OpenClaw 客户端层分析

文档版本：2026.2.26　　最后更新：2026-02-26

openclaw版本：v2026.2.25

1. 层概述

职责: 为用户提供多种访问 OpenClaw 系统的入口和交互界面

定位: 系统的最外层，直接面向终端用户

交互协议: 通过 WebSocket/HTTP 与 Gateway 控制平面通信

2. 主要组件

2.1 CLI 工具

路径 : src/cli/, src/commands/, openclaw.mjs

职责:

提供命令行接口
管理 Gateway 生命周期
执行系统管理任务
与 AI 代理交互

关键命令:

bash 复制代码

openclaw gateway run      # 启动 Gateway
openclaw agent            # AI 代理交互
openclaw message send     # 发送消息
openclaw channels status  # 渠道状态
openclaw config          # 配置管理
openclaw onboard         # 引导向导
openclaw doctor          # 诊断工具
openclaw pairing         # 配对管理

技术实现:

框架: Commander.js
交互提示: @clack/prompts
进度显示: osc-progress
颜色输出: chalk
伪终端: @lydell/node-pty

2.2 macOS 菜单栏应用

路径 : apps/macos/

系统角色：双重身份 --- Gateway 宿主 + Node

macOS 应用在整个系统中具有唯一的双重角色，是系统的"核心枢纽设备"。

less 复制代码

macOS 设备
  ├── 角色 A: Gateway 宿主 (可选，本地模式)
  │     └── 运行 Gateway 服务器进程，系统中枢
  └── 角色 B: Node (始终运行)
        └── 作为节点连接到 Gateway，提供设备能力

连接模式 (由配置 gateway.mode 决定):

local --- macOS 本机运行 Gateway 服务器，同时自身也作为 Node 接入，本机独立运行一套完整系统
remote --- macOS 连接到远程 Gateway (VPS / Pi 等)，仅作为 Node 提供能力；通过 Tailscale/SSH 隧道打通

关键代码: ConnectionModeCoordinator 负责切换模式，MacNodeModeCoordinator 负责 Node 会话生命周期，MenuBar.swift 在菜单栏就绪时启动 Node (MacNodeModeCoordinator.shared.start())。

macOS Node 能力 (`currentCaps`)

能力	说明	默认状态
`canvas`	AI 可视化界面渲染（独立 Canvas 窗口，支持 A2UI）	始终开启
`screen`	屏幕录制	始终开启
`camera`	摄像头拍照/录视频	可配置开启
`location`	GPS/网络定位	可配置开启

macOS Node 声明的 commands（命令）:

Canvas: canvas.present, canvas.hide, canvas.navigate, canvas.evalJS, canvas.snapshot

A2UI: canvas.a2ui.push, canvas.a2ui.pushJSONL, canvas.a2ui.reset

屏幕: screen.record

系统: system.notify, system.which, system.run (仅 macOS 独有)

执行审批: exec.approvals.get, exec.approvals.set (仅 macOS 独有)

摄像头 (可选): camera.list, camera.snap, camera.clip

位置 (可选): location.get

macOS 专有能力（非 Node 协议层）

功能	描述
Voice Wake	全局语音唤醒，检测唤醒词后转录并通过 `VoiceWakeForwarder` 发送给 AI Agent
Talk Mode	双工语音对话模式（`TalkModeController` + `TalkModeRuntime`）
Shell 命令执行	`system.run` / `system.which` + `ExecApprovals` 安全审批机制
Cron 任务调度	内置 Cron 编辑器，定时触发 Agent 任务
Peekaboo 自动化	macOS UI 自动化框架 (`PeekabooBridgeHostCoordinator`)，支持截图/UI 操控
Tailscale 集成	通过 `TailscaleService` 建立加密隧道连接远程 Gateway
多实例管理	`InstancesStore` 管理多个 Agent 实例
Agent 事件监控	`AgentEventStore` / `AgentEventsWindow` 可视化查看 Agent 运行事件
WebChat 嵌入	`WebChatManager` 嵌入浏览器对话界面
CLI 安装管理	`CLIInstaller` 安装和管理命令行工具
使用量/费用统计	`UsageCostData` / `CostUsageMenuView` 显示 AI 调用费用

应用场景（macOS）

家庭/个人 AI 中枢：macOS（本地模式）是整个多设备系统的核心，所有 iOS/Android 设备通过它接入
远程工作流自动化 ：通过 system.run 在 Mac 上执行脚本，配合 Cron 任务实现无人值守自动化
语音控制电脑：Voice Wake + macOS 命令执行，说话即可操作电脑、查询文件、运行程序
AI 配合桌面 UI 操作：Peekaboo 桥接实现 AI 截屏分析、自动点击界面元素
Canvas 可视化展示：AI 生成图表、仪表盘、交互式 UI，实时投屏于 macOS 桌面窗口
多设备协调节点：macOS 作为远程 Gateway 的 Node，同时为其他移动设备提供 macOS 算力和界面

技术实现:

语言: Swift
框架: SwiftUI + AppKit
协议: OpenClawKit (Swift Package)
网络: WebSocket + Bonjour (mDNS)
UI: NSStatusBar + NSWindow

关键文件:

bash 复制代码

apps/macos/Sources/OpenClaw/
├── AppState.swift                    # 应用全局状态
├── ConnectionModeCoordinator.swift   # 本地/远程模式切换
├── GatewayProcessManager.swift       # Gateway 进程管理（本地模式）
├── GatewayConnection.swift           # Gateway 连接
├── MenuBar.swift                     # 菜单栏逻辑（启动 Node）
├── NodeMode/
│   ├── MacNodeModeCoordinator.swift  # Node 会话生命周期
│   ├── MacNodeRuntime.swift          # Node 命令处理
│   └── MacNodeScreenCommands.swift   # 屏幕录制命令
├── VoiceWakeForwarder.swift          # 语音唤醒转发
├── VoiceWakeRuntime.swift            # 语音唤醒运行时
├── TalkModeController.swift          # Talk Mode 控制
├── PeekabooBridgeHostCoordinator.swift # macOS UI 自动化
├── CronSettings.swift                # Cron 任务管理
├── CanvasWindowController.swift      # Canvas 窗口
└── TailscaleService.swift            # Tailscale 隧道

2.3 iOS 节点应用

路径 : apps/ios/

系统角色：纯 Node --- 移动传感器与个人数据枢纽

iOS 应用在系统中扮演纯 Node 角色 （不托管 Gateway），是系统的"移动感知节点"。相比 macOS Node，iOS Node 拥有更丰富的移动端传感器与个人数据能力。

bash 复制代码

iOS 设备
  └── 角色: Node（仅此一种）
        ├── 通过 Bonjour/mDNS 发现局域网 Gateway
        ├── 或手动配置远程 Gateway 地址
        └── 建立 WebSocket 连接，声明能力注册

UI 入口: 三个 Tab --- Screen （Canvas 展示）、Voice （语音交互）、Settings（设置）

iOS Node 能力 (`currentCaps`)

能力	说明	默认状态
`canvas`	AI 可视化界面渲染	始终开启
`screen`	屏幕录制	始终开启
`device`	设备状态与硬件信息	始终开启
`photos`	相册访问（最新照片）	始终开启
`contacts`	联系人读写	始终开启
`calendar`	日历事件读写	始终开启
`reminders`	提醒事项读写	始终开启
`camera`	摄像头拍照/录像	默认开启（可关闭）
`voiceWake`	语音唤醒	需手动开启
`location`	GPS/网络定位	需手动开启
`watch`	Apple Watch 通讯	设备支持时自动开启
`motion`	计步器 & 活动识别	设备支持时自动开启

iOS Node 声明的 commands（命令）:

Canvas: canvas.present, canvas.hide, canvas.navigate, canvas.evalJS, canvas.snapshot

A2UI: canvas.a2ui.push, canvas.a2ui.pushJSONL, canvas.a2ui.reset

屏幕: screen.record

系统: system.notify

聊天: chat.push

PTT 语音: talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, talk.ptt.once

摄像头: camera.list, camera.snap, camera.clip

位置: location.get

设备: device.status, device.info

Apple Watch: watch.status, watch.notify

相册: photos.latest

联系人: contacts.search, contacts.add

日历: calendar.events, calendar.add

提醒: reminders.list, reminders.add

运动: motion.activity, motion.pedometer

iOS 独有能力（与 macOS Node 对比）

能力	iOS	macOS Node
联系人读写	✅ `contacts.search` / `contacts.add`	❌
日历读写	✅ `calendar.events` / `calendar.add`	❌
提醒事项	✅ `reminders.list` / `reminders.add`	❌
相册访问	✅ `photos.latest`	❌
计步/活动识别	✅ `motion.activity` / `motion.pedometer`	❌
Apple Watch	✅ `watch.status` / `watch.notify`	❌
设备详情	✅ `device.status` / `device.info`	❌
PTT 语音对话	✅ `talk.ptt.*`	❌
Shell 命令执行	❌	✅ `system.run`
执行审批	❌	✅ `exec.approvals.*`
Cron 任务	❌	✅ 内置
Gateway 宿主	❌	✅ (本地模式)

应用场景（iOS）

随身 AI 助理：移动中随时唤醒 AI（Voice Wake），查询联系人、添加日历、设置提醒
相机工具节点 ：AI 通过 camera.snap 拍照、camera.clip 录像，进行视觉分析（扫描文件、识别物体）
个人数据接入：AI 直接读写手机上的联系人、日历、提醒事项，实现"帮我查一下 XXX 的电话"、"明天下午 3 点安排会议"
健康数据感知 ：通过 motion.pedometer 读取步数、motion.activity 识别活动（步行/跑步/驾驶），AI 可感知用户当前状态
Apple Watch 延伸 ：通过 watch.notify 向用户 Apple Watch 发送通知，AI 结果直接推送腕表
Canvas 移动展示：AI 生成的可视化界面直接投屏至 iPhone/iPad 上
屏幕录制分析 ：screen.record 录制 iOS 屏幕，AI 分析用户操作流程
位置感知助理：开启位置后，AI 可获取当前 GPS 坐标，提供基于位置的服务

技术实现:

语言: Swift
框架: SwiftUI
协议: OpenClawKit (Swift Package)
网络: URLSession (WebSocket)
媒体: AVFoundation + ReplayKit
发现: Network.framework (Bonjour/mDNS)
传感器: CoreMotion + CoreLocation
个人数据: Contacts + EventKit + Photos

关键文件:

bash 复制代码

apps/ios/Sources/
├── OpenClawApp.swift                    # 应用入口
├── RootTabs.swift                       # 三 Tab 主界面（Screen/Voice/Settings）
├── Gateway/
│   ├── GatewayConnectionController.swift # Node 连接与能力注册
│   ├── GatewayDiscoveryModel.swift       # Bonjour 设备发现
│   └── GatewaySettingsStore.swift        # 连接配置持久化
├── Capabilities/
│   └── NodeCapabilityRouter.swift        # 能力命令路由
├── Camera/
│   └── CameraController.swift            # 摄像头控制
├── Screen/
│   ├── ScreenRecordService.swift         # 屏幕录制
│   └── ScreenWebView.swift               # Canvas WebView
├── Voice/
│   ├── VoiceWakeManager.swift            # 语音唤醒
│   └── TalkModeManager.swift             # Talk Mode
├── Device/
│   ├── DeviceStatusService.swift         # 设备状态
│   └── DeviceInfoHelper.swift            # 设备信息
├── Motion/
│   └── MotionService.swift               # 计步/活动
├── Calendar/                             # 日历读写
├── Contacts/                             # 联系人读写
├── Reminders/                            # 提醒事项
├── Location/                             # GPS 定位
└── Media/                                # 媒体处理

2.4 Android 节点应用

路径 : apps/android/

系统角色：纯 Node --- 移动感知节点（含 SMS 独有能力）

Android 应用与 iOS 类似，扮演纯 Node 角色 （不托管 Gateway），但具有 iOS 没有的 SMS 短信发送能力，以及非常相似但略有差异的能力集合。

ini 复制代码

Android 设备
  └── 角色: Node（仅此一种）
        ├── 通过 Bonjour/mDNS 发现局域网 Gateway（NSD）
        ├── 或手动配置远程 Gateway 地址
        └── 建立 WebSocket 连接，声明能力并注册（clientId = "openclaw-android"）

UI 入口: 五个 Tab --- Connect （连接状态）、Chat （聊天）、Voice （语音）、Screen （Canvas）、Settings（设置）

Android Node 能力 (`buildCapabilities`)

能力	说明	默认状态
`canvas`	AI 可视化界面渲染（WebView Canvas + A2UI）	始终开启
`screen`	屏幕录制	始终开启
`camera`	摄像头拍照/录像	默认开启（可关闭）
`sms`	短信发送（Android 独有）	需系统 SMS 权限
`voiceWake`	语音唤醒	需手动开启 + 麦克风权限
`location`	GPS/网络定位	需手动开启

Android Node 声明的 commands（命令）:

Canvas: canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot

A2UI: canvas.a2ui.push, canvas.a2ui.pushJSONL, canvas.a2ui.reset

屏幕: screen.record

摄像头: camera.snap, camera.clip（开启后）

位置: location.get（开启后）

SMS: sms.send（Android 独有，有 SMS 权限时启用）

应用更新: app.update

调试 (DEBUG 构建): debug.logs, debug.ed25519

Android 独有能力（与 iOS Node 对比）

能力	Android	iOS
SMS 短信发送	✅ `sms.send`	❌
联系人读写	❌	✅
日历/提醒事项	❌	✅
相册访问	❌	✅
计步/活动识别	❌	✅
Apple Watch	❌	✅
设备状态/信息	❌ (通过 UA 传递)	✅ `device.status`
应用更新	✅ `app.update`	❌
前台要求	✅ Canvas/摄像头/屏幕需在前台	部分

重要约束 ：Android 的 Canvas、摄像头、屏幕录制命令需要应用在前台运行 ，后台时 InvokeDispatcher 会返回 NODE_BACKGROUND_UNAVAILABLE 错误。

应用场景（Android）

短信自动化 ：AI 通过 sms.send 直接从 Android 手机发送 SMS，适合通知类自动化（无需 WhatsApp 等第三方）
相机视觉节点 ：camera.snap / camera.clip 拍照录像，AI 分析视觉内容
屏幕录制分析 ：screen.record 录制 Android 屏幕，AI 分析 App 使用行为
语音助理移动端：Voice Wake 支持，手机随时唤醒 AI
Canvas 移动展示：AI 生成的可视化界面实时推送至 Android 端 WebView 展示
应用自更新 ：app.update 命令支持 AI 触发应用更新，便于远程维护
位置感知助理 ：开启位置后，location.get 返回 GPS 坐标（含精度、高度、速度）

技术实现:

语言: Kotlin
框架: Jetpack Compose (Material 3)
网络: OkHttp + WebSocket
媒体: CameraX + MediaProjection
发现: NSD (Network Service Discovery，Android Bonjour)
前台服务: NodeForegroundService 保持 Node 连接存活

关键文件:

bash 复制代码

apps/android/app/src/main/java/ai/openclaw/android/
├── MainActivity.kt                   # 主活动，请求权限
├── NodeApp.kt                        # Application 类，全局初始化
├── MainViewModel.kt                  # UI 状态管理
├── NodeRuntime.kt                    # Node 运行时，协调各 Handler
├── NodeForegroundService.kt          # 前台服务，保持 Node 存活
├── node/
│   ├── ConnectionManager.kt          # 能力注册与连接配置 (buildCapabilities)
│   ├── InvokeDispatcher.kt           # 命令路由分发
│   ├── CanvasController.kt           # Canvas WebView 控制
│   ├── CameraHandler.kt              # 摄像头命令处理
│   ├── ScreenHandler.kt              # 屏幕录制命令处理
│   ├── LocationHandler.kt            # 位置命令处理
│   ├── SmsHandler.kt                 # SMS 发送命令处理
│   ├── A2UIHandler.kt                # A2UI 渲染处理
│   └── AppUpdateHandler.kt           # 应用更新处理
├── voice/
│   ├── VoiceWakeManager.kt           # 语音唤醒
│   └── TalkModeManager.kt            # Talk Mode
└── ui/
    ├── PostOnboardingTabs.kt         # 五 Tab 主界面（Connect/Chat/Voice/Screen/Settings）
    ├── CanvasScreen.kt               # Canvas 展示
    ├── VoiceTabScreen.kt             # 语音 Tab
    └── ConnectTabScreen.kt           # 连接状态 Tab

2.5 Web 控制界面

路径 : ui/, src/gateway/control-ui.ts

系统角色：Gateway 控制台 + WebChat 入口

Web 界面是内嵌在 Gateway 中的浏览器端控制台 ，通过 src/gateway/control-ui.ts 由 Gateway 内置 HTTP 服务器托管。它是唯一无需安装、通过浏览器即可访问的客户端，既是系统管理员的运维面板，也是最轻量的 AI 对话入口。

ini 复制代码

浏览器 (http://localhost:18789)
  └── 角色: 控制台 + 操作员客户端
        ├── 通过 WebSocket 连接 Gateway (GatewayBrowserClient)
        ├── 以 role="operator" 身份接入
        └── 订阅系统事件，执行管理操作

页面结构: 左侧导航栏分为四组 ------ Chat（聊天） / Control（控制） / Agent（代理） / Settings（设置）

Web UI 功能模块（Tab 全列表）

Tab 组	Tab	功能说明
Chat	`chat`	WebChat 对话界面，直接与 AI 交互，支持 Markdown 渲染、工具调用展示、流式响应
Control	`overview`	Gateway 总览：连接状态、活跃会话、节点列表、快速操作
	`channels`	渠道管理：启停 Telegram/Discord/Slack/Signal/iMessage/WhatsApp 等，内置各渠道配置表单
	`instances`	多 Agent 实例管理
	`sessions`	会话历史查看器：查看所有对话会话，支持时间线展示
	`usage`	AI 调用用量 & 费用统计，按模型/渠道/时间维度分析
	`cron`	Cron 任务编辑器：可视化配置定时 Agent 任务
Agent	`agents`	Agent 详情面板：工具调用追踪、文件浏览、Skills 配置、渠道绑定、Cron 绑定
	`skills`	Skills（技能）管理：查看/启用/配置 Agent 技能
	`nodes`	Node 设备列表：查看所有已配对 iOS/Android/macOS 节点及其能力，管理执行审批
Settings	`config`	完整配置编辑器：结构化分节展示所有配置项，支持搜索
	`debug`	调试工具：测试消息发送、连接测试
	`logs`	实时日志流：Gateway 运行日志，支持过滤和搜索

Web UI 专有能力

功能	描述
执行审批弹窗	当 macOS Node 执行 `system.run` 需要审批时，Web UI 显示 `exec-approval` 提示弹窗
Gateway URL 确认	首次连接陌生 Gateway 时弹出 TLS/URL 确认对话框
多渠道配置表单	每个渠道（Telegram/Discord/Slack/Signal/WhatsApp/iMessage 等）有独立配置表单视图
i18n 多语言	支持界面语言切换（`ui/src/i18n/`）
主题切换	明暗主题切换 (`theme-transition.ts`)
Markdown 渲染	Chat 和 Agent 面板中完整 Markdown 渲染，包含代码高亮
工具调用流展示	`app-tool-stream.ts` 实时展示 AI 工具调用进度

应用场景（Web 控制界面）

远程运维控制台：通过浏览器（本地或远程 SSH 隧道转发）管理 Gateway 的所有渠道和配置
零安装 AI 对话 ：在任意浏览器打开 localhost:18789 即可与 AI 对话，无需安装任何 App
多渠道接入管理：集中配置所有消息渠道的 Token/密钥，查看连接状态
定时任务可视化：通过 Cron 编辑器配置 AI 定期执行的任务（每日总结、数据抓取等）
会话记录回溯：通过 Sessions Tab 查看历史对话，包含完整的工具调用链路
用量成本分析：Usage Tab 按模型统计 API 调用量和估算费用
安全审批中心：macOS Node 执行危险命令时，通过 Web UI 弹窗进行人工审批

技术实现:

框架: Vanilla TypeScript + Lit (Web Components)
状态管理: 本地响应式状态 (app-view-state.ts) + localStorage
构建: Rollup (bundled into dist/ui/)
通信: WebSocket (GatewayBrowserClient, gateway.ts) + HTTP polling
渲染: app-render.ts 纯函数渲染（Tagged Template Literals via html...``）

关键文件:

bash 复制代码

ui/src/
├── main.ts                          # 入口，初始化 OpenClawApp 组件
├── ui/
│   ├── app.ts                       # 根组件 (OpenClawApp Lit element)
│   ├── app-render.ts                # 主渲染函数（所有 Tab 路由到对应 view）
│   ├── app-view-state.ts            # 应用状态（当前 Tab、数据缓存）
│   ├── gateway.ts                   # GatewayBrowserClient（WebSocket 客户端）
│   ├── app-gateway.ts               # Gateway 连接生命周期
│   ├── navigation.ts                # Tab 定义、路由（Tab 类型、TAB_GROUPS）
│   ├── app-tool-stream.ts           # 工具调用流式展示
│   ├── app-channels.ts              # 渠道管理逻辑
│   ├── app-settings.ts              # 设置管理
│   └── views/
│       ├── overview.ts              # 总览页
│       ├── channels.ts              # 渠道管理（含各渠道配置表单）
│       ├── agents.ts                # Agent 详情面板
│       ├── sessions.ts              # 会话查看器
│       ├── usage.ts                 # 用量统计
│       ├── cron.ts                  # Cron 任务编辑器
│       ├── nodes.ts                 # Node 设备管理（含 exec-approvals）
│       ├── skills.ts                # Skills 管理
│       ├── config.ts                # 配置编辑器（config-form.*）
│       ├── logs.ts                  # 实时日志
│       ├── chat.ts                  # WebChat 界面
│       └── exec-approval.ts         # 执行审批弹窗

3. 对外提供的接口

3.1 CLI 接口

命令行 API:

typescript 复制代码

// Gateway 管理
openclaw gateway run [--port PORT] [--bind BIND] [--force]
openclaw gateway stop

// Agent 交互
openclaw agent --message "text" [--thinking LEVEL]

// 消息发送
openclaw message send --to TARGET --message "text" [--channel CHANNEL]

// 渠道管理
openclaw channels status [--probe] [--deep] [--all]

// 配置管理
openclaw config set KEY VALUE
openclaw config get KEY
openclaw config list

// 配对管理
openclaw pairing list [--channel CHANNEL]
openclaw pairing approve CHANNEL CODE
openclaw pairing revoke CHANNEL TARGET

// 诊断工具
openclaw doctor [--fix] [--verbose]

3.2 GUI 接口 (macOS/iOS/Android)

用户交互:

点击菜单栏图标 → 显示菜单
启动/停止 Gateway → 控制后台服务
打开设置 → 配置界面
激活 Voice Wake → 语音唤醒
打开 Canvas → 可视化窗口

系统集成:

系统托盘/通知中心
启动项管理
快捷键绑定
语音权限
网络权限

3.3 Web 接口

HTTP Endpoints (通过 Gateway):

bash 复制代码

GET  /api/status            # Gateway 状态
GET  /api/channels          # 渠道列表
POST /api/channels/:id/start # 启动渠道
POST /api/channels/:id/stop  # 停止渠道
GET  /api/config            # 获取配置
PUT  /api/config            # 更新配置
GET  /api/logs              # 获取日志

WebSocket Events:

typescript 复制代码

// 客户端 → 服务器
{ type: 'subscribe', channels: ['gateway', 'channels', 'logs'] }
{ type: 'agent_message', message: 'Hello' }
{ type: 'config_update', config: {...} }

// 服务器 → 客户端
{ type: 'gateway_status', status: {...} }
{ type: 'channel_event', channel: 'telegram', event: {...} }
{ type: 'log_entry', entry: {...} }
{ type: 'agent_response', response: {...} }

4. 与其他层的交互

4.1 与 Gateway 控制平面交互

CLI 工具:

less 复制代码

CLI → WebSocket (ws://localhost:18789)
    → Gateway WebSocket 服务器
        → 命令执行
            → 响应返回

原生应用:

bash 复制代码

macOS/iOS/Android App
    → WebSocket/HTTP 连接
        → Gateway 控制平面
            → 实时状态同步
            → Canvas 更新推送
            → 语音指令转发

Web 界面:

less 复制代码

Browser
    → HTTP/WebSocket (http://localhost:18789)
        → Gateway HTTP/WS 服务器
            → 状态查询
            → 配置更新
            → 日志流式传输

4.2 通信协议

WebSocket 消息格式:

typescript 复制代码

interface GatewayMessage {
  type: string              // 消息类型
  id?: string               // 消息 ID (用于请求-响应)
  timestamp: number         // 时间戳
  payload: any             // 消息载荷
}

// 示例
{
  type: 'agent_message',
  id: 'msg-123',
  timestamp: 1706400000000,
  payload: {
    message: 'Hello',
    thinking: 'high'
  }
}

HTTP API 格式:

typescript 复制代码

// 请求
POST /api/channels/telegram/start
Content-Type: application/json
{
  "reconnect": true
}

// 响应
HTTP/1.1 200 OK
Content-Type: application/json
{
  "success": true,
  "channel": "telegram",
  "status": "connected"
}

5. 技术实现细节

5.1 CLI 架构

命令解析流程:

typescript 复制代码

// openclaw.mjs
import { Command } from 'commander'

const program = new Command()
program
  .name('openclaw')
  .description('Personal AI assistant')
  .version('2026.2.24')

// 注册命令
program
  .command('gateway')
  .description('Manage Gateway')
  .action(async (options) => {
    const { runGateway } = await import('./dist/commands/gateway.js')
    await runGateway(options)
  })

program.parse(process.argv)

依赖注入:

typescript 复制代码

// src/commands/gateway.ts
import { createDefaultDeps } from '../infra/deps.js'

export async function runGateway(options: GatewayOptions) {
  const deps = createDefaultDeps()
  const gateway = new Gateway(deps, options)
  await gateway.start()
}

5.2 macOS 应用架构

macOS 应用具备双重角色：既可托管 Gateway（本地模式），也同时以 Node 身份接入。

模式切换 (ConnectionModeCoordinator):

swift 复制代码

// apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift
func apply(mode: AppState.ConnectionMode, paused: Bool) async {
    switch mode {
    case .local:
        // 启动本地 Gateway 进程，然后建立 ControlChannel
        let shouldStart = GatewayAutostartPolicy.shouldStartGateway(mode: .local, paused: paused)
        if shouldStart { /* 启动 GatewayProcessManager */ }
        try await ControlChannel.shared.configure(mode: .local)
    case .remote:
        // 不运行本地 Gateway，通过 SSH/Tailscale 隧道连接远端
        try await ControlChannel.shared.configure(mode: .remote(...))
    }
}

Node 模式 (MacNodeModeCoordinator): macOS 作为 Node 连接 Gateway，声明 canvas/screen/camera/location/system.run 等能力：

swift 复制代码

// apps/macos/Sources/OpenClaw/NodeMode/MacNodeModeCoordinator.swift
// MenuBar 就绪时启动:  MacNodeModeCoordinator.shared.start()
let caps = self.currentCaps()   // ["canvas","screen","camera","location",...]
let commands = self.currentCommands(caps: caps)  // 包含 system.run, screen.record 等
let connectOptions = GatewayConnectOptions(
    role: "node", caps: caps, commands: commands,
    clientId: "openclaw-macos", clientMode: "node",
    clientDisplayName: InstanceIdentity.displayName)
try await self.session.connect(url: config.url, ...)

Voice Wake 转发 (VoiceWakeForwarder): 识别到唤醒词后，将转录文本发送给 AI Agent：

swift 复制代码

// apps/macos/Sources/OpenClaw/VoiceWakeForwarder.swift
static func forward(transcript: String, options: ForwardOptions) async {
    let payload = Self.prefixedTranscript(transcript)  // 添加"User talked via voice on <machineName>"前缀
    await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
        message: payload, sessionKey: options.sessionKey, thinking: options.thinking))
}

5.3 iOS 架构

iOS 仅作为 Node，在 GatewayConnectionController 中注册能力（包含 macOS 没有的 contacts/calendar/reminders/motion/watch 等）：

swift 复制代码

// apps/ios/Sources/Gateway/GatewayConnectionController.swift
private func currentCaps() -> [String] {
    var caps = [OpenClawCapability.canvas.rawValue, OpenClawCapability.screen.rawValue]
    if cameraEnabled { caps.append(OpenClawCapability.camera.rawValue) }
    if voiceWakeEnabled { caps.append(OpenClawCapability.voiceWake.rawValue) }
    if locationMode != .off { caps.append(OpenClawCapability.location.rawValue) }
    caps.append(OpenClawCapability.device.rawValue)
    if WatchMessagingService.isSupportedOnDevice() {
        caps.append(OpenClawCapability.watch.rawValue)
    }
    caps.append(OpenClawCapability.photos.rawValue)
    caps.append(OpenClawCapability.contacts.rawValue)
    caps.append(OpenClawCapability.calendar.rawValue)
    caps.append(OpenClawCapability.reminders.rawValue)
    if Self.motionAvailable() { caps.append(OpenClawCapability.motion.rawValue) }
    return caps
}

iOS 主界面包含三个 Tab（RootTabs.swift）:

Screen --- Canvas 展示（ScreenTab）
Voice --- 语音唤醒 & Talk Mode（VoiceTab）
Settings --- 连接配置（SettingsTab）

5.4 Web UI 架构

Web UI 以 Lit Web Component (OpenClawApp) 为根，app-render.ts 作为单一渲染函数，依据 AppViewState.tab 路由到各 view 模块。

导航结构 (navigation.ts):

typescript 复制代码

export const TAB_GROUPS = [
  { label: "chat",     tabs: ["chat"] },
  { label: "control",  tabs: ["overview", "channels", "instances", "sessions", "usage", "cron"] },
  { label: "agent",    tabs: ["agents", "skills", "nodes"] },
  { label: "settings", tabs: ["config", "debug", "logs"] },
] as const;

渲染入口 (app-render.ts):

typescript 复制代码

// 每个 Tab 对应独立 view 渲染函数
state.tab === "chat"     ? renderChat({ ... })
state.tab === "overview" ? renderOverview({ ... })
state.tab === "channels" ? renderChannels({ ... })
state.tab === "agents"   ? renderAgents({ ... })
state.tab === "nodes"    ? renderNodes({ ... })
// ... 等 13 个 Tab
// 全局浮层（始终在 DOM 中）：
renderExecApprovalPrompt(state)    // 执行审批弹窗
renderGatewayUrlConfirmation(state) // Gateway URL 确认弹窗

Android 双角色 (ConnectionManager.kt):

kotlin 复制代码

// Android 既可作为 Node，也可作为 Operator（控制台）
fun buildNodeConnectOptions() = GatewayConnectOptions(role = "node", caps = buildCapabilities(), ...)
fun buildOperatorConnectOptions() = GatewayConnectOptions(
    role = "operator",
    scopes = listOf("operator.read", "operator.write", "operator.talk.secrets"),
    caps = emptyList(), ...
)

6. 安全考虑

6.1 本地访问控制

默认绑定:

yaml 复制代码

gateway:
  bind: loopback  # 仅监听 127.0.0.1
  port: 18789

远程访问 (可选):

yaml 复制代码

gateway:
  bind: all       # 监听 0.0.0.0
  require_auth: true
  auth_token: "secure-token"

6.2 移动应用配对

Bonjour 发现 (iOS/macOS):

swift 复制代码

let browser = NWBrowser(for: .bonjourWithTXTRecord(
    type: "_openclaw._tcp",
    domain: "local."
), using: .tcp)

browser.browseResultsChangedHandler = { results, changes in
    for result in results {
        // 发现 Gateway 实例
        connectToGateway(result.endpoint)
    }
}

配对流程:

markdown 复制代码

1. 移动设备发现 Gateway (Bonjour/mDNS)
2. 请求配对
3. Gateway 生成配对码
4. 用户在 macOS/CLI 确认配对
5. 建立信任连接

6.3 数据保护

本地存储: 配置和会话存储在用户目录
传输加密: WebSocket 可选 TLS
令牌管理: OAuth 令牌本地加密存储
权限隔离: 移动应用最小权限原则

7. 性能优化

7.1 CLI 性能

延迟加载: 命令模块按需导入
缓存配置: 配置文件缓存
并发控制: 限制并发请求数

7.2 原生应用性能

WebSocket 重连: 自动重连机制
状态缓存: 本地缓存 Gateway 状态
增量更新: Canvas 仅更新变化部分
资源管理: 及时释放未使用资源

7.3 Web UI 性能

虚拟滚动: 日志查看器虚拟列表
防抖/节流: 配置编辑器输入防抖
懒加载: 组件按需加载
缓存策略: HTTP 缓存头

8. 开发和调试

8.1 CLI 开发

bash 复制代码

# 开发模式运行
pnpm dev gateway run --verbose

# 调试日志
DEBUG=openclaw:* pnpm dev gateway run

# 测试命令
pnpm test src/cli/

8.2 macOS 应用开发

bash 复制代码

# 构建应用
pnpm mac:package

# 打开 Xcode (SPM 项目)
open apps/macos

# 运行应用
pnpm mac:open

8.3 iOS/Android 开发

bash 复制代码

# iOS
pnpm ios:build
pnpm ios:run

# Android
pnpm android:assemble
pnpm android:run

8.4 Web UI 开发

bash 复制代码

# 开发服务器
pnpm ui:dev

# 构建生产版本
pnpm ui:build

# 测试
pnpm ui:test

9. 部署和分发

9.1 CLI 分发

npm 全局安装:

bash 复制代码

npm install -g openclaw@latest

二进制分发:

macOS: DMG 安装包
Linux: deb/rpm 包
Windows: MSI 安装程序

9.2 macOS 应用分发

开发版本:

bash 复制代码

scripts/package-mac-app.sh
# 生成 dist/OpenClaw.app

发布版本:

bash 复制代码

# 签名和公证
scripts/codesign-mac-app.sh
scripts/create-dmg.sh
# 生成 dist/OpenClaw-v2026.2.24.dmg

9.3 移动应用分发

iOS:

TestFlight (Beta 测试)
App Store (正式发布)

Android:

APK 直接分发
Google Play (正式发布)

10. 总结

客户端层是 OpenClaw 系统的用户接触点，各客户端在系统中扮演不同角色：

客户端	系统角色	核心特色能力
CLI	管理工具，Gateway 生命周期控制	命令行 API，适合开发者和脚本自动化
macOS 应用	双重身份：Gateway 宿主 + Node	唯一可托管 Gateway；`system.run` Shell 执行；Peekaboo UI 自动化；Cron 调度
iOS 应用	纯 Node，移动传感器节点	个人数据全面接入（联系人/日历/提醒/相册）；Apple Watch；计步/活动识别；PTT 语音
Android 应用	纯 Node，移动感知节点	SMS 发送（唯一支持 SMS 的客户端）；`app.update` 自更新；前台强约束
Web 控制界面	运维控制台 + 操作员客户端	零安装浏览器访问；13 个 Tab 全功能管理；执行审批弹窗；i18n 多语言

所有 Node 客户端通过统一的 WebSocket 协议（role=node）向 Gateway 注册能力并接受命令调用，Web 控制界面以 role=operator 接入执行管理操作，确保了一致的通信协议和清晰的职责边界。

11. 应用场景畅想

了解了这些客户端的能力，心中是不是已经有场景了？比如：给男/女朋友手机装上客户端，问一句"ta到家了没"→ AI 秒报位置，顺带汇报"步行中"还是"坐车了"。对方动态尽在掌握！

谁在兴奋？劝你不要这么做...

如果你在用安卓手机，婚礼前一天，一句话让 AI 批量 sms.send 邀请函给全部联系人，省得一条一条复制粘贴，AI 还能帮你润色措辞。

请合理合规使用...

把旧 Android 手机和 iPhone、Mac 摄像头分别摆好，一句话统一指挥同时开拍：猫咪犯事现场，多角度同步存档。

我知道你在想什么...

来说说你想到的玩法~

OpenClaw 客户端层分析

1. 层概述

2. 主要组件

2.1 CLI 工具

2.2 macOS 菜单栏应用

系统角色：双重身份 --- Gateway 宿主 + Node

macOS Node 能力 (currentCaps)

macOS 专有能力（非 Node 协议层）

应用场景（macOS）

2.3 iOS 节点应用

系统角色：纯 Node --- 移动传感器与个人数据枢纽

iOS Node 能力 (currentCaps)

iOS 独有能力（与 macOS Node 对比）

应用场景（iOS）

2.4 Android 节点应用

系统角色：纯 Node --- 移动感知节点（含 SMS 独有能力）

Android Node 能力 (buildCapabilities)

Android 独有能力（与 iOS Node 对比）

应用场景（Android）

2.5 Web 控制界面

系统角色：Gateway 控制台 + WebChat 入口

Web UI 功能模块（Tab 全列表）

Web UI 专有能力

应用场景（Web 控制界面）

3. 对外提供的接口

3.1 CLI 接口

3.2 GUI 接口 (macOS/iOS/Android)

3.3 Web 接口

4. 与其他层的交互

4.1 与 Gateway 控制平面交互

4.2 通信协议

5. 技术实现细节

5.1 CLI 架构

5.2 macOS 应用架构

5.3 iOS 架构

5.4 Web UI 架构

6. 安全考虑

6.1 本地访问控制

6.2 移动应用配对

6.3 数据保护

7. 性能优化

7.1 CLI 性能

7.2 原生应用性能

7.3 Web UI 性能

8. 开发和调试

8.1 CLI 开发

8.2 macOS 应用开发

8.3 iOS/Android 开发

8.4 Web UI 开发

9. 部署和分发

9.1 CLI 分发

9.2 macOS 应用分发

9.3 移动应用分发

10. 总结

11. 应用场景畅想

macOS Node 能力 (`currentCaps`)

iOS Node 能力 (`currentCaps`)

Android Node 能力 (`buildCapabilities`)