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-switch如果你用 Cherry Studio 跑过 Agent最近可能会撞见一个陌生弹窗这个 Agent 的模型必须通过本地 API Gateway 桥接是否启用 这不是 bug而是一次行为变更的结果——Cherry Studio 的 API Gateway 不再自动启动改为由你在设置里显式开关。本文带你一次搞懂这次到底改了什么、为什么以前关不掉、新机制如何保证关了就是关了以及 Agent 用户遇到弹窗时该怎么处理。这次到底改了什么 过去Cherry Studio 的 API Gateway一个本地 HTTP 网关默认监听127.0.0.1:23333为 OpenAI / Anthropic / Gemini 等协议客户端提供统一入口有两个让人头大的毛病只要你系统里存在任意 Agent它就在每次启动时自行拉起更糟的是你手动关掉之后它会被偷偷重新打开——关闭这个操作从来不算数。这次变更把它掰直了两个关键变化关了就是关了。你在设置 → API Gateway里关掉后这个状态会跨重启保持本地端口保持关闭下次启动也不会自己复活。Agent 不再静默拉起。如果一个 Agent 的模型必须经 Gateway 桥接即不是由 Anthropic 兼容端点原生服务的运行时不会再默默启动 Gateway而是先弹窗问你是否启用你接受后恢复此前行为且这次启用的意图会被持久化下来。一句话以前 Gateway 是谁都能拉它、关了也白关现在是只有你点头它才动而且你说了算。下面这张图里带需要路由标记的条目就是那些必须经本地 API Gateway 桥接的模型。为什么以前会关不掉 讲人话以前的 Gateway 有两条信息线而且经常不同步运行时状态Gateway 此刻到底在不在跑。你点关闭停掉的只是这条线——服务确实不监听了。持久化意图intent记在设置里的那个enabled开关代表下次启动时你希望它开还是关。问题在于旧逻辑里存在任意 Agent会强行把持久化意图改回开。于是出现两种翻车现场关闭不生效。你关了运行时状态确实变成停但持久化意图被悄悄改回true。下次启动一看意图是开Gateway 又活了——你看到的关了又开就是这么来的。端口重新开放。某次关闭时持久化没写成功比如偏好写入出错true残留在设置里。下次启动端口就被重新打开而且这次连你关过的痕迹都没了。根子就一句话运行时状态和持久化意图脱节了谁说了算说不清楚。新机制怎么保证关了就是关了 ⚙️新设计把谁说了算定死了持久化的enabled偏好是期望状态的唯一来源。具体拆成三点意图先落库再动手。你点开或关系统先把这个意图写进设置写成功才去启动 / 停止服务。以前是先停服务、顺手改设置现在顺序反过来了。这样就算中途出错你也会立刻知道意图没生效而不会出现服务停了、设置还开着的漂移。只有一个启停管家。所有启动 / 停止都走同一个协调器LatestReconciler它的工作方式以实际状态为基准对比期望和实际不一样才动作最新的意图赢切换中途反复横跳下一轮会遵从最新意图不会出现两个操作互相打架导致状态漂移失败不空转持续失败的转换比如端口被占用会被记录且不再重试避免死循环刷日志。临时借用不算数。有些瞬时功能比如 PDF 翻译需要 Gateway 临时在跑但不能因此把enabled永久置开。为此引入了租约lease临时消费者申请一个租约租约计数抬高运行目标但绝不改写你的持久化意图。租约一释放只要enabled是关的协调器自动把服务停掉。所以有效运行目标其实是期望开启 || 有租约。换句话说租约期间你点关闭不会打断正在用的功能但租约一结束服务照旧关掉。运行状态则通过 Shared Cache 发布给界面——设置页会据此在服务运行期间禁用端口 / 密钥编辑防止你去改一个正在用的配置。想深挖实现可看src/main/features/apiGateway/ApiGatewayService.ts里的applyIntent与协调器逻辑以及src/main/core/concurrency/latestReconciler.ts的收敛语义。Agent 用户会遇到的弹窗 这是对你最直接的影响。先说清哪些模型会触发目前当 provider 属于 Cherry 云时模型必须由本地 Gateway 做翻译层因为它不是 Anthropic 兼容端点原生服务的。这类 Agent 会话会走一遍许可 → 收敛 → 密钥的流程先查持久化意图。如果enabled是关的直接抛Gateway 未运行错误不启动。注意这里查的是持久化意图而不是此刻是否在跑——因为 Gateway 可能在启动绑定、重启中或激活失败后短暂没在监听。若以是否在跑为准会对已经开了它的用户反复弹请启用的荒谬提示。已开但未跑就收敛而非隐式启动。此时调用ensureRunning()把服务拉起来。和start()不同ensureRunning()永远不会重新持久化意图所以它救不活你已经禁用的 Gateway。前三关都过了才生成 / 取用密钥。首次使用会生成一个cs-sk-uuid的密钥并持久化如果前面检查没通过就不会留下这个副作用。当Gateway 是关的、但模型又必须桥接时各运行时驱动会广播一个api_gateway.required事件带sessionId界面据此弹出启用确认对话框。文案大意是这个 Agent 的模型必须通过 Cherry Studio 的本地 API Gateway 桥接。启用它也会让 Gateway 在未来启动时自动拉起你之后可以在设置里再关掉。两个容易踩的点弹窗启用不会重发任何消息Gateway 就绪后你需要手动再发一次消息。启用即持久化接受一次后未来启动默认拉起除非你在设置里再关一次。配置项速查 Gateway 的配置都在feature.api_gateway.*偏好命名空间下从 v1 的redux/settings/apiServer.*经 v2 偏好迁移器迁过来偏好键类型默认值作用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补一句容易踩的坑enabled这个键只允许主进程在 start / stop 内部写入渲染端不能回写——正是这种第二次没等待的写入曾造成持久化失败与运行态漂移。你需要做什么 ✅普通用户什么都不用做行为自动生效。想彻底关闭 Gateway进设置 → API Gateway关一次。和旧版不同它会保持关闭本地端口保持不监听。Agent 用户跑非 Anthropic 兼容原生服务模型的首次遇到启用确认弹窗时点接受即可一次搞定接受后若 Gateway 启动失败比如端口被占用错误会如实呈现在 IPC 结果和运行状态里不会被静默复活掩盖。维护者 / Release 注意在 Code 页把配置指向 Cherry Gateway 的外部 CLI 工具不受影响——选择该 provider 时仍会启用 Gateway所以它依然会在启动时拉起。这是有意保留的行为CLI 工具场景依赖 Gateway 常驻属于显式选择而非隐式自启动。延伸阅读 API Gateway 参考文档HTTP 路由面、认证、请求流转、适配器系统与关键不变量docs/references/api-gateway/README.md。Agent 运行时桥接requiresAgentGateway、resolveApiGatewayRuntime与ApiGatewayNotRunningErrorsrc/main/ai/runtime/agentApiGateway.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），仅供参考