1. 为什么我要给龙虾智能体写自定义 Skill龙虾智能体OpenClaw基础部署跑通之后你会发现它默认能力其实很通用能聊天、能查资料、能写点代码但一旦涉及你团队内部的业务逻辑比如读一下我们销售系统的 CSV 然后出一份周报它就抓瞎了。原因很简单——它不知道你的数据长什么样也不知道你的报告格式要求。这就是 Skill 插件存在的意义。Skill 本质上是给 Agent 挂载的一个能力模块它用一份描述文件告诉模型三件事这个能力叫什么、需要传什么参数、执行后返回什么。模型负责理解用户意图并决定调用哪个 Skill真正的脏活累活交给你的 handler 代码去干。这样一来Agent 就从通用助手变成了懂你业务的数字同事。这篇内容面向的是已经跑通 OpenClaw 基础环境、想进一步扩展私有能力的开发者。我会带你从零写一个可用的 Skill 插件把目录骨架、skill.md元数据、handler 逻辑、config.toml与settings.json配置片段全部给出来然后重点讲多模型适配——也就是怎么通过 TaoToken 的统一 Key 和 API 通道让同一个 Skill 在不同模型之间自由切换最后完成插件注册、模型切换、调用回显的端到端验证。全程可复制踩过的坑我也会标出来。2. TaoToken 前置准备统一 Key 与通道配置在写 Skill 之前先把模型接入这一层理顺。OpenClaw 支持多种模型后端但如果你每个模型都单独配一套 Key、单独维护 base_url配置会迅速膨胀成一团乱麻。我的做法是统一走 TaoToken 的 API 通道一个 Key 覆盖多个模型切换模型时只改模型名不动鉴权信息。先拿到你的 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key建议按用途命名比如openclaw-skill-dev方便后续排查是哪个环境在调用。创建后立刻复制保存页面刷新后就看不到完整 Key 了。拿到 Key 之后OpenClaw 侧的接入信息这样填配置项值API Base URLhttps://taotoken.net/apiAPI Key你在控制台创建的 Key默认模型按需选择例如claude-sonnet或gpt-4o请求格式OpenAI 兼容/v1/chat/completions这里有个细节要注意Base URL 填https://taotoken.net/api就够了OpenClaw 内部会拼接/v1/chat/completions这类路径。如果你手动填成带/v1的地址容易出现路径重复导致 404。我一开始就踩过这个坑报错信息是404 page not found排查了半天才发现是路径拼了两遍。配置写进 OpenClaw 的主配置文件config.toml[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 default_model claude-sonnet timeout 60 [model.fallback] enabled true chain [claude-sonnet, gpt-4o, qwen-plus]fallback这一段是多模型适配的关键。当首选模型超时或返回错误时OpenClaw 会按chain顺序自动降级到下一个模型保证 Skill 调用不会因为单个模型抖动而整体失败。这个降级链在跑批处理任务时特别有用。3. 可复制的 Skill 插件目录骨架一个规范的 Skill 插件目录长这样我建议你直接照这个结构建csv-analyzer/ ├── skill.md # Skill 元数据与参数 Schema ├── handler.py # 执行逻辑Python 实现 ├── handler.js # 执行逻辑Node.js 实现二选一 ├── config.json # Skill 级默认配置 ├── requirements.txt # Python 依赖 └── README.md # 使用说明skill.md是整个插件的入口模型靠它理解这个 Skill 能干什么。下面是一个可直接用的模板--- name: csv-analyzer description: 分析 CSV 文件并生成统计报告支持概况、相关性、分布三种分析类型 parameters: - name: file_path type: string description: CSV 文件的绝对路径 required: true - name: analysis_type type: string description: 分析类型可选 summary、correlation、distribution default: summary enum: [summary, correlation, distribution] handler: handler.py runtime: python dependencies: - pandas - numpy ---description这一行非常关键模型就是靠它判断用户这句话该不该触发这个 Skill。写得太笼统比如分析数据会导致误触发写得太窄又会导致该调用时不调用。我的经验是把触发场景和参数含义都写进去模型的理解准确率会明显提升。handler 用 Python 实现核心逻辑是读 CSV、按分析类型算统计量、返回 JSONimport pandas as pd import numpy as np import json import sys def analyze_csv(file_path, analysis_type): df pd.read_csv(file_path) result { file: file_path, rows: len(df), columns: len(df.columns), column_names: list(df.columns) } if analysis_type summary: numeric_cols df.select_dtypes(include[np.number]).columns result[numeric_summary] {} for col in numeric_cols: result[numeric_summary][col] { mean: float(df[col].mean()), median: float(df[col].median()), std: float(df[col].std()), min: float(df[col].min()), max: float(df[col].max()), null_count: int(df[col].isnull().sum()) } elif analysis_type correlation: numeric_df df.select_dtypes(include[np.number]) if len(numeric_df.columns) 1: result[correlation_matrix] numeric_df.corr().to_dict() print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: params json.loads(sys.argv[1]) analyze_csv(params[file_path], params.get(analysis_type, summary))注意最后是print出 JSON 而不是return因为 OpenClaw 通过标准输出捕获 handler 的结果。如果你用 Node.js 写对应的是console.log。这个约定不遵守的话Skill 会执行成功但返回空结果很难排查。4. 多模型适配settings.json 与动态路由Skill 写好了接下来是让它能在多个模型之间灵活切换。OpenClaw 的模型路由配置放在settings.json里支持按关键词匹配自动选模型{ model_routing: { rules: [ { pattern: code|编程|代码|bug|debug, model: deepseek-coder }, { pattern: translate|翻译, model: qwen-plus }, { pattern: .*, model: claude-sonnet } ] }, model_fallback: { claude-sonnet: [gpt-4o, qwen-plus], deepseek-coder: [gpt-4o] } }规则从上往下匹配第一条命中就停止。所以兜底的.*必须放最后。我实测下来把代码类请求路由到专门的代码模型生成质量比通用模型稳定不少尤其是涉及多文件重构的场景。模型选择上我整理了一张对照表供参考场景推荐模型理由中文对话与总结qwen-plus中文表达自然响应快代码生成与调试deepseek-coder代码补全质量高复杂推理与规划claude-sonnet长链路推理稳定轻量高频任务gpt-4o-mini成本低速度快需要说明的是这些模型都通过同一个 TaoToken Key 调用你不需要为每个模型单独申请账号。切换模型时只改settings.json里的模型名鉴权信息完全不动这是统一通道最大的好处。如果你要长期跑编码类 Agent 任务可以考虑 TaoToken 的 Coding Plan它在高频调用场景下比按量计费更划算具体可以在控制台里对比一下用量再决定。5. 验证请求注册 Skill 并跑通端到端回显配置齐了现在做端到端验证。第一步安装 Skillopenclaw skill install ./csv-analyzer安装成功后应该能看到类似Skill csv-analyzer registered的回显。如果报skill.md not found检查你是不是在插件目录的上一级执行命令——install后面跟的应该是插件目录路径。第二步准备一份测试 CSVcat /tmp/test-sales.csv EOF date,region,amount,quantity 2024-01-01,North,1200,3 2024-01-02,South,800,2 2024-01-03,North,1500,4 2024-01-04,East,950,2 EOF第三步发起调用openclaw chat 用 csv-analyzer 分析 /tmp/test-sales.csv给我概况预期回显里应该包含rows: 4、columns: 4以及amount和quantity两列的均值、中位数等统计量。如果模型正确触发了 Skill你会看到它先输出一段正在调用 csv-analyzer的说明然后贴出 JSON 结果。第四步验证多模型切换。把settings.json里的默认模型从claude-sonnet改成qwen-plus重启 OpenClaw 后重复上面的调用。结果 JSON 应该完全一致因为 Skill 的执行逻辑和模型无关模型只负责决定调用这一层。这一步能跑通说明你的多模型适配链路是通的。6. 本篇常见错误排查Skill 注册成功但模型不调用。九成是description写得太模糊。模型判断是否调用 Skill 完全依赖这段描述如果它和用户 query 的语义距离太远模型就会选择直接回答而不是调用。解决办法是把典型触发语句写进描述比如当用户要求分析 CSV、生成数据报告时使用。handler 执行报ModuleNotFoundError。Python 依赖没装。在插件目录下执行pip install -r requirements.txt注意要装到 OpenClaw 运行时的同一个 Python 环境里。如果你用虚拟环境确认 OpenClaw 启动时激活的是同一个。调用返回 401 或 403。检查config.toml里的api_key是否完整、有没有多余空格。TaoToken 的 Key 以sk-开头复制时容易带上首尾空白。另外确认base_url是https://taotoken.net/api不要手动加/v1。模型降级不生效。model_fallback的 key 必须和model_routing里出现的模型名完全一致大小写敏感。我见过把claude-sonnet写成Claude-Sonnet导致降级链匹配不上的情况。返回结果为空但没报错。大概率是 handler 用了return而不是print/console.log。OpenClaw 通过标准输出读取结果函数返回值它拿不到。切换模型后 Skill 行为异常。不同模型对参数 Schema 的理解能力有差异。如果某个模型频繁传错参数类型可以在skill.md的description里把参数格式写得更明确比如file_path 必须是绝对路径以 / 开头。排查时建议打开 OpenClaw 的 debug 日志能看到每次请求实际路由到了哪个模型、Skill 是否被触发、handler 的原始输出是什么。这三个信息基本能定位绝大多数问题。接入相关的配置细节和 API 参数说明可以对照 TaoToken 的接入文档核对想先验证模型对话是否正常可以直接在模型对话页面发一条测试消息长期跑编码类 Agent 的话Coding Plan 的用量模型值得对比一下。
