ZEGA AI（外部原型）

ZEGA AI 是一个外部金融科技平台，通过 TypeScript 桥接包（@zega/zeroclaw-bridge）连接到 ZeroClaw v0.8.x 网关守护进程。该桥接包是由 ZEGA 单体仓库维护的外部原型，不属于 ZeroClaw 本身。

状态： 原型版。该桥接器已针对本地辅助模块（SemVer 解析、错误层级结构、离线容错能力）完成冒烟测试。尚未执行实时守护进程配对或端点测试。以下信息描述的是该桥接器的设计意图，而非经过验证的生产环境兼容性。

配对

**网关 URL 配置说明：**桥接客户端默认使用 http://127.0.0.1:4242，而 ZeroClaw 的规范 GatewayConfig 默认端口为 42617。连接到原生本地 ZeroClaw 守护进程时，请将客户端配置为使用匹配的网关地址：
const client = new ZeroClawGatewayClient({
  gatewayUrl: "http://127.0.0.1:42617",
});
如果不将网关端口设置为与活动的 ZeroClaw 守护进程匹配，桥接器将在配对前报告离线/无法访问状态。

可远程访问的网关应使用 HTTPS 或经过身份验证的隧道（例如 WireGuard、Tailscale 或 SSH 隧道），而不是明文 HTTP，以保护通过 Authorization 标头传输的 Bearer 凭据。

桥接器实现 ZeroClaw 网关公开的两个配对契约，并按顺序尝试：

增强路由：`POST /api/pair`

接受 JSON 请求体：

{
  "code": "<6 位配对代码>",
  device_name: "ZEGA AI Bridge",
  "device_type": "api-bridge"
}

成功后，网关会返回 { "paired": true, "token": "<bearer>" }。桥接器会存储该令牌，以用于后续经过身份验证的请求。

上游处理程序：api_pairing::submit_pairing_enhanced (crates/zeroclaw-gateway/src/api_pairing.rs)。

旧版路由：`POST /pair`

在 X-Pairing-Code 请求头中发送配对代码：

POST /pair
Content-Type: application/json
X-Pairing-Code: <6-digit code>

当增强端点不可用或返回既非限流错误也非成功的状态时，桥接器会回退到此路由。如果增强端点返回限流失败（RateLimitError），桥接器会立即重新抛出该错误，而不会尝试旧版回退。

上游处理程序：handle_pair（crates/zeroclaw-gateway/src/lib.rs）。

桥接架构

组件	角色
`ZeroClawGatewayClient`	HTTP 客户端，默认请求超时和健康检查超时均为 5 秒，支持通过 `AbortController` 取消，并自动使用指数退避重试。守护进程无法访问时回退到离线错误状态。
`ZeroClawAuthManager`	管理配对流程（增强版 → 旧版回退），并为需要身份验证的端点生成 `Authorization: Bearer <token>` 请求标头。
版本矩阵	针对数值范围 `>=0.8.0 <0.9.0` 的客户端版本检查（目标 `v0.8.3`）。当前客户端辅助函数会在比较前去除预发布版本后缀，并评估数值组件（`major.minor.patch`）。此范围体现了设计意图，尚未针对正在运行的守护进程进行验证。

冒烟测试涵盖的内容

该桥接组件附带一个冒烟测试（pnpm --filter @zega/zeroclaw-bridge test:smoke），其中包含 18 个断言，用于验证以下 离线 / 单元级行为：

SemVer 解析和比较。
版本兼容性边界（兼容、过旧、超过上限）。
Auth-manager 的令牌存储、Bearer 标头构造以及离线 getState() 行为。
网关错误构造函数和字段。

冒烟测试不会启动 ZeroClaw 守护进程、交换配对码，也不会通过 HTTP 调用任何网关端点。

它不会覆盖增强版到旧版的配对回退或速率限制升级分支。

外部引用

有关源代码和单仓库详情，请访问 ZEGA AI 仓库，或查看已审阅提交 f99104367a6b06815cf478120b247d042fa7b1a5 中的桥接包。

Keyboard shortcuts

ZeroClaw Docs