Протокол Gateway

Gateway WS-протокол є єдиною площиною керування + транспортом вузлів для OpenClaw. Усі клієнти (CLI, веб-інтерфейс, застосунок macOS, вузли iOS/Android, headless вузли) підключаються через WebSocket і оголошують свою роль + область дії під час рукостискання.

Транспорт

• WebSocket, текстові фрейми з JSON-навантаженням.
• Перший фрейм має бути запитом connect.
• Фрейми до підключення обмежені 64 KiB. Після успішного рукостискання клієнти мають дотримуватися лімітів hello-ok.policy.maxPayload і hello-ok.policy.maxBufferedBytes. Коли діагностику ввімкнено, завеликі вхідні фрейми й повільні вихідні буфери генерують події payload.large до того, як gateway закриє або відкине відповідний фрейм. Ці події зберігають розміри, ліміти, поверхні та безпечні коди причин. Вони не зберігають тіло повідомлення, вміст вкладень, сире тіло фрейму, токени, cookies або секретні значення.

Рукостискання (connect)

Gateway → Клієнт (виклик до підключення):

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

Клієнт → Gateway:

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

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 ще завершує запуск sidecar-компонентів, запит connect може повернути повторювану помилку UNAVAILABLE з details.reason, встановленим у "startup-sidecars", і retryAfterMs. Клієнти мають повторити цю відповідь у межах свого загального бюджету підключення, а не показувати її як остаточний збій рукостискання.

server, features, snapshot і policy усі є обов’язковими за схемою (packages/gateway-protocol/src/schema/frames.ts). auth також є обов’язковим і повідомляє узгоджені роль/області дії. pluginSurfaceUrls є необов’язковим і зіставляє назви поверхонь plugin, наприклад canvas, зі scoped розміщеними URL.

Scoped URL поверхонь plugin можуть завершуватися. Вузли можуть викликати 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") можуть опускати device на прямих loopback-з’єднаннях, коли вони автентифікуються спільним gateway-токеном/паролем. Цей шлях зарезервований для внутрішніх RPC площини керування й не дає застарілим базовим станам поєднання CLI/пристрою блокувати локальну бекенд-роботу, як-от оновлення сесій subagent. Віддалені клієнти, клієнти з браузерним origin, клієнти-вузли й явні клієнти з токеном пристрою/ідентичністю пристрою далі використовують звичайні перевірки поєднання й підвищення областей дії.

Коли токен пристрою видано, hello-ok також містить:

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

Вбудований bootstrap через QR/код налаштування є свіжим шляхом передачі на мобільний пристрій. Успішне підключення базового коду налаштування повертає основний токен вузла плюс один обмежений токен оператора:

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

Передача оператору навмисно обмежена, щоб QR-онбординг міг запустити мобільний цикл оператора й завершити нативне налаштування без надання областей дії мутації поєднання або operator.admin. Вона включає operator.talk.secrets, щоб нативний клієнт міг прочитати конфігурацію Talk, потрібну після bootstrap. Ширший доступ до поєднання й адміністрування потребує окремого затвердженого поєднання оператора або потоку токена. Клієнти мають зберігати hello-ok.auth.deviceTokens лише коли connect використовував bootstrap-автентифікацію на довіреному транспорті, такому як wss:// або loopback/local pairing.

Приклад вузла

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

Методи з побічними ефектами потребують ключів ідемпотентності (див. схему).

Ролі + області дії

Повну модель областей дії оператора, перевірки під час затвердження й семантику спільних секретів див. у Області дії оператора.

Ролі

• operator = клієнт площини керування (CLI/UI/автоматизація).
• node = хост можливостей (camera/screen/canvas/system.run).

Області дії (оператор)

Поширені області дії:

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

talk.config з includeSecrets: true потребує operator.talk.secrets (або operator.admin). Коли секрети включено, клієнти мають читати активні облікові дані провайдера Talk з talk.resolved.config.apiKey; talk.providers.<id>.apiKey залишається у формі джерела й може бути об’єктом SecretRef або заредагованим рядком.

Зареєстровані plugin методи gateway RPC можуть запитувати власну область дії оператора, але зарезервовані основні префікси адміністрування (config.*, exec.approvals.*, wizard.*, update.*) завжди резолвляться в operator.admin.

Область дії методу є лише першим шлюзом. Деякі slash-команди, доступні через chat.send, застосовують суворіші перевірки на рівні команди додатково. Наприклад, сталі записи /config set і /config unset потребують operator.admin.

node.pair.approve також має додаткову перевірку області дії під час затвердження поверх базової області дії методу:

• запити без команд: operator.pairing
• запити з non-exec командами вузла: operator.pairing + operator.write
• запити, що містять system.run, system.run.prepare або system.which: operator.pairing + operator.admin

Можливості/команди/дозволи (вузол)

Вузли оголошують claims можливостей під час підключення:

• caps: високорівневі категорії можливостей, як-от camera, canvas, screen, location, voice і talk.
• commands: allowlist команд для invoke.
• permissions: деталізовані перемикачі (наприклад, screen.record, camera.capture).

Gateway розглядає їх як claims і застосовує серверні allowlist.

Присутність

• system-presence повертає записи з ключами за ідентичністю пристрою.
• Записи присутності містять deviceId, roles і scopes, щоб UI могли показувати один рядок на пристрій навіть коли він підключається і як operator, і як node.
• node.list містить необов’язкові поля lastSeenAtMs і lastSeenReason. Підключені вузли повідомляють час свого поточного з’єднання як lastSeenAtMs з причиною connect; поєднані вузли також можуть повідомляти сталу фонову присутність, коли довірена подія вузла оновлює їхні метадані поєднання.

Фонова подія активності вузла

Вузли можуть викликати node.event з event: "node.presence.alive", щоб записати, що поєднаний вузол був активним під час фонового пробудження, не позначаючи його підключеним.

{  "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. Невідомі рядки trigger нормалізуються до background gateway перед збереженням. Подія є сталою лише для автентифікованих сесій пристроїв вузла; сесії без пристрою або без поєднання повертають handled: false.

Успішні gateway повертають структурований результат:

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

Старіші gateway можуть усе ще повертати { "ok": true } для node.event; клієнти мають трактувати це як підтверджений RPC, а не як стале збереження присутності.

Обмеження областями дії для broadcast-подій

Надіслані сервером broadcast-події WebSocket обмежуються областями дії, щоб сесії з областю поєднання або лише вузлові сесії не отримували пасивно вміст сесії.

• Фрейми чату, агента й результатів інструментів (зокрема потокові події agent і результати викликів інструментів) потребують щонайменше operator.read. Сесії без operator.read повністю пропускають ці фрейми.
• Визначені plugin broadcast-події plugin.* обмежуються operator.write або operator.admin, залежно від того, як plugin їх зареєстрував.
• Події статусу й транспорту (heartbeat, presence, tick, життєвий цикл connect/disconnect тощо) залишаються необмеженими, щоб стан транспорту був видимий кожній автентифікованій сесії.
• Невідомі сімейства broadcast-подій за замовчуванням обмежуються областями дії (fail-closed), якщо зареєстрований обробник явно їх не послаблює.

Кожне клієнтське з’єднання зберігає власний per-client порядковий номер, тому broadcast-події зберігають монотонне впорядкування на цьому сокеті, навіть коли різні клієнти бачать різні відфільтровані за областю дії підмножини потоку подій.

Поширені сімейства методів RPC

Публічна поверхня WS ширша за наведені вище приклади рукостискання/автентифікації. Це не згенерований dump — hello-ok.features.methods є консервативним списком discovery, побудованим із src/gateway/server-methods-list.ts плюс завантажених експортів методів plugin/channel. Розглядайте його як discovery функцій, а не повний перелік src/gateway/server-methods/*.ts.

Поширені сімейства подій

• chat: оновлення чату UI, як-от chat.inject, та інші події чату лише з транскриптами. У протоколі v4 delta-навантаження несуть deltaText; message залишається накопиченим знімком помічника. Заміни не за префіксом установлюють replace=true і використовують deltaText як текст заміни.
• session.message, session.operation і session.tool: транскрипт, операція сесії в процесі виконання та оновлення потоку подій для підписаної сесії.
• sessions.changed: індекс сесій або метадані змінено.
• presence: оновлення знімка присутності системи.
• tick: періодична подія keepalive / liveness.
• health: оновлення знімка стану gateway.
• heartbeat: оновлення потоку подій heartbeat.
• cron: подія зміни запуску/завдання cron.
• shutdown: сповіщення про вимкнення gateway.
• node.pair.requested / node.pair.resolved: життєвий цикл сполучення вузла.
• node.invoke.request: широкомовний запит виклику вузла.
• device.pair.requested / device.pair.resolved: життєвий цикл спряженого пристрою.
• voicewake.changed: конфігурацію тригера wake-word змінено.
• exec.approval.requested / exec.approval.resolved: життєвий цикл схвалення exec.
• plugin.approval.requested / plugin.approval.resolved: життєвий цикл схвалення plugin.

Допоміжні методи вузлів

• Вузли можуть викликати skills.bins, щоб отримати поточний список виконуваних файлів навичок для перевірок auto-allow.

RPC реєстру завдань

Операторські клієнти можуть переглядати й скасовувати записи фонових завдань Gateway через RPC реєстру завдань. Ці методи повертають очищені зведення завдань, а не необроблений стан runtime.

• tasks.list вимагає operator.read.
  • Параметри: необов’язковий status ("queued", "running", "completed", "failed", "cancelled" або "timed_out") або масив цих статусів, необов’язковий agentId, необов’язковий sessionKey, необов’язковий limit від 1 до 500 і необов’язковий рядок cursor.
  • Результат: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get вимагає operator.read.
  • Параметри: { "taskId": string }.
  • Результат: { "task": TaskSummary }.
  • Відсутні ідентифікатори завдань повертають форму помилки not-found Gateway.
• tasks.cancel вимагає operator.write.
  • Параметри: { "taskId": string, "reason"?: string }.
  • Результат: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found повідомляє, чи мав реєстр відповідне завдання. cancelled повідомляє, чи runtime прийняв або записав скасування.

TaskSummary містить id, status і необов’язкові метадані, як-от kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, часові позначки, прогрес, термінальне зведення й очищений текст помилки. agentId ідентифікує агента, який виконує завдання; sessionKey і ownerKey зберігають контекст запитувача та керування.

Допоміжні методи оператора

• Оператори можуть викликати commands.list (operator.read), щоб отримати інвентар команд середовища виконання для агента.
  • agentId необов’язковий; не вказуйте його, щоб читати робочий простір агента за замовчуванням.
  • scope керує тим, на яку поверхню націлюється основне name:
    • text повертає основний текстовий токен команди без початкового /
    • native і стандартний шлях both повертають нативні імена з урахуванням провайдера, коли вони доступні
  • textAliases містить точні slash-аліаси, як-от /model і /m.
  • nativeName містить нативну назву команди з урахуванням провайдера, коли вона існує.
  • provider необов’язковий і впливає лише на нативне іменування та доступність нативних команд Plugin.
  • includeArgs=false вилучає серіалізовані метадані аргументів із відповіді.
• Оператори можуть викликати tools.catalog (operator.read), щоб отримати каталог інструментів середовища виконання для агента. Відповідь містить згруповані інструменти та метадані походження:
  • source: core або plugin
  • pluginId: власник Plugin, коли source="plugin"
  • optional: чи є інструмент Plugin необов’язковим
• Оператори можуть викликати tools.effective (operator.read), щоб отримати фактичний інвентар інструментів середовища виконання для сеансу.
  • sessionKey обов’язковий.
  • Gateway виводить довірений контекст середовища виконання з сеансу на боці сервера замість приймати auth або контекст доставки, наданий викликачем.
  • Відповідь є серверною проєкцією активного інвентарю в межах сеансу, зокрема core, Plugin, channel і вже виявлені інструменти MCP-сервера.
  • tools.effective доступний лише для читання для MCP: він може пропустити прогрітий каталог MCP сеансу через фінальну політику інструментів, але не створює середовища виконання MCP, не підключає транспорти й не викликає tools/list. Якщо відповідного прогрітого каталогу немає, відповідь може містити повідомлення на кшталт mcp-not-yet-connected, mcp-not-yet-listed або mcp-stale-catalog.
  • Елементи фактичних інструментів використовують source="core", source="plugin", source="channel" або source="mcp".
• Оператори можуть викликати tools.invoke (operator.write), щоб викликати один доступний інструмент через той самий шлях політики Gateway, що й /tools/invoke.
  • name обов’язковий. args, sessionKey, agentId, confirm і idempotencyKey необов’язкові.
  • Якщо наявні і sessionKey, і agentId, розв’язаний агент сеансу має збігатися з agentId.
  • Core-обгортки лише для власників, як-от cron, gateway і nodes, потребують ідентичності власника/адміністратора (operator.admin), хоча сам метод tools.invoke є operator.write.
  • Відповідь є конвертом для SDK із полями ok, toolName, необов’язковим output і типізованими полями error. Відмови через схвалення або політику повертають ok:false у payload замість обходу конвеєра політики інструментів Gateway.
• Оператори можуть викликати skills.status (operator.read), щоб отримати видимий інвентар навичок для агента.
  • agentId необов’язковий; не вказуйте його, щоб читати робочий простір агента за замовчуванням.
  • Відповідь містить придатність, відсутні вимоги, перевірки конфігурації та санітизовані параметри встановлення без розкриття необроблених секретних значень.
• Оператори можуть викликати skills.search і skills.detail (operator.read) для метаданих пошуку ClawHub.
• Оператори можуть викликати skills.upload.begin, skills.upload.chunk і skills.upload.commit (operator.admin), щоб підготувати приватний архів навички перед установленням. Це окремий шлях адміністративного завантаження для довірених клієнтів, а не звичайний потік установлення навичок ClawHub, і він вимкнений за замовчуванням, якщо не ввімкнено skills.install.allowUploadedArchives.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) створює завантаження, прив’язане до цього slug і значення force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) додає байти за точним декодованим offset.
  • skills.upload.commit({ uploadId, sha256? }) перевіряє фінальний розмір і SHA-256. Commit лише завершує завантаження; він не встановлює навичку.
  • Завантажені архіви навичок є zip-архівами, що містять кореневий SKILL.md. Внутрішня назва каталогу архіву ніколи не вибирає ціль установлення.
• Оператори можуть викликати skills.install (operator.admin) у трьох режимах:
  • Режим ClawHub: { source: "clawhub", slug, version?, force? } встановлює папку навички в каталог skills/ робочого простору агента за замовчуванням.
  • Режим завантаження: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } встановлює підтверджене завантаження в каталог skills/<slug> робочого простору агента за замовчуванням. Значення slug і force мають збігатися з початковим запитом skills.upload.begin. Цей режим відхиляється, якщо не ввімкнено skills.install.allowUploadedArchives. Налаштування не впливає на встановлення ClawHub.
  • Режим інсталятора Gateway: { name, installId, timeoutMs? } запускає оголошену дію metadata.openclaw.install на хості Gateway. Старіші клієнти все ще можуть надсилати dangerouslyForceUnsafeInstall; це поле застаріле, приймається лише для сумісності протоколу й ігнорується. Використовуйте security.installPolicy для рішень щодо встановлення, якими володіє оператор.
• Оператори можуть викликати skills.update (operator.admin) у двох режимах:
  • Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у робочому просторі агента за замовчуванням.
  • Режим конфігурації патчить значення skills.entries.<skillKey>, як-от enabled, apiKey і env.

Подання models.list

models.list приймає необов’язковий параметр view:

• Не вказано або "default": поточна поведінка середовища виконання. Якщо налаштовано agents.defaults.models, відповіддю є дозволений каталог, зокрема динамічно виявлені моделі для записів provider/*. Інакше відповіддю є повний каталог Gateway.
• "configured": поведінка розміру picker. Якщо налаштовано agents.defaults.models, він усе одно має пріоритет, зокрема виявлення в межах провайдера для записів provider/*. Без allowlist відповідь використовує явні записи models.providers.*.models, повертаючись до повного каталогу лише тоді, коли немає налаштованих рядків моделей.
• "all": повний каталог Gateway з обходом agents.defaults.models. Використовуйте це для діагностики та UI виявлення, а не для звичайних picker моделей.

Схвалення exec

• Коли запит exec потребує схвалення, Gateway транслює exec.approval.requested.
• Клієнти операторів розв’язують це викликом exec.approval.resolve (потребує scope operator.approvals).
• Для host=node exec.approval.request має містити systemRunPlan (канонічні argv/cwd/rawCommand/метадані сеансу). Запити без systemRunPlan відхиляються.
• Після схвалення переспрямовані виклики node.invoke system.run повторно використовують цей канонічний systemRunPlan як авторитетний контекст command/cwd/session.
• Якщо викликач змінює command, rawCommand, cwd, agentId або sessionKey між підготовкою та фінальним схваленим переспрямуванням system.run, Gateway відхиляє запуск замість довіряти зміненому payload.

Резервний варіант доставки агентом

• Запити agent можуть містити deliver=true, щоб запитати вихідну доставку.
• bestEffortDeliver=false зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставки повертають INVALID_REQUEST.
• bestEffortDeliver=true дозволяє резервний перехід до виконання лише в межах сеансу, коли неможливо розв’язати зовнішній маршрут доставки (наприклад, внутрішні/webchat-сеанси або неоднозначні багатоканальні конфігурації).
• Фінальні результати agent можуть містити result.deliveryStatus, коли було запитано доставку, використовуючи ті самі статуси sent, suppressed, partial_failed і failed, які задокументовані для openclaw agent --json --deliver.

Версіонування

• PROTOCOL_VERSION міститься в packages/gateway-protocol/src/version.ts.
• Клієнти надсилають minProtocol + maxProtocol; сервер відхиляє діапазони, які не містять його поточний протокол. Поточні клієнти й сервери потребують протокол v4.
• Схеми + моделі генеруються з визначень TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Константи клієнта

Еталонний клієнт у src/gateway/client.ts використовує ці значення за замовчуванням. Значення стабільні в межах protocol v4 і є очікуваною базою для сторонніх клієнтів.

Сервер оголошує фактичні policy.tickIntervalMs, policy.maxPayload і policy.maxBufferedBytes у hello-ok; клієнти мають дотримуватися цих значень, а не стандартних значень до handshake.

Auth

• Автентифікація Gateway за спільним секретом використовує connect.params.auth.token або connect.params.auth.password, залежно від налаштованого режиму автентифікації.
• Режими з ідентичністю, як-от Tailscale Serve (gateway.auth.allowTailscale: true) або не-loopback gateway.auth.mode: "trusted-proxy", задовольняють перевірку автентифікації підключення через заголовки запиту замість connect.params.auth.*.
• Private-ingress gateway.auth.mode: "none" повністю пропускає автентифікацію підключення за спільним секретом; не відкривайте цей режим на публічному/ненадійному ingress.
• Після спарювання Gateway видає токен пристрою, обмежений роллю підключення
  • scopes. Він повертається в hello-ok.auth.deviceToken, і клієнт має зберігати його для майбутніх підключень.
• Клієнти мають зберігати основний hello-ok.auth.deviceToken після будь-якого успішного підключення.
• Повторне підключення з цим збереженим токеном пристрою також має повторно використовувати збережений затверджений набір scopes для цього токена. Це зберігає доступ для читання/проби/статусу, який уже було надано, і не дає повторним підключенням непомітно звузитися до неявного scope лише для адміністратора.
• Складання автентифікації підключення на боці клієнта (selectConnectAuth у src/gateway/client.ts):
  • auth.password є ортогональним і завжди передається, коли заданий.
  • auth.token заповнюється в порядку пріоритету: спочатку явний спільний токен, потім явний deviceToken, потім збережений токен для пристрою (ключований за deviceId + role).
  • auth.bootstrapToken надсилається лише тоді, коли жоден із наведених вище варіантів не визначив auth.token. Спільний токен або будь-який визначений токен пристрою пригнічує його.
  • Автоматичне підвищення збереженого токена пристрою під час одноразової повторної спроби AUTH_TOKEN_MISMATCH дозволене лише для довірених endpoints — loopback або wss:// із закріпленим tlsFingerprint. Публічний wss:// без pinning не підходить.
• Вбудований bootstrap через код налаштування повертає основний токен вузла hello-ok.auth.deviceToken плюс обмежений токен оператора в hello-ok.auth.deviceTokens для довіреної передачі на мобільний пристрій. Токен оператора містить operator.talk.secrets для читання нативної конфігурації Talk, але не містить scopes мутації спарювання та operator.admin.
• Поки non-baseline bootstrap через код налаштування очікує схвалення, деталі PAIRING_REQUIRED містять recommendedNextStep: "wait_then_retry", retryable: true і pauseReconnect: false. Клієнти мають продовжувати повторне підключення з тим самим bootstrap-токеном, доки запит не буде схвалено або токен не стане недійсним.
• Зберігайте hello-ok.auth.deviceTokens лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті, як-от wss:// або loopback/local pairing.
• Якщо клієнт надає явний deviceToken або явні scopes, цей запитаний викликачем набір scopes залишається авторитетним; кешовані scopes повторно використовуються лише тоді, коли клієнт повторно використовує збережений токен для пристрою.
• Токени пристроїв можна ротувати/відкликати через device.token.rotate і device.token.revoke (потрібен scope operator.pairing). Ротація або відкликання вузла чи іншої неоператорської ролі також потребує operator.admin.
• device.token.rotate повертає метадані ротації. Він повторює замінний bearer-токен лише для викликів із того самого пристрою, які вже автентифіковані цим токеном пристрою, щоб token-only клієнти могли зберегти заміну перед повторним підключенням. Ротації зі спільним/адміністративним доступом не повторюють bearer-токен.
• Видача, ротація та відкликання токенів залишаються обмеженими затвердженим набором ролей, записаним у записі спарювання цього пристрою; мутація токена не може розширити або націлитися на роль пристрою, яку схвалення спарювання ніколи не надавало.
• Для token-сесій спарених пристроїв керування пристроями є self-scoped, якщо викликач також не має operator.admin: викликачі без прав адміністратора можуть керувати лише токеном оператора для запису власного пристрою. Керування токенами вузла та інших неоператорських ролей доступне лише адміністратору, навіть для власного пристрою викликача.
• device.token.rotate і device.token.revoke також перевіряють цільовий набір scopes токена оператора щодо поточних scopes сесії викликача. Викликачі без прав адміністратора не можуть ротувати або відкликати ширший токен оператора, ніж уже мають.
• Помилки автентифікації містять 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 означає, що токен пристрою розпізнано, але він не покриває запитану роль/scopes. Клієнти не мають показувати це як недійсний токен; запропонуйте оператору повторно спарити або схвалити вужчий/ширший контракт scopes.

Ідентичність пристрою + спарювання

• Вузли мають містити стабільну ідентичність пристрою (device.id), отриману з відбитка keypair.
• Gateways видають токени для кожного пристрою + ролі.
• Схвалення спарювання потрібні для нових ID пристроїв, якщо не ввімкнене локальне автоматичне схвалення.
• Автоматичне схвалення спарювання зосереджене на прямих підключеннях local loopback.
• OpenClaw також має вузький backend/container-local шлях самопідключення для довірених helper-потоків зі спільним секретом.
• Підключення same-host tailnet або LAN усе одно вважаються віддаленими для спарювання та потребують схвалення.
• WS-клієнти зазвичай містять ідентичність device під час connect (оператор + вузол). Єдині винятки для оператора без пристрою — явні довірені шляхи:
  • gateway.controlUi.allowInsecureAuth=true для сумісності з небезпечним HTTP лише на localhost.
  • успішна автентифікація оператора Control UI через gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, серйозне зниження безпеки).
  • direct-loopback backend RPCs gateway-client на зарезервованому внутрішньому helper-шляху.
• Пропуск ідентичності пристрою має наслідки для scopes. Коли підключення оператора без пристрою дозволене через явний довірений шлях, OpenClaw усе одно очищає самостійно оголошені scopes до порожнього набору, якщо цей шлях не має названого винятку збереження scopes. Методи, обмежені scopes, тоді завершуються помилкою missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true є шляхом збереження scopes break-glass для Control UI. Він не надає scopes довільним користувацьким backend або CLI-подібним WebSocket-клієнтам.
• Зарезервований direct-loopback backend helper-шлях gateway-client зберігає scopes лише для внутрішніх локальних control-plane RPCs; користувацькі backend IDs не отримують цього винятку.
• Усі підключення мають підписувати наданий сервером nonce connect.challenge.

Діагностика міграції автентифікації пристрою

Для legacy клієнтів, які досі використовують поведінку підпису до challenge, connect тепер повертає коди деталей DEVICE_AUTH_* у error.details.code зі стабільним error.details.reason.

Поширені помилки міграції:

Ціль міграції:

• Завжди чекайте на connect.challenge.
• Підписуйте v2 payload, який містить серверний nonce.
• Надсилайте той самий nonce у connect.params.device.nonce.
• Рекомендований payload підпису — v3, який прив’язує platform і deviceFamily на додаток до полів device/client/role/scopes/token/nonce.
• Legacy підписи v2 залишаються прийнятими для сумісності, але pinning метаданих спареного пристрою все одно керує політикою команд під час повторного підключення.

TLS + pinning

• TLS підтримується для WS-підключень.
• Клієнти можуть необов’язково закріпити відбиток сертифіката Gateway (див. конфігурацію gateway.tls плюс gateway.remote.tlsFingerprint або CLI --tls-fingerprint).

Scope

Цей протокол відкриває повний API gateway (статус, канали, моделі, чат, агент, сесії, вузли, схвалення тощо). Точну поверхню визначають схеми TypeBox у packages/gateway-protocol/src/schema.ts.

Пов’язане

• Протокол bridge
• Runbook Gateway