第 4 章：Codex 上手、双模型接入与第一个应用
本章认识 Codex 客户端与模型服务的关系，选择 OpenAI 或 DeepSeek 路线完成接入，再用同一份需求和数据生成 Python 订单统计工具。
4.1 先分清：Codex 和模型是什么关系
可以把 Codex 理解成工作的执行环境：它组织对话、读取项目、修改文件、调用终端，并把结果交给我们检查。模型负责理解需求、分析问题和生成方案。
使用哪个软件，与软件背后调用哪个模型，是两个相关但不同的选择。
本课程提供两条路线：
| 路线 | 使用方式 | 需要准备 |
|---|---|---|
| OpenAI 原生路线 | 使用 Codex 官方认证和可用模型 | 符合使用条件的 ChatGPT 账号，或 OpenAI API 凭据 |
| DeepSeek 路线 | 为 Codex 配置 DeepSeek 提供方 | DeepSeek 开放平台账号、API Key 和可用额度 |
选择时先考虑自己的账号、网络条件与使用需求。两条路线都围绕同一个案例讲解，不需要为了看懂案例同时开通两套服务。切换模型后，工具调用效果、响应速度与可用功能仍需实际验证。
从哪个入口开始
Codex 常见入口包括桌面客户端、命令行 CLI 和编辑器扩展。桌面入口便于展示项目与修改结果；CLI 在终端中工作，便于展示配置状态；编辑器扩展适合边看代码边修改。
选择适合自己的一种入口即可。Windows 桌面安装入口以官方 Windows 文档为准。若选择 CLI，打开官方安装页，选择自己的系统安装方式，安装后在终端运行：
codex --version
codex第一条查看版本，第二条启动。界面名称可能随版本变化，以当前客户端为准。
4.2 路线 A：使用 OpenAI 原生模型
登录与选择模型
首次打开客户端，按界面提示使用 ChatGPT 登录。CLI 也可以通过以下命令启动登录流程：
codex login如果使用 OpenAI API Key，选择客户端提供的 API Key 认证入口。ChatGPT 订阅与 OpenAI API 用量属于不同的计费体系，不能把订阅理解成 API 余额。具体支持的认证方式见官方认证说明。
登录后，使用当前账号能选择的模型。CLI 可以通过 /model 选择模型，通过 /status 查看当前会话配置，命令说明见Codex CLI 文档。
可以这样理解：
我们先确认软件能够正常工作。后面完成同一项需求时，可以比较不同模型的效果，但不能只凭一次结果判断某个模型永远更好。
用一句简单指令验证
打开本章的演示项目文件夹，输入：
请读取需求说明.md，告诉我这个项目要做什么。先不要修改文件。观察它是否确实读取了项目文件，回答是否符合需求。能够聊天只是第一步，后面的案例还会继续检查文件修改和实际运行。
4.3 路线 B：让 Codex 使用 DeepSeek
接入前准备
打开 DeepSeek 开放平台，准备 API Key，并在平台查看可用额度和用量入口。这里需要的是 API 服务凭据，不能用网页版聊天登录密码代替。
接入的核心是告诉 Codex：调用哪个提供方、哪个模型、哪个接口，以及如何认证。 DeepSeek 当前提供了 Codex 官方接入指南，包含脚本与手工配置两种方式，详见DeepSeek 接入文档。
两条模型路线与两种配置方法
OpenAI 与 DeepSeek 是两条模型服务路线；脚本配置与手工配置是 DeepSeek 路线下的两种操作方法。选择 DeepSeek 后，在两种配置方法中选择一种即可。
模型接口与业务工具接口也不同：模型接口用于推理和生成，MCP 接口用于访问工具与资料。配置好模型后，仍需单独安装技能、准备 Python，或连接需要的 MCP 服务。
两种配置操作怎么选
- 脚本配置： 展示官方页面、脚本来源和执行过程，适合第一次接入。
- 手工配置： 打开配置文件解释关键字段，适合理解原理或排查问题。
具体命令与脱敏配置放在模型配置说明。先理解以下配置项：
| 名称 | 可以怎样理解 |
|---|---|
config.toml | 客户端的配置文件 |
model_provider | 选择模型服务提供方 |
model | 选择该提供方的具体模型 |
base_url | 请求发送到的 API 地址 |
| 认证配置 | 让服务识别你的调用身份 |
models.json | 告诉客户端模型有哪些能力的目录文件 |
| Responses API | 客户端和模型服务交换请求、结果的一种接口规范 |
这些设置应保持一致。仅把模型名称改成 DeepSeek，而请求仍发往其他服务，并不能完成接入。配置位置和提供方的定义方式可查阅 Codex 配置基础与高级配置。
如何确认接入成功
保存配置后，完全退出并重新打开客户端，新建会话。先查看当前模型与提供方，再执行读取需求文件的指令，最后到对应开放平台核对这次调用的用量记录；用量显示可能有延迟。
不要只问模型“你是谁”来判断接入是否成功。模型的自我介绍不是实际请求路由的证据。也不要把 OpenAI 的登录状态，当成 DeepSeek 接入状态。
遇到问题时，按现象检查：
| 现象 | 优先检查 |
|---|---|
| 认证失败 | Key 是否属于当前提供方、是否有效、是否被正确读取 |
| 提示额度不足或请求过多 | 平台余额、用量限制以及报错详情 |
| 找不到模型或接口 | 模型 ID、接口地址、客户端版本是否符合当前接入指南 |
| 能回答但工具调用失败 | 参数和工具支持情况；先用简单的读取文件任务定位 |
| 修改配置后无变化 | 是否编辑了实际配置目录、是否重启并创建了新会话 |
4.4 简单案例：用 Python 编写订单统计工具
案例目标
本章制作一个命令行小工具：读取订单数据，显示统计结果，并按商品和状态查询记录。无需网页、数据库或第三方 Python 库。
使用演示项目资料，其中提供需求说明和 8 条去重后的 JSON 数据。将需求和数据交给 Codex，生成程序后检查运行结果。
第一步：读取需求，检查 Python 环境
打开复制后的 演示项目 文件夹，输入：
请读取需求说明.md和订单数据.json。
先说明程序的输入、输出、统计规则和准备生成的文件。
检查本机是否有可用的 Python 3，并报告解释器版本与启动命令。
先不要写代码或安装软件。如果没有 Python，请说明如何准备环境。Python 是运行程序的环境，Codex 是帮助我们编写和修改程序的工具。切换 OpenAI 或 DeepSeek 不会替代本地 Python 环境。
在 Windows 中可先检查 py --version，或使用本机已有的 python --version。如果没有 Python 3，从 Python 官方下载页准备环境，安装后重新打开终端再检查。后续示例使用 py；如果本机使用其他启动命令，请相应替换。
第二步：让 Codex 生成程序
确认需求理解正确后，输入：
请按需求说明生成 main.py 和 README.md。
使用 Python 3 标准库，不安装第三方依赖。
默认读取 main.py 同目录下的订单数据.json，使用 UTF-8 编码。
支持 --product 和 --status 参数，组合条件使用“同时满足”。
每次运行先显示全量统计，再显示筛选条件、匹配数量和匹配记录。
筛选不改变全量统计。无匹配时显示中文提示。
数据文件缺失或 JSON 格式错误时，给出清楚的中文错误并以非零状态退出。
保留源数据，不新增接口、网页或数据库。
生成后执行几条典型命令，报告实际结果和未完成的检查。其中，main.py 是程序文件；json 负责读数据；argparse 可以处理命令参数；pathlib 可以定位文件。这些模块都属于 Python 标准库。
第三步：运行并检查结果
在程序所在文件夹打开终端，依次演示：
py main.py
py main.py --product "机械键盘"
py main.py --product "机械键盘" --status "已支付"
py main.py --product "蓝牙耳机" --status "已取消"| 命令场景 | 预期结果 |
|---|---|
| 不加筛选 | 总记录 8、已支付订单 6、待支付 1、已取消 1；列出 8 条 |
| 机械键盘 | 匹配 4 条 |
| 机械键盘且已支付 | 匹配 3 条 |
| 蓝牙耳机且已取消 | 匹配 0 条，提示没有符合条件的记录 |
四次运行的全量统计应相同。取消筛选只需重新执行不带参数的命令。下面是首条命令的输出示意，具体排版可不同：
电商订单统计
总记录：8 | 已支付订单：6 | 待支付：1 | 已取消：1
筛选条件：全部商品 / 全部状态
当前匹配：8 条以上为根据输入数据计算的预期，可与实际终端输出逐项核对。
第四步：提出一次明确的修改
请在全量统计下方增加“各商品已支付订单数”。
只统计状态为“已支付”的记录，不受命令行筛选影响。
修改后重新运行原有四种场景，检查商品统计和原有查询是否正确。预期两类商品各为 3 条。这个过程展示了“描述需求 → 生成程序 → 实际运行 → 反馈修改”。如果报错，应把完整错误和执行命令交给 Codex，而不是只说“运行不了”。
从哪里运行命令
py main.py 中的 main.py 相对于终端当前目录；程序内部的默认数据文件则按本案例要求，相对于脚本所在目录定位。前者决定怎样找到程序，后者决定程序怎样找到输入。
本章实际生成的程序是后续升级案例的基础。换一个模型继续开发时，仍以同一份需求、输入和预期结果核对；模型能够回答问题、修改文件、运行程序是逐层确认的能力。
4.5 用 AGENTS.md 保存项目约定
反复使用的约定可以写进项目根目录的 AGENTS.md，例如：
# 项目约定
- 本项目是 Python 命令行教学工具，说明与输出使用简体中文。
- 使用 Python 3 标准库，不添加第三方依赖。
- 按脚本所在目录定位默认输入，以 UTF-8 读取数据。
- 已支付订单仅统计“已支付”，保留源数据。
- 修改后运行全部记录、组合筛选和无匹配三个场景。
- 说明实际执行的检查，不把未运行的检查写成通过。Codex 根据项目位置读取适用的指令文件，规则见 AGENTS.md 官方说明。这里先理解它用于保存项目约定，后续再介绍如何用 Skills 复用完整工作方法。
下一章将继续使用这个 Python 工具，将单文件查询升级为批量处理工具，展示数据规则、结果验收与交付说明。
本例统计的是订单记录及其导出状态。样例每条订单只有一个商品，没有金额、退款和物流字段；“已支付”不等于已经完成支付对账或发货，也不能换算成销售额。