第 12 章 · 节点与多平台部署
Agent 有"大脑"（Gateway），也需要"身体"——你的手机、电脑、树莓派就是它的感官延伸。节点系统让 OpenClaw 从"聊天机器人"变成"能看见、听见、触碰的 AI"。
本章你将学到：
- 理解 Node 的设计哲学和配对流程
- 掌握 Canvas、Camera、Screen、Location 等节点能力
- 学会 Talk 模式和 Voice Wake 的配置
- 在 macOS、iOS、Android、Windows、Linux 和树莓派上部署
- 配置远程访问和多 Gateway 架构
12.1 Node 是什么 —— Agent 的"身体"
到目前为止，你接触的 OpenClaw 都是"只有大脑"的状态——Gateway 运行在服务器上，通过通道接收文字消息，回复文字消息。Agent 能聊天、能调用工具，但它"看不见"你的屏幕，"听不到"你的声音，"摸不到"你的设备。
Node 系统就是解决这个问题的。
没有 Node 时：
用户 → WhatsApp 文字 → Gateway → Agent → 回复文字 → 用户
有 Node 时：
用户 → WhatsApp 文字/语音/图片 → Gateway → Agent → 回复 + 截屏 + 打开网页 → 用户
↑
通过 Node 执行
Node 的本质：一个运行在用户设备上的客户端程序，通过 WebSocket 连接到 Gateway，以 role: "node" 身份注册。Gateway 可以通过 node.invoke 向 Node 下发命令——截图、拍照、导航网页、播放语音、获取定位。
Node 不是 Gateway 的替代品，而是 Gateway 的感官延伸。一个 Gateway 可以同时连接多个 Node——你的 MacBook、你的 iPhone、你的 Android 平板，都可以是同一个 Agent 的"身体"。
12.1.1 Node 的两种形态
OpenClaw 的 Node 分为两种：
有头 Node（Headed Node）：带 GUI 的原生应用
- macOS 菜单栏应用（推荐）
- iOS 应用
- Android 应用
有头 Node 拥有完整的 GUI 上下文——可以控制窗口、显示通知、获取摄像头画面、执行 AppleScript。
无头 Node（Headless Node）：后台服务
- Linux 服务器上的 Node 服务
- 树莓派上的 Node 服务
- Docker 容器中的 Node 服务
无头 Node 没有 GUI，但可以执行命令、访问文件系统、连接硬件设备。
12.1.2 节点能力一览
不同平台暴露不同的能力：
| 能力 | macOS | iOS | Android | Linux | 树莓派 |
|---|---|---|---|---|---|
| Canvas（画布） | ✅ | ✅ | ✅ | — | — |
| Camera（摄像头） | ✅ | ✅ | ✅ | — | ✅ |
| Screen（屏幕录制） | ✅ | ✅ | — | — | — |
| Location（定位） | ✅ | ✅ | ✅ | — | — |
| System.run（命令执行） | ✅ | — | 部分 | ✅ | ✅ |
| SMS 发送 | — | — | ✅ | — | — |
| 通知 | ✅ | ✅ | ✅ | — | — |
| 通讯录/日历 | — | — | ✅ | — | — |
| 传感器（运动/计步） | — | — | ✅ | — | — |
12.2 Node 配对与管理
Node 在接入 Gateway 之前需要配对（Pairing）——这是一个安全机制，防止任何设备都能冒充你的 Node。
12.2.1 配对流程
┌──────────┐ ┌──────────┐
│ Node │ │ Gateway │
│(你的设备) │ │(你的服务器)│
└────┬─────┘ └────┬─────┘
│ 1. 发现 Gateway │
│ (mDNS/手动输入) │
│ ─────────────────────────────→│
│ │
│ 2. WebSocket 握手 │
│ (role: "node") │
│ ─────────────────────────────→│
│ │
│ 3. 等待批准 │
│← ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ──│
│ │
│ 4. 运维人员批准 │
│ openclaw devices approve │
│ │
│ 5. 配对成功，开始通信 │
│←─────────────────────────────→│
12.2.2 Gateway 发现方式
Node 可以通过三种方式找到 Gateway：
1. mDNS/Bonjour（同一局域网，最简单）
Gateway 自动在本地网络广播 _openclaw-gw._tcp。同一局域网内的 Node 会自动发现：
# 验证 Gateway 是否在广播
dns-sd -B _openclaw-gw._tcp local.
2. Tailscale + unicast DNS-SD（跨网络，推荐）
当 Node 和 Gateway 不在同一局域网时（比如你的 iPhone 在外面，Gateway 在家里），通过 Tailscale 组网 + DNS-SD 转发实现发现：
- 在 Gateway 上设置 DNS-SD 区域（如
openclaw.internal.） - 配置 Tailscale Split DNS 指向该 DNS 服务器
- Node 通过 Tailscale 的 MagicDNS 解析 Gateway 地址
3. 手动输入（兜底方案）
在 Node 的设置中启用"手动主机"，直接输入 Gateway 的地址和端口：
Host: 192.168.1.100
Port: 18789
Token: <你的 Gateway token>
12.2.3 配对批准
Node 首次连接时会在 Gateway 产生一个待批准的配对请求：
# 查看待配对设备
openclaw devices list
# 输出示例：
# ┌─────────────────────────────────────────────────────┐
# │ PENDING PAIRING REQUESTS │
# ├──────────────┬──────────────────────────────────────┤
# │ ID │ 7f3a2b1c-8e4d-4f6a-9b1c-2d3e4f5a6b7c │
# │ Device │ Alice's iPhone │
# │ Role │ node │
# │ Status │ pending │
# └──────────────┴──────────────────────────────────────┘
# 批准配对
openclaw devices approve 7f3a2b1c-8e4d-4f6a-9b1c-2d3e4f5a6b7c
# 或拒绝
openclaw devices reject 7f3a2b1c-8e4d-4f6a-9b1c-2d3e4f5a6b7c
配对成功后，Node 会自动重连——下次启动时不需要重新配对（除非你在 Node 端清除了配对数据）。
⚠️ 踩坑记录
问题：iOS app 重装后无法重连。
原因：重装会清除 Keychain 中的配对令牌。
解决：在 Gateway 端重新配对（
openclaw devices list→openclaw devices approve）。
12.2.4 验证连接
# 查看 Node 状态
openclaw nodes status
# 通过 Gateway API 查看
openclaw gateway call node.list --params "{}"
nodes status 会显示每个 Node 的连接状态、上报的能力列表、最后活跃时间。
12.3 Canvas —— Agent 的"画布"
Canvas 是 Node 最强大的能力之一。它让 Agent 可以在 Node 设备上显示 HTML/CSS/JS 内容——不只是文字，而是完整的网页界面。
想象一下这些场景：
- Agent 生成一个数据图表，直接显示在你的手机上
- Agent 制作一个交互式表单，你在手机上填写后提交
- Agent 搭建一个临时的控制面板，实时显示系统状态
12.3.1 Canvas 的工作原理
Gateway HTTP 服务器（同端口，默认 18789）
├── /__openclaw__/canvas/ ← Canvas 主机
│ └── 由 workspace/canvas/ 目录提供文件
├── /__openclaw__/a2ui/ ← A2UI 主机（Agent-to-UI）
│ └── 接收 JSONL 流，实时渲染 UI
└── ...
Canvas 文件存放在 Gateway 的 ~/.openclaw/workspace/canvas/ 目录。当文件变化时，Gateway 的 Canvas 主机会自动注入 live-reload 客户端，刷新 Node 上的显示。
12.3.2 Canvas 命令
# 让 Node 导航到 Canvas 页面
openclaw nodes invoke --node "iPhone" \
--command canvas.navigate \
--params '{"url":"http://gateway-host:18789/__openclaw__/canvas/"}'
# 在 Canvas 上执行 JavaScript
openclaw nodes invoke --node "iPhone" \
--command canvas.eval \
--params '{"javaScript":"document.title = \"Hello from Agent\""}'
# 截取 Canvas 快照
openclaw nodes invoke --node "iPhone" \
--command canvas.snapshot \
--params '{"maxWidth":900,"format":"jpeg"}'
# 显示 Canvas（iOS/Android 前台）
openclaw nodes invoke --node "iPhone" \
--command canvas.present
# 隐藏 Canvas
openclaw nodes invoke --node "iPhone" \
--command canvas.hide
# 返回默认空白页
openclaw nodes invoke --node "iPhone" \
--command canvas.navigate \
--params '{"url":""}'
12.3.3 A2UI（Agent-to-UI）
A2UI 是 Canvas 的高级模式——Agent 不需要预先写好 HTML 文件，而是通过 JSONL 流实时推送 UI 组件到 Node 上渲染：
# 推送 UI 组件
openclaw nodes invoke --node "iPhone" \
--command canvas.a2ui.push \
--params '{"items":[{"type":"text","content":"当前温度: 23°C"}]}'
# 重置 A2UI 画布
openclaw nodes invoke --node "iPhone" \
--command canvas.a2ui.reset
iOS Node 在连接成功后会自动导航到 A2UI（如果 Gateway 广播了 Canvas 主机 URL）。
💡 提示：Canvas 命令（
canvas.navigate、canvas.eval、camera.snap等）需要 Node 应用处于前台。如果 Node 在后台，命令会返回NODE_BACKGROUND_UNAVAILABLE错误。
12.4 Camera —— Agent 的"眼睛"
Camera 能力让 Agent 可以调用 Node 设备的摄像头拍照或录视频。
12.4.1 支持的命令
# 拍照（返回 JPEG）
openclaw nodes invoke --node "iPhone" \
--command camera.snap \
--params '{}'
# 录制视频片段（返回 MP4）
openclaw nodes invoke --node "iPhone" \
--command camera.clip \
--params '{}'
12.4.2 使用条件
- Node 应用必须处于前台
- 用户已授予相机权限
- macOS 的 Camera 通过系统摄像头实现，iOS/Android 通过系统相机 API
12.4.3 典型场景
Agent 可以在以下场景自动使用 Camera：
- "帮我看看冰箱里有什么" → 调用
camera.snap拍照 → 分析图片内容 - "帮我录一段 10 秒的视频" → 调用
camera.clip录制 - "监控门口有没有人" → 定期拍照 + 分析
12.5 Screen —— Agent 的"屏幕"
Screen 能力让 Agent 可以截取 Node 设备的屏幕内容。
12.5.1 支持的命令
# 屏幕录制
openclaw nodes invoke --node "MacBook" \
--command screen.record \
--params '{}'
12.5.2 平台支持
Screen Recording 目前支持 macOS 和 iOS。Android 暂不支持（受限于系统 API）。
macOS 需要用户在"系统偏好设置 → 安全性与隐私 → 屏幕录制"中授权 OpenClaw。
12.6 Location —— Agent 的"位置感知"
Location 能力让 Agent 知道 Node 设备当前在哪里。
12.6.1 获取位置
openclaw nodes invoke --node "iPhone" \
--command location.get \
--params '{}'
返回值包含经纬度和精度信息。
12.6.2 权限模式
Location 有三种权限模式，Node 端可以配置：
| 模式 | 行为 |
|---|---|
off |
禁止获取位置 |
whileUsing |
仅在 Node 应用前台时允许 |
precise |
允许精确定位（包括后台） |
首次调用 location.get 时，系统会弹出权限请求。用户选择"允许一次"、"使用时允许"或"始终允许"决定了后续的权限级别。
12.6.3 典型场景
- "我附近有什么好吃的？" → 获取位置 → 搜索附近餐厅
- "提醒我到公司后打卡" → Cron 任务中检查位置
- "记录今天的运动轨迹" → 定期获取位置点
12.7 System.run —— 远程执行命令
system.run 是 Node 能力中最灵活也最需要谨慎对待的一个——它让 Gateway 可以在 Node 设备上执行命令。
12.7.1 工作原理
Gateway
│
│ node.invoke → system.run → { command: "ls -la ~/Desktop" }
│
▼
Node Service (WS)
│
│ IPC (Unix Domain Socket + token + HMAC + TTL)
│
▼
macOS App / Headless Node
│
│ 执行命令，返回结果
│
▼
Gateway 收到输出
在 macOS 上，system.run 通过本地 Unix Socket 从 Node Service 传递到 macOS App 执行。这意味着命令在 macOS App 的进程上下文中运行——拥有 App 的 TCC 权限（辅助功能、屏幕录制等）。
12.7.2 Exec Approvals（命令审批）
不是所有命令都能随意执行。macOS App 内置了命令审批机制：
~/.openclaw/exec-approvals.json
{
"version": 1,
"defaults": {
"security": "deny",
"ask": "on-miss"
},
"agents": {
"main": {
"security": "allowlist",
"ask": "on-miss",
"allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
}
}
}
安全策略：
| 值 | 行为 |
|---|---|
deny |
拒绝所有命令 |
allowlist |
只允许白名单中的命令 |
ask |
未知命令弹出确认（on-miss = 仅首次） |
安全过滤：
- 包含 shell 控制字符（
&&、||、;、|、$、反引号等）的命令自动视为白名单未命中 - 环境变量会被过滤（移除
PATH、DYLD_*、LD_*、NODE_OPTIONS等） - Shell 包装器（
bash -c）的环境覆盖会被限制为安全白名单（TERM、LANG、LC_*等）
⚠️ 踩坑记录
问题：Agent 通过
system.run执行cat /etc/passwd成功了，但执行echo hello && cat /etc/passwd被拒绝了。原因：包含 shell 控制字符
&&的命令会被自动视为 allowlist miss。解决：如果确实需要执行链式命令，手动将 shell 二进制（如
/bin/bash）加入 allowlist。但请谨慎——这意味着 Agent 可以通过 shell 执行任意命令。
12.7.3 典型场景
# 在 Mac 上搜索文件
openclaw nodes invoke --node "MacBook" \
--command system.run \
--params '{"command": "/opt/homebrew/bin/rg --files ~/Documents"}'
# 在 Mac 上显示通知
openclaw nodes invoke --node "MacBook" \
--command system.notify \
--params '{"title": "提醒", "body": "该开会了"}'
12.8 媒体理解 —— 看、听、读
Node 不只是"输出"设备，它也是"输入"设备——用户发送的图片、语音、视频，Agent 都需要理解。
12.8.1 媒体理解管线
OpenClaw 的媒体理解采用"Provider 优先 + CLI 兜底"的双层策略：
用户发送图片/音频/视频
│
▼
┌─────────────┐ ┌──────────────┐
│ 自动检测 │────→│ Provider API │ ← Whisper、Gemini 等
│ 媒体类型 │ │（高质量） │
└──────┬──────┘ └──────────────┘
│ │
│ 成功？
│ ┌──┴──┐
│ Yes No
│ │ │
│ ▼ ▼
│ 使用结果 ┌──────────────┐
│ │ 本地 CLI │ ← ffmpeg、whisper.cpp 等
│ │（离线兜底） │
│ └──────────────┘
│
▼
Agent 收到文本/描述
自动检测流程：
- 检查附件的 MIME 类型
- 匹配本地可用的 CLI 工具
- 尝试 Provider API 转录/识别
- CLI 失败则尝试 Provider，反之亦然
12.8.2 配置媒体理解
{
agents: {
defaults: {
media: {
// 音频转录（优先用 Whisper API）
audio: {
transcription: {
provider: "openai/whisper-1",
fallback: "cli:whisper" // 本地 whisper CLI 兜底
}
},
// 图片理解
image: {
understanding: {
provider: "anthropic/claude-sonnet-4-6",
fallback: "cli:gemini" // Gemini CLI 兜底
}
}
}
}
}
}
12.8.3 附件策略
你可以通过配置控制哪些媒体类型被接受：
{
agents: {
defaults: {
attachments: {
policy: "allow", // "allow" | "deny" | "ask"
maxBytes: 20 * 1024 * 1024, // 最大 20MB
types: ["image/*", "audio/*", "video/mp4"],
}
}
}
}
12.8.4 语音消息处理
在群聊中，OpenClaw 可以自动检测并转录语音消息：
{
agents: {
defaults: {
audio: {
mention: true, // @Agent 时自动转录语音
echoTranscript: true, // 转录后发送文字副本
}
}
}
}
12.9 Talk 模式 —— 持续语音对话
Talk 模式让 Agent 和用户之间可以进行持续的语音对话——就像打电话一样，你说一句，Agent 回一句，循环往复。
12.9.1 Talk 模式的工作流程
用户按下麦克风按钮（或语音唤醒触发）
│
▼
录音 → 转录为文字 → 发送给 Agent → Agent 生成回复
│
▼
TTS 语音合成
│
▼
播放语音给用户
│
▼
等待用户下一句
（或用户中断）
12.9.2 配置 Talk 模式
Talk 模式目前支持 macOS、iOS 和 Android。
TTS 配置（推荐 ElevenLabs）：
{
agents: {
defaults: {
talk: {
tts: {
provider: "elevenlabs",
voice: "Rachel", // ElevenLabs 语音名称
apiKey: {
source: "env",
provider: "elevenlabs",
id: "ELEVENLABS_API_KEY"
}
},
// 语音指令：Agent 回复中包含这些指令时会被拦截执行
voiceDirectives: true,
// 说话时检测到新语音则中断当前播放
interruptOnSpeech: true,
}
}
}
}
系统 TTS 兜底：如果没有配置 ElevenLabs，Talk 模式会使用系统自带的 TTS 引擎（质量较低，但不需要额外配置）。
12.9.3 语音指令（Voice Directives）
Agent 可以在回复中嵌入"语音指令"——特殊标记，被 Node 端拦截执行而不是朗读出来：
Agent 回复文本中包含：
[TALK_PAUSE] → 暂停对话
[TALK_RESUME] → 恢复对话
[TALK_END] → 结束对话
这让 Agent 可以控制对话的流程——比如在需要用户操作时暂停，操作完成后恢复。
12.9.4 说话中断（Interrupt-on-Speech）
当 interruptOnSpeech: true 时，如果用户在 Agent 说话时开口，Node 会中断当前的 TTS 播放，重新录音并发送给 Agent。这让对话更自然——不需要等 Agent 说完才能插话。
12.9.5 平台限制
| 平台 | Talk 模式 | 语音唤醒 | 注意 |
|---|---|---|---|
| macOS | ✅ | ✅ | 最完整的支持 |
| iOS | ✅ | ✅ | 后台音频可能被系统挂起 |
| Android | ✅ | ❌ | 语音唤醒/对话模式暂未开放 |
⚠️ 注意：iOS 的后台音频策略比较严格。当 App 不在前台时，语音播放可能被系统暂停。Talk 模式在 App 活跃时体验最佳。
12.10 Voice Wake —— 语音唤醒
Voice Wake 让你可以通过唤醒词（如"Hey OpenClaw"）随时激活 Agent，无需触摸设备。
12.10.1 工作原理
┌─────────────────────────────────────────────┐
│ Gateway（拥有者） │
│ │
│ ~/.openclaw/settings/voicewake.json │
│ ├── 唤醒词列表 │
│ ├── 模型文件 │
│ └── 同步到所有 Node │
│ │
├─────────────────────────────────────────────┤
│ Node（执行者） │
│ │
│ 持续监听音频流 │
│ ├── 检测到唤醒词 → 发送事件给 Gateway │
│ └── Gateway 触发 Talk 模式或执行命令 │
└─────────────────────────────────────────────┘
Voice Wake 的存储和模型文件由 Gateway 拥有，同步到所有连接的 Node。这样你只需要在一个地方配置唤醒词，所有设备都能响应。
12.10.2 配置唤醒词
Voice Wake 目前支持 macOS 和 iOS。唤醒词的配置和模型文件存储在：
~/.openclaw/settings/voicewake.json
在 macOS App 或 iOS App 的设置中启用 Voice Wake，App 会自动从 Gateway 同步唤醒词配置。
12.10.3 典型场景
- 家里多个设备都连接了同一个 Gateway，说"Hey OpenClaw"后最近的设备响应
- iPhone 放在桌上，语音唤醒后直接说"帮我设个明天早上 8 点的闹钟"
- 厨房里的 iPad 通过语音唤醒查询菜谱
12.11 多平台部署
OpenClaw 的 Gateway 支持多种操作系统，Node 支持更多平台。不同平台有不同的推荐部署方式。
12.11.1 平台支持总览
| 平台 | Gateway | Node | 推荐方式 | 备注 |
|---|---|---|---|---|
| macOS | ✅ | ✅ | macOS App | 最完整的体验 |
| Linux | ✅ | ✅ | systemd 服务 | 推荐用于服务器 |
| Windows | ✅ | — | WSL2（推荐）/ 原生 | 原生有部分限制 |
| iOS | — | ✅ | App Store | 仅 Node |
| Android | — | ✅ | APK | 仅 Node |
| 树莓派 | ✅ | ✅ | systemd 服务 | 低成本方案 |
关键点：Gateway 只运行在"桌面/服务器"操作系统上（macOS、Linux、Windows/WSL2）。移动设备（iOS、Android）只能作为 Node 连接到远程 Gateway。
12.11.2 macOS 部署
macOS 是 OpenClaw 的"主场"——它同时是最佳的 Gateway 宿主和最强大的 Node。
macOS App 的功能：
- 菜单栏常驻，显示连接状态
- 管理 Gateway 生命周期（启动/停止/重启）
- 拥有所有 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音识别、AppleScript）
- 暴露完整的 Node 能力（Canvas、Camera、Screen、system.run）
- 支持本地模式和远程模式
本地模式（默认）：App 管理本地 Gateway。如果没有运行中的 Gateway，App 会通过 openclaw gateway install 安装并启动 launchd 服务。
远程模式：App 连接到远程 Gateway（通过 SSH/Tailscale），同时启动本地 Node Service 让远程 Gateway 可以调用这台 Mac 的能力。
本地模式：
macOS App ←→ 本地 Gateway ←→ 云端模型 API
远程模式：
macOS App (Node Service) ←→ 远程 Gateway (在 VPS/树莓派上)
↓
云端模型 API
安装 macOS App：
- 下载 OpenClaw.app
- 拖到 Applications 文件夹
- 首次启动时完成权限清单（TCC 提示会依次弹出）
- 安装 CLI（App 内菜单或
openclaw gateway install）
状态目录：
避免将 OpenClaw 的状态目录放在 iCloud 或其他云同步文件夹中：
# 推荐：使用本地路径
export OPENCLAW_STATE_DIR=~/.openclaw
openclaw doctor 会检测状态目录是否在云同步路径下并发出警告。
12.11.3 Linux 部署
Linux 是最主流的 Gateway 宿主——VPS、服务器、树莓派都运行 Linux。
快速部署（VPS）：
# 1. 安装 Node.js 24
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
# 2. 安装 OpenClaw
npm i -g openclaw@latest
# 3. 运行 onboarding（含 daemon 安装）
openclaw onboard --install-daemon
Gateway 服务管理：
OpenClaw 默认安装 systemd 用户服务。对于共享或常驻服务器，建议使用系统服务：
# ~/.config/systemd/user/openclaw-gateway.service
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
systemctl --user enable --now openclaw-gateway.service
注意：不推荐用 Bun 运行 Gateway——WhatsApp 和 Telegram 通道在 Bun 下有已知 bug。
12.11.4 Windows 部署
Windows 有两条路径：WSL2（推荐）和原生。
WSL2 路径（推荐）：
WSL2 让你在 Windows 上运行完整的 Linux 环境，兼容性最好：
# 1. 安装 WSL2 + Ubuntu
wsl --install -d Ubuntu-24.04
# 2. 重启后，在 WSL 中启用 systemd
# /etc/wsl.conf
[boot]
systemd=true
# 3. 在 PowerShell 中重启 WSL
wsl --shutdown
# 4. 在 WSL 中安装 OpenClaw
npm i -g openclaw@latest
openclaw onboard --install-daemon
Windows 登录前自动启动（无头场景）：
# WSL 内：保持用户服务运行（不需要登录）
sudo loginctl enable-linger "$(whoami)"
# WSL 内：安装 Gateway 服务
openclaw gateway install
# PowerShell（管理员）：Windows 启动时自动启动 WSL
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
原生 Windows 状态：
原生 Windows 的 CLI 基础功能可用（openclaw --version、openclaw doctor），但 Daemon 安装依赖 Windows 计划任务。如果计划任务创建被拒绝，OpenClaw 会回退到启动文件夹的登录项。
WSL 服务暴露到局域网：
WSL 有自己的虚拟网络。如果局域网内其他设备需要访问 WSL 中的服务（Gateway、SSH 等），需要端口转发：
# PowerShell（管理员）
$WslIp = (wsl -d Ubuntu-24.04 -- hostname -I).Trim().Split(" ")[0]
# 转发 Windows 18789 端口到 WSL
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=18789 `
connectaddress=$WslIp connectport=18789
# 防火墙放行
New-NetFirewallRule -DisplayName "WSL OpenClaw" -Direction Inbound `
-Protocol TCP -LocalPort 18789 -Action Allow
⚠️ 踩坑记录
问题：WSL 重启后端口转发失效。
原因：WSL 的 IP 地址在每次重启后可能变化。
解决：将端口转发刷新命令注册为 Windows 计划任务（登录时执行），自动更新目标 IP。
12.11.5 iOS 部署
iOS 只能作为 Node——它不运行 Gateway。
配对流程：
- 在另一台设备上运行 Gateway
- 在 iOS App 中选择已发现的 Gateway（或手动输入地址）
- 在 Gateway 端批准配对请求
推送通知（官方/TestFlight 构建）：
官方 iOS 构建使用外部推送中继（Relay），而不是直接将 APNs 令牌发送给 Gateway：
{
gateway: {
push: {
apns: {
relay: {
baseUrl: "https://relay.example.com",
},
},
},
},
}
这个设计有三个安全目的：
- 生产 APNs 凭证不暴露给用户 Gateway
- 原始 APNs 令牌不存储在 Gateway 上
- 只允许官方/TestFlight 构建使用中继服务
- 防止一个 Gateway 向属于另一个 Gateway 的 iOS 设备发送推送
如果你使用本地 Xcode 构建（自签），仍然需要直接 APNs 凭证：
export OPENCLAW_APNS_TEAM_ID="TEAMID"
export OPENCLAW_APNS_KEY_ID="KEYID"
export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"
12.11.6 Android 部署
Android 也只能作为 Node。源码在 OpenClaw 仓库的 apps/android 下，可以用 Java 17 + Android SDK 自行构建。
Android 独有的能力：
除了通用的 Canvas、Camera 之外，Android Node 还暴露了更多设备级能力：
| 命令族 | 能力 |
|---|---|
device.status / device.info |
设备状态和信息 |
notifications.list / notifications.actions |
通知管理 |
photos.latest |
获取最新照片 |
contacts.search / contacts.add |
通讯录 |
calendar.events / calendar.add |
日历 |
callLog.search |
通话记录 |
sms.search / sms.send |
短信 |
motion.activity / motion.pedometer |
运动传感器 |
这些能力的可用性取决于设备型号和已授予的权限。
Android 连接特性：
- 使用前台服务保持 WebSocket 连接（通知栏会显示持久通知）
- 支持聊天历史（
chat.history、chat.send、chat.subscribe） - 语音使用单麦克风开/关流程（非 Talk 模式的连续对话）
- 语音唤醒和对话模式目前未开放
12.12 远程访问
Node 和 Gateway 不一定在同一台机器上。你可以在 VPS 上运行 Gateway，在家里 MacBook 上运行 Node——只要网络可达。
12.12.1 SSH 隧道
SSH 隧道是最简单、最通用的远程访问方式：
# 从笔记本建立隧道到 VPS 上的 Gateway
ssh -N -L 18789:127.0.0.1:18789 user@your-vps-ip
这条命令在笔记本上打开 localhost:18789，所有流量通过 SSH 转发到 VPS 的 127.0.0.1:18789。
macOS App 的远程模式：
当 macOS App 配置为远程模式时，它会自动建立 SSH 隧道：
- 控制隧道：转发 Gateway WebSocket 端口（用于健康检查、Web Chat、配置等）
- SSH 使用
BatchMode+ExitOnForwardFailure+ keepalive 选项 - 如果隧道断开，App 自动重连
⚠️ 注意：SSH 隧道使用 loopback，Gateway 看到的 Node IP 是
127.0.0.1。如果你需要 Gateway 看到真实的客户端 IP，使用 Direct（ws/wss）传输。
12.12.2 Tailscale
Tailscale 是基于 WireGuard 的零配置 VPN，非常适合 OpenClaw 的远程访问场景。
两种模式：
| 模式 | 用途 | 公网暴露 |
|---|---|---|
| Tailscale Serve | tailnet 内可访问 | ❌ |
| Tailscale Funnel | 全网可访问 | ✅ |
Tailscale Serve（推荐，仅 tailnet 内）：
{
gateway: {
bind: "tailnet", // 只监听 tailnet IP
},
tailscale: {
serve: {
enabled: true,
// 自动将 tailnet 域名映射到 Gateway 端口
},
},
}
这样你的所有 Tailscale 设备（笔记本、手机、树莓派）都可以通过 https://gateway-name.tail1234.ts.net 访问 Gateway。
Tailscale Funnel（公网访问）：
如果你需要从非 Tailscale 设备访问 Gateway：
{
tailscale: {
funnel: {
enabled: true,
},
},
}
⚠️ 安全警告：Funnel 会将 Gateway 暴露到公网。务必确保
gateway.auth已正确配置（token 或 password），否则任何人都可以控制你的 Agent。
Tailscale + DNS-SD：
Node 的 mDNS 发现无法跨网络工作。如果 Node 和 Gateway 通过 Tailscale 连接但在不同网络，配置 unicast DNS-SD：
- 在 Gateway 上设置 DNS-SD 区域（如
openclaw.internal.） - 发布
_openclaw-gw._tcp记录 - 配置 Tailscale Split DNS 指向该 DNS 服务器
- Node 通过 Tailscale 的 DNS 解析发现 Gateway
12.12.3 凭证优先级
远程访问模式下，CLI 使用凭证的优先级：
1. 环境变量（OPENCLAW_GATEWAY_TOKEN）
2. 本地配置文件（~/.openclaw/openclaw.json）
3. 远程模式凭证
如果你在本地和远程之间切换，注意凭证可能冲突。使用 openclaw status --all 检查当前连接状态。
12.13 多 Gateway 配置
某些场景下你可能需要运行多个 Gateway——比如一个用于个人助手，另一个用于测试新配置。
12.13.1 隔离清单
同一台机器上的多个 Gateway 必须在以下维度完全隔离：
| 维度 | 说明 |
|---|---|
| 配置路径 | OPENCLAW_CONFIG_DIR 或 --profile |
| 状态目录 | OPENCLAW_STATE_DIR |
| 工作空间 | OPENCLAW_WORKSPACE |
| 端口 | gateway.port 必须不同 |
12.13.2 使用 Profile
Profile 是管理多 Gateway 的推荐方式：
# 使用 profile 启动第二个 Gateway
openclaw gateway --profile test --port 18790
# CLI 操作指定 profile
openclaw status --profile test
openclaw nodes status --profile test
Profile 会自动隔离配置路径和状态目录：
~/.openclaw/
├── openclaw.json ← 默认 profile
├── profiles/
│ └── test/
│ ├── openclaw.json ← test profile
│ └── sessions/
12.13.3 救援机器人模式（Rescue Bot）
多 Gateway 的一个实用场景是"救援机器人"——当主 Gateway 出问题时，你可以启动一个轻量的救援 Gateway 来诊断和修复：
# 启动救援 Gateway（使用独立的 profile）
openclaw gateway --profile rescue --port 18791
# 救援 Gateway 连接到主 Gateway 的状态目录进行诊断
# 但不会干扰主 Gateway 的运行
12.13.4 macOS App 的 LaunchAgent
macOS App 管理的 LaunchAgent 标签会包含 profile 名称：
ai.openclaw.gateway ← 默认 profile
ai.openclaw.test ← test profile
# 控制 launchd 服务
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway
12.14 树莓派部署实战
树莓派是最经济的 OpenClaw Gateway 宿主——一次性投入 35-80 美元，没有月费。适合做 24/7 的个人 AI 助手、家庭自动化中枢或 Telegram/WhatsApp 机器人。
12.14.1 硬件选择
| 型号 | 内存 | 推荐 | 说明 |
|---|---|---|---|
| Pi 5 | 4/8GB | ✅ 最佳 | 最快，推荐 |
| Pi 4 | 4GB | ✅ 甜点 | 大多数用户够用 |
| Pi 4 | 2GB | ✅ 可用 | 加 swap 即可 |
| Pi 4 | 1GB | ⚠️ 勉强 | 最小配置，需要 swap |
| Pi 3B+ | 1GB | ⚠️ 慢 | 能跑但体验不佳 |
| Pi Zero 2W | 512MB | ❌ | 不推荐 |
最低要求：1GB RAM、1 核、500MB 磁盘 推荐配置：2GB+ RAM、64 位系统、16GB+ SD 卡（或 USB SSD）
12.14.2 部署步骤
第 1 步：刷写系统
使用 Raspberry Pi Imager 刷写 Raspberry Pi OS Lite（64 位）。点击齿轮图标预配置：
- 设置主机名（如
gateway-host） - 启用 SSH
- 设置用户名和密码
- 配置 WiFi（如果不使用以太网）
第 2 步：连接并更新系统
ssh user@gateway-host
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential
# 设置时区（对 Cron/提醒很重要）
sudo timedatectl set-timezone Asia/Shanghai
第 3 步：安装 Node.js 24
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version # v24.x.x
第 4 步：添加 Swap（2GB 以下内存必须）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# 降低 swappiness，优先使用物理内存
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
第 5 步：安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
或者如果你想要可修改的源码版本：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install && npm run build && npm link
第 6 步：运行 Onboarding
openclaw onboard --install-daemon
向导中的推荐选择：
- Gateway 模式：Local
- 认证：API Keys（OAuth 在无头环境下可能有问题）
- 通道：Telegram 最容易开始
- Daemon：Yes（systemd）
第 7 步：验证安装
openclaw status
sudo systemctl status openclaw
journalctl -u openclaw -f
12.14.3 性能优化
使用 USB SSD 替代 SD 卡：
SD 卡速度慢且容易磨损。USB SSD 是最大的性能提升：
lsblk # 检查是否从 USB 启动
加速 CLI 启动（模块编译缓存）：
grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc
NODE_COMPILE_CACHE 缓存编译后的模块，后续 status、health、--help 等命令会快很多。OPENCLAW_NO_RESPAWN=1 避免 CLI 自重启的额外开销。
systemd 启动调优：
sudo systemctl edit openclaw
[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90
sudo systemctl daemon-reload
sudo systemctl restart openclaw
减少内存占用：
# 禁用 GPU 内存分配（无头服务器不需要）
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
# 禁用蓝牙（如果不需要）
sudo systemctl disable bluetooth
12.14.4 远程访问树莓派
从你的笔记本访问树莓派上的 Dashboard：
# 获取 Dashboard URL
ssh user@gateway-host 'openclaw dashboard --no-open'
# 另一个终端：建立 SSH 隧道
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
# 在本地浏览器打开 Dashboard URL
如果需要随时远程访问，配置 Tailscale Serve。
12.14.5 ARM 兼容性
| 工具 | ARM64 状态 | 说明 |
|---|---|---|
| Node.js | ✅ | 完美运行 |
| WhatsApp (Baileys) | ✅ | 纯 JS 实现 |
| Telegram | ✅ | 纯 JS 实现 |
| Chromium | ✅ | sudo apt install chromium-browser |
| gog (Gmail CLI) | ⚠️ | 检查是否有 ARM 版本 |
务必使用 64 位系统：
uname -m
# 应该显示 aarch64（64 位），而不是 armv7l（32 位）
12.14.6 成本对比
| 方案 | 一次性成本 | 月费 | 备注 |
|---|---|---|---|
| Pi 4 (2GB) | ~$45 | $0 | + 电费 ~$5/年 |
| Pi 4 (4GB) | ~$55 | $0 | 推荐 |
| Pi 5 (4GB) | ~$60 | $0 | 最佳性能 |
| DigitalOcean | $0 | $6/月 | $72/年 |
| Hetzner | $0 | ~€3.79/月 | ~$50/年 |
树莓派大约 6-12 个月就能回本。但你得到的不只是省钱——你得到了一台真正属于你的、物理上可控的 AI 服务器。
12.14.7 常见问题
OOM（内存不足）：
free -h
# 如果可用内存接近 0，增加 swap 或减少运行的服务
性能慢：
- 换用 USB SSD
- 禁用不必要的服务：
sudo systemctl disable cups bluetooth avahi-daemon - 检查 CPU 降频：
vcgencmd get_throttled（返回0x0表示正常）
WiFi 断连（无头 Pi）：
sudo iwconfig wlan0 power off
echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
本章小结
- Node 是 Gateway 的感官延伸——让 Agent 能看见、听见、触碰设备
- Node 通过 WebSocket 连接 Gateway，以
role: "node"身份配对注册 - Canvas 让 Agent 在设备上显示完整的 HTML/CSS/JS 界面
- Camera、Screen、Location 让 Agent 拥有感知能力
system.run通过审批机制安全地执行远程命令- 媒体理解采用"Provider 优先 + CLI 兜底"的双层策略
- Talk 模式实现持续语音对话，Voice Wake 实现语音唤醒
- macOS 是最完整的平台，Linux 是最主流的服务器平台
- WSL2 是 Windows 用户的推荐路径
- iOS/Android 只能作为 Node，不能运行 Gateway
- SSH 隧道和 Tailscale 是远程访问的两种主要方式
- 多 Gateway 通过 Profile 实现隔离
- 树莓派是 35-80 美元的一次性投入，6-12 个月回本
下一步
Agent 有了"身体"（Node 系统），接下来要让它更"聪明"——学会用命令行自动化一切。下一章深入 OpenClaw 的 CLI 体系，从基础命令到自动化工作流，让你的运维效率提升一个量级。