2026 OpenClaw ウェブ検索構成：Brave / Parallel / Tavily API、Mac クラウドのクォータと web_search/web_fetch トラブルシュート
誰が・何に困るか： Mac クラウドやノート上で OpenClaw を動かすチームが、曖昧なツールエラー・想定外の API 請求・「fetch が全部赤」のとき、検索・出口・TLS のどれを先に直すべきか迷う。得られるもの：web_search（発見）と web_fetch（精読）を分離し、Brave / Parallel / Tavily をマトリクスで選び、専用 Mac ノード上でキーと出口を固める。構成：番号付き痛点、二つの表（プロバイダ＋トリアージ）、5 ステップ以上の導入、ハード指標、遅延・コスト粗見積り、FAQ/HowTo JSON-LD。環境変数名は利用中の OpenClaw 版ドキュメントに合わせること。
目次
1. 要約：web_search と web_fetch
web_search はクエリから URL とスニペットを返す発見層、web_fetch は 1 ページを取得・正規化する精読層。失敗の形が異なる：検索は API キー・クォータ・リージョン政策、取得はボット対策・TLS 改ざん・リダイレクト・共有出口 IP の評判など。分離して初めて無駄な再インストールを避けられる。2026 年はコスト重視で Brave 系、引用品質で Parallel 系、素早い PoC で Tavily 系、といった併用が一般的。Mac クラウドではブランド選びより キーローテーション、デーモンユーザーへの環境変数継承、企業プロキシのドメイン許可、429/402 や空結果をモデル劣化と誤認しないことが本丸。ツール失敗をモデルが黙って埋め合わせることもあるため、最終テキストではなく構造化ログで可視化する。
web_fetch は DNS→TLS→HTTP の連鎖。企業プロキシや共有出口がいずれかを書き換えるとタイムアウトや断片化に見え、検索品質のせいにしがちなので段階を切り分ける。
2. よくあるつまずき
- キーが層違い：対話シェルに export があるが launchd/systemd/Docker に無い。SSH では見えるのにゲートウェイは「キーなし」。
- クォータのズレ：無料枠枯渇で空や曖昧なエラー。時間あたりカウントが無いとプロンプトのせいにする。
- 出口と SNI：検索 API と取得先でポリシーが違う。共有 IP はキャプチャや 403 を誘発しプロバイダ起因ではない。
- fetch のみ調整：検索が使える URL を返していない／ログイン Cookie が要る URL なのに取得側だけいじる。
- プロバイダ切替後に冷起動しない：環境やルートが古く、断続的成功。プロンプトではなく diff と再起動。
3. プロバイダマトリクス
アーキレビュー用（料金・条項は各社 2026 年版で確認）。国内外の出口があるなら 検索 API ホスト名 と 高頻度で fetch するドキュメントドメイン を別ホワイトリストにしないと、アプリバグに見える断続タイムアウトが出る。
| 観点 | Brave Search API（典型） | Parallel 系エージェント API | Tavily 系（典型） |
|---|---|---|---|
| 価値 | 広いインデックス、素直 | エージェント向け品質 | オンボードが速い |
| コスト | 中位ティアが多い | 品質・遅延でプレミアム | 従量、スパイク注意 |
| コンプライアンス | robots/ToS と API 条項 | ログ保管は企業レビュー | クエリログに注意 |
| fetch との関係 | URL 列挙後に取得 | 抜粋あり得る | 同様に検証 |
4. 導入手順（5 ステップ以上）
- サービス同一性：デーモンと同じユーザーで doctor/config を実行し、キーの二重人格を防ぐ。
- 最小 web_search プローブ：単一クエリ、長い推論なしで URL/タイトル等の構造を確認。
- 単一 URL の web_fetch：安定した HTTPS ドキュメントで TLS と HTTP コードを切り分け。
- プロキシと複数プロバイダ：OpenClaw の前にサービスユーザーで
curl -Iを通す。 - メトリクスとアラート：時間あたり検索回数、連続 429/402。可観測性・Docker 文書と Runbook 化。
- 実プロンプト回帰：バージョン／エラー文字列／比較の 3 系で期待ドメインを断言。
5. ハード指標
- 429 とバックオフ：指数バックオフとツール同時実行の削減。多ターンで同検索を繰り返すとコストが数倍。
- タイムアウト：検索と取得で別上限。バイト上限でゲートウェイ OOM（Docker Exit 137）を避ける。
- DNS/IPv6：AAAA 優先で壊れるなら IPv4 固定や順序変更。
- User-Agent / robots：デフォルト UA が拒否され得る。ベンダー推奨と変更監査。
- リダイレクト深さ：最終 URL を記録し無限連鎖を止める。
6. 遅延・コスト粗見積り（例）
以下はオーダー感の計画用でベンチマークではない。リージョン・モデル・請求で実測し置き換えること。
| シナリオ（例） | web_search 遅延目安 | web_fetch 遅延目安 | コスト感（2026 一般的ティア） |
|---|---|---|---|
| 単純 1 クエリ＋1 ドキュメント | 約 0.3～2.0 s | 約 0.5～3.0 s | 従量課金、バーストで 429 増 |
| 毎ターン検索 | TTFT と線形に累積 | 複数 URL で尾部悪化 | 重複クエリと相関→キャッシュ |
| 企業 HTTPS 検査 | ホップごとに数百 ms 増え得る | 大ページ＋解凍でタイムアウト近接 | API 単価より工数が嵩むことも |
検索→取得→要約を 1 つの request id で 3 セグメント計測し、「遅い」をモデル／ツール／ネットに分解する。JSONL 可観測性の記事と同じ考え方。
7. エラー対照
| 症状 | 想定層 | まずやること |
|---|---|---|
| キー未設定／無効 | 検索プロバイダ | サービス環境、doctor、冷起動 |
| URL が null | パース／版ズレ | 版を揃え生 JSON を保存 |
| 429／クォータ | プロバイダ | コンソール、スロットル、ティア変更 |
| TLS 失敗 | fetch または MITM | curl -v、企業根、プロキシ |
| 特定サイトだけ 403/503 | ボット対策 | ミラー URL、間隔、ポリシー |
| 文字化け・切り詰め | エンコーディング | UTF-8、バイト上限、バイナリ除外 |
| コンテナのみ失敗 | Docker DNS/プロキシ | コンテナ内 curl、Docker ガイド |
本番レベルの読ページをノートのブラウザ自動化や捨てスクリプトだけに頼ると、(1) スリープ・ロック・GUI セッションで不安定、(2) キーとプロキシが対話ユーザーに紐づきゲートウェイとズレ、(3) 出口と TLS の監査ログが弱く 429 やハンドシェイク失敗が「再起動して祈る」になる。さらに Docker 単独でボリューム・DNS・環境継承が曖昧だと、ネットワーク名前空間や UID、OOM/Exit 137の調査が「検索品質」に見えて時間を浪費する。
対して OpenClaw を専用 Mac クラウドに載せ、Linux VPS に近い SSH 運用でキー・出口ホワイトリスト・launchd/compose を一箇所にまとめると、単一の信頼できる実行身份と Apple ツールチェーン親和性が得られる。本番で「ウェブを読むエージェント」を安定運用するチームにとって、VPSMAC の Mac クラウドをレンタルするのが通常より優れた選択になりやすい。検索＋取得をチャネル・モデルと同じリリースチェックに入れ、ゲートウェイ更新のたびにツールが壊れているのを最後に知ることを避ける。ゲートウェイ未起動なら先に 5 分デプロイ記事を完了させ、本稿で固めよ。