Codex 하네스 활용하기: OpenAI가 App Server를 구축한 방법

• Codex를 자신의 제품에 통합할 수 있도록 표준화된 App Server 아키텍처와 JSON-RPC 프로토콜을 구축해서 제공
• 초기에는 CLI 중심의 TUI 하네스에서 출발했으나, JSON-RPC 프로토콜을 도입해 IDE·웹·로컬 앱 등 여러 클라이언트가 동일한 에이전트 루프를 공유할 수 있게 됨
• App Server는 Codex 코어 라이브러리를 호스팅하는 장기 실행 프로세스로, 스레드 라이프사이클 관리, 설정/인증, 도구 실행 등 전체 에이전트 경험을 클라이언트에 노출
• 아이템·턴·스레드라는 세 가지 대화 프리미티브를 통해 에이전트 루프의 복잡한 상호작용을 구조화하고 풍부한 UI 구축 가능
• VS Code, JetBrains, Xcode, 데스크톱 앱, 웹 런타임 등 다양한 서피스에서 동일한 하네스를 재사용하며, Go·Python·TypeScript·Swift·Kotlin 등 다국어 클라이언트 바인딩 지원
• MCP 서버, CLI 모드, TypeScript SDK 등 대안 통합 방식도 제공하지만, App Server가 최우선 통합 표준으로 자리잡음
• OpenAI는 App Server를 Codex 통합의 기본 경로로 유지하며, 오픈소스 CLI 레포를 통해 누구나 자체 워크플로에 Codex를 통합할 수 있도록 지원함

---

App Server의 기본 배경

• 초기에는 여러 제품에서 Codex 하네스를 재사용하기 위한 실용적 방법이었으나, 점차 표준 프로토콜로 발전
• Codex CLI는 TUI(터미널 사용자 인터페이스)로 시작했으며, VS Code 확장 프로그램 구축 시 동일한 하네스를 IDE UI에서 구동할 방법이 필요
  • 워크스페이스 탐색, 추론 진행 상황 스트리밍, 차이 출력 등 요청/응답을 넘어선 다양한 상호작용 패턴 지원 필요
• 처음에는 Codex를 MCP 서버로 노출하는 시도를 했으나, VS Code에 적합한 방식으로 MCP 시맨틱을 유지하기 어려움
• 대안으로 TUI 루프를 반영한 JSON-RPC 프로토콜을 도입, App Server의 비공식 첫 버전이 됨
  • 당시 다른 클라이언트가 의존할 것을 예상하지 못해 안정적 API로 설계되지 않았음
• Codex 도입이 확대되면서 내부 팀과 외부 파트너(JetBrains, Xcode 등)가 자체 제품에 하네스를 임베드할 수 있는 기능을 요구
  • 이전 버전과의 호환성을 유지하면서 프로토콜을 발전시킬 수 있는 플랫폼 서피스 설계 필요

Codex 하네스 내부 구조

• Codex 코어는 모든 에이전트 코드가 포함된 라이브러리이자, 에이전트 루프를 실행하고 하나의 Codex 스레드(대화)의 지속성을 관리하는 런타임
• 핵심 에이전트 루프 외에 세 가지 주요 기능 영역 존재:
  • 스레드 라이프사이클 및 지속성: 스레드 생성·재개·포크·보관, 이벤트 기록 유지로 클라이언트가 다시 연결해 일관된 타임라인 렌더링 가능
  • 설정 및 인증: 구성 로드, 기본값 관리, 자격 증명 상태 관리, "ChatGPT로 로그인" 같은 인증 흐름 실행
  • 도구 실행 및 확장: 샌드박스에서 셸/파일 도구 실행, MCP 서버 및 스킬 같은 통합을 연결해 일관된 정책 모델 하에서 에이전트 루프에 참여

App Server 아키텍처

• App Server는 클라이언트와 서버 간의 JSON-RPC 프로토콜이며 Codex 코어 스레드를 호스팅하는 장기 실행 프로세스
• 네 가지 주요 구성요소:
  • stdio 리더: 클라이언트의 입력을 읽는 역할
  • Codex 메시지 프로세서: 각 코어 세션과 직접 통신하여 클라이언트 요청 제출 및 업데이트 수신
  • 스레드 관리자: 각 스레드마다 하나의 코어 세션을 시작
  • 코어 스레드: 실제 에이전트 루프 실행
• 클라이언트 요청 하나가 많은 이벤트 업데이트를 발생시킬 수 있으며, 이 세부 이벤트를 통해 풍부한 UI 구축 가능
• stdio 리더와 Codex 메시지 프로세서는 클라이언트 JSON-RPC 요청을 Codex 코어 작업으로 변환하고, 내부 이벤트 스트림을 안정적이고 UI 사용 가능한 JSON-RPC 알림으로 변환하는 변환 계층 역할
• 클라이언트와 App Server 간 JSON-RPC 프로토콜은 완전한 양방향
  • 에이전트가 승인 같은 입력이 필요할 때 서버가 요청을 시작하고, 클라이언트가 응답할 때까지 턴 일시 중지 가능

대화 프리미티브

• 에이전트 루프용 API 설계의 핵심은 사용자와 에이전트 간의 상호작용이 단순한 요청/응답이 아닌 구조화된 일련의 작업으로 전개된다는 점
• 세 가지 핵심 프리미티브:

• 아이템(Item)

  • Codex에서 입력/출력의 기본 단위
  • 유형이 지정됨: 사용자 메시지, 에이전트 메시지, 도구 실행, 승인 요청, 차이 등
  • 명시적 라이프사이클: item/started → 선택적 item/*/delta(스트리밍) → item/completed(최종 페이로드)
  • 클라이언트는 started에서 즉시 렌더링 시작, delta에서 점진적 업데이트 스트리밍, completed에서 완결

• 턴(Turn)

  • 사용자 입력으로 시작되는 에이전트 작업의 한 단위
  • 예: 클라이언트가 "run tests and summarize failures"를 제출하면 턴 시작, 에이전트가 출력 생성을 완료하면 턴 종료
  • 한 턴에는 중간 단계와 결과물을 나타내는 일련의 아이템 포함

• 스레드(Thread)

  • 사용자와 에이전트 간의 진행 중인 Codex 세션을 위한 항구적 컨테이너
  • 여러 개의 턴 포함, 생성·재개·포크·보관 가능
  • 스레드 기록이 지속적으로 유지되어 클라이언트가 다시 연결하고 일관된 타임라인 렌더링 가능

클라이언트-서버 대화 흐름

• 대화 시작 시 클라이언트와 서버가 initialize 핸드셰이크 설정 필요
  • 클라이언트가 다른 메서드보다 먼저 단일 initialize 요청을 보내고, 서버가 응답으로 확인
  • 프로토콜 버전 관리, 기능 플래그, 기본값에 대해 양측이 합의
• 새 요청 시 서버가 스레드 생성 후 턴 생성, thread/started 및 turn/started 알림 전송
• 도구 호출도 아이템으로 클라이언트에게 전송되며, 서버가 작업 실행 승인을 요청 가능
  • 승인 요청 시 클라이언트가 "허용" 또는 "거부"로 응답할 때까지 턴 일시 중지
• 서버가 에이전트 메시지를 보내고 turn/completed로 턴 종료
  • 에이전트 메시지 델타 이벤트가 메시지 일부를 스트리밍하다가 item/completed로 최종 완결
• 전체 턴의 JSON을 확인하려면 codex debug app-server send-message-v2 "run tests and summarize failures" 명령 실행 가능

클라이언트와의 통합 패턴

• 로컬 앱과 IDE

  • 전송 방식은 stdio를 통한 JSON-RPC(JSONL)
  • 로컬 클라이언트는 플랫폼별 App Server 바이너리를 번들로 포함하거나 가져와서 장기 실행 하위 프로세스로 실행
  • VS Code 확장 프로그램과 데스크톱 앱에서는 배포 아티팩트에 플랫폼별 Codex 바이너리 포함, 테스트 완료된 버전에 고정
  • Go, Python, TypeScript, Swift, Kotlin 등 다양한 언어로 App Server 클라이언트 구현 완료
    • TypeScript: codex app-server generate-ts 명령으로 정의 직접 생성
    • 기타 언어: codex app-server generate-json-schema 명령으로 JSON 스키마 번들 생성 후 코드 생성기에 입력
  • Xcode 같은 파트너는 클라이언트를 안정적으로 유지하고 최신 App Server 바이너리를 지목하는 방식으로 릴리스 주기 분리
    • 클라이언트 릴리스를 기다리지 않고 서버 측 개선사항(향상된 자동 컴팩션, 새 구성 키 등)과 버그 수정 배포 가능
    • JSON-RPC 서피스가 이전 버전과의 호환성을 갖추어 구형 클라이언트도 신형 서버와 안전하게 통신

• Codex 웹 런타임

  • 컨테이너 환경에서 실행
  • 작업자가 체크아웃된 워크스페이스로 컨테이너를 프로비저닝하고, 그 안에서 App Server 바이너리를 실행, stdio 채널을 통해 JSON-RPC 유지
  • 웹 앱(사용자 브라우저)은 HTTP 및 SSE를 통해 Codex 백엔드와 통신하여 작업 이벤트 스트리밍
  • 브라우저 측 UI를 가볍게 유지하면서 데스크톱과 웹 전반에서 일관된 런타임 제공
  • 웹 세션은 단기적(탭 닫힘, 네트워크 끊김)이므로 서버에서 상태와 진행 상황 유지
    • 탭이 사라지더라도 작업 계속, 새 세션이 쉽게 다시 연결되어 중단된 곳에서 재개

• TUI 리팩터링 계획

  • 기존 TUI는 에이전트 루프와 동일한 프로세스에서 실행되는 "네이티브" 클라이언트로, App Server 프로토콜이 아닌 Rust 코어 유형과 직접 통신
  • App Server를 사용하여 다른 클라이언트처럼 작동하도록 TUI를 리팩터링할 계획
    • 원격 머신에서 실행 중인 Codex 서버에 연결 가능
    • 에이전트가 컴퓨팅 인프라와 밀접하게 연동, 노트북 절전 모드 또는 연결 끊김에도 작업 계속
    • 로컬에서 라이브 업데이트와 제어 기능 계속 제공

올바른 프로토콜 선택하기

• App Server가 최우선 통합 방식이지만, 기능이 더 제한적인 대안도 존재

• MCP 서버

  • codex mcp-server를 실행하고 stdio 서버를 지원하는 모든 MCP 클라이언트(예: OpenAI Agents SDK)에서 연결
  • 이미 MCP 기반 워크플로가 있고 Codex를 호출 가능한 도구로 사용하고자 할 때 적합
  • 단점: MCP가 제공하는 것만 사용 가능, 차이 업데이트 같은 Codex 전용 상호작용이 매끄럽게 매핑되지 않을 수 있음

• 이식 가능한 인터페이스

  • 여러 모델 공급자와 런타임을 대상으로 하는 단일 추상화가 필요할 때 적합
  • 단점: 기능의 공통된 하위 집합으로 수렴되어 풍부한 상호작용 표현이 어려울 수 있음
  • 이 분야는 빠르게 발전 중이며, 더 많은 공통 표준이 등장할 것으로 예상(예: agentskills.io)

• App Server

  • 전체 Codex 하네스를 안정적이고 UI 친화적인 이벤트 스트림으로 노출
  • 에이전트 루프 전체 기능 외에 ChatGPT로 로그인, 모델 탐색, 구성 관리 같은 지원 기능도 사용 가능
  • 주요 비용: 사용 중인 언어로 클라이언트 측 JSON-RPC 바인딩 구축 필요
    • JSON 스키마와 문서를 제공하면 Codex가 다수의 복잡한 작업 처리 가능, 많은 팀이 신속하게 통합 구현

• CLI 모드

  • 일회성 작업 및 CI 실행을 위한 경량 스크립트형 모드
  • 단일 명령을 비대화형으로 실행, 구조화된 출력 스트리밍, 명확한 성공/실패 신호로 종료
  • 자동화 및 파이프라인에 적합

• TypeScript SDK

  • 자체 애플리케이션 내에서 로컬 Codex 에이전트를 프로그래밍 방식으로 제어할 수 있는 TypeScript 라이브러리
  • 별도의 JSON-RPC 클라이언트 구축 없이 네이티브 라이브러리 인터페이스 필요할 때 적합
  • App Server보다 먼저 출시되어 지원 언어가 더 적고 적용 범위가 더 좁음
  • 개발자 관심에 따라 App Server 프로토콜을 래핑하는 추가 SDK 제공 가능성 존재

향후 계획

• App Server가 Codex 코어를 노출하고, 클라이언트가 전체 에이전트 루프를 구동할 수 있게 하며, TUI·로컬 IDE 통합·웹 런타임을 비롯한 광범위한 서피스 지원
• 모든 소스 코드는 Codex CLI 오픈 소스 레포에 공개
• 기능 요청과 의견을 환영하며, 에이전트를 보다 쉽게 이용할 수 있도록 지속적 개선 예정

• Codex App Server 공식 문서