第 1 课
安装与 TUI：login、首轮对话与 Plan 模式
按官方 Overview / CLI：安装 grok，完成 login 或 API Key；在项目目录开 TUI，用 /plan 走完审批。
学习位置仅保存在当前浏览器，有效期 180 天。
图文讲义
来源：xAI · Grok Build Overview、CLI Reference、Plan Mode、Permissions、Modes and Commands。 安装入口以 x.ai/cli 与官方 Overview 为准；可执行名是
grok。
你将得到什么
- 本机可用的
grokCLI（macOS / Linux 用 bash 安装脚本；Windows 用官方 PowerShell） - 一次成功的登录：浏览器 Approve，或无浏览器环境用
XAI_API_KEY/grok login --device-auth - 在真实项目目录里打开交互 TUI，用
/plan（或Shift+Tab）走完「先写计划、审批后再改代码」
开始前准备
- 终端可访问外网（拉安装脚本与 xAI 服务）。
- 一台 macOS、Linux，或 Windows（PowerShell）。
- 一个可练习的代码目录（任意本地 git 仓库即可；不要用含生产密钥的目录）。
- 账号与配额：官方当前面向 SuperGrok / X Premium Plus 等订阅用户；无浏览器时准备好
XAI_API_KEY（以控制台签发为准，形如xai-...）。 - 建议先打开并通读：https://docs.x.ai/build/overview
核心事实（先记住）
| 项 | 官方值 |
|---|---|
| 安装（macOS / Linux） | curl -fsSL https://x.ai/cli/install.sh | bash |
| 安装（Windows） | irm https://x.ai/cli/install.ps1 | iex |
| 交互入口 | 项目目录执行 grok（无参数 = TUI） |
| 无浏览器鉴权 | export XAI_API_KEY="xai-..." 或 grok login --device-auth |
| Plan 模式 | /plan 或 Shift+Tab 切到 Plan；审批前只改 session plan 文件 |
| 权限模式 | Ask（默认）/ Auto / Always-approve；Shift+Tab 循环 |
| 配置主文件 | ~/.grok/config.toml（可用 $GROK_HOME） |
步骤 1：安装 CLI
macOS / Linux（官方 Overview）：
curl -fsSL https://x.ai/cli/install.sh | bash
对照结果：脚本结束后，新开一个终端（或 source 你的 shell rc），应能找到 grok：
which grok
grok version
对照结果：打印版本信息（具体版本号随官方发布变化；能打印即可）。若 which 为空，检查安装脚本提示的 PATH（常见是 ~/.local/bin）。
Windows（官方 Overview）：
irm https://x.ai/cli/install.ps1 | iex
对照结果：PowerShell 结束后，新开窗口执行 grok version 应有输出。
可选核对：
grok --help
grok update --check
对照结果：--help 列出子命令（login、inspect、models、mcp、agent 等）；--check 只检查更新不强制安装。
安全提示：管道执行远程脚本前，可先用浏览器打开 https://x.ai/cli/install.sh 阅读内容，再决定是否执行。
步骤 2：登录
路径 A — 本机有浏览器（推荐人机跟做）
grok login
对照结果：打开浏览器完成 xAI / X 账号授权；结束后本地缓存凭证。也可在首次直接运行 grok 时，由欢迎屏引导登录。
路径 B — 无浏览器 / 远程 SSH（官方 CLI）
设备码：
grok login --device-auth
对照结果：终端打印验证 URL 与短码；你在另一台有浏览器的机器打开并确认后，本机登录完成。
或 API Key（官方 Overview「non-browser environments」）：
export XAI_API_KEY="xai-..."
grok
对照结果：不再弹浏览器也能进入会话。CI / 脚本里建议把 Key 放进环境变量或密钥管理，不要写进仓库。
核对可用模型列表：
grok models
对照结果：列出当前账号可见模型（文档示例含 API 侧 grok-4.7；Build 默认 coding 模型在 Settings 示例里写作 grok-build）。若报未登录，回到路径 A/B。
步骤 3：在项目目录启动交互 TUI
cd /path/to/your-project
grok
对照结果：进入全屏（或近全屏）TUI；底部有状态行。官方建议的首轮提示：
Explain this repo.
或带文件引用（官方示例）：
@src/main.rs Walk me through this file.
把路径换成你仓库里真实存在的文件。对照结果：Agent 开始读仓库并回复结构说明；在 Ask 模式下，读文件通常会弹出工具审批，按提示允许只读操作即可。
常用 TUI 命令（官方 Modes and Commands，本课先用这几条）：
| 命令 | 作用 |
|---|---|
/help | 命令与快捷键 |
/model <name> | 切换模型 |
/context | 查看上下文占用 |
/plan [描述] | 进入 Plan 模式 |
/view-plan | 重新打开计划预览 |
/settings | 设置面板 |
/quit | 退出 |
步骤 4：用 Plan 模式「先审再改」
官方：Plan 模式下 Agent 先探索并起草计划，你审批后才会改业务代码；审批前只允许编辑 session plan 文件。
在 TUI 输入：
/plan 给 README 增加一节「本地开发」：写清安装依赖、启动命令，不要改其它文件
或先 /plan，再发任务描述。也可用 Shift+Tab 从 Normal 切到 Plan。
对照结果：状态显示 plan；Agent 读仓库后打开 plan preview。官方审批快捷键：
| 键 | 动作 |
|---|---|
a | 批准并开始执行（可带未提交评论） |
s | 要求修改（输入意见后 Enter） |
c | 对选中行/范围写评论 |
q | 退出计划并关闭 Plan 模式 |
Tab | 在计划预览与输入框间切换 |
先按 s 试一次「要求改计划」，再按 a 批准。对照结果：状态从 plan approval 回到普通会话并开始按计划改文件；你应在 diff / 审批里看到拟改路径主要落在 README。
注意（官方 Caveats）：Plan 只门禁「编辑类工具」，不门禁 shell。bash 仍可能通过重定向写文件；生产仓库请保持 Ask 模式，并审看每条危险命令。
步骤 5：分清权限模式
官方 Permissions 三种模式：
| 模式 | 行为 | 进入方式 |
|---|---|---|
| Ask（默认） | 未预先允许的工具都要问你 | — |
| Auto | 分类器自动放行偏安全工具；危险的仍可能询问 | /auto 或 Shift+Tab（功能开启时） |
| Always-approve | 工具调用自动批准（deny 规则与 PreToolUse hooks 仍生效） | /always-approve、Ctrl+O、Shift+Tab，或 grok --always-approve |
Shift+Tab 循环顺序（官方）：Normal → Plan → Auto（可用时）→ Always-approve。
本课建议：学习阶段保持 Ask；只有你完全理解任务时再短时打开 Always-approve。可在用户配置里设默认（官方 Settings，仅用户级 ~/.grok/config.toml）：
[ui]
permission_mode = "ask"
改完后下一会话生效；用下一课的 grok inspect 核对。
本课检查清单
-
grok version有输出 -
grok login或XAI_API_KEY可用，grok models能列出模型 - 在项目目录
grok进入 TUI，并用一句提示让 Agent 解释仓库 - 用
/plan走完一次预览 → 审批（或要求修改后再批准） - 知道 Ask / Auto / Always-approve 的区别，默认留在 Ask
下一课：无头 grok -p、输出格式、会话续跑、config.toml、MCP 与 grok inspect。
