codex-cli

Codex CLI — Local Usage Guide

OpenAI Codex CLI (@openai/codex) is OpenAI's terminal coding agent. This skill teaches you how to correctly invoke it from Claude Code.

Core Principles

1. Codex is a collaborator, not a replacement. Use it for independent, verifiable subtasks; don't dump the entire session context onto it.
2. Non-interactive first. When invoking from Claude Code, always use codex exec(non-interactive mode), do not launch the interactive TUI.
3. Capture output. Use -o <file> or --json to get the results for subsequent processing.
4. Respect the sandbox. By default use --full-auto(workspace-write sandbox), and only relax it when the user explicitly authorizes it.

---

1. codex exec — Non-interactive task delegation

This is the most core command. Hand a clear prompt to Codex and let it complete it autonomously.

Basic usage

codex exec "你的任务描述" --full-auto -o /tmp/codex-output.md

Key parameters

Parameter	Description	Example
--full-auto	Execute automatically within the sandbox, no step-by-step approval needed	The default choice for most scenarios
-o <file>	Write the final reply to a file	-o /tmp/result.md
--json	Output the entire event stream in JSONL format	Suitable for programmatic parsing
-m <model>	Specify the model	-m o3 -m codex-mini
-C <dir>	Specify the working directory	-C ./my-project
-s <mode>	Sandbox policy:read-only / workspace-write / danger-full-access	-s read-only
--output-schema <file>	Constrain the output structure with a JSON Schema	Structured extraction scenarios
--skip-git-repo-check	Allow running in a non-git directory	Temporary directory scenarios
--ephemeral	Do not save the session to disk	One-off tasks
-i <file>	Attach an image to the prompt	-i screenshot.png
--search	Enable the web search tool	When you need to look up information

Prompt read from stdin

When the prompt is long or contains special characters, passing it via stdin is safer:

cat <<'PROMPT' | codex exec - --full-auto -o /tmp/result.md
在 src/utils/ 下创建一个 debounce 函数，
要求：TypeScript，支持泛型，带取消功能。
写完后运行现有测试确认不破坏。
PROMPT

Common patterns

Delegate a coding subtask:

codex exec "在 src/components/Button.tsx 中添加 loading 状态支持，参考同目录下 Input.tsx 的实现模式" \
  --full-auto -C "$(pwd)" -o /tmp/codex-button.md

Read-only analysis (without modifying files):

codex exec "分析 src/api/ 目录下所有接口的错误处理模式，输出一份报告" \
  --full-auto -s read-only -o /tmp/analysis.md

Structured output:

# 先创建 schema 文件
cat > /tmp/schema.json <<'EOF'
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "files_changed": { "type": "array", "items": { "type": "string" } },
    "risk_level": { "type": "string", "enum": ["low", "medium", "high"] }
  },
  "required": ["summary", "files_changed", "risk_level"]
}
EOF

codex exec "重构 src/utils/date.ts，把 moment 替换为 dayjs" \
  --full-auto --output-schema /tmp/schema.json -o /tmp/result.json

---

2. codex review — Code review

Have Codex perform a non-interactive review of code changes.

Basic usage

# review 未提交的改动（staged + unstaged + untracked）
codex review --uncommitted

# review 相对于某个分支的改动
codex review --base main

# review 某个 commit
codex review --commit abc1234

# 带自定义 review 指令
codex review --uncommitted "重点关注性能问题和潜在的内存泄漏"

Capture review results

The review output goes to stdout and can be redirected directly:

codex review --uncommitted > /tmp/review-result.md 2>&1

---

3. codex cloud exec — Cloud tasks (experimental)

Submit tasks to Codex Cloud for asynchronous execution, suitable for longer-running tasks.

# 提交任务
codex cloud exec "为整个项目添加单元测试，覆盖率目标 80%"

# 查看任务列表
codex cloud list

# 查看任务状态
codex cloud status <task-id>

# 查看 diff
codex cloud diff <task-id>

# 应用改动到本地
codex cloud apply <task-id>

---

4. Other useful commands

Apply the diff of a historical session

codex apply <task-id>

Run as an MCP Server

codex mcp-server

You can register Codex as an MCP server for Claude Code to achieve tool-level integration.

---

5. Best practices for invoking from Claude Code

When to delegate to Codex

Suitable for delegation:

• Independent, clearly bounded coding subtasks (e.g., writing a utility function, refactoring a file)
• Code review (codex review）
• Validation of approaches that need a second opinion
• Large-scale read-only analysis
• The user explicitly requests the use of Codex

Not suitable for delegation:

• Continuous work that requires the current session context
• Operations involving sensitive credentials or keys
• Tasks that require real-time human interaction for confirmation

Construct an effective prompt

The prompt given to Codex should be self-contained, because it cannot see the session context of Claude Code:

✗ "把刚才讨论的那个函数实现一下"
✓ "在 src/utils/format.ts 中创建 formatCurrency 函数，接收 number 和 locale 参数，返回格式化货币字符串。参考同文件中 formatDate 的实现风格。"

Read the output result

# 方式一：-o 写文件，然后读取
codex exec "..." --full-auto -o /tmp/codex-out.md
cat /tmp/codex-out.md

# 方式二：--json 流式解析
codex exec "..." --full-auto --json 2>/dev/null | tail -1

Timeout control

Codex exec has no built-in timeout parameter; use the timeout command to wrap it:

timeout 120 codex exec "..." --full-auto -o /tmp/result.md

Error handling

Check the exit code:

• 0 — success
• Non- 0 — failure, check stderr

if codex exec "..." --full-auto -o /tmp/result.md 2>/tmp/codex-err.log; then
  cat /tmp/result.md
else
  echo "Codex 执行失败："
  cat /tmp/codex-err.log
fi

---

6. Local configuration reference

The Codex configuration on the current machine is located at ~/.codex/config.toml. Key configuration items:

# 模型提供商与模型
model_provider = "rightcode"
model = "gpt-5.4"

# 沙箱策略（exec 子命令可覆盖）
# -s read-only | workspace-write | danger-full-access

# 项目信任级别
[projects."/path/to/project"]
trust_level = "trusted"  # trusted 项目可跳过部分审批

# MCP 服务器（Codex 也支持 MCP 集成）
[mcp_servers.xxx]
type = "stdio"
command = "..."
args = [...]

At runtime, any configuration item can be overridden via -c key=value :

codex exec "..." -c model="o3" -c model_reasoning_effort="high"