Grok CLI Manual
工作流与排查
把任务、输出和验证方式说清楚，比单纯追求更长的提示词更有效。
会话恢复
grok sessions list
grok --continue
grok --resume <ID_OR_TITLE>--continue 会继续当前目录最近的会话；grok sessions list 用于查找会话，--resume 按 ID 或当前目录下的标题恢复指定会话。
在独立 Worktree 中执行
grok --worktree=feat "实现这个功能，运行测试并总结 diff"这适合试验性修改或与当前工作并行的任务。
无头模式与自检
grok --max-turns 8 -p '定位当前测试失败，做最小修复并重新运行相关测试；结束前检查 diff 和测试结果'把验证要求直接写入提示词；--max-turns 用来限制无头任务的代理轮数。
JSON 输出
grok --output-format json -p '总结当前项目的构建和测试命令'需要稳定结构时：
grok \
--json-schema '{"type":"object","properties":{"build":{"type":"string"},"test":{"type":"string"}},"required":["build","test"]}' \
-p '返回当前项目的构建和测试命令'MCP 与插件
grok mcp --help
grok plugin --help先查看子命令帮助，再根据项目需要添加 MCP 服务或插件。
常见问题
| 现象 | 优先检查 |
|---|---|
grok models 失败 | models_base_url、XAI Router Key 与网络连通性 |
Router Key 调图片时报 Incorrect API key provided | 检查 xai_api_base_url；只配置 models_base_url 时图片请求仍可能直达 api.x.ai |
| 提示 backend 或请求格式错误 | api_backend = "responses" 是否位于正确的模型块 |
| 配置修改后无效 | 运行 grok inspect，确认当前环境读取的文件 |
| 模型不在列表中 | 检查 XAI Router 的模型权限与名称映射 |
| 长会话过早或过晚压缩 | 调整 auto_compact_threshold_percent |
grok 命令不存在 | 重开终端，检查 PATH 和安装位置 |
排查时先运行 grok inspect、grok models 和一条最小 grok -p 请求，可以快速把问题缩小到本地配置、XAI Router 或模型请求层。