Skip to main content

​
Runbook do serviço Gateway

Use esta página para a inicialização do dia 1 e as operações do dia 2 do serviço Gateway.

Deep troubleshooting

Diagnósticos orientados por sintomas com sequências exatas de comandos e assinaturas de logs.

Configuration

Guia de configuração orientado a tarefas + referência completa de configuração.

​
Inicialização local em 5 minutos

1

Start the Gateway

2

Verify service health

Linha de base saudável: Runtime: running e RPC probe: ok.
3

Validate channel readiness

O recarregamento de configuração do Gateway monitora o caminho do arquivo de configuração ativo (resolvido a partir dos padrões de perfil/estado ou OPENCLAW_CONFIG_PATH quando definido). Modo padrão: gateway.reload.mode="hybrid" (aplica mudanças seguras a quente, reinicia em críticas).

​
Modelo de runtime

  • Um processo sempre ativo para roteamento, plano de controle e conexões de canal.
  • Multiplexação em porta única.
    • Controle/RPC via WebSocket
    • OpenResponses (HTTP): /v1/responses.
    • Interface de controle e hooks
  • Modo de bind padrão: loopback.
  • A autenticação do Gateway é exigida por padrão: defina gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN) ou gateway.auth.password.

​
Precedência de porta e bind

​
Modos de hot reload

​
Conjunto de comandos do operador

​
Acesso remoto

Tailscale/VPN é preferido; caso contrário, túnel SSH: Fallback: túnel SSH.
Os clientes então se conectam a ws://127.0.0.1:18789 através do túnel.
Se um token estiver configurado, os clientes devem incluí-lo em connect.params.auth.token mesmo através do túnel.
Veja: Remote Gateway, Authentication, Tailscale.

​
Supervisão e ciclo de vida do serviço

Use execuções supervisionadas para confiabilidade semelhante à de produção.
Os rótulos do LaunchAgent são ai.openclaw.gateway (padrão) ou ai.openclaw.<profile> (perfil nomeado). openclaw doctor audita e corrige desvios na configuração do serviço.

​
Múltiplos gateways (mesmo host)

Geralmente desnecessário: um Gateway pode atender a vários canais de mensagens e agentes. Use múltiplos Gateways apenas para redundância ou isolamento rigoroso (ex: bot de resgate). Checklist por instância:
  • gateway.port exclusivo
  • OPENCLAW_CONFIG_PATH exclusivo
  • OPENCLAW_STATE_DIR exclusivo
  • agents.defaults.workspace exclusivo
Exemplo:
Veja Múltiplos gateways.

​
Perfil Dev (--dev)

Os padrões incluem estado/configuração isolados e porta base do gateway 19001.

​
Protocolo (visão do operador)

  • O primeiro frame do cliente deve ser connect.
  • O Gateway retorna um snapshot hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
  • Requisições: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Eventos comuns: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
As execuções do agente têm duas etapas:
  1. Ack de aceitação imediato (status:"accepted")
  2. As respostas agent são em duas etapas: primeiro res ack {runId,status:"accepted"}, depois um res {runId,status:"ok"|"error",summary} final após o término da execução; a saída em streaming chega como event:"agent".
Documentação completa: Protocolo do Gateway e Protocolo Bridge (legado).

​
Verificações operacionais

​
Vitalidade

  • Abra o WS e envie connect.
  • Espere a resposta hello-ok com o snapshot.

​
Prontidão

​
Recuperação de lacunas

Os eventos não são reproduzidos. Em caso de lacunas na sequência, atualize o estado (health, system-presence) antes de continuar.

​
Assinaturas comuns de falha

Para escadas completas de diagnóstico, use Gateway Troubleshooting.

​
Garantias de segurança

  • Clientes do protocolo Gateway falham rapidamente quando o Gateway está indisponível (sem fallback implícito para canal direto).
  • Frames iniciais não-connect ou JSON malformado são rejeitados e o socket é fechado.
  • Desligamento gracioso: emite evento shutdown antes de fechar; os clientes devem lidar com fechamento + reconexão.
Relacionado: