1. 为什么需要自定义 OpenClaw 技能从通用 Agent 到业务专精OpenClaw 是一套可扩展的 AI Agent 运行框架它把「模型能力」和「具体动作」拆开模型负责理解意图技能负责执行动作。内置技能覆盖了搜索、文件读写、命令执行这类通用场景但一旦落到真实业务里通用能力往往不够用。比如你要让 Agent 每天定时拉取内部库存接口、按阈值生成补货建议、再把结果写进飞书表格这套流程没有任何内置技能能直接完成必须自己写一个。自定义技能的价值就在这里它让 Agent 从「什么都能聊两句」变成「这件事只有它能干得准」。我接触过的团队里凡是把 Agent 真正用起来的几乎都走过自定义技能这一步。原因很直接——通用模型对私有接口、私有数据格式、私有业务规则一无所知你不把规则写进技能Agent 就只能靠猜。OpenClaw 的技能系统采用「SKILL.md 脚本」的架构。SKILL.md 是技能描述骨架告诉 Agent 这个技能什么时候该被调用、需要什么参数、返回什么脚本是实际执行逻辑用 Python、Node.js 或 Shell 都行。这种设计的好处是门槛低你不需要改框架源码只要在 skills 目录下新建一个文件夹放一个 SKILL.md 和一个脚本重启后 Agent 就能识别。本文聚焦从零开发一个可运行的技能并把它接入 TaoToken 的统一 Key/API 通道。TaoToken 在这里扮演的是模型调用入口的角色——技能脚本里如果需要调用大模型做二次处理比如把抓取到的原始数据总结成自然语言就可以通过 TaoToken 的 API 完成而不必在技能里硬编码某一家模型的地址和密钥。这样技能本身保持干净模型切换只改配置。适合读这篇的人已经跑通 OpenClaw 基础对话、想让 Agent 接入自己业务接口的开发者或者正在评估 Agent 框架、想看看自定义能力开发到底要写多少代码的技术负责人。下面我会给出完整的目录结构、SKILL.md 模板、脚本代码、config.toml 配置骨架以及一次真实请求的验证步骤你可以直接照着改。2. TaoToken 前置准备统一 Key 与 API 通道配置在写技能之前先把模型调用通道准备好。OpenClaw 的技能脚本如果要调用大模型最省事的做法是走一个统一的 OpenAI 兼容接口而不是在每个技能里分别对接不同厂商。TaoToken 提供的正是这样一个入口一个 Base URL、一个 Key就能调用多种模型。你需要先拿到 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次关掉页面就看不到了建议直接写进环境变量或配置文件别贴在聊天记录里。拿到 Key 之后记下两个地址。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址是https://taotoken.net/api。注意 API 地址后面不加任何查询参数直接作为 Base URL 使用。模型 ID 按你实际要用的填比如claude-sonnet-4-5这类具体以控制台模型列表为准。这里有个容易踩的坑很多人把 Base URL 写成带/v1的完整路径结果请求 404。OpenClaw 的技能脚本里如果你用的是 OpenAI SDK通常 Base URL 填https://taotoken.net/apiSDK 会自动补/v1/chat/completions如果你手写 HTTP 请求就要自己拼完整路径。两种方式都对关键是别重复拼。配置建议放在环境变量里而不是硬编码进脚本。原因很简单技能目录可能会提交到 GitKey 写死在代码里等于泄露。推荐在技能目录下放一个.env文件或者用系统级环境变量。OpenClaw 启动时会读取技能目录下的配置你可以在config.toml里声明环境变量映射。如果你用的是 Claude Code 这类工具做技能脚本的辅助开发也可以在它的配置里指向同一个 Base URL这样开发和生产用的是同一套通道减少环境差异带来的问题。TaoToken 的接入文档里有各语言 SDK 的示例照着改 Base URL 和 Key 即可。前置准备清单一个可用的 API Key、确认 Base URL 为https://taotoken.net/api、确认要用的模型 ID、把 Key 写进环境变量。这四件事做完再进入技能开发后面就不会因为通道问题卡住。3. 可复制配置SKILL.md 模板与 config.toml 骨架这一节给出可以直接复制的文件内容。先看目录结构这是 OpenClaw 技能的标准布局skills/ └── inventory-monitor/ ├── SKILL.md ├── monitor.py ├── requirements.txt └── config.tomlSKILL.md是技能描述骨架Agent 靠它判断是否调用。下面是一个库存监控技能的模板你可以把触发条件和参数说明改成自己的业务# 库存监控技能 ## 触发条件 当用户要求查询商品库存、检查补货时机、生成库存预警报告时调用此技能。 示例触发词查一下库存、哪些商品该补货了、生成库存预警。 ## 功能描述 接收商品 ID 列表和库存阈值调用内部库存接口获取当前库存 对低于阈值的商品生成补货建议并返回结构化报告。 ## 使用方法 bash openclaw skill-call inventory-monitor {sku_ids: [A001, A002], threshold: 10}参数说明sku_ids商品 ID 数组必填threshold库存预警阈值选填默认 10输出格式返回 JSON包含 alert_list预警商品、summary汇总文本。注意事项需要内部库存接口的网络访问权限接口超时设置为 10 秒失败重试 2 次注意 SKILL.md 里的触发条件要写得具体。写「处理库存相关请求」太模糊Agent 可能在不该调用的时候调用写「当用户要求查询商品库存、检查补货时机时调用」就明确得多。这是我在实际项目里反复验证过的经验触发条件越具体误调用越少。 接下来是 config.toml这是接入 TaoToken 的配置骨架。OpenClaw 读取这个文件来获取模型通道信息 toml [model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_id claude-sonnet-4-5 timeout 30 [skill.inventory-monitor] enabled true script monitor.py timeout 120 env { INVENTORY_API ${INVENTORY_API_URL} }这里api_key用${TAOTOKEN_API_KEY}引用环境变量而不是写明文。启动 OpenClaw 前先export TAOTOKEN_API_KEY你的Key。base_url就是前面说的https://taotoken.net/api不要加/v1。model_id按控制台实际可用的填。requirements.txt里声明脚本依赖requests2.31.0如果你需要调用大模型做文本总结再加openai1.0.0。这个技能本身只做库存查询模型调用是可选的所以先不强制依赖。三件套对照一下Base URL 是https://taotoken.net/apiKey 是你在控制台创建的那串字符Model ID 是claude-sonnet-4-5或你实际用的。这三个值在 config.toml 里各就各位技能脚本通过读取配置拿到它们不需要自己再拼。4. 验证请求与成功结果一次真实调用全过程配置写完后先别急着写复杂脚本用一个最小可运行版本验证通道是否通。monitor.py先写成这样import json import os import sys import requests def fetch_inventory(sku_ids): api os.environ.get(INVENTORY_API, ) # 这里替换成你的真实库存接口 # 演示用假数据 return {sku: 5 for sku in sku_ids} def main(): params json.loads(sys.argv[1]) sku_ids params.get(sku_ids, []) threshold params.get(threshold, 10) inventory fetch_inventory(sku_ids) alert_list [ {sku: sku, stock: stock} for sku, stock in inventory.items() if stock threshold ] result { alert_list: alert_list, summary: f共检查 {len(sku_ids)} 个商品{len(alert_list)} 个需要补货 } print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()保存后先单独跑一次脚本确认它能输出 JSONpython skills/inventory-monitor/monitor.py {sku_ids: [A001, A002], threshold: 10}预期输出{alert_list: [{sku: A001, stock: 5}, {sku: A002, stock: 5}], summary: 共检查 2 个商品2 个需要补货}脚本能跑通再通过 OpenClaw 调用openclaw skill-call inventory-monitor {sku_ids: [A001, A002], threshold: 10}如果 OpenClaw 返回了同样的 JSON说明技能注册成功。接下来验证 TaoToken 通道。写一个最小的模型调用测试确认 Base URL 和 Key 可用from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: 用一句话说明库存预警的意义}], ) print(resp.choices[0].message.content)运行后如果打印出一句通顺的中文说明通道正常。这一步很关键因为技能脚本里如果要做文本总结走的就是这个通道。我试过把 Base URL 误写成带/v1的地址结果报 404改回https://taotoken.net/api就正常了。成功结果的特征脚本输出合法 JSON、OpenClaw 能识别技能名、模型调用返回非空内容。三者都满足就可以把技能接入真实业务接口了。把fetch_inventory里的假数据换成真实 HTTP 请求加上超时和重试技能就具备生产可用性。5. 本篇常见错排查401、local proxy failed、reading choices技能开发过程中最容易卡住的不是业务逻辑而是通道和配置问题。下面按真实报错逐条排查。报错一401 Unauthorized。这是 Key 问题。先确认环境变量是否真的导出成功在终端执行echo $TAOTOKEN_API_KEY如果为空说明没导出。注意export只在当前终端会话有效换一个终端就没了建议写进~/.bashrc或~/.zshrc。如果 Key 确认存在仍报 401检查是不是复制时带了空格或换行重新从控制台复制一次。还有一种情况是 Key 被删除或过期去控制台确认状态。报错二local proxy failed。这个报错通常出现在脚本里配置了本地代理地址但代理服务没启动。检查你的脚本或环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类设置如果有就临时取消掉再试。OpenClaw 技能脚本直接访问https://taotoken.net/api即可不需要额外代理层。如果公司网络有统一出口按网络管理员给的配置来别自己乱设。报错三reading choices 相关错误。典型表现是KeyError: choices或list index out of range。这说明返回的 JSON 里没有choices字段通常是请求根本没成功返回的是错误信息。打印完整响应体看看resp client.chat.completions.create(...) print(resp.model_dump())常见原因是模型 ID 写错比如写了一个控制台里不存在的模型名接口返回错误对象。对照控制台模型列表改成正确的 ID。另一个原因是 Base URL 拼错请求打到了不存在的路径返回 HTML 而不是 JSON解析时自然找不到choices。报错四OAuth 相关错误。如果你用的是 Claude Code 或类似工具做辅助开发可能会遇到 OAuth 认证失败。这类工具默认走官方 OAuth 流程如果你要指向 TaoToken 的 API 通道需要在配置里显式设置 Base URL 和 Key而不是依赖 OAuth。检查工具的配置文件确认base_url指向https://taotoken.net/api并且提供了 API Key。OAuth 和 API Key 是两套认证方式别混用。报错五skill not found。技能目录名和调用名不一致。OpenClaw 按目录名注册技能skills/inventory-monitor/对应的调用名就是inventory-monitor。检查目录名有没有拼错以及config.toml里[skill.inventory-monitor]这一段是否和目录名一致。排查顺序建议先确认环境变量再确认 Base URL再确认模型 ID最后看脚本逻辑。大部分问题出在前三步而不是代码本身。6. 语义一致 CTA把技能接到真实业务技能跑通之后下一步是把它接到真实业务接口。把fetch_inventory里的假数据替换成你的内部 API 调用加上超时和重试def fetch_inventory(sku_ids): api os.environ[INVENTORY_API] result {} for sku in sku_ids: for attempt in range(3): try: resp requests.get(f{api}/stock/{sku}, timeout10) resp.raise_for_status() result[sku] resp.json()[stock] break except requests.RequestException: if attempt 2: result[sku] -1 return result如果技能里需要模型做二次处理比如把预警列表总结成一段自然语言就调用 TaoToken 通道。模型对话入口在https://taotoken.net/api配合你的 Key 和模型 ID 即可。需要管理多个 Key 或查看调用量去控制台需要长期跑编码类 Agent 任务可以了解 Coding Plan接入细节看文档。技能开发这件事写第一个的时候会觉得步骤多写到第三个就会发现套路固定SKILL.md 写清楚触发条件脚本做好错误处理config.toml 管好通道配置。真正花时间的不是代码而是想清楚这个技能该在什么时候被调用、返回什么格式对 Agent 最友好。把这两点想明白剩下的都是填空。