$cd ../troubleshooting/
CRITICAL📦 Installation
双重安装：openclaw 二进制被遮蔽 — 运行了错误版本
// 你已升级 OpenClaw，但 `openclaw --version` 仍显示旧版本，doctor 修复不生效，或 gateway 行为像你没删掉的旧发行版。这几乎总是因为存在两个全局安装——常见于 `sudo npm i -g openclaw`（/usr/local/bin）加上用户级安装（~/.npm-global 或 nvm）——而 shell 先解析到错误的那一个。被遮蔽的二进制很隐蔽：命令成功，但跑的是旧代码。本非官方指南说明如何列出磁盘上每个副本、选定一种安装策略、修正 PATH 优先级，并在 OpenClaw 文档推荐的用户 prefix 下干净重装。
diagnose.sh
🔍 这是您的问题吗？
?`openclaw --version` 显示的版本比刚安装的更旧
?`which -a openclaw` 列出两条及以上路径（如 /usr/local/bin 与 ~/.npm-global/bin）
?`openclaw doctor` 或升级的修复在运行时从未生效
?您曾同时运行 `sudo npm i -g openclaw` 与普通用户全局安装
?Gateway 日志引用您预期版本中不存在的功能
diagnose_paths.sh
✅ 修复方法 1 — 列出磁盘上每个 openclaw 二进制
改动前先映射所有二进制
# 列出 PATH 上每个 openclaw which -a openclaw # Bash：显示所有解析名 type -a openclaw # 对比各路径版本 /usr/local/bin/openclaw --version 2>/dev/null ~/.npm-global/bin/openclaw --version 2>/dev/null # 查看 npm 全局根目录 npm prefix -g sudo npm prefix -g 2>/dev/null
确认重复 npm 安装与当前活跃二进制
# 检查两个 npm 全局树 npm list -g openclaw --depth=0 sudo npm list -g openclaw --depth=0 2>/dev/null # 看 shell 实际运行哪个 hash -r # bash：清除命令缓存 command -v openclaw openclaw --version
uninstall_dupes.sh
✅ 修复方法 2 — 删除重复的安装路径
卸载两棵树——~/.openclaw 配置安全
# 卸载用户级全局副本 npm uninstall -g openclaw # 卸载系统级 sudo 副本（若存在） sudo npm uninstall -g openclaw # 确认 PATH 上已无 which -a openclaw || echo "PATH 上无 openclaw — 正常"
npm uninstall 留下坏链时手动清理
# 可选：手动删除残留符号链接 sudo rm -f /usr/local/bin/openclaw rm -f ~/.npm-global/bin/openclaw # 清除 shell 哈希表 hash -r # 确认干净 which -a openclaw
reinstall_clean.sh
✅ 修复方法 3 — 修正 PATH 顺序并在用户 prefix 重装
PATH 顺序正确时用户 prefix 优先于 /usr/local/bin
# 标准用户 prefix（推荐） npm config set prefix "$HOME/.npm-global" mkdir -p "$HOME/.npm-global/bin" # 写入 ~/.bashrc 或 ~/.zshrc — npm bin 在前 export PATH="$HOME/.npm-global/bin:$PATH" # 重载 shell source ~/.bashrc # 或 ~/.zshrc
一条路径、一个版本——然后重启服务
# 在用户 prefix 全新安装 npm i -g openclaw@latest # 验证单一二进制 which -a openclaw openclaw --version openclaw doctor # 若 gateway 在跑则重启 openclaw gateway restart
💡 专业技巧：只保留一种全局策略
在用户级 npm global（推荐）或系统级 sudo 安装中二选一——不要混用。清理后 `which -a openclaw` 应只返回一条路径。在 ~/.npmrc 中固定 npm prefix，避免今后 `npm i -g` 装到第二个位置。
🛡️ 预防清单
- • 不要混用 `sudo npm i -g openclaw` 与用户级全局安装——选定一个 prefix 并坚持
- • 每次安装后，在重启 gateway 或运行 doctor 前先执行 `which -a openclaw` 和 `openclaw --version`
- • 在 ~/.bashrc 或 ~/.zshrc 中把 npm 全局 bin（`npm prefix -g`/bin）放在 /usr/local/bin 之前
- • 若使用 nvm/fnm，确保版本管理器 init 在非交互 shell（systemd、cron、SSH）中也会加载
- • 在主机 README 中记录所选安装路径，避免未来再次 sudo 安装
❓ 常见问题
Q1. 如何确认存在被遮蔽的二进制？
运行 `which -a openclaw`（bash 可用 `type -a openclaw`）。若出现两条及以上路径——例如 /usr/local/bin/openclaw 与 /home/you/.npm-global/bin/openclaw——shell 会使用 $PATH 中先出现的那条。分别对比 `openclaw --version` 与各路径下的二进制版本。再以普通用户与 `sudo npm list -g openclaw` 检查；两者都有安装即为危险信号。
Q2. 应保留 sudo 安装还是用户级安装？
Linux VPS 与 Mac Mini 社区实践偏向不用 sudo 的用户级全局安装：`npm config set prefix ~/.npm-global` 并将该 bin 加入 PATH。sudo 安装写入 /usr/local，之后以普通用户 `npm i -g` 时容易被忽略。若已有可用的用户 prefix，应删除 sudo 副本。仅在刻意用单一服务账户且从不以登录用户安装时才保留系统级安装。
Q3. 删了旧二进制但 systemd 里 openclaw 仍是错版本？
gateway 服务可能使用绝对路径，或 systemd/launchd 继承的 PATH 很精简。检查 `~/.config/systemd/user/openclaw-gateway.service` 的 ExecStart= 与 Environment=PATH=，改为正确二进制路径或导出包含 npm 全局 bin 的完整 PATH。然后 `systemctl --user daemon-reload && systemctl --user restart openclaw-gateway`。交互 shell 的修复不会自动作用于守护进程环境。
Q4. nvm 会导致同样问题吗？
会。nvm 按 Node 版本安装全局包。若在 Node 22 下安装 openclaw 而 systemd 用 Node 20，或登录 shell 加载 nvm 而 cron 不加载，会得到不同二进制。在与 gateway 相同上下文（如 `systemctl --user show-environment`）中运行 `node -v` 和 `which openclaw`。可设 nvm 默认别名，或使用指向稳定路径的官方安装脚本。
Q5. 卸载会破坏 ~/.openclaw 配置吗？
不会。配置、会话与通道认证在 ~/.openclaw/，与调用哪个全局二进制无关。卸载只从 npm 全局树移除 CLI/gateway 包。重装正确版本后 `openclaw doctor` 仍应读到相同配置。重大清理前可备份 ~/.openclaw/openclaw.json。
Q6. 最干净的重装步骤是什么？
1）确认配置路径。2）分别以用户与 `sudo npm uninstall -g openclaw` 卸载。3）确认 `which -a openclaw` 无输出。4）`npm config set prefix ~/.npm-global`。5）在 shell rc 中加入 PATH。6）`npm i -g openclaw@latest`。7）确认单一路径与版本后重启 gateway。官方仓库：github.com/openclaw/openclaw。