技能 - OpenClaw 中文文档

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

创建技能

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

技能工作坊

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

技能配置

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

ClawHub

浏览并安装社区技能。

加载顺序

OpenClaw 从以下来源加载，优先级从高到低。当同名技能出现在多个位置时，优先级更高的来源获胜。

优先级	来源	路径
1 — 最高	工作区技能	`<workspace>/skills`
2	项目代理技能	`<workspace>/.agents/skills`
3	个人代理技能	`~/.agents/skills`（仅默认状态）
4	托管 / 本地技能	`<state-dir>/skills`
5	捆绑技能	随安装包提供
6 — 最低	额外目录	`skills.load.extraDirs` + 插件技能

技能根目录支持分组布局。只要在已配置的根目录下任意位置出现 SKILL.md，OpenClaw 就会发现该技能（最多向下 6 层）：

<workspace>/skills/research/SKILL.md          ✓ 发现为 "research"
<workspace>/skills/personal/research/SKILL.md ✓ 也发现为 "research"

文件夹路径仅用于组织。技能的名称和斜杠命令来自 name frontmatter 字段（如果缺少 name，则使用目录名）。代理允许列表（见下文）也会匹配这个 name。

Codex CLI 的原生 $CODEX_HOME/skills 目录不是 OpenClaw 的技能根目录。请使用 openclaw migrate plan codex 清点这些技能，然后用 openclaw migrate codex 将它们复制到你的 OpenClaw 工作区。

节点托管技能

已连接的无头节点可以发布其活动 OpenClaw 技能目录中安装的技能（默认位于 ~/.openclaw/skills；适用配置文件环境覆盖）。当节点连接时，这些技能会出现在正常的代理技能列表中，断开连接时则会消失。发生名称冲突时，本地或 Gateway 技能会保留其名称；节点技能会获得一个确定性的、以节点为前缀的名称。节点托管 v1 要求目录名称与该技能的 name frontmatter 字段匹配。技能条目包含节点定位器。其文件、相对引用和二进制文件都位于节点上，因此请使用 exec host=node node=<node-id> 来加载和执行它。更改其技能文件后，请重启节点主机。有关配对和关闭开关，请参见节点。

按代理与共享技能

在多代理设置中，每个代理都有自己的工作区。请使用与你期望可见性匹配的路径：

作用范围	路径	对谁可见
每个代理	`<workspace>/skills`	仅该代理
项目代理	`<workspace>/.agents/skills`	仅该工作区的代理
个人代理	`~/.agents/skills`	使用默认状态的代理
共享托管	`<state-dir>/skills`	使用该状态的所有代理
额外目录	`skills.load.extraDirs`	使用该配置的所有代理

当 OPENCLAW_STATE_DIR 指向默认 ~/.openclaw 以外的位置时，会话技能索引会排除基于主目录的个人或兼容性技能根目录，例如 ~/.agents/skills。工作区、项目、捆绑、额外以及由状态拥有的托管技能仍会照常加载。

代理允许列表

技能的位置（优先级）和技能的可见性（哪个代理可以使用它）是两个独立的控制项。使用允许列表来限制某个代理能看到哪些技能，无论它们从哪里加载。

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // 共享基线
    },
    entries: {
      writer: { default: true }, // inherits github, weather
      docs: { skills: ["docs-search"] }, // replaces defaults entirely
      "locked-down": { skills: [] }, // no skills
    },
  },
}

允许列表规则

省略 agents.defaults.skills 可使默认情况下所有技能都不受限制。
省略 agents.entries.*.skills 可继承 agents.defaults.skills。
将 agents.entries.*.skills 设置为 [] 可使该代理不暴露任何技能。
非空的 agents.entries.*.skills 列表是最终集合——它不会与默认值合并。
生效的允许列表适用于提示词构建、斜杠命令发现、沙箱同步以及技能快照。
这不是宿主 shell 的授权边界。如果同一个代理可以使用 exec，请通过沙箱、OS 用户隔离、exec 拒绝/允许列表以及按资源凭据单独约束该 shell。

插件和技能

插件可以通过在 openclaw.plugin.json 中列出 skills 目录来提供自己的技能（该路径相对于插件根目录）。启用插件后，其插件技能会被加载——例如，浏览器插件提供了用于多步骤浏览器控制的 browser-automation 技能。插件技能目录会与 skills.load.extraDirs 处于同一较低优先级级别进行合并，因此名称相同的内置、托管、代理或工作区技能将覆盖它们。插件技能本身的适用性可以通过其 frontmatter 中的 metadata.openclaw.requires 进行控制，其方式与其他技能相同。有关完整的插件系统，请参阅插件和工具。

在提示词中引用技能

在 Control UI 编辑器中输入 $，即可搜索当前代理可用的技能。选择搜索结果后，会插入其稳定的命令名称，例如 $release_notes，而不会替换消息的其余内容。一个提示词可以引用多个技能：

使用 $github 和 $release_notes 总结此更改，以便发布。

OpenClaw 会根据当前代理具备的、可由用户调用且对模型可见的技能解析这些引用，并告知模型在执行操作前读取每个被引用技能的 SKILL.md。一条消息最多可以引用八个不同的技能；如果超出数量限制，OpenClaw 会返回可见错误，而不是忽略多余的引用。 $ 形式是可组合的提示词文本；/release_notes ... 仍然是独立的命令形式，并且当技能声明了 command-dispatch: tool 时，可以使用直接工具分发。常见的大写 shell 变量，例如 $HOME、$PATH 和 $EDITOR，仍会被视为普通文本；如果要引用具有这些名称的技能，请使用小写形式 $home、$path 或 $editor。设置了 disable-model-invocation: true 的技能不会出现在 $ 选择器中，因为它们的指令会被有意排除在模型提示词之外。请改用其独立的斜杠命令显式调用这些技能。 $ 引用会在 WebChat/Control UI 的消息轮次中进行解析。其他消息渠道会将 $name 保留为普通文本；请在那里使用技能的斜杠命令。

技能工作坊

技能工作坊是代理与你当前技能文件之间的一个提案队列。当代理发现可复用的工作时，它会起草一个提案，而不是直接写入 SKILL.md。你需要在任何内容变更之前进行审阅和批准。

openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop evaluate <proposal-id>
openclaw skills workshop apply <proposal-id>

有关完整生命周期、CLI 参考和配置，请参见技能工作坊。

从 ClawHub 安装

ClawHub 是公开的技能注册中心。使用 openclaw skills 命令进行安装和更新，或使用 clawhub CLI 进行发布和同步。

操作	命令
将技能安装到工作区	`openclaw skills install @owner/<slug>`
安装外部 skills.sh 引用	`openclaw skills install skills-sh:owner/repo/slug`
从 Git 仓库安装	`openclaw skills install git:owner/repo@ref`
安装本地技能目录	`openclaw skills install ./path/to/skill --as my-tool`
为所有本地代理安装	`openclaw skills install @owner/<slug> --global`
更新所有工作区技能	`openclaw skills update --all`
更新共享托管技能	`openclaw skills update @owner/<slug> --global`
更新所有共享托管技能	`openclaw skills update --all --global`
验证技能的信任封装	`openclaw skills verify @owner/<slug>`
打印生成的 Skill Card	`openclaw skills verify @owner/<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 @owner/<slug> 会向 ClawHub 请求该技能的 clawhub.skill.verify.v1 信任封装。已安装的 ClawHub 技能会根据 .clawhub/origin.json 中记录的版本和注册表进行验证。对于已存在的已安装技能或无歧义技能，裸 slug 仍然可接受，但带所有者限定的引用可避免发布者歧义。ClawHub 技能页面会在安装前展示最新的安全扫描状态，并提供 VirusTotal、ClawScan 和静态分析的详细页面。当 ClawHub 将验证标记为失败时，该命令会以非零状态退出。发布者可通过 ClawHub 仪表板或 clawhub skill rescan @owner/<slug> 处理误报。

私有归档安装

需要非 ClawHub 分发的网关客户端可以使用 skills.upload.begin、skills.upload.chunk 和 skills.upload.commit 分段上传 zip 技能归档，然后使用 skills.install({ source: "upload", ... }) 安装。此路径默认关闭，并且需要在 openclaw.json 中设置 skills.install.allowUploadedArchives: true。正常的 ClawHub 安装不需要该设置。

安全

将第三方技能视为不受信任的代码。在启用前先阅读它们。对不受信任的输入和高风险工具优先使用沙箱运行。有关代理侧控制，请参见沙箱化。

路径包含性

Workspace、project-agent 和 extra-dir 的技能发现仅接受其解析后的 realpath 仍位于已配置根目录内的技能根目录，除非 skills.load.allowSymlinkTargets 明确可信任某个目标根目录。只有在启用 skills.workshop.allowSymlinkTargetWrites 时，Skill Workshop 才会通过这些受信任的目标进行写入。托管的 ~/.openclaw/skills 和个人的 ~/.agents/skills 可以包含带有符号链接的技能文件夹，但每个 SKILL.md 的 realpath 仍必须保持在其解析后的技能目录内。

操作者安装策略

配置 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 会先按 YAML 解析；如果失败，则回退到仅单行解析器。嵌套的 metadata 块（包括多行 YAML 映射）会被展平为 JSON 字符串，并重新按 JSON5 解析，因此在门控下展示的块形式可正常工作。请在正文中使用 {baseDir} 来引用 skill 文件夹路径。

可选 frontmatter 键

string

在 macOS Skills UI 中显示为“网站”的 URL。也支持通过 metadata.openclaw.homepage 配置。

boolean

default:"true"

当为 true 时，该 skill 会作为用户可调用的斜杠命令暴露出来。

boolean

default:"false"

当为 true 时，OpenClaw 会将该 skill 的说明排除在 agent 的常规提示词之外。该 skill 仍然可以作为斜杠命令使用，只要 user-invocable 也为 true。

"tool"

当设置为 tool 时，斜杠命令会绕过模型，直接分发到已注册的工具。

string

当设置了 command-dispatch: tool 时要调用的工具名称。

"raw"

default:"raw"

对于工具分发，会将原始参数字符串原样传递给工具，不进行核心解析。工具接收 { command: "<原始参数>", commandName: "<斜杠命令>", skillName: "<skill 名称>" }。

门控

OpenClaw 在加载时使用 metadata.openclaw（嵌入在 frontmatter 中的 JSON5 对象，参见上面的解析说明）来过滤技能。没有 metadata.openclaw 块的技能默认始终符合条件，除非被显式禁用。

---
name: image-lab
description: 通过基于提供商的图像工作流生成或编辑图像
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      }
  }
---

boolean

当为 true 时，始终包含该技能，并跳过所有其他门控。

string

在 macOS 技能界面中显示的可选 emoji。

string

在 macOS 技能界面中显示为“网站”的可选 URL。

("darwin" | "linux" | "win32")[]

平台过滤器。设置后，该技能仅在所列操作系统上符合条件。

string[]

每个二进制文件都必须存在于 PATH 中。

string[]

至少有一个二进制文件必须存在于 PATH 中。

string[]

每个环境变量都必须存在于进程中，或通过配置提供。

string[]

每个 openclaw.json 路径都必须为真值。

string

与 skills.entries.<name>.apiKey 关联的环境变量名称。

object[]

macOS 技能界面使用的可选安装器规格（brew / node / go / uv / download）。

当 metadata.openclaw 不存在时，仍然接受旧版 metadata.clawdbot 块，因此较早安装的技能仍可保留它们的依赖门控和安装提示。新技能应使用 metadata.openclaw。

安装器规格

安装器规格告诉 macOS 技能界面如何安装依赖：

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

安装器选择规则

当列出多个安装器时，网关会选择一个首选项（可用时优先 brew，否则 node）。
如果所有安装器都是 download，OpenClaw 会列出每个条目，以便你查看所有可用制品。
规格可以包含 os: ["darwin"|"linux"|"win32"] 来按平台过滤。
Node 安装会遵循 openclaw.json 中的 skills.install.nodeManager（默认：npm；可选：npm / pnpm / yarn / bun）。这只影响技能安装；Gateway 运行时仍应使用 Node。
网关安装器优先级：Homebrew → uv → 已配置的 node manager → go → download。

每个安装器的详细信息

Homebrew: OpenClaw 不会自动安装 Homebrew，也不会将 brew formula 转换为系统包命令。在没有 brew 的 Linux 容器中，只显示非 brew 专用的安装器；请使用自定义镜像或手动安装依赖。
Go: OpenClaw 进行自动技能安装时要求 Go 1.21 或更高版本。如果缺少 go 且 Homebrew 可用，OpenClaw 会先通过 Homebrew 安装 Go；在没有 Homebrew 的 Linux 上，如果刷新后的 golang-go 候选版本满足最低版本要求，也可以改用 apt-get 以 root 或通过免密 sudo 来安装。依赖项实际执行的 go install 总是目标为专用的、由 OpenClaw 管理的 bin 目录（全新安装时为 Homebrew 的 bin，否则为 ~/.local/bin），而不是你配置的 GOBIN —— 你自己的 GOBIN、GOPATH 和 GOTOOLCHAIN 环境变量会被读取，但绝不会被覆盖。
Download: url（必填）、archive（tar.gz | tar.bz2 | zip）、 extract（默认：检测到 archive 时自动）、stripComponents、 targetDir（默认：~/.openclaw/tools/<skillKey>）。

沙箱说明

requires.bins 会在技能加载时于主机上检查。如果 agent 在沙箱中运行，该二进制文件也必须存在于容器内。请通过 agents.defaults.sandbox.docker.setupCommand 或自定义镜像安装它。setupCommand 会在容器创建后运行一次，并且需要沙箱具备网络外连、可写的根文件系统以及 root 用户。

配置覆盖

在 ~/.openclaw/openclaw.json 的 skills.entries 下切换并配置内置或已管理的技能：

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

boolean

false 会禁用该技能，即使它是内置或已安装的。coding-agent 内置技能默认不启用——需要设置 skills.entries.coding-agent.enabled: true，并确保已安装且完成认证的 claude、codex、opencode 或其他受支持的 CLI 之一。

string | { source, provider, id }

适用于声明了 metadata.openclaw.primaryEnv 的技能的便捷字段。支持明文字符串或 SecretRef 对象。

Record<string, string>

为 agent 运行注入的环境变量。仅在该变量尚未在进程中设置时才会注入。

object

用于自定义每个 skill 配置字段的可选对象。

string[]

仅适用于内置 skills 的可选允许列表。设置后，只有列表中的内置 skills 才符合条件。已管理和工作区 skills 不受影响。

默认情况下，配置键与技能名称匹配。如果某个技能定义了 metadata.openclaw.skillKey，则请改为在 skills.entries 下使用该键。带连字符的名称需要加引号：JSON5 允许带引号的键。

环境注入

当代理运行开始时，OpenClaw 会：

读取技能元数据

OpenClaw 会解析代理的有效技能列表，应用门控规则、允许列表和配置覆盖。

注入环境变量和 API 密钥

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

构建系统提示词

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

恢复环境

运行结束后，原始环境会被恢复。

环境注入仅作用于主机上的代理运行，而不作用于沙箱。在沙箱内，env 和 apiKey 不会生效。有关如何将密钥传递到沙箱运行，请参阅技能配置。

对于内置的 claude-cli 后端，OpenClaw 还会将同一份符合条件的技能快照作为临时 Claude Code 插件落盘，并通过 --plugin-dir 传递。其他 CLI 后端只使用提示词目录。

快照与刷新

OpenClaw 会在会话开始时对符合条件的 skills 进行快照，并在该会话后续的所有轮次中复用这份列表。对 skills 或配置的更改会在下一次新会话中生效。以下两种情况下，skills 会在会话中刷新：

skills 监视器检测到 SKILL.md 变更。
新的符合条件的远程节点连接上来。

刷新后的列表会在下一次 agent 轮次中生效。如果有效的 agent 允许列表发生变化，OpenClaw 会刷新快照以保持可见 skills 的一致性。

Skills 监视器

默认情况下，OpenClaw 会监视 skill 文件夹，并在 SKILL.md 文件变更时更新快照。在 skills.load 下配置：

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

观察器事件使用内置的 250 ms 防抖。对于有意使用符号链接布局、且 skill 根符号链接指向配置根目录之外的情况，请使用 allowSymlinkTargets，例如 <workspace>/skills/manager -> ~/Projects/manager/skills。仅当 Skill Workshop 也应通过这些受信任的符号链接路径应用提案时，才启用 skills.workshop.allowSymlinkTargetWrites。

远程 macOS 节点（Linux 网关）

如果 Gateway 运行在 Linux 上，但连接了一个允许 system.run 的macOS 节点，那么当所需二进制文件存在于该节点上时，OpenClaw 可以将仅适用于 macOS 的 skills 视为符合条件。agent 应通过带 host=node 的 exec 工具运行这些 skills。离线节点不会让仅远程可用的 skills 可见。如果某个节点停止响应 bin 探测，OpenClaw 会清除其缓存的 bin 匹配结果。

Token 影响

当 skills 符合条件时，OpenClaw 会在系统提示词中注入一个紧凑的 XML 块。其成本是确定性的，并且会随每个 skill 线性增长：

基础开销（仅在有 1 个或以上 skills 符合条件时）：一段固定的介绍性文本，加上 <available_skills> 包装器。
**每个 skill：**约 97 个字符 + 你的 name、description 和 location 字段长度。
XML 转义会将 & < > " ' 展开为实体，因此每次出现都会增加少量字符。
按每 token 约 4 个字符计算，97 个字符 ≈ 每个 skill 24 个 token，尚未计入字段长度。

如果渲染后的块会超过配置的提示词预算（skills.limits.maxSkillsPromptChars），OpenClaw 会首先尽可能保留尽量多的 skill 标识（name、location 和 version），这些信息可以放入不含描述的紧凑格式中。然后会使用剩余预算放入缩短后的描述。如果不再有描述预算，则会省略描述。只要需要紧凑格式或列表截断，提示词中就会包含一条指向 openclaw skills check 的提示。请保持描述简短且具有描述性，以尽量减少提示词开销

创建技能

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

技能工作坊

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

技能配置

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

斜杠命令

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

ClawHub

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

插件

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

概览

插件

插件指南

构建插件

技能

自动化

工具

智能体协作

技能

创建技能

技能工作坊

技能配置

ClawHub

加载顺序

节点托管技能

按代理与共享技能

代理允许列表

插件和技能

在提示词中引用技能

技能工作坊

从 ClawHub 安装

安全

SKILL.md 格式

可选 frontmatter 键

门控

安装器规格

配置覆盖

环境注入

快照与刷新

Token 影响

相关内容

创建技能

技能工作坊

技能配置

斜杠命令

ClawHub

插件

创建技能

技能工作坊

技能配置

ClawHub

​加载顺序

​节点托管技能

​按代理与共享技能

​代理允许列表

​插件和技能

​在提示词中引用技能

​技能工作坊

​从 ClawHub 安装

​安全

​SKILL.md 格式

​可选 frontmatter 键

​门控

​安装器规格

​配置覆盖

​环境注入

​快照与刷新

​Token 影响

​相关内容

创建技能

技能工作坊

技能配置

斜杠命令

ClawHub

插件

加载顺序

节点托管技能

按代理与共享技能

代理允许列表

插件和技能

在提示词中引用技能

技能工作坊

从 ClawHub 安装

安全

SKILL.md 格式

可选 frontmatter 键

门控

安装器规格

配置覆盖

环境注入

快照与刷新

Token 影响

相关内容