文档 · 供应商

Grok 接入 Claude Code、Codex、Gemini CLI 和 OpenCode

xAI 的 Grok 模型同时提供三种接口：OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。把 xAI 的 API Key 添加到 magpie 一次，Claude Code、Codex、Gemini CLI、OpenCode 以及你接入的其他工具，都能通过 magpie 的本地网关 127.0.0.1:3425 使用 Grok，每个工具各用各的模型。

添加 xAI

1. 拿到 Key在 console.x.ai 创建。
2. 添加供应商在 magpie 的 供应商 页点 ＋ 添加供应商，选 xAI，粘贴 Key 并保存。magpie 会向 xAI 查询这个 Key 能用哪些模型。
3. 给工具选上在 Agent 页点工具那一行的模型，选一个 Grok 模型，比如 grok-4.7。

magpie provider add xai xai-…
magpie provider test xai

magpie 里的模型 id 是 供应商/模型，所以 xAI 的模型写作 xai/grok-4.7：前面是供应商，后面是 xAI 自己的 id。Key 保存在 magpie 的设置里，magpie 不会从 shell 里读取它。

接口地址

工具说的接口如果 xAI 提供，请求就直接交给那个接口。需要转换时，magpie 用 Chat Completions：只有 OpenAI 官方的 OpenAI 模型优先走 Responses，只有 Claude 模型优先走 Messages，Grok 两者都不是。

模型列表

magpie 从 xAI 的 https://api.x.ai/v1/models 拉取模型列表，所以工具里看到的就是你这个 Key 能用的模型。模型名称、推理档位和价格来自 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 也提供这个接口，所以它的请求原样发过去，只做下面列出的修正。Claude Code 接入其他模型。
• Codex 说 OpenAI Responses，xAI 在 https://api.x.ai/v1 提供这个接口，所以它的请求也原样发过去。如果 xAI 拒绝 Codex 的自定义工具（“unknown variant custom”），magpie 之后会把这个模型的 Codex 请求转换后再发，并把这些工具当作普通函数提供。Codex 接入其他模型。
• Gemini CLI 说 Google 的 Gemini 接口，xAI 不提供。magpie 把每个请求转成 Chat Completions，再把回复转回来，流式输出和工具调用都包括在内。Gemini CLI 接入其他模型。
• OpenCode 说 Chat Completions，所以它的请求原样发给 xAI。OpenCode 接入其他模型。

xAI 自己的命令行工具 Grok Build 也能用 magpie 的模型：magpie 把它们写进 ~/.grok/config.toml，它们就会出现在 /model 的选择列表里。

magpie 替你修正的请求

工具发出的有些内容，xAI 的接口不接受。magpie 会在转发途中改好，原样转发的请求和转换过的请求都一样，工具不会再碰到这些报错：

• 工具的正则。xAI 用另一种正则引擎读工具的 pattern，像 Claude Code 在 Windows 上的 ^[^\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”。
• 空字段。工具 schema 里的 "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 接口不认识 Codex 的 additional_tools 条目，magpie 会把其中的工具放进请求的 tools 里。
• 整数。Grok 在工具调用参数里写整数时会带小数部分，比如 2500.0，Codex 要求整数的字段不接受。magpie 会改写成 2500，流式回复里也一样。

推理

• 推理强度。工具要求的推理强度，会按目录里列出的档位，换成这个模型最接近的一档。不知道档位的模型，按工具的原始要求发送。
• 关闭推理。需要 magpie 转换请求的工具（比如 Gemini CLI）关掉推理时，如果模型的档位里有 none，magpie 就请求 none。
• 对话中途换模型。xAI 只认它自己加密的推理内容。Codex 的对话从 GPT 或另一个账号换到 Grok 时，xAI 会回 “Could not decrypt the provided encrypted_content”。magpie 会立刻去掉这些条目重新请求，并在这段对话后面的请求里都不再带上。

联网搜索

• Codex。xAI 在自己的 Responses 接口上执行联网搜索，所以 Codex 的 web_search 由 xAI 完成。
• Claude Code、Gemini CLI 和 OpenCode。xAI 的 Messages 和 Chat Completions 接口不会搜索，所以 magpie 给模型提供自己的搜索工具，由设置里指定的搜索服务回答；没指定时，由 magpie 自己挑一个。
• 用 xAI 来搜索。因为 xAI 能自己搜索，magpie 也可以挑一个 xAI 的 Key，替不会搜索的模型联网搜索。

缓存、费用与用量

• 缓存 token。magpie 读取 xAI 在每次回复里报告的缓存 token，所以 用量 页会把缓存命中和其余的提示分开统计。
• 保住缓存。有多个 Key 时，只要一段对话的缓存值得保留（1,024 个 token 以上），而且还热着（五分钟内读过），它就一直用同一个 Key，不会把某一轮发给缓存已经凉了的 Key。
• 费用。用量页按 models.dev 上 xAI 的价格给每次 Grok 调用计价。
• 余额。magpie 不会从 xAI 读取余额。可以用 key-balance 自己填上，用量页会显示它减去 magpie 此后给这个 Key 的调用算出的费用。

多个 Key 与故障切换

一个 xAI 供应商可以放多个 Key：在它下面点 添加另一个密钥，也可以一次粘贴好几个。请求先走第一个开着的 Key，它用完或被限流时由下一个接替。

• 花费上限。spend-cap 给某个 Key 设一个每天、每月或总计的美元上限，按用量页的计价算；到了上限，路由就转去其他 Key 和备用模型。
• 备用模型。fallback 指定 xAI 额度用完或挂掉时请求去哪：另一个供应商的模型，或一个路由分组。
• xAI 读不懂的请求。xAI 回 422 “Failed to deserialize the JSON body … unknown item type” 时，请求会交给路由分组里的下一个成员，这个 Key 不会因此暂停。

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 请求，这个报错只会出现一次。
• 检查 Key。magpie provider test xai 会向每个接口发一个很小的请求，或者发给你指定的每个模型。加上 --as codex 或 --as claude-code，就按那个工具的方式发送。

常见问题

Claude Code 怎么用 Grok？

在 magpie 里添加 xAI 的 API Key（供应商页，添加供应商，选 xAI），然后在 Claude Code 那一行选一个 Grok 模型，比如 grok-4.7，或者运行 magpie claude xai/grok-4.7。Claude Code 的请求经过 magpie 的网关，发到 xAI 的 Anthropic Messages 接口 https://api.x.ai。

Codex 能用 Grok 4 吗？

能。xAI 提供 Codex 说的 Responses 接口，所以 magpie codex xai/grok-4.7 会把 Codex 的请求原样发到 https://api.x.ai/v1，途中修正 xAI 不接受的内容：工具 schema、没有工具的 tool_choice，以及 Grok 写成 2500.0 的整数。

Gemini CLI 和 OpenCode 能用 Grok 吗？

能。Gemini CLI 说 Google 的接口，magpie 把它的请求转成 xAI 的 Chat Completions，再把回复转回来。OpenCode 说 Chat Completions，请求原样发给 xAI。运行 magpie gemini model xai/grok-4.7 或 magpie opencode xai/grok-4.7 即可。

用 Grok 能联网搜索吗？

能。Codex 的联网搜索由 xAI 在自己的 Responses 接口上完成。Claude Code、Gemini CLI 和 OpenCode 则由 magpie 给模型提供自己的搜索工具，由设置里指定的搜索服务回答，或者由 magpie 自己挑一个。

Codex 对话中途从 GPT 换到 Grok 为什么报错？

xAI 读不了别家加密的推理内容，会回 “Could not decrypt the provided encrypted_content”。magpie 会去掉这些条目重新请求，并在这段对话后面都不再带上。

magpie 能显示 xAI 的余额吗？

不能。用量页会统计每次 Grok 调用的 token、缓存和费用，按 models.dev 的价格计价，但 magpie 不会从 xAI 读取余额。你可以用 magpie provider key-balance 自己填上余额，用量页会显示它减去 magpie 此后算出的费用。

按供应商：DeepSeek · Kimi 与 Kimi Code · GLM 编程套餐 · 通义千问 · MiniMax · Gemini · Mistral · OpenRouter · GitHub Copilot · Ollama

各个工具的指南：Claude Code 接入其他模型、Codex 接入其他模型、Gemini CLI 接入其他模型、OpenCode 接入其他模型。遇到问题可以在 Discord 提问。