入职向导 (CLI)

入职向导是在 macOS、Linux 或 Windows (通过 WSL2；强烈推荐) 上设置 Clawdbot 的 推荐 方式。 它在一个引导流程中配置本地网关或远程网关连接，以及频道、技能和工作区默认设置。

主要入口点：

clawdbot onboard

后续重新配置：

clawdbot configure

推荐：设置 Brave Search API 密钥，以便智能体可以使用 web_search (web_fetch 无需密钥即可工作)。最简单的路径：clawdbot configure --section web，它将存储 tools.web.search.apiKey。文档：Web 工具。

快速开始 vs 高级

向导开始时提供 QuickStart (默认) vs Advanced (完全控制)。

QuickStart 保留默认设置：

• 本地网关 (回环)
• 工作区默认 (或现有工作区)
• 网关端口 18789
• 网关认证 令牌 (自动生成，即使在回环上)
• Tailscale 暴露 关闭
• Telegram + WhatsApp 私聊默认为 白名单 (将提示你输入电话号码)

Advanced 暴露每一步 (模式、工作区、网关、频道、守护进程、技能)。

向导做了什么

本地模式 (默认) 引导你完成：

• 模型/认证 (OpenAI Code (Codex) 订阅 OAuth, Anthropic API 密钥 (推荐) 或 setup-token (粘贴), 加上 MiniMax/GLM/Moonshot/AI Gateway 选项)
• 工作区位置 + 引导文件
• 网关设置 (端口/绑定/认证/tailscale)
• 提供商 (Telegram, WhatsApp, Discord, Google Chat, Mattermost (插件), Signal)
• 守护进程安装 (LaunchAgent / systemd 用户单元)
• 健康检查
• 技能 (推荐)

远程模式 仅配置本地客户端以连接到其他地方的网关。 它 不会 在远程主机上安装或更改任何内容。

要添加更多隔离的智能体 (独立工作区 + 会话 + 认证)，请使用：

clawdbot agents add <name>

提示：--json 不 意味着非交互模式。对于脚本，请使用 --non-interactive (和 --workspace)。

流程详情 (本地)

1. 现有配置检测

   • 如果 ~/.clawdbot/clawdbot.json 存在，选择 保留 / 修改 / 重置。
   • 重新运行向导 不会 清除任何内容，除非你显式选择 重置 (或传递 --reset)。
   • 如果配置无效或包含旧键，向导会停止并要求你在继续之前运行 clawdbot doctor。
   • 重置使用 trash (从不使用 rm) 并提供范围：
     • 仅配置
     • 配置 + 凭证 + 会话
     • 完全重置 (也移除工作区)

2. 模型/认证

   • Anthropic API 密钥 (推荐)：如果存在 ANTHROPIC_API_KEY 则使用，或提示输入密钥，然后保存以供守护进程使用。
   • Anthropic OAuth (Claude Code CLI)：在 macOS 上，向导检查 Keychain 项目 "Claude Code-credentials" (选择 "始终允许" 以便 launchd 启动时不阻塞)；在 Linux/Windows 上，如果存在 ~/.claude/.credentials.json 则复用。
   • Anthropic 令牌 (粘贴 setup-token)：在任何机器上运行 claude setup-token，然后粘贴令牌 (你可以命名它；空白 = 默认)。
   • OpenAI Code (Codex) 订阅 (Codex CLI)：如果 ~/.codex/auth.json is present, the wizard can reuse it.
   • OpenAI Code (Codex) 订阅 (OAuth)：浏览器流程；粘贴 code#state。
     • 当模型未设置或为 openai/* 时，将 agents.defaults.model 设置为 openai-codex/gpt-5.2。
   • OpenAI API 密钥：如果存在 OPENAI_API_KEY 则使用，或提示输入密钥，然后保存到 ~/.clawdbot/.env 以便 launchd 读取。
   • OpenCode Zen (多模型代理)：提示输入 OPENCODE_API_KEY (或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取)。
   • API 密钥：为你存储密钥。
   • Vercel AI Gateway (多模型代理)：提示输入 AI_GATEWAY_API_KEY。
   • 更多详情：Vercel AI Gateway
   • MiniMax M2.1：配置自动写入。
   • 更多详情：MiniMax
   • Synthetic (兼容 Anthropic)：提示输入 SYNTHETIC_API_KEY。
   • 更多详情：Synthetic
   • Moonshot (Kimi K2)：配置自动写入。
   • Kimi Code：配置自动写入。
   • 更多详情：Moonshot AI (Kimi + Kimi Code)
   • 跳过：尚未配置认证。
   • 从检测到的选项中选择默认模型 (或手动输入提供商/模型)。
   • 向导运行模型检查，如果配置的模型未知或缺少认证，会发出警告。

• OAuth 凭证存储在 ~/.clawdbot/credentials/oauth.json；认证配置文件存储在 ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json (API 密钥 + OAuth)。
• 更多详情：/concepts/oauth

3. 工作区

   • 默认 ~/clawd (可配置)。
   • 为智能体引导仪式所需的初始工作区文件提供种子。
   • 完整的工作区布局 + 备份指南：智能体工作区

4. 网关

   • 端口、绑定、认证模式、Tailscale 暴露。
   • 认证建议：即使对于回环地址也保留 Token，这样本地 WS 客户端必须进行身份验证。
   • 仅当你完全信任每个本地进程时才禁用认证。
   • 非回环绑定仍然需要认证。

5. 频道

• WhatsApp：可选的二维码登录。
• Telegram：机器人令牌。
• Discord：机器人令牌。
• Google Chat：服务账号 JSON + Webhook 受众。
• Mattermost (插件)：机器人令牌 + 基础 URL。
• Signal：可选的 signal-cli 安装 + 账号配置。
• iMessage：本地 imsg CLI 路径 + 数据库访问。
• 私聊安全：默认是配对。第一条私聊消息发送一个验证码；通过 clawdbot pairing approve <channel> <code> 批准或使用白名单。

6. 守护进程安装

   • macOS: LaunchAgent
     • 需要登录的用户会话；对于无头模式，使用自定义 LaunchDaemon (未附带)。
   • Linux (以及通过 WSL2 的 Windows): systemd 用户单元
     • 向导尝试通过 loginctl enable-linger <user> 启用保持登录，以便网关在注销后保持运行。
     • 可能会提示输入 sudo (写入 /var/lib/systemd/linger)；它会先尝试不使用 sudo。
   • 运行时选择：Node (推荐；WhatsApp/Telegram 必需)。Bun 不推荐。

7. 健康检查

   • 启动网关 (如果需要) 并运行 clawdbot health。
   • 提示：clawdbot status --deep 在状态输出中增加网关健康探测 (需要可达的网关)。

8. 技能 (推荐)

   • 读取可用技能并检查要求。
   • 让你选择一个 Node 管理器：npm / pnpm (不推荐 bun)。
   • 安装可选依赖 (有些在 macOS 上使用 Homebrew)。

9. 完成

   • 总结 + 下一步，包括具有额外功能的 iOS/Android/macOS 应用。
   • 如果未检测到 GUI，向导会打印用于控制 UI 的 SSH 端口转发指令，而不是打开浏览器。
   • 如果控制 UI 资产丢失，向导会尝试构建它们；后备方案是 pnpm ui:build (自动安装 UI 依赖)。

远程模式

远程模式配置本地客户端连接到其他地方的网关。

你将设置：

• 远程网关 URL (ws://...)
• 如果远程网关需要认证，则需要令牌 (推荐)

注意：

• 不会执行远程安装或守护进程更改。
• 如果网关仅限回环，请使用 SSH 隧道或 Tailscale 网络。
• 发现提示：
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

添加另一个智能体

使用 clawdbot agents add <name> 创建一个独立的智能体，拥有自己的工作区、 会话和认证配置文件。不带 --workspace 运行会启动向导。

它设置的内容：

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

注意：

• 默认工作区遵循 ~/clawd-<agentId>。
• 添加 bindings 来路由入站消息 (向导可以做到这一点)。
• 非交互式标志：--model、--agent-dir、--bind、--non-interactive。

非交互模式

使用 --non-interactive 来自动化或脚本化入职：

clawdbot 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 示例：

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

Z.AI 示例：

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

Vercel AI 网关示例：

clawdbot 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 示例：

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

Synthetic 示例：

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

OpenCode Zen 示例：

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

添加智能体 (非交互式) 示例：

clawdbot 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 应用、控制 UI) 可以渲染步骤，而无需重新实现入职逻辑。

Signal 设置 (signal-cli)

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

• 下载适当的发布资产。
• 将其存储在 ~/.clawdbot/tools/signal-cli/<version>/ 下。
• 将 channels.signal.cliPath 写入你的配置。

注意：

• JVM 构建需要 Java 21。
• 如果可用，将使用原生构建。
• Windows 使用 WSL2；signal-cli 安装遵循 WSL 内部的 Linux 流程。

向导写入的内容

~/.clawdbot/clawdbot.json 中的典型字段：

• agents.defaults.workspace
• agents.defaults.model / models.providers (如果选择了 Minimax)
• gateway.* (模式、绑定、认证、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

clawdbot agents add 写入 agents.list[] 和可选的 bindings。

WhatsApp 凭证位于 ~/.clawdbot/credentials/whatsapp/<accountId>/。 会话存储在 ~/.clawdbot/agents/<agentId>/sessions/。

有些频道以插件形式交付。当你在入职期间选择其中一个时，向导会提示先安装它 (npm 或本地路径) 以后才能进行配置。

相关文档

• macOS 应用入职：入职
• 配置参考：网关配置
• 提供商：WhatsApp, Telegram, Discord, Google Chat, Signal, iMessage
• 技能：技能, 技能配置