常见问题（FAQ）

针对实际环境（本地开发、VPS、多代理（multi-agent）、OAuth/API密钥、模型故障转移（model failover））的快速解答和深度排错指南。关于运行时诊断，请参阅故障排除。关于完整的配置参考，请参阅配置。

目录

出问题时的前60秒排查

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

    openclaw status

    快速本地摘要：操作系统 + 更新、网关/服务可达性、代理/会话、提供商配置 + 运行时问题（当网关可达时）。

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

    openclaw status --all

    只读诊断与日志尾部（令牌已编辑）。

  3. 守护进程 + 端口状态

    openclaw gateway status

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

  4. 深度探测

    openclaw status --deep

    运行网关健康检查 + 提供商探测（需要可达的网关）。参阅健康检查。

  5. 追踪最新日志

    openclaw logs --follow

    如果 RPC 宕机，回退到：

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

    文件日志与服务日志是分开的；参阅日志记录和故障排除。

  6. 运行诊断修复（repairs）

    openclaw doctor

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

  7. 网关快照

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

    向运行中的网关请求完整快照（仅限 WebSocket）。参阅健康检查。

快速开始和首次运行设置

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

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

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

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

这会从 git 检出安装 OpenClaw，因此代理可以读取代码 + 文档并推理你正在运行的确切版本。你以后可以通过重新运行不带 --install-method git 的安装器切换回稳定版。

提示：让代理计划并监督修复过程（逐步进行），然后只执行必要的命令。这样可以保持更改小且易于审计。

如果你发现了真正的 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：网关/代理健康状态 + 基本配置的快速快照。
  • openclaw models status：检查提供商认证 + 模型可用性。
  • openclaw doctor：验证并修复常见的配置/状态问题。

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

快速调试循环：出问题时的前60秒排查。 安装文档：安装、安装器标志、更新。

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

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

curl -fsSL https://openclaw.bot/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 运行。

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

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

如何在本地主机与远程环境中验证控制面板（token）？

本地主机（同一台机器）：

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

不在本地主机上：

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

参阅控制面板和Web 界面了解绑定模式和认证详情。

需要什么运行时？

需要 Node >= 22。推荐使用 pnpm。不推荐在网关（Gateway）上使用 Bun。

可以在树莓派上运行吗？

可以。网关（Gateway）是轻量级的 - 文档列出 512MB-1GB RAM、1 核心和约 500MB 磁盘空间对于个人使用已经足够，并指出 树莓派 4 可以运行它。

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

提示：一个小型树莓派/VPS 可以托管网关（Gateway），你可以在笔记本/手机上配对**节点（nodes）**以使用本地屏幕/摄像头/画布或命令执行。参阅节点。

树莓派安装有什么技巧？

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

  • 使用 64 位操作系统并保持 Node >= 22。
  • 优先使用可编辑（hackable）git 安装，这样你可以查看日志并快速更新。
  • 开始时不要启用频道/技能，然后逐个添加它们。
  • 如果遇到奇怪的二进制问题，通常是 ARM 兼容性问题。

文档：Linux、安装。

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

该屏幕依赖于网关（Gateway）可达且已认证。TUI 也会在首次孵化时自动发送"Wake up, my friend!"。如果你看到该行没有回复且令牌保持在 0，代理从未运行。

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

如果网关是远程的，确保隧道/Tailscale 连接已启动，并且 UI 指向正确的网关。参阅远程访问。

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

可以。复制状态目录和工作区（workspace），然后运行一次 Doctor。这会保持你的机器人"完全相同"（内存、会话历史、认证和频道状态），只要你复制两个位置：

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

这会保留配置、认证配置文件、WhatsApp 凭据、会话和内存。如果你在远程模式下，记住网关主机拥有会话存储和工作区。

重要：如果你只是提交/推送你的工作区到 GitHub，你是在备份内存 + 引导文件，但不是会话历史或认证。那些存储在 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/sessions/）。

相关：迁移、磁盘上的文件位置、 代理工作区、Doctor、 远程模式。

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

查看 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 加入白名单，然后重试。更多详情：故障排除。 请通过在此报告帮助我们解除封锁：https://spa.xfinity.com/check_url_status。

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

稳定版（stable）和测试版（beta）有什么区别？

**稳定版（Stable）和测试版（beta）**是 npm dist-tags，而不是单独的代码线：

  • latest = 稳定版
  • beta = 用于测试的早期构建

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

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

如何安装测试版（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.bot/install.sh | bash -s -- --beta

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

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

更多详情：开发渠道和安装器标志。

如何试用最新版本？

两个选项：

  1. 开发渠道（git 检出）：
openclaw update --channel dev

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

  1. 可编辑安装（从安装器站点）：
curl -fsSL https://openclaw.bot/install.sh | bash -s -- --install-method git

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

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

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

文档：更新、开发渠道、 安装。

安装器卡住了？如何获得更多反馈？

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

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

带详细输出的 Beta 安装：

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

对于可编辑（git）安装：

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

更多选项：安装器标志。

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。

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

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

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

更多详情：安装和安装器标志。

如何在 Linux 上安装 OpenClaw？

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

如何在 VPS 上安装 OpenClaw？

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

指南：exe.dev、Hetzner、Fly.io。
远程访问：网关远程。

云服务器/VPS 安装指南在哪里？

我们在一个托管中心保存了常见提供商的指南。选择一个并按照指南操作：

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

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

中心：平台。远程访问：网关远程。 节点：节点、节点 CLI。

能否让 OpenClaw 自己更新自己？

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

使用 CLI：

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

如果你必须从代理自动化：

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

文档：更新、更新指南。

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

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

  • 模型/认证设置（推荐为 Claude 订阅使用 Anthropic setup-token，支持 OpenAI Codex OAuth，可选 API 密钥，支持 LM Studio 本地模型）
  • **工作区（Workspace）**位置 + 引导文件
  • 网关设置（bind/port/auth/tailscale）
  • 提供商（WhatsApp、Telegram、Discord、Mattermost（插件）、Signal、iMessage）
  • 守护进程安装（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元）
  • 健康检查和**技能（skills）**选择

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

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

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

文档：Anthropic、OpenAI、 本地模型、模型。

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

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

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

Anthropic "setup-token" 认证如何工作？

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

在哪里找到 Anthropic setup-token？

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

claude setup-token

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

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

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

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

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

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

提示：设置一个后备模型，这样当提供商速率受限时 OpenClaw 可以继续回复。参阅模型和OAuth。

支持 AWS Bedrock 吗？

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

Codex 认证如何工作？

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

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

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

参阅OAuth、模型提供商和向导。

如何设置 Gemini CLI OAuth？

Gemini CLI 使用插件认证流程，而不是 openclaw.json 中的客户端 id 或密钥。

步骤：

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

这会在网关主机上的认证配置文件中存储 OAuth 令牌。详情：模型提供商。

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

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

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

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

必须购买 Mac Mini 才能安装吗？

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

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

文档：iMessage、节点、Mac 远程模式。

需要 Mac mini 才能支持 iMessage 吗？

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

常见设置：

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

文档：iMessage、BlueBubbles、 Mac 远程模式。

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

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

常见模式：

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

文档：节点、节点 CLI。

可以使用 Bun 吗？

不推荐使用 Bun。我们看到运行时错误，尤其是在 WhatsApp 和 Telegram 上。使用 Node 作为稳定的网关。

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

Telegram：allowFrom 里应该填什么？

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

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

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

官方 Bot API：

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

第三方（不太私密）：

  • 给 @userinfobot 或 @getidsbot 发私信。

参阅/channels/telegram。

多个人可以在不同的 OpenClaw 实例中使用同一个 WhatsApp 号码吗？

可以，通过多代理路由（multi-agent routing）。将每个发送者的 WhatsApp 私信（DM）（对等方 kind: "dm"，发送者 E.164 如 +15551234567）绑定到不同的 agentId，这样每个人都有自己的工作区和会话存储。回复仍然来自同一个 WhatsApp 账户，私信访问控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）对每个 WhatsApp 账户是全局的。参阅多代理路由和WhatsApp。

能否运行一个"快速聊天"代理和一个"Opus 编码"代理？

可以。使用多代理路由：为每个代理提供自己的默认模型，然后将入站路由（提供商账户或特定对等方）绑定到每个代理。示例配置在多代理路由中。另请参阅模型和配置。

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 中解析。 最新版本还在 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。

可编辑（hackable）git 安装和 npm 安装有什么区别？

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

文档：入门指南、更新指南。

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

可以。安装另一种方式，然后运行 Doctor，以便网关服务指向新的入口点。这不会删除你的数据 - 它只会更改 OpenClaw 代码安装。你的状态（~/.openclaw）和工作区（~/.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 检测到网关服务入口点不匹配，并提供重写服务配置以匹配当前安装（在自动化中使用 --repair）。

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

应该在笔记本还是 VPS 上运行网关（Gateway）？

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

笔记本（本地网关）

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

VPS / 云

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

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

**推荐默认值：**如果你之前遇到过网关断开连接，使用 VPS。当你积极使用 Mac 并希望本地文件访问或具有可见浏览器的 UI 自动化时，本地方式很好。

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

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

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

如果你想要两全其美，将网关保留在专用主机上，并将笔记本配对为**节点（node）**以使用本地屏幕/摄像头/执行工具。参阅节点。 有关安全指南，请阅读安全。

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

OpenClaw 是轻量级的。对于基本网关 + 一个聊天频道：

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

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

文档：Linux、VPS 托管。

能否在虚拟机中运行 OpenClaw，要求是什么？

可以。将虚拟机视为 VPS：它需要始终开启、可达，并有足够的 RAM 用于网关和你启用的任何频道。

基准指南：

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

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

什么是 OpenClaw？

用一段话介绍 OpenClaw 是什么？

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

价值主张是什么？

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

亮点：

  • **你的设备，你的数据：**在你想要的任何地方（Mac、Linux、VPS）运行网关，并将工作区 + 会话历史保留在本地。
  • 真实频道，而不是 Web 沙箱： WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等，以及支持平台上的移动语音和画布（Canvas）。
  • **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，具有每个代理路由和故障转移。
  • 仅本地选项：运行本地模型，以便所有数据都可以保留在你的设备上（如果你想要）。
  • **多代理路由：**每个频道、账户或任务有单独的代理，每个代理都有自己的工作区和默认值。
  • **开源且可编辑：**检查、扩展和自托管，无供应商锁定。

文档：网关、频道、多代理、 内存。

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

好的首批项目：

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

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

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

日常胜利通常看起来像：

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

OpenClaw 能帮助 SaaS 进行潜在客户开发、外展、广告和博客吗？

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

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

文档：安全。

与 Claude Code 相比，在 Web 开发方面有什么优势？

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

优势：

  • 跨会话的持久内存 + 工作区
  • 多平台访问（WhatsApp、Telegram、TUI、WebChat）
  • 工具编排（浏览器、文件、调度、钩子）
  • 始终在线的网关（在 VPS 上运行，从任何地方交互）
  • **节点（Nodes）**用于本地浏览器/屏幕/摄像头/执行

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

技能和自动化（Skills and automation）

如何在不污染仓库的情况下自定义技能

使用托管覆盖（managed overrides）而不是直接编辑仓库副本。将您的更改放在 ~/.openclaw/skills/<name>/SKILL.md 中（或通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 添加文件夹）。优先级是 <workspace>/skills > ~/.openclaw/skills > 内置技能，因此托管覆盖会优先生效而不会影响 git。只有值得向上游贡献的编辑才应该存在于仓库中并作为 PR 提交。

我可以从自定义文件夹加载技能吗

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

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

目前支持的模式有：

  • 定时任务（Cron jobs）：隔离的任务可以为每个作业设置 model 覆盖。
  • 子代理（Sub-agents）：将任务路由到具有不同默认模型的单独代理。
  • 按需切换：使用 /model 随时切换当前会话模型。

参见 定时任务、多代理路由 和 斜杠命令。

机器人在执行繁重工作时卡住了，如何卸载该任务

使用子代理处理长时间或并行任务。子代理在自己的会话中运行， 返回摘要，并保持您的主聊天响应。

要求您的机器人"为此任务生成一个子代理"或使用 /subagents。 使用聊天中的 /status 查看网关当前正在做什么（以及是否繁忙）。

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

文档：子代理。

定时任务或提醒不触发，我应该检查什么

定时任务（Cron）在网关进程内运行。如果网关没有持续运行， 计划任务将不会运行。

检查清单：

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

调试：

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

文档：定时任务、Cron vs Heartbeat。

如何在 Linux 上安装技能

使用 ClawdHub（CLI）或将技能放入您的工作区。macOS 技能 UI 在 Linux 上不可用。 在 https://clawdhub.com 浏览技能。

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

npm i -g clawdhub

pnpm add -g clawdhub

OpenClaw 可以按计划或在后台持续运行任务吗

可以。使用网关调度器：

  • 定时任务（Cron jobs） 用于计划或重复任务（跨重启持久化）。
  • 心跳（Heartbeat） 用于"主会话"定期检查。
  • 隔离任务（Isolated jobs） 用于发布摘要或传递到聊天的自主代理。

文档：定时任务、Cron vs Heartbeat、 心跳。

我可以从 Linux 运行 Apple macOS 专属技能吗

不能直接运行。macOS 技能由 metadata.openclaw.os 加上所需二进制文件控制，并且技能仅在网关主机上符合条件时才出现在系统提示中。在 Linux 上，darwin 专属技能（如 imsg、apple-notes、apple-reminders）除非您覆盖控制，否则不会加载。

您有三种支持的模式：

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

选项 B - 使用 macOS 节点（无需 SSH）。
在 Linux 上运行网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将节点运行命令设置为"始终询问"或"始终允许"。当所需二进制文件存在于节点上时，OpenClaw 可以将 macOS 专属技能视为符合条件。代理通过 nodes 工具运行这些技能。如果您选择"始终询问"，在提示中批准"始终允许"会将该命令添加到允许列表。

选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。
将网关保持在 Linux 上，但使所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖技能以允许 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. 覆盖技能元数据（工作区或 ~/.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. 启动新会话以便技能快照刷新。

专门针对 iMessage，您还可以将 channels.imessage.cliPath 指向 SSH 包装器（OpenClaw 仅需要 stdio）。参见 iMessage。

你们有 Notion 或 HeyGen 集成吗

目前没有内置。

选项：

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

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

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

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

安装技能：

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

ClawdHub 安装到当前目录下的 ./skills（或回退到您配置的 OpenClaw 工作区）；OpenClaw 在下次会话时将其视为 <workspace>/skills。对于跨代理的共享技能，将它们放在 ~/.openclaw/skills/<name>/SKILL.md 中。某些技能需要通过 Homebrew 安装的二进制文件；在 Linux 上意味着 Linuxbrew（参见上面的 Homebrew Linux FAQ 条目）。参见 技能 和 ClawdHub。

如何安装用于浏览器接管的 Chrome 扩展

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

openclaw browser extension install
openclaw browser extension path

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

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

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

沙箱和内存（Sandboxing and memory）

有专门的沙箱文档吗

有。参见 沙箱。有关 Docker 特定设置（Docker 中的完整网关或沙箱镜像），请参见 Docker。

我可以保持 DM 私密但使用一个代理让群组公开沙箱化吗

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

使用 agents.defaults.sandbox.mode: "non-main"，以便群组/频道会话（非主密钥）在 Docker 中运行，而主 DM 会话保持在主机上。然后通过 tools.sandbox.tools 限制沙箱会话中可用的工具。

设置演练 + 示例配置：群组：个人 DM + 公共群组

关键配置参考：网关配置

如何将主机文件夹绑定到沙箱中

将 agents.defaults.sandbox.docker.binds 设置为 ["host:path:mode"]（例如，"/home/user/src:/src:ro"）。全局 + 每个代理的绑定会合并；当 scope: "shared" 时，每个代理的绑定会被忽略。对于任何敏感内容使用 :ro，并记住绑定会绕过沙箱文件系统隔离。参见 沙箱 和 沙箱 vs 工具策略 vs 提升权限 获取示例和安全说明。

内存是如何工作的

OpenClaw 内存只是代理工作区中的 Markdown 文件：

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

OpenClaw 还在自动压缩前运行静默预压缩内存刷新，以提醒模型 在自动压缩前写入持久笔记。这仅在工作区 可写时运行（只读沙箱会跳过它）。参见 内存。

内存总是忘记事情，如何让它保持

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

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

文档：内存、代理工作区。

语义内存搜索需要 OpenAI API 密钥吗

仅当您使用 OpenAI 嵌入时。Codex OAuth 涵盖聊天/完成，并且 不授予嵌入访问权限，因此使用 Codex 登录（OAuth 或 Codex CLI 登录） 对语义内存搜索没有帮助。OpenAI 嵌入 仍然需要真实的 API 密钥（OPENAI_API_KEY 或 models.providers.openai.apiKey）。

如果您没有显式设置提供商，OpenClaw 会在可以解析 API 密钥时自动选择提供商（auth 配置文件、models.providers.*.apiKey 或环境变量）。 如果可以解析 OpenAI 密钥，它会优先选择 OpenAI，否则如果可以解析 Gemini 密钥，则选择 Gemini。如果两个密钥都不可用，内存搜索将保持禁用状态，直到您配置它。如果您配置并存在本地模型路径，OpenClaw 会优先选择 local。

如果您宁愿保持本地，设置 memorySearch.provider = "local"（并可选 memorySearch.fallback = "none"）。如果您想要 Gemini 嵌入，设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini 或本地嵌入 模型 - 有关设置详细信息，请参见 内存。

内存会永久保存吗，有什么限制

内存文件存储在磁盘上并持久保存，直到您删除它们。限制是您的 存储，而不是模型。会话上下文仍然受模型上下文窗口限制，因此长对话可能会压缩或截断。这就是为什么 内存搜索存在的原因 - 它只将相关部分拉回上下文。

文档：内存、上下文。

文件在磁盘上的存储位置（Where things live on disk）

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

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

  • 默认本地： 会话、内存文件、配置和工作区存储在网关主机上 （~/.openclaw + 您的工作区目录）。
  • 远程必要性： 您发送给模型提供商（Anthropic/OpenAI/等）的消息会发送到 它们的 API，聊天平台（WhatsApp/Telegram/Slack/等）在它们的 服务器上存储消息数据。
  • 您控制足迹： 使用本地模型可将提示保留在您的机器上，但频道 流量仍会通过频道的服务器。

相关：代理工作区、内存。

OpenClaw 在哪里存储其数据

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

路径（Path）用途（Purpose）
$OPENCLAW_STATE_DIR/openclaw.json主配置（JSON5）
$OPENCLAW_STATE_DIR/credentials/oauth.json旧版 OAuth 导入（首次使用时复制到 auth 配置文件）
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.jsonAuth 配置文件（OAuth + API 密钥）
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json运行时 auth 缓存（自动管理）
$OPENCLAW_STATE_DIR/credentials/提供商状态（例如 whatsapp/<accountId>/creds.json）
$OPENCLAW_STATE_DIR/agents/每个代理的状态（agentDir + 会话）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/对话历史 & 状态（每个代理）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json会话元数据（每个代理）

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

您的工作区（AGENTS.md、内存文件、技能等）是独立的，通过 agents.defaults.workspace 配置（默认：~/.openclaw/workspace）。

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

这些文件存储在代理工作区中，而不是 ~/.openclaw。

  • 工作区（每个代理）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、 MEMORY.md（或 memory.md）、memory/YYYY-MM-DD.md、可选的 HEARTBEAT.md。
  • 状态目录（~/.openclaw）：配置、凭据、auth 配置文件、会话、日志 和共享技能（~/.openclaw/skills）。

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

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

如果机器人在重启后"忘记"，请确认网关每次启动时使用相同的 工作区（并记住：远程模式使用网关主机的 工作区，而不是您的本地笔记本电脑）。

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

参见 代理工作区 和 内存。

推荐的备份策略是什么

将您的代理工作区放入私有 git 仓库并备份到某个 私有位置（例如 GitHub 私有）。这会捕获内存 + AGENTS/SOUL/USER 文件，并允许您稍后恢复助手的"思维"。

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

文档：代理工作区。

如何完全卸载 OpenClaw

参见专用指南：卸载。

代理可以在工作区外工作吗

可以。工作区是默认 cwd 和内存锚点，而不是硬沙箱。 相对路径在工作区内解析，但绝对路径可以访问其他 主机位置，除非启用了沙箱。如果您需要隔离，请使用 agents.defaults.sandbox 或每个代理的沙箱设置。如果您 想将仓库作为默认工作目录，请将该代理的 workspace 指向仓库根目录。OpenClaw 仓库只是源代码；除非您有意让代理在其中工作，否则请将 工作区分开。

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

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

我在远程模式下，会话存储在哪里

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

配置基础（Config basics）

配置是什么格式，在哪里

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

$OPENCLAW_CONFIG_PATH

如果文件缺失，它使用安全的默认值（包括默认工作区 ~/.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 调用；它不启用本地网关认证。
  • 控制 UI 通过 connect.params.auth.token（存储在应用/UI 设置中）进行认证。避免将 token 放在 URL 中。

为什么我现在在 localhost 上需要 token

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

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

更改配置后必须重启吗

网关监视配置并支持热重载：

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

如何启用网络搜索和网络获取

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

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

注意：

  • 如果您使用允许列表，请添加 web_search/web_fetch 或 group:web。
  • web_fetch 默认启用（除非显式禁用）。
  • 守护进程从 ~/.openclaw/.env（或服务环境）读取环境变量。

文档：网络工具。

如何在设备间运行中央网关和专门的工作器

常见模式是一个网关（例如 Raspberry Pi）加上节点和代理：

  • 网关（中央）： 拥有频道（Signal/WhatsApp）、路由和会话。
  • 节点（设备）： Mac/iOS/Android 作为外围设备连接并公开本地工具（system.run、canvas、camera）。
  • 代理（工作器）： 为特殊角色提供独立的大脑/工作区（例如"Hetzner 运维"、"个人数据"）。
  • 子代理： 当您需要并行性时，从主代理生成后台工作。
  • TUI： 连接到网关并切换代理/会话。

文档：节点、远程访问、多代理路由、子代理、TUI。

OpenClaw 浏览器可以无头运行吗

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

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

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

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

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

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

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

远程网关 + 节点（Remote gateways + nodes）

命令如何在 Telegram、网关和节点之间传播

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

Telegram → 网关 → 代理 → node.* → 节点 → 网关 → Telegram

节点看不到入站提供商流量；它们仅接收节点 RPC 调用。

如果网关托管在远程，我的代理如何访问我的计算机

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

典型设置：

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

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

安全提醒：配对 macOS 节点允许在该机器上执行 system.run。仅 配对您信任的设备，并查看 安全。

文档：节点、网关协议、macOS 远程模式、安全。

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

检查基础：

  • 网关正在运行：openclaw gateway status
  • 网关健康：openclaw status
  • 频道健康：openclaw channels status

然后验证认证和路由：

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

文档：Tailscale、远程访问、频道。

两个 OpenClaw 实例可以相互通信吗（本地 - VPS）

可以。没有内置的"机器人到机器人"桥接，但您可以通过几种 可靠的方式连接它们：

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

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

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

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

提示：添加防护措施，以便两个机器人不会无休止地循环（仅提及、频道 允许列表或"不回复机器人消息"规则）。

文档：远程访问、代理 CLI、代理发送。

我需要为多个代理使用单独的 VPS 吗

不需要。一个网关可以托管多个代理，每个代理都有自己的工作区、模型默认值 和路由。这是正常设置，比每个代理运行一个 VPS 更便宜、更简单。

仅当您需要硬隔离（安全边界）或非常 不同的配置而您不想共享时，才使用单独的 VPS。否则，保持一个网关并 使用多个代理或子代理。

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

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

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

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

文档：节点、节点 CLI、Chrome 扩展。

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

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

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

文档：节点、节点 CLI、多网关。

节点是否运行网关服务

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

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

是否有 API/RPC 方式来应用配置

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

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

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

恢复：

  • 从备份恢复（git 或复制的 ~/.openclaw/openclaw.json）。
  • 如果您没有备份，重新运行 openclaw doctor 并重新配置频道/模型。
  • 如果这是意外的，提交错误报告并包含您上次已知的配置或任何备份。
  • 本地编码代理通常可以从日志或历史记录中重建工作配置。

避免它：

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

文档：配置、配置命令、Doctor。

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

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

这设置您的工作区并限制谁可以触发机器人。

如何在 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 的控制 UI，在 VPS 上使用 Tailscale Serve：

openclaw gateway --tailscale serve

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

如何将 Mac 节点连接到远程网关 Tailscale Serve

Serve 公开网关控制 UI + WS。节点通过相同的网关 WS 端点连接。

推荐设置：

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

文档：网关协议、发现、macOS 远程模式。

环境变量和 .env 加载（Env vars and .env loading）

OpenClaw 如何加载环境变量

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

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

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

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

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

有关完整优先级和来源，请参见 /environment。

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

两个常见修复：

  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 环境导入是否启用。"Shell env: off" 不意味着您的环境变量缺失 - 它只是意味着 OpenClaw 不会自动加载 您的登录 shell。

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

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

然后重启网关并重新检查：

openclaw models status

Copilot token 从 COPILOT_GITHUB_TOKEN（也包括 GH_TOKEN / GITHUB_TOKEN）读取。 参见 /concepts/model-providers 和 /environment。

会话和多聊天（Sessions & multiple chats）

如何开始新对话

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

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

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

{
  session: {
    idleMinutes: 240
  }
}

有没有办法创建一个 OpenClaw 实例团队，一个 CEO 和许多代理

有，通过多代理路由和子代理。您可以创建一个协调器 代理和几个具有自己工作区和模型的工作代理。

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

文档：多代理路由、子代理、代理 CLI。

为什么上下文在任务中途被截断，如何防止

会话上下文受模型窗口限制。长聊天、大工具输出或许多 文件可能会触发压缩或截断。

有帮助的做法：

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

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

使用重置命令：

openclaw reset

非交互式完全重置：

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

然后重新运行入门：

openclaw onboard --install-daemon

注意：

  • 如果看到现有配置，入门向导也会提供重置。参见 向导。
  • 如果您使用配置文件（--profile / OPENCLAW_PROFILE），请重置每个状态目录（默认为 ~/.openclaw-<profile>）。
  • 开发重置：openclaw gateway --dev --reset（仅限开发；清除开发配置 + 凭据 + 会话 + 工作区）。

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

使用以下之一：

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

    /compact

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

  • 重置（为相同聊天密钥生成新会话 ID）：

    /new
/reset

如果它持续发生：

  • 启用或调整会话修剪（agents.defaults.contextPruning）以修剪旧工具输出。
  • 使用具有更大上下文窗口的模型。

文档：压缩、会话修剪、会话管理。

为什么我看到 LLM request rejected messages\ncontentX\tool_use\input Field required

这是提供商验证错误：模型发出了 tool_use 块，但没有所需的 input。这通常意味着会话历史陈旧或损坏（通常在长线程 或工具/架构更改后）。

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

为什么我每 30 分钟收到一次心跳消息

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

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

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

每个代理覆盖使用 agents.list[].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（如果已配置/允许列表）：从配置列出群组：

openclaw directory groups list --channel whatsapp

文档：WhatsApp、目录、日志。

为什么 OpenClaw 不在群组中回复

两个常见原因：

  • 提及控制已开启（默认）。您必须 @提及机器人（或匹配 mentionPatterns）。
  • 您配置了 channels.whatsapp.groups 但没有 "*"，并且群组未在允许列表中。

参见 群组 和 群组消息。

群组/线程与 DM 共享上下文吗

直接聊天默认折叠到主会话。群组/频道有自己的会话密钥，Telegram 主题 / Discord 线程是独立的会话。参见 群组 和 群组消息。

我可以创建多少个工作区和代理

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

  • 磁盘增长： 会话 + 转录存储在 ~/.openclaw/agents/<agentId>/sessions/ 下。
  • Token 成本： 更多代理意味着更多并发模型使用。
  • 运维开销： 每个代理的 auth 配置文件、工作区和频道路由。

提示：

  • 为每个代理保留一个活动工作区（agents.defaults.workspace）。
  • 如果磁盘增长，修剪旧会话（删除 JSONL 或存储条目）。
  • 使用 openclaw doctor 发现游离工作区和配置文件不匹配。

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

可以。使用多代理路由运行多个隔离代理并通过 频道/帐户/对等方路由入站消息。Slack 作为频道支持，可以绑定到特定代理。

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

最佳实践设置：

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

文档：多代理路由、Slack、 浏览器、Chrome 扩展、节点。

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

什么是默认模型（default model）

OpenClaw 的默认模型（default model）是你设置的：

agents.defaults.model.primary

模型（Models）以 provider/model 格式引用（例如：anthropic/claude-opus-4-5）。如果省略提供商（provider），OpenClaw 当前会假定为 anthropic 作为临时弃用回退（deprecation fallback）- 但你仍应明确设置 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 和 本地模型（Local models）。

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

强烈警告：较弱/过度量化的模型更容易受到提示注入（prompt injection）和不安全行为的攻击。参见 安全（Security）。

更多上下文：模型（Models）。

我可以使用自托管模型（selfhosted models）llamacpp vLLM Ollama 吗

可以。如果你的本地服务器暴露了 OpenAI 兼容的 API，你可以将 自定义提供商（provider）指向它。Ollama 直接支持，是最简单的路径。

安全提示：较小或大量量化的模型更容易受到提示注入（prompt injection）的攻击。我们强烈推荐大型模型用于任何可以使用工具的机器人。 如果你仍想使用小型模型，请启用沙箱（sandboxing）和严格的工具允许列表（allowlists）。

文档：Ollama、本地模型（Local models）、 模型提供商（Model providers）、安全（Security）、 沙箱（Sandboxing）。

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

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

安全选项：

  • 在聊天中使用 /model（快速，每会话）
  • 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）（每会话）：

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

提示：/model status 显示哪个代理（agent）处于活动状态，正在使用哪个 auth-profiles.json 文件，以及下一个将尝试的身份验证配置文件（auth profile）。 当可用时，它还显示配置的提供商端点（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 吗

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

  • 快速切换（每会话）： /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）： 将编码任务路由到具有不同默认模型的子代理。

参见 模型（Models） 和 斜杠命令（Slash commands）。

为什么我看到"模型不允许（Model is not allowed）"然后没有回复

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

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

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

为什么我看到"未知模型 minimaxMiniMaxM21（Unknown model minimaxMiniMaxM21）"

这意味着提供商未配置（未找到 MiniMax 提供商配置或身份验证配置文件（auth profile）），因此无法解析模型。此检测的修复在 2026.1.12 中（撰写时未发布）。

修复清单：

  1. 升级到 2026.1.12（或从源代码 main 运行），然后重启网关（gateway）。
  2. 确保配置了 MiniMax（向导或 JSON），或者环境变量/身份验证配置文件中存在 MiniMax API 密钥，以便可以注入提供商。
  3. 使用确切的模型 id（区分大小写）：minimax/MiniMax-M2.1 或 minimax/MiniMax-M2.1-lightning。
  4. 运行： 
    openclaw models list
    并从列表中选择（或在聊天中使用 /model list）。

参见 MiniMax 和 模型（Models）。

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

可以。使用 MiniMax 作为默认值，并在需要时按会话切换模型。 回退（Fallbacks）用于错误，而不是"困难任务"，因此使用 /model 或单独的代理。

选项 A：按会话切换

{
  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：单独的代理（agents）

  • 代理 A 默认：MiniMax
  • 代理 B 默认：OpenAI
  • 按代理路由或使用 /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

如果你用相同的名称设置自己的别名（alias），你的值优先。

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

别名（Aliases）来自 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。

如何添加来自其他提供商（如 OpenRouter 或 ZAI）的模型

OpenRouter（按令牌付费；多种模型）：

{
  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 但缺少所需的提供商密钥，你将收到运行时身份验证错误（例如 No API key found for provider "zai"）。

添加新代理后出现"未找到提供商的 API 密钥（No API key found for provider）"

这通常意味着新代理具有空的身份验证存储（auth store）。身份验证（Auth）是每个代理的， 存储在：

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

修复选项：

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

不要在代理之间重用 agentDir；这会导致身份验证/会话冲突。

模型故障转移（Model failover）和"所有模型失败（All models failed）"

故障转移（failover）如何工作

故障转移分两个阶段进行：

  1. 在同一提供商内身份验证配置文件轮换（Auth profile rotation）。
  2. **模型回退（Model fallback）**到 agents.defaults.model.fallbacks 中的下一个模型。

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

这个错误是什么意思

No credentials found for profile "anthropic:default"

这意味着系统尝试使用身份验证配置文件 ID anthropic:default，但在预期的身份验证存储中找不到它的凭据。

修复"未找到配置文件 anthropic:default 的凭据（No credentials found for profile anthropic:default）"的检查清单

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

修复"未找到配置文件 anthropic 的凭据（No credentials found for profile anthropic）"的检查清单

这意味着运行固定到 Anthropic 身份验证配置文件，但网关 在其身份验证存储中找不到它。

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

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

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

修复：要么提供 Google 身份验证，要么在 agents.defaults.model.fallbacks / 别名中删除/避免 Google 模型，这样回退就不会路由到那里。

LLM 请求被拒绝消息思考签名必需 google antigravity（LLM request rejected message thinking signature required google antigravity）

原因：会话历史包含没有签名的思考块（thinking blocks without signatures）（通常来自 中止/部分流）。Google Antigravity 要求思考块有签名。

修复：OpenClaw 现在为 Google Antigravity Claude 剥离未签名的思考块。如果仍然出现，开始新会话或为该代理设置 /thinking off。

身份验证配置文件（Auth profiles）：它们是什么以及如何管理它们

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

什么是身份验证配置文件（auth profile）

身份验证配置文件（auth profile）是绑定到提供商的命名凭据记录（OAuth 或 API 密钥）。配置文件位于：

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

典型的配置文件 ID 是什么

OpenClaw 使用提供商前缀的 ID，例如：

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

我可以控制首先尝试哪个身份验证配置文件吗

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

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

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

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

# 将轮换锁定到单个配置文件（仅尝试此配置文件）
openclaw models auth order set --provider anthropic anthropic:default

# 或设置明确的顺序（提供商内回退）
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

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

要定位特定代理：

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

OAuth 与 API 密钥有什么区别

OpenClaw 支持两者：

  • OAuth 通常利用订阅访问（在适用的情况下）。
  • API 密钥使用按令牌付费计费。

向导明确支持 Anthropic 设置令牌和 OpenAI Codex OAuth，并可以为你存储 API 密钥。

网关（Gateway）：端口、"已在运行（already running）"和远程模式

网关使用什么端口

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

优先级：

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

为什么 openclaw gateway status 说"运行时正在运行（Runtime running）"但"RPC 探测失败（RPC probe failed）"

因为"正在运行"是监督者的视图（launchd/systemd/schtasks）。RPC 探测是 CLI 实际连接到网关 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.mode: "remote" 并指向远程 WebSocket URL，可选地使用令牌/密码：

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

注意：

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

控制 UI 说"未授权（unauthorized）"或不断重新连接怎么办

你的网关正在启用身份验证（gateway.auth.*）运行，但 UI 没有发送匹配的令牌/密码。

事实（来自代码）：

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

修复：

  • 最快：openclaw dashboard（打印 + 复制令牌化链接，尝试打开；如果无头则显示 SSH 提示）。
  • 如果你还没有令牌：openclaw doctor --generate-gateway-token。
  • 如果是远程的，首先建立隧道：ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/?token=...。
  • 在网关主机上设置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
  • 在控制 UI 设置中，粘贴相同的令牌（或使用一次性 ?token=... 链接刷新）。
  • 仍然卡住？运行 openclaw status --all 并遵循 故障排除（Troubleshooting）。参见 仪表板（Dashboard） 了解身份验证详细信息。

我设置了 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"。

我可以在同一主机上运行多个网关吗

通常不行 - 一个网关可以运行多个消息通道和代理。仅在需要冗余（例如：救援机器人）或硬隔离时使用多个网关。

可以，但你必须隔离：

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

快速设置（推荐）：

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

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

"无效的握手代码 1008（invalid handshake code 1008）"是什么意思

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

常见原因：

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

快速修复：

  1. 使用 WS URL：ws://<host>:18789（或如果 HTTPS 则为 wss://...）。
  2. 不要在普通浏览器标签中打开 WS 端口。
  3. 如果启用了身份验证，请在 connect 帧中包含令牌/密码。

如果你使用 CLI 或 TUI，URL 应该如下所示：

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

协议详细信息：网关协议（Gateway protocol）。

日志记录和调试

日志在哪里

文件日志（结构化）：

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

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

最快的日志跟踪：

openclaw logs --follow

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

  • macOS：$OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log（默认：~/.openclaw/logs/...；配置文件使用 ~/.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） 了解更多。

如何启动/停止/重启网关服务

使用网关助手：

openclaw gateway status
openclaw gateway restart

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

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

有两种 Windows 安装模式：

1) WSL2（推荐）： 网关在 Linux 内运行。

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

wsl
openclaw gateway status
openclaw gateway restart

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

openclaw gateway run

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

打开 PowerShell 并运行：

openclaw gateway status
openclaw gateway restart

如果你手动运行（没有服务），使用：

openclaw gateway run

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

网关启动但回复从未到达我应该检查什么

从快速健康检查开始：

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

常见原因：

  • 模型身份验证未在网关主机上加载（检查 models status）。
  • 通道配对/允许列表阻止回复（检查通道配置 + 日志）。
  • WebChat/Dashboard 在没有正确令牌的情况下打开。

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

文档：通道（Channels）、故障排除（Troubleshooting）、远程访问（Remote access）。

从网关断开连接无原因怎么办

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

  1. 网关正在运行吗？openclaw gateway status
  2. 网关健康吗？openclaw status
  3. UI 有正确的令牌吗？openclaw dashboard
  4. 如果是远程的，隧道/Tailscale 链接是否启动？

然后跟踪日志：

openclaw logs --follow

文档：仪表板（Dashboard）、远程访问（Remote access）、故障排除（Troubleshooting）。

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

从日志和通道状态开始：

openclaw channels status
openclaw channels logs --channel telegram

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

文档：Telegram、通道故障排除（Channel troubleshooting）。

TUI 不显示输出我应该检查什么

首先确认网关可访问并且代理可以运行：

openclaw status
openclaw models status
openclaw logs --follow

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

文档：TUI、斜杠命令（Slash commands）。

如何完全停止然后启动网关

如果你安装了服务：

openclaw gateway stop
openclaw gateway start

这会停止/启动受监督的服务（macOS 上的 launchd，Linux 上的 systemd）。 当网关作为守护进程在后台运行时使用此方法。

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

openclaw gateway run

文档：网关服务运行手册（Gateway service runbook）。

ELI5 openclaw gateway restart 与 openclaw gateway

  • openclaw gateway restart：重启后台服务（launchd/systemd）。
  • openclaw gateway：在此终端会话的前台运行网关。

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

当出现故障时获取更多详细信息的最快方法是什么

使用 --verbose 启动网关以获取更多控制台详细信息。然后检查日志文件以查找通道身份验证、模型路由和 RPC 错误。

媒体和附件

我的技能生成了图像/PDF 但什么都没有发送

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

CLI 发送：

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

还要检查：

  • 目标通道支持出站媒体并且不被允许列表阻止。
  • 文件在提供商的大小限制内（图像调整为最大 2048px）。

参见 图像（Images）。

安全和访问控制

向入站 DM 暴露 OpenClaw 是否安全

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

  • 支持 DM 的通道上的默认行为是配对（pairing）：
    • 未知发送者收到配对代码；机器人不处理他们的消息。
    • 使用以下方式批准：openclaw pairing approve <channel> <code>
    • 待处理请求每个通道上限为 3 个；如果代码未到达，请检查 openclaw pairing list <channel>。
  • 公开打开 DM 需要明确选择加入（dmPolicy: "open" 和允许列表 "*"）。

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

提示注入（prompt injection）只是公共机器人的问题吗

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

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

  • 使用只读或禁用工具的"阅读器"代理来总结不受信任的内容
  • 为启用工具的代理关闭 web_search / web_fetch / browser
  • 沙箱和严格的工具允许列表

详细信息：安全（Security）。

我的机器人应该有自己的电子邮件 GitHub 账户还是电话号码

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

从小处开始。仅授予你实际需要的工具和账户的访问权限，并在 需要时稍后扩展。

文档：安全（Security）、配对（Pairing）。

我可以给它自主权处理我的短信吗这安全吗

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

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

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

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

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

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

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

检查待处理请求：

openclaw pairing list telegram

如果你想立即访问，允许列表你的发送者 id 或为该账户设置 dmPolicy: "open"。

WhatsApp 会向我的联系人发送消息吗配对如何工作

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

使用以下方式批准配对：

openclaw pairing approve whatsapp <code>

列出待处理请求：

openclaw pairing list whatsapp

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

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

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

大多数内部或工具消息仅在为该会话启用**详细（verbose）或推理（reasoning）**时出现。

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

/verbose off
/reasoning off

如果仍然嘈杂，请检查控制 UI 中的会话设置并将详细设置为继承（inherit）。还要确认你没有使用在配置中将 verboseDefault 设置为 on 的机器人配置文件。

文档：思考和详细（Thinking and verbose）、安全（Security）。

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

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

stop
abort
esc
wait
exit
interrupt

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

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

process action:kill sessionId:XXX

斜杠命令概述：参见 斜杠命令（Slash commands）。

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

如何从 Telegram 发送 Discord 消息"跨上下文消息被拒绝（Cross-context messaging denied）"

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

为代理启用跨提供商消息：

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

编辑配置后重启网关。如果你只想为单个 代理执行此操作，请改为在 agents.list[].tools.message 下设置。

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

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

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

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

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

Q："使用 API 密钥的 Anthropic 默认模型是什么？"

A： 在 OpenClaw 中，凭据和模型选择是分开的。设置 ANTHROPIC_API_KEY（或在身份验证配置文件中存储 Anthropic API 密钥）启用身份验证，但实际的默认模型是你在 agents.defaults.model.primary 中配置的任何内容（例如，anthropic/claude-sonnet-4-5 或 anthropic/claude-opus-4-5）。如果你看到 No credentials found for profile "anthropic:default"，这意味着网关无法在正在运行的代理的预期 auth-profiles.json 中找到 Anthropic 凭据。

仍然卡住？在 Discord 中询问或打开 GitHub 讨论。

← 返回文档首页