经常有朋友在后台问我“你说 OpenClaw 是个全能 AI 助理那它能不能干这个、能不能干那个”每次我都回一句能但要先给它装个“新 App”。这篇是《大白话聊 OpenClaw》系列的第 8 篇我想把这件事彻底讲明白。这里说的 App不是手机上那种点一下图标的东西而是 OpenClaw 生态里的技能Skill、插件Plugin、工具Tool叫法好几个本质上都是同一类东西。默认装好的 OpenClaw就像一台刚拆封的手机打电话、发短信、上自带浏览器都行可你要它读 PDF、整理 Obsidian 笔记、定时跑脚本、自动查天气就得一个个往里装“应用”。这篇文章适合所有刚开始折腾 OpenClaw 的人也适合已经装了一堆技能但经常踩坑的老手——我尽量用大白话把原理、步骤、坑都一次说清楚。1. 先搞清楚给 AI 装“新 App”到底装的是什么1.1 为什么 AI 需要“新 App”先说说 OpenClaw 本体能干什么。装完默认状态下核心 Agent 只保证几件事跟大模型对话、执行终端命令、读写本地文件、维护会话记忆。听起来不少但这些都是“地基能力”不是“业务能力”。真实的个人助理场景全是组合拳比如“帮我把 Obsidian 里昨天的日记整理成周报草稿顺便附上本周天气”这种需求核心 Agent 根本不知道 Obsidian 的数据存在哪个目录、用什么格式存储、天气数据从哪里来。它缺的不是对话能力而是针对具体领域的“知识”和“操作能力”。这些缺失的部分就得靠外部模块注入这就是给 AI 装 App 的本质。手机系统的思路完全一样操作系统保持精简稳定五花八门的需求交给独立应用去实现。Agent 框架如果什么都内置很快就会变成一个大泥球改一处崩三处维护成本直接爆炸。OpenClaw 走的就是“最小核心 模块化能力”这条路每个技能只负责一件具体的事装到系统里AI 才能知道怎么用它。举个我自己的例子我前阵子让它把一个 Markdown 日记文件转成简洁周报核心 Agent 完全不碰。提示词写得再漂亮也没用因为它根本不知道 Obsidian 的库结构长什么样。后来装了一个 obsidian 相关的技能它自己就会去读库目录、解析文件、按模板生成内容一次搞定。这件事给我最大的启发是提示词解决的是“怎么说”技能解决的是“会什么”两者缺一不可。1.2 OpenClaw 里的“App”到底长什么样很多人第一次打开技能目录会懵这玩意儿怎么不是个安装包没错OpenClaw 的技能本质上就是一个普通文件夹里面塞了一份“说明书”和一堆“工具脚本”。最核心的文件通常叫 SKILL.md相当于 App 的安装说明和操作手册二合一。文件开头有一段结构化信息写着这个技能叫什么、是干什么的、什么时候该用、有哪些参数正文部分则是给大模型看的详细使用说明。旁边是真正的执行代码可以是 Python 脚本、Node.js 脚本甚至直接是几条命令。AI 接到你的请求后会先看所有已装技能的说明书判断哪个技能适合当前任务然后按说明书调用对应的脚本。这里有个特别关键的机制大模型不是把所有技能挨个试一遍而是靠“读描述”来决定用哪个。所以技能描述写得好不好直接决定 AI 会不会在关键时刻想起它。我把这个机制叫“技能的选择权在模型手里但提示权在你手里”——你写不清楚它就用不上这后面实操时还会反复提到。2. “App 商店”在哪技能来源和安装前的功课2.1 三个靠谱的技能来源刚接触 OpenClaw 的人第一个问题肯定是我去哪找这些“App”我的经验是分三个层次。第一层是官方内置技能。OpenClaw 装完自带一批常用技能比如网页抓取、文件整理、代码搜索这类基础能力覆盖日常 80% 的简单需求。我建议新人先把内置技能摸一遍很多时候你以为要装新东西其实内置的就够用了。第二层是社区仓库。GitHub 上有人维护各种技能集合搜索 OpenClaw skill 相关的话题就能找到不少。我装过的就有 obsidian 笔记管理、办公文档生成、定时任务调度这些。社区资源的好处是现成、功能丰富坏处是质量参差不齐装之前必须把 README 读完重点关注维护时间、依赖声明和 issue 区有没有人报问题。第三层是自己写。最靠谱的永远是自己写的因为只有你自己最清楚需求。我后面会专门用一节讲怎么写一个最简单的技能真的不难半小时就能跑通。2.2 安装前必须做的三个功课用生活类比来说给 OpenClaw 装技能跟手机装 App 一样装之前也得看“权限列表”。我每次装社区技能前雷打不动做三件事。第一读 description描述。看它自己怎么介绍功能。如果描述含糊其辞比如只说“帮助用户处理各种文件”这种技能装上之后大模型也大概率不会主动调它因为模型不知道什么时候该用。第二看依赖。技能要跑起来需要哪些 Python 包、Node 包、系统工具依赖声明是否写清楚了我见过不少技能的 README 只字不提依赖结果装完一调用就报 module not found。第三查权限和网络行为。这个技能会不会访问外网会不会读写敏感目录有没有执行高危命令的可能一个“词典查询”技能如果要求读取你整个用户目录那就要警惕了。千万别嫌这三步麻烦。技能本质上是一段可以在你机器上执行任意脚本的代码来路不明的东西装进去等于把家门钥匙交给了陌生人。我自己现在装新技能都会先在隔离环境里跑一遍确认没有奇怪行为再正式用。3. 实操把新技能一步步装进 OpenClaw3.1 安装前的环境检查清单很多人卡在“装不上”这一步其实大部分问题出在环境而不是 OpenClaw 本身。我每次排查外部技能安装问题第一件事就是检查环境。OpenClaw 是 Node.js 应用所以 Node.js 版本必须达标。我建议不低于 18最好直接用 20 LTS。然后是 Git因为很多社区技能要用 git clone 拉取。Windows 用户还要特别留意 WSLOpenClaw 在 Windows 上推荐跑在 WSL2 的 Ubuntu 里如果 WSL 版本不对后面全是坑。先跑一遍检查命令node -v npm -v git --version wsl --status # Windows 下用顺便提一句如果你想把手机变成 OpenClaw 的遥控器还会涉及 Windows companion 的配置这个属于“外接设备”而不是技能本身但环境检查阶段一起确认了更省事。companion 的核心就两件事服务地址和令牌两样配对了才能连上。3.2 三种安装方式怎么选我用了这么久实际就三种装法没有更复杂的了。安装方式操作适合场景直接复制目录把技能文件夹丢进~/.openclaw/skills/自己写的或别人发来的技能包git clonegit clone 仓库地址到技能目录装社区仓库里现成的技能命令行管理openclaw skills add 名字或地址版本较新、带配套 CLI 的环境直接复制目录是最朴素也最不容易出错的方式。前提是技能文件夹结构完整SKILL.md 在最外层脚本文件都在里面。放好后不需要编译重启 OpenClaw 就会自动扫描加载。git clone 适合装 GitHub 上持续维护的仓库。这里有个细节clone 下来的仓库一般带着.git目录和一堆说明文件不影响使用但建议 clone 到独立的技能目录里别跟其他技能混在一个目录下不然 OpenClaw 扫描的时候容易识别错。如果你的 OpenClaw 版本带命令行管理工具那体验最顺。做一次openclaw skills list看看当前装了哪些技能openclaw skills add装新的openclaw skills remove卸载。命令名称不同版本可能有差异记不住的话用--help看一眼就懂。3.3 装完别急着用三步验证法装完技能不等于它能正常工作我吃过太多“看起来装了但实际没用”的亏。现在每次装完都按三步验证。第一步用openclaw skills list确认技能出现在加载列表里。这一步检查的是“OpenClaw 认不认识它”。第二步新建一个会话直接用明确的语言要求 AI 调用这个技能比如“用天气技能查一下北京的天气”。如果它能正确响应说明基本链路通了。第三步如果想让 AI 自动调用还要开 debug 模式看日志。启动时加--debug然后在日志里找 tool call 的记录看模型有没有在合适的时机选中这个技能、参数传得对不对。很多新手装完技能发现 AI 一直不用它就以为是技能坏了。其实多半是描述写得含糊模型不知道什么时候该调用。还有一种是权限拦截——技能想执行某个操作但审批配置没放行调用被静默拦下来了。这些问题后面章节会逐个展开。4. 配置与权限让“新玩具”不失控4.1 技能权限模型该问就问别图省事给 AI 装了一堆技能之后最危险的不是装不上而是装上了随便跑。OpenClaw 的权限审批机制本质上就是给技能的执行行为分级哪些操作可以直接做哪些操作必须先问用户哪些操作干脆禁用。我的配置习惯是这样的{ permissions: { allow: [obsidian.read, weather.query], ask: [shell.execute, file.delete, network.request], deny: [] } }allow 里放的是低风险、高频率的操作比如读笔记、查天气直接放行省得每次弹确认。ask 里放的是有副作用的操作比如执行 shell 命令、删文件、发起网络请求这些都值得停下来问一句。deny 默认留空但如果你发现某个技能行为异常直接把它对应的操作塞进 deny 就行。有人觉得每次弹确认很烦想全部 allow。我劝你别这么干。AI 的技能编排偶尔会做出人意料的操作尤其是同时装了多个技能的时候组合调用可能触发你想都想不到的路径。宁可多一次确认也好过它直接删掉你一个重要文件。4.2 API Key 怎么管永远别写进技能文件很多技能要调外部服务比如天气接口、搜索接口、日历同步都需要 API Key。这个环节有个我反复强调的规矩API Key 绝对不要硬编码在技能文件里。原因很简单技能文件是可能被分享、被上传到 GitHub 的。我见过有人把自己的付费 API Key 写死在技能脚本里然后整个仓库公开出去几天时间被刷了几百块钱。正确做法是放环境变量或者放在项目根目录的.env文件里技能运行时从环境读取WEATHER_API_KEYyour_key_here技能脚本里用os.getenv(WEATHER_API_KEY)读取。这样即使脚本被人看到也拿不到你的真实密钥。另外给外部 API 服务尽量开用量上限这是最后一道保险。4.3 接本地小模型qwen2.5-3b 这类怎么配合如果你不想所有请求都走云端 API本地模型是一条路。很多人问过我怎么把 Qwen2.5-3B 这类本地小模型关联到 OpenClaw我的建议是可以用但要分清场景。本地小模型的优势是隐私、免费、响应快缺点是工具调用能力明显弱于云端大模型。所谓工具调用就是模型能不能正确理解“该调用哪个技能、传什么参数”。我实测下来的感受是3B 级别的模型做简单的单技能调用还凑合比如“查天气”“读文件”但让它同时协调两三个技能、处理复杂依赖链的时候经常选错工具或者参数传得莫名其妙。所以我现在的做法是混合配置日常对话、简单查询走本地小模型涉及复杂技能编排的任务在请求里指定走云端强模型。OpenClaw 可以在配置里按任务类型指定不同的模型提供方相当于给不同难度的工作安排不同的“大脑”既省钱又不耽误事。5. 常见问题与排查实录5.1 WSL 环境报错请先运行 wsl --statusWindows 用户最常见的拦路虎是启动 OpenClaw 时报类似“无法安全验证 WSL2 环境”的错。别慌先在 PowerShell 里跑一下wsl --status看看状态。我排查下来八成的情况是 WSL 内核太旧或者默认版本还是 WSL1。OpenClaw 需要 WSL2因为 WSL1 的文件系统性能和兼容性都跟不上。解决步骤很简单先wsl --update更新内核再wsl --set-default-version 2把默认版本切到 2最后wsl -l -v确认发行版已经是 VERSION 2。如果改了还不行直接把发行版wsl --unregister后重装一遍代价最小。5.2 Node.js 版本太老依赖装不上装技能时经常遇到npm install失败报 engine 不兼容十有八九是 Node.js 版本太老。社区技能更新很快很多已经要求 Node 18 甚至 20 以上。解决办法是别去官网手动装用 nvm 管理版本nvm install 20 nvm use 20 node -v版本切好之后如果技能目录里已经有残留的node_modules先删掉再重装避免新旧依赖混在一起rm -rf node_modules package-lock.json npm ci5.3 技能装了不生效先查三件事如果skills list里能看到技能但 AI 就是不用按顺序排查三件事。第一SKILL.md 的格式是不是规范front matter 里必填字段有没有漏。第二技能目录名有没有特殊字符有些版本对目录名很敏感建议纯小写加连字符。第三进程缓存——改过技能文件后没重启加载的还是旧版本。先重启再看日志。还有一个特别隐蔽的原因描述写得太泛。比如你把技能描述写成“处理文件相关任务”模型看到这个描述根本不知道应该在什么场景下调用它。把描述改成“当用户需要汇总、转换或分析 Markdown 笔记时使用”模型一眼就知道什么时候该出手。5.4 Python 依赖冲突用虚拟环境隔离OpenClaw 的很多技能是 Python 写的依赖冲突是家常便饭。最常见的是技能 A 需要 requests 2.x技能 B 需要 requests 3.x结果互相覆盖一调用就报错。我在每个依赖复杂的技能目录里单独建虚拟环境把依赖锁在里面cd 技能目录 python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt这样每个技能用自己的一套依赖互不干扰。需要留意的是脚本开头的 shebang要指向虚拟环境的 Python 解释器否则系统还是用全局 Python 跑。5.5 问题速查表现象大概率原因处理办法启动报 WSL 验证失败WSL 版本或内核问题wsl --update 切到 WSL2npm 安装报 engine 不兼容Node 版本太老nvm 切到 20 LTS列表有技能但 AI 不调用描述不清晰或权限拦截改 SKILL.md 描述 查日志调用技能报 module not foundPython 依赖缺失建 venv 装依赖核对 shebang装完新技能旧技能失效依赖互相覆盖给每个技能独立虚拟环境技能卡住一直无响应模型选错技能或参数开 debug 看 tool call 日志6. 进阶半小时写一个自己的“新 App”6.1 一个最小的技能结构老看别人的技能不如自己写一个。一个最简单的技能目录长这样my-weather/ ├── SKILL.md └── scripts/ └── weather.py就两个文件一个说明书一个干活脚本。够简单吧。目录名就是技能名建议全小写加连字符避免奇怪的字符导致扫描失败。脚本可以是 Python、Node.js或者任何你熟悉的语言能执行的东西关键是 SKILL.md 要把调用方式写清楚。6.2 SKILL.md 的写法与字段含义SKILL.md 是最重要的文件。我用一个天气技能的模板演示--- name: my-weather description: 获取指定城市的实时天气。当用户询问某地今天天气、温度、是否适合出行时使用 version: 1.0.0 command: python3 scripts/weather.py parameters: city: type: string description: 城市名例如 北京 unit: type: string description: 温度单位celsius 或 fahrenheit required: false --- # my-weather 获取天气并输出简洁结果。调用时请确保给出明确城市名。输出格式 城市当前温度天气状况建议。这里有几个字段值得展开说。description是给模型看的务必写清楚“什么时候用”我的写法是“当用户询问……时使用”这样模型最容易匹配。command是真正执行的命令注意路径是相对 SKILL.md 所在目录的。parameters告诉模型该传什么参数required: false表示可选参数。这些定义越明确模型调用越准确。6.3 调试技巧四步定位法写完技能不要直接上生产先调试。我调试新技能固定看四个位置模型选没选对技能、参数传得对不对、脚本执行有没有报错、输出格式是否符合预期。启动命令加--debug日志里会打出模型每一步的工具调用记录。有一次我写的技能描述里把“天气”写成了“气候”结果模型死活不触发因为用户说“今天冷不冷”的时候它匹配到的是“气候”而不是“天气”。把描述改回日常用词之后立刻就好了。这让我意识到给 AI 写描述别用书面语用你平时说话的方式写模型反而更容易命中。7. 最后分享几个自己的体会折腾 OpenClaw 这一年多我最大的感受是装技能之前先想清楚你要解决什么流程问题而不是看到新技能就装。技能多不代表强每个技能在启动时都会被模型看到描述太长、数量太多反而会让模型选择困难。我目前常驻的技能也就六七个剩下的需要时再装。权限配置上我坚持最小化原则宁可在 ask 里多点几次确认也不要图省事全部 allow。API Key 永远走环境变量这个底线不能破。最后分享一个小技巧每次装完新技能直接问 AI 一句“你现在有哪些新能力”它会根据加载到的技能说明复述一遍。这比翻日志直观多了一旦它漏掉了某个技能你立刻就知道这个技能没被正确加载省去大量排查时间。