Протокол Gateway

Documentation Index

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

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

​

Транспорт

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

​

Handshake (connect)

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

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 4,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

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

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

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

​

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

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 4,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

​

Фреймінг

• Запит: {type:"req", id, method, params}
• Відповідь: {type:"res", id, ok, payload|error}
• Подія: {type:"event", event, payload, seq?, stateVersion?}

​

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

​

Ролі

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

​

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

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

• запити без команд: operator.pairing
• запити з non-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 команд для invoke.
• permissions: деталізовані перемикачі (наприклад, screen.record, camera.capture).

​

Присутність

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

​

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

{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}

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

​

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

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

​

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

​

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

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

​

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

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

​

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

​

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

• Оператори можуть викликати commands.list (operator.read), щоб отримати runtime інвентар команд для агента.
  • agentId необов’язковий; опустіть його, щоб читати типовий робочий простір агента.
  • scope керує тим, на яку поверхню націлено основний name:
    • text повертає основний текстовий токен команди без початкового /
    • native і типовий шлях both повертають нативні імена з урахуванням провайдера, коли вони доступні
  • textAliases містить точні slash-псевдоніми, як-от /model і /m.
  • nativeName містить нативну назву команди з урахуванням провайдера, коли така існує.
  • provider необов’язковий і впливає лише на нативне іменування та доступність нативних команд plugin.
  • includeArgs=false опускає серіалізовані метадані аргументів із відповіді.
• Оператори можуть викликати tools.catalog (operator.read), щоб отримати runtime-каталог інструментів для агента. Відповідь містить згруповані інструменти та метадані походження:
  • source: core або plugin
  • pluginId: власник plugin, коли source="plugin"
  • optional: чи інструмент plugin є необов’язковим
• Оператори можуть викликати tools.effective (operator.read), щоб отримати ефективний для runtime інвентар інструментів для сеансу.
  • sessionKey обов’язковий.
  • Gateway виводить довірений runtime-контекст із сеансу на серверному боці замість приймання наданого викликачем контексту автентифікації чи доставки.
  • Відповідь обмежена сеансом і відображає те, що активна розмова може використовувати прямо зараз, включно з core, plugin та інструментами каналів.
• Оператори можуть викликати tools.invoke (operator.write), щоб викликати один доступний інструмент через той самий шлях політики gateway, що й /tools/invoke.
  • name обов’язковий. args, sessionKey, agentId, confirm і idempotencyKey необов’язкові.
  • Якщо присутні і sessionKey, і agentId, розв’язаний агент сеансу має збігатися з agentId.
  • Відповідь є конвертом для SDK з полями ok, toolName, необов’язковим output і типізованими полями error. Відмови через схвалення або політику повертають ok:false у payload, а не обходять pipeline політики інструментів gateway.
• Оператори можуть викликати skills.status (operator.read), щоб отримати видимий інвентар skill для агента.
  • agentId необов’язковий; опустіть його, щоб читати типовий робочий простір агента.
  • Відповідь містить відповідність вимогам, відсутні вимоги, перевірки конфігурації та очищені параметри встановлення без розкриття сирих значень секретів.
• Оператори можуть викликати skills.search і skills.detail (operator.read) для метаданих виявлення ClawHub.
• Оператори можуть викликати skills.upload.begin, skills.upload.chunk і skills.upload.commit (operator.admin), щоб підготувати приватний архів skill перед його встановленням. Це окремий адміністративний шлях завантаження для довірених клієнтів, а не звичайний потік встановлення skill з 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 лише завершує завантаження; він не встановлює skill.
  • Завантажені архіви skill є zip-архівами, що містять кореневий SKILL.md. Внутрішня назва каталогу архіву ніколи не вибирає ціль встановлення.
• Оператори можуть викликати skills.install (operator.admin) у трьох режимах:
  • Режим ClawHub: { source: "clawhub", slug, version?, force? } встановлює папку skill у каталог skills/ типового робочого простору агента.
  • Режим завантаження: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } встановлює зафіксоване завантаження в каталог skills/<slug> типового робочого простору агента. Slug і значення force мають збігатися з початковим запитом skills.upload.begin. Цей режим відхиляється, якщо skills.install.allowUploadedArchives не ввімкнено. Налаштування не впливає на встановлення з ClawHub.
  • Режим інсталятора Gateway: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } запускає оголошену дію metadata.openclaw.install на хості gateway.
• Оператори можуть викликати skills.update (operator.admin) у двох режимах:
  • Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у типовому робочому просторі агента.
  • Режим конфігурації виправляє значення skills.entries.<skillKey>, як-от enabled, apiKey і env.

​

Подання models.list

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

​

Схвалення виконання

• Коли запит виконання потребує схвалення, 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 як авторитетний контекст команди/cwd/сеансу.
• Якщо викликач змінює 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 розташовано в src/gateway/protocol/version.ts.
• Клієнти надсилають minProtocol + maxProtocol; сервер відхиляє діапазони, які не включають його поточний протокол. Нативні клієнти використовують нижню межу v3, щоб адитивні клієнти v4 усе ще могли досягати gateway v3.
• Схеми + моделі генеруються з визначень TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

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

​

Автентифікація

• Автентифікація Gateway зі спільним секретом використовує connect.params.auth.token або connect.params.auth.password, залежно від налаштованого режиму автентифікації.
• Режими з ідентичністю, як-от Tailscale Serve (gateway.auth.allowTailscale: true) або non-loopback gateway.auth.mode: "trusted-proxy", задовольняють перевірку автентифікації підключення через заголовки запиту замість connect.params.auth.*.
• Private-ingress gateway.auth.mode: "none" повністю пропускає автентифікацію підключення зі спільним секретом; не виставляйте цей режим у публічний/ненадійний ingress.
• Після pairing Gateway видає device token, обмежений роллю підключення
  • scopes. Його повертають у hello-ok.auth.deviceToken, і клієнт має зберігати його для майбутніх підключень.
• Клієнти мають зберігати основний hello-ok.auth.deviceToken після будь-якого успішного підключення.
• Повторне підключення з цим збереженим device token також має повторно використовувати збережений схвалений набір scopes для цього токена. Це зберігає доступ для read/probe/status, який уже було надано, і запобігає непомітному звуженню повторних підключень до неявного scope лише для адміністратора.
• Формування автентифікації підключення на боці клієнта (selectConnectAuth у src/gateway/client.ts):
  • auth.password є ортогональним і завжди пересилається, коли його задано.
  • auth.token заповнюється в порядку пріоритету: спочатку явний спільний токен, потім явний deviceToken, потім збережений токен окремого пристрою (за ключем deviceId + role).
  • auth.bootstrapToken надсилається лише тоді, коли жоден із варіантів вище не визначив auth.token. Спільний токен або будь-який визначений device token пригнічує його.
  • Автоматичне підвищення збереженого device token під час одноразової повторної спроби AUTH_TOKEN_MISMATCH дозволене лише для довірених endpoints — loopback або wss:// із закріпленим tlsFingerprint. Публічний wss:// без pinning не підходить.
• Додаткові записи hello-ok.auth.deviceTokens є токенами передавання bootstrap. Зберігайте їх лише тоді, коли підключення використовувало bootstrap auth через довірений транспорт, як-от wss:// або loopback/local pairing.
• Якщо клієнт надає явний deviceToken або явні scopes, цей запитаний викликачем набір scopes залишається авторитетним; кешовані scopes повторно використовуються лише тоді, коли клієнт повторно використовує збережений токен окремого пристрою.
• Device tokens можна ротувати/відкликати через device.token.rotate і device.token.revoke (потрібен scope operator.pairing).
• device.token.rotate повертає метадані ротації. Він віддзеркалює замінний bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим device token, тож клієнти лише з токеном можуть зберегти свою заміну перед повторним підключенням. Shared/admin ротації не віддзеркалюють bearer token.
• Видача, ротація та відкликання токенів залишаються обмеженими схваленим набором ролей, записаним у pairing-записі цього пристрою; зміна токена не може розширити або націлити роль пристрою, яку pairing-approval ніколи не надавав.
• Для сесій paired-device token керування пристроями є self-scoped, якщо викликач також не має operator.admin: неадміністративні викликачі можуть видаляти/відкликати/ротувати лише запис власного пристрою.
• device.token.rotate і device.token.revoke також перевіряють цільовий набір scopes operator token щодо поточних scopes сесії викликача. Неадміністративні викликачі не можуть ротувати або відкликати ширший operator token, ніж уже мають.
• Помилки автентифікації містять error.details.code плюс підказки для відновлення:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Поведінка клієнта для AUTH_TOKEN_MISMATCH:
  • Довірені клієнти можуть спробувати одну обмежену повторну спробу з кешованим токеном окремого пристрою.
  • Якщо ця повторна спроба не вдається, клієнти мають зупинити автоматичні цикли повторного підключення та показати оператору вказівки щодо дії.
• AUTH_SCOPE_MISMATCH означає, що device token було розпізнано, але він не покриває запитану роль/scopes. Клієнти не мають подавати це як поганий токен; запропонуйте оператору виконати re-pair або схвалити вужчий/ширший контракт scopes.

​

Ідентичність пристрою + pairing

• Nodes мають включати стабільну ідентичність пристрою (device.id), отриману з fingerprint пари ключів.
• Gateways видають токени для кожного пристрою + ролі.
• Pairing approvals потрібні для нових device IDs, якщо не ввімкнено локальне auto-approval.
• Pairing auto-approval зосереджене на прямих підключеннях local loopback.
• OpenClaw також має вузький backend/container-local шлях самопідключення для довірених helper flows зі спільним секретом.
• Підключення same-host tailnet або LAN усе ще вважаються віддаленими для pairing і потребують схвалення.
• WS-клієнти зазвичай включають ідентичність device під час connect (operator + node). Єдині винятки operator без пристрою — явні trust paths:
  • gateway.controlUi.allowInsecureAuth=true для сумісності небезпечного HTTP лише на localhost.
  • успішна автентифікація operator Control UI для gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, серйозне зниження безпеки).
  • backend RPCs прямого loopback gateway-client, автентифіковані спільним gateway token/password.
• Усі підключення мають підписувати наданий сервером nonce connect.challenge.

​

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

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

​

TLS + pinning

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

​

Область дії

​

Пов’язане

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