Grok CLI 快速参考手册：Reference 项目中基于 xAI Grok 模型的 AI 终端编程助手实战指南

Grok CLI 快速参考手册：Reference 项目中基于 xAI Grok 模型的 AI 终端编程助手实战指南

【免费下载链接】reference⭕ Share quick reference cheat sheet for developers.项目地址: https://gitcode.com/gh_mirrors/re/reference

Grok CLI 是一款由 xAI 的 Grok 模型驱动的对话式 AI 终端工具，能够在命令行中完成文件读写、代码分析、计划模式（Plan Mode）以及与 MCP 服务器的集成。本文以 Reference 仓库中收录的 Grok CLI 速查表 为主体，完整整理其安装、认证、CLI 选项、交互快捷键、工具集、Plan Mode 与 MCP 配置等全部实用要点，并结合仓库的速查表语法规范（见 source/_posts/quickref.md）说明该文档在 Reference 项目中的组织与渲染方式，帮助你快速上手这一 AI 编程助手并高效落地到日常开发流程中。

快速上手（Getting Started）

立即体验（无需安装）

使用npx可以在不安装任何东西的情况下直接运行 Grok CLI，只需通过环境变量注入 API Key：

# 立即运行（无需安装） $ GROK_API_KEY=your_key npx -y grok-cli-hurry-mode@latest # 全局安装 $ npm install -g grok-cli-hurry-mode@latest # 启动交互式会话 $ grok # 发送首条消息 $ grok "Help me understand this project" # Headless / 非交互模式 $ grok -p "explain the auth module" # 使用指定模型 $ grok -m grok-4-latest "refactor this file" # 设置工作目录 $ grok -d /path/to/project # 设置最大工具轮数 $ grok --max-tool-rounds 100 "rewrite the API"

其中-p用于一次性问答（headless 模式），-d将工作目录切换到目标项目，--max-tool-rounds控制 AI 在一轮任务中最多可以调用工具的轮数（默认 400 轮，见下文"全部选项"），适合让模型在大型重构任务中有足够的执行空间。

认证方式（Authentication）

Grok CLI 支持四种 API Key 注入方式，优先级从环境变量到配置文件逐级覆盖：

获取 API Key 请前往 xAI 官方控制台（console.x.ai）。若希望 Key 永久生效，可以将其写入 shell 配置文件：

echo 'export GROK_API_KEY=your_key' >> ~/.zshrc source ~/.zshrc

安装方式（Installation Methods）

环境要求：Node.js（建议最新 LTS 版本）、npm/yarn/pnpm 任一包管理器、可用的网络连接。

AI 模型选择（AI Models）

模型优先级可通过三种途径覆盖：命令行-m参数、GROK_MODEL环境变量、~/.grok/user-settings.json中的model字段。此外还支持自定义 API 端点：-u https://api.x.ai/v1或GROK_BASE_URL环境变量。

CLI 选项与环境变量

全部选项（All Options）

环境变量

子命令（Subcommands）

Grok CLI 提供两个内置子命令，分别用于 Git 提交流程自动化与 MCP 服务器管理：

# AI 生成 git commit 信息并推送 $ grok git commit-and-push $ grok git commit-and-push -d /path/to/repo $ grok git commit-and-push -m grok-4-latest # MCP 服务器管理 $ grok mcp add <name> $ grok mcp add-json <name> <json> $ grok mcp remove <name> $ grok mcp list $ grok mcp test <name>

git commit-and-push子命令支持与主命令相同的-d、-k、-u、-m、--max-tool-rounds参数，意味着你可以为它单独指定工作目录、模型甚至 API 端点，例如针对不同仓库使用不同配置。

交互模式（Interactive Mode）

键盘快捷键（Keyboard Shortcuts）

两个值得重点说明的模式：

• 自动编辑模式（Auto-edit mode）：开启后 AI 会直接编辑文件，不再逐个请求确认，适合对改动方向有明确预期的场景，实现"免打扰"的文件修改。
• 上下文提示（Ctrl+I）：显示项目统计信息、Git 分支、内存压力以及当前会话信息，帮助你了解 AI 眼中的工作区全貌。

斜杠命令（Slash Commands）

这些命令覆盖了文档生成（/readme、/api-docs、/changelog）、Git 协作（/commit-and-push）与系统维护（/heal、/guardrails）三大场景，是日常使用频率最高的交互入口。

配置文件（Config Files）

user-settings.json示例：

{ "apiKey": "your_api_key", "model": "grok-code-fast-1", "baseURL": "https://api.x.ai/v1" }

创建项目上下文：通过.grok/GROK.md可以为 Plan Mode 提供自定义上下文，例如项目约定、架构约束等，让 AI 在分析时遵循团队规范：

# 为 Plan Mode 添加自定义上下文 $ mkdir -p .grok $ echo "# Project Rules" > .grok/GROK.md

工具集（Tools）

Grok CLI 内置三类工具，AI 会根据请求自动选择合适的工具组合，无需手动指定。

核心工具（Core Tools）

• Read支持通过 offset/limit 分段读取大文件，并且能以视觉方式展示图片内容；
• Edit支持精确字符串替换、正则表达式模式，以及单处或全部出现位置的替换；
• Bash支持 stdout/stderr 捕获、后台进程、超时管理以及环境变量处理。

高级工具（Advanced Tools）

• MultiEdit在单个原子事务内完成 create、edit、delete、rename、move 等操作，任何一步失败都可整体回滚，避免多文件改动出现"半成品"状态；
• Task（子代理委派）具备 token 优化的处理能力，适合复杂的调研与分析，并能自主完成任务后输出报告；
• WebFetch将 HTML 转换为 Markdown，配合 AI 内容抽取与缓存，减少重复抓取开销。

IDE 工具（IDE Tools）

Plan Mode（计划模式）

Plan Mode 是 Grok CLI 面向"先规划、后执行"工作流设计的核心能力：在动手改代码之前，先让 AI 调研代码库并生成一份可审阅的执行计划。

激活方式（Activating Plan Mode）

快速连按两次Shift+Tab，终端会出现如下提示：

🎯 Plan Mode: Analysis 📊 Exploring codebase and gathering insights...

或者使用 headless 模式：

$ grok -p "analyze changes in this PR and create plan" $ grok -p "check if changes follow architecture guidelines"

Plan Mode 中禁止的操作：

• 所有文件写入/编辑操作
• 破坏性 bash 命令
• 任何会修改状态的操作

Plan Mode 中允许的操作：

• 读取文件（ls、cat、grep）
• 网络搜索与抓取
• 项目结构分析
• 生成计划（仅写入计划输出）

退出 Plan Mode：

• Enter—— 确认并执行计划
• Esc—— 不执行直接退出

Plan Mode 四个阶段（Phases）

Plan Mode 会重点分析：项目类型（Node/Python/React 等）、目录结构、关键组件、依赖关系、入口文件、模块划分以及架构模式。

使用技巧（Tips）

建议在以下场景使用 Plan Mode：

• 复杂的多文件功能开发
• 大规模重构
• 探索陌生代码库
• 改动前的风险评估

技巧要点：

• 把需求描述得具体明确
• 批准前认真审阅计划
• 出问题时使用/heal自检
• 创建.grok/GROK.md注入自定义上下文

MCP 服务器管理

MCP（Model Context Protocol）让 Grok CLI 能够接入外部工具与数据源，扩展其能力边界。

命令行管理

# 添加 stdio 服务器 $ grok mcp add myserver \ -t stdio \ -c npx \ -a -y my-mcp-package # 添加 HTTP/SSE 服务器 $ grok mcp add myserver \ -t http \ -u https://api.example.com/mcp # 添加并携带环境变量与请求头 $ grok mcp add myserver \ -t http \ -u https://api.example.com/mcp \ -e API_KEY=secret \ -h Authorization="Bearer token" # 通过原始 JSON 添加 $ grok mcp add-json myserver \ '{"transport":{"type":"stdio","command":"npx","args":["-y","pkg"]}}' # 列出所有服务器 $ grok mcp list # 测试连接 $ grok mcp test myserver # 移除服务器 $ grok mcp remove myserver

MCP 配置 Schema

在.grok/settings.json中可持久化配置多个 MCP 服务器：

{ "mcpServers": [ { "name": "my-server", "transport": { "type": "stdio", "command": "npx", "args": ["-y", "my-mcp-package"], "env": { "KEY": "value" } } }, { "name": "remote-server", "transport": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer $TOKEN" } } } ] }

传输类型（Transport Types）

添加服务器选项

故障排查（Troubleshooting）

常见问题（Common Issues）

API Key 未找到：

# 检查环境变量是否已设置 $ echo $GROK_API_KEY # 或使用内联方式传入 $ GROK_API_KEY=key grok "hello"

安装后提示 command not found：

# 将 npm 全局 bin 目录加入 PATH $ echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc $ source ~/.zshrc $ which grok

安装时权限报错：

# 使用 sudo（不推荐）或改用 node 版本管理器 $ npm install -g grok-cli-hurry-mode --force # 推荐：使用 nvm/fnm 后无需 sudo $ nvm use --lts $ npm install -g grok-cli-hurry-mode

卡死 / 缓存导致安装异常：

$ pkill -f grok $ npm uninstall -g grok-cli-hurry-mode $ npm cache clean --force $ npm install -g grok-cli-hurry-mode@latest

常用环境变量

默认 API 端点：https://api.x.ai/v1

Git Smart Push

Grok CLI 的自动化发布系统会创建版本号 bump 提交，因此始终建议使用智能推送（smart push）以避免冲突：

# 正确 —— 自动处理版本号自动 bump $ npm run smart-push $ git pushup # 错误 —— 会触发 "fetch first" 报错 $ git push origin main

该速查表在 Reference 仓库中的组织方式

本文内容来自 Reference 项目速查表集合中的 Grok CLI 速查表。该仓库将所有速查表以 Markdown 源文件形式存放在source/_posts/目录下，每篇文档通过 YAML front matter 声明标题、标签、分类与简介，正文则使用 quickref.md 中定义的"魔术语法"进行排版：

• 二级标题（##）作为章节（Section），三级标题（###）作为卡片（Card），例如本文档使用{.cols-3}将"Getting Started"章节编排为三栏布局，用{.row-span-2}让"Quick Start"卡片跨两行展示；
• 快捷键类表格通过{.shortcuts}标记渲染为按键风格；长命令行代码块通过{.wrap}标记自动换行；
• 每个章节均可通过{.cols-n}自由调整列数，卡片可通过{.col-span-n}、{.row-span-n}控制跨列跨行。

此外，仓库为速查表配套了对应图标资源 source/assets/icon/grok-cli.svg，用于在速查表入口页展示。若你想为本主题贡献或修正内容，只需按上述语法编辑source/_posts/下的 Markdown 源文件并提交合并请求即可。

小结

Grok CLI 将 xAI Grok 模型的对话能力与终端工作流深度绑定：从免安装的npx快速启动、多途径认证、模型切换，到自动编辑模式、Plan Mode 四阶段工作流，再到通过 MCP 协议接入外部服务器，构成了一个完整的"调研—规划—执行—校验"AI 编程闭环。配合本文整理的快捷键、斜杠命令与故障排查清单，你可以快速定位所需用法，将其无缝集成到个人或团队的项目开发流程中。

【免费下载链接】reference⭕ Share quick reference cheat sheet for developers.项目地址: https://gitcode.com/gh_mirrors/re/reference