게이트웨이 소유 페어링 (옵션 B)

게이트웨이 소유 페어링에서는 게이트웨이가 어떤 노드의 참여를 허용할지에 대한 진실의 원천(source of truth)입니다. UI(macOS 앱, 향후 클라이언트)는 대기 중인 요청을 승인하거나 거부하는 프런트엔드일 뿐입니다.

중요: WS 노드는 connect 시 디바이스 페어링(역할 node)을 사용합니다. node.pair.*는 별도의 페어링 저장소이며, WS 핸드셰이크를 게이트하지 않습니다. 명시적으로 node.pair.*를 호출하는 클라이언트만 이 흐름을 사용합니다.

개념

대기 요청: 노드가 참여를 요청한 상태로, 승인이 필요합니다.
페어링된 노드: 승인된 노드로, 인증 토큰이 발급됩니다.
전송 계층: 게이트웨이 WS 엔드포인트가 요청을 전달하지만 멤버십을 결정하지는 않습니다. (레거시 TCP 브리지 지원은 더 이상 사용되지 않으며/제거되었습니다.)

페어링 작동 방식

노드가 게이트웨이 WS에 연결하고 페어링을 요청합니다.
게이트웨이가 대기 요청을 저장하고 node.pair.requested를 발생시킵니다.
요청을 승인하거나 거부합니다 (CLI 또는 UI).
승인 시 게이트웨이가 새 토큰을 발급합니다 (재페어링 시 토큰이 갱신됩니다).
노드가 토큰을 사용하여 재연결하면 “페어링됨” 상태가 됩니다.

대기 요청은 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는 페어링된/연결된 노드와 해당 기능을 보여줍니다.

API 인터페이스 (게이트웨이 프로토콜)

이벤트:

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

메서드:

node.pair.request — 대기 요청을 생성하거나 기존 것을 재사용.
node.pair.list — 대기 중 + 페어링된 노드 목록 조회.
node.pair.approve — 대기 요청 승인 (토큰 발급).
node.pair.reject — 대기 요청 거부.
node.pair.verify — { nodeId, token } 검증.

참고:

node.pair.request는 노드별 멱등성(idempotent)을 가집니다: 반복 호출 시 동일한 대기 요청을 반환합니다.
승인 시 항상 새 토큰이 생성됩니다. node.pair.request에서는 토큰이 반환되지 않습니다.
요청에 자동 승인 흐름을 위한 힌트로 silent: true를 포함할 수 있습니다.

자동 승인 (macOS 앱)

macOS 앱은 다음 조건에서 선택적으로 자동 승인을 시도할 수 있습니다:

요청에 silent 표시가 있고,
앱이 동일 사용자의 게이트웨이 호스트에 대한 SSH 연결을 확인할 수 있는 경우.

자동 승인이 실패하면, 일반 “승인/거부” 프롬프트로 대체됩니다.

저장소 (로컬, 비공개)

페어링 상태는 게이트웨이 상태 디렉터리(기본값 ~/.openclaw)에 저장됩니다:

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

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

보안 참고:

토큰은 비밀 정보입니다. paired.json을 민감한 파일로 취급하세요.
토큰 갱신을 위해서는 재승인(또는 노드 항목 삭제)이 필요합니다.

전송 계층 동작

전송 계층은 무상태입니다. 멤버십을 저장하지 않습니다.
게이트웨이가 오프라인이거나 페어링이 비활성화된 경우, 노드는 페어링할 수 없습니다.
게이트웨이가 원격 모드인 경우에도 페어링은 원격 게이트웨이의 저장소에 대해 수행됩니다.