无头与配置：-p、config.toml、MCP、inspect

你将得到什么

• 用 grok -p 在脚本/CI 友好模式下跑通一轮无头任务
• 会选 --output-format（plain / json / streaming-json），并用会话标志续跑
• 写好一份最小可用的 ~/.grok/config.toml，用 grok mcp 加一个 MCP，并用 grok inspect 核对发现项

步骤 1：无头跑一轮

进入你的练习仓库（与第 1 课相同即可）：

cd /path/to/your-project
grok -p "用三句话概括这个仓库做什么，并列出顶层目录里最重要的 3 个文件"

对照结果：终端直接打印回答（plain 默认），不进入全屏 TUI。若提示未鉴权，先：

export XAI_API_KEY="xai-..."
# 或
grok login --device-auth

常用标志（官方 Headless 表）：

CI / 脚本推荐写法（官方）：

grok --no-auto-update -p "List TODO comments" --output-format json

对照结果：结束时输出一个 JSON 对象（--output-format json）；若用 streaming-json，则是按行增量事件。也可持久关闭自动更新（官方）：在 ~/.grok/config.toml 写：

[cli]
auto_update = false

步骤 2：会话续跑与工作目录

先开一个命名无头会话：

grok -p "记住：我们接下来只讨论测试策略，不要改代码。" -s demo-test-strategy --no-auto-update

对照结果：完成一轮回答。无头会话落在 ~/.grok/sessions（官方）。再续跑：

grok -p "根据刚才的约定，列出本仓库最值得补的 3 类测试。" -s demo-test-strategy --no-auto-update

或：

grok -p "继续上一问，给出最小可执行的测试命令示例。" -c --no-auto-update

对照结果：回答应承接「只讨论测试、不改代码」的上下文（具体措辞因模型而异，但不应突然开始大范围改文件——若你未加 --always-approve，写文件仍会受权限模式约束）。

指定目录而不 cd：

grok -p "Explain the architecture" --cwd /path/to/your-project --output-format plain --no-auto-update

列出会话（官方 CLI）：

grok sessions list

对照结果：能看到 demo-test-strategy 或近期会话 ID。需要导出时：

grok export <session-id>

对照结果：得到 Markdown 转写（路径以命令输出为准）。

步骤 3：最小 `config.toml`

官方 Settings：用户配置在 ~/.grok/config.toml（Windows：%USERPROFILE%\.grok\config.toml）；也可用 $GROK_HOME。项目级 .grok/config.toml 只适合放 MCP、plugins、permission rules，不是完整用户配置。

创建目录并写入一份与官方示例对齐的最小配置（按需改 Key 名；不要把真实 Key 写进文件进 git）：

mkdir -p ~/.grok
nano ~/.grok/config.toml

示例（整理自官方 Settings；模型默认名以文档为准）：

[models]
default = "grok-build"
web_search = "grok-4.7"

[model."grok-4.7"]
model = "grok-4.7"
base_url = "https://api.x.ai/v1"
name = "Grok 4.7"
description = "Grok 4.7 from xAI"
env_key = "XAI_API_KEY"
api_backend = "responses"

[ui]
permission_mode = "ask"
theme = "auto"
show_thinking_blocks = true

[cli]
auto_update = false

保存后核对发现项：

cd /path/to/your-project
grok inspect

对照结果：打印当前目录加载到的配置来源、instructions、skills、plugins、hooks、MCP 等。需要机器可读时：

grok inspect --json

无头指定模型（官方 Overview）：

grok -p "Hello" -m grok-4.7 --no-auto-update

对照结果：使用你在 -m 或 config.toml 里声明的模型；TUI 内也可用 /model <name> 切换。

自定义任意 OpenAI 兼容端点时，官方形状如下（Overview「Custom models」）——仅在你确实有第三方端点时使用：

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

步骤 4：加一个 MCP 并体检

官方最快路径是 grok mcp（示例用 filesystem；把目录换成你允许暴露的路径）：

grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory
grok mcp list
grok mcp doctor filesystem

对照结果：

• list：看到名为 filesystem 的服务器
• doctor：配置/连通性诊断通过，或给出可操作的错误（首次 npx 拉包可能较慢；官方建议必要时提高 startup_timeout_sec）

远程 HTTP MCP 示例（官方）：

grok mcp add --transport http linear https://mcp.linear.app/mcp

带静态头：

grok mcp add --transport http api https://mcp.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

等价 TOML（官方，可写进 ~/.grok/config.toml）：

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 6000

项目共享 MCP 时加 --scope project（写入当前目录 .grok/config.toml）。TUI 里也可用 /mcps 开关服务器。

兼容性（官方）：Grok 还会合并读取 ~/.claude.json、.cursor/mcp.json、项目 .mcp.json；优先级低于 config.toml。可用 grok inspect 看每个 server 的来源。

删除练习用 server：

grok mcp remove filesystem

步骤 5：Skills 与 Claude / AGENTS.md 兼容（了解即可）

官方 Skills：可复用的说明 + 脚本目录，发现路径包括：

• ./.grok/skills/（向上走到仓库根）
• ~/.grok/skills/
• 已启用 plugin 的 skills/
• config.toml 里 [skills] paths

用户可调用的 skill 会出现成 slash 命令，如 /<skill-name>。

兼容（官方，零配置）：

• 自动读取 Claude Code 的 marketplaces / plugins / skills / MCP / agents / hooks，以及 CLAUDE.md 等
• 读取 AGENTS.md / Agents.md / AGENT.md（从 cwd 走到仓库根）
• 用户级 ~/.agents/skills/、~/.agents/commands/

本课不强制新建 skill；知道 grok inspect 能列出它们即可。扩展面板入口：/skills、/plugins、/hooks、/marketplace、/mcps（同一 modal 不同 tab）。

步骤 6：ACP（可选加分）

若要把 Grok 接到支持 Agent Client Protocol 的 IDE/工具，而不是终端会话：

grok agent stdio

对照结果：进程在 stdin/stdout 上讲 JSON-RPC。官方 Headless 页提供完整 Node 示例（initialize → authenticate → session/new → session/prompt）。跟做时需本机已登录或设置 XAI_API_KEY；鉴权失败时按文档先 grok login。

本课检查清单

• grok -p "..." 无头成功返回
• 试过 --output-format json 或 streaming-json
• 用 -s / -c 续跑过同一会话
• 写了 ~/.grok/config.toml，且 grok inspect 能看到配置来源
• grok mcp add + list + doctor 至少跑通一次（或明确记录失败原因）

常见问题

无头任务想改文件但不想每次点批准？
官方提供 --always-approve（别名 --yolo）。仅在可丢弃的练习目录使用；生产仓库请配合 [permission] rules 的 deny（见 Permissions 文档）。

脚本里被更新检查打断？
加 --no-auto-update，或 [cli] auto_update = false。

MCP 冷启动超时？
看 ~/.grok/logs/mcp/<server>.stderr.log，并提高 startup_timeout_sec（官方 Troubleshooting）。

和「直接调 grok-4.7 HTTP API」有何不同？
Overview 里的 curl https://api.x.ai/v1/responses / SDK 示例是模型 API；本课的 grok 是终端编程 Agent（工具、计划、MCP、会话）。两者可共用 XAI_API_KEY，但产品面不同。

课后延伸（官方文档）

• Plan / 权限深挖：https://docs.x.ai/build/features/plan-mode 、 https://docs.x.ai/build/features/permissions
• Subagents / Worktrees：见 docs.x.ai/build/features/ 目录
• Enterprise 托管配置：https://docs.x.ai/build/enterprise