〖OpenClaw系列〗onboard新手引导全流程拆解

上篇回顾

上一篇《配置文件 openclaw.json 详解》，我们把OpenClaw的神经中枢拆成了五个模块——agents、gateway、channels、session、tools。你现在已经知道，配好这个文件AI就能跑起来。

但说实话，盯着那几百行JSON5配置，新手很容易劝退。有没有更友好的方式？

有。OpenClaw自带的 onboard 命令，就是一个交互式向导。回答几个问题，10分钟出一套可用配置。这篇我们把这10分钟拆成每一步，让你既会用向导，又明白向导在背后帮你写了什么配置。

本文定位：onboard向导的完整操作手册，同时建立与第3篇文章的映射关系。读完这篇，你会用向导快速上手；后续深入时，知道去哪里查配置细节。

先上全景：onboard的五步旅程

看一眼这张图，明白onboard的全流程：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

这张图分两部分：

上半部分（彩色卡片）：onboard的五个交互步骤

  • 蓝色 Step 1：环境诊断，检查现有配置
  • 绿色 Step 2：模型选择，配置AI大脑
  • 紫色 Step 3：渠道选择，配置消息入口
  • 橙色 Step 4：配置预览，确认生成内容
  • 红色 Step 5：文件生成，写入openclaw.json

下半部分：每步生成的配置如何映射到 openclaw.json 的模块

下面的文章沿着这五步展开，每一步都告诉你：向导问了什么？你回答了什么？背后生成了什么配置？

Step 1：环境诊断（Diagnose）

发生了什么

运行 openclaw onboard，第一步不是让你填配置，而是检查你的环境：

$ openclaw onboard

OpenClaw Onboard Wizard
═══════════════════════════════════════

Step 1/5: Environment Diagnosis
────────────────────────────────
Checking existing configuration...
  [✓] No existing config found at ~/.openclaw/openclaw.json
  [✓] Directory ~/.openclaw/ is writable

Checking environment variables...
  [✓] OPENCLAW_STATE_DIR not set (will use default)
  [-] No API key variables found (will configure in next step)

Continue? [Y/n]:

诊断内容清单

onboard在后台检查了这些项目：

检查项 目的 对应第3篇模块
现有配置文件是否存在 避免覆盖已有配置 全局检查
~/.openclaw/ 目录是否可写 确保能写入新配置 配置文件位置
OPENCLAW_STATE_DIR 环境变量 自定义状态目录 环境变量覆盖
API Key变量是否已设置 提示是否使用已有Key env/SecretRef

两种结果的处理

情况A：全新环境（无现有配置）

  • onboard显示绿色勾，直接进入下一步
  • 这是最常见的新手场景

情况B：已有配置存在

  [!] Existing config found at ~/.openclaw/openclaw.json
  Options:
    1) Backup existing and create new
    2) Merge with existing (advanced)  
    3) Cancel
  • 向导会询问如何处理已有配置
  • 新用户选1（备份并重写），老用户可选2（合并）

对应第3篇：这篇提到的配置文件路径 ~/.openclaw/openclaw.json，在第3篇「配置文件在哪里」章节有详细说明。

Step 2：模型选择（Model）

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

发生了什么

诊断通过后，onboard开始配置AI的大脑——模型：

Step 2/5: Model Selection
────────────────────────

Choose your AI model provider:

  [1] Anthropic (Claude) - Recommended
  [2] OpenAI (GPT)
  [3] Groq (Fast inference)
  [4] Together AI (Open source)
  [5] Local model (Ollama)
  [6] Skip for now

Select [1-6]: 1

Enter your Anthropic API key:
  (Get one at https://console.anthropic.com/)
  Key: sk-ant-api03-xxxxxxxx

Select model:
  [1] claude-sonnet-4-6 (default, balanced)
  [2] claude-opus-4-7 (powerful, higher cost)
  [3] claude-haiku-3-5 (fast, low cost)

Select [1-3]: 1

向导背后的配置逻辑

你的每一步选择，都对应生成一段配置：

选择Provider → 生成 providers 配置

{
  models: {
    providers: {
      anthropic: {
        apiKey: {
          source: "onboard-interactive",  // 向导自动记录
          // 实际Key被安全存储，不在配置文件中显式保存
        },
        defaultOptions: {
          maxTokens: 4096,
          temperature: 0.7,
        },
      },
    },
  },
}

选择模型 → 生成 alias 和 agents 配置

{
  models: {
    "anthropic/claude-sonnet-4-6": {
      alias: "Sonnet",
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "Sonnet",  // 使用别名
      },
    },
  },
}

安全提示：API Key去哪了

你可能会问：我输入的API Key保存在哪？

onboard提供三种存储方式供你选择：

How would you like to store your API key?
  [1] Save to ~/.openclaw/.env (default, local file)
  [2] Set as environment variable (recommended for production)
  [3] Skip saving (you'll need to set it manually)

Select [1-3]: 1
存储方式 位置 安全性 适用场景
.env 文件 ~/.openclaw/.env 中 开发测试
环境变量 Shell environment 高 生产服务器
手动设置 暂不保存 - 后续手动配置

对应第3篇：API Key的安全管理，在第3篇「Secret管理」章节有详尽论述，包括 env/SecretRef/.env 三种方式的对比。

Step 3：渠道选择（Channel）

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

发生了什么

模型配好后，onboard询问你想接入的沟通渠道：

Step 3/5: Channel Selection
────────────────────────────

Select messaging platforms to connect:
  (You can add more later)

  [✓] [1] Telegram
  [ ] [2] WhatsApp Business
  [ ] [3] Discord
  [ ] [4] Slack
  [ ] [5] 飞书 (Lark)
  [ ] [6] Skip for now - Control UI only

Toggle selection (1-5), or 0 to continue: 1

You've selected: Telegram

Configuring Telegram:
  Bot Token: (Get from @BotFather on Telegram)
  Enter your bot token: 123456:ABC-DEF1234...

  Private message policy:
    [1] pairing - Require pairing code (secure, recommended)
    [2] allowlist - Only allow specific users
    [3] open - Allow anyone (not recommended)
    [4] disabled - No private messages
  
  Select [1-4]: 1

渠道配置生成

Telegram的选择生成了这段配置：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",  // 引用环境变量
      dmPolicy: "pairing",  // 你选的私信策略
      allowFrom: [],        // pairing模式下为空，动态维护
      groups: {
        "*": { requireMention: true },  // 群组需@才回复
      },
    },
  },
}

多渠道的选择策略

onboard允许你一次配置多个渠道：

Toggle selection (1-5), or 0 to continue: 3
You've selected: Telegram, Discord

这样生成的配置就包含多个channel：

{
  channels: {
    telegram: { /* 配置 */ },
    discord: { /* 配置 */ },
  },
}

对应第3篇：dmPolicy四种模式的详细解释，在第3篇「第三条紫带：channels」章节有完整的安全策略分析。

Step 4：配置预览（Review）

发生了什么

向导汇总前几步的选择，展示最终配置：

Step 4/5: Configuration Preview
──────────────────────────────

Here's what will be generated:

File: ~/.openclaw/openclaw.json
─────────────────────────────────────
{
  agents: {
    defaults: {
      model: { primary: "Sonnet" },
      workspace: "~/.openclaw/workspace",
      heartbeat: { every: "30m", target: "last" },
    },
  },
  models: {
    providers: {
      anthropic: {
        apiKey: { source: "env", id: "ANTHROPIC_API_KEY" },
        defaultOptions: { maxTokens: 4096, temperature: 0.7 },
      },
    },
    "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      /* ... */
    },
  },
  session: {
    dmScope: "per-channel-peer",
    reset: { mode: "daily", atHour: 4 },
  },
}

Additional files:
  - ~/.openclaw/.env (API keys)
  - ~/.openclaw/workspace/ (created)
  - ~/.openclaw/workspace/SOUL.md (template)

Proceed? [Y/n/Edit]:

预览页的三重作用

第一：确认配置正确

  • 在写入前最后检查
  • 发现错误可输入Edit返回修改

第二：学习配置结构

  • 对应回第3篇的五个模块
  • 这次有了向导生成的完整示例

第三：识别自动生成项

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

注意到这些你没选但自动出现的配置了吗？

自动生成项 作用 对应第3篇
workspace Agent工作目录 第一条蓝带
heartbeat 定时自检 第一条蓝带
session.dmScope 会话隔离 第四条橙带
session.reset 定时重置会话 第四条橙带

这是onboard的"安全默认值"策略——为你补齐新手不易察觉但生产环境需要的配置。

Step 5：文件生成（Generate）

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

发生了什么

确认后，向导执行实际的文件写入：

Step 5/5: Generating Configuration
───────────────────────────────────

Creating directory structure...
  [✓] ~/.openclaw/
  [✓] ~/.openclaw/workspace/

Writing configuration files...
  [✓] ~/.openclaw/openclaw.json
  [✓] ~/.openclaw/.env

Creating template files...
  [✓] ~/.openclaw/workspace/SOUL.md

Setting permissions...
  [✓] .env readable only by owner

Configuration complete!

Next steps:
  1. Review ~/.openclaw/.env and set your API keys
  2. Run: openclaw gateway start
  3. Open: http://localhost:18789

═══════════════════════════════════════

生成了哪些文件

文件 内容 作用
~/.openclaw/openclaw.json 主配置（JSON5） OpenClaw的神经中枢
~/.openclaw/.env API Key 敏感信息隔离存储
~/.openclaw/workspace/ 工作目录 各Agent的SOUL.md、数据
~/.openclaw/workspace/SOUL.md 系统提示词模板（Agent人设定义文件） Agent人设定义起点

启动验证

按向导提示启动：

# 设置API Key（如果你在onboard时选了手动设置）
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export TELEGRAM_BOT_TOKEN="123456:..."

# 启动Gateway
openclaw gateway start

# 浏览器打开Control UI

如果看到 Gateway ready on http://localhost:18789，恭喜你，配置成功！

onboard vs 手动配置：怎么选？

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

场景 推荐方式 理由
第一次使用OpenClaw onboard向导 快速上手，建立感性认识
配置少量渠道（1-2个） onboard向导 效率最高，不易出错
需要深入定制 手动配置 灵活度更高，可配onboard未覆盖的项
已有配置需要修改 手动配置 onboard目前不支持增量修改
团队标准化部署 手动+模板 便于版本控制、CI/CD集成

最佳实践：两者结合

新手路径：
  onboard起步 → Control UI体验 → 阅读第3篇深入理解 → 手动调优

老手路径：
  复制已有配置模板 → 手动修改 → 使用CLI快速调参

踩坑

坑1：onboard完成后启动失败，报错API Key不存在

现象：

Error: ANTHROPIC_API_KEY environment variable not found

原因：你在onboard时选了"Set as environment variable"，但没在当前shell中设置。

解决：

# 方案1：手动设置
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 方案2：从.env文件加载
source ~/.openclaw/.env
openclaw gateway start

坑2：Telegram Bot已配置，但收不到消息

现象：Bot在线，但私聊/群消息无响应

原因排查：

  1. Webhook未设置：向导向导能配置Bot Token，但Webhook需要手动或通过openclaw设置
  2. 隐私模式：@BotFather创建时开启了隐私模式，Bot看不到群消息
  3. 未开始对话：用户需要先私聊Bot开始对话，否则消息发送失败

解决：

# 检查Webhook状态
openclaw channel telegram check

# 重新设置Webhook
openclaw channel telegram set-webhook

坑3：.env文件权限过于开放

现象：

Warning: .env file is readable by others

原因：onboard生成的.env文件权限可能受系统umask影响

解决：

chmod 600 ~/.openclaw/.env

坑4：想修改onboard生成的配置，但不知道哪些能改

现象：不确定手动修改哪些配置不会破坏onboard设置

安全清单：可以放心手动修改的项

  • agents.defaults.model.options.{temperature,maxTokens} ✓
  • channels.{name}.dmPolicy ✓
  • session.reset.* ✓
  • gateway.{port,bind} ✓ (需重启)

建议保留onboard原始值的项

  • models.providers.{name}.apiKey 的结构 ✗
  • channels.{name}.botToken 的变量引用格式 ✗

坑5：onboard生成的workspace下没有skills目录

现象：想用Skill系统，但workspace里找不到skills位置

原因：onboard默认不创建skills目录，首次使用skill时自动创建

解决：

# 手动创建
mkdir -p ~/.openclaw/workspace/skills

# 或使用CLI自动创建
openclaw skill init

FAQ

Q：onboard生成的配置可以和其他配置共存吗？

A：可以，但需注意：

  • 不能有多个openclaw.json（主配置会覆盖）
  • 可用$include拆分配置，但onboard生成的是单文件
  • 建议先用onboard跑通，再学习第3篇的$include拆分

Q：onboard时选错了渠道，能重新运行吗？

A：可以。运行前会提示是否备份现有配置。选Backup existing and create new，然后重新选择即可。旧配置会备份为openclaw.json.bak。

Q：onboard生成的配置支持热重载吗？

A：支持。大部分配置修改后自动生效，除了gateway.port等网络配置。详见第3篇「配置热重载」章节。

Q：onboard没有我想要的渠道选项，怎么办？

A：onboard只包含主流渠道。小众渠道（如Matrix、iMessage）需手动配置。参考第3篇channels模块的通用配置结构。

Q：团队部署可以用onboard吗？

A：不推荐。团队部署更适合用：

  1. 版本控制管理配置模板
  2. 环境变量注入敏感信息
  3. CI/CD流水线自动部署

onboard更适合个人快速上手。

总结

onboard向导把「写配置」变成了「回答问题」。回顾这五步：

步骤 向导收集 生成配置 对应第3篇模块
Step 1 环境状态 诊断报告 全局检查
Step 2 Provider+模型+API Key models.providers + agents.model 第一条蓝带
Step 3 渠道选择+Token channels.* 第三条紫带
Step 4 确认 完整预览 五模块汇总
Step 5 确认 openclaw.json + .env + workspace/ -

onboard的本质：用交互式对话，帮你完成了第3篇讲的五模块配置的"最小可用版本"。

下一步：配置已生成，Gateway已启动。但你可能想知道——这背后的Gateway是怎么工作的？它如何监听端口、处理消息？下一篇我们拆解Gateway的完整生命周期。

本文是系列第4篇，前序文章：第3篇：配置文件详解

📌 觉得有用？点个「在看」 👇
👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货
⭐ 收藏这篇文章，10分钟快速搭起你的第一个AI助手

# 人工智能
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

28.Agent 框架对比：LangChain / LlamaIndex / AutoGen / CrewAI

avatar AI编程社区
cover

Gemini中的表格怎么导出？别说你会复制粘贴！我们测了4种方案，发现“AI导出鸭”才是终极答案

avatar AI编程社区

vibecoding起步注意点:Claude 操作飞书文档、表格和群聊的完整流程总结

可以实现。

avatar AI编程社区