# Codex VS Code 教程：API Key、第三方模型与首次验证 > 先确认扩展、认证和请求去向，再做第一次小改动；这样能把安装成功、模型可用和代码正确分开验证。 - URL: https://blog.laozhang.ai/zh/posts/codex-vscode-extension-api-key-custom-models - Published: 2026-09-01 - Updated: 2026-09-01 - Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about) - Topic: 开发工具与智能体 - Tags: OpenAI Codex, VS Code, Codex API Key, 第三方模型, config.toml --- 在 VS Code 里用 Codex，最容易出错的不是“少装了一个插件”，而是把三件不同的事混成一件：安装 OpenAI 官方扩展、选择 ChatGPT 或 API Key 登录、把模型请求交给哪家模型服务商。三者分别决定入口、账单与请求去向。 一个可靠的设置不以“侧栏能打开”为终点。你还要能回答：当前用什么认证、密钥属于谁、请求发往哪个 Base URL、实际选择了哪个模型，以及 Codex 生成的改动是否经过 diff 和项目检查。下面的流程就按这些可观察结果推进。 ## 先选路线：官方 OpenAI 还是自定义服务商 先根据实际目标选一条路线，暂时不要修改配置文件。 | 目标 | 认证与服务商 | 你需要确认的账单或限制 | |---|---|---| | 在 ChatGPT 计划下交互式使用 Codex | 使用 **Sign in with ChatGPT**，保留内建 OpenAI 路线 | 受 ChatGPT 计划、工作区权限和产品功能影响 | | 用自己的 OpenAI Platform 项目按量调用 | 在扩展中选择 **Use API Key**，输入自己的 OpenAI API key | 用量进入 OpenAI Platform 账单；部分依赖 ChatGPT 工作区或云端的功能可能不可用 | | 通过公司网关、外部 API 或其他模型服务 | 在用户级 `config.toml` 定义自定义服务商，并使用该服务商的认证 | 端点、可用模型、协议、价格和限额由该服务商负责 | | 使用本机 Ollama 或 LM Studio | 使用 Codex 支持的本地服务商路线 | 本机资源、模型能力和本地服务状态成为主要限制 | OpenAI 的[当前认证说明](https://learn.chatgpt.com/docs/auth)明确区分 ChatGPT 登录和 API key 登录。API key 并不是“订阅密码”，ChatGPT 订阅也不会自动给第三方网关付费。若你还没决定哪种账单适合，可以先看 [Codex API Key 和 ChatGPT 订阅怎么选](https://blog.laozhang.ai/zh/posts/codex-api-key-vs-subscription)，再回来继续。 ## 安装并确认是官方 Codex 扩展 从 OpenAI 的[Codex IDE 官方页面](https://learn.chatgpt.com/docs/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 计划与工作区管理能力的人。 - **Use API Key**：输入从 [OpenAI Platform API keys](https://platform.openai.com/api-keys) 创建、且由你控制的 key，调用按标准 API 用量计费。 如果扩展已经登录了另一个账户，不要直接删除 `~/.codex/auth.json`。先在 Codex 的账户菜单查看当前认证方式，使用 **Log out** 清除现有会话，再从官方登录界面选择新路线。OpenAI 的认证文档说明 CLI 与 IDE 扩展会共用缓存登录信息；在其中一端登出后，另一端下次也需要重新登录。 无论哪条路线，都不要把 key 放进： - 项目源码、`.env.example` 或准备提交的 `.env`； - `config.toml` 的明文字符串； - Codex 对话、issue、截图或故障日志； - 来源不明的共享账号或共享密钥。 只使用 OpenAI 官方模型时，完成登录后可以先跳到“第一次验证”。需要外部网关或第三方模型时，再配置服务商。 ## 在 VS Code 打开正确的 config.toml Codex IDE 和 Codex CLI 共用智能体配置。OpenAI 的[基础配置文档](https://learn.chatgpt.com/docs/config-file/config-basic)给出的直接入口是：在 Codex 侧栏右上角选择齿轮，然后进入 **Codex Settings > Open config.toml**。 第三方服务商应放在用户级文件： ```text ~/.codex/config.toml ``` 不要把服务商、Base URL 或认证方式提交到仓库内的 `.codex/config.toml`。当前配置参考会限制项目层改变这类机器私有设置，这也能避免一个仓库静默把你的请求改发到陌生端点。 还要区分两种设置： - `config.toml` 控制模型、服务商、权限、沙盒和 MCP 等 Codex 的执行行为； - VS Code 的 `chatgpt.*` 设置控制扩展在编辑器里的展示与交互。 因此，“在 VS Code Settings 里找不到 Base URL 输入框”并不代表 Codex 不支持自定义服务商；正确入口通常是 `config.toml`，不是照搬其他 AI 扩展的 JSON 字段。 ## 配置第三方模型或公司网关 下面是一个只说明字段关系的占位示例。域名、变量名和模型 ID 都要替换成服务商实际提供的值： ```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` 是自定义服务商 ID，必须与 `model_provider` 完全一致；不要复用保留的 `openai`、`ollama` 或 `lmstudio` ID。 - `base_url` 是服务商明确给 Codex/Responses 客户端使用的根地址，不能从普通聊天网页地址猜测。 - `env_key` 是环境变量的**名称**，不是 API key 的值。 - `model` 必须是服务商当前可用的精确模型 ID；营销名称不一定能直接用于 API。 - `wire_api = "responses"` 要求端点实际实现相应请求和流式返回，而不只是声称“OpenAI-compatible”。 在启动 VS Code 的环境中设置变量。例如 macOS 或 Linux 当前 shell 可先执行： ```bash export TEAM_GATEWAY_API_KEY="" code . ``` PowerShell 可在当前会话设置： ```powershell $env:TEAM_GATEWAY_API_KEY = "" code . ``` 这里的占位符不要原样保留，也不要把真实 key 发给 Codex。若从 Dock、开始菜单或另一个远程环境启动 VS Code，它未必继承你在终端设置的变量。出现认证错误时，先确认编辑器进程是否来自同一环境，而不是立即更换 key。 OpenAI 的[自定义服务商文档](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)还支持 OpenAI auth、命令获取 token 或无认证的本地服务。选择哪一种取决于服务商实际支持的认证方式；不要同时堆叠互斥的认证方式。 ![Codex VS Code 从官方扩展、认证到自定义服务商的设置检查点](https://blog.laozhang.ai/posts/zh/codex-vscode-extension-api-key-custom-models/img/setup-checkpoints.webp) ## 用一次小任务证明设置真的可用 重载 VS Code 或重新打开 Codex 会话后，不要直接让一个陌生模型重构整个仓库。选一个你理解的函数，并检查 Git 工作区状态： ```bash git status --short ``` 打开目标文件，选中一个小函数，提交类似下面的任务： ```text 只检查我选中的 parseConfig 函数。 目标：让空字符串返回现有错误类型，不改变公开 API。 只允许修改当前文件；不要安装依赖，也不要执行部署命令。 完成后说明改动，并告诉我应运行哪一条现有测试。 ``` 验证时分四层看： 1. **会话可用**：没有立即出现登录或服务商认证失败。 2. **上下文正确**：回答准确提到选中函数中的真实变量或分支。 3. **修改受控**：VS Code diff 只包含允许文件，没有额外依赖或配置变化。 4. **结果成立**：项目原有测试或检查通过，`git diff` 与目标一致。 再次运行： ```bash git status --short git diff -- path/to/your-file ``` 只有四层都通过，才能说“这套 VS Code、认证、服务商与模型配置完成了首次可审查的任务”。一次普通回复成功不代表工具调用、长任务、图片输入或网页搜索等其他能力也一定兼容。 ![Codex VS Code 从安装到首次代码验证的实战流程与故障边界](https://blog.laozhang.ai/posts/zh/codex-vscode-extension-api-key-custom-models/img/verification-flow.webp) ## 按第一处失败定位，不要反复重装 | 现象 | 先检查 | 不要先做 | |---|---|---| | 找不到 Codex 图标或侧栏命令 | 官方扩展身份、当前窗口是否启用、Remote/WSL 扩展位置 | 更换 API key | | 侧栏停在登录页 | 当前认证路线、账户与工作区状态、密钥所属 OpenAI 项目 | 修改模型 ID | | 自定义服务商配置后仍走旧路线 | 是否编辑用户级文件、`model_provider` 是否匹配、是否有更高优先级配置 | 删除整个 Codex 目录 | | 401/403 | 编辑器是否继承环境变量、key 是否属于目标服务商、账户权限 | 把 key 粘贴到日志求助 | | 404 或 model not found | Base URL 路径、精确模型 ID、服务商的模型名称对应关系 | 随机尝试营销名称 | | 能聊天但工具或流式响应失败 | 服务商对 Responses、流式响应和工具调用的支持 | 宣称它“完全兼容”后继续大任务 | | 回答没用到当前代码 | 打开的文件、选区、任务范围、工作区信任与权限 | 一次授权整个磁盘 | 如果 Codex 已加载配置但行为仍不对，转到 [Codex config.toml 为什么没生效](https://blog.laozhang.ai/zh/posts/codex-config-toml)，按配置层、覆盖和服务商调用分别排查。不要把接口兼容问题继续当成 TOML 语法错误。 ## 完成设置后保留这份最小证据 不保存密钥等秘密信息，只记录下面这些非敏感信息，后续排错会快很多： - VS Code 与 Codex 扩展版本； - ChatGPT 登录、OpenAI API key 或自定义服务商三者中的当前路线； - 服务商 ID、Base URL 的主机名和模型 ID（不含访问令牌与认证请求头）； - 首次失败或成功的时间、原始错误文本和任务范围； - 修改前后的 `git status`、目标 diff 与测试命令结果。 这样，你得到的不是一份只能在今天复制的配置，而是一条可维护的判断链：入口由官方扩展负责，认证决定账户与账单，服务商决定接口地址与模型支持范围，最后由 diff 和项目检查决定这次代码修改是否值得保留。 ## 参考来源 本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-09-01。 - [当前认证说明](https://learn.chatgpt.com/docs/auth) (learn.chatgpt.com) - [Codex IDE 官方页面](https://learn.chatgpt.com/docs/codex/ide) (learn.chatgpt.com) - [OpenAI Platform API keys](https://platform.openai.com/api-keys) (platform.openai.com) - [基础配置文档](https://learn.chatgpt.com/docs/config-file/config-basic) (learn.chatgpt.com) - [自定义服务商文档](https://learn.chatgpt.com/docs/config-file/config-advanced) (learn.chatgpt.com)