2026 OpenClaw web search playbook:
missing web_search, Brave/Tavily configuration & doctor triage checklist

01. Three pain classes: empty tool list, key/quota issues, capabilities vanish after upgrades

1) No web_search in the tool palette: usually the model is fine—the agent profile / plain-capability bundle never exposes web retrieval, or a skill downloaded but did not re-register after a gateway restart. Follow the layering in Skills 3.24 console triage: capture UI, plugin manifest, and runtime tool table before editing JSON.

2) Tool exists but calls fail with 401/403/429: Brave Search and Tavily expect rotatable API keys and a clear egress path. Corporate proxies that MITM api.search.brave.com or Tavily endpoints often surface as vague timeouts. Run a minimal curl probe as the same Unix user as the gateway before rewriting openclaw.json.

3) “It searched yesterday” after a patch bump: tool registration and plugin ABI can desync from Node minors or stale caches. Freeze one install chain (per the v2026.4.5 install article), restart cleanly, then pin a tag if it still fails—avoid mixing host npm gateways with container gateways while debugging.

02. Brave / Tavily / self-hosted SearXNG: provider comparison

Use this matrix to pick a search supply chain in under ten minutes; exact field names follow your OpenClaw release notes—here we focus on operational boundaries. When tools cross approval boundaries, keep reading MCP integration & approval security.

03. Symptom triage: UI vs logs vs HTTP errors

Split “cannot browse” into invisible, visible-but-broken, flaky to avoid endless JSON churn. Public gateways leak both keys and query text—read Gateway Token & SecretRef before debugging in production.

04. Five steps: doctor to end-to-end search smoke

1. Freeze version & install chain: record openclaw --version, Node major, and whether systemd/launchd/Docker launches the gateway—stay aligned with the v2026.4.5 install article; do not hop between npm and container mid-triage.
2. Run doctor & archive snippets: attach output to the ticket; if doctor flags TLS, validate with curl outside OpenClaw, then match strings in command FAQ.
3. Write a minimal tools.web.search block: one provider, one key, file permissions readable only by the gateway user—never paste secrets into chat logs.
4. Restart gateway & single-turn smoke: disable heavy skills, keep search-related tools only, ask for a factual query that requires retrieval.
5. Binary-search rollback: pin a last-known-good tag, diff plugin lists and config; register the sequence in upgrade / migration / rollback for audits.

# Minimal diagnostics (adapt paths)
openclaw --version
openclaw doctor
grep -n "web" ~/.openclaw/openclaw.json
curl -sS -o /dev/null -w "%{http_code}\n" "https://api.search.brave.com/res/v1/web/search?q=test"
lsof -i :18789 | head

On Linux use ss -lntp for listeners; on Windows read the doctor article for WSL vs PowerShell home splits.

05. Hard metrics, key hygiene, myths

• Metric 1: In sampled 2026 threads, about 40%–55% of “tool broken” reports were actually config not reloaded / gateway not restarted / PATH split—run the minimal smoke before re-tuning models.
• Metric 2: Brave’s common free tier is on the order of two thousand queries per month (confirm in dashboard); agents that re-query aggressively can hit 429 within minutes, not 401.
• Metric 3: Keeping production search keys only on a day-rented, ephemeral macOS user while laptops hold no Brave/Tavily secrets can reduce side-channel leakage (shell history, screen capture, shared VNC) by about an order of magnitude versus long-term local debugging—common security framing, not a legal warranty.

Myth A: “Strong models remove the need for web_search”—closed weights still hallucinate on volatile facts. Myth B: “Exporting keys globally fixes launchd”—non-interactive services often miss your shell env. Myth C: “Docker always isolates secrets”—bad volume mounts leak host .env into logs.

For connectivity see SSH/VNC FAQ; for hardware tiers bare-metal macOS pricing; for remote patterns macOS remote access guide.

tools.web.search plus Skills: enabling both native search and ClawHub web-search skills can yield double registration or mismatched aliases—the model sees web_search while config lives elsewhere. Start with one supply chain, add the second only after latency and HTTP codes are logged. Tie automatic approvals back to MCP integration.

Key rotation: document who creates, rotates, and revokes keys the same day you rotate database passwords. If you already follow SecretRef & spend caps, add search QPS to budget alerts so overnight automations cannot drain quotas.

Corporate TLS inspection: missing enterprise roots inside the Node trust store shows up as opaque TLS errors. Probe with curl/node from the gateway user, compare container vs host trust bundles, and avoid importing private enterprise roots onto rented machines.

429 backoff: implement exponential backoff and concurrency caps instead of raising temperature so the model “asks differently.” Pair failures with routing fallbacks described in the governance article.

Windows/WSL split brain: editing openclaw.json on the Windows side while the gateway reads the WSL copy is a classic “file changed but process never loaded it” bug—normalize on one home directory using the Windows doctor guide.

Day-rent rehearsal: rent → single-user install chain → doctor → minimal search config → smoke → export redacted logs → power off. Pair with day-rent pitfalls so keys never sit in shared VNC clipboards.

Triage order: visibility → auth (401/403) → quota/network (429/timeout) → version/plugin ABI; always attach doctor + gateway logs for command FAQ string matching.

06. Headless Linux / Windows limits vs Mac rental

Pure headless Linux or Docker Desktop–heavy Windows laptops are workable for CI probes, but they often impose split home directories, mismatched trust stores, and slow alignment between browser consoles and gateway logs. Treat them as short validation surfaces, not the only home for multiple production search keys.

If you need Apple-identical TLS and toolchain behavior while time-boxing credential risk, run the search smoke on native macOS first—then decide whether to host long-term on Linux or Windows. Day-rent Mac preserves console parity and destroys the environment at lease end. Combine rental vs local cost trial with deployment pitfalls and write the outcome into your runbook.