Node pairing

기준일: 2026-07-26
공식 기준: Node pairing

Node pairing 문서는 OpenClaw 공식 문서(gateway/pairing)를 한국어로 정리한 가이드입니다. Node capability approvals: how nodes gain command exposure after device pairing 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Node capability approvals: how nodes gain command exposure after device pairing

한국어 가이드 범위: gateway/pairing 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• How capability approval works
• CLI workflow (headless friendly)
• API surface (gateway protocol)
• Node command gating (2026.3.31+)
• Node event trust boundaries (2026.3.31+)
• SSH-verified device auto-approval (default)
• Auto-approval (macOS app)
• Trusted-CIDR device auto-approval
• Silent pairing supersede cleanup
• Metadata-upgrade auto-approval
• QR pairing helpers
• Locality and forwarded headers
• Storage (local, private)
• Transport behavior
• 관련 문서

상세 내용

본문

Node pairing has two layers, both stored on the paired device record in the Gateway's SQLite state database:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Device pairing (role node) gates the connect handshake. See
• Node capability approval (node.pair.*) gates which declared

How capability approval works

1. A node connects to the Gateway WS (device pairing gates this step). 2. The Gateway compares the declared capability/command surface with the approved one; new or widened surfaces store a pending request on the device record and emit node.pair.requested. 3. You approve or reject the request (CLI or UI). 4. Until approval, node commands stay filtered; approval exposes the declared surface, subject to the normal command policy.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

CLI workflow (headless friendly)

nodes status shows paired/connected nodes and their capabilities.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

API surface (gateway protocol)

role in the paired-device store, drops the approved node surface with it, and invalidates/disconnects that device's node-role sessions. A mixed-role device (for example one that also holds operator) keeps its row and only loses the node role; a node-only device row is deleted. Authz: operator.pairing may remove non-operator node rows; a device-token caller revoking its own node role on a mixed-role device additionally needs operator.admin.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• node.pair.requested - emitted when a new pending request is created.
• node.pair.resolved - emitted when a request is approved, rejected, or
• node.pair.list - list pending and paired nodes (operator.pairing).
• node.pair.approve - approve a pending request.
• node.pair.reject - reject a pending request.
• node.pair.remove - remove a paired node. This revokes the device's node
• node.rename - rename a paired node's operator-facing display name.
• Reconnects with an unchanged surface reuse the pending request; repeated
• Operator scope levels and approval-time checks are summarized in
• node.pair.approve uses the pending request's declared commands to enforce
• commandless request: operator.pairing
• ordinary command request: operator.pairing + operator.write
• admin-sensitive request containing system.run, system.run.prepare,
• Live node commands come from what the node declares on connect, filtered by
• Per-node system.run allow and ask policy lives on the node in

Node command gating (2026.3.31+)

When a node connects for the first time, pairing is requested automatically. Until that request is approved, all pending node commands from that node are filtered and will not execute. Once pairing is approved, the node's declared commands become available, subject to the normal command policy.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Nodes that previously relied on device pairing alone to expose commands must
• Commands queued before pairing approval are dropped, not deferred.

Node event trust boundaries (2026.3.31+)

Node-originated summaries and related session events are restricted to the intended trusted surface. Notification-driven or node-triggered flows that previously relied on broader host or session tool access may need adjustment. This hardening keeps node events from escalating into host-level tool access beyond what the node's trust boundary permits.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

SSH-verified device auto-approval (default)

First-time role: node device pairing from a private/CGNAT address is auto-approved when the gateway can prove machine ownership over SSH: it connects back to the pairing host (BatchMode, StrictHostKeyChecking=yes), runs openclaw node identity --json there, and approves only when the remote device id and public key match the pending request exactly. The key match is what makes this safe: reachability alone never approves, so NAT co-tenants, other users on a shared host, and LAN spoofing all fall through to the normal prompt.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• The gateway process user (or sshVerify.user) can SSH to the node host
• openclaw resolves on the remote PATH for non-interactive sh -lc.
• The connecting IP is a direct (non-proxied, non-loopback) private, ULA,
• Same eligibility floor as trusted-CIDR approval: fresh scopeless node

{
  gateway: {
    nodes: {
      pairing: {
        // Disable entirely:
        sshVerify: false,
        // ...or scope/tune the probe:
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

Auto-approval (macOS app)

The macOS app can attempt a silent approval of node capability requests when:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• the request is marked silent (the gateway marks the first capability
• the app can verify an SSH connection to the gateway host using the same

Trusted-CIDR device auto-approval

WS device pairing for role: node stays manual by default. For private node networks where the Gateway already trusts the network path, operators can opt in with explicit CIDRs or exact IPs:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Disabled when gateway.nodes.pairing.autoApproveCidrs is unset.
• No blanket LAN or private-network auto-approve mode exists; SSH-verified
• Only a fresh role: node device pairing request with no requested scopes is
• Operator, browser, Control UI, and WebChat clients stay manual.
• Role, scope, metadata, and public-key upgrades stay manual.
• Same-host loopback trusted-proxy header paths are not eligible, because that

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

Silent pairing supersede cleanup

Non-interactive approvals record their provenance on the paired-device row: same-host local policy approvals as silent, trusted-CIDR node approvals as trusted-cidr, SSH-verified node approvals as ssh-verified. Clients whose state directory is ephemeral (temporary homes, containers, per-run sandboxes) mint a fresh device keypair per run, and every run silently re-pairs as a brand-new device — without cleanup the paired list grows one stale row per run.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Only records whose latest approval was same-host local (silent) are
• Owner-approved and QR/setup-code (bootstrap) pairings are never removed
• Currently connected devices are skipped, so concurrent local sessions with
• Affected clients are local by construction, so they re-pair silently on

Metadata-upgrade auto-approval

When an already-paired device reconnects with only non-sensitive metadata changes (for example display name or client platform hints), OpenClaw treats that as a metadata-upgrade. Silent auto-approval is narrow: it applies only to trusted non-browser local reconnects that already proved possession of local or shared credentials, including same-host native app reconnects after OS version metadata changes. Browser/Control UI clients and remote clients still use the explicit re-approval flow. Scope upgrades (read to write/admin) and public key changes are not eligible for metadata-upgrade auto-approval; they stay explicit re-approval requests.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

QR pairing helpers

/pair qr renders the pairing payload as structured media so mobile and browser clients can scan it directly.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Locality and forwarded headers

Gateway pairing treats a connection as loopback only when both the raw socket and any upstream proxy evidence agree. If a request arrives on loopback but carries Forwarded, any X-Forwarded-*, or X-Real-IP header evidence, that forwarded-header evidence disqualifies the loopback locality claim, and the pairing path requires explicit approval instead of silently treating the request as a same-host connect. See Trusted Proxy Auth for the equivalent rule on operator auth.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Storage (local, private)

Pairing state lives on the paired device records in the shared SQLite state database under the Gateway state directory (default ~/.openclaw):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• ~/.openclaw/state/openclaw.sqlite (paired devices with device auth,
• Device tokens are secrets; treat the state database as sensitive.
• Rotating a device token uses openclaw devices rotate /

Transport behavior

주요 항목:

• The transport is stateless; it does not store membership.
• If the Gateway is offline or pairing is disabled, nodes cannot pair.
• In remote mode, pairing happens against the remote Gateway's store.

관련 문서

주요 항목:

• Channel pairing
• Nodes CLI
• Devices CLI

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/pairing
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  gateway: {
    nodes: {
      pairing: {
        // Disable entirely:
        sshVerify: false,
        // ...or scope/tune the probe:
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

관련 링크

• 공식 원문: gateway/pairing
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.