OpenClaw 用久了你会遇到一个分水岭一开始盯着别人的技能包装网盘技能、知识库插件、自动化脚本装一个跑通一个新鲜劲确实足。但玩到后面就会发现这套 Agent 真正值钱的地方不在开箱即用的那几个成品技能而在你能不能给它搭一套贴合自己数据、自己工作流、自己模型策略的专属技能生态。这篇文章我打算跳过基础安装直接聊进阶玩法技能内部的运作逻辑、从零写一个能用的技能、授权和调试的完整排查链路、不同算力模式下技能的差异以及怎么把这套生态搬到 Windows、安卓和本地模型上去。我默认你已经装好了 OpenClaw并且至少跑通过一两个社区技能。如果你还在环境配置阶段可以先补基础文档再回来读这篇体验会顺畅很多。1. 先搞清楚OpenClaw 的技能为什么值得专门做一套生态1.1 技能不是花架子是给 Agent 装上的手眼很多人刚接触 OpenClaw 时会有一个误解觉得技能和提示词差不多无非是给模型加点背景知识。实际完全两回事。提示词是在教模型怎么回答技能是在告诉模型你可以调用什么工具以及这个工具怎么用。模型本身的能力再强也拿不到实时股价、写不了本地文件、没法替你刷新网盘里的授权 token。它真正擅长的只有一件事根据上下文做决策。至于决策之后怎么落地就是技能的工作。拿人类团队做类比模型是那个带判断力的管理者技能是执行层的员工。管理者负责决定现在该查资料还是该发通知员工负责把具体动作做完并返回结果。这个分工逻辑决定了 OpenClaw 的技能必须是一套生态而不是几个孤立脚本。技能之间要共享配置、遵循统一的输入输出规范、能互相调用还需要有一个中心化的注册和发现机制。否则模型就不知道该在什么时候调哪个技能更谈不上组合使用。1.2 别人的技能包很好但要跑顺还得自己做生态社区里的技能资源确实不少。我见到过的就有网络安全方向的技能包、自动化办公的技能集合、各种生活服务类的技能甚至有人把超级技能做成了一整套可组合的模块。直接引入这些包是最快的启动方式但我不建议你长期只靠它们。原因很简单别人的技能是按别人的数据路径、别人的账号体系、别人的模型参数调的。以网盘类技能为例社区版本很可能绑定了某个固定的授权回调地址或者默认输出路径指向作者的测试目录。你可以改但改来改去发现还不如自己花半小时写一个干净的专属版本。专属技能生态这个词我理解不只是技术层面的技能集合而是包括四层东西技能清单明确自己长期要用哪些技能哪些只是临时试一下避免生态臃肿。统一配置API key、token、目录路径、模型偏好全部集中管理不散落在各技能里。基础能力库不同技能里重复用到的工具函数文本解析、JSON 校验、HTTP 请求等抽出来共享。测试与回滚机制每个技能都有独立的本地验证方式改坏了能恢复到上一个可用版本。把这四层理顺之后新增一个技能的成本会低非常多而且不会被单个技能的问题拖垮整个 Agent 的稳定性。2. 拆解一个技能的内部结构声明、执行体与交互契约2.1 技能目录骨架一眼能看懂的布局不同版本的 OpenClaw 对技能目录规范可能略有差异但大体结构是稳定的。以下是我目前的项目里用到的布局可以当作模板参考skills/ my-notes/ manifest.yaml main.py requirements.txt README.md assets/建议每个技能独立占一个目录目录名就是技能名。manifest.yaml 是技能的说明书main.py 是执行体requirements.txt 记录 Python 依赖README.md 给自己留使用笔记assets 目录放技能运行时需要的静态资源。有一点容易忽略尽量别把技能相关文件散落在全局目录里。你可能会图省事把一个技能的核心逻辑写进公共工具文件结果另一个技能升级时不小心改坏了它排查难度会翻倍。独立目录加严格的文件边界是技能生态能长期维护的前提。2.2 声明文件里的关键字段模型靠它做调用决策manifest.yaml 是整个技能最重要也最容易被低估的文件。它不负责干活但它决定了模型能不能在正确的时机、用正确的参数去调用你的技能。以下是我实际使用的字段结构字段作用注意事项name技能唯一标识全局不能冲突建议加命名空间前缀description描述技能能力模型据此判断何时调用写得越具体越好要写清楚边界keywords触发场景的关键词帮模型在模糊指令下联想提升命中率parameters参数定义JSON Schema 格式类型、必填、默认值都要声明returns返回结果的结构说明模型需要据此解析结果并继续推理permissions授权与访问需求涉及外部账号时必须如实声明我最想强调的是 description 字段。模型不会提前读你的实现代码它判断要不要调技能完全靠 description 和当前对话上下文是否匹配。很多技能写出来没有模型调用问题就出在这个字段写得太模糊或者太泛。举个例子如果你的技能是检索本地笔记description 里只写搜索笔记是不够的。更好的写法是搜索本地 Markdown 笔记目录支持按关键词过滤返回文件路径和内容摘要当用户询问历史记录、项目总结、会议纪要等自己写过的东西时使用。要明确功能也要明确边界——如果用户问的是网页上的内容就不该调用这个技能。2.3 执行体的交互结构化输入输出是第一原则技能执行体和 Agent 之间的通信理想状态应该只走结构化数据不要有人类的废话。具体来说我遵循三条原则第一输入统一走 JSON。不管执行体是 Python 脚本、Node.js 脚本还是 Shell 命令都从标准输入读取一段 JSON 作为调用参数技能内部自己解析。第二输出统一走 JSON。执行结果里请只包含结构化字段不要夹杂开始处理处理完成这类日志输出。模型拿到的结果应该干净、可直接读取。第三失败必须返回明确错误码和可读信息。技能失败时不要只丢一个 stack trace 出去Agent 那边会看得一头雾水。错误信息要先做一遍翻译——告诉模型你遇到了什么情况是授权失败、参数不对还是外部服务超时。从实际运维经验来看返回非 JSON 的杂物输出是技能生态里最常见的翻车原因之一。调试技能时看到模型答非所问十有八九是技能执行体 stdout 里混入了多余的打印内容。把执行体当作一个内部 API 服务来对待能规避掉这一整类问题。3. 从零开发一个专属技能以本地笔记检索为例的完整实操3.1 先做需求拆解别急着写代码我建议每一个技能在动手前先花五分钟把需求拆成输入-处理-输出三段。用笔记检索技能做例子输入keyword检索关键词、top_k最多返回条数。处理扫描指定目录下的 Markdown 文件做大小写不敏感的关键词过滤按修改时间排序取前 N 条。输出结构化的文件路径、标题和片段摘要。把这三段写清楚再去写 manifest.yaml 和执行体基本不会跑偏。这个技能是最小可用的版本不涉及复杂的向量化、语义检索但完整覆盖了一个技能从声明到执行的链路。3.2 声明文件实战一个可直接抄的 manifest.yaml 示例以下是我实际在用的声明文件字段和写法都经过了多次调试name: my_notes_search description: - 搜索本地 Markdown 笔记目录按关键词过滤并返回文件路径和内容摘要。 当用户询问自己的笔记、历史记录、项目文档、会议纪要等本地资料时使用。 keywords: - 笔记 - 搜索 - 文档 - 纪要 parameters: type: object properties: keyword: type: string description: 要检索的关键词 top_k: type: integer description: 最多返回多少条结果 default: 5 required: - keyword returns: type: object properties: results: type: array items: type: object properties: path: { type: string, description: 匹配到的文件路径 } title: { type: string, description: 文件名不含扩展名 } snippet: { type: string, description: 匹配到的内容片段约200字 } permissions: filesystem: read: true paths: - ${OPENCLAW_NOTES_DIR}这里有一个细节值得展开。permissions 里的路径我写的是${OPENCLAW_NOTES_DIR}而不是一个写死的绝对路径。这样每个设备都能通过环境变量指定自己的笔记目录技能代码不用改一行。跨设备同步技能时这个设计能帮你省掉大量精力。3.3 执行体实现保持最小但完整的骨架技能执行体我用 Python 实现没有引入任何重量级依赖核心逻辑用一个文件就够。参考实现如下#!/usr/bin/env python3 import json import os import sys from pathlib import Path def load_notes_dir(): raw os.getenv(OPENCLAW_NOTES_DIR, ~/notes) path Path(raw).expanduser() if not path.exists(): raise RuntimeError(f笔记目录不存在: {path}) return path def search_notes(base_dir, keyword, top_k): hits [] for file_path in base_dir.rglob(*.md): try: text file_path.read_text(encodingutf-8, errorsignore) except OSError: continue if keyword.lower() not in text.lower(): continue mtime file_path.stat().st_mtime hits.append({ path: str(file_path), title: file_path.stem, snippet: text[:200].replace(\n, ), mtime: mtime, }) hits.sort(keylambda x: x[mtime], reverseTrue) return {results: hits[:top_k]} if __name__ __main__: try: payload json.load(sys.stdin) keyword payload.get(keyword, ) top_k int(payload.get(top_k, 5)) result search_notes(load_notes_dir(), keyword, top_k) print(json.dumps(result, ensure_asciiFalse)) except Exception as exc: print(json.dumps({error: str(exc)}, ensure_asciiFalse)) sys.exit(1)一个很容易踩的坑是编码。笔记里大概率有中文Python 在 Windows 命令行下默认输出编码可能是 GBK直接打印中文 JSON 可能报UnicodeEncodeError。我在代码里统一用json.dumps(..., ensure_asciiFalse)并且建议运行环境的PYTHONIOENCODINGutf-8。另外错误处理和正常返回一样输出 JSON 并带非零退出码这是为了让 Agent 侧能通过退出码快速判断技能执行状态。3.4 本地验证不经过 Agent 直接喂参数写完执行体第一件事不是丢给 Agent 试而是自己在命令行模拟调用echo {keyword:项目总结, top_k:3} | python main.py这条命令会直接从标准输入读参数、让技能执行、再输出 JSON 结果。如果返回结果符合预期再接 Agent。这一步能把技能本身的问题和模型调度的问题彻底隔开排查效率会高很多。我强烈建议把这个验证命令写进技能的 README 里。每次改完代码先跑一遍确认没引入新的问题再让 Agent 使用。这相当于给技能加了一个最小的回归测试。3.5 授权绑定向外调用账号类技能的正确姿势笔记检索这类文件系统技能一般不需要登录。但社区里大量技能是需要授权的——我接触过的网盘类技能就是典型。以某个网盘存储技能举例安装完成后通常会有一步提示要求你安装对应网盘客户端并授权账号技能才能替你去操作文件。授权背后其实是一套 OAuth 流程技能发起授权、你在浏览器里登录、平台回调一个 token、技能把这枚 token 保存下来用于后续请求。这一步常见的坑有三个token 存的位置不对换个终端就丢了。尽量把 token 存放在角色的配置目录下而不是技能源码目录里。授权回调地址和技能配置里声明的地址不一致导致授权落地失败。token 有效期过了没有刷新机制。长时间挂着的 Agent 会在某次调用时突然返回授权已失效但 Agent 不会自动处理只会把原始报错抛给模型。对于第一类技能我的实践是让技能从统一的环境变量里读取 token 或账号配置而不允许技能绕过配置中心直接发请求。这样以后更换账号、迁移设备都只动配置不碰代码。4. 技能运行时的大脑选型算力与模型对技能成败的影响4.1 别忽视模型能力技能成功率的一半在模型手里很多人调技能出现问题就盯着技能代码反复改。但实际经验告诉我技能失败有一半概率出在模型侧尤其是模型不理解技能描述、传错参数、甚至干脆无视技能直接回答。这个问题的根源在于模型是在用自然语言理解你的技能声明而不是执行机器指令。声明文件里的 JSON Schema、description、keywords 都要被模型阅读理解后转化为一次调用动作。模型能力越强理解越准能力弱的小模型很可能把参数类型搞混或者忽略必填字段直接空着。就有同学在项目里把 qwen2.5 系列的小参数模型关联到 OpenClaw 用。实测下来这类模型做单技能、明确指令的调用问题不大但一旦场景复杂、技能多、需要模型自主编排流程小模型的成功率会明显下降。这不是 OpenClaw 的问题是模型推理能力的客观限制。4.2 三种算力模式怎么选OpenClaw 并不是只能用 API 调用外部模型。本地部署、API 接入、混合模式都是可行的只是各有取舍。我在几台设备上都跑过把判断依据整理成一个对照表模式优势劣势合适场景纯 API云端模型推理能力强、技能调用准确、无需本地算力有延迟和用量成本、数据需出本地正式办公、复杂技能编排本地模型Ollama 等隐私好、离线可用、零推理费用模型能力受限、复杂调度不行个人笔记、内网环境、敏感数据混合模式灵活简单任务走本地、复杂任务走 API配置复杂需要在技能层做路由一台设备跑多种场景有朋友会问OpenClaw 是不是只能通过 API 的方式使用算力答案是否定的。用 Ollama 部署一个本地模型再关联到 OpenClaw 是完全可以的。还有一个常见搭配是把大模型留在 API但外部服务调用比如网盘、知识库的 API走安全通道这样对外部服务访问可控、日志可审计。4.3 遇到弱模型时给技能加提示如果你的设备确实只能跑小参数本地模型也有办法提升技能调用成功率。我的经验是三个调整第一把参数的枚举值、格式示例直接写进 parameters 的 description 里。模型看到keyword: {type: string, description: 例如项目总结、张伟的周报}时会更容易给出正确格式。第二给必填参数都设置合理的默认值。即使模型漏传了技能侧也能兜底执行至少不会直接失败。第三在不同模型之间同一技能的表现可能差异很大。做模型切换后建议用同一组测试提问重新过一遍技能确认调用时机和参数没走样。5. 技能挂了按这条链路排查比瞎改快十倍5.1 第一层先看 Agent 到底有没有调用技能技能表现异常时先别急着改代码。第一件事是翻调用日志确认 Agent 是不是真的尝试调用过这个技能。OpenClaw 的日志里会清晰记录模型选用了哪个技能、传入了哪些参数。这个信息能直接帮你分清问题出在哪一层如果模型压根没调用那是调度层问题要回去修 description 和 keywords如果模型调用了但参数明显不对那是模型理解问题如果调用和参数都对但返回结果异常那才是技能执行体的问题。后排错顺序能省掉大量无用功。5.2 第二层把技能从 Agent 里摘出来单独跑日志确认 Agent 调用了技能之后回到命令行用固定输入手动跑一遍执行体。这一步的意义是把模型决策和技能执行彻底分离。我在前面提到的那条echo ... | python main.py的命令就是干这个用的。如果手动执行返回正常那么问题大概率出在模型传给技能的那份参数上如果手动执行也报错那技能代码本身存在缺陷。两个方向各有对应的修法后面展开。5.3 常见问题的速查表下面是几类我在实际项目里碰到过、并最终定位出原因的问题直接列成速查表供你参照表现常见根因排查方向Agent 说我不需要技能直接回答description 太泛或触发词太少重写技能描述加入典型用户意图参数传成字符串本该传数字模型对 JSON Schema 理解偏差在描述里加格式化示例必要时给默认值技能返回了一坨非 JSON 杂物执行体里有多余 print 或第三方库日志清理 stdout 输出日志走 stderr技能执行超时外部 API 慢、文件扫描范围太大优化执行体增加超时上限和采样逻辑返回授权失效或无法验证token 过期或环境未初始化检查配置中心和外部账号状态在 Windows 上报环境相关错误WSL 子系统异常或 PATH 问题先用 PowerShell 检查环境状态5.4 一个完整的授权失败排查案例我调试某个网盘类技能时Agent 给我的反馈是无法安全检查你的环境请在 PowerShell 中运行 wsl --status解决报告的问题。这个信息很误导人看起来像是 Windows 环境坏了但实际跟 WSL 关系不大。我当时按顺序做了四步排查第一步绕开 Agent 直接在命令行里手动调用技能。结果显示技能在创建一个临时目录时权限不足和 WSL 状态没关系。第二步检查技能运行形态。因为 Agent 自带的外部命令工具会把子进程丢进 WSL 环境如果这个技能恰好需要在桌面端访问用户目录就会产生权限断层。这才能解释为什么报错信息指向 WSL。第三步查看授权 token 的存储位置。发现 token 存在了技能目录下但 WSL 环境访问该目录的权限受限导致技能请求时读不到完整的授权凭证。第四步把 token 移到授权配置中心并给技能明确指定访问路径。问题彻底消失。这个案例给我的核心教训是Agent 的报错信息常常是二次翻译后的结果底层真实原因会被包装得面目全非。正确做法永远是绕过 Agent、直接调技能本体一层层剥开看。6. 多技能协作与生态治理让技能之间不打架6.1 模型自由调度 vs 复合技能两种编排思路当技能数量超过五个之后你必然要面对一个问题多个技能怎么配合。OpenClaw 默认的思路是模型自由调度——它根据上下文自己决定要不要先查笔记、再生成周报、然后发到网盘。这种模式胜在灵活动手写技能时不用考虑太多依赖关系。但自由调度不稳定。模型每一步的决策都可能因为上下文微调而变化。同一个任务今天它先调 A 再调 B明天可能就变成了先调 B 再调 A。如果你需要的是固定流程我更推荐做复合技能写一个编排技能在它内部按固定顺序依次调用其他技能或服务直接对模型暴露一个高级接口。我的选择依据很简单探索型任务比如帮我看看最近有什么值得读的资料交给自由调度固化的业务流程比如生成日报并归档做成复合技能。前者要挖掘后者要确定性。6.2 依赖治理装一个技能搞坏全局环境是最烦的事技能大多自带依赖。Python 技能要 pip 装包Node 技能要 npm 装包如果不加隔离很可能会出现某个技能升级依赖后把另一个技能的运行环境弄崩的情况。我的做法是给每个技能做独立运行环境哪怕只是每个技能目录下建一个独立的虚拟环境也比全部用全局环境稳得多。OpenClaw 在调用执行体时倾向于直接执行入口脚本环境切换自己来控制。依赖治理的另外两个要点requirements.txt 锁定版本范围别裸装最新版。技能生态还处于快速迭代期依赖库上游更新可能带来破坏性变更。技能之间不要互相 import 对方的私有模块。如果有一段逻辑多个技能都要用就把它抽到基础能力库。这能避免因技能 A 重构导致技能 B 不可用的连锁故障。6.3 引入他人技能的三个安全检查社区技能包的出现让引入变得非常方便但引入前我强烈建议做一道工序。第一看 requirements 依赖。如果一个技能要求装了一堆和它功能无关的包要小心它可能在偷偷做别的事。技能需要最小权限这个安全意识应该刻在流程里。第二看它对模型能力的假设。有些技能 description 写得极有信心实际上依赖很强的模型才能正确传参。如果你的模型较弱这个技能即使装上了也大概率不可用。第三看授权设计的说明。正规技能一定会写清楚需要什么权限、token 存哪、如何撤销。只字不提授权的技能一定要警惕。引入后如有必要我一般会做一次本地化改造把路径改成本机路径、把输出语言改成中文、把输入示例改成自己实际会用的场景。改造完手动验证一遍再考虑接入日常使用。7. 跨设备落地Windows、安卓与本地模型的实战经验7.1 Windows 端WSL 和 companion 是你绕不开的两件事OpenClaw 在 Windows 上跑绕不开 WSL 这个话题。不少新手第一次报错就栽在环境验证上提示让你去 PowerShell 里运行wsl --status。这类问题大多是 WSL 子系统没有正常初始化或者默认发行版没有指定。打开 PowerShell 执行wsl --status、wsl --list --verbose检查一下子系统状态通常能定位到问题。另一个值得单独拿出来说的是 Windows companion。它的思路是把重资源操作留在桌面端移动端或者轻客户端只做会话管理。我这边的配置原则是所有涉及本地大目录扫描、复杂技能编排、外部 API 批量调用的技能都只挂在桌面端移动端只暴露查询类技能。这样能显著降低移动端的负载和电池消耗也能避免多个设备争抢同一批资源时互相干扰。配置 companion 时如果技能出现网络请求超时或者类似问题别直接奔着技能代码去先检查 Windows 防火墙是不是拦截了业务进程的出入流量。这类环境问题在 Agent 的日志里往往会伪装成技能执行失败排查时要多留个心眼。7.2 安卓端Termux 部署的精简策略手机端装 OpenClaw 是可行的社区里也有 Termux 的部署步骤。但我想说手机端的技能生态策略一定和桌面端不同。手机的优势是随时在线、方便接收通知劣势是算力小、资源有限、网络可能不稳定。在 Termux 里跑技能我建议三条原则第一只装轻量技能。检索、待办、快捷查询这类纯文本处理没问题但涉及大批量文件操作、图像处理、复杂授权的技能尽量留在远端桌面实例。第二把重活转发出去。手机上可以保留一个轻会话入口真正需要跑大技能时通过 OpenClaw 的远端连接能力去调用桌面端技能。第三会话持久化要单独处理。手机端 App 进程容易被系统回收技能配置和授权 token 要做好持久化存储不然重开一次会话就要重新授权体验很差。7.3 技能配置跨设备同步git 与 .env 分离多设备落地之后技能配置的同步就成了新的痛点。我的做法是技能目录整体纳入 git 管理版本历史一清二楚改坏了随时回滚。但有一个例外凡是包含 token、密钥的设备私有配置一律不进 git而是放在各设备本地的 .env 文件里。这样你可以在不同设备上保持相同的技能代码但是各用各的配置。比如桌面端笔记目录指向某个路径手机端指向另一个路径由于代码里读的是环境变量技能本身完全不需要改动。同步的另一个经验是设备间技能版本尽量保持一致。不要这台设备跑 v1那台设备跑 v2否则你在桌面端调试好的技能到手机上表现完全不一样会让你怀疑人生。统一走 git 分支或 tag 管理能在多设备之间维持可预期的行为。回到开头那句话OpenClaw 真正吸引人的地方从来不是它预置了多少功能而是你怎么把自己的日常操作沉淀成一套可复用、可迁移的能力集合。我那套笔记检索技能现在在电脑、手机、WSL 环境里都能跑社区里没有任何一个现成技能比它更贴近我自己的文件结构和搜索习惯。如果你也想动手做第一个专属技能就从一个小而实用的场景开始——把某条固定目录下的待办文档读出来按优先级整理成结构化输出。等这个技能被 Agent 稳定调用一周以上你再去扩展更复杂的授权、多技能编排和跨设备方案会发现整个逻辑是相通的。