1. OpenClaw 不是玩具SKILL 才是它的“手”和“眼”你可能已经试过 OpenClaw 的 demo 页面看着那个带点科幻感的 UI 滑动、加载、弹出几个预设按钮心里嘀咕“这玩意儿真能干活”——答案是不能至少默认状态下完全不能。OpenClaw 本身只是一个轻量级的 Agent 运行时框架它不自带任何业务能力就像一辆刚下线的底盘没有方向盘、没有油门、连轮胎都没装。真正让它能点击网页、读取文档、调用 API、生成 PPT 的是 SKILL。不是“技能”的泛泛而谈而是指一套严格遵循 OpenClaw 协议、具备明确输入输出契约、可独立注册与卸载的可执行单元。网络上铺天盖地的“openclaw安装教程”90% 都卡在了这一步他们只装好了底盘却以为车已经能上路。我第一次部署时也犯了这个错。npx openclawlatest一行命令跑完服务起来了UI 也打开了但所有按钮都是灰色的点一下弹出 “The agent execution provider did not respond in time.” —— 这不是延迟问题这是根本没东西可执行。后来翻遍clawhub的 GitHub 仓库和零散的 Discord 讨论才明白核心逻辑OpenClaw 启动时会扫描skills/目录加载其中符合规范的模块没有 SKILL它就是个哑巴框架。那些热词里反复出现的 “superpowers skill”、“workbuddy skill”、“ppt skill”全都是别人写好的、可即插即用的“肢体”。而所谓“极简安装”本质不是降低技术门槛而是帮你绕过所有文档里没说清的隐含前提你必须先理解 SKILL 的结构契约再把它放进正确的位置最后让 OpenClaw 看得见、认得准、调得动。这不是一个npm install就能解决的依赖问题而是一次对 Agent 架构本质的实操确认。接下来我会带你从零开始亲手把第一个 SKILL 装进 OpenClaw让它真正动起来。2. SKILL 的真实面目一个被严重低估的标准化协议很多人把 SKILL 当成一个 npm 包或者一个 Python 脚本这是最危险的误解。SKILL 的核心不是语言而是协议。它定义了一套最小但不可妥协的接口规范任何想被 OpenClaw 调用的代码都必须满足这三条铁律必须有一个manifest.json文件这是 SKILL 的“身份证”。它不包含任何逻辑只声明这个模块叫什么name、版本号version、作者author、一句话描述description最关键的是entrypoint字段——它明确告诉 OpenClaw“我的主程序入口文件是index.js或main.py”。没有这个文件OpenClaw 根本不会尝试加载这个目录。必须导出一个符合签名的execute函数无论你用 JavaScript、Python 还是 Rust 写这个函数的签名必须是async execute(input: any): Promiseany。input是 OpenClaw 传来的 JSON 对象里面封装了用户指令、上下文、甚至临时文件路径Promise的返回值则必须是 OpenClaw 能解析的结构通常是{ success: true, result: xxx }或{ success: false, error: xxx }。我见过太多人直接写console.log(hello)就以为完成了结果 OpenClaw 等了半天收不到 Promise 的 resolve自然就超时报错。必须能被 Node.js 或 Python 环境直接执行OpenClaw 本身是一个 Node.js 进程它通过child_process.spawn启动你的 SKILL 进程。这意味着你的 SKILL 不能依赖全局安装的、OpenClaw 进程看不到的环境变量或二进制文件。比如你想用playwright自动化浏览器npx playwright install必须在 SKILL 目录内执行而不是在系统全局执行。这也是为什么热词里有 “npx playwright install 手动安装”——它不是可选项是必选项。提示clawhub仓库里那些官方 SKILL如cursor-pro-skill、nature-skill之所以能直接用是因为它们的manifest.json和execute函数都经过了严格验证。你下载下来解压第一件事就是打开manifest.json看entrypoint指向哪个文件再打开那个文件确认export async function execute(input)这行代码是否存在。这是你判断一个 SKILL 是否“合法”的最快方法。为了彻底厘清我们来解剖一个最简 SKILL 的完整结构。假设我们要做一个“回声”SKILL它什么都不做只是把用户输入原样返回。它的目录结构长这样echo-skill/ ├── manifest.json ├── index.js └── package.json # 如果是 JS 版本需要这个来管理依赖manifest.json内容如下{ name: echo-skill, version: 0.1.0, author: your-name, description: A simple skill that echoes back the input, entrypoint: index.js }index.js内容如下// 注意这是 SKILL 的主文件不是 OpenClaw 的主文件 // 它会被 OpenClaw 的子进程启动所以不能访问 OpenClaw 的全局变量 async function execute(input) { // input 是 OpenClaw 传来的对象通常包含 { query: xxx, context: {...} } console.log(Echo Skill received input:, input); // 必须返回一个 Promise且结构要清晰 return { success: true, result: Echo: ${JSON.stringify(input)} }; } // 这行是关键必须导出 execute 函数OpenClaw 才能调用 module.exports { execute };package.json如果需要{ name: echo-skill, version: 0.1.0, main: index.js, dependencies: {} }看到这里你应该明白了SKILL 安装的“极简”不在于命令有多短而在于你是否精准踩中了这三个协议点。漏掉任何一个OpenClaw 都会视而不见。那些“openclaw为什么会延迟”的抱怨绝大多数时候根源就在这里——框架在徒劳地等待一个根本不存在的execute函数的响应。3. 极简安装的真相三步走每一步都直击要害现在我们把理论落地。所谓“极简安装”是指在你已经拥有一个合法 SKILL比如上面的echo-skill的前提下用最少、最不可绕过的操作让它被 OpenClaw 成功加载。整个过程只有三步没有第四步多一步都是冗余。3.1 第一步找到 OpenClaw 的skills目录这是唯一合法的“插槽”这是最容易被忽略、也最致命的一步。OpenClaw 不会自动创建skills目录也不会从node_modules或全局路径去搜索 SKILL。它只认一个地方启动时所在目录下的skills/子目录。如果你是用npx openclawlatest启动的那么npx会把 OpenClaw 下载到一个临时缓存目录比如~/.npm/_npx/xxxxx/node_modules/openclaw然后在这个临时目录里找skills/。这几乎不可能成功因为临时目录你无法控制也无法持久化。正确做法是先创建一个你完全掌控的工作目录。例如在你的~/projects/下新建一个my-openclaw文件夹mkdir ~/projects/my-openclaw cd ~/projects/my-openclaw然后在这个my-openclaw目录里手动创建skills文件夹mkdir skills这个skills/目录就是 OpenClaw 唯一认可的“插槽”。所有你想让它用的 SKILL都必须放在这里。注意不要试图修改 OpenClaw 的源码去指定其他路径。虽然技术上可行但这会让你的部署失去可移植性一旦 OpenClaw 升级你的修改就会失效。坚守这个约定是长期维护的基石。3.2 第二步将 SKILL 复制到skills/目录命名即身份把你的echo-skill文件夹确保它包含manifest.json和index.js整个复制到刚才创建的skills/目录下cp -r /path/to/your/echo-skill ./skills/此时你的项目结构应该是~/projects/my-openclaw/ ├── skills/ │ └── echo-skill/ # 这个文件夹名就是 SKILL 的 ID │ ├── manifest.json │ └── index.js关键点来了echo-skill这个文件夹的名字就是这个 SKILL 在 OpenClaw 中的唯一标识符ID。OpenClaw 启动时会遍历skills/下的每一个子目录读取其manifest.json并用该目录名作为注册名。如果你把它复制成了skills/echo/那么你在 UI 里看到的技能名就是echo而不是echo-skill。很多初学者在这里栽跟头改了manifest.json里的name字段却忘了改文件夹名导致 OpenClaw 加载失败。3.3 第三步启动 OpenClaw并验证日志这是唯一的“验收测试”现在一切准备就绪。在my-openclaw目录下执行启动命令npx openclawlatest注意这次是在你自己的工作目录下执行而不是随便一个地方。OpenClaw 会自动找到同级的skills/目录。启动后终端会输出大量日志。不要只盯着最后那行 “Server running on http://localhost:3000”。你需要向上滚动寻找类似这样的关键日志行[INFO] Loading skill from: /Users/yourname/projects/my-openclaw/skills/echo-skill [INFO] Skill echo-skill loaded successfully with version 0.1.0如果看到了这两行恭喜你安装成功了。这意味着 OpenClaw 已经成功识别了你的manifest.json找到了index.js并验证了execute函数的存在。如果没看到或者看到Error loading skill...那就说明前面三步中某一步出了问题。最常见的错误日志是No manifest.json found in skill directory检查skills/echo-skill/下是否有manifest.json文件名是否拼写正确大小写敏感。Failed to load skill: Cannot find module index.js检查manifest.json里的entrypoint字段是否指向了正确的文件名以及该文件是否真的存在。Skill echo-skill failed validation: missing required field name检查manifest.json的 JSON 格式是否正确是否漏掉了逗号或引号。实操心得我建议在启动前先用ls -R skills/命令把整个skills/目录结构打印出来对照着日志逐行检查。这是一种“笨办法”但比对着空屏幕瞎猜高效十倍。另外OpenClaw 的日志级别默认是INFO足够诊断安装问题。不需要额外配置 debug 模式。4. 从“能装”到“能用”在 UI 中激活并调试你的第一个 SKILL安装成功只是万里长征第一步。接下来你要在 OpenClaw 的 Web UI 中让这个 SKILL 真正“活”起来接受指令并返回结果。这一步的关键在于理解 UI 的交互逻辑和调试技巧。4.1 UI 中的 SKILL 列表名字、状态与“启用”开关启动 OpenClaw 并打开http://localhost:3000后进入左侧导航栏的Skills页面。你会看到一个列表其中应该包含了你刚刚安装的echo-skill。列表中每一项显示Name即manifest.json中的name字段也是skills/下的文件夹名。Versionmanifest.json中的version。Status这是一个至关重要的状态指示器。它有三种可能Loaded表示 OpenClaw 已成功加载但尚未启用。Enabled表示该 SKILL 已被启用可以被 Agent 调用。Disabled表示该 SKILL 被禁用即使已加载也不会被调用。默认情况下新加载的 SKILL 状态是Loaded。你必须手动点击它旁边的Enable按钮才能让它变成Enabled。这一步是强制的没有捷径。很多用户以为装完就能用结果在 Chat 页面发指令UI 却毫无反应原因就在这里——SKILL 还躺在“加载区”没被“上岗”。4.2 在 Chat 页面发送指令构造一个有效的input对象现在切换到Chat页面。这里就是你和 Agent 对话的地方。但请注意Agent 不是通用聊天机器人它调用 SKILL 时会把你的自然语言提问转换成一个结构化的input对象再传递给execute函数。对于我们的echo-skill它最简单的用法就是让它“回显”你输入的原始内容。在 Chat 输入框里输入以下内容注意这是精确的指令格式/echo {query: Hello from OpenClaw!}这个/echo是 SKILL 的调用前缀它对应skills/下的文件夹名echo-skillOpenClaw 会自动截取-skill后缀。大括号{}里的内容就是execute函数收到的input参数。按下回车后UI 应该会立即显示一条新消息内容类似于Echo: {query:Hello from OpenClaw!,context:{}}这证明你的 SKILL 不仅被启用了而且execute函数成功执行并将结果返回给了 UI。4.3 调试的核心利用console.log和 OpenClaw 的实时日志如果结果不是你预期的或者 UI 显示错误不要慌。SKILL 的调试核心就是看日志。回到你启动 OpenClaw 的终端窗口那里一直在滚动输出日志。当你在 UI 中发送/echo指令时你应该立刻看到类似这样的日志[INFO] Executing skill echo-skill with input: {query:Hello from OpenClaw!,context:{}} [INFO] Echo Skill received input: {query:Hello from OpenClaw!,context:{}} [INFO] Skill echo-skill executed successfully如果console.log(Echo Skill received input:, input);这行日志没有出现说明execute函数根本没被调用问题出在 UI 的指令格式或 SKILL 的启用状态上。如果日志里出现了Echo Skill received input...但 UI 返回的是{success:false,error:...}那就说明你的execute函数内部抛出了未捕获的异常。这时你需要在index.js里加一层try...catchasync function execute(input) { try { console.log(Echo Skill received input:, input); return { success: true, result: Echo: ${JSON.stringify(input)} }; } catch (error) { console.error(Echo Skill execution failed:, error); return { success: false, error: error.message || Unknown error }; } }这样任何运行时错误都会被捕获并以结构化的方式返回给 UI同时错误详情也会打印在终端日志里方便你精准定位。经验分享我在调试一个调用外部 API 的 SKILL 时发现它在本地能跑通但部署到群晖 Docker 里就失败。最终排查发现Docker 容器里没有安装curl而我的 SKILL 用child_process.exec调用了它。这个错误在try...catch里被捕获日志里清晰地写着command not found: curl。如果没有这层保护错误就会静默消失让你陷入无尽的猜测。所以永远为你的execute函数加上try...catch这是 SKILL 开发者的护身符。5. 超越 echo构建一个真正有用的 SKILL——PPT 生成器现在你已经掌握了 SKILL 的安装、启用和调试全流程。是时候把这套方法论应用到一个更实际的场景了自动生成一份 PPT。这正是热词里反复出现的 “ppt skill” 的雏形。我们将基于echo-skill的骨架快速迭代出一个能干活的版本。5.1 需求分析与技术选型为什么选择pptxgenjs目标很明确用户输入一段文字描述比如“公司Q3销售数据总结”SKILL 要能生成一个.pptx文件并返回下载链接。技术上我们需要一个能在 Node.js 环境下生成 PPTX 的库。经过对比node-pptx功能较老社区活跃度低文档稀少。officegen支持 PPTX但生成的文件兼容性在新版 PowerPoint 中偶有瑕疵。pptxgenjs目前最成熟、最活跃的 Node.js PPTX 生成库API 清晰生成的文件兼容性极佳且有详尽的官方文档和大量示例。因此我们选择pptxgenjs。它是一个纯 JavaScript 库无需额外的系统依赖不像 Playwright 那样需要 Chromium安装和部署都极其简单。5.2 构建ppt-skill五步完成一个生产级 SKILL我们将在skills/目录下创建一个新的ppt-skill文件夹。整个过程就是对前面三步的复现和深化。第一步创建目录与manifest.jsonmkdir skills/ppt-skill cd skills/ppt-skill创建manifest.json{ name: ppt-skill, version: 0.1.0, author: your-name, description: Generates a PowerPoint presentation from text input, entrypoint: index.js }第二步初始化package.json并安装依赖npm init -y npm install pptxgenjs这会在ppt-skill/目录下生成package.json和node_modules/。注意node_modules/必须和index.js在同一个目录下因为 OpenClaw 的子进程会在这个目录里执行node index.js。第三步编写核心逻辑index.jsconst pptxgen require(pptxgenjs); async function execute(input) { try { // 1. 解析输入。我们约定 input.query 是 PPT 的标题input.content 是幻灯片内容数组 const title input.query || Untitled Presentation; const content input.content || [ { title: Slide 1, text: This is the first slide. } ]; // 2. 创建一个新的 PPTX 对象 const pres new pptxgen(); // 3. 添加封面页 pres.addSlide().addText(title, { x: 0.5, y: 1.5, w: 90%, h: 20%, fontSize: 36, align: center, bold: true }); // 4. 为每条内容添加一页 content.forEach((item, index) { const slide pres.addSlide(); slide.addText(item.title, { x: 0.5, y: 0.5, w: 90%, h: 15%, fontSize: 28, bold: true }); slide.addText(item.text, { x: 0.5, y: 1.2, w: 90%, h: 60%, fontSize: 18 }); }); // 5. 生成文件名使用时间戳避免冲突 const filename presentation_${Date.now()}.pptx; // 6. 将 PPTX 生成为 ArrayBuffer二进制数据 const pptxBlob await pres.write({ type: arraybuffer }); // 7. 将 ArrayBuffer 转换为 base64 字符串以便通过 JSON 传输 const base64String Buffer.from(pptxBlob).toString(base64); // 8. 返回结果包含文件名和 base64 数据 return { success: true, result: { filename: filename, data: base64String, mimeType: application/vnd.openxmlformats-officedocument.presentationml.presentation } }; } catch (error) { console.error(PPT Skill execution failed:, error); return { success: false, error: error.message || Failed to generate PPT }; } } module.exports { execute };第四步回到my-openclaw目录重启 OpenClawcd ../.. npx openclawlatest在 Skills 页面你应该能看到ppt-skill并将其Enable。第五步在 Chat 中测试在 Chat 输入框里输入/ppt {query: Q3 Sales Summary, content: [{title: Overview, text: Total revenue: $1.2M (15% QoQ)}, {title: Key Metrics, text: New customers: 240; Churn rate: 2.1%}]}按下回车。几秒钟后UI 应该会返回一个 JSON 对象里面包含filename和data。你可以把这个data字段的 base64 字符串粘贴到浏览器的开发者工具 Console 里用以下代码解码并下载const base64 你的base64字符串; const blob new Blob([Uint8Array.from(atob(base64), c c.charCodeAt(0))], {type: application/vnd.openxmlformats-officedocument.presentationml.presentation}); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download Q3_Sales_Summary.pptx; a.click(); URL.revokeObjectURL(url);这就是一个能真正“干活”的 SKILL。它不再是一个回声而是一个生产力工具。关键细节为什么要把 PPTX 转成 base64因为 OpenClaw 的通信协议是基于 JSON 的 HTTP 请求/响应。JSON 只能传输文本不能直接传输二进制文件。所以我们必须把二进制的.pptx文件编码成文本base64再通过 JSON 传回来。这是 SKILL 开发中一个非常典型的“协议适配”技巧几乎所有处理文件的 SKILL如 PDF 生成、图片处理都遵循这个模式。6. 从单点突破到生态构建如何管理你的 SKILL 仓库当你拥有了echo-skill和ppt-skill下一步自然就是思考如何让这些 SKILL 更好地组织、共享和复用这引出了 SKILL 生态的核心概念——本地 SKILL 仓库。它不是指clawhub那样的中心化平台而是你个人或团队的、可版本控制的、可一键部署的代码集合。6.1 为什么需要本地仓库一个真实的协作困境想象一下你和两位同事共同开发一个hermes-agent项目。你们各自负责不同的 SKILLA 负责飞书通知B 负责微信接入C 负责数据库查询。如果每个人都把自己的 SKILL 文件夹零散地丢在skills/目录下会出现什么问题版本混乱A 更新了飞书 SKILL 的 API 密钥但 B 和 C 不知道还在用旧版。依赖冲突A 的 SKILL 依赖axios1.0B 的 SKILL 依赖axios2.0放在同一个skills/目录下node_modules会互相覆盖。部署困难每次上线都要手动把三个文件夹复制过去漏掉一个功能就残缺。解决方案就是建立一个统一的skills-repo仓库。它的结构如下skills-repo/ ├── README.md ├── package.json # 全局依赖管理 ├── scripts/ │ └── deploy.sh # 一键部署脚本 ├── skills/ │ ├── feishu-skill/ # A 的飞书 SKILL │ ├── wechat-skill/ # B 的微信 SKILL │ └── db-skill/ # C 的数据库 SKILL └── .gitignore6.2 一键部署脚本deploy.sh的力量scripts/deploy.sh是这个仓库的灵魂。它是一个 Bash 脚本作用是把你仓库里的所有 SKILL干净、准确、可重复地复制到 OpenClaw 的skills/目录下。一个健壮的deploy.sh内容如下#!/bin/bash # 设置变量 SKILLS_REPO_DIR$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd) OPENCLAW_PROJECT_DIR$HOME/projects/my-openclaw SKILLS_TARGET_DIR$OPENCLAW_PROJECT_DIR/skills # 检查目标目录是否存在 if [ ! -d $SKILLS_TARGET_DIR ]; then echo Error: Target skills directory does not exist: $SKILLS_TARGET_DIR exit 1 fi # 清空目标目录谨慎确保这是你想要的 echo Cleaning target skills directory... rm -rf $SKILLS_TARGET_DIR/* if [ $? -ne 0 ]; then echo Error: Failed to clean target directory. exit 1 fi # 复制所有 SKILL echo Copying skills from repository... cp -r $SKILLS_REPO_DIR/skills/* $SKILLS_TARGET_DIR/ # 为每个 SKILL 安装其独立的 node_modules for skill_dir in $SKILLS_TARGET_DIR/*/; do if [ -d $skill_dir ] [ -f $skill_dir/package.json ]; then echo Installing dependencies for $(basename $skill_dir): cd $skill_dir npm ci --onlyproduction if [ $? -ne 0 ]; then echo Warning: Failed to install dependencies for $(basename $skill_dir). Skipping... fi fi done echo Deployment completed successfully! echo Please restart OpenClaw to load the new skills.这个脚本做了三件关键事安全清理先清空skills/目录确保没有残留的、旧版本的 SKILL。精准复制只复制skills-repo/skills/下的子目录不复制其他无关文件。独立安装为每个 SKILL 目录单独执行npm ci --onlyproduction保证每个 SKILL 的依赖都是隔离的、确定的。npm ci比npm install更可靠因为它严格依据package-lock.json安装杜绝了“在我机器上能跑在你机器上不行”的问题。6.3 团队协作的最佳实践Git Tag CI有了本地仓库团队协作就变得简单Git 分支为每个新 SKILL 创建一个 feature 分支开发完成后通过 Pull Request 合并到main分支。Git Tag每次发布一个稳定版本打一个 Git Tag比如v1.2.0。这让你可以随时回滚到任意一个历史版本。CI/CD在 GitHub Actions 或 GitLab CI 中配置一个简单的流水线。当main分支有新提交时自动运行deploy.sh脚本将最新版 SKILL 部署到你的测试服务器上。这样“部署”就从一个手动、易错的操作变成了一个原子化、可审计的步骤。最后一点体会我曾经管理过一个包含 17 个 SKILL 的项目。没有本地仓库之前每次更新一个 SKILL都要花半小时手动同步、测试、祈祷。引入skills-repo和deploy.sh后整个流程压缩到 30 秒。更重要的是它消除了所有关于“谁改了什么”的扯皮。因为每一次变更都在 Git 的历史里清清楚楚。SKILL 的管理本质上就是代码的管理而 Git就是最好的 SKILL 管理员。