ADR-007：将网关提取为独立的可选进程

上下文

ZeroClaw 的 HTTP、WebSocket、webhook 和仪表板界面已有专用的 zeroclaw-gateway crate。主应用程序仍然在 gateway 特性下，在进程内链接并启动该 crate。crate 边界改进了代码所有权，但它并不提供进程隔离，也无法让操作员独立于代理运行时来运行、重启、升级或省略 Web 界面。

运行时也有一个 JSON-RPC 接口面，但外部网关所需的完整且稳定的本地契约、传输层、身份验证模型、兼容性策略和进程监管尚未作为一个受支持的边界整体交付。因此，当前的 crate 和 RPC 接缝是有用的迁移步骤，而不是进程抽离已完成的证明。

备选方案是将进程内特性门控的 crate 视为最终架构，或者将网关设为一个独立的可选进程，通过显式的本地 IPC 契约与运行时连接。

决策

我们将把网关设计为一个独立的可选 zeroclaw-gw 进程。

代理运行时对代理执行、会话、内存、配置、工具、安全策略及其他领域状态保持权威性。网关负责外部 HTTP 与流式协议、仪表板交付、配对与传输层相关事务，以及通用 Webhook 入口。网关必须通过受支持的 IPC 契约请求运行时操作，而不得直接访问进程本地运行时状态。

运行时到网关的 IPC 边界必须经过身份验证、版本化并有文档记录。传输方式的选择可能因平台而异，但默认连接必须保持在本地，且不得在公共接口上悄然暴露运行时控制面。

当前受功能门控的进程内 zeroclaw-gateway crate 是一个过渡性衔接层。在构建 IPC 对等能力和进程生命周期支持期间，它可以继续保留，但新架构不应将直接访问运行时内部实现作为网关的永久性要求。

运维人员必须能够在没有 zeroclaw-gw 的情况下运行代理。网关故障或重启不得终止本来正常运行的代理执行。

此 ADR 在满足以下所有条件之前仍处于提议状态：

受支持的 zeroclaw-gw 二进制文件通过已记录的本地 IPC 契约与运行时通信；
IPC 边界涵盖了受支持的仪表板和 API 体验所需的网关功能，而无需直接访问进程本地状态；
身份验证、版本协商、重连、健康检查、启动和关闭行为均已实现并记录在文档中；以及
受支持的运行时发行版可以在不链接或启动网关服务器的情况下运行。

后果

积极后果：

无头和受限部署可以完全省略 Web 界面。
网关的崩溃、重启和升级与代理执行相互隔离。
IPC 契约为桌面应用程序和其他受信任的本地客户端提供了明确的集成边界。
运行时和网关的所有权变得更易于测试和推理，因为跨边界访问是显式的。

负面后果：

多进程安装、启动、身份验证、日志记录和诊断比进程内函数调用更复杂。
流式处理和大型负载必须跨越序列化边界。
当运行时版本与网关版本可能不同时，必须提供兼容性策略。
在实现完全对等之前，维护者必须同时支持当前的进程内接缝和目标进程边界。

参考文献

ADR-002：基于 trait 的可扩展性
FND-001: Intentional architecture
Crate 映射图
Channel runtime lifecycle
Gateway API
ADR-006 和 ADR-007 的方向决策
crates/zeroclaw-gateway
crates/zeroclaw-runtime/src/rpc
crates/zeroclaw-api/src/jsonrpc.rs

Keyboard shortcuts

ZeroClaw Docs

ADR-007：将网关提取为独立的可选进程

上下文

决策

后果

参考文献