第 7 章 Nodes 与 Browser：OpenClaw 的「身体」与「眼睛」

上一章我们理解了 OpenClaw 如何接收消息；这一章看另一侧——它如何通过 Nodes 和 Browser，真正在你的设备和浏览器里「动手」。

7.1 为什么需要「身体」：从 API 到真实操作

大多数 Skills 可以通过 API 完成任务（Gmail API、GitHub API、Slack API……），但现实中有很多情况 API 搞不定。目标网站没有公开 API 或 API 能力不足；OAuth 授权太麻烦，反而不如直接用已有浏览器会话；任务涉及屏幕操作、截图、识别、或者复杂的鼠标键盘序列；又或者需要控制本机软件（播放器、IDE、系统设置等）。

这就是 Nodes 和 Browser 存在的原因：让 OpenClaw 拥有「在真实设备上动手」的能力，而不只是调用远程 API。

7.2 Node 抽象：每台设备都是一个执行环境

7.2.1 Node 是什么

Node 是 OpenClaw 对「执行设备/环境」的抽象。macOS 桌面机器可以是一个 Node，iOS 手机可以是一个 Node，Android 手机可以是一个 Node，甚至一台远程服务器（通过 SSH 或容器）也可以成为 Node。

每个 Node 对 Gateway 暴露的，是一组「该设备上可以执行的能力」：

interface NodeCapabilities {
  system: {
    run?: boolean;       // 是否可以运行 Shell 命令
    notify?: boolean;    // 是否可以发送系统通知
    fileAccess?: boolean; // 是否可以读写文件
  };
  camera?: boolean;       // 是否有摄像头可用
  screen?: boolean;       // 是否可以截图/录屏
  location?: boolean;     // 是否可以获取位置
  audio?: boolean;        // 是否可以录音/TTS 播放
  canvas?: boolean;       // 是否支持 Canvas（LiveCanvas 功能）
}

7.2.2 macOS Node 的典型能力

在 OpenClaw 的 macOS 桌面端（以菜单栏 App 形式运行），Node 能力通常包括执行 Shell 命令（ls、curl、git 等）、通过 macOS 通知中心发送系统通知、摄像头快照和短视频录制、屏幕截图或录屏、监听唤醒词并触发 Talk Mode（Voice Wake）、以及向 macOS 上的 Canvas 窗口推送 UI 内容。

7.2.3 iOS/Android Node 的典型能力

移动端 Node 主要为 Gateway 提供位置信息（Android 可配置持续上报）、摄像头拍照和录像、屏幕录制、接收推送和通知等功能。Android 端还有一些特有能力，比如读取短信、通讯录、日历、设备运动传感器，甚至控制某些系统设置。

7.2.4 Node 与 Gateway 的通信方式

Node 和 Gateway 之间通常通过一个持久连接保持实时通信。在局域网中，Node 直接连 Gateway 的 WebSocket 地址（例如 ws://192.168.x.x:18789）；远程场景下，可以通过 Tailscale、SSH Tunnel 等方式将 Gateway 暴露出去，Node 再连过来。

通信协议大致遵循「指令 + 结果」模式：

// Gateway → Node 下发指令
interface NodeCommand {
  type: "system.run" | "camera.snap" | "screen.capture" | "notify" | ...; 
  payload: Record<string, any>;
}

// Node → Gateway 返回结果
interface NodeCommandResult {
  success: boolean;
  data?: any;      // 例如截图的 base64 数据，或 Shell 命令的输出
  error?: string;
}

Agent Runtime 在决定使用某个 Node 能力时，会通过 Gateway 下发 NodeCommand；Gateway 找到对应 Node、转发指令，再把 NodeCommandResult 回传给 Agent。

7.3 Browser 工具：可控的专用浏览器实例

7.3.1 为什么是「专用」浏览器

OpenClaw 的 Browser 工具通常不复用你日常使用的 Chrome/Firefox，而是启动一个专用的 Chromium 实例。这么做有几个好处：隔离方面，避免 AI 操作误触你的正常标签页、表单、密码管理器；可控方面，对这个专用实例的所有操作都记录在日志中，便于审计；无缝方面，可以在专用实例里预先登录某些服务（Gmail、GitHub 等），AI 操作时直接使用已有 Session，不用每次重新 OAuth。

7.3.2 Browser 能做什么

interface BrowserCapabilities {
  // 页面导航
  navigate(url: string): Promise<void>;
  
  // 快照（页面截图）
  snapshot(): Promise<{
    screenshot: string;  // base64 图片
    html?: string;       // 当前页面 HTML（可选）
    text?: string;       // 页面可读文本
  }>;
  
  // 元素操作
  click(selector: string): Promise<void>;
  type(selector: string, text: string): Promise<void>;
  select(selector: string, value: string): Promise<void>;
  
  // 脚本执行
  evaluate(script: string): Promise<any>;
  
  // 文件操作
  upload(selector: string, filePath: string): Promise<void>;
  download(url: string, saveTo: string): Promise<void>;
  
  // 页面等待
  waitForSelector(selector: string, timeout?: number): Promise<void>;
  waitForNavigation(timeout?: number): Promise<void>;
}

当 Agent Runtime 要求执行「归档 Gmail 中的所有 GitHub 通知」时，它可能给 Browser 发一系列指令：先 navigate 到 Gmail 页面，snapshot 截图确认状态，type 搜索关键词，click 搜索按钮，循环勾选邮件，点击归档，最后再 snapshot 确认结果。

这整个序列通常由 Agent Runtime 和模型协同完成：每一步操作后，截图或页面文本会反馈给模型，模型再决定下一步该做什么，直到目标完成或失败。

7.3.3 Browser Profiles 与登录状态

Browser 工具通常支持持久化的「浏览器 Profile」，在 Profile 里保存 Cookie、Local Storage 等登录状态，这样下次启动时不需要重新登录。不同任务还可以使用不同 Profile（例如个人邮箱 Profile 和公司 Profile 分开）。这个机制极大地提高了 Browser 工具的实用性——避免每次操作都卡在登录验证上。

7.4 媒体与多模态：图片、语音、视频在通道与 Agent 间的流转

现实中你给 OpenClaw 发的消息未必只有文字。你可能发一张截图问「这个报错是什么意思」，用语音说「把这件事加到今天的 Todo」，OpenClaw 也可能主动给你发一张处理结果的截图，或者读一段 TTS 语音。

7.4.1 入站媒体的处理

入站媒体会在 Channel 适配器层进行初步处理：下载附件到临时目录，记录文件大小、MIME 类型、临时路径，如果是音频则触发转录（ASR）流程，得到文本后再和原始消息一起传给 Gateway。

在 InboundMessage 中，附件结构大致如下：

interface Attachment {
  type: "image" | "audio" | "video" | "file";
  mimeType: string;
  url?: string;       // 原始 URL（如果平台支持直接访问）
  localPath?: string; // 下载到本地的临时文件路径
  transcript?: string; // 音频转录结果（如果已转录）
  size?: number;      // 文件大小（字节）
}

大文件和超时转录会按策略处理，超过上限直接拒绝，或记录但不转录。

7.4.2 出站媒体

Agent 生成的结果也可能是非文本的：Browser 截图作为「操作证明」发送给用户，Node 拍摄的照片，Canvas 画面的导出，或者由 ElevenLabs 或系统 TTS 生成的语音。

这些出站媒体的生命周期是有限的，通常在成功发送给用户后就可以从临时存储中清理，避免无限占用磁盘。

7.4.3 Voice Wake 与 Talk Mode

在 macOS/iOS 上，OpenClaw 还支持语音交互模式。Voice Wake 监听特定唤醒词（类似「Hey Siri」），听到后自动进入对话模式。Talk Mode 则持续进行语音转录、Agent 处理、TTS 回复的循环，适合双手不在键盘时使用。

这两个功能依赖 Node 的音频能力。整体上是一个「麦克风录音 → ASR → InboundMessage → Agent → TTS → 播放」的端到端链路，内部结构和普通文本消息的链路基本一致，只是在首尾各加了音频处理步骤。

7.5 语音与画布：Canvas / A2UI 简介

Canvas 是 OpenClaw 的一个特殊功能。在 macOS 上，Agent 可以向一个专门的 Canvas 窗口推送内容（表格、卡片、图表、HTML 片段等），相当于给 OpenClaw 一个「可视化白板」，既可以展示信息，也可以和你协同编辑。A2UI 是其中负责 UI 渲染的子系统，通过一套简单的 DSL，允许 Agent 以声明式方式描述界面内容。

从架构上说，Canvas/A2UI 是 macOS Node 能力的一部分，通过 Gateway → Node 的指令通道驱动。详细内容参见官方文档：docs.openclaw.ai/platforms/mac/canvas。

7.6 安全与隔离设计

7.6.1 Browser 沙盒

虽然 Browser 工具功能强大，但仍需要隔离。Browser 实例通常运行在一个独立的容器或专用目录下，防止意外访问到系统敏感文件。下载文件会落在指定的临时目录，不会直接放到用户 Home 或桌面。对于高风险操作（如表单提交、支付相关页面、账号设置页面），Agent Policy 可以要求额外确认。

7.6.2 Node 权限最小化

Node 暴露给 Gateway 的能力集，也应该遵循最小权限原则。默认不开放 system.run（可执行任意 Shell），摄像头和屏幕录制等高隐私能力需要用户显式授权，每次执行高风险 Node 命令建议记录到审计日志。

有关完整的权限控制策略，我们会在第 14 章「安全模型」中深入讨论。

7.7 源码走读导向：Browser 工具与 Node Command 的实现

在阅读相关源码时，可以沿以下路径找到关键模块。

Browser 工具实现方面，在 src/browser/ 中可以找到 Chromium + CDP 封装的代码，重点关注如何通过 Chrome DevTools Protocol 封装网页操作 API，以及如何在每次操作后触发截图反馈给 Agent。

Node 通信模块方面，在 Gateway 侧查找处理 Node 注册、心跳检测和命令下发的模块，在 macOS/iOS/Android 端分别查找对应 Node 客户端的实现（可能是 Swift/Kotlin/TypeScript 视平台而定）。

媒体处理管道方面，查找入站附件下载、音频转录的相关模块（关键词：transcribe、attachment、media），以及出站媒体的生命周期管理（临时文件创建、发送后清理）。

7.8 小结

本章介绍了 OpenClaw 的「执行层」。Node 是对设备和环境的抽象，暴露一组可远程调用的执行能力；Browser 是独立可控的浏览器工具，支持页面操作、截图、脚本执行；媒体管道处理了入站和出站的图片、语音、视频；Voice Wake 和 Talk Mode 把语音交互接入了标准消息链路；Canvas/A2UI 为 macOS 用户提供了可视化交互界面。

至此，我们已经把 Part II 中 OpenClaw 的四大核心抽象（Session、Agent、Channel、Node/Browser）全部过了一遍。从下一章开始，我们进入 Part III，直接走进 Gateway 的「控制室」，从源码层面拆开它的骨架。