新闻详情

新闻详情

首页 / 资讯中心 / 详情

ClawX 后端通信架构收敛:移除渲染进程 Host API 服务器与 Gateway 直连传输,统一为类型化 Electron IPC

发布时间:2026/11/18 10:01:47来源:尧图网络
ClawX 后端通信架构收敛:移除渲染进程 Host API 服务器与 Gateway 直连传输,统一为类型化 Electron IPC
人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载本篇文章以 ClawX 仓库中的运行时桥接任务规格remove-host-api-server-and-renderer-gateway-transports为骨架系统梳理 ClawX 桌面端后端通信的最终形态渲染进程Renderer不再启动本地 Host API HTTP 服务器、不再直连 OpenClaw Gateway 的 WebSocket/HTTP 端口而是统一走类型化 Electron IPChost:invoke由 Electron 主进程Main独占持有 OpenClaw Gateway WebSocket。读完本文你将掌握 ClawX 后端通信的边界规则、hostApi门面的工作原理、Gateway 帧诊断方法CLAWX_GATEWAY_WS_TRACE1以及守护这一架构的验收测试与质量门禁。为什么需要移除这两条传输通道ClawX 是一个把 OpenClaw AI AgentCLI 编排搬进桌面的图形客户端其核心场景是不用终端也能编排 Agent。早期版本为了让渲染进程React UI拿到后端能力曾引入两条旁路本地 Host API HTTP 服务器渲染进程通过浏览器fetch直连http://127.0.0.1:13210获取后端数据并提供浏览器环境下的回退通道渲染进程直连 Gateway 传输渲染进程自行建立指向 OpenClaw Gateway 的 WebSocketws://127.0.0.1:18789一类地址或 HTTP 代理通道绕过主进程直接做 RPC 与事件订阅。这两条路径带来的问题是传输选择、重试策略、协议回退散落在渲染进程各处HTTP 端口与 WebSocket 端口的暴露面变大且 Gateway 帧诊断职责不清晰。本任务的核心意图intent写得很明确把后端通信折叠为渲染进程中的类型化 Electron IPC同时把 OpenClaw Gateway WebSocket 的所有权保留在 Electron Main。对应的场景文档见 gateway-backend-communication.md。移除之后整个 ClawX 唯一被允许的后端数据流是Renderer page/component - src/lib/host-api.ts类型化门面 - Electron Main typed host service / IPC handlerhost:invoke - Main-owned OpenClaw Gateway WebSocket - runtime result - store / UI这条允许流在场景文档中被明确固定渲染进程代码不得拥有传输选择、直接 IPC 通道、直接 Gateway HTTP 调用、重试策略或协议回退渲染进程也不得创建直连 Gateway 的 WebSocketGateway 帧诊断必须由主进程 Gateway 日志产出。支柱一类型化 Host API 门面hostApi facade host:invoke渲染进程唯一的后端入口移除本地 Host API 服务器后渲染进程访问后端数据的唯一入口是hostApi.module.action()门面实现在 src/lib/host-api.ts。这个门面按业务模块组织appopenClawDoctoropenclawstatus、getConfigPath、getSkillsDir、getCliCommand、getCompactionReserveshell/dialog/window/updates/uv系统级能力settingsgetAll、get、set、setMany、resetgatewaystatus、start、stop、restart、health、controlUi、rpclogs/channels/agents/diagnostics/providers/files/media/sessions/chat/cron/skills/usage/asr例如设置项读写与 Gateway 泛型 RPC// settings hostApi.settings.getAll() hostApi.settings.set(theme, dark) hostApi.settings.setMany({ theme: dark }) // gateway 泛型 RPCmethod 字符串 可选超时 hostApi.gateway.rpcunknown(sessions.list, { limit: 10 }, 500)注意gateway.rpc是刻意保留的类型逃生舱动态 Gateway 方法无法静态枚举因此它接受字符串方法名并允许调用方泛型化返回类型除此之外的所有 hostApi 方法输入与返回类型都来自共享契约。invokeHost把门面调用翻译成 IPC 请求每个门面方法最终都调用 src/lib/host-api-client.ts 中的invokeHost(module, action, payload)。其核心逻辑是通过crypto.randomUUID()生成请求id构造TypedHostRequestM, A{ id, module, action, payload? }调用 preload 桥暴露的window.clawx?.hostInvoke即 electron/preload/index.ts 中的hostInvoke: (request) ipcRenderer.invoke(host:invoke, request)解析HostResponseok: true时返回data否则抛出response.error.message。HostResponse与TypedHostRequest的类型定义见 shared/host-api/types.ts请求失败时统一携带{ code, message, details? }。Main 侧的分发器主进程在 electron/main/ipc/host-invoke.ts 注册ipcMain.handle(host:invoke, ...)。分发器把 IPC 输入当作不可信数据格式非法不是合法HostRequest→ 返回VALIDATION错误registry.resolve(module, action)找不到处理函数 → 返回UNSUPPORTED错误Unsupported host request: module.action执行期间抛错 → 返回INTERNAL错误并把异常消息透出。全链路共享同一份函数形状契约任务规格还配套了类型收紧任务 tighten-host-api-contract-types.md它把散落的unknown类型替换为函数形状的HostApiContract由渲染端门面、preload 桥和 Main 的 host service 注册表三方共享定义在 shared/host-api/contract.ts。例如export type HostApiContract { settings: { getAll: () SettingsSnapshot; get: (payload: SettingsGetPayload) SettingsValue; set: (payload: SettingsSetPayload) HostSuccess; setMany: (payload: SettingsSetManyPayload) HostSuccess; reset: () SettingsResetResult; }; gateway: { status: () GatewayStatus; start: () HostSuccess; rpc: (payload: GatewayRpcPayload) unknown; // ... }; // ... };配套类型助手HostApiModule、HostApiAction、HostApiPayload、HostApiResult、HostApiPayloadArgs在 contract.ts 中定义invokeHost据此推断载荷与结果类型gateway.rpc保留泛型出口。这样一来渲染进程无法再通过路径字符串 fetch访问后端也绕过了旧{ input, output }描述符的脆弱性。支柱二Gateway 传输所有权收归 Electron Main渲染进程彻底不再构造 Gateway 传输api-client-transport-policy规则api-client-transport-policy.md规定Gateway RPC 传输仅限 IPC渲染进程不得启用面向 OpenClaw Gateway 的 WebSocket 或 HTTP 传输渲染进程只能通过类型化 host-api 或遗留 IPC 包装调用 MainMain 独占 Gateway WebSocket。backend-communication-boundary规则backend-communication-boundary.md进一步把禁止面写死渲染进程后端调用必须走src/lib/host-api.ts页面与组件不得新增window.electron.ipcRenderer.invoke(...)直连调用渲染进程不得调用 Gateway HTTP 端点包括127.0.0.1:18789与localhost:18789渲染进程不得实现WS - HTTP - IPC的协议切换新后端接口必须先经 Electron Main 或 host API 层暴露渲染进程才能消费。场景文档 gateway-backend-communication.md 的forbiddenPatterns把上述禁令翻译成可机检的正则例如fetch(http://127.0.0.1:18789 ...、new WebSocket(ws://127.0.0.1:18789 ...出现在src/**即违规。Main 侧 Gateway 服务与 WebSocket 客户端渲染进程通过hostApi.gateway.*触达主进程的 Gateway 管理。服务实现位于 electron/services/gateway-api.tsstatus / start / stop / restart直接委托GatewayManagerhealth({ probe })转调gatewayManager.checkHealthcontrolUi依据保存的gatewayToken与端口构造 OpenClaw Control UI 地址并触发本地设备授权自动放行rpc是泛型 Gateway RPC 的唯一入口方法名必须是字符串并去空白超时必须是正有限数值parseTimeoutMs拒绝非有限或 ≤0 的值随后委托GatewayManager.rpc。真正的 WebSocket 连接由主进程持有实现在 electron/gateway/ws-client.ts。其中定义了GATEWAY_CHALLENGE_TIMEOUT_MS 10_000与GATEWAY_CONNECT_HANDSHAKE_TIMEOUT_MS 20_000它还包含设备握手buildDeviceAuthPayload、signDevicePayload与就绪探测probeGatewayReady探活用短生命周期 WebSocket 并以terminate()快速关闭避免 Windows 上残留 TIME_WAIT。这条路径没有任何渲染进程的 Chat 历史/发送特化、轮询队列、合并或背压层——它在 gateway-api.ts 处完成校验后直接进GatewayManager.rpc。支柱三主机事件订阅全部走类型化 IPC 映射事件侧同样收敛。渲染进程的事件订阅统一封装在 src/lib/host-events.tshostEvents提供Gateway 事件onGatewayStatus、onGatewayMessage、onGatewayError、onGatewayNotification、onGatewayHealth、onGatewayPresence、onGatewayChatMessage、onGatewayChannelStatus、onGatewayExitChat 事件onChatRuntimeEvent、onAcpSessionUpdate、onAcpPermissionRequestOAuth 事件onOAuthCode、onOAuthSuccess、onOAuthError渠道动态事件onChannelQr、onChannelSuccess、onChannelError按渠道名动态拼接通道名更新与应用事件onUpdateStatusChanged、onUpdateAutoInstallCountdown、onNavigate、onNewChat、onOpenClawCliInstalled。每个订阅器都通过onIpc走window.electron?.ipcRenderer.on(...)通道名来自共享常量表 shared/host-events/contract.tsHOST_EVENT_CHANNELS例如gateway:status-changed、chat:runtime-event、oauth:code、channel:name-qr等。host-events-fallback-policy规则host-events-fallback-policy.md明确主机事件订阅默认使用 IPC 映射未知主机事件不得回退到 SSE/EventSource新增的、用户可见的 gateway、channel、OAuth、QR 事件应当补充到 IPC 映射而不是依赖 EventSource 兜底。安全细节在 preload 侧事件通道白名单由静态通道集合 动态正则^channel:[a-z0-9_-]-(?:qr|success|error)$ext:前缀构成electron/preload/index.ts。IPCinvoke通道也维持显式允许列表未登记的通道如旧channel:saveConfig、chat:sendWithMedia、clawhub:search等已被从主进程注册与 preload 白名单中清除由测试守护见下。支柱四Gateway WebSocket 帧诊断CLAWX_GATEWAY_WS_TRACE1既然渲染进程不再直连 Gateway帧级诊断的职责就落在主进程日志上。主进程 WebSocket 客户端在连接/收帧时检查环境变量开关实现在 electron/gateway/ws-trace.tsexport function isGatewayWsTraceEnabled(): boolean { return process.env.CLAWX_GATEWAY_WS_TRACE 1; }trace 开启后见 ws-client.ts连接握手载荷与每条入站消息都会输出两条字段summary由summarizeGatewayFrameForTrace生成例如req id... method...、res id... ok...、event event、jsonrpc method...ws-trace.tsframe由redactGatewayFrameForTrace递归脱敏后的完整帧ws-trace.ts。脱敏规则值得注意名为token、authorization、apikey、api_key、signature、cookie、set-cookie、accesstoken、refreshtoken的键一律替换为[redacted]对config.set、config.patch、config.apply这类配置写入方法其params.raw会被整体替换为[redacted]避免把完整 OpenClaw 配置写进日志。开发者文档 docs/zh-CN/development.md 也给出使用前提除非正在测量 WebSocket trace 本身否则不要设置CLAWX_GATEWAY_WS_TRACE它默认关闭。对应的单测见 tests/unit/gateway-ws-trace.test.ts覆盖认证与设备密钥脱敏配置写入载荷脱敏请求/事件帧摘要三类行为。验收标准与守护测试任务规格的acceptance块给出了可审计的完成态且当前仓库源码可以逐条印证生产源码不再引用遗留 Host API fetch/token IPC 名称、Gateway HTTP 代理通道、本地 Host API 服务器启动、Host event bus、渲染进程 Gateway WS 诊断开关——旧electron/api目录与本地 Host API 路由测试已不在仓库electron/下现无api目录src/lib/api-client.ts为 IPC-only 且不构造 WebSocket/HTTP Gateway 传输——当前仓库中该遗留统一 API 客户端已被移除其不得复活由测试守护src/lib/host-api.ts只暴露类型化hostApi门面方法不导出基于路径的 fetch 助手——见 host-api.tssrc/lib/host-events.ts通过类型化 IPC 事件订阅不回退 SSE/EventSource——见 host-events.tsREADME.md、README.zh-CN.md、README.ja-JP.md 描述类型化 IPC 与 Main-owned Gateway WebSocket 所有权对应docs-sync规则。守护这些不变量的是 tests/unit/host-api-facade.test.ts 中的一批扫描型测试它们用fs递归读取源码做断言例如扫描src/**不允许出现hostApi.module.actionT形式的调用点泛型gateway.rpc除外扫描electron/**与src/**禁止跨边界 importelectron不得引用src/src不得引用electron/检查electron/main/ipc-handlers.ts与 preload 白名单中不再注册 hostApi 已覆盖的遗留通道channel:saveConfig、chat:sendWithMedia、clawhub:*、cron:*、provider:*等 40 余条以及无调用方的直连通道检查旧的src/lib/host-api-contract.ts、src/lib/host-api-types.ts等路径不存在验证HostApiContract是函数形状openClawDoctor: (payload: ...) ...而非{ input, output }描述符验证MaybePromise只存在于 Main 侧契约、不泄漏到渲染进程契约。配套单测 tests/unit/host-invoke.test.ts 覆盖 Main 分发器的请求格式校验与错误响应tests/unit/host-events.test.ts 覆盖 IPC 事件映射共同构成requiredTests基线。质量门禁comms 回归与文档同步任何涉及通信路径变更的任务都必须过comms回归通道pnpm run typecheck全仓库类型检查契约三方共享后类型错配会在编译期暴露pnpm run comms:replay与pnpm run comms:compare脚本位于 scripts/comms/基于数据集baseline、datasets回放并对比通信行为基线防止传输收敛引入行为漂移若通信结果改变可见 UI 状态还须运行或补充相关 Electron E2E 用例e2e-parallel-isolation、comms-regression规则。此外docs-sync规则要求 READMEREADME.md、README.zh-CN.md、README.ja-JP.md与多语言 docsdocs/zh-CN/development.md、docs/en-US/development.md 等同步描述这套类型化 IPC Main-owned Gateway WebSocket的最终形态保证文档、规则、源码三者一致。对开发者的实操约定如果要在 ClawX 上新增一个需要后端能力的功能请遵守以下边界纪律它们全部来自 renderer-main-boundary.md 与 host-api-fallback-policy.md页面与组件禁止直接调用window.electron.ipcRenderer.invoke(...)取后端数据应把新能力加进hostApi门面或 API client页面只消费门面方法新后端接口先在 Electron Main 或 host API 层暴露再在渲染进程消费不允许渲染进程先实现再补 Main不要重新引入http://127.0.0.1:13210之类的本地 Host API 服务器也不要让渲染进程触碰ws://127.0.0.1:18789/http://127.0.0.1:18789一类 Gateway 端点不要实现WS - HTTP - IPC协议切换传输选择、重试、回退全部由 Main 负责新增用户可见的 gateway/channel/OAuth/QR 事件时先补充HOST_EVENT_CHANNELS映射与 preload 通道白名单而不是引入 EventSource 兜底排查 Gateway 帧问题时在主进程环境设置CLAWX_GATEWAY_WS_TRACE1并查看 Main 日志帧内容会自动脱敏。这套架构把 ClawX 的桌面 UI ↔ OpenClaw 运行时通信收敛成一条可审计、可类型检查、可扫描验证的单一链路类型化 IPC 负责请求/响应与事件Main 独占 Gateway WebSocket 与帧诊断扫描型测试与comms回归负责长期守住边界——这正是移除本地 Host API 服务器与渲染进程 Gateway 传输这一任务的完整落点。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐ClawX 渲染进程通信边界规范Host API 分层与 Gateway 传输隔离的架构纪律ClawX 渲染进程通信边界规范Host API 分层与 Gateway 传输隔离的架构纪律 导读 本文基于 ClawX 仓库中的 harness/specs人工智能AI 应用桌面应用交互助手ClawX 渲染进程通信边界理解 hostApi 统一入口与主进程 IPC 隔离架构ClawX 渲染进程通信边界理解 hostApi 统一入口与主进程 IPC 隔离架构 导读 本文围绕 ClawXOpenClaw AI 代理的桌面图形化客户人工智能AI 应用桌面应用交互助手ClawX 桌面端与 OpenClaw 网关通信架构实战Renderer 传输边界、类型化 Host API 桥与 Gateway 心跳安全机制ClawX 桌面端与 OpenClaw 网关通信架构实战Renderer 传输边界、类型化 Host API 桥与 Gateway 心跳安全机制 ClawX人工智能AI 应用桌面应用交互助手上一篇bCNC新手教程5分钟上手GRBL控制器的G代码发送与编辑下一篇Spark ML算法性能调优指南从源码层面优化模型训练效率创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/17 7:04:08

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/17 5:42:44

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/17 19:43:34

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/17 6:55:04

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/17 5:57:47

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/17 19:43:32

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉