ドキュメント · プロバイダ

Grok を Claude Code・Codex・Gemini CLI・OpenCode で使う

xAI は Grok のモデルを OpenAI Chat Completions・OpenAI Responses・Anthropic Messages の三つの API で提供しています。xAI の API キーを magpie に一度追加すれば、Claude Code・Codex・Gemini CLI・OpenCode などつないだすべてのツールが、magpie のゲートウェイ 127.0.0.1:3425 経由で Grok を使えます。ツールごとに別のモデルを選べます。

xAI を追加する

1. キーを取得console.x.ai で作ります。
2. プロバイダを追加magpie の プロバイダ で ＋ プロバイダを追加 を押し、xAI を選んでキーを貼り付け、保存します。magpie がそのキーで使えるモデルを xAI に問い合わせます。
3. ツールで選ぶエージェント タブで、ツールの行のモデルを押し、grok-4.7 などの Grok モデルを選びます。

magpie provider add xai xai-…
magpie provider test xai

magpie のモデル ID は プロバイダ/モデル の形なので、xAI のモデルは xai/grok-4.7 のようになります。前がプロバイダ、後ろが xAI 自身の ID です。キーは magpie の設定に保存され、magpie がシェルから読むことはありません。

エンドポイント

ツールの話す API を xAI が提供していれば、リクエストはその API にそのまま渡します。変換が必要なときは Chat Completions を使います。Responses を優先するのは OpenAI での OpenAI 自身のモデルだけ、Messages を優先するのは Claude モデルだけで、Grok はどちらでもないからです。

モデル一覧

magpie は一覧を xAI の https://api.x.ai/v1/models から取得するので、ツールにはそのキーで使えるモデルが並びます。名前・推論レベル・価格は models.dev の xai カタログから取ります。ツールに見せるモデルは、プロバイダのモデル一覧かターミナルで選べます。

magpie provider models xai +grok-4.7
magpie provider refresh-every xai 1d

ツールごとの使い方

magpie claude xai/grok-4.7
magpie codex xai/grok-4.7
magpie gemini model xai/grok-4.7
magpie opencode xai/grok-4.7

• Claude Code は Anthropic Messages を話し、xAI も https://api.x.ai で同じ API を提供しているので、リクエストはそのまま送ります。手を入れるのは下に挙げた点だけです。Claude Code で他のモデル。
• Codex は OpenAI Responses を話し、xAI はそれを https://api.x.ai/v1 で提供しているので、こちらもそのまま送ります。xAI が Codex のカスタムツールを拒否した場合（“unknown variant custom”）、magpie はそれ以降そのモデルへの Codex のリクエストを変換し、それらのツールを通常の関数として渡します。Codex で他のモデル。
• Gemini CLI は Google の Gemini API を話しますが、xAI はこれを提供していません。magpie が各リクエストを Chat Completions に変換し、返答を戻します。ストリーミングとツール呼び出しも含みます。Gemini CLI で他のモデル。
• OpenCode は Chat Completions を話すので、リクエストはそのまま xAI に送ります。OpenCode で他のモデル。

xAI 自身の CLI である Grok Build でも magpie のモデルを使えます。magpie がそれらを ~/.grok/config.toml に書き込むので、/model の選択肢に並びます。

magpie が xAI 向けに直すもの

ツールが送るもののうち、いくつかは xAI の API に拒否されます。magpie はそのまま渡すリクエストでも変換するリクエストでも途中でそれを直すので、ツールがこれらのエラーを見ることはありません。

• ツールの正規表現。xAI はツールの pattern を別の正規表現エンジンで読むため、Windows の Claude Code が使う ^[^\s[\]]+$ のようなパターンが “Schema validation failed: … is not a "regex"” で失敗していました。magpie はこれをエスケープし、xAI が JavaScript と同じように読めるようにします。
• ツール引数のルート。引数が anyOf・oneOf・allOf で始まるツール（Codex デスクトップ版の自動化ツールなど）は、最初のリクエストから object にまとめて送ります。そうしないと xAI は “tool parameter root must be an object type” を返します。
• 空のフィールド。ツールのスキーマにある "required": null と、Codex の推論アイテムにある "content": null は外して送ります。そうしないと xAI は “/required: null is not of type "array"” や “Could not decode the compaction blob” を返します。
• 会話の途中のシステムメッセージ。Claude Code が会話の途中に入れるシステムメッセージは、先頭のシステムプロンプトにまとめます。そうしないと xAI は “Invalid request content: Invalid message role.” を返します。
• ツールのない tool_choice。tool_choice を指定しながらツールを一つも渡さないリクエスト（Codex がコンテキストを圧縮するときの要約など）は、それを外して送ります。そうしないと xAI は “A tool_choice was set on the request but no tools were specified” を返します。
• Codex が追加するツール。xAI の Responses API は Codex の additional_tools アイテムを知らないので、magpie はそのツールをリクエストの tools に入れます。
• 整数。Grok はツール呼び出しの引数で整数を 2500.0 のように小数付きで書き、Codex の整数フィールドはそれを受け付けません。magpie は 2500 に書き直します。ストリーミングの返答でも同じです。

推論

• 推論の強さ。ツールが求める推論の強さは、カタログにあるそのモデルのレベルのうち最も近いものに合わせます。レベルがわからないモデルには、ツールが求めたとおりに送ります。
• 推論オフ。Gemini CLI のように magpie が変換するツールが推論をオフにし、モデルのレベルに none があるとき、magpie は none を求めます。
• 会話の途中でモデルを替える。xAI が読めるのは自分で封じた推論だけです。Codex の会話を GPT や別のアカウントから Grok に移すと、xAI は “Could not decrypt the provided encrypted_content” を返します。magpie はすぐにそのアイテムを外して問い合わせ直し、その会話のあとのリクエストからも外します。

Web 検索

• Codex。xAI は Responses API で自ら Web を検索するので、Codex の web_search は xAI が行います。
• Claude Code・Gemini CLI・OpenCode。xAI の Messages と Chat Completions の API は検索しないので、magpie がモデルに自前の検索ツールを渡します。答えるのは設定で指定した検索サービスで、指定がなければ magpie が選んだものです。
• xAI を検索役に。xAI は自分で検索できるので、magpie は検索できないモデルのために xAI のキーを検索役に選ぶことがあります。

キャッシュ・費用・使用量

• キャッシュのトークン。magpie は xAI が返答ごとに報告するキャッシュ済みトークンを読むので、使用量 タブではキャッシュヒットをプロンプトの残りと分けて数えます。
• キャッシュを生かす。キーが複数あるとき、会話のキャッシュに残す価値があり（1,024 トークン以上）、まだ温かい（5 分以内に読まれた）あいだは、その会話は同じキーを使い続けます。キャッシュの冷えたキーにターンを送ることはありません。
• 費用。使用量タブは、models.dev にある xAI の価格で Grok の呼び出しごとに費用を計算します。
• 残高。magpie は xAI から残高を読みません。key-balance で自分で入力すると、使用量ページはそこから magpie がそれ以降のキーの呼び出しに付けた費用を引いて表示します。

複数のキーとフェイルオーバー

一つの xAI プロバイダに複数のキーを入れられます。その下の 別のキーを追加 を押すか、まとめて貼り付けます。リクエストはオンになっている最初のキーに行き、そのキーが尽きるかレート制限にかかると次のキーが引き継ぎます。

• 支出上限。spend-cap で、キーごとに 1 日・1 か月・累計のドル上限を決められます。金額は使用量タブの計算で数え、上限に達するとルーティングはほかのキーとフォールバックに移ります。
• フォールバック。fallback で、xAI の枠が尽きたときや落ちたときの行き先を決めます。別のプロバイダのモデルか、ルーティンググループです。
• xAI が読めないリクエスト。xAI が 422 “Failed to deserialize the JSON body … unknown item type” を返したときは、ルーティンググループの次のメンバーに回します。そのためにキーが休むことはありません。

magpie provider spend-cap xai <key> 20 month
magpie provider key-balance xai <key> 25
magpie provider fallback xai deepseek/deepseek-v4-pro

うまくいかないとき

• “maximum prompt length is …”。会話がモデルの受け付ける長さを超えています。magpie はこれをツールが理解できる形、context_length_exceeded や Anthropic の “prompt is too long” で伝えるので、ツールはコンテキストを圧縮してやり直します。
• “Could not decrypt the provided encrypted_content”。Codex が別ベンダーの推論を含んだまま、会話の途中で Grok に移りました。magpie はそれを外して問い合わせ直します。推論を参照してください。
• “unknown variant custom”。xAI が Codex のカスタムツールを拒否しました。magpie はそれ以降そのモデルへの Codex のリクエストを変換するので、このエラーが出るのは一度だけです。
• キーの確認。magpie provider test xai は各エンドポイントに、または指定した各モデルに小さなリクエストを送ります。--as codex や --as claude-code を付けると、そのツールと同じ形で送ります。

よくある質問

Claude Code で Grok を使うには？

magpie で xAI の API キーを追加し（プロバイダ、プロバイダを追加、xAI）、Claude Code の行で grok-4.7 などの Grok モデルを選ぶか、magpie claude xai/grok-4.7 を実行します。Claude Code のリクエストは magpie のゲートウェイを通って xAI の Anthropic Messages エンドポイント https://api.x.ai に届きます。

Codex で Grok 4 は使えますか？

使えます。xAI は Codex が話す Responses API を提供しているので、magpie codex xai/grok-4.7 で Codex のリクエストは https://api.x.ai/v1 にそのまま届きます。ツールのスキーマ、ツールのない tool_choice、Grok が 2500.0 と書く整数など、xAI が拒否するものは途中で直します。

Gemini CLI と OpenCode で Grok は使えますか？

使えます。Gemini CLI は Google の API を話すので、magpie がリクエストを xAI の Chat Completions に変換し、返答を戻します。OpenCode は Chat Completions を話すので、リクエストはそのまま xAI に届きます。magpie gemini model xai/grok-4.7 か magpie opencode xai/grok-4.7 を実行してください。

Grok で Web 検索はできますか？

できます。Codex の Web 検索は xAI が Responses API で自ら行います。Claude Code・Gemini CLI・OpenCode では、magpie がモデルに自前の検索ツールを渡し、設定で指定した検索サービスか magpie が選んだものが答えます。

Codex の会話の途中で GPT から Grok に替えたらエラーになるのはなぜ？

xAI はほかのベンダーが封じた推論を読めず、“Could not decrypt the provided encrypted_content” を返します。magpie はそのアイテムを外して問い合わせ直し、その会話の残りでも外したままにします。

magpie で xAI の残高は見られますか？

見られません。使用量タブは Grok の呼び出しごとにトークン・キャッシュ・費用を models.dev の価格で数えますが、magpie は xAI から残高を読みません。magpie provider key-balance で残高を入力すると、使用量ページはそこから magpie がそれ以降に計算した費用を引いて表示します。

プロバイダ別：DeepSeek · Kimi と Kimi Code · GLM Coding Plan · Qwen · MiniMax · Gemini · Mistral · OpenRouter · GitHub Copilot · Ollama

ツールごとのガイド：Claude Code で他のモデル、Codex で他のモデル、Gemini CLI で他のモデル、OpenCode で他のモデル。困ったときは Discord で質問してください。