Web UI 架构 —— OpenClaw 如何实现与 CLI/WhatsApp 一致的交互体验

关键词：ACP 协议｜状态同步｜响应式 UI｜多端一致性｜WebSocket｜会话复用

在多渠道 AI 系统中，一个常见陷阱是：不同客户端体验割裂。用户在 WhatsApp 上能执行的操作，在 Web UI 中却不可用；CLI 输出的工具调用日志，在网页上却看不到——这不仅降低效率，更破坏信任。

OpenClaw 的核心原则之一是：无论用户从哪个入口接入，AI 的能力、上下文与行为必须完全一致。为此，其 Web UI 并非独立前端，而是 ACP（Agent Communication Protocol）。

本文将详解 OpenClaw Web UI 的三大支柱：

1. 统一通信协议（ACP）—— 所有渠道的“通用语言”
2. 响应式状态树—— 实时同步会话全貌
3. 多端组件抽象—— 一套逻辑，多端渲染

一、问题根源：为什么多端体验容易不一致？

OpenClaw 的解法是：彻底解耦“通信”与“呈现”。

二、核心基石：ACP 协议 —— 所有渠道的通用语言

ACP（Agent Communication Protocol）是一个基于 JSON-RPC 2.0 的双向事件协议，定义了智能体与客户端之间的标准化消息格式。

关键特性

• 双向通信：支持请求（request）、响应（response）和通知（notification）
• 类型安全：每条消息有明确 method 和结构化 params
• 无渠道感知：协议本身不知道客户端是 Web、WhatsApp 还是 CLI

典型 ACP 消息示例

1. 用户发送消息（所有渠道相同）

{
  "jsonrpc": "2.0",
  "method": "chat.sendMessage",
  "params": {
    "sessionKey": "wa:+1234567890",
    "content": "重启数据库"
  }
}

2. AI 返回工具调用（结构化，非文本）

{
  "jsonrpc": "2.0",
  "method": "tool.call.request",
  "params": {
    "toolId": "bash_exec",
    "args": { "cmd": "kubectl rollout restart deployment/db" },
    "requiresApproval": true,
    "host": "gateway"
  }
}

3. 客户端审批（跨渠道通用）

{
  "jsonrpc": "2.0",
  "method": "tool.call.approve",
  "params": { "requestId": "req_abc123" }
}

所有渠道使用同一套消息语义，后端无需区分来源。

三、Web UI 架构：基于 ACP 的响应式前端

OpenClaw Web UI 采用 SvelteKit + Vite 构建，但其核心不是框架，而是状态驱动架构。

整体数据流

1. 会话状态树（Session State Tree）

每个 sessionKey 对应一棵响应式状态树：

// stores/sessionStore.ts
const sessionState = writable({
  messages: [],
  activeTools: new Map(),      // 当前待审批/运行的工具
  backgroundTasks: [],         // 后台任务列表
  managedProcesses: [],        // 受管进程状态
  inputDisabled: false         // 是否等待 AI 响应
});

• 所有 ACP 通知（如 tool.call.request、process.log）直接更新此树
• UI 组件通过 $sessionState 自动响应变化

2. 组件抽象：渠道无关渲染

• 消息气泡：根据 message.role 渲染用户/AI/工具消息
• 工具卡片：统一展示 tool.call.request，含“批准/拒绝”按钮
• 进程面板：实时显示 managedProcesses 状态（运行/崩溃/日志）

UI 是状态的投影，而非消息的直译。

四、多端一致性实现细节

1. 会话复用

• Web UI 使用与 WhatsApp 相同的 sessionKey（如 wa:+1234567890）
• 所有历史消息、进行中的工具调用、后台任务均来自同一持久化源（sessions/xxx.jsonl）
• 用户在手机上批准命令，网页端立即更新状态

2. 输入一致性

• Web 输入框、CLI stdin、WhatsApp 消息 → 均转为 chat.sendMessage
• 支持 /command 快捷指令（如 /task list），各端行为一致

3. 输出一致性

• AI 的思考过程（/think ...）在 Web 显示为折叠区块，在 CLI 显示为灰色文本，在 WhatsApp 显示为“AI 正在思考...”
• 工具输出（如 kubectl 日志）在所有端以等宽字体+滚动容器呈现

体验一致，形式自适应。

五、性能优化：低延迟与离线支持

1. 本地回显（Optimistic UI）

• 用户发送消息后，立即在 UI 显示（不等服务器确认）
• 若 ACP 返回错误，再撤回并提示

2. 消息压缩与批处理

• WebSocket 启用 permessage-deflate
• 高频日志（如 process.log）在前端做 100ms 节流合并

3. 离线缓存

• 使用 IndexedDB 缓存最近 10 个会话
• 重连后自动同步增量消息

即使在网络波动下，体验依然流畅。

六、安全与权限：Web 不是特权通道

Web UI 不享有额外权限：

• 所有高危操作（如 gateway 命令）仍需审批
• 审批按钮点击后，发送标准 ACP tool.call.approve，与 WhatsApp 行为一致
• 无法绕过 allowedPaths 或 elevatedWhitelist

Web 只是另一个客户端，不是后门。

七、开发体验：热重载与调试工具

OpenClaw Web UI 内置开发者工具：

• ACP Inspector：实时查看所有进出消息
• Session Switcher：快速切换不同 sessionKey
• Mock Mode：模拟 WhatsApp/CLI 行为

<!-- DevTools.svelte -->
{#if devMode}
  <div class="acp-inspector">
    {#each acpLog as msg}
      <pre>{JSON.stringify(msg, null, 2)}</pre>
    {/each}
  </div>
{/if}

让前端开发者也能理解 AI 的“内心活动”。

八、对比：传统多端 vs OpenClaw 多端

结语：一致性是尊重用户的表现

OpenClaw 的 Web UI 架构证明：多端体验的一致性并非技术难题，而是设计选择。通过 ACP 协议将“通信”标准化，通过状态树将“呈现”解耦，系统得以在任意渠道提供同等能力、同等上下文、同等控制权的体验。

这不仅是工程优雅，更是对用户时间与认知的尊重——无论你在哪里，AI 都记得你是谁，做过什么，需要什么。

在下一篇中，我们将探讨 OpenClaw 的部署模型：如何从单机运行到 Kubernetes 集群。

下一篇预告：
第 15 篇：部署模型演进 —— 从单机 Docker 到 Kubernetes Operator