HRouter Desktop：一键配置 Claude Code、Codex、Gemini CLI
HRouter Desktop 是一个开源的桌面应用，用来集中管理 Claude Code、Codex、Gemini CLI 等 AI 编程工具的接入配置。你只需要提供一个 HRouter Key，它会读取这个 Key 实际可用的模型，并把正确的 API 地址、Key 和模型写入各工具的配置文件，不用再手动编辑 JSON、TOML 或环境变量。
它基于开源项目 CC Switch（MIT License）二次开发，保留原项目版权声明；HRouter 的品牌和定制功能不代表 CC Switch 官方版本。
适合谁用
- 同时使用多个 AI 编程工具，不想分别记每个工具的配置格式。
- 不熟悉环境变量、
config.toml、settings.json，希望点几下就能用。 - 有多个 Key（个人、团队、不同套餐），需要随时切换。
如果你更习惯自己维护配置文件，直接看 Claude Code 手动配置 或 Codex 手动配置。
下载与安装
| 系统 | 安装包 | 说明 |
|---|---|---|
| macOS | .dmg |
仅支持 Apple 芯片（M 系列），macOS 12 及以上 |
| Windows | -setup.exe |
x64 |
- 前往 Releases 下载最新版本
- 查看开源源码
- 已安装的版本可以在应用内检查更新。
请只从上面的 GitHub 仓库下载，不要下载原版 CC Switch 代替 HRouter 版本。Intel 芯片的 Mac 目前不支持。
支持的工具
Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi Agent、DeepSeek Harness、WorkBuddy。每个工具使用独立的适配器，支持的功能范围不同，具体以应用内显示为准。
第 1 步：准备 HRouter Key
- 登录 https://hrouter.net。
- 在 API 密钥 页面创建或复制一个 Key，Key 以
sk-开头。 - 确认 Key 状态可用，分组与你要配置的工具相符。不确定分组怎么选，看 如何选择 Key 分组。
第 2 步：给工具添加 HRouter
下面以 Codex 为例，其他工具的步骤完全一样，只是在第 1 步选择不同的工具。截图中的模型数量、模型名和配置名称是演示结果，以你自己的 Key 返回为准。
1. 打开配置中心，选择工具，点击新增。
顶部点击 配置中心，选择要配置的工具（Claude Code、Codex、Gemini、Grok Build 等），再点击右上角橙色的 ＋。页面里已有的供应商卡片是示例，你不需要照着建立；已启用的卡片会显示 使用中。
2. 切换到“HRouter 快捷接入”。
进入“添加供应商”页面后，点击顶部的 HRouter 快捷接入。旁边的“通用接入”是手动填写供应商名称、API 地址、默认模型的另一条路径，用快捷接入就不用再填。
3. 填写 Key，点击“识别 Key”。
把 sk-... 格式的 Key 粘贴到 HRouter Key 输入框，点击右侧 识别 Key。Key 只保存在本机配置中，用于读取这个 Key 实际可用的模型。截图或录屏时保持 Key 隐藏。
4. 检查识别结果、默认模型和模型映射。
识别成功后右侧会显示 已识别，并提示“已读取 N 个模型”。接着检查：
- 默认模型：工具启动时使用的模型。
- 模型映射：每一行有“显示名称”和“实际模型 ID”。显示名称只用于工具里的模型菜单，实际模型 ID 会原样发送给 HRouter，必须来自 Key 返回的列表。
- 一键推荐映射：会替换当前映射列表，只映射 Key 可用的推荐模型，使用前先读清页面提示。
预填的只是推荐值，保存后还可以再编辑。
5. 查看生成的配置，确认后添加。
向下滚动可以看到生成的 config.toml（Claude Code 等工具会显示对应的配置）和当前 Key 的完整模型列表。核对模型和接口地址后，点击右下角 添加 HRouter。上下文窗口、Goal 模式、远程压缩这些高级选项保持默认即可，不需要为了和截图一致而调整。
6. 启用并测试。
回到配置中心，确认新建的 HRouter 卡片显示 使用中；如果没有，点击卡片上的 启用。然后刷新或重新打开对应工具，发一句最短的测试消息：
请用一句话介绍你自己。
收到正常回复，并且在 使用记录 里能看到请求，就接好了。测试消息会真实调用模型，可能消耗少量额度。
遇到报错先看本页末尾的常见问题，或者对照 常见问题汇总。
自动写入的 API 地址
| 工具 | API 地址 | 写入方式 |
|---|---|---|
| Codex | https://hrouter.net/v1 |
使用 Responses API，写入 auth.json 与 config.toml |
| Claude Code / Claude Desktop | https://hrouter.net |
写入 ANTHROPIC_BASE_URL 和 Key |
| Gemini CLI | https://hrouter.net |
写入 Gemini Base URL、Key 和模型 |
| Grok Build | https://hrouter.net/v1 |
自动配置 grok-4.5 与 Responses 协议 |
| OpenCode / OpenClaw / Hermes | https://hrouter.net/v1 |
生成对应工具的 HRouter 供应商配置 |
这些地址为什么不同，见 API 地址对照表。
模型绑定
HRouter Desktop 不写死模型清单：每次“识别 Key”都读取服务器实际返回的模型，再按工具过滤并预填推荐值。预填值只是起点，保存前后都可以再改。
- Codex：可选择当前 Key 返回的 OpenAI / Codex 模型，也可以设置上下文窗口和远程压缩开关。
- Claude Code：可设置默认模型，以及 Haiku、Sonnet、Opus 三个角色各自对应的模型。
- Gemini CLI：选择当前 Key 开放的 Gemini 模型。
- Grok Build：使用
grok-4.5。
下图是 Claude Desktop 的模型绑定页，Claude 系列工具的映射都是这个结构：
- 客户端模型 ID：决定工具识别到的模型能力和思考菜单。
- 上游模型 ID：HRouter 实际请求的模型，必须来自当前 Key 返回的列表。
- 菜单显示名（可选）：只改菜单里显示的名称，不改变能力。
- 按已导入列表重新推荐：会替换下方的映射，按版本号为各角色选出最新可用的模型。导入列表和打开编辑页都不会覆盖你已保存的手动映射。
- 设为默认模型：选择哪一行作为默认使用的模型。
不要用更新的模型 ID 去冒充旧模型的能力，客户端模型 ID 和上游模型 ID 保持一致最稳妥。
选什么模型更合适，见 编程场景怎么选模型。
多个 Key 与切换
同一个工具下可以添加多个 HRouter 配置，默认名称依次为 HRouter、HRouter 2、HRouter 3，可以改成套餐名或用途，方便切换。切换后重启终端或工具即可，Claude Code 的部分配置可以热切换。
配置保护与备用线路（可选）
- 配置保护：主动开启后，切换前可预览改动并保留你自定义的字段，还会保存本地快照，方便恢复。
- 备用线路：可以为模型设置主备供应商和故障转移顺序，供应商由你自己选择。
- 用量统计：查看请求日志、Token 与缓存明细和本地费用估算。费用是估算值，不是账单，实际扣费以 HRouter 控制台的使用记录为准。
从 CC Switch 迁移
在 工作台 → 开放接入 → 从 CC Switch 迁移 中选择原来的 cc-switch.db 文件，只读预览后再导入需要的供应商。迁移的是供应商，不是整个账户；登录态、提示词、Skills 和用量脚本不在迁移范围内。已有用户升级时不需要删除 Key 或配置目录。
常见问题
点击“识别 Key”失败怎么办？
先检查 Key 是否完整、有没有多余空格、是否被禁用，再检查网络能否访问 hrouter.net。返回 401 的具体原因见 API 401 报错。
识别后没有模型？ 这个 Key 的分组没有对应工具所需的模型权限，或套餐尚未生效。到 API 密钥 页面核对分组，再重新识别。
保存后工具没有用新配置？ 关闭并重新打开终端，或重启对应工具。仍然无效见 配置不生效怎么排查。
想换一个套餐或另一个 Key？ 新增第二个 HRouter 配置，输入另一个 Key 即可，两个配置可以随时切换。
模型变了怎么办？ 编辑配置后重新点击“识别 Key”，再保存新的模型绑定。
Desktop 会替代控制台吗？ 不会。充值、订单、Key 管理仍在 hrouter.net 网页端，Desktop 只负责把工具接上。
隐私、签名和安全反馈见仓库中的 PRIVACY.md、CODE_SIGNING_POLICY.md 与 SECURITY.md，问题可以在 GitHub Issues 提交。