OpenClaw 的技能从六个位置加载（workspace > .agents/skills > ~/.agents/skills > ~/.openclaw/skills > bundled > extraDirs），同名时高优先级覆盖低优先级。每个智能体可通过 agents.list[].skills 精确控制可见技能列表，不设则继承 defaults。技能通过 SKILL.md 的 metadata.openclaw.requires（bins/env/config）过滤加载，密钥和配置用 skills.entries.* 覆盖。用 openclaw skills install 安装 ClawHub 技能，SKILL.md 修改后会话重启或开启 watcher 后生效。不涉及发布流程。

OpenClaw 技能怎么配置：加载优先级、Allowlist 与门控过滤

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

技能加载位置与优先级（六层）

OpenClaw 从以下来源加载技能，高优先级优先：

#	来源	路径
1	工作区技能	<workspace>/skills
2	项目智能体技能	<workspace>/.agents/skills
3	个人智能体技能	~/.agents/skills
4	Managed/本地技能	~/.openclaw/skills
5	内置技能	随安装包一起提供
6	额外技能文件夹	skills.load.extraDirs（配置中）

如果技能名称冲突，高优先级来源胜出。

注意：Codex CLI 的原生 $CODEX_HOME/skills 目录不在上述技能根目录中。在 Codex harness 模式下，本地 app-server 启动使用隔离的 per-agent Codex home，因此操作员的个人 ~/.codex/skills 不会被隐式加载。OpenClaw 自己的技能根目录已经包含了 ~/.agents/skills。使用 openclaw migrate codex --dry-run 盘点 Codex home 中的技能，再用 openclaw migrate codex 通过交互式复选框选择技能目录并复制到当前工作区。非交互模式重复 --skill <name> 指定精确复制的技能。

Per-Agent 与共享技能的作用域

作用域	路径	对谁可见
单智能体	<workspace>/skills	仅该智能体
项目智能体	<workspace>/.agents/skills	仅该工作区的智能体
个人智能体	~/.agents/skills	该机器上所有智能体
共享 managed/本地	~/.openclaw/skills	该机器上所有智能体
共享额外目录	skills.load.extraDirs（低优先级）	该机器上所有智能体

同名技能在多个位置出现时，高优先级胜出。顺序：工作区 > 项目智能体 > 个人智能体 > managed/本地 > 内置 > extraDirs。

配置的技能根目录也支持一级分组，例如 skills/<group>/<skill>/SKILL.md，这样相关的第三方技能可以放在同一个共享文件夹下，无需广泛的递归扫描。

怎么配置 Agent Allowlist（per-agent 技能白名单）

技能位置和技能可见性是独立的控制。位置/优先级决定同名技能哪个版本胜出；agent allowlists 决定技能加载后哪些技能该 agent 可以使用。

{
  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: [] 则该 agent 无技能。
• 非空 agents.list[].skills 列表是该 agent 的最终集合，不与 defaults 合并。
• 有效的 allowlist 作用于提示词构建、技能斜杠命令发现、沙箱同步和技能快照。

插件的技能怎么加载

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

ClawHub 安装与同步

ClawHub 是 OpenClaw 的公共技能注册中心。使用原生 openclaw skills 命令进行发现/安装/更新，或使用单独的 clawhub CLI 进行发布/同步。详细指南：ClawHub。

操作	命令
将 ClawHub 技能安装到工作区	openclaw skills install <skill-slug>
将 Git 技能安装到工作区	openclaw skills install git:owner/repo@ref
将本地技能安装到工作区	openclaw skills install ./path/to/skill --as my-tool
为所有本地 agent 安装技能	openclaw skills install <skill-slug> --global
更新所有工作区已安装技能	openclaw skills update --all
更新单个共享 managed 技能	openclaw skills update <skill-slug> --global
更新所有共享 managed/本地技能	openclaw skills update --all --global
同步（扫描 + 发布更新）	clawhub sync --all

openclaw skills install 默认安装到当前工作区的 skills/ 目录。添加 --global 安装到共享 managed/本地目录（默认 ~/.openclaw/skills），该目录对所有本地 agent 可见，除非 agent 技能 allowlist 限制可见性。单独的 clawhub CLI 也安装到 ./skills 下（当前工作目录），或回退到配置的 OpenClaw 工作区。OpenClaw 在下次会话时将其识别为 <workspace>/skills。

Git 和本地目录安装期望源根目录下存在 SKILL.md。安装 slug 来自 SKILL.md frontmatter 的 name（当它是有效 slug 时），然后回退到源目录或仓库名。使用 --as <slug> 覆盖推断的 slug。--version 仅适用于 ClawHub 安装。技能安装不支持 npm 包规范或 zip/archive 路径。openclaw skills update 仅更新 ClawHub 跟踪的安装；Git 或本地源需要重新安装以刷新。

需要非 ClawHub 私密交付的 Gateway 客户端，可以通过 skills.upload.begin、skills.upload.chunk、skills.upload.commit 暂存 zip 技能归档，然后用 skills.install({ source: "upload", uploadId, slug, force?, sha256? }) 安装已提交的上传。这需要显式设置 skills.install.allowUploadedArchives: true 在 openclaw.json 中。上传模式仍安装到默认 agent 工作区的 skills/<slug> 目录；归档内的文件夹名被忽略。上传模式默认关闭。

ClawHub 技能页面在安装前展示最新的安全扫描状态，包括 VirusTotal、ClawScan 和静态分析的详情页。openclaw skills install <slug> 只是安装路径；发布者通过 ClawHub 仪表盘或 clawhub skill rescan <slug> 处理误报。

安全注意事项

WARNING

将第三方技能视为不可信代码。启用前请先阅读其内容。优先对不可信输入和风险工具使用沙箱运行。参见 Sandboxing 了解 agent 侧控制。

• 工作区、项目智能体和额外目录的技能发现只接受技能根目录，其解析后的真实路径必须在配置的根目录内，除非 skills.load.allowSymlinkTargets 显式信任目标根目录。内置技能始终包含。Managed ~/.openclaw/skills 和个人 ~/.agents/skills 根目录可能包含由 ClawHub 或其他本地技能管理器安装的符号链接技能文件夹，但每个 SKILL.md 的真实路径必须仍在其解析后的技能目录内。
• Gateway 私有归档安装默认关闭。当显式启用时，需要提交包含 SKILL.md 的 zip 归档，并复用与 ClawHub 技能安装相同的归档提取、路径遍历、符号链接、强制和回滚保护。由 skills.install.allowUploadedArchives 控制；普通 ClawHub 安装不需要此设置。
• Gateway 支持的技能依赖安装（skills.install、onboarding 和 Skills 设置 UI）在执行安装器元数据前运行内置危险代码扫描器。critical 发现默认阻止，除非调用方显式设置危险覆盖；suspicious 发现仅警告。
• openclaw skills install <slug> 不同：它从 ClawHub 下载技能文件夹到工作区，或通过 --global 下载到共享 managed/本地技能，不走上述安装器元数据路径。Git 和本地目录安装将可信的 SKILL.md 目录复制到同一技能根目录，但不被 openclaw skills update 跟踪。
• skills.entries.*.env 和 skills.entries.*.apiKey 将密钥注入到该 agent 轮次的宿主进程（不是沙箱）。请勿在提示词和日志中暴露密钥。

更广泛的威胁模型和清单参见 Security。

SKILL.md 格式

SKILL.md 必须至少包含：

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

OpenClaw 遵循 AgentSkills 规范的布局/意图。内嵌 agent 使用的解析器只支持单行 frontmatter 键；metadata 应为单行 JSON 对象。在说明中用 {baseDir} 引用技能文件夹路径。

可选 frontmatter 键

homepage string

URL，在 macOS Skills UI 中显示为"Website"。也可通过 metadata.openclaw.homepage 支持。

user-invocable boolean

为 true 时，技能作为用户斜杠命令暴露。

disable-model-invocation boolean

为 true 时，OpenClaw 将技能的说明从 agent 的正常提示词中移除。技能仍安装，当 user-invocable 也为 true 时仍可作为斜杠命令显式运行。

command-dispatch

设置为 tool 时，斜杠命令绕过模型，直接分发到工具。

command-tool string

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

command-arg-mode

用于工具分发时，将原始参数字符串转发给工具（不做核心解析）。工具被调用时携带参数：{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

技能门控（加载时过滤）

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

---
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 boolean

为 true 时，始终包含该技能（跳过其他门控）。

emoji string

macOS Skills UI 使用的可选 Emoji。

homepage string

macOS Skills UI 中显示为"Website"的可选 URL。

os

可选平台列表。设置后技能只在该操作系统上生效。

requires.bins string[]

列表中的每个可执行文件必须在 PATH 中存在。

requires.anyBins string[]

列表中的至少一个可执行文件必须在 PATH 中存在。

requires.env string[]

环境变量必须存在或在配置中提供。

requires.config string[]

openclaw.json 路径列表，每个必须为 truthy。

primaryEnv string

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

install object[]

macOS Skills UI 使用的可选安装器规格数组（brew/node/go/uv/download）。

如果 metadata.openclaw 不存在，技能始终符合条件（除非在配置中禁用，或受 skills.allowBundled 限制）。

INFO

旧版 metadata.clawdbot 在没有 metadata.openclaw 时仍被接受，因此旧安装的技能保留依赖门控和安装器提示。新建和更新的技能应使用 metadata.openclaw。

沙箱注意事项：

• requires.bins 在技能加载时检查宿主环境。
• 如果 agent 处于沙箱中，该二进制文件也必须存在于容器内部。通过 agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装。setupCommand 在容器创建后运行一次。包安装还需要网络出站、可写根文件系统和沙箱中的 root 用户。

安装器规格

---
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 可用时优先 brew，否则 node）。
- 如果所有安装器都是 `download`，OpenClaw 列出每一条让你看到可用的制品。
- 安装器规格可包含 `os: ["darwin"|"linux"|"win32"]` 按平台过滤选项。
- Node 安装使用 `skills.install.nodeManager`（默认：npm；选项：npm/pnpm/yarn/bun）。这只影响**技能安装**；Gateway 运行时应仍使用 Node。
- Gateway 支持的安装器选择是偏好驱动：当安装规格混合种类时，OpenClaw 优先 Homebrew（当 `skills.install.preferBrew` 启用且 `brew` 存在时），然后 `uv`，然后配置的 node manager，然后其他回退如 `go` 或 `download`。
- 如果每个安装规格都是 `download`，OpenClaw 展示所有下载选项而不折叠为一个首选安装器。

每个安装器的细节

- **Homebrew 安装**：OpenClaw 不会自动安装 Homebrew 或将 brew formula 翻译成系统包管理器命令。在 Linux 容器中没有 `brew` 时，onboarding 隐藏 brew 专属依赖安装器；使用自定义镜像或手动安装依赖后再启用该技能。
- **Go 安装**：如果缺少 `go` 且 `brew` 可用，Gateway 通过 Homebrew 先安装 Go，并在可能时将 `GOBIN` 设置为 Homebrew 的 `bin`。
- **Download 安装**：`url`（必填）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（检测到压缩包时默认自动）、`stripComponents`、`targetDir`（默认：`~/.openclaw/tools/<skillKey>`）。

怎么用 openclaw.json 覆盖技能配置

内置和 managed 技能可以在 ~/.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 },
    },
  },
}

enabled boolean

false 禁用技能，即使它是内置或已安装的。内置 coding-agent 技能是 opt-in：设置 skills.entries.coding-agent.enabled: true 后才能暴露给 agent，并确保 claude、codex、opencode 或 pi 之一已安装并通过认证。

apiKey

声明了 metadata.openclaw.primaryEnv 的技能的便捷配置。支持纯文本字符串或 SecretRef。

env Record<string, string>

只有当变量尚未在进程中设置时才注入。

config object

可选容器，用于自定义每技能字段。自定义键必须放在这里。

allowBundled string[]

仅针对内置技能的可选白名单。设置后只有白名单中的内置技能符合条件（managed/工作区技能不受影响）。

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

INFO

对于 OpenClaw 内的标准图像生成/编辑，使用核心 image_generate 工具配合 agents.defaults.imageGenerationModel，而不是内置技能。这里的技能示例适用于自定义或第三方工作流。如需原生图像分析，使用 image 工具配合 agents.defaults.imageModel。如果选择 openai/*、google/*、fal/* 或其他特定提供商的图像模型，请确保也添加该提供商的认证/API key。

环境注入（每次 Agent 运行）

当 agent 运行开始时，OpenClaw：

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

环境注入作用于该 agent 运行，不是全局 shell 环境。

对于内置的 claude-cli 后端，OpenClaw 还将相同的符合条件的快照作为临时 Claude Code 插件实例化，并通过 --plugin-dir 传递。Claude Code 可以使用其原生技能解析器，而 OpenClaw 仍拥有优先级、per-agent allowlists、门控和 skills.entries.* env/API key 注入。其他 CLI 后端仅使用提示词目录。

技能快照与刷新

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

技能在两种情况下可以会话中刷新：

• 技能 watcher 启用。
• 新的符合条件的远程节点出现。

可将此视为热重载：刷新后的列表在下一次 agent 轮次时生效。如果该会话的有效 agent 技能 allowlist 发生变化，OpenClaw 会刷新快照使可见技能与当前 agent 保持一致。

技能 watcher

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

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

使用 allowSymlinkTargets 处理包含符号链接的工作区、项目智能体或额外目录布局，例如 <workspace>/skills/manager -> ~/Projects/manager/skills。Managed ~/.openclaw/skills 和个人 ~/.agents/skills 默认可以跟随来自本地技能管理器的技能目录符号链接，但目标列表在 realpath 解析后仍应匹配，并在配置时保持狭窄。

远程 macOS 节点（Linux Gateway）

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

这依赖于节点上报其命令支持和通过 system.which 或 system.run 进行的 bin 探测。离线节点不使远程专属技能可见。如果已连接的节点停止响应 bin 探测，OpenClaw 清除其缓存的 bin 匹配，以便 agent 不再看到当前无法在该节点运行的技能。

Token 影响

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

• 基础开销（只有 ≥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，因此 97 字符 ≈ 24 token 每个技能，加上你实际的字段长度。

Managed 技能生命周期

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

配置参考

完整配置 schema 参见 Skills config。

寻找更多技能？

浏览 https://clawhub.ai。

相关链接

• ClawHub - 公共技能注册中心
• 创建技能 - 构建自定义技能
• 插件 - 插件系统概览
• Skill Workshop 插件 - 从 agent 工作生成技能
• Skills 配置 - 技能配置参考
• 斜杠命令 - 所有可用斜杠命令

常见问题

技能加载优先级怎么覆盖？同名技能在 workspace 和 managed 里都有，哪个生效？

工作区技能（<workspace>/skills）优先级最高，始终覆盖 managed 技能（~/.openclaw/skills）中的同名版本。如果项目智能体或个人智能体目录中存在同名技能，也按优先级顺序：workspace > .agents/skills > ~/.agents/skills > ~/.openclaw/skills。可用 openclaw skills list（如果该命令存在）或检查 skills.load 配置确认当前加载的路径。

Agent Allowlist 和技能门控 (metadata.openclaw.requires) 有什么区别？

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

插件自带的技能怎么启用？

插件在 openclaw.plugin.json 中声明其 skills 目录路径。插件启用后，这些技能自动合并到技能加载系统中，优先级与 skills.load.extraDirs 相同。如果插件技能名称与内置或 managed 技能冲突，内置/managed 版本优先。可以通过插件配置条目的 metadata.openclaw.requires.config 控制加载条件。详细参考 Plugins。