Skip to main content
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.

Solução de problemas aprofundada

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

Configuração

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

Gerenciamento de segredos

Contrato de SecretRef, comportamento do snapshot em tempo de execução e operações de migração/recarregamento.

Contrato do plano de segredos

Regras exatas de destino/caminho de secrets apply e comportamento de perfil de autenticação somente por referência.

​
Inicialização local em 5 minutos

1

Inicie o Gateway

2

Verifique a integridade do serviço

Referência de integridade: Runtime: running, Connectivity probe: ok e uma linha Capability que corresponda ao esperado. Use openclaw gateway status --require-rpc para comprovar o RPC com escopo de leitura, não apenas a acessibilidade.
3

Valide a prontidão dos canais

Com um Gateway acessível, isso executa sondagens ativas por conta nos canais e auditorias opcionais. Se o Gateway estiver inacessível, a CLI recorre a resumos de canais baseados somente na configuração.
O recarregamento da configuração do Gateway monitora o caminho do arquivo de configuração ativo (resolvido pelos padrões de perfil/estado ou por OPENCLAW_CONFIG_PATH, quando definido). O modo padrão é gateway.reload.mode="hybrid". Após o primeiro carregamento bem-sucedido, o processo em execução utiliza o snapshot ativo da configuração na memória; um recarregamento bem-sucedido substitui esse snapshot de forma atômica.

​
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

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:
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:
Configuração detalhada: /gateway/multiple-gateways.

​
Acesso remoto

Preferencial: Tailscale/VPN. Alternativa: túnel SSH.
Em seguida, conecte os clientes localmente a ws://127.0.0.1:18789.
Os túneis SSH não ignoram a autenticação do Gateway. Para autenticação com segredo compartilhado, os clientes ainda devem enviar token/password, mesmo pelo túnel. Para modos que carregam identidade, a solicitação ainda precisa satisfazer esse fluxo de autenticação.
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.
Use openclaw gateway restart para reinicializações. Não encadeie openclaw gateway stop e openclaw gateway start como substituto para uma reinicialização.No macOS, gateway stop usa launchctl bootout por padrão. Isso remove o LaunchAgent da sessão de inicialização atual sem desativá-lo permanentemente; assim, a recuperação automática do KeepAlive continua funcionando após falhas inesperadas, e gateway start o reativa corretamente. Para impedir permanentemente a recriação automática do processo após reinicializações, passe --disable: openclaw gateway stop --disable.Os rótulos do LaunchAgent são ai.openclaw.gateway (padrão) ou ai.openclaw.<profile> (perfil nomeado). openclaw doctor audita e corrige divergências na configuração do serviço.
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

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

​
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