入门指南
目标：尽快从 零 → 第一次正常聊天（使用合理的默认设置）。
推荐路径：使用 CLI 入职向导 (clawdbot onboard)。它会设置：
- 模型/认证 (推荐 OAuth)
- 网关设置
- 频道 (WhatsApp/Telegram/Discord/Mattermost (插件)/...)
- 配对默认值 (安全私聊)
- 工作区引导 + 技能
- 可选的后台服务
如果你想要更深入的参考页面，请跳转至：向导、设置、配对、安全。
沙盒说明：agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey (默认 "main")，因此群组/频道会话是沙盒化的。如果你希望主智能体始终在主机上运行，请设置显式的每智能体覆盖：
{
"routing": {
"agents": {
"main": {
"workspace": "~/clawd",
"sandbox": { "mode": "off" }
}
}
}
}
0) 先决条件
- Node
>=22 pnpm(可选；如果是从源码构建则推荐)- 推荐： 用于网络搜索的 Brave Search API 密钥。最简单的路径：
clawdbot configure --section web(存储tools.web.search.apiKey)。 参见 Web 工具。
macOS：如果你计划构建应用程序，请安装 Xcode / CLT。仅对于 CLI + 网关，Node 就足够了。 Windows：使用 WSL2 (推荐 Ubuntu)。强烈推荐 WSL2；原生 Windows 未经测试，问题较多，且工具兼容性较差。请先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 Windows (WSL2)。
1) 安装 CLI (推荐)
curl -fsSL https://clawd.bot/install.sh | bash
安装程序选项（安装方法、非交互式、从 GitHub）：安装。
Windows (PowerShell):
iwr -useb https://clawd.bot/install.ps1 | iex
替代方案 (全局安装):
npm install -g clawdbot@latest
pnpm add -g clawdbot@latest
2) 运行入职向导 (并安装服务)
clawdbot onboard --install-daemon
你需要选择：
- 本地 vs 远程 网关
- 认证：OpenAI Code (Codex) 订阅 (OAuth) 或 API 密钥。对于 Anthropic 我们推荐 API 密钥；
claude setup-token也受支持。 - 提供商：WhatsApp 二维码登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
- 守护进程：后台安装 (launchd/systemd; WSL2 使用 systemd)
- 运行时：Node (推荐；WhatsApp/Telegram 必需)。Bun 不推荐。
- 网关令牌：向导默认生成一个（即使在回环上）并将其存储在
gateway.auth.token中。
向导文档：向导
认证：它存在哪里 (重要)
-
推荐的 Anthropic 路径 ： 设置一个 API 密钥（向导可以将其存储以供服务使用）。如果你想复用 Claude Code 凭证，
claude setup-token也受支持。 -
OAuth 凭证 (旧版导入)：
~/.clawdbot/credentials/oauth.json -
认证配置文件 (OAuth + API 密钥)：
~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
无头/服务器提示：先在普通机器上进行 OAuth，然后将 oauth.json 复制到网关主机。
3) 启动网关
如果你在入职期间安装了服务，网关应该已经在运行了：
clawdbot gateway status
手动运行（前台）：
clawdbot gateway --port 18789 --verbose
仪表板 (本地回环)：http://127.0.0.1:18789/
如果配置了令牌，请将其粘贴到控制 UI 设置中（存储为 connect.params.auth.token）。
⚠️ Bun 警告 (WhatsApp + Telegram)： Bun 在这些频道上存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 Node 运行网关。
3.5) 快速验证 (2 分钟)
clawdbot status
clawdbot health
4) 配对并连接你的第一个聊天界面
WhatsApp (二维码登录)
clawdbot channels login
通过 WhatsApp → 设置 → 已连接设备进行扫描。
WhatsApp 文档：WhatsApp
Telegram / Discord / 其他
向导可以为你编写令牌/配置。如果你更喜欢手动配置，请从以下内容开始：
- Telegram：Telegram
- Discord：Discord
- Mattermost (插件)：Mattermost
Telegram 私聊提示： 你的第一条私聊消息会返回一个配对码。批准它（参见下一步），否则机器人不会响应。
5) 私聊安全 (配对批准)
默认策略：未知的私聊消息会获得一个短代码，在批准之前不会处理消息。 如果你的第一条私聊消息没有回复，请批准配对：
clawdbot pairing list whatsapp
clawdbot pairing approve whatsapp <code>
配对文档：配对
6) 从源码运行 (开发)
如果你正在开发 Clawdbot 本身，请从源码运行：
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
clawdbot onboard --install-daemon
如果你还没有全局安装，请在仓库中通过 pnpm clawdbot ... 运行入职步骤。
网关 (来自此仓库)：
node dist/entry.js gateway --port 18789 --verbose
7) 端到端验证
在一个新终端中，发送一条测试消息：
clawdbot message send --target +15555550123 --message "Hello from Clawdbot"
如果 clawdbot health 显示 “未配置认证”，请返回向导并设置 OAuth/密钥认证 —— 否则智能体将无法响应。
提示：clawdbot status --all 是最好的可粘贴、只读调试报告。
健康探测：clawdbot health (或 clawdbot status --deep) 向运行中的网关请求健康快照。