Manual de operações do Gateway

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

# Inicialização local em 5 minutos

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# Modelo de runtime

• Um processo sempre ativo para roteamento, plano de controle e conexões de canal.
• Porta única multiplexada para:
  • Controle/RPC por WebSocket
  • APIs HTTP, compatíveis com OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • UI de controle e hooks
• Modo de bind padrão: loopback.
• 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 fora de loopback podem usar gateway.auth.mode: "trusted-proxy".

# Endpoints compatíveis com OpenAI

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

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

Por que este conjunto importa:

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

Nota de planejamento:

• /v1/models é agent-first: 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.

Todos eles rodam 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.

# Precedência de porta e bind

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 bind efetivos ao semear origens locais da UI de controle para binds fora de loopback. Por exemplo, --bind lan --port 3000 semeia http://localhost:3000 e http://127.0.0.1:3000 antes que a validação de runtime execute. Adicione explicitamente quaisquer origens de navegador remoto, como URLs de proxy HTTPS, a gateway.controlUi.allowedOrigins.

# Modos de recarga a quente

# Conjunto de comandos do operador

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

gateway status --deep é para descoberta extra de serviços (LaunchDaemons/unidades systemd de sistema/schtasks), não uma sondagem RPC de integridade 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 quiser isolamento intencionalmente ou um bot de resgate.

Verificações úteis:

openclaw gateway status --deep
openclaw gateway probe

O que esperar:

• gateway status --deep pode informar Other gateway-like services detected (best effort) e imprimir dicas de limpeza quando instalações obsoletas de launchd/systemd/schtasks ainda existirem.
• gateway probe pode avisar sobre multiple reachable gateways quando mais de um destino responder.
• 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 19001
OPENCLAW_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

Então conecte clientes localmente a ws://127.0.0.1:18789.

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

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

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

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# Caminho rápido do perfil de desenvolvimento

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --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 dump gerado de cada rota auxiliar chamável.
• Solicitações: req(method, params) → res(ok/payload|error).
• Eventos comuns incluem connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, eventos de ciclo de vida de pareamento/aprovação e shutdown.

Execuções de agente 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.

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

# Verificações operacionais

# Atividade

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

# Prontidão

openclaw gateway status
openclaw channels status --probe
openclaw 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 sequências 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/que não são de conexão são rejeitados e fechados.
• O encerramento ordenado emite o evento shutdown antes do fechamento do socket.

Relacionado:

• Solução de problemas
• Processo em segundo plano
• Configuração
• Integridade
• Diagnóstico
• Autenticação

# Relacionados

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