Skip to main content
技能是 Markdown 指令文件，用于教会代理如何以及何时使用 工具。每个技能都位于一个目录中，该目录包含一个带有 YAML frontmatter 和 Markdown 正文的 SKILL.md 文件。OpenClaw 会加载捆绑技能以及任何本地 覆盖，并根据环境、配置和 二进制文件是否存在在加载时进行过滤。

创建技能

从零开始构建并测试一个自定义技能。

技能工作坊

审阅并批准代理起草的技能提案。

技能配置

完整的 skills.* 配置模式和代理允许列表。

ClawHub

浏览并安装社区技能。

​
加载顺序

OpenClaw 从以下来源加载，优先级从高到低。当同名 技能出现在多个位置时，优先级更高的来源获胜。
优先级来源路径
1 — 最高工作区技能<workspace>/skills
2项目代理技能<workspace>/.agents/skills
3个人代理技能~/.agents/skills
4托管 / 本地技能~/.openclaw/skills
5捆绑技能随安装包一起提供
6 — 最低额外目录skills.load.extraDirs + 插件技能
技能根目录支持分组布局。只要 SKILL.md 出现在任一已配置根目录下，OpenClaw 就会发现该技能： 
<workspace>/skills/research/SKILL.md          ✓ 发现为 "research"
<workspace>/skills/personal/research/SKILL.md ✓ 也发现为 "research"
文件夹路径仅用于组织。技能名称、斜杠命令和 允许列表键都来自 name frontmatter 字段（或在 缺少 name 时使用目录名）。
Codex CLI 的原生 $CODEX_HOME/skills 目录不是 OpenClaw 的 技能根目录。请使用 openclaw migrate plan codex 清点这些技能，然后用 openclaw migrate codex 将它们复制到你的 OpenClaw 工作区。
对于非交互式运行，请对要复制的精确技能重复使用 --skill <name>。 在多代理设置中，每个代理都有自己的工作区。请使用与你期望可见性匹配的路径：
范围路径可见对象
每代理<workspace>/skills仅该代理
项目代理<workspace>/.agents/skills仅该工作区的代理
个人代理~/.agents/skills此机器上的所有代理
共享托管~/.openclaw/skills此机器上的所有代理
额外目录skills.load.extraDirs此机器上的所有代理

​
代理允许列表

技能的位置（优先级）和技能的可见性（哪个代理可以使用它）是两个独立的控制项。使用允许列表来限制某个代理能看到哪些技能，无论它们从哪里加载。 
{
  agents: {
    defaults: {
      skills: ["github", "weather"], // 共享基线
    },
    list: [
      { id: "writer" }, // 继承 github, weather
      { id: "docs", skills: ["docs-search"] }, // 完全替换 defaults
      { id: "locked-down", skills: [] }, // 没有技能
    ],
  },
}
  • 省略 agents.defaults.skills 会让默认情况下所有技能都不受限制。
  • 省略 agents.list[].skills 会继承 agents.defaults.skills。
  • 将 agents.list[].skills: [] 设置为对该代理不暴露任何技能。
  • 非空的 agents.list[].skills 列表是最终集合——它不会 与 defaults 合并。
  • 生效的允许列表适用于提示词构建、斜杠命令 发现、沙箱同步以及技能快照。

​
插件和技能

插件可以通过在 openclaw.plugin.json 中列出 skills 目录来提供自己的技能（路径相对于插件根目录）。当插件启用时，会加载插件技能——例如，浏览器插件提供了一个用于多步骤浏览器控制的 browser-automation 技能。 插件技能目录与 skills.load.extraDirs 处于相同的低优先级层级进行合并，因此同名的捆绑、托管、代理或工作区技能会覆盖它们。通过插件配置项上的 metadata.openclaw.requires.config 对它们进行门控。 有关完整插件系统，请参见 插件 和 工具。

​
技能工作坊

技能工作坊 是代理与你当前技能文件之间的一个提案队列。当代理发现可复用的工作时，它会起草一个提案，而不是直接写入 SKILL.md。你需要在任何内容变更之前进行审阅和批准。 
openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>
有关完整生命周期、CLI 参考和配置，请参见 技能工作坊。

​
从 ClawHub 安装

ClawHub 是公开的技能注册中心。使用 openclaw skills 命令进行安装和更新，或使用 clawhub CLI 进行 发布和同步。
操作命令
将技能安装到工作区openclaw skills install <slug>
从 Git 仓库安装openclaw skills install git:owner/repo@ref
安装本地技能目录openclaw skills install ./path/to/skill --as my-tool
为所有本地代理安装openclaw skills install <slug> --global
更新所有工作区技能openclaw skills update --all
更新共享托管技能openclaw skills update <slug> --global
更新所有共享托管技能openclaw skills update --all --global
验证技能的信任包络openclaw skills verify <slug>
打印生成的 Skill Cardopenclaw skills verify <slug> --card
通过 ClawHub CLI 发布 / 同步clawhub sync --all
openclaw skills install 默认将技能安装到当前工作区的 skills/ 目录。添加 --global 可安装到共享的 ~/.openclaw/skills 目录，除非代理允许列表将其限制，否则所有本地代理都可见。Git 和本地安装要求源根目录下存在 SKILL.md。slug 首先来自 SKILL.md frontmatter 中有效的 name，然后回退到 目录或仓库名称。使用 --as <slug> 可覆盖。 openclaw skills update 仅跟踪 ClawHub 安装——要刷新 Git 或 本地来源，需要重新安装。
openclaw skills verify <slug> 会向 ClawHub 请求该技能的 clawhub.skill.verify.v1 信任包络。已安装的 ClawHub 技能会根据 .clawhub/origin.json 中记录的版本和注册中心进行验证。ClawHub 技能页面在安装前会显示最新的安全扫描状态， 详细页面包含 VirusTotal、ClawScan 和静态分析。当天然 命令将 ClawHub 标记为验证失败时，会以非零状态退出。发布者可通过 ClawHub 仪表板或 clawhub skill rescan <slug> 处理误报。
需要非 ClawHub 分发的网关客户端可以使用 skills.upload.begin、skills.upload.chunk 和 skills.upload.commit 分段上传 zip 技能归档，然后使用 skills.install({ source: "upload", ... }) 安装。此路径 默认关闭，并且需要在 openclaw.json 中设置 skills.install.allowUploadedArchives: true。正常的 ClawHub 安装不需要该设置。

​
安全

将第三方技能视为不受信任的代码。在启用前先阅读它们。 对不受信任的输入和高风险工具优先使用沙箱运行。有关代理侧控制，请参见 沙箱化。
工作区、项目代理和额外目录的技能发现只接受其解析后的真实路径仍位于配置根目录内的技能根目录，除非 skills.load.allowSymlinkTargets 明确信任某个目标根目录。 托管的 ~/.openclaw/skills 和个人的 ~/.agents/skills 可以包含 通过符号链接指向的技能文件夹，但每个 SKILL.md 的真实路径仍必须位于其解析后的技能目录内。
配置 security.installPolicy 可在技能安装继续之前运行一个受信任的本地策略命令。该策略会接收元数据和暂存的源路径，适用于 ClawHub、上传、Git、本地、更新和 依赖安装器路径，并且在命令无法返回有效决策时会默认失败关闭。
skills.entries.*.env 和 skills.entries.*.apiKey 会将密钥注入到该代理轮次的宿主进程中——不会注入到沙箱中。请将密钥排除在提示词和日志之外。
有关更广泛的威胁模型和安全检查清单，请参见 安全。

​
SKILL.md 格式

每个 skill 的 frontmatter 至少需要 name 和 description： 
---
name: image-lab
description: 通过基于提供商的图像工作流生成或编辑图像
---

当用户请求生成图像时，使用 `image_generate` 工具...
OpenClaw 遵循 AgentSkills 规范。frontmatter 解析器仅支持 单行键 — metadata 必须是一个单行 JSON 对象。使用正文中的 {baseDir} 来引用 skill 文件夹路径。

​
可选 frontmatter 键

​
homepage
string
在 macOS Skills UI 中显示为“Website”的 URL。也支持通过 metadata.openclaw.homepage 配置。
​
user-invocable
boolean
default:"true"
当为 true 时，该 skill 会作为用户可调用的斜杠命令暴露出来。
​
disable-model-invocation
boolean
default:"false"
当为 true 时，OpenClaw 会将该 skill 的说明排除在 agent 的常规提示词之外。 该 skill 仍然可以作为斜杠命令使用，只要 user-invocable 也为 true。
​
command-dispatch
"tool"
当设置为 tool 时，斜杠命令会绕过模型，直接分发到已注册的工具。
​
command-tool
string
当设置了 command-dispatch: tool 时要调用的工具名称。
​
command-arg-mode
"raw"
default:"raw"
对于工具分发，会将原始参数字符串原样传递给工具，不进行核心解析。工具接收 { command: "<原始参数>", commandName: "<斜杠命令>", skillName: "<skill 名称>" }。

​
门控

OpenClaw 在加载时使用 metadata.openclaw（frontmatter 中的单行 JSON）对 skills 进行过滤。没有 metadata.openclaw 块的 skill 默认始终符合条件，除非被显式禁用。 
---
name: image-lab
description: 通过基于提供商的图像工作流生成或编辑图像
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---
​
always
boolean
当为 true 时，始终包含该 skill，并跳过所有其他门控。
​
emoji
string
在 macOS Skills UI 中显示的可选 emoji。
​
homepage
string
在 macOS Skills UI 中显示为“Website”的可选 URL。
​
os
"darwin" | "linux" | "win32"
平台过滤器。设置后，该 skill 仅在列出的操作系统上符合条件。
​
requires.bins
string[]
每个二进制文件都必须存在于 PATH 中。
​
requires.anyBins
string[]
至少有一个二进制文件必须存在于 PATH 中。
​
requires.env
string[]
每个环境变量都必须存在于进程中，或通过配置提供。
​
requires.config
string[]
每个 openclaw.json 路径都必须为真值。
​
primaryEnv
string
与 skills.entries.<name>.apiKey 关联的环境变量名称。
​
install
object[]
macOS Skills UI 使用的可选安装器规格（brew / node / go / uv / download）。
当 metadata.openclaw 不存在时，仍然接受旧版 metadata.clawdbot 块，因此较早安装的 skills 仍可保留它们的依赖门控和安装提示。新 skills 应使用 metadata.openclaw。

​
安装器规格

安装器规格告诉 macOS Skills UI 如何安装依赖： 
---
name: gemini
description: 使用 Gemini CLI 提供编码辅助和 Google 搜索查询。
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "安装 Gemini CLI（brew）",
            },
          ],
      },
  }
---
  • 当列出多个安装器时，gateway 会选择一个首选项（可用时优先 brew，否则 node）。
  • 如果所有安装器都是 download，OpenClaw 会列出每个条目，以便你查看所有可用制品。
  • 规格可以包含 os: ["darwin"|"linux"|"win32"] 来按平台过滤。
  • Node 安装会遵循 openclaw.json 中的 skills.install.nodeManager（默认：npm；可选：npm / pnpm / yarn / bun）。这只影响 skill 安装；Gateway 运行时仍应使用 Node。
  • Gateway 安装器优先级：Homebrew → uv → 已配置的 node manager → go → download。
  • Homebrew： OpenClaw 不会自动安装 Homebrew，也不会把 brew 配方转换为系统包管理命令。在没有 brew 的 Linux 容器中，纯 brew 安装器会被隐藏；请使用自定义镜像或手动安装依赖。
  • Go： 如果缺少 go 且可用 brew，gateway 会先通过 Homebrew 安装 Go，并将 GOBIN 设置为 Homebrew 的 bin 目录。
  • Download： url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（默认：检测到压缩包时自动解压）、stripComponents、targetDir（默认：~/.openclaw/tools/<skillKey>）。
requires.bins 会在 skill 加载时于主机上检查。如果 agent 在沙箱中运行，该二进制文件也必须存在于容器内。请通过 agents.defaults.sandbox.docker.setupCommand 或自定义镜像安装它。setupCommand 会在容器创建后运行一次，并且需要沙箱具备网络外连、可写的根文件系统以及 root 用户。

​
配置覆盖

在 ~/.openclaw/openclaw.json 的 skills.entries 下切换并配置内置或已管理的 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，即使它是内置或已安装的。coding-agent 内置 skill 默认不启用——需要设置 skills.entries.coding-agent.enabled: true，并确保已安装且完成认证的 claude、codex、opencode 或其他受支持的 CLI 之一。
​
apiKey
string | { source, provider, id }
适用于声明了 metadata.openclaw.primaryEnv 的 skill 的便捷字段。支持明文字符串或 SecretRef 对象。
​
env
Record<string, string>
为 agent 运行注入的环境变量。仅在该变量尚未在进程中设置时才会注入。
​
config
object
用于自定义每个 skill 配置字段的可选对象。
​
allowBundled
string[]
仅适用于内置 skills 的可选允许列表。设置后，只有列表中的内置 skills 才符合条件。已管理和工作区 skills 不受影响。
默认情况下，配置键与skill 名称一致。如果某个 skill 定义了 metadata.openclaw.skillKey，请在 skills.entries 下使用该键。带连字符的名称需要加引号：JSON5 允许带引号的键。

​
环境注入

当 agent 运行开始时，OpenClaw 会：
1

读取 skill 元数据

OpenClaw 会解析 agent 的有效 skill 列表，应用门控规则、允许列表和配置覆盖。
2

注入环境变量和 API keys

skills.entries.<key>.env 和 skills.entries.<key>.apiKey 会在运行期间应用到 process.env。
3

构建系统提示词

符合条件的 skills 会被编译成一个紧凑的 XML 块，并注入到系统提示词中。
4

恢复环境

运行结束后，原始环境会被恢复。
环境注入仅作用于主机上的 agent 运行，而不作用于沙箱。在沙箱内，env 和 apiKey 不会生效。有关如何将密钥传递到沙箱运行，请参阅 Skills config。
对于内置的 claude-cli 后端，OpenClaw 还会将同一份符合条件的 skill 快照作为临时 Claude Code 插件落盘，并通过 --plugin-dir 传递。其他 CLI 后端只使用提示词目录。

​
快照与刷新

OpenClaw 会在会话开始时对符合条件的 skills 进行快照，并在该会话后续的所有轮次中复用这份列表。对 skills 或配置的更改会在下一次新会话中生效。 以下两种情况下，skills 会在会话中刷新：
  • skills watcher 检测到 SKILL.md 变更。
  • 新的符合条件的远程节点连接上来。
刷新后的列表会在下一次 agent 轮次中生效。如果有效的 agent 允许列表发生变化，OpenClaw 会刷新快照以保持可见 skills 的一致性。
默认情况下，OpenClaw 会监视 skill 文件夹，并在 SKILL.md 文件变更时更新快照。在 skills.load 下配置：
{
  skills: {
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
  },
}
对于有意使用符号链接的布局，如果某个 skill 根符号链接指向了配置根目录之外的路径，请使用 allowSymlinkTargets，例如 <workspace>/skills/manager -> ~/Projects/manager/skills。
如果 Gateway 运行在 Linux 上，但连接了一个允许 system.run 的macOS 节点，那么当所需二进制文件存在于该节点上时，OpenClaw 可以将仅适用于 macOS 的 skills 视为符合条件。agent 应通过带 host=node 的 exec 工具运行这些 skills。离线节点不会让仅远程可用的 skills 可见。如果某个节点停止响应 bin 探测，OpenClaw 会清除其缓存的 bin 匹配结果。

​
Token 影响

当 skills 符合条件时，OpenClaw 会在系统提示词中注入一个紧凑的 XML 块。其成本是确定性的： 
total = 195 + Σ (97 + len(name) + len(description) + len(filepath))
  • 基础开销（仅当 ≥ 1 个 skill 时）：约 195 个字符
  • 每个 skill： 约 97 个字符 + 你的 name、description 和 location 字段长度
  • XML 转义会将 & < > " ' 展开为实体，每次出现会额外增加少量字符
  • 按每 4 个字符约 1 个 token 计算，97 个字符约等于每个 skill 24 个 token，不含字段长度
请保持描述简短且具有描述性，以尽量减少提示词开销

​
相关内容

创建技能

编写自定义技能的分步指南。

技能工作坊

面向代理草拟技能的提案队列。

技能配置

完整的 skills.* 配置模式和代理允许列表。

斜杠命令

技能斜杠命令如何注册和路由。

ClawHub

在公共注册表中浏览和发布技能。

插件

插件可以连同其所文档化的工具一起发布技能。