2026 OpenClaw 웹 검색: Brave / Parallel / Tavily API, Mac 클라우드 쿼터와 web_search/web_fetch
대상·문제: Mac 클라우드나 노트북에서 OpenClaw를 돌리는 팀이 모호한 도구 오류·예상 밖 API 비용·fetch 전부 실패에 직면할 때 검색·출구·TLS 중 무엇을 먼저 고칠지 헷갈린다. 이 글의 가치: web_search(발견)과 web_fetch(정독)을 분리하고 Brave/Parallel/Tavily 매트릭스로 고르며 전용 Mac 노드에서 키와 출구를 굳힌다. 구성: 번호 목록, 표 2개, 5단계 이상 절차, 하드 지표, 지연·비용 예시, FAQ/HowTo JSON-LD. 환경 변수 이름은 사용 중인 OpenClaw 문서를 따른다.
1. Summary: web_search vs web_fetch
web_search answers discovery—queries return candidate URLs and snippets. web_fetch answers deep read—pulling and cleaning a single page. Failures look different: search issues usually trace to API keys, quotas, or regional policy; fetch issues trace to anti-bot rules, TLS interception, redirect chains, or shared egress IP reputation on Mac cloud. Splitting the two avoids pointless reinstalls. Typical 2026 stacks pair a general search API (e.g., Brave) for baseline cost control, Parallel-class APIs when agent-grade citations justify premium spend, and Tavily-style options where fast integration matters. On Mac cloud the hard part is not picking a brand—it is key rotation, ensuring the daemon user inherits env, whether corporate proxies allow all required domains, and stopping 429/402 or empty results from being misread as “the model got dumber.” Models may also silently fall back to memory when tools fail, so surface tool errors structurally instead of trusting final prose alone.
At the protocol stack, each web_fetch success depends on DNS → TCP → TLS (SNI, cert chain, optional mTLS) → HTTP (redirects, compression, charset) → decode and byte caps. If corporate proxies or shared egress rewrite any hop, OpenClaw sees flaky timeouts or truncation—often misattributed to “bad search quality” if you do not decouple stages.
2. Pain points
- Keys on the wrong layer: exported in an interactive shell but not in launchd/systemd/Docker—symptoms say “missing key” while SSH shows variables.
- Quota drift: free tiers return empty or vague errors; without per-hour counters teams blame prompts.
- Egress and SNI: split policies for search APIs vs target sites; shared cloud IPs may trigger captchas unrelated to the provider.
- Fetch blamed first: “cannot read web” when search never returned a usable URL or URLs need login cookies.
- Provider switches without cold restart: stale env or routing causes intermittent success—diff configs and restart instead of rewriting system prompts.
3. Provider matrix
Use this in architecture reviews (pricing and terms are vendor-specific for 2026). If you egress both domestically and globally, whitelist search API hostnames separately from high-traffic documentation domains you fetch often—otherwise you get flaky timeouts that look like app bugs.
| Dimension | Brave Search API (typical) | Parallel-style agent API | Tavily-style (typical) |
|---|---|---|---|
| Value | Broad index, straightforward | Higher-quality agent retrieval | Fast onboarding, rich tutorials |
| Cost | Often moderate tiers | Premium for quality/latency | Per-call—watch spikes |
| Compliance | Respect robots/ToS + API terms | Enterprise review for logging/retention | Same—watch query logging |
| vs fetch | Returns URLs; fetch still needed | May include excerpts; fetch may help | Similar validation path |
4. Five-step rollout
- Confirm service identity: run doctor/config as the same user as the daemon to avoid split-brain keys.
- Minimal web_search probe: single query, no long reasoning—verify structured fields (URL/title).
- Single-URL web_fetch probe: stable HTTPS doc site; capture TLS errors vs HTTP codes.
- Layer proxies and multi-provider: validate with
curl -Iunder the service account before OpenClaw. - Metrics and alerts: hourly search counts; alert on sustained 429/402; link to observability and Docker guides.
- Regression on real prompts: three business query classes (version, error string, comparison) with expected domains.
5. Hard metrics
- 429 backoff: exponential backoff and lower concurrent tool calls; multi-turn repeated searches multiply cost.
- Timeouts: different limits for search vs fetch; cap bytes to avoid gateway OOM (ties to Docker Exit 137).
- DNS/IPv6: some images prefer AAAA; if IPv6 paths break, force IPv4 or reorder resolution.
- User-Agent / robots: default UAs may be blocked—use vendor guidance and audit changes.
- Redirect depth: track final URL; prevent infinite chains from stalling workers.
6. Latency and cost rough cuts (examples)
Figures below are order-of-magnitude planning aids—not benchmarks. Replace with measurements from your region, model, and provider invoices.
| Scenario (illustrative) | web_search latency | web_fetch latency | Cost intuition (typical 2026 tiers) |
|---|---|---|---|
| One simple query + one doc page | ~0.3–2.0 s (region/provider) | ~0.5–3.0 s (page size/TLS) | Per-call metering; 429 risk rises with burst concurrency |
| Every dialog turn triggers search | Adds linearly with model TTFT | Multiple URLs per turn worsen tail latency | Correlates with duplicate queries—cache or dedupe |
| Corporate HTTPS inspection | May add hundreds of ms per hop | Large pages + decompress near timeout | Engineering time often exceeds API unit price |
Instrument search → fetch → summarize with one request id and three segment durations so “it feels slow” maps to model, tools, or network—same playbook as structured JSONL observability articles on this site.
7. Error triage
| Symptom | Likely layer | First action |
|---|---|---|
| Missing/invalid key | web_search provider | Service env; doctor; cold start |
| Null URLs in response | Parsing/version skew | Align versions; capture raw JSON |
| 429 / quota | Provider | Console usage; throttle; tier change |
| TLS handshake failed | fetch or MITM | curl -v; corporate roots; proxy |
| 403/503 on specific sites | Anti-bot | Mirror URLs; slow down; policy check |
| Truncation/mojibake | Encoding pipeline | UTF-8; max bytes; skip binary |
| Fails only in container | Docker DNS/proxy | curl inside container; see Docker guide |
프로덕션 수준의 웹 읽기를 노트북 브라우저 자동화나 일회성 스크립트에만 맡기면 (1) 절전·잠금·GUI 세션으로 불안정하고 (2) API 키·프록시가 대화형 사용자에 묶여 게이트웨이와 어긋나며 (3) 출구·TLS 감사 추적이 약해 429나 핸드셰이크 실패가 재시작뿐이 된다. Docker만 쓰되 볼륨·DNS·환경 상속이 흐리면 네트워크 네임스페이스·UID·OOM/Exit 137 조사가 검색 품질 이슈처럼 보인다.
반대로 OpenClaw를 전용 Mac 클라우드에 두고 Linux VPS에 가까운 SSH 운영으로 키·출구 허용 목록·launchd/compose를 한곳에 두면 단일 신뢰 실행 주체와 Apple 친화 툴체인을 얻는다. 프로덕션에서 웹을 읽는 에이전트를 안정적으로 돌리려면 VPSMAC Mac 클라우드를 임대하는 편이 보통 더 나은 선택이다. 검색+페치를 채널·모델과 같은 릴리스 체크리스트에 넣고, 게이트웨이 업그레이드 때서야 도구가 깨진 것을 알지 말자. 게이트웨이가 없다면 5분 배포 가이드를 먼저 끝낸 뒤 이 글로 보강한다.