hagency.
EN开始使用
Hagency/系统架构
探索系统连接

看清每一条连接。

从 Matrix 对话，到编程 Agent 的工作目录。探索 Robrix2、Palpo 及其配套 Web 服务如何与 Hagency 协作。

MatrixHTTPSAppserviceACP / MCP
已核验的开发版架构 · 2026 年 9 月

下方提供完整架构说明，交互图将在浏览器模块加载后显示。

阅读连接说明

出站传输与配套管理应用描述已核验的开发集成，不代表所有发布包都包含这些能力。图表用于说明，不连接真实服务。

01 / HTTPS

Hagency 主动连接， Palpo 持久保存队列。

贡献方机器可以位于 NAT 后。Hagency 桥接主动向公开的 Palpo Web 传输入口发起 HTTPS 连接；Matrix homeserver 则通过服务器网络访问同侧中继。

操作 / API方向含义
发布能力与状态POST /api/fleet/v2/{fleetId}/updatesHagency → Palpo Web带序号的发件箱承载心跳、资源快照与申请观察状态；响应丢失时重试相同序号和内容。
接收 Matrix 事务GET /api/fleet/v2/{fleetId}/poll?lane=matrixHagency 发起请求 → Web 响应长轮询从持久 Matrix 队列租赁原始 AS 事务，HTTP 连接由 Hagency 发起。
接收工作请求GET /api/fleet/v2/{fleetId}/poll?lane=workHagency 发起请求 → Web 响应独立队列承载包含来源事件及权限绑定的申请与探测工作，不绕过本地接纳检查。
确认接收保管POST /api/fleet/v2/{fleetId}/ackHagency → Palpo Web本地持久化后，ACK 指定投递、队列和当前租约令牌；它表示接收，不代表资源审批、任务完成或工具执行授权。
投递 Appservice 事务PUT /api/relay/v2/{fleetId}/_matrix/app/v1/transactions/{txnId}Palpo homeserver → 服务器侧 Web 中继中继校验 hs_token，持久化事务后返回 HTTP 200。这是 Matrix AS 链路，不是对 Hagency 的入站调用。

持久投递，状态明确

Web 中继先持久化，再向 Matrix 确认；Hagency 先持久化，再确认投递租约。重放 ID 和内容摘要用于防止重复接纳，冲突内容会被拒绝。处理、分配和完成状态与这两种确认分别记录。

先验证连接，再以心跳维持

当前 generation 的确切 Matrix 探测建立连接，之后由后台心跳维持活性。旧申请观察不会因为较晚到达的心跳或重传而变成“当前就绪”。已有回调机群需要明确迁移，图中展示当前出站路径。

02 / APPSERVICE

注册服务， 再验证连接。

Matrix 定义应用服务注册；Palpo 配套 Web 应用自动安装注册，并在其周围实现所有者配对和机群传输。

  1. 01

    授权一个机群

    Palpo 管理员选择活跃的本地所有者和出站传输。配套服务在联系 homeserver 前持久化操作 ID、随机机群 ID 与生成的注册；重试复用原操作，内容变化则报告冲突。

  2. 02

    安装限定范围的 Appservice

    配套服务以管理员权限调用 POST /_palpo/admin/v1/appservices，生成代表身份的 localpart、独占本地用户命名空间、as_token 和 hs_token。注册 URL 指向服务器侧中继，而非贡献方电脑。

  3. 03

    回读注册，创建代表身份

    服务回读注册并比较 ID、URL、令牌、发送者与命名空间。在核验的 Palpo 实现中，带 user_id 的 AS 认证 whoami 请求会创建代表身份，随后检查准确的 MXID 和 appservice 归属。这种创建行为是 Palpo 特有实现。

  4. 04

    配对所有者的 Hagency

    只有指定所有者可以下载该机群配置，并通过 Hagency 项目方接入流程导入。配置包含限定范围的 Matrix 注册和独立出站机器凭据，不会把 Palpo 管理员令牌交给 Hagency。

  5. 05

    开始出站轮询与状态发布

    Hagency 启动独立的 matrix/work 轮询循环，在本地保存投递，确认租约，并发布能力、心跳与申请观察结果。即使贡献方离线，Web 服务也能从存储状态提供信息。

  6. 06

    验证真实 Matrix 消息往返

    所有者的连接操作创建或恢复接待房间，并发送 com.hagency.connection.probe.v1。Palpo → 中继 → Hagency 必须投递该确切事件；当前 generation 的事务接收记录与 Hagency 验证结果共同建立连接，单独心跳不能证明初次就绪。

  7. 07

    接纳项目并分配 Agent

    项目注册绑定所有者与目标房间，并建立独立私密审批房间。具名 Agent 申请仍需资源贡献方接纳和分配检查；完成资源交付且核验实际目标房间成员后，门户才报告可用。

查看 Appservice 注册示例
仅作示例 · 每个机群独立生成 · 不含真实密钥
# Illustrative values; generated separately for every fleet.
id: hf_0123456789abcdef0123456789abcdef
url: http://palpo-web:8090/api/relay/v2/hf_0123456789abcdef0123456789abcdef
as_token: <APP_SERVICE_SECRET>
hs_token: <HOMESERVER_SECRET>
sender_localpart: hf_0123456789abcdef0123456789abcdef_representative
namespaces:
  users:
    - exclusive: true
      regex: '^@hf_0123456789abcdef0123456789abcdef_[a-z0-9_]+:example\.org$'
  aliases: []
  rooms: []
rate_limited: true
receive_ephemeral: false

中继 URL 供 homeserver 访问；本地用户正则限定到一个机群和一个 Matrix 服务器身份。这段 YAML 展示字段，配套服务通过 Palpo 管理 API 安装等价 JSON。

03 / ROBRIX2 → PALPO

原生客户端， 标准 Matrix 连接。

Robrix 直接连接 Matrix homeserver，其对话通过 Matrix 事件、房间绑定和桥接到达 Hagency。

选择 Matrix 入口并登录

Robrix 以所选 homeserver URL 或服务器名称构建 matrix-sdk Client，使用账户支持的登录方式或恢复已有设备会话。Matrix API 入口与配套管理门户可以使用不同 URL。

同步时不阻塞界面

Makepad 界面将 MatrixRequest 操作交给 Tokio 工作线程；matrix-sdk-ui SyncService 发现原生 sliding sync，并将房间列表和各房间时间线更新交回界面。媒体、输入状态、回执和成员关系使用 SDK 对应的 Matrix 操作。

保留线程与身份信息

消息与回复使用 Matrix 事件和线程关系。Hagency 验证实际发送者及存储的房间线程绑定，显示名称或文本提及不是授权凭据。

在客户端维护加密

Robrix 在本地持久化设备与加密状态。Hagency 的受支持加密路径使用自己的真实 Matrix 设备及持久加密存储。AS 注册或服务器中继本身不会提供读取加密房间的密钥。

房间权限等级可以赋予人和 Agent 相同的房间能力，但编程工具执行仍需 Hagency 自身的运行时授权。 了解 Matrix 权限模型 →

04 / HAGENCY → CODING AGENTS

一个控制平面， 多条明确的运行路径。

Hagency 协调真实编程 Agent 进程，重建上下文、选择符合条件的适配器、授予限定范围工具、观察执行，并将结果送回原始会话。

Claude Code

当前无界面任务运行器
claude -p · stream-json

每次调度启动受管理的新进程，通过 stdin 传入提示词，流式输出活动与结果，并提供限定范围的 MCP 服务。上下文来自 Hagency 持久状态。

权限检查遵循 Claude 运行时集成与配置的工具策略。

Codex

当前 App Server 任务运行器
codex app-server --stdio

initialize → thread/start → turn/start。新 App Server 线程接收重建上下文，通知和原生审批请求绑定到本次调度。

命令、文件、权限及受支持的 MCP 审批，均需核验操作身份与所有者决定。

Octos

明确选择的 ACP 适配器
octos acp --profile coding-full

ACP initialize → session/new → session/prompt。核验的适配器要求在 Octos 自身配置中声明 MCP 服务，并忽略 session/new 的 mcpServers。

核验能力声明不支持加载会话，也不会阻塞等待 request_permission；启动时的沙箱策略仍是实际控制。

Hermes

明确选择的 ACP 适配器
hermes-acp

接受会话 MCP 配置，同时需要安装 ACP 与 MCP 扩展；模型选择遵循 Hermes 自身配置。

Hagency 不发送不受支持的 --model 或 --cwd 参数；声明的会话能力不代表任务运行器完全等价。

Codex ACP

独立适配器传输
codex-acp

独立适配器包装 Codex，通过 stdio 讲 ACP，接受会话 MCP 配置，并通过 session/update 报告进度。

与 codex app-server 区分。核验的适配器未接收文件系统沙箱参数；Hagency 的 ACP 权限回调限制工具批准。

ACP、MCP 与推理各司其职

ACP 是 Hagency 与兼容编程适配器之间的会话协议；MCP 向编程 Agent 提供 Hagency 工具；Agent 再独立连接其配置的模型服务。Octos 基于自身配置注入 MCP，Hermes/Codex ACP 基于会话注入，这是明确的适配器差异。

会话持久，工作进程可替换

后端拥有 Agent、房间、范围和线程身份，以及已接纳输入、摘要和调度状态。新工作进程接收有界重建上下文；编程工作需要任务和真实 Matrix 线程根。保留的 tmux 窗格及运行时进程 ID 不能替代这一权威状态。

05 / IDENTITY & AUTHORITY

每条连接，都有自己的权限来源。

人与 Agent 可以使用相同的房间权限模型。以下凭据则分别对应不同网络与执行边界。

凭据调用方 → 服务范围
as_tokenAppservice → Matrix 服务器为已注册命名空间中的获授权本地身份执行操作，不是 Palpo 管理员令牌。
hs_tokenMatrix 服务器 → AS 中继认证向已注册中继的事务投递，不是机群机器令牌。
Machine token + generationHagency → Palpo Web 传输授权单个机群的轮询、ACK 和状态发布；轮换改变 generation，并使旧传输权限失效。
Matrix user / device tokenRobrix 或 Agent 设备 → homeserver标识真实用户与设备会话；房间成员、权限等级和加密密钥仍然适用。
Browser session + CSRF浏览器 → Palpo 配套应用授权已登录用户的网页操作；管理调用仍需对应服务器权限。
Dispatch capability编程运行时 / MCP → Hagency将任务和工具操作限定在本次调度；运行时执行审批独立于 Matrix 房间角色。
Provider credentials编程 Agent → 模型入口在所选服务提供方授权模型调用；具体数据目的地由该 Agent 配置决定。
06 / STATE & FEDERATION

状态跟随责任，分别保存。

Robrix2

本地会话与加密数据库、房间和时间线缓存。

Palpo homeserver

服务器侧 Matrix 账户、房间状态与事件、成员关系，以及按服务器部署配置保存的媒体。

Palpo companion web

私有 SQLite 状态，保存注册、机群凭据、项目操作、持久传输与审计记录。

Hagency

资源与接洽状态、房间任务会话绑定、收发件箱与调度账本，以及独立设备加密存储。

编程 Agent

分配的代码仓库、工作文件与任务产物；模型上下文在配置预算内重建。

联邦连接独立运营的房间

其他 homeserver 上的用户可以参与获授权的联邦房间。其服务器使用 Matrix 服务器间 API 与 Palpo 交换房间事件。这不会暴露 Hagency 本地 API 或共享其文件系统。房间数据、加密可用性及模型服务的数据披露仍取决于实际房间、设备与部署。

07 / CONNECTION REFERENCE

逐条阅读系统连接。

与交互图对应的连接说明，无需 JavaScript 即可阅读。箭头标识调用方与接收方，轮询响应则将投递内容返回 Hagency。

整体架构

Robrix2 → Palpo Matrix 服务器

HTTPS · Matrix user/device token

Robrix 向 Palpo 认证、发送消息和媒体，并通过 SDK 同步接收房间更新；它不直接连接 Hagency 后端。

所有者 / 管理员浏览器 → Palpo Web 服务

HTTPS · session cookie + CSRF

用户以自己的 Matrix 身份使用配套应用；服务端验证身份及各操作所需权限。

Palpo Web 服务 → Palpo Matrix 服务器

POST /_palpo/admin/v1/appservices

Web 服务以服务器管理员权限安装按机群隔离的注册，再回读核验完整配置。这是 Palpo 管理 API。

Palpo Matrix 服务器 → AS 中继与持久队列

PUT …/_matrix/app/v1/transactions/{txnId} · hs_token

Palpo 向同侧中继推送事务；中继校验 hs_token，保存原始 ID 和内容后确认。这一跳位于服务器侧。

Hagency Matrix 桥接 → AS 中继与持久队列

GET /poll · POST /ack · machine token + generation

Hagency 主动发起 HTTPS 请求，投递内容随轮询响应返回。matrix/work 队列分别使用租约；先写本地 SQLite 再 ACK，ACK 不代表审批。

Hagency Matrix 桥接 → Palpo Web 服务

POST /updates · machine token + generation

Hagency 从带序号的持久发件箱发布资源快照、心跳和申请观察结果；重试旧观察不会让它变成新状态。

Hagency Matrix 桥接 → Hagency 控制平面

Authenticated local API

桥接验证发送者、房间、命名空间和项目绑定；控制平面保留资源方审批、额度、任务归属和执行权限检查。

Hagency 控制台 → Hagency 控制平面

Console server proxy → Hagency API

资源配置与接洽决定调用经过认证的本地后端；浏览器代码不是后端权限来源。

Hagency 控制平面 → 编程 Agent 适配器

Guarded subprocess / selected transport

后端选择符合条件的 Agent 和传输方式，验证调度，并以数据形式传递上下文，而不是可执行 shell 文本。

编程 Agent 适配器 → 配置的模型服务

Provider-specific endpoint + credentials

Agent 运行时独立于 Matrix 传输连接配置的模型服务；该 Agent 支持时也可使用本地入口。

Agent Matrix 设备 → Palpo Matrix 服务器

Matrix device token · sync + media + crypto

真实设备客户端维护受支持加密消息和私密审批的密钥与会话存储；服务器中继持有消息不等于持有解密密钥。

Palpo Matrix 服务器 → 其他 Matrix 服务器

Matrix Server–Server API · signed requests

独立服务器交换获授权的房间事件；接收方执行 Matrix 事件与成员规则，运行时权限仍由 Hagency 本地掌握。

Appservice 注册

所有者 / 管理员浏览器 → Palpo Web 服务

HTTPS · session cookie + CSRF

用户以自己的 Matrix 身份使用配套应用；服务端验证身份及各操作所需权限。

Palpo Web 服务 → Palpo Matrix 服务器

POST /_palpo/admin/v1/appservices

Web 服务以服务器管理员权限安装按机群隔离的注册，再回读核验完整配置。这是 Palpo 管理 API。

Palpo Matrix 服务器 → AS 中继与持久队列

PUT …/_matrix/app/v1/transactions/{txnId} · hs_token

Palpo 向同侧中继推送事务；中继校验 hs_token，保存原始 ID 和内容后确认。这一跳位于服务器侧。

Hagency Matrix 桥接 → AS 中继与持久队列

GET /poll · POST /ack · machine token + generation

Hagency 主动发起 HTTPS 请求，投递内容随轮询响应返回。matrix/work 队列分别使用租约；先写本地 SQLite 再 ACK，ACK 不代表审批。

Hagency Matrix 桥接 → Palpo Web 服务

POST /updates · machine token + generation

Hagency 从带序号的持久发件箱发布资源快照、心跳和申请观察结果；重试旧观察不会让它变成新状态。

Hagency 控制台 → Hagency 控制平面

Console server proxy → Hagency API

资源配置与接洽决定调用经过认证的本地后端；浏览器代码不是后端权限来源。

Hagency Matrix 桥接 → Hagency 控制平面

Authenticated local API

桥接验证发送者、房间、命名空间和项目绑定；控制平面保留资源方审批、额度、任务归属和执行权限检查。

Hagency Matrix 桥接 → Agent Matrix 设备

Persistent device/crypto state

桥接启动并监管专用 Matrix 设备客户端，并按相同绑定规则接纳其解密消息。

Agent Matrix 设备 → Palpo Matrix 服务器

Matrix device token · sync + media + crypto

真实设备客户端维护受支持加密消息和私密审批的密钥与会话存储；服务器中继持有消息不等于持有解密密钥。

消息 → 工作 → 回复

Robrix2 → Palpo Matrix 服务器

HTTPS · Matrix user/device token

Robrix 向 Palpo 认证、发送消息和媒体，并通过 SDK 同步接收房间更新；它不直接连接 Hagency 后端。

Palpo Matrix 服务器 → AS 中继与持久队列

PUT …/_matrix/app/v1/transactions/{txnId} · hs_token

Palpo 向同侧中继推送事务；中继校验 hs_token，保存原始 ID 和内容后确认。这一跳位于服务器侧。

Hagency Matrix 桥接 → AS 中继与持久队列

GET /poll · POST /ack · machine token + generation

Hagency 主动发起 HTTPS 请求，投递内容随轮询响应返回。matrix/work 队列分别使用租约；先写本地 SQLite 再 ACK，ACK 不代表审批。

Hagency Matrix 桥接 → Hagency 控制平面

Authenticated local API

桥接验证发送者、房间、命名空间和项目绑定；控制平面保留资源方审批、额度、任务归属和执行权限检查。

Hagency 控制平面 → 编程 Agent 适配器

Guarded subprocess / selected transport

后端选择符合条件的 Agent 和传输方式，验证调度，并以数据形式传递上下文，而不是可执行 shell 文本。

Hagency Matrix 桥接 → Palpo Matrix 服务器

Matrix Client–Server API · as_token + scoped user_id

桥接可凭 Appservice 认证，以命名空间内已注册的本地身份发言；受支持的加密路径则使用真实设备会话。

编程 Agent 适配器 → 配置的模型服务

Provider-specific endpoint + credentials

Agent 运行时独立于 Matrix 传输连接配置的模型服务；该 Agent 支持时也可使用本地入口。

编程 Agent 适配器 → Agent 工作空间与文件

Assigned cwd + runtime tool policy

代码和任务产物写入分配的工作目录；向房间发布文件是明确授权的操作。

Agent Matrix 设备 → Palpo Matrix 服务器

Matrix device token · sync + media + crypto

真实设备客户端维护受支持加密消息和私密审批的密钥与会话存储；服务器中继持有消息不等于持有解密密钥。

执行审批 → Agent Matrix 设备

Verified Matrix owner binding

审批请求与决定经过验证的所有者通道；授予 Matrix 房间角色不能绕过执行检查。

编程 Agent 运行时

Hagency 控制平面 → 持久任务与会话状态

SQLite transactions / dispatch ledger

会话身份和任务状态在运行器退出后仍然保留；上下文由已接纳输入、摘要和房间线程绑定重建。

Hagency 控制平面 → Claude Code 运行器

claude -p · stream-json

为本次调度启动受管理的 Claude 子进程，流式读取活动与输出，再按账本结算或记录不确定失败。

Hagency 控制平面 → Codex App Server

JSON-RPC / stdio

执行 initialize、thread/start、turn/start，并把通知与审批响应关联到当前调度。每个工作进程创建新的 App Server 线程。

Hagency 控制平面 → ACP 适配层

Agent Client Protocol / stdio

使用明确选择的 Octos、Hermes 或 Codex ACP 适配器；session/update 报告进度，request_permission 行为因适配器而异。

Hagency 控制平面 → 保留的 tmux 传输

tmux runtime interface

保留的终端 Agent 使用窗格输入与捕获；该方式不会被视为无界面运行器或 ACP 会话的隐式替代。

Claude Code 运行器 → Hagency MCP 工具

MCP / stdio

Claude 项目配置指向 mcp-server.js；调度凭据随进程启动传入，不写入公开配置。

Codex App Server → Hagency MCP 工具

MCP / stdio

App Server 启动时注入 Hagency MCP 配置和允许的环境变量名称，并为特权工具调用核验操作身份。

ACP 适配层 → Hagency MCP 工具

session/new mcpServers or agent-side config

Hermes 与 Codex ACP 接受会话 MCP 配置；核验的 Octos 适配器则需要自身配置和 coding-full 配置档。

Hagency MCP 工具 → Hagency 控制平面

Authenticated backend API + dispatch capability

MCP 请求转换为经过检查的任务、会话、消息和文件操作；权限取决于调度与操作，而非模型写出的文字。

Codex App Server → 执行审批

Native JSON-RPC approval request

命令、文件修改或其他受支持的原生请求等待已绑定的所有者决定。审批卡片负责展示，后端验证答案。

08 / SOURCE NOTES

以实际实现为依据。

核验于 2026 年 9 月的本地开发源码。仓库链接指向上游项目，不将这些本地版本与集成等同于最新发布版或当前部署二进制。

Hagency 源码

核验本地开发版本 05dc46b：fleet-outbound-client/config/store、Matrix 桥接、router/src/runner.ts 与框架清单。

Robrix2 源码

核验本地版本 d5523276：客户端构建、MatrixRequest 工作线程、SyncService、消息发送与持久加密。

机群 /api/fleet/v2 传输、Palpo 管理注册入口与配套应用属于项目扩展；标准 Matrix 提供客户端服务器通信、Appservice、房间权限和联邦。

HAGENCY

一起创造新的可能。

从一个项目开始，在团队需要时连接整个生态。

开始使用加入社区

搜索

找到你的下一步。

ESC关闭⌘ / Ctrl + K

项目截图

打开原图