OpenClaw Skills安全使用及设计原理

一、什么是 Skills

Skills（技能） 是 OpenClaw 的核心扩展机制。它们是 Markdown 格式的指令文件，告诉 AI 代理「如何」以及「何时」使用工具。每个 Skill 是一个包含 SKILL.md 文件的目录，带有 YAML 前置元数据和 Markdown 正文。

简单说：Skills = 可复用的 AI 使用说明书。它们教会代理执行特定任务，而无需用户每次重复告诉代理怎么做。

核心哲学

用户请求 → 代理理解意图 → Skills 提供上下文 → 代理调用工具 → 完成任务

Skills 不是独立运行的「插件」或「应用」，而是注入到 AI 模型系统提示词中的指令块，让代理知道面对什么场景该用什么工具、怎么用。

二、SKILL.md 格式详解

2.1 基本结构——最简单的一个例子

---
name: hello-world
description: 打个招呼
---

当用户让你打招呼的时候，用 exec 工具执行：
echo "你好！"

就这么多。上面是「头」（metadata），下面是「身体」（干活说明）。

2.2 「头」（metadata）前置元数据字段

2.3 什么是「条件激活」（Gating）

就是你可以在 Skill 头上写：我只有在某某条件满足时才干活。

metadata:
  { "openclaw": { "requires": { "bins": ["ffmpeg"] } } }

这句话的意思是：这个 Skill 只有在电脑上装了 ffmpeg 这个软件的时候才会激活。没装就不加载，省得 AI 乱捣鼓。

可以设置的条件：

2.4 {baseDir} 是啥？

就是「我自己的文件夹在哪」这个意思。

比如你的 Skill 文件夹结构是这样的：

skills/my-tool/SKILL.md
skills/my-tool/scripts/run.sh

如果不用 {baseDir}，你得写死路径：

运行 /Users/你/.../skills/my-tool/scripts/run.sh 这个脚本

换了电脑就废了。

用 {baseDir}：

运行 {baseDir}/scripts/run.sh 这个脚本

不管装在哪，OpenClaw 都会自动换成正确的路径。换个地方也能用，分享给别人也能用。

三、整体设计逻辑

3.1 分层加载体系

OpenClaw 按优先级从高到低加载 Skills：

同名覆盖规则：当同一个 Skill 名称出现在多个位置时，优先级高的覆盖优先级低的。这允许用户在工作区层级覆盖内置或共享的 Skill。

3.2 加载与注入流程

用户发起会话
    ↓
1. 解析会话所属代理的 Skill 可见列表（按 allowlist + gating 过滤）
    ↓
2. 对每个可见 Skill，检查其 gating 条件：
   - 是否需要特定环境变量？
   - 是否需要特定二进制工具？
   - 是否需要特定配置项？
   - 是否匹配当前操作系统？
    ↓
3. 符合条件的 Skill 被编译为 XML 块
    ↓
4. 该 XML 块注入到 AI 模型的系统提示词中
    ↓
5. 模型根据这些指令，在合适的时候调用对应工具

3.3 快照机制（Snapshots）

• 代理会话启动时，OpenClaw 对当前可见的 Skills 拍快照

• 快照在整个会话生命周期内复用，不会在每次对话都重新计算

• 以下情况会触发 Skills 刷新：

  • 文件监控器检测到 SKILL.md 变化

  • 新的远程节点连接

  • 代理的 allowlist 发生变化

3.4 环境变量注入

当代理运行开始时：

1. 解析有效 Skill 列表，应用 gating 规则、allowlist 和配置覆盖

2. 将 skills.entries.<key>.env 和 skills.entries.<key>.apiKey 注入到 process.env

3. 将符合条件的 Skills 编译为 XML 块注入系统提示词

4. 运行结束后恢复原始环境

⚠️ 重要安全限制：环境变量注入仅在**宿主机（host）**生效，不会传递到沙箱中。沙箱中的代理需要单独通过 agents.defaults.sandbox.docker.env配置。

四、安全体系详解

OpenClaw 的 Skills 安全体系是多层防御结构，从多个维度限制风险。

4.1 条件激活（Gating）——入口安全

Gating 是 Skills 的第一道安全防线。一个 Skill 只有在所有条件都满足时才会被加载到代理的提示词中。

---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---

可用的 Gating 条件：

安全意义：即使 Skill 文件存在于磁盘上，如果依赖的二进制工具未安装或配置不完整，它也不会生效。这避免了在缺少安全环境时运行危险指令。

4.2 路径隔离（Path Containment）——文件系统安全

OpenClaw 对 Skill 的加载路径有严格限制：

• 工作区、项目代理和额外目录中的 Skill 发现只接受**解析后的真实路径（realpath）**仍然在配置根目录内的目录

• 即使使用符号链接，每个 SKILL.md 的真实路径也必须在其解析后的 Skill 目录内部

• 如需允许符号链接指向外部目录，必须在 skills.load.allowSymlinkTargets 中显式声明信任的目录

⚠️ 始终使用信任列表，allowSymlinkTargets 应保持范围狭窄，不要设置为 ~ 或 ~/Projects 这样的宽泛路径。

4.3 代理可见性控制（Allowlist）——访问控制

Skill 的位置（优先级）和可见性（哪个代理可以使用）是独立的控制维度。

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // 共享基线
    },
    list: [
      { id: "writer" }, // 继承 github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换所有默认值
      { id: "locked-down", skills: [] }, // 没有任何 Skill
    ],
  },
}

规则：

• 省略 agents.defaults.skills → 所有 Skills 对所有代理默认无限制

• 省略 agents.list[].skills → 继承 agents.defaults.skills

• 设置 agents.list[].skills: [] → 该代理无任何 Skill

• 非空的 agents.list[].skills 列表是最终集合——不会与默认值合并

4.4 执行审批（Exec Approvals）——命令执行安全

当 Skill 需要执行宿主机命令时，OpenClaw 提供多层审批机制：

• 白名单支持通配符模式和参数模式匹配

• 已审批的命令会被绑定具体的执行上下文（cwd、argv、环境变量）

• 审批记录绑定文件操作数，如果文件在执行前发生变化，命令将被拒绝

• autoAllowSkills 可以将已知 Skill 引用的可执行文件自动加入白名单

4.5 沙箱隔离（Sandboxing）——运行环境隔离

OpenClaw 支持将工具执行放入沙箱中，减少安全影响面：

沙箱模式：

• off：不使用沙箱

• non-main：仅非主会话使用沙箱（推荐，日常聊天在宿主机）

• all：所有会话都使用沙箱

沙箱范围：

• agent：每个代理一个容器（默认）

• session：每个会话一个容器

• shared：所有沙箱化会话共享一个容器

⚠️ 重要：沙箱不是完美的安全边界，但能有效限制工具执行的文件系统和进程访问范围。

4.6 安全扫描（Security Scanning）

从 ClawHub 安装的 Skills 会经过多层安全检查：

1. ClawHub 页面：安装前展示最新的安全扫描状态

2. VirusTotal：病毒扫描

3. ClawScan：静态分析

4. 内置危险代码扫描器：在安装元数据执行前运行扫描

   • critical（严重）发现 → 默认阻止安装

   • suspicious（可疑）发现 → 仅给出警告

验证命令：

openclaw skills verify <slug>
openclaw skills verify <slug> --card    # 打印 Skill Card

4.7 Skill Workshop —— 审核机制

Skill Workshop 是 OpenClaw 的受控审核路径。Agent 不能直接写 SKILL.md，必须先创建提案（Proposal）：

流程：create/update → pending → revise → apply → applied
                                  → reject  → rejected
                                  → quarantine → quarantined

• 提案在被批准（apply）之前不生效

• 创建新 Skill 时，如果目标名称已存在则失败（不覆盖）

• 更新提案绑定当前目标文件的哈希，如果文件在期间被修改则失效

• Apply 操作会重新运行安全扫描

五、一张图看明白完整安全体系

你 👩
  │ 审核、审批、配置
  ▼
Gateway（管家总部）──── Skill Workshop（审核室）
  │
  ▼
Skills 系统
  ├── Gating：条件够了才出来
  ├── Allowlist：谁才能用
  └── Env 注入：悄悄塞密钥
  │
  ▼
工具执行层
  ├── Exec 审批：跑命令要同意
  ├── 沙箱隔离：关笼子里跑
  └── 路径保护：别瞎链接

每一层都不是无敌的，但几层叠在一起就很稳了。

记住三句话就够了：

1️⃣ 谁可以用 — Allowlist 管 2️⃣ 能用什么 — Gating + 审批管 3️⃣ 在哪跑 — 沙箱管