整理说明：本记录通过小龙虾OpenClaw依据本地记忆文件、历史会话记录和当前运行配置整理，重点保留可复用的安装步骤、故障现象、根因判断和解决办法。
一、环境概况
操作系统：Ubuntu 22.04.5 LTS
OpenClaw 状态目录：/home/node/.openclaw
工作目录：/home/node/.openclaw/workspace
运行时 Node：已迁移为系统 Node，node / npm / openclaw 解析到 /usr/bin 下的系统安装版本。
OpenClaw 版本线索：配置中 lastTouchedVersion 为 2026.3.13；运行状态里显示 Node 24.14.0。
主要接入方式：Gateway + QQ Bot。
二、安装与部署过程梳理
1. 基础安装思路
本次环境最终采用"系统级 Node + OpenClaw + systemd 管理 Gateway 服务"的方式，而不是继续依赖 nvm 下的 Node 运行。
整理后的推荐安装顺序如下：
（1）准备系统环境：确保 Ubuntu 22.04.5 LTS 可正常使用 apt，建议 root 或具备 sudo 权限。
（2）安装系统级 Node.js 与 npm，保证 node、npm 可直接从系统 PATH 调用。
（3）全局安装 OpenClaw，使 openclaw 命令可直接使用。
（4）初始化 /home/node/.openclaw 下的配置与 workspace。
（5）通过 systemd 安装并管理 gateway 服务，确保开机自启、可探活、可重启。
（6）根据需要接入 QQ Bot，并在 openclaw.json 中写入 appId、clientSecret 等配置。
2. 实际落地后的结构
OpenClaw 的配置文件位于 /home/node/.openclaw/openclaw.json。
Gateway 通过 systemd 管理；后续排查中多次使用 openclaw gateway status、openclaw status 以及 systemctl 进行状态确认。
QQ Bot 接入已成功，日志中可以看到获取 access token、发送消息、接收 C2C_MESSAGE_CREATE 事件等正常行为。
三、安装和使用过程中遇到的主要问题
问题 1：OpenClaw 运行最初依赖 nvm，后续需要迁移到系统 Node
现象：运行环境混用 nvm 路径和系统路径，Gateway 服务的 Node 来源不够统一，后期维护和 systemd 管理容易出现偏差。
根因：OpenClaw 初期依附于用户环境中的 nvm Node；而 systemd 服务更适合绑定稳定的系统级 Node 路径。
解决方法：将 OpenClaw 运行时迁移到系统 Node，确认 node、npm、openclaw 都解析到 /usr/bin；同时让 Gateway 服务也使用系统 Node。
结果：运行时来源统一，后续对 systemd、PATH、服务状态的判断更稳定。
问题 2：Gateway 的 systemd 管理存在 user scope 与 system scope 混淆
现象：机器上曾同时存在用户态 unit 残留和系统级 unit，CLI 对服务状态的识别被误导。
典型表现：虽然实际服务已经 running，但 openclaw gateway status 在某些阶段仍然显示异常或误判，尤其容易偏向 systemctl --user。
根因：同名服务同时存在于 ~/.config/systemd/user/ 与 /etc/systemd/system/，CLI 在 scope 识别上受到残留 unit 干扰。
解决方法：
（1）明确采用 root + 系统级 systemd 方案。
（2）备份或移除用户态残留 unit，避免继续误判。
（3）修正 OpenClaw 对 Linux systemd scope 的识别逻辑，使其在 user bus 不可用时回退到系统级 systemctl。
结果：服务层恢复清晰，systemd 管理链路能够围绕系统级 unit 正常工作。
问题 3：控制台或状态页偶发显示异常，日志提示 missing scope: operator.read
现象：Gateway 实际正常，但控制台某些状态读取失败，容易让人误以为服务不可用。
日志特征：status、system-presence、config.get 等请求返回 missing scope: operator.read。
根因：当前连接到 control UI / webchat 的会话权限不具备 operator.read，对"查看类信息"有限制。
解决方法：把这类现象与"服务真的挂了"区分开。先用 openclaw gateway status、RPC probe、监听端口、日志确认服务本身是否正常，再单独处理控制台权限问题。
结果：明确了这是"权限视角问题"，不是 Gateway 本身宕机。
问题 4：为了提升安全性而启用 sandbox 后，机器没有 Docker，导致 agent 无法回复
现象：QQ 私聊和主会话都出现 agent failed before reply，无法正常回答。
报错特征：Sandbox mode requires Docker, but the docker command was not found in PATH。
根因：配置把 agents.defaults.sandbox.mode 调成了 all，但当前机器没有安装 Docker。
解决方法：
方案 A：安装 Docker，并确保 docker 命令在 PATH 中可用。
方案 B：如果当前机器不准备安装 Docker，则把 agents.defaults.sandbox.mode 改回 off，避免嵌入式 agent 直接失败。
经验结论：在 Ubuntu 服务器上启用 OpenClaw sandbox 前，必须先确认 Docker 已安装且服务可用，否则会直接影响消息回复。
问题 5：QQ 通道安全收紧后，allowFrom 为空会导致私聊被全部拦截
现象：为了避免 QQ 来源全开放，配置把 dmPolicy 调成 allowlist，但 allowFrom 为空。
日志与 doctor 提示：channels.qqbot.dmPolicy is allowlist but allowFrom is empty --- all DMs will be blocked。
根因：安全策略收紧后，没有把实际需要放行的 QQ 用户 ID 加回白名单。
解决方法：将需要使用的 QQ sender ID 精确加入 channels.qqbot.allowFrom；如果已有配对记录，也可使用 openclaw doctor --fix 协助迁移。
结果：QQ 私聊既能恢复可用，又避免像 ["*"] 那样完全开放。
问题 6：系统环境维修期间，MySQL 异常拖慢了 OpenClaw 所在主机的整体部署节奏
现象：apt / dpkg 被卡住，mysql-server-8.0 长期 half-configured，日志反复出现 1396 Operation ALTER USER failed for root@localhost。
根因：升级用的临时 MySQL 实例里只有 root@% ，缺少 root@localhost，导致 postinst 脚本执行 ALTER USER 失败。
解决方法：
（1）先区分正式 mysql.service 与升级拉起的临时实例。
（2）清理互相抢锁的维护 / 临时 mysqld。
（3）连接升级临时 socket，检查 mysql.user。
（4）如果只有 root@% ，则复制补出 root@localhost。
（5）恢复正式 mysql.service，并用 systemctl status mysql、mysqladmin ping 验证。
（6）最后用完整 root PATH 重跑 dpkg --configure -a 和 apt-get -f install。
说明：这不是 OpenClaw 本体故障，但属于部署主机上的关键环境问题，解决后有助于整个系统恢复稳定。
四、可复用的排查方法与经验
1. 先分清"服务问题"还是"展示问题"
如果 openclaw status 或控制台看起来异常，不要立刻判定 Gateway 挂了。应先检查：
openclaw gateway status
openclaw status
日志文件 /tmp/openclaw/openclaw-YYYY-MM-DD.log
RPC probe 是否正常、端口是否在监听。
2. systemd 只保留一套主路径最稳
若决定使用 root + 系统级 systemd，就尽量不要再保留用户态的同名 unit。双份 unit 很容易让排查变复杂。
3. 改安全配置前，先确认依赖条件
例如启用 sandbox 之前先确认 Docker；启用 QQ allowlist 之前先把自己的 sender ID 放进去。否则系统不是"不安全"，而是"直接不可用"。
4. 会话长了会影响体感稳定性
历史排查中还发现，主会话和 QQ direct 会话积累到 60k+ token 后，更容易出现上下文串线、答偏、带旧信息的问题。必要时应缩短 reset 时间，或主动开启新会话验证。
五、建议保留的一份最小检查清单
-
检查 Node 与 OpenClaw 命令路径是否统一：which node && which npm && which openclaw
-
检查 Gateway：openclaw gateway status
-
检查整体状态：openclaw status
-
检查最近日志：tail -n 100 /tmp/openclaw/openclaw-当天日期.log
-
若启用 sandbox，先执行：docker --version
-
若 QQ 私聊异常，检查 channels.qqbot.dmPolicy 与 channels.qqbot.allowFrom 是否匹配。
六、结论
这次 Ubuntu 22.04.5 LTS 上的 OpenClaw 部署，最终稳定方案可以概括为：系统级 Node、systemd 托管 Gateway、按需接入 QQ Bot、谨慎启用 sandbox、不要混用多套 systemd scope。
真正需要长期记住的，不只是安装命令本身，而是三条经验：一是路径和运行时要统一；二是 systemd scope 要唯一；三是安全配置一定要和实际依赖、白名单同步配置。
附：本记录同时覆盖了部署过程中遇到的环境问题（如 MySQL 修复），便于后续再次排查时少走弯路。
