拓冰网站定制 
cc-switch 供应商编辑深度指南live 配置回填、图标自定义与 JSON 编辑实践【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switchcc-switch 的「编辑供应商」是日常使用频率最高的功能之一修改 API Key、切换端点地址、调整模型列表、更换图标都发生在这块全屏编辑面板里。本文基于官方用户手册的编辑章节结合 EditProviderDialog、IconPicker、JsonEditor 等前端源码完整拆解可编辑字段、「live 回填」同步机制、多端点管理与 JSON 编辑器的工作方式帮助你在改动配置时理解每一个保存动作背后实际发生了什么。打开编辑面板编辑入口位于供应商卡片上找到要编辑的供应商卡片鼠标悬停在卡片上显示操作按钮点击「编辑」按钮。点击后打开的是一个全屏面板。从源码看编辑对话框由 EditProviderDialog 实现它基于 FullScreenPanel 渲染内部复用与添加供应商完全相同的 ProviderForm 表单组件——这也意味着编辑时能用的功能模型下拉、通用配置快捷开关、端点管理与添加时一致。面板底部放置「保存」按钮其可用状态与表单的提交就绪状态isFormReady和提交中状态isFormSubmitting绑定防止重复提交。可编辑内容基本信息字段说明名称供应商显示名称备注附加说明信息网站链接供应商官网或控制台地址图标自定义图标和颜色提交时这些字段会经过轻量的规范化处理。查看 EditProviderDialog 的handleSubmit可以发现name会trim()而notes和websiteUrl在仅有空白字符时会被置为undefined即清空输入与留空效果等价不会把纯空格存进数据库。图标自定义CC Switch 提供丰富的图标自定义功能。图标选择器点击图标区域打开图标选择器使用搜索框按名称搜索图标点击选择想要的图标。图标库包含常见的 AI 服务商和技术图标支持按名称模糊搜索显示图标名称提示实时预览选中效果。从源码看选择器由 IconPicker 实现核心机制包括搜索过滤搜索框输入后调用searchIcons(searchQuery)对图标列表做模糊匹配图标元数据来自 icons/extracted 目录名称提示每个图标按钮的title使用getIconMetadata(iconName)中的displayName即悬停时能看到图标的可读名称而不是内部标识符选中态反馈被选中的图标会应用border-primary bg-primary/10高亮样式且按钮下方的名称文字提供实时预览无结果兜底搜索无匹配时显示未找到匹配的图标提示避免空白界面。图标值最终保存为字符串icon字段配合可选的iconColor用于配色。配置信息JSON 格式的配置内容包括API Key端点地址其他环境变量。编辑当前启用的供应商live 回填机制编辑当前启用的供应商时有特殊的「回填」机制打开编辑面板时会从 live 配置文件读取最新内容如果你在 CLI 工具中手动修改过配置这些修改会被同步回来保存后修改会写入 live 配置文件。这确保了 CC Switch 和 CLI 工具的配置始终同步。这一机制在 EditProviderDialog 中有完整实现值得细看几个设计决策仅对当前生效供应商读取 live打开面板时先通过providersApi.getCurrent(appId)查询当前启用的供应商 ID只有当编辑对象恰好是它时才调用vscodeApi.getLiveProviderSettings(appId)读取实时配置编辑非启用供应商时直接以数据库SSOT中的settingsConfig为初始值。只加载一次hasLoadedLive标记保证 live 配置只在首次打开时读取一次避免后续渲染用旧数据覆盖用户已在表单中做的编辑。读取失败静默回退live 读取抛错时回退到数据库配置SSOT不打断编辑流程。代理接管模式例外当代理proxy接管了配置写入时live 文件里是代理改写后的地址与占位符此时isProxyTakeover分支会跳过 live 读取、直接展示数据库配置避免用户在编辑界面看到代理地址后误保存源码注释见 EditProviderDialog。OpenCode / Pi 例外OpenCode 使用增量合并additive模式Pi 的共享models.json由目录协调器管理二者都没有每个供应商一份 live 快照的概念因此同样不读取 live 覆盖数据库聚合值。Codex modelCatalog 防丢失Codex 的modelCatalog是 cc-switch 的私有字段SSOT 在数据库而 live 的config.toml只在写入时投影出model_catalog_json指针。来回切换供应商或 Codex.app 改写配置都可能让 live 丢失该投影。因此源码强制以数据库的modelCatalog为准EditProviderDialog防止编辑界面显示空映射表 → 保存后连同数据库映射一起被清空的数据丢失问题。自动获取模型编辑供应商时可以自动从供应商端点获取可用模型列表确保已填写 API Key 和端点地址点击模型输入框旁的获取模型按钮下载图标从分组下拉菜单中选择模型。详细说明请参阅 2.1 添加供应商 — 自动获取模型。由于编辑面板复用ProviderForm模型获取、下拉选择与添加时的行为完全一致。通用配置快捷开关Claude编辑 Claude 供应商时JSON 编辑器上方提供常用设置的快捷开关包括工具搜索、禁用自动更新、Teammates、高效能模式等。详见 2.1 添加供应商 — Claude 通用配置快捷开关。修改 API Key编辑供应商时可以直接在API Key输入框中修改点击供应商卡片的「编辑」按钮在「API Key」输入框中输入新的密钥点击「保存」。提示API Key 输入框支持显示/隐藏切换点击右侧的眼睛图标可查看完整密钥。修改端点地址编辑供应商时可以直接在端点地址输入框中修改点击供应商卡片的「编辑」按钮在「端点地址」输入框中输入新的 URL点击「保存」。端点地址格式应用格式示例Claudehttps://api.example.comCodexhttps://api.example.com/v1Geminihttps://api.example.com注意 Claude 与 Codex 的差异Codex 的 base URL 需要带/v1路径后缀Claude 则是裸域名。填错路径是最常见的连通性问题来源之一保存前可借助表单的校验提示确认。添加自定义端点供应商可以配置多个端点用于速度测试时测试多个地址故障转移时的备用端点。自动收集添加供应商时CC Switch 会自动从配置中提取端点地址。手动添加编辑供应商时在「端点管理」区域可以添加新端点删除现有端点设置默认端点。从源码看多端点能力集中在表单层useSpeedTestEndpoints 管理端点集合与速度测试EndpointSpeedTest 负责并发探测各端点延迟CommonConfigEditor 提供端点编辑界面。这些组件在编辑面板中与添加面板共享保证两处体验一致。JSON 编辑器配置使用 JSON 格式编辑器提供语法高亮格式校验错误提示。常见错误缺少引号// ❌ 错误 { env: { KEY: value } } // ✅ 正确 { env: { KEY: value } }多余逗号// ❌ 错误 { env: { KEY: value, } } // ✅ 正确 { env: { KEY: value } }未闭合括号// ❌ 错误 { env: { KEY: value } // ✅ 正确 { env: { KEY: value } }从实现看JsonEditor 基于 CodeMirror 6 构建使用codemirror/lang-json提供 JSON 语言支持与语法高亮codemirror/lint的linter扩展实时解析文档内容并生成诊断diagnostics——包括 JSON 语法错误、以及顶层结构不是对象时的额外提示showValidation属性可关闭校验只读展示场景。编辑体验上它还实现了基于最长公共前后缀的最小差异更新与光标位置映射mapPositionByContext确保格式化重排时输入光标不跳位。保存与生效点击「保存」按钮如果表单检测到非阻塞问题会出现「先存上再说」确认提示确认后仍可保存如果是当前启用的供应商配置立即写入 live 文件重启 CLI 工具生效。第 2 步对应源码中的软校验soft validation表单在提交前检查必填项例如非官方供应商未填 API Key、未填端点发现问题时弹出标题为「配置存在以下问题」的确认框提示仍要保存吗保存后切换此供应商时可能失败可以之后再补全按钮文案为「仍要保存」——文案定义见 zh.json弹框触发点位于 ProviderForm。而 JSON 格式错误则属于硬校验configJsonError配置JSON格式错误请检查语法会直接阻断保存。保存成功后handleSubmit会关闭面板并通过onSubmit把新配置连同originalId原供应商 ID一起交给上层处理上层负责持久化到数据库必要时同步 live 文件。对于当前启用的供应商配置会立即写入 live 文件但注意 CLI 工具读取配置通常在进程启动时完成因此需要重启 CLI 工具如重启 Claude Code / Codex 会话才能让新配置生效。取消编辑点击「取消」或按Esc键关闭编辑面板所有修改都不会保存。从源码看取消路径经过closeDialog→onOpenChange(false)关闭全屏面板由于所有编辑都只发生在表单的受控状态中未经提交就不会写入数据库或 live 文件因此取消是完全无损的。另外源码对面板关闭做了细分若此时打开着托管账号Auth设置子面板handlePanelClose会先关闭子面板而不是整个编辑对话框避免误关导致编辑内容丢失。小结操作行为要点源码/文档依据打开编辑卡片悬停 →「编辑」全屏面板EditProviderDialog编辑启用供应商live 回填保持与 CLI 手动修改同步EditProviderDialog图标更换搜索、名称提示、选中高亮IconPicker配置编辑CodeMirror JSON 实时校验JsonEditor非阻塞问题「仍要保存」软校验确认ProviderForm保存生效启用供应商立即写 live重启 CLIdocs/user-manual/zh/2-providers/2.3-edit.md理解数据库 SSOT live 文件双向同步这条主线是正确使用编辑功能的关键数据库是配置的事实来源live 文件是 CLI 工具实际读取的产物编辑启用供应商时回填 live 是为了纳入你在 CLI 侧的手动修改而代理接管、OpenCode、Pi 等特殊应用形态各有明确的例外处理避免误读误写。【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 cc-switch 供应商编辑深度指南：live 配置回填、图标自定义与 JSON 编辑实践
cc-switch 供应商编辑深度指南live 配置回填、图标自定义与 JSON 编辑实践【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switchcc-switch 的「编辑供应商」是日常使用频率最高的功能之一修改 API Key、切换端点地址、调整模型列表、更换图标都发生在这块全屏编辑面板里。本文基于官方用户手册的编辑章节结合 EditProviderDialog、IconPicker、JsonEditor 等前端源码完整拆解可编辑字段、「live 回填」同步机制、多端点管理与 JSON 编辑器的工作方式帮助你在改动配置时理解每一个保存动作背后实际发生了什么。打开编辑面板编辑入口位于供应商卡片上找到要编辑的供应商卡片鼠标悬停在卡片上显示操作按钮点击「编辑」按钮。点击后打开的是一个全屏面板。从源码看编辑对话框由 EditProviderDialog 实现它基于 FullScreenPanel 渲染内部复用与添加供应商完全相同的 ProviderForm 表单组件——这也意味着编辑时能用的功能模型下拉、通用配置快捷开关、端点管理与添加时一致。面板底部放置「保存」按钮其可用状态与表单的提交就绪状态isFormReady和提交中状态isFormSubmitting绑定防止重复提交。可编辑内容基本信息字段说明名称供应商显示名称备注附加说明信息网站链接供应商官网或控制台地址图标自定义图标和颜色提交时这些字段会经过轻量的规范化处理。查看 EditProviderDialog 的handleSubmit可以发现name会trim()而notes和websiteUrl在仅有空白字符时会被置为undefined即清空输入与留空效果等价不会把纯空格存进数据库。图标自定义CC Switch 提供丰富的图标自定义功能。图标选择器点击图标区域打开图标选择器使用搜索框按名称搜索图标点击选择想要的图标。图标库包含常见的 AI 服务商和技术图标支持按名称模糊搜索显示图标名称提示实时预览选中效果。从源码看选择器由 IconPicker 实现核心机制包括搜索过滤搜索框输入后调用searchIcons(searchQuery)对图标列表做模糊匹配图标元数据来自 icons/extracted 目录名称提示每个图标按钮的title使用getIconMetadata(iconName)中的displayName即悬停时能看到图标的可读名称而不是内部标识符选中态反馈被选中的图标会应用border-primary bg-primary/10高亮样式且按钮下方的名称文字提供实时预览无结果兜底搜索无匹配时显示未找到匹配的图标提示避免空白界面。图标值最终保存为字符串icon字段配合可选的iconColor用于配色。配置信息JSON 格式的配置内容包括API Key端点地址其他环境变量。编辑当前启用的供应商live 回填机制编辑当前启用的供应商时有特殊的「回填」机制打开编辑面板时会从 live 配置文件读取最新内容如果你在 CLI 工具中手动修改过配置这些修改会被同步回来保存后修改会写入 live 配置文件。这确保了 CC Switch 和 CLI 工具的配置始终同步。这一机制在 EditProviderDialog 中有完整实现值得细看几个设计决策仅对当前生效供应商读取 live打开面板时先通过providersApi.getCurrent(appId)查询当前启用的供应商 ID只有当编辑对象恰好是它时才调用vscodeApi.getLiveProviderSettings(appId)读取实时配置编辑非启用供应商时直接以数据库SSOT中的settingsConfig为初始值。只加载一次hasLoadedLive标记保证 live 配置只在首次打开时读取一次避免后续渲染用旧数据覆盖用户已在表单中做的编辑。读取失败静默回退live 读取抛错时回退到数据库配置SSOT不打断编辑流程。代理接管模式例外当代理proxy接管了配置写入时live 文件里是代理改写后的地址与占位符此时isProxyTakeover分支会跳过 live 读取、直接展示数据库配置避免用户在编辑界面看到代理地址后误保存源码注释见 EditProviderDialog。OpenCode / Pi 例外OpenCode 使用增量合并additive模式Pi 的共享models.json由目录协调器管理二者都没有每个供应商一份 live 快照的概念因此同样不读取 live 覆盖数据库聚合值。Codex modelCatalog 防丢失Codex 的modelCatalog是 cc-switch 的私有字段SSOT 在数据库而 live 的config.toml只在写入时投影出model_catalog_json指针。来回切换供应商或 Codex.app 改写配置都可能让 live 丢失该投影。因此源码强制以数据库的modelCatalog为准EditProviderDialog防止编辑界面显示空映射表 → 保存后连同数据库映射一起被清空的数据丢失问题。自动获取模型编辑供应商时可以自动从供应商端点获取可用模型列表确保已填写 API Key 和端点地址点击模型输入框旁的获取模型按钮下载图标从分组下拉菜单中选择模型。详细说明请参阅 2.1 添加供应商 — 自动获取模型。由于编辑面板复用ProviderForm模型获取、下拉选择与添加时的行为完全一致。通用配置快捷开关Claude编辑 Claude 供应商时JSON 编辑器上方提供常用设置的快捷开关包括工具搜索、禁用自动更新、Teammates、高效能模式等。详见 2.1 添加供应商 — Claude 通用配置快捷开关。修改 API Key编辑供应商时可以直接在API Key输入框中修改点击供应商卡片的「编辑」按钮在「API Key」输入框中输入新的密钥点击「保存」。提示API Key 输入框支持显示/隐藏切换点击右侧的眼睛图标可查看完整密钥。修改端点地址编辑供应商时可以直接在端点地址输入框中修改点击供应商卡片的「编辑」按钮在「端点地址」输入框中输入新的 URL点击「保存」。端点地址格式应用格式示例Claudehttps://api.example.comCodexhttps://api.example.com/v1Geminihttps://api.example.com注意 Claude 与 Codex 的差异Codex 的 base URL 需要带/v1路径后缀Claude 则是裸域名。填错路径是最常见的连通性问题来源之一保存前可借助表单的校验提示确认。添加自定义端点供应商可以配置多个端点用于速度测试时测试多个地址故障转移时的备用端点。自动收集添加供应商时CC Switch 会自动从配置中提取端点地址。手动添加编辑供应商时在「端点管理」区域可以添加新端点删除现有端点设置默认端点。从源码看多端点能力集中在表单层useSpeedTestEndpoints 管理端点集合与速度测试EndpointSpeedTest 负责并发探测各端点延迟CommonConfigEditor 提供端点编辑界面。这些组件在编辑面板中与添加面板共享保证两处体验一致。JSON 编辑器配置使用 JSON 格式编辑器提供语法高亮格式校验错误提示。常见错误缺少引号// ❌ 错误 { env: { KEY: value } } // ✅ 正确 { env: { KEY: value } }多余逗号// ❌ 错误 { env: { KEY: value, } } // ✅ 正确 { env: { KEY: value } }未闭合括号// ❌ 错误 { env: { KEY: value } // ✅ 正确 { env: { KEY: value } }从实现看JsonEditor 基于 CodeMirror 6 构建使用codemirror/lang-json提供 JSON 语言支持与语法高亮codemirror/lint的linter扩展实时解析文档内容并生成诊断diagnostics——包括 JSON 语法错误、以及顶层结构不是对象时的额外提示showValidation属性可关闭校验只读展示场景。编辑体验上它还实现了基于最长公共前后缀的最小差异更新与光标位置映射mapPositionByContext确保格式化重排时输入光标不跳位。保存与生效点击「保存」按钮如果表单检测到非阻塞问题会出现「先存上再说」确认提示确认后仍可保存如果是当前启用的供应商配置立即写入 live 文件重启 CLI 工具生效。第 2 步对应源码中的软校验soft validation表单在提交前检查必填项例如非官方供应商未填 API Key、未填端点发现问题时弹出标题为「配置存在以下问题」的确认框提示仍要保存吗保存后切换此供应商时可能失败可以之后再补全按钮文案为「仍要保存」——文案定义见 zh.json弹框触发点位于 ProviderForm。而 JSON 格式错误则属于硬校验configJsonError配置JSON格式错误请检查语法会直接阻断保存。保存成功后handleSubmit会关闭面板并通过onSubmit把新配置连同originalId原供应商 ID一起交给上层处理上层负责持久化到数据库必要时同步 live 文件。对于当前启用的供应商配置会立即写入 live 文件但注意 CLI 工具读取配置通常在进程启动时完成因此需要重启 CLI 工具如重启 Claude Code / Codex 会话才能让新配置生效。取消编辑点击「取消」或按Esc键关闭编辑面板所有修改都不会保存。从源码看取消路径经过closeDialog→onOpenChange(false)关闭全屏面板由于所有编辑都只发生在表单的受控状态中未经提交就不会写入数据库或 live 文件因此取消是完全无损的。另外源码对面板关闭做了细分若此时打开着托管账号Auth设置子面板handlePanelClose会先关闭子面板而不是整个编辑对话框避免误关导致编辑内容丢失。小结操作行为要点源码/文档依据打开编辑卡片悬停 →「编辑」全屏面板EditProviderDialog编辑启用供应商live 回填保持与 CLI 手动修改同步EditProviderDialog图标更换搜索、名称提示、选中高亮IconPicker配置编辑CodeMirror JSON 实时校验JsonEditor非阻塞问题「仍要保存」软校验确认ProviderForm保存生效启用供应商立即写 live重启 CLIdocs/user-manual/zh/2-providers/2.3-edit.md理解数据库 SSOT live 文件双向同步这条主线是正确使用编辑功能的关键数据库是配置的事实来源live 文件是 CLI 工具实际读取的产物编辑启用供应商时回填 live 是为了纳入你在 CLI 侧的手动修改而代理接管、OpenCode、Pi 等特殊应用形态各有明确的例外处理避免误读误写。【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考