与 Claude Desktop 集成

本页介绍如何把 cc-router 接入 Claude Desktop，让 Claude Desktop 通过 cc-router 的 HTTPS 网关，调用你已经聚合好的 model-opus / model-sonnet / model-haiku 等虚拟模型。

前置要求

  • 已按 快速开始 安装并配置好 cc-router，至少绑定了一个虚拟模型
  • 已安装 Claude Desktop
  • 本指南以 本机回环（127.0.0.1） 为主示例。若 Claude Desktop 与 cc-router 不在同一台机器（局域网场景），请额外关注 §第二步 的「额外 SAN」和 §第五步 的 URL 写法

第一步：在 cc-router 启用 HTTPS

Claude Desktop 的第三方推理网关只接受 HTTPS 端点，所以先把 cc-router 的 HTTPS 接口打开。

打开 cc-router → 设置 → 代理服务 → 监听协议 选 仅 HTTPS 或 HTTP + HTTPS → 完整退出并重启 app（必须，不会热生效）。

HTTPS 端口默认 23457，被占用时自动 +1，以设置页底部的「实际监听端口」为准。

cc-router 设置中开启 HTTPS

第二步：导出 CA 证书

cc-router 用本地自签 CA 颁发 leaf 证书。要让 Claude Desktop 信任这个 HTTPS 接口，需要先把这张 CA 装到系统信任库。

进入 设置 → 滚到 HTTPS 证书 区域 → 点 导出 CA 证书… → 保存为 cc-router-ca.pem（可改后缀 .crt）。

核对指纹：上方显示的 「CA 证书指纹 (SHA-256)」 建议记一下，导入系统后再对一次，确保是同一张 CA。

局域网多机访问：如果 Claude Desktop 在另一台机器上访问本机 cc-router，请先在「额外 SAN」文本框里加入访问用的 IP 或 hostname（每行一条），失焦自动重签 leaf，然后重启 app；CA 不变，再继续导出。

cc-router 设置中导出 CA 证书

第三步：让系统信任这张 CA

macOS

双击 .pem 文件，「钥匙串访问」会弹出添加对话框，钥匙串选 系统，点 添加。

双击证书文件添加到钥匙串

系统会要求验证权限，使用触控 ID 或输入密码即可。

钥匙串访问请求权限

回到「钥匙串访问」，在 系统 钥匙串下找到 cc-router local CA，双击它。

在钥匙串里找到 cc-router local CA

展开 信任 折叠区，把 使用此证书时 改为 始终信任，关闭窗口时再输一次密码确认。

把证书设为始终信任

Windows

双击 .pem 或 .crt → 安装证书 → 选 本地计算机（需管理员）→ 将所有的证书放入下列存储 → 浏览到 受信任的根证书颁发机构 → 完成。

Linux

后缀必须是 .crt：

sudo cp cc-router-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Firefox / Chromium 使用自己的证书库，必要时还需在浏览器里单独导入。

第四步：在 Claude Desktop 启用开发者模式

打开 Claude Desktop → 顶部 Help 菜单 → Troubleshooting 子菜单 → 启用开发者模式相关选项（不同版本菜单项名称可能略有差异，以截图所示位置为准）→ 按提示重启 Claude Desktop。

重启后菜单栏会出现 Developer 菜单。

Help → Troubleshooting 启用开发者模式

第五步：配置第三方推理网关

启用开发者模式后通常会自动弹出 Configure Third-Party Inference 配置窗口；若没有自动弹出，从顶部 Developer 菜单选择 Configure Third-Party Inference… 手动打开。

在 Developer 菜单中打开配置窗口

在 Connection 标签页选择 Gateway (Anthropic-compatible)，然后填写以下字段：

  • Gateway base URL
    • 模板：https://<cc-router 所在机器 IP>:<HTTPS 端口>
    • 本机示例：https://127.0.0.1:23457
    • 局域网示例：https://192.168.x.x:23457（前提是该 IP 已在第二步加入「额外 SAN」并重新签发，对端机器也已导入同一张 CA）
    • 端口以 cc-router 设置页底部「实际监听端口」为准
  • Gateway API key：填 cc-router 设置页提供的 token
  • Gateway auth scheme：选 bearer

填完点右下角 Apply locally 保存。

配置 Gateway 网关

第六步：选择模型并验证

回到 Claude Desktop 主界面，在对话框的模型选择器里就能看到 anthropic/claude-opus-4-7、anthropic/claude-sonnet-4-6、anthropic/claude-haiku-4-5 等条目 —— 它们都会经由 cc-router 路由到你绑定的真实模型。任选其一发起对话即可。

Claude Desktop 模型选择器中能选到 cc-router 提供的模型

在 cc-router 主界面 请求日志 页可以实时看到来自 Claude Desktop 的请求被路由到哪个真实 provider。

排错

  • unable to verify the first certificate / self-signed cert —— CA 没装好，或装到了错误平台位置，重做第三步。macOS 注意把证书添加到「系统」而不是「登录」钥匙串。
  • connection refused —— cc-router 没启动、HTTPS 未开启、端口被改、防火墙拦截。检查 cc-router 设置页底部「实际监听端口」，并把这个值同步到 Gateway base URL。
  • Hostname/IP doesn't match certificate —— Gateway base URL 里的 IP 或 hostname 不在证书 SAN 列表里。回到 cc-router 设置页把它加进「额外 SAN」，重新生成证书（CA 不变），重启 app；其他机器无需重新导入 CA。
  • 401 Unauthorized —— cc-router 的 token 可能轮换过了，重新从设置页复制 Gateway API key。

安全提示

  • Gateway API key 是访问凭据，等同于直接调用你的所有上游 provider，勿外泄。
  • 仅在受信任的局域网中暴露 cc-router 端口；公网暴露需自行评估风险，并配合反向代理 + 鉴权层加固。