CC Switch 供应商编辑实战：JSON 配置、API Key、多端点管理与 Live 配置回填机制

本篇围绕 CC Switch 用户手册「Edit Provider」章节，完整讲解供应商编辑面板的每一项可编辑内容：基本信息与图标、JSON 配置、API Key 与 Endpoint URL 修改、多端点管理、JSON 编辑器校验，以及针对"当前生效供应商"的 live 配置回填机制。读完后可直接上手修改任意供应商配置，并理解 CC Switch 如何通过回填机制保证与 CLI 工具本地配置文件的双向同步。

打开编辑面板

1. 找到要编辑的供应商卡片；
2. 将鼠标悬停在卡片上，卡片会显现操作按钮；
3. 点击 Edit 按钮。

从源码看，供应商卡片组件 ProviderCard.tsx 接收 onEdit 回调，悬停时渲染的操作按钮区域由 ProviderActions.tsx 提供；编辑入口最终打开的是全屏编辑面板 EditProviderDialog.tsx，它内部复用与新建供应商相同的 ProviderForm 表单组件，因此新建与编辑拥有完全一致的字段、校验与保存逻辑。

可编辑内容

基本信息

字段	说明
Name	供应商显示名称
Notes	备注信息
Website Link	供应商官网或控制台 URL
Icon	自定义图标和颜色

这些字段在提交时会被逐一规范化处理：以 EditProviderDialog.tsx 中的 handleSubmit 为例，name 会去除首尾空白，notes、websiteUrl、icon、iconColor 在为空时统一收敛为 undefined，避免把无意义的空字符串写回数据库。

图标自定义

CC Switch 提供丰富的图标自定义能力：

图标选择器（Icon Picker）

1. 点击图标区域打开图标选择器；
2. 在搜索框中按名称搜索图标；
3. 点击选中目标图标。

图标库涵盖常见 AI 服务商与技术图标，支持：

• 按名称模糊搜索；
• 图标名称悬停提示（tooltips）；
• 选中图标的实时预览。

选择器由 IconPicker.tsx 实现，除内置图标库外，供应商卡片渲染图标时还会经过 providerIcon.ts 做解析与回退（例如未匹配到图标时的默认展示）。

配置

JSON 格式的配置内容，通常包含：

• API Key
• Endpoint URL
• 其他环境变量

不同应用（Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 等）对应不同的默认配置结构，表单内的默认值来自 opencodeFormUtils 中定义的 CLAUDE_DEFAULT_CONFIG、CODEX_DEFAULT_CONFIG、GEMINI_DEFAULT_CONFIG 等常量（见 ProviderForm.tsx 的导入）。各应用的完整配置格式可参考 2.1 Add Provider 的 "Custom Configuration" 小节。

编辑"当前生效供应商"时的回填（Backfill）机制

当编辑的恰好是当前正在生效的供应商时，CC Switch 会启用特殊的 live 配置回填机制：

1. 打开编辑面板时，会从实时配置文件（live configuration file）读取最新内容作为表单初始值；
2. 如果期间你手动用 CLI 工具修改过配置，这些改动会被同步回来；
3. 保存后，修改会立即写回实时配置文件。

这保证了 CC Switch 与 CLI 工具的配置始终一致。

从源码结构看，该机制集中在 EditProviderDialog.tsx 的加载逻辑中，有几个值得注意的实现细节：

• 只读一次：hasLoadedLive 标记确保 live 配置只在首次打开面板时加载一次，防止重复读取覆盖用户正在进行的编辑；
• 仅对当前生效供应商生效：代码先调用 providersApi.getCurrent(appId) 获取当前生效的供应商 ID，只有当 provider.id === currentId 时才去读取 live 配置，否则直接使用数据库中的配置；
• 代理接管模式例外：当 isProxyTakeover 为 true（本地代理已接管供应商配置）时，跳过 live 读取、回退到数据库配置，避免编辑界面展示被代理改写后的地址或占位符（见 EditProviderDialog.tsx）；
• OpenCode / Pi 例外：OpenCode 使用追加（additive）模式，Pi 的共享 models.json 由目录协调器管理，两者都没有"每供应商一份"的 live 快照，因此同样直接回退数据库配置（见 EditProviderDialog.tsx）；
• Codex 的 modelCatalog 特殊保护：Codex 的 modelCatalog 是 CC Switch 私有字段，SSOT（唯一事实来源）在数据库；live 的 config.toml 只在写入时投影出 model_catalog_json 指针，来回切换供应商可能导致 live 中该投影丢失。若放任 live 值覆盖，编辑界面会显示空映射表并在保存时连数据库中的映射一起清空。因此源码始终以数据库的 modelCatalog 为准，仅在数据库确实没有时才回退 live 反解结果（见 EditProviderDialog.tsx）。

自动获取模型列表

编辑供应商时，可以从供应商端点自动拉取可用模型列表：

1. 确认 API Key 与 endpoint URL 已填写；
2. 点击模型输入框旁的 Fetch Models 按钮（下载图标）；
3. 在分组下拉框中选择一个模型。

完整的拉取流程与端点适配规则参见 2.1 Add Provider — Auto-Fetch Models。

Claude 通用配置快捷开关

编辑 Claude 供应商时，JSON 编辑器上方提供针对常见设置的快捷开关，包括 Tool Search、Disable Auto Upgrade、Teammates、High Effort 等。这些开关会向 JSON 配置中注入/移除对应的配置片段，避免手工编辑出错。详细行为参见 2.1 Add Provider — Claude Common Config Toggles，前端实现位于 CommonConfigEditor.tsx。

修改 API Key

编辑供应商时，可以直接在 API Key 输入框中修改密钥：

1. 点击供应商卡片上的 Edit 按钮；
2. 在 API Key 输入框中填入新的密钥；
3. 点击 Save。

提示：API Key 输入框支持显示/隐藏切换，点击右侧的眼睛图标可查看完整密钥。该输入框由 ApiKeyInput.tsx 实现。

修改 Endpoint URL

编辑供应商时，可以直接在 Endpoint URL 输入框中修改地址：

1. 点击供应商卡片上的 Edit 按钮；
2. 在 Endpoint URL 输入框中填入新地址；
3. 点击 Save。

Endpoint URL 格式约定

应用	格式示例
Claude	https://api.example.com
Codex	https://api.example.com/v1
Gemini	https://api.example.com

注意 Claude 与 Gemini 通常填写根地址，而 Codex 需要在末尾带上 /v1 版本路径；填写错版本路径是代理请求 404 的常见原因之一。

添加自定义端点（多端点）

供应商可以配置多个端点，用于：

• 测速时测试多个地址；
• 作为故障转移（failover）的备用端点。

自动收集

新建供应商时，CC Switch 会自动从配置内容中提取 endpoint URL 并归入端点列表。

手动管理

编辑供应商时，在 Endpoint Management 区域可以：

• 添加新的端点；
• 删除已有端点；
• 设置默认端点。

端点列表还支持批量测速，相关组件为 EndpointSpeedTest.tsx，配合 2.1 Add Provider 中的 Endpoint Speed Test 小节使用。

JSON 编辑器

配置采用 JSON 格式，编辑器基于 CodeMirror 构建（见 JsonEditor.tsx），提供：

• 语法高亮（JSON / TOML 等语言由 language 属性切换）；
• 格式校验；
• 错误消息提示。

源码中 linter 的行为（JsonEditor.tsx）是：对非空文档执行 JSON.parse，解析失败时把 SyntaxError 信息作为诊断项标注在编辑器内；解析成功但顶层不是对象（例如是数组）时，会给出"必须为 JSON 对象"的专属错误提示。

常见错误

缺少引号：

// Wrong
{ env: { KEY: "value" } }

// Correct
{ "env": { "KEY": "value" } }

尾随逗号：

// Wrong
{ "env": { "KEY": "value", } }

// Correct
{ "env": { "KEY": "value" } }

括号未闭合：

// Wrong
{ "env": { "KEY": "value" }

// Correct
{ "env": { "KEY": "value" } }

保存与生效

1. 点击 Save 按钮；
2. 若表单检测到非阻断性问题，会出现 "save anyway" 确认提示，确认后仍会保存供应商；
3. 如果该供应商是当前生效供应商，配置会立即写入实时配置文件；
4. 重启 CLI 工具使改动生效。

保存链路的前后端交接如下：EditProviderDialog.tsx 中 handleSubmit 把表单返回的 settingsConfig 字符串 JSON.parse 成对象，组装为更新后的 Provider 并连同 originalId 一起提交；随后经 Tauri 命令层落到 Rust 后端的 update_provider 命令（见 provider.rs），由其负责更新数据库并在必要时重写对应应用的实时配置文件。表单中"save anyway" 确认弹窗由 ProviderForm.tsx 中的 ConfirmDialog 承载。

取消编辑

点击 Cancel 或按 Esc 键关闭编辑面板，所有未保存的修改将被丢弃。由于 live 配置只在面板打开时加载一次，取消操作不会产生任何副作用——数据库与实时配置文件均保持打开前的状态。

小结

场景	关键机制	源码依据
打开编辑面板	卡片悬停操作区 → 全屏表单	ProviderCard.tsx、EditProviderDialog.tsx
Live 配置回填	仅当前生效供应商读取 live，且只读一次	EditProviderDialog.tsx
代理接管/追加模式	回退数据库配置，避免展示代理改写内容	EditProviderDialog.tsx
JSON 校验	CodeMirror linter + 顶层必须为对象	JsonEditor.tsx
保存落盘	前端 parse 提交 → 后端 update_provider	provider.rs

掌握以上内容后，你就可以在 CC Switch 中安全地修改任意供应商的密钥、端点、模型与自定义配置，并理解其在代理接管、多端点测速与故障转移等进阶场景下的行为边界。