文档
开始使用
向导（onboard）

向导（onboard）

适用范围

当你需要运行/配置初始化向导、或在新机器上完成一次可用的部署时，用这页。

初始化向导是 macOS/Linux/Windows（通过 WSL2，强烈推荐）上配置 Moltbot 的推荐方式。 它会在一个引导流程里完成本机网关（或连接远程网关）、渠道、技能、工作区默认值等配置。

主入口：

moltbot onboard

后续补充配置：

moltbot configure

建议：配置 Brave Search API Key 让智能体可以使用 web_search（web_fetch 不需要 key）。最省事的路径：moltbot configure --section web（写入 tools.web.search.apiKey）。相关说明：/en/docs/tools/web/。

QuickStart vs Advanced

向导一开始会让你选择 QuickStart（默认值）或 Advanced（完整控制）。

QuickStart 保持默认：

  • 本机网关（loopback）
  • 工作区默认路径（或复用已有工作区）
  • 网关端口 18789
  • 网关鉴权 Token（自动生成，即便是 loopback）
  • Tailscale 暴露关闭
  • Telegram + WhatsApp 的 DMs 默认使用 allowlist（会提示你输入自己的号码）

Advanced 会展开所有步骤（模式、工作区、网关、渠道、后台服务、技能）。

向导会做什么

本机模式（默认） 会引导你完成：

  • 模型与鉴权（OpenAI Code（Codex）订阅 OAuth、Anthropic API key（推荐）或 setup-token（粘贴），以及 MiniMax/GLM/Moonshot/AI Gateway 等选项）
  • 工作区位置与引导文件
  • 网关设置（port/bind/auth/tailscale）
  • 渠道（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal）
  • 安装后台服务（LaunchAgent / systemd user unit）
  • 健康检查
  • 安装/选择技能（推荐）

远程模式 只会在本机写入“如何连接另一个网关”的客户端配置；不会在远端主机上安装或修改任何东西。

如果你希望新增更多隔离的 agent（各自独立 workspace/sessions/auth），使用：

moltbot agents add <name>

提示：--json 不代表非交互；脚本场景请使用 --non-interactive（必要时加 --workspace）。

流程细节（本机）

  1. 检测现有配置

    • 如果 ~/.moltbot/moltbot.json 已存在，会让你选：Keep / Modify / Reset。
    • 重新运行向导不会清空任何东西，除非你明确选择 Reset（或传 --reset）。
    • 如果配置无效或含遗留字段，向导会停止并要求你先运行 moltbot doctor。
    • Reset 使用 trash（不会用 rm），并提供范围选择：
      • 仅配置
      • 配置 + 凭证 + 会话
      • 完全重置（也会删除 workspace）

  2. 模型与鉴权

    • Anthropic API key（推荐）：优先读 ANTHROPIC_API_KEY；否则提示输入，并保存供后台服务使用。
    • Anthropic OAuth（Claude Code CLI）：
      • macOS：向导会检查 Keychain 项 “Claude Code-credentials”（建议在弹窗里选择 “Always Allow”，避免 launchd 启动时卡住）。
      • Linux/Windows：若存在则复用 ~/.claude/.credentials.json。
    • Anthropic token（粘贴 setup-token）：在任意机器上运行 claude setup-token，再把 token 粘贴进来（可命名；空白表示默认）。
    • OpenAI Code（Codex）订阅（Codex CLI）：如果存在 ~/.codex/auth.json，向导可复用。
    • OpenAI Code（Codex）订阅（OAuth）：浏览器流程；粘贴 code#state。
      • 当模型未设置或是 openai/* 时，会把 agents.defaults.model 设为 openai-codex/gpt-5.2。
    • OpenAI API key：优先读 OPENAI_API_KEY；否则提示输入，并写入 ~/.moltbot/.env 供 launchd 读取。
    • OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY；获取地址：https://opencode.ai/auth）。
    • Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
      • 相关说明：/en/docs/providers/vercel-ai-gateway/
    • MiniMax M2.1：向导会自动写入配置。
      • 相关说明：/en/docs/providers/minimax/
    • Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
      • 相关说明：/en/docs/providers/synthetic/
    • Moonshot（Kimi K2） / Kimi Code：向导会自动写入配置。
      • 相关说明：/en/docs/providers/moonshot/
    • Skip：暂不配置鉴权。
    • 选择默认模型（来自已检测到的选项，或手动输入 provider/model）。
    • 向导会做模型检查：当模型未知或缺少鉴权时提示警告。
    • OAuth 凭证通常在 ~/.moltbot/credentials/oauth.json；鉴权档案在 ~/.moltbot/agents/<agentId>/agent/auth-profiles.json（API keys + OAuth）。
      • 相关说明：/en/docs/concepts/oauth/

  3. 工作区

    • 默认 ~/clawd（可改）。
    • 会初始化一组工作区文件，用于智能体的引导与约束。
    • 工作区布局与备份建议：/en/docs/concepts/agent-workspace/

  4. 网关

    • 端口、绑定、鉴权模式、Tailscale 暴露。
    • 鉴权建议：即便是 loopback 也保留 Token，让本机 WS 客户端也必须鉴权。
    • 只有当你完全信任所有本机进程时才考虑关闭鉴权。
    • 非 loopback 绑定仍然需要鉴权。

  5. 渠道

    • WhatsApp：可选扫码登录。
    • Telegram：bot token。
    • Discord：bot token。
    • Google Chat：service account JSON + webhook audience。
    • Mattermost（插件）：bot token + base URL。
    • Signal：可选安装 signal-cli 并配置账号。
    • iMessage：本机 imsg CLI 路径 + 数据库访问权限。
    • DM 安全：默认是 pairing；第一次 DM 会返回配对码，可用 moltbot pairing approve <channel> <code> 批准，或改用 allowlists。

  6. 后台服务安装

    • macOS：LaunchAgent
      • 需要用户登录态；无头场景需自定义 LaunchDaemon（默认不提供）。
    • Linux（以及 Windows 通过 WSL2）：systemd user unit
      • 向导会尝试执行 loginctl enable-linger <user>，让网关在注销后仍能运行。
      • 可能会请求 sudo（写入 /var/lib/systemd/linger），会先尝试不带 sudo。
    • 运行时选择：Node（推荐；WhatsApp/Telegram 必需）。不建议 Bun。

  7. 健康检查

    • 需要时会启动网关并执行 moltbot health。
    • 提示：moltbot status --deep 会在 status 输出里加入网关健康探测（需要网关可达）。

  8. 技能（推荐）

    • 读取可用技能并检查依赖。
    • 让你选择 node manager：npm / pnpm（不建议 bun）。
    • 安装可选依赖（macOS 上部分依赖会使用 Homebrew）。

  9. 完成

    • 输出总结与下一步（包括 iOS/Android/macOS 应用能力）。
    • 如果检测不到 GUI，会打印 Control UI 的 SSH 端口转发方式，而不是直接打开浏览器。
    • 如果缺少 Control UI 资源，向导会尝试构建；兜底命令是 pnpm ui:build（首次运行会自动安装 UI 依赖）。

远程模式

远程模式会在本机配置“连接另一个网关”的客户端参数。

你需要设置：

  • 远程网关 URL（ws://...）
  • 远程网关的 token（推荐启用鉴权）

说明：

  • 不会在远端执行安装或变更后台服务。
  • 如果远端网关只绑定 loopback，请使用 SSH 隧道或 tailnet。
  • 发现/探测提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

新增一个 agent

使用 moltbot agents add <name> 创建一个独立 agent（独立 workspace、sessions、鉴权档案）。不带 --workspace 会进入向导模式。

会写入：

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

说明：

  • 默认 workspace 跟随 ~/clawd-<agentId>。
  • 通过 bindings 把入站消息路由到不同 agent（向导可协助配置）。
  • 非交互参数：--model、--agent-dir、--bind、--non-interactive。

非交互模式

使用 --non-interactive 便于自动化/脚本：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

加上 --json 可输出机器可读的摘要。

Gemini 示例：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI 示例：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI Gateway 示例：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot 示例：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic 示例：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zen 示例：

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

新增 agent（非交互）示例：

moltbot agents add work \
  --workspace ~/clawd-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

网关向导 RPC

网关通过 RPC 暴露向导流程（wizard.start、wizard.next、wizard.cancel、wizard.status）。 客户端（macOS app、Control UI）可以渲染向导步骤，而无需重复实现初始化逻辑。

Signal 安装（signal-cli）

向导可以从 GitHub releases 安装 signal-cli：

  • 下载对应平台的 release 资源
  • 存放到 ~/.moltbot/tools/signal-cli/<version>/
  • 写入 channels.signal.cliPath

说明：

  • JVM 构建需要 Java 21。
  • 尽量使用 native 构建（可用时）。
  • Windows 使用 WSL2；signal-cli 安装按 Linux 流程在 WSL 内执行。

向导会写哪些内容

常见写入到 ~/.moltbot/moltbot.json 的字段包括：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（例如选择了 Minimax）
  • gateway.*（mode、bind、auth、tailscale）
  • channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
  • 在提示里选择后，写入一些渠道白名单（Slack/Discord/Matrix/Microsoft Teams；可解析时会把名称解析成 ID）
  • skills.install.nodeManager
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode

moltbot agents add 会写入 agents.list[] 与可选的 bindings。

WhatsApp 凭证通常在 ~/.moltbot/credentials/whatsapp/<accountId>/。 会话通常在 ~/.moltbot/agents/<agentId>/sessions/。

部分渠道以插件形式交付；当你在向导里选择这些渠道时，会先提示安装插件（npm 或本地路径），安装后才能继续配置。

相关文档

  • macOS App 初始化：/en/docs/start/onboarding/
  • 配置参考：/zh-cn/docs/gateway/configuration/
  • 渠道：/zh-cn/docs/channels/whatsapp/、/zh-cn/docs/channels/telegram/、/zh-cn/docs/channels/discord/、/en/docs/channels/googlechat/、/en/docs/channels/signal/、/en/docs/channels/imessage/
  • Skills：/en/docs/tools/skills/、/en/docs/tools/skills-config/
文档中心展示