OpenAI Codex — App-Server provider (`codex-app-server`) (Español)

1. Arquitectura

┌─ Aplicación OmniRoute ───────────┐        ┌─ Sidecar codex-app-server ──────────┐
│  CodexAppServerExecutor          │  WS    │  codex app-server                   │
│  ws://codex-app-server:1456 ─────┼───────▶│  --listen ws://0.0.0.0:1456         │
│  (+ token de capacidad)          │  JSON  │  --ws-auth capability-token         │
│                                  │  RPC   │  administra automáticamente OAuth   │
└──────────────────────────────────┘        │  de OpenAI (~/.codex/auth.json,      │
        │ comparte (volúmenes de compose)   │  renovación automática)             │
        ▼                                   └─────────────────────────────────────┘
  codex-appserver-token   → el token de capacidad de WS (ambos lo montan)
  codex-appserver-home    → ~/.codex (auth.json escrito por el panel,
                             leído por codex app-server en el sidecar)

• El sidecar escucha únicamente en la red interna de compose (ws://codex-app-server:1456), protegido mediante un token de capacidad. Nunca se publica en el host ni en internet.
• Codex CLI está incluido en omniroute:base, por lo que no es necesario instalar codex en el host ni en el equipo del usuario al ejecutar el sidecar.

2. Iniciarlo

# Inicia el conjunto CON el perfil del 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)

El sidecar genera su token de capacidad de WS durante el primer arranque (en el volumen compartido codex-appserver-token) y la aplicación lee el mismo token mediante OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE. No es necesario configurar el token manualmente.

3. Conectarse e iniciar sesión

1. En el panel, añade una conexión para OpenAI Codex (App-Server). No se requiere ninguna clave de API ni token (es un proveedor sin autenticación; el sidecar gestiona la autenticación).
2. Si la Codex CLI del sidecar aún no ha iniciado sesión, la comprobación de estado de la conexión muestra “en ejecución, pero sin sesión iniciada” (no un error de autenticación en rojo). Usa Iniciar sesión con ChatGPT: esto ejecuta el OAuth de dispositivo estándar de Codex en tu navegador y, después, escribe ~/.codex/auth.json en el volumen compartido mediante Aplicar autenticación (el mismo inicio de sesión sirve tanto para el proveedor codex como para codex-app-server).
3. Una vez iniciada la sesión, la comprobación de estado pasa a verde (verifica tanto /readyz como account/read, es decir, que esté en ejecución y autenticado) y comienza a funcionar.

El panel nunca sobrescribe un archivo ~/.codex/auth.json existente que sea válido: solo escribe cuando el archivo no existe o su token está obsoleto (siempre se crea una copia de seguridad).

4. Escenarios de implementación

• Operador con una Codex CLI ya autenticada — monta el directorio ~/.codex del host en el sidecar (codex-appserver-home) y omite el paso de inicio de sesión.
• Usuario público sin codex instalado localmente — no importa: el sidecar incluye la CLI. El usuario solo se autentica mediante el panel.
• OmniRoute en equipo físico (sin sidecar, codex en el host) — configura OMNIROUTE_CODEX_APPSERVER_WS para que apunte a tu propio codex app-server y asegúrate de que codex en el host haya iniciado sesión; si falta el binario, aparece el aviso «codex no está instalado».

5. Salida residencial / UDP (opción adicional para el operador, no incluida)

El sidecar genérico anterior dirige el tráfico saliente a través de la red normal del contenedor. Un operador que necesite que el tráfico de Codex salga mediante una conexión residencial (por ejemplo, un sidecar tailscale con TUN que transporte TCP + UDP/QUIC) debe ejecutarlo como una configuración de compose separada; intencionadamente, no forma parte del perfil codex-app-server incluido. Consulta el manual interno de operaciones para obtener información sobre esa configuración.

---

Código fuente de OmniRoute (a58000c7685f)