跳到主要內容

Grok

將編碼任務委託給 xAI Grok Build CLI（功能開發、PR）。

技能元數據​

來源可選 — 使用 hermes skills install official/autonomous-ai-agents/grok 安裝
路徑optional-skills/autonomous-ai-agents/grok
版本0.1.0
作者Matt Maximo (MattMaximo), Hermes Agent
許可證MIT
平臺linux, macos, windows
標籤Coding-Agent, Grok, xAI, Code-Review, Refactoring, Automation
相關技能codex, claude-code, hermes-agent

參考：完整 SKILL.md​

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。

Grok Build CLI — Hermes 編排指南

通過 Hermes 終端將編碼任務委託給 Grok Build（xAI 的自主編碼代理 CLI，即 grok 命令）。Grok 可以讀取文件、編寫代碼、運行 shell 命令、生成子代理以及管理 git 工作流。它有三種運行方式：交互式 TUI、無頭模式（-p）以及作為基於 JSON-RPC 的 ACP 代理。

這是繼 codex 和 claude-code 之後的第三個同類技能。編排模式幾乎相同——對於一次性任務，首選無頭模式 -p，對於交互式會話則使用 PTY。

何時使用​

  • 構建功能
  • 重構
  • PR 審查
  • 批量問題修復
  • 任何你原本會使用 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 → 令牌緩存在 ~/.grok/auth.json 中。這使用你的 SuperGrok 或 X Premium+ 訂閱（無需按令牌 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/（技能、代理、MCPs、鉤子、規則）以及 AGENTS.md 系列文件。現有的項目上下文可直接使用。

API 密鑰回退方案（非此用戶的默認設置）： 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 以跳過後臺更新檢查。

何時使用無頭模式：

  • 一次性編碼任務（修復錯誤、添加功能、重構）
  • CI/CD 自動化和腳本編寫
  • 使用 --output-format json 進行結構化輸出解析
  • 任何不需要多輪對話的任務

模式 2：交互式 PTY — 多輪 TUI 會話​

TUI 是一個全屏、支持鼠標交互的應用程序。使用 pty=true 驅動它。為了進行穩健的監控/輸入，請使用 tmux（與 claude-code 技能相同的模式）。

# 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")

無頭但內聯輸出的提示： 如果你希望獲得類似 TUI 的輸出而不佔用全屏備用屏幕（例如，為了更清晰的日誌），請添加 --no-alt-screen。對於純自動化，無頭模式 -p 仍然比 TUI 更乾淨。

無頭模式深入解析​

常用標誌​

標誌效果
-p, --single <PROMPT>發送一個提示，以無頭模式運行，然後退出
-m, --model <MODEL>選擇模型
-s, --session-id <ID>創建或恢復命名的無頭會話
-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 skills 完全相同。

會話續接​

# 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. 首先使用 Hermes 工具（read_file、write_file）準備穩定的輸入文件。僅將相關上下文快照保存到臨時文件中，而不是轉儲原始路徑。
  2. 在不使用 --always-approve 的情況下無頭運行 Grok，使其無法自動寫入，並要求輸出格式為 markdown only, no preamble（僅 markdown，無前導說明）。
  3. 使用 write_file() 將 Grok 的標準輸出直接保存到目標筆記中。
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”（重寫這個）提示可能會返回更改摘要，而不是完整文件。相反：通過管道傳入文件，並要求 Return ONLY the full revised markdown document. No intro, no explanation, no code fences. Start immediately with '# Title'.（僅返回完整的修訂版 markdown 文檔。無引言，無解釋，無代碼圍欄。立即以 '# 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")

使用 Worktrees 並行修復問題​

# 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"無頭一次性執行
grok login / grok logout登錄 / 登出（SuperGrok / X Premium+ OAuth）
grok inspect顯示 Grok 在當前工作目錄中發現的內容：配置源、指令、skills、插件、鉤子、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          # 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. 不要混淆 Hermes 的 xAI 認證與 grok CLI 的認證。 Hermes 的 x_search 運行在其自身的 xAI OAuth 上；獨立的 grok CLI 在 ~/.grok/auth.json 中有單獨的令牌。x_search 正常工作並不意味著 grok 已登錄。
  3. 在自動化中始終傳遞 --no-auto-update — 否則 Grok 會聯網檢查更新（且 x.ai/storage.googleapis.com 可能不可達）。
  4. 優先使用 npm install 而非 curl 安裝程序 — npm install -g @xai-official/grok 避免了被 Cloudflare 屏蔽的 x.ai 主機。
  5. --always-approve 是自主構建開關。 如果沒有它，無頭運行可能會因等待工具批准提示而停滯。對於只讀審查/審計工作，故意省略它，以便 Grok 無法修改文件。
  6. 無頭 -p 跳過 TUI 對話框；TUI 需要 pty=true（+ tmux 用於監控），就像 Claude Code 一樣。
  7. 如果使用內聯 TUI 且全屏 alt-screen 接管導致捕獲的輸出混亂，請使用 --no-alt-screen。
  8. 不需要 git 倉庫，但對於 PR/提交工作流，你仍然需要一個 — 使用 mktemp -d && git init 進行臨時提交任務。
  9. 完成後使用 tmux kill-session -t <name> 清理 tmux 會話。

Hermes Agents 規則​

  1. 對於單個任務，優先使用無頭 -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." 煙霧測試；不要假設 Hermes 的 xAI 認證會自動延續。
  8. 向用戶報告結果 — 總結 Grok 更改了什麼以及剩餘什麼。