OpenClaw 节点部署完整教程 - 从零到开机自启动

前言

折腾了整整一晚上，终于成功将 Mac mini 节点连接到远程 OpenClaw Gateway。中间踩了无数坑，写下这篇完整教程，确保后续设备能一次成功。

问题背景

OpenClaw 是一个自托管的 AI 助手网关系统，支持多节点分布式部署。但在实际配置中遇到以下挑战：

  1. Gateway 默认绑定 loopback - 只能本地访问
  2. Tailscale DNS 解析问题 - 部分设备无法解析 MagicDNS
  3. 配对机制 - 首次连接需要服务器批准，但请求在断开后被删除

解决方案架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
┌─────────────────────────────────────────────────────────────┐
│                         服务器端                              │
│                                                              │
│  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐ │
│  │  Gateway    │◄────►│   socat     │◄────►│  Tailscale  │ │
│  │ 127.0.0.1   │      │ 转发        │      │   网络      │ │
│  │   :18789    │      │ 18790→18789 │      │             │ │
│  └─────────────┘      └─────────────┘      └─────────────┘ │
│                              ▲                               │
└──────────────────────────────│───────────────────────────────┘
                               │
                          Tailscale
                            网络
                               │
┌──────────────────────────────│───────────────────────────────┐
│                         节点端                                │
│                              ▼                               │
│  ┌─────────────┐      ┌─────────────┐                       │
│  │ OpenClaw    │◄────►│  Tailscale  │                       │
│  │ Node        │      │   客户端    │                       │
│  └─────────────┘      └─────────────┘                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

核心原理：

  1. Gateway 保持绑定 127.0.0.1:18789 (loopback)
  2. 使用 socat 将 Tailscale IP:18790 转发到 127.0.0.1:18789
  3. 节点通过 Tailscale IP:18790 连接 Gateway

第一步：服务器端配置

1.1 Gateway 基础配置

1
2
3
4
5
6
7
8
# Gateway 保持 loopback 绑定
openclaw config set gateway.bind loopback
openclaw gateway restart

# 验证 Gateway 状态
openclaw gateway status | grep -E "bind|Listening"
# 输出: Gateway: bind=loopback (127.0.0.1), port=18789
# 输出: Listening: 127.0.0.1:18789

1.2 获取 Gateway Token

1
2
3
4
5
6
# 查看当前 Token
cat ~/.openclaw/openclaw.json | grep -A5 '"auth"' | grep token

# 如果需要生成新 Token
openclaw config set gateway.auth.token YOUR_NEW_TOKEN
openclaw gateway restart

重要： 请妥善保管 Gateway Token，不要泄露到公开渠道。

1.3 启动 socat 端口转发

1
2
3
4
5
6
7
8
9
10
11
12
# 检查 Tailscale IP
tailscale ip -4
# 输出示例: 100.x.x.x（Tailscale 分配的私有 IP）

# 启动 socat 转发（替换为你的 Tailscale IP）
GATEWAY_TS_IP=$(tailscale ip -4)
nohup socat TCP-LISTEN:18790,bind=$GATEWAY_TS_IP,fork,reuseaddr TCP:127.0.0.1:18789 > /tmp/socat-tailscale.log 2>&1 &

# 验证端口
ss -tlnp | grep -E "18789|18790"
# 输出: LISTEN 127.0.0.1:18789 (Gateway)
# 输出: LISTEN <TS_IP>:18790 (socat)

1.4 socat 持久化（开机自启动）

创建 systemd 服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 获取 Tailscale IP
GATEWAY_TS_IP=$(tailscale ip -4)

# 创建服务文件
sudo tee /etc/systemd/system/openclaw-socat.service > /dev/null << EOF
[Unit]
Description=OpenClaw socat port forward
After=network.target tailscaled.service
Requires=tailscaled.service

[Service]
Type=simple
ExecStart=/usr/bin/socat TCP-LISTEN:18790,bind=$GATEWAY_TS_IP,fork,reuseaddr TCP:127.0.0.1:18789
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable openclaw-socat
sudo systemctl start openclaw-socat

# 验证
sudo systemctl status openclaw-socat

第二步：节点端配置

2.1 安装 Tailscale

macOS:

1
2
brew install tailscale
# 或从 App Store 安装

Linux:

1
curl -fsSL https://tailscale.com/install.sh | sh

2.2 登录 Tailscale

1
2
3
4
5
6
7
8
# 登录 Tailscale
tailscale login

# 验证连接
tailscale status

# 测试连通性（替换为服务器 Tailscale IP）
tailscale ping <GATEWAY_TS_IP>

2.3 安装 OpenClaw CLI

macOS:

1
brew install openclaw

Linux:

1
npm install -g openclaw

2.4 首次连接

1
2
3
4
5
6
7
8
# 设置 Gateway Token（替换为你的 Token）
export OPENCLAW_GATEWAY_TOKEN=YOUR_GATEWAY_TOKEN

# 连接 Gateway（替换 IP 和名称）
openclaw node run \
  --host <GATEWAY_TS_IP> \
  --port 18790 \
  --display-name "YOUR_NODE_NAME"

首次连接会显示：

1
node host gateway connect failed: pairing required

这是正常的！ 表示连接成功，等待服务器批准配对。

第三步：服务器端批准配对

节点发起连接后，在服务器端执行：

1
2
3
4
5
# 查看待批准设备
openclaw devices list

# 批准设备（替换为实际的 Request ID）
openclaw devices approve <request-id>

第四步：节点端重新连接

批准后，节点端重新执行连接命令：

1
2
3
4
5
6
export OPENCLAW_GATEWAY_TOKEN=YOUR_GATEWAY_TOKEN

openclaw node run \
  --host <GATEWAY_TS_IP> \
  --port 18790 \
  --display-name "YOUR_NODE_NAME"

成功标志：

  • 不再显示 pairing required
  • 连接保持活跃，终端不会退出

第五步：配置节点开机自启动

macOS (launchd)

创建 LaunchAgent 配置文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# 替换以下占位符：
# YOUR_GATEWAY_IP - 服务器 Tailscale IP
# YOUR_NODE_NAME - 节点名称
# YOUR_GATEWAY_TOKEN - Gateway Token

cat > ~/Library/LaunchAgents/com.openclaw.node.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.node</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/openclaw</string>
        <string>node</string>
        <string>run</string>
        <string>--host</string>
        <string>YOUR_GATEWAY_IP</string>
        <string>--port</string>
        <string>18790</string>
        <string>--display-name</string>
        <string>YOUR_NODE_NAME</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>OPENCLAW_GATEWAY_TOKEN</key>
        <string>YOUR_GATEWAY_TOKEN</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/openclaw-node.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/openclaw-node.error.log</string>
</dict>
</plist>
EOF

管理服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 加载服务
launchctl load ~/Library/LaunchAgents/com.openclaw.node.plist

# 验证服务状态
launchctl list | grep openclaw

# 查看日志
tail -f /tmp/openclaw-node.log

# 停止服务
launchctl unload ~/Library/LaunchAgents/com.openclaw.node.plist

# 重启服务
launchctl unload ~/Library/LaunchAgents/com.openclaw.node.plist
launchctl load ~/Library/LaunchAgents/com.openclaw.node.plist

Linux (systemd)

创建服务文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 替换占位符后创建服务
sudo tee /etc/systemd/system/openclaw-node.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Node
After=network.target tailscaled.service
Requires=tailscaled.service

[Service]
Type=simple
Environment="OPENCLAW_GATEWAY_TOKEN=YOUR_GATEWAY_TOKEN"
ExecStart=/usr/local/bin/openclaw node run --host YOUR_GATEWAY_IP --port 18790 --display-name "YOUR_NODE_NAME"
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable openclaw-node
sudo systemctl start openclaw-node

# 查看状态
sudo systemctl status openclaw-node

# 查看日志
journalctl -u openclaw-node -f

常见问题

Q1: 显示 ECONNREFUSED

原因： Gateway 未运行或 socat 未启动

解决：

1
2
3
4
5
6
7
8
9
10
# 检查 Gateway 状态
openclaw gateway status

# 检查 socat 进程
ps aux | grep socat

# 重启 socat
pkill socat
GATEWAY_TS_IP=$(tailscale ip -4)
nohup socat TCP-LISTEN:18790,bind=$GATEWAY_TS_IP,fork,reuseaddr TCP:127.0.0.1:18789 > /tmp/socat.log 2>&1 &

Q2: 显示 pairing required 但服务器看不到设备

原因： 配对请求在断开后被删除

解决：

  1. 节点保持连接状态（不要退出）
  2. 服务器立即执行 openclaw devices list
  3. 批准后节点重新连接

Q3: 显示 gateway token mismatch

原因： Token 不正确

解决：

1
2
3
4
5
# 服务器端查看正确 Token
cat ~/.openclaw/openclaw.json | grep -A5 '"auth"' | grep token

# 节点端使用正确 Token
export OPENCLAW_GATEWAY_TOKEN=<正确的 Token>

Q4: Tailscale DNS 无法解析

解决： 直接使用 Tailscale IP 地址，不使用域名

1
2
3
4
5
# 获取服务器 Tailscale IP
tailscale ip -4  # 在服务器上执行

# 节点连接时使用 IP
openclaw node run --host <IP> --port 18790 --display-name "NAME"

Q5: 节点重启后无法自动连接

解决：

1
2
3
4
5
6
7
8
9
# macOS 检查服务
launchctl list | grep openclaw

# Linux 检查服务
sudo systemctl status openclaw-node

# 查看日志排查问题
tail -f /tmp/openclaw-node.log  # macOS
journalctl -u openclaw-node -f   # Linux

配置清单

服务器端

  • Gateway 正在运行 (openclaw gateway status)
  • Gateway Token 已设置
  • Tailscale 正在运行 (tailscale status)
  • socat 转发正在运行 (ss -tlnp | grep 18790)
  • socat systemd 服务已启用

节点端

  • Tailscale 已安装并登录
  • 可以 ping 通服务器 Tailscale IP
  • OpenClaw CLI 已安装
  • Gateway Token 已设置
  • 首次连接后已在服务器端批准
  • LaunchAgent/systemd 服务已配置

快速命令参考

服务器端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Gateway 管理
openclaw gateway status          # 查看状态
openclaw gateway restart         # 重启
openclaw gateway stop            # 停止
openclaw gateway start           # 启动

# 节点管理
openclaw nodes status            # 查看节点状态
openclaw devices list            # 查看设备列表
openclaw devices approve <id>    # 批准设备
openclaw devices remove <id>     # 移除设备

# 配置管理
openclaw config set gateway.bind loopback
openclaw config set gateway.auth.token <token>

# 端口检查
ss -tlnp | grep -E "18789|18790"
ps aux | grep socat

节点端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 连接管理
export OPENCLAW_GATEWAY_TOKEN=<token>
openclaw node run --host <ip> --port <port> --display-name "<name>"
openclaw node status             # 查看状态
openclaw node stop               # 停止

# Tailscale 管理
tailscale status                 # 查看状态
tailscale ping <ip>              # 测试连接
tailscale ip -4                  # 查看本机 IP

# macOS LaunchAgent 管理
launchctl load ~/Library/LaunchAgents/com.openclaw.node.plist    # 加载
launchctl unload ~/Library/LaunchAgents/com.openclaw.node.plist  # 卸载
launchctl list | grep openclaw                                    # 查看状态

# Linux systemd 管理
sudo systemctl start openclaw-node     # 启动
sudo systemctl stop openclaw-node      # 停止
sudo systemctl restart openclaw-node   # 重启
sudo systemctl status openclaw-node    # 查看状态

安全提醒

  1. Gateway Token - 不要泄露到公开渠道
  2. Tailscale IP - 只在 Tailnet 内部有效，但仍需保护
  3. 防火墙 - 确保只开放必要端口
  4. 定期更新 - 保持 OpenClaw 和 Tailscale 版本最新

总结

配置 OpenClaw 节点的关键在于：

  1. 理解网络架构 - Gateway 绑定 loopback，需要 socat 转发
  2. 配对流程 - 首次连接需要服务器批准
  3. 持久化配置 - 服务器 socat + 节点 LaunchAgent/systemd

按照本教程操作，后续设备应该能一次成功。

相关文档：

技术实践
#OpenClaw #Tailscale #节点管理 #DevOps
OpenClaw 节点部署完整教程 - 从零到开机自启动
https://dapalm.com/2026/03/14/2026-03-14-OpenClaw节点部署完整教程-从零到开机自启动/
作者
Mars
发布于
2026年3月14日
许可协议