在 Roo Code 中接入 xAI Grok 模型：配置、推理控制与 Prompt 缓存完整指南

在 Roo Code 中接入 xAI Grok 模型配置、推理控制与 Prompt 缓存完整指南【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code本文围绕 Roo Code 官方文档 xai.md 展开系统讲解如何在 Roo Code 中启用 xAIGrok提供商包括 API Key 获取、模型选择、推理强度reasoning_effort控制、Prompt 缓存机制与底层 Responses API 调用链路。读完本文你将能够在 Roo Code 中稳定接入 Grok 系列模型并根据任务复杂度与成本诉求合理配置推理参数。一、xAI 与 Grok先了解背景xAI 是 Grok 大语言模型的研发公司Grok 系列以对话能力与超大上下文窗口著称被设计用来提供有帮助、信息丰富且贴合语境的回答。在 Roo Code 中xAI 是内置的一等公民提供商Provider模型 ID 为xai由 src/api/index.ts 中的case xai: return new XAIHandler(options)分派到对应的处理器实现。xAI 提供商在整个调用链中扮演两个角色既可以作为主对话模型驱动 Roo Code 的 Agent 任务循环也支持单轮补全completePrompt等场景其能力边界取决于所选的 Grok 具体型号。二、获取 API Key四步流程在 Roo Code 中配置 xAI 之前需要先到 xAI 控制台console.x.ai申请一个 API Key官方文档给出的流程如下注册/登录访问 xAI Consoleconsole.x.ai创建账号或直接登录。进入 API Keys 页面在控制台左侧导航中找到 API KeysAPI 密钥区块。创建新 Key点击创建按钮生成一个新的 API Key建议起一个具有描述性的名字例如Roo Code方便日后区分用途。立即复制并妥善保存⚠️ Key 只会在创建时完整展示一次关闭页面后将无法再次查看请务必立即复制并存放到安全的位置如密码管理器。在 src/api/providers/xai.ts 中可以看到当配置缺失时处理器会回退到占位值not-provided因此未填写 Key 时的请求会在服务端鉴权阶段失败——确保 Key 正确粘贴是配置的第一步。三、在 Roo Code 中配置 xAI完成 Key 申请后按以下步骤在 Roo Code 中启用 xAI打开设置点击 Roo Code 面板中的齿轮图标进入设置页。选择提供商在 API ProviderAPI 提供商下拉框中选中xAI。填入 API Key将上一步申请的 xAI API Key 粘贴到 xAI API Key 输入框中。选择模型在 Model模型下拉框中选择你需要的 Grok 型号可用型号见下一节。配置完成后xAI 会作为xai提供商写入配置并通过 ProfileValidator.ts 做合法性校验从源码看XAIHandler通过 OpenAI SDK 以https://api.x.ai/v1为 baseURL 建立客户端xai.ts并对该提供商设置了默认温度0XAI_DEFAULT_TEMPERATURE追求稳定、可复现的输出。四、可用模型全景仓库中的模型注册表Roo Code 支持通过 xAI API 提供的全部 Grok 模型。官方文档提示完整、最新的模型列表与能力请参见 xAI 官方文档而在仓库层面当前模型注册表维护在 packages/types/src/providers/xai.ts默认模型为grok-4.20xaiDefaultModelId。核心模型信息整理如下价格单位美元 / 百万 token均支持图像输入supportsImages与 Prompt 缓存supportsPromptCache模型 ID上下文窗口最大输出 token输入价格输出价格缓存写/读价格说明grok-4.202,000,00065,5362.06.00.5 / 0.5xAI 旗舰模型2M 上下文支持推理默认grok-code-fast-1256,00016,3840.21.50.02 / 0.02面向编码场景的快速模型grok-4-1-fast-reasoning2,000,00065,5360.20.50.05 / 0.054.1 Fast 推理版高性能 Agentic 工具调用grok-4-1-fast-non-reasoning2,000,00065,5360.20.50.05 / 0.054.1 Fast 非推理版grok-4-fast-reasoning2,000,00065,5360.20.50.05 / 0.054 Fast 推理版grok-4-fast-non-reasoning2,000,00065,5360.20.50.05 / 0.054 Fast 非推理版grok-4-0709256,0008,1923.015.00.75 / 0.75早期 Grok-4256K 上下文grok-3-mini131,0728,1920.30.50.07 / 0.07128K 上下文支持可配置推理强度grok-3131,0728,1923.015.00.75 / 0.75Grok-3128K 上下文需要注意几点上述表格以当前仓库packages/types/src/providers/xai.ts的实际注册内容为准官方文档正文中提到的grok-4.1-fast、grok-4、grok-3-fast等历史型号在最新注册表中已细分为grok-4-1-fast-reasoning/grok-4-1-fast-non-reasoning等版本选择模型时请以 Roo Code 下拉框中展示的为准。所有模型均声明了includedTools: [search_replace]与excludedTools: [apply_diff]意味着接入 xAI 时默认启用search_replace工具、禁用apply_diff这与 Roo Code 对 Grok 系列工具偏好的适配有关。价格字段直接驱动 Roo Code 的成本统计与预算显示缓存读写价格单独计价详见第六节。五、推理能力与reasoning_effort控制Grok 系列中相当一部分型号具备推理能力——模型会在给出答案前先思考再作答这对复杂问题求解尤其有价值。哪些模型支持可配置推理强度官方文档明确指出只有 Grok 3 Mini 系列支持可配置的reasoning_effort参数grok-3-mini— 支持推理强度控制grok-3-mini-fast— 支持推理强度控制仓库注册表中由grok-3-mini承载该能力其余型号如grok-code-fast-1、grok-4.1-fast、grok-4、grok-3、grok-3-fast虽然具备推理能力但不暴露reasoning_effort参数。这一点在源码中得到印证模型定义中只有grok-3-mini带有supportsReasoningEffort: [low, high]与reasoningEffort: low默认值xai.ts。仓库测试 xai.spec.ts 也从调用层验证了这一行为对grok-3-mini设置reasoningEffort: high时请求体会携带reasoning: { reasoning_effort: high }对grok-3设置同样的值请求体不包含reasoning字段。如何选择推理强度reasoning_effort的取值及语义见官方文档取值含义适用场景low最小化思考时间消耗更少 token响应更快简单查询、希望快速完成的日常任务high最大化思考时间消耗更多 token 应对复杂问题难题求解对响应延迟不敏感一句话建议简单问题用low复杂问题用high。从参数解析链路看Roo Code 在 model-params.ts 中会优先采用用户在设置中显式指定的reasoningEffort未指定时才回退到模型默认值grok-3-mini默认low并经由 reasoning.ts 的getOpenAiReasoning转换为 Responses API 的reasoning_effort字段最终由XAIHandler在组装请求体时写入requestBody.reasoningxai.ts。推理模型的关键特性逐步求解Step-by-Step模型在给出结论前会系统化地拆解问题提升多步任务的正确率。数学与定量能力突出在数值计算、逻辑谜题类任务上表现优秀。推理轨迹可访问Reasoning Trace模型的思考过程可通过响应完成对象中的reasoning_content字段获取。在 Roo Code 实现中请求体会显式声明include: [reasoning.encrypted_content]xai.ts而流式处理端 responses-api-stream.ts 会识别response.reasoning_text.delta、response.reasoning.delta等事件类型将思考内容以{ type: reasoning }的流块喂给上层 UI从而实现思考过程可见。六、Prompt 缓存省钱与提速的关键Prompt 缓存是 Grok 系列在 Roo Code 中一个实用的成本优化特性当多次请求共用相同的前缀内容如系统提示、长文档上下文时命中缓存的部分按缓存读取价计费显著低于原始输入价。官方文档明确列出支持 Prompt 缓存的型号grok-code-fast-1、grok-4、grok-3、grok-3-fast、grok-3-mini、grok-3-mini-fast。在仓库模型注册表中所有已注册的 Grok 模型均声明supportsPromptCache: true且每个模型都配置了独立的cacheWritesPrice与cacheReadsPrice见第四节表格用于成本统计。从实现层面看缓存收益会被精确计入用量统计responses-api-stream.ts中的createUsageNormalizer会从响应的input_tokens_details或prompt_tokens_details提取cached_tokens分别归一化为cacheReadTokens与cacheWriteTokensresponses-api-stream.ts再结合cacheReadsPrice计算真实成本。这意味着你在 Roo Code 界面看到的费用明细已经如实反映了 Prompt 缓存带来的折扣。七、底层实现Responses API 调用链路官方文档只讲述了配置与能力仓库源码则展示了完整的调用链路理解它有助于排查问题客户端构建XAIHandler基于 OpenAI SDK 创建客户端baseURL固定为https://api.x.ai/v1并附带DEFAULT_HEADERSxai.ts。消息转换Roo Code 内部使用 Anthropic 格式的消息发送前通过convertToResponsesApiInput转换为 Responses API 的input结构内容部件使用{ type: input_text }系统提示则放入instructions字段responses-api-input.ts。工具声明mapResponseTools将 OpenAI Chat Completions 的工具结构转换为 Responses API 的扁平结构并对 MCP 之外的普通工具启用strict: true的严格 schema强制additionalProperties: false与必填字段校验提升工具调用的稳定性xai.ts。请求组装默认stream: true、store: false不在服务端留存对话保护隐私并透传max_output_tokens、temperature、tools、tool_choice、parallel_tool_calls与可选的reasoningxai.ts。流式消费通过processResponsesApiStream消费 SSE 流把文本增量、推理增量与用量数据统一归一化为 Roo Code 的ApiStream事件responses-api-stream.ts。错误归一化请求失败时经handleOpenAIError包装为带提供商前缀的错误信息如xAI completion error: ...见 xai.spec.ts便于在日志中定位。八、定价与成本提示Grok 各型号定价差异较大以当前注册表为例grok-3与grok-4-0709输入价高达 3.0 美元/百万 token而grok-code-fast-1与 4.1/4 Fast 系列输入价仅 0.2 美元/百万 token相差一个数量级。具体计价以 xAI 控制台实时公示为准Roo Code 内置的价格数据主要用于界面上的成本预估。选型建议基于仓库价格数据的客观对比非性能结论追求性价比的日常编码grok-code-fast-1256K 上下文、低单价是成本敏感场景的合理选择需要超长上下文的复杂 Agent 任务grok-4.20与 4.1/4 Fast 系列提供 2M 上下文且缓存价极低0.05 美元/百万 token配合 Prompt 缓存可显著摊薄成本需要手动控制推理强度grok-3-mini是当前唯一开放reasoning_effort的型号适合在响应速度与深度思考之间做精细权衡。九、常见问题与排查思路报xAI completion error通常是 API Key 无效、余额不足或模型名称不在注册表中。先核对 packages/types/src/providers/xai.ts 中的模型 ID 与设置中的apiModelId是否一致getModel会校验apiModelId in xaiModels不合法时回退到默认模型grok-4.20。设置了推理强度但模型没反应确认当前选中的是grok-3-mini——只有它声明了supportsReasoningEffort其余型号的reasoning_effort会被静默忽略参见 xai.spec.ts 的断言逻辑。想关掉工具apply_diff却出现在面板apply_diff对所有 Grok 型号默认被列入excludedTools如遇异常请检查是否存在全局工具配置覆盖。成本比预期高确认长上下文任务是否命中 Prompt 缓存缓存读写价在模型注册表中单独计价命中缓存后应按cacheReadsPrice远低于输入价计费。结语xAI 的 Grok 系列为 Roo Code 提供了从 128K 到 2M 上下文的完整模型梯度配合grok-3-mini的可调推理强度与全系 Prompt 缓存支持足以覆盖从轻量编码补全到超长文档分析的多类 Agent 场景。官方文档 xai.md 是配置入口而 xai.ts、xai 模型注册表 与 xai.spec.ts 则提供了排查与深挖的源码依据值得按需翻阅。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考