OpenAI Codex — App-Server provider (`codex-app-server`) (Português (Brasil))

1. Arquitetura

┌─ Aplicativo OmniRoute ───────────┐        ┌─ Sidecar codex-app-server ──────────┐
│  CodexAppServerExecutor          │  WS    │  codex app-server                   │
│  ws://codex-app-server:1456 ─────┼───────▶│  --listen ws://0.0.0.0:1456         │
│  (+ token de capacidade)         │  JSON  │  --ws-auth capability-token         │
│                                  │  RPC   │  gerencia sozinho o OAuth da OpenAI │
└──────────────────────────────────┘        │  (~/.codex/auth.json, renovação auto.)│
        │ compartilha (volumes do compose)   └─────────────────────────────────────┘
        ▼
  codex-appserver-token   → o token de capacidade do WS (ambos o montam)
  codex-appserver-home    → ~/.codex (auth.json gravado pelo painel,
                             lido pelo codex app-server do sidecar)

• O sidecar escuta somente na rede interna do compose (ws://codex-app-server:1456), protegido por um token de capacidade. Ele nunca é publicado no host nem na internet.
• O Codex CLI já vem incluído em omniroute:base, portanto não é necessário instalar o codex no host nem na máquina do usuário ao executar o sidecar.

2. Inicialização

# Inicie a stack COM o perfil do sidecar codex app-server:
docker compose --profile base --profile codex-app-server up -d
# (podman: podman compose --profile base --profile codex-app-server up -d)

Na primeira inicialização, o sidecar gera seu token de capacidade do WS (no volume compartilhado codex-appserver-token), e o aplicativo lê o mesmo token por meio de OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE. Não é necessário configurar o token manualmente.

3. Conexão e autenticação

1. No painel, adicione uma conexão para OpenAI Codex (App-Server). Nenhuma chave de API ou token é necessário (é um provedor sem autenticação — o sidecar é responsável pela autenticação).
2. Se o Codex CLI do sidecar ainda não estiver autenticado, a verificação de integridade da conexão informará “em execução, mas não autenticado” (em vez de exibir um erro de autenticação em vermelho). Use Entrar com o ChatGPT: isso executa o fluxo OAuth padrão por dispositivo do Codex no navegador e, em seguida, grava ~/.codex/auth.json no volume compartilhado por meio de Aplicar autenticação (o mesmo login atende tanto ao provedor codex quanto ao codex-app-server).
3. Após a autenticação, a verificação de integridade fica verde (ela verifica tanto /readyz quanto account/read — ou seja, se o serviço está ativo e autenticado), e tudo começa a funcionar.

O painel nunca sobrescreve um ~/.codex/auth.json existente e válido — ele somente grava quando o arquivo está ausente ou quando seu token está desatualizado (um backup é sempre criado).

4. Cenários de implantação

• Operador com um Codex CLI já autenticado — monte o diretório ~/.codex do host no sidecar (codex-appserver-home) e pule a etapa de autenticação.
• Usuário público sem o codex instalado localmente — isso é irrelevante: o sidecar contém o CLI. O usuário somente se autentica pelo painel.
• OmniRoute em bare metal (sem sidecar, codex no host) — aponte OMNIROUTE_CODEX_APPSERVER_WS para seu próprio codex app-server e certifique-se de que o codex do host esteja autenticado; a dica “codex não está instalado” será exibida se o binário estiver ausente.

5. Saída residencial / UDP (recurso adicional para operadores, não incluído)

O sidecar genérico acima encaminha o tráfego de saída pela rede normal do contêiner. Um operador que precise que o tráfego do Codex saia por uma saída residencial (por exemplo, um sidecar tailscale com TUN que transporte TCP + UDP/QUIC) deve executá-lo como uma sobrescrita separada do compose; isso intencionalmente não faz parte do perfil codex-app-server incluído. Consulte o runbook interno de operações para obter instruções sobre essa configuração.

---

Código-fonte do OmniRoute (a58000c7685f)