openclaw技能添加指南：从基础概念到安全配置与实战排查

1. 先搞清楚“给 openclaw 添加技能”到底在做什么1.1 openclaw 是什么技能为什么成了刚需openclaw 是一个偏向本地化部署的智能体执行框架核心思路是把大模型的对话能力、外部工具调用、自动化任务编排统一收口到一个可编程的运行环境里。你可以把它理解成一个“长着手脚的 AI 管家”模型负责思考openclaw 负责把思考变成能落地的动作比如读写文件、调用接口、操作浏览器、处理文档。但光有框架不够openclaw 天生只带一批基础能力。你要让它处理 PDF、查数据库、对接飞书或 Teams、整理 Obsidian 笔记就得往里面加“技能”。我现在说的“技能”指的不是模型参数里的能力而是 openclaw 里的技能包——由描述文件、脚本、工具定义和依赖声明组成的功能单元。添加技能本质上就是在做三件事告诉 openclaw“你能做什么”、给它“怎么做的工具”、再给它“什么时候该调用的判断依据”。很多刚上手的朋友会问大模型不是啥都会吗直接问它不就行了。这里有个关键差异。模型确实能聊出步骤但它不会真的替你打开浏览器、不会真的把文件从 A 目录挪到 B 目录更不会稳定地按你的私有协议去调一个内部系统。技能就是那层“从知道到做到”的桥。所以“openclaw 添加技能”这个话题本质上是在解决智能体落地时最核心的问题如何用最小成本让模型在可控、可复现、可维护的前提下完成真实工作。1.2 “添加技能”的三种典型需求场景我在实际使用中观察到想给 openclaw 添加技能的人需求大致能分成三类。第一类是“补基础能力”。比如官方技能库里没有 OCR 类技能你拿到一张扫描件模型能读到里面有几个字但没法准确抽取表格结构。这时候你需要的是一个专门的 OCR 技能包内部封装了识别模型和结构化输出逻辑。第二类是“接业务系统”。比如要把 openclaw 接入 Microsoft Teams让它能自动读取群消息、发送通知、归档会议纪要。这时候你加的不只是一个技能而是一整套连接器加技能的组合连接器负责打通渠道技能负责定义“在什么情况下、用哪些数据、做什么动作”。第三类是“做私有知识处理”。典型例子是把 openclaw 和 Obsidian 联动让它能读取你的笔记库按需生成摘要、反向链接或者周报。这时候技能里最重要的不是模型而是怎么限定目录范围、怎么解析 Markdown、怎么避免把不该公开的内容发出去。这三种场景对应三种不同的添加方式装现成的、改造官方模板、从零手写。我下面会把每一种都拆开讲。但开始动手之前建议你先想清楚一件事你要给 openclaw 加的到底是“一件新工具”还是“一套新流程”这两者的复杂度差了不止一个量级后续的配置思路也完全不同。2. 技能、插件、连接器这三者到底有什么分工2.1 三者的基础定义openclaw 的生态里经常同时出现三个词技能、插件、连接器。很多人第一次看文档时直接懵了因为有些教程把它们混着说有些甚至互相代指。我按自己的使用经验给一个相对清晰的分法。技能是最小的“能力单元”描述的是“openclaw 能完成某类任务”。举个例子一个“生成会议纪要”的技能它定义了输入会议录音文件、参会人列表、处理逻辑转写、分段、提炼议题、输出格式Markdown 纪要。技能可以纯靠提示词实现也可以靠脚本实现也可以两者结合。插件是可复用的功能模块通常解决的是“某一种技术能力”。比如 PDF 解析插件、Excel 处理插件、图像识别插件。插件不关心业务场景它只提供底层操作技能可以调用插件来组合出完整任务。连接器负责打通外部系统。Teams、飞书、钉钉、Obsidian、邮件服务器这些外部系统都有各自的鉴权方式、消息格式和接口约束。连接器把差异封装掉让技能可以用统一的方式去读写外部数据。2.2 从请求到响应的完整数据链路我画一个非常简化的流程来帮你理解三者在一次任务里是怎么协作的。假设用户对 openclaw 说“把今天群里关于项目进度的消息整理成周报发给飞书”。这条请求进来后openclaw 先通过连接器飞书/群聊连接器拉取当天消息模型根据技能描述命中了一个叫“群聊周报生成”的技能该技能内部调用了文本摘要插件来处理聊天记录生成周报后再通过飞书连接器把内容发送到指定群。看出来了吗连接器管“输入输出通道”插件管“通用技术能力”技能管“业务逻辑组装”。三者层层嵌套但边界很清楚。我在文档里看到官方把插件、技能、连接器并列介绍时也容易让人误解它们是互斥的。实际上一个完整任务往往同时用到三者只是配置位置和加载方式不同。2.3 搞混这三者会踩什么坑我见过最多的一个坑把技能写死成某个插件的专属调用。比如有朋友写了一个“导出 PDF 报告”的技能然后在技能描述里写死了“调用 pdf_export 插件”。看着没问题可一旦官方更新了插件接口技能立刻失效。正确做法是在技能里声明“需要能把数据渲染成 PDF 的能力”把具体插件选择交给 openclaw 的运行时去匹配。另一个坑是把连接器逻辑埋在技能脚本里。有人直接在技能脚本里写了 Teams 的鉴权代码结果换个环境密钥就乱套排查半天才发现连接器本身已经做过一层 Token 管理。记住一句话鉴权归连接器业务归技能通用能力归插件。这个原则虽然看起来简单但能帮你省掉大部分环境迁移时的痛苦。还有朋友把插件当技能用装了一堆插件却发现 openclaw 里根本找不到可用的“功能”。原因很简单插件只是提供了能力积木如果没有技能去定义“这个积木在什么时候、以什么方式被使用”模型不会自己知道该调用它。所以检查清单里应该多一步——装完插件后确认有没有对应的技能把它串起来。3. 添加技能前的前置检查清单3.1 环境与部署状态确认不管你是用 Docker 部署、用一键脚本部署还是直接本地跑源码动手加技能前都要先确认一件事openclaw 本身是健康的。我习惯用一个三连命令做体检查进程、查端口、查日志。如果是在 Linux 服务器上部署先确认主进程还在再确认配置里声明的内部端口没有被占用最后看一眼最近的日志里有没有报错。很多“技能加不上”的问题根子其实是主服务已经处于半崩状态只是表面还能响应简单对话。有一类非常典型的环境问题出现在 Windows 用户身上。openclaw 的部分版本依赖 WSL2 环境来跑沙箱或子进程如果你在 PowerShell 里执行wsl -- status时看到的是“WSL2 环境异常”或者“无法安全验证”之类的提示那不要急着去装技能。先把 WSL2 的内核更新、默认发行版设置、虚拟化支持这几项逐一确认否则技能里只要带脚本执行就大概率会莫名其妙失败。3.2 确认技能目录与配置文件位置openclaw 的技能通常放在独立的技能目录下不同安装方式目录位置不一样。Docker 安装的一般挂载在数据卷里二进制安装的默认在当前用户目录下的隐藏文件夹里还有一部分发行版允许你在主配置文件里自定义技能路径。我的建议是不要凭感觉找直接看主配置里的skills.path不同版本字段名可能不同但意思类似。如果配置文件里没写那就去官方默认目录找找到一个叫skills的文件夹就对了。确认了技能目录之后再看目录结构。官方模板通常长这样skills/ ├── pdf-summary/ │ ├── SKILL.md │ ├── requirements.txt │ └── src/ │ ├── parse_pdf.py │ └── summarize.py └── meeting-notes/ ├── SKILL.md ├── config.json └── scripts/每个技能一个独立文件夹文件夹名字就是技能名里面必须有一个 SKILL.md 作为入口描述。其余文件看需求。你要是看到某篇文章说“把整个技能仓库复制到某目录”先搞清楚它说的其实是工具仓库还是技能仓库这俩经常被搞混。3.3 权限、网络与依赖项检查很多技能需要联网下载模型、调用 API 或者安装 Python 依赖。如果你部署 openclaw 的机器处在内网环境一定要提前确认网络策略放行了哪些域名和端口。我遇到过几次真实案例技能装上了运行时模型也正常调用但拉取外部词典、下载字体、请求 OAuth 授权时全部超时排查到最后发现是防火墙把相关端口堵了。另外给技能单独建运行用户是更稳妥的做法。用 root 跑 openclaw 本身就不推荐如果再用 root 去跑技能里的脚本一旦技能代码有漏洞风险会放大很多。我自己的习惯是创建一个叫openclaw的系统用户技能目录的所有者设为该用户脚本执行权限严格控制。这个步骤看起来繁琐但对长期运行、涉及敏感数据的智能体来说值得花这几分钟。依赖方面要特别留意版本冲突。openclaw 自带了一个 Python 运行时很多技能会把依赖装到同一个环境里。装技能装多了以后你会发现经常出现“这个技能要求 requests 2.31那个技能只兼容 2.28”的惨案。合理的做法是每个技能根据自己的依赖声明创建虚拟环境或者在技能配置里显式声明运行所需环境不要让所有技能共享同一个全局依赖目录。4. 四种常用技能添加方式与实操步骤4.1 方式一从社区技能库引入现成技能最省力的方式当然是“白嫖”社区里已经做好的技能。现在 openclaw 生态里有不少公开技能仓库有人整理了常用技能合集也有人专门做技能索引站。找到合用的技能包之后下载解压到技能目录即可。理论上这就算完成了但我强烈不建议直接复制完就收工。拿到一个第三方技能先看三样东西。第一SKILL.md 里声明的适用范围和依赖第二脚本里有没有写死绝对路径、私有 Token、外部服务地址第三它的许可证允许不允许你在自己的项目里使用。我见过有人把技能里的测试密钥直接带到了生产环境结果所有请求都打到别人的服务器上白给别人交了学费。引入后还要跑一次“最小验证”。用技能描述里给出的典型示例喂一条最简单的请求看能不能走通。比如 PDF 摘要技能就找一个小 PDF 试跑别一上来就处理几百页的大文件。这一步能帮你快速区分“技能本身的问题”和“环境配置的问题”。4.2 方式二手工新建一个自定义技能如果你的需求比较特殊社区里找不到现成的就得自己写了。这里我以“给一个文本文件生成结构化摘要”的技能为例讲清楚完整流程。第一步创建技能目录。起名要短且描述性强比如simple-file-summarizer。目录名最好不要用空格和中文避免跨平台兼容问题。第二步编写 SKILL.md。这是最关键的文件模型靠它来判断“什么时候该调用这个技能”。内容要有三块技能描述、输入参数、输出格式。描述要写清楚这个技能是干什么的、适用于什么场景、不适用于什么场景。我写了个参考模板# Simple File Summarizer ## 用途 为本地文本文件生成结构化摘要支持提取核心观点、关键数据、待办事项。 适合快速浏览长文档不适合处理扫描件和图片类文件。 ## 输入 - file_path: 文件绝对路径仅支持 txt / md / json 格式 - length: 摘要长度可选 short / medium / long默认 medium ## 输出 返回 Markdown 格式摘要包含 - 一句话概述 - 核心观点列表 - 关键数据表 - 待办或后续动作第三步实现脚本。我建议脚本入口保持简单统一从标准输入读取参数、从标准输出返回结果。这样做的好处是将来不管 openclaw 的调用方式怎么变你的技能脚本都不用跟着改。核心逻辑可以是读文件、分段、按参数调用模型、整理输出。这里注意不要自己在脚本里再写一套模型调用逻辑直接用 openclaw 提供的模型访问接口或上下文变量否则你会在“模型入口维护”上耗费大量时间。第四步注册技能。有些版本支持自动扫描技能目录有些需要你手动在主配置里把技能目录添加进去。改完配置后重启 openclaw 或者执行一次技能刷新操作再在技能列表里确认能看到新技能。看不到的话回看一下日志基本能在里面找到扫描路径和解析错误。4.3 方式三通过连接器把外部系统变成技能这种方式比较有趣适合把 Obsidian、Teams、飞书这类系统变成 openclaw 的“手脚”。核心思路是连接器负责打通系统技能负责定义业务动作。以接入 Microsoft Teams 为例流程大致是先在 openclaw 里创建或启用一个 Teams 连接器配置填入你在 Azure 应用注册里拿到的应用 ID、租户 ID、客户端密钥等凭证。完成授权之后openclaw 能收到来自 Teams 的事件通知也能主动发消息。但到这一步openclaw 只是“能连上 Teams”并不代表“会干活”。要想让它自动把群聊里的问题汇总成日报还得再配一个技能。这个技能要做的事包括设置触发条件比如“每天早上 9 点”或“当群里出现 日报 关键词”、定义消息获取范围你所在团队的哪个频道、设计输出模板、确定发送目标。技能配置好了人才真正感觉到 openclaw 是一个“会干活的同事”而不是一个“能聊天的接口”。我特别提醒一点连接器的鉴权凭证一定要放在独立配置里不要让技能脚本直接读取这些敏感值。技能里的敏感变量要通过 openclaw 的密钥管理机制来引用而不是把 Token 直接写在 SKILL.md 或者 .py 文件里。这个习惯我在下文单独展开。4.4 方式四把本地模型接入作为技能推理后端有时候你不想每次调用技能都走云端大模型接口尤其是处理隐私数据或离线场景。这时候可以把一个本地小模型比如 Qwen2.5-3B接进来作为技能的内部推理引擎。做法上先确保本地模型服务已经跑起来比如通过 Ollama、vLLM 或者 Transformers 起一个 OpenAI 兼容的接口。然后在技能配置里把推理地址指向本地服务并设置合理的超时时间和最大 Token 数。这里有个容易忽略的点本地小模型的能力边界比云端大模型明显弱技能内部如果一次性塞进太多内容或者提出过于复杂的任务效果会大打折扣。我的经验是给本地模型配技能时要把任务拆得更细、提示词写得更明确。同样一个“总结邮件”技能云端模型只需要一句“总结这封邮件”本地模型可能需要你明确告诉它“提取发件人、主题、关键要求、截止时间并以列表输出”。另一个要注意的是并发。3B 级别的模型虽然不大但如果 openclaw 同时触发了多个技能实例显存或内存会被直接打满。建议在技能配置里限制并发数或者在模型服务端做好排队避免任务批量进来时直接 OOM 崩掉。5. 技能开发中的关键配置与敏感信息处理5.1 技能描述与触发参数的设计技能能不能被正确调用很大程度取决于 SKILL.md 写得好不好。模型是靠语义匹配来找技能的不是靠硬编码。描述太含糊它会在多个技能之间犹豫描述太死板稍微换一种说法它就匹配不上。我总结了一个好用的描述结构先说“这是什么”再说“能做什么”接着说“不能做什么”最后给一两个典型调用示例。对比一下# 差劲的描述 处理 PDF 文件。 # 还不错的描述 读取 PDF 文档并提取文本内容。适用于 PDF 转文本、PDF 全文搜索、PDF 内容摘要。不适用于扫描件、图片型 PDF、加密文档。典型用法把 report.pdf 的内容整理成要点。参数设计上要尽量“少而稳”。每次技能调用都要经历模型生成参数的过程参数越多模型出错或生成无效参数的概率就越高。能用路径参数就不用传文件内容能用默认值就不必强制调用方填写。我甚至习惯给每个参数写清楚允许的取值范围比如“length 仅接受 short、medium、long 三个值”这样能显著降低参数校验的失败率。5.2 敏感变量与权限隔离技能开发里最容易被忽视、也最危险的问题就是敏感信息泄露。一个合格的技能不应该在代码里硬编码任何密钥、Token、数据库密码。openclaw 一般提供密钥管理能力或者支持通过环境变量注入敏感值。你需要在技能配置里声明需要的变量名然后在运行时统一注入。比如一个技能需要调用某个内部知识库 API在 SKILL.md 的配置节里写成- env.API_KEY: 知识库接口鉴权密钥由外部环境统一注入 - env.API_BASE_URL: 知识库接口地址脚本里只读这两个环境变量而不是直接写死。这样做的直接好处是技能包可以被安全地复制、分发、备份不会因为一次仓库泄露就把所有密钥搭进去。另一个好处是部署环境切换时只需要改环境变量不用改技能代码。权限隔离方面我强烈建议不要给技能脚本放开所有系统权限。有些技能需要写临时文件、需要访问网络、需要执行外部命令你可以在 openclaw 的权限模块里逐一配置允许项。宁可先收紧再逐步放开也不要一开始就给个无限制的权限等到出了事故再回头追查。5.3 技能测试与回滚我接触过不少朋友技能一写完就直接上生产结果用户随便输入一条边界情况技能就崩了。正规一点的流程至少要有这么几步单测脚本、模拟调用、灰度切换。单测脚本不用写得特别复杂核心是构造几个典型输入跑一遍脚本逻辑验证输出结构是否符合 SKILL.md 里的声明。比如摘要技能我至少会测空文件、超长文件、包含特殊字符的文件、格式损坏的文件这四类。模拟调用测试则是在 openclaw 的沙箱环境中不实际触发外部系统只测试技能内部逻辑是否能正常跑通。这一步能抓出不少依赖问题、路径问题、权限问题。最后是灰度切换。如果技能会替换现有流程不要直接停旧上新的。我见过一个更稳妥的做法把新技能用另一个技能名注册先让它和旧技能并行跑一段时间人工对比输出质量确认稳定后再把旧的禁用。这个流程多花几天时间但能避免很多“上线半小时就回滚”的尴尬。6. 常见问题与排查技巧实录6.1 WSL2 环境校验失败openclaw 无法启动这是 Windows 用户碰到概率最高的一个问题。现象一般是启动 openclaw 时提示 WSL2 环境无法安全验证让你在 PowerShell 里运行wsl -- status检查。很多人照着做了发现 WSL 状态显示正常但 openclaw 还是起不来。原因通常是 openclaw 检测 WSL2 的方式依赖某个具体版本特性而你的系统里装了多个 WSL 发行版或者默认发行版指向了 WSL1。排查步骤如下先运行wsl -- list --verbose看默认发行版后面写的是 1 还是 2。如果是 1执行wsl -- set-version 发行版名 2升级。升级完再刷新虚拟化平台。还有一类情况是 Windows 的“虚拟机平台”功能没有打开。可以在 PowerShell 里以管理员身份执行命令启用可选功能然后重启系统。这里我多说一句尽量不要在冒烟测试阶段就跳过这个步骤否则后续带脚本的技能会在执行子进程时频繁报错而且问题看起来千奇百怪实际都是同一个根因。6.2 技能列表里看不到刚添加的技能技能文件已经放进目录了配置文件也改了但 openclaw 的技能列表里就是找不到。这个问题我遇到过很多次原因一般集中在三处。第一目录扫描路径不对。你放技能的位置和 openclaw 实际扫描的位置不是同一个目录。解决方法是查看运行时日志确认服务启动时扫描的路径到底是哪个。第二SKILL.md 格式解析失败。YAML 或 Markdown 头部的缩进有一个空格不对解析器就可能静默跳过整个目录。优先检查 YAML 文档分隔符前后是否有多余字符。第三技能被错误信息拦截。有些技能目录里缺少必要文件或者配置文件引用了不存在的依赖导致 openclaw 在加载时主动跳过并写入错误日志。看到技能列表没有变化时别急着反复重启先去看一眼启动日志里关于该技能的报错行。6.3 技能执行时报错缺少依赖 / 权限拒绝技能进了列表但一运行就报错最常见的两类是缺少依赖和权限拒绝。缺少依赖相对好排查看报错里提到的包名手动安装即可。但要注意安装依赖前先确认当前 Python 环境是不是 openclaw 实际使用的环境。有些人用系统 Python 装了一堆包结果发现 openclaw 跑在自己的虚拟环境里等于白装。权限拒绝则要稍微仔细一点。技能脚本可能试图访问一个它没有权限的目录或者尝试监听某个端口或者试图读取环境变量。排查时先看报错是发生在“脚本启动前”还是“脚本运行中”。前者多半是 openclaw 的权限模块拦截了后者多半是系统文件权限没配好。前者的处理方式是去技能配置里声明相应权限后者的处理方式是检查目录所有者和脚本执行位。我还有一个建议把技能日志打开到 debug 级别第一次跑的时候就留一份完整日志。技能脚本里多打印几步状态不要等出错了再回头改代码这也是我踩过很多次坑之后养成的习惯。6.4 技能“能用但不好用”上下文与召回优化最后说一个相对隐蔽的问题技能能跑但效果不稳定。同一个请求有时触发了技能有时没触发有时输出准确有时输出跑偏。这大概率不是脚本的问题而是技能召回和上下文管理的问题。召回不稳常见原因是 SKILL.md 的描述与用户真实表达的差距太大。解决办法是积累实际的用户问题把它们整理成同义表达补充到技能描述中。你也可以适当调整技能的匹配阈值或启用关键词提示但要小心别做得太死板否则换种说法又不灵了。输出质量不稳常见原因是上下文里塞进了太多无关信息。技能在处理长文档时尤其明显模型注意力被大量噪声分散。解决办法是把技能内部流程改成“先裁剪再分析”——先通过规则或摘要把篇幅压到一个模型更舒适的范围再让模型深入理解。比如客户反馈“我会先做粗提取再做精加工”。这个两步走的思路比让模型一次读完几百页再输出要稳定得多。这个优化过程确实没有标准答案但有一点是通用的多记录失败案例。我自己的习惯是每个技能旁边放一个 examples 文件夹既放标准成功案例也放曾经失败的输入和修正后的预期输出。技能升级时用这些案例做回归测试确保新版本没有“修好一个 bug 又弄坏三个场景”。最后分享一点个人体会玩了这么久的 openclaw我的真实感受是技能体系的爽点不在“添加”这个动作而在于“沉淀”。每写一个技能你其实是在把自己一次性的操作过程变成团队里可复用、可维护、可传承的自动化能力。所以每一次添加技能都值得多花半小时把描述写清楚、把测试用例留下来、把文档补到位。这些看似不起眼的功夫最后都会变成你技能库里最值钱的资产。