快速解答及针对实际部署场景（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）的深入故障排除。运行时诊断请参阅故障排除。完整配置参考请参阅配置。
HTTP 429: rate_limit_error（来自 Anthropic）？allowFrom 填什么？/new，会话会自动重置吗？openclaw gateway status 显示 Runtime: running 但 RPC probe: failed？openclaw gateway status 显示 Config (cli) 和 Config (service) 不同？gateway.bind: "tailnet" 但无法绑定 / 什么都没监听快速状态（首先检查）
openclaw status
快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（Gateway 网关可达时）。
可粘贴的报告（可安全分享）
openclaw status --all
只读诊断，附带日志尾部（令牌已脱敏）。
守护进程 + 端口状态
openclaw gateway status
显示 supervisor 运行状态与 RPC 可达性、探测目标 URL，以及服务可能使用的配置。
深度探测
openclaw status --deep
运行 Gateway 网关健康检查 + 提供商探测（需要可达的 Gateway 网关）。参阅健康检查。
跟踪最新日志
openclaw logs --follow
如果 RPC 不可用，回退到：
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
运行 doctor（修复）
openclaw doctor
修复/迁移配置/状态 + 运行健康检查。参阅 Doctor。
Gateway 网关快照
openclaw health --json
openclaw health --verbose # 出错时显示目标 URL + 配置路径
向运行中的 Gateway 网关请求完整快照（仅 WS）。参阅健康检查。
使用能看到你机器的本地 AI 智能体。这比在 Discord 上提问有效得多，因为大多数“卡住了”的情况都是本地配置或环境问题，远程帮助者无法检查。
这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级别设置（PATH、服务、权限、认证文件）。通过可编辑（git）安装提供完整源代码：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
这会从 git checkout 安装 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：Gateway 网关/智能体健康状况 + 基本配置的快速快照。openclaw models status：检查提供商认证 + 模型可用性。openclaw doctor：验证并修复常见的配置/状态问题。其他有用的 CLI 检查：openclaw status --all、openclaw logs --follow、
openclaw gateway status、openclaw health --verbose。
快速调试流程：出问题后的最初六十秒。 安装文档：安装、安装程序标志、更新。
仓库推荐从源码运行并使用新手引导：
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。令牌保持在本地主机上，不会从浏览器获取任何内容。
本地（同一台机器）：
http://127.0.0.1:18789/。openclaw dashboard 并使用带令牌的链接（?token=...）。gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）的值相同，UI 在首次加载后会存储它。非本地环境：
openclaw gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，身份标头满足认证要求（无需令牌）。openclaw gateway --bind tailnet --token "<token>"，打开 http://<tailscale-ip>:18789/，在仪表板设置中粘贴令牌。ssh -N -L 18789:127.0.0.1:18789 user@host，然后从 openclaw dashboard 打开 http://127.0.0.1:18789/?token=...。Node >= 22 是必需的。推荐使用 pnpm。不推荐使用 Bun 运行 Gateway 网关。
可以。Gateway 网关是轻量级的——文档列出 512MB-1GB RAM、1 核和约 500MB 磁盘空间足够个人使用，并指出 Raspberry Pi 4 可以运行。
如果你需要额外的余量（日志、媒体、其他服务），推荐 2GB，但这不是硬性最低要求。
提示：小型 Pi/VPS 可以托管 Gateway 网关，你可以在笔记本/手机上配对节点以获取本地屏幕/摄像头/画布或命令执行能力。参阅节点。
简短回答：可以运行，但预期会有一些粗糙之处。
该界面依赖于 Gateway 网关可达且已认证。TUI 也会在首次启动时自动发送"Wake up, my friend!"。如果你看到该行但没有回复且令牌保持为 0，说明智能体从未运行。
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --follow
openclaw doctor
如果 Gateway 网关在远程，确保隧道/Tailscale 连接正常，且 UI 指向正确的 Gateway 网关。参阅远程访问。
可以。复制状态目录和工作区，然后运行一次 Doctor。只要你同时复制两个位置，就能保持你的机器人“完全一样”（记忆、会话历史、认证和渠道状态）：
$OPENCLAW_STATE_DIR（默认：~/.openclaw）。~/.openclaw/workspace）。openclaw doctor 并重启 Gateway 网关服务。这会保留配置、认证配置文件、WhatsApp 凭据、会话和记忆。如果你处于远程模式，请记住 Gateway 网关主机拥有会话存储和工作区。
重要： 如果你只将工作区提交/推送到 GitHub，你只备份了记忆 + 引导文件，但不包括会话历史或认证。它们位于 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/sessions/）。
相关：迁移、磁盘上的文件位置、 智能体工作区、Doctor、 远程模式。
查看 GitHub 变更日志： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
最新条目在顶部。如果顶部部分标记为 Unreleased，则下一个带日期的部分是最新发布版本。条目按亮点、变更和修复分组（需要时还有文档/其他部分）。
一些 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 是 npm dist-tags，不是独立的代码分支：
latest = stablebeta = 用于测试的早期构建我们将构建发布到 beta，测试后，一旦构建稳定，就会将同一版本提升为 latest。这就是为什么 beta 和 stable 可以指向相同版本。
查看变更： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
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
大致指南：
两个选项：
openclaw update --channel dev
这会切换到 main 分支并从源码更新。
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
这会给你一个可编辑的本地仓库，然后通过 git 更新。
如果你更喜欢手动克隆，使用：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
使用详细输出重新运行安装程序：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
带详细输出的 Beta 安装：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
可编辑（git）安装：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
更多选项：安装程序标志。
两个常见的 Windows 问题：
1) npm error spawn git / git not found
git 在你的 PATH 中。2) openclaw is not recognized（安装后）
npm config get prefix
<prefix>\\bin 在 PATH 中（在大多数系统上是 %AppData%\\npm）。如果你想要最顺畅的 Windows 设置，请使用 WSL2 而不是原生 Windows。 文档：Windows。
使用可编辑（git）安装，这样你在本地拥有完整的源码和文档，然后从该文件夹向你的机器人（或 Claude/Codex）提问，这样它可以读取仓库并精确回答。
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
简短回答：按照 Linux 指南操作，然后运行新手引导。
任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。
指南：exe.dev、Hetzner、Fly.io。 远程访问：Gateway 网关远程。
我们维护了一个托管中心，涵盖常见提供商。选择一个并按指南操作：
在云端的工作方式：Gateway 网关运行在服务器上，你通过控制 UI（或 Tailscale/SSH）从笔记本/手机访问。你的状态 + 工作区位于服务器上，因此将主机视为数据来源并做好备份。
你可以将节点（Mac/iOS/Android/无头）配对到云端 Gateway 网关，以访问本地屏幕/摄像头/画布或在笔记本上执行命令，同时 Gateway 网关保持在云端。
中心：平台。远程访问：Gateway 网关远程。 节点：节点、节点 CLI。
简短回答：可以，但不推荐。更新流程可能重启 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 是推荐的设置路径。在本地模式下，它引导你完成：
如果你配置的模型未知或缺少认证，它还会发出警告。
不需要。你可以使用 API 密钥（Anthropic/OpenAI/其他）或纯本地模型运行 OpenClaw，这样你的数据留在你的设备上。订阅（Claude Pro/Max 或 OpenAI Codex）是这些提供商的可选认证方式。
可以。你可以使用 setup-token 代替 API 密钥进行认证。这是订阅路径。
Claude Pro/Max 订阅不包含 API 密钥，因此这是订阅账户的正确方式。重要提示：你必须向 Anthropic 确认此用法是否符合其订阅政策和条款。如果你想要最明确、受支持的方式，请使用 Anthropic API 密钥。
claude setup-token 通过 Claude Code CLI 生成一个令牌字符串（在 Web 控制台中不可用）。你可以在任何机器上运行它。在新手引导中选择 Anthropic token (paste setup-token) 或使用 openclaw models auth paste-token --provider anthropic 粘贴。令牌作为 anthropic 提供商的认证配置文件存储，像 API 密钥一样使用（无自动刷新）。更多详情：OAuth。
它不在 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。
是的——通过 setup-token。OpenClaw 不再复用 Claude Code CLI OAuth 令牌；请使用 setup-token 或 Anthropic API 密钥。在任何地方生成令牌并在 Gateway 网关主机上粘贴。参阅 Anthropic 和 OAuth。
注意：Claude 订阅访问受 Anthropic 条款约束。对于生产或多用户工作负载，API 密钥通常是更安全的选择。
这意味着你当前窗口的 Anthropic 配额/速率限制已耗尽。如果你使用 Claude 订阅（setup-token 或 Claude Code OAuth），请等待窗口重置或升级你的计划。如果你使用 Anthropic API 密钥，请在 Anthropic Console 中检查使用量/计费并根据需要提高限制。
提示：设置一个备用模型，这样 OpenClaw 在某个提供商被限速时仍能继续回复。 参阅模型和 OAuth。
是的——通过 pi-ai 的 Amazon Bedrock (Converse) 提供商进行手动配置。你必须在 Gateway 网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参阅 Amazon Bedrock 和模型提供商。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是有效选项。
OpenClaw 通过 OAuth（ChatGPT 登录）支持 OpenAI Code (Codex)。新手引导可以运行 OAuth 流程，并在适当时将默认模型设置为 openai-codex/gpt-5.2。参阅模型提供商和CLI 新手引导。
是的。OpenClaw 完全支持 OpenAI Code (Codex) 订阅 OAuth。新手引导可以为你运行 OAuth 流程。
Gemini CLI 使用插件认证流程，而不是 openclaw.json 中的 client id 或 secret。
步骤：
openclaw plugins enable googleopenclaw models auth login --provider google-gemini-cli --set-default这会在 Gateway 网关主机上将 OAuth 令牌存储为认证配置文件。详情：模型提供商。
通常不适合。OpenClaw 需要大上下文 + 强安全性；小显卡会截断且泄漏。如果必须使用，请在本地运行你能运行的最大 MiniMax M2.1 版本（LM Studio），参阅 /gateway/local-models。较小/量化的模型会增加提示注入风险——参阅安全。
选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体以保持数据在区域内。你仍然可以通过使用 models.mode: "merge" 在这些旁边列出 Anthropic/OpenAI，这样故障转移保持可用，同时尊重你选择的区域提供商。
不需要。OpenClaw 运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人买一台作为常开主机，但小型 VPS、家庭服务器或 Raspberry Pi 级别的设备也可以。
你只有在使用 macOS 专用工具时才需要 Mac。对于 iMessage，你可以将 Gateway 网关保持在 Linux 上，通过将 channels.imessage.cliPath 指向 SSH 包装器在任何 Mac 上运行 imsg。如果你需要其他 macOS 专用工具，在 Mac 上运行 Gateway 网关或配对一个 macOS 节点。
你需要某台登录了 Messages 的 macOS 设备。它不一定是 Mac mini——任何 Mac 都可以。OpenClaw 的 iMessage 集成在 macOS 上运行（BlueBubbles 或 imsg），而 Gateway 网关可以在其他地方运行。
常见设置：
channels.imessage.cliPath 指向在 Mac 上运行 imsg 的 SSH 包装器。文档：iMessage、BlueBubbles、 Mac 远程模式。
可以。Mac mini 可以运行 Gateway 网关，你的 MacBook Pro 可以作为节点（伴随设备）连接。节点不运行 Gateway 网关——它们提供额外功能，如该设备上的屏幕/摄像头/画布和 system.run。
常见模式：
openclaw nodes status / openclaw nodes list 查看它。Bun 不推荐。我们观察到运行时 bug，特别是在 WhatsApp 和 Telegram 方面。 使用 Node 以获得稳定的 Gateway 网关。
如果你仍想尝试 Bun，请在没有 WhatsApp/Telegram 的非生产 Gateway 网关上进行。
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 发私信。可以，通过多智能体路由。将每个发送者的 WhatsApp 私信（peer kind: "dm"，发送者 E.164 格式如 +15551234567）绑定到不同的 agentId，这样每个人获得自己的工作区和会话存储。回复仍然来自同一个 WhatsApp 账户，且私信访问控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）对每个 WhatsApp 账户是全局的。参阅多智能体路由和 WhatsApp。
可以。使用多智能体路由：为每个智能体设置自己的默认模型，然后将入站路由（提供商账户或特定对等方）绑定到每个智能体。示例配置位于多智能体路由。另参阅模型和配置。
可以。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。
可以。安装另一种方式，然后运行 Doctor 使 Gateway 网关服务指向新的入口点。
这不会删除你的数据——它只改变 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 会检测 Gateway 网关服务入口点不匹配，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 --repair）。
备份提示：参阅备份策略。
笔记本（本地 Gateway 网关）
VPS / 云
OpenClaw 特定说明： WhatsApp/Telegram/Slack/Mattermost（插件）/Discord 在 VPS 上都能正常工作。唯一的真正权衡是无头浏览器与可见窗口。参阅浏览器。
推荐默认值： 如果之前遇到过 Gateway 网关断连，使用 VPS。当你正在积极使用 Mac 并且需要本地文件访问或可见浏览器的 UI 自动化时，本地运行很好。
不是必需的，但推荐用于可靠性和隔离。
如果你想要两全其美，将 Gateway 网关保持在专用主机上，并将笔记本配对为节点以获取本地屏幕/摄像头/执行工具。参阅节点。 安全指南请阅读安全。
OpenClaw 是轻量级的。对于基本的 Gateway 网关 + 一个聊天渠道：
操作系统：使用 Ubuntu LTS（或任何现代 Debian/Ubuntu）。Linux 安装路径在那里测试得最充分。
可以。将虚拟机视为与 VPS 相同：它需要常开、可达，并有足够的 RAM 用于 Gateway 网关和你启用的任何渠道。
基准指南：
如果你使用 Windows，WSL2 是最简单的虚拟机式设置，具有最佳的工具兼容性。参阅 Windows、VPS 托管。 如果你在虚拟机中运行 macOS，参阅 macOS VM。
OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它在你已经使用的消息平台上回复（WhatsApp、Telegram、Slack、Mattermost（插件）、Discord、Google Chat、Signal、iMessage、WebChat），还可以在支持的平台上进行语音和实时 Canvas。Gateway 网关 是常开的控制平面；助手是产品。
OpenClaw 不是“只是一个 Claude 包装器”。它是一个本地优先的控制平面，让你在自己的硬件上运行强大的助手，可从你已经使用的聊天应用访问，具有有状态会话、记忆和工具——无需将工作流程的控制权交给托管 SaaS。
亮点：
文档：Gateway 网关、渠道、多智能体、 记忆。
好的入门项目：
它可以处理大型任务，但最好将其拆分为多个阶段，并使用子智能体进行并行工作。
日常收益通常包括：
可以用于调研、筛选和起草。它可以扫描网站、建立候选名单、总结潜在客户，并撰写外联或广告文案草稿。
对于外联或广告投放，请保持人工审核。避免垃圾邮件，遵守当地法律和平台政策，在发送之前审查所有内容。最安全的模式是让 OpenClaw 起草，由你批准。
文档：安全。
OpenClaw 是一个个人助手和协调层，不是 IDE 替代品。使用 Claude Code 或 Codex 在仓库中进行最快的直接编码循环。当你需要持久记忆、跨设备访问和工具编排时，使用 OpenClaw。
优势：
展示：https://openclaw.ai/showcase
使用托管覆盖而不是编辑仓库副本。将你的更改放在 ~/.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。clawhub 默认安装到 ./skills，OpenClaw 将其视为 <workspace>/skills。
目前支持的模式有：
model 覆盖。/model 随时切换当前会话模型。使用子智能体处理长时间或并行任务。子智能体在自己的会话中运行，返回摘要，并保持你的主聊天响应。
要求你的机器人“为这个任务生成一个子智能体”或使用 /subagents。
在聊天中使用 /status 查看 Gateway 网关当前正在做什么（以及是否忙碌）。
令牌提示：长任务和子智能体都消耗令牌。如果关注成本，通过 agents.defaults.subagents.model 为子智能体设置更便宜的模型。
文档：子智能体。
定时任务在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行，计划任务将不会运行。
检查清单：
cron.enabled）且未设置 OPENCLAW_SKIP_CRON。--tz 与主机时区）。调试：
openclaw cron run <jobId> --force
openclaw cron runs --id <jobId> --limit 50
文档：定时任务、定时任务 vs 心跳。
使用 ClawHub（CLI）或将 Skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。 浏览 Skills：https://clawhub.com。
安装 ClawHub CLI（选择一个包管理器）：
npm i -g clawhub
pnpm add -g clawhub
可以。使用 Gateway 网关调度器：
文档：定时任务、定时任务 vs 心跳、 心跳。
能否从 Linux 运行仅限 Apple/macOS 的 Skills
不能直接运行。macOS Skills 受 metadata.openclaw.os 和所需二进制文件限制，Skills 只有在 Gateway 网关主机上符合条件时才会出现在系统提示中。在 Linux 上，darwin 专用 Skills（如 apple-notes、apple-reminders、things-mac）不会加载，除非你覆盖限制。
你有三种支持的模式：
方案 A - 在 Mac 上运行 Gateway 网关（最简单）。 在 macOS 二进制文件所在的地方运行 Gateway 网关，然后从 Linux 通过远程模式或 Tailscale 连接。Skills 正常加载，因为 Gateway 网关主机是 macOS。
方案 B - 使用 macOS 节点（无需 SSH）。
在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将节点运行命令设置为“始终询问”或“始终允许”。当所需二进制文件存在于节点上时，OpenClaw 可以将 macOS 专用 Skills 视为符合条件。智能体通过 nodes 工具运行这些 Skills。如果你选择“始终询问”，在提示中批准“始终允许”会将该命令添加到允许列表。
方案 C - 通过 SSH 代理 macOS 二进制文件（高级）。 保持 Gateway 网关在 Linux 上，但使所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skills 以允许 Linux 使其保持符合条件。
imsg）：#!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"
PATH 上（例如 ~/bin/imsg）。~/.openclaw/skills）以允许 Linux：---
name: imsg
description: iMessage/SMS CLI for listing chats, history, watch, and sending.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["imsg"] } } }
---
对于 iMessage，你也可以将 channels.imessage.cliPath 指向 SSH 包装器（OpenClaw 只需要 stdio）。参阅 iMessage。
目前没有内置集成。
选项：
如果你想按客户保留上下文（代理工作流），一个简单的模式是：
如果你想要原生集成，请提交功能请求或构建一个针对这些 API 的 Skills。
安装 Skills：
clawhub install <skill-slug>
clawhub update --all
ClawHub 安装到当前目录下的 ./skills（或回退到你配置的 OpenClaw 工作区）；OpenClaw 在下一个会话中将其视为 <workspace>/skills。对于跨智能体共享的 Skills，将它们放在 ~/.openclaw/skills/<name>/SKILL.md。某些 Skills 期望通过 Homebrew 安装二进制文件；在 Linux 上意味着 Linuxbrew（参阅上面的 Homebrew Linux 常见问题条目）。参阅Skills和 ClawHub。
使用内置安装程序，然后在 Chrome 中加载未打包的扩展：
openclaw browser extension install
openclaw browser extension path
然后 Chrome → chrome://extensions → 启用“开发者模式” → “加载已解压的扩展程序” → 选择该文件夹。
完整指南（包括远程 Gateway 网关 + 安全注意事项）：Chrome 扩展
如果 Gateway 网关运行在与 Chrome 同一台机器上（默认设置），你通常不需要额外配置。 如果 Gateway 网关运行在其他地方，在运行浏览器的机器上运行一个节点主机，以便 Gateway 网关可以代理浏览器操作。 你仍然需要在要控制的标签页上点击扩展按钮（它不会自动附加）。
有。参阅沙箱。对于 Docker 特定设置（完整 Gateway 网关在 Docker 中或沙箱镜像），参阅 Docker。
能否让私信保持私密，但群组用一个智能体公开沙箱隔离
可以——如果你的私密流量是私信而公开流量是群组。
使用 agents.defaults.sandbox.mode: "non-main"，这样群组/频道会话（非主键）在 Docker 中运行，而主私信会话保持在主机上。然后通过 tools.sandbox.tools 限制沙箱会话中可用的工具。
设置指南 + 示例配置：群组：个人私信 + 公开群组
关键配置参考：Gateway 网关配置
将 agents.defaults.sandbox.docker.binds 设置为 ["host:path:mode"]（例如 "/home/user/src:/src:ro"）。全局 + 按智能体的绑定会合并；当 scope: "shared" 时按智能体的绑定会被忽略。对于敏感内容使用 :ro，并记住绑定会绕过沙箱文件系统隔离。参阅沙箱和沙箱 vs 工具策略 vs 提权了解示例和安全注意事项。
OpenClaw 记忆就是智能体工作区中的 Markdown 文件：
memory/YYYY-MM-DD.mdMEMORY.md（仅限主/私密会话）OpenClaw 还会运行静默的预压缩记忆刷新，以提醒模型在自动压缩之前写入持久笔记。这只在工作区可写时运行（只读沙箱会跳过）。参阅记忆。
要求机器人将事实写入记忆。长期笔记属于 MEMORY.md，短期上下文放入 memory/YYYY-MM-DD.md。
这仍然是我们正在改进的领域。提醒模型存储记忆会有帮助；它会知道如何操作。如果它持续遗忘，验证 Gateway 网关每次运行时是否使用相同的工作区。
只有在使用 OpenAI embeddings 时才需要。Codex OAuth 覆盖 chat/completions 但不授予 embeddings 访问权限，因此使用 Codex 登录（OAuth 或 Codex CLI 登录）对语义记忆搜索没有帮助。OpenAI embeddings 仍然需要真正的 API 密钥（OPENAI_API_KEY 或 models.providers.openai.apiKey）。
如果你没有明确设置提供商，OpenClaw 会在能解析 API 密钥（认证配置文件、models.providers.*.apiKey 或环境变量）时自动选择提供商。如果 OpenAI 密钥可解析则优先使用 OpenAI，否则如果 Gemini 密钥可解析则使用 Gemini。如果两个密钥都不可用，记忆搜索保持禁用直到你配置它。如果你配置了本地模型路径且存在，OpenClaw 优先使用 local。
如果你更想保持本地运行，设置 memorySearch.provider = "local"（可选 memorySearch.fallback = "none"）。如果你想使用 Gemini embeddings，设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini 或本地 embedding 模型——参阅记忆了解设置详情。
记忆文件保存在磁盘上，持久存在直到你删除它们。限制是你的存储空间，而不是模型。会话上下文仍然受模型上下文窗口限制，所以长对话可能会压缩或截断。这就是记忆搜索存在的原因——它只将相关部分拉回上下文。
不是——OpenClaw 的状态是本地的，但外部服务仍然会看到你发送给它们的内容。
~/.openclaw + 你的工作区目录）。所有内容位于 $OPENCLAW_STATE_DIR（默认：~/.openclaw）下：
| 路径 | 用途 |
| --------------------------------------------------------------- | ---------------------------------------------------- |
| $OPENCLAW_STATE_DIR/openclaw.json | 主配置（JSON5） |
| $OPENCLAW_STATE_DIR/credentials/oauth.json | 旧版 OAuth 导入（首次使用时复制到认证配置文件） |
| $OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json | 认证配置文件（OAuth + API 密钥） |
| $OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json | 运行时认证缓存（自动管理） |
| $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、记忆文件、Skills 等）是独立的，通过 agents.defaults.workspace 配置（默认：~/.openclaw/workspace）。
这些文件位于智能体工作区中，而不是 ~/.openclaw。
AGENTS.md、SOUL.md、IDENTITY.md、USER.md、
MEMORY.md（或 memory.md）、memory/YYYY-MM-DD.md、可选的 HEARTBEAT.md。~/.openclaw）：配置、凭据、认证配置文件、会话、日志和共享 Skills（~/.openclaw/skills）。默认工作区是 ~/.openclaw/workspace，可通过以下方式配置：
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}
如果机器人在重启后“忘记”了内容，确认 Gateway 网关每次启动时都使用相同的工作区（记住：远程模式使用 Gateway 网关主机的工作区，而不是你本地笔记本的）。
提示：如果你想要一个持久的行为或偏好，要求机器人将其写入 AGENTS.md 或 MEMORY.md，而不是依赖聊天历史。
将你的智能体工作区放入一个私有 git 仓库，并备份到某个私有位置（例如 GitHub 私有仓库）。这会捕获记忆 + AGENTS/SOUL/USER 文件，让你以后可以恢复助手的“思维”。
不要提交 ~/.openclaw 下的任何内容（凭据、会话、令牌）。如果你需要完整恢复，将工作区和状态目录分别备份（参阅上面的迁移问题）。
文档：智能体工作区。
参阅专门指南：卸载。
可以。工作区是默认 cwd 和记忆锚点，不是硬沙箱。相对路径在工作区内解析，但绝对路径可以访问其他主机位置，除非启用了沙箱。如果你需要隔离，使用 agents.defaults.sandbox 或按智能体的沙箱设置。如果你希望某个仓库作为默认工作目录，将该智能体的 workspace 指向仓库根目录。OpenClaw 仓库只是源代码；除非你有意要让智能体在其中工作，否则保持工作区独立。
示例（仓库作为默认 cwd）：
{
agents: {
defaults: {
workspace: "~/Projects/my-repo",
},
},
}
会话状态归 Gateway 网关主机所有。如果你处于远程模式，你关心的会话存储在远程机器上，而不是你的本地笔记本上。参阅会话管理。
OpenClaw 从 $OPENCLAW_CONFIG_PATH（默认：~/.openclaw/openclaw.json）读取可选的 JSON5 配置：
$OPENCLAW_CONFIG_PATH
如果文件不存在，使用安全的默认值（包括默认工作区 ~/.openclaw/workspace）。
非 local loopback 绑定需要认证。配置 gateway.auth.mode + gateway.auth.token（或使用 OPENCLAW_GATEWAY_TOKEN）。
{
gateway: {
bind: "lan",
auth: {
mode: "token",
token: "replace-me",
},
},
}
注意：
gateway.remote.token 仅用于远程 CLI 调用；它不启用本地 Gateway 网关认证。connect.params.auth.token（存储在应用/UI 设置中）进行认证。避免将令牌放在 URL 中。向导默认生成 Gateway 网关令牌（即使在 local loopback 上），因此本地 WS 客户端必须认证。这阻止了其他本地进程调用 Gateway 网关。在控制 UI 设置（或你的客户端配置）中粘贴令牌以连接。
如果你确实想要开放 local loopback，从配置中移除 gateway.auth。Doctor 可以随时为你生成令牌：openclaw doctor --generate-gateway-token。
Gateway 网关监视配置文件并支持热重载：
gateway.reload.mode: "hybrid"（默认）：安全更改热应用，关键更改重启hot、restart、offweb_fetch 无需 API 密钥即可工作。web_search 需要所选提供商的 API 密钥。推荐： 运行 openclaw configure --section web。新的提供商专属配置会存储在 plugins.entries.<plugin>.config.webSearch.* 下。环境变量替代方案：为 Gateway 网关进程设置相应的提供商环境变量。
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "brave",
maxResults: 5,
},
fetch: {
enabled: true,
},
},
},
}
注意：
web_search/web_fetch 或 group:web。web_fetch 默认启用（除非明确禁用）。~/.openclaw/.env（或服务环境）读取环境变量。tools.web.search.* 提供商路径仍通过兼容层继续生效，但不应再用于新配置。文档：Web 工具。
config.apply 替换整个配置。如果你发送部分对象，其他所有内容都会被移除。
恢复：
~/.openclaw/openclaw.json）。openclaw doctor 并重新配置渠道/模型。避免方法：
openclaw config set。openclaw configure。常见模式是一个 Gateway 网关（例如 Raspberry Pi）加上节点和智能体：
system.run、canvas、camera）。可以。这是一个配置选项：
{
browser: { headless: true },
agents: {
defaults: {
sandbox: { browser: { headless: true } },
},
},
}
默认为 false（有头）。无头模式在某些网站上更容易触发反机器人检测。参阅浏览器。
无头模式使用相同的 Chromium 引擎，适用于大多数自动化（表单、点击、抓取、登录）。主要区别：
将 browser.executablePath 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器）并重启 Gateway 网关。
参阅浏览器中的完整配置示例。
Telegram 消息由 Gateway 网关 处理。Gateway 网关运行智能体，只有在需要节点工具时才通过 Gateway 网关 WebSocket 调用节点：
Telegram → Gateway 网关 → 智能体 → node.* → 节点 → Gateway 网关 → Telegram
节点不会看到入站提供商流量；它们只接收节点 RPC 调用。
简短回答：将你的电脑配对为节点。Gateway 网关运行在其他地方，但它可以通过 Gateway 网关 WebSocket 在你的本地机器上调用 node.* 工具（屏幕、摄像头、系统）。
典型设置：
openclaw nodes pending
openclaw nodes approve <requestId>
不需要单独的 TCP 桥接；节点通过 Gateway 网关 WebSocket 连接。
安全提醒：配对 macOS 节点允许在该机器上执行 system.run。只配对你信任的设备，并查阅安全。
文档：节点、Gateway 网关协议、macOS 远程模式、安全。
检查基础项：
openclaw gateway statusopenclaw statusopenclaw channels status然后验证认证和路由：
gateway.auth.allowTailscale 设置正确。可以。没有内置的“机器人对机器人”桥接，但你可以通过几种可靠的方式实现：
最简单： 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。让机器人 A 给机器人 B 发消息，然后让机器人 B 正常回复。
CLI 桥接（通用）： 运行一个脚本调用另一个 Gateway 网关，使用 openclaw agent --message ... --deliver，定向到另一个机器人监听的聊天。如果一个机器人在远程 VPS 上，通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关（参阅远程访问）。
示例模式（从能到达目标 Gateway 网关的机器上运行）：
openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>
提示：添加护栏防止两个机器人无限循环（仅提及、渠道允许列表或“不回复机器人消息”规则）。
文档：远程访问、Agent CLI、Agent send。
不需要。一个 Gateway 网关可以托管多个智能体，每个都有自己的工作区、模型默认值和路由。这是正常设置，比每个智能体一个 VPS 便宜且简单得多。
只有在需要硬隔离（安全边界）或非常不同的配置（你不想共享）时才使用独立的 VPS。否则保持一个 Gateway 网关并使用多个智能体或子智能体。
有——节点是从远程 Gateway 网关到达你笔记本的首选方式，它们解锁的不仅仅是 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 通过 WSL2）上且是轻量级的（小型 VPS 或 Raspberry Pi 级别的设备就够用；4 GB RAM 足够），所以常见设置是一个常开主机加上你的笔记本作为节点。
system.run 受该笔记本上节点允许列表/审批的限制。system.run 还暴露 canvas、camera 和 screen。SSH 对临时 shell 访问很好，但节点对于持续的智能体工作流和设备自动化更简单。
如果你只需要第二台笔记本上的本地工具（屏幕/摄像头/执行），将其添加为节点。这保持单一 Gateway 网关并避免重复配置。本地节点工具目前仅限 macOS，但我们计划扩展到其他操作系统。
只有在需要硬隔离或两个完全独立的机器人时才安装第二个 Gateway 网关。
文档：节点、节点 CLI、多 Gateway 网关。
不会。每台主机上应该只运行一个 Gateway 网关，除非你有意运行隔离的配置文件（参阅多 Gateway 网关）。节点是连接到 Gateway 网关的外围设备（iOS/Android 节点，或 macOS 菜单栏应用的“节点模式”）。对于无头节点主机和 CLI 控制，参阅节点主机 CLI。
gateway、discovery 和 canvasHost 的更改需要完全重启。
有。config.apply 验证 + 写入完整配置，并在操作过程中重启 Gateway 网关。
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
这设置了你的工作区并限制谁可以触发机器人。
最简步骤：
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
ssh user@your-vps.tailnet-xxxx.ts.netws://your-vps.tailnet-xxxx.ts.net:18789如果你想要无 SSH 的控制 UI，在 VPS 上使用 Tailscale Serve：
openclaw gateway --tailscale serve
这保持 Gateway 网关绑定到 local loopback 并通过 Tailscale 暴露 HTTPS。参阅 Tailscale。
Serve 暴露 Gateway 网关控制 UI + WS。节点通过同一个 Gateway 网关 WS 端点连接。
推荐设置：
openclaw nodes pending
openclaw nodes approve <requestId>
文档：Gateway 网关协议、发现、macOS 远程模式。
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 了解优先级和来源详情。
两个常见修复方法：
~/.openclaw/.env 中，这样即使服务不继承你的 shell 环境也能被获取。{
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000,
},
},
}
这会运行你的登录 shell 并仅导入缺失的预期键名（从不覆盖）。环境变量等效项：
OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。
openclaw models status 报告的是 shell 环境导入是否启用。"Shell env: off"不意味着你的环境变量缺失——它只意味着 OpenClaw 不会自动加载你的登录 shell。
如果 Gateway 网关作为服务（launchd/systemd）运行，它不会继承你的 shell 环境。通过以下方式之一修复：
~/.openclaw/.env 中：COPILOT_GITHUB_TOKEN=...
env.shellEnv.enabled: true）。env 块中（仅在缺失时应用）。然后重启 Gateway 网关并重新检查：
openclaw models status
Copilot 令牌从 COPILOT_GITHUB_TOKEN 读取（也支持 GH_TOKEN / GITHUB_TOKEN）。
参阅 /concepts/model-providers 和 /environment。
发送 /new 或 /reset 作为独立消息。参阅会话管理。
会。会话在 session.idleMinutes（默认 60）后过期。下一条消息会为该聊天键开始一个新的会话 ID。这不会删除记录——只是开始一个新会话。
{
session: {
idleMinutes: 240,
},
}
可以，通过多智能体路由和子智能体。你可以创建一个协调器智能体和多个工作者智能体，每个都有自己的工作区和模型。
话虽如此，最好将其视为一个有趣的实验。它消耗大量令牌，通常不如使用一个机器人配合不同会话的效率高。我们设想的典型模型是一个你与之对话的机器人，用不同的会话进行并行工作。该机器人也可以在需要时生成子智能体。
会话上下文受模型窗口限制。长对话、大量工具输出或许多文件可能触发压缩或截断。
有帮助的做法：
/compact，切换话题时使用 /new。使用重置命令：
openclaw reset
非交互式完整重置：
openclaw reset --scope full --yes --non-interactive
然后重新运行新手引导：
openclaw onboard --install-daemon
注意：
--profile / OPENCLAW_PROFILE），重置每个状态目录（默认为 ~/.openclaw-<profile>）。openclaw gateway --dev --reset（仅限开发；清除开发配置 + 凭据 + 会话 + 工作区）。使用以下方式之一：
压缩（保留对话但总结较早的轮次）：
/compact
或 /compact <instructions> 来引导总结。
重置（为同一聊天键开始新的会话 ID）：
/new
/reset
如果持续出现：
agents.defaults.contextPruning）以裁剪旧的工具输出。这是一个提供商验证错误：模型发出了一个没有必需 input 的 tool_use 块。通常意味着会话历史已过时或损坏（通常在长线程或工具/模式变更后发生）。
修复：使用 /new（独立消息）开始新会话。
心跳默认每 30 分钟运行一次。调整或禁用：
{
agents: {
defaults: {
heartbeat: {
every: "2h", // 或 "0m" 禁用
},
},
},
}
如果 HEARTBEAT.md 存在但实际上为空（只有空行和 markdown 标题如 # Heading），OpenClaw 会跳过心跳运行以节省 API 调用。如果文件不存在，心跳仍然运行，由模型决定做什么。
按智能体覆盖使用 agents.list[].heartbeat。文档：心跳。
不需要。OpenClaw 运行在你自己的账户上，所以如果你在群组中，OpenClaw 就能看到它。
默认情况下，群组回复被阻止，直到你允许发送者（groupPolicy: "allowlist"）。
如果你只想你自己能触发群组回复：
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
方法 1（最快）：跟踪日志并在群组中发送测试消息：
openclaw logs --follow --json
查找以 @g.us 结尾的 chatId（或 from），如：
1234567890-1234567890@g.us。
方法 2（如果已配置/加入允许列表）：从配置中列出群组：
openclaw directory groups list --channel whatsapp
两个常见原因：
mentionPatterns）。channels.whatsapp.groups 但没有 "*" 且该群组未加入允许列表。直接聊天默认折叠到主会话。群组/频道有自己的会话键，Telegram 话题 / Discord 线程是独立的会话。参阅群组和群组消息。
没有硬性限制。几十个（甚至几百个）都没问题，但请注意：
~/.openclaw/agents/<agentId>/sessions/ 下。提示：
agents.defaults.workspace）。openclaw doctor 发现无用的工作区和配置文件不匹配。可以。使用多智能体路由运行多个隔离的智能体，并按渠道/账户/对等方路由入站消息。Slack 作为渠道受支持，可以绑定到特定智能体。
浏览器访问功能强大，但不是“能做人类能做的一切”——反机器人、验证码和 MFA 仍然可以阻止自动化。为了最可靠的浏览器控制，在运行浏览器的机器上使用 Chrome 扩展中继（Gateway 网关可以在任何地方）。
最佳实践设置：
文档：多智能体路由、Slack、 浏览器、Chrome 扩展、节点。
OpenClaw 的默认模型是你设置的：
agents.defaults.model.primary
模型以 provider/model 引用（示例：anthropic/claude-opus-4-5）。如果你省略提供商，OpenClaw 目前假设 anthropic 作为临时弃用回退——但你仍然应该明确设置 provider/model。
推荐默认： anthropic/claude-opus-4-5。
好的替代： anthropic/claude-sonnet-4-5。
可靠（个性较少）： openai/gpt-5.2——几乎和 Opus 一样好，只是个性较少。
经济： zai/glm-4.7。
MiniMax M2.1 有自己的文档：MiniMax 和 本地模型。
经验法则：高风险工作使用你能负担的最好的模型，日常聊天或摘要使用更便宜的模型。你可以按智能体路由模型并使用子智能体并行处理长任务（每个子智能体消耗令牌）。参阅模型和子智能体。
重要警告：较弱/过度量化的模型更容易受到提示注入和不安全行为的影响。参阅安全。
更多上下文：模型。
可以。如果你的本地服务器暴露了兼容 OpenAI 的 API，你可以将自定义提供商指向它。Ollama 直接支持，是最简单的路径。
安全说明：较小或大幅量化的模型更容易受到提示注入的影响。我们强烈建议对任何可以使用工具的机器人使用大型模型。如果你仍然想使用小模型，启用沙箱和严格的工具允许列表。
使用模型命令或只编辑模型字段。避免完整配置替换。
安全选项：
/model（快速，按会话）openclaw models set ...（只更新模型配置）openclaw configure --section models（交互式）~/.openclaw/openclaw.json 中的 agents.defaults.model避免使用部分对象执行 config.apply，除非你打算替换整个配置。如果你确实覆盖了配置，从备份恢复或重新运行 openclaw doctor 来修复。
文档：模型、Configure、Config、Doctor。
anthropic/claude-opus-4-5）——参阅 Anthropic。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
你也可以为提供商强制指定特定的认证配置文件（按会话）：
/model opus@anthropic:default
/model opus@anthropic:work
提示：/model status 显示哪个智能体是活跃的、正在使用哪个 auth-profiles.json 文件，以及接下来将尝试哪个认证配置文件。
它还显示配置的提供商端点（baseUrl）和 API 模式（api）（如果可用）。
如何取消用 @profile 设置的配置文件固定
重新运行 /model 但不带 @profile 后缀：
/model anthropic/claude-opus-4-5
如果你想返回默认值，从 /model 中选择（或发送 /model <default provider/model>）。
使用 /model status 确认哪个认证配置文件是活跃的。
可以。设置一个为默认并按需切换：
/model gpt-5.2，编程用 /model gpt-5.2-codex。agents.defaults.model.primary 设置为 openai-codex/gpt-5.2，然后编程时切换到 openai-codex/gpt-5.2-codex（或反过来）。如果设置了 agents.defaults.models，它成为 /model 和任何会话覆盖的允许列表。选择不在该列表中的模型会返回：
Model "provider/model" is not allowed. Use /model to list available models.
该错误代替正常回复返回。修复：将模型添加到 agents.defaults.models，移除允许列表，或从 /model list 中选择一个模型。
这意味着提供商未配置（未找到 MiniMax 提供商配置或认证配置文件），因此模型无法解析。此检测的修复在 2026.1.12（撰写本文时尚未发布）中。
修复清单：
升级到 2026.1.12（或从源码 main 运行），然后重启 Gateway 网关。
确保 MiniMax 已配置（向导或 JSON），或者 MiniMax API 密钥存在于环境/认证配置文件中以便提供商可以被注入。
使用精确的模型 ID（区分大小写）：minimax/MiniMax-M2.1 或 minimax/MiniMax-M2.1-lightning。
运行：
openclaw models list
并从列表中选择（或在聊天中使用 /model list）。
可以。使用 MiniMax 作为默认，需要时按会话切换模型。故障转移用于错误，而非“困难任务”，所以使用 /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：分离智能体
/agent 切换是的。OpenClaw 内置了一些默认简写（仅在模型存在于 agents.defaults.models 中时应用）：
opus → anthropic/claude-opus-4-5sonnet → anthropic/claude-sonnet-4-5gpt → openai/gpt-5.2gpt-mini → openai/gpt-5-minigemini → google/gemini-3-pro-previewgemini-flash → google/gemini-3-flash-preview如果你设置了同名的自定义别名，你的值优先。
别名来自 agents.defaults.models.<modelId>.alias。示例：
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-5" },
models: {
"anthropic/claude-opus-4-5": { alias: "opus" },
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
"anthropic/claude-haiku-4-5": { alias: "haiku" },
},
},
},
}
然后 /model sonnet（或支持时的 /<alias>）解析为该模型 ID。
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"）。
添加新智能体后提示 No API key found for provider
这通常意味着新智能体的认证存储为空。认证是按智能体的，存储在：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
修复选项：
openclaw agents add <id> 并在向导中配置认证。agentDir 复制 auth-profiles.json 到新智能体的 agentDir。不要在智能体之间重用 agentDir；这会导致认证/会话冲突。
故障转移分两个阶段：
agents.defaults.model.fallbacks 中的下一个模型。冷却期适用于失败的配置文件（指数退避），因此 OpenClaw 即使在提供商被限速或临时失败时也能继续响应。
No credentials found for profile "anthropic:default"
这意味着系统尝试使用认证配置文件 ID anthropic:default，但在预期的认证存储中找不到它的凭据。
~/.openclaw/agents/<agentId>/agent/auth-profiles.json~/.openclaw/agent/*（通过 openclaw doctor 迁移）ANTHROPIC_API_KEY 但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承。将其放在 ~/.openclaw/.env 中或启用 env.shellEnv。auth-profiles.json 文件。openclaw models status 查看已配置的模型以及提供商是否已认证。No credentials found for profile "anthropic" 的修复清单
这意味着运行固定到 Anthropic 认证配置文件，但 Gateway 网关在其认证存储中找不到它。
claude setup-token，然后用 openclaw models auth setup-token --provider anthropic 粘贴。openclaw models auth paste-token --provider anthropic。ANTHROPIC_API_KEY 放入 ~/.openclaw/.env。openclaw models auth order clear --provider anthropic
如果你的模型配置包含 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 块（通常来自中止/部分流）。Google Antigravity 要求 thinking 块有签名。
修复：OpenClaw 现在为 Google Antigravity Claude 剥离未签名的 thinking 块。如果仍然出现，开始新会话或为该智能体设置 /thinking off。
相关：/concepts/oauth（OAuth 流程、令牌存储、多账户模式）
认证配置文件是绑定到提供商的命名凭据记录（OAuth 或 API 密钥）。配置文件位于：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
OpenClaw 使用提供商前缀的 ID，如：
anthropic:default（没有邮箱身份时常见）anthropic:<email>（用于 OAuth 身份）anthropic:work）可以。配置支持配置文件的可选元数据和按提供商的排序（auth.order.<provider>）。这不存储密钥；它将 ID 映射到 provider/mode 并设置轮换顺序。
如果某个配置文件处于短期冷却（速率限制/超时/认证失败）或较长的禁用状态（计费/额度不足），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
OpenClaw 两者都支持：
向导明确支持 Anthropic setup-token 和 OpenAI Codex OAuth，也可以为你存储 API 密钥。
gateway.port 控制用于 WebSocket + HTTP（控制 UI、钩子等）的单个复用端口。
优先级：
--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789
因为"running"是 supervisor 的视角（launchd/systemd/schtasks）。RPC 探测是 CLI 实际连接到 Gateway 网关 WebSocket 并调用 status。
使用 openclaw gateway status 并关注这些行：
Probe target:（探测实际使用的 URL）Listening:（端口上实际绑定的内容）Last gateway error:（进程存活但端口未监听时的常见根因）你正在编辑一个配置文件，而服务运行的是另一个（通常是 --profile / OPENCLAW_STATE_DIR 不匹配）。
修复：
openclaw gateway install --force
从你希望服务使用的相同 --profile / 环境运行该命令。
OpenClaw 通过在启动时立即绑定 WebSocket 监听器来强制运行时锁（默认 ws://127.0.0.1:18789）。如果绑定因 EADDRINUSE 失败，它会抛出 GatewayLockError 表示另一个实例已在监听。
修复：停止另一个实例，释放端口，或使用 openclaw gateway --port <port> 运行。
设置 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 时启动（或你传递覆盖标志）。你的 Gateway 网关运行时启用了认证（gateway.auth.*），但 UI 没有发送匹配的令牌/密码。
事实（来自代码）：
openclaw.control.settings.v1 中。?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）。?token=... 链接刷新）。openclaw status --all 并按故障排除操作。参阅仪表板了解认证详情。tailnet 绑定从你的网络接口中选择 Tailscale IP（100.64.0.0/10）。如果机器没有在 Tailscale 上（或接口已关闭），就没有可绑定的地址。
修复：
gateway.bind: "loopback" / "lan"。注意：tailnet 是明确的。auto 优先 local loopback；当你想要仅 tailnet 绑定时使用 gateway.bind: "tailnet"。
通常不需要——一个 Gateway 网关可以运行多个消息渠道和智能体。仅在需要冗余（例如救援机器人）或硬隔离时使用多个 Gateway 网关。
可以，但你必须隔离：
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>)）。
完整指南：多 Gateway 网关。
Gateway 网关是一个 WebSocket 服务器，它期望第一条消息是 connect 帧。如果收到其他内容，它会以 code 1008（策略违规）关闭连接。
常见原因：
http://...）而不是 WS 客户端。快速修复：
ws://<host>:18789（或 wss://... 如果 HTTPS）。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
服务/supervisor 日志（当 Gateway 网关通过 launchd/systemd 运行时）：
$OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log（默认：~/.openclaw/logs/...；配置文件使用 ~/.openclaw-<profile>/logs/...）journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pagerschtasks /Query /TN "OpenClaw Gateway 网关 (<profile>)" /V /FO LIST参阅故障排除了解更多。
使用 Gateway 网关辅助命令：
openclaw gateway status
openclaw gateway restart
如果你手动运行 Gateway 网关，openclaw gateway --force 可以回收端口。参阅 Gateway 网关。
有两种 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 网关服务运维手册。
从快速健康扫描开始：
openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow
常见原因：
models status）。如果你在远程，确认隧道/Tailscale 连接正常且 Gateway 网关 WebSocket 可达。
这通常意味着 UI 丢失了 WebSocket 连接。检查：
openclaw gateway statusopenclaw statusopenclaw dashboard然后跟踪日志：
openclaw logs --follow
从日志和渠道状态开始：
openclaw channels status
openclaw channels logs --channel telegram
如果你在 VPS 上或代理后面，确认出站 HTTPS 被允许且 DNS 正常工作。 如果 Gateway 网关在远程，确保你在 Gateway 网关主机上查看日志。
首先确认 Gateway 网关可达且智能体可以运行：
openclaw status
openclaw models status
openclaw logs --follow
在 TUI 中，使用 /status 查看当前状态。如果你期望在聊天渠道中收到回复，确保投递已启用（/deliver on）。
openclaw gateway stop
openclaw gateway start
这会停止/启动受监管的服务（macOS 上的 launchd，Linux 上的 systemd）。 当 Gateway 网关作为守护进程在后台运行时使用此命令。
如果你在前台运行，用 Ctrl‑C 停止，然后：
openclaw gateway run
文档：Gateway 网关服务运维手册。
openclaw gateway restart：重启后台服务（launchd/systemd）。openclaw gateway：在这个终端会话中前台运行 Gateway 网关。如果你安装了服务，使用 Gateway 网关命令。想要一次性前台运行时使用 openclaw gateway。
使用 --verbose 启动 Gateway 网关以获取更多控制台详情。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。
智能体的出站附件必须包含 MEDIA:<path-or-url> 行（独占一行）。参阅 OpenClaw 助手设置和 Agent send。
CLI 发送：
openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
还要检查：
参阅图片。
将入站私信视为不可信输入。默认设计旨在降低风险：
openclaw pairing approve <channel> <code>openclaw pairing list <channel>。dmPolicy: "open" 且允许列表 "*"）。运行 openclaw doctor 以发现有风险的私信策略。
不是。提示注入是关于不可信内容，不仅仅是谁能给机器人发私信。如果你的助手读取外部内容（网络搜索/抓取、浏览器页面、邮件、文档、附件、粘贴的日志），这些内容可能包含试图劫持模型的指令。即使你是唯一的发送者，这也可能发生。
最大的风险是在启用工具时：模型可能被诱导泄露上下文或代表你调用工具。通过以下方式减少影响范围：
web_search / web_fetch / browser详情：安全。
是的，对于大多数设置来说。用独立的账户和电话号码隔离机器人可以在出问题时减少影响范围。这也使得轮换凭据或撤销访问更容易，而不影响你的个人账户。
从小处开始。只授予你实际需要的工具和账户的访问权限，以后需要时再扩展。
我们不建议完全自主管理你的个人消息。最安全的模式是：
如果你想实验，在专用账户上进行并保持隔离。参阅安全。
可以，如果智能体仅用于聊天且输入是可信的。较小的模型更容易受到指令劫持，因此避免将它们用于启用工具的智能体或读取不可信内容时。如果你必须使用较小的模型，锁定工具并在沙箱中运行。参阅安全。
配对码仅在未知发送者向机器人发消息且 dmPolicy: "pairing" 启用时发送。/start 本身不会生成代码。
检查待处理请求：
openclaw pairing list telegram
如果你想立即获得访问权限，将你的发送者 ID 加入允许列表或为该账户设置 dmPolicy: "open"。
不会。WhatsApp 的默认私信策略是配对。未知发送者只会收到配对码，他们的消息不会被处理。OpenClaw 只回复它收到的聊天或你明确触发的发送。
批准配对：
openclaw pairing approve whatsapp <code>
列出待处理请求：
openclaw pairing list whatsapp
向导电话号码提示：它用于设置你的允许列表/所有者，以便你自己的私信被允许。它不用于自动发送。如果你在个人 WhatsApp 号码上运行，使用该号码并启用 channels.whatsapp.selfChatMode。
大多数内部或工具消息只在该会话启用了 verbose 或 reasoning 时才出现。
在你看到它的聊天中修复：
/verbose off
/reasoning off
如果仍然嘈杂，检查控制 UI 中的会话设置并将 verbose 设为继承。同时确认你没有使用在配置中将 verboseDefault 设为 on 的机器人配置文件。
发送以下任一内容作为独立消息（不带斜杠）：
stop
abort
esc
wait
exit
interrupt
这些是中止触发器（不是斜杠命令）。
对于后台进程（来自 exec 工具），你可以要求智能体运行：
process action:kill sessionId:XXX
斜杠命令概览：参阅斜杠命令。
大多数命令必须作为以 / 开头的独立消息发送，但一些快捷方式（如 /status）对允许列表中的发送者也支持内联使用。
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（或在认证配置文件中存储 Anthropic API 密钥）启用认证，但实际的默认模型是你在 agents.defaults.model.primary 中配置的（例如 anthropic/claude-sonnet-4-5 或 anthropic/claude-opus-4-5）。如果你看到 No credentials found for profile "anthropic:default"，意味着 Gateway 网关在正在运行的智能体的预期 auth-profiles.json 中找不到 Anthropic 凭据。