Gateway 기반 페어링(Option B) 가이드

새로운 장치를 네트워크에 연결할 때마다 인증을 관리하는 일은 꽤나 번거롭습니다. 어떤 노드가 허용되었는지, 보안 토큰은 어떻게 관리해야 하는지 고민하다 보면 정작 중요한 개발 작업에 집중하기 어려워지곤 하죠. 복잡한 설정 없이 노드를 안전하게 연결하고 관리하고 싶은 개발자분들을 위해 Gateway 기반 페어링 방식을 소개합니다.

이 방식에서 Gateway는 노드 가입 허용 여부를 결정하는 ‘신뢰 지점(Source of Truth)’ 역할을 합니다. macOS 앱과 같은 UI는 대기 중인 요청을 승인하거나 거절하는 프론트엔드 역할을 수행하게 됩니다.

필요한 것

• Gateway 설치 및 실행 환경
• node 역할을 가진 WS 노드
• OpenClaw CLI 도구

빠른 시작

Gateway 기반 페어링을 시작하는 가장 빠른 방법입니다. 5분 안에 노드를 연결해 보세요.

1. 노드 연결: 노드가 Gateway WS에 접속하여 페어링을 요청합니다.
2. 요청 확인: Gateway에서 생성된 pending request를 확인합니다.
3. 승인: CLI를 사용해 요청을 승인합니다.

   openclaw nodes approve \<requestId\>

4. 토큰 발급 및 재연결: 승인이 완료되면 Gateway가 새 토큰을 발급합니다. 노드는 이 토큰을 사용해 자동으로 재연결하며 ‘paired’ 상태가 됩니다.

CLI Workflow

헤드리스 환경에서도 CLI를 통해 노드 상태를 쉽게 관리할 수 있습니다.

# 대기 중인 요청 목록 확인
openclaw nodes pending

# 특정 요청 승인
openclaw nodes approve \<requestId\>

# 특정 요청 거절
openclaw nodes reject \<requestId\>

# 연결된 노드 상태 및 기능 확인
openclaw nodes status

# 노드 이름 변경
openclaw nodes rename --node &lt;id|name|ip&gt; --name "Living Room iPad"

API Surface

Gateway 프로토콜을 통해 페어링 프로세스를 직접 제어할 수 있습니다.

Events

• node.pair.requested: 새로운 대기 요청이 생성될 때 발생합니다.
• node.pair.resolved: 요청이 승인, 거절 또는 만료되었을 때 발생합니다.

Methods

• node.pair.request: 대기 요청을 생성하거나 기존 요청을 재사용합니다. (Idempotent)
• node.pair.list: 대기 중인 노드와 페어링된 노드 목록을 반환합니다.
• node.pair.approve: 요청을 승인하고 새 토큰을 발급합니다.
• node.pair.reject: 요청을 거절합니다.
• node.pair.verify: { nodeId, token } 조합을 검증합니다.

Storage 및 보안

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

• ~/.openclaw/nodes/paired.json: 승인된 노드 정보
• ~/.openclaw/nodes/pending.json: 대기 중인 요청 정보

토큰은 비밀 정보이므로 paired.json 파일은 보안에 유의해서 다뤄야 합니다. 만약 토큰을 교체하려면 노드를 다시 승인하거나 기존 노드 엔트리를 삭제해야 합니다. OPENCLAW_STATE_DIR 환경 변수를 사용하면 저장 경로를 변경할 수 있습니다.

문제 해결

• 요청 만료: 대기 중인 요청은 5분이 지나면 자동으로 만료됩니다. 시간이 지났다면 다시 페어링을 요청하세요.
• Gateway 오프라인: Gateway가 꺼져 있거나 페어링 기능이 비활성화된 경우 노드가 연결될 수 없습니다.
• 자동 승인 실패: macOS 앱의 silent 승인은 동일한 사용자의 SSH 연결을 확인할 수 없을 때 실패하며, 이 경우 수동 승인 프롬프트가 표시됩니다.
• 토큰 재발급: 승인 프로세스는 항상 새로운 토큰을 생성합니다. 기존 토큰은 재사용되지 않습니다.

AI Setup Assistant

다음 단계

• Gateway Configuration
• Node SDK Reference