Back to Details

codex

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex Subagent

Codex子代理

Session ID: ${CLAUDE_SESSION_ID} Output: 
~/.claude/codex/${CLAUDE_SESSION_ID}/
会话ID: ${CLAUDE_SESSION_ID} 输出路径: 
~/.claude/codex/${CLAUDE_SESSION_ID}/

Arguments

参数

Task: $ARGUMENTS
Optional flags (only if user explicitly requests):
  • --model <model>
    : 
    gpt-5.2-codex
    (default), 
    gpt-5.2
    , 
    gpt-5-mini
    , 
    o3
  • --sandbox <mode>
    : 
    read-only
    , 
    workspace-write
    , 
    danger-full-access
Omit flags to use user's config defaults.
任务: $ARGUMENTS
可选标志（仅当用户明确要求时添加）:
  • --model <model>
    : 可选值 
    gpt-5.2-codex
    （默认）、
    gpt-5.2
    、
    gpt-5-mini
    、
    o3
  • --sandbox <mode>
    : 可选值 
    read-only
    、
    workspace-write
    、
    danger-full-access
省略标志将使用用户的默认配置。

Context Depth

上下文深度

Minimal: Specific file/function → git state only Medium: Feature/multi-file → add recent changes Full: Investigation/unclear → add session summary
最小: 针对特定文件/函数 → 仅提供git状态 中等: 针对功能/多文件任务 → 额外添加最近变更记录 完整: 针对调研/需求不清晰的场景 → 额外添加会话摘要

Gather Context

收集上下文

Always:
bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "Not a git repo"
git branch --show-current 2>/dev/null && git status --short 2>/dev/null | head -20
Medium/Full:
bash
git diff --stat 2>/dev/null | tail -20
git log --oneline -5 --since="4 hours ago" 2>/dev/null
Full only: Session summary (work done, decisions, blockers)
始终执行:
bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "Not a git repo"
git branch --show-current 2>/dev/null && git status --short 2>/dev/null | head -20
中等/完整深度额外执行:
bash
git diff --stat 2>/dev/null | tail -20
git log --oneline -5 --since="4 hours ago" 2>/dev/null
仅完整深度: 会话摘要（已完成工作、已做决策、阻塞问题）

Prompt Structure

Prompt结构

Use CTCO format (Context → Task → Constraints → Output):
<context>
Working directory: {cwd}
Repository: {repo_name}
Branch: {branch}
{git_status}
{recent_changes if medium/full}
{session_summary if full}
</context>

<task>
{task from arguments}
</task>

<constraints>
- Implement EXACTLY what is requested
- Read files before changing
- Run tests/linters to validate
- State interpretation if ambiguous
</constraints>

<output>
Summary (≤5 bullets):
- **What changed**: Files and changes
- **Where**: file:line references
- **Validation**: Tests/linters run
- **Risks**: Edge cases to watch
- **Next steps**: Follow-up or "None"
</output>
使用CTCO格式（上下文 → 任务 → 约束 → 输出）:
<context>
工作目录: {cwd}
代码仓库: {repo_name}
分支: {branch}
{git_status}
{recent_changes if medium/full}
{session_summary if full}
</context>

<task>
{参数传入的任务内容}
</task>

<constraints>
- 严格按照需求实现
- 修改文件前先读取文件内容
- 运行测试/linters验证改动
- 若需求有歧义，请说明你的理解
</constraints>

<output>
摘要（不超过5条）:
- **改动内容**: 涉及的文件和具体变更
- **改动位置**: 文件:行号引用
- **验证情况**: 已运行的测试/linters
- **潜在风险**: 需要注意的边界情况
- **后续步骤**: 后续待办事项或"无"
</output>

Execute

执行

Setup:
bash
mkdir -p ~/.claude/codex/${CLAUDE_SESSION_ID}
git rev-parse --show-toplevel 2>/dev/null && IN_GIT=true || IN_GIT=false
Run:
bash
codex exec --json \
  -o ~/.claude/codex/${CLAUDE_SESSION_ID}/summary-{timestamp}.txt \
  {--skip-git-repo-check if not in git} \
  {--full-auto OR --sandbox <mode>} \
  {-m <model> if requested} \
  - <<'CODEX_PROMPT'
{prompt}
CODEX_PROMPT > ~/.claude/codex/${CLAUDE_SESSION_ID}/progress-{timestamp}.jsonl
Flags:
  • Not in git: add 
    --skip-git-repo-check
  • Default: 
    --full-auto
    (workspace-write + auto-approval)
  • User-requested: 
    --sandbox <mode>
    or 
    -m <model>
初始化:
bash
mkdir -p ~/.claude/codex/${CLAUDE_SESSION_ID}
git rev-parse --show-toplevel 2>/dev/null && IN_GIT=true || IN_GIT=false
运行:
bash
codex exec --json \
  -o ~/.claude/codex/${CLAUDE_SESSION_ID}/summary-{timestamp}.txt \
  {--skip-git-repo-check if not in git} \
  {--full-auto OR --sandbox <mode>} \
  {-m <model> if requested} \
  - <<'CODEX_PROMPT'
{prompt}
CODEX_PROMPT > ~/.claude/codex/${CLAUDE_SESSION_ID}/progress-{timestamp}.jsonl
标志说明:
  • 不在git仓库中: 添加 
    --skip-git-repo-check
  • 默认模式: 
    --full-auto
    （工作区可写 + 自动审批）
  • 用户指定模式: 使用 
    --sandbox <mode>
    或 
    -m <model>

Background vs Foreground

后台 vs 前台执行

Background tasks (>30 seconds expected):
  • Multi-file changes, investigations, tests, feature work
  • Use 
    run_in_background: true
    → returns 
    task_id
Foreground tasks (<30 seconds):
  • Single-line fixes, simple queries
后台任务（预计耗时>30秒）:
  • 多文件变更、问题调研、测试运行、功能开发
  • 使用 
    run_in_background: true
    → 会返回 
    task_id
前台任务（耗时<30秒）:
  • 单行代码修复、简单查询

Monitoring Background Tasks

监控后台任务

Token-efficient approach:
  1. Use 
    TaskOutput(task_id, block=true)
    to wait for completion
  2. Ignore TaskOutput's content (stdout redirected to progress file)
  3. Read summary file directly: 
    cat ~/.claude/codex/${CLAUDE_SESSION_ID}/summary-*.txt
The summary file contains only Codex's final message (token-efficient).
Progress checks (if needed before completion):
  • TaskOutput(task_id, block=false)
    - check if still running
  • tail -n 3 ~/.claude/codex/${CLAUDE_SESSION_ID}/progress-*.jsonl
    - last 3 events only
Do NOT read entire progress files or use 
tail -f
.
Token高效方案:
  1. 使用 
    TaskOutput(task_id, block=true)
    等待任务完成
  2. 忽略TaskOutput的内容（标准输出已重定向到进度文件）
  3. 直接读取摘要文件: 
    cat ~/.claude/codex/${CLAUDE_SESSION_ID}/summary-*.txt
摘要文件仅包含Codex的最终消息（Token利用率高）。
进度查询（如果需要在任务完成前查看进度）:
  • TaskOutput(task_id, block=false)
    - 检查任务是否仍在运行
  • tail -n 3 ~/.claude/codex/${CLAUDE_SESSION_ID}/progress-*.jsonl
    - 仅查看最近3条事件
禁止 读取完整进度文件或使用 
tail -f
命令。

Report Result

报告结果

Read summary:
bash
cat ~/.claude/codex/${CLAUDE_SESSION_ID}/summary-*.txt
Report format (≤5 bullets):
**Status:** {success/error/partial}
**Changed:** {files and changes}
**Validation:** {tests/linters}
**Risks:** {if any}
**Next:** {follow-up or "None"}
读取摘要:
bash
cat ~/.claude/codex/${CLAUDE_SESSION_ID}/summary-*.txt
报告格式（不超过5条）:
**Status:** {success/error/partial}
**Changed:** {files and changes}
**Validation:** {tests/linters}
**Risks:** {if any}
**Next:** {follow-up or "None"}

Examples

示例

bash
undefined
bash
undefined

Simple fix

简单修复

/codex fix the null pointer in utils/parser.ts line 42
/codex fix the null pointer in utils/parser.ts line 42

Feature work

功能开发

/codex add rate limiting to the /api/submit endpoint
/codex add rate limiting to the /api/submit endpoint

Investigation (background)

问题调研（后台执行）

/codex investigate why the CI build fails on arm64
/codex investigate why the CI build fails on arm64

Model override

覆盖默认模型

/codex --model o3 design a caching strategy
/codex --model o3 design a caching strategy

Read-only

只读模式

/codex --sandbox read-only review the auth implementation
undefined
/codex --sandbox read-only review the auth implementation
undefined