Clawdbot更新失败需按五步排查：一、强制升级Node.js至22+并确认架构匹配；二、清npm缓存后重装CLI；三、使用官方install.sh脚本安装；四、从源码构建二进制；五、修复权限与PATH路径冲突。
如果您尝试更新Clawdbot，但执行命令后未生效、版本号未变化或报错退出，则可能是由于Node.js版本不兼容、全局包权限冲突或安装源失效所致。以下是解决此问题的步骤：
一、验证并强制升级Node.js至22+版本
Clawdbot自2026年起强制要求Node.js 22或更高版本，旧版Node会导致npm install -g clawdbot静默失败或安装残留v1.x旧二进制。必须确认当前运行环境为ARM原生Node（M系列Mac）或x64 Node（Linux/Windows），且无nvm多版本混用干扰。
1、在终端中执行node -v，检查输出是否为v22.x.x或更高版本。
2、若版本低于22或提示command not found，运行nvm install 22 && nvm use 22 && nvm alias default 22完成安装与设为默认。
3、执行which node，确认路径包含nvm/versions/node/v22；若仍指向系统自带/usr/bin/node，需在~/.zshrc末尾追加export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"，然后运行source ~/.zshrc刷新环境。
二、清除npm全局缓存并重装CLI
npm缓存可能保留损坏的tarball或校验失败的包元数据，导致clawdbot更新时跳过实际下载，仅复用本地旧包。需彻底清空缓存并绕过package-lock机制强制拉取最新发布版本。
1、运行npm cache clean --force清除全部缓存。
2、执行npm uninstall -g clawdbot卸载现有全局安装。
3、使用--ignore-scripts参数规避预编译脚本冲突，运行npm install -g clawdbot@latest --ignore-scripts。
4、验证安装结果：clawdbot --version应返回v1.9.0或更高版本号。
三、切换至一键脚本安装通道
当npm方式持续失败时，官方维护的install.sh脚本具备自动架构识别、依赖校验与ARM/x64二进制精准分发能力，可绕过npm registry策略限制与权限沙箱问题，适用于终端权限受限或企业网络拦截registry的场景。
1、在终端中粘贴并执行：curl -fsSL https://clawd.bot/install.sh | bash。
2、输入管理员密码（输入过程无回显，完成后按回车）。
3、等待脚本输出✅ Clawdbot v1.9.0 installed successfully提示。
4、立即运行clawdbot onboard --skip-ai-config跳过API配置，仅验证CLI可执行性。
四、从源码构建最新Release二进制
适用于需审计代码、启用调试日志或目标平台无预编译二进制支持（如部分ARM64 Linux发行版）的用户。该方式直接拉取GitHub Actions发布的正式tag源码，通过pnpm构建生成本地适配二进制，完全规避npm包管理器层异常。
1、执行git clone --depth 1 --branch v1.9.0 https://github.com/clawdbot/clawdbot.git && cd clawdbot。
2、运行pnpm install --no-frozen-lockfile安装最新依赖树。
3、执行pnpm build触发TypeScript编译与打包流程。
4、运行pnpm link将dist/bin/clawdbot.js软链至$PATH中，使clawdbot命令全局可用。
五、修复权限与路径冲突问题
macOS Monterey及以上系统对/usr/local/bin写入实施更严格Gatekeeper策略，而某些旧版Homebrew或手动安装的Node会将npm全局bin目录设为/opt/homebrew/lib/node_modules等非标准路径，造成clawdbot命令无法被Shell定位。必须统一bin路径归属并重置执行权限。
1、运行npm config get prefix，记录输出路径（如/opt/homebrew或/Users/xxx/.nvm/versions/node/v22.14.0）。
2、执行ls -l $(npm config get prefix)/bin/clawdbot，确认文件存在且权限为-rwxr-xr-x。
3、若权限异常，运行chmod +x $(npm config get prefix)/bin/clawdbot。
4、将该bin目录加入PATH：在~/.zshrc中添加export PATH="$(npm config get prefix)/bin:$PATH"，再执行source ~/.zshrc。
