尧图网站建设 
人工智能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 是一个为 OpenClaw AI Agent 提供图形化界面的桌面应用将基于 CLI 的 AI 编排转化为无需使用终端的桌面体验。本文基于 docs/ru-RU/architecture.md以及与之同源的 docs/en-US/architecture.md、docs/zh-CN/architecture.md展开聚焦 ClawX 的双进程架构、Host API 统一接入层、ACP 语义权威、配置交付策略、Gateway 存活恢复等核心设计并结合仓库源码与测试验证每一处关键机制。读完本文你将掌握 ClawX 从「Renderer → Main → Gateway」的完整调用链、ACP 历史回放与 transcript 补充的边界、以及三分钟存活恢复策略的底层实现。架构总览双进程 Host API 统一接入ClawX 采用双进程架构 Host API 统一接入层。RendererReact 渲染进程只调用一个统一的客户端抽象而协议选择与进程生命周期由 Electron Main主进程统一管理。这意味着前端代码不感知底层是走 ACP stdio bridge、Gateway WebSocket 还是本地文件操作——所有协议细节都被隐藏在稳定的host-api/api-client接口之后。仓库中给出了完整的分层结构示意四个层次自上而下┌──────────────────────────────────────────────────────────────────┐ │ ClawX 桌面应用 │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Electron 主进程 │ │ │ │ • 窗口与应用生命周期管理 │ │ │ │ • 网关进程监控 │ │ │ │ • 系统集成托盘、通知、密钥链 │ │ │ │ • 自动更新编排 │ │ │ └──────────────────────────────────────────────┬────────────────┘ │ │ │ IPC (权威控制面) │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ React 渲染进程 │ │ │ │ • 现代组件化 UIReact 19 │ │ │ │ • Zustand 状态管理 │ │ │ │ • 统一 host-api/api-client 调用 │ │ │ │ • 回复使用 Markdown用户输入按原文显示 │ │ │ └──────────────────────────────────────────────┬────────────────┘ │ │ │ 类型化 IPC 请求 │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 主进程 Host Services 与 Gateway Manager │ │ │ │ • host:invoke 类型化服务分发 │ │ │ │ • 设置、文件、会话、技能、供应商、诊断服务 │ │ │ │ • 主进程持有 Gateway WebSocket 并负责进程监控 │ │ │ └──────────────────────────────────────────────┬────────────────┘ │ │ │ 主进程持有 WebSocket│ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ OpenClaw 网关 │ │ │ │ • AI 智能体运行时与编排 │ │ │ │ • 消息频道管理 │ │ │ │ • 技能/插件执行环境 │ │ │ │ • 供应商抽象层 │ │ │ └─────────────────────────────────────────────────────────────┘ │各层职责可以归纳如下Electron Main窗口与应用生命周期管理、Gateway 进程监督electron/gateway/manager.ts 中的GatewayManager是核心实现、系统集成托盘、通知、密钥链、自动更新编排。React Renderer现代组件化 UIReact 19、Zustand 状态管理、统一host-api/api-client调用、Markdown 回复与原文用户输入。Main Host Services 与 Gateway Manager通过host:invoke提供类型化服务分发覆盖设置、文件、会话、技能、供应商、诊断等服务Gateway WebSocket 与进程监督归 Main 所有。OpenClaw GatewayAI 智能体运行时与编排、消息频道管理、技能/插件执行环境、供应商抽象层运行在独立进程中。主进程的职责边界从源码看主进程的核心类GatewayManagerelectron/gateway/manager.ts负责Gateway 生命周期start()、stop()、restart()、debouncedRestart()等状态机由GatewayStateController维护stopped/starting/running/error等。WebSocket 通信通过rpc()方法按 OpenClaw 协议格式{ type: req, id, method, params }发送请求manager.ts。健康检查checkHealth()并行调用health与statusRPCcheckTransportHealth()只检查 WebSocket 是否 OPENOpenClaw Gateway 没有 HTTP /health 端点。能力监控GatewayCapabilityMonitor将health、status、channels.status、doctor.memory.*等 RPC 分类为不同能力记录成功/失败classifyCapabilityMethodmanager.ts。RPC 路由判定isCoreRpcMethod把system-presence视为核心读 RPCmanager.ts。Renderer 与 Main 的类型化 IPCRenderer 不直接调用本地 HTTP 端点而是通过类型化 IPC 请求 Main。IPC 契约定义在 electron/main/ipc/host-contract.ts请求形如{ id, module, action, payload }响应为{ ok: true, data }或{ ok: false, error: { code, message } }错误码分为VALIDATION/UNSUPPORTED/INTERNAL。服务注册与分发由 electron/main/ipc/host-invoke.ts 中的HostApiRegistry完成核心服务通过registerCoreServices()注册主进程扩展则通过registerExtensionContributions()以(extensionId, contributions) () void的形式贡献 host-api action——这与文档中的「扩展 IPC 贡献点」设计原则一一对应。OpenClaw 配置交付config.get / config.set 与 JSON5 协调OpenClaw 配置交付同样由 Electron Main 统一管理核心策略是「按 Gateway 运行状态选择写入路径」Gateway 运行中以config.get返回的权威快照为基线通过config.set提交修改。Gateway 停止或启动中同一个协调器只更新解析后的 JSON5 配置文件即 OpenClaw 的openclaw.json不会因此启动 Gateway。这一策略的直接收益是普通的 Provider、Agent、Channel、绑定、Skill 和模型修改不会替换 Gateway 进程。完整重启只保留给两类场景进程启动环境的变化如代理 proxy 设置用户的显式操作。配套实现位于 electron/gateway/config-sync.ts 的syncGatewayConfigBeforeLaunch()每次 Gateway 启动前会执行代理同步syncProxyConfigToOpenClaw、配置消毒sanitizeOpenClawConfig、频道插件自动升级/清理、DingTalk dws 预置、Gateway token 批量同步batchSyncConfigFields等预启动维护任务并利用runCachedPrelaunchMaintenanceTask缓存签名避免重复开销。认证配置热更新secrets.reload文档强调认证配置写入 SQLite 后ClawX 会调用 OpenClaw 的secrets.reload让运行中的 Agent 无需重启即可读取新凭据。这意味着你在设置页保存 Provider API Key 后正在运行的 Agent 会话不会被打断新凭据通过 reload 机制即时生效。心跳与自动恢复配置变更虽然不会触发重启但 Gateway 自身的健康状态由主进程持续监控心跳参数GATEWAY_HEARTBEAT_INTERVAL_MS 60_000发送间隔 60s、GATEWAY_HEARTBEAT_TIMEOUT_MS 30_000等待超时 30s、GATEWAY_HEARTBEAT_MAX_MISSES 4最大连续漏跳 4 次、GATEWAY_LIVENESS_DEADLINE_MS 180_000三分钟存活静默 deadline、GATEWAY_CONTROL_PROBE_TIMEOUT_MS 5_000控制面探测超时 5s全部定义在 electron/gateway/recovery-budget.ts。前三跳只诊断连续前 3 次 WebSocket 心跳无响应只更新诊断计数consecutiveHeartbeatMisses不会因短暂的 pong 延迟中断长时间运行的任务例如大型 Skill 或工具调用天然会延迟 pong。收到 pong 或任意入站消息会重置计数markAlive(pong | message)将consecutiveMisses归零并重新安排 deadlineelectron/gateway/connection-monitor.ts。第四次漏跳仅当生命周期处于可自动恢复的 running 状态时才请求受保护的 Gateway 自动恢复。已确认的退出与重连路径已确认的进程退出与WebSocket close继续使用现有的自动重连路径scheduleReconnect()。code 1012 reloadGateway 在进程内重启如 code 1012后Main 检测到仍持有该进程的所有权时会保留 ownership并记录一次 restart 完成避免多余的 killrespawnmanager.ts。ACP 语义权威Chat 的唯一事实来源什么是 ACP 语义权威ACPAgent Client Protocol是 ClawX 中每个 Chat 语义和上下文的优先权威来源而不仅是session/load的历史来源。适用场景包括session identity 与路由适用时工作空间与执行cwdprompt 与 timeline 状态标准 resource 或附件语义。当 ACP 提供某个值或事件时Main 和 Renderer 必须使用 ACP 的结果不得用以下替代品替换Gateway 快照transcript 推断本地配置另一套并行投影。绕过 ACP 的严格条件只有在上游 ACP没有对应能力时才允许绕过 ACP。此类兼容性路径必须满足保持狭窄、有界绑定session 和 generation在相关 Harness reference 或 rule 中记录原因rationale、事实来源source of truth、限制limits、协调行为reconciliation behavior、移除条件removal condition。它不得悄悄演变为竞争性的权威来源。ClawX 只在「有界、带标记、仅存于内存」的范围内维护兼容性补充见下文。prompt 压力恢复补丁后的 OpenClaw 会在提交给 Provider 之前执行 prompt 压力恢复。当聚合工具结果文本超过「扣除预留后的 prompt 预算」时根据实测溢出量 安全缓冲推导一个统一的截断目标truncation target该目标在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 只保留有界、带标记、仅存于内存的兼容性补充路径bounded transcript supplements。已结算回合的 replay hydration这是文档中最重要的运行时流程描述了「prompt 完成后如何把历史回放合并进可见 timeline」即时更新ACP prompt 运行期间session/update通知会继续即时更新可见 timeline。无固定 sleepRenderer 等待类型化的session/prompt调用完成并且只在其成功返回后立即对同一 session 发起一次session/load两个操作之间没有固定 sleep。有效性守卫只有 session、generation、workspace 和 Renderer load request 仍然有效时才开始 hydration。串行与缓冲Main 会在共享 ACP connection 上串行执行 load分配下一代 routing generation在上游session/load完成前缓冲replay notifications并随 load 结果一起返回原始 batch。无空白 loadingload 进行期间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 不匹配被丢弃。源码佐证AcpChatService.performLoadSession()中的resumed-active-prompt分支electron/services/acp-chat-service.ts与loadSession()的串行队列acp-chat-service.ts完整实现了上述语义sendPrompt()则实现了 session 未加载、prompt 重复激活、cwd 不匹配等守卫acp-chat-service.ts。因果结算屏障为什么不用固定延迟session/prompt成功完成就是这个流程的因果结算屏障causal settlement barrier。文档明确解释了为什么不该用无条件延迟无条件延迟只会——增加回复结算耗时让 sending 状态维持更久扩大 navigation 或其它 load 使本次 hydration 过期的窗口而它并不能证明上游持久化已经完成。如果未来确认某个上游实现在 replay 可用前就返回 prompt success正确的补救是在相同 identity guards下针对空 replay 或缺失当前回合做有界、条件式重试而不是加入固定延迟。注意下文提到的1500 ms 重试只属于有界 transcript 兼容补充不是 ACP replay hydration 的一部分。有界 transcript 补充的边界历史读取最多读取最近 1000 条 transcript 消息一次成功的实时 prompt 会立即读取一次并在1500 ms 后重试一次。每类补充都有严格边界补充类型恢复条件边界异步图像生成结果同一 session 存在已确认的image_generate上下文且完成证据可信或来自获准 transcript 证据只恢复结果本身普通附件持久化的 assistant__openclaw.media规范事实或明确的行首 assistantMEDIA:指令只恢复附件引用和声明的元数据不恢复周围的 assistant 消息整轮耗时ACP 回放不提供原始事件时间戳Main 从有界的 transcript JSONL 记录中补充仅含元数据的整轮耗时只能标注已经由 ACP 回放恢复出的回合cron 会话历史cron session 的 ACP 回放完全为空时Main 的类型化 cron-history API 提供计划提示词和完成摘要仅当对应 run 的 transcript 更长且共享完整的已持久化摘要前缀时才可恢复最终 assistant 文本每个补充路径都必须绑定精确的 session、ACP generation、补充操作并在适用时绑定当前用户回合过期、缺失、重复或有歧义的匹配都会被丢弃。禁止事项这些路径不得做重建普通 assistant 消息、thought、tool、plan、permission重建文件活动、缺失回合或另一套 Chat 历史Main 根据 transcript伪造原生 ACP 事件。标准 ACP resource 仍是首选上游提供等价内容后这些兼容性例外应当移除。未完成回复的流式行为打开其它会话或页面时尚未完成的 ACP 回复仍会继续流式接收。若在回复完成前返回ClawX 会恢复最新的内存 timeline 并继续显示实时输出回复完成后普通 ACP 历史回放仍是唯一事实来源。整轮耗时whole-turn timingACP assistant 回合会显示整轮耗时Live 计时跟随客户端观测到的 prompt 生命周期并在应用内导航后保持连续历史耗时由 Electron Main 根据有界的 OpenClaw transcript 时间戳计算而且只能标注 ACP 回放已经恢复出的回合。附件、文件活动与 Office 预览语义附件渲染ACP Chat 将标准 ACP resource渲染为附件。用户选择的图片显示为缩略图悬停蒙层显示文件名其它附件卡片显示文件名与灰色、可截断的来源路径。当 OpenClaw ACP adapter 遗漏 assistant 媒体时__openclaw.media规范事实和显式MEDIA:指令可恢复为附件卡片且不显示仅用于 transcript 的元数据。路径重新验证现有本地文件引用包括当前 workspace 外的路径在每次预览或打开前都由 Electron Main 按精确的 session 和 generation 重新验证——这是 CORS 安全原则的延伸Renderer 不做任意文件系统访问。Office 与 HTML 附件可预览的本地附件AI 生成且可预览的本地附件包括不超过20 MB的.docx和.pptx保留主要的只读应用内预览操作并提供次级菜单通过兼容应用打开或在 Finder / 文件资源管理器 / 系统文件管理器中显示。HTML 附件菜单第一项在右侧Preview标签页中打开文件。Office 限制.doc和.ppt仍通过系统应用打开DOCX 分页可能与 Microsoft Word 不同PPTX 的动画、切换效果和媒体播放不受支持。兼容应用发现仅在 macOS 和 Windows 可用Linux 上或发现失败时静默降级为仅显示文件位置。其它本地文件包括超过 20 MB 的 Office 文件在用户点击后通过系统应用打开。文件夹附件用户选择的文件夹在发送后保持可用点击后交给系统文件管理器打开ClawX 不会读取或预览其中内容。远程 HTTP/HTTPS 附件用户点击后从外部打开。裸路径没有规范媒体事实佐证的普通文本裸路径或行内路径不会被当作附件。生成图片预览当 runtime 以可信结构化媒体投递图像生成结果时ACP Chat 可显示生成图片预览可信的 OpenClaw internal-UI 投递和与生图任务关联的最终回复保留原始的用户可见完成文案包括只有文本的失败说明不统一替换成通用图片文案历史回放中assistant 的图片MEDIA:标记只有在同一会话已记录图像生成任务启动后才进入内联图片体验ClawX 通过 Electron Main 的主机媒体处理加载预览不是Renderer 任意文件系统访问标准 ACP 图片和 resource 内容仍是首选路径并直接渲染。ACP 文件活动语义文件活动由成功且已完成的 OpenClawwrite、edit、apply_patch调用投影而来工具识别方式与 OpenClaw 官方 Chat UI 保持一致「仅接收已完成调用」的筛选规则是 ClawX 特有的。已创建/已修改的活动行与可预览的 assistant 附件共用同一种文件卡片外壳和「打开方式」菜单同时保留状态文字与可选的/-统计。HTML 文件菜单第一项在右侧Preview标签页打开已删除的行只保留Changes操作。独立重新验证应用列表、指定应用打开、显示文件位置都由 Electron Main 根据 workspace 根目录与相对路径分别重新验证工具路径不会变成附件Renderer 也不会获得规范化系统路径。write语义按工具声明的语义显示——视为创建展示为全部新增的 diff即使该路径可能已存在。Changes 不是 Git 输出它是按时间顺序记录工具声明活动的会话级记录不是 Git 输出也不是相对已验证源码基线的差异。每文件每回合最多一个 diff 编辑器可安全串联的片段会合并独立片段拼接到同一个编辑器但不会被描述为基于完整文件基线的差异。不检测副作用Shell 命令、脚本、用户或 IDE 产生的副作用不会被检测。完整回放可恢复完整的 ACP 回放可以恢复已记录的文件活动如果回放不完整ClawX不会通过回退推断补造缺失活动。ACP stdio bridge认证、恢复 run 与 agent.wait 结算Main 持有的 ACP 子进程Chat 使用由Electron Main 持有的 ACP stdio bridge。AcpChatServiceelectron/services/acp-chat-service.ts通过fork()启动openclaw acp子进程并通过 NDJSON 流与agentclientprotocol/sdk的ClientSideConnection通信。两个关键实现细节Token 注入Main 通过私有进程环境把OPENCLAW_GATEWAY_TOKEN传给本地子进程acp-chat-service.ts因此运行时配置重载后 ACP 历史回放仍能完成认证。stdout 诊断过滤OpenClaw 启动时可能向 stdout 输出 clack/doctor 诊断文本filterAcpStdoutDiagnostics会把非 JSON 行挡在 SDK 严格的 NDJSON 解析器之外acp-chat-service.ts。恢复 run 与 lineage如果受保护的 Gateway 恢复中断了已接收的主会话 run补丁后的 OpenClaw 运行时会启动独立的恢复 run并显式携带直接被中断的 run id 作为 lineage。Chat 和 agent events 会保留该 lineage重连后的 ACP bridge 据此逐次将 pending prompt 接续到新 run重置该 run 的流式游标订阅会话级 tool events。agent.wait 结算如果之后的重启在答复持久化后丢失了进程内终态通知ACP 会把当前 run id 和 session key 传给agent.waitGateway 仅在持久化 lifecycle owner 与该 run 匹配时结算。这保证了「答复已写入持久化存储但进程内终态丢失」时主进程不会误判任务未完成。Renderer 的无身份视角Renderer 不感知 Gateway 运行实例身份仍通过类型化 host events 渲染同一个内存 ACP timeline。这意味着 Gateway 的进程替换、run 恢复、token 重载对前端完全透明。Gateway 继续负责 providers、models、skills、workspace、settings、diagnostics 和 media configuration 等非 Chat 能力。设计原则文档列出的七条设计原则与源码一一对应原则含义源码佐证进程隔离AI 运行时在独立进程中运行即使高负载计算期间 UI 也保持响应GatewayManager通过Electron.UtilityProcess/ 子进程启动 Gateway前端调用单一入口渲染层统一走 host-api/api-client不感知底层协议细节electron/main/ipc/host-contract.ts 的类型化请求/响应契约主进程掌控传输策略ACP Chat stdio bridge 与 Gateway 传输都由 Electron Main 持有渲染进程通过类型化 IPC 调用 MainAcpChatService的 fork NDJSONGatewayManager的 WebSocket扩展 IPC 贡献点主进程扩展通过类型化 IPC 注册表贡献 host-api action而不是挂载 HTTP routeelectron/main/ipc/host-invoke.ts 的registerExtensionContributions优雅恢复内置重连、超时、退避逻辑自动处理瞬时故障scheduleReconnect()、GatewayRestartGovernor、deadline probe安全存储API 密钥和敏感数据利用操作系统原生安全存储机制electron/services/secrets/secret-store.ts、electron/utils/secure-storage.tsCORS 安全渲染进程不直接请求本地 Gateway 或 Host API HTTP 端点Renderer 只走 IPC附件/文件路径由 Main 重新验证Gateway 存活恢复三分钟静默 deadline 与 system-presence 探测Gateway 的存活状态由Electron Main决定。WebSocket pong 是有价值的传输层证据但不是唯一证据。整体策略是普通传输丢失时主进程优先沿既有 Gateway WebSocket 重连路径恢复连接在三分钟没有可信存活信号后先通过system-presence验证核心 RPC 路由再决定是否替换其自身拥有的进程。设计决策表设计点处置目的将 pong、任意入站 Gateway 帧和成功 RPC 视为存活信号*刷新lastAliveAt并取消过期的 deadline callback大型 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 的思路文档脚注注明。需要说明的是这属于项目文档自行声明的设计来源并非本仓库可直接验证的实现证据。源码级实现心跳循环GatewayConnectionMonitor.startPing()以 60s 间隔发送 ping30s 无 pong 计一次 misselectron/gateway/connection-monitor.ts。静默 deadlineGatewayRecoveryController.recordAlive()每次刷新lastAliveAt并重排GATEWAY_LIVENESS_DEADLINE_MS180s的 deadlineelectron/gateway/recovery-controller.ts。控制面探测deadline 到期进入verifying状态通过回调requestDeadlineProbe()触发一次system-presenceRPC5s 超时成功则recordAlive恢复正常监控失败则按是否自管进程分流自管进程进入restart-executing触发受保护重启外部进程进入external-unavailable只做传输重连recovery-controller.ts。受保护重启GatewayRestartGovernor决定是否允许重启含冷却与熔断抑制RESTART_COOLDOWN_MS 5_000避免级联 stop/start 循环manager.ts。压缩活动宽限GATEWAY_COMPACTION_RECOVERY_GRACE_MS 5 * 60_000OpenClaw 压缩compaction期间缺少 end 诊断不能无限压制真实恢复recovery-budget.ts。进程模型与 Gateway 排障多进程是正常现象ClawX 基于 Electron单个应用实例出现多个系统进程是正常现象main/renderer/zygote/utility。这不代表应用出问题。单实例保护单实例保护同时使用Electron 自带锁与本地进程文件锁回退机制electron/main/process-instance-lock.ts可在桌面会话总线异常时避免重复启动。滚动升级注意滚动升级期间若新旧版本混跑单实例保护仍可能出现不对称行为为保证稳定性建议桌面客户端尽量统一升级到同一版本。Gateway 监听必须是单实例与「应用多进程正常」相反OpenClaw Gateway 监听应始终保持单实例127.0.0.1:18789只能有一个监听者。确认监听进程的命令macOS/Linuxlsof -nP -iTCP:18789 -sTCP:LISTENWindowsPowerShellGet-NetTCPConnection -LocalPort 18789 -State ListenGateway readiness 判定Gateway readiness 以 OpenClaw 的system-presence、health、status等核心信号为准memory 或频道失败会显示为能力降级capability degradation而不是全局 Gateway 故障。这与GatewayCapabilityMonitor将health/status/channels.status/doctor.memory.*分类为独立能力、各自记录成败的设计一致。退出行为点击窗口关闭按钮X默认只是最小化到托盘并不会完全退出应用。请在托盘菜单中选择Quit ClawX执行完整退出。托盘与退出生命周期实现可参考 electron/main/tray.ts 与 electron/main/quit-lifecycle.ts。相关文档与测试想要深入验证本文涉及的设计可以在仓库中继续阅读架构文档的其它语言版本docs/en-US/architecture.md、docs/zh-CN/architecture.md、docs/ja-JP/architecture.md开发指南docs/en-US/development.md、docs/ru-RU/development.md核心实现electron/gateway/manager.ts、electron/gateway/recovery-controller.ts、electron/gateway/connection-monitor.ts、electron/gateway/recovery-budget.ts、electron/gateway/config-sync.ts、electron/services/acp-chat-service.tsIPC 契约与注册表electron/main/ipc/host-contract.ts、electron/main/ipc/host-invoke.ts关键测试网关恢复与预算 tests/unit/gateway-recovery-budget.test.ts、tests/unit/gateway-manager-restart-recovery.test.ts、tests/unit/gateway-connection-monitor.test.ts、tests/unit/gateway-manager-heartbeat.test.ts、tests/unit/gateway-startup-recovery.test.tsACP 相关 tests/unit/acp-chat-service.test.ts、tests/unit/acp-session-access-registry.test.ts、tests/unit/acp-host-contract.test.ts架构规则文档harness/specs/rules/renderer-main-boundary.md、harness/specs/rules/gateway-heartbeat-safety.md、harness/specs/rules/gateway-readiness-policy.md、harness/specs/rules/backend-communication-boundary.md总结ClawX 通过「Renderer 单入口 Main 管控传输 Gateway 独立进程」的双进程架构把 OpenClaw 的 AI 编排能力稳定地封装进桌面体验ACP 语义权威保证了 Chat 历史的唯一事实来源三分钟存活恢复 system-presence控制面探测则在「不误杀长任务」与「及时恢复死进程」之间取得了平衡。理解这些机制是排查 Gateway 异常、评估配置热更新行为、以及扩展 host-api 服务时最重要的知识基础。赞分享人工智能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 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计ClawX 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计 ClawX 是一款为 OpenClaw AI A人工智能AI 应用桌面应用交互助手Wazuh 5.x 升级指南Manager 与 Agent 版本升级的完整操作、文件保留机制与回滚策略Wazuh 5.x 升级指南Manager 与 Agent 版本升级的完整操作、文件保留机制与回滚策略 本文基于 Wazuh 仓库的升级参考文档 docs/人工智能AI 应用桌面应用交互助手上一篇RocketMap项目Docker部署完全指南下一篇ayu-vim配色原理分析从调色板到语法高亮的完整实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ClawX 系统架构深度解析：双进程 + Host API 统一接入与 ACP 语义权威
人工智能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 是一个为 OpenClaw AI Agent 提供图形化界面的桌面应用将基于 CLI 的 AI 编排转化为无需使用终端的桌面体验。本文基于 docs/ru-RU/architecture.md以及与之同源的 docs/en-US/architecture.md、docs/zh-CN/architecture.md展开聚焦 ClawX 的双进程架构、Host API 统一接入层、ACP 语义权威、配置交付策略、Gateway 存活恢复等核心设计并结合仓库源码与测试验证每一处关键机制。读完本文你将掌握 ClawX 从「Renderer → Main → Gateway」的完整调用链、ACP 历史回放与 transcript 补充的边界、以及三分钟存活恢复策略的底层实现。架构总览双进程 Host API 统一接入ClawX 采用双进程架构 Host API 统一接入层。RendererReact 渲染进程只调用一个统一的客户端抽象而协议选择与进程生命周期由 Electron Main主进程统一管理。这意味着前端代码不感知底层是走 ACP stdio bridge、Gateway WebSocket 还是本地文件操作——所有协议细节都被隐藏在稳定的host-api/api-client接口之后。仓库中给出了完整的分层结构示意四个层次自上而下┌──────────────────────────────────────────────────────────────────┐ │ ClawX 桌面应用 │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Electron 主进程 │ │ │ │ • 窗口与应用生命周期管理 │ │ │ │ • 网关进程监控 │ │ │ │ • 系统集成托盘、通知、密钥链 │ │ │ │ • 自动更新编排 │ │ │ └──────────────────────────────────────────────┬────────────────┘ │ │ │ IPC (权威控制面) │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ React 渲染进程 │ │ │ │ • 现代组件化 UIReact 19 │ │ │ │ • Zustand 状态管理 │ │ │ │ • 统一 host-api/api-client 调用 │ │ │ │ • 回复使用 Markdown用户输入按原文显示 │ │ │ └──────────────────────────────────────────────┬────────────────┘ │ │ │ 类型化 IPC 请求 │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 主进程 Host Services 与 Gateway Manager │ │ │ │ • host:invoke 类型化服务分发 │ │ │ │ • 设置、文件、会话、技能、供应商、诊断服务 │ │ │ │ • 主进程持有 Gateway WebSocket 并负责进程监控 │ │ │ └──────────────────────────────────────────────┬────────────────┘ │ │ │ 主进程持有 WebSocket│ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ OpenClaw 网关 │ │ │ │ • AI 智能体运行时与编排 │ │ │ │ • 消息频道管理 │ │ │ │ • 技能/插件执行环境 │ │ │ │ • 供应商抽象层 │ │ │ └─────────────────────────────────────────────────────────────┘ │各层职责可以归纳如下Electron Main窗口与应用生命周期管理、Gateway 进程监督electron/gateway/manager.ts 中的GatewayManager是核心实现、系统集成托盘、通知、密钥链、自动更新编排。React Renderer现代组件化 UIReact 19、Zustand 状态管理、统一host-api/api-client调用、Markdown 回复与原文用户输入。Main Host Services 与 Gateway Manager通过host:invoke提供类型化服务分发覆盖设置、文件、会话、技能、供应商、诊断等服务Gateway WebSocket 与进程监督归 Main 所有。OpenClaw GatewayAI 智能体运行时与编排、消息频道管理、技能/插件执行环境、供应商抽象层运行在独立进程中。主进程的职责边界从源码看主进程的核心类GatewayManagerelectron/gateway/manager.ts负责Gateway 生命周期start()、stop()、restart()、debouncedRestart()等状态机由GatewayStateController维护stopped/starting/running/error等。WebSocket 通信通过rpc()方法按 OpenClaw 协议格式{ type: req, id, method, params }发送请求manager.ts。健康检查checkHealth()并行调用health与statusRPCcheckTransportHealth()只检查 WebSocket 是否 OPENOpenClaw Gateway 没有 HTTP /health 端点。能力监控GatewayCapabilityMonitor将health、status、channels.status、doctor.memory.*等 RPC 分类为不同能力记录成功/失败classifyCapabilityMethodmanager.ts。RPC 路由判定isCoreRpcMethod把system-presence视为核心读 RPCmanager.ts。Renderer 与 Main 的类型化 IPCRenderer 不直接调用本地 HTTP 端点而是通过类型化 IPC 请求 Main。IPC 契约定义在 electron/main/ipc/host-contract.ts请求形如{ id, module, action, payload }响应为{ ok: true, data }或{ ok: false, error: { code, message } }错误码分为VALIDATION/UNSUPPORTED/INTERNAL。服务注册与分发由 electron/main/ipc/host-invoke.ts 中的HostApiRegistry完成核心服务通过registerCoreServices()注册主进程扩展则通过registerExtensionContributions()以(extensionId, contributions) () void的形式贡献 host-api action——这与文档中的「扩展 IPC 贡献点」设计原则一一对应。OpenClaw 配置交付config.get / config.set 与 JSON5 协调OpenClaw 配置交付同样由 Electron Main 统一管理核心策略是「按 Gateway 运行状态选择写入路径」Gateway 运行中以config.get返回的权威快照为基线通过config.set提交修改。Gateway 停止或启动中同一个协调器只更新解析后的 JSON5 配置文件即 OpenClaw 的openclaw.json不会因此启动 Gateway。这一策略的直接收益是普通的 Provider、Agent、Channel、绑定、Skill 和模型修改不会替换 Gateway 进程。完整重启只保留给两类场景进程启动环境的变化如代理 proxy 设置用户的显式操作。配套实现位于 electron/gateway/config-sync.ts 的syncGatewayConfigBeforeLaunch()每次 Gateway 启动前会执行代理同步syncProxyConfigToOpenClaw、配置消毒sanitizeOpenClawConfig、频道插件自动升级/清理、DingTalk dws 预置、Gateway token 批量同步batchSyncConfigFields等预启动维护任务并利用runCachedPrelaunchMaintenanceTask缓存签名避免重复开销。认证配置热更新secrets.reload文档强调认证配置写入 SQLite 后ClawX 会调用 OpenClaw 的secrets.reload让运行中的 Agent 无需重启即可读取新凭据。这意味着你在设置页保存 Provider API Key 后正在运行的 Agent 会话不会被打断新凭据通过 reload 机制即时生效。心跳与自动恢复配置变更虽然不会触发重启但 Gateway 自身的健康状态由主进程持续监控心跳参数GATEWAY_HEARTBEAT_INTERVAL_MS 60_000发送间隔 60s、GATEWAY_HEARTBEAT_TIMEOUT_MS 30_000等待超时 30s、GATEWAY_HEARTBEAT_MAX_MISSES 4最大连续漏跳 4 次、GATEWAY_LIVENESS_DEADLINE_MS 180_000三分钟存活静默 deadline、GATEWAY_CONTROL_PROBE_TIMEOUT_MS 5_000控制面探测超时 5s全部定义在 electron/gateway/recovery-budget.ts。前三跳只诊断连续前 3 次 WebSocket 心跳无响应只更新诊断计数consecutiveHeartbeatMisses不会因短暂的 pong 延迟中断长时间运行的任务例如大型 Skill 或工具调用天然会延迟 pong。收到 pong 或任意入站消息会重置计数markAlive(pong | message)将consecutiveMisses归零并重新安排 deadlineelectron/gateway/connection-monitor.ts。第四次漏跳仅当生命周期处于可自动恢复的 running 状态时才请求受保护的 Gateway 自动恢复。已确认的退出与重连路径已确认的进程退出与WebSocket close继续使用现有的自动重连路径scheduleReconnect()。code 1012 reloadGateway 在进程内重启如 code 1012后Main 检测到仍持有该进程的所有权时会保留 ownership并记录一次 restart 完成避免多余的 killrespawnmanager.ts。ACP 语义权威Chat 的唯一事实来源什么是 ACP 语义权威ACPAgent Client Protocol是 ClawX 中每个 Chat 语义和上下文的优先权威来源而不仅是session/load的历史来源。适用场景包括session identity 与路由适用时工作空间与执行cwdprompt 与 timeline 状态标准 resource 或附件语义。当 ACP 提供某个值或事件时Main 和 Renderer 必须使用 ACP 的结果不得用以下替代品替换Gateway 快照transcript 推断本地配置另一套并行投影。绕过 ACP 的严格条件只有在上游 ACP没有对应能力时才允许绕过 ACP。此类兼容性路径必须满足保持狭窄、有界绑定session 和 generation在相关 Harness reference 或 rule 中记录原因rationale、事实来源source of truth、限制limits、协调行为reconciliation behavior、移除条件removal condition。它不得悄悄演变为竞争性的权威来源。ClawX 只在「有界、带标记、仅存于内存」的范围内维护兼容性补充见下文。prompt 压力恢复补丁后的 OpenClaw 会在提交给 Provider 之前执行 prompt 压力恢复。当聚合工具结果文本超过「扣除预留后的 prompt 预算」时根据实测溢出量 安全缓冲推导一个统一的截断目标truncation target该目标在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 只保留有界、带标记、仅存于内存的兼容性补充路径bounded transcript supplements。已结算回合的 replay hydration这是文档中最重要的运行时流程描述了「prompt 完成后如何把历史回放合并进可见 timeline」即时更新ACP prompt 运行期间session/update通知会继续即时更新可见 timeline。无固定 sleepRenderer 等待类型化的session/prompt调用完成并且只在其成功返回后立即对同一 session 发起一次session/load两个操作之间没有固定 sleep。有效性守卫只有 session、generation、workspace 和 Renderer load request 仍然有效时才开始 hydration。串行与缓冲Main 会在共享 ACP connection 上串行执行 load分配下一代 routing generation在上游session/load完成前缓冲replay notifications并随 load 结果一起返回原始 batch。无空白 loadingload 进行期间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 不匹配被丢弃。源码佐证AcpChatService.performLoadSession()中的resumed-active-prompt分支electron/services/acp-chat-service.ts与loadSession()的串行队列acp-chat-service.ts完整实现了上述语义sendPrompt()则实现了 session 未加载、prompt 重复激活、cwd 不匹配等守卫acp-chat-service.ts。因果结算屏障为什么不用固定延迟session/prompt成功完成就是这个流程的因果结算屏障causal settlement barrier。文档明确解释了为什么不该用无条件延迟无条件延迟只会——增加回复结算耗时让 sending 状态维持更久扩大 navigation 或其它 load 使本次 hydration 过期的窗口而它并不能证明上游持久化已经完成。如果未来确认某个上游实现在 replay 可用前就返回 prompt success正确的补救是在相同 identity guards下针对空 replay 或缺失当前回合做有界、条件式重试而不是加入固定延迟。注意下文提到的1500 ms 重试只属于有界 transcript 兼容补充不是 ACP replay hydration 的一部分。有界 transcript 补充的边界历史读取最多读取最近 1000 条 transcript 消息一次成功的实时 prompt 会立即读取一次并在1500 ms 后重试一次。每类补充都有严格边界补充类型恢复条件边界异步图像生成结果同一 session 存在已确认的image_generate上下文且完成证据可信或来自获准 transcript 证据只恢复结果本身普通附件持久化的 assistant__openclaw.media规范事实或明确的行首 assistantMEDIA:指令只恢复附件引用和声明的元数据不恢复周围的 assistant 消息整轮耗时ACP 回放不提供原始事件时间戳Main 从有界的 transcript JSONL 记录中补充仅含元数据的整轮耗时只能标注已经由 ACP 回放恢复出的回合cron 会话历史cron session 的 ACP 回放完全为空时Main 的类型化 cron-history API 提供计划提示词和完成摘要仅当对应 run 的 transcript 更长且共享完整的已持久化摘要前缀时才可恢复最终 assistant 文本每个补充路径都必须绑定精确的 session、ACP generation、补充操作并在适用时绑定当前用户回合过期、缺失、重复或有歧义的匹配都会被丢弃。禁止事项这些路径不得做重建普通 assistant 消息、thought、tool、plan、permission重建文件活动、缺失回合或另一套 Chat 历史Main 根据 transcript伪造原生 ACP 事件。标准 ACP resource 仍是首选上游提供等价内容后这些兼容性例外应当移除。未完成回复的流式行为打开其它会话或页面时尚未完成的 ACP 回复仍会继续流式接收。若在回复完成前返回ClawX 会恢复最新的内存 timeline 并继续显示实时输出回复完成后普通 ACP 历史回放仍是唯一事实来源。整轮耗时whole-turn timingACP assistant 回合会显示整轮耗时Live 计时跟随客户端观测到的 prompt 生命周期并在应用内导航后保持连续历史耗时由 Electron Main 根据有界的 OpenClaw transcript 时间戳计算而且只能标注 ACP 回放已经恢复出的回合。附件、文件活动与 Office 预览语义附件渲染ACP Chat 将标准 ACP resource渲染为附件。用户选择的图片显示为缩略图悬停蒙层显示文件名其它附件卡片显示文件名与灰色、可截断的来源路径。当 OpenClaw ACP adapter 遗漏 assistant 媒体时__openclaw.media规范事实和显式MEDIA:指令可恢复为附件卡片且不显示仅用于 transcript 的元数据。路径重新验证现有本地文件引用包括当前 workspace 外的路径在每次预览或打开前都由 Electron Main 按精确的 session 和 generation 重新验证——这是 CORS 安全原则的延伸Renderer 不做任意文件系统访问。Office 与 HTML 附件可预览的本地附件AI 生成且可预览的本地附件包括不超过20 MB的.docx和.pptx保留主要的只读应用内预览操作并提供次级菜单通过兼容应用打开或在 Finder / 文件资源管理器 / 系统文件管理器中显示。HTML 附件菜单第一项在右侧Preview标签页中打开文件。Office 限制.doc和.ppt仍通过系统应用打开DOCX 分页可能与 Microsoft Word 不同PPTX 的动画、切换效果和媒体播放不受支持。兼容应用发现仅在 macOS 和 Windows 可用Linux 上或发现失败时静默降级为仅显示文件位置。其它本地文件包括超过 20 MB 的 Office 文件在用户点击后通过系统应用打开。文件夹附件用户选择的文件夹在发送后保持可用点击后交给系统文件管理器打开ClawX 不会读取或预览其中内容。远程 HTTP/HTTPS 附件用户点击后从外部打开。裸路径没有规范媒体事实佐证的普通文本裸路径或行内路径不会被当作附件。生成图片预览当 runtime 以可信结构化媒体投递图像生成结果时ACP Chat 可显示生成图片预览可信的 OpenClaw internal-UI 投递和与生图任务关联的最终回复保留原始的用户可见完成文案包括只有文本的失败说明不统一替换成通用图片文案历史回放中assistant 的图片MEDIA:标记只有在同一会话已记录图像生成任务启动后才进入内联图片体验ClawX 通过 Electron Main 的主机媒体处理加载预览不是Renderer 任意文件系统访问标准 ACP 图片和 resource 内容仍是首选路径并直接渲染。ACP 文件活动语义文件活动由成功且已完成的 OpenClawwrite、edit、apply_patch调用投影而来工具识别方式与 OpenClaw 官方 Chat UI 保持一致「仅接收已完成调用」的筛选规则是 ClawX 特有的。已创建/已修改的活动行与可预览的 assistant 附件共用同一种文件卡片外壳和「打开方式」菜单同时保留状态文字与可选的/-统计。HTML 文件菜单第一项在右侧Preview标签页打开已删除的行只保留Changes操作。独立重新验证应用列表、指定应用打开、显示文件位置都由 Electron Main 根据 workspace 根目录与相对路径分别重新验证工具路径不会变成附件Renderer 也不会获得规范化系统路径。write语义按工具声明的语义显示——视为创建展示为全部新增的 diff即使该路径可能已存在。Changes 不是 Git 输出它是按时间顺序记录工具声明活动的会话级记录不是 Git 输出也不是相对已验证源码基线的差异。每文件每回合最多一个 diff 编辑器可安全串联的片段会合并独立片段拼接到同一个编辑器但不会被描述为基于完整文件基线的差异。不检测副作用Shell 命令、脚本、用户或 IDE 产生的副作用不会被检测。完整回放可恢复完整的 ACP 回放可以恢复已记录的文件活动如果回放不完整ClawX不会通过回退推断补造缺失活动。ACP stdio bridge认证、恢复 run 与 agent.wait 结算Main 持有的 ACP 子进程Chat 使用由Electron Main 持有的 ACP stdio bridge。AcpChatServiceelectron/services/acp-chat-service.ts通过fork()启动openclaw acp子进程并通过 NDJSON 流与agentclientprotocol/sdk的ClientSideConnection通信。两个关键实现细节Token 注入Main 通过私有进程环境把OPENCLAW_GATEWAY_TOKEN传给本地子进程acp-chat-service.ts因此运行时配置重载后 ACP 历史回放仍能完成认证。stdout 诊断过滤OpenClaw 启动时可能向 stdout 输出 clack/doctor 诊断文本filterAcpStdoutDiagnostics会把非 JSON 行挡在 SDK 严格的 NDJSON 解析器之外acp-chat-service.ts。恢复 run 与 lineage如果受保护的 Gateway 恢复中断了已接收的主会话 run补丁后的 OpenClaw 运行时会启动独立的恢复 run并显式携带直接被中断的 run id 作为 lineage。Chat 和 agent events 会保留该 lineage重连后的 ACP bridge 据此逐次将 pending prompt 接续到新 run重置该 run 的流式游标订阅会话级 tool events。agent.wait 结算如果之后的重启在答复持久化后丢失了进程内终态通知ACP 会把当前 run id 和 session key 传给agent.waitGateway 仅在持久化 lifecycle owner 与该 run 匹配时结算。这保证了「答复已写入持久化存储但进程内终态丢失」时主进程不会误判任务未完成。Renderer 的无身份视角Renderer 不感知 Gateway 运行实例身份仍通过类型化 host events 渲染同一个内存 ACP timeline。这意味着 Gateway 的进程替换、run 恢复、token 重载对前端完全透明。Gateway 继续负责 providers、models、skills、workspace、settings、diagnostics 和 media configuration 等非 Chat 能力。设计原则文档列出的七条设计原则与源码一一对应原则含义源码佐证进程隔离AI 运行时在独立进程中运行即使高负载计算期间 UI 也保持响应GatewayManager通过Electron.UtilityProcess/ 子进程启动 Gateway前端调用单一入口渲染层统一走 host-api/api-client不感知底层协议细节electron/main/ipc/host-contract.ts 的类型化请求/响应契约主进程掌控传输策略ACP Chat stdio bridge 与 Gateway 传输都由 Electron Main 持有渲染进程通过类型化 IPC 调用 MainAcpChatService的 fork NDJSONGatewayManager的 WebSocket扩展 IPC 贡献点主进程扩展通过类型化 IPC 注册表贡献 host-api action而不是挂载 HTTP routeelectron/main/ipc/host-invoke.ts 的registerExtensionContributions优雅恢复内置重连、超时、退避逻辑自动处理瞬时故障scheduleReconnect()、GatewayRestartGovernor、deadline probe安全存储API 密钥和敏感数据利用操作系统原生安全存储机制electron/services/secrets/secret-store.ts、electron/utils/secure-storage.tsCORS 安全渲染进程不直接请求本地 Gateway 或 Host API HTTP 端点Renderer 只走 IPC附件/文件路径由 Main 重新验证Gateway 存活恢复三分钟静默 deadline 与 system-presence 探测Gateway 的存活状态由Electron Main决定。WebSocket pong 是有价值的传输层证据但不是唯一证据。整体策略是普通传输丢失时主进程优先沿既有 Gateway WebSocket 重连路径恢复连接在三分钟没有可信存活信号后先通过system-presence验证核心 RPC 路由再决定是否替换其自身拥有的进程。设计决策表设计点处置目的将 pong、任意入站 Gateway 帧和成功 RPC 视为存活信号*刷新lastAliveAt并取消过期的 deadline callback大型 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 的思路文档脚注注明。需要说明的是这属于项目文档自行声明的设计来源并非本仓库可直接验证的实现证据。源码级实现心跳循环GatewayConnectionMonitor.startPing()以 60s 间隔发送 ping30s 无 pong 计一次 misselectron/gateway/connection-monitor.ts。静默 deadlineGatewayRecoveryController.recordAlive()每次刷新lastAliveAt并重排GATEWAY_LIVENESS_DEADLINE_MS180s的 deadlineelectron/gateway/recovery-controller.ts。控制面探测deadline 到期进入verifying状态通过回调requestDeadlineProbe()触发一次system-presenceRPC5s 超时成功则recordAlive恢复正常监控失败则按是否自管进程分流自管进程进入restart-executing触发受保护重启外部进程进入external-unavailable只做传输重连recovery-controller.ts。受保护重启GatewayRestartGovernor决定是否允许重启含冷却与熔断抑制RESTART_COOLDOWN_MS 5_000避免级联 stop/start 循环manager.ts。压缩活动宽限GATEWAY_COMPACTION_RECOVERY_GRACE_MS 5 * 60_000OpenClaw 压缩compaction期间缺少 end 诊断不能无限压制真实恢复recovery-budget.ts。进程模型与 Gateway 排障多进程是正常现象ClawX 基于 Electron单个应用实例出现多个系统进程是正常现象main/renderer/zygote/utility。这不代表应用出问题。单实例保护单实例保护同时使用Electron 自带锁与本地进程文件锁回退机制electron/main/process-instance-lock.ts可在桌面会话总线异常时避免重复启动。滚动升级注意滚动升级期间若新旧版本混跑单实例保护仍可能出现不对称行为为保证稳定性建议桌面客户端尽量统一升级到同一版本。Gateway 监听必须是单实例与「应用多进程正常」相反OpenClaw Gateway 监听应始终保持单实例127.0.0.1:18789只能有一个监听者。确认监听进程的命令macOS/Linuxlsof -nP -iTCP:18789 -sTCP:LISTENWindowsPowerShellGet-NetTCPConnection -LocalPort 18789 -State ListenGateway readiness 判定Gateway readiness 以 OpenClaw 的system-presence、health、status等核心信号为准memory 或频道失败会显示为能力降级capability degradation而不是全局 Gateway 故障。这与GatewayCapabilityMonitor将health/status/channels.status/doctor.memory.*分类为独立能力、各自记录成败的设计一致。退出行为点击窗口关闭按钮X默认只是最小化到托盘并不会完全退出应用。请在托盘菜单中选择Quit ClawX执行完整退出。托盘与退出生命周期实现可参考 electron/main/tray.ts 与 electron/main/quit-lifecycle.ts。相关文档与测试想要深入验证本文涉及的设计可以在仓库中继续阅读架构文档的其它语言版本docs/en-US/architecture.md、docs/zh-CN/architecture.md、docs/ja-JP/architecture.md开发指南docs/en-US/development.md、docs/ru-RU/development.md核心实现electron/gateway/manager.ts、electron/gateway/recovery-controller.ts、electron/gateway/connection-monitor.ts、electron/gateway/recovery-budget.ts、electron/gateway/config-sync.ts、electron/services/acp-chat-service.tsIPC 契约与注册表electron/main/ipc/host-contract.ts、electron/main/ipc/host-invoke.ts关键测试网关恢复与预算 tests/unit/gateway-recovery-budget.test.ts、tests/unit/gateway-manager-restart-recovery.test.ts、tests/unit/gateway-connection-monitor.test.ts、tests/unit/gateway-manager-heartbeat.test.ts、tests/unit/gateway-startup-recovery.test.tsACP 相关 tests/unit/acp-chat-service.test.ts、tests/unit/acp-session-access-registry.test.ts、tests/unit/acp-host-contract.test.ts架构规则文档harness/specs/rules/renderer-main-boundary.md、harness/specs/rules/gateway-heartbeat-safety.md、harness/specs/rules/gateway-readiness-policy.md、harness/specs/rules/backend-communication-boundary.md总结ClawX 通过「Renderer 单入口 Main 管控传输 Gateway 独立进程」的双进程架构把 OpenClaw 的 AI 编排能力稳定地封装进桌面体验ACP 语义权威保证了 Chat 历史的唯一事实来源三分钟存活恢复 system-presence控制面探测则在「不误杀长任务」与「及时恢复死进程」之间取得了平衡。理解这些机制是排查 Gateway 异常、评估配置热更新行为、以及扩展 host-api 服务时最重要的知识基础。赞分享人工智能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 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计ClawX 架构深度解析基于 OpenClaw 的双进程桌面 AI Agent 网关与 ACP 语义权威设计 ClawX 是一款为 OpenClaw AI A人工智能AI 应用桌面应用交互助手Wazuh 5.x 升级指南Manager 与 Agent 版本升级的完整操作、文件保留机制与回滚策略Wazuh 5.x 升级指南Manager 与 Agent 版本升级的完整操作、文件保留机制与回滚策略 本文基于 Wazuh 仓库的升级参考文档 docs/人工智能AI 应用桌面应用交互助手上一篇RocketMap项目Docker部署完全指南下一篇ayu-vim配色原理分析从调色板到语法高亮的完整实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考