reference 速查清单:Grok CLI(非官方版)从安装认证到 Plan Mode 与 MCP 的完整实战指南【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference本文基于 Grok CLI 备忘清单(非官方) 整理,覆盖 Grok CLI 的安装与免安装运行、四种认证方式、全部 CLI 选项与环境变量、子命令、交互模式快捷键与 Slash 命令、配置文件、工具体系、Plan Mode 工作流以及 MCP 服务器管理。读完后,你可以直接在终端跑起 Grok 驱动的 AI 编码会话,配置项目级上下文与 MCP 服务器,并在需要时切换到只读的计划模式完成复杂变更前的风险评估。一、Grok CLI 是什么:定位与版本区分Grok CLI 是一个由 X.AI 的 Grok 模型驱动的对话式 AI 终端工具,核心能力包括文件操作、代码分析、Plan Mode(先规划后执行)与 MCP(Model Context Protocol)服务器集成。在 reference 项目的 AI 分类卡片中,Grok CLI 与 Claude Code、Codex CLI、Cursor CLI、Gemini CLI 等并列为终端 AI 编码工具速查入口,对应的速查文档即为本文所依据的 docs/grok-cli.md。需要注意,reference 仓库中同时收录了两份 Grok CLI 速查,定位不同,使用时不要混淆:维度非官方版(本文主题)官方版(docs/grok.md)安装渠道npm 生态:grok-cli-hurry-mode包curl -fsSL https://x.ai/cli/install.sh \| bash官方安装脚本API key 变量GROK_API_KEYXAI_API_KEY配置格式JSON:~/.grok/user-settings.json、.grok/settings.jsonTOML:~/.grok/config.toml特色能力git commit-and-push、mcp子命令、/heal、/guardrails会话续跑(-s/-r/-c)、grok inspect、ACP(JSON-RPC over stdio)集成模型覆盖grok-code-fast-1、grok-4-latest、grok-3-fast支持在config.toml中声明任意自定义模型从两份文档并列收录的结构可以推断,reference 项目的意图是让开发者按自身环境选择:走 npm 包生态的团队适合非官方版;追求官方维护通道与 IDE/脚本平台 ACP 集成的用户适合官方版。本文后续全部内容均围绕非官方版展开。二、快速上手:从免安装运行到常用启动姿势最快的体验方式是免安装直跑,通过 npx 一次性拉起最新版:# 立即运行(无需安装) $ GROK_API_KEYyour_key npx -y grok-cli-hurry-modelatest确认体验良好后再做全局安装并进入交互会话:# 全局安装 $ npm install -g grok-cli-hurry-modelatest # 启动交互会话 $ grok # 发送初始消息 $ grok Help me understand this project几个高频启动姿势:# 无头 / 非交互模式(适合脚本与 CI) $ 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(无头模式)让 CLI 发送一条提示后返回,适合串联进自动化流程;-d指定工作目录后可脱离当前 shell 所在路径运行;--max-tool-rounds控制 AI 连续调用工具的上限,该选项默认值为 400,上例将其收紧到 100,适合对执行时长敏感的任务。三、认证:四种提供 API key 的方式Grok CLI 的 API key 从 xAI 官方控制台(console.x.ai)获取。支持以下四种提供方式,优先级上建议开发期用环境变量、脚本期用内联或参数、长期配置用配置文件:方式用法环境变量export GROK_API_KEYyour_key内联(npx)GROK_API_KEYkey npx grok-cli-hurry-modelatestCLI 参数grok --api-key your_key(别名-k)配置文件在~/.grok/user-settings.json中设置apiKey字段写入 shell 配置以持久生效:echo export GROK_API_KEYyour_key ~/.zshrc source ~/.zshrc四、安装方式与运行要求方式命令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 https://raw.githubusercontent.com/hinetapora/grok-cli-hurry-mode/main/install.sh \| bash运行要求:Node.js(最新 LTS)、npm/yarn/pnpm 任一包管理器、可用的网络连接。由于工具本身是 npm 包,Node 版本管理器(nvm/fnm)在解决全局安装权限问题上是官方排查方案推荐的路径(见第九节故障排查)。五、AI 模型与自定义基础 URL内置可选模型:模型说明grok-code-fast-1默认,针对代码任务优化grok-4-latest最新版本,能力增强grok-3-fast更快,通用场景模型覆盖有三级途径,可按需组合:命令行参数-m model(单次生效);环境变量GROK_MODEL(会话级默认);~/.grok/user-settings.json中的model字段(持久默认)。如果走代理网关或自建端点,可通过-u参数或GROK_BASE_URL环境变量覆盖默认基础 URL(默认为https://api.x.ai/v1):$ grok -u https://api.x.ai/v1 ...六、CLI 选项与环境变量全表选项别名说明--api-key key-kGrok API key--base-url url-uAPI 基础 URL--model model-m指定模型--prompt text-p无头模式提示词--directory dir-d设置工作目录--max-tool-rounds n无最大工具轮次(默认:400)--version-V显示版本--help-h显示帮助环境变量:变量用途GROK_API_KEYAPI key(必需)GROK_MODEL默认模型GROK_BASE_URL自定义 API 端点默认 API 端点:https://api.x.ai/v1七、子命令:git 智能提交与 MCP 管理入口7.1git commit-and-pushAI 分析工作区变更后自动生成提交信息并推送:# AI 生成提交并推送 $ grok git commit-and-push $ grok git commit-and-push -d /path/to/repo $ grok git commit-and-push -m grok-4-latest该子命令支持与主命令相同的-d、-k、-u、-m、--max-tool-rounds参数,因此可以在指定目录、指定模型、指定端点的前提下独立运行。7.2mcp服务器管理# MCP 服务器管理 $ grok mcp add name $ grok mcp add-json name json $ grok mcp remove name $ grok mcp list $ grok mcp test namemcp add的完整参数与典型命令示例见第十一节,mcp test name用于在改动后验证连通性,mcp list用于盘点当前项目已注册的服务器。八、交互模式:快捷键、Slash 命令与自动编辑8.1 键盘快捷键按键操作ShiftTab连按两次进入 Plan ModeShiftTab切换自动编辑模式CtrlI上下文提示(工作区信息)CtrlC清空当前输入Esc中断当前操作↑/↓浏览输入历史两个值得展开的机制:自动编辑模式:开启后免确认文件编辑,AI 会直接修改文件而不弹出确认提示。适合对信任度较高的会话,配合 Plan Mode 使用可以形成先只读规划、批准后再放开写入的完整闭环。上下文提示(CtrlI):显示项目统计、git 分支、内存压力与会话信息,长会话中可快速判断上下文是否已接近饱和(配合/compact使用)。8.2 Slash 命令命令说明/help显示可用命令/clear清空终端屏幕/models列出可用模型/exit退出应用/compact压缩会话上下文/commit-and-pushAI 生成提交信息并推送/init-agent初始化 agent 文档/docs打开文档/readme生成 README/api-docs生成 API 文档/changelog生成变更日志/comments添加代码注释/update-agent-docs更新 agent 文档/heal自愈系统检查/guardrails显示护栏状态Slash 命令大体分为三类:会话管理(/help、/clear、/exit、/compact)、文档与提交生成(/readme、/api-docs、/changelog、/comments、/commit-and-push)、代理工程(/init-agent、/update-agent-docs、/heal、/guardrails)。其中/heal是 Plan Mode 工作流中推荐的兜底手段——当批准后的执行出现问题时,用它触发自愈检查;/guardrails则用于查看当前会话的护栏(行为边界)状态。九、配置文件:全局、项目与项目上下文三级文件用途~/.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 }创建项目上下文:# 为 Plan Mode 添加自定义上下文 $ mkdir -p .grok $ echo # Project Rules .grok/GROK.md.grok/GROK.md是喂给 AI 的项目规则文档,通常写明代码风格约定、目录结构约束、禁改区域等,Plan Mode 在生成计划时会参考这些内容。三级配置的职责划分:全局user-settings.json管密钥与默认端点,项目级.grok/settings.json管该仓库的 MCP 服务器等工程配置,.grok/GROK.md管AI 应该知道这个项目的哪些规则。十、工具体系:核心、高级与 IDE 工具AI 会为每个请求自动选择合适的工具组合,无需手动调用,但了解工具面有助于理解会话中出现的操作类型。核心工具:工具用途Read读取文件:文本、图片、PDF、notebookWrite创建或覆盖文件Edit精确字符串查找替换Bash执行 shell 命令Grep通过 ripgrep 进行正则搜索Glob文件模式匹配LS目录列表关键细节:Read支持大文件的行偏移/行数限制,并可直接显示图片;Edit支持精确字符串替换、正则模式、单次或全量替换;Bash支持 stdout/stderr 捕获、后台进程、超时管理、环境变量处理。高级工具:工具用途MultiEdit原子化多文件编辑(支持回滚)WebFetch抓取并解析网页内容WebSearch实时网页搜索Task委派给专用子代理TodoWrite任务追踪与进度管理MultiEdit的操作包括创建、编辑、删除、重命名、移动,均在一次原子事务中完成,失败可整体回滚;Task(子代理委派)面向 token 成本优化与复杂调研分析,子代理自动完成后输出报告;WebFetch支持 HTML 到 Markdown 转换,并带 AI 内容提取与缓存。IDE 工具:工具用途NotebookEdit编辑 Jupyter notebook 单元BashOutput流式查看后台进程输出KillBash终止后台进程十一、MCP 服务器:注册、结构与传输类型11.1 管理命令实战# 添加 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 myserver11.2grok mcp add参数选项别名说明--transport type-tstdio / http / sse / streamable_http--command cmd-c可执行命令(仅 stdio)--args [args...]-a命令参数(仅 stdio)--url url-u服务器 URL(http/sse)--headers [kv...]-hHTTP 请求头(keyvalue)--env [kv...]-e环境变量(keyvalue)11.3 配置结构与传输类型MCP 服务器最终持久化在.grok/settings.json的mcpServers数组中:{ 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 } } } ] }传输类型:类型适用场景stdio本地子进程(默认)http远程 HTTP 端点sseServer-Sent Eventsstreamable_http流式 HTTP选型上,本地 npm 生态的 MCP 包(如通过npx拉起)用stdio;远程服务按服务端能力选http、sse或streamable_http。远程服务器中的$TOKEN这类占位符形式表明请求头支持从环境变量取值,避免把明文 token 写进项目配置。十二、Plan Mode:只读规划与四阶段工作流Plan Mode 是 Grok CLI 处理高风险变更的核心机制:进入后所有写操作被拦截,只保留分析能力,直到用户明确批准计划。12.1 启用方式快速连续按下ShiftTab两次,终端显示类似: Plan Mode: Analysis Exploring codebase and gathering insights...无头模式下则直接在提示词中要求产出计划:$ grok -p analyze changes in this PR and create plan $ grok -p check if changes follow architecture guidelines12.2 允许与阻止的操作边界Plan Mode 下会被阻止的操作:所有文件写入/编辑操作破坏性 bash 命令任何修改状态的操作Plan Mode 下允许的操作:读取文件(ls、cat、grep)Web 搜索与抓取项目结构分析生成计划(仅写入计划输出)退出 Plan Mode:Enter:确认并执行计划Esc:不执行直接退出12.3 四个阶段阶段时长发生内容 Analysis1–5 秒项目类型、结构、依赖分析 Strategy5–15 秒AI 生成实施计划 Presentation1–2 秒整理计划供审阅✅ Approval用户控制审阅、确认或细化Analysis 阶段会分析:项目类型(Node/Python/React 等)、目录结构、关键组件、依赖、入口点、模块与架构模式。12.4 适用场景与使用建议Plan Mode 适用于:复杂的多文件功能开发、大规模重构、探索陌生代码库、变更前风险评估。建议:明确描述你的目标;批准前先审阅计划;出问题时可使用/heal触发自愈检查;通过.grok/GROK.md提供自定义上下文,让计划贴合项目约束。十三、故障排查13.1 找不到 API key# 检查环境变量是否已设置 $ echo $GROK_API_KEY # 或内联设置 $ GROK_API_KEYkey grok hello13.2 安装后命令找不到将 npm 全局 bin 目录加入 PATH:$ echo export PATH$(npm config get prefix)/bin:$PATH ~/.zshrc $ source ~/.zshrc $ which grok13.3 安装时报权限错误优先使用 Node 版本管理器(无 sudo),sudo/--force仅作为兜底:# 使用 sudo(不推荐)或 Node 版本管理器 $ npm install -g grok-cli-hurry-mode --force # 或使用 nvm/fnm(无 sudo) $ nvm use --lts $ npm install -g grok-cli-hurry-mode13.4 安装卡住 / 缓存问题$ pkill -f grok $ npm uninstall -g grok-cli-hurry-mode $ npm cache clean --force $ npm install -g grok-cli-hurry-modelatest排查顺序建议:先echo $GROK_API_KEY确认认证,再which grok确认 PATH,最后走缓存清理重装。13.5 关于 smart push 的上游工程实践速查清单中另有一条针对上游工具自身发布流程的建议:由于自动发布系统会创建版本号变更提交,该项目贡献者被要求使用 smart push(npm run smart-push/git pushup)而非裸git push origin main,以免触发 fetch first 冲突。这条内容反映的是 Grok CLI 项目自身的 CI 协作约定,其通用启示是:当远端存在自动化工具代提交的版本变更时,推送前要设计冲突容忍的推送方式。十四、在 reference 仓库中的位置与延伸阅读Grok CLI 速查在 reference 仓库中位于 AI 工具分类下,与 AI 工具总览、Claude Code、Codex CLI、Cursor CLI 等速查共同构成终端 AI 编码工具矩阵;仓库自身是纯文档站点,Markdown 清单通过refs-cli构建为静态页(见 package.json 中的build脚本与 netlify.toml 的发布配置),因此本文所有命令与参数均以 docs/grok-cli.md 的原始记载为准。如果需要官方通道的 Grok CLI 速查(安装脚本、XAI_API_KEY、TOML 配置、会话续跑与 ACP 集成),可对照仓库内的 docs/grok.md;选型时注意区分二者环境变量与配置格式的差异(第一节对照表)。要点回顾:一条npx命令即可零安装体验;认证有环境变量、内联、-k参数、配置文件四种途径;-m/-p/-d/--max-tool-rounds覆盖模型、无头、目录与工具轮次的核心控制;Plan Mode 以只读分析 显式批准约束高风险变更;MCP 服务器通过grok mcp子命令管理并持久化到.grok/settings.json;故障排查按认证 → PATH → 权限 → 缓存的顺序推进即可解决绝大多数问题。【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考