常见问题解答 (FAQ)

问题: 系统未安装 Node.js

解决方案:

# macOS
brew install node

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
# 从 https://nodejs.org/ 下载安装包

安装完成后验证：

node --version
npm --version

可能原因:

1. 网络连接问题
2. 权限不足
3. 脚本兼容性问题

解决方案:

# 方案 1: 检查网络连接
curl -I https://clawd.org.cn

# 方案 2: 使用 sudo 执行
curl -fsSL https://clawd.org.cn/install.sh | sudo bash

# 方案 3: 手动下载后执行
curl -O https://clawd.org.cn/install.sh
bash install.sh

# 方案 4: 使用国内镜像（中国大陆用户）
curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry npm

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 清理缓存后重试
npm cache clean --force
npm install -g @openclaw/core

# 或使用 yarn
npm install -g yarn
yarn global add @openclaw/core

# 方案 1: 修复 npm 权限（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 然后重新安装
npm install -g @openclaw/core

# 运行配置向导
openclaw init

# 或手动编辑配置文件
# ~/.openclaw/config.json
{
  "model": {
    "provider": "anthropic",
    "apiKey": "sk-...",
    "model": "claude-sonnet-4-20250514"
  }
}

支持的模型提供商:

• Anthropic (Claude)
• OpenAI (GPT-4)
• 智谱 AI
• 通义千问
• 本地模型 (Ollama 等)

解决方案:

1. 登录对应平台检查 API Key 状态
2. 确认账户余额充足
3. 检查 API Key 权限范围
4. 重新生成 API Key 并更新配置

# 更新配置
openclaw config set model.apiKey "新的 API Key"

# 切换到 GPT-4
openclaw config set model.provider openai
openclaw config set model.model gpt-4-turbo

# 切换到 Claude
openclaw config set model.provider anthropic
openclaw config set model.model claude-sonnet-4-20250514

# 切换到本地模型
openclaw config set model.provider ollama
openclaw config set model.model llama3

# 列出所有已安装技能
openclaw skills list

# 查看技能详情
openclaw skills info <技能名称>

# 检查技能更新
openclaw skills check-updates

# 确认技能名称
openclaw skills search <关键词>

# 检查网络
curl -I https://clawhub.ai

# 手动安装
openclaw skills install <技能名> --verbose

# 使用备用源
openclaw skills install <技能名> --source github

# 查看详细错误信息
openclaw run <技能名> --verbose

# 检查技能配置
openclaw skills config <技能名>

# 重新安装技能
openclaw skills reinstall <技能名>

# 查看技能日志
openclaw logs <技能名>

# 卸载单个技能
openclaw skills uninstall <技能名>

# 卸载并清理配置
openclaw skills uninstall <技能名> --purge

# 批量卸载
openclaw skills uninstall --all

排查步骤:

1. 检查 App 配置：openclaw channels status feishu
2. 确认机器人已添加到群聊
3. 检查权限配置（飞书开放平台）
4. 重新配置：openclaw channels config feishu --reset

# 检查 Bot Token
openclaw channels status telegram

# 测试连接
openclaw channels test telegram

# 重新配置
openclaw channels config telegram --reset

# 检查隐私模式
# 在@BotFather 中关闭 Privacy Mode

1. 确认使用的是 WhatsApp Business
2. 检查手机网络连接
3. 重新生成二维码：openclaw channels config whatsapp --reset
4. 检查会话状态：openclaw channels status whatsapp

# 检查记忆配置
openclaw memory status

# 启用长期记忆
openclaw memory enable long-term

# 清理记忆缓存
openclaw memory clear --type short-term

# 查看记忆内容
openclaw memory view

# 导出记忆
openclaw memory export --output ~/backup/memory.json

# 导入记忆
openclaw memory import --input ~/backup/memory.json

# 备份所有数据
openclaw backup --output ~/backup/openclaw-backup-$(date +%Y%m%d)

# 检查版本
openclaw --version

# 查看日志
openclaw logs --tail 100

# 重启服务
openclaw restart

# 重新安装
npm uninstall -g @openclaw/core
npm install -g @openclaw/core

# 检查系统资源
top -pid $(pgrep -f openclaw)

# 切换更快的模型
openclaw config set model.model claude-haiku-3

# 启用缓存
openclaw config set cache.enabled true

# 检查网络连接
ping api.anthropic.com

# 降低请求频率
openclaw config set rate_limit.requests_per_minute 10

# 启用请求队列
openclaw config set rate_limit.queue_enabled true

# 使用多个 API Key 轮换
openclaw config set model.apiKeys ["key1", "key2", "key3"]

# 1. 使用环境变量
export OPENCLAW_API_KEY="your-key"
openclaw config set model.apiKey $OPENCLAW_API_KEY

# 2. 设置文件权限
chmod 600 ~/.openclaw/config.json

# 3. 定期轮换 Key
# 每 30-90 天更新一次 API Key

# 4. 使用最小权限原则

需要放行的域名:

• api.anthropic.com - Claude
• api.openai.com - GPT
• clawhub.ai - 技能市场
• open.feishu.cn - 飞书
• api.telegram.org - Telegram

# 1. 创建技能目录
mkdir -p ~/.openclaw/skills/my-skill

# 2. 创建 SKILL.md
cat > ~/.openclaw/skills/my-skill/SKILL.md << EOF
---
name: my-skill
description: 我的自定义技能
---

# 技能说明
...
EOF

# 3. 测试技能
openclaw skills load my-skill

详细教程请查看：多 Agent 配置完整指南

# 示例配置
agents:
  - name: strategist
    role: 策略规划
    model: claude-sonnet-4
    skills: [research, analysis]

  - name: developer
    role: 代码开发
    model: claude-sonnet-4
    skills: [code, git]

orchestration:
  mode: sequential
  workflow: [strategist, developer, reviewer]

# 完整备份
openclaw backup --output ~/openclaw-backup

# 仅备份配置
openclaw backup --type config

# 仅备份记忆
openclaw backup --type memory

# 定时备份（crontab）
0 2 * * * openclaw backup --output ~/backups/openclaw-$(date +\%Y\%m\%d)