Help

快速解答及针对实际部署场景（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）的深入故障排除。运行时诊断请参阅故障排除。完整配置参考请参阅配置。 目录 快速开始与首次运行设置 我卡住了，最快的排障方法是什么？ 安装和设置 OpenClaw 的推荐方式是什么？ 新手引导后如何打开仪表板？ 如何在本地和远程环境中验证仪表板（令牌）？ 我需要什么运行时？ 能在 Raspberry Pi 上运行吗？ Raspberry Pi 安装有什么建议？ 卡在 “wake up my friend” / 新手引导无法启动，怎么办？ 能否将我的设置迁移到新机器（Mac mini）而不重新进行新手引导？ 在哪里查看最新版本的更新内容？ 无法访问 docs.openclaw.ai（SSL 错误），怎么办？ stable 和 beta 有什么区别？ 如何安装 beta 版本，beta 和 dev 有什么区别？ 如何试用最新代码？ 安装和新手引导通常需要多长时间？ 安装程序卡住了？如何获取更多反馈？ Windows 安装提示找不到 git 或无法识别 openclaw 文档没有解答我的问题——如何获得更好的答案？ 如何在 Linux 上安装 OpenClaw？ 如何在 VPS 上安装 OpenClaw？ 云/VPS 安装指南在哪里？ 可以让 OpenClaw 自行更新吗？ 新手引导向导具体做了什么？ 运行 OpenClaw 需要 Claude 或 OpenAI 订阅吗？ 能否使用 Claude Max 订阅而不需要 API 密钥？ Anthropic “setup-token” 认证如何工作？ 在哪里获取 Anthropic setup-token？ 是否支持 Claude 订阅认证（Claude Code OAuth）？ 为什么我看到 HTTP 429: rate_limit_error（来自 Anthropic）？ 支持 AWS Bedrock 吗？ Codex 认证如何工作？ 是否支持 OpenAI 订阅认证（Codex OAuth）？ 如何设置 Gemini CLI OAuth？ 本地模型适合日常聊天吗？ 如何将托管模型流量限制在特定区域？ 我必须购买 Mac Mini 才能安装吗？ iMessage 支持需要 Mac mini 吗？ 如果我买了 Mac mini 运行 OpenClaw，能连接到我的 MacBook Pro 吗？ 可以使用 Bun 吗？ Telegram：allowFrom 填什么？ 多人能否使用同一个 WhatsApp 号码配合不同的 OpenClaw 实例？ 能否同时运行一个“快速聊天”智能体和一个“用 Opus 编程”的智能体？ Homebrew 在 Linux 上可用吗？ 可编辑（git）安装和 npm 安装有什么区别？ 之后可以在 npm 和 git 安装之间切换吗？ 应该在笔记本电脑还是 VPS 上运行 Gateway 网关？ 在专用机器上运行 OpenClaw 有多重要？ VPS 的最低要求和推荐操作系统是什么？ 可以在虚拟机中运行 OpenClaw 吗？有什么要求？ 什么是 OpenClaw？ 用一段话描述 OpenClaw？ 价值主张是什么？ 刚设置好，应该先做什么？ OpenClaw 日常最常用的五个场景是什么？ OpenClaw 能否帮助 SaaS 进行获客、外联、广告和博客？ 相比 Claude Code，在 Web 开发方面有什么优势？ Skills 与自动化 如何自定义 Skills 而不弄脏仓库？ 可以从自定义文件夹加载 Skills 吗？ 如何为不同任务使用不同模型？ 机器人在执行繁重工作时卡住了，如何卸载任务？ 定时任务或提醒没有触发，应该检查什么？ 如何在 Linux 上安装 Skills？ OpenClaw 能否按计划或在后台持续运行任务？ 能否从 Linux 运行仅限 Apple/macOS 的 Skills？ 有 Notion 或 HeyGen 集成吗？ 如何安装用于浏览器接管的 Chrome 扩展？ 沙箱与记忆 有专门的沙箱文档吗？ 如何将主机文件夹绑定到沙箱中？ 记忆是如何工作的？ 记忆总是遗忘，如何让它持久保存？ 记忆是否永久保留？有什么限制？ 语义记忆搜索需要 OpenAI API 密钥吗？ 磁盘上的文件位置 OpenClaw 使用的所有数据都保存在本地吗？ OpenClaw 将数据存储在哪里？ AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放在哪里？ 推荐的备份策略是什么？ 如何完全卸载 OpenClaw？ 智能体可以在工作区外工作吗？ 我处于远程模式——会话存储在哪里？ 配置基础 配置文件是什么格式？在哪里？ 我设置了 gateway.bind: "lan"（或 "tailnet"），现在什么都监听不了 / UI 显示未授权 为什么现在在 localhost 也需要令牌？ 更改配置后需要重启吗？ 如何启用网络搜索（和网页抓取）？ config.apply 清空了我的配置，如何恢复和避免？ 如何运行一个中心 Gateway 网关配合跨设备的专用工作节点？ OpenClaw 浏览器可以无头运行吗？ 如何使用 Brave 进行浏览器控制？ 远程 Gateway 网关与节点 命令如何在 Telegram、Gateway 网关和节点之间传播？ 如果 Gateway 网关托管在远程，我的智能体如何访问我的电脑？ Tailscale 已连接但收不到回复，怎么办？ 两个 OpenClaw 实例（本地 + VPS）可以互相通信吗？ 多个智能体需要独立的 VPS 吗？ 在个人笔记本电脑上使用节点而不是从 VPS SSH 有什么好处？ 节点会运行 Gateway 网关服务吗？ 有 API / RPC 方式来应用配置吗？ 首次安装的最小“合理”配置是什么？ 如何在 VPS 上设置 Tailscale 并从 Mac 连接？ 如何将 Mac 节点连接到远程 Gateway 网关（Tailscale Serve）？ 应该在第二台笔记本上安装还是只添加一个节点？ 环境变量和 .env 加载 OpenClaw 如何加载环境变量？ “我通过服务启动了 Gateway 网关，但环境变量消失了。”怎么办？ 我设置了 COPILOT_GITHUB_TOKEN，但 models status 显示"Shell env: off"，为什么？ 会话与多聊天 如何开始一个新对话？ 如果我从不发送 /new，会话会自动重置吗？ 能否创建一个 OpenClaw 实例团队——一个 CEO 和多个智能体？ 为什么上下文在任务中途被截断了？如何防止？ 如何完全重置 OpenClaw 但保留安装？ 我遇到了"context too large"错误——如何重置或压缩？ 为什么我看到"LLM request rejected: messages.N.content.X.tool_use.input: Field required"？ 为什么每 30 分钟收到一次心跳消息？ 需要在 WhatsApp 群组中添加“机器人账号”吗？ 如何获取 WhatsApp 群组的 JID？ 为什么 OpenClaw 不在群组中回复？ 群组/线程与私聊共享上下文吗？ 可以创建多少个工作区和智能体？ 可以同时运行多个机器人或聊天（Slack）吗？应该如何设置？ 模型：默认值、选择、别名、切换 什么是“默认模型”？ 推荐什么模型？ 如何在不清空配置的情况下切换模型？ 可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？ OpenClaw、Flawd 和 Krill 使用什么模型？ 如何在运行中切换模型（无需重启）？ 能否日常任务用 GPT 5.2，编程用 Codex 5.2？ 为什么我看到"Model … is not allowed"然后没有回复？ 为什么我看到"Unknown model: minimax/MiniMax-M2.1"？ 能否将 MiniMax 设为默认，复杂任务用 OpenAI？ opus / sonnet / gpt 是内置快捷方式吗？ 如何定义/覆盖模型快捷方式（别名）？ 如何添加其他提供商（如 OpenRouter 或 Z.AI）的模型？ 模型故障转移与"All models failed" 故障转移是如何工作的？ 这个错误是什么意思？ No credentials found for profile "anthropic:default" 的修复清单 为什么还尝试了 Google Gemini 并且失败了？ 认证配置文件：概念和管理方式 什么是认证配置文件？ 典型的配置文件 ID 有哪些？ 可以控制首先尝试哪个认证配置文件吗？ OAuth 与 API 密钥：有什么区别？ Gateway 网关：端口、“已在运行”和远程模式 Gateway 网关使用什么端口？ 为什么 openclaw gateway status 显示 Runtime: running 但 RPC probe: failed？ 为什么 openclaw gateway status 显示 Config (cli) 和 Config (service) 不同？ “another gateway instance is already listening"是什么意思？ 如何以远程模式运行 OpenClaw（客户端连接到其他位置的 Gateway 网关）？ 控制 UI 显示"unauthorized”（或持续重连），怎么办？ 我设置了 gateway.bind: "tailnet" 但无法绑定 / 什么都没监听 可以在同一主机上运行多个 Gateway 网关吗？ “invalid handshake” / code 1008 是什么意思？ 日志与调试 日志在哪里？ 如何启动/停止/重启 Gateway 网关服务？ 我在 Windows 上关闭了终端——如何重启 OpenClaw？ Gateway 网关已启动但回复始终不到达，应该检查什么？ “Disconnected from gateway: no reason”——怎么办？ Telegram setMyCommands 因网络错误失败，应该检查什么？ TUI 没有输出，应该检查什么？ 如何完全停止然后启动 Gateway 网关？ 通俗解释：openclaw gateway restart 与 openclaw gateway 出现故障时获取更多详情的最快方法是什么？ 媒体与附件 我的 Skills 生成了图片/PDF，但什么都没发送 安全与访问控制 将 OpenClaw 暴露给入站私信安全吗？ 提示注入只对公开机器人有影响吗？ 我的机器人应该有自己的邮箱、GitHub 账户或电话号码吗？ 我能让它自主管理我的短信吗？这安全吗？ 个人助理任务可以使用更便宜的模型吗？ 我在 Telegram 中运行了 /start 但没收到配对码 WhatsApp：会给我的联系人发消息吗？配对如何工作？ 聊天命令、中止任务和“停不下来” 如何阻止内部系统消息显示在聊天中？ 如何停止/取消正在运行的任务？ 如何从 Telegram 发送 Discord 消息？（“Cross-context messaging denied”） 为什么感觉机器人“忽略”了快速连发的消息？ 出问题后的最初六十秒 快速状态（首先检查） ...

最初的六十秒 按顺序运行这些命令： openclaw status openclaw status --all openclaw gateway probe openclaw logs --follow openclaw doctor 如果 Gateway 网关可达，进行深度探测： openclaw status --deep 常见的“它坏了”情况 openclaw: command not found 几乎总是 Node/npm PATH 问题。从这里开始： 安装（Node/npm PATH 安装完整性检查） 安装程序失败（或你需要完整日志） 以详细模式重新运行安装程序以查看完整跟踪和 npm 输出： curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose 对于 beta 安装： curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose 你也可以设置 OPENCLAW_VERBOSE=1 代替标志。 Gateway 网关“unauthorized”、无法连接或持续重连 Gateway 网关故障排除 Gateway 网关认证 控制 UI 在 HTTP 上失败（需要设备身份） Gateway 网关故障排除 控制 UI docs.openclaw.ai 显示 SSL 错误（Comcast/Xfinity） 一些 Comcast/Xfinity 连接通过 Xfinity Advanced Security 阻止 docs.openclaw.ai。 禁用 Advanced Security 或将 docs.openclaw.ai 添加到允许列表，然后重试。 ...

OpenClaw 包含三个 Vitest 测试套件（单元/集成、端到端、实时）以及一小组 Docker 运行器。 本文档是一份"我们如何测试"的指南： 每个套件覆盖什么（以及它刻意不覆盖什么） 常见工作流程应运行哪些命令（本地、推送前、调试） 实时测试如何发现凭证并选择模型/提供商 如何为现实中的模型/提供商问题添加回归测试 快速开始 日常使用： 完整检查（推送前的预期流程）：pnpm build && pnpm check && pnpm test 当你修改测试或需要额外的信心时： 覆盖率检查：pnpm test:coverage 端到端套件：pnpm test:e2e 调试真实提供商/模型时（需要真实凭证）： 实时套件（模型 + Gateway 网关工具/图像探测）：pnpm test:live 提示：当你只需要一个失败用例时，建议使用下文描述的允许列表环境变量来缩小实时测试范围。 测试套件（在哪里运行什么） 可以将这些套件理解为"逐渐增强的真实性"（以及逐渐增加的不稳定性/成本）： 单元/集成测试（默认） 命令：pnpm test 配置：vitest.config.ts 文件：src/**/*.test.ts 范围： 纯单元测试 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置） 已知问题的确定性回归测试 预期： 在 CI 中运行 不需要真实密钥 应该快速且稳定 端到端测试（Gateway 网关冒烟测试） 命令：pnpm test:e2e 配置：vitest.e2e.config.ts 文件：src/**/*.e2e.test.ts 范围： 多实例 Gateway 网关端到端行为 WebSocket/HTTP 接口、节点配对和较重的网络操作 预期： 在 CI 中运行（当在流水线中启用时） 不需要真实密钥 比单元测试有更多活动部件（可能较慢） 实时测试（真实提供商 + 真实模型） 命令：pnpm test:live 配置：vitest.live.config.ts 文件：src/**/*.live.test.ts 默认：通过 pnpm test:live 启用（设置 OPENCLAW_LIVE_TEST=1） 范围： “这个提供商/模型用真实凭证今天实际能工作吗？” 捕获提供商格式变更、工具调用怪癖、认证问题和速率限制行为 预期： 设计上不适合 CI 稳定运行（真实网络、真实提供商策略、配额、故障） 花费金钱/使用速率限制 建议运行缩小范围的子集而非"全部" 实时运行会加载 ~/.profile 以获取缺失的 API 密钥 Anthropic 密钥轮换：设置 OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..."（或 OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...）或多个 ANTHROPIC_API_KEY* 变量；测试会在遇到速率限制时重试 我应该运行哪个套件？ 使用这个决策表： ...

OpenClaw 从多个来源拉取环境变量。规则是永不覆盖现有值。 优先级（从高到低） 进程环境（Gateway 网关进程从父 shell/守护进程已有的内容）。 当前工作目录中的 .env（dotenv 默认；不覆盖）。 全局 .env 位于 ~/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env；不覆盖）。 配置 env 块 位于 ~/.openclaw/openclaw.json（仅在缺失时应用）。 可选的登录 shell 导入（env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1），仅对缺失的预期键名应用。 如果配置文件完全缺失，步骤 4 将被跳过；如果启用了 shell 导入，它仍会运行。 配置 env 块 两种等效方式设置内联环境变量（都是非覆盖的）： { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, }, } Shell 环境导入 env.shellEnv 运行你的登录 shell 并仅导入缺失的预期键名： { env: { shellEnv: { enabled: true, timeoutMs: 15000, }, }, } 环境变量等效项： OPENCLAW_LOAD_SHELL_ENV=1 OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 配置中的环境变量替换 你可以使用 ${VAR_NAME} 语法在配置字符串值中直接引用环境变量： ...

scripts/ 目录包含用于本地工作流和运维任务的辅助脚本。 当任务明确与某个脚本相关时使用这些脚本；否则优先使用 CLI。 约定 除非在文档或发布检查清单中引用，否则脚本为可选。 当 CLI 接口存在时优先使用（例如：认证监控使用 openclaw models status --check）。 假定脚本与特定主机相关；在新机器上运行前请先阅读脚本内容。 认证监控脚本 认证监控脚本的文档请参阅： /automation/auth-monitoring 添加脚本时 保持脚本专注且有文档说明。 在相关文档中添加简短条目（如果缺少则创建一个）。

本页介绍用于流式输出的调试辅助工具，特别是当提供商将推理混入正常文本时。 运行时调试覆盖 在聊天中使用 /debug 设置仅运行时配置覆盖（内存中，不写入磁盘）。 /debug 默认禁用；通过 commands.debug: true 启用。 当你需要切换不常用的设置而不编辑 openclaw.json 时，这非常方便。 示例： /debug show /debug set messages.responsePrefix="[openclaw]" /debug unset messages.responsePrefix /debug reset /debug reset 清除所有覆盖并返回到磁盘上的配置。 Gateway 网关监视模式 为了快速迭代，在文件监视器下运行 Gateway 网关： pnpm gateway:watch --force 这映射到： tsx watch src/entry.ts gateway --force 在 gateway:watch 后添加任何 Gateway 网关 CLI 标志，它们将在每次重启时传递。 Dev 配置文件 + dev Gateway 网关（–dev） 使用 dev 配置文件来隔离状态，并启动一个安全、可丢弃的调试设置。有两个 --dev 标志： 全局 --dev（配置文件）： 将状态隔离到 ~/.openclaw-dev 下，并将 Gateway 网关端口默认为 19001（派生端口随之移动）。 gateway --dev：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区（并跳过 BOOTSTRAP.md）。 推荐流程（dev 配置文件 + dev 引导）： ...