---

一、引言：为什么需要理解 Skills 系统？

OpenClaw 作为一款强大的 AI Agent 框架，其核心魅力不仅在于内置的工具集，更在于极度灵活的可扩展性。而这一切的基石，正是 Skills 系统——一个基于 AgentSkills 规范的插件化架构。

如果你只是使用 OpenClaw 的默认功能，那可能只用了其 30% 的能力。当你需要：

• 集成内部工具（公司数据库、私有 API）
• 为特定场景定制智能行为（如股票分析、代码审查）
• 贡献社区技能，建立个人影响力
• 理解框架源码，进行深度定制

这时，Skills 系统就是你必须掌握的桥梁。本文将从源码级别剖析 Skills 的加载、配置、分发机制，并提供手把手的实战教程，让你从使用者变为扩展者。

---

二、Skills 系统架构解析

技能在哪里？——三层加载优先级

OpenClaw 的技能来源分为三个层次，形成一个清晰的优先级链：

1. Bundled Skills（内置技能）

随 OpenClaw npm 包或应用一起安装的技能，位于：

/Users/xgn/.npm-global/lib/node_modules/openclaw/skills/

示例：coding-agent、peekaboo、gemini、github 等。

2. Managed/Local Skills（管理技能）

用户级覆盖目录：

~/.openclaw/skills/

用于局部修改内置技能（比如 patch 一个 bug 或调整提示词），而无需改动 bundled 版本。

3. Workspace Skills（工作区技能）

当前 OpenClaw 会话的工作区目录：

<workspace>/skills/

你可以为不同项目配置不同的技能集，实现完全隔离。

Precedence 规则（优先级）

<workspace>/skills  (最高) → ~/.openclaw/skills → bundled skills (最低)

同名技能，workspace 版本始终胜出。这意味着你可以安全地覆盖任何内置技能，而不会影响全局。

实战：覆盖内置技能

假设你想修改 coding-agent 的提示词：

# 1. 在工作区创建同名技能目录
mkdir -p ~/.openclaw/workspace/skills/coding-agent

# 2. 复制原技能文件（从 bundled 复制过来）
cp /Users/xgn/.npm-global/lib/node_modules/openclaw/skills/coding-agent/SKILL.md \
   ~/.openclaw/workspace/skills/coding-agent/

# 3. 编辑 SKILL.md，修改指令部分
# 4. 启动新会话，workspace 版本自动覆盖 bundled

Skills 与 Plugins 的关系

OpenClaw 的插件（Plugins）可以打包自己的技能，在 openclaw.plugin.json 中声明：

{
  "skills": ["./skills"]  // 相对路径
}

插件技能在插件启用时加载，参与同样的优先级规则。这使得：

• 功能模块化（例如 feishu 插件打包 4 个技能：doc/drive/perm/wiki）
• 第三方开发者可以分发完整的技能+工具包

单 Agent vs 多 Agent 场景

在多 Agent 架构中，每个 Agent 有独立的 workspace。因此：

• Per-agent skills：放在 <workspace>/skills，仅该 Agent 可见
• Shared skills：放在 ~/.openclaw/skills，所有同机 Agent 共享
• Extra dirs：通过 skills.load.extraDirs 配置，最低优先级，适合共享技能包

{
  skills: {
    load: {
      extraDirs: ["~/Projects/oss/skill-pack/skills"]
    }
  }
}

---

三、SKILL.md 格式详解

Frontmatter 元数据规范

一个技能的核心是 SKILL.md，采用 YAML frontmatter + Markdown body：

---
name: coding-agent
description: 'Delegate coding tasks to Codex, Claude Code, or Pi agents...'
metadata:
  {
    "openclaw": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } },
  }
---

必需字段

• name：技能唯一标识（小写字母、连字符）
• description：简短描述（用于提示 LLM）

常用可选字段

• homepage：网站链接（macOS UI 显示）
• emoji：图标（macOS Skills UI）
• user-invocable：是否暴露为用户 slash 命令（默认 true）
• disable-model-invocation：是否从模型 prompt 中排除（仅用户手动触发）

metadata.openclaw 完整字段

这是 OpenClaw 特有的单行 JSON，用于加载时 gating（过滤）：

字段	类型	说明
always	boolean	强制启用，跳过其他 gates
os	string[]	限制平台：darwin、linux、win32
requires.bins	string[]	所有二进制必须在 PATH 中
requires.anyBins	string[]	至少一个二进制存在
requires.env	string[]	指定环境变量必须存在
requires.config	string[]	配置路径必须为真（如 browser.enabled）
primaryEnv	string	关联 skills.entries.<key>.apiKey 的 env 名
install	Installer[]	自动安装说明（支持 brew/node/go/download）

Gating 执行时机

在Agent 会话启动时，OpenClaw 会扫描所有技能，检查 requires.* 条件，仅加载符合条件的技能。条件不满足则技能不可见。

Installer 示例（gemini 技能）

metadata:
  {
    "openclaw": {
      "emoji": "♊️",
      "requires": { "bins": ["gemini"] },
      "install": [
        {
          "id": "brew",
          "kind": "brew",
          "formula": "gemini-cli",
          "bins": ["gemini"],
          "label": "Install Gemini CLI (brew)",
        },
      ],
    },
  }

macOS 上如果 gemini 不存在，Skills UI 会显示一个"Install Gemini CLI (brew)"按钮。

指令编写技巧

body 部分是给 LLM 的操作指南，关键原则：

• 告诉模型"做什么"，不是"如何思考"
• 明确工具选择（是用 read 还是 exec？）
• 使用 {baseDir} 引用技能目录的绝对路径

# Coding Agent Skill

When the user asks for code generation or review:
1. Use `bash` with `pty:true` to spawn the coding agent.
2. Prefer `codex exec` for one-shot tasks, `--full-auto` for auto-approval.
3. For PR reviews, always use a separate temp directory: `mktemp -d && git init`.

---

四、技能配置与权限控制

配置位置：~/.openclaw/openclaw.json

所有技能相关配置集中在 skills 键下：

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],  // 仅允许这些 bundled 技能
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
        config: { endpoint: "https://api.example.com", model: "v1" },
      },
      "sag": { enabled: false },  // 禁用 sag 技能
    },
  },
}

关键配置项

• allowBundled：白名单，仅列出内置技能可启用（防误启）
• load.extraDirs：额外技能目录（最低优先级）
• load.watch：监听技能文件夹变化，热重载（默认 true）
• entries.<skillKey>：每个技能的独立配置
  • enabled：显式禁用技能
  • env：注入环境变量（仅在变量不存在时）
  • apiKey：便捷方式，关联 primaryEnv
  • config：自定义参数，供技能指令引用

安全注意事项

• 第三方技能视为不可信代码：务必阅读 SKILL.md 和脚本文件
• Sandbox 隔离：高风险技能应配置 sandbox.docker 环境
• 密钥管理：避免在 env 中硬编码；使用 SecretRef：

  apiKey: { source: "env", provider: "default", id: "MY_API_KEY" }
  

• 环境变量注入范围：仅当前 Agent 会话，非全局

---

五、ClawHub：技能生态圈

什么是 ClawHub？

ClawHub 是 OpenClaw 的公共技能注册表（https://clawhub.ai），相当于 npm for Skills：

• 公开、版本化、可搜索
• 任何人都可以发布技能
• 社区驱动的评分与评论
• 自动审核（报告机制）

CLI 工作流

安装 CLI：

npm install -g clawhub

搜索技能

clawhub search "stock"
# 返回：my-stock-quote, stock-watcher, trading-signals

安装技能

# 默认安装到当前工作区的 ./skills
clawhub install my-stock-quote

# 指定版本
clawhub install my-stock-quote --version 1.2.0

# 强制覆盖
clawhub install my-stock-quote --force

更新技能

# 单个更新
clawhub update my-stock-quote

# 全部更新
clawhub update --all

发布技能

# 扫描目录并发布新版本
clawhub publish ./my-skill \
  --slug my-stock-quote \
  --name "My Stock Quote Skill" \
  --version 1.0.0 \
  --tags "stock,finance"

# 批量同步（扫描 + 发布未同步的）
clawhub sync --all

ClawHub 会记录已安装技能的 lock 文件：.clawhub/lock.json

发布规则与安全

• GitHub 账户需满一周（防止即时滥用）
• 报告机制：超过 3 个独特报告自动隐藏
• Moderator：可删除、取消删除、封禁用户
• Telemetry：CLAWHUB_DISABLE_TELEMETRY=1 可禁用统计

---

六、实战：手写一个自定义技能

让我们从头创建一个A 股股价查询技能，命名为 china-stock-quote。

Step 1：创建目录结构

# 进入工作区技能目录
cd ~/.openclaw/workspace/skills

# 新建技能文件夹
mkdir -p china-stock-quote
cd china-stock-quote

结构：

china-stock-quote/
├── SKILL.md          # 必需
├── requirements.txt  # Python 依赖（可选）
└── quote.py          # 实现脚本（可选）

Step 2：编写 SKILL.md

这是一个完整的 SKILL.md 示例：

---
name: china-stock-quote
description: 查询 A 股股票实时价格（支持上证、深证）
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["python3"], "env": ["STOCK_API_KEY"] },
      "primaryEnv": "STOCK_API_KEY",
      "emoji": "📈",
    },
  }
---

# 中国股票报价技能

用于查询 A 股（上证、深证）实时行情的技能。

## 何时使用

- 用户询问某只股票的价格（如"600519 现在多少钱"）
- 需要对比多只股票的表现
- 获取市场快照

## 如何调用

1. 确认参数：`symbol`（6位股票代码，如 `600519`）、`market`（可选，`sh`/`sz`）
2. 使用 `exec` 运行 `quote.py` 脚本
3. 解析 JSON 输出并返回给用户

## 示例

用户：查询 600519 的股价
代理：exec python3 quote.py --symbol 600519

输出 (JSON):
{
“symbol”: “600519”,
“name”: “贵州茅台”,
“price”: 1688.50,
“change”: “+12.3”,
“change_percent”: “+0.73%”,
“timestamp”: “2026-03-10 15:05:00”
}

## 实现说明

- 脚本 `quote.py` 使用 `yfinance` 库或公开 API（如 akshare）
- 如 API Key 需要，使用 `{baseDir}/.env` 或 `STOCK_API_KEY` 环境变量
- 若查询失败，返回错误信息并建议重试

Step 3：实现逻辑（quote.py）

创建 quote.py（建议放在技能目录）：

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

def query_stock(symbol: str) -> dict:
    # TODO: 接入真实 API（如 akshare、yfinance、tushare）
    # 这里返回 mock 数据用于演示
    return {
        "symbol": symbol,
        "name": "贵州茅台" if symbol == "600519" else "未知股票",
        "price": 1688.50,
        "change": "+12.3",
        "change_percent": "+0.73%",
        "timestamp": "2026-03-10 15:05:00"
    }

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--symbol", required=True, help="6位股票代码")
    args = parser.parse_args()
    result = query_stock(args.symbol)
    print(json.dumps(result, ensure_ascii=False))

创建 requirements.txt（如果需要依赖）：

yfinance>=0.2.0
# 或 akshare

Step 4：测试与调试

方法 A：新会话自动发现

# 打开新终端，启动 OpenClaw
openclaw agent --message "用 china-stock-quote 查询 600519 的股价"

方法 B：实时刷新（无需重启）

在当前 OpenClaw 会话中：

/skills refresh

然后直接对话。

查看技能是否加载

# 查看日志
openclaw logs | grep "china-stock-quote"

调试技巧

1. 如果技能未出现：检查 SKILL.md frontmatter 格式（YAML 缩进、JSON 单行）
2. 如果 requires 不满足：确认 python3 在 PATH、STOCK_API_KEY 已设置
3. 如果 agent 不会调用：简化指令，明确 exec python3 quote.py --symbol <code>

Step 5：发布到 ClawHub（可选）

完成并验证后，可以分享给社区：

# 从技能目录执行
cd ~/.openclaw/workspace/skills/china-stock-quote

# 发布
clawhub publish . \
  --slug china-stock-quote \
  --name "China Stock Quote" \
  --version 1.0.0 \
  --tags "stock,finance,china"

# 同步 lock
clawhub sync --all

之后其他用户只需 clawhub install china-stock-quote 即可使用。

---

七、深入：内置技能源码分析

coding-agent：执行外部编码代理

核心能力：调用 Codex、Claude Code、Pi 等编码助手。

SKILL.md 要点：

metadata:
  {
    "openclaw": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } },
  }

• anyBins：只要有一个编码代理 CLI 存在即可用
• 指令中强调 pty:true（对 Codex/Pi 必须）
• 提供了详细的 Background + process 模式示例

为什么 pty 必要？因为这些 CLI 是交互式终端程序，没有 PTY 会导致输出错乱或 hang。

典型调用：

bash pty:true workdir:~/project background:true \
  command:"codex --full-auto 'Add error handling to API'"

peekaboo：macOS UI 自动化

核心能力：控制鼠标、键盘、截图、应用管理（macOS only）。

SKILL.md 亮点：

metadata:
  {
    "openclaw": {
      "emoji": "👀",
      "os": ["darwin"],  # 仅 macOS
      "requires": { "bins": ["peekaboo"] },
      "install": [{ "id": "brew", "kind": "brew", "formula": "steipete/tap/peekaboo" }],
    },
  }

• os: ["darwin"]：其他平台自动屏蔽
• install 提供一键安装按钮（macOS Skills UI）
• 指令极详细，列举了所有子命令和参数

典型调用场景：

peekaboo see --app Safari --window-title "Login" --annotate
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari

gemini：Google Gemini CLI 集成

核心能力：调用 Gemini 模型进行生成。

SKILL.md 特色：

metadata:
  {
    "openclaw": {
      "emoji": "♊️",
      "requires": { "bins": ["gemini"] },
      "install": [{ "id": "brew", "kind": "brew", "formula": "gemini-cli" }],
    },
  }

• 没有 primaryEnv（Gemini CLI 本地认证）
• install 让非技术用户也能一键安装

---

八、进阶话题与最佳实践

Token 影响：技能列表的开销

OpenClaw 在系统 prompt 中注入所有eligible技能的 XML 列表，开销公式：

195 (基础) + Σ [97 + len(name) + len(description) + len(location)]

其中 97 是每个技能的固定 XML 标签开销。XML 转义（&、<、>）还会额外增加字符数。

优化建议：

• 精简 description（10-20 字足够）
• 使用 allowBundled 白名单，限制加载数量
• 对于不需要模型自动调用的技能，设 disable-model-invocation: true

技能热重载

默认 skills.load.watch: true，当 SKILL.md 改变时：

1. 文件系统 watcher 检测到变化
2. 刷新技能快照（新的 eligible 列表）
3. 下一条 agent turn 自动使用新技能

无需重启 OpenClaw。可以在开发中实时调试。

远程节点的技能分发

如果 Gateway 在 Linux 但连接了 macOS node，且 node 允许 system.run，那么：

• 仅限 node 上存在的 darwin-only 技能会被标记为 eligible
• 执行时自动路由到 node（通过 nodes.run）

这实现了一个跨平台技能池。

---

九、总结与展望

核心要点回顾

1. Skills 是 OpenClaw 的可插拔能力单元，通过 SKILL.md 定义，分层加载
2. 三层优先级：workspace > managed > bundled，同名覆盖无压力
3. Gating 机制（`requires.*）确保技能仅在条件满足时加载，提升稳定性**
4. ClawHub 生态让技能发现、安装、发布变得像 npm 一样简单
5. 创建自定义技能只需一个 SKILL.md（配合脚本），即可无限扩展

下一步行动

• 动手写一个技能：从简单的 echo 开始，逐步增加外部工具集成
• 探索 ClawHub：搜索你常用工具的现有技能，学习他人实现
• 贡献回社区：将通用技能发布到 ClawHub，建立技术影响力
• 安全第一：永远不要在生产环境运行未审计的第三方技能

---

十、参考资料

• OpenClaw 官方文档：Skills、ClawHub、Creating Skills
• ClawHub 网站：https://clawhub.ai
• AgentSkills 规范（上游）：https://agentskills.io

---

📎 附录：常见问题 FAQ

Q：技能不加载怎么办？
A：检查日志 openclaw logs，查看 requires gating 失败原因；确认 SKILL.md 格式正确（YAML + 单行 JSON）

Q：如何调试技能内的脚本？
A：在 exec 中直接运行脚本，加 --log-level debug；或使用 process action:log 查看背景输出

Q：技能可以访问网络吗？
A：默认 sandbox 禁止网络；需配置 tools.exec.sandbox.docker.network 或使用 host=gateway

Q：多技能冲突怎么办？
A：优先级规则已解决；同名 workspace 技能总是胜出，或重命名

---