oracle-codex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Oracle

File paths: All
scripts/
and
references/
paths in this skill resolve under
~/.agents/skills/oracle-codex/
. Do not look for them in the current working directory.

Use OpenAI Codex CLI as a planning oracle and code reviewer. Codex provides analysis and recommendations; Claude synthesizes and presents to the user.

Critical: This skill is for planning and review ONLY. Never use Codex to implement changes.

文件路径：所有此技能中的
scripts/
和
references/
路径均在
~/.agents/skills/oracle-codex/
下解析。请勿在当前工作目录中查找它们。

将OpenAI Codex CLI用作规划神谕和代码审查工具。Codex提供分析和建议；Claude负责整合并呈现给用户。

重要提示：此技能仅用于规划和审查。绝不要使用Codex来实现代码变更。

Agent Compatibility

代理兼容性

Claude Code only. This skill depends on Claude Code features (

ExitPlanMode

AskUserQuestion

, plan mode). If you are not Claude Code — e.g., you are Codex CLI, GPT, or another agent — stop immediately and inform the user that this skill requires Claude Code.

仅支持Claude Code。此技能依赖Claude Code的功能（

ExitPlanMode

、

AskUserQuestion

、规划模式）。如果您不是Claude Code——例如您是Codex CLI、GPT或其他代理——请立即停止，并告知用户此技能需要Claude Code。

Prerequisites

前置条件

Before invoking Codex, validate availability:

bash

~/.agents/skills/oracle-codex/scripts/check-codex.sh

If the script exits non-zero, display the error message and stop. Do not proceed without Codex CLI.

For

codex exec

, prefer the wrapper script (handles flag compatibility and surfaces errors):

bash

~/.agents/skills/oracle-codex/scripts/run-codex-exec.sh

在调用Codex之前，验证其可用性：

bash

~/.agents/skills/oracle-codex/scripts/check-codex.sh

如果脚本返回非零值，显示错误信息并停止。没有Codex CLI请勿继续操作。

对于

codex exec

，优先使用包装脚本（处理标志兼容性并显示错误）：

bash

~/.agents/skills/oracle-codex/scripts/run-codex-exec.sh

Configuration Defaults

配置默认值

Setting	Default	User Override
Model	`gpt-5.3-codex`	Only models from the allowlist below
Reasoning	Dynamic (based on complexity)	"use medium reasoning" or "with xhigh effort"
Sandbox	`read-only`	Not overridable (safety constraint)
Timeout	5 minutes minimum	Estimate based on task complexity

设置项	默认值	用户覆盖方式
模型	`gpt-5.3-codex`	仅可使用以下允许列表中的模型
推理级别	动态（基于复杂度）	可指定“use medium reasoning”或“with xhigh effort”
沙箱模式	`read-only`	不可覆盖（安全约束）
超时时间	最少5分钟	根据任务复杂度估算

Model Allowlist

模型允许列表

Only the following models may be passed to

-m

. Reject any model not in this list — do not infer or substitute models from the user's prompt (e.g., "o3", "gpt-4o").

Model	Description
`gpt-5.3-codex`	Latest frontier agentic coding model

仅可将以下模型传递给

-m

参数。拒绝任何不在此列表中的模型——不要从用户的提示中推断或替换模型（例如“o3”、“gpt-4o”）。

模型	描述
`gpt-5.3-codex`	最新的前沿代理式编码模型

Timeout Guidelines

超时时间指南

When invoking

codex exec

via the Bash tool, always set an appropriate timeout:

Minimum: 5 minutes (300000ms) for any Codex operation
Simple queries (single file review, focused question): 5 minutes (300000ms)
Moderate complexity (multi-file review, feature planning): 10 minutes (600000ms)
High complexity (
```
high
```
reasoning): 15 minutes minimum (900000ms)
Maximum complexity (
```
xhigh
```
reasoning): 20 minutes (1200000ms)

通过Bash工具调用

codex exec

时，始终设置适当的超时时间：

最小值：任何Codex操作最少5分钟（300000毫秒）
简单查询（单文件审查、聚焦问题）：5分钟（300000毫秒）
中等复杂度（多文件审查、功能规划）：10分钟（600000毫秒）
高复杂度（
```
high
```
推理级别）：最少15分钟（900000毫秒）
最高复杂度（
```
xhigh
```
推理级别）：20分钟（1200000毫秒）

Reasoning Effort Guidelines

推理力度指南

Select reasoning effort based on task complexity:

Complexity	Effort	Examples
Simple	`low`	Single file review, syntax check, quick question
Moderate	`medium`	Multi-file review, focused feature planning, bug analysis
Complex	`high`	Architecture analysis, cross-cutting concerns, security audit
Maximum	`xhigh`	Large codebase planning, comprehensive design, deep reasoning

Selection heuristics:

low
: Task involves <3 files, simple question, or quick validation
medium
: Task involves 3-10 files or requires moderate analysis
high
: Task spans multiple modules or requires architectural thinking
xhigh
: Task requires comprehensive codebase understanding or critical decisions

For available models and reasoning levels, consult

~/.agents/skills/oracle-codex/references/codex-flags.md

根据任务复杂度选择推理力度：

复杂度	力度	示例
简单	`low`	单文件审查、语法检查、快速问题解答
中等	`medium`	多文件审查、聚焦式功能规划、Bug分析
复杂	`high`	架构分析、跨模块关注点、安全审计
最高	`xhigh`	大型代码库规划、全面设计、深度推理

选择规则：

low
：任务涉及少于3个文件、问题简单或仅需快速验证
medium
：任务涉及3-10个文件或需要中等深度分析
high
：任务跨越多个模块或需要架构层面思考
xhigh
：任务需要全面理解代码库或涉及关键决策

有关可用模型和推理级别的详细信息，请查阅

~/.agents/skills/oracle-codex/references/codex-flags.md

。

Workflow

工作流程

1. Validate Prerequisites

1. 验证前置条件

Run the check script. On failure, report the installation instructions and abort.

运行检查脚本。如果失败，报告安装说明并终止操作。

2. Determine Mode

2. 确定模式

Planning mode: User wants architecture, implementation approach, or design decisions
Review mode: User wants code analysis, bug detection, or improvement suggestions

Plan mode detection: If Claude Code is running in plan mode (a plan file path was provided in the system prompt), the review target changes:

Normal mode → review uncommitted changes (
```
git diff
```
+
```
git diff --staged
```
)
Plan mode → read the plan file and review its contents instead of uncommitted changes

规划模式：用户需要架构设计、实现方案或设计决策建议
审查模式：用户需要代码分析、Bug检测或改进建议

规划模式检测：如果Claude Code正以规划模式运行（系统提示中提供了计划文件路径），则审查目标会发生变化：

普通模式 → 审查未提交的变更（
```
git diff
```
+
```
git diff --staged
```
）
规划模式 → 读取计划文件并审查其内容，而非未提交的变更

3. Construct Prompt

3. 构建提示词

Build a focused prompt for Codex based on mode:

Planning prompt template:

Analyze this codebase and provide a detailed implementation plan for: [user request]

Focus on:
- Architecture decisions and trade-offs
- Files to create or modify
- Implementation sequence
- Potential risks or blockers

Do not implement anything. Provide analysis and recommendations only.

Review prompt template (normal mode — uncommitted changes):

Review the following code changes for:
- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Code quality and maintainability
- Adherence to best practices

[git diff output]

Provide specific, actionable feedback with file locations and line references.

Review prompt template (plan mode — plan file):

Review the following implementation plan for:
- Completeness and feasibility
- Architectural soundness
- Missing edge cases or risks
- Ordering and dependency issues
- Alignment with stated goals

[plan file contents]

Provide specific, actionable feedback on the plan. Identify gaps, risks, and improvements.

根据模式为Codex构建聚焦的提示词：

规划提示词模板：

分析此代码库，并为以下需求提供详细的实现计划：[用户请求]

重点关注：
- 架构决策与权衡
- 需要创建或修改的文件
- 实现顺序
- 潜在风险或障碍

请勿实现任何内容。仅提供分析和建议。

审查提示词模板（普通模式——未提交变更）：

审查以下代码变更，重点关注：
- Bug与逻辑错误
- 安全漏洞
- 性能问题
- 代码质量与可维护性
- 最佳实践的遵循情况

[git diff输出]

提供包含文件位置和行号引用的具体、可操作的反馈。

审查提示词模板（规划模式——计划文件）：

审查以下实现计划，重点关注：
- 完整性与可行性
- 架构合理性
- 遗漏的边缘情况或风险
- 顺序与依赖问题
- 与既定目标的一致性

[计划文件内容]

提供针对该计划的具体、可操作的反馈。指出差距、风险和改进方向。

4. Assess Complexity and Execute Codex

4. 评估复杂度并执行Codex

Before executing, assess task complexity to select appropriate reasoning effort:

Count files involved in the query
Evaluate scope (single module vs cross-cutting)
Consider depth (surface review vs architectural analysis)

Use HEREDOC syntax for safe prompt handling. Always use the Bash tool's timeout parameter (minimum 300000ms / 5 minutes).

Redirect output to a temp file to avoid context bloat and race conditions.

Step 1: Generate a unique temp file path using

$RANDOM

for randomness:

bash

CODEX_OUTPUT="/tmp/codex-${RANDOM}${RANDOM}.txt"

Step 2: Execute Codex via the wrapper (detects supported flags and surfaces stderr):

bash

undefined

执行前，评估任务复杂度以选择合适的推理力度：

统计查询涉及的文件数量
评估范围（单模块 vs 跨模块）
考虑深度（表面审查 vs 架构分析）

使用HEREDOC语法安全处理提示词。务必使用Bash工具的超时参数（最少300000毫秒/5分钟）。

将输出重定向到临时文件，以避免上下文膨胀和竞争条件。

步骤1：使用

$RANDOM

生成唯一的临时文件路径：

bash

CODEX_OUTPUT="/tmp/codex-${RANDOM}${RANDOM}.txt"

步骤2：通过包装脚本执行Codex（检测支持的标志并显示stderr）：

bash

undefined

Select EFFORT based on complexity assessment (low/medium/high/xhigh)

根据复杂度评估选择EFFORT（low/medium/high/xhigh）

Bash tool timeout: 5-20 minutes based on complexity

Bash工具超时时间：根据复杂度设置5-20分钟

MODEL="${MODEL:-gpt-5.3-codex}"
EFFORT="${EFFORT}"
CODEX_OUTPUT="$CODEX_OUTPUT"
~/.agents/skills/oracle-codex/scripts/run-codex-exec.sh <<'EOF' [constructed prompt] EOF


**Important flags:**

- `-m`: Model selection
- `-c model_reasoning_effort=`: Reasoning depth (low/medium/high/xhigh) — select based on Reasoning Effort Guidelines
- `-s read-only`: Prevents any file modifications (non-negotiable)
- `--skip-git-repo-check`: Works outside git repositories (exec-specific)
- `-o <file>`: Write output to file (cleaner than shell redirection)
- `--search`: Enable web search for queries needing current information (optional)
- `2>/dev/null`: Suppresses stderr (progress/thinking output)

**Bash tool timeout**: Estimate based on task complexity (see Timeout Guidelines above). Never use the default 2-minute timeout for Codex operations.

MODEL="${MODEL:-gpt-5.3-codex}"
EFFORT="${EFFORT}"
CODEX_OUTPUT="$CODEX_OUTPUT"
~/.agents/skills/oracle-codex/scripts/run-codex-exec.sh <<'EOF' [构建好的提示词] EOF


**重要标志：**

- `-m`：模型选择
- `-c model_reasoning_effort=`: 推理深度（low/medium/high/xhigh）——根据推理力度指南选择
- `-s read-only`: 防止任何文件修改（不可协商）
- `--skip-git-repo-check`: 在git仓库外也可工作（exec特定参数）
- `-o <file>`: 将输出写入文件（比shell重定向更清晰）
- `--search`: 为需要当前信息的查询启用网络搜索（可选）
- `2>/dev/null`: 抑制stderr（进度/思考输出）

**Bash工具超时时间**：根据任务复杂度估算（见上述超时时间指南）。绝不要为Codex操作使用默认的2分钟超时。

5. Present Codex Output

5. 呈现Codex输出

Step 3: Read the analysis from the temp file and display to the user:

bash

cat "$CODEX_OUTPUT"

Format the output with clear attribution:

undefined

步骤3：从临时文件读取分析结果并呈现给用户：

bash

cat "$CODEX_OUTPUT"

使用清晰的归属格式呈现输出：

undefined

Codex Analysis

Codex分析结果

[Codex output from the temp file]

Model: gpt-5.3-codex | Reasoning: [selected effort level]


For very large outputs (>5000 lines), summarize key sections rather than displaying everything.

[临时文件中的Codex输出]

模型: gpt-5.3-codex | 推理级别: [所选力度级别]


对于非常大的输出（超过5000行），请总结关键部分而非全部显示。

6. Synthesize and Plan

6. 整合与规划

After presenting Codex output:

Synthesize key insights from Codex analysis
Identify actionable items and critical decisions
If Codex's analysis presents multiple viable approaches or significant trade-offs, consider using
```
AskUserQuestion
```
to clarify user preferences before finalizing the plan
Write a structured plan
Call
```
ExitPlanMode
```
to present the plan for user approval

When to use AskUserQuestion:

Codex proposes multiple architectures with different trade-offs
Technology or library choices need user input
Scope decisions (minimal vs comprehensive) are ambiguous

Skip clarification when:

Codex's recommendations are clear and unambiguous
User's original request already specified preferences
Only one viable approach exists

呈现Codex输出后：

整合Codex分析中的关键见解
识别可操作项和关键决策
如果Codex的分析提出了多种可行方案或重大权衡，在最终确定计划前，考虑使用
```
AskUserQuestion
```
来明确用户偏好
编写结构化计划
调用
```
ExitPlanMode
```
以将计划呈现给用户审批

何时使用AskUserQuestion：

Codex提出了多种具有不同权衡的架构方案
技术或库的选择需要用户输入
范围决策（最小化 vs 全面性）不明确

何时跳过澄清：

Codex的建议清晰明确
用户的原始请求已指定偏好
仅存在一种可行方案

Error Handling

错误处理

The check script returns specific exit codes:

Exit Code	Error	Response
1	Codex not installed	Show installation instructions from check script
2	Codex not responding	Suggest running `codex --version` manually
3	Codex not authenticated	Show login instructions from check script

The

codex exec

command returns:

Exit Code	Meaning	Response
0	Exec completed	Present results
1	Prompt/config error or runtime failure	Show stderr and adjust prompt/config
2	CLI usage error (usually unsupported flag / bad arguments)	Use the wrapper script or re-check `codex exec --help` options

Runtime errors:

Error	Response
Codex timeout	Inform user, suggest simpler query or lower reasoning
API rate limit	Wait and retry, or inform user of limit
Empty response	Retry once, then report failure

检查脚本返回特定的退出码：

退出码	错误类型	响应方式
1	Codex未安装	显示检查脚本中的安装说明
2	Codex无响应	建议手动运行 `codex --version`
3	Codex未认证	显示检查脚本中的登录说明

codex exec

命令返回的退出码：

退出码	含义	响应方式
0	执行完成	呈现结果
1	提示词/配置错误或运行时失败	显示stderr并调整提示词/配置
2	CLI使用错误（通常是不支持的标志/无效参数）	使用包装脚本或重新检查 `codex exec --help` 选项

运行时错误：

错误类型	响应方式
Codex超时	告知用户，建议使用更简单的查询或降低推理级别
API速率限制	等待并重试，或告知用户限制情况
空响应	重试一次，然后报告失败

Usage Examples

使用示例

Planning Request

规划请求

User: "Ask Codex to plan how to add authentication to this app"

Validate Codex CLI available
Gather relevant codebase context
Assess complexity → auth spans multiple modules →
```
high
```
reasoning
Construct planning prompt with auth requirements
Execute Codex with
```
gpt-5.3-codex
```
and
```
high
```
Present Codex's architecture recommendations
Synthesize into Claude plan format

用户：“让Codex规划如何为这个应用添加认证功能”

验证Codex CLI可用
收集相关代码库上下文
评估复杂度 → 认证功能涉及多个模块 →
```
high
```
推理级别
构建包含认证需求的规划提示词
使用
```
gpt-5.3-codex
```
和
```
high
```
推理级别执行Codex
呈现Codex的架构建议
整合成Claude的计划格式

Code Review Request

代码审查请求

User: "Have Codex review the changes in src/auth/"

Validate Codex CLI available
Read files in
```
src/auth/
```
directory
Assess complexity → single directory, focused review →
```
medium
```
reasoning
Construct review prompt with file contents and diff context
Execute via
```
run-codex-exec.sh
```
with
```
EFFORT=medium
```
Present findings with file/line references
Summarize critical issues and recommendations

用户：“让Codex审查src/auth/中的变更”

验证Codex CLI可用
读取
```
src/auth/
```
目录中的文件
评估复杂度 → 单目录、聚焦审查 →
```
medium
```
推理级别
构建包含文件内容和diff上下文的审查提示词
通过
```
run-codex-exec.sh
```
以
```
EFFORT=medium
```
执行
呈现包含文件/行号引用的发现结果
总结关键问题和建议

Additional Resources

额外资源

Reference Files

参考文件

~/.agents/skills/oracle-codex/references/codex-flags.md
- Complete model and flag documentation

~/.agents/skills/oracle-codex/references/codex-flags.md
- 完整的模型和标志文档

Scripts

脚本

~/.agents/skills/oracle-codex/scripts/check-codex.sh
- Prerequisite validation (run before any Codex command)

~/.agents/skills/oracle-codex/scripts/check-codex.sh
- 前置条件验证（任何Codex命令前都需运行）