You already run OpenClaw on a remote Mac, but answers still feel “offline” until you wire first-class web search. In 2026 the stack treats search as a tool family: web_search for broad queries and web_fetch for single URLs, with optional Firecrawl fallback when pages are JS-heavy or bot-hostile. This guide is not the v2026.3.28 plugin approvals deep dive nor the browser MCP tutorial—it focuses on provider choice, enablement order, API keys, allowlists, /approve interactions, quota/429 handling, empty results, and log triage, plus a VNC checklist so you can see Gateway consoles and macOS prompts that SSH hides. Cross-read silent no-reply triage and launchd daemon stability when search works but the agent still goes quiet.
Readers here typically paste docs into chat instead of trusting retrieval, hit rate limits after the first demo, or see “web search disabled” despite a key in .env. The fix is rarely one toggle: it is a sequence—doctor baseline, interactive openclaw configure --section web or JSON under tools.web, environment or SecretRef secrets, agent allowlists, channel test, approval surfaces, then structured downgrade when the network says no.
Who this is for and boundaries
This article is for operators who already ship OpenClaw on macOS and need reliable public-web retrieval—not for first-time binary installs. It complements plugin-approval and browser-MCP posts by isolating search providers, quotas, and failure signatures.
If you are still proving SSH connectivity, finish the first-connection checklist for your platform before tuning search. Once search is on the critical path, treat it like any other production dependency: version the configuration, record which agent profile is active, and keep a rollback path to a narrower tool allowlist when incidents strike.
Pain points and scope boundaries
- Tool confusion: Browser MCP drives a real Chrome profile; built-in search calls provider APIs. Mixing the two without boundaries doubles spend and creates conflicting citations.
- Allowlist drift: Upgrades may ship new tool names. If
web_searchorgroup:webis missing from the active profile, the model will hallucinate browsing. - Secrets placement: Keys only in a local shell export do not always reach launchd services; SecretRef and service env must match how your Gateway actually starts.
- Approval deadlocks: requireApproval hooks can stall search until /approve clears—especially on Telegram/Discord overlays; see the approvals article for your channel.
- Quota shape: 429 bursts often follow parallel sub-agents or retries; fix concurrency before blaming the provider.
- Empty hits: Strict site filters, language hints, or regional SERPs can return zero rows while logs still show HTTP 200—treat as a query tuning problem.
- Observability gaps: If logs only show the model transcript, you may never see the tool HTTP status. Enable Gateway/tool traces that include provider names, latency, and status codes before opening vendor tickets.
- Multi-tenant bleed: Shared API keys across staging and production make 429s impossible to attribute. Partition keys per environment and label canary traffic in your orchestration layer.
Logs, policy surfaces, and runbooks that survive upgrades
Split web_search, web_fetch, and crawl fallbacks
Users say “search is broken” when the failure is actually a fetch timeout, a TLS MITM appliance, or a Firecrawl quota on a different code path. Before swapping vendors, tag one conversation or request ID and follow the tool span end-to-end: provider name, HTTP code, retry count, and whether the model retried in parallel. Mixing traces from multiple sub-agents is the fastest way to misread a 429 as an auth problem.
Corporate egress and DNS that mimic quota issues
Split-horizon DNS, captive portals, and inspected TLS can return empty bodies with HTTP 200 or stall long enough to look like provider throttling. Document the Gateway host’s egress next to your provider matrix. On a remote Mac over VNC, validate that Safari or curl from the same user context as the service can reach the provider endpoint—SSH sessions and launchd services do not always share identical environment or proxy settings.
Runbook order: PID env → allowlist diff → minimal replay → concurrency
Standardize triage: confirm environment variables visible to the running Gateway PID, diff the effective allowlist against release notes (new tool names appear often), replay the smallest possible query outside the LLM if policy allows, then reduce parallel tool calls and sub-agents. Rotating API keys rarely fixes a missing group:web entry after an upgrade, yet teams burn hours doing exactly that.
Cost and safety guardrails beyond the vendor dashboard
Dashboards show monthly totals; agents show burst traffic. Combine provider caps with orchestration-side limits: maximum parallel searches per conversation, deduplication of near-duplicate queries, and explicit “no search” modes for sensitive channels. Pair those limits with audit notes in SOUL/MEMORY so future you knows why a stricter allowlist exists.
Search provider decision matrix (indicative)
| Provider pattern | Good when | Watch outs |
|---|---|---|
| Brave Search (common default) | General web, privacy-minded defaults | Watch monthly caps; verify model allows citations you need |
| Tavily / AI search APIs | Structured JSON snippets for agents | Paid tiers; tune include_domains to avoid noise |
| Perplexity-style stacks | Answer synthesis with links | Higher cost; confirm citation format matches your compliance story |
| Gemini / Google keys | You already standardize on Google AI billing | Keep keys out of repo; rotate with SecretRef workflow |
| Firecrawl on fetch path | Single URL extraction behind anti-bot pages | Separate quota from search; failures map to fetch not search |
| Bing / broader SERP APIs | You need classic blue-link coverage or region-specific results | Map compliance and caching rules; some stacks forbid storing raw SERP payloads |
| Self-hosted retrieval | Air-gapped or policy-blocked public search | You own uptime, freshness, and embedding pipelines—do not pretend it is “free search” |
Nine-step enablement and verification ladder
Freeze a doctor baseline
Run openclaw doctor and capture anything mentioning web, search, or tools. File the output with your version string so upgrades are comparable.
Run the web configuration wizard
Execute openclaw configure --section web and pick a provider. If you prefer files, mirror the same fields under tools.web.search in ~/.openclaw/openclaw.json—never commit API keys.
Wire secrets the way your daemon loads them
Export TAVILY_API_KEY, BRAVE_API_KEY, PERPLEXITY_API_KEY, or provider-specific vars in the plist/env that launchd uses; validate with a reboot test.
Allowlist tools for the active agent profile
Ensure web_search (and web_fetch if you need pages) appears in the effective allowlist or group:web equivalent for your build.
Send a canary query from a real channel
Ask for a timeboxed fact that requires the public web—not your repo. Watch Gateway logs for tool invocation latency and error classes.
Clear approval gates deliberately
If policy wraps before_tool_call, approve via the channel-native surface, then re-run once to confirm cache behavior.
Triage failures in order
HTTP 401/403 → key or ACL; 429 → backoff and concurrency; timeouts → network path; empty JSON → loosen filters; TLS MITM → corporate proxy documentation.
Capture a reproducible trace package
Export redacted logs, the active openclaw.json fragment for tools.web, and the allowlist snippet—without secrets—for every incident. Future upgrades compare cleanly against this baseline.
Define a degraded mode
Pre-approve text that tells users search is temporarily read-only or capped, disable sub-agents, and switch to smaller models if your policy allows. Degraded mode should be boring and documented, not improvised during an outage.
Citable operating notes
openclaw doctor before and after provider changes; attach diff to tickets to avoid mismatched environments.Checkbox checklist before opening a ticket
- Doctor output archived with version
- Provider block present in JSON or wizard transcript
- Effective allowlist contains web tools
- Secrets visible to the running Gateway process
- Canary query reproduced from the same channel users rely on
VNC remote Mac: console, permissions, and split-brain checks
Open the Gateway UI on the remote Mac while tailing logs over SSH. Align clocks, confirm no proxy intercepts tool HTTPS, and verify menu-bar companion state if your build uses it. When macOS shows consent for network extensions or automation, approve through the graphical session—SSH-only operators often miss these and blame search providers.
Use the graphical session to open Keychain Access or your secret manager UI when validating that the same credentials your launchd plist references are actually present and not expired. If your workflow mixes local Terminal tests with production services, keep two browser windows: one logged in as the operator, one reflecting the service account context, so you do not “prove” connectivity with the wrong identity.
Related posts
Approvals: plugin approvals & Grok. Browser automation: Chrome DevTools MCP. Silence: no-reply triage. Uptime: launchd daemon checklist.
FAQ
- Why does the UI still say web search is disabled? Usually missing allowlist entry, provider block, or keys not loaded into the Gateway environment. Re-run doctor after fixing env, not before.
- Do I need Firecrawl if search already works? No—Firecrawl commonly backs
web_fetchfor tough pages. Keep budgets separate and monitor fetch errors distinctly from search. - How do I handle 429 without swapping vendors? Reduce parallel agents, add exponential backoff in your workflow, cache recent queries at the orchestration layer, and widen quota with the same provider if available.
- Is browser MCP safer than search APIs? Different threat model: MCP may touch logged-in sessions; search APIs touch the public index. Pick per task and document both in SOUL/MEMORY files.
- Why do results differ between my laptop test and the remote Mac? Different DNS, proxy PAC files, system language/region, and even IPv6 preference change SERPs. Always reproduce from the Gateway host.
- Should I cache search results inside the agent workspace? Only with a retention policy that matches compliance. Cached SERPs go stale quickly; prefer short TTLs and store provider metadata for audits.
Closing
Linux VMs and headless servers hide the consent and console surfaces that search tooling frequently needs, and they make it easy to run tests under the wrong user context. A real macOS desktop accessed over VNC preserves the full chain from API key load to Gateway overlays, which matters the moment approvals, Keychain prompts, or browser-adjacent debugging enter the story. For short engagements, renting a VNC-ready Mac from VNCMac plus the linked checklists typically costs less time than chasing partial logs on the wrong host shape—especially when your runbook assumes you can see the same screen your production agent does.