Cherry Studio API Gateway 自动启动行为大改一文看懂显式开关、Agent 桥接弹窗与端口彻底关闭指南【免费下载链接】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-switchCherry Studio 的本地 API Gateway默认监听127.0.0.1:23333的本地 HTTP 网关把 OpenAI / Anthropic / Gemini 等协议的请求统一翻译成后端模型能力从有 Agent 就自动开机变成了只在设置 → API Gateway里手动打开才开机。对应的缺陷修复见 issue #18521 / PR #18523旧版里用户手动关闭后开关会被悄悄拨回关闭形同虚设现在关闭一次跨重启依然关闭本地端口随之保持关闭。 新旧行为逐项对照行为旧版修复前新版修复后启动时是否自动拉起只要存在任意 Agent 就自动开机完全取决于feature.api_gateway.enabled这个持久化开关默认关闭、不随 Agent 存在而变化手动关闭能否生效关闭只改运行时状态持久化意图被悄悄改回开下次启动端口又开了先写偏好、再停服务写失败会如实报错关闭状态跨重启保持Agent 需要网关时默默替你把网关开起来先弹确认框征求许可点启用才开机且持久化点拒绝则给出本地化错误文案 谁会受到影响普通用户不用 Agent 或只用 Anthropic 兼容端点原生模型什么都不用做如果之前被自动开机的行为困扰去设置里关一次即可这次会真正保持关闭。Agent 用户模型必须经网关桥接例如 Cherry 云模型首次发消息会看到一次启用确认弹窗接受后即恢复旧版体验且启用会被记住未来启动默认拉起之后仍可随时在设置里关闭。弹窗启用后不会自动补发刚才那条消息需要手动再发一次。在 Code 页配置了 Cherry Gateway 的外部 CLI 工具用户不受影响选择该 provider 本身就会启用网关它依然会在启动时拉起——这是有意保留的显式选择不是隐式自启动。 开关为什么这次关得住把旧实现想成一根被剪掉的电线你以为按了遥控器关闭按钮实际插座持久化的enabled偏好还插着电下次开机自然又通了。新实现做了两件事——意图先落库点开关时先把feature.api_gateway.enabled写入偏好存储成功后才去启停服务写入失败会直接抛错告诉你意图没生效而不是像旧版那样运行时停了、偏好却还是 true。收敛器是唯一闸门所有启停请求开关、重启、临时借用都汇入同一个协调器LatestReconciler。它比较期望状态和实际状态不一致才动作中途反复切换以最后一次意图为准不会出现两个操作者抢跑导致状态漂移端口被占用这类持续性失败只记录、不空转重试。核心代码只有这几行src/main/features/apiGateway/ApiGatewayService.ts 内的applyIntent路径仅作定位private async applyIntent(enabled: boolean): Promisevoid { await application.get(PreferenceService).set(feature.api_gateway.enabled, enabled) await this.converge(enabled) }另外还有一个临时借用机制PDF 翻译等瞬时功能会通过租约lease短暂借用网关借用期间服务在跑但绝不把enabled改回 true——用完即还你在借用中途关闭网关也不会切断正在跑的任务还完后协调器会自动把服务停掉。 Agent 弹窗的三步判定所有需要网关桥接的 Agent 路由都走同一条判定链位于 src/main/ai/runtime/agentApiGateway.ts顺序是许可 → 收敛 → 密钥许可检查的是持久化的enabled而不是现在是否在监听。因为网关在启动绑定中、重启中或激活失败后会短暂不监听若以运行态为准会给已经开启的用户反复弹请启用这种荒唐提示。enabled为 false 时抛出带 i18n 键的错误各运行时驱动Claude Code、Pi 等广播api_gateway.required事件界面据此弹出启用确认框。收敛已启用但没在跑时调用ensureRunning()。它和start()的关键区别是永不重新写偏好所以一条 Agent 路由不可能把你手动关掉的网关偷偷开回来。密钥前两步都通过后才生成/取用cs-sk-uuid密钥并持久化——失败的路由不会留下这个副作用。弹窗文案会明确告诉你该 Agent 的模型必须经本地 API Gateway 桥接启用后未来启动也会自动拉起之后可在设置中再次关闭。⚙️ 配置一览feature.api_gateway.* 命名空间偏好键类型默认值说明feature.api_gateway.enabledbooleanfalse显式开关本次变更核心只有主进程在 start/stop 内部写它渲染端不回写feature.api_gateway.hoststring127.0.0.1绑定地址feature.api_gateway.portnumber23333TCP 端口UI 限制 1000–65535feature.api_gateway.api_keystring | nullnull首次激活时自动生成cs-sk-uuidfeature.api_gateway.running共享缓存boolean—运行态只读镜像设置页据此在运行期间禁用端口/密钥编辑✅ 如何验证开关真的生效 常见坑验证方法设置页状态显示已停止且共享缓存中的运行态为 false用系统命令确认端口无人监听例如 macOS/Linux 执行lsof -i :23333或ss -lntp | grep 23333Windows 执行netstat -ano | findstr 23333应无输出重启应用后再查一次——这正是旧版会翻车的时刻现在应当保持关闭。常见坑弹窗为什么还会出现判定依据是持久化的enabled而非运行状态。如果你从未在弹窗里点过启用每次桥接类请求都会提示点一次启用即永久记住。端口被占用导致启动失败新版会把真实错误如实抛到调用方与运行状态里而不是静默复活掩盖问题释放端口后重试即可。接受弹窗后消息没反应这是预期行为启用流程不会补发消息手动再发一次。临时借用期间看到运行中PDF 翻译等功能持有租约时服务在跑是正常的且不会把开关拨回打开。 延伸阅读docs/references/api-gateway/README.mdHTTP 路由面、认证、适配器系统与关键不变量v2-refactor-temp/docs/breaking-changes/2026-08-13-api-gateway-never-autostarts.md本次变更的官方变更记录src/main/features/apiGateway/ApiGatewayService.ts偏好意图、租约与协调器的实现本体。【免费下载链接】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），仅供参考
