深入 OpenClaw Studio 架构服务器控制面、SQLite 投影存储与 WebSocket 适配器【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studioOpenClaw Studio 是 OpenClaw 的 Web 控制台连接 Gateway、管理智能体Agents、聊天、审批执行与配置定时任务一站完成。本文深入它的核心架构——服务器控制面server-owned control plane、SQLite 投影存储runtime.db与WebSocket 适配器Gateway 连接管理帮你理解消息如何不丢、连接如何自愈、刷新页面为何依然秒回。架构总览三层单向数据流OpenClaw Studio 已移除浏览器直连 Gateway 的旧方案生产运行时只保留三条路径详见 ARCHITECTURE.md层级路径说明浏览器 → Studio/api/runtime/*、/api/intents/*HTTP读取状态与执行意图操作浏览器 ← Studio/api/runtime/streamSSE实时事件流 断线回放Studio → Gateway一条服务器持有的 WebSocket由 Node 进程独占打开一句话心智模型浏览器只与 Studio 说话Studio 替浏览器保管 Gateway 连接。这也是为什么远程部署时ws://localhost:18789指的是Studio 所在主机上的 Gateway。服务器控制面进程内单例的中枢控制面运行时的核心是 runtime.ts 中的ControlPlaneRuntime它是进程级单例职责清晰事件扇出Gateway 事件经适配器回调进入handleDomainEvent()先落库再分发给所有订阅者runtime.ts#L106-L115网关调用边界所有请求都走callGateway()不允许前端绕过服务器直接调用runtime.ts#L94-L100快照读取snapshot()直接返回 SQLite 中的投影状态读取永远有数据新鲜度依据。浏览器侧的意图路由发送消息、创建 Agent、审批执行等全部收敛在/api/intents/*由 runtimeWriteTransport.ts 驱动保证写路径单一、可审计。SQLite 投影存储runtime.db 的三张表投影存储实现位于 projection-store.ts数据库文件位于~/.openclaw/openclaw-studio/runtime.db初始化时创建三张核心表projection-store.ts#L343-L368表作用runtime_projection单行投影连接状态、原因、数据截止时间as_ofoutbox有序事件日志outbox每行带自增id与agent_id索引是回放与历史分页的游标基准processed_events按事件键去重保证域事件幂等应用Gateway 重连重推也不会产生重复消息这套设计带来两个直接收益确定性回放SSE 携带Last-Event-ID时从该 id 向后补发没有时从 outbox 尾部回放最近窗口刷新页面和进程重启都不丢事件降级可读Gateway 不可用时读取路由可以基于投影数据返回带新鲜度元信息的降级响应见 degraded-read.ts。迁移策略遵循只做增量的护栏新增列、新增索引、提升user_version从不断裂历史数据。WebSocket 适配器Gateway 连接的管家适配器实现于 openclaw-adapter.ts由 Studio Node 进程持有唯一的上游 WebSocket负责四件事握手鉴权收到connect.challenge后以连接画像协议版本 3、tool-events能力声明发起connect请求画像构建逻辑在 gateway-connect-profile.ts超时保护8 秒内未收到连接响应即判定CONNECT_TIMEOUTopenclaw-adapter.ts#L320-L360自动重连断线后以 1 秒起步、最高 15 秒的退避策略指数退避重连并在连接画像中支持自动回退旧版 Control UI 握手方法白名单仅放行chat.send、agents.create、cron.add、exec.approval.resolve等显式列出的网关方法openclaw-adapter.ts#L28-L54请求一律经过这层关卡杜绝越权调用。Token 由服务器保管存于~/.openclaw/openclaw-studio/settings.json并在 API 响应中脱敏永远不会出现在浏览器里。SSE 回放刷新页面为何不丢消息事件出口是 stream/route.ts关键参数一目了然回放上限 2000 条REPLAY_LIMIT连接建立时先按Last-Event-ID补发再切换实时推送stream/route.ts#L5-L2515 秒心跳保持长连接存活避免代理层误判超时历史分页更早的消息走/api/runtime/agents/[agentId]/history用beforeOutboxId作排他游标向前翻页history/route.ts客户端通过useRuntimeSyncController将分页行灌入与实时 SSE 相同的事件管线按 outbox id 去重因此历史 实时天然无缝拼接。聊天事件的解析与渲染细节可继续参考 pi-chat-streaming.md权限与沙箱配置如何流入 Gateway 则见 permissions-sandboxing.md。关键文件速查模块文件职责控制面运行时src/lib/controlplane/runtime.ts单例、订阅扇出、网关调用边界投影存储src/lib/controlplane/projection-store.tsruntime.db读写、幂等落库、回放窗口WebSocket 适配器src/lib/controlplane/openclaw-adapter.ts握手、白名单、重连退避领域契约src/lib/controlplane/contracts.ts事件、outbox 条目、快照类型定义SSE 出口src/app/api/runtime/stream/route.ts回放 心跳 实时推送总览文档ARCHITECTURE.md边界划分、错误语义、护栏清单小结OpenClaw Studio 的架构可以浓缩为一句话连接在服务器事实在 SQLite浏览器只消费 HTTP SSE。服务器控制面让 Gateway 连接成为进程级单例SQLite outbox 让事件持久、幂等、可回放WebSocket 适配器让断线与重连完全自动化。理解这三块你就掌握了这个控制台消息不丢、状态可信、连接自愈的全部秘密也为二次开发新增意图路由、扩展投影字段找到了正确的落点。【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入 OpenClaw Studio 架构：服务器控制面、SQLite 投影存储与 WebSocket 适配器
深入 OpenClaw Studio 架构服务器控制面、SQLite 投影存储与 WebSocket 适配器【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studioOpenClaw Studio 是 OpenClaw 的 Web 控制台连接 Gateway、管理智能体Agents、聊天、审批执行与配置定时任务一站完成。本文深入它的核心架构——服务器控制面server-owned control plane、SQLite 投影存储runtime.db与WebSocket 适配器Gateway 连接管理帮你理解消息如何不丢、连接如何自愈、刷新页面为何依然秒回。架构总览三层单向数据流OpenClaw Studio 已移除浏览器直连 Gateway 的旧方案生产运行时只保留三条路径详见 ARCHITECTURE.md层级路径说明浏览器 → Studio/api/runtime/*、/api/intents/*HTTP读取状态与执行意图操作浏览器 ← Studio/api/runtime/streamSSE实时事件流 断线回放Studio → Gateway一条服务器持有的 WebSocket由 Node 进程独占打开一句话心智模型浏览器只与 Studio 说话Studio 替浏览器保管 Gateway 连接。这也是为什么远程部署时ws://localhost:18789指的是Studio 所在主机上的 Gateway。服务器控制面进程内单例的中枢控制面运行时的核心是 runtime.ts 中的ControlPlaneRuntime它是进程级单例职责清晰事件扇出Gateway 事件经适配器回调进入handleDomainEvent()先落库再分发给所有订阅者runtime.ts#L106-L115网关调用边界所有请求都走callGateway()不允许前端绕过服务器直接调用runtime.ts#L94-L100快照读取snapshot()直接返回 SQLite 中的投影状态读取永远有数据新鲜度依据。浏览器侧的意图路由发送消息、创建 Agent、审批执行等全部收敛在/api/intents/*由 runtimeWriteTransport.ts 驱动保证写路径单一、可审计。SQLite 投影存储runtime.db 的三张表投影存储实现位于 projection-store.ts数据库文件位于~/.openclaw/openclaw-studio/runtime.db初始化时创建三张核心表projection-store.ts#L343-L368表作用runtime_projection单行投影连接状态、原因、数据截止时间as_ofoutbox有序事件日志outbox每行带自增id与agent_id索引是回放与历史分页的游标基准processed_events按事件键去重保证域事件幂等应用Gateway 重连重推也不会产生重复消息这套设计带来两个直接收益确定性回放SSE 携带Last-Event-ID时从该 id 向后补发没有时从 outbox 尾部回放最近窗口刷新页面和进程重启都不丢事件降级可读Gateway 不可用时读取路由可以基于投影数据返回带新鲜度元信息的降级响应见 degraded-read.ts。迁移策略遵循只做增量的护栏新增列、新增索引、提升user_version从不断裂历史数据。WebSocket 适配器Gateway 连接的管家适配器实现于 openclaw-adapter.ts由 Studio Node 进程持有唯一的上游 WebSocket负责四件事握手鉴权收到connect.challenge后以连接画像协议版本 3、tool-events能力声明发起connect请求画像构建逻辑在 gateway-connect-profile.ts超时保护8 秒内未收到连接响应即判定CONNECT_TIMEOUTopenclaw-adapter.ts#L320-L360自动重连断线后以 1 秒起步、最高 15 秒的退避策略指数退避重连并在连接画像中支持自动回退旧版 Control UI 握手方法白名单仅放行chat.send、agents.create、cron.add、exec.approval.resolve等显式列出的网关方法openclaw-adapter.ts#L28-L54请求一律经过这层关卡杜绝越权调用。Token 由服务器保管存于~/.openclaw/openclaw-studio/settings.json并在 API 响应中脱敏永远不会出现在浏览器里。SSE 回放刷新页面为何不丢消息事件出口是 stream/route.ts关键参数一目了然回放上限 2000 条REPLAY_LIMIT连接建立时先按Last-Event-ID补发再切换实时推送stream/route.ts#L5-L2515 秒心跳保持长连接存活避免代理层误判超时历史分页更早的消息走/api/runtime/agents/[agentId]/history用beforeOutboxId作排他游标向前翻页history/route.ts客户端通过useRuntimeSyncController将分页行灌入与实时 SSE 相同的事件管线按 outbox id 去重因此历史 实时天然无缝拼接。聊天事件的解析与渲染细节可继续参考 pi-chat-streaming.md权限与沙箱配置如何流入 Gateway 则见 permissions-sandboxing.md。关键文件速查模块文件职责控制面运行时src/lib/controlplane/runtime.ts单例、订阅扇出、网关调用边界投影存储src/lib/controlplane/projection-store.tsruntime.db读写、幂等落库、回放窗口WebSocket 适配器src/lib/controlplane/openclaw-adapter.ts握手、白名单、重连退避领域契约src/lib/controlplane/contracts.ts事件、outbox 条目、快照类型定义SSE 出口src/app/api/runtime/stream/route.ts回放 心跳 实时推送总览文档ARCHITECTURE.md边界划分、错误语义、护栏清单小结OpenClaw Studio 的架构可以浓缩为一句话连接在服务器事实在 SQLite浏览器只消费 HTTP SSE。服务器控制面让 Gateway 连接成为进程级单例SQLite outbox 让事件持久、幂等、可回放WebSocket 适配器让断线与重连完全自动化。理解这三块你就掌握了这个控制台消息不丢、状态可信、连接自愈的全部秘密也为二次开发新增意图路由、扩展投影字段找到了正确的落点。【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考