Gateway 프로토콜

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

전송

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

​

핸드셰이크(connect)

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

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "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": "…"
    }
  }
}

{
  "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
    }
  }
}

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

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

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

​

노드 예시

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "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?}

​

Role + scope

​

Role

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

​

Scope(operator)

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

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

​

Caps/commands/permissions(노드)

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

​

Presence

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

​

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

{
  "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\"}"
}

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

​

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

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

​

일반적인 RPC 메서드 계열

​

일반 이벤트 계열

• chat: chat.inject 및 기타 기록 전용 채팅 이벤트와 같은 UI 채팅 업데이트입니다.
• session.message 및 session.tool: 구독된 세션의 기록/이벤트 스트림 업데이트입니다.
• sessions.changed: 세션 인덱스 또는 메타데이터가 변경되었습니다.
• presence: 시스템 현재 상태 스냅샷 업데이트입니다.
• tick: 주기적인 keepalive / liveness 이벤트입니다.
• health: Gateway 상태 스냅샷 업데이트입니다.
• heartbeat: Heartbeat 이벤트 스트림 업데이트입니다.
• cron: Cron 실행/작업 변경 이벤트입니다.
• shutdown: Gateway 종료 알림입니다.
• node.pair.requested / node.pair.resolved: Node 페어링 수명 주기입니다.
• node.invoke.request: Node invoke 요청 브로드캐스트입니다.
• device.pair.requested / device.pair.resolved: 페어링된 기기 수명 주기입니다.
• voicewake.changed: 깨우기 단어 트리거 구성이 변경되었습니다.
• exec.approval.requested / exec.approval.resolved: exec 승인 수명 주기입니다.
• plugin.approval.requested / plugin.approval.resolved: Plugin 승인 수명 주기입니다.

​

Node 헬퍼 메서드

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

​

작업 원장 RPC

• tasks.list에는 operator.read가 필요합니다.
  • 매개변수: 선택적 status("queued", "running", "completed", "failed", "cancelled" 또는 "timed_out") 또는 해당 상태들의 배열, 선택적 agentId, 선택적 sessionKey, 1부터 500까지의 선택적 limit, 선택적 문자열 cursor.
  • 결과: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get에는 operator.read가 필요합니다.
  • 매개변수: { "taskId": string }.
  • 결과: { "task": TaskSummary }.
  • 누락된 작업 ID는 Gateway not-found 오류 형태를 반환합니다.
• tasks.cancel에는 operator.write가 필요합니다.
  • 매개변수: { "taskId": string, "reason"?: string }.
  • 결과: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found는 원장에 일치하는 작업이 있었는지를 보고합니다. cancelled는 런타임이 취소를 수락했거나 기록했는지를 보고합니다.

​

운영자 헬퍼 메서드

• 운영자는 에이전트의 런타임 명령 인벤토리를 가져오려고 commands.list(operator.read)를 호출할 수 있습니다.
  • agentId는 선택 사항입니다. 기본 에이전트 워크스페이스를 읽으려면 생략합니다.
  • scope는 기본 name이 대상으로 삼는 표면을 제어합니다.
    • text는 앞의 / 없이 기본 텍스트 명령 토큰을 반환합니다.
    • native와 기본 both 경로는 사용 가능한 경우 provider-aware 네이티브 이름을 반환합니다.
  • textAliases는 /model 및 /m 같은 정확한 슬래시 별칭을 전달합니다.
  • nativeName은 존재하는 경우 provider-aware 네이티브 명령 이름을 전달합니다.
  • provider는 선택 사항이며 네이티브 이름 지정과 네이티브 Plugin 명령 사용 가능 여부에만 영향을 줍니다.
  • includeArgs=false는 응답에서 직렬화된 인수 메타데이터를 생략합니다.
• 운영자는 에이전트의 런타임 도구 카탈로그를 가져오려고 tools.catalog(operator.read)를 호출할 수 있습니다. 응답에는 그룹화된 도구와 출처 메타데이터가 포함됩니다.
  • source: core 또는 plugin
  • pluginId: source="plugin"일 때 Plugin 소유자
  • optional: Plugin 도구가 선택 사항인지 여부
• 운영자는 세션의 런타임 유효 도구 인벤토리를 가져오려고 tools.effective(operator.read)를 호출할 수 있습니다.
  • sessionKey는 필수입니다.
  • Gateway는 호출자가 제공한 인증 또는 전달 컨텍스트를 받는 대신 세션 서버 측에서 신뢰할 수 있는 런타임 컨텍스트를 도출합니다.
  • 응답은 세션 범위이며, 활성 대화가 지금 사용할 수 있는 항목을 반영합니다. 여기에는 코어, Plugin, 채널 도구가 포함됩니다.
• 운영자는 /tools/invoke와 동일한 Gateway 정책 경로를 통해 사용 가능한 도구 하나를 호출하려고 tools.invoke(operator.write)를 호출할 수 있습니다.
  • name은 필수입니다. args, sessionKey, agentId, confirm, idempotencyKey는 선택 사항입니다.
  • sessionKey와 agentId가 모두 있으면 확인된 세션 에이전트가 agentId와 일치해야 합니다.
  • 응답은 ok, toolName, 선택적 output, 타입이 지정된 error 필드가 있는 SDK 대상 envelope입니다. 승인 또는 정책 거부는 Gateway 도구 정책 파이프라인을 우회하지 않고 페이로드에서 ok:false를 반환합니다.
• 운영자는 에이전트에 표시되는 Skills 인벤토리를 가져오려고 skills.status(operator.read)를 호출할 수 있습니다.
  • agentId는 선택 사항입니다. 기본 에이전트 워크스페이스를 읽으려면 생략합니다.
  • 응답에는 원시 secret 값을 노출하지 않고 적격성, 누락된 요구사항, 구성 검사, 정제된 설치 옵션이 포함됩니다.
• 운영자는 ClawHub 발견 메타데이터를 위해 skills.search 및 skills.detail(operator.read)을 호출할 수 있습니다.
• 운영자는 설치 전에 비공개 Skills 아카이브를 준비하려고 skills.upload.begin, skills.upload.chunk, skills.upload.commit(operator.admin)을 호출할 수 있습니다. 이는 신뢰할 수 있는 클라이언트를 위한 별도의 관리자 업로드 경로이며, 일반 ClawHub Skills 설치 흐름이 아니고, skills.install.allowUploadedArchives가 활성화되지 않는 한 기본적으로 비활성화됩니다.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? })는 해당 slug와 force 값에 바인딩된 업로드를 생성합니다.
  • skills.upload.chunk({ uploadId, offset, dataBase64 })는 정확히 디코딩된 오프셋에 바이트를 추가합니다.
  • skills.upload.commit({ uploadId, sha256? })는 최종 크기와 SHA-256을 확인합니다. commit은 업로드만 완료하며 Skills를 설치하지 않습니다.
  • 업로드된 Skills 아카이브는 SKILL.md 루트를 포함하는 zip 아카이브입니다. 아카이브의 내부 디렉터리 이름은 설치 대상을 선택하지 않습니다.
• 운영자는 세 가지 모드로 skills.install(operator.admin)을 호출할 수 있습니다.
  • ClawHub 모드: { source: "clawhub", slug, version?, force? }는 Skills 폴더를 기본 에이전트 워크스페이스 skills/ 디렉터리에 설치합니다.
  • 업로드 모드: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? }는 커밋된 업로드를 기본 에이전트 워크스페이스 skills/<slug> 디렉터리에 설치합니다. slug와 force 값은 원래 skills.upload.begin 요청과 일치해야 합니다. 이 모드는 skills.install.allowUploadedArchives가 활성화되지 않으면 거부됩니다. 이 설정은 ClawHub 설치에 영향을 주지 않습니다.
  • Gateway 설치 관리자 모드: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }는 Gateway 호스트에서 선언된 metadata.openclaw.install 작업을 실행합니다.
• 운영자는 두 가지 모드로 skills.update(operator.admin)를 호출할 수 있습니다.
  • ClawHub 모드는 기본 에이전트 워크스페이스에서 추적되는 slug 하나 또는 추적되는 모든 ClawHub 설치를 업데이트합니다.
  • 구성 모드는 enabled, apiKey, env 같은 skills.entries.<skillKey> 값을 패치합니다.

​

models.list 보기

• 생략 또는 "default": 현재 런타임 동작입니다. agents.defaults.models가 구성되어 있으면 응답은 provider/* 항목에 대해 동적으로 발견된 모델을 포함한 허용 카탈로그입니다. 그렇지 않으면 응답은 전체 Gateway 카탈로그입니다.
• "configured": picker 크기의 동작입니다. agents.defaults.models가 구성되어 있으면 provider/* 항목에 대한 provider 범위 발견을 포함해 여전히 우선합니다. allowlist가 없으면 응답은 명시적인 models.providers.*.models 항목을 사용하며, 구성된 모델 행이 없을 때만 전체 카탈로그로 폴백합니다.
• "all": agents.defaults.models를 우회하는 전체 Gateway 카탈로그입니다. 일반 모델 picker가 아니라 진단 및 발견 UI에 사용하세요.

​

Exec 승인

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

​

에이전트 전달 폴백

• agent 요청은 아웃바운드 전달을 요청하기 위해 deliver=true를 포함할 수 있습니다.
• bestEffortDeliver=false는 엄격한 동작을 유지합니다. 확인되지 않았거나 내부 전용인 전달 대상은 INVALID_REQUEST를 반환합니다.
• bestEffortDeliver=true는 외부로 전달 가능한 경로를 확인할 수 없을 때(예: 내부/webchat 세션 또는 모호한 다중 채널 구성) 세션 전용 실행으로 폴백할 수 있게 합니다.
• 최종 agent 결과에는 전달이 요청된 경우 result.deliveryStatus가 포함될 수 있으며, openclaw agent --json --deliver에 문서화된 것과 동일한 sent, suppressed, partial_failed, failed 상태를 사용합니다.

​

버전 관리

• PROTOCOL_VERSION은 src/gateway/protocol/version.ts에 있습니다.
• 클라이언트는 minProtocol + maxProtocol을 보냅니다. 서버는 현재 프로토콜을 포함하지 않는 범위를 거부합니다. 네이티브 클라이언트는 v3 하한을 사용하므로 추가형 v4 클라이언트도 v3 Gateway에 계속 도달할 수 있습니다.
• 스키마 + 모델은 TypeBox 정의에서 생성됩니다.
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

클라이언트 상수

​

인증

• 공유 비밀 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.* 대신 요청 헤더에서 연결 인증 검사를 충족합니다.
• private-ingress 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에 대한 클라이언트 동작:
  • 신뢰할 수 있는 클라이언트는 캐시된 디바이스별 토큰으로 제한된 재시도를 한 번 시도할 수 있습니다.
  • 해당 재시도가 실패하면 클라이언트는 자동 재연결 루프를 중지하고 운영자 조치 안내를 표시해야 합니다.
• AUTH_SCOPE_MISMATCH는 device token이 인식되었지만 요청된 역할/범위를 포함하지 않는다는 뜻입니다. 클라이언트는 이를 잘못된 토큰으로 표시해서는 안 됩니다. 운영자에게 다시 페어링하거나 더 좁거나 더 넓은 범위 계약을 승인하도록 요청하세요.

​

디바이스 ID + 페어링

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

​

디바이스 인증 마이그레이션 진단

• 항상 connect.challenge를 기다립니다.
• 서버 nonce를 포함하는 v2 페이로드에 서명합니다.
• 동일한 nonce를 connect.params.device.nonce에 보냅니다.
• 권장 서명 페이로드는 v3이며, device/client/role/scopes/token/nonce 필드에 더해 platform 및 deviceFamily를 바인딩합니다.
• 레거시 v2 서명은 호환성을 위해 계속 허용되지만, 페어링된 디바이스 메타데이터 고정은 재연결 시에도 명령 정책을 계속 제어합니다.

​

TLS + 고정

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

​

범위

​

관련 항목

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