OpenAI Codex 全流程指南：从认知到工程化实践
·
本文基于 OpenAI 官方文档、开源仓库源码与 2026 年 7 月最新生产环境实践编写，完整覆盖 Codex Web、CLI、桌面应用、IDE 扩展四大入口，深度拆解沙箱安全、MCP 生态、自动化技能、企业合规等全部核心功能，包含完整配置模板、命令速查、提示工程方法论与故障排查方案，是目前国内最全面的 Codex 落地参考手册。
前言：重新认识 Codex —— 从代码补全到软件工程智能体
很多开发者对 Codex 的认知还停留在「GitHub Copilot 竞品」的阶段，这是对这款产品最大的误解。Codex 不是另一个代码补全插件，而是 OpenAI 面向软件工程全流程打造的端到端 AI 智能体（Agent）。它的核心定位是「能独立在沙箱环境中完成完整开发任务的数字工程师」，而非编辑器里的辅助输入工具。
Codex 的核心定位与本质区别
| 产品 | 核心形态 | 工作粒度 | 自主性 | 典型场景 |
|---|---|---|---|---|
| GitHub Copilot | 编辑器补全插件 | 行 / 函数级 | 被动辅助，无自主执行能力 | 写代码时实时补全片段 |
| ChatGPT 编程对话 | 对话式问答 | 代码片段级 | 仅输出文本，不操作文件 | 单文件代码咨询、算法解答 |
| OpenAI Codex | 全场景 Agent 体系 | 项目 / 仓库级 | 自主读写文件、执行命令、迭代调试 | 功能开发、重构迁移、测试生成、Bug 闭环修复 |
简单来说：Copilot 帮你「写得更快」，而 Codex 帮你「把整件事做完」。一个完整的 Codex 任务链路通常是：你用自然语言描述需求 → Codex 分析代码库 → 制定修改计划 → 多文件联动修改 → 安装依赖 → 运行测试 → 根据报错迭代修复 → 最终交付可运行的代码变更。
Codex 的产品演进与能力边界
自 2025 年正式发布以来，Codex 经历了三次核心架构升级：
- 初代版本：仅支持 CLI 工具，基础代码生成与命令执行
- 2025 年 Q3 更新：推出 IDE 扩展、Web 云端版、MCP 工具协议
- 2026 年重大升级：桌面应用发布、技能系统、录制与重放、Computer Use 能力、自动化定时任务
截至 2026 年 7 月，Codex 已经形成「四位一体」的产品矩阵：CLI 命令行 + 桌面应用 + IDE 扩展 + Web 云端版，四端共享账号、会话同步、能力一致，分别适配不同的开发场景。
本文将按照「产品体系 → 基础使用 → 深度配置 → 高级功能 → 企业治理 → 故障排查」的逻辑，逐一拆解 Codex 的所有功能与最佳实践。
第一章 Codex 产品体系全解析：四大入口的功能与适用场景
Codex 不是单一工具，而是一套完整的 Agent 生态。四个客户端共享同一套模型能力和账号体系，但交互方式、适用场景和专属功能各有不同。
1.1 Codex CLI：开发者的主力工作台
CLI 是 Codex 最核心、功能最完整、灵活度最高的入口，也是绝大多数资深开发者的首选。它完全开源（仓库地址：github.com/openai/codex），支持全平台运行，能够深度集成到终端工作流中。
核心能力
- 交互式会话模式：终端内直接对话，实时查看 Agent 执行过程
- 非交互 exec 模式：单次任务执行，适合脚本和 CI 集成
- 完整的沙箱控制与审批策略配置
- 原生支持 MCP 工具扩展
- 会话持久化、分叉、压缩、恢复等全生命周期管理
- 支持管道、重定向等标准 Shell 操作
适用场景
- 日常本地开发、调试、重构
- 终端重度用户、Vim/Emacs 党
- 脚本自动化、CI/CD 流水线集成
- 服务器、远程开发环境部署
1.2 Codex 桌面应用：多 Agent 指挥中心
桌面应用（支持 macOS、Windows）是 Codex 的图形化指挥中心，专为「并行管理多个项目、委托长周期任务」设计。它不是 CLI 的简单套壳，而是拥有大量专属高级功能的独立产品。
核心专属功能
- 多线程并行任务：同时运行多个独立 Agent 任务，按项目分组管理，一个任务跑重构、另一个写测试、第三个做部署，互不干扰
- 技能系统（Skills）：内置上百种预构建工作流技能，可直接调用，例如：
- Figma 转 UI：自动读取设计稿生成像素级前端代码
- 项目管理：对接 Linear/Jira 自动分单、追踪进度
- 一键部署：自动部署到 Vercel、Cloudflare Pages、Netlify
- 文档生成：自动生成 API 文档、技术方案、PDF 报告
- 图片生成：集成 GPT Image 模型生成 UI 素材与产品图
- 录制与重放（Record & Replay）：macOS 专属功能，你手动演示一遍工作流程，Codex 自动将其转化为可重复执行的自动化技能，支持无 API 的桌面软件操作
- 自动化（Automations）：定时触发任务，例如每日凌晨自动跑测试、监控告警自动排查、Issue 自动分类回复
- 内置浏览器预览：前端开发时直接在应用内渲染页面，支持页面上直接圈选标注，AI 自动根据标注修改代码
- Computer Use：macOS 专属，Agent 可以像真人一样控制鼠标键盘，操作任意桌面应用，填写表单、操作后台系统、测试 GUI 软件
适用场景
- 多项目并行管理
- 长周期后台任务委托
- 前端开发、UI 还原工作流
- 桌面软件自动化、无 API 系统操作
- 非终端用户的图形化交互偏好
1.3 Codex IDE 扩展：编辑器内的无缝协作
IDE 扩展目前支持 VS Code 及所有兼容分支（Cursor、Windsurf、VS Code Insiders），macOS/Linux 正式支持，Windows 处于实验阶段（推荐 WSL 环境）。
三种工作模式
IDE 扩展提供三级权限模式，兼顾安全与效率：
- Chat 模式（只读）：仅对话问答，不修改任何文件，适合需求讨论、代码解释、技术方案评审
- Agent 模式（默认）：可读写工作目录内的文件、执行本地命令，访问网络或目录外资源时弹窗申请审批
- Agent（Full Access）：完全权限，自动放行网络访问和目录外操作，仅建议在可信私有项目中使用
核心特性
- 上下文自动感知：自动读取当前打开的文件、选中的代码片段，无需手动 @ 引用
- 内联 diff 预览：代码修改直接在编辑器内高亮显示，逐行审查后再应用
- 云端委托：大任务一键提交到云端沙箱运行，不占用本地资源，完成后自动同步结果
- 本地 / 云端会话无缝切换：对话上下文在 CLI、IDE、桌面端完全同步
- 自定义快捷键：支持绑定「唤起面板」「添加选中文本到上下文」「批准上一步操作」等动作
安装与登录
- 在 VS Code 扩展市场搜索「OpenAI Codex」并安装
- 点击侧边栏 Codex 图标，选择「Sign in with ChatGPT」
- 浏览器跳转授权后自动完成登录，即可使用
1.4 Codex Web 云端版：浏览器里的开发环境
访问地址：chatgpt.com/codex，无需安装任何软件，浏览器即可使用完整的 Codex Agent 能力。
核心特性
- GitHub 仓库直连：授权后直接加载 GitHub 仓库，无需克隆到本地
- 云端沙箱运行：所有任务在 OpenAI 托管的云端环境执行，不消耗本地算力
- PR 级工作流：直接基于分支创建任务，完成后自动提交 PR 到 GitHub
- 跨设备访问：任何设备打开浏览器即可继续任务，进度自动云端同步
- 协作分享：可将会话链接分享给团队成员，共同查看和调试
适用场景
- 临时查看、审查远程仓库
- 轻量任务快速处理，不想开本地环境
- 跨设备、异地办公场景
- 团队协作、任务分享与评审
1.5 四端能力对比与选择建议
| 功能维度 | CLI | 桌面应用 | IDE 扩展 | Web 云端版 |
|---|---|---|---|---|
| 代码读写与命令执行 | ✅ 完整 | ✅ 完整 | ✅ 完整 | ✅ 完整 |
| 图形化界面 | ❌ | ✅ | ✅ 内嵌 | ✅ 网页 |
| 多任务并行 | 需多终端 | ✅ 原生支持 | ❌ 单会话 | ✅ 多标签 |
| 技能系统 | 需手动配置 | ✅ 原生图形化 | ❌ | ✅ 部分支持 |
| 录制与重放 | ❌ | ✅ macOS 专属 | ❌ | ❌ |
| Computer Use | ❌ | ✅ macOS 专属 | ❌ | ❌ |
| 内置浏览器预览 | ❌ | ✅ | ❌ | ✅ |
| 本地文件系统访问 | ✅ 完整 | ✅ 完整 | ✅ 完整 | ❌ 仅连接的仓库 |
| CI / 脚本集成 | ✅ 最佳 | ❌ | ❌ | ❌ |
| 安装依赖 | 需要 | 需要 | 需要 | 无需 |
选择建议：
- 终端开发者主力用 CLI，配合 IDE 扩展做编辑器内辅助
- 多项目管理、前端开发、自动化需求选桌面应用
- 临时处理、跨设备、协作场景用 Web 版
- 四端账号互通，会话同步，建议根据当前任务灵活切换
第二章 Codex CLI 深度指南：安装、配置与全命令手册
CLI 是 Codex 功能最完整、自定义程度最高的入口，也是深入掌握 Codex 的核心。本章将从安装开始，完整拆解所有命令、参数、配置与高阶用法。
2.1 全平台安装指南
方式一：npm 全局安装（跨平台推荐）
这是最通用的安装方式，支持 macOS、Windows、Linux：
npm install -g @openai/codex
安装完成后验证：
codex --version
方式二：系统包管理器
- macOS Homebrew：
brew install --cask codex - Linux：官方提供 deb/rpm 包，也可通过 npm 安装
- Windows：推荐 npm 安装，或下载官方 MSI 安装包
方式三：源码编译安装
git clone https://github.com/openai/codex.git
cd codex
npm install && npm run build
npm link
2.2 认证登录：两种方式详解
Codex 支持两种认证模式，分别适配个人用户与企业 API 用户。
方式 A：ChatGPT OAuth 登录（个人用户首选）
codex login
执行后自动唤起浏览器，使用你的 ChatGPT 账号授权即可。
- 优势：无需管理 API Key，用量计入 ChatGPT 套餐额度
- 支持套餐：Free、Go、Plus、Pro、Business、Edu、Enterprise
- 凭据安全：默认存储在系统密钥链中，而非明文文件
方式 B：API Key 登录（企业 / 开发者模式）
codex login --api-key
按提示输入你的 OpenAI API Key。
- 优势：独立计费，灵活管控，适合企业统一结算
- 注意：API Key 按 Token 实际消耗量计费，与 ChatGPT 套餐额度独立
- 环境变量方式：设置
OPENAI_API_KEY环境变量可自动识别，无需手动登录
登出与凭据管理
codex logout # 清除本地凭据
codex auth status # 查看当前登录状态与认证方式
2.3 核心命令全集
主命令列表
| 命令 | 简写 | 功能说明 |
|---|---|---|
codex |
- | 进入交互式会话模式（默认） |
codex exec "任务描述" |
codex e |
非交互模式，执行单次任务后退出 |
codex review |
- | 代码审查模式，输出结构化审查报告 |
codex init |
- | 在当前项目初始化，自动生成 AGENTS.md 模板 |
codex resume |
- | 列出历史会话，选择恢复 |
codex resume --last |
- | 快速恢复最近一次会话 |
codex fork |
- | 分叉当前会话为独立新线程，不影响原会话 |
codex apply |
codex a |
将云端任务的 diff 应用到本地工作区 |
codex login |
- | 登录认证 |
codex logout |
- | 登出清除凭据 |
codex status |
- | 查看当前配置、模型、用量、沙箱状态 |
codex mcp |
- | MCP 工具管理命令组 |
codex config |
- | 配置管理命令组 |
codex history |
- | 会话历史管理 |
常用启动参数大全
| 参数 | 简写 | 说明 |
|---|---|---|
--model <name> |
-m |
指定使用的模型 |
--profile <name> |
-p |
指定使用的配置 profile |
--sandbox <mode> |
- | 设置沙箱模式：read-only / workspace-write / full-access |
--approval-mode <mode> |
- | 设置审批策略：never / on-request / always / untrusted |
--full-auto |
- | 全自动预设：workspace-write + on-request，低摩擦自动化 |
--dangerously-bypass-approvals-and-sandbox |
--yolo |
绕过所有审批和沙箱限制，极高风险，仅测试用 |
--cd <path> |
-C |
任务执行前切换工作目录 |
--image <path> |
-i |
附加图片作为初始上下文，支持多图 |
--search |
- | 启用联网搜索能力 |
--ephemeral |
- | 临时会话，不保存历史记录 |
--json |
- | 输出 JSON 格式结果，适合程序解析 |
--config key=value |
-c |
临时覆盖单个配置项 |
--skip-git-repo-check |
- | 允许在非 Git 仓库中运行 |
--no-alt-screen |
- | 禁用终端交替屏幕模式，适合日志重定向 |
--enable <feature> |
- | 强制启用指定特性开关 |
--disable <feature> |
- | 强制禁用指定特性开关 |
--output-schema <schema> |
- | 指定输出 JSON Schema，强制结构化输出 |
2.4 交互式会话内斜杠命令
在 Codex 交互界面中，输入 / 开头的命令可执行系统操作：
| 命令 | 功能说明 |
|---|---|
/help |
显示所有可用命令帮助 |
/model |
切换模型与推理强度 |
/mode |
快速切换审批模式 |
/sandbox |
切换沙箱运行模式 |
/new |
开启全新会话 |
/compact |
压缩当前对话上下文，节省 Token |
/diff |
显示本次会话产生的所有文件变更 diff |
/status |
查看当前会话状态、配置、用量 |
/mcp |
查看已连接的 MCP 服务器与可用工具 |
/search |
切换联网搜索开关 |
/clear |
清空终端屏幕（保留对话历史） |
/fork |
分叉当前会话 |
/save <name> |
保存当前会话为命名快照 |
/init |
为当前项目生成 AGENTS.md 模板 |
/approve |
批准当前待审批操作 |
/deny |
拒绝当前待审批操作 |
2.5 终端快捷键大全
| 快捷键 | 功能 |
|---|---|
Ctrl + C |
取消当前操作；连按两次强制退出 |
Ctrl + D |
正常退出 Codex |
Ctrl + L |
清屏，保留对话历史 |
Ctrl + G |
调用外部编辑器编辑当前 Prompt |
Ctrl + O |
复制最近一条 AI 输出到剪贴板 |
Option + Enter / Ctrl + J |
输入框内换行，不发送 |
Tab |
任务运行中查看后台任务队列状态 |
Esc Esc |
编辑上一条用户输入 |
↑ / ↓ |
浏览历史输入记录 |
Enter（任务运行中） |
向正在运行的任务注入新指令 |
2.6 六层配置优先级体系
Codex 采用多层级配置机制，优先级从高到低依次为：
- CLI 命令行参数（最高优先级，单次生效）
- 环境变量
- 项目级配置：
项目根目录/.codex/config.toml - 用户级配置：
~/.codex/config.toml - 系统级配置：
/etc/codex/config.toml（Linux/macOS） - 内置默认值（最低优先级）
高优先级配置会覆盖低优先级配置，项目级配置仅在对应目录下生效。
2.7 完整配置文件模板与详解
以下是生产环境可用的完整 config.toml 模板，包含所有官方配置项：
# ===== 基础模型配置 =====
model = "gpt-5.4" # 默认使用的模型
model_reasoning_effort = "medium" # 推理强度: minimal/low/medium/high
model_verbosity = "medium" # 回复详细程度: low/medium/high
model_temperature = 0.2 # 采样温度，编码任务建议偏低
# ===== 认证与安全 =====
preferred_auth_method = "oauth" # 优先认证方式: oauth / apikey
cli_auth_credentials_store = "keyring" # 凭据存储: keyring / file
# ===== 审批策略 =====
# 控制"什么时候问你"，与沙箱独立生效
approval_policy = "on-request" # never / on-request / always / untrusted
auto_approve_low_risk = true # 自动批准低风险操作（只读、格式化等）
approval_timeout_seconds = 300 # 审批等待超时时间
# ===== 沙箱配置 =====
# 控制"技术上最多能做什么"，是最后一道安全防线
sandbox_mode = "workspace-write" # read-only / workspace-write / full-access
[sandbox_workspace_write]
writable_roots = [] # 额外允许写入的目录列表
network_access = false # 是否允许网络访问（默认关闭）
allow_tmpdir = true # 是否允许使用系统临时目录
allow_git_operations = true # 是否允许执行 Git 命令
enable_seatbelt = true # macOS 启用内核级 Seatbelt 沙箱
[sandbox_network]
allowed_domains = [] # 白名单域名列表
blocked_domains = [] # 黑名单域名列表
allow_private_network = false # 是否允许访问内网 IP
# ===== 功能开关 =====
[features]
web_search = false # 联网搜索
memories = false # 跨会话记忆
hide_agent_reasoning = false # 隐藏 Agent 思考过程
auto_compact = true # 自动压缩长上下文
git_integration = true # Git 集成
diff_preview = true # 修改前预览 diff
multi_agent = false # 多 Agent 协作模式
# ===== 历史与会话 =====
[history]
persistence = "local" # 持久化方式: local / none / cloud
max_sessions = 50 # 最大保留会话数
max_session_age_days = 30 # 会话最大保留天数
auto_save_interval_seconds = 30 # 自动保存间隔
# ===== 项目信任等级 =====
# 可信项目减少审批弹窗，陌生项目加强安全限制
[projects]
[projects."/Users/you/work/trusted-repo"]
trust_level = "trusted"
[projects."/Users/you/Downloads/stranger-repo"]
trust_level = "untrusted"
sandbox_mode = "read-only"
approval_policy = "always"
# ===== MCP 工具配置 =====
[mcp]
auto_load_project_mcp = false # 是否自动加载项目内 MCP（安全风险）
[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
[[mcp.servers]]
name = "postgres"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
# ===== Hooks 钩子配置 =====
[hooks]
[[hooks.pre_execution]]
name = "secret-scanner"
script = "~/.codex/hooks/secret_scanner.py"
block_on_failure = true
[[hooks.post_generation]]
name = "style-check"
script = "~/.codex/hooks/eslint_check.js"
block_on_failure = false
2.8 .codexignore：上下文优化与成本控制
作用类似 .gitignore，用于指定 Codex 不需要索引和读取的文件。配置合理的 .codexignore 可以显著减少 Token 消耗、提升响应速度、避免敏感信息泄露。
生产级最佳实践模板：
# ===== 依赖目录 =====
node_modules/
vendor/
__pycache__/
.pnp
.yarn
.venv/
venv/
env/
# ===== 构建产物 =====
dist/
build/
out/
.next/
.nuxt/
.output/
.svelte-kit/
# ===== 版本控制 =====
.git/
.svn/
.hg/
# ===== 日志与缓存 =====
*.log
*.lock
*.map
coverage/
.cache/
.parcel-cache/
.turbo/
# ===== 环境与密钥 =====
.env
.env.*
!.env.example
*.pem
*.key
*.crt
id_rsa*
# ===== 大文件与二进制 =====
*.zip
*.tar.gz
*.sql
*.dump
*.bak
*.bin
*.exe
*.dll
*.so
# ===== 媒体资源 =====
*.png
*.jpg
*.jpeg
*.gif
*.mp4
*.pdf
*.psd
# ===== IDE 配置 =====
.idea/
.vscode/
*.swp
*.swo
*~
2.9 AGENTS.md：项目级行为规范
在项目根目录创建 AGENTS.md（也支持 .codex/instructions.md），Codex 启动时会自动读取并严格遵循其中的规则。这是团队统一编码规范、约束 AI 行为边界的核心文件。
企业级规范模板：
# 项目开发规范（Codex Agent 执行准则）
## 一、技术栈约束
- 前端：TypeScript 5.x + React 18 + Vite，严格启用 strict 模式
- 后端：Python 3.11 + FastAPI + Pydantic v2
- 数据库：PostgreSQL 16 + Prisma ORM
- 测试：前端 Vitest，后端 pytest
- 禁止使用任何未在本列表中的框架和库，如需新增必须先说明理由并获得批准
## 二、编码质量标准
1. **类型安全**：所有函数必须有完整类型注解，严禁使用 any 类型
2. **函数长度**：单个函数不超过 50 行，超出必须拆分
3. **错误处理**：所有异步操作、IO 操作必须有异常捕获
4. **注释规范**：公共 API 必须有 JSDoc / docstring 注释
5. **代码风格**：严格遵循项目 .eslintrc / .prettierrc 配置，提交前自动格式化
## 三、测试要求
- 新增功能必须附带单元测试，核心逻辑覆盖率不低于 85%
- 测试用例命名遵循 given-when-then 风格
- 修复 Bug 必须先补充复现测试，再修复代码
## 四、安全红线
- 绝对禁止硬编码密钥、密码、Token 等敏感信息
- 所有用户输入必须做校验和转义，禁止直接拼接 SQL
- 禁止向外部发送项目代码和数据
- 禁止修改项目目录外的任何文件
## 五、工作流程规范
1. 动手修改前，先列出计划改动的文件清单和大致方案
2. 每次提交只做一件事，保持 Commit 粒度清晰
3. 完成功能后自动运行相关测试并报告结果
4. 遇到不确定的地方，停止并询问，不要擅自猜测
5. 所有改动必须可通过 git diff 清晰审查
## 六、架构约束
- 遵循现有分层架构，不得随意新增目录层级
- 公共逻辑必须抽离到 utils 或 shared 模块，禁止重复代码
- 数据库迁移必须编写可逆脚本
2.10 全局个人指令文件
除了项目级的 AGENTS.md，你还可以配置全局个人偏好文件 ~/.codex/instructions.md，所有项目都会生效，用于定义你的个人习惯：
# 个人偏好设置
- 所有回复使用简体中文
- 代码注释使用中文
- 优先考虑可读性，其次才是性能
- 命名采用小驼峰风格
- 报错信息要详细，包含可能的原因和解决建议
第三章 模型选型与推理配置：效果、成本与速度的平衡
Codex 底层支持多款模型，不同模型在能力、速度、成本上差异巨大。选对模型可以在保证效果的前提下大幅降低成本。
3.1 官方模型矩阵详解
| 模型 | 定位 | 适用场景 | 相对成本 |
|---|---|---|---|
| gpt-5.4 | 通用旗舰 | 日常开发、多模态任务、大多数场景的首选 | 标准 |
| gpt-5.3-codex | 编程专用旗舰 | 复杂重构、深度调试、架构设计、大型代码库迁移 | 较高 |
| gpt-5.2-codex | 稳定编程版 | API 集成、长上下文任务、企业稳定环境 | 标准 |
| gpt-5.4-mini | 轻量快速版 | 简单修复、Lint 格式化、批量任务、CI 检查 | 约 1/5 |
| o3-codex | 深度推理版 | 算法难题、安全审计、极端复杂逻辑排查 | 高 |
3.2 推理强度（Reasoning Effort）
除了模型选择，推理强度也是影响质量和成本的关键参数，共四档：
- minimal：最快、最便宜，适合纯格式化、简单拼写修复、极简单问答
- low：快速响应，适合简单代码生成、单文件修改、常规问答
- medium：默认值，平衡质量与速度，适合绝大多数日常开发任务
- high：深度思考，质量最高、耗时最长、成本最高，适合复杂重构、安全审计、疑难 Bug 排查
3.3 场景化配置推荐
场景 1：日常开发，追求性价比
model = "gpt-5.4"
model_reasoning_effort = "medium"
场景 2：大型重构 / 技术迁移，追求最佳效果
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
approval_policy = "on-request"
场景 3：CI 批量任务 / Lint 自动修复，成本优先
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
approval_policy = "never"
hide_agent_reasoning = true
场景 4：代码安全审计 / 渗透测试
model = "o3-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "always"
3.4 成本优化核心技巧
- 分级使用模型：简单任务用 mini，复杂任务才上旗舰模型
- 精确控制上下文：配置完善的
.codexignore，只给必要的文件 - 及时压缩会话：长对话用
/compact压缩，减少无效历史 Token - 合并批量任务：多个小任务合并执行，减少初始化开销
- 关闭不必要功能：不需要搜索就关掉 web_search，不需要思考过程就隐藏推理
- 非交互模式批量处理：使用 exec 模式批量处理文件，比交互式更省 Token
第四章 提示工程最佳实践：让 Codex 一次做对
再好的模型，指令写不好也会产出垃圾结果。Codex 的提示工程和普通 ChatGPT 有本质区别 —— 它是执行型 Agent，指令必须具备精确性、边界感、可验证性。
4.1 高质量任务指令的五要素
反面教材（大概率返工）：
修复一下登录的 Bug
正面教材（一次通过率 90%+）：
项目是 Node.js + Express 技术栈，问题出在 src/auth/middleware.ts 第 34 行。
现象：JWT Token 过期时，接口直接返回 500 错误，而不是预期的 401。
请完成以下工作：
1. 用 try-catch 包裹 jwt.verify 逻辑，捕获 TokenExpiredError 异常
2. 过期时返回 401 状态码，响应体 { code: 40101, message: "Token expired" }
3. 其他验证失败保持原有 401 逻辑不变
4. 在 tests/auth.middleware.test.ts 中补充 2 个测试用例：过期 Token、无效 Token
5. 不要修改其他文件，不要重构无关代码
完成后自动运行 npm test auth 并报告测试结果。
核心五要素：
- 背景定位：说明技术栈、具体文件、行号、现象，避免 Codex 盲目搜索
- 目标明确：列出具体要做的事情，一项一项清晰罗列
- 边界约束：明确说清楚「不要做什么」，防止过度修改
- 验收标准：给出验证方式和通过条件
- 输出要求：指定完成后的动作（跑测试、生成报告等）
4.2 高频场景 Prompt 模板
模板一：代码审查
审查 @src/services/user.service.ts 文件，从以下维度输出结构化报告：
1. 逻辑正确性：是否有明显 Bug、边界条件遗漏
2. 类型安全：类型定义是否完善，有无隐式 any
3. 性能问题：有无 O(n²) 循环、不必要的重复计算
4. 安全风险：注入风险、敏感信息泄露、权限绕过
5. 代码规范：是否符合项目编码风格
按严重程度（高危/中危/低危/建议）分级，每个问题给出具体行号和修改建议。
模板二：单元测试生成
为 @src/utils/date.ts 中的所有导出函数编写单元测试，使用 Jest 框架。
要求：
- 覆盖正常分支、边界值、异常输入、空值场景
- 测试用例命名遵循 given-when-then 风格
- 每个测试独立，不依赖执行顺序
- 不要修改原文件，测试文件写入 tests/utils/date.test.ts
模板三：Bug 定位与修复
用户反馈提交表单后偶发数据丢失，复现路径：快速连续点击两次提交按钮。
相关文件：
- @src/pages/SubmitForm.tsx
- @src/hooks/useSubmit.ts
请按以下步骤执行：
1. 先分析代码，列出 3 个最可能的根本原因假设
2. 逐一验证你的假设，给出验证结论
3. 选择最可能的原因进行修复
4. 补充对应的防重复提交测试用例
模板四：功能开发
在现有项目基础上新增一个「密码重置」功能，技术栈是 React + Node.js + PostgreSQL。
需求详情：
1. 后端：新增 /api/auth/reset-password 接口，接收邮箱，发送重置链接（Token 有效期 1 小时）
2. 后端：新增 /api/auth/set-new-password 接口，验证 Token 后更新密码
3. 前端：新增重置密码页面和设置新密码页面
4. 数据库：编写 Prisma migration，无需改动现有表结构
约束：
- 遵循现有项目的代码风格和目录结构
- 所有接口要有参数校验
- Token 使用 JWT，存储在 Redis 中做黑名单
- 不要引入新的第三方依赖
完成后列出所有改动的文件清单。
4.3 进阶技巧：提升效率与准确率
- @ 引用精确制导：用
@路径/文件名直接引用文件，Codex 会优先读取，避免全局搜索浪费时间和 Token。支持相对路径和绝对路径。 - 分步拆解大任务：超过 3 个文件改动的大任务，拆成 2-3 步执行，每步确认后再继续，避免跑偏后大面积返工。
- 提供完整报错信息：把终端完整的报错堆栈直接粘贴进去，定位效率提升数倍，不要只说「报错了」。
- 先计划后执行：复杂任务先让 Codex 输出「实施方案和改动文件清单」，你确认没问题后再让它动手修改。
- 善用否定指令：明确说「不要重构」「不要改其他文件」「不要引入新依赖」，防止 AI 画蛇添足。
- 注入中间指令：任务运行中按 Enter 可以直接输入新指令，随时纠正方向，不用等任务跑完。
4.4 常见误区避坑
- ❌ 误区一：描述过于抽象，全是业务黑话，没有技术细节
- ❌ 误区二：边界不清，只说要做什么，不说不能做什么
- ❌ 误区三：任务粒度过大，一次丢给它整个系统重构
- ❌ 误区四：只给需求不给上下文，让 AI 凭空猜
- ✅ 正确思路：把 Codex 当成初级工程师来带，交代清楚背景、目标、约束和验收标准
第五章 沙箱安全机制深度拆解
沙箱是 Codex 最核心的安全基础设施，也是很多开发者最容易误解的部分。它不是简单的权限提示，而是内核级的强制隔离机制，是保障你系统安全的最后一道防线。
5.1 核心概念：审批策略 ≠ 沙箱机制
很多人会把「审批弹窗」当成安全保障，这是错误的。两者是完全独立的两个维度：
- 审批策略：控制「要不要问你」，属于交互层面的流程控制
- 沙箱机制：控制「技术上能不能做到」，属于操作系统内核级的强制限制
即使你把审批策略设为 never（永远不问），沙箱依然会强制阻止越权操作。两者组合生效，构成纵深防御体系。
5.2 三种沙箱模式详解
| 模式 | 文件权限 | 网络权限 | 适用场景 |
|---|---|---|---|
| read-only（只读） | 只能读取工作目录文件，不能修改、删除、创建任何文件 | 默认关闭 | 陌生代码库审查、代码分析、学习开源项目 |
| workspace-write（工作区读写） | 仅能读写当前工作目录内的文件，目录外完全不可见 | 默认关闭，可单独开启 | 日常开发、绝大多数场景的默认选择 |
| full-access（完全访问） | 可访问整个文件系统、执行任意命令 | 默认开启 | 系统级操作、安装全局软件，极高风险 |
5.3 跨平台沙箱技术实现
Codex 的沙箱不是用户态模拟，而是基于各平台原生安全机制实现的内核级隔离，子进程自动继承限制，无法通过 fork 逃逸。
macOS：Seatbelt（SBPL）
- 基于 macOS 原生的 Sandbox 框架，内核层强制拦截
- 默认禁止网络访问、限制文件读写范围
- 禁止权限提升、禁止加载内核扩展
- 子进程自动继承沙箱策略
Linux：Bubblewrap + Landlock + Seccomp
- Bubblewrap：提供文件系统挂载隔离、PID 命名空间
- Landlock：内核级文件系统访问控制
- Seccomp：系统调用白名单，禁止危险系统调用
- 三层叠加，任何一层被绕过都不会完全失守
Windows：受限账户 + DACL + 防火墙
- 创建两个专用本地账户：CodexSandboxOffline（无网）和 CodexSandboxOnline（有网）
- SID 级别的 DACL 权限控制，精确限制可写入目录
- Windows 防火墙基于账户身份隔离网络访问
- DPAPI 保护凭据存储，沙箱内无法读取
5.4 网络访问控制
默认情况下，workspace-write 模式是禁止网络访问的，这是很多新手踩坑的地方 —— 执行 npm install、pip install 会失败，不是 Codex 坏了，是沙箱挡住了。
开启网络访问的两种方式：
- 临时开启：启动时加参数
--enable network_access - 永久配置：在 config.toml 中设置
network_access = true
精细化网络控制：
[sandbox_network]
allowed_domains = ["registry.npmjs.org", "pypi.org"]
blocked_domains = ["*.example.com"]
allow_private_network = false
5.5 项目信任等级
Codex 会自动识别 Git 仓库的可信度，对陌生仓库自动提升安全等级：
- 可信项目：你自己创建的、本地长期开发的仓库，使用正常默认配置
- 不可信项目：刚下载的第三方开源项目、陌生来源的代码，自动降级为
read-only沙箱 +always审批策略
你也可以手动在配置中指定项目信任等级：
[projects."/path/to/repo"]
trust_level = "trusted" # trusted / untrusted / unknown
5.6 安全最佳实践
- 陌生代码先只读：下载的开源项目、第三方代码，先用
read-only模式分析，确认没问题再放开写权限 - 日常用工作区模式：绝大多数场景
workspace-write足够，永远不要默认开full-access - 网络按需开启：需要装依赖的时候临时开网络，装完关掉，不要常开
- 永远不要用 root 运行：不要用 sudo 运行 Codex，否则沙箱隔离意义大打折扣
- 重要项目开启审批：核心生产仓库建议设为
on-request审批模式，关键操作人工确认 - 禁用项目自动加载 MCP：
auto_load_project_mcp保持关闭，防止恶意仓库通过 MCP 逃逸
第六章 MCP 生态：扩展 Codex 的能力边界
MCP（Model Context Protocol，模型上下文协议）是 OpenAI 主推的 AI Agent 工具标准，让 Codex 可以连接外部系统、调用第三方工具、获取实时数据。掌握 MCP，才能真正发挥 Codex 的 Agent 潜力。
6.1 MCP 是什么
简单理解：MCP 就是 AI Agent 的「插件协议」。符合 MCP 标准的服务（MCP Server）可以无缝接入 Codex，让 Agent 获得新的能力，比如查数据库、操作 GitHub、调用云服务、读取本地文件系统之外的资源。
MCP 支持两种运行方式：
- STDIO 模式：本地子进程运行，性能最好，适合本地工具
- HTTP 模式：远程服务，适合云端 API、团队共享服务
6.2 MCP 常用命令
# 列出已配置的 MCP 服务器
codex mcp list
# 添加一个 STDIO 类型 MCP
codex mcp add github -- npx -y @modelcontextprotocol/server-github
# 添加一个 HTTP 类型 MCP
codex mcp add my-server --url https://mcp.example.com
# 移除 MCP 服务器
codex mcp remove github
# 测试 MCP 连接
codex mcp test github
# 查看某个 MCP 提供的工具列表
codex mcp tools github
6.3 常用 MCP 服务器推荐
1. GitHub MCP
让 Codex 直接操作 GitHub：查看 Issue、评论 PR、创建分支、合并代码
codex mcp add github -- npx -y @modelcontextprotocol/server-github
使用示例：「查看 issue #123 的详情，分析问题原因，然后在 PR #456 下评论修复方案」
2. PostgreSQL MCP
让 Codex 直接查询数据库表结构、执行 SQL、分析数据
codex mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost:5432/db
使用示例：「分析 user 表的数据分布，找出注册量最高的 10 天，生成统计 SQL」
3. Filesystem MCP
扩展访问指定目录，突破默认工作区限制（谨慎使用）
codex mcp add docs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
4. Figma MCP
读取 Figma 设计稿，自动生成前端代码
codex mcp add figma -- npx -y @modelcontextprotocol/server-figma
5. Playwright MCP
自动化浏览器操作，做端到端测试、网页抓取
codex mcp add playwright -- npx -y @modelcontextprotocol/server-playwright
6.4 配置文件中声明 MCP
在 config.toml 中持久化配置 MCP 服务器：
[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
[[mcp.servers]]
name = "internal-api"
url = "https://mcp.company.internal"
headers = { Authorization = "Bearer xxx" }
6.5 MCP 安全注意事项
- 最小权限原则：只给 MCP 服务器它需要的权限，比如数据库账号只给查询权限
- 不信任项目内 MCP：永远不要开启
auto_load_project_mcp，恶意仓库可以植入 MCP 执行任意代码 - 敏感信息走环境变量：Token、密码不要写死在配置里，用环境变量注入
- 定期审查 MCP 列表：不用的 MCP 及时移除，减少攻击面
第七章 高级功能全解析：从工具到智能体
本章介绍 Codex 的进阶功能，这些功能是它区别于普通代码助手的核心竞争力，也是真正提升生产力的关键。
7.1 录制与重放（Record & Replay）
这是桌面应用的王牌功能（目前仅 macOS 支持）。你不需要写任何代码，只要手动操作一遍电脑上的工作流程，Codex 就会自动记录你的鼠标点击、键盘输入、窗口切换，然后转化为可重复执行的自动化技能。
典型应用场景
- 无 API 的企业后台系统批量操作
- 设计软件、办公软件的重复工作流
- 跨多个桌面应用的复杂流程
- 测试人员录制复现 Bug 的操作路径
使用方式
- 打开 Codex 桌面应用，点击顶部「Record」
- 选择录制范围（全屏 / 特定应用），点击开始
- 正常操作你的软件，完成后点击停止
- Codex 自动生成可重放的技能，可命名保存
- 后续只需一句话即可触发执行整个流程
7.2 技能系统（Skills）
技能是预封装的完整工作流，相当于 Codex 的「专业插件包」。内置上百种官方技能，也支持自定义和团队共享。
官方内置技能分类
- UI 开发类：Figma 转代码、设计稿还原、响应式适配、无障碍优化
- 部署运维类：Vercel 部署、Cloudflare Pages 发布、Docker 镜像构建、服务器部署
- 项目管理类：Jira 工单处理、Linear 需求拆分、Issue 自动分类、PR 审查
- 文档生成类：API 文档自动生成、技术方案编写、Changelog 生成、PDF 报告导出
- 数据处理类：CSV 分析、SQL 生成、图表生成、数据清洗
- 图片素材类：UI 图标生成、产品图制作、海报设计、图片裁切优化
调用方式
- 显式调用：「使用 Figma 转 UI 技能，把这个设计稿转换成 React 组件」
- 自动调用：Codex 会根据任务描述自动判断并调用合适的技能
7.3 自动化（Automations）
自动化功能让 Codex 可以在后台无人值守运行，定时触发、事件触发执行任务。
触发方式
- 定时触发：Cron 表达式，每日、每周、每小时固定时间执行
- 事件触发：GitHub Webhook、Slack 消息、告警系统触发
- 轮询触发：定期检查某个状态，满足条件则执行任务
典型应用场景
- 每日凌晨自动跑全量测试，失败自动告警
- 监控线上错误日志，出现异常自动排查并生成修复建议
- 新 Issue 提交自动分类、打标签、指派负责人
- 定期扫描代码库安全漏洞，生成安全报告
7.4 Computer Use（计算机控制）
macOS 专属的高级能力，Codex Agent 可以像真人一样控制鼠标和键盘，操作任意桌面应用，突破 API 的限制。
能力范围
- 打开 / 关闭应用程序
- 点击按钮、拖动滑块、输入文字
- 操作无 API 的老旧系统、企业后台
- 测试 GUI 桌面应用、游戏
- 跨应用串联工作流
安全限制
- 每次操作前都会申请权限
- 操作过程全程可监控、可随时终止
- 默认无法读取密码输入框、系统偏好设置等敏感区域
- 不会在你使用电脑时自动接管，必须显式触发
7.5 内置浏览器与可视化标注
桌面应用和 Web 版都内置浏览器，专为前端开发优化：
- 修改代码后自动热重载预览
- 直接在页面上圈选、标注、写评论
- AI 自动根据页面标注定位代码并修改
- 支持多设备尺寸切换测试响应式
- 支持控制台日志、网络请求查看
7.6 云端委托与并行任务
对于耗时很长的大任务（比如全仓库重构、跑全量测试），你可以委托到云端运行：
- 不占用本地 CPU、内存、网络
- 后台运行，你可以关掉本地终端去做别的事
- 完成后自动通知，diff 一键同步到本地
- 支持同时运行多个云端任务，并行处理
7.7 会话管理高级用法
会话分叉（Fork）
对当前会话创建分支，尝试不同的解决方案，对比效果，不影响原会话。适合 A/B 测试不同实现方案。
# 交互内执行
/fork
会话压缩（Compact）
长对话会消耗越来越多 Token，用压缩命令让 AI 总结历史，保留核心信息，大幅减少 Token 占用。
/compact
会话快照
重要节点保存快照，后续可以随时回退到这个状态。
/save milestone-1
7.8 多模态输入能力
Codex 支持图片输入，你可以直接发截图、设计稿、架构图，AI 能看懂图片内容并据此写代码。
使用场景
- 截个报错图，让它分析修复
- 发一张 UI 设计稿，让它还原成代码
- 画一张架构图，让它按图搭建项目骨架
- 拍一张白板手写需求，让它转化为技术方案
CLI 中使用
codex -i screenshot.png "根据这个报错修复 Bug"
第八章 企业级部署与合规治理
对于企业团队而言，Codex 的价值不仅是提效，更重要的是安全、可控、可审计。本章介绍企业部署的完整方案。
8.1 企业适用套餐
| 套餐 | 适用规模 | 核心企业特性 |
|---|---|---|
| Business | 中小团队（2-100 人） | 团队管理、数据不用于训练、基础审计 |
| Edu | 教育机构 | 学术授权、批量账号、教育专属额度 |
| Enterprise | 大型企业 | 专属部署、SLA、HIPAA/BAA、定制化、SSO |
8.2 核心企业安全能力
1. 数据隐私与零保留
- Business 及以上套餐默认不将用户输入输出用于模型训练
- Enterprise 可开启零数据保留（Zero Data Retention），请求处理完立即删除
- 代码不上传公开训练集，符合企业数据保密要求
2. 身份与访问管理
- 支持 SSO 单点登录（SAML/OIDC）
- 角色权限控制（RBAC）：管理员、开发者、只读用户
- IP 白名单限制，仅允许企业内网访问
- 强制 MFA 多因素认证
3. 审计与合规
- 完整的操作审计日志，记录所有 Agent 行为
- 支持通过 Compliance API 导出日志，接入企业 SIEM 系统
- 合规认证：SOC 2 Type II、ISO 27001、ISO 27701、HIPAA BAA
- 数据驻留选项：可指定数据处理的地理区域
8.3 企业部署模式
模式一：本地部署（客户端模式）
每个开发者电脑安装 Codex CLI / 桌面应用 / IDE 扩展，统一企业账号登录。
- 优势：部署简单，体验完整，代码不离开本地
- 适合：绝大多数企业，代码敏感、不能出内网的场景
模式二：云端托管模式
使用 Web 版 + GitHub 企业版集成，统一在云端管理。
- 优势：集中管控，无需本地安装，跨设备访问
- 适合：分布式团队、轻量开发场景
模式三：私有部署（Enterprise 专属）
部署在企业私有云或 VPC 内，完全隔离公网。
- 优势：最高安全等级，数据完全自留
- 适合：金融、医疗、政府等强监管行业
8.4 团队统一配置方案
企业可以通过全局配置统一所有开发者的 Codex 行为：
- 系统级配置文件：部署到所有开发机的
/etc/codex/config.toml，强制安全基线 - 项目级 AGENTS.md：纳入代码仓库版本控制，统一团队编码规范
- 企业内部 MCP 服务：统一部署内部系统的 MCP 服务，比如内部数据库、运维平台
- 集中审计日志：所有操作日志汇总到企业日志平台
8.5 合规风险与应对建议
| 风险点 | 影响 | 应对措施 |
|---|---|---|
| 敏感代码泄露 | 核心知识产权泄露 | 升级企业套餐，开启零数据保留；本地部署，代码不上传云端 |
| 开源版权风险 | 生成代码可能与开源项目重合 | 启用代码合规扫描，重要项目做版权查重 |
| 安全漏洞引入 | AI 生成代码可能存在安全缺陷 | 强制人工审核 + 自动化安全扫描流水线 |
| 监管合规要求 | 金融、医疗等行业数据合规 | 选择 Enterprise 套餐，签署 BAA/DPA |
| 过度权限风险 | Agent 误操作破坏生产环境 | 严格沙箱限制，生产环境只读模式 |
第九章 CI/CD 集成与 Hooks 机制
Codex 不是只能交互式使用，还可以深度集成到开发流水线中，实现全自动化的代码处理。
9.1 非交互 exec 模式
codex exec 是自动化集成的核心，执行完任务自动退出，适合脚本和 CI 调用。
基础用法
codex exec "自动修复 src 目录下所有的 ESLint 错误"
CI 环境常用参数组合
codex exec \
--full-auto \
--sandbox workspace-write \
--ephemeral \
--json \
"运行 eslint --fix 修复所有可自动修复的问题，然后输出修复报告"
9.2 典型 CI 集成场景
场景 1：PR 自动代码审查
在 GitHub Actions 中添加步骤：
- name: Codex Code Review
run: |
codex review \
--diff origin/main...${{ github.sha }} \
--json \
--output review-report.json
场景 2：自动修复 Lint 问题
# 自动修复并提交
codex exec --full-auto "运行 prettier --write 格式化所有代码"
git add .
git commit -m "auto: format code by codex"
场景 3：测试失败自动排查
# 跑测试，失败则让 Codex 分析原因
npm test > test-output.txt 2>&1
if [ $? -ne 0 ]; then
codex exec -i test-output.txt "分析测试失败原因，给出修复建议"
fi
9.3 Hooks 钩子系统
Codex 支持钩子机制，可以在 Agent 执行流程的特定节点插入自定义脚本，实现企业自定义规则校验。
支持的钩子阶段
- pre_execution：命令执行前，可用于密钥扫描、敏感词检测
- post_generation：代码生成后、写入文件前，可用于风格检查、安全扫描
- pre_commit：Git 提交前，可用于提交信息规范校验
- post_session：会话结束后，可用于日志上报、用量统计
示例：密钥扫描钩子
Python 脚本 secret_scanner.py：
import re
import sys
def scan(content):
secret_pattern = r'AKIA[0-9A-Z]{16}'
matches = re.findall(secret_pattern, content)
if matches:
print(f"检测到疑似 AWS 密钥: {matches}", file=sys.stderr)
sys.exit(1)
sys.exit(0)
if __name__ == "__main__":
with open(sys.argv[1]) as f:
scan(f.read())
配置到 config.toml：
[[hooks.pre_execution]]
name = "aws-secret-scanner"
script = "/opt/codex/hooks/secret_scanner.py"
block_on_failure = true
9.4 远程任务监控
长耗时任务可以通过 ChatGPT 手机 App 远程监控和操控：
- 实时查看任务进度和日志
- 接收任务完成 / 失败通知
- 远程注入指令，调整任务方向
- 批准敏感操作，无需守在电脑前
第十章 故障排查与性能优化
10.1 常见错误速查表
| 错误现象 | 可能原因 | 解决方法 |
|---|---|---|
command not found: codex |
安装失败，npm 全局路径未加入 PATH | 重装 npm 包，检查 npm root -g 所在目录是否在 PATH 中，重启终端 |
401 Unauthorized |
登录过期、API Key 无效 | 执行 codex login 重新登录，检查 API Key 是否正确且未过期 |
429 Too Many Requests |
额度用尽、调用频率超限 | 升级套餐，购买点数，降低调用频率，等待额度重置 |
403 Forbidden |
账号无权限、地区限制、IP 被封禁 | 确认套餐包含 Codex，检查网络环境和 IP 地区 |
permission denied |
沙箱拦截、文件系统权限不足 | 确认沙箱模式是否允许写入，不要用 sudo 运行 Codex |
| npm install /pip install 失败 | 沙箱默认关闭网络 | 开启 network_access = true 或加 --enable network_access 参数 |
| 终端卡死无响应 | 交互式命令阻塞、死循环 | 连按两次 Ctrl+C 强制终止，查看日志定位问题 |
| 只聊天不修改文件 | 沙箱只读模式、未授权工作区 | 检查沙箱模式，确认项目已被标记为可信 |
| 大项目经常跑偏、改无关文件 | 上下文过大、指令不精确 | 使用 @ 精确指定文件，明确约束边界，拆分大任务 |
| MCP 工具不显示 | 配置错误、服务启动失败 | 执行 codex mcp test <name> 检查连接状态 |
10.2 性能优化指南
1. 上下文优化
- 完善
.codexignore，排除所有无关文件 - 用
@精确引用文件，不要让 AI 全局搜索 - 长会话及时
/compact压缩 - 单个会话聚焦一个主题，不要混太多不相关内容
2. 速度优化
- 简单任务用轻量模型（gpt-5.4-mini）和低推理强度
- 关闭不需要的功能：web_search、思考过程展示
- 本地执行比云端委托响应更快
- 批量任务合并执行，减少多次初始化开销
3. 额度节省技巧
- 分级使用模型，不要所有任务都用最贵的
- 开启自动压缩，减少无效 Token
- 临时会话用
--ephemeral，不保存历史 - 重复性工作做成技能或自动化，减少重复描述
- 善用 AGENTS.md，把不变的规则写进去，不用每次 Prompt 重复
10.3 紧急故障处理
如果 Codex 出现异常行为（死循环、越权操作、异常修改）：
- 立即终止：连按两次
Ctrl + C强制终止当前任务 - 进程查杀：如果无效，执行
pkill -f codex杀所有相关进程 - 回滚改动：执行
git checkout .回滚所有未提交的文件修改 - 降级模式：切换到
read-only沙箱模式，排查问题 - 上报问题：收集日志（
~/.codex/logs/），反馈给官方
10.4 日志与调试
- 日志位置：
~/.codex/logs/ - 开启调试模式：
CODEX_DEBUG=1 codex - 查看当前配置：
codex status - 查看沙箱详情：交互内执行
/sandbox status
第十一章 实战案例：从零到一完成一个完整功能
下面通过一个真实案例，演示 Codex 的完整工作流。
任务背景
现有一个 Python FastAPI 项目，需要新增一个「用户头像上传」功能。
步骤 1：初始化与规划
进入项目目录，启动 Codex，先做需求对齐：
@项目是 FastAPI + SQLAlchemy + PostgreSQL，现在需要新增用户头像上传功能。
先不要写代码，帮我做方案设计：
1. 技术选型：用什么方式存储、图片怎么处理、权限怎么控制
2. 改动文件清单
3. 可能的风险点和注意事项
→ 等待 Codex 输出方案，人工确认方案合理。
步骤 2：数据库层开发
确认方案后分步执行：
很好，就按这个方案来。
第一步：编写数据库 migration，给 user 表增加 avatar_url 字段，写入 alembic 迁移文件。
不要改其他地方。
→ 执行完成后审查 migration 文件。
步骤 3：后端接口开发
第二步：实现上传接口。
要求：
- 接口：POST /api/users/avatar
- 鉴权：JWT 登录用户才能上传
- 限制：最大 2MB，仅支持 jpg/png/webp
- 处理：压缩到 200x200 像素，保存到本地 uploads 目录
- 返回头像的访问 URL
- 同时更新 user 表的 avatar_url 字段
参考现有的文件上传工具类 @app/utils/file.py
→ 审查代码逻辑、错误处理、权限校验。
步骤 4：测试与验证
第三步：为这个接口编写单元测试，覆盖正常上传、格式错误、超大文件、未登录四种场景。
写完自动运行 pytest 测试，确保全部通过。
→ 查看测试结果，如有失败让 Codex 自动迭代修复。
步骤 5：收尾与审查
最后：
1. 列出本次所有改动的文件
2. 做一次代码自审，看看有没有安全问题和 Bug
3. 生成一份简短的功能说明文档
整个过程大约 5-10 分钟，从数据库到接口到测试全部完成，你只需要做决策和审查，具体编码工作全部由 Codex 执行。
第十二章 总结与高效使用方法论
12.1 Codex 高效使用的五条核心原则
-
安全第一，权限最小化 从只读开始，逐步放开权限。日常开发用 workspace-write，网络按需开启，永远保留人工审核的最后一道关。Codex 是工具，不是主人。
-
指令越精确，效率越高 把 Codex 当成一个执行力很强但不会主动思考的初级工程师。背景、目标、边界、验收标准，交代得越清楚，返工越少，一次通过率越高。
-
分层使用，降本增效 不要杀鸡用牛刀。格式化、Lint 修复用 mini 模型；日常开发用标准模型；复杂重构、安全审计才上旗舰模型 + 高强度推理。
-
规则前置，减少重复 把团队规范、项目架构、编码标准写进 AGENTS.md 和配置文件，让 Codex 自动遵守，不用每次写 Prompt 都重复一遍。
-
人机协作，各擅所长 Codex 擅长执行、编码、查错、重复劳动；人负责架构设计、需求判断、业务决策、质量把关。不要让 AI 替你做关键决策，也不要自己去做重复的体力活。
12.2 不同角色的使用建议
- 初级开发者：用它学习代码、理解项目、辅助写代码，边用边学，提升成长速度
- 中级开发者：用它处理重复劳动、写测试、修 Bug、做重构，专注核心逻辑
- 高级开发者 / 架构师：用它做方案落地、代码审查、技术调研，把精力放在架构和设计上
- 团队负责人：建立团队规范，统一 AGENTS.md，管控安全合规，提升整体团队效率
12.3 未来展望
Codex 还在高速迭代，未来的演进方向非常清晰：
- 更强的多 Agent 协作，多个专业 Agent 配合完成大型项目
- 更深度的 IDE 集成，真正做到「自然语言驱动开发」
- 更完善的企业治理能力，满足更多行业合规要求
- 更丰富的技能生态，覆盖研发全流程
可以预见的是，AI Agent 不会取代程序员，但会用 AI Agent 的程序员，会显著拉开和不会用的人的效率差距。越早掌握这套工具，就能越早享受到技术红利。
附录
A. 官方资源链接
- 官方首页：https://openai.com/codex
- Web 版入口：https://chatgpt.com/codex
- CLI 开源仓库：https://github.com/openai/codex
- 官方帮助中心：https://help.openai.com/
B. 版本说明
本文基于 2026 年 7 月最新版本编写。Codex 迭代速度很快，建议关注官方更新日志。核心的 CLI 命令、配置体系、沙箱机制相对稳定，桌面端的高级功能可能会有调整。
这里是“一人公司”的成长家园。我们提供从产品曝光、技术变现到法律财税的全栈内容，并连接云服务、办公空间等稀缺资源，助你专注创造，无忧运营。
更多推荐
4
0- 0
已为社区贡献2条内容
所有评论(0)