常见问题 - OpenClaw

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

最初的六十秒，如果出现故障

快速状态（首次检查）
```
openclaw status
```
快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。
可粘贴报告（可安全分享）
```
openclaw status --all
```
只读诊断，包含日志尾部（令牌已脱敏）。
守护进程 + 端口状态
```
openclaw gateway status
```
显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用的配置。
深度探测
```
openclaw status --deep
```
运行实时 Gateway 网关健康探测，包括在支持时进行渠道探测（需要可达的 Gateway 网关）。参阅 Health。
跟踪最新日志
```
openclaw logs --follow
```
如果 RPC 不可用，则回退到：
```
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
```
文件日志与服务日志分开；参阅 Logging 和故障排除。
运行 Doctor（修复）
```
openclaw doctor
```
修复/迁移配置/状态 + 运行健康检查。参阅 Doctor。

Gateway 网关快照

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

请求正在运行的 Gateway 网关提供完整快照（仅 WS）。参阅 Health。

快速开始和首次运行设置

首次运行问答——安装、新手引导、认证路由、订阅、初始失败—— 位于首次运行常见问题。

什么是 OpenClaw？

一句话说明 OpenClaw 是什么？

OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它可以在你已经使用的消息界面上回复（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及 QQ Bot 等内置渠道插件），也可以在支持的平台上提供语音 + 实时 Canvas。Gateway 网关是常驻控制平面；助手才是产品。

价值主张

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

你的设备，你的数据： 在任何你想要的位置运行 Gateway 网关（Mac、Linux、VPS），并将工作区 + 会话历史保留在本地。
真实渠道，而不是 Web 沙箱： WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等，加上受支持平台上的移动语音和 Canvas。
模型无关： 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由和故障转移。
仅本地选项： 运行本地模型，这样如果你愿意，所有数据都可以留在你的设备上。
多智能体路由： 按渠道、账号或任务分离智能体，每个智能体都有自己的工作区和默认设置。
开源且可改造： 可检查、扩展并自托管，不受供应商锁定。

文档：Gateway 网关、Channels、多智能体、 Memory。

我刚刚完成设置——应该先做什么？

适合入门的项目：

构建一个网站（WordPress、Shopify，或简单的静态站点）。
原型化一个移动应用（大纲、界面、API 计划）。
整理文件和文件夹（清理、命名、打标签）。
连接 Gmail 并自动生成摘要或跟进事项。

它可以处理大型任务，但当你把任务拆成多个阶段，并使用子智能体并行工作时，效果最好。

OpenClaw 最常见的五个日常用例是什么？

日常收益通常包括：

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

OpenClaw 能帮助 SaaS 做潜在客户开发、触达、广告和博客吗？

可以用于研究、筛选和起草。它可以扫描站点、建立候选名单、汇总潜在客户，并编写触达或广告文案草稿。对于触达或广告投放，请保留人工审核环节。避免垃圾信息，遵守当地法律和平台政策，并在发送前审查所有内容。最安全的模式是让 OpenClaw 起草，然后由你批准。文档：Security。

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

OpenClaw 是个人助手和协调层，不是 IDE 替代品。在仓库中进行最快的直接编码循环时，请使用 Claude Code 或 Codex。当你需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。优势：

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

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

Skills 和自动化

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

使用托管覆盖，而不是编辑仓库副本。将你的更改放入 ~/.openclaw/skills/<name>/SKILL.md（或通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 添加文件夹）。优先级为 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 内置 → skills.load.extraDirs，因此托管覆盖仍会在不触碰 git 的情况下优先于内置 Skills。如果你需要全局安装该 skill，但只让某些智能体可见，请将共享副本保留在 ~/.openclaw/skills，并用 agents.defaults.skills 和 agents.list[].skills 控制可见性。只有值得上游合并的编辑才应该放在仓库中并以 PR 形式提交。

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

可以。在 ~/.openclaw/openclaw.json 中通过 skills.load.extraDirs 添加额外目录（最低优先级）。默认优先级是 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 内置 → skills.load.extraDirs。clawhub 默认安装到 ./skills，OpenClaw 会在下一次会话中将其视为 <workspace>/skills。如果该 skill 只应对某些智能体可见，请与 agents.defaults.skills 或 agents.list[].skills 配合使用。

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

当前支持的模式是：

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

参阅 Cron jobs、多智能体路由和 Slash commands。

机器人在执行繁重工作时卡住。如何卸载这类工作？

对长任务或并行任务使用子智能体。子智能体在自己的会话中运行，返回摘要，并保持主聊天响应流畅。让你的机器人“为此任务生成一个子智能体”，或使用 /subagents。在聊天中使用 /status 查看 Gateway 网关当前在做什么（以及是否忙碌）。令牌提示：长任务和子智能体都会消耗令牌。如果你担心成本，可以通过 agents.defaults.subagents.model 为子智能体设置更便宜的模型。文档：子智能体、Background Tasks。

Discord 上绑定线程的子智能体会话如何工作？

使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息会留在绑定的会话上。基本流程：

使用 sessions_spawn 生成，并设置 thread: true（也可为持久跟进设置 mode: "session"）。
或使用 /focus <target> 手动绑定。
使用 /agents 检查绑定状态。
使用 /session idle <duration|off> 和 /session max-age <duration|off> 控制自动取消聚焦。
使用 /unfocus 分离线程。

必需配置：

全局默认值：session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
Discord 覆盖：channels.discord.threadBindings.enabled、channels.discord.threadBindings.idleHours、channels.discord.threadBindings.maxAgeHours。
生成时自动绑定：channels.discord.threadBindings.spawnSessions 默认为 true；将其设为 false 可禁用绑定线程的会话生成。

文档：子智能体、Discord、Configuration Reference、Slash commands。

子智能体已完成，但完成更新发到了错误位置或从未发布。我应该检查什么？

先检查解析后的请求者路由：

完成模式的子智能体投递会在存在绑定线程或对话路由时优先使用它。
如果完成来源只携带渠道，OpenClaw 会回退到请求者会话存储的路由（lastChannel / lastTo / lastAccountId），这样直接投递仍可能成功。
如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退到队列会话投递，而不是立即发布到聊天。
无效或过期目标仍可能强制队列回退或最终投递失败。
如果子会话最后一条可见助手回复正好是静默令牌 NO_REPLY / no_reply，或正好是 ANNOUNCE_SKIP，OpenClaw 会有意抑制公告，而不是发布过期的早期进度。
如果子会话在只有工具调用后超时，公告可能会将其折叠成简短的部分进度摘要，而不是回放原始工具输出。

调试：

openclaw tasks show <runId-or-sessionKey>

文档：子智能体、Background Tasks、Session Tools。

Cron 或提醒没有触发。我应该检查什么？

Cron 在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行，定时作业就不会运行。检查清单：

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

调试：

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

文档：Cron jobs、自动化。

Cron 已触发，但没有任何内容发送到渠道。为什么？

先检查投递模式：

--no-deliver / delivery.mode: "none" 表示不应期望运行器回退发送。
缺失或无效的公告目标（channel / to）表示运行器跳过了出站投递。
渠道认证失败（unauthorized、Forbidden）表示运行器尝试投递，但凭据阻止了投递。
静默隔离结果（仅 NO_REPLY / no_reply）会被视为有意不可投递，因此运行器也会抑制排队的回退投递。

对于隔离的 Cron 任务，当聊天路由可用时，智能体仍然可以使用 message 工具直接发送。--announce 只控制运行器对智能体尚未发送的最终文本使用的回退路径。调试：

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

文档：Cron 任务、后台任务。

为什么隔离的 Cron 运行会切换模型或重试一次？

这通常是实时模型切换路径，不是重复调度。当活动运行抛出 LiveSessionModelSwitchError 时，隔离 Cron 可以持久化运行时模型移交并重试。重试会保留已切换的提供商/模型；如果切换携带了新的认证配置覆盖， Cron 也会在重试前持久化该覆盖。相关选择规则：

Gmail 钩子模型覆盖在适用时优先。
然后是每个任务的 model。
然后是任何已存储的 Cron 会话模型覆盖。
然后是正常的智能体/默认模型选择。

重试循环有上限。初始尝试加上 2 次切换重试之后， Cron 会中止，而不是无限循环。调试：

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

文档：Cron 任务、Cron CLI。

如何在 Linux 上安装 Skills？

使用原生 openclaw skills 命令，或将 Skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。在 https://clawhub.ai 浏览 Skills。

openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check

原生 openclaw skills install 会写入活动工作区的 skills/ 目录。只有当你想发布或同步自己的 Skills 时，才需要安装单独的 clawhub CLI。对于跨智能体共享安装，请将 Skill 放在 ~/.openclaw/skills 下；如果你想限制哪些智能体可以看到它，请使用 agents.defaults.skills 或 agents.list[].skills。

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

可以。使用 Gateway 网关调度器：

Cron 任务用于计划任务或重复任务（重启后仍会持久保留）。
Heartbeat用于“主会话”周期检查。
隔离任务用于发布摘要或投递到聊天的自主智能体。

文档：Cron 任务、自动化、 Heartbeat。

我能在 Linux 上运行仅限 Apple macOS 的 Skills 吗？

不能直接运行。macOS Skills 受 metadata.openclaw.os 加必需二进制文件限制，并且只有在 Gateway 网关主机上符合条件时，Skills 才会出现在系统提示中。在 Linux 上，除非你覆盖门控，否则仅限 darwin 的 Skills（如 apple-notes、apple-reminders、things-mac）不会加载。你有三种受支持的模式：选项 A - 在 Mac 上运行 Gateway 网关（最简单）。 在存在 macOS 二进制文件的位置运行 Gateway 网关，然后从 Linux 通过远程模式或 Tailscale 连接。由于 Gateway 网关主机是 macOS，Skills 会正常加载。选项 B - 使用 macOS 节点（无 SSH）。 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 节点运行命令设置为“始终询问”或“始终允许”。当节点上存在必需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 nodes 工具运行这些 Skills。如果选择“始终询问”，在提示中批准“始终允许”会将该命令添加到允许列表。选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。 保持 Gateway 网关在 Linux 上运行，但让必需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skill 以允许 Linux，使其保持符合条件。

为该二进制文件创建 SSH 包装器（示例：Apple Notes 的 memo）：

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

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

覆盖 Skill 元数据（工作区或 ~/.openclaw/skills）以允许 Linux：

---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---

启动新会话，以便刷新 Skills 快照。

你们有 Notion 或 HeyGen 集成吗？

目前没有内置。选项：

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

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

每个客户一个 Notion 页面（上下文 + 偏好 + 活跃工作）。
要求智能体在会话开始时获取该页面。

如果你想要原生集成，请提交功能请求，或构建面向这些 API 的 Skill。安装 Skills：

openclaw skills install <skill-slug>
openclaw skills update --all

原生安装会落在活动工作区的 skills/ 目录中。对于跨智能体共享的 Skills，请将它们放在 ~/.openclaw/skills/<name>/SKILL.md。如果只有部分智能体应该看到共享安装，请配置 agents.defaults.skills 或 agents.list[].skills。某些 Skills 需要通过 Homebrew 安装的二进制文件；在 Linux 上，这意味着 Linuxbrew（请参阅上方的 Homebrew Linux 常见问题条目）。参见 Skills、Skills 配置和 ClawHub。

如何将现有已登录的 Chrome 与 OpenClaw 一起使用？

使用内置的 user 浏览器配置文件，它通过 Chrome DevTools MCP 附加：

openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot

如果你想使用自定义名称，请创建显式 MCP 配置文件：

openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs

此路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关在其他位置运行，请在浏览器机器上运行节点主机，或改用远程 CDP。existing-session / user 的当前限制：

操作基于 ref，而不是基于 CSS 选择器
上传需要 ref / inputRef，并且目前一次支持一个文件
responsebody、PDF 导出、下载拦截和批量操作仍需要托管浏览器或原始 CDP 配置文件

沙箱隔离和记忆

是否有专门的沙箱隔离文档？

有。参见沙箱隔离。对于 Docker 专用设置（Docker 中的完整 Gateway 网关或沙箱镜像），参见 Docker。

Docker 感觉受限 - 如何启用完整功能？

默认镜像以安全优先，并以 node 用户运行，因此不包含系统包、Homebrew 或内置浏览器。若要获得更完整的设置：

使用 OPENCLAW_HOME_VOLUME 持久化 /home/node，以便缓存保留。
使用 OPENCLAW_DOCKER_APT_PACKAGES 将系统依赖烘焙进镜像。
通过内置 CLI 安装 Playwright 浏览器： node /app/node_modules/playwright-core/cli.js install chromium
设置 PLAYWRIGHT_BROWSERS_PATH，并确保该路径被持久化。

文档：Docker、浏览器。

我能否用一个智能体让私信保持个人化，但让群组公开/沙箱隔离？

可以，前提是你的私有流量是私信，公开流量是群组。使用 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，并记住绑定会绕过沙箱文件系统边界。OpenClaw 会同时根据规范化路径和通过最深已存在祖先解析出的规范路径验证绑定源。这意味着即使最后一个路径片段尚不存在，符号链接父级逃逸仍会安全失败，并且允许根检查在符号链接解析后仍会应用。参见沙箱隔离和沙箱、工具策略和提升权限，了解示例和安全说明。

记忆如何工作？

OpenClaw 记忆只是智能体工作区中的 Markdown 文件：

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

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

记忆总是忘记东西。如何让它记住？

要求机器人将事实写入记忆。长期笔记应放在 MEMORY.md，短期上下文应放入 memory/YYYY-MM-DD.md。这仍是我们正在改进的领域。提醒模型存储记忆会有帮助；它会知道该怎么做。如果它持续遗忘，请验证 Gateway 网关在每次运行时都使用相同工作区。文档：记忆、Agent 工作区。

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

记忆文件位于磁盘上，并会持续保留，直到你删除它们。限制来自你的存储空间，而不是模型。会话上下文仍受模型上下文窗口限制，因此长对话可能会压缩或截断。这就是为什么存在记忆搜索 - 它只会将相关部分拉回上下文。文档：记忆、上下文。

语义记忆搜索是否需要 OpenAI API key？

只有在你使用 OpenAI 嵌入时才需要。Codex OAuth 覆盖聊天/补全，但不会授予嵌入访问权限，因此**使用 Codex 登录（OAuth 或 Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI 嵌入仍然需要真正的 API key（OPENAI_API_KEY 或 models.providers.openai.apiKey）。如果你没有显式设置提供商，OpenClaw 会在能够解析 API key 时自动选择提供商（认证配置档、models.providers.*.apiKey 或环境变量）。如果解析到 OpenAI 密钥，它会优先使用 OpenAI；否则如果解析到 Gemini 密钥，则使用 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥，记忆搜索会保持禁用，直到你完成配置。如果你已配置且存在本地模型路径， OpenClaw 会优先使用 local。显式设置 memorySearch.provider = "ollama" 时支持 Ollama。如果你更愿意保持本地运行，请设置 memorySearch.provider = "local"（并可选设置 memorySearch.fallback = "none"）。如果你想使用 Gemini 嵌入，请设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini、Voyage、Mistral、Ollama 或本地嵌入模型 - 设置详情见 Memory。

各类内容在磁盘上的位置

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

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

默认本地： 会话、记忆文件、配置和工作区位于 Gateway 网关主机（~/.openclaw + 你的工作区目录）。
因需要而远程： 你发送给模型提供商（Anthropic/OpenAI 等）的消息会发送到它们的 API，聊天平台（WhatsApp/Telegram/Slack 等）会在它们的服务器上存储消息数据。
你控制占用范围： 使用本地模型会让提示词留在你的机器上，但渠道流量仍会经过该渠道的服务器。

路径	用途
`$OPENCLAW_STATE_DIR/openclaw.json`	主配置（JSON5）
`$OPENCLAW_STATE_DIR/credentials/oauth.json`	旧版 OAuth 导入（首次使用时复制到认证配置档中）
`$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json`	认证配置档（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`）
`$OPENCLAW_STATE_DIR/secrets.json`	用于 `file` SecretRef 提供商的可选文件后端密钥负载
`$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json`	旧版兼容文件（静态 `api_key` 条目会被清理）
`$OPENCLAW_STATE_DIR/credentials/`	提供商状态（例如 `whatsapp/<accountId>/creds.json`）
`$OPENCLAW_STATE_DIR/agents/`	按智能体划分的状态（agentDir + 会话）
`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`	对话历史和状态（按智能体）
`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json`	会话元数据（按智能体）

配置基础

配置采用什么格式？在哪里？

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

$OPENCLAW_CONFIG_PATH

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

我设置了 gateway.bind: "lan"（或 "tailnet"），但现在没有任何监听 / UI 显示未授权

非 loopback 绑定需要有效的 Gateway 网关认证路径。实际含义是：

共享密钥认证：令牌或密码
在正确配置的身份感知反向代理之后使用 gateway.auth.mode: "trusted-proxy"

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

注意：

gateway.remote.token / .password 本身不会启用本地 Gateway 网关认证。
只有当 gateway.auth.* 未设置时，本地调用路径才能使用 gateway.remote.* 作为回退。
对于密码认证，请改为设置 gateway.auth.mode: "password" 加 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置但未解析，解析会失败并关闭访问（不会用远程回退掩盖）。
共享密钥 Control UI 设置通过 connect.params.auth.token 或 connect.params.auth.password 认证（存储在应用/UI 设置中）。Tailscale Serve 或 trusted-proxy 等携带身份的模式则使用请求头。避免将共享密钥放入 URL。
使用 gateway.auth.mode: "trusted-proxy" 时，同主机 loopback 反向代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true，并在 gateway.trustedProxies 中加入 loopback 条目。

为什么现在 localhost 上也需要令牌？

OpenClaw 默认强制执行 Gateway 网关认证，包括 loopback。在正常默认路径中，这意味着令牌认证：如果没有配置显式认证路径，Gateway 网关启动会解析为令牌模式，并为该次启动生成仅运行时有效的令牌，因此本地 WS 客户端必须认证。当客户端需要跨重启保持稳定密钥时，请显式配置 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。这会阻止其他本地进程调用 Gateway 网关。如果你偏好不同的认证路径，可以显式选择密码模式（或者对于身份感知反向代理，选择 trusted-proxy）。如果你确实想开放 loopback，请在配置中显式设置 gateway.auth.mode: "none"。Doctor 随时可以为你生成令牌：openclaw doctor --generate-gateway-token。

更改配置后必须重启吗？

Gateway 网关会监听配置并支持热重载：

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

如何禁用有趣的 CLI 标语？

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

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

off：隐藏标语文本，但保留横幅标题/版本行。
default：每次都使用 All your chats, one OpenClaw.。
random：轮换有趣/季节性标语（默认行为）。
如果你完全不想显示横幅，请设置环境变量 OPENCLAW_HIDE_BANNER=1。

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

web_fetch 无需 API key 即可工作。web_search 取决于你选择的提供商：

Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等 API 后端提供商需要它们常规的 API key 设置。
Ollama Web 搜索不需要密钥，但它使用你配置的 Ollama 主机，并需要 ollama signin。
DuckDuckGo 不需要密钥，但它是非官方的基于 HTML 的集成。
SearXNG 不需要密钥/可自托管；配置 SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl。

推荐： 运行 openclaw configure --section web 并选择提供商。环境替代项：

Brave：BRAVE_API_KEY
Exa：EXA_API_KEY
Firecrawl：FIRECRAWL_API_KEY
Gemini：GEMINI_API_KEY
Grok：XAI_API_KEY
Kimi：KIMI_API_KEY 或 MOONSHOT_API_KEY
MiniMax Search：MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY 或 MINIMAX_API_KEY
Perplexity：PERPLEXITY_API_KEY 或 OPENROUTER_API_KEY
SearXNG：SEARXNG_BASE_URL
Tavily：TAVILY_API_KEY

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}

提供商特定的 Web 搜索配置现在位于 plugins.entries.<plugin>.config.webSearch.* 下。旧版 tools.web.search.* 提供商路径仍会临时加载以保持兼容，但新配置不应使用它们。 Firecrawl Web 获取回退配置位于 plugins.entries.firecrawl.config.webFetch.* 下。注意：

如果你使用 allowlist，请添加 web_search/web_fetch/x_search 或 group:web。
web_fetch 默认启用（除非显式禁用）。
如果省略 tools.web.fetch.provider，OpenClaw 会从可用凭证中自动检测第一个就绪的获取回退提供商。目前内置提供商是 Firecrawl。
守护进程从 ~/.openclaw/.env（或服务环境）读取环境变量。

文档：Web 工具。

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

config.apply 会替换整个配置。如果你发送部分对象，其他所有内容都会被移除。当前的 OpenClaw 会防止许多意外覆盖：

OpenClaw 拥有的配置写入会在写入前验证完整的更改后配置。
无效或破坏性的 OpenClaw 拥有写入会被拒绝，并保存为 openclaw.json.rejected.*。
如果直接编辑破坏了启动或热重载，Gateway 网关会故障关闭或跳过重载；它不会重写 openclaw.json。
openclaw doctor --fix 负责修复，可以恢复最后一次已知可用配置，同时将被拒绝的文件保存为 openclaw.json.clobbered.*。

恢复：

检查 openclaw logs --follow 中是否有 Invalid config at、Config write rejected: 或 config reload skipped (invalid config)。
检查活动配置旁最新的 openclaw.json.clobbered.* 或 openclaw.json.rejected.*。
运行 openclaw config validate 和 openclaw doctor --fix。
只用 openclaw config set 或 config.patch 复制回需要的键。
如果你没有最后一次已知可用配置或被拒绝的载荷，请从备份恢复，或重新运行 openclaw doctor 并重新配置渠道/模型。
如果这是意外情况，请提交 bug，并附上你最后已知的配置或任何备份。
本地编码智能体通常可以从日志或历史记录中重建可工作的配置。

避免：

对小改动使用 openclaw config set。
对交互式编辑使用 openclaw configure。
当你不确定确切路径或字段形状时，先使用 config.schema.lookup；它会返回浅层 schema 节点以及直接子项摘要，便于向下排查。
对部分 RPC 编辑使用 config.patch；仅将 config.apply 用于完整配置替换。
如果你在智能体运行中使用仅限所有者的 gateway 工具，它仍会拒绝写入 tools.exec.ask / tools.exec.security（包括会规范化到相同受保护 exec 路径的旧版 tools.bash.* 别名）。

文档：配置、配置、Gateway 网关故障排除、Doctor。

如何运行一个中央 Gateway 网关，并跨设备使用专用 worker？

常见模式是一个 Gateway 网关（例如 Raspberry Pi）加上节点和智能体：

Gateway 网关（中央）： 拥有渠道（Signal/WhatsApp）、路由和会话。
节点（设备）： Mac/iOS/Android 作为外围设备连接，并暴露本地工具（system.run、canvas、camera）。
智能体（worker）： 用于特殊角色的独立大脑/工作区（例如“Hetzner 运维”、“个人数据”）。
子智能体： 当你需要并行处理时，从主智能体派生后台工作。
TUI： 连接到 Gateway 网关并切换智能体/会话。

文档：节点、远程访问、多 Agent 路由、子智能体、TUI。

OpenClaw 浏览器可以无头运行吗？

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

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

默认值为 false（有头）。无头模式更容易在某些网站触发反机器人检查。参见浏览器。无头模式使用相同的 Chromium 引擎，适用于大多数自动化（表单、点击、抓取、登录）。主要区别：

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

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

将 browser.executablePath 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。查看浏览器中的完整配置示例。

远程 Gateway 网关和节点

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

Telegram 消息由 Gateway 网关处理。Gateway 网关运行智能体，只有在需要节点工具时，才会通过 Gateway WebSocket 调用节点：Telegram → Gateway → Agent → node.* → Node → Gateway → Telegram节点看不到入站提供商流量；它们只接收节点 RPC 调用。

如果 Gateway 网关托管在远端，我的智能体如何访问我的电脑？

简短答案：将你的电脑配对为节点。Gateway 网关在别处运行，但它可以通过 Gateway WebSocket 在你的本地机器上调用 node.* 工具（屏幕、摄像头、系统）。典型设置：

在始终在线的主机（VPS/家用服务器）上运行 Gateway 网关。
将 Gateway 网关主机和你的电脑放在同一个 tailnet 中。
确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。
在本地打开 macOS 应用，并以 Remote over SSH 模式（或直接 tailnet）连接，使其可以注册为节点。

在 Gateway 网关上批准节点：

openclaw devices list
openclaw devices approve <requestId>

不需要单独的 TCP 桥接；节点通过 Gateway WebSocket 连接。安全提醒：配对 macOS 节点允许在该机器上执行 system.run。只配对你信任的设备，并查看安全。文档：节点、Gateway 网关协议、macOS 远程模式、安全。

Tailscale 已连接但我收不到回复。现在怎么办？

检查基础项：

Gateway 网关正在运行：openclaw gateway status
Gateway 网关健康状态：openclaw status
渠道健康状态：openclaw channels status

然后验证身份认证和路由：

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

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

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

可以。没有内置的“bot-to-bot”桥接，但你可以用几种可靠方式连接它们：最简单： 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。让机器人 A 向机器人 B 发送消息，然后让机器人 B 像往常一样回复。CLI 桥接（通用）： 运行一个脚本，用 openclaw agent --message ... --deliver 调用另一个 Gateway 网关，目标是另一个机器人监听的聊天。如果一个机器人在远程 VPS 上，请通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关（参见远程访问）。示例模式（从能够访问目标 Gateway 网关的机器运行）：

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

提示：添加防护规则，避免两个机器人无限循环（仅提及、渠道 allowlist，或“不回复机器人消息”的规则）。文档：远程访问、Agent CLI、Agent 发送。

多个智能体需要单独的 VPS 吗？

不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、模型默认值和路由。这是常规设置，比每个智能体运行一个 VPS 便宜且简单得多。只有在需要强隔离（安全边界）或非常不同且你不想共享的配置时，才使用单独的 VPS。否则，请保留一个 Gateway 网关并使用多个智能体或子智能体。

相比从 VPS 通过 SSH 访问，在我的个人笔记本上使用节点有什么好处吗？

有。节点是从远程 Gateway 网关访问你笔记本的一等方式，并且不止提供 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 通过 WSL2）上，并且很轻量（小型 VPS 或 Raspberry Pi 级别的机器即可；4 GB RAM 已经足够），所以常见设置是始终在线的主机加上你的笔记本作为节点。

不需要入站 SSH。 节点向外连接到 Gateway WebSocket，并使用设备配对。
更安全的执行控制。 system.run 受该笔记本上的节点 allowlist/审批限制。
更多设备工具。 除了 system.run，节点还暴露 canvas、camera 和 screen。
本地浏览器自动化。 将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 附加到主机上的本地 Chrome。

SSH 适合临时 shell 访问，但对于持续的智能体工作流和设备自动化，节点更简单。文档：节点、节点 CLI、浏览器。

节点会运行 Gateway 网关服务吗？

不会。除非你有意运行隔离配置文件（参见多个 Gateway 网关），否则每台主机只应运行一个 Gateway 网关。节点是连接到 Gateway 网关的外围设备（iOS/Android 节点，或菜单栏应用中的 macOS“node mode”）。对于无头节点主机和 CLI 控制，请参见节点主机 CLI。对 gateway、discovery 和托管插件表面的更改需要完整重启。

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

有。

config.schema.lookup：在写入前检查一个配置子树及其浅层 schema 节点、匹配的 UI 提示和直接子项摘要
config.get：获取当前快照 + hash
config.patch：安全的部分更新（大多数 RPC 编辑的首选）；可行时热重载，必要时重启
config.apply：验证 + 替换完整配置；可行时热重载，必要时重启
仅所有者可用的 gateway 运行时工具仍会拒绝重写 tools.exec.ask / tools.exec.security；旧版 tools.bash.* 别名会规范化为相同的受保护 exec 路径

首次安装的最小合理配置

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

这会设置你的工作区，并限制谁可以触发 bot。

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

最少步骤：

在 VPS 上安装 + 登录

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

在你的 Mac 上安装 + 登录
- 使用 Tailscale 应用并登录到同一个 tailnet。
启用 MagicDNS（推荐）
- 在 Tailscale 管理控制台中启用 MagicDNS，让 VPS 拥有稳定名称。
使用 tailnet 主机名
- 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：

openclaw gateway --tailscale serve

这会让 gateway 绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 Tailscale。

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

Serve 会暴露 Gateway 网关 Control UI + WS。节点通过同一个 Gateway 网关 WS 端点连接。推荐设置：

确保 VPS + Mac 位于同一个 tailnet。
在 Remote 模式下使用 macOS 应用（SSH 目标可以是 tailnet 主机名）。应用会隧道转发 Gateway 网关端口，并作为节点连接。

在 gateway 上批准节点：

openclaw devices list
openclaw devices approve <requestId>

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

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

如果你只需要第二台笔记本上的本地工具（屏幕/相机/exec），请将它添加为节点。这样可以保留单个 Gateway 网关并避免重复配置。本地节点工具目前仅支持 macOS，但我们计划将其扩展到其他操作系统。仅当你需要强隔离或两个完全独立的 bot 时，才安装第二个 Gateway 网关。文档：节点、节点 CLI、多个 gateway。

环境变量和 .env 加载

OpenClaw 如何加载环境变量？

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

当前工作目录中的 .env
来自 ~/.openclaw/.env 的全局 fallback .env（也就是 $OPENCLAW_STATE_DIR/.env）

两个 .env 文件都不会覆盖现有环境变量。你也可以在配置中定义内联环境变量（仅在进程环境缺失时应用）：

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

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

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

两种常见修复方式：

将缺失的键放入 ~/.openclaw/.env，这样即使服务没有继承你的 shell 环境，也能被读取。
启用 shell 导入（可选便利功能）：

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖）。等效环境变量： OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

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

openclaw models status 报告的是是否启用了 shell 环境导入。“Shell env: off” 不表示你的环境变量缺失，而只是表示 OpenClaw 不会自动加载你的登录 shell。如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell 环境。请选择以下任一种方式修复：

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

然后重启 gateway 并重新检查：

openclaw models status

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

会话和多个聊天

如何开始一段全新对话？

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

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

会话可以在 session.idleMinutes 后过期，但这默认禁用（默认值为 0）。将其设为正值即可启用空闲过期。启用后，空闲时段之后的下一条 消息会为该聊天键启动新的会话 id。这不会删除转录内容，只是启动一个新会话。

{
  session: {
    idleMinutes: 240,
  },
}

有没有办法创建一组 OpenClaw 实例（一个 CEO 和多个 agent）？

可以，通过多 Agent 路由和子智能体。你可以创建一个协调者 agent 和多个 worker agent，并为它们配置各自的工作区和模型。不过，这更适合作为一个有趣的实验。它会消耗大量 token，而且通常不如使用一个 bot 搭配多个独立会话高效。我们设想的典型模型是一个你对话的 bot，并通过不同会话进行并行工作。该 bot 也可以在需要时生成子智能体。文档：多 Agent 路由、子智能体、智能体 CLI。

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

会话上下文受模型窗口限制。长聊天、大型工具输出或大量文件都可能触发压缩或截断。有帮助的做法：

让 bot 总结当前状态并写入文件。
在长任务前使用 /compact，在切换主题时使用 /new。
将重要上下文保存在工作区中，并让 bot 回读。
对长时间或并行工作使用子智能体，让主聊天保持更小。
如果经常发生这种情况，请选择上下文窗口更大的模型。

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

使用重置命令：

openclaw reset

非交互式完整重置：

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

然后重新运行设置：

openclaw onboard --install-daemon

注意：

如果新手引导看到已有配置，也会提供重置。参见新手引导（CLI）。
如果你使用了 profile（--profile / OPENCLAW_PROFILE），请重置每个状态目录（默认是 ~/.openclaw-<profile>）。
开发重置：openclaw gateway --dev --reset（仅限开发；会清除开发配置 + 凭证 + 会话 + 工作区）。

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

使用以下任一种方式：

压缩（保留对话，但总结较早轮次）：
```
/compact
```
或使用 /compact <instructions> 指导摘要。
重置（为同一聊天键创建新会话 ID）：
```
/new
/reset
```

如果仍然持续发生：

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

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

为什么我看到 "LLM request rejected: messages.content.tool_use.input field required"？

这是提供商验证错误：模型发出了一个缺少必需 input 的 tool_use 块。这通常表示会话历史已过期或损坏（常见于长线程或工具/schema 变更之后）。修复：使用 /new（独立消息）开始一个全新会话。

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

Heartbeat 默认每 30m 运行一次（使用 OAuth auth 时为 1h）。可以调整或禁用：

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

如果 HEARTBEAT.md 存在但实际上为空（只有空行和类似 # Heading 的 markdown 标题），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。如果文件缺失，heartbeat 仍会运行，并由模型决定该做什么。按 Agent 覆盖使用 agents.list[].heartbeat。文档：Heartbeat。

我需要向 WhatsApp 群组添加一个 "bot account" 吗？

不需要。OpenClaw 在你自己的账号上运行，所以如果你在群组中，OpenClaw 就能看到它。默认情况下，群组回复会被阻止，直到你允许发送者（groupPolicy: "allowlist"）。如果你只想让你能够触发群组回复：

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

如何获取 WhatsApp 群组的 JID？

选项 1（最快）：tail 日志，并在群组中发送一条测试消息：

openclaw logs --follow --json

查找以 @g.us 结尾的 chatId（或 from），例如： 1234567890-1234567890@g.us。选项 2（如果已配置/加入 allowlist）：从配置中列出群组：

openclaw directory groups list --channel whatsapp

文档：WhatsApp、Directory、日志。

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

两个常见原因：

Mention gating 已开启（默认）。你必须 @mention bot（或匹配 mentionPatterns）。
你配置了 channels.whatsapp.groups，但没有配置 "*"，并且该群组未加入 allowlist。

参见群组和群组消息。

群组/线程是否会与私信共享上下文？

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

我可以创建多少个工作区和智能体？

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

**磁盘增长：**会话 + 转录记录位于 ~/.openclaw/agents/<agentId>/sessions/ 下。
**Token 成本：**更多智能体意味着更多并发模型使用。
**运维开销：**每个智能体都有各自的凭证配置文件、工作区和频道路由。

提示：

为每个智能体保留一个活跃工作区（agents.defaults.workspace）。
如果磁盘增长，清理旧会话（删除 JSONL 或存储条目）。
使用 openclaw doctor 查找游离工作区和配置文件不匹配。

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

可以。使用多智能体路由来运行多个隔离的智能体，并按渠道/账号/对端路由入站消息。Slack 支持作为渠道，并可绑定到特定智能体。浏览器访问功能强大，但并不是“人能做什么它就能做什么”——反机器人、CAPTCHA 和 MFA 仍然可能阻止自动化。要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP，或在实际运行浏览器的机器上使用 CDP。最佳实践设置：

常驻 Gateway 网关主机（VPS/Mac mini）。
每个角色一个智能体（绑定）。
Slack 渠道绑定到这些智能体。
需要时通过 Chrome MCP 或某个节点使用本地浏览器。

文档：多智能体路由、Slack、浏览器、节点。

Models、故障转移和凭证配置文件

模型问答——默认值、选择、别名、切换、故障转移、凭证配置文件—— 位于 Models 常见问题。

Gateway 网关：端口、“already running”和远程模式

Gateway 网关使用哪个端口？

gateway.port 控制用于 WebSocket + HTTP（Control UI、钩子等）的单个复用端口。优先级：

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

为什么 openclaw gateway status 显示 "Runtime: running" 但显示 "Connectivity probe: failed"？

因为 “running” 是监督器视角（launchd/systemd/schtasks）。连通性探测是 CLI 实际连接 Gateway 网关 WebSocket。使用 openclaw gateway status，并信任这些行：

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

为什么 openclaw gateway status 显示的 "Config (cli)" 和 "Config (service)" 不同？

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

openclaw gateway install --force

请从你希望服务使用的同一 --profile / 环境运行该命令。

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

OpenClaw 会在启动时立即绑定 WebSocket 监听器（默认 ws://127.0.0.1:18789）来强制执行运行时锁。如果绑定因 EADDRINUSE 失败，它会抛出 GatewayLockError，表示已有另一个实例在监听。修复：停止另一个实例、释放端口，或使用 openclaw gateway --port <port> 运行。

如何以远程模式运行 OpenClaw（客户端连接到其他位置的 Gateway 网关）？

设置 gateway.mode: "remote" 并指向远程 WebSocket URL，可选地配合共享密钥远程凭证：

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

注意：

openclaw gateway 仅在 gateway.mode 为 local 时启动（或你传入覆盖标志时）。
macOS 应用会监视配置文件，并在这些值变化时实时切换模式。
gateway.remote.token / .password 仅是客户端侧远程凭证；它们本身不会启用本地 Gateway 网关认证。

Control UI 显示 "unauthorized"（或持续重连）。现在怎么办？

你的 Gateway 网关认证路径与 UI 的认证方式不匹配。事实（来自代码）：

Control UI 会把当前浏览器标签页会话和所选 Gateway 网关 URL 的 token 保存在 sessionStorage 中，因此同一标签页刷新可以继续工作，而无需恢复长期存在的 localStorage token 持久化。
在 AUTH_TOKEN_MISMATCH 时，如果 Gateway 网关返回重试提示（canRetryWithDeviceToken=true、recommendedNextStep=retry_with_device_token），受信客户端可以使用缓存的设备 token 尝试一次有界重试。
该缓存 token 重试现在会复用与设备 token 一起存储的缓存已批准 scope。显式 deviceToken / 显式 scopes 调用方仍保留其请求的 scope 集，而不是继承缓存 scope。
在该重试路径之外，连接认证优先级为：显式共享 token/password 优先，然后是显式 deviceToken，然后是已存储设备 token，然后是 bootstrap token。
Bootstrap token scope 检查带有角色前缀。内置 bootstrap operator allowlist 仅满足 operator 请求；节点或其他非 operator 角色仍需要其自身角色前缀下的 scope。

修复：

最快方式：openclaw dashboard（打印 + 复制仪表板 URL，并尝试打开；如果是无头环境则显示 SSH 提示）。
如果你还没有 token：openclaw doctor --generate-gateway-token。
如果是远程，先建隧道：ssh -N -L 18789:127.0.0.1:18789 user@host，然后打开 http://127.0.0.1:18789/。
共享密钥模式：设置 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD，然后在 Control UI 设置中粘贴匹配的密钥。
Tailscale Serve 模式：确保 gateway.auth.allowTailscale 已启用，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback/tailnet URL。
受信代理模式：确保你是通过已配置的身份感知代理访问，而不是原始 Gateway 网关 URL。同主机 loopback 代理还需要 gateway.auth.trustedProxy.allowLoopback = true。
如果一次重试后仍不匹配，请轮换/重新批准已配对设备 token：
- openclaw devices list
- openclaw devices rotate --device <id> --role operator
如果该轮换调用显示被拒绝，请检查两件事：
- 已配对设备会话只能轮换它们自己的设备，除非它们也拥有 operator.admin
- 显式 --scope 值不能超出调用方当前的 operator scope
仍然卡住？运行 openclaw status --all 并按照故障排除操作。有关认证详情，请参阅仪表板。

我设置了 gateway.bind tailnet，但它无法绑定且没有任何监听

tailnet 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果该机器不在 Tailscale 上（或接口已关闭），就没有可绑定的地址。修复：

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

注意：tailnet 是显式的。auto 优先使用 loopback；当你需要仅 tailnet 绑定时，请使用 gateway.bind: "tailnet"。

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

通常不需要——一个 Gateway 网关可以运行多个消息渠道和智能体。只有在需要冗余（例如救援机器人）或强隔离时，才使用多个 Gateway 网关。可以，但你必须隔离：

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

快速设置（推荐）：

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

Profile 也会给服务名称加后缀（ai.openclaw.<profile>；旧版 com.openclaw.*、openclaw-gateway-<profile>.service、OpenClaw Gateway (<profile>)）。完整指南：多个 Gateway 网关。

"invalid handshake" / 代码 1008 是什么意思？

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

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

快速修复：

使用 WS URL：ws://<host>:18789（如果是 HTTPS，则用 wss://...）。
不要在普通浏览器标签页中打开 WS 端口。
如果启用了认证，请在 connect 帧中包含 token/password。

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

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

协议详情：Gateway 网关协议。

日志记录和调试

日志在哪里？

文件日志（结构化）：

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

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

openclaw logs --follow

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

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

更多内容请参阅故障排除。

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

使用 Gateway 网关辅助命令：

openclaw gateway status
openclaw gateway restart

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

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

有两种 Windows 安装模式：**1) WSL2（推荐）：**Gateway 网关在 Linux 内运行。打开 PowerShell，进入 WSL，然后重启：

wsl
openclaw gateway status
openclaw gateway restart

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

openclaw gateway run

**2) 原生 Windows（不推荐）：**Gateway 网关直接在 Windows 中运行。打开 PowerShell 并运行：

openclaw gateway status
openclaw gateway restart

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

openclaw gateway run

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

Gateway 网关已启动，但回复一直不到达。我应该检查什么？

从快速健康检查开始：

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

常见原因：

模型凭证未在 Gateway 网关主机 上加载（检查 models status）。
频道配对/allowlist 阻止回复（检查频道配置 + 日志）。
WebChat/Dashboard 已打开，但没有正确的 token。

如果你在远程环境中，请确认 tunnel/Tailscale 连接已建立，并且 Gateway 网关 WebSocket 可访问。文档：Channels、故障排除、Remote access。

“已与 Gateway 网关断开连接：无原因”——现在怎么办？

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

Gateway 网关是否正在运行？openclaw gateway status
Gateway 网关是否健康？openclaw status
UI 是否有正确的 token？openclaw dashboard
如果是远程环境，tunnel/Tailscale 链接是否已建立？

然后跟踪日志：

openclaw logs --follow

文档：Dashboard、Remote access、故障排除。

Telegram setMyCommands 失败。我应该检查什么？

从日志和频道状态开始：

openclaw channels status
openclaw channels logs --channel telegram

然后匹配错误：

BOT_COMMANDS_TOO_MUCH：Telegram 菜单条目太多。OpenClaw 已经会裁剪到 Telegram 限制并用更少的命令重试，但仍然需要删除一些菜单条目。减少插件/skill/自定义命令，或者如果你不需要菜单，请禁用 channels.telegram.commands.native。
TypeError: fetch failed、Network request for 'setMyCommands' failed! 或类似网络错误：如果你在 VPS 上或位于代理后面，请确认允许出站 HTTPS，并且 DNS 能解析 api.telegram.org。

如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。文档：Telegram、频道故障排除。

TUI 没有显示输出。我应该检查什么？

首先确认 Gateway 网关可访问，并且 agent 可以运行：

openclaw status
openclaw models status
openclaw logs --follow

在 TUI 中，使用 /status 查看当前状态。如果你期望在聊天渠道中收到回复，请确保已启用投递（/deliver on）。文档：TUI、斜杠命令。

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

如果你安装了服务：

openclaw gateway stop
openclaw gateway start

这会停止/启动 受监管服务（macOS 上的 launchd，Linux 上的 systemd）。当 Gateway 网关作为守护进程在后台运行时，请使用这种方式。如果你在前台运行，请用 Ctrl-C 停止，然后运行：

openclaw gateway run

文档：Gateway 网关服务运行手册。

ELI5：openclaw gateway restart 与 openclaw gateway

openclaw gateway restart：重启 后台服务（launchd/systemd）。
openclaw gateway：在此终端会话中以前台方式运行 Gateway 网关。

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

出现失败时最快获取更多细节的方法

使用 --verbose 启动 Gateway 网关以获取更多控制台细节。然后检查日志文件中的频道凭证、模型路由和 RPC 错误。

媒体和附件

我的 skill 生成了图片/PDF，但什么都没发送

agent 的出站附件必须包含一行 MEDIA:<path-or-url>（单独一行）。请参阅 OpenClaw assistant 设置和 Agent send。CLI 发送：

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

另请检查：

目标频道支持出站媒体，并且未被 allowlist 阻止。
文件位于提供商的大小限制内（图片会被调整为最大 2048px）。
tools.fs.workspaceOnly=true 会将本地路径发送限制为工作区、temp/media-store 和通过沙箱验证的文件。
tools.fs.workspaceOnly=false 允许 MEDIA: 发送 agent 已经可读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似密钥的文件仍会被阻止。

请参阅图片。

安全和访问控制

将 OpenClaw 暴露给入站私信安全吗？

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

支持私信的渠道默认行为是配对：
- 未知发送者会收到配对码；机器人不会处理他们的消息。
- 使用以下命令批准：openclaw pairing approve --channel <channel> [--account <id>] <code>
- 待处理请求上限为 每个 channel 3 个；如果未收到代码，请检查 openclaw pairing list --channel <channel> [--account <id>]。
公开开放私信需要显式选择加入（dmPolicy: "open" 和 allowlist "*"）。

运行 openclaw doctor 以暴露有风险的私信策略。

提示注入只是公共机器人需要担心的问题吗？

不是。提示注入关乎 不受信任的内容，不只是关乎谁能给机器人发私信。如果你的 assistant 读取外部内容（Web 搜索/获取、浏览器页面、电子邮件、文档、附件、粘贴的日志），这些内容可能包含试图劫持模型的指令。即使 只有你一个发送者，这种情况也可能发生。最大的风险出现在工具已启用时：模型可能被诱骗泄露上下文，或代表你调用工具。通过以下方式降低影响范围：

使用只读或禁用工具的 “reader” agent 来总结不受信任的内容
为启用工具的 agent 关闭 web_search / web_fetch / browser
也将解码后的文件/文档文本视为不受信任：OpenResponses input_file 和媒体附件提取都会用明确的外部内容边界标记包裹提取文本，而不是传递原始文件文本
沙箱隔离和严格的工具 allowlist

详情：安全。

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

对大多数设置来说，应该。用独立账号和电话号码隔离机器人可以在出问题时降低影响范围。这也使得轮换凭证或撤销访问时不会影响你的个人账号。从小范围开始。只授予你实际需要的工具和账号访问权限，必要时再扩展。文档：安全、配对。

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

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

将私信保持在 配对模式 或严格的 allowlist 中。
如果你希望它代表你发消息，请使用 单独的号码或账号。
让它起草，然后 发送前批准。

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

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

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

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

只有当未知发送者给机器人发消息且 dmPolicy: "pairing" 已启用时，才会发送配对码。/start 本身不会生成代码。检查待处理请求：

openclaw pairing list telegram

如果你想立即访问，请将你的 sender id 加入 allowlist，或为该账号设置 dmPolicy: "open"。

WhatsApp：它会给我的联系人发消息吗？配对如何工作？

不会。默认 WhatsApp 私信策略是配对。未知发送者只会收到配对码，其消息 不会被处理。OpenClaw 只会回复它收到的聊天，或回复你显式触发的发送。使用以下命令批准配对：

openclaw pairing approve whatsapp <code>

列出待处理请求：

openclaw pairing list whatsapp

向导电话号码提示：它用于设置你的 allowlist/owner，以允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用该号码并启用 channels.whatsapp.selfChatMode。

聊天命令、中止任务，以及“它不会停止”

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

大多数内部消息或工具消息只会在该会话启用 verbose、trace 或 reasoning 时出现。在你看到它的聊天中修复：

/verbose off
/trace off
/reasoning off

如果仍然很嘈杂，请检查 Control UI 中的会话设置，并将 verbose 设置为 inherit。另请确认你没有使用在配置中将 verboseDefault 设置为 on 的机器人配置文件。文档：Thinking and verbose、安全。

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

将以下任一内容 作为独立消息 发送（不是斜杠命令）：

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

这些是中止触发词（不是斜杠命令）。对于后台进程（来自 exec 工具），你可以要求 agent 运行：

process action:kill sessionId:XXX

斜杠命令概览：请参阅斜杠命令。大多数命令必须作为以 / 开头的独立消息发送，但少数快捷方式（如 /status）也可由 allowlisted 发送者内联使用。

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

OpenClaw 默认阻止 跨提供商 消息传递。如果工具调用绑定到 Telegram，它不会发送到 Discord，除非你显式允许。为 agent 启用跨提供商消息传递：

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

编辑配置后重启 Gateway 网关。

为什么感觉机器人会“忽略”连续快速发送的消息？

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

steer - 将所有待处理 steering 排队到当前运行的下一个模型边界
queue - 旧版一次一个 steering
followup - 一次运行一条消息
collect - 批量收集消息并回复一次
steer-backlog - 立即 steer，然后处理积压
interrupt - 中止当前运行并重新开始

默认模式是 steer。你可以为后续模式添加类似 debounce:0.5s cap:25 drop:summarize 的选项。参见命令队列和 Steering queue。

杂项

使用 API key 时 Anthropic 的默认模型是什么？

在 OpenClaw 中，凭证和模型选择是分开的。设置 ANTHROPIC_API_KEY（或在 auth profiles 中存储 Anthropic API key）会启用身份验证，但实际默认模型取决于你在 agents.defaults.model.primary 中配置的内容（例如 anthropic/claude-sonnet-4-6 或 anthropic/claude-opus-4-6）。如果你看到 No credentials found for profile "anthropic:default"，这表示 Gateway 网关无法在正在运行的智能体的预期 auth-profiles.json 中找到 Anthropic 凭证。

仍然卡住？在 Discord 提问，或打开一个 GitHub discussion。

Documentation Index

​最初的六十秒，如果出现故障

​快速开始和首次运行设置

​什么是 OpenClaw？

​Skills 和自动化

​沙箱隔离和记忆

​各类内容在磁盘上的位置

​配置基础

​远程 Gateway 网关和节点

​环境变量和 .env 加载

​会话和多个聊天

​Models、故障转移和凭证配置文件

​Gateway 网关：端口、“already running”和远程模式

​日志记录和调试

​媒体和附件

​安全和访问控制

​聊天命令、中止任务，以及“它不会停止”

​杂项

​相关内容