Docs · Provider

Grok in Claude Code, Codex, Gemini CLI and OpenCode

xAI serves its Grok models on three APIs at once: OpenAI Chat Completions, OpenAI Responses and Anthropic Messages. Add an xAI API key to magpie once, and Claude Code, Codex, Gemini CLI, OpenCode and every other agent you connect can use Grok through magpie’s local gateway at 127.0.0.1:3425, each agent with a model of its own.

Add xAI

1. Get a keyMake one on console.x.ai.
2. Add the providerIn magpie’s Providers tab, press ＋ Add provider, pick xAI, paste the key and save. magpie asks xAI which models the key can use.
3. Pick it for an agentIn the Agents tab, click the model on the agent’s row and choose a Grok model such as grok-4.7.

magpie provider add xai xai-…
magpie provider test xai

Model ids in magpie are provider/model, so xAI’s read xai/grok-4.7: the provider, then xAI’s own id. The key is kept in magpie’s settings; magpie doesn’t take it from your shell.

Endpoints

An agent whose API xAI serves is passed on to that API. When magpie has to translate, it uses Chat Completions: it keeps Responses first only for OpenAI’s own models at OpenAI, and Messages first only for Claude models, and Grok is neither.

Model list

magpie fetches the list from xAI, at https://api.x.ai/v1/models, so agents see the models your key can use. Names, reasoning levels and prices come from models.dev’s xai catalog. Pick the models agents see in the provider’s model list, or from the terminal:

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

In each agent

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 speaks Anthropic Messages, and so does xAI at https://api.x.ai, so its requests go there as they are, with the fixes below. Models in Claude Code.
• Codex speaks OpenAI Responses, which xAI serves at https://api.x.ai/v1, so its requests go there as they are too. If xAI turns away Codex’s custom tools (“unknown variant custom”), magpie translates that model’s Codex requests from then on and offers those tools as ordinary functions. Models in Codex.
• Gemini CLI speaks Google’s Gemini API, which xAI doesn’t serve. magpie translates each request to Chat Completions and the reply back, streaming and tool calls included. Models in Gemini CLI.
• OpenCode speaks Chat Completions, so its requests go to xAI as they are. Models in OpenCode.

Grok Build, xAI’s own CLI, can take magpie’s models too: magpie adds them to ~/.grok/config.toml, so they join its /model picker.

What magpie fixes for xAI

xAI’s API turns away a few things that agents send. magpie changes them on the way, on requests it passes on and on those it translates alike, so the agent never sees these errors:

• Tool patterns. xAI reads a tool’s pattern with a different regex engine, so a pattern such as Claude Code’s ^[^\s[\]]+$ on Windows failed with “Schema validation failed: … is not a "regex"”. magpie escapes it so xAI reads it as JavaScript does.
• Tool roots. A tool whose parameters start with anyOf, oneOf or allOf, such as a Codex desktop automation tool, is folded into an object from the first request. xAI otherwise answers “tool parameter root must be an object type”.
• Empty fields. "required": null in a tool’s schema, and "content": null on a Codex reasoning item, are left out. xAI otherwise answers “/required: null is not of type "array"” or “Could not decode the compaction blob”.
• System turns. Claude Code’s system turns in the middle of a conversation are folded into the top-level system prompt. xAI otherwise answers “Invalid request content: Invalid message role.”
• A tool choice with no tools. A request that sets tool_choice but offers no tools, such as Codex’s compaction summary, goes without it. xAI otherwise answers “A tool_choice was set on the request but no tools were specified”.
• Codex’s added tools. xAI’s Responses API doesn’t know Codex’s additional_tools items, so magpie puts their tools in the request’s tools.
• Whole numbers. Grok writes whole numbers in tool-call arguments with a fraction, such as 2500.0, which Codex’s whole-number fields refuse. magpie writes 2500, in streamed replies too.

Reasoning

• Effort. The effort an agent asks for is fitted to the nearest level the model has, as the catalog lists them. A model whose levels aren’t known is asked as the agent asked.
• Reasoning off. When an agent whose requests magpie translates, such as Gemini CLI, turns reasoning off and the model lists none among its levels, magpie asks for none.
• Switching models mid-conversation. xAI reads only the sealed reasoning it wrote itself. When a Codex conversation moves to Grok from GPT or from another account, xAI answers “Could not decrypt the provided encrypted_content”. magpie asks again without those items at once, and leaves them out for the rest of that conversation.

Web search

• Codex. xAI runs web search itself on its Responses API, so Codex’s web_search is done by xAI.
• Claude Code, Gemini CLI and OpenCode. xAI’s Messages and Chat Completions APIs don’t search, so magpie gives the model its own search tool, answered by the searcher chosen in Settings, or by one magpie picks when none is chosen.
• xAI as the searcher. Because xAI searches by itself, magpie can pick an xAI key to search for models that can’t.

Cache, cost and usage

• Cache tokens. magpie reads the cached tokens xAI reports in each reply, so the Usage tab counts cache hits apart from the rest of the prompt.
• Keeping the cache. With several keys, a conversation stays on its key while its cache is worth keeping, 1,024 tokens or more, and still warm, read within the last five minutes, so a turn isn’t sent to a key with a cold cache.
• Cost. The Usage tab prices each Grok call with xAI’s prices from models.dev.
• Balance. magpie reads no balance from xAI. Type it in yourself with key-balance, and the Usage page shows it less what magpie has priced the key’s calls at since.

Several keys and failover

One xAI provider can hold several keys: press Add another key under it, or paste several at once. Requests go to the first key that’s on, and when it runs out or is rate limited the next one takes over.

• Spend caps. spend-cap stops a key at a dollar amount a day, a month or in all, as the Usage tab prices its calls; routing then goes on to the other keys and the fallbacks.
• Fallbacks. fallback names where requests go when xAI is out of quota or down: another provider’s model or a routing group.
• A request xAI can’t read. When xAI answers 422 “Failed to deserialize the JSON body … unknown item type”, the request goes to the next member of the routing group, and the key isn’t rested for it.

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

Troubleshooting

• “maximum prompt length is …”. The conversation is longer than the model takes. magpie tells the agent so the way it understands, context_length_exceeded or Anthropic’s “prompt is too long”, so the agent compacts and tries again.
• “Could not decrypt the provided encrypted_content”. Codex moved to Grok mid-conversation with another vendor’s reasoning in it. magpie asks again without it; see Reasoning.
• “unknown variant custom”. xAI turned away Codex’s custom tools. magpie translates that model’s Codex requests from then on; the first refusal is the last.
• Checking a key. magpie provider test xai sends a tiny request through each endpoint, or to each model you name. Add --as codex or --as claude-code to send it the way that agent would.

FAQ

How do I use Grok in Claude Code?

Add your xAI API key in magpie (Providers, Add provider, xAI), then pick a Grok model such as grok-4.7 on Claude Code’s row, or run magpie claude xai/grok-4.7. Claude Code’s requests go through magpie’s gateway to xAI’s Anthropic Messages endpoint, https://api.x.ai.

Can Codex use Grok 4?

Yes. xAI serves the Responses API that Codex speaks, so magpie codex xai/grok-4.7 sends Codex’s requests to https://api.x.ai/v1 as they are, with what xAI would refuse fixed on the way: tool schemas, a tool choice with no tools, and whole numbers Grok writes as 2500.0.

Can Gemini CLI and OpenCode use Grok?

Yes. Gemini CLI speaks Google’s API, so magpie translates its requests to xAI’s Chat Completions and the replies back. OpenCode speaks Chat Completions, so its requests go to xAI as they are. Run magpie gemini model xai/grok-4.7 or magpie opencode xai/grok-4.7.

Does web search work with Grok?

Yes. Codex’s web search is run by xAI itself on its Responses API. For Claude Code, Gemini CLI and OpenCode, magpie gives the model its own search tool, answered by the searcher chosen in Settings, or by one magpie picks.

Why did Codex fail after switching from GPT to Grok mid-conversation?

xAI can’t read reasoning that another vendor sealed, and answers “Could not decrypt the provided encrypted_content”. magpie asks again without those items and leaves them out for the rest of the conversation.

Does magpie show my xAI balance?

No. The Usage tab counts tokens, cache and cost for every Grok call, priced from models.dev, but magpie reads no balance from xAI. You can type the balance in with magpie provider key-balance, and the Usage page shows it less what magpie has priced since.

By provider: DeepSeek · Kimi and Kimi Code · GLM Coding Plan · Qwen · MiniMax · Gemini · Mistral · OpenRouter · GitHub Copilot · Ollama

Every agent: Models in Claude Code, Models in Codex, Models in Gemini CLI, Models in OpenCode. Ask on Discord if you get stuck.