最近群里聊 OpenClaw 的人越來越多了大家都管它叫“龍蝦”而這套東西最讓人上頭的點(diǎn)就是 Skill 機(jī)制。簡(jiǎn)單說OpenClaw 是一個(gè)偏執(zhí)行側(cè)的智能體框架模型負(fù)責(zé)“想”Skill 負(fù)責(zé)“做”。框架本身會(huì)帶一些默認(rèn)技能可真到自己的業(yè)務(wù)場(chǎng)景里你會(huì)發(fā)現(xiàn)大部分時(shí)候都得自己動(dòng)手寫 Skill。用 Python 給 OpenClaw 寫自定義 Skill是當(dāng)前門檻最低、生態(tài)最順手的一條路——Python 社區(qū)里輪子多你只要把一個(gè)業(yè)務(wù)功能封裝成 Skill 的標(biāo)準(zhǔn)格式Agent 就能在對(duì)話里自動(dòng)調(diào)用它。這篇文章不是給你念官方文檔而是按照我自己從零摸一遍的經(jīng)驗(yàn)走先拆 Skill 的運(yùn)行邏輯再完整寫一個(gè)能落地的系統(tǒng)信息采集技能最后聊注冊(cè)、調(diào)試和踩坑。如果你正準(zhǔn)備給 OpenClaw 加技能或者只是好奇這種“模型 工具插件”的模式怎么玩這篇文章應(yīng)該能幫你少走不少彎路。1. Skill機(jī)制拆解龍蝦的“技能插件”到底是怎么跑的1.1 Skill的本質(zhì)一個(gè)目錄、一份元信息和一段執(zhí)行邏輯很多人第一次看到 OpenClaw 的 Skill 目錄會(huì)懵一個(gè)文件夾里放一個(gè).py文件、一個(gè).yaml文件這算什么“技能”其實(shí)它的設(shè)計(jì)思路跟 IDE 插件、瀏覽器擴(kuò)展很像。每個(gè) Skill 就是一個(gè)自包含的模塊向 Agent 暴露兩樣?xùn)|西元信息告訴 Agent“我會(huì)什么、需要什么參數(shù)”執(zhí)行函數(shù)告訴 Agent“你調(diào)我之后我能具體做什么”。我在實(shí)際使用中習(xí)慣把 Skill 看作“給大模型配的一把專用工具”。模型本身的強(qiáng)項(xiàng)是語義理解和生成弱項(xiàng)是執(zhí)行確定性的計(jì)算、讀本機(jī)狀態(tài)、調(diào)領(lǐng)域接口。Skill 正好補(bǔ)上這塊。比如你問模型“看看這臺(tái)機(jī)器內(nèi)存剩多少”模型如果只靠訓(xùn)練知識(shí)它根本不知道你這個(gè)環(huán)境里真實(shí)的內(nèi)存占用但如果你掛了一個(gè)system_info技能模型就會(huì)決定調(diào)用它把工具返回的真實(shí)數(shù)據(jù)整理成回答。所以理解 Skill 不能只看代碼要把它放進(jìn) Agent 的工作鏈路里看用戶請(qǐng)求進(jìn)來模型判斷需要外部能力通過元信息匹配到合適的 Skill再按參數(shù)約定觸發(fā)執(zhí)行函數(shù)拿到返回值后繼續(xù)組織語言。這里面的核心設(shè)計(jì)點(diǎn)就是元信息能不能讓模型“一眼看懂”。很多新手寫 Skill 只顧著寫實(shí)現(xiàn)結(jié)果模型根本不知道什么時(shí)候該調(diào)問題就出在元信息寫得太抽象。1.2 開發(fā)前的環(huán)境準(zhǔn)備動(dòng)手寫 Skill 之前先把環(huán)境捋清楚。我的建議是不要直接往系統(tǒng) Python 里裝東西而是為 OpenClaw 單獨(dú)準(zhǔn)備一個(gè)虛擬環(huán)境。原因很簡(jiǎn)單OpenClaw 本身依賴不少庫你寫 Skill 時(shí)還會(huì)加一些自己的依賴如果全堆在系統(tǒng)環(huán)境里沒過多久就會(huì)出現(xiàn)“裝了這個(gè)包那個(gè)包被降級(jí)”的連鎖反應(yīng)?；A(chǔ)環(huán)境有這么幾樣Python 3.8 或更高版本。OpenClaw 生態(tài)目前對(duì) 3.10/3.11 的支持最穩(wěn)如果你還沒裝 Python直接裝 3.11 就行。OpenClaw 本體。安裝方式去官方倉庫看就好不同版本的安裝命令會(huì)變我不建議死記硬背命令重點(diǎn)是把它的skills目錄找到。一個(gè)你順手的編輯器。VSCode 或者任意文本編輯器都行Skill 本質(zhì)上就是一個(gè)目錄里的幾個(gè)文件不需要重型 IDE。代碼版本管理工具。哪怕只有你自己開發(fā)也建議建一個(gè) git 倉庫Skill 的迭代速度比你想象中快。裝完以后先別急著寫代碼在命令行里跑一下 OpenClaw 自帶的示例 Skill確認(rèn)“框架主流程”是通的。這一步特別重要因?yàn)樗选翱蚣軉栴}”和“你的代碼問題”隔離開如果示例 Skill 都跑不通那就是環(huán)境問題如果示例能跑通而你的 Skill 不行那問題多半出在自己寫的代碼里。1.3 命名與設(shè)計(jì)原則在我看過的二三十個(gè) Skill 插件里最影響使用體驗(yàn)的不是代碼寫得好不好而是命令命名。OpenClaw 里模型的調(diào)用決策依賴元信息里的name和description如果你的技能叫data_processor描述寫“一個(gè)數(shù)據(jù)處理模塊”模型面對(duì)用戶問題“幫我把這段文字里的電話號(hào)碼都提取出來”很難確定是不是該調(diào)你這個(gè)技能。我自己定了幾條命名規(guī)范供你參考技能名用動(dòng)詞開頭比如fetch_weather、send_email、check_system讓模型一眼看出動(dòng)作。描述里寫清楚“什么場(chǎng)景用、輸入什么、輸出什么”不要寫空話。比如描述寫“當(dāng)用戶想查看本機(jī)CPU/內(nèi)存/磁盤使用情況時(shí)使用此技能獲取系統(tǒng)信息并返回結(jié)構(gòu)化數(shù)據(jù)”模型命中率會(huì)高很多。一個(gè) Skill 只做一件事。有些朋友喜歡寫一個(gè)大而全的 Skill里面有十幾個(gè)函數(shù)看似方便但模型在調(diào)用時(shí)會(huì)很猶豫參數(shù)也容易傳錯(cuò)。寧可多做幾個(gè)小 Skill也別憋一個(gè)大怪物。2. 手把手寫第一個(gè)Python Skill2.1 場(chǎng)景選擇先做一個(gè)系統(tǒng)信息采集技能我在給新手建議時(shí)從來不讓他們上來就寫“調(diào)用外部 API”或者“操作數(shù)據(jù)庫”這種帶網(wǎng)絡(luò)和服務(wù)依賴的技能而推薦先寫一個(gè)能“自我感知”的技能。這里我就用系統(tǒng)信息采集做例子它有幾個(gè)好處只用標(biāo)準(zhǔn)庫就能跑通最小版本方便確認(rèn) Skill 機(jī)制本身沒問題返回結(jié)果是真實(shí)數(shù)據(jù)調(diào)試時(shí)有明確預(yù)期后續(xù)想加 psutil 增強(qiáng)版也順理成章。我們這個(gè)技能要實(shí)現(xiàn)的能力是當(dāng)用戶問“這臺(tái)電腦什么系統(tǒng)”“內(nèi)存夠不夠”“磁盤還剩多少”時(shí)Agent 能調(diào)用一個(gè) Python Skill返回 JSON 格式的系統(tǒng)信息。為了讓過程可感我會(huì)先實(shí)現(xiàn)一個(gè)“標(biāo)準(zhǔn)庫版”再升級(jí)成“psutil 增強(qiáng)版”這樣你能看出來一個(gè)技能是怎么從零到一演進(jìn)的。2.2 目錄與元信息文件怎么寫先看看 Skill 的標(biāo)準(zhǔn)目錄結(jié)構(gòu)。在 OpenClaw 的skills目錄下建一個(gè)文件夾名字就是技能名里面放代碼和元信息skills/ └── system_info/ ├── skill.py └── skill.yamlskill.yaml是模型感知 Skill 的第一入口相當(dāng)于“技能說明書”。我一般會(huì)這樣寫name: system_info version: 1.0.0 description: 獲取本機(jī)操作系統(tǒng)、CPU、內(nèi)存、磁盤等基礎(chǔ)信息。當(dāng)用戶詢問系統(tǒng)版本、內(nèi)存占用、磁盤剩余空間時(shí)使用。 python: 3.8 parameters: - name: detail type: boolean required: false default: false description: 是否輸出詳細(xì)的CPU占用率和內(nèi)存/磁盤使用情況這里有幾個(gè)細(xì)節(jié)容易踩坑。第一個(gè)是description別寫太短寫清楚觸發(fā)條件模型才能正確決策第二個(gè)是parameters里的type一定要和代碼里的邏輯對(duì)應(yīng)否則模型會(huì)傳錯(cuò)類型第三個(gè)是version字段我要求自己每改一次就升一個(gè)小版本這樣出問題時(shí)能排查是不是緩存了舊版本。2.3 Skill代碼標(biāo)準(zhǔn)庫版本與psutil增強(qiáng)版skill.py部分我一般會(huì)定義一個(gè)Skill類然后實(shí)現(xiàn)run方法。OpenClaw 各個(gè)小版本的調(diào)用約定可能略有差異但“定義類、實(shí)現(xiàn)run()”這個(gè)模式在多數(shù) Agent 框架里是通用的你只需要把函數(shù)名對(duì)牢自己用的版本就行。先看最簡(jiǎn)單的版本import platform import json import socket class Skill: name system_info version 1.0.0 description 獲取本機(jī)操作系統(tǒng)、CPU、內(nèi)存、磁盤等基礎(chǔ)信息 def run(self, **kwargs): detail kwargs.get(detail, False) info { os: platform.system(), os_version: platform.version(), machine: platform.machine(), hostname: socket.gethostname(), python_version: platform.python_version(), } if detail: try: import psutil info[cpu_usage_percent] psutil.cpu_percent(interval1) memory psutil.virtual_memory() info[memory] { total_gb: round(memory.total / 1024 ** 3, 2), available_gb: round(memory.available / 1024 ** 3, 2), usage_percent: memory.percent, } disk psutil.disk_usage(/) info[disk] { total_gb: round(disk.total / 1024 ** 3, 2), free_gb: round(disk.free / 1024 ** 3, 2), usage_percent: disk.percent, } except ImportError: info[warning] psutil not installed, only basic information returned return json.dumps(info, ensure_asciiFalse)我解釋幾個(gè)設(shè)計(jì)決策。第一detail參數(shù)默認(rèn)是False但psutil是懶加載的也就是說只有用戶明確要求詳細(xì)信息時(shí)這個(gè)庫才會(huì)被導(dǎo)入。這么做是為了讓基礎(chǔ)調(diào)用不依賴第三方庫降低失敗率。第二返回值我用json.dumps(..., ensure_asciiFalse)確保中文不會(huì)被轉(zhuǎn)成\u開頭的一串轉(zhuǎn)義符否則在 Agent 端看起來非常不直覺。第三interval1是cpu_percent的參數(shù)表示采樣一秒能拿到一個(gè)相對(duì)真實(shí)的瞬時(shí) CPU 使用率而不是 0.0 這種無意義值。2.4 參數(shù)傳遞與返回值約定寫 Skill 的時(shí)候最怕框架約定的輸入輸出接口和你自己寫的函數(shù)對(duì)不上。我強(qiáng)烈的建議是統(tǒng)一用**kwargs接收參數(shù)統(tǒng)一返回 JSON 字符串。拿**kwargs的原因在于 Skill 可能被框架用多種方式調(diào)用有的版本會(huì)傳入模型填好的命名參數(shù)有的會(huì)傳一組字典你用kwargs.get(detail)取值無論哪種都能應(yīng)對(duì)。返回值那里也容易迷糊。有些框架希望run返回字符串因?yàn)樽址梢灾苯尤?Agent 上下文有些框架希望返回 dict框架自己幫你序列化。你沒法保證所有版本一致時(shí)就按項(xiàng)目文檔來。我的默認(rèn)選擇是返回字符串因?yàn)樗募嫒菝孀顝V而且可以在返回前手動(dòng)控制序列化過程。還要注意一個(gè)設(shè)計(jì)細(xì)節(jié)返回內(nèi)容不要讓 Agent“看不懂”。比如返回一個(gè)套娃式的嵌套 JSON模型解析起來費(fèi)勁回答自然容易出錯(cuò)。我習(xí)慣把數(shù)據(jù)打平到兩級(jí)以內(nèi)像上面memory、disk這種對(duì)象里包含基礎(chǔ)字段就是夠用的深度。3. 把Skill裝進(jìn)OpenClaw并完成本地聯(lián)調(diào)3.1 安裝路徑與自動(dòng)發(fā)現(xiàn)寫完了代碼和元信息接下來就是把 Skill 放進(jìn) OpenClaw 能掃到的地方。不同版本的 OpenClaw 對(duì) Skill 目錄的掃描路徑不完全相同但大體邏輯沒變有一個(gè)根目錄叫skills下一級(jí)每個(gè)子目錄代表一個(gè) Skill框架啟動(dòng)時(shí)遍歷這些目錄讀取skill.yaml并把skill.py里的類實(shí)例化注冊(cè)到技能庫里。我用過一個(gè)笨但有效的辦法來確認(rèn)路徑對(duì)不對(duì)先在skills目錄下建一個(gè)空目錄再在里面放一個(gè)只返回ping的最小 Skill啟動(dòng) OpenClaw 看日志里有沒有出現(xiàn)這個(gè)技能名。如果日志里都找不到先查目錄層級(jí)很常見的問題是有人把system_info.py直接扔在skills下面而不是放到skills/system_info/skill.py。另外如果你用了配置文件來管理技能白名單記得在配置里把system_info加進(jìn)啟用列表。這一步在不同框架版本里差異挺大有的默認(rèn)全量加載有的默認(rèn)只加載顯式聲明的技能。看日志最直接加載失敗時(shí)通常會(huì)有 “failed to load skill” 之類的報(bào)錯(cuò)跟著提示改就好。3.2 用Ollama跑本地模型做端到端驗(yàn)證OpenClaw 比較大的亮點(diǎn)之一就是可以接本地模型玩常見方案是 Ollama 部署一個(gè)開源模型比如 qwen 或者 llama 系列然后讓 OpenClaw 通過本地模型做推理。這樣整個(gè)鏈路不依賴外部服務(wù)適合在離線環(huán)境或本地開發(fā)機(jī)里反復(fù)驗(yàn)證 Skill。我的端到端測(cè)試流程是這樣的先確保 Ollama 服務(wù)啟動(dòng)然后在 OpenClaw 的模型配置里把地址指向本地 Ollama重啟框架。接著在對(duì)話里輸入一句自然語言比如“查一下這臺(tái)電腦的磁盤使用情況”。如果配置正常模型會(huì)自己判斷需要調(diào)用system_info技能然后你應(yīng)該能在日志里看到技能命中、參數(shù)填充、執(zhí)行結(jié)果返回這幾個(gè)階段的記錄。這里有個(gè)常見現(xiàn)象本地小模型在參數(shù)填充上不如大模型準(zhǔn)確它可能會(huì)漏掉detail參數(shù)或者把布爾值傳成字符串“True”。所以在設(shè)計(jì) Skill 時(shí)參數(shù)盡量給默認(rèn)值并且代碼里要有容錯(cuò)。比如把kwargs.get(detail, False)改成能兼容字符串真值的寫法可以寫成detail str(kwargs.get(detail, False)).lower() in (true, 1, yes)這樣模型再怎么傳錯(cuò)你的代碼也不會(huì)崩。3.3 調(diào)試三板斧單測(cè)入口、日志隔離、JSON輸出檢查在把 Skill 交給 OpenClaw 之前我建議你把它當(dāng)作普通 Python 模塊先單獨(dú)測(cè)試一遍。我以前直接往 Agent 里調(diào)試一報(bào)錯(cuò)就掙扎半天分不清是我代碼的問題還是框架調(diào)用的問題。后來養(yǎng)成了習(xí)慣每個(gè)skill.py底部都留一個(gè)if __name__ __main__:入口里邊調(diào)用Skill().run()先當(dāng)作腳本跑。調(diào)試時(shí)的三條經(jīng)驗(yàn)單測(cè)入口的模擬要貼近框架傳參。比如框架傳參數(shù)可能是字典你就在入口里構(gòu)造一個(gè)字典傳進(jìn)去不要直接用函數(shù)默認(rèn)參數(shù)測(cè)試。日志要能區(qū)分“技能執(zhí)行日志”和“模型思考日志”。我的做法是在 Skill 代碼里只往 stdout 輸出最終結(jié)果任何中間日志一律寫到文件或 stderr避免污染返回內(nèi)容。JSON 輸出要做一次合法性檢查。寫完json.dumps之后再用json.loads讀回來確認(rèn)沒有因?yàn)樽兞款愋蛦栴}導(dǎo)致序列化失敗。這一步可以作為“金標(biāo)準(zhǔn)”在命令行能正確輸出 JSON再接 OpenClaw 聯(lián)調(diào)。我見過太多人跳過了這個(gè)步驟直接在 Agent 里報(bào)錯(cuò)最后排查一圈發(fā)現(xiàn)就是 Python 序列化時(shí)遇到set對(duì)象這種鍋不該讓 Agent 背。4. 常見問題與排查實(shí)錄4.1 高頻報(bào)錯(cuò)速查表把我在實(shí)際使用中遇到過的、以及在開發(fā)群里看別人踩過的坑整理一下做成一個(gè)速查表可以收藏備用?，F(xiàn)象可能原因處理辦法框架日志里沒有 Skill 加載記錄目錄層級(jí)不對(duì)、技能未啟用、元信息格式錯(cuò)誤檢查skills/技能名/skill.py結(jié)構(gòu)確認(rèn)配置里已啟用Agent 一直不選擇調(diào)用技能元信息描述不具體模型無法判斷觸發(fā)場(chǎng)景重寫description增加觸發(fā)條件和示例場(chǎng)景調(diào)用后返回內(nèi)容為空?qǐng)?zhí)行發(fā)生異常但異常信息被吞掉在run里給執(zhí)行邏輯包try/except打印堆棧到日志ModuleNotFoundErrorSkill 代碼引用了未安裝的依賴在 OpenClaw 的 Python 環(huán)境里安裝依賴或用懶加載邏輯中文輸出亂碼Windows 下控制臺(tái)編碼與 Python 默認(rèn)編碼不一致設(shè)置PYTHONIOENCODINGutf-8返回 JSON 時(shí)指定ensure_asciiFalse技能返回了但 Agent 說沒結(jié)果返回內(nèi)容里混了日志輸出結(jié)構(gòu)不符合模型預(yù)期檢查 stdout 是否只有 JSON格式確保能被json.loads解析這個(gè)表看起來簡(jiǎn)單卻是我屢次“懷璧其罪”的總結(jié)。尤其是第一行新手十有八九會(huì)折在目錄結(jié)構(gòu)上不是你代碼寫錯(cuò)是文件放錯(cuò)位置。4.2 三個(gè)容易被忽略的坑第一個(gè)坑是Skill 執(zhí)行環(huán)境的 Python 和 OpenClaw 的 Python 不是同一個(gè)。如果你用系統(tǒng)自帶的 Python 跑了pip install psutil但 OpenClaw 跑在虛擬環(huán)境里那 Skill 照樣找不到模塊。排查方法是啟動(dòng)前在配置里打印sys.executable確認(rèn)到底走的哪個(gè)解釋器。第二個(gè)坑是緩存。有一些版本會(huì)緩存 Skill 信息你改了skill.py但它加載的還是舊代碼。我改代碼后必做的動(dòng)作是清楚緩存目錄并重啟框架別省錢。第三個(gè)坑是權(quán)限問題。不是所有環(huán)境都允許你讀取完整系統(tǒng)信息尤其在 Linux 容器里磁盤統(tǒng)計(jì)可能只有掛載點(diǎn)的一部分。這種問題在 Python 層沒有解只能在 Skill 輸出里加一個(gè)warning字段保證 Agent 不會(huì)拿到 false 數(shù)據(jù)。4.3 Windows和Linux部署差異開發(fā)環(huán)境如果是 Windows到了 Linux 服務(wù)器上跑有兩點(diǎn)要提前處理。第一是路徑分隔符skills目錄掃描在 Windows 下用反斜杠Linux 下用正斜杠代碼里不要硬編碼任何路徑盡量用pathlib去拼。第二是權(quán)限模型Linux 下讀取磁盤信息和進(jìn)程信息有時(shí)需要 sudo所以如果你的 Skill 里有這些操作要提前想好運(yùn)行 OpenClaw 的服務(wù)賬號(hào)權(quán)限。Windows 上還有一種常見坑就是 PowerShell 的默認(rèn)編碼和 Python 輸出的 UTF-8 不兼容。我自己碰到過腳本單獨(dú)運(yùn)行沒問題接入 OpenClaw 后中文信息全變成亂碼。后來在啟動(dòng)腳本里加了環(huán)境變量才解決。這個(gè)問題不算復(fù)雜但一旦碰上會(huì)浪費(fèi)一下午在這里提個(gè)醒。5. 我的建議與擴(kuò)展方向5.1 新手的入場(chǎng)順序如果讓我給新手排一個(gè)開發(fā)路線我的建議是這樣的先寫一個(gè)不帶參數(shù)、只返回“hello world”的最小 Skill跑通注冊(cè)和調(diào)用鏈路然后給這個(gè)最小 Skill 加一個(gè)參數(shù)體驗(yàn)一下參數(shù)傳遞如何影響輸出再把它替換成有實(shí)際價(jià)值的系統(tǒng)信息采集技能體驗(yàn)完整業(yè)務(wù)閉環(huán)最后再去嘗試 API 類、數(shù)據(jù)庫類、文件操作類的復(fù)雜技能。這條路徑看起來慢其實(shí)最快。因?yàn)槟忝恳徊蕉贾辉黾右粋€(gè)變量出了問題能立刻定位。反觀一上來就想寫個(gè)大而全的電商助手、GIS 分析助手結(jié)局往往是卡在環(huán)境問題上連“我的代碼到底有沒有被執(zhí)行”都不知道。5.2 值得擴(kuò)展的方向Skill 這個(gè)機(jī)制本身是中性的任何領(lǐng)域能力都可以封裝成技能。我目前看到社區(qū)里有人在寫 GIS 空間分析技能把常用空間操作包裝成 Skill 給 Agent 調(diào)用也有做電商場(chǎng)景的把商品查詢、價(jià)格計(jì)算做成技能ROS2 方向也有人在做嘗試想通過 Skill 讓 Agent 間接控制機(jī)器人仿真環(huán)境。這些嘗試的共同點(diǎn)就是把原本需要手動(dòng)寫腳本的領(lǐng)域邏輯變成模型可以按需調(diào)用的“工具”。往深了做還有兩個(gè)方向值得關(guān)注。一個(gè)是多技能協(xié)作比如先調(diào)用系統(tǒng)信息技能拿到本機(jī)狀態(tài)再根據(jù)狀態(tài)決定要不要調(diào)用另一個(gè)清理技能這種“技能編排”會(huì)極大豐富 Agent 的行為能力。另一個(gè)是技能參數(shù)復(fù)雜化讓 Skill 支持結(jié)構(gòu)化參數(shù)對(duì)象而不是一層的鍵值對(duì)這能讓技能適應(yīng)更復(fù)雜的業(yè)務(wù)輸入。最后分享一個(gè)小技巧調(diào)試 Skill 時(shí)一定要讓 Agent 肉眼可見地拿到結(jié)果。我的做法是先在單獨(dú)測(cè)試入口里把返回的 JSON 字符串寫到一個(gè)臨時(shí)文件確認(rèn)文件內(nèi)容完全正確再接 OpenClaw 聯(lián)調(diào)。等這一步穩(wěn)了再去做參數(shù)變形和異常分支。按這個(gè)順序走我基本沒再遇到過“卡在兩套環(huán)境之間”的難題希望你也能一次跑通。