OpenClaw 实战指南

Appearance

9.4 技能配置优先级 ​

上一节你学会了创建自己的 Skill。但有个问题：你安装了 ClawHub 上的 tavily-search，又在工作区写了一个同名的 Skill。OpenClaw 会用哪个？

想象一下这个场景：

公司前台接到一个电话。

“找销售部”——前台转给销售 “找技术支持”——前台转给技术

前台就是路由——根据规则，把消息送到正确的地方。

Skills 的加载也是这样——优先级规则决定用哪个。

这一节，我们用10分钟，理解 Skills 的三级优先级。

三级加载位置 ​

OpenClaw 从三个位置加载 Skills：

层级路径优先级用途
工作区 Skills<workspace>/skills最高当前智能体专属
本地 Skills~/.openclaw/skills中多智能体共享
内置 Skills安装包自带最低基础功能

1. 工作区 Skills（最高优先级） ​

路径：<workspace>/skills

  • 当前工作区独有的 Skills
  • 仅对当前智能体可见
  • 会覆盖其他位置的同名 Skills

2. 本地 Skills（中等优先级） ​

路径：~/.openclaw/skills

  • 当前机器上所有智能体共享的 Skills
  • 可以用来覆盖内置 Skills 的某些行为
  • 适合安装通用的第三方 Skills

3. 内置 Skills（最低优先级） ​

  • OpenClaw 安装包自带的 Skills
  • 跟随版本更新
  • 可以被本地 Skills 覆盖

优先级规则 ​

当 Skills 名称冲突时，优先级为：

优先级来源路径说明
1（最高）workspace<workspace>/skills工作区专属，覆盖一切
2local~/.openclaw/skills本地共享，覆盖内置
3（最低）bundled安装包自带基础功能，可被覆盖
<workspace>/skills（最高）
    ↓
~/.openclaw/skills
    ↓
内置 Skills（最低）

示例：

假设三个位置都有一个叫 weather 的 Skill：

  • 工作区的 weather 会生效
  • ~/.openclaw/skills 的 weather 被忽略
  • 内置的 weather 被忽略

对话示例：优先级生效 ​

你在三个地方都定义了 greeting 技能：

内置版本（bundled）：

markdown
你是友好的助手，用简洁的方式问候用户。

本地版本（local）：

markdown
你是专业的工作助手，问候时加上当前时间。

工作区版本（workspace）：

markdown
你是创意写作助手，用诗意的方式问候。
用户：你好

机器人：晨曦微露，新的一天如诗篇般展开。我是你的创意伙伴，愿与你在文字的世界里同行。

可以看到，工作区版本胜出——因为它优先级最高。

试一试：查看 Skills 来源 ​

使用 CLI 查看每个 Skill 的来源：

bash
openclaw skills list

输出示例：

Skills:
- weather          (workspace)   - Get weather information
- tavily-search    (local)       - Web search via Tavily
- browser          (bundled)     - Browser automation
- bash             (bundled)     - Execute shell commands

括号里的就是来源：

标记含义
workspace工作区 Skills
local托管/本地 Skills
bundled内置 Skills

额外加载目录 ​

你还可以在配置中添加额外的 Skills 目录：

编辑 ~/.openclaw/openclaw.json：

json5
{
  skills: {
    load: {
      extraDirs: [
        "~/Projects/agent-scripts/skills",
        "~/Projects/oss/some-skill-pack/skills"
      ]
    }
  }
}

这些额外目录的优先级低于内置 Skills。

覆盖内置 Skill ​

如果你想修改内置 Skill 的行为，可以：

方法 1：在工作区创建同名 Skill

bash
mkdir -p ~/.openclaw/workspace/skills/browser
cat > ~/.openclaw/workspace/skills/browser/SKILL.md << 'EOF'
---
name: browser
description: Custom browser automation rules
---

# Custom Browser Skill

[你的自定义说明]
EOF

方法 2：在本地 Skills 目录创建

bash
mkdir -p ~/.openclaw/skills/browser
# 同上创建 SKILL.md

工作区版本优先级更高，但如果想多个智能体共享，用本地 Skills 更合适。

禁用特定 Skill ​

如果某个 Skill 有问题，可以在配置中禁用它：

json5
{
  skills: {
    entries: {
      "some-skill": {
        enabled: false
      }
    }
  }
}

或者使用白名单模式，只允许特定的内置 Skills：

json5
{
  skills: {
    allowBundled: ["browser", "bash", "edit"]
  }
}

allowBundled 只对内置 Skills 生效，工作区和本地 Skills 不受影响。

配置环境变量和 API Key ​

你可以为每个 Skill 单独配置环境变量：

json5
{
  skills: {
    entries: {
      "tavily-search": {
        enabled: true,
        apiKey: "your-api-key-here",
        env: {
          TAVILY_API_KEY: "your-api-key-here"
        }
      },
      "gemini": {
        enabled: true,
        config: {
          model: "gemini-pro",
          endpoint: "https://custom.endpoint.com"
        }
      }
    }
  }
}
配置项说明
apiKey便捷字段，用于声明了 primaryEnv 的 Skills
env注入环境变量（仅在变量未设置时生效）
config自定义配置项

故障排查 ​

Skill 没有生效 ​

检查清单：

  • [ ] Skill 文件名是否为 SKILL.md
  • [ ] SKILL.md 是否在正确的目录下
  • [ ] frontmatter 格式是否正确（name 和 description 必填）
  • [ ] 是否有更高优先级的同名 Skill 覆盖了它

查看实际加载的 Skill ​

bash
# 查看所有 Skill 及其来源
openclaw skills list

# 查看特定 Skill 的详细信息
openclaw skills show <skill-name>

环境变量没有注入 ​

检查项操作
配置格式确认 entries 中的 Skill 名称正确
优先级检查系统环境变量是否已设置（会覆盖配置）
重启修改配置后重启 Agent

内置 Skill 被意外覆盖 ​

bash
# 检查是否有同名 Skill
openclaw skills list | grep <skill-name>

# 如果有 local 或 workspace 版本，删除或重命名
rm ~/.openclaw/skills/<skill-name>
# 或
rm ~/.openclaw/workspace/skills/<skill-name>

调试命令汇总 ​

bash
# 查看所有 Skill 来源
openclaw skills list

# 查看配置是否生效
openclaw config validate

# 查看 Agent 日志
openclaw logs --follow

这一节，你做了什么 ​

壂级路径优先级用途
工作区 Skills<workspace>/skills最高当前智能体专属
本地 Skills~/.openclaw/skills中多智能体共享
内置 Skills安装包自带最低基础功能

关键要点：

  • 同名 Skills，高优先级覆盖低优先级

  • 可以用 enabled: false 禁用特定 Skill

  • 可以用 allowBundled 限制内置 Skills 白名单

  • 通过 entries 为每个 Skill 配置独立的环境变量

  • 用 openclaw skills list 查看 Skills 来源

  • 用 openclaw skills show <name> 查看特定 Skill 详情

  • 修改配置后重启 Agent 才生效

  • 遇到同名冲突时，删除优先级较低的版本

  • 为每个 Skill 单独配置 API Key 和环境变量

下一节 ​

Skills 能力强大，但也带来了安全风险。

下一节，我们来学习 Skills 安全审计。

基于 MIT 许可发布

Copyright © 2025 Gleam2Torch