信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。
1. 定位
【有据可查】xAI 的终端编程 Agent，可交互 TUI、headless（脚本/CI）、ACP（接入 IDE/应用）；支持 AGENTS.md、插件、Hooks、MCP、子代理、worktree、Marketplace、技能（/skillify 把会话沉淀为技能）。来源：x.ai/build、Docs Overview、GitHub
注：xAI 官网/文档页面标题中出现 "SpaceXSI / SpaceXAI" 等品牌字样，页面上的模型版本号也不完全一致（如 Grok 4.6 / 4.7），说明处于频繁更新期。【有据可查（页面现象）】
2. 订阅方案结构
| 方式 | 说明 | 层级 |
|---|---|---|
| SuperGrok / X Premium Plus 订阅 | 官方发布文称 Grok Build 面向这两类订阅用户 | 有据可查：Introducing Grok Build |
| xAI API Key | XAI_API_KEY 或配置文件，按量计费，适合 CI |
有据可查：Enterprise |
| 企业认证 | 浏览器 OIDC、设备码、外部认证命令 | 有据可查 |
/usage 可查看额度用量或管理账单。【有据可查】具体套餐价格请看 xAI 官网。
3. 安装【有据可查】
curl -fsSL https://x.ai/cli/install.sh | bash
# 或
npm install -g @xai-official/grok
grok # 首次启动打开浏览器认证
grok login --device-auth # SSH/容器等无浏览器环境
企业网络需放行的主机：api.x.ai（API Key 直连）、code.grok.com（会话同步/分享）、x.ai 与 storage.googleapis.com（仅 curl 安装与更新需要；用 npm 安装则不需要）。来源：Enterprise Deployments
4. 首次配置
grok inspect：查看当前目录发现了哪些配置源、指令、技能、插件、Hooks、MCP。【有据可查】- 写
AGENTS.md；如从 Claude Code 迁移，可用/import-claude。【有据可查】 - 用户配置
~/.grok/config.toml；项目配置.grok/config.toml（MCP、插件、权限规则）。 /privacy查看/切换隐私与数据保留状态。【有据可查】
5. 权限与安全模型【有据可查】
权限决定"调用能不能执行"；沙箱限制"批准后的调用能做到什么程度"。
5.1 权限模式
| 模式 | 行为 | 进入方式 |
|---|---|---|
| Ask（默认） | 未授权的都询问 | — |
| Auto | 分类器自动批准安全工具，危险的仍可能询问 | /auto、Shift+Tab（功能开启时） |
| Always-approve | 自动批准所有调用（deny 规则与 PreToolUse hooks 仍生效） | /always-approve、Ctrl+O、grok --always-approve |
- 默认模式只能在用户级配置设置（不能由项目
.grok/config.toml设定）：[ui] permission_mode = "ask"。 - 规则示例：
[permission]
rules = [
{ action = "allow", tool = "bash", pattern = "git *" },
{ action = "allow", tool = "read" },
{ action = "deny", tool = "bash", pattern = "rm -rf *" },
]
deny永远优先；"记住的 always allow"对rm、git push等危险模式仍会再问。
5.2 沙箱：⚠️ 默认关闭
| Profile | 读 | 写 | 子进程网络 | 场景 |
|---|---|---|---|---|
off |
不限 | 不限 | 允许 | 默认 |
workspace |
全部 | 当前目录、~/.grok/、临时目录 |
允许 | 日常开发 |
devbox |
全部 | 除 /data 外顶层目录 |
允许 | 云端 devbox |
read-only |
全部 | 仅 ~/.grok/ 与临时目录 |
阻断 | 代码审查 |
strict |
当前目录 + 系统路径 | 当前目录、~/.grok/、临时 |
阻断 | 不可信仓库 |
已知限制（官方原文要点）：
- 子进程网络阻断只在 Linux 生效，macOS 上
read-only/strict的网络限制是 no-op； - 内置 profile 不会永久保护
~/.ssh等凭据路径，需自定义deny； - 模型 API 与网页工具属于进程内网络，不受子进程网络设置限制。
# ~/.grok/config.toml —— 建议新手起步
[sandbox]
profile = "workspace"
[ui]
permission_mode = "ask"
# ~/.grok/sandbox.toml —— 自定义保护凭据
[profiles.safe]
extends = "workspace"
restrict_network = true
deny = ["**/.env", "**/*.pem", "~/.ssh"]
6. 常用命令与工作流【有据可查】
| 命令 | 作用 |
|---|---|
/plan [描述]、/view-plan |
计划模式（只能改计划文件，批准后执行） |
/model、/effort |
切换模型、推理强度 |
/resume、/sessions、/fork、/rewind |
会话管理、分叉、回退 |
/compact、/context |
压缩上下文、查看用量 |
/goal <目标> |
多轮自主推进，完成时由多名审查子代理投票核验；--budget 限制 token |
/create-workflow、/workflow |
编排后台子代理工作流（保存为 .grok/workflows/*.rhai） |
/deep-research |
后台研究工作流 |
/loop [间隔] <提示> |
定时循环执行 |
/btw <问题> |
不打断当前任务的旁路提问 |
/skills、/mcps、/plugins、/hooks、/marketplace |
扩展管理 |
grok -p "任务" --output-format json |
headless |
grok agent stdio |
ACP 模式 |
写好 /goal 的诀窍（官方示例改写）：说清"完成长什么样"。
弱：/goal 把 auth 模块迁移到新 API
强：/goal 把 auth 模块迁移到新 API，以 auth 测试套件全部通过为准，不改变对外接口。
7. 接入自定义模型【有据可查】
官方称"支持任何自定义模型"，在 ~/.grok/config.toml（Windows：%USERPROFILE%\.grok\config.toml）中添加后，用 grok inspect 确认，再在 TUI 或 headless 中选择。也可作为 OpenAI 兼容 chat completion 后端被调用。具体字段请看 Settings Reference。
8. 常见报错
| 现象 | 原因 | 处理 | 层级 |
|---|---|---|---|
项目里设 permission_mode 无效 |
只能用户级设置 | 写到 ~/.grok/config.toml |
有据可查 |
| macOS 上 strict 仍能联网 | 子进程网络限制仅 Linux 生效 | 理解限制，另加网络控制 | 有据可查 |
| SSH 环境登录失败 | 无浏览器 | grok login --device-auth |
有据可查 |
| 防火墙下安装失败 | x.ai 不可达 |
改用 npm 安装 | 有据可查 |
/auto 不出现 |
该功能未开启 | 正常现象 | 有据可查 |
9. 适合人群
- ✅ 终端党、喜欢工作流编排与子代理并行
- ✅ 已有 SuperGrok / X Premium Plus 订阅
- ⚠️ 新手：沙箱默认关闭，务必手动开启
workspace或更严格的 profile
10. 本篇无法核实/需谨慎的点
- 订阅档位与 Grok Build 额度的对应关系、价格。
- 自定义模型配置的完整字段（以 Settings Reference 为准）。
- 页面品牌名（SpaceXSI/SpaceXAI）变化的背景。
小白练习：把本文流程逐项走通
练习目标：验证 CLI 可用，并在受控目录完成一次任务。
上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。
-
按官方支持的方式安装，重新打开终端，再查看 grok --help；实际安装的版本决定可用命令。
-
用 cd 进入练习目录，运行 grok，并完成所选认证方式。确认正在消耗订阅还是 API 用量。
-
运行原文的 inspect 检查配置来源，先启用适合练习目录的沙箱，再确认权限模式。
-
第一次任务只要求阅读并说明文件。第二次只修改一个文件，保留执行前的副本。
-
目标任务写清通过标准，再设置预算。查看工具调用结果，而不是只看最后一句完成声明。
-
完成后检查 diff 与真实运行效果；遇到权限差异先读当前版本的权限与沙箱文档。