Skills

Skills 是 Markdown 指令文件，用于教智能体如何以及何时使用工具。每个 Skill 都位于一个目录中，该目录包含带有 YAML frontmatter 和 Markdown 正文的 SKILL.md 文件。OpenClaw 会加载内置 Skills 和所有本地覆盖项，并在加载时根据环境、配置和二进制文件是否存在进行筛选。

创建技能

从头构建并测试自定义 Skill。

Skill Workshop

审查并批准智能体起草的 Skill 提案。

Skills 配置

完整的 skills.* 配置架构和智能体允许列表。

ClawHub

浏览并安装社区 Skills。

加载顺序

OpenClaw 按以下来源加载，优先级从高到低。当多个位置出现同名 Skill 时，优先级最高的来源生效。

优先级	来源	路径
1 — 最高	工作区 Skills	`<workspace>/skills`
2	项目智能体 Skills	`<workspace>/.agents/skills`
3	个人智能体 Skills	`~/.agents/skills`
4	托管／本地 Skills	`~/.openclaw/skills`
5	内置 Skills	随安装包提供
6 — 最低	额外目录	`skills.load.extraDirs` + 插件 Skills

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

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

文件夹路径仅用于组织。Skill 的名称和斜杠命令来自 name frontmatter 字段（缺少 name 时则使用目录名称）。智能体允许列表（见下文）也按此 name 进行匹配。

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

节点托管的 Skills

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

每智能体 Skills 与共享 Skills

在多智能体设置中，每个智能体都有自己的工作区。请使用与你所需可见范围匹配的路径：

范围	路径	可见对象
每智能体	`<workspace>/skills`	仅该智能体
项目智能体	`<workspace>/.agents/skills`	仅该工作区的智能体
个人智能体	`~/.agents/skills`	此计算机上的所有智能体
共享托管	`~/.openclaw/skills`	此计算机上的所有智能体
额外目录	`skills.load.extraDirs`	此计算机上的所有智能体

智能体允许列表

Skill 位置（优先级）和 Skill 可见性（哪个智能体可以使用它）是独立的控制项。无论 Skills 从何处加载，都可以使用允许列表限制智能体可见的 Skills。

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // 共享基线
    },
    list: [
      { id: "writer" }, // 继承 github、weather
      { id: "docs", skills: ["docs-search"] }, // 完全替换默认值
      { id: "locked-down", skills: [] }, // 无 Skills
    ],
  },
}

允许列表规则

省略 agents.defaults.skills，默认不限制任何 Skills。
省略 agents.entries.*.skills，以继承 agents.defaults.skills。
将 agents.entries.*.skills: [] 设为不向该智能体公开任何 Skills。
非空的 agents.entries.*.skills 列表是最终集合，不会与默认值合并。
生效的允许列表适用于提示词构建、斜杠命令发现、沙箱同步和 Skill 快照。
这并非主机 shell 授权边界。如果同一智能体能够使用 exec，请另外通过沙箱隔离、操作系统用户隔离、Exec 拒绝／允许列表和按资源配置的凭据来限制该 shell。

插件和 Skills

插件可以通过在 openclaw.plugin.json 中列出 skills 目录（相对于插件根目录的路径）来随附自己的 Skills。启用插件时会加载插件 Skills——例如，浏览器插件随附一个用于多步骤浏览器控制的 browser-automation Skill。插件 Skill 目录与 skills.load.extraDirs 处于相同的低优先级层级，因此同名的内置、托管、智能体或工作区 Skill 会覆盖它们。与其他 Skill 一样，可以通过其 frontmatter 中的 metadata.openclaw.requires 控制插件 Skill 自身是否符合条件。有关完整插件系统，请参阅插件和工具。

Skill Workshop

Skill Workshop 是智能体与你当前 Skill 文件之间的提案队列。当智能体发现可复用的工作时，它会起草提案，而不是直接写入 SKILL.md。任何内容更改前都需要你审查并批准。

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

有关完整生命周期、CLI 参考和配置，请参阅 Skill Workshop。

从 ClawHub 安装

ClawHub 是公共 Skills 注册表。使用 openclaw skills 命令进行安装和更新，或使用 clawhub CLI 进行发布和同步。

操作	命令
将 Skill 安装到工作区	`openclaw skills install @owner/<slug>`
从 Git 仓库安装	`openclaw skills install git:owner/repo@ref`
安装本地 Skill 目录	`openclaw skills install ./path/to/skill --as my-tool`
为所有本地智能体安装	`openclaw skills install @owner/<slug> --global`
更新所有工作区 Skills	`openclaw skills update --all`
更新共享托管 Skill	`openclaw skills update @owner/<slug> --global`
更新所有共享托管 Skills	`openclaw skills update --all --global`
验证 Skill 的信任边界	`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。如果 SKILL.md frontmatter 的 name 有效，则使用它作为 slug，否则回退到目录或仓库名称。使用 --as <slug> 可覆盖此值。 openclaw skills update 仅跟踪 ClawHub 安装——要刷新 Git 或本地来源，请重新安装。

验证和安全扫描

openclaw skills verify @owner/<slug> 会向 ClawHub 请求 Skill 的 clawhub.skill.verify.v1 信任边界。已安装的 ClawHub Skills 会根据 .clawhub/origin.json 中记录的版本和注册表进行验证。对于现有已安装或名称明确的 Skills，仍接受不带所有者的 slug，但带所有者限定的引用可以避免发布者歧义。ClawHub Skill 页面会在安装前显示最新的安全扫描状态，并提供 VirusTotal、ClawScan 和静态分析的详情页面。当 ClawHub 将验证标记为失败时，命令会以非零状态退出。发布者可通过 ClawHub 控制面板或 clawhub skill rescan @owner/<slug> 处理误报。

私有归档安装

需要非 ClawHub 交付方式的 Gateway 网关客户端，可以使用 skills.upload.begin、skills.upload.chunk 和 skills.upload.commit 暂存 zip 格式的 Skill 归档，然后使用 skills.install({ source: "upload", ... }) 安装。此路径默认关闭，并要求在 openclaw.json 中配置 skills.install.allowUploadedArchives: true。常规 ClawHub 安装绝不需要该设置。

安全

将第三方 Skills 视为不受信任的代码。启用前请阅读其内容。对于不受信任的输入和高风险工具，优先使用沙箱隔离运行。有关智能体侧的控制措施，请参阅沙箱隔离。

路径限制

工作区、项目智能体和额外目录的 Skill 发现仅接受解析后的 realpath 仍位于已配置根目录内的 Skill 根目录，除非 skills.load.allowSymlinkTargets 明确信任目标根目录。仅当启用 skills.workshop.allowSymlinkTargetWrites 时，Skill Workshop 才能通过这些受信任的目标写入。托管的 ~/.openclaw/skills 和个人的 ~/.agents/skills 可以包含符号链接 Skill 文件夹，但每个 SKILL.md 的 realpath 仍必须位于其解析后的 Skill 目录内。

操作员安装策略

配置 security.installPolicy，以便在继续安装 Skill 前运行受信任的本地策略命令。该策略会接收元数据和暂存的源路径，适用于 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 中显示为 “Website” 的 URL。也可通过 metadata.openclaw.homepage 支持。

boolean

默认值:"true"

当 true 时，该技能会作为用户可调用的斜杠命令公开。

boolean

默认值:"false"

当 true 时，OpenClaw 不会将该技能的指令加入智能体的常规提示词。当 user-invocable 同时为 true 时，该技能仍可作为斜杠命令使用。

"tool"

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

string

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

"raw"

默认值:"raw"

对于工具分派，将原始参数字符串直接转发给工具，不进行任何核心解析。工具会收到 { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

门控

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 Skills UI 中显示的可选表情符号。

string

macOS Skills UI 中以 “Website” 显示的可选 URL。

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

平台筛选器。设置后，该技能仅在列出的操作系统上符合条件。

string[]

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

string[]

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

string[]

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

string[]

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

string

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

object[]

macOS Skills UI 使用的可选安装程序规范（brew / node / go / uv / download）。

当缺少 metadata.openclaw 时，仍接受旧版 metadata.clawdbot 块，因此较早安装的技能会保留其依赖项门控和安装程序提示。新技能应使用 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 时选择 brew，否则选择 node）。
如果所有安装程序都是 download，OpenClaw 会列出每个条目，以便你查看所有可用工件。
规范可以包含 os: ["darwin"|"linux"|"win32"]，以按平台筛选。
Node 安装遵循 openclaw.json 中的 skills.install.nodeManager （默认值：npm；选项：npm / pnpm / yarn / bun）。这仅影响技能安装；Gateway 网关运行时仍应使用 Node。
Gateway 网关安装程序优先级：Homebrew → uv → 已配置的 node 管理器 → go → download。

各安装程序详情

**Homebrew：**OpenClaw 不会自动安装 Homebrew，也不会将 brew 公式转换为系统软件包命令。在缺少 brew 的 Linux 容器中，仅支持 brew 的安装程序会被隐藏；请使用自定义镜像或手动安装依赖项。
**Go：**OpenClaw 要求 Go 1.21 或更高版本才能自动安装技能。如果缺少 go 且 Homebrew 可用，OpenClaw 会先通过 Homebrew 安装 Go；在没有 Homebrew 的 Linux 上，如果刷新的 golang-go 候选版本满足最低版本要求，则可以改为以 root 身份或通过无需密码的 sudo 使用 apt-get。依赖项实际使用的 go install 始终指向 OpenClaw 管理的专用 bin 目录（全新安装时为 Homebrew 的 bin，否则为 ~/.local/bin），而不是你配置的 GOBIN —— 系统会读取你自己的 GOBIN、GOPATH 和 GOTOOLCHAIN 环境变量，但绝不会覆盖它们。
下载：url（必需）、archive（tar.gz | tar.bz2 | zip）、 extract（默认值：检测到归档时为 auto）、stripComponents、 targetDir（默认值：~/.openclaw/tools/<skillKey>）。

沙箱隔离注意事项

加载技能时会在宿主机上检查 requires.bins。如果智能体在沙箱中运行，该二进制文件也必须存在于容器内部。请通过 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，并确保已安装且已完成身份验证的 CLI 包括 claude、codex、opencode 或其他受支持的 CLI 之一。

string | { source, provider, id }

为声明 metadata.openclaw.primaryEnv 的技能提供的便捷字段。支持明文字符串或 SecretRef 对象。

Record<string, string>

为智能体运行注入的环境变量。仅当进程中尚未设置该变量时才注入。

object

用于自定义各技能配置字段的可选属性集合。

string[]

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

默认情况下，配置键与技能名称匹配。如果技能定义了 metadata.openclaw.skillKey，请改用 skills.entries 下的该键。请用引号括起含连字符的名称：JSON5 允许使用带引号的键。

环境注入

当智能体运行开始时，OpenClaw 会：

读取技能元数据

OpenClaw 解析该智能体的有效技能列表，并应用门控规则、允许列表和配置覆盖。

注入环境变量和 API 密钥

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

构建系统提示词

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

恢复环境

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

环境变量注入的作用域是宿主机上的智能体运行，而非沙箱。在沙箱内，env 和 apiKey 不会生效。有关如何将密钥传入沙箱隔离的运行，请参阅 Skills 配置。

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

快照和刷新

OpenClaw 会在会话启动时为符合条件的技能创建快照，并在该会话后续的所有轮次中重复使用该列表。对技能或配置的更改会在下一个新会话中生效。在以下两种情况下，Skills 会在会话中途刷新：

Skills 监视器检测到 SKILL.md 更改。
新的符合条件的远程节点连接。

刷新的列表会在下一个智能体轮次中使用。如果有效的智能体允许列表发生变化，OpenClaw 会刷新快照，使可见技能保持一致。

Skills 监视器

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

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

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

远程 macOS 节点（Linux Gateway 网关）

如果 Gateway 网关在 Linux 上运行，但已连接一个允许 system.run 的 macOS 节点，且该节点上存在所需的二进制文件， OpenClaw 可以将仅限 macOS 的技能视为符合条件。智能体应通过 exec 工具并使用 host=node 来运行这些技能。离线节点不会使仅限远程的技能可见。如果节点停止响应二进制文件探测，OpenClaw 会清除其缓存的二进制文件匹配项。

Token 影响

当有符合条件的技能时，OpenClaw 会将紧凑的 XML 块注入系统提示词。其成本是确定性的，并随技能数量线性增长：

基础开销（仅当有 1 个或更多符合条件的技能时）：固定的介绍性文本块以及 <available_skills> 包装器。
**每个技能：**约 97 个字符，加上 name、description 和 location 字段的长度。
XML 转义会将 & < > " ' 展开为实体，每次出现时会增加几个字符。
按约 4 个字符/token 计算，在不计字段长度前，97 个字符 ≈ 每个技能 24 个 token。

如果渲染后的块会超出配置的提示词预算 (skills.limits.maxSkillsPromptChars)，OpenClaw 会先使用不含描述的紧凑格式，保留预算可容纳的尽可能多的技能标识信息（名称、位置和版本）。然后，它会将所有剩余预算用于缩短后的描述。如果没有剩余的描述预算，则省略描述。只要需要使用紧凑格式或截断列表，提示词中就会包含一条指向 openclaw skills check 的说明。保持描述简短且表意清晰，以最大限度减少提示词开销。

创建技能

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

技能工作坊

Agent 起草技能的提案队列。

Skills 配置

完整的 skills.* 配置架构和 Agent 允许列表。

斜杠命令

技能斜杠命令的注册和路由方式。

ClawHub

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

插件

插件可以随其所记录的工具一起提供技能。

概览

Plugins

扩展

Building plugins

技能

自动化与任务

内置工具

代理协作

创建技能

Skill Workshop

Skills 配置

ClawHub

加载顺序

节点托管的 Skills

每智能体 Skills 与共享 Skills

智能体允许列表

插件和 Skills

Skill Workshop

从 ClawHub 安装

安全

SKILL.md 格式

可选 frontmatter 键

门控

安装程序规范

配置覆盖

环境注入

快照和刷新

Token 影响

相关内容

创建技能

技能工作坊

Skills 配置

斜杠命令

ClawHub

插件

创建技能

Skill Workshop

Skills 配置

ClawHub

​加载顺序

​节点托管的 Skills

​每智能体 Skills 与共享 Skills

​智能体允许列表

​插件和 Skills

​Skill Workshop

​从 ClawHub 安装

​安全

​SKILL.md 格式

​可选 frontmatter 键

​门控

​安装程序规范

​配置覆盖

​环境注入

​快照和刷新

​Token 影响

​相关内容

创建技能

技能工作坊

Skills 配置

斜杠命令

ClawHub

插件

加载顺序

节点托管的 Skills

每智能体 Skills 与共享 Skills

智能体允许列表

插件和 Skills

Skill Workshop

从 ClawHub 安装

安全

SKILL.md 格式

可选 frontmatter 键

门控

安装程序规范

配置覆盖

环境注入

快照和刷新

Token 影响

相关内容