OpenAI Codex 使用指南

一、平台介绍

1. 两代 Codex 区分（核心避坑前提）

• 初代 Codex（2021-2023，已彻底废弃）定义：基于 GPT-3 微调的纯代码补全模型。
• 功能：仅支持单行代码生成。
• 现状：早期 GitHub Copilot 底层模型，官网页面已下线，无法使用。
• 新版 Codex（2025 至今，当前官网产品）全称：Codex AI 软件工程智能体（Agent）。
• 定位：不是简单代码补全，是一套完整自动化开发工具矩阵。
• 底层模型：GPT-5 系列代码专项优化模型。
• 官网入口区分：
• 产品介绍页：https://openai.com/zh-Hans-CN/codex
• 网页在线使用：https://chatgpt.com/zh-Hans-CN/codex
• 开发者 API 文档：developers.openai.com/codex

2. 核心定位

• OpenAI 面向开发者的自主式编程智能体。
• 区别：区别于 ChatGPT 问答模式。
• 能力：
• 可读取完整代码仓库。
• 批量修改多文件。
• 自动执行测试。
• 生成 PR。
• 长时间独立跑开发任务。
• 配套载体：桌面客户端、VS Code 插件、CLI 命令行、GitHub 集成。
• Computer Use：支持操控本地文件/浏览器，打通完整开发工作流。

3. 底层逻辑

• 运行环境：任务运行在云端隔离沙箱。
• 数据安全：不会直接修改本地/线上真实代码。
• 修改机制：所有改动生成 diff 变更记录，人工审核确认后才落地。

二、主要功能

1. 全仓库级代码处理（王牌能力）

• 架构分析：一键解析陌生仓库、梳理模块依赖、输出架构文档。
• 批量修改：单条需求同时改数十个源码、配置、测试文件。
• 代码重构：老旧项目模块化、规范统一、补充注释与类型校验。
• 自动测试：自动生成单元/集成测试，提升测试覆盖率，自动跑用例排查报错。

2. 自动化 Bug 修复与迭代

• 输入：上传报错日志、Issue 描述。
• 处理：Codex 自主定位根因、写修复代码、循环自测直到通过。
• 输出：直接生成 GitHub Pull Request 供审核。

3. 多端载体入口

• 桌面 App（Windows/macOS）本地文件夹读取。
• Computer Use 操控电脑文件、浏览器、办公软件。
• VS Code 插件编辑器内直接唤起。
• 实时关联当前项目上下文。
• Codex CLI 命令行Linux/服务器批量脚本。
• CI/CD 流水线集成。
• 网页端（chatgpt.com/codex）绑定 GitHub 仓库。
• 云端在线处理开源项目。
• GitHub Action 集成自动化代码评审。
• 合并前自动校验。

4. MCP 插件扩展生态

• 自定义技能包：支持自定义技能包。
• 外部连接：对接数据库、云服务、API 接口。
• 流程封装：封装重复开发流程一键调用。
• 内置能力：代码解释器、终端执行、文件读写权限管控。

5. 配套辅助能力

• 代码评审：扫描漏洞、不规范写法、性能隐患，输出整改清单。
• 文档自动生成：接口文档、README、开发手册。
• 低代码工具开发：爬虫、数据处理脚本、后台管理简易服务。
• 长任务持续执行：单次 Agent 任务最长可连续运行 30 分钟无需人工干预。

三、适用人群

1. 高度适配人群

1. 全职后端/前端/全栈开发者：大型项目重构、批量改需求、写测试、修线上 bug。
2. 开源项目维护者：自动处理 Issues、审核 PR、更新文档（OSS 计划免费 Pro 权益）。
3. 学生/编程初学者：解析源码、辅助写作业、排查报错、学习工程规范。
4. 独立开发者/创业小团队：单人承接完整需求，快速搭建 MVP，减少重复体力编码。
5. 运维/数据工程师：批量写 Shell/Python 运维脚本、数据清洗工具。

2. 轻度可用人群（非程序员）

• 产品/运营/分析师：生成自动化办公脚本、数据处理小工具、简易网站 Demo，零代码基础也可通过自然语言下达任务。

3. 不适合人群

1. 国内企业内网、合规要求严格、无法访问境外服务的团队。
2. 仅需要单行代码片段、追求极简轻量化工具（GitHub Copilot 更轻量便宜）。
3. 影视/3D、纯设计类无代码需求用户。

四、免费&付费情况

Codex 分 ChatGPT 订阅使用、OpenAI API 按量调用 两套独立账单，互不通用。

（一）ChatGPT 订阅（网页/桌面 App/VS 插件使用）

• 免费版（普通 ChatGPT 免费账号）状态：Codex 入口完全锁定不可用。
• 功能：无任何编程 Agent 额度，仅普通 ChatGPT 自带简易代码生成（无仓库读取、无多文件修改能力）。
• ChatGPT Plus ($20/月)额度：解锁 Codex 基础额度，每日有使用上限。
• 限制：复杂重构、长任务容易耗尽配额。
• 支持：桌面 App、GitHub 绑定、基础沙箱任务。
• ChatGPT Pro（两档）中档 ($100/月)：Codex 配额为 Plus 5 倍，无基础速率限制，适合高频开发。
• 顶配 ($200/月)：Codex 配额 20 倍，企业级优先级、专属算力、长任务无阻断。
• Team/Enterprise 企业版 ($20/席位/月，年付)功能：团队统一管理、权限隔离、数据隐私协议、SLA 服务保障、超大仓库支持。
• 免费专项福利学生：edu 邮箱享 ChatGPT Edu，免费解锁等同 Plus 的 Codex 权限。
• 开源维护者：申请通过享 6 个月免费 ChatGPT Pro 完整权限。

（二）OpenAI API 按量付费（程序调用 codex 模型）

• 模型：gpt-5.5-codex
• 输入 Token：$1.5 / 百万 tokens
• 输出 Token：$6 / 百万 tokens
• 计费方式：预充值余额制，无月租，仅调用扣费。
• 适用场景：自动化脚本、自研工具集成。

补充支付说明

• 仅支持境外 Visa/Master 信用卡，无支付宝、微信国内支付渠道。

五、分步使用教程

方式 1：网页端快速上手（新手首选）

1. 访问 https://chatgpt.com/zh-Hans-CN/codex。
2. 登录 ChatGPT Plus/Pro 账号。
3. 授权绑定 GitHub 账号，导入需要处理的代码仓库。
4. 输入自然语言任务（示例：重构 user 模块、修复登录报错、生成单元测试）。
5. Codex 自动加载仓库代码，在云端沙箱执行修改。
6. 查看变更 diff，确认无误一键生成 GitHub PR。

方式 2：桌面客户端本地项目使用（最常用）

1. 打开 https://openai.com/zh-Hans-CN/codex/get-started 下载 Windows/macOS 安装包。
2. 登录同 ChatGPT 付费账号，授予本地文件读取权限。
3. 拖拽本地项目文件夹到 Codex 界面。
4. 下达开发任务，支持直接读写本地文件、执行终端命令。
5. 所有修改留存记录，一键回滚全部变更。

方式 3：VS Code 插件集成

1. VS Code 扩展商店搜索「OpenAI Codex」安装。
2. 登录账号，自动关联当前打开工程。
3. 编辑器侧边栏唤起 Agent，选中代码直接下发修复/重构指令。

方式 4：API 代码调用 JSON 示例

• 请求头：Authorization: Bearer 你的 OpenAI API Key
• 接口地址：https://api.openai.com/v1/chat/completions
• 示例 Payload：
• json

{
  "model": "gpt-5.5-codex",
  "messages": [
    {
      "role": "system",
      "content": "你是资深后端工程师，基于提供的 Python 代码修复数据库查询慢的 bug，输出完整优化后文件与说明"
    },
    {
      "role": "user",
      "content": "现有代码：[粘贴完整代码 + 报错堆栈]，需求：添加索引、分页优化，补充异常捕获"
    }
  ],
  "temperature": 0.2,
  "stream": false
}
{
  "model": "gpt-5.5-codex",
  "messages": [
    {
      "role": "system",
      "content": "你是资深后端工程师，基于提供的 Python 代码修复数据库查询慢的 bug，输出完整优化后文件与说明"
    },
    {
      "role": "user",
      "content": "现有代码：[粘贴完整代码 + 报错堆栈]，需求：添加索引、分页优化，补充异常捕获"
    }
  ],
  "temperature": 0.2,
  "stream": false
}

六、避坑重点（高频踩坑汇总）

1. 网络致命坑（国内用户第一难题）

• 现状：Codex 服务器全部海外。
• 影响：国内直连大概率加载失败、GitHub 仓库拉取超时、桌面 App 同步卡住、API 请求 504 超时。
• 合规：无国内节点、无备案，企业内网无法合规使用。
• 解决：刚需需稳定境外网络环境。

2. 两代 Codex 混淆坑

• 风险：不要搜索旧版 codex 模型接口，2023 年已废弃。
• 现状：现在所有产品为 Agent 智能体。
• 后果：两者功能、计费、接口完全不互通，网上老旧教程全部失效。

3. 额度与计费分离坑

• 独立扣费：ChatGPT 订阅额度不能抵扣 API 调用，分开充值扣费。
• Plus 限制：Plus 每日 Codex 配额有限，大型重构、批量测试极易耗尽，只能等次日重置或升级 Pro。
• API 成本：API 按量消耗极快，处理千行代码仓库单次消耗数十万 tokens，成本容易失控。

4. 安全权限风险

1. 本地权限：桌面 App 授予本地全盘权限，不要上传包含密钥、数据库密码、生产配置的项目。
2. 仓库绑定：绑定私人 GitHub 仓库后，Codex 可读取全部源码，涉密业务仓库禁止接入。
3. 沙箱执行：沙箱仅隔离云端任务，本地 Computer Use 模式可修改本机文件，执行前务必预览 diff 变更。

5. 功能局限性坑

1. 内核推理：复杂底层内核、驱动、嵌入式代码推理能力弱，容易生成无法编译代码。
2. 任务中断：长任务（超过 20 分钟）偶发中断，大型微服务多仓库并行处理容易遗漏模块。
3. 测试覆盖：自动生成测试只能覆盖基础场景，边界用例仍需人工补充。

6. 订阅与支付坑

1. 支付渠道：无国内支付，境外虚拟卡续费容易失败、订阅无故取消。
2. 价格门槛：Pro 档位价格高昂，个人轻度开发无需盲目升级 Plus 以上套餐。
3. 报销难题：取消订阅流程繁琐，账单无法开具国内报销发票。

7. 版本与生态坑

1. Linux 支持：Linux 无官方桌面 App，仅 CLI 命令行，可视化操作缺失。
2. 插件同步：VS Code 插件偶尔同步账号失效，需重新登录。
3. 模型合并：2026 年 4 月 OpenAI 宣布不再维护独立 codex 专用模型，能力并入 GPT-5.5 通用模型，后续接口、功能可能持续调整，旧代码存在兼容失效风险。

8. 版权商用坑

• 授权问题：Codex 生成代码商用无明确无风险授权。
• 协议：核心付费企业版才有完整商用协议。
• 责任：个人/Plus 用户用于商业产品需自行承担代码版权风险。

七、同类替代对比

• 轻量化实时补全：GitHub Copilot（$10/月，便宜、适合单行编码）。
• 本地开源 Agent：Cursor（内置代码智能体，可离线使用）。
• 推理型代码 Agent：Claude Code（长上下文读仓库更强，但国内访问限制大）。
• 国内合规平替：字节 Trae、华为云 CodeArts（国内服务器、微信支付、合规内网部署）。