Grok CLI 中转站完整配置教程：Windows / macOS / Linux 安装、API 接入与 Grok Build 使用指南

type

status

date

slug

summary

1. 开始前需要准备什么

Grok Build 可以阅读项目、规划任务、修改文件、运行命令，并通过子代理分工处理较大的开发任务。复杂任务可以先进入 Plan Mode，在批准计划后再开始实施。功能介绍见 Grok Build 官方页面。

准备以下内容：

终端环境：macOS 的终端、Linux 的 Bash，或 Windows 的 Git Bash / WSL。

Git：用于查看改动、管理分支和回退代码，建议在项目根目录运行。

API 密钥：在 https://api.aigc.bar 获取具有目标模型权限的密钥。

接口兼容性：确认目标模型可通过 Responses API 使用；可用模型、额度和计费规则以控制台为准。

项目依赖：开发 React 项目通常需要 Node.js，开发 Rust 项目需要 Rust 工具链。Grok CLI 本身通过官方安装脚本下载二进制文件，不要求先通过 npm 安装。

本文统一使用以下地址：

用途	地址
中转平台 / 账户与令牌管理	https://api.aigc.bar
API Base URL	https://api.aigc.bar/v1

2. 获取 API Key

打开 https://api.aigc.bar，注册或登录账户。

在控制台找到 API 令牌管理入口，创建用于 Grok CLI 的令牌。

选择支持目标 Grok CLI分组，确认账户余额、令牌额度以及模型访问权限。

4.复制 API Key，稍后填写到 config.toml 的 api_key 字段。

5.记录控制台提供的准确模型 ID，用于配置 model 字段。

界面名称和分组可能调整，应以控制台实际显示为准。密钥请保存在个人配置中，不要提交到项目仓库或贴到公开截图中。

3. 安装 Grok CLI

Windows：使用 Git Bash 安装

先安装 Git for Windows，然后打开 Git Bash，运行：

安装完成后关闭并重新打开 Git Bash，再检查版本：

这条安装命令使用 Bash，请在 Git Bash 中执行。若要在 PowerShell 或 CMD 中运行已安装的 grok，需将 %USERPROFILE%\.grok\bin 加入用户的 Path 环境变量，然后重新打开终端。

使用 WSL 的情况：进入 WSL 的 Linux 终端，按下面的 Linux 方式安装。WSL 使用自己的 Linux 用户目录和配置文件，不会自动使用 Windows 用户目录里的配置。

macOS：在终端中安装

打开“终端”，执行：

重新打开终端，验证：

Linux：在 Bash 中安装

确认系统已安装 curl 和 bash。例如 Ubuntu / Debian 可以先运行：

随后安装并验证：

重新打开终端后执行：

上述安装方式和 Windows Bash 支持来自 xAI 官方安装脚本。默认二进制目录为用户目录下的 .grok/bin；如果提示找不到 grok，先重新打开终端，再检查 PATH。

4. 配置 https://api.aigc.bar 接口

找到配置文件

三个系统使用相同的 TOML 配置结构，主要区别是文件路径：

环境	配置文件
Windows 原生 / Git Bash	`%USERPROFILE%\.grok\config.toml`
macOS	`~/.grok/config.toml`
Linux / WSL	`~/.grok/config.toml`

先备份已有配置，再合并下面的内容。 安装器可能已写入 [cli] 等配置，应保留；如果已有 [models] 或 [model.grok]，修改对应段落即可，不要重复添加同名 TOML 表。

Windows：创建目录并打开配置

在 PowerShell 中运行：

如果记事本提示新建文件，选择创建。保存时确认文件名是 config.toml，而不是 config.toml.txt。

macOS / Linux / WSL：创建目录并打开配置

在终端执行：

也可以用自己熟悉的文本编辑器。使用 Nano 时，完成编辑后按 Ctrl + O、回车保存，再按 Ctrl + X 退出。

填写 TOML 配置

下面沿用参考教程的 grok-4.6 作为模型 ID 示例。使用前必须确认 https://api.aigc.bar 控制台提供这个模型，或者换成控制台实际提供的 ID。 context_window 和 supports_backend_search 也应按该接口实际能力填写；示例中的 100 万上下文和后端搜索并不代表所有渠道都支持。

字段	如何填写
`default = "grok"`	默认选择下面 `[model.grok]` 定义的本地模型配置
`model`	平台实际支持的模型 ID，不能只根据产品展示名称猜测
`base_url`	统一填写 `https://api.aigc.bar/v1`，不要重复加 `/v1`
`api_key`	把 `YOUR_API_KEY` 替换为自己的真实 API 密钥
`api_backend`	本示例使用 `responses`，需要中转接口支持该协议
`default_reasoning_effort`	示例为 `high`；按任务复杂度和模型支持情况调整
`context_window`	模型与接口实际支持的上下文上限；不是填大就能扩大容量
`web_search` / `supports_backend_search`	搜索使用的模型和后端搜索能力声明；不支持时不要照搬开启

5. 启动与验证配置

进入项目根目录再启动：

将 your-project 替换为自己的项目路径。启动后先发送一条简单指令：

收到正常回复后，在平台控制台检查请求记录，确认使用的是预期令牌和模型。界面显示的模型名称不足以单独证明请求已走指定中转，应结合实际请求记录确认。

需要排查当前项目加载了哪些配置、技能和插件时，可以运行：

查看已配置的模型、环境诊断和完整命令帮助：

分享诊断信息前，检查输出中是否含有密钥或私人路径。

6. TUI 界面操作指南

TUI 就是直接运行 grok 后出现的终端交互界面。输入框可以直接输入中文或英文需求；键盘快捷键用于切换模式，鼠标操作和图片粘贴的效果取决于终端与当前版本的支持情况。

新手先输入 /help。帮助面板会展示当前版本可用的命令及操作方式。下面汇总常见命令；别名和参数形式应以本机帮助为准。

命令	用途
`/help`	打开帮助面板，查看当前版本的命令和快捷键
`/plan`	进入规划模式；部分版本支持 `/plan on` 和 `/plan off`
`/yolo` 或 `/always-approve`	自动批准模式的常见入口或别名；请查看当前版本帮助确认
`/model <模型名>`	切换模型，例如选择已配置的 `grok`
`/effort <等级>`	调整推理强度，例如 `low`、`medium`、`high`、`xhigh`；取决于模型支持
`/inspect`	查看当前项目的配置、技能和插件；终端中也可用 `grok inspect`
`/feedback`	向 xAI 反馈使用问题
`/clear`	清空当前会话历史

斜杠命令在 Grok 的输入框里输入；grok inspect、grok --help 等命令在系统终端中运行。

自动批准模式会减少工具执行前的确认。日常使用可先保留默认审批；熟悉任务范围后，再按需要启用。当前核对版本也支持启动参数 --always-approve。

7. Plan Mode：复杂任务先规划

涉及多文件重构、新建项目或较大功能时，建议先进入 Plan Mode。Grok 会先分析需求并提出步骤，你可以补充限制、评论某一步，或要求重写计划。批准计划之后才进入实施阶段；完成修改后继续查看 diff 和测试结果。官方 Plan 功能介绍

方法一：通过快捷键切换

在 TUI 中尝试按 Shift + Tab 循环切换模式，直到状态栏显示 Plan。若快捷键行为与预期不同，打开 /help 查看本机版本的绑定。

方法二：使用斜杠命令

在 TUI 中输入：

支持开关参数的版本也可以使用 /plan on。退出时按 Shift + Tab 切回 Normal / 默认模式，或使用本机支持的 /plan off。

方法三：启动时进入规划模式

本文核对的 grok 1.0.25 使用：

一些旧教程写作 grok --plan，但本次核对版本会报 unexpected argument '--plan'。遇到参数差异，以 grok --help 中的 --permission-mode 选项为准。

一套实用的规划流程

说明目标、技术栈、约束和验收标准。

要求先列出需要改动的文件、主要风险和测试方法。

阅读计划，在对应步骤补充意见；需要大改时要求重新规划。

使用界面提供的批准操作开始实施。

检查最终 diff，运行相关测试，再决定是否提交代码。

可以直接使用下面的提示词：

8. 基本使用示例

示例一：从零创建 React + TypeScript Todo App

先建立空目录并进入规划模式：

输入需求：

批准计划后，可以让它按需要创建 package.json、组件和样式文件，并协助安装依赖、运行开发命令。具体操作仍取决于任务要求、审批设置和本机环境。

建议验收这些行为：

新增、编辑、完成和删除任务正常工作。

暗黑模式可以切换，并在刷新后保留选择。

拖拽排序正常，刷新后任务和顺序仍然存在。

项目提供清晰的启动说明，并运行了相关检查。

拖拽可以选用 @dnd-kit，状态管理可以选用 Zustand，持久化可以使用 localStorage；在规划阶段确定是否需要这些依赖。

后续可以追加：

准备部署时可以说：

示例二：分析现有项目

在仓库根目录启动 Grok，输入：

示例三：重构代码并添加错误处理

若项目中存在 src/main.rs，可以引用该文件：

将路径替换为实际文件；文件引用补全是否可用，以当前 TUI 为准。

示例四：让子代理并行处理大型任务

Grok Build 支持让多个子代理各自处理任务，再由主代理汇总。适合前端、后端、测试等可以明确分工的工作；子代理的上下文与工作目录隔离方式见官方说明。

并行不是每个任务都需要开启；如果任务较小，直接顺序完成通常更容易核对。

9. 无头模式：脚本与自动化

无头模式适合批处理、CI/CD 和集成到其他工具。使用 -p 提供一次性任务：

也可以用于代码任务：

具体工具执行仍受当前权限策略影响；无人值守环境应事先配置工作目录、凭据和允许执行的操作。

输出 JSON

输出流式 JSON

streaming-json 输出的是 NDJSON 事件流：按行解析 JSON，每行对应一条 ACP 会话更新。不要把整段输出当成单个 JSON 对象直接解析。

也可以明确指定工作目录和最大轮数：

10. 高级功能与项目配置

功能	用途	上手方式
并行子代理	拆分较大且可独立处理的任务	在需求里说明分工和文件范围
Git 集成	查看差异、管理分支、暂存、提交和推送	明确说出要执行的 Git 操作，并检查结果
AGENTS.md	固定项目规则、代码风格和测试要求	在项目根目录维护项目指令文件
技能与插件	复用领域流程或扩展能力	通过 `/inspect` 或 `grok inspect` 检查实际加载情况
MCP	连接外部工具和数据源	从 `grok mcp --help` 查看配置入口
自定义模型	使用不同模型配置	在配置文件中定义，再通过 `/model` 或 `--model` 选择
ACP / 工具集成	与支持相关协议的客户端协作	按目标客户端的接入文档设置；流式事件格式见上一节
Inspect	排查配置、技能和插件的加载情况	`grok inspect`；需要机器读取时可查看 `--json` 选项

技能、插件、Hooks、MCP 和项目指令的能力介绍见 Grok Build 官方页面。扩展通常有各自的目录与配置要求，放入项目后应通过 Inspect 确认是否加载成功。

一个简洁的 AGENTS.md 示例

在项目根目录创建 AGENTS.md：

若仓库已有 AGENTS.md，请合并规则，避免覆盖原有项目约定。

Git 操作提示词

生成 PR 还需要对应代码托管平台的工具和认证，能否直接创建取决于本机环境。

11. 实用技巧与常见问题

日常操作技巧

在仓库根目录启动，让工具更容易识别项目规则与版本控制状态。

大任务先用 Plan Mode，把任务拆成可以验收的步骤。

提示词写清验收条件，例如刷新后数据仍在、移动端能用、相关测试通过。

图片辅助排查：终端和当前版本支持时，可粘贴截图分析 UI 或报错；同时提供复现步骤和关键日志。

多个实例同时工作：尽量使用不同分支和 Git worktree，避免同时改写同一批文件。

适度使用推理强度：简单说明或小改动不必总选最高等级，按模型支持情况调整。

及时整理上下文：长对话先让它记录进度与未完成事项，再清理或新建会话。

遇到产品问题：使用 /feedback 提供版本、复现步骤和经过脱敏的日志。

常见故障排查表

问题	排查方式
`grok: command not found`	重新打开终端；检查 `.grok/bin` 是否在 PATH，Windows 检查用户 Path
安装脚本无法运行	确认正在使用 Bash；Windows 请用 Git Bash 或 WSL，并确认可访问官方安装地址
401 / Unauthorized	检查 API Key 是否完整、是否仍有效，是否有空格，以及令牌权限与余额
403 / 权限不足	检查所选令牌分组、模型授权和平台访问限制
404 / 模型不存在	检查 Base URL 是否为 `https://api.aigc.bar/v1`，确认准确模型 ID 及 Responses API 支持情况
请求超时	检查网络和平台服务状态，先用短提示词验证，避免一开始就发送整个大仓库
搜索或上下文相关报错	核对 `supports_backend_search` 与 `context_window`，按接口实际能力配置
TOML 解析失败	检查英文引号、等号与表名，避免重复 `[models]`、`[model.grok]`，确认未保存成 `.txt`
切换后仍使用旧模型	重启 Grok，检查当前模型选择，并用 `grok inspect` 排查实际生效配置
控制台没有预期请求记录	检查所用密钥和模型配置，排查是否仍选中了其他模型或认证方式
`--plan` 参数不识别	本文核对版本使用 `--permission-mode plan`；以 `grok --help` 为准
找不到教程中的斜杠命令	在 TUI 输入 `/help` 查看当前版本，留意命令更名和别名差异

更新与卸载

需要更新时，先查看当前安装方式对应的更新选项：

卸载时先确认实际二进制位置，并按官方说明移除。.grok 目录可能包含密钥、配置与会话记录；不要为了移除可执行文件就直接删除整个目录。

参考资料

Grok Build 官方介绍与安装入口

xAI 官方安装脚本

本文使用的 API 平台

本机命令帮助：grok --help、grok inspect --help、grok models --help；核对版本 grok 1.0.25。