A2A 桥 tailnet 接入补丁方案 v1

日期：2026-10-11 ｜ 状态：待批准实施 ｜ 范围：wushi_band/openclaw_a2a_server.py（F4 节点）＋ launchd ai.openclaw.a2a-bridge

1. 现状（已实测/已读码确认）

• Muse 的 VM 已加入用户 tailnet（设备名 muse，tailnet 地址 100.71.177.20）；Mac（kensei）tailnet 地址 100.124.73.50，经运行时隧道代理 TCP 可达。
• A2A 桥由 launchd ai.openclaw.a2a-bridge 托管（KeepAlive），以 Hermes 运行时 Python 启动：openclaw_a2a_server.py --port 18999，env 来自 ~/.hermes/secrets/brave-serpapi.env。该节点即六眼议会 F4 独立顾问（xAI OIDC Grok 4.7），协议为 A2A v0.3.0：GET /.well-known/agent-card.json、POST /（tasks/send / tasks/get / tasks/cancel）。
• 当前不可直调的原因只有一条：--host 默认 127.0.0.1，仅监听回环口，tailnet 流量到不了进程。
• 认证逻辑（_is_authorized，do_POST 首行强制，失败 403）：API_TOKEN 已设置时只验 Bearer token、不限来源；未设置时仅放行 localhost 来源。限流 100 次/分钟/IP，请求体上限 10MB，均已内置。

2. 补丁设计（三处，全部向后兼容）

2.1 代码：多地址绑定（main()，约 10 行）

--host 改为接受逗号分隔列表；每个地址起一个 ThreadingHTTPServer（首个前台 serve_forever，其余守护线程）。不传参时行为与现状完全一致（仅 127.0.0.1）。

2.2 代码：远程来源双因子（_is_authorized，约 8 行）

新增 env A2A_REMOTE_PEERS（逗号分隔的 tailnet 地址白名单）。规则：

• localhost 来源：行为不变。
• 非 localhost 来源：必须同时满足「来源在白名单内」且「Bearer token 与 API_TOKEN 一致」；API_TOKEN 为空时一律拒绝（fail-closed）。

2.3 plist：ai.openclaw.a2a-bridge.plist

• 按用户既有惯例先备份（.bak.20261011_a2a-tailnet）。
• ProgramArguments 追加：--host 127.0.0.1,100.124.73.50（回环口保留，Hermes 本地 a2a_tool.py 调用不受影响；新增 Mac 的 tailnet 地址）。
• EnvironmentVariables 追加：A2A_REMOTE_PEERS = 100.71.177.20（仅 Muse 的 VM）。

3. 前置核验（实施前一步，需在 Mac 本地执行）

确认生产 env 是否已设 API_TOKEN（只看有无、不看值）：

grep -q '^API_TOKEN=' ~/.hermes/secrets/brave-serpapi.env && echo set || echo unset

• 若 unset：生成一枚高熵 token 写入该 env 文件；token 经 Muse 保险箱录入通道交付到 Muse 侧，存 ~/workspace/tools/a2a-f4.env（600 权限），不进聊天明文、不进记忆。
• 若 set：现有 token 同样经保险箱通道补录到 Muse 侧（值不经聊天）。

4. 部署（Mac 本地执行，Muse 无 Mac shell）

launchctl kickstart -k gui/$(id -u)/ai.openclaw.a2a-bridge
tail -n 50 ~/.openclaw/logs/a2a-bridge.log   # 确认双地址监听、无启动报错

5. 验收（Muse 侧经 tailnet 隧道执行）

1. GET /.well-known/agent-card.json → 200，卡片为 F4 节点。
2. POST /（tasks/send，不带 token）→ 期望 403。
3. POST /（tasks/send，带 token）→ 发送一条无害测试任务（如请 F4 用一句话自我介绍），tasks/get 轮询至 completed 并回收正文。
4. 回归：观察 bridge 日志，确认 Hermes 本地回环口任务流量正常（部署后首个例行任务成功即算通过）。

6. 回滚

恢复 plist 备份并再次 kickstart -k；代码改动默认单地址行为不变，无数据迁移、无状态变更（任务表为内存态，重启即清，与现状一致）。

7. 安全边界

• 暴露面仅限 tailnet 内部（当前成员：Mac、Muse 的 VM 及用户自有设备），不对局域网与公网开放（不绑 0.0.0.0）。
• 远程调用双因子（白名单地址＋token），本地调用零变化；限流与体量上限沿用现有实现。
• F4 节点本身 fail-closed 设计（认证拒绝仅刷新凭据重试一次、其余失败不计票），本补丁不改其模型路由与议会规则。
• 本补丁只开 F4 一个节点；其余节点（F3/F5/F6/F7、Hermes F2@18998）如需接入，同一手法逐个复制，另行批准。