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/referenceGrok 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_KEYyour_key npx -y grok-cli-hurry-modelatest # 全局安装 $ npm install -g grok-cli-hurry-modelatest # 启动交互式会话 $ 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 轮见下文全部选项适合让模型在大型重构任务中有足够的执行空间。认证方式AuthenticationGrok CLI 支持四种 API Key 注入方式优先级从环境变量到配置文件逐级覆盖方式操作环境变量export GROK_API_KEYyour_key内联npxGROK_API_KEYkey npx grok-cli-hurry-modelatestCLI 参数grok --api-key your_key配置文件在~/.grok/user-settings.json中设置apiKey获取 API Key 请前往 xAI 官方控制台console.x.ai。若希望 Key 永久生效可以将其写入 shell 配置文件echo export GROK_API_KEYyour_key ~/.zshrc source ~/.zshrc安装方式Installation Methods方式命令npm推荐npm install -g grok-cli-hurry-modelatestnpx免安装npx grok-cli-hurry-modelatestyarnyarn global add grok-cli-hurry-modelatestpnpmpnpm add -g grok-cli-hurry-modelatestbunbun add -g grok-cli-hurry-modelatest自动脚本curl -fsSL install.sh 地址 \| bash项目仓库提供的官方安装脚本环境要求Node.js建议最新 LTS 版本、npm/yarn/pnpm 任一包管理器、可用的网络连接。AI 模型选择AI Models模型说明grok-code-fast-1默认模型针对代码场景优化grok-4-latest最新模型能力更强grok-3-fast快速通用模型模型优先级可通过三种途径覆盖命令行-m参数、GROK_MODEL环境变量、~/.grok/user-settings.json中的model字段。此外还支持自定义 API 端点-u https://api.x.ai/v1或GROK_BASE_URL环境变量。CLI 选项与环境变量全部选项All Options选项别名说明--api-key key-kGrok API Key--base-url url-uAPI 基础地址--model model-m指定使用的模型--prompt text-pHeadless 模式下的提示词--directory dir-d设置工作目录--max-tool-rounds n—最大工具轮数默认400--version-V显示版本号--help-h显示帮助信息环境变量变量用途GROK_API_KEYAPI Key必填GROK_MODEL默认模型GROK_BASE_URL自定义 API 端点子命令SubcommandsGrok 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 namegit commit-and-push子命令支持与主命令相同的-d、-k、-u、-m、--max-tool-rounds参数意味着你可以为它单独指定工作目录、模型甚至 API 端点例如针对不同仓库使用不同配置。交互模式Interactive Mode键盘快捷键Keyboard Shortcuts按键作用ShiftTab按两次进入 Plan ModeShiftTab切换自动编辑模式auto-editCtrlI上下文提示工作区信息CtrlC清空当前输入Esc中断当前操作↑/↓浏览输入历史两个值得重点说明的模式自动编辑模式Auto-edit mode开启后 AI 会直接编辑文件不再逐个请求确认适合对改动方向有明确预期的场景实现免打扰的文件修改。上下文提示CtrlI显示项目统计信息、Git 分支、内存压力以及当前会话信息帮助你了解 AI 眼中的工作区全貌。斜杠命令Slash Commands命令说明/help显示可用命令/clear清空终端屏幕/models列出可用模型/exit退出应用/compact压缩对话上下文/commit-and-pushAI 生成 commit 信息并推送/init-agent初始化 agent 文档/docs打开文档/readme生成 README/api-docs生成 API 文档/changelog生成变更日志/comments添加代码注释/update-agent-docs更新 agent 文档/heal自愈式系统检查/guardrails显示护栏guardrails状态这些命令覆盖了文档生成/readme、/api-docs、/changelog、Git 协作/commit-and-push与系统维护/heal、/guardrails三大场景是日常使用频率最高的交互入口。配置文件Config Files文件用途~/.grok/user-settings.json全局用户设置.grok/settings.json项目级设置.grok/GROK.md项目上下文供 AI 读取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工具集ToolsGrok CLI 内置三类工具AI 会根据请求自动选择合适的工具组合无需手动指定。核心工具Core Tools工具用途Read读取文件——文本、图片、PDF、NotebookWrite创建或覆盖文件Edit精确的字符串查找替换Bash执行 shell 命令Grep基于 ripgrep 的正则搜索Glob文件模式匹配LS目录列表Read支持通过 offset/limit 分段读取大文件并且能以视觉方式展示图片内容Edit支持精确字符串替换、正则表达式模式以及单处或全部出现位置的替换Bash支持 stdout/stderr 捕获、后台进程、超时管理以及环境变量处理。高级工具Advanced Tools工具用途MultiEdit原子化多文件编辑支持回滚WebFetch抓取并解析网页内容WebSearch实时网络搜索Task委派给专门的子代理sub-agentTodoWrite任务跟踪与进度管理MultiEdit在单个原子事务内完成 create、edit、delete、rename、move 等操作任何一步失败都可整体回滚避免多文件改动出现半成品状态Task子代理委派具备 token 优化的处理能力适合复杂的调研与分析并能自主完成任务后输出报告WebFetch将 HTML 转换为 Markdown配合 AI 内容抽取与缓存减少重复抓取开销。IDE 工具IDE Tools工具用途NotebookEdit编辑 Jupyter Notebook 单元格BashOutput流式输出后台进程结果KillBash终止后台进程Plan Mode计划模式Plan Mode 是 Grok CLI 面向先规划、后执行工作流设计的核心能力在动手改代码之前先让 AI 调研代码库并生成一份可审阅的执行计划。激活方式Activating Plan Mode快速连按两次ShiftTab终端会出现如下提示 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 guidelinesPlan Mode 中禁止的操作所有文件写入/编辑操作破坏性 bash 命令任何会修改状态的操作Plan Mode 中允许的操作读取文件ls、cat、grep网络搜索与抓取项目结构分析生成计划仅写入计划输出退出 Plan ModeEnter—— 确认并执行计划Esc—— 不执行直接退出Plan Mode 四个阶段Phases阶段耗时发生什么 Analysis分析1–5 秒识别项目类型、结构、依赖 Strategy策略5–15 秒AI 生成实现计划 Presentation呈现1–2 秒格式化计划供审阅✅ Approval审批用户控制审阅、确认或细化Plan Mode 会重点分析项目类型Node/Python/React 等、目录结构、关键组件、依赖关系、入口文件、模块划分以及架构模式。使用技巧Tips建议在以下场景使用 Plan Mode复杂的多文件功能开发大规模重构探索陌生代码库改动前的风险评估技巧要点把需求描述得具体明确批准前认真审阅计划出问题时使用/heal自检创建.grok/GROK.md注入自定义上下文MCP 服务器管理MCPModel 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_KEYsecret \ -h AuthorizationBearer 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 myserverMCP 配置 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类型适用场景stdio本地子进程默认http远程 HTTP 端点sseServer-Sent Events服务端推送streamable_http流式 HTTP添加服务器选项选项别名说明--transport type-tstdio / http / sse / streamable_http--command cmd-c可执行命令仅 stdio--args [args...]-a命令参数仅 stdio--url url-u服务器地址http/sse--headers [kv...]-hHTTP 请求头keyvalue形式--env [kv...]-e环境变量keyvalue形式故障排查Troubleshooting常见问题Common IssuesAPI Key 未找到# 检查环境变量是否已设置 $ echo $GROK_API_KEY # 或使用内联方式传入 $ GROK_API_KEYkey 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-modelatest常用环境变量变量说明GROK_API_KEYAPI Key必填GROK_MODEL覆盖默认模型GROK_BASE_URL自定义 API 端点默认 API 端点https://api.x.ai/v1Git Smart PushGrok 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考