Brave Search Setup

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.

Security Scan

The skill's instructions, helper script, and requested actions align with its stated purpose of configuring a Brave Search API key and setting up a local proxy for OpenClaw web tools; there are no unexplained credential requests or hidden network endpoints.

Purpose & Capability

The skill's name/description match the actual instructions: it shows how to add a Brave Search API key to OpenClaw config, test web_search/web_fetch, detect local proxy ports (Clash/V2Ray/Surge), set HTTPS_PROXY/HTTP_PROXY, and restart the OpenClaw gateway. There are no unrelated credentials, binaries, or external endpoints required beyond the Brave Search API and common tools.

Instruction Scope

The SKILL.md includes commands that read/write local OpenClaw config (~/.openclaw/openclaw.json), inspect a Clash YAML under the user's Library, set environment variables via launchctl or shell profile, and suggests installing/running proxychains-ng with sudo. These actions are consistent with troubleshooting network/proxy issues, but they will change local shell config, environment, and may store the API key in OpenClaw config (potentially plaintext). Users should be aware the skill directs edits to user files and requires restarting the gateway process.

Install Mechanism

This is an instruction-only skill with a small helper script (scripts/detect-proxy.sh) that scans local ports and reads a Clash config path. There is no install spec, no downloads, and no extracted archives; the script content is simple shell logic and appears benign.

Credentials

The skill does not declare or require external environment variables or credentials beyond the Brave Search API key (which the instructions ask you to place into OpenClaw config). It asks the user to set standard HTTPS_PROXY/HTTP_PROXY env vars to route traffic through a local proxy — appropriate for the stated goal. Note: storing API keys in config files can expose them if files are not protected.

Persistence & Privilege

The skill does not request permanent platform privileges (always:false) and does not modify other skills. It instructs restarting the OpenClaw gateway and setting user-level environment variables (launchctl or shell profile), which is expected for proxy propagation but is a system-level change the user must consciously approve.

Assessment

This skill appears coherent and focused on setting a Brave Search API key and configuring a local proxy for OpenClaw tools. Before running commands: 1) Back up your OpenClaw config (~/.openclaw/openclaw.json) so you can restore it if needed. 2) Prefer using openclaw gateway config.patch (the doc's 'Option A') rather than editing files directly if you want the platform to manage formatting; confirm where/how your API key will be stored (it may be plaintext in config). 3) Review scripts/detect-proxy.sh yourself — it only scans local ports and a known Clash config path. 4) Be cautious when adding exports to shell profiles or running sudo to install proxychains-ng (these change your environment or require elevated privileges). 5) If unsure about exposing your API key or making system changes, run the discovery/test commands manually and ask for help rather than applying the suggested permanent changes.

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 <<EOF
strict_chain
proxy_dns
[ProxyList]
http 127.0.0.1 7897
EOF

# 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