Protocolo do 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.

​

Transporte

• WebSocket, quadros de texto com cargas JSON.
• O primeiro quadro deve ser uma requisição connect.
• Quadros antes da 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 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 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údos de anexos, corpo bruto do quadro, tokens, cookies ou valores secretos.

​

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

​

Exemplo de nó

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

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

​

Papéis + escopos

​

Papéis

• operator = cliente do plano de controle (CLI/UI/automação).
• node = host de capacidade (camera/screen/canvas/system.run).

​

Escopos (operador)

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

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

​

Caps/comandos/permissões (nó)

• caps: categorias de capacidade de alto nível, como camera, canvas, screen, location, voice e talk.
• commands: allowlist de comandos para invocação.
• permissions: alternâncias granulares (por exemplo, screen.record, camera.capture).

​

Presença

• system-presence retorna entradas indexadas por identidade de dispositivo.
• Entradas de presença incluem deviceId, roles e scopes para que UIs possam mostrar uma única linha por dispositivo mesmo quando ele se conecta como operator e node.
• node.list inclui campos opcionais lastSeenAtMs e lastSeenReason. Nós conectados relatam o horário da conexão atual como lastSeenAtMs com motivo connect; nós pareados também podem relatar 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

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

​

Escopo de eventos de broadcast

• Quadros de chat, agente e resultado de ferramenta (incluindo eventos agent em streaming e resultados de chamadas de ferramenta) exigem pelo menos operator.read. Sessões sem operator.read ignoram esses quadros completamente.
• Broadcasts plugin.* definidos por plugin são bloqueados para operator.write ou operator.admin, dependendo de como o plugin os registrou.
• Eventos de status e transporte (heartbeat, presence, tick, ciclo de vida de conexão/desconexão etc.) permanecem sem restrição para que a integridade do transporte permaneça observável para toda sessão autenticada.
• Famílias de eventos de broadcast desconhecidas são bloqueadas por escopo por padrão (falha fechada), a menos que um handler registrado as relaxe explicitamente.

​

Famílias comuns de métodos RPC

​

Famílias comuns de eventos

• chat: atualizações de chat da UI, como chat.inject e outros eventos de chat apenas de transcrição.
• session.message e session.tool: atualizações de transcrição/fluxo de eventos para uma sessão assinada.
• sessions.changed: índice ou metadados da sessão alterados.
• presence: atualizações de snapshot de presença do sistema.
• tick: evento periódico de keepalive / vivacidade.
• health: atualização de snapshot de integridade do Gateway.
• heartbeat: atualização do fluxo de eventos de Heartbeat.
• cron: evento de alteração de execução/tarefa de Cron.
• shutdown: notificação de encerramento do Gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida de 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 de dispositivo pareado.
• voicewake.changed: configuração de disparo por palavra de ativação alterada.
• exec.approval.requested / exec.approval.resolved: ciclo de vida de aprovação de execução.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de aprovação de Plugin.

​

Métodos auxiliares de Node

• Nodes 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

• tasks.list requer operator.read.
  • Parâmetros: status opcional ("queued", "running", "completed", "failed", "cancelled" ou "timed_out") ou uma matriz desses status, agentId opcional, sessionKey opcional, limit opcional de 1 a 500 e string cursor opcional.
  • Resultado: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get requer 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 requer 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.

​

Métodos auxiliares de operador

• Operadores podem chamar commands.list (operator.read) para buscar o inventário de comandos de runtime de um agente.
  • agentId é opcional; omita-o para ler o workspace padrão do agente.
  • scope controla qual superfície o name primário mira:
    • text retorna o token de comando de texto primário sem a / inicial
    • native e o caminho padrão both retornam nomes nativos cientes do provedor quando disponíveis
  • textAliases carrega aliases de barra exatos, como /model e /m.
  • nativeName carrega o nome de comando nativo ciente do provedor quando existe.
  • provider é opcional e afeta apenas a nomeação nativa, além da 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 de runtime para 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 runtime para uma sessão.
  • sessionKey é obrigatório.
  • O gateway deriva o contexto de runtime confiável da sessão no lado do servidor, em vez de aceitar autenticação ou contexto de entrega fornecidos pelo chamador.
  • A resposta é escopada à sessão e reflete o que a conversa ativa pode usar agora, incluindo ferramentas de core, Plugin e canal.
• Operadores podem chamar tools.invoke (operator.write) para invocar uma ferramenta disponível por meio do 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 deve corresponder a agentId.
  • 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 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 secretos brutos.
• 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 Skills 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 }) anexa bytes no offset 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 Skill enviados são arquivos zip que contêm uma raiz SKILL.md. O nome do diretório interno do arquivo nunca seleciona o destino de 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, dangerouslyForceUnsafeInstall?, timeoutMs? } executa uma ação metadata.openclaw.install declarada no host do Gateway.
• 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 de configuração aplica patches a valores skills.entries.<skillKey>, como enabled, apiKey e env.

​

Visualizações de models.list

• Omitido ou "default": comportamento atual de runtime. 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 em tamanho de seletor. Se agents.defaults.models estiver configurado, ele ainda prevalece, incluindo descoberta escopada por provedor para entradas provider/*. Sem uma allowlist, a resposta usa entradas explícitas models.providers.*.models, recorrendo ao catálogo completo somente quando não há linhas de modelo configuradas.
• "all": catálogo completo do Gateway, contornando agents.defaults.models. Use isso para diagnósticos e UIs de descoberta, não para seletores normais de modelo.

​

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 chamando exec.approval.resolve (requer o 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 node.invoke system.run reutilizam esse systemRunPlan canônico como o contexto autoritativo de comando/cwd/sessão.
• Se um chamador mutar 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 mutado.

​

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: 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 entregável externa pode 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 src/gateway/protocol/version.ts.
• Clientes enviam minProtocol + maxProtocol; o servidor rejeita intervalos que não incluem seu protocolo atual. Clientes nativos usam um limite inferior v3 para que clientes v4 aditivos ainda possam alcançar gateways v3.
• Esquemas + modelos são gerados a partir de definições TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Constantes de cliente

​

Autenticação

• A autenticação de 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" fora de loopback atendem à verificação de autenticação de conexão a partir dos cabeçalhos da solicitação em vez de connect.params.auth.*.
• gateway.auth.mode: "none" em ingresso privado ignora totalmente a autenticação de conexão 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 ao papel + escopos da conexão. 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 aprovado armazenado para esse token. Isso preserva acesso de leitura/sondagem/status que já foi concedido e evita reduzir silenciosamente as reconexões a um escopo implícito mais restrito, apenas de administrador.
• Montagem de autenticação de conexão 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 por dispositivo armazenado (chaveado por deviceId + role).
  • auth.bootstrapToken é enviado somente quando nenhuma das opções 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 de AUTH_TOKEN_MISMATCH é restrita a endpoints confiáveis — loopback, ou wss:// com um tlsFingerprint fixado. wss:// público sem fixação não se qualifica.
• Entradas adicionais de hello-ok.auth.deviceTokens são tokens de repasse de bootstrap. Persista-as somente quando a conexão usar autenticação de bootstrap em um transporte confiável como wss:// ou pareamento local/loopback.
• Se um cliente fornecer 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 por dispositivo armazenado.
• Tokens de dispositivo podem ser rotacionados/revogados via device.token.rotate e device.token.revoke (requer escopo operator.pairing).
• device.token.rotate retorna metadados de rotação. Ele ecoa o token portador substituto somente para chamadas do mesmo dispositivo que já estão autenticadas com esse token de dispositivo, para que clientes apenas com token possam persistir o substituto antes de reconectar. Rotações compartilhadas/de administrador não ecoam o token portador.
• Emissão, rotação e revogação de tokens permanecem limitadas ao conjunto de papéis aprovado registrado na entrada de pareamento desse dispositivo; a mutação de token não pode expandir nem mirar um papel 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 remover/revogar/rotacionar somente sua própria entrada de dispositivo.
• device.token.rotate e device.token.revoke também verificam o conjunto de escopos do token de operador de destino contra os 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 por dispositivo em cache.
  • Se essa nova tentativa falhar, os clientes devem parar loops de reconexão automática e apresentar orientação de ação ao operador.
• AUTH_SCOPE_MISMATCH significa que o token de dispositivo foi reconhecido, mas não cobre o papel/escopos solicitados. Os clientes não devem apresentar isso como um token inválido; solicite que o operador faça novo pareamento ou aprove o contrato de escopo mais restrito/mais amplo.

​

Identidade do dispositivo + pareamento

• Nós 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 + papel.
• 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 é centrada em conexões diretas de local loopback.
• OpenClaw também tem um caminho restrito de autoconexão local de backend/contêiner para fluxos auxiliares confiáveis com 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 + nó). As únicas exceções de operador sem dispositivo são caminhos de confiança explícitos:
  • gateway.controlUi.allowInsecureAuth=true para compatibilidade HTTP insegura apenas em localhost.
  • autenticação de operador bem-sucedida da UI de controle com gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (recurso de emergência, rebaixamento severo de segurança).
  • RPCs de backend gateway-client por loopback direto autenticados com o token/senha compartilhado do Gateway.
• Todas as conexões devem assinar o nonce connect.challenge fornecido pelo servidor.

​

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

• Sempre aguarde connect.challenge.
• Assine o payload v2 que inclui o nonce do servidor.
• Envie o mesmo nonce em connect.params.device.nonce.
• O payload de assinatura preferencial é v3, que vincula platform e deviceFamily além dos campos de dispositivo/cliente/papel/escopos/token/nonce.
• Assinaturas legadas v2 continuam aceitas por 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.
• Clientes podem opcionalmente fixar a impressão digital do certificado do Gateway (veja a configuração gateway.tls mais gateway.remote.tlsFingerprint ou a CLI --tls-fingerprint).

​

Escopo

​

Relacionados

• Protocolo de ponte
• Runbook do Gateway