OpenClaw 在 Ubuntu 22.04.5 LTS 上的安装与问题处理记录

整理说明本记录通过小龙虾OpenClaw依据本地记忆文件、历史会话记录和当前运行配置整理重点保留可复用的安装步骤、故障现象、根因判断和解决办法。一、环境概况操作系统Ubuntu 22.04.5 LTSOpenClaw 状态目录/home/node/.openclaw工作目录/home/node/.openclaw/workspace运行时 Node已迁移为系统 Nodenode / 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 事件等正常行为。三、安装和使用过程中遇到的主要问题问题 1OpenClaw 运行最初依赖 nvm后续需要迁移到系统 Node现象运行环境混用 nvm 路径和系统路径Gateway 服务的 Node 来源不够统一后期维护和 systemd 管理容易出现偏差。根因OpenClaw 初期依附于用户环境中的 nvm Node而 systemd 服务更适合绑定稳定的系统级 Node 路径。解决方法将 OpenClaw 运行时迁移到系统 Node确认 node、npm、openclaw 都解析到 /usr/bin同时让 Gateway 服务也使用系统 Node。结果运行时来源统一后续对 systemd、PATH、服务状态的判断更稳定。问题 2Gateway 的 systemd 管理存在 user scope 与 system scope 混淆现象机器上曾同时存在用户态 unit 残留和系统级 unitCLI 对服务状态的识别被误导。典型表现虽然实际服务已经 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 已安装且服务可用否则会直接影响消息回复。问题 5QQ 通道安全收紧后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 rootlocalhost。根因升级用的临时 MySQL 实例里只有 root% 缺少 rootlocalhost导致 postinst 脚本执行 ALTER USER 失败。解决方法1先区分正式 mysql.service 与升级拉起的临时实例。2清理互相抢锁的维护 / 临时 mysqld。3连接升级临时 socket检查 mysql.user。4如果只有 root% 则复制补出 rootlocalhost。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 statusopenclaw status日志文件 /tmp/openclaw/openclaw-YYYY-MM-DD.logRPC probe 是否正常、端口是否在监听。2. systemd 只保留一套主路径最稳若决定使用 root 系统级 systemd就尽量不要再保留用户态的同名 unit。双份 unit 很容易让排查变复杂。3. 改安全配置前先确认依赖条件例如启用 sandbox 之前先确认 Docker启用 QQ allowlist 之前先把自己的 sender ID 放进去。否则系统不是“不安全”而是“直接不可用”。4. 会话长了会影响体感稳定性历史排查中还发现主会话和 QQ direct 会话积累到 60k token 后更容易出现上下文串线、答偏、带旧信息的问题。必要时应缩短 reset 时间或主动开启新会话验证。五、建议保留的一份最小检查清单1. 检查 Node 与 OpenClaw 命令路径是否统一which node which npm which openclaw2. 检查 Gatewayopenclaw gateway status3. 检查整体状态openclaw status4. 检查最近日志tail -n 100 /tmp/openclaw/openclaw-当天日期.log5. 若启用 sandbox先执行docker --version6. 若 QQ 私聊异常检查 channels.qqbot.dmPolicy 与 channels.qqbot.allowFrom 是否匹配。六、结论这次 Ubuntu 22.04.5 LTS 上的 OpenClaw 部署最终稳定方案可以概括为系统级 Node、systemd 托管 Gateway、按需接入 QQ Bot、谨慎启用 sandbox、不要混用多套 systemd scope。真正需要长期记住的不只是安装命令本身而是三条经验一是路径和运行时要统一二是 systemd scope 要唯一三是安全配置一定要和实际依赖、白名单同步配置。附本记录同时覆盖了部署过程中遇到的环境问题如 MySQL 修复便于后续再次排查时少走弯路。