OpenClaw A2A 게이트웨이 플러그인

무엇인가요 – OpenClaw 에이전트 플랫폼용 프로덕션 준비 완료 플러그인으로, Google A2A (에이전트 간) v0.3.0 프로토콜을 구현합니다. 서로 다른 머신에 있는 OpenClaw 에이전트들이 자동으로 상호 발견하고, JSON-RPC, REST, 또는 gRPC를 통해 메시지(텍스트, 파일, JSON 데이터)를 교환할 수 있게 해줍니다.

---

핵심 개념

개념	플러그인의 처리 방식
트랜스포트	JSON-RPC → REST → gRPC 순으로 자동 시도하고, 실패 시 폴백. 실시간 상태 업데이트를 위한 허트비트 포함 Server-Sent-Events 스트리밍 지원.
메시지 부분	A2A의 세 가지 파트 유형 – TextPart, FilePart (URI 또는 base64), DataPart 지원. 에이전트 응답에 포함된 파일 URL은 자동으로 아웃바운드 FilePart로 변환됩니다.
라우팅	규칙 기반(정규식, 태그, 기술) + 생물학적 영감을 받은 "힐 방정식" 유사도 점수(기술, 태그, 패턴 일치, 성공률 가중치). 각 메시지마다 최적의 피어를 선택합니다.
디스커버리	DNS-SD(_a2a._tcp SRV/TXT)를 통한 제로 컨피그 피어 탐색, mDNS 자가 광고, 그리고 알려진 피어 수에 따라 간격을 조절하는 큐럼 센싱 폴러.
회복성	네 단계의 서킷 브레이커(닫힘 → 민감도 감소 → 열림 → 복구)와 지수 회복, 적응형 트랜스포트 순위, 푸시 알림 웹훅, 마이클리스-멘텐 스타일의 소프트 동시성 스로틀.
보안	베어러 토큰 인증(단일 토큰 또는 회전 목록), Ed25519 장치 식별, SSRF 보호(호스트 허용 목록, MIME 허용 목록, 크기 제한), JSON-L 감사 로그, 선택적 인증 메트릭스 엔드포인트, TTL 정리가 있는 내구성 디스크 작업 저장소.

---

빠른 시작 (제로 컨피그)

# npm에서 설치 (권장)
openclaw plugins install openclaw-a2a-gateway

# 또는 소스에서
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
openclaw gateway restart

# 에이전트 카드 접근성 확인
curl -s http://localhost:18800/.well-known/agent-card.json | python3 -m json.tool

플러그인은 기본 에이전트 카드(name: "OpenClaw A2A Gateway", skills: [chat])로 시작합니다.

---

피어 추가 및 구성

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

양방향 통신을 위해서는 양측 모두 상대방을 피어로 추가하고 재시작해야 합니다.

---

메시지 전송

플러그인은 공식 @a2a-js/sdk 클라이언트를 감싸는 헬퍼 스크립트를 제공합니다.

node <PLUGIN_PATH>/skill/scripts/a2a-send.mjs \
  --peer-url http://<PEER_IP>:18800 \
  --token <PEER_TOKEN> \
  --message "Hello from Server A!"

장시간 또는 다중 라운드 상호작용은 비차단 모드로 폴링하여 실행 가능:

node <PLUGIN_PATH>/skill/scripts/a2a-send.mjs \
  --peer-url http://<PEER_IP>:18800 \
  --token <PEER_TOKEN> \
  --non-blocking --wait --timeout-ms 600000 --poll-ms 1000 \
  --message "Discuss A2A advantages in 3 rounds"

원격 측의 특정 OpenClaw agentId를 타겟으로 하려면(OpenClaw 전용 확장 기능), --agent-id <ID>를 추가합니다.

---

에이전트 측 도구

플러그인은 에이전트가 호출할 수 있는 a2a_send_file 도구를 등록합니다:

매개변수	필수?	의미
peer	예	구성된 피어의 이름
uri	예	파일의 공개 URL
name	아니요	파일 이름 (예: report.pdf)
mimeType	아니요	MIME 타입 (생략 시 자동 감지)
text	아니요	선택적 캡션
agentId	아니요	원격 OpenClaw 에이전트 ID (확장 기능)

에이전트는 TOOLS.md 항목을 a-2-a-send.mjs 스크립트로 링크함으로써 이 도구를 사용할 수 있도록 가르칠 수 있습니다.

---

네트워크 옵션

옵션	사용 시기
Tailscale (권장)	서버 간 보안 메시; 방화벽 변경 없이 가능.
LAN	두 머신이 동일한 로컬 네트워크에 있음; 단지 포트 18800을 열기만 하면 됨.
공용 IP	인터넷에 노출됨; 베어러 토큰과 선택적 방화벽 규칙으로 보호 필요.

---

구성 참조 (요약)

{
  "agentCard": {
    "name": "OpenClaw A2A Gateway",
    "description": "A2A bridge for OpenClaw agents",
    "skills": [{"id":"chat","name":"chat","description":"Chat bridge"}]
  },
  "server": {"host":"0.0.0.0","port":18800},
  "security": {"inboundAuth":"bearer","token":"<TOKEN>"},
  "routing": {"defaultAgentId":"main","rules":[]},
  "peers": []
}

주요 섹션은 agentCard, server, security (토큰 회전, MIME 허용 목록, 파일 크기 제한), routing (기본 에이전트 ID, 규칙 목록), peers (URL과 인증 정보를 가진 원격 에이전트 배열)입니다.

---

누구에게 적합한가요?

• 다중 에이전트 배포 – 서로 다른 OpenClaw 인스턴스가 통신이 필요한 경우 (예: 챗봇 클러스터, 소셜미디어 자동화 봇, 분산 도구 호출 에이전트).
• 연구자 – 대규모 에이전트 생태계를 구축하고, 자체 네트워크 레이어를 작성하지 않고도 자동 발견과 생물학적 영감 루팅을 원하는 사람.
• 운영 팀 – 이미 OpenClaw를 운영 중이며, 데이터센터, 엣지, 클라우드 노드 간에 보안적이고 제로 컨피그 브리지가 필요한 사람.

---

TL;DR

OpenClaw A2A Gateway는 설치 가능한 Node.js 플러그인으로, OpenClaw 에이전트가 기계 간에 표준 준수, 자동 발견, 회복성 있는 방식으로 서로 호출할 수 있도록 합니다. 트랜스포트 폴백, 파트 직렬화, 기술 기반 라우팅, 보안, 관찰성을 기본 제공하며, 몇 줄의 명령어로 설정 가능합니다.