工作原理
本页从概念层面讲清 swarmx 如何运行你的 CLI、多个 agent 如何协作，以及它对隐私与安全的处理方式。想深入某一部分，可继续阅读编排器与角色、黑板与收件箱、唤醒机制、工作方向与隔离。
定位
swarmx 在伪终端（PTY）中原样运行你已安装的 claude、codex、opencode、reasonix 二进制，并让它们通过共享收件箱与黑板协作，完成同一任务。它不是又一个模型客户端——鉴权、限流与套餐额度的行为，与你在终端里直接使用这些工具完全一致。
三层结构
swarmx 自下而上分为三层，各层职责单一：
| 层 | 职责 |
|---|---|
| 终端层 | 未经修改的 CLI 二进制运行于 PTY 之上。鉴权、限流与用量行为与终端环境一致，凭证始终由 CLI 自身管理。 |
| 适配层 | 一个极薄的包装进程负责启动 CLI，并向服务端上报「已就绪」与「已退出」两个生命周期信号。 |
| 工具层 | 协作能力以原生 MCP 工具的形式暴露给模型：发送消息、读写黑板、派发 worker 等。模型像调用任何其他工具一样调用它们。 |
在此之上，一个基于 Rust 的服务端（仅监听本地回环地址）统筹进程生命周期、收件箱、黑板、会话录制与唤醒调度。前端是浏览器仪表盘，为每个 agent 建立实时终端连接，并通过一条事件流接收状态与消息更新。
数据流
以创建一个 agent 为例：
- 浏览器向服务端请求创建 agent，指定使用的 CLI 与工作目录。
- 服务端为该 agent 写入 MCP 与钩子配置，随后在 PTY 中启动 CLI。
- CLI 就绪后，服务端向所有前端广播状态，并开始将终端字节流录制为可回放的会话文件。
- 浏览器为该 agent 建立一条 WebSocket 实时终端连接；另有一条事件流持续接收状态与消息更新。
- 运行中的模型通过 MCP 工具发送消息、读写黑板，这些调用最终由服务端处理并持久化。
协作的两种载体
多个 agent 之间不共享上下文窗口，而是通过两种显式载体协作：
- 黑板——一块支持全文检索与版本历史的共享键值存储，承载结构化产物与共享上下文，写入会即时唤醒订阅者。
- 收件箱——点对点消息，承载「发生了某事」的信号，触发接收方在下一回合读取并回应。
详见黑板与收件箱。
唤醒
编码 CLI 通常「处理完一个回合即停下等待」。swarmx 通过两条路径让停下的 agent 在需要时重新开工：回合结束时的检查，以及黑板键被写入时的即时唤醒。无需轮询，也不会因互相等待而死锁。详见唤醒机制。
编排器与角色
每条工作线由一个常驻的编排器（队长）负责：它扫描项目、维护计划、按任务规模派发 worker。worker 从一份内置角色目录中实例化，各有其擅长的职责与默认引擎。详见编排器与角色。
各引擎差异
不同 CLI 的驱动方式不同，但仪表盘对外呈现的是统一的 agent 视图：claude、codex 以 PTY 终端运行；opencode 是全屏终端界面，经其官方控制接口驱动；reasonix、zulu 是无界面的 HTTP/SSE 服务。逐个引擎的传输方式、鉴权与自动唤醒能力见引擎参考。
隐私与安全边界
- 服务端仅绑定
127.0.0.1，不对外暴露；中间件拒绝所有非本地来源的请求。 - swarmx 不读取、也不存储任何登录凭证——它只将
HOME透传给子进程，复用 CLI 已有的登录状态。 - 启动子进程时从空白环境构建变量，避免将敏感变量泄漏给 CLI。
更完整的数据落盘位置与隐私说明见数据与隐私。
打包与运行时资源
桌面版通过 Tauri 打包，服务端及其配套二进制以内嵌方式随包分发，所需的内置资源在编译期一并打入。因此用户下载、安装、打开即可使用，不依赖任何仓库目录或手动配置。运行参数可通过环境变量调整，详见配置项。