Runbook do Gateway

Use esta página para a inicialização do serviço Gateway no primeiro dia e para as operações a partir do segundo dia.

Inicialização local em 5 minutos

openclaw gateway --port 18789# depuração/rastreamento espelhados na E/S padrãoopenclaw gateway --port 18789 --verbose# encerra à força o processo que escuta na porta selecionada e iniciaopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Modelo de execução

• Um processo sempre ativo para roteamento, plano de controle e conexões de canais.
• Uma única porta multiplexada para:
  • Controle/RPC via WebSocket
  • APIs HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Rotas HTTP de Plugins, como a rota opcional /api/v1/admin/rpc
  • Interface de controle e hooks
• Modo de vinculação padrão: loopback. Dentro de um ambiente de contêiner detectado, o padrão efetivo é auto (resolvido como 0.0.0.0 para encaminhamento de portas), exceto quando o serve/funnel do Tailscale está ativo, o que sempre força loopback.
• A autenticação é obrigatória por padrão. Configurações com segredo compartilhado usam gateway.auth.token / gateway.auth.password (ou OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), e configurações de proxy reverso fora de loopback podem usar gateway.auth.mode: "trusted-proxy".

Endpoints compatíveis com OpenAI

A superfície de compatibilidade de maior impacto do OpenClaw:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Por que esse conjunto é importante:

• A maioria das integrações com Open WebUI, LobeChat e LibreChat consulta primeiro /v1/models.
• Muitos pipelines de RAG e memória esperam /v1/embeddings.
• Clientes nativos para agentes preferem cada vez mais /v1/responses.

/v1/models prioriza agentes: retorna openclaw, openclaw/default e openclaw/<agentId> para cada agente configurado. openclaw/default é o alias estável que sempre corresponde ao agente padrão configurado. Envie x-openclaw-model quando quiser substituir o provedor/modelo de backend; caso contrário, o modelo normal e a configuração de embeddings do agente selecionado permanecem no controle.

Todos esses endpoints são executados na porta principal do Gateway e usam o mesmo limite de autenticação de operador confiável que o restante da API HTTP do Gateway.

O RPC HTTP administrativo (POST /api/v1/admin/rpc) é uma rota de Plugin separada e desativada por padrão para ferramentas do host que não podem usar RPC via WebSocket. Consulte RPC HTTP administrativo.

Precedência de porta e vinculação

Os serviços de Gateway instalados registram o --port resolvido nos metadados do supervisor. Após alterar gateway.port, execute openclaw doctor --fix ou openclaw gateway install --force para que launchd/systemd/schtasks inicie o processo na nova porta.

A inicialização do Gateway usa a mesma porta e vinculação efetivas ao preencher as origens locais da interface de controle para vinculações fora de loopback. Por exemplo, --bind lan --port 3000 adiciona http://localhost:3000 e http://127.0.0.1:3000 antes da validação em tempo de execução. Adicione explicitamente a gateway.controlUi.allowedOrigins quaisquer origens de navegadores remotos, como URLs de proxy HTTPS.

Modos de recarregamento dinâmico

Conjunto de comandos do operador

openclaw gateway statusopenclaw gateway status --deep   # adiciona uma varredura de serviços no nível do sistemaopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep serve para descoberta adicional de serviços (LaunchDaemons/unidades de sistema do systemd/schtasks), não para uma sondagem mais profunda da integridade do RPC.

Vários Gateways (mesmo host)

A maioria das instalações deve executar um Gateway por máquina. Um único Gateway pode hospedar vários agentes e canais. Você só precisa de vários Gateways quando quiser deliberadamente isolamento ou um bot de resgate.

Verificações úteis:

openclaw gateway status --deepopenclaw gateway probe

O que esperar:

• gateway status --deep pode relatar Other gateway-like services detected (best effort) e exibir dicas de limpeza quando ainda houver instalações obsoletas de launchd/systemd/schtasks.
• gateway probe pode alertar sobre multiple reachable gateway identities quando Gateways distintos respondem ou quando o OpenClaw não consegue comprovar que os destinos acessíveis são o mesmo Gateway. Um túnel SSH, uma URL de proxy ou uma URL remota configurada para o mesmo Gateway representa um único Gateway com vários transportes, mesmo quando as portas de transporte são diferentes.
• Se isso for intencional, isole as portas, a configuração/estado e as raízes dos espaços de trabalho de cada Gateway.

Lista de verificação por instância:

• gateway.port exclusivo
• OPENCLAW_CONFIG_PATH exclusivo
• OPENCLAW_STATE_DIR exclusivo
• agents.defaults.workspace exclusivo

Exemplo:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Configuração detalhada: /gateway/multiple-gateways.

Acesso remoto

Preferencial: Tailscale/VPN. Alternativa: túnel SSH.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Em seguida, conecte os clientes localmente a ws://127.0.0.1:18789.

Consulte: Gateway remoto, Autenticação, Tailscale.

Supervisão e ciclo de vida do serviço

Use execuções supervisionadas para obter confiabilidade semelhante à de produção.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=Gateway do OpenClawAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

Erros de configuração inválida encerram com o código 78. As unidades systemd do Linux usam RestartPreventExitStatus=78 para interromper as novas tentativas de inicialização até que a configuração seja corrigida. O launchd e o Agendador de Tarefas do Windows não têm uma regra equivalente de interrupção por código de saída; portanto, o Gateway também persiste o histórico de inicializações rápidas sem encerramento limpo e impede o início automático das contas de canais/provedores após falhas repetidas de inicialização. Nesse modo de segurança, o plano de controle ainda é iniciado para inspeção e reparo, os recarregamentos dinâmicos da configuração e secrets.reload recusam reinicializações automáticas de canais, e uma solicitação explícita do operador para channels.start pode substituir o bloqueio.

Caminho rápido do perfil de desenvolvimento

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

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

Referência rápida do protocolo (visão do operador)

• O primeiro frame do cliente deve ser connect.
• O Gateway retorna um frame hello-ok com um snapshot (presence, health, stateVersion, uptimeMs), além dos limites de policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events são uma lista conservadora de descoberta, não um despejo gerado de todas as rotas auxiliares invocáveis.
• Solicitações: req(method, params) → res(ok/payload|error).
• Eventos comuns incluem connect.challenge, agent, chat, session.message, session.operation, session.tool, o evento opcional session.approval, sessions.changed, presence, tick, health, heartbeat, eventos do ciclo de vida de pareamento/aprovação e shutdown.

As execuções do agente têm duas etapas:

1. Confirmação imediata de aceitação (status:"accepted")
2. Resposta final de conclusão (status:"ok"|"error"), com eventos agent transmitidos entre as duas etapas.

Consulte a documentação completa do protocolo: Protocolo do Gateway.

Verificações operacionais

Atividade

• Abra o WS e envie connect.
• Aguarde uma resposta hello-ok com o snapshot.

Prontidão

openclaw gateway statusopenclaw channels status --probeopenclaw health

Recuperação de lacunas

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

Assinaturas comuns de falha

Para obter sequências completas de diagnóstico, consulte Solução de problemas do Gateway.

Garantias de segurança

• Os clientes do protocolo do Gateway falham imediatamente quando o Gateway está indisponível (sem fallback implícito para canal direto).
• Primeiros frames inválidos ou que não sejam de conexão são rejeitados, e a conexão é encerrada.
• O desligamento normal emite o evento shutdown antes de fechar o socket.

Relacionados

• Configuração
• Solução de problemas do Gateway
• Processo em segundo plano
• Integridade
• Doctor
• Autenticação
• Acesso remoto
• Gerenciamento de segredos