OpenClaw Agent 引导（Bootstrapping）机制详解：首次运行的“出生仪式“、身份播种与完整配置指南-开发者社区

OpenClaw Agent 引导（Bootstrapping）机制详解：首次运行的"出生仪式"、身份播种与完整配置指南

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

Agent 第一次真正开口说话之前，OpenClaw 会为它执行一场只有一次的"引导仪式"（Bootstrapping）：向全新工作区播种身份与操作文件，让 Agent 通过一段受限的"四拍出生序列"确立名字、气质与安全边界，并完成插件/技能推荐的安装决策。本文以 docs/start/bootstrapping.md 为核心骨架，结合 BOOTSTRAP.md 模板、Agent 工作区文档、Onboard CLI 参考与源码测试，完整还原引导机制的触发时机、执行流程、全部命令行参数与可配置项，读完即可理解并掌控这一首次运行流程。

什么是 Bootstrapping：Agent 的首次运行仪式

Bootstrapping 是 OpenClaw 在全新工作区上执行的首次运行仪式，负责两件事：

播种工作区与身份文件：向默认的~/.openclaw/workspace写入AGENTS.md、SOUL.md、IDENTITY.md、USER.md和BOOTSTRAP.md五份初始文件；
引导 Agent 完成身份确立对话：让 Agent 在首次真实回合（first real turn）中，用一段简短对话确认自己的名字、气质与安全注意事项，并把结论持久化到文件与配置两个层面。

它只在 onboarding（引导设置，见 macOS App onboarding）完成之后、Agent 的第一次真实回合运行时执行一次。工作区一旦看起来已配置完成，BOOTSTRAP.md就会被删除，仪式不会再次运行。

从 Agent 工作区文档可以看到，工作区与配置目录是严格分离的：~/.openclaw/workspace是 Agent 的"家"，存放人格与记忆文件；而~/.openclaw/根目录下存放的是openclaw.json配置、凭据与会话数据库，不应被提交进工作区的 git 仓库。

引导播种的五份工作区文件

首次运行时，OpenClaw 会在工作区根目录种下以下标准文件（文件映射详见 Agent workspace 的 "Workspace file map"）：

文件	作用	加载时机
`AGENTS.md`	操作指令：规则、优先级、"如何表现"，环境相关的工具说明应写入其中的`## Tools`小节	每个会话开始时加载
`SOUL.md`	人格、语气与边界	每个会话加载
`IDENTITY.md`	名字、气质、表情符号等身份记录	引导仪式期间创建/更新
`USER.md`	基于指令的用户模型（可选）：稳定的偏好、沟通风格、活跃项目上下文	每个会话以独立的 4,000 字符预算加载
`BOOTSTRAP.md`	一次性首次运行仪式脚本（见下文"出生序列"）	仅全新工作区存在，完成后删除

模板分别位于 BOOTSTRAP.md 模板、AGENTS.md 模板与 IDENTITY 模板。

值得注意的是工作区默认位置是可配置的（Agent workspace）：

默认~/.openclaw/workspace；
设置了非default的OPENCLAW_PROFILE时，变为~/.openclaw-<profile>/workspace；
OPENCLAW_WORKSPACE_DIR优先于上述两者；
也可在openclaw.json中配置agents.defaults.workspace或按 Agent 覆盖agents.entries.*.workspace。

如果你自行管理工作区文件，可以在配置中禁用引导文件的自动创建：

{ agents: { defaults: { skipBootstrap: true, }, }, }

四拍出生序列：一次简短而非问卷的对话

BOOTSTRAP.md模板（docs/reference/templates/BOOTSTRAP.md）定义了完整的出生对话脚本，核心原则是：用户请求永远优先。如果第一条消息要求的是真实工作，Agent 应先把活干完并交付结果，再在安静时刻补上出生序列——"This file is a ritual, not a gate"（这是一个仪式，不是关卡）。

出生序列严格限定为四拍（four beats），禁止把它变成问卷或长篇传记：

第 1 拍：询问如何称呼你

Agent 以"用户的新助手"身份自我介绍，然后询问用户想怎么称呼它。不能自行选择、发明或建议名字，必须等待用户回答后再继续。

第 2 拍：确定你的气质（Vibe）

给出一句简短、真实的气质描述（soul/vibe line），用户有一次否决或调整的机会，同时挑选一个签名 emoji。

名字与气质确认后，需要双重持久化——两处都重要：

写入IDENTITY.md（名字、你是什么、气质行、emoji），并把气质行放入SOUL.md。这两个文件是 Agent 读取"我是谁"的来源；如果停留在模板状态，就等于抹掉了这次对话的成果。
运行现有配置命令，让频道与 UI 显示同样的身份：

openclaw agents set-identity --workspace "<this workspace>" --name "<name>" --theme "<vibe>" --emoji "<emoji>"

必须使用真实的工作区路径并对值做安全引号包裹，不要手工编辑openclaw.json。

第 3 拍：处理应用推荐

读取 onboarding 期间已存储的待处理应用匹配结果（该命令只读、绝不重新扫描机器，若用户已应答过该邀请则返回空列表）：

openclaw onboard recommendations --json

输出只包含不透明的安装 ID（opaque install IDs）、本地生成的来源与层级，每个层级为recommended（推荐）或optional（可选）。ID 仅作为标识符使用，不含任何市场文案。

如果存在匹配，简要说明后询问用户："minimal set or maximum convenience?"（最小集还是最大便利？）：

最小集：只安装recommended匹配项；
最大便利：额外提供optional匹配项。

安装规则有严格边界：

官方插件匹配项：只用openclaw plugins install <id>安装用户选定集合；
ClawHub 技能属于第三方：必须单独列出，且除非用户明确选择某个特定技能，否则绝不安装；安装用openclaw skills install <id>；
如果没有存储的匹配，跳过本拍且不发表评论。

用户回答且所有选中的安装成功后，记录完成状态，让该邀请永不再次出现：

openclaw onboard recommendations acknowledge

若某个安装失败，则消耗成功与已拒绝的推荐，但把失败 ID 保留为待处理供后续 onboarding 运行重试：

openclaw onboard recommendations acknowledge --retry "<failed-id>" ["<failed-id>"...]

这里必须使用读取命令返回的确切不透明 ID。绝不能在未带--retry的情况下确认一个失败的安装。中断的技能安装可能在下次尝试时报"目标已存在"，此时需要用发布者限定的 ID 精确校验：

openclaw skills verify "@owner/slug"

只有当校验对同一个 ID 成功、且 JSON 输出中openclaw.resolution.source为installed时，才算安装成功——注册表校验不能证明本地已安装。若校验失败、报告了不同发布者或不同解析来源，则保留该 ID 为待处理（--retry），不要覆盖已有技能。

第 4 拍：一句安全提示

在仪式之后或交付完用户工作后，用一两句话而非说教：Agent 以对这台机器的真实访问权限运行。在连接频道或暴露 Gateway 之前，请用户浏览网关安全文档（可随时用openclaw security audit检查当前设置）。

仪式收尾：删除 BOOTSTRAP.md 与"已配置"判定

四拍完成后，Agent 删除BOOTSTRAP.md，并说一句话：

Ask me anything; for system things I'll ask OpenClaw.

文件删除后，OpenClaw 将出生序列视为完成，不会重新创建BOOTSTRAP.md。如果 Agent 把文件留在原地，一旦工作区看起来已配置，OpenClaw 会代为删除。

一个工作区在以下任一条件满足时被视为已配置（configured）：

SOUL.md、IDENTITY.md或USER.md与各自的起始模板产生差异；
或存在memory/文件夹。

身份的双重持久化：IDENTITY.md / SOUL.md 与 set-identity

身份既写入 Agent 自己读取的文件（IDENTITY.md+SOUL.md），也通过openclaw agents set-identity写入配置（供频道与 UI 显示）。

IDENTITY 模板定义了身份字段格式：

Name：名字；
Creature：生物类型（AI？机器人？灵宠？机魂？……）；
Vibe：气质（锐利？温暖？混乱？冷静？）；
Emoji：签名表情；
Avatar：工作区相对路径、http(s)URL 或 data URI。

其中Theme、Creature、Vibe三者按Theme（若设置）→Creature→Vibe的优先级共同作用于同一个有效身份值；工具同步时只把Name、Theme、Emoji、Avatar写回文件，Creature与Vibe是只读输入。

openclaw agents set-identity会把字段写入agents.entries.*.identity（见 Agents CLI 参考）：

# 从 IDENTITY.md 读取并同步 openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity # 显式覆盖字段 openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png

写入配置的效果示例：

{ agents: { entries: { main: { default: true, identity: { name: "OpenClaw", theme: "space lobster", emoji: "🦞", avatar: "avatars/openclaw.png", }, }, }, }, }

--agent与--workspace用于选择目标 Agent（若--workspace匹配多个 Agent 则命令失败并要求指定--agent）；--workspace与--identity-file只用于选择目标，不会改变agents.entries.*.workspace。工作区相对的头像路径不能逃逸工作区根目录（即使通过符号链接也不行），本地头像文件限制为 2 MB。

源码测试 src/commands/agents.identity.test.ts 覆盖了身份文件的创建、持久化与命令集成：测试通过makeTempWorkspace构建临时工作区、写入IDENTITY.md，并断言agentsSetIdentityCommand正确地把身份写入agents.entries.main.identity，印证了"文件 + 配置"双通道持久化的实现路径。

应用推荐命令族的更多细节

Onboard CLI 参考补充了推荐命令族的完整用法：

openclaw onboard recommendations --json openclaw onboard recommendations --agent writer --json openclaw onboard recommendations acknowledge --agent writer openclaw onboard recommendations refresh --agent writer openclaw onboard recommendations acknowledge --retry "<failed-id>" openclaw onboard recommendations refresh

openclaw onboard recommendations读取 onboarding 期间存储的待处理应用匹配；--json输出供首次运行引导使用。该命令不重新扫描已安装应用、不调用模型，输出只包含校验过的安装 ID、来源与层级，刻意省略不可信的市场文案、模型理由与本地应用标签；
邀请被应答后，命令返回空列表，后续 onboarding 运行直接跳过该步骤；
openclaw onboard recommendations refresh清除已存储的邀请，使下一次 onboarding 重新扫描已安装应用并生成新邀请；
--agent <id>用于选择已配置的 Agent 进行读取、acknowledge、acknowledge --retry或refresh，操作只作用于该 Agent 工作区的推荐；未知或空白的 Agent ID 直接失败且不改变存储的推荐；
全新工作区把推荐选择推迟到引导对话中进行；对话处理完用户选择后，acknowledge将存储的邀请标记为已应答，该操作是幂等的；
失败 ID 用--retry保持待处理，成功与已拒绝的匹配被消耗。

嵌入与本地模型运行的特殊处理

对于嵌入式或本地模型运行，OpenClaw 把BOOTSTRAP.md排除在特权系统上下文之外（见 docs/start/bootstrapping.md）：

在主要的交互式首次运行中，仍会通过用户提示（user prompt）传入文件内容，因此不能可靠调用read工具的模型也能完成仪式；
如果当前运行无法安全访问工作区，Agent 会收到一段简短的"受限引导说明"（limited-bootstrap note），而不是一句泛泛的问候。

这保证了即使模型工具调用能力受限、或运行环境访问不到工作区，首次运行流程也不会静默失败。

跳过引导：--skip-bootstrap 与 skipBootstrap

对已预先播种（pre-seeded）的工作区，可以在 onboarding 时跳过引导：

openclaw onboard --skip-bootstrap

从 Onboard CLI 参考可以看到，--skip-bootstrap的实际作用是设置agents.defaults.skipBootstrap: true，并跳过创建AGENTS.md、SOUL.md、IDENTITY.md、USER.md与BOOTSTRAP.md。与之对应，配置层面直接写{ agents: { defaults: { skipBootstrap: true } } }也能达到同样效果（Agent workspace）。openclaw setup可以重建缺失的默认文件而不覆盖已有文件。

引导在哪里运行：Gateway 主机

引导始终运行在 Gateway 主机上（docs/start/bootstrapping.md）。如果 macOS App 连接的是远程 Gateway，那么工作区及其引导文件位于那台远程机器上，而不是 Mac 上：

当 Gateway 运行在其他机器时，应在 Gateway 主机上编辑工作区文件（例如user@gateway-host:~/.openclaw/workspace）；
这也意味着引导仪式的实际执行、身份文件的写入、推荐安装（插件/技能）都发生在 Gateway 主机侧。

引导文件的系统提示注入机制

从 System prompt 文档可以深入理解这些引导文件是如何进入模型上下文的：

引导文件按各自的生命周期被解析并路由到提示表面：AGENTS.md、SOUL.md、USER.md、MEMORY.md以及仅存在于全新工作区的BOOTSTRAP.md都会参与注入；BOOTSTRAP.md只在品牌新工作区注入；
如果某个必需引导文件缺失，OpenClaw 会在会话中注入一个"缺失文件"标记并继续；可选的USER.md、MEMORY.md缺失时直接省略；
大型引导文件会被截断注入，相关限额可用agents.defaults.bootstrapMaxChars（默认20000）与agents.defaults.bootstrapTotalMaxChars（默认60000）调整；USER.md保持独立的 4,000 字符上限；
子 Agent 会话只注入AGENTS.md（其他引导文件被过滤，以保持子 Agent 上下文精简）；
内部钩子可通过agent:bootstrap事件在注入前拦截并修改或替换引导文件（例如为SOUL.md换用另一人格）。

这套机制保证了出生仪式的产出（身份文件）在后续每个会话中稳定生效，且截断、缺失都有明确的降级行为，不会破坏会话启动。

小结

OpenClaw 的 Bootstrapping 是一个设计精巧的一次性流程：通过四拍出生序列让 Agent 在首次真实回合确立身份、气质与安全认知，用"文件 + 配置"双重持久化保证身份在 Agent 自读层面与频道/UI 展示层面一致，用只读推荐命令族把插件/技能安装决策收敛成一次"最小集还是最大便利"的选择，最后以删除BOOTSTRAP.md作为仪式完成的标志。理解这套机制，无论你是手动预播种工作区、排查身份初始化问题，还是在远程 Gateway 架构下规划首次运行，都能准确掌握每一步的触发条件与影响范围。