> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code Codex 插件如何配置自定义 Base URL 和 API Key？

> 在 VS Code Codex 插件中打开共享的 config.toml，配置 BetterToken Base URL、API Key 和 GPT 分组模型，并排查插件未读取配置的问题。

## 直接答案

VS Code Codex 插件没有独立的 Base URL 和 API Key 输入框。它与 Codex CLI 共享配置层，因此你需要通过插件右上角的齿轮打开 **Codex Settings → Open config.toml**，再在用户级配置中添加 BetterToken provider。配置完成后执行 **Developer: Reload Window**，让插件读取新地址、密钥和模型。

<Info>
  如果你在 VS Code 设置里没有看到 `Base URL` 或 API Key 输入框，这是正常的。不要把自定义 endpoint 填到普通 VS Code 网络代理设置中。
</Info>

## 前置条件

* 已安装 VS Code
* 已安装 **Codex - OpenAI's coding agent** 插件
* 已获取 BetterToken API Key（<a href={"https://www.bettertoken.ai/register"}>注册并获取</a>）
* 已从<a href={"https://www.bettertoken.ai/pricing"}>模型广场</a>复制 **GPT 分组**下可用的模型 ID

<Warning>
  不要把 API Key 写进项目文件、`AGENTS.md`、`.env` 示例文件或公开仓库。下面的配置只应保存在你本机的 Codex 配置目录中。
</Warning>

## 配置方式

<Tabs>
  <Tab title="推荐：使用 Setup 弹窗">
    创建 API Key 后，控制台会弹出 **Setup** 弹窗。你可以在弹窗中复制 **API Key** 和 **Base URL**，并选择 Codex 相关配置方式。

    <Steps>
      <Step title="选择 Codex">
        在 **Available tools** 中选择 **Codex**。
      </Step>

      <Step title="选择配置方式">
        你可以选择：

        * **One-click Bash Configuration**：复制命令到本机终端执行，适合快速配置。
        * **CC Switch Integration**：导入到 CC Switch，适合统一管理多个工具。
        * **Manual Configuration**：复制 API Key 和 Base URL，手动写入 `config.toml`。
      </Step>

      <Step title="重启 VS Code">
        配置写入后，重启 VS Code，或执行 **Developer: Reload Window**，让 Codex 插件重新读取本机配置。
      </Step>
    </Steps>
  </Tab>

  <Tab title="手动配置">
    <Steps>
      <Step title="找到 config.toml">
        在 Codex 插件右上角点击齿轮，选择 **Codex Settings → Open config.toml**。也可以直接打开：

        | 系统            | 配置文件                                    |
        | ------------- | --------------------------------------- |
        | macOS / Linux | `~/.codex/config.toml`                  |
        | Windows       | `C:\Users\YOUR_USER\.codex\config.toml` |
        | Windows + WSL | WSL 内的 `~/.codex/config.toml`           |

        Codex CLI 和 IDE 插件会读取同一套配置。Windows 使用 WSL 打开工作区时，应修改 WSL 内的文件，而不是 Windows 用户目录中的另一份配置。
      </Step>

      <Step title="写入 BetterToken provider">
        将下面配置添加到 `config.toml`。如果文件中已经有同名字段，请合并配置，不要重复写多个 `model_provider`。

        ```toml theme={null}
        model_provider = "custom"
        model = "gpt-5.5"
        review_model = "gpt-5.4"
        model_reasoning_effort = "high"
        model_context_window = 1000000
        model_auto_compact_token_limit = 900000
        windows_wsl_setup_acknowledged = true

        [model_providers]
        [model_providers.custom]
        name = "BetterToken"
        base_url = "https://www.bettertoken.ai/v1"
        wire_api = "responses"
        requires_openai_auth = true
        experimental_bearer_token = "YOUR_API_KEY"
        request_max_retries = 4
        stream_max_retries = 8
        stream_idle_timeout_ms = 300000
        supports_websockets = false
        ```

        将 `YOUR_API_KEY` 替换为你的 BetterToken API Key。
      </Step>

      <Step title="确认关键字段">
        重点检查这几项：

        | 字段                          | 应填写                             |
        | --------------------------- | ------------------------------- |
        | `base_url`                  | `https://www.bettertoken.ai/v1` |
        | `wire_api`                  | `responses`                     |
        | `model`                     | 从 **GPT 分组**复制的模型 ID            |
        | `experimental_bearer_token` | 你的 BetterToken API Key          |

        <Warning>
          VS Code Codex 插件场景下，不建议把 `auth.json` 改成 API Key 结构。`auth.json` 用于保留 Codex 官方登录态；第三方 API Key 应放在 `experimental_bearer_token` 中。
        </Warning>
      </Step>

      <Step title="重启 VS Code">
        修改完成后，关闭当前 Codex 会话，并重启 VS Code。

        也可以在命令面板执行：

        ```text theme={null}
        Developer: Reload Window
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 为什么这里要保留官方登录态？

VS Code Codex 插件依赖 Codex 的应用侧能力，例如插件界面、会话管理和 VS Code 集成。因此推荐保留官方登录态，同时让模型请求走 BetterToken。

这组配置中：

| 配置                                           | 作用                                                          |
| -------------------------------------------- | ----------------------------------------------------------- |
| `requires_openai_auth = true`                | 保留 Codex 官方登录态                                              |
| `experimental_bearer_token = "YOUR_API_KEY"` | 使用 BetterToken API Key 发起模型请求                               |
| `base_url = "https://www.bettertoken.ai/v1"` | 将模型请求发送到 BetterToken 的 OpenAI-compatible / Responses API 入口 |

<Note>
  Codex 官方配置参考更推荐普通自定义 provider 通过 `env_key` 读取 API Key。本页使用 `experimental_bearer_token`，是因为目标场景还需要保留 Codex 官方登录态。如果你只使用 Codex CLI，不需要插件、Remote Control 或官方登录态，请使用 [config.toml 普通自定义 provider 配置](/zh/faq/codex/config-toml)。
</Note>

## 验证插件读取的是哪份配置

完成配置后，在 VS Code 中打开 Codex 插件，发送一条简单测试消息。

如果能正常回复，说明配置已生效。还可以从插件齿轮再次打开 `config.toml`，确认它指向你刚才修改的文件。

## 常见错误与解决方法

| 现象                        | 原因                                          | 解决方法                                                                |
| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------- |
| Codex CLI 正常，VS Code 插件失败 | 插件运行在另一环境或仍使用旧窗口                            | 从插件齿轮打开实际配置；WSL 项目修改 WSL 内文件；执行 **Developer: Reload Window**        |
| 插件仍要求官方登录                 | Codex IDE 扩展需要应用侧登录                         | 先完成官方登录，再保留 `requires_openai_auth = true` 和第三方 bearer token         |
| `401` 或 `403`             | API Key 错误或 `experimental_bearer_token` 未替换 | 重新复制 Key，不要修改 `auth.json` 中的官方登录内容                                  |
| `404`                     | Base URL 缺少 `/v1`                           | 使用 `https://www.bettertoken.ai/v1`                                  |
| Model not found           | 模型 ID 不属于 GPT 分组                            | 从<a href={"https://www.bettertoken.ai/pricing"}>模型广场</a>重新复制当前可用 ID |
| TOML 解析失败                 | 同一字段或表重复声明                                  | 合并已有配置，只保留一个 `[model_providers.custom]`                             |

## 相关文档

* [Codex 接入 BetterToken 指南](/zh/ai-tools/codex)
* [如何在使用第三方 API 的同时保留 Codex 登录态？](/zh/faq/codex/official-login-third-party-api)
* [如何配置 Codex CLI 的 config.toml？](/zh/faq/codex/config-toml)
* [Codex CLI 中 model\_provider、base\_url 和 wire\_api 是什么？](/zh/faq/codex/model-provider-base-url-wire-api)

## References

* [Codex IDE extension](https://developers.openai.com/codex/ide)
* [Codex basic configuration](https://developers.openai.com/codex/config-basic)
* [Codex configuration reference](https://developers.openai.com/codex/config-reference)