01. 三つの痛み分類：ツール一覧が空、キー／クォータ、アップグレード後に機能消失

1）ツールパレットに web_search が無い：多くの場合モデルは問題ありません。エージェントプロファイル／プレーン機能バンドルが Web 取得を公開していないか、スキルは入れたがゲートウェイ再起動後に再登録されていないことがあります。Skills 3.24 コンソール切り分けの層に従い、JSON を触る前に UI・プラグインマニフェスト・ランタイムのツール表を取得してください。

2）ツールはあるが 401/403/429 で失敗：Brave Search と Tavily はローテーション可能な API キーと明確な外向き経路を前提にします。企業プロキシが api.search.brave.com や Tavily を MITM すると、ぼんやりしたタイムアウトに見えがちです。openclaw.json を書き換える前に、ゲートウェイと同じ Unix ユーザーで最小の curl プローブを実行してください。

3）パッチ適用後に「昨日は検索できた」：ツール登録とプラグイン ABI が Node のマイナーや古いキャッシュとずれることがあります。v2026.4.5 導入記事に沿って単一インストール経路に固定し、きれいに再起動してから、まだダメならタグをピン留めしてください。切り分け中はホスト npm のゲートウェイとコンテナを混在させないでください。

02. Brave / Tavily / 自前 SearXNG：プロバイダ比較

この表で10 分以内に検索サプライチェーンを選ぶための枠組みです。フィールド名の詳細はリリースノートに従い、ここでは運用上の境界に絞ります。ツールが承認境界をまたぐ場合は MCP 連携と承認セキュリティも併読してください。

観点	Brave Search API	Tavily 系 API	自前 SearXNG
オンボーディングと課金	ダッシュボードでキー発行。無料枠は多くの場合月約 2,000 クエリ前後（コンソールで要確認）	コール単位のティア。バースト実験向き	初期構築コストは高いが長期で償却
コンプライアンスとデータ所在地	ToS／ログを確認。クエリはネットワーク外に出る場合あり	プロンプトにイントラネットホスト名が含まれる場合も同様の注意	VPC 内にクエリを閉じ込めやすい
OpenClaw との結合	`tools.web.search` の provider 文字列とキーローテーション	同様。モデル温度が高いと QPS が増えやすい	MCP や独自 HTTP ツールラッパーが必要なことが多い
日払い Mac との相性	「キーは通るがゲートウェイから呼べない」再現に向く	クォータ／ブレーカ演習に有用	社内 DNS／証明書問題のシミュレーションに向く

03. 症状切り分け：UI・ログ・HTTP エラー

「ブラウズできない」を見えない／見えるが壊れている／不安定に分け、JSON を無限にいじるのを避けます。公開ゲートウェイはキーとクエリ本文の両方が漏れやすいので、本番で切り分ける前にゲートウェイ Token と SecretRef を読んでください。

症状	まず確認	関連読み物
UI に web_search が無い	エージェント機能の許可リスト、スキル ON/OFF、古いゲートウェイ PID	Skills コンソール切り分け
ツール呼び出しで 401/403	正しい環境へのキー注入、時刻ずれ、アカウント混在	コマンドエラー FAQ
429 や間欠タイムアウト	クォータ、プロキシ、DNS、同時ツールの嵐	利用量とルーティングのガバナンス

04. 五手順：doctor からエンドツーエンド検索スモークまで

バージョンとインストール経路を固定：openclaw --version、Node メジャー、systemd/launchd/Docker のどれがゲートウェイを起動しているかを記録します。v2026.4.5 導入記事と揃え、切り分けの途中で npm とコンテナを行き来しないでください。
doctor を実行しスニペットを保管：出力をチケットに添付します。TLS を指摘されたら OpenClaw の外で curl を検証し、コマンド FAQ の文字列と突き合わせます。
最小の tools.web.search ブロックを書く：プロバイダとキーは一つずつ。ファイル権限はゲートウェイユーザーだけが読めるようにします。チャットログに秘密を貼らないでください。
ゲートウェイ再起動と単一ターンスモーク：重いスキルは無効化し検索関連ツールのみにして、取得が必要な事実クエリを一発投げます。
二分探索でロールバック：最後に動いていたタグにピン留めし、プラグイン一覧と設定を diff します。手順は監査用にアップグレード／移行／ロールバックに記録してください。

# 最小診断（パスは環境に合わせて変更）
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

Linux では待受確認に ss -lntp を使います。Windows では WSL と PowerShell のホーム分割について Windows doctor 記事を参照してください。

05. 指標、キー運用、よくある誤解

指標 1：2026 年のスレッドサンプルでは、「ツールが壊れた」報告の約 40～55% が実際には設定未再読込／ゲートウェイ未再起動／PATH 分裂でした。モデルをいじる前に最小スモークを走らせてください。
指標 2：Brave の一般的な無料枠は月およそ二千クエリオーダーです（ダッシュボードで確認）。再クエリの激しいエージェントは数分で 429に当たり、401 ではないことがあります。
指標 3：本番の検索キーを日払いの短命 macOS ユーザーだけに置き、ノート PC には Brave/Tavily の秘密を持たせないと、長期ローカルデバッグに比べシェル履歴・画面キャプチャ・共有 VNC などのサイドチャネル漏えいをおおよそ一桁抑えられるという整理がよくされます（法的保証ではありません）。

誤解 A：「強いモデルがあれば web_search は不要」—閉じた重みでも変動する事実は幻覚します。誤解 B：「キーをグローバル export すれば launchd が直る」—非対話サービスはシェル環境を読めないことがあります。誤解 C：「Docker は常に秘密を隔離」—悪いボリュームマウントでホストの .env がログに出ます。

接続は SSH/VNC FAQ、ハードウェア段階はベアメタル macOS 料金、リモート運用は macOS リモート接続ガイドを参照してください。

tools.web.search と Skills の併用：ネイティブ検索と ClawHub の Web 検索スキルを同時に有効にすると、二重登録やエイリアス不一致が起き、モデルは web_search を見ているのに設定は別場所、という状態になりがちです。まず一本のサプライチェーンから始め、遅延と HTTP コードをログに残してから二本目を足してください。自動承認は MCP 連携に戻して設計します。

キーローテーション：DB パスワードを回す日と同じ日に、誰がキーを発行・ローテーション・失効させるかを文書化します。SecretRef と支出上限を既に運用しているなら、検索 QPS を予算アラートに載せ、夜間自動化がクォータを枯らさないようにします。

企業 TLS インスペクション：Node のトラストストアに企業ルートが無いと、不透明な TLS エラーになります。ゲートウェイユーザーで curl/node を試し、コンテナとホストの信頼束を比較し、プライベート企業ルートをレンタル機に持ち込まないでください。

429 のバックオフ：温度を上げてモデルに「別の聞き方」をさせるのではなく、指数バックオフと同時実行上限を実装します。失敗はガバナンス記事のフォールバックルーティングと組み合わせます。

Windows/WSL の二重人格：Windows 側で openclaw.json を編集しているのにゲートウェイが WSL 側を読むと、「ファイルは変わったがプロセスは読み込んでいない」典型パターンになります。Windows doctor ガイドでホームを一本化してください。

日払いリハーサル：レンタル → 単一ユーザー経路で導入 → doctor → 最小検索設定 → スモーク → マスクしたログをエクスポート → 電源オフ。日払いの落とし穴と組み合わせ、共有 VNC クリップボードにキーを置かないでください。

切り分け順：可視性 → 認証（401/403）→ クォータ／ネットワーク（429/タイムアウト）→ バージョン／プラグイン ABI。常に doctor とゲートウェイログを添付し、コマンド FAQ の文字列照合に回してください。

06. ヘッドレス Linux／Windows の限界と Mac レンタル

純ヘッドレス LinuxやDocker Desktop 依存の重い Windows ノートは CI プローブには使えますが、ホーム分割、信頼ストア不一致、ブラウザコンソールとゲートウェイログのすり合わせの遅さを招きがちです。複数の本番検索キーの唯一の置き場にするのではなく、短期の検証面として扱ってください。

Apple と同一の TLS・ツールチェーン挙動が必要で、資格情報リスクを時間で区切りたいなら、まずネイティブ macOS で検索スモークを通し、その後に Linux/Windows で長期ホストするか決めます。日払い Mac はコンソールの見え方を保ちつつ、契約終了で環境を破棄できます。レンタルとローカルのコスト試算とデプロイの落とし穴を併読し、結果をランブックに書き留めてください。

2026 OpenClaw Web 検索プレイブック：
web_search 不在、Brave/Tavily 設定と doctor 切り分け

目次