跳到主要内容

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
相关 skillcodex, 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 或仓库) 而不改动任何东西:

  1. 先用 Kopi Agent 工具(read_file、write_file)准备好稳定的输入文件。 只把相关上下文快照到临时文件,而不是倾倒原始路径。
  2. 不带 --always-approve 运行 Grok headless,这样它无法自动写入,并 要求 markdown only, no preamble。
  3. 用 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 键。

常见陷阱与注意事项​

  1. 认证受订阅限制。 grok login 需要 SuperGrok 或 X Premium+ 订阅。如果登录失败或没有 ~/.grok/auth.json, 先确认订阅有效,再回退到 XAI_API_KEY。
  2. 不要把 Kopi Agent 的 xAI 认证与 grok CLI 的认证混为一谈。 Kopi Agent 的 x_search 运行在它自己的 xAI OAuth 上;独立的 grok CLI 在 ~/.grok/auth.json 里有单独的 token。x_search 能用并不意味着 grok 已登录。
  3. 在自动化中始终传入 --no-auto-update —— 否则 Grok 会联网 检查更新(而且 x.ai/storage.googleapis.com 可能不可达)。
  4. 优先用 npm 安装而不是 curl 安装器 —— npm install -g @xai-official/grok 避开了被 Cloudflare 墙挡住的 x.ai 主机。
  5. --always-approve 是自主构建的开关。 没有它,headless 运行可能卡在等待工具批准提示上。在只读的审查/审计工作中刻意省略它, 这样 Grok 就无法改动文件。
  6. Headless -p 跳过 TUI 对话框;TUI 需要 pty=true(+ tmux 用于 监控),和 Claude Code 一样。
  7. 使用 --no-alt-screen —— 如果你内联运行 TUI 且全屏 alt-screen 接管会弄乱捕获的输出。
  8. 不需要 git 仓库,但 PR/提交工作流还是需要一个 —— 用 mktemp -d && git init 做草稿提交任务。
  9. 清理 tmux 会话 —— 完成后用 tmux kill-session -t <name>。

KOPI AI AGENT 的规则​

  1. 单个任务优先使用 headless -p —— 最干净的集成,通过 --output-format json 获得结构化输出。
  2. 始终设置 workdir(或 --cwd),让 Grok 针对正确的项目。
  3. 每次自动调用都传入 --no-auto-update。
  4. 只在 Grok 需要自主写入时使用 --always-approve;只读的审查 和审计要省略它。
  5. 用后台模式运行长任务,background=true, notify_on_complete=true, 并通过 process 工具监控。
  6. 多轮交互式工作用 tmux,用 tmux capture-pane -t <session> -p -S -50 监控。
  7. 依赖认证之前先验证 —— 检查 ~/.grok/auth.json 或运行一次 便宜的 grok -p "Say ok." 冒烟测试;不要想当然认为 Kopi Agent 的 xAI 认证 能直接沿用。
  8. 向用户报告结果 —— 总结 Grok 改了什么、还剩什么。