> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openclaw.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 게이트웨이 소유 페어링

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

게이트웨이 소유 페어링에서는 **게이트웨이**가 어떤 노드가 참여할 수 있는지에 대한 진실의 근원입니다. UI(macOS 앱, 미래의 클라이언트)는 대기 중인 요청을 승인하거나 거부하는 프론트엔드일 뿐입니다.

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

## 개념

* **대기 중인 요청**: 노드가 참여를 요청했고 승인이 필요함.
* **페어링된 노드**: 승인된 노드이며 인증 토큰이 발급됨.
* **전송**: 게이트웨이 WS 엔드포인트는 요청을 전달하지만 멤버십을 결정하지 않습니다. (이전 TCP 브리지 지원은 폐기/제거되었습니다.)

## 페어링이 작동하는 방법

1. 노드가 게이트웨이 WS에 연결하고 페어링을 요청합니다.
2. 게이트웨이는 **대기 중인 요청**을 저장하고 `node.pair.requested`를 발행합니다.
3. 당신은 요청을 승인하거나 거부합니다 (CLI 또는 UI).
4. 승인 시, 게이트웨이는 **새로운 토큰**을 발행합니다 (재페어링 시 토큰이 회전됨).
5. 노드는 토큰을 사용하여 다시 연결되며 이제 "페어링됨" 상태가 됩니다.

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

## CLI 작업 흐름 (헤드리스 친화적)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`는 노드당 멱등성을 가집니다: 반복 호출은 같은 대기 중인 요청을 반환합니다.
* 승인 시 **항상** 새로운 토큰이 생성됩니다; `node.pair.request`로부터는 토큰이 절대 반환되지 않습니다.
* 요청은 자동 승인 흐름을 위한 힌트로 `silent: true`를 포함할 수 있습니다.

## 자동 승인 (macOS 앱)

macOS 앱은 다음의 경우 **자동 승인**을 시도할 수 있습니다:

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

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

## 저장소 (로컬, 개인)

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

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

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

보안 노트:

* 토큰은 비밀입니다; `paired.json`을 민감하게 취급하십시오.
* 토큰을 회전하기 위해서는 재승인이 필요합니다 (또는 노드 엔트리 삭제).

## 전송 동작

* 전송은 **무상태**이며, 멤버십을 저장하지 않습니다.
* 게이트웨이가 오프라인이거나 페어링이 비활성화된 경우, 노드들은 페어링할 수 없습니다.
* 게이트웨이가 원격 모드인 경우, 페어링은 여전히 원격 게이트웨이의 저장소에서 발생합니다.