OpenClaw 系列写到第四篇技能系统是我一直想动笔的主题。前面聊完基础部署、通道接入和模型配置OpenClaw 已经能跑起来能接入飞书、Teams能跟人正常聊天了。但不少朋友在这个阶段会陷入同一种困惑OpenClaw 好像什么都会一点又好像什么都没真正交给我——让它干活它总是绕回到对话里跟我确认来确认去离自动完成任务差着一大截。这个差距基本都落在同一个点上技能系统。这篇我会把技能系统从原理到实现完整过一遍包括一次最小技能是怎么写出来、如何注册和自检的技能如何被会话机制驱动以及为什么你会看到agent failed before reply: session file locked (timeout 60000ms)这类报错。最后会结合 Microsoft Teams、飞书和 Obsidian 的实际接入场景把渠道输出时容易踩的坑一并处理掉。适合已经装好 OpenClaw、正在琢磨接下来让它干什么的读者。1. 为什么技能系统是 OpenClaw 从能聊天到能干活的分水岭先给一个我自己的定义技能系统是 OpenClaw 给智能体挂载的可插拔能力包。它不是简单地把某个函数注册给模型而是由清单注册信息、实现代码或脚本和上下文触发规则、参数声明、依赖说明组成的一个完整单元。这个单元一旦注册成功OpenClaw 的 agent 就能在合适的时机调用它完成一次具体的任务然后带着结果回到对话里。1.1 技能不是 Function Calling 的别名很多人第一次听到技能系统第一反应是这不就是 Function Calling 换个名字吗我在刚开始接触时也这么想过实际用下来发现两者完全是两个层面的东西。Function Calling 是模型在一次对话里临时决定要调用某个工具的机制重心在调用这一瞬间技能系统则是一套可维护、可装卸、可复用的人员架构。你可以在技能里写清楚什么时候该触发需要哪些参数没有参数时用什么默认值依赖哪些外部文件这些都独立于模型本身。模型只是技能的调度者之一而不是技能的编写者。拿我自己的经历举例。早期部署 OpenClaw 时我试过在每个 prompt 里堆指令让智能体记住 Obsidian 的路径、记住飞书怎么回复、记住本地数据库的查询方式。结果是维护成本直线上升——改一处逻辑所有相关配置都得跟着动而且不同渠道之间还会互相污染上下文。后来我把这些逻辑全部收拢成技能每个技能只负责一件事编译一次就能在多个渠道复用改动时只需要动对应技能目录里的文件。从那以后我才觉得 OpenClaw 真正稳了。1.2 三个真实场景看懂技能系统的价值场景一定时归档。每天早上让 OpenClaw 把 Obsidian 里没有被归档的日记按周合并生成一份周报并输出到指定目录。场景二数据查询。飞书群里有人发了查一下项目进度agent 自动去本地数据库执行查询返回结构化表格而不是把 SQL 结果原样扔出来。场景三跨渠道推送。在 Microsoft Teams 的某个频道里周期性拉取外部任务列表的更新把变更内容推给指定群组。这三类任务如果你不使用技能系统要么靠手工输入一串复杂提示词然后一次次重复要么把业务逻辑全部写死在主程序里——想换一个数据源、换一种输出格式就得重新部署整个服务。技能系统把任务定义触发条件执行逻辑拆开了任何一环都能独立改动而且每加一个新技能不需要修改 OpenClaw 主程序只要在配置里多挂一个目录。1.3 技能系统在 OpenClaw 里的两个支柱声明式路由和会话驱动技能系统真正跑起来依赖两个底层机制。第一个是声明式路由。技能的注册信息里会声明它支持哪些触发方式可以是关键词触发、正则匹配也可以是模型根据意图自动选择。OpenClaw 在收到消息后先做路由解析再决定调用哪个技能。这个设计的好处是技能之间互不感知对方的存在你新增技能时不需要在旧技能里做任何适配。第二个是会话驱动。OpenClaw 每个会话对应一份 session 文件里面保存了上下文的积累。技能执行过程中产生的中间状态、向用户输出、抛出的异常全部会被记录到当前会话里。这就是为什么群里聊同一个话题时智能体能记得前几轮的内容。但会话文件也带来一个隐患——如果两个请求同时对同一个 session 文件做读写就可能触发锁冲突也就是网上很多人搜过的那条session file locked报错。后面我会专门讲排查方法这里先记住一个原则技能执行要尽量设计成短平快不要长时间持有会话。2. 开发环境准备从 Windows 到 Ubuntu 再到云服务器把底座铺平说完了技能系统的设计逻辑先把运行环境准备好。OpenClaw 本身跨平台支持社区里 Windows、Linux、云服务器的安装教程都不少这里我只挑容易出问题的地方讲。2.1 三种部署场景的安装要点Windows 场景。很多朋友用的是 windowshub 这类辅助工具一键安装体验上类似应用商店。安装后建议重点检查两件事一是 OpenClaw 的可执行文件目录有没有加入 PATH否则后面加载技能时会找不到命令二是注意权限问题尽量不要把 OpenClaw 装在系统盘的高权限保护目录下否则技能脚本写文件时容易被拦。Ubuntu / Linux 场景。网上 openclaw ubuntu 安装教程和 openclaw 安装教程 linux 的内容大同小异核心三步下载二进制、初始化配置目录、启动服务。我个人的建议是用 systemd 把 OpenClaw 托管起来这样不会因为 SSH 断开导致 agent 退出。很多人忽略的是 systemd 服务里的WorkingDirectory要指向 OpenClaw 的配置目录否则技能脚本里的相对路径会集体失效。云服务器场景以阿里云免费试用为例。如果用的是阿里云服务器免费试用实例一般 2 核 2G 就能跑基础技能但建议给系统加一个小 swap 分区。原因很简单技能加载时如果涉及模型调用和脚本编译内存瞬时占用会出现一个峰值没有 swap 的话 OOM 直接把进程杀掉日志里还看不出任何异常。2.2 把千问配置成 OpenClaw 的模型后端技能系统本身不提供智能决策能力它依赖一个模型后端来理解用户意图、决定是否触发技能。我在免费试用服务器上最常配的是千问因为它提供 OpenAI 兼容接口配置起来非常直接。在 OpenClaw 的主配置里模型相关的部分大致长这样model: provider: qwen model_name: qwen-plus base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key_env: QWEN_API_KEY注意几个细节base_url用的是 DashScope 的 OpenAI 兼容终点字段名和 OpenAI 保持一致OpenClaw 内部不需要做额外适配。api_key_env意思是密钥从环境变量读取而不是直接写在配置文件里。这样做的好处是技能代码、配置文件可以放进版本管理不用担心密钥泄出去。如果内存紧张可以把model_name换成一个更小的模型版本技能触发场景对推理能力要求不高够用就行。2.3 选对 channel同一个 OpenClaw 怎么决定把回复送到哪OpenClaw 里的 channel 是消息通道的概念常见的 channel 有飞书、Teams、Obsidian、终端等。你完全可以同时启用多个 channel同一个技能在不同渠道里被触发后回复会回到各自发消息的那个渠道。channel 的路由配置大致如下channels: feishu: enabled: true webhook: your-feishu-webhook app_id: cli_xxx teams: enabled: true bot_id: your-teams-bot-id bot_password_env: TEAMS_BOT_PASSWORD obsidian: enabled: true vault_path: /home/user/notes很多新手在这里会踩一个坑多个 channel 同时开启后agent 在 A 渠道聊到一半的消息可能会被 B 渠道的问题打断上下文互相串。如果你的 use case 是每个渠道独立工作建议先只开终端 channel 调试把所有技能都调通后再逐步打开其他 channel。否则排查问题的时候你很难分清是技能的问题还是 channel 路由规则的问题。我在后面的实战里会再提到 channel 选择这件事尤其是agent 怎么选择 channel这个问题在社区讨论里特别高频。先建立一个认知OpenClaw 的 agent 默认遵循路由表而不是自己随便挑一个 channel 回复。想让它在飞书群里只回复飞书、在 Teams 里只回复 Teams本质是把每个 channel 的上下文隔离开。3. 技能运行的内部机制一条消息从进来到技能执行前发生了什么写第一个技能之前得先把机制讲清楚。很多人的技能写得没问题但死活触发不了就是对中间链路不够了解。3.1 技能触发的完整流程一次完整的技能调用通常经过这么几个阶段用户在某个 channel 发出一条消息。channel 接入层把消息标准化转成内部事件。会话管理模块查找到当前 session加载上下文文件。意图解析模块根据当前模型判断用户想做什么。技能清单匹配如果命中了某条触发规则就进入技能执行。技能运行结束后把结果以文本或结构化数据的形式返回。channel 输出层将结果格式化后发回原渠道。这个过程里最容易出问题的是第 4 步和第 5 步之间的衔接。模型可能理解了意图但技能清单里没有合适的技能也可能技能清单匹配了但模型的 prompt 上下文里没有足够的触发信息导致 agent 选择直接对话而不是调用技能。我的调试经验是在技能清单里把description写得尽量有画面感。不要写归档日记而要写当用户要求整理日记、生成周报、汇总每日记录时调用此技能归档指定目录下的 md 文件。因为模型是根据 description 来做匹配的你描述得越具体匹配准确率越高。3.2 深入理解 session 文件锁和 60000ms 超时网上有个高频搜索词agent failed before reply: session file locked (timeout 60000ms)。第一次看到这行报错的人都会慌因为它看起来像是 agent 崩了。实际上它说的是当前会话的文件锁无法在 60 秒内获取。在 OpenClaw 里每个 session 对应一个文件文件的读写需要一个锁机制来避免并发冲突。如果你同一个 agent 同时收到多个 channel 的消息或者一个技能执行得太慢还没结束另一个请求又来了后一个请求就可能等待锁释放。等待时间超过 60000ms就抛出这条错误。引发这个问题的常见原因有三个同一份会话文件被多个进程同时打开。最常见的是你手动启动了第二个 OpenClaw 实例却没有关闭旧的。某个技能脚本卡死导致会话上下文一直处于执行中状态锁迟迟不释放。会话目录里有残留的.lock文件进程异常退出后没有清理掉。排查路径我放在后面第 6 节详细介绍这里先给一个应急方案确认没有重复进程后去会话目录把.lock后缀的文件备份后删除再重启 OpenClaw 进程一般能恢复正常。但要记住这不是根治办法根治要靠技能尽量无状态化、执行超时可控。3.3 agent 怎么选择 channel路由规则和典型误区openclaw agent 怎么选择 channel这个热搜词背后其实藏着两种需求一是问配置层面怎么决定消息走哪个渠道二是问运行时 agent 为什么有时不按预期选择渠道。运行时选择的逻辑很简单agent 只有在收到该 channel 的消息或事件时才会把该 channel 视为可回复的候选。它不会自己去别的 channel 找活干更不会主动跨渠道回复。如果你的 agent 突然在 A 渠道回复了 B 渠道的问题那多半不是 agent 自己做主而是两个渠道的配置里关联到了同一个 session上下文被共享了。所以想让 agent 选对 channel核心工作是做好 session 隔离。你可以按 channel 维度分配不同的 session 前缀比如飞书的消息都进session_feishu_*Teams 的消息都进session_teams_*。这样即使两个渠道同时来消息互不排队也不会出现锁等待。4. 从零写一个能用的技能以 Obsidian 笔记整理为例理论讲完直接上手。我选一个非常典型且容易验证的场景让 OpenClaw 把 Obsidian 里的日记按周归档成周报。这个技能麻雀虽小但覆盖了清单、触发规则、参数声明、Python 实现和注册自检的完整链路。4.1 技能目录结构和清单文件在 OpenClaw 的技能目录下每个技能是一个独立文件夹。以obsidian-archiver为例skills/ obsidian-archiver/ skill.json run.py requirements.txtskill.json是技能的身份证我写下这样一个最小版本{ name: obsidian-archiver, description: 用户要求整理日记、生成周报、汇总每日记录时将指定目录下的日记文件按周归档, version: 0.1.0, agent: { triggers: [归档, 整理日记, 周报], auto_trigger: true }, parameters: [ { name: vault_path, type: string, description: Obsidian 仓库根目录, required: false } ] }几个字段我觉得值得多解释一句triggers是关键词触发列表命中任意一个就会优先让技能处理。但注意触发关键词不等于技能就一定会被调用最终决定权还在模型解析那一步。auto_trigger设为 true 时agent 会自行判断是否调用技能不一定要用户说出明确关键词。parameters用于声明技能需要的外部参数模型在调用技能前会尝试从对话上下文里提取这些值。提取不到时技能内部要处理参数缺失的默认值。4.2 核心逻辑实现run.py是技能的执行入口。我习惯让它从标准输入接收一个 JSON 参数对象处理完把结果以 JSON 字符串输出到标准输出。OpenClaw 会捕获这个输出并作为技能的执行结果返回给会话。#!/usr/bin/env python3 import json import re import datetime from pathlib import Path from collections import defaultdict def run(config): vault Path(config.get(vault_path, ~/notes)).expanduser() diary_dir vault / Diary weekly_dir vault / Weekly weekly_dir.mkdir(exist_okTrue) files list(diary_dir.glob(*.md)) if not files: return json.dumps({ok: True, archived: 0, message: no diary files}) groups defaultdict(list) for f in files: m re.match(r(\d{4}-\d{2}-\d{2}), f.stem) if m: date datetime.date.fromisoformat(m.group(1)) iso date.isocalendar() key f{iso[0]}-W{iso[1]:02d} groups[key].append(f) for week, items in groups.items(): dest weekly_dir / f{week}.md lines [f# Week {week}\n] for item in sorted(items, keylambda x: x.name): content item.read_text(encodingutf-8) lines.append(f## {item.stem}\n\n{content}) dest.write_text(\n.join(lines), encodingutf-8) return json.dumps({ok: True, archived: len(files), weeks: len(groups)}) if __name__ __main__: payload json.loads(input()) print(run(payload))这个实现非常简单但已经具备了一个技能该有的健壮性传参缺失时有默认值目录不存在时会自动创建没有日记文件时会明确给出提示而不是报错退出。脚本短小的原因是它把大量逻辑交给模型去理解触发条件脚本本身只做稳定的文件操作。4.3 注册与自检技能放进目录后OpenClaw 通常会在启动时自动扫描目录并加载。如果你正在运行 OpenClaw需要重启一次进程或者触发技能热加载命令。重启之后先用终端 channel 做自检。终端输入帮我整理一下日记正常情况下 agent 应该命中技能执行完成后返回类似这样的结果{ok: true, archived: 15, weeks: 2}如果返回的不是 JSON 而是一段对话文本说明技能没被真正调用agent 只是在纯聊天。这时优先检查skill.json的description是否清晰其次看run.py的入口逻辑是否符合 OpenClaw 约定。千万不要去怪模型笨绝大多数情况是技能注册信息写得不够准确。4.4 新手最容易犯的四个错误路径权限不对。技能脚本的目标目录如果是系统目录OpenClaw 运行时没有写权限脚本会静默失败。建议技能的操作路径统一指向配置目录或用户目录下。依赖环境不一致。requirements.txt里写了第三方库但没有在 OpenClaw 所在环境里安装。技能加载时可以 import 失败log 里不一定有显眼报错。触发词和业务强绑定。如果你把触发词写得过于口语化换个说法它就认不出来了。触发词只做初筛真正的匹配还是要靠 description。技能没有独立目录。把多个技能的代码堆在一个目录下会导致 OpenClaw 的清单解析混乱技能时好时坏。一个目录只放一个技能目录名就是技能名。5. 渠道接入实战Teams、飞书和输出截断问题技能写好了接下来最重要的是把它接到真实工作流里。我选两个最常见的渠道展开讲Microsoft Teams 和飞书。5.1 从零接入 Microsoft Teams机器人注册与路由校验OpenClaw 接入 Microsoft Teams本质上是在 Teams 里创建一个机器人应用再把机器人的身份凭据交给 OpenClaw 去连接。步骤大致是先在 Azure 门户或 Teams 开发者平台注册一个机器人拿到 Bot ID 和 Bot Password然后在 Teams 应用管理里给机器人添加适当的权限范围最后把凭据填进 OpenClaw 配置中像我在 2.3 节里给出的那段channels.teams配置。这里最容易翻车的点有两个密码不是拿来就能用。Teams 的 Bot Password 经常带有特殊字符直接写进 YAML 容易被转义解析错误。我建议一律通过环境变量注入配置里只写变量名。消息回复方向搞反。在 Teams 里机器人收到的消息和它发出的消息是两个概念。技能执行完后OpenClaw 会以机器人的身份向同一频道回复。如果你的技能修改了文档、生成了文件尽量把摘要发到频道就行没必要把整个文件都推上去。Teams 对单条消息大小有限制。如果一个技能返回 8000 字的报告Teams 会自动截断用户看到一半内容没了还以为技能出 bug 了。这不是技能的问题是输出层的限制。后面 5.2 节会讲通用解法。5.2 飞书输出被截断为什么总在技能场景里发生openclaw在飞书输出容易被截断这个热搜词我太有共鸣了。我之前跑一个数据统计技能一次返回 8000 字结果飞书群里的消息只显示前两千字后半部分直接消失。飞书截断的根因在于消息卡片/文本长度有限制当技能返回的内容超过上限时飞书要么截断显示要么直接报错拒收。以前纯聊天场景很少遇到因为聊天回复普遍在几百字以内但技能系统一旦跑起来你会经常遇到动辄几千字的输出。解决思路有三个我按推荐程度排个序技能端做摘要。返回给渠道的内容只保留结论、关键数字和建议完整数据写入附件或本地文件。这是最健康的做法对用户也友好。输出分段。在技能内部把超长内容拆成多段每段单独通过渠道接口发送。这个方案不用改模型适合快速解决燃眉之急但发送多段消息体验略碎。启用长文本模式。部分渠道有专门的长文本发送接口可以把完整内容作为附件发送。Obsidian 和飞书都支持类似能力但需要你在 channel 配置里显式开启。我个人建议第一个方案为主第二个方案保底。永远不要指望一个渠道能承载无限长的输出技能设计本身就应该遵循返回摘要、存储细节的原则。5.3 让一套技能服务多个渠道的实践如果你的 OpenClaw 同时接入了 Teams、飞书、Obsidian同样的技能可以共享但要注意输出格式的适配。我的做法是在每个技能里接收一个channel参数根据渠道名称选择输出格式。比如同一个查询技能在飞书群里输出 Markdown 表格在 Teams 里输出 Adaptive Card 的 JSON 结构在 Obsidian 里则直接追加到笔记文件底部。这样一套逻辑复用输出层单独适配比每个渠道各写一套技能要轻松得多。这也是我强力推荐声明式路由的原因——技能本身只关心执行不需要理会消息从哪来、要到哪去。6. 线上部署后的调试与排错从 60000ms 超时到日常运维技能上线之后真正的考验才开始。这一节把最常遇到的线上问题按症状-根因-处理的方式梳理一遍。6.1 “session file locked” 的完整排查链路先还原一个典型场景。某天早上飞书群里有人 agent 让它跑一下日报统计OpenClaw 半天没反应日志里出现agent failed before reply: session file locked (timeout 60000ms)我的完整排查步骤是这样先确认进程数。执行ps -ef | grep openclaw查看是否有多个实例在跑。如果之前用nohup启动过后来又用 systemd 启动了一遍就会有双进程同时监听同一份配置。双进程必然抢会话文件锁这种是最好排查的。杀掉旧实例保留 systemd 托管的那个。查看会话目录里的锁文件。OpenClaw 会话目录一般在配置目录下的 sessions 里。用ls -la找.lock后缀的文件。正常运行时这些锁文件应该会随会话结束自动释放如果发现有残留且时间戳停在很久以前说明之前某个进程是被强杀的锁没来得及清理。检查技能日志。如果锁文件没有残留、进程也只有一份那问题大概率出在技能执行时间过长。日志里如果能看到技能业务逻辑开始打印却没有结束标记就说明技能脚本卡住了。我之前遇到过一次是技能里做了网络请求第三方接口迟迟不响应导致整个会话文件一直被锁住。修复并验证。删除残留锁文件先备份重启 OpenClaw然后用终端 channel 向同一个 agent 连发两条消息确认不会再次报错。如果复现就进入了代码层修复环节。重点说一下预防方案。技能设计上要把 IO 操作全部加上超时控制。Python 里用requests时设置timeout文件读写时控制并发。技能本身是无状态的任何一次调用都不应该阻塞整个会话。6.2 技能卡死的高发原因归类根据我观察到的经验线上技能卡死的主要原因有以下几类外部服务无响应。技能里调用了一个 API上游服务 hang 住技能一直等。处理方式是为所有外部请求统一加timeout并设置重试上限。死循环未加退出条件。技能处理一批文件时如果代码里有个while循环条件永远为真就会一直跑。建议在技能脚本里加最大执行次数或最大处理文件数。模型解析步骤和技能执行步骤相互等待。个别情况下 agent 先请求模型判断意图技能执行结束后又把结果送回模型做二次总结模型响应慢整体执行时间拉长流量高峰期就容易触发 60s 锁等待。6.3 OpenClaw 和 WorkBuddy 的选型经验很多人在搜索openclaw和workbuddy哪个好说明大家在做智能体框架选型。我个人的看法是这两个工具定位并不完全一样。OpenClaw 的优势在于灵活性技能目录是独立模块你可以随时写脚本、挂服务、改触发规则甚至把一套技能迁移到另一台服务器上复用。适合喜欢自己掌控逻辑、需要频繁自定义能力的人。WorkBuddy 更偏向开箱即用配置更简单但个性化能力相对受限。如果你的核心诉求只是聊天和几个预设功能WorkBuddy 上手更快如果你要长期维护一套业务技能比如 Obsidian 归档、数据库查询、跨渠道推送OpenClaw 的技能系统会给你更大的操作空间。我的建议是不要被框架名带着跑先想清楚你要做多少个技能、哪些渠道、哪些逻辑需要和你现有系统打通再做选择。框架只是载体技能才是资产。6.4 日常运维的两个习惯日志分类输出。OpenClaw 自身的日志和技能日志分开维护。技能脚本里可以用独立的日志文件记录每次调用的参数、执行时长和输出摘要。出现问题的时候先看技能日志能过滤掉大量信息。定期备份配置目录。技能是资产配置是基建。把整个配置目录纳入版本管理技能改动前先提交一个 base。线上改技能时就算改坏了也能快速回滚不需要从零排查。7. 让技能系统真正运行的四个习惯最后的篇幅没有新知识分享几个我在实际部署中固化下来的习惯也算是一个阶段性的总结。第一个习惯一个技能只做一件事。技能最忌讳变成大杂烩。一个技能里面又归档笔记又查询数据库又发送消息看起来高效实际上是把自己活活困死。任何一处改动都可能影响其他环节调试成本会指数级上升。第二个习惯所有可配置项都暴露成参数。我在 4.1 节里给vault_path提供了默认值其实这就是一个最小化的参数化设计。不要把路径、密钥、目标频道直接硬编码在技能里让它们作为参数从配置里读取这样同一个技能才能在不同环境间迁移复用。第三个习惯输出结构化数据。技能返回给 agent 的结果尽量使用 JSON 等机器可读格式让 agent 能根据结果决定下一轮动作。纯文本输出虽然人看着舒服但对模型后续处理不友好。比如归档技能返回{archived: 15, weeks: 2}agent 就能直接告诉用户已归档 15 篇生成 2 份周报而不是把整个文件内容念一遍。第四个习惯每个技能都写下可用的触发示例。我会在技能的description末尾附上一两个典型句式比如触发示例整理一下本周日记。这不仅能提高触发准确率也是在帮未来的自己回忆这个技能当初是为什么写的。一次技能系统的开发周期通常不需要太长但把它做得好用、可维护、不轻易卡死靠的是上面这些细碎的设定。我的建议是不要追求一开始就写一个复杂的超级技能先有一个能跑通的最小闭环让 OpenClaw 真正完成一次自动干活然后再在这个基础上迭代。技能系统的价值不是单次执行得多么惊艳而是当你积累了几十个技能之后OpenClaw 会变成一个真正懂你的工作伙伴——你只需要告诉它你想做什么剩下的事情交给技能去完成。