一、前置基础认知
1. 什么是 Skill 技能
Skill 是 OpenClawSkills 技能层的最小可插拔单元，是 AI 真正操作电脑、调用接口、处理文件的执行载体。
四层架构对应关系：

Gateway接收指令 → Agent判断需求 → 匹配自定义Skill执行 → Memory存储结果

所有本地文件读写、接口请求、脚本运行、业务自动化都依靠自定义 Skill 实现，分为两类：

1. 轻量文档型 Skill（SKILL.md）：无需代码，仅写自然语言执行脚本，新手快速搭建简单自动化；
2. 代码插件型 Skill（JS/TS/Python）：复杂业务、API 对接、批量文件处理、企业私有系统对接，支持完整逻辑、参数校验、权限管控。

2. 技能标准目录结构（固定规范）
所有自定义技能统一存放路径：
Windows(WSL2) / Linux / macOS：~/.openclaw/workspace/skills/
单个技能文件夹完整结构：

my-office-stat/ # 技能唯一名称（小写、连字符，不能中文）

├── SKILL.md # 【必需】技能元数据+功能描述，AI识别调用的核心

├── manifest.json # 【代码型必需】权限、参数、运行环境声明

├── index.js / index.ts # 【代码型必需】主执行逻辑入口

├── scripts/ # 可选：存放bash/python辅助脚本

├── assets/ # 可选：报表模板、静态资源

└── references/ # 可选：API文档、业务参考资料

二、开发前置环境准备

1. 已完整部署 OpenClaw，网关正常运行

openclaw gateway start -d
openclaw status

开发依赖（二选一）
·JS/TS 开发（官方推荐）：Node.js 22 LTS，内置openclaw-sdk无需额外安装
·Python 开发：Python3.10+，在 manifest 声明 runtime 为python
基础命令：技能目录热加载，修改文件无需重启网关，系统自动监听变更
三、方案 1：零代码轻量技能（SKILL.md，新手入门）
适合简单自动化：文件整理、简易 shell 脚本、固定重复流程，不用编写 JS 代码。

步骤 1：创建技能文件夹

# 创建文本批量处理技能
mkdir -p ~/.openclaw/workspace/skills/text-batch-handle
cd ~/.openclaw/workspace/skills/text-batch-handle

步骤 2：编写 SKILL.md（核心文件）
文件顶部---包裹 YAML 元数据，下方写 Markdown 功能说明与执行逻辑。

---

name: text-batch-handle

description: 批量处理本地文本文件，支持去重、大小写转换、关键词提取，当用户需要批量处理txt文档时自动调用

emoji: "📝"

user-invocable: true

always: false

os: ["linux", "darwin", "win32"]

---

# 文本批量处理技能

## 触发规则

用户指令包含：批量txt、文本去重、大小写转换、提取关键词时，优先使用本技能。

## 入参

1. dir_path：本地文件夹绝对路径，必填

2. operate：操作类型，可选 deduplicate / upper / lower / keyword

## 执行步骤

1. 读取dir_path下全部.txt文件

2. 根据operate执行对应文本处理

3. 在目录生成result.md汇总结果

## 执行脚本

```bash

for file in $dir_path/*.txt; do

  cat $file >> temp-all.txt

done

# 执行文本处理逻辑

返回要求
输出处理完成文件路径、总处理文件数量

关键字段说明
name：全局唯一，小写字母 + 连字符，不可重复
description：最关键，Agent 依靠这段文字判断何时调用该技能，描述越清晰匹配越精准
user-invocable: true：允许用户手动斜杠命令调用 /text-batch-handle
os：限制运行系统，全部兼容填写["linux","darwin","win32"]

步骤 3：测试零代码技能
（1）保存文件，网关自动热加载
（2）Web 面板发送指令：

把D盘笔记文件夹所有txt批量提取关键词，生成汇总文件

（3）Agent 自动识别匹配text-batch-handle技能执行

四、方案 2：代码型插件技能（JS/TS，企业复杂业务推荐）
可实现接口调用、数据库读写、复杂循环逻辑、参数校验、密钥安全存储，适合办公自动化、私有系统对接。
完整分 4 步：创建目录→配置 manifest.json→编写执行代码 index.js→本地调试启用。
步骤 1：新建技能目录

mkdir -p ~/.openclaw/workspace/skills/stock-query
cd ~/.openclaw/workspace/skills/stock-query

步骤 2：编写 manifest.json（权限 + 参数 + 环境声明，2026.4 + 强制）
核心作用：声明技能权限、入参 JSON Schema、依赖环境变量、运行时类型，沙箱会根据配置放行文件 / 网络权限。

json
{
  "name": "stock-query",
  "version": "1.0.0",
  "author": "自定义开发者",
  "runtime": "node",
  "entry": "./index.js",
  "description": "查询A股实时股票行情，传入股票代码返回价格、涨跌幅",
  "user-invocable": true,
  "permissions": {
    "network": {
      "allow": ["hq.sinajs.cn"]
    },
    "fs": {
      "write": ["~/.openclaw/workspace/skills/stock-query/cache/"]
    }
  },
  "input": {
    "type": "object",
    "required": ["stock_code"],
    "properties": {
      "stock_code": {
        "type": "string",
        "description": "A股6位股票代码"
      }
    }
  },
  "output": {
    "type": "object",
    "properties": {
      "success": {"type": "boolean"},
      "message": {"type": "string"},
      "data": {"type": "object"}
    }
  },
  "requires": {
    "env": []
  },
  "metadata": {
    "openclaw": {
      "emoji": "📈",
      "os": ["linux", "darwin", "win32"]
    }
  }
}

核心配置项：
（1）permissions 权限（最小权限原则，禁止全盘读写 / 无限制网络）
fs.read/write：允许读写的本地目录
network.allow：允许访问的域名，禁止填*
（2）input：入参校验，AI 调用时自动校验参数完整性，缺失直接报错
（3）runtime：node/python，对应入口文件语言
步骤 3：编写核心执行代码 index.js
框架内置openclaw-sdk，提供上下文、日志、环境变量读取能力，固定导出execute异步函数。

// 导入官方SDK
const { SkillContext } = require("openclaw-sdk");
const http = require("http");
const fs = require("fs");
const path = require("path");

/**
 * 技能统一执行入口
 * @param {SkillContext} context 上下文对象（参数、日志、环境变量）
 * @returns 标准化返回结果
 */
exports.execute = async function (context) {
  try {
    // 1. 获取AI传入的参数（与manifest input对应）
    const { stock_code } = context.parameters;
    context.log.info(`开始查询股票：${stock_code}`);

    // 2. 接口请求逻辑
    let url;
    if (stock_code.startsWith("6")) {
      url = `http://hq.sinajs.cn/list=s_sh${stock_code}`;
    } else {
      url = `http://hq.sinajs.cn/list=s_sz${stock_code}`;
    }

    // 封装http请求
    const stockData = await new Promise((resolve, reject) => {
      http.get(url, (res) => {
        let raw = "";
        res.on("data", chunk => raw += chunk);
        res.on("end", () => resolve(raw));
      }).on("error", reject);
    });

    // 3. 解析返回数据
    const match = stockData.match(/="([^"]+)"/);
    if (!match) throw new Error("未查询到该股票信息");
    const arr = match[1].split(",");
    const result = {
      name: arr[0],
      open: arr[1],
      close: arr[2],
      high: arr[3],
      low: arr[4],
      change: (Number(arr[2]) - Number(arr[1])).toFixed(2)
    };

    // 4. 缓存结果到本地文件（使用声明过的权限目录）
    const cachePath = path.join(__dirname, "./cache/stock-cache.json");
    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
    fs.writeFileSync(cachePath, JSON.stringify(result, null, 2));

    // 标准化成功返回格式
    return {
      success: true,
      message: `股票${stock_code}行情查询完成`,
      data: result
    };
  } catch (err) {
    // 统一异常捕获，返回错误信息
    context.log.error("技能执行失败：", err.message);
    return {
      success: false,
      message: `查询失败：${err.message}`,
      data: null
    };
  }
};

context 上下文内置能力
·context.parameters：AI 传递的入参
·context.log.info/warn/error：写入全局日志，openclaw logs可查看
·context.env.XXX：读取全局环境变量（如 API 密钥）
·context.sessionId：当前会话 ID，区分不同用户任务
步骤 4：技能启用、调试、测试
（1）自动加载：保存文件后网关自动扫描识别新技能
（2）查看已加载技能列表，确认存在

openclaw skills list
# 启用自定义技能
openclaw skills enable stock-query
# 实时查看技能运行日志
openclaw logs --follow

Web 面板测试指令：

查询股票600036实时行情

Agent 自动调用stock-query技能，拉取行情并返回格式化数据。

五、Python 版技能开发补充
如需 Python 实现业务逻辑，仅修改两处：
（1）manifest.json 中runtime: "python"，entry: "./main.py"
（2）编写 main.py，固定读取标准输入参数、标准输出返回 JSON

#!/usr/bin/env python3
import json
import sys

def main():
    # 读取AI传入参数
    raw_input = sys.stdin.read()
    params = json.loads(raw_input)
    stock_code = params.get("stock_code")
    # 业务逻辑...
    res = {
        "success": True,
        "message": "查询完成",
        "data": {"price": "12.34"}
    }
    # 标准输出返回JSON
    print(json.dumps(res))

if __name__ == "__main__":
    main()

六、技能安全开发规范（企业必遵守）
1.权限最小化
·文件读写只开放业务必需目录，禁止/全盘、C:\根目录
·网络仅放行目标 API 域名，禁止*通配所有网站
2.密钥安全
API 密钥、账号密码禁止硬编码写死在代码 / 配置，统一通过全局环境变量传入：

# 全局配置环境变量
openclaw config set stock.api_key "xxx"
# 代码读取 context.env.stock_api_key

3.参数强制校验
manifest 中定义required必填项，代码内部二次校验，防止空参数、路径注入风险
4.全链路日志记录
所有文件修改、网络请求、外部接口调用必须写入 context 日志，方便审计回溯
5.禁止高危操作
不允许 rm -rf 全盘删除、系统关机、root 级脚本执行，企业部署可通过网关全局封禁高危 shell 指令

七、技能运维常用命令

# 查看所有本地技能
openclaw skills list
# 启用/禁用自定义技能
openclaw skills enable 技能名
openclaw skills disable 技能名
# 一键校验技能manifest配置、权限是否合规
openclaw doctor skills
# 实时监控技能执行日志
openclaw logs --follow
# 重新加载全部技能（修改元数据后刷新）
openclaw gateway restart
# 卸载自定义技能（直接删除技能文件夹即可，自动失效）
rm -rf ~/.openclaw/workspace/skills/技能名

八、开发避坑指南
1.技能名称只能小写 + 连字符，中文 / 大写会导致加载失败
2.manifest 权限配置错误会触发沙箱拦截，文件读写、网络请求直接报错，执行openclaw doctor skills一键检测
3.SKILL.md 的 description 描述模糊会导致 Agent 无法匹配调用，写清触发场景 + 完整功能
4.Windows WSL 路径必须使用 Linux 格式/mnt/d/xxx，不能使用D:\xxx
5.代码返回格式必须固定{success, message, data}，否则 Agent 无法解析执行结果
6.新增环境变量后需要重启网关才能生效
7.Ollama 离线模式下，自定义技能网络权限仍会生效，内网接口需手动放行域名

九、技能发布（可选，分享到 ClawHub 社区）
开发完成稳定后，可打包发布到官方插件市场 ClawHub：
1.完善 SKILL.md 使用文档、参数说明
2.补充 README、示例调用指令
3.执行打包命令

clawhub package ./stock-query
# 登录账号上传
clawhub publish stock-query-1.0.0.clawpkg

其他用户可一键安装你的自定义技能：

clawhub install stock-query