OpenClaw 🦞

FAQ

FAQ

快速答案加上针对真实环境设置的深入故障排除（本地开发、VPS、多代理、OAuth/API 密钥、模型故障转移）。有关运行时诊断，请参阅 故障排除。有关完整的配置参考，请参阅 配置。

目录

如果出现问题，前 60 秒

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

    openclaw status

    快速本地摘要：操作系统 + 更新、gateway/service 可达性、代理/sessions、提供商配置 + 运行时问题（当 gateway 可达时）。

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

    openclaw status --all

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

  3. 守护进程 + 端口状态

    openclaw gateway status

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

  4. 深度探测

    openclaw status --deep

    运行 gateway 健康检查 + 提供商探测（需要可访问的 gateway）。请参阅 健康。

  5. 跟踪最新日志

    openclaw logs --follow

    如果 RPC 宕机，回退到：

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

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

  6. 运行 doctor（修复）

    openclaw doctor

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

  7. Gateway 快照

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

    请求运行中的 gateway 提供完整快照（仅 WS）。请参阅 健康。

快速入门和首次运行设置

我卡住了最快的摆脱方法是什么

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

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

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

这会从 git checkout 安装 OpenClaw，因此代理可以读取代码 + 文档，并针对你运行的确切版本进行推理。以后可以通过不带 --install-method git 重新运行安装程序切换回 stable。

提示：让代理计划和监督修复（逐步），然后仅执行必要的命令。这样可以保持更改较小，易于审核。

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

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

快速调试循环：如果出现问题，前 60 秒。 安装文档：安装、安装程序标志、更新。

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

repo 推荐从源码运行并使用入门向导：

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 运行。

入门后如何打开仪表板

向导会在入门后立即用干净的（非令牌）仪表板 URL 打开浏览器，并在摘要中打印链接。保持该标签页打开；如果没有启动，在同一台机器上复制/粘贴打印的 URL。

如何在 localhost 和远程之间认证仪表板token

Localhost（同一台机器）：

  • 打开 http://127.0.0.1:18789/。
  • 如果要求认证，将 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）中的 token 粘贴到 Control UI 设置中。
  • 从 gateway 主机获取：openclaw config get gateway.auth.token（或生成一个：openclaw doctor --generate-gateway-token）。

不在 localhost：

  • Tailscale Serve（推荐）：保持绑定 loopback，运行 openclaw gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，身份头满足 Control UI/WebSocket 认证（无需 token，假设受信任的 gateway 主机）；HTTP API 仍需要 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 然后打开 http://127.0.0.1:18789/ 并在 Control UI 设置中粘贴 token。

请参阅 仪表板 和 Web 表面 了解绑定模式和认证详情。

我需要什么运行时

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

它能在 Raspberry Pi 上运行吗

可以。Gateway 很轻量 - 文档列出 512MB-1GB RAM、1 核心 和大约 500MB 磁盘就足够个人使用，并指出 Raspberry Pi 4 可以运行它。

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

提示：小型 Pi/VPS 可以托管 Gateway，你可以在笔记本/手机上配对 nodes 以获取本地屏幕/相机/canvas 或命令执行。请参阅 Nodes。

Raspberry Pi 安装有什么提示吗

简而言之：它有效，但预期会有些粗糙。

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

文档：Linux、安装。

它卡在 wake up my friend 入门无法孵化现在怎么办

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

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

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

我可以将设置迁移到新机器mac-mini 而无需重新入门吗

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

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

这会保留配置、auth profiles、WhatsApp 凭据、sessions 和内存。如果在远程模式，记住 gateway 主机拥有 session store 和 workspace。

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

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

我在哪里可以看到最新版本的新内容

查看 GitHub changelog： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

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

我无法访问 docsopenclawai-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 = 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

更多详情：开发频道 和 安装程序标志。

安装和入门通常需要多长时间

粗略指南：

  • 安装： 2-5 分钟
  • 入门： 5-15 分钟，取决于配置的频道/模型数量

如果挂起，使用 安装程序卡住 和 我卡住了 中的快速调试循环。

如何尝试最新的代码

两个选项：

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

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

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

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

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

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

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

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

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

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

带详细输出的 beta 安装：

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

对于 hackable（git）安装：

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

Windows（PowerShell）等价命令：

# install.ps1 还没有专用的 -Verbose 标志。
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

更多选项：安装程序标志。

Windows 安装显示 git not found 或 openclaw not recognized

两个常见的 Windows 问题：

1) npm error spawn git / git not found

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

2) 安装后 openclaw not recognized

  • 你的 npm 全局 bin 文件夹不在 PATH 上。

  • 检查路径：

    npm config get prefix

  • 将该目录添加到用户 PATH（Windows 上不需要 \bin 后缀；大多数系统是 %AppData%\npm）。

  • 更新 PATH 后关闭并重新打开 PowerShell。

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

Windows exec 输出显示乱码中文文本该怎么办

这通常是原生 Windows shell 上的控制台代码页不匹配。

症状：

  • system.run/exec 输出将中文渲染为乱码
  • 同一命令在另一个终端配置文件中看起来正常

PowerShell 中的快速解决方法：

chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

然后重启 Gateway 并重试命令：

openclaw gateway restart

如果在最新 OpenClaw 上仍然重现此问题，在以下位置跟踪/报告：

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

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

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

更多详情：安装 和 安装程序标志。

如何在 Linux 上安装 OpenClaw

简答：遵循 Linux 指南，然后运行入门向导。

如何在 VPS 上安装 OpenClaw

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

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

云vps 安装指南在哪里

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

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

你可以配对 nodes（Mac/iOS/Android/headless）到该云 Gateway，以访问本地屏幕/相机/canvas 或在笔记本上运行命令，同时将 Gateway 保持在云中。

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

我可以要求 OpenClaw 更新自己吗

简答：可能，但不推荐。更新流程可能会重启 Gateway（这会丢弃活动会话），可能需要干净的 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

如果必须从代理自动化：

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

文档：更新、更新。

入门向导实际上做了什么

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

  • 模型/认证设置（支持提供商 OAuth/setup-token 流程和 API 密钥，以及本地模型选项如 LM Studio）
  • Workspace 位置 + bootstrap 文件
  • Gateway 设置（绑定/端口/认证/tailscale）
  • 提供商（WhatsApp、Telegram、Discord、Mattermost（插件）、Signal、iMessage）
  • 守护进程安装（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元）
  • 健康检查 和 技能 选择

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

我需要 Claude 或 OpenAI 订阅才能运行这个吗

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

如果选择 Anthropic 订阅认证，自行决定是否使用它：Anthropic 过去曾阻止 Claude Code 之外的一些订阅使用。OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具。

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

可以在没有-api-密钥的情况下使用-claude-max-订阅吗

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

Claude Pro/Max 订阅不包括 API 密钥，所以这是订阅账户的技术路径。但这是你的决定：Anthropic 过去曾阻止 Claude Code 之外的一些订阅使用。如果想要最清晰和最安全的生产支持路径，使用 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 提供商的 auth profile 存储，并像 API 密钥一样使用（无自动刷新）。更多详情：OAuth。

在哪里可以找到-anthropic-setup-token

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

claude setup-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 令牌；使用 setup-token 或 Anthropic API 密钥。在任何地方生成令牌并在 gateway 主机上粘贴它。请参阅 Anthropic 和 OAuth。

重要：这是技术兼容性，不是政策保证。Anthropic 过去曾阻止 Claude Code 之外的一些订阅使用。你需要决定是否使用它并验证 Anthropic 的当前条款。对于生产或多用户工作负载，Anthropic API 密钥认证是更安全、推荐的选择。

为什么我看到来自-anthropic-的-http-429-ratelimit_error

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

如果消息具体是： Extra usage is required for long context requests，请求正尝试使用 Anthropic 的 1M 上下文 beta（context1m: true）。这仅在你的凭据有资格获得长上下文计费（API 密钥计费或启用额外使用的订阅）时才有效。

提示：设置回退模型，这样当提供商被速率限制时 OpenClaw 可以继续回复。请参阅 模型、OAuth 和 /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context。

支持 AWS Bedrock 吗

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

Codex 认证如何工作

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

你们支持-openai-订阅认证codex-oauth-吗

支持。OpenClaw 完全支持 OpenAI Code（Codex）订阅 OAuth。OpenAI 明确允许在像 OpenClaw 这样的外部工具/工作流中使用订阅 OAuth。入门向导可以为你运行 OAuth 流程。

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

如何设置 Gemini CLI OAuth

Gemini CLI 使用插件认证流程，而不是 openclaw.json 中的 client id 或 secret。

步骤：

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

这会在 gateway 主机上的 auth profiles 中存储 OAuth 令牌。详情：模型提供商。

本地模型适合休闲聊天吗

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

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

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

我必须购买 Mac Mini 才能安装这个吗

不需要。OpenClaw 在 macOS 或 Linux 上运行（Windows 通过 WSL2）。Mac mini 是可选的 - 有些人买一个作为常开主机，但小型 VPS、家庭服务器或 Raspberry Pi 级盒子也可以。

你只需要 Mac 来运行仅限 macOS 的工具。对于 iMessage，使用 BlueBubbles（推荐） - BlueBubbles 服务器在任何 Mac 上运行，Gateway 可以在 Linux 或其他地方运行。如果想要其他仅限 macOS 的工具，在 Mac 上运行 Gateway 或配对 macOS node。

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

我需要 Mac mini 来支持 iMessage 吗

你需要某个 macOS 设备登录到 Messages。它不必是 Mac mini - 任何 Mac 都可以。使用 BlueBubbles（推荐）来支持 iMessage - BlueBubbles 服务器在 macOS 上运行，而 Gateway 可以在 Linux 或其他地方运行。

常见设置：

  • 在 Linux/VPS 上运行 Gateway，在任何登录 Messages 的 Mac 上运行 BlueBubbles 服务器。
  • 如果想要最简单的单机设置，在 Mac 上运行所有内容。

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

如果我购买-mac-mini-运行-openclaw-可以将其连接到我的-macbook-pro-吗

可以。Mac mini 可以运行 Gateway，你的 MacBook Pro 可以作为node（ Companion 设备）连接。Nodes 不运行 Gateway - 它们提供额外功能，如屏幕/相机/canvas 和该系统上的 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 获得稳定的 gateways。

如果仍想实验 Bun，在没有 WhatsApp/Telegram 的非生产 gateway 上进行。

Telegramallowfrom 中应该放什么

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

入门向导接受 @username 输入并将其解析为数字 ID，但 OpenClaw 授权仅使用数字 ID。

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

  • 给你的机器人发 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-实例吗

可以，通过多代理路由。将每个发送者的 WhatsApp DM（对等 kind: "direct"，发送者 E.164 如 +15551234567）绑定到不同的 agentId，这样每个人都有自己的 workspace 和 session store。回复仍然来自同一个 WhatsApp 账户，DM 访问控制（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。

hackablegit-安装和-npm-安装有什么区别

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

文档：入门、更新。

以后可以在-npm-和-git-安装之间切换吗

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

从 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（插件）/Discord 都可以从 VPS 正常运行。唯一的真正权衡是无头浏览器与可见窗口。请参阅 浏览器。

推荐默认： 如果之前有 gateway 断开连接，使用 VPS。当你积极使用 Mac 并想要本地文件访问或使用可见浏览器进行 UI 自动化时，本地很好。

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

不需要，但推荐用于可靠性和隔离。

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

如果想要两全其美，将 Gateway 保持在专用主机上，并将笔记本配对为node，用于本地屏幕/相机/执行工具。请参阅 Nodes。 有关安全指导，阅读 安全。

最低 VPS 要求和推荐 OS 是什么

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

  • 绝对最低： 1 vCPU，1GB RAM，约 500MB 磁盘。
  • 推荐： 1-2 vCPU，2GB RAM 或更多以获得余量（日志、媒体、多个频道）。Node 工具和浏览器自动化可能消耗大量资源。

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

文档：Linux、VPS hosting。

可以在-vm-中运行-openclaw-吗要求是什么

可以。将 VM 视为与 VPS 相同：它必须常开、可达，并有足够的 RAM 用于 Gateway 和启用的任何频道。

基线指导：

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

如果在 Windows 上，WSL2 是最简单的 VM 风格设置，具有最好的工具兼容性。请参阅 Windows、VPS hosting。 如果在 VM 中运行 macOS，请参阅 macOS VM。

OpenClaw 是什么？

用一段话来说openclaw 是什么

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

价值主张是什么

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

亮点：

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

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

我刚设置好首先应该做什么

好的第一个项目：

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

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

OpenClaw 的五大日常用例是什么

日常胜利通常看起来像：

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

OpenClaw 能帮助-saas-进行潜在客户开发外展广告和博客吗

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

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

文档：安全。

与-claude-code-相比在-web-开发方面有什么优势

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

优势：

  • 持久内存 + workspace 跨会话
  • 多平台访问（WhatsApp、Telegram、TUI、WebChat）
  • 工具编排（浏览器、文件、调度、hooks）
  • 常开 Gateway（在 VPS 上运行，从任何地方交互）
  • Nodes 用于本地浏览器/屏幕/相机/执行

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

技能和自动化

如何自定义技能而不让-repo-保持脏状态

使用托管覆盖而不是编辑 repo 副本。将更改放在 ~/.openclaw/skills/<name>/SKILL.md（或通过 skills.load.extraDirs 添加到 ~/.openclaw/openclaw.json）。优先级是 <workspace>/skills > ~/.openclaw/skills > 捆绑，所以托管覆盖获胜而无需触碰 git。只有值得上游的编辑应该生活在 repo 中并作为 PR 发出。

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

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

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

今天支持的模式是：

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

请参阅 Cron 作业、多代理路由 和 斜杠命令。

机器人在执行繁重工作时冻结如何卸载

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

让你的机器人"为此任务生成子代理"或使用 /subagents。在聊天中使用 /status 查看 Gateway 当前在做什么（以及是否繁忙）。

令牌提示：长任务和子代理都消耗令牌。如果关心成本，通过 agents.defaults.subagents.model 为子代理设置更便宜的模型。

文档：子代理。

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

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

检查清单：

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

调试：

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

文档：Cron 作业、Cron vs Heartbeat。

如何在 Linux 上安装技能

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

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

npm i -g clawhub

pnpm add -g clawhub

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

可以。使用 Gateway 调度器：

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

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

可以从-linux-运行仅限-apple-macos-的技能吗

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

你有三种支持模式：

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

选项 B - 使用 macOS node（无 SSH）。 在 Linux 上运行 Gateway，配对 macOS node（菜单栏应用），并在 Mac 上将Node Run Commands 设置为"Always Ask"或"Always Allow"。当节点上存在所需的二进制文件时，OpenClaw 可以将仅限 macOS 的技能视为符合条件。代理通过 nodes 工具运行这些技能。如果选择"Always Ask"，在提示中批准"Always Allow"会将该命令添加到允许列表中。

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

  1. 为二进制文件创建 SSH 包装器（示例：memo 用于 Apple Notes）：

    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"

  2. 将包装器放在 Linux 主机上的 PATH 上（例如 ~/bin/memo）。

  3. 覆盖技能元数据（workspace 或 ~/.openclaw/skills）以允许 Linux：

    ---
name: apple-notes
description: 通过 macOS 上的 memo CLI 管理 Apple Notes。
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---

  4. 启动新会话，以便技能快照刷新。

有 Notion 或 HeyGen 集成吗

今天没有内置。

选项：

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

如果想要为每个客户保持上下文（机构工作流），一个简单模式是：

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

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

安装技能：

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

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

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

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

openclaw browser extension install
openclaw browser extension path

然后 Chrome → chrome://extensions → 启用"开发者模式" → "Load unpacked" → 选择该文件夹。

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

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

沙盒和内存

有专门的沙盒文档吗

有。请参阅 沙盒。对于 Docker 特定设置（Docker 中的完整 gateway 或沙盒镜像），请参阅 Docker。

Docker 感觉有限如何启用完整功能

默认镜像是安全优先，作为 node 用户运行，所以不包括系统包、Homebrew 或捆绑浏览器。对于更完整的设置：

  • 使用 OPENCLAW_HOME_VOLUME 持久化 /home/node，这样缓存可以存活。
  • 使用 OPENCLAW_DOCKER_APT_PACKAGES 将系统依赖项构建到镜像中。
  • 通过捆绑 CLI 安装 Playwright 浏览器： node /app/node_modules/playwright-core/cli.js install chromium
  • 设置 PLAYWRIGHT_BROWSERS_PATH 并确保路径持久化。

文档：Docker、浏览器。

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

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

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

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

关键配置参考：Gateway 配置

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

将 agents.defaults.sandbox.docker.binds 设置为 ["host:path:mode"]（例如 "/home/user/src:/src:ro"）。全局 + 每代理绑定合并；当 scope: "shared" 时每代理绑定被忽略。对任何敏感内容使用 :ro，并记住绑定绕过沙盒文件系统墙。请参阅 沙盒 和 沙盒 vs 工具策略 vs Elevated 了解示例和安全说明。

内存如何工作

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

  • 每日笔记在 memory/YYYY-MM-DD.md
  • 策划的长期笔记在 MEMORY.md（仅限主/私密会话）

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

内存总是忘记事情如何让它持久化

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

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

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

语义内存搜索需要-openai-api-密钥吗

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

如果没有明确设置提供商，OpenClaw 在可以解析 API 密钥时自动选择提供商（auth profiles、models.providers.*.apiKey 或环境变量）。如果解析了 OpenAI 密钥，它优先使用 OpenAI，否则如果解析了 Gemini 密钥则使用 Gemini，然后是 Voyage，然后是 Mistral。如果没有远程密钥可用，内存搜索保持禁用直到你配置它。如果配置并存在本地模型路径，OpenClaw 优先使用 local。当你明确设置 memorySearch.provider = "ollama" 时支持 Ollama。

如果想保持本地，设置 memorySearch.provider = "local"（可选 memorySearch.fallback = "none"）。如果想要 Gemini embeddings，设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持OpenAI、Gemini、Voyage、Mistral、Ollama 或本地嵌入模型 - 请参阅 内存 了解设置详情。

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

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

文档：内存、上下文。

磁盘上的存储位置

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

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

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

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

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 密钥和可选 keyRef/tokenRef）
$OPENCLAW_STATE_DIR/secrets.json用于 file SecretRef 提供商的可选文件支持秘密负载
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json传统兼容文件（静态 api_key 条目已清理）
$OPENCLAW_STATE_DIR/credentials/提供商状态（例如 whatsapp/<accountId>/creds.json）
$OPENCLAW_STATE_DIR/agents/每代理状态（agentDir + sessions）
$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）。

agentsmd--soulmd--usermd--memorymd-应该放在哪里

这些文件生活在代理工作区，不是 ~/.openclaw。

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

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

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

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

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

请参阅 代理工作区 和 内存。

推荐的备份策略是什么

将你的代理工作区放入私有 git repo 并备份到某个私有地方（例如 GitHub 私有）。这会捕获内存 + AGENTS/SOUL/USER 文件，并允许你以后恢复助手的"思想"。

不要提交 ~/.openclaw 下的任何内容（凭据、sessions、令牌或加密的秘密负载）。 如果需要完全恢复，分别备份工作区和状态目录（见上面的迁移问题）。

文档：代理工作区。

如何完全卸载 OpenClaw

请参阅专用指南：卸载。

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

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

示例（repo 作为默认 cwd）：

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

我在远程模式-session-store-在哪里

会话状态由gateway 主机拥有。如果在远程模式，你关心的 session store 在远程机器上，不是你的本地笔记本。请参阅 会话管理。

配置基础

配置是什么格式在哪里

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

$OPENCLAW_CONFIG_PATH

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

我设置了-gatewaybind-lan-或-tailnet-现在没有监听--ui-显示未授权

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

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

说明：

  • gateway.remote.token / .password 本身不启用本地 gateway 认证。
  • 当 gateway.auth.* 未设置时，本地调用路径可以使用 gateway.remote.* 作为回退。
  • Control UI 通过 connect.params.auth.token 认证（存储在应用/UI 设置中）。避免将令牌放入 URL。

为什么现在-localhost-需要-token

OpenClaw 默认强制执行令牌认证，包括 loopback。如果没有配置令牌，gateway 启动会自动生成一个并保存到 gateway.auth.token，所以本地 WS 客户端必须认证。这阻止其他本地进程调用 Gateway。

如果真的想要开放 loopback，在配置中明确设置 gateway.auth.mode: "none"。Doctor 可以随时为你生成令牌：openclaw doctor --generate-gateway-token。

更改配置后必须重启吗

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

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

如何禁用有趣的-cli-标语

在配置中设置 cli.banner.taglineMode：

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}
  • off：隐藏标语文本但保留横幅标题/版本行。
  • default：每次使用 All your chats, one OpenClaw.。
  • random：轮换有趣/季节性标语（默认行为）。
  • 如果不想要横幅，设置环境变量 OPENCLAW_HIDE_BANNER=1。

如何启用-web-search-和-web-fetch

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,
      },
    },
  },
}

说明：

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

文档：Web 工具。

如何运行一个带有跨设备专用工作者的中央-gateway

常见模式是一个 Gateway（例如 Raspberry Pi）加上nodes和代理：

  • Gateway（中央）： 拥有频道（Signal/WhatsApp）、路由和 sessions。
  • Nodes（设备）： Macs/iOS/Android 作为外围设备连接并暴露本地工具（system.run、canvas、camera）。
  • 代理（工作者）： 用于特殊角色的独立大脑/工作区（例如"Hetzner ops"、"Personal data"）。
  • 子代理： 当想要并行时从主代理生成后台工作。
  • TUI： 连接到 Gateway 并切换代理/sessions。

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

OpenClaw 浏览器可以无头运行吗

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

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

默认是 false（有头）。无头更可能在某些站点上触发反机器人检查。请参阅 浏览器。

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

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

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

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

远程 gateways 和 nodes

命令如何在-telegramgateway-和-nodes-之间传播

Telegram 消息由gateway处理。Gateway 运行代理，然后仅在需要 node 工具时通过Gateway WebSocket调用 nodes：

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

Nodes 看不到入站提供商流量；它们只接收 node RPC 调用。

如果-gateway-托管在远程我的代理如何访问我的计算机

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

典型设置：

  1. 在常开主机（VPS/家庭服务器）上运行 Gateway。

  2. 将 Gateway 主机 + 你的计算机放在同一个 tailnet 上。

  3. 确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。

  4. 在本地打开 macOS 应用并以Remote over SSH模式连接（或直接 tailnet），这样它可以注册为 node。

  5. 在 Gateway 上批准 node：

    openclaw devices list
openclaw devices approve <requestId>

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

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

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

Tailscale 已连接但没有回复现在怎么办

检查基础：

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

然后验证认证和路由：

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

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

两个-openclaw-实例可以互相通信吗本地--vps

可以。没有内置的"bot-to-bot"桥，但可以通过几种可靠方式连接：

最简单： 使用两个机器人都可以访问的正常聊天频道（Telegram/Slack/WhatsApp）。让机器人 A 向机器人 B 发送消息，然后让机器人 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>

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

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

多个代理需要单独的-vps-吗

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

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

在个人笔记本电脑上使用-node-而不是从-vps-ssh-有什么好处吗

可以 - nodes 是从远程 Gateway 到达笔记本电脑的一流方式，它们解锁的不仅仅是 shell 访问。Gateway 在 macOS/Linux（Windows 通过 WSL2）上运行，并且很轻量（小型 VPS 或 Raspberry Pi 级盒子就可以；4 GB RAM 足够），所以常见设置是常开主机加上笔记本电脑作为 node。

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

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

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

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

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

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

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

nodes 运行 gateway 服务吗

不。除非你故意运行隔离的配置文件（请参阅 多个 gateways），否则每个主机应该只运行一个 gateway。Nodes 是连接到 gateway 的外围设备（iOS/Android nodes，或菜单栏应用中的 macOS"node 模式"）。对于无头 node 主机和 CLI 控制，请参阅 Node host CLI。

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

有-api--rpc-方式应用配置吗

可以。config.apply 验证 + 写入完整配置，并在操作过程中重启 Gateway。

configapply 清除了我的配置如何恢复并避免这种情况

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

恢复：

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

避免：

  • 对小更改使用 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：ssh user@your-vps.tailnet-xxxx.ts.net
    • Gateway WS：ws://your-vps.tailnet-xxxx.ts.net:18789

如果想要 Control UI 而无需 SSH，在 VPS 上使用 Tailscale Serve：

openclaw gateway --tailscale serve

这保持 gateway 绑定到 loopback 并通过 Tailscale 暴露 HTTPS。请参阅 Tailscale。

如何将-mac-node-连接到远程-gatewaytailscale-serve

Serve 暴露Gateway Control UI + WS。Nodes 通过相同的 Gateway WS 端点连接。

推荐设置：

  1. 确保 VPS + Mac 在同一个 tailnet 上。

  2. 在远程模式使用 macOS 应用（SSH 目标可以是 tailnet 主机名）。 应用将隧道化 Gateway 端口并作为 node 连接。

  3. 在 gateway 上批准 node：

    openclaw devices list
openclaw devices approve <requestId>

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

环境变量和-env-加载

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 了解完整优先级和来源。

我通过服务启动了-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。

我设置了-copilotgithubtoken-但-models-status-显示-shell-env-off-为什么

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

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

  1. 将令牌放入 ~/.openclaw/.env：

    COPILOT_GITHUB_TOKEN=...

  2. 或启用 shell 导入（env.shellEnv.enabled: true）。

  3. 或将其添加到配置 env 块（仅在缺失时应用）。

然后重启 gateway 并重新检查：

openclaw models status

Copilot 令牌从 COPILOT_GITHUB_TOKEN（还有 GH_TOKEN / GITHUB_TOKEN）读取。请参阅 /concepts/model-providers 和 /environment。

Sessions 和多个聊天

如何开始新的对话

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

如果从不发送-new-sessions 会自动重置吗

可以。Sessions 在 session.idleMinutes（默认60）后过期。下一个消息为该聊天键开始新的会话 id。这不会删除记录 - 它只是开始新的会话。

{
  session: {
    idleMinutes: 240,
  },
}

有没有办法组建-openclaw-实例团队一个-ceo-和多个代理

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

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

文档：多代理路由、子代理、代理 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（仅限开发；清除开发配置 + 凭据 + sessions + workspace）。

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

使用以下之一：

  • 压缩（保留对话但总结较早的回合）：

    /compact

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

  • 重置（同一聊天键的新会话 ID）：

    /new
/reset

如果继续发生：

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

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

为什么我看到-llm-request-rejected-messagescontenttool_useinput-field-required

这是提供商验证错误：模型发出了缺少必需 input 的 tool_use 块。这通常意味着会话历史过时或损坏（通常在长主题或工具/模式更改之后）。

修复：用 /new（独立消息）开始新的会话。

为什么每-30-分钟收到心跳消息

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

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

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

每代理覆盖使用 agents.list[].heartbeat。文档：Heartbeat。

需要在-whatsapp-群组中添加机器人账户吗

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

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

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

如何获取-whatsapp-群组的-jid

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

openclaw logs --follow --json

查找 chatId（或 from）以 @g.us 结尾，如： 1234567890-1234567890@g.us。

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

openclaw directory groups list --channel whatsapp

文档：WhatsApp、目录、日志。

为什么-openclaw-不在群组中回复

两个常见原因：

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

请参阅 群组 和 群组消息。

群组主题与-dm-共享上下文吗

直接聊天默认折叠到主会话。群组/频道有自己的会话键，Telegram 主题 / Discord 主题是分开的会话。请参阅 群组 和 群组消息。

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

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

  • 磁盘增长： sessions + 记录生活在 ~/.openclaw/agents/<agentId>/sessions/ 下。
  • 令牌成本： 更多代理意味着更多并发模型使用。
  • 操作开销： 每代理 auth profiles、workspaces 和频道路由。

提示：

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

可以同时运行多个机器人或聊天吗slack应该如何设置

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

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

最佳实践设置：

  • 常开 Gateway 主机（VPS/Mac mini）。
  • 每个角色一个代理（绑定）。
  • Slack 频道绑定到这些代理。
  • 需要时通过扩展中继（或 node）使用本地浏览器。

文档：多代理路由、Slack、浏览器、Chrome 扩展程序、Nodes。

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

什么是默认模型

OpenClaw 的默认模型是你设置为的任何内容：

agents.defaults.model.primary

模型引用为 provider/model（例如：anthropic/claude-opus-4-6）。如果省略提供商，OpenClaw 当前假设 anthropic 作为临时弃用回退 - 但你仍然应该明确设置 provider/model。

你推荐什么模型

推荐默认： 在提供商堆栈中使用可用的最强最新一代模型。 对于启用工具或不受信任输入的代理： 优先考虑模型强度而不是成本。 对于常规/低风险聊天： 使用更便宜的回退模型并按代理角色路由。

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

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

强烈警告：更弱/过度量化的模型更容易受到提示注入和不安全行为的影响。请参阅 安全。

更多上下文：模型。

可以使用自托管模型llamacppvllmollama-吗

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

安全说明：更小或重度量化的模型更容易受到提示注入。我们强烈建议任何可以使用工具的机器人使用大模型。如果仍想要小模型，启用沙盒和严格的工具允许列表。

文档：Ollama、本地模型、模型提供商、安全、沙盒。

如何切换模型而不清除配置

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

安全选项：

  • 聊天中的 /model（快速、每会话）
  • openclaw models set ...（仅更新模型配置）
  • openclaw configure --section model（交互式）
  • 在 ~/.openclaw/openclaw.json 中编辑 agents.defaults.model

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

文档：模型、配置、配置、Doctor。

OpenClawFlawd-和-krill-使用什么模型

  • 这些部署可能不同，并且可能随时间变化；没有固定的提供商推荐。
  • 使用 openclaw models status 检查每个 gateway 上的当前运行时设置。
  • 对于安全敏感/启用工具的代理，使用可用的最强最新一代模型。

如何动态切换模型无需重启

使用 /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

你还可以为提供商强制使用特定的 auth profile（每会话）：

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

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

如何使用 profile 设置的取消固定 profile

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

/model anthropic/claude-opus-4-6

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

可以日常任务用-gpt-52-编码用-codex-53-吗

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

  • 快速切换（每会话）： 日常任务使用 /model gpt-5.2，编码使用 /model gpt-5.3-codex。
  • 默认 + 切换： 将 agents.defaults.model.primary 设置为 openai/gpt-5.2，然后在编码时切换到 openai-codex/gpt-5.3-codex（反之亦然）。
  • 子代理： 将编码任务路由到具有不同默认模型的子代理。

请参阅 模型 和 斜杠命令。

为什么我看到-model-is-not-allowed-然后没有回复

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

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

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

为什么我看到-unknown-model-minimaxminimax-m25

这意味着提供商未配置（未找到 MiniMax 提供商配置或 auth profile），所以无法解析模型。2026.1.12 中有一个针对此检测的修复（撰写时未发布）。

修复检查清单：

  1. 升级到2026.1.12（或从源码 main 运行），然后重启 gateway。

  2. 确保配置了 MiniMax（向导或 JSON），或者 env/auth profiles 中存在 MiniMax API 密钥，这样可以注入提供商。

  3. 使用确切的模型 id（区分大小写）：minimax/MiniMax-M2.5 或 minimax/MiniMax-M2.5-highspeed（传统：minimax/MiniMax-M2.5-Lightning）。

  4. 运行：

    openclaw models list

    并从列表中选择（或聊天中的 /model list）。

请参阅 MiniMax 和 模型。

可以默认使用-minimax-复杂任务使用-openai-吗

可以。使用MiniMax 作为默认，在需要时每会话切换模型。回退用于错误，不是"困难任务"，所以使用 /model 或单独的代理。

选项 A：每会话切换

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

然后：

/model gpt

选项 B：独立代理

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

文档：模型、多代理路由、MiniMax、OpenAI。

opus--sonnet--gpt-是内置快捷方式吗

可以。OpenClaw 提供几个默认简写（仅当模型存在于 agents.defaults.models 中时应用）：

  • opus → anthropic/claude-opus-4-6
  • 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-6" },
      models: {
        "anthropic/claude-opus-4-6": { 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-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}

如果引用提供商/模型但缺少所需的提供商密钥，将获得运行时认证错误（例如 No API key found for provider "zai"）。

添加新代理后找不到提供商的 API 密钥

这通常意味着新代理有空的 auth store。Auth 是每代理的，存储在：

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

修复选项：

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

不要在代理之间重用 agentDir；这会导致 auth/session 冲突。

模型故障转移和-all-models-failed

故障转移如何工作

故障转移分两个阶段发生：

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

冷却时间适用于失败的 profiles（指数退避），所以即使提供商被速率限制或暂时失败，OpenClaw 也可以继续响应。

这个错误是什么意思

No credentials found for profile "anthropic:default"

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

修复-no-credentials-found-for-profile-anthropicdefault-的检查清单

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

修复-no-credentials-found-for-profile-anthropic-的检查清单

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

  • 使用 setup-token

    • 运行 claude setup-token，然后用 openclaw models auth setup-token --provider anthropic 粘贴它。
    • 如果令牌是在另一台机器上创建的，使用 openclaw models auth paste-token --provider anthropic。

  • 如果想改用 API 密钥

    • 在gateway 主机上的 ~/.openclaw/.env 中放入 ANTHROPIC_API_KEY。

    • 清除任何强制缺失 profile 的固定顺序：

      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 认证，或在 agents.defaults.model.fallbacks / 别名中删除/避免 Google 模型，这样回退不会路由到那里。

LLM request rejected message thinking signature required google antigravity

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

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

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

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

什么是-auth-profile

Auth profile 是绑定到提供商的命名凭据记录（OAuth 或 API 密钥）。Profiles 生活在：

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

典型的-profile-id-是什么

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

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

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

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

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

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

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

# 将旋转锁定到单个 profile（仅尝试这个）
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-vs-api-key-有什么区别

OpenClaw 支持两者：

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

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

Gateway：端口、"already running" 和远程模式

Gateway 使用什么端口

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

优先级：

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

为什么-openclaw-gateway-status-显示-runtime-running-但-rpc-probe-failed

因为 "running" 是监督器的视图（launchd/systemd/schtasks）。RPC probe 是 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，可选带令牌/密码：

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

说明：

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

Control-ui-显示-unauthorized-或不断重新连接现在怎么办

你的 gateway 运行启用了认证（gateway.auth.*），但 UI 没有发送匹配的令牌/密码。

事实（来自代码）：

  • Control UI 将令牌存储在浏览器 localStorage 键 openclaw.control.settings.v1 中。

修复：

  • 最快：openclaw dashboard（打印 + 复制仪表板 URL，尝试打开；如果无头显示 SSH 提示）。
  • 如果还没有令牌：openclaw doctor --generate-gateway-token。
  • 如果远程，先隧道：ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/。
  • 在 gateway 主机上设置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
  • 在 Control UI 设置中，粘贴相同的令牌。
  • 仍然卡住？运行 openclaw status --all 并遵循 故障排除。有关认证详情，请参阅 仪表板。

我设置了-gatewaybind-tailnet-但无法绑定--没有监听

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

修复：

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

说明：tailnet 是显式的。auto 优先 loopback；当想要 tailnet 专用绑定时使用 gateway.bind: "tailnet"。

可以在同一主机上运行多个-gateways-吗

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

可以，但必须隔离：

  • 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。

配置文件还后缀服务名称（ai.openclaw.<profile>；传统 com.openclaw.*、openclaw-gateway-<profile>.service、OpenClaw Gateway (<profile>)）。 完整指南：多个 gateways。

invalid-handshake--code-1008-是什么意思

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

常见原因：

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

快速修复：

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

如果使用 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/...；配置文件使用 ~/.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

更多信息请参阅 故障排除。

如何启动停止重启-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

常见原因：

  • gateway 主机上未加载模型认证（检查 models status）。
  • 频道配对/允许列表阻止回复（检查频道配置 + 日志）。
  • WebChat/Dashboard 打开时没有正确的令牌。

如果远程，确认隧道/Tailscale 连接已启动，并且 Gateway WebSocket 可达。

文档：频道、故障排除、远程访问。

Disconnected-from-gateway-no-reason-现在怎么办

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

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

然后跟踪日志：

openclaw logs --follow

文档：仪表板、远程访问、故障排除。

Telegram setMyCommands 因网络错误失败应该检查什么

从日志和频道状态开始：

openclaw channels status
openclaw channels logs --channel telegram

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

文档：Telegram、频道故障排除。

TUI 没有输出应该检查什么

首先确认 Gateway 可达且代理可以运行：

openclaw status
openclaw models status
openclaw logs --follow

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

文档：TUI、斜杠命令。

如何完全停止然后启动-gateway

如果安装了服务：

openclaw gateway stop
openclaw gateway start

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

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

openclaw gateway run

文档：Gateway 服务运行手册。

eli5-openclaw-gateway-restart-vs-openclaw-gateway

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

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

当某些东西失败时获取更多细节的最快方法是什么

使用 --verbose 启动 Gateway 以获得更多控制台详情。然后检查日志文件以了解频道认证、模型路由和 RPC 错误。

媒体和附件

我的技能生成了图片pdf-但没有发送

来自代理的出站附件必须包含 MEDIA:<path-or-url> 行（在其自己的行上）。请参阅 OpenClaw 助手设置 和 代理发送。

CLI 发送：

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

还要检查：

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

请参阅 图像。

安全和访问控制

将-openclaw-暴露给入站-dm-安全吗

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

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

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

提示注入只与公共机器人有关吗

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

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

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

详情：安全。

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

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

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

文档：安全、配对。

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

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

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

如果想实验，在专用账户上进行并保持隔离。请参阅 安全。

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

可以，如果代理仅限聊天且输入受信任。较小层级更容易受到指令劫持，所以对启用工具的代理或读取不受信任的内容时避免使用它们。如果必须使用较小的模型，锁定工具并在沙盒内运行。请参阅 安全。

我在-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

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

文档：思考和 verbose、安全。

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

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

stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt

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

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

process action:kill sessionId:XXX

斜杠命令概述：请参阅 斜杠命令。

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

如何从-telegram-发送-discord-消息cross-context-messaging-denied

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

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

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

编辑配置后重启 gateway。如果只想为单个代理使用这个，在 agents.list[].tools.message 下设置。

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

队列模式控制新消息如何与进行中的运行交互。使用 /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-6）。如果看到 No credentials found for profile "anthropic:default"，这意味着 Gateway 在运行的代理的预期 auth-profiles.json 中找不到 Anthropic 凭据。

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