OpenAI Codex 앱 서버 아키텍처 및 통합

OpenAI는 Codex 앱 서버를 도입했습니다. 이 JSON-RPC 기반 프로토콜 및 프로세스는 Codex 에이전트 하네스를 다양한 클라이언트에 노출하여 IDE, 웹 런타임 및 터미널 인터페이스 전반에 걸쳐 일관된 에이전트 경험을 제공합니다.

Codex 앱 서버 아키텍처

Codex 앱 서버는 클라이언트와 "Codex core" 사이의 번역 계층 역할을 하며, 여기에는 에이전트 루프, 도구 실행 로직 및 스레드 관리가 포함됩니다.

핵심 구성 요소

App Server 프로세스는 네 가지 주요 구성 요소로 이루어집니다:

  • Stdio Reader: 들어오는 통신 채널을 처리합니다.
  • Codex Message Processor: 클라이언트 JSON-RPC 요청을 Codex 코어 작업으로 변환하고 내부 이벤트 스트림을 안정적인 UI 준비 알림으로 변환합니다.
  • Thread Manager: 코어 세션의 수명 주기를 관리하며, 스레드당 하나의 코어 세션을 생성합니다.
  • Core Threads: 에이전트 루프가 실행되는 실제 런타임 인스턴스입니다.

Codex 하네스

에이전트 루프 외에도, App Server는 전체 Codex 하네스를 노출합니다:

  • Thread Lifecycle and Persistence: 대화를 생성, 재개, 포크 및 보관할 수 있는 기능을 제공하여 재연결 시 클라이언트에 일관된 타임라인을 보장합니다.
  • Configuration and Authentication: 기본값 및 인증 흐름 관리, 예: "Sign in with ChatGPT".
  • Tool Execution and Extensions: 셸 및 파일 도구를 위한 샌드박스 환경과 MCP 서버 및 스킬 통합을 제공합니다.

대화 기본 요소

에이전트 상호작용의 비선형성을 처리하기 위해, 앱 서버 프로토콜은 세 가지 핵심 기본 요소를 활용하여 다양한 사용자 인터페이스 간의 탄력성과 통합 용이성을 보장합니다.

1. Item

Item은 입력 및 출력의 원자 단위입니다. 각 Item(예: 사용자 메시지, 도구 실행, diff)은 특정 수명 주기를 따릅니다:

  • item/started: Item이 시작됩니다.
  • item/*/delta: 콘텐츠가 점진적으로 스트리밍됩니다(스트리밍 유형의 경우).
  • item/completed: Item이 최종 페이로드와 함께 완료됩니다.

2. Turn

Turn은 사용자 입력에 의해 트리거되는 에이전트 작업의 단일 단위를 나타냅니다. 이는 에이전트가 생성한 중간 단계와 최종 출력을 나타내는 일련의 Item을 포함합니다.

3. Thread

Thread는 세션을 위한 영구적인 컨테이너입니다. 여러 Turn을 유지하여 클라이언트가 세션에 재연결하고 상태를 재구성하지 않고도 기록을 렌더링할 수 있게 합니다.

클라이언트 통합 패턴

앱 서버는 stdio(JSONL)를 통한 JSON-RPC를 사용하여 Go, Python, TypeScript, Swift, Kotlin 등 여러 언어에서 클라이언트 바인딩을 가능하게 합니다.

로컬 앱 및 IDE

로컬 클라이언트(VS Code 확장 및 Codex Desktop App 등)는 플랫폼 전용 App Server 바이너리를 자식 프로세스로 번들합니다. Xcode와 같은 일부 파트너는 클라이언트 릴리스와 별도로 최신 App Server 바이너리를 지정함으로써 릴리스 주기를 분리하고 서버 측 개선 및 버그 수정을 전체 클라이언트 업데이트 없이 적용합니다.

Codex 웹

컨테이너화된 환경에서 워커는 작업 공간이 포함된 컨테이너를 프로비저닝하고 App Server 바이너리를 실행합니다. 웹 앱은 HTTP와 SSE를 통해 Codex 백엔드와 통신하며, 워커로부터 이벤트를 스트리밍합니다. 이를 통해 브라우저 탭이 닫혀도 장기 실행 작업이 계속됩니다.

TUI 및 Codex CLI

TUI는 원래 Rust 코어 타입과 직접 상호작용했지만, 현재 App Server 프로토콜을 사용하도록 리팩터링 중입니다. 이를 통해 TUI는 원격 Codex 서버에 연결하여 에이전트를 컴퓨팅 리소스에 가깝게 유지하면서 로컬 업데이트를 제공할 수 있습니다.

통합 방법 비교

OpenAI는 전체 하네스가 필요한 경우 App Server를 권장하지만, 특정 사용 사례에 따라 다른 옵션도 제공합니다:

방법 최적 사용 사례 트레이드오프
Codex App Server 전체 하네스, 안정적인 UI 친화적 이벤트 스트림 및 인증 관리. 클라이언트 측 JSON-RPC 바인딩을 구축해야 합니다.
MCP Server Codex가 호출 가능한 도구인 기존 MCP 기반 워크플로우. MCP 의미론에 제한되며, diff 업데이트와 같은 풍부한 세션 기능이 부족합니다.
Cross-provider Protocols 다양한 모델 제공자 간 다중 에이전트 조정. 대부분 공통 기능 하위 집합에 제한되며, 제공자별 의미론이 부족합니다.
CLI Mode 일회성 작업, CI/CD 파이프라인 및 비대화형 자동화. 비대화형; 단일 명령 완료를 위해 설계되었습니다.
TypeScript Library TS 애플리케이션 내 로컬 에이전트에 대한 프로그래밍 제어. 현재 App Server보다 지원 언어가 적고 범위가 작습니다.

App Server의 소스 코드는 오픈소스 Codex CLI 저장소에서 확인할 수 있습니다.

Sources