快速入门

目标：从零基础到首次工作聊天（使用合理的默认配置）尽可能快速完成。

最快的聊天方式：打开控制界面（无需频道设置）。运行：


moltbot dashboard

在浏览器中聊天，或在网关主机上打开 http://127.0.0.1:18789/。

推荐路径：使用 CLI 引导向导。它会设置：

如果你想要更深入的参考页面，跳转到：向导、设置、配对、安全。

沙箱注意事项：agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（默认 "main"），因此群组/频道会话会被沙箱化。如果你希望主代理始终在主机上运行，设置显式的每个代理覆盖：


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

0) 前置要求

Node >=22
pnpm（可选；如果从源代码构建则推荐）
推荐： Brave Search API 密钥用于网络搜索。最简单的方式： moltbot configure --section web（存储 tools.web.search.apiKey）。参见 Web 工具。

macOS：如果你计划构建应用程序，安装 Xcode / CLT。仅 CLI + 网关的话，Node 就足够了。

Windows：使用 WSL2（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经测试，问题较多，工具兼容性较差。先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 Windows (WSL2)。


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

安装程序选项（安装方法、非交互式、从 GitHub）：安装。

Windows (PowerShell)：


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

替代方案（全局安装）：


npm install -g moltbot@latest

或使用 pnpm：


pnpm add -g moltbot@latest


moltbot 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 复制到网关主机。

如果你在引导期间安装了服务，网关应该已经在运行：


moltbot gateway status

手动运行（前台）：


moltbot gateway


moltbot status

应该显示：


moltbot channels login

扫描二维码即可连接。

按照各自的设置指南：

默认情况下，未知发件人会收到配对代码。你需要批准：


moltbot pairing list <channel>
moltbot pairing approve <channel> <code>

参见配对获取详细信息。


git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build
pnpm build
moltbot onboard --install-daemon

发送测试消息：


moltbot message send --target +15555550123 --message "你好，来自 Moltbot"

或直接在配对的频道中发送消息。