OpenClaw 常见问题解答（FAQ）：30 个高频问题与解决方案

# 1. 检查网络是否能访问 npm registry
curl -I https://registry.npmjs.org

# 2. 尝试切换 npm 镜像（中国大陆）
npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest

# 3. 如果是 Node 版本问题
node --version  # 需要 >= 22
# 用 nvm 升级
nvm install 24 && nvm use 24

# 找到 npm 全局路径
npm prefix -g  # 输出类似 /usr/local

# 添加到 PATH
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 设置环境变量跳过本地编译
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw@latest

# pnpm 需要手动确认带构建脚本的包
pnpm approve-builds -g
# 选择 openclaw、sharp、node-llama-cpp 等，按空格选中，回车确认

# 1. 确认 Gateway 正在运行
openclaw gateway status

# 2. 全面诊断
openclaw doctor

# 3. 查看实时日志
openclaw gateway logs --tail 50 --follow
# 给 Bot 发消息，看日志里是否有请求记录

# 检查是否配置了 requireMention
# 群组里需要 @Bot名字 才会触发
openclaw config get channels.telegram.groups

{
  channels: {
    telegram: {
      groups: { "*": { requireMention: false } }
    }
  }
}

# 让同事查自己的 Telegram 用户 ID（给 @userinfobot 发消息）
# 把用户 ID 加入白名单
openclaw config set channels.telegram.allowFrom '["你的ID","同事ID1","同事ID2"]'
openclaw gateway reload

openclaw gateway reload   # 手动触发重载
# 或完整重启
openclaw gateway restart

openclaw config validate
# 会提示哪行配置有问题

# 常见问题：
# - 字段名拼写错误（channels.telgram vs channels.telegram）
# - 字符串没加引号
# - 数组格式错误

{
  channels: {
    telegram: {
      token: "Bot1的Token",
    },
    "telegram-work": {
      type: "telegram",
      token: "Bot2的Token（工作用）",
    }
  }
}

# 方法 1：在 Telegram 里发
/reload

# 方法 2：重启 Gateway
openclaw gateway restart

# SOUL.md 在每次会话开始时加载，已有的对话不受影响
# 新建一个对话就会加载新的 SOUL.md

# 查看 Cron 任务列表
openclaw cron list

# 查看 Cron 执行日志
openclaw gateway logs --filter cron --tail 30

# 常见原因：
# - Gateway 未运行（Cron 依赖 Gateway）
# - cron 表达式格式错误（可用 crontab.guru 验证）
# - 时区设置问题（检查服务器时区与预期是否一致）

# 检查 heartbeat 配置
openclaw config get agents.defaults.heartbeat

# 确认 HEARTBEAT.md 文件存在
ls ~/.openclaw/workspace-content/HEARTBEAT.md

# 关闭 Browser 工具
openclaw config set tools.browser.enabled false
openclaw gateway restart
# 关闭后内存降至约 100MB

# 开启 Node 编译缓存（显著提速）
echo 'export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' >> ~/.bashrc
echo 'export OPENCLAW_NO_RESPAWN=1' >> ~/.bashrc
source ~/.bashrc
mkdir -p /var/tmp/openclaw-compile-cache
# 首次运行预热，之后每次快很多

tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz     ~/.openclaw/openclaw.json     ~/.openclaw/workspace-content/     ~/.openclaw/tokens/

# 旧服务器打包
tar -czf openclaw-migrate.tar.gz ~/.openclaw/

# 传输到新服务器
scp openclaw-migrate.tar.gz user@新服务器IP:~/

# 新服务器安装 OpenClaw 后恢复
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
tar -xzf ~/openclaw-migrate.tar.gz -C ~/
openclaw gateway restart

# 停止服务
openclaw gateway stop
openclaw gateway uninstall  # 移除 systemd 服务

# 卸载 npm 包
npm uninstall -g openclaw

# 删除所有数据（不可恢复！）
rm -rf ~/.openclaw

openclaw --version