上篇回顾

上一篇《〖OpenClaw系列〗配置文件 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 onboardOpenClaw Onboard Wizard═══════════════════════════════════════Step 1/5: Environment Diagnosis────────────────────────────────Checking existing configuration...  [✓] No existing config found at ~/.openclaw/openclaw.json  [✓] Directory ~/.openclaw/ is writableChecking environment variables...  [✓] OPENCLAW_STATE_DIR not set (will use default)  [-] No API key variables found (will configure in next step)Continue? [Y/n]: 

诊断内容清单

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

两种结果的处理

情况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篇「配置文件在哪里」章节有详细说明。

敏叔侃技术，公众号：敏叔侃技术〖OpenClaw系列〗配置文件 openclaw.json 详解

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 nowSelect [1-6]: 1Enter your Anthropic API key:  (Get one at https://console.anthropic.com/)  Key: sk-ant-api03-xxxxxxxxSelect 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

对应第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 onlyToggle selection (1-5), or 0 to continue: 1You've selected: TelegramConfiguring 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: 3You'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篇的五个模块
• 这次有了向导生成的完整示例

第三：识别自动生成项

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

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

Step 5：文件生成（Generate）

发生了什么

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

Step 5/5: Generating Configuration───────────────────────────────────Creating directory structure...  [✓] ~/.openclaw/  [✓] ~/.openclaw/workspace/Writing configuration files...  [✓] ~/.openclaw/openclaw.json  [✓] ~/.openclaw/.envCreating template files...  [✓] ~/.openclaw/workspace/SOUL.mdSetting permissions...  [✓] .env readable only by ownerConfiguration complete!Next steps:  1. Review ~/.openclaw/.env and set your API keys  2. Run: openclaw gateway start  3. Open: http://localhost:18789═══════════════════════════════════════

生成了哪些文件

启动验证

按向导提示启动：

# 设置API Key（如果你在onboard时选了手动设置）export ANTHROPIC_API_KEY="sk-ant-api03-..."export TELEGRAM_BOT_TOKEN="123456:..."# 启动Gatewayopenclaw gateway start# 浏览器打开Control UI

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

onboard vs 手动配置：怎么选？

最佳实践：两者结合

新手路径：  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/.envopenclaw gateway start

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

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

原因排查：

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

解决：

# 检查Webhook状态openclaw channel telegram check# 重新设置Webhookopenclaw 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向导把「写配置」变成了「回答问题」。回顾这五步：

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

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

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

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