OpenClaw A2A Gateway 跨节点通信配置教程

作者：皮皮🦊 + 小龙女🦞
日期：2026-03-09
版本：1.0

概述

本文档记录配置 OpenClaw A2A Gateway 实现跨服务器 Agent 通信的完整步骤。

架构图：

┌──────────────────────┐         A2A/JSON-RPC          ┌──────────────────────┐
│    OpenClaw 服务器 A   │ ◄──────────────────────────► │    OpenClaw 服务器 B   │
│    (节点A/新加坡)      │      (Tailscale / 内网)       │    (节点B/国内)        │
│  Agent: 皮皮🦊        │                               │  Agent: 小龙女🦞       │
│  A2A 端口: 18800      │                               │  A2A 端口: 18800      │
└──────────────────────┘                               └──────────────────────┘

前提条件

• OpenClaw ≥ 2026.3.0 已安装并运行
• 两台服务器之间网络可达（Tailscale、局域网或公网）
• Node.js ≥ 22

安装步骤

1. 克隆插件（两台服务器都需要）

mkdir -p ~/.openclaw/workspace/plugins
cd ~/.openclaw/workspace/plugins
git clone https://github.com/win4r/openclaw-a2a-gateway.git a2a-gateway
cd a2a-gateway
npm install --production
openclaw plugins install ~/.openclaw/workspace/plugins/a2a-gateway

2. 配置服务器A（以新加坡节点为例）

# 2.1 配置 Agent Card
openclaw config set plugins.entries.a2a-gateway.config.agentCard.name "OpenClaw SG"
openclaw config set plugins.entries.a2a-gateway.config.agentCard.description "新加坡节点"

# 2.2 生成并配置认证 Token
SG_TOKEN=$(openssl rand -hex 24)
echo "新加坡Token: $SG_TOKEN"
openclaw config set plugins.entries.a2a-gateway.config.security.inboundAuth "bearer"
openclaw config set plugins.entries.a2a-gateway.config.security.token "$SG_TOKEN"

# 2.3 设置默认路由（指定 Agent ID）
openclaw config set plugins.entries.a2a-gateway.config.routing.defaultAgentId "main"

# 2.4 重启 Gateway
openclaw gateway restart

3. 配置服务器B（以国内节点为例）

# 3.1 配置 Agent Card
openclaw config set plugins.entries.a2a-gateway.config.agentCard.name "OpenClaw CN"
openclaw config set plugins.entries.a2a-gateway.config.agentCard.description "国内节点"

# 3.2 生成并配置认证 Token
CN_TOKEN=$(openssl rand -hex 24)
echo "国内Token: $CN_TOKEN"
openclaw config set plugins.entries.a2a-gateway.config.security.inboundAuth "bearer"
openclaw config set plugins.entries.a2a-gateway.config.security.token "$CN_TOKEN"

# 3.3 设置默认路由
openclaw config set plugins.entries.a2a-gateway.config.routing.defaultAgentId "main"

# 3.4 添加服务器A为 Peer
openclaw config set plugins.entries.a2a-gateway.config.peers '[{"name":"节点A","agentCardUrl":"http://<节点A_IP>:18800/.well-known/agent-card.json","auth":{"type":"bearer","token":"<节点A_TOKEN>"}}]'

# 3.5 重启 Gateway
openclaw gateway restart

4. 双向配置（重要！）

回到服务器A，添加服务器B为 Peer：

openclaw config set plugins.entries.a2a-gateway.config.peers '[{"name":"节点B","agentCardUrl":"http://<节点B_IP>:18800/.well-known/agent-card.json","auth":{"type":"bearer","token":"<节点B_TOKEN>"}}]'
openclaw gateway restart

验证配置

检查 Agent Card 是否可访问

# 在服务器A上
curl -s http://localhost:18800/.well-known/agent-card.json | python3 -m json.tool

# 从服务器B访问服务器A
curl -s http://<服务器A_IP>:18800/.well-known/agent-card.json

测试跨节点通信

# 从服务器A发送消息到服务器B
node ~/.openclaw/workspace/plugins/a2a-gateway/skill/scripts/a2a-send.mjs \
  --peer-url http://<服务器B_IP>:18800 \
  --token <服务器B_TOKEN> \
  --message "你好，测试通信！"

常见问题解决

❌ 错误：missing scope: operator.write

问题描述：

Agent dispatch failed: missing scope: operator.write

解决方案：
修改 src/executor.ts 文件中的 scopes 配置：

// 找到这一行（约第435行）
scopes: ["operator.admin", "operator.approvals", "operator.pairing"]

// 修改为
scopes: ["operator.admin", "operator.approvals", "operator.pairing", "operator.read", "operator.write"]

修改后重启 Gateway：

openclaw gateway restart

❌ 错误：Method not found

检查点：

1. 确认 Gateway 已重启
2. 确认 Token 正确
3. 确认两台服务器都已配置对方为 Peer

❌ 消息发送成功但无回复

可能原因：

1. 接收方 Gateway 未正确配置
2. 认证失败
3. 路由到的 Agent ID 不存在

排查方法：

1. 检查接收方 Gateway 日志
2. 确认 Agent ID 正确
3. 验证 Bearer Token

配置文件说明

网络方案

方案A：Tailscale（推荐）

# 两台服务器都安装
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 使用 Tailscale IP 进行通信
# 例如：100.x.x.x:18800

方案B：公网 IP

• 确保 18800 端口在防火墙中开放
• 使用 Bearer Token 保证安全

总结

1. 安装：两台服务器都安装 a2a-gateway 插件
2. 配置：分别配置 Agent Card、Token、Peer
3. 重启：每次配置后重启 Gateway
4. 验证：测试跨节点通信

关键点：

• 需要双向添加 Peer
• Scopes 必须包含 operator.read 和 operator.write
• Token 需要互相交换