結論からお伝えします。2026年2月、私たちはOpenClawでxAIのGrok Searchを有効化しようとして直面した問題を、2本の記事に分けて扱いました。ところが今回統合改訂するにあたって再検証したところ、その記事が紹介していた手動パッチ2件は、私たちが記事を公開する前に、すでに上流(upstream)で修正されていました。 さらに、原因として名指ししていたGitHubのissue番号も、6本の記事すべてで誤って引用していたことがわかりました。この記事はその訂正とあわせて、現時点で実際に必要な設定だけを改めて整理したガイドです。
🔍 概要 ― Grok Searchとこの記事の背景
Grok Searchは、xAIのGrokモデルを活用してOpenClawのAIエージェントがリアルタイムのウェブ検索を行えるようにするツールです。これまではBrave Search APIのみに対応していましたが、Brave側は検索品質は安定しているものの、結果が純粋な検索スニペット中心で、最新のニュースや急速に変化する情報を扱う際には物足りない面がありました。2026.2.9バージョン(PR #12419)でGrokが新しい検索プロバイダーとして追加され、xAIの/v1/responsesエンドポイントにweb_searchツールを組み合わせて使う方式が一緒に導入されました。Grokモデル自体がリアルタイム性を強みとしているため、検索プロバイダーとしてもこの点に期待が集まりました。
私たちはこの機能を有効化する過程でいくつもの問題に直面し、これを2月13日のバグ修正記録(デバッグ日誌形式)と2月23日のセットアップガイド(整理されたチュートリアル形式)の2本に分けて扱いました。今回、両方の記事を並べて改めて見直したところ、それぞれが挙げる「問題の数」からしてすでに食い違っていました。
当時の状況をもう少し説明すると、Grok Searchはリリース直後にすぐ使える状態ではありませんでした。PR #12419がマージされたばかりの新機能で、私たちが実際に触っていた時期(2月初旬〜中旬)は、関連するバグが上流でもまさに修正されている最中でした。そのため、私たちが直面した問題の多くは環境側の問題ではなく、機能そのものがまだ安定化する前の状態をそのまま経験したものでした。この背景を踏まえると、後述する「すでに修正されていたバグを、修正済みと知らずに再度パッチしていた」という話にも納得がいきやすくなります。
🐛 当初見つかった5つの問題
私たちの既存記事はいずれも「4つの問題」として紹介していましたが、実際には5つの異なる問題があり、どの記事もこの5つを一つにまとめきれていませんでした。バグ修正記録はタイトルで「バグ3個」としながら、本文では「4つの問題(コードバグ2つ+設定ミス2つ)」と述べ、npm二重インストールの項目を番号なしの「ボーナス」として別扱いにしていました。セットアップガイドは逆に、APIキーの問題を4番目として番号を振り、今度はnpm二重インストールの方を番号なしの解決手順に回していました。結果として、私たちのコンテンツ全体を通じて「4つ」という数字だけが繰り返され、その中身は毎回違う組み合わせだったわけです。今回の統合改訂では、5つすべてを正直に列挙します。
| # | 問題 | 分類 |
|---|---|---|
| 1 | モデル名がgrok-2に設定されていた(web_search非対応モデル) | 設定ミス |
| 2 | includeパラメータの400エラー | コードバグ |
| 3 | 検索自体はできるのに常に「No response」 | コードバグ |
| 4 | npm二重インストールによりゲートウェイが古いコードを実行 | 運用・デプロイの問題 |
| 5 | .envのXAI_API_KEYがコメントアウトされていた | 設定ミス |
🔬 どう診断したか
当時のバグ修正記録に残っていた診断過程をここに転載します。最初に出会ったエラーはモデル名の問題でした。
xAI API error (400): {"error": "Model not found: grok-2"}モデル名をgrok-4-1-fastに直すと、別のエラーが現れました。
xAI API error (400): {"code":"400","error":"Argument not supported: include"}このエラーはコードを直接見なければ原因がわからない種類のものでした。エラーが消えた後も検索結果は常に空で返ってきており、xAI APIをcurlで直接呼び出して実際のレスポンス構造を確認しました。
curl -s -X POST https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-d '{"model":"grok-4-1-fast",
"input":[{"role":"user","content":"latest AI news"}],
"tools":[{"type":"web_search"}]}'当時のOpenClawのコードが想定していたレスポンス形式と、xAIが実際に返す形式はまったく異なっていました。
| OpenClawが想定していたもの | xAIの実際のレスポンス構造 |
|---|---|
data.output_text | data.output[0].content[0].text |
この過程で得た教訓は4つでした。
- PRの原文こそが真実のソースです。 モデル名や設定のデフォルト値がわかりにくいときは、公式ドキュメントよりGitHub PRのコミットメッセージの方が速く正確な根拠になることが多いです。ドキュメント化は常にコード変更より一歩遅れます。
- xAIのAPIはOpenAIと異なります。
/v1/responsesエンドポイントのレスポンスがネストした配列構造のため、OpenAI互換を前提に書かれたコードはパース段階でずれが生じやすいです。 - 直接curlで確認するのが最速です。 アプリケーション層を経由せずAPIを直接呼び出せば、問題がクライアントコード側にあるのかAPI自体にあるのか、すぐに切り分けられます。
- npmのグローバルインストールは一つの経路に統一すべきです。 sudoインストールとユーザーprefixインストールを併用すると、systemdのようなサービスがどちらを参照しているのか混乱しやすくなります。
🔧 当時の解決方法
当時、私たちが実際に適用した手動パッチです。以下のコードパッチ2件(問題2、3)は、この後の「では、今はどうなのか?」の節で訂正します ― すでに上流で修正された後でした。 当時の記録をそのまま残しておく理由は、同じ時期に別バージョンを使っている方の参考になる可能性があることと、私たち自身の判断過程を透明に残しておくためです。
npm二重インストールの整理 ― /usr/lib/node_modules/openclaw/と~/.npm-global/lib/node_modules/openclaw/の2箇所にインストールされており、systemdサービスは後者を参照していました。
sed -i 's|/home/{username}/.npm-global/lib/node_modules/openclaw/dist/index.js|/usr/lib/node_modules/openclaw/dist/index.js|g' \
~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload
rm -rf ~/.npm-global/lib/node_modules/openclaw
rm ~/.npm-global/bin/openclawモデル名の修正 ― grok-2をgrok-4-1-fastに変更しました。
python3 -c "
import json
with open('/home/{username}/.openclaw/openclaw.json') as f:
d = json.load(f)
d['tools']['web']['search']['grok']['model'] = 'grok-4-1-fast'
with open('/home/{username}/.openclaw/openclaw.json', 'w') as f:
json.dump(d, f, indent=2)
"(当時の暫定対応) includeパラメータのパッチ ― ビルドされたファイルを直接sedで修正しました。
sudo sed -i 's/if (params.inlineCitations) body.include = \["inline_citations"\];/\/\/ PATCHED/' \
/usr/lib/node_modules/openclaw/dist/reply-DptDUVRg.js(当時の暫定対応) レスポンスパースのパッチ ― フォールバック経路を直接追加しました。
sudo sed -i 's|content: data.output_text ?? "No response"|content: (data.output_text ?? data.output?.find(o => o.type === "message")?.content?.find(c => c.type === "output_text")?.text) ?? "No response"|' \
/usr/lib/node_modules/openclaw/dist/reply-DptDUVRg.jsAPIキーの有効化 ― .envのコメントアウトを解除しました。
sed -i 's/^#XAI_API_KEY=/XAI_API_KEY=/' ~/.openclaw/.envincludeパラメータのパッチとレスポンスパースのパッチは、もう適用してはいけません。 下の「では、今はどうなのか?」の節を先にご確認ください ― ビルドファイルのパス(reply-DptDUVRg.js)自体、現在のアーキテクチャにはもう存在しません。🔄 では、今はどうなのか?
今回の統合改訂で最も重要な部分です。5つの問題を、実際のGitHub PR・issue・現在のコードと一つずつ突き合わせました。
最も重要な発見: コードバグ2件は、私たちが記事を公開する前にすでに修正されていました。 includeパラメータバグの本当の修正はPR #12945で、2026年2月11日にマージされました。レスポンスパースバグの修正はPR #13049で、2026年2月10日にマージされました。両方の修正とも2026年2月13日にリリースされたv2026.2.12に含まれていましたが、この日はまさに私たちのバグ修正記録(KO)が公開されたその日です。私たちは「次のリリースに修正が含まれる予定」と未来形で書きましたが、実際にはそのリリースはすでに出ていました。
includeパラメータバグの原因としてGitHub Issue #12860を名指ししていましたが、今回再検証した結果、このissueは実際にはレスポンスパースバグ(問題3)に関するものでした。 includeパラメータバグの本当のissueはIssue #12910であり、これを修正したPR #12945は、私たちの既存記事のどこにも引用されていませんでした。これは私たち側の引用ミスだったと、はっきりお伝えしておきます。整理すると、こうなります。
当時は正しかったが、今は違うこと
- includeパラメータのパッチ、レスポンスパースのパッチ ― どちらもすでに上流で修正済みです。さらに、パッチ対象だった
reply-DptDUVRg.jsのようなビルドファイルを直接修正するという方式自体、今ではGrok/xAIのロジックがextensions/xai/専用プラグインに完全に切り出されたことで、そもそも成立しなくなっています。現在のコード(extractXaiWebSearchContent)はoutput[]配列を走査してtype === "message"ブロックを探し、その中のcontent[]をさらに調べてテキストと引用(annotation)を一緒に取り出します。当時私たちが追加した単純なフォールバックはインデックスベースだったため、レスポンス構造が少し変わるだけで壊れる可能性がありましたが、現在の方式はweb_search_callのような中間項目が混ざっていても堅牢に処理します。 - モデル名
grok-4-1-fast― 今も有効なモデルIDではありますが、もうデフォルトではありません。現在のデフォルトモデルはgrok-4.3で、xAIの最新フラッグシップは2026年7月8日にリリースされたgrok-4.5です。さらに根本的な話として、モデル選択自体がweb_search設定においてもはやドキュメント化されたオプションではありません。
今も有効なこと
- APIキーの問題 ―
.envや設定ファイルにキーを設定し忘れるミスは、アーキテクチャが変わっても同じように起こり得ます。ただし設定パスは以下で更新してお伝えします。 - npm二重インストールのリスク ― 完全には消えていません。公式インストールスクリプトができたことでリスクは減りましたが、今もドキュメント化されたトラブルシューティング項目です。
⚙️ 現在の推奨設定
設定パスそのものが変わりました。以前の記事が教えていたtools.web.search.grok.*パスは、今も下位互換のために読み込まれてはいますが(resolveXaiToolSearchConfigがレガシー設定とプラグイン設定をまとめてマージします)、現在のオンボーディングが実際に生成する設定ではありません。現時点での推奨パスはplugins.entries.xai.config.webSearch.*で、APIキーの代わりにxAI OAuth認証が優先経路として案内されます。
{
"plugins": {
"entries": {
"xai": {
"config": {
"webSearch": {
"apiKey": "xai-...(your-key, OAuthを使わない場合)",
"baseUrl": "https://api.x.ai/v1"
}
}
}
}
}
}web_search設定のドキュメント化されたオプションではありません。デフォルト値(grok-4.3)をそのまま使うことをおすすめします。APIキーを自分で管理したい場合は、XAI_API_KEY環境変数の経路も引き続き動作します。OAuthとAPIキー、何が違うのか ― APIキー方式は、この記事がもともと扱っていた方式で、発行されたキー文字列を設定ファイルや環境変数に直接入れます。キーが漏れたり流出したりした場合は自分で再発行する必要があり、有効期限や失効の管理もユーザー側の責任です。一方OAuth経路は、xAIアカウントで認証した後にトークンを発行してもらう方式のため、キー管理の負担が減り、権限範囲もより細かく制御できます。現在のオンボーディング過程で優先的に案内されるのがOAuthである理由です。すでにAPIキーで設定済みの方も、今すぐ変更する必要はありません ― どちらの経路も引き続きサポートされています。
以前の設定ファイルが残っている場合 ― tools.web.search.grok.*パスで設定した状態のままでも、現在のバージョンで急に動作が止まることはありません。resolveXaiToolSearchConfigがレガシーパスと新しいプラグインパスをまとめて読み込むためです。ただし、新しいドキュメントやオンボーディングフローはすべて新パス基準で書かれているため、この機会に移行しておくことをおすすめします。
npm二重インストール、今はこう防止されています ― 公式インストールスクリプト(install.sh、install-cli.sh)を使えば、はるかに安全です。install-cli.shはユーザー所有の単一パス(~/.openclaw)にのみインストールするため、root権限のインストール本体が別途できてしまう状況自体を構造的に防ぎます。install.shはインストール・アップグレード後に、すでに起動しているゲートウェイサービスを検知して再起動まで処理します。当時私たちが直面した問題 ― sudo npm install -gでアップグレードしても、ゲートウェイが古いパスを実行し続けていた状況 ― は、まさにこの事後の再起動ステップが存在しなかったために起きたことでした。ただし、npmのグローバルインストールを手動で複数のパスに分けて行った場合のPATH競合は、今も公式のトラブルシューティングドキュメントに残っている項目のため、完全に消えたリスクではありません。
APIキーの問題、確認する順番
.envでXAI_API_KEYの行がコメントアウト(#)されていないか確認- 設定ファイルの
apiKeyフィールドが空文字列になっていないか確認 - OAuth経路を使っている場合、別途APIキーを設定しなくても動作するかを先に確認(こちらの方が優先度が高いです)
今の設定が正しくできているか確認する方法 ― 最も確実な方法は、以前と同様にcurlで直接呼び出してみることです。正常なレスポンスであれば、output[]配列の中にtype: "message"ブロックがあり、その中のcontent[]に実際のテキストが入っているはずです。もし以前のようにレスポンスが空だったり400エラーが出たりする場合は、今回はコードバグではなく、認証(OAuthトークンの期限切れ、APIキーの入力ミス)の方を先に疑うのが順序として正しいです ― もともとコードバグだった2つの問題は、先に説明した通り、すでに上流で解決されているためです。
🧭 まとめ
今回の統合改訂の要点は2つです。第一に、当初の5つの問題のうちコードバグ2件はすでに解決されており、その修正は私たちが記事を公開した時点よりも前に出ていました。私たちが「もうすぐ修正される予定」と書いた文章は、公開時点ですでに誤りだったことになります。第二に、その過程で私たち側の引用ミス(Issue #12860の誤帰属)が6本の記事すべてで繰り返されていたことも、今回確認しました。
なぜこのようなことが繰り返されたのかを考えると、原因は不注意ではなくタイミングでした。Grok Searchはリリース直後の数日間に関連PRが次々とマージされていた機能で、私たちはその流れを追いきれないまま、ある一瞬のスナップショットだけを見て記事を書いてしまいました。ただし、issue番号の誤帰属はタイミングの問題ではなく純粋な引用ミスであり、これは私たちが認めて向き合うべき部分です。急速に変化するオープンソースプロジェクトを扱う際は、特定時点のスナップショットを「現在の状態」と決めつけるのではなく、「この時点基準」というラベルを付ける習慣が必要だと改めて感じました。
今Grok Searchを新しく設定される場合は、上の「現在の推奨設定」の節だけをご覧いただければ十分です。それ以外の部分は、当時の私たちがどのように、そしてなぜ間違えたのかという記録として残しておきます。
📚 参考資料
- PR #12419 ― Grok Searchプロバイダーの追加
- Issue #12910 ― includeパラメータ400エラー(本当の原因)
- PR #12945 ― includeパラメータバグの修正(2026-02-11マージ)
- Issue #12860 ― レスポンスパースバグ(私たちが以前誤って引用していたissue)
- PR #13049 ― レスポンスパースバグの修正(2026-02-10マージ)
- 現在のxAIプラグインソース ― responses-tool-shared.ts
- 現在のGrok Search公式ドキュメント
- 公式インストールスクリプトのドキュメント
- xAI公式発表 ― Grok 4.5(2026-07-08)