2.2 引导向导（Onboarding Wizard）

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~140,000 tokens，输出 ~10,000 tokens（本章合计）

---

OpenClaw 提供了一个交互式引导向导（Onboarding Wizard），帮助用户完成首次配置。运行一条命令即可启动：

openclaw onboard --install-daemon

这是官方推荐的配置路径——比手动编辑 openclaw.json 要安全得多，因为向导会自动处理许多容易遗漏的细节。

2.2.1 openclaw onboard 命令的源码入口

向导的源码入口位于 src/wizard/onboarding.ts。让我们从文件头部的导入开始，了解这个向导涉及的模块：

// src/wizard/onboarding.ts（关键导入）
import { ensureAuthProfileStore } from "../agents/auth-profiles.js";
import { listChannelPlugins } from "../channels/plugins/index.js";
import { promptAuthChoiceGrouped } from "../commands/auth-choice-prompt.js";
import { applyAuthChoice } from "../commands/auth-choice.js";
import { applyPrimaryModel, promptDefaultModel } from "../commands/model-picker.js";
import { setupChannels } from "../commands/onboard-channels.js";
import { setupInternalHooks } from "../commands/onboard-hooks.js";
import { setupSkills } from "../commands/onboard-skills.js";
import { configureGatewayForOnboarding } from "./onboarding.gateway-config.js";
import { finalizeOnboardingWizard } from "./onboarding.finalize.js";

从导入关系中，我们可以推断出向导的功能模块：

• Auth 配置：auth-profiles.js、auth-choice-prompt.js、auth-choice.js

• 模型选择：model-picker.js

• 通道配置：onboard-channels.js

• 钩子设置：onboard-hooks.js

• 技能安装：onboard-skills.js

• Gateway 配置：onboarding.gateway-config.js

• 最终确认：onboarding.finalize.js

2.2.2 向导流程

向导按以下顺序引导用户完成配置：

第一步：安全警告确认

向导首先展示安全警告，要求用户明确确认理解风险。这段代码体现了 OpenClaw 对安全的重视：

// src/wizard/onboarding.ts
async function requireRiskAcknowledgement(params) {
  if (params.opts.acceptRisk === true) return;

  await params.prompter.note(
    [
      "Security warning — please read.",
      "",
      "OpenClaw is a hobby project and still in beta.",
      "This bot can read files and run actions if tools are enabled.",
      "A bad prompt can trick it into doing unsafe things.",
      // ...
      "Run regularly:",
      "openclaw security audit --deep",
      "openclaw security audit --fix",
    ].join("\n"),
    "Security",
  );
}

第二步：Gateway 配置

配置 Gateway 的绑定地址、端口、认证方式。默认绑定到 127.0.0.1:18789（仅本机可访问）。如果用户需要远程访问，向导会引导配置 Tailscale 或密码认证。

第三步：模型选择（Auth + Model）

这是向导中最核心的步骤。OpenClaw 支持多种模型提供者，每种有不同的认证方式：

• Anthropic：推荐使用 Claude Pro/Max 订阅 OAuth，或 API Key

• OpenAI：支持 ChatGPT/Codex 订阅 OAuth，或 API Key

• 其他提供者：OpenRouter、Google Gemini、本地模型（Ollama）等

向导调用 promptAuthChoiceGrouped() 展示一个分组的认证选项菜单，然后用 applyAuthChoice() 将选择写入配置。模型选择通过 promptDefaultModel() 完成，用户可以从配置的提供者中选择默认模型。

第四步：通道连接

setupChannels() 引导用户连接消息平台：

• WhatsApp：扫描 QR 码连接（通过 Baileys 库）

• Telegram：输入 Bot Token

• Discord：输入 Bot Token

• Slack：输入 Bot Token + App Token

• Signal：配置 signal-cli

• 其他通道：根据需要配置

第五步：技能安装

setupSkills() 让用户选择要安装的内置技能。OpenClaw 有 52 个内置技能，向导会展示推荐的技能列表。

第六步：最终确认与守护进程安装

finalizeOnboardingWizard() 完成配置写入，如果用户指定了 --install-daemon，还会安装系统守护进程（下一节详述）。

2.2.3 交互式提示的实现：Clack Prompts 库

向导的交互式提示使用了 Clack 库（@clack/prompts）。Clack 是一个现代化的 CLI 提示库，提供了美观的终端 UI 组件。

OpenClaw 对 Clack 进行了一层抽象，定义在 src/wizard/prompts.ts 和 src/wizard/clack-prompter.ts 中。WizardPrompter 接口定义了向导需要的所有交互能力：

// src/wizard/prompts.ts（简化示意）
export interface WizardPrompter {
  note(message: string, title?: string): Promise<void>;
  confirm(options: { message: string; initialValue?: boolean }): Promise<boolean>;
  select<T>(options: {
    message: string;
    options: Array<{ label: string; value: T; hint?: string }>;
  }): Promise<T>;
  text(options: { message: string; placeholder?: string }): Promise<string>;
  // ...
}

这个抽象层使得向导可以在不同环境中运行——终端中使用 Clack 渲染美观的 UI，测试中可以注入一个模拟实现。

WizardCancelledError 是向导中用户按 Ctrl+C 取消时抛出的专用错误类型，确保向导可以优雅地退出而不是崩溃。

配置文件输出

向导完成后，会在 ~/.openclaw/ 目录下生成配置文件：

~/.openclaw/
├── openclaw.json          # 主配置（JSON5 格式）
├── credentials/           # 通道凭据
│   └── whatsapp/          # WhatsApp session 数据
├── workspace/             # 工作区
│   ├── AGENTS.md
│   ├── SOUL.md
│   └── TOOLS.md
└── agents/
    └── main/
        ├── sessions/
        │   └── sessions.json
        └── models.json

一个典型的最小配置 openclaw.json：

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}

这个看似简单的配置，背后有一套复杂的默认值系统（src/config/defaults.ts）填充了所有未指定的配置项。我们将在第 23 章深入分析配置系统。