OpenClaw04_基础设置VS向导流程

坐吃山猪

347人浏览 · 2026-03-19 17:01:08

坐吃山猪 · 2026-03-19 17:01:08 发布

OpenClaw04_基础设置VS向导流程

针对中文版本openClaw进行源码阅读，当前项目针对openClaw安装中的源码进行安装模式分析

1-参考地址

2-知识整理

1）setupCommand (基础设置)
2）onboardCommand (完整向导流程)

3-setup 命令与 onboard 命令对比

本文档说明 register.setup.ts 和 register.onboard.ts 两个注册模块的功能区别。

概述

特性	setup 命令	onboard 命令
主要用途	初始化基础配置和工作区	交互式向导，完整配置系统
命令名称	`openclaw setup`	`openclaw onboard`
交互性	非交互式为主	交互式向导
配置范围	基础配置文件和工作区	网关、认证、网络、技能等全流程

setup 命令详解

文件位置: src/cli/program/register.setup.ts

功能定位

setup 命令是系统的基础初始化工具，负责：

初始化配置文件: 创建 ~/.openclaw/openclaw.json
设置工作区: 初始化智能体工作区目录
可选向导模式: 支持通过 --wizard 参数触发完整的入驻向导

命令参数

openclaw setup [options]

参数	说明
`--workspace <dir>`	指定智能体工作区目录（默认：~/clawd）
`--wizard`	启用交互式引导向导模式
`--non-interactive`	静默模式运行向导
`--mode <mode>`	工作模式：local/remote
`--remote-url <url>`	远程网关 WebSocket 地址
`--remote-token <token>`	远程网关身份验证令牌

执行逻辑

用户执行 setup 命令
    ↓
检查是否指定 --wizard 或相关选项
    ↓
┌─────────────┬────────────────┐
│ 是 (向导模式)   │ 否 (标准模式)    │
├─────────────┼────────────────┤
│ 调用 onboardCommand  │ 调用 setupCommand  │
│ (完整入驻流程) │ (基础环境设置)   │
└─────────────┴────────────────┘

适用场景

首次安装: 快速初始化基础配置
工作区迁移: 更改工作区目录位置
配置重置: 重新初始化配置文件
向导入口: 通过 --wizard 进入完整配置流程

onboard 命令详解

文件位置: src/cli/program/register.onboard.ts

功能定位

onboard 命令是系统的完整入驻向导，提供交互式配置体验，涵盖：

工作区配置: 设置 Agent 工作区目录
认证设置: 配置 AI 服务商密钥（支持多种服务商）
网关配置: 网络端口、绑定模式、认证方式
网络隧道: Tailscale 集成配置
守护进程: 网关服务安装与运行时选择
组件管理: 频道、技能、健康检查等

命令参数

openclaw onboard [options]

基础选项

参数	说明
`--workspace <dir>`	Agent 工作区目录
`--reset`	重置配置、凭证、会话及工作区
`--non-interactive`	静默模式运行
`--accept-risk`	确认已知悉风险（非交互模式必需）
`--flow <flow>`	向导流程：quickstart/advanced/manual
`--mode <mode>`	连接模式：local/remote

认证选项

参数	说明
`--auth-choice <choice>`	认证方式选择（token/多种 API Key）
`--anthropic-api-key <key>`	Anthropic API 密钥
`--openai-api-key <key>`	OpenAI API 密钥
`--moonshot-api-key <key>`	Moonshot API 密钥
`--gemini-api-key <key>`	Gemini API 密钥
`--minimax-api-key <key>`	MiniMax API 密钥
…	（支持 10+ 种 AI 服务商）

网关配置选项

参数	说明
`--gateway-port <port>`	网关监听端口
`--gateway-bind <mode>`	绑定模式：loopback/tailnet/lan/auto/custom
`--gateway-auth <mode>`	认证模式：token/password
`--gateway-token <token>`	网关 Token
`--gateway-password <password>`	网关密码

Tailscale 选项

参数	说明
`--tailscale <mode>`	Tailscale 模式：off/serve/funnel
`--tailscale-reset-on-exit`	退出时重置状态

守护进程选项

参数	说明
`--install-daemon`	安装网关服务
`--no-install-daemon`	跳过网关服务安装
`--skip-daemon`	跳过网关服务安装
`--daemon-runtime <runtime>`	运行时：node/bun

流程控制选项

参数	说明
`--skip-channels`	跳过频道设置
`--skip-skills`	跳过技能设置
`--skip-health`	跳过健康检查
`--skip-ui`	跳过控制面板 UI 交互
`--node-manager <name>`	节点管理器：npm/pnpm/bun
`--json`	输出 JSON 格式摘要

适用场景

首次部署: 完整的系统初始化和配置
高级配置: 需要详细配置网关、认证、网络等
非交互部署: 通过参数实现自动化部署
组件管理: 精确控制哪些组件需要安装配置

关系与区别

命令关系

┌─────────────────────────────────────────────────────┐
│                    setup 命令                        │
│         (基础初始化入口)                              │
└───────────────────┬─────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
    标准 mode                 Wizard mode
        │                       │
        ▼                       ▼
┌───────────────┐    ┌─────────────────────┐
│  setupCommand │    │  onboardCommand     │
│  (基础设置)    │    │  (完整向导流程)       │
└───────────────┘    └─────────────────────┘
                                  │
                                  ▼
                          ┌─────────────────┐
                          │   onboard 命令    │
                          │ (直接调用)        │
                          └─────────────────┘

功能对比

维度	setup	onboard
命令层级	上层入口	专项命令
配置深度	基础	深度
参数数量	6 个	40+ 个
交互性	低	高
灵活性	中等	高
学习曲线	简单	较复杂

使用建议

新手用户: 从 openclaw onboard 开始，使用交互式向导
快速开始: 使用 openclaw setup --wizard 进入向导
仅初始化配置: 使用 openclaw setup（不带向导参数）
自动化部署: 使用 openclaw onboard --non-interactive 配合参数
高级定制: 使用 openclaw onboard 的详细参数进行精确配置

示例

setup 命令示例

# 基础初始化
openclaw setup

# 指定工作区目录
openclaw setup --workspace ~/my-workspace

# 启动向导模式
openclaw setup --wizard

# 远程网关模式
openclaw setup --mode remote --remote-url ws://example.com

onboard 命令示例

# 交互式向导
openclaw onboard

# 快速开始模式
openclaw onboard --flow quickstart

# 非交互模式配置
openclaw onboard --non-interactive --accept-risk \
  --anthropic-api-key sk-ant-xxx \
  --gateway-port 18789 \
  --gateway-bind loopback

# 跳过某些步骤
openclaw onboard --skip-channels --skip-skills

# 完整自动化部署
openclaw onboard --non-interactive --accept-risk \
  --workspace ~/clawd \
  --auth-choice anthropic-api-key \
  --anthropic-api-key sk-ant-xxx \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --gateway-auth token \
  --gateway-token my-token \
  --install-daemon \
  --daemon-runtime bun \
  --tailscale serve \
  --skip-ui