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

OpenAI의 코딩 에이전트 Codex는 웹 앱⁠(새 창에서 열기), CLI⁠(새 창에서 열기), IDE 확장 프로그램⁠(새 창에서 열기), 새로운 Codex macOS 앱 등 다양한 서피스에서 사용할 수 있습니다. 내부적으로는 모두 동일한 Codex 하네스로 구동됩니다. 이는 모든 Codex 경험의 기반이 되는 에이전트 루프와 로직입니다. 이들 사이의 중요한 연결 고리는 무엇일까요? Codex App Server⁠(새 창에서 열기)는 클라이언트 친화적인 양방향 JSON-RPC¹ API입니다.

이 게시글에서는 Codex App Server를 소개하며, Codex의 기능을 제품에 가장 효과적으로 통합하여 사용자가 워크플로를 한층 더 강화할 수 있도록 하는 방법에 대한 지금까지의 학습 내용을 공유합니다. App Server의 아키텍처와 프로토콜, 다양한 Codex 서피스에서의 통합 방법, Codex를 코드 리뷰어, SRE 에이전트 또는 코딩 어시스턴트로 활용하는 팁에 대해 설명합니다.

아키텍처에 대해 자세히 알아보기 전에 App Server의 배경을 알아두면 도움이 됩니다. 초기에는 App Server가 여러 제품에서 Codex 하네스를 재사용할 수 있는 실용적인 방법이었지만 점차 표준 프로토콜로 발전했습니다.

Codex CLI는 TUI(터미널 사용자 인터페이스)로 시작했으며, 이는 Codex가 터미널을 통해 접근된다는 의미입니다. Codex 에이전트와 상호작용할 수 있는 IDE 친화적인 방식인 VS Code 확장 프로그램을 구축할 때, 동일한 하네스를 사용하여 IDE UI에서 동일한 에이전트 루프를 다시 구현하지 않고도 구동할 수 있는 방법이 필요했습니다. 즉, 워크스페이스를 탐색하고 에이전트가 추론하는 동안 진행 상황을 스트리밍하며 차이를 출력하는 등 요청/응답을 넘어 다양한 상호작용 패턴을 지원해야 했습니다. 처음에는 Codex를 MCP 서버⁠(새 창에서 열기)로 노출하는 시도를 했지만, VS Code에 적합한 방식으로 MCP 시맨틱을 유지하는 것이 어려웠습니다. 그 대신, TUI 루프를 반영한 JSON-RPC 프로토콜을 도입하여 App Server의 비공식적인 첫 번째 버전⁠(새 창에서 열기)이 되었습니다. 당시에는 다른 클라이언트가 App Server에 의존할 것이라고 예상하지 못했기 때문에 안정적인 API로 설계되지 않았습니다.

Codex 도입이 몇 달 동안 확대되면서, 내부 팀과 외부 파트너는 사용자의 소프트웨어 개발 워크플로를 가속화하기 위해 동일한 하네스를 자체 제품에 임베드할 수 있는 기능이 필요했습니다. 예를 들어, JetBrains와 Xcode는 IDE 수준의 에이전트 경험을 원했지만 Codex 데스크톱 앱은 여러 Codex 에이전트를 병렬로 조정해야 했습니다. 이러한 필요성으로 인해 제품과 파트너 통합이 시간이 지나도 안전하게 의존할 수 있는 플랫폼 서피스를 설계하게 되었습니다. 기존 클라이언트를 손상시키지 않고 프로토콜을 발전시킬 수 있도록 손쉬운 통합과 이전 버전과의 호환성이 필요했습니다.

이제, 서로 다른 클라이언트가 동일한 하네스를 사용할 수 있도록 아키텍처와 프로토콜을 어떻게 설계했는지 단계별로 설명하겠습니다.

먼저, Codex 하네스 내부에 무엇이 있는지 살펴보고 Codex App Server가 이를 클라이언트에게 어떻게 노출하는지 알아보겠습니다. 지난 Codex 블로그에서는 사용자, 모델, 도구 간의 상호작용을 조율하는 핵심 에이전트 루프를 자세히 살펴봤습니다. 이는 Codex 하네스의 핵심 로직이지만 전체 에이전트 경험에는 더 많은 것이 있습니다.

1. 스레드 라이프사이클 및 지속성. 스레드는 사용자와 에이전트 간의 Codex 대화입니다. Codex는 클라이언트가 다시 연결하여 일관된 타임라인을 렌더링할 수 있도록 스레드를 생성하고, 재개하고, 포크하고, 보관하며, 이벤트 기록을 유지합니다.

2. 설정 및 인증. Codex는 구성을 로드하고, 기본값을 관리하며, 자격 증명 상태를 비롯하여 “ChatGPT로 로그인”과 같은 인증 흐름을 실행합니다.

3. 도구 실행 및 확장. Codex는 샌드박스에서 셸/파일 도구를 실행하고 MCP 서버 및 스킬과 같은 통합을 연결하여 일관된 정책 모델 하에서 에이전트 루프에 참여할 수 있도록 합니다.

여기서 언급한 모든 에이전트 로직(핵심 에이전트 루프 포함)은 Codex CLI 코드베이스의 "Codex 코어⁠(새 창에서 열기)"라는 부분에 포함되어 있습니다. Codex 코어는 모든 에이전트 코드가 포함된 라이브러리이자, 에이전트 루프를 실행하고 하나의 Codex 스레드(대화)의 지속성을 관리할 수 있는 런타임입니다.

Codex 하네스를 유용하게 사용하려면 클라이언트가 여기에 액세스할 수 있어야 합니다. 이때가 바로 App Server의 역할이 필요합니다.

App Server는 클라이언트와 서버 간의 JSON-RPC 프로토콜이며 Codex 코어 스레드를 호스팅하는 장기 실행 프로세스입니다. 위의 다이어그램에서 볼 수 있듯이, App Server 프로세스에는 stdio 리더, Codex 메시지 프로세서, 스레드 관리자, 코어 스레드 네 가지 주요 구성요소가 있습니다. 스레드 관리자가 각 스레드마다 하나의 코어 세션을 시작하면 Codex 메시지 프로세서는 각 코어 세션과 직접 통신하여 클라이언트 요청을 제출하고 업데이트를 받습니다.

클라이언트 요청 하나로 인해 많은 이벤트 업데이트가 발생할 수 있으며, 이러한 세부 이벤트 덕분에 App Server에서 풍부한 UI를 구축할 수 있습니다. 또한 stdio 리더와 Codex 메시지 프로세서는 클라이언트와 Codex 코어 스레드 간의 변환 계층 역할을 합니다. 그들은 클라이언트 JSON-RPC 요청을 Codex 코어 작업으로 변환하고 Codex 코어의 내부 이벤트 스트림을 수신한 후, 이러한 낮은 수준의 이벤트를 안정적이고 UI 사용 가능한 소수의 JSON-RPC 알림으로 변환합니다.

클라이언트와 App Server 간의 JSON-RPC 프로토콜은 완전한 양방향입니다. 일반적인 스레드에는 클라이언트 요청과 여러 서버 알림이 포함되어 있습니다. 또한 에이전트가 승인과 같은 입력이 필요할 때 서버가 요청을 시작할 수 있으며, 그런 다음 클라이언트가 응답할 때까지 턴을 일시 중지할 수 있습니다.

다음으로, App Server 프로토콜의 기본 구성 요소인 대화 프리미티브에 대해 자세히 알아보겠습니다. 에이전트 루프용 API를 설계하는 것은 까다롭습니다. 이는 사용자와 에이전트 간의 상호작용이 단순한 요청/응답이 아니기 때문입니다. 하나의 사용자 요청은 클라이언트가 충실하게 표현해야 하는 구조화된 일련의 작업으로 전개될 수 있습니다. 여기에는 사용자의 입력, 에이전트의 점진적인 진행 상황, 그리고 진행 과정에서 생성되는 산출물(예: 차이)이 포함됩니다. 이러한 상호작용 스트림을 UI 전반에서 쉽게 통합하고 탄력적으로 조정할 수 있도록 명확한 경계와 라이프사이클을 가진 세 가지 핵심 기본 요소에 집중했습니다.

1. 아이템: 아이템은 Codex에서 입력/출력의 기본 단위입니다. 아이템은 유형이 지정되어 있으며(예: 사용자 메시지, 에이전트 메시지, 도구 실행, 승인 요청, 차이) 각 유형에는 명시적인 라이프사이클이 있습니다.

• 아이템이 시작될 때 item/started
• 콘텐츠 스트리밍 시 선택적 item/*/delta 이벤트(스트리밍 아이템 유형의 경우)
• 아이템이 최종 페이로드와 함께 완결될 때 item/completed

이 라이프사이클을 통해 클라이언트는 started에서 즉시 렌더링을 시작하고, delta에서 점진적 업데이트를 스트리밍하며, completed에서 완결합니다.

2. 턴: 턴은 사용자 입력으로 시작되는 에이전트 작업의 한 단위입니다. 클라이언트가 입력(예: “run tests and summarize failures”)을 제출할 때 시작되며, 에이전트가 해당 입력에 대한 출력을 생성하는 작업을 완료할 때 끝납니다. 한 턴에는 중간 단계와 그 과정에서 생성된 결과물을 나타내는 일련의 아이템이 포함됩니다.

3. 스레드: 스레드는 사용자와 에이전트 간의 진행 중인 Codex 세션을 지속적으로 저장하는 컨테이너입니다. 여기에는 여러 개의 턴이 포함됩니다. 스레드는 생성, 재개, 포크, 보관할 수 있습니다. 스레드 기록은 지속적으로 유지되므로 클라이언트가 다시 연결하고 일관된 타임라인을 렌더링할 수 있습니다.

이제 프리미티브로 표현된 클라이언트와 에이전트 간의 단순화된 대화를 살펴보겠습니다.

대화가 시작될 때 클라이언트와 서버는 initialize 핸드셰이크를 설정해야 합니다. 클라이언트는 다른 메서드보다 먼저 단일 initialize 요청을 보내야 하며, 서버는 응답으로 이를 확인합니다. 이렇게 하면 서버는 기능을 알릴 기회를 얻고 실제 작업이 시작되기 전에 양측이 프로토콜 버전 관리, 기능 플래그, 기본값에 대해 합의할 수 있습니다. 다음은 OpenAI의 VS Code 확장 프로그램에서 가져온 예시 페이로드입니다.

다음은 서버가 반환하는 내용입니다.

클라이언트가 새 요청을 하면 서버는 스레드를 먼저 생성하고 그 다음에 턴을 생성합니다. 서버는 진행 상황에 대한 알림(thread/started 및 turn/started)을 다시 전송합니다. 또한 여기의 사용자 메시지처럼 아이템으로 등록된 입력을 다시 전송합니다.

도구 호출도 아이템으로 클라이언트에게 다시 전송됩니다. 또한 서버는 서버 요청을 보내 작업을 실행하기 전에 클라이언트의 승인을 요청할 수 있습니다. 승인을 요청하면 클라이언트가 “허용” 또는 “거부”로 응답할 때까지 턴이 일시 중지됩니다. VS Code 확장 프로그램에서 승인 흐름은 다음과 같습니다.

결국 서버는 에이전트 메시지를 보내고 turn/completed로 턴을 종료합니다. 에이전트 메시지 델타 이벤트는 메시지가 item/completed로 최종 완결될 때까지 메시지의 일부를 스트리밍합니다.

다이어그램의 메시지는 읽기 쉽게 간소화되었습니다. 전체 턴에 대한 JSON을 보려면 Codex CLI 리포지토리에서 테스트 클라이언트를 실행할 수 있습니다.

이제 App Server를 통해 다양한 클라이언트 서피스에서 Codex를 어떻게 임베드하는지 살펴보겠습니다. 여기서는 로컬 앱과 IDE, Codex 웹 런타임, TUI 세 가지 패턴을 다루겠습니다.

세 가지 모두, 전송 방식은 stdio를 통한 JSON-RPC(JSONL)입니다. JSON-RPC를 사용하면 원하는 언어로 클라이언트 바인딩을 쉽게 구축할 수 있습니다. Codex 서피스 및 파트너 통합은 Go, Python, TypeScript, Swift, Kotlin 등의 언어로 App Server 클라이언트를 구현했습니다. TypeScript의 경우 Rust 프로토콜에서 다음 명령을 실행하여 정의를 직접 생성할 수 있습니다.

다른 언어의 경우, 다음 명령을 실행하여 JSON 스키마 번들을 생성하고 선호하는 코드 생성기에 입력할 수 있습니다.

일반적으로 로컬 클라이언트는 플랫폼별 App Server 바이너리를 번들로 포함하거나 가져와서, 이를 장기 실행되는 하위 프로세스로 실행하며, JSON-RPC를 위해 양방향 stdio 채널을 열어 둡니다. 예를 들어, VS Code 확장 프로그램과 데스크톱 앱에서는 배포된 아티팩트에 플랫폼별 Codex 바이너리가 포함되며, 테스트 완료된 버전에 고정되어 있어 클라이언트가 항상 검증된 것과 정확히 일치하는 비트를 실행할 수 있습니다.

모든 통합이 클라이언트 업데이트를 자주 제공할 수 있는 것은 아닙니다. Xcode와 같은 일부 파트너는 클라이언트를 안정적으로 유지하고 필요할 때 최신 App Server 바이너리를 지목하도록 허용함으로써 릴리스 주기를 분리합니다. 그렇게 하면 클라이언트 릴리스를 기다리지 않고도 서버 측 개선사항(예: Codex 코어의 향상된 자동 컴팩션 또는 새로 지원되는 구성 키)을 적용하고 버그 수정을 배포할 수 있습니다. 앱 서버의 JSON-RPC 서피스는 이전 버전과의 호환성을 갖추도록 설계되어 구형 클라이언트도 신형 서버와 안전하게 통신할 수 있습니다.

Codex 웹은 Codex 하네스를 사용하지만 컨테이너 환경에서 실행됩니다. 작업자는 체크아웃된 워크스페이스로 컨테이너를 프로비저닝하고, 그 안에서 App Server 바이너리를 실행하며, stdio² 채널을 통해 장기 유지되는 JSON-RPC를 유지합니다. 웹 앱(사용자의 브라우저 탭에서 실행)은 HTTP 및 SSE를 통해 Codex 백엔드와 통신하여 작업자가 생성한 작업 이벤트를 스트리밍합니다. 이렇게 하면 브라우저 측 UI를 가볍게 유지하면서도 데스크톱과 웹 전반에서 일관된 런타임을 제공합니다.

웹 세션은 단기적(탭이 닫히고, 네트워크가 끊어짐)이기 때문에 웹 앱은 장시간 실행되는 작업의 신뢰할 수 있는 소스가 될 수 없습니다. 서버에서 상태와 진행 상황을 유지하면 탭이 사라지더라도 작업이 계속됩니다. 스트리밍 프로토콜과 저장된 스레드 세션 덕분에 새 세션이 쉽게 다시 연결되고, 중단된 곳에서 다시 시작하며, 클라이언트에서 상태를 다시 구축하지 않고도 만회할 수 있습니다.

이전에는 TUI는 에이전트 루프와 동일한 프로세스에서 실행되는 “네이티브” 클라이언트였으며 앱 서버 프로토콜이 아닌 Rust 코어 유형과 직접 통신했습니다. 그 덕분에 초기 반복 작업은 빨랐지만, TUI는 특별한 경우의 서피스가 되기도 했습니다.

이제 App Server가 존재하므로, App Server 하위 프로세스를 실행하고, stdio를 통해 JSON-RPC로 통신하며, 동일한 스트리밍 이벤트와 승인을 렌더링하는 등 다른 클라이언트처럼 작동하도록 이를 사용하여 TUI를 리팩터링⁠(새 창에서 열기)할 계획입니다. 이를 통해 TUI가 원격 머신에서 실행 중인 Codex 서버에 연결할 수 있는 워크플로를 활용하여 에이전트가 컴퓨팅 인프라와 밀접하게 연동되도록 하고, 노트북이 절전 모드로 전환되거나 연결이 끊기더라도 작업을 계속할 수 있으며, 로컬에서 라이브 업데이트와 제어 기능을 계속 제공할 수 있습니다.

Codex App Server는 앞으로 우리가 유지 관리할 최우선 통합 방식이지만, 기능이 더 제한적인 다른 방식도 있습니다. 기본적으로 Codex와의 통합을 위해 클라이언트가 Codex App Server를 사용하는 것이 바람직하지만, 다양한 통합 방법을 살펴보고 그 장단점을 이해하는 것도 가치가 있습니다. 아래는 Codex를 구동하는 가장 일반적인 방법과 각각의 방법이 언제 적합한지에 대한 설명입니다.

codex mcp-server⁠(새 창에서 열기)를 실행하고 stdio 서버를 지원하는 모든 MCP 클라이언트(예: OpenAI Agents SDK⁠(새 창에서 열기))에서 연결합니다. 이미 MCP 기반 워크플로가 있고 Codex를 호출 가능한 도구로 사용하고자 할 때 적합한 방법입니다. 단점은 MCP가 제공하는 것만 사용할 수 있기 때문에, 더 풍부한 세션 시맨틱(예: 차이 업데이트)에 의존하는 Codex 전용 상호작용은 MCP 엔드포인트를 통해 매끄럽게 매핑되지 않을 수 있다는 점입니다.

일부 생태계는 여러 모델 공급자와 런타임을 대상으로 할 수 있는 이식 가능한 인터페이스를 제공합니다. 여러 에이전트를 조율하는 단일 추상화가 필요할 때 적합한 방법입니다. 하지만 이러한 프로토콜이 종종 기능의 공통된 하위 집합으로 수렴된다는 단점이 있습니다. 특히 공급자별 도구 및 세션 시맨틱이 중요한 경우 더 풍부한 상호작용을 표현하기 어려울 수 있습니다. 이 분야는 빠르게 발전하고 있으며, 실제 에이전트 워크플로를 표현하는 데 가장 적합한 기본 요소를 파악함에 따라 더 많은 공통 표준이 등장할 것으로 예상합니다(가장 좋은 예: 스킬⁠(새 창에서 열기)).

전체 Codex 하네스를 안정적이고 UI 친화적인 이벤트 스트림으로 노출하려면 App Server를 선택합니다. 에이전트 루프의 전체 기능뿐만 아니라 ChatGPT로 로그인, 모델 탐색, 구성 관리와 같은 다른 지원 기능도 사용할 수 있습니다. 주요 비용은 통합 작업에서 발생합니다. 사용 중인 언어로 클라이언트 측 JSON-RPC 바인딩을 구축해야 하기 때문입니다. 하지만 실제로는 JSON 스키마와 문서를 제공하면 Codex가 다수의 복잡한 작업을 처리할 수 있습니다. 저희가 함께 작업한 많은 팀은 Codex를 사용하여 효과적인 통합을 신속하게 구현할 수 있었습니다.

일회성 작업 및 CI 실행을 위한 경량의 스크립트형 CLI 모드. 단일 명령을 비대화형으로 완료될 때까지 실행하고, 구조화된 출력을 스트리밍하여 로그에 기록하고, 명확한 성공 또는 실패 신호와 함께 종료하려는 자동화 및 파이프라인에 적합합니다.

자체 애플리케이션 내에서 로컬 Codex 에이전트를 프로그래밍 방식으로 제어할 수 있는 TypeScript 라이브러리입니다. 별도의 JSON-RPC 클라이언트를 구축하지 않고도 서버 측 도구와 워크플로를 위한 네이티브 라이브러리 인터페이스가 필요할 때 가장 적합합니다. App Server보다 먼저 출시되었기 때문에 현재 지원되는 언어가 더 적고 적용 범위도 더 좁습니다. 개발자들이 관심을 보인다면, 팀이 JSON-RPC 바인딩을 작성하지 않고도 하네스 서피스를 더 많이 커버할 수 있도록 App Server 프로토콜을 래핑하는 추가 SDK를 제공할 수도 있습니다.

이 게시글에서는 에이전트와 상호작용하기 위한 새로운 표준을 설계하는 방법과 Codex 하네스를 안정적이고 사용자 친화적인 프로토콜로 전환하는 방법을 공유했습니다. App Server가 Codex 코어를 노출하고, 클라이언트가 전체 에이전트 루프를 구동할 수 있게 하며, TUI, 로컬 IDE 통합, 웹 런타임을 비롯한 광범위한 서피스를 지원하는 방법을 다뤘습니다.

이를 통해 Codex를 자체 워크플로에 통합할 아이디어가 떠올랐다면 App Server를 사용해 보는 것도 좋습니다. 모든 소스 코드는 Codex CLI 오픈 소스 레포⁠(새 창에서 열기)에 있습니다. 여러분의 의견과 기능 요청을 마음 놓고 보내주시기 바랍니다. 여러분의 의견을 언제든지 환영하며 누구나 에이전트를 보다 쉽게 이용할 수 있도록 계속 개선해 나가겠습니다.