古法编程

Appearance

遇到 OpenClaw 故障不要慌——优先运行 openclaw status 获取概览，然后用 openclaw doctor 自动修复配置。远程时检查 WebSocket 隧道和 aouth；模型报 429 时启用 failover 或更换 provider。本页汇总了 60 秒诊断步骤、技能安装、权限配置和会话管理的关键操作，能应对多数日常问题。

OpenClaw 常见问题排查：安装配置、模型认证、远程访问失败 ​

前 60 秒：立刻判断问题根因 ​

  1. 快速状态（第一排查）

    bash
    openclaw status

    本地摘要：系统版本 + 更新状态、Gateway/服务可达性、Agent/会话信息、Provider 配置和运行时问题（Gateway 可达时）。

  2. 可共享的诊断报告（安全脱敏）

    bash
    openclaw status --all

    只读诊断，附带日志末尾（token 已屏蔽），可放心分享给他人协助。

  3. 守护进程 + 端口状态

    bash
    openclaw gateway status

    显示 Supervisor 运行时状态 vs RPC 可达性、探测目标 URL 以及服务实际使用的配置文件。

  4. 深度探测

    bash
    openclaw status --deep

    运行实时 Gateway 健康探测，支持渠道级探测（需 Gateway 可达）。详见 Health。

  5. 查看最新日志

    bash
    openclaw logs --follow

    若 RPC 不可用，退而查看文件日志：

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

    文件日志与服务日志分离，详见 Logging 和 Troubleshooting。

  6. 运行 Doctor（自动修复）

    bash
    openclaw doctor

    修复或迁移配置/状态，并执行健康检查。详见 Doctor。

  7. Gateway 快照

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

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

快速开始和首次运行问题 ​

首次运行的问题（安装、引导、认证、订阅、初始失败）请参阅 First-run FAQ。

什么是 OpenClaw？ ​

一句话概括 ​

OpenClaw 是一个运行在你自有设备上的个人 AI 助手。它能通过你日常使用的消息界面（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及 QQ Bot 等内置渠道插件）回复消息，并在支持平台上提供语音 + Live Canvas。Gateway 是常开控制面，助手是最终产品。

价值主张 ​

OpenClaw 不只是"Claude 包装器"。它是一个本地优先的控制面，让你在自有硬件上运行一个称职的助手，可以经由你已有的聊天应用访问，拥有状态化会话、记忆和工具——无需将工作流交给托管 SaaS。

亮点：

  • 你的设备，你的数据： 在任何地方运行 Gateway（Mac、Linux、VPS），工作区和会话历史保留在本地。
  • 真实渠道而非网页沙箱： WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等，加上移动端语音和受支持平台的 Canvas。
  • 模型无关： 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，支持按 Agent 路由和 failover。
  • 本地优先选项： 运行本地模型，全部数据可保留在设备上。
  • 多 Agent 路由： 按渠道、账户或任务隔离 Agent，每个有独立的工作区和默认设置。
  • 开源可审计： 检查、扩展，无供应商锁定。

文档：Gateway、渠道、多 Agent、记忆。

首次设置后推荐做什么？ ​

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

它能处理大型任务，但分阶段进行并用于 Agent 并行工作效果最佳。

五大日常使用场景 ​

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

OpenClaw 能否帮助 SaaS 的线索挖掘、外展、广告和博客？ ​

可以用于研究、资格判定和起草。它能扫描网站、构建短名单、总结潜在客户并撰写外展或广告文案。对于外展或广告投放，请保持人工审核。避免垃圾信息，遵守当地法律和平台政策，发送前审核一切。最安全的模式是让 OpenClaw 起草，你审核批准。文档：安全。

与 Claude Code 做 Web 开发相比有什么优势？ ​

OpenClaw 是个人助手和协作层，不是 IDE 替代品。在仓库内做最快编码循环请用 Claude Code 或 Codex。当你需要持久记忆、跨设备访问和工具编排时使用 OpenClaw。

优势：

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

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

技能与自动化 ​

如何自定义技能而不弄脏仓库？ ​

使用托管覆盖而不是编辑仓库副本。将修改放入 ~/.openclaw/skills/<name>/SKILL.md（或通过 skills.load.extraDirs 添加文件夹）。优先级：<workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled → skills.load.extraDirs。所以托管覆盖仍比 bundled 技能优先级高，无须触摸 git。如果技能要全局安装但仅部分 Agent 可见，将共享副本放在 ~/.openclaw/skills，并通过 agents.defaults.skills 和 agents.list[].skills 控制可见性。只有值得上游的修改才应放入仓库作为 PR。

能从自定义文件夹加载技能吗？ ​

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

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

当前支持的模式：

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

参见 Cron jobs、多 Agent 路由 和 Slash 命令。

机器人在执行重任务时卡住，如何卸载？ ​

使用子 Agent 处理长时间或并行任务。子 Agent 在其自己的会话中运行，返回摘要，使主聊天保持响应。要求机器人"spawn a sub-agent for this task"或使用 /subagents。在聊天中使用 /status 查看 Gateway 当前状态（以及是否忙碌）。

Token 提示： 长任务和子 Agent 都会消耗 token。如果担心成本，可以通过 agents.defaults.subagents.model 为子 Agent 设置更便宜的模型。文档：子 Agent、后台任务。

Discord 上线程绑定的子 Agent 会话如何工作？ ​

使用线程绑定。你可以将 Discord 线程绑定到子 Agent 或会话目标，使得该线程中的后续消息保持在该绑定会话上。

基本流程：

  • 使用 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 禁用线程绑定的会话生成。

文档：子 Agent、Discord、配置参考、Slash 命令。

子 Agent 完成但完成更新去错了地方或未发布。应检查什么？ ​

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

  • 完成模式的子 Agent 传递优先选择绑定的线程或会话路由（如果存在）。
  • 如果完成来源只携带渠道，OpenClaw 会回退到请求者会话存储的路由（lastChannel / lastTo / lastAccountId），因此直接传递仍可能成功。
  • 如果绑定的路由或可用的存储路由都不存在，直接传递可能失败，结果退回到排队会话传递而不是立即发布到聊天。
  • 无效或过期的目标仍然可能导致排队回退或最终传递失败。
  • 如果子 Agent 的最后可见助手回复正是静默 token NO_REPLY / no_reply，或恰好是 ANNOUNCE_SKIP，OpenClaw 有意抑制 announcement 而不是发布旧的早期进度。
  • 如果子 Agent 超时且只进行了工具调用，announcement 会将其折叠为简短的部分进度摘要，而不是重放原始工具输出。

调试：

bash
openclaw tasks show <runId-or-sessionKey>

文档：子 Agent、后台任务、会话工具。

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

Cron 在 Gateway 进程内运行。如果 Gateway 没有持续运行，计划任务不会执行。

检查清单：

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

调试：

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

文档：Cron jobs、自动化。

Cron 触发了但没有消息发送到渠道。为什么？ ​

首先检查投递模式：

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

对于隔离的 cron 任务，当存在聊天路由时，Agent 仍可使用 message 工具直接发送。--announce 仅控制运行器回退路径，用于 Agent 尚未发送的最终文本。

调试：

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

文档：Cron jobs、后台任务。

为什么隔离的 cron 运行切换了模型或重试了一次？ ​

这通常是实时的模型切换路径，而不是重复调度。

隔离 cron 可以持久化运行时模型交递，并在活动运行抛出 LiveSessionModelSwitchError 时重试。重试保持切换后的 provider/model，如果切换携带了新的认证配置文件覆盖，cron 也会在重试之前持久化。

相关选择规则：

  • 适用时 Gmail 钩子模型覆盖优先。
  • 然后是任务级别的 model。
  • 然后任何存储的 cron 会话模型覆盖。
  • 然后是正常的 Agent/默认模型选择。

重试循环有界。初次尝试加上 2 次 switch 重试后，cron 中止而不是无限循环。

调试：

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

文档：Cron jobs、cron CLI。

如何在 Linux 上安装技能？ ​

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

bash
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 install <skill-slug> --global
openclaw skills update --all
openclaw skills update --all --global
openclaw skills list --eligible
openclaw skills check

原生 openclaw skills install 默认写入活动工作区的 skills/ 目录。添加 --global 安装到所有本地 Agent 共享的托管技能目录。仅当你想发布或同步自己的技能时才安装单独的 clawhub CLI。如果想限制哪些 Agent 能看到共享技能，使用 agents.defaults.skills 或 agents.list[].skills。

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

可以。使用 Gateway 调度器：

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

文档：Cron jobs、自动化、Heartbeat。

我能从 Linux 运行仅限 macOS 的技能吗？ ​

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

三种支持的模式：

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

方案 B - 使用 macOS 节点（无 SSH）。 在 Linux 上运行 Gateway，配对 macOS 节点（菜单栏应用），并在 Mac 上将 Node Run Commands 设置为"Always Ask"或"Always Allow"。当所需二进制存在于节点上时，OpenClaw 可将仅 macOS 的技能视为符合条件的。Agent 通过 nodes 工具运行这些技能。如果选择"Always Ask"，在提示中批准"Always Allow"会将该命令加入白名单。

方案 C - 通过 SSH 代理 macOS 二进制（高级）。 将 Gateway 保留在 Linux 上，但让所需 CLI 二进制解析为在 Mac 上运行的 SSH 包装器。然后覆盖技能允许 Linux，使其保持合格。

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

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

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

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

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

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

你们有 Notion 或 HeyGen 集成吗？ ​

目前没有内置。

  • 自定义技能/插件： 最好用于可靠的 API 访问（Notion/HeyGen 都有 API）。
  • 浏览器自动化： 无需代码但较慢且脆弱。

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

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

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

安装技能：

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

原生安装默认放入活动工作区的 skills/ 目录。对于跨所有本地 Agent 的共享技能，使用 openclaw skills install &lt;slug&gt; --global（或手动放入 ~/.openclaw/skills/&lt;name&gt;/SKILL.md）。如果只有部分 Agent 应看到共享安装，配置 agents.defaults.skills 或 agents.list[].skills。有些技能期望通过 Homebrew 安装二进制；在 Linux 上表示 Linuxbrew（参见上面的 Homebrew Linux FAQ 条目）。参见 Skills、Skills config 和 ClawHub。

如何使用我已经登录的 Chrome 与 OpenClaw？ ​

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

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

如果要自定义名称，创建显式的 MCP 配置文件：

bash
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 配置文件。

沙箱与记忆 ​

是否有专门的沙箱文档？ ​

是的。参见 Sandboxing。对于 Docker 特定设置（Gateway 完全在 Docker 或沙箱镜像中），参见 Docker。

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

默认镜像以安全为首，以 node 用户运行，因此不包括系统包、Homebrew 或捆绑浏览器。要更完整的设置：

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

文档：Docker、Browser。

能否让个人 DM 私有，但使群组公开/沙箱化且使用一个 Agent？ ​

可以——如果你的私人流量是 DM，公共流量是群组。

使用 agents.defaults.sandbox.mode: "non-main"，这样群组/渠道会话（非主键）在配置的沙箱后端运行，而主 DM 会话留在主机上。Docker 是默认后端（如果你不选择）。然后通过 tools.sandbox.tools 限制沙箱会话中可用的工具。

配置 walkthrough + 示例：群组：个人 DM + 公共群组

关键配置参考：Gateway 配置

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

设置 agents.defaults.sandbox.docker.binds 为 ["host:path:mode"]（例如 "/home/user/src:/src:ro"）。全局 + 按 Agent 绑定合并；当 scope: "shared" 时忽略按 Agent 绑定。对敏感内容使用 :ro，并记住绑定会绕过沙箱文件系统墙。

OpenClaw 会根据规范化路径以及通过最深已存在祖先解析的规范路径验证绑定源。这意味着即使最后一个路径段还不存在，符号链接父级转义仍然被拒绝，并且允许根检查在符号链接解析后仍然生效。

参见 Sandboxing 和 Sandbox vs Tool Policy vs Elevated 获取示例和安全说明。

记忆如何工作？ ​

OpenClaw 的记忆只是 Agent 工作区中的 Markdown 文件：

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

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

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

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

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

文档：Memory、Agent workspace。

记忆会永远保留吗？有哪些限制？ ​

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

文档：Memory、Context。

语义记忆搜索是否需要 OpenAI API 密钥？ ​

仅当你使用 OpenAI embeddings 时才需要。Codex OAuth 涵盖聊天/补全，但不授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 Codex CLI 登录）**对语义记忆搜索无帮助。OpenAI embeddings 仍然需要真正的 API 密钥（OPENAI_API_KEY 或 models.providers.openai.apiKey）。

如果你没有显式设置 provider，OpenClaw 能解析 API 密钥时自动选择 provider（认证配置文件、models.providers.*.apiKey 或环境变量）。如果解析到 OpenAI 密钥则优先使用 OpenAI，否则 Gemini，然后 Voyage，然后 Mistral。如果没有远程密钥可用，记忆搜索保持禁用直到你配置。如果你已配置本地模型路径且存在，OpenClaw 优先选择 local。当显式设置 memorySearch.provider = "ollama" 时支持 Ollama。

如果更愿意保持本地，设置 memorySearch.provider = "local"（并可选设置 memorySearch.fallback = "none"）。如果想要 Gemini embeddings，设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini、Voyage、Mistral、Ollama 或 local 嵌入模型——参见 Memory 了解设置细节。

数据存储位置 ​

OpenClaw 使用的所有数据是否都保存在本地？ ​

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

  • 默认本地： 会话、记忆文件、配置和工作区位于 Gateway 主机上（~/.openclaw + 工作区目录）。
  • 远程不可避免： 你发送给模型提供商（Anthropic/OpenAI 等）的消息会转到它们的 API，聊天平台（WhatsApp/Telegram/Slack 等）将消息数据存储在其服务器上。
  • 你控制足迹： 使用本地模型将提示留在你的机器上，但渠道流量仍然经过该渠道的服务器。

相关：Agent 工作区、记忆。

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.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/按 Agent 的状态（agentDir + sessions）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/对话历史 & 状态（按 Agent）
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json会话元数据（按 Agent）

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

你的工作区（AGENTS.md、记忆文件、技能等）是分开的，通过 agents.defaults.workspace 配置（默认：~/.openclaw/workspace）。

AGENTS.md / SOUL.md / USER.md / MEMORY.md 应放在哪里？ ​

这些文件位于Agent 工作区，而不是 ~/.openclaw。

  • 工作区（每 Agent）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md、memory/YYYY-MM-DD.md、可选的 HEARTBEAT.md。小写的根目录 memory.md 仅用于旧版修复输入；openclaw doctor --fix 可以在两个文件都存在时将其合并到 MEMORY.md。
  • 状态目录（~/.openclaw）：配置、渠道/提供商状态、认证配置文件、会话、日志和共享技能（~/.openclaw/skills）。

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

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

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

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

参见 Agent workspace 和 Memory。

推荐的备份策略 ​

将你的Agent 工作区放入一个私有 git 仓库，并在私有位置（例如 GitHub 私有）备份。这样可以捕获记忆 + AGENTS/SOUL/USER 文件，以后可以恢复助手的"心智"。

不要提交 ~/.openclaw 下的任何内容（凭证、会话、令牌或加密密封有效载荷）。如果需要完整恢复，分别备份工作区和状态目录（参见上面的迁移问题）。

文档：Agent workspace。

如何完全卸载 OpenClaw？ ​

参见专门指南：Uninstall。

Agent 能在工作区之外工作吗？ ​

可以。工作区是默认 cwd 和记忆锚点，不是硬沙箱。相对路径在工作区内解析，但绝对路径可以访问其他主机位置，除非沙箱启用。如果需要隔离，使用 agents.defaults.sandbox 或按 Agent 的沙箱设置。如果希望仓库成为默认工作目录，将该 Agent 的 workspace 指向仓库根目录。OpenClaw 仓库只是源代码；除非你故意让 Agent 在其内部工作，否则保持工作区独立。

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

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

远程模式：会话存储在哪里？ ​

会话状态由Gateway 主机拥有。如果你处于远程模式，你关心的会话存储在远程机器上，不是你的本地笔记本。参见 Session management。

配置基础 ​

配置使用什么格式？在哪里？ ​

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

$OPENCLAW_CONFIG_PATH

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

我设置了 gateway.bind: "lan"（或 "tailnet"），但什么都没监听 / UI 显示未授权 ​

非环回绑定需要有效的 Gateway 认证路径。实际上这意味着：

  • 共享密钥认证：token 或 password
  • gateway.auth.mode: "trusted-proxy" 放在正确配置的身份感知反向代理之后
json5
{
  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" 时，同主机环回反向代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true 并在 gateway.trustedProxies 中添加环回条目。

为什么现在 localhost 上也要求 token？ ​

OpenClaw 默认强制执行 Gateway 认证，包括环回。在正常的默认路径下，这意味着 token 认证：如果没有配置显式认证路径，Gateway 启动会解析为 token 模式，并为该次启动生成运行时 token，因此本地 WS 客户端必须认证。当客户端需要在重启间保持稳定密钥时，显式配置 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。这会阻止其他本地进程调用 Gateway。

如果更喜欢不同的认证路径，可以显式选择密码模式（或对于身份感知反向代理，选择 trusted-proxy）。如果确实想要开放环回，在配置中显式设置 gateway.auth.mode: "none"。Doctor 随时可以为你生成 token：openclaw doctor --generate-gateway-token。

更改配置后必须重启吗？ ​

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

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

如何禁用有趣的 CLI 标语？ ​

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

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

如何启用网页搜索（和网页抓取）？ ​

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

  • 由 API 驱动的提供商如 Brave、Exa、Firecrawl、Gemini、Kimi、MiniMax Search、Perplexity、Tavily 需要正常的 API 密钥设置。
  • Grok 可以重用模型认证中的 xAI OAuth，或回退到 XAI_API_KEY / 插件 web-search 配置。
  • Ollama Web Search 无需密钥，但使用你配置的 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 OAuth、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
json5
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        maxResults: 5,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // 可选；省略则自动检测
      },
    },
  },
}

提供商特定的 web-search 配置现在位于 plugins.entries.&lt;plugin&gt;.config.webSearch.*。旧版 tools.web.search.* 提供商路径仍然暂时加载以保持兼容，但不应用作新配置。Firecrawl web-fetch 回退配置位于 plugins.entries.firecrawl.config.webFetch.*。

注意：

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

文档：Web tools。

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 并包含你最后已知的配置或任何备份。
  • 本地编码 Agent 通常可以从日志或历史记录重建工作配置。

避免它：

  • 对于小更改使用 openclaw config set。
  • 对于交互式编辑使用 openclaw configure。
  • 在不确定确切的路径或字段形状时，先使用 config.schema.lookup；它返回浅层 schema 节点加上直接子摘要以供深入查看。
  • 对于部分 RPC 编辑使用 config.patch；仅对完整配置替换使用 config.apply。
  • 如果你在 Agent 运行中使用 Agent 面向的 gateway 工具，它仍然会拒绝写入 tools.exec.ask / tools.exec.security（包括标准化为相同保护执行路径的旧版 tools.bash.* 别名）。

文档：Config、Configure、Gateway troubleshooting、Doctor。

如何运行一个中央 Gateway 并让专用 Worker 跨设备？ ​

常见模式是一个 Gateway（例如 Raspberry Pi）加上 Nodes 和 Agents：

  • Gateway（中央）： 拥有渠道（Signal/WhatsApp）、路由和会话。
  • Nodes（设备）： Mac/iOS/Android 作为外围设备连接，暴露本地工具（system.run、canvas、camera）。
  • Agents（工作者）： 独立的头脑/工作区，用于特殊角色（例如 "Hetzner ops"、"Personal data"）。
  • Sub-agents： 从主 Agent 生成后台工作，以实现并行性。
  • TUI： 连接到 Gateway 并切换 Agent/会话。

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

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

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

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

默认是 false（有头）。无头在某些站点上更可能触发反机器人检测。参见 Browser。

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

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

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

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

远程 Gateway 与 Nodes ​

命令如何在 Telegram、Gateway 和 Nodes 之间传播？ ​

Telegram 消息由 Gateway 处理。Gateway 运行 Agent，仅当需要 Node 工具时才通过 Gateway WebSocket 调用 Nodes：

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

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

如果 Gateway 远程托管，我的 Agent 如何访问我的计算机？ ​

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

典型设置：

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

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

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

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

  5. 批准 Gateway 上的 Node：

    bash
    openclaw devices list
openclaw devices approve <requestId>

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

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

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

Tailscale 已连接但我没有收到回复。怎么办？ ​

检查基本信息：

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

然后验证认证和路由：

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

文档：Tailscale、Remote access、Channels。

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

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

最简单： 使用两个 bot 都能访问的正常聊天渠道（Telegram/Slack/WhatsApp）。让 Bot A 向 Bot B 发送一条消息，然后让 Bot B 正常回复。

CLI 桥接（通用）： 运行脚本调用另一个 Gateway：openclaw agent --message ... --deliver，目标是另一个 bot 监听的聊天。如果其中一个 bot 在远程 VPS 上，通过 SSH/Tailscale 将 CLI 指向该远程 Gateway（参见 Remote access）。

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

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

提示：添加防护措施，防止两个 bot 无限循环（仅提及、渠道白名单或"不回复 bot 消息"规则）。

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

我需要为多个 Agent 准备单独的 VPS 吗？ ​

不需要。一个 Gateway 可以托管多个 Agent，每个有独立的工作区、模型默认值和路由。这是正常设置，比每个 Agent 运行一个 VPS 更便宜更简单。

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

使用个人笔记本电脑上的 Node 相比从 VPS 使用 SSH 有没有优势？ ​

是的——Nodes 是从远程 Gateway 访问笔记本电脑的一等公民方式，它们解锁了比 shell 访问更多的东西。Gateway 在 macOS/Linux 上运行（Windows 通过 WSL2）且轻量（小型 VPS 或 Raspberry Pi 级别机器即可；4 GB RAM 足够），因此常见设置是常开主机加笔记本电脑作为 Node。

  • 无需入站 SSH。 Nodes 向外连接到 Gateway WebSocket 并使用设备配对。
  • 更安全的执行控制。 system.run 由该笔记本电脑上的 Node 白名单/批准控制。
  • 更多设备工具。 Nodes 暴露 canvas、camera 和 screen 以及 system.run。
  • 本地浏览器自动化。 将 Gateway 放在 VPS 上，但通过笔记本电脑上的 Node 主机本地运行 Chrome，或通过 Chrome MCP 附加到主机上的本地 Chrome。

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

文档：Nodes、Nodes CLI、Browser。

Nodes 运行 gateway 服务吗？ ​

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

gateway、discovery 和托管插件表面的更改需要完整重启。

有 API / RPC 方式来应用配置吗？ ​

有。

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

首次安装的最小合理配置 ​

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

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

如何在 VPS 上设置 Tailscale 并从 Mac 连接？ ​

最小步骤：

  1. 在 VPS 上安装并登录

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

  2. 在 Mac 上安装并登录

    • 使用 Tailscale 应用并登录到同一个 tailnet。

  3. 启用 MagicDNS（推荐）

    • 在 Tailscale 管理控制台中启用 MagicDNS，使 VPS 有稳定名称。

  4. 使用 tailnet 主机名

    • SSH：ssh user@your-vps.tailnet-xxxx.ts.net
    • Gateway WS：ws://your-vps.tailnet-xxxx.ts.net:18789

如果在没有 SSH 的情况下想要 Control UI，在 VPS 上使用 Tailscale Serve：

bash
openclaw gateway --tailscale serve

这会将 gateway 绑定到环回并通过 Tailscale 暴露 HTTPS。参见 Tailscale。

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

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

推荐设置：

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

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

  3. 在 gateway 上批准 Node：

    bash
    openclaw devices list
openclaw devices approve <requestId>

文档：Gateway 协议、Discovery、macOS remote mode。

应该在第二台笔记本电脑上安装 OpenClaw 还是仅添加一个 Node？ ​

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

仅当需要硬隔离或两个完全独立的 bot 时，才安装第二个 Gateway。

文档：Nodes、Nodes CLI、Multiple gateways。

环境变量与 .env 加载 ​

OpenClaw 如何加载环境变量？ ​

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

  • 当前工作目录的 .env
  • 来自 ~/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env）的全局回退 .env

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

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

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

参见 /environment 了解完整的优先级和来源。

我通过服务启动了 Gateway，然后环境变量不见了。怎么办？ ​

两个常见修复：

  1. 将缺失的密钥放入 ~/.openclaw/.env，这样即使服务没有继承你的 shell 环境也能被拾取。
  2. 启用 shell 导入（可选的便利功能）：
json5
{
  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 env 导入是否启用。"Shell env: off" 不意味着你的环境变量丢失——它只是意味着 OpenClaw 不会自动加载你的登录 shell。

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

  1. 将 token 放入 ~/.openclaw/.env：

    COPILOT_GITHUB_TOKEN=...

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

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

然后重启 gateway 并重新检查：

bash
openclaw models status

Copilot tokens 从 COPILOT_GITHUB_TOKEN（以及 GH_TOKEN / GITHUB_TOKEN）读取。参见 /concepts/model-providers 和 /environment。

会话与多聊天 ​

如何开始新对话？ ​

发送独立消息 /new 或 /reset。参见 Session management。

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

会话可以在 session.idleMinutes 后过期，但默认禁用（默认 0）。设置为正值以启用空闲过期。启用后，空闲期后的下一个消息会为该聊天键启动新的会话 ID。这不会删除对话记录——只是开始新会话。

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

有没有办法创建一个 OpenClaw 实例团队（一个 CEO 和多个 Agent）？ ​

可以，通过多 Agent 路由和子 Agent。你可以创建一个协调 Agent 和几个拥有自己工作区和模型的 Worker Agent。

但这最好视为有趣的实验。它消耗大量 token，且通常不如使用一个 bot 加上独立会话高效。我们设想的典型模型是一个你可以与之交谈的 bot，具有不同会话用于并行工作。该 bot 在需要时也可以生成子 Agent。

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

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

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

有助于的做法：

  • 要求 bot 总结当前状态并写入文件。
  • 在长任务前使用 /compact，切换主题时使用 /new。
  • 将重要上下文放在工作区中，要求 bot 重新读取。
  • 对于长时间或并行工作，使用子 Agent，使主聊天保持较小。
  • 如果经常发生，选择上下文窗口更大的模型。

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

使用重置命令：

bash
openclaw reset

非交互式完全重置：

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

然后重新运行设置：

bash
openclaw onboard --install-daemon

注意：

  • Onboarding 如果看到现有配置，也提供 Reset。参见 Onboarding (CLI)。
  • 如果使用了配置文件（--profile / OPENCLAW_PROFILE），重置每个状态目录（默认为 ~/.openclaw-&lt;profile&gt;）。
  • 开发者重置：openclaw gateway --dev --reset（仅开发环境；清除开发配置 + 凭证 + 会话 + 工作区）。

我收到 "context too large" 错误——如何重置或压缩？ ​

使用以下之一：

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

    /compact

    或 /compact &lt;instructions&gt; 指导总结。

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

    /new
/reset

如果持续发生：

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

文档：Compaction、Session pruning、Session management。

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

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

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

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

心跳默认每 30 分钟运行一次（使用 OAuth 认证时 1 小时）。调整或禁用：

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

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

按 Agent 覆盖使用 agents.list[].heartbeat。文档：Heartbeat。

我需要在 WhatsApp 群组中添加一个"bot 账号"吗？ ​

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

如果只想让你自己能够触发群组回复：

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

如何获取 WhatsApp 群组的 JID？ ​

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

bash
openclaw logs --follow --json

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

选项 2（如果已配置/白名单）：从配置列出群组：

bash
openclaw directory groups list --channel whatsapp

文档：WhatsApp、Directory、Logs。

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

两个常见原因：

  • 提及门控开启（默认）。你必须 @提及 bot（或匹配 mentionPatterns）。
  • 你配置了 channels.whatsapp.groups 但没有 "*"，群组未在白名单中。

参见 Groups 和 Group messages。

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

直接对话默认折叠到主会话。群组/渠道有它们自己的会话键，Telegram 主题 / Discord 线程是单独的会话。参见 Groups 和 Group messages。

可以创建多少个工作区和 Agent？ ​

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

  • 磁盘增长： 会话 + 对话记录位于 ~/.openclaw/agents/<agentId>/sessions/。
  • Token 成本： 更多 Agent 意味着更多的并发模型使用。
  • 运维开销： 按 Agent 的认证配置文件、工作区和渠道路由。

提示：

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

可以同时运行多个 bot 或聊天吗（Slack），应该如何设置？ ​

可以。使用多 Agent 路由运行多个隔离的 Agent，并按渠道/账户/对端路由入站消息。Slack 支持作为渠道，并可以绑定到特定的 Agent。

浏览器访问功能强大，但不是"人能做的任何事情"——反机器人、CAPTCHAs 和 MFA 仍然可能阻止自动化。为了最可靠的浏览器控制，使用主机上的本地 Chrome MCP，或使用实际运行浏览器的机器上的 CDP。

最佳实践设置：

  • 常开 Gateway 主机（VPS/Mac mini）。
  • 每个角色一个 Agent（绑定）。
  • Slack 渠道绑定到这些 Agent。
  • 需要时通过 Chrome MCP 或 Node 使用本地浏览器。

文档：Multi-Agent Routing、Slack、Browser、Nodes。

模型、降级与认证配置文件 ​

模型 Q&A（默认值、选择、别名、切换、降级、认证配置文件）位于 Models FAQ。

Gateway：端口、"已在运行"和远程模式 ​

Gateway 使用什么端口？ ​

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

优先级：

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

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

因为"running"是Supervisor 的视角（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 不匹配）。

修复：

bash
openclaw gateway install --force

从你想要服务使用的相同 --profile / 环境中运行。

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

OpenClaw 通过启动时立即绑定 WebSocket 监听器来强制执行运行时锁定（默认 ws://127.0.0.1:18789）。如果绑定因 EADDRINUSE 失败，它会抛出 GatewayLockError，表示另一个实例已在监听。

修复：停止另一个实例，释放端口，或使用 openclaw gateway --port &lt;port&gt; 运行。

如何以远程模式运行 OpenClaw（客户端连接到另一台 Gateway）？ ​

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

json5
{
  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 将 token 存储在 sessionStorage 中，用于当前浏览器标签会话和选定的 gateway URL，因此同标签刷新无需恢复长时 localStorage token 持久化。
  • 在 AUTH_TOKEN_MISMATCH 上，信任的客户端可以尝试一次有界重试，使用缓存的设备 token（当 gateway 返回重试提示时：canRetryWithDeviceToken=true、recommendedNextStep=retry_with_device_token）。
  • 该缓存 token 重试现在重用与设备 token 一起存储的已批准范围。显式的 deviceToken / 显式 scopes 调用者仍保留其请求的作用域集而不是继承缓存的作用域。
  • 在该重试路径之外，连接认证优先级是：显式共享 token/password 优先，然后显式 deviceToken，然后存储的设备 token，然后 bootstrap token。
  • 内置的设置代码 bootstrap 仅限节点。批准后，它会返回一个具有 scopes: [] 的节点设备 token，并且不会返回交递的操作员 token。

修复：

  • 最快：openclaw dashboard（打印并复制 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 身份头部的原始环回/tailnet URL。
  • 受信任代理模式：确保你正通过配置的身份感知代理到达，而不是原始 gateway URL。同主机环回代理也需要 gateway.auth.trustedProxy.allowLoopback = true。
  • 如果在一次重试后不匹配仍然存在，轮换/重新批准配对的设备 token：
    • openclaw devices list
    • openclaw devices rotate --device &lt;id&gt; --role operator
  • 如果该轮换调用说被拒绝，检查两件事：
    • 配对设备会话只能轮换它们自己的设备，除非它们还有 operator.admin
    • 显式 --scope 值不能超过调用者当前的操作员作用域
  • 仍然卡住？运行 openclaw status --all 并遵循 Troubleshooting。参见 Dashboard 了解认证详情。

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

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

修复：

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

注意：tailnet 是明确的。auto 优先选择 loopback；使用 gateway.bind: "tailnet" 当需要仅 tailnet 绑定。

可以在同一台主机上运行多个 Gateway 吗？ ​

通常不需要——一个 Gateway 可以运行多个消息渠道和 Agent。仅当需要冗余（例如救援 bot）或硬隔离时才使用多个 Gateway。

可以，但必须隔离：

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

快速设置（推荐）：

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

配置文件还会为服务名称添加后缀（ai.openclaw.&lt;profile&gt;；旧版 com.openclaw.*、openclaw-gateway-&lt;profile&gt;.service、OpenClaw Gateway (&lt;profile&gt;)）。完整指南：Multiple gateways。

"invalid handshake" / code 1008 是什么意思？ ​

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

常见原因：

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

快速修复：

  1. 使用 WS URL：ws://&lt;host&gt;:18789（如果 HTTPS 则用 wss://...）。
  2. 不要在普通浏览器标签中打开 WS 端口。
  3. 如果开启了认证，在 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 控制。

最快日志跟踪：

bash
openclaw logs --follow

服务/监督进程日志（当 gateway 通过 launchd/systemd 运行时）：

  • macOS launchd stdout：~/Library/Logs/openclaw/gateway.log（配置文件使用 gateway-&lt;profile&gt;.log；stderr 被抑制）
  • Linux：journalctl --user -u openclaw-gateway[-&lt;profile&gt;].service -n 200 --no-pager
  • Windows：schtasks /Query /TN "OpenClaw Gateway (&lt;profile&gt;)" /V /FO LIST

参见 Troubleshooting 了解更多。

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

使用 gateway 帮助命令：

bash
openclaw gateway status
openclaw gateway restart

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

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

两种 Windows 安装模式：

1) WSL2（推荐）： Gateway 在 Linux 内部运行。

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

powershell
wsl
openclaw gateway status
openclaw gateway restart

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

bash
openclaw gateway run

2) 原生命令行（不推荐）： Gateway 直接运行在 Windows 中。

打开 PowerShell 并运行：

powershell
openclaw gateway status
openclaw gateway restart

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

powershell
openclaw gateway run

文档：Windows (WSL2)、Gateway service runbook。

Gateway 已启动但回复从未到达。应检查什么？ ​

从快速健康扫描开始：

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

常见原因：

  • 模型认证未在 gateway 主机上加载（检查 models status）。
  • 渠道配对/白名单阻止了回复（检查渠道配置 + 日志）。
  • WebChat/Dashboard 已打开但没有正确的 token。

如果远程，确认隧道/Tailscale 连接正常且 Gateway WebSocket 可达。

文档：Channels、Troubleshooting、Remote access。

"Disconnected from gateway: no reason"——怎么办？ ​

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

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

然后跟踪日志：

bash
openclaw logs --follow

文档：Dashboard、Remote access、Troubleshooting。

Telegram setMyCommands 失败。应检查什么？ ​

从日志和渠道状态开始：

bash
openclaw channels status
openclaw channels logs --channel telegram

然后匹配错误：

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

如果 Gateway 远程，确保你查看的是 Gateway 主机上的日志。

文档：Telegram、Channel troubleshooting。

TUI 没有输出。应检查什么？ ​

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

bash
openclaw status
openclaw models status
openclaw logs --follow

在 TUI 中，使用 /status 查看当前状态。如果你期望在聊天渠道中有回复，确保投递已启用（/deliver on）。

文档：TUI、Slash 命令。

如何完全停止再启动 Gateway？ ​

如果你安装了服务：

bash
openclaw gateway stop
openclaw gateway start

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

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

bash
openclaw gateway run

文档：Gateway service runbook。

ELI5：openclaw gateway restart 与 openclaw gateway ​

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

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

出错时快速获取更多细节的方式 ​

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

媒体与附件 ​

我的技能生成了图片/PDF，但什么也没发送 ​

来自 Agent 的出站附件必须包含一行 MEDIA:&lt;path-or-url&gt;（单独一行）。参见 OpenClaw assistant setup 和 Agent send。

CLI 发送：

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

还要检查：

  • 目标渠道支持出站媒体并且未被白名单阻止。
  • 文件在提供商的尺寸限制内（图片调整为最大 2048px）。
  • tools.fs.workspaceOnly=true 将本地路径发送限制在工作区、临时/媒体存储和沙箱验证的文件。
  • tools.fs.workspaceOnly=false 让 MEDIA: 发送 Agent 已能读取的主机本地文件，但仅限于媒体加安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似秘密的文件仍被阻止。

参见 Images。

安全与访问控制 ​

将 OpenClaw 暴露给入站 DM 安全吗？ ​

将入站 DM 视为不可信输入。默认设计旨在降低风险：

  • DM 能力渠道的默认行为是配对：
    • 未知发送者收到配对代码；bot 不处理他们的消息。
    • 批准使用：openclaw pairing approve --channel &lt;channel&gt; [--account &lt;id&gt;] <code>
    • 待处理请求每个渠道最多 3 个；如果代码未到达，检查 openclaw pairing list --channel &lt;channel&gt; [--account &lt;id&gt;]。
  • 公开打开 DM 需要显式选择加入（dmPolicy: "open" 和白名单 "*"）。

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

提示注入只关心公开 bot 吗？ ​

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

最大的风险是在工具启用时：模型可能被诱骗泄露上下文或代表你调用工具。通过以下方式减少影响范围：

  • 使用只读或禁用工具的"阅读器"Agent 来总结不可信内容
  • 为启用工具的 Agent 关闭 web_search / web_fetch / browser
  • 将解码的文件/文档文本也视为不可信：OpenResponses input_file 和媒体附件提取都将提取的文本包裹在明确的外部内容边界标记内，而不是传递原始文件文本
  • 沙箱化和严格的工具白名单

详情：Security。

我的 bot 应该有它自己的电子邮件、GitHub 账号或电话号码吗？ ​

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

从小处开始。仅授予所需工具和账号的实际访问权限，之后根据需要扩展。

文档：Security、Pairing。

我能给它对我的短信的完全自主权吗？这安全吗？ ​

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

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

如果你想实验，在专门账号上做并保持隔离。参见 Security。

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

可以，如果 Agent 仅聊天且输入受信任。较小的层级更容易受指令劫持影响，因此避免用于启用工具的 Agent 或读取不可信内容时。如果必须使用较小的模型，锁定工具并在沙箱内运行。参见 Security。

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

配对代码仅在未知发送者向 bot 发送消息且 dmPolicy: "pairing" 启用时发送。/start 本身不会生成代码。

检查待处理请求：

bash
openclaw pairing list telegram

如果希望立即访问，白名单你的发送者 ID 或为该账户设置 dmPolicy: "open"。

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

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

批准配对使用：

bash
openclaw pairing approve whatsapp <code>

列出待处理请求：

bash
openclaw pairing list whatsapp

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

聊天命令、中止任务和"它不停下来" ​

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

大多数内部或工具消息仅当该会话启用 verbose、trace 或 reasoning 时才显示。

在你看到的聊天中修复：

/verbose off
/trace off
/reasoning off

如果仍然嘈杂，检查 Control UI 中的会话设置并将 verbose 设置为 inherit。同时确认未使用具有 verboseDefault 设置为 on 的 bot 配置文件。

文档：Thinking and verbose、Security。

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

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

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

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

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

process action:kill sessionId:XXX

Slash 命令概览：参见 Slash commands。

大多数命令必须以独立消息发送并以 / 开头，但少数快捷方式（如 /status）对白名单发送者也内联工作。

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

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

启用 Agent 的跨提供商消息：

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

编辑配置后重启 gateway。

为什么 bot 感觉"忽略"快速连续的消息？ ​

运行中的提示默认被引导到活动运行。使用 /queue 选择活动运行行为：

  • steer - 在下一个模型边界引导活动运行
  • followup - 将消息排队并在当前运行结束后逐一运行
  • collect - 兼容消息排队并在当前运行结束后回复一次
  • interrupt - 中止当前运行并重新开始

默认模式是 steer。你可以为排队模式添加选项如 debounce:0.5s cap:25 drop:summarize。参见 Command queue 和 Steering queue。

杂项 ​

Anthropic 使用 API 密钥时的默认模型是什么？ ​

在 OpenClaw 中，凭证和模型选择是分开的。设置 ANTHROPIC_API_KEY（或通过在认证配置文件中存储 Anthropic API 密钥）启用认证，但实际的默认模型是你在 agents.defaults.model.primary 中配置的任何模型（例如 anthropic/claude-sonnet-4-6 或 anthropic/claude-opus-4-6）。如果你看到 No credentials found for profile "anthropic:default"，意味着 Gateway 无法在运行 Agent 的预期的 auth-profiles.json 中找到 Anthropic 凭证。

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

相关文档 ​

常见问题 ​

Q: 我的 OpenClaw 每次重启都要重新配置，有没有快速保存配置的方法？ ​

A: 配置存在 ~/.openclaw/openclaw.json，只要不删这个文件，重启后配置完全保留。如果想备份，运行 openclaw backup create 生成完整存档文件。

Q: 能用 Bun 代替 Node 运行 Gateway 吗？ ​

A: 官方不推荐。Bun 在 WhatsApp 和 Telegram 渠道上已知存在运行时 bug，生产环境请坚持用 Node >= 22。

Q: 报错 openclaw gateway status 显示 RPC 不可达，怎么快速修复？ ​

A: 先运行 openclaw doctor（自动修复大多数配置问题），然后 openclaw gateway restart。如果仍有问题，用 openclaw logs --follow 查看实时日志定位具体错误。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策