codex

Codex 执行技能

先决条件

• 已安装并配置 Codex CLI（~/.codex/config.toml）
• 验证是否可用：每个会话首次使用时运行 codex --version

工作流检查清单

每项 Codex 任务都遵循以下步骤：

1. ☐ 检测 HPC/Slurm 环境：

   • 检查是否在 HPC 集群上运行（查找 /home/woody/、/home/hpc/、Slurm 环境变量）
   • 如果检测到 HPC：始终使用 --yolo 标志绕过 Landlock 沙箱限制

2. ☐ 通过 AskUserQuestion 询问用户执行参数（单次提示）：

   • 模型：gpt-5、gpt-5-codex 或默认值
   • 推理力度：minimal、low、medium、high

3. ☐ 根据任务确定沙箱模式：

   • read-only：代码审查、分析、文档
   • workspace-write：修改代码、创建文件
   • danger-full-access：系统操作、网络访问
   • HPC 覆盖规则：始终添加 --yolo 标志（绕过 Landlock 限制）

4. ☐ 添加必需标志来构建命令：

   codex exec [OPTIONS] "PROMPT"
   

   必需标志：

   • -m <MODEL>（覆盖默认值时）
   • -c model_reasoning_effort="<LEVEL>"
   • -s <SANDBOX_MODE>（HPC 环境下跳过）
   • --skip-git-repo-check（位于 git 仓库之外时）
   • -C <DIRECTORY>（更改工作区时）
   • --full-auto（用于非交互式执行，不能与 --yolo 一起使用）

   HPC 命令模式（使用 --yolo 绕过 Landlock）：

   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
     "Analyze this code: $(cat /path/to/file.py)" 2>/dev/null
   

   注意：--yolo 是 --dangerously-bypass-approvals-and-sandbox 的别名，在 HPC 集群上为避免 Landlock 沙箱错误而必须使用。不要将 --full-auto 与 --yolo 一起使用，两者不兼容。

5. ☐ 执行时抑制 stderr：

   • 添加 2>/dev/null 以隐藏思考 token
   • 仅在用户要求详细输出或调试时移除

6. ☐ 验证执行结果：

   • 检查退出代码（0 = 成功）
   • 向用户总结输出
   • 报告错误并提供可操作的解决方案
   • 如果 HPC 上出现 Landlock/沙箱错误：确认是否使用了 --yolo 标志，如果未使用则重试

7. ☐ 告知用户可恢复会话：

   • “随时恢复此会话：codex resume”

命令模式

🔥 HPC 快速提示：在 HPC 集群上（例如 /home/woody/、/home/hpc/），始终添加 --yolo 标志以避免 Landlock 沙箱错误。例如：codex exec --yolo -m gpt-5 ...

只读分析

codex exec -m gpt-5 -c model_reasoning_effort="medium" -s read-only \
  --skip-git-repo-check --full-auto "review @file.py for security issues" 2>/dev/null

标准输入（绕过沙箱文件限制）

cat file.py | codex exec -m gpt-5 -c model_reasoning_effort="low" \
  --skip-git-repo-check --full-auto - 2>/dev/null

注意：并非所有 Codex CLI 版本都支持使用 - 标志的标准输入。

HPC/Slurm 环境（YOLO 模式——绕过 Landlock）

在受 Landlock 安全限制的 HPC 集群上运行时，请使用 --yolo 标志：

# Primary solution: --yolo flag bypasses Landlock sandbox
codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
  "Analyze this code: $(cat /path/to/file.py)" 2>/dev/null

替代方案：手动注入代码（如果无法使用 --yolo）：

# Capture code content and pass directly in prompt
codex exec -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check --full-auto \
  "Analyze this Python code: $(cat file.py)" 2>/dev/null

对于大型文件，也可以使用 heredoc：

codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check "$(cat <<'ENDCODE'
Analyze the following code comprehensively:

$(cat file.py)

Focus on: architecture, algorithms, multi-GPU optimization, potential bugs, code quality.
ENDCODE
)" 2>/dev/null

注意：--yolo 是 --dangerously-bypass-approvals-and-sandbox 的简称，在权限本就有限的 HPC 登录节点上使用是安全的。不要将 --yolo 与 --full-auto 结合使用，两者不兼容。

修改代码

codex exec -m gpt-5 -c model_reasoning_effort="high" -s workspace-write \
  --skip-git-repo-check --full-auto "refactor @module.py to async/await" 2>/dev/null

恢复会话

echo "fix the remaining issues" | codex exec --skip-git-repo-check resume --last 2>/dev/null

跨目录执行

codex exec -C /path/to/project -m gpt-5 -c model_reasoning_effort="medium" \
  -s read-only --skip-git-repo-check --full-auto "analyze architecture" 2>/dev/null

使用配置档

codex exec --profile production -c model_reasoning_effort="high" \
  --full-auto "optimize performance in @app.py" 2>/dev/null

CLI 参考

核心标志

标志	值	使用时机
-m, --model	gpt-5、gpt-5-codex	覆盖默认模型
-c, --config	key=value	运行时配置覆盖（可重复使用）
-s, --sandbox	read-only、workspace-write、danger-full-access	设置执行权限
--yolo	标志	HPC 上必须使用 - 绕过所有沙盒限制（--dangerously-bypass-approvals-and-sandbox 的别名）。不能与 --full-auto 一起使用
-C, --cd	path	更改工作区目录
--skip-git-repo-check	标志	允许在 Git 仓库外执行
--full-auto	标志	非交互模式（workspace-write + 失败时请求批准）。不能与 --yolo 一起使用
-p, --profile	string	从 config.toml 加载配置档案
--json	标志	JSON 事件输出（CI/CD 流水线）
-o, --output-last-message	path	将最终消息写入文件
-i, --image	path[,path...]	附加图像（可重复使用或以逗号分隔）
--oss	标志	使用本地开源模型（需要 Ollama）

配置选项

模型推理力度（-c model_reasoning_effort="<LEVEL>"）：

• minimal：快速任务、简单查询
• low：常规操作、日常重构
• medium：复杂分析、架构决策（默认）
• high：关键代码、安全审计、复杂算法

模型详尽程度（-c model_verbosity="<LEVEL>"）：

• low：最简输出
• medium：详略平衡（默认）
• high：详细解释

批准提示（-c approvals="<WHEN>"）：

• on-request：使用任何工具之前
• on-failure：仅在出错时（--full-auto 的默认设置）
• untrusted：尽量减少提示
• never：不受打扰（谨慎使用）

配置管理

配置文件位置

~/.codex/config.toml

运行时覆盖

# Override single setting
codex exec -c model="gpt-5" "task"

# Override multiple settings
codex exec -c model="gpt-5" -c model_reasoning_effort="high" "task"

使用配置档案

在 config.toml 中定义：

[profiles.research]
model = "gpt-5"
model_reasoning_effort = "high"
sandbox = "read-only"

[profiles.development]
model = "gpt-5-codex"
sandbox = "workspace-write"

使用方式：

codex exec --profile research "analyze codebase"

恢复行为

自动继承：

• 模型选择
• 推理力度
• 沙盒模式
• 配置覆盖

恢复语法：

# Resume last session
codex exec resume --last

# Resume with new prompt
codex exec resume --last "continue with next steps"

# Resume via stdin
echo "new instructions" | codex exec resume --last 2>/dev/null

# Resume specific session
codex exec resume <SESSION_ID> "follow-up task"

标志注入（位于 exec 和 resume 之间）：

# Change reasoning effort for resumed session
codex exec -c model_reasoning_effort="high" resume --last

错误处理

验证循环

1. 执行命令
2. 检查退出码（非零表示失败）
3. 提供包含上下文的错误报告
4. 通过 AskUserQuestion 询问用户如何处理
5. 调整后重试或升级处理

权限请求

使用高影响标志前，通过 AskUserQuestion 请求用户批准：

• --full-auto：自动执行
• -s danger-full-access：系统级访问权限
• --yolo / --dangerously-bypass-approvals-and-sandbox：
  • HPC 集群：无需批准（运行所必需）
  • 个人计算机：请求批准（完全系统访问权限）

部分成功处理

当输出包含警告时：

1. 总结成功的操作
2. 说明失败情况及相关上下文
3. 使用 AskUserQuestion 确定后续步骤
4. 提出具体的调整建议

故障排除

文件访问受阻

症状："shell is blocked by the sandbox" 或权限错误

根本原因：沙盒的 read-only 模式限制了文件系统访问

解决方案（按优先级排列）：

1. 通过标准输入传递（推荐）：

   cat target.py | codex exec -m gpt-5 -c model_reasoning_effort="medium" \
     --skip-git-repo-check --full-auto - 2>/dev/null
   

2. 显式设置权限：

   codex exec -m gpt-5 -s read-only \
     -c 'sandbox_permissions=["disk-full-read-access"]' \
     --skip-git-repo-check --full-auto "@file.py" 2>/dev/null
   

3. 升级沙盒权限：

   codex exec -m gpt-5 -s workspace-write \
     --skip-git-repo-check --full-auto "review @file.py" 2>/dev/null
   

无效标志错误

症状："unexpected argument '--add-dir' found"

原因：Codex CLI 中不存在该标志

解决方案：使用 -C <DIR> 更改目录：

codex exec -C /target/dir -m gpt-5 --skip-git-repo-check \
  --full-auto "task" 2>/dev/null

退出码错误

症状：退出码非零，但没有明确的错误消息

诊断步骤：

1. 移除 2>/dev/null 以查看完整的 stderr
2. 验证安装：codex --version
3. 检查配置：cat ~/.codex/config.toml
4. 测试最简命令：codex exec -m gpt-5 "hello world"
5. 验证模型访问权限：codex exec --model gpt-5 "test"

模型不可用

症状：“找不到模型”或身份验证错误

解决方案：

1. 检查已配置的模型：grep model ~/.codex/config.toml
2. 验证 API 访问权限：确保凭据有效
3. 尝试其他模型：-m gpt-5-codex
4. 使用 OSS 回退方案：--oss（需要 Ollama）

会话恢复失败

症状：无法恢复之前的会话

诊断步骤：

1. 列出最近的会话：codex history
2. 验证会话 ID 格式
3. 尝试使用 --last 标志，而不是指定 ID
4. 检查会话是否已过期或被清理

HPC/Slurm 沙箱故障

症状：“Landlock 沙箱错误”、“LandlockRestrict”或所有文件操作均失败

根本原因：HPC 集群使用 Landlock/seccomp 内核安全模块，这些模块会阻止 Codex 的默认沙箱

✅ 解决方案：使用 --yolo 标志（优先级顺序）：

1. YOLO 标志（主要解决方案——适用于 HPC）：

   # Bypasses Landlock restrictions completely
   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
     "Analyze this code: $(cat /full/path/to/file.py)" 2>/dev/null
   

   有效原因：--yolo（--dangerously-bypass-approvals-and-sandbox 的别名）会完全禁用 Codex 沙箱，从而允许在 HPC 系统上直接访问文件。注意：不要同时使用 --full-auto 和 --yolo，因为两者不兼容。

2. 手动注入代码（--yolo 不可用时的备用方案）：

   # Pass code directly in prompt via command substitution
   codex exec -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check --full-auto \
     "Analyze this code comprehensively: $(cat /full/path/to/file.py)" 2>/dev/null
   

3. 使用 Heredoc 输入长代码：

   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check "$(cat <<'EOF'
   Analyze the following Python code for architecture, bugs, and optimization opportunities:
   
   $(cat /home/user/script.py)
   
   Provide technical depth with actionable insights.
   EOF
   )" 2>/dev/null
   

4. 在登录节点上运行（如果计算节点阻止出站连接）：

   # SSH to login node first, then run codex there (not in Slurm job)
   ssh login.cluster.edu
   codex exec --yolo -m gpt-5 --skip-git-repo-check "analyze @file.py" 2>/dev/null
   

5. 使用 Apptainer/Singularity（如果集群支持）：

   # Build image with Codex installed, then run via Slurm
   singularity exec codex.sif codex exec --yolo -m gpt-5 "task"
   

HPC 最佳实践：

• 在 HPC 集群上始终使用 --yolo 标志——在登录节点上使用是安全的，因为你本来就只有有限的权限
• 在登录节点上运行分析，仅将繁重的计算任务提交到 Slurm
• 将代码文件保存在登录节点可读取的共享文件系统中
• 将 --yolo 与 $(cat file.py) 结合使用，以实现最大兼容性

最佳实践

推理强度选择

• minimal：语法修复、简单重命名
• low：常规重构、基础分析
• medium：复杂重构、架构审查
• high：安全审计、算法优化、严重错误

沙箱模式选择

• read-only：任何分析或审查任务的默认模式
• workspace-write：仅修改文件
• danger-full-access：网络操作、系统命令（较少使用）

抑制 Stderr

• 除非符合以下情况，否则始终使用 2>/dev/null：
  • 用户明确请求显示思维过程 tokens
  • 调试失败的命令
  • 排查配置问题

配置文件的使用

为常见工作流创建配置文件：

• review：高推理强度，只读
• refactor：中等推理强度，workspace-write
• quick：低推理强度，只读
• security：高推理强度，workspace-write

标准输入与文件引用

• 标准输入：分析单个文件，避免权限问题
• 文件引用：提供多文件上下文，进行代码库范围的更改

安全指南

HPC 集群——--yolo 安全且必需：

• HPC 登录节点本身已有严格的权限限制（无 root 访问权限，不能修改网络）
• --yolo 会绕过 Codex 沙箱，但你仍受 HPC 用户权限限制
• 在 HPC 上始终使用 --yolo，以避免 Landlock 错误

一般使用——谨慎操作：

• 不要在不受限制的系统上使用 --yolo（你的笔记本电脑、拥有完整 sudo 权限的云 VM）
• 常规开发时优先使用 --full-auto + -s workspace-write

以下操作前务必确认：

• 使用 danger-full-access 沙箱（HPC 环境之外）
• 在生产系统上禁用审批提示
• 在拥有 sudo 权限的个人设备上使用 --yolo 运行

以下情况需征得用户同意：

• 首次使用 workspace-write
• 请求系统范围的访问权限
• 执行破坏性操作（删除、迁移）

高级用法

CI/CD 集成

codex exec --json -o result.txt -m gpt-5 \
  -c model_reasoning_effort="medium" \
  --skip-git-repo-check --full-auto \
  "run security audit on changed files" 2>/dev/null

批处理

for file in *.py; do
  cat "$file" | codex exec -m gpt-5 -c model_reasoning_effort="low" \
    --skip-git-repo-check --full-auto "lint and format" - 2>/dev/null
done

多步骤工作流

# Step 1: Analysis
codex exec -m gpt-5 -c model_reasoning_effort="high" -s read-only \
  --full-auto "analyze @codebase for architectural issues" 2>/dev/null

# Step 2: Resume with changes
echo "implement suggested refactoring" | \
  codex exec -s workspace-write resume --last 2>/dev/null

何时升级处理

如果排查后错误仍然存在：

1. 查阅文档：

   WebFetch https://developers.openai.com/codex/cli/reference
   

   WebFetch https://developers.openai.com/codex/local-config#cli
   

2. 向用户报告：

   • 错误消息原文
   • 已尝试的解决方案
   • 配置详情
   • 退出代码和 stderr 输出

3. 请求指导：

   • 替代方案
   • 配置调整
   • 需要人工干预的环节

模型选择指南

任务类型	推荐模型	推理强度
快速语法修复	gpt-5	minimal
代码审查	gpt-5	medium
重构	gpt-5-codex	medium
架构分析	gpt-5	high
安全审计	gpt-5	high
算法优化	gpt-5-codex	high
文档生成	gpt-5	low

常见工作流

代码审查工作流

1. 询问用户：模型 + 推理强度
2. 运行只读分析
3. 展示发现
4. 如需修改：使用 workspace-write 恢复
5. 验证修改
6. 告知用户可恢复执行

重构工作流

1. 询问用户：模型 + 推理强度
2. 分析当前代码（只读）
3. 提出修改方案
4. 征得用户批准
5. 应用修改（workspace-write）
6. 运行验证/测试
7. 报告结果

安全审计工作流

1. 使用高推理强度
2. 运行全面分析（只读）
3. 记录发现
4. 提出修复方案
5. 经批准后应用修复（workspace-write）
6. 重新审计以进行验证
7. 生成报告