多智能体设置演练

这是 Agents 章节 的操作端配套指南。请按照本指南为某个安装环境添加第二个 agent、配置跨 agent 的内存访问，并将两个 agent 放入同一频道上的同一对等组中。

背景：每个代理在 <install>/agents/<alias>/workspace/ 下拥有自己的工作区目录，在创建时选定一种内存后端（不可变更），并受 [risk_profiles.<profile>] 条目的限制。

在本演练中，现有的单个 agent 称为 primary（请替换为你的安装实际使用的名称），新添加的 agent 称为 researcher。

前置条件

• 已配置的 [agents.primary] 条目，包含可用的 model_provider、risk_profile 以及至少一个通道绑定。
• 新代理将继承的 [risk_profiles.<name>] 条目。对于大多数用途，复用 primary 的配置即可；如果新代理具有不同的信任面，请选择更严格的别名（例如 hardened）。

添加第二个 agent

通过网关仪表板、zerocode 或 zeroclaw config set 添加另一个 agent。运行时会在首次进入 agent 循环时创建 <install>/agents/<alias>/workspace/。每次启动时，agent 循环都会将存在的工作区身份文件注入系统提示中：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md，然后是 BOOTSTRAP.md（仅首次运行）和 MEMORY.md（仅主会话）。HEARTBEAT.md 也是一个工作区个性文件，但它由心跳引擎读取，而不会注入提示中。仪表板的个性编辑器开放了 SOUL.md、IDENTITY.md、USER.md、AGENTS.md、TOOLS.md、HEARTBEAT.md 和 MEMORY.md 供编辑。创建并编辑这些文件以赋予 agent 其角色设定。（BOOTSTRAP.md 是一个首次运行的脚手架文件，agent 读取一次后会将其删除；编辑器不会开放它。）

绑定通道

没有通道，代理就无处监听。请通过代理的 channels 列表绑定一个通道，然后重启守护进程。代理将在下次启动时获取其通道。

跨代理文件访问

默认情况下，一个 agent 只能在自己的 workspace 目录内读写。你可以授予某个 agent 对另一个 agent workspace 的读取或写入权限（通过 gateway、zerocode 或 zeroclaw config set 进行配置）。实际行为示例，例如 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/。

POSIX 设备文件（/dev/null、/dev/zero、/dev/random、/dev/urandom）始终可读，无需为每个 agent 单独配置。

跨代理内存访问

仅限相同后端。要让 researcher 调用 primary 写入的记忆，两个代理必须使用相同的记忆后端（例如均使用 sqlite）。模式验证器会拒绝指向位于不同后端的同级条目；当运行时构建每个代理的记忆包装器时，它绝不会看到跨后端的允许列表。

绑定的代理始终能看到自己的行；白名单纯粹是附加性的。无法对代理_隐藏_它自己的行。

共享通道上的对等组

两个 agent 只有在同时出现于同一对等组中时，才会成为“对等节点”（彼此可在通道上寻址）。参见 Peer Groups。

external_peers 列出群组预期在同一频道中出现的人类或外部机器人；运行时会将来自这些用户名的入站消息作为跨代理流量接受。ignore 是按群组设置的屏蔽列表，会从每个成员看到的已解析对等集合中移除相应成员，可用于排除某个噪声较多的特定机器人账户。

配置加载时的架构验证器强制执行以下规则：

1. 每个成员的 channels 列表都包含该组的 channel（不在那里监听的 agent 无法在那里建立对等连接）。
2. 每个成员都是已配置的代理（不存在悬空引用）。
3. read_memory_from 未指向智能体本身。

检查安装

每个已配置的 agent 都位于 agents.<alias> 条目下，包含其风险配置、模型提供方、内存后端和通道集。

zeroclaw agents 生命周期命令仅在启用了 gateway 和 agent-runtime 的构建版本中（包括标准分发的二进制文件）执行完整的自有状态级联操作。功能精简的 CLI 仍会更改配置，但会提示自有状态未被级联。当存在自有状态时，请使用 gateway 仪表板或同时启用了这两项功能的二进制文件来执行以下操作。

重命名代理

在网关仪表板的 Config > Agents 下使用该代理的重命名控件，或运行：

zeroclaw agents rename researcher analyst

两个界面都会将引用重写为别名、持久化配置、移动每个别名的默认工作区，并重新指向所拥有的 memory、cron、ACP 和会话状态。自定义工作区路径不会移动，因为它们不是从别名派生的。保留的 default 别名无法重命名，也无法被重命名为该名称。

读取响应中的任何警告。配置重命名在工作区和所有者状态迁移之前提交，因此警告用于识别仍需处理的副作用。可以重新发出相同的 gateway API 重命名请求，以重试遗留在旧别名下的残留内容。

删除代理

使用 Config > Agents 下的删除控件，或预览并应用 CLI 操作：

zeroclaw agents delete researcher --dry-run
zeroclaw agents delete researcher --yes

1. 查看影响预览并清除其报告的每个阻塞项。常见的配置阻塞项包括该代理拥有的已启用心跳，以及没有其他已启用代理拥有的已启用通道绑定。预览还会列出级联操作将自动移除的软引用。
2. 结束所有活跃的 ACP 会话。仪表板会在预览中包含它们；CLI 在 --yes 执行时会验证它们，此前会先进行仅配置的 --dry-run 预览。
3. 确认删除仪表板，或使用 --yes 运行 CLI 命令。该操作会先从配置中移除 agent 及软引用，然后运行所属状态的级联删除。
4. 在依赖归档或清理结果之前，请检查 <data_dir>/agents/_deleted/<alias>-<timestamp>/ 和网关日志。

自有状态级联尝试执行以下操作：

• 将已配置的工作区移入删除归档；
• 将导出的 memory、cron 和 ACP 数据写入 cascade/；
• 清除代理的内存行和 cron 作业；
• 移除其非活动 ACP 会话；
• 从保留的会话中清除代理归因；以及
• 写入包含计数和已显示警告的 manifest.json。

这些副作用属于尽力而为。导出或归档文件写入可能失败，而后续清理操作仍会继续执行。请验证适用的 workspace/、cascade/*.json 和 manifest.json 条目，而不是假设归档已完整。CLI 会打印浮出的级联警告。删除 API 同样会返回这些警告，但控制台目前不显示它们；控制台运营人员还必须检查网关日志。

不要将此流程替换为直接编辑 TOML、zeroclaw config set、手动删除工作区或 SQL 删除。这些路径不会运行网关的引用和自有状态级联。

没有自动还原命令。请保留删除存档，直到您不再需要对其进行检查或手动恢复为止。

验证

查看合并的日志流；现在每一行都应带有 [<alias>] 或 [system] 前缀：

zeroclaw daemon 2>&1 | grep '\[researcher\]'   # 仅 researcher 的行
zeroclaw daemon 2>&1 | grep '\[system\]'       # 仅限引导/迁移/调度器行

如果边界检查正常工作，从任何代理执行 file_read /dev/null 都会成功（POSIX 设备文件白名单），而在工作区和访问列表之外执行 file_read 则会失败并提示 Path escapes workspace directory，向只读白名单同级目录执行 file_write 也会失败并显示相同的消息。