{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Grok

把编码委派给 xAI Grok Build CLI（特性、PR）。

Skill 元数据


来源	可选——用 `hermes skills install official/autonomous-ai-agents/grok` 安装
路径	`optional-skills/autonomous-ai-agents/grok`
版本	`0.1.1`
作者	Matt Maximo（MattMaximo）、Hermes Agent
许可证	MIT
平台	linux, macos, windows
标签	`Coding-Agent`, `Grok`, `xAI`, `Code-Review`, `Refactoring`, `Automation`
相关 skill	`codex`、`claude-code`、`hermes-agent`

参考：完整 SKILL.md

INFO

以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。

Grok Build CLI——Hermes 编排指南

经 Hermes terminal 把编码任务委派给 Grok Build（xAI 自主编码 agent CLI，grok 命令）。Grok 能读文件、写代码、跑 shell 命令、派生子代理、管理 git 工作流。它以三种方式运行：交互式 TUI、无头（-p）和经 JSON-RPC 的 ACP agent。

这是 codex 和 claude-code 的第三个兄弟。编排模式几乎相同——一次性优先无头 -p，交互式会话用 PTY。

何时使用

构建特性
重构
PR 评审
批量修 issue
任何你本会用 Codex / Claude Code 但想要 Grok 的任务

前置条件

安装（首选）： npm install -g @xai-official/grok
- 官方安装器 curl -fsSL https://x.ai/cli/install.sh | bash 也工作，但 x.ai 主机在某些环境被 Cloudflare 挡。npm 路径完全避开该依赖。
认证——SuperGrok / X Premium+ 订阅（主路径）：
- 跑一次 grok login → 开浏览器 OAuth → token 缓存于 ~/.grok/auth.json。这用你的 SuperGrok 或 X Premium+ 订阅（无逐 token API 计费）。
- 查登录状态：找 ~/.grok/auth.json，或跑便宜无头冒烟测试：grok --no-auto-update -p "Say ok."
- TUI 中 /logout 登出，/login（或重启）登回。
无需 git 仓库——不像 Codex，Grok 在 git 目录外也跑（适合临时/一次性任务）。
Claude Code / AGENTS.md 零配置兼容——Grok 自动读 CLAUDE.md、.claude/（skill、agent、MCP、钩子、规则）和 AGENTS.md 家族。既有项目上下文直接工作。

API key 回退（非本用户默认）： Grok 也支持设 XAI_API_KEY 环境变量，经 api.x.ai 按量计费。仅当 grok login / SuperGrok 认证不可用时用。订阅路径（grok login）是此处预定设置。

两种编排模式

模式 1：无头（`-p`）——非交互（首选）

跑一次性任务，打印结果，退出。无 PTY，无交互式对话框要导航。这是最干净的集成路径——类比 claude -p 和 codex exec。

terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)

自动化中总传 --no-auto-update 跳过后台更新检查。

何时用无头：

一次性编码任务（修 bug、加特性、重构）
CI/CD 自动化和脚本
用 --output-format json 解析结构化输出
任何不需多轮对话的任务

模式 2：交互式 PTY——多轮 TUI 会话

TUI 是全屏、鼠标交互应用。用 pty=true 驱动。稳健监控/输入用 tmux（同 claude-code skill 模式）。

# 在 tmux 会话启动做 capture-pane 监控
terminal(command="tmux new-session -d -s grok-work -x 140 -y 40")
terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter")

# 等启动，发任务
terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")

# 监控进度
terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")

# 完成退出
terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")

无头但行内输出提示： 若你要 TUI 风格输出而不要全屏 alt-screen 接管（如要更干净日志），加 --no-alt-screen。纯自动化，无头 -p 仍比 TUI 干净。

无头深入

常见标志

标志	作用
`-p, --single <PROMPT>`	发一个 prompt，无头跑，退出
`-m, --model <MODEL>`	选模型
`-s, --session-id <UUID>`	给新会话指派一个新有效 UUID（不得已存在）。不恢复——用 `--resume`/`--continue`。仅在配 `--fork-session` 时与 `--resume`/`--continue` 合用有效
`-r, --resume [<UUID>]`	按 UUID 恢复既有会话（省略则最近）
`-c, --continue`	继续当前目录最近会话
`--fork-session`	恢复时创建新会话 ID 而非复用原
`--max-turns <N>`	封顶 agent 最大轮次
`--cwd <PATH>`	设工作目录
`--output-format <FMT>`	`plain`（默认）、`json` 或 `streaming-json`
`--always-approve`	自动批准所有工具执行（`--full-auto` / `--yolo` 等价）
`--no-alt-screen`	行内跑，无全屏 TUI 接管
`--no-auto-update`	跳过后台更新检查（所有自动化用；`--help` 隐藏但仍工作）

输出格式

plain——人类可读文本（默认）
json——运行结束一个 JSON 对象（干净解析结果）
streaming-json——到达时换行分隔 JSON 事件

# 供解析的结构化结果
terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)

# 自主构建自动批准
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)

后台模式（长任务）

# 后台启无头
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
# 返回 session_id

# 监控
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# 需要时杀
process(action="kill", session_id="<id>")

交互式（TUI）后台会话，用 pty=true + tmux，用 tmux capture-pane 监控，正同 claude-code / codex skill。

会话续接

会话按 UUID 而非名键控。--session-id 给新运行指派新 UUID（它不恢复）；--resume 取既有会话 UUID（或省略值恢复最近）。

# 用自指派 UUID 启会话（须有效未用 UUID）
SID=$(uuidgen)
terminal(command="grok --no-auto-update -s $SID -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)

# 之后按 UUID 恢复那个确切会话
terminal(command="grok --no-auto-update -r $SID -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)

# 或就继续此目录最近会话（无需 UUID）
terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)

只读审计 → Markdown 笔记模式

要 Grok 评审本地工件并返回干净 markdown 笔记（给 Obsidian 或仓库）而不改任何东西：

先用 Hermes 工具（read_file、write_file）准备稳定输入文件。仅把相关上下文快照进临时文件，而非 dump 裸路径。
跑 Grok 无头不带 --always-approve，使它不能自动写，并要求 markdown only, no preamble。
用 write_file() 把 Grok stdout 直接存进目标笔记。

grok --no-auto-update -p "Read ~/.hermes/cache/scratch/current.md and ~/.hermes/cache/scratch/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain

陷阱（同 Claude Code）： 文档重写，松散"rewrite this"prompt 可能返回变更摘要而非整文件。改法：把文件管道进，要求 Return ONLY the full revised markdown document. No intro, no explanation, no code fences. Start immediately with '# Title'. 覆盖目标前用 read_file() 验证首行。

PR 评审模式

快速评审（无头）

terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120)

克隆到临时目录评审（安全，不改仓库）

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300)

发评审

terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo")

用 worktree 并行修 issue

# 建 worktree
terminal(command="git worktree add -b fix/issue-78 ~/.hermes/cache/scratch/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 ~/.hermes/cache/scratch/issue-99 main", workdir="~/project")

# 每个里启 Grok 无头（后台）
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-78", background=true, notify_on_complete=true)
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-99", background=true, notify_on_complete=true)

# 监控
process(action="list")

# 完成后：push 并开 PR
terminal(command="cd ~/.hermes/cache/scratch/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")

# 清理
terminal(command="git worktree remove ~/.hermes/cache/scratch/issue-78", workdir="~/project")

有用子命令与 TUI 命令

命令	用途
`grok`	启交互式 TUI
`grok -p "query"`	无头一次性
`grok login` / `grok logout`	登出/登出（SuperGrok / X Premium+ OAuth）
`grok inspect`	显示 Grok 在 cwd 发现什么：配置来源、指令、skill、插件、钩子、MCP 服务器
`grok agent stdio`	作为 ACP agent 经 JSON-RPC 跑（供 IDE/工具集成）
`grok update`	更新 CLI（需 `x.ai` 主机；自动化中跳过）

TUI 斜杠命令（仅交互）：/model <name>、/always-approve、 /plan、/context、/compact、/resume、/sessions、/fork、/usage、 /quit。Shift+Tab 循环会话模式（含 Plan 模式，它阻塞写工具除会话计划文件外）。

配置（`~/.grok/config.toml`）

[cli]
auto_update = false          # 持久跳过后台更新检查

[ui]
permission_mode = "ask"      # 或 "always-approve" 默认跳过工具提示

[models]
default = "grok-build-0.1"

全局偏好放 ~/.grok/config.toml（非项目作用域 .grok/config.toml）。permission_mode 取代旧 approval_mode / yolo = true 键。

常见陷阱

认证订阅门控。 grok login 需 SuperGrok 或 X Premium+ 订阅。若登录失败或无 ~/.grok/auth.json，先确认订阅活跃再回退 XAI_API_KEY。
别把 Hermes 的 xAI 认证与 grok CLI 的认证混。 Hermes x_search 跑自己的 xAI OAuth；独立 grok CLI 在 ~/.grok/auth.json 有单独 token。x_search 工作不意味着 grok 已登录。
自动化中总传 --no-auto-update——否则 Grok 回拨做更新检查（且 x.ai/storage.googleapis.com 可能不可达）。
优先 npm 安装而非 curl 安装器——npm install -g @xai-official/grok 避开 Cloudflare 挡的 x.ai 主机。
--always-approve 是自主构建开关。 无它，无头运行可能等工具批准提示卡住。只读评审/审计工作故意省略它，使 Grok 不能改文件。
无头 -p 跳过 TUI 对话框；TUI 需 pty=true（+tmux 监控），正同 Claude Code。
用 --no-alt-screen，若你行内跑 TUI 且全屏 alt-screen 接管弄乱捕获输出。
无需 git 仓库，但 PR/commit 工作流仍要——临时 commit 任务用 mktemp -d && git init。
完成清理 tmux 会话，用 tmux kill-session -t <name>。

Hermes agent 规则

单任务优先无头 -p——最干净集成，经 --output-format json 结构化输出。
总设 workdir（或 --cwd）使 Grok 瞄准正确项目。
每次自动调用传 --no-auto-update。
仅当 Grok 应自主写时用 --always-approve；只读评审和审计省略。
长任务后台用 background=true, notify_on_complete=true，经 process 工具监控。
多轮交互用 tmux，用 tmux capture-pane -t <session> -p -S -50 监控。
依赖前验证认证——查 ~/.grok/auth.json 或跑便宜 grok -p "Say ok." 冒烟测试；别假设 Hermes 的 xAI 认证带过来。
向用户报告结果——摘要 Grok 改了什么、还剩什么。

Grok

Skill 元数据

参考：完整 SKILL.md

Grok Build CLI——Hermes 编排指南

何时使用

前置条件

两种编排模式

模式 1：无头（-p）——非交互（首选）

模式 2：交互式 PTY——多轮 TUI 会话

无头深入

常见标志

输出格式

后台模式（长任务）

会话续接

只读审计 → Markdown 笔记模式

PR 评审模式

快速评审（无头）

克隆到临时目录评审（安全，不改仓库）

发评审

用 worktree 并行修 issue

有用子命令与 TUI 命令

配置（~/.grok/config.toml）

常见陷阱

Hermes agent 规则

模式 1：无头（`-p`）——非交互（首选）

配置（`~/.grok/config.toml`）