💡 快速解决：遇到问题？先在这里找答案，90%的问题都能快速解决
📋 目录
🔌 API连接问题
问题1：API密钥无效
症状：
Error: Invalid API key
401 Unauthorized
原因：API密钥错误或已过期
解决方案：
步骤1：验证API密钥
- 登录您的 API 提供商后台（如 DeepSeek, Kimi, OpenAI 等）
- 确认密钥是否依然有效
- 重新获取并配置密钥
步骤2：测试API连接
# 使用 curl 测试
curl https://api.deepseek.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
问题2：API请求超时
症状：
Error: Request timeout
ETIMEDOUT
原因：网络连接慢或API服务器响应慢
解决方案：
方案1：检查网络连接
- 确保您的网络可以正常访问 API 地址
- 如果使用国际模型，请确保您的网络环境支持
方案2：使用国内API服务
- 推荐使用 DeepSeek、Kimi 等国内服务，速度更快更稳定
问题3：API限流
症状：
Error: Rate limit exceeded
429 Too Many Requests
原因：请求频率过高，超出了 API 提供商的限制
解决方案：
- 降低发送消息的频率
- 检查是否有后台任务在频繁调用 API
- 在 API 提供商后台查看当前用量和限制，必要时升级套餐
🧩 Skills加载问题
问题4：Skills不生效
症状：安装了Skills但无法使用
原因：Skills未启用或配置错误
解决方案：
步骤1：检查Skills状态
# 列出所有已安装的Skills
openclaw skills list
步骤2：确认Skills已启用
- 确保您请求的功能对应的 Skills 处于
enabled状态
步骤3：检查Skills配置
- 部分 Skills 需要额外的配置（如 Google Search 需要 API Key）
- 检查相关配置项是否已正确填写
问题5：Skills版本冲突
症状：
Error: Skill version conflict
原因：多个Skills依赖不同版本的库
解决方案：
- 尝试更新 Skills 到最新版本
- 如果冲突持续，请联系您的技术支持人员进行排查
📱 多平台集成问题
问题6：飞书Bot不回复
症状：在飞书中发送消息，Bot无响应
原因：配置错误或权限不足
解决方案：
步骤1：检查权限（最常见问题）⭐
飞书Bot需要以下三个核心权限才能正常工作：
im:message：获取与发送消息im:message:send_as_bot：以应用身份发消息contact:contact.base:readonly：获取通讯录基本信息（用于识别发送者）
步骤2：检查事件订阅
- 确保已选择”使用长连接接收事件”（WebSocket模式）
- 确保已添加
im.message.receive_v1事件
步骤3：检查应用发布状态
- 确认飞书应用已通过审核并发布
问题7：企业微信/钉钉配置失败
症状：Bot 无法连接或消息推送失败
原因：ID、Secret 或回调地址配置错误
解决方案：
- 登录对应平台的管理后台，核对 CorpID、AgentID、Secret 等参数
- 确保配置中的参数没有多余的空格
📁 文件操作问题
问题8：无法访问文件
症状：
Error: Permission denied
EACCES: permission denied
原因：系统权限不足，OpenClaw 无法读取或写入目标文件
解决方案：
- 检查文件或文件夹的系统权限，确保 OpenClaw 运行用户有读写权限
- 在 macOS 上，请参考 权限问题 章节
问题9：文件搜索结果为空
症状：搜索文件时返回空结果
原因：索引未建立或路径未包含
解决方案：
- 运行索引重建命令：
openclaw files reindex - 检查您的配置文件，确保目标文件夹已包含在
searchPaths中
⚡ 性能问题
问题10：响应速度慢
症状：发送消息后等待很久才收到回复
原因：模型响应慢或网络延迟
解决方案：
- 方案1：使用更快的模型（如
deepseek-chat） - 方案2：启用流式输出（Streaming），让 AI 边生成边回复
- 方案3：检查网络延迟，考虑使用国内 API 服务
🔐 权限问题 (macOS)
问题11：macOS 权限请求
症状：无法访问备忘录、日历或文件
原因：macOS 安全机制拦截
解决方案：
- 打开”系统设置” → “隐私与安全性”
- 授予运行 OpenClaw 的终端程序（如 Terminal, iTerm, VS Code）以下权限：
- 完全磁盘访问权限
- 辅助功能
- 自动化
- 重启您的终端程序
🌐 网络问题
问题12：无法连接到API服务
症状：
Error: getaddrinfo ENOTFOUND
原因：DNS解析失败或网络被墙
解决方案：
- 检查您的网络连接是否正常
- 尝试更换 DNS（如 8.8.8.8）
- 如果访问国际服务，请确保您的网络环境支持
🆘 获取帮助
如果以上方案都无法解决您的问题，请联系您的专业技术支持人员，并提供以下信息：
- 您使用的 OpenClaw 版本
- 您的操作系统
- 具体的错误现象或截图
最后更新：2026年3月