OpenAI Codex — App-Server provider (`codex-app-server`) (한국어)

1. 아키텍처

┌─ OmniRoute 앱 ──────────────────┐        ┌─ codex-app-server 사이드카 ─────────┐
│  CodexAppServerExecutor          │  WS    │  codex app-server                   │
│  ws://codex-app-server:1456 ─────┼───────▶│  --listen ws://0.0.0.0:1456         │
│  (+ 기능 토큰)                   │  JSON  │  --ws-auth capability-token         │
│                                  │  RPC   │  OpenAI OAuth 자체 관리             │
└──────────────────────────────────┘        │  (~/.codex/auth.json, 자동 갱신)    │
        │ 공유(compose 볼륨)                 └─────────────────────────────────────┘
        ▼
  codex-appserver-token   → WS 기능 토큰(양쪽 모두 마운트)
  codex-appserver-home    → ~/.codex(대시보드가 auth.json을 작성하고,
                             사이드카의 codex app-server가 읽음)

사이드카는 기능 토큰으로 보호되는 내부 compose 네트워크 (ws://codex-app-server:1456)에서만 수신 대기합니다. 호스트나 인터넷에 절대로 게시되지 않습니다.
Codex CLI는 omniroute:base에 포함되어 있으므로 사이드카를 실행할 때 호스트나 사용자 머신에 codex를 설치할 필요가 없습니다.

2. 실행하기

# codex app-server 사이드카 프로필과 함께 스택 시작:
docker compose --profile base --profile codex-app-server up -d
# (podman: podman compose --profile base --profile codex-app-server up -d)

사이드카는 처음 부팅할 때 WS 기능 토큰을 생성하여 공유 codex-appserver-token 볼륨에 저장하며, 앱은 OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE을 통해 동일한 토큰을 읽습니다. 토큰을 수동으로 연결할 필요가 없습니다.

3. 연결 및 로그인

대시보드에서 OpenAI Codex (App-Server) 연결을 추가합니다. API 키나 토큰은 필요하지 않습니다(인증이 필요 없는 제공자이며 사이드카가 인증을 관리합니다).
사이드카의 Codex CLI에 아직 로그인하지 않았다면, 연결 상태 확인에 빨간색 인증 오류 대신 *“실행 중이지만 로그인되지 않음”*이 표시됩니다. ChatGPT로 로그인을 사용하세요. 그러면 브라우저에서 표준 Codex 기기 OAuth가 실행된 후 인증 적용을 통해 공유 볼륨에 ~/.codex/auth.json을 기록합니다(한 번의 로그인으로 codex와 codex-app-server 제공자 모두를 사용할 수 있습니다).
로그인하면 상태 확인이 정상으로 바뀌고(/readyz와 account/read를 모두 확인하므로, 실행 중인지와 인증되었는지를 모두 검증함) 작업을 처리하기 시작합니다.

대시보드는 정상적인 기존 ~/.codex/auth.json을 절대로 덮어쓰지 않습니다. 파일이 없거나 토큰이 오래된 경우에만 기록하며, 항상 백업을 생성합니다.

4. 배포 시나리오

이미 인증된 Codex CLI를 보유한 운영자 — 호스트의 ~/.codex를 사이드카(codex-appserver-home)에 마운트하고 로그인 단계를 건너뜁니다.
로컬에 codex가 설치되지 않은 일반 사용자 — 문제되지 않습니다. 사이드카에 CLI가 포함되어 있습니다. 사용자는 대시보드를 통해서만 인증하면 됩니다.
베어메탈 OmniRoute(사이드카 없이 호스트 codex 사용) — OMNIROUTE_CODEX_APPSERVER_WS가 자체 codex app-server를 가리키도록 설정하고 호스트의 codex가 로그인된 상태인지 확인합니다. 바이너리가 없으면 “codex가 설치되지 않음” 안내가 표시됩니다.

5. 가정용 / UDP 이그레스(운영자용 추가 구성, 기본 제공되지 않음)

위의 범용 사이드카는 컨테이너의 일반 네트워크를 통해 외부로 통신합니다. Codex 트래픽이 가정용 네트워크 출구를 통해 외부로 나가야 하는 운영자는 TCP + UDP/QUIC를 전달하는 TUN tailscale 사이드카 등을 별도의 compose 오버라이드로 실행해야 합니다. 이는 의도적으로 기본 제공되는 codex-app-server 프로필에 포함되지 않습니다. 해당 구성은 내부 운영 런북을 참조하세요.

OmniRoute 소스 코드 (a58000c7685f)