安装Clawdbot失败时，需依次检查环境兼容性（OS、Node.js版本、架构、内存）、修复npm权限与全局路径、更新API配置源、重置状态目录及systemd服务、或改用云镜像部署。
如果您尝试安装 Clawdbot，但安装过程卡在依赖下载、服务启动失败或配置报错阶段，则可能是由于环境不兼容、权限缺失、网络策略限制或配置文件错误所致。以下是解决此问题的步骤：
一、验证系统与基础环境兼容性
Clawdbot 对操作系统版本、Node.js 运行时及系统架构有明确要求，不满足将导致安装脚本中断或二进制无法加载。需确认当前环境是否符合最低运行标准。
1、执行 cat /etc/os-release 查看操作系统发行版及版本号，确认为 Ubuntu 20.04/22.04/24.04 LTS、Debian 11/12 或 CentOS Stream 9；
2、执行 node --version 检查 Node.js 版本，必须为 v18.17.0 或 v20.9.0 及以上，低于此版本将触发 npm install 阶段的 peer dependency 冲突；
3、执行 uname -m 确认 CPU 架构为 x86_64 或 aarch64，不支持 i386 或 32 位 ARM；
4、执行 free -h 检查可用内存，确保至少 2GB 可用 RAM，内存不足会导致编译阶段 OOM 终止。
二、修复 npm 权限与全局安装路径冲突
Clawdbot 安装脚本依赖 npm 全局命令（如 clawdbot-cli），若 npm 使用 root 权限安装或被系统包管理器（如 apt）覆盖，将引发 EACCES 错误或二进制不可执行。
1、执行 npm config get prefix 查看当前全局路径，若输出为 /usr/local，说明存在 root 权限风险；
2、执行 mkdir ~/.npm-global && npm config set prefix '~/.npm-global' 创建非特权安装目录；
3、执行 echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrc 将新 bin 路径加入环境变量；
4、重新运行安装命令：npm install -g @clawdbot/cli。
三、绕过网络限制重设模型 API 配置源
安装过程中若出现 fetch failed、404 page not found 或 401 invalid api key 错误，表明 clawdbot.json 中预设的 MiniMax 或百炼 API endpoint 不可达，需手动修正为可用地址。
1、定位配置文件：~/.clawdbot/clawdbot.json；
2、使用 nano 编辑：nano ~/.clawdbot/clawdbot.json；
3、查找 "minimax" 区块，将原 "baseUrl": "https://api.minimax.io/anthropic" 替换为 "https://api.minimax.chat/anthropic"；
4、同步修改 "api" 字段值为 "v1/messages"；
5、若使用阿里云百炼，确保 "baseUrl" 设为 "https://dashscope.aliyuncs.com/api/v1"，且 "Authorization" 头使用 "Bearer YOUR_API_KEY" 格式。
四、启用 systemd 服务前强制重置状态目录
重复安装或异常中断后，~/.clawdbot 目录可能残留损坏的 session 文件或锁文件，导致 clawdbot start 命令反复报错“agent bootstrapping forever”或 tokens stuck at 0。
1、停止所有相关进程：pkill -f clawdbot；
2、备份并清空状态目录：mv ~/.clawdbot ~/.clawdbot.bak && mkdir ~/.clawdbot；
3、重新初始化配置：clawdbot init --provider minimax（或对应 provider）；
4、手动创建 systemd service 文件：sudo cp ~/.clawdbot/systemd/clawdbot.service /etc/systemd/system/；
5、重载并启用：sudo systemctl daemon-reload && sudo systemctl enable --now clawdbot。
五、切换至云镜像部署规避本地构建失败
当本地编译持续失败（如 node-gyp 构建 native 模块超时、OpenSSL 版本不匹配、clang 缺失）时，可跳过源码安装流程，直接使用预构建镜像启动完整服务。
1、访问阿里云轻量应用服务器控制台，搜索 “Moltbot 官方镜像”；
2、选择配置：CPU 2核、内存 4GB、SSD 40GB、地域选香港或新加坡（低延迟）；
3、实例创建完成后，在控制台点击 “一键部署”，自动注入百炼 API Key 并配置钉钉通道；
4、等待约 3 分钟，通过公网 IP 访问 http://[SERVER_IP]:3000 进入仪表盘；
5、首次登录使用默认凭证：admin / clawdbot2026，登录后立即修改密码。
