文档
开始使用
快速开始

快速开始

适用范围

当你需要：

  • 第一次从零开始安装
  • 追求从安装 → 初始化 → 第一条可用回复的最快路径

目标：尽可能快地从 零 到 第一条可用对话（默认安全策略合理）。

推荐路径：使用 CLI 初始化向导（moltbot onboard）。它会帮你配置：

  • 模型与鉴权（推荐 OAuth）
  • 网关设置
  • 渠道（WhatsApp/Telegram/Discord/Mattermost（插件）等）
  • 配对默认值（更安全的 DMs）
  • 工作区引导文件与技能
  • 可选：安装后台服务

如果你需要更深入的说明，可跳转：/zh-cn/docs/start/wizard/、/zh-cn/docs/start/setup/、/zh-cn/docs/start/pairing/、/zh-cn/docs/gateway/security/。

沙箱提示：agents.defaults.sandbox.mode: "non-main" 会根据 session.mainKey（默认 "main"）判断哪些会话会被沙箱化；群聊/频道会话通常会落入沙箱。如果你希望主 agent 永远在宿主机运行，可显式覆盖：

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) 前置条件

  • Node >=22
  • pnpm（可选；从源码构建时推荐）
  • 推荐：Brave Search API Key（用于 web search）。最省事的路径：moltbot configure --section web（写入 tools.web.search.apiKey）。相关说明见：/en/docs/tools/web/。

macOS：只用 CLI + 网关通常只需要 Node；如果你要构建应用，再安装 Xcode / CLT。 Windows：推荐 WSL2（Ubuntu 优先）。原生 Windows 未充分测试，兼容性与工具链更容易出问题。先装 WSL2，再在 WSL 里按 Linux 流程执行：/en/docs/platforms/windows/。

1) 安装 CLI（推荐） 

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

安装器可选项（安装方式、非交互、从 GitHub 安装等）：/zh-cn/docs/install/。

Windows（PowerShell）：

iwr -useb https://clawd.bot/install.ps1 | iex

备选方案（全局安装）：

npm install -g moltbot@latest
pnpm add -g moltbot@latest

2) 运行初始化向导（并安装后台服务） 

moltbot onboard --install-daemon

你会在向导里选择/配置：

  • 网关模式：本机 / 远程
  • 鉴权：OpenAI Code（Codex）订阅（OAuth）或 API Key；Anthropic 更推荐 API Key，也支持 claude setup-token
  • 渠道接入：WhatsApp 扫码、Telegram/Discord bot token、Mattermost 插件 token 等
  • 后台服务：安装到 launchd/systemd（WSL2 使用 systemd）
    • 运行时：Node（推荐；WhatsApp/Telegram 必需）。不建议使用 Bun。
  • 网关 token：向导默认会生成并写入 gateway.auth.token（即便是 loopback）

向导说明：/zh-cn/docs/start/wizard/

鉴权文件在哪里（重要）

  • 推荐的 Anthropic 路径：使用 API Key（向导可写入并供后台服务读取）；如果你希望复用 Claude Code 凭证，也支持 claude setup-token。
  • OAuth 凭证（遗留导入）：~/.moltbot/credentials/oauth.json
  • 鉴权档案（OAuth + API keys）：~/.moltbot/agents/<agentId>/agent/auth-profiles.json

无头/服务器小技巧：先在常用机器上完成 OAuth，再把 oauth.json 复制到网关主机。

3) 启动网关

如果你在向导里安装了后台服务，网关通常已经在运行：

moltbot gateway status

手动前台运行（便于看日志）：

moltbot gateway --port 18789 --verbose

控制台（本机 loopback）：http://127.0.0.1:18789/ 如果配置了 token，把它粘贴到控制台设置里（写入 connect.params.auth.token）。

注意（WhatsApp + Telegram）：Bun 对这些渠道存在已知问题；如需 WhatsApp/Telegram，请使用 Node 运行网关。

3.5) 两分钟快速验证 

moltbot status
moltbot health

4) 配对并接入你的第一个聊天入口

WhatsApp（扫码登录） 

moltbot channels login

在 WhatsApp 里扫码：Settings → Linked Devices。

WhatsApp 说明：/zh-cn/docs/channels/whatsapp/

Telegram / Discord / 其他

向导可以帮你写入 token/配置。如果你希望手动配置，可从这些页面开始：

  • Telegram：/zh-cn/docs/channels/telegram/
  • Discord：/zh-cn/docs/channels/discord/
  • Mattermost（插件）：/en/docs/channels/mattermost/

Telegram DM 提示：第一次私聊通常会返回一个配对码；需要先批准（见下一步）否则不会继续处理消息。

5) DM 安全（配对审批）

默认姿态：未知 DM 会收到一个短配对码，在被批准前，消息不会进入智能体处理。 如果你第一次 DM 没收到回复，先批准配对：

moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>

配对说明：/zh-cn/docs/start/pairing/

从源码运行（开发）

如果你在开发/改 Moltbot 本身，可从源码运行：

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
moltbot onboard --install-daemon

如果你还没全局安装 CLI，可在仓库目录用 pnpm moltbot ... 运行向导相关命令。

从仓库启动网关：

node dist/entry.js gateway --port 18789 --verbose

7) 端到端验证

在另一个终端里发送一条测试消息：

moltbot message send --target +15555550123 --message "Hello from Moltbot"

如果 moltbot health 显示“no auth configured”，回到向导配置 OAuth/API key；没有鉴权时智能体无法正常回复。

小技巧：moltbot status --all 是最适合粘贴分享的只读诊断报告。 健康探测：moltbot health（或 moltbot status --deep）会向运行中的网关请求一份健康快照。

下一步（可选，但很实用）

  • macOS 菜单栏应用与语音唤醒：/en/docs/platforms/macos/
  • iOS/Android nodes（Canvas/camera/voice）：/en/docs/nodes/
  • 远程访问（SSH 隧道 / Tailscale Serve）：/en/docs/gateway/remote/ 与 /en/docs/gateway/tailscale/
  • 常驻/VPN 场景：/en/docs/gateway/remote/、/en/docs/platforms/exe-dev/、/en/docs/platforms/hetzner/、/en/docs/platforms/mac/remote/
安装与更新策略配对（Pairing）