跳到主要内容

常见问题 (FAQ)

这里列出了 OpenClaw 最常见的问题和故障排除技巧。

一般信息​

1. 什么是 OpenClaw？​

OpenClaw（前身为 Clawdbot 和 Moltbot）是一个开源、自托管的个人 AI 助手。它作为一个集中式网关，将各种消息平台（如 WhatsApp, Telegram, Discord, Slack）连接到由大型语言模型（LLM）驱动的 AI 代理。它允许您在自己的硬件或服务器上运行 AI 助手。

2. 本地运行 OpenClaw 安全吗？​

虽然功能强大，但应谨慎使用 OpenClaw。因为它创建了一个能够执行代码并访问文件系统的代理，所以建议在沙盒环境（如 Docker 容器）、专用机器或云服务器中运行它，而不是直接在包含敏感数据的个人工作站上运行。

3. 如何改善 OpenClaw 的记忆和持久性？​

默认情况下，OpenClaw 在重新安装后可能会丢失上下文。为了保持长期记忆并确立标准操作程序（SOP），您可以将其连接到一个专用的 GitHub 仓库，在那里它可以存储“记忆”和学到的行为。

4. 硬件要求是什么？​

OpenClaw 本身很轻量级，但它连接的 LLM 可能是资源密集型的。如果运行本地 LLM，您需要大量的 RAM 和 GPU 能力（要求因模型而异）。对于 OpenClaw 的网关操作，标准的 VPS 或现代笔记本电脑就足够了。对于复杂的任务，建议使用具有大上下文窗口（例如 64k token）的模型。

安装与设置​

5. 如何修复 "Container Stops Immediately"（容器立即停止）？​

这通常是因为配置无效或端口 18789 被占用。

  • 检查日志： 运行 docker compose logs openclaw-gateway。
  • 检查端口： 确保端口 18789 未被占用。
  • 验证配置： 确保您的 openclaw.json（或 moltbot.json）已正确挂载。

6. 如何修复 "Gateway Fails to Start"（网关无法启动）？​

常见原因：

  • Node.js 版本： 需要 Node.js 22+。
  • 端口冲突： 另一个服务正在使用端口 18789。
  • 语法错误： 检查 JSON 配置文件是否有尾随逗号或缺失括号。

7. 如何修复 Unraid 安装问题（Token URL）？​

在 Unraid 上设置时，必须手动将令牌附加到 Web UI URL。

  • 解决方案： 通过 http://<IP>:18789/?token=YOUR_TOKEN 访问 UI。

8. 如何修复 Docker 构建 "Error relocating /usr/bin/node"？​

这通常表明架构不匹配（例如在 ARM/Raspberry Pi 上运行 x86 镜像）或 Dockerfile 中的基础 Alpine 镜像有问题。

  • 解决方案： 确保使用了适合您架构的正确 Docker 镜像标签。

9. 如何修复 "EVP_MD_CTX_get_size_ex: symbol not found"？​

这通常是基于 Alpine Linux 的容器中的库兼容性问题，通常与 OpenSSL 版本有关。

  • 解决方案： 尝试将 Docker 镜像更新到最新版本，或固定到已知可与您的主机内核配合使用的稳定版本。

10. 如何修复 macOS 上的权限错误？​

OpenClaw 需要特定的权限才能与操作系统交互。

  • 解决方案： 转到 系统设置 > 隐私与安全性。授予运行 OpenClaw 的终端或应用程序“屏幕录制”、“辅助功能”和“完全磁盘访问权限”。重启网关。

配置​

11. 我的配置文件在哪里？​

根据您的版本和操作系统，通常位于：

  • ~/.openclaw/openclaw.json
  • ~/.clawdbot/moltbot.json
  • ~/.config/openclaw/config.json 您可以运行 openclaw config path（或 moltbot config path）来查找确切位置。

12. 如何修复 "No API Key Found"（未找到 API 密钥）？​

  • 检查密钥： 验证 apiKey 是否存在于配置文件中。
  • 检查环境变量： 如果您引用了环境变量，请确保已设置 OPENAI_API_KEY 等变量。
  • 提供商匹配： 确保密钥与提供商匹配（例如，不要将 Anthropic 密钥放在 OpenAI 插槽中）。

13. 如何修复不使用 Anthropic 时出现的 "No API key found for anthropic"？​

OpenClaw 通常默认为 Anthropic/Claude。如果您使用其他提供商（如 OpenAI 或 Ollama），必须在配置中显式将默认模型设置为不使用 Anthropic 的模型。

14. 如何修复 "Model Not Supported"（模型不支持）？​

OpenClaw 限制不安全或过时的模型。

  • 解决方案： 运行 openclaw models list 查看支持的模型，并更新配置以使用其中之一。

15. 如何修复 "Validation failed for tool 'exec'"（工具 'exec' 验证失败）？​

这通常发生在严格验证工具调用 JSON 架构的本地 LLM（如 Ollama）上。

  • 解决方案： 确保配置中的工具定义与 LLM 预期的架构完全匹配。这通常是属性名称不匹配（例如 cmd 与 command）。

16. 如何验证我的配置文件？​

运行命令：

openclaw config validate

这将检查语法错误和缺失的必填字段。

故障排除错误​

17. 如何修复 API 密钥 401 Unauthorized 错误？​

  • 无效密钥： 您可能复制了错误的密钥或密钥已过期。
  • 格式： 确保它以正确的前缀开头（例如 sk-...）。
  • 账户： 检查您的 API 提供商账户是否处于活动状态且有余额。

18. 如何修复 Model Not Found (404) 错误？​

  • 拼写错误： 检查配置中的模型 ID（例如 gpt-4o 与 gpt-4-0）。
  • 访问权限： 您的 API 密钥可能无权访问该特定模型。

19. 如何修复 Rate Limited (429) 错误？​

  • 减速： 请求发送过快。
  • 配额： 使用付费计划或向提供商申请提高速率限制。

20. 如何修复 Internal Server Error (500)？​

这通常是 API 提供商方面的问题。请稍等几分钟重试。如果问题持续存在，请检查 OpenClaw 日志以获取更具体的错误详细信息。

21. 如何修复 "Connection refused"（连接被拒绝）错误？​

  • Base URL： 检查配置中的 baseUrl 是否正确。
  • 服务当机： 如果使用本地模型（Ollama/LM Studio），请确保该服务正在运行。
  • 网络： 检查您的互联网连接。

22. 如何修复 BaseURL 特有的 "Connection refused"？​

如果在 Docker 容器内连接到本地服务（如 Ollama），localhost 指的是容器，而不是主机。

  • 解决方案： 在配置 baseUrl 中使用 host.docker.internal 代替 localhost。

23. 如何修复 "OpenClaw Not Responding"（OpenClaw 无响应）？​

  • 网关状态： 运行 openclaw gateway status。
  • 重启： 运行 openclaw gateway restart。
  • LLM 卡死： 模型可能正在处理非常长的上下文。

24. 如何修复 "DNS Label Length Error"？​

这会导致服务崩溃。

  • 原因： 主机名对于 mDNS 来说太长（最大 63 字节）。
  • 解决方案： 将您的主机或容器重命名为较短的名称。

使用与连接​

25. 如何修复 "Messaging Channel Not Connecting"（消息频道未连接）？​

  • 凭据： 仔细检查该平台的令牌/密钥（Discord/Slack/Telegram）。
  • Webhooks： 确保您的 Webhook URL 可从互联网访问（本地测试可能需要 Cloudflare 或 Ngrok 等隧道）。

26. 如何修复 "Messages Not Triggering Responses"（消息未触发响应）？​

  • 日志： 检查日志以查看是否收到消息。
  • 隐私模式： 对于 Telegram，在 BotFather 中禁用“群组隐私”（Group Privacy），以便机器人可以看到消息。
  • 权限： 确保机器人有在该频道发帖的权限。

27. 如何修复 "Extra Workspace Folders Detected"（检测到额外的工作区文件夹）？​

为了避免状态冲突，OpenClaw 建议仅保留一个活动工作区。

  • 解决方案： 从配置的工作区目录中归档或删除旧的工作区文件夹。

28. 为了获得最佳效果，我该如何与 OpenClaw 互动？​

把它当作远程实习生。指令要具体。使用“心跳规则”（Heartbeat Rule，即要求它定期报告状态）。为了安全起见，对于让它访问的任何服务，请使用“一次性”或受限的凭据。

29. 如何使用 Nginx 保护 OpenClaw？​

如果将 OpenClaw 暴露给网络：

  • 受信任的代理： 配置 Nginx 以识别受信任的代理。
  • 认证： 保护 auth-profiles.json。
  • SSL： 始终使用 HTTPS（Let's Encrypt）。

30. 如何运行诊断？​

运行 doctor 命令以检查系统和配置运行状况：

openclaw doctor