Gateway 소유 페어링 (옵션 B)

Gateway 소유 페어링에서는 Gateway가 어떤 node들이 가입할 수 있는지에 대한 신뢰의 원천입니다. UI(macOS 앱, 향후 클라이언트)는 단지 대기 중인 요청을 승인하거나 거부하는 프론트엔드일 뿐입니다.

중요: WS node는 connect 중에 device 페어링 (role node)을 사용합니다. node.pair.*는 별도의 페어링 저장소이며 WS 핸드셰이크를 제어하지 않습니다. 명시적으로 node.pair.*를 호출하는 클라이언트만 이 플로우를 사용합니다.

개념

  • 대기 중인 요청: node가 가입을 요청했으며 승인이 필요합니다.
  • 페어링된 node: 발급된 인증 token으로 승인된 node.
  • 전송: Gateway WS 엔드포인트가 요청을 전달하지만 멤버십을 결정하지는 않습니다. (레거시 TCP 브리지 지원은 deprecated/제거됨.)

페어링 작동 방식

  1. node가 Gateway WS에 연결하여 페어링을 요청합니다.
  2. Gateway는 대기 중인 요청을 저장하고 node.pair.requested를 발생시킵니다.
  3. 요청을 승인하거나 거부합니다 (CLI 또는 UI).
  4. 승인 시, Gateway는 새 token을 발급합니다 (token은 재페어링 시 로테이션됨).
  5. node가 token을 사용하여 재연결하면 이제 "페어링"됩니다.

대기 중인 요청은 5분 후 자동으로 만료됩니다.

CLI 워크플로우 (헤드리스 친화적)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status는 페어링/연결된 node와 그 기능을 표시합니다.

API 표면 (gateway 프로토콜)

이벤트:

  • node.pair.requested — 새 대기 중인 요청이 생성될 때 발생.
  • node.pair.resolved — 요청이 승인/거부/만료될 때 발생.

메서드:

  • node.pair.request — 대기 중인 요청 생성 또는 재사용.
  • node.pair.list — 대기 중 + 페어링된 node 목록 조회.
  • node.pair.approve — 대기 중인 요청 승인 (token 발급).
  • node.pair.reject — 대기 중인 요청 거부.
  • node.pair.verify — { nodeId, token } 확인.

참고:

  • node.pair.request는 node당 멱등성을 가집니다: 반복 호출은 동일한 대기 중인 요청을 반환합니다.
  • 승인은 항상 새로운 token을 생성합니다; node.pair.request에서 token이 반환되지 않습니다.
  • 요청은 자동 승인 플로우에 대한 힌트로 silent: true를 포함할 수 있습니다.

자동 승인 (macOS 앱)

macOS 앱은 다음과 같은 경우 선택적으로 무음 승인을 시도할 수 있습니다:

  • 요청이 silent로 표시되고,
  • 앱이 동일한 사용자를 사용하여 gateway 호스트에 대한 SSH 연결을 확인할 수 있습니다.

무음 승인이 실패하면, 일반 "승인/거부" 프롬프트로 폴백합니다.

저장소 (로컬, 비공개)

페어링 상태는 Gateway 상태 디렉토리 (기본값 ~/.openclaw) 아래에 저장됩니다:

  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json

OPENCLAW_STATE_DIR을 재정의하면, nodes/ 폴더가 함께 이동합니다.

보안 참고사항:

  • Token은 비밀입니다; paired.json을 민감하게 취급하세요.
  • Token 로테이션은 재승인이 필요합니다 (또는 node 항목 삭제).

전송 동작

  • 전송은 무상태입니다; 멤버십을 저장하지 않습니다.
  • Gateway가 오프라인이거나 페어링이 비활성화되어 있으면, node는 페어링할 수 없습니다.
  • Gateway가 원격 모드인 경우에도 페어링은 원격 Gateway의 저장소에 대해 발생합니다.
← 문서로 돌아가기