人工智能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），仅供参考