实战教程

Codex 完整教程：四种形态、配置系统与生产级实战

发布时间: 2026-02-24 · 更新于: 2026-03-25

2026 最新 Codex 完整教程，从 Codex 是什么到 App、CLI、IDE、Cloud 四种形态，再到配置系统、提示词工程与生产级实战一次讲透。

Codex API 国内中转 Codex API 注册领取 1.5 美元额度，支持 gpt-5.3-codex（AI 编程专用），充值额度 1 人民币 = 1 美元。 点击查看 →

这篇是面向中文开发者的 Codex 长文教程，目标是解决三个问题：

  1. Codex 到底和普通 AI 编程助手有什么本质区别。
  2. App、CLI、IDE 扩展、Cloud 四种形态该怎么选、怎么配。
  3. 如何把 Codex 真正用于生产任务，而不是停留在“演示级”对话。

阅读建议：

说明：本文基于你当前可访问的产品能力与工程经验整理。具体命令、开关和可用模型版本，始终以你本地 codex --help 和官方文档为准。

第一章：Codex 到底是什么？

1.1 官方定义 vs 实际体验

官方定位通常是“软件开发助手”，覆盖写代码、读代码、审查、调试和自动化。

实际工程体验可以更直白：

  • 它不是“给你一点代码片段”的补全工具。
  • 它更像一个能在较长上下文里持续推理、执行和验证的开发代理。
  • 在复杂任务上，常见表现是前期思考时间更长，但一次产出质量更高。

1.2 Codex vs 其他 Coding Agent

维度 Codex 其他 Agent（常见）
推理节奏 偏重深推理，复杂任务更稳 偏重快响应
输出质量 目标是减少返工与迭代轮次 常需多轮补丁式修正
屎山风险 较低（前提是边界定义清楚） 中到高（提示词不严谨时）
适合场景 复杂任务、生产级改动 快速原型、轻量需求
集成方式 模型与执行框架一体化明显 很多是插件式拼接

1.3 为什么 Codex 经常“一击必杀”？

核心逻辑不是“模型更大”这么简单，而是模型层、执行框架层、交互层的协同。

  1. 模型层（Model）
  • 负责代码理解、方案推理与生成。
  • 能处理架构级问题，不只是函数级改写。
  1. 框架层（Harness）
  • 把“建议”变成“可执行动作”：读写文件、运行命令、执行测试。
  • 通过上下文压缩与状态管理，降低长对话失真。
  1. 界面层（Surfaces）
  • App、CLI、IDE、Cloud 各自适配不同生产场景。
  • 同一任务可在不同入口接力，不必重建上下文。

这也是 Native Coding 的关键：不是把模型硬塞进旧工具，而是从执行链路开始共同设计。

1.4 能力边界（这段一定要看）

Codex 能做：

  • 写生产代码与测试
  • 理解复杂仓库结构
  • 做代码审查与优化建议
  • 诊断错误并给出修复路径
  • 自动化重复工程任务

Codex 不能替代：

  • 业务决策
  • 最终安全审计
  • 代码 Owner 的上线把关

一句话：它很强，但你仍然要做 Review。

第二章：Codex 的四种形态（Surfaces）

这是你真正拉开效率差距的一章。

2.1 形态总览

形态 适用场景 核心优势 平台
Codex App 主力开发、并行任务、Git 工作流 并行线程、Worktree、内置 Git macOS（Apple Silicon 优先）
CLI 终端、脚本化、CI/CD 功能完整、可编排、易自动化 macOS/Linux/Windows
IDE 扩展 编辑器内迭代 上下文感知、所见即所得 VS Code/Cursor/Windsurf/JetBrains
Cloud 后台长任务、远程执行 不占本地、并行能力强、GitHub 集成 Web

2.2 Codex App：主力开发形态

安装与初始化

  1. 下载并安装 App。
  2. 用 ChatGPT 账号或 API Key 登录。
  3. 选择项目目录。
  4. 选择模式（Local / Worktree / Cloud）并发送首条任务。

三种工作模式

  • Local：直接修改当前仓库，适合小改动。
  • Worktree：每任务独立工作区，隔离性最好，推荐默认使用。
  • Cloud：远程执行，适合长时间任务或本地资源紧张。

Worktree 工作流（推荐）

  1. 新建线程时选择 Worktree。
  2. 设定基线分支（如 main）。
  3. 执行任务并完成验证。
  4. 将结果转分支并发起 PR。

优点：隔离、可并行、低污染。

Automations（自动化）

你可以把固定任务变成定时作业：

  • 定时代码审查
  • 变更触发文档更新
  • 日志告警后的自动修复草案

建议为自动化设置清晰边界：

  • 审批策略不要默认全开放
  • 沙盒优先 read-only 或 workspace-write
  • 关键仓库必须保留人工合并门禁

Local Environments

在项目根目录配置 .codex/local-env.toml：

[setup]
commands = [
  "npm install",
  "npm run build"
]

[actions]
test = "npm test"
lint = "npm run lint"

价值：新线程或新 worktree 打开即可进入“可工作状态”。

2.3 CLI：最灵活的形态

CLI 适合“可复制、可批量、可集成”的任务。

安装与登录

npm install -g @openai/codex
codex login

三种常用用法

  1. 交互式
codex
codex "帮我重构这个模块，先输出计划再改代码"
  1. 非交互脚本化
codex exec --json "分析这个目录的风险" > result.json
codex exec --output-last-message report.md "生成发布说明"
  1. 会话续接
codex resume --all
codex resume --last
codex fork --last

进阶能力（高频）

  • 模型切换：--model
  • 推理强度：--config model_reasoning_effort=high
  • 图片输入：--image
  • 网页搜索：--search（受权限和策略约束）
  • 代码审查：/review 或 against 某分支

2.4 IDE 扩展：编辑器内闭环

如果你长时间在编辑器里工作，IDE 扩展是最低摩擦路径。

核心价值：

  • 自动带入当前文件与选中代码
  • 支持 @filename 精准引用上下文
  • 不离开编辑器完成提问、改动、审查

审批模式一般分为：

  • Chat：只讨论，不改文件
  • Agent：默认读写+执行
  • Agent (Full Access)：含更高权限能力

2.5 Cloud：后台执行形态

Cloud 适合“重任务”和“长任务”：

  • 仓库级重构
  • 多模块并行分析
  • 需要离线等待结果的任务

常见流程：

  1. 在 App/IDE 里选择 Cloud。
  2. 提交任务并离线等待。
  3. 任务完成后预览 diff。
  4. 手动审查后应用到本地。

2.6 配置系统（TOML）

配置优先级（高 -> 低）：

  1. CLI 参数（--config）
  2. Profile（--profile）
  3. 项目配置（.codex/config.toml）
  4. 用户配置（~/.codex/config.toml）
  5. 系统配置
  6. 默认值

项目级推荐模板：

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

developer_instructions = """
这是一个 FastAPI 项目。
请优先保持现有目录结构。
所有新增函数必须有类型注解和测试。
"""

[history]
persistence = "save-all"
max_bytes = 104857600

2.7 怎么选最合适的形态？

快速决策：

  • 你是终端重度用户，且要做 CI/CD：优先 CLI。
  • 你要并行做多个功能，且强调隔离：优先 App + Worktree。
  • 你在编辑器内高频改小步代码：优先 IDE 扩展。
  • 你要让任务后台跑几个小时：优先 Cloud。

常见组合：

  • 日常主力：App + IDE
  • 自动化链路：CLI + Cloud
  • 大型重构：App(Worktree) + Cloud

第三章：提示词工程（让 Codex 准确执行）

3.1 好提示词与坏提示词

坏提示词：

帮我写个程序

好提示词：

用 Python 写一个异步 HTTP 客户端，要求：
1) 支持 GET/POST/PUT/DELETE
2) 默认超时 30 秒
3) 自动重试 3 次，指数退避
4) 记录请求/响应日志
5) 使用 aiohttp，不要 requests

区别在于：目标、边界、约束、质量标准是否明确。

3.2 万能公式

目标 + 技术栈 + 输入输出 + 约束条件 + 质量要求

可直接复用模板：

目标：{你要达成什么}
技术栈：{语言/框架/库}
输入：{文件/接口/数据来源}
输出：{产物和格式}
约束：{不可改动内容、性能、安全、兼容性}
质量要求：{测试、类型注解、文档、错误处理}

3.3 迭代式提问（最实用）

建议按“骨架 -> 能跑 -> 强化”三轮推进：

  1. 先让它给架构和最小实现。
  2. 再补鉴权、缓存、重试、日志等能力。
  3. 最后加性能、安全、可观测性与测试。

3.4 让它解释陌生代码

请逐段解释这段代码，重点说明：
1) 装饰器的作用
2) 异步边界在哪里
3) 异常处理覆盖了哪些失败路径
4) 这段代码最可能的线上风险是什么

3.5 调试提示词模板

我遇到如下报错：
{粘贴完整堆栈}

运行环境：
- Python 版本：
- 依赖版本：
- 输入样例：

请输出：
1) 根因定位
2) 最小修复 patch
3) 回归测试用例
4) 如何避免同类问题再次发生

第四章：实战模板（可直接开工）

4.1 项目一：API 监控服务

需求拆解：

  • 监控 50+ API 健康状态
  • 每 5 分钟检测一次
  • 连续失败告警（Slack）
  • 历史数据入库（PostgreSQL）
  • 前端仪表板可视化

首轮提示词建议：

请设计一个 API 监控系统，技术栈：FastAPI + PostgreSQL + React + APScheduler + Slack SDK。
先输出：
1) 项目目录结构
2) 数据库 schema
3) 核心模块骨架代码
4) 第一周可交付里程碑

4.2 项目二：ETL 数据管道自动化

目标流程：S3(raw) -> 清洗 -> 转换 -> PostgreSQL(analytics)

首轮提示词：

构建一个 Python ETL 管道（Airflow + boto3 + pandas + SQLAlchemy），请实现：
1) DAG 定义
2) 重试与告警机制
3) 数据质量检查（空值率、重复率、主键完整性）
4) 失败回滚策略

4.3 项目三：内部 CLI 工具

常见命令：deploy / config / logs

首轮提示词：

用 Click + rich 实现一个内部 CLI：
- deploy：打包、上传、远程脚本执行
- config：初始化/校验/编辑配置
- logs：拉取日志、grep 过滤、tail 模式
要求：支持 --dry-run 和 --verbose，并补充单元测试。

第五章：进阶技巧

5.1 自定义 Rules

把团队约束前置给 Codex，减少来回拉扯。

示例规则目标：

  • I/O 逻辑优先 async/await
  • 新增函数必须类型注解
  • 可能失败路径必须显式异常处理

5.2 用 Skills 扩展能力

Skills 可以把固定工作流封装为可复用能力，例如：

  • 代码审查模板
  • SEO 审计流程
  • 发布前检查清单

建议：把高频任务沉淀为团队共享 Skill，减少重复提问。

5.3 Codex App 实用技巧

  • Cmd+J：线程终端切换
  • Cmd+数字：项目快速切换
  • Ctrl+M：语音输入（如版本支持）
  • Worktree 默认开启，减少误改主分支

5.4 MCP 集成

MCP 让 Codex 访问第三方上下文（文档、设计、平台 API）。

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@github/mcp-server"]

5.5 多 Agent 协作（实验性）

适合复杂任务拆分：

  • Agent A 负责架构与任务分解
  • Agent B 负责实现
  • Agent C 负责评审与回归检查

原则：分工清晰、输入输出标准化、最终人工合并把关。

结语：把 Codex 用成生产力系统

你可以把 Codex 当成“更聪明的聊天机器人”，也可以把它当成“可执行的工程系统”。

真正的差距来自三件事：

  1. 你是否定义了清晰边界。
  2. 你是否把流程标准化（计划 -> 执行 -> 验证 -> 提交）。
  3. 你是否把经验沉淀为配置、模板和规则。

如果你已经看完这篇，建议下一步直接实操这两篇配套教程：

相关阅读