OpenClaw 中文

深色模式

广告 · 本站推荐广告

技能（OpenClaw） ​

OpenClaw 使用兼容 AgentSkills 的技能文件夹来教智能体如何使用工具。每个技能是一个包含 SKILL.md 文件的目录，该文件带有 YAML frontmatter 和指令。OpenClaw 加载内置技能和可选的本地覆盖，并在加载时根据环境、配置和二进制文件存在性进行过滤。

位置与优先级 ​

技能从三个位置加载：

  1. 内置技能：随安装包附带（npm 包或 OpenClaw.app）
  2. 托管/本地技能：~/.openclaw/skills
  3. 工作区技能：/skills

如果技能名称冲突，优先级为：/skills（最高）→ ~/.openclaw/skills → 内置技能（最低）。

此外，你可以通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 配置额外的技能目录（最低优先级）。

每智能体 vs 共享技能 ​

在多智能体设置中，每个智能体有自己的工作区。这意味着：

  • 每智能体技能存放在 /skills 中，仅对该智能体可见。
  • 共享技能存放在 ~/.openclaw/skills（托管/本地），对同一机器上的所有智能体可见。
  • 共享文件夹也可以通过 skills.load.extraDirs（最低优先级）添加，如果你想要一个被多个智能体使用的通用技能包。

如果同一技能名称存在于多个位置，通常的优先级规则适用：工作区优先，然后是托管/本地，最后是内置。

插件 + 技能 ​

插件可以通过在 openclaw.plugin.json 中列出 skills 目录来附带自己的技能（路径相对于插件根目录）。插件技能在插件启用时加载，并参与正常的技能优先级规则。你可以通过插件配置条目上的 metadata.openclaw.requires.config 来控制它们。

参见插件了解发现/配置，以及工具了解这些技能所教授的工具。

ClawHub（安装与同步） ​

ClawHub 是 OpenClaw 的公共技能注册中心。浏览地址：https://clawhub.com。用于发现、安装、更新和备份技能。完整指南：ClawHub。

常用操作：

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

默认情况下，clawhub 安装到当前工作目录下的 ./skills（或回退到配置的 OpenClaw 工作区）。OpenClaw 会在下一个会话中将其作为 /skills 加载。

安全说明 ​

  • 将第三方技能视为不受信任的代码。在启用前请仔细阅读。
  • 对于不受信任的输入和高风险工具，建议使用沙箱运行。参见沙箱。
  • skills.entries.<name>.env 和 skills.entries.<name>.apiKey 将密钥注入到该智能体轮次的主机进程中（不是沙箱）。请将密钥远离提示词和日志。
  • 有关更广泛的威胁模型和检查清单，请参见安全。

格式（AgentSkills + Pi 兼容） ​

SKILL.md 必须至少包含：

markdown
---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

注意事项：

  • 我们遵循 AgentSkills 规范的布局/意图。
  • 嵌入式智能体使用的解析器仅支持单行 frontmatter 键。
  • metadata 应该是一个单行 JSON 对象。
  • 在指令中使用 {baseDir} 引用技能文件夹路径。
  • 可选的 frontmatter 键：
    • homepage — 在 macOS 技能 UI 中显示为"Website"的 URL（也支持通过 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: "", commandName: "", skillName: "" }。

过滤（加载时过滤） ​

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

markdown
---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata: { "openclaw": { "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] }, "primaryEnv": "GEMINI_API_KEY", }, }
---

metadata.openclaw 下的字段：

  • always: true — 始终包含该技能（跳过其他过滤条件）。
  • emoji — macOS 技能 UI 使用的可选表情符号。
  • homepage — macOS 技能 UI 中显示为"Website"的可选 URL。
  • os — 可选的平台列表（darwin、linux、win32）。如果设置，技能仅在这些操作系统上可用。
  • requires.bins — 列表；每个都必须存在于 PATH 中。
  • requires.anyBins — 列表；至少一个必须存在于 PATH 中。
  • requires.env — 列表；环境变量必须存在或在配置中提供。
  • requires.config — openclaw.json 路径列表，必须为真值。
  • primaryEnv — 与 skills.entries.<name>.apiKey 关联的环境变量名。
  • install — macOS 技能 UI 使用的可选安装器规格数组（brew/node/go/uv/download）。

关于沙箱的说明：

  • requires.bins 在技能加载时在主机上检查。
  • 如果智能体被沙箱化，二进制文件也必须存在于容器内部。通过 agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装。setupCommand 在容器创建后运行一次。包安装还需要网络出口、可写的根文件系统和沙箱中的 root 用户。示例：summarize 技能（skills/summarize/SKILL.md）需要沙箱容器中有 summarize CLI 才能运行。

安装器示例：

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 会选择一个首选选项（可用时选 brew，否则选 node）。
  • 如果所有安装器都是 download，OpenClaw 会列出每个条目以便你查看可用的构件。
  • 安装器规格可以包含 os: ["darwin"|"linux"|"win32"] 按平台过滤选项。
  • Node 安装遵循 openclaw.json 中的 skills.install.nodeManager（默认：npm；选项：npm/pnpm/yarn/bun）。这仅影响技能安装；Gateway 运行时应该仍使用 Node（不推荐将 Bun 用于 WhatsApp/Telegram）。
  • Go 安装：如果 go 缺失且 brew 可用，gateway 会先通过 Homebrew 安装 Go，并在可能时将 GOBIN 设置为 Homebrew 的 bin。
  • Download 安装：url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（默认：检测到归档时自动提取）、stripComponents、targetDir（默认：~/.openclaw/tools/）。

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

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

内置/托管技能可以被切换并提供环境值：

json5
{
  skills: {
    entries: {
      "nano-banana-pro": {
        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 },
    },
  },
}

注意：如果技能名称包含连字符，请给键加引号（JSON5 允许带引号的键）。配置键默认匹配技能名称。如果技能定义了 metadata.openclaw.skillKey，请在 skills.entries 下使用该键。

规则：

  • enabled: false 禁用技能，即使它是内置/已安装的。
  • env：仅在变量尚未在进程中设置时注入。
  • apiKey：为声明了 metadata.openclaw.primaryEnv 的技能提供的便捷方式。支持纯文本字符串或 SecretRef 对象（{ source, provider, id }）。
  • config：自定义每技能字段的可选包；自定义键必须放在这里。
  • allowBundled：仅用于内置技能的可选允许列表。如果设置，仅列表中的内置技能可用（托管/工作区技能不受影响）。

环境注入（每次智能体运行） ​

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

  1. 读取技能元数据。
  2. 将 skills.entries.<name>.env 或 skills.entries.<name>.apiKey 应用到 process.env。
  3. 使用可用的技能构建系统提示。
  4. 运行结束后恢复原始环境。

这限定在智能体运行范围内，而非全局 shell 环境。

会话快照（性能） ​

OpenClaw 在会话开始时对可用技能进行快照，并在同一会话的后续轮次中重用该列表。对技能或配置的更改在下一个新会话中生效。

技能也可以在会话中刷新——当技能监视器启用时或当新的可用远程节点出现时（见下文）。可以把这理解为热重载：刷新后的列表会在下一个智能体轮次中被使用。

远程 macOS 节点（Linux Gateway） ​

如果 Gateway 运行在 Linux 上但连接了一个macOS 节点且允许 system.run（Exec 审批安全设置未设为 deny），OpenClaw 可以在该节点上存在所需二进制文件时将 macOS 专用技能视为可用。智能体应通过 nodes 工具（通常是 nodes.run）执行这些技能。

这依赖于节点报告其命令支持情况以及通过 system.run 的二进制探测。如果 macOS 节点后来离线，技能仍然可见；调用可能会失败直到节点重新连接。

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

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

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

Token 影响（技能列表） ​

当技能可用时，OpenClaw 将可用技能的紧凑 XML 列表注入系统提示（通过 pi-coding-agent 中的 formatSkillsForPrompt）。成本是确定性的：

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

公式（字符数）：

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

注意事项：

  • XML 转义将 & < > " ' 展开为实体（&amp;、&lt; 等），增加长度。
  • Token 数量因模型分词器而异。粗略的 OpenAI 风格估算是每个 token 约 4 个字符，因此每个技能 97 个字符 ≈ 24 个 token 加上你的实际字段长度。

托管技能生命周期 ​

OpenClaw 作为安装的一部分（npm 包或 OpenClaw.app）附带一组基线的内置技能。~/.openclaw/skills 用于本地覆盖（例如，固定/补丁一个技能而不更改内置副本）。工作区技能由用户拥有，在名称冲突时覆盖两者。

配置参考 ​

参见 技能配置 了解完整的配置模式。

寻找更多技能？ ​

浏览 https://clawhub.com。

基于MIT协议开源 | 内容翻译自 官方文档，同步更新

Copyright © 2026 OpenClaw 中文社区