OpenClaw 日常运维 Runbook：Gateway 18789 巡检、灰度升级回滚与日志磁盘规划（2026）- Hashvps

先把三条运维原则装进肌肉记忆，再读正文：

探针双验，IO 不误判

curl 探 18789 之前先用 lsof 确认端口归属；Dashboard 卡顿先查盘 IO，不要把写日志高峰误读成网关故障。

curl + lsof
灰度升级，30 分钟回滚窗口

冻结版本号 → 黄金样机先行 → 再滚生产；tarball 备份与旧 plist 路径同时还原，回滚不超过 30 分钟。

≤ 30 min
日志与根盘分离

日志目录与 npm cache 独立挂载或独立 logrotate 轮转，防止静默写满根盘导致 Gateway 异常退出。

logrotate 7d

本篇只回答一个问题

OpenClaw 安装脚本跑完、Gateway 18789 首次冒绿灯之后，团队往往进入一段「跑着跑着出问题、出了问题没 Runbook」的阶段：网关偶尔 401、升级后有一台行为不一致、日志把根盘写满导致 Gateway 静默退出。这些都不是安装文档要解决的问题。

本篇只回答一个问题：如何把 OpenClaw 的日常运维动作标准化成一份可以复用的 Runbook，让任何一名团队成员接手都能在 15 分钟内完成巡检或回滚？覆盖范围：Gateway 健康巡检 → 灰度升级策略 → 回滚流程 → Tailscale / SSH 传输选择 → 日志磁盘规划。安装与首次 onboard 见 OpenClaw 2026 安装与 onboard 完全指南；通道首通与产线排障见 OpenClaw 远程 Mac Channels 首通与产线排障。

1. Gateway 18789 健康巡检

很多团队的「巡检」只有一条 curl，这不够。Gateway 在端口被占用或 launchd 没有正确拉起时，curl 会挂起而不是立即失败。标准巡检要同时跑 curl 和 lsof，分别验证响应与端口归属。

Gateway 探活双检（每日巡检可加入 cron）

# 1. HTTP 探活：期望 200，输出 fail 则警报
curl -fsS --max-time 3 http://127.0.0.1:18789/health \
  && echo "gateway OK" || echo "GATEWAY FAIL"

# 2. 端口归属确认：pid 应属 node/openclaw 进程
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 3. 最近 50 行错误日志（路径按实际安装目录）
tail -n 50 ~/.openclaw/logs/gateway.log | grep -i "error\|warn\|exit"

如果 curl 返回 200 但 Dashboard 仍然卡顿，优先排查盘 IO：iostat -d 1 5 看写入峰值。把日志写高峰误判为网关故障是最常见的假警报来源。固定一台「黄金样机」机器与生产保持同版本，当本机巡检出现异常时，先用黄金样机对比，可以快速排除环境差异。

18789 端口被占用时的快速排查

如果 lsof -iTCP:18789 返回的 pid 不是 OpenClaw 进程，先用 launchctl list | grep openclaw 确认服务状态，再考虑是否有残留旧版本进程没有被 bootout 干净。直接 kill 占用进程而不清理 plist 会导致 launchd 在下次登录时重新拉起。

2. 升级前三件事：版本冻结、黄金样机与盘余检查

OpenClaw 的版本迭代频率较高，不加节制地跟随最新版本会带来两类风险：配置键变更导致 Gateway 启动失败，以及新版本与已有 Channel 配置不兼容。灰度升级是标准做法，但很多团队把「灰度」理解成「先升一台看看」，忽略了升级前的版本冻结和盘余检查。

升级前三件事对照：做与不做的差异
检查项	做了标准灰度流程	没做直接 npm update
版本冻结（记录当前 tag）	回滚时直接 `npm install openclaw@旧tag`	不知道旧版本号，只能 tarball 恢复
黄金样机先行	异常隔离在测试节点，生产不受影响	全量失败，所有通道同时断
根盘余量 ≥15%	npm install 的临时文件有足够空间	安装中途写满盘，留下半残状态

升级前的版本冻结包含三条记录：当前 npm 包版本号（npm list -g openclaw）、plist 文件绝对路径和当前配置 tarball。这三条信息存入团队 wiki 或 Notion，回滚时不用临时翻记录。黄金样机与生产部署保持逻辑隔离，可以是同一机房的另一台节点，也可以是同一台机器上的独立 workspace 路径；关键是升级后先跑完整 doctor 检查再切流量。

升级前版本快照（写入 wiki 或 .upgrade-memo）

# 记录当前版本
npm list -g openclaw --depth=0 > .upgrade-memo

# 打包当前配置（路径按实际目录）
tar czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/config/ \
  ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 确认盘余量 ≥15%
df -h / | awk 'NR==2 {print "根盘可用："$4, "已用："$5}'

3. 回滚：tarball + plist 二合一恢复流程

回滚失败最常见的原因不是二进制版本没降回去，而是配置键与旧版本不兼容——新版本升级时可能新增了必填字段，回滚二进制后旧配置反而触发 Gateway 启动报错。正确的回滚顺序是：先 bootout 服务 → 还原 tarball 配置 → 降级二进制 → 重新 bootstrap。

回滚完整流程（≤30 分钟）

# 步骤 1：停止当前服务
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 步骤 2：还原配置 tarball
tar xzf openclaw-config-20260604.tar.gz -C /

# 步骤 3：降级 npm 包到冻结版本
npm install -g openclaw@1.x.x   # 替换为记录的旧版本号

# 步骤 4：重新启动服务
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 步骤 5：验证（等待约 10 秒）
sleep 10 && curl -fsS http://127.0.0.1:18789/health && echo "回滚成功"

如果 plist 路径在升级过程中发生了变化（新版本的安装脚本有时会修改 plist 的 ProgramArguments 路径），bootout 时需要指向新 plist 路径，bootstrap 时使用还原后的旧 plist。两步的路径不一定相同，这是回滚时最容易踩的坑。建议在升级前用 diff 比对新旧 plist，把差异记录在 upgrade-memo 里。

4. Tailscale 与 SSH/rsync：什么场景用哪个

团队常见的争论是「我们该用 Tailscale 还是直连 SSH」。实际上两者不互斥，适合的场景不同。Tailscale 的核心价值是多终端、跨区的随身访问，无需配置防火墙规则；SSH/rsync 的核心价值是大文件批量传输，速度瓶颈在出口带宽而不是协议开销。

Tailscale vs SSH/rsync 决策矩阵
维度	Tailscale WireGuard 隧道	SSH / rsync 直连 + 加密传输
推荐场景	随身设备打开 Dashboard、团队多人远程访问、跨区 VPN 控制面	CI 制品下载、日志包批量拉取、TB 级大文件定期同步
延迟特性	DERP 中转时延迟略高（~50ms 亚太←→加拿大），直连时接近裸 RTT	裸 TCP，延迟低；但需要端口开放或跳板
带宽消耗	协议开销约 +5%，适合持续低流量会话	建议 `--bwlimit` 限速，防止打满加拿大出口
权限管理	Tailscale ACL 按设备/用户精细控制	SSH key 管理，`authorized_keys` 需定期审计
排障入口	ACL 规则、DERP 节点、MagicDNS 解析	路由可达性、MTU、连接超时与断点续传

实际推荐组合：日常看 Dashboard 和运维操作走 Tailscale tailnet，保持多终端随时可接入；定期日志包、CI 制品下载走 SSH + rsync 并加 --bwlimit=50000（约 50 MB/s），避免单次大文件传输打满加拿大节点的出口影响其他 Channel 的正常流量。两条路径同时保留，互为备用。

rsync 限速示例（防止打满出口）

# 从加拿大节点拉取日志包，限速 50 MB/s，断点续传
rsync -avz --bwlimit=50000 --partial \
  user@canada-m4.hashvps.com:~/.openclaw/logs/archive/ \
  ./local-logs/

# 验证 Tailscale 直连状态（非 DERP 中转）
tailscale ping canada-m4 --until-direct

5. 日志磁盘规划：logrotate 配置与分区建议

Gateway 异常退出有相当一部分原因是根盘写满。OpenClaw 默认把日志写在用户目录下，而 npm 全局 cache 也在同一个卷上；两者叠加，加上 Xcode 导出或 CI 制品临时文件，几周内就可以把一块 512GB 的盘填满。分盘或独立 logrotate 是解决方案，而不是「定期手动 rm」。

最直接的解法是为日志目录单独配置 logrotate，每 7 天轮转一次，保留最近 4 份，并对 npm cache 设置大小上限：

~/.openclaw/logrotate.conf（按实际路径调整）

/Users/mac/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    dateext
    copytruncate
}

# 加入 crontab（每天凌晨 3 点执行）
# crontab -e 里添加：
# 0 3 * * * /usr/local/bin/logrotate /Users/mac/.openclaw/logrotate.conf

对于 npm cache，可用 npm config set cache-max 10240 限制缓存不超过 10GB，同时在升级完成后执行 npm cache clean --force 清理升级遗留的旧包缓存。如果机器配置是 1TB 盘，推荐把 ~/.openclaw/logs 和 npm cache 移至独立的卷或磁盘分区，与根盘完全隔离；即使日志意外暴涨，也不会影响 Gateway 进程的运行。加拿大 M4 节点的 1TB 配置下，建议预留 100GB 给日志与 cache，剩余空间给 Xcode 制品和 LFS。

6. FAQ：六个高频运维问题

Gateway 18789 健康检查返回非 200，第一步查哪里？

先跑 lsof -nP -iTCP:18789 -sTCP:LISTEN 确认端口是否在监听。如果没有输出，说明进程没起来，用 launchctl list | grep openclaw 看 launchd 状态，再查 ~/.openclaw/logs/gateway.log 最后 50 行的错误原因。如果端口在监听但 HTTP 返回 500，通常是配置键错误，对比升级前的 config tarball。

回滚后 plist 路径需要手动修改吗？

取决于升级时 plist 是否有改动。如果只是 npm 包版本升级而安装脚本没有重写 plist，还原 tarball 后路径不变。如果新版本的安装脚本修改了 ProgramArguments（通常是二进制路径变了），还原后需要手动把 plist 里的路径改回旧版二进制的位置，再执行 bootstrap。这就是为什么升级前要 diff 新旧 plist。

多台节点同时升级还是逐台？

强烈建议逐台。先升黄金样机，观察 24 小时内的 Gateway 健康和 Channel SLA；无异常后再逐台滚动生产节点，每台间隔至少 30 分钟。全量同时升级的风险是：如果新版本存在配置不兼容，所有节点同时失败，没有对照组。

Dashboard 显示 CPU 100%，是 OpenClaw 本身的问题吗？

不一定。先用 top -o cpu 或 Activity Monitor 定位实际耗 CPU 的 pid。OpenClaw 的 Gateway 进程在正常状态下 CPU 占用应在 1-5% 以内；如果是 node 进程占高，检查是否有大量 Channel 请求积压或日志写入异常。另一个常见原因是 Xcode 构建进程与 OpenClaw 进程共享资源，Dedicated Mac mini 可以通过 nice/renice 调整优先级。

Tailscale 连接上了，但 Dashboard 仍然无法访问？

检查 Tailscale ACL 是否允许该设备访问 18789 端口（默认 ACL 不限制端口，但有定制 ACL 的团队需要确认）。其次确认 MagicDNS 是否解析正确，用 tailscale ip -4 拿到 tailnet IP 后直接 curl 该 IP:18789 测试。如果直接 IP 能通而 MagicDNS 不行，是 DNS 解析问题而不是 Gateway 问题。

logrotate 执行后日志文件消失，Gateway 还在写入吗？

使用了 copytruncate 选项时，logrotate 先复制文件再清零原文件，进程的文件描述符不变，不会出现「找不到日志句柄」的问题。如果用的是默认 create 模式，需要给 Gateway 发送 SIGHUP 信号让它重新打开日志文件，或者在 logrotate 配置里加 postrotate 脚本执行 launchctl kickstart。推荐用 copytruncate 避免服务中断。