Back to Details

codex

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex CLI

Codex CLI

Delegate coding tasks to Codex via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI.
通过Hermes终端将编码任务委托给Codex。Codex是OpenAI的自主编码Agent CLI。

When to use

使用场景

  • Building features
  • Refactoring
  • PR reviews
  • Batch issue fixing
Requires the codex CLI and a git repository.
  • 功能开发
  • 代码重构
  • PR评审
  • 批量修复问题
需要安装codex CLI并处于git仓库环境中。

Prerequisites

前置条件

  • Codex installed: 
    npm install -g @openai/codex
  • OpenAI auth configured: either 
    OPENAI_API_KEY
    or Codex OAuth credentials from the Codex CLI login flow
  • Must run inside a git repository — Codex refuses to run outside one
  • Use 
    pty=true
    in terminal calls — Codex is an interactive terminal app
For Hermes itself, 
model.provider: openai-codex
uses Hermes-managed Codex OAuth from 
~/.hermes/auth.json
after 
hermes auth add openai-codex
. For the standalone Codex CLI, a valid CLI OAuth session may live under 
~/.codex/auth.json
; do not treat a missing 
OPENAI_API_KEY
alone as proof that Codex auth is missing.
  • 已安装Codex：
    npm install -g @openai/codex
  • 已配置OpenAI认证：可通过
    OPENAI_API_KEY
    或Codex CLI登录流程获取的Codex OAuth凭证
  • 必须在git仓库内运行——Codex拒绝在仓库外运行
  • 在终端调用中使用
    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认证缺失。

One-Shot Tasks

一次性任务

terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)
For scratch work (Codex needs a git repo):
terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)
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)

Background Mode (Long Tasks)

后台模式（长时任务）

undefined
undefined

Start in background with PTY

启动带PTY的后台任务

terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)

Returns session_id

返回session_id

Monitor progress

监控进度

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

Send input if Codex asks a question

当Codex提问时发送输入

process(action="submit", session_id="<id>", data="yes")
process(action="submit", session_id="<id>", data="yes")

Kill if needed

必要时终止任务

process(action="kill", session_id="<id>")
undefined
process(action="kill", session_id="<id>")
undefined

Key Flags

关键参数

FlagEffect
exec "prompt"
One-shot execution, exits when done
--full-auto
Sandboxed but auto-approves file changes in workspace
--yolo
No sandbox, no approvals (fastest, most dangerous)
参数作用
exec "prompt"
一次性执行，完成后退出
--full-auto
沙箱环境下自动批准工作区中的文件变更
--yolo
无沙箱、无批准（速度最快，风险最高）

PR Reviews

PR评审

Clone to a temp directory for safe review:
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)
克隆到临时目录以安全评审：
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)

Parallel Issue Fixing with Worktrees

使用工作树批量修复问题

undefined
undefined

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")
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 Codex in each

在每个工作树中启动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)
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)

Monitor

监控任务

process(action="list")
process(action="list")

After completion, push and create PRs

完成后推送并创建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="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")
undefined
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
undefined

Batch PR Reviews

批量PR评审

undefined
undefined

Fetch all PR refs

获取所有PR引用

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

Review multiple PRs in parallel

并行评审多个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="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")
undefined
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
undefined

Rules

规则

  1. Always use 
    pty=true
     — Codex is an interactive terminal app and hangs without a PTY
  2. Git repo required — Codex won't run outside a git directory. Use 
    mktemp -d && git init
    for scratch
  3. Use 
    exec
    for one-shots     — 
    codex exec "prompt"
    runs and exits cleanly
  4. --full-auto
    for building     — auto-approves changes within the sandbox
  5. Background for long tasks — use 
    background=true
    and monitor with 
    process
    tool
  6. Don't interfere — monitor with 
    poll
    /
    log
    , be patient with long-running tasks
  7. Parallel is fine — run multiple Codex processes at once for batch work
  1. 始终使用
    pty=true
    ——Codex是交互式终端应用，没有PTY会挂起
  2. 必须使用git仓库——Codex不会在git目录外运行。临时工作可使用
    mktemp -d && git init
  3. 一次性任务使用
    exec
    ——
    codex exec "prompt"
    运行完成后会干净退出
  4. 开发时使用
    --full-auto
    ——在沙箱内自动批准变更
  5. 长时任务使用后台模式——使用
    background=true
    并通过
    process
    工具监控
  6. 不要干预——使用
    poll
    /
    log
    监控，对长时任务保持耐心
  7. 支持并行运行——可同时运行多个Codex进程处理批量任务