Brave Search Setup

---

name: brave-search-setup description: Configure Brave Search API and troubleshoot network/proxy issues for web_search functionality. Use when user needs to (1) Set up Brave Search API key, (2) Fix web_search fetch failures, (3) Configure proxy for OpenClaw tools on macOS with Clash/V2Ray/Surge, or (4) Diagnose "fetch failed" errors with web_search/web_fetch tools.

---

Brave Search Setup & Proxy Configuration

Setup Brave Search API and resolve network connectivity issues for OpenClaw web tools.

Prerequisites

Brave Search API key (get from https://brave.com/search/api/)

OpenClaw CLI installed

macOS with proxy client (Clash/V2Ray/Surge) if behind GFW

Quick Setup

Step 1: Configure API Key

# Option A: Via config.patch (key will be stored securely)
openclaw gateway config.patch --raw '{"tools":{"web":{"search":{"apiKey":"YOUR_BRAVE_API_KEY","enabled":true,"provider":"brave"}}}}'

Or edit ~/.openclaw/openclaw.json directly:

{
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "provider": "brave",
        "apiKey": "YOUR_BRAVE_API_KEY"
      }
    }
  }
}

Step 2: Test Without Proxy

openclaw web.search --query "test" --count 1

If works → Done. If "fetch failed" → Continue to proxy setup.

Proxy Setup (macOS)

Step 3: Detect Proxy Port

Common proxy ports by client:

Clash: 7890 (HTTP), 7891 (SOCKS5), 7897 (mixed-port)

Surge: 6152, 6153

V2Ray: 1080, 10808

Detect actual port:

# Check if Clash is running
ps aux | grep -i clash
Find mixed-port from Clash config
cat "~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/clash-verge.yaml" | grep mixed-port
Or test common ports
for port in 7890 7891 7897 6152 6153 1080 10808; do
  if nc -z 127.0.0.1 $port 2>/dev/null; then
    echo "Port $port is open"
  fi
done

Step 4: Set System Proxy

Method A: launchctl (Recommended - survives restart)

# Set for current session and future sessions
launchctl setenv HTTPS_PROXY http://127.0.0.1:7897
launchctl setenv HTTP_PROXY http://127.0.0.1:7897

Method B: Shell export (Session only)

export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897

Method C: Add to shell profile (Permanent)

echo 'export HTTPS_PROXY=http://127.0.0.1:7897' >> ~/.zshrc
echo 'export HTTP_PROXY=http://127.0.0.1:7897' >> ~/.zshrc
source ~/.zshrc

Step 5: Enable Gateway Restart

openclaw gateway config.patch --raw '{"commands":{"restart":true}}'

Step 6: Restart Gateway with Proxy

# Restart to pick up proxy env vars
openclaw gateway restart
Or use SIGUSR1
kill -USR1 $(pgrep -f "openclaw gateway")

Step 7: Verify

# Test web search
openclaw web.search --query "Brave Search test" --count 1
Test web fetch
openclaw web.fetch --url "https://api.search.brave.com" --max-chars 100

Troubleshooting

"fetch failed" but proxy works in browser

Symptom: Browser can access Google, but OpenClaw tools fail. Cause: Gateway process started before proxy env vars were set. Solution: Restart Gateway after setting HTTPS_PROXY.

Permission denied on Gateway restart

Enable restart command:

openclaw gateway config.patch --raw '{"commands":{"restart":true}}'

API key errors

Verify key is set:

openclaw gateway config.get | grep -A5 'web.*search'

Test directly with curl:

curl -s "https://api.search.brave.com/res/v1/web/search?q=test&count=1" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: YOUR_API_KEY"

Mixed-port vs dedicated ports

Clash "mixed-port" (default 7897) handles both HTTP and SOCKS5. If using dedicated ports:

HTTP proxy: 7890

SOCKS5 proxy: 7891 (requires different handling)

Advanced: Per-Tool Proxy

Not all tools respect HTTPS_PROXY. For tools that don't:

# Use proxychains-ng
brew install proxychains-ng
Configure
sudo tee /usr/local/etc/proxychains.conf <
Run with proxy
proxychains4 openclaw web.search --query "test"

Workflow Summary

1. Configure API key → config.patch or edit JSON 2. Test → If fails, proxy needed 3. Detect port → Check Clash/Surge config 4. Set env vars → launchctl setenv or shell export 5. Restart Gateway → openclaw gateway restart 6. Verify → Run test search

References

Brave Search API Docs: https://api.search.brave.com/app/docs

OpenClaw Config: https://docs.openclaw.ai/config

Clash Verge: https://github.com/clash-verge-rev/clash-verge-rev

Brave Search API key (get from https://brave.com/search/api/)

OpenClaw CLI installed

macOS with proxy client (Clash/V2Ray/Surge) if behind GFW

"fetch failed" but proxy works in browser

Symptom: Browser can access Google, but OpenClaw tools fail. Cause: Gateway process started before proxy env vars were set. Solution: Restart Gateway after setting HTTPS_PROXY.

Permission denied on Gateway restart

Enable restart command:

openclaw gateway config.patch --raw '{"commands":{"restart":true}}'

API key errors

Verify key is set:

openclaw gateway config.get | grep -A5 'web.*search'

Test directly with curl:

curl -s "https://api.search.brave.com/res/v1/web/search?q=test&count=1" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: YOUR_API_KEY"

Mixed-port vs dedicated ports

Clash "mixed-port" (default 7897) handles both HTTP and SOCKS5. If using dedicated ports:

HTTP proxy: 7890

SOCKS5 proxy: 7891 (requires different handling)