> ## 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.

# Codex 接入 BetterToken 指南

> 在 OpenAI Codex 中使用 BetterToken，使用 /v1 与 OpenAI Responses。

在 Codex 中接入 BetterToken，需要配置自定义模型提供商和 API Key。`base_url` 必须填写为 `https://www.bettertoken.ai/v1`，协议为 `OpenAI Responses`。

## 前置条件

* 已安装 Node.js
* 已获取 BetterToken API Key（注册并获取 (`https://www.bettertoken.ai/register`)）

<Warning>
  配置前请先清除 OpenAI 相关环境变量，避免它们覆盖 `config.toml` 或 `auth.json` 中的设置。

  需要清除的变量包括：

  * `OPENAI_API_KEY`
  * `OPENAI_BASE_URL`

  macOS / Linux 执行：

  ```bash theme={null}
  unset OPENAI_API_KEY
  unset OPENAI_BASE_URL
  ```

  Windows PowerShell 执行：

  ```powershell theme={null}
  Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
  Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
  [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
  [Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")
  ```
</Warning>

## 安装 Codex

```bash theme={null}
npm install -g @openai/codex
```

## 配置步骤

<Tabs>
  <Tab title="自动配置">
    你可以直接运行 BetterToken 提供的自动配置脚本。它只负责写入 BetterToken provider 配置，不替代页面上方的安装前置条件。脚本需要 `Node.js`。如果你没有显式传入 API Key 或模型，脚本会按工具能力提示你交互输入。

    按你的操作系统执行对应步骤。你只需要执行其中一项。

    <Steps>
      <Step title="如果你使用 macOS / Linux">
        ```bash theme={null}
        curl -fsSL https://www.bettertoken.ai/install-codex-provider.sh | bash
        ```
      </Step>

      <Step title="如果你使用 Windows">
        ```powershell theme={null}
        iwr https://www.bettertoken.ai/install-codex-provider.ps1 -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="通过 CC-Switch 配置">
    这条接入路径由 [CC Switch 接入文档](/ai-tools/cc-switch#codex-cli) 统一维护。

    直接查看 [CC Switch 中的 Codex 配置步骤](/ai-tools/cc-switch#codex-cli)。

    通过 CC Switch 完成配置后，再回到本页继续参考启动、验证或生效说明。
  </Tab>

  <Tab title="手动配置">
    <Steps>
      <Step title="从模型广场复制模型 ID">
        打开 BetterToken 模型广场 (`https://www.bettertoken.ai/pricing`)，复制 **Codex 分组**下当前可用的模型 ID。下文示例中的 `YOUR_CODEX_MODEL_ID` 都应替换为这个值。
      </Step>

      <Step title="确认配置文件位置">
        手动配置需要同时修改 Codex 的 `config.toml` 和 `auth.json`。

        | 系统            | `config.toml`                           | `auth.json`                           |
        | ------------- | --------------------------------------- | ------------------------------------- |
        | macOS / Linux | `~/.codex/config.toml`                  | `~/.codex/auth.json`                  |
        | Windows       | `C:\Users\YOUR_USER\.codex\config.toml` | `C:\Users\YOUR_USER\.codex\auth.json` |
      </Step>

      <Step title="编辑 Codex 配置文件">
        打开 `config.toml`（不存在则新建）。

        <Warning>
          这里的配置只适用于手动修改 `~/.codex/config.toml`。如果你使用 CC Switch 配置 Codex，请严格按照 [CC Switch 接入文档](/ai-tools/cc-switch#codex-cli) 操作，不要直接复制这里的信息去替换 CC Switch 管理的配置。
        </Warning>

        添加以下内容：

        ```toml theme={null}
        model_provider = "bettertoken"
        model = "YOUR_CODEX_MODEL_ID"
        model_reasoning_effort = "high"
        disable_response_storage = true

        [model_providers.bettertoken]
        name = "BetterToken"
        base_url = "https://www.bettertoken.ai/v1"
        wire_api = "responses"
        requires_openai_auth = true
        model_context_window = 1000000
        model_auto_compact_token_limit = 900000
        ```
      </Step>

      <Step title="写入 Codex 认证文件">
        打开 `auth.json`（不存在则新建）。

        写入以下内容（`YOUR_API_KEY` 替换为你的 BetterToken API Key）：

        ```json theme={null}
        {
          "OPENAI_API_KEY": "YOUR_API_KEY"
        }
        ```
      </Step>

      <Step title="重启终端中的 Codex">
        修改 `config.toml` 或 `auth.json` 后，请结束当前 Codex 进程，并在新终端会话中重新启动。
      </Step>

      <Step title="启动 Codex">
        ```bash theme={null}
        codex
        ```
      </Step>
    </Steps>

    ### 配置参数说明

    | 参数                         | 说明                                                                       |
    | -------------------------- | ------------------------------------------------------------------------ |
    | `model_provider`           | 当前默认使用的模型提供商标识，需要与 `[model_providers.bettertoken]` 中的 `bettertoken` 保持一致 |
    | `model`                    | Codex 启动后默认使用的模型 ID，请填写从模型广场复制的 **Codex 分组**模型                           |
    | `model_reasoning_effort`   | 模型推理强度，可按需要设置为 `low`、`medium` 或 `high`                                   |
    | `disable_response_storage` | 禁用响应存储，建议保持为 `true`                                                      |
    | `name`                     | 提供商显示名称，可保持为 `BetterToken`                                               |
    | `base_url`                 | BetterToken 的 Codex / OpenAI-compatible 协议入口，必须带 `/v1`                   |
    | `wire_api`                 | Codex 使用的 API 协议，保持为 `responses`                                         |
    | `requires_openai_auth`     | 使用 Codex 的 OpenAI 认证文件读取 API Key，保持为 `true`                              |

    ### 1M 上下文配置

    如果你使用支持长上下文的 **Codex 分组**模型，建议保留以下两项配置：

    ```toml theme={null}
    model_context_window = 1000000
    model_auto_compact_token_limit = 900000
    ```

    | 参数                               | 作用                             |
    | -------------------------------- | ------------------------------ |
    | `model_context_window`           | 将可用上下文窗口设置为 `1,000,000` tokens |
    | `model_auto_compact_token_limit` | 接近上限前提前触发压缩，减少对话直接撞满上下文的概率     |

    如果你通过 CC Switch 写入配置，请优先以 CC Switch 生成的配置为准。只有在手动配置或排障时，才建议自行修改这些参数。
  </Tab>
</Tabs>

## 验证配置

启动后，向 Codex 发送一条测试消息，确认收到正常回复即表示配置成功。

如遇到连接问题，请检查：

1. `base_url` 是否填写为 `https://www.bettertoken.ai/v1`
2. `wire_api` 是否保持为 `responses`
3. `model` 是否为从模型广场 (`https://www.bettertoken.ai/pricing`)复制的 **Codex 分组**模型 ID
4. `~/.codex/auth.json` 中的 `OPENAI_API_KEY` 是否为你的 BetterToken API Key
5. 是否有旧的 `OPENAI_API_KEY` 或 `OPENAI_BASE_URL` 环境变量在干扰配置