Linux systemd 下 OpenClaw 网关与使用者环境变量示意

2026 年 OpenClaw 在 Linux systemd 上升級後「閘道器能起但設定像空的」：service 環境（HOME/User）漂移、舊路徑殘留與依官方 Troubleshooting 的合併恢復閉環

在非登入型 systemd 使用者單元裡跑 openclaw gateway 時，升級後常出現程序 active 但面板像空設定：多半是 HOME/XDG 與互動式 shell 不一致，或舊 json 未合併到新預設路徑。本文給三分層＋環境核對＋合併快照＋ doctor 階梯，並聯 split brain、Docker 權杖、macOS gateway restart 專文邊界。

目錄

1. 現象三分層：进程在 / RPC 不通 / 設定空壳

进程层：systemctl --user status 为 active，ss 也能看到监听端口，但不代表读到了你熟悉的 openclaw.json。User 单元若未设置 WorkingDirectory 或 HOME，Node 侧可能回落到包内默认目錄并生成空壳設定树。

RPC 层：openclaw gateway status 若 build 與 CLI semver 不一致，应优先对照《split brain 與 meta.lastTouchedVersion》，而不是先删整个 ~/.openclaw。

設定壳层：目錄存在但 plugins、channels 块像被「重置」，常见是写到另一份 XDG_CONFIG_HOME；升級脚本若改动默认搜索顺序，旧文件仍躺在上一大版本路径里，看起来像「升級吃設定」。

  1. journal：搜 ENOENT、HOME、config path。
  2. 三路径 diff：登录 shell、非登录、systemctl --user show 的 Environment。
  3. 先 tar 快照再合併，避免不可逆误操作。

2. status→gateway status→logs→doctor 阶梯

与《官方 gateway probe 阶梯》一致：先证 RPC/监听再 doctor，避免把 HOME 漂移误判为 429 或插件 shape。doctor 修复前后各跑一次 gateway status 写入变更单。

3. 决策矩阵：仅重启 vs 合併 vs install --force

用于升級窗口分钟级决策；多机 fleet 先冻结镜像再滚动。

症状签名 首选动作 风险
Environment 缺 HOME，設定落在 /tmp 或包内 drop-in 补 HOME/WorkingDirectory 后重启 低：可回滚单元
旧路径仍有完整 json，新路径 skeleton 合併 + 提升 meta 版本記錄 中：合併冲突需人工 diff
CLI 與 gateway semver 分裂且 doctor 报 install gateway install 或 --force（变更窗内） 高：改写服务文件

4. How-to：七步合併与验证清单

服务名以单元 Id= 为准；维护窗口执行并留审计副本。

# 1) 查看使用者单元实际环境（示例）
systemctl --user show openclaw-gateway.service -p Environment -p WorkingDirectory

# 2) 与交互 shell 对照
echo "$HOME" "$XDG_CONFIG_HOME"

# 3) 快照（示例路径请按主机调整）
tar czf ~/openclaw-premerge-$(date +%Y%m%d%H%M).tgz ~/.openclaw ~/.config/openclaw 2>/dev/null
  1. 冻结并发：禁并行 install 與 vim 同一 json。
  2. 导出 root/登录/单元三份 env。
  3. 以 gateway status 的 config root 为准。
  4. channels、credentials、plugins 分块合併。
  5. doctor 后复验 status 與 channels。
  6. 无头场景核对 loginctl linger。
  7. 变更单记 semver、drop-in 哈希、回滚 tar。

5. 可引用检查项与环境对照表

可打印进值班手册。

检查项 命令/线索 期望
User 单元 HOMEsystemctl --user show与拥有設定的使用者主目錄一致
lingerloginctl show-user无头场景下会话不随 SSH 断开而灭
journal 关键字journalctl --user -u无持续 ENOENT 读設定

6. 與 split brain、Docker、macOS 文的边界

split brain管 CLI/守护 semver 與 meta，可與 HOME 漂移叠加，先版本后路径。《Docker Compose 令牌》属容器平面，与裸 User 单元 drop-in 不同。

macOS 见《gateway restart》：plist/Node 前缀；Linux 重 User、WorkingDirectory、linger。

7. FAQ

问：能否直接删除 skeleton 再 cp 旧文件？答：可以但务必先快照并停服务，避免运行中半写 json；更稳妥是分块 merge 并跑 doctor。

问：root 与同名使用者各跑一份网关会怎样？答：端口与設定根都会冲突；请在单元里用 User= 明确属主并禁用多余副本。

问：升級频率高的小团队如何减负？答：把可重复环境交给托管平面，减少自建机上「人肉合併」次数；见下文。

8. 总结与遠端 Mac 託管收束

要「读对設定」须把 HOME/XDG 与单元写入同一真相源，用官方阶梯验 RPC，而非盲重启。

自建仍要人盯 drop-in、镜像与合併纪律；高频升級下漂移会复发。

若要把网关稳定与目錄隔离迁到对齐 Apple 生态的远程 Mac 托管，见 SFTPMAC 远程 Mac 租赁 与帮助中心，收敛升級空設定类问题。