Building a Gateway client

Building a Gateway client 문서는 OpenClaw 공식 문서(gateway/clients)를 한국어로 정리한 가이드입니다. Build a third-party operator or WebChat client for the Gateway WebSocket protocol 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Build a third-party operator or WebChat client for the Gateway WebSocket protocol

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

문서 구성

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

Install the packages
Choose scopes and pair the device
Advertise client capabilities
Recover state after reconnect
Use history metadata and stable anchors
Subscribe instead of polling usage
Backfill exec approvals
Track protocol versions
관련 문서

상세 내용

본문

Use the published Gateway packages to build operator dashboards, WebChat clients, and other third-party applications. This guide covers the client lifecycle around the wire contract: authentication, capabilities, reconnect recovery, history, subscriptions, and version upgrades.

Install the packages

These packages ship with OpenClaw release trains. During the initial rollout, npm may return E404 until the first package-bearing OpenClaw release is published; install them only after the registry pages below resolve.

주요 항목:

@openclaw/gateway-protocol
@openclaw/gateway-client

npm install @openclaw/gateway-client @openclaw/gateway-protocol

Choose scopes and pair the device

A full interactive chat client that also renders approval prompts should request role: "operator" with these scopes:

Scope	Use it for
`operator.read`	`chat.history`, `sessions.list`, `sessions.subscribe`, model status, and read-only events
`operator.write`	`chat.send` and ordinary session mutations
`operator.approvals`	Listing, displaying, and resolving exec or plugin approvals

Advertise client capabilities

connect.params.caps describes optional behavior the client can consume. It does not grant authorization. Import names from GATEWAY_CLIENT_CAPS instead of duplicating string literals:

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

Recover state after reconnect

Treat every successful reconnect as a new projection over durable history and current in-memory run state:

Use history metadata and stable anchors

Rows returned by chat.history can carry an __openclaw metadata envelope:

주요 항목:

id is the transcript entry identity. Use it for anchored history requests,
seq is the positive transcript-record sequence. One stored record can project
kind identifies synthetic rows. A compaction boundary uses

Load the initial catalog with sessions.list, then call sessions.subscribe once per connection. Merge sessions.changed events by sessionKey. Session change payloads can carry live inputTokens, outputTokens, totalTokens, totalTokensFresh, contextTokens, estimatedCostUsd, response-usage settings, and active-run state.

Backfill exec approvals

A client with operator.approvals should install its event listener as soon as hello-ok completes, then call exec.approval.list to backfill requests that predate the connection. Reconcile the list and live exec.approval.requested / exec.approval.resolved events by approval ID so a transition racing the list request is neither lost nor resurrected.

Track protocol versions

The current wire version is 4. General operator and WebChat clients must negotiate the exact current version with minProtocol: 4 and maxProtocol: 4. Only authenticated node clients and lightweight probes have the N-1 acceptance window, currently protocol 3 through 4.

실습 체크리스트

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

자주 쓰는 명령·설정 예시

npm install @openclaw/gateway-client @openclaw/gateway-protocol

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

Building a Gateway client

핵심 요약

Build a third-party operator or WebChat client for the Gateway WebSocket protocol

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

문서 구성

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

Install the packages
Choose scopes and pair the device
Advertise client capabilities
Recover state after reconnect
Use history metadata and stable anchors
Subscribe instead of polling usage
Backfill exec approvals
Track protocol versions
관련 문서

상세 내용

본문

Install the packages

주요 항목:

@openclaw/gateway-protocol
@openclaw/gateway-client

npm install @openclaw/gateway-client @openclaw/gateway-protocol

Choose scopes and pair the device

A full interactive chat client that also renders approval prompts should request role: "operator" with these scopes:

Scope	Use it for
`operator.read`	`chat.history`, `sessions.list`, `sessions.subscribe`, model status, and read-only events
`operator.write`	`chat.send` and ordinary session mutations
`operator.approvals`	Listing, displaying, and resolving exec or plugin approvals

Advertise client capabilities

connect.params.caps describes optional behavior the client can consume. It does not grant authorization. Import names from GATEWAY_CLIENT_CAPS instead of duplicating string literals:

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

Recover state after reconnect

Treat every successful reconnect as a new projection over durable history and current in-memory run state:

Use history metadata and stable anchors

Rows returned by chat.history can carry an __openclaw metadata envelope:

주요 항목:

id is the transcript entry identity. Use it for anchored history requests,
seq is the positive transcript-record sequence. One stored record can project
kind identifies synthetic rows. A compaction boundary uses

Backfill exec approvals

Track protocol versions

실습 체크리스트

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

자주 쓰는 명령·설정 예시

npm install @openclaw/gateway-client @openclaw/gateway-protocol

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

Building a Gateway client

핵심 요약

문서 구성

상세 내용

본문

Install the packages

Choose scopes and pair the device

Advertise client capabilities

Recover state after reconnect

Use history metadata and stable anchors

Backfill exec approvals

Track protocol versions

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Building a Gateway client

핵심 요약

문서 구성

상세 내용

본문

Install the packages

Choose scopes and pair the device

Advertise client capabilities

Recover state after reconnect

Use history metadata and stable anchors

Backfill exec approvals

Track protocol versions

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Building a Gateway client

핵심 요약

문서 구성

상세 내용

본문

Install the packages

Choose scopes and pair the device

Advertise client capabilities

Recover state after reconnect

Use history metadata and stable anchors

Subscribe instead of polling usage

Backfill exec approvals

Track protocol versions

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Building a Gateway client

핵심 요약

문서 구성

상세 내용

본문

Install the packages

Choose scopes and pair the device

Advertise client capabilities

Recover state after reconnect

Use history metadata and stable anchors

Subscribe instead of polling usage

Backfill exec approvals

Track protocol versions

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드