1. 本期目标

上一期我们分析了 OpenClaw 的 CLI 启动链路：用户输入 openclaw 命令后，程序会先经过 entry.ts、run-main、Commander Program 构建和命令注册流程，然后再进入具体命令逻辑。

这一期继续往下看，重点分析两个最基础的初始化命令：

openclaw setup
openclaw onboard

它们的作用都和“第一次把 OpenClaw 配起来”有关，但定位并不完全相同。官方 CLI 文档中明确区分了这几个命令：openclaw setup 负责创建基础配置和 workspace，openclaw onboard 是完整的引导式首次配置流程，而 openclaw configure 用于对已有配置做定向修改。(OpenClaw)

本期主要解决几个问题：

1. setup 和 onboard 有什么区别？
2. setup 命令在源码中做了哪些事情？
3. openclaw.json 是如何被创建和更新的？
4. workspace 是什么，里面会生成哪些文件？
5. sessions 目录为什么也会在 setup 阶段创建？
6. onboard 为什么比 setup 更完整？
7. 后续源码阅读应该如何从配置初始化继续深入？

---

2. 先区分 setup 和 onboard

从使用者角度看，可以先这样理解：

openclaw setup：
创建最基础的本地配置和 agent workspace。

openclaw onboard：
完整引导用户完成 Gateway、模型认证、workspace、channels、skills 和健康检查等配置。

openclaw configure：
在已有配置基础上做局部修改。

官方文档也明确写到，openclaw setup 初始化 baseline config 和 agent workspace；如果带上某些 onboarding 相关参数，它也可以触发 wizard。而 openclaw onboard 是完整的 guided onboarding，适合用户希望 OpenClaw 一步步引导完成模型认证、Gateway、渠道、技能和健康检查的情况。(OpenClaw) (OpenClaw)

所以，这三个命令的关系可以画成：

第一次最小初始化
    ↓
openclaw setup

第一次完整引导配置
    ↓
openclaw onboard

已有配置上的局部修改
    ↓
openclaw configure

如果你只是为了源码调试，通常先理解 setup 就够了；如果你想理解完整产品初始化体验，就需要继续看 onboard。

---

3. setup 命令在 CLI 体系中的位置

上一期讲到，OpenClaw 的 CLI 命令是通过 command descriptor 注册进来的。

在 core-command-descriptors.ts 中，setup 被描述为：

Initialize local config and an agent workspace

onboard 被描述为：

Interactive onboarding for gateway, workspace, and skills

configure 被描述为：

Interactive configuration for credentials, channels, gateway, and agent defaults

这些描述符说明，OpenClaw 把 setup、onboard、configure 放在同一组“初始化 / 配置”命令体系中，但它们解决的问题层次不同。(GitHub)

可以理解为：

setup：
偏底层，负责把本地运行需要的基础目录和基础配置建起来。

onboard：
偏用户体验，负责把第一次使用 OpenClaw 的完整流程串起来。

configure：
偏维护，负责后续配置调整。

这也提醒我们：读源码时不要只看命令名字，要把它放到 CLI 命令体系里理解。

---

4. setup 源码入口

openclaw setup 对应的核心实现位于：

src/commands/setup.ts

从源码可以看到，setupCommand 的主要逻辑包括：

1. 解析用户传入的 workspace 参数
2. 创建或读取配置 IO
3. 读取已有 openclaw.json
4. 计算最终 workspace 路径
5. 构造 next config
6. 必要时写回配置文件
7. 创建 / 检查 agent workspace
8. 创建 / 检查 sessions 目录

源码中 setupCommand 会读取现有配置文件，如果文件不存在或关键字段需要更新，就生成新的配置并写回；之后调用 ensureAgentWorkspace 确保 workspace 存在，并创建 sessions 目录。(GitHub)

这条链路可以概括成：

openclaw setup
    ↓
读取现有配置
    ↓
计算 workspace
    ↓
更新 agents.defaults.workspace
    ↓
补充 gateway.mode
    ↓
确保 workspace 存在
    ↓
确保 sessions 目录存在

---

5. setup 第一步：确定 workspace 路径

workspace 是 OpenClaw 中非常重要的概念。

简单来说，源码仓库是程序代码所在的位置，而 workspace 是用户自己的 agent 工作区。前面第二期已经提到，个人配置和工作区应该放在 ~/.openclaw 下面，而不是直接写进源码仓库。

setupCommand 会优先读取命令行传入的 --workspace 参数。如果用户没有传入，就查看已有配置中的 agents.defaults.workspace。如果配置里也没有，就使用默认 workspace 目录。源码中的逻辑可以抽象为：

命令行 --workspace
    ↓ 如果没有
已有配置 agents.defaults.workspace
    ↓ 如果没有
默认 workspace 目录

官方 setup 文档也说明，--workspace <dir> 用于设置 agent workspace 目录，默认是 ~/.openclaw/workspace，并且会存储到 agents.defaults.workspace。(OpenClaw)

所以 setup 的第一件关键事情，就是把“OpenClaw 的工作区在哪里”确定下来。

---

6. setup 第二步：创建或更新 openclaw.json

OpenClaw 的主配置文件通常是：

~/.openclaw/openclaw.json

官方配置文档说明，OpenClaw 会从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置；如果文件不存在，就使用安全默认值。(OpenClaw)

setupCommand 会读取这个配置文件，然后构造一个新的 next 配置对象。它至少会关注两个地方：

agents.defaults.workspace
gateway.mode

源码逻辑大概可以理解成：

nextConfig = {
  ...existingConfig,

  agents: {
    ...existingConfig.agents,
    defaults: {
      ...existingConfig.agents.defaults,
      workspace: 最终确定的 workspace 路径
    }
  },

  gateway: {
    ...existingConfig.gateway,
    mode: existingConfig.gateway.mode ?? "local"
  }
}

也就是说，setup 并不是粗暴覆盖整个配置文件，而是在已有配置基础上补齐必要字段。源码中也能看到，它只有在配置不存在、workspace 变化或 gateway.mode 需要补齐时，才会写回配置。(GitHub)

这体现出一个比较重要的工程习惯：

初始化命令应该尽量补齐缺失配置，
而不是随意覆盖用户已有配置。

---

7. 为什么要设置 gateway.mode？

在 setupCommand 中，除了 workspace，另一个关键字段是：

gateway.mode

源码中默认会把它设置为：

local

这和 OpenClaw 的 local-first 定位有关。第一次本地初始化时，系统默认把 Gateway 视为本地模式，而不是远程 Gateway。onboard 文档中也提到，本地 onboarding 会把 gateway.mode="local" 写入配置；远程 onboarding 则只写入远程 Gateway 的连接信息。(OpenClaw)

所以这里可以这样理解：

workspace 决定 Agent 的工作区在哪里；
gateway.mode 决定 OpenClaw 连接本地 Gateway 还是远程 Gateway。

这两个字段是 OpenClaw 能正常运行的基础。

---

8. setup 第三步：确保 workspace 存在

配置写好之后，setupCommand 会调用：

ensureAgentWorkspace(...)

这个函数位于：

src/agents/workspace.ts

从源码可以看到，workspace 模块定义了一组默认文件名，包括：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
BOOTSTRAP.md

这些文件是 OpenClaw workspace 初始化时的重要模板文件。ensureAgentWorkspace 会创建 workspace 目录，并在需要时写入缺失的 bootstrap 文件。(GitHub)

可以先这样理解这些文件：

AGENTS.md：
描述 agent 的整体行为或多 agent 相关规则。

SOUL.md：
更偏 agent 的长期身份、风格或核心行为倾向。

TOOLS.md：
描述工具使用相关约束或说明。

IDENTITY.md：
描述 agent 身份信息。

USER.md：
描述用户相关信息或偏好。

HEARTBEAT.md：
描述周期性状态、心跳或维护类行为。

BOOTSTRAP.md：
首次启动或首次配置时的引导文件。

这里不一定每个文件都需要马上深入，但要先知道：OpenClaw 的 workspace 不只是一个空目录，而是一组会被 Agent 读取和使用的行为文件、身份文件和引导文件。

---

9. workspace 为什么不等于源码目录？

这是初学者很容易混淆的点。

OpenClaw 至少有三个层面的路径：

源码目录：
存放 OpenClaw 程序代码，例如 src、extensions、skills、ui。

配置目录：
存放 openclaw.json、credentials、状态文件等。

workspace：
存放 agent 的工作文件、身份文件、工具说明、用户偏好和长期记忆相关文件。

这三者的边界可以写成：

openclaw 源码仓库
    ↓
研究 OpenClaw 如何实现

~/.openclaw/openclaw.json
    ↓
控制 OpenClaw 如何运行

~/.openclaw/workspace
    ↓
描述 Agent 如何表现、如何工作、如何记住用户上下文

这样设计的好处是，用户可以更新源码，而不影响自己的长期配置和工作区。官方配置文档也强调，openclaw.json 可以直接编辑，Gateway 会监听配置文件并自动应用变化；同时配置必须符合 schema，未知字段或类型错误会导致 Gateway 拒绝启动。(OpenClaw)

---

10. setup 第四步：创建 sessions 目录

setupCommand 除了配置文件和 workspace，还会处理 sessions 目录。

源码中可以看到，在 workspace 初始化后，它会调用 resolveSessionTranscriptsDir 获取 sessions 相关目录，然后通过 fs.mkdir(..., { recursive: true }) 确保目录存在。(GitHub)

这说明 OpenClaw 在初始化时就考虑到了“会话记录”这个问题。

因为 OpenClaw 不是一次性问答程序，它是一个长期运行的个人助手。用户和 Agent 的对话会被组织成不同 session，后续可能用于上下文恢复、历史查询、调试或多渠道会话隔离。

所以 setup 最后创建 sessions 目录，其实是在为后续 Agent 运行做准备：

配置文件：
告诉系统怎么运行。

workspace：
告诉 Agent 怎么表现。

sessions：
保存 Agent 与用户的交互历史。

这三者共同构成了 OpenClaw 本地运行的基础状态。

---

11. setup 的输出意味着什么？

当 openclaw setup 正常执行时，通常会输出类似下面的信息：

Wrote ~/.openclaw/openclaw.json
Workspace OK: ~/.openclaw/workspace
Sessions OK: ~/.openclaw/agents/main/sessions

这些输出不是简单提示，而是对应三类初始化结果：

Wrote / Config OK：
配置文件已经创建或已有配置可用。

Workspace OK：
agent workspace 已经创建或已有 workspace 可用。

Sessions OK：
会话目录已经创建或已有 sessions 目录可用。

如果你后续调试 OpenClaw，遇到 agent 无法启动、配置不生效、workspace 文件没有加载、session 历史异常，可以先回到这三个位置检查。

---

12. onboard 为什么比 setup 更完整？

setup 只解决“基础文件和目录存在”的问题。

而 onboard 解决的是“用户第一次使用 OpenClaw 时如何完整配置系统”的问题。

官方 onboard 文档说明，openclaw onboard 是完整引导式 onboarding，用于配置 local 或 remote Gateway，并覆盖模型认证、workspace、Gateway、channels、skills 和 health 等流程。(OpenClaw)

也就是说：

setup：
只负责地基。

onboard：
负责从地基到可用系统的一整套装修流程。

onboard 支持不同 flow，例如：

quickstart：
最少提示，快速完成。

manual：
完整提示，适合手动配置端口、绑定地址和认证。

import：
从已有 agent 系统迁移。

官方文档中也列出了这些 flow 类型：quickstart 是 minimal prompts，manual 是完整提示，import 会运行迁移 provider 并在确认后应用计划。(OpenClaw)

---

13. onboard 的交互式和非交互式模式

onboard 不只是交互式向导，也支持非交互模式。

例如官方文档中给出了类似下面的用法：

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

还支持远程 Gateway、SecretRef、Gateway token、跳过 health、跳过 bootstrap 等配置。(OpenClaw)

这说明 OpenClaw 的初始化既面向普通用户，也面向自动化部署场景：

普通用户：
openclaw onboard
一步步选择和确认。

自动化脚本：
openclaw onboard --non-interactive ...
直接写入配置并完成初始化。

从源码阅读角度看，onboard 比 setup 更复杂，因为它要处理用户输入、认证方式、模型 provider、Gateway 模式、channel、skills、health check 甚至迁移逻辑。

---

14. setup 与 onboard 的调用关系

官方 setup 文档提到，openclaw setup 在带有 onboarding 相关 flag 时，也会运行 wizard。例如 --wizard、--non-interactive、--mode、--import-from、--remote-url、--remote-token 等参数都会触发 wizard。(OpenClaw)

所以可以理解为：

普通 setup：
只做基础初始化。

setup + onboarding 参数：
进入更完整的 onboarding 流程。

onboard：
直接进入完整 onboarding 流程。

这是一种比较灵活的 CLI 设计。

它既保留了简单命令：

openclaw setup

也支持用户从 setup 入口进入更复杂流程：

openclaw setup --wizard
openclaw setup --non-interactive --mode remote --remote-url ...

---

15. 配置文件的严格校验

OpenClaw 的配置系统不是“随便写 JSON 就行”。

官方配置文档明确说明，OpenClaw 只接受完全匹配 schema 的配置。未知字段、类型错误或非法值会导致 Gateway 拒绝启动；配置失败时，通常只有 doctor、logs、health、status 等诊断命令可用。(OpenClaw)

这对源码学习很重要。

因为后续我们如果手动修改 ~/.openclaw/openclaw.json，必须注意：

字段名要正确；
类型要正确；
结构要符合 schema；
不要随便添加未知字段；
修改失败后先用 openclaw doctor 检查。

这也解释了为什么 OpenClaw 需要 config get/set/unset/validate/schema 等命令。它不是简单读写配置文件，而是围绕 schema 建立了一套可验证的配置管理机制。

---

16. 从 setup 看 OpenClaw 的本地状态模型

通过 setup 命令，我们可以初步看到 OpenClaw 的本地状态模型：

~/.openclaw/openclaw.json
    ↓
系统配置

~/.openclaw/workspace
    ↓
Agent 工作区和行为文件

~/.openclaw/agents/<agentId>/sessions
    ↓
会话历史与 transcript

~/.openclaw/credentials
    ↓
渠道、模型或认证状态

/tmp/openclaw
    ↓
运行日志

这一期重点看前三个：

config
workspace
sessions

它们是后续理解 Agent Runtime 的前置基础。

后面当我们分析 openclaw agent --message "Hello" 时，就会发现 Agent 处理一次消息之前，需要读取配置、找到 workspace、加载相关 bootstrap 文件，并决定使用哪个 session 保存上下文。

---

17. 本期源码阅读建议

这一期建议重点看四类文件：

src/commands/setup.ts
    ↓
理解 setupCommand 如何创建配置、workspace 和 sessions。

src/agents/workspace.ts
    ↓
理解 workspace 如何创建，bootstrap 文件有哪些。

src/config/config.ts
    ↓
理解配置读写、校验、快照和变更的入口导出。

src/config/sessions.ts
    ↓
理解 sessions 相关能力从哪些模块导出。

阅读时可以带着下面几个问题：

1. setupCommand 是直接覆盖配置，还是合并已有配置？
2. workspace 路径优先级是什么？
3. gateway.mode 为什么默认是 local？
4. ensureAgentWorkspace 会创建哪些文件？
5. skipBootstrap 会影响哪些行为？
6. sessions 目录创建后，后续由哪个模块写入会话内容？

这些问题串起来，就能从“初始化命令”过渡到“Agent 运行时”。

---

18. 我的理解

我认为 setup 是理解 OpenClaw 的一个很好入口。

因为它虽然不是最复杂的命令，但它把 OpenClaw 的几个核心概念串了起来：

配置文件
workspace
Gateway 模式
Agent bootstrap 文件
sessions 目录

这些概念如果没理解，后面直接看 Agent、Tools、Skills、Channel 会比较吃力。

可以说，openclaw setup 做的事情不是“安装 OpenClaw”，而是“为 OpenClaw 创建一个可运行的本地状态环境”。

这个本地状态环境包括：

OpenClaw 怎么运行；
Agent 在哪里工作；
Agent 初始读哪些行为文件；
会话历史放在哪里。

---

19. 本期重点理解

这一期可以总结为五点：

第一，openclaw setup 负责创建基础配置和 agent workspace，是最小初始化命令。

第二，setup 会读取已有 openclaw.json，并在不破坏原配置的前提下补齐 agents.defaults.workspace 和 gateway.mode。

第三，workspace 默认位于 ~/.openclaw/workspace，里面会包含 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md 等文件。

第四，setup 还会创建 sessions 目录，为后续会话记录和上下文管理做准备。

第五，openclaw onboard 是更完整的首次引导流程，覆盖 Gateway、模型认证、workspace、channels、skills 和 health 等环节。

一句话概括：

setup 负责把 OpenClaw 的本地运行地基搭起来，onboard 负责把这个地基进一步配置成一个真正可用的个人 AI 助手系统。

---

20. 本期小结

本期主要分析了 OpenClaw 的 setup 和 onboard 初始化逻辑。setup 是最小初始化命令，核心任务是创建或更新 ~/.openclaw/openclaw.json，设置 agents.defaults.workspace，补齐 gateway.mode="local"，确保 workspace 存在，并创建 sessions 目录。workspace 是 Agent 的工作区，不等于源码目录，它会保存 AGENTS、SOUL、TOOLS、IDENTITY、USER、HEARTBEAT、BOOTSTRAP 等文件。onboard 则是更完整的首次配置向导，覆盖模型认证、Gateway、渠道、技能和健康检查等流程，并支持交互式和非交互式两种方式。

这一期可以用一句话总结：

OpenClaw 的初始化逻辑体现了它的核心设计边界：源码负责程序实现，openclaw.json 负责运行配置，workspace 负责 Agent 行为与长期工作区，sessions 负责对话历史。

下一期可以继续分析：

OpenClaw 源码解析（六）：agent 命令与一次 Agent 对话的执行链路

下一期重点分析 openclaw agent --message "Hello" 这类命令，看看 CLI 如何把用户输入交给 Gateway，Gateway 如何创建一次 Agent turn，Agent 如何加载配置、workspace、session 和模型，最终生成回复。