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

# Claude Desktop 自定义模型接入 BetterToken 指南

> 在 Claude 桌面端启用 developer mode，并配置 BetterToken API 作为第三方推理网关。

Claude 桌面端支持通过 developer mode 配置第三方推理网关。你可以根据 BetterToken API Key 分组，选择直接填写 Anthropic 协议入口，或通过 CC Switch 本地路由转发请求。

<Info>
  如果你使用 **Claude 分组** API Key，可以在 Claude 桌面端直接填写 `https://www.bettertoken.ai`。如果你使用 **GPT 分组** API Key，建议先通过 CC Switch 建立本地路由，再把本地服务地址填入 Claude 桌面端。不要把 Codex / OpenAI-compatible 协议使用的 `https://www.bettertoken.ai/v1` 直接填进 Claude 桌面端 Gateway。
</Info>

## 配置步骤

<Steps>
  <Step title="下载 Claude 桌面端">
    通过官方链接下载最新版 Claude 桌面端：

    [下载 Claude for Mac](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect)

    安装完成后不要登录 Claude 账号，直接进入下一步启用 developer mode。
  </Step>

  <Step title="启用 developer mode">
    打开 Claude 桌面端后，在 macOS 左上角菜单中选择 **Help** → **Troubleshooting** → **Enable Developer Mode**。

    <Frame>
      <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/claude-desktop-llmeasy-api/enable-developer-mode-menu.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=88d5591c4fc6690a13b846df03f84991" alt="在 Claude 桌面端 Help 菜单里选择 Enable Developer Mode。" style={{ borderRadius: '0.5rem' }} width="3840" height="2160" data-path="images/claude-desktop-llmeasy-api/enable-developer-mode-menu.png" />
    </Frame>

    在确认窗口中点击 **Enable**，然后重启 Claude 桌面端。

    <Frame>
      <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/developer-mode-confirm.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=ec60755e271216c1383bd7ec466c58db" alt="确认启用 Claude 桌面端 developer mode。" style={{ borderRadius: '0.5rem' }} width="520" height="480" data-path="images/claude-desktop-llmeasy-api/developer-mode-confirm.png" />
    </Frame>
  </Step>

  <Step title="打开第三方推理配置">
    重启后，macOS 左上角菜单会出现 **Developer** 选项。

    选择 **Developer** → **Configure Third-Party Inference...**。

    <Frame>
      <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/claude-desktop-llmeasy-api/configure-third-party-inference.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=f4412369928fe11c78433578e0efa60a" alt="在 Developer 菜单中选择 Configure Third-Party Inference。" style={{ borderRadius: '0.5rem' }} width="3840" height="2160" data-path="images/claude-desktop-llmeasy-api/configure-third-party-inference.png" />
    </Frame>
  </Step>
</Steps>

完成前 3 步后，根据你的 BetterToken API Key 分组选择继续配置方式。

<Tabs>
  <Tab title="Claude 分组">
    <Steps>
      <Step title="填写 BetterToken API 信息">
        在配置窗口中选择 **Gateway**，然后填写以下信息：

        | 字段                      | 填写内容                                    |
        | ----------------------- | --------------------------------------- |
        | **Gateway base URL**    | `https://www.bettertoken.ai`            |
        | **Gateway API key**     | 在 BetterToken 控制台的 **令牌管理** 中复制 API Key |
        | **Gateway auth scheme** | `x-api-key`                             |

        选择 **Gateway auth scheme** 后，Claude 桌面端会自动获取 **Claude 分组**下可用的模型。填写完成后点击 **Apply locally**。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/claude-desktop-llmeasy-api/gateway-credentials.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=14951973725bde190ce650415e7b67f8" alt="在 Claude 桌面端配置 BetterToken Gateway 信息并点击 Apply locally。" style={{ borderRadius: '0.5rem' }} width="1800" height="1440" data-path="images/claude-desktop-llmeasy-api/gateway-credentials.png" />
        </Frame>
      </Step>

      <Step title="确认重启客户端">
        Claude 写入本地配置后会提示保存并重启。点击 **Save & Restart**，让新网关配置生效。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/relaunch-claude.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=9f6734947d08bab9e20a4e7e7435314c" alt="Claude 桌面端提示 Save & Restart，点击 Save & Restart 保存并重启客户端。" style={{ borderRadius: '0.5rem' }} width="1800" height="2046" data-path="images/claude-desktop-llmeasy-api/relaunch-claude.png" />
        </Frame>
      </Step>

      <Step title="选择 Gateway 网关登录">
        重启后等待约 3 秒，会出现登录方式选择界面。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/continue-with-gateway.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=cdd2a315ee2850d07bbaac39f0e06756" alt="Claude 桌面端显示 Continue with Gateway 登录选项。" style={{ borderRadius: '0.5rem' }} width="1200" height="1200" data-path="images/claude-desktop-llmeasy-api/continue-with-gateway.png" />
        </Frame>

        选择 **Continue with Gateway**。进入 Claude 后，左下角显示 **Cowork 3P | Gateway**，即可正常使用。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/gateway-ready.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=292b7db7ffddbcb11be3312dda097997" alt="Claude 桌面端已通过 Gateway 进入并可以正常使用。" style={{ borderRadius: '0.5rem' }} width="3840" height="2100" data-path="images/claude-desktop-llmeasy-api/gateway-ready.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="GPT 分组">
    <Steps>
      <Step title="切到 Claude Code 并添加 provider">
        打开 CC Switch，切到 **Claude Code**，点击 **Add Provider**。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/qbH0nwqS9mSIdsda/images/cc-switch/claude-code-add-provider.png?fit=max&auto=format&n=qbH0nwqS9mSIdsda&q=85&s=517f215f5f828187647dd214eacfe19b" alt="CC Switch 的 Claude Code 页面，右上角加号按钮用于新增 provider。" style={{ borderRadius: '0.5rem' }} width="2000" height="1792" data-path="images/cc-switch/claude-code-add-provider.png" />
        </Frame>
      </Step>

      <Step title="填写基础字段">
        * **Provider Name**：`BetterToken`
        * **Base URL**：`https://www.bettertoken.ai`
        * **API Key**：你的 BetterToken API Key

        下图中的标注对应：

        1. **Provider Name**
        2. **API Key**
        3. **Base URL**

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/cc-switch/claude-code-basic-fields.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=52f2f9c51f8c709da0654fff89977b59" alt="CC Switch 的 provider 编辑页面，标出了 Provider Name、API Key 和 Base URL 的填写位置。" style={{ borderRadius: '0.5rem' }} width="2000" height="1898" data-path="images/cc-switch/claude-code-basic-fields.png" />
        </Frame>
      </Step>

      <Step title="设置 API 格式和模型映射">
        打开 **高级选项**，在 **API 格式** 中选择 **OpenAI Responses API**。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/cc-switch/claude-code-api-format.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=78fd213694139a6457f16de0a4b1642c" alt="CC Switch 的高级选项区域，API 格式被设置为 OpenAI Responses API。" style={{ borderRadius: '0.5rem' }} width="2000" height="1792" data-path="images/cc-switch/claude-code-api-format.png" />
        </Frame>

        在 **模型映射** 里点击 **获取模型列表**，将 **主模型**、**推理模型（Thinking）**、**Haiku 默认模型**、**Sonnet 默认模型**、**Opus 默认模型** 都从下拉列表中显式选中。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/qbH0nwqS9mSIdsda/images/cc-switch/claude-code-model-mapping.png?fit=max&auto=format&n=qbH0nwqS9mSIdsda&q=85&s=6a59bc2ab875c6c262656fbcc3e811f9" alt="CC Switch 的模型映射区域，展示了获取模型列表以及主模型、Thinking、Haiku、Sonnet、Opus 的映射位置。" style={{ borderRadius: '0.5rem' }} width="2000" height="1792" data-path="images/cc-switch/claude-code-model-mapping.png" />
        </Frame>

        这里使用的模型都应来自 <a href={"https://www.bettertoken.ai/pricing"}>BetterToken 模型广场</a> 当前可用的 **GPT 分组**模型 ID。
      </Step>

      <Step title="保存、切换，并开启代理">
        保存后，回到渠道列表页：

        1. 将刚保存的 BetterToken provider 设为 **使用中**
        2. 打开左上角的 **CC Switch 代理功能**

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/cc-switch/claude-code-enable-proxy.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=388cb7aa77282c5d7ae090a9f7291a56" alt="保存后回到渠道列表页，将 BetterToken 设为使用中，并打开左上角的 CC Switch 代理开关。" style={{ borderRadius: '0.5rem' }} width="2000" height="1792" data-path="images/cc-switch/claude-code-enable-proxy.png" />
        </Frame>
      </Step>

      <Step title="进入 CC Switch 设置">
        回到 CC Switch 主界面后，点击左上角的 **设置**。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/claude-desktop-llmeasy-api/cc-switch-settings-entry.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=6a1028431ba18e7981ed24062211cb1c" alt="CC Switch 主界面中，左上角设置按钮被箭头标出。" style={{ borderRadius: '0.5rem' }} width="2000" height="1302" data-path="images/claude-desktop-llmeasy-api/cc-switch-settings-entry.png" />
        </Frame>
      </Step>

      <Step title="确认路由已打开并复制服务地址">
        进入 **路由** 设置，确认图中标注的 **路由总开关** 和 **Claude** 路由开关都已打开。然后复制下方显示的 **服务地址**。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/cc-switch-route-service.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=cadbb3ee3defaa9f4f8d419074607026" alt="CC Switch 路由设置页中，路由总开关、Claude 路由开关和服务地址复制按钮被标出。" style={{ borderRadius: '0.5rem' }} width="2000" height="1302" data-path="images/claude-desktop-llmeasy-api/cc-switch-route-service.png" />
        </Frame>
      </Step>

      <Step title="在 Claude 桌面端填入 Gateway base URL">
        回到 Claude 桌面端的第三方推理配置窗口，选择 **Gateway**。把刚才复制的 CC Switch **服务地址** 填入 **Gateway base URL**，并填写你的 BetterToken API Key。

        **Gateway auth scheme** 选择 `bearer`。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/claude-gateway-local-route.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=0fb9eb62189e501116d16dfdac54153c" alt="Claude 桌面端 Gateway 配置页中填入 CC Switch 本地服务地址。" style={{ borderRadius: '0.5rem' }} width="1800" height="1440" data-path="images/claude-desktop-llmeasy-api/claude-gateway-local-route.png" />
        </Frame>
      </Step>

      <Step title="添加模型列表并应用到本机">
        在 **Model list** 里增加要展示的模型。每个模型都需要同时填写 **Model ID** 和 **Display name**。

        例如：

        | Model ID        | Display name    |
        | --------------- | --------------- |
        | `claude-opus-4` | `Claude Opus 4` |

        填写完成后点击 **Apply locally**。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/claude-model-list-codex-group.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=754f1468abb9da6007c591d041269575" alt="Claude 桌面端 Model list 中填写 Model ID 和 Display name，并点击 Apply locally。" style={{ borderRadius: '0.5rem' }} width="1800" height="1440" data-path="images/claude-desktop-llmeasy-api/claude-model-list-codex-group.png" />
        </Frame>
      </Step>

      <Step title="确认重启客户端">
        Claude 写入本地配置后会提示保存并重启。点击 **Save & Restart**，让新网关配置生效。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/relaunch-claude.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=9f6734947d08bab9e20a4e7e7435314c" alt="Claude 桌面端提示 Save & Restart，点击 Save & Restart 保存并重启客户端。" style={{ borderRadius: '0.5rem' }} width="1800" height="2046" data-path="images/claude-desktop-llmeasy-api/relaunch-claude.png" />
        </Frame>
      </Step>

      <Step title="选择 Gateway 网关登录">
        重启后等待约 3 秒，会出现登录方式选择界面。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/continue-with-gateway.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=cdd2a315ee2850d07bbaac39f0e06756" alt="Claude 桌面端显示 Continue with Gateway 登录选项。" style={{ borderRadius: '0.5rem' }} width="1200" height="1200" data-path="images/claude-desktop-llmeasy-api/continue-with-gateway.png" />
        </Frame>

        选择 **Continue with Gateway**。进入 Claude 后，左下角显示 **Cowork 3P | Gateway**，即可正常使用。

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/yi2bQP5Q3QRPQ3t1/images/claude-desktop-llmeasy-api/gateway-ready.png?fit=max&auto=format&n=yi2bQP5Q3QRPQ3t1&q=85&s=292b7db7ffddbcb11be3312dda097997" alt="Claude 桌面端已通过 Gateway 进入并可以正常使用。" style={{ borderRadius: '0.5rem' }} width="3840" height="2100" data-path="images/claude-desktop-llmeasy-api/gateway-ready.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 排查建议

如果 Claude 桌面端没有出现 **Developer** 菜单，确认你已经点击 **Enable** 并完全重启应用。

如果请求失败，优先检查：

1. **Gateway base URL** 是否与分组路径一致：**Claude 分组**填写 `https://www.bettertoken.ai`；**GPT 分组**填写 CC Switch 复制出的本地服务地址
2. **Gateway API key** 是否来自 BetterToken 控制台的 **令牌管理**
3. **Gateway auth scheme** 是否与 API Key 分组匹配：**Claude 分组**使用 `x-api-key`，**GPT 分组**使用 `bearer`
4. 是否点击了 **Apply locally**
5. 如果使用 **GPT 分组**，是否已在 CC Switch **路由**设置中打开 **路由总开关** 和 **Claude** 路由开关
6. 是否点击 **Save & Restart** 并在重启后选择 **Continue with Gateway**