Onboarding Wizard（命令行向导）

概览

clawdbot onboard

向导覆盖 macOS / Linux / Windows（WSL2）。后续重新配置可运行 clawdbot configure。

建议先配置 web_search（Brave Search API Key）：clawdbot configure --section web。

QuickStart vs Advanced

• QuickStart 默认：本地网关（loopback）、工作区默认、端口 18789、自动生成 token、关闭 Tailscale、Telegram/WhatsApp 默认 allowlist。
• Advanced 会展开全部步骤（模式、工作区、网关、渠道、后台服务、技能）。

向导会做什么

• 模型/认证：OpenAI Codex OAuth、Anthropic API Key 或 setup-token，MiniMax/GLM/Moonshot/AI Gateway 等选项
• 工作区位置与引导文件
• 网关设置（端口/bind/认证/tailscale）
• 渠道配置（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
• 后台服务（launchd/systemd user unit）
• 健康检查与推荐技能
• 远程模式仅配置本地客户端，不修改远端网关

clawdbot agents add <name>

流程细节（本地模式）

• 检测现有配置：Keep / Modify / Reset；除非选择 Reset 不会清空数据
• 配置无效会要求先运行 clawdbot doctor
• Reset 通过 trash 实现（不会直接 rm），可选范围：仅配置、配置+凭据+会话、全量（含工作区）
• Anthropic OAuth 可复用 Claude Code 的凭据；OpenAI Codex 可复用 ~/.codex/auth.json
• OpenAI OAuth 会引导浏览器并写入 auth profile；默认模型会设置为 openai-codex/gpt-5.2
• OpenAI API key 会写入 ~/.clawdbot/.env 供服务读取

远程模式

• 配置远程网关 WS 地址（ws://...）
• 若远程需要认证，设置 token
• 不对远程主机做安装或服务改动
• loopback 网关需要 SSH 隧道或 tailnet 访问

非交互模式

--json 不等同于非交互；脚本请显式使用 --non-interactive 并指定 --workspace。

向导 RPC

Gateway 暴露 wizard.start / wizard.next / wizard.cancel / wizard.status，UI 可复用向导逻辑。

Signal 安装

• 向导会下载 signal-cli release 并写入 channels.signal.cliPath
• JVM 版本需要 Java 21
• Windows 通过 WSL2 跟随 Linux 流程

向导写入内容

• agents.defaults.workspace
• agents.defaults.model / models.providers
• gateway.*（mode/bind/auth/tailscale）
• channels.*（token/allowlist 等）
• skills.install.nodeManager
• wizard.lastRun* 记录