让 Agent 可迁移：OpenClaw Workspace、知识库和工具配置的打包实践

最近我做了一件看起来不大、但很重要的事：把一个 OpenClaw 生产问答 workspace 打成一个可迁移的 zip 包。这个动作本身不复杂，但它背后反映的是另一个问题：一个 Agent 如果只能在当前服务器上跑，依赖一堆口头说明和临时配置，那它还不算真正可交付。

可迁移，不只是把文件压缩一下。真正有用的迁移包，应该让另一个环境能够清楚知道：哪些是 workspace，哪些是知识库，哪些是配置样例，哪些不能覆盖，哪些工具不该默认开启。

我为什么要做迁移包

在 OpenClaw 里，Agent 的行为并不只由一段 Prompt 决定。它依赖 workspace 里的 AGENTS.md、TOOLS.md、MEMORY.md、路由规则、知识库路径、工具插件和运行时配置。只复制其中一部分，很容易得到一个“看起来像原来的 Agent，但行为不一致”的副本。

所以我更倾向于把生产问答 Agent 的相关材料打成一个完整包。这样后续无论是迁移到新服务器，还是在同一生产环境里新建一个 Agent，都不用靠记忆还原。

一个迁移包应该包含什么

这次我把内容拆成几类。

• workspace：包括 AGENTS.md、TOOLS.md、路由、模式和工具契约。
• 知识库：包括 FAQ、SOP、场景卡片、业务术语等 Markdown 文件。
• 来源材料：保留 FAQ 原始来源，方便后续追溯和重新生成。
• 配置样例：例如 memorySearch、embedding、tools allowlist 的示例。
• 插件代码：只作为可选依赖，尤其是只读查询工具需要时才部署。
• 迁移说明：说明怎么解压、复制、配置、索引、验证和回滚。

这些内容放在一起，迁移才不是“把目录拷过去试试”，而是一套可以复查的交付物。

最重要的不是打包，而是不影响旧 Agent

同一个 OpenClaw 生产环境里可能有多个 Agent。新增一个 Agent 时，最怕的是误改默认配置，导致所有 Agent 行为变化。我的原则很简单：不要改 agents.defaults，不要覆盖旧 workspace，不要混用知识库路径。

更安全的方式是新建目录。

/opt/openclaw-data/workspace/hotel-cs-new
/opt/openclaw-data/kb/hotel-cs-new

然后在配置里新增 agent id，而不是改默认 workspace。测试时通过 openclaw agent --agent hotel-cs-new 指定新 Agent。这样就算新 Agent 有问题，也可以删除或停用它，不会影响旧的生产 Agent。

工具权限要特别小心

迁移包里可以带插件代码，但不代表所有工具都应该开放。生产问答 Agent 推荐只开放只读和知识检索能力，例如：

• memory_search
• memory_get
• search_hotel_orders

取消、退款、工单写入这类工具，即使代码存在，也不应该默认开放。尤其是在一些 OpenClaw 版本里，tools.allow 可能是全局配置，随便改会影响所有 Agent。工具权限不是越多越好，而是要和 workspace 的目标匹配。

知识库迁移后必须重建索引

很多人迁移知识库后会忽略索引问题。文件复制过去不代表 RAG 已经可用。部署完成后，需要重新检查 memory 状态并强制索引。

openclaw memory status --deep
openclaw memory index --force
openclaw memory search --query "酒店发票什么时候开" --max-results 8

只有能检索到预期知识片段，Agent 的问答才有基础。否则模型可能会退回到泛化回答，看起来能说，但不一定有业务依据。

迁移包里不应该包含什么

我这次刻意没有把运行态敏感信息放进去。

• 不放真实 authSign。
• 不放 API Key。
• 不放 runtime.json。
• 不放 pending actions。
• 不放真实账号密码。

迁移包应该携带结构和说明，而不是携带生产密钥。真实凭据只应该存在服务器运行时配置里。

结语

Agent 工程化的一个重要标志，是它能不能被迁移、复刻和回滚。OpenClaw workspace 给了我们一个不错的组织方式，但真正让它可交付的，是把 workspace、知识库、配置样例、工具边界和迁移说明一起沉淀下来。这样 Agent 才不是某台服务器上的“手工状态”，而是一套可以被管理的工程资产。