本页介绍 OpenClaw 的 Skills 技能系统。技能是告诉代理"如何使用工具"的 SKILL.md 文件，从六个位置加载（workspace > .agents/skills > ~/.agents/skills > managed > bundled > extraDirs）。支持 per-agent allowlists 控制不同 agent 可见哪些技能，通过 metadata.openclaw 门控过滤（requires.bins/env/config），并可在 ~/.openclaw/openclaw.json 中覆盖配置。

Skills（OpenClaw 技能系统）

OpenClaw 使用 AgentSkills 兼容的技能文件夹来教 Agent 如何使用工具。每个技能是一个包含 SKILL.md 文件（含 YAML frontmatter 和说明）的目录。OpenClaw 加载内置技能以及可选的本地覆盖，并在加载时根据环境、配置和可执行文件是否存在对其进行过滤。

加载位置与优先级

OpenClaw 从以下六个位置加载技能：

额外技能文件夹：通过 skills.load.extraDirs 配置
内置技能：随安装内置（npm 包或 OpenClaw.app）
Managed/本地技能：~/.openclaw/skills
个人 Agent 技能：~/.agents/skills
项目 Agent 技能：<workspace>/.agents/skills
工作区技能：<workspace>/skills

如果技能名称冲突，优先级为：

<workspace>/skills（最高）→ <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 内置技能 → skills.load.extraDirs（最低）

单 Agent vs 共享技能

在多 Agent 部署中，每个 Agent 有自己的工作区，因此：

单 Agent 技能存放在该 Agent 的 <workspace>/skills，只对该 Agent 生效。
项目 Agent 技能存放在 <workspace>/.agents/skills，在该工作区的普通 skills/ 文件夹之前应用。
个人 Agent 技能存放在 ~/.agents/skills，跨该机器所有工作区应用。
共享技能存放在 ~/.openclaw/skills（managed/本地），对同一台机器上的所有 Agent可见。
共享文件夹也可通过 skills.load.extraDirs 添加（优先级最低），用于多个 Agent 共用一套技能包。

当同一技能名在多处存在时，遵循常规优先级：工作区优先，然后项目 agent，然后个人 agent，然后 managed/本地，最后内置，最低为 extraDirs。

Per-Agent Allowlists（per-agent 技能白名单）

技能位置和技能可见性是独立的控制：

位置/优先级决定同名技能哪个版本胜出。
Agent allowlists 决定可见的技能中该 agent 实际可以使用哪些。

使用 agents.defaults.skills 设置共享基准，然后用 agents.list[].skills 按 agent 覆盖：

json5

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // 继承 github、weather
      { id: "docs", skills: ["docs-search"] }, // 替换默认值
      { id: "locked-down", skills: [] }, // 无技能
    ],
  },
}

规则：

省略 agents.defaults.skills 则默认不限制技能。
省略 agents.list[].skills 则继承 agents.defaults.skills。
设置 agents.list[].skills: [] 则该 agent 无技能。
非空的 agents.list[].skills 列表是该 agent 的最终集合；不与默认值合并。

OpenClaw 将有效的 agent 技能集应用于提示词构建、技能斜杠命令发现、沙箱同步和技能快照。

插件与技能

插件可以在 openclaw.plugin.json 的 skills 目录中（相对于插件根目录的路径）携带自己的技能。插件启用时技能随之加载，合并到与 skills.load.extraDirs 相同的低优先级路径中，因此同名的内置、managed、agent 或工作区技能会覆盖它们。你可以通过插件配置条目的 metadata.openclaw.requires.config 对其进行门控。参见 Plugins 了解发现/配置，以及 Tools 了解这些技能教导的工具接口。

ClawHub（安装 + 同步）

ClawHub 是 OpenClaw 的公共技能注册中心，网址 https://clawhub.ai。使用原生 openclaw skills 命令发现/安装/更新技能，或在需要发布/同步工作流时使用单独的 clawhub CLI。完整指南：ClawHub。

常见流程：

将技能安装到工作区：
- openclaw skills install <skill-slug>
更新所有已安装技能：
- openclaw skills update --all
同步（扫描 + 发布更新）：
- clawhub sync --all

openclaw skills install 会将技能安装到当前工作区的 skills/ 目录。单独的 clawhub CLI 也安装到当前工作目录下的 ./skills（或回退到配置的 OpenClaw 工作区）。OpenClaw 在下次会话时将其识别为 <workspace>/skills。

安全注意事项

将第三方技能视为不可信代码。启用前请先阅读其内容。
对于不可信输入和风险工具，建议使用沙箱运行。参见 Sandboxing。
工作区和额外目录的技能发现只接受技能根目录和 SKILL.md 文件，其解析后的真实路径必须在配置的根目录内。
Gateway 支持的技能依赖安装（skills.install、onboarding 和 Skills 设置 UI）在执行安装器元数据前会运行内置危险代码扫描器。critical 发现默认阻止，除非调用方显式设置危险覆盖；suspicious 发现仍仅警告。
openclaw skills install <slug> 不同：它从 ClawHub 下载技能文件夹到工作区，不走上面的安装器元数据路径。
skills.entries.*.env 和 skills.entries.*.apiKey 会将密钥注入到该 Agent 轮次的宿主进程（不是沙箱）。请勿在提示词和日志中暴露密钥。
更广泛的威胁模型和清单参见 Security。

格式（AgentSkills + Pi 兼容）

SKILL.md 至少需要包含：

markdown

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

注意：

我们遵循 AgentSkills 规范的布局/意图。
内嵌 Agent 使用的解析器只支持单行 frontmatter key。
metadata 应为单行 JSON 对象。
在说明中用 {baseDir} 引用技能文件夹路径。
可选 frontmatter key：
- homepage — URL，显示在 macOS Skills UI 的"Website"中（也可通过 metadata.openclaw.homepage 支持）。
- user-invocable — true|false（默认：true）。为 true 时，技能作为用户斜杠命令暴露。
- disable-model-invocation — true|false（默认：false）。为 true 时，技能从模型提示词中排除（仍可通过用户调用访问）。
- command-dispatch — tool（可选）。设置为 tool 时，斜杠命令绕过模型，直接分发到工具。
- command-tool — 设置 command-dispatch: tool 时调用的工具名称。
- command-arg-mode — raw（默认）。用于工具分发时，将原始参数字符串转发给工具（不做核心解析）。
  工具的调用参数为： { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

门控（加载时过滤）

OpenClaw 使用 metadata（单行 JSON）在加载时过滤技能：

markdown

---
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: true — 始终包含该技能（跳过其他门控）。
emoji — macOS Skills UI 使用的可选 Emoji。
homepage — macOS Skills UI 中显示为"Website"的可选 URL。
os — 可选的平台列表（darwin、linux、win32）。设置后技能只在对应平台生效。
requires.bins — 列表；每个都必须在 PATH 中存在。
requires.anyBins — 列表；至少一个必须在 PATH 中存在。
requires.env — 列表；环境变量必须存在或在配置中提供。
requires.config — openclaw.json 路径列表，每个必须为 truthy。
primaryEnv — 与 skills.entries.<name>.apiKey 关联的环境变量名。
install — macOS Skills UI 使用的可选安装器规格数组（brew/node/go/uv/download）。

关于沙箱的注意事项：

requires.bins 在技能加载时检查宿主环境。
如果 Agent 处于沙箱中，该二进制文件也必须存在于容器内部。通过 agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装它。 setupCommand 在容器创建后执行一次。

安装器示例：

markdown

---
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)",
            },
          ],
      },
  }
---

安装器注意事项：

如果列出了多个安装器，Gateway 会选择单个首选选项。当 skills.install.preferBrew 启用且 brew 可用时优先 brew，然后 uv，然后配置的 node manager，最后 go 或 download。
如果所有安装器都是 download，OpenClaw 会列出所有下载选项供选择。
安装器规格可以包含 os: ["darwin"|"linux"|"win32"] 按平台过滤选项。
Node 安装使用 skills.install.nodeManager（默认：npm；选项：npm/pnpm/yarn/bun）。这只影响技能安装；Gateway 运行时仍应使用 Node。
Go 安装：如果缺少 go 且 brew 可用，Gateway 会先通过 Homebrew 安装 Go，并在可能时将 GOBIN 设置为 Homebrew 的 bin。
Download 安装：url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（检测到压缩包时默认自动）、stripComponents、targetDir（默认：~/.openclaw/tools/<skillKey>）。

如果没有 metadata.openclaw，技能始终符合条件（除非在配置中禁用或被内置技能的 skills.allowBundled 阻止）。

配置覆盖（`~/.openclaw/openclaw.json`）

内置/managed 技能可以被切换并提供环境变量值：

json5

{
  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 },
    },
  },
}

注意：如果技能名包含连字符，请将 key 加引号（JSON5 允许带引号的 key）。

配置 key 默认与技能名称匹配。如果技能定义了 metadata.openclaw.skillKey，在 skills.entries 下使用该 key。

规则：

enabled: false 禁用技能，即使它是内置/已安装的。
env：只有当变量尚未在进程中设置时才注入。
apiKey：声明了 metadata.openclaw.primaryEnv 的技能的便捷配置。支持纯文本字符串或 SecretRef 对象（{ source, provider, id }）。
config：自定义每技能字段的可选容器；自定义 key 必须放在这里。
allowBundled：仅针对内置技能的可选白名单。设置后只有白名单中的内置技能符合条件（managed/工作区技能不受影响）。

环境注入（每次 Agent 运行）

当 Agent 运行开始时，OpenClaw：

读取技能元数据。
将所有 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 应用到 process.env。
使用符合条件的技能构建系统提示词。
运行结束后恢复原始环境。

这只作用于该 Agent 运行，不是全局 shell 环境。

会话快照（性能优化）

OpenClaw 在会话开始时快照符合条件的技能列表，并在同一会话的后续轮次中复用该列表。技能或配置的变更在下一个新会话时生效。

启用技能监视器或有新的符合条件的远程节点出现时，技能也可以在会话中途刷新（热重载）：刷新后的列表在下一次 Agent 轮次时生效。

如果该会话的有效 agent 技能 allowlist 发生变化，OpenClaw 会刷新快照使可见技能与当前 agent 保持一致。

远程 macOS 节点（Linux Gateway）

如果 Gateway 运行在 Linux 上，但连接了一个允许 system.run 的 macOS 节点（Exec 审批安全性未设置为 deny），当必要的二进制文件存在于该节点上时，OpenClaw 可以将 macOS 专属技能视为符合条件。Agent 应通过 exec 工具（host=node）来执行这些技能。

这依赖于节点上报其命令支持和通过 system.run 进行的 bin 探测。如果 macOS 节点后来下线，技能仍然可见；调用可能会失败，直到节点重新连接。

技能监视器（自动刷新）

默认情况下，OpenClaw 监视技能文件夹，当 SKILL.md 文件发生变化时更新技能快照。在 skills.load 下配置：

json5

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token 影响（技能列表）

当技能符合条件时，OpenClaw 会将可用技能的紧凑 XML 列表注入系统提示词。成本是确定性的：

基础开销（只有 ≥1 个技能时）：195 字符。
每个技能：97 字符 + <name>、<description> 和 <location> 的 XML 转义值的长度。

公式（字符数）：

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

注意：

XML 转义会将 & < > " ' 展开为实体（&、< 等），增加长度。
Token 计数因模型 tokenizer 而异。粗略的 OpenAI 式估算约为 4 字符/token，即每个技能约 24 token，加上你实际的字段长度。

Managed 技能生命周期

OpenClaw 将一套基础技能作为内置技能随安装包一起提供（npm 包或 OpenClaw.app）。~/.openclaw/skills 用于本地覆盖（例如，在不修改内置副本的情况下固定/补丁某个技能）。工作区技能由用户拥有，在名称冲突时覆盖前两者。

配置参考

完整配置 schema 参见 Skills config。

寻找更多技能？

浏览 https://clawhub.ai。

常见问题

Q: ~/.agents/skills 和 <workspace>/skills 有什么区别？

A: <workspace>/skills 是工作区级技能，只对使用该工作区的 agent 生效，优先级最高。~/.agents/skills 是个人 agent 技能，跨该机器所有工作区的 agent 都能看到，优先级介于工作区和 managed（~/.openclaw/skills）之间。这是 2025 年新增的两级 agent skills 路径，旧版文档只有三层结构。

Q: per-agent allowlists 和技能门控（metadata.openclaw.requires）有什么区别？

A: 技能门控（门控）是技能本身声明的加载条件，基于环境（bin 是否存在、环境变量是否设置、配置项是否为 truthy）在加载时过滤，与 agent 无关。per-agent allowlists 是管理员通过 agents.list[].skills 配置的可见性控制，在加载后再决定哪个 agent 可以使用哪些已加载的技能。两者叠加：技能必须先通过门控加载，才有可能出现在 agent 的可见列表中。

Q: 如果同一技能名在工作区和 ~/.openclaw/skills 都有，哪个生效？

A: 工作区技能（<workspace>/skills）优先级最高，始终覆盖 managed 技能（~/.openclaw/skills）中的同名版本。这是设计意图：工作区允许你针对特定项目固定或自定义某个技能，而不影响其他项目使用 managed 版本。

Skills（OpenClaw 技能系统） ​

加载位置与优先级 ​

单 Agent vs 共享技能 ​

Per-Agent Allowlists（per-agent 技能白名单） ​

插件与技能 ​

ClawHub（安装 + 同步） ​

安全注意事项 ​

格式（AgentSkills + Pi 兼容） ​

门控（加载时过滤） ​

配置覆盖（~/.openclaw/openclaw.json） ​

环境注入（每次 Agent 运行） ​

会话快照（性能优化） ​

远程 macOS 节点（Linux Gateway） ​

技能监视器（自动刷新） ​

Token 影响（技能列表） ​

Managed 技能生命周期 ​

配置参考 ​

寻找更多技能？ ​

相关链接 ​

常见问题 ​

Skills（OpenClaw 技能系统）

加载位置与优先级

单 Agent vs 共享技能

Per-Agent Allowlists（per-agent 技能白名单）

插件与技能

ClawHub（安装 + 同步）

安全注意事项

格式（AgentSkills + Pi 兼容）

门控（加载时过滤）

配置覆盖（`~/.openclaw/openclaw.json`）

环境注入（每次 Agent 运行）

会话快照（性能优化）

远程 macOS 节点（Linux Gateway）

技能监视器（自动刷新）

Token 影响（技能列表）

Managed 技能生命周期

配置参考

寻找更多技能？

相关链接

常见问题