Cherry Studio API Gateway 不再自动启动：显式开关与 Agent 弹窗许可完整指南-酒店常州论坛

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.enabled`	`boolean`	`false`	是否随启动自动拉起 / 设置页开关（本次变更核心）
`feature.api_gateway.host`	`string`	`127.0.0.1`	绑定地址
`feature.api_gateway.port`	`number`	`23333`	TCP 端口（UI 限制 1000–65535）
`feature.api_gateway.api_key`	`string \\| null`	`null`	首次激活自动生成`cs-sk-<uuid>`

补一句容易踩的坑：enabled这个键只允许主进程在 start / stop 内部写入，渲染端不能回写——正是这种"第二次没等待的写入"曾造成持久化失败与运行态漂移。

你需要做什么 ✅

普通用户：什么都不用做，行为自动生效。

想彻底关闭 Gateway？进"设置 → API Gateway"关一次。和旧版不同，它会保持关闭，本地端口保持不监听。

Agent 用户（跑非 Anthropic 兼容原生服务模型的）：

首次遇到启用确认弹窗时，点接受即可，一次搞定；
接受后若 Gateway 启动失败（比如端口被占用），错误会如实呈现在 IPC 结果和运行状态里，不会被"静默复活"掩盖。

维护者 / Release 注意：在 Code 页把配置指向 Cherry Gateway 的外部 CLI 工具不受影响——选择该 provider 时仍会启用 Gateway，所以它依然会在启动时拉起。这是有意保留的行为：CLI 工具场景依赖 Gateway 常驻，属于"显式选择"而非"隐式自启动"。

企业官网建设流程全解析