常见问题

向运行中的网关请求完整快照（仅限WS）。参见 [健康状态](/gateway/health)。

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

### 我卡住了，最快的方法是什么？

使用一个可以**查看你的机器**的本地AI代理。这比在Discord上提问要有效得多，因为大多数“我卡住了”的情况都是**本地配置或环境问题**，远程帮助者无法检查。

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

这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置（PATH、服务、权限、认证文件）。通过可被修改的（git）安装方式，向它们提供**完整的源代码检查**。
bash
curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git

他们能做什么：
- `clawdbot status`：快速查看网关/代理的健康状态 + 基本配置。
- `clawdbot models status`：检查提供者认证 + 模型可用性。
- `clawdbot doctor`：验证并修复常见的配置/状态问题。

其他有用的 CLI 检查命令：`clawdbot status --all`，`clawdbot logs --follow`，  
`clawdbot gateway status`，`clawdbot health --verbose`。

快速调试循环：[如果出现问题的前60秒](#first-60-seconds-if-somethings-broken)。  
安装文档：[安装](/install)，[安装程序标志](/install/installer)，[更新](/install/updating)。

### 推荐的安装和设置 Clawdbot 的方式

该仓库推荐从源码运行并使用引导向导进行设置：
bash
curl -fsSL https://clawd.bot/install.sh | bash
clawdbot onboard --install-daemon

如果尚未全局安装，可以通过 `pnpm clawdbot onboard` 运行。

### 上线后如何打开仪表板

向导在完成上线后会直接在你的浏览器中打开一个带令牌的仪表板 URL，并在摘要中打印完整的链接（含令牌）。请保持该标签页打开；如果它没有自动打开，请将打印出的 URL 粘贴到同一台机器上。令牌仅在你的主机本地有效，不会从浏览器获取。

### 如何在本地主机和远程主机上认证仪表板令牌

**本地主机（同一台机器）：**
- 打开 `http://127.0.0.1:18789/`。
- 如果提示需要认证，运行 `clawdbot dashboard` 并使用带令牌的链接（`?token=...`）。
- 令牌与 `gateway.auth.token`（或 `CLAWDBOT_GATEWAY_TOKEN`）相同，并在首次加载后由 UI 存储。

**不在本地主机上：**
- **Tailscale Serve**（推荐）：保留绑定 loopback，运行 `clawdbot gateway --tailscale serve`，打开 `https://<magicdns>/`。如果 `gateway.auth.allowTailscale` 设置为 `true`，身份头即可满足认证（无需令牌）。
- **Tailnet 绑定**：运行 `clawdbot gateway --bind tailnet --token "<token>"`，打开 `http://<tailscale-ip>:18789/`，然后在仪表板设置中粘贴令牌。
- **SSH 隧道**：运行 `ssh -N -L 18789:127.0.0.1:18789 user@host`，然后从 `clawdbot dashboard` 打开 `http://127.0.0.1:18789/?token=...`。

有关绑定模式和认证的详细信息，请参阅 [仪表板](/web/dashboard) 和 [Web 表面](/web)。

### 我需要什么运行时环境

需要 **Node >= 22**。推荐使用 `pnpm`。不推荐使用 **Bun** 作为网关的运行时。

### 它能在树莓派上运行吗

是的。网关轻量级——文档中列出的 **512MB-1GB 内存**、**1 核 CPU** 和约 **500MB 磁盘空间** 对于个人使用来说已经足够，并且指出 **树莓派 4 可以运行它**。

如果你想为日志、媒体或其他服务留出更多空间，推荐使用 **2GB 内存**，但这不是硬性最低要求。

提示：一个小的树莓派/VPS 可以托管网关，你可以在笔记本电脑/手机上运行 **节点**，用于本地屏幕/摄像头/画布或命令执行。参见 [节点](/nodes)。

### 树莓派安装有什么提示吗

简而言之：可以工作，但可能会遇到一些不完美的地方。

- 使用 **64 位** 操作系统，并确保 Node >= 22。
- 推荐使用 **可修改的（git）安装方式**，以便查看日志和快速更新。
- 初次启动时不要加载通道/技能，然后逐个添加。
- 如果遇到奇怪的二进制问题，通常是 **ARM 兼容性** 问题。

文档：[Linux](/platforms/linux)、[安装](/install)。

### 我卡在“唤醒我的朋友”上线界面，无法继续怎么办

该屏幕取决于网关是否可访问并已认证。TUI 会在首次启动时自动发送 “Wake up, my friend!”。如果你看到该提示但 **没有回应**，且令牌值保持为 0，说明代理程序从未运行。

1) 重新启动网关：
bash
clawdbot gateway restart

3) 如果仍然卡住，请运行：
bash
clawdbot doctor

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

2) **可修改安装（从安装程序网站）：**
bash
curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git

文档：[更新](/cli/update)，[开发渠道](/install/development-channels)，[安装](/install)。

### 安装程序卡住，该如何获取更多反馈

以**详细输出**模式重新运行安装程序：
bash
curl -fsSL https://clawd.bot/install.sh | bash -s -- --verbose

对于可通过 Git 破解的安装：
bash
curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --verbose```
更多选项：[安装程序标志](/install/installer)。

### Windows 安装时提示 git 未找到或 clawdbot 未被识别

两个常见的 Windows 问题：

**1) npm 错误：spawn git / git 未找到**
- 安装 **Git for Windows**，并确保 `git` 在你的 PATH 环境变量中。
- 关闭并重新打开 PowerShell，然后重新运行安装程序。

**2) 安装后提示 clawdbot 未被识别**
- 你的 npm 全局 bin 文件夹未添加到 PATH 中。
- 检查路径：  ```powershell
  npm config get prefix

更多详情：[安装](/install) 和 [安装程序标志](/install/installer)。

### 如何在 Linux 上安装 Clawdbot

简短回答：按照 Linux 指南操作，然后运行引导向导。

- Linux 快速路径 + 服务安装：[Linux](/platforms/linux)。
- 完整教程：[开始使用](/start/getting-started)。
- 安装程序 + 更新：[安装与更新](/install/updating)。

### 如何在 VPS 上安装 Clawdbot

任何 Linux VPS 都可以使用。在服务器上安装，然后通过 SSH/Tailscale 访问网关（Gateway）。

指南：[exe.dev](/platforms/exe-dev)、[Hetzner](/platforms/hetzner)、[Fly.io](/platforms/fly)。  
远程访问：[网关远程访问](/gateway/remote)。

### 云 VPS 的安装指南在哪里

我们维护了一个 **托管中心**，包含常见的提供商。选择一个并按照指南操作：

- [VPS 托管](/vps)（在一个地方汇总所有提供商）
- [Railway](/railway)（一键式、基于浏览器的设置）
- [Fly.io](/platforms/fly)
- [Hetzner](/platforms/hetzner)
- [exe.dev](/platforms/exe-dev)

在云端的工作方式：**网关运行在服务器上**，你可以通过控制界面（或 Tailscale/SSH）从笔记本电脑/手机访问它。你的状态和工作区都保存在服务器上，因此请将主机视为真实数据源并进行备份。

你可以将 **节点**（Mac/iOS/Android/无头设备）与该云网关配对，以访问本地屏幕/摄像头/画布或在你的笔记本电脑上运行命令，同时保持网关在云端。

中心：[平台](/platforms)。远程访问：[网关远程访问](/gateway/remote)。  
节点：[节点](/nodes)、[节点 CLI](/cli/nodes)。```bash
clawdbot update
clawdbot update status
clawdbot update --channel stable|beta|dev
clawdbot update --tag <dist-tag|version>
clawdbot update --no-restart
```
如果您必须从代理进行自动化操作：
bash  
clawdbot update --yes --no-restart  
clawdbot gateway restart```
文档：[更新](/cli/update), [更新说明](/install/updating)。

### onboard 向导到底做了什么

`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](/providers/anthropic), [OpenAI](/providers/openai), [本地模型](/gateway/local-models), [模型](/concepts/models)。

### 我可以不用 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** 生成一个 **令牌字符串**（在网页控制台中不可用）。你可以在 **任何机器** 上运行它。如果网关主机上已存在 Claude Code CLI 的凭证，Clawdbot 可以复用它们；否则，选择 **Anthropic 令牌（粘贴 setup-token）** 并粘贴该字符串。该令牌将作为 **anthropic** 提供者的认证配置文件存储，并像 API 密钥或 OAuth 配置文件一样使用。更多细节：[OAuth](/concepts/oauth)。

Clawdbot 会将 `auth.profiles["anthropic:claude-cli"].mode` 保持为 `"oauth"`，因此该配置文件可以接受 OAuth 或 setup-token 凭证；旧的 `"token"` 模式配置会自动迁移。```bash
claude setup-token
```
复制它输出的 token，然后在向导中选择 **Anthropic token (粘贴 setup-token)**。如果你想在网关主机上运行，使用 `clawdbot models auth setup-token --provider anthropic`。如果你在其他地方运行了 `claude setup-token`，请通过 `clawdbot models auth paste-token --provider anthropic` 在网关主机上粘贴它。详见 [Anthropic](/providers/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](/providers/anthropic) 和 [OAuth](/concepts/oauth)。

注意：Claude 订阅访问由 Anthropic 的条款管理。对于生产环境或多人使用的工作负载，API 密钥通常是更安全的选择。

### 为什么我会看到来自 Anthropic 的 HTTP 429 速率限制错误？

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

提示：设置一个 **备用模型**，这样当某个提供方被速率限制时，Clawdbot 仍可以继续回复。
详见 [Models](/cli/models) 和 [OAuth](/concepts/oauth)。

### 是否支持 AWS Bedrock？

是的——通过 pi-ai 的 **Amazon Bedrock (Converse)** 提供商进行 **手动配置**。你必须在网关主机上提供 AWS 凭证/区域，并在你的模型配置中添加一个 Bedrock 提供商条目。详见 [Amazon Bedrock](/bedrock) 和 [Model providers](/providers/models)。如果你希望使用托管密钥流程，可以在 Bedrock 前面使用一个 OpenAI 兼容的代理仍然是一个有效选项。

### Codex 认证是如何工作的？

Clawdbot 通过 OAuth 或复用你的 Codex CLI 登录（`~/.codex/auth.json`）支持 **OpenAI Code (Codex)**。向导可以导入 CLI 登录或运行 OAuth 流程，并在适当的时候将默认模型设置为 `openai-codex/gpt-5.2`。详见 [Model providers](/concepts/model-providers) 和 [Wizard](/start/wizard)。

### 你们支持 OpenAI 订阅认证（Codex OAuth）吗？

是的。Clawdbot 完全支持 **OpenAI Code (Codex) 订阅 OAuth**，并且还可以在网关主机上复用现有的 Codex CLI 登录（`~/.codex/auth.json`）。入门向导可以为你导入 CLI 登录或运行 OAuth 流程。

详见 [OAuth](/concepts/oauth)、[Model providers](/concepts/model-providers) 和 [Wizard](/start/wizard)。

### 我如何设置 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 令牌到认证配置文件中。详情：[模型提供者](/concepts/model-providers)。

### 本地模型是否适合日常聊天

通常不行。Clawdbot 需要大上下文 + 强大的安全性；小型模型会截断并泄露信息。如果必须使用，请在本地运行你所能运行的 **最大** 的 MiniMax M2.1 版本（通过 LM Studio），并查看 [/gateway/local-models](/gateway/local-models)。更小或量化后的模型会增加提示注入的风险 - 详见 [安全](/gateway/security)。

### 如何确保托管模型的流量在特定区域

选择区域绑定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国主机选项；选择美国主机的版本可以确保数据留在该区域内。你仍然可以使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些模型一起列出，这样在尊重你所选区域提供者的同时，回退选项仍然可用。

### 我必须购买 Mac mini 来安装这个吗

不需要。Clawdbot 可以在 macOS 或 Linux 上运行（Windows 通过 WSL2）。Mac mini 是可选的 - 有些人购买它作为始终在线的主机，但小型 VPS、家庭服务器或 Raspberry Pi 类设备也可以。

你只需要 Mac **用于仅 macOS 工具**。对于 iMessage，你可以将网关运行在 Linux 上，并通过 SSH 在任意 Mac 上运行 `imsg`，只需将 `channels.imessage.cliPath` 指向一个运行 `imsg` 的 SSH 包装器。如果你想使用其他仅 macOS 的工具，请在 Mac 上运行网关或连接一个 macOS 节点。

文档：[iMessage](/channels/imessage)，[节点](/nodes)，[Mac 远程模式](/platforms/mac/remote)。

### 我需要 Mac mini 来支持 iMessage 吗

你需要 **一台 macOS 设备** 并登录到 Messages 应用。它 **不一定是 Mac mini** - 任何 Mac 都可以。Clawdbot 的 iMessage 集成运行在 macOS 上（BlueBubbles 或 `imsg`），而网关可以在其他设备上运行。

常见配置：
- 将网关运行在 Linux/VPS 上，并将 `channels.imessage.cliPath` 指向一个通过 SSH 运行 `imsg` 的包装器。
- 如果你想要最简单的单机设置，可以在 Mac 上运行所有内容。

文档：[iMessage](/channels/imessage)，[BlueBubbles](/channels/bluebubbles)，[Mac 远程模式](/platforms/mac/remote)。

### 如果我购买了一台 Mac mini 来运行 Clawdbot，我能否连接到我的 MacBook Pro

可以。**Mac mini 可以运行网关**，而你的 MacBook Pro 可以作为 **节点**（配套设备）连接。节点不会运行网关 - 它们提供额外的功能，如屏幕/摄像头/画布以及在该设备上的 `system.run`。

常见模式：
- 网关运行在 Mac mini 上（始终在线）。
- MacBook Pro 运行 macOS 应用或节点主机，并与网关配对。
- 使用 `clawdbot nodes status` / `clawdbot nodes list` 查看节点状态。

文档：[节点](/nodes)，[节点 CLI](/cli/nodes)。

### 我可以使用 Bun 吗

不推荐使用 Bun。我们发现它在 WhatsApp 和 Telegram 上存在运行时问题。建议使用 **Node** 来确保网关的稳定性。

如果你仍想尝试使用 Bun，请在非生产环境的网关上进行，不要包含 WhatsApp/Telegram。

### Telegram 中 allowFrom 的内容是什么

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

更安全的方式（不使用第三方机器人）：
- 向你的机器人发送私信，然后运行 `clawdbot logs --follow` 并查看 `from.id`。

官方 Bot API 方式：
- 向你的机器人发送私信，然后调用 `https://api.telegram.org/bot<bot_token>/getUpdates` 并查看 `message.from.id`。

第三方方式（隐私性较差）：
- 向 `@userinfobot` 或 `@getidsbot` 发送私信。

详见 [/channels/telegram](/channels/telegram#access-control-dms--groups)。

### 多个人能否使用同一个 WhatsApp 号码并搭配不同的 Clawdbots

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

### 我能否同时运行一个快速聊天代理和一个用于编程的 Opus 代理

可以。使用 **多代理路由**：为每个代理分配其自己的默认模型，然后将入站路由（提供者账号或特定发送者）绑定到每个代理。示例配置位于 [多代理路由](/concepts/multi-agent) 中。也可参考 [模型](/concepts/models) 和 [配置](/gateway/configuration)。

### Homebrew 是否支持 Linux

是的。Homebrew 支持 Linux（称为 Linuxbrew）。快速设置方法如下：
bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>

从 Git → npm：
bash
npm install -g clawdbot@latest
clawdbot doctor
clawdbot gateway restart

"文档：[定时任务](/automation/cron-jobs)，[Cron 与 Heartbeat](/automation/cron-vs-heartbeat)。

### 如何在 Linux 上安装技能

使用 **ClawdHub**（CLI）或直接将技能放入你的工作区。macOS 的技能界面在 Linux 上不可用。
在 https://clawdhub.com 浏览技能。

安装 ClawdHub CLI（选择一个包管理器）：
bash
npm i -g clawdhub
```"```
```md
pnpm add -g clawdhub```
### Clawdbot 是否可以在计划任务或后台持续运行任务

是的。使用网关调度器：

- **Cron 任务** 用于计划或重复性任务（在重启后仍然保留）。
- **心跳机制** 用于“主会话”的周期性检查。
- **隔离任务** 用于自主代理，用于发布摘要或向聊天发送内容。

文档：[Cron 任务](/automation/cron-jobs)，[Cron 与心跳机制的区别](/automation/cron-vs-heartbeat)，[心跳机制](/gateway/heartbeat)。

**能否仅在 macOS 上运行的技能在 Linux 上运行**

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

你有三种支持的方案：

**选项 A - 在 Mac 上运行网关（最简单）。**  
在拥有 macOS 二进制文件的机器上运行网关，然后从 Linux 以 [远程模式](#how-do-i-run-clawdbot-in-remote-mode-client-connects-to-a-gateway-elsewhere) 连接，或通过 Tailscale 连接。由于网关主机是 macOS，这些技能可以正常加载。

**选项 B - 使用 macOS 节点（无需 SSH）。**  
在 Linux 上运行网关，然后配对一个 macOS 节点（菜单栏应用），并在 macOS 上设置 **节点运行命令** 为“始终询问”或“始终允许”。当节点上存在所需的二进制文件时，Clawdbot 可以将 macOS 专用技能视为可用。代理会通过 `nodes` 工具运行这些技能。如果你选择“始终询问”，在提示中批准“始终允许”会将该命令添加到允许列表中。

**选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。**  
在 Linux 上保持网关运行，但让所需的 CLI 二进制文件通过 SSH 包装器在 Mac 上运行。然后覆盖技能设置，使 Linux 保持技能的可用性。
  
1) 为二进制文件创建一个 SSH 包装器（例如：`imsg`）：   ```bash
   #!/usr/bin/env bash
   set -euo pipefail
   exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"

ClawdHub 安装到当前目录下的 `./skills` 文件夹中（或回退到您配置的 Clawdbot 工作空间）；在下一次会话中，Clawdbot 会将该文件夹视为 `<workspace>/skills`。对于多个代理共享的技能，请将其放置在 `~/.clawdbot/skills/<name>/SKILL.md` 中。一些技能需要通过 Homebrew 安装二进制文件；在 Linux 上这意味着需要使用 Linuxbrew（请参见上面的 Homebrew Linux 常见问题解答）。请参阅 [Skills](/tools/skills) 和 [ClawdHub](/tools/clawdhub)。

### 如何安装浏览器接管的 Chrome 扩展

使用内置安装程序，然后在 Chrome 中加载未打包的扩展程序：```bash
clawdbot browser extension install
clawdbot browser extension path
```
然后在 Chrome 中 → `chrome://extensions` → 启用“开发者模式” → 点击“加载解压的扩展程序” → 选择该文件夹。

完整指南（包括通过 Tailscale 的远程网关 + 安全注意事项）：[Chrome 扩展程序](/tools/chrome-extension)

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

## 沙箱与内存

### 是否有专门的沙箱文档

是的。请参阅 [沙箱](/gateway/sandboxing)。对于 Docker 特定的设置（完整网关在 Docker 中或沙箱镜像中），请参阅 [Docker](/install/docker)。

**我可以保留 DM 为私有，但让群组在同一个代理下公开沙箱化吗**

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

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

设置步骤 + 示例配置：[群组：私有 DM + 公共群组](/concepts/groups#pattern-personal-dms-public-groups-single-agent)

关键配置参考：[网关配置](/gateway/configuration#agentsdefaultssandbox)

### 如何将主机文件夹绑定到沙箱中

将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如，`"/home/user/src:/src:ro"`）。全局绑定和按代理绑定会合并；当 `scope: "shared"` 时，按代理绑定会被忽略。对于任何敏感内容，请使用 `:ro`，并记住绑定会绕过沙箱的文件系统隔离。参见 [沙箱](/gateway/sandboxing#custom-bind-mounts) 和 [沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) 获取示例和安全注意事项。

### 内存是如何工作的

Clawdbot 的内存只是代理工作区中的 Markdown 文件：
- 每日笔记在 `memory/YYYY-MM-DD.md`
- 人工整理的长期笔记在 `MEMORY.md`（仅主/私人会话）

Clawdbot 还会运行一个 **无声的预压缩内存刷新**，以提醒模型在自动压缩前写入持久化笔记。这仅在工作区可写时运行（只读沙箱会跳过它）。参见 [内存](/concepts/memory)。

### 内存总是忘记东西，如何让它记住

让 bot **将事实写入内存**。长期笔记应放在 `MEMORY.md` 中，短期上下文则放在 `memory/YYYY-MM-DD.md` 中。

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

文档：[内存](/concepts/memory)，[代理工作区](/concepts/agent-workspace)。

### 语义内存搜索是否需要 OpenAI API 密钥

仅当你使用 **OpenAI 嵌入** 时才有效。Codex OAuth 仅覆盖 chat/completions 功能，**不** 提供嵌入访问权限，因此 **通过 Codex（OAuth 或 Codex CLI 登录）登录** 对语义记忆搜索 **没有帮助**。OpenAI 嵌入仍需要一个真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。

如果你没有显式设置提供者，当 Clawdbot 能够解析 API 密钥（认证配置文件、`models.providers.*.apiKey` 或环境变量）时，它会自动选择一个提供者。它会优先选择 OpenAI，如果 OpenAI 密钥可用；否则会选择 Gemini。如果两者密钥都不可用，记忆搜索将保持禁用，直到你进行配置。如果你配置了本地模型路径并且该路径存在，Clawdbot 会优先选择 `local`。

如果你想保持本地模式，可以设置 `memorySearch.provider = "local"`（并可选设置 `memorySearch.fallback = "none"`）。如果你想使用 Gemini 嵌入，可以设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini 或本地** 嵌入模型 - 请参阅 [Memory](/concepts/memory) 了解具体的配置细节。

### 记忆是否永久保存？有哪些限制？

记忆文件存储在磁盘上，并会一直存在直到你手动删除它们。限制取决于你的存储空间，而不是模型本身。**会话上下文** 仍然受限于模型的上下文窗口，因此长时间的对话可能会被压缩或截断。这就是为什么需要记忆搜索的原因——它只将相关部分重新拉入上下文中。

文档：[Memory](/concepts/memory)，[Context](/concepts/context)。

## 数据在磁盘上的存储位置

### Clawdbot 使用的所有数据都会本地保存吗？

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

- **默认本地存储**：会话、记忆文件、配置和工作区数据都存储在网关主机上（`~/.clawdbot` + 你的工作区目录）。
- **必要时远程存储**：你发送给模型提供者（如 Anthropic/OpenAI 等）的消息会发送到它们的 API，而聊天平台（如 WhatsApp/Telegram/Slack 等）则会将其消息数据存储在它们的服务器上。
- **你控制数据范围**：使用本地模型时，提示信息会保留在你的机器上，但频道流量仍会经过频道的服务器。

相关：[Agent 工作区](/concepts/agent-workspace)，[Memory](/concepts/memory)。

### 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`，可通过以下方式配置：
json5
{
  agents: { defaults: { workspace: "~/clawd" } }
}

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

会话状态由 **网关主机** 拥有。如果你处于远程模式，你关心的会话存储在远程机器上，而不是你的本地笔记本电脑上。请参阅 [会话管理](/concepts/session)。

## 配置基础

### 配置的格式是什么？它在哪里

Clawdbot 会从 `$CLAWDBOT_CONFIG_PATH`（默认值：`~/.clawdbot/clawdbot.json`）读取一个可选的 **JSON5** 配置文件：

$CLAWDBOT_CONFIG_PATH

注意事项：
- `gateway.remote.token` 仅用于 **远程 CLI 调用**；它不会启用本地网关认证。
- 控制 UI 通过 `connect.params.auth.token` 进行认证（存储在应用/UI 设置中）。请避免将令牌放在 URL 中。

### 为什么现在需要在 localhost 上使用令牌

向导默认会生成一个网关令牌（即使是在回环地址上），因此 **本地 WS 客户端必须进行认证**。这会阻止其他本地进程调用网关。请将令牌粘贴到 Control 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`。
json5
{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE",
        maxResults: 5
      },
      fetch: {
        enabled: true
      }
    }
  }
}

默认值为 `false`（有头模式）。无头模式在一些网站上更可能触发反机器人检查。请参阅 [Browser](/tools/browser)。

无头模式使用相同的 **Chromium 引擎**，并且适用于大多数自动化操作（表单填写、点击、爬取、登录）。主要区别如下：
- 没有可见的浏览器窗口（如需视觉效果，请使用截图）。
- 一些网站在无头模式下对自动化更严格（例如 CAPTCHA、反机器人机制）。
  例如，X/Twitter 常常会阻止无头会话。

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

将 `browser.executablePath` 设置为你的 Brave 可执行文件路径（或任何基于 Chromium 的浏览器），然后重启 Gateway。
有关完整的配置示例，请参阅 [Browser](/tools/browser#use-brave-or-another-chromium-based-browser)。

## 远程网关 + 节点

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

Telegram 消息由 **网关** 处理。网关运行代理程序，并在需要节点工具时通过 **网关 WebSocket** 调用节点：

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

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

### 如果网关托管在远程，我的代理如何访问我的电脑

简短回答：**将你的电脑作为节点进行配对**。网关运行在其他地方，但它可以通过网关 WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。

典型设置如下：
1) 在常驻主机（VPS/家庭服务器）上运行网关。
2) 将网关主机和你的电脑置于同一个 tailnet 网络中。
3) 确保网关 WebSocket 可以被访问（通过 tailnet 绑定或 SSH 隧道）。
4) 在本地打开 macOS 应用程序并以 **通过 SSH 远程连接** 模式（或直接 tailnet）连接，以便它可以注册为一个节点。
5) 在网关上批准该节点：
bash
   clawdbot nodes pending
   clawdbot nodes approve <requestId>
```   ```
无需单独的 TCP 桥接；节点通过网关 WebSocket 连接。

安全提醒：配对 macOS 节点将允许在该机器上运行 `system.run`。请仅配对你信任的设备，并查阅 [安全](/gateway/security)。

文档：[节点](/nodes)，[网关协议](/gateway/protocol)，[macOS 远程模式](/platforms/mac/remote)，[安全](/gateway/security)。

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

先检查基本设置：
- 网关是否正在运行：`clawdbot gateway status`
- 网关状态：`clawdbot status`
- 通道状态：`clawdbot channels status`

然后验证认证和路由：
- 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。
- 如果通过 SSH 隧道连接，请确认本地隧道已启动，并指向正确的端口。
- 确认你的允许列表（DM 或群组）中包含你的账户。

文档：[Tailscale](/gateway/tailscale)，[远程访问](/gateway/remote)，[通道](/channels)。

### 两个 Clawdbot 能否在本地 VPS 上互相通信？

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

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

**CLI 桥接（通用方法）**：运行一个脚本，通过 `clawdbot agent --message ... --deliver` 调用另一个网关，并指向另一个机器人监听的聊天通道。如果其中一个机器人在 Railway/VPS 上，可以通过 SSH/Tailscale（见 [远程访问](/gateway/remote)）连接到该远程网关。

示例模式（从可以访问目标网关的机器上运行）：```bash
clawdbot agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

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

### 如何在 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`
   - 网关 WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`

如果你想在不使用 SSH 的情况下使用控制界面，请在 VPS 上使用 Tailscale Serve：
bash
clawdbot gateway --tailscale serve```
这会将网关绑定到环回地址，并通过 Tailscale 暴露 HTTPS。请参见 [Tailscale](/gateway/tailscale)。

### 如何将 Mac 节点连接到远程网关的 Tailscale 服务

Serve 暴露了 **网关控制 UI + WS**。节点通过相同的网关 WS 端点进行连接。

推荐设置：
1) **确保 VPS 和 Mac 处于同一个 tailnet 中**。
2) **使用 macOS 应用程序的远程模式**（SSH 目标可以是 tailnet 主机名）。
   该应用程序会将网关端口进行隧道传输，并作为节点进行连接。
3) **在网关上批准该节点**：   ```bash
   clawdbot nodes pending
   clawdbot nodes approve <requestId>
   ```
"文档：[网关协议](/gateway/protocol)，[发现](/gateway/discovery)，[macOS 远程模式](/platforms/mac/remote)。

## 环境变量与 .env 文件加载

### Clawdbot 如何加载环境变量

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

- 当前工作目录下的 `.env` 文件
- 全局备用的 `.env` 文件，位于 `~/.clawdbot/.env`（即 `$CLAWDBOT_STATE_DIR/.env`）

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

你也可以在配置中直接定义环境变量（仅在进程环境变量中不存在时生效）：
json5
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." }
  }
}

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

### 我设置了 COPILOTGITHUBTOKEN，但模型状态显示 Shell 环境已关闭，为什么？

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

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

1) 将 token 放入 `~/.clawdbot/.env` 中：

   COPILOT_GITHUB_TOKEN=...
```   ```
2) 或启用 shell 导入（`env.shellEnv.enabled: true`）。
3) 或将其添加到你的配置 `env` 块中（仅在缺失时生效）。

然后重启网关并重新检查：```bash
clawdbot models status

### 是否可以创建一个由Clawdbots组成的团队，其中有一个CEO和多个代理

是的，可以通过 **多代理路由** 和 **子代理** 实现。你可以创建一个协调代理和多个工作代理，每个代理都有自己的工作空间和模型。

不过，这种情况最好被视为一个 **有趣的实验**。这种方式会消耗较多的token，并且通常比使用一个代理进行多个会话的效率要低。我们通常设想的是一个代理，你可以与它交谈，并为并行任务使用不同的会话。该代理在需要时也可以生成子代理。

文档：[多代理路由](/concepts/multi-agent)，[子代理](/tools/subagents)，[代理CLI](/cli/agents)。

### 为什么任务进行中上下文会被截断？如何防止这种情况

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

以下方法可能有帮助：
- 让代理总结当前状态并将其写入文件。
- 在进行长时间任务之前使用 `/compact` 命令，在切换主题时使用 `/new`。
- 将重要上下文保存在工作空间中，并让代理重新读取它。
- 对于长时间或并行任务，使用子代理，以保持主聊天窗口较小。
- 如果这种情况经常发生，可以选择一个具有更大上下文窗口的模型。```bash
clawdbot reset
```
非交互式完全重置：
bash
clawdbot reset --scope full --yes --non-interactive

注意事项：
- 如果启动向导检测到已有的配置，它还会提供 **重置** 选项。详见 [向导](/start/wizard)。
- 如果你使用了配置文件（`--profile` / `CLAWDBOT_PROFILE`），请为每个状态目录重置（默认路径为 `~/.clawdbot-<profile>`）。
- 开发环境重置：`clawdbot gateway --dev --reset`（仅限开发环境；会清除开发配置、凭证、会话和工作区）。

### 我遇到了“上下文太大”的错误，如何重置或压缩？

使用以下方法之一：

- **压缩**（保留对话内容，但对较早的对话进行摘要）：

  /compact
```  ```
或 `/compact <instructions>` 用于指导摘要。

- **重置**（为相同的聊天密钥生成新的会话ID）：  ```
  /new
  /reset

如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 Markdown 标题如 `# 标题`），Clawdbot 会跳过心跳运行以节省 API 调用次数。
如果该文件缺失，心跳仍然会运行，由模型决定如何处理。

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

### 我需要将机器人账户添加到 WhatsApp 群组中吗？

不需要。Clawdbot 在 **你的个人账户** 上运行，所以如果你在该群组中，Clawdbot 也能看到它。
默认情况下，群组回复会被阻止，直到你允许发送者（`groupPolicy: "allowlist"`）。

如果你想只有 **你自己** 能够触发群组回复：```json5
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    }
  }
}
```
### 如何获取 WhatsApp 群组的 JID

选项 1（最快）：查看日志并在群组中发送测试消息：
bash
clawdbot logs --follow --json

文档：[WhatsApp](/channels/whatsapp)，[目录](/cli/directory)，[日志](/cli/logs)。

### 为什么Clawdbot在群组中不回复

两个常见原因：
- 有人@提醒功能已开启（默认开启）。你必须@提及机器人（或匹配 `mentionPatterns`）。
- 你配置了 `channels.whatsapp.groups` 但没有包含 `"*"`，并且该群组未被允许使用。

参见 [群组](/concepts/groups) 和 [群组消息](/concepts/group-messages)。

### 群组/线程是否与私信（DMs）共享上下文

默认情况下，私信会合并到主会话中。群组/频道有自己独立的会话密钥，Telegram 的主题 / Discord 的线程是独立的会话。参见 [群组](/concepts/groups) 和 [群组消息](/concepts/group-messages)。

### 我可以创建多少个工作区和代理

没有硬性限制。数十个甚至上百个都是可以的，但需要注意以下几点：

- **磁盘增长**：会话和对话记录存储在 `~/.clawdbot/agents/<agentId>/sessions/` 下。
- **令牌成本**：更多的代理意味着更多的模型并发使用。
- **运维开销**：每个代理都需要单独的认证配置、工作区和频道路由。

提示：
- 为每个代理保持一个**活跃**的工作区（`agents.defaults.workspace`）。
- 如果磁盘空间增长，可以清理旧的会话（删除 JSONL 或存储条目）。
- 使用 `clawdbot doctor` 来发现多余的 workspace 和配置不匹配问题。

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

可以。使用 **多代理路由** 来运行多个独立的代理，并根据频道/账号/联系人路由入站消息。Slack 作为频道支持，并且可以绑定到特定的代理。

浏览器访问功能强大，但不是“能做人类能做的事”——反机器人机制、CAPTCHA 和 MFA 仍可能阻止自动化。为了最可靠的浏览器控制，建议在运行浏览器的机器上使用 Chrome 扩展中继（relay），并让 Gateway 部署在任何地方。

最佳实践设置：
- 始终运行的 Gateway 主机（VPS / Mac mini）。
- 每个代理对应一个角色（绑定）。
- 将 Slack 频道绑定到这些代理。
- 需要时通过扩展中继（或节点）使用本地浏览器。

文档：[多代理路由](/concepts/multi-agent)，[Slack](/channels/slack)，[浏览器](/tools/browser)，[Chrome 扩展](/tools/chrome-extension)，[节点](/nodes)。

## 模型：默认设置、选择、别名、切换

### 什么是默认模型

Clawdbot 的默认模型是你设置的：
yaml
model: "gpt-4o"``````
agents.defaults.model.primary

你也可以为提供者（每个会话）强制指定特定的认证配置文件：

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

如果想要恢复默认模型，请从 `/model` 中选择（或发送 `/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`（或反过来）。
- **子代理：** 将编码任务路由到使用不同默认模型的子代理。

详见 [Models](/concepts/models) 和 [Slash 命令](/tools/slash-commands)。
"provider/model" 模型不允许使用。请使用 `/model` 列出可用模型。```
返回此错误 **而非正常回复**。修复方法：将模型添加到 `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) 运行：   ```bash
   clawdbot models list

然后：```
/model gpt
```
**选项 B：独立代理**
- 代理 A 默认：MiniMax
- 代理 B 默认：OpenAI
- 按代理路由或使用 `/agent` 切换

文档：[模型](/concepts/models), [多代理路由](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/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`。例如：
json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-5" },
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" }
      }
    }
  }
}

Z.AI（GLM 模型）：
json5
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} }
    }
  },
  env: { ZAI_API_KEY: "..." }
}

修复选项：
- 运行 `clawdbot agents add <id>` 并在向导中配置认证信息。
- 或者将主代理的 `agentDir` 中的 `auth-profiles.json` 文件复制到新代理的 `agentDir` 中。

请 **不要** 在多个代理之间重复使用 `agentDir`；这会导致认证/会话冲突。

## 模型故障转移与“所有模型均失败”

### 故障转移是如何工作的

故障转移分为两个阶段：

1) **同一提供者内的认证配置轮换**。
2) **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。

对于失败的认证配置会应用冷却时间（指数退避机制），因此即使某个提供者被限流或暂时失败，Clawdbot 仍可以继续响应。 

### 这个错误意味着什么
No credentials found for profile "anthropic:default"```
这意味着系统尝试使用身份验证配置文件 ID `anthropic:default`，但在预期的身份验证存储中找不到相应的凭据。

### 未找到 anthropicdefault 配置文件凭据的修复检查清单

- **确认身份验证配置文件所在的位置**（新路径与旧路径）
  - 当前路径：`~/.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` 查看已配置的模型以及提供者是否已通过身份验证。

### 未找到 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 密钥代替**
  - 在 **网关主机** 上的 `~/.clawdbot/.env` 中放入 `ANTHROPIC_API_KEY`。
  - 清除任何强制使用 `anthropic:claude-cli` 的固定订单配置：    ```bash
    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 请求被拒绝的消息：思考签名需要 Google Antigravity**

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

解决方法：现在 Clawdbot 会移除没有签名的思考块以适配 Google Antigravity Claude。如果问题仍然存在，请启动一个 **新会话**，或为该代理设置 `/thinking off`。```
### 什么是典型的配置文件 ID

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

- `anthropic:default`（当没有电子邮件身份时常见）
- `anthropic:<email>`（用于 OAuth 身份）
- 你自己选择的自定义 ID（例如 `anthropic:work`）

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

可以。配置支持为每个配置文件添加可选的元数据，并为每个提供者设置尝试顺序（`auth.order.<provider>`）。这**不会**存储密钥；它将 ID 映射到提供者/模式，并设置轮换顺序。

如果某个配置文件处于短期的**冷却状态**（速率限制/超时/认证失败）或更长的**禁用状态**（账单问题/信用不足），Clawdbot 可能会暂时跳过该配置文件。要检查这些状态，请运行 `clawdbot models status --json` 并查看 `auth.unusableProfiles`。调整参数：`auth.cooldowns.billingBackoffHours*`。

你也可以通过 CLI 为**每个代理**设置尝试顺序的覆盖（存储在该代理的 `auth-profiles.json` 中）：```bash
# Defaults to the configured default agent (omit --agent)
clawdbot models auth order get --provider anthropic

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

# Or set an explicit order (fallback within provider)
clawdbot models auth order set --provider anthropic anthropic:claude-cli anthropic:default

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

### OAuth 与 API 密钥的区别

Clawdbot 支持以下两种方式：

- **OAuth** 通常会使用订阅访问（在适用的情况下）。
- **API 密钥** 使用按令牌计费的方式。

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

## 网关：端口、“已运行”以及远程模式

### 网关使用哪个端口

`gateway.port` 控制用于 WebSocket + HTTP 的单一多路复用端口（控制 UI、钩子等）。

优先级：```
--port > CLAWDBOT_GATEWAY_PORT > gateway.port > default 18789
```
### 为什么 clawdbot 网关状态显示 Runtime 运行但 RPC 探针失败？

因为“运行”是 **supervisor（启动守护进程）** 的视角（launchd/systemd/schtasks）。RPC 探针是 CLI 实际连接到网关 WebSocket 并调用 `status` 的过程。

使用 `clawdbot gateway status` 并信任以下几行：
- `Probe target:`（探针实际使用的 URL）
- `Listening:`（实际绑定在端口上的内容）
- `Last gateway error:`（当进程正在运行但端口未监听时的常见原因）

### 为什么 clawdbot 网关状态显示 Config cli 和 Config service 不同？

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

修复方法：
bash
clawdbot gateway install --force

### 注意事项：
- `clawdbot gateway` 仅在 `gateway.mode` 设置为 `local` 时启动（或你传递了覆盖标志）。
- macOS 应用会实时监控配置文件，并在这些值发生变化时切换模式。

### 控制 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/troubleshooting) 进行操作。查看 [仪表盘](/web/dashboard) 获取认证详细信息。

### 我设置了 gatewaybind tailnet，但无法绑定，没有服务监听

`tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果该机器没有连接到 Tailscale（或接口处于关闭状态），就没有可用的 IP 可以绑定。

解决方法：
- 在该主机上启动 Tailscale（这样它会获得一个 100.x 地址），或者
- 改为使用 `gateway.bind: "loopback"` / `"lan"`。

注意：`tailnet` 是显式绑定。`auto` 会优先选择 loopback；当你希望仅绑定到 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>)`）。
完整指南：[多个网关](/gateway/multiple-gateways)。

### “无效的握手代码 1008” 是什么意思

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

常见原因：
- 你在浏览器中打开了 **HTTP** URL（`http://...`），而不是 WebSocket 客户端。
- 使用了错误的端口或路径。
- 代理或隧道移除了认证头，或发送了非网关请求。

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

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

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

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

最快的日志尾随方式：
bash
clawdbot logs --follow

如果手动运行网关，`clawdbot gateway --force` 可以释放端口。参见 [网关](/gateway)。

### 我在 Windows 上关闭了终端，如何重新启动 Clawdbot

有两种 **Windows 安装模式**：

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

打开 PowerShell，进入 WSL，然后重新启动：
powershell
wsl
clawdbot gateway status
clawdbot gateway restart

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

打开 PowerShell 并运行：
powershell
clawdbot gateway status
clawdbot gateway restart

文档：[Windows (WSL2)](/platforms/windows)，[网关服务运行手册](/gateway)。

### 网关已启动但未收到响应 应该检查什么

首先进行一次快速健康检查：
bash
clawdbot status
clawdbot models status
clawdbot channels status
clawdbot logs --follow

文档：[仪表板](/web/dashboard)，[远程访问](/gateway/remote)，[故障排除](/gateway/troubleshooting)。

### 在使用 setMyCommands 时出现网络错误，应该检查什么

首先查看日志和频道状态：
bash
clawdbot channels status
clawdbot channels logs --channel telegram

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

文档：[TUI](/tui)，[斜杠命令](/tools/slash-commands)。

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

如果你已安装该服务：
bash
clawdbot gateway stop
clawdbot gateway start```
这将停止/启动 **受监督的服务**（在 macOS 上为 launchd，在 Linux 上为 systemd）。
当网关以后台守护进程形式运行时，请使用此命令。

如果您以前台模式运行，请使用 Ctrl-C 停止，然后执行以下操作：```bash
clawdbot gateway run

另外请检查：
- 目标频道支持出站媒体，并且未被允许列表阻止。
- 文件在提供方的大小限制内（图片最大调整为2048像素）。

查看 [Images](/nodes/images)。

## 安全与访问控制

### 暴露 Clawdbot 给入站私信（DMs）是否安全？

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

- 在支持 DM 的频道上，默认行为是 **配对（pairing）**：
  - 未知发送者会收到一个配对码；机器人不会处理他们的消息。
  - 批准配对请使用：`clawdbot pairing approve <channel> <code>`
  - 每个频道的待处理请求最多为 **3 条**；如果未收到码，请检查 `clawdbot pairing list <channel>`。

- 如果要公开开放 DM，请明确选择加入（`dmPolicy: "open"` 和允许列表 `"*"`）。

运行 `clawdbot doctor` 以发现有风险的 DM 策略。

### 提示注入（prompt injection）是否只对公开的机器人有影响？

不是。提示注入关注的是 **不受信任的内容**，而不仅仅是谁能向机器人发送私信。
如果你的助手读取了外部内容（如网络搜索/获取、网页内容、邮件、文档、附件、粘贴的日志），这些内容可能包含试图劫持模型的指令。即使 **你本人是唯一的发送者**，这种情况也有可能发生。

最大的风险出现在启用了工具时：模型可能被欺骗，泄露上下文或代表你调用工具。为了减少影响范围，可以：
- 使用只读或禁用工具的“阅读器”代理来总结不受信任的内容
- 对于启用了工具的代理，关闭 `web_search` / `web_fetch` / `browser`
- 对工具进行沙箱隔离和严格允许列表控制

详情：[Security](/gateway/security)。

### 我的机器人是否应该拥有自己的 GitHub 邮箱账号或手机号？

是的，对于大多数设置来说都是如此。通过使用独立的账号和手机号来隔离机器人，可以降低出现问题时的影响范围。这也便于在需要时轮换凭证或撤销访问权限，而不会影响到你的个人账号。

从小处开始。仅给予机器人你实际需要的工具和账号权限，如有需要再逐步扩展。

文档：[Security](/gateway/security)、[Pairing](/start/pairing)。

### 我可以让机器人自主处理我的短信吗？这样安全吗？

我们 **不推荐** 让机器人拥有对个人短信的完全自主权。最安全的做法是：
- 将 DM 保持在 **配对模式** 或严格允许列表中。
- 如果你希望它代表你发送消息，请使用 **单独的号码或账号**。
- 让它起草内容，然后在发送前进行 **人工审批**。

如果你想进行实验，请在专用账号上进行，并保持隔离。查看 [Security](/gateway/security)。

### 我可以使用更便宜的模型来执行个人助手任务吗？

可以，**如果** 该代理仅用于聊天且输入是可信的。较小的模型层级更容易受到指令劫持的影响，因此不建议用于启用了工具的代理或读取不可信内容的场景。如果必须使用较小的模型，请严格限制工具并运行在沙箱环境中。查看 [Security](/gateway/security)。

当未知发件人向机器人发送消息且启用 `dmPolicy: "pairing"` 时，才会发送配对代码。单独的 `/start` 命令不会生成代码。

检查待处理的请求：```bash
clawdbot pairing list telegram
```
如果你想要立即访问，请将你的发件人ID加入白名单或为该账户设置 `dmPolicy: "open"`。

### WhatsApp 会向我的联系人发送消息吗？配对是如何工作的？

不会。默认的 WhatsApp DM 策略是 **配对**。未知发件人只会收到一个配对码，他们的消息 **不会被处理**。Clawdbot 仅回复它接收到的聊天或你手动触发的发送。

批准配对的方式如下：
bash
clawdbot pairing approve whatsapp <code>

**Wizard 电话号码提示**：用于设置你的 **允许列表/所有者**，以便允许你的私人消息。它不用于自动发送。如果你使用个人 WhatsApp 电话号码，请使用该号码并启用 `channels.whatsapp.selfChatMode`。

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

### 如何停止内部系统消息在聊天中显示

大多数内部或工具消息只有在该会话中启用了 **verbose** 或 **reasoning** 时才会出现。

在你看到这些消息的聊天中进行修复：

/verbose off  
/reasoning off  

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

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

process action: kill sessionId: XXX