人工智能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 是基于 Electron 的桌面应用为 OpenClaw AI 智能体提供图形化界面将原本依赖命令行的 AI 编排工作变成纯桌面体验。本文以 docs/zh-CN/architecture.md 为核心系统讲解 ClawX 的双进程 Host API 统一接入架构、OpenClaw 配置交付协调、ACPAgent Client Protocol语义权威与历史回放补充、文件活动语义以及 Gateway 存活恢复与进程排障方案。读完本文你将掌握 ClawX 内部进程边界划分、主进程如何统一管理传输策略、Chat 历史为何以 ACP 回放为唯一事实来源以及三分钟静默 deadline 驱动的 Gateway 恢复机制与常见排障命令。一、总体架构双进程 Host API 统一接入ClawX 采用双进程 Host API 统一接入架构。渲染进程只调用统一客户端抽象协议选择与进程生命周期由 Electron 主进程统一管理。渲染层不感知底层是 WebSocket、stdio bridge 还是其它传输方式所有请求都通过类型化 IPC 进入主进程的 Host Services 与 Gateway Manager。以下架构图来自原文档略作排版整理展示了完整的分层结构┌───────────────────────────────────────────────────────────────────┐ │ ClawX 桌面应用 │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Electron 主进程 │ │ │ │ • 窗口与应用生命周期管理 │ │ │ │ • 网关进程监控 │ │ │ │ • 系统集成托盘、通知、密钥链 │ │ │ │ • 自动更新编排 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ IPC (权威控制面) │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ React 渲染进程 │ │ │ │ • 现代组件化 UIReact 19 │ │ │ │ • Zustand 状态管理 │ │ │ │ • 统一 host-api/api-client 调用 │ │ │ │ • 回复使用 Markdown用户输入按原文显示 │ │ │ └─────────────────────────────────────────────────────────────┘ │ └──────────────────────────────┬───────────────────────────────────┘ │ │ 类型化 IPC 请求 ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 主进程 Host Services 与 Gateway Manager │ │ │ │ • host:invoke 类型化服务分发 │ │ • 设置、文件、会话、技能、供应商、诊断服务 │ │ • 主进程持有 Gateway WebSocket 并负责进程监控 │ └──────────────────────────────┬──────────────────────────────────┘ │ │ 主进程持有 WebSocket ▼ ┌─────────────────────────────────────────────────────────────────┐ │ OpenClaw 网关 │ │ │ │ • AI 智能体运行时与编排 │ │ • 消息频道管理 │ │ • 技能/插件执行环境 │ │ • 供应商抽象层 │ └─────────────────────────────────────────────────────────────────┘这一分层决定了几个关键结论Gateway 是非 Chat 能力的总入口providers、models、skills、workspace、settings、diagnostics 和 media configuration 等非 Chat 能力全部由 Gateway 负责。Chat 走独立的 ACP stdio bridge由 Electron Main 持有与 Gateway WebSocket 是两条并行的权威通道互不替代详见下文。渲染进程只通过类型化 host events 消费状态Renderer 不感知 Gateway 运行实例身份即使 Gateway 经历了自动恢复渲染层仍然渲染同一个内存 ACP timeline。二、OpenClaw 配置交付权威快照为基线文件路径为兜底ClawX 的 OpenClaw 配置交付统一由 Electron Main 管理其核心规则是Gateway 运行时以config.get返回的权威快照为基线通过config.set提交修改Gateway 停止或启动中同一个协调器只更新解析后的JSON5 配置文件不会因此启动 Gateway。因此普通的 Provider、Agent、Channel、绑定、Skill 和模型修改不会替换 Gateway 进程。完整重启只保留给代理等进程启动环境变化和用户显式操作。该协调器的实际实现位于 electron/gateway/config-delivery.ts从中可以看到几个重要的工程细节① RPC 优先、文件兜底的双路径切换协调器在mutateOpenClawConfig中先判断 Gateway 状态running时走config.get→ mutator →config.set的 RPC 路径否则走文件路径。runMutation捕获到 Gateway 不可用错误如 socket 因 code 1012 在途重启而断开时会把纯函数式 mutator 在持久化文件上重放一遍——已落地的提交变成 no-op丢失的提交由 ClawX 补写Gateway 恢复运行后文件路径自动切回 RPC 路径。② 基于 baseHash 的乐观并发控制config.set携带baseHash来自config.get快照的 hash。当冲突错误信息为config changed since last load; re-run config.get and retry时协调器会重试一轮重新取快照避免覆盖其它进程的并发修改。③ 敏感值脱敏与还原config.get快照中的敏感值会被替换为哨兵值__OPENCLAW_REDACTED__常量OPENCLAW_REDACTED_SENTINEL。提交时若快照中仍带哨兵restoreRedactedSentinelsFromBaseline会从文件的原始基线还原真实值防止把占位符写回磁盘覆盖真实密钥。④ 事务串行化与响应丢失自愈所有读写操作通过transactionTail链式排队保证串行语义。当config.set的响应因 Gateway 重启code 1012丢失时ClawX 会重新读取持久化文件用isPersistedConfigSetCommitEquivalent对比提交内容与已落盘内容忽略 OpenClaw 自动维护的lastTouchedAt/lastTouchedVersion元数据确认一致即视为提交成功。⑤ secrets.reload 免重启生效认证配置写入 SQLite 后ClawX 调用reloadOpenClawSecretsIfRunning触发 OpenClaw 的secrets.reload见 config-delivery.ts让运行中的 Agent无需重启即可读取新凭据。三、Chat 传输主进程持有的 ACP stdio bridgeChat 使用由 Electron Main 持有的ACP stdio bridge。Main 通过私有进程环境把同一份应用管理的 Gateway token 传给本地子进程因此运行时配置重载后 ACP 历史回放仍能完成认证。具体流程实现于 electron/services/acp-chat-service.ts如果受保护的 Gateway 恢复中断了已接收的主会话 run补丁后的 OpenClaw 运行时会启动独立的恢复 run并显式携带直接被中断的 run id 作为lineage参见 shared/acp-chat/subagent-lineage.ts。Chat 和 agent events 会保留该 lineage重连后的 ACP bridge 据此逐次将 pending prompt 接续到新 run重置该 run 的流式游标并订阅会话级 tool events。如果之后的重启在答复持久化后丢失了进程内终态通知ACP 会把当前 run id 和 session key 传给agent.waitGateway仅在持久化 lifecycle owner 与该 run 匹配时结算。Renderer 不感知 Gateway 运行实例身份仍通过类型化 host events 渲染同一个内存 ACP timeline。ACP 语义权威对于 ACP 能够提供的每一种 Chat 语义和上下文ACP 都是优先的语义权威包括session identity 与路由、工作空间和执行cwd、prompt 与 timeline 状态以及标准 resource 或附件语义。ACP 提供值或事件时Main 和 Renderer 必须使用 ACP 的结果不得用 Gateway 快照、transcript 推断、本地配置或另一套并行投影替代。只有在上游 ACP 没有对应能力时才允许绕过 ACP。此类兼容性路径必须保持狭窄、有界并绑定 session 和 generation同时必须在相关 Harness reference 或 rule 中记录其原因、事实来源、限制、协调行为和移除条件参见 harness/reference 与 harness/specs/rules不得悄悄演变为竞争性的权威来源。Prompt 压力恢复补丁后的 OpenClaw 会在提交给 Provider 前执行prompt 压力恢复当聚合工具结果文本超过扣除预留后的 prompt 预算时根据实测溢出量和安全缓冲推导截断目标并在 mid-turn、pre-prompt 和 post-compaction 恢复中复用该目标系统优先缩减较早的工具输出同时保留每组工具调用/结果配对以及最新结果的有界表示压缩返回没有真实会话消息时不会丢弃已经实测到的 transcript 或渲染后 prompt 压力结构化压缩失败事件会将触发来源与可选的稳定原因码分开并在 ACP 记录前把纯文本原因裁剪到 500 个字符。四、ACP 历史权威与有界 transcript 补充ACPsession/load回放是Chat 历史的首要事实来源。ClawX 不会持久化第二套 ACP ledger、精简 timeline、回放缓存或重建的工具历史。当 OpenClaw 的结构化 ACP event ledger 不可用时其 ACP adapter 会按 transcript 顺序把持久化的toolCall和toolResult记录重建为原生工具更新并保留 text-tool-text 边界ClawX 本身不会推断这些记录。OpenClaw 的部分能力目前还没有完全对应的 ACP 实现例如 assistant 媒体可能不会出现在 ACP 中Gateway 处理也可能从可见的实时回复中移除 assistantMEDIA:指令。因此ClawX 只保留有界、带标记、仅存于内存的兼容性补充路径。已结算回合的 replay hydrationACP prompt 运行期间session/update通知会继续即时更新可见 timeline。Renderer 会等待类型化的session/prompt调用完成并且只在其成功返回后立即对同一 session 发起一次session/load两个操作之间没有固定 sleep。只有 session、generation、workspace 和 Renderer load request 仍然有效时才会开始 hydration。Main 会在共享 ACP connection 上串行执行 load分配下一代路由 generation在上游session/load完成前收集其 replay notifications并随 load 结果一起返回原始 batch。load 进行期间Renderer 会保留已经结算的 live timeline不暴露空白 loading 状态IPC 结果交接窗口中提前到达的新 generation events 会被缓冲。成功且非空的 batch 会先按返回的 session 和 generation 过滤再从空 ACP timeline 开始通过普通 reducer 归约最后把完整 timeline 与 generation 在一次状态提交中原子替换。Pending attachments 会按新 generation 重新解析live turn timing 会映射到 replay 中的 user-message identityreplay 图片证据也会接管旧 generation 中尚未完成的投影。失败、抛错、过期或已被 supersede 的 hydration不会替换 live 内容。成功但为空或标记为 resumed-active-prompt 的结果会保留可见 items但仍采用 Main 已经提交的 generation避免后续 events 因 generation 不匹配而被丢弃。为什么没有固定延迟session/prompt成功完成就是此流程的因果结算屏障。无条件延迟只会增加回复结算耗时、让 sending 状态维持更久并扩大 navigation 或其它 load 使本次 hydration 过期的窗口却不能证明上游持久化已经完成。如果未来确认某个上游实现在 replay 可用前就返回 prompt success正确的补救应是在相同 identity guards 下针对空 replay 或缺失当前回合做有界、条件式重试而不是加入固定延迟。下文的 1500 ms 重试只属于有界 transcript 兼容补充不是 ACP replay hydration 的一部分。有界 transcript 兼容补充路径在 ACP 回放能力不足时Main 可以有限地使用有界的 transcript JSONL 记录全部受以下约束只有在同一 session 中存在已确认的image_generate上下文且完成证据可信或来自获准 transcript 证据时才可以恢复异步图像生成结果。普通附件可以从持久化的 assistant__openclaw.media规范事实或明确的行首 assistantMEDIA:指令中恢复。这只恢复附件引用和声明的元数据不恢复周围的 assistant 消息。由于 ACP 回放不提供原始事件时间戳Main 可以从有界的 transcript JSONL 记录中补充仅包含元数据的整轮耗时但只能标注已经由 ACP 回放恢复出的回合。如果 cron session 的 ACP 回放完全为空Main 的类型化 cron-history API 可以提供计划提示词和完成摘要。当已识别的运行摘要带有 OpenClaw 截断标记时只有在对应 run 的 transcript 更长且共享完整的已持久化摘要前缀时Main 才可以恢复最终 assistant 文本。边界硬性规定历史读取最多读取最近1000 条transcript 消息一次成功的实时 prompt 会立即读取一次并在1500ms 后重试一次。每个补充路径都必须绑定精确的 session、ACP generation、补充操作并在适用时绑定当前的用户回合过期、缺失、重复或有歧义的匹配都会被丢弃。这些路径不得重建普通 assistant 消息、thought、tool、plan、permission、文件活动、缺失回合或另一套 Chat 历史Main 也不得根据 transcript 伪造原生 ACP 事件。标准 ACP resource 仍是首选上游提供等价内容后这些兼容性例外应当移除。跨会话导航与回复持续打开其它会话或页面时尚未完成的 ACP 回复仍会继续流式接收。若在回复完成前返回ClawX 会恢复最新的内存 timeline 并继续显示实时输出回复完成后普通 ACP 历史回放仍是唯一事实来源。ACP assistant 回合会显示整轮耗时Live 计时跟随客户端观测到的 prompt 生命周期并在应用内导航后保持连续历史耗时由 Electron Main 根据有界的 OpenClaw transcript 时间戳计算而且只能标注 ACP 回放已经恢复出的回合。ACP 附件与图像生成预览ACP Chat 会将标准 ACP resource 渲染为附件用户选择的图片显示为缩略图悬停蒙层中显示文件名其它可用的附件卡片显示文件名以及灰色、可截断的来源路径。当前 OpenClaw ACP adapter 遗漏 assistant 媒体时OpenClaw 持久化的规范媒体事实和显式 assistantMEDIA:指令也可恢复为附件卡片且不会显示仅用于 transcript 的元数据。现有本地文件引用包括当前 workspace 外的路径在每次预览或打开前都会由 Electron Main 按精确的 session 和 generation 重新验证见 electron/services/attachment-access.ts。AI 生成且可预览的本地附件包括不超过 20 MB的.docx和.pptx文件保留主要的只读应用内预览操作并提供次级菜单可通过兼容应用打开或在 Finder、文件资源管理器或系统文件管理器中显示。对于本地 HTML 附件该菜单第一项会在右侧预览中打开文件。Office 预览限制.doc和.ppt仍通过系统应用打开DOCX 的分页效果可能与 Microsoft Word 不同PPTX 的动画、切换效果和媒体播放不受支持。兼容应用发现仅在 macOS 和 Windows 上可用在 Linux 上或发现失败时会静默降级为仅显示文件位置。其它本地文件包括超过 20 MB 的 Office 文件会在用户点击后通过系统应用打开用户选择的文件夹附件在发送后保持可用点击后交给系统文件管理器打开ClawX不会读取或预览其中内容远程 HTTP 和 HTTPS 附件在用户点击后从外部打开。没有规范媒体事实佐证的普通文本裸路径或行内路径不会被当作附件。ACP Chat 也可在 runtime 以可信结构化媒体投递图像生成结果时显示生成图片预览。对于可信的 OpenClaw internal-UI 投递和与生图任务关联的最终回复ClawX 会保留原始的用户可见完成文案包括只有文本的失败说明而不会统一替换成通用图片文案。历史 OpenClaw 回放中assistant 的图片MEDIA:标记只有在同一会话已记录图像生成任务启动后才会进入内联图片体验。ClawX 通过 Electron Main 的主机媒体处理加载预览而不是让 Renderer 任意访问文件系统标准 ACP 图片和 resource 内容仍是首选路径并会直接渲染。五、ACP 文件活动语义ClawX 的文件活动视图遵循以下语义不依赖 Git也不做推断补造文件活动由成功且已完成的 OpenClawwrite、edit和apply_patch调用投影而来工具识别方式与 OpenClaw 官方 Chat UI 保持一致仅接收已完成调用的筛选规则是 ClawX 特有的。已创建和已修改的活动行与可预览的 assistant 附件共用同一种文件卡片外壳和打开方式菜单同时保留状态文字及可用的/-统计。对于 HTML 文件菜单第一项会在右侧预览中打开文件已删除的活动行只保留Changes操作。应用列表、指定应用打开和显示文件位置都会由 Electron Main 根据 workspace 根目录与相对路径分别重新验证工具路径不会因此变成附件Renderer 也不会获得规范化系统路径。write按工具声明的语义显示视为创建并展示为全部新增的差异即使该路径可能已经存在。Changes是按时间顺序记录工具声明活动的会话级记录不是 Git 输出也不是相对于已验证源码基线的差异。对每个文件Changes 在每轮助手回复中最多展示一个 diff 编辑器。可安全串联的片段会合并独立片段会拼接到同一个编辑器中但不会被描述为基于完整文件基线的差异。Shell 命令、脚本、用户或 IDE 产生的副作用不会被检测。完整的 ACP 回放可以恢复已记录的文件活动如果回放不完整ClawX 不会通过回退推断来补造缺失活动。六、Gateway 存活恢复三分钟静默 deadline 机制Gateway 的存活状态由 Electron 主进程判断WebSocket pong 是有价值的传输层证据。普通传输丢失时主进程优先沿既有 Gateway WebSocket 重连路径恢复连接。ClawX 在三分钟没有可信存活信号后先通过system-presence验证核心 RPC 路由再决定是否替换其自身拥有的进程。核心实现位于 electron/gateway/manager.ts 与 electron/gateway/recovery-controller.tsrecordAlive()会刷新lastAliveAt、把consecutiveHeartbeatMisses归零并取消过期的 deadline 回调deadline 到期后执行system-presence控制面探测超时 5 秒探测失败才通过受保护的升级路径请求重启自管进程。isCoreRpcMethod目前仅把system-presence视为核心读 RPC 方法manager.ts。设计点处置目的将 pong、任意入站 Gateway 帧和成功 RPC 视为存活信号*刷新lastAliveAt并取消过期的 deadline 回调当连接仍在承载真实流量时大型 AI 操作如 Skill 调用、工具调用可能导致 pong 延迟避免把这种延迟误判为 Gateway 已死亡使用单一三分钟静默 deadline180 秒前只记录 heartbeat miss不修改 socket 或进程在限制自动恢复时间的同时避免仅因 pong 缺失而重启在 deadline 到期时验证控制面以 5 秒超时调用一次system-presenceRPC从控制面而非纯 WebSocket 确认 Gateway 状态成功则恢复正常监控区分事件流暂时安静与无法提供核心读 RPC 的 Gateway只重启不可用的 ClawX 自管进程deadline probe 失败后请求受保护的 Gateway 重启路径恢复真正无响应的本地子进程绝不自动停止外部 Gateway优先仅替换或重连 ClawX 的 WebSocket并报告不可用诊断避免向 ClawX 不拥有的进程发出 shutdown保持权威生命周期路径独立保留现有 WebSocket close 重连、code 1012 reload 恢复、进程退出恢复和手动重启防止重复或竞争性的 stop/start 操作不在此路径追踪活跃工作负载无论 chat、tool 或 cron 是否活跃均使用相同 deadline让存活恢复聚焦于防止虚假重启和进程所有权* 此存活信号设计参考了 LobsterAI 项目的思路。对应的测试用例可在 tests/unit/gateway-manager-heartbeat.test.ts 与 electron/gateway/recovery-controller.test.ts 中找到覆盖了miss 只更新诊断不触发重启入站帧重置 deadlinedeadline probe 成功后不重启自管进程恰好重启一次外部 Gateway 仅走传输重连不停止进程等关键场景。心跳与自动重连的细化规则结合源码还可以看到更细的层次连续前 3 次 WebSocket 心跳无响应只更新诊断不会因短暂的 pong 延迟中断长时间运行的任务收到 pong 或任意消息会重置计数。连续第 4 次无响应时只有在生命周期处于可自动恢复的 running 状态时才会请求受保护的 Gateway 自动恢复。已确认的进程退出与 WebSocket 关闭继续使用现有的自动重连路径WebSocket close 重连、code 1012 reload 恢复、进程退出恢复、手动重启四条权威路径彼此独立避免重复或竞争性的 stop/start 操作。system-presence探测还用于ready fallback当 Gateway 长时间未上报 ready 时主进程会先探测 RPC 路由再决定是否标记 ready避免仅因事件流安静而误判故障manager.ts。七、进程模型与 Gateway 排障多进程是正常现象ClawX 基于 Electron单个应用实例出现多个系统进程是正常现象main/renderer/zygote/utility。排查问题时不要把它们误判为异常或泄漏单实例保护同时使用 Electron 自带锁与本地进程文件锁回退机制可在桌面会话总线异常时避免重复启动参见 electron/main/process-instance-lock.ts。滚动升级期间若新旧版本混跑单实例保护仍可能出现不对称行为。为保证稳定性建议桌面客户端尽量统一升级到同一版本。但 OpenClaw Gateway 监听应始终保持单实例127.0.0.1:18789只能有一个监听者。Gateway readiness 判定Gateway readiness 以 OpenClaw 的system-presence、health、status等核心信号为准memory 或频道失败会显示为能力降级而不是全局 Gateway 故障。常用排障命令确认监听进程macOS/Linuxlsof -nP -iTCP:18789 -sTCP:LISTENWindowsPowerShellGet-NetTCPConnection -LocalPort 18789 -State Listen退出方式提醒点击窗口关闭按钮X默认只是最小化到托盘并不会完全退出应用。请在托盘菜单中选择Quit ClawX执行完整退出。八、设计原则小结ClawX 架构遵循七条核心设计原则贯穿上述所有机制进程隔离AI 运行时在独立进程中运行确保即使在高负载计算期间 UI 也能保持响应前端调用单一入口渲染层统一走 host-api/api-client不感知底层协议细节主进程掌控传输策略ACP Chat stdio bridge 与 Gateway 传输都由 Electron Main 持有渲染进程通过类型化 IPC 调用 Main扩展 IPC 贡献点主进程扩展通过类型化 IPC 注册表贡献 host-api action而不是挂载 HTTP route优雅恢复内置重连、超时、退避逻辑自动处理瞬时故障安全存储API 密钥和敏感数据利用操作系统原生的安全存储机制CORS 安全渲染进程不直接请求本地 Gateway 或 Host API HTTP 端点。深入阅读架构总览原文docs/zh-CN/architecture.md配置交付协调器实现electron/gateway/config-delivery.tsGateway 管理器心跳、deadline probe、ready fallbackelectron/gateway/manager.ts存活恢复控制器electron/gateway/recovery-controller.tsACP Chat 服务generation、session/load、promptelectron/services/acp-chat-service.ts子会话 lineage 类型shared/acp-chat/subagent-lineage.ts心跳恢复测试tests/unit/gateway-manager-heartbeat.test.tsHarness 规则与参考文档harness/specs/rules、harness/reference赞分享人工智能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、ACP Chat 权威链路与 Gateway 存活恢复设计ClawX 双进程架构深入解析统一 Host API、ACP Chat 权威链路与 Gateway 存活恢复设计 ClawX 是一款为 OpenClaw AI人工智能AI 应用桌面应用交互助手ClawX 系统架构深度解析双进程 Host API 统一接入与 ACP 语义权威ClawX 系统架构深度解析双进程 Host API 统一接入与 ACP 语义权威 ClawX 是一个为 OpenClaw AI Agent 提供图形化界人工智能AI 应用桌面应用交互助手ClawX 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计ClawX 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计 ClawX 是一款为 OpenClaw AI A人工智能AI 应用桌面应用交互助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ClawX 系统架构深度解析：双进程 Host API、ACP 语义权威与 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 是基于 Electron 的桌面应用为 OpenClaw AI 智能体提供图形化界面将原本依赖命令行的 AI 编排工作变成纯桌面体验。本文以 docs/zh-CN/architecture.md 为核心系统讲解 ClawX 的双进程 Host API 统一接入架构、OpenClaw 配置交付协调、ACPAgent Client Protocol语义权威与历史回放补充、文件活动语义以及 Gateway 存活恢复与进程排障方案。读完本文你将掌握 ClawX 内部进程边界划分、主进程如何统一管理传输策略、Chat 历史为何以 ACP 回放为唯一事实来源以及三分钟静默 deadline 驱动的 Gateway 恢复机制与常见排障命令。一、总体架构双进程 Host API 统一接入ClawX 采用双进程 Host API 统一接入架构。渲染进程只调用统一客户端抽象协议选择与进程生命周期由 Electron 主进程统一管理。渲染层不感知底层是 WebSocket、stdio bridge 还是其它传输方式所有请求都通过类型化 IPC 进入主进程的 Host Services 与 Gateway Manager。以下架构图来自原文档略作排版整理展示了完整的分层结构┌───────────────────────────────────────────────────────────────────┐ │ ClawX 桌面应用 │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Electron 主进程 │ │ │ │ • 窗口与应用生命周期管理 │ │ │ │ • 网关进程监控 │ │ │ │ • 系统集成托盘、通知、密钥链 │ │ │ │ • 自动更新编排 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ IPC (权威控制面) │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ React 渲染进程 │ │ │ │ • 现代组件化 UIReact 19 │ │ │ │ • Zustand 状态管理 │ │ │ │ • 统一 host-api/api-client 调用 │ │ │ │ • 回复使用 Markdown用户输入按原文显示 │ │ │ └─────────────────────────────────────────────────────────────┘ │ └──────────────────────────────┬───────────────────────────────────┘ │ │ 类型化 IPC 请求 ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 主进程 Host Services 与 Gateway Manager │ │ │ │ • host:invoke 类型化服务分发 │ │ • 设置、文件、会话、技能、供应商、诊断服务 │ │ • 主进程持有 Gateway WebSocket 并负责进程监控 │ └──────────────────────────────┬──────────────────────────────────┘ │ │ 主进程持有 WebSocket ▼ ┌─────────────────────────────────────────────────────────────────┐ │ OpenClaw 网关 │ │ │ │ • AI 智能体运行时与编排 │ │ • 消息频道管理 │ │ • 技能/插件执行环境 │ │ • 供应商抽象层 │ └─────────────────────────────────────────────────────────────────┘这一分层决定了几个关键结论Gateway 是非 Chat 能力的总入口providers、models、skills、workspace、settings、diagnostics 和 media configuration 等非 Chat 能力全部由 Gateway 负责。Chat 走独立的 ACP stdio bridge由 Electron Main 持有与 Gateway WebSocket 是两条并行的权威通道互不替代详见下文。渲染进程只通过类型化 host events 消费状态Renderer 不感知 Gateway 运行实例身份即使 Gateway 经历了自动恢复渲染层仍然渲染同一个内存 ACP timeline。二、OpenClaw 配置交付权威快照为基线文件路径为兜底ClawX 的 OpenClaw 配置交付统一由 Electron Main 管理其核心规则是Gateway 运行时以config.get返回的权威快照为基线通过config.set提交修改Gateway 停止或启动中同一个协调器只更新解析后的JSON5 配置文件不会因此启动 Gateway。因此普通的 Provider、Agent、Channel、绑定、Skill 和模型修改不会替换 Gateway 进程。完整重启只保留给代理等进程启动环境变化和用户显式操作。该协调器的实际实现位于 electron/gateway/config-delivery.ts从中可以看到几个重要的工程细节① RPC 优先、文件兜底的双路径切换协调器在mutateOpenClawConfig中先判断 Gateway 状态running时走config.get→ mutator →config.set的 RPC 路径否则走文件路径。runMutation捕获到 Gateway 不可用错误如 socket 因 code 1012 在途重启而断开时会把纯函数式 mutator 在持久化文件上重放一遍——已落地的提交变成 no-op丢失的提交由 ClawX 补写Gateway 恢复运行后文件路径自动切回 RPC 路径。② 基于 baseHash 的乐观并发控制config.set携带baseHash来自config.get快照的 hash。当冲突错误信息为config changed since last load; re-run config.get and retry时协调器会重试一轮重新取快照避免覆盖其它进程的并发修改。③ 敏感值脱敏与还原config.get快照中的敏感值会被替换为哨兵值__OPENCLAW_REDACTED__常量OPENCLAW_REDACTED_SENTINEL。提交时若快照中仍带哨兵restoreRedactedSentinelsFromBaseline会从文件的原始基线还原真实值防止把占位符写回磁盘覆盖真实密钥。④ 事务串行化与响应丢失自愈所有读写操作通过transactionTail链式排队保证串行语义。当config.set的响应因 Gateway 重启code 1012丢失时ClawX 会重新读取持久化文件用isPersistedConfigSetCommitEquivalent对比提交内容与已落盘内容忽略 OpenClaw 自动维护的lastTouchedAt/lastTouchedVersion元数据确认一致即视为提交成功。⑤ secrets.reload 免重启生效认证配置写入 SQLite 后ClawX 调用reloadOpenClawSecretsIfRunning触发 OpenClaw 的secrets.reload见 config-delivery.ts让运行中的 Agent无需重启即可读取新凭据。三、Chat 传输主进程持有的 ACP stdio bridgeChat 使用由 Electron Main 持有的ACP stdio bridge。Main 通过私有进程环境把同一份应用管理的 Gateway token 传给本地子进程因此运行时配置重载后 ACP 历史回放仍能完成认证。具体流程实现于 electron/services/acp-chat-service.ts如果受保护的 Gateway 恢复中断了已接收的主会话 run补丁后的 OpenClaw 运行时会启动独立的恢复 run并显式携带直接被中断的 run id 作为lineage参见 shared/acp-chat/subagent-lineage.ts。Chat 和 agent events 会保留该 lineage重连后的 ACP bridge 据此逐次将 pending prompt 接续到新 run重置该 run 的流式游标并订阅会话级 tool events。如果之后的重启在答复持久化后丢失了进程内终态通知ACP 会把当前 run id 和 session key 传给agent.waitGateway仅在持久化 lifecycle owner 与该 run 匹配时结算。Renderer 不感知 Gateway 运行实例身份仍通过类型化 host events 渲染同一个内存 ACP timeline。ACP 语义权威对于 ACP 能够提供的每一种 Chat 语义和上下文ACP 都是优先的语义权威包括session identity 与路由、工作空间和执行cwd、prompt 与 timeline 状态以及标准 resource 或附件语义。ACP 提供值或事件时Main 和 Renderer 必须使用 ACP 的结果不得用 Gateway 快照、transcript 推断、本地配置或另一套并行投影替代。只有在上游 ACP 没有对应能力时才允许绕过 ACP。此类兼容性路径必须保持狭窄、有界并绑定 session 和 generation同时必须在相关 Harness reference 或 rule 中记录其原因、事实来源、限制、协调行为和移除条件参见 harness/reference 与 harness/specs/rules不得悄悄演变为竞争性的权威来源。Prompt 压力恢复补丁后的 OpenClaw 会在提交给 Provider 前执行prompt 压力恢复当聚合工具结果文本超过扣除预留后的 prompt 预算时根据实测溢出量和安全缓冲推导截断目标并在 mid-turn、pre-prompt 和 post-compaction 恢复中复用该目标系统优先缩减较早的工具输出同时保留每组工具调用/结果配对以及最新结果的有界表示压缩返回没有真实会话消息时不会丢弃已经实测到的 transcript 或渲染后 prompt 压力结构化压缩失败事件会将触发来源与可选的稳定原因码分开并在 ACP 记录前把纯文本原因裁剪到 500 个字符。四、ACP 历史权威与有界 transcript 补充ACPsession/load回放是Chat 历史的首要事实来源。ClawX 不会持久化第二套 ACP ledger、精简 timeline、回放缓存或重建的工具历史。当 OpenClaw 的结构化 ACP event ledger 不可用时其 ACP adapter 会按 transcript 顺序把持久化的toolCall和toolResult记录重建为原生工具更新并保留 text-tool-text 边界ClawX 本身不会推断这些记录。OpenClaw 的部分能力目前还没有完全对应的 ACP 实现例如 assistant 媒体可能不会出现在 ACP 中Gateway 处理也可能从可见的实时回复中移除 assistantMEDIA:指令。因此ClawX 只保留有界、带标记、仅存于内存的兼容性补充路径。已结算回合的 replay hydrationACP prompt 运行期间session/update通知会继续即时更新可见 timeline。Renderer 会等待类型化的session/prompt调用完成并且只在其成功返回后立即对同一 session 发起一次session/load两个操作之间没有固定 sleep。只有 session、generation、workspace 和 Renderer load request 仍然有效时才会开始 hydration。Main 会在共享 ACP connection 上串行执行 load分配下一代路由 generation在上游session/load完成前收集其 replay notifications并随 load 结果一起返回原始 batch。load 进行期间Renderer 会保留已经结算的 live timeline不暴露空白 loading 状态IPC 结果交接窗口中提前到达的新 generation events 会被缓冲。成功且非空的 batch 会先按返回的 session 和 generation 过滤再从空 ACP timeline 开始通过普通 reducer 归约最后把完整 timeline 与 generation 在一次状态提交中原子替换。Pending attachments 会按新 generation 重新解析live turn timing 会映射到 replay 中的 user-message identityreplay 图片证据也会接管旧 generation 中尚未完成的投影。失败、抛错、过期或已被 supersede 的 hydration不会替换 live 内容。成功但为空或标记为 resumed-active-prompt 的结果会保留可见 items但仍采用 Main 已经提交的 generation避免后续 events 因 generation 不匹配而被丢弃。为什么没有固定延迟session/prompt成功完成就是此流程的因果结算屏障。无条件延迟只会增加回复结算耗时、让 sending 状态维持更久并扩大 navigation 或其它 load 使本次 hydration 过期的窗口却不能证明上游持久化已经完成。如果未来确认某个上游实现在 replay 可用前就返回 prompt success正确的补救应是在相同 identity guards 下针对空 replay 或缺失当前回合做有界、条件式重试而不是加入固定延迟。下文的 1500 ms 重试只属于有界 transcript 兼容补充不是 ACP replay hydration 的一部分。有界 transcript 兼容补充路径在 ACP 回放能力不足时Main 可以有限地使用有界的 transcript JSONL 记录全部受以下约束只有在同一 session 中存在已确认的image_generate上下文且完成证据可信或来自获准 transcript 证据时才可以恢复异步图像生成结果。普通附件可以从持久化的 assistant__openclaw.media规范事实或明确的行首 assistantMEDIA:指令中恢复。这只恢复附件引用和声明的元数据不恢复周围的 assistant 消息。由于 ACP 回放不提供原始事件时间戳Main 可以从有界的 transcript JSONL 记录中补充仅包含元数据的整轮耗时但只能标注已经由 ACP 回放恢复出的回合。如果 cron session 的 ACP 回放完全为空Main 的类型化 cron-history API 可以提供计划提示词和完成摘要。当已识别的运行摘要带有 OpenClaw 截断标记时只有在对应 run 的 transcript 更长且共享完整的已持久化摘要前缀时Main 才可以恢复最终 assistant 文本。边界硬性规定历史读取最多读取最近1000 条transcript 消息一次成功的实时 prompt 会立即读取一次并在1500ms 后重试一次。每个补充路径都必须绑定精确的 session、ACP generation、补充操作并在适用时绑定当前的用户回合过期、缺失、重复或有歧义的匹配都会被丢弃。这些路径不得重建普通 assistant 消息、thought、tool、plan、permission、文件活动、缺失回合或另一套 Chat 历史Main 也不得根据 transcript 伪造原生 ACP 事件。标准 ACP resource 仍是首选上游提供等价内容后这些兼容性例外应当移除。跨会话导航与回复持续打开其它会话或页面时尚未完成的 ACP 回复仍会继续流式接收。若在回复完成前返回ClawX 会恢复最新的内存 timeline 并继续显示实时输出回复完成后普通 ACP 历史回放仍是唯一事实来源。ACP assistant 回合会显示整轮耗时Live 计时跟随客户端观测到的 prompt 生命周期并在应用内导航后保持连续历史耗时由 Electron Main 根据有界的 OpenClaw transcript 时间戳计算而且只能标注 ACP 回放已经恢复出的回合。ACP 附件与图像生成预览ACP Chat 会将标准 ACP resource 渲染为附件用户选择的图片显示为缩略图悬停蒙层中显示文件名其它可用的附件卡片显示文件名以及灰色、可截断的来源路径。当前 OpenClaw ACP adapter 遗漏 assistant 媒体时OpenClaw 持久化的规范媒体事实和显式 assistantMEDIA:指令也可恢复为附件卡片且不会显示仅用于 transcript 的元数据。现有本地文件引用包括当前 workspace 外的路径在每次预览或打开前都会由 Electron Main 按精确的 session 和 generation 重新验证见 electron/services/attachment-access.ts。AI 生成且可预览的本地附件包括不超过 20 MB的.docx和.pptx文件保留主要的只读应用内预览操作并提供次级菜单可通过兼容应用打开或在 Finder、文件资源管理器或系统文件管理器中显示。对于本地 HTML 附件该菜单第一项会在右侧预览中打开文件。Office 预览限制.doc和.ppt仍通过系统应用打开DOCX 的分页效果可能与 Microsoft Word 不同PPTX 的动画、切换效果和媒体播放不受支持。兼容应用发现仅在 macOS 和 Windows 上可用在 Linux 上或发现失败时会静默降级为仅显示文件位置。其它本地文件包括超过 20 MB 的 Office 文件会在用户点击后通过系统应用打开用户选择的文件夹附件在发送后保持可用点击后交给系统文件管理器打开ClawX不会读取或预览其中内容远程 HTTP 和 HTTPS 附件在用户点击后从外部打开。没有规范媒体事实佐证的普通文本裸路径或行内路径不会被当作附件。ACP Chat 也可在 runtime 以可信结构化媒体投递图像生成结果时显示生成图片预览。对于可信的 OpenClaw internal-UI 投递和与生图任务关联的最终回复ClawX 会保留原始的用户可见完成文案包括只有文本的失败说明而不会统一替换成通用图片文案。历史 OpenClaw 回放中assistant 的图片MEDIA:标记只有在同一会话已记录图像生成任务启动后才会进入内联图片体验。ClawX 通过 Electron Main 的主机媒体处理加载预览而不是让 Renderer 任意访问文件系统标准 ACP 图片和 resource 内容仍是首选路径并会直接渲染。五、ACP 文件活动语义ClawX 的文件活动视图遵循以下语义不依赖 Git也不做推断补造文件活动由成功且已完成的 OpenClawwrite、edit和apply_patch调用投影而来工具识别方式与 OpenClaw 官方 Chat UI 保持一致仅接收已完成调用的筛选规则是 ClawX 特有的。已创建和已修改的活动行与可预览的 assistant 附件共用同一种文件卡片外壳和打开方式菜单同时保留状态文字及可用的/-统计。对于 HTML 文件菜单第一项会在右侧预览中打开文件已删除的活动行只保留Changes操作。应用列表、指定应用打开和显示文件位置都会由 Electron Main 根据 workspace 根目录与相对路径分别重新验证工具路径不会因此变成附件Renderer 也不会获得规范化系统路径。write按工具声明的语义显示视为创建并展示为全部新增的差异即使该路径可能已经存在。Changes是按时间顺序记录工具声明活动的会话级记录不是 Git 输出也不是相对于已验证源码基线的差异。对每个文件Changes 在每轮助手回复中最多展示一个 diff 编辑器。可安全串联的片段会合并独立片段会拼接到同一个编辑器中但不会被描述为基于完整文件基线的差异。Shell 命令、脚本、用户或 IDE 产生的副作用不会被检测。完整的 ACP 回放可以恢复已记录的文件活动如果回放不完整ClawX 不会通过回退推断来补造缺失活动。六、Gateway 存活恢复三分钟静默 deadline 机制Gateway 的存活状态由 Electron 主进程判断WebSocket pong 是有价值的传输层证据。普通传输丢失时主进程优先沿既有 Gateway WebSocket 重连路径恢复连接。ClawX 在三分钟没有可信存活信号后先通过system-presence验证核心 RPC 路由再决定是否替换其自身拥有的进程。核心实现位于 electron/gateway/manager.ts 与 electron/gateway/recovery-controller.tsrecordAlive()会刷新lastAliveAt、把consecutiveHeartbeatMisses归零并取消过期的 deadline 回调deadline 到期后执行system-presence控制面探测超时 5 秒探测失败才通过受保护的升级路径请求重启自管进程。isCoreRpcMethod目前仅把system-presence视为核心读 RPC 方法manager.ts。设计点处置目的将 pong、任意入站 Gateway 帧和成功 RPC 视为存活信号*刷新lastAliveAt并取消过期的 deadline 回调当连接仍在承载真实流量时大型 AI 操作如 Skill 调用、工具调用可能导致 pong 延迟避免把这种延迟误判为 Gateway 已死亡使用单一三分钟静默 deadline180 秒前只记录 heartbeat miss不修改 socket 或进程在限制自动恢复时间的同时避免仅因 pong 缺失而重启在 deadline 到期时验证控制面以 5 秒超时调用一次system-presenceRPC从控制面而非纯 WebSocket 确认 Gateway 状态成功则恢复正常监控区分事件流暂时安静与无法提供核心读 RPC 的 Gateway只重启不可用的 ClawX 自管进程deadline probe 失败后请求受保护的 Gateway 重启路径恢复真正无响应的本地子进程绝不自动停止外部 Gateway优先仅替换或重连 ClawX 的 WebSocket并报告不可用诊断避免向 ClawX 不拥有的进程发出 shutdown保持权威生命周期路径独立保留现有 WebSocket close 重连、code 1012 reload 恢复、进程退出恢复和手动重启防止重复或竞争性的 stop/start 操作不在此路径追踪活跃工作负载无论 chat、tool 或 cron 是否活跃均使用相同 deadline让存活恢复聚焦于防止虚假重启和进程所有权* 此存活信号设计参考了 LobsterAI 项目的思路。对应的测试用例可在 tests/unit/gateway-manager-heartbeat.test.ts 与 electron/gateway/recovery-controller.test.ts 中找到覆盖了miss 只更新诊断不触发重启入站帧重置 deadlinedeadline probe 成功后不重启自管进程恰好重启一次外部 Gateway 仅走传输重连不停止进程等关键场景。心跳与自动重连的细化规则结合源码还可以看到更细的层次连续前 3 次 WebSocket 心跳无响应只更新诊断不会因短暂的 pong 延迟中断长时间运行的任务收到 pong 或任意消息会重置计数。连续第 4 次无响应时只有在生命周期处于可自动恢复的 running 状态时才会请求受保护的 Gateway 自动恢复。已确认的进程退出与 WebSocket 关闭继续使用现有的自动重连路径WebSocket close 重连、code 1012 reload 恢复、进程退出恢复、手动重启四条权威路径彼此独立避免重复或竞争性的 stop/start 操作。system-presence探测还用于ready fallback当 Gateway 长时间未上报 ready 时主进程会先探测 RPC 路由再决定是否标记 ready避免仅因事件流安静而误判故障manager.ts。七、进程模型与 Gateway 排障多进程是正常现象ClawX 基于 Electron单个应用实例出现多个系统进程是正常现象main/renderer/zygote/utility。排查问题时不要把它们误判为异常或泄漏单实例保护同时使用 Electron 自带锁与本地进程文件锁回退机制可在桌面会话总线异常时避免重复启动参见 electron/main/process-instance-lock.ts。滚动升级期间若新旧版本混跑单实例保护仍可能出现不对称行为。为保证稳定性建议桌面客户端尽量统一升级到同一版本。但 OpenClaw Gateway 监听应始终保持单实例127.0.0.1:18789只能有一个监听者。Gateway readiness 判定Gateway readiness 以 OpenClaw 的system-presence、health、status等核心信号为准memory 或频道失败会显示为能力降级而不是全局 Gateway 故障。常用排障命令确认监听进程macOS/Linuxlsof -nP -iTCP:18789 -sTCP:LISTENWindowsPowerShellGet-NetTCPConnection -LocalPort 18789 -State Listen退出方式提醒点击窗口关闭按钮X默认只是最小化到托盘并不会完全退出应用。请在托盘菜单中选择Quit ClawX执行完整退出。八、设计原则小结ClawX 架构遵循七条核心设计原则贯穿上述所有机制进程隔离AI 运行时在独立进程中运行确保即使在高负载计算期间 UI 也能保持响应前端调用单一入口渲染层统一走 host-api/api-client不感知底层协议细节主进程掌控传输策略ACP Chat stdio bridge 与 Gateway 传输都由 Electron Main 持有渲染进程通过类型化 IPC 调用 Main扩展 IPC 贡献点主进程扩展通过类型化 IPC 注册表贡献 host-api action而不是挂载 HTTP route优雅恢复内置重连、超时、退避逻辑自动处理瞬时故障安全存储API 密钥和敏感数据利用操作系统原生的安全存储机制CORS 安全渲染进程不直接请求本地 Gateway 或 Host API HTTP 端点。深入阅读架构总览原文docs/zh-CN/architecture.md配置交付协调器实现electron/gateway/config-delivery.tsGateway 管理器心跳、deadline probe、ready fallbackelectron/gateway/manager.ts存活恢复控制器electron/gateway/recovery-controller.tsACP Chat 服务generation、session/load、promptelectron/services/acp-chat-service.ts子会话 lineage 类型shared/acp-chat/subagent-lineage.ts心跳恢复测试tests/unit/gateway-manager-heartbeat.test.tsHarness 规则与参考文档harness/specs/rules、harness/reference赞分享人工智能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、ACP Chat 权威链路与 Gateway 存活恢复设计ClawX 双进程架构深入解析统一 Host API、ACP Chat 权威链路与 Gateway 存活恢复设计 ClawX 是一款为 OpenClaw AI人工智能AI 应用桌面应用交互助手ClawX 系统架构深度解析双进程 Host API 统一接入与 ACP 语义权威ClawX 系统架构深度解析双进程 Host API 统一接入与 ACP 语义权威 ClawX 是一个为 OpenClaw AI Agent 提供图形化界人工智能AI 应用桌面应用交互助手ClawX 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计ClawX 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计 ClawX 是一款为 OpenClaw AI A人工智能AI 应用桌面应用交互助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
