跳转至

技能工坊

Skill Workshop 保存代理为自己编写的技能,称为习得技能。代理在完成复杂的多步骤工作后会保存流程,并修正曾误导它的习得技能;30 天内无人使用的技能会被归档。每次更改都会立即生效,先保存上一版本,并且可以撤销。

习得技能是流程,而不是记忆:它是用户会重复执行的任务的方法,因此代理不必每次都重新推导。关于用户或世界的事实应放在记忆中。关于某个代码库的知识,例如其约定、构建命令或架构,应放在该仓库的文档或 AGENTS.md 中,因为在那里工作的每个代理都会读取它,所以代理不应将其保存为习得技能。

习得技能属于一个代理,并且对该代理始终可见:它们会绕过 agents.defaults.skills 和 agents.entries.<id>.skills 允许列表。若要隐藏某个技能,请将其归档。

你自己编写的技能(工作区、项目、托管、ClawHub、插件和内置技能)不是 Workshop 技能。请在其来源处编辑它们;参见创建技能。对于共享 Gateway 上由配置文件拥有的技能,参见个人库编写。

代理如何学习

  • 在一轮对话中: 当代理使用的某个习得技能被证明错误或不完备时,它会查看该技能并修补具有误导性的步骤。在你很可能重复的复杂多步骤工作之后,它会保存可用的流程,修补覆盖该类任务的技能,或在没有覆盖时创建一个。
  • 后台审查: 在对话中模型完成足够多的工作后,或在使用了习得技能的一轮对话结束后,后台运行会审查它并保存值得保留的内容。参见自学习。
  • /learn [request]: 要求代理立即保存一个技能,来源可以是当前对话或你指定的来源。参见 /learn。
  • 从历史记录学习: Control UI 按钮会打开一个普通聊天,代理在其中审查较早的对话并保存它发现的内容。
  • 未使用技能清理: 30 天内无人使用的习得技能会被归档。参见未使用技能清理。

更改后的技能会在新会话中加载。正在运行的会话会保留其开始时使用的技能快照。

撤销

当后台运行更改某个技能时,OpenClaw 会向触发它的对话发布一行:

💾 Learned: updated `deploy-staging` (tightened the rollback step). Say "undo" to revert this skill change.

回复 "undo" 后,代理会使用 skill_workshop 恢复上一版本。如果审查未更改任何内容,则不会发布任何内容。无通道的 Control UI 会话会以转录条目的形式获得同一行。

你也可以从 Control UI(在技能的最新更改上选择撤销,或在它的历史记录选项卡中)或 CLI 撤销:

openclaw skills workshop restore deploy-staging
openclaw skills workshop restore deploy-staging --version <version-id>

恢复操作会在替换之前保存当前副本,因此撤销本身也可以被撤销。刚刚创建的技能没有更早的版本;请改为将其归档。

未使用技能清理

当学习功能开启时,OpenClaw 会归档 30 天内没有活动的习得技能,并在更改记录中记录原因 unused for 30 days 和操作者 curator。活动是以下最新的一项:其 SKILL.md 的已记录读取、前台 skill_workshop view,以及其最后一次更改(创建、修补、恢复)。创建不到 30 天的技能永远不会被归档。该检查每个代理每天最多运行一次,在一轮对话结束后运行,并且从不延迟该轮对话。归档是常规的版本化归档:可以随时恢复。

清理仅针对默认运行时为嵌入式 OpenClaw 运行时框架的代理运行,运行在 Gateway 进程中。Codex app-server 运行时框架使用其原生 shell 读取技能,OpenClaw 无法将其归属到某个技能,因此对于 Codex 代理,清理保持关闭,而不是归档正在使用的技能。

早期版本运行每周 curator 自动化(skill-collection-review:<agentId>)。它已退役:Gateway 在升级时会删除这些 cron 行,并且不会创建替代项。

/learn

/learn
/learn docs/runbook.md; focus on recovery

/learn 是一个普通的前台轮次。如果没有请求,代理会保存当前对话中可复用的工作流。如果有请求,它会使用常规工具收集你指定的路径、URL、笔记或对话引用,并遵循你给出的任何重点、范围或命名。它会先查看相关技能,修补覆盖该任务的技能,只有在没有覆盖时才创建新技能。覆盖同一类任务的相关技能会合并为一个总括技能:它会修补保留下来的技能,并将其余技能以 absorbed_into 归档。然后它会告诉你哪个技能发生了更改。如果没有值得长期保留的内容,它不会更改任何内容。

/learn 在两种学习模式下均可用。当 skill_workshop 不可用时,例如在沙箱会话中或工具策略隐藏该工具时,它会改为回复一条说明。

代理工具

内置 skill_workshop 工具是执行所有习得技能更改的方式。它是 tools.profile: "coding" 的一部分;如果使用更严格的策略,请将其添加到 tools.allow 或 tools.alsoAllow。

操作 参数 效果
list — 列出可用技能和已归档技能
view name、可选 file_path、version 读取文件,当前版本或已保存版本
create name、content(完整 SKILL.md) 创建新技能
操作 参数 效果
patch name、old_text、new_text、可选 file_path 替换一个精确且唯一的片段
write_file name、file_path、content 写入支持文件,或重写 SKILL.md
remove_file name、file_path 删除一个支持文件;SKILL.md 只能通过 archive 处理
archive name、可选 absorbed_into、reason 隐藏该技能;absorbed_into 指定现在覆盖它的活跃技能
restore name、可选 version 恢复最新保存的版本,或指定名称的版本

每个变更操作都接受 reason,一行简短说明,会显示在变更流和聊天通知中。每次变更都会先保存之前的版本。

写入在落地前会经过校验:

  • 新名称使用 1-63 个小写字母、数字或连字符,并以字母或数字开头。早期版本保存的较长名称仍会列出并可管理。
  • SKILL.md 需要前置元数据,其中 name 与技能目录匹配,并且 description 为 1-1024 字节(目标约 160)。它必须不超过 skills.workshop.maxSkillBytes。
  • 支持文件位于 references/、templates/、scripts/ 或 assets/ 下,每个文件最多 256 KiB。绝对路径、路径穿越和符号链接会被拒绝。
  • 严重的安全扫描器发现(包括字面量密钥)会拒绝写入,并指明文件、行号和规则。

后台审查必须先 view 一个现有技能,才能对其执行 patch、write_file、remove_file 或 archive,并且其归档需要 absorbed_into 或 reason。前台 view 算作使用该技能。

对 SKILL.md 的成功 create、patch 或 write_file 可能以最多三行 Advisory (not blocking) 结尾:写入引入的编写问题(描述超过 160 字节或以 "This skill" 开头、正文超过 250 行或 12 KB、强调词、三个或更多 Never/Don't 步骤、更新说明或日期)。写入已经落地。create 还会列出该代理的其他已学习技能,因此由代理本身判断新技能是否与某个技能重复并应合并。

配置

{
  skills: {
    workshop: {
      autonomous: { mode: "auto" },
      maxSkillBytes: 40000,
    },
  },
}
设置 默认值 效果
skills.workshop.autonomous.mode "auto" "auto" 启用后台审查和未使用技能清理。"off" 禁用两者。
skills.workshop.maxSkillBytes 40000 SKILL.md 的最大字节数(1024-200000)。
openclaw config set skills.workshop.autonomous.mode off
openclaw config set skills.workshop.autonomous.mode auto

在 off 模式下,当你要求时、通过 /learn 或在 从过往对话中学习 会话中,代理仍可以创建和更新已学习技能。有关模式,请参阅 技能配置。

文件存放位置

<agentDir>/workshop-skills/
  <name>/
    SKILL.md
    references/  templates/  scripts/  assets/
  .archive/
    <name>/<versionId>/     # full copy of the skill before each change

<agentDir> 默认为 <state-dir>/agents/<agentId>/agent,如果设置则为 agents.entries.<id>.agentDir。除非 OPENCLAW_STATE_DIR 覆盖,否则 <state-dir> 为 ~/.openclaw。

每次变更(包括归档和恢复)之前都会保存一个版本。每个技能保留最新的 10 个版本。已归档技能没有活跃目录;其最新版本会恢复它。变更流(谁在何时以何种原因变更了哪个技能)保存在状态数据库中,每个代理保留最新的 500 条记录。

操作员界面

  • 控制 UI: 打开 插件 → 技能工作坊。已学习技能按最常用优先列出(或按最近活动或名称),每个都显示其最新变更和 撤销;闲置两周的技能会被标记,因为 未使用技能清理 可能在 30 天时归档它们。选择某个技能会显示其说明、支持文件和历史记录。从历史记录中,你可以将较早版本与当前版本比较、恢复它,或撤销一次变更。归档 和 恢复 在活跃列表和已归档列表之间切换技能。页面头部包含学习模式开关和 从历史中学习。如果无法加载学习配置,页面会显示错误和 重试 按钮,同时保持技能库可用。
  • CLI: openclaw skills workshop list | changes | show | archive | restore。请参阅 技能 CLI。
  • 插件: skill_changed 钩子会观察每次已提交的技能工作坊变更。

网关方法接受可选的 agentId(省略时使用默认代理):

方法 范围 参数 返回值
skills.workshop.list operator.read — agentId、mode、root、活跃 skills(含 useCount、lastUsedAtMs)、archived 版本
方法 范围 参数 返回值
skills.workshop.changes operator.read limit(最多 500)、beforeMs changes,最新在前
skills.workshop.read operator.read name、filePath、versionId name、filePath、content、files
skills.workshop.archive operator.admin name、reason change
skills.workshop.restore operator.admin name、versionId change

从 CLI、Control UI 或 Gateway 执行的归档和恢复会记录为 user 变更。

从早期版本升级

早期版本会将学习到的技能暂存为草稿以供审查。openclaw doctor --fix 会导出任何待处理的草稿并移除旧设置;参见 状态迁移 和 技能配置。导出的草稿 不会被加载。如果你仍需要它,请让代理使用 /learn 保存一个。

早期的 skills.proposals.* 和 skills.curator.* Gateway 方法仍保持 注册,但会返回一个指向上述方法的错误。 skill_proposal_evaluate 和 skill_proposal_changed 插件钩子已被移除; 参见 已移除的接口。

早期每周审查写入 <agentDir>/skill-workshop/collection-backups/ 的备份不再被读取。请手动 从其中复制你需要的任何文件;OpenClaw 不会恢复它们。

故障排除

问题 检查项
从未学习到任何内容 skills.workshop.autonomous.mode 为 auto,对话符合条件,并且工具策略允许 skill_workshop。参见 自学习。
代理无法调用 skill_workshop 沙盒运行不会获得该工具。请使用非沙盒会话或 CLI。否则将该工具添加到 tools.allow 或 tools.alsoAllow。
写入被拒绝 错误会指明修复方法:重命名技能、更正 frontmatter、缩短描述或 SKILL.md,或移除被标记的行。
发生了不需要的变更 说“撤销”,在 Control UI 中按 撤销,或运行 openclaw skills workshop restore <name>。
技能被意外归档 未使用技能清理会归档 30 天内没有活动的技能。运行 openclaw skills workshop restore <name>。

在 auto 模式下,openclaw doctor 会为每个代理运行 core/doctor/skill-workshop-tool-policy 检查。它会指明隐藏 skill_workshop 的沙盒设置或配置层,以及需要做出的确切 allow 或 alsoAllow 更改。

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