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 会话可能位于 ~/.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)
后台模式(长时间任务)
# 在后台启动并使用 PTY
terminal(command="codex exec --full-auto 'Refactor the auth module'", 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 "prompt" | 一次性执行,完成后退出 |
--full-auto | 沙箱化但自动批准工作区内的文件更改 |
--yolo | 无沙箱、无批准(最快,最危险) |
--sandbox danger-full-access | 不使用 Codex 沙箱;当主机服务上下文破坏了 bubblewrap 时非常有用 |
Hermes 网关注意事项
当从 Hermes 网关/服务上下文(例如 Telegram 驱动的代理会话)调用 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 "<task>"
转而使用进程边界作为安全层:明确的 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)
使用 Worktree 并行修复问题
# 创建 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 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", 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 'fix: ...' --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 '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)
# 发布结果
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
规则
- 始终使用
pty=true——Codex 是一个交互式终端应用,没有 PTY 会挂起 - 需要 git 仓库——Codex 不会在非 git 目录下运行。临时工作请使用
mktemp -d && git init - 使用
exec进行一次性任务——codex exec "prompt"运行后干净退出 --full-auto用于构建——自动批准沙箱内的更改- 长时间任务使用后台模式——使用
background=true并通过process工具监控 - 不要干扰——使用
poll/log监控,耐心等待长时间运行的任务 - 并行没问题——可以同时运行多个 Codex 进程以处理批量工作