OpenClaw skills 技能配置完全指南：打造你的专属 AI 助手

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

OpenClaw 使用 AgentSkills 兼容的技能文件夹结构来扩展 AI 助手的能力。每个技能本质上是一个包含 SKILL.md 文件的目录，这个文件定义了：

简单来说，技能就是教你的 AI 助手”如何做某件事”的说明书。

OpenClaw 从三个位置加载技能，优先级从高到低：

1. 
 
   
   
    
    
   /skills ← 你的工作区技能（最高优先级） 2. ~/.openclaw/skills ← 本地管理技能 3. bundled skills ← 安装包内置技能（最低优先级）

这意味着什么？

额外技能目录：你还可以在配置中添加更多技能目录：

// ~/.openclaw/openclaw.json { skills: { load: { extraDirs: ["~/Projects/my-skills", "~/Projects/shared-skills"] } } }

每个技能的核心是 SKILL.md 文件。它由两部分组成：

--- name: my-custom-skill description: 我的自定义技能描述 homepage: https://example.com metadata: { "openclaw": { "emoji": "🔧", "requires": { "bins": ["node", "npm"], "env": ["MY_API_KEY"], "config": ["browser.enabled"] }, "primaryEnv": "MY_API_KEY", "os": ["linux", "darwin"] } } ---

关键字段说明：

字段说明 name 技能名称（唯一标识，建议用短横线分隔） description 技能描述（会显示在技能列表中） homepage 技能主页 URL（可选） metadata.openclaw.emoji 技能图标 emoji metadata.openclaw.requires.bins 需要的二进制文件（必须在 PATH 中） metadata.openclaw.requires.env 需要的环境变量 metadata.openclaw.requires.config 需要的配置项（必须为 true） metadata.openclaw.primaryEnv 主环境变量名（用于 apiKey 配置） metadata.openclaw.os 支持的平台（darwin/linux/win32）

Frontmatter 之后是技能的详细指令，告诉 AI 如何执行任务：

# 技能名称 触发条件 当用户请求 XXX 时，执行以下步骤： 1. 第一步做什么 2. 第二步做什么 3. ... 注意事项 - 安全提示 - 边界条件 - 错误处理

**实践：

技能的全局配置在 ~/.openclaw/openclaw.json 的 skills 字段下：

{ skills: { // 内置技能白名单（可选） allowBundled: ["gemini", "peekaboo", "sag"], // 技能加载配置 load: { extraDirs: ["~/Projects/my-skills"], watch: true, // 自动监听技能文件变化 watchDebounceMs: 250 // 防抖时间（毫秒） }, // 安装器配置 install: { preferBrew: true, // 优先使用 Homebrew nodeManager: "npm" // Node 包管理器（npm/pnpm/yarn/bun） }, // 单个技能配置 entries: { "my-custom-skill": { enabled: true, apiKey: "sk-xxxxxxxx", // 或者使用 SecretRef env: { MY_API_KEY: "xxxxx", CUSTOM_VAR: "value" }, config: { customEndpoint: "https://api.example.com" } }, "builtin-skill": { enabled: false // 禁用内置技能 } } } }

方式一：明文（不推荐用于生产环境）

apiKey: "sk-xxxxxxxx"

方式二：SecretRef（推荐）

apiKey: { source: "env", provider: "default", id: "MY_API_KEY" }

OpenClaw 会在加载时根据技能元数据过滤技能，只有满足所有条件的技能才会被激活。

条件类型字段说明二进制文件 requires.bins 所有列出的二进制必须存在于 PATH 任意二进制 requires.anyBins 至少一个二进制存在即可环境变量 requires.env 环境变量必须存在（或通过 config 提供）配置项 requires.config openclaw.json 中的配置必须为 true 操作系统 requires.os 仅在指定平台生效强制启用 always: true 跳过所有 gating 检查

--- name: macos-automation description: macOS 自动化技能 metadata: { "openclaw": { "requires": { "bins": ["osascript"], "os": ["darwin"] } } } ---

这个技能只在 macOS 上激活，因为：

需要 osascript 二进制（macOS 特有）
os 限制为 darwin

ClawHub 是 OpenClaw 的官方技能市场：https://clawhub.com

# 安装技能 clawhub install 
 
   
   
    
    
   # 更新所有技能 clawhub update --all # 同步技能（扫描 + 发布更新） clawhub sync --all

# 创建技能目录 mkdir -p ~/.openclaw/workspace/skills/hello-world # 创建 SKILL.md cat > ~/.openclaw/workspace/skills/hello-world/SKILL.md << 'EOF' --- name: hello-world description: 一个简单的问候技能 --- # Hello World 当用户说"你好"或"打招呼"时，回复： "你好！我是你的 AI 助手，有什么可以帮你的吗？" EOF

cd ~/.openclaw/workspace/skills git clone https://github.com/username/my-skill.git

mkdir -p ~/.openclaw/workspace/skills/weather-query cd ~/.openclaw/workspace/skills/weather-query

--- name: weather-query description: 查询实时天气和预报 homepage: https://wttr.in metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } } --- # 天气查询技能 功能 使用 wttr.in 服务查询全球任意城市的天气信息。 使用方法 当用户询问天气时： 1. 提取用户提到的城市名 2. 如果未指定城市，使用用户所在时区推断（或询问） 3. 执行命令：`curl wttr.in/ 
 
   
   <城市名>
    
    
   ?format=%C+%t+%h+%w` 4. 将结果翻译成自然语言回复 输出格式示例 - 晴天：☀️ 北京 晴 25°C 湿度 45% 风速 10km/h - 多云：☁️ 上海 多云 22°C 湿度 60% 风速 5km/h - 雨天：🌧️ 广州 小雨 20°C 湿度 85% 风速 15km/h 注意事项 - 城市名使用拼音或英文（wttr.in 不支持中文城市名） - 如果查询失败，告知用户并重试一次 - 可以提供 3 天预报：`curl wttr.in/ 
  
    
    <城市名>
      +3`

如果技能需要 API Key，在 openclaw.json 中添加：

{ skills: { entries: { "weather-query": { enabled: true, env: { WEATHER_API_KEY: "your-key-here" } } } } }

# 重启 Gateway 或等待自动刷新 openclaw gateway restart # 测试技能 openclaw agent --message "北京今天天气怎么样？"

在多 Agent 设置中，每个 Agent 有自己的工作区：

Agent 专属技能：放在 /skills
共享技能：放在 ~/.openclaw/skills（所有 Agent 可见）

技能冲突处理：

如果同名技能存在于多个位置，优先级为：

Agent 工作区 > 本地管理 (~/.openclaw/skills) > 内置技能

⚠️ 重要：第三方技能视为不可信代码

审查技能代码：安装前仔细阅读 SKILL.md 和任何脚本
沙箱运行：对涉及外部输入的技能使用沙箱模式
最小权限：只授予技能必要的权限和环境变量
敏感操作确认：涉及删除、外部写入、数据导出的操作必须人工确认

 } } } }

技能列表会注入到系统提示中，产生固定的 Token 开销：

计算公式：

总字符数 = 195 + Σ(97 + name 长度 + description 长度 + location 长度) Token 估算 ≈ 总字符数 / 4

示例：10 个技能，平均名称 20 字符、描述 50 字符、路径 80 字符

总字符数 = 195 + 10 × (97 + 20 + 50 + 80) = 195 + 2470 = 2665 Token 估算 ≈ 2665 / 4 ≈ 666 tokens

优化建议：

保持技能描述简洁（但要有信息量）
禁用不常用的技能
使用 allowBundled 白名单限制内置技能

检查 SKILL.md 的 YAML frontmatter 格式是否正确
确认 gating 条件是否满足（二进制、环境变量、配置项）
查看 Gateway 日志：openclaw gateway logs
尝试重启 Gateway：openclaw gateway restart

检查所需的环境变量是否正确配置
确认二进制文件在 PATH 中：which
查看技能指令是否有语法错误
检查沙箱配置（如果启用了沙箱）

确认修改的是正确的配置文件（~/.openclaw/openclaw.json）
JSON5 格式是否正确（注意逗号、引号）
配置变更需要新会话才会生效（技能快照在会话开始时创建）

在技能指令中，可以用 {baseDir} 表示技能文件夹的绝对路径：

运行脚本：`{baseDir}/scripts/run.sh`

在 frontmatter 中定义安装器，让用户可以一键安装依赖：

--- name: gemini-cli description: Gemini CLI 工具 metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "gemini-cli", "bins": ["gemini"], "label": "Install Gemini CLI (brew)" } ] } } ---

通过 frontmatter 控制技能是否对用户可见：

--- name: admin-task description: 管理员任务 user-invocable: false // 用户不能直接调用 ---

--- name: quick-command command-dispatch: tool command-tool: system_exec command-arg-mode: raw ---

OpenClaw 的技能系统是一个强大而灵活的扩展机制：

✅ 三层加载：工作区 > 本地 > 内置，灵活覆盖
✅ Gating 机制：根据环境自动过滤技能
✅ ClawHub 市场：一键安装社区技能
✅ 安全沙箱：隔离风险操作
✅ 多 Agent 支持：专属技能 + 共享技能

下一步行动：

参考资料：

本文基于 OpenClaw 2026.3.12 版本编写，配置格式可能随版本更新而变化。

OpenClaw skills 技能配置完全指南：打造你的专属 AI 助手

相关推荐