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

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

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

这时，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 会话的工作区目录：

 
   
    
     
       /skills/ 
     

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

Precedence 规则（优先级）

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

{ skills: {

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

} }

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（过滤）：

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. ：每个技能的独立配置
  • enabled：显式禁用技能
  • env：注入环境变量（仅在变量不存在时）
  • apiKey：便捷方式，关联 primaryEnv
  • config：自定义参数，供技能指令引用

安全注意事项

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

  apiKey: { source: “env”, provider: “default”, id: “MY_API_KEY” } 

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

什么是 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 股（上证、深证）实时行情的技能。

何时使用

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

如何调用

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

示例

实现说明

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

  Step 3：实现逻辑（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  

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 查询 的股价” 

方法 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

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

metadata: {

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

bash pty:true workdir:~/project background:true  command:“codex –full-auto ‘Add error handling to API’” 

metadata: {

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

peekaboo see –app Safari –window-title “Login” –annotate peekaboo click –on B3 –app Safari peekaboo type “” –app Safari 

metadata: {

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

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