在分布式 AI 代理系统的构建中，跨机器通信始终是工程实践的核心挑战。与单机器多代理协同框架不同，真正的分布式代理编排需要解决网络层的信任建立、消息可靠传输、会话持久化等问题。Loopsy 作为新兴的开源项目，提供了一套完整的终端与 AI 代理跨机器通信基础设施，其设计思路值得深入探讨。
Loopsy 的核心定位
Loopsy 最初解决的是「用手机控制电脑上运行的终端与 AI 代理」这一需求，随后演进为一套通用的机器间代理通信框架。项目托管于 GitHub（leox255/loopsy），采用 TypeScript 开发，核心特性包括全功能 PTY 支持、持久化会话、语音输入，以及通过 MCP 协议向 AI 编码代理暴露跨机器工具能力。
从架构角度看，Loopsy 实现了两种通信路径：其一是基于 Cloudflare Workers 中继的广域网方案，适用于手机远程控制笔记本场；其二是基于 mDNS 的局域网点对点方案，支持多台机器上的 AI 代理相互调用。这两种路径共享统一的协议层与安全模型，但在穿透性与部署复杂度上各有取舍。
WebSocket 中继架构
Loopsy 的移动端控制采用典型的中继架构。运行在本地的 daemon 与部署在 Cloudflare Workers 上的 relay 之间建立 outbound WebSocket 连接，用户的手机浏览器同样连接到同一个 relay。relay 的核心逻辑极为简洁：它像一条「网线」一样将两端的 WebSocket 连接拼接在一起，使手机端的 /app 页面能够看到一个完整的 PTY 会话。
这种设计的优势在于无需暴露本地端口到公网，也不需要 VPN 或静态 IP。daemon 始终作为 WebSocket 客户端主动连接中继，天然绕过了家庭网络的入站限制。relay 本身基于 Cloudflare Durable Object 实现，能够在免费额度下承载个人使用场景。部署过程通过 npx @loopsy/deploy-relay 命令一键完成，自动生成配对令牌密钥并通过 stdin 写入 Worker 秘密存储，整个流程约三十秒即可搞定。
需要特别说明的是中继的安全模型。当前版本的手机与 daemon 之间的传输采用 TLS 加密，但 TLS 终止于 relay 层面，意味着 relay 运营者理论上可以读取全部终端内容。项目在威胁模型文档中明确指出这是 v1.1 路线图的核心改进项 —— 端到端加密与前向保密将在后续版本引入。对于安全敏感场景，自托管 relay 是唯一的可选方案。
局域网代理间通信
Loopsy 的另一核心场景是同一局域网内多台机器上的 AI 代理相互协作。每台机器运行一个 daemon，通过 mDNS 自动发现局域网内的其他 peer。首次配对时，用户在其中一台机器上执行 loopsy pair 获取六位码，然后在另一台机器上输入该码完成 ECDH P-256 密钥交换。此后两个 daemon 建立直接连接，不再依赖中继。
配对完成后，每个 daemon 会向本地运行的 AI 编码代理暴露一组 MCP 工具。loopsy_execute 允许在一台机器上远程执行命令；loopsy_session_start 与 loopsy_session_stop 管理远程 PTY 会话的生命周期；loopsy_transfer_file 实现跨机器文件传输；loopsy_list_remote_files 则提供远程文件系统的只读浏览能力。这些工具的存在使得一个代理可以直接驱动另一台机器完成构建、测试、部署等任务，而无需人工切换终端。
更关键的是，Loopsy 还提供了共享键值存储与消息传递机制。loopsy_context_set 与 loopsy_context_get 允许代理将中间结果写入对等机器的本地存储；loopsy_broadcast_context 则将同一键值一次性写入所有在线 peer。这种设计支持了多代理流水线的构建：机器 A 上的代理将阶段性产物写入共享键，机器 B 上的代理随后读取并继续处理，两端的代理无需感知彼此的存在，只需遵循约定的键名约定即可完成协作。
消息协议在此基础上进一步定义了可靠的代理间消息传递语义。协议约定 inbox:<recipient>:<msg_id> 存储在接收方机器，outbox:<msg_id> 保存在发送方本地，ack:<sender> 记录接收方已处理的消息 ID。这套协议复用键值存储作为传输层，新加入的机器只需查询对应键即可获取待处理消息，无需协调客户端的发现与连接管理。完整的消息封装格式、轮询间隔与 TTL 默认值在项目的 AGENTS.md 文档中有详细说明。
安全性实现细节
作为控制面工具，Loopsy 在安全设计上投入了相当精力。配对令牌采用 HMAC 签名验证，且令牌本身通过 SHA-256 哈希后存储，攻击者即使获取存储介质也无法还原有效令牌。Bearer 认证使用 crypto.timingSafeEqual 进行恒定时间比较，防止时序攻击泄露密钥。手机端秘钥通过 WebSocket 子协议 header 传递，而非 URL 查询参数，避免在服务器日志中留下痕迹。
每个配对设备拥有独立的自动批准令牌，管理员可随时通过 loopsy phone revoke 命令撤销。配对 URL 包含一次性令牌与四位 SAS 验证码，配对窗口默认为一小时，超时后令牌自动失效。对于需要更强隔离的场景，自托管 relay 可配置 REGISTRATION_SECRET 并设置更短的 TTL。
项目还执行了定期的安全审计。威胁模型文档坦诚列出了当前版本的妥协点，包括 relay 的明文可见性、自动批准令牌的传输风险、以及缺乏前向保密等，这些问题均标注为 v2 版本的改进目标。这种透明的安全治理方式值得其他开源项目借鉴。
工程参数与配置要点
对于计划在生产环境或复杂工作流中部署 Loopsy 的团队，以下配置参数值得特别关注。
在 daemon 绑定层面，默认配置仅监听 127.0.0.1，所有外部访问通过 relay 或本地 Unix socket 路由。如需启用局域网 peer 模式，需显式执行 loopsy start --lan 或在配置文件中设置 server.host: 0.0.0.0。这种「默认关闭、按需开启」的设计降低了意外暴露风险。
执行策略通过 execution.denylist 与 maxConcurrent 两个字段控制。前者列出禁止直接执行的命令（默认为 rm, rmdir, format, mkfs, dd, shutdown, reboot），后者限制并发执行的命令数量，防止恶意或误操作导致资源耗尽。文件传输的路径限制同样支持黑白名单机制，transfer.allowedPaths 与 transfer.deniedPaths 可精细控制远程文件浏览的可见范围。
速率限制针对不同操作类型设置了独立阈值。execute 默认每分钟三十次，transfer 每分钟十次，context 读写每分钟六十次。这些阈值可根据实际使用场景调整，但过高可能放大安全风险，过低则影响协作效率。
会话持久化是 Loopsy 的核心竞争力之一。PTY 会话在网络中断、客户端断开甚至手机锁屏后依然保持运行，重新连接时可从断点恢复。项目的实现方式是将会话状态完全保留在 daemon 端，客户端仅作为输入输出通道，这对长时间运行的代理任务尤为重要 —— 例如在更强算力机器上启动 Claude 会话进行大规模重构，开发者可以从笔记本或手机随时检查进度。
与传统分布式代理方案的差异
当前分布式 AI 代理领域的通信方案多聚焦于单机器内部的代理协同，或基于云服务的集中式调度。Loopsy 的差异化在于，它将「终端控制」与「代理间通信」统一纳入同一套基础设施，并以去中心化的方式实现 —— 每台机器运行独立的 daemon，peer 之间直接通信，不依赖中心化的消息队列或服务注册中心。
这套方案的适用场景明确：需要跨多台机器编排任务、但又不希望引入复杂基础设施的团队。例如在开发工作流中，用轻薄本发起构建任务，由闲置的台式机或服务器执行；或在多机器实验环境中，让不同机器上的代理通过共享键值状态传递中间结果。Loopsy 提供的 MCP 工具使得现有 AI 编码代理（Claude Code、Codex CLI、Opencode 等）无需修改即可获得跨机器能力，这对已有代理工作流的团队而言是低侵入性的扩展。
当然，方案局限也需要正视。relay 中继模式目前不支持端到端加密，大规模部署场景下的中继可用性需要自行保障；局域网模式依赖 mDNS，在跨子网或严格网络隔离环境下可能失效，此时需手动添加 peer 地址。总体而言，Loopsy 填补了「轻量级分布式终端控制与代理协作」这一细分需求的市场空白，其设计思路对构建类似系统具有较高的参考价值。
资料来源
- Loopsy 官方仓库：https://github.com/leox255/loopsy