常见问题

快速解答以及针对真实场景(本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移)的深度故障排除。运行时诊断请参阅故障排除。完整配置参考请参阅配置。

目录

• 快速入门和首次运行设置
  • 遇到困难了,最快的解决方法是什么?
  • 推荐的 OpenClaw 安装和设置方法是什么?
  • 引导完成后如何打开仪表板?
  • 如何在 localhost 和远程环境中验证仪表板(令牌)?
  • 需要什么运行时?
  • 能在树莓派上运行吗?
  • 树莓派安装有什么技巧?
  • 卡在"wake up my friend"/引导无法孵化,怎么办?
  • 可以将设置迁移到新机器(Mac mini)而不重新进行引导吗?
  • 在哪里查看最新版本的新功能?
  • 无法访问 docs.openclaw.ai(SSL 错误),怎么办?
  • stable 和 beta 有什么区别?
  • 如何安装 beta 版本,beta 和 dev 有什么区别?
  • 如何尝试最新版本?
  • 安装和引导通常需要多长时间?
  • 安装程序卡住了?如何获取更多反馈?
  • Windows 安装显示找不到 git 或无法识别 openclaw
  • 文档没有回答我的问题 - 如何获得更好的答案?
  • 如何在 Linux 上安装 OpenClaw?
  • 如何在 VPS 上安装 OpenClaw?
  • 云/VPS 安装指南在哪里?
  • 可以让 OpenClaw 自我更新吗?
  • 引导向导实际上做什么?
  • 运行这个需要 Claude 或 OpenAI 订阅吗?
  • 可以在没有 API 密钥的情况下使用 Claude Max 订阅吗
  • Anthropic "setup-token" 认证如何工作?
  • 在哪里找到 Anthropic setup-token?
  • 支持 Claude 订阅认证(Claude Code OAuth)吗?
  • 为什么我会看到来自 Anthropic 的 HTTP 429 RateLimitError?
  • 支持 AWS Bedrock 吗?
  • Codex 认证如何工作?
  • 支持 OpenAI 订阅认证(Codex OAuth)吗?
  • 如何设置 Gemini CLI OAuth
  • 本地模型可以用于日常聊天吗?
  • 如何将托管模型流量保持在特定区域?
  • 必须购买 Mac Mini 才能安装吗?
  • 需要 Mac mini 来支持 iMessage 吗?
  • 如果我买一台 Mac mini 来运行 OpenClaw,可以将它连接到我的 MacBook Pro 吗?
  • 可以使用 Bun 吗?
  • Telegram:allowFrom 中应该填什么?
  • 多人可以使用同一个 WhatsApp 号码配合不同的 OpenClaw 实例吗?
  • 可以运行一个"快速聊天"智能体和一个"Opus 用于编码"的智能体吗?
  • Homebrew 在 Linux 上可用吗?
  • 可修改(git)安装和 npm 安装有什么区别?
  • 以后可以在 npm 和 git 安装之间切换吗?
  • 应该在笔记本电脑上还是 VPS 上运行网关?
  • 在专用机器上运行 OpenClaw 有多重要?
  • 最低 VPS 要求和推荐的操作系统是什么?
  • 可以在虚拟机中运行 OpenClaw,需要什么配置
• 什么是 OpenClaw?
  • 用一段话介绍什么是 OpenClaw?
  • 价值主张是什么?
  • 刚设置好应该先做什么
  • OpenClaw 的五大日常用例是什么
  • OpenClaw 能帮助 SaaS 进行潜在客户开发、推广、广告和博客吗
  • 与 Claude Code 相比在 Web 开发方面有什么优势?
• 技能和自动化
  • 如何在不使仓库变脏的情况下自定义技能?
  • 可以从自定义文件夹加载技能吗?
  • 如何为不同任务使用不同模型?
  • 机器人在处理繁重工作时冻结,如何卸载?
  • Cron 或提醒不触发,应该检查什么?
  • 如何在 Linux 上安装技能?
  • OpenClaw 可以按计划或在后台持续运行任务吗?
  • 可以从 Linux 运行 Apple/macOS 专用技能吗?
  • 有 Notion 或 HeyGen 集成吗?
  • 如何安装用于浏览器接管的 Chrome 扩展?
• 沙箱和内存
  • 有专门的沙箱文档吗?
  • 如何将主机文件夹绑定到沙箱?
  • 内存如何工作?
  • 内存一直忘记东西,如何让它保持?
  • 内存会永久保存吗?有什么限制?
  • 语义内存搜索需要 OpenAI API 密钥吗?
• 磁盘上的文件位置
  • OpenClaw 使用的所有数据都保存在本地吗?
  • OpenClaw 将数据存储在哪里?
  • AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放在哪里?
  • 推荐的备份策略是什么?
  • 如何完全卸载 OpenClaw?
  • 智能体可以在工作区外工作吗?
  • 我在远程模式 - 会话存储在哪里?
• 配置基础
  • 配置是什么格式?在哪里?
  • 我设置了 gateway.bind: lan(或 tailnet),现在什么都没监听/UI 显示未授权
  • 为什么现在在 localhost 上需要令牌?
  • 更改配置后必须重启吗?
  • 如何启用 Web 搜索(和 Web 获取)?
  • config.apply 清空了我的配置,如何恢复并避免这种情况?
  • 如何在多个设备上运行中央网关和专用工作器?
  • OpenClaw 浏览器可以无头运行吗?
  • 如何使用 Brave 进行浏览器控制?
• 远程网关 + 节点
  • 命令如何在 Telegram、网关和节点之间传播?
  • 如果网关托管在远程,我的智能体如何访问我的计算机?
  • Tailscale 已连接但我没有收到回复,怎么办?
  • 两个 OpenClaw 实例可以互相通信吗(本地 + VPS)?
  • 多个智能体需要单独的 VPS 吗
  • 在个人笔记本电脑上使用节点而不是从 VPS SSH 有好处吗?
  • 节点运行网关服务吗?
  • 是否有 API/RPC 方式来应用配置?
  • 首次安装的最小"合理"配置是什么?
  • 如何在 VPS 上设置 Tailscale 并从 Mac 连接?
  • 如何将 Mac 节点连接到远程网关(Tailscale Serve)?
  • 应该在第二台笔记本电脑上安装还是只添加一个节点?
• 环境变量和 .env 加载
  • OpenClaw 如何加载环境变量?
  • "我通过服务启动了网关,我的环境变量消失了。"怎么办?
  • 我设置了 COPILOT_GITHUB_TOKEN,但模型状态显示"Shell env: off。"为什么?
• 会话和多个聊天
  • 如何开始新的对话?
  • 如果我从不发送 /new,会话会自动重置吗?
  • 有办法让 OpenClaw 实例组成一个团队,一个 CEO 和许多智能体吗
  • 为什么上下文在任务中途被截断?如何防止?
  • 如何完全重置 OpenClaw 但保持安装?
  • 我遇到"上下文过大"错误 - 如何重置或压缩?
  • 为什么我看到"LLM 请求被拒绝:messages.N.content.X.tool_use.input:必填字段"?
  • 为什么我每 30 分钟收到一次心跳消息?
  • 需要将"机器人账户"添加到 WhatsApp 群组吗?
  • 如何获取 WhatsApp 群组的 JID?
  • 为什么 OpenClaw 不在群组中回复?
  • 群组/线程与私聊共享上下文吗?
  • 可以创建多少个工作区和智能体?
  • 可以同时运行多个机器人或聊天(Slack)吗,应该如何设置?
• 模型:默认值、选择、别名、切换
  • 什么是"默认模型"?
  • 你推荐什么模型?
  • 如何在不清空配置的情况下切换模型?
  • 可以使用自托管模型(llama.cpp、vLLM、Ollama)吗?
  • OpenClaw、Flawd 和 Krill 使用什么模型?
  • 如何即时切换模型(无需重启)?
  • 可以使用 GPT 5.2 进行日常任务和 Codex 5.2 进行编码吗
  • 为什么我看到"模型...不允许"然后没有回复?
  • 为什么我看到"未知模型:minimax/MiniMax-M2.1"?
  • 可以使用 MiniMax 作为默认模型,OpenAI 用于复杂任务吗?
  • opus/sonnet/gpt 是内置快捷方式吗?
  • 如何定义/覆盖模型快捷方式(别名)?
  • 如何添加其他提供商(如 OpenRouter 或 Z.AI)的模型?
• 模型故障转移和"所有模型失败"
  • 故障转移如何工作?
  • 这个错误是什么意思?
  • 修复清单:找不到配置文件 anthropic:default 的凭据
  • 为什么它还尝试了 Google Gemini 并失败了?
• 认证配置文件:它们是什么以及如何管理
  • 什么是认证配置文件?
  • 典型的配置文件 ID 有哪些?
  • 可以控制首先尝试哪个认证配置文件吗?
  • OAuth 与 API 密钥:有什么区别?
• 网关:端口、"已在运行"和远程模式
  • 网关使用什么端口?
  • 为什么 openclaw gateway status 显示 Runtime: running 但 RPC probe failed?
  • 为什么 openclaw gateway status 显示 Config (cli) 和 Config (service) 不同?
  • "另一个网关实例已在监听"是什么意思?
  • 如何在远程模式下运行 OpenClaw(客户端连接到其他地方的网关)?
  • 控制 UI 显示"未授权"(或不断重新连接),怎么办?
  • 我设置了 gateway.bind: tailnet 但它无法绑定/没有监听
  • 可以在同一主机上运行多个网关吗?
  • "无效握手"/代码 1008 是什么意思?
• 日志记录和调试
  • 日志在哪里?
  • 如何启动/停止/重启网关服务?
  • 我在 Windows 上关闭了终端 - 如何重启 OpenClaw?
  • 网关正在运行但回复从未到达,应该检查什么?
  • "从网关断开连接:无原因" - 怎么办?
  • Telegram setMyCommands 失败并出现网络错误,应该检查什么?
  • TUI 没有输出,应该检查什么?
  • 如何完全停止然后启动网关?
  • ELI5:openclaw gateway restart 与 openclaw gateway
  • 当某些东西失败时,获取更多详细信息的最快方法是什么?
• 媒体和附件
  • 我的技能生成了图像/PDF,但什么都没发送
• 安全和访问控制
  • 将 OpenClaw 暴露给入站私聊安全吗?
  • 提示注入只是公共机器人的问题吗?
  • 我的机器人应该有自己的电子邮件 GitHub 账户或电话号码吗
  • 可以让它自主处理我的短信吗,这样安全吗
  • 可以使用更便宜的模型进行个人助理任务吗?
  • 我在 Telegram 中运行了 /start 但没有收到配对代码
  • WhatsApp:会给我的联系人发消息吗?配对如何工作?
• 聊天命令、中止任务和"它停不下来"
  • 如何阻止内部系统消息显示在聊天中
  • 如何停止/取消正在运行的任务?
  • 如何从 Telegram 发送 Discord 消息?("跨上下文消息被拒绝")
  • 为什么感觉机器人"忽略"了快速连续的消息?

如果出现问题的前 60 秒

1. 快速状态(首次检查)

   openclaw status

   快速本地摘要:操作系统 + 更新、网关/服务可达性、智能体/会话、提供商配置 + 运行时问题(当网关可达时)。

2. 可粘贴报告(安全共享)

   openclaw doctor --report

   只读诊断,带日志尾部(令牌已编辑)。

3. 守护进程 + 端口状态

   openclaw gateway status

   显示监督器运行时与 RPC 可达性、探测目标 URL 以及服务可能使用的配置。

4. 深度探测

   openclaw probes

   运行网关健康检查 + 提供商探测(需要可达