ZeroClaw 多智能体实战指南添加第二智能体、跨智能体文件/记忆访问与对等组配置【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 是一个可部署在任意操作系统与平台上的 AI 个人助手基础设施其核心设计理念是多智能体从第一行配置开始——不存在特权的那个 Agent运行时持有的是一个按别名alias索引的智能体映射单智能体安装只是大小为 1 的映射。本文基于官方运维指南 multi-agent-setup.md完整走通一条多智能体部署链路为现有安装添加第二个智能体、为其配置人格与渠道、授予跨智能体文件与记忆访问权限、将两个智能体放进同一渠道的对等组peer group最后介绍重命名与删除的运维流程与验证方法。读完本文你将掌握用 gateway 仪表盘、zerocode 桌面端或zeroclaw config set三种界面完成多智能体布线的全部实操细节并理解其背后的配置校验与源码级安全边界。背景每个智能体是什么在动手之前需要先理解 ZeroClaw 中智能体的组成。根据 agents/overview.md 的阐述一个智能体不是一个可安装的程序而是一行命名记录[agents.alias]它把两个半边**连接join**在一起配置引用关系侧指向配置在别处的各种指针——模型提供方、风险档案、运行时档案、渠道、对等组、技能/知识/MCP 包、定时任务。每个都是点分别名dotted alias。智能体不拥有这些资源只引用它们多个智能体可以共享同一个引用也可以各自独立。文件系统组件磁盘侧每个智能体私有的 workspace 目录、记忆后端memory backend和身份人格来源。这里是关系图落到具体目录树的地方。从 filesystem.md 可以看清磁盘布局按作用域组织而非一棵扁平树install/ ├── data/ — 实例级状态不属于任何单个智能体 │ ├── sessions/ — 聊天会话存储 │ ├── state/ — 运行时状态成本、跟踪等 │ ├── devices.db — 配对设备元数据 │ └── memory/ — 共享实例记忆 ├── shared/ — 各智能体共同使用的资源 │ └── skills/bundle/ — 技能包 └── agents/ — 每个智能体的私有数据 └── alias/ └── workspace/ — 该智能体的文件系统沙箱 └── memory/ └── brain.db多智能体实战涉及的关键约束有三条也是本 walkthrough 的背景每个智能体拥有自己的工作目录install/agents/alias/workspace/每个智能体在创建时选定一个记忆后端一旦落盘写入数据后端就被锁定不可静默切换每个智能体受[risk_profiles.profile]条目的门控。下文沿用官方指南的命名约定现有单智能体叫primary请替换为你安装中实际使用的别名新增的智能体叫researcher。前置条件开始前请确认你的安装满足存在一个配置好的[agents.primary]条目带有可用的model_provider、risk_profile以及至少一个渠道绑定存在一个新智能体将继承的[risk_profiles.name]条目。多数场景直接复用primary的档案即可如果新智能体的信任面trust surface不同建议选更严格的别名例如hardened。从源码看[agents.alias]块反序列化为AliasedAgentConfig见 crates/zeroclaw-config/src/schema.rs 中的定义其字段除了model_provider、risk_profile、channels之外还包括enabled设为 false 可禁用而不删除定义、runtime_profile、skill_bundles、knowledge_bundles、mcp_bundles安全默认只授予该智能体 bundle 中点名的 MCP 服务器、acp_enable_mcp以及 cron 任务别名等。这意味着一个新智能体不仅可以从零配置也可以按需组合引用任意已存在的提供方与档案。添加第二个智能体通过 gateway 仪表盘、zerocode 或zeroclaw config set添加另一个智能体。运行时会在**首次进入智能体循环agent loop**时创建install/agents/alias/workspace/。用 workspace 身份文件定义人格每次启动时智能体循环会把已存在的workspace 身份文件注入系统提示词注入顺序为AGENTS.mdSOUL.mdTOOLS.mdIDENTITY.mdUSER.mdBOOTSTRAP.md仅首次运行时注入MEMORY.md仅主会话注入需要特别说明的文件HEARTBEAT.md也是 workspace 人格文件但它由心跳引擎读取不会注入提示词BOOTSTRAP.md是首次运行的脚手架文件智能体读取一次后即删除人格编辑器不暴露它仪表盘的人格编辑器暴露SOUL.md、IDENTITY.md、USER.md、AGENTS.md、TOOLS.md、HEARTBEAT.md、MEMORY.md供编辑。创建并编辑这些文件即可赋予新智能体独特的人格。身份的来源方式由agents.identity配置决定详见 agents/filesystem.md默认格式读取上述项目人格文件备选格式加载 AIEOS JSON 定义相对于 workspace 的路径或内联。配置位置所有已配置的智能体都位于agents.alias条目之下其风险档案、模型提供方、记忆后端与渠道集合一目了然。每个[agents.alias]TOML 块都会反序列化为一个AliasedAgentConfigConfig::validate()会对悬空引用直接报错fail loud。绑定渠道没有渠道智能体就无处聆听。在智能体的channels列表中绑定一个渠道然后重启守护进程daemon。智能体将在下次启动时拾取它的渠道。渠道绑定在配置层面即被校验[peer_groups.name]的每个成员的channels列表必须包含该组的channel——不监听该渠道的智能体不可能在那里成为对等体详见下文对等组一节。跨智能体文件访问默认情况下智能体只能在自己的 workspace 目录内读写。你可以通过 gateway、zerocode 或zeroclaw config set授予某个智能体对另一个智能体 workspace 的读或写权限。权限模型与配置形态底层实现位于 crates/zeroclaw-config/src/multi_agent.rs 的AgentWorkspaceConfig结构配置前缀agent_workspace字段含义path显式 workspace 路径None表示派生自install/agents/alias/workspace/access跨智能体 workspace 白名单BTreeMapAgentAlias, AccessMode空映射表示不授予任何兄弟访问权unrestricted_filesystem逃生舱为true时智能体可读写主机文件系统允许的任何位置默认关闭开启可审计read_memory_from跨智能体记忆白名单见下一节AccessMode是三种模式的枚举序列化为 snake_caseRead仅读——允许跨智能体file_read禁止写入Write仅写——允许跨智能体file_write禁止读取ReadWrite读写——可对目标 workspace 执行file_read和file_write。生效行为示例假设researcher被授予对primary的写权限、对archivist的读权限则来自researcher的file_read可以读取install/agents/primary/workspace/和install/agents/archivist/workspace/来自researcher的file_write和file_edit可以写入install/agents/primary/workspace/但不能写入install/agents/archivist/workspace/。测试代码agent_workspace_config_round_trips_with_access_map同文件印证了 TOML 形态unrestricted_filesystem false read_memory_from [beta] [access] beta read gamma read_writePOSIX 设备文件的特殊待遇POSIX 设备文件/dev/null、/dev/zero、/dev/random、/dev/urandom始终可读无需任何按智能体的配置。这是有意的白名单例外file_read /dev/null从任意智能体调用都应成功。跨智能体记忆访问跨智能体记忆访问仅限相同后端。要让researcher召回primary写入的记忆两者必须使用相同的记忆后端例如都是sqlite。schema 校验器会拒绝指向不同后端兄弟条目的配置到运行时为每个智能体构建记忆包装器时跨后端的白名单根本不会出现。记忆后端由AgentMemoryConfig.backend选择见 multi_agent.rsMemoryBackendKind枚举包含后端说明none无记忆召回返回空存储为空操作sqlite内嵌 SQLite新安装默认值每个受支持平台都无需额外服务即可运行postgresPostgreSQL可选 pgvectorfeaturememory-postgresqdrantQdrant 向量存储markdownworkspace 中的 Markdown 文件lucid本地 SQLite 外部 Lucid CLI 的混合模式新智能体默认sqlite一旦有落盘数据后端即被锁定。授权形态全量字符串形式 vs 分类限定的结构化形式read_memory_from中的每一项是MemoryGrantuntagged 枚举兼容两种 TOML 形态。旧版字符串形式授予全部类别read_memory_from [primary]最小权限共享时对每个源智能体使用一条类型化授权并列出可被召回的精确类别名read_memory_from [ { agent primary, categories [core, family] }, ]规则要点源码MemoryGrant::categories()返回None表示无限制省略categories字段 不受限制显式空的类别列表会被拒绝未知类别名匹配不到任何东西精确匹配授权不可传递兄弟智能体自己的授权不会扩大调用方的可见范围分类限定授权要求后端保留逐行类别Markdown 后端在校验阶段和记忆工厂构建阶段都会拒绝这类授权它的文件不携带该归属信息。此外被绑定的智能体始终能看到自己的行白名单纯粹是增量additive的。没有任何办法让智能体隐藏自己的行。memory_grant_round_trips_legacy_and_scoped_forms测试multi_agent.rs 内验证了混合形态的解析[beta, { agent gamma }, { agent delta, categories [family, events] }]会正确解析为无限制与分类限定两种授权并存。共享渠道上的对等组只有当两个智能体同时出现在同一个对等组中它们才成为对等体peer即可以在渠道上互相寻址。详见 channels/peer-groups.md。组内字段[peer_groups.name]块的字段源码PeerGroupConfig配置前缀peer_group字段含义channel渠道类型如telegram作用于该类型的所有别名或点分渠道别名如telegram.work仅作用于该实例agents按别名的成员智能体两个智能体只有同时出现在同一组中才算对等成员关系是互惠的external_peers按渠道原生用户名/ID 的非智能体成员[*]接受任何人空则谁都不接受ignore每组的屏蔽名单从每个成员看到的已解析对等集合中扣除适用于排除某个吵闹的特定 bot 账号output_modality组内首选回复模态mirror随输入而定默认、voice总是用 TTS 语音回复并投递主动消息、text总是文本admin_for_agent_scope为true时组的external_peers被授权在绑定的智能体上执行/model --agent model默认false默认拒绝external_peers列出组期望在同一渠道上看到的人类或外部 bot运行时把来自这些用户名的入站消息当作跨智能体流量接受。加载时的 schema 校验schema 校验器在配置加载时强制执行对应指南中的四条也是 peer-groups.md 与源码校验路径的共同契约每个成员的channels列表必须包含组的channel不在那里监听的智能体不能在那里对等每个成员都必须是已配置的智能体不允许悬空引用read_memory_from不能指向智能体自身每个源智能体在read_memory_from中至多出现一次把该源的所有类别合并进同一条授权。解析过程对某个智能体而言运行时遍历它出现的每个组把其他成员的别名作为智能体对等体与组的external_peers在组渠道上取并集再减去ignore名单最后防御性地移除智能体自身的别名以避免自环。未加入任何对等组的智能体独立运行无跨智能体派发。匹配会剥离前导并针对渠道原生发送者标识做大小写不敏感比较。检查安装与生命周期命令的注意事项每个已配置的智能体都位于agents.alias条目下带有其风险档案、模型提供方、记忆后端与渠道集合。可通过 gateway 仪表盘Config Agents页面或 CLI 检视。重要前提zeroclaw agents生命周期命令只有在同时启用了gateway与agent-runtime特性的构建中才会执行完整的自有状态级联owned-state cascade标准分布式二进制满足此条件。功能裁剪的 CLI 仍然会修改配置但会打印自有状态未级联的提示。当存在自有状态时请使用 gateway 仪表盘或同时启用两个特性的二进制执行下述操作。重命名智能体使用 gateway 仪表盘Config Agents下该智能体的重命名控件或运行zeroclaw agents rename researcher analyst两种界面都会重写指向该别名的引用、持久化配置、移动默认的按别名 workspace、并重新指向自有记忆、cron、ACP 与会话状态。自定义 workspace 路径不会移动因为它们不是从别名派生的。保留别名default不能被重命名到它也不能从它重命名。务必阅读响应中的任何警告。配置重命名先于 workspace 与自有状态迁移提交因此警告标识的是一个仍需要注意的副作用。同一 gateway API 重命名请求可以重新发起以重试旧别名下遗留的残留项。删除智能体使用Config Agents下的删除控件或预览并应用 CLI 操作zeroclaw agents delete researcher --dry-run zeroclaw agents delete researcher --yes完整流程分四步审阅影响预览并清除它报告的每个阻塞项。常见的配置阻塞项有由该智能体拥有且处于启用状态的心跳heartbeat、以及没有任何其他启用智能体拥有的启用渠道绑定。预览还会列出级联将自动移除的软引用。结束任何存活的 ACP 会话。仪表盘会把它们包含在预览中CLI 在--yes执行时即配置-only 的--dry-run预览之后验证它们。确认仪表盘删除或带--yes运行 CLI 命令。操作先从配置中移除智能体与软引用然后运行自有状态级联。在依赖归档或清理结果之前检查data_dir/agents/_deleted/alias-timestamp/与 gateway 日志。自有状态级联会做什么级联是尽力而为best-effort的它依次尝试把已配置的 workspace 移入删除归档在cascade/下写出导出的记忆、cron 与 ACP 数据清除该智能体的记忆行与 cron 任务移除其非存活的 ACP 会话清除保留会话上的智能体归属attribution写出带计数与浮出警告的manifest.json。这些副作用都可能失败——某个导出或归档文件写入失败时后续清理仍会继续。因此要核对对应的workspace/、cascade/*.json与manifest.json条目而不是假定归档完整。CLI 会打印浮出的级联警告删除 API 也返回它们但仪表盘目前不显示仪表盘运维人员必须同时查看 gateway 日志。网关侧的级联入口位于 crates/zeroclaw-gateway/src/api_config.rsdelete_agent_cascade路径它把配置删除与自有非配置状态记忆/cron/ACP的清理串在一起。不要用直接 TOML 编辑、zeroclaw config set、手动删除 workspace 或 SQL 删除来替代上述流程——那些路径不会运行 gateway 的引用与自有状态级联。另外没有自动化的恢复命令。请保留删除归档直到你不再需要它用于检查或手动恢复。验证多智能体安装查看合并日志流每一行现在都应带有[alias]或[system]前缀zeroclaw daemon 21 | grep \[researcher\] # 只看 researcher 的行 zeroclaw daemon 21 | grep \[system\] # 只看启动/迁移/调度器行边界检查是否生效可以这样验证从任意智能体执行file_read /dev/null应成功POSIX 设备文件白名单对 workspace 访问名单之外的路径执行file_read应失败并报Path escapes workspace directory对只读白名单兄弟执行file_write也应失败并报同样的消息。该错误消息在 crates/zeroclaw-runtime/src/tools/file_read.rs 与deliver_file.rs中产生是文件沙箱边界的关键证据。系统级的多智能体端到端场景在 tests/system/multi_agent_e2e.rs 中有覆盖可作为你部署后的回归参考。小结一次多智能体布线的完整检查单[agents.researcher]已配置model_provider、risk_profile与channels与primary可共享提供方风险档案可不同workspace 身份文件SOUL.md、IDENTITY.md、USER.md、AGENTS.md、TOOLS.md、HEARTBEAT.md、MEMORY.md已就位守护进程已重启如需跨智能体文件访问在access中按read/write/read_write授予兄弟权限如需跨智能体记忆两端使用同一记忆后端用read_memory_from的字符串或{ agent, categories }形式授权注意分类限定仅适用于保留逐行类别的后端如需互相对等两个别名同时出现在同一个[peer_groups.name]的agents中且组channel是双方channels都监听的渠道重命名用zeroclaw agents rename删除用--dry-run预览后--yes执行并检查data_dir/agents/_deleted/与 gateway 日志。遵循这一链路你的安装将从单智能体映射平滑演化为多个职责独立、边界清晰、可互相协作的智能体集群——这正是 ZeroClaw 多智能体架构从第一天就设计好的用法。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考