《手册指南：开启AI开发平台的实用指南》

如果你是工程经理、采购负责人或行政人员，且只需要了解第7节、第8节以及第14节》的内容，那么就可以跳过这些技术前提要求，直接阅读相关章节。

在开始学习第4节之前，请先准备好以下工具和账户。如果完全从零开始设置，所需时间约为15–25分钟。

验证你的开发环境

在开始阅读第4节之前，请先运行以下三个命令。如果其中任何一条命令执行失败，请先解决相应问题。

node --version   # 应该显示v18.x或更高版本
npm --version    # 应该显示9.x或更高版本
git --version    # 应该显示2.30或更高版本

本手册不会涵盖的内容

为了明确大家的期望，需要说明的是，本手册不会涉及以下内容：

• 如何编写适用于生产环境的Python代码、JavaScript代码或任何其他特定语言的程序。我们使用简短的示例来演示Codex的功能，而不是教授相关语法。

• 如何从零开始设计系统架构。第14节已经解释了为什么Codex并不适合用于全新的架构设计。

• 如何在组织层面管理GitHub账户。第8节介绍了如何配置适用于Codex的GitHub连接器，但前提是你的GitHub组织账户已经存在。

• 大语言模型的内部工作原理（如注意力机制、RLHF等）。我们把这些模型视为具有可测量行为功能的“黑箱”。

第1节：Codex是什么

Codex是OpenAI提供的编程辅助工具。最重要的是要明白：Codex不仅仅是一个模型名称，而是一种旨在帮助人们更快地编写代码、审查代码、调试代码并最终发布代码的产品与工作流程工具。用OpenAI自己的话来说，它就是一种能够与你本地协作或在云端完成各项任务的AI编程助手。

这种区分非常重要。大多数人会从两种角度来理解人工智能：

• 一种能够回答问题的聊天机器人。

• 一种能提供代码片段的辅助编写工具。

Codex的范围远超这两者。它不仅可以检查代码仓库、编辑文件、运行命令以及执行测试，还能根据用户提供的提示或需求，生成具体的任务计划、代码修改内容以及可供审查的输出结果。

对于团队来说，基于云的工作流程尤为重要，因为这样可以让Codex在后台持续运行，而工程师们则可以专注于自己的工作。

OpenAI目前的文档还将Codex与其他一系列开发工具一起进行介绍，比如API、Responses API、Agents SDK、MCP工具以及Codex应用程序。如果你正在带领一个团队开始使用Codex，那么以下这种理解方式会非常有用：

• 各种模型是核心处理引擎。

• Codex就是利用这些引擎来帮助人们进行编程的工具。

• CLI命令行工具、IDE扩展程序、网页应用程序以及云端任务管理功能，都是人们与Codex交互的方式。

第2节：Codex在OpenAI生态系统中的位置

目前，OpenAI提供了一套多层次的开发工具栈：

• 通用型前沿模型，例如GPT-5.5、GPT-5.5 Pro、GPT-5.4、GPT-5.4-mini以及GPT-5.4-nano。

• 专为特定领域设计的模型，例如GPT-5.3-Codex、GPT-5.2-Codex、GPT-5.1-Codex以及codex-mini-latest。

• 将这些模型整合到具体工作流程中的工具与平台，包括Codex CLI、Codex应用程序、集成开发环境扩展插件、云任务处理功能以及代码审查工具等。

实际应用中的区别很简单：

• 如果你需要进行一次性推理、综合分析或日常聊天，可以使用通用模型。

• 如果你需要一个能够浏览代码库、修改文件、运行测试并最终生成具体代码结果的工具，那么Codex正是为此而设计的。

OpenAI目前的模型文档将GPT-5.4描述为用于复杂推理和编码的旗舰模型。而专门针对Codex设计的模型页面则将GPT-5.3-Codex和GPT-5.2-Codex描述为专为在Codex或类似环境中进行编码任务而优化的模型。这说明了OpenAI是如何定位这些模型的：

• GPT-5.4是通用的旗舰模型。

• 专门针对Codex设计的模型则是为编码工作流程量身定制的。

• Codex这个产品可以根据不同的使用场景和配置来切换不同的模型。

如果这一部分内容你只记住了这一点，那就记住：Codex是处理工作流程的工具，而模型则是实现这些功能的“引擎”。

GPT-5.5：最新版本

OpenAI于2026年4月23日发布了GPT-5.5，其API也在同年4月24日正式上线。同时，还推出了更高级别的GPT-5.5 Pro版本。OpenAI称GPT-5.5是“迄今为止最智能、使用起来也最为直观的模型，它是迈向一种新的计算机工作方式的里程碑。”

对于使用Codex的用户来说，实际应用中的变化可以概括为以下几点：

1. GPT-5.5已成为新的通用旗舰模型。凡是旧文档中提到“GPT-5.4是旗舰模型”的地方，今后都应该理解为GPT-5.5。不过GPT-5.4仍然作为更便宜的默认选项提供。

2. Codex的各种使用界面将会逐步切换到使用GPT-5.5。预计在发布后不久，GPT-5.5就会成为CLI、IDE、应用程序以及云任务中的可选模型，甚至很可能成为默认模型。请务必检查自己的设置中当前使用的模型是什么。

3. 定价也发生了变化。从每个token的费用来看，GPT-5.5明显高于GPT-5.4。在批准预算之前，请先查看第7节的内容。

关于如何选择GPT-5.5、GPT-5.4或专门为Codex设计的模型，详细的基准测试数据、性能亮点以及针对不同工作负载的推荐方案，请参阅第11节：模型规格与基准测试。在掌握了基础内容之后，再阅读这一节会更有帮助。

第3节：核心使用界面

目前，Codex可以在多个地方被使用，而每个使用界面都是为适应不同的工作风格而优化的。

Codex CLI

• 官方文档：developers.openai.com/codex/cli

• npm包：@openai/codex

• GitHub仓库

CLI是将Codex直接应用于终端会话的最快捷方式。相关文档将其描述为OpenAI开发的一款编码辅助工具：该工具可在用户的终端上本地运行，能够读取、修改并执行用户机器上的代码，而且它是开源软件，使用Rust语言编写。

在以下情况下可以使用CLI：

• 需要以终端为主要工作环境时。

• 需要在现有的代码仓库中快速进行代码迭代时。

• 需要对代码的审批和执行过程进行精细控制时。

• 对于需要完成本地编码任务的场景来说，CLI是一个轻量级的选择。

IDE扩展插件

• 官方文档：developers.openai.com/codex/ide

• VS Code市场中的扩展插件(openai.chatgpt)

CLI的相关文档及帮助中心文章都推荐使用适用于VS Code、Cursor、Windsurf等VS Code衍生产品的IDE扩展插件。当你的团队主要使用某种编辑器进行开发，并希望将Codex集成到常规的编码流程中时，这种扩展插件无疑是理想的选择。

在以下情况下可以使用IDE扩展插件：

• 当你正在编辑文件时，希望随时能够使用Codex辅助功能。

• 无需切换工作环境即可进行代码提示和编辑操作。

• 它能够将人工编码与智能辅助编码有机地结合起来。

Codex应用程序

• 帮助中心：关于如何将Codex与ChatGPT结合使用

• 从chatgpt.com/codex下载该应用程序

OpenAI的帮助中心指出，Codex应用程序适用于macOS和Windows系统。它专为跨项目并行开发而设计，内置了工作树管理功能、技能设置机制、自动化脚本以及Git相关功能。

在以下情况下可以使用该应用程序：

• 需要同时运行多个Codex辅助工具时。

• 进行云端任务处理时，无需在终端和编辑器之间来回切换。

• 它是一个以项目为中心的任务管理平台，可用于分配和监控各项开发任务。

Codex云端服务

• 官方文档：developers.openai.com/codex/cloud

• 网页界面：chatgpt.com/codex

Codex云端服务是一种后台执行模式。它会在隔离的沙盒环境中运行各项任务，同时会使用相应的代码仓库和环境配置。这种服务更适合用于生成可供审核的代码结果，而非进行实时的交互式操作。

在以下情况下可以使用Codex云端服务：

• 当你需要在做其他事情的同时后台运行某些任务时。

• 需要在一个沙盒环境中执行代码，并能查看修改前后的差异时。

• 适用于自动化代码审核或团队级的工作流程管理。

代码审查

• 帮助中心：关于如何使用Codex进行代码审查

• Codex的应用场景示例

Codex还可以用于审查GitHub上的代码。OpenAI将这种方式描述为一种可以自动审核你的个人拉取请求，或在团队层面配置代码审核流程的方法。

在以下情况下可以使用代码审核功能：

• 让其他人帮忙检查拉取请求中的问题。

• 在人工审核之前，利用自动化工具检测回归错误或潜在问题。

• 在整个团队范围内实现轻量级的代码审核机制。

第4节：入门指南：安装、配置及第一个任务

本节会引导你从“什么都没有安装”的状态，逐步完成设置，直到“Codex帮我修复了一个实际存在的错误”这一目标。

我们会使用一个由你自己在两分钟内搭建好的小型演示仓库——这个仓库包含一个存在明显错误的Python价格计算器程序，以及一个缺失的测试用例。这样的演示环境非常实用，你可以用它来练习相关操作，完成后也可以直接丢弃。

对于命令行工具、VS Code扩展程序以及Codex应用程序，同样的安装指南也适用，不过每种方式会有相应的使用说明。

如果你已经有自己想要使用的代码库，可以直接跳到第4步，让Codex直接处理你的代码库。这个演示版本主要是为那些希望从一个可靠的起点开始学习的用户准备的。

步骤0：确认访问权限

Codex被包含在ChatGPT Plus、Pro、Business以及Enterprise/Edu套餐中。在有限的时间内，Free和Go套餐也包含了这一功能，不过使用这些套餐时访问权限会受到更严格的限制。

如果你是在团队或企业工作环境中使用Codex，那么访问权限可能还取决于工作环境的设置及基于角色的权限控制机制。请不要认为仅仅拥有ChatGPT的订阅资格就一定能在受管理的环境中使用Codex——请务必向你的管理员确认，或者直接查看chatgpt.com/codex页面上的Codex Cloud设置。

步骤1：安装Codex

你有三种安装方式可以选择。先选择其中一种开始使用吧，其他方式以后再添加也可以。

选项A：命令行工具（推荐用于第一个任务)

命令行工具是了解Codex功能的最直接方式。官方文档指出，macOS和Linux系统上使用Codex效果最佳，而Windows系统上的使用目前仍处于测试阶段，建议使用WSL2环境。

npm i -g @openai/codex
codex --version

如果执行codex --version后能够看到版本号，那就说明安装成功了。

选项B：VS Code扩展程序

在VS Code中，打开“扩展”面板，通过搜索“Codex”来找到并安装该扩展程序。或者也可以在终端中执行以下命令进行安装：

code --install-extension openai.chatgpt

安装完成后，Codex扩展程序会出现在右侧边栏中。

选项C：Codex应用程序

你可以在chatgpt.com/codex页面下载适用于macOS或Windows系统的Codex应用程序。当你需要同时处理多个任务、使用内置的Git工作区功能，或者希望拥有以项目为中心的用户界面时，这个应用程序会非常有用。不过对于你的第一个任务来说，使用它可能有些过于复杂了——建议先从命令行工具或扩展程序开始学习吧。

VS Code用户： 如需了解涵盖VS Code三种使用方式的详细步骤指南（扩展程序、集成终端中的CLI命令以及浏览器版Codex），请参阅附录E：在VS Code中使用Codex。

步骤2：进行身份验证

在终端中运行codex命令（或打开扩展程序面板）。系统会提示您选择以下方式之一进行登录：

• 使用ChatGPT登录——推荐这种方式。使用该选项时，费用将从您的计划所包含的Codex积分中扣除。

• 使用API密钥登录——当您需要按使用量计费，或者工作区政策有此要求时，可以选择这种方式。

如果您不确定该选择哪种方式，建议选择“使用ChatGPT登录”。

步骤3：创建演示仓库

大多数快速入门指南都会跳过这一步。我们不会让Codex直接处理“任意仓库”，而是会创建一个包含已知缺陷的、独立的演示仓库，这样您就可以验证Codex确实能够修复这些缺陷。

在终端中运行以下命令：

mkdir codex-demo && cd codex-demo
git init

接下来创建三个文件。首先是pricing.py——这个文件包含一个简单的定价计算器，其中存在一个逻辑错误以及一个被忽略的边界情况：

# pricing.py
def apply_discount(price: float, discount_percent: float) -> float:
    """对价格应用百分比折扣。

    BUG：当前折扣是按照(discount_percent / 10)来计算的，而不是(discount_percent / 100)。因此，20%的折扣实际上会使价格翻倍，而非降低。

    """
    if discount_percent < 0:
        raise ValueError("discount_percent必须大于或等于0")
    return price * (1 - discount_percent / 10)


def cart_total(items: list[dict], discount_percent: float = 0) -> float:
    """计算打折后购物车中所有商品的总价。"""
    subtotal = sum(item["price"] * item["quantity"] for item in items)
    return apply_discount(subtotal, discount_percent)

然后是test_pricing.py——这个文件包含一个通过测试，以及另一个因为上述缺陷而会失败的测试：

# test_pricing.py
from pricing import apply_discount, cart_total


def test_no_discount_returns_original_price():
    assert apply_discount(100.0, 0) == 100.0


def test_twenty_percent_discount_on_100_is_80():
    # 在apply_discount函数中的缺陷被修复之前，这个测试会失败。
    assert apply_discount(100.0, 20) == 80.0


def test_cart_total_with_discount():
    items = [
        {"price": 10.0, "quantity": 2},
        {"price": 5.0, "quantity": 1},
    ]
    # 子总价为25.0元。打9折后，预计总价应为22.5元。
    assert cart_total(items, discount_percent=10) == 22.5

最后是README.md文件：

# codex-demo

这是一个用于学习Codex使用方式的简单定价示例模块。

运行测试命令：`python -m pytest`

将初始状态提交到版本控制系统中，这样Codex生成的差异对比文件就便于查看了：

git add .
git commit -m "初始演示：包含已知缺陷的定价模块"

在请求Codex修复该缺陷之前，先确认这个缺陷确实存在：

python -m pytest

你应该会看到有两个测试失败（test_twenty_percent_discount_on_100_is_80和test_cart_total_with_discount）。

如果还没有安装pytest，可以执行pip install pytest。完整的演示功能只需要Python 3.10及以上版本以及pytest即可。

步骤4：启动Codex并运行你的第一个任务

现在将Codex指向这个演示代码仓库。

通过命令行界面操作：

cd codex-demo
codex

当Codex启动后，给它一个具体且范围明确的任务。请严格按照以下提示输入指令：

测试套件中有两个测试失败了。请阅读pricing.py和test_pricing.py文件，找出问题的根本原因，然后修复最简单、最容易实现的问题部分，之后再运行测试以确认问题是否已经得到解决。同时，请说明你做了哪些修改以及为什么这样做。

Codex会执行以下操作：

1. 检查pricing.py和test_pricing.py文件。

2. 发现那个“差1”的错误（应该是/ 100而不是/ 10）。

3. 生成一条用于修改代码的差异对比信息。

4. 在修改文件之前，会请求你进行确认（默认情况下会这样操作）。

5. 得到你的确认后，它会运行python -m pytest命令，并告诉你三个测试现在都通过了。

通过VS Code扩展程序操作：在VS Code中打开codex-demo文件夹，然后在右侧边栏中打开Codex面板，输入相同的指令。差异对比信息会直接显示在编辑器中，你可以查看并接受这些修改。

步骤5：审核差异对比结果

养成这个习惯非常重要。即使所做的修改只涉及一个字符的更改（比如将10改为100），在接受这些修改之前也一定要先查看差异对比结果：

git diff

仔细阅读这些修改内容，确认它们与Codex给出的描述一致。然后你自己再运行测试：

python -m pytest

三个测试都应该能够通过。最后将这个修改提交到版本控制系统中：

git commit -am "修复了在应用折扣时出现的‘差1’错误"

你刚刚完成了整个Codex流程：了解背景 → 明确任务 → 进行修改 → 审核差异 → 确认效果。任何规模更大的任务，其实都是这个流程的延伸。

步骤6：再尝试两个具体且范围明确的任务

既然这个流程已经可以正常使用了，现在就用同一个演示代码仓库来尝试另外两个任务：

1. 添加一个边界条件测试。提示内容如下："请添加一个测试用例，用来验证当discount_percent为负数时，apply_discount函数是否会引发ValueError异常。修改完成后请重新运行所有测试。

2. 补充一项缺失的安全检查措施。提示内容如下："目前apply_discount函数并没有拒绝那些discount_percent值大于100的输入，这样会导致价格计算结果为负数。请添加相应的验证逻辑，如有必要的话，请更新现有的测试用例，并为这种新的行为添加一个新的测试用例。

每个任务规模都很小，都有明确的通过标准（测试必须通过），并且会生成可供审核的代码差异文件。这就是每一个优秀的Codex任务的典型特征。

步骤7（可选）：配置Codex Cloud

云任务允许你在处理其他工作的同时让Codex在后台运行。这些任务需要一个托管在GitHub上的仓库。

要为演示仓库启用Codex Cloud，请按照以下步骤操作：

1. 将codex-demo仓库推送到一个私有的GitHub仓库中：gh repo create codex-demo --private --source=. --push（需要使用gh命令行工具）。

2. 访问chatgpt.com/codex，然后连接ChatGPT GitHub连接器。

3. 在连接器中允许codex-demo仓库被使用。默认情况下不要授予全局访问权限——具体请参阅附录C。

4. 通过网页界面选择该仓库，然后按照提示操作："为pricing.py文件中的每个函数添加类型提示"，并生成一份符合CI流程的变更摘要。"

5. 等待沙箱环境完成处理，在浏览器中查看代码差异文件，然后选择接受这些变更或提交一个PR请求。

默认情况下，Codex Cloud沙箱环境没有互联网访问权限。这是有意为之的设计——如果实际工作流程确实需要依赖某些外部资源，管理员可以手动允许这些资源的访问。

何时使用哪种工具界面

完成演示环节后，各种工具界面的适用场景就会变得清晰起来：

• 命令行工具——对于那些需要大量在终端中执行的操作来说，这是最快的选择；同时它也支持脚本编写，特别适合那些需要多步骤执行且需要明确审批流程的任务。

• VS Code扩展程序——当你已经在使用VS Code编辑器时，使用这个扩展程序进行代码编辑会带来最少的干扰。

• Codex应用程序——当你需要在多个项目中同时运行并行任务，并且需要确保各个项目之间的工作环境相互独立时，这个应用程序是非常合适的。

• Codex Cloud——最适合用于后台作业、耗时较长的任务，以及那些可以持续运行的PR评审流程。

大多数经验丰富的用户都会安装所有这些工具，然后根据具体任务的需要来选择使用哪种工具。因为很少有某种工作流程能够适用于所有情况。

如果遇到问题怎么办？

如果在执行这些操作时遇到了困难，请尝试以下解决方法：

• 如果找不到codex命令，可能是因为npm的全局bin目录没有添加到你的系统路径中。请重新启动终端，或者使用像nvm这样的Node版本管理工具。

• 如果登录一直失败，请确认输入的电子邮件地址与你的ChatGPT账户信息是否一致；在企业工作环境中，可能需要管理员来启用Codex功能。

• 如果Codex无法修改文件，可能是因为你处于严格的审批模式下。请按照提示进行审批，或者在完成第一个成功的任务后解除这个模式。

• 如果在Windows系统中遇到问题，可以尝试切换到WSL2终端环境。因为对于命令行工具来说，原生Windows版本目前还处于测试阶段。

完整的故障排除指南位于第12节中。

第5节：如何有效使用Codex

只有将Codex视为需要引导学习的工具，而非能够自动生成解决方案的魔法程序，它才能发挥最佳效果。你的任务描述越具体，得到的结果就会越好。

以下每一条建议都包含了错误示例（人们实际会输入的内容）和正确示例（能够产生有效结果的输入方式）。大多数示例都是使用来自第4节的codex-demo代码库来演示的，因此你可以亲自尝试运行这些示例。

为任务设定明确的目标

“明确的目标”是指具有可验证结果的具体目标，而不是某种主观感受。

错误示例：

改进这个代码库。

Codex会自动选择一些操作来执行，但你无法确定最终结果是否符合预期，而且修改的内容可能非常多，超出了你能够审查的范围。

正确示例：

重新编写pricing.py中的cart_total函数，将迭代逻辑和折扣计算分别放在两个独立的辅助函数中。保持cart_total函数的公开接口不变，并为这两个辅助函数编写测试用例，最后运行pytest进行验证。

这种做法之所以有效，是因为它有一个明确的验收标准（新代码结构通过测试）和一个清晰的边界条件（公开接口保持不变）。你可以在30秒内完成对修改内容的审查。

其他有效的表达方式还包括：

• "修复test_pricing.py::test_twenty_percent_discount_on_100_is_80中出现的错误。

• "在cart_total函数中添加一个currency: str = 'USD'参数，并更新相应的测试用例。

• "检查我上一次提交的代码中是否遗漏了某些边缘情况。”

提供正确的上下文信息

虽然Codex可以自动分析代码库，但你仍然需要指明它应该关注哪些文件以及遵循哪些约束条件。如果没有这些指导，它就会无所适从。

错误示例：

为pricing模块添加验证机制。

但具体应该进行什么样的验证？针对哪些输入数据？使用哪种错误处理方式？这些信息Codex都无法自行判断。

正确示例：

上下文信息：
- 文件：pricing.py
- 函数：apply_discount
- 当前行为：当discount_percent为负数时，会抛出ValueError异常。
- 期望的行为：当discount_percent大于100时，也应抛出ValueError异常，并显示“discount_percent必须在0到100之间”的提示信息。

任务：
- 为apply_discount函数添加验证机制。
- 在test_pricing.py中编写相应的测试用例。
- 确保apply_discount函数的公开接口保持不变。
- 完成修改后运行pytest进行测试。

注意这个示例的结构：涉及哪个文件、当前存在的问题、期望达到的效果、具体任务内容、需要遵循的约束条件以及验证方法。正是这样的结构，才能让提示信息变得有用，而不会只是含糊不清的建议。

对于规模较大的任务，还需要包括以下内容：

• 问题的链接或相关规范文件（如果启用了网络访问功能，Codex能够自动获取这些信息）。

• 相关文件的名称——即使Codex本身可以找到这些文件，明确列出它们的名称也能将首次编辑所需的时间缩短一半。

• 任何需要执行的测试命令、构建命令或代码检查工具的名称。

在必要时要求进行中间层思考

“中间层思考”意味着让Codex在编辑文件之前先以书面形式制定计划。默认情况下，Codex会直接开始修改代码。但对于任何涉及多个功能的部分来说，这种默认设置都是不合适的。

如果不进行中间层思考：

修改pricing.py文件以支持多种货币。

Codex会立即开始编辑代码。事后你会发现，它改变了数据库结构、API接口以及三个测试文件的内容——但你根本不知道它所做的这些设计选择是否正确。

如果进行中间层思考：

我想为pricing.py添加多货币支持功能。

在开始修改之前：
1. 列出所有可能会被修改的文件以及修改的原因。
2>用5到10条要点来概述具体的修改方案。
3>说明你所做的一些假设以及还存在哪些未解决的问题。
4>找出这次修改中最容易出问题的部分。
在得到我的批准后再进行任何修改。

这样，你就能得到一个可以仔细审查、提出修改意见或直接放弃的修改计划——而且这对代码库本身没有任何负面影响。一旦你批准了这个计划，Codex就会按照这个计划来执行修改操作，因此最终的修改结果也是可以预见的。

在任何以下情况下，都应该进行中间层思考：

• 涉及多个文件或需要跨多个模块进行修改时。

• 当这种修改对当前代码库的结构来说属于创新性操作时。

• 修改内容难以进行测试时（因为只有通过测试结果才能判断修改是否正确）。

• 如果修改失败，其影响范围会非常广时（比如涉及认证系统、支付功能或数据迁移等操作）。

优先选择范围明确的修改

所谓范围明确的修改，是指具备以下四个特征的修改：

1. 影响范围小——只涉及一个文件、一个模块或一个逻辑概念。

2. 有明确的验收标准——存在特定的测试用例、输出结果或行为表现，能够证明修改是成功的。

3. 可以在几分钟内完成审查——人类阅读修改后的代码差异后，无需花费一小时的时间就能形成判断。

4. 易于回滚—如果修改出了问题，使用git revert命令就可以轻松地恢复到修改前的状态，而不会影响其他部分的功能。

与之相反的是范围不明确的修改：比如“让代码库运行得更快”、“对API进行现代化改造”或“在所有地方添加类型定义”等等。这类修改没有明确的结束点，也难以验证其正确性，更没有便捷的回滚途径。

范围明确的修改示例（好的修改方式）：

• 在CartItem类中添加一个serialize()方法，该方法应返回一个适合进行JSON编码的字典。同时需要编写相应的测试用例。

• 在apply_discount方法中，将硬编码的数字100替换为模块级别的常量MAX_DISCOUNT_PERCENT。

• cart_total函数目前接受一个名为discount_percent的参数，默认值为0。现在应将该默认值改为None，并将None视为“不享受折扣”的情况。同时需要更新相关的测试用例。

应避免使用的不具体指令示例：

• “将pricing.py修改为可用于生产环境。”

• “在所有地方添加适当的错误处理机制。”

• “改进代码架构。”

当你发现自己正在编写不具体的指令时，应在发送之前将其分解为一系列具体、可操作的步骤。进行这种分解本身就是最重要的工作；一旦完成了这个步骤，Codex就能很好地执行每一项后续任务。

将评审流程作为循环来使用

Codex不仅仅用于编写代码，它还可以作为一种非常有用的预合并代码审核工具。具体的使用流程如下：

1. 你（或Codex）编写代码变更内容。

2. 让Codex对这些变更进行审核。

3. 针对Codex指出的问题进行修改。

4. 重新运行测试。

实际操作中的流程如下：

在完成codex-demo中的某项任务后，可以让Codex审核你自己的代码提交：

请审核我上次提交的代码变更（使用git show HEAD命令查看）：
- 检查是否存在正确性方面的问题，例如数值计算错误、类型不匹配或默认值设置不当；
- 确认是否缺少测试用例，尤其是针对边界情况的测试；
- 评估是否存在安全风险，比如输入验证问题、注入攻击隐患或不安全的默认设置；
- 分析代码的可维护性，例如变量命名是否清晰、模块之间的耦合程度如何。

请根据问题的严重性对发现的问题进行优先级排序。对于每一个问题，请指出具体的错误位置，并提出相应的修改方案。在这一轮审核过程中，不要直接修改任何文件，只需生成审核报告即可。

你通常会收到如下结构的回复：

严重问题：第14行——函数apply_discount在类型检查时忽略了NaN值，因为`discount_percent < 0`这个条件对于NaN来说是不成立的。解决方法是在比较之前添加一个显式的math.isnan()判断语句。

重要问题：test_pricing.py脚本中没有针对折扣百分比为100这种情况的测试用例。需要添加一条测试，确保apply_discount(100, 100)的结果为0。

建议改进的地方：第8行的文档字符串中提到了一个“BUG”，但由于这个错误已经得到修复，因此应该将这条注释删除。

接下来你需要对这些反馈进行分类处理：立即修复严重和重要的问题（通常可以通过再次让Codex执行修改建议来完成），对于那些建议改进的小问题则可以暂时不予处理或直接拒绝它们，最后重新运行测试用例。

通过这种方式，Codex就从单纯的代码生成工具转变成了一个质量把控工具，而这种用途通常能带来更大的价值。如果一个团队仅仅将Codex用作代码生成工具，那么他们的编码速度可能会加快；但如果同时利用它来进行代码审核，那么他们的代码质量将会得到显著提升。

第6节：Codex与其他编程工具的区别

对于新用户来说，这一节的内容往往最为重要，因为不同编程工具之间的界限很容易被混淆。

Codex是一个产品层，而不仅仅是一个模型

Codex实际上代表了用户的编码体验和整个工作流程。而各种编程模型则属于底层支撑技术。换句话说：

• 一般的模型用于回答问题或生成文本。

• 而专门的编程模型则是为软件开发任务量身定制的。

• Codex将这些模型整合到了一个包含文件、命令、审批流程、测试环境以及代码审核机制的完整工作流程中。

这一点很重要，因为用户在比较Codex时，常常会将其与“另一种模型”相提并论，而实际上应该将它们视为“不同的编码系统”。

Codex与OpenAI通用模型的对比

OpenAI目前的模型推荐页面将GPT-5.4列为用于复杂推理和编码的旗舰模型。这就是从通用模型角度给出的建议。

而专门介绍Codex的页面则将GPT-5.3-Codex、GPT-5.2-Codex这类模型描述为专为在Codex或类似环境中进行编码任务而优化的模型。

实际使用建议如下：

• 如果你需要一款顶级的通用模型，那就选择GPT-5.4。

• 如果你需要一款专为Codex内的编码工作流程设计的模型，那就选择针对Codex优化的模型。

• 如果你不仅需要文本输出，还需要文件编辑、shell命令执行、代码审查以及沙箱测试功能，那么Codex才是你的最佳选择。

Codex与Claude Code的对比

Claude Code同样是一款基于终端的编码工具。Anthropic在其文档中将其描述为一种能够制定计划、编辑文件、运行命令、创建提交记录，并能处理与MCP连接的数据源的工具。如果你所在的团队已经习惯使用终端进行工作，且需要一款具备强大脚本编写功能的开发工具，那么Claude Code会是一个不错的选择。

Codex在以下几个方面有所不同：

• Codex提供了更丰富的使用场景，包括命令行界面、IDE扩展程序、移动应用、云服务以及代码审查功能。

• Codex的云服务基于与GitHub连接的任务执行和代码审查机制来运作。

• Codex被明确定位为一系列编码工作流程的工具，而不仅仅是一个单纯的终端工具。

实际使用建议如下：

• 如果你希望拥有一个以终端为基础、具备高度可组合性的开发工作流程，并且主要喜欢在shell环境中进行操作，那么Claude Code是你的最佳选择。

• 如果你需要一款功能更全面的工具，能够支持本地环境、云服务以及移动应用中的编码工作流程，并且希望整个团队都能使用这套工具，那么Codex才是更适合你的选择。

Codex与GitHub Copilot Coding Agent的对比

GitHub Copilot Coding Agent是围绕GitHub自身的工作流程设计的。GitHub在其文档中将其描述为一种可以用来分配问题或拉取请求的任务管理工具，它会在后台自动创建或修改拉取请求。这款工具非常适合在由GitHub托管的开发环境中使用。

Codex在侧重点上有所不同：

• Copilot Coding Agent非常以GitHub为中心设计。

• Codex的功能覆盖范围更广，包括终端、IDE、移动应用以及云服务。

• 如果你的团队已经将GitHub作为任务分配和代码审查的核心平台，那么Copilot Coding Agent会是一个非常合适的选择。

• 如果你需要一个功能更为全面的编码工具，能够在本地环境、IDE以及云服务中都能正常使用，那么Codex会更适合你。

实际使用建议如下：

• 如果你的开发流程已经深度依赖于GitHub的问题管理和拉取请求功能，那么Copilot Coding Agent是你的最佳选择。

• 如果你需要一个功能更全面的编码工具，能够在本地环境、IDE中或Codex云服务中运行，那么Codex才是更适合你的选择。

Codex与开放权重模型及自托管模型的对比

开放权重模型或自托管模型能满足不同的需求。当团队有以下需求时，通常会选择这些模型：

• 能够完全控制基础设施。

• 希望进行自定义托管或采用隔离环境进行部署。

• 希望能更直接地掌控数据保留策略及数据边界的管理。

• 如果团队已经拥有相应的硬件和运维资源，那么在大规模应用这些模型时成本会更低。

不过，自托管模型通常无法提供Codex所具备的即开即用的使用体验。用户需要自行搭建调度机制、配置代码库访问权限、设置沙盒环境，并处理审批流程等事宜。

因此，真正的选择标准并不是“哪种模型最智能”，而是“我愿意在围绕该模型的工作流程上投入多少精力进行定制开发？”

实际应用建议如下：

• 当基础设施控制是主要需求，并且你愿意自行构建相关的辅助系统时，可以选择开放权重模型或自托管模型。

• 对于那些需要即开即用的工作流程的团队来说，Codex是更好的选择。

Codex与通用聊天模型的对比

当任务需要以下功能时，通用聊天模型会更加适用：

• 进行问答交流。

• 进行概念性推理。

• 撰写文章或段落。

• 总结或改写文本。

而当任务需要以下功能时，Codex会表现得更好：

• 阅读和修改代码库中的内容。

• 运行测试。

• 修复代码错误。

• 审核拉取请求。

• 协调多步骤的实施工作。

相同模型在不同接口下的使用差异

同一系列的模型，在不同的使用界面下，其功能和表现也可能会有所不同。

• 通过API直接调用模型时，你可以自行设计调度流程。

• 而在Codex中，相同的或类似的模型可能需要结合代码库访问权限、审批流程以及任务执行机制才能发挥作用。

因此，有些模型页面会注明“该模型适用于‘Codex’或类似的环境”。虽然这些模型是为辅助软件开发而优化的，但具体的使用界面仍然非常重要。

对比矩阵

以上各项对比内容可以汇总成一张表格，以便快速查阅：

。

比较维度	Codex	Claude Code	GitHub Copilot Coding Agent	自托管/开放权重模型
主要使用界面	命令行接口、集成开发环境、应用程序、云平台	仅支持命令行接口	GitHub网站/拉取请求/问题管理系统	用户可自行选择任何使用界面
后台执行能力	支持（Codex Cloud的沙盒环境）	有限，仅在本地运行	支持（GitHub Actions的执行器）	需用户自行配置
与代码库的集成程度	通过GitHub连接器集成；也可直接使用本地代码库	仅支持本地代码库，且需要连接MCP源代码库	原生支持GitHub接口	需用户自行配置
可使用的模型种类	OpenAI提供的模型，可根据不同界面进行选择	Anthropic Claude系列模型	由GitHub管理的多种模型	任何你能自行托管的模型
审批与沙盒控制功能	支持，且根据使用界面不同而有所差异	支持，但每个工具都有各自的设置机制	遵循GitHub的权限管理规则	需用户自行配置
能否同时运行多个辅助进程	支持（在应用程序和云平台上）	有限	支持（针对每个拉取请求单独运行辅助进程）	需用户自行配置
最适合的应用场景	跨不同界面的团队协作工作流程	习惯在终端环境中工作的资深用户	已经熟悉GitHub平台的团队	需要使用隔离环境、自定义基础设施，或希望在大规模应用时控制成本的用户
主要缺点	受OpenAI生态系统的限制；价格档次较高	可使用的功能界面相对较少	与GitHub的耦合程度过高	需要投入大量的开发工作来进行定制配置

可以使用这个矩阵来选择最合适的工具，然后将其他工具根据实际情况进行搭配使用。许多团队确实会同时使用其中两种工具——例如，使用Codex处理跨平台的工作任务，而使用Claude Code来满足高级用户的需求。

新用户应该选择哪种工具呢？

作为一个参考原则：

• 对于以终端为中心的编码和脚本编写工作，Claude Code是一个非常不错的选择。

• 对于需要利用GitHub内置的功能来实现问题处理和拉取请求自动化的工作场景，GitHub Copilot是更为合适的选择。

• 对于那些需要在本地、云端以及基于应用程序的环境中协同工作的团队来说，Codex是最具灵活性的工具。

• 如果希望对基础设施拥有更大的控制权，那么选择自行托管或使用开放源代码的技术栈会更为合适。

OpenAI的官方文档目前将GPT-5.5列为主要的旗舰产品，而GPT-5.4、GPT-5.4-mini和GPT-5.4-nano则作为次要选项提供。至于Codex，其官方文档和模型页面会详细介绍针对Codex设计的特定变体以及如何在命令行界面中切换不同的模型。

第7节：定价与计划访问权限

由于定价政策可能会发生变化，因此这一部分的内容应被视为当前官方文档中的临时信息。

计划访问权限

根据OpenAI目前的帮助中心说明，Codex被包含在以下套餐中：

• ChatGPT Plus

• ChatGPT Pro

• ChatGPT Business

• ChatGPT Enterprise/Edu

在有限的时间内，Codex也被包含在Free和Go套餐中，不过这些套餐属于临时性的例外情况，且会受到使用频率的限制。

灵活的定价机制与积分制度

目前的定价表显示，从2026年4月2日起，Codex的定价方式发生了变化，不再单纯按照每条消息的费用来计算，而是根据使用的API令牌数量来收费。相关说明还指出：

• 新老的Plus和Pro套餐用户都会使用基于令牌的定价机制。

• 新老的Business套餐用户也会使用基于令牌的定价机制。

• 新注册的Enterprise套餐用户也会使用基于令牌的定价机制。

• 现有的Enterprise/Edu套餐以及其他一些传统套餐类别，在完成升级之前，仍然会沿用原有的定价方式。

这一点非常重要，因为同一家公司内的不同团队，可能会因为工作空间状态或所选择的套餐类型的不同，而适用不同的定价规则。

当前模型的定价情况一览

目前的模型页面会列出每100万令牌对应的费用。具体价格会根据您选择的模型不同而有所差异：

• GPT-5.5：输入500万个令牌，输出30个结果。自2026年4月23日起成为新的旗舰产品。

• GPT-5.5 Pro：输入300万个令牌，输出180个结果。适用于要求较高的智能助手和推理任务。

• GPT-5.4：输入250万个令牌，输出15个结果。

• GPT-5.4-mini：输入75万个令牌，输出4.5个结果。

• GPT-5.4-nano：输入20万个令牌，输出1.25个结果。

• GPT-5-Codex：输入125万个令牌，输出10个结果。

• GPT-5.2-Codex：输入175万个令牌，输出14个结果。

• GPT-5.1-Codex-mini：输入25万个令牌，输出2个结果。

• codex-mini-latest：输入150万个令牌，输出6个结果。

这些模型页面还会说明上下文窗口的相关信息、输出字数限制，以及该模型是专为Codex平台设计还是通用API设计的。在制定预算时，请记住：较长的输出结果所产生的费用往往远高于输入请求所消耗的成本，因此任务的具体设定与模型选择同样重要。

需要注意的是，GPT-5.5的输入成本和输出成本都是GPT-5.4的两倍，而GPT-5.5 Pro的价格则更是高出许多。OpenAI表示，GPT-5.5在token使用效率方面也优于GPT-5.4，这一优势可以在一定程度上弥补价格上的差异。但在实际应用之前，你仍需要根据自己的工作需求来验证这一点。对于专为Codex平台设计的模型来说，随着基于GPT-5.5的Codex变体版本的推出，相关模型阵容可能会发生变化；在那些版本上市之前，上述列出的这些模型仍然适合用于纯粹与编码相关的任务。

实际应用中的意义

实际成本取决于以下因素：

• 输入数据的规模。

• 是否使用了缓存过的输入数据。

• 输出结果的长度。

• 任务是否采用了快速处理模式。

• 你选择了哪种模型。

因此，如果你计划在整个团队中推广使用这些模型，就不要仅根据“请求次数”来估算成本。而应该根据预期的token消耗量以及任务类型来进行估算。

旧版定价政策

对于那些尚未迁移至新定价体系的用户和工作空间来说，旧的定价表仍然具有参考意义。重要的是要明白：现在的定价机制与模型实际使用量之间的关系更为紧密，而不再简单地取决于请求消息的数量。任何打算使用Codex平台的人，在制定内部收费规则或使用政策之前，都应该先仔细阅读当前的定价表。

成本计算示例

定价表格往往容易让人看错意思，通过具体的计算示例可以让模型选择的问题变得更加清晰明了。

场景示例：一个由30名工程师组成的团队使用Codex Cloud来进行自动化的Pull Request审核工作。每位工程师每周大约会处理4个PR请求。每次审核过程中会消耗约30,000个输入token（包括差异代码及相关上下文文件），同时会产生约3,000个输出token（审核评论和风险分析结果）。

每周的token使用量如下：

• 每周审核次数：30名工程师 × 4个PR请求 = 120次审核

• 每周输入token数量：120次审核 × 30,000个token/次 = 3.6百万个token

• 每周输出token数量：120次审核 × 3,000个token/次 = 36万个token

按模型划分的每周成本如下：

)

模型	输入成本	输出成本	每周总成本	年化成本（52周计算）
GPT-5.5 (\(5 / 30\))	3.6百万 × \(5/1百万 = 18.00\)美元	0.36百万 × \(30/1百万 = 10.80\)美元	28.80美元	1,498美元
GPT-5.5 Pro (\(30 / 180\))	108.00美元	64.80美元	172.80美元	8,986美元
GPT-5.4 (\(2.50 / 15\))	9.00美元	5.40美元	14.40美元	749美元
GPT-5-Codex (\(1.25 / 10\))	4.50美元	3.60美元	8.10美元	421美元
GPT-5.1-Codex-mini (\(0.25 / 2\))	0.90美元	0.72美元	1.62美元	84美元

解读这些数据： 当使用量达到一定规模时，GPT-5.5所带来的成本冲击就会减弱——对于需要30名工程师来进行自动化代码审查的工作来说，每年花费不到1,500美元其实只是工程人力成本的微不足道的一部分。而GPT-5.5 Pro的价格则是前者的6倍，因此对于常规的代码审查工作而言，使用它并不划算；只有在对那些需要高级功能的特殊审查任务中，才应该考虑使用它。针对Codex平台专门开发的模型价格要低得多，如果你的代码审查工作主要是涉及格式检查、修复明显错误或补充缺失测试等内容，那么这些模型才是更合适的选择。

但这个例子没有考虑到以下因素：

• 重复输入带来的成本节省。 如果在代码审查过程中反复使用相同的上下文文件，实际花费会低于显示的数值。

• 复杂任务所需的额外资源。那些需要多次读取文件或进行迭代处理的任务，所消耗的资源会比一次性完成的代码审查多得多。例如，一项编码任务的耗资可能是一个普通代码审查的5到10倍。

• 任务失败后的重试成本。如果一个任务失败后需要重新执行，其成本与初次执行时的成本大致相同。因此，系统在处理任务失败时的效率也会影响总体成本。

• 混合使用不同模型带来的优化效果。大多数经验丰富的团队会将那些耗资较低的任务（如编写测试用例、更新文档等）交给Codex-mini模型来处理，而将GPT-5.5留用于那些需要深入分析代码逻辑的复杂任务，比如针对整个代码库进行的重构工作或处理Pull Request请求。

在实际应用中，应该根据自己工作中耗时最多、成本最高的环节来制定成本预算；而对于那些确实可以从新模型功能中受益的少数任务，再专门为它们安排GPT-5.5的使用预算。

第8节：安全性、权限设置与企业级应用配置

对于团队来说，Codex不仅仅是一种提高工作效率的工具，更是一个能够被有效控制的软件开发平台。OpenAI提供的文档也充分体现了这一点。

本地访问与云访问

企业管理员可以单独启用以下功能：

• Codex本地版

• Codex云版本

• 两者同时启用

Codex本地版包括应用程序、命令行工具以及集成开发环境插件；而Codex云版本则涵盖了托管任务、代码审查及相关集成服务。

这种区分非常实用，因为有些组织希望让更多员工能够使用本地工具，但同时只允许少数用户使用云服务。

工作空间权限管理

根据管理员文档的说明，工作空间所有者可以通过角色基访问控制机制来管理用户的访问权限。他们可以：

• 设置默认角色。

• 创建自定义角色。

• 将角色分配给特定团队或用户组。

• 将用户组信息与SCIM系统同步。

• 集中管理所有权限设置。

在这种机制下，可以确保只有真正需要使用这些功能的员工才能获得相应的访问权限，从而避免给所有开发人员都赋予过高的权限。

GitHub连接器与代码库访问功能

Codex Cloud要求使用托管在GitHub上的仓库。管理员需要连接ChatGPT的GitHub连接器，选择安装目标，并允许特定的仓库被使用。Codex会使用有效期较短、权限较低的GitHub应用令牌，并且会严格遵守仓库的权限设置以及分支保护规则。

对于安全团队来说，这一点非常重要，因为这能确保Codex与你们现有的代码库访问机制保持一致。

互联网访问

默认情况下，Codex云代理在运行时并不具备互联网访问权限。这是经过刻意设计的。如果你的任务确实需要访问依赖关系注册表或可信网站，管理员可以配置允许列表并设置HTTP方法的使用限制。

推荐的治理模式

企业文档建议为用户和管理员分别创建不同的组：

• 设立一个较小的“Codex管理员组”，专门负责政策管理和治理工作。

• 设立一个范围更广的“Codex用户组”，供那些只需要使用该工具的开发人员使用。

这种划分方式有助于确保政策管理更加严谨，同时避免出现不必要的权限过度授予现象。

第9章：团队最佳实践

如果你正在带领一个团队开展工作，那么事先明确各项期望会帮助你取得更好的成果。

从简单而有价值的任务开始

适合团队初期使用的案例包括：

• 审查拉取请求。

• 修复一些小错误。

• 生成测试用例。

• 更新文档内容。

• 帮助团队成员熟悉代码库的结构。

这些任务都很容易与人工工作进行对比，也便于评估其完成质量。

统一任务提示格式

应为所有人提供统一的任务提示模板。例如：

任务：修复X中的故障测试用例。
背景信息：问题是在Y之后出现的。
注意事项：不要更改公共API的功能。
输出要求：说明问题的根本原因，应用相应的修复措施，运行测试，并总结可能存在的风险。

这样就能让结果更便于审查，同时也能减少因提示格式不一致而影响团队使用效率的情况。

培养评审文化

Codex不应取代传统的代码评审流程。应将其视为：

• 辅助开发者完成初步实现的工具。

• 在正式评审之前的预审工具。

• 一种有助于减少重复性工作的方法。

最终，代码的架构设计、功能权衡以及最终的确认工作仍应由人类团队来完成。

关注真正重要的指标

真正有意义的指标是那些能够说明Codex是否产生了可供评审、可以合并且值得信赖的代码的指标，而不是那些仅仅反映代码开发活跃度的指标。下面列出了各项指标、如何利用现有数据来计算这些指标，以及判断这些指标“是否正常”的参考标准。

1. 产生可应用修改结果的时间

定义：从开始执行Codex任务那一刻起，到它生成出人类认为可以实际应用的修改结果为止所花费的时间（在此过程中可能还需要进行一些小的调整）。

测量方法：

• 对于通过 CLI/IDE 执行的任务，需要记录从提交命令到生成第一个差异文件所花费的实际时间。Codex CLI 会生成结构化日志，这些日志可以方便地被解析；使用一个简单的脚本即可实现这一功能：

  start=\((date +%s); codex "<prompt>>"; echo "elapsed: \)(( $(date +%s) - start ))s"

• 对于在 Codex Cloud 上执行的任务，可以直接使用 chatgpt.com/codex 控制面板中显示的任务耗时，或者从工作区使用情况的数据中获取相关信息。

• 在第一个月内，需要在共享的电子表格中将每项任务标记为“有用”或“被丢弃”；之后可以根据需要选择性地进行统计分析。

正常值： 对于有明确边界的任务，处理时间应低于2分钟；对于涉及多文件的代码重构任务，处理时间应低于10分钟。如果实际数值远高于这些标准，那么你的提示信息很可能缺乏必要的上下文信息（详见第5节）。

2. Codex生成的变更通过测试的比率

定义： 在Codex生成的差异代码中，有多少比例在首次测试时就通过了现有的测试套件。

测量方法：

• 在持续集成环境中，可以为那些由Codex生成的拉取请求添加标记（例如使用标签codex-authored，或在提交信息前加上相应的前缀）。然后每周运行一次简单的查询语句来获取数据：

  SELECT
    COUNT(*) FILTER (WHERE first_ci_run = 'pass') * 100.0 / COUNT(*) AS first_try_pass_rate
  FROM pull_requests
  WHERE labels @> '{"codex-authored"}'
    AND created_at > NOW() - INTERVAL '7 days';
  

• 对于本地使用情况，可以编写一个封装脚本，在Codex完成处理后立即运行你的测试命令，并记录测试的退出代码。

正常值： 对于有明确边界的任务，这一比率应高于75%；如果低于50%，说明Codex在未经验证的情况下就直接进行了代码修改——通常可以通过在提示模板中添加“处理完成后请运行测试”这样的语句来解决这个问题（详见第9节 → 规范化任务提示信息）。

3. Codex发现的问题的类型

定义： 当将Codex用作合并前的代码审核工具时，它所发现的问题中，有多少是人工审核人员也会注意到的，又有多少是只有Codex才能检测出来的，还有哪些属于误报。

测量方法：

• 请人工审核人员用三种标签之一来标记Codex给出的审核意见：agree-found-it、agree-missed-it或disagree-noise。

• 随时间跟踪这些比率的变化情况：

  • 有价值问题的比率 = (agree-found-it + agree-missed-it) / Codex给出的总评论数。

  • 独特问题比率 = agree-missed-it / Codex给出的总评论数。

• 通过在GitHub Actions中添加一个简单的步骤，发布Codex的审核结果，并要求人工审核人员用表情符号（✅、⚠️或❌）来表示他们的反馈，就可以轻松收集到这些数据。

正常值： 有价值问题的比率应高于70%，独特问题比率应高于20%。如果独特问题比率接近于零，说明Codex正在重复持续集成系统的功能，此时可以将其关闭而不会造成任何损失。

4. 无需人工修改即可完成的任务

定义： 在所有由Codex生成的变更中，有多少比例在合并后几乎保持了原有的代码结构，而没有经过人工的大幅修改。

测量方法：

• 将最初生成的差异对比文件与最终被合并的差异对比文件进行比较。最简单的检测方法如下：

  在编写了差异对比文件的分支中执行以下命令：
  git diff codex/initial-commit HEAD --shortstat
  

  如果差异对比文件生成后，原本由该工具编写的代码中有超过30%的行发生了变化，那么就应将这项任务视为“需要重新编写代码”。

• 需要每月跟踪这一数据。趋势线比具体的绝对数值更为重要。

理想状态：在第三个月时，第1至第4项指标的平均得分应高于3.5分；如果第4项指标的趋势呈下降趋势，那么无论其他指标的数据如何，这项工具的推广工作都算失败了。

5. 开发者的满意度

定义：实际使用该工具的开发者是否认为它提高了他们的工作效率，并且是否愿意继续使用它。单纯的数字数据无法反映这一情况。

测量方法：

• 每月进行一次包含5个问题的调查问卷，问卷内容要简短。建议使用的问题如下（所有问题的评分范围均为1至5分）：

  1. “这周这个工具为我节省了时间。”

  2. “我足够信任这个工具生成的差异对比结果，因此可以放心地依据它们进行代码审查。”

  3. “这个工具提供的审核意见通常很有参考价值。”

  4. “如果这个工具被撤掉，我会感到很不满意。”

  5. “目前使用这个工具时，最大的障碍是什么？”（自由回答题）

• 特别需要关注第4项指标的趋势变化。对于内部使用的工具来说，这一指标最能反映其是否真正符合用户的需求。

理想状态：在推广使用的第三个月时，第1至第4项指标的平均得分应高于3.5分；如果第4项指标的趋势呈下降趋势，那么无论其他指标的数据如何，这项工具的推广工作都算失败了。

不要测量这些指标

以下这些指标看似有用，但实际上会误导人们：

• “发送的提示信息数量”。这个指标只能反映使用频率，并不能反映实际效果。一个团队如果发送的提示信息数量是另一个团队的10倍，那么他们的工作效率可能是也高10倍，也可能是混乱程度也高了10倍。

• “消耗的令牌数量”。这个指标对预算管理有一定帮助，但对评估工具的实际效果毫无意义。使用频率高的用户并不一定就是高效的用户。

• “生成的代码行数”。与以往的类似指标一样，这个指标实际上是在奖励代码的冗长性。

• “由这个工具提交的拉取请求数量”。如果一个由这个工具提交的拉取请求最终没有被任何人合并，那么这其实是一个负面的结果，却被伪装成了正面的成果。

使用成本数据（第7节）来管理预算；使用上述指标来评估工具的普及程度。

根据不同的工作需求选择合适的工具界面

• 对于需要经常在终端上操作的场景，应使用命令行界面。

• 对于日常编码工作，应使用集成开发环境插件。

• 对于需要同时处理多个项目的场景，应使用专用应用程序。

• 对于后台任务和代码审核工作，应使用云服务平台。

通常来说，这就是“这个工具有用”与“这个工具很烦人”之间的区别所在。

第10节：常见的工作流程及示例

以下是大多数团队实际会使用的工作流程。每个流程都附带了一个实际操作示例，这些示例都是基于第4节中提供的codex-demo仓库进行的，因此你可以看到完整的指令输入、Codex产生的输出结果，以及应该如何处理这些结果。

工作流程1：在本地修复错误

适用场景：当某个测试失败，或者程序的行为出现异常，且问题的根源仅存在于某个文件或函数中时，可以使用此流程。

操作步骤：

1. 在终端或集成开发环境中打开相应的仓库。

2. 让Codex检查出出现问题的代码路径。

3. 请求Codex提供修复方案并运行测试。

4. 查看修改前后代码的差异。

5. 运行测试套件以验证修复效果。

实际操作示例：

在codex-demo仓库中，假设有同事报告称："apply_discount函数在discount_percent大于100时会无声地返回负数结果。首先验证这个错误：

python -c "from pricing import apply_discount; print(apply_discount(100, 150))"
# 输出结果为：-50.0    —— 即出现了负数结果，但没有抛出异常

接下来启动Codex并运行以下命令：

Bug: apply_discount(100, 150)返回-50.0，而没有抛出错误。
预期结果：当discount_percent大于100时，应该会抛出ValueError异常，错误信息应为“discount_percent的值必须在0到100之间”。
任务：
- 在pricing.py文件中添加相应的验证逻辑。
- 在test_pricing.py文件中添加测试用例，确保当discount_percent=150时能够抛出ValueError异常。
- 确保现有的测试用例都能正常通过。
- 最后运行pytest并查看测试结果。

最终得到的结果：会在apply_discount函数中添加if discount_percent > 100: raise ValueError(...)这段代码，还会新增一个名为test_invalid_discount_percent_above_100的测试用例。运行pytest后，会看到所有四个测试用例都通过了。你可以使用git diff来查看修改内容，也可以自己运行python -m pytest进行确认，最后通过git commit -am "修复了当discount_percent大于100时出现的错误"来完成提交操作。

这种流程在错误范围明确且能够被重复复现的情况下效果最佳。如果你无法从命令行环境中重现这个错误，那么Codex通常也无法帮助你找到问题所在。

工作流程2：审核拉取请求

适用场景：当你或同事对代码进行了修改后，在正式提交之前，想要先快速检查这些修改是否合理、是否存在缺失的测试用例或安全隐患时，可以使用此流程。

操作步骤：

1. 让Codex扫描相关的拉取请求或被修改过的文件。

2. 检查是否存在逻辑错误、遗漏的测试用例或安全风险。

3. 将Codex的检查结果与人工审核的结果进行对比。

4. 在团队进行正式审查之前，先使用Codex作为初步筛选工具。

实际操作示例：

完成上述工作流程后，在提交拉取请求之前，让Codex先审核你所做的修改：

请审核我上次提交的变更——我在`pricing.py`文件中添加了`apply_discount`功能的验证逻辑。

需要检查的内容包括：
- 代码的正确性问题（例如边界值计算错误、错误类型不正确等）
- 是否缺少测试用例（比如当输入值为100、0、NaN或负数时是否能够正确处理）
- 安全性或稳定性方面的问题
- 确保新的验证逻辑与现有的`apply_discount`功能保持一致

将发现的问题按“严重”“重要”或“建议改进”进行分类，并针对每一类问题提出具体的解决方案。在这一阶段，请不要修改任何文件。

你可能会收到的反馈示例：

重要提示：第14行代码中的新验证规则会拒绝`discount_percent`大于100的情况，但却允许`discount_percent`等于100，这种情况下价格会变为0。虽然这种做法在技术上是可行的，但建议添加相应的测试用例来确保边界值的正确处理。需要添加的测试用例为：`test_apply_discount_at_boundary_100_returns_zero`

建议改进：新的错误提示信息中写着“值应在0到100之间”，但实际上现有的检查机制会判断数值是否大于或等于0。为了保持一致性，建议统一这两种错误提示的信息。

你需要按照“重要”类别的建议进行修改，对于“建议改进”的内容则可以暂时不处理，或者根据实际情况决定是否采纳，然后重新运行测试用例。

这种工作流程具有很高的效率，因为它能够在人类花费时间进行审核之前就发现那些明显的问题。有关如何了解这一工作流程的实际价值，请参阅第9节 → 评估工作流程的实际效果 → 了解Codex捕获的审核结果。

工作流程3：理解庞大的代码库

适用场景：当你初次接触某个代码库（或者时隔数月后再次使用它）时，需要先了解其结构，才能安全地进行修改。

操作步骤：

1. 让Codex追踪请求的处理流程。

2. 询问该代码库中的关键模块及入口点。

3. 在开始编辑任何文件之前，先获取代码结构的整体结构图。

实际操作示例：

codex-demo这个代码库规模较小，因此不需要使用这种工作流程。但我们可以举一个更现实的例子：假设你负责维护一个包含`app/`、`services/`、`models/`、`api/`等目录的代码库，其中还有80个你从未看过的文件。在Codex中打开这个代码库，然后运行以下命令：

我是这个代码库的新使用者。在不修改任何代码的情况下，请提供以下信息：
1. HTTP API的入口点是什么？
2>当有人发送POST请求到 `/users` 时，系统会依次访问哪些文件？请为每个被访问的文件写一条简短的描述。
3>数据库访问功能是集中管理的吗？是否采用了某种仓库模式？
4>我应该运行什么测试命令来验证自己所做的任何修改？
5>为了了解这个项目的开发规范，我首先应该阅读哪三份文件？

请将结果以结构化的Markdown格式呈现出来。

你将获得什么：一份可以粘贴到笔记中的Markdown格式报告。阅读推荐文件后，就可以开始使用Codex来处理实际的修改工作了。花10分钟了解这些入门信息，通常能够节省后来因混淆而导致的数小时重构时间。

这种工作流程对新员工来说尤其有用。资深工程师在首次接触不熟悉的服务时，也可以使用这种方法，从而避免破坏那些自己尚未注意到的规则或惯例。

工作流程4：并行开发功能

适用场景：当一个功能可以自然地被分解成互不干扰的独立部分时（例如API、测试代码、文档，或者前端界面、后端服务、数据迁移等）。

操作步骤：

1. 将整个任务拆分为多个子任务。

2. 分别为前端界面、API、测试代码和文档创建独立的Codex任务。

3. 审核完成后，将所有任务的输出结果合并在一起。

示例：

为codex-demo添加新的“会员折扣”功能。这项工作可以分解为三个互不依赖的环节：

子任务	执行平台	具体要求
A. 实现代码编写	终端命令行	"在pricing.py文件中添加一个loyalty_discount(price, customer_tier)函数。折扣等级包括‘青铜’（0%）、‘白银’（5%）和‘黄金’（10%）。如果遇到未知的折扣等级，就用ValueError异常进行处理。其他现有功能不要修改。"
B. 编写测试用例	Codex Cloud平台	"在test_pricing.py文件中为loyalty_discount(price, customer_tier)函数编写覆盖所有情况的测试用例，包括不同折扣等级、负价格、零价格以及小数价格等场景。注意不要修改pricing.py文件——假设这个函数已经存在。
C. 编写文档	VS Code扩展程序	"在README.md文件中添加专门介绍新功能的章节，内容包括函数签名、折扣等级信息以及使用示例。"

这三个任务可以同时并行执行。当所有任务都完成后，再将最终的修改结果合并起来。注意要分别审核每个部分的代码。

Codex应用程序及其云平台特别适合这种工作方式，因为它们允许用户同时启动并监控多个任务，而无需频繁切换终端窗口。虽然命令行界面也支持并行处理，但使用git worktree命令后，每个任务都会在独立的分支上运行，这样能更有效地提高效率。

工作流程5：利用子代理进行任务分解

适用场景：当一个任务规模过大，无法通过一次Codex操作完成，但可以自然地被划分为调研、规划、实施三个阶段时。

命令行界面明确支持使用子代理——即一个主任务会生成多个子任务，每个子任务的执行范围更具体，并且拥有独立的运行环境。

实例分析：

有一份错误报告称：“对于欧洲货币而言，购物车总金额有时会偏差1美分。”目前还不知道这是由于四舍五入导致的错误、货币转换问题，还是数据采集错误。此时可以启动一个分解任务来处理这个问题：

有份错误报告指出，使用欧洲货币时，购物车总金额偶尔会偏差1美分。
可以将这个任务分解为三个子任务：

1. **调查**：仔细阅读`pricing.py`文件以及所有与货币相关的代码，找出所有涉及浮点运算且结果可能与金钱数值有关的代码段。只需记录调查结果，无需立即提出修改方案。

2. **复现问题**：在`test_pricing.py`中编写测试用例，专门用来验证欧元金额是否确实会出现1美分的偏差。尽量使用最简单的场景来复现这个问题。

3. **提出解决方案**：根据第1步和第2步的调查结果，提出两种可能的修改方案（例如是改用`Decimal`类型进行计算，还是在进行四舍五入操作时调整规则），并分析每种方案的优缺点。此时还不要实际编写任何修改代码。

在确定最终采用哪种方案之前，请先等待我的指示。

为什么使用子任务会有帮助：每个子任务都在一个清晰的上下文中进行，因此调查结果不会影响到测试用例的编写过程，而提出解决方案时也能全面了解相关情况。此外，在调查和实施之间设置这样的步骤也有助于提高工作效率——这种分步处理的方式通常比一次性完成整个任务更快，而且也更容易进行审查。

这种分工方式往往能更高效地解决问题，同时也便于后续的审核工作。

提示模板集

新用户经常请求提供示例，因为他们知道自己最终想要达到的效果，但不知道该如何具体表述。这些模板为他们提供了一个很好的起点。

错误修复模板

检查[文件或模块]中出现的错误现象，找出根本原因；
然后实施最小范围且安全的修改措施；
接着添加或更新相应的测试用例；
最后总结所有更改内容以及需要注意的特殊情况。

当错误的具体表现较为明确时，可以使用这个模板来进行有条理的修复工作，而不需要重新设计整个系统。

代码重构模板

对[模块]进行重构，以提高代码的可读性并确保其功能仍然保持不变；
同时要保证外部API接口的稳定性；
在开始修改之前，先详细解释重构计划；
最后只进行最小范围的更改，以确保能够达成预期目标。

当代码本身可以正常运行，但维护起来比较困难时，可以使用这个模板来进行优化。

代码审查模板

仔细审查这些修改内容，检查其正确性、是否缺少测试用例、是否存在安全风险或维护难度；
根据问题的严重程度对发现的问题进行优先排序；
特别要注意那些可能会引起行为变化或逻辑模糊的地方。

当你希望系统能像预合并审核工具一样发挥作用时，可以使用这个模板。

功能开发模板

在[文件或子系统中实现[所需功能]；
在开始修改之前，列出所有可能会受到影响的文件；
添加相应的测试用例；
确保新的实现方式与当前的系统架构保持一致。

当任务涉及多个文件时，可以使用这种方法来清晰地了解整个规划过程。

您正确使用Codex的迹象

通常情况下，当以下情况发生时，说明工作流程是正常的：

• Codex只会生成少量、便于审查的修改内容，而不会进行大规模的重写。

• 只有当某些关键细节缺失时，模型才会要求提供进一步的说明。

• 随着功能的不断完善，测试覆盖率也会随之提高。

• 新开发者无需接受专门的培训，就能使用这个工具。

• 从提出修改请求到最终合并这些修改所需的时间较短，而且审查质量也不会下降。

而当以下情况发生时，说明工作流程存在问题：

• 提供的提示过于模糊，导致每次修改都需要进行大量的返工。

• 团队将最初的输出结果视为最终版本。

• 没有人会检查修改内容或运行测试。

• 用户总是要求“把事情做得更好”，却从未明确具体的目标。

这些迹象比单纯的使用频率更为重要。

第11节：模型规格与基准测试（GPT-5.5深度分析）

第2节介绍了GPT-5.5作为新的通用旗舰模型的特点，并给出了三个实用的建议。这一节则会对这些基准测试数据进行深入分析：这些数字具体衡量了什么，为什么它们对Codex的工作流程尤为重要，以及如何根据这些数据为不同的任务选择合适的模型。

如果您需要为团队制定预算或选择默认模型，请仔细阅读这一节的内容；如果您只是想使用Codex，也可以快速浏览一下。

为什么基准测试对模型选择如此重要

Codex允许您了解每种模型背后的实际性能。正确选择模型关键在于让模型的优势与具体任务的需求相匹配：

• 对于那些只涉及单个文件、单一功能的修改任务来说，前沿模型并不会带来太大帮助；使用Codex专用或Codex-mini变体通常会是更合适的选择。

• 而对于需要模型能够同时处理多个文件的复杂重构任务而言，长上下文处理能力就显得尤为重要了。

• 对于那些可以自动运行长达十分钟的自动化任务来说，低错误率以及强大的工具使用能力是至关重要的。

• 在代码审查场景中，低错误率同样非常重要——一个看似合理但实际上错误的审核意见，其造成的损失往往比忽略一个真正的缺陷还要严重。

以下的基准测试数据可以帮助您了解哪种模型最适合特定的任务类型。

GPT-5.5的性能亮点

已发布的基准测试结果显示，GPT-5.5在处理自动化任务和需要长上下文分析的任务时，其性能相比GPT-5.4有了显著提升——而这些正是Codex用户最常使用的任务类型。

• 知识工作能力（GDPval）——84.9%。GDPval用于评估该模型是否能够在44种职业场景中生成结构清晰、要求明确的知识成果。这一指标反映了模型的一般性能力。

• 计算机使用能力（OSWorld-Verified）——78.7%。该指标衡量模型是否能够完整地操作真实的计算机环境，与Codex Cloud沙箱测试及代理端CLI运行直接相关。

• 编码能力（Terminal-Bench 2.0）——82.7%。这是一个以终端操作为中心的编码测试项目，包含长上下文检索及计算机使用相关测试内容，是评估Codex CLI实际工作能力的最接近的公开指标。

• 客户服务工作流程能力（Tau2-bench Telecom）——98.0%。这一数值是在未进行任何调整的情况下测得的，说明该模型开箱即可用时，其工具使用能力和规则遵循程度都非常高。

• 长上下文检索能力（MRCR v2，100万令牌规模）——74.0%。这一数值相比GPT-5.4时代的36.6%有了显著提升。在需要模型将大量文件保留在工作内存中的仓库级Codex任务中，这一指标的重要性尤为突出。

• 幻觉现象出现率：独立测试结果显示，与前几代模型相比，该模型的幻觉现象出现了大约60%的减少。这一变化显著影响了评审流程及代码反馈机制的可靠性。

各评估指标的实际含义

这些评估指标容易被误解，以下是对上述各项指标的简要说明：

• GDPval：要求模型在44种职业场景中生成规范的知识成果，如法律文件、财务摘要、技术文档等。高分意味着模型能够可靠地生成结构清晰、要求明确的输出结果。这一指标用于评估模型的一般性能力，而非特定的编码能力。

• OSWorld-Verified：测试模型是否能够操作真实的桌面环境来完成实际工作流程，如打开文件、导航用户界面、执行命令等。高分说明该模型在模拟开发者桌面的沙箱环境中表现良好。

• Terminal-Bench 2.0：这是一个以终端操作为核心的编码测试项目，包含长上下文检索及计算机使用相关测试内容，是评估Codex CLI实际工作能力的最直接指标。

• Tau2-bench Telecom：用于评估复杂的客户服务类工作流程，这类流程要求模型严格遵守规则并正确使用工具。这一指标能够反映“模型是否按照指令行事，没有出现偏离预定路径的情况”。

• MRCR v2，100万令牌规模：这是一个长上下文检索测试项目，用于评估模型是否能够在包含100万令牌的庞大信息范围内查找并使用所需信息。在需要模型将大量文件保留在工作内存中的仓库级Codex任务中，这一指标是预测模型表现的最佳依据。

针对Codex用户的实用指南

将各种基准测试结果转化为模型选择建议：

• 适用于整个代码库的任务（跨文件重构、多模块迁移）：应选用GPT-5.5。MRCR v2的测试结果显示，GPT-5.5在处理大型代码库时表现明显优于GPT-5.4。

• 成本较低、修改范围有限的本地编辑任务（单一功能修改、单个测试用例调整、文档优化）：可以选择GPT-5.4或专为Codex设计的模型。这种场景下，成本与响应速度之间的权衡更为合理，而GPT-5.5的强大功能在这类小规模任务中反而会被浪费掉。因此，不要仅仅因为GPT-5.5是最新的模型就默认使用它。

• 需要自主执行的任务（后台沙箱运行、多步骤工作流程）：同样应选择GPT-5.5。OSWorld-Verified评分以及较低的错误率是判断其适用性的重要指标——这些指标意味着沙箱测试失败的情况会更少，输出结果出错的概率也会更低。

• 代码评审相关工作：GPT-5.5也是最佳选择。其错误率降低了60%，这一数据对于代码评审工作来说至关重要；不过，如果使用效果不佳，反而会让人觉得这个模型并不实用。

• 成本最高的工作负载（那些接近GPT-5.5 Pro定价水平的任务）：应该将GPT-5.5 Pro留用在那些确实需要其高级功能的场景中，比如需要进行高度创新性的推理或处理极长上下文信息的任务。

对于采购部门而言：应将GPT-5.5视为独立的预算项目

在需要自主执行任务的场景中，模型消耗的资源主要取决于其输出结果。实际上，GPT-5.5产生的输出结果比GPT-5.4的成本要高得多。具体来说：

• 现在，混合模型策略已经成为常态，而不是例外。大多数经验丰富的团队都会将常规任务分配给Codex-mini模型，而将GPT-5.5留用在涉及整个代码库或需要大量代码评审的任务中。

• 第7节中的成本计算示例展示了在五种不同模型层级下，30名工程师参与代码评审时的实际成本情况。在批准预算之前，请务必仔细阅读这一示例。

• 每季度都要重新核对价格信息。过去价格曾经发生过变化，未来也可能会继续调整。

报价前请先进行核实

本节中提到的各项数据均来源于OpenAI的官方发布资料及当时的媒体报道。在将这些数据纳入采购文件或公开文档之前，务必与OpenAI的正式公告以及相关模型页面上的信息进行核对——具体参考第16节：参考资料。由于评估方法可能会发生变化，因此基准测试结果也会随之改变。

第12节：故障排除

即使是非常优秀的工具，如果使用方法不当，也可能会出现问题。以下是一些最常见的故障原因。

“Codex尚未安装”

请检查以下几点：

• 你是否已经运行了npm i -g @openai/codex命令？

• 你使用的shell环境和运行时环境是否符合要求？

• Codex的二进制文件是否已经添加到系统的路径中？

“我无法登录”

请检查以下内容：

• 您的ChatGPT账户使用的套餐是合适的。

• 您的工作空间支持在本地或云端使用Codex。

• 您使用的是正确的账户进行登录。

“Windows系统运行异常”

CLI文档说明，Windows系统的支持目前仍处于测试阶段。如果您使用的是Windows系统，建议使用WSL来运行CLI工具，或者在适当的情况下直接使用Codex应用程序。

“云端任务无法识别我的代码库”

请检查以下内容：

• GitHub连接器已经安装完成。

• 您的代码库被允许在连接器中被使用。

• 您的组织管理员已经启用了Codex的云端功能。

• 您使用的代码库是由GitHub托管的。

“Codex无法访问互联网”

在云端模式下，这种情况是正常的。请询问您的管理员是否有意限制了互联网访问权限。

“结果从技术上来说是正确的，但并不是我想要的结果”

通常这意味着任务描述不够明确。请仔细完善以下内容：

• 目标文件或具体功能是什么。

• 接受标准是什么。

• 有哪些限制条件。

• 预期的输出格式是什么。

第13节：常见问题解答

“Codex是一个聊天模型吗？”

不完全是。它实际上是一种用于处理代码库、进行测试、代码审查以及执行多步骤软件任务的工具。

“我可以不频繁切换工具就能使用Codex吗？”

可以。这正是它的优势之一。根据您的工作流程，您可以选择使用CLI、IDE扩展程序或Codex应用程序。

“我需要云端功能吗？”

不一定。许多个人用户仅通过使用本地的CLI或IDE扩展程序就能获得价值。只有当您需要后台执行、并行处理或自动代码审查等功能时，云端功能才会显得有用。

“Codex只是为专业工程师设计的吗？”

不是的。不过，当用户能够评估代码变更并理解代码库的结构时，Codex会发挥最大的作用。它首先是一款面向开发者的工具。

“Codex和GPT-5.4是一样的吗？”

不一样。GPT-5.4只是一个模型，而Codex则是一个具体的编码工具或工作流程解决方案。根据不同的使用场景和配置，Codex可能会使用不同的模型。

“最安全的开始方式是什么？”

建议先在一个较小的代码库变更上尝试使用CLI或IDE扩展程序，将审批流程设置得较为严格，并在合并代码之前仔细审核每一处差异。

第14节：何时不应使用Codex

这本手册的大部分内容都在强调：Codex在这方面表现优异，适合用于这些场景，以及如何配置它。然而，这种表述方式容易让人产生一种错觉，即认为Codex是解决任何与编码相关任务的理想工具。其实并非如此。要想让团队失去对某种AI编码工具的信任，最快的方法就是强迫它去处理那些它不擅长的任务。以下列举了一些目前Codex并不适合处理的场景。

没有可审核输出的任务

Codex的价值在于人类能够对代码差异、测试结果或相关解释进行审核。但如果某项任务的输出内容根本没有人会去检查——比如那些只会触碰生产数据的一次性脚本，或者那些在任何人阅读SQL语句之前就已经决定了最终结果的探索性查询——那么AI生成的答案就成为了唯一的审核标准。无论模型的质量如何，这种处境都是非常不利的。因此，要么为这些任务增加审核环节，要么干脆由人类亲自来完成这些工作。

高度新颖的架构决策

Codex在应用现有模式方面表现不错，但在帮助团队选择那些之前未曾解决过的问题的解决方案时，它的能力就显得十分有限了。对于真正属于新领域的任务——比如新的定价模型、新的认证机制或新的事件驱动架构设计——Codex很可能生成一些看似合理但实际上错误的方案。因此，应该利用它来生成各种设计方案的原型，而不是用它来最终决定哪种方案才是最佳选择。

跨越多个部门的工作

Codex只能看到它有权访问的代码仓库，而无法了解跨团队之间的协作安排、平台开发团队制定的弃用计划、其他代码仓库中尚未完成的迁移工作，或者某些方案因政治原因而被禁止使用。对于那些涉及多个团队或服务的变更，虽然Codex可以协助完成其中的一些具体步骤，但最终还是需要人类来统筹整个跨部门的工作流程。

任何会影响生产环境的状态变更

Codex Cloud提供的沙盒环境确实非常有用，但它们并不能替代人类在正式进行生产环境变更之前的审核工作。无论是数据库迁移、会修改实际资源的基础设施配置脚本，还是处理客户数据的程序，这些操作都需要经过人类的审批才能执行——即使这些代码都是Codex生成的。仅仅因为Codex能够运行这些命令，并不意味着它就应该被用来执行这些操作。

涉及合规性与安全性的代码

那些处于受监管环境中的代码（比如用于支付系统、医疗领域或安全相关的代码），其审核要求和来源追溯要求通常要比普通的产品代码高得多。虽然Codex生成的代码可以作为初始草案使用，但对其进行审核的工作量仍然与第三方编写的代码相同；因此，在这些场景下，Codex的速度优势实际上会大大减弱。为此，要么为这些任务安排专门的人工审核流程，要么干脆避免使用Codex来处理这些内容。

那些真正的问题在于知识缺乏而非打字效率低下的任务

如果团队因为没有人理解原有的系统架构、那些无法通过的测试结果，或是那些奇怪的客户反馈而陷入困境，那么编写更多的代码通常并不会带来帮助。只有在明确了该做什么之后，Codex才能帮助加快开发进程；但它无法替代那些应该在前期进行的探索与设计环节。那些跳过探索阶段、直接依赖Codex来解决问题的团队，往往会很快发布出有缺陷的产品。

那些因幻觉现象而带来高风险的场景

与之前的版本相比，GPT-5.5将产生幻觉现象的概率降低了大约60%，这一改进确实显著。不过这种概率仍未降为零。在那些错误结果可能会造成实际危害的任务中——比如生成会导致监管问题的内容、从模型并未真正阅读过的文档中复制API合同细节、或者对不熟悉的第三方库做出错误的描述——仍然需要像对待任何AI输出一样保持警惕。对于这类任务，应该采用基于搜索的工作流程或进行人工审核。

快速判断法则

如果你能够对以下四个问题都回答“是”，那么Codex很可能适合你使用：

1. 该任务的输出结果能否被他人审核并发现其中的错误？

2. 这项任务属于常见的操作模式，而不是某种新颖的架构设计吗？

3. 该任务的影响范围仅限于某个特定的仓库或服务内部吗？

4. 如果输出结果出现问题，其造成的后果是有限的（例如测试失败、代码被回退），而不是不可预测的（比如导致生产数据丢失或引发监管问题）吗？

如果其中任何一个问题的答案是“否”，那么就需要重新设计任务，使其符合这些条件；否则就应该将这项工作从Codex系统中移除。

第15节：最终建议

如果你打算向新用户推广Codex，我建议提供以下简单的使用指南：

1. 首先从命令行工具或IDE插件开始使用。

2. 通过完成一个简单的任务来熟悉这个工具。

3. 在合并代码之前，务必仔细审核所有的修改内容。

4. 只有当用户对本地的工作流程充满信心后，才允许他们使用云端的任务。

5. 对于团队来说，应该将用户的普通访问权限与管理员权限分开设置。

6. 每当你的计划或工作空间发生变化时，都要重新核对相关费用信息。

只有将Codex视为一种严谨的工程工具而非仅仅是一种新奇的事物，它才能发挥出最大的价值。如果你为它提供具体的代码、明确的约束条件以及完善的审核机制，它就能帮助加快软件开发中那些繁琐的工作流程，同时让复杂的任务变得更加容易处理。

LUNARTECH奖学金：连接学术界与工业界

为了解决学术理论与科技产业实际需求之间的日益脱节问题，LUNARTECH奖学金应运而生，旨在帮助填补这一人才缺口。

很多时候，有志成为工程师的人会陷入“没有经验就无法获得工作”的困境——他们虽然掌握了理论知识，但却无法应对生产系统中的各种实际问题。

为了解决这一系统性问题并阻止由此导致的人才流失，该奖学金大力投资于有潜力的年轻人，为他们提供一个重视实践经验、导师指导以及真实项目开发的成长环境，而非仅仅依赖传统的学位证书。

这个为期6个月的远程学习项目，旨在帮助有志之士从初学者成长为AI领域的先驱。参与者不会孤立地学习知识，而是会与经验丰富的资深工程师和创始人一起参与实际的高风险AI项目和数据开发工作。通过解决真实的工程难题并完成可投入生产的实际作品，他们将掌握在当今竞争激烈的环境中取得成功所需的各项技能。

如果你准备打破现状、加速自己的职业发展，那么可以探索这些机会，并从这里开始你的新征程：https://www.lunartech.ai/our-careers。

掌握你的职业发展：AI工程手册

对于那些准备从理论转向实践的人来说，我们编写了《AI工程手册：如何开启职业生涯并成为一名优秀的AI工程师》。这份全面的指南为人们提供了逐步学习的路径，帮助他们在2026年这个充满变革的AI时代掌握必要的技能。

无论你是希望进入竞争激烈的技术领域发展的开发者，还是希望为自己的职业发展打下坚实基础的从业者，这本手册都提供了经过验证的战略和实用建议，这些方法已经帮助无数人获得了重要的职位。

书中内容涵盖了实际的工作流程、先进的架构设计方法，以及来自NVIDIA、Microsoft和OpenAI等公司的专家观点。从了解ChatGPT背后的技术原理，到学习如何构建能够将研究成果转化为改变世界的产品，这本电子书绝对是助力你加速职业发展的理想工具。你可以免费下载这份手册，开始掌握AI技术的未来发展方向。

第16节：参考资料来源

本手册中引用的OpenAI官方资源如下：

• 了解GPT-5.5（OpenAI版本）

• 如何在你的ChatGPT项目中使用Codex

• 所有模型列表

• OpenAI API模型概述

• GPT-5-Codex模型

• GPT-5.2-Codex模型

• codex-mini-latest模型

• Codex的应用场景示例

• Claude简介

• GitHub Copilot使用说明

• 企业版Codex管理设置指南

• Codex IDE扩展插件文档

• Codex——OpenAI的代码辅助工具（VS Code市场列表页链接）

• Codex云端使用文档

• Codex命令行工具使用指南

• Codex命令行参数参考

• Codex命令行工具的功能介绍

• 快速开始使用Codex

• 如何在你的ChatGPT项目中使用Codex（帮助中心指南）

第2节和第11节中提到了关于GPT-5.5发布的媒体报道：

• OpenAI发布了GPT-5.5，这使得该公司向打造一款“人工智能超级应用”又迈进了一步（TechCrunch）

• OpenAI发布了GPT-5.5，并称其为“一种新型的人工智能技术”（The New Stack）

• OpenAI的GPT-5.5测试结果显示，其生成错误率下降了60%，其编码能力甚至可以与资深工程师相媲美（Startup Fortune）

附录A：30-60-90天应用推广计划

如果你正在向一个团队引入Codex，那么逐步推进其应用才是建立信任的最佳方式，而不是突然进行全面推广。分阶段实施的计划还能帮助你发现其中可能存在的障碍：比如认证流程、权限设置、提示语的质量、团队的审阅习惯，或是预算方面的问题。

前30天：验证其价值

在第一个月里，目标并不是让所有人都在使用这款工具，而是要取得能够重复出现的成功案例。

建议采取的措施：

1. 挑选一两名愿意尝试新工具的工程师。

2. 最初将这项工具仅用于一些简单、风险较低的任务，例如修复错误、生成测试用例或更新文档。

3. 制定统一的提示语模板，确保每个请求都能明确说明任务内容、背景信息、限制条件以及预期结果。

4. 要求所有修改内容都必须经过人工审核。

5. 记录从提交请求到得到最终修改结果所需的时间。

在这个阶段，你需要了解以下几点：

• Codex是否能够理解你的代码结构？

• 生成后的修改内容是否便于审核？

• 审批流程是会有效地减缓工作进度，还是会带来不必要的麻烦？

• 哪些类型的任务使用这款工具效果较好，哪些还需要进一步的指导？

如果第一个月出现了一些问题，不要首先归咎于模型本身。通常原因在于任务范围不明确、缺乏必要的背景信息，或者验收标准不清晰。

第31-60天：谨慎扩展应用范围

当这款工具在少数几项任务中证明了自身的有效性后，可以逐步将其推广到更广泛的测试群体中。

建议采取的措施：

1. 邀请来自不同部门的更多开发人员来使用这款工具。

2. 至少要包括一名持怀疑态度的人，他们的反馈能够帮助你发现产品中的不足之处。

3. 同时尝试使用应用程序、命令行界面以及集成开发环境扩展功能，让团队成员可以根据自己的习惯选择最适合的工作方式。

4. 可以将其用于一两项后台任务或拉取请求的审核工作中。

开始整理那些应用效果良好的提示语，并记录下高质量后续指令的示例。

在这个阶段，您应该了解以下内容：

• 对于团队来说，哪些功能实际上非常实用？

• 使用Codex可以在哪些环节节省最多时间？

• 人们是否足够信任Codex的输出结果，从而愿意将其用于实际工作？

• 是否经常出现相同的错误？

在这个阶段，内部文档的作用十分重要。一份简短的“我们在这里如何使用Codex”的说明，往往比深入的技术讲解更有用。

第61-90天：正式投入运行

大约三个月后，您的目标应该从实验阶段转向实际应用阶段。

推荐采取的行动：

1. 明确谁负责管理工作区设置、GitHub连接器的配置以及模型访问权限的分配。

2. 确定哪些任务适合在本地完成，哪些可以放到云沙箱环境中进行测试。

3. 记录下您对Codex生成的差异文件的审核标准。

4. 与团队明确预算预期，避免出现某些任务因需要大量资源而让大家感到意外。

5. 将Codex纳入新员工的入职培训流程中，先从简单的案例开始。

在这个阶段，理想的状态应该是：

• 新员工可以在第一天就开始使用Codex。

• 团队成员清楚何时应该使用Codex，何时应该采用其他工作流程。

• 管理员能够快速回答关于访问权限和价格方面的问题。

• 整个组织能够清楚地了解这款工具的优势和局限性。

实用的入职培训脚本

如果您需要一份现成的新用户入门指南，可以参考以下步骤：

1. “安装CLI或扩展程序。”

2. “打开一个你熟悉的仓库。”

3. “让Codex执行一个简单且安全的操作。”

4. “逐行查看差异结果。”

5. “运行测试。”

6. “让Codex解释它修改了什么以及为什么这样修改。”

7. “用一个稍微复杂一点的任务重复这个过程。”

这样的步骤有助于用户掌握核心的工作流程：理解上下文、确定任务、执行操作、审核结果、验证效果。一旦用户掌握了这个流程，其他相关产品也会变得更容易使用。

附录B：术语表

本手册中使用的术语按字母顺序排列。这份列表有意只包含那些在正文中出现、且非工程领域读者可能不熟悉的术语（如采购、安全、领导力等相关概念）。

• 智能代理/智能工作流程。指能够接受任务指令、规划执行步骤、采取相应行动（读取文件、运行命令、调用API）、观察结果并迭代改进的软件。Codex属于智能编码工作流程，而聊天机器人则不属于这一类别。

• 审批模式。Codex的一项设置，用于控制智能代理在未经人工确认的情况下能执行哪些操作。较严格的模式会在执行shell命令或修改文件之前提示人类用户；较为宽松的模式则允许智能代理无干扰地工作。

• CLI。命令行界面。Codex的CLI是基于终端的版本，可以通过`npm i -g @openai/codex`进行安装。

• Codex Cloud。Codex的托管式沙箱执行环境。任务在隔离的环境中运行，完成后会生成可供审核的差异文件。

• GDPval。一种评估模型能力的基准指标，用于衡量模型能否在44种职业场景中产生规范、准确的知识性输出。在第11节中作为模型通用能力的参考指标。

• GitHub Connector。使Codex Cloud能够访问GitHub仓库的集成组件。进行云环境任务时必需使用该功能，它会生成有效期较短、权限较低的令牌。

• MCP（模型上下文协议）。一种用于将模型与外部数据源和工具连接的开放协议。Codex的CLI支持MCP，因此它可以从仓库之外的系统中获取数据。

• MRCR v2.一种评估模型长上下文处理能力的基准测试。100万令牌版本的测试结果被用于GPT-5.5的相关分析，因为该测试能反映模型在大规模任务中的表现。

• OSWorld-Verified.一种评估模型是否能够操作真实桌面计算机环境以完成任务的基准。它是衡量模型能否胜任实际工作负载的直接指标。

• PR（拉取请求）。在GitHub等平台上提出的代码修改建议，需要经过其他用户的审核才能最终合并到代码库中。

• RBAC（基于角色的访问控制）。一种权限管理模型，用户被分配到不同的角色，而每个角色具有特定的权限。Codex的工作区管理员利用这一机制来控制谁可以执行哪些操作。

• SCIM（跨域身份管理系统）。一种用于将用户和组从身份提供者（如Okta、Entra ID等）同步到其他系统的标准。Codex支持基于SCIM的企业级组同步功能。

• 子代理。Codex CLI的一项功能，它可以将一个任务分配给多个智能代理同时执行，每个代理负责处理其中的一部分工作。

• Tau2-bench Telecom.一种针对复杂客户服务工作流程的测试基准，用于评估工具使用的可靠性及政策遵从性。

• Terminal-Bench 2.0.一项专注于终端驱动工作流程的编码测试基准，包括长上下文检索和计算机操作等内容。它是最接近Codex CLI工作负载的真实测试环境。

• 工作树。

  Git的一项功能，允许用户在不同的目录中同时检出多个分支。Codex应用程序利用工作树机制，使多个智能代理能够并行工作而不会互相干扰。

• WSL（Windows Subsystem for Linux）。一种兼容层，可以让Linux二进制程序在Windows系统中原生运行。对于在Windows上使用Codex CLI来说，这是推荐的环境，因为直接支持Windows系统的功能目前还处于测试阶段。

附录C：管理员安全检查清单

本检查清单专为为企业环境配置Codex的工作空间管理员设计。它将第8节中的内容整理成了可操作的步骤。在全面推广使用之前，请先仔细核对这份清单，之后每季度再重新审视一次。

访问权限设置

• [ ] 决定是在工作空间层面启用Codex Local、Codex Cloud，还是同时启用两者。

• [ ] 为Codex管理员（负责政策制定与管理工作）和Codex用户（日常开发人员）创建不同的RBAC角色组，切勿将两者混合使用。

• [ ] 通过SCIM协议从身份认证提供商处同步用户及组成员信息，避免手动管理用户账户。

• [ ] 为新加入工作空间的成员设置合理的默认角色，切勿直接将其设置为管理员权限。

与GitHub的集成

• [ ] 将ChatGPT GitHub Connector安装到相应的GitHub组织上。

• [ ] 仅允许Codex Cloud访问必要的仓库，切勿默认授予整个组织的访问权限。

• [ ] 在启用云功能之前，确认Codex会遵守受保护分支的相关规则。

• [ ] 确保Codex使用的GitHub App令牌为短期有效且权限最低。

网络与运行环境配置

• [ ] 确认Codex Cloud在默认情况下是不允许访问互联网的。这是安全的默认设置，请务必检查这一项是否已启用。

• [ ] 如果某个工作流程确实需要访问互联网，那么请明确指定允许访问的网站列表（如依赖库注册地址、可信站点），并限制允许使用的HTTP方法。

• [ > 明确记录哪些模型界面被允许用于处理敏感代码。通常来说：对于最敏感的仓库，本地CLI界面是可以使用的，而云端界面则不应被使用。

数据管理与审核流程

• [ ] 规定团队对Codex生成的差异文件应如何进行审核。最低要求是：每项合并操作都必须经过人工审核。

• [ > 根据企业的合规要求，确保Codex的所有操作都会被记录下来，并生成审计轨迹。

• [ ] 明确哪些类型的数据是Codex不允许访问的（例如个人身份信息、客户数据、机密信息），并制定相应的监管措施来执行这些规定。

• [ > 制定应对方案，以处理Codex生成或提交错误内容的情况。

预算与日常运营管理

• [ ] 为每个工作空间设定令牌使用的预算上限或预警阈值，以便及时发现异常支出情况。

• [ > 根据不同的任务类型选择合适的模型版本（例如：常规审核使用Codex-mini模型，全仓库重构任务使用GPT-5.5模型），并将这一选择理由记录下来。

• [ > 每季度检查一次Codex的定价信息。价格政策可能会发生变化，因此需要定期更新相关资料。

• [ > 当出现以下情况时，请重新执行这份检查清单：(a) 有新的模型版本发布；(b) 工作空间扩展到新的团队；(c) Codex增加了新的功能或界面。

附录D：变更记录

这是一份简短的、仅用于记录对本手册进行实质性修改的日志。每条记录都会列出版本号、修改日期，以及对该修改内容的简要说明。

• v1.3 — 2026-04-30. 将目录页设置为可点击链接；在目录之后新增了“先决条件”章节；对前几章的内容进行了结构调整：将原来的“快速入门”和“如何设置Codex”合并为第4节，其中提供了使用自包含的codex-demo仓库来构建环境的操作指南；同时将关于GPT-5.5基准测试的内容移至了第11节（模型规格与基准测试）。在第3节中添加了指向相关内容的超链接；重新撰写了第5节，为每条使用建议提供了具体的示例，并对“有限范围的变化”这一概念进行了明确说明；同时修改了“衡量关键指标”这个小节，为每个评估指标提供了具体的计算方法。在第10节中为每个工作流程都添加了可运行的示例代码；随后也相应地调整了后续章节的编号。

• v1.2 — 2026-04-25. 新增了附录E《在VS Code中使用Codex》，该附录提供了详细的操作指南，涵盖了通过扩展程序、集成终端中的命令行工具，以及chatgpt.com/codex网站上的浏览器端三种方式使用Codex的方法，并包含了设置说明、决策矩阵、综合工作流程示例，以及针对VS Code环境的故障排除方法。在设置章节中还添加了指向相关内容的链接。

• v1.1 — 2026-04-25. 在第2节和第7节》中增加了对GPT-5.5/GPT-5.5 Pro的介绍；在模型对比章节中添加了执行摘要和对比矩阵；在第14节中提供了成本计算示例以及“何时不应使用Codex”的建议；同时新增了附录B《术语表》、附录C《管理员安全检查清单》和附录D《变更记录》。此外还添加了版本号和作者信息；在第16节中列出了关于GPT-5.5的新闻报道来源。

• v1.0 — 初始版本。 这是最初的Codex使用手册，内容涵盖了基础概念、设置方法、使用技巧、模型对比信息、定价政策、安全注意事项、团队协作流程、故障排除方法、常见问题解答，以及30天、60天和90天的快速上手计划。

附录E：在VS Code中使用Codex

本附录提供了针对Visual Studio Code（及其分支版本Cursor和Windsurf）使用Codex的详细操作指南。

对于新使用的Codex用户来说，VS Code是最常见的入门工具。其工作流程提供了三种不同的入口方式，这些方式可以单独使用，也可以结合使用。本指南将详细介绍每种入口方式、适合在什么情况下使用它们，以及如何将这三种方式整合成一套流畅的工作流程。

E.1 为什么推荐使用VS Code作为入门工具

出于以下几个实际原因，大多数团队都会选择从VS Code开始使用Codex，而不是单独使用Codex应用程序或纯命令行界面：

• 工程师们日常工作中已经在使用VS Code了，添加Codex功能并不会导致他们需要切换工作环境。

• Codex的扩展模块数量较少，且易于测试。工程师可以先在单个文件上尝试这些扩展模块，然后再逐步将其应用到更广泛的范围中。

• VS Code内置的终端使得通过命令行界面操作变得非常便捷，因此可以在不离开VS Code编辑器的情况下同时使用扩展模块和命令行界面。

• VS Code最受欢迎的两种分支版本——Cursor和Windsurf——都使用了相同的Codex扩展模块。如果某个团队已经习惯了VS Code的工作流程，即使有些工程师更喜欢其他分支版本，也不需要重新培训他们。

不过，使用VS Code作为入门工具的缺点是，它最初并不支持并行任务处理或工作树功能，而这些功能在Codex应用程序中更为强大。对于大多数个人开发者来说，在刚开始使用的第一个月内，这一缺陷并不会造成太大的影响。

E.2 三种入口方式

Codex在VS Code中有多种不同的呈现形式，这些形式很容易被混淆。实际上，它们都是独立的软件组件，需要分别进行安装，并且也需要单独完成身份验证流程，尽管所有这些组件都是使用同一个ChatGPT账户来登录的。

1. Codex VS Code扩展模块——这是VS Code内部的一个侧边栏界面。该扩展模块可以通过VS Code市场进行安装。它最适合用于对打开的文件进行即时编辑、快速查询相关信息，或完成一些简单的任务。

2. 在VS Code内置终端中运行的Codex命令行界面——这个命令行工具(codex)可以直接在已经连接到VS Code工作区的终端窗口中使用。它非常适合用于需要执行多步骤操作的复杂任务、脚本化运行任务，或那些需要设置明确的审批流程的任务。

3. 通过chatgpt.com/codex访问的Web版Codex——这是Codex Cloud的Web界面，用户可以在其中在隔离的环境中运行任务，这些任务会针对你的GitHub仓库进行操作。它非常适合用于后台作业、并行处理任务，或进行类似Pull Request的代码审核流程。

这三种方式并不是互斥的，也就是说你并不一定必须选择其中的一种。它们分别适用于不同类型的工作场景，大多数经验丰富的Codex用户都会同时配置这三种工具。

E.3 配置Codex VS Code扩展模块

这是大多数新用户首先会遇到的入门步骤。

安装过程

有两种安装方式：

1. 打开VS Code市场，搜索“Codex”或“ChatGPT”，然后安装由openai发布的扩展模块。该扩展模块在市场上的标识符是openai.chatgpt。

2. 也可以通过终端来安装：

code --install-extension openai.chatgpt

CLI的安装路径对于通过脚本配置开发环境、管理点文件仓库以及编写用于将新机器设置到已知基准状态的初始化脚本来说非常有用。

登录

安装完成后，Codex面板会出现在右侧边栏中。首次打开该面板时，系统会提示您进行登录。您有两种登录选项：

• 使用ChatGPT登录。推荐给使用Plus、Pro、Business或Enterprise/Edu套餐的用户。使用此方式登录时，相关费用将从您的套餐所含的Codex积分中扣除。

• 使用API密钥登录。当您希望采用按量计费的API收费模式，或者工作空间政策有此要求时，可以选择这种方式登录。请从OpenAI开发者控制台获取API密钥，然后将其粘贴到扩展程序的认证提示框中。

如果两种登录选项都可见，而您不确定该选择哪一种，建议默认使用ChatGPT登录方式。因为这种登录方式会使用与您的团队其他成员相同的套餐资源，从而确保费用计算的透明度。

首次使用前的检查

登录成功后，在正式开始使用该扩展程序之前，请先进行为期五分钟的测试：

1. 打开一个您非常熟悉的小型代码仓库。

2. 在右侧边栏中打开Codex面板。

3. 针对这个打开的文件提出一个问题（例如：“这个函数的作用是什么？”），然后确认得到的答案与您已知的答案一致。

4. 要求对该文件进行一个小的修改（例如：“为这个函数添加文档字符串”），然后确认系统中确实会出现可供查看的差异对比结果。

5. 应用所做的修改，运行测试程序，必要时再恢复原始状态。

如果其中任何一步失败，请先修复认证相关问题或重新安装扩展程序后再继续操作。在实际任务中调试扩展程序要比在简单的测试环境中调试它困难得多。

平台注意事项

• macOS和Linux系统上，该扩展程序及底层的CLI工具都能正常运行。

• Windows系统上，CLI工具目前仍处于测试阶段。虽然扩展程序本身可以正常使用，但如果您想在VS Code的集成终端中同时使用CLI工具，OpenAI建议使用WSL工作空间。在安装CLI之前，请先通过“以WSL方式重新打开”选项打开相应文件夹。

• Cursor和Windsurf插件也使用了相同的扩展程序。需要注意的是，这些插件可能会与Fork工具内置的AI功能产生视觉或快捷键上的冲突，具体细节请参见E.9章节。

E.4 在VS Code集成终端中设置Codex CLI

CLI工具也是另一个可使用的登录入口。它作为普通的命令行工具运行，但在VS Code的集成终端中，它会自动识别当前激活的工作空间文件夹，因此使用起来会感觉就像编辑器的固有功能一样。

安装CLI工具

您可以在任何终端中安装该工具，包括VS Code的集成终端。

npm i -g @openai/codex

这会将codex二进制文件全局安装。运行以下命令进行确认：

codex --version

如果无法找到该命令，最常见的原因是npm的全局bin目录没有添加到你的PATH环境中。你可以修改PATH环境变量，或者使用Node版本管理工具（如nvm、fnm或volta）来自动处理这个问题。

在VS Code中打开集成终端

有三种方法可以打开集成终端，选择最适合你习惯的方式即可：

• 通过“视图”菜单 → “终端”来打开。

• 在Windows/Linux系统中使用键盘快捷键Ctrl+**（反引号）**，在macOS系统中使用⌃。

• 通过命令面板输入Terminal: Create New Terminal来打开。

集成终端会使用当前活动的工作区文件夹作为工作目录，因此从这里启动codex时，它会立即找到正确的代码仓库。

运行Codex

在终端中，导航到目标代码仓库（如果还没有进入该仓库的话），然后运行以下命令：

codex

第一次运行时，你需要按照扩展程序的要求进行身份验证——使用ChatGPT账号登录，或者输入API密钥。

选择审批模式

CLI支持多种审批模式，这些模式决定了Codex在未经明确确认的情况下可以执行哪些操作。对于新用户来说，建议先使用最严格的模式（在执行每个shell命令或修改文件之前都会请求确认）；一旦你对自己的代码仓库的工作流程有了信心，再调整审批模式。相关模式及其切换方法详见第16节中的CLI文档。

CLI相比扩展程序的优势

• 对于那些需要读取多个文件、运行测试、进行迭代并生成报告的多步骤任务来说，CLI更加适用。

• 任何你想要通过package.json中的脚本、Makefile或CI流程来执行的操作，都可以使用CLI来完成。

• CLI明确支持将一个任务分解为多个并行任务来执行。

• 对于那些与MCP平台连接的工具或自定义数据源，CLI也能提供更好的支持。

• 当你不想离开键盘时，也可以在终端中直接启动云任务。

E.5 设置浏览器版Codex（chatgpt.com/codex）

第三个使用入口位于VS Code之外，但它对于完成整个工作流程来说至关重要，因为它是用来启动和监控云任务的。

打开浏览器版Codex

访问chatgpt.com/codex。你需要使用与扩展程序及CLI相同的ChatGPT账号进行登录。如果你属于企业工作环境，那么你的管理员必须在工作区层面启用Codex Cloud功能——详情请参见第8节。

<你也可以通过普通版ChatGPT的侧边栏来访问Codex。浏览器界面提供了两个主要的操作选项：>

• “编写代码”——分配一项编码任务。Codex会启动一个预先加载了你的代码仓库的沙箱环境，并生成可供审核的代码差异文件。

• “提问”——在不修改任何代码的情况下，针对你的代码库提出问题。

连接 GitHub 仓库

云任务需要使用由 GitHub 托管的仓库。请按照以下步骤完成连接：

1. 在 chatgpt.com/codex 中打开环境设置。

2. 通过 ChatGPT 的 GitHub 连接器来关联你的 GitHub 账户。

3. 授权 Codex 使用特定的仓库。默认情况下不要授予全局访问权限——具体安全要求请参阅附录 C。

4. 确认连接器已正确显示该仓库为可用状态。

启动任务

通过 Codex 的网页界面进行操作：

1. 选择相应的仓库以及（可选的）分支。

2. 输入描述任务的提示语。请尽量具体一些——例如“为 /users 的 POST 接口添加输入验证功能，并更新相关的测试用例”，这样的描述比“改进 API”更为清晰有效。

3. 点击 “编写代码”（如需提问，则选择 “提问”）。

4. 可以实时查看 Codex 的运行日志，也可以关闭该窗口让任务在后台继续执行。

5. 任务完成后，请审核生成的代码差异文件。你可以要求对代码进行修改、直接接受结果，或者提交拉取请求。

通过 GitHub 的拉取请求评论来委托任务

这是一个非常实用的快捷方式：在任何与你的 GitHub 仓库关联的拉取请求中，你都可以发表一条包含 @codex 标签的评论，并在其中说明具体要求（例如“@codex 请检查这个拉取请求是否存在安全问题或遗漏的测试用例”）。Codex会收到这条请求并在相应的拉取请求中给出回复。不过，请注意，你必须在同一浏览器中登录 ChatGPT 才能使用这一功能。

即使你正在使用 VS Code，为什么浏览器界面仍然很重要

云任务使得 Codex 与你的本地机器相互独立。你可以通过浏览器启动一项耗时较长的任务，然后关闭笔记本电脑，稍后再回来查看代码差异文件。而扩展程序或命令行工具则无法实现这一点——它们需要一个处于打开状态的 VS Code 实例才能正常运行。

E.6 何时选择合适的入口点

这三种入口点之间存在重叠，因此容易引起混淆。下表可以帮助你更明确地做出选择。

>

使用场景	最佳入口点	原因
对当前打开的文件进行快速编辑	扩展程序	操作最为便捷，无需切换上下文环境
想了解“这个函数的作用是什么？”	扩展程序	通过右侧边栏的问答功能比在终端中输入命令更快
需要对多个文件进行重构并同时运行测试用例	集成终端中的命令行工具	更适合执行多步骤的操作及获取相关审批
任何需要通过脚本实现的功能，或者想要将其纳入 Makefile 中	命令行工具	只有命令行工具才能被其他脚本调用
希望让任务在后台持续运行	浏览器（云端服务）	与本地设备完全解耦
需要同时执行多项并行任务	浏览器（云端服务）	云端的沙箱环境可以并行运行，不会占用本地资源
需要对同事提交的拉取请求进行审核	通过浏览器，在拉取请求中添加 @codex 标签来发起请求	这样可以在实际进行审核的地方直接操作
任何涉及生产环境凭证或实时基础设施的操作	未经明确的人工批准，不得使用上述任何方法	请参阅 第 14 节

由此形成的使用模式是：使用扩展功能进行实时编辑，通过命令行界面处理需要审批的本地开发工作，而浏览器则用于那些需要与团队共享或离线处理的操作。

E.7 综合使用的VS Code工作流程

当这三个使用入口被结合在一起使用时，它们的效果会最为显著。一个典型的工作日安排如下：

上午，在VS Code中：

1. 打开代码仓库。Codex扩展面板位于右侧边栏中。

2. 在修改不熟悉的模块之前，先使用该扩展功能来了解相关信息。

3. 利用扩展功能提供的差异应用流程，进行一些简单的编辑操作——比如修改单函数代码、更新文档字符串或修正类型错误等。

上午中段，在集成终端中：

1. 打开集成终端（按Ctrl+键）。

2. 运行codex命令，启动一个需要明确审批的多文件任务。例如：“将认证中间件重构为使用新的会话接口。先列出要修改的文件列表，然后分多次提交这些更改。”

3. 按照Codex的要求，对每个shell命令和差异应用结果进行审批。

4. 当Codex完成处理后，运行测试套件。

下午，在浏览器中：

1. 在查看上午通过命令行进行的更改时，可以在另一个标签页中打开chatgpt.com/codex。

2. 启动一项云任务：“为/api/v2目录中的所有公共接口添加OpenAPI注释。”这项任务需要一些时间才能完成。

3. 返回VS Code继续工作。云任务会在独立的沙箱环境中运行。

4. 当云任务完成后，在浏览器中查看差异结果，如有必要进行进一步调整，然后提交拉取请求。

一天结束之际，在GitHub上：

1. 在同事提交的未合并拉取请求上添加标签@codex，并注明“请检查代码的正确性及是否缺少测试用例”。系统会在夜间自动将这条评论添加到相关请求中。

这种综合使用工作流程的优点在于：每个工具都能发挥其最大的作用。扩展功能使实时编辑变得高效；命令行界面适用于那些需要审批的本地开发任务；而云服务则可以处理耗时较长或需要并行执行的操作，而不会占用你的本地计算机资源。

E.8 VS Code专用技巧

这些都是一些小技巧，但如果你每天都在VS Code中使用Codex，这些技巧会逐渐发挥出更大的作用。

• 边栏位置设置。默认情况下，Codex面板会出现在右侧边栏。如果你的右侧边栏还有其他面板或需要查看GitHub拉取请求，可以将Codex面板拖放到次要边栏或底部工具栏中——只要能保证它不会占用编辑器的空间即可。

• 键盘快捷键设置。通过VS Code的Preferences: Open Keyboard Shortcuts选项，为常用的Codex命令设置快捷键。尽量使用键盘操作，而不要依赖鼠标。

• 设置同步功能。如果你使用了VS Code的设置同步功能，那么Codex扩展的配置信息也会自动同步到其他设备上。不过认证状态不会被同步，因此你需要在每台设备上都重新登录。这是正常的设计逻辑，切勿尝试绕过这一机制。

• 多根工作区使用技巧。该扩展功能的作用范围仅限于当前激活的工作区文件夹。如果你打开了一个具有多个根目录的工作区，在请求Codex进行修改之前，请先明确切换到正确的根目录，否则它可能会对错误的目录进行操作。

• 集成终端配置。如果你使用了多种终端环境（如PowerShell、bash或WSL），请在Windows系统中将WSL配置设置为默认环境，这样通过集成终端运行的codex命令就会始终在支持的环境中执行。

• 源代码控制面板。当Codex完成某项更改后，VS Code的源代码控制面板会显示相应的差异对比结果。在提交更改之前，请先在那里查看这些信息——这样你就可以在不离开编辑器的情况下了解所做的修改内容了，效果与运行git diff命令相同。

• 不要随意调整审批设置。新用户往往因为觉得审批流程太繁琐，而很快将审批模式设置为“自动”状态。但在第一周内，请坚持使用原有的审批流程。只有通过这种方式，你才能真正了解Codex在你的代码仓库中具体起到了什么作用。

• 每个VS Code窗口只使用一个Codex面板。请避免在同一工作区中同时运行扩展功能和命令行界面来处理同一项任务，因为它们都可能会修改文件，从而导致你无法分辨到底是哪个工具进行了哪些更改。

E.9 Cursor与Windsurf

Codex扩展明确支持Cursor和Windsurf这两种最受欢迎的VS Code分支。它们的安装和登录流程是完全相同的。以下是一些需要注意的事项：

• 避免混淆不同的AI功能。Cursor和Windsurf都各自配备了独立的AI功能。当工程师在Codex中使用这些功能时，有时会无意中调用分支自带的AI功能，而本意是想使用Codex的功能；反之亦然。因此，请选择一种主要的编辑工具进行使用，只有在另一种工具的特定优势确实需要的时候才使用它。

• 登录系统是独立的。Codex扩展的ChatGPT登录系统与Cursor或Windsurf各自拥有的账户系统是分开的。您使用Codex所产生的费用将计入您的ChatGPT订阅计划中；而使用Cursor/Windsurf所产生的费用则会计入它们各自的订阅计划中。

• 键绑定设置可能会产生冲突。尤其是Cursor，它对与AI相关的键绑定设置了较多的自定义选项。在安装Codex扩展后，请检查您的键绑定设置，确保两种工具都能正常使用相应的功能。

• 设置同步方面需要注意的问题。Cursor和Windsurf都有自己独立的设置同步机制，这种机制与VS Code的主流设置同步方式有所不同。因此，Codex扩展的设置可能会在Cursor或Windsurf中单独进行同步，而不会影响到您在VS Code中的设置。

对于那些主要使用Codex的工具团队来说，原版的VS Code是最简单的选择；而对于那些已经因为其他原因而习惯了使用Cursor或Windsurf的团队而言，Codex扩展只是为他们的工具环境增添了新的功能，而不是取代原有的工具。

E.10 针对VS Code特有的问题进行排查

一般的故障排查方法可以在第12节中找到。而以下这些问题是专门针对在VS Code中使用Codex时可能遇到的。

扩展已安装，但侧边栏面板始终没有出现

请重新加载窗口（通过命令面板输入“Developer: Reload Window”）。如果这个问题仍然存在，请检查“输出”面板，将下拉菜单选项切换为“Codex”，然后查找具体的错误信息。最常见的原因可能是企业的代理设置阻止了扩展程序的登录流程，或者系统中还安装了旧版本的扩展程序。

“登录”按钮不断循环，始终返回登录界面

这种情况通常意味着浏览器中的登录流程并没有成功将用户重定向到扩展程序所在的页面。请尝试完全退出VS Code，关闭所有窗口，然后重新打开并重新登录。在Windows系统中，请确认您使用的默认浏览器是VS Code能够通过操作系统正常打开的浏览器。

codex 这个命令在集成终端中无法找到

可能是因为CLI工具的npm全局安装目录没有被添加到系统的PATH环境变量中。在macOS/Linux系统中，最快的解决方法是在您的shell配置文件（如`.zshrc`或`.bashrc`）中添加$(npm bin -g)这一行代码；在Windows系统中，请在完成npm安装后重新启动VS Code，这样集成终端就能使用到更新后的PATH环境变量了；或者直接使用已经将npm安装目录添加到PATH中的WSL终端进行操作。

尽管你已经连接了相应的仓库，但Cloud任务仍然显示“没有连接的仓库”

请在chatgpt.com/codex的环境设置中确认该特定仓库是否被列入允许列表。GitHub连接器是按仓库来授予访问权限的；仅仅允许访问整个组织是不够的。同时，请确认你的工作空间管理员已经启用了Codex Cloud功能——普通用户无法自行启用这一功能。

扩展程序和命令行工具同时编辑同一个文件

请停止其中的一个操作。这两个工具并不会进行协调，因此会导致编辑结果出现冲突。最简单的解决办法是：每项任务只选择一种编辑方式，分别在不同的任务之间切换进行编辑，而不要试图在同一任务中同时使用两种方法。

对于相同的指令，扩展程序的执行速度似乎比命令行工具慢

通常这是因为扩展程序使用的默认模型与命令行工具配置中的模型不同。请检查两者所使用的模型是什么——可以在扩展程序面板中查看模型选择选项，也可以通过命令`codex --help`或查阅命令行工具的相关配置文件来确认。

在Windows系统上使用这些工具时，性能通常较差

建议切换到WSL工作空间。OpenAI官方文档明确指出，在Windows系统中使用命令行工具属于试验性用法；而WSL路径才是被官方支持的方式，使用它能够解决大部分相关问题。

你准备好成为一名优秀的AI工程师了吗？

在结束这次关于智能医疗领域的探讨后，我们可以清楚地看到：未来属于那些能够将突破性的研究成果与实际应用紧密结合起来的人。如果你有志于引领这一变革进程，我们邀请你下载我们的核心资源——《AI工程手册》。这本书由LUNARTECH的联合创始人、杰出的AI工程师Tatev Aslanyan编写，旨在帮助你在竞争激烈的AI工程领域中找到前进的方向，为你提供构建能够改变世界的产品所需的步骤指南和行业工作流程。

掌握那些被全球最具创新力的科技公司所采用的策略，你不仅能够跟上这个快速发展的时代，还能够为它的进步做出贡献。现在就点击链接下载电子书吧：https://www.lunartech.ai/download/the-ai-engineering-handbook。

关于LunarTech Lab

“真正的AI技术。实实在在的投资回报。这一切都由工程师们来实现——而不是通过幻灯片演示。”

LunarTech Lab是一家专注于AI、数据科学以及数字化转型领域的深度科技创新机构，其业务范围涵盖医疗健康、能源、电信等多个行业。

我们致力于开发真正的系统，而不是仅仅制作一些PPT演示文稿。我们的团队结合临床实践、数据分析及工程技术，打造出可衡量、符合行业标准且可直接投入实际应用的AI解决方案。我们保持中立立场，团队分布在全球各地，我们的技术基于真实的AI原理和工程实践，而非空洞的宣传口号。我们的团队融合了西欧和北美的领先理念与高效的技术能力，能够以四大科技巨头成本的一折提供世界级的服务。

我们的工作方式——分四个阶段从零开始

1. 发现阶段（2–4周）：我们首先会分析数据并评估投资回报率，而不是基于假设来决定哪些项目值得开发、哪些不值得，以及这些项目的成本是多少。

2>试点/概念验证阶段（8–12周）：我们会快速、专注地开发出核心功能的原型，并对这些原型进行测试，以验证其可行性及实际效果。这一阶段还会检验各种集成方案以及在现实环境中的投资回报率。

3>全面实施阶段（6–12个月）：我们会将这些解决方案转化为可大规模应用的系统，包括建立安全的数据传输机制、开发具备生产级性能的模型，确保各项要求符合HIPAA、MDR、GDPR等法规标准，并完成相关知识转移工作。

4>后续服务阶段（持续进行）：我们会对AI模型进行维护、重新训练并不断优化，以确保其长期发挥投资效益。我们还会每季度对这些模型进行评估，确保它们的性能会随着时间的推移而提升，而不是下降。由于我们拥有LunarTech Academy，因此我们还能为客户提供定制化的培训服务，帮助他们的技术团队在无需我们继续参与的情况下也能独立开展工作。

每一个项目都是从零开始设计的，我们会结合临床知识、数据工程技术和应用AI研究来推进项目的开发。

为什么选择LunarTech Lab?

LunarTech Lab弥补了战略规划与实际工程实施之间的差距——这也是大多数竞争对手所欠缺的。传统的咨询公司，包括四大咨询巨头，出售的只是框架和理论体系，并没有真正具备可操作性的解决方案；而这些框架和理论往往需要耗费高昂的成本来实施。

我们同样能够提供清晰的战略指导，但这些指导是由工程师和数据科学家们亲自制定的，并且实施成本仅为传统方法的70%左右。云服务提供商往往会强制客户使用他们自己的技术栈，从而限制客户的选择自由；而LunarTech则是中立的——我们会根据您的实际需求来选择最合适的技术方案，从而确保您能够获得最大的灵活性和长期效益。

外包公司往往缺乏创新精神，而LunarTech则像一个研发合作伙伴一样，从基础原理出发进行开发工作，与客户共同创造知识产权，并确保最终交付的产品能够带来可量化的投资回报。

从项目发现阶段到最终部署阶段，我们始终将战略规划、科学研究和工程技术紧密结合在一起。我们的承诺是：我们不会仅仅提供理论框架或演示文稿，而是会为您提供真正能产生实际效果的解决方案。

保持与LunarTech的联系

请关注LunarTech Lab的新闻通讯以及LinkedIn账号，在这里，您将了解到应用AI和数据科学领域的最新进展、项目案例以及行业突破。