Grok
将编码委托给 xAI Grok Build CLI(功能开发、PR)。
Skill 元数据
| 来源 | 可选 — 通过 kopi skills install official/autonomous-ai-agents/grok 安装 |
| 路径 | optional-skills/autonomous-ai-agents/grok |
| 版本 | 0.1.0 |
| 作者 | Matt Maximo (MattMaximo), KOPI AI AGENT |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | Coding-Agent, Grok, xAI, Code-Review, Refactoring, Automation |
| 相关 skill | codex, claude-code, kopi-ai-agent |
参考:完整 SKILL.md
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
Grok Build CLI — Kopi Agent 编排指南
通过 Kopi Agent 终端把编码任务委托给 Grok Build(xAI 的
自主编码 agent CLI,即 grok 命令)。Grok 可以读取文件、编写代码、运行 shell 命令、
生成子 agent,并管理 git 工作流。它有三种运行方式:交互式 TUI、headless(-p),以及
通过 JSON-RPC 的 ACP agent。
这是 codex 和 claude-code 之后的第三个同类 skill。编排模式几乎相同 —— 一次性任务优先使用
headless -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检查登录状态,或运行一次便宜的 headless 冒烟测试:grok --no-auto-update -p "Say ok." - 在 TUI 中,
/logout登出,/login(或重新启动)重新登录。
- 运行一次
- 不需要 git 仓库 —— 与 Codex 不同,Grok 在 git 目录之外也能正常运行 (适合草稿/一次性任务)。
- 零配置兼容 Claude Code / AGENTS.md —— Grok 会自动读取
CLAUDE.md、.claude/(skills、agents、MCPs、hooks、rules)以及AGENTS.md系列文件。现有的项目上下文直接就能用。
API key 回退路径(本用户的默认不走这条路): Grok 也支持 设置
XAI_API_KEY环境变量,通过api.x.ai按量计费。 只有在grok login/ SuperGrok 认证不可用时才使用这种方式。 订阅路径(grok login)才是这里的预期设置。
两种编排模式
模式 1:Headless(-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 以跳过后台更新检查。
何时使用 headless:
- 一次性编码任务(修 bug、加功能、重构)
- CI/CD 自动化和脚本
- 用
--output-format json做结构化输出解析 - 任何不需要多轮对话的任务
模式 2:交互式 PTY — 多轮 TUI 会话
TUI 是一个全屏、支持鼠标交互的应用。用 pty=true 驱动它。为了稳健的监控/输入,
请使用 tmux(与 claude-code skill 相同的模式)。
# Launch in a tmux session for capture-pane monitoring
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")
# Wait for startup, then send a task
terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")
# Monitor progress
terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")
# Exit when done
terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")
想要 headless 式的内联输出的小技巧: 如果你想要 TUI 风格的输出但不要
全屏 alt-screen 接管(例如为了更干净的日志),加上 --no-alt-screen。
对于纯自动化,headless -p 仍然比 TUI 更干净。
Headless 深入
常用标志
| 标志 | 效果 |
|---|---|
-p, --single <PROMPT> | 发送一个 prompt,headless 运行,退出 |
-m, --model <MODEL> | 选择模型 |
-s, --session-id <ID> | 创建或恢复一个具名 headless 会话 |
-r, --resume <ID> | 恢复一个已有会话 |
-c, --continue | 继续当前目录中最近的会话 |
--cwd <PATH> | 设置工作目录 |
--output-format <FMT> | plain(默认)、json 或 streaming-json |
--always-approve | 自动批准所有工具执行(相当于 --full-auto / --yolo) |
--no-alt-screen | 内联运行,不做全屏 TUI 接管 |
--no-auto-update | 跳过后台更新检查(所有自动化中都用) |
输出格式
plain— 人类可读的文本(默认)json— 运行结束时输出一个 JSON 对象(干净地解析结果)streaming-json— 逐行输出的 JSON 事件流
# Structured result for parsing
terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)
# Auto-approve for autonomous building
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)
后台模式(长任务)
# Start headless in background
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
# Returns session_id
# Monitor
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
# Kill if needed
process(action="kill", session_id="<id>")
对于交互式(TUI)后台会话,使用 pty=true + tmux,并用
tmux capture-pane 监控,与 claude-code / codex skill 完全一样。
会话延续
# Start a named session
terminal(command="grok --no-auto-update -s refactor-db -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
# Resume it later
terminal(command="grok --no-auto-update -r refactor-db -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
# Or continue the most recent session in this directory
terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)
只读审计 → Markdown 笔记模式
要让 Grok 审查本地产物并返回一份干净的 markdown 笔记(用于 Obsidian 或仓库) 而不改动任何东西:
- 先用 Kopi Agent 工具(
read_file、write_file)准备好稳定的输入文件。 只把相关上下文快照到临时文件,而不是倾倒原始路径。 - 不带
--always-approve运行 Grok headless,这样它无法自动写入,并 要求markdown only, no preamble。 - 用
write_file()把 Grok 的 stdout 直接保存到目标笔记。
grok --no-auto-update -p "Read /tmp/current.md and /tmp/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 审查模式
快速审查(Headless)
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
# Create worktrees
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
# Launch Grok headless in each (background)
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/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="/tmp/issue-99", background=true, notify_on_complete=true)
# Monitor
process(action="list")
# After completion: push and open PRs
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
# Cleanup
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
常用子命令与 TUI 命令
| 命令 | 用途 |
|---|---|
grok | 启动交互式 TUI |
grok -p "query" | Headless 一次性运行 |
grok login / grok logout | 登录 / 登出(SuperGrok / X Premium+ OAuth) |
grok inspect | 显示 Grok 在当前目录发现的内容:配置来源、指令、skills、插件、hooks、MCP 服务器 |
grok agent stdio | 作为通过 JSON-RPC 的 ACP agent 运行(用于 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 # skip background update checks persistently
[ui]
permission_mode = "ask" # or "always-approve" to skip tool prompts by default
[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。 - 不要把 Kopi Agent 的 xAI 认证与
grokCLI 的认证混为一谈。 Kopi Agent 的x_search运行在它自己的 xAI OAuth 上;独立的grokCLI 在~/.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是自主构建的开关。 没有它,headless 运行可能卡在等待工具批准提示上。在只读的审查/审计工作中刻意省略它, 这样 Grok 就无法改动文件。- Headless
-p跳过 TUI 对话框;TUI 需要pty=true(+ tmux 用于 监控),和 Claude Code 一样。 - 使用
--no-alt-screen—— 如果你内联运行 TUI 且全屏 alt-screen 接管会弄乱捕获的输出。 - 不需要 git 仓库,但 PR/提交工作流还是需要一个 —— 用
mktemp -d && git init做草稿提交任务。 - 清理 tmux 会话 —— 完成后用
tmux kill-session -t <name>。
KOPI AI AGENT 的规则
- 单个任务优先使用 headless
-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."冒烟测试;不要想当然认为 Kopi Agent 的 xAI 认证 能直接沿用。 - 向用户报告结果 —— 总结 Grok 改了什么、还剩什么。