OpenClaw 自定义开发指南

要解决什么问题

在 OpenClaw 生态里，很多「技能」只有一篇 SKILL.md，没有可执行脚本，Agent 只能当文档读，无法完成输入→运算→输出。反过来，即便你打算做工具型 Skill，也容易踩坑：front matter 缺字段、目录命名不规范、脚本不能独立跑、stdout 混进调试信息导致 JSON 解析失败，或不小心把 API Key 写进仓库。

本技能把「读规范」变成「动手搭」：按 OpenClaw 约定生成目录与文件，并在本机走完加载与调用链路，减少上线前才发现结构不对的情况。

技能如何工作

对话里按场景触发四条主流程：

• 创建新 Skill：你说「帮我创建一个 XX 技能」，会生成完整目录结构（含 SKILL.md、scripts/ 等）与起步内容。
• 结构验证：检查 SKILL.md front matter、scripts/ 是否存在、脚本是否可执行、敏感信息与体积限制（单文件 ≤50KB、总包 ≤5MB）等。
• 本地调试：模拟 OpenClaw 加载——解析 SKILL.md → 按说明执行脚本并传入 input → 收集输出，用于验证端到端是否可用。
• 代码模板：按需给出 file-io、http-request、data-process、report-gen、cli-parser 等标准库实现参考。

脚本侧约定统一：python scripts/xxx.py --input '{...}' 从 stdin/参数读 JSON，结果以 JSON 打印到 stdout；错误形态为 {"status": "error", "message": "..."}。设计强调 工具型优先、零第三方依赖、相对路径、参数化而非交互式输入。

适用边界与注意点

• 纯 Markdown、无 scripts/ 的技能在本规范下属于阅读型，不适合当作可运算工具发布。
• 模板与生成物面向 Python 标准库；若脚本出现 ModuleNotFoundError，需要改写成标准库方案。
• 调试时务必保证 stdout 仅输出最终 JSON，否则 Agent 侧解析会失败。
• 密钥与令牌应通过环境变量或参数传入，不要硬编码在脚本里。