English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Gateway

Manual de operações do Gateway

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

Solução de problemas aprofundada

Diagnósticos orientados por sintoma com sequências exatas de comandos e assinaturas de logs.
Configuração

Guia de configuração orientado por tarefa + referência completa de configuração.
Gerenciamento de segredos

Contrato SecretRef, comportamento de snapshot em runtime 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

  • Inicie o Gateway

    bash
    OmeniaClaw gateway --port 18789# debug/trace mirrored to stdioOmeniaClaw gateway --port 18789 --verbose# force-kill listener on selected port, then startOmeniaClaw gateway --force

  • Verifique a integridade do serviço

    bash
    OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --follow

    Linha de base saudável: Runtime: running, Connectivity probe: ok e Capability: ... que corresponde ao que você espera. Use OmeniaClaw gateway status --require-rpc quando precisar de comprovação de RPC com escopo de leitura, não apenas alcançabilidade.

  • Valide a prontidão do canal

    bash
    OmeniaClaw channels status --probe

    Com um Gateway alcançável, isso executa probes de canais por conta ao vivo e auditorias opcionais. Se o Gateway estiver inalcançável, a CLI recorre a resumos de canais somente de configuração em vez da saída de probe ao vivo.

    • Modelo de runtime

    • Um processo sempre ativo para roteamento, plano de controle e conexões de canais.
    • Porta única multiplexada para:
      • Controle/RPC via 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.
    • A autenticação é exigida por padrão. Configurações com segredo compartilhado usam gateway.auth.token / gateway.auth.password (ou OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_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 OmeniaClaw 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 faz primeiro o probe de /v1/models.
    • 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: ele retorna OmeniaClaw, OmeniaClaw/default e OmeniaClaw/<agentId>.
    • OmeniaClaw/default é o alias estável que sempre aponta para o agente padrão configurado.
    • Use x-OmeniaClaw-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 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

    Configuração Ordem de resolução
    Porta do Gateway --port → OmeniaClaw_GATEWAY_PORT → gateway.port → 18789
    Modo de bind CLI/sobrescrita → gateway.bind → loopback

    Serviços de Gateway instalados registram o --port resolvido nos metadados do supervisor. Depois de alterar gateway.port, execute OmeniaClaw doctor --fix ou OmeniaClaw gateway install --force para que launchd/systemd/schtasks inicie o processo na nova porta.

    A inicialização do Gateway usa a mesma porta efetiva e o mesmo bind quando semeia 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 de runtime. Adicione explicitamente quaisquer origens de navegador remoto, como URLs de proxy HTTPS, a gateway.controlUi.allowedOrigins.

    Modos de recarregamento a quente

    gateway.reload.mode Comportamento
    off Sem recarregamento de configuração
    hot Aplica somente alterações seguras a quente
    restart Reinicia em alterações que exigem recarregamento
    hybrid (padrão) Aplica a quente quando seguro, reinicia quando necessário

    Conjunto de comandos do operador

    bash
    OmeniaClaw gateway statusOmeniaClaw gateway status --deep   # adds a system-level service scanOmeniaClaw gateway status --jsonOmeniaClaw gateway installOmeniaClaw gateway restartOmeniaClaw gateway stopOmeniaClaw secrets reloadOmeniaClaw logs --followOmeniaClaw doctor

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

    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 intencionalmente isolamento ou um bot de resgate.

    Verificações úteis:

    bash
    OmeniaClaw gateway status --deepOmeniaClaw 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 obsoletas de launchd/systemd/schtasks ainda existirem.
    • gateway probe pode avisar sobre multiple reachable gateways quando mais de um destino responde.
    • Se isso for intencional, isole portas, configuração/estado e raízes de workspace por Gateway.

    Checklist por instância:

    • gateway.port único
    • OmeniaClaw_CONFIG_PATH único
    • OmeniaClaw_STATE_DIR único
    • agents.defaults.workspace único

    Exemplo:

    bash
    OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/a.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-a OmeniaClaw gateway --port 19001OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/b.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-b OmeniaClaw gateway --port 19002

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

    Acesso remoto

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

    bash
    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.

    macOS (launchd)

    bash
    OmeniaClaw gateway installOmeniaClaw gateway statusOmeniaClaw gateway restartOmeniaClaw gateway stop

    Use OmeniaClaw gateway restart para reinicializações. Não encadeie OmeniaClaw gateway stop e OmeniaClaw gateway start como substituto de reinicialização.

    No macOS, gateway stop usa launchctl bootout por padrão — isso remove o LaunchAgent da sessão de boot atual sem persistir uma desativação, então a recuperação automática por KeepAlive ainda funciona após falhas inesperadas e gateway start reativa tudo de forma limpa. Para suprimir persistentemente o respawn automático entre reinicializações, passe --disable: OmeniaClaw gateway stop --disable.

    Os rótulos do LaunchAgent são ai.OmeniaClaw.gateway (padrão) ou ai.OmeniaClaw.<profile> (perfil nomeado). OmeniaClaw doctor audita e repara desvios de configuração do serviço.

    Linux (usuário systemd)

    bash
    OmeniaClaw gateway installsystemctl --user enable --now OmeniaClaw-gateway[-<profile>].serviceOmeniaClaw gateway status

    Para persistência após logout, habilite lingering:

    bash
    sudo loginctl enable-linger <user>

    Exemplo manual de unidade de usuário quando você precisa de um caminho de instalação personalizado:

    ini
    [Unit]Description=OmeniaClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/OmeniaClaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

    Windows (nativo)

    powershell
    OmeniaClaw gateway installOmeniaClaw gateway status --jsonOmeniaClaw gateway restartOmeniaClaw gateway stop

    A inicialização gerenciada nativa do Windows usa uma Tarefa Agendada chamada OmeniaClaw Gateway (ou OmeniaClaw Gateway (<profile>) para perfis nomeados). Se a criação da Tarefa Agendada for negada, o OmeniaClaw recorre a um launcher por usuário na pasta de Inicialização que aponta para gateway.cmd dentro do diretório de estado.

    Linux (serviço do sistema)

    Use uma unidade do sistema para hosts multiusuário/sempre ativos.

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

    Use o mesmo corpo de serviço da unidade de usuário, mas instale-o em /etc/systemd/system/OmeniaClaw-gateway[-<profile>].service e ajuste ExecStart= se o binário OmeniaClaw estiver em outro lugar.

    Não permita também que OmeniaClaw doctor --fix instale um serviço de Gateway em nível de usuário para o mesmo perfil/porta. O doctor recusa essa instalação automática quando encontra um serviço de Gateway do OmeniaClaw em nível de sistema; use OmeniaClaw_SERVICE_REPAIR_POLICY=external quando a unidade do sistema for dona do ciclo de vida.

    Caminho rápido do perfil de desenvolvimento

    bash
    OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --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.
    • Requisiçõ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 agentes têm duas etapas:

    1. Ack imediato aceito (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

    Liveness

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

    Prontidão

    bash
    OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw 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

    Assinatura Problema provável
    refusing to bind gateway ... without auth Bind não-loopback sem um caminho de autenticação do Gateway válido
    another gateway instance is already listening / EADDRINUSE Conflito de porta
    Gateway start blocked: set gateway.mode=local Configuração definida para modo remoto, ou o carimbo de modo local está ausente de uma configuração danificada
    unauthorized during connect Incompatibilidade de autenticação entre o cliente e o Gateway

    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 do fechamento do socket.

    Relacionado:

    Relacionado

    Was this useful?
    On this page

    On this page