Cherry Studio 升级指南API Gateway 不再自动启动完整解析【免费下载链接】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从该版本起Cherry Studio 的 API Gateway本地 HTTP 网关为 OpenAI / Anthropic / Gemini 等协议客户端提供统一入口不再自动启动只有你在设置页显式开启它才会监听端口关掉则保持关闭。本文以仓库变更记录v2-refactor-temp/docs/breaking-changes/2026-08-13-api-gateway-never-autostarts.md为骨架对照主进程服务src/main/features/apiGateway/ApiGatewayService.ts、Agent 运行时桥接src/main/ai/runtime/agentApiGateway.ts、渲染端钩子src/renderer/hooks/useApiGateway.ts与配套测试契约带你掌握受影响者要做什么、旧行为关了又开的根因以及新机制如何保证关闭即持久。一分钟看懂核心结论一句话网关启停的决策权从是否存在 Agent转移到了持久化enabled偏好preference写入磁盘、跨重启仍生效的配置项上。维度旧行为新行为开关语义关闭后被偷偷重新打开实际不生效关闭即持久关闭后保持关闭本地端口保持关闭重启行为只要存在任意 Agent启动时自动拉起仅当enabled偏好为 true 时拉起与 Agent 数量无关Agent 遇到 Gateway 不可用静默启动 Gateway 继续请求先弹窗征求是否启用接受一次即恢复旧行为并持久化一句话概括状态切换开关语义关了又开 → 关闭即持久启动判定Agent 是否存在 →enabled偏好。谁会被影响三类用户中只有 Agent 用户可能被弹窗打扰一次其余两类基本无感。普通用户什么都不用做。升级后网关行为完全由设置 → API Gateway页的开关决定想让本地 23333 端口保持关闭关一次即可重启也不会再被拉起。Agent 用户仅当模型必须经网关桥接时受影响。目前的判定口径是provider 为 Cherry 云时本地 Gateway 必须作为协议翻译层agentApiGateway.ts。首次运行这类 Agent 会看到启用确认弹窗接受一次即恢复旧体验且该启用意图被持久化。在 Code 页把外部 CLI 工具配置为 Cherry Gateway 的用户不受影响。选择该 provider 仍会启用 Gateway启动时照常拉起CLI 场景依赖网关常驻属于显式选择而非隐式自启动。旧行为为什么不可靠根因是运行时状态与持久化意图的脱节用户关闭的只是内存里的运行态磁盘上的意图被悄悄改回。缺陷启动时是否拉起网关由是否存在 Agent决定用户执行关闭只改变了运行时状态持久化的enabled意图被静默改回true。可观察现象设置页关闭后服务短暂停止下次重启端口照常打开源码注释将持久化意图从未落库的运行时转换明确标记为 issue #18521 的根源ApiGatewayService.ts。后果若偏好写入失败enabled: true残留下一次启动端口被重新打开——关闭这个操作在该版本前从来不会真正生效。本变更在 PR #18523 中修复。新机制的三个核心设计新机制围绕三条原则组织唯一意图来源、唯一启停入口、租约与意图隔离。收敛reconcile比较期望状态与实际状态只做缺失的启停动作使两者最终一致。设计一唯一意图来源——enabled偏好即期望状态持久化enabled偏好是期望状态的单一事实来源启动时网关是否运行只取决于它。// onInit订阅偏好变化任何修改都会触发收敛 application.get(PreferenceService).subscribeChange(feature.api_gateway.enabled, (enabled) { this.desiredEnabled enabled this.reconciler.request() }) // onReady启动时读取持久化意图并收敛到实际运行状态 const config this.getCurrentConfig() this.desiredEnabled config.enabled this.reconciler.request() await this.reconciler.flush()这段代码说明偏好变化与应用启动两条路径汇入同一个收敛动作运行时没有资格反向改写意图ApiGatewayService.ts。与之配套的是applyIntent意图先落库再收敛——先写偏好再驱动服务private async applyIntent(enabled: boolean): Promisevoid { await application.get(PreferenceService).set(feature.api_gateway.enabled, enabled) await this.converge(enabled) // 收敛到目标状态 }这段代码把写入失败暴露给调用方偏好没写进去时立即报意图未生效避免运行时停了、偏好却还是 true的旧式漂移ApiGatewayService.ts。边界场景stop()仍可能返回deferred——若存在临时租约持有意图已清除但服务暂不停止ApiGatewayService.ts。设计二唯一启停入口——LatestReconciler 的收敛语义所有启停只经过内部的LatestReconciler它是对activate/deactivate的唯一调用方语义为level-triggered电平触发以实际isActivated为基准期望与实际不一致才动作、latest-wins过渡中途反向切换时遵从最新意图两个操作者不并发竞争、失败不空转端口占用这类持续失败的转换被记录且不重试避免死循环打日志。运行状态不经 IPC 拉取publishRunningState()把布尔值feature.api_gateway.running写入共享缓存Shared Cache主进程与渲染进程之间的只读订阅通道主进程是权威方渲染端只读订阅ApiGatewayService.ts、useApiGateway.ts。反例若存在第二个启停路径或拉取状态IPC#18521 的漂移就会原样回归。设计三临时租约与持久意图隔离租约lease消费者临时借用服务运行期的许可用完即还不改动用户设置。acquireLease()/releaseLease()只增减leaseCount抬高有效运行目标desiredEnabled || leaseCount 0绝不改写desiredEnabledApiGatewayService.ts。由此得到三条边界行为用户中途关闭不会切断正在运行的租约持有者租约释放后若enabled为 false协调器自动停服租约期间拒绝restart()避免重启打断瞬时任务。运行状态会如实反映租约期间服务在监听的事实设置页据此在运行期间禁用端口/密钥编辑。Agent 会话的完整时序所有需要网关的 Agent 运行时都走许可 → 收敛 → 密钥的固定序列入口是resolveApiGatewayRuntime(sessionId)agentApiGateway.ts。许可检查查持久化意图检查对象是持久化的enabled而非isRunning()。原因是网关在启动绑定、重启或激活失败后会短暂不在监听若以运行态为准会对已启用的用户反复弹请启用的提示agentApiGateway.ts。enabled为 false 时抛出ApiGatewayNotRunningError它携带 i18n 键可在回合错误块中渲染本地化文案agentApiGateway.ts——用户侧表现为一次回合报错而非崩溃。弹窗许可模型必须桥接而用户保持禁用时各运行时驱动Claude Code、DSh、Pi 等广播携带sessionId的api_gateway.required事件ClaudeCodeRuntimeDriver.ts、DshRuntimeConnection.ts、PiRuntimeConnection.ts渲染端弹出启用确认对话框。弹窗启用不会重发任何消息需在网关就绪后手动重发接受一次即持久化未来启动默认拉起除非再次在设置中关闭。收敛而非隐式启动已启用但未运行时调用ensureRunning()。与start()不同它绝不重新持久化意图无法复活用户已禁用的网关ApiGatewayService.ts。生成/取用密钥以上全部通过后才调用ensureValidApiKey()——首次使用生成cs-sk-uuid并持久化失败的路由不会留下这一副作用ApiGatewayService.ts。if (!config.enabled) throw new ApiGatewayNotRunningError()这一行是先问再启的分界线它检查持久化意图而非运行状态因此已启用用户不会被误判为未启用。配置项与调试速查网关配置集中在feature.api_gateway.*偏好命名空间由 v1 的redux/settings/apiServer.*经 v2 偏好迁移器迁入默认值来自getCurrentConfig()ApiGatewayService.ts、docs/references/api-gateway/README.md。偏好键类型默认值说明feature.api_gateway.enabledbooleanfalse随启动自动拉起 / 设置页开关本次变更核心feature.api_gateway.hoststring127.0.0.1绑定地址feature.api_gateway.portnumber23333TCP 端口UI 限制 1000–65535feature.api_gateway.api_keystring \| nullnull首次激活自动生成cs-sk-uuid调试建议端口占用导致启动失败协调器会记录失败且不重试失败不空转错误如实呈现在 IPC 结果与运行状态中不会被静默复活掩盖。查看实时运行状态渲染端经useSharedCacheValue(feature.api_gateway.running)只读订阅该版本没有拉取状态IPCuseApiGateway.ts。渲染端禁止回写enabled该键的写入只允许主进程在 start/stop 内部完成正是渲染端第二次未 await 的写入曾造成 #18521 的持久化失败与运行态漂移useApiGateway.ts。高频疑问用户侧的高频疑问大多来自持久意图与临时租约的边界。问我已关闭端口为什么还开着大概率仍有租约持有有效运行目标是desiredEnabled || leaseCount 0关闭操作不打断租约持有者租约释放且enabled为 false 后服务会自动停止ApiGatewayService.ts。问弹窗启用后为什么还要重发消息弹窗启用只负责许可 持久化不重发任何消息当前回合已在许可检查处失败需等网关就绪后手动重发。问租约会不会把enabled改成 true不会。租约仅通过leaseCount抬高有效运行目标绝不触碰desiredEnabled反映到持久层的是running运行状态设置页据此在运行期间禁用端口/密钥编辑。问为什么存在 Agent不再触发自动启动该版本中启动时网关是否运行只取决于enabled偏好Agent 存在与否不参与启动决策ApiGatewayService.ts。发布与回归发布侧唯一需要对外说明的是外部 CLI 工具不受影响——Code 页配置 Cherry Gateway 的选择仍会启用网关并随启动拉起这是有意保留的行为变更记录 Notes for release manager 一节明确说明且本次变更修复 issue #18521PR #18523。回归由四个测试文件各锁一条契约src/main/features/apiGateway/__tests__/ApiGatewayService.test.ts断言偏好启用时启动即拉起、命令与持久化意图必须同时落库——偏好写入失败时报告失败而非停止、启动成功后持久化意图被写入。src/main/features/apiGateway/__tests__/serverShutdown.test.ts活动 SSE/MCP 流下stop()必须及时返回且isRunning() false客户端不会被遗弃在无人服务的流上。src/main/ai/runtime/pi/PiRuntimeConnection.test.ts禁用网关时运行时正确广播api_gateway.required。src/main/ai/runtime/claudeCode/__tests__/agentSessionWarmup.test.ts许可流程只调用ensureRunning、绝不调用start——收敛不得重新持久化意图。相关入口变更记录v2-refactor-temp/docs/breaking-changes/2026-08-13-api-gateway-never-autostarts.md主进程服务src/main/features/apiGateway/ApiGatewayService.tsAgent 桥接src/main/ai/runtime/agentApiGateway.ts渲染端钩子src/renderer/hooks/useApiGateway.ts网关参考文档docs/references/api-gateway/README.md【免费下载链接】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），仅供参考