跳转至

创建技能

技能教智能体如何以及何时使用工具。每个技能是一个包含 SKILL.md 文件的目录,内含 YAML 前置元数据和 Markdown 指令。OpenClaw 会按定义的优先级顺序从多个根目录加载技能。

创建你的第一个技能

1. 创建技能目录

技能存放在你的工作区 skills/ 文件夹中:

mkdir -p ~/.openclaw/workspace/skills/hello-world

你可以将技能分组放在子文件夹中以便组织——技能仍以 SKILL.md 前置元数据中的 name 命名,而非文件夹路径:

mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world

2. 编写 SKILL.md

前置元数据定义元信息;正文部分为智能体提供指令。

---
name: hello-world
description: A simple skill that prints a greeting.
---

# Hello World

When the user asks for a greeting, use the `exec` tool to run:

```bash
echo "Hello from your custom skill!"
```

命名规则:

  • name 使用小写字母、数字和连字符。
  • 保持目录名与前置元数据中的 name 一致。
  • description 会展示给智能体,并用于斜杠命令发现——请保持在一行且不超过 160 个字符。

3. 确认技能已加载

openclaw skills list

默认情况下,OpenClaw 会监视技能根目录下的 SKILL.md 文件。如果监视器已禁用,或者你正在继续既有会话,请启动一个新会话,以便智能体获得刷新后的列表:

# From chat — archive current session and start fresh
/new

# Or restart the gateway
openclaw gateway restart

4. 测试它

openclaw agent --message "give me a greeting"

或者打开聊天并直接向智能体提出请求。使用 /skill hello-world 可按名称显式调用该技能。

在共享 Gateway 上创建个人技能

对于应跟随你已登录资料而非属于某个智能体工作区的技能,请使用 Plugins → Skills → My skills。在那里创建或导入 SKILL.md 包,然后查看已保存的修订版本和激活结果。你不需要主机 shell 访问权限,也无需编辑共享 Gateway 设置的权限。

你也可以让智能体创建或改进个人技能。它的 skill_workshop 工具使用 Gateway 的授权库服务;它不会直接写入受管修订目录。结果会指明所发布的修订版本,并说明会话何时可以使用该修订。

请明确要求在当前会话中使用新修订,或与团队分享。

单一管理员默认仍采用上述工作区工作流。同一操作者的额外渠道身份不会将个人安装变为团队设置。关于所有权、共享、存储和会话行为,请参阅个人技能与修订。

SKILL.md 参考

必填字段

字段 描述
name 使用小写字母、数字和连字符的唯一 slug
description 一行描述,展示给智能体并显示在发现输出中

可选前置元数据键

字段 默认值 描述
user-invocable true 将技能公开为用户斜杠命令
disable-model-invocation false 将技能从智能体的系统提示中排除(仍可通过 /skill 运行)
command-dispatch — 设置为 tool 可将斜杠命令直接路由到工具,绕过模型
command-tool — 在设置 command-dispatch: tool 时要调用的工具名称
command-arg-mode raw 对于工具分发,将原始参数字符串转发给工具
homepage — 在 macOS 技能界面中显示为“网站”的 URL

有关门控字段(requires.bins、requires.env 等),请参阅技能 — 门控。

使用 {baseDir}

引用技能目录内的文件而无需硬编码路径——智能体会将 {baseDir} 解析为技能自身目录:

Run the helper script at `{baseDir}/scripts/run.sh`.

添加条件激活

为你的技能设置门控,使其仅在依赖项可用时加载:

---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---
门控选项
键 描述
requires.bins 所有二进制文件必须存在于 PATH 中
requires.anyBins 至少一个二进制文件必须存在于 PATH 中
requires.env 每个环境变量必须存在于进程或配置中
requires.config 每个 openclaw.json 路径必须为真值
os 平台过滤器:["darwin"]、["linux"]、["win32"]
always 即使 requires.* 检查失败,在兼容操作系统上也包含

完整参考:技能 — 门控。

环境与 API 密钥

在 openclaw.json 中将 API 密钥绑定到技能条目:

{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}

该密钥仅在该次智能体轮次注入宿主进程,不会到达沙箱——请参阅沙箱环境变量。

习得技能(Skill Workshop)

智能体还会通过Skill Workshop编写自己的技能。这些习得技能会立即生效,并保留之前的版本,因此任何更改都可以撤销。你可以从 CLI 检查和管理它们:

openclaw skills workshop list
openclaw skills workshop changes
openclaw skills workshop show hello-world
openclaw skills workshop archive hello-world --reason "Replaced by greeting"
openclaw skills workshop restore hello-world

查看 openclaw skills workshop 了解所有选项。

发布到 ClawHub

所有者是 ClawHub 发布者句柄,例如 @alice 或 @your-org。 你的账户拥有一个个人所有者。组织所有者可以拥有具有 owner、admin 或 publisher 角色的成员;这三种角色都可以发布。请选择你的 个人所有者,或选择一个你拥有发布者访问权限的组织。

1. 确保你的 SKILL.md 已完整

确保 name、description 以及任何 metadata.openclaw 门控字段 已设置。如果你有项目页面,请添加 homepage URL。

2. 安装独立的 ClawHub CLI 并登录

npm i -g clawhub
clawhub login

3. 发布

clawhub skill publish ./path/to/hello-world

添加 --version <version> 或 --owner <owner> 以覆盖推断的 版本,或在特定所有者下发布。请参阅 ClawHub — 发布 和 ClawHub CLI 了解完整流程、所有者作用域以及其他 维护命令(clawhub sync、clawhub skill rename 等)。

最佳实践

Tip

  • 保持简洁 — 指示模型做什么,而不是如何成为 AI。
  • 安全第一 — 如果你的技能使用 exec,请确保提示词不允许 来自不受信任输入的任意命令注入。
  • 本地测试 — 在分享之前使用 openclaw agent --message "..."。
  • 使用 ClawHub — 在从零开始构建之前,先在 clawhub.ai 上浏览社区技能。

技能参考

加载顺序、门控、允许列表以及 SKILL.md 格式。

技能工作坊

你的代理自行保存和更新的技能,支持撤销。

技能配置

完整的 skills.* 配置模式。

ClawHub

在公共注册表中浏览和发布技能。

构建插件

插件可以随其文档化的工具一起发布技能。

斜杠命令

技能注册的命令如何被调用和门控。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw