Codex 是 OpenAI 面向软件开发的智能编码代理。它不只是补全代码，而是能够读取项目、修改多个文件、运行命令、执行测试、审查差异，并在获得授权后完成一段完整的工程任务。Codex 目前覆盖桌面应用、终端 CLI、IDE 扩展和云端执行环境，适合从快速排错到长时间重构的不同场景。
本文基于 2026 年 8 月的 OpenAI 官方文档整理。具体模型、套餐权益和界面可能随版本变化，以客户端内显示和官方文档为准。
一、先选对 Codex 使用入口
| 入口 | 适用场景 | 特点 |
|---|---|---|
| ChatGPT 桌面应用中的 Codex | 本地项目、长任务、文件和终端协作 | 图形界面完整，适合规划、执行和审查 |
| Codex CLI | 终端、服务器、脚本和 CI | 启动快，可交互，也可用非交互模式自动化 |
| Codex IDE 扩展 | 边写代码边让 Agent 修改 | 能利用编辑器当前文件、选区和诊断信息 |
| Codex Cloud | 隔离环境中的后台任务 | 适合把耗时任务委派出去，再审查结果 |
二、安装、登录与打开项目
桌面应用
- 从 OpenAI 官方页面安装 ChatGPT 桌面应用并登录。
- 新建任务时选择 Codex。
- 选择本地项目文件夹，或使用已保存的项目。
- 首次访问文件、终端或网络时，根据任务范围授予权限。
Codex CLI
Node.js 环境可通过 npm 安装 CLI：
npm install -g @openai/codex
cd /path/to/your-project
codex首次运行会引导登录。进入会话后，先让 Codex阅读项目结构和说明文件，再提出修改目标。用于脚本或 CI 时，可使用 codex exec 运行非交互任务。
三、一个高成功率的标准工作流
- 先说明结果：例如“修复登录后偶发 401，并补充回归测试”。
- 限定范围：指出目录、不能改动的接口、兼容版本与依赖限制。
- 要求先检查：让 Codex读取相关代码、日志和测试，再决定修改点。
- 让验证成为任务的一部分：明确要求运行 typecheck、lint、单测或构建。
- 审查差异：重点看权限、数据库迁移、依赖升级和删除操作。
请定位订单回调重复入账的原因。
只修改 services/payment 和对应测试；不要改数据库结构。
修复后运行相关单测，并总结根因、改动和剩余风险。四、权限、沙箱与安全
Codex 的能力来自文件系统、终端、网络和外部工具，因此权限边界比“回答是否正确”更重要。日常开发建议让项目目录可写、其他目录只读；涉及网络、系统设置、密钥或破坏性命令时保留确认。不要把生产密钥写进提示词、仓库或日志。
- 计划和阅读阶段使用较保守权限。
- 执行测试、安装依赖前确认来源和作用域。
- 删除、覆盖、发布、推送和外部发消息前检查目标。
- 把可重复的安全规则写入项目说明，而不是每次临时提醒。
五、用 AGENTS.md 固化项目规则
Codex 会在开始工作前读取 AGENTS.md。根目录文件适合记录全项目约定，子目录中的文件可以补充更具体的规则。
# AGENTS.md
## Commands
- Install: npm ci
- Test: npm test
- Typecheck: npm run typecheck
## Rules
- 不提交 .env
- 新接口必须包含权限检查
- 修改公共行为时同步更新 README说明应短而可验证，优先写真实命令、目录边界、检查项和禁止事项。过长的背景材料更适合放在文档中，由 AGENTS.md 指向它。
六、连接 MCP 与外部工具
MCP 可以让 Codex访问文档、GitHub、浏览器、数据库或内容系统。桌面应用、CLI 和 IDE 扩展可共享同一主机上的 MCP 配置。
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list远程 Streamable HTTP 服务可在 ~/.codex/config.toml 中配置 URL 和鉴权环境变量。密钥应保存在环境变量或密钥管理器中，不要直接写入版本库。
七、适合交给 Codex 的任务
- 理解陌生代码库并画出调用链。
- 定位错误、补充诊断并修复回归。
- 跨文件重构、接口迁移和依赖升级。
- 生成测试、审查 PR、整理发布说明。
- 创建文档、脚本、自动化和 MCP 工具。
八、常见问题
Codex 改得太多怎么办？
缩小目录和文件范围，明确“不改公共接口”，并要求先给出计划或先只读诊断。
为什么没有读取 AGENTS.md？
确认文件非空、位于项目根目录或当前目录链路中，并新开会话让说明重新加载。
如何提高长任务成功率？
给出明确完成条件，要求阶段性验证，保留测试命令，并把大任务拆成可审查的里程碑。
