夜雨聆风一、什么是 Node 服务？
1.1 核心概念
Node 服务（Node Host Service）是 OpenClaw 的远程命令执行代理，它允许 Gateway 在另一台机器上执行命令。
组件 | 运行位置 | 作用
|------|---------|------|
**Gateway** | 主服务器（如华为云 ECS） | 接收消息、运行 AI 模型、路由工具调用
**Node Host** | 远程设备（macOS/iOS/Android/Linux） | 执行设备本地命令（相机/屏幕/通知等）
1.2 为什么需要 Node 服务？
典型场景：
你的 Gateway 在华为云上，但你想：
❌ 直接在云上执行 → 无法访问你本地 Mac 的相机/屏幕/文件
✅ 通过 Node 服务 → Gateway 发送命令 → 你的 Mac 执行 → 返回结果核心用途：
- 📸 调用远程设备的相机拍照
- 🖥️ 截取远程设备的屏幕
- 📍 获取远程设备的位置信息
- 💻 在远程机器上执行 shell 命令
- 🔔 发送系统通知到远程设备
二、Node 服务架构详解
2.1 架构拓扑
┌──────────────────────────────────────────────────────────────┐
│ Gateway（华为云 ECS） │
│ ┌─────────────┬─────────────┬─────────────────────────────┐ │
│ │ WebSocket │ Agent │ Exec 工具（host=node） │ │
│ │ :18789 │ LLM 路由 │ 转发命令到 Node Host │ │
│ └──────┬──────┴──────┬──────┴──────────────┬──────────────┘ │
└─────────┼─────────────┼─────────────────────┼────────────────┘
│ │ │
│ WebSocket │ │
│ 配对认证 │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ macOS │ │ iOS │ │ Headless │
│ Node │ │ Node │ │ Node Host│
│（Menubar）│ │（App） │ │（Linux） │
└──────────┘ └──────────┘ └──────────┘
│ │ │
└────────────────┴───────────────────┘
执行本地命令
（相机/屏幕/通知/system.run）2.2 Node 类型与能力
Node 类型 | 平台 | 核心能力 | 运行方式
|----------|------|---------|---------|
**macOS Node** | macOS | `system.run`、`canvas.*`、`camera.*`、`screen.record`、`notifications` | Menubar App 或 headless
**iOS Node** | iOS | `canvas.*`、`camera.*`、`location.get`、Voice Wake | iOS App（后台受限）
**Android Node** | Android | `device.*`、`sms.send`、`photos.latest`、`contacts.*`、`calendar.*` | Android App
**Headless Node** | Linux/Windows | `system.run`、`system.which` | 命令行服务
2.3 核心能力清单
macOS Node 能力：
{
"commands": [
"system.run", "system.notify", "system.which",
"canvas.present", "canvas.hide", "canvas.navigate",
"canvas.eval", "canvas.snapshot", "canvas.a2ui.push",
"camera.snap", "camera.clip", "screen.record",
"location.get"
],
"permissions": {
"screenRecording": true,
"accessibility": false,
"camera": true,
"location": true,
"notifications": true
}
}Android Node 能力：
{
"commands": [
"device.status", "device.info", "device.permissions",
"notifications.list", "notifications.actions",
"photos.latest", "contacts.search", "contacts.add",
"calendar.events", "calendar.add",
"sms.send", "sms.search", "callLog.search",
"motion.activity", "motion.pedometer"
]
}三、部署前准备
3.1 确认 Gateway 状态
在 Gateway 服务器（华为云 ECS）上执行：
# 检查 Gateway 是否运行
openclaw gateway status
# 查看 Gateway 绑定地址
openclaw config get gateway.bind
# 可能值：loopback | lan | wan
# 查看 Gateway 端口
openclaw config get gateway.port
# 默认：18789
# 获取 Gateway Token（用于 Node 认证）
openclaw config get gateway.auth.token记录以下关键信息：
3.2 网络准备
确保 Gateway 防火墙允许 18789 端口：
# 华为云安全组添加入站规则
# 协议：TCP
# 端口：18789
# 源地址：0.0.0.0/0（或指定 IP）四、部署场景 A：Headless Node Host（Linux 服务器）
步骤 1：安装 OpenClaw CLI
在目标 Linux 机器上执行：
# 安装 Node.js 22+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证版本
node --version # 应 >= v22.0.0
# 安装 OpenClaw
npm install -g openclaw@latest
# 验证安装
openclaw --version步骤 2：配置环境变量
设置 Gateway 认证 Token：
# 方法 1：临时设置（当前 shell 会话）
export OPENCLAW_GATEWAY_TOKEN="你的 gateway token"
# 方法 2：永久设置（写入 ~/.bashrc）
echo 'export OPENCLAW_GATEWAY_TOKEN="你的 gateway token"' >> ~/.bashrc
source ~/.bashrc
# 方法 3：使用 .env 文件（推荐）
mkdir -p ~/.openclaw
cat > ~/.openclaw/node.env << 'EOF'
OPENCLAW_GATEWAY_TOKEN=你的 gateway token
OPENCLAW_NODE_EXEC_HOST=local
EOF
# 加载 .env 文件
set -a && source ~/.openclaw/node.env && set +a步骤 3：测试连接（前台运行）
先测试能否连接 Gateway：
# 前台运行 Node Host（调试模式）
openclaw node run \
--host 139.9.198.192 \
--port 18789 \
--display-name "My Linux Node"预期输出：
Connecting to Gateway at 139.9.198.192:18789...
WebSocket connected.
Waiting for device pairing approval...此时在 Gateway 服务器上执行：
# 查看待配对的 Node 请求
openclaw devices list
# 输出示例：
# Pending pairing requests:
# [req_xyz789] Node: "My Linux Node" (IP: x.x.x.x)
# 批准配对
openclaw devices approve req_xyz789配对成功后，Node Host 会显示：
Device pairing approved.
Node ID: node_abc123
Connected as: My Linux Node按 Ctrl+C 停止前台运行（接下来配置为后台服务）
步骤 4：安装为 systemd 服务
创建 systemd 服务文件：
sudo cat > /etc/systemd/system/openclaw-node.service << 'EOF'
[Unit]
Description=OpenClaw Node Host Service
After=network.target
[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/home/openclaw
# 环境变量
Environment="OPENCLAW_GATEWAY_TOKEN=你的 gateway token"
Environment="OPENCLAW_NODE_EXEC_HOST=local"
Environment="OPENCLAW_SYSTEMD_UNIT=openclaw-node.service"
Environment="OPENCLAW_LOG_PREFIX=node"
# 执行命令
ExecStart=/home/openclaw/.nvm/versions/node/v22.22.1/bin/openclaw node run \
--host 139.9.198.192 \
--port 18789 \
--display-name "My Linux Node"
# 自动重启
Restart=always
RestartSec=10
# 日志
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-node
# 安全限制
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
[Install]
WantedBy=multi-user.target
EOF重新加载 systemd 并启动服务：
# 重新加载 systemd 配置
sudo systemctl daemon-reload
# 启用开机自启
sudo systemctl enable openclaw-node
# 启动服务
sudo systemctl start openclaw-node
# 查看状态
sudo systemctl status openclaw-node预期输出：
● openclaw-node.service - OpenClaw Node Host Service
Loaded: loaded (/etc/systemd/system/openclaw-node.service; enabled)
Active: active (running) since Wed 2026-04-01 10:00:00 CST步骤 5：验证部署
在 Gateway 服务器上：
# 查看已配对的 Nodes
openclaw nodes status
# 输出示例：
# Connected nodes:
# [node_abc123] My Linux Node (192.168.1.100) - Online
# Capabilities: system.run, system.which
# 测试执行命令
openclaw nodes run --node "My Linux Node" --raw "uname -a"
# 查看 Node 详细信息
openclaw nodes describe --node "My Linux Node"查看 Node 日志：
# 实时查看日志
sudo journalctl -u openclaw-node -f
# 查看最近 100 行
sudo journalctl -u openclaw-node -n 100五、部署场景 B：macOS Node 部署
方式 1：Menubar App（推荐）
步骤 1：下载并安装 OpenClaw macOS App
步骤 2：启动 App 并配置
1. 打开 OpenClaw.app
2. 菜单栏出现 OpenClaw 图标
3. 点击图标 → Settings
4. 输入 Gateway 地址：139.9.198.192:18789
5. 输入 Gateway Token
6. 勾选 "Enable Node Mode"
7. 点击 "Connect"步骤 3：在 Gateway 上批准配对
openclaw devices list
openclaw devices approve req_xxx步骤 4：授予权限（System Settings → Privacy & Security）
方式 2：Headless Node Host（命令行）
步骤 1：安装 OpenClaw CLI
# 安装 Node.js
brew install node@22
# 安装 OpenClaw
npm install -g openclaw@latest步骤 2：配置并运行
# 设置环境变量
export OPENCLAW_GATEWAY_TOKEN="你的 gateway token"
# 运行 Node Host
openclaw node run \
--host 139.9.198.192 \
--port 18789 \
--display-name "My Mac Node"步骤 3：安装为 launchd 服务
# 自动安装
openclaw node install \
--host 139.9.198.192 \
--port 18789 \
--display-name "My Mac Node"
# 启动服务
openclaw node restart
# 查看状态
openclaw node statuslaunchd 配置文件位置：
~/Library/LaunchAgents/com.openclaw.node.plist查看日志：
# 实时日志
log show --predicate 'process == "OpenClaw"' --last 1h --style syslog
# 或查看日志文件
tail -f ~/Library/Logs/openclaw-node.log六、部署场景 C：iOS/Android Node 部署
6.1 iOS 部署
步骤 1：下载 App
步骤 2：配置连接
1. 打开 App
2. 点击 "Connect to Gateway"
3. 输入 Gateway 地址：139.9.198.192:18789
4. 输入 Gateway Token
5. 勾选 "Enable Canvas"（可选）
6. 点击 "Connect"步骤 3：授予权限
步骤 4：在 Gateway 上批准
openclaw devices approve req_xxx注意：iOS Node 后台运行受限，Canvas 和 Camera 功能需要 App 在前台
6.2 Android 部署
步骤 1：下载 APK
步骤 2：安装并配置
1. 安装 APK
2. 打开 App
3. 点击 "Connect"
4. 输入 Gateway 地址和 Token
5. 点击 "Pair"步骤 3：授予权限
步骤 4：在 Gateway 上批准
openclaw devices approve req_xxxAndroid Node 能力：
七、安全配置：Exec 审批
7.1 Exec 审批机制
Node Host 上的 system.run 命令受 Exec 审批 控制：
审批模式 | 说明 | 安全级别
|---------|------|---------|
`ask` | 每次执行前需要手动批准 | 🔒 最高
`allowlist` | 只在白名单中的命令可执行 | 🔒 推荐
`full` | 允许所有命令 | ⚠️ 不安全
配置文件：~/.openclaw/exec-approvals.json（在 Node Host 上）
7.2 配置 Exec 白名单
在 Gateway 上添加允许的命令：
# 设置 Exec 默认使用 Node
openclaw config set tools.exec.host node
# 设置安全模式为白名单
openclaw config set tools.exec.security allowlist
# 指定默认 Node
openclaw config set tools.exec.node "My Linux Node"
# 添加允许的命令
openclaw approvals allowlist add \
--node "My Linux Node" \
"/usr/bin/uname"
openclaw approvals allowlist add \
--node "My Linux Node" \
"/usr/bin/git"
openclaw approvals allowlist add \
--node "My Linux Node" \
"/usr/bin/docker"exec-approvals.json 示例：
{
"allowlist": [
{
"command": "/usr/bin/uname",
"args": ["-a"],
"node": "node_abc123"
},
{
"command": "/usr/bin/git",
"args": ["status"],
"node": "node_abc123"
}
]
}八、远程连接方案
8.1 直连模式（Gateway 绑定 LAN/WAN）
Gateway 配置（openclaw.json）：
{
"gateway": {
"bind": "lan", // 或 "wan"
"port": 18789,
"auth": {
"mode": "token",
"token": "your-token"
}
}
}Node Host 连接：
openclaw node run \
--host 139.9.198.192 \
--port 18789 \
--env OPENCLAW_GATEWAY_TOKEN="your-token"8.2 SSH 隧道模式（Gateway 绑定 Loopback）
场景：Gateway 只绑定 127.0.0.1（更安全）
步骤：
1. 建立 SSH 隧道（在 Node Host 上）：
# 保持运行：本地 18790 → Gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host2. 连接 Node Host：
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw node run \
--host 127.0.0.1 \
--port 18790 \
--display-name "Tunneled Node"8.3 Tailscale 模式
Gateway 配置：
{
"gateway": {
"bind": "loopback",
"tailscale": {
"mode": "serve" // 或 "funnel"
}
}
}Node Host 连接：
openclaw node run \
--host <gateway-tailnet-ip> \
--port 443 \
--tls九、测试与验证
测试 1：查看 Node 状态
在 Gateway 上：
openclaw nodes status预期输出：
Connected nodes (1):
[node_abc123] My Linux Node
IP: 192.168.1.100
Status: Online
Capabilities: system.run, system.which
Last seen: 2 seconds ago测试 2：执行远程命令
# 执行简单命令
openclaw nodes run \
--node "My Linux Node" \
--raw "uname -a"
# 执行带参数命令
openclaw nodes run \
--node "My Linux Node" \
--raw "df -h /"测试 3：发送通知
openclaw nodes notify \
--node "My Linux Node" \
--title "测试通知" \
--body "Node 服务部署成功！"测试 4：通过 Agent 使用 Node
在聊天中：
用户：在我的 Linux 节点上运行 git status
Agent: [调用 exec tool，host=node]
[Gateway 转发到 Node Host]
[Node 执行命令并返回结果]
Agent: 执行结果:
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean十、故障排查
问题 1：Node 无法连接 Gateway
# 在 Node Host 上检查网络
ping 139.9.198.192
# 检查 Gateway 端口是否可达
telnet 139.9.198.192 18789
# 或
nc -zv 139.9.198.192 18789
# 检查 Gateway 防火墙
# 在 Gateway 上:
sudo ufw status
sudo ufw allow 18789/tcp问题 2：配对请求不出现
# 在 Gateway 上查看待处理请求
openclaw devices list
# 如果没有请求，检查 Node 日志
# Linux:
sudo journalctl -u openclaw-node -n 50
# macOS:
log show --predicate 'process == "OpenClaw"' --last 10m
# 重启 Node 服务
# Linux:
sudo systemctl restart openclaw-node
# macOS:
openclaw node restart问题 3：system.run 被拒绝
# 检查审批模式
openclaw config get tools.exec.security
# 如果是 "ask" 模式，需要手动批准
# 如果是 "allowlist" 模式，添加白名单
openclaw approvals allowlist add \
--node "My Linux Node" \
"/usr/bin/uname"
# 或临时切换到 "full" 模式（不安全）
openclaw config set tools.exec.security full十一、部署检查清单
完成以下检查确认部署成功：
十二、快速参考命令
Gateway 服务器
openclaw devices list # 查看待配对请求
openclaw devices approve <id> # 批准配对
openclaw nodes status # 查看 Node 状态
openclaw nodes describe <id> # 查看 Node 详情
openclaw approvals list # 查看审批白名单Node Host（Linux）
sudo systemctl status openclaw-node # 查看服务状态
sudo journalctl -u openclaw-node -f # 查看实时日志
sudo systemctl restart openclaw-node # 重启服务
openclaw node run --host ... # 前台运行（调试）Node Host（macOS）
openclaw node status # 查看服务状态
openclaw node restart # 重启服务
log show --predicate ... # 查看日志十三、性能与限制
13.1 性能指标
指标 | 数值
|------|------|
WebSocket 延迟 | ~50-200ms（取决于网络）
命令执行延迟 | ~100-500ms（简单命令）
屏幕录制大小 | ~1-5MB/10s（720p）
相机照片大小 | ~1-3MB（JPEG）
并发连接数 | 无限制（取决于 Gateway 资源）
13.2 限制
限制项 | 值 | 说明
|--------|-----|------|
屏幕录制最长时间 | 60s | 避免过大文件
相机视频最长时间 | 60s | 避免过大文件
Canvas 快照最大宽度 | 4096px | 可调整
后台执行 | 受限（iOS/Android） | 需要前台运行
权限要求 | 平台相关 | 相机/位置/通知需用户授权
十四、最佳实践
14.1 安全建议
1. 使用 Token 认证，避免密码
2. 启用 TLS（生产环境）
3. 配置白名单（allowlist 模式）
4. 定期轮换 Token
5. 限制 Gateway 绑定（优先 loopback + SSH/Tailscale）
14.2 运维建议
1. 监控 Node 状态：openclaw nodes status（每日检查）
2. 日志轮转：配置 logrotate（Linux）
3. 自动重启：使用 systemd/launchd 服务
4. 备份配置：~/.openclaw/node.json 纳入备份
5. 版本同步：Node 和 Gateway 保持相同版本
14.3 网络优化
1. 局域网优先：Node 和 Gateway 在同一内网延迟最低
2. 使用 Tailscale：跨网络时比直连更安全
3. 避免 NAT 穿透：明确端口转发或使用隧道
4. QoS 配置：为 WebSocket 流量优先（企业网络）
结语
OpenClaw Node 服务让你能够安全、可靠地跨设备执行命令，将 AI 助手的能力延伸到任何联网设备。无论是远程服务器管理、本地设备控制，还是移动设备交互，Node 服务都提供了统一的接口和强大的能力。
按照本文的部署步骤，你可以在 10 分钟内完成 Node Host 的部署和配置，开始享受跨设备自动化带来的便利。
参考资料：
作者：云中仙
编辑：2026-04-01
版本：v1.0
