codex

Codex CLI

通过 Hermes 终端将编码任务委派给 Codex。Codex 是 OpenAI 的自主编码 Agent CLI。

适用场景

• 开发功能
• 重构
• PR 审查
• 批量修复问题

需要安装 codex CLI，并且当前目录必须是 git 仓库。

前置条件

• 已安装 Codex：npm install -g @openai/codex
• 已配置 OpenAI 身份验证：使用 OPENAI_API_KEY 或 Codex CLI 登录流程获取的 Codex OAuth 凭据
• 必须在 git 仓库内运行——Codex 拒绝在仓库外运行
• 在终端调用中使用 pty=true——Codex 是交互式终端应用

对于 Hermes 本身，在执行 hermes auth add openai-codex 后，model.provider: openai-codex 会使用 Hermes 管理的 Codex OAuth，凭据存放在 ~/.hermes/auth.json。对于独立的 Codex CLI，有效的 CLI OAuth 会话可能位于 ~/.codex/auth.json；不能仅凭缺少 OPENAI_API_KEY 就认定 Codex 未通过身份验证。

一次性任务

terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)

用于临时工作（Codex 需要 git 仓库）：

terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)

后台模式（长时间任务）

# Start in background with PTY
terminal(command="codex exec --sandbox workspace-write 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send input if Codex asks a question
process(action="submit", session_id="<id>", data="yes")

# Kill if needed
process(action="kill", session_id="<id>")

关键标志

标志	作用
exec "prompt"	一次性执行，完成后退出
--sandbox workspace-write (-s)	在沙箱中运行，但会自动批准工作区内的文件更改（推荐的自动构建模式）
--dangerously-bypass-approvals-and-sandbox	不使用沙箱，也不需要批准（速度最快，也最危险；--yolo 仍可作为隐藏别名使用）
--sandbox danger-full-access	不使用 Codex 沙箱；适用于宿主服务上下文导致 bubblewrap 无法正常工作的情况

已弃用：--full-auto 仍可使用，但当前 CLI 会提示改用 --sandbox workspace-write。

Hermes 网关注意事项

在 Hermes 网关／服务上下文中调用 Codex CLI 时（例如，由 Telegram 驱动的 Agent 会话），即使同一命令在用户的交互式 shell 中可以正常运行，Codex 的 workspace-write 沙箱也可能失败。常见症状是 bubblewrap／用户命名空间错误，例如 setting up uid map: Permission denied 或 loopback: Failed RTM_NEWADDR: Operation not permitted。

在这种情况下，建议使用：

codex exec --sandbox danger-full-access "<task>"

改用进程边界作为安全层：明确指定 workdir，启动前确保 git 状态干净，使用范围明确的任务提示词，通过 git diff 审查，运行有针对性的测试，并在提交大范围更改前由人工／Agent 确认。

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)

使用 Worktree 并行修复问题

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

# Launch Codex in each
terminal(command="codex --sandbox workspace-write exec 'Fix issue #78: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-78", background=true, pty=true)
terminal(command="codex --sandbox workspace-write exec 'Fix issue #99: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-99", background=true, pty=true)

# Monitor
process(action="list")

# After completion, push and create PRs
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 '...'")

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

批量审查 PR

# Fetch all PR refs
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")

# Review multiple PRs in parallel
terminal(command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
terminal(command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)

# Post results
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")

规则

1. 始终使用 pty=true——Codex 是交互式终端应用，没有 PTY 就会挂起
2. 必须使用 git 仓库——Codex 不会在 git 目录之外运行。临时工作可使用 mktemp -d && git init
3. 一次性任务使用 exec——codex exec "prompt" 会运行并正常退出
4. 构建时使用 --sandbox workspace-write——会自动批准沙箱内的更改（--full-auto 已弃用）
5. 长时间任务放入后台运行——使用 background=true，并通过 process 工具监控
6. 不要干预——通过 poll／log 监控，耐心等待长时间运行的任务
7. 可以并行运行——可同时运行多个 Codex 进程来处理批量任务