Gateway 프로토콜

Gateway WS 프로토콜은 OpenClaw의 단일 제어 플레인 + 노드 전송 계층입니다. 모든 클라이언트(CLI, 웹 UI, macOS 앱, iOS/Android 노드, 헤드리스 노드)는 WebSocket으로 연결하고 핸드셰이크 시점에 자신의 역할 + 범위를 선언합니다.

# 전송

• WebSocket, JSON 페이로드가 포함된 텍스트 프레임.
• 첫 번째 프레임은 반드시 connect 요청이어야 합니다.
• 연결 전 프레임은 64 KiB로 제한됩니다. 핸드셰이크가 성공한 뒤에는 클라이언트가 hello-ok.policy.maxPayload 및 hello-ok.policy.maxBufferedBytes 제한을 따라야 합니다. 진단이 활성화된 경우, Gateway가 영향을 받은 프레임을 닫거나 버리기 전에 지나치게 큰 인바운드 프레임과 느린 아웃바운드 버퍼가 payload.large 이벤트를 내보냅니다. 이 이벤트는 크기, 제한, 표면, 안전한 이유 코드를 보관합니다. 메시지 본문, 첨부 파일 내용, 원시 프레임 본문, 토큰, 쿠키 또는 비밀 값은 보관하지 않습니다.

# 핸드셰이크(connect)

Gateway → 클라이언트(연결 전 챌린지):

{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}

클라이언트 → Gateway:

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

Gateway → 클라이언트:

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

Gateway가 아직 시작 사이드카를 마무리하는 중이면 connect 요청은 details.reason이 "startup-sidecars"로 설정되고 retryAfterMs가 포함된 재시도 가능한 UNAVAILABLE 오류를 반환할 수 있습니다. 클라이언트는 이를 최종 핸드셰이크 실패로 표시하지 말고 전체 연결 예산 안에서 해당 응답을 재시도해야 합니다.

server, features, snapshot, policy는 모두 스키마(src/gateway/protocol/schema/frames.ts)에서 필수입니다. auth도 필수이며 협상된 역할/범위를 보고합니다. pluginSurfaceUrls는 선택 사항이며 canvas 같은 Plugin 표면 이름을 범위가 지정된 호스팅 URL에 매핑합니다.

범위가 지정된 Plugin 표면 URL은 만료될 수 있습니다. 노드는 node.pluginSurface.refresh를 { "surface": "canvas" }와 함께 호출해 pluginSurfaceUrls의 새 항목을 받을 수 있습니다. 실험적 Canvas Plugin 리팩터링은 더 이상 사용되지 않는 canvasHostUrl, canvasCapability 또는 node.canvas.capability.refresh 호환 경로를 지원하지 않습니다. 현재 네이티브 클라이언트와 Gateway는 Plugin 표면을 사용해야 합니다.

장치 토큰이 발급되지 않으면 hello-ok.auth는 토큰 필드 없이 협상된 권한을 보고합니다.

{
  "auth": {
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

신뢰할 수 있는 동일 프로세스 백엔드 클라이언트(client.id: "gateway-client", client.mode: "backend")는 공유 Gateway 토큰/비밀번호로 인증하는 직접 루프백 연결에서 device를 생략할 수 있습니다. 이 경로는 내부 제어 플레인 RPC용으로 예약되어 있으며, 오래된 CLI/장치 페어링 기준선이 서브에이전트 세션 업데이트 같은 로컬 백엔드 작업을 막지 않도록 합니다. 원격 클라이언트, 브라우저 출처 클라이언트, 노드 클라이언트, 명시적 장치 토큰/장치 ID 클라이언트는 여전히 일반 페어링 및 범위 업그레이드 검사를 사용합니다.

장치 토큰이 발급되면 hello-ok에는 다음도 포함됩니다.

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

신뢰할 수 있는 부트스트랩 인계 중에는 hello-ok.auth가 deviceTokens에 추가로 제한된 역할 항목을 포함할 수도 있습니다.

{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]
      }
    ]
  }
}

내장 노드/오퍼레이터 부트스트랩 흐름에서는 기본 노드 토큰이 scopes: []로 유지되고, 인계된 모든 오퍼레이터 토큰은 부트스트랩 오퍼레이터 허용 목록(operator.approvals, operator.read, operator.talk.secrets, operator.write)으로 제한됩니다. 부트스트랩 범위 검사는 역할 접두사를 유지합니다. 오퍼레이터 항목은 오퍼레이터 요청만 충족하며, 오퍼레이터가 아닌 역할은 여전히 자체 역할 접두사 아래의 범위가 필요합니다.

# 노드 예시

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

# 프레이밍

• 요청: {type:"req", id, method, params}
• 응답: {type:"res", id, ok, payload|error}
• 이벤트: {type:"event", event, payload, seq?, stateVersion?}

부작용이 있는 메서드에는 멱등성 키가 필요합니다(스키마 참조).

# 역할 + 범위

전체 오퍼레이터 범위 모델, 승인 시점 검사, 공유 비밀 의미 체계는 오퍼레이터 범위를 참조하세요.

# 역할

• operator = 제어 플레인 클라이언트(CLI/UI/자동화).
• node = 기능 호스트(camera/screen/canvas/system.run).

# 범위(오퍼레이터)

일반 범위:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

includeSecrets: true가 있는 talk.config에는 operator.talk.secrets(또는 operator.admin)가 필요합니다.

Plugin에 등록된 Gateway RPC 메서드는 자체 오퍼레이터 범위를 요청할 수 있지만, 예약된 핵심 관리자 접두사(config.*, exec.approvals.*, wizard.*, update.*)는 항상 operator.admin으로 해석됩니다.

메서드 범위는 첫 번째 관문일 뿐입니다. chat.send를 통해 도달하는 일부 슬래시 명령은 그 위에 더 엄격한 명령 수준 검사를 적용합니다. 예를 들어 영구적인 /config set 및 /config unset 쓰기에는 operator.admin이 필요합니다.

node.pair.approve에도 기본 메서드 범위 위에 승인 시점 범위 검사가 추가로 있습니다.

• 명령 없는 요청: operator.pairing
• exec가 아닌 노드 명령이 있는 요청: operator.pairing + operator.write
• system.run, system.run.prepare 또는 system.which를 포함하는 요청: operator.pairing + operator.admin

# 기능/명령/권한(노드)

노드는 연결 시점에 기능 클레임을 선언합니다.

• caps: camera, canvas, screen, location, voice, talk 같은 상위 수준 기능 범주.
• commands: invoke용 명령 허용 목록.
• permissions: 세분화된 토글(예: screen.record, camera.capture).

Gateway는 이를 클레임으로 취급하고 서버 측 허용 목록을 적용합니다.

# 프레즌스

• system-presence는 장치 ID를 키로 하는 항목을 반환합니다.
• 프레즌스 항목에는 deviceId, roles, scopes가 포함되므로, UI는 장치가 operator와 node 양쪽으로 연결된 경우에도 장치당 단일 행을 표시할 수 있습니다.
• node.list에는 선택적 lastSeenAtMs 및 lastSeenReason 필드가 포함됩니다. 연결된 노드는 현재 연결 시간을 lastSeenAtMs로, 이유를 connect로 보고합니다. 페어링된 노드는 신뢰할 수 있는 노드 이벤트가 해당 페어링 메타데이터를 업데이트할 때 지속성 있는 백그라운드 프레즌스도 보고할 수 있습니다.

# 노드 백그라운드 활성 이벤트

노드는 event: "node.presence.alive"와 함께 node.event를 호출해 페어링된 노드가 백그라운드 깨우기 중에 살아 있었음을 연결됨으로 표시하지 않고 기록할 수 있습니다.

{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}

trigger는 닫힌 enum입니다. 값은 background, silent_push, bg_app_refresh, significant_location, manual 또는 connect입니다. 알 수 없는 트리거 문자열은 Gateway가 영속화 전에 background로 정규화합니다. 이 이벤트는 인증된 노드 장치 세션에 대해서만 지속성 있게 저장됩니다. 장치가 없거나 페어링되지 않은 세션은 handled: false를 반환합니다.

성공한 Gateway는 구조화된 결과를 반환합니다.

{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}

이전 Gateway는 node.event에 대해 여전히 { "ok": true }를 반환할 수 있습니다. 클라이언트는 이를 지속성 있는 프레즌스 저장이 아니라 확인된 RPC로 취급해야 합니다.

# 브로드캐스트 이벤트 범위 지정

서버가 푸시하는 WebSocket 브로드캐스트 이벤트는 범위로 보호되므로, 페어링 범위 세션이나 노드 전용 세션이 세션 콘텐츠를 수동으로 수신하지 않습니다.

• 채팅, 에이전트, 도구 결과 프레임(스트리밍된 agent 이벤트 및 도구 호출 결과 포함)에는 최소 operator.read가 필요합니다. operator.read가 없는 세션은 이러한 프레임을 완전히 건너뜁니다.
• Plugin 정의 plugin.* 브로드캐스트는 Plugin이 등록한 방식에 따라 operator.write 또는 operator.admin으로 보호됩니다.
• 상태 및 전송 이벤트(heartbeat, presence, tick, 연결/연결 해제 수명 주기 등)는 전송 상태를 모든 인증된 세션에서 관찰할 수 있도록 제한 없이 유지됩니다.
• 알 수 없는 브로드캐스트 이벤트 계열은 등록된 핸들러가 명시적으로 완화하지 않는 한 기본적으로 범위로 보호됩니다(닫힌 실패).

각 클라이언트 연결은 자체 클라이언트별 시퀀스 번호를 유지하므로, 서로 다른 클라이언트가 이벤트 스트림에서 범위로 필터링된 서로 다른 하위 집합을 보더라도 브로드캐스트는 해당 소켓에서 단조 순서를 보존합니다.

# 일반적인 RPC 메서드 계열

공개 WS 표면은 위의 핸드셰이크/인증 예시보다 넓습니다. 이것은 생성된 덤프가 아닙니다. hello-ok.features.methods는 src/gateway/server-methods-list.ts와 로드된 Plugin/채널 메서드 내보내기로 구성된 보수적인 탐색 목록입니다. 이를 기능 탐색으로 취급하고, src/gateway/server-methods/*.ts의 전체 열거로 취급하지 마세요.

# 일반 이벤트 계열

• chat: chat.inject 같은 UI 채팅 업데이트 및 기타 transcript-only 채팅 이벤트.
• session.message 및 session.tool: 구독된 세션의 transcript/event-stream 업데이트.
• sessions.changed: 세션 인덱스 또는 메타데이터가 변경됨.
• presence: 시스템 presence 스냅샷 업데이트.
• tick: 주기적 keepalive / liveness 이벤트.
• health: gateway health 스냅샷 업데이트.
• heartbeat: heartbeat 이벤트 스트림 업데이트.
• cron: cron 실행/작업 변경 이벤트.
• shutdown: gateway 종료 알림.
• node.pair.requested / node.pair.resolved: node 페어링 수명 주기.
• node.invoke.request: node invoke 요청 브로드캐스트.
• device.pair.requested / device.pair.resolved: 페어링된 device 수명 주기.
• voicewake.changed: wake-word 트리거 설정이 변경됨.
• exec.approval.requested / exec.approval.resolved: exec 승인 수명 주기.
• plugin.approval.requested / plugin.approval.resolved: plugin 승인 수명 주기.

# Node 헬퍼 메서드

• Node는 자동 허용 검사를 위한 현재 skill 실행 파일 목록을 가져오려고 skills.bins를 호출할 수 있습니다.

# 운영자 헬퍼 메서드

• 운영자는 agent의 runtime 명령 인벤토리를 가져오려고 commands.list(operator.read)를 호출할 수 있습니다.
  • agentId는 선택 사항이며, 생략하면 기본 agent workspace를 읽습니다.
  • scope는 기본 name이 대상으로 삼는 surface를 제어합니다.
    • text는 선행 / 없이 기본 텍스트 명령 토큰을 반환합니다.
    • native 및 기본 both 경로는 사용 가능한 경우 provider-aware native 이름을 반환합니다.
  • textAliases는 /model 및 /m 같은 정확한 슬래시 별칭을 포함합니다.
  • nativeName은 존재하는 경우 provider-aware native 명령 이름을 포함합니다.
  • provider는 선택 사항이며 native 이름 지정 및 native plugin 명령 사용 가능 여부에만 영향을 줍니다.
  • includeArgs=false는 응답에서 직렬화된 인수 메타데이터를 생략합니다.
• 운영자는 agent의 runtime 도구 catalog를 가져오려고 tools.catalog(operator.read)를 호출할 수 있습니다. 응답에는 그룹화된 도구와 출처 메타데이터가 포함됩니다.
  • source: core 또는 plugin
  • pluginId: source="plugin"일 때 plugin 소유자
  • optional: plugin 도구가 선택 사항인지 여부
• 운영자는 세션의 runtime-effective 도구 인벤토리를 가져오려고 tools.effective(operator.read)를 호출할 수 있습니다.
  • sessionKey가 필요합니다.
  • gateway는 호출자가 제공한 auth 또는 delivery context를 수락하는 대신 세션에서 신뢰할 수 있는 runtime context를 서버 측에서 파생합니다.
  • 응답은 세션 범위이며 core, plugin, channel 도구를 포함해 활성 대화가 지금 사용할 수 있는 항목을 반영합니다.
• 운영자는 /tools/invoke와 같은 gateway 정책 경로를 통해 사용 가능한 도구 하나를 호출하려고 tools.invoke(operator.write)를 호출할 수 있습니다.
  • name이 필요합니다. args, sessionKey, agentId, confirm, idempotencyKey는 선택 사항입니다.
  • sessionKey와 agentId가 모두 있으면, 해석된 세션 agent가 agentId와 일치해야 합니다.
  • 응답은 ok, toolName, 선택적 output, 형식화된 error 필드가 있는 SDK-facing envelope입니다. 승인 또는 정책 거부는 gateway 도구 정책 pipeline을 우회하지 않고 payload에서 ok:false를 반환합니다.
• 운영자는 agent의 표시 가능한 skill 인벤토리를 가져오려고 skills.status(operator.read)를 호출할 수 있습니다.
  • agentId는 선택 사항이며, 생략하면 기본 agent workspace를 읽습니다.
  • 응답에는 원시 secret 값을 노출하지 않는 eligibility, 누락된 요구 사항, config 검사, 정리된 install 옵션이 포함됩니다.
• 운영자는 ClawHub discovery 메타데이터를 위해 skills.search 및 skills.detail(operator.read)을 호출할 수 있습니다.
• 운영자는 두 가지 모드에서 skills.install(operator.admin)을 호출할 수 있습니다.
  • ClawHub 모드: { source: "clawhub", slug, version?, force? }는 기본 agent workspace skills/ 디렉터리에 skill 폴더를 설치합니다.
  • Gateway installer 모드: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }는 gateway host에서 선언된 metadata.openclaw.install 작업을 실행합니다.
• 운영자는 두 가지 모드에서 skills.update(operator.admin)를 호출할 수 있습니다.
  • ClawHub 모드는 기본 agent workspace에서 추적 중인 slug 하나 또는 추적 중인 모든 ClawHub 설치를 업데이트합니다.
  • Config 모드는 enabled, apiKey, env 같은 skills.entries.<skillKey> 값을 패치합니다.

# models.list 보기

models.list는 선택적 view 매개변수를 허용합니다.

• 생략 또는 "default": 현재 runtime 동작입니다. agents.defaults.models가 구성되어 있으면 응답은 허용된 catalog입니다. 그렇지 않으면 응답은 전체 Gateway catalog입니다.
• "configured": picker-sized 동작입니다. agents.defaults.models가 구성되어 있으면 여전히 우선합니다. 그렇지 않으면 응답은 명시적 models.providers.*.models 항목을 사용하며, 구성된 model 행이 없을 때만 전체 catalog로 fallback합니다.
• "all": 전체 Gateway catalog이며, agents.defaults.models를 우회합니다. 일반 model picker가 아니라 진단 및 discovery UI에 사용하세요.

# Exec 승인

• exec 요청에 승인이 필요하면 gateway가 exec.approval.requested를 브로드캐스트합니다.
• 운영자 client는 exec.approval.resolve를 호출해 해결합니다(operator.approvals scope 필요).
• host=node의 경우, exec.approval.request에는 systemRunPlan(canonical argv/cwd/rawCommand/세션 메타데이터)이 포함되어야 합니다. systemRunPlan이 없는 요청은 거부됩니다.
• 승인 후 전달된 node.invoke system.run 호출은 해당 canonical systemRunPlan을 권위 있는 command/cwd/session context로 재사용합니다.
• 호출자가 prepare와 최종 승인된 system.run 전달 사이에 command, rawCommand, cwd, agentId 또는 sessionKey를 변경하면, gateway는 변경된 payload를 신뢰하지 않고 실행을 거부합니다.

# Agent delivery fallback

• agent 요청은 outbound delivery를 요청하기 위해 deliver=true를 포함할 수 있습니다.
• bestEffortDeliver=false는 엄격한 동작을 유지합니다. 해석되지 않거나 internal-only delivery 대상은 INVALID_REQUEST를 반환합니다.
• bestEffortDeliver=true는 외부로 deliver 가능한 route를 해석할 수 없을 때 session-only 실행으로 fallback할 수 있게 합니다(예: internal/webchat 세션 또는 모호한 multi-channel config).

# Versioning

• PROTOCOL_VERSION은 src/gateway/protocol/version.ts에 있습니다.
• Client는 minProtocol + maxProtocol을 보내며, server는 불일치를 거부합니다.
• Schema + model은 TypeBox 정의에서 생성됩니다.
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

# Client 상수

src/gateway/client.ts의 reference client는 다음 기본값을 사용합니다. 값은 protocol v4 전반에서 안정적이며 third-party client의 예상 baseline입니다.

상수	기본값	출처
PROTOCOL_VERSION	4	src/gateway/protocol/version.ts
요청 제한 시간(RPC별)	30_000 ms	src/gateway/client.ts (requestTimeoutMs)
Preauth / connect-challenge 제한 시간	15_000 ms	src/gateway/handshake-timeouts.ts (config/env가 페어링된 server/client budget을 늘릴 수 있음)
초기 재연결 backoff	1_000 ms	src/gateway/client.ts (backoffMs)
최대 재연결 backoff	30_000 ms	src/gateway/client.ts (scheduleReconnect)
device-token close 이후 fast-retry clamp	250 ms	src/gateway/client.ts
terminate() 전 force-stop 유예	250 ms	FORCE_STOP_TERMINATE_GRACE_MS
stopAndWait() 기본 제한 시간	1_000 ms	STOP_AND_WAIT_TIMEOUT_MS
기본 tick 간격(hello-ok 이전)	30_000 ms	src/gateway/client.ts
Tick-timeout close	침묵이 tickIntervalMs * 2를 초과하면 code 4000	src/gateway/client.ts
MAX_PAYLOAD_BYTES	25 * 1024 * 1024 (25 MB)	src/gateway/server-constants.ts

Server는 유효한 policy.tickIntervalMs, policy.maxPayload, policy.maxBufferedBytes를 hello-ok에서 알립니다. Client는 pre-handshake 기본값이 아니라 이 값들을 준수해야 합니다.

# Auth

• 공유 비밀 Gateway 인증은 구성된 인증 모드에 따라 connect.params.auth.token 또는 connect.params.auth.password를 사용합니다.
• Tailscale Serve(gateway.auth.allowTailscale: true) 또는 non-loopback gateway.auth.mode: "trusted-proxy" 같은 신원 포함 모드는 connect.params.auth.* 대신 요청 헤더로 연결 인증 검사를 충족합니다.
• 비공개 인그레스 gateway.auth.mode: "none"은 공유 비밀 연결 인증을 완전히 건너뜁니다. 이 모드를 공개/신뢰할 수 없는 인그레스에 노출하지 마세요.
• 페어링 후 Gateway는 연결 역할 + 범위로 제한된 device token을 발급합니다. 이는 hello-ok.auth.deviceToken에 반환되며, 이후 연결을 위해 클라이언트가 저장해야 합니다.
• 클라이언트는 성공한 모든 연결 이후 기본 hello-ok.auth.deviceToken을 저장해야 합니다.
• 해당 저장된 device token으로 다시 연결할 때는 그 토큰에 대해 저장된 승인 범위 집합도 재사용해야 합니다. 이렇게 하면 이미 부여된 읽기/프로브/상태 액세스가 유지되며, 재연결이 더 좁은 암시적 관리자 전용 범위로 조용히 축소되는 일을 방지합니다.
• 클라이언트 측 연결 인증 조립(src/gateway/client.ts의 selectConnectAuth):
  • auth.password는 독립적이며 설정된 경우 항상 전달됩니다.
  • auth.token은 우선순위에 따라 채워집니다. 명시적 공유 토큰이 먼저이고, 그다음 명시적 deviceToken, 그다음 저장된 장치별 토큰(deviceId + role 기준)입니다.
  • auth.bootstrapToken은 위 항목 중 어떤 것도 auth.token으로 해석되지 않았을 때만 전송됩니다. 공유 토큰이나 해석된 device token이 있으면 전송되지 않습니다.
  • 일회성 AUTH_TOKEN_MISMATCH 재시도에서 저장된 device token의 자동 승격은 신뢰할 수 있는 엔드포인트에만 허용됩니다. 즉 loopback 또는 고정된 tlsFingerprint가 있는 wss://입니다. 고정이 없는 공개 wss://는 해당하지 않습니다.
• 추가 hello-ok.auth.deviceTokens 항목은 부트스트랩 핸드오프 토큰입니다. wss:// 또는 loopback/local 페어링처럼 신뢰할 수 있는 전송에서 부트스트랩 인증으로 연결한 경우에만 저장하세요.
• 클라이언트가 명시적 deviceToken 또는 명시적 scopes를 제공하면 해당 호출자가 요청한 범위 집합이 계속 권한의 기준이 됩니다. 캐시된 범위는 클라이언트가 저장된 장치별 토큰을 재사용할 때만 재사용됩니다.
• device token은 device.token.rotate 및 device.token.revoke로 교체/폐기할 수 있습니다(operator.pairing 범위 필요).
• device.token.rotate는 교체 메타데이터를 반환합니다. 동일 장치 호출이 이미 해당 device token으로 인증된 경우에만 대체 bearer token을 그대로 반환하므로, 토큰 전용 클라이언트는 다시 연결하기 전에 대체 토큰을 저장할 수 있습니다. 공유/관리자 교체는 bearer token을 그대로 반환하지 않습니다.
• 토큰 발급, 교체, 폐기는 해당 장치의 페어링 항목에 기록된 승인된 역할 집합으로 제한됩니다. 토큰 변경으로 페어링 승인이 부여하지 않은 장치 역할을 확장하거나 대상으로 지정할 수 없습니다.
• 페어링된 장치 토큰 세션에서 장치 관리는 호출자에게 operator.admin도 있지 않은 한 자체 범위로 제한됩니다. 관리자가 아닌 호출자는 자신의 장치 항목만 제거/폐기/교체할 수 있습니다.
• device.token.rotate와 device.token.revoke는 대상 operator token 범위 집합도 호출자의 현재 세션 범위와 대조해 검사합니다. 관리자가 아닌 호출자는 자신이 이미 보유한 것보다 더 넓은 operator token을 교체하거나 폐기할 수 없습니다.
• 인증 실패에는 error.details.code와 복구 힌트가 포함됩니다.
  • error.details.canRetryWithDeviceToken(boolean)
  • error.details.recommendedNextStep(retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• AUTH_TOKEN_MISMATCH에 대한 클라이언트 동작:
  • 신뢰할 수 있는 클라이언트는 캐시된 장치별 토큰으로 한 번의 제한된 재시도를 시도할 수 있습니다.
  • 해당 재시도가 실패하면 클라이언트는 자동 재연결 루프를 중단하고 운영자 조치 안내를 표시해야 합니다.

# 장치 신원 + 페어링

• Node는 키 쌍 지문에서 파생된 안정적인 장치 신원(device.id)을 포함해야 합니다.
• Gateway는 장치 + 역할별로 토큰을 발급합니다.
• local auto-approval이 활성화되지 않은 한 새 장치 ID에는 페어링 승인이 필요합니다.
• 페어링 자동 승인은 직접 local loopback 연결을 중심으로 합니다.
• OpenClaw에는 신뢰할 수 있는 공유 비밀 헬퍼 흐름을 위한 좁은 백엔드/컨테이너 local self-connect 경로도 있습니다.
• 동일 호스트 tailnet 또는 LAN 연결은 여전히 페어링에서 원격으로 처리되며 승인이 필요합니다.
• WS 클라이언트는 일반적으로 connect 중에 device 신원을 포함합니다(operator + node). 장치 없는 operator 예외는 명시적 신뢰 경로뿐입니다.
  • localhost 전용 안전하지 않은 HTTP 호환성을 위한 gateway.controlUi.allowInsecureAuth=true.
  • 성공한 gateway.auth.mode: "trusted-proxy" operator Control UI 인증.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true(비상용, 심각한 보안 수준 저하).
  • 공유 Gateway 토큰/비밀번호로 인증된 direct-loopback gateway-client 백엔드 RPC.
• 모든 연결은 서버가 제공한 connect.challenge nonce에 서명해야 합니다.

# 장치 인증 마이그레이션 진단

아직 챌린지 이전 서명 동작을 사용하는 레거시 클라이언트를 위해, 이제 connect는 안정적인 error.details.reason과 함께 error.details.code 아래에 DEVICE_AUTH_* 세부 코드를 반환합니다.

일반적인 마이그레이션 실패:

메시지	details.code	details.reason	의미
device nonce required	DEVICE_AUTH_NONCE_REQUIRED	device-nonce-missing	클라이언트가 device.nonce를 생략했거나 공백으로 보냈습니다.
device nonce mismatch	DEVICE_AUTH_NONCE_MISMATCH	device-nonce-mismatch	클라이언트가 오래되었거나 잘못된 nonce로 서명했습니다.
device signature invalid	DEVICE_AUTH_SIGNATURE_INVALID	device-signature	서명 페이로드가 v2 페이로드와 일치하지 않습니다.
device signature expired	DEVICE_AUTH_SIGNATURE_EXPIRED	device-signature-stale	서명된 타임스탬프가 허용된 편차를 벗어났습니다.
device identity mismatch	DEVICE_AUTH_DEVICE_ID_MISMATCH	device-id-mismatch	device.id가 공개 키 지문과 일치하지 않습니다.
device public key invalid	DEVICE_AUTH_PUBLIC_KEY_INVALID	device-public-key	공개 키 형식/정규화에 실패했습니다.

마이그레이션 대상:

• 항상 connect.challenge를 기다리세요.
• 서버 nonce를 포함하는 v2 페이로드에 서명하세요.
• 동일한 nonce를 connect.params.device.nonce에 보내세요.
• 선호되는 서명 페이로드는 v3이며, 장치/클라이언트/역할/범위/토큰/nonce 필드에 더해 platform과 deviceFamily도 바인딩합니다.
• 레거시 v2 서명은 호환성을 위해 계속 허용되지만, 페어링된 장치 메타데이터 고정은 재연결 시에도 명령 정책을 계속 제어합니다.

# TLS + 고정

• WS 연결에는 TLS가 지원됩니다.
• 클라이언트는 선택적으로 Gateway 인증서 지문을 고정할 수 있습니다(gateway.tls 구성 및 gateway.remote.tlsFingerprint 또는 CLI --tls-fingerprint 참조).

# 범위

이 프로토콜은 전체 Gateway API(상태, 채널, 모델, 채팅, 에이전트, 세션, Node, 승인 등)를 노출합니다. 정확한 표면은 src/gateway/protocol/schema.ts의 TypeBox 스키마로 정의됩니다.

# 관련 항목

• 브리지 프로토콜
• Gateway 런북