Skip to content

E-common-problems.md

Latest commit

 

History

History
531 lines (381 loc) · 9.63 KB

E-common-problems.md

File metadata and controls

531 lines (381 loc) · 9.63 KB

附录E：常见访问题速查

💡 快速定位访问题：本附录汇总了OpenClaw使用过程中最常见的各类访问题及解决方案，帮助你快速排查和解决访问题。

📋 目附录

安装配置访问题

Q1: 安装失败怎么怎么办？

症状：执行安装命令时报错

解决方案：

  1. 检查Node.js版本
node --version  # 需要v22.14.0或更高版本（macOS 需要 v22.16.0+）
  1. 使用官方中文安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash
  1. 使用npm直接安装
npm install -g openclaw
  1. 检查网络连接
  • 如果在国内，建议使用镜像源或中转API

Q2: 权限错误怎么怎么办？

症状：安装或运行时提示权限不足

解决方案：

# macOS/Linux
sudo npm install -g openclaw

# 或者使用nvm（推荐）
nvm install node
nvm use node
npm install -g openclaw

Q3: 网络超时怎么怎么办？

症状：安装或更新时网络连接超时

解决方案：

  1. 使用国内镜像源
npm config set registry https://registry.npmmirror.com
  1. 设置代理
npm config set proxy http://proxy-server:port
npm config set https-proxy http://proxy-server:port
  1. 使用离线安装
# 下载安装包后本地安装
npm install -g ./openclaw-*.tgz

Q4: WSL/Linux 安装后提示缺少 UI 资产怎么办？（v2026.3.22 已知问题）

症状：通过 npm install -g openclaw 安装后启动时报错：

Missing Control UI assets. You can build them yourself with: pnpm ui:build

或执行 pnpm ui:build 时又报错：

Cannot find module '.../scripts/ui.js'

原因：openclaw@2026.3.22 的 npm 包打包时遗漏了 scripts/ui.js 和预构建的 UI 资产文件，不是用户操作问题。

解决方案：

方法一：升级到最新版（推荐）

npm install -g openclaw@latest
openclaw --version  # 确认版本为 2026.3.24 或更新

方法二：确认 Node 版本是否符合要求

node --version
# Linux/WSL 需要 >= 22.14.0
# macOS 需要 >= 22.16.0

如果版本不符合，先升级 Node：

# 使用 nvm 升级
nvm install 22
nvm use 22
npm install -g openclaw@latest

方法三：仍报错则从源码构建（临时方案）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

⚠️ 注意：WSL 环境下建议优先使用方法一，升级到 v2026.3.24+ 后该问题已修复。

API连接访问题

Q4: API连接失败怎么怎么办？

症状：提示API连接错误或超时

解决方案：

  1. 检查API Key是否正确
openclaw config get env | grep API_KEY
  1. 测试API连接
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.anthropic.com/v1/messages
  1. 检查网络
ping api.anthropic.com
  1. 使用中转API（国内推荐）
  • 参考附录C：API服务商对比

Q5: API费用太高怎么怎么办？

症状：API使用成本超出预算

解决方案：

  1. 使用国产模型
  • DeepSeek：成本降低95%
  • Kimi：长文档处理优惠
  • GLM-4：中文友好
  1. 多模型组合
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx",
    "DEEPSEEK_API_KEY": "sk-xxx"
  },
  "agents": [
    {
      "name": "assistant",
      "model": "claude-3-5-sonnet-20241022"
    },
    {
      "name": "coder",
      "model": "deepseek-chat"
    }
  ]
}
  1. 设置工具权限
openclaw config set tools.profile "coding"  # 限制工具使用

Gateway访问题

Q6: Gateway启动失败怎么怎么办？

症状：执行openclaw daemon start后Gateway无法启动

解决方案：

  1. 检查配置文件
openclaw doctor  # 诊断配置访问题
  1. 检查端口占用
lsof -i :18789  # macOS/Linux
netstat -ano | findstr :18789  # Windows
  1. 查看日志
tail -f ~/.openclaw/logs/gateway.log
  1. 重启Gateway
openclaw daemon stop
openclaw daemon start

Q7: Gateway认证配置错误（v2026.3.7+）

症状：升级后Gateway拒绝启动，提示需要配置认证

解决方案：

# 设置token认证
openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"

# 重启Gateway
openclaw daemon restart

Q8: 端口被占用怎么办？

症状：提示18789端口已被占用

解决方案：

  1. 更改端口
openclaw config set gateway.port 18790
  1. 停止占用端口的进程
# 查找并停止占用进程
lsof -ti :18789 | xargs kill -9

Skills访问题

Q9: Skills安装失败怎么怎么办？

症状：clawhub install命令执行失败

解决方案：

  1. 检查网络连接
ping clawhub.ai
  1. 使用ClawHub镜像（如有）
clawhub install skill-name --registry https://mirror.clawhub.ai
  1. 手动安装
# 下载Skill源码
git clone https://github.com/user/skill-repo.git

# 安装依赖
cd skill-repo
npm install

# 复制到Skills目附录
cp -r . ~/.openclaw/skills/skill-name

Q10: Skills不生效怎么怎么办？

症状：安装Skill后功能无法使用

解决方案：

  1. 检查Skill配置
cat ~/.openclaw/skills/skill-name/SKILL.md
  1. 重启Gateway
openclaw daemon restart
  1. 检查Skill权限
openclaw config get skills.allowlist
  1. 查看错误日志
tail -f ~/.openclaw/logs/skills.log

Q11: 如何卸载Skills？

解决方案：

# 使用clawhub卸载
clawhub uninstall skill-name

# 手动删除
rm -rf ~/.openclaw/skills/skill-name

# 重启Gateway
openclaw daemon restart

Q12: Skills冲突怎么怎么办？

症状：多个Skills功能冲突

解决方案：

  1. 检查Skills列表
clawhub list
  1. 禁用冲突Skills
{
  "skills": {
    "denylist": ["skill-a", "skill-b"]
  }
}
  1. 使用版本管理
clawhub install skill-name@version

平台集成访问题

Q13: 飞书Bot不回复怎么怎么办？

症状：给飞书Bot发布送消息无响应

解决方案：

  1. 检查Bot状态
openclaw status
  1. 检查飞书配置
openclaw config get channels.feishu
  1. 验证Webhook
curl -X POST https://open.feishu.cn/open-apis/bot/v2/hook/xxx \
  -H "Content-Type: application/json" \
  -d '{"msg_type":"text","content":{"text":"测试"}}'
  1. 使用飞书配置检查清单
  • 参考：附录J：飞书配置检查清单

Q14: 企业微信Bot配置失败？

症状：企业微信Bot无法接入

解决方案：

  1. 检查应用Secret
  2. 验证回调URL
  3. 检查通讯附录权限
  4. 参考第9章节配置步骤

Q15: 能接入微信吗？

症状：想在微信中使用 OpenClaw 智能体

解决方案：

OpenClaw 提供了官方微信接入方案 ClawBot（橙皮书 v1.4 新增）：

  1. 安装官方插件：

    openclaw plugins install @openclaw/wechat-clawbot

  2. 启用微信渠道：

    openclaw config set channels.wechat.enabled true

  3. 重启 Gateway：

    openclaw gateway restart

注意事项：

  • ClawBot 基于 WeChatFerry，目前仅支持 Windows
  • 强烈建议使用小号，有封号风险
  • 详见 第9章 9.5 微信接入

Q16: Telegram Bot无响应？

症状：Telegram Bot不回复消息

解决方案：

  1. 检查Bot Token
openclaw config get channels.telegram.botToken
  1. 与Bot发布起对话
curl https://api.telegram.org/bot<TOKEN>/getMe
  1. 检查Webhook设置
curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo

性能访问题

Q17: 响应速度慢怎么怎么办？

解决方案：

  1. 使用更快的模型
  • DeepSeek：国内访问快
  • Claude 3.5 Sonnet：平衡速度和质量
  1. 减少上下文
# 定期清理会话历史
openclaw chat clear
  1. 优化配置
{
  "agents": [{
    "maxTokens": 4096,  # 减少输出长度
    "temperature": 0.7
  }]
}

Q18: 内存占用过高？

解决方案：

  1. 限制会话数量
openclaw config set sessions.max 10
  1. 定期重启Gateway
openclaw daemon restart
  1. 使用Docker部署
docker run -d --memory="2g" openclaw/openclaw

Q19: 磁盘空间不足？

解决方案：

  1. 清理日志文件
rm -rf ~/.openclaw/logs/*.log
  1. 清理缓存
rm -rf ~/.openclaw/cache/*
  1. 清理旧会话
openclaw session prune --days 30

🔍 更多资源

最后更新：2026年3月27日 适用版本：OpenClaw v2026.3.7+（Q4 适用 v2026.3.22+）