openclaw 文档

简体中文

English

简体中文

English

Appearance

FAQ ​

常见问题

这里包含快速答案，以及面向真实环境（本地开发、VPS、多 agent、OAuth/API keys、模型 failover）的更深入排障说明。 运行时诊断请见 Troubleshooting。完整配置参考请见 Configuration。

Table of contents ​

（目录：为避免破坏 (#...) 显式锚点链接，目录条目暂保留英文。）

First 60 seconds if something's broken ​

（如果东西坏了：先跑完这 60 秒的自检循环。）

  1. 快速状态（第一次检查）

    bash
    openclaw status

    本地快速概要：OS + 更新状态、gateway/service 可达性、agents/sessions、provider 配置与运行时问题（当 gateway 可达时）。

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

    bash
    openclaw status --all

    只读诊断，包含日志尾部（tokens 已脱敏）。

  3. daemon + 端口状态

    bash
    openclaw gateway status

    展示 supervisor 运行状态 vs RPC 可达性、probe target URL，以及 service 可能使用的 config。

  4. 深度探测

    bash
    openclaw status --deep

    运行 gateway 健康检查 + provider probes（需要 gateway 可达）。见 Health。

  5. 跟随最新日志

    bash
    openclaw logs --follow

    如果 RPC 不通，可退回到：

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

    文件日志与 service 日志是分开的；见 Logging 与 Troubleshooting。

  6. 运行 doctor（修复）

    bash
    openclaw doctor

    修复/迁移 config/state，并运行健康检查。见 Doctor。

  7. Gateway 快照

    bash
    openclaw health --json
openclaw health --verbose   # shows the target URL + config path on errors

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

Quick start and first-run setup ​

（快速开始与首次运行设置。）

Im stuck whats the fastest way to get unstuck ​

（我卡住了：最快的脱困方式是什么？）

使用一个能看到你机器的本地 AI agent。相比在 Discord 里提问，这通常更有效：因为大多数“卡住”的情况都是本地配置或环境问题，远程协助者无法直接检查。

  • Claude Code：https://www.anthropic.com/claude-code/
  • OpenAI Codex：https://openai.com/codex/

这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器层面的设置（PATH、services、权限、auth files）。请通过 hackable（git）安装给它们提供完整源码 checkout：

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

这会从 git checkout 安装 OpenClaw，使 agent 能读取代码 + 文档，并基于你正在运行的确切版本做判断。之后你随时可以通过不带 --install-method git 重新运行安装器切回 stable。

小提示：让 agent 先制定并监督修复计划（一步步），然后只执行必要命令。这样改动更小、更易审计。

如果你发现了真实 bug 或修复，请提交 GitHub issue 或 PR： https://github.com/openclaw/openclaw/issueshttps://github.com/openclaw/openclaw/pulls

建议先从这些命令开始（在求助时可分享输出）：

bash
openclaw status
openclaw models status
openclaw doctor

它们的作用：

  • openclaw status：快速查看 gateway/agent 健康与基础配置。
  • openclaw models status：检查 provider 鉴权与模型可用性。
  • openclaw doctor：验证并修复常见 config/state 问题。

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

快速排障循环见：First 60 seconds if something's broken。 安装相关文档：Install、Installer flags、Updating。

（推荐的安装与初始化方式是什么？）

仓库推荐从源码运行，并使用 onboarding wizard：

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

wizard 也可以自动构建 UI assets。完成 onboarding 后，你通常会在 18789 端口运行 Gateway。

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

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
openclaw onboard

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

How do I open the dashboard after onboarding ​

（onboarding 后如何打开 dashboard？）

wizard 现在会在 onboarding 结束后立刻用一个带 token 的 dashboard URL 打开浏览器，并在 summary 中打印完整链接（包含 token）。请保持该标签页打开；如果没自动弹出，请在同一台机器上复制/粘贴打印出来的 URL。token 会保留在本机；浏览器不会从远端“拉取 token”。

How do I authenticate the dashboard token on localhost vs remote ​

（dashboard 在本机与远程场景下如何鉴权？）

Localhost（同一台机器）：

  • 打开 http://127.0.0.1:18789/。
  • 如果提示需要鉴权，运行 openclaw dashboard 并使用带 token 的链接（?token=...）。
  • token 与 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）的值相同，并会在 UI 首次加载后由 UI 保存。

非 localhost：

  • Tailscale Serve（推荐）：保持 bind=loopback，运行 openclaw gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，Serve identity headers 即可满足鉴权（不需要 token）。
  • Tailnet bind：运行 openclaw gateway --bind tailnet --token "<token>"，打开 http://<tailscale-ip>:18789/，在 dashboard settings 中粘贴 token。
  • SSH tunnel：ssh -N -L 18789:127.0.0.1:18789 user@host，然后从 openclaw dashboard 打开的 http://127.0.0.1:18789/?token=... 访问。

bind modes 与鉴权细节见 Dashboard 与 Web surfaces。

What runtime do I need ​

（需要什么运行时？）

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

Does it run on Raspberry Pi ​

（能在树莓派上跑吗？）

可以。Gateway 相对轻量；文档给出的个人使用参考为 512MB-1GB RAM、1 核、以及约 500MB 磁盘；并明确指出 Raspberry Pi 4 可以运行。

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

提示：你可以让一台小型 Pi/VPS 托管 Gateway，再把笔记本/手机配对为 nodes 来使用本地 screen/camera/canvas 或执行命令。见 Nodes。

Any tips for Raspberry Pi installs ​

（树莓派安装有什么建议？）

简版：能用，但要预期会有一些“边角问题”。

  • 使用 64-bit OS，并保持 Node >= 22。
  • 优先选择 hackable（git）安装，这样更方便看日志与快速更新。
  • 先不启用 channels/skills，之后再逐个添加。
  • 如果遇到奇怪的二进制问题，通常是 ARM 兼容性问题。

相关文档：Linux、Install。

It is stuck on wake up my friend onboarding will not hatch What now ​

（卡在 “wake up my friend” / onboarding 无法 hatch，怎么办？）

该界面依赖 gateway 可达且已鉴权。TUI 也会在首次 hatch 时自动发送 “Wake up, my friend!”。如果你看到这行但没有回复，并且 tokens 一直是 0，说明 agent 没有跑起来。

  1. 重启 Gateway：
bash
openclaw gateway restart
  1. 检查状态与鉴权：
bash
openclaw status
openclaw models status
openclaw logs --follow
  1. 仍然卡住则运行：
bash
openclaw doctor

如果 Gateway 是远程的，请确认 tunnel/Tailscale 连接正常，并且 UI 指向了正确的 Gateway。见 Remote access。

Can I migrate my setup to a new machine Mac mini without redoing onboarding ​

（能否迁移到新机器而不重做 onboarding？）

可以。复制 state directory 与 workspace，然后运行一次 Doctor。 只要这两个位置都复制了，你的 bot 就能“几乎完全一致”（memory、session history、鉴权、channel state）。

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

这样会保留 config、auth profiles、WhatsApp creds、sessions 与 memory。若你处于 remote mode，请记住 session store 与 workspace 的事实来源在 gateway host 上。

重要： 如果你只把 workspace commit/push 到 GitHub，你备份的是 memory + bootstrap files，但不会备份 session history 或鉴权。它们在 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/sessions/）。

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

Where do I see whats new in the latest version ​

（在哪里看最新版本更新内容？）

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

最新条目在顶部。如果最上面一节标记为 Unreleased，那么下一节带日期的内容就是最近一次正式发布的版本。 条目通常按 Highlights、Changes、Fixes 分组（必要时还会有 docs/other 等章节）。

I cant access docs.openclaw.ai SSL error What now ​

（访问 docs.openclaw.ai 失败/SSL 错误，怎么办？）

部分 Comcast/Xfinity 网络会通过 Xfinity Advanced Security 误拦截 docs.openclaw.ai。 请关闭 Advanced Security 或把 docs.openclaw.ai 加入 allowlist 后重试。更多细节见： Troubleshooting。 也欢迎你在这里提交报告帮助我们解封：https://spa.xfinity.com/check_url_status。

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

What's the difference between stable and beta ​

（stable 与 beta 有什么区别？）

Stable 与 beta 是 npm dist-tags，不是两条独立代码线：

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

我们会先把构建发布到 beta，测试后，再把验证过的构建提升（promote）到 latest。 因此 beta 与 stable 可能指向同一个版本号。

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

How do I install the beta version and whats the difference between beta and dev ​

（如何安装 beta？beta 与 dev 的区别是什么？）

Beta 是 npm dist-tag beta（可能与 latest 相同）。
Dev 是 main 的滚动 head（git）；当发布到 npm 时使用 dist-tag dev。

一行命令（macOS/Linux）：

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

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

更多细节：Development channels 与 Installer flags。

How long does install and onboarding usually take ​

（安装与 onboarding 通常需要多久？）

粗略参考：

  • Install： 2-5 分钟
  • Onboarding： 5-15 分钟（取决于你配置了多少 channels/models）

如果卡住了，请参考 Installer stuck， 以及 Im stuck 中的快速排障循环。

How do I try the latest bits ​

（如何体验最新版本？）

两个选项：

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

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

  1. Hackable install（通过安装器站点安装 git checkout）：
bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

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

如果你更喜欢手动干净 clone：

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

文档：Update、Development channels、Install。

Installer stuck How do I get more feedback ​

（安装器卡住了，怎么获取更多反馈？）

用 verbose 输出重跑安装器：

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

Beta 安装 + verbose：

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

Hackable（git）安装 + verbose：

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

更多选项见：Installer flags。

Windows install says git not found or openclaw not recognized ​

（Windows 安装提示 git not found 或 openclaw 未识别）

Windows 上常见两类问题：

1) npm error spawn git / git not found

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

2) openclaw is not recognized after install

  • npm 全局 bin 目录没有加入 PATH。
  • 检查 prefix：
    powershell
    npm config get prefix
  • 确保 <prefix>\\bin 在 PATH 上（多数系统为 %AppData%\\npm）。
  • 更新 PATH 后关闭并重新打开 PowerShell。

如果你想要最顺滑的 Windows 体验，推荐使用 WSL2 而不是原生 Windows。 文档：Windows。

The docs didnt answer my question how do I get a better answer ​

（文档没解决我的问题，怎么获得更好的答案？）

使用 hackable（git）安装，让你在本地拥有完整源码与文档；然后在那个目录里向你的 bot（或 Claude/Codex）提问，这样它才能读取仓库并给出精准答案。

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

更多细节：Install 与 Installer flags。

How do I install OpenClaw on Linux ​

（如何在 Linux 上安装？）

简版：按 Linux 指南安装，然后运行 onboarding wizard。

How do I install OpenClaw on a VPS ​

（如何在 VPS 上安装？）

任何 Linux VPS 都可以。把 OpenClaw 安装到服务器上，然后用 SSH/Tailscale 连接 Gateway。

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

Where are the cloudVPS install guides ​

（云/VPS 的安装指南在哪里？）

我们提供了一个托管指南入口（hosting hub），汇总常见 provider。选择一个并按指南操作：

云上运行机制：Gateway 跑在服务器上，你通过 Control UI（或 Tailscale/SSH）从笔记本/手机访问。 你的 state + workspace 也在服务器上，因此请把该主机当作事实来源并做好备份。

你还可以把 nodes（Mac/iOS/Android/headless）配对到云端 Gateway：既能访问本地 screen/camera/canvas，也能在笔记本上执行命令，同时保持 Gateway 在云端。

入口：Platforms。远程访问：Gateway remote。 Nodes：Nodes、Nodes CLI。

Can I ask OpenClaw to update itself ​

（能让 OpenClaw 自己更新自己吗？）

简版：可以，但不推荐。更新流程可能会重启 Gateway（导致当前活跃 session 断开），可能需要 git checkout 干净，还可能出现确认提示。 更稳妥的方式是由 operator 在 shell 中执行更新。

使用 CLI：

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

如果你必须从 agent 自动化：

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

文档：Update、Updating。

What does the onboarding wizard actually do ​

（onboarding wizard 实际会做什么？）

openclaw onboard 是推荐的 setup 路径。在 local mode 下，它会引导你完成：

  • 模型/鉴权配置（Claude 订阅推荐 Anthropic setup-token；支持 OpenAI Codex OAuth；API keys 可选；支持 LM Studio 本地模型）
  • Workspace 位置 + bootstrap files
  • Gateway 设置（bind/port/auth/tailscale）
  • Providers（WhatsApp、Telegram、Discord、Mattermost（插件）、Signal、iMessage）
  • Daemon 安装（macOS 的 LaunchAgent；Linux/WSL2 的 systemd user unit）
  • 健康检查与 skills 选择

它也会在你配置的模型未知或缺少鉴权时发出警告。

Do I need a Claude or OpenAI subscription to run this ​

（运行它必须要 Claude 或 OpenAI 订阅吗？）

不需要。你可以用 API keys（Anthropic/OpenAI/其它 provider），也可以使用纯本地模型让数据留在你的设备上。 订阅（Claude Pro/Max 或 OpenAI Codex）只是这些 provider 的一种可选鉴权方式。

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

Can I use Claude Max subscription without an API key ​

（没有 API key 能用 Claude Max 订阅吗？）

可以。你可以使用 setup-token 来替代 API key。这是订阅鉴权路径。

Claude Pro/Max 订阅不包含 API key，因此对订阅账号来说，这是正确路径。 重要提示：你需要自行向 Anthropic 确认该用法符合其订阅政策与条款。 如果你希望最明确、最受支持的方式，请使用 Anthropic API key。

How does Anthropic setuptoken auth work ​

（Anthropic setup-token 鉴权如何工作？）

claude setup-token 会通过 Claude Code CLI 生成一段 token 字符串（Web Console 里拿不到）。你可以在任意机器上运行它。 在 wizard 中选择 Anthropic token (paste setup-token)，或使用 openclaw models auth paste-token --provider anthropic 粘贴。 该 token 会以 anthropic provider 的 auth profile 形式存储，并像 API key 一样使用（不会自动刷新）。 更多细节见：OAuth。

Where do I find an Anthropic setuptoken ​

（去哪里拿 Anthropic setup-token？）

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

bash
claude setup-token

复制其输出的 token，然后在 wizard 里选择 Anthropic token (paste setup-token)。 如果你希望在 gateway host 上生成，使用 openclaw models auth setup-token --provider anthropic。 如果你在别处运行了 claude setup-token，在 gateway host 上用 openclaw models auth paste-token --provider anthropic 粘贴即可。 见：Anthropic。

Do you support Claude subscription auth (Claude Pro/Max) ​

（支持 Claude 订阅鉴权吗？）

支持——通过 setup-token。OpenClaw 不再复用 Claude Code CLI 的 OAuth tokens；请使用 setup-token 或 Anthropic API key。 你可以在任意机器生成 token，然后粘贴到 gateway host 上。见 Anthropic 与 OAuth。

注意：Claude 订阅访问受 Anthropic 条款约束。对生产或多用户负载来说，API keys 往往是更稳妥的选择。

Why am I seeing HTTP 429 ratelimiterror from Anthropic ​

（为什么会收到 Anthropic 的 HTTP 429 rate_limit_error？）

这表示当前时间窗内你的 Anthropic quota/rate limit 已耗尽。 如果你使用 Claude 订阅（setup-token 或 Claude Code OAuth），请等待窗口重置或升级套餐。 如果你使用 Anthropic API key，请到 Anthropic Console 检查用量/计费，并按需提升限额。

提示：设置一个 fallback model，让 OpenClaw 在某个 provider 被限流时仍能继续回复。 见 Models 与 OAuth。

Is AWS Bedrock supported ​

（支持 AWS Bedrock 吗？）

支持——通过 pi-ai 的 Amazon Bedrock (Converse) provider，并需要手动配置。 你需要在 gateway host 上提供 AWS credentials/region，并在 models config 中添加 Bedrock provider 条目。 见 Amazon Bedrock 与 Model providers。 如果你更偏好“托管式”的 key 流程，在 Bedrock 前面放一个 OpenAI 兼容代理也是可行方案。

How does Codex auth work ​

（Codex 鉴权如何工作？）

OpenClaw 通过 OAuth（ChatGPT 登录）支持 OpenAI Code（Codex）。wizard 可以为你完成 OAuth 流程，并在合适情况下把默认模型设为 openai-codex/gpt-5.2。 见 Model providers 与 Wizard。

Do you support OpenAI subscription auth Codex OAuth ​

（支持 OpenAI 订阅鉴权/Codex OAuth 吗？）

支持。OpenClaw 完整支持 OpenAI Code（Codex）订阅 OAuth，onboarding wizard 可以为你完成 OAuth 流程。

见 OAuth、Model providers、Wizard。

How do I set up Gemini CLI OAuth ​

（如何配置 Gemini CLI OAuth？）

Gemini CLI 使用 plugin 鉴权流程，而不是在 openclaw.json 中配置 client id/secret。

步骤：

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

这会把 OAuth tokens 存入 gateway host 上的 auth profiles。细节见：Model providers。

Is a local model OK for casual chats ​

（本地模型适合日常闲聊吗？）

通常不适合。OpenClaw 需要更大的上下文与更强的安全性；小模型更容易截断与泄露。 如果你一定要用，建议在本地（LM Studio）运行你能跑得动的最大 MiniMax M2.1，并参考 /gateway/local-models。 更小/量化模型会增加 prompt-injection 风险——见 Security。

How do I keep hosted model traffic in a specific region ​

（如何让托管模型流量留在特定区域？）

选择能 pin 区域的 endpoints。OpenRouter 提供 MiniMax、Kimi 与 GLM 的 US-hosted 选项；选择 US-hosted 变体即可把数据留在该区域。 你仍然可以通过 models.mode: "merge" 同时列出 Anthropic/OpenAI，让 fallbacks 保持可用，同时遵守你选择的 region provider。

Do I have to buy a Mac Mini to install this ​

（必须买 Mac mini 才能装吗？）

不需要。OpenClaw 可运行在 macOS 或 Linux（Windows 可通过 WSL2）。Mac mini 只是可选项——有人会买一台当作常开的 host，但小型 VPS、家用服务器或树莓派级别主机也可以。

你只有在需要 macOS-only tools 时才需要 Mac。对 iMessage，你可以让 Gateway 运行在 Linux 上，并通过 SSH 在任意 Mac 上运行 imsg：把 channels.imessage.cliPath 指向一个 SSH wrapper 即可。 如果你还需要其它 macOS-only tools，要么把 Gateway 跑在 Mac 上，要么配对一个 macOS node。

文档：iMessage、Nodes、Mac remote mode。

Do I need a Mac mini for iMessage support ​

（iMessage 支持需要 Mac mini 吗？）

你需要一台登录了 Messages 的 macOS 设备。它不必是 Mac mini——任何 Mac 都可以。 OpenClaw 的 iMessage 集成运行在 macOS 上（BlueBubbles 或 imsg），而 Gateway 可以跑在别处。

常见组合：

  • Gateway 跑在 Linux/VPS；把 channels.imessage.cliPath 指向一个 SSH wrapper，让它在 Mac 上运行 imsg。
  • 全部都跑在 Mac 上（最简单的单机方案）。

文档：iMessage、BlueBubbles、Mac remote mode。

If I buy a Mac mini to run OpenClaw can I connect it to my MacBook Pro ​

（如果我用 Mac mini 跑 OpenClaw，能连接我的 MacBook Pro 吗？）

可以。Mac mini 可以运行 Gateway，而 MacBook Pro 可以作为 node（伴随设备）连接。 nodes 不运行 Gateway——它们提供额外能力，例如该设备上的 screen/camera/canvas，以及 system.run。

常见模式：

  • Gateway 跑在 Mac mini（常开）。
  • MacBook Pro 运行 macOS app 或 node host，并与 Gateway 配对。
  • 用 openclaw nodes status / openclaw nodes list 查看。

文档：Nodes、Nodes CLI。

Can I use Bun ​

（可以用 Bun 吗？）

不推荐。我们观察到一些运行时 bug，尤其是 WhatsApp 与 Telegram。想要稳定的 gateway，请使用 Node。

如果你仍想试验 Bun，请在非生产 gateway 上进行，并避免启用 WhatsApp/Telegram。

Telegram what goes in allowFrom ​

（Telegram 的 allowFrom 应该填什么？）

channels.telegram.allowFrom 填的是真人发送者的 Telegram user ID（数字，推荐）或 @username，不是 bot 的用户名。

更安全的方式（不依赖第三方 bot）：

  • 私信你的 bot，然后运行 openclaw logs --follow 并读取 from.id。

官方 Bot API：

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

第三方方式（隐私更差）：

  • 私信 @userinfobot 或 @getidsbot。

见 /channels/telegram。

Can multiple people use one WhatsApp number with different OpenClaw instances ​

（多个人能否用同一个 WhatsApp 号码、对应不同的 OpenClaw 实例？）

可以，通过 multi-agent routing。 把每个发送者的 WhatsApp DM（peer kind: "dm"，发送者的 E.164 如 +15551234567）绑定到不同 agentId，这样每个人都会有独立的 workspace 与 session store。 回复仍然来自同一个 WhatsApp 账号；并且 DM 访问控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）在该 WhatsApp 账号范围内是全局的。 见 Multi-Agent Routing 与 WhatsApp。

Can I run a fast chat agent and an Opus for coding agent ​

（能同时跑一个“快速聊天”agent 和一个“用 Opus 写代码”的 agent 吗？）

可以。使用 multi-agent routing：给每个 agent 配置自己的默认模型，然后把入站路由（provider account 或具体 peers）绑定到对应 agent。 示例配置见 Multi-Agent Routing。另见 Models 与 Configuration。

Does Homebrew work on Linux ​

（Homebrew 在 Linux 上能用吗？）

可以。Homebrew 支持 Linux（Linuxbrew）。快速安装：

bash
/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，请确保 service 的 PATH 包含 /home/linuxbrew/.linuxbrew/bin（或你的 brew prefix），这样在非登录 shell 里才能解析到 brew 安装的工具。 近期构建也会在 Linux 的 systemd services 下前置一些常见用户 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。

What's the difference between the hackable git install and npm install ​

（hackable（git）安装与 npm 安装有什么区别？）

  • Hackable（git）安装： 完整源码 checkout，可编辑，最适合贡献者。 你在本地运行构建，并可以修改代码/文档。
  • npm 安装： 全局 CLI 安装，不包含仓库，最适合“只想跑起来”。 更新来自 npm dist-tags。

文档：Getting started、Updating。

Can I switch between npm and git installs later ​

（之后能在 npm 与 git 安装之间切换吗？）

可以。安装另一种方式后，运行 Doctor，让 gateway service 指向新的 entrypoint。 这不会删除你的数据——它只改变 OpenClaw 的代码安装方式；你的 state（~/.openclaw）与 workspace（~/.openclaw/workspace）不会被动到。

从 npm → git：

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

从 git → npm：

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

Doctor 会检测 gateway service 的 entrypoint 不匹配，并提供重写 service 配置以匹配当前安装的选项（自动化场景可用 --repair）。

备份建议见：Backup strategy。

Should I run the Gateway on my laptop or a VPS ​

（Gateway 应该跑在笔记本还是 VPS 上？）

简版：想要 24/7 可靠性就用 VPS。如果你追求最低摩擦、且能接受睡眠/重启带来的中断，就本地跑。

Laptop（本地 Gateway）

  • 优点： 不需要服务器成本、可直接访问本地文件、浏览器窗口可见。
  • 缺点： 睡眠/网络抖动会断线，系统更新/重启会中断，机器必须保持唤醒。

VPS / 云

  • 优点： 常开、网络更稳定、不受笔记本睡眠影响、更容易保持持续运行。
  • 缺点： 通常是 headless（用截图观察）、访问本地文件不方便、更新需要 SSH。

OpenClaw 特有说明： WhatsApp/Telegram/Slack/Mattermost（插件）/Discord 在 VPS 上都能正常工作。主要权衡是 headless browser vs 可见窗口。见 Browser。

推荐默认： 如果你以前遇到过 gateway 断线，优先 VPS。本地适合你正在频繁使用 Mac、需要访问本地文件或需要“可见浏览器”的 UI 自动化。

How important is it to run OpenClaw on a dedicated machine ​

（是否必须用专用机器运行？）

不是必须，但为了可靠性与隔离性，推荐使用专用机器。

  • 专用 host（VPS/Mac mini/Pi）： 常开、更少睡眠/重启干扰、权限边界更清晰、更容易保持运行。
  • 共享的笔记本/台式机： 测试与日常使用完全没问题，但机器睡眠或更新时会有暂停。

如果你想两全其美：把 Gateway 放在专用 host 上，把笔记本配对成 node 来提供本地 screen/camera/exec tools。见 Nodes。 安全建议见 Security。

（VPS 的最低配置与推荐 OS 是什么？）

OpenClaw 相对轻量。对“基础 Gateway + 一个聊天 channel”：

  • 绝对最低： 1 vCPU、1GB RAM、约 500MB 磁盘。
  • 推荐： 1-2 vCPU、2GB RAM 或更多（给日志、媒体、多 channels 留余量）。一些 Node tools 与浏览器自动化会比较吃资源。

OS：推荐使用 Ubuntu LTS（或任意现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。

文档：Linux、VPS hosting。

Can I run OpenClaw in a VM and what are the requirements ​

（能在 VM 里跑吗？需要什么配置？）

可以。把 VM 当作 VPS 即可：需要常开、可达，并且有足够 RAM 支撑 Gateway 与你启用的 channels。

基线建议：

  • 绝对最低： 1 vCPU、1GB RAM。
  • 推荐： 如果你跑多个 channels、浏览器自动化或媒体 tools，建议 2GB RAM 或更多。
  • OS： Ubuntu LTS 或其它现代 Debian/Ubuntu。

如果你在 Windows 上，WSL2 是最容易的“VM 风格”部署，并且工具兼容性最好。见 Windows、VPS hosting。 如果你在 VM 中运行 macOS，见 macOS VM。

What is OpenClaw? ​

（OpenClaw 是什么？）

What is OpenClaw in one paragraph ​

（用一段话介绍 OpenClaw）

OpenClaw 是一个你在自己的设备上运行的个人 AI 助手。它会在你已经在用的消息界面里回复（WhatsApp、Telegram、Slack、Mattermost（插件）、Discord、Google Chat、Signal、iMessage、WebChat），并且在支持的平台上还提供语音 + 实时 Canvas。Gateway 是常驻运行的控制平面；助手才是产品本身。

What's the value proposition ​

（价值主张是什么？）

OpenClaw 不是“只是一个 Claude 包装壳”。它是一个本地优先的控制平面，让你可以在自己的硬件上运行一个强大的助手，通过你已在使用的聊天应用触达，并提供有状态会话、记忆和工具——而无需把你的工作流控制权交给托管式 SaaS。

亮点：

  • 你的设备，你的数据： 你可以把 Gateway 跑在任何地方（Mac、Linux、VPS），并把 workspace + 会话历史保留在本地。
  • 真实 channels，而不是网页沙盒： WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， 以及在支持的平台上提供移动端语音与 Canvas。
  • 模型无关： 可使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按 agent 路由 与故障切换。
  • 仅本地选项： 如果你愿意，可以运行本地模型，让所有数据都留在你的设备上。
  • 多 agent 路由： 按 channel、账号或任务拆分不同 agent，每个 agent 有自己的 workspace 和默认配置。
  • 开源且可改造： 可审计、可扩展、可自托管，不被供应商锁定。

文档：Gateway、Channels、Multi‑agent、 Memory。

I just set it up what should I do first ​

（我刚装好，第一步该做什么？）

一些很适合作为起手项目的方向：

  • 搭一个网站（WordPress、Shopify，或一个简单静态站）。
  • 做一个移动端 App 原型（大纲、页面、API 方案）。
  • 整理文件与文件夹（清理、命名、打标签）。
  • 连接 Gmail，自动做摘要或跟进。

它可以处理大任务，但最好的方式是把任务拆成阶段，并用 sub agents 并行推进。

What are the top five everyday use cases for OpenClaw ​

（OpenClaw 最常见的 5 个日常用法是什么？）

日常提升通常长这样：

  • 个人简报： 汇总你关心的收件箱、日历与新闻。
  • 研究与起草： 快速调研、摘要，以及邮件/文档的一稿。
  • 提醒与跟进： 由 cron 或 heartbeat 驱动的提醒与清单。
  • 浏览器自动化： 填表、采集数据、重复性的网页操作。
  • 跨设备协作： 从手机发起任务，让 Gateway 在服务器上跑起来，并在聊天里回传结果。

Can OpenClaw help with lead gen outreach ads and blogs for a SaaS ​

（OpenClaw 能帮 SaaS 做获客、外联、广告和博客吗？）

可以用于调研、筛选与起草：它能扫描网站、生成候选名单、汇总潜在客户信息，并写外联或广告文案草稿。

但对于外联发送或投放执行，务必把人留在闭环里：避免垃圾信息，遵守当地法律与平台政策，并在发送前人工审阅。最稳妥的方式是让 OpenClaw 起草，你来批准。

文档：Security。

What are the advantages vs Claude Code for web development ​

（与 Claude Code 相比，OpenClaw 在 Web 开发上有哪些优势？）

OpenClaw 是个人助理与协同层，而不是 IDE 的替代品。若你想在仓库里获得最快的“直接写代码”循环，用 Claude Code 或 Codex 更合适；当你需要更持久的记忆、跨设备访问与工具编排时，用 OpenClaw 更合适。

优势：

  • 跨会话的持久记忆 + workspace
  • 多平台访问（WhatsApp、Telegram、TUI、WebChat）
  • 工具编排（浏览器、文件、调度、hooks）
  • 常驻 Gateway（跑在 VPS 上，随时随地交互）
  • Nodes 用于本地浏览器/屏幕/摄像头/执行

Showcase: https://openclaw.ai/showcase

Skills and automation ​

（技能与自动化）

How do I customize skills without keeping the repo dirty ​

（如何在不把仓库弄脏的情况下自定义 skills？）

不要直接编辑仓库里的技能副本，改用托管覆盖（managed overrides）。把你的改动放到 ~/.openclaw/skills/<name>/SKILL.md（或在 ~/.openclaw/openclaw.json 里通过 skills.load.extraDirs 增加一个目录）。优先级是 <workspace>/skills > ~/.openclaw/skills > bundled，因此托管覆盖会在不触碰 git 的前提下生效。只有值得上游合并的改动才应该留在仓库里并以 PR 形式提交。

Can I load skills from a custom folder ​

（能从自定义目录加载 skills 吗？）

可以。在 ~/.openclaw/openclaw.json 里通过 skills.load.extraDirs 添加额外目录（优先级最低）。默认优先级仍是：<workspace>/skills → ~/.openclaw/skills → bundled → skills.load.extraDirs。clawhub 默认安装到 ./skills，OpenClaw 会把它视作 <workspace>/skills。

How can I use different models for different tasks ​

（如何让不同任务使用不同模型？）

目前支持的模式包括：

  • Cron jobs：隔离作业可以为每个 job 设置 model 覆盖。
  • Sub-agents：把任务路由到不同 agent，每个 agent 有不同的默认模型。
  • On-demand switch：随时用 /model 切换当前会话的模型。

参见：Cron jobs、Multi-Agent Routing、Slash commands。

The bot freezes while doing heavy work How do I offload that ​

（机器人做重活时卡住了，怎么把工作卸载出去？）

长任务或并行任务请用 sub-agents。Sub-agents 会在独立会话里运行，返回总结，并保持你的主聊天可响应。

你可以让机器人执行 "spawn a sub-agent for this task"，或直接使用 /subagents。 在聊天里用 /status 查看 Gateway 此刻在做什么（以及是否忙碌）。

Token 提示：长任务和 sub-agents 都会消耗 token。如果你在意成本，可以通过 agents.defaults.subagents.model 为 sub-agents 配一个更便宜的模型。

文档：Sub-agents。

Cron or reminders do not fire What should I check ​

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

Cron 运行在 Gateway 进程内部。如果 Gateway 不是持续运行的，定时任务就不会执行。

清单：

  • 确认 cron 已启用（cron.enabled），并且没有设置 OPENCLAW_SKIP_CRON。
  • 确认 Gateway 24/7 运行（没有睡眠/重启）。
  • 核对 job 的时区设置（--tz 与主机时区）。

调试：

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

文档：Cron jobs、Cron vs Heartbeat。

How do I install skills on Linux ​

（在 Linux 上如何安装 skills？）

使用 ClawHub（CLI），或把 skills 直接放进你的 workspace。macOS 的 Skills UI 在 Linux 上不可用。 在 https://clawhub.com 浏览技能。

安装 ClawHub CLI（任选一种包管理器）：

bash
npm i -g clawhub
bash
pnpm add -g clawhub

Can OpenClaw run tasks on a schedule or continuously in the background ​

（OpenClaw 能按计划定时运行任务，或在后台持续运行吗？）

可以，使用 Gateway 的调度器：

  • Cron jobs：用于按计划或循环执行的任务（重启后仍会保留）。
  • Heartbeat：用于“主会话”的周期性检查。
  • Isolated jobs：用于自主 agent，在后台产出总结或投递到聊天。

文档：Cron jobs、Cron vs Heartbeat、 Heartbeat。

Can I run Apple macOS only skills from Linux

（Linux 能运行仅限 macOS 的 skills 吗？）

不能直接运行。macOS skills 会受 metadata.openclaw.os 与所需二进制依赖的 gating 影响；只有当它们在 Gateway host 上“满足条件”时，才会出现在 system prompt 里。在 Linux 上，darwin-only 的 skills（例如 imsg、apple-notes、apple-reminders）不会加载，除非你覆盖这层 gating。

支持三种方式：

Option A - run the Gateway on a Mac (simplest).
在有 macOS 二进制依赖的机器上运行 Gateway，然后从 Linux 通过 remote mode 或 Tailscale 连接。因为 Gateway host 是 macOS，这些 skills 会正常加载。

Option B - use a macOS node (no SSH).
在 Linux 上运行 Gateway，配对一个 macOS node（菜单栏应用），并在 Mac 上把 Node Run Commands 设置为 "Always Ask" 或 "Always Allow"。当所需二进制存在于该 node 上时，OpenClaw 可以把 macOS-only skills 视为可用；agent 通过 nodes 工具运行这些 skills。如果你选择 "Always Ask"，在弹窗里批准 "Always Allow" 会把该命令加入 allowlist。

Option C - proxy macOS binaries over SSH (advanced).
继续把 Gateway 跑在 Linux 上，但把所需 CLI 二进制解析为在 Mac 上执行的 SSH wrapper。然后覆盖 skill，使其允许 Linux，从而保持“可用”。

  1. 为二进制创建一个 SSH wrapper（示例：imsg）：
    bash
    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"
  2. 在 Linux host 上把该 wrapper 放到 PATH 里（例如 ~/bin/imsg）。
  3. 覆盖 skill 元数据（workspace 或 ~/.openclaw/skills）以允许 Linux：
    markdown
    ---
name: imsg
description: iMessage/SMS CLI for listing chats, history, watch, and sending.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["imsg"] } } }
---
  4. 启动一个新会话，让 skills 快照刷新。

就 iMessage 而言，你也可以把 channels.imessage.cliPath 指向 SSH wrapper（OpenClaw 只需要 stdio）。参见 iMessage。

Do you have a Notion or HeyGen integration ​

（有 Notion 或 HeyGen 集成吗？）

目前没有内置集成。

可选方案：

  • Custom skill / plugin： 最适合做稳定可靠的 API 访问（Notion/HeyGen 都有 API）。
  • Browser automation： 无需写代码，但更慢且更脆弱。

如果你想按客户保留上下文（agency 工作流），一个简单模式是：

  • 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。
  • 在会话开始时让 agent 抓取该页面。

如果你希望原生集成，可以提一个 feature request，或自己写一个面向这些 API 的 skill。

安装 skills：

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

ClawHub 会把技能安装到你当前目录下的 ./skills（或者回退到你配置的 OpenClaw workspace）；OpenClaw 会在下一次会话把它视为 <workspace>/skills。如果你想跨多个 agent 共享 skills，把它们放到 ~/.openclaw/skills/<name>/SKILL.md。有些 skills 依赖通过 Homebrew 安装的二进制；在 Linux 上这通常意味着 Linuxbrew（见上面的 Homebrew Linux FAQ 条目）。参见 Skills 与 ClawHub。

How do I install the Chrome extension for browser takeover ​

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

使用内置安装器，然后在 Chrome 里加载“未打包扩展”：

bash
openclaw browser extension install
openclaw browser extension path

然后在 Chrome 中打开 chrome://extensions → 启用 “Developer mode” → “Load unpacked” → 选择该目录。

完整指南（包含远程 Gateway + 安全说明）：Chrome extension

如果 Gateway 就运行在 Chrome 所在的机器上（默认设置），你通常不需要额外操作。 如果 Gateway 运行在别的机器上，请在浏览器所在机器运行一个 node host，让 Gateway 可以代理浏览器动作。 你仍然需要在要控制的标签页上点击扩展按钮（它不会自动附着到页面）。

Sandboxing and memory ​

（沙盒与记忆）

Is there a dedicated sandboxing doc ​

（有单独的沙盒文档吗？）

有。见 Sandboxing。如果你是 Docker 相关的设置（例如把整个 gateway 放进 Docker，或使用 sandbox images），见 Docker。

Docker feels limited How do I enable full features ​

（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、Browser。

Can I keep DMs personal but make groups public sandboxed with one agent

（能否让私聊保持“个人/非沙盒”，但把群聊放进“公开/沙盒”，且只用一个 agent？）

可以——前提是你的私密流量主要是 DMs，而公开流量主要是 groups。

把 agents.defaults.sandbox.mode: "non-main" 设为 Docker，让 group/channel 会话（non-main keys）在 Docker 里跑，同时主 DM 会话仍留在宿主机。然后通过 tools.sandbox.tools 限制沙盒会话可用的工具。

配置讲解 + 示例配置：Groups: personal DMs + public groups

关键配置参考：Gateway configuration

How do I bind a host folder into the sandbox ​

（如何把宿主机目录 bind mount 到沙盒里？）

把 agents.defaults.sandbox.docker.binds 设为 ["host:path:mode"]（例如 "/home/user/src:/src:ro"）。全局 binds 会与 per-agent binds 合并；当 scope: "shared" 时会忽略 per-agent binds。对敏感内容请使用 :ro，并记住 bind mount 会绕过沙盒文件系统隔离。示例与安全说明见：Sandboxing 与 Sandbox vs Tool Policy vs Elevated。

How does memory work ​

（记忆是如何工作的？）

OpenClaw 的记忆本质上就是 agent workspace 里的 Markdown 文件：

  • 日记/当日笔记在 memory/YYYY-MM-DD.md
  • 精选的长期笔记在 MEMORY.md（仅 main/private 会话）

OpenClaw 还会在自动压缩（auto-compaction）之前做一次静默的 pre-compaction memory flush，提醒模型先把需要长期保留的信息写成耐久笔记。该流程只会在 workspace 可写时运行（只读沙盒会跳过）。见 Memory。

Memory keeps forgetting things How do I make it stick ​

（记忆总是忘，怎么让它“记住”？）

让机器人把事实写入 memory。长期笔记放在 MEMORY.md，短期上下文放在 memory/YYYY-MM-DD.md。

这仍是我们在持续改进的领域。你可以提醒模型去存记忆；它会知道该怎么做。如果还是经常忘，请确认 Gateway 每次运行都在使用同一个 workspace。

文档：Memory、Agent workspace。

Does semantic memory search require an OpenAI API key ​

（语义记忆搜索需要 OpenAI API key 吗？）

只有当你使用 OpenAI embeddings 时才需要。Codex OAuth 覆盖 chat/completions，但不授予 embeddings 权限，所以**登录 Codex（OAuth 或 Codex CLI login）**并不能让语义记忆搜索可用。OpenAI embeddings 仍需要真实的 API key（OPENAI_API_KEY 或 models.providers.openai.apiKey）。

如果你没有显式指定 provider，OpenClaw 会在能解析出 API key 时自动选择 provider（auth profiles、models.providers.*.apiKey 或环境变量）。如果能解析到 OpenAI key 就优先用 OpenAI；否则若能解析到 Gemini key 就用 Gemini；两者都没有时，memory search 会保持禁用，直到你完成配置。如果你配置了本地模型路径且存在，OpenClaw 会偏好 local。

如果你更想保持本地化，可以设置 memorySearch.provider = "local"（并可选设置 memorySearch.fallback = "none"）。如果你想用 Gemini embeddings，设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini 或 local 的 embedding models——具体配置见 Memory。

Does memory persist forever What are the limits ​

（记忆会永久保存吗？限制是什么？）

记忆文件保存在磁盘上，除非你手动删除，否则会一直存在。限制来自你的存储空间，而不是模型。会话上下文仍受模型上下文窗口限制，因此长对话可能会被压缩或截断；这也是 memory search 存在的原因——它只把相关片段拉回上下文。

文档：Memory、Context。

Where things live on disk ​

（磁盘上的数据都放在哪里）

Is all data used with OpenClaw saved locally ​

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

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

  • 默认本地： sessions、记忆文件、配置与 workspace 位于 Gateway host 上 （~/.openclaw + 你的 workspace 目录）。
  • 必然远端： 你发送给模型提供商（Anthropic/OpenAI 等）的消息会到它们的 API；聊天平台（WhatsApp/Telegram/Slack 等）也会在它们的服务器上保存消息数据。
  • 你可以控制足迹： 使用本地模型能让 prompts 留在你的机器上，但 channel 流量仍会经过对应平台的服务器。

相关：Agent workspace、Memory。

Where does OpenClaw store its data ​

（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 keys）
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json运行时 auth 缓存（自动管理）
$OPENCLAW_STATE_DIR/credentials/Provider 状态（例如 whatsapp/<accountId>/creds.json）
$OPENCLAW_STATE_DIR/agents/每个 agent 的状态（agentDir + sessions）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/对话历史与状态（按 agent）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json会话元数据（按 agent）

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

你的 workspace（AGENTS.md、记忆文件、skills 等）是单独的一套目录，通过 agents.defaults.workspace 配置（默认：~/.openclaw/workspace）。

Where should AGENTSmd SOULmd USERmd MEMORYmd live ​

（AGENTS.md/SOUL.md/USER.md/MEMORY.md 应该放在哪？）

这些文件应该放在 agent workspace 中，而不是 ~/.openclaw。

  • Workspace（每个 agent 一套）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、 MEMORY.md（或 memory.md）、memory/YYYY-MM-DD.md，可选 HEARTBEAT.md。
  • State dir（~/.openclaw）：配置、凭据、auth profiles、sessions、日志， 以及共享 skills（~/.openclaw/skills）。

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

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

如果机器人在重启后“忘记了”，请确认 Gateway 每次启动都使用同一个 workspace（并记住：remote mode 使用的是 gateway host’s workspace，而不是你本地笔记本的）。

提示：如果你希望某个行为或偏好长期稳定，请让机器人把它写入 AGENTS.md 或 MEMORY.md，不要只依赖聊天记录。

参见 Agent workspace 与 Memory。

（推荐的备份策略是什么？）

把你的 agent workspace 放进一个私有 git 仓库，并备份到某个私密位置（例如 GitHub private）。这样可以连同 memory + AGENTS/SOUL/USER 文件一起备份，之后也能恢复助手的“心智”。

不要提交 ~/.openclaw 下的任何内容（credentials、sessions、tokens）。如果你需要完整恢复，请分别备份 workspace 与 state directory（见上面的迁移问题）。

文档：Agent workspace。

How do I completely uninstall OpenClaw ​

（如何彻底卸载 OpenClaw？）

见专门指南：Uninstall。

Can agents work outside the workspace ​

（agent 能在 workspace 之外工作吗？）

可以。workspace 是默认 cwd 与记忆锚点，并不是硬性沙盒。相对路径会解析到 workspace 内，但在未启用沙盒时，绝对路径仍可访问宿主机其他位置。如果你需要隔离，请使用 agents.defaults.sandbox 或 per‑agent 沙盒设置。如果你希望某个 repo 成为默认工作目录，把该 agent 的 workspace 指向 repo 根目录即可。OpenClaw 仓库只是源代码；除非你明确希望 agent 在仓库内工作，否则建议把 workspace 与仓库分开。

示例（把 repo 作为默认 cwd）：

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

Im in remote mode where is the session store ​

（我在 remote mode，session 存在哪？）

Session 状态由 gateway host 持有。如果你处于 remote mode，你关心的 session store 在远端机器上，而不是你本地笔记本上。参见 Session management。

Config basics ​

（配置基础）

What format is the config Where is it ​

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

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

$OPENCLAW_CONFIG_PATH

如果文件不存在，它会使用相对安全的默认值（其中包括默认 workspace：~/.openclaw/workspace）。

I set gatewaybind lan or tailnet and now nothing listens the UI says unauthorized ​

（我把 gateway 绑定到 lan/tailnet 后就连不上了，UI 还提示 unauthorized）

非 loopback 绑定必须启用鉴权。请配置 gateway.auth.mode + gateway.auth.token（或使用 OPENCLAW_GATEWAY_TOKEN）。

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

注意：

  • gateway.remote.token 只用于远程 CLI 调用；它不会启用本地 gateway auth。
  • Control UI 通过 connect.params.auth.token 鉴权（存储在 app/UI settings）。避免把 token 放在 URL 里。

Why do I need a token on localhost now ​

（为什么现在连 localhost 也要 token？）

wizard 默认会生成一个 gateway token（即便是 loopback），因此本地 WS client 必须鉴权。这会阻止其它本地进程随意调用 Gateway。把 token 粘贴到 Control UI settings（或你的 client config）里即可连接。

如果你确实想让 loopback 开放访问，可以从配置里移除 gateway.auth。你也可以随时让 doctor 生成 token：openclaw doctor --generate-gateway-token。

Do I have to restart after changing config ​

（改了配置一定要重启吗？）

Gateway 会监听配置变化，并支持热重载：

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

How do I enable web search and web fetch ​

（如何启用 web search 和 web fetch？）

web_fetch 不需要 API key 就能工作。web_search 需要 Brave Search API key。推荐： 运行 openclaw configure --section web 把 key 写入 tools.web.search.apiKey。也可以通过环境变量为 Gateway 进程设置 BRAVE_API_KEY。

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

注意：

  • 如果你使用 allowlists，请添加 web_search/web_fetch 或 group:web。
  • web_fetch 默认启用（除非显式禁用）。
  • daemon 会从 ~/.openclaw/.env（或 service 环境）读取 env vars。

文档：Web tools。

How do I run a central Gateway with specialized workers across devices ​

（如何用一个中心化 Gateway，在多设备上运行专门的 worker？）

常见模式是：一个 Gateway（例如 Raspberry Pi）+ nodes + agents：

  • Gateway（中枢）： 负责 channels（Signal/WhatsApp）、路由与 sessions。
  • Nodes（设备）： Mac/iOS/Android 作为外设接入，暴露本地工具（system.run、canvas、camera）。
  • Agents（工人）： 为特定角色拆分不同“大脑/workspace”（例如 “Hetzner ops”“Personal data”）。
  • Sub‑agents： 当你需要并行时，从主 agent 派生后台工作。
  • TUI： 连接到 Gateway 并切换 agents/sessions。

文档：Nodes、Remote access、Multi-Agent Routing、Sub-agents、TUI。

Can the OpenClaw browser run headless ​

（OpenClaw browser 能 headless 运行吗？）

可以，这是一个配置项：

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

默认是 false（headful）。在某些网站上，headless 更容易触发反自动化检测。见 Browser。

headless 使用同一套 Chromium 引擎，能覆盖大多数自动化场景（表单、点击、抓取、登录）。主要差异：

  • 没有可见的浏览器窗口（如果你需要视觉反馈，请用截图）。
  • 有些站点对 headless 更严格（CAPTCHA、反爬/反 bot）。例如 X/Twitter 经常会阻止 headless 会话。

How do I use Brave for browser control ​

（如何用 Brave 做浏览器控制？）

把 browser.executablePath 设为你的 Brave 二进制路径（或任意 Chromium 系浏览器），然后重启 Gateway。 完整配置示例见 Browser。

Remote gateways + nodes ​

（远程 Gateway + nodes）

How do commands propagate between Telegram the gateway and nodes ​

（Telegram、gateway 与 nodes 之间的命令是怎么流转的？）

Telegram 消息由 gateway 处理。gateway 先运行 agent，只有在需要 node 工具时，才会通过 Gateway WebSocket 调用 nodes：

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

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

How can my agent access my computer if the Gateway is hosted remotely ​

（如果 Gateway 部署在远端，我的 agent 怎么访问我的电脑？）

简短回答：把你的电脑配对成一个 node。Gateway 跑在别处，但它可以通过 Gateway WebSocket 在你的本地机器上调用 node.* 工具（screen、camera、system）。

常见搭建步骤：

  1. 把 Gateway 跑在一台常开主机上（VPS/家庭服务器）。
  2. 让 Gateway host + 你的电脑加入同一个 tailnet。
  3. 确保 Gateway 的 WS 可达（tailnet bind 或 SSH tunnel）。
  4. 在本地打开 macOS 应用，并用 Remote over SSH（或直连 tailnet）连接， 这样它就能注册为一个 node。
  5. 在 Gateway 上批准该 node：
    bash
    openclaw nodes pending
openclaw nodes approve <requestId>

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

安全提示：配对一个 macOS node 意味着允许在该机器上执行 system.run。只配对你信任的设备，并阅读 Security。

文档：Nodes、Gateway protocol、macOS remote mode、Security。

Tailscale is connected but I get no replies What now ​

（Tailscale 已连接但收不到回复，怎么办？）

先检查基础项：

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

然后核对鉴权与路由：

  • 如果你用了 Tailscale Serve，确认 gateway.auth.allowTailscale 配置正确。
  • 如果你通过 SSH tunnel 连接，确认本地 tunnel 正在运行并且指向正确端口。
  • 确认 allowlists（DM 或 group）包含你的账号。

文档：Tailscale、Remote access、Channels。

Can two OpenClaw instances talk to each other local VPS ​

（两套 OpenClaw 实例能互相对话吗？比如本地 + VPS）

可以。虽然没有内置的 “bot-to-bot” bridge，但你可以用几种可靠方式把它们串起来：

最简单： 用一个两边都能接入的普通聊天 channel（Telegram/Slack/WhatsApp）。让 Bot A 发消息给 Bot B，然后 Bot B 像平常一样回复。

CLI bridge（通用）： 跑一个脚本调用另一端 Gateway，例如用 openclaw agent --message ... --deliver，投递到另一只 bot 监听的聊天。如果其中一只 bot 在远端 VPS 上，把你的 CLI 通过 SSH/Tailscale 指向那台远端 Gateway（见 Remote access）。

示例模式（在能访问目标 Gateway 的机器上运行）：

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

提示：加一个护栏避免两只 bot 无限互相回复（比如 mention-only、channel allowlists，或一条“不要回复 bot 消息”的规则）。

文档：Remote access、Agent CLI、Agent send。

Do I need separate VPSes for multiple agents ​

（多个 agent 需要分别用不同的 VPS 吗？）

不需要。一个 Gateway 可以承载多个 agents，每个 agent 都有自己的 workspace、模型默认值与路由。这是常见且推荐的方式，比“每个 agent 一台 VPS”更便宜也更简单。

只有当你需要硬隔离（安全边界）或你不想共享的一套完全不同的配置时，才考虑分开用不同 VPS。否则就保持一个 Gateway，使用多个 agents 或 sub-agents。

Is there a benefit to using a node on my personal laptop instead of SSH from a VPS ​

（把个人笔记本作为 node 相比从 VPS 用 SSH，有什么好处？）

有。nodes 是从远端 Gateway 访问你笔记本的第一等方式，它带来的不仅是 shell 访问。Gateway 可运行在 macOS/Linux（Windows 通过 WSL2），本身很轻量（小 VPS 或树莓派级别设备即可；4 GB RAM 通常足够），所以常见架构是“常开 host + 笔记本作为 node”。

  • 不需要入站 SSH。 nodes 会主动连接 Gateway WebSocket，并通过设备配对工作。
  • 更安全的执行控制。 笔记本上的 system.run 由 node allowlists/审批机制进行 gating。
  • 更多设备工具。 除了 system.run，nodes 还能暴露 canvas、camera、screen。
  • 本地浏览器自动化。 Gateway 跑在 VPS 上，但 Chrome 在本地跑，通过 Chrome extension + 笔记本上的 node host 中继控制。

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

文档：Nodes、Nodes CLI、Chrome extension。

Should I install on a second laptop or just add a node ​

（第二台笔记本要装第二套 Gateway，还是只加一个 node？）

如果你只需要第二台笔记本上的本地工具（screen/camera/exec），把它加成一个 node 即可。这能保持单一 Gateway，避免重复配置。本地 node 工具目前仅支持 macOS，但我们计划扩展到其它 OS。

只有当你需要硬隔离或两套完全独立的 bots 时，才安装第二套 Gateway。

文档：Nodes、Nodes CLI、Multiple gateways。

Do nodes run a gateway service ​

（node 会运行一个 gateway 服务吗？）

不会。除非你刻意运行隔离 profiles（见 Multiple gateways），否则每台 host 只应该运行一个 gateway。nodes 是连接到 gateway 的外设（iOS/Android nodes，或 macOS 菜单栏应用里的 “node mode”）。对于 headless node host 与 CLI 控制，见 Node host CLI。

gateway、discovery 与 canvasHost 的变更需要完整重启。

Is there an API RPC way to apply config ​

（有没有 API/RPC 可以应用配置？）

有。config.apply 会校验并写入完整配置，并在流程中重启 Gateway。

configapply wiped my config How do I recover and avoid this ​

（config.apply 把我的配置清空了，怎么恢复并避免再次发生？）

config.apply 会替换整个配置。如果你发送的是一个“部分对象”，其它字段就会被移除。

恢复：

  • 从备份恢复（git，或你拷贝过的 ~/.openclaw/openclaw.json）。
  • 如果没有备份，重新运行 openclaw doctor，并重新配置 channels/models。
  • 如果这是意外行为，请提交 bug，并附上你最后一次已知的配置或任何备份。
  • 本地 coding agent 往往也能从日志或历史中重建一份可用配置。

避免：

  • 小改动用 openclaw config set。
  • 交互式编辑用 openclaw configure。

文档：Config、Configure、Doctor。

What's a minimal sane config for a first install ​

（首次安装，一个最小但够用的配置长什么样？）

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

这会设置你的 workspace，并限制“谁可以触发机器人”。

How do I set up Tailscale on a VPS and connect from my Mac ​

（如何在 VPS 上配置 Tailscale，并从 Mac 连接？）

最小步骤：

  1. 在 VPS 上安装并登录
    bash
    curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
  2. 在 Mac 上安装并登录
    • 使用 Tailscale app，并登录到同一个 tailnet。
  3. 启用 MagicDNS（推荐）
    • 在 Tailscale 管理后台启用 MagicDNS，让 VPS 有一个稳定名称。
  4. 使用 tailnet hostname
    • SSH：ssh user@your-vps.tailnet-xxxx.ts.net
    • Gateway WS：ws://your-vps.tailnet-xxxx.ts.net:18789

如果你想在不使用 SSH 的情况下访问 Control UI，可以在 VPS 上启用 Tailscale Serve：

bash
openclaw gateway --tailscale serve

这会让 gateway 仍绑定在 loopback 上，并通过 Tailscale 暴露 HTTPS。见 Tailscale。

How do I connect a Mac node to a remote Gateway Tailscale Serve ​

（如何把 Mac node 连接到远程 Gateway（Tailscale Serve）？）

Serve 会暴露 Gateway Control UI + WS。Nodes 通过同一个 Gateway WS endpoint 连接。

推荐配置：

  1. 确保 VPS + Mac 在同一个 tailnet。
  2. 在 macOS app 中使用 Remote mode（SSH target 可以是 tailnet hostname）。 app 会对 Gateway 端口做隧道，并以 node 身份连接。
  3. 在 gateway 上批准该 node：
    bash
    openclaw nodes pending
openclaw nodes approve <requestId>

文档：Gateway protocol、Discovery、macOS remote mode。

Env vars and .env loading ​

（环境变量与 .env 加载）

How does OpenClaw load environment variables ​

（OpenClaw 如何加载环境变量？）

OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取 env vars，并额外加载：

  • 当前工作目录下的 .env
  • 全局兜底的 .env：~/.openclaw/.env（也就是 $OPENCLAW_STATE_DIR/.env）

这两个 .env 都不会覆盖进程里已经存在的 env vars。

你也可以在配置里以内联方式定义 env vars（仅当进程环境里缺失时才会应用）：

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

完整优先级与来源见 /environment。

I started the Gateway via the service and my env vars disappeared What now ​

（我通过 service 启动 Gateway 后，环境变量“消失”了，怎么办？）

两种常见修复：

  1. 把缺失的 key 写到 ~/.openclaw/.env，这样即便 service 没有继承你的 shell env，也能被拾取。
  2. 启用 shell import（可选的便捷功能）：
json5
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

这会运行你的 login shell，并只导入“预期但缺失”的 keys（永不覆盖已有值）。对应的环境变量是： OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

I set COPILOTGITHUBTOKEN but models status shows Shell env off Why ​

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

openclaw models status 只是在报告是否启用了 shell env import。“Shell env: off” 并不表示你的 env vars 不存在——它只是表示 OpenClaw 不会自动加载你的 login shell。

如果 Gateway 以 service 方式运行（launchd/systemd），它通常不会继承你的 shell 环境。你可以用以下任一方式修复：

  1. 把 token 写进 ~/.openclaw/.env：
    COPILOT_GITHUB_TOKEN=...
  2. 或启用 shell import（env.shellEnv.enabled: true）。
  3. 或把它加入配置的 env 区块（仅在缺失时生效）。

然后重启 gateway 并重新检查：

bash
openclaw models status

Copilot token 从 COPILOT_GITHUB_TOKEN 读取（也支持 GH_TOKEN / GITHUB_TOKEN）。 参见 /concepts/model-providers 与 /environment。

Sessions & multiple chats ​

（会话与多聊天）

How do I start a fresh conversation ​

（如何开始一段全新的对话？）

发送 /new 或 /reset（作为单独一条消息）。参见 Session management。

Do sessions reset automatically if I never send new ​

（如果我从不发 /new，会话会自动重置吗？）

会。会话会在 session.idleMinutes 后过期（默认 60）。下一条消息会为该 chat key 启动一个新的 session id。它不会删除历史 transcript——只是开启一个新会话。

json5
{
  session: {
    idleMinutes: 240,
  },
}

Is there a way to make a team of OpenClaw instances one CEO and many agents ​

（能否做成“一个 CEO + 多个 agent”的 OpenClaw 团队？）

可以，通过 multi-agent routing 与 sub-agents。你可以创建一个 coordinator agent，再创建几个拥有各自 workspace 与模型的 worker agents。

不过，这更适合作为一个有趣的实验：它很吃 token，且常常不如“一个 bot + 多个独立 sessions”高效。我们更常见的设想是：你对话的是同一个 bot，但用不同 sessions 并行推进；需要时再让它 spawn sub-agents。

文档：Multi-agent routing、Sub-agents、Agents CLI。

Why did context get truncated midtask How do I prevent it ​

（为什么任务中途 context 被截断了？怎么避免？）

Session context 受模型上下文窗口限制。超长对话、大体积工具输出或大量文件都可能触发 compaction 或 truncation。

有帮助的做法：

  • 让机器人总结当前状态并写入一个文件。
  • 长任务前用 /compact，切换话题时用 /new。
  • 把关键上下文放在 workspace 里，并让机器人按需读回。
  • 长任务或并行任务用 sub-agents，让主聊天保持更“轻”。
  • 如果经常发生，选择更大上下文窗口的模型。

How do I completely reset OpenClaw but keep it installed ​

（如何彻底重置 OpenClaw，但保留安装？）

使用 reset 命令：

bash
openclaw reset

非交互的完整重置：

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

然后重新运行 onboarding：

bash
openclaw onboard --install-daemon

注意：

  • onboarding wizard 如果检测到已有配置，也会提供 Reset。见 Wizard。
  • 如果你使用了 profiles（--profile / OPENCLAW_PROFILE），请分别重置各自的 state dir（默认是 ~/.openclaw-<profile>）。
  • Dev reset：openclaw gateway --dev --reset（仅 dev；会清空 dev 配置 + credentials + sessions + workspace）。

Im getting context too large errors how do I reset or compact ​

（我遇到 context too large，应该 reset 还是 compact？）

可以用以下之一：

  • Compact（保留对话，但把更早的轮次总结压缩）：

    /compact

    或使用 /compact <instructions> 来引导总结方式。

  • Reset（针对同一 chat key 启动新的 session ID）：

    /new
/reset

如果仍频繁发生：

  • 启用或调优 session pruning（agents.defaults.contextPruning）以裁剪旧的工具输出。
  • 使用更大上下文窗口的模型。

文档：Compaction、Session pruning、Session management。

Why am I seeing LLM request rejected messagesNcontentXtooluseinput Field required ​

（为什么我会看到 LLM request rejected ... tool_use.input Field required 这类报错？）

这是一个 provider 的校验错误：模型输出了一个 tool_use block，但缺少必填的 input。这通常意味着 session 历史已经过期或损坏（常见于超长线程，或 tool/schema 发生变更之后）。

修复：用 /new（单独一条消息）开启一个新会话。

Why am I getting heartbeat messages every 30 minutes ​

（为什么我每 30 分钟会收到 heartbeat 消息？）

默认 heartbeat 每 30m 运行一次。你可以调优或禁用它：

json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}

如果 HEARTBEAT.md 存在但基本为空（只有空行与类似 # Heading 的 markdown 标题），OpenClaw 会跳过 heartbeat 以节省 API 调用。 如果文件不存在，heartbeat 仍会运行，并由模型决定要做什么。

per-agent 覆盖使用 agents.list[].heartbeat。文档：Heartbeat。

Do I need to add a bot account to a WhatsApp group ​

（需要把“机器人账号”加入 WhatsApp 群吗？）

不需要。OpenClaw 运行在你自己的账号上，所以只要你在群里，OpenClaw 就能看到群消息。 默认情况下，群内回复会被阻止，直到你允许发送者（groupPolicy: "allowlist"）。

如果你希望只有你能触发群内回复：

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

How do I get the JID of a WhatsApp group ​

（如何获取 WhatsApp 群的 JID？）

方案 1（最快）：tail 日志，然后在群里发一条测试消息：

bash
openclaw logs --follow --json

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

方案 2（已完成配置/allowlist 时）：从目录里列出 groups：

bash
openclaw directory groups list --channel whatsapp

文档：WhatsApp、Directory、Logs。

Why doesnt OpenClaw reply in a group ​

（为什么 OpenClaw 在群里不回复？）

两种常见原因：

  • 默认开启了 mention gating：你必须 @mention 机器人（或匹配 mentionPatterns）。
  • 你配置了 channels.whatsapp.groups 但没有包含 "*"，并且该群不在 allowlist 里。

参见 Groups 与 Group messages。

Do groupsthreads share context with DMs ​

（群/线程会和私聊共享上下文吗？）

默认情况下，私聊会折叠到 main session。群/频道有各自的 session keys，而 Telegram topics / Discord threads 也都是独立 sessions。参见 Groups 与 Group messages。

How many workspaces and agents can I create ​

（我最多能创建多少个 workspaces 和 agents？）

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

  • 磁盘增长： sessions + transcripts 存在 ~/.openclaw/agents/<agentId>/sessions/ 下。
  • Token 成本： agent 越多，越可能产生更多并发的模型调用。
  • 运维开销： 每个 agent 的 auth profiles、workspaces 与 channel 路由。

建议：

  • 每个 agent 保持一个活跃 workspace（agents.defaults.workspace）。
  • 如果磁盘增长，清理旧 sessions（删除 JSONL 或 store 条目）。
  • 用 openclaw doctor 发现游离 workspaces 与 profile 不匹配。

Can I run multiple bots or chats at the same time Slack and how should I set that up ​

（我能同时跑多个 bots/多个聊天吗？例如 Slack；应该怎么搭？）

可以。使用 Multi‑Agent Routing 跑多个相互隔离的 agents，并按 channel/account/peer 路由入站消息。Slack 作为 channel 受支持，并且可以绑定到特定 agents。

浏览器访问很强大，但并不等于“人能做什么它都能做”：反 bot、CAPTCHA 与 MFA 仍可能阻断自动化。想要最可靠的浏览器控制，建议在运行浏览器的那台机器上使用 Chrome extension relay（Gateway 可以放在任何地方）。

最佳实践搭建：

  • 常开 Gateway host（VPS/Mac mini）。
  • 每个角色一个 agent（bindings）。
  • 把 Slack channel 绑定到对应 agents。
  • 需要时通过 extension relay（或 node）使用本地浏览器。

文档：Multi‑Agent Routing、Slack、Browser、Chrome extension、Nodes。

Models: defaults, selection, aliases, switching ​

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

What is the default model ​

（默认模型是什么？）

OpenClaw 的默认模型由你配置的以下字段决定：

agents.defaults.model.primary

模型用 provider/model 引用（例如：anthropic/claude-opus-4-5）。如果你省略 provider，OpenClaw 目前会把它当作一个临时的兼容兜底（默认假设为 anthropic），但你仍然应该显式设置 provider/model。

What model do you recommend ​

（推荐用什么模型？）

推荐默认： anthropic/claude-opus-4-5。
不错的替代： anthropic/claude-sonnet-4-5。
稳定（但“性格”更少）： openai/gpt-5.2——几乎和 Opus 一样好，只是更少人格化。
预算： zai/glm-4.7。

MiniMax M2.1 有单独文档：MiniMax 与 Local models。

经验法则：高风险/高价值工作用你负担得起的最好模型，日常聊天或摘要用更便宜的模型。你可以按 agent 路由模型，并使用 sub-agents 并行长任务（每个 sub-agent 都会消耗 tokens）。见 Models 与 Sub-agents。

强提醒：更弱或过度量化（over-quantized）的模型更容易受到 prompt injection 影响，也更容易产生不安全行为。见 Security。

更多背景：Models。

Can I use selfhosted models llamacpp vLLM Ollama ​

（我能用自托管模型吗？例如 llama.cpp / vLLM / Ollama）

可以。如果你的本地服务暴露了 OpenAI 兼容 API，你可以把一个自定义 provider 指向它。Ollama 也被直接支持，而且通常是最简单的路径。

安全提示：更小或严重量化的模型更容易被 prompt injection 影响。对任何能使用工具的 bot，我们强烈建议使用大模型。如果你仍想用小模型，请启用沙盒并使用严格的工具 allowlists。

文档：Ollama、Local models、 Model providers、Security、 Sandboxing。

How do I switch models without wiping my config ​

（如何切换模型但不把配置弄没？）

使用模型命令或只编辑 model 字段，避免整份配置替换。

安全选项：

  • 在聊天里用 /model（快捷、按 session 生效）
  • openclaw models set ...（只更新模型配置）
  • openclaw configure --section models（交互式）
  • 编辑 ~/.openclaw/openclaw.json 中的 agents.defaults.model

除非你确实想替换整份配置，否则不要用“部分对象”去跑 config.apply。 如果你已经误覆盖了配置，请从备份恢复，或重新运行 openclaw doctor 修复。

文档：Models、Configure、Config、Doctor。

What do OpenClaw, Flawd, and Krill use for models ​

（OpenClaw、Flawd、Krill 分别用什么模型？）

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

How do I switch models on the fly without restarting ​

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

把 /model 作为单独一条消息发送：

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

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

/model（以及 /model list）会展示一个紧凑的带编号选择器，你可以按编号选择：

/model 3

你也可以为 provider 强制指定某个 auth profile（按 session 生效）：

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

提示：/model status 会显示当前激活的是哪个 agent、正在使用哪个 auth-profiles.json 文件，以及下一步将尝试哪个 auth profile。 在可用时，它还会显示已配置的 provider endpoint（baseUrl）与 API 模式（api）。

How do I unpin a profile I set with profile

（如何取消我用 @profile 固定的 profile？）

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

/model anthropic/claude-opus-4-5

如果你想回到默认值，可以在 /model 里选择默认项（或发送 /model <default provider/model>）。 用 /model status 确认当前激活的 auth profile。

Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding ​

（能否日常用 GPT 5.2，写代码用 Codex 5.2？）

可以。把其中一个设为默认，按需切换：

  • 快捷切换（按 session）： 日常用 /model gpt-5.2，写代码用 /model gpt-5.2-codex。
  • 默认 + 切换： 把 agents.defaults.model.primary 设为 openai-codex/gpt-5.2，写代码时切换到 openai-codex/gpt-5.2-codex（或反过来）。
  • Sub-agents： 把 coding 任务路由到默认模型不同的 sub-agents。

参见 Models 与 Slash commands。

Why do I see Model is not allowed and then no reply ​

（为什么我看到 Model is not allowed 然后就不回复了？）

如果设置了 agents.defaults.models，它会成为 /model 以及任何 session overrides 的允许列表。选择一个不在列表里的模型会返回：

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

这个错误会替代正常回复返回。修复：把模型加入 agents.defaults.models、移除 allowlist，或从 /model list 里选择一个模型。

Why do I see Unknown model minimaxMiniMaxM21 ​

（为什么我看到 Unknown model minimaxMiniMaxM21？）

这表示 provider 没有配置（没有找到 MiniMax 的 provider config 或 auth profile），因此模型无法解析。针对该检测的修复会在 2026.1.12 中提供（写作时尚未发布）。

修复清单：

  1. 升级到 2026.1.12（或从源码 main 运行），然后重启 gateway。
  2. 确认 MiniMax 已配置（wizard 或 JSON），或确保 env/auth profiles 中存在 MiniMax API key，以便注入 provider。
  3. 使用精确的模型 id（大小写敏感）：minimax/MiniMax-M2.1 或 minimax/MiniMax-M2.1-lightning。
  4. 运行：
    bash
    openclaw models list
    然后从列表中选择（或在聊天里用 /model list）。

参见 MiniMax 与 Models。

Can I use MiniMax as my default and OpenAI for complex tasks ​

Yes. Use MiniMax as the default and switch models per session when needed. Fallbacks are for errors, not “hard tasks,” so use /model or a separate agent.

Option A: switch per session

json5
{
  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" },
      },
    },
  },
}

Then:

/model gpt

Option B: separate agents

  • Agent A default: MiniMax
  • Agent B default: OpenAI
  • Route by agent or use /agent to switch

Docs: Models, Multi-Agent Routing, MiniMax, OpenAI.

Are opus sonnet gpt builtin shortcuts ​

Yes. OpenClaw ships a few default shorthands (only applied when the model exists in agents.defaults.models):

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

If you set your own alias with the same name, your value wins.

How do I defineoverride model shortcuts aliases ​

Aliases come from agents.defaults.models.<modelId>.alias. Example:

json5
{
  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" },
      },
    },
  },
}

Then /model sonnet (or /<alias> when supported) resolves to that model ID.

How do I add models from other providers like OpenRouter or ZAI ​

OpenRouter (pay‑per‑token; many models):

json5
{
  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 models):

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

If you reference a provider/model but the required provider key is missing, you’ll get a runtime auth error (e.g. No API key found for provider "zai").

No API key found for provider after adding a new agent

This usually means the new agent has an empty auth store. Auth is per-agent and stored in:

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

Fix options:

  • Run openclaw agents add <id> and configure auth during the wizard.
  • Or copy auth-profiles.json from the main agent’s agentDir into the new agent’s agentDir.

Do not reuse agentDir across agents; it causes auth/session collisions.

Model failover and “All models failed” ​

How does failover work ​

Failover happens in two stages:

  1. Auth profile rotation within the same provider.
  2. Model fallback to the next model in agents.defaults.model.fallbacks.

Cooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate‑limited or temporarily failing.

What does this error mean ​

No credentials found for profile "anthropic:default"

It means the system attempted to use the auth profile ID anthropic:default, but could not find credentials for it in the expected auth store.

Fix checklist for No credentials found for profile anthropicdefault ​

  • Confirm where auth profiles live (new vs legacy paths)
    • Current: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Legacy: ~/.openclaw/agent/* (migrated by openclaw doctor)
  • Confirm your env var is loaded by the Gateway
    • If you set ANTHROPIC_API_KEY in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in ~/.openclaw/.env or enable env.shellEnv.
  • Make sure you’re editing the correct agent
    • Multi‑agent setups mean there can be multiple auth-profiles.json files.
  • Sanity‑check model/auth status
    • Use openclaw models status to see configured models and whether providers are authenticated.

Fix checklist for No credentials found for profile anthropic

This means the run is pinned to an Anthropic auth profile, but the Gateway can’t find it in its auth store.

  • Use a setup-token
    • Run claude setup-token, then paste it with openclaw models auth setup-token --provider anthropic.
    • If the token was created on another machine, use openclaw models auth paste-token --provider anthropic.
  • If you want to use an API key instead
    • Put ANTHROPIC_API_KEY in ~/.openclaw/.env on the gateway host.
    • Clear any pinned order that forces a missing profile:
      bash
      openclaw models auth order clear --provider anthropic
  • Confirm you’re running commands on the gateway host
    • In remote mode, auth profiles live on the gateway machine, not your laptop.

Why did it also try Google Gemini and fail ​

If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw will try it during model fallback. If you haven’t configured Google credentials, you’ll see No API key found for provider "google".

Fix: either provide Google auth, or remove/avoid Google models in agents.defaults.model.fallbacks / aliases so fallback doesn’t route there.

LLM request rejected message thinking signature required google antigravity

Cause: the session history contains thinking blocks without signatures (often from an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.

Fix: OpenClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a new session or set /thinking off for that agent.

Auth profiles: what they are and how to manage them ​

Related: /concepts/oauth (OAuth flows, token storage, multi-account patterns)

What is an auth profile ​

An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:

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

What are typical profile IDs ​

OpenClaw uses provider‑prefixed IDs like:

  • anthropic:default (common when no email identity exists)
  • anthropic:<email> for OAuth identities
  • custom IDs you choose (e.g. anthropic:work)

Can I control which auth profile is tried first ​

Yes. Config supports optional metadata for profiles and an ordering per provider (auth.order.<provider>). This does not store secrets; it maps IDs to provider/mode and sets rotation order.

OpenClaw may temporarily skip a profile if it’s in a short cooldown (rate limits/timeouts/auth failures) or a longer disabled state (billing/insufficient credits). To inspect this, run openclaw models status --json and check auth.unusableProfiles. Tuning: auth.cooldowns.billingBackoffHours*.

You can also set a per-agent order override (stored in that agent’s auth-profiles.json) via the CLI:

bash
# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic

To target a specific agent:

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

OAuth vs API key whats the difference ​

OpenClaw supports both:

  • OAuth often leverages subscription access (where applicable).
  • API keys use pay‑per‑token billing.

The wizard explicitly supports Anthropic setup-token and OpenAI Codex OAuth and can store API keys for you.

Gateway: ports, “already running”, and remote mode ​

What port does the Gateway use ​

gateway.port controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.).

Precedence:

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

Why does openclaw gateway status say Runtime running but RPC probe failed ​

Because “running” is the supervisor’s view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling status.

Use openclaw gateway status and trust these lines:

  • Probe target: (the URL the probe actually used)
  • Listening: (what’s actually bound on the port)
  • Last gateway error: (common root cause when the process is alive but the port isn’t listening)

Why does openclaw gateway status show Config cli and Config service different ​

You’re editing one config file while the service is running another (often a --profile / OPENCLAW_STATE_DIR mismatch).

Fix:

bash
openclaw gateway install --force

Run that from the same --profile / environment you want the service to use.

What does another gateway instance is already listening mean ​

OpenClaw enforces a runtime lock by binding the WebSocket listener immediately on startup (default ws://127.0.0.1:18789). If the bind fails with EADDRINUSE, it throws GatewayLockError indicating another instance is already listening.

Fix: stop the other instance, free the port, or run with openclaw gateway --port <port>.

How do I run OpenClaw in remote mode client connects to a Gateway elsewhere ​

Set gateway.mode: "remote" and point to a remote WebSocket URL, optionally with a token/password:

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

Notes:

  • openclaw gateway only starts when gateway.mode is local (or you pass the override flag).
  • The macOS app watches the config file and switches modes live when these values change.

The Control UI says unauthorized or keeps reconnecting What now ​

Your gateway is running with auth enabled (gateway.auth.*), but the UI is not sending the matching token/password.

Facts (from code):

  • The Control UI stores the token in browser localStorage key openclaw.control.settings.v1.
  • The UI can import ?token=... (and/or ?password=...) once, then strips it from the URL.

Fix:

  • Fastest: openclaw dashboard (prints + copies tokenized link, tries to open; shows SSH hint if headless).
  • If you don’t have a token yet: openclaw doctor --generate-gateway-token.
  • If remote, tunnel first: ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/?token=....
  • Set gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN) on the gateway host.
  • In the Control UI settings, paste the same token (or refresh with a one-time ?token=... link).
  • Still stuck? Run openclaw status --all and follow Troubleshooting. See Dashboard for auth details.

I set gatewaybind tailnet but it cant bind nothing listens ​

tailnet bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn’t on Tailscale (or the interface is down), there’s nothing to bind to.

Fix:

  • Start Tailscale on that host (so it has a 100.x address), or
  • Switch to gateway.bind: "loopback" / "lan".

Note: tailnet is explicit. auto prefers loopback; use gateway.bind: "tailnet" when you want a tailnet-only bind.

Can I run multiple Gateways on the same host ​

Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation.

Yes, but you must isolate:

  • OPENCLAW_CONFIG_PATH (per‑instance config)
  • OPENCLAW_STATE_DIR (per‑instance state)
  • agents.defaults.workspace (workspace isolation)
  • gateway.port (unique ports)

Quick setup (recommended):

  • Use openclaw --profile <name> … per instance (auto-creates ~/.openclaw-<name>).
  • Set a unique gateway.port in each profile config (or pass --port for manual runs).
  • Install a per-profile service: openclaw --profile <name> gateway install.

Profiles also suffix service names (bot.molt.<profile>; legacy com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). Full guide: Multiple gateways.

What does invalid handshake code 1008 mean ​

The Gateway is a WebSocket server, and it expects the very first message to be a connect frame. If it receives anything else, it closes the connection with code 1008 (policy violation).

Common causes:

  • You opened the HTTP URL in a browser (http://...) instead of a WS client.
  • You used the wrong port or path.
  • A proxy or tunnel stripped auth headers or sent a non‑Gateway request.

Quick fixes:

  1. Use the WS URL: ws://<host>:18789 (or wss://... if HTTPS).
  2. Don’t open the WS port in a normal browser tab.
  3. If auth is on, include the token/password in the connect frame.

If you’re using the CLI or TUI, the URL should look like:

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

Protocol details: Gateway protocol.

Logging and debugging ​

Where are logs ​

File logs (structured):

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

You can set a stable path via logging.file. File log level is controlled by logging.level. Console verbosity is controlled by --verbose and logging.consoleLevel.

Fastest log tail:

bash
openclaw logs --follow

Service/supervisor logs (when the gateway runs via launchd/systemd):

  • macOS: $OPENCLAW_STATE_DIR/logs/gateway.log and gateway.err.log (default: ~/.openclaw/logs/...; profiles use ~/.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

See Troubleshooting for more.

How do I startstoprestart the Gateway service ​

Use the gateway helpers:

bash
openclaw gateway status
openclaw gateway restart

If you run the gateway manually, openclaw gateway --force can reclaim the port. See Gateway.

I closed my terminal on Windows how do I restart OpenClaw ​

There are two Windows install modes:

1) WSL2 (recommended): the Gateway runs inside Linux.

Open PowerShell, enter WSL, then restart:

powershell
wsl
openclaw gateway status
openclaw gateway restart

If you never installed the service, start it in the foreground:

bash
openclaw gateway run

2) Native Windows (not recommended): the Gateway runs directly in Windows.

Open PowerShell and run:

powershell
openclaw gateway status
openclaw gateway restart

If you run it manually (no service), use:

powershell
openclaw gateway run

Docs: Windows (WSL2), Gateway service runbook.

The Gateway is up but replies never arrive What should I check ​

Start with a quick health sweep:

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

Common causes:

  • Model auth not loaded on the gateway host (check models status).
  • Channel pairing/allowlist blocking replies (check channel config + logs).
  • WebChat/Dashboard is open without the right token.

If you are remote, confirm the tunnel/Tailscale connection is up and that the Gateway WebSocket is reachable.

Docs: Channels, Troubleshooting, Remote access.

Disconnected from gateway no reason what now ​

This usually means the UI lost the WebSocket connection. Check:

  1. Is the Gateway running? openclaw gateway status
  2. Is the Gateway healthy? openclaw status
  3. Does the UI have the right token? openclaw dashboard
  4. If remote, is the tunnel/Tailscale link up?

Then tail logs:

bash
openclaw logs --follow

Docs: Dashboard, Remote access, Troubleshooting.

Telegram setMyCommands fails with network errors What should I check ​

Start with logs and channel status:

bash
openclaw channels status
openclaw channels logs --channel telegram

If you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works. If the Gateway is remote, make sure you are looking at logs on the Gateway host.

Docs: Telegram, Channel troubleshooting.

TUI shows no output What should I check ​

First confirm the Gateway is reachable and the agent can run:

bash
openclaw status
openclaw models status
openclaw logs --follow

In the TUI, use /status to see the current state. If you expect replies in a chat channel, make sure delivery is enabled (/deliver on).

Docs: TUI, Slash commands.

How do I completely stop then start the Gateway ​

If you installed the service:

bash
openclaw gateway stop
openclaw gateway start

This stops/starts the supervised service (launchd on macOS, systemd on Linux). Use this when the Gateway runs in the background as a daemon.

If you’re running in the foreground, stop with Ctrl‑C, then:

bash
openclaw gateway run

Docs: Gateway service runbook.

ELI5 openclaw gateway restart vs openclaw gateway ​

  • openclaw gateway restart: restarts the background service (launchd/systemd).
  • openclaw gateway: runs the gateway in the foreground for this terminal session.

If you installed the service, use the gateway commands. Use openclaw gateway when you want a one-off, foreground run.

What's the fastest way to get more details when something fails ​

Start the Gateway with --verbose to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors.

Media & attachments ​

My skill generated an imagePDF but nothing was sent ​

Outbound attachments from the agent must include a MEDIA:<path-or-url> line (on its own line). See OpenClaw assistant setup and Agent send.

CLI sending:

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

Also check:

  • The target channel supports outbound media and isn’t blocked by allowlists.
  • The file is within the provider’s size limits (images are resized to max 2048px).

See Images.

Security and access control ​

Is it safe to expose OpenClaw to inbound DMs ​

Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:

  • Default behavior on DM‑capable channels is pairing:
    • Unknown senders receive a pairing code; the bot does not process their message.
    • Approve with: openclaw pairing approve <channel> <code>
    • Pending requests are capped at 3 per channel; check openclaw pairing list <channel> if a code didn’t arrive.
  • Opening DMs publicly requires explicit opt‑in (dmPolicy: "open" and allowlist "*").

Run openclaw doctor to surface risky DM policies.

Is prompt injection only a concern for public bots ​

No. Prompt injection is about untrusted content, not just who can DM the bot. If your assistant reads external content (web search/fetch, browser pages, emails, docs, attachments, pasted logs), that content can include instructions that try to hijack the model. This can happen even if you are the only sender.

The biggest risk is when tools are enabled: the model can be tricked into exfiltrating context or calling tools on your behalf. Reduce the blast radius by:

  • using a read-only or tool-disabled "reader" agent to summarize untrusted content
  • keeping web_search / web_fetch / browser off for tool-enabled agents
  • sandboxing and strict tool allowlists

Details: Security.

Should my bot have its own email GitHub account or phone number ​

Yes, for most setups. Isolating the bot with separate accounts and phone numbers reduces the blast radius if something goes wrong. This also makes it easier to rotate credentials or revoke access without impacting your personal accounts.

Start small. Give access only to the tools and accounts you actually need, and expand later if required.

Docs: Security, Pairing.

Can I give it autonomy over my text messages and is that safe ​

We do not recommend full autonomy over your personal messages. The safest pattern is:

  • Keep DMs in pairing mode or a tight allowlist.
  • Use a separate number or account if you want it to message on your behalf.
  • Let it draft, then approve before sending.

If you want to experiment, do it on a dedicated account and keep it isolated. See Security.

Can I use cheaper models for personal assistant tasks ​

Yes, if the agent is chat-only and the input is trusted. Smaller tiers are more susceptible to instruction hijacking, so avoid them for tool-enabled agents or when reading untrusted content. If you must use a smaller model, lock down tools and run inside a sandbox. See Security.

I ran start in Telegram but didnt get a pairing code ​

Pairing codes are sent only when an unknown sender messages the bot and dmPolicy: "pairing" is enabled. /start by itself doesn’t generate a code.

Check pending requests:

bash
openclaw pairing list telegram

If you want immediate access, allowlist your sender id or set dmPolicy: "open" for that account.

WhatsApp will it message my contacts How does pairing work ​

No. Default WhatsApp DM policy is pairing. Unknown senders only get a pairing code and their message is not processed. OpenClaw only replies to chats it receives or to explicit sends you trigger.

Approve pairing with:

bash
openclaw pairing approve whatsapp <code>

List pending requests:

bash
openclaw pairing list whatsapp

Wizard phone number prompt: it’s used to set your allowlist/owner so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable channels.whatsapp.selfChatMode.

Chat commands, aborting tasks, and “it won’t stop” ​

How do I stop internal system messages from showing in chat ​

Most internal or tool messages only appear when verbose or reasoning is enabled for that session.

Fix in the chat where you see it:

/verbose off
/reasoning off

If it is still noisy, check the session settings in the Control UI and set verbose to inherit. Also confirm you are not using a bot profile with verboseDefault set to on in config.

Docs: Thinking and verbose, Security.

How do I stopcancel a running task ​

Send any of these as a standalone message (no slash):

stop
abort
esc
wait
exit
interrupt

These are abort triggers (not slash commands).

For background processes (from the exec tool), you can ask the agent to run:

process action:kill sessionId:XXX

Slash commands overview: see Slash commands.

Most commands must be sent as a standalone message that starts with /, but a few shortcuts (like /status) also work inline for allowlisted senders.

How do I send a Discord message from Telegram Crosscontext messaging denied ​

OpenClaw blocks cross‑provider messaging by default. If a tool call is bound to Telegram, it won’t send to Discord unless you explicitly allow it.

Enable cross‑provider messaging for the agent:

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

Restart the gateway after editing config. If you only want this for a single agent, set it under agents.list[].tools.message instead.

Why does it feel like the bot ignores rapidfire messages ​

Queue mode controls how new messages interact with an in‑flight run. Use /queue to change modes:

  • steer - new messages redirect the current task
  • followup - run messages one at a time
  • collect - batch messages and reply once (default)
  • steer-backlog - steer now, then process backlog
  • interrupt - abort current run and start fresh

You can add options like debounce:2s cap:25 drop:summarize for followup modes.

Answer the exact question from the screenshot/chat log ​

Q: “What’s the default model for Anthropic with an API key?”

A: In OpenClaw, credentials and model selection are separate. Setting ANTHROPIC_API_KEY (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in agents.defaults.model.primary (for example, anthropic/claude-sonnet-4-5 or anthropic/claude-opus-4-5). If you see No credentials found for profile "anthropic:default", it means the Gateway couldn’t find Anthropic credentials in the expected auth-profiles.json for the agent that’s running.

Still stuck? Ask in Discord or open a GitHub discussion.