OpenClaw 能力迁移、共享能力与多 Agent 架构设计笔记

背景

这份笔记整理了我与 Jarvis 关于以下主题的完整讨论：

1. 如何在迁移机器、重装 OpenClaw、甚至切换到其他智能体框架时，尽可能快速复原现有能力、记忆与 skills。
2. 如何让 agent 在新上下文、新 skill、子 agent 或其他长期 agent 中，默认复用已有的登录态、secrets、工具与本地约定，而不是每次重新摸索。
3. wrapper、script、skill 三者的职责边界到底是什么。
4. 如果当前所有东西都放在主 agent 的 workspace 下，将来扩展到多 agent 时，平台能力与 agent 身份应该如何拆分。

这份总结不是单纯备忘，而是一套关于 agent 基础设施、可迁移性、能力继承与多 agent 演化 的系统化设计笔记。

---

一、从“备份 OpenClaw”转向“保留 agent 能力”的思路

核心结论：真正要保留的不是某个程序实例，而是三层资产。

1. 你的资产

这些内容本质上构成了 agent 的人格、长期记忆、工作习惯与本地知识，最值得版本化和迁移。

• SOUL.md
• IDENTITY.md
• USER.md
• MEMORY.md
• memory/*.md
• HEARTBEAT.md
• TOOLS.md
• 自定义 skills
• 自定义 scripts / prompts / notes

这部分可以理解为：

• persona
• operating rules
• long-term memory
• local conventions
• local agent knowledge

它们决定“这个 agent 还是不是原来那个 agent”。

2. OpenClaw 的运行时资产

这部分是 OpenClaw 作为调度器、容器与连接层的部分。

• gateway 配置
• extensions
• installed skills
• cron jobs
• channel bindings
• model / provider 配置
• agent definitions

这部分决定“能力能不能立即跑起来”。

3. 外部依赖与登录态

这部分最容易在迁移时卡住。

• API keys
• bot tokens
• GitHub / NotebookLM / 其他服务登录态
• browser session / storage state
• 本地 CLI 工具安装状态
• 路径约定（如默认 Obsidian vault）

这部分不应该简单粗暴地混入 Git，而应该通过 secrets 管理、环境模板、安装脚本和迁移文档来恢复。

---

二、快速复原能力的关键：不是“全量拷贝”，而是“可重建”

真正可持续的方案，不是依赖某次完整备份，而是建立一套可以重新搭起来的结构。

建议准备的四类东西

1. workspace Git 仓库

把 agent 的人格、记忆、skills 和脚本版本化。

建议纳入版本控制：

• SOUL.md
• IDENTITY.md
• USER.md
• MEMORY.md
• memory/
• HEARTBEAT.md
• TOOLS.md
• 自定义 skills/
• scripts/

2. bootstrap 脚本

比如：

• bootstrap-mac.sh
• bootstrap-openclaw.sh

它们负责：

• 安装 Homebrew 依赖
• 安装 OpenClaw
• 安装 Python / Node / CLI 工具
• 恢复 workspace
• 创建目录
• 提示补 .env
• 做最基础的环境检查

3. 环境清单

例如：

• Brewfile
• .env.example
• requirements.txt / pyproject.toml

4. 迁移说明文档

例如：

• MIGRATION.md
• RECOVERY.md
• SMOKE_TEST.md

它们记录：

• 依赖
• secrets 来源
• 登录步骤
• 配置恢复顺序
• 验证步骤

推荐的恢复顺序

1. 恢复 workspace
2. 安装基础依赖
3. 恢复 OpenClaw 配置
4. 补 secrets 与登录态
5. 做 smoke test

这样恢复的不是“那台旧机器”，而是“同一套 agent 能力结构”。

---

三、如果以后不用 OpenClaw，哪些能力还能保留？

这是讨论中非常关键的一点。

真正可移植的不是 OpenClaw daemon 本身，而是你的 agent substrate。

可以直接复用的

• SOUL.md
• IDENTITY.md
• USER.md
• MEMORY.md
• memory/*.md
• 绝大多数 Markdown skills
• 你的脚本和 SOP

需要适配的

• tool 调用约定
• session / subagent / ACP 路由
• cron / heartbeat 机制
• channel messaging 机制
• browser / node / canvas 等 OpenClaw 特性

不可直接复用的

• 某些 OpenClaw 内部元数据格式
• 某些 built-in tools schema
• gateway 自身配置结构

因此，最稳的设计原则是：

把人格、记忆、技能说明和执行脚本尽量放在 OpenClaw 之外；把调度、接线和运行时集成交给 OpenClaw。

也就是：

• 知识与规则：Markdown 化
• 执行能力：脚本化
• 编排能力：框架化

---

四、为什么“共享能力”不是简单的 memory 问题

讨论中一个关键转折是：

你真正想要的不是“让我记住一些提醒”，而是建立一个稳定的能力继承层。

你希望的是：

• 新 skill 默认知道已有登录态
• 子 agent 默认知道本地已有工具
• 新上下文默认知道标准路径与能力入口
• 不再重复发明替代方案

这说明问题不在于“对话记忆不够”，而在于：

这些东西还没有被提升成稳定的系统资产。

所以解决方案不是“多记一点”，而是把共享能力变成：

• 可读的约定
• 可调用的脚本
• 可继承的环境
• 可被 skill 明确引用的统一入口

---

五、共享能力应该拆成四个固定面

1. 声明面

说明系统中“有哪些能力、应该优先怎么用”。

载体：

• TOOLS.md
• skill 文档
• MIGRATION.md

例如：

• NotebookLM 登录态在哪里
• Obsidian 默认 vault 是什么
• 哪个服务优先用已有方案
• 哪个老方案已经废弃

2. 凭证面

说明能力如何授权。

载体：

• .env
• 系统 Keychain
• 1Password
• storage state 文件

重点：不要把真正的密钥散落在 Markdown 记忆中。

3. 调用面

说明 agent 如何稳定调用这些能力。

载体：

• wrapper scripts
• 固定命令入口
• 通用 task scripts

重点：让 skill 走统一入口，而不是自己拼实现。

4. 策略面

说明默认什么时候复用、什么时候允许新建。

例如：

• 默认复用现有登录态
• 默认不新建第二套 storage
• 默认不替换成熟方案
• 只有明确要求隔离时才开新状态

总结成一句话：

你要的不是“记住已有能力”，而是“任何 agent 都能接入同一套共享能力基础设施”。

---

六、登录态应该如何分类：哪些适合迁移，哪些适合重登

不是所有登录态都值得“搬家”。正确思路是分层判断。

1. API 型凭证：最适合重建

典型例子：

• OpenAI / Anthropic / Gemini API key
• Telegram bot token
• GitHub PAT

特点：

• 本质是凭证，不是 session
• 与机器绑定很弱
• 最适合通过 .env / Keychain / 密码管理器恢复

策略：

• 优先重建
• 不需要迁移 cookie / session 文件

2. CLI / OAuth 型登录态：可迁移，但通常重登更稳

典型例子：

• gh auth login
• NotebookLM storage state
• 某些第三方 CLI OAuth cache

特点：

• 技术上常常可以拷贝
• 但可能依赖本地环境、浏览器、版本

策略：

• 能快速重登时优先重登
• 只有在重登成本很高时，才迁移 state

3. 浏览器 / 网页会话型登录态：最脆弱

典型例子：

• cookies
• 浏览器 profile
• 扩展绑定状态

特点：

• 与本机环境耦合强
• 易失效
• 隐私污染重

策略：

• 不适合作为主要恢复方式
• 最多作为可选的快捷方式

4. 机器绑定型认证：优先重建

典型例子：

• Keychain 绑定项
• SSH agent 临时状态
• 设备信任关系
• 本机证书

策略：

• 不建议迁移
• 直接重建更稳

一个实用原则

能力恢复优先级：API / CLI > state 文件 > 浏览器 profile 整体迁移

---

七、Secrets 应该放 .env、Keychain，还是 1Password

讨论结论不是三选一，而是分角色组合使用。

1. .env

优点：

• 开发和自动化最方便
• 脚本易读
• 可迁移性强
• 易于配 .env.example

缺点：

• 容易误提交
• 明文落盘
• 权限控制弱

适合：

• 开发环境 token
• 高频被脚本读取的 key

2. Keychain

优点：

• 本机保管比 .env 更安全
• 不易误提交
• 更适合作为长期本机存储层

缺点：

• 跨机器不如 .env 直接
• 自动化接入稍麻烦

适合：

• 本机长期使用的高频 secrets
• 不希望明文落地在项目目录中的凭证

3. 1Password / 密码管理器

优点：

• 跨机器同步好
• 人类管理体验好
• 适合作为 secrets 的权威来源

缺点：

• 自动化接入不一定最简单
• 经常还需要注入到运行环境

最适合的定位：

作为 source of truth，由它保存真正的值；运行时再注入 .env 或 Keychain。

推荐组合

方案 A：1Password + .env

• 1Password 保存真值
• .env 作为本机运行时入口
• .env.example 记录变量名

方案 B：Keychain + wrapper 注入

• 真值存 Keychain
• wrapper 运行时读取并注入
• skill 不直接接触 secret 来源

方案 C：混合制

• 高频开发类放 .env
• 高敏感长期类放 Keychain / 1Password
• 对脚本暴露统一环境变量接口

最关键的原则不是“存在哪”，而是：

skill 只应该知道自己需要哪个变量名，而不应该知道 secret 真值具体存在哪里。

---

八、wrapper 到底是什么，它和 script、skill 的区别是什么

这是整场讨论里最值得澄清的概念之一。

最短定义

• wrapper：给某个已有能力做稳定入口适配层
• script：为了完成某个具体任务而写的执行流程
• skill：决定用户这类请求应该怎么解释、怎么调度、有什么规则边界

一句话区分

wrapper 解决“怎么统一调用这个能力”，script 解决“为了完成这个任务，要按什么步骤做”，skill 解决“面对用户请求，该用什么策略来调用这些流程”。

---

九、wrapper 的职责边界

wrapper 面向的是“能力入口”。

它应该负责：

• 定位标准路径
• 注入标准环境
• 复用现有登录态
• 做基础检查
• 规范少量参数
• 统一错误输出

它不该负责：

• 复杂业务流程
• 大段 prompt
• 多阶段任务编排
• 隐蔽副作用
• 一堆 fallback 分支

好的 wrapper 本质上是：

一个稳定入口 + 最小策略层

好 wrapper 的特征

• 薄
• 显式
• 幂等
• 可替换

它存在的意义

• skill 不用再猜路径
• 登录态位置变化时，只改一处
• 底层工具替换时，只改一处
• 多个 skill 共享同一能力接入方式

---

十、script 的职责边界

script 面向的是“任务完成”。

它应该负责：

• 一个任务需要的步骤
• 每一步失败怎么办
• 中间产物怎么传
• 要调用哪些工具
• 最终结果如何组织

例如：

• 论文阅读脚本
• URL 转 markdown 再入 Obsidian
• issue 转 note
• 总结 + 音频 + 通知

它和 wrapper 的关系通常是：

• wrapper 提供标准入口
• script 调用 wrapper 完成任务流程

---

十一、skill 的职责边界

skill 面向的是“自然语言请求与系统调度策略”。

它负责：

• 识别哪些请求属于自己
• 定义输入输出协议
• 决定默认策略和边界
• 规定 fallback 规则
• 规定是否保留中间产物
• 规定失败时如何告知用户

因此：

• wrapper 是能力入口层
• script 是任务流程层
• skill 是策略与编排层

---

十二、为什么系统级 wrapper 不该藏在某个 skill 里

讨论中明确区分了两种脚本：

1. skill-private script

如果它完全服务于某个 skill、复用价值不高，那么放 skill 目录中完全合理。

2. 系统级 wrapper

如果它承担的是：

• 统一登录态复用
• 统一默认路径
• 统一能力入口
• 多个 skill 共享调用

那它就不应该藏在某个单独 skill 下面。

原因包括：

原因 1：可发现性差

别人不知道系统里已经有统一入口，于是又写一套。

原因 2：语义被污染

一旦路径是 skills/foo/scripts/bar.sh，别人会默认它是 foo 私有实现，而不会把它当公共平台入口。

原因 3：版本演化会隐性耦合

skill A 改了脚本，skill B 可能也依赖它，却没人知道。

原因 4：迁移时边界不清

无法区分哪些是平台层、哪些只是业务实现细节。

更合理的分层

公共平台层

适合放：

• 公共 wrappers
• 公共 task scripts
• shared references
• env templates
• migration docs

skill 私有层

适合放：

• skill 专用解析器
• skill 专用 prompt 预处理
• skill 私有中间格式转换

一句判断口诀：

• 解决“怎么统一调用某个能力” → wrapper
• 解决“为了完成某个任务，需要按什么步骤做” → script
• 解决“用户这类请求该怎么处理，有什么规则和边界” → skill

---

十三、拿真实例子理解 wrapper / script / skill

1. NotebookLM

wrapper

负责：

• 检查 CLI 是否存在
• 默认 storage state
• 统一 --json
• 统一 notebook 选择逻辑
• 明确报错

它回答：

系统里任何人如果要调用 NotebookLM，应该从哪个入口进？

script

负责：

• 接收论文 URL
• 获取标题
• 上传 source
• 发 summary / audio prompt
• 等待 artifact
• 保存输出

它回答：

为了完成“单篇论文阅读”任务，要按什么步骤做？

skill

负责：

• 什么请求属于论文阅读
• 默认 summary / audio 策略
• source 和 artifact 是否保留
• 长任务如何通知用户
• fallback 如何处理

它回答：

用户说“帮我读这篇论文”时，系统应该如何解释并调度？

---

2. Obsidian

wrapper

负责：

• 统一默认 vault
• 用 obsidian-cli 调用
• 统一 note 路径与错误输出

script

负责：

• URL 转 markdown
• 加 YAML
• 插入文件夹
• 追加 tag
• 更新索引

skill

负责：

• 哪些请求属于建 note
• 什么时候走 GitHub issue 方案
• 什么时候直接写 vault
• APPEND / INSERT / PATCH 的使用规则

---

3. Codex / ACP

wrapper（这里不一定是 shell 文件，更可能是统一调度约定）

负责：

• Codex 一律走 sessions_spawn
• runtime 统一为 acp
• 默认 thread / label / model 策略
• 默认调试与 stuck 处理方案

它回答：

如果系统里有人要用 Codex，应该从哪条统一入口进？

script / orchestration logic

负责：

• 下发任务
• 收集结果
• 卡住时切调试模式
• 汇总 diff / 风险 / 下一步建议

skill

负责：

• 什么时候请求应该交给 Codex
• 什么时候 run，什么时候 session
• 什么时候需要长期线程
• 用户说“用 codex 做”时该如何解释

一个关键结论是：

wrapper 不一定是 shell 脚本，它的本质是“稳定入口抽象”。

---

十四、skill 规范应该怎么写，才能强制复用已有能力

这一部分相当于“skill 宪法”。

核心思想是：

新 skill 的目标不只是完成任务，而是优先接入现有基础设施完成任务。

六条硬规则

1. Reuse First

新 skill 先找现有能力，再考虑新实现。

也就是：

• 是否已有 wrapper
• 是否已有脚本
• 是否已有标准路径
• 是否已有登录态
• 是否已有本地偏好实现

2. 默认复用登录态与环境，不默认新建

默认流程：

1. 检查现有登录态 / storage / token
2. 有则复用
3. 没有再报缺失
4. 只有明确要求隔离时才允许新建

3. Stable Entry Points Only

优先使用：

1. 现有 wrapper
2. 现有 task script
3. 稳定 CLI
4. 最后才是临时底层命令

4. 禁止无声明 fallback

失败时可以兜底，但不能偷偷引入新的实现路线、新状态或新副作用。

5. 所有副作用都要可预期

涉及：

• 写配置
• 新建状态目录
• 改默认路径
• 覆盖文件
• 注册新 cron
• 修改长期默认值

都应该明确、最小化、可追踪。

6. skill 必须说明：依赖什么、复用什么、不会做什么

这让 skill 成为可判断的系统组件，而不是黑盒。

四条软规则

1. skill 偏编排，不偏内嵌实现

SKILL.md 负责规则和入口，真正执行交给 scripts/。

2. single source of truth

同一能力尽量只有一个权威入口。

3. 倾向报清楚错，不要偷偷绕路

清晰的错比隐性的替代路线更健康。

4. 面向第二次使用而设计

不是第一次能跑通，而是半年后还能维护。

三条最短总结

1. 新 skill 不是来重新实现能力的，而是来接入已有能力的。
2. 默认复用已有状态，禁止悄悄创建平行系统。
3. skill 负责编排，wrapper 负责入口，secrets 负责注入，三层不要混在一起。

---

十五、为什么“共享能力”本质上不是 memory，而是 shared substrate

这里有一个非常重要的抽象：

你想要的不是“主 agent 记得某条经验”，而是：

无论谁执行任务，都能接入同一套已存在的能力基础设施。

这叫 shared substrate。

相比之下，单靠 memory 的问题是：

• 可能记得，但不一定执行
• 可能模糊，不够精确
• 路径和工具一变就失效
• 跨 skill / 子 agent 不稳定

shared substrate 则是：

• 可执行的
• 可验证的
• 可迁移的
• 可复用的

所以长期看，最强的方案不是“让 OpenClaw 记住一切”，而是：

让任何 agent 来了，都能沿着同一套文档、wrapper、secrets 机制工作。

---

十六、主 agent 全在 workspace 下时，未来多 agent 应该怎么考虑

讨论后得出的结论是：

多 agent 不应该完全共享主 workspace，也不应该每个 agent 完全复制一份，而应该采用“分层继承”结构。

两种错误思路

错误思路 A：所有 agent 完全共享主 workspace

问题：

• 记忆相互污染
• 身份边界模糊
• TOOLS / MEMORY / SOUL 混用
• 各种 skill 和脚本互相踩

错误思路 B：每个 agent 完全复制一套

问题：

• 维护爆炸
• wrapper 和 scripts 到处复制
• 修一个问题要改 N 份
• 无法形成共享平台能力

更合理的三层结构

1. 平台层（shared platform）

共享基础设施：

• 公共 wrappers
• 公共 scripts
• 公共 capability registry
• 公共 secrets access mechanism
• 公共 migration / bootstrap 文档

2. 身份层（agent profile）

每个 agent 自己独立维护：

• SOUL
• IDENTITY
• USER
• MEMORY
• memory/
• HEARTBEAT
• agent-specific skills

3. 任务层（runtime context）

每次运行时的临时上下文：

• 当前项目目录
• 当前线程
• 临时输出
• 日志
• 附件

总结成一句话：

共享的是能力，不是人格。

---

十七、什么应该共享，什么应该独立

应该共享的

• 公共 wrapper
• 公共 task scripts
• 公共 skill 规范
• secrets access mechanism
• 环境模板
• 路径约定
• migration / recovery 文档

应该独立的

• SOUL.md
• IDENTITY.md
• USER.md
• MEMORY.md
• memory/*.md
• agent-specific HEARTBEAT.md
• 私有 skills

因为这些构成 agent 的人格、职责与长期身份。

半共享的

像 TOOLS.md 这种东西，更合理的方向是逐步拆成两层：

• platform TOOLS / capability registry
• agent-local TOOLS / preferences

也就是：

• 全局层描述系统有什么能力
• agent 层描述自己偏好如何使用这些能力

---

十八、从“单主脑 + 临时子执行者”走向“多 agent 生态”

当前的 workspace 模式之所以还能正常工作，是因为现在本质上还是：

• 主 agent 是长期人格
• 其他 agent 大多只是临时任务执行者
• 大家共用 workspace，暂时问题不大

但一旦开始认真经营多个长期 agent，就会遇到这些问题：

• 记忆谁来记
• 规则谁说了算
• TOOLS 是给谁看的
• 哪些脚本是全局能力，哪些是私有实现
• skill 是全局共享还是局部专属

这时就需要从“单脑 workspace”升级到：

平台层 + 多个 agent profile + 临时 runtime context

你真正维护的就不再只是一个 workspace，而是：

一个共享基础设施 + 多个 agent profile 的生态系统。

---

十九、整场讨论的总纲总结

如果把全部讨论压缩成一套核心哲学，可以总结为下面这些句子。

1. 要保留的不是程序实例，而是 agent 的结构

包括：

• 人格
• 记忆
• 工作习惯
• 技能说明
• 脚本入口
• 恢复机制

2. 要做的不是“备份一个 OpenClaw”，而是构建“可重建的 agent system”

核心是：

• 文档化
• 版本化
• 脚本化
• 可恢复

3. 新上下文和新 skill 不应该靠“提醒”，而应该靠共享基础设施继承能力

共享能力必须变成：

• capability registry
• secrets mechanism
• wrappers
• reusable scripts
• 明确的 reuse-first 规则

4. 登录态先分类，secrets 再分层，能力最后统一从 wrapper 暴露

这是系统稳定性的关键顺序。

5. wrapper、script、skill 的职责必须分层

• wrapper：能力入口
• script：任务流程
• skill：策略与调度

6. skill 的目标不是重新发明能力，而是优先接入现有能力

这是避免系统未来“乱长”的根本。

7. 多 agent 的正确方向不是全共享，也不是全复制，而是“共享平台，独立人格”

也就是：

• 共享能力
• 独立记忆
• 独立人格
• 共享入口
• 局部可覆写

---

二十、最后的结论

这次讨论的真正主题，其实不是单纯的 OpenClaw 使用技巧，而是一套关于 agent 系统的基础设计观：

如果希望一个 agent 能跨机器、跨上下文、跨 skill、甚至跨框架持续保留能力，那么就不能只依赖即时上下文和模糊记忆，而必须把人格、记忆、能力入口、secrets 机制、迁移流程和 skill 规范显式化、结构化、平台化。

最简练地说：

• 人格和记忆要沉淀成文件
• 能力和 secrets 要沉淀成基础设施
• 技能和流程要沉淀成可复用入口
• 多 agent 要围绕共享平台与独立身份来演化

这才是一个 agent 从“能用”走向“可持续演化”的起点。