# Codex 하네스 활용하기: OpenAI가 App Server를 구축한 방법 > Clean Markdown view of GeekNews topic #26956. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=26956](https://news.hada.io/topic?id=26956) - GeekNews Markdown: [https://news.hada.io/topic/26956.md](https://news.hada.io/topic/26956.md) - Type: GN+ - Author: [xguru](https://news.hada.io/@xguru) - Published: 2026-02-24T12:43:28+09:00 - Updated: 2026-02-24T12:43:28+09:00 - Original source: [openai.com](https://openai.com/ko-KR/index/unlocking-the-codex-harness/) - Points: 21 - Comments: 0 ## Summary **OpenAI Codex App Server**는 에이전트 루프를 표준화된 **JSON-RPC 프로토콜**로 노출해, IDE·웹·CLI 등 다양한 환경에서 동일한 Codex 경험을 구현할 수 있게 합니다. App Server는 스레드·턴·아이템으로 구성된 대화 프리미티브를 통해 복잡한 상호작용을 구조화하며, 설정·인증·도구 실행까지 포함한 전체 에이전트 수명주기를 관리합니다. 이를 통해 개발자는 Go·Python·TypeScript 등 여러 언어에서 일관된 방식으로 Codex를 통합하고, 클라이언트·서버 간 버전 호환성을 유지한 채 기능을 확장할 수 있습니다. ## Topic Body - **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 공식 문서](https://developers.openai.com/codex/app-server/) ## Comments _No public comments on this page._