1. 为什么 SKILL.md 改完不生效一次本地调试的完整复盘如果你正在本地折腾 OpenClaw 的 AgentSkills大概率遇到过这种场景明明把SKILL.md里的触发词改了对话里喊了半天Agent 还是按老逻辑走或者新加了一个 Skill 目录重启前死活扫不到。这不是你写错了而是没搞清 OpenClaw 的加载链路——扫描、门控过滤、提示词注入、热重载监听这四步里任何一环卡住Skill 都不会生效。OpenClaw 的 Skill 机制本质上是一套「按需披露」的能力包系统。每个 Skill 就是一个带 YAML frontmatter 的SKILL.md用自然语言告诉模型「我能做什么、什么时候用我、具体怎么做」。它和传统插件的区别在于插件是提前装好的死功能Skill 是被描述、被理解、被按需调用的活流程。和 Tools 的区别更直接——Tools 负责「用手」Skill 负责「做事」它知道怎么组合多个工具、按什么顺序执行、出错怎么兜底。这篇面向本地 AgentSkills 开发调试场景我会给出可直接复制的SKILL.md骨架和config.toml配置片段然后演示改完文件后触发热重载、通过日志和调用结果验证 Skill 生效的完整动作。适合已经在本地跑 OpenClaw、想搞清楚 Skill 加载与热重载流程的开发者。下面所有操作都在本地工作区完成不涉及任何外部网络配置。2. 前置准备TaoToken 接入与 OpenClaw 环境确认在拆解 Skill 机制之前得先保证模型侧是通的否则你调半天 Skill最后发现是 API Key 没配好白折腾。我习惯用 TaoToken 来做模型接入它的 API 地址是https://taotoken.net/api兼容主流协议配置起来比较省事。第一步去控制台拿 Key。打开https://taotoken.net/console登录后进 API Keys 页面创建一个新 Key复制出来。这个 Key 只在本地配置文件里用别写进SKILL.md后面会讲为什么。第二步确认 OpenClaw 版本和 Skill 目录。在终端里跑openclaw --version ls -la ./skills如果./skills不存在手动建一个。OpenClaw 启动时会按优先级扫描四个位置工作区./skills最高然后是~/.openclaw/skills再是内置目录最后是skills.load.extraDirs里配置的自定义共享目录。本地调试优先用工作区目录改起来最方便。第三步把模型接入配置写进config.toml。OpenClaw 的配置文件一般在项目根目录或~/.openclaw/下具体看你启动方式。核心是让模型请求走 TaoToken 的 API 端点[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 [skills] enabled true watch true debounce_ms 250 [skills.load] extraDirs []这里watch true是热重载的总开关debounce_ms 250是文件监听的防抖窗口默认就是 250 毫秒。改完config.toml需要重启一次 OpenClaw之后改SKILL.md就不用重启了。注意api_key写在config.toml里不要写进SKILL.md的 frontmatter。Skill 的密钥通过skills.entries.*.env或apiKey字段注入只在执行期间生效不会泄漏到全局环境。3. 可复制配置SKILL.md 骨架与目录结构现在进入正题。一个 Skill 就是一个独立文件夹核心文件是SKILL.md可选扩展有bins/、references/、scripts/。先看目录结构./skills/ └── daily-report/ ├── SKILL.md ├── scripts/ │ └── gen_report.py └── references/ └── format-guide.mdSKILL.md的骨架长这样直接复制改--- name: daily-report description: 当用户要求生成日报、周报或工作总结时使用。汇总当日任务、代码提交和待办事项输出结构化 Markdown 报告。 metadata: openclaw: os: [darwin, linux] requires: bins: [python3] env: [REPORT_OUTPUT_DIR] triggers: - 生成日报 - 写周报 - 总结今天的工作 --- # 日报生成 Skill ## 使用场景 当用户明确要求生成日报、周报或说「总结今天的工作」时加载本 Skill。 ## 执行步骤 1. 调用 scripts/gen_report.py 收集当日数据。 2. 读取 references/format-guide.md 确认输出格式。 3. 将结果写入 $REPORT_OUTPUT_DIR 目录。 4. 把生成的报告路径和摘要返回给用户。 ## 边界与限制 - 只处理文本报告不生成图表。 - 如果 REPORT_OUTPUT_DIR 未设置提示用户先配置环境变量。frontmatter 里的metadata.openclaw是门控过滤的核心。os限定操作系统requires.bins检查命令行工具是否装了requires.env检查环境变量是否设了requires.config检查 OpenClaw 配置项。只有全部满足这个 Skill 才会被标记为「可用」否则在扫描阶段就被过滤掉模型根本看不到它。triggers是给模型看的触发提示不是硬匹配。模型会根据description和triggers自主判断当前请求要不要加载这个 Skill。所以描述写得越清楚命中率越高。环境变量注入在config.toml里配[skills.entries.daily-report] env { REPORT_OUTPUT_DIR /Users/you/reports }这样REPORT_OUTPUT_DIR只在daily-report这个 Skill 执行期间生效其他 Skill 和全局环境都拿不到隔离性比直接export好得多。4. 验证请求触发热重载并确认 Skill 生效配置写完了怎么确认 Skill 真的被加载、热重载真的生效分三步走。第一步启动 OpenClaw 并观察启动日志。终端里跑openclaw start --log-level debug启动日志里会打印扫描结果类似[skills] scanning workspace: ./skills [skills] found 1 skill: daily-report [skills] gate check daily-report: osok binsok envok - available [skills] injected 1 skill into system prompt看到available和injected就说明扫描、门控、注入三步都过了。如果显示filtered后面会跟原因比如missing bin: python3或env not set: REPORT_OUTPUT_DIR。第二步触发热重载。保持 OpenClaw 运行另开一个终端改SKILL.md里的description比如加一句「支持按项目分组」。保存后看 OpenClaw 日志[skills] file change detected: ./skills/daily-report/SKILL.md [skills] debounce 250ms elapsed, reloading [skills] reloaded skill: daily-report [skills] system prompt updated这三行出现说明热重载链路通了。debounce 250ms是防抖避免你连续保存时反复重载。下一轮对话就会用新版本的 Skill不用重启。第三步实际调用验证。在对话里输入「帮我生成今天的日报」观察 Agent 行为。正常流程是模型判断需要daily-report调用read工具读取完整SKILL.md然后按步骤执行脚本、读参考文档、写结果。日志里会看到[agent] model requested skill: daily-report [agent] reading SKILL.md for daily-report [agent] executing: python3 scripts/gen_report.py [agent] result written to /Users/you/reports/2025-01-15.md如果模型没调用 Skill先检查description和triggers是否覆盖了你的说法再确认门控条件是否满足。5. 本篇常见错排查热重载不生效与门控过滤踩坑调试 Skill 时报错和「静默失败」是两回事。下面这几个是我踩过的坑按排查顺序列出来。热重载没反应。先确认config.toml里skills.watch true且改完配置后重启过一次。然后看文件监听是否覆盖了你的目录——extraDirs里的目录默认也监听但如果你把 Skill 放在工作区外又没配extraDirs改了也不会触发。最后检查debounce_ms设太大比如 5000会让你以为没反应其实只是还没到时间。Skill 被门控过滤。日志里搜filtered后面会跟具体原因。常见的有requires.bins里的工具没装比如ffmpeg、uvrequires.env里的环境变量没在skills.entries.*.env里配os写成了macos而不是darwin。注意os用的是 Node 的process.platform值darwin、linux、win32。模型不调用 Skill。门控过了、注入也成功了但模型就是不调用多半是description写得太模糊。把「处理报告相关任务」改成「当用户要求生成日报、周报或工作总结时使用」命中率会明显提升。triggers里多列几个用户可能说的原话比如「总结今天的工作」「写个周报」。改了 SKILL.md 但模型还用旧逻辑。检查是不是改在了references/里的文件那些是第三级深度资源只在执行子任务时才加载改它们不影响 Skill 的触发判断。另外如果SKILL.md的 frontmatter YAML 格式错了比如缩进不对、冒号后没空格解析会失败整个 Skill 可能被跳过日志里会有parse error。环境变量泄漏或冲突。两个 Skill 都配了同名 env后加载的会覆盖先加载的。用skills.entries.skill-name.env的方式配每个 Skill 独立作用域避免全局export。6. 继续深入从验证到长期编码调试Skill 生效之后下一步就是把它用起来。如果你只是偶尔验证一下模型对 Skill 的理解可以直接在模型对话里试打开https://taotoken.net/models把SKILL.md的内容贴进去问模型「这个 Skill 会在什么情况下被触发」看它的判断和你的预期是否一致。这是最快的语义验证方式不用起 OpenClaw。如果你要把 Skill 机制接进日常编码流程比如让 Agent 在写代码时自动调用某个 Skill 做代码审查或生成提交信息那更适合用 Coding Plan。它面向长期编码和 Agent 场景配置一次就能持续用不用每次手动调。入口在https://taotoken.net/coding-plan。接入文档和 API Keys 管理分别在https://taotoken.net/doc和https://taotoken.net/api-keys。调试阶段建议把日志级别开到debug把[skills]相关的行单独 grep 出来看比翻全量日志快得多openclaw start --log-level debug 21 | grep \[skills\]最后说个实用技巧热重载虽然方便但改SKILL.md的 frontmatter 时如果 YAML 解析失败OpenClaw 会保留上一个可用版本不会让 Skill 直接消失。所以你可以放心改改坏了日志会报parse error修好保存就恢复。真正需要重启的只有config.toml里的skills.load和skills.entries变更SKILL.md本身永远是即改即用。