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，我的真实感受是：技能体系的爽点不在“添加”这个动作，而在于“沉淀”。每写一个技能，你其实是在把自己一次性的操作过程，变成团队里可复用、可维护、可传承的自动化能力。所以每一次添加技能，都值得多花半小时把描述写清楚、把测试用例留下来、把文档补到位。这些看似不起眼的功夫，最后都会变成你技能库里最值钱的资产。
