Codex CLI
透過 Hermes 終端機將編碼任務委派給 Codex。Codex 是 OpenAI 的自主編碼代理 CLI。
使用時機
- 建構功能
- 重構程式碼
- PR 審查
- 批次問題修正
需要安裝 codex CLI 以及在一個 git 儲存庫內執行。
前提條件
- 已安裝 Codex：
npm install -g @openai/codex - 已設定 OpenAI 驗證：可以是
OPENAI_API_KEY，或來自 Codex CLI 登入流程的 Codex OAuth 憑證 - 必須在 git 儲存庫內執行 — Codex 拒絕在 git 儲存庫外執行
- 在終端機呼叫中使用
pty=true— Codex 是一個互動式終端應用程式
對於 Hermes 本身，model.provider: openai-codex 使用 Hermes 管理的 Codex OAuth，其憑證存放於 ~/.hermes/auth.json，這是透過 hermes auth add openai-codex 設定的。對於獨立的 Codex CLI，有效的 CLI OAuth session 可能位於 ~/.codex/auth.json；不要僅因為缺少 OPENAI_API_KEY 就斷定缺少 Codex 驗證。
一次性任務
terminal(command="codex exec '在設定中新增深色模式切換'"， workdir="~/project", pty=true)
用於臨時工作（Codex 需要一個 git 儲存庫）：
terminal(command="cd $(mktemp -d) && git init && codex exec '用 Python 建立一個貪食蛇遊戲'"， pty=true)
背景模式（長時間任務）
# 在背景啟動，並開啟 PTY
terminal(command="codex exec --full-auto '重構驗證模組'"， workdir="~/project", background=true, pty=true)
# 回傳 session_id
# 監控進度
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
# 如果 Codex 提問，則發送輸入
process(action="submit", session_id="<id>", data="yes")
# 必要時終止
process(action="kill", session_id="<id>")
關鍵旗標
| 旗標 | 效果 |
|---|---|
exec "提示詞" | 一次性執行，完成後退出 |
--full-auto | 在沙盒內運行，但自動批准對工作區的檔案變更 |
--yolo | 無沙盒，無批准（最快，但最危險） |
--sandbox danger-full-access | 無 Codex 沙盒；當主機服務環境破壞 bubblewrap 時很有用 |
Hermes 閘道器注意事項
從 Hermes 閘道器/服務環境（例如 Telegram 驅動的代理 session）呼叫 Codex CLI 時，即使相同的指令在使用者的互動式 shell 中可以正常運作，Codex 的 workspace-write 沙盒機制仍可能失敗。典型的症狀是 bubblewrap/user-namespace 錯誤，例如 setting up uid map: Permission denied 或 loopback: Failed RTM_NEWADDR: Operation not permitted。
在這種情況下，建議使用：
codex exec --sandbox danger-full-access "<任務描述>"
改用進程邊界作為安全層：明確的 workdir、啟動前乾淨的 git 狀態、狹義的任務提示、git diff 審查、目標明確的測試，以及在提交大規模變更前由人員/代理確認。
PR 審查
為安全審查，複製到暫存目錄：
terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main"， pty=true)
使用 Worktrees 進行平行問題修正
# 建立 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")
# 在每個 worktree 中啟動 Codex
terminal(command="codex --yolo exec '修正 issue #78：<描述>。完成後提交。'"， workdir="/tmp/issue-78"， background=true, pty=true)
terminal(command="codex --yolo exec '修正 issue #99：<描述>。完成後提交。'"， workdir="/tmp/issue-99"， background=true, pty=true)
# 監控
process(action="list")
# 完成後，推送並建立 PR
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 '修復：...' --body '...'")
# 清理
terminal(command="git worktree remove /tmp/issue-78"， workdir="~/project")
批次 PR 審查
# 獲取所有 PR 引用
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'"， workdir="~/project")
# 平行審查多個 PR
terminal(command="codex exec '審查 PR #86。git diff origin/main...origin/pr/86'"， workdir="~/project"， background=true, pty=true)
terminal(command="codex exec '審查 PR #87。git diff origin/main...origin/pr/87'"， workdir="~/project"， background=true, pty=true)
# 張貼結果
terminal(command="gh pr comment 86 --body '<審查內容>'"， workdir="~/project")
規則
- 永遠使用
pty=true— Codex 是互動式終端應用程式，沒有 PTY 會掛起 - 需要 Git 儲存庫 — Codex 不會在 git 目錄外執行。臨時工作請使用
mktemp -d && git init - 一次性任務使用
exec—codex exec "提示詞"會執行並乾淨地退出 - 建構時使用
--full-auto— 在沙盒內自動批准變更 - 長時間任務使用背景 — 使用
background=true，並使用process工具監控 - 不要干擾 — 使用
poll/log監控，對長時間運行的任務保持耐心 - 平行執行是可行的 — 可以同時執行多個 Codex 進程以進行批次工作