Protocolo do Gateway

O protocolo WS do Gateway é o único plano de controle e transporte de nodes do OpenClaw. Clientes operadores e nodes (CLI, interface web, aplicativo para macOS, nodes iOS/Android, nodes headless) conectam-se por WebSocket e declaram uma função e um escopo no momento do handshake.

Transporte e enquadramento

• WebSocket, quadros de texto, payloads JSON.
• O primeiro quadro deve ser uma solicitação connect.
• Quadros anteriores à conexão são limitados a 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Após o handshake, siga hello-ok.policy.maxPayload e hello-ok.policy.maxBufferedBytes. Com os diagnósticos ativados, quadros de entrada grandes demais e buffers de saída lentos emitem eventos payload.large antes que o Gateway feche ou descarte o quadro. Esses eventos contêm surface, tamanhos em bytes, limites e um código de motivo seguro, nunca corpos de mensagens, conteúdo de anexos, bytes brutos de quadros, tokens, cookies ou segredos.

Formatos dos quadros:

• 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).

Handshake

O Gateway envia um desafio anterior à conexão:

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

O cliente responde com 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": "…"    }  }}

O Gateway responde com 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 e auth são todos obrigatórios em HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth informa a função e os escopos negociados mesmo quando nenhum token de dispositivo é emitido (formato acima). pluginSurfaceUrls é opcional e mapeia nomes de superfícies de plugins (por exemplo, canvas) para URLs hospedadas com escopo; ele pode expirar, portanto os nodes chamam node.pluginSurface.refresh com { "surface": "canvas" } para obter uma entrada nova. O caminho obsoleto canvasHostUrl / canvasCapability / node.canvas.capability.refresh não é compatível; use superfícies de plugins.

Enquanto o Gateway ainda estiver concluindo a inicialização dos processos auxiliares, connect poderá retornar um erro UNAVAILABLE que permite nova tentativa, com details.reason: "startup-sidecars" e retryAfterMs. Tente novamente dentro do limite de tempo da conexão, em vez de tratar isso como uma falha terminal do handshake.

Quando um token de dispositivo é emitido, hello-ok.auth o adiciona:

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

O bootstrap integrado por QR/código de configuração é um caminho de transferência para dispositivos móveis. Uma conexão bem-sucedida com o código de configuração básico retorna um token de node primário e um token de operador limitado:

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

Essa transferência para o operador é limitada de propósito: o suficiente para iniciar o ciclo do operador móvel e a configuração nativa, incluindo operator.talk.secrets para leituras da configuração do Talk, mas sem escopos de alteração de pareamento e sem operator.admin. Um acesso mais amplo a pareamento/administração exige um fluxo separado e aprovado de pareamento ou token. Persista hello-ok.auth.deviceTokens somente quando a autenticação do bootstrap tiver sido executada por um transporte confiável (wss:// ou pareamento por loopback/local).

Clientes de backend confiáveis no mesmo processo (client.id: "gateway-client", client.mode: "backend") podem omitir device em conexões diretas por loopback ao se autenticarem com o token/senha compartilhado do Gateway. Esse caminho é reservado para RPCs internos do plano de controle (por exemplo, atualizações de sessão de subagentes) e evita que linhas de base obsoletas de pareamento de CLI/dispositivo bloqueiem o trabalho do backend local. Clientes remotos, com origem no navegador, nodes e clientes explícitos de token de dispositivo/identidade de dispositivo ainda passam pelas verificações normais de pareamento e elevação de escopo.

Função de worker e protocolo fechado

Workers na nuvem usam uma entrada dedicada por loopback através do túnel SSH pertencente ao Gateway, com chave do host fixada. Ela aceita somente a identidade do worker e nunca encaminha autenticação geral, eventos de node, RPCs de operador ou métodos de plugins. Um connect rigoroso verifica uma credencial de curta duração, armazenada como hash e vinculada ao ambiente, ao hash do bundle, à época do proprietário, à versão do conjunto de RPCs, à expiração e a uma sessão anulável; ele verifica separadamente a versão e o conjunto de recursos atuais. O sucesso retorna um worker-hello-ok mínimo; a negociação de recursos é independente da versão geral do protocolo. Os quadros permanecem abaixo de 64 KiB. A lista fechada de permissões contém worker.heartbeat, worker.transcript.commit e worker.live-event. Os commits de transcrição usam delimitação pela época do proprietário, uma vinculação de sessão pertencente ao Gateway, comparação e troca da folha base e reprodução durável de sequência; o Gateway gera IDs de entrada e de pai da transcrição por meio do gravador de sessão normal. A propriedade e a expiração são verificadas novamente em cada RPC.

Recursos do cliente

Clientes operadores podem anunciar recursos opcionais em connect.params.caps:

• tool-events: aceita eventos estruturados do ciclo de vida de ferramentas.
• inline-widgets: pode renderizar resultados hospedados de ferramentas em widgets embutidos.

Os recursos do cliente descrevem o cliente conectado, não a autorização. As ferramentas do agente podem declarar recursos obrigatórios; o Gateway omite essas ferramentas, a menos que todos os requisitos estejam presentes em caps do cliente de origem. Execuções originadas em canais não têm recursos de cliente do Gateway, portanto ferramentas condicionadas a recursos ficam indisponíveis mesmo quando a política de ferramentas as permite explicitamente.

Exemplo de conexão de node

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

Os nodes declaram as alegações de recursos no momento da conexão:

• caps: categorias de alto nível, como camera, canvas, screen, location, voice, talk.
• commands: lista de permissões de comandos para invocação.
• permissions: controles granulares (por exemplo, screen.record, camera.capture).

O Gateway trata esses valores como alegações e aplica listas de permissões no lado do servidor.

Funções e escopos

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

Funções:

• operator: cliente do plano de controle (CLI/interface/automação).
• node: host de recursos (câmera/tela/canvas/system.run).
• worker: host de execução na nuvem no protocolo dedicado e fechado de workers.

Escopos do operador (src/gateway/operator-scopes.ts), o conjunto fechado completo:

• 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 os segredos estiverem incluídos, leia a credencial ativa do provedor do Talk em talk.resolved.config.apiKey; talk.providers.<id>.apiKey mantém o formato da origem e pode ser um objeto SecretRef ou uma string ocultada.

Métodos RPC do Gateway registrados por plugins podem solicitar seu próprio escopo de operador, mas estes prefixos reservados do núcleo sempre são resolvidos como operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

O escopo do método é apenas a primeira barreira. Alguns comandos de barra acessados por chat.send aplicam verificações mais rigorosas no nível do comando: gravações persistentes de /config set e /config unset exigem operator.admin, mesmo para clientes do Gateway que já tenham um escopo de operador inferior.

node.pair.approve tem uma verificação adicional de escopo no momento da aprovação, além do escopo base do método (operator.pairing), com base nos commands declarados pela solicitação pendente (src/infra/node-pairing-authz.ts):

Caps/comandos/permissões (node)

Os nodes declaram as alegações de recursos no momento da conexão:

• caps: categorias de recursos de alto nível, como camera, canvas, screen, location, voice e talk.
• commands: lista de permissões de comandos para invocação.
• permissions: controles granulares (por exemplo, screen.record, camera.capture).

O Gateway trata esses valores como alegações e aplica listas de permissões no lado do servidor. Nodes conectados podem publicar descritores opcionais, visíveis para o agente, de ferramentas de plugins ou MCP com node.pluginTools.update após uma conexão ou reconexão bem-sucedida. Hosts de nodes headless são reiniciados para aplicar alterações declarativas no inventário MCP. Esse método de atualização é o único caminho de publicação; descritores de ferramentas de plugins não são aceitos nos parâmetros de connect. Cada descritor deve usar um name de ferramenta seguro para o provedor e nomear um command presente na lista atual de permissões de comandos do node. O Gateway confia nos metadados do descritor provenientes do node pareado, filtra descritores fora da superfície de comandos aprovada, remove-os quando o node se desconecta e rejeita tentativas do operador de alterar o catálogo de outro node. Defina gateway.nodes.pluginTools.enabled: false para ignorar descritores publicados por nodes.

Hosts de nodes conectados publicam seu catálogo completo de substituição de skills com node.skills.update. Esse método da função de node é o único caminho de publicação de skills de nodes; skills não são aceitas nos parâmetros de connect. Cada descritor contém um nome seguro, uma descrição e conteúdo limitado de SKILL.md. O Gateway analisa esse conteúdo com o carregador normal de skills, inclui-o nos snapshots de skills do agente enquanto o node está conectado e remove-o na desconexão. Defina gateway.nodes.skills.enabled: false para ignorar skills publicadas por nodes.

Presença

• system-presence retorna entradas indexadas pela identidade do dispositivo, incluindo deviceId, roles e scopes, para que as interfaces possam mostrar uma linha por dispositivo, mesmo quando ele se conecta tanto como operador quanto como node.
• node.list inclui os campos opcionais lastSeenAtMs e lastSeenReason. Nodes conectados informam o horário da conexão atual com o motivo connect; nodes pareados também podem informar presença durável em segundo plano por meio de um evento confiável de node.

Nodes nativos do macOS também podem enviar eventos node.presence.activity autenticados com tempo de inatividade de entrada limitado. O Gateway deriva os carimbos de data/hora de atividade usando seu próprio relógio, expõe o Mac conectado com atividade mais recente por meio de node.list e node.describe e transmite atualizações de node.presence para clientes com escopo de leitura. Consulte Presença do computador ativo para saber mais sobre seleção, privacidade, contexto do modelo e comportamento de roteamento de notificações.

Evento de atividade do Node em segundo plano

Os Nodes chamam node.event com event: "node.presence.alive" para registrar que um Node 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\":\"iPhone do Peter\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger é uma enumeração fechada: background, silent_push, bg_app_refresh, significant_location, manual, connect. Valores desconhecidos são normalizados para background (src/shared/node-presence.ts). O evento só é persistido em sessões autenticadas de dispositivos Node; 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 podem retornar apenas { "ok": true } para node.event; trate isso como uma RPC confirmada, não como persistência durável da presença.

Escopo de eventos de transmissão

Eventos de transmissão enviados pelo servidor são controlados por escopo para que sessões com escopo de pareamento ou exclusivas de Node não recebam passivamente o conteúdo da sessão (src/gateway/server-broadcast.ts):

• Quadros de chat, agente e resultado de ferramenta (eventos agent transmitidos, eventos de resultado de ferramenta) exigem pelo menos operator.read. Sessões sem esse escopo ignoram completamente esses quadros.
• Transmissões plugin.* definidas por Plugins são restritas a operator.write ou operator.admin por padrão; entradas explícitas como plugin.approval.requested / plugin.approval.resolved usam operator.approvals.
• Eventos de status/transporte (heartbeat, presence, tick, ciclo de vida de conexão/desconexão) permanecem irrestritos para que a integridade do transporte seja observável por todas as sessões autenticadas.
• Famílias desconhecidas de eventos de transmissão são controladas por escopo por padrão (falha segura) a menos que um manipulador registrado as flexibilize explicitamente.

Cada conexão de cliente mantém seu próprio número de sequência por cliente, portanto as transmissões permanecem ordenadas de forma monotônica nesse soquete, mesmo quando clientes diferentes veem subconjuntos distintos do fluxo de eventos filtrados por escopo.

Famílias de métodos RPC

hello-ok.features.methods é uma lista de descoberta conservadora criada a partir de src/gateway/server-methods-list.ts e das exportações de métodos de plugins/canais carregados — ela não é um despejo gerado de todos os métodos, e alguns métodos (por exemplo, push.test, web.login.start, web.login.wait, sessions.usage) são intencionalmente excluídos da descoberta, embora sejam métodos reais e invocáveis. Considere isso uma descoberta de recursos, não uma enumeração completa de src/gateway/server-methods/*.ts.

Famílias comuns de eventos

• chat: atualizações do chat da UI, como chat.inject e outros eventos de chat exclusivos da transcrição. No protocolo v4, cargas delta contêm deltaText; message continua sendo o snapshot cumulativo do assistente. Substituições que não sejam de prefixo definem replace=true e usam deltaText como texto substituto.
• session.message, session.operation, session.tool: atualizações de transcrição, operação de sessão em andamento e fluxo de eventos para uma sessão assinada.
• session.approval: estado sanitizado e autoritativo de aprovações pendentes e terminais para um assinante de sessão exata que tenha aderido explicitamente. Aprovações filhas usam o público ancestral persistido; os eventos nunca alteram transcrições nem despertam agentes.
• sessions.changed: o índice ou os metadados da sessão foram alterados.
• presence: atualizações do snapshot de presença do sistema.
• tick: evento periódico de keepalive/atividade.
• health: atualização do snapshot de integridade do Gateway.
• heartbeat: atualização do fluxo de eventos de Heartbeat.
• cron: evento de alteração de execução/trabalho Cron.
• shutdown: notificação de desligamento do Gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida do pareamento de Node.
• node.invoke.request: transmissão de solicitação de invocação de Node.
• device.pair.requested / device.pair.resolved: ciclo de vida do dispositivo pareado.
• voicewake.changed: a configuração do acionador por palavra de ativação foi alterada.
• exec.approval.requested / exec.approval.resolved: ciclo de vida da aprovação de execução.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida da aprovação de Plugin.

Métodos auxiliares de Node

Nodes podem chamar skills.bins para obter a lista atual de executáveis de Skills para verificações de permissão automática.

RPC do livro-razão de auditoria

audit.activity.list fornece aos clientes do operador uma visualização estável, do mais recente para o mais antigo, dos metadados de ciclo de vida de execuções de agente, ações de ferramenta e mensagens com adesão opcional. Exige operator.read. As consultas excluem registros com mais de 30 dias, e o livro-razão SQLite compartilhado é limitado a 100,000 registros. Linhas expiradas são excluídas durante a inicialização do Gateway, a manutenção horária e gravações posteriores. Consulte Histórico de auditoria para conhecer o modelo de dados e a semântica de privacidade.

• Parâmetros: agentId, sessionKey ou runId exato opcional; kind opcional ("agent_run", "tool_action" ou "message"); status opcional ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" ou "unknown"); direction opcional da mensagem ("inbound" ou "outbound") e channel exato; limites inclusivos opcionais after / before em milissegundos Unix; limit opcional de 1 a 500; e cursor de string opcional da página anterior.
• Resultado: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

A união nomeada de resultados V1 tem esquemas separados para execução de agente, ação de ferramenta, mensagem de entrada e mensagem de saída. O discriminador eventType é, respectivamente, agent_run, tool_action, inbound_message ou outbound_message; kind e direction da mensagem continuam disponíveis para filtragem e exibição. Todo evento tem schemaVersion: 1 inteiro. As referências de identidade da mensagem usam o formato exato hmac-sha256:v1:<32 hex key id>:<64 hex digest>; um id de ator remetente do canal usa o mesmo formato.

Todas as variantes exigem eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor e redaction. Os campos das variantes são:

As enumerações fechadas de mensagem são:

• conversationKind: direct, group, channel ou unknown.
• outcome de entrada: completed, skipped ou failed; reasonCode opcional: 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 ou acp_dispatch_aborted.
• outcome de saída: sent, suppressed, failed ou unknown; reasonCode opcional: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook ou no_visible_payload. Um adaptador que não retorna identidade da plataforma é unknown, pois não é possível refutar o efeito colateral externo.
• deliveryKind: text, media ou other; failureStage: platform_send, queue ou unknown.

Os campos terminais são correlacionados, não opcionais de forma independente:

Cada evento de atividade inclui um id de evento estável, uma sequência monotônica do registro contábil, a sequência do evento de origem, o carimbo de data/hora, o ator, a ação, o status, schemaVersion: 1 inteiro e redaction: "metadata_only". Os registros de execução e ferramenta exigem a proveniência do agente e da execução e podem incluir a proveniência da sessão. Os registros de mensagem podem incluir ids de agente e execução, mas intencionalmente nunca incluem sessionKey ou sessionId; portanto, o filtro de consulta sessionKey aplica-se somente às linhas de execução e ferramenta. Os eventos de ferramenta podem incluir o id da chamada da ferramenta e o nome da ferramenta.

Os registros de mensagem usam message.inbound.processed ou message.outbound.finished e adicionam direção, canal, tipo de conversa, resultado normalizado e, opcionalmente, tipo de entrega, estágio da falha, duração, contagem de resultados, código do motivo e pseudônimos com chave, locais à instalação, de conta/conversa/mensagem/destino. Esses pseudônimos auxiliam na correlação, mas não constituem anonimização: o banco de dados de estado contém a chave deles, enquanto as exportações de RPC e CLI não a contêm. O registro contábil não armazena prompts, corpos de mensagens, argumentos de ferramentas, resultados de ferramentas, saída de comandos nem texto bruto de erros. Os valores sessionKey de execução/ferramenta permanecem como metadados brutos de correlação e podem incorporar ids de conta ou de par da plataforma; os registros de mensagem omitem chaves de sessão.

Para linhas de entrada, durationMs mede o despacho do núcleo até seu estado terminal e resultCount conta payloads finalizados de ferramentas, blocos e respostas na fila. Para linhas de saída, durationMs abrange desde a posse da entrega até a confirmação, a fila de mensagens mortas ou a reconciliação (incluindo o tempo de espera na fila), e resultCount conta os envios físicos identificados para a plataforma. deliveryKind, quando presente, descreve o payload efetivo após hooks e renderização; linhas suprimidas ou ambíguas devido a falhas omitem esse campo.

A cobertura atual de mensagens inclui mensagens de entrada aceitas que chegam ao despacho do núcleo, incluindo resultados de duplicação/estado terminal do núcleo. A cobertura de saída grava uma linha terminal por payload de resposta lógico original que chega à entrega durável compartilhada; a divisão em partes e a distribuição pelo adaptador são agregadas em resultCount. Envios na fila que podem ser repetidos ou que são ambíguos são registrados somente após confirmação, envio à fila de mensagens mortas ou reconciliação. Caminhos locais de Plugin e de envio direto que contornam esses limites compartilhados ainda não são cobertos. A fila limitada de workers opera em regime de melhor esforço e pode descartar registros em caso de falha ou saturação, portanto esta superfície não é um arquivo de conformidade sem perdas.

A gravação fica ativada por padrão e é controlada por audit.enabled. A gravação de mensagens é controlada separadamente por audit.messages e o padrão é "off". Quando a gravação está desativada, audit.activity.list continua fornecendo registros gravados anteriormente até que expirem.

Os esquemas fornecidos de solicitação e resultado de audit.list e de AuditEvent permanecem inalterados e retornam somente registros de execução de agente e ação de ferramenta. Novos clientes de operador devem chamar audit.activity.list quando o Gateway o anunciar. Gateways mais antigos podem retornar unknown method: audit.activity.list ou, como a autorização precedia a consulta do método nas versões fornecidas, missing scope: operator.admin para uma solicitação com escopo de leitura. Trate o segundo caso como ausência do método somente quando o método não tiver sido anunciado. Um cliente poderá então tentar novamente com audit.list somente quando seus filtros não exigirem suporte a tipo de mensagem, direção ou canal.

Use openclaw audit para consultas de texto e exportações JSON limitadas.

RPCs do registro de tarefas

Clientes de operador inspecionam e cancelam registros de tarefas em segundo plano do Gateway por meio dos RPCs do registro de tarefas (packages/gateway-protocol/src/schema/tasks.ts). Eles retornam resumos de tarefas sanitizados, não o estado bruto do runtime.

• tasks.list exige operator.read.
  • Parâmetros: status opcional ("queued", "running", "completed", "failed", "cancelled" ou "timed_out") ou um array desses estados, agentId opcional, sessionKey opcional, limit opcional de 1 a 500 e cursor de string 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 de 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 registro continha uma tarefa correspondente. cancelled informa se o runtime aceitou ou registrou o cancelamento.

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

Métodos auxiliares do operador

• commands.list (operator.read) busca o inventário de comandos de runtime para um agente.
  • agentId é opcional; omita-o para ler o espaço de trabalho do agente padrão.
  • scope controla qual superfície é o destino do name principal: text retorna o token principal do comando de texto sem a / inicial; native e o caminho padrão both retornam nomes nativos específicos do provedor quando disponíveis.
  • textAliases contém aliases exatos com barra, como /model e /m.
  • nativeName contém o nome do comando nativo específico do provedor quando existe.
  • provider é opcional e afeta somente a nomenclatura nativa e a disponibilidade de comandos nativos de plugins.
  • includeArgs=false omite da resposta os metadados serializados dos argumentos.
• tools.catalog (operator.read) busca o catálogo de ferramentas de runtime para um agente. A resposta inclui ferramentas agrupadas e metadados de proveniência:
  • source: core ou plugin
  • pluginId: plugin proprietário quando source="plugin"
  • optional: indica se uma ferramenta de plugin é opcional
• tools.effective (operator.read) busca o inventário de ferramentas efetivas no runtime para uma sessão.
  • sessionKey é obrigatório.
  • O gateway deriva o contexto confiável de runtime da sessão no servidor, em vez de aceitar contexto de autenticação ou entrega fornecido pelo chamador.
  • A resposta é uma projeção derivada pelo servidor e limitada à sessão do inventário ativo, incluindo ferramentas do núcleo, de plugins, de canais e de servidores MCP já descobertos.
  • tools.effective é somente leitura para MCP: pode projetar um catálogo MCP de uma sessão ativa por meio da política final de ferramentas, mas não cria runtimes MCP, conecta transportes nem emite tools/list. Se não houver um catálogo ativo correspondente, a resposta poderá incluir um aviso como mcp-not-yet-connected, mcp-not-yet-listed ou mcp-stale-catalog.
  • As entradas de ferramentas efetivas usam source="core", source="plugin", source="channel" ou source="mcp".
• tools.invoke (operator.write) invoca 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 resolvido da sessão deverá corresponder a agentId.
  • Wrappers do núcleo exclusivos do proprietário, como cron, gateway e nodes, exigem identidade de proprietário/administrador (operator.admin), embora tools.invoke em si seja operator.write.
  • A resposta é um envelope voltado ao SDK com ok, toolName, output opcional e campos error tipados. Recusas por aprovação ou política retornam ok:false na carga útil, em vez de ignorar o pipeline de políticas de ferramentas do gateway.
• skills.status (operator.read) busca o inventário visível de Skills para um agente.
  • agentId é opcional; omita-o para ler o espaço de trabalho do agente padrão.
  • A resposta inclui elegibilidade, requisitos ausentes, verificações de configuração e opções de instalação sanitizadas, sem expor valores brutos de segredos.
• skills.search e skills.detail (operator.read) retornam metadados de descoberta do ClawHub.
• skills.upload.begin, skills.upload.chunk e skills.upload.commit (operator.admin) preparam 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 Skills do ClawHub, e fica desativado por padrão, a menos que skills.install.allowUploadedArchives esteja ativado.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) cria um upload vinculado a esse slug e valor de força.
  • 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. A confirmação apenas finaliza o upload; ela não instala a Skill.
  • Os arquivos de Skills enviados são arquivos zip que contêm um SKILL.md na raiz. O nome do diretório interno do arquivo nunca seleciona o destino da instalação.
• skills.install (operator.admin) tem três modos:
  • Modo ClawHub: { source: "clawhub", slug, version?, force? } instala uma pasta de Skill no diretório skills/ do espaço de trabalho do agente padrão.
  • Modo de upload: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } instala um upload confirmado no diretório skills/<slug> do espaço de trabalho do agente padrão. O slug e o valor de força devem corresponder à solicitação skills.upload.begin original. A solicitação é rejeitada, a menos que skills.install.allowUploadedArchives esteja ativado; a configuração não afeta instalações do ClawHub.
  • Modo de instalador do Gateway: { name, installId, timeoutMs? } executa uma ação metadata.openclaw.install declarada no host do gateway. Clientes antigos ainda podem enviar dangerouslyForceUnsafeInstall; esse campo está obsoleto, é aceito somente para compatibilidade de protocolo e é ignorado. Use security.installPolicy para decisões de instalação sob responsabilidade do operador.
• skills.update (operator.admin) tem dois modos:
  • O modo ClawHub atualiza um slug rastreado ou todas as instalações rastreadas do ClawHub no espaço de trabalho do agente padrão.
  • O modo de configuração modifica valores de skills.entries.<skillKey>, como enabled, apiKey e env.

Visualizações de models.list

models.list aceita um parâmetro view opcional (src/agents/model-catalog-visibility.ts):

• Omitido ou "default": 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 terá precedência, incluindo a descoberta limitada ao provedor para entradas provider/*. Sem uma lista de permissões, a resposta usará entradas explícitas de models.providers.<provider>.models, recorrendo ao catálogo completo somente quando não houver linhas de modelos configuradas.
• "provider-config": inventário de models.providers.*.models criado pela origem, independente das listas de permissões do seletor. As linhas incluem recursos públicos dos modelos e disponibilidade que considera as rotas, mas omitem endpoints de provedores, material de autenticação e configuração de solicitações de runtime.
• "all": catálogo completo do gateway, ignorando agents.defaults.models. Use para interfaces de diagnóstico/descoberta, não para seletores normais de modelos.

Aprovações de execução

• Quando uma solicitação de execução precisa de aprovação, o gateway transmite exec.approval.requested.
• Clientes operadores resolvem a solicitação chamando exec.approval.resolve (requer operator.approvals).
• Para host=node, exec.approval.request deve incluir systemRunPlan (argv/cwd/rawCommand canônicos e metadados da sessão). 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 alterar 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 na carga útil alterada.

Fallback de entrega do agente

• As solicitações de agent podem incluir deliver=true para solicitar entrega de saída.
• bestEffortDeliver=false (o padrão) mantém o comportamento estrito: destinos de entrega não resolvidos ou somente internos retornam INVALID_REQUEST.
• bestEffortDeliver=true permite fallback para execução somente na sessão quando nenhuma rota externa de entrega puder ser resolvida (por exemplo, sessões internas/de webchat ou configurações ambíguas com vários canais).
• Os resultados finais de agent podem incluir result.deliveryStatus quando a entrega tiver sido solicitada, usando os mesmos status sent, suppressed, partial_failed e failed documentados para openclaw agent --json --deliver.

Versionamento

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION e MIN_PROBE_PROTOCOL_VERSION ficam em packages/gateway-protocol/src/version.ts.
• Os clientes enviam minProtocol + maxProtocol. Os clientes operadores e de interface devem incluir o protocolo atual nesse intervalo; clientes e servidores atuais executam o protocolo v4.
• Clientes autenticados com role: "node" e client.mode: "node" podem usar o protocolo de Node N-1 (atualmente v3). Sondas leves de reinicialização usam a mesma janela N-1. Autenticação de dispositivos, pareamento, escopos, política de comandos e aprovações de execução não são alterados por essa janela de compatibilidade. Recursos e comandos de Node pertencentes a plugins são retidos até que o Node seja atualizado para o protocolo atual, pois suas superfícies hospedadas não fazem parte do contrato N-1.
• Esquemas e modelos são gerados a partir de definições do TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Constantes do cliente

A implementação de referência do cliente fica em packages/gateway-client/src/ (o OpenClaw a encapsula por meio da fachada fina src/gateway/client.ts). Esses padrões são estáveis em todo o protocolo v4 e constituem a linha de base esperada para clientes de terceiros.

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

O cliente de referência permite que solicitações finitas controlem seu prazo configurado quando todas as solicitações pendentes têm um. Uma solicitação expectFinal sem um timeoutMs finito, qualquer solicitação com timeoutMs: null ou uma combinação de solicitações finitas e ilimitadas mantém o watchdog de tick ativo. Se eventos e respostas de entrada permanecerem em silêncio além do limite de tempo do tick, o cliente fecha o socket com o código 4000, rejeita todas as solicitações pendentes e se reconecta. Ele não reenvia as solicitações rejeitadas após a reconexão.

Autenticação

• A autenticação do Gateway por segredo compartilhado usa connect.params.auth.token ou connect.params.auth.password, dependendo do gateway.auth.mode configurado ("none" | "token" | "password" | "trusted-proxy").
• Modos que incluem identidade, como Tailscale Serve (gateway.auth.allowTailscale: true) ou gateway.auth.mode: "trusted-proxy" fora de loopback, satisfazem a verificação de autenticação da conexão por meio dos cabeçalhos da solicitação, em vez de connect.params.auth.*.
• O gateway.auth.mode: "none" em entrada privada ignora completamente a autenticação da conexão por segredo compartilhado; não exponha esse modo em entradas públicas/não confiáveis.
• Após o pareamento, o Gateway emite um token de dispositivo com escopo correspondente à função + aos escopos da conexão, retornado em hello-ok.auth.deviceToken. Os clientes devem persistir esse token após qualquer conexão bem-sucedida.
• Ao se reconectar com esse token de dispositivo armazenado, o conjunto de escopos aprovados armazenado para esse token também deve ser reutilizado. Isso preserva o acesso de leitura/sondagem/status já concedido e evita que as reconexões sejam silenciosamente reduzidas a um escopo implícito mais restrito, exclusivo de administrador.
• Montagem da autenticação de conexão no lado do cliente (selectConnectAuth em packages/gateway-client/src/client.ts):
  • auth.password é independente e sempre é encaminhado quando definido.
  • auth.token é preenchido na seguinte ordem de prioridade: primeiro o token compartilhado explícito, depois um deviceToken explícito e, por fim, um token armazenado por dispositivo (indexado por deviceId + role).
  • auth.bootstrapToken é enviado somente quando nenhuma das opções acima definiu auth.token. Um token compartilhado ou qualquer token de dispositivo definido impede seu envio.
  • A promoção automática de um token de dispositivo armazenado na única nova tentativa de AUTH_TOKEN_MISMATCH é restrita apenas a endpoints confiáveis: loopback ou wss:// com um tlsFingerprint fixado. Um wss:// público sem fixação não se qualifica.
• O bootstrap integrado por código de configuração retorna o hello-ok.auth.deviceToken do Node principal, além de 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 nativas da configuração do Talk, mas exclui os escopos de alteração de pareamento e operator.admin.
• Enquanto um bootstrap por código de configuração que não seja de linha de base aguarda aprovação, os detalhes de PAIRING_REQUIRED incluem recommendedNextStep: "wait_then_retry", retryable: true e pauseReconnect: false. Continue se 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 tiver usado autenticação de bootstrap em um transporte confiável, como wss:// ou pareamento por loopback/local.
• Se um cliente fornecer um deviceToken explícito ou scopes explícitos, o conjunto de escopos solicitado pelo chamador continuará sendo a fonte de autoridade; os escopos em cache só serão reutilizados quando o cliente estiver reutilizando o token armazenado por dispositivo.
• Os tokens de dispositivo podem ser rotacionados/revogados por meio de device.token.rotate e device.token.revoke (requer operator.pairing). Rotacionar ou revogar um Node ou outra função que não seja de operador também requer operator.admin.
• device.token.rotate retorna metadados da rotação. Ele reproduz o token portador substituto somente para chamadas do mesmo dispositivo já autenticadas com esse token de dispositivo, permitindo que clientes que usam apenas token persistam o substituto antes de se reconectarem. Rotações compartilhadas/de administrador não reproduzem o token portador.
• A emissão, a rotação e a revogação de tokens permanecem limitadas ao conjunto de funções aprovado registrado na entrada de pareamento desse dispositivo; uma alteração de token não pode expandir nem selecionar 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 é limitado ao próprio dispositivo, a menos que o chamador também tenha operator.admin: chamadores que não sejam administradores só podem gerenciar o token de operador da própria entrada de dispositivo. O gerenciamento de tokens de Node e de outras funções que não sejam de operador é exclusivo de administradores, 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 que não sejam administradores não podem rotacionar nem revogar um token de operador com escopo mais amplo do que o que já possuem.
• Falhas de autenticação incluem error.details.code, além de orientações de recuperação:
  • error.details.canRetryWithDeviceToken (booleano)
  • error.details.recommendedNextStep: um entre retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• Comportamento do cliente para AUTH_TOKEN_MISMATCH:
  • Clientes confiáveis podem realizar uma única nova tentativa limitada com um token por dispositivo em cache.
  • Se essa nova tentativa falhar, interrompa os ciclos de reconexão automática e apresente orientações de ação ao operador.
• AUTH_SCOPE_MISMATCH significa que o token do dispositivo foi reconhecido, mas não abrange a função/os escopos solicitados. Não apresente isso como um token inválido; solicite ao operador que refaça o pareamento ou aprove o contrato de escopo mais restrito/amplo.

Identidade e pareamento do dispositivo

• Os Nodes devem incluir uma identidade de dispositivo estável (device.id) derivada da impressão digital de um par de chaves.
• Os Gateways emitem tokens por dispositivo + função.
• Aprovações de pareamento são necessárias para novos IDs de dispositivo, a menos que a aprovação automática local esteja habilitada.
• A aprovação automática de pareamento se concentra em conexões diretas por loopback local.
• O OpenClaw também tem um caminho restrito de autoconexão local ao backend/contêiner para fluxos auxiliares confiáveis por segredo compartilhado.
• Conexões da tailnet ou LAN no mesmo host ainda são tratadas como remotas para fins de pareamento e exigem aprovação.
• Normalmente, os clientes WS incluem a 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 HTTP insegura somente em localhost.
  • autenticação bem-sucedida da Control UI do operador com gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (medida emergencial, redução severa da segurança).
  • RPCs de backend por loopback direto do gateway-client no caminho auxiliar interno reservado.
• Omitir a identidade do dispositivo tem consequências para os escopos. Quando uma conexão de operador sem dispositivo é permitida por um caminho de confiança explícito, o OpenClaw ainda redefine 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 emergencial de preservação de escopo da Control UI. Ele não concede escopos a clientes WebSocket arbitrários de backend personalizado ou com formato de CLI.
• O caminho auxiliar reservado de backend do gateway-client por loopback direto preserva escopos somente para RPCs internos do plano de controle local; IDs de backend personalizados não recebem essa exceção.
• Todas as conexões devem assinar o nonce connect.challenge fornecido pelo servidor.

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

Para clientes legados que ainda usam o comportamento de assinatura anterior ao desafio, connect 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 o conteúdo v2 que inclui o nonce do servidor.
• Envie o mesmo nonce em connect.params.device.nonce.
• O conteúdo de assinatura preferencial é v3 (buildDeviceAuthPayloadV3 em packages/gateway-client/src/device-auth.ts), que vincula platform e deviceFamily, além dos campos de dispositivo/cliente/função/escopos/token/nonce.
• Assinaturas v2 legadas continuam sendo aceitas por compatibilidade, mas a fixação dos metadados do dispositivo pareado ainda controla a política de comandos na reconexão.

TLS e fixação

• TLS é compatível com conexões WS (configuração gateway.tls).
• Opcionalmente, os clientes podem fixar a impressão digital do certificado do Gateway por meio de gateway.remote.tlsFingerprint ou da opção de CLI --tls-fingerprint.

Escopo

Este protocolo expõe a API completa do Gateway: status, canais, modelos, chat, agente, sessões, nós, aprovações e muito mais. A superfície exata é definida pelos esquemas TypeBox reexportados de packages/gateway-protocol/src/schema.ts.

Relacionados

• Protocolo de ponte
• Runbook do Gateway