OpenClaw 子节点升级后持久化连接修复指南

适用版本:节点 OpenClaw 2026.8.2(升级自 2026.6.x) 症状:升级后旧的 openclaw-node.service 失效,节点反复重启无法连接网关,只能靠前台 openclaw node run --pair 临时连接,关闭终端即断开。

一、故障原因

升级到新版后,旧 systemd 服务失效通常由三个问题叠加导致:

1. 配置文件校验失败:旧版留下的 ~/.openclaw/openclaw.json 含已废弃的键(如 meta.lastTouchedAt),新版启动时直接退出(status=1),systemd 无限重启。
2. 文件属主错误:如果曾用 sudo 运行过 doctor/服务,~/.openclaw/ 下的 openclaw.json、state/openclaw.sqlite 等会变成 root 属主,普通用户读取报 EACCES。
3. TLS 自签证书校验:网关使用自签证书时,必须带 --tls-fingerprint <sha256>,否则报 self-signed certificate 连接失败。

二、修复步骤

以下命令均在节点机器上执行,假设:

• 网关地址:192.168.3.39:18789(TLS)
• 节点用户:lishewen(按实际替换)

1. 以节点用户身份修复配置

# 先修属主(若之前用过 sudo,文件会变成 root)sudochown -R lishewen:lishewen ~/.openclaw# 修复废弃配置键sudo -u lishewen openclaw doctor --fixsudo -u lishewen openclaw config validate   # 应输出 "Config valid"

⚠️ doctor 一定要用 sudo -u <user> 以节点用户身份跑,直接 sudo openclaw doctor --fix 会把配置文件写成 root 属主,引发新的权限问题。

2. 获取网关 TLS 证书指纹

在网关机器上执行(或在任一能访问网关的机器上):

echo | openssl s_client -connect 192.168.3.39:18789 2>/dev/null \  | openssl x509 -noout -fingerprint -sha256 | cut -d= -f2 | tr -d ':' | tr'A-F''a-f'

输出形如 9288130c2c90b7b14453398a...(64 位小写十六进制)。

3. 修复 systemd 目录权限并重装服务

新版安装器会拒绝 group/world-writable 的服务目录:

chmod go-w ~/.config ~/.config/systemd ~/.config/systemd/user ~/.config/systemd/user/* ~

重装为用户级服务(旧的系统级 /etc/systemd/system/openclaw-node.service 会被替代):

sudo -u lishewen openclaw node install --force \  --host 192.168.3.39 --port 18789 \  --tls --tls-fingerprint <上一步的指纹> \  --display-name "节点名称"

4. 启用 lingering + 启动服务

sudo loginctl enable-linger lishewen   # 注销 SSH 后服务不停# 停掉并移除旧的系统级服务(若存在)sudo systemctl disable --now openclaw-node# 启动用户级服务sudo -u lishewen XDG_RUNTIME_DIR=/run/user/$(id -u lishewen) systemctl --user daemon-reloadsudo -u lishewen XDG_RUNTIME_DIR=/run/user/$(id -u lishewen) systemctl --user enable --now openclaw-node

5. 网关侧批准配对

新服务使用新的设备身份,首次连接会报 pairing required。在网关机器上:

openclaw devices list                                    # 找到 Pending 的 requestIdopenclaw devices approve <requestId>                     # 设备配对审批openclaw nodes pending                                   # 能力清单审批(如提示)openclaw nodes approve <capabilityRequestId>sudo -u lishewen XDG_RUNTIME_DIR=/run/user/1000 systemctl --user restart openclaw-node  # 节点上重启

6. 验证

节点上:

systemctl --user is-active openclaw-node                # activejournalctl --user -u openclaw-node -n 5 --no-pager      # 应有 "gateway connected: wss://..."

网关上:

openclaw nodes status    # 节点显示 paired · connected

三、日常管理命令

systemctl --user restart openclaw-node    # 重启systemctl --user stop openclaw-node       # 停止journalctl --user -u openclaw-node -f     # 实时日志openclaw node status                      # 服务状态概览

四、常见错误速查