OpenClaw Guild：构建企业级AI智能体协作平台，实现数据隔离与权限管理

1. 项目概述：从单兵作战到团队协同的AI平台进化

如果你正在使用OpenClaw来构建和管理你的AI智能体，并且已经感受到了它带来的效率提升，那么恭喜你，你已经走在了自动化办公的前沿。但很快，你可能会遇到一个几乎所有早期采用者都会面临的瓶颈：当你想让团队的其他成员——无论是市场部的同事、客服专员还是项目助理——也接入并使用你精心调教的AI助手时，你会发现事情变得棘手起来。在标准的OpenClaw架构下，所有智能体共享同一个“大脑”，即同一份记忆和上下文。这意味着，你无法放心地将一个处理市场数据的智能体交给新来的实习生，因为TA可能会无意中（或有意地）访问到包含公司财务、未公开项目或敏感客户信息的对话历史。这种数据混杂和权限模糊的状态，对于任何严肃的商业应用来说，都是不可接受的。

这正是OpenClaw Guild项目诞生的背景。它不是一个简单的功能扩展，而是一个旨在将OpenClaw从一个强大的个人AI工作台，彻底转变为一个安全、可扩展、适合团队协作的企业级AI平台的核心插件。想象一下，你的每个团队成员都能拥有一个专属的、懂业务的AI助手，这些助手既能独立工作，处理各自职责范围内的任务，又能在需要时，安全、受控地共享团队知识库和公司规程。市场部的智能体精通产品卖点和竞品分析，但看不到研发的代码片段；客服智能体能调取标准的服务流程和常见问题解答，但接触不到内部的薪资讨论。这一切，都建立在严格的数据隔离和基于角色的访问控制之上。

Guild的核心价值，在于它解决了企业部署AI时最根本的信任与协作问题。它通过引入多用户体系、分层级的内存管理、版本化的技能指令集以及一个集中的管理仪表盘，为OpenClaw注入了企业级应用所必需的“秩序”。无论你是一个小型创业公司，还是一个拥有多个部门的中型企业，甚至是像SpireTech这样的托管服务提供商，需要为不同客户部署独立且安全的AI环境，Guild都提供了一套现成的、经过深思熟虑的解决方案。接下来，我将带你深入拆解Guild的设计哲学、核心组件以及如何一步步将它集成到你的工作流中，让你和你的团队能真正安全、高效地驾驭AI的力量。

2. 核心架构与设计哲学解析

2.1 问题根源：单用户AI平台的局限性

要理解Guild的价值，首先要看清原生OpenClaw在团队场景下的“阿喀琉斯之踵”。其核心问题可以归结为三点：数据混沌、权限缺失和运维黑洞。

数据混沌指的是所有智能体的记忆都存储在同一个平面空间里，比如默认的MEMORY.md文件。智能体A与用户关于预算的对话，智能体B在处理一个技术支持请求时也能“看到”并可能引用。这不仅可能导致信息泄露，更会造成严重的上下文污染。一个处理创意文案的智能体，如果它的系统提示里混入了大量代码片段的记忆，其输出质量会大打折扣。

权限缺失是更致命的问题。OpenClaw本身没有内建的用户概念和权限模型。你无法定义“张三可以指挥营销智能体但无权访问财务智能体”，也无法规定“某个技能指令集只对‘项目经理’角色的成员生效”。一切访问控制都依赖于外部系统或手动管理，既脆弱又难以审计。

运维黑洞则体现在规模化管理的困难上。当你有十几个智能体、几十条技能指令、数百条记忆片段时，如何统一查看、编辑、归档或清理？如何确保新上线的智能体能立即获得它该有的知识和权限？如何审计某个敏感信息是被谁、在什么时间、通过哪个智能体查询的？原生OpenClaw没有提供这些企业级管理工具。

Guild的设计哲学，正是直面这些挑战，其核心思路是“注入秩序，而非推倒重来”。它没有尝试重新发明OpenClaw的轮子，而是以插件的形式，无缝接入现有的OpenClaw网关，通过一系列精巧的钩子和工具，在原有的智能体运行时之上，构建起一套完整的多租户管理体系。

2.2 架构总览：插件、服务器与数据层的协同

Guild的架构清晰地区分了三个逻辑层次，它们各司其职，共同构成了整个平台。

第一层：OpenClaw网关插件。这是Guild的“大脑”和“执行器”，直接运行在OpenClaw网关进程内部。它主要做两件事：一是向智能体暴露一系列以guild_为前缀的工具函数（如guild_memory_read,guild_skill_read），让智能体有能力去操作被隔离的记忆和技能；二是通过生命周期钩子，在关键时刻自动介入智能体的运行流程。例如，在每次构建提示词之前，自动注入当前用户相关的技能目录和记忆摘要；在上下文窗口被压缩前，将重要的临时记忆持久化到数据库。这种深度集成的方式，使得智能体调用Guild功能就像调用原生功能一样自然高效，没有网络延迟，也无需复杂的配置。

第二层：数据持久化与规则引擎（Supabase）。这是Guild的“记忆中枢”和“安全官”。所有数据——用户、角色、智能体、记忆、技能——都存储在Supabase中。Supabase不仅提供了可靠的PostgreSQL数据库，其内置的行级安全策略功能更是Guild实现数据隔离的基石。通过精心设计的RLS策略，Guild确保了数据库中的每一条记录都只能被其所有者或授权角色访问。例如，一条属于“客服小李”的私人记忆，即使用户“市场小王”直接连接数据库进行SQL查询，也无法看到这条记录。安全在数据库层面就被强制执行，这比在应用层做校验要可靠得多。

第三层：外部接口层（MCP服务器与管理后台）。这是Guild的“外交官”和“控制台”。guild-mcp服务器实现了Model Context Protocol，使得Claude Desktop、Cursor等支持MCP的客户端，也能以标准化方式访问Guild管理的数据，实现了生态扩展。而独立的Admin UI则提供了一个直观的Web仪表盘，让管理员无需触碰命令行，就能完成用户管理、角色分配、技能编辑、记忆审核、策略配置等所有日常运维工作。这个控制台是团队协作不可或缺的部分，它将散落在配置文件和数据库中的信息，以可视化的方式呈现出来。

这三层架构形成了一个闭环：插件赋予智能体能力，智能体产生和消费数据，数据被安全地存储在Supabase中并通过RLS隔离，而管理员则通过MCP或Admin UI来管理和观测整个系统。这种设计既保证了核心交互的性能（插件内嵌），又提供了管理的灵活性和安全性（外部接口与数据库强隔离）。

2.3 核心概念：分层记忆与技能编排

Guild引入了两个至关重要的抽象概念：分层记忆和版本化技能。它们是实现精细化权限管理和知识复用的关键。

分层记忆模型是一个四级金字塔结构，自下而上，共享范围逐渐扩大：

1. 智能体私有记忆：仅对该智能体可见。例如，一个代码审查智能体对自己总结的“某位开发者常见的代码风格问题”的记忆。
2. 用户级记忆：对单个用户的所有智能体可见。例如，用户“张三”向智能体A透露了“我下周要去巴黎出差”，这个信息应该对张三使用的智能体B也可见，但其他用户不可见。
3. 角色级记忆：对拥有特定角色的所有用户和智能体可见。例如，“初级工程师”角色共享的“公司代码提交规范”记忆。
4. 公司级记忆：对整个组织的所有成员可见。例如，“公司价值观”或“年度假期安排”。

这种分层结构非常符合企业组织的实际情况。记忆可以通过“晋升”工作流，从下层移动到上层。比如，一个智能体私有的“高效会议技巧”如果被验证有效，可以被其用户晋升到用户级记忆；如果对整个团队都有价值，可以由管理员晋升到角色级甚至公司级。这个过程是可审计、受控的。

版本化技能系统则解决了指令集的管理难题。在Guild中，“技能”是一组可执行的指令或知识片段（比如“如何撰写一份合格的项目周报”或“处理客户退款的标准流程”）。每个技能都可以有多个版本，这允许管理员迭代改进指令而不会立即影响所有使用者。更重要的是，技能可以通过一个可视化的分配矩阵，被精确地分配给不同的作用域：可以分配给整个公司、某个特定角色、某个特定用户，甚至某个特定的智能体。

这意味着，你可以创建一套名为“客户沟通礼仪”的技能，将其v1版本分配给“销售”角色，将更详细的v2版本单独分配给资深销售“李四”。当李四与他的智能体交互时，智能体会自动获得v2版本的技能注入；而其他销售人员的智能体则获得v1版本。这种粒度控制使得知识传递既标准化又个性化。

3. 详细部署与配置指南

3.1 环境准备与前置条件

在开始安装Guild之前，你需要确保基础环境就绪。这不仅仅是安装软件，更是为后续的稳定运行打下地基。

第一，OpenClaw版本确认。Guild要求OpenClaw版本不低于2026.3.24。你可以通过运行openclaw --version来检查。如果版本过低，请务必先升级OpenClaw。我遇到过因为主程序版本不匹配导致插件钩子无法正常触发的问题，排查起来很费时间。

第二，Supabase实例准备。这是Guild的数据核心。你有两个选择：

• 本地运行（推荐用于开发和测试）：使用npx supabase start命令可以在本地快速启动一个完整的Supabase栈（数据库、认证、存储等）。这能让你完全控制环境，且没有网络延迟。启动后，记下输出的API URL（通常是http://127.0.0.1:54321）和anon key。
• 使用托管服务（推荐用于生产）：在Supabase官网创建一个新项目。生产环境务必启用网络限制，只允许你的服务器IP地址访问，并妥善保管service_role key（拥有最高权限，仅用于后台管理）。

注意：无论选择哪种方式，请确保Supabase项目的database和auth模块已启用。Guild的迁移脚本会创建所有必要的表和RLS策略。

第三，Node.js环境。确保安装了Node.js 22或更高版本。一些底层的依赖包可能需要较新的Node特性。

第四，嵌入模型服务（可选但重要）。如果你计划使用Guild的“知识搜索”功能（基于语义的向量搜索），你需要一个嵌入模型服务。Guild默认配置为使用本地Ollama服务，运行nomic-embed-text模型。你需要先安装Ollama，然后通过ollama pull nomic-embed-text拉取该模型。如果不用知识搜索，可以跳过这一步，在配置中关闭该功能即可。

3.2 插件安装与自动化配置

Guild提供了极其便捷的CLI安装方式，这是最推荐的方法。

# 1. 安装插件到你的OpenClaw环境 openclaw plugins install openclaw-guild

这条命令会从插件仓库拉取并安装Guild插件。安装完成后，你的openclaw.json配置文件中会自动添加Guild的插件条目，但此时它还未被激活配置。

核心步骤：运行设置向导。这是最关键的一步，Guild的setup命令是一个交互式向导，它会智能地引导你完成整个配置。

openclaw guild setup

这个向导会做以下几件事：

1. 检测Supabase：它会尝试连接你提供的Supabase URL和Anon Key。如果连接失败，会给出明确提示。
2. 运行数据库迁移：自动执行migrations/目录下的SQL脚本，在你的Supabase数据库中创建Guild所需的所有表、函数和行级安全策略。你可以在Supabase的SQL编辑器中查看生成的表结构。
3. 更新插件配置：将Supabase连接信息、功能开关等写入openclaw.json文件的plugins.entries.guild.config部分。
4. 引导智能体配置：它会询问你是否要为现有的OpenClaw智能体配置Guild访问权限。如果选择“是”，它会为每个智能体在Supabase的agents表中创建一条记录，并生成对应的认证信息。

为什么智能体需要“邮箱”和“密码”？这是初次接触者最困惑的一点。因为Supabase Auth的设计是基于真实用户的，没有“服务账户”的概念。为了让每个智能体能以独立的身份通过RLS策略验证，Guild为每个智能体自动生成一个虚拟的邮箱（如agent-my-coder@platform.local）和密码。这些邮箱并不用于收发邮件，仅仅是Auth系统需要的唯一身份标识。密码可以是一个随机字符串，也可以引用环境变量（如$AGENT_CODER_PWD），以提高安全性。这些凭证会安全地存储在openclaw.json的配置中。

配置完成后，使用openclaw guild doctor命令进行健康检查。这个命令会验证插件加载状态、数据库连接、智能体认证等各个环节，并给出详细的诊断报告，非常实用。

3.3 手动配置详解与高级选项

虽然CLI向导很方便，但理解手动配置的细节对于故障排查和高级定制至关重要。Guild的配置主要位于openclaw.json的plugins.entries.guild.config部分。

{ "plugins": { "slots": { "memory": "guild" // 关键！这行告诉OpenClaw用Guild接管内存槽 }, "entries": { "guild": { "enabled": true, "config": { "supabaseUrl": "http://127.0.0.1:54321", "supabaseAnonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "features": { "memory": true, // 启用记忆工具和钩子 "skills": true // 启用技能目录注入 }, "agents": { "my-marketing-bot": { // 对应你OpenClaw中定义的智能体ID "uuid": "a1b2c3d4-...", // 来自Supabase `agents`表 "email": "agent-my-marketing-bot@platform.local", "password": "$ENV_MARKETING_BOT_PASSWORD" // 推荐使用环境变量引用 } } } } } } }

几个关键配置项解析：

• "memory": "guild"：这行配置至关重要，它禁用了OpenClaw默认的基于文件的内存系统，将所有内存操作路由到Guild插件。
• features：你可以根据需要关闭某些功能。例如，如果你暂时不需要技能系统，可以设置"skills": false。
• agents配置块：每个你需要接入Guild的智能体都必须在这里注册。uuid必须与Supabase数据库中agents表的记录对应。password或jwt字段支持$ENV_VAR语法，这是生产环境的最佳实践，避免将明文密码写入配置文件。

为现有智能体提供配置：如果你已经有一些正在运行的智能体，需要手动将它们“接入”Guild。

1. 首先，在Supabase的agents表中为每个智能体创建一条记录。你可以通过Admin UI完成，或者使用SQL插入。记录创建后，会生成一个唯一的id（UUID）。
2. 然后，在openclaw.json的agents配置块中，添加该智能体的配置，填入对应的uuid。
3. 最后，使用openclaw guild provision-agent --agent-id my-marketing-bot命令，为这个智能体生成认证凭证（邮箱/密码），并更新到配置中。

3.4 管理后台与MCP服务器的部署

Admin UI部署：对于团队管理而言，Web管理后台是必需品。官方提供了Docker镜像，部署非常简单。

docker run -p 3100:3100 \ -e SUPABASE_URL=https://your-project-ref.supabase.co \ -e SUPABASE_ANON_KEY=your-anon-key \ -e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \ -e ORG_NAME="我们公司" \ ghcr.io/spiretech/openclaw-guild-admin:latest

访问http://localhost:3100即可登录。这里需要SERVICE_ROLE_KEY，因为它需要执行一些超越普通用户权限的管理操作，如创建角色、分配全局权限等。务必保护好这个密钥。

MCP服务器部署：如果你希望让Claude Desktop等外部客户端也能访问Guild管理的数据（比如让Claude直接查询公司知识库），就需要运行MCP服务器。

cd packages/mcp/guild-mcp npm install GUILD_TOOLS=memory,skills,knowledge \ SUPABASE_URL=... \ SUPABASE_ANON_KEY=... \ OLLAMA_URL=http://localhost:11434 \ node dist/index.js

GUILD_TOOLS环境变量允许你按需启用工具组。如果你的环境没有运行Ollama，可以设置为GUILD_TOOLS=memory,skills来禁用知识搜索功能。MCP服务器启动后，需要在你的客户端（如Claude Desktop）的配置文件中添加该服务器地址。

4. 核心功能实操与工作流

4.1 智能体如何与分层记忆交互

安装配置完成后，你的智能体就获得了操作分层记忆的超能力。这一切对智能体来说是透明的，它只需要调用Guild提供的工具。

记忆的读写：假设你是用户“张三”，正在与你的“项目助手”智能体对话。当你告诉它“请记住我偏好每周一下午进行项目同步会议”时，智能体可以调用guild_memory_save工具。Guild插件会根据当前会话的上下文（智能体ID、用户身份），自动将这条记忆以“用户级记忆”的身份保存到Supabase中，关联到“张三”名下。之后，无论是“项目助手”还是张三使用的另一个“文案助手”，在会话开始时，都会通过before_prompt_build钩子自动获得这条记忆的摘要，从而知道用户的这个偏好。

记忆的搜索与共享：智能体可以调用guild_memory_search在当前用户的内存中进行语义搜索。例如，用户问“我之前说过关于预算的事情吗？”，智能体可以搜索关键词“预算”，返回相关的记忆片段。如果需要获取团队知识，可以调用guild_memory_team（获取角色级记忆）或guild_memory_company（获取公司级记忆）。这些工具内部都严格执行RLS，智能体只能看到它被授权看到的内容。

自动捕获与持久化：这是Guild的两个“静默”但强大的功能。

• 自动捕获：在会话结束时（agent_end钩子），Guild会分析对话内容，自动提取关于用户的客观事实（例如“用户住在北京”、“用户养了一只猫”），并询问用户是否保存。这极大地减轻了手动记忆的负担。用户可以在Admin UI中全局关闭此功能。
• 持久化：在OpenClaw进行上下文压缩（丢弃旧消息以节省token）之前（before_compaction钩子），Guild会将当前会话中的重要上下文作为“工作记忆”保存到数据库。这样，即使原始对话被压缩了，这些关键信息也不会丢失，可以在后续对话中被“回忆”起来。

4.2 技能的创建、分配与注入流程

技能系统是标准化团队知识输出的利器。其工作流分为三步：创建、分配、注入。

第一步：创建版本化技能。管理员通过Admin UI的“技能库”页面，创建一条新技能，例如“客户需求调研问卷编写指南”。你可以编写详细的Markdown内容，包含步骤、模板、注意事项等。保存后，这就是v1版本。之后，你可以基于v1创建v2版本进行改进，而v1版本仍然可以被分配给那些尚未升级的智能体使用。

第二步：通过矩阵进行可视化分配。在技能分配页面，你会看到一个矩阵：行是技能，列是作用域（公司、角色、用户、智能体）。你可以通过勾选，轻松地将“问卷编写指南”技能分配给“销售”角色和“高级客户经理”角色。你还可以额外为资深员工“王五”单独分配这个技能。矩阵视图让你对“谁拥有什么知识”一目了然。

第三步：智能体的自动技能注入。当用户“王五”启动他的智能体时，Guild的before_prompt_build钩子会触发。它会查询数据库：王五本人有哪些技能？王五所属的“高级客户经理”和“销售”角色有哪些技能？然后，将这些技能的内容整合成一个“技能目录”，作为系统提示的一部分，注入到智能体的会话中。智能体在回答关于编写调研问卷的问题时，就会自动参考这些指南，确保输出的内容符合公司规范。

4.3 用户、角色与权限管理实战

Guild的多用户体系核心是“外部身份”与“平台用户”的链接。

1. 用户创建与身份链接：Guild本身不直接处理用户注册和密码。它利用Supabase Auth作为认证层。你的团队成员通过你已有的系统（可以是Supabase Auth的UI，也可以是你自己的应用）进行注册登录。然后，在Guild Admin UI中，管理员执行“链接用户”操作，将Supabase Auth中的用户（通过其UID）与Guild平台内的一个用户档案（包含姓名、部门等信息）绑定起来。这个用户档案会被分配一个或多个角色。

2. 角色的力量：角色是权限和记忆共享的单元。你可以创建“实习生”、“开发工程师”、“项目经理”、“部门总监”等角色。角色的核心作用有两个：一是作为技能和角色级记忆的分配目标；二是通过user_agent_grants表，控制用户对智能体的访问权限。例如，你可以设置只有“项目经理”角色的用户，才能使用“项目进度分析”这个高级智能体。

3. 智能体授权：在user_agent_grants表中，每条记录定义了哪个用户有权使用哪个智能体。当用户通过前端应用（或MCP客户端）发起请求时，请求中会携带用户的JWT令牌。Guild插件会解析令牌，确认用户身份，然后检查授权表。只有拥有权限的用户，其请求才会被路由到对应的智能体。这就实现了“不同的人使用不同的AI助手”的精细控制。

整个权限流是：用户认证 (Supabase Auth) -> 身份链接 (Guild) -> 角色分配 -> 智能体授权 (Grants表) -> 数据访问 (RLS)。环环相扣，确保了安全性。

5. 生产环境运维、问题排查与迁移策略

5.1 日常运维与监控要点

将Guild投入生产环境后，以下几个方面的运维需要你持续关注：

数据库性能与备份：Supabase是你的数据核心。随着记忆和技能条目的增长，需要关注：

• 索引：确保agent_memories,user_memories等表在user_id,agent_id,created_at等常用查询字段上建立了索引。Guild的迁移脚本通常会创建基础索引，但根据你的查询模式，可能还需要添加复合索引。
• 归档策略：并非所有记忆都需要永久活跃。可以定期（如每月）将旧的、不重要的记忆标记为archived=true。Guild的搜索工具默认会过滤掉已归档的记忆，减少查询负担。你可以写一个简单的定时任务（cron job）来执行自动归档。
• 备份：务必启用Supabase项目的定期备份功能。对于关键数据，这是最后的安全网。

智能体凭证管理：智能体的邮箱/密码凭证存储在openclaw.json中。在生产环境，必须使用$ENV_VAR引用环境变量，而不是明文。考虑使用像HashiCorp Vault或AWS Secrets Manager这样的秘密管理服务来存储这些环境变量。定期轮换这些密码也是一个好习惯。

Admin UI的访问控制：Admin UI本身是一个强大的管理工具，必须严格保护。除了使用强密码和启用Supabase的多因素认证外，建议将Admin UI部署在内部网络，或通过VPN/VPC访问，不要直接暴露在公网。同时，严格控制拥有Supabaseservice_role key的人员范围。

日志与审计：Guild设计了memory_audit表来记录关键操作。你需要定期检查这些日志，监控异常模式，例如某个智能体在短时间内进行了大量记忆读取操作。可以将Supabase的日志导出到你的集中式日志系统（如ELK Stack）进行更深入的分析和告警。

5.2 常见问题与深度排查指南

即使准备充分，在生产中也可能遇到问题。下面是一些典型场景的排查思路：

问题一：智能体报告“无法访问记忆”或“权限错误”。

• 排查步骤：
  1. 运行诊断：首先执行openclaw guild doctor。它会检查插件状态、数据库连接和智能体认证。这是最快定位问题的方法。
  2. 检查智能体配置：确认openclaw.json中该智能体的uuid是否与Supabaseagents表中的记录完全一致（包括大小写）。一个字符的错误都会导致认证失败。
  3. 验证RLS策略：以该智能体的身份（使用其邮箱/密码）直接连接Supabase的REST API或PostgreSQL，尝试查询agent_memories表。如果查询失败，说明RLS策略阻止了访问。需要检查该智能体对应的Supabase Auth用户是否确实存在且状态为confirmed。
  4. 检查钩子注入：在OpenClaw网关的日志中（日志级别设为DEBUG），查看before_prompt_build钩子是否被触发，以及它是否成功注入了技能和记忆摘要。如果钩子没执行，检查features.memory和features.skills配置是否为true。

问题二：Admin UI可以登录，但看不到任何数据或无法管理用户。

• 排查步骤：
  1. 检查环境变量：确认启动Admin UI容器时传入的SUPABASE_SERVICE_ROLE_KEY是正确的，并且拥有足够的权限。anon key权限不足，无法绕过RLS执行管理操作。
  2. 检查网络连通性：从Admin UI容器内部，使用curl测试是否能访问Supabase的rest/v1/和auth/v1/端点。
  3. 查看浏览器控制台：打开浏览器的开发者工具，查看网络请求。如果API请求返回403或500错误，根据错误信息进一步判断是密钥问题还是API路径问题。

问题三：记忆的自动捕获功能没有生效。

• 排查步骤：
  1. 检查用户设置：在Admin UI中，找到对应用户，检查其auto_capture_enabled字段是否为true。用户可能手动关闭了此功能。
  2. 检查钩子触发：agent_end钩子只在会话正常结束时触发。如果会话是因为错误或超时异常终止，钩子可能不会运行。查看网关日志确认。
  3. 检查捕获逻辑：自动捕获依赖于对对话内容的分析。如果对话非常简短或没有包含可以被识别为“用户事实”的陈述（如“我是...”、“我有...”），则可能不会触发捕获。可以尝试在更长的、包含明确事实陈述的对话后测试。

问题四：从文件内存迁移到Guild后，智能体表现异常。

• 排查步骤：
  1. 确认迁移完成：使用openclaw guild migrate dummy --all --dry-run预览后，再执行实际迁移。迁移后，检查Supabase对应的记忆表中是否有数据。
  2. 检查记忆格式：Guild的记忆存储格式可能与原来的MEMORY.md文件不同。旧的记忆被导入后，可能缺少一些Guild所需的元数据字段（如memory_type）。确保迁移脚本正确处理了格式转换。
  3. 重启网关：迁移完成后，必须重启OpenClaw网关，以确保插件重新加载并连接到包含新数据的数据源。

5.3 从单机文件内存到Guild的平滑迁移

如果你已经在使用OpenClaw原生的文件内存（MEMORY.md），迁移到Guild需要谨慎操作，以避免数据丢失和服务中断。

迁移前准备：

1. 完整备份：备份你现有的MEMORY.md文件以及整个OpenClaw配置目录。
2. 安装并基础配置Guild：按照前文步骤，完成Guild插件的安装、Supabase配置和数据库迁移。但先不要在openclaw.json中将内存槽设置为"guild"。
3. 测试空环境：在切换内存槽之前，先创建一个测试智能体，配置其使用Guild，验证基本的记忆读写功能是否正常。

执行数据迁移： Guild提供了专门的迁移命令来处理MEMORY.md文件。

# 1. 首先进行模拟运行，查看哪些数据会被迁移 openclaw guild migrate dummy --all --dry-run # 2. 确认无误后，执行实际迁移 openclaw guild migrate dummy --all

这个dummy迁移器会将MEMORY.md中的内容作为“公司级”记忆导入到Supabase中。因为原文件没有用户归属信息，所以这是最合理的默认处理方式。

切换与验证：

1. 修改openclaw.json，将plugins.slots.memory的值从原来的设置（可能是空或"memory-core"）改为"guild"。
2. 重启OpenClaw网关：openclaw gateway restart。
3. 进行验证测试：
   • 让智能体尝试读取一条你知道存在于旧MEMORY.md中的信息。
   • 让智能体保存一条新信息。
   • 通过Admin UI查看，确认新旧记忆都已存在，且新记忆具有正确的层级和归属。

回滚计划：如果迁移后出现严重问题，回滚步骤是：

1. 将plugins.slots.memory改回原来的设置。
2. 重启网关。
3. 智能体将回退到使用原来的文件内存。Guild数据库中的数据会被保留，但暂时不被使用，直到你再次切换回来并解决问题。

整个迁移过程的核心是逐步切换，充分测试。对于关键业务场景，可以考虑让新旧系统并行运行一段时间，通过双写或日志对比来确保Guild的稳定性和数据一致性，然后再完全切流。