OpenClaw 한국어 문서

Appearance

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

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

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

개념 ​

  • 보류 중인 요청: 노드가 참여를 요청했으며 승인이 필요합니다.
  • 페어링된 노드: 발급된 인증 토큰이 있는 승인된 노드.
  • 전송: 게이트웨이 WS 엔드포인트는 요청을 전달하지만 멤버십을 결정하지 않습니다. (레거시 TCP 브리지 지원이 제거되었습니다.)

페어링 작동 방식 ​

  1. 노드가 게이트웨이 WS에 연결하고 페어링을 요청합니다.
  2. 게이트웨이는 보류 중인 요청을 저장하고 node.pair.requested를 내보냅니다.
  3. 요청을 승인하거나 거부합니다 (CLI 또는 UI).
  4. 승인 시 게이트웨이는 새 토큰을 발급합니다 (토큰은 재페어링 시 순환됩니다).
  5. 노드는 토큰을 사용하여 재연결하며 이제 "페어링됨" 상태가 됩니다.

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

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

bash
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 — 보류 중 + 페어링된 노드를 나열합니다 (operator.pairing).
  • node.pair.approve — 보류 중인 요청을 승인합니다 (토큰 발급).
  • node.pair.reject — 보류 중인 요청을 거부합니다.
  • node.pair.verify — { nodeId, token }을 확인합니다.

참고 사항:

  • node.pair.request는 노드별로 멱등성을 가집니다: 반복 호출은 동일한 보류 중인 요청을 반환합니다.
  • 동일한 보류 중인 노드에 대한 반복 요청은 저장된 노드 메타데이터와 오퍼레이터 가시성을 위한 최신 허용 목록 선언 명령 스냅샷도 새로 고칩니다.
  • 승인은 항상 새 토큰을 생성합니다; node.pair.request에서 토큰은 반환되지 않습니다.
  • 요청에는 자동 승인 흐름에 대한 힌트로 silent: true가 포함될 수 있습니다.
  • node.pair.approve는 추가 승인 범위를 적용하기 위해 보류 중인 요청의 선언된 명령을 사용합니다:
    • 명령 없는 요청: operator.pairing
    • exec가 아닌 명령 요청: operator.pairing + operator.write
    • system.run / system.run.prepare / system.which 요청: operator.pairing + operator.admin

중요:

  • 노드 페어링은 신뢰/신원 흐름 플러스 토큰 발급입니다.
  • 노드별로 라이브 노드 명령 표면을 핀하지 않습니다.
  • 라이브 노드 명령은 게이트웨이의 전역 노드 명령 정책(gateway.nodes.allowCommands / denyCommands)이 적용된 후 노드가 연결 시 선언하는 것에서 옵니다.
  • 노드별 system.run 허용/요청 정책은 페어링 레코드가 아닌 exec.approvals.node.*의 노드에 있습니다.

노드 명령 게이팅 (2026.3.31+) ​

WARNING

호환성을 깨는 변경: 2026.3.31부터 노드 명령은 노드 페어링이 승인될 때까지 비활성화됩니다. 기기 페어링만으로는 선언된 노드 명령을 노출하기에 더 이상 충분하지 않습니다.

노드가 처음 연결될 때 페어링이 자동으로 요청됩니다. 페어링 요청이 승인될 때까지 해당 노드의 모든 보류 중인 노드 명령은 필터링되어 실행되지 않습니다. 페어링 승인을 통해 신뢰가 확립되면 노드의 선언된 명령은 정상 명령 정책에 따라 사용 가능해집니다.

이는 다음을 의미합니다:

  • 이전에 명령을 노출하기 위해 기기 페어링만 사용했던 노드는 이제 노드 페어링을 완료해야 합니다.
  • 페어링 승인 전에 대기열에 있던 명령은 연기되지 않고 삭제됩니다.

노드 이벤트 신뢰 경계 (2026.3.31+) ​

WARNING

호환성을 깨는 변경: 노드 발생 실행은 이제 축소된 신뢰할 수 있는 표면에 유지됩니다.

노드 발생 요약 및 관련 세션 이벤트는 의도된 신뢰할 수 있는 표면으로 제한됩니다. 이 강화는 노드 이벤트가 노드의 신뢰 경계가 허용하는 것 이상의 호스트 수준 도구 액세스로 에스컬레이션할 수 없도록 보장합니다.

자동 승인 (macOS 앱) ​

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

  • 요청이 silent로 표시된 경우, 그리고
  • 앱이 동일한 사용자를 사용하여 게이트웨이 호스트에 SSH 연결을 확인할 수 있는 경우.

자동 승인이 실패하면 정상적인 "승인/거부" 프롬프트로 폴백합니다.

저장 (로컬, 비공개) ​

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

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

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

보안 참고 사항:

  • 토큰은 시크릿입니다; paired.json을 민감한 것으로 취급하십시오.
  • 토큰을 순환하려면 재승인(또는 노드 항목 삭제)이 필요합니다.

전송 동작 ​

  • 전송은 상태 없음입니다; 멤버십을 저장하지 않습니다.
  • 게이트웨이가 오프라인이거나 페어링이 비활성화된 경우 노드는 페어링할 수 없습니다.
  • 게이트웨이가 원격 모드에 있는 경우 페어링은 여전히 원격 게이트웨이의 스토어에 대해 발생합니다.