OpenClaw Agent Runtime 深度解析工作区契约、引导文件注入与会话自举机制【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 内置一套嵌入式 Agent 运行时embedded agent runtime它将 Agent 循环、工具接线与提示词组装集成在单一运行时表面区别于把每轮对话委托给外部 harness 进程的架构。本文以 docs/concepts/agent.md 为骨架结合仓库源码主要位于 src/agents深入讲解该运行时的完整契约工作区必须具备什么、哪些引导文件会被注入系统提示词、会话如何基于 SQLite 自举以及流式输出、模型引用与最小化配置等实操要点。读完本文你将能够独立规划一个 OpenClaw Agent 的工作区结构、配置多 Agent 路由下的运行时参数并理解底层注入与状态管理原理。工作区WorkspaceAgent 的唯一工作目录每个配置的 Agent 都拥有一个独立的工作区目录它通过agents.defaults.workspace全局默认或agents.entries.*.workspace按 Agent 覆盖指定并作为工具执行与上下文读取的唯一工作目录cwd。也就是说Agent 的文件读写、命令执行都默认被约束在这个目录之内这是运行时安全与职责隔离的基础。官方推荐使用openclaw setup命令来创建~/.openclaw/openclaw.json若缺失并初始化工作区文件。完整的工作区布局与备份指南见 Agent workspace。需要特别说明的是如果开启了agents.defaults.sandbox非主会话non-main sessions可以覆盖默认工作区改用agents.defaults.sandbox.workspaceRoot下的按会话划分的工作区相关配置细节见 Gateway configuration。引导文件Bootstrap Files注入系统提示词的六个文件在工作区内OpenClaw 期望以下用户可编辑的引导文件存在文件用途AGENTS.md操作指令 记忆如何执行任务、项目约定SOUL.md人格、边界、语气IDENTITY.mdAgent 名称/气质/emojiUSER.md用户画像 偏好称呼BOOTSTRAP.md一次性首次运行仪式完成后即删除MEMORY.md根级长期记忆文件仅当存在时注入这些文件名在源码中有明确的常量定义见 src/agents/workspace.tsDEFAULT_AGENTS_FILENAME AGENTS.md、DEFAULT_SOUL_FILENAME SOUL.md、DEFAULT_IDENTITY_FILENAME IDENTITY.md、DEFAULT_USER_FILENAME USER.md、DEFAULT_BOOTSTRAP_FILENAME BOOTSTRAP.md而DEFAULT_MEMORY_FILENAME指向规范化的根记忆文件名常量。注入时机与行为规则在新会话的第一轮OpenClaw 会把这些文件的内容注入系统提示词的Project Context区域。具体的注入行为遵循以下规则空白文件被跳过内容为空的文件不会进入上下文。大文件被裁剪超出预算的文件会被截断并附上标记保证提示词保持精简需要全文时由模型自行读取文件。缺失文件注入标记行除MEMORY.md外的文件若缺失会注入一行missing file标记而非报错openclaw setup会为缺失文件创建安全默认模板。MEMORY.md条件注入只有当它存在于工作区根目录时才注入不存在时不产生标记行。BOOTSTRAP.md一次性首次运行仪式BOOTSTRAP.md是引导文件中最特殊的一个它只在全新工作区不存在其他任何引导文件时创建在待处理期间OpenClaw 会将其持续保留在 Project Context中并在系统提示词中加入初始仪式的引导说明而不是把文件内容复制进用户消息仪式完成后你删除该文件后续重启不会重新创建它。工作区状态认证与 SQLite 持久化当工作区被观察observed之后OpenClaw 会把它的**设置状态与认证信息attestation**存储在共享 SQLite 数据库中路径为~/.openclaw/state/openclaw.sqlite。这带来一个重要的安全行为如果最近认证过的工作区消失或被清空启动时会拒绝静默重新播种BOOTSTRAP.md——因为静默重建可能掩盖工作区被误删或篡改的事实。此时应恢复工作区或执行一次完整的上线重置full onboard reset让工作区与其数据库状态一并清除。认证相关逻辑实现在 src/agents/workspace.ts其中包含attestation状态、attestedAtMs时间戳与防重播种保护参考该文件 L527-L659 附近的实现。旧版引导文件迁移旧版本使用工作区 JSON 与.attestedsidecar 文件记录状态而当前运行时不再读取这些文件。运行openclaw doctor --fix可以校验这些旧文件、把其状态导入 SQLite并在导入行验证完成后逐个移除来源文件。完全禁用引导文件生成对于已预播种pre-seeded的工作区可以通过配置彻底关闭引导文件的自动创建{ agents: { defaults: { skipBootstrap: true } } }该配置项在配置 Schema 中有明确定义见 src/config/zod-schema.agent-defaults-base.tsskipBootstrap: z.boolean().optional()。此外源码还暴露了更细粒度的skipOptionalBootstrapFiles可跳过指定可选引导文件如SOUL.md、IDENTITY.md、USER.md、BOOTSTRAP.md以及上下文注入相关的contextInjection、bootstrapMaxChars、bootstrapTotalMaxChars等参数同文件 L77-L82。注入模式的源码实现引导文件的解析与注入并非简单的读文件拼字符串src/agents/bootstrap-files.ts 展示了完整的处理流水线上下文注入模式resolveContextInjectionMode支持always每轮都注入、continuation-skip续接会话时跳过与never从不注入三种模式默认always会话级过滤filterBootstrapFilesForSession按会话与聊天类型筛选文件钩子覆盖applyBootstrapHookOverrides允许注册的钩子调整、替换引导文件大小预算buildBootstrapContextForFiles通过resolveBootstrapMaxChars单文件上限与resolveBootstrapTotalMaxChars总预算控制注入体积完成标记hasCompletedBootstrapTurn会在活动会话分支上扫描自定义事件openclaw:bootstrap-context:full以判断全量引导是否已完成见 src/agents/bootstrap-files.ts。内置工具Built-in Tools核心工具读、执行、编辑、写文件及相关的系统工具始终可用但受工具策略tool policy约束。其中apply_patch对 OpenAI 模型默认开启并可通过tools.exec.applyPatch配置门控支持三个层级enabled直接启用workspaceOnly仅限工作区内的文件操作allowModels按模型白名单控制。一个重要认知AGENTS.md中的## Tools段落并不控制工具是否存在——它只是指导模型你希望这些工具被如何使用的引导性文本工具注册与启用的实际决策权在运行时与配置层。Skills 加载优先级OpenClaw 从以下位置加载 skills优先级从高到低工作区级workspace/skills项目 Agent 级workspace/.agents/skills个人 Agent 级~/.agents/skills托管/本地级~/.openclaw/skills内置级随安装分发额外目录skills.load.extraDirsSkill 根目录下可以包含分组文件夹例如workspace/skills/personal/foo/SKILL.md但 skill 仍然以其扁平的 frontmatter 名称暴露例如foo。Skills 还可以通过配置/环境变量进行门控见 Gateway configuration 中的skills一节。运行时边界Runtime Boundaries嵌入式 Agent 运行时完全由 OpenClaw 拥有模型发现model discovery、工具接线tool wiring、提示词组装prompt assembly、会话管理session management与频道投递channel delivery共享同一套集成式运行时表面。这意味着 Agent 的整个执行生命周期——从收到消息、发现模型、组装上下文、调用工具到把回复投递给频道——都在一个统一、可控的边界内完成这也是它区别于外部 harness 委托模式的核心特征。会话存储SQLite 数据库会话行session rows存储在每个 Agent 独立的 SQLite 数据库中~/.openclaw/agents/agentId/agent/openclaw-agent.sqlite转录 JSONL 文件仍可存在于~/.openclaw/agents/agentId/sessions/目录下但它们的角色已转变为遗留迁移输入包括已删除或重置的归档、导入导出文件与支持性工件。活跃的 Agent 历史记录以会话行形式存储在 SQLite 中。会话 ID 稳定且由 OpenClaw 选定。需要强调OpenClaw 不读取其他工具的会话文件夹——会话状态的唯一权威来源是它自己的 SQLite 存储。流式运行中的转向Steering While Streaming当新一轮输入在 Agent 运行中途到达时默认行为是将其转向steer进当前运行。OpenClaw 运行时会在未启动的工具启动前与下一次模型调用前检查转向请求正在运行的工具继续执行未启动的串行调用被跳过并行调用在其批次越过启动检查点后继续执行被跳过的调用在模型看到转向消息前会收到合成的成对结果synthetic paired results保证上下文一致。队列语义方面/queue steer默认的活动运行行为转向进当前运行/queue followup与/queue collect让消息等待后续轮次而非转向/queue interrupt中止当前活动运行。详见 Queue 与 Steering queue。块式流式输出Block Streaming块式流式输出会在每个完成的 assistant 块产生后立即发送默认关闭agents.defaults.blockStreamingDefault: off。可调参数包括参数作用默认值agents.defaults.blockStreamingBreak块边界切分点text_end可选message_endagents.defaults.blockStreamingChunk软块分块大小控制800-1200 字符优先段落换行其次换行最后句子agents.defaults.blockStreamingCoalesce合并流式块以减少单行刷屏发送前按空闲合并视渠道而定渠道差异需要注意非 Telegram 渠道需要显式设置*.streaming.block.enabled: true才能启用块回复而QQ Bot 默认流式输出块回复除非将channels.qqbot.streaming.mode设为off。此外工具开始执行时会输出详细的工具摘要verbosity 较高无防抖Control UI 在可用时通过 agent events 流式展示工具输出。完整机制见 Streaming chunking。模型引用Model Refsprovider/model 解析规则配置中的模型引用例如agents.defaults.model与agents.defaults.models通过按第一个/拆分来解析使用provider/model形式配置模型如果模型 ID 自身包含/OpenRouter 风格必须带上 provider 前缀例如openrouter/moonshotai/kimi-k2如果省略 providerOpenClaw 依次尝试先查别名alias再在已配置的 provider 中做唯一匹配按精确模型 ID最后回退到配置的默认 provider若该 provider 已不再暴露配置的默认模型则回退到第一个已配置的 provider/model而不是暴露一个已移除 provider 的陈旧默认值。这一别名 → 唯一匹配 → 默认 provider → 首个已配置 provider/model的降级链路保证了模型引用在配置变更后依然具有确定性与鲁棒性。最小化配置Configuration Minimal要让一个 Agent 真正跑起来最少需要设置两件事agents.defaults.workspace指定工作区目录运行时契约的根基每个启用渠道的发送者白名单sender allowlist强烈推荐配置这是渠道访问安全的第一道防线参见 Access groups。从配置 Schema 可以看到workspace与skipBootstrap、contextInjection等参数同属 Agent 默认配置层见 src/config/zod-schema.agent-defaults-base.ts说明工作区声明是 Agent 运行时的基础配置单元。相关文档Agent workspace完整工作区布局与备份指南Multi-agent routing多 Agent 路由与会话隔离Session management会话生命周期管理Group chats群聊场景下的 Agent 行为System prompt系统提示词组装细节【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考