Codex App Server 아키텍처: OpenAI가 표준 하네스로 통합한 에이전트 실행 구조

이 글은 OpenAI가 Codex를 다양한 제품과 환경에 일관되게 통합하기 위해 구축한 App Server 아키텍처와 JSON-RPC 기반 하네스 구조를 정리한 내용입니다.
초기 CLI 중심 구조에서 출발해, IDE·웹·데스크톱 등 여러 클라이언트가 동일한 에이전트 루프를 공유할 수 있도록 발전한 배경과 내부 구조, 그리고 통합 방식별 특징까지 기술 관점에서 살펴봅니다.

Codex를 자체 제품에 통합하려는 개발자라면, 어떤 방식이 적합한지 판단하는 데 도움이 될 것입니다.

반응형

---

1. App Server가 등장한 배경

CLI에서 시작된 Codex 하네스

Codex는 처음에 TUI(터미널 사용자 인터페이스) 기반 CLI 하네스로 시작했습니다.
이 구조는 에이전트 루프를 하나의 프로세스 안에서 직접 실행하는 방식이었습니다.

그러나 VS Code 확장 프로그램을 개발하면서 문제가 생겼습니다.

• 워크스페이스 탐색
• 추론 진행 상황 스트리밍
• 코드 차이(diff) 출력
• 도구 실행 승인 요청

단순 요청/응답 모델로는 이런 복합 상호작용을 처리하기 어려웠습니다.

MCP 서버 시도와 한계

초기에는 Codex를 MCP 서버로 노출하는 방식도 시도됐습니다.
하지만 VS Code에 적합한 방식으로 MCP 시맨틱을 유지하기 어렵다는 한계가 있었습니다.

JSON-RPC 프로토콜 도입

결국 TUI 루프 구조를 반영한 JSON-RPC 프로토콜이 도입됐고, 이것이 App Server의 비공식 첫 버전이 됐습니다.

이후 Codex 도입이 확대되면서 JetBrains, Xcode 등 외부 파트너도 하네스를 임베드하려는 요구가 증가했습니다.
그 결과, 이전 버전과의 호환성을 유지하면서 발전 가능한 표준 프로토콜로 정식화됐습니다.

---

2. Codex 하네스 내부 구조

Codex 코어는 에이전트 코드 전체가 포함된 라이브러리이자 런타임입니다.
핵심 역할은 다음과 같습니다.

1) 에이전트 루프 실행

하나의 Codex 스레드(대화)를 지속적으로 관리하며 작업을 수행합니다.

2) 스레드 라이프사이클 및 지속성

• 스레드 생성
• 재개
• 포크
• 보관

이벤트 기록을 유지해, 클라이언트가 재연결하더라도 일관된 타임라인을 렌더링할 수 있습니다.

3) 설정 및 인증

• 구성 로드
• 기본값 관리
• 자격 증명 상태 관리
• “ChatGPT로 로그인” 같은 인증 흐름 실행

4) 도구 실행 및 확장

• 샌드박스에서 셸/파일 도구 실행
• MCP 서버 및 스킬 통합
• 정책 모델 하에서 일관된 실행

---

3. App Server 아키텍처 구성 요소

App Server는 Codex 코어 스레드를 호스팅하는 장기 실행 프로세스이며, 클라이언트와 JSON-RPC로 통신합니다.

주요 구성요소 4가지

1. stdio 리더
   클라이언트 입력 수신
2. Codex 메시지 프로세서
   클라이언트 요청을 코어 작업으로 변환하고 이벤트 수신
3. 스레드 관리자
   각 스레드마다 하나의 코어 세션 시작
4. 코어 스레드
   실제 에이전트 루프 실행

App Server는 단순한 요청-응답 서버가 아닙니다.
하나의 요청이 여러 이벤트를 발생시키며, 이를 통해 풍부한 UI를 구성할 수 있습니다.

또한 JSON-RPC 통신은 완전한 양방향 구조입니다.
예를 들어, 에이전트가 도구 실행 승인을 요청하면 클라이언트가 응답할 때까지 턴이 일시 중지됩니다.

---

4. 대화 프리미티브: Item, Turn, Thread

Codex는 단순 채팅 모델이 아니라, 구조화된 작업 흐름을 기반으로 동작합니다.

1) Item

입력/출력의 기본 단위입니다.

유형 예시:

• 사용자 메시지
• 에이전트 메시지
• 도구 실행
• 승인 요청
• 코드 차이

라이프사이클:

• item/started
• item/*/delta (스트리밍)
• item/completed

클라이언트는 started에서 즉시 렌더링하고, delta로 점진 업데이트하며, completed에서 최종 상태를 확정합니다.

---

2) Turn

사용자 입력으로 시작되는 하나의 작업 단위입니다.

예:
"run tests and summarize failures"

이 요청이 시작되면 턴이 열리고, 결과 생성이 완료되면 종료됩니다.
하나의 턴에는 여러 Item이 포함됩니다.

---

3) Thread

사용자와 에이전트 간의 지속적 세션 컨테이너입니다.

• 여러 턴 포함
• 생성/재개/포크/보관 가능
• 상태 지속 유지

웹 브라우저가 닫혀도 서버에서 작업을 계속 유지할 수 있는 이유가 여기에 있습니다.

---

5. 클라이언트 통합 방식

App Server는 다양한 환경에서 재사용됩니다.

1) 로컬 앱 및 IDE

• stdio 기반 JSON-RPC(JSONL) 통신
• 플랫폼별 App Server 바이너리 포함
• Go, Python, TypeScript, Swift, Kotlin 바인딩 지원

예시:

• TypeScript:
  codex app-server generate-ts
• 기타 언어:
  codex app-server generate-json-schema

Xcode 같은 파트너는 클라이언트 릴리스와 서버 개선을 분리해 운영합니다.
JSON-RPC 서피스가 이전 버전과 호환되므로 구형 클라이언트도 신형 서버와 통신 가능합니다.

---

2) 웹 런타임

• 컨테이너 환경에서 App Server 실행
• 브라우저는 HTTP + SSE로 이벤트 스트리밍 수신
• 세션이 끊겨도 서버 상태 유지

이 구조는 브라우저를 가볍게 유지하면서 데스크톱과 동일한 런타임을 제공합니다.

---

3) CLI 모드

일회성 작업 및 CI 환경에 적합합니다.

• 단일 명령 실행
• 구조화된 출력 스트리밍
• 명확한 성공/실패 종료 신호

자동화 파이프라인에 적합한 경량 모드입니다.

---

4) TypeScript SDK

JSON-RPC 클라이언트를 별도로 구축하지 않고, 로컬 Codex 에이전트를 프로그래밍 방식으로 제어할 수 있습니다.

단, App Server 대비 범위는 좁습니다.

---

6. App Server가 최우선 통합 표준인 이유

App Server는 다음을 모두 제공합니다.

• 전체 에이전트 루프 노출
• UI 친화적 이벤트 스트림
• 인증 및 구성 관리
• 모델 탐색
• 장기 세션 유지

단점은 클라이언트 측 JSON-RPC 바인딩 구현이 필요하다는 점입니다.
하지만 JSON 스키마와 문서가 제공되므로 다수 팀이 빠르게 통합을 완료하고 있습니다.

---

• TUI를 App Server 기반으로 리팩터링 예정
• 원격 서버 연결 지원 강화
• 노트북 절전 상태에서도 작업 지속
• Codex CLI 오픈소스 레포 공개
• 기능 요청 및 지속 개선 예정

App Server는 단순한 통신 계층이 아니라, Codex 통합의 표준 실행 플랫폼으로 자리 잡고 있습니다.

---

728x90

Codex App Server는 다음과 같은 의미를 가집니다.

• CLI 중심 구조에서 시작해 표준 프로토콜로 발전
• JSON-RPC 기반의 양방향 에이전트 실행 구조
• Item·Turn·Thread 프리미티브로 복잡한 상호작용 구조화
• IDE, 웹, 데스크톱, CI 환경까지 일관된 런타임 제공
• 장기 실행 프로세스를 통한 상태 지속 및 확장성 확보

이 구조는 단순히 AI 모델을 호출하는 방식이 아니라,
에이전트를 하나의 실행 플랫폼으로 다루는 접근 방식입니다.

향후 더 많은 제품과 런타임이 이 구조를 기반으로 통합될 가능성이 높으며,
표준화된 에이전트 실행 환경이라는 측면에서 중요한 의미를 가집니다.

300x250

https://openai.com/ko-KR/index/unlocking-the-codex-harness/

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