说明：本手册按"安装、检查、常见问题修复"的顺序整理，优先覆盖这次实际用到的可复用命令。执行前请确认当前用户具备 root 或 sudo 权限。
一、基础环境检查
- 查看系统版本
lsb_release -a
uname -a
- 检查 Node / npm / OpenClaw 命令位置
which node
which npm
which openclaw
node -v
npm -v
预期：尽量统一到系统路径，例如 /usr/bin/node、/usr/bin/npm、/usr/bin/openclaw。
二、安装或确认系统级 Node.js
如果当前还在混用 nvm，可优先整理为系统级 Node。以下命令先用于确认：
which node
readlink -f $(which node)
which npm
readlink -f $(which npm)
如果确认系统已具备可用 Node，则可直接进入 OpenClaw 检查；若未安装，请按你的实际源安装系统级 Node。安装完成后再次确认 which node / which npm。
三、OpenClaw 基础检查
- 查看 Gateway 状态
openclaw gateway status
- 查看整体状态
openclaw status
- 跟踪日志
tail -n 100 /tmp/openclaw/openclaw-$(date +%F).log
四、systemd 管理 Gateway 的常用命令
如果已经采用 systemd 托管 Gateway，常用命令如下：
openclaw gateway status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
如果你当前明确采用 root + 系统级服务，也可以直接看系统服务：
systemctl status openclaw-gateway --no-pager -l
systemctl daemon-reload
五、修复 systemd user scope 与 system scope 混淆
现象：CLI 容易误判到 systemctl --user，或者机器上同时存在用户态和系统级 unit。
- 先检查两边是否都存在 unit
ls -l ~/.config/systemd/user/openclaw-gateway.service
ls -l /etc/systemd/system/openclaw-gateway.service
- 如果你决定只保留系统级 unit，可先备份用户态残留 unit
mv ~/.config/systemd/user/openclaw-gateway.service ~/.config/systemd/user/openclaw-gateway.service.bak
- 然后重新检查 Gateway 状态
openclaw gateway status
systemctl status openclaw-gateway --no-pager -l
注意：如果当前会话本身依赖 OpenClaw 在线，不建议在关键对话中贸然重启 gateway，避免把自己会话也重启掉。
六、修复控制台显示异常但服务实际上正常的问题
现象：页面或状态里出现 missing scope: operator.read。
这种情况下先确认服务本身是否正常，不要只看 UI。
openclaw gateway status
openclaw status
ss -ltnp | grep 18789
tail -n 100 /tmp/openclaw/openclaw-$(date +%F).log | grep -n "operator.read"
如果 RPC probe 正常、端口也在监听，则优先判断为权限视角问题，而不是 Gateway 已宕机。
七、修复 sandbox 开启后因未安装 Docker 导致 agent 无法回复
现象：日志报 Sandbox mode requires Docker, but the docker command was not found in PATH。
- 先确认 Docker 是否安装
docker --version
which docker
- 如果没安装 Docker，而你只是想先恢复可用性，建议先把 sandbox 关闭
python3 - <<'PY2'
import json
p = "/home/node/.openclaw/openclaw.json"
with open(p, "r", encoding="utf-8") as f:
data = json.load(f)
data.setdefault("agents", {}).setdefault("defaults", {}).setdefault("sandbox", {})"mode" = "off"
with open(p, "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False, indent=2)
f.write("\n")
print("updated:", p)
PY2
- 修改后重新检查
openclaw gateway status
tail -n 80 /tmp/openclaw/openclaw-$(date +%F).log
八、修复 QQ allowlist 配置导致私聊被拦截
现象：dmPolicy=allowlist，但 allowFrom 为空，doctor 会提示 all DMs will be blocked。
- 先检查当前配置
python3 - <<'PY2'
import json
p = "/home/node/.openclaw/openclaw.json"
with open(p, "r", encoding="utf-8") as f:
data = json.load(f)
qq = data.get("channels", {}).get("qqbot", {})
print(json.dumps({"dmPolicy": qq.get("dmPolicy"), "allowFrom": qq.get("allowFrom")}, ensure_ascii=False, indent=2))
PY2
- 把自己的 QQ sender ID 加入白名单（下面示例把 80D430D088174E8157D1309218917F86 加入）
python3 - <<'PY2'
import json
p = "/home/node/.openclaw/openclaw.json"
uid = "80D430D088174E8157D1309218917F86"
with open(p, "r", encoding="utf-8") as f:
data = json.load(f)
qq = data.setdefault("channels", {}).setdefault("qqbot", {})
qq"dmPolicy" = "allowlist"
allow = qq.setdefault("allowFrom", \[\])
if uid not in allow:
allow.append(uid)
with open(p, "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False, indent=2)
f.write("\n")
print("updated:", p)
PY2
- 再检查
openclaw gateway status
openclaw status
九、会话过长导致回复易串线时的处理建议
- 先看当前会话状态
openclaw status
- 如果 direct 会话 token 已经很高，最稳的办法通常是新开会话验证，而不是在超长旧会话里硬修。
十、MySQL 环境异常时的修复命令（部署主机通用）
如果在同一台 Ubuntu 主机上遇到 apt / dpkg 被 MySQL 卡住，可按下面顺序检查。
- 看服务状态
systemctl status mysql --no-pager -l
mysqladmin ping
- 查看是否有包状态未完成
dpkg --audit
apt-get -f install
- 如果 root PATH 太瘦，先补全再重试
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
dpkg --configure -a
apt-get -f install
dpkg --audit
- 如果日志仍然报 ALTER USER failed for root@localhost，则要检查升级临时实例里的 mysql.user，确认是否只有 root@% 而缺少 root@localhost。
十一、日常最小巡检命令
which node && which npm && which openclaw
openclaw gateway status
openclaw status
tail -n 100 /tmp/openclaw/openclaw-$(date +%F).log
十二、建议
建议把这份命令版和前一份过程记录版一起保存：过程记录适合回顾原因，命令版适合下次直接照着操作。
