TokenNova星元API文档
配置指南

Claude Desktop + CC Switch

在 CC Switch 中管理 Claude Desktop 的供应商配置。

Claude Desktop 面板用于在 CC Switch 中管理 Claude Desktop 的供应商配置。开启后，你可以在 Claude Desktop 中使用第三方 Anthropic 兼容供应商，也可以为 DeepSeek、Kimi、DouBao、OpenAI、Gemini 等非 Claude 模型配置模型映射。

Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使用 ~/.claude/settings.json，Claude Desktop 使用自己的 3P profile 配置；在 CC Switch 中也会分别显示为 Claude Code 和 Claude Desktop。

支持范围

项目说明
支持系统macOS、Windows
暂不支持Linux 写入 Claude Desktop 3P 配置
生效方式切换供应商后需要重启 Claude Desktop
官方模式使用 Claude Desktop 内置登录，不需要 API Key 和接口地址
第三方模式写入 CC Switch 管理的 3P profile
MCP / SkillsClaude Desktop 3P profile 不走 CC Switch 的 MCP / Skills 同步

快速上手

第一步：切换到 Claude Desktop 面板

在左侧应用切换器中选择 Claude Desktop。

如果没有看到该入口，请到：

设置 -> 通用 -> 应用可见性

确认 Claude Desktop 没有被隐藏。

第二步：导入或添加供应商

如果你已经在 Claude Code 中配置过供应商，优先使用 将 Claude Code 中已有的供应商导入。这是迁移到 Claude Desktop 最省事的路径，可以省掉逐个重新填写接口地址、API Key 和默认模型的工作。

导入规则：

  • 已存在同 ID 供应商时不会覆盖
  • 能直连且模型名安全的 Claude Code 供应商会导入为直连模式
  • 需要模型转换的供应商会尝试导入为模型映射模式
  • ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 会转换为 Desktop 的 Sonnet / Opus / Haiku 映射
  • 旧的 1M 后缀会转换为 Claude Desktop profile 中的 supports1m 标记
  • 无法判断模型映射的供应商会被跳过

导入后请检查每个供应商的模型映射是否符合实际上游模型。尤其是 Kimi、DeepSeek、GLM、DouBao 这类非 Claude 模型，通常需要使用模型映射模式。

如果没有可导入的配置，或想单独给 Claude Desktop 添加一个供应商，可以点击右上角 + 按钮添加供应商。

你可以选择：

  • 预设供应商：从内置 Claude Desktop 预设中选择，只填写 API Key
  • 自定义供应商：手动填写名称、接口地址、API Key 和模型设置
  • Claude Desktop Official：恢复 Claude Desktop 官方登录模式

对于提供 Claude 系列模型的供应商，通常只需要：

  1. 选择预设或自定义供应商
  2. 填写 API Key
  3. 确认接口地址
  4. 保持 需要模型映射 关闭
  5. 点击 添加

第三步：切换并重启 Claude Desktop

在供应商卡片上点击 启用。

切换成功后：

  • 直连供应商：重启 Claude Desktop 后生效
  • 需要路由的供应商：保持 CC Switch 运行，开启 Claude Desktop 本地路由，然后重启 Claude Desktop

Claude Desktop 不会像 Claude Code 那样热重载配置。每次切换供应商后，都需要完全退出并重新打开 Claude Desktop。

两种工作模式

直连模式

直连模式适合供应商本身已经提供 Anthropic Messages API，并且能被 Claude Desktop 直接访问。

直连模式下，CC Switch 会把 Claude Desktop 的 3P profile 指向供应商接口：

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.example.com",
  "inferenceGatewayAuthScheme": "bearer",
  "inferenceGatewayApiKey": "你的 API Key"
}

适用场景：

  • 供应商暴露原生 Anthropic Messages API
  • 模型 ID 使用 claude-* 或 anthropic/claude-*
  • 不需要格式转换
  • 不需要 CC Switch 在使用期间保持本地路由

直连模式的 手动指定 Claude Desktop 模型列表 是高级选项。多数原生 Claude 模型供应商不需要填写，Claude Desktop 会自动读取 /v1/models。仅当供应商的 /v1/models 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。

模型映射模式

模型映射模式适合供应商提供的不是 Claude 系列模型，或者接口格式需要 CC Switch 转换的场景。

开启 需要模型映射 后，Claude Desktop 会连接到 CC Switch 本地网关：

http://127.0.0.1:15721/claude-desktop

CC Switch 会负责：

  1. 向 Claude Desktop 暴露安全的 Claude 模型路由
  2. 把 Desktop 选择的模型角色映射到真实上游模型
  3. 按供应商要求转换 Anthropic / OpenAI / Gemini 请求格式
  4. 使用 CC Switch 中保存的供应商凭据访问上游

支持的 API 格式：

  • Anthropic Messages：原生或兼容 Anthropic 请求
  • OpenAI Chat Completions：OpenAI 兼容 /chat/completions
  • OpenAI Responses API：OpenAI Responses 兼容接口
  • Gemini Native generateContent：Gemini 原生接口

模型映射模式下，Claude Desktop 只看到 claude-* 形式的模型；真实模型名不会直接写进 Claude Desktop profile。

配置模型映射

字段说明
模型角色Claude Desktop 可识别的 Sonnet / Opus / Haiku 路由
菜单显示名在 Claude Desktop 模型菜单里显示的名称
实际请求模型发送给上游供应商的真实模型 ID
1M向 Claude Desktop 声明该模型支持 1M 上下文

推荐写法：

场景模型角色菜单显示名实际请求模型1M
使用 KimiSonnetKimi K2kimi-k2不勾选
使用 DeepSeekSonnetDeepSeek V4 Prodeepseek-v4-pro勾选

这样做的原因是 Claude Desktop 会拒绝非 claude-* 模型，所以需要 CC Switch 的路由功能进行模型映射。

你可以同时配置 Sonnet、Opus、Haiku 三个角色：

  • Sonnet：默认主力模型
  • Opus：高质量或复杂任务模型
  • Haiku：快速、低成本模型

如果供应商只有一个模型，也可以只配置一个角色。模型映射模式至少需要一条有效映射。

本地路由开关

模型映射模式需要 CC Switch 本地路由参与请求转换。主页面的本地路由开关默认隐藏，需要路由功能时，请手动显示出来。

打开方式：

设置 -> 路由 -> 本地路由 -> 开启 在主页面显示本地路由开关

状态说明：

  • 开启：本地网关正在运行，地址通常是 127.0.0.1:15721
  • 关闭：直连供应商仍可使用；模型映射供应商无法正常工作
  • 正在加载：路由服务正在启动或停止

只有 需要模型映射 的供应商必须依赖本地路由。直连供应商不需要打开这个开关。

恢复官方 Claude Desktop

如果你想回到 Claude Desktop 官方登录：

  1. 选择 Claude Desktop Official
  2. 点击 启用
  3. 重启 Claude Desktop

CC Switch 会恢复 Claude Desktop 的官方 1P 模式，并移除 CC Switch 管理的 3P profile。官方模式不需要 API Key，也不需要本地路由。

从 Claude Code 导入供应商时，会自动添加一个 Claude Desktop Official。

配置文件位置

CC Switch 会写入 Claude Desktop 的 3P 配置目录。

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json
~/Library/Application Support/Claude-3p/claude_desktop_config.json
~/Library/Application Support/Claude-3p/configLibrary/_meta.json
~/Library/Application Support/Claude-3p/configLibrary/00000000-0000-4000-8000-000000157210.json

Windows：

%LOCALAPPDATA%\Claude\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\configLibrary\_meta.json
%LOCALAPPDATA%\Claude-3p\configLibrary\00000000-0000-4000-8000-000000157210.json

配置文件由 CC Switch 自动维护，不建议手动编辑。出现配置不一致时，重新启用当前供应商通常可以修复。

状态提示与处理

Claude Desktop 面板顶部可能出现 Claude Desktop 配置需要检查 提示。

提示处理
当前平台暂不支持目前仅 macOS / Windows 支持写入 3P 配置
profile 中存在非 claude-* 模型名重新切换当前供应商，或编辑供应商改用模型映射
启用了模型映射但没有有效路由编辑供应商，至少添加一条模型映射
本地路由 token 尚未生成重新切换该供应商，CC Switch 会写入新的本地 token
profile 指向的地址与当前供应商不一致重新切换当前供应商，让 profile 回到正确地址

常见问题

切换成功但 Claude Desktop 没变化？

请完全退出并重启 Claude Desktop。Claude Desktop 读取 3P profile 的时机通常在启动阶段，切换后不会自动热更新。

模型映射供应商请求失败？

检查：

  • CC Switch 是否仍在运行
  • Claude Desktop 本地路由是否已开启
  • 供应商 API Key 和接口地址是否正确
  • 模型映射中是否填写了实际请求模型
  • 切换供应商后是否重启了 Claude Desktop

Claude Desktop 模型菜单里看不到我的品牌模型名？

编辑供应商，在模型映射中填写 菜单显示名，然后重新启用供应商并重启 Claude Desktop。

直连模式下为什么报错？

直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 使用的 Claude 安全模型名。如果供应商使用 OpenAI、Gemini 或非 Claude 模型 ID，请开启 需要模型映射。

可以关闭 CC Switch 吗？

取决于模式：

  • 直连模式：Claude Desktop 重启并加载配置后，可以不保持本地路由运行
  • 模型映射模式：必须保持 CC Switch 运行，并保持 Claude Desktop 本地路由开启

是否会把真实上游模型名写入 Claude Desktop？

模型映射模式不会。Claude Desktop profile 中只保存安全的 claude-* 路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。

更多 CC Switch 指南参考

CC Switch 统一配置

用一套统一入口完成 Claude Code、Codex 等客户端的模型提供商配置。

ZCF

用 ZCF 快速写入 TokenNova 提供商配置、工作流和 MCP 服务。

On this page

支持范围快速上手第一步：切换到 Claude Desktop 面板第二步：导入或添加供应商第三步：切换并重启 Claude Desktop两种工作模式直连模式模型映射模式配置模型映射本地路由开关恢复官方 Claude Desktop配置文件位置状态提示与处理常见问题切换成功但 Claude Desktop 没变化？模型映射供应商请求失败？Claude Desktop 模型菜单里看不到我的品牌模型名？直连模式下为什么报错？可以关闭 CC Switch 吗？是否会把真实上游模型名写入 Claude Desktop？更多 CC Switch 指南参考