Protocolo do Gateway

O protocolo WS do Gateway é o plano de controle único + transporte de nós do OpenClaw. Todos os clientes (CLI, interface web, aplicativo macOS, nós iOS/Android, nós headless) se conectam por WebSocket e declaram seu papel + escopo no momento do handshake.

Transporte

• WebSocket, frames de texto com payloads JSON.
• O primeiro frame deve ser uma solicitação connect.
• Frames pré-conexão são limitados a 64 KiB. Após um handshake bem-sucedido, os clientes devem seguir os limites hello-ok.policy.maxPayload e hello-ok.policy.maxBufferedBytes. Com diagnósticos habilitados, frames de entrada grandes demais e buffers de saída lentos emitem eventos payload.large antes que o gateway feche ou descarte o frame afetado. Esses eventos mantêm tamanhos, limites, superfícies e códigos de motivo seguros. Eles não mantêm o corpo da mensagem, conteúdo de anexos, corpo bruto do frame, tokens, cookies ou valores secretos.

Handshake (connect)

Gateway → Cliente (desafio pré-conexão):

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

Cliente → 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 → Cliente:

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

Enquanto o Gateway ainda está finalizando serviços auxiliares de inicialização, a solicitação connect pode retornar um erro UNAVAILABLE passível de nova tentativa com details.reason definido como "startup-sidecars" e retryAfterMs. Os clientes devem repetir essa resposta dentro do orçamento geral de conexão em vez de apresentá-la como uma falha terminal de handshake.

server, features, snapshot e policy são todos obrigatórios pelo esquema (packages/gateway-protocol/src/schema/frames.ts). auth também é obrigatório e informa o papel/escopos negociados. pluginSurfaceUrls é opcional e mapeia nomes de superfícies de Plugin, como canvas, para URLs hospedadas com escopo.

URLs de superfície de Plugin com escopo podem expirar. Nós podem chamar node.pluginSurface.refresh com { "surface": "canvas" } para receber uma entrada nova em pluginSurfaceUrls. A refatoração experimental do Plugin Canvas não oferece suporte ao caminho de compatibilidade obsoleto canvasHostUrl, canvasCapability ou node.canvas.capability.refresh; clientes nativos e gateways atuais devem usar superfícies de Plugin.

Quando nenhum token de dispositivo é emitido, hello-ok.auth informa as permissões negociadas sem campos de token:

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

Clientes de backend confiáveis no mesmo processo (client.id: "gateway-client", client.mode: "backend") podem omitir device em conexões diretas de loopback quando se autenticam com o token/senha compartilhado do gateway. Esse caminho é reservado para RPCs internos do plano de controle e impede que baselines obsoletas de pareamento CLI/dispositivo bloqueiem trabalho de backend local, como atualizações de sessão de subagente. Clientes remotos, clientes com origem em navegador, clientes de nó e clientes explícitos com token de dispositivo/identidade de dispositivo ainda usam as verificações normais de pareamento e upgrade de escopo.

Quando um token de dispositivo é emitido, hello-ok também inclui:

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

O bootstrap integrado por QR/código de configuração é um caminho novo de transferência móvel. Uma conexão bem-sucedida com código de configuração de baseline retorna um token primário de nó mais um token de operador limitado:

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

A transferência de operador é intencionalmente limitada para que o onboarding por QR possa iniciar o loop de operador móvel e concluir a configuração nativa sem conceder escopos de mutação de pareamento ou operator.admin. Ela inclui operator.talk.secrets para que o cliente nativo possa ler a configuração de Talk de que precisa após o bootstrap. Acesso mais amplo a pareamento e administração exige um fluxo separado aprovado de pareamento ou token de operador. Clientes devem persistir hello-ok.auth.deviceTokens somente quando a conexão usou autenticação de bootstrap em transporte confiável, como wss:// ou pareamento local/local loopback.

Exemplo de Node

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

Enquadramento

• Solicitação: {type:"req", id, method, params}
• Resposta: {type:"res", id, ok, payload|error}
• Evento: {type:"event", event, payload, seq?, stateVersion?}

Métodos com efeitos colaterais exigem chaves de idempotência (consulte o esquema).

Papéis + escopos

Para o modelo completo de escopos de operador, verificações no momento da aprovação e semântica de segredo compartilhado, consulte Escopos de operador.

Papéis

• operator = cliente do plano de controle (CLI/interface/automação).
• node = host de capacidade (câmera/tela/canvas/system.run).

Escopos (operador)

Escopos comuns:

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

talk.config com includeSecrets: true exige operator.talk.secrets (ou operator.admin). Quando segredos são incluídos, os clientes devem ler a credencial ativa do provedor Talk em talk.resolved.config.apiKey; talk.providers.<id>.apiKey permanece no formato da origem e pode ser um objeto SecretRef ou uma string redigida.

Métodos RPC de gateway registrados por Plugin podem solicitar seu próprio escopo de operador, mas prefixos administrativos centrais reservados (config.*, exec.approvals.*, wizard.*, update.*) sempre resolvem para operator.admin.

O escopo de método é apenas a primeira barreira. Alguns comandos de barra acessados por chat.send aplicam verificações mais rígidas em nível de comando além dela. Por exemplo, gravações persistentes de /config set e /config unset exigem operator.admin.

node.pair.approve também tem uma verificação extra de escopo no momento da aprovação além do escopo básico do método:

• solicitações sem comando: operator.pairing
• solicitações com comandos de nó que não sejam exec: operator.pairing + operator.write
• solicitações que incluem system.run, system.run.prepare ou system.which: operator.pairing + operator.admin

Capacidades/comandos/permissões (nó)

Nós declaram reivindicações de capacidade no momento da conexão:

• caps: categorias de capacidade de alto nível, como camera, canvas, screen, location, voice e talk.
• commands: lista de permissões de comandos para invoke.
• permissions: alternâncias granulares (por exemplo, screen.record, camera.capture).

O Gateway trata isso como reivindicações e aplica listas de permissões no lado do servidor.

Presença

• system-presence retorna entradas indexadas por identidade de dispositivo.
• Entradas de presença incluem deviceId, roles e scopes para que interfaces possam mostrar uma única linha por dispositivo mesmo quando ele se conecta como operador e nó.
• node.list inclui campos opcionais lastSeenAtMs e lastSeenReason. Nós conectados informam seu tempo de conexão atual como lastSeenAtMs com motivo connect; nós pareados também podem informar presença durável em segundo plano quando um evento de nó confiável atualiza seus metadados de pareamento.

Evento de nó ativo em segundo plano

Nós podem chamar node.event com event: "node.presence.alive" para registrar que um nó pareado estava ativo durante uma ativação em segundo plano sem marcá-lo como conectado.

{  "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 é um enum fechado: background, silent_push, bg_app_refresh, significant_location, manual ou connect. Strings de trigger desconhecidas são normalizadas para background pelo gateway antes da persistência. O evento só é durável para sessões de dispositivo de nó autenticadas; sessões sem dispositivo ou não pareadas retornam handled: false.

Gateways bem-sucedidos retornam um resultado estruturado:

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

Gateways mais antigos ainda podem retornar { "ok": true } para node.event; clientes devem tratar isso como uma RPC confirmada, não como persistência de presença durável.

Escopo de eventos de transmissão

Eventos de transmissão WebSocket enviados pelo servidor são controlados por escopo para que sessões com escopo de pareamento ou apenas de nó não recebam passivamente conteúdo de sessão.

• Frames de chat, agente e resultado de ferramenta (incluindo eventos agent transmitidos e resultados de chamadas de ferramenta) exigem pelo menos operator.read. Sessões sem operator.read ignoram esses frames completamente.
• Transmissões plugin.* definidas por Plugin são controladas por operator.write ou operator.admin, dependendo de como o Plugin as registrou.
• Eventos de status e transporte (heartbeat, presence, tick, ciclo de vida de conexão/desconexão etc.) permanecem irrestritos para que a integridade do transporte continue observável para cada sessão autenticada.
• Famílias desconhecidas de eventos de transmissão são controladas por escopo por padrão (falham fechadas), a menos que um manipulador registrado as relaxe explicitamente.

Cada conexão de cliente mantém seu próprio número de sequência por cliente, para que as transmissões preservem a ordenação monotônica nesse socket mesmo quando diferentes clientes veem diferentes subconjuntos filtrados por escopo do fluxo de eventos.

Famílias comuns de métodos RPC

A superfície WS pública é mais ampla do que os exemplos de handshake/autenticação acima. Isto não é um despejo gerado — hello-ok.features.methods é uma lista conservadora de descoberta criada a partir de src/gateway/server-methods-list.ts mais exports de métodos de Plugin/canal carregados. Trate-a como descoberta de recursos, não como uma enumeração completa de src/gateway/server-methods/*.ts.

Famílias de eventos comuns

• chat: atualizações de chat de UI, como chat.inject, e outros eventos de chat somente de transcrição. No protocolo v4, payloads delta carregam deltaText; message permanece o snapshot cumulativo do assistente. Substituições que não são prefixo definem replace=true e usam deltaText como texto de substituição.
• session.message, session.operation e session.tool: atualizações de transcrição, operação de sessão em andamento e stream de eventos para uma sessão assinada.
• sessions.changed: índice de sessões ou metadados alterados.
• presence: atualizações de snapshot de presença do sistema.
• tick: evento periódico de keepalive / liveness.
• health: atualização de snapshot de integridade do gateway.
• heartbeat: atualização de stream de eventos de Heartbeat.
• cron: evento de alteração de execução/job do cron.
• shutdown: notificação de desligamento do gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida de pareamento de nós.
• node.invoke.request: transmissão de solicitação de invoke de nó.
• device.pair.requested / device.pair.resolved: ciclo de vida de dispositivo pareado.
• voicewake.changed: configuração de gatilho de palavra de despertar alterada.
• exec.approval.requested / exec.approval.resolved: ciclo de vida de aprovação exec.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de aprovação de plugin.

Métodos auxiliares de Node

• Nós podem chamar skills.bins para buscar a lista atual de executáveis de Skills para verificações de permissão automática.

RPCs do livro-razão de tarefas

Clientes operadores podem inspecionar e cancelar registros de tarefas em segundo plano do Gateway por meio dos RPCs do livro-razão de tarefas. Esses métodos retornam resumos de tarefas sanitizados, não estado bruto de runtime.

• tasks.list exige operator.read.
  • Parâmetros: status opcional ("queued", "running", "completed", "failed", "cancelled" ou "timed_out") ou um array desses status, agentId opcional, sessionKey opcional, limit opcional de 1 a 500 e string cursor opcional.
  • Resultado: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get exige operator.read.
  • Parâmetros: { "taskId": string }.
  • Resultado: { "task": TaskSummary }.
  • IDs de tarefa ausentes retornam o formato de erro não encontrado do Gateway.
• tasks.cancel exige operator.write.
  • Parâmetros: { "taskId": string, "reason"?: string }.
  • Resultado: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found informa se o livro-razão tinha uma tarefa correspondente. cancelled informa se o runtime aceitou ou registrou o cancelamento.

TaskSummary inclui id, status e metadados opcionais como kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, timestamps, progresso, resumo terminal e texto de erro sanitizado. agentId identifica o agente que executa a tarefa; sessionKey e ownerKey preservam o contexto de solicitante e controle.

Métodos auxiliares de operador

• Operadores podem chamar commands.list (operator.read) para buscar o inventário de comandos em tempo de execução de um agente.
  • agentId é opcional; omita-o para ler o workspace padrão do agente.
  • scope controla qual superfície o name primário tem como alvo:
    • text retorna o token primário de comando de texto sem o / inicial
    • native e o caminho padrão both retornam nomes nativos cientes do provedor quando disponíveis
  • textAliases carrega aliases exatos com barra, como /model e /m.
  • nativeName carrega o nome de comando nativo ciente do provedor quando existir.
  • provider é opcional e afeta apenas a nomenclatura nativa e a disponibilidade de comandos nativos de plugin.
  • includeArgs=false omite metadados de argumentos serializados da resposta.
• Operadores podem chamar tools.catalog (operator.read) para buscar o catálogo de ferramentas em tempo de execução de um agente. A resposta inclui ferramentas agrupadas e metadados de proveniência:
  • source: core ou plugin
  • pluginId: proprietário do plugin quando source="plugin"
  • optional: se uma ferramenta de plugin é opcional
• Operadores podem chamar tools.effective (operator.read) para buscar o inventário de ferramentas efetivo em tempo de execução para uma sessão.
  • sessionKey é obrigatório.
  • O Gateway deriva o contexto confiável de tempo de execução da sessão no lado do servidor, em vez de aceitar contexto de autenticação ou entrega fornecido pelo chamador.
  • A resposta é uma projeção derivada pelo servidor e com escopo de sessão do inventário ativo, incluindo ferramentas de core, plugin, canal e servidores MCP já descobertos.
  • tools.effective é somente leitura para MCP: ele pode projetar um catálogo MCP de sessão aquecida por meio da política final de ferramentas, mas não cria runtimes MCP, conecta transportes nem emite tools/list. Se não existir um catálogo aquecido correspondente, a resposta pode incluir um aviso como mcp-not-yet-connected, mcp-not-yet-listed ou mcp-stale-catalog.
  • Entradas de ferramentas efetivas usam source="core", source="plugin", source="channel" ou source="mcp".
• Operadores podem chamar tools.invoke (operator.write) para invocar uma ferramenta disponível pelo mesmo caminho de política do Gateway que /tools/invoke.
  • name é obrigatório. args, sessionKey, agentId, confirm e idempotencyKey são opcionais.
  • Se sessionKey e agentId estiverem presentes, o agente da sessão resolvida deve corresponder a agentId.
  • Wrappers de core somente para proprietário, como cron, gateway e nodes, exigem identidade de proprietário/admin (operator.admin), embora o próprio método tools.invoke seja operator.write.
  • A resposta é um envelope voltado para SDK com ok, toolName, output opcional e campos error tipados. Recusas por aprovação ou política retornam ok:false no payload em vez de contornar o pipeline de política de ferramentas do Gateway.
• Operadores podem chamar skills.status (operator.read) para buscar o inventário visível de skills de um agente.
  • agentId é opcional; omita-o para ler o workspace padrão do agente.
  • A resposta inclui elegibilidade, requisitos ausentes, verificações de configuração e opções de instalação sanitizadas sem expor valores brutos de segredos.
• Operadores podem chamar skills.search e skills.detail (operator.read) para metadados de descoberta do ClawHub.
• Operadores podem chamar skills.upload.begin, skills.upload.chunk e skills.upload.commit (operator.admin) para preparar um arquivo privado de skill antes de instalá-lo. Este é um caminho separado de upload administrativo para clientes confiáveis, não o fluxo normal de instalação de skill do ClawHub, e fica desabilitado por padrão, a menos que skills.install.allowUploadedArchives esteja habilitado.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) cria um upload vinculado a esse slug e valor de force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) acrescenta bytes no deslocamento decodificado exato.
  • skills.upload.commit({ uploadId, sha256? }) verifica o tamanho final e o SHA-256. O commit apenas finaliza o upload; ele não instala a skill.
  • Arquivos de skills enviados são arquivos zip contendo uma raiz SKILL.md. O nome do diretório interno do arquivo nunca seleciona o alvo da instalação.
• Operadores podem chamar skills.install (operator.admin) em três modos:
  • Modo ClawHub: { source: "clawhub", slug, version?, force? } instala uma pasta de skill no diretório skills/ do workspace padrão do agente.
  • Modo upload: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } instala um upload confirmado no diretório skills/<slug> do workspace padrão do agente. O slug e o valor de force devem corresponder à solicitação original skills.upload.begin. Este modo é rejeitado, a menos que skills.install.allowUploadedArchives esteja habilitado. A configuração não afeta instalações do ClawHub.
  • Modo instalador do Gateway: { name, installId, timeoutMs? } executa uma ação metadata.openclaw.install declarada no host do Gateway. Clientes mais antigos ainda podem enviar dangerouslyForceUnsafeInstall; este campo está obsoleto, é aceito apenas para compatibilidade de protocolo e é ignorado. Use security.installPolicy para decisões de instalação controladas pelo operador.
• Operadores podem chamar skills.update (operator.admin) em dois modos:
  • O modo ClawHub atualiza um slug rastreado ou todas as instalações rastreadas do ClawHub no workspace padrão do agente.
  • O modo config aplica patches a valores de skills.entries.<skillKey>, como enabled, apiKey e env.

Visualizações de models.list

models.list aceita um parâmetro opcional view:

• Omitido ou "default": comportamento atual em tempo de execução. Se agents.defaults.models estiver configurado, a resposta será o catálogo permitido, incluindo modelos descobertos dinamicamente para entradas provider/*. Caso contrário, a resposta será o catálogo completo do Gateway.
• "configured": comportamento dimensionado para seletores. Se agents.defaults.models estiver configurado, ele ainda prevalece, incluindo descoberta com escopo de provedor para entradas provider/*. Sem uma allowlist, a resposta usa entradas explícitas de models.providers.*.models, recorrendo ao catálogo completo apenas quando não existem linhas de modelo configuradas.
• "all": catálogo completo do Gateway, ignorando agents.defaults.models. Use isto para diagnósticos e UIs de descoberta, não para seletores normais de modelo.

Aprovações de exec

• Quando uma solicitação de exec precisa de aprovação, o Gateway transmite exec.approval.requested.
• Clientes operadores resolvem chamando exec.approval.resolve (exige escopo operator.approvals).
• Para host=node, exec.approval.request deve incluir systemRunPlan (argv/cwd/rawCommand/metadados de sessão canônicos). Solicitações sem systemRunPlan são rejeitadas.
• Após a aprovação, chamadas encaminhadas de node.invoke system.run reutilizam esse systemRunPlan canônico como o contexto autoritativo de comando/cwd/sessão.
• Se um chamador modificar command, rawCommand, cwd, agentId ou sessionKey entre a preparação e o encaminhamento final aprovado de system.run, o Gateway rejeitará a execução em vez de confiar no payload modificado.

Fallback de entrega do agente

• Solicitações agent podem incluir deliver=true para solicitar entrega de saída.
• bestEffortDeliver=false mantém o comportamento estrito: alvos de entrega não resolvidos ou somente internos retornam INVALID_REQUEST.
• bestEffortDeliver=true permite fallback para execução apenas na sessão quando nenhuma rota externa entregável puder ser resolvida (por exemplo, sessões internas/webchat ou configurações multicanal ambíguas).
• Resultados finais de agent podem incluir result.deliveryStatus quando a entrega foi solicitada, usando os mesmos status sent, suppressed, partial_failed e failed documentados para openclaw agent --json --deliver.

Versionamento

• PROTOCOL_VERSION fica em packages/gateway-protocol/src/version.ts.
• Clientes enviam minProtocol + maxProtocol; o servidor rejeita intervalos que não incluem seu protocolo atual. Clientes e servidores atuais exigem o protocolo v4.
• Esquemas + modelos são gerados a partir de definições TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Constantes do cliente

O cliente de referência em src/gateway/client.ts usa estes padrões. Os valores são estáveis no protocolo v4 e são a linha de base esperada para clientes de terceiros.

O servidor anuncia policy.tickIntervalMs, policy.maxPayload e policy.maxBufferedBytes efetivos em hello-ok; clientes devem respeitar esses valores em vez dos padrões pré-handshake.

Auth

• A autenticação do Gateway por segredo compartilhado usa connect.params.auth.token ou connect.params.auth.password, dependendo do modo de autenticação configurado.
• Modos com identidade, como Tailscale Serve (gateway.auth.allowTailscale: true) ou gateway.auth.mode: "trusted-proxy" sem loopback, satisfazem a verificação de autenticação de connect a partir dos cabeçalhos da solicitação, em vez de connect.params.auth.*.
• gateway.auth.mode: "none" de ingresso privado ignora totalmente a autenticação de connect por segredo compartilhado; não exponha esse modo em ingresso público/não confiável.
• Após o pareamento, o Gateway emite um token de dispositivo com escopo limitado à função da conexão + escopos. Ele é retornado em hello-ok.auth.deviceToken e deve ser persistido pelo cliente para conexões futuras.
• Os clientes devem persistir o hello-ok.auth.deviceToken primário após qualquer conexão bem-sucedida.
• Reconectar com esse token de dispositivo armazenado também deve reutilizar o conjunto de escopos aprovados armazenado para esse token. Isso preserva o acesso de leitura/sondagem/status que já foi concedido e evita reduzir silenciosamente as reconexões para um escopo implícito mais restrito, somente de administrador.
• Montagem da autenticação de connect no lado do cliente (selectConnectAuth em src/gateway/client.ts):
  • auth.password é ortogonal e sempre é encaminhado quando definido.
  • auth.token é preenchido em ordem de prioridade: primeiro o token compartilhado explícito, depois um deviceToken explícito, depois um token armazenado por dispositivo (indexado por deviceId + role).
  • auth.bootstrapToken é enviado somente quando nenhum dos itens acima resolveu um auth.token. Um token compartilhado ou qualquer token de dispositivo resolvido o suprime.
  • A promoção automática de um token de dispositivo armazenado na nova tentativa única AUTH_TOKEN_MISMATCH é restrita a endpoints confiáveis apenas — loopback ou wss:// com um tlsFingerprint fixado. wss:// público sem fixação não se qualifica.
• O bootstrap de código de configuração integrado retorna o hello-ok.auth.deviceToken do Node primário mais um token de operador limitado em hello-ok.auth.deviceTokens para transferência móvel confiável. O token de operador inclui operator.talk.secrets para leituras de configuração nativa do Talk, mas exclui escopos de mutação de pareamento e operator.admin.
• Enquanto um bootstrap de código de configuração não basal aguarda aprovação, os detalhes de PAIRING_REQUIRED incluem recommendedNextStep: "wait_then_retry", retryable: true e pauseReconnect: false. Os clientes devem continuar reconectando com o mesmo token de bootstrap até que a solicitação seja aprovada ou o token se torne inválido.
• Persista hello-ok.auth.deviceTokens somente quando a conexão usar autenticação de bootstrap em um transporte confiável, como wss:// ou pareamento local/loopback.
• Se um cliente fornece um deviceToken explícito ou scopes explícitos, esse conjunto de escopos solicitado pelo chamador permanece autoritativo; escopos em cache só são reutilizados quando o cliente está reutilizando o token armazenado por dispositivo.
• Tokens de dispositivo podem ser rotacionados/revogados por meio de device.token.rotate e device.token.revoke (exige o escopo operator.pairing). Rotacionar ou revogar um Node ou outra função não operadora também exige operator.admin.
• device.token.rotate retorna metadados de rotação. Ele ecoa o token bearer de substituição somente para chamadas do mesmo dispositivo que já estão autenticadas com esse token de dispositivo, para que clientes somente com token possam persistir a substituição antes de reconectar. Rotações compartilhadas/de administrador não ecoam o token bearer.
• A emissão, rotação e revogação de tokens permanecem limitadas ao conjunto de funções aprovado registrado na entrada de pareamento desse dispositivo; a mutação de token não pode expandir nem direcionar uma função de dispositivo que a aprovação de pareamento nunca concedeu.
• Para sessões de token de dispositivo pareado, o gerenciamento de dispositivos é autoescopado, a menos que o chamador também tenha operator.admin: chamadores não administradores podem gerenciar somente o token de operador da entrada do próprio dispositivo. O gerenciamento de tokens de Node e de outros não operadores é somente de administrador, mesmo para o próprio dispositivo do chamador.
• device.token.rotate e device.token.revoke também verificam o conjunto de escopos do token de operador de destino em relação aos escopos da sessão atual do chamador. Chamadores não administradores não podem rotacionar nem revogar um token de operador mais amplo do que já possuem.
• Falhas de autenticação incluem error.details.code mais dicas de recuperação:
  • error.details.canRetryWithDeviceToken (booleano)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Comportamento do cliente para AUTH_TOKEN_MISMATCH:
  • Clientes confiáveis podem tentar uma nova tentativa limitada com um token em cache por dispositivo.
  • Se essa nova tentativa falhar, os clientes devem interromper loops de reconexão automática e exibir orientação de ação para o operador.
• AUTH_SCOPE_MISMATCH significa que o token de dispositivo foi reconhecido, mas não cobre a função/escopos solicitados. Os clientes não devem apresentar isso como um token inválido; solicite que o operador faça o pareamento novamente ou aprove o contrato de escopo mais restrito/mais amplo.

Identidade do dispositivo + pareamento

• Nodes devem incluir uma identidade de dispositivo estável (device.id) derivada de uma impressão digital de par de chaves.
• Gateways emitem tokens por dispositivo + função.
• Aprovações de pareamento são exigidas para novos IDs de dispositivo, a menos que a aprovação automática local esteja habilitada.
• A aprovação automática de pareamento é centrada em conexões diretas de local loopback.
• O OpenClaw também tem um caminho restrito de autoconexão local de backend/contêiner para fluxos auxiliares confiáveis de segredo compartilhado.
• Conexões de tailnet ou LAN no mesmo host ainda são tratadas como remotas para pareamento e exigem aprovação.
• Clientes WS normalmente incluem identidade device durante connect (operador + Node). As únicas exceções de operador sem dispositivo são caminhos de confiança explícitos:
  • gateway.controlUi.allowInsecureAuth=true para compatibilidade com HTTP inseguro somente em localhost.
  • autenticação bem-sucedida do Control UI de operador com gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, rebaixamento severo de segurança).
  • RPCs de backend gateway-client de loopback direto no caminho auxiliar interno reservado.
• Omitir a identidade do dispositivo tem consequências de escopo. Quando uma conexão de operador sem dispositivo é permitida por meio de um caminho de confiança explícito, o OpenClaw ainda limpa os escopos autodeclarados para um conjunto vazio, a menos que esse caminho tenha uma exceção nomeada de preservação de escopo. Métodos protegidos por escopo então falham com missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true é um caminho break-glass de preservação de escopo do Control UI. Ele não concede escopos a clientes WebSocket arbitrários personalizados de backend ou em formato de CLI.
• O caminho auxiliar de backend gateway-client reservado de loopback direto preserva escopos apenas para RPCs internos locais do plano de controle; IDs personalizados de backend não recebem essa exceção.
• Todas as conexões devem assinar o nonce connect.challenge fornecido pelo servidor.

Diagnósticos de migração de autenticação de dispositivo

Para clientes legados que ainda usam o comportamento de assinatura anterior ao desafio, connect agora retorna códigos de detalhe DEVICE_AUTH_* em error.details.code com um error.details.reason estável.

Falhas comuns de migração:

Destino da migração:

• Sempre aguarde connect.challenge.
• Assine a carga v2 que inclui o nonce do servidor.
• Envie o mesmo nonce em connect.params.device.nonce.
• A carga de assinatura preferida é v3, que vincula platform e deviceFamily além dos campos device/client/role/scopes/token/nonce.
• Assinaturas legadas v2 continuam aceitas para compatibilidade, mas a fixação de metadados de dispositivo pareado ainda controla a política de comandos na reconexão.

TLS + fixação

• TLS é compatível com conexões WS.
• Os clientes podem, opcionalmente, fixar a impressão digital do certificado do Gateway (consulte a configuração gateway.tls mais gateway.remote.tlsFingerprint ou a CLI --tls-fingerprint).

Escopo

Este protocolo expõe a API completa do Gateway (status, canais, modelos, chat, agente, sessões, Nodes, aprovações etc.). A superfície exata é definida pelos esquemas TypeBox em packages/gateway-protocol/src/schema.ts.

Relacionados

• Protocolo de ponte
• Runbook do Gateway