跳到主要内容

FAQ

关于真实场景设置（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）的快速回答以及深度故障排除。有关运行时诊断，请参阅 故障排除。有关完整的配置参考，请参阅 配置。

目录​

如果出故障了，前 60 秒该做什么​

  1. 快速状态检查 (首选)

    clawdbot status

    快速本地摘要：操作系统 + 更新、网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当网关可达时）。

  2. 可粘贴的报告 (分享时安全)

    clawdbot status --all

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

  3. 守护进程 + 端口状态

    clawdbot gateway status

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

  4. 深度探测

    clawdbot status --deep

    运行网关健康检查 + 提供商探测（需要网关可达）。参见 健康状况 (Health)。

  5. 查看最新日志

    clawdbot logs --follow

    如果 RPC 掉线，请回退到：

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

    文件日志与服务日志是分开的；参见 日志记录 (Logging) 和 网关故障排除 (Troubleshooting)。

  6. 运行医生 (修复)

    clawdbot doctor

    修复/迁移配置/状态 + 运行健康检查。参见 医生 (Doctor)。

  7. 网关快照

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

    向运行中的网关请求完整快照（仅限 WS）。参见 健康状况 (Health)。

快速入门和首次运行设置​

我卡住了，最快的脱困方法是什么？​

使用能够 看到您机器 的本地 AI 智能体。这比在 Discord 中提问要有效得多，因为大多数“我卡住了”的情况都是 本地配置或环境问题，远程助手无法检查。

这些工具可以阅读仓库、运行命令、检查日志并帮助修复您的机器级设置（PATH、服务、权限、身份验证文件）。通过 可破解的 (git) 安装 为它们提供 完整的源码签出：

curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git

这将从 git 签出 安装 Clawdbot，因此智能体可以阅读代码 + 文档并推断您正在运行的确切版本。您以后可以随时通过重新运行不带 --install-method git 的安装程序切回稳定版。

提示：让智能体 规划并监督 修复（逐步进行），然后仅执行必要的命令。这样可以保持更改较小且更易于审计。

如果您发现了一个真正的错误或修复方法，请提交 GitHub issue 或发送 PR： https://github.com/clawdbot/clawdbot/issues https://github.com/clawdbot/clawdbot/pulls

从这些命令开始（在寻求帮助时分享输出）：

clawdbot status
clawdbot models status
clawdbot doctor

它们的作用：

  • clawdbot status: 网关/智能体健康状况 + 基础配置的快速快照。
  • clawdbot models status: 检查提供商身份验证 + 模型可用性。
  • clawdbot doctor: 验证并修复常见的配置/状态问题。

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

快速调试循环：如果出故障了，前 60 秒该做什么。 安装文档：安装、安装程序标志、更新。

安装和设置 Clawdbot 的推荐方式是什么？​

仓库推荐从源码运行并使用入职向导：

curl -fsSL https://clawd.bot/install.sh | bash
clawdbot onboard --install-daemon

向导还可以自动构建 UI 资源。入职后，您通常在端口 18789 上运行网关。

从源码安装（贡献者/开发人员）：

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm build
pnpm ui:build # 首次运行时自动安装 UI 依赖
clawdbot onboard

如果您还没有全局安装，请通过 pnpm clawdbot onboard 运行它。

入职后如何打开仪表板？​

向导现在会在入职后立即打开带有 Token 化仪表板 URL 的浏览器，并在摘要中打印完整链接（带 Token）。请保持该标签页打开；如果它没有启动，请在同一台机器上复制/粘贴打印的 URL。Token 仅保存在本地主机上——不会从浏览器获取任何内容。

如何在 localhost vs 远程机器上验证仪表板 (Token)？​

Localhost (同一台机器):

  • 打开 http://127.0.0.1:18789/。
  • 如果要求身份验证，请运行 clawdbot dashboard 并使用 Token 化链接 (?token=...)。
  • 该 Token 与 gateway.auth.token (或 CLAWDBOT_GATEWAY_TOKEN) 的值相同，并在首次加载后由 UI 存储。

不在 localhost:

  • Tailscale Serve (推荐): 保持绑定到 loopback，运行 clawdbot gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，身份标头即可满足身份验证（无需 Token）。
  • Tailnet 绑定: 运行 clawdbot gateway --bind tailnet --token "<token>"，打开 http://<tailscale-ip>:18789/，在仪表板设置中粘贴 Token。
  • SSH 隧道: ssh -N -L 18789:127.0.0.1:18789 user@host 然后从 clawdbot dashboard 打开 http://127.0.0.1:18789/?token=...。

参见 仪表板 (Dashboard) 和 Web 界面 以了解绑定模式和身份验证详情。

我需要什么运行时？​

需要 Node >= 22。推荐使用 pnpm。不推荐 在网关中使用 Bun。

它能在 Raspberry Pi 上运行吗？​

可以。网关非常轻量级——文档列出 512MB-1GB RAM、1 核 和大约 500MB 磁盘空间足以供个人使用，并指出 Raspberry Pi 4 即可运行它。

如果您想要额外的余地（日志、媒体、其他服务），建议使用 2GB，但这并不是硬性最低要求。

提示：一台小型 Pi/VPS 可以托管网关，您可以在笔记本电脑/手机上配对 节点 (Nodes)，以使用本地屏幕/摄像头/画布或执行命令。参见 节点 (Nodes)。

有针对 Raspberry Pi 安装的建议吗？​

简短版：它可以工作，但可能会有一些不完善的地方。

  • 使用 64 位 操作系统并保持 Node >= 22。
  • 首选 可破解的 (git) 安装，以便您可以查看日志并快速更新。
  • 从不带频道/技能的配置开始，然后逐个添加。
  • 如果遇到奇怪的二进制问题，通常是 ARM 兼容性 问题。

文档：Linux、安装。

它卡在 "wake up my friend" / 入职无法孵化。现在该怎么办？​

该屏幕取决于网关是否可达并已通过身份验证。TUI 也会在首次孵化时自动发送 "Wake up, my friend!"。如果您看到该行但 没有回复 且 Token 保持为 0，则说明智能体从未运行。

  1. 重启网关：
clawdbot gateway restart
  1. 检查状态 + 身份验证：
clawdbot status
clawdbot models status
clawdbot logs --follow
  1. 如果仍然卡住，请运行：
clawdbot doctor

如果网关是远程的，请确保隧道/Tailscale 连接已启动，并且 UI 指向了正确的网关。参见 远程访问 (Remote access)。

我可以将设置迁移到新机器 (Mac mini) 而不重新参加入职流程吗？​

可以。复制 状态目录 和 工作区，然后运行一次 Doctor。只要您复制了 这两个 位置，就可以保持您的机器人“完全相同”（记忆、会话历史、身份验证和频道状态）：

  1. 在新机器上安装 Clawdbot。
  2. 从旧机器复制 $CLAWDBOT_STATE_DIR（默认：~/.clawdbot）。
  3. 复制您的工作区（默认：~/clawd）。
  4. 运行 clawdbot doctor 并重启网关服务。

这将保留配置、身份验证配置文件、WhatsApp 凭据、会话和记忆。如果您处于远程模式，请记住网关主机拥有会话存储和工作区。

重要提示： 如果您只将工作区提交/推送到 GitHub，那么您备份的是 记忆 + 引导文件，但 不包括 会话历史或身份验证。这些文件位于 ~/.clawdbot/ 下（例如 ~/.clawdbot/agents/<agentId>/sessions/）。

相关内容：文件在磁盘上的位置、 智能体工作区 (Agent workspace)、医生 (Doctor)、 远程模式 (Remote mode)。

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

查看 GitHub 变更日志 (Changelog)： https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md

最新的条目位于顶部。如果顶部章节标记为 Unreleased，则下一个带有日期的章节就是最新发布的版本。条目按 Highlights (亮点)、Changes (变更) 和 Fixes (修复) 分组（如果需要，还会有文档/其他章节）。

我无法访问 docs.clawd.bot (SSL 错误)。现在该怎么办？​

某些 Comcast/Xfinity 连接会通过 Xfinity Advanced Security 错误地拦截 docs.clawd.bot。请禁用它或将 docs.clawd.bot 添加到白名单，然后重试。更多详情：故障排除。 请在此处报告以帮助我们解除拦截：https://spa.xfinity.com/check_url_status。

如果您仍然无法访问该网站，文档在 GitHub 上有备份： https://github.com/clawdbot/clawdbot/tree/main/docs

stable 和 beta 有什么区别？​

Stable (稳定版) 和 beta (测试版) 是 npm dist-tags，而不是不同的代码分支：

  • latest = 稳定版
  • beta = 用于测试的早期构建版本

我们将构建版本发布到 beta，进行测试，一旦构建版本稳定，我们就将 该版本提升为 latest。这就是为什么 beta 和 stable 可能指向 同一个版本。

查看变更内容： https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md

如何安装 beta 版本，以及 beta 和 dev 有什么区别？​

Beta 是 npm dist-tag beta（可能与 latest 相同）。 Dev 是 main 分支 (git) 的最新进度；发布时，它使用 npm dist-tag dev。

单行命令 (macOS/Linux)：

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

Windows 安装程序 (PowerShell)： https://clawd.bot/install.ps1

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

安装和入职通常需要多长时间？​

大致指南：

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

如果卡住了，请参考 安装程序卡住了 以及 我卡住了 中的快速调试循环。

如何尝试最新的功能？​

有两个选项：

  1. 开发频道 (git 签出):
clawdbot update --channel dev

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

  1. 可破解的安装 (从安装程序网站):
curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git

这将为您提供一个可以编辑的本地仓库，然后通过 git 进行更新。

如果您更喜欢手动进行干净的克隆，请使用：

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

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

安装程序卡住了？我该如何获得更多反馈？​

以 详细模式 (verbose output) 重新运行安装程序：

curl -fsSL https://clawd.bot/install.sh | bash -s -- --verbose

详细模式下的 Beta 安装：

curl -fsSL https://clawd.bot/install.sh | bash -s -- --beta --verbose

对于可破解的 (git) 安装：

curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --verbose

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

Windows 安装显示找不到 git 或无法识别 clawdbot​

两个常见的 Windows 问题：

1) npm error spawn git / git not found

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

2) 安装后无法识别 clawdbot

  • 您的 npm 全局 bin 文件夹不在 PATH 中。
  • 检查路径： 
    npm config get prefix
  • 确保 <prefix>\bin 在 PATH 中（在大多数系统上，它是 %AppData%\npm）。
  • 更新 PATH 后，关闭并重新打开 PowerShell。

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

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

使用 可破解的 (git) 安装，这样您在本地就拥有完整的源码和文档，然后在 该文件夹中 询问您的机器人（或 Claude/Codex），以便它可以阅读仓库并准确回答。

curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git

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

如何在 Linux 上安装 Clawdbot？​

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

如何在 VPS 上安装 Clawdbot？​

任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 连接到网关。

指南：exe.dev、Hetzner、Fly.io。 远程访问：网关远程访问。

云端/VPS 安装指南在哪里？​

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

在云端的工作原理：网关运行在服务器上，您通过控制 UI（或 Tailscale/SSH）从笔记本电脑/手机访问它。您的状态 + 工作区位于服务器上，因此请将主机视为真相来源并进行备份。

您可以将 节点 (Nodes) (Mac/iOS/Android/headless) 配对到该云端网关，以便访问本地屏幕/摄像头/画布或在笔记本电脑上运行命令，同时保持网关在云端运行。

中心：平台 (Platforms)。远程访问：网关远程访问。 节点：节点 (Nodes)、节点 CLI。

我可以让 Clawd 自行更新吗？​

简短回答：可以，但不推荐。更新流程可能会重启网关（这会中断当前会话），可能需要干净的 git 签出，并可能提示确认。更安全的方法是：作为操作员从 shell 运行更新。

使用 CLI：

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

如果您必须从智能体自动化更新：

clawdbot update --yes --no-restart
clawdbot gateway restart

文档：更新、正在更新。

入职向导实际上做了什么？​

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

  • 模型/身份验证设置 (推荐使用 Anthropic setup-token 用于 Claude 订阅，支持 OpenAI Codex OAuth，API 密钥可选，支持 LM Studio 本地模型)
  • 工作区 位置 + 引导文件
  • 网关设置 (绑定/端口/身份验证/Tailscale)
  • 提供商 (WhatsApp, Telegram, Discord, Mattermost (插件), Signal, iMessage)
  • 守护进程安装 (macOS 上为 LaunchAgent；Linux/WSL2 上为 systemd 用户单元)
  • 健康检查 和 技能 选择

如果配置的模型未知或缺少身份验证，它也会发出警告。

运行它需要 Claude 或 OpenAI 订阅吗？​

不需要。您可以使用 API 密钥 (Anthropic/OpenAI/其他) 或 仅限本地的模型 来运行 Clawdbot，这样您的数据就会保留在您的设备上。订阅 (Claude Pro/Max 或 OpenAI Codex) 是对这些提供商进行身份验证的可选方式。

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

我可以在没有 API 密钥的情况下使用 Claude Max 订阅吗？​

可以。您可以使用 Claude Code CLI OAuth 或 setup-token 进行身份验证，而无需 API 密钥。这是订阅路径。

Claude Pro/Max 订阅 不包含 API 密钥，因此这是订阅帐户的正确方法。重要提示：您必须向 Anthropic 确认此类使用在其订阅政策和条款下是被允许的。如果您想要最明确、受支持的路径，请使用 Anthropic API 密钥。

Anthropic setup-token 身份验证是如何工作的？​

claude setup-token 通过 Claude Code CLI 生成一个 Token 字符串（它在 Web 控制台中不可用）。您可以在 任何机器 上运行它。如果网关主机上存在 Claude Code CLI 凭据，Clawdbot 可以重用它们；否则选择 Anthropic token (paste setup-token) 并粘贴字符串。该 Token 将作为 anthropic 提供商的身份验证配置文件存储，并像 API 密钥或 OAuth 配置文件一样使用。更多详情：OAuth。

Clawdbot 将 auth.profiles["anthropic:claude-cli"].mode 保持设置为 "oauth"，以便该配置文件同时接受 OAuth 和 setup-token 凭据；旧的 "token" 模式条目将自动迁移。

在哪里可以找到 Anthropic setup-token？​

它 不在 Anthropic 控制台中。setup-token 是由 任何机器 上的 Claude Code CLI 生成的：

claude setup-token

复制它打印的 Token，然后在向导中选择 Anthropic token (paste setup-token)。如果您想在网关主机上运行它，请使用 clawdbot models auth setup-token --provider anthropic。如果您在其他地方运行了 claude setup-token，请使用 clawdbot models auth paste-token --provider anthropic 在网关主机上粘贴它。参见 Anthropic。

你们支持 Claude 订阅身份验证 (Claude Code OAuth) 吗？​

支持。Clawdbot 可以 重用 Claude Code CLI 凭据 (OAuth)，也支持 setup-token。如果您有 Claude 订阅，我们建议在长期运行的设置中使用 setup-token（需要 Claude Pro/Max + claude CLI）。您可以在任何地方生成它并将其粘贴到网关主机上。支持 OAuth 重用，但请避免分别通过 Clawdbot 和 Claude Code 登录，以防止 Token 冲突。参见 Anthropic 和 OAuth。

注意：Claude 订阅访问受 Anthropic 条款约束。对于生产或多用户工作负载，API 密钥通常是更安全的选择。

为什么我看到来自 Anthropic 的 HTTP 429: rate_limit_error？​

这意味着您的 Anthropic 配额/速率限制 已在当前窗口中耗尽。如果您使用 Claude 订阅 (setup-token 或 Claude Code OAuth)，请等待窗口重置或升级您的计划。如果您使用 Anthropic API 密钥，请在 Anthropic 控制台中检查使用情况/账单，并根据需要提高限制。

提示：设置一个 回退模型 (fallback model)，以便在提供商受到速率限制时，Clawdbot 可以继续回复。参见 模型 和 OAuth。

支持 AWS Bedrock 吗？​

支持 - 通过 pi-ai 的 Amazon Bedrock (Converse) 提供商进行 手动配置。您必须在网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参见 Amazon Bedrock 和 模型提供商。如果您更喜欢托管密钥流程，在 Bedrock 前面使用 OpenAI 兼容的代理仍然是一个有效的选择。

Codex 身份验证是如何工作的？​

Clawdbot 通过 OAuth 或重用您的 Codex CLI 登录信息 (~/.codex/auth.json) 支持 OpenAI Code (Codex)。向导可以导入 CLI 登录信息或运行 OAuth 流程，并在适当时将默认模型设置为 openai-codex/gpt-5.2。参见 模型提供商 和 向导。

你们支持 OpenAI 订阅身份验证 (Codex OAuth) 吗？​

支持。Clawdbot 完全支持 OpenAI Code (Codex) 订阅 OAuth，也可以重用网关主机上现有的 Codex CLI 登录信息 (~/.codex/auth.json)。入职向导可以为您导入 CLI 登录信息或运行 OAuth 流程。

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

如何设置 Gemini CLI OAuth​

Gemini CLI 使用 插件身份验证流程，而不是 clawdbot.json 中的客户端 ID 或密钥。

步骤：

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

这会将 OAuth 令牌存储在网关主机的身份验证配置文件中。详情请参阅：模型提供商。

本地模型适合日常聊天吗？​

通常不适合。Clawdbot 需要大上下文和强大的安全性；小模型会截断内容并出现幻觉。如果您必须尝试，请运行您能在本地运行的 最大 MiniMax M2.1 版本（使用 LM Studio），并参阅 /gateway/local-models。较小/量化后的模型会增加提示注入风险 - 请参阅 安全性。

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

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

我必须买一台 Mac Mini 才能安装吗？​

不需要。Clawdbot 可以运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的 - 有些人买它作为常驻主机，但小型 VPS、家用服务器或树莓派级别的设备也可以工作。

您只需要在 使用仅限 macOS 的工具 时才需要 Mac。对于 iMessage，您可以将网关保留在 Linux 上，并通过将 channels.imessage.cliPath 指向 SSH 包装器，在任何 Mac 上通过 SSH 运行 imsg。如果您需要其他仅限 macOS 的工具，请在 Mac 上运行网关或配对 macOS 节点。

文档：iMessage、节点 (Nodes)、Mac 远程模式。

iMessage 支持需要 Mac mini 吗？​

您需要 某台登录了信息 (Messages) 的 macOS 设备。它 不一定 要是 Mac mini - 任何 Mac 都可以。Clawdbot 的 iMessage 集成运行在 macOS 上（BlueBubbles 或 imsg），而网关可以运行在其他地方。

常见设置：

  • 在 Linux/VPS 上运行网关，并将 channels.imessage.cliPath 指向在 Mac 上运行 imsg 的 SSH 包装器。
  • 如果您想要最简单的单机设置，请在 Mac 上运行所有程序。

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

如果我买了一台 Mac mini 来运行 Clawdbot，我可以将它连接到 my MacBook Pro 吗？​

可以。Mac mini 可以运行网关，而您的 MacBook Pro 可以作为 节点 (node)（伴侣设备）连接。节点不运行网关 - 它们在该设备上提供额外的功能，如屏幕/摄像头/画布和 system.run。

常见模式：

  • 网关运行在 Mac mini 上（始终开启）。
  • MacBook Pro 运行 macOS 应用程序或节点主机，并与网关配对。
  • 使用 clawdbot nodes status / clawdbot nodes list 来查看它。

文档：节点 (Nodes)、节点 CLI。

我可以使用 Bun 吗？​

不推荐 使用 Bun。我们发现了一些运行时错误，尤其是在使用 WhatsApp 和 Telegram 时。请使用 Node 以获得稳定的网关。

如果您仍然想尝试 Bun，请在不运行 WhatsApp/Telegram 的非生产环境网关上进行。

Telegram：allowFrom 中填什么？​

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

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

  • 给您的机器人发私信，然后运行 clawdbot logs --follow 并查看 from.id。

官方机器人 API：

  • 给您的机器人发私信，然后调用 https://api.telegram.org/bot<bot_token>/getUpdates 并查看 message.from.id。

第三方方法（隐私性较低）：

  • 给 @userinfobot 或 @getidsbot 发私信。

参见 /channels/telegram。

多个人可以使用同一个 WhatsApp 号码连接不同的 Clawdbot 吗？​

可以，通过 多智能体路由 (multi-agent routing)。将每个发送者的 WhatsApp 私信 (DM)（peer kind: "dm"，发送者 E.164 格式，如 +15551234567）绑定到不同的 agentId，这样每个人都有自己的工作区和会话存储。回复仍然来自 同一个 WhatsApp 账号，并且私信访问控制 (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) 是针对每个 WhatsApp 账号全局生效的。参见 多智能体路由 (Multi-Agent Routing) 和 WhatsApp。

我可以运行一个“快速聊天”智能体和一个“用于编码的 Opus”智能体吗？​

可以。使用多智能体路由：为每个智能体分配自己的默认模型，然后将入站路由（提供商账号或特定对等节点）绑定到每个智能体。示例配置位于 多智能体路由 (Multi-Agent Routing)。另请参阅 模型 (Models) 和 配置 (Configuration)。

Homebrew 在 Linux 上可以工作吗？​

可以。Homebrew 支持 Linux (Linuxbrew)。快速设置：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>

如果您通过 systemd 运行 Clawdbot，请确保服务 PATH 包含 /home/linuxbrew/.linuxbrew/bin（或您的 brew 前缀），以便在非登录 shell 中可以解析 brew 安装的工具。 最近的版本还会将常见的用户 bin 目录预置到 Linux systemd 服务中（例如 ~/.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。

可破解的 (git) 安装和 npm 安装有什么区别？​

  • 可破解的 (git) 安装： 完整的源代码签出，可编辑，最适合贡献者。 您在本地运行构建，并可以修补代码/文档。
  • npm 安装： 全局 CLI 安装，没有仓库，最适合“直接运行”。 更新来自 npm 的发行标签 (dist-tags)。

文档：入门指南、正在更新。

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

可以。安装另一个版本，然后运行 Doctor，以便网关服务指向新的入口点。 这 不会删除您的数据 - 它只会更改 Clawdbot 的代码安装。您的状态 (~/.clawdbot) 和工作区 (~/clawd) 将保持不变。

从 npm 切换到 git：

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

从 git 切换到 npm：

npm install -g clawdbot@latest
clawdbot doctor
clawdbot gateway restart

Doctor 会检测网关服务入口点不匹配，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 --repair）。

备份提示：请参阅 推荐的备份策略。

我应该在笔记本电脑还是 VPS 上运行网关？​

简短回答：如果您想要 24/7 的可靠性，请使用 VPS。如果您想要最低的摩擦且可以接受休眠/重启，请在本地运行。

笔记本电脑（本地网关）

  • 优点： 无服务器成本，直接访问本地文件，实时浏览器窗口。
  • 缺点： 休眠/网络掉线 = 断连，操作系统更新/重启会中断，必须保持唤醒。

VPS / 云端

  • 优点： 始终在线，网络稳定，没有笔记本电脑休眠问题，更容易保持运行。
  • 缺点： 通常是无头 (headless) 运行（使用截图），仅限远程文件访问，您必须通过 SSH 进行更新。

Clawdbot 特有说明： WhatsApp/Telegram/Slack/Mattermost (插件)/Discord 都可以从 VPS 正常工作。唯一的真正权衡是 无头浏览器 与可见窗口。请参阅 浏览器 (Browser)。

推荐默认： 如果您以前遇到过网关断开连接，请选择 VPS。如果您正在积极使用 Mac 并希望访问本地文件或使用带有可见浏览器的 UI 自动化，那么本地网关非常棒。

在专用机器上运行 Clawdbot 有多重要？​

不是必需的，但 为了可靠性和隔离性，建议这样做。

  • 专用主机 (VPS/Mac mini/Pi)： 始终在线，休眠/重启中断更少，权限更清晰，更容易保持运行。
  • 共享笔记本电脑/台式机： 对于测试和积极使用完全没问题，但在机器休眠或更新时可能会出现暂停。

如果您想兼顾两者的优点，请将网关保留在专用主机上，并将您的笔记本电脑配对为 节点 (node)，以使用本地屏幕/摄像头/执行工具。请参阅 节点 (Nodes)。 有关安全指南，请阅读 安全性 (Security)。

最低 VPS 要求和推荐的操作系统是什么？​

Clawdbot 是轻量级的。对于一个基本的网关 + 一个聊天频道：

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

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

文档：Linux、VPS 托管。

我可以在虚拟机中运行 Clawdbot 吗？有什么要求？​

可以。将虚拟机视为与 VPS 相同：它需要始终在线、可访问，并且有足够的 RAM 供网关和您启用的任何频道使用。

基准指南：

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

如果您使用的是 Windows，WSL2 是最简单的虚拟机风格设置，并且具有最好的工具兼容性。请参阅 Windows、VPS 托管。 如果您在虚拟机中运行 macOS，请参阅 macOS VM。

什么是 Clawdbot？​

用一段话概括，什么是 Clawdbot？​

Clawdbot 是一个在您自己的设备上运行的个人 AI 智能体。它在您已经使用的消息传递平台（WhatsApp、Telegram、Slack、Mattermost (插件)、Discord、Google Chat、Signal、iMessage、WebChat）上进行回复，并且在支持的平台上还可以进行语音交流和实时画布 (Canvas) 互动。网关 (Gateway) 是始终在线的控制平面；而智能体本身就是产品。

它的价值主张是什么？​

Clawdbot 不仅仅是一个“Claude 外壳”。它是一个 本地优先的控制平面，让您可以在 自己的硬件 上运行功能强大的智能体，可以通过您已经在使用的聊天应用程序访问，具有状态会话、记忆和工具 - 且无需将您的工作流程控制权交给托管的 SaaS。

亮点：

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

文档：网关 (Gateway)、频道 (Channels)、多智能体 (Multi-agent)、记忆 (Memory)。

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

好的入门项目：

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

它可以处理大型任务，但最好将其拆分为多个阶段，并使用子智能体进行并行工作。

Clawdbot 的五大日常用例是什么？​

日常的优势通常体现在：

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

Clawdbot 能帮我为 SaaS 做潜在客户开发推广、广告和博客吗？​

在 研究、筛选和起草 方面是可以的。它可以扫描网站、建立候选名单、总结潜在客户，并撰写推广或广告文案草稿。

对于 推广或广告投放，请保持人工参与。避免垃圾邮件，遵守当地法律和平台政策，并在发送任何内容之前进行审查。最安全模式是让 Clawdbot 起草，由您批准。

文档：安全性 (Security)。

与 Claude Code 相比，在 Web 开发方面有哪些优势？​

Clawdbot 是一个 个人智能体 和协作层，而不是 IDE 的替代品。在仓库内部进行最直接的编码循环时，请使用 Claude Code 或 Codex。当您想要持久记忆、跨设备访问和工具编排时，请使用 Clawdbot。

优势：

  • 跨会话的持久记忆 + 工作区
  • 多平台访问 (WhatsApp, Telegram, TUI, WebChat)
  • 工具编排 (浏览器、文件、调度、钩子)
  • 始终在线的网关 (运行在 VPS 上，随时随地交互)
  • 节点 (Nodes) 用于本地浏览器/屏幕/摄像头/执行

展示：https://clawd.bot/showcase

技能与自动化​

如何在不保持仓库脏乱的情况下自定义技能？​

使用托管覆盖 (managed overrides) 而不是编辑仓库副本。将您的更改放在 ~/.clawdbot/skills/<name>/SKILL.md 中（或通过 ~/.clawdbot/clawdbot.json 中的 skills.load.extraDirs 添加文件夹）。优先级顺序是 <workspace>/skills > ~/.clawdbot/skills > 捆绑技能，因此托管覆盖在不触动 git 的情况下获胜。只有值得向上游提交的编辑才应该留在仓库中并作为 PR 发布。

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

可以。通过 ~/.clawdbot/clawdbot.json 中的 skills.load.extraDirs 添加额外目录（优先级最低）。默认优先级顺序保持不变：<workspace>/skills → ~/.clawdbot/skills → 捆绑技能 → skills.load.extraDirs。clawdhub 默认安装到 ./skills，Clawdbot 将其视为 <workspace>/skills。

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

目前支持的模式有：

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

参见 Cron 任务、多智能体路由 (Multi-Agent Routing) 和 斜杠命令 (Slash commands)。

机器人在执行繁重工作时会冻结。我该如何卸载它？​

使用 子智能体 (sub-agents) 处理耗时或并行的任务。子智能体在自己的会话中运行，返回摘要，并保持您的主聊天响应。

让您的机器人“为此任务生成一个子智能体”或使用 /subagents。 在聊天中使用 /status 查看网关现在正在做什么（以及它是否忙碌）。

Token 提示：长任务和子智能体都会消耗 token。如果担心成本，请通过 agents.defaults.subagents.model 为子智能体设置更便宜的模型。

文档：子智能体 (Sub-agents)。

Cron 或提醒不触发。我该检查什么？​

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

检查清单：

  • 确认 cron 已启用 (cron.enabled) 且未设置 CLAWDBOT_SKIP_CRON。
  • 检查网关是否 24/7 运行（无休眠/重启）。
  • 验证任务的时区设置 (--tz vs 主机时区)。

调试：

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

文档：Cron 任务、Cron vs Heartbeat。

如何在 Linux 上安装技能？​

使用 ClawdHub (CLI) 或将技能直接放入您的工作区。macOS 的技能 UI 在 Linux 上不可用。 在 https://clawdhub.com 浏览技能。

安装 ClawdHub CLI（任选其一）：

npm i -g clawdhub
pnpm add -g clawdhub

Clawdbot 可以在后台按计划或连续运行任务吗？​

可以。使用网关调度器：

  • Cron 任务 用于计划或循环任务（跨重启持久存在）。
  • Heartbeat 用于“主会话”的定期检查。
  • Isolated jobs 用于自主代理，发布摘要或交付到聊天中。

Docs: Cron 任务, Cron vs Heartbeat, Heartbeat.

我可以在 Linux 上运行仅限 Apple macOS 的技能吗？​

不能直接运行。macOS 技能受到 metadata.clawdbot.os 以及所需二进制文件的限制，并且只有当技能在 网关主机 上符合条件时，才会出现在系统提示词中。在 Linux 上，除非你覆盖限制，否则 darwin 专用技能（如 imsg、apple-notes、apple-reminders）将不会加载。

你有三种支持的模式：

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

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

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

  1. 为二进制文件创建 SSH 包装器（例如：imsg）： 
    #!/usr/bin/env bash
    set -euo pipefail
    exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"
  2. 将包装器放在 Linux 主机的 PATH 上（例如 ~/bin/imsg）。
  3. 覆盖技能元数据（工作区或 ~/.clawdbot/skills）以允许 Linux： 
    ---
    name: imsg
    description: iMessage/SMS CLI for listing chats, history, watch, and sending.
    metadata: {"clawdbot":{"os":["darwin","linux"],"requires":{"bins":["imsg"]}}}
    ---
  4. 启动新会话，以便刷新技能快照。

特别是对于 iMessage，你还可以将 channels.imessage.cliPath 指向 SSH 包装器（Clawdbot 只需要标准输入输出）。参见 iMessage。

你们有 Notion 或 HeyGen 的集成吗？​

目前没有内置。

选项：

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

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

  • 每个客户端一个 Notion 页面（上下文 + 偏好 + 进行中的工作）。
  • 要求代理在会话开始时获取该页面。

如果你想要原生集成，请开启功能请求或针对这些 API 构建一个技能。

安装技能：

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

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

如何安装用于浏览器接管的 Chrome 扩展程序？​

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

clawdbot browser extension install
clawdbot browser extension path

然后 Chrome → chrome://extensions → 启用“开发者模式” → “加载已解压的扩展程序” → 选择该文件夹。

完整指南（包括通过 Tailscale 的远程网关 + 安全说明）：Chrome 扩展程序

如果网关运行在与 Chrome 相同的机器上（默认设置），你通常 不需要 运行 clawdbot browser serve。 你仍然需要在想要控制的标签页上点击扩展程序按钮（它不会自动附加）。

沙箱与记忆​

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

是的。参见 沙箱。关于 Docker 特定设置（在 Docker 中运行完整网关或沙箱镜像），参见 Docker。

我可以在保持 DM 私人的同时，让群组使用一个代理进行公共沙箱化吗？

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

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

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

关键配置参考：网关配置

如何将宿主机文件夹挂载到沙箱中？​

将 agents.defaults.sandbox.docker.binds 设置为 ["host:path:mode"]（例如，"/home/user/src:/src:ro"）。全局和每个代理的挂载会合并；当 scope: "shared" 时，每个代理的挂载将被忽略。对任何敏感内容使用 :ro，并记住挂载会绕过沙箱文件系统的隔离。参见 沙箱 和 沙箱 vs 工具策略 vs 提权 以获取示例和安全说明。

记忆是如何工作的？​

Clawdbot 的记忆只是代理工作区中的 Markdown 文件：

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

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

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

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

这仍然是我们正在改进的领域。提醒模型存储记忆会有所帮助；它会知道该怎么做。如果它一直遗忘，请验证网关在每次运行时是否使用相同的工作区。

文档：记忆, 代理工作区。

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

只有当你使用 OpenAI 嵌入 (embeddings) 时才需要。Codex OAuth 涵盖了聊天/补全，并且 不 授予嵌入访问权限，因此 使用 Codex 登录（OAuth 或 Codex CLI 登录） 对语义记忆搜索没有帮助。OpenAI 嵌入仍然需要真实的 API 密钥（OPENAI_API_KEY 或 models.providers.openai.apiKey）。

如果你没有明确设置提供商，Clawdbot 会在能够解析 API 密钥（身份验证配置文件、models.providers.*.apiKey 或环境变量）时自动选择提供商。如果 OpenAI 密钥可以解析，它会优先选择 OpenAI，否则如果 Gemini 密钥可以解析，则选择 Gemini。如果两个密钥都不可用，记忆搜索将保持禁用状态，直到你进行配置。如果你配置并存在本地模型路径，Clawdbot 会优先选择 local。

如果你宁愿保持本地化，请设置 memorySearch.provider = "local"（并可选设置 memorySearch.fallback = "none"）。如果你想要 Gemini 嵌入，请设置 memorySearch.provider = "gemini" 并提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我们支持 OpenAI、Gemini 或本地 嵌入模型 - 参见 记忆 获取设置详情。

记忆会永远持久吗？有什么限制？​

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

文档：记忆, 上下文。

磁盘上的存储位置​

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

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

  • 默认本地： 会话、记忆文件、配置和工作区存储在网关主机上（~/.clawdbot + 你的工作区目录）。
  • 必要的远程： 你发送给模型提供商（Anthropic/OpenAI 等）的消息会进入它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在它们的服务器上。
  • 你控制痕迹： 使用本地模型可以将提示词保留在你的机器上，但频道流量仍然会通过频道的服务器。

相关内容：代理工作区, 记忆。

Clawdbot 将数据存储在哪里？​

所有内容都存储在 $CLAWDBOT_STATE_DIR 下（默认：~/.clawdbot）：

路径用途
$CLAWDBOT_STATE_DIR/clawdbot.json主配置 (JSON5)
$CLAWDBOT_STATE_DIR/credentials/oauth.json遗留 OAuth 导入（首次使用时复制到身份验证配置文件中）
$CLAWDBOT_STATE_DIR/agents/<agentId>/agent/auth-profiles.json身份验证配置文件（OAuth + API 密钥）
$CLAWDBOT_STATE_DIR/agents/<agentId>/agent/auth.json运行时身份验证缓存（自动管理）
$CLAWDBOT_STATE_DIR/credentials/提供商状态（例如 whatsapp/<accountId>/creds.json）
$CLAWDBOT_STATE_DIR/agents/每个代理的状态（agentDir + 会话）
$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/对话历史和状态（每个代理）
$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/sessions.json会话元数据（每个代理）

遗留的单代理路径：~/.clawdbot/agent/*（由 clawdbot doctor 迁移）。

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

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

这些文件存储在 代理工作区 中，而不是 ~/.clawdbot。

  • 工作区（每个代理）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md（或 memory.md）、memory/YYYY-MM-DD.md、可选的 HEARTBEAT.md。
  • 状态目录 (~/.clawdbot)：配置、凭据、身份验证配置文件、会话、日志和共享技能 (~/.clawdbot/skills)。

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

{
  agents: { defaults: { workspace: "~/clawd" } }
}

如果机器人在重启后“忘记”了事情，请确认网关在每次启动时是否使用相同的工作区（记住：远程模式使用的是 网关主机 的工作区，而不是你的本地笔记本电脑）。

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

参见 代理工作区 和 记忆。

推荐的备份策略是什么？​

将你的 代理工作区 放在一个 私有 git 仓库中，并将其备份到私有地方（例如 GitHub 私有仓库）。这会捕获记忆 + AGENTS/SOUL/USER 文件，并让你以后可以恢复助手的“思想”。

不要 提交 ~/.clawdbot 下的任何内容（凭据、会话、令牌）。如果你需要完整恢复，请分别备份工作区和状态目录（参见上面的迁移问题）。

文档：代理工作区。

如何完全卸载 Clawdbot？​

参见专用指南：卸载。

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

可以。工作区是 默认当前工作目录 (cwd) 和记忆锚点，而不是硬性的沙箱。相对路径会在工作区内解析，但绝对路径可以访问其他宿主机位置，除非启用了沙箱。如果你需要隔离，请使用 agents.defaults.sandbox 或每个代理的沙箱设置。如果你希望某个仓库成为默认工作目录，请将该代理的 workspace 指向该仓库根目录。Clawdbot 仓库只是源代码；除非你有意让代理在其中工作，否则请将工作区分开。

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

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

我处于远程模式，会话存储在哪里？​

会话状态归 网关主机 所有。如果你处于远程模式，你关心的会话存储在远程机器上，而不是你的本地笔记本电脑。参见 会话管理。

配置基础​

配置是什么格式？在哪里？​

Clawdbot 从 $CLAWDBOT_CONFIG_PATH（默认：~/.clawdbot/clawdbot.json）读取可选的 JSON5 配置：

$CLAWDBOT_CONFIG_PATH

如果文件缺失，它会使用较为安全的默认值（包括默认工作区 ~/clawd）。

我设置了 gateway.bind 为 lan 或 tailnet，现在没有任何监听，UI 显示未授权​

非回环 (Non-loopback) 绑定 需要身份验证。请配置 gateway.auth.mode + gateway.auth.token（或使用 CLAWDBOT_GATEWAY_TOKEN）。

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

注意：

  • gateway.remote.token 仅用于 远程 CLI 调用；它不会启用本地网关身份验证。
  • 控制 UI 通过 connect.params.auth.token（存储在应用/UI 设置中）进行身份验证。避免在 URL 中放置令牌。

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

向导默认会生成一个网关令牌（即使在回环地址上也是如此），因此 本地 WS 客户端必须进行身份验证。这会阻止其他本地进程调用网关。将令牌粘贴到控制 UI 设置（或你的客户端配置）中以进行连接。

如果你 真的 想要开放回环，请从配置中删除 gateway.auth。Doctor 可以随时为你生成令牌：clawdbot doctor --generate-gateway-token。

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

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

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

如何启用网页搜索和网页获取？​

web_fetch 无需 API 密钥即可工作。web_search 需要 Brave Search API 密钥。推荐做法： 运行 clawdbot configure --section web 将其存储在 tools.web.search.apiKey 中。环境变量替代方案：为网关进程设置 BRAVE_API_KEY。

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

注意：

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

文档：网页工具。

如何运行一个带有分布在不同设备上的专门工作节点的中央网关？​

常见的模式是 一个网关（例如 Raspberry Pi）加上 节点 (nodes) 和 代理 (agents)：

  • 网关 (中央): 拥有频道（Signal/WhatsApp）、路由和会话。
  • 节点 (设备): Mac/iOS/Android 作为外设连接并公开本地工具（system.run、canvas、camera）。
  • 代理 (工作节点): 为特殊角色准备的独立大脑/工作区（例如“Hetzner 运维”、“个人数据”）。
  • 子代理: 当你想要并行处理时，从主代理发起后台工作。
  • TUI: 连接到网关并切换代理/会话。

文档：节点, 远程访问, 多代理路由, 子代理, TUI。

Clawdbot 浏览器可以无头 (headless) 运行吗？​

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

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

默认值为 false（有界面）。在某些网站上，无头模式更有可能触发反爬虫检查。参见 浏览器。

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

  • 没有可见的浏览器窗口（如果需要视觉效果，请使用截图）。
  • 某些网站对无头模式下的自动化更加严格（验证码、反爬虫）。 例如，X/Twitter 经常屏蔽无头会话。

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

将 browser.executablePath 设置为你的 Brave 二进制路径（或任何基于 Chromium 的浏览器）并重启网关。 参见 浏览器 中的完整配置示例。

远程网关 + 节点​

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

Telegram 消息由 网关 处理。网关运行代理，只有在需要节点工具时才通过 网关 WebSocket 调用节点：

Telegram → 网关 → 代理 → node.* → 节点 → 网关 → Telegram

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

如果网关是远程托管的，我的代理如何访问我的电脑？​

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

典型设置：

  1. 在始终在线的主机（VPS/家庭服务器）上运行网关。
  2. 将网关主机 + 你的电脑放在同一个 Tailscale 网络中。
  3. 确保网关 WS 可达（Tailscale 绑定或 SSH 隧道）。
  4. 在本地打开 macOS 应用，并以 Remote over SSH 模式（或直接通过 Tailscale）连接，以便它可以注册为节点。
  5. 在网关上批准该节点： 
    clawdbot nodes pending
    clawdbot nodes approve <requestId>

不需要单独的 TCP 桥接；节点通过网关 WebSocket 连接。

安全提示：配对 macOS 节点允许在该机器上执行 system.run。仅配对你信任的设备，并查阅 安全。

文档：节点, 网关协议, macOS 远程模式, 安全。

Tailscale 已连接但我没有收到回复，现在该怎么办？​

检查基础项：

  • 网关是否正在运行：clawdbot gateway status
  • 网关健康状况：clawdbot status
  • 频道健康状况：clawdbot channels status

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

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

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

两个 Clawdbot 可以互相交流吗（本地和 VPS）？​

可以。虽然没有内置的“机器人对机器人”桥接，但你可以通过几种可靠的方式来实现：

最简单的方法： 使用两个机器人都能访问的普通聊天频道（Telegram/Slack/WhatsApp）。让机器人 A 向机器人 B 发送消息，然后让机器人 B 正常回复。

CLI 桥接（通用）： 运行一个脚本，调用另一个网关的 clawdbot agent --message ... --deliver，目标是另一个机器人监听的聊天频道。如果一个机器人在 Railway/VPS 上，请通过 SSH/Tailscale 将你的 CLI 指向该远程网关（参见 远程访问）。

示例模式（从可以连接到目标网关的机器运行）：

clawdbot agent --message "来自本地机器人的问候" --deliver --channel telegram --reply-to <chat-id>

提示：添加一个防护栏，以防止两个机器人陷入死循环（仅限提及、频道允许列表或“不回复机器人消息”规则）。

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

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

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

仅当你需要硬件隔离（安全边界）或非常高的资源需求时，才使用单独的 VPS。 different configs that you do not want to share. Otherwise, keep one Gateway and use multiple agents or sub-agents.

在我的个人笔记本电脑上使用节点，而不是从 VPS 使用 SSH，有什么好处吗？​

是的——节点是从远程网关连接到你笔记本电脑的一流方式，它们开启的功能远不止 shell 访问。网关运行在 macOS/Linux（Windows 通过 WSL2）上，非常轻量（小型 VPS 或树莓派级别的设备即可；4 GB 内存足够了），因此常见的设置是：一个始终在线的主机，加上你的笔记本电脑作为一个节点。

  • 不需要入站 SSH。 节点连接到网关的 WebSocket 并使用设备配对。
  • 更安全的执行控制。 system.run 受到该笔记本电脑上节点允许列表/批准的限制。
  • 更多的设备工具。 除了 system.run，节点还公开了 canvas、camera 和 screen。
  • 本地浏览器自动化。 将网关保留在 VPS 上，但在本地运行 Chrome，并通过 Chrome 扩展程序 + clawdbot browser serve 进行中继控制。

SSH 对于临时 shell 访问是可以的，但节点对于持续的代理工作流和设备自动化来说更简单。

文档：节点, 节点 CLI, Chrome 扩展程序。

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

如果你只需要在第二台笔记本电脑上使用 本地工具（屏幕/摄像头/执行），请将其添加为 节点。这样可以保持单个网关，并避免重复配置。本地节点工具目前仅限 macOS，但我们计划将其扩展到其他操作系统。

仅当你需要 硬隔离 或两个完全独立的机器人时，才安装第二个网关。

文档：节点, 节点 CLI, 多个网关。

节点运行网关服务吗？​

不。除非你特意运行隔离的配置文件（参见 多个网关），否则每个主机只能运行 一个网关。节点是连接到网关的外围设备（iOS/Android 节点，或菜单栏应用中的 macOS “节点模式”）。对于无头节点主机和 CLI 控制，参见 节点主机 CLI。

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

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

是的。config.apply 会验证并写入完整配置，并作为操作的一部分重启网关。

config.apply 抹掉了我的配置！我该如何恢复并避免这种情况？​

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

恢复：

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

避免：

  • 对于微小更改，使用 clawdbot config set。
  • 对于交互式编辑，使用 clawdbot configure。

文档：配置, 配置工具, 医生。

第一次安装时，什么是合理的最小配置？​

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

这会设置你的工作区并限制谁可以触发机器人。

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

最小步骤：

  1. 在 VPS 上安装并登录 
    curl -fsSL https://tailscale.com/install.sh | sh
    sudo tailscale up
  2. 在你的 Mac 上安装并登录
    • 使用 Tailscale 应用并登录到同一个 tailnet。
  3. 启用 MagicDNS（推荐）
    • 在 Tailscale 管理控制台中启用 MagicDNS，以便 VPS 拥有稳定的名称。
  4. 使用 tailnet 主机名
    • SSH: ssh user@your-vps.tailnet-xxxx.ts.net
    • 网关 WS: ws://your-vps.tailnet-xxxx.ts.net:18789

如果你想要不通过 SSH 使用控制 UI，请在 VPS 上使用 Tailscale Serve：

clawdbot gateway --tailscale serve

这会保持网关绑定到回环地址，并通过 Tailscale 公开 HTTPS。参见 Tailscale。

如何将 Mac 节点连接到远程网关的 Tailscale Serve？​

Serve 会公开 网关控制 UI + WS。节点通过同一个网关 WS 端点连接。

推荐设置：

  1. 确保 VPS 和 Mac 在同一个 tailnet 上。
  2. 在远程模式下使用 macOS 应用（SSH 目标可以是 tailnet 主机名）。 该应用将隧道化网关端口并作为节点连接。
  3. 在网关上批准该节点： 
    clawdbot nodes pending
    clawdbot nodes approve <requestId>

文档：网关协议, 发现, macOS 远程模式。

环境变量与 .env 加载​

Clawdbot 如何加载环境变量？​

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

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

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

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

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

参见 /environment 获取完整的优先级和来源。

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

两个常见的修复方法：

  1. 将缺失的密钥放入 ~/.clawdbot/.env，这样即使服务没有继承你的 shell 环境，它们也能被获取。
  2. 启用 shell 导入（为了方便的选择性加入）：
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

这会运行你的登录 shell 并仅导入缺失的预期密钥（从不覆盖）。环境变量对应项： CLAWDBOT_LOAD_SHELL_ENV=1，CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000。

我设置了 COPILOT_GITHUB_TOKEN，但模型状态显示 “Shell env off”。为什么？​

clawdbot models status 报告的是 shell 环境导入 是否已启用。“Shell env: off”并不意味着你的环境变量缺失——它只是意味着 Clawdbot 不会自动加载你的登录 shell。

如果网关作为服务运行（launchd/systemd），它将不会继承你的 shell 环境。通过以下任一方式修复：

  1. 将令牌放入 ~/.clawdbot/.env： 
    COPILOT_GITHUB_TOKEN=...
  2. 或者启用 shell 导入（env.shellEnv.enabled: true）。
  3. 或者将其添加到你的配置 env 块中（仅在缺失时应用）。

然后重启网关并重新检查：

clawdbot models status

Copilot 令牌从 COPILOT_GITHUB_TOKEN 读取（也可以是 GH_TOKEN / GITHUB_TOKEN）。 参见 /concepts/model-providers 和 /environment。

会话与多聊天​

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

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

如果我从不发送新消息，会话会自动重置吗？​

是的。会话在 session.idleMinutes（默认 60 分钟）后过期。下一条 消息将为该聊天密钥启动一个新的会话 ID。这不会删除对话记录——它只是开始一个新会话。

{
  session: {
    idleMinutes: 240
  }
}

有没有办法组建一个 Clawdbot 团队，一个 CEO 和多个智能体？​

是的，通过 多智能体路由 和 子智能体。你可以创建一个协调员智能体和几个拥有各自工作区和模型的工人智能体。

话虽如此，这最好被看作是一个 有趣的实验。它非常消耗 token，而且通常不如在一个 bot 上使用不同的会话高效。我们设想的典型模式是你与一个 bot 交谈，针对并行工作使用不同的会话。该 bot 在需要时也可以派生子智能体。

文档：多智能体路由, 子智能体, 智能体 CLI。

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

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

以下方法会有所帮助：

  • 要求机器人总结当前状态并将其写入文件。
  • 在执行长任务前使用 /compact，在切换话题时使用 /new。
  • 将重要上下文保留在工作区中，并要求机器人重新读取。
  • 对于长任务或并行工作使用子智能体，这样主聊天可以保持较小。
  • 如果经常发生这种情况，请选择一个具有更大上下文窗口的模型。

如何完全重置 Clawdbot 但保持安装状态？​

使用 reset 命令：

clawdbot reset

非交互式完全重置：

clawdbot reset --scope full --yes --non-interactive

然后重新运行入职向导：

clawdbot onboard --install-daemon

注意：

  • 如果入职向导检测到现有配置，它也会提供 重置 选项。参见 向导。
  • 如果你使用了配置文件（--profile / CLAWDBOT_PROFILE），请重置每个状态目录（默认值为 ~/.clawdbot-<profile>）。
  • 开发重置：clawdbot gateway --dev --reset（仅限开发；抹掉开发配置 + 凭据 + 会话 + 工作区）。

我收到了 “context too large” 错误，该如何重置或压缩？​

使用以下任一方式：

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

    /compact

    或 /compact <instructions> 来引导总结。

  • 重置 (Reset)（为同一个聊天密钥开启新会话 ID）：

    /new
    /reset

如果这种情况持续发生：

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

文档：压缩, 会话裁剪, 会话管理。

为什么我会看到 “LLM request rejected message... content... tool_use... input: Field required”？​

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

修复：通过 /new（独立消息）启动一个新会话。

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

心跳默认每 30 分钟 运行一次。你可以调整或禁用它们：

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

如果 HEARTBEAT.md 存在但实际上是空的（只有空行和像 # Heading 这样的 markdown 标题），Clawdbot 会跳过心跳运行以节省 API 调用。如果该文件不存在，心跳仍会运行，由模型决定做什么。

每个代理的覆盖设置使用 agents.list[].heartbeat。文档：心跳。

我需要将机器人账号添加到 WhatsApp 群组吗？​

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

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

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

如何获取 WhatsApp 群组的 JID？​

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

clawdbot logs --follow --json

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

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

clawdbot directory groups list --channel whatsapp

文档：WhatsApp, 目录, 日志。

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

两个常见原因：

  • 提及门控已开启（默认）。你必须 @机器人（或匹配 mentionPatterns）。
  • 你配置了 channels.whatsapp.groups 但没有包含 "*"，且该群组不在白名单中。

参见 群组 和 群组消息。

群组/线程是否与私聊共享上下文？​

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

我可以创建多少个工作空间和代理？​

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

  • 磁盘增长： 会话 + 转录记录存储在 ~/.clawdbot/agents/<agentId>/sessions/ 下。
  • Token 成本： 更多代理意味着更多并发的模型使用。
  • 运维开销： 每个代理的认证配置文件、工作空间和频道路由。

提示：

  • 每个代理保持一个活跃的工作空间 (agents.defaults.workspace)。
  • 如果磁盘空间不足，清理旧会话（删除 JSONL 或存储条目）。
  • 使用 clawdbot doctor 查找杂乱的工作空间和配置文件不匹配。

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

可以。使用多代理路由 (Multi‑Agent Routing) 来运行多个独立的代理，并按频道/账号/对端路由入站消息。Slack 支持作为频道，并可以绑定到特定代理。

浏览器访问功能强大，但并非“能做人类能做的任何事” —— 反机器人机制、验证码 (CAPTCHA) 和多因素认证 (MFA) 仍可能阻止自动化。为了获得最可靠的浏览器控制，请在运行浏览器的机器上使用 Chrome 扩展转发器（并将网关放在任何地方）。

最佳实践设置：

  • 始终在线的网关主机（VPS/Mac mini）。
  • 每个角色一个代理（绑定）。
  • 绑定到这些代理的 Slack 频道。
  • 需要时通过扩展转发器（或节点）使用本地浏览器。

文档：多代理路由, Slack, 浏览器, Chrome 扩展, 节点。

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

什么是默认模型？​

Clawdbot 的默认模型是你设置的：

agents.defaults.model.primary

模型以 provider/model 格式引用（例如：anthropic/claude-opus-4-5）。如果你省略了提供商，Clawdbot 目前会假设为 anthropic 作为临时的弃用回退 —— 但你仍然应该显式设置 provider/model。

你推荐什么模型？​

推荐默认： anthropic/claude-opus-4-5。
不错的替代方案： anthropic/claude-sonnet-4-5。
可靠（但性格较少）： openai/gpt-5.2 —— 几乎和 Opus 一样好，只是性格没那么鲜明。
预算之选： zai/glm-4.7。

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

经验法则：对高风险工作使用你能负担得起的最强模型，对常规聊天或总结使用较便宜的模型。你可以按代理路由模型，并使用子代理并行处理长任务（每个子代理都会消耗 token）。参见 模型 和 子代理。

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

更多上下文：模型。

我可以使用自托管模型吗 (llama.cpp, vLLM, Ollama)？​

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

安全说明：较小或重度量化的模型更容易受到提示词注入的影响。我们强烈建议为任何可以使用工具的机器人使用大模型。如果你仍想使用小模型，请启用沙箱和严格的工具白名单。

文档：Ollama, 本地模型, 模型提供商, 安全, 沙箱。

如何在不清除配置的情况下切换模型？​

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

安全选项：

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

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

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

Clawd、Flawd 和 Krill 使用什么模型？​

  • Clawd + Flawd: Anthropic Opus (anthropic/claude-opus-4-5) —— 参见 Anthropic。
  • Krill: MiniMax M2.1 (minimax/MiniMax-M2.1) —— 参见 MiniMax。

如何在不重启的情况下即时切换模型？​

使用 /model 命令作为独立消息：

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

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

/model（和 /model list）会显示一个紧凑的数字选择器。通过数字选择：

/model 3

你还可以为提供商强制使用特定的认证配置文件（按会话）：

/model opus@anthropic:claude-cli
/model opus@anthropic:default

提示：/model status 显示哪个代理处于活跃状态，正在使用哪个 auth-profiles.json 文件，以及下一个将尝试哪个认证配置文件。它还会在可用时显示配置的提供商端点 (baseUrl) 和 API 模式 (api)。

如何取消我使用 @profile 设置的配置文件锁定？​

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

/model anthropic/claude-opus-4-5

如果你想返回默认值，请从 /model 中选择它（或发送 /model <default provider/model>）。使用 /model status 确认哪个认证配置文件处于活跃状态。

我可以对日常任务使用 GPT 5.2，对编程使用 Codex 5.2 吗？​

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

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

参见 模型 和 斜杠命令。

为什么我看到 “Model is not allowed” 然后没有回复？​

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

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

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

为什么我看到 “Unknown model minimaxMiniMaxM21”？​

这意味着提供商未配置（未找到 MiniMax 提供商配置或认证配置文件），因此无法解析该模型。针对此检测的修复包含在 2026.1.12 版本中（在编写本文时尚未发布）。

修复检查列表：

  1. 升级到 2026.1.12（或从 main 源码运行），然后重启网关。
  2. 确保配置了 MiniMax（通过向导或 JSON），或者在环境变量/认证配置文件中存在 MiniMax API 密钥，以便注入提供商。
  3. 使用准确的模型 ID（区分大小写）：minimax/MiniMax-M2.1 或 minimax/MiniMax-M2.1-lightning。
  4. 运行： 
    clawdbot models list
    并从列表中选择（或在聊天中使用 /model list）。

参见 MiniMax 和 模型。

我可以使用 MiniMax 作为默认值，将 OpenAI 用于复杂任务吗？​

可以。将 MiniMax 设置为默认模型，并根据需要在每个会话中切换模型。回退 (Fallbacks) 是为了处理错误，而不是“困难的任务”，因此请使用 /model 或单独的代理。

选项 A：按会话切换

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

然后：

/model gpt

选项 B：独立的代理

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

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

opus、sonnet、gpt 是内置快捷方式吗？​

是的。Clawdbot 提供了一些默认简写（仅当模型存在于 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

如果你设置了同名的自定义别名，你的值将优先。

如何定义/覆盖模型快捷方式（别名）？​

别名来自 agents.defaults.models.<modelId>.alias。例如：

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-5" },
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" }
      }
    }
  }
}

然后 /model sonnet（或受支持时的 /<alias>）将解析为该模型 ID。

如何添加来自 OpenRouter 或 ZAI 等其他提供商的模型？​

OpenRouter（按 token 付费；模型众多）：

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
      models: { "openrouter/anthropic/claude-sonnet-4-5": {} }
    }
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." }
}

Z.AI (GLM 模型)：

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

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

添加新代理后提示 “No API key found for provider”​

这通常意味着新代理的认证存储是空的。认证是按代理进行的，存储在：

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

修复选项：

  • 运行 clawdbot agents add <id> 并在向导中配置认证。
  • 或者将主代理的 agentDir 中的 auth-profiles.json 复制到新代理的 agentDir 中。

不要在代理之间重用 agentDir；这会导致认证/会话冲突。

模型故障转移与 “All models failed”​

故障转移是如何工作的？​

故障转移分为两个阶段：

  1. 同一提供商内的 认证配置文件轮换 (Auth profile rotation)。
  2. 模型回退 (Model fallback) 到 agents.defaults.model.fallbacks 中的下一个模型。

冷却时间 (Cooldowns) 适用于失败的配置文件（指数退避），因此即使提供商被限流或暂时失效，Clawdbot 仍能保持响应。

这个错误是什么意思？​

No credentials found for profile "anthropic:default"

这意味着系统尝试使用认证配置文件 ID anthropic:default，但在预期的认证存储中找不到该 ID 的凭据。

“No credentials found for profile anthropic:default” 修复检查列表​

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

“No credentials found for profile anthropic:claude-cli” 修复检查列表​

这意味着运行被锁定在 Claude Code CLI 配置文件上，但网关在其认证存储中找不到该配置文件。

  • 在网关主机上同步 Claude Code CLI 令牌
    • 运行 clawdbot models status（它会加载并同步 Claude Code CLI 凭据）。
    • 如果仍显示缺失：运行 claude setup-token（或 clawdbot models auth setup-token --provider anthropic）并重试。
  • 如果令牌是在另一台机器上创建的
    • 使用 clawdbot models auth paste-token --provider anthropic 将其粘贴到网关主机中。
  • 检查配置文件模式
    • auth.profiles["anthropic:claude-cli"].mode 必须为 "oauth"（令牌模式会拒绝 OAuth 凭据）。
  • 如果你想改用 API 密钥
    • 将 ANTHROPIC_API_KEY 放入网关主机上的 ~/.clawdbot/.env。
    • 清除强制使用 anthropic:claude-cli 的锁定顺序： 
      clawdbot models auth order clear --provider anthropic
  • 确认你正在网关主机上运行命令
    • 在远程模式下，认证配置文件存放在网关机器上，而不是你的笔记本电脑上。

为什么它还尝试了 Google Gemini 并且失败了？​

如果你的模型配置中包含 Google Gemini 作为回退模型（或者你切换到了 Gemini 简写），Clawdbot 会在模型回退期间尝试它。如果你还没有配置 Google 凭据，你将看到 No API key found for provider "google"。

修复：要么提供 Google 认证，要么从 agents.defaults.model.fallbacks / 别名中移除/避开 Google 模型，以免回退路由到那里。

“LLM request rejected message thinking signature required google antigravity”​

原因：会话历史包含没有签名的思考块（通常来自中止/部分的流）。Google Antigravity 要求思考块必须有签名。

修复：Clawdbot 现在会为 Google Antigravity Claude 剥离未签名的思考块。如果该错误仍然出现，请启动一个新会话或为该代理设置 /thinking off。

认证配置文件：它们是什么以及如何管理​

相关：/concepts/oauth (OAuth 流程、令牌存储、多账号模式、CLI 同步)

什么是认证配置文件 (Auth profile)？​

认证配置文件是与提供商绑定的命名凭据记录（OAuth 或 API 密钥）。配置文件存放在：

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

典型的配置文件 ID 有哪些？​

Clawdbot 使用带有提供商前缀的 ID，例如：

  • anthropic:default（在不存在 Email 身份时常见）
  • anthropic:<email> 用于 OAuth 身份
  • 你选择的自定义 ID（例如 anthropic:work）

我可以控制首先尝试哪个认证配置文件吗？​

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

如果某个配置文件处于短时间的冷却期 (cooldown)（由于限流/超时/认证失败）或长时间的禁用状态（欠费/余额不足），Clawdbot 可能会暂时跳过它。要检查此状态，请运行 clawdbot models status --json 并查看 auth.unusableProfiles。调整设置：auth.cooldowns.billingBackoffHours*。

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

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

# 锁定轮换到单个配置文件（仅尝试这一个）
clawdbot models auth order set --provider anthropic anthropic:claude-cli

# 或者设置显式顺序（在提供商内部回退）
clawdbot models auth order set --provider anthropic anthropic:claude-cli anthropic:default

# 清除覆盖（回退到配置中的 auth.order / 轮询）
clawdbot models auth order clear --provider anthropic

针对特定代理：

clawdbot models auth order set --provider anthropic --agent main anthropic:claude-cli

OAuth vs API 密钥：有什么区别？​

Clawdbot 两者都支持：

  • OAuth 通常利用订阅访问权限（如果适用）。
  • API 密钥 使用按 token 计费。

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

网关：端口、“已经在运行”和远程模式​

网关使用哪个端口？​

gateway.port 控制用于 WebSocket + HTTP (Control UI、钩子等) 的单个多路复用端口。

优先级：

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

为什么 “clawdbot gateway status” 显示 Runtime 正在运行，但 RPC 探测失败？​

因为 “正在运行” 是管理器 (Supervisor) 的视图 (launchd/systemd/schtasks)。RPC 探测是 CLI 实际连接到网关 WebSocket 并调用 status。

请使用 clawdbot gateway status 并信任以下行：

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

为什么 “clawdbot gateway status” 显示 CLI 配置和服务配置不同？​

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

修复：

clawdbot gateway install --force

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

“another gateway instance is already listening” 是什么意思？​

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

修复：停止另一个实例，释放端口，或使用 clawdbot gateway --port <port> 运行。

如何以远程模式运行 Clawdbot（客户端连接到其他地方的网关）？​

设置 gateway.mode: "remote" 并指向远程 WebSocket URL，可选带上令牌/密码：

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

注意：

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

控制 UI (Control UI) 显示未授权或不断重新连接，现在该怎么办？​

你的网关在启用认证的情况下运行 (gateway.auth.*)，但 UI 没有发送匹配的令牌/密码。

事实（来自代码）：

  • 控制 UI 将令牌存储在浏览器 localStorage 键 clawdbot.control.settings.v1 中。
  • UI 可以导入一次 ?token=...（和/或 ?password=...），然后将其从 URL 中剥离。

修复：

  • 最快：clawdbot dashboard（打印并复制带令牌的链接，尝试打开；如果是无头模式则显示 SSH 提示）。
  • 如果你还没有令牌：clawdbot doctor --generate-gateway-token。
  • 如果是远程连接，先建立隧道：ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/?token=...。
  • 在网关主机上设置 gateway.auth.token（或 CLAWDBOT_GATEWAY_TOKEN）。
  • 在控制 UI 设置中，粘贴相同的令牌（或使用一次性的 ?token=... 链接刷新）。
  • 仍然卡住？运行 clawdbot status --all 并遵循 故障排除。有关认证详情，请参阅 仪表盘。

我设置了 “gateway.bind: tailnet” 但它无法绑定，没有监听任何内容​

tailnet 绑定会从你的网络接口中挑选一个 Tailscale IP (100.64.0.0/10)。如果机器不在 Tailscale 上（或者接口已关闭），则没有可绑定的地址。

修复：

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

注意：tailnet 是显式的。auto 优先选择回环地址；当你想要仅限 tailnet 的绑定时，请使用 gateway.bind: "tailnet"。

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

通常不需要 —— 一个网关可以运行多个消息频道和代理。仅当你需要冗余（例如：救援机器人）或强隔离时才使用多个网关。

可以，但你必须隔离：

  • CLAWDBOT_CONFIG_PATH（每个实例的配置）
  • CLAWDBOT_STATE_DIR（每个实例的状态）
  • agents.defaults.workspace（工作空间隔离）
  • gateway.port（唯一的端口）

快速设置（推荐）：

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

配置文件还会为服务名称添加后缀 (com.clawdbot.<profile>, clawdbot-gateway-<profile>.service, Clawdbot Gateway (<profile>))。 完整指南：多个网关。

无效握手代码 1008 (invalid handshake code 1008) 是什么意思？​

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

常见原因：

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

快速修复：

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

如果你正在使用 CLI 或 TUI，URL 应该类似于：

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

协议详情：网关协议。

日志与调试​

日志在哪里？​

文件日志（结构化）：

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

你可以通过 logging.file 设置一个稳定的路径。文件日志级别由 logging.level 控制。控制台详细程度由 --verbose 和 logging.consoleLevel 控制。

最快的日志监控方式：

clawdbot logs --follow

服务/管理器日志（当网关通过 launchd/systemd 运行时）：

  • macOS：$CLAWDBOT_STATE_DIR/logs/gateway.log 和 gateway.err.log（默认：~/.clawdbot/logs/...；使用配置文件的则为 ~/.clawdbot-<profile>/logs/...）
  • Linux：journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager
  • Windows：schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST

更多详情请参阅 故障排除。

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

使用网关辅助命令：

clawdbot gateway status
clawdbot gateway restart

如果你是手动运行网关，clawdbot gateway --force 可以强行占用端口。参见 网关。

我在 Windows 上关闭了终端，如何重启 Clawdbot？​

Windows 有两种安装模式：

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

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

wsl
clawdbot gateway status
clawdbot gateway restart

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

clawdbot gateway run

2) 原生 Windows（不推荐）： 网关直接运行在 Windows 中。

打开 PowerShell 并运行：

clawdbot gateway status
clawdbot gateway restart

如果你是手动运行（没有服务），请使用：

clawdbot gateway run

文档：Windows (WSL2), 网关服务运行手册。

网关已启动但回复从未送达，我应该检查什么？​

首先进行快速健康检查：

clawdbot status
clawdbot models status
clawdbot channels status
clawdbot logs --follow

常见原因：

  • 模型认证未在网关主机上加载（检查 models status）。
  • 频道配对/白名单阻止了回复（检查频道配置 + 日志）。
  • WebChat/控制面板 (Dashboard) 已打开但没有正确的令牌。

如果你是远程连接，请确认隧道/Tailscale 连接已建立，且网关 WebSocket 可访问。

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

无缘无故与网关断开连接，现在该怎么办？​

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

  1. 网关是否在运行？ clawdbot gateway status
  2. 网关是否健康？ clawdbot status
  3. UI 是否有正确的令牌？ clawdbot dashboard
  4. 如果是远程连接，隧道/Tailscale 链路是否正常？

然后监控日志：

clawdbot logs --follow

文档：仪表盘, 远程访问, 故障排除。

Telegram setMyCommands 失败并提示网络错误，我应该检查什么？​

从日志和频道状态开始检查：

clawdbot channels status
clawdbot channels logs --channel telegram

如果你在 VPS 上或处于代理之后，请确认允许出站 HTTPS 且 DNS 正常工作。 如果网关是远程的，请确保你查看的是网关主机上的日志。

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

TUI 没有输出，我应该检查什么？​

首先确认网关可访问且代理可以运行：

clawdbot status
clawdbot models status
clawdbot logs --follow

在 TUI 中，使用 /status 查看当前状态。如果你期望在聊天频道中收到回复，请确保已启用送达 (/deliver on)。

文档：TUI, 斜杠命令。

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

如果你安装了服务：

clawdbot gateway stop
clawdbot gateway start

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

如果你是在前台运行，使用 Ctrl‑C 停止，然后：

clawdbot gateway run

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

通俗易懂地解释下 “clawdbot gateway restart” 和 “clawdbot gateway” 的区别​

  • clawdbot gateway restart：重启后台服务 (launchd/systemd)。
  • clawdbot gateway：在当前终端会话的前台运行网关。

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

当某些东西失败时，获取更多详情的最快方法是什么？​

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

媒体与附件​

我的技能生成了图片/PDF，但没有发送出去​

从代理发出的传出附件必须包含 MEDIA:<path-or-url> 行（单独一行）。请参阅 Clawdbot 助手设置 和 代理发送。

CLI 发送示例：

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

同时检查：

  • 目标频道支持传出媒体且未被允许列表拦截。
  • 文件在提供商的大小限制内（图片会自动调整大小至最大 2048px）。

详见 图片。

安全与访问控制​

将 Clawdbot 暴露给传入的私信（DM）是否安全？​

请将传入的私信视为不可信输入。默认设置旨在降低风险：

  • 支持私信频道的默认行为是 配对 (pairing)：
    • 未知发送者会收到配对码；机器人不会处理他们的消息。
    • 使用以下命令批准：clawdbot pairing approve <channel> <code>
    • 待处理请求每个频道上限为 3 个；如果没收到代码，请检查 clawdbot pairing list <channel>。
  • 公开开放私信需要显式启用 (dmPolicy: "open" 且允许列表为 "*"）。

运行 clawdbot doctor 可以发现有风险的私信策略。

提示词注入（Prompt injection）只对公开机器人有风险吗？​

不。提示词注入关乎 不可信内容，而不只是谁能给机器人发私信。 如果你的助手读取外部内容（网页搜索/获取、浏览器页面、电子邮件、文档、附件、粘贴的日志），这些内容可能包含尝试劫持模型的指令。即使 你是唯一的发送者，这也可能发生。

最大的风险在于启用工具时：模型可能会被诱导窃取上下文或代表你调用工具。可以通过以下方式缩小攻击面：

  • 使用只读或禁用工具的 “阅读器” 代理来总结不可信内容。
  • 对启用了工具的代理关闭 web_search / web_fetch / browser。
  • 使用沙箱和严格的工具允许列表。

详情请参阅：安全。

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

对于大多数设置来说，是的。将机器人与独立的账号和电话号码隔离，可以在出现问题时缩小受影响范围。这也使得在不影响你个人账号的情况下轮换凭证或撤销访问权限变得更加容易。

从小处开始。仅授予其真正需要的工具和账号访问权限，以后如有需要再进行扩展。

文档：安全，配对。

我能让它自主管理我的短信吗？这安全吗？​

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

  • 保持私信处于 配对模式 或严格的允许列表。
  • 如果你想让它代表你发送消息，请使用 独立的号码或账号。
  • 让它起草，然后在发送前由你 批准。

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

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

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

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

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

检查待处理请求：

clawdbot pairing list telegram

如果你想立即访问，请将你的发送者 ID 加入允许列表，或为该账号设置 dmPolicy: "open"。

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

不。默认的 WhatsApp 私信策略是 配对 (pairing)。未知发送者只会收到配对码，他们的消息 不会被处理。Clawdbot 只回复它收到的聊天或由你触发的显式发送。

批准配对：

clawdbot pairing approve whatsapp <code>

列出待处理请求：

clawdbot pairing list whatsapp

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

聊天命令、终止任务和 “它停不下来”​

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

大多数内部或工具消息仅在为该会话启用了 verbose (详细) 或 reasoning (推理) 时才会出现。

在出现这些消息的聊天中修复：

/verbose off
/reasoning off

如果仍然有很多噪音，请检查 Control UI 中的会话设置，并将 verbose 设置为 inherit (继承)。还要确认你没有在配置中将机器人配置文件的 verboseDefault 设置为 on。

文档：思考与详细输出，安全。

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

发送以下任何一个 作为独立消息（不要带斜杠）：

stop
abort
esc
wait
exit
interrupt

这些是终止触发词（不是斜杠命令）。

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

process action:kill sessionId:XXX

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

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

如何从 Telegram 发送 Discord 消息？（Crosscontext messaging denied）​

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

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

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

编辑配置后重启网关。如果你只想为单个代理设置此项，请在 agents.list[].tools.message 下进行设置。

为什么感觉机器人忽略了连珠炮式的消息？​

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

  • steer - 新消息重定向当前任务
  • followup - 逐个处理消息
  • collect - 汇总消息并回复一次（默认）
  • steer-backlog - 立即重定向，然后处理积压
  • interrupt - 中断当前运行并重新开始

你可以为 followup 模式添加选项，例如 debounce:2s cap:25 drop:summarize。

根据截图/聊天记录回答具体问题​

问：“Anthropic 的默认模型是什么？使用 API 密钥时。”

答： 在 Clawdbot 中，凭据和模型选择是分开的。设置 ANTHROPIC_API_KEY（或在身份验证配置文件中存储 Anthropic API 密钥）可以启用身份验证，但实际的默认模型取决于你在 agents.defaults.model.primary 中配置的内容（例如 anthropic/claude-sonnet-4-5 或 anthropic/claude-opus-4-5）。如果你看到 No credentials found for profile "anthropic:default"，这意味着网关在正在运行的代理所预期的 auth-profiles.json 中找不到 Anthropic 凭据。

仍然卡住了？在 Discord 中提问或发起 GitHub 讨论。