codex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex: High-Reasoning AI Assistant for Claude Code

Codex：面向Claude Code的高推理AI助手

DEFAULT MODEL: Task-Based Model Selection with Read-Only Default

默认模型：基于任务的模型选择，默认只读模式

Codex uses task-based model selection. Sandbox is
read-only
by default - only use
workspace-write
when user explicitly requests file editing.

Task Type	Model	Sandbox (default)	Sandbox (explicit edit)
Code-related tasks	`gpt-5.3-codex`	read-only	workspace-write
General tasks	`gpt-5.2`	read-only	workspace-write

Code-related tasks: Use
```
gpt-5.3-codex
```
- optimized for agentic coding (56.8% SWE-Bench Pro)
General tasks: Use
```
gpt-5.2
```
- high-reasoning general model
Sandbox default: Always
```
read-only
```
unless user explicitly requests editing
Explicit editing: Only when user says "edit", "modify", "write changes", etc., use
```
workspace-write
```
Always use
```
-c model_reasoning_effort=xhigh
```
for maximum capability

bash

undefined

Codex采用基于任务的模型选择策略。沙箱默认设置为
read-only
（只读）——仅当用户明确要求编辑文件时，才使用
workspace-write
（工作区可写）模式。

任务类型	模型	沙箱模式（默认）	沙箱模式（明确编辑请求）
代码相关任务	`gpt-5.3-codex`	read-only	workspace-write
通用任务	`gpt-5.2`	read-only	workspace-write

代码相关任务：使用
```
gpt-5.3-codex
```
——针对智能编码优化（在SWE-Bench Pro上达到56.8%的表现）
通用任务：使用
```
gpt-5.2
```
——高推理能力通用模型
沙箱默认设置：始终为
```
read-only
```
，除非用户明确要求编辑
明确编辑请求：仅当用户说出“edit”、“modify”、“write changes”等词汇时，才使用
```
workspace-write
```
始终使用
```
-c model_reasoning_effort=xhigh
```
以获取最大能力

bash

undefined

Code task (read-only default)

codex exec -m gpt-5.3-codex -s read-only
-c model_reasoning_effort=xhigh
"analyze this function implementation"

General task (read-only default)

codex exec -m gpt-5.2 -s read-only
-c model_reasoning_effort=xhigh
"explain this architecture"

Code task with explicit edit request

codex exec -m gpt-5.3-codex -s workspace-write
-c model_reasoning_effort=xhigh
"edit this file to add the feature"

General task with explicit edit request

codex exec -m gpt-5.2 -s workspace-write
-c model_reasoning_effort=xhigh
"modify the documentation file"

undefined

codex exec -m gpt-5.2 -s workspace-write
-c model_reasoning_effort=xhigh
"modify the documentation file"

undefined

Model Fallback Chain

模型降级链

If the primary model is unavailable, fallback gracefully:

Code tasks:
```
gpt-5.3-codex
```
→
```
gpt-5.2
```
General tasks:
```
gpt-5.2
```
→
```
gpt-5.3-codex
```
Reasoning effort:
```
xhigh
```
→
```
high
```
→
```
medium
```

如果主模型不可用，按以下规则优雅降级：

代码任务：
```
gpt-5.3-codex
```
→
```
gpt-5.2
```
通用任务：
```
gpt-5.2
```
→
```
gpt-5.3-codex
```
推理能力：
```
xhigh
```
→
```
high
```
→
```
medium
```

CRITICAL: Always Use

codex exec

重要提示：始终使用

codex exec

MUST USE:

codex exec

for ALL Codex CLI invocations in Claude Code.

NEVER USE:

codex

(interactive mode) - will fail with "stdout is not a terminal" ALWAYS USE:

codex exec

(non-interactive mode)

Examples:

```
codex exec -m gpt-5.2 "prompt"
```
(CORRECT)
```
codex -m gpt-5.2 "prompt"
```
(WRONG - will fail)
```
codex exec resume --last
```
(CORRECT)
```
codex resume --last
```
(WRONG - will fail)

Why? Claude Code's bash environment is non-terminal/non-interactive. Only

codex exec

works in this environment.

必须使用：在Claude Code中调用Codex CLI时，一律使用

codex exec

。

禁止使用：

codex

（交互模式）——会因“stdout is not a terminal”错误失败 务必使用：

codex exec

（非交互模式）

示例：

```
codex exec -m gpt-5.2 "prompt"
```
（正确）
```
codex -m gpt-5.2 "prompt"
```
（错误——会失败）
```
codex exec resume --last
```
（正确）
```
codex resume --last
```
（错误——会失败）

原因？ Claude Code的bash环境为非终端/非交互式环境，仅

codex exec

可在此环境中正常工作。

IMPORTANT: Interactive vs Exec Mode Flags

注意：交互模式与Exec模式的参数差异

Some Codex CLI flags are ONLY available in interactive mode, NOT in
codex exec
.

Flag	Interactive `codex`	`codex exec`	Alternative for exec
`--search`	✅ Available	❌ NOT available	`--enable web_search_request`
`-a/--ask-for-approval`	✅ Available	❌ NOT available	`--full-auto` or `-c approval_policy=...`
`--add-dir`	✅ Available	✅ Available	N/A
`--full-auto`	✅ Available	✅ Available	N/A

For web search in exec mode:

bash

undefined

部分Codex CLI参数仅在交互模式下可用，无法在
codex exec
中使用。

参数	交互模式 `codex`	`codex exec`	Exec模式替代方案
`--search`	✅ 可用	❌ 不可用	`--enable web_search_request`
`-a/--ask-for-approval`	✅ 可用	❌ 不可用	`--full-auto` 或 `-c approval_policy=...`
`--add-dir`	✅ 可用	✅ 可用	无
`--full-auto`	✅ 可用	✅ 可用	无

Exec模式下的网页搜索：

bash

undefined

CORRECT - works in codex exec

正确——在codex exec中可用

codex exec --enable web_search_request "research topic"

WRONG - --search only works in interactive mode

错误——--search仅在交互模式下可用

codex --search "research topic"


**For approval control in exec mode**:
```bash

codex --search "research topic"


**Exec模式下的审批控制：**
```bash

CORRECT - works in codex exec

正确——在codex exec中可用

codex exec --full-auto "task" codex exec -c approval_policy=on-request "task"

WRONG - -a only works in interactive mode

错误——-a仅在交互模式下可用

codex -a on-request "task"

---

codex -a on-request "task"

---

Trigger Examples

触发示例

This skill activates when users say phrases like:

"Use codex to analyze this architecture"
"Ask codex about this design decision"
"Run codex on this problem"
"Call codex for help with this implementation"
"I need GPT-5 reasoning for this task"
"Get OpenAI's high-reasoning model on this"
"Continue with codex" or "Resume the codex session"
"Codex, help me with..." or simply "Codex"

当用户说出以下类似短语时，本技能会激活：

"Use codex to analyze this architecture"
"Ask codex about this design decision"
"Run codex on this problem"
"Call codex for help with this implementation"
"I need GPT-5 reasoning for this task"
"Get OpenAI's high-reasoning model on this"
"Continue with codex" 或 "Resume the codex session"
"Codex, help me with..." 或直接说 "Codex"

When to Use This Skill

何时使用本技能

This skill should be invoked when:

User explicitly mentions "Codex" or requests Codex assistance
User needs help with complex coding tasks, algorithms, or architecture
User requests "high reasoning" or "advanced implementation" help
User needs complex problem-solving or architectural design
User wants to continue a previous Codex conversation

在以下场景中应调用本技能：

用户明确提及“Codex”或请求Codex协助
用户需要复杂编码任务、算法或架构方面的帮助
用户请求“高推理”或“高级实现”相关帮助
用户需要复杂问题解决或架构设计支持
用户希望继续之前的Codex对话

How It Works

工作原理

Detecting New Codex Requests

检测新的Codex请求

When a user makes a request, first determine the task type (code vs general), then determine sandbox based on explicit edit request:

Step 1: Determine Task Type (Model Selection)

Code-related tasks: Use
```
gpt-5.3-codex
```
- for implementation, refactoring, code analysis, debugging, etc.
General tasks: Use
```
gpt-5.2
```
- for architecture design, explanations, reviews, documentation, etc.

Step 2: Determine Sandbox (Edit Permission)

Default:
```
read-only
```
- safe for all tasks unless user explicitly requests editing
Explicit edit request:
```
workspace-write
```
- ONLY when user explicitly says to edit/modify/write files

Code-related task examples:

Read-only: "Analyze this function", "Review this implementation", "Debug this code"
With editing: "Edit this file to fix the bug", "Modify the function", "Refactor and save"

General task examples:

Read-only: "Design a queue data structure", "Explain this algorithm", "Review the architecture"
With editing: "Update the documentation file", "Modify the README"

⚠️ Important: The key distinction for sandbox is whether the user explicitly asks for file modifications. Use

workspace-write

ONLY when user says "edit", "modify", "write changes", "save", etc.

当用户提出请求时，首先确定任务类型（代码类 vs 通用类），然后根据是否有明确编辑请求确定沙箱模式：

步骤1：确定任务类型（模型选择）

代码相关任务：使用
```
gpt-5.3-codex
```
——适用于实现、重构、代码分析、调试等场景
通用任务：使用
```
gpt-5.2
```
——适用于架构设计、解释、评审、文档编写等场景

步骤2：确定沙箱模式（编辑权限）

默认设置：
```
read-only
```
——所有任务的安全默认选项，除非用户明确要求编辑
明确编辑请求：
```
workspace-write
```
——仅当用户明确表示要编辑/修改/写入文件时使用

代码相关任务示例：

只读模式：“Analyze this function”、“Review this implementation”、“Debug this code”
编辑模式：“Edit this file to fix the bug”、“Modify the function”、“Refactor and save”

通用任务示例：

只读模式：“Design a queue data structure”、“Explain this algorithm”、“Review the architecture”
编辑模式：“Update the documentation file”、“Modify the README”

⚠️ 注意：沙箱模式的核心判断标准是用户是否明确要求修改文件。仅当用户说出“edit”、“modify”、“write changes”、“save”等词汇时，才使用

workspace-write

。

Bash CLI Command Structure

Bash CLI命令结构

See the DEFAULT MODEL section above for complete command templates. Key points:

Always use
```
codex exec
```
(non-interactive mode required)
Add
```
--enable web_search_request
```
for research tasks
See
```
references/command-patterns.md
```
for additional patterns

完整命令模板请参考默认模型章节。核心要点：

始终使用
```
codex exec
```
（必须采用非交互模式）
研究类任务添加
```
--enable web_search_request
```
更多命令模式请查看
```
references/command-patterns.md
```

Model Selection Logic

模型选择逻辑

Step 1: Choose Model Based on Task Type

Use
gpt-5.3-codex
for code-related tasks:

Implementation, refactoring, code analysis
Debugging, fixing bugs, optimization
Any task involving code understanding or modification

Use
gpt-5.2
for general tasks:

Architecture and system design
Explanations, documentation, reviews
Planning, strategy, general reasoning

Step 2: Choose Sandbox Based on Edit Intent

Use
read-only
(DEFAULT):

Analysis, review, explanation tasks
ANY task where user does NOT explicitly request file editing

Use
workspace-write
(ONLY when explicitly requested):

User explicitly says "edit this file", "modify the code", "write changes"
User explicitly asks to "make edits" or "save the changes"
User explicitly requests "refactor and save" or "implement and write"

Fallback: If primary model unavailable, fallback to the other 5.2 variant. See fallback chain in DEFAULT MODEL section.

步骤1：根据任务类型选择模型

代码相关任务使用
gpt-5.3-codex
：

实现、重构、代码分析
调试、修复bug、性能优化
任何涉及代码理解或修改的任务

通用任务使用
gpt-5.2
：

架构与系统设计
解释、文档编写、评审
规划、策略制定、通用推理

步骤2：根据编辑意图选择沙箱模式

使用
read-only
（默认）：

分析、评审、解释类任务
用户未明确要求文件编辑的任何任务

使用
workspace-write
（仅在明确请求时）：

用户明确表示“edit this file”、“modify the code”、“write changes”
用户明确要求“make edits”或“save the changes”
用户明确请求“refactor and save”或“implement and write”

降级策略：如果主模型不可用，降级为另一款5.2系列模型。具体降级链请查看默认模型章节。

Default Configuration

默认配置

All Codex invocations use these defaults unless user specifies otherwise:

Parameter	Default Value	CLI Flag	Notes
Model (code tasks)	`gpt-5.3-codex`	`-m gpt-5.3-codex`	For code-related tasks
Model (general tasks)	`gpt-5.2`	`-m gpt-5.2`	For general tasks
Sandbox (default)	`read-only`	`-s read-only`	Safe default for ALL tasks
Sandbox (explicit edit)	`workspace-write`	`-s workspace-write`	Only when user explicitly requests editing
Reasoning Effort	`xhigh`	`-c model_reasoning_effort=xhigh`	Maximum reasoning capability
Verbosity	`medium`	`-c model_verbosity=medium`	Balanced output detail
Web Search	`enabled`	`--enable web_search_request`	Access to up-to-date information

除非用户另行指定，所有Codex调用均使用以下默认配置：

参数	默认值	CLI参数	说明
代码任务模型	`gpt-5.3-codex`	`-m gpt-5.3-codex`	适用于代码相关任务
通用任务模型	`gpt-5.2`	`-m gpt-5.2`	适用于通用任务
沙箱模式（默认）	`read-only`	`-s read-only`	所有任务的安全默认选项
沙箱模式（明确编辑）	`workspace-write`	`-s workspace-write`	仅当用户明确要求编辑时使用
推理能力	`xhigh`	`-c model_reasoning_effort=xhigh`	最大推理能力
输出详细程度	`medium`	`-c model_verbosity=medium`	平衡的输出细节
网页搜索	`enabled`	`--enable web_search_request`	可获取最新信息

CLI Flags Reference

CLI参数参考

Codex CLI Version: 0.98.0+

See:

references/cli-features.md

for the complete CLI flags table and feature documentation.

Key flags for this skill:

```
-m, --model
```
- Model selection (
```
gpt-5.3-codex
```
,
```
gpt-5.2
```
)
```
-s, --sandbox
```
- Sandbox mode (
```
read-only
```
,
```
workspace-write
```
)

-c, --config

- Config overrides (e.g.,

model_reasoning_effort=xhigh

)

```
--enable
```
/
```
--disable
```
- Feature toggles (e.g.,
```
web_search_request
```
)

Codex CLI版本：0.98.0+

查看：完整的CLI参数表和功能文档请参考

references/cli-features.md

。

本技能核心参数：

```
-m, --model
```
- 模型选择（
```
gpt-5.3-codex
```
、
```
gpt-5.2
```
）
```
-s, --sandbox
```
- 沙箱模式（
```
read-only
```
、
```
workspace-write
```
）

-c, --config

- 配置覆盖（例如

model_reasoning_effort=xhigh

）

```
--enable
```
/
```
--disable
```
- 功能开关（例如
```
web_search_request
```
）

Configuration Parameters

配置参数

Pass these as

-c key=value

```
model_reasoning_effort
```
:
```
minimal
```
,
```
low
```
,
```
medium
```
,
```
high
```
,
```
xhigh
```
- CLI default:
```
high
```
  - The Codex CLI defaults to high reasoning
- Skill default:
```
xhigh
```
  - This skill explicitly uses xhigh for maximum capability
- xhigh
  : Extra-high reasoning for maximum capability (supported by gpt-5.2 models)
- Use
```
xhigh
```
  for complex architectural refactoring, long-horizon tasks, or when quality is more important than speed
```
model_verbosity
```
:
```
low
```
,
```
medium
```
,
```
high
```
(default:
```
medium
```
)

model_reasoning_summary

auto

concise

detailed

none

(default:

auto

)

sandbox_workspace_write.writable_roots

: JSON array of additional writable directories (e.g.,

["/path1","/path2"]

)

approval_policy

untrusted

on-failure

on-request

never

(approval behavior)

Additional Writable Directories:

Use

--add-dir

flag (preferred) or config:

bash

undefined

通过

-c key=value

传递以下参数：

```
model_reasoning_effort
```
：
```
minimal
```
、
```
low
```
、
```
medium
```
、
```
high
```
、
```
xhigh
```
- CLI默认值：
```
high
```
  - Codex CLI默认使用高推理能力
- 技能默认值：
```
xhigh
```
  - 本技能明确使用xhigh以获取最大能力
- xhigh
  ：超高推理能力，适用于复杂场景（gpt-5.2系列模型支持）
- 复杂架构重构、长周期任务或质量优先于速度时使用
```
xhigh
```
```
model_verbosity
```
：
```
low
```
、
```
medium
```
、
```
high
```
（默认：
```
medium
```
）

model_reasoning_summary

：

auto

、

concise

、

detailed

、

none

（默认：

auto

）

sandbox_workspace_write.writable_roots

：额外可写目录的JSON数组（例如

["/path1","/path2"]

）

approval_policy

：

untrusted

、

on-failure

、

on-request

、

never

（审批行为）

额外可写目录：

优先使用

--add-dir

参数，或通过配置传递：

bash

undefined

Using --add-dir for multiple directories

使用--add-dir添加多个目录

codex exec --add-dir /path1 --add-dir /path2 "task"

Alternative - config approach

替代方案——通过配置传递

codex exec -c 'sandbox_workspace_write.writable_roots=["/path1","/path2"]' "task"

undefined

codex exec -c 'sandbox_workspace_write.writable_roots=["/path1","/path2"]' "task"

undefined

Model Selection Guide

模型选择指南

Available Models:

```
gpt-5.3-codex
```
- Code tasks (implementation, refactoring, debugging)
```
gpt-5.2
```
- General tasks (architecture, reviews, explanations)

Default:

gpt-5.3-codex

for code tasks,

gpt-5.2

for general tasks with

xhigh

reasoning effort.

可用模型：

```
gpt-5.3-codex
```
- 代码任务（实现、重构、调试）
```
gpt-5.2
```
- 通用任务（架构、评审、解释）

默认设置：代码任务使用

gpt-5.3-codex

，通用任务使用

gpt-5.2

，均采用

xhigh

推理能力。

Session Continuation

会话续接

Detecting Continuation Requests

检测续接请求

When user indicates they want to continue a previous Codex conversation:

Keywords: "continue", "resume", "keep going", "add to that"
Follow-up context referencing previous Codex work
Explicit request like "continue where we left off"

当用户表示希望继续之前的Codex对话时：

关键词：“continue”、“resume”、“keep going”、“add to that”
后续问题引用了之前的Codex工作内容
明确请求如“continue where we left off”

Resuming Sessions

恢复会话

For continuation requests, use the

codex resume

command:

对于续接请求，使用

codex resume

命令：

Resume Most Recent Session (Recommended)

恢复最近的会话（推荐）

bash

codex exec resume --last

This automatically continues the most recent Codex session with all previous context maintained.

bash

codex exec resume --last

该命令会自动继续最近的Codex会话，并保留所有历史上下文。

Resume Specific Session

恢复特定会话

bash

codex exec resume <session-id>

Resume a specific session by providing its UUID. Get session IDs from previous Codex output or by running

codex exec resume --last

to see the most recent session.

Note: The interactive session picker (

codex resume

without arguments) is NOT available in non-interactive/Claude Code environments. Always use

--last

or provide explicit session ID.

bash

codex exec resume <session-id>

通过提供UUID恢复特定会话。可从之前的Codex输出中获取会话ID，或运行

codex exec resume --last

查看最近的会话。

注意：交互式会话选择器（不带参数的

codex resume

）在非交互式/Claude Code环境中不可用。请始终使用

--last

或提供明确的会话ID。

Forking Sessions (Interactive Only)

会话分支（仅交互模式）

The

codex fork

command creates a new session from a previous one, allowing exploration of different directions without affecting the original session.

bash

undefined

codex fork

命令可从已有会话创建新会话，允许探索不同方向而不影响原会话。

bash

undefined

Fork the most recent session (interactive terminal only)

分支最近的会话（仅交互式终端可用）

codex fork --last

Fork a specific session by ID (interactive terminal only)

通过ID分支特定会话（仅交互式终端可用）

codex fork <session-id>


**⚠️ Important**: `codex fork` is an **interactive-only** command. It is NOT available under `codex exec` and will fail with "stdin is not a terminal" in Claude Code's non-interactive environment.

**Workaround for Claude Code**: To achieve similar functionality, use `codex exec resume --last` with a prompt that indicates you want to explore an alternative approach. The session history will be preserved.

**Note**: Unlike `resume` which continues the same session, `fork` creates a new independent session with the same history as a starting point.

codex fork <session-id>


**⚠️ 注意**：`codex fork`是**仅交互模式**命令。在`codex exec`下不可用，且在Claude Code的非交互式环境中会因“stdin is not a terminal”错误失败。

**Claude Code替代方案**：要实现类似功能，使用`codex exec resume --last`并在提示中说明要探索替代方案。会话历史将被保留。

**说明**：与`resume`继续同一会话不同，`fork`会创建一个新的独立会话，并以原会话历史为起点。

Decision Logic: New vs. Continue

决策逻辑：新建会话 vs 续接会话

Use
codex exec -m ... "<prompt>"
when:

User makes a new, independent request
No reference to previous Codex work
User explicitly wants a "fresh" or "new" session

Use
codex exec resume --last
when:

User indicates continuation ("continue", "resume", "add to that")
Follow-up question building on previous Codex conversation
Iterative development on same task
User wants to explore alternatives (provide new direction in prompt)

当以下情况使用
codex exec -m ... "<prompt>"
：

用户提出新的、独立的请求
未引用之前的Codex工作内容
用户明确要求“全新”或“新的”会话

当以下情况使用
codex exec resume --last
：

用户表示要续接（“continue”、“resume”、“add to that”）
后续问题基于之前的Codex对话
同一任务的迭代开发
用户希望探索替代方案（在提示中说明新方向）

Session History Management

会话历史管理

Codex CLI automatically saves session history
No manual session ID tracking needed
Sessions persist across Claude Code restarts
Use
```
codex exec resume --last
```
to access most recent session
Use
```
codex exec resume <session-id>
```
for specific sessions

Codex CLI会自动保存会话历史
无需手动跟踪会话ID
会话在Claude Code重启后仍会保留
使用
```
codex exec resume --last
```
访问最近的会话
使用
```
codex exec resume <session-id>
```
恢复特定会话

Error Handling

错误处理

Simple Error Response Strategy

简单错误响应策略

When errors occur, return clear, actionable messages without complex diagnostics:

Error Message Format:

Error: [Clear description of what went wrong]

To fix: [Concrete remediation action]

[Optional: Specific command example]

发生错误时，返回清晰、可操作的消息，无需复杂诊断：

错误消息格式：

Error: [清晰描述问题]

修复方案：[具体解决步骤]

[可选：特定命令示例]

Common Errors

常见错误

Command Not Found

命令未找到

Error: Codex CLI not found

To fix: Install Codex CLI and ensure it's available in your PATH

Check installation: codex --version

Error: Codex CLI not found

修复方案：安装Codex CLI并确保其在PATH中可用

检查安装：codex --version

Authentication Required

需要认证

Error: Not authenticated with Codex

To fix: Run 'codex login' to authenticate

After authentication, try your request again.

Error: Not authenticated with Codex

修复方案：运行'codex login'进行认证

认证完成后，请重新尝试您的请求。

Invalid Configuration

无效配置

Error: Invalid model specified

To fix:
- For coding tasks: Use 'gpt-5.3-codex' with workspace-write sandbox
- For reasoning tasks: Use 'gpt-5.2' with read-only sandbox

Example (coding): codex exec -m gpt-5.3-codex -s workspace-write -c model_reasoning_effort=xhigh "implement feature"
Example (reasoning): codex exec -m gpt-5.2 -s read-only -c model_reasoning_effort=xhigh "explain architecture"

Error: Invalid model specified

修复方案：
- 代码任务：使用'gpt-5.3-codex'并搭配workspace-write沙箱
- 推理任务：使用'gpt-5.2'并搭配read-only沙箱

示例（代码任务）：codex exec -m gpt-5.3-codex -s workspace-write -c model_reasoning_effort=xhigh "implement feature"
示例（推理任务）：codex exec -m gpt-5.2 -s read-only -c model_reasoning_effort=xhigh "explain architecture"

Troubleshooting

故障排除

First Steps for Any Issues:

Check Codex CLI built-in help:

codex --help

codex exec --help

codex exec resume --help

Consult official documentation: https://github.com/openai/codex/tree/main/docs
Verify skill resources in
```
references/
```
directory

Note: Commands like

codex --help

codex --version

codex login

, and

codex logout

work without the

exec

subcommand. The

exec

requirement only applies to task execution.

Skill not being invoked?

Check that request matches trigger keywords (Codex, complex coding, high reasoning, etc.)
Explicitly mention "Codex" in your request
Try: "Use Codex to help me with..."

Session not resuming?

Verify you have a previous Codex session (check command output for session IDs)
Try:
```
codex exec resume --last
```
to resume most recent session
If no history exists, start a new session first

"stdout is not a terminal" error?

Always use
```
codex exec
```
instead of plain
```
codex
```
in Claude Code
Claude Code's bash environment is non-interactive/non-terminal

Errors during execution?

Codex CLI errors are passed through directly
Check Codex CLI logs for detailed diagnostics
Verify working directory permissions if using workspace-write
Check official Codex docs for latest updates and known issues

任何问题的第一步：

查看Codex CLI内置帮助：

codex --help

、

codex exec --help

、

codex exec resume --help

查阅官方文档：https://github.com/openai/codex/tree/main/docs
查看
```
references/
```
目录下的技能资源

注意：

codex --help

、

codex --version

、

codex login

和

codex logout

等命令无需

exec

子命令即可使用。仅任务执行需要使用

exec

。

技能未被触发？

检查请求是否匹配触发关键词（Codex、复杂编码、高推理等）
在请求中明确提及“Codex”
尝试：“Use Codex to help me with...”

会话无法恢复？

确认您有之前的Codex会话（查看命令输出中的会话ID）
尝试：
```
codex exec resume --last
```
恢复最近的会话
如果没有历史会话，请先启动新会话

“stdout is not a terminal”错误？

在Claude Code中始终使用
```
codex exec
```
而非直接使用
```
codex
```
Claude Code的bash环境为非交互式/非终端环境

执行过程中出错？

Codex CLI错误会直接传递
查看Codex CLI日志获取详细诊断信息
如果使用workspace-write模式，检查工作目录权限
查看官方Codex文档获取最新更新和已知问题

Examples

示例

Code Analysis (Read-Only)

代码分析（只读模式）

bash

codex exec -m gpt-5.3-codex -s read-only \
  -c model_reasoning_effort=xhigh \
  "Analyze this function implementation"

bash

codex exec -m gpt-5.3-codex -s read-only \
  -c model_reasoning_effort=xhigh \
  "Analyze this function implementation"

Code Editing (Explicit Request)

代码编辑（明确请求）

bash

codex exec -m gpt-5.3-codex -s workspace-write \
  -c model_reasoning_effort=xhigh \
  "Edit this file to implement the feature"

bash

codex exec -m gpt-5.3-codex -s workspace-write \
  -c model_reasoning_effort=xhigh \
  "Edit this file to implement the feature"

Session Continuation

会话续接

bash

codex exec resume --last

See:

references/examples.md

for more examples including web search, file context, and code review patterns.

bash

codex exec resume --last

查看：更多示例（包括网页搜索、文件上下文和代码评审模式）请参考

references/examples.md

。

Code Review Subcommand (v0.71.0+)

代码评审子命令（v0.71.0+）

The

codex review

subcommand provides non-interactive code review capabilities:

bash

undefined

codex review

子命令提供非交互式代码评审功能：

bash

undefined

Review uncommitted changes (staged, unstaged, untracked)

评审未提交的更改（已暂存、未暂存、未跟踪文件）

codex review --uncommitted

Review changes against a base branch

评审与基准分支的差异

codex review --base main

Review a specific commit

评审特定提交

codex review --commit abc123

Review with custom instructions

带自定义指令的评审

codex review --uncommitted "Focus on security vulnerabilities"

Non-interactive via exec

通过exec以非交互模式运行

codex exec review --uncommitted


**Review Options**:
| Flag | Description |
|------|-------------|
| `--uncommitted` | Review staged, unstaged, and untracked changes |
| `--base <BRANCH>` | Review changes against the given base branch |
| `--commit <SHA>` | Review the changes introduced by a commit |
| `--title <TITLE>` | Optional commit title for review summary |

---

codex exec review --uncommitted


**评审选项**：
| 参数 | 描述 |
|------|-------------|
| `--uncommitted` | 评审已暂存、未暂存和未跟踪的更改 |
| `--base <BRANCH>` | 评审与指定基准分支的差异 |
| `--commit <SHA>` | 评审指定提交引入的更改 |
| `--title <TITLE>` | 评审摘要的可选提交标题 |

---

Apply Command (v0.98.0+)

应用命令（v0.98.0+）

The

codex apply

command applies the latest diff produced by the Codex agent as a

git apply

to your local working tree:

bash

undefined

codex apply

命令将Codex代理生成的最新diff作为

git apply

应用到本地工作区：

bash

undefined

Apply the latest diff from Codex

应用Codex生成的最新diff

codex apply


This is useful when Codex generates code changes in read-only mode and you want to apply those changes to your local files.

---

codex apply


当Codex在只读模式下生成代码更改，而您希望将这些更改应用到本地文件时，此命令非常有用。

---

CLI Features Reference

CLI功能参考

For detailed CLI feature documentation, see

references/cli-features.md

Quick Reference - Common features:

```
--enable web_search_request
```
- Enable web search
```
-i, --image
```
- Attach images to prompts
```
--add-dir
```
- Add writable directories
```
--full-auto
```
- Low-friction workspace-write mode
```
--json
```
- JSONL output for programmatic processing

详细的CLI功能文档请查看

references/cli-features.md

。

快速参考 - 常用功能：

```
--enable web_search_request
```
- 启用网页搜索
```
-i, --image
```
- 向提示中附加图片
```
--add-dir
```
- 添加可写目录
```
--full-auto
```
- 低摩擦的workspace-write模式
```
--json
```
- 用于程序化处理的JSONL输出

File Context Passing

文件上下文传递

IMPORTANT: Pass file paths to Codex CLI instead of embedding file content in prompts. This enables Codex to read files autonomously.

Quick reference:

Use
```
-C /path
```
to set working directory
Use
```
--add-dir /path
```
for additional directories
Use
```
@path/to/file
```
syntax for explicit file references

bash

undefined

重要提示：向Codex CLI传递文件路径，而非在提示中嵌入文件内容。这样可以让Codex自主读取文件。

快速参考：

使用
```
-C /path
```
设置工作目录
使用
```
--add-dir /path
```
添加额外目录
使用
```
@path/to/file
```
语法明确引用文件

bash

undefined

Example: analyze file with explicit @ syntax

示例：使用@语法分析文件

codex exec -m gpt-5.3-codex -s read-only
"Analyze @src/auth.ts and compare with @src/session.ts"

Example: multi-directory analysis

示例：多目录分析

codex exec -m gpt-5.3-codex -s read-only
--add-dir /shared/libs
"Review how auth module uses shared utilities"


**See**: `references/file-context.md` for complete file context documentation.

---

codex exec -m gpt-5.3-codex -s read-only
--add-dir /shared/libs
"Review how auth module uses shared utilities"


**查看**：完整的文件上下文文档请参考`references/file-context.md`。

---

Best Practices

最佳实践

1. Use Descriptive Requests

1. 使用描述性请求

Good: "Help me implement a thread-safe queue with priority support in Python" Vague: "Code help"

Clear, specific requests get better results from high-reasoning models.

良好示例："Help me implement a thread-safe queue with priority support in Python" 模糊示例："Code help"

清晰、具体的请求能从高推理模型获得更好的结果。

2. Indicate Continuation Clearly

2. 明确表示续接意图

Good: "Continue with that queue implementation - add unit tests" Unclear: "Add tests" (might start new session)

Explicit continuation keywords help the skill choose the right command.

良好示例："Continue with that queue implementation - add unit tests" 不清晰示例："Add tests"（可能会启动新会话）

明确的续接关键词有助于技能选择正确的命令。

3. Specify Permissions When Needed

3. 需要时明确指定权限

Good: "Refactor this code (allow file writing)" Risky: Assuming permissions without specifying

Make your intent clear when you need workspace-write permissions.

良好示例："Refactor this code (allow file writing)" 风险示例：未明确说明就假设权限

当需要workspace-write权限时，请清晰表达您的意图。

4. Leverage High Reasoning

4. 充分利用高推理能力

The skill defaults to high reasoning effort - perfect for:

Complex algorithms
Architecture design
Performance optimization
Security reviews

本技能默认使用高推理能力——非常适合：

复杂算法
架构设计
性能优化
安全评审

Reference Documentation

参考文档

For detailed information, consult these reference files:

如需详细信息，请查阅以下参考文件：

Core References

核心参考

references/file-context.md
- File and directory context passing guide
references/examples.md
- Complete command examples by use case
references/cli-features.md
- Feature flags and CLI options

references/file-context.md
- 文件与目录上下文传递指南
references/examples.md
- 按使用场景分类的完整命令示例
references/cli-features.md
- 功能参数与CLI选项

Workflow References

工作流参考

references/command-patterns.md
- Common codex exec usage patterns
references/session-workflows.md
- Session continuation and resume workflows
references/advanced-patterns.md
- Complex configuration and flag combinations

references/command-patterns.md
- 常用codex exec使用模式
references/session-workflows.md
- 会话续接与恢复工作流
references/advanced-patterns.md
- 复杂配置与参数组合

CLI References

CLI参考

references/codex-help.md
- Codex CLI command reference
references/codex-config.md
- Full configuration options

references/codex-help.md
- Codex CLI命令参考
references/codex-config.md
- 完整配置选项

codex

Original

Translation

Codex: High-Reasoning AI Assistant for Claude Code

Codex：面向Claude Code的高推理AI助手

DEFAULT MODEL: Task-Based Model Selection with Read-Only Default

默认模型：基于任务的模型选择，默认只读模式

Code task (read-only default)

Code task (read-only default)

General task (read-only default)

General task (read-only default)

Code task with explicit edit request

Code task with explicit edit request

General task with explicit edit request

General task with explicit edit request

Model Fallback Chain

模型降级链

CRITICAL: Always Use codex exec

重要提示：始终使用codex exec

IMPORTANT: Interactive vs Exec Mode Flags

注意：交互模式与Exec模式的参数差异

CORRECT - works in codex exec

正确——在codex exec中可用

WRONG - --search only works in interactive mode

错误——--search仅在交互模式下可用

CORRECT - works in codex exec

正确——在codex exec中可用

WRONG - -a only works in interactive mode

错误——-a仅在交互模式下可用

Trigger Examples

触发示例

When to Use This Skill

何时使用本技能

How It Works

工作原理

Detecting New Codex Requests

检测新的Codex请求

Bash CLI Command Structure

Bash CLI命令结构

Model Selection Logic

模型选择逻辑

Default Configuration

默认配置

CLI Flags Reference

CLI参数参考

Configuration Parameters

配置参数

Using --add-dir for multiple directories

使用--add-dir添加多个目录

Alternative - config approach

替代方案——通过配置传递

Model Selection Guide

模型选择指南

Session Continuation

会话续接

Detecting Continuation Requests

检测续接请求

Resuming Sessions

恢复会话

Resume Most Recent Session (Recommended)

恢复最近的会话（推荐）

Resume Specific Session

恢复特定会话

Forking Sessions (Interactive Only)

会话分支（仅交互模式）

Fork the most recent session (interactive terminal only)

分支最近的会话（仅交互式终端可用）

Fork a specific session by ID (interactive terminal only)

通过ID分支特定会话（仅交互式终端可用）

Decision Logic: New vs. Continue

决策逻辑：新建会话 vs 续接会话

Session History Management

会话历史管理

Error Handling

错误处理

Simple Error Response Strategy

简单错误响应策略

Common Errors

常见错误

Command Not Found

CRITICAL: Always Use
`codex exec`

重要提示：始终使用
`codex exec`