Codex VS Code 教程：API Key、第三方模型与首次验证

在 VS Code 里用 Codex，最容易出错的不是“少装了一个插件”，而是把三件不同的事混成一件：安装 OpenAI 官方扩展、选择 ChatGPT 或 API Key 登录、把模型请求交给哪个 provider。三者分别决定入口、账单与请求去向。

一个可靠的设置不以“侧栏能打开”为终点。你还要能回答：当前用什么认证、密钥属于谁、请求发往哪个 Base URL、实际选择了哪个模型，以及 Codex 生成的改动是否经过 diff 和项目检查。下面的流程就按这些可观察结果推进。

先选路线：官方 OpenAI 还是自定义 provider

先根据实际目标选一条路线，暂时不要修改配置文件。

OpenAI 的当前认证说明明确区分 ChatGPT 登录和 API key 登录。API key 并不是“订阅密码”，ChatGPT 订阅也不会自动给第三方网关付费。若你还没决定哪种账单适合，可以先看 Codex API Key 和 ChatGPT 订阅怎么选，再回来继续。

安装并确认是官方 Codex 扩展

从 OpenAI 的Codex IDE 官方页面进入 Visual Studio Code 安装入口。扩展市场里的发布者、名称和入口都应与官方页面一致；不要只凭图标或“Codex”字样判断。

安装或启用后：

1. 打开一个你熟悉、可以安全测试的 Git 项目。
2. 点击活动栏中的 Codex 图标。
3. 如果图标没有出现，打开 Command Palette，运行 Codex: Open Codex Sidebar。
4. 确认看到的是可开始会话的 Codex 侧栏，而不是扩展详情页。

此时只证明 VS Code 已加载扩展。它还不能证明账户有效、当前项目已被读取，或自定义模型具备 Codex 需要的能力。

用 ChatGPT 或 OpenAI API Key 登录

在未登录状态，官方 IDE 扩展提供两条本地认证路线：

• Sign in with ChatGPT：浏览器完成登录，适合希望使用 ChatGPT 计划与 workspace 管理能力的人。
• Use API Key：输入从 OpenAI Platform API keys 创建、且由你控制的 key，调用按标准 API 用量计费。

如果扩展已经登录了另一个账户，不要直接删除 ~/.codex/auth.json。先在 Codex 的 profile 菜单查看当前认证方式，使用 Log out 清除现有会话，再从官方登录界面选择新路线。OpenAI 的认证文档说明 CLI 与 IDE 扩展会共用缓存登录信息；在其中一端登出后，另一端下次也需要重新登录。

无论哪条路线，都不要把 key 放进：

• 项目源码、.env.example 或准备提交的 .env；
• config.toml 的明文字符串；
• Codex 对话、issue、截图或故障日志；
• 来源不明的共享账号或共享密钥。

只使用 OpenAI 官方模型时，完成登录后可以先跳到“第一次验证”。需要外部网关或第三方模型时，再配置 provider。

在 VS Code 打开正确的 config.toml

Codex IDE 和 Codex CLI 共用 agent 配置层。OpenAI 的基础配置文档给出的直接入口是：在 Codex 侧栏右上角选择齿轮，然后进入 Codex Settings > Open config.toml。

第三方 provider 应放在用户级文件：

text
~/.codex/config.toml

不要把 provider、Base URL 或认证路线提交到仓库内的 .codex/config.toml。当前配置参考会限制项目层改变这类机器私有设置，这也能避免一个仓库静默把你的请求改发到陌生端点。

还要区分两种设置：

• config.toml 控制模型、provider、权限、沙盒和 MCP 等 Codex agent 行为；
• VS Code 的 chatgpt.* 设置控制扩展在编辑器里的展示与交互。

因此，“在 VS Code Settings 里找不到 Base URL 输入框”并不代表 Codex 不支持 custom provider；正确入口通常是 config.toml，不是照搬其他 AI 扩展的 JSON 字段。

配置第三方模型或公司网关

下面是一个只说明字段关系的占位示例。域名、变量名和模型 ID 都要替换成 provider 实际提供的值：

toml
# ~/.codex/config.toml
model = "EXACT_MODEL_ID"
model_provider = "team_gateway"

[model_providers.team_gateway]
name = "Team gateway"
base_url = "https://gateway.example.com/v1"
env_key = "TEAM_GATEWAY_API_KEY"
wire_api = "responses"

关键点不在于复制这六行，而在于逐项核对合同：

• team_gateway 是自定义 provider ID，必须与 model_provider 完全一致；不要复用保留的 openai、ollama 或 lmstudio ID。
• base_url 是 provider 明确给 Codex/Responses 客户端使用的根地址，不能从普通聊天网页地址猜测。
• env_key 是环境变量的名称，不是 API key 的值。
• model 必须是 provider 当前可用的精确模型 ID；营销名称不一定能直接用于 API。
• wire_api = "responses" 要求端点实际实现相应请求和流式返回，而不只是声称“OpenAI-compatible”。

在启动 VS Code 的环境中设置变量。例如 macOS 或 Linux 当前 shell 可先执行：

bash
export TEAM_GATEWAY_API_KEY="<your-provider-key>"
code .

PowerShell 可在当前会话设置：

powershell
$env:TEAM_GATEWAY_API_KEY = "<your-provider-key>"
code .

这里的占位符不要原样保留，也不要把真实 key 发给 Codex。若从 Dock、开始菜单或另一个远程环境启动 VS Code，它未必继承你在终端设置的变量。出现认证错误时，先确认编辑器进程是否来自同一环境，而不是立即更换 key。

OpenAI 的自定义 provider 文档还支持 OpenAI auth、命令获取 token 或无认证的本地服务。选择哪一种取决于 provider 的真实合同；不要同时堆叠互斥的认证方式。

用一次小任务证明设置真的可用

重载 VS Code 或重新打开 Codex 会话后，不要直接让一个陌生模型重构整个仓库。选一个你理解的函数，并建立 Git 检查点：

bash
git status --short

打开目标文件，选中一个小函数，提交类似下面的任务：

text
只检查我选中的 parseConfig 函数。
目标：让空字符串返回现有错误类型，不改变公开 API。
只允许修改当前文件；不要安装依赖，也不要执行部署命令。
完成后说明改动，并告诉我应运行哪一条现有测试。

验证时分四层看：

1. 会话可用：没有立即出现登录或 provider 认证失败。
2. 上下文正确：回答准确提到选中函数中的真实变量或分支。
3. 修改受控：VS Code diff 只包含允许文件，没有额外依赖或配置变化。
4. 结果成立：项目原有测试或检查通过，git diff 与目标一致。

再次运行：

bash
git status --short
git diff -- path/to/your-file

只有四层都通过，才能说“这条 VS Code + 认证 + provider + 模型路线完成了第一次可审查任务”。一次普通回复成功不代表工具调用、长任务、图片输入或 web search 等其他能力也一定兼容。

按第一处失败定位，不要反复重装

如果 Codex 已加载配置但行为仍不对，转到 Codex config.toml 为什么没生效，按配置层、覆盖和 provider 调用分别排查。不要把 endpoint 兼容问题继续当成 TOML 语法错误。

完成设置后保留这份最小证据

不保存 secret，只记录下面这些非敏感信息，后续排错会快很多：

• VS Code 与 Codex extension 版本；
• ChatGPT 登录、OpenAI API key 或 custom provider 三者中的当前路线；
• provider ID、Base URL 的主机名和模型 ID（不含 token 与 headers）；
• 首次失败或成功的时间、原始错误文本和任务范围；
• 修改前后的 git status、目标 diff 与测试命令结果。

这样，你得到的不是一份只能在今天复制的配置，而是一条可维护的判断链：入口由官方扩展负责，认证决定账户与账单，provider 决定 endpoint 与模型合同，最后由 diff 和项目检查决定这次代码修改是否值得保留。