技能工坊
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 是一个普通的前台轮次。如果没有请求,代理会保存当前对话中可复用的工作流。如果有请求,它会使用常规工具收集你指定的路径、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" |
"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