Протокол Gateway

Протокол Gateway WS — это единая плоскость управления + транспорт узлов для OpenClaw. Все клиенты (CLI, веб-UI, приложение macOS, узлы iOS/Android, безголовые узлы) подключаются через WebSocket и объявляют свою роль + область действия во время рукопожатия.

Транспорт

• WebSocket, текстовые фреймы с JSON-полезной нагрузкой.
• Первый фрейм должен быть запросом connect.
• Фреймы до подключения ограничены 64 КиБ. После успешного рукопожатия клиентам следует соблюдать ограничения hello-ok.policy.maxPayload и hello-ok.policy.maxBufferedBytes. Когда диагностика включена, слишком большие входящие фреймы и медленные исходящие буферы порождают события payload.large до того, как gateway закроет или отбросит затронутый фрейм. Эти события сохраняют размеры, лимиты, поверхности и безопасные коды причин. Они не сохраняют тело сообщения, содержимое вложений, необработанное тело фрейма, токены, cookie или секретные значения.

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

server, features, snapshot и policy обязательны по схеме (packages/gateway-protocol/src/schema/frames.ts). auth также обязателен и сообщает согласованные роль/области действия. pluginSurfaceUrls необязателен и сопоставляет имена поверхностей Plugin, например canvas, с URL размещенных поверхностей в рамках области действия.

URL поверхностей Plugin с областью действия могут истекать. Узлы могут вызвать node.pluginSurface.refresh с { "surface": "canvas" }, чтобы получить свежую запись в pluginSurfaceUrls. Экспериментальный рефакторинг Plugin Canvas не поддерживает устаревший путь совместимости canvasHostUrl, canvasCapability или node.canvas.capability.refresh; текущие нативные клиенты и gateways должны использовать поверхности Plugin.

Когда токен устройства не выдан, hello-ok.auth сообщает согласованные разрешения без полей токена:

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

Доверенные backend-клиенты в том же процессе (client.id: "gateway-client", client.mode: "backend") могут не указывать device при прямых loopback-подключениях, когда они аутентифицируются с помощью общего токена/пароля gateway. Этот путь зарезервирован для внутренних RPC плоскости управления и не дает устаревшим базовым привязкам CLI/устройства блокировать локальную backend-работу, например обновления сеансов субагентов. Удаленные клиенты, клиенты из браузерного origin, клиенты узлов и явные клиенты с токеном устройства/идентичностью устройства по-прежнему используют обычные проверки сопряжения и повышения области действия.

Когда токен устройства выдан, hello-ok также включает:

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

Встроенная инициализация через QR/код настройки — это новый путь передачи на мобильное устройство. Успешное базовое подключение по коду настройки возвращает основной токен узла и один ограниченный токен оператора:

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

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

Пример узла

{  "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).

RPC-методы gateway, зарегистрированные Plugin, могут запрашивать собственную область действия оператора, но зарезервированные префиксы администрирования ядра (config.*, exec.approvals.*, wizard.*, update.*) всегда разрешаются в operator.admin.

Область действия метода — только первый барьер. Некоторые slash-команды, доступные через chat.send, применяют поверх него более строгие проверки на уровне команды. Например, постоянные записи /config set и /config unset требуют operator.admin.

node.pair.approve также имеет дополнительную проверку области действия во время одобрения поверх базовой области действия метода:

• запросы без команд: operator.pairing
• запросы с node-командами не exec-типа: operator.pairing + operator.write
• запросы, включающие system.run, system.run.prepare или system.which: operator.pairing + operator.admin

Возможности/команды/разрешения (узел)

Узлы объявляют заявки на возможности во время подключения:

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

Gateway рассматривает их как заявки и применяет серверные 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 — закрытое перечисление: background, silent_push, bg_app_refresh, significant_location, manual или connect. Неизвестные строки trigger нормализуются gateway до background перед сохранением. Событие устойчиво только для аутентифицированных сеансов устройств узлов; сеансы без устройства или без сопряжения возвращают handled: false.

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

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

Более старые gateways все еще могут возвращать { "ok": true } для node.event; клиентам следует считать это подтвержденным RPC, а не устойчивым сохранением присутствия.

Определение областей действия широковещательных событий

Широковещательные события WebSocket, отправляемые сервером, ограничиваются областями действия, чтобы сеансы с областью сопряжения или только для узла не получали пассивно содержимое сеанса.

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

Каждое клиентское подключение хранит собственный порядковый номер для клиента, поэтому широковещательные события сохраняют монотонный порядок на этом сокете, даже когда разные клиенты видят разные отфильтрованные по областям действия подмножества потока событий.

Общие семейства RPC-методов

Публичная поверхность WS шире, чем приведенные выше примеры рукопожатия/аутентификации. Это не сгенерированный дамп — hello-ok.features.methods является консервативным списком обнаружения, построенным из src/gateway/server-methods-list.ts плюс загруженных экспортов методов Plugin/каналов. Рассматривайте его как обнаружение возможностей, а не как полное перечисление 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.
• node.invoke.request: широковещательный запрос вызова Node.
• 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.bins, чтобы получить текущий список исполняемых файлов Skills для проверок автоматического разрешения.

RPC реестра задач

Клиенты операторов могут просматривать и отменять записи фоновых задач Gateway через RPC реестра задач. Эти методы возвращают очищенные сводки задач, а не сырое состояние среды выполнения.

• 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 }.
  • Отсутствующие идентификаторы задач возвращают форму ошибки Gateway not-found.
• tasks.cancel требует operator.write.
  • Параметры: { "taskId": string, "reason"?: string }.
  • Результат: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found сообщает, была ли в реестре совпадающая задача. cancelled сообщает, приняла ли среда выполнения отмену или записала ее.

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 выводит доверенный контекст времени выполнения из сессии на стороне сервера, вместо того чтобы принимать предоставленный вызывающим кодом контекст аутентификации или доставки.
  • Ответ представляет собой серверную проекцию активного инвентаря в области сессии, включая core, Plugin, канал и уже обнаруженные инструменты 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 в полезной нагрузке, а не обходят конвейер политики инструментов 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 }) добавляет байты по точному декодированному смещению.
  • 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/*. Без списка разрешений ответ использует явные записи models.providers.*.models, откатываясь к полному каталогу только тогда, когда настроенных строк моделей нет.
• "all": полный каталог Gateway, с обходом agents.defaults.models. Используйте это для диагностики и UI обнаружения, а не для обычных picker моделей.

Подтверждения 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/сессии.
• Если вызывающий код изменяет command, rawCommand, cwd, agentId или sessionKey между подготовкой и итоговым подтвержденным перенаправлением system.run, Gateway отклоняет запуск вместо доверия измененной полезной нагрузке.

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

• Запросы 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 использует эти значения по умолчанию. Значения стабильны в рамках протокола v4 и являются ожидаемой базовой линией для сторонних клиентов.

Сервер объявляет эффективные policy.tickIntervalMs, policy.maxPayload и policy.maxBufferedBytes в hello-ok; клиенты должны соблюдать эти значения, а не значения по умолчанию до handshake.

Аутентификация

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

Идентичность устройства + сопряжение

• Node должны включать стабильную идентичность устройства (device.id), полученную из отпечатка пары ключей.
• Gateway выдают токены для каждой пары устройство + роль.
• Для новых идентификаторов устройств требуются утверждения сопряжения, если не включено локальное автоутверждение.
• Автоутверждение сопряжения сосредоточено на прямых подключениях через local loopback.
• OpenClaw также имеет узкий путь самоподключения, локальный для backend/контейнера, для доверенных вспомогательных потоков с общим секретом.
• Подключения в tailnet или LAN с того же хоста все равно считаются удаленными для сопряжения и требуют утверждения.
• Клиенты WS обычно включают идентичность device во время connect (оператор + Node). Единственные исключения оператора без устройства — явные доверенные пути:
  • gateway.controlUi.allowInsecureAuth=true для совместимости небезопасного HTTP только на localhost.
  • успешная аутентификация оператора Control UI через gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (аварийный режим, серьезное снижение безопасности).
  • прямые loopback backend-RPC gateway-client на зарезервированном внутреннем вспомогательном пути.
• Пропуск идентичности устройства имеет последствия для областей доступа. Когда подключение оператора без устройства разрешено через явный доверенный путь, OpenClaw все равно очищает самостоятельно объявленные области доступа до пустого набора, если у этого пути нет именованного исключения для сохранения областей доступа. Методы, ограниченные областями доступа, затем завершаются ошибкой missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true — это аварийный путь Control UI с сохранением областей доступа. Он не выдает области доступа произвольным пользовательским backend- или CLI-подобным WebSocket-клиентам.
• Зарезервированный прямой loopback вспомогательный backend-путь gateway-client сохраняет области доступа только для внутренних локальных RPC плоскости управления; пользовательские идентификаторы backend не получают это исключение.
• Все соединения должны подписывать предоставленный сервером nonce connect.challenge.

Диагностика миграции аутентификации устройства

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

Типичные ошибки миграции:

Цель миграции:

• Всегда ждать connect.challenge.
• Подписывать полезную нагрузку v2, которая включает nonce сервера.
• Отправлять тот же nonce в connect.params.device.nonce.
• Предпочтительная полезная нагрузка подписи — v3, которая связывает platform и deviceFamily в дополнение к полям device/client/role/scopes/token/nonce.
• Устаревшие подписи v2 по-прежнему принимаются для совместимости, но закрепление метаданных сопряженного устройства все равно управляет политикой команд при переподключении.

TLS + закрепление

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

Область доступа

Этот протокол открывает полный API Gateway (статус, каналы, модели, чат, агент, сеансы, узлы, утверждения и т. д.). Точная поверхность определяется схемами TypeBox в packages/gateway-protocol/src/schema.ts.

Связанное

• Протокол моста
• Runbook Gateway