Tools, Skills & MCP — Extending OpenClaw

## Understanding Skill Directories OpenClaw loads skills from these locations in order of precedence: 1. <workspace>/skills — your workspace (highest priority) 2. ~/.clawdbot/skills/ — managed overrides 3. Bundled skills (lowest priority) Common mistake: Placing skills in ~/clawd/skills/ when OpenClaw expects ~/.clawdbot/skills/.

# Move skills to correct locationmv ~/clawd/skills/my-skill ~/.clawdbot/skills/# Or configure custom skills directory in clawdbot.json

{  "skills": {    "dir": "/path/to/your/skills",    "entries": {      "my-skill": {        "enabled": true      }    }  }}

## Configuring Web Search Providers OpenClaw supports two search providers: Brave (default) and Perplexity. Note: Google is NOT supported. Perplexity provides AI-synthesized answers with citations, which is often preferred over raw search results.

# Configure via CLIclawdbot configure --section web

// Or manually in clawdbot.json:{  "tools": {    "web": {      "search": {        "provider": "perplexity",        "perplexity": {          "apiKey": "your-perplexity-api-key",          "model": "perplexity/sonar-pro",          "baseUrl": "https://api.perplexity.ai"        }      }    }  }}

# Or use environment variablesexport PERPLEXITY_API_KEY="pplx-xxxxx"# Can also route through OpenRouter:export OPENROUTER_API_KEY="sk-or-xxxxx"

## Fixing 'HTTP 400: tool_call_id is not found' Errors This error typically cascades and breaks all subsequent messages. The gateway is in a corrupted state.

# Immediate fix — restart the gatewayclawdbot gateway restart# Check logs for root causeclawdbot gateway logs# If error persists, check for deleted/expired messagesclawdbot logs

If errors continue after restart: - Note the exact message content that triggers it - Check if original messages still exist in chat - May indicate race condition from rapid responses

## Fixing Skill OAuth Token Expiry (gog, etc.) Google OAuth tokens expire after ~1 hour. The refresh mechanism sometimes fails silently.

# Force fresh token with consent screengog auth add you@gmail.com --force-consent# Or remove and re-addgog auth remove you@gmail.comgog auth add you@gmail.com# Verify tokens are validgog auth list --check

## Setting Up gog (Google Workspace) Skill The gog skill requires manual setup beyond just enabling it.

# 1. Install the CLIbrew install steipete/tap/gogcli# 2. Set up OAuth credentials (get from Google Cloud Console)# Create OAuth 2.0 Client ID, download client_secret.json# Add redirect URI: http://localhost:8080/oauth/callbackgog auth credentials /path/to/client_secret.json# 3. Authenticate with servicesgog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs# 4. Set default account (optional)export GOG_ACCOUNT=you@gmail.com# 5. Verifygog auth list

## Fixing 'Tool X not found' After Initial Success If skills work initially but later show 'Tool not found':

# 1. Check skill directory configurationclawdbot config get skills.dir# 2. Verify skills are loadedclawdbot skills list# 3. Check skill logsclawdbot gateway logs | grep -i skill# 4. Restart gateway to reload skillsclawdbot gateway restart

## Fixing Undici Errors During Skill Installation Node version managers (nvm, fnm, volta, asdf) are intentionally excluded from the daemon's PATH because they require shell initialization.

# Option 1: Use system Node instead of nvmsource ~/.nvm/nvm.shnvm use systemnpx clawdhub@latest# Option 2: Use official installer (recommended)curl -fsSL https://clawd.bot/install.sh | bash# Option 3: Fix npm global permissions (Linux)mkdir -p ~/.npm-globalnpm config set prefix '~/.npm-global'export PATH=~/.npm-global/bin:$PATHnpx clawdhub@latest

## Fixing Session Bloat & Tool Drift As sessions grow, tool schemas get buried and tools become unreliable. Classic symptom: works fresh, degrades over time.

Prevention: - Keep sessions shorter, start fresh when tools drift - Use /molt or clawdbot molt to clear session state - Monitor session size — anything over 1MB is problematic - Document working workflows in persistent locations (MEMORY.md, not TOOLS.md) Note: TOOLS.md is for YOUR notes about tools (camera names, SSH aliases). Procedures should go in MEMORY.md or documentation folders.

## SKILL.md Frontmatter Format Incorrect indentation in SKILL.md causes skills to fail loading.

---name: my-skilldescription: Description of what the skill does.metadata: {"clawdbot":{"emoji":"🔧","requires":{"bins":["node"],"env":["MY_API_KEY"]},"primaryEnv":"MY_API_KEY"}}---**Important:** No leading spaces on frontmatter lines!

## Browser Automation Reliability Browser automation (TheFork booking, form filling) can freeze or fail. This depends on: - Model capability (use Sonnet 4 or GPT-5 for complex tasks) - SKILLS.md quality and context - Site complexity (heavy JS sites are harder) Tips: - Use cliclick skill for cursor control if standard browser actions fail - Break complex tasks into smaller steps - Verify each step before proceeding