Протокол Gateway

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

Транспорт и кадрирование

• WebSocket, текстовые кадры, полезная нагрузка JSON.
• Первый кадр должен быть запросом connect.
• Размер кадров до подключения ограничен 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). После рукопожатия соблюдайте hello-ok.policy.maxPayload и hello-ok.policy.maxBufferedBytes. Если диагностика включена, слишком большие входящие кадры и медленные исходящие буферы создают события payload.large, прежде чем Gateway закроет соединение или отбросит кадр. Эти события содержат surface, размеры в байтах, ограничения и безопасный код причины, но никогда не содержат тела сообщений, содержимое вложений, необработанные байты кадров, токены, файлы cookie или секреты.

Формы кадров:

• Запрос: {type:"req", id, method, params}
• Ответ: {type:"res", id, ok, payload|error}
• Событие: {type:"event", event, payload, seq?, stateVersion?}

Для методов с побочными эффектами требуются ключи идемпотентности (см. схему).

Рукопожатие

Gateway отправляет запрос-проверку перед подключением:

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

Клиент отвечает с помощью connect:

{  "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 отвечает с помощью hello-ok:

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

server, features, snapshot, policy и auth обязательны для HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth сообщает согласованные роль и области действия, даже если токен устройства не выдан (форма приведена выше). pluginSurfaceUrls является необязательным и сопоставляет имена поверхностей плагинов (например, canvas) с размещёнными URL-адресами с ограниченной областью действия; срок его действия может истечь, поэтому узлы вызывают node.pluginSurface.refresh с { "surface": "canvas" }, чтобы получить новую запись. Устаревший путь canvasHostUrl / canvasCapability / node.canvas.capability.refresh не поддерживается; используйте поверхности плагинов. Необязательное поле appliedConfigHash снимка — это редакция разрешённой исходной конфигурации, принятая активной средой выполнения Gateway. Клиенты могут сравнить её с config.get.configRevisionHash, чтобы определить, требуется ли для более новой сохранённой конфигурации перезапуск. config.get.hash остаётся необработанной редакцией корневого файла, используемой средствами защиты от конфликтов при записи конфигурации.

Пока Gateway завершает запуск вспомогательных процессов, connect может вернуть допускающую повторную попытку ошибку UNAVAILABLE с details.reason: "startup-sidecars" и retryAfterMs. Выполните повторную попытку в пределах бюджета подключения, не считая её неустранимой ошибкой рукопожатия.

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

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

Эта передача управления оператору намеренно ограничена: её достаточно для запуска мобильного цикла оператора и нативной настройки, включая operator.talk.secrets для чтения конфигурации Talk, но без областей действия для изменения сопряжения и без operator.admin. Для более широкого доступа к сопряжению или администрированию требуется отдельный одобренный процесс сопряжения или выдачи токена. Сохраняйте hello-ok.auth.deviceTokens только тогда, когда начальная аутентификация выполнялась через доверенный транспорт (wss:// или сопряжение через loopback/локальное соединение).

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

Роль рабочего процесса и закрытый протокол

Облачные рабочие процессы используют выделенную loopback-точку входа через принадлежащий Gateway SSH-туннель с закреплённым ключом хоста. Она принимает только идентификаторы рабочих процессов и никогда не передаёт общую аутентификацию, события узлов, RPC операторов или методы плагинов. Строгая проверка connect проверяет хранимые в виде хеша краткосрочные учётные данные, привязанные к среде, хешу пакета, эпохе владельца, версии набора RPC, сроку действия и одному допускающему значение null сеансу; она отдельно проверяет текущую версию и набор функций. При успехе возвращается минимальный worker-hello-ok; согласование функций не зависит от общей версии протокола. Размер кадров остаётся меньше 64 KiB, кроме согласованного кадра worker.inference.start, размер которого может достигать 25 MiB. Закрытый список разрешённых значений содержит worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start и worker.inference.cancel.

Фиксация транскриптов использует ограждение по эпохе владельца, принадлежащую Gateway привязку сеанса, операцию сравнения с базовым конечным элементом и замены, а также устойчивое воспроизведение последовательности; Gateway создаёт идентификаторы записей транскрипта и их родительских элементов через обычный модуль записи сеансов. Владение и срок действия повторно проверяются при каждом RPC.

Возможности клиента

Клиенты оператора могут объявлять необязательные возможности в connect.params.caps:

• tool-events: принимает структурированные события жизненного цикла инструментов.
• inline-widgets: может отображать результаты инструментов размещённых встроенных виджетов.

Возможности клиента описывают подключённый клиент, а не авторизацию. Инструменты агента могут объявлять необходимые возможности; Gateway исключает такие инструменты, если в caps исходного клиента отсутствует хотя бы одно требование. Запуски, инициированные каналом, не имеют возможностей клиента Gateway, поэтому инструменты с проверкой возможностей недоступны, даже если политика инструментов явно разрешает их.

Пример подключения узла

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

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

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

Gateway рассматривает их как заявления и применяет серверные списки разрешений.

Роли и области действия

Полное описание модели областей действия оператора, проверок при одобрении и семантики общих секретов см. в разделе Области действия оператора.

Роли:

• operator: клиент плоскости управления (CLI/UI/автоматизация).
• node: узел предоставления возможностей (camera/screen/canvas/system.run).
• worker: узел облачного выполнения в выделенном закрытом протоколе рабочих процессов.

Области действия оператора (src/gateway/operator-scopes.ts), полный закрытый набор:

• 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 или отредактированной строкой.

Зарегистрированные плагинами методы RPC Gateway могут запрашивать собственную область действия оператора, но эти зарезервированные префиксы ядра всегда разрешаются в operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

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

Для node.pair.approve поверх базовой области действия метода (operator.pairing) выполняется дополнительная проверка области действия во время одобрения на основе объявленного в ожидающем запросе commands (src/infra/node-pairing-authz.ts):

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

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

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

Gateway рассматривает их как заявленные возможности и применяет серверные списки разрешений. Подключённые узлы могут публиковать необязательные, видимые агенту дескрипторы плагинов или инструментов MCP с помощью node.pluginTools.update после успешного подключения или повторного подключения. Хосты узлов без графического интерфейса перезапускаются для применения декларативных изменений инвентаря MCP. Этот метод обновления является единственным способом публикации; дескрипторы инструментов плагинов не принимаются в параметрах connect. Каждый дескриптор должен использовать безопасное для провайдера name инструмента и указывать command из текущего списка разрешённых команд узла. Gateway доверяет метаданным дескриптора от сопряжённого узла, отфильтровывает дескрипторы за пределами утверждённого набора команд, удаляет их при отключении узла и отклоняет попытки оператора изменить каталог другого узла. Задайте gateway.nodes.pluginTools.enabled: false, чтобы игнорировать опубликованные узлами дескрипторы.

Подключённые хосты узлов публикуют полный замещающий каталог навыков с помощью node.skills.update. Этот метод роли узла является единственным способом публикации навыков узлом; навыки не принимаются в параметрах connect. Каждый дескриптор содержит безопасное имя, описание и содержимое SKILL.md ограниченного размера. Gateway разбирает это содержимое обычным загрузчиком навыков, включает его в снимки навыков агента, пока узел подключён, и удаляет при отключении. Задайте gateway.nodes.skills.enabled: false, чтобы игнорировать опубликованные узлами навыки.

Присутствие

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

Нативные узлы macOS также могут отправлять аутентифицированные события node.presence.activity с ограниченным временем бездействия ввода. Gateway самостоятельно вычисляет метки активности по своим часам, предоставляет самый недавно активный подключённый Mac через node.list и node.describe и рассылает обновления node.presence клиентам с областью доступа на чтение. Поведение выбора, конфиденциальности, контекста модели и маршрутизации уведомлений описано в разделе Присутствие активного компьютера.

Фоновое событие активности узла

Узлы вызывают 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. Неизвестные значения нормализуются в background (src/shared/node-presence.ts). Событие сохраняется только для аутентифицированных сеансов устройств узлов; сеансы без устройства или без сопряжения возвращают handled: false.

При успешном выполнении Gateway возвращает структурированный результат:

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

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

Ограничение области рассылки событий

Рассылаемые сервером события ограничиваются областью доступа, чтобы сеансы, предназначенные только для сопряжения или узлов, пассивно не получали содержимое сеансов (src/gateway/server-broadcast.ts):

• Кадры чата, агента и результатов инструментов (потоковые события agent, события результатов инструментов) требуют как минимум operator.read. Сеансы без этой области полностью пропускают такие кадры.
• Определённые плагинами рассылки plugin.* по умолчанию ограничиваются operator.write или operator.admin; явно заданные записи, такие как plugin.approval.requested / plugin.approval.resolved, вместо этого используют operator.approvals.
• События состояния и транспорта (heartbeat, presence, tick, жизненный цикл подключения и отключения) остаются без ограничений, чтобы состояние транспорта было доступно каждому аутентифицированному сеансу.
• Неизвестные семейства рассылаемых событий по умолчанию ограничиваются областью доступа (закрыто при ошибке), если зарегистрированный обработчик явно не ослабляет эти ограничения.

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

Семейства методов RPC

hello-ok.features.methods — это консервативный список обнаружения, составленный из src/gateway/server-methods-list.ts и экспортируемых методов загруженных плагинов и каналов; это не сгенерированный перечень всех методов, и некоторые методы (например, push.test, web.login.start, web.login.wait, sessions.usage) намеренно исключены из обнаружения, хотя они существуют и доступны для вызова. Рассматривайте его как средство обнаружения возможностей, а не как полный перечень src/gateway/server-methods/*.ts.

Общие семейства событий

• chat: обновления чата пользовательского интерфейса, такие как chat.inject, и другие события чата, относящиеся только к расшифровке. В протоколе v4 полезные данные дельт содержат deltaText; message остаётся накопительным снимком ассистента. Замены, не являющиеся префиксами, устанавливают replace=true и используют deltaText в качестве текста замены.
• session.message, session.operation, session.tool: обновления расшифровки, выполняемой операции сеанса и потока событий для сеанса с оформленной подпиской.
• session.approval: очищенные достоверные данные об ожидающих и терминальных подтверждениях для подписчика точного сеанса, который явно согласился их получать. Дочерние подтверждения используют сохранённую аудиторию предка; события никогда не изменяют расшифровки и не пробуждают агентов.
• sessions.changed: изменился индекс или метаданные сеанса.
• presence: обновления снимка присутствия системы.
• tick: периодическое событие поддержания соединения или проверки работоспособности.
• 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: жизненный цикл подтверждения выполнения.
• plugin.approval.requested / plugin.approval.resolved: жизненный цикл подтверждения плагина.

Вспомогательные методы Node

Node могут вызывать skills.bins, чтобы получить текущий список исполняемых файлов Skills для проверок автоматического разрешения.

RPC журнала аудита

audit.activity.list предоставляет клиентам оператора стабильное представление с сортировкой от новых записей к старым для метаданных жизненного цикла запусков агента, действий инструментов и сообщений с явным согласием. Для него требуется operator.read. Запросы исключают записи старше 30 дней, а общий журнал SQLite ограничен 100,000 записями. Просроченные строки удаляются при запуске Gateway, во время ежечасного обслуживания и при последующих операциях записи. Модель данных и семантику конфиденциальности см. в разделе История аудита.

• Параметры: необязательный точный agentId, sessionKey или runId; необязательный kind ("agent_run", "tool_action" или "message"); необязательный status ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" или "unknown"); необязательный direction сообщения ("inbound" или "outbound") и точный channel; необязательные включительные границы after / before в миллисекундах Unix; необязательный limit от 1 до 500; и необязательная строка cursor с предыдущей страницы.
• Результат: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

Именованное объединение результатов V1 содержит отдельные схемы запуска агента, действия инструмента, входящего сообщения и исходящего сообщения. Дискриминатор eventType соответственно имеет значение agent_run, tool_action, inbound_message или outbound_message; kind и direction сообщения остаются доступными для фильтрации и отображения. Каждое событие содержит целочисленный schemaVersion: 1. Ссылки на идентификаторы сообщений используют точный формат hmac-sha256:v1:<32 hex key id>:<64 hex digest>; идентификатор субъекта-отправителя канала использует тот же формат.

Все варианты требуют eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor и redaction. Поля вариантов:

Закрытые перечисления сообщений:

• conversationKind: direct, group, channel или unknown.
• Входящий outcome: completed, skipped или failed; необязательный reasonCode: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty или acp_dispatch_aborted.
• Исходящий outcome: sent, suppressed, failed или unknown; необязательный reasonCode: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook или no_visible_payload. Адаптер, не возвращающий идентификатор платформы, имеет значение unknown, поскольку внешний побочный эффект нельзя опровергнуть.
• deliveryKind: text, media или other; failureStage: platform_send, queue или unknown.

Терминальные поля взаимосвязаны, а не являются независимо необязательными:

Каждое событие активности включает стабильный идентификатор события, монотонную последовательность реестра, последовательность исходного события, временную метку, субъекта, действие, статус, целочисленное schemaVersion: 1 и redaction: "metadata_only". Записи запусков и инструментов требуют сведений о происхождении агента и запуска и могут включать сведения о происхождении сессии. Записи сообщений могут включать идентификаторы агента и запуска, но намеренно никогда не включают sessionKey или sessionId; поэтому фильтр запроса sessionKey применяется только к строкам запусков и инструментов. События инструментов могут включать идентификатор вызова инструмента и имя инструмента.

Записи сообщений используют message.inbound.processed или message.outbound.finished и дополнительно содержат направление, канал, тип беседы, нормализованный результат и необязательные тип доставки, этап сбоя, длительность, число результатов, код причины и псевдонимы учётной записи, беседы, сообщения и цели, созданные с ключом, локальным для установки. Эти псевдонимы помогают сопоставлять данные, но не обеспечивают анонимизацию: база данных состояния содержит их ключ, а экспорты RPC и CLI — нет. Реестр не хранит промпты, содержимое сообщений, аргументы инструментов, результаты инструментов, вывод команд или исходный текст ошибок. Значения sessionKey запусков и инструментов остаются необработанными метаданными сопоставления и могут содержать идентификаторы учётных записей или собеседников платформы; записи сообщений не содержат ключей сессий.

Для входящих строк durationMs измеряет время диспетчеризации в ядре до её завершения, а resultCount подсчитывает окончательно сформированные поставленные в очередь полезные нагрузки инструментов, блоков и ответов. Для исходящих строк durationMs охватывает период владения доставкой до подтверждения, помещения в очередь недоставленных сообщений или сверки (включая время ожидания в очереди), а resultCount подсчитывает идентифицированные физические отправки через платформу. deliveryKind, если присутствует, описывает фактическую полезную нагрузку после хуков и рендеринга; в подавленных строках или строках с неоднозначностью из-за сбоя оно отсутствует.

Текущий охват сообщений включает принятые входящие сообщения, дошедшие до диспетчеризации в ядре, включая результаты обработки дубликатов и терминальные результаты ядра. Для исходящих сообщений записывается одна терминальная строка на каждую исходную логическую полезную нагрузку ответа, достигшую общего надёжного механизма доставки; разделение на части и разветвление в адаптерах агрегируются в resultCount. Поставленные в очередь повторяемые или неоднозначные отправки регистрируются только после подтверждения, помещения в очередь недоставленных сообщений или сверки. Локальные пути плагинов и пути прямой отправки, обходящие эти общие границы, пока не охватываются. Ограниченная очередь воркеров работает по принципу максимальных усилий и при сбое или переполнении может терять записи, поэтому этот интерфейс не является полным архивом для соблюдения нормативных требований без потерь.

Запись включена по умолчанию и управляется параметром audit.enabled. Запись сообщений управляется отдельно параметром audit.messages, значение по умолчанию — "off". Когда запись отключена, audit.activity.list продолжает предоставлять ранее записанные записи до истечения срока их хранения.

Поставляемые схемы запроса и результата audit.list, а также схема AuditEvent остаются без изменений и возвращают только записи запусков агентов и действий инструментов. Новым операторским клиентам следует вызывать audit.activity.list, когда Gateway объявляет о его поддержке. Старые версии Gateway могут сообщать либо unknown method: audit.activity.list, либо, поскольку в поставленных версиях авторизация выполнялась до поиска метода, missing scope: operator.admin для запроса с областью доступа на чтение. Считайте последнее отсутствием метода только в том случае, если метод не был объявлен. После этого клиент может повторить запрос через audit.list только тогда, когда его фильтрам не требуется поддержка типа сообщения, направления или канала.

Используйте openclaw audit для текстовых запросов и ограниченных экспортов JSON.

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

Операторские клиенты проверяют и отменяют записи фоновых задач Gateway через RPC реестра задач (packages/gateway-protocol/src/schema/tasks.ts). Они возвращают очищенные сводки задач, а не исходное состояние среды выполнения.

• 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 «не найдено».
• 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 содержит точные псевдонимы слеш-команд, такие как /model и /m.
  • nativeName содержит нативное имя команды с учётом провайдера, если оно существует.
  • provider является необязательным и влияет только на нативное именование и доступность нативных команд плагина.
  • includeArgs=false исключает из ответа сериализованные метаданные аргументов.
• tools.catalog (operator.read) получает каталог инструментов среды выполнения для агента. Ответ включает сгруппированные инструменты и метаданные происхождения:
  • source: core или plugin
  • pluginId: плагин-владелец, когда source="plugin"
  • optional: является ли инструмент плагина необязательным
• tools.effective (operator.read) получает фактический перечень инструментов среды выполнения для сессии.
  • sessionKey является обязательным.
  • Gateway получает доверенный контекст среды выполнения из сессии на стороне сервера, а не принимает предоставленный вызывающей стороной контекст аутентификации или доставки.
  • Ответ представляет собой ограниченную сессией, сформированную сервером проекцию активного перечня, включая инструменты ядра, плагинов, каналов и уже обнаруженных серверов 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.
  • Доступные только владельцу обёртки ядра, такие как 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? }) создаёт загрузку, привязанную к этому слагу и значению принудительной установки.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) добавляет байты с точного декодированного смещения.
  • skills.upload.commit({ uploadId, sha256? }) проверяет итоговый размер и SHA-256. Фиксация лишь завершает загрузку; она не устанавливает навык.
  • Загружаемые архивы навыков представляют собой zip-архивы, содержащие корневой каталог SKILL.md. Имя внутреннего каталога архива никогда не определяет цель установки.
• skills.install (operator.admin) имеет три режима:
  • Режим ClawHub: { source: "clawhub", slug, version?, force? } устанавливает папку навыка в каталог skills/ рабочего пространства агента по умолчанию.
  • Режим загрузки: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } устанавливает зафиксированную загрузку в каталог skills/<slug> рабочего пространства агента по умолчанию. Слаг и значение принудительной установки должны соответствовать исходному запросу skills.upload.begin. Запрос отклоняется, если не включён skills.install.allowUploadedArchives; эта настройка не влияет на установки из ClawHub.
  • Режим установщика Gateway: { name, installId, timeoutMs? } выполняет объявленное действие metadata.openclaw.install на хосте Gateway. Старые клиенты всё ещё могут отправлять dangerouslyForceUnsafeInstall; это поле устарело, принимается только для совместимости протокола и игнорируется. Используйте security.installPolicy для решений об установке, принадлежащих оператору.
• skills.update (operator.admin) имеет два режима:
  • Режим ClawHub обновляет один отслеживаемый слаг или все отслеживаемые установки ClawHub в рабочем пространстве агента по умолчанию.
  • Режим конфигурации изменяет значения skills.entries.<skillKey>, такие как enabled, apiKey и env.

Представления models.list

models.list принимает необязательный параметр view (src/agents/model-catalog-visibility.ts):

• Не указано или "default": если настроено agents.defaults.models, ответом будет разрешённый каталог, включая динамически обнаруженные модели для записей provider/*. В противном случае ответом будет полный каталог Gateway.
• "configured": поведение с объёмом данных для средства выбора. Если настроено agents.defaults.models, оно по-прежнему имеет приоритет, включая обнаружение в рамках провайдера для записей provider/*. Без списка разрешённых значений ответ использует явно заданные записи models.providers.<provider>.models, переходя к полному каталогу только при отсутствии строк настроенных моделей.
• "provider-config": сформированный источником перечень models.providers.*.models, не зависящий от списков разрешённых значений средства выбора. Строки содержат общедоступные возможности моделей и доступность с учётом маршрута, но не содержат конечные точки провайдеров, данные аутентификации и конфигурацию запросов среды выполнения.
• "all": полный каталог Gateway в обход agents.defaults.models. Используйте для интерфейсов диагностики и обнаружения, а не для обычных средств выбора модели.

Подтверждения выполнения

• Когда запрос на выполнение требует подтверждения, 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 разрешает резервный переход к выполнению только в сеансе, когда невозможно определить внешний маршрут доставки (например, для внутренних сеансов или сеансов веб-чата, а также неоднозначных многоканальных конфигураций).
• Итоговые результаты agent могут содержать result.deliveryStatus, если была запрошена доставка, с теми же статусами sent, suppressed, partial_failed и failed, которые описаны для openclaw agent --json --deliver.

Управление версиями

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION и MIN_PROBE_PROTOCOL_VERSION находятся в packages/gateway-protocol/src/version.ts.
• Клиенты отправляют minProtocol + maxProtocol. Клиенты оператора и пользовательского интерфейса должны включать текущий протокол в этот диапазон; текущие клиенты и серверы используют протокол v4.
• Аутентифицированные клиенты, имеющие как role: "node", так и client.mode: "node", могут использовать протокол Node версии N-1 (сейчас v3). Облегчённые проверки после перезапуска используют то же окно N-1. Это окно совместимости не изменяет аутентификацию устройств, сопряжение, области доступа, политику команд и подтверждения выполнения. Возможности и команды Node, принадлежащие плагинам, недоступны, пока Node не обновится до текущей версии протокола, поскольку предоставляемые ими поверхности не входят в контракт N-1.
• Схемы и модели создаются из определений TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Константы клиента

Эталонная реализация клиента находится в packages/gateway-client/src/ (OpenClaw оборачивает её тонким фасадом src/gateway/client.ts). Эти значения по умолчанию стабильны в рамках протокола v4 и являются ожидаемой базовой конфигурацией для сторонних клиентов.

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

Эталонный клиент позволяет конечным запросам самостоятельно контролировать настроенный крайний срок, когда он задан для каждого ожидающего запроса. Запрос expectFinal без конечного timeoutMs, любой запрос с timeoutMs: null или сочетание конечных и неограниченных запросов сохраняют активность сторожевого таймера тактов. Если входящие события и ответы отсутствуют дольше порога тайм-аута такта, клиент закрывает сокет с кодом 4000, отклоняет все ожидающие запросы и повторно подключается. После повторного подключения он не отправляет отклонённые запросы заново.

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

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

Идентификатор устройства и сопряжение

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

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

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

Распространённые ошибки миграции:

Целевая схема миграции:

• Всегда дожидайтесь connect.challenge.
• Подписывайте полезную нагрузку v2, включающую одноразовый код сервера.
• Отправляйте тот же одноразовый код в connect.params.device.nonce.
• Предпочтительная полезная нагрузка подписи — v3 (buildDeviceAuthPayloadV3 в packages/gateway-client/src/device-auth.ts), которая наряду с полями устройства, клиента, роли, областей доступа, токена и одноразового кода связывает platform и deviceFamily.
• Устаревшие подписи v2 по-прежнему принимаются для совместимости, но закрепление метаданных сопряжённого устройства продолжает определять политику команд при повторном подключении.

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

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

Область действия

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

Связанные материалы

• Протокол моста
• Руководство по эксплуатации Gateway