技能介绍

问题在哪

OpenClaw 的 gateway 重启、容器重启甚至容器重建之后，你在启动阶段手工加的那些步骤——拉配置、预热缓存、执行初始化脚本——往往就丢了。重新装配一遍既费时，也容易漏掉关键步骤，导致服务看起来在跑，实际状态却不完整。

init-hooks 要解决的就是这件事：把启动期必须执行的动作变成可声明、可追踪、跨重启不丢的钩子，而不是每次重建后重新手写。

它如何工作

持久化存储：钩子清单保存在 ~/.openclaw/workspace/.init-hooks/，容器重建后数据卷还在，清单不会消失。
三种钩子类型：

- inline：直接内嵌 shell 命令，多行用 \n 分隔，适合一两条短命令。
- script / python：引用本地 shell 或 Python 脚本，适合逻辑较长的任务。
- CDN URL：直接给 zip 或 tar.gz 地址，首次运行时自动下载解压到 downloads/hook_/；缓存存在则复用，pod 重建后缓存丢失会自动重新下载。

执行顺序可控：通过 --order 追加顺序号，默认步进 10，按 order 字段从小到大依次执行。
安装即接线：install 是幂等操作，会创建目录、初始化 hooks.json、生成 dispatcher.sh，并尝试把 dispatcher 调用注入容器启动脚本或 post-init.sh。
配置同步：当 openclaw.json 被修改时，需要同步到持久化路径；额外持久化目标由环境变量 INIT_HOOKS_SYNC_PATHS 配置，路径不存在时自动跳过。

执行时是宽松模式：单个钩子失败不会中断后续，日志追加到 last-run.log 同时输出到 stdout，结束时打印成功与失败列表，方便排查。

适用边界与注意点

钩子内容禁止硬编码 /home/node/，shell 里用 $HOME，Python 里用 Path.home()，否则换部署环境就会失效。
hooks.json 是唯一事实来源，dispatcher.sh 是生成物；手动改 dispatcher.sh 会在下次 add/edit/delete 时被覆盖。
CDN 钩子的缓存在 re-install 时不会被清除，需要手动删除 downloads/hook_/。
delete --force 会跳过二次确认，Agent 不应主动使用，除非用户明确说“直接删”。
向容器启动脚本注入调用时，大多数环境没有写权限或根本没有 /app/start.sh，这属于正常情况，不影响使用——只要 post-init.sh 已注入，dispatcher 就会经由它间接调用。