人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载bootstrap-extra-files是 OpenClaw 内置bundled的自动化钩子它在agent:bootstrap事件触发、工作区 bootstrap 文件即将注入Project Context之前运行通过一组 glob/path 模式把工作区内其他位置例如 Monorepo 各子包的AGENTS.md、TOOLS.md等上下文文件一并加载进 Agent 的提示词上下文全程只修改内存中的上下文而不写入任何文件。读完本文你将掌握该钩子的启用方式、paths/patterns/files三种配置形态、9 个受支持的文件名清单、以及其背后的边界安全校验与子代理 allowlist 行为可以直接把单根工作区的上下文策略平滑扩展到多根multi-root场景。背景agent:bootstrap 事件与 Project Context在 OpenClaw 中Agent 启动时会从工作区读取一组「bootstrap 文件」并把它们注入到系统提示Project Context中作为 Agent 长期行为与工具使用规范的载体。这一过程由agent:bootstrap事件表示——根据 internal-hooks.ts 中的类型定义该事件携带一个AgentBootstrapHookContext其中包含workspaceDir、bootstrapFilesWorkspaceBootstrapFile[]、cfg、sessionKey、sessionId、agentId等字段。事件的实际派发由 bootstrap-hooks.ts 中的applyBootstrapHookOverrides完成它构造agent:bootstrap事件并调用triggerInternalHook随后读取事件上下文中更新后的bootstrapFiles返回给上层。这意味着任何注册在agent:bootstrap上的钩子都可以就地修改即将注入上下文的文件列表——这正是bootstrap-extra-files的工作位置。按 hooks.ts 的导出约定钩子通过registerInternalHook(event, handler)注册目录式发现的钩子则由 loader.ts 根据HOOK.md元数据中的events数组逐一注册bootstrap-extra-files声明的事件正是[agent:bootstrap]。为什么需要它多上下文根工作区OpenClaw 默认只在工作区根目录查找并注入 bootstrap 文件。但对于 Monorepo 这类拥有多个上下文根的项目——例如packages/下每个子包各自维护一份AGENTS.md或TOOLS.md——如果不动工作区根目录这些子包级别的上下文就无法进入Project Context。bootstrap-extra-files解决的正是在不改动工作区根的前提下按 glob 模式把额外文件纳入注入范围适用于「一个工作区、多个 context root」的项目结构不需要把子包的AGENTS.md复制到根目录避免文件重复与同步问题钩子本身不写任何文件只对内存中的bootstrapFiles做追加安全且可随时通过配置关闭。快速启用该钩子随 OpenClaw 一起分发metadata.openclaw.install标记为bundled见 HOOK.md自动被发现通过 CLI 或配置文件即可启用。方式一CLI 启用openclaw hooks enable bootstrap-extra-files该命令会在你的配置文件~/.openclaw/openclaw.json中写入hooks.internal.entries.bootstrap-extra-files.enabled true见 docs/cli/hooks.md 中关于openclaw hooks enable name的行为说明。配套的管理命令openclaw hooks list # 列出全部可用钩子与启用状态 openclaw hooks info bootstrap-extra-files # 查看单个钩子的详细信息 openclaw hooks check # 检查钩子状态与缺失的前置条件 openclaw hooks disable bootstrap-extra-files # 停用方式二配置文件启用在~/.openclaw/openclaw.json中配置。注意总开关hooks.internal.enabled必须为true钩子条目本身再显式开启{ hooks: { internal: { enabled: true, entries: { bootstrap-extra-files: { enabled: true, paths: [packages/*/AGENTS.md, packages/*/TOOLS.md] } } } } }配置选项详解钩子只接受一个核心参数用于描述「要额外加载哪些文件」的 glob/path 模式数组且提供了三种等价写法。选项类型说明pathsstring[]首选写法glob/path 模式列表patternsstring[]paths的别名filesstring[]paths的别名三者优先级从源码可以确认根据 handler.ts 中的resolveExtraBootstrapPatterns实现钩子会依次尝试paths→patterns→files取第一个非空的数组作为生效模式若三者都为空钩子直接返回、不做任何操作。此外需要注意两个全局性约束路径解析与边界所有路径都相对于工作区根解析且必须保持在工作区内部含 realpath 校验越界文件一律不加载文件名白名单只有被识别为 bootstrap 的文件名才会被加载其余匹配到的文件会被跳过并记录诊断。受支持的 bootstrap 文件名清单并非模式匹配到的任意文件都会被注入运行时只认以下 9 个「bootstrap basename」文件名常量定义workspace.tsAGENTS.mdDEFAULT_AGENTS_FILENAMESOUL.mdDEFAULT_SOUL_FILENAMETOOLS.mdDEFAULT_TOOLS_FILENAMEIDENTITY.mdDEFAULT_IDENTITY_FILENAMEUSER.mdDEFAULT_USER_FILENAMEHEARTBEAT.mdDEFAULT_HEARTBEAT_FILENAMEBOOTSTRAP.mdDEFAULT_BOOTSTRAP_FILENAMEMEMORY.mdDEFAULT_MEMORY_FILENAMEmemory.mdDEFAULT_MEMORY_ALT_FILENAMEMEMORY.md的备选小写形式这组白名单对应 workspace.ts 中的VALID_BOOTSTRAP_NAMES集合也是loadExtraBootstrapFilesWithDiagnostics做文件名校验的依据。若模式匹配到README.md、CHANGELOG.md之类的文件它们不会进入上下文只会产生一条invalid-bootstrap-filename诊断。执行流程与源码级原理1. 事件守卫与配置解析handler.ts 中的处理函数依次执行通过isAgentBootstrapEvent(event)确认事件类型为agent:bootstrap守卫定义见 hooks.ts事件 type 为agent、action 为bootstrap且上下文中存在workspaceDir字符串与bootstrapFiles数组用resolveHookConfig(context.cfg, bootstrap-extra-files)读取hooks.internal.entries.bootstrap-extra-files条目若未配置或enabled false则跳过用normalizeStringArray清洗模式数组剔除非字符串与空白项再按paths→patterns→files解析出最终模式列表。2. 模式展开与文件加载加载逻辑全部收敛在 workspace.ts 的loadExtraBootstrapFilesWithDiagnostics(workspaceDir, patterns)中glob 展开模式若包含*、?或{使用fs.glob(pattern, { cwd: resolvedDir })展开成具体相对路径否则按字面路径处理。展开失败时回退为字面路径文件名校验每个匹配项先检查path.basename是否属于VALID_BOOTSTRAP_NAMES不属于则记入invalid-bootstrap-filename诊断并跳过边界安全读取通过readWorkspaceFileWithGuards读取其内部调用openBoundaryFile以workspaceDir为根做 realpath 边界校验并限制单文件最大MAX_WORKSPACE_BOOTSTRAP_FILE_BYTES 2 * 1024 * 10242 MiB见 workspace.ts读取缓存按dev:ino:size:mtimeMs生成文件身份标识内容相同则复用缓存避免重复 IOworkspace.ts失败分类读取失败按原因映射为诊断码——路径问题 →missing、校验失败越界/超限→security、IO 异常 →io。3. 上下文合并成功加载的额外文件与原有bootstrapFiles合并后再经过filterBootstrapFilesForSession做会话级过滤写回事件上下文handler.ts。全程不落盘符合内置钩子「Output: No files written; context is modified in-memory only」的定位见 src/hooks/bundled/README.md。安全模型路径不能逃逸工作区由于配置的模式理论上可以由用户自定义该钩子对「加载范围」做了多层防护相关测试位于 workspace.load-extra-bootstrap-files.test.ts路径穿越拦截../outside/AGENTS.md这类试图读取工作区外文件的模式会被拒绝测试断言加载结果为 0 个文件符号链接真实路径校验工作区根本身可以是符号链接realpath 解析后依然能正常加载但指向工作区外的链接别名会被排除硬链接别名排除工作区内指向外部文件的硬链接会被拒绝加载超大文件拦截超过 2 MiB 1 字节的文件被跳过并产生reason: security的诊断文件名白名单即使路径合法非 bootstrap basename 也不会被注入。因此在实际配置时应把模式严格限定在工作区内部例如packages/*/AGENTS.md而不是用../或绝对路径去引用外部内容。子代理Subagent会话的 allowlist 行为合并完额外文件后钩子会调用filterBootstrapFilesForSession(files, sessionKey)workspace.ts重新应用会话过滤当sessionKey属于子代理或 cron 会话时最终只保留最小 allowlist——AGENTS.md、TOOLS.md、SOUL.md、IDENTITY.md、USER.md——其余 bootstrap 文件如HEARTBEAT.md、MEMORY.md、BOOTSTRAP.md会被剔除。这一行为在 handler.test.ts 中有直接验证以agent:main:subagent:abc为会话键、配置packages/*/SOUL.md模式时最终上下文只保留AGENTS.md、SOUL.md、TOOLS.md三个文件。也就是说额外文件对子代理会话同样受 allowlist 约束并非「注入即全量可见」。故障排查与验证钩子的运行日志使用createSubsystemLogger(bootstrap-extra-files)子系统handler.ts被跳过的候选文件会以debug级别汇总输出按reason统计数量如invalid-bootstrap-filename、missing、security、io加载阶段抛出的异常以warn级别记录不会中断 Agent 启动log.warn(failed: ...)钩子自身加载失败例如 handler 不是函数、事件元数据为空会由 loader.ts 以error级别记录。启用后可通过以下方式自检openclaw hooks list # 确认 bootstrap-extra-files 处于 enabled 状态 openclaw hooks check # 检查前置条件requires.config 要求 workspace.dir 已配置 openclaw hooks info bootstrap-extra-files # 查看事件与元数据也可以直接观察新会话中 Agent 的 Project Context 是否出现来自子目录的 bootstrap 内容或结合openclaw hooks enable/ 修改paths后重启 Gateway参考 src/hooks/bundled/README.md 的测试步骤来验证注入效果。典型场景示例场景一Monorepo 子包上下文注入{ hooks: { internal: { enabled: true, entries: { bootstrap-extra-files: { enabled: true, paths: [ packages/*/AGENTS.md, packages/*/TOOLS.md, packages/*/SOUL.md ] } } } } }对每个子包目录packages/pkg/其存在的AGENTS.md、TOOLS.md、SOUL.md都会在agent:bootstrap阶段被追加到 Project Context与根目录的同类文件并存。场景二嵌套多级目录使用 glob 递归匹配更深层级的文件{ paths: [apps/*/AGENTS.md, apps/**/TOOLS.md, services/*/IDENTITY.md] }注意**匹配任意层级的子目录命中后仍受「必须位于工作区内」与「basename 必须在白名单内」两条硬约束。场景三用别名patterns/files书写三个选项等价钩子按paths→patterns→files的优先级取第一个非空者{ entries: { bootstrap-extra-files: { enabled: true, patterns: [modules/*/AGENTS.md] } } }小结bootstrap-extra-files是 OpenClaw 处理多上下文根工作区尤其是 Monorepo的关键内置钩子它在agent:bootstrap阶段把配置模式匹配到的额外 bootstrap 文件合并进Project Context通过 9 个文件名白名单、工作区 realpath 边界校验、2 MiB 单文件上限与子代理 allowlist 层层约束加载范围且全程不写文件。配置只需在hooks.internal.entries下开启并声明paths或等价的patterns/files即可在不动工作区根目录的前提下让每个子包自己的AGENTS.md/TOOLS.md类上下文随会话自动生效。如果想进一步深入可以阅读 handler.ts 与 workspace.ts 的实现参考 handler.test.ts 与 workspace.load-extra-bootstrap-files.test.ts 的测试用例或查看 docs/automation/hooks.md 中该钩子的官方文档段落。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw bootstrap-extra-files Hook 深度指南为 Monorepo 工作区注入额外的 AGENTS.md / TOOLS.md 引导文件OpenClaw bootstrap extra files Hook 深度指南为 Monorepo 工作区注入额外的 AGENTS.md / TOOLS.m人工智能大模型LLM 网关AI Agent即时通讯OpenClaw Agent Workspace工作区目录结构、Bootstrap 文件机制与 Git 备份实战OpenClaw Agent Workspace工作区目录结构、Bootstrap 文件机制与 Git 备份实战 Agent workspaceAgent人工智能大模型LLM 网关AI Agent即时通讯Trellis 本地钩子Hooks定制实战指南掌控会话上下文注入、工作流状态与子代理上下文Trellis 本地钩子Hooks定制实战指南掌控会话上下文注入、工作流状态与子代理上下文 本文以 EcoPaste 仓库中 Trellis 工作流体系为桌面应用数据存储上一篇DeepEval让AI模型评估变得简单高效的完整指南下一篇Stitching与OpenCV对比为什么选择这个专业图像拼接库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考