OpenClaw openclaw onboard 命令完全指南：交互式引导配置 Gateway、工作区、认证与渠道

openclaw onboard 是 OpenClaw 的交互式新手引导向导，用于在本机或远程完成 Gateway 网关、工作区、模型认证、渠道（Channels）与 Skills 的引导式设置。读完本文，你将掌握 quickstart 与 manual（advanced）两种流程的差异、完整的命令行参数表、本地与远程网关的配置原理，以及如何用 openclaw dashboard 跳过渠道配置直接开始聊天。文中所有行为均以当前仓库 commands/onboard.ts、wizard/setup.ts 等源码为据。

命令概览：本地或远程 Gateway 网关设置

openclaw onboard 定位于"交互式新手引导向导"，其 CLI 描述为 Interactive onboarding for the gateway, workspace, and skills（见 cli/program/register.onboard.ts）。它覆盖四个核心设置面：

• Gateway 网关：端口、绑定地址、认证方式（token / password）、Tailscale 暴露方式；
• 工作区（workspace）：Agent 的默认工作目录，默认 ~/.openclaw/workspace（对应源码中的 DEFAULT_AGENT_WORKSPACE_DIR）；
• 认证（auth）：选择模型提供方（如 OpenAI、DeepSeek、Gemini、ZAI、MiniMax 等）并写入 API Key；
• 渠道与 Skills：引导接入聊天渠道（Channels）与安装 Skills，并顺手完成搜索提供方、内部 hooks 的配置。

命令入口为 commands/onboard.ts 中的 setupWizardCommand，它会先执行运行时校验，再根据是否带 --non-interactive 分流到 commands/onboard-interactive.ts 的交互式向导或 commands/onboard-non-interactive.ts 的非交互式流程。

基本用法与流程选择

原文档给出的四种典型调用：

openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url ws://gateway-host:18789

流程说明：

• quickstart：最少提示，自动生成 Gateway 网关令牌。向导会用默认值完成大部分配置——默认端口（ws://127.0.0.1:18789，见 commands/onboard-remote.ts 中的 DEFAULT_GATEWAY_URL）、Loopback 绑定、token 认证、Tailscale 关闭，并直接进入渠道设置；
• manual：完整的端口/绑定/认证提示，是 advanced 的别名。该别名在 commands/onboard.ts 中显式归一化：const flow = opts.flow === "manual" ? "advanced" : opts.flow；
• 最快开始聊天：openclaw dashboard（打开 Control UI，无需渠道设置）。

需要注意两个流程间存在隐式约束：QuickStart 只支持本地网关。在 wizard/setup.ts 中，如果 mode === "remote" 且 flow === "quickstart"，向导会提示 "QuickStart only supports local gateways. Switching to Manual mode." 并自动切换为 advanced 流程。

完整命令行参数参考

openclaw onboard 的全部选项注册在 cli/program/register.onboard.ts，参数类型定义在 commands/onboard-types.ts。核心参数整理如下：

参数	说明	取值/默认值
--flow <flow>	引导流程	quickstart、advanced、manual（manual 是 advanced 别名）
--mode <mode>	引导模式	local、remote（QuickStart 下强制 local）
--workspace <dir>	Agent 工作区目录	默认 ~/.openclaw/workspace
--reset	引导前重置配置 + 凭据 + 会话（配合 --reset-scope full 才重置工作区）	布尔
--reset-scope <scope>	重置范围	config、config+creds+sessions（默认）、full
--non-interactive	无提示运行	布尔，需配合 --accept-risk
--accept-risk	明确接受风险声明（--non-interactive 必需）	布尔
--auth-choice <choice>	认证方式选择	见下文"认证选择"列表
--token-provider <id>	token 提供方 id（非交互式，配合 --auth-choice token）	字符串
--token <token>	token 值（非交互式）	字符串
--token-profile-id <id>	认证 profile id（非交互式）	默认 <provider>:manual
--token-expires-in <duration>	可选 token 过期时长	如 365d、12h
--secret-input-mode <mode>	API Key 持久化方式	plaintext（默认）、ref
--gateway-port <port>	Gateway 端口	整数
--gateway-bind <mode>	Gateway 绑定	loopback、tailnet、lan、auto、custom
--gateway-auth <mode>	Gateway 认证	token、password
--gateway-token <token>	Gateway token	字符串
--gateway-token-ref-env <name>	token 的 SecretRef 环境变量名	如 OPENCLAW_GATEWAY_TOKEN
--gateway-password <password>	Gateway 密码	字符串
--remote-url <url>	远程 Gateway WebSocket URL	ws:// 或 wss://
--remote-token <token>	远程 Gateway token（可选）	字符串
--tailscale <mode>	Tailscale 暴露方式	off、serve、funnel
--tailscale-reset-on-exit	退出时重置 Tailscale serve/funnel	布尔
--install-daemon / --no-install-daemon / --skip-daemon	安装/跳过 Gateway 服务	布尔
--daemon-runtime <runtime>	Gateway 服务运行时	node、bun
--skip-channels	跳过渠道设置	布尔
--skip-skills	跳过 Skills 设置	布尔
--skip-search	跳过搜索提供方设置	布尔
--skip-health	跳过健康检查	布尔
--skip-ui	跳过 Control UI / TUI 提示	布尔
--node-manager <name>	Skills 安装用的 Node 包管理器	npm、pnpm、bun
--json	输出 JSON 摘要	布尔

认证选择（--auth-choice）与 API Key 直传

BuiltInAuthChoice 枚举（见 commands/onboard-types.ts）覆盖了大量提供方，包括 openai-api-key、deepseek-api-key、gemini-api-key、moonshot-api-key、zai-api-key、xiaomi-api-key、minimax-global-api、openrouter-api-key、github-copilot、custom-api-key、skip 等，以及兼容旧版 CLI 的别名（如 oauth 是 setup-token 的旧别名）。除内置选择外，还支持通过 --custom-base-url、--custom-api-key、--custom-model-id、--custom-compatibility（openai / anthropic）接入自定义提供方。

在非交互模式下，可通过 --deepseek-api-key、--openai-api-key、--gemini-api-key 等由 commands/onboard-core-auth-flags.ts 注册的"每提供方 API Key"标志直传密钥，向导会将其按 --secret-input-mode 指定的方式（明文写入配置，或 ref 引用）持久化。

本地网关引导流程详解

以本地模式（默认）为例，交互式向导在 wizard/setup.ts 中按固定顺序执行。理解这一顺序有助于在使用时预判每一步的输入：

1. 风险确认：向导首先展示安全提示（默认是"个人 Agent，单一可信操作者边界"），需要用户确认接受；交互模式下以确认框呈现，非交互模式则要求显式 --accept-risk；
2. 读取现有配置：若 ~/.openclaw/openclaw.json 已存在，向导会汇总显示现有 workspace、model、gateway 配置，并提供三种处理方式——Use existing values（沿用）/ Update values（更新）/ Reset（重置）；若配置无效，则提示先运行 openclaw doctor 修复；
3. 选择流程与模式：默认 quickstart；高级流程下会询问 "What do you want to set up?"（本地网关 / 远程网关）；
4. 设置工作区目录；
5. 认证与默认模型：选择认证方式（含 skip 跳过）并挑选默认模型；QuickStart 流程默认采用各提供方的推荐模型；
6. Gateway 配置（端口、绑定、认证、Tailscale）；
7. 渠道设置：QuickStart 只列出声明了 quickstartAllowFrom 的渠道插件，跳过 DM 策略与确认提示，直接写入 allow-from 配置；
8. 搜索提供方（可用 --skip-search 跳过）；
9. Skills 安装（可用 --skip-skills 跳过，安装前会询问 Node 包管理器 npm/pnpm/bun）；
10. 内部 hooks：设置 /new 时注入的会话记忆 hooks；
11. 收尾：安装 Gateway 服务、健康检查、展示 Control UI 链接、shell 补全安装。

QuickStart 的网关默认值

QuickStart 的关键在于"最少提示 + 自动生成令牌"。从 wizard/setup.gateway-config.ts 的 configureGatewayForSetup 可以看到其默认策略：

• 端口：沿用现有配置或默认 18789；
• 绑定：loopback（127.0.0.1）；
• 认证：token，令牌由 commands/onboard-helpers.ts 的 randomToken() 生成（24 字节随机数转 hex，共 48 个十六进制字符）；若环境变量 OPENCLAW_GATEWAY_TOKEN 已设置则优先使用；
• Tailscale：off；
• 若此前没有网关配置，QuickStart 还会为新增网关写入默认的危险命令拒绝列表 denyCommands（见 gateway/node-command-policy.ts），并开启 loopback 下的 controlUi.allowInsecureAuth。

Manual（advanced）流程的完整提示

manual 流程则会逐一提示：

• Gateway 端口：默认 18789，输入必须是合法数字；
• Gateway bind：loopback（127.0.0.1）、lan（0.0.0.0）、tailnet（Tailscale IP）、auto（Loopback → LAN 自动回退）、custom（自定义 IPv4 地址，须通过 validateIPv4AddressInput 校验）；
• Gateway auth：token（默认，推荐）或 password；token 可留空由系统生成，也可通过 --gateway-token-ref-env 指定 SecretRef 环境变量；
• Tailscale exposure：off / serve / funnel，并询问是否在退出时重置 serve/funnel。

源码中还强制了两条安全约束：Tailscale 非 off 时绑定必须为 loopback（避免非 loopback 服务与 Tailscale 同时暴露）；funnel 模式必须使用 password 认证。这些约束由向导自动修正并在界面中提示。

远程网关模式：--mode remote

远程模式用于连接"在其他主机上运行的 Gateway"，向导只写入远程连接信息，不会在本机配置认证（凭据必须已存在于网关主机上）。对应实现见 commands/onboard-remote.ts。

openclaw onboard --mode remote --remote-url ws://gateway-host:18789

远程模式的配置项包括：

• URL 校验：必须以 ws:// 或 wss:// 开头；远程主机默认要求 wss://，仅 ws://127.0.0.1 / localhost 允许明文（典型场景是 SSH 隧道），如需在可信私网放行可使用环境变量 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1；
• Bonjour 发现：本机存在 dns-sd（macOS）或 avahi-browse（Linux）时会询问是否在局域网发现网关；发现到候选后可选"直接连接 wss://host:port"（含 TLS 指纹确认与 pin）或"SSH 隧道（loopback）"（保持 ws://127.0.0.1:18789）；
• 认证：token（推荐，默认）、password、no auth 三种；token/password 均可选择明文输入或以 SecretRef 方式引用（首选环境变量 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。

完成后的配置写入 gateway.mode: "remote" 与 gateway.remote.url，且使用非 loopback 绑定时会自动补充 Control UI 的允许来源（allowedOrigins）。

非交互式安装：--non-interactive

面向脚本与自动化场景，openclaw onboard 支持完全无提示的安装。由于 Agent 具备系统访问能力，非交互模式必须显式传入 --accept-risk，否则命令直接报错退出（见 commands/onboard.ts）：

openclaw onboard --non-interactive --accept-risk --flow quickstart
openclaw onboard --non-interactive --accept-risk --auth-choice deepseek-api-key \
  --deepseek-api-key sk-xxx --gateway-port 18789

校验规则还包括：--secret-input-mode 只允许 plaintext / ref；--reset-scope 只允许 config / config+creds+sessions / full。非交互流程在 commands/onboard-non-interactive 下按 local / remote 两个子路径实现，可用 --json 输出机器可读的安装摘要。

现有配置处理与重置

重新运行 onboard 时，向导会先汇总现有配置摘要（workspace、model、gateway.mode/port/bind、remote URL、nodeManager）。若选择"Reset"（或使用 --reset 标志），则按 --reset-scope 执行不同深度的清理，对应实现 commands/onboard-helpers.ts 的 handleReset：

• config：仅移入回收站删除配置文件 openclaw.json；
• config+creds+sessions（默认）：额外清理 credentials 目录与会话记录；
• full：再清理整个 Agent 工作区目录。

openclaw onboard --reset --reset-scope full

引导收尾：服务安装、健康检查与 Control UI

收尾阶段由 wizard/setup.finalize.ts 完成，包括：

• Gateway 服务安装：QuickStart 默认安装（Linux 下为 systemd user service，且会检查并提示启用 linger 防止登出后服务被杀）；advanced 流程询问是否安装、选择运行时（node / bun）；若服务已存在则提供 Restart / Reinstall / Skip 三选一；
• 健康检查：通过 waitForGatewayReachable 轮询 WebSocket 端点（默认 15 秒超时），成功后自动运行 openclaw health；失败时给出 openclaw gateway run、openclaw onboard --install-daemon、openclaw onboard --skip-health 等提示；
• Control UI / TUI 引导：展示 Web UI 地址（token 模式下附 #token=... 认证 URL）与 Gateway WS 地址，并提供"在 TUI 中孵化（推荐）/ 打开 Web UI / 稍后再说"三选一；最后提示 openclaw dashboard --no-open 随时重开控制台；
• shell 补全：向导会自动检查并安装当前 shell（bash / zsh / fish / powershell）的 openclaw 补全，QuickStart 流程直接安装，advanced 流程询问确认。

收尾时还会提示备份 Agent 工作区、阅读安全加固文档，并总结 Web 搜索配置状态（已配置 / 缺 Key / 被禁用时给出 openclaw configure --section web 的修复入口）。

最快开始聊天：openclaw dashboard

如果只想尽快开始对话、跳过渠道配置，直接运行：

openclaw dashboard

该命令打开 Control UI（Web 控制台，默认 http://127.0.0.1:<gateway-port>），无需先完成渠道设置即可与 Agent 聊天；无 GUI 环境下可用 --no-open 仅打印带 token 的 URL。之后随时可回到 openclaw onboard 补充渠道、搜索或 Skills 配置，或使用 openclaw configure 逐项调整。

相关资源

• macOS 桌面端的第一启动流程参考：docs/start/onboarding.md；
• 更细化的配置向导命令（openclaw setup 相关）见 docs/cli/setup.md；
• 引导后的配置修复与体检：openclaw doctor；逐项配置：openclaw configure；渠道管理：openclaw channels。

提示：本文描述的默认端口 18789、参数名与流程行为均取自当前仓库源码（commands/onboard.ts、cli/program/register.onboard.ts、wizard/setup.ts），实际使用时以你安装的 OpenClaw 版本 openclaw onboard --help 输出为准。