Skills（技能系统）

概述

Skills 是 OpenClaw 的技能系统，基于 AgentSkills 规范，通过 SKILL.md 文件向 Agent 传授工具使用方法。每个 Skill 是一个目录，包含带 YAML frontmatter 的 Markdown 指令文件。OpenClaw 在加载时根据环境、配置和二进制文件存在性对 Skills 进行过滤。

加载来源与优先级

OpenClaw 从以下来源加载 Skills，高优先级覆盖低优先级（同名 skill 取最高来源）：

优先级	来源	路径
1（最高）	Workspace skills	`<workspace>/skills`
2	Project agent skills	`<workspace>/.agents/skills`
3	Personal agent skills	`~/.agents/skills`
4	Managed/local skills	`~/.openclaw/skills`
5	Bundled skills	随安装包附带
6（最低）	Extra skill folders	`skills.load.extraDirs`（配置项）

Codex CLI 的 $CODEX_HOME/skills 不在 OpenClaw 的 skill 根目录中。可用 openclaw migrate codex --dry-run 盘点，再用 openclaw migrate codex 交互式选择复制到当前 workspace。非交互模式用 --skill <name> 指定。

多 Agent 场景下的 Skill 可见性

作用域	路径	可见范围
Per-agent	`<workspace>/skills`	仅该 Agent
Project-agent	`<workspace>/.agents/skills`	仅该 workspace 的 Agent
Personal-agent	`~/.agents/skills`	本机所有 Agent
Shared managed/local	`~/.openclaw/skills`	本机所有 Agent
Shared extra dirs	`skills.load.extraDirs`	本机所有 Agent（最低优先级）

Agent 白名单（Allowlists）

Skill 位置/优先级 和 Skill 可见性 是两个独立控制维度。白名单决定某个 Agent 实际能使用哪些 Skills。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" },                    // 继承 defaults：github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换 defaults，只有 docs-search
      { id: "locked-down", skills: [] },   // 无任何 skill
    ],
  },
}

白名单规则：

省略 agents.defaults.skills → 默认不限制
省略 agents.list[].skills → 继承 agents.defaults.skills
agents.list[].skills: [] → 该 Agent 无任何 skill
非空的 agents.list[].skills 是该 Agent 的最终集合，不与 defaults 合并
白名单作用于：prompt 构建、slash command 发现、sandbox 同步、skill 快照

插件与 Skills

插件可在 openclaw.plugin.json 的 skills 字段中列出 skill 目录（相对插件根目录的路径），插件启用时这些 skills 自动加载。

插件 skill 目录合并到与 skills.load.extraDirs 相同的低优先级路径
同名的 bundled、managed、agent、workspace skill 会覆盖插件 skill
可通过插件 config entry 上的 metadata.openclaw.requires.config 进行门控

典型用例：browser 插件附带 browser-automation skill，提供多步浏览器控制指南。

Skill Workshop（实验性）

可选的实验性插件，能从 Agent 工作中观察到的可复用流程自动创建/更新 workspace skills。

默认禁用，需通过 plugins.entries.skill-workshop 显式启用
只写入 <workspace>/skills
支持 pending approval（推荐）或自动安全写入
对不安全的提案进行隔离（quarantine）
写入成功后自动刷新 skill 快照，无需重启 Gateway

适用场景：记录纠错（“下次验证 GIF 归属”）或来之不易的工作流（媒体 QA 检查清单）。

详见：plugin-skill-workshop

ClawHub（安装与同步）

ClawHub 是 OpenClaw 的公共 Skills 注册表。

操作	命令
安装 skill 到 workspace	`openclaw skills install <skill-slug>`
更新所有已安装 skills	`openclaw skills update --all`
同步（扫描 + 发布更新）	`clawhub sync --all`

openclaw skills install 安装到当前 workspace 的 skills/ 目录
clawhub CLI 也安装到 ./skills（或回退到配置的 OpenClaw workspace）
Skill 根目录支持一级分组：skills/<group>/<skill>/SKILL.md

私有 Archive 安装（非 ClawHub）：

Gateway 客户端可通过以下步骤安装私有 zip skill：

skills.upload.begin → skills.upload.chunk → skills.upload.commit
skills.install({ source: "upload", uploadId, slug, force?, sha256? })

此路径默认关闭，需在 openclaw.json 中设置 skills.install.allowUploadedArchives: true。

安全

警告：将第三方 skills 视为不可信代码，启用前务必阅读内容。对不可信输入和高风险工具优先使用沙箱运行。

Workspace 和 extra-dir 的 skill 发现只接受 realpath 在配置根目录内的 SKILL.md
Gateway 私有 archive 安装默认关闭；启用后与 ClawHub 安装共用相同的路径遍历、符号链接、force、回滚保护
Gateway 支持的 skill 依赖安装（skills.install、onboarding、Skills 设置 UI）在执行 installer metadata 前运行内置危险代码扫描器：critical 发现默认阻断，suspicious 仅警告
openclaw skills install <slug> 直接下载 ClawHub skill 文件夹到 workspace，不走 installer-metadata 路径
skills.entries.*.env 和 skills.entries.*.apiKey 注入到宿主进程（非沙箱），避免将 secrets 写入 prompt 或日志

SKILL.md 格式

最小格式

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

metadata 必须是单行 JSON 对象（parser 只支持单行 frontmatter key）
在指令中用 {baseDir} 引用 skill 文件夹路径

可选 frontmatter 字段

字段	类型	默认值	说明
`homepage`	string	—	macOS Skills UI 中显示为”Website”的 URL
`user-invocable`	boolean	`true`	是否暴露为用户 slash command
`disable-model-invocation`	boolean	`false`	`true` 时不注入 Agent 提示词，但仍可 slash 调用
`command-dispatch`	`"tool"`	—	slash command 直接路由到 tool，绕过模型
`command-tool`	string	—	`command-dispatch: tool` 时调用的 tool 名称
`command-arg-mode`	`"raw"`	`"raw"`	tool dispatch 时将原始 args 字符串转发给 tool

command-dispatch: tool 时，tool 收到的参数为：

{ "command": "<raw args>", "commandName": "<slash command>", "skillName": "<skill name>" }

Gating（加载时过滤）

OpenClaw 在加载时通过 metadata（单行 JSON）过滤 skills：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

`metadata.openclaw` 字段说明

字段	类型	说明
`always`	boolean	`true` 时始终包含，跳过其他门控
`emoji`	string	macOS Skills UI 中显示的 emoji
`homepage`	string	macOS Skills UI 中显示的 URL
`os`	`"darwin" \| "linux" \| "win32"`	平台过滤，不在列表中的平台不加载
`requires.bins`	string[]	PATH 上必须存在的所有二进制
`requires.anyBins`	string[]	PATH 上至少存在一个二进制
`requires.env`	string[]	必须存在的环境变量（或在 config 中提供）
`requires.config`	string[]	`openclaw.json` 中必须为 truthy 的路径列表
`primaryEnv`	string	与 `skills.entries.<name>.apiKey` 关联的环境变量名
`install`	object[]	macOS Skills UI 使用的安装器规格（brew/node/go/uv/download）

无 metadata.openclaw 时，skill 始终 eligible（除非在 config 中禁用或被 skills.allowBundled 阻止）。

兼容性：旧版 metadata.clawdbot 在无 metadata.openclaw 时仍被接受。新 skill 应使用 metadata.openclaw。

沙箱注意事项

requires.bins 在宿主机加载时检查
若 Agent 在沙箱中运行，二进制也必须存在于容器内
通过 agents.defaults.sandbox.docker.setupCommand 安装（容器创建后运行一次）
包安装需要：网络出口、可写根文件系统、容器内 root 用户

Installer 规格示例

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Installer 选择规则：

多个 installer 时，Gateway 选择单个首选项：有 brew 时优先 brew，否则 node
全部为 download 类型时，列出所有条目供选择
可用 os: ["darwin"|"linux"|"win32"] 按平台过滤
Node 安装遵循 skills.install.nodeManager（默认 npm；可选 npm/pnpm/yarn/bun）
Gateway 偏好顺序：Homebrew（skills.install.preferBrew 启用且 brew 存在）→ uv → 配置的 node manager → go → download

各类型细节：

Go 安装：若 go 缺失且有 brew，Gateway 先通过 Homebrew 安装 Go，并将 GOBIN 设为 Homebrew 的 bin
Download 安装：url（必填）、archive（tar.gz/tar.bz2/zip）、extract（检测到 archive 时默认自动）、stripComponents、targetDir（默认 ~/.openclaw/tools/<skillKey>）

Config 覆盖（skills.entries）

在 ~/.openclaw/openclaw.json 中通过 skills.entries 对 bundled 和 managed skills 进行开关和环境变量配置：

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

字段	类型	说明
`enabled`	boolean	`false` 禁用 skill（即使是 bundled 或已安装的）
`apiKey`	string \| SecretRef	为声明了 `primaryEnv` 的 skill 提供 API key
`env`	Record<string, string>	仅在变量未在进程中设置时注入
`config`	object	自定义 per-skill 字段的容器
`allowBundled`	string[]	仅限 bundled skills 的白名单；设置后只有列表中的 bundled skills eligible

skill 名含连字符时需加引号（JSON5 支持带引号的 key）
默认用 skill name 作为 config key；若 skill 定义了 metadata.openclaw.skillKey，则用该 key

注意：OpenClaw 内置图像生成/编辑使用 image_generate tool + agents.defaults.imageGenerationModel，而非 bundled skill。Skill 示例适用于自定义或第三方工作流。

环境注入

Agent run 启动时，OpenClaw 执行：

读取 skill metadata
将 skills.entries.<key>.env 和 skills.entries.<key>.apiKey 应用到 process.env
用 eligible skills 构建 system prompt
run 结束后恢复原始环境

环境注入作用域为单次 agent run，不影响全局 shell 环境。

claude-cli backend 特殊处理： 对于 bundled claude-cli backend，OpenClaw 还会将 eligible skill 快照物化为临时 Claude Code plugin，通过 --plugin-dir 传入。Claude Code 可使用其原生 skill resolver，而 OpenClaw 仍掌控优先级、per-agent 白名单、gating 和 skills.entries.* 的 env/API key 注入。其他 CLI backend 仅使用 prompt catalog。

快照与热重载

OpenClaw 在 session 启动时快照 eligible skills，同一 session 的后续 turn 复用该列表。Skills 或 config 的变更在下一个新 session 生效。

两种 mid-session 刷新场景：

Skills watcher 启用时
新的 eligible 远程节点出现时

刷新后的列表在下一个 agent turn 生效（热重载）。若该 session 的 agent skill 白名单发生变化，OpenClaw 也会刷新快照以保持一致。

Skills Watcher 配置

{
  skills: {
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

allowSymlinkTargets：用于 sibling-repo 布局中的符号链接（如 ~/.agents/skills/manager -> ~/Projects/manager/skills），匹配 realpath 后解析，列表应保持精简

远程 macOS 节点（Linux Gateway）

若 Gateway 运行在 Linux 但连接了 macOS 节点（system.run 已允许），OpenClaw 可在该节点上存在所需二进制时将 macOS-only skills 视为 eligible。Agent 应通过 exec tool 的 host=node 执行这些 skills。

依赖节点上报命令支持情况，以及通过 system.which 或 system.run 进行 bin 探测
离线节点不会使 remote-only skills 可见
节点停止响应 bin 探测时，OpenClaw 清除其缓存的 bin 匹配，Agent 不再看到无法运行的 skills

Token 开销

Skills eligible 时，OpenClaw 通过 formatSkillsForPrompt 将紧凑 XML 列表注入 system prompt，开销确定性可计算：

基础开销（≥1 个 skill 时）：195 字符
每个 skill：97 字符 + XML 转义后的 <name>、<description>、<location> 长度

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

XML 转义会将 & < > " ' 扩展为实体（&、< 等），增加长度。粗略估算（OpenAI tokenizer）：约 4 字符/token，即 97 字符 ≈ 24 token/skill（不含字段内容）。

Managed Skills 生命周期

Bundled skills：随安装包（npm 包或 OpenClaw.app）附带的基础 skill 集
~/.openclaw/skills：本地覆盖目录，用于 pin 或 patch skill 而不修改 bundled 副本
Workspace skills：用户自有，同名时覆盖 bundled 和 managed

Wiki AI

目录

Skills（技能系统）

概述

加载来源与优先级

多 Agent 场景下的 Skill 可见性

Agent 白名单（Allowlists）

插件与 Skills

Skill Workshop（实验性）

ClawHub（安装与同步）

安全

SKILL.md 格式

最小格式

可选 frontmatter 字段

Gating（加载时过滤）

`metadata.openclaw` 字段说明

沙箱注意事项

Installer 规格示例

Config 覆盖（skills.entries）

环境注入

快照与热重载

Skills Watcher 配置

远程 macOS 节点（Linux Gateway）

Token 开销

Managed Skills 生命周期

相关页面

关系图谱

目录

反向链接

Wiki AI

目录

Skills（技能系统）

概述

加载来源与优先级

多 Agent 场景下的 Skill 可见性

Agent 白名单（Allowlists）

插件与 Skills

Skill Workshop（实验性）

ClawHub（安装与同步）

安全

SKILL.md 格式

最小格式

可选 frontmatter 字段

Gating（加载时过滤）

metadata.openclaw 字段说明

沙箱注意事项

Installer 规格示例

Config 覆盖（skills.entries）

环境注入

快照与热重载

Skills Watcher 配置

远程 macOS 节点（Linux Gateway）

Token 开销

Managed Skills 生命周期

相关页面

关系图谱

目录

反向链接

`metadata.openclaw` 字段说明