Codex 团队开发入门到精通学习资料
本文档面向希望用 Codex 开展日常项目开发的工程师与团队，内容涵盖入门基础、学习练习、精通进阶、扩展应用四个层次，并附带常用命令速查表。建议按章节顺序学习，先打牢基础，再通过练习巩固，最后在团队项目中实践精通与扩展部分。
编程资源
https://pan.quark.cn/s/7f7c83756948
更多资源
https://pan.quark.cn/s/bda57957c548
阅读约定：文中命令以
$开头表示在终端执行；#开头为注释或说明文字。代码块标注了语言以便阅读。
一、入门基础
1.1 Codex 是什么
Codex 是云端软件工程智能体（AI Agent），能够自主理解、编写、调试与审查代码，并可以并行处理多项开发任务。其官方定位是 “One agent for everywhere you code”——一个可以在你编码的任何地方工作的智能体。
它更像一名能够独立完成开发任务的工程师，而不只是一个"问答机器人"。你可以把需求描述给它，它会主动读代码、改文件、跑命令，直到任务完成。
说明：自 2026 年 7 月起，Codex 已并入 ChatGPT，成为 ChatGPT 内的一个应用入口，但原有的 CLI、IDE 插件等使用方式依然保留。
1.2 适合人群与基础要求
适合阅读本资料的人：
- 已学习过至少一门编程语言（如 JavaScript / Python / Java / Go）
- 能看懂基础语法、函数、条件判断和循环
- 写过简单项目或练习代码
- 希望借助 AI 提升开发效率与工程能力
- 独立开发者，或需要长期维护项目的工程师
- 技术负责人、团队核心成员
使用前建议具备的能力：
- 基础编程能力（能读懂并编写简单代码）
- 基本的代码阅读与理解能力
- 会使用常见开发工具（编辑器、命令行）
- 愿意理解代码，而不是完全依赖 AI 产出
1.3 四种使用方式
Codex 提供四种使用方式，满足不同场景需求：
| 方式 | 说明 | 适用场景 |
|---|---|---|
| App（桌面应用） | macOS / Windows 桌面客户端 | 完整功能、多项目并行 |
| IDE 扩展 | VS Code、Cursor、Windsurf 插件 | 深度集成开发环境 |
| CLI（命令行） | 终端交互式工具 | 终端爱好者、脚本自动化 |
| Web（云端） | 网页版 | 远程访问、并行任务 |
1.4 五大核心能力
| 能力 | 说明 |
|---|---|
| 编写代码 | 描述想构建的功能，Codex 生成匹配意图的代码，自动适应项目结构和规范 |
| 理解代码库 | 阅读和解释复杂或遗留代码，帮助快速熟悉陌生项目 |
| 代码审查 | 分析代码识别潜在 Bug、逻辑错误和未处理的边缘情况 |
| 调试修复 | 追踪失败、诊断根因、提供针对性的修复方案 |
| 自动化任务 | 执行重复性工作流：重构、测试、迁移、项目设置等 |
1.5 与传统 AI 编程工具的区别
| 对比维度 | Codex | 传统对话式 AI |
|---|---|---|
| 工作模式 | 主动执行循环（模型 + 操作） | 单次对话回答 |
| 文件操作 | 可读取、创建、修改项目文件 | 仅提供建议，不操作文件 |
| 命令执行 | 可在沙箱中运行 Shell 命令 | 不执行命令 |
| 项目理解 | 深度理解整个代码库结构 | 仅基于对话上下文 |
| 任务完成 | 自动执行直到完成 | 需要人工复制粘贴 |
1.6 适用计划（选型参考）
Codex 包含在多种订阅计划中，团队可按预算与合规要求选择：
| 计划 | 价格 | Codex 功能 |
|---|---|---|
| Free | 免费 | 探索 Codex、快速编码任务 |
| Plus | $20/月 | Web、CLI、IDE、云端集成、主流模型 |
| Pro | $200/月 | 10x–20x 更高限额、优先处理、Spark 模型 |
| Business | 按用量付费 | 更大 VM、SAML SSO、MFA |
| Enterprise | 联系销售 | SCIM、EKM、RBAC、审计日志、数据驻留 |
1.7 核心概念
理解以下概念是使用 Codex 的基础。
Prompt（提示词）
你通过发送 Prompt 与 Codex 交互，描述想要它完成的任务。提交后，Codex 进入工作循环：调用模型理解任务 → 执行模型指示的操作（读文件、改代码、跑命令）→ 将结果反馈给模型 → 循环直到完成或你取消。
有效 Prompt 的原则：
| 原则 | 说明 | 示例 |
|---|---|---|
| 包含验证步骤 | Codex 能验证工作时输出质量更高 | “写一个函数，并包含测试用例验证它处理空列表” |
| 拆解复杂任务 | 小任务更易测试和审查 | “第一步：创建模型；完成后告诉我再继续第二步” |
| 提供上下文 | 引用相关文件和图片 | “参考 src/auth.py 的风格，实现类似功能” |
Thread（线程/会话）
Thread 是单个任务会话：你的 Prompt 加上后续的模型输出与工具调用。
- 本地线程：在你的机器沙箱内运行，可读写文件、使用现有工具、执行命令。
- 云端线程：在云端隔离环境克隆仓库运行，适合并行任务、跨设备委派。
注意：运行中的线程可以并发，但避免两个线程同时修改同一文件；线程可稍后通过继续 Prompt 恢复；长时间任务可能自动压缩上下文。
Context（上下文）
提交 Prompt 时包含的、Codex 可使用的上下文——对相关文件和图片的引用。来源包括：IDE 扩展自动包含打开的文件与选中文本、手动在 Prompt 中引用路径或图片、对话历史。所有信息须适合模型上下文窗口，接近上限时会被提示；长任务会自动 Compact（压缩）以释放空间。
Sandbox（沙箱）
安全隔离机制，防止意外修改工作区外的文件。模式如下：
| 模式 | 文件修改 | 网络访问 | 适用场景 |
|---|---|---|---|
| Read-only | 禁止 | 禁止 | 只读分析、代码审查 |
| Workspace-write | 仅工作区 | 禁止 | 日常开发（默认） |
| Full-access | 允许 | 允许 | 完全信任的环境（谨慎使用） |
Approval Policy（审批策略）
控制 Codex 执行操作前是否需要确认：
| 策略 | 说明 | 行为 |
|---|---|---|
| ask | 每次询问 | 敏感操作前请求确认（默认） |
| approve | 自动批准 | 自动执行，无需确认（谨慎使用） |
| deny | 自动拒绝 | 拒绝所有可能产生副作用的操作 |
1.8 安装与配置
Codex CLI 由 Rust 编写，轻量高效，支持 macOS、Linux 与 Windows（实验性，建议 WSL2）。
方式一：npm 全局安装（推荐）
# 安装
npm install -g @openai/codex
# 验证
codex --version
# 国内镜像加速
npm install -g @openai/codex --registry=https://registry.npmmirror.com
方式二：Homebrew 安装（macOS）
brew install codex
方式三：GitHub Release 二进制
下载对应平台压缩包后解压，加入 PATH：
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl codex
sudo mv codex /usr/local/bin
常见版本：codex-aarch64-apple-darwin.tar.gz（Mac Apple Silicon）、codex-x86_64-apple-darwin.tar.gz（Mac Intel）、codex-x86_64-unknown-linux-musl.tar.gz（Linux）。
方式四：IDE 插件
在 VS Code / Cursor / Windsurf 的插件市场搜索 “Codex” 安装，登录账号即可在编辑器内使用。
Codex 应用（桌面/Web）
直接下载桌面应用或访问网页版，登录 ChatGPT 账号即可使用，无需本地安装运行环境。
登录认证
首次运行 codex 会引导认证，有三种方式：
- ChatGPT 登录（推荐）：运行
codex，选择 “Sign in with ChatGPT”，浏览器打开登录页完成授权。 - API Key 登录：
# macOS / Linux 临时设置
export OPENAI_API_KEY="sk-你的API密钥"
# 永久配置
echo 'export OPENAI_API_KEY="sk-你的API密钥"' >> ~/.zshrc
source ~/.zshrc
# Windows PowerShell
$env:OPENAI_API_KEY="sk-你的API密钥"
# 指定模型启动
codex --model gpt-5-codex
- auth.json 文件配置：
mkdir -p ~/.codex
cat > ~/.codex/auth.json << 'EOF'
{
"OPENAI_API_KEY": "sk-你的API密钥"
}
EOF
三种运行模式
| 模式 | 功能 |
|---|---|
| Suggest | 只建议修改，不自动执行 |
| Auto Edit | 自动修改文件，命令需确认 |
| Full Auto | 自动执行所有操作（谨慎使用） |
codex # 默认 Suggest
codex --auto-edit # Auto Edit
codex --full-auto # Full Auto
更新与卸载
# 更新
npm update -g @openai/codex
# 或
npm install -g @openai/codex@latest
codex --upgrade
# 卸载
npm uninstall -g @openai/codex
brew uninstall --cask codex
1.9 CLI 使用详解
首次使用与 TUI
# 启动交互式界面
codex
# 指定初始任务
codex "解释这个项目结构"
CLI 默认进入终端用户界面（TUI），分为：消息区（对话历史、工具调用、执行结果）、输入区（底部输入框发送 Prompt）、状态栏（模型、上下文使用、线程信息）。
TUI 配置（~/.codex/config.toml）：
[tui]
alternate_screen = "auto" # auto | always | never
Approval 模式（四种）
| 模式 | 说明 | 行为 |
|---|---|---|
| suggest | 建议模式 | 提供建议但不执行 |
| auto-edit | 自动编辑 | 自动执行文件编辑，命令需确认 |
| full-auto | 全自动 | 自动执行所有操作（谨慎使用） |
| interactive | 交互模式 | 敏感操作前询问（默认） |
codex --approval-mode full-auto
# 或在会话中切换
/approval full-auto
Sandbox 模式
codex --sandbox read-only # 只读
codex --sandbox workspace-write # 工作区写入（推荐）
codex --sandbox danger-full-access # 完全访问（危险）
| 模式 | 文件修改 | 命令执行 | 网络访问 |
|---|---|---|---|
| read-only | 禁止 | 禁止 | 禁止 |
| workspace-write | 仅工作区 | 允许 | 禁止 |
| danger-full-access | 允许 | 允许 | 允许 |
斜杠命令速查
| 命令 | 功能 |
|---|---|
/model | 切换模型（如 /model gpt-5.4-mini） |
/fast | 切换 Fast 模式 |
/plan | 进入计划模式 |
/review | 审查代码变更 |
/new | 开始新会话 |
/resume | 恢复历史会话 |
/fork | 克隆当前会话到新线程 |
/compact | 压缩上下文历史 |
/status | 显示会话状态 |
/clear | 清除屏幕 |
/quit | 退出 Codex |
示例：
/model gpt-5.4-mini
/plan 实现用户认证系统
/status
Shell 命令执行
在 CLI 中以 ! 开头执行 Shell 命令：
! ls -la
! git status
! ps aux
危险命令（如 rm、kill、修改系统配置）会要求确认。
图片输入
codex -i screenshot.png
codex --image design.png "根据这个设计实现页面"
codex -i img1.png -i img2.png "对比这两张设计稿的差异"
适用：截图分析错误、UI 设计稿转代码、图表数据解读。
非交互模式（exec）
适合脚本与 CI/CD，运行单次任务：
codex exec "审查代码并输出报告"
codex exec "生成 README" -o README.md
codex exec -m gpt-5.4-mini "分析项目结构"
codex exec --full-auto "运行测试并修复失败"
常用参数：-m 指定模型、-o 输出到文件、--full-auto 全自动执行、--ephemeral 不保存会话文件、--json JSON 输出格式。
快捷键
| 快捷键 | 功能 |
|---|---|
| Enter | 发送消息 |
| Shift+Enter | 换行 |
| Ctrl+C | 中断操作（连续两次退出） |
| Ctrl+D | 退出（输入空时） |
| Ctrl+R | 搜索历史 |
| Up/Down | 浏览历史 |
| Tab | 自动补全 |
| Esc Esc | 编辑上一条消息 |
| Ctrl+O | 复制最后回复 |
配置文件 config.toml 示例
# ~/.codex/config.toml
approval_policy = "ask"
[tui]
alternate_screen = "auto"
[sandbox]
default = "workspace-write"
日志位于 ~/.codex/log/ 目录，排错时可查看。
1.10 提示词最佳实践
基本结构
| 要素 | 说明 | 示例 |
|---|---|---|
| 任务描述 | 你想做什么 | “实现用户登录功能” |
| 上下文 | 相关背景信息 | “使用现有的 auth 模块” |
| 约束条件 | 限制和要求 | “必须兼容现有 API” |
| 期望结果 | 具体产出 | “返回 JWT token” |
结构化示例：
# 任务描述
实现一个用户登录 API 端点
# 上下文
- 项目使用 FastAPI 框架
- 已有 auth 模块处理认证逻辑
- 数据库使用 PostgreSQL
# 约束条件
- 使用现有的 JWT 工具生成 token
- 密码使用 bcrypt 验证
- 需要添加请求日志
# 期望结果
- 路径：POST /api/auth/login
- 请求体：{"email": "...", "password": "..."}
- 成功响应：{"token": "...", "user": {...}}
- 失败响应：{"error": "..."}
任务拆解
复杂任务应拆解为小步骤逐步完成。例如"实现完整的用户认证系统"可拆为：设计数据结构 → 注册功能 → 登录功能 → token 中间件 → 登出功能 → 编写测试 → 更新文档。使用 /plan 模式可让 Codex 自动拆解。
提供上下文
类型包括技术栈、项目结构、现有代码、约束条件。方式：直接描述、引用现有代码（"参考 src/utils/validator.py 的验证逻辑"）、指定文件、或通过 AGENTS.md 自动提供。
错误信息处理
提供完整错误要素：错误类型和消息、完整堆栈跟踪、触发条件、期望 vs 实际结果。可附加错误截图。
图片输入
适用场景：错误截图、UI 设计稿、架构图、数据图表。支持 PNG / JPG / WebP，分辨率适中即可。
迭代优化
流程：初步实现 → 检查提改进点 → 调整 → 验证 → 重复。例如先实现分页列表，再逐步加排序、搜索、性能优化。
避免歧义
- 模糊：“修改那个函数” → 明确：“修改 src/utils/helper.py 中的 format_date 函数”
- 模糊：“让它更快” → 明确：“优化 query_users 函数，查询时间从 500ms 降到 100ms 以内”
- 模糊：“加个功能” → 明确：“在用户 API 中添加批量删除功能，接收用户 ID 列表”
参考示例
提供参考代码、文档或响应格式，帮助 Codex 理解期望风格：
参考 src/api/products.py 的风格，实现用户 API
按照 OpenAPI 规范文档 docs/api-spec.yaml 实现
按照这个格式返回响应：{"success": true, "data": {...}, "message": "..."}
常用提示词模板
功能开发：
在 [模块路径] 添加 [功能名称] 功能
要求：
- 使用 [技术/库]
- 兼容 [现有系统]
- 包含 [边界处理]
- 返回 [响应格式]
参考：[现有类似功能路径]
Bug 修复：
问题描述：[Bug 表现]
触发条件：[什么情况下出现]
错误信息：
[完整错误堆栈]
期望行为：[正确结果应该是什么]
请分析原因并修复，不要影响其他功能。
代码审查：
/review [范围] for [重点]
# 示例
/review src/auth/ for security issues
/review HEAD~5..HEAD for performance regressions
AGENTS.md 项目规范文件
在项目根目录创建 AGENTS.md，Codex 会自动读取并遵循项目规范，减少重复说明。示例：
# 项目规范
## 技术栈
- 后端：FastAPI + PostgreSQL
- 测试：pytest
## 代码风格
- 使用 black 格式化，行宽 100
- 函数命名用 snake_case
## 常用命令
- 启动：uvicorn app.main:app --reload
- 测试：pytest
## 注意事项
- 所有 API 返回统一格式 {"success", "data", "message"}
- 数据库变更必须带迁移脚本
二、学习练习
2.1 练习设计说明
练习分为三个层级：
- L1 基础：熟悉安装、交互、基本代码生成与解释（1–5）。
- L2 进阶：Bug 修复、测试、审查、提示词对比、AGENTS.md（6–9）。
- L3 综合：把 Codex 用于真实工作流（自动化、图片转代码、小型功能模块）。
每个练习含：目标、准备、步骤、预期结果、自测清单。建议每完成一个练习在团队内做一次 5 分钟分享。
2.2 基础练习（L1）
练习 1：安装并首次运行
- 目标：独立完成 Codex CLI 安装并完成身份认证。
- 准备：已安装 Node.js（含 npm）或 Homebrew；拥有 ChatGPT 账号或 API Key。
- 步骤：
- 执行
npm install -g @openai/codex（或brew install codex）。 - 运行
codex --version确认安装成功。 - 运行
codex，按提示完成 ChatGPT 或 API Key 登录。
- 执行
- 预期结果：终端进入 TUI 界面，可输入 Prompt。
- 自测清单：
-
codex --version正常输出版本号 - 能进入交互界面
- 账号或 Key 认证通过
-
练习 2：让 Codex 解释项目结构
- 目标：体验 Codex 理解代码库的能力。
- 准备：任意已有项目目录（或新建
mkdir demo && cd demo并放入几个源文件）。 - 步骤：
- 在项目目录运行
codex。 - 输入：
分析当前项目结构，说明各模块职责和调用关系。
- 在项目目录运行
- 预期结果：Codex 输出项目架构说明，准确提及主要文件与模块。
- 自测清单：
- 输出包含主要文件清单
- 对模块职责的描述基本准确
- 你能据此快速理解项目
练习 3：生成 Hello World 并运行
- 目标：体验代码生成与文件写入。
- 准备：空目录。
- 步骤：
codex，输入：创建一个 Python 文件，打印 Hello Codex!，并给出运行命令。- 按 Codex 提示运行
python hello.py（或确认它已自动执行）。
- 预期结果：生成
hello.py，运行后输出Hello Codex!。 - 自测清单：
- 生成了可执行文件
- 运行输出符合预期
- 理解了 Codex 的文件写入方式
练习 4：使用 Suggest 与 Auto Edit 模式对比
- 目标：理解不同审批模式的行为差异。
- 准备：一个含简单函数的项目。
- 步骤：
codex（默认 Suggest）输入：把 utils.py 里的 add 函数改名为 sum_numbers，观察它只给建议。codex --auto-edit输入同样需求，观察它自动改文件但命令需确认。
- 预期结果：两种模式下对"是否自动改文件"的行为明显不同。
- 自测清单：
- 能说出 Suggest 与 Auto Edit 的区别
- 知道何时该用哪种模式
练习 5：用 Sandbox 做只读审查
- 目标：掌握 Sandbox 的安全边界。
- 准备：任意项目。
- 步骤：
codex --sandbox read-only，输入：审查 src/ 目录，列出潜在的空指针风险，不要修改任何文件。- 验证运行前后文件未被改动（
git status无变更）。
- 预期结果：Codex 只输出审查结论，未修改任何文件。
- 自测清单：
- 文件未被修改
- 输出了有价值的审查点
2.3 进阶练习（L2）
练习 6：修复一个真实 Bug
- 目标：用 Codex 定位并修复缺陷。
- 准备：在项目中故意制造一个 Bug（如除零、越界、拼写错误字段名）。
- 步骤：
codex，提供完整错误信息：运行测试时报错 [粘贴完整堆栈]，请分析原因并修复，不要影响其他功能。- 运行测试验证修复。
- 预期结果：Bug 被修复且测试通过。
- 自测清单：
- 修复了根因而非表象
- 未引入新的失败
- 理解了修复逻辑
练习 7：为函数编写测试
- 目标：让 Codex 生成高质量测试并验证。
- 准备：一个未覆盖测试的函数。
- 步骤：
- 输入：
为 src/calc.py 的 calculate_discount 函数编写 pytest 测试用例，覆盖正常、边界与异常输入，并运行测试。 - 检查测试是否真的运行且通过。
- 输入：
- 预期结果：生成测试文件，覆盖多分支，全部通过。
- 自测清单：
- 测试覆盖正常/边界/异常
- 测试实际执行并通过
- 能看懂测试断言
练习 8：提示词对比实验
- 目标：直观感受"模糊 vs 明确"提示词的差异。
- 准备：同一需求。
- 步骤：
- 输入模糊提示：
优化下数据库查询。 - 另开会话输入明确提示：
优化 src/repo/users.py 的 get_active_users 函数，当前全表扫描，改为带索引的查询，目标响应 < 100ms，并说明改动。 - 对比两次产出的可用性。
- 输入模糊提示：
- 预期结果：明确提示产出更可落地、更贴合项目。
- 自测清单：
- 记录两次产出差异
- 能复述"明确提示词"的写法要点
练习 9：编写项目 AGENTS.md
- 目标：建立项目级规范，让 Codex 自动遵循。
- 准备：你的真实项目。
- 步骤：
- 在项目根目录创建
AGENTS.md，写入技术栈、代码风格、常用命令、注意事项（参考 1.10 模板）。 - 输入一个需要遵循规范的任务，例如：
新增一个用户列表 API，观察 Codex 是否自动匹配风格与命令。
- 在项目根目录创建
- 预期结果：Codex 产出的代码风格、命名、命令符合 AGENTS.md 约定。
- 自测清单：
- AGENTS.md 包含至少技术栈与常用命令
- Codex 行为明显受规范约束
2.4 综合实战（L3）
练习 10：exec 模式自动化任务
- 目标：把 Codex 接入脚本/CI 流程。
- 准备：一个带测试的项目。
- 步骤：
- 运行：
codex exec --full-auto "运行测试，若失败则修复并重新运行直到通过"。 - 查看输出与最终测试结果。
- 运行：
- 预期结果：测试最终通过，过程有清晰日志。
- 自测清单：
- exec 模式正常返回
- 测试通过
- 理解了其在 CI 中的价值
练习 11：图片转代码
- 目标：用设计稿生成前端页面。
- 步骤：
- 准备一张 UI 截图或设计稿
ui.png。 - 运行：
codex --image ui.png "根据这张设计稿实现对应的 HTML/CSS 页面，保持布局与配色"。 - 在浏览器打开生成页面，对比设计稿。
- 准备一张 UI 截图或设计稿
- 预期结果：生成贴近设计稿的页面，结构合理。
- 自测清单：
- 页面布局接近设计稿
- 代码可读、可继续修改
练习 12：小型功能模块全流程
- 目标：串联"规划 → 实现 → 测试 → 审查"完整闭环。
- 准备：选择一个真实小需求（如"导出用户数据为 CSV"）。
- 步骤：
/plan 实现用户数据导出为 CSV 的功能，评审计划。- 按计划实现，要求包含单元测试。
/review 本次改动 for 安全与性能。- 根据审查意见修正。
- 预期结果：功能可用、有测试、经审查无重大问题。
- 自测清单：
- 完成了计划评审
- 功能 + 测试齐全
- 审查问题已处理
三、精通学习资料
3.1 高级提示词工程（上下文工程）
精通 Codex 的关键在于"上下文工程"：把正确信息在正确时机喂给模型。
- 把验证标准写进 Prompt：让 Codex 自己跑测试/构建来验证，质量显著高于"写完就交"。
- 把大任务拆成可验证小步：每步结束让 Codex 报告，再进入下一步，避免偏离。
- 用引用代替复述：引用文件路径、函数名、AGENTS.md，而非大段粘贴代码。
- 让模型先 plan 再 act：复杂改动先
/plan，人工确认方案后再执行，降低返工。 - 善用图片与图表：UI、报错截图、架构图直接给图，比文字描述更高效。
3.2 AGENTS.md 深度配置
AGENTS.md 是项目与 Codex 之间的"契约文件"，可包含：
- 技术栈与版本约束（避免用错依赖）。
- 目录结构与模块职责（让 Codex 放对文件）。
- 命令约定：开发、测试、构建、lint、迁移的标准命令。
- 代码规范：命名、格式化、注释、错误处理偏好。
- 禁区：哪些文件/目录不要动，哪些操作需人工确认。
- 多语言项目可用多个 AGENTS.md 分层（根目录总纲 + 子模块细则）。
提示：把 AGENTS.md 纳入版本管理并与团队共享，是保证 Codex 产出一致性的核心手段。
3.3 工作流编排与自动化（exec + CI/CD）
- exec 模式：适合无交互的一次性任务，如生成变更日志、跑安全检查、修复失败测试。配合
--json可接入流水线解析。 - CI 集成：在 PR 中自动触发
codex exec做初步审查或修复，把结果作为评论回写。 - 定时任务：结合系统定时任务，对仓库做周期性健康扫描（死代码、过期依赖、潜在漏洞）。
- 注意：自动化任务应使用受限 Sandbox 与
ask/deny审批策略，避免全自动误改生产代码。
3.4 Sandbox 与审批策略精调
- 默认使用
workspace-write，仅放开工作区写入，禁止网络以降低风险。 - 仅在可信环境（如隔离 CI VM）使用
danger-full-access或full-auto。 - 通过
approval_policy在配置中设默认值，敏感仓库设为ask强制人工确认。 - 在 AGENTS.md 中声明禁区，配合 Sandbox 形成双重防护。
3.5 多会话并行与上下文管理
- 用
/fork克隆会话尝试不同方案，保留主线程不被污染。 - 长任务用
/compact或自动压缩释放上下文；接近上限时用/new开启新会话。 - 并行线程避免同时改同一文件，必要时按模块拆分任务。
- 用
/status监控上下文与线程配置。
3.6 测试驱动开发（TDD）与质量保障
- 让 Codex 先写测试再实现（红→绿→重构），比先实现再补测试更稳。
- 每次改动要求"运行测试并通过"作为完成判据。
- 用
/review做安全、性能、可读性多维度审查，并把高频问题沉淀进 AGENTS.md。 - 把覆盖率目标写入 AGENTS.md，作为 Codex 的自我约束。
3.7 大型项目重构与迁移实战
- 先映射后动手：让 Codex 先输出依赖关系图与影响面评估。
- 小步提交：每完成一个子模块就提交，便于回滚与评审。
- 双跑验证：重构后用对比测试（输入输出一致性）确认行为未变。
- 语言/框架迁移：分阶段迁移，保留兼容层，用 Codex 批量转换样板代码，人工把控核心逻辑。
3.8 安全、合规与数据治理
- 企业场景优先选择支持 SSO、MFA、审计日志、数据驻留的计划。
- 敏感代码库使用本地/私有部署或受限 Sandbox，避免代码外泄。
- 在 AGENTS.md 与审批策略中禁止 Codex 访问
~/.ssh、/etc、密钥文件等。 - 定期审查 Codex 的操作日志，留存审计轨迹。
3.9 性能与成本优化
- 简单任务用轻量模型（
/fast或 mini 模型），复杂任务用主力模型，按需切换。 - 控制上下文规模：精简 AGENTS.md、及时
/compact、避免一次性粘贴超大文件。 - 用 exec +
--ephemeral避免会话堆积占用资源。 - 在 Plus/Pro 限额内合理并行，避免无意义的长任务空转。
3.10 团队协作规范
- 统一 AGENTS.md 模板，纳入仓库根目录与子模块。
- 约定运行模式：日常用
auto-edit/交互，生产改动用ask审批。 - 建立"AI 辅助 + 人工评审"机制：Codex 产出必须经人 review 后才能合并。
- 沉淀团队提示词库（常用模板、Skills），减少重复摸索。
- 定期复盘：哪些任务适合交给 Codex，哪些必须由人完成。
3.11 常见故障排查
| 现象 | 可能原因 | 处理 |
|---|---|---|
codex: command not found | PATH 未包含 npm 全局目录 | 用 npm bin -g 定位并加入 PATH，或改用 Homebrew |
| 认证失败 | Key 失效/权限不足 | 重新登录或更换 API Key，检查计划是否含 Codex |
| Windows 启动异常 | 原生支持实验性 | 使用 WSL2 运行 |
| 上下文溢出 | 历史过长/文件过大 | /new 或 /compact，精简 AGENTS.md |
| 误改文件 | 用了 full-auto/全访问 | 立即 git checkout 回滚，收紧 Sandbox 与审批策略 |
| 命令被频繁拦截 | 审批策略过严 | 在可信范围调整为 approve，或显式放行特定命令 |
四、扩展学习资料
4.1 同类工具横向对比
| 工具 | 形态 | 特点 | 适用 |
|---|---|---|---|
| Codex | CLI/IDE/App/Web | 多形态、云端代理、深度项目理解 | 全场景 |
| Cursor | IDE | 编辑器内 AI 补全与对话 | 日常编码 |
| Claude Code | CLI | 强推理、长上下文 | 复杂重构 |
| Aider | CLI | 轻量、Git 友好 | 小规模改动 |
| Trae / Qoder | AI IDE | 国内网络友好、本地化 | 国内团队 |
选型建议：团队统一以 Codex 为主入口，按成员习惯辅以 IDE 类工具；涉及强网络/合规要求时评估本地化替代。
4.2 场景化应用指南
- Web 开发：用 Codex 生成页面骨架、实现 API、写前后端联调测试。
- 数据处理：让它编写清洗/ETL 脚本并附带校验测试。
- 测试与质量：批量补测试、做安全/性能审查。
- 文档：从代码生成 README、API 文档、变更日志。
- 重构迁移：依赖分析 → 小步重构 → 一致性验证。
- 运维脚本：生成部署、监控、告警脚本并自检。
4.3 进阶学习方向
- 官方文档与更新日志：跟踪新模型、新命令、新策略。
- 开源仓库：阅读实现与示例，理解 Agent 循环与沙箱机制。
- 社区实践：关注提示词工程、AGENTS.md 模板、CI 集成案例。
- 内部沉淀：把团队高频用法、踩坑、模板整理成内部 Wiki。
4.4 团队落地路线图
- 试点（第 1–2 周）：2–3 人用 Codex 完成日常小任务，统一安装与登录方式。
- 规范（第 3–4 周）：编写团队 AGENTS.md 模板，确立运行模式与评审机制。
- 推广（第 2 月）：全员培训，开展练习 6–12 的实战工作坊。
- 自动化（第 3 月）：把 exec 模式接入 CI，做自动审查/修复试点。
- 复盘优化：每月复盘效率与质量指标，迭代规范。
4.5 能力自测清单（入门 → 精通）
入门级（应掌握）：
- 能独立完成安装与登录
- 能用四种方式之一启动 Codex
- 理解 Prompt / Thread / Context / Sandbox / Approval
- 会用 TUI、斜杠命令、exec 模式
- 能写出结构化的明确提示词
进阶级（应掌握）：
- 能用 Codex 修复 Bug、写测试、做审查
- 会编写并维护 AGENTS.md
- 能对比不同提示词的效果
- 会用 Sandbox 与审批策略控制风险
精通级（应掌握）：
- 能把 Codex 接入 CI/CD 做自动化
- 能在大型项目中安全重构/迁移
- 能设计团队级规范与评审机制
- 能排查常见故障并优化性能/成本
- 能指导他人落地 Codex
附录：常用命令速查表
安装与版本
npm install -g @openai/codex # 安装
brew install codex # macOS 安装
codex --version # 查看版本
npm update -g @openai/codex # 更新
codex --upgrade # 更新
npm uninstall -g @openai/codex # 卸载
启动与模式
codex # 启动（默认 Suggest）
codex "解释项目结构" # 带初始任务
codex --auto-edit # Auto Edit 模式
codex --full-auto # Full Auto 模式
codex --approval-mode full-auto # 指定审批模式
codex --sandbox workspace-write # 指定沙箱
codex --model gpt-5-codex # 指定模型
非交互与图片
codex exec "运行测试并修复失败" --full-auto # 单次任务
codex exec "生成 README" -o README.md # 输出到文件
codex -i screenshot.png # 附加图片
codex --image design.png "按设计稿实现页面" # 图片+任务
会话管理（斜杠命令）
/new 开始新会话
/resume 恢复历史会话
/fork 克隆当前会话
/plan 计划模式
/review 审查改动
/compact 压缩上下文
/status 会话状态
/model 切换模型
/quit 退出
配置文件（~/.codex/config.toml）
approval_policy = "ask"
[tui]
alternate_screen = "auto"
[sandbox]
default = "workspace-write"
本资料用于团队内部 Codex 学习与落地参考，建议结合实际项目持续更新。
编程资源
https://pan.quark.cn/s/7f7c83756948
更多资源
https://pan.quark.cn/s/bda57957c548
扫一扫
1966
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
