第 4 章：模型配置说明
本资料介绍 Codex 的 OpenAI 与 DeepSeek 模型配置、连接检查及恢复方法。两条路线任选其一；DeepSeek 的脚本与手工方式也是二选一。
1. 找到配置位置并备份
先安装并启动一次所选客户端。默认用户配置是 ~/.codex/config.toml；如果设置了 CODEX_HOME，应以该目录为准。用户配置与项目中的 .codex/config.toml 不同，本章的提供方设置放在用户配置中。参见 OpenAI 配置基础和高级配置。
Windows PowerShell 中可以用以下命令定位目录：
$courseCodexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
$courseCodexDir关闭客户端后，把该目录现有的 config.toml 和 models.json 复制到自己新建的带日期备份文件夹；记录原先不存在的文件。不复制或展示认证文件。已有配置可能包含 Key，备份同样不应放进课程资料或公开仓库。
在 Windows 原生客户端与 WSL 之间切换时，不要假设它们自动使用同一套配置；默认目录的区别见官方 Windows 说明。
2. OpenAI 原生路线
在客户端选择 ChatGPT 登录，或选择 OpenAI API Key 认证。CLI 可使用 codex login 发起登录。登录后从可用模型列表选择模型即可；不必复制网上某个固定型号到配置里。
使用 OpenAI API 的费用与 ChatGPT 订阅分开，具体认证和凭据保存行为见官方认证说明。API Key 应保存在本地凭据配置中，不写入共享资料。
3. DeepSeek：官方脚本方式
打开 DeepSeek 官方 Codex 接入指南，确认当前命令和客户端要求，再执行页面给出的 Windows PowerShell 命令：
irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex这条命令会下载并执行远程配置脚本。应先查看官方页面与脚本内容，理解它会修改用户配置；避免将真实 Key 写入共享文件或日志。
按菜单选择模型并提供 DeepSeek API Key。官方脚本会准备模型目录与配置，并提供备份和恢复操作。菜单、模型选项以执行当天页面为准，不把脚本输出或含密钥的文件上传为教材。
4. DeepSeek：手工配置方式
此方式与脚本方式二选一，不必重复配置。首先从同一官方指南的手工配置部分取得完整模型目录 JSON，保存为实际 Codex 用户目录中的 models.json。不要把下面的 TOML 当作全部接入材料，也不要把空 JSON 当模型目录。
以下是依据官方指南整理的脱敏示例。将顶层字段放在任何 [表名] 之前；已有同名字段和表时合并修改，不要整段追加造成重复。
model = "deepseek-flash"
model_provider = "deepseek"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
web_search = "disabled"
show_raw_agent_reasoning = true
model_catalog_json = "C:/Users/YOUR_USER/.codex/models.json"
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "REPLACE_WITH_YOUR_DEEPSEEK_API_KEY"
[desktop]
enabled-reasoning-efforts = ["low", "medium", "high", "xhigh", "ultra", "max"]将模型目录路径改成真实路径；示例使用正斜杠，避免 TOML 字符串中的反斜杠转义问题。Key 占位符必须在自己的机器上替换，不要将真实值放进演示资料。这种写法会把 Key 存在配置文件中。
模型 ID 必须同时被当前服务和模型目录支持。model_catalog_json 指向元数据，不是把模型下载到本地；请求依然发送到配置的 API 服务。该配置关闭了内置网页搜索，不代表所有其他工具也被关闭。完整字段说明和客户端要求以 DeepSeek 官方指南为准。
如果已有配置采用 env_key 引用环境变量，应保持一种明确的认证方式，不要同时堆叠多种 Key 配置。环境变量修改后要重启客户端；只在某个终端临时设置的变量，其他已打开的应用未必能读取。env_key 的意义参见 OpenAI 自定义提供方配置。本例采用上述提供方配置。
5. 验证、切换与恢复
保存后重启客户端并新建会话。检查当前模型和提供方，执行读取需求文件的任务，再完成案例中的创建文件与运行检查。结合服务平台用量确认实际调用；不要只凭模型的自我介绍判断。
记录客户端版本、所选模型、接入日期和验证结果，便于排查版本差异。不把“配置文件保存成功”描述成“功能全部验证通过”。
从 DeepSeek 切回原生路线时：
- 关闭客户端，保存需要保留的当前配置。
- 脚本配置按官方恢复菜单操作；手工配置则恢复自己保存的原始配置文件。原来不存在的文件，按备份记录单独移出，不删除整个用户目录。
- 重新启动，选择原生登录方式和模型，重新执行一次读取文件验证。
恢复时要核对提供方、模型目录及认证相关设置是否一起恢复。只修改 model 一项，可能仍然调用旧提供方。不要为了切换模型清空整个配置目录或删除历史会话。
6. 分层检查接入结果
| 检查 | 说明 |
|---|---|
| 配置可解析 | TOML 没有重复段落，模型目录是完整有效的 JSON |
| 提供方正确 | 当前模型、API 地址与凭据属于同一条路线 |
| 文件可读取 | 能读取指定需求文件并准确概括 |
| 工具可执行 | 能在案例目录生成程序并运行 Python |
| 结果正确 | 样例全量统计为 8、6、1、1，组合筛选符合要求 |
配置、模型调用、本地执行与业务结果是不同层次。后面连接 MCP 或安装 Skill 时，仍分别检查相应能力，不能从“能够聊天”推断所有工具都可用。