Manual operacional do Gateway

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

Inicialização local em 5 minutos

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Modelo de runtime

• Um processo sempre ativo para roteamento, plano de controle e conexões de canais.
• Porta única multiplexada para:
  • Controle/RPC por WebSocket
  • APIs HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Rotas HTTP de Plugin, como /api/v1/admin/rpc opcional
  • UI de controle e hooks
• Modo de bind padrão: loopback.
• A autenticação é exigida 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 não loopback podem usar gateway.auth.mode: "trusted-proxy".

Endpoints compatíveis com OpenAI

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

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

Por que esse conjunto importa:

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

Nota de planejamento:

• /v1/models é orientado a agentes: retorna openclaw, openclaw/default e openclaw/<agentId>.
• openclaw/default é o alias estável que sempre mapeia para o agente padrão configurado.
• Use x-openclaw-model quando quiser uma substituição de provedor/modelo de backend; caso contrário, a configuração normal de modelo e embeddings do agente selecionado permanece no controle.

Tudo isso é executado na porta principal do Gateway e usa o mesmo limite de autenticação de operador confiável do restante da API HTTP do Gateway.

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

Precedência de porta e bind

Serviços de Gateway instalados registram o --port resolvido nos metadados do supervisor. Depois de 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 o mesmo bind efetivos ao semear origens locais da UI de controle para binds não loopback. Por exemplo, --bind lan --port 3000 semeia http://localhost:3000 e http://127.0.0.1:3000 antes da execução da validação em runtime. Adicione explicitamente quaisquer origens de navegador remoto, como URLs de proxy HTTPS, a gateway.controlUi.allowedOrigins.

Modos de recarregamento a quente

Conjunto de comandos do operador

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

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 deseja intencionalmente 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 imprimir dicas de limpeza quando instalações antigas de launchd/systemd/schtasks ainda estiverem presentes.
• gateway probe pode avisar sobre multiple reachable gateway identities quando gateways distintos respondem, ou quando o OpenClaw não consegue provar 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 é um Gateway com vários transportes, mesmo quando as portas de transporte são diferentes.
• Se isso for intencional, isole portas, configuração/estado e raízes de workspace por Gateway.

Checklist 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

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

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

Depois conecte 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 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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=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

Caminho rápido do perfil dev

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

Os padrões incluem estado/configuração isolados e 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 o snapshot hello-ok (presence, health, stateVersion, uptimeMs, limites/política).
• hello-ok.features.methods / events são uma lista conservadora de descoberta, não um despejo gerado de todas as rotas auxiliares chamáveis.
• Solicitações: req(method, params) → res(ok/payload|error).
• Eventos comuns incluem connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, eventos de ciclo de vida de pareamento/aprovação, e shutdown.

Execuções de agentes têm duas etapas:

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

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

Verificações operacionais

Vitalidade

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

Prontidão

openclaw gateway statusopenclaw channels status --probeopenclaw health

Recuperação de lacunas

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

Assinaturas comuns de falha

Para escadas completas de diagnóstico, use Solução de problemas do Gateway.

Garantias de segurança

• Clientes do protocolo Gateway falham rapidamente quando o Gateway está indisponível (sem fallback implícito para canal direto).
• Primeiros frames inválidos/sem conexão são rejeitados e fechados.
• O encerramento gracioso emite o evento shutdown antes de fechar o socket.

Relacionado:

• Solução de problemas
• Processo em segundo plano
• Configuração
• Saúde
• Doctor
• Autenticação

Relacionado

• Configuração
• Solução de problemas do Gateway
• Acesso remoto
• Gerenciamento de segredos