OpenClaw A2A Gateway:让不同服务器上的 Ag

OpenClaw A2A Gateway：让你的 AI Agent 学会「跨服务器对话」

为什么 Agent 需要互相对话？

你有没有遇到过这种情况：家里一台 Mac Studio 跑着代码审查 Agent，公司服务器上跑着运维 Agent，云端还有个做数据分析的 Agent。它们各自很强，但彼此完全隔离——就像三个专家坐在不同的房间里，中间没有电话线。

这就是 A2A（Agent-to-Agent）协议要解决的问题。Google 在 2025 年提出的这个开放协议，本质上就是给 AI Agent 装了一套「通讯录 + 电话系统」。而今天我们要介绍的 OpenClaw A2A Gateway 插件，就是把这套系统接入 OpenClaw 生态的桥梁。

一句话总结：装完这个插件，你的 OpenClaw Agent 就能跟其他服务器上的 Agent 直接对话、互相委派任务、传输文件。

A2A 协议到底是什么？

A2A 全称 Agent-to-Agent Protocol，由 Google 主导设计，目前版本 v0.3.0。它定义了几个核心概念：

Agent Card：每个 Agent 的「名片」。放在 `/.well-known/agent-card.json`，包含名字、能力描述、通信端点。其他 Agent 通过读这张名片来发现你、了解你能做什么。

Task：Agent 之间的交互单位。一个 Agent 给另一个发消息，就会创建一个 Task，支持同步等待结果，也支持异步轮询。

三种消息载体：

　　• `TextPart`：纯文本

　　• `FilePart`：文件传输（支持 URI 引用和 base64 内联）

　　• `DataPart`：结构化 JSON 数据

三种传输协议：JSON-RPC、REST、gRPC，你选哪个都行。

OpenClaw A2A Gateway 做了什么？

这个插件把 A2A 协议完整实现为一个 OpenClaw 插件。安装后你的 OpenClaw 实例会多出几个能力：

1. 被发现——Agent Card 自动发布

插件启动后会在 `http://你的IP:18800/.well-known/agent-card.json` 发布一张 Agent Card。其他 A2A 兼容的 Agent（不限于 OpenClaw）可以通过这个地址发现你。

2. 被调用——接收入站消息

外部 Agent 通过 JSON-RPC 或 REST 发来的消息，会被路由到你指定的 OpenClaw Agent（默认是 `main`），然后把回复返回给调用方。

3. 主动出击——调用 Peer Agent

你的 Agent 可以通过内置的 SDK 脚本或 `a2a_send_file` 工具，主动给配置好的 Peer 发消息、传文件。

4. 安全认证——Bearer Token

支持入站认证，每台服务器生成独立的 Token，防止未授权访问。

五分钟安装指南

前提条件

　　• OpenClaw ≥ 2026.3.0

　　• Node.js ≥ 22

　　• 两台服务器之间有网络连通性（Tailscale/内网/公网均可）

第一步：安装插件

bash

1mkdir -p ~/.openclaw/workspace/plugins

2cd ~/.openclaw/workspace/plugins

3git clone https://github.com/win4r/openclaw-a2a-gateway.git a2a-gateway

4cd a2a-gateway

5npm install --production

6# 一键注册

7openclaw plugins install ~/.openclaw/workspace/plugins/a2a-gateway

8openclaw gateway restart

第二步：验证安装

bash

1# 检查插件是否加载

2openclaw plugins list

3# 检查 Agent Card

4curl -s http://localhost:18800/.well-known/agent-card.json | python3 -m json.tool

看到返回的 JSON 包含 `protocolVersion: "0.3.0"` 就说明装好了。

第三步：配置安全（推荐）

bash

1TOKEN=$(openssl rand -hex 24)

2echo "你的 Token: $TOKEN"

3openclaw config set plugins.entries.a2a-gateway.config.security.inboundAuth 'bearer'

4openclaw config set plugins.entries.a2a-gateway.config.security.token "$TOKEN"

5openclaw gateway restart

第四步：添加 Peer

bash

1openclaw config set plugins.entries.a2a-gateway.config.peers '[

2 {

3 "name": "对方服务器",

4 "agentCardUrl": "http://对方IP:18800/.well-known/agent-card.json",

5 "auth": {

6 "type": "bearer",

7 "token": "对方的Token"

8 }

9 }

10]'

11openclaw gateway restart

注意：双向通信需要两边都互相添加对方为 Peer。

架构全景

产品化视角：名片发现（Agent Card）→ 认证（Bearer Token）→ 路由（agentId）→ 双向调用

code

1┌──────────────────────┐ A2A/JSON-RPC ┌──────────────────────┐

2│ OpenClaw 服务器 A │ ◄──────────────────────────► │ OpenClaw 服务器 B │

3│ │ (Tailscale / 内网) │ │

4│ Agent: 代码审查 │ │ Agent: 运维监控 │

5│ A2A 端口: 18800 │ │ A2A 端口: 18800 │

6│ Peer: Server-B │ │ Peer: Server-A │

7└──────────────────────┘ └──────────────────────┘

当服务器 A 上的代码审查 Agent 发现了一个需要运维介入的问题，它可以直接通过 A2A 协议把问题描述发给服务器 B 上的运维 Agent，运维 Agent 处理完后把结果回传。全程无需人工中转。

深度特性解析

异步任务模式

对于耗时较长的任务，支持 non-blocking 模式：

bash

1node skill/scripts/a2a-send.mjs \

2 --peer-url http://对方IP:18800 \

3 --token 对方Token \

4 --non-blocking \

5 --wait \

6 --timeout-ms 600000 \

7 --message "分析过去一周的系统日志并生成报告"

发送方不阻塞等待，而是通过轮询 `tasks/get` 接口获取结果。适合需要几分钟甚至更久的复杂任务。

文件传输

插件支持完整的 A2A Part 类型，包括文件传输：

Part 类型	传递方式	适用场景
TextPart	原始文本	普通对话
FilePart（URI）	URL 引用	发送报告链接
FilePart（base64）	内联二进制	直传小文件
DataPart	结构化 JSON	API 数据交换

还内置了 `a2a_send_file` 工具，Agent 可以直接调用来发送文件。

SSE 流式输出

支持 Server-Sent Events 流式输出，实时看到对方 Agent 的思考过程和中间结果。配合心跳 keep-alive 机制，长时间任务也不会断连。

Peer 健康检查与熔断

对每个 Peer 做健康检查，连续失败后触发熔断，自动指数退避重试。避免一个 Peer 挂了拖慢整个系统。

审计日志

所有跨 Agent 通信都记录在 JSONL 审计日志中，方便事后追溯和合规审查。

多 Token 轮换

支持同时配置多个 Token，实现零停机 Token 轮换。旧 Token 和新 Token 可以同时有效，平滑过渡。

实际应用场景

场景一：分布式开发团队

　　• 服务器 A（Mac Studio）：跑代码审查、测试、构建

　　• 服务器 B（云端 GPU）：跑 AI 模型训练和推理

　　• 服务器 C（办公室 NAS）：跑文档生成和知识库管理

三台服务器上的 Agent 通过 A2A 互相协作。代码审查 Agent 发现需要模型验证的问题，直接委派给 GPU 服务器上的 AI Agent；训练完成后结果自动同步到文档 Agent 生成报告。

场景二：多 Agent 运维

生产环境的监控 Agent 检测到异常 → 通过 A2A 通知开发环境的诊断 Agent → 诊断 Agent 分析日志定位问题 → 自动生成修复方案发回给运维 Agent 执行。

场景三：AI 工作流编排

把不同专长的 Agent 组织成流水线。数据采集 Agent → 清洗 Agent → 分析 Agent → 报告 Agent，每一步都通过 A2A 自动衔接。

与 MCP 的对比

你可能听说过 MCP（Model Context Protocol），它也是 Agent 通信的一种方式。两者的核心区别：

维度	A2A	MCP
定位	Agent 之间通信	Agent 与工具/数据源之间通信
关系	对等（Peer-to-Peer）	主从（Client-Server）
场景	跨服务器 Agent 协作	单 Agent 调用外部能力
发现	Agent Card 自动发现	需预先配置

简单说：MCP 让 Agent 能用工具，A2A 让 Agent 能交朋友。 两者互补，不冲突。

常见问题

Q: Agent Card 返回 404？ 确认插件已加载：`openclaw plugins list` 里应该能看到 `a2a-gateway` 状态为 `loaded`。

Q: 18800 端口连接被拒？ 检查防火墙设置，确认端口开放。如果用 Tailscale，确保两台机器都在同一个 Tailnet 里。

Q: 对等方认证失败？ 仔细核对 Token——你 peer 配置里的 token 要跟对方 `security.token` 完全一致。

Q: 推荐用什么网络方案？ 首推 Tailscale——安装简单、端对端加密、无需配置防火墙。内网环境直接用 IP 也行。

总结

OpenClaw A2A Gateway 把 Google 的 A2A 协议变成了一个开箱即用的 OpenClaw 插件。3800 多行 TypeScript 代码，覆盖了任务持久化、并发控制、文件传输、流式输出、健康检查、审计日志等生产级特性。

最重要的是：安装只需要 5 分钟。 `git clone` → `npm install` → `openclaw plugins install` → 搞定。

如果你在用 OpenClaw 管理多台服务器上的 Agent，这个插件值得一试。让你的 Agent 不再是孤岛，而是一个能互相协作的团队。

🔗 项目地址：https://github.com/win4r/openclaw-a2a-gateway
📖 A2A 协议规范：https://github.com/google/A2A
🦞 OpenClaw 官网：https://openclaw.ai

深入源码：3800 行背后的工程决策

我们拉下来项目代码看一眼目录结构，会发现这不是一个简单的 HTTP 转发层：

code

1src/

2├── executor.ts # 核心执行引擎（1096行）

3├── queueing-executor.ts # 队列化执行器，限流+排队

4├── client.ts # A2A SDK 客户端封装

5├── agent-card.ts # Agent Card 生成与配置合并

6├── task-store.ts # 磁盘持久化任务存储

7├── task-cleanup.ts # TTL 自动清理过期任务

8├── peer-health.ts # Peer 健康检查+熔断器

9├── peer-retry.ts # 指数退避重试策略

10├── file-security.ts # SSRF 防护+MIME 白名单

11├── audit.ts # JSONL 审计日志

12├── telemetry.ts # 结构化指标采集

13└── types.ts # TypeScript 类型定义

14index.ts # 插件入口（690行）

executor.ts：最重要的 1096 行

这是插件的心脏。它负责接收 A2A 入站请求，把消息转换成 OpenClaw Gateway 能理解的格式，调用 Agent，然后把响应转换回 A2A 格式返回。

关键设计决策：

　　• Part 类型序列化：由于 OpenClaw Gateway RPC 只接受纯文本，所有 FilePart 和 DataPart 都被序列化为人类可读的文本格式。这是一个务实的权衡——牺牲了一些结构化信息，但保证了与现有 OpenClaw 生态的兼容性。

　　• 超时处理：默认 5 分钟超时，可配置。超时后任务状态标记为 `failed`，不会永远挂着。

　　• 并发控制：通过 `queueing-executor.ts` 限制同时处理的入站任务数量（默认 4 个），超出的排队等待，队列满了直接拒绝。

file-security.ts：安全不是事后想法

文件传输是最容易出安全问题的地方。这个模块做了几件事：

　　1. SSRF 防护：校验文件 URI，阻止指向内网地址（127.0.0.1、10.x、192.168.x 等）的请求

　　2. MIME 白名单：只允许安全的文件类型通过，阻止可执行文件等危险类型

　　3. 大小限制：base64 内联文件有大小上限，防止恶意大文件消耗内存

这些防护在 Agent 间通信场景中尤其重要——你不会想让一个被入侵的 Peer 通过 A2A 协议探测你的内网。

peer-health.ts + peer-retry.ts：优雅的故障处理

分布式系统最怕的就是雪崩。当一个 Peer 挂了：

　　1. 健康检查定期探测每个 Peer 的 Agent Card 端点

　　2. 连续失败触发熔断器，暂停向该 Peer 发送请求

　　3. 指数退避机制自动尝试恢复：1s → 2s → 4s → 8s → ...

　　4. Peer 恢复后自动重新加入可用列表

这套机制保证了一个 Peer 出问题不会拖慢整个系统的响应速度。

安全最佳实践

Token 管理

每台服务器应该生成独立的 Token，不要多台服务器共用同一个。推荐流程：

　　1. 每台服务器生成自己的 Token：`openssl rand -hex 24`

　　2. 把自己的 Token 分享给需要调用你的 Peer

　　3. 在 peer 配置中填入对方的 Token

网络隔离

　　• 首推 Tailscale：零配置、端到端加密、自动穿越 NAT

　　• 内网环境：确保 18800 端口只对可信 IP 开放

　　• 公网暴露：务必开启 Bearer Token 认证 + 防火墙 IP 白名单

审计与监控

插件默认开启 JSONL 审计日志和 metrics 端点，建议：

　　• 定期检查审计日志，排查异常调用

　　• 把 `/a2a/metrics` 接入你的监控系统（Prometheus/Grafana）

　　• 设置告警：Peer 熔断、任务超时、认证失败

未来路线图

项目已经完成了 P0-P7 的核心特性，接下来社区期待的方向包括：

　　• 规则路由：按消息类型/标签/skill 自动选择目标 Peer 和 agentId，实现更智能的任务分发

　　• DNS-SD 动态发现：通过 mDNS 自动发现局域网内的 A2A Agent，替代手动配置 Peer URL

　　• Push Notifications：超长任务完成后主动回调通知，而不是靠调用方轮询

　　• 跨实现互操作：与 Google 参考实现、LangChain A2A 等其他实现做兼容性测试

这是一个 MIT 协议的开源项目，欢迎贡献代码和提出 Feature Request。

如果你觉得这篇文章有帮助，欢迎转发给同样在玩 Agent 的朋友。有问题欢迎在评论区讨论，我会逐一回复。

🤔 互动话题

关于OpenClaw A2A Gateway，你有什么踩坑经历或心得？评论区聊聊~

👍 点赞 + 在看 + 转发是对我最大的支持！

本文首发于「不怕慢」