从单个 skill.md 到 skill.md+ Python 双引擎架构： OpenClaw 集成优化实践

最近在做一个 AI 创作平台的 OpenClaw 集成，踩了一些坑，最后找到一个比较优雅的解决方案。分享一下这个过程，希望能给同样在做 Agent 集成的朋友一些参考。
背景
简单说下项目背景：我们做了一个 AI 创作平台，用户可以通过自然语言描述来生成图片、视频、音乐等内容。需要集成到 OpenClaw ，让 AI Agent 能够调用我们的能力。
第一阶段：纯 skill.md 方案
一开始的想法很简单——写一个详细的 skill.md ，告诉 AI 所有事情：
怎么构造 HTTP 请求
怎么处理错误和重试
怎么轮询任务状态
怎么验证参数
...
写了 500 多行，自以为很完善了，但实际用起来问题不少。遇到的问题：
执行不稳定 - 复杂的逻辑（比如"先检查状态，失败了先查积分，够就重试，不够就提示充值"），AI 经常会漏步骤或者理解错
Token 消耗大 - 大部分 token 都用在描述这些"基础设施"上了，真正用来理解用户意图的反而不够
维护成本高 - 每次改业务逻辑都要调整 skill.md ，然后重新测试 AI 能不能正确理解，很依赖经验
转折点
后来我们意识到一个问题：为什么要让 AI 去做它不擅长的事情？ AI 的优势是语义理解、意图识别、创意发散。AI 的劣势是精确执行、状态管理、复杂逻辑判断。那我们为什么不反过来：让 AI 只做决策，把执行交给传统代码？
第二阶段：skill.md + Python 脚本
新的思路很清晰：skill.md 负责：
说明有哪些能力可用
什么场景下使用
权限边界是什么
可以调用哪些命令
Python 脚本负责：
精确执行每个操作
处理所有异常情况
管理状态和轮询
保证结果一致性
举个具体的例子：以前 skill.md 要写一大段：
"查询状态时发送 GET 请求到某个端点，如果返回 running 就等 10 秒再查，failed 就检查错误信息，completed 就下载结果..."
现在 skill.md 只需要一行：
查询任务状态：python get_status.py <execution_id>
所有的轮询逻辑、超时处理、状态判断都在 Python 脚本里，AI 只需要知道有这个命令就行。
效果对比
直接看数据：
指标 纯 skill.md skill.md+ 脚本 改进
Token 消耗 ~2000 ~1200 -40%
调用成功率 ~75% ~95% +26%
迭代效率 改一次测半天 改了立马生效 10x
最明显的是稳定性提升了很多，因为确定性的逻辑都由代码保证了。
几个关键设计点
1. 职责分离
AI 只负责理解"用户想要什么"，不负责"具体怎么做"。比如用户说"做个产品广告"，AI 的任务是理解这是个视频创作需求，然后调用 generate_workflow.py 。至于这个脚本内部怎么和后端交互、怎么管理状态，AI 不需要关心。
2. 确定性封装
把所有需要精确执行的逻辑都封装到脚本里：
HTTP 请求的重试机制
状态轮询的间隔控制
超时的判断和处理
错误的分类和恢复
这些逻辑用代码写出来，比用自然语言描述给 AI 听要可靠得多。
3. 权限边界清晰化
在 skill.md 里明确定义哪些能做、哪些不能做。比如我们的 AccessKey 只能用于创作相关操作，计费、管理等功能明确告知 AI 这不在范围内。这样 AI 很清楚自己的边界，不会尝试越权操作。
编程哲学层面的思考
这件事给我们的最大启发是：好的 AI 应用架构，不是让 AI 变得更全能，而是让 AI 和代码各自做自己最擅长的事。具体来说就是：
不确定性 → AI （语义理解、意图识别、创意）
确定性 → 代码（精确执行、状态管理、错误处理）
这种"人机协作"的模式，比"全权交给 AI"要可靠得多。
实际案例
说个具体的。我们有个"失败节点重试"的功能：以前的做法：在 skill.md 里描述一整套重试逻辑，AI 经常搞不清楚什么时候该重跑整个流程，什么时候该只重试单个节点。现在的做法：skill.md 只告诉 AI 有两个命令可以用：
execute_workflow.py - 执行完整工作流
execute_single_node.py - 只重试单个节点
AI 根据当前情况选择调用哪个命令，具体的重试逻辑在脚本里实现。结果是 AI 再也不纠结这个问题了，因为它只需要做一个简单的选择题，不需要理解复杂的重试策略。
开源实现
我们的 Skill 实现已经发布到 ClawHub ，有兴趣的朋友可以看看具体是怎么做的：Skill 地址： https://clawhub.ai/hkljjkl/voooai 代码都是开源的，可以参考一下我们的 script 是怎么组织的，skill.md 是怎么简化的。
总结
核心观点就一个：在 AI 应用中，要懂得"有所为有所不为"。不要试图让 AI 包办一切，而是要：
识别出哪些是不确定的、需要语义理解的部分 → 交给 AI
识别出哪些是确定的、需要精确执行的部分 → 交给代码
设计清晰的接口让两者协作
这样的架构往往比"纯 AI"或者"纯代码"都要好。
最后，我们平台最近在做技术分享，欢迎大家来交流～ 也欢迎体验我们的产品，提提意见。