OpenAI Codex 完整使用指南

Cactus li原创2025年9月23日...大约 21 分钟

OpenAI Codex 完整使用指南

📖 文档导读

本指南将带你从零开始掌握 OpenAI Codex，涵盖配置、命令、工具调用、实战技巧等各个方面。

🔗 官方资源

🆕 Codex 新特性（2025）

重大更新

Codex 已从单纯的代码生成模型升级为功能完整的软件工程代理，具备以下核心能力：

核心能力

功能	说明
自主任务执行	在隔离环境中自动完成功能开发、Bug 修复、代码重构等任务（1-30分钟）
多任务并行	支持同时处理多个独立任务，提升开发效率
完整可追溯性	提供终端日志、测试输出等可验证证据，完整追踪执行步骤
Slack 集成	直接在 Slack 频道中与 Codex 交互，像与同事沟通一样分配任务
Codex SDK	将 Codex 能力嵌入到自己的应用和工作流中，无需大量调优
管理员工具	环境控制、监控和分析仪表板，便于大规模管理 Codex

技术架构

模型: 基于 codex-1 模型，通过强化学习在真实编程任务上优化
开源 CLI: 使用 Rust 构建，开源在 GitHub，持续更新
系统要求:
- macOS 12+ / Ubuntu 20.04+ / Debian 10+ / Windows 11 (WSL2)
- Node.js 22+
- Git 2.23+ (推荐)

使用方式

终端 CLI - 本地开发环境直接使用
IDE 扩展 - VS Code 等 IDE 集成
Web 界面 - 通过 ChatGPT 网页版使用（需关联 GitHub 账户）
GitHub Actions - CI/CD 流程自动化
Slack - 团队协作场景

🚀 快速开始

安装 Codex CLI

Codex CLI 支持多种安装方式：

使用 npm（推荐）：

npm install -g @openai/codex

使用 Homebrew（macOS）：

brew install codex

更新到最新版本：

# npm
npm install -g @openai/codex@latest

# Homebrew
brew upgrade codex

认证方式

Codex 提供两种认证方式：

1. ChatGPT 账户认证（推荐）

直接使用 ChatGPT 账户登录，无需配置 API Key：

codex
# 首次运行会提示登录 ChatGPT 账户

优势：

✅ 无需管理 API Key
✅ 自动同步配置
✅ 支持所有订阅计划（Plus, Pro, Business, Enterprise）

2. API Key 认证

适用于需要使用自定义 API 端点的场景：

# 设置 API Key
export OPENAI_API_KEY="your-api-key"
codex

使用限制

订阅计划	本地任务消息限制	云端任务限制
Plus	50 条/3小时	有限制
Pro	更高额度	更高额度
Business/Enterprise	企业级额度	企业级额度

提示

本地任务（CLI/IDE）和云端任务（Web/Slack）的限制分别计算。合理分配使用场景可以最大化利用配额。

⚙️ 基础配置 config.toml

配置前必读

工欲善其事，必先利其器。强烈建议先阅读官方配置文档了解各项配置的详细作用。

在 ~/.codex/config.toml 文件中进行基础配置：

# 模型配置
model = "codex-1"
#model = "gpt-5-codex"                      # Codex 0.36.0+ 支持
model_reasoning_effort = "high"            # 使用最大推理能力
model_reasoning_summary = "detailed"       # 终端显示详细推理总结 (Ctrl+T查看)
model_verbosity = "high"                   # 高详细度输出
model_supports_reasoning_summaries = true  # 强制启用推理总结

# 代理配置
hide_agent_reasoning = false               # 显示 Agent 内部思考过程

# 隐私配置
disable_response_storage = true            # 禁止 OpenAI 存储对话数据

# 权限配置 (建议通过 /approvals 命令配置)
approval_policy = "never"                  
sandbox_mode = "workspace-write"           

# 网络访问配置
[sandbox_workspace_write]
network_access = true                      # 允许网络访问

配置项详解

model_reasoning_effort: 控制模型推理深度，high 提供最佳效果
model_reasoning_summary: 推理总结详细程度，detailed 提供完整信息
hide_agent_reasoning: 设为 false 可查看更多内部处理过程
disable_response_storage: 重要隐私设置，禁止数据存储

🚀 核心命令

命令帮助

使用 codex --help 查看所有可用命令参数，这是个好习惯！

启动 Codex 后，输入 / 可查看所有支持的快捷命令：

📊 /status - 状态检查

最重要的命令，用于检查：

当前权限级别
codex-1 模型配置状态
API Key 或 ChatGPT 认证状态
当前工作区和环境设置

特别提醒

使用自定义 API Key 时，务必经常检查确保使用正确的模型配置。建议优先使用 ChatGPT 账户认证，无需处理 API Key。

🔐 /approvals - 权限管理

Codex 提供三种权限级别：

权限级别	功能范围	适用场景	实际体验
Read Only	仅读取文件	代码审查、学习	❌ 限制过多，频繁需要确认
Auto	读写文件、运行命令	一般开发	⚠️ 仍需较多手动确认
Full Access	完整权限 + 网络访问	完整开发流程	✅ 真正的自动化体验

推荐配置

对于日常开发，推荐使用 Full Access 模式，可通过启动参数跳过权限确认：

codex --dangerously-bypass-approvals-and-sandbox

安全提醒

Full Access 模式具有完整系统权限，请确保在可信环境中使用。

🔌 /mcp - MCP 服务器配置

Windows 用户注意

Windows 开发者按照 mcp_servers 官方文档配置通常会失败！

常见错误信息：

Program not found
# 或
request timed out

Windows 下正确配置方法：

在原教程基础上添加以下配置：

➕ 新增 command - 指向具体的 npx 位置
➕ 新增 env - 包含 SYSTEMROOT 环境变量

[mcp_servers.context7]
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "@upstash/context7-mcp", "--api-key", "<your_api_key>"]
env = {SYSTEMROOT = 'C:\Windows'}

成功配置后

正确配置后，你将看到类似下图的显示效果：

🔄 对话恢复功能

功能状态

恢复/继续对话功能仍在开发中，所以 --help 中暂未添加说明，但当前可用。

Codex 的对话历史保存在本地目录 ~/.codex/sessions 下：

选择恢复对话：

codex --resume    # 显示最近对话列表，手动选择

直接继续上次对话：

codex --continue  # 无需选择，自动继续上次对话

🛠️ 工具调用优化

目标

为了最快、最准确地帮助 Codex 完成任务，我们需要针对性地使用不同的搜索工具。

平台适配：
本文主要针对 Windows 平台，旨在引导 Codex 使用正确的命令和工具，减少错误重试、降低任务执行时长。

仓库规则配置：
Codex 支持在代码仓库根目录添加 AGENTS.md 文件指导工具使用规则。

📋 AGENTS.md 最佳实践（重要）

性能提升

根据 OpenAI 官方测试，正确配置的 AGENTS.md 文件可以将代码生成准确率提升至 75%，显著改善开发体验和代码质量。

什么是 AGENTS.md？

AGENTS.md 是 Codex 引入的特殊文档文件，作为项目的"AI 指南"，让 Codex 理解你的项目特有的编码标准、架构模式和最佳实践。通过提供上下文特定的信息，Codex 可以生成与团队规范高度一致的代码。

层级结构与优先级

Codex 支持 层级化的 AGENTS.md 配置，在不同目录层级定义不同规则：

project-root/
├── AGENTS.md              # 全局规则（最低优先级）
├── src/
│   ├── AGENTS.md          # 源码目录规则
│   ├── components/
│   │   └── AGENTS.md      # 组件特定规则
│   └── tests/
│       └── AGENTS.md      # 测试特定规则（最高优先级）

优先级顺序（从高到低）：

开发者直接指令 - 对话中的明确要求
嵌套 AGENTS.md - 越深层的目录优先级越高
根目录 AGENTS.md - 全局默认规则

配置内容建议

一个完善的 AGENTS.md 应包含：

1. 项目结构说明

## Project Structure
- `src/` - 主要源代码目录
- `src/components/` - React 组件（使用函数式组件 + Hooks）
- `src/utils/` - 工具函数（纯函数，需要单元测试）
- `tests/` - 测试文件（使用 Vitest）

2. 编码规范

## Coding Conventions
- 使用 TypeScript，启用严格模式
- 组件命名：PascalCase（例如：`UserProfile.tsx`）
- 工具函数命名：camelCase（例如：`formatDate.ts`）
- CSS 使用 Tailwind CSS，避免内联样式
- 异步函数必须有错误处理

3. 测试要求

## Testing Guidelines
- 测试框架：Vitest + React Testing Library
- 每个工具函数必须有单元测试
- 组件测试覆盖主要交互流程
- 运行测试：`pnpm test`
- 覆盖率目标：80%+

4. Pull Request 规范

## PR Guidelines
- 分支命名：`feature/`, `fix/`, `refactor/`
- Commit 信息：遵循 Conventional Commits
- PR 标题格式：`[类型] 简短描述`
- 必须通过：lint, typecheck, 所有测试

5. 工具链配置（重要！）

## Tool Priority
- 文件名搜索：使用 `fd`
- 文本内容搜索：使用 `rg` (ripgrep)
- 代码结构搜索：使用 `sg` (ast-grep)
- 排除目录：`.git`, `node_modules`, `dist`, `coverage`

实际效果对比

场景	无 AGENTS.md	有 AGENTS.md
代码风格一致性	60%	95%
首次生成正确率	40%	75%
需要重构次数	3-5 次	0-1 次
团队成员上手时间	2-3 天	0.5-1 天

调试与优化

重要技巧

每次修改 AGENTS.md 后，使用 Ctrl+T 查看 Codex 的思考过程，验证：

是否正确读取了 AGENTS.md 规则
命令调用是否符合预期
是否还有需要补充的规则

优化流程：

修改 AGENTS.md → 2. 分配任务给 Codex → 3. Ctrl+T 查看思考过程 → 4. 发现偏差及时调整

🔍 三大搜索工具

工具类型	工具名称	使用场景	命令示例
📁 文件名搜索	`fd`	按文件名查找	`fd "*.ts" src/`
📋 文本内容搜索	`rg` (ripgrep)	按文本内容查找	`rg "function" src/`
🌳 代码结构搜索	`sg` (ast-grep)	按代码语义查找	`sg -p "import $$" src/`

Windows 安装

winget install sharkdp.fd BurntSushi.ripgrep.MSVC ast-grep

ripgrep 安装后需要手动添加到环境变量，自行解决

🗍️ AGENTS.md 配置指南

经验分享

在实际操作中发现，仅声明可用工具而不引导具体用法，经常会偏离预期。建议使用下方完整配置，按需调整。

## Tool Priority

- Filename search: `fd`.
- Text/content search: `rg` (ripgrep).
- AST/structural search: `sg` (ast-grep) — preferred for code-aware queries (imports, call expressions, JSX/TSX nodes).

### AST-grep Usage (Windows)

- Announce intent and show the exact command before running complex patterns.
- Common queries:
  - Find imports from `node:path` (TypeScript/TSX):
    - `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
  - Find CommonJS requires of `node:path`:
    - `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
  - Suggest rewrite (do not auto-apply in code unless approved):
    - Search: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
    - Proposed replacement: `import $$ from 'pathe'`

### Search Hygiene (fd/rg/sg)

- Exclude bulky folders to keep searches fast and relevant: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- Prefer running searches against a scoped path (e.g., `src`) to implicitly avoid vendor and VCS directories.
- Examples:
  - `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
  - `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grep typically respects `.gitignore`; target `src` to avoid scanning vendor folders:
  - `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
  - If needed, add ignore patterns to your ignore files rather than disabling ignores.

🔔 系统通知配置

功能介绍

Codex 支持在任务执行完成后执行自定义事件，我们可利用这一特性实现 Windows 系统弹窗通知。

参考文档： Codex 通知配置

步骤 1：配置 config.toml

在 ~/.codex/config.toml 中添加：

# 通知命令配置
notify = [
    "powershell.exe",
    "-NoProfile",
    "-ExecutionPolicy","Bypass",
    "-File","C:\\Users\\<username>\\.codex\\notify.ps1"
]

步骤 2：创建通知脚本

在 ~/.codex/notify.ps1 中创建：

param(
  [Parameter(Mandatory = $true)]
  [string]$json
)

# 解析 JSON（Codex 传入的 JSON 参数）
try {
  $payload = $json | ConvertFrom-Json
} catch {
  $payload = @{}
}

# 配置通知内容
$title = 'Codex 任务完成'
$msg   = $payload.'last-assistant-message'

if (-not $msg) {
  if ($payload.type) {
    $msg = "事件类型: $($payload.type)"
  } else {
    $msg = 'Codex 有新更新。'
  }
}

# 文本截断处理（避免过长显示）
if ($msg -and $msg.Length -gt 240) {
  $msg = $msg.Substring(0,240) + '...'
}

# 使用 BurntToast 模块显示通知
Import-Module BurntToast -ErrorAction Stop
New-BurntToastNotification -Text $title, $msg | Out-Null

安装依赖

需要先安装 BurntToast PowerShell 模块：

Install-Module -Name BurntToast -Scope CurrentUser

🛠️ 调试技巧与优化

调试核心

每次修改 AGENTS.md 后，多使用 Ctrl+T 查看思考过程，检查命令调用和思考逻辑是否符合预期。

🔄 优化流程

📈 调试技巧

定期检查 - 使用 Ctrl+T 查看当前任务的思考轨迹
及时调整 - 发现偏差时直接与 Codex 对话询问
多轮优化 - 重复调整直到获得满意结果
记录经验 - 将有效的 AGENTS.md 配置保存为模板

🧪 Spec-kit 工作流（实验性）

实验特性

模仿 GitHub Spec-kit 建立的新功能实现规范，包含三个流程：spec、plan 和 do。

流程概览

阶段	命令	作用	输出
规范	`/spec`	生成功能规范	`specs/` 目录下的 Markdown 文件
计划	`/plan`	根据规范生成实现计划	`plans/` 目录下的计划文件
实现	`/do`	按照计划执行实现	实际代码变更

注意事项

不必严格遵循三个阶段顺序
可以多轮对话调整 spec 文件直到满意
仍在测试优化中，未使用官方 prompts.md 方式

## Stage-Gated Workflow (spec/plan/do)

- Mode: Opt-in. The workflow applies only when the user explicitly uses `/spec`, `/plan`, or `/do`. Routine Q&A or trivial edits do not require these stages.
- Triggers: A message containing one of `/spec`, `/plan`, or `/do` activates or advances the workflow. Once active, stages must proceed in order with explicit user approval to advance.
- Guardrails:
  - Do not modify source code before `/do`. Documentation/spec files may be edited only in `/spec`.
  - Do not skip stages or proceed without user confirmation once the workflow is active.
  - If scope changes, return to the appropriate prior stage for approval.
  - Respect sandbox/approval settings for all actions.

- When to Use
  - Use the workflow for new features, structural refactors, multi-file changes, or work needing traceability.
  - Skip the workflow (no triggers) for routine Q&A, diagnostics, or one-off trivial edits.

- Entry Points and Prerequisites
  - `/spec` is the canonical entry point for new efforts.
  - `/plan` requires an approved `/spec`. If unclear which spec applies, pause and ask the user to identify the correct file(s) under `specs/`.
  - `/do` requires an approved `/plan`.

- `/spec` (Specifications; docs only)
  - Purpose: Capture a concrete, reviewable specification using spec-kit style.
  - Output: Markdown spec(s) under `specs/` (no code changes). Share a concise diff summary and links to updated files; wait for approval.
  - Style: Specs are canonical and final. Do not include change logs or “correction/更正” notes. Incorporate revisions directly so the document always reflects the current agreed state. Historical context belongs in PR descriptions, commit messages, or the conversation — not in the spec.
  - Recommended contents:
    - Problem statement and context
    - Goals and non-goals
    - Requirements and constraints (functional, UX, performance, security)
    - UX/flows and API/IPC contracts (as applicable)
    - Acceptance criteria and success metrics
    - Alternatives considered and open questions
    - Rollout/backout considerations and telemetry (if relevant)

- `/plan` (High-level Plan; docs only)
  - Purpose: Turn the approved spec into an ordered, verifiable implementation plan.
  - Inputs: Approved spec file(s) in `specs/`.
  - Ambiguity: If the relevant spec is unclear, pause and request clarification before writing the plan.
  - Style: Plans are canonical and should not include change logs or “correction/更正” notes. Incorporate revisions directly so the plan always reflects the current agreed state. Historical notes should live in PR descriptions, commit messages, or the conversation.
  - Output:
    - An ordered plan via `update_plan` (short, verifiable steps; Task is merged into Plan and tracked here).
    - A plan document in `plans/` named `YYYY-MM-DD-short-title.md`, containing:
      - Scope and links to authoritative spec(s)
      - Assumptions and out-of-scope items
      - Phases/milestones mapped to acceptance criteria
      - Impacted areas, dependencies, risks/mitigations
      - Validation strategy (tests/lint/build) and rollout/backout notes
      - Approval status and next stage
  - Handoff: Await user approval of the plan before `/do`.

- `/do` (Execution)
  - Purpose: Implement approved plan steps with minimal, focused changes and file operations.
  - Actions:
    - Use `apply_patch` for file edits; group related changes and keep diffs scoped to approved steps.
    - Provide concise progress updates and a final summary of changes.
    - Validate appropriately: run `pnpm lint`, `pnpm format`, `pnpm build`, and relevant tests.
    - If material changes to the plan are needed, pause and return to `/plan` (or `/spec`) for approval.
  - Output: Implemented changes, validation results, and a concise change summary linked to the plan checklist.

### Plans Directory

- Location: `plans/` at the repository root.
- Filename: `YYYY-MM-DD-short-title.md` (kebab-case title; consistent dating).
- Style: Plan docs are the canonical source of truth for the implementation approach; avoid embedding change logs or “correction/更正” notes. Update the plan in place as decisions evolve.
- Contents:
  - Title and summary
  - Scope and linked specs (paths under `specs/`)
  - Assumptions / Out of scope
  - Step-by-step plan (short, verifiable)
  - Validation strategy (tests/lint/build)
  - Approval status and next stage
- Process:
  - During `/plan`, create or update the relevant file in `plans/` and share a short summary in the conversation. Await approval before `/do`.

WSL2

如果你在 Windows 下让 Codex 执行任务，你会发现它经常调用命令失败然后重试，如此循环。虽然最终都会成功，但浪费了很多时间，个人推测这是因为 GPT-5 Unix Shell 训练数据太多而 Powershell 数据太少导致的幻觉，Codex 总是下意识调用 Unix Shell 命令来处理。

那么有没有办法解决呢？当然有！打不过就加入——WSL2。

以 Windows 11 为例，在 Powershell 执行 wsl --install 即可安装 WSL2。

这种情况下，有两种方式选择：

Windows 端代码+WSL2 Codex 环境，适用于开发 Windows 端的程序，比如 Electron Windows，.NET 等
WSL2 代码 + WSL2 Codex 环境，比如 Vue Web 开发

对于后者，所有都能正常在 WSL2 环境内运行，就不做说明了，而前者 Windows + WSL2 混用就需要解决一个问题：如何在 WSL2 调用 Windows 端的 npm/pnpm，执行定义好的 pnpm typecheck pnpm lint:fix 等。

在 WSL2 Codex 对话时，要求其调用 pwsh.exe 来执行 pnpm typecheck 来检查，如此即可。

we're in WSL2, please using pwsh.exe to run `pnpm <script>`

完整 AGENTS.md

还在调整中，不要完全照抄，最好还是通过 ctrl+T 查看整个过程，如果遇到 Codex 经常会出错的命令，选择性的修删适合自己的 AGENTS.md。

主要适配内容：

Windows/WSL2 支持，优先使用 Powershell 支持的命令，对于任何 npm 包安装都必须请示用户，避免混乱的依赖项
使用 fd,ripgrep,ast-grep 搜索文件、文本和代码片段，更快更直接
spec/plan/do 工作流，先确定规范，再编写计划，最后实现

# AGENTS Guidelines

## Windows Environment Notice

- Prefer PowerShell (`pwsh`/`powershell`) when on Windows.
- Prefer using pwsh.exe to run `pnpm <script>` when on WSL2.
- WSL2 may be used for non-package-manager commands only (e.g., `rg`, `tar`). Avoid running Node builds in WSL due to OS mismatch.
- WSL2 cross-drive performance: accessing repos under `/mnt/c|d|e/...` goes through a filesystem bridge and can be slower for full scans. Prefer scoping to subtrees, excluding heavy folders, or running the same searches with native Windows binaries in PowerShell for large/iterative scans.
- Do not auto-run dependency installs. The user must run `pnpm install` in Windows PowerShell manually and then confirm completion.
- Do not modify `package.json`/lockfiles to add or update dependencies without explicit user approval. Propose dependencies in `/spec` or `/plan`, and ask the user to run `pnpm add <pkg>` (or `pnpm install`) and confirm.
- Do not call Unix text tools directly in PowerShell (e.g., `sed`, `awk`, `cut`, `head`, `tail`). Use PowerShell-native equivalents instead:
  - `head` → `Select-Object -First N`
  - `tail` → `Get-Content -Tail N`
  - paging → `Out-Host -Paging` or `more`
  - substitution/replace → `-replace` with `Get-Content`/`Set-Content`

## Tool Priority

- Filename search: `fd`.
- Text/content search: `rg` (ripgrep).
- AST/structural search: `sg` (ast-grep) — preferred for code-aware queries (imports, call expressions, JSX/TSX nodes).

### AST-grep Usage

- Announce intent and show the exact command before running complex patterns.
- Common queries:
  - Find imports from `node:path` (TypeScript/TSX):
    - `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
  - Find CommonJS requires of `node:path`:
    - `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
  - Suggest rewrite (do not auto-apply in code unless approved):
    - Search: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
    - Proposed replacement: `import $$ from 'pathe'`

### Search Hygiene (fd/rg/sg)

- Exclude bulky folders to keep searches fast and relevant: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- Prefer running searches against a scoped path (e.g., `src`) to implicitly avoid vendor and VCS directories.
- Examples:
  - `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
  - `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grep typically respects `.gitignore`; target `src` to avoid scanning vendor folders:
  - `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
  - If needed, add ignore patterns to your ignore files rather than disabling ignores.

## Temporary Research Files

- Canonical location: store all temporary research artifacts (downloaded READMEs, API docs, scratch notes) under `docs/research/`.
- Do not place temporary files at the repository root or outside `docs/research/`.
- Commit policy: avoid committing temporary files unless they are necessary for traceability during `/spec` or `/plan`. If committed, keep the scope minimal and store them under `docs/` only.
- Naming: use descriptive names with date or task context (e.g., `docs/research/2025-09-11-wsl-notes.md`).
- Cleanup: after completing a task (`/do`), evaluate whether each temporary file is still required. Remove unneeded files, or promote essential content into curated docs under `docs/` or into `specs/`/`plans/`.

## Stage-Gated Workflow (spec/plan/do)

- Mode: Opt-in. The workflow applies only when the user explicitly uses `/spec`, `/plan`, or `/do`. Routine Q&A or trivial edits do not require these stages.
- Triggers: A message containing one of `/spec`, `/plan`, or `/do` activates or advances the workflow. Once active, stages must proceed in order with explicit user approval to advance.
- Guardrails:
  - Do not modify source code before `/do`. Documentation/spec files may be edited only in `/spec`.
  - Do not skip stages or proceed without user confirmation once the workflow is active.
  - If scope changes, return to the appropriate prior stage for approval.
  - Respect sandbox/approval settings for all actions.

- When to Use
  - Use the workflow for new features, structural refactors, multi-file changes, or work needing traceability.
  - Skip the workflow (no triggers) for routine Q&A, diagnostics, or one-off trivial edits.

- Entry Points and Prerequisites
  - `/spec` is the canonical entry point for new efforts.
  - `/plan` requires an approved `/spec`. If unclear which spec applies, pause and ask the user to identify the correct file(s) under `specs/`.
  - `/do` requires an approved `/plan`.

- `/spec` (Specifications; docs only)
  - Purpose: Capture a concrete, reviewable specification using spec-kit style.
  - Output: Markdown spec(s) under `specs/` (no code changes). Share a concise diff summary and links to updated files; wait for approval.
  - Style: Specs are canonical and final. Do not include change logs or “correction/更正” notes. Incorporate revisions directly so the document always reflects the current agreed state. Historical context belongs in PR descriptions, commit messages, or the conversation — not in the spec.
  - Recommended contents:
    - Problem statement and context
    - Goals and non-goals
    - Requirements and constraints (functional, UX, performance, security)
    - UX/flows and API/IPC contracts (as applicable)
    - Acceptance criteria and success metrics
    - Alternatives considered and open questions
    - Rollout/backout considerations and telemetry (if relevant)

- `/plan` (High-level Plan; docs only)
  - Purpose: Turn the approved spec into an ordered, verifiable implementation plan.
  - Inputs: Approved spec file(s) in `specs/`.
  - Ambiguity: If the relevant spec is unclear, pause and request clarification before writing the plan.
  - Style: Plans are canonical and should not include change logs or “correction/更正” notes. Incorporate revisions directly so the plan always reflects the current agreed state. Historical notes should live in PR descriptions, commit messages, or the conversation.
  - Output:
    - An ordered plan via `update_plan` (short, verifiable steps; Task is merged into Plan and tracked here).
    - A plan document in `plans/` named `YYYY-MM-DD-short-title.md`, containing:
      - Scope and links to authoritative spec(s)
      - Assumptions and out-of-scope items
      - Phases/milestones mapped to acceptance criteria
      - Impacted areas, dependencies, risks/mitigations
      - Validation strategy (tests/lint/build) and rollout/backout notes
      - Approval status and next stage
  - Handoff: Await user approval of the plan before `/do`.

- `/do` (Execution)
  - Purpose: Implement approved plan steps with minimal, focused changes and file operations.
  - Actions:
    - Use `apply_patch` for file edits; group related changes and keep diffs scoped to approved steps.
    - Provide concise progress updates and a final summary of changes.
    - Validate appropriately: run `pnpm lint`, `pnpm format`, `pnpm build`, and relevant tests.
    - If material changes to the plan are needed, pause and return to `/plan` (or `/spec`) for approval.
  - Output: Implemented changes, validation results, and a concise change summary linked to the plan checklist.

### Plans Directory

- Location: `plans/` at the repository root.
- Filename: `YYYY-MM-DD-short-title.md` (kebab-case title; consistent dating).
- Style: Plan docs are the canonical source of truth for the implementation approach; avoid embedding change logs or “correction/更正” notes. Update the plan in place as decisions evolve.
- Contents:
  - Title and summary
  - Scope and linked specs (paths under `specs/`)
  - Assumptions / Out of scope
  - Step-by-step plan (short, verifiable)
  - Validation strategy (tests/lint/build)
  - Approval status and next stage
- Process:
  - During `/plan`, create or update the relevant file in `plans/` and share a short summary in the conversation. Await approval before `/do`.

💡 经验分享

🎯 主动引导技巧

核心理念

不要把所有注意事项都写入 AGENTS.md，用户需要根据不同场景主动引导 Codex 使用适合的工具。

实用例子：

使用 git diff 提供更准确的上下文
在查询时直接给出关键信息（函数名、文件名等）

📝 信息提供原则

尽可能提供完整信息：
Codex 的代码搜索方式相对原始，可能搜不到你想要的内容。

最佳实践：

直接提供函数名、文件名等关键信息
使用 @ 快捷命令快速搜索文件名
减少 Codex 的误判和搜索时间

🌐 网页搜索建议

分工建议

网页搜索优先使用网页版 ChatGPT-5-Thinking：

搜索更快更完整
非常擅长 GitHub 项目检索（源码、项目结构、issue、PR）
特别适合了解开源项目功能

🎯 Codex 与其他 AI 编程工具对比

Codex vs GitHub Copilot

特性	Codex	GitHub Copilot
定位	自主编程代理	代码补全助手
工作方式	完整任务执行（1-30分钟）	实时行级建议
环境	隔离沙箱环境	IDE 内联
能力范围	读写文件、执行命令、运行测试、提交 PR	代码建议和补全
适用场景	功能开发、重构、Bug 修复	日常编码加速
可追溯性	完整日志和执行记录	无执行记录

最佳使用建议

日常编码：使用 GitHub Copilot 获得实时建议
功能开发：使用 Codex 自动化完成完整功能
代码审查：使用 Codex 分析代码库、生成文档
团队协作：使用 Codex Slack 集成分配任务
CI/CD：使用 Codex GitHub Actions 自动化测试和部署

💡 个性化调教建议

AI 工具千人千面，每个人都有各自的编程习惯：

📅 投入时间学习：不要期望三分钟上手，花几天深入了解
🧠 理解工作原理：了解大语言模型的特点和局限性
🔧 定制化配置：根据项目和团队特点调整 AGENTS.md
🔄 持续迭代：观察实际效果，不断优化使用方式
🤝 社区交流：参与 Codex 社区，分享经验和最佳实践

⚠️ 注意事项

不是万能的：Codex 是助手，不是替代品，关键决策仍需人工
代码审查必不可少：始终审查 Codex 生成的代码
安全第一：注意敏感信息，合理设置权限级别
成本意识：了解使用限制，合理分配任务优先级
持续学习：AI 技术快速发展，保持关注最新特性

文档维护

本文档基于 OpenAI Codex 2025 年 10 月最新版本编写，将持续更新跟进最新变化。