运行时内部机制

本页是 Agents 部分其余内容的架构深入补充，介绍运行时如何执行每个智能体的权限、划分记忆作用域以及归因日志。如需配置和运行智能体，请从 Agents 开始；如需架构级字段参考，请参阅 Config；如需实际设置步骤，请参阅 Multi-agent setup。

权限模型

每个智能体的有效 SecurityPolicy 由 SecurityPolicy::for_agent(config, alias) 构建：

从智能体的风险配置文件（[risk_profiles.<profile>]）开始。
将边界设置为每个代理的工作区目录（<install>/agents/<alias>/workspace/）。
遍历 [agents.<alias>.workspace.access]：
- Read（读取）→ 同级的工作区会进入只读白名单。
- Write → 同级工作区会被加入仅写入允许列表。
- ReadWrite → 同级工作区会被加入读写白名单。
如果 [agents.<alias>.workspace.unrestricted_filesystem] 为 true，请关闭 workspace_only。

只读允许列表由 file_read 以及其他读取侧工具执行，包括 git_operations 的 status、diff、log、branch、stash-list 和 worktree-list 命令。worktree list 仅返回那些 worktree 路径可解析、且其 Git 元数据可通过适用的读取授权验证的条目。读写允许列表控制 file_write、file_edit、被归类为写操作的 git_operations 命令（包括 worktree add/remove/prune），以及 shell 工具中涉及路径的调用。仅写的同级工作区不可供 git_operations 使用：Git 在执行任何操作前必须先读取仓库元数据。worktree 目标以及关联 worktree 的 .git/gitdir/commondir 元数据必须位于适用的授权范围内。git_operations 会拒绝该元数据中任何位置的符号链接，而不会跟随它们，即使其最终目标原本是被允许的。Git 调用会丢弃继承的 GIT_* 变量；请在仓库或全局 Git 配置中设置提交身份，而不是使用环境变量。只读命令会抑制仓库配置的可执行集成以及 mailmap 身份解析；其固定的日志格式还使用原始作者字段，因此这些命令从不读取 .mailmap 或 mailmap.file。它们禁止 Git 传输，并禁用隐式的 promisor 对象抓取，因此需要不可用的部分克隆对象的读取会失败，而不会启动由仓库选择的传输。当操作者授予读写权限时，写命令会保留常规的 Git hooks 和 filters，并应用每个代理配置的沙箱边界。在 [runtime] kind = "docker" 下，被归类为写操作的 git_operations 命令会在启动任何写操作类 Git 命令之前被拒绝，因为 Git 不会进入运行时容器；读操作类命令不受影响，shell 工具仍是容器内的命令路径。在原生运行时模式下，空操作（no-op）沙箱因此不会限制 Git。只有 Landlock 后端会将该沙箱扩展到已配置的同级根目录；其他沙箱后端可能拒绝工作区之外的写入、以只读方式挂载工作区、省略工作区，或隐藏全局 Git 配置。后端行为详见沙箱机制。POSIX 设备文件（/dev/null、/dev/zero、/dev/random、/dev/urandom）始终可读，因此 shell 惯用写法无需按代理单独配置即可正常工作。

SubAgent 生成会强制执行子代理不能超越其父代理权限的规则。验证器的完整轴列表和预算共享行为记录在委派 → 权限继承。

单工具轮次

单轮工具调用模式下，每次提供方响应最多只包含一个原生工具调用。现有的代理循环会执行该调用、记录其结果，并在同一用户轮次内向提供方请求下一次响应。模型可以在调用之间输出叙述性文字，但这不是 ZeroClaw 的要求，也不由 ZeroClaw 生成。

此模式默认关闭。在 ZeroCode Config 中，将 runtime_profiles.<profile>.single_tool_rounds 设为 true，并通过 agents.<alias>.runtime_profile 选择该配置档。未设置该值或设为 false 时，保持批量行为。该设置与 parallel_tools 相互独立：parallel_tools 控制已接纳批次的执行并发度，而不是提供方可返回的调用数量。

仅支持的提供商路由会激活该策略。如果所选路由或任何可达的回退路由不支持该策略，ZeroClaw 会保持批处理行为，并在每轮对话中显示一次限制提示。在策略生效期间，若某个响应包含多个原生或恢复的工具调用，该响应会在这些调用执行或写入工具交换历史之前失败。被拒绝的提供商请求所产生的用量仍计入 token 和成本统计。流式输出的叙述内容可能已经显示；ZeroClaw 不会重放违规的响应。

工具审批、回执、取消和迭代上限保持现有行为。顺序调用可能需要更多的提供方请求，增加延迟，并更快达到 max_tool_iterations。如需回滚，请在所选运行时配置文件中将 single_tool_rounds 设为 false 或取消设置。

内存模型

每个智能体都有自己的 Arc<dyn Memory> 实例。该工厂（zeroclaw_memory::create_memory_for_agent）会根据后端类型进行分发：

SQLite / Postgres / Lucid：共享的全局安装存储。agents 表将别名映射到 UUID，memories 表中的 agent_id 引用该 UUID。工厂会将内部后端包装在 AgentScopedMemory 中，它通过 store_with_agent 在每次存储时写入绑定 agent 的 UUID，并通过 recall_for_agents 使用解析后的允许列表过滤每次召回。结构化授权还可以将每个同级 agent 进一步过滤为精确的类别名称；绑定的 agent 始终可以看到它自己的所有类别。
Markdown：按代理划分的目录。每个代理的 MarkdownMemory 会写入 <install>/agents/<alias>/workspace/MEMORY.md 和 memory/YYYY-MM-DD.md。由于 Markdown 不保留逐行的自定义类别，配置校验器和工厂会拒绝针对该后端的按类别授权；仅接受不受限制的同级授权。包装器仍会对任何直接构造的对等实体进行防御性过滤。
Qdrant：共享集合，按 payload 建立键。agent_id payload 字段用于标识各个 agent 的归属；recall_for_agents 会过量获取数据，并根据 payload 进行后置过滤。
None：空操作存根。包装器仍然存在，以保持运行时路径统一。

不支持跨后端的跨智能体记忆：配置加载时的 schema 校验器会拒绝指向不同后端上同级智能体的 read_memory_from 条目。类别授权为精确匹配且不具传递性；未知类别不匹配任何行。

重命名和删除生命周期

请使用网关仪表盘的代理控制项或专用的 zeroclaw agents CLI 执行重命名和删除。在启用 gateway 和 agent-runtime 的标准构建中，这两个界面都会执行引用和所属状态的级联处理；直接在 TOML 中移除或重新设置 agents.<alias> 的键名，或通过通用配置设置器执行此操作，则不会进行级联处理。功能精简版 CLI 仍会更新配置引用，但会警告所属状态未进行级联处理，因此执行生命周期操作时，请使用同时启用这两项功能的构建版本。

两种操作都会先将配置更改持久化，然后再执行自有状态副作用。重命名会先重写配置引用，然后移动每个别名的默认工作区，并更新记忆、cron、ACP 和会话状态的指向。删除会先拒绝处理存在硬引用或活跃 ACP 会话的情况，然后移除配置条目和软引用，再尝试执行工作区归档、自有状态导出与清理，以及清除会话归属信息。

持久化后的副作用是尽力而为的，并会报告已暴露的失败，但归档文件写入失败可能只会出现在网关日志中。重命名警告表示需要重试同一个网关 API 重命名操作，以收敛旧别名下遗留的残留内容。删除后，在依赖归档进行恢复之前，请先验证归档内容和日志。不支持自动恢复。

See 多智能体设置指南了解当前的控制项、阻塞项、归档结构和运维检查。

今天不支持

跨后端跨代理内存访问（例如 SQLite 代理读取 Postgres 代理的行）。
从 agent 删除存档中自动恢复。
每个 agent 的密钥命名空间隔离：存在一个工作区范围的 SecretStore。
用于跨代理作用域的 Lucid 线格式扩展。