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

# CC-Switch 接入 XRouter

> 在 CC-Switch 中导入或手动添加 XRouter Provider，并切换 Claude Code、Codex 和 Gemini 配置。

CC-Switch 是一个桌面应用，用来统一管理 Claude Code、Codex、Gemini 等 AI 编程工具的 Provider 配置。接入 XRouter 后，你可以在图形界面里切换 Provider，不需要反复手动编辑各个工具的配置文件。

<Info>
  XRouter 控制台提供 CC-Switch 导入入口，用于生成 `ccswitch://` 导入链接。导入后如需检查或调整配置，请以 CC-Switch 主界面中的 Provider 表单为准。
</Info>

## 前置条件

* 本机已安装 CC-Switch。
* 本机已安装要使用的 CLI 工具，例如 Claude Code 或 Codex CLI。
* 已在 XRouter 控制台创建 API Key。
* 已从控制台模型页复制目标模型 ID。

## 安装 CC-Switch

<Tabs>
  <Tab title="macOS">
    ```bash Terminal theme={null}
    brew tap farion1231/ccswitch
    brew install --cask cc-switch
    ```
  </Tab>

  <Tab title="Windows">
    从 CC-Switch Releases 下载 `.msi` 安装包或便携版 `.zip`，安装后启动应用。
  </Tab>

  <Tab title="Linux">
    从 CC-Switch Releases 下载适合发行版的安装包，例如 `.deb`、`.rpm` 或 `.AppImage`。
  </Tab>
</Tabs>

## 从 XRouter 控制台导入

在 XRouter 控制台的 API Keys 页面，选择一把 Key 后打开 CC-Switch 导入弹窗。

<Note>
  待补图片：XRouter 控制台里的 Import to CC Switch 弹窗，展示 Claude、Codex、Gemini 选择和模型选择。截图必须使用假 Key。
</Note>

导入弹窗会让你选择：

| 字段                          | 说明                           |
| --------------------------- | ---------------------------- |
| Application                 | 要导入的工具：Claude、Codex 或 Gemini |
| Name                        | Provider 在 CC-Switch 中显示的名称  |
| Model                       | 主模型 ID，从 XRouter 控制台模型页复制    |
| Haiku / Sonnet / Opus Model | Claude 可选模型字段，按需要填写          |

点击打开 CC-Switch 后，CC-Switch 会导入对应 Provider。

<Note>
  待补图片：CC-Switch 桌面端 Provider 已导入并启用的界面。截图中需要隐藏本机用户名和不相关 Provider。
</Note>

## 手动添加 Provider

如果一键导入不可用，也可以在 CC-Switch 里手动添加。

<Tabs>
  <Tab title="Claude Code">
    | 字段           | 填写内容                      |
    | ------------ | ------------------------- |
    | Name         | `XRouter`                 |
    | Endpoint URL | `https://api.xrouter.dev` |
    | API Key      | `sk-your-api-key`         |
    | API Format   | `Anthropic Messages`      |
    | Model        | `your-claude-model-id`    |

    Claude Code 使用服务根地址，不追加 `/v1/messages`。
  </Tab>

  <Tab title="Codex">
    Codex 使用 OpenAI 兼容地址，需要 `/v1` 后缀。

    ```toml config.toml theme={null}
    model = "your-codex-model-id"
    model_provider = "xrouter"

    [model_providers.xrouter]
    name = "XRouter"
    base_url = "https://api.xrouter.dev/v1"
    wire_api = "responses"
    env_key = "XROUTER_API_KEY"
    ```

    同时确认环境变量中存在：

    ```bash Terminal theme={null}
    export XROUTER_API_KEY="sk-your-api-key"
    ```
  </Tab>

  <Tab title="Gemini">
    | 字段           | 填写内容                      |
    | ------------ | ------------------------- |
    | Name         | `XRouter`                 |
    | Endpoint URL | `https://api.xrouter.dev` |
    | API Key      | `sk-your-api-key`         |
    | Model        | `your-gemini-model-id`    |

    Gemini 兼容接口使用 `/v1beta/models/...` 路径，具体路径通常由客户端根据模型和动作生成。
  </Tab>
</Tabs>

<Warning>
  不同工具的 endpoint 不同：Claude Code 使用服务根地址；Codex 使用 OpenAI 兼容地址并带 `/v1`。不要混用。
</Warning>

## 切换 Provider

<Steps>
  <Step title="选择工具分组">
    在 CC-Switch 顶部选择目标工具，例如 Claude、Codex 或 Gemini。
  </Step>

  <Step title="选中 XRouter Provider">
    在 Provider 列表中选择你导入或手动创建的 `XRouter` Provider。
  </Step>

  <Step title="启用配置">
    点击启用或切换按钮。看到成功提示后，新的 Provider 会写入对应工具配置。
  </Step>

  <Step title="重启目标工具">
    Claude Code 通常开启新会话即可；Codex CLI 建议重新打开终端后再启动。
  </Step>
</Steps>

## 常见问题

<AccordionGroup>
  <Accordion title="控制台点击导入后没有反应">
    确认本机已安装 CC-Switch，并且系统已经注册 `ccswitch://` 协议。如果浏览器拦截外部应用打开，请允许打开 CC-Switch。
  </Accordion>

  <Accordion title="切换 Provider 后没有生效">
    重启目标 CLI。Claude Code 请开启新会话；Codex CLI 请关闭当前会话，并重新打开终端后启动。
  </Accordion>

  <Accordion title="提示 API Key 无效">
    确认 API Key 以 `sk-` 开头，复制时没有多余空格，并到 XRouter 控制台确认 Key 状态正常。
  </Accordion>

  <Accordion title="Codex Provider 格式错误">
    检查 TOML 是否合法，`wire_api` 是否为 `responses`，`base_url` 是否带 `/v1`。
  </Accordion>
</AccordionGroup>