FAQ

快速解答和深度故障排除，涵盖真实场景（本地开发、VPS、多 Agent、OAuth/API 密钥、模型故障转移）。运行时诊断请参考故障排除。完整配置参考请参考配置。

目录

出问题时的前 60 秒

  1. 快速状态检查（首先检查）

    openclaw status

    快速本地摘要：操作系统 + 更新、Gateway/服务可达性、Agent/Session、Provider 配置 + 运行时问题（当 Gateway 可达时）。

  2. 可粘贴报告（安全分享）

    openclaw status --all

    只读诊断，带日志尾部（Token 已脱敏）。

  3. Daemon + 端口状态

    openclaw gateway status

    显示 supervisor 运行时 vs RPC 可达性、探测目标 URL，以及服务可能使用的配置。

  4. 深度探测

    openclaw status --deep

    运行 Gateway 健康检查 + Provider 探测（需要可达的 Gateway）。参见 Health。

  5. 查看最新日志

    openclaw logs --follow

    如果 RPC 不可用，回退到：

    tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"

    文件日志与服务日志是分开的；参见 Logging 和 Troubleshooting。

  6. 运行医生（修复）

    openclaw doctor

    修复/迁移配置/状态 + 运行健康检查。参见 Doctor。

  7. Gateway 快照

    openclaw health --json
openclaw health --verbose   # 出错时显示目标 URL + 配置路径

    向运行中的 Gateway 请求完整快照（仅 WS）。参见 Health。

快速开始和首次运行设置

我卡住了，最快的解决办法是什么？

使用能看到你机器的本地 AI Agent。这比在 Discord 上提问有效得多，因为大多数”我卡住了”的情况都是本地配置或环境问题，远程帮助者无法检查。

这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置（PATH、服务、权限、认证文件）。通过可修改（git）安装给它们完整的源代码检出：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

这会从 git 检出安装 OpenClaw，这样 Agent 就能读取代码 + 文档，并推理你正在运行的确切版本。你随时可以通过重新运行安装程序（不带 --install-method git）切换回稳定版。

提示：让 Agent 规划和监督修复（逐步进行），然后只执行必要的命令。这样可以保持更改小而易于审计。

如果你发现了真正的 bug 或修复方案，请提交 GitHub issue 或发送 PR： https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls

从这些命令开始（寻求帮助时分享输出）：

openclaw status
openclaw models status
openclaw doctor

它们的作用：

  • openclaw status：Gateway/Agent 健康状况 + 基本配置的快速快照。
  • openclaw models status：检查 Provider 认证 + 模型可用性。
  • openclaw doctor：验证并修复常见的配置/状态问题。

其他有用的 CLI 检查：openclaw status --all、openclaw logs --follow、openclaw gateway status、openclaw health --verbose。

快速调试循环：出问题时的前 60 秒。 安装文档：Install、Installer flags、Updating。

推荐的安装和设置 OpenClaw 的方式是什么？

仓库推荐从源代码运行并使用引导向导：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

向导还可以自动构建 UI 资源。引导完成后，你通常会在端口 18789 上运行 Gateway。

从源代码（贡献者/开发）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build # 首次运行时自动安装 UI 依赖
openclaw onboard

如果你还没有全局安装，通过 pnpm openclaw onboard 运行。

引导完成后如何打开控制面板？

向导现在会在引导完成后立即用带 Token 的控制面板 URL 打开你的浏览器，并在摘要中打印完整链接（带 Token）。保持该标签页打开；如果没有启动，在同一台机器上复制/粘贴打印的 URL。Token 保留在你的主机本地 - 浏览器不会获取任何内容。

如何在 localhost 和远程环境下认证控制面板（token）？

Localhost（同一台机器）：

  • 打开 http://127.0.0.1:18789/。
  • 如果要求认证，运行 openclaw dashboard 并使用带 Token 的链接（?token=...）。
  • Token 与 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）的值相同，首次加载后由 UI 存储。

不在 localhost：

  • Tailscale Serve（推荐）：保持绑定 loopback，运行 openclaw gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，身份标头满足认证（无需 Token）。
  • Tailnet 绑定：运行 openclaw gateway --bind tailnet --token "<token>"，打开 http://<tailscale-ip>:18789/，在控制面板设置中粘贴 Token。
  • SSH 隧道：ssh -N -L 18789:127.0.0.1:18789 user@host 然后从 openclaw dashboard 打开 http://127.0.0.1:18789/?token=...。

参见 Dashboard 和 Web surfaces 了解绑定模式和认证详情。

需要什么运行时？

需要 Node >= 22。推荐使用 pnpm。Gateway 不推荐使用 Bun。

能在树莓派上运行吗？

可以。Gateway 很轻量 - 文档列出 512MB-1GB RAM、1 核和约 500MB 磁盘空间就足够个人使用，并且注明 树莓派 4 可以运行。

如果你想要额外的余量（日志、媒体、其他服务），推荐 2GB，但这不是硬性最低要求。

提示：小型树莓派/VPS 可以托管 Gateway，你可以在笔记本/手机上配对 nodes 来访问本地屏幕/摄像头/画布或执行命令。参见 Nodes。

树莓派安装有什么技巧？

简短版本：可以运行，但预期会有些粗糙边缘。

  • 使用 64 位操作系统并保持 Node >= 22。
  • 优先使用可修改（git）安装，这样你可以查看日志并快速更新。
  • 先不配置 Channel/Skill，然后逐个添加。
  • 如果遇到奇怪的二进制问题，通常是 ARM 兼容性问题。

文档：Linux、Install。

卡在”wake up my friend”/ 引导无法孵化，怎么办？

该屏幕依赖于 Gateway 可达且已认证。TUI 还会在首次孵化时自动发送”Wake up, my friend!”。如果你看到该行没有回复且 Token 保持为 0，说明 Agent 从未运行。

  1. 重启 Gateway：
openclaw gateway restart
  1. 检查状态 + 认证：
openclaw status
openclaw models status
openclaw logs --follow
  1. 如果仍然挂起，运行：
openclaw doctor

如果 Gateway 是远程的，确保隧道/Tailscale 连接正常，并且 UI 指向正确的 Gateway。参见 Remote access。

能否在不重新引导的情况下将设置迁移到新机器（Mac mini）？

可以。复制状态目录和 Workspace，然后运行一次 Doctor。只要你复制两个位置，这会保持你的机器人”完全相同”（内存、Session 历史、认证和 Channel 状态）：

  1. 在新机器上安装 OpenClaw。
  2. 从旧机器复制 $OPENCLAW_STATE_DIR（默认：~/.openclaw）。
  3. 复制你的 Workspace（默认：~/.openclaw/workspace）。
  4. 运行 openclaw doctor 并重启 Gateway 服务。

这会保留配置、认证配置文件、WhatsApp 凭据、Session 和内存。如果你处于远程模式，记住 Gateway 主机拥有 Session 存储和 Workspace。

重要：如果你只将 Workspace 提交/推送到 GitHub，你备份的是内存 + Bootstrap 文件，但不包括 Session 历史或认证。这些存储在 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/sessions/）。

相关：Migrating、Where things live on disk、Agent workspace、Doctor、Remote mode。

在哪里查看最新版本的更新内容？

查看 GitHub 更新日志： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

最新条目在顶部。如果顶部部分标记为 Unreleased，下一个带日期的部分就是最新发布版本。条目按 Highlights、Changes 和 Fixes 分组（需要时还有文档/其他部分）。

无法访问 docs.openclaw.ai（SSL 错误），怎么办？

某些 Comcast/Xfinity 连接通过 Xfinity Advanced Security 错误地阻止了 docs.openclaw.ai。禁用它或将 docs.openclaw.ai 加入白名单，然后重试。更多详情：Troubleshooting。 请在这里报告帮助我们解除封锁：https://spa.xfinity.com/check_url_status。

如果你仍然无法访问该站点，文档在 GitHub 上有镜像： https://github.com/openclaw/openclaw/tree/main/docs

stable 和 beta 有什么区别？

Stable 和 beta 是 npm dist-tags，不是独立的代码分支：

  • latest = stable
  • beta = 用于测试的早期构建

我们将构建发布到 beta，测试它们，一旦构建稳定就将同一版本提升到 latest。这就是为什么 beta 和 stable 可以指向同一版本。

查看更改内容： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

如何安装 beta 版本，beta 和 dev 有什么区别？

Beta 是 npm dist-tag beta（可能与 latest 匹配）。 Dev 是 main 的移动头（git）；发布时使用 npm dist-tag dev。

一行命令（macOS/Linux）：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

Windows 安装程序（PowerShell）： https://openclaw.ai/install.ps1

更多详情：Development channels 和 Installer flags。

安装和引导通常需要多长时间？

粗略指南：

  • **安装：**2-5 分钟
  • **引导：**5-15 分钟，取决于你配置多少 Channel/模型

如果挂起，使用 Installer stuck 和 Im stuck 中的快速调试循环。

如何尝试最新版本？

两个选项：

  1. Dev Channel（git checkout）：
openclaw update --channel dev

这会切换到 main 分支并从源代码更新。

  1. 可修改安装（从安装程序站点）：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

这会给你一个可以编辑的本地仓库，然后通过 git 更新。

如果你更喜欢手动干净克隆，使用：

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

文档：Update、Development channels、Install。

安装程序卡住了？如何获取更多反馈？

使用详细输出重新运行安装程序：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

Beta 安装带详细输出：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose

可修改（git）安装：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose

更多选项：Installer flags。

Windows 安装提示找不到 git 或无法识别 openclaw

两个常见的 Windows 问题：

1) npm error spawn git / git not found

  • 安装 Git for Windows 并确保 git 在你的 PATH 中。
  • 关闭并重新打开 PowerShell，然后重新运行安装程序。

2) 安装后无法识别 openclaw

  • 你的 npm 全局 bin 文件夹不在 PATH 中。
  • 检查路径： 
    npm config get prefix
  • 确保 <prefix>\\bin 在 PATH 中（在大多数系统上是 %AppData%\\npm）。
  • 更新 PATH 后关闭并重新打开 PowerShell。

如果你想要最流畅的 Windows 设置，使用 WSL2 而不是原生 Windows。 文档：Windows。

文档没有回答我的问题 - 如何获得更好的答案？

使用可修改（git）安装，这样你就有完整的源代码和本地文档，然后_从该文件夹_询问你的机器人（或 Claude/Codex），这样它就可以读取仓库并精确回答。

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

更多详情：Install 和 Installer flags。

如何在 Linux 上安装 OpenClaw？

简短答案：遵循 Linux 指南，然后运行引导向导。

如何在 VPS 上安装 OpenClaw？

任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway。

指南：exe.dev、Hetzner、Fly.io。 远程访问：Gateway remote。

云/VPS 安装指南在哪里？

我们有一个托管中心，包含常见的 Provider。选择一个并遵循指南：

云中的工作方式：Gateway 在服务器上运行，你通过 Control UI（或 Tailscale/SSH）从笔记本/手机访问它。你的状态 + Workspace 存储在服务器上，所以将主机视为真实来源并备份它。

你可以将 nodes（Mac/iOS/Android/headless）配对到该云 Gateway，以访问本地屏幕/摄像头/画布或在笔记本上运行命令，同时将 Gateway 保留在云中。

中心：Platforms。远程访问：Gateway remote。 Nodes：Nodes、Nodes CLI。

能让 OpenClaw 自己更新吗？

简短答案：可能，但不推荐。更新流程可能会重启 Gateway（这会断开活动 Session），可能需要干净的 git checkout，并且可能会提示确认。更安全的做法：作为操作员从 shell 运行更新。

使用 CLI：

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart

如果你必须从 Agent 自动化：

openclaw update --yes --no-restart
openclaw gateway restart

文档：Update、Updating。

引导向导实际上做了什么？

openclaw onboard 是推荐的设置路径。在本地模式下，它会引导你完成：

  • 模型/认证设置（推荐使用 Anthropic setup-token 用于 Claude 订阅，支持 OpenAI Codex OAuth，可选 API 密钥，支持 LM Studio 本地模型）
  • Workspace 位置 + Bootstrap 文件
  • Gateway 设置（bind/port/auth/tailscale）
  • Providers（WhatsApp、Telegram、Discord、Mattermost（Plugin）、Signal、iMessage）
  • Daemon 安装（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元）
  • 健康检查和 Skill 选择

如果你配置的模型未知或缺少认证，它还会发出警告。

运行这个需要 Claude 或 OpenAI 订阅吗？

不需要。你可以使用 API 密钥（Anthropic/OpenAI/其他）或仅本地模型运行 OpenClaw，这样你的数据就保留在你的设备上。订阅（Claude Pro/Max 或 OpenAI Codex）是认证这些 Provider 的可选方式。

文档：Anthropic、OpenAI、Local models、Models。

能否在没有 API 密钥的情况下使用 Claude Max 订阅？

可以。你可以使用 setup-token 而不是 API 密钥进行认证。这是订阅路径。

Claude Pro/Max 订阅不包括 API 密钥，所以这是订阅账户的正确方法。重要提示：你必须向 Anthropic 确认此使用是否在其订阅政策和条款下被允许。如果你想要最明确、受支持的路径，请使用 Anthropic API 密钥。

Anthropic “setup-token” 认证如何工作？

claude setup-token 通过 Claude Code CLI 生成一个 Token 字符串（在 Web 控制台中不可用）。你可以在任何机器上运行它。在向导中选择 Anthropic token (paste setup-token) 或使用 openclaw models auth paste-token --provider anthropic 粘贴它。Token 作为 anthropic Provider 的认证配置文件存储，并像 API 密钥一样使用（无自动刷新）。更多详情：OAuth。

在哪里找到 Anthropic setup-token？

它不在 Anthropic Console 中。setup-token 由 Claude Code CLI 在任何机器上生成：

claude setup-token

复制它打印的 Token，然后在向导中选择 Anthropic token (paste setup-token)。如果你想在 Gateway 主机上运行它，使用 openclaw models auth setup-token --provider anthropic。如果你在其他地方运行了 claude setup-token，在 Gateway 主机上使用 openclaw models auth paste-token --provider anthropic 粘贴它。参见 Anthropic。

支持 Claude 订阅认证（Claude Pro/Max）吗？

支持 — 通过 setup-token。OpenClaw 不再重用 Claude Code CLI OAuth Token；使用 setup-token 或 Anthropic API 密钥。在任何地方生成 Token 并在 Gateway 主机上粘贴它。参见 Anthropic 和 OAuth。

注意：Claude 订阅访问受 Anthropic 条款约束。对于生产或多用户工作负载，API 密钥通常是更安全的选择。

为什么看到 HTTP 429: rate_limit_error 来自 Anthropic？

这意味着你的 Anthropic 配额/速率限制在当前窗口内已耗尽。如果你使用 Claude 订阅（setup-token 或 Claude Code OAuth），等待窗口重置或升级你的计划。如果你使用 Anthropic API 密钥，检查 Anthropic Console 的使用/计费情况并根据需要提高限制。

提示：设置一个备用模型，这样当 Provider 受速率限制时 OpenClaw 可以继续回复。参见 Models 和 OAuth。

支持 AWS Bedrock 吗？

支持 - 通过 pi-ai 的 Amazon Bedrock (Converse) Provider 进行手动配置。你必须在 Gateway 主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock Provider 条目。参见 Amazon Bedrock 和 Model providers。如果你更喜欢托管密钥流程，在 Bedrock 前面使用 OpenAI 兼容代理仍然是一个有效选项。

Codex 认证如何工作？

OpenClaw 通过 OAuth（ChatGPT 登录）支持 OpenAI Code (Codex)。向导可以运行 OAuth 流程，并在适当时将默认模型设置为 openai-codex/gpt-5.2。参见 Model providers 和 Wizard。

支持 OpenAI 订阅认证（Codex OAuth）吗？

支持。OpenClaw 完全支持 OpenAI Code (Codex) 订阅 OAuth。引导向导可以为你运行 OAuth 流程。

参见 OAuth、Model providers 和 Wizard。

如何设置 Gemini CLI OAuth？

Gemini CLI 使用 Plugin 认证流程，而不是在 openclaw.json 中使用客户端 ID 或密钥。

步骤：

  1. 启用 Plugin：openclaw plugins enable google-gemini-cli-auth
  2. 登录：openclaw models auth login --provider google-gemini-cli --set-default

这会在 Gateway 主机上的认证配置文件中存储 OAuth Token。详情：Model providers。

本地模型适合日常聊天吗？

通常不适合。OpenClaw 需要大 Context + 强安全性；小模型会截断和泄漏。如果你必须这样做，在本地运行你能运行的最大 MiniMax M2.1 构建（LM Studio），并参见 /gateway/local-models。较小/量化模型会增加 Prompt 注入风险 - 参见 Security。

如何将托管模型流量保持在特定区域？

选择区域固定端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体以将数据保留在区域内。你仍然可以通过使用 models.mode: "merge" 将 Anthropic/OpenAI 与这些一起列出，这样在尊重你选择的区域 Provider 的同时，备用选项仍然可用。

必须买 Mac Mini 才能安装吗？

不需要。OpenClaw 可以在 macOS 或 Linux（Windows 通过 WSL2）上运行。Mac mini 是可选的 - 有些人买一个作为始终在线的主机，但小型 VPS、家庭服务器或树莓派级别的设备也可以。

你只需要 Mac 用于 macOS 专用工具。对于 iMessage，你可以将 Gateway 保留在 Linux 上，并通过 SSH 在任何 Mac 上运行 imsg，方法是将 channels.imessage.cliPath 指向 SSH 包装器。如果你想要其他 macOS 专用工具，在 Mac 上运行 Gateway 或配对 macOS node。

文档：iMessage、Nodes、Mac remote mode。

需要 Mac mini 才能支持 iMessage 吗？

你需要某个 macOS 设备登录到 Messages。它不必是 Mac mini - 任何 Mac 都可以。OpenClaw 的 iMessage 集成在 macOS 上运行（BlueBubbles 或 imsg），而 Gateway 可以在其他地方运行。

常见设置：

  • 在 Linux/VPS 上运行 Gateway，并将 channels.imessage.cliPath 指向在 Mac 上运行 imsg 的 SSH 包装器。
  • 如果你想要最简单的单机设置，在 Mac 上运行所有内容。

文档：iMessage、BlueBubbles、Mac remote mode。

如果买 Mac mini 运行 OpenClaw，能连接到我的 MacBook Pro 吗？

可以。Mac mini 可以运行 Gateway，你的 MacBook Pro 可以作为 node（配套设备）连接。Nodes 不运行 Gateway - 它们提供额外的功能，如该设备上的屏幕/摄像头/画布和 system.run。

常见模式：

  • Gateway 在 Mac mini 上（始终在线）。
  • MacBook Pro 运行 macOS 应用或 node 主机并配对到 Gateway。
  • 使用 openclaw nodes status / openclaw nodes list 查看它。

文档：Nodes、Nodes CLI。

能用 Bun 吗？

不推荐使用 Bun。我们看到运行时 bug，特别是在 WhatsApp 和 Telegram 上。使用 Node 以获得稳定的 Gateway。

如果你仍然想尝试 Bun，在没有 WhatsApp/Telegram 的非生产 Gateway 上进行。

Telegram：allowFrom 里填什么？

channels.telegram.allowFrom 是人类发送者的 Telegram 用户 ID（数字，推荐）或 @username。它不是机器人用户名。

更安全（无第三方机器人）：

  • 给你的机器人发 DM，然后运行 openclaw logs --follow 并读取 from.id。

官方 Bot API：

  • 给你的机器人发 DM，然后调用 https://api.telegram.org/bot<bot_token>/getUpdates 并读取 message.from.id。

第三方（隐私较低）：

  • 给 @userinfobot 或 @getidsbot 发 DM。

参见 /channels/telegram。

多个人能用同一个 WhatsApp 号码配合不同的 OpenClaw 实例吗？

可以，通过多 Agent Routing。将每个发送者的 WhatsApp DM（peer kind: "dm"，发送者 E.164 如 +15551234567）绑定到不同的 agentId，这样每个人都有自己的 Workspace 和 Session 存储。回复仍然来自同一个 WhatsApp 账户，DM 访问控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）对每个 WhatsApp 账户是全局的。参见 Multi-Agent Routing 和 WhatsApp。

能同时运行”快速聊天” Agent 和”Opus 编码” Agent 吗？

可以。使用多 Agent Routing：给每个 Agent 自己的默认模型，然后将入站路由（Provider 账户或特定 peer）绑定到每个 Agent。示例配置在 Multi-Agent Routing。另见 Models 和 Configuration。

Homebrew 在 Linux 上能用吗？

可以。Homebrew 支持 Linux（Linuxbrew）。快速设置：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>

如果你通过 systemd 运行 OpenClaw，确保服务 PATH 包含 /home/linuxbrew/.linuxbrew/bin（或你的 brew 前缀），这样 brew 安装的工具可以在非登录 shell 中解析。

可修改的 git 安装和 npm 安装有什么区别？

  • **可修改的（git）安装：**完整的源代码检出，可编辑，最适合贡献者。你在本地运行构建，可以修补代码/文档。
  • **npm 安装：**全局 CLI 安装，没有仓库，最适合”直接运行”。更新来自 npm dist-tags。

文档：开始使用、更新。

我能在 npm 和 git 安装之间切换吗？

可以。安装另一种方式，然后运行 Doctor，这样 Gateway 服务就会指向新的入口点。这不会删除你的数据 - 它只会更改 OpenClaw 代码安装。你的状态（~/.openclaw）和 Workspace（~/.openclaw/workspace）保持不变。

从 npm → git：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

从 git → npm：

npm install -g openclaw@latest
openclaw doctor
openclaw gateway restart

Doctor 会检测到 Gateway 服务入口点不匹配，并提供重写服务配置以匹配当前安装（在自动化中使用 --repair）。

备份提示：参见 备份策略。

我应该在笔记本电脑还是 VPS 上运行 Gateway？

简短回答：如果你想要 24/7 可靠性，使用 VPS。如果你想要最低摩擦，并且可以接受睡眠/重启，就在本地运行。

笔记本电脑（本地 Gateway）

  • **优点：**无服务器成本，直接访问本地文件，实时浏览器窗口。
  • **缺点：**睡眠/网络断开 = 断线，操作系统更新/重启会中断，必须保持唤醒。

VPS / 云

  • **优点：**始终在线，稳定网络，没有笔记本电脑睡眠问题，更容易保持运行。
  • **缺点：**通常无头运行（使用截图），仅远程文件访问，你必须 SSH 进行更新。

OpenClaw 特定说明：WhatsApp/Telegram/Slack/Mattermost（plugin）/Discord 都可以在 VPS 上正常工作。唯一真正的权衡是无头浏览器与可见窗口。参见 Browser。

**推荐默认：**如果你之前遇到过 Gateway 断线，使用 VPS。当你积极使用 Mac 并想要本地文件访问或带可见浏览器的 UI 自动化时，本地很好。

在专用机器上运行 OpenClaw 有多重要？

不是必需的，但推荐用于可靠性和隔离。

  • **专用主机（VPS/Mac mini/Pi）：**始终在线，更少的睡眠/重启中断，更清晰的权限，更容易保持运行。
  • **共享笔记本电脑/台式机：**完全适合测试和主动使用，但当机器睡眠或更新时会暂停。

如果你想要两全其美，将 Gateway 保持在专用主机上，并将你的笔记本电脑配对为节点以获得本地屏幕/摄像头/exec 工具。参见 Nodes。 有关安全指导，请阅读 Security。

VPS 的最低要求和推荐操作系统是什么？

OpenClaw 很轻量。对于基本的 Gateway + 一个聊天 Channel：

  • **绝对最低：**1 vCPU，1GB RAM，约 500MB 磁盘。
  • **推荐：**1-2 vCPU，2GB RAM 或更多以留有余地（日志、媒体、多个 Channel）。Node 工具和浏览器自动化可能会占用资源。

操作系统：使用 Ubuntu LTS（或任何现代 Debian/Ubuntu）。Linux 安装路径在那里测试得最好。

文档：Linux、VPS 托管。

我能在 VM 中运行 OpenClaw 吗？要求是什么？

可以。将 VM 视为 VPS：它需要始终在线、可访问，并有足够的 RAM 用于 Gateway 和你启用的任何 Channel。

基本指导：

  • **绝对最低：**1 vCPU，1GB RAM。
  • **推荐：**如果你运行多个 Channel、浏览器自动化或媒体工具，2GB RAM 或更多。
  • **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。

如果你在 Windows 上，WSL2 是最简单的 VM 风格设置，并且具有最好的工具兼容性。参见 Windows、VPS 托管。 如果你在 VM 中运行 macOS，参见 macOS VM。

OpenClaw 是什么？

用一段话说明 OpenClaw 是什么？

OpenClaw 是你在自己设备上运行的个人 AI 助手。它在你已经使用的消息平台上回复（WhatsApp、Telegram、Slack、Mattermost（plugin）、Discord、Google Chat、Signal、iMessage、WebChat），还可以在支持的平台上进行语音 + 实时 Canvas。Gateway 是始终在线的控制平面；助手是产品。

价值主张是什么？

OpenClaw 不是”只是一个 Claude 包装器”。它是一个本地优先的控制平面，让你在自己的硬件上运行一个强大的助手，可以从你已经使用的聊天应用访问，具有有状态的 Session、Memory 和工具 - 无需将工作流程的控制权交给托管的 SaaS。

亮点：

  • **你的设备，你的数据：**在任何你想要的地方运行 Gateway（Mac、Linux、VPS），并将 Workspace + Session 历史保持在本地。
  • **真实的 Channel，而不是 Web 沙盒：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等，以及支持平台上的移动语音和 Canvas。
  • **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，具有每个 Agent 的路由和 Failover。
  • 仅本地选项：运行本地模型，这样所有数据都可以保留在你的设备上（如果你想要）。
  • **多 Agent Routing：**每个 Channel、账户或任务的独立 Agent，每个都有自己的 Workspace 和默认设置。
  • **开源且可修改：**检查、扩展和自托管，无供应商锁定。

文档：Gateway、Channels、Multi-Agent、Memory。

我刚设置好，应该先做什么？

好的第一个项目：

  • 构建一个网站（WordPress、Shopify 或简单的静态站点）。
  • 原型化一个移动应用（大纲、屏幕、API 计划）。
  • 组织文件和文件夹（清理、命名、标记）。
  • 连接 Gmail 并自动化摘要或跟进。

它可以处理大型任务，但当你将它们分成阶段并使用 Sub Agent 进行并行工作时效果最好。

OpenClaw 的五大日常用例是什么？

日常胜利通常看起来像：

  • **个人简报：**收件箱、日历和你关心的新闻的摘要。
  • **研究和起草：**快速研究、摘要和电子邮件或文档的初稿。
  • **提醒和跟进：**Cron 或 Heartbeat 驱动的提醒和清单。
  • **浏览器自动化：**填写表单、收集数据和重复的 Web 任务。
  • **跨设备协调：**从手机发送任务，让 Gateway 在服务器上运行，并在聊天中获取结果。

OpenClaw 能帮助 SaaS 的潜在客户生成、外展、广告和博客吗？

可以用于研究、资格审查和起草。它可以扫描网站、构建候选名单、总结潜在客户并撰写外展或广告文案草稿。

对于外展或广告投放，保持人工参与。避免垃圾邮件，遵守当地法律和平台政策，并在发送之前审查任何内容。最安全的模式是让 OpenClaw 起草，你批准。

文档：Security。

与 Claude Code 相比，Web 开发的优势是什么？

OpenClaw 是一个个人助手和协调层，而不是 IDE 替代品。在仓库内使用 Claude Code 或 Codex 以获得最快的直接编码循环。当你想要持久的 Memory、跨设备访问和工具编排时，使用 OpenClaw。

优势：

  • 跨 Session 的持久 Memory + Workspace
  • 多平台访问（WhatsApp、Telegram、TUI、WebChat）
  • 工具编排（浏览器、文件、调度、Hooks）
  • 始终在线的 Gateway（在 VPS 上运行，从任何地方交互）
  • Nodes 用于本地浏览器/屏幕/摄像头/exec

展示：https://openclaw.ai/showcase

Skills 和自动化

如何在不保持仓库脏的情况下自定义 Skills？

使用托管覆盖而不是编辑仓库副本。将你的更改放在 ~/.openclaw/skills/<name>/SKILL.md 中（或通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 添加文件夹）。优先级是 <workspace>/skills > ~/.openclaw/skills > 捆绑的，所以托管覆盖获胜而不触及 git。只有值得上游的编辑应该存在于仓库中并作为 PR 提交。

我能从自定义文件夹加载 Skills 吗？

可以。通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 添加额外的目录（最低优先级）。默认优先级保持：<workspace>/skills → ~/.openclaw/skills → 捆绑的 → skills.load.extraDirs。clawhub 默认安装到 ./skills，OpenClaw 将其视为 <workspace>/skills。

如何为不同的任务使用不同的模型？

目前支持的模式是：

  • Cron 作业：隔离的作业可以为每个作业设置 model 覆盖。
  • Sub-agents：将任务路由到具有不同默认模型的独立 Agent。
  • 按需切换：使用 /model 随时切换当前 Session 模型。

参见 Cron 作业、Multi-Agent Routing 和 Slash 命令。

机器人在做繁重工作时冻结，如何卸载？

使用 Sub-agents 处理长时间或并行任务。Sub-agents 在自己的 Session 中运行，返回摘要，并保持你的主聊天响应。

要求你的机器人”为此任务生成一个 Sub-agent”或使用 /subagents。 在聊天中使用 /status 查看 Gateway 现在正在做什么（以及它是否忙碌）。

Token 提示：长任务和 Sub-agents 都会消耗 Token。如果成本是一个问题，通过 agents.defaults.subagents.model 为 Sub-agents 设置更便宜的模型。

文档：Sub-agents。

Cron 或提醒不触发，我应该检查什么？

Cron 在 Gateway 进程内运行。如果 Gateway 没有持续运行，计划的作业将不会运行。

检查清单：

  • 确认 Cron 已启用（cron.enabled）并且 OPENCLAW_SKIP_CRON 未设置。
  • 检查 Gateway 是否 24/7 运行（无睡眠/重启）。
  • 验证作业的时区设置（--tz 与主机时区）。

调试：

openclaw cron run <jobId> --force
openclaw cron runs --id <jobId> --limit 50

文档：Cron 作业、Cron vs Heartbeat。

如何在 Linux 上安装 Skills？

使用 ClawHub（CLI）或将 Skills 放入你的 Workspace。macOS Skills UI 在 Linux 上不可用。 在 https://clawhub.com 浏览 Skills。

安装 ClawHub CLI（选择一个包管理器）：

npm i -g clawhub
pnpm add -g clawhub

OpenClaw 能按计划或在后台持续运行任务吗？

可以。使用 Gateway 调度器：

  • Cron 作业用于计划或重复任务（跨重启持久化）。
  • Heartbeat 用于”主 Session”定期检查。
  • 隔离作业用于发布摘要或传递到聊天的自主 Agent。

文档：Cron 作业、Cron vs Heartbeat、Heartbeat。

我能从 Linux 运行 Apple macOS 专用 Skills 吗？

不能直接运行。macOS Skills 由 metadata.openclaw.os 加上所需的二进制文件控制，Skills 仅在 Gateway 主机上符合条件时才会出现在系统 Prompt 中。在 Linux 上，darwin 专用 Skills（如 imsg、apple-notes、apple-reminders）不会加载，除非你覆盖控制。

你有三种支持的模式：

选项 A - 在 Mac 上运行 Gateway（最简单）。 在 macOS 二进制文件存在的地方运行 Gateway，然后从 Linux 以远程模式或通过 Tailscale 连接。Skills 正常加载，因为 Gateway 主机是 macOS。

选项 B - 使用 macOS 节点（无 SSH）。 在 Linux 上运行 Gateway，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 Node Run Commands 设置为”Always Ask”或”Always Allow”。当所需的二进制文件存在于节点上时，OpenClaw 可以将 macOS 专用 Skills 视为符合条件。Agent 通过 nodes 工具运行这些 Skills。如果你选择”Always Ask”，在 Prompt 中批准”Always Allow”会将该命令添加到 Allowlist。

选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。 将 Gateway 保持在 Linux 上，但使所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skill 以允许 Linux，使其保持符合条件。

  1. 为二进制文件创建 SSH 包装器（示例：imsg）： 
    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"
  2. 将包装器放在 Linux 主机的 PATH 上（例如 ~/bin/imsg）。
  3. 覆盖 Skill 元数据（Workspace 或 ~/.openclaw/skills）以允许 Linux： 
    ---
name: imsg
description: iMessage/SMS CLI for listing chats, history, watch, and sending.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["imsg"] } } }
---
  4. 启动新 Session，以便 Skills 快照刷新。

对于 iMessage，你还可以将 channels.imessage.cliPath 指向 SSH 包装器（OpenClaw 只需要 stdio）。参见 iMessage。

你们有 Notion 或 HeyGen 集成吗？

目前没有内置的。

选项：

  • **自定义 Skill / Plugin：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。
  • **浏览器自动化：**无需代码即可工作，但速度较慢且更脆弱。

如果你想为每个客户保留上下文（代理工作流程），一个简单的模式是：

  • 每个客户一个 Notion 页面（上下文 + 偏好 + 活动工作）。
  • 要求 Agent 在 Session 开始时获取该页面。

如果你想要原生集成，请提交功能请求或构建针对这些 API 的 Skill。

安装 Skills：

clawhub install <skill-slug>
clawhub update --all

ClawHub 安装到当前目录下的 ./skills（或回退到你配置的 OpenClaw Workspace）；OpenClaw 在下一个 Session 中将其视为 <workspace>/skills。对于跨 Agent 的共享 Skills，将它们放在 ~/.openclaw/skills/<name>/SKILL.md 中。一些 Skills 期望通过 Homebrew 安装二进制文件；在 Linux 上这意味着 Linuxbrew（参见上面的 Homebrew Linux FAQ 条目）。参见 Skills 和 ClawHub。

如何安装 Chrome 扩展以进行浏览器接管？

使用内置安装程序，然后在 Chrome 中加载解压的扩展：

openclaw browser extension install
openclaw browser extension path

然后 Chrome → chrome://extensions → 启用”开发者模式” → “加载已解压的扩展程序” → 选择该文件夹。

完整指南（包括远程 Gateway + 安全说明）：Chrome 扩展

如果 Gateway 与 Chrome 在同一台机器上运行（默认设置），你通常不需要任何额外的东西。 如果 Gateway 在其他地方运行，在浏览器机器上运行节点主机，以便 Gateway 可以代理浏览器操作。 你仍然需要在要控制的标签页上单击扩展按钮（它不会自动附加）。

Sandboxing 和 Memory

有专门的 Sandboxing 文档吗？

有。参见 Sandboxing。对于 Docker 特定设置（Docker 中的完整 Gateway 或 Sandbox 镜像），参见 Docker。

我能保持 DM 私密但使用一个 Agent 使群组公开沙盒化吗？

可以 - 如果你的私人流量是 DM，公共流量是群组。

使用 agents.defaults.sandbox.mode: "non-main"，这样群组/Channel Session（非主键）在 Docker 中运行，而主 DM Session 保持在主机上。然后通过 tools.sandbox.tools 限制沙盒 Session 中可用的工具。

设置演练 + 示例配置：Groups: personal DMs + public groups

关键配置参考：Gateway 配置

如何将主机文件夹绑定到 Sandbox？

将 agents.defaults.sandbox.docker.binds 设置为 ["host:path:mode"]（例如，"/home/user/src:/src:ro"）。全局 + 每个 Agent 的绑定合并；当 scope: "shared" 时，每个 Agent 的绑定被忽略。对任何敏感内容使用 :ro，并记住绑定会绕过 Sandbox 文件系统墙。参见 Sandboxing 和 Sandbox vs Tool Policy vs Elevated 以获取示例和安全说明。

Memory 如何工作？

OpenClaw Memory 只是 Agent Workspace 中的 Markdown 文件：

  • memory/YYYY-MM-DD.md 中的每日笔记
  • MEMORY.md 中的精选长期笔记（仅主/私人 Session）

OpenClaw 还运行静默的预 Compaction Memory 刷新，以提醒模型在自动 Compaction 之前写入持久笔记。这仅在 Workspace 可写时运行（只读 Sandbox 跳过它）。参见 Memory。

Memory 总是忘记东西，如何让它坚持？

要求机器人将事实写入 Memory。长期笔记属于 MEMORY.md，短期上下文进入 memory/YYYY-MM-DD.md。

这仍然是我们正在改进的领域。提醒模型存储 Memory 会有所帮助；它会知道该怎么做。如果它一直忘记，请验证 Gateway 在每次运行时使用相同的 Workspace。

文档：Memory、Agent Workspace。

语义 Memory 搜索需要 OpenAI API 密钥吗？

仅当你使用 OpenAI Embeddings 时。Codex OAuth 涵盖 chat/completions，不授予 Embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 Codex CLI 登录）**对语义 Memory 搜索没有帮助。OpenAI Embeddings 仍然需要真正的 API 密钥（OPENAI_API_KEY 或 models.providers.openai.apiKey）。

如果你没有明确设置 Provider，OpenClaw 会在可以解析 API 密钥时自动选择 Provider（auth profiles、models.providers.*.apiKey 或环境变量）。如果 OpenAI 密钥解析，它更喜欢 OpenAI，否则如果 Gemini 密钥解析，则更喜欢 Gemini。如果两个密钥都不可用，Memory 搜索将保持禁用状态，直到你配置它。如果你配置并存在本地模型路径，OpenClaw 更喜欢 local。

如果你更愿意保持本地，设置 memorySearch.provider = "local"（并可选地设置 memorySearch.fallback = "none"）。如果你想要 Gemini Embeddings，设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini 或本地 Embedding 模型 - 参见 Memory 以获取设置详细信息。

Memory 会永久保留吗？有什么限制？

Memory 文件存储在磁盘上，并持久保留直到你删除它们。限制是你的存储，而不是模型。Session Context 仍然受模型 Context 窗口的限制，因此长对话可以 Compact 或截断。这就是为什么 Memory 搜索存在 - 它只将相关部分拉回 Context。

文档：Memory、Context。

磁盘上的东西在哪里

与 OpenClaw 一起使用的所有数据都保存在本地吗？

不 - OpenClaw 的状态是本地的，但外部服务仍然会看到你发送给它们的内容。

  • **默认本地：**Session、Memory 文件、配置和 Workspace 存储在 Gateway 主机上（~/.openclaw + 你的 Workspace 目录）。
  • **必要的远程：**你发送给模型 Provider（Anthropic/OpenAI 等）的消息会发送到它们的 API，聊天平台（WhatsApp/Telegram/Slack 等）将消息数据存储在它们的服务器上。
  • **你控制足迹：**使用本地模型将 Prompt 保留在你的机器上，但 Channel 流量仍然通过 Channel 的服务器。

相关：Agent Workspace、Memory。

OpenClaw 将其数据存储在哪里？

所有内容都存储在 $OPENCLAW_STATE_DIR 下（默认：~/.openclaw）：

路径目的
$OPENCLAW_STATE_DIR/openclaw.json主配置（JSON5）
$OPENCLAW_STATE_DIR/credentials/oauth.json旧版 OAuth 导入（首次使用时复制到 auth profiles）
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.jsonAuth profiles（OAuth + API 密钥）
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.jsonRuntime auth 缓存（自动管理）
$OPENCLAW_STATE_DIR/credentials/Provider 状态（例如 whatsapp/<accountId>/creds.json）
$OPENCLAW_STATE_DIR/agents/每个 Agent 的状态（agentDir + sessions）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/对话历史和状态（每个 Agent）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.jsonSession 元数据（每个 Agent）

旧版单 Agent 路径：~/.openclaw/agent/*（由 openclaw doctor 迁移）。

你的 Workspace（AGENTS.md、Memory 文件、Skills 等）是独立的，通过 agents.defaults.workspace 配置（默认：~/.openclaw/workspace）。

AGENTS.md、SOUL.md、USER.md、MEMORY.md 应该放在哪里？

这些文件存储在 Agent Workspace 中，而不是 ~/.openclaw。

  • Workspace（每个 Agent）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md（或 memory.md）、memory/YYYY-MM-DD.md、可选的 HEARTBEAT.md。
  • 状态目录（~/.openclaw）：配置、凭据、auth profiles、Session、日志和共享 Skills（~/.openclaw/skills）。

默认 Workspace 是 ~/.openclaw/workspace，可通过以下方式配置：

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

如果机器人在重启后”忘记”，请确认 Gateway 在每次启动时使用相同的 Workspace（并记住：远程模式使用 Gateway 主机的 Workspace，而不是你的本地笔记本电脑）。

提示：如果你想要持久的行为或偏好，要求机器人将其写入 AGENTS.md 或 MEMORY.md，而不是依赖聊天历史。

参见 Agent Workspace 和 Memory。

推荐的备份策略是什么？

将你的 Agent Workspace 放在私有 git 仓库中，并将其备份到私有的地方（例如 GitHub 私有仓库）。这会捕获 Memory + AGENTS/SOUL/USER 文件，并让你以后恢复助手的”思维”。

不要提交 ~/.openclaw 下的任何内容（凭据、Session、Token）。 如果你需要完全恢复，请分别备份 Workspace 和状态目录（参见上面的迁移问题）。

文档：Agent Workspace。

如何完全卸载 OpenClaw？

参见专门的指南：卸载。

Agent 能在 Workspace 外工作吗？

可以。Workspace 是默认 cwd 和 Memory 锚点，而不是硬 Sandbox。相对路径在 Workspace 内解析，但绝对路径可以访问其他主机位置，除非启用了 Sandboxing。如果你需要隔离，使用 agents.defaults.sandbox 或每个 Agent 的 Sandbox 设置。如果你想让仓库成为默认工作目录，将该 Agent 的 workspace 指向仓库根目录。OpenClaw 仓库只是源代码；保持 Workspace 独立，除非你有意让 Agent 在其中工作。

示例（仓库作为默认 cwd）：

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}

我在远程模式下，Session 存储在哪里？

Session 状态由 Gateway 主机拥有。如果你处于远程模式，你关心的 Session 存储在远程机器上，而不是你的本地笔记本电脑上。参见 Session 管理。

配置基础

配置是什么格式？在哪里？

OpenClaw 从 $OPENCLAW_CONFIG_PATH 读取可选的 JSON5 配置（默认：~/.openclaw/openclaw.json）：

$OPENCLAW_CONFIG_PATH

如果文件缺失，它使用相对安全的默认值（包括默认 Workspace ~/.openclaw/workspace）。

我设置了 gateway.bind lan 或 tailnet，现在什么都不监听，UI 说未授权？

非回环绑定需要认证。配置 gateway.auth.mode + gateway.auth.token（或使用 OPENCLAW_GATEWAY_TOKEN）。

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

注意：

  • gateway.remote.token 仅用于远程 CLI 调用；它不启用本地 Gateway 认证。
  • Control UI 通过 connect.params.auth.token 进行认证（存储在应用/UI 设置中）。避免在 URL 中放置 Token。

为什么我现在在 localhost 上需要 Token？

向导默认生成 Gateway Token（即使在回环上），因此本地 WS 客户端必须进行认证。这会阻止其他本地进程调用 Gateway。将 Token 粘贴到 Control UI 设置（或你的客户端配置）中以连接。

如果你真的想要开放回环，从配置中删除 gateway.auth。Doctor 可以随时为你生成 Token：openclaw doctor --generate-gateway-token。

更改配置后必须重启吗？

Gateway 监视配置并支持热重载：

  • gateway.reload.mode: "hybrid"（默认）：热应用安全更改，对关键更改重启
  • 也支持 hot、restart、off

如何启用 Web 搜索和 Web 获取？

web_fetch 无需 API 密钥即可工作。web_search 需要 Brave Search API 密钥。**推荐：**运行 openclaw configure --section web 将其存储在 tools.web.search.apiKey 中。环境替代方案：为 Gateway 进程设置 BRAVE_API_KEY。

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE",
        maxResults: 5,
      },
      fetch: {
        enabled: true,
      },
    },
  },
}

注意：

  • 如果你使用 Allowlist，添加 web_search/web_fetch 或 group:web。
  • web_fetch 默认启用（除非明确禁用）。
  • Daemon 从 ~/.openclaw/.env（或服务环境）读取环境变量。

文档：Web 工具。

如何运行一个中央 Gateway 并在设备间使用专门的工作者？

常见模式是一个 Gateway（例如 Raspberry Pi）加上 Nodes 和 Agents：

  • **Gateway（中央）：**拥有 Channel（Signal/WhatsApp）、Routing 和 Session。
  • **Nodes（设备）：**Mac/iOS/Android 作为外围设备连接并公开本地工具（system.run、canvas、camera）。
  • **Agents（工作者）：**用于特殊角色的独立大脑/Workspace（例如”Hetzner ops”、“Personal data”）。
  • **Sub-agents：**当你想要并行性时，从主 Agent 生成后台工作。
  • **TUI：**连接到 Gateway 并切换 Agent/Session。

文档：Nodes、远程访问、Multi-Agent Routing、Sub-agents、TUI。

OpenClaw 浏览器能无头运行吗？

可以。这是一个配置选项：

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}

默认是 false（有头）。无头模式在某些网站上更容易触发反机器人检查。参见 Browser。

无头使用相同的 Chromium 引擎，适用于大多数自动化（表单、点击、抓取、登录）。主要区别：

  • 没有可见的浏览器窗口（如果需要视觉效果，使用截图）。
  • 某些网站在无头模式下对自动化更严格（CAPTCHA、反机器人）。例如，X/Twitter 经常阻止无头 Session。

如何使用 Brave 进行浏览器控制？

将 browser.executablePath 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器）并重启 Gateway。 参见 Browser 中的完整配置示例。

远程 Gateway + Nodes

命令如何在 Telegram、Gateway 和 Nodes 之间传播？

Telegram 消息由 Gateway 处理。Gateway 运行 Agent，只有在需要节点工具时才通过 Gateway WebSocket 调用 Nodes：

Telegram → Gateway → Agent → node.* → Node → Gateway → Telegram

Nodes 看不到入站 Provider 流量；它们只接收节点 RPC 调用。

如果 Gateway 托管在远程，我的 Agent 如何访问我的计算机？

简短回答：将你的计算机配对为节点。Gateway 在其他地方运行，但它可以通过 Gateway WebSocket 在你的本地机器上调用 node.* 工具（屏幕、摄像头、系统）。

典型设置：

  1. 在始终在线的主机（VPS/家庭服务器）上运行 Gateway。
  2. 将 Gateway 主机 + 你的计算机放在同一个 tailnet 上。
  3. 确保 Gateway WS 可访问（tailnet 绑定或 SSH 隧道）。
  4. 在本地打开 macOS 应用并以 Remote over SSH 模式连接（或直接 tailnet），以便它可以注册为节点。
  5. 在 Gateway 上批准节点： 
    openclaw nodes pending
openclaw nodes approve <requestId>

不需要单独的 TCP 桥接；节点通过 Gateway WebSocket 连接。

安全提醒：配对 macOS 节点允许在该机器上使用 system.run。只配对你信任的设备，并查看 Security。

文档：Nodes、Gateway 协议、macOS 远程模式、Security。

Tailscale 已连接但我没有收到回复，现在怎么办？

检查基础：

  • Gateway 正在运行：openclaw gateway status
  • Gateway 健康：openclaw status
  • Channel 健康：openclaw channels status

然后验证认证和路由：

  • 如果你使用 Tailscale Serve，确保 gateway.auth.allowTailscale 设置正确。
  • 如果你通过 SSH 隧道连接，确认本地隧道已启动并指向正确的端口。
  • 确认你的 Allowlist（DM 或群组）包含你的账户。

文档：Tailscale、远程访问、Channels。

两个 OpenClaw 实例能相互通信吗（本地/VPS）？

可以。没有内置的”机器人对机器人”桥接，但你可以通过几种可靠的方式连接它：

**最简单：**使用两个机器人都可以访问的普通聊天 Channel（Telegram/Slack/WhatsApp）。让 Bot A 向 Bot B 发送消息，然后让 Bot B 像往常一样回复。

**CLI 桥接（通用）：**运行一个脚本，使用 openclaw agent --message ... --deliver 调用另一个 Gateway，目标是另一个机器人监听的聊天。如果一个机器人在远程 VPS 上，通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway（参见远程访问）。

示例模式（从可以访问目标 Gateway 的机器运行）：

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

提示：添加护栏，以便两个机器人不会无限循环（仅提及、Channel Allowlist 或”不回复机器人消息”规则）。

文档：远程访问、Agent CLI、Agent send。

我需要为多个 Agent 使用单独的 VPS 吗？

不需要。一个 Gateway 可以托管多个 Agent，每个都有自己的 Workspace、模型默认值和路由。这是正常设置，比每个 Agent 运行一个 VPS 便宜得多且简单得多。

仅当你需要硬隔离（安全边界）或非常不同的配置且不想共享时，才使用单独的 VPS。否则，保持一个 Gateway 并使用多个 Agent 或 Sub-agents。

在我的个人笔记本电脑上使用节点而不是从 VPS SSH 有什么好处？

有 - 节点是从远程 Gateway 访问笔记本电脑的一流方式，它们解锁的不仅仅是 shell 访问。Gateway 在 macOS/Linux（Windows 通过 WSL2）上运行，并且是轻量级的（小型 VPS 或 Raspberry Pi 级别的盒子就可以；4 GB RAM 就足够了），因此常见的设置是始终在线的主机加上你的笔记本电脑作为节点。

  • **不需要入站 SSH。**节点连接到 Gateway WebSocket 并使用设备配对。
  • 更安全的执行控制。system.run 由该笔记本电脑上的节点 Allowlist/批准控制。
  • **更多设备工具。**除了 system.run，节点还公开 canvas、camera 和 screen。
  • **本地浏览器自动化。**将 Gateway 保持在 VPS 上，但在本地运行 Chrome，并使用 Chrome 扩展 + 笔记本电脑上的节点主机中继控制。

SSH 适用于临时 shell 访问，但节点对于持续的 Agent 工作流程和设备自动化更简单。

文档：Nodes、Nodes CLI、Chrome 扩展。

我应该在第二台笔记本电脑上安装还是只添加一个节点？

如果你只需要第二台笔记本电脑上的本地工具（屏幕/摄像头/exec），将其添加为节点。这样可以保持单个 Gateway 并避免重复配置。本地节点工具目前仅限 macOS，但我们计划将其扩展到其他操作系统。

仅当你需要硬隔离或两个完全独立的机器人时，才安装第二个 Gateway。

文档：Nodes、Nodes CLI、多个 Gateway。

节点运行 Gateway 服务吗？

不。每个主机只应运行一个 Gateway，除非你有意运行隔离的配置文件（参见多个 Gateway）。节点是连接到 Gateway 的外围设备（iOS/Android 节点，或 macOS 菜单栏应用中的”节点模式”）。对于无头节点主机和 CLI 控制，参见 Node 主机 CLI。

gateway、discovery 和 canvasHost 更改需要完全重启。

有 API/RPC 方式应用配置吗？

有。config.apply 验证 + 写入完整配置，并作为操作的一部分重启 Gateway。

config.apply 清空了我的配置，如何恢复并避免这种情况？

config.apply 替换整个配置。如果你发送部分对象，其他所有内容都会被删除。

恢复：

  • 从备份恢复（git 或复制的 ~/.openclaw/openclaw.json）。
  • 如果你没有备份，重新运行 openclaw doctor 并重新配置 Channel/模型。
  • 如果这是意外的，提交 bug 并包含你最后已知的配置或任何备份。
  • 本地编码 Agent 通常可以从日志或历史记录重建工作配置。

避免它：

  • 对小更改使用 openclaw config set。
  • 对交互式编辑使用 openclaw configure。

文档：Config、Configure、Doctor。

首次安装的最小合理配置是什么？

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

这会设置你的 Workspace 并限制谁可以触发机器人。

如何在 VPS 上设置 Tailscale 并从 Mac 连接？

最小步骤：

  1. 在 VPS 上安装 + 登录 
    curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
  2. 在 Mac 上安装 + 登录
    • 使用 Tailscale 应用并登录到同一个 tailnet。
  3. 启用 MagicDNS（推荐）
    • 在 Tailscale 管理控制台中，启用 MagicDNS，以便 VPS 有一个稳定的名称。
  4. 使用 tailnet 主机名

如果你想要没有 SSH 的 Control UI，在 VPS 上使用 Tailscale Serve：

openclaw gateway --tailscale serve

这会将 Gateway 绑定到回环并通过 Tailscale 公开 HTTPS。参见 Tailscale。

如何将 Mac 节点连接到远程 Gateway（Tailscale Serve）？

Serve 公开 Gateway Control UI + WS。节点通过相同的 Gateway WS 端点连接。

推荐设置：

  1. 确保 VPS + Mac 在同一个 tailnet 上。
  2. 在远程模式下使用 macOS 应用（SSH 目标可以是 tailnet 主机名）。应用将隧道 Gateway 端口并作为节点连接。
  3. 在 Gateway 上批准节点： 
    openclaw nodes pending
openclaw nodes approve <requestId>

文档：Gateway 协议、Discovery、macOS 远程模式。

环境变量和 .env 加载

OpenClaw 如何加载环境变量？

OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载：

  • 当前工作目录中的 .env
  • ~/.openclaw/.env 的全局回退 .env（即 $OPENCLAW_STATE_DIR/.env）

两个 .env 文件都不会覆盖现有的环境变量。

你还可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

参见 /environment 以获取完整的优先级和来源。

我通过服务启动了 Gateway，我的环境变量消失了，现在怎么办？

两个常见的修复方法：

  1. 将缺失的密钥放在 ~/.openclaw/.env 中，这样即使服务不继承你的 shell 环境，它们也会被拾取。
  2. 启用 shell 导入（选择加入的便利）：
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

这会运行你的登录 shell 并仅导入缺失的预期密钥（从不覆盖）。环境变量等效项：OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

我设置了 COPILOT_GITHUB_TOKEN，但 models status 显示 Shell env off，为什么？

openclaw models status 报告 shell env 导入是否启用。“Shell env: off”不意味着你的环境变量缺失 - 它只是意味着 OpenClaw 不会自动加载你的登录 shell。

如果 Gateway 作为服务运行（launchd/systemd），它不会继承你的 shell 环境。通过执行以下操作之一来修复：

  1. 将 Token 放在 ~/.openclaw/.env 中： 
    COPILOT_GITHUB_TOKEN=...
  2. 或启用 shell 导入（env.shellEnv.enabled: true）。
  3. 或将其添加到你的配置 env 块（仅在缺失时应用）。

然后重启 Gateway 并重新检查：

openclaw models status

Copilot Token 从 COPILOT_GITHUB_TOKEN 读取（也可以是 GH_TOKEN / GITHUB_TOKEN）。 参见 /concepts/model-providers 和 /environment。

Session 和多个聊天

如何开始新的对话？

发送 /new 或 /reset 作为独立消息。参见 Session 管理。

如果我从不发送 new，Session 会自动重置吗？

会。Session 在 session.idleMinutes（默认 60）后过期。下一条消息为该聊天键启动一个新的 Session ID。这不会删除记录 - 它只是启动一个新 Session。

{
  session: {
    idleMinutes: 240,
  },
}

有办法创建一个 OpenClaw 实例团队吗（一个 CEO 和多个 Agent）？

可以，通过 Multi-Agent Routing 和 Sub-agents。你可以创建一个协调器 Agent 和几个具有自己 Workspace 和模型的工作 Agent。

也就是说，这最好被视为有趣的实验。它消耗大量 Token，通常不如使用一个具有独立 Session 的机器人高效。我们设想的典型模型是你与之交谈的一个机器人，具有不同的 Session 用于并行工作。该机器人还可以在需要时生成 Sub-agents。

文档：Multi-Agent Routing、Sub-agents、Agents CLI。

为什么 Context 在任务中途被截断？如何防止？

Session Context 受模型窗口限制。长聊天、大型工具输出或许多文件可能触发 Compaction 或截断。

有帮助的方法：

  • 要求机器人总结当前状态并将其写入文件。
  • 在长任务之前使用 /compact，在切换主题时使用 /new。
  • 将重要 Context 保留在 Workspace 中，并要求机器人读回它。
  • 对长时间或并行工作使用 Sub-agents，以便主聊天保持较小。
  • 如果经常发生这种情况，选择具有更大 Context 窗口的模型。

如何完全重置 OpenClaw 但保持安装？

使用重置命令：

openclaw reset

非交互式完全重置：

openclaw reset --scope full --yes --non-interactive

然后重新运行入门：

openclaw onboard --install-daemon

注意：

  • 如果入门向导看到现有配置，它也会提供 Reset。参见 Wizard。
  • 如果你使用了配置文件（--profile / OPENCLAW_PROFILE），重置每个状态目录（默认为 ~/.openclaw-<profile>）。
  • Dev 重置：openclaw gateway --dev --reset（仅 dev；清除 dev 配置 + 凭据 + Session + Workspace）。

我收到”context too large”错误，如何重置或压缩？

使用以下之一：

  • Compact（保留对话但总结旧的轮次）：

    /compact

    或 /compact <instructions> 来指导摘要。

  • Reset（相同聊天键的新 Session ID）：

    /new
/reset

如果它一直发生：

  • 启用或调整 Session Pruning（agents.defaults.contextPruning）以修剪旧的工具输出。
  • 使用具有更大 Context 窗口的模型。

文档：Compaction、Session Pruning、Session 管理。

为什么我看到”LLM request rejected messages[N].content[X].tool_use.input: Field required”？

这是 Provider 验证错误：模型发出了没有所需 input 的 tool_use 块。这通常意味着 Session 历史过时或损坏（通常在长线程或工具/架构更改后）。

修复：使用 /new（独立消息）启动新 Session。

为什么我每 30 分钟收到一次 Heartbeat 消息？

Heartbeat 默认每 30 分钟运行一次。调整或禁用它们：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // 或 "0m" 禁用
      },
    },
  },
}

如果 HEARTBEAT.md 存在但实际上是空的（只有空行和 Markdown 标题如 # Heading），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。如果文件缺失，Heartbeat 仍然运行，模型决定做什么。

每个 Agent 的覆盖使用 agents.list[].heartbeat。文档：Heartbeat。

我需要将机器人账户添加到 WhatsApp 群组吗？

不需要。OpenClaw 在你自己的账户上运行，所以如果你在群组中，OpenClaw 可以看到它。默认情况下，群组回复被阻止，直到你允许发送者（groupPolicy: "allowlist"）。

如果你只想你能够触发群组回复：

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

如何获取 WhatsApp 群组的 JID？

选项 1（最快）：跟踪日志并在群组中发送测试消息：

openclaw logs --follow --json

查找以 @g.us 结尾的 chatId（或 from），如：[email protected]。

选项 2（如果已配置/已列入 Allowlist）：从配置列出群组：

openclaw directory groups list --channel whatsapp

文档：WhatsApp、Directory、Logs。

为什么 OpenClaw 不在群组中回复？

两个常见原因：

  • 提及门控已开启（默认）。你必须 @提及机器人（或匹配 mentionPatterns）。
  • 你配置了 channels.whatsapp.groups 但没有 "*"，并且群组未列入 Allowlist。

参见 Groups 和 Group 消息。

群组/线程与 DM 共享 Context 吗？

直接聊天默认折叠到主 Session。群组/Channel 有自己的 Session 键，Telegram 主题 / Discord 线程是独立的 Session。参见 Groups 和 Group 消息。

我可以创建多少个 Workspace 和 Agent？

没有硬性限制。几十个（甚至几百个）都可以，但要注意：

  • **磁盘增长：**Session + 记录存储在 ~/.openclaw/agents/<agentId>/sessions/ 下。
  • **Token 成本：**更多 Agent 意味着更多并发模型使用。
  • **运维开销：**每个 Agent 的 auth profiles、Workspace 和 Channel Routing。

提示：

  • 为每个 Agent 保留一个活动 Workspace（agents.defaults.workspace）。
  • 如果磁盘增长，修剪旧 Session（删除 JSONL 或存储条目）。
  • 使用 openclaw doctor 发现杂散 Workspace 和配置文件不匹配。

我可以同时运行多个机器人或聊天吗（Slack），应该如何设置？

可以。使用 Multi-Agent Routing 运行多个隔离的 Agent，并按 Channel/账户/peer 路由入站消息。Slack 作为 Channel 受支持，可以绑定到特定 Agent。

浏览器访问很强大，但不是”做人类能做的任何事情” - 反机器人、CAPTCHA 和 MFA 仍然可以阻止自动化。对于最可靠的浏览器控制，在运行浏览器的机器上使用 Chrome 扩展中继（并将 Gateway 保持在任何地方）。

最佳实践设置：

  • 始终在线的 Gateway 主机（VPS/Mac mini）。
  • 每个角色一个 Agent（绑定）。
  • 绑定到这些 Agent 的 Slack Channel。
  • 需要时通过扩展中继（或节点）使用本地浏览器。

文档：Multi-Agent Routing、Slack、Browser、Chrome 扩展、Nodes。

模型：默认值、选择、别名、切换

默认模型是什么？

OpenClaw 的默认模型是你设置的：

agents.defaults.model.primary

模型被引用为 provider/model（示例：anthropic/claude-opus-4-5）。如果你省略 Provider，OpenClaw 目前假定 anthropic 作为临时弃用回退 - 但你仍应明确设置 provider/model。

你推荐什么模型？

推荐默认：anthropic/claude-opus-4-5。 好的替代：anthropic/claude-sonnet-4-5。 可靠（较少个性）：openai/gpt-5.2 - 几乎和 Opus 一样好，只是个性较少。 预算：zai/glm-4.7。

MiniMax M2.1 有自己的文档：MiniMax 和 本地模型。

经验法则：对高风险工作使用你能负担得起的最好模型，对常规聊天或摘要使用更便宜的模型。你可以为每个 Agent 路由模型，并使用 Sub-agents 并行化长任务（每个 Sub-agent 消耗 Token）。参见 Models 和 Sub-agents。

强烈警告：较弱/过度量化的模型更容易受到 Prompt 注入和不安全行为的影响。参见 Security。

更多上下文：Models。

我可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？

可以。如果你的本地服务器公开 OpenAI 兼容的 API，你可以将自定义 Provider 指向它。Ollama 直接支持，是最简单的路径。

安全说明：较小或严重量化的模型更容易受到 Prompt 注入的影响。我们强烈建议任何可以使用工具的机器人使用大型模型。如果你仍然想要小型模型，启用 Sandboxing 和严格的工具 Allowlist。

文档：Ollama、本地模型、模型 Provider、Security、Sandboxing。

如何在不清空配置的情况下切换模型？

使用模型命令或仅编辑模型字段。避免完全配置替换。

安全选项：

  • 在聊天中使用 /model（快速，每个 Session）
  • openclaw models set ...（仅更新模型配置）
  • openclaw configure --section models（交互式）
  • 在 ~/.openclaw/openclaw.json 中编辑 agents.defaults.model

避免使用部分对象的 config.apply，除非你打算替换整个配置。如果你确实覆盖了配置，从备份恢复或重新运行 openclaw doctor 进行修复。

文档：Models、Configure、Config、Doctor。

OpenClaw、Flawd 和 Krill 使用什么模型？

  • **OpenClaw + Flawd：**Anthropic Opus（anthropic/claude-opus-4-5）- 参见 Anthropic。
  • **Krill：**MiniMax M2.1（minimax/MiniMax-M2.1）- 参见 MiniMax。

如何在不重启的情况下即时切换模型？

使用 /model 命令作为独立消息：

/model sonnet
/model haiku
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash

你可以使用 /model、/model list 或 /model status 列出可用模型。

/model（和 /model list）显示紧凑的编号选择器。按编号选择：

/model 3

你还可以为 Provider 强制特定的 auth profile（每个 Session）：

/model opus@anthropic:default
/model opus@anthropic:work

提示：/model status 显示哪个 Agent 处于活动状态，正在使用哪个 auth-profiles.json 文件，以及接下来将尝试哪个 auth profile。它还显示配置的 Provider 端点（baseUrl）和 API 模式（api）（如果可用）。

如何取消固定我用 @profile 设置的配置文件？

重新运行 /model 不带 @profile 后缀：

/model anthropic/claude-opus-4-5

如果你想返回默认值，从 /model 中选择它（或发送 /model <default provider/model>）。使用 /model status 确认哪个 auth profile 处于活动状态。

我可以将 GPT 5.2 用于日常任务，将 Codex 5.2 用于编码吗？

可以。将一个设置为默认值，并根据需要切换：

  • 快速切换（每个 Session）：/model gpt-5.2 用于日常任务，/model gpt-5.2-codex 用于编码。
  • **默认 + 切换：**将 agents.defaults.model.primary 设置为 openai-codex/gpt-5.2，然后在编码时切换到 openai-codex/gpt-5.2-codex（或反过来）。
  • **Sub-agents：**将编码任务路由到具有不同默认模型的 Sub-agents。

参见 Models 和 Slash 命令。

为什么我看到”Model is not allowed”然后没有回复？

如果设置了 agents.defaults.models，它将成为 /model 和任何 Session 覆盖的 Allowlist。选择不在该列表中的模型会返回：

Model "provider/model" is not allowed. Use /model to list available models.

该错误代替正常回复返回。修复：将模型添加到 agents.defaults.models，删除 Allowlist，或从 /model list 中选择模型。

为什么我看到”Unknown model minimax/MiniMax-M2.1”？

这意味着 Provider 未配置（未找到 MiniMax Provider 配置或 auth profile），因此无法解析模型。此检测的修复在 2026.1.12 中（在撰写本文时尚未发布）。

修复清单：

  1. 升级到 2026.1.12（或从源代码 main 运行），然后重启 Gateway。
  2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax API 密钥存在于 env/auth profiles 中，以便可以注入 Provider。
  3. 使用确切的模型 ID（区分大小写）：minimax/MiniMax-M2.1 或 minimax/MiniMax-M2.1-lightning。
  4. 运行： 
    openclaw models list
    并从列表中选择（或在聊天中使用 /model list）。

参见 MiniMax 和 Models。

我可以将 MiniMax 作为默认值，将 OpenAI 用于复杂任务吗？

可以。使用 MiniMax 作为默认值，并在需要时按 Session 切换模型。Fallback 用于错误，而不是”困难任务”，因此使用 /model 或单独的 Agent。

选项 A：按 Session 切换

{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.1" },
      models: {
        "minimax/MiniMax-M2.1": { alias: "minimax" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
    },
  },
}

然后：

/model gpt

选项 B：独立 Agent

  • Agent A 默认：MiniMax
  • Agent B 默认：OpenAI
  • 按 Agent 路由或使用 /agent 切换

文档：Models、Multi-Agent Routing、MiniMax、OpenAI。

opus、sonnet、gpt 是内置快捷方式吗？

是的。OpenClaw 附带一些默认简写（仅在模型存在于 agents.defaults.models 中时应用）：

  • opus → anthropic/claude-opus-4-5
  • sonnet → anthropic/claude-sonnet-4-5
  • gpt → openai/gpt-5.2
  • gpt-mini → openai/gpt-5-mini
  • gemini → google/gemini-3-pro-preview
  • gemini-flash → google/gemini-3-flash-preview

如果你设置了同名的自己的别名，你的值获胜。

如何定义/覆盖模型快捷方式（别名）？

别名来自 agents.defaults.models.<modelId>.alias。示例：

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-5" },
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" },
      },
    },
  },
}

然后 /model sonnet（或支持时的 /<alias>）解析为该模型 ID。

如何添加来自其他 Provider 的模型，如 OpenRouter 或 ZAI？

OpenRouter（按 Token 付费；许多模型）：

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
      models: { "openrouter/anthropic/claude-sonnet-4-5": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}

Z.AI（GLM 模型）：

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}

如果你引用 provider/model 但缺少所需的 Provider 密钥，你将收到运行时认证错误（例如 No API key found for provider "zai"）。

添加新 Agent 后出现”No API key found for provider”

这通常意味着新 Agent 有一个空的 auth 存储。Auth 是每个 Agent 的，存储在：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

修复选项：

  • 运行 openclaw agents add <id> 并在向导期间配置 auth。
  • 或将 auth-profiles.json 从主 Agent 的 agentDir 复制到新 Agent 的 agentDir。

不要跨 Agent 重用 agentDir；它会导致 auth/Session 冲突。

模型 Failover 和”All models failed”

Failover 如何工作？

Failover 分两个阶段进行：

  1. 同一 Provider 内的 Auth profile 轮换。
  2. 模型回退到 agents.defaults.model.fallbacks 中的下一个模型。

冷却时间适用于失败的配置文件（指数退避），因此即使 Provider 受到速率限制或暂时失败，OpenClaw 也可以继续响应。

这个错误是什么意思？

No credentials found for profile "anthropic:default"

这意味着系统尝试使用 auth profile ID anthropic:default，但在预期的 auth 存储中找不到它的凭据。

“No credentials found for profile anthropic:default”的修复清单

  • 确认 auth profiles 的位置（新路径与旧路径）
    • 当前：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • 旧版：~/.openclaw/agent/*（由 openclaw doctor 迁移）
  • 确认 Gateway 加载了你的环境变量
    • 如果你在 shell 中设置了 ANTHROPIC_API_KEY，但通过 systemd/launchd 运行 Gateway，它可能不会继承它。将其放在 ~/.openclaw/.env 中或启用 env.shellEnv。
  • 确保你正在编辑正确的 Agent
    • Multi-Agent 设置意味着可能有多个 auth-profiles.json 文件。
  • 健全性检查模型/auth 状态
    • 使用 openclaw models status 查看配置的模型以及 Provider 是否已认证。

“No credentials found for profile anthropic”的修复清单

这意味着运行固定到 Anthropic auth profile，但 Gateway 在其 auth 存储中找不到它。

  • 使用 setup-token
    • 运行 claude setup-token，然后使用 openclaw models auth setup-token --provider anthropic 粘贴它。
    • 如果 Token 是在另一台机器上创建的，使用 openclaw models auth paste-token --provider anthropic。
  • 如果你想使用 API 密钥
    • 在 Gateway 主机上将 ANTHROPIC_API_KEY 放在 ~/.openclaw/.env 中。
    • 清除强制缺失配置文件的任何固定顺序： 
      openclaw models auth order clear --provider anthropic
  • 确认你在 Gateway 主机上运行命令
    • 在远程模式下，auth profiles 存储在 Gateway 机器上，而不是你的笔记本电脑上。

为什么它也尝试了 Google Gemini 并失败？

如果你的模型配置包含 Google Gemini 作为回退（或你切换到 Gemini 简写），OpenClaw 将在模型回退期间尝试它。如果你没有配置 Google 凭据，你会看到 No API key found for provider "google"。

修复：提供 Google auth，或在 agents.defaults.model.fallbacks / 别名中删除/避免 Google 模型，以便回退不会路由到那里。

LLM request rejected message thinking signature required google antigravity

原因：Session 历史包含没有签名的 thinking 块（通常来自中止/部分流）。Google Antigravity 需要 thinking 块的签名。

修复：OpenClaw 现在为 Google Antigravity Claude 剥离未签名的 thinking 块。如果它仍然出现，启动新 Session 或为该 Agent 设置 /thinking off。

Auth profiles：它们是什么以及如何管理它们

相关：/concepts/oauth（OAuth 流程、Token 存储、多账户模式）

什么是 auth profile？

Auth profile 是与 Provider 绑定的命名凭据记录（OAuth 或 API 密钥）。Profiles 存储在：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

典型的 profile ID 是什么？

OpenClaw 使用 Provider 前缀的 ID，如：

  • anthropic:default（当不存在电子邮件身份时常见）
  • anthropic:<email> 用于 OAuth 身份
  • 你选择的自定义 ID（例如 anthropic:work）

我可以控制首先尝试哪个 auth profile 吗？

可以。配置支持 profiles 的可选元数据和每个 Provider 的排序（auth.order.<provider>）。这不存储秘密；它将 ID 映射到 Provider/模式并设置轮换顺序。

如果 profile 处于短暂的冷却（速率限制/超时/auth 失败）或更长的禁用状态（计费/信用不足），OpenClaw 可能会暂时跳过它。要检查这一点，运行 openclaw models status --json 并检查 auth.unusableProfiles。调整：auth.cooldowns.billingBackoffHours*。

你还可以通过 CLI 设置每个 Agent 的顺序覆盖（存储在该 Agent 的 auth-profiles.json 中）：

# 默认为配置的默认 Agent（省略 --agent）
openclaw models auth order get --provider anthropic

# 锁定轮换到单个 profile（仅尝试这一个）
openclaw models auth order set --provider anthropic anthropic:default

# 或设置显式顺序（Provider 内的回退）
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# 清除覆盖（回退到配置 auth.order / 轮询）
openclaw models auth order clear --provider anthropic

要针对特定 Agent：

openclaw models auth order set --provider anthropic --agent main anthropic:default

OAuth 与 API 密钥有什么区别？

OpenClaw 支持两者：

  • OAuth 通常利用订阅访问（如果适用）。
  • API 密钥使用按 Token 计费。

向导明确支持 Anthropic setup-token 和 OpenAI Codex OAuth，并可以为你存储 API 密钥。

Gateway：端口、“已运行”和远程模式

Gateway 使用什么端口？

gateway.port 控制 WebSocket + HTTP（Control UI、Hooks 等）的单个多路复用端口。

优先级：

--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789

为什么 openclaw gateway status 说”Runtime running”但”RPC probe failed”？

因为”running”是监督者的视图（launchd/systemd/schtasks）。RPC 探测是 CLI 实际连接到 Gateway WebSocket 并调用 status。

使用 openclaw gateway status 并信任这些行：

  • Probe target:（探测实际使用的 URL）
  • Listening:（端口上实际绑定的内容）
  • Last gateway error:（当进程存活但端口未监听时的常见根本原因）

为什么 openclaw gateway status 显示”Config cli”和”Config service”不同？

你正在编辑一个配置文件，而服务正在运行另一个（通常是 --profile / OPENCLAW_STATE_DIR 不匹配）。

修复：

openclaw gateway install --force

从你希望服务使用的相同 --profile / 环境运行它。

“another gateway instance is already listening”是什么意思？

OpenClaw 通过在启动时立即绑定 WebSocket 监听器（默认 ws://127.0.0.1:18789）来强制执行运行时锁。如果绑定失败并显示 EADDRINUSE，它会抛出 GatewayLockError，表示另一个实例已在监听。

修复：停止另一个实例，释放端口，或使用 openclaw gateway --port <port> 运行。

如何在远程模式下运行 OpenClaw（客户端连接到其他地方的 Gateway）？

设置 gateway.mode: "remote" 并指向远程 WebSocket URL，可选地使用 Token/密码：

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

注意：

  • openclaw gateway 仅在 gateway.mode 为 local 时启动（或你传递覆盖标志）。
  • macOS 应用监视配置文件，并在这些值更改时实时切换模式。

Control UI 说”unauthorized”或一直重新连接，现在怎么办？

你的 Gateway 正在运行并启用了 auth（gateway.auth.*），但 UI 没有发送匹配的 Token/密码。

事实（来自代码）：

  • Control UI 将 Token 存储在浏览器 localStorage 键 openclaw.control.settings.v1 中。
  • UI 可以导入 ?token=...（和/或 ?password=...）一次，然后从 URL 中剥离它。

修复：

  • 最快：openclaw dashboard（打印 + 复制带 Token 的链接，尝试打开；如果无头则显示 SSH 提示）。
  • 如果你还没有 Token：openclaw doctor --generate-gateway-token。
  • 如果远程，首先隧道：ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/?token=...。
  • 在 Gateway 主机上设置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
  • 在 Control UI 设置中，粘贴相同的 Token（或使用一次性 ?token=... 链接刷新）。
  • 仍然卡住？运行 openclaw status --all 并遵循 Troubleshooting。参见 Dashboard 以获取 auth 详细信息。

我设置了 gateway.bind tailnet 但它无法绑定，什么都不监听？

tailnet 绑定从你的网络接口中选择 Tailscale IP（100.64.0.0/10）。如果机器不在 Tailscale 上（或接口已关闭），则没有可绑定的内容。

修复：

  • 在该主机上启动 Tailscale（以便它有一个 100.x 地址），或
  • 切换到 gateway.bind: "loopback" / "lan"。

注意：tailnet 是显式的。auto 更喜欢回环；当你想要仅 tailnet 绑定时使用 gateway.bind: "tailnet"。

我可以在同一主机上运行多个 Gateway 吗？

通常不行 - 一个 Gateway 可以运行多个消息 Channel 和 Agent。仅当你需要冗余（例如：救援机器人）或硬隔离时才使用多个 Gateway。

可以，但你必须隔离：

  • OPENCLAW_CONFIG_PATH（每个实例的配置）
  • OPENCLAW_STATE_DIR（每个实例的状态）
  • agents.defaults.workspace（Workspace 隔离）
  • gateway.port（唯一端口）

快速设置（推荐）：

  • 每个实例使用 openclaw --profile <name> …（自动创建 ~/.openclaw-<name>）。
  • 在每个配置文件配置中设置唯一的 gateway.port（或为手动运行传递 --port）。
  • 安装每个配置文件的服务：openclaw --profile <name> gateway install。

Profiles 还会为服务名称添加后缀（bot.molt.<profile>；旧版 com.openclaw.*、openclaw-gateway-<profile>.service、OpenClaw Gateway (<profile>)）。 完整指南：多个 Gateway。

“invalid handshake code 1008”是什么意思？

Gateway 是一个 WebSocket 服务器，它期望第一条消息是 connect 帧。如果它收到其他任何内容，它会以 code 1008（策略违规）关闭连接。

常见原因：

  • 你在浏览器中打开了 HTTP URL（http://...）而不是 WS 客户端。
  • 你使用了错误的端口或路径。
  • 代理或隧道剥离了 auth 标头或发送了非 Gateway 请求。

快速修复：

  1. 使用 WS URL：ws://<host>:18789（或 wss://... 如果是 HTTPS）。
  2. 不要在普通浏览器标签中打开 WS 端口。
  3. 如果 auth 已开启，在 connect 帧中包含 Token/密码。

如果你使用 CLI 或 TUI，URL 应该看起来像：

openclaw tui --url ws://<host>:18789 --token <token>

协议详细信息：Gateway 协议。

日志和调试

日志在哪里？

文件日志（结构化）：

/tmp/openclaw/openclaw-YYYY-MM-DD.log

你可以通过 logging.file 设置稳定路径。文件日志级别由 logging.level 控制。控制台详细程度由 --verbose 和 logging.consoleLevel 控制。

最快的日志跟踪：

openclaw logs --follow

服务/监督者日志（当 Gateway 通过 launchd/systemd 运行时）：

  • macOS：$OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log（默认：~/.openclaw/logs/...；profiles 使用 ~/.openclaw-<profile>/logs/...）
  • Linux：journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
  • Windows：schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

参见 Troubleshooting 以获取更多信息。

如何启动/停止/重启 Gateway 服务？

使用 Gateway 助手：

openclaw gateway status
openclaw gateway restart

如果你手动运行 Gateway，openclaw gateway --force 可以回收端口。参见 Gateway。

我在 Windows 上关闭了终端，如何重启 OpenClaw？

有两种 Windows 安装模式：

**1) WSL2（推荐）：**Gateway 在 Linux 内运行。

打开 PowerShell，进入 WSL，然后重启：

wsl
openclaw gateway status
openclaw gateway restart

如果你从未安装服务，在前台启动它：

openclaw gateway run

**2) 原生 Windows（不推荐）：**Gateway 直接在 Windows 中运行。

打开 PowerShell 并运行：

openclaw gateway status
openclaw gateway restart

如果你手动运行它（无服务），使用：

openclaw gateway run

文档：Windows（WSL2）、Gateway 服务运行手册。

Gateway 已启动但回复从未到达，我应该检查什么？

从快速健康检查开始：

openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow

常见原因：

  • 模型 auth 未在 Gateway 主机上加载（检查 models status）。
  • Channel 配对/Allowlist 阻止回复（检查 Channel 配置 + 日志）。
  • WebChat/Dashboard 在没有正确 Token 的情况下打开。

如果你是远程的，确认隧道/Tailscale 连接已启动，并且 Gateway WebSocket 可访问。

文档：Channels、Troubleshooting、远程访问。

“Disconnected from gateway”没有原因，现在怎么办？

这通常意味着 UI 失去了 WebSocket 连接。检查：

  1. Gateway 正在运行吗？openclaw gateway status
  2. Gateway 健康吗？openclaw status
  3. UI 有正确的 Token 吗？openclaw dashboard
  4. 如果远程，隧道/Tailscale 链接已启动吗？

然后跟踪日志：

openclaw logs --follow

文档：Dashboard、远程访问、Troubleshooting。

Telegram setMyCommands 失败并出现网络错误，我应该检查什么？

从日志和 Channel 状态开始：

openclaw channels status
openclaw channels logs --channel telegram

如果你在 VPS 上或在代理后面，确认允许出站 HTTPS 并且 DNS 工作。如果 Gateway 是远程的，确保你在 Gateway 主机上查看日志。

文档：Telegram、Channel 故障排除。

TUI 没有输出，我应该检查什么？

首先确认 Gateway 可访问且 Agent 可以运行：

openclaw status
openclaw models status
openclaw logs --follow

在 TUI 中，使用 /status 查看当前状态。如果你期望在聊天 Channel 中回复，确保启用了传递（/deliver on）。

文档：TUI、Slash 命令。

如何完全停止然后启动 Gateway？

如果你安装了服务：

openclaw gateway stop
openclaw gateway start

这会停止/启动监督服务（macOS 上的 launchd，Linux 上的 systemd）。当 Gateway 作为 Daemon 在后台运行时使用此方法。

如果你在前台运行，使用 Ctrl-C 停止，然后：

openclaw gateway run

文档：Gateway 服务运行手册。

ELI5：openclaw gateway restart 与 openclaw gateway 的区别？

  • openclaw gateway restart：重启后台服务（launchd/systemd）。
  • openclaw gateway：在此终端 Session 中在前台运行 Gateway。

如果你安装了服务，使用 Gateway 命令。当你想要一次性前台运行时使用 openclaw gateway。

当某些东西失败时，获取更多详细信息的最快方法是什么？

使用 --verbose 启动 Gateway 以获取更多控制台详细信息。然后检查日志文件以获取 Channel auth、模型路由和 RPC 错误。

媒体和附件

我的 Skill 生成了图像/PDF，但什么都没有发送？

来自 Agent 的出站附件必须包含 MEDIA:<path-or-url> 行（单独一行）。参见 OpenClaw 助手设置 和 Agent send。

CLI 发送：

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

还要检查：

  • 目标 Channel 支持出站媒体，并且未被 Allowlist 阻止。
  • 文件在 Provider 的大小限制内（图像调整为最大 2048px）。

参见 Images。

安全和访问控制

将 OpenClaw 暴露给入站 DM 安全吗？

将入站 DM 视为不受信任的输入。默认值旨在降低风险：

  • DM 能力 Channel 上的默认行为是 Pairing：
    • 未知发送者收到配对代码；机器人不处理他们的消息。
    • 批准：openclaw pairing approve <channel> <code>
    • 待处理请求上限为每个 Channel 3 个；如果代码未到达，检查 openclaw pairing list <channel>。
  • 公开打开 DM 需要明确选择加入（dmPolicy: "open" 和 Allowlist "*"）。

运行 openclaw doctor 以发现有风险的 DM 策略。

Prompt 注入只是公共机器人的问题吗？

不。Prompt 注入是关于不受信任的内容，而不仅仅是谁可以 DM 机器人。如果你的助手读取外部内容（Web 搜索/获取、浏览器页面、电子邮件、文档、附件、粘贴的日志），该内容可能包含试图劫持模型的指令。即使你是唯一的发送者，这也可能发生。

最大的风险是启用工具时：模型可能被欺骗泄露 Context 或代表你调用工具。通过以下方式减少爆炸半径：

  • 使用只读或禁用工具的”阅读器” Agent 来总结不受信任的内容
  • 为启用工具的 Agent 关闭 web_search / web_fetch / browser
  • Sandboxing 和严格的工具 Allowlist

详细信息：Security。

我的机器人应该有自己的电子邮件、GitHub 账户或电话号码吗？

是的，对于大多数设置。使用单独的账户和电话号码隔离机器人可以减少出错时的爆炸半径。这也使得轮换凭据或撤销访问更容易，而不会影响你的个人账户。

从小处开始。只授予你实际需要的工具和账户的访问权限，如果需要，稍后再扩展。

文档：Security、Pairing。

我可以让它自主处理我的短信吗？这安全吗？

我们不建议对你的个人消息完全自主。最安全的模式是：

  • 将 DM 保持在 Pairing 模式或严格的 Allowlist 中。
  • 如果你想让它代表你发送消息，使用单独的号码或账户。
  • 让它起草，然后在发送前批准。

如果你想实验，在专用账户上进行并保持隔离。参见 Security。

我可以为个人助手任务使用更便宜的模型吗？

可以，如果 Agent 仅用于聊天且输入是受信任的。较小的层级更容易受到指令劫持的影响，因此避免将它们用于启用工具的 Agent 或读取不受信任内容时。如果你必须使用较小的模型，锁定工具并在 Sandbox 内运行。参见 Security。

我在 Telegram 中运行了 /start 但没有收到配对代码？

配对代码仅在未知发送者向机器人发送消息且启用了 dmPolicy: "pairing" 时发送。/start 本身不会生成代码。

检查待处理请求：

openclaw pairing list telegram

如果你想立即访问，将你的发送者 ID 列入 Allowlist 或为该账户设置 dmPolicy: "open"。

WhatsApp 会给我的联系人发消息吗？Pairing 如何工作？

不会。默认的 WhatsApp DM 策略是 Pairing。未知发送者只会收到配对代码，他们的消息不会被处理。OpenClaw 只回复它收到的聊天或你触发的显式发送。

批准配对：

openclaw pairing approve whatsapp <code>

列出待处理请求：

openclaw pairing list whatsapp

向导电话号码提示：它用于设置你的 Allowlist/所有者，以便允许你自己的 DM。它不用于自动发送。如果你在个人 WhatsApp 号码上运行，使用该号码并启用 channels.whatsapp.selfChatMode。

聊天命令、中止任务和”它不会停止”

如何阻止内部系统消息在聊天中显示？

大多数内部或工具消息仅在为该 Session 启用 verbose 或 reasoning 时出现。

在你看到它的聊天中修复：

/verbose off
/reasoning off

如果它仍然嘈杂，在 Control UI 中检查 Session 设置并将 verbose 设置为 inherit。还要确认你没有使用配置中 verboseDefault 设置为 on 的机器人配置文件。

文档：Thinking and verbose、Security。

如何停止/取消正在运行的任务？

发送以下任何一个作为独立消息（无斜杠）：

stop
abort
esc
wait
exit
interrupt

这些是中止触发器（不是 Slash 命令）。

对于后台进程（来自 exec 工具），你可以要求 Agent 运行：

process action:kill sessionId:XXX

Slash 命令概述：参见 Slash 命令。

大多数命令必须作为以 / 开头的独立消息发送，但一些快捷方式（如 /status）也适用于 Allowlist 发送者的内联使用。

如何从 Telegram 发送 Discord 消息？“Cross-context messaging denied”

OpenClaw 默认阻止跨 Provider 消息传递。如果工具调用绑定到 Telegram，它不会发送到 Discord，除非你明确允许。

为 Agent 启用跨 Provider 消息传递：

{
  agents: {
    defaults: {
      tools: {
        message: {
          crossContext: {
            allowAcrossProviders: true,
            marker: { enabled: true, prefix: "[from {channel}] " },
          },
        },
      },
    },
  },
}

编辑配置后重启 Gateway。如果你只想为单个 Agent 启用此功能，请在 agents.list[].tools.message 下设置。

为什么感觉机器人忽略了快速连发的消息？

Queue 模式控制新消息如何与正在进行的运行交互。使用 /queue 更改模式：

  • steer - 新消息重定向当前任务
  • followup - 一次运行一条消息
  • collect - 批量处理消息并回复一次（默认）
  • steer-backlog - 现在引导，然后处理积压
  • interrupt - 中止当前运行并重新开始

你可以为 followup 模式添加选项，如 debounce:2s cap:25 drop:summarize。

回答截图/聊天日志中的确切问题

问：“使用 API 密钥的 Anthropic 默认模型是什么？”

**答：**在 OpenClaw 中，凭据和模型选择是分开的。设置 ANTHROPIC_API_KEY（或在 auth profiles 中存储 Anthropic API 密钥）启用认证，但实际的默认模型是你在 agents.defaults.model.primary 中配置的（例如，anthropic/claude-sonnet-4-5 或 anthropic/claude-opus-4-5）。如果你看到 No credentials found for profile "anthropic:default"，这意味着 Gateway 在正在运行的 Agent 的预期 auth-profiles.json 中找不到 Anthropic 凭据。

仍然卡住？在 Discord 中提问或打开 GitHub 讨论。 最新构建还会在 Linux systemd 服务上预置常见的用户 bin 目录（例如 ~/.local/bin、~/.npm-global/bin、~/.local/share/pnpm、~/.bun/bin），并在设置时遵守 PNPM_HOME、NPM_CONFIG_PREFIX、BUN_INSTALL、VOLTA_HOME、ASDF_DATA_DIR、NVM_DIR 和 FNM_DIR。