OpenClaw 源码解析（五）：setup / onboard 与本地配置初始化

1. 本期目标上一期我们分析了 OpenClaw 的 CLI 启动链路用户输入openclaw命令后程序会先经过entry.ts、run-main、Commander Program 构建和命令注册流程然后再进入具体命令逻辑。这一期继续往下看重点分析两个最基础的初始化命令openclaw setup openclaw onboard它们的作用都和“第一次把 OpenClaw 配起来”有关但定位并不完全相同。官方 CLI 文档中明确区分了这几个命令openclaw setup负责创建基础配置和 workspaceopenclaw 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 workspaceonboard被描述为Interactive onboarding for gateway, workspace, and skillsconfigure被描述为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.jsonOpenClaw 的主配置文件通常是~/.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.modelocal写入配置远程 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 promptsmanual是完整提示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.modelocal确保 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 如何把用户输入交给 GatewayGateway 如何创建一次 Agent turnAgent 如何加载配置、workspace、session 和模型最终生成回复。