4. 技能与记忆

这是什么：技能（skill） = 一个装着 SKILL.md 的文件夹，用 Markdown 告诉 Agent「这件事该怎么做」。记忆（memory） = 工作区里的几个 Markdown 文件，把「你是谁、你偏好什么」写下来，跨会话不丢。

为什么用：每次都要重新交代一遍「日报怎么写、部署怎么走」，你累它也烦。技能把流程固化，记忆把偏好留下——用得越久，它越像你的助手。

如何用：本章先手写一个 SKILL.md，再讲技能放在哪、怎么被加载；然后讲记忆的四个文件各管什么，最后从 ClawHub 装一个现成技能。

4.1 技能长什么样

每个技能就是一个目录，里面放一个 SKILL.md：YAML frontmatter + Markdown 正文。

---
name: weekly-report
description: 汇总本周 Git 提交与 Issue，生成周报
---

用户说「出周报」时：

1. 进入仓库目录，跑 `git log --since="7 days ago" --oneline`
2. 拉取本周关闭的 Issue，统计数量与类型
3. 按「做了什么 / 有什么风险 / 下周计划」三段输出
4. 写到 `reports/YYYY-WW.md`，并在聊天里回一句摘要

frontmatter 里至少要有 name 和 description：name 是技能名（同时是斜杠命令名 /weekly-report），description 一句话说明「什么时候该用它」，模型靠它决定要不要加载。另外还有 user-invocable（是否暴露为斜杠命令，默认 true）、disable-model-invocation（true 时模型不能主动选它，只能你显式 $ 引用）、command-dispatch: "tool"（斜杠命令绕过模型直接派给工具）。

正文里可用 {baseDir} 引用技能文件夹路径。格式遵循 AgentSkills 规范，和 Claude Code 等生态兼容。

4.2 技能放在哪：谁赢谁

技能可以从好几个地方加载，同名时优先级高的赢：

优先级	来源	路径
1（最高）	工作区技能	`<workspace>/skills`
2	项目 Agent 技能	`<workspace>/.agents/skills`
3	个人 Agent 技能	`~/.agents/skills`
4	托管 / 本地技能	`<state-dir>/skills`（默认 `~/.openclaw/skills`）
5	Workshop 技能	`<state-dir>/agents/<agentId>/agent/workshop-skills`
6	内置技能	随安装附带
7（最低）	额外目录	`skills.load.extraDirs` + 插件自带技能

两个容易忽略的点：文件夹名只是分类（真名取自 frontmatter 的 name）；扫描会在根目录下最多 6 层找 SKILL.md，所以 skills/research/SKILL.md 这种分组布局也能被发现。默认工作区是 ~/.openclaw/workspace，所以最常见的放法就是 mkdir -p ~/.openclaw/workspace/skills/weekly-report。

4.3 手写第一个技能

把 4.1 那段 SKILL.md 存成 ~/.openclaw/workspace/skills/weekly-report/SKILL.md，然后查一下它有没有被认出来：

openclaw skills list
openclaw skills check

你会看到（示意）：

weekly-report   (workspace)  汇总本周 Git 提交与 Issue，生成周报
check: 1 eligible, 0 blocked

openclaw skills check 专门用来排查「配置里写了技能，Agent 却看不见」这类问题。

4.4 门控：先说清楚「我需要什么」

技能可以在 frontmatter 里声明依赖，OpenClaw 在加载时就过滤掉不满足条件的：

---
name: image-lab
description: 用图像生成工作流生成或编辑图片
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

门控项：requires.bins / requires.anyBins（命令必须在 PATH 里，后者至少一个）、requires.env（环境变量必须存在）、requires.config（openclaw.json 配置项必须为真）、os（限定平台）、always（true 时跳过依赖检查，但不覆盖 os 过滤）。

⚠️ 2026 年 7 月之前的 metadata.clawdbot 旧格式不再读取，老技能要改成 metadata.openclaw。

这既是功能也是安全机制：一个需要 docker 的技能，在没装 Docker 的机器上不会假装自己能用。

4.5 怎么调用技能

用 $weekly-report 和 $release_notes 总结这次改动

$ 引用：写在提示词里，OpenClaw 让模型先读对应的 SKILL.md 再动手。一条消息最多引用 8 个技能，超出会直接报错
/ 斜杠命令：独立成行的 /weekly-report ...，在渠道消息里是真正的命令形式

细节：$HOME、$PATH 这类大写 shell 变量仍是普通文本，技能名要用小写（$home）；想让 $ 保持字面量就写 \$name；标了 disable-model-invocation: true 的技能模型不会主动用，但你显式写 $技能名 仍能调。

4.6 记忆的四个文件

OpenClaw 的记忆没有隐藏状态——全是工作区里的 Markdown 文件（默认 ~/.openclaw/workspace）：

文件	作用	什么时候加载
`USER.md`	你的稳定画像：偏好、沟通风格、关系、进行中的项目	会话开始时，带一个单独的小预算
`MEMORY.md`	长期记忆：耐久的事实和决定（不是流水账）	会话开始时
`memory/YYYY-MM-DD.md`	每日笔记：当天/近期的观察与会话摘要	`/new` 或 `/reset` 时自动带上今天和昨天的
`DREAMS.md`	「梦境日记」：后台巩固过程的摘要，给人看的	需要时人工查阅

分层的逻辑是：USER.md 管「我是谁」，MEMORY.md 管「记住的事实」，memory/*.md 管「流水」。

MEMORY.md 变长了会被截断注入（文件本身不会被改），这时该把细节挪进 memory/*.md，只留摘要。查体积用 openclaw doctor，或在对话里用 /context list。

4.7 记忆工具和后台巩固

Agent 有三个记忆工具：memory_search（语义检索，换个说法也能找到）、memory_get（读指定文件或行范围）、intent（创建/列出/取消「事件触发式」的长期意图）。

检索是混合搜索——向量相似度加关键词匹配，产品型号、函数名这类精确词也能命中。默认用 OpenAI 的 embedding，也可换成 Gemini、Voyage、Mistral、Bedrock 或本地 GGUF / Ollama。

后台还有两个自动化机制：memory flush（压缩前冲刷）在上下文要压缩之前跑一轮静默回合，提醒 Agent 把重要内容写进记忆文件（默认开启）；dreaming（做梦）在后台定时把 memory/*.md 里值得留的东西提炼进 MEMORY.md，过程摘要写进 DREAMS.md，不想要就关掉：

{ plugins: { entries: { "memory-core": { config: { dreaming: { enabled: false } } } } } }

你会看到（示意）：

$ openclaw memory status
plugin: memory-core  dreaming: disabled  provider: openai  docs: 12  entries: 41

命令行也能查：

openclaw memory status
openclaw memory search "部署流程"
openclaw memory index --force

你会看到（示意）：

openclaw memory status
plugin: memory-core  dreaming: enabled  provider: openai  docs: 12  entries: 41

openclaw memory search "部署流程"
memory/2026-10-18.md:42  部署流程走 openclaw gateway install，然后跑 doctor

小提醒：记忆能保留「审批上下文」，但不能代替权限控制。想让某件事「除非我批准否则别做」，得靠沙箱和审批策略（第 5 章）。

4.8 从 ClawHub 装技能

ClawHub（clawhub.ai） 是公开的技能注册中心：

openclaw skills search "周报"
openclaw skills install @owner/<slug>
openclaw skills verify @owner/<slug>
openclaw skills update --all

你会看到（示意）：

installed: @acme/weekly-report  -> workspace/skills/weekly-report
verify:    trust envelope OK, scan status: passed

默认装进当前工作区的 skills/；加 --global 装到共享的 ~/.openclaw/skills。也支持 git:owner/repo@ref 和本地目录。

⚠️ 第三方技能当成不可信代码对待，装之前先读一遍 SKILL.md。它能指示 Agent 做什么，等于给了它工具权限。

动手改

写一个 daily-standup 技能放进 ~/.openclaw/workspace/skills/daily-standup/SKILL.md，要求它汇总昨天的 Git 提交和未完成 Todo，跑 openclaw skills list 确认被认出来
在对话里说「记住我下午 3 点后不接需求」，然后去 ~/.openclaw/workspace/USER.md 看它被写到了哪一行
给技能加个门控（比如 requires.bins: ["git"]），再把 git 从 PATH 里临时去掉，看看 openclaw skills check 怎么反应

小结

技能 = 带 SKILL.md 的文件夹；frontmatter 至少写 name 和 description
加载优先级：工作区 > 项目 Agent > 个人 Agent > 托管库 > Workshop > 内置 > 额外目录
metadata.openclaw.requires 声明依赖，不满足的技能直接不加载
调用方式：$技能名 写在提示词里，/技能名 独立成行；一条消息最多 8 个
记忆四件套：USER.md（画像）、MEMORY.md（长期事实）、memory/YYYY-MM-DD.md（每日笔记）、DREAMS.md（巩固摘要）
记忆只是上下文，不是权限——边界靠第 5 章的策略来划

下一章：安全边界，信任模型与密钥管理，这套东西能不能放心上线全看这一章 🐸