Codex 概述
什么是 Codex？
OpenAI Codex 是一款 AI 编程智能体，专为软件工程任务设计，能够帮助开发者编写代码、修复 Bug、理解陌生代码库，并执行各类工程任务。Codex 支持多种使用场景，包括云端、命令行工具、桌面应用、IDE 插件和 GitHub 集成。
功能定位
Codex 的功能定位是成为开发者的 AI 编程助手，支持多种使用场景和工具链集成。
套餐与权限
Codex 访问权限包含在 ChatGPT Plus、Pro、Business、Edu 和 Enterprise 套餐中。
快速入门
云端快速开始（Web）
- 访问 ChatGPT.com/codex，连接 GitHub 账户。
- 配置环境，选择要操作的 GitHub 仓库。
- 创建任务，实时查看日志或后台运行。
- 任务完成后，审查变更并创建 Pull Request。
CLI 快速开始
- 安装 Codex CLI：
npm install -g @openai/codex。
- 登录认证：
codex。
- 执行任务：
codex \"修复所有 TypeScript 类型错误\"。
桌面应用快速开始
- 下载并安装 Codex 桌面应用。
- 使用 ChatGPT 账户或 OpenAI API Key 登录。
- 选择项目文件夹，确认模式为 Local。
示例任务
- 分析项目架构
- 查找空指针异常
- 添加输入验证
- 重构代码风格
- 分析 CI 失败原因
Codex 桌面应用
核心功能一览
- 多项目并行
- Git Worktree 支持
- 电脑操控
- 代码审查与提交
- 集成终端
- 内置浏览器
- 图像生成
- 自动化任务
- 技能
- 插件
与 IDE 插件同步
桌面应用与 IDE 插件之间可共享 Auto Context 和活跃线程，实现实时协作。
CLI 命令行工具
安装与认证
安装：npm install -g @openai/codex。
登录：codex 或使用 API Key。
常用命令
- 执行任务：
codex \"任务描述\"。
- 子代理并行：
codex \"同时执行多个子任务\"。
- 云端任务启动：
codex cloud \"GitHub 任务描述\"。
- Web 搜索集成：
codex --search \"搜索内容\"。
- MCP 工具支持：通过 Model Context Protocol 连接第三方工具。
云端（Codex Cloud）
云端概述
Codex Cloud 允许任务在 OpenAI 托管的隔离容器中后台运行，支持并行处理多个任务，并直接生成 Pull Request。
连接 GitHub 仓库
- 访问 ChatGPT.com/codex。
- 点击连接 GitHub 账户。
- 选择仓库，配置安装步骤和工具。
GitHub 集成
在 GitHub Issue 或 Pull Request 评论中 @codex，触发任务并直接提交变更建议。
网络访问控制
默认关闭网络访问，可开启完全开放或域名白名单模式。
环境配置
自定义 GitHub 仓库、依赖安装步骤、工具列表和网络访问策略。
安全与沙箱
安全架构
Codex 的安全控制由沙箱模式和审批策略两层机制协同工作。
沙箱模式对比
提供不同级别的沙箱模式，限制 Codex 的操作范围。
config.toml 安全配置
持久化安全设置，包括审批策略和沙箱模式。
受保护路径
默认受只读保护，包括 .git、.agents 和 .codex 目录。
自动审批审核
默认发送审批请求，可配置自动审核模式。
OS 级沙箱实现
在容器化环境中，使用 Docker 提供隔离边界。
Dev Container 安全方案
使用 Dev Containers 配合 Codex，提供外部隔离边界。
监控与遥测（OTel）
支持通过 OpenTelemetry 进行使用审计，默认关闭。
自动化任务（Automations）
概述
Automations 允许设置定时循环任务，Codex 在后台执行并将结果添加到收件箱。
两种自动化类型
- 独立自动化：按计划启动全新运行。
- 线程自动化：以心跳方式定期唤醒当前线程。
Git Worktree 集成
可选择在本地项目或独立 Worktree 中运行任务。
通过对话创建自动化
使用自然语言直接创建自动化任务。
与 Skills 结合
在自动化中调用 Skills，触发预定义的工作流。
技能（Skills）
什么是 Skills？
Skills 是可复用的指令和工作流集合，跨 Codex 桌面应用、CLI 和 IDE 插件使用。
Skills 的使用场景
- 标准化代码审查流程
- 统一的测试生成指令
- 项目特定的文档模板
- 自定义的 bug 分析工作流
- 跨项目通用的重构规则
创建和管理 Skills
Skills 存储在 .codex/skills 目录中，可通过对话请求、插件或直接编辑创建。
插件与 MCP
插件生态
Codex 通过 Model Context Protocol (MCP) 支持插件，扩展 Codex 的能力边界。
配置 MCP 服务器
在 config.toml 中配置 MCP 服务器。
MCP 工具安全
Codex 对 MCP 工具调用有安全机制，包括审批策略。
SDK 集成
TypeScript/Node.js SDK
提供程序化控制方式，适合服务端集成。
Python SDK
需要 Python 3.10+ 和 Codex 开源仓库的本地克隆。
非交互模式（exec 命令）
通过 exec 命令脚本化执行重复工作流。
配置参考
配置文件位置
主配置文件路径：~/.codex/config.toml。
完整配置示例
提供基础配置、历史记录设置、遥测配置和自动审核配置示例。
命令行参数速查
提供常用命令行参数速查表。
最佳实践
提示词编写技巧
- 清晰具体
- 使用积极和消极示例
- 鼓励分步推理
- 指定输出格式
版本控制工作流
- 保持 git status 干净
- 创建 Git 检查点
- 将 Codex 建议当作普通 PR 审查
任务委派策略
- 从小而具体的任务开始
- 使用 Skills 标准化工作流
- 利用 Worktree 隔离任务
安全建议
- 使用沙箱
- 定期审查审批/沙箱变更
- 使用 read-only + approval never 组合
常见问题与故障排查
诊断工具
运行 codex doctor 获取环境诊断信息。
沙箱测试
本地测试沙箱行为：codex sandbox [平台] [命令]。
常见问题
- Docker 容器中沙箱不工作
- WSL1 不再支持
- VS Code 中强制使用 WSL2
- OTel 导出失败
获取帮助
官方资源包括文档、开源仓库、支持与反馈。
