🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

OpenAI는 여러 Codex 제품이 같은 에이전트 루프와 실행 로직을 재사용할 수 있도록, Codex harness를 양방향 JSON-RPC 기반 App Server로 노출하는 구조를 만들었다.

📌 핵심 요약

• Codex는 웹 앱, CLI, IDE 확장, macOS 앱 등 여러 표면에서 동작하지만, 내부적으로는 동일한 Codex harness가 에이전트 루프와 핵심 로직을 담당한다.
• App Server는 처음에는 VS Code 확장에서 TUI 기반 Codex harness를 재사용하기 위한 실용적 연결 계층으로 출발했지만, 이후 여러 제품과 파트너가 의존할 수 있는 표준 프로토콜 표면으로 발전했다.
• Codex harness에는 사용자·모델·도구를 조율하는 핵심 에이전트 루프뿐 아니라 스레드 생명주기와 영속성, 설정과 인증, 샌드박스 도구 실행 및 확장 통합이 포함된다.
• App Server는 장기 실행 프로세스로 Codex core thread를 호스팅하며, stdio reader와 메시지 처리기가 클라이언트의 JSON-RPC 요청을 Codex core 작업으로 바꾸고 내부 이벤트를 안정적인 UI용 알림으로 변환한다.
• 프로토콜은 Item, Turn, Thread라는 대화 primitive를 중심으로 설계되어 스트리밍 진행 상황, 도구 호출, 승인 요청, diff 같은 에이전트 작업 흐름을 다양한 클라이언트 UI가 일관되게 표현할 수 있게 한다.

🧩 주요 포인트

1. Codex는 웹 앱, CLI, IDE 확장, macOS 앱 등 여러 표면에서 동작하지만, 내부적으로는 동일한 Codex harness가 에이전트 루프와 핵심 로직을 담당한다.
2. App Server는 처음에는 VS Code 확장에서 TUI 기반 Codex harness를 재사용하기 위한 실용적 연결 계층으로 출발했지만, 이후 여러 제품과 파트너가 의존할 수 있는 표준 프로토콜 표면으로 발전했다.
3. Codex harness에는 사용자·모델·도구를 조율하는 핵심 에이전트 루프뿐 아니라 스레드 생명주기와 영속성, 설정과 인증, 샌드박스 도구 실행 및 확장 통합이 포함된다.
4. App Server는 장기 실행 프로세스로 Codex core thread를 호스팅하며, stdio reader와 메시지 처리기가 클라이언트의 JSON-RPC 요청을 Codex core 작업으로 바꾸고 내부 이벤트를 안정적인 UI용 알림으로 변환한다.
5. 프로토콜은 Item, Turn, Thread라는 대화 primitive를 중심으로 설계되어 스트리밍 진행 상황, 도구 호출, 승인 요청, diff 같은 에이전트 작업 흐름을 다양한 클라이언트 UI가 일관되게 표현할 수 있게 한다.

🧠 상세 정리

1. 여러 Codex 표면을 하나로 묶는 App Server

글은 Codex가 웹 앱, CLI, IDE 확장, 새 macOS 앱 등 다양한 사용 표면에 존재한다는 점에서 출발한다. 겉으로는 제품 형태가 다르지만, 모두 같은 Codex harness, 즉 에이전트 루프와 로직을 공유한다. 이 공통 harness를 각 클라이언트가 사용할 수 있게 해주는 핵심 연결부가 Codex App Server다. App Server는 클라이언트 친화적인 양방향 JSON-RPC API로 소개되며, 글 전체는 이 서버의 배경, 아키텍처, 프로토콜, 클라이언트 통합 방식을 설명하는 흐름으로 전개된다.

2. TUI에서 IDE로 확장하며 드러난 재사용 문제

Codex CLI는 처음에 터미널 사용자 인터페이스인 TUI 형태로 시작했다. 그러나 VS Code 확장을 만들면서, IDE UI에서도 같은 에이전트 루프를 구동하되 harness 자체를 다시 구현하지 않는 방법이 필요해졌다. IDE 환경에서는 단순 요청과 응답만으로 충분하지 않았고, 작업공간 탐색, 모델이 추론하는 동안의 진행 상황 스트리밍, diff 방출 같은 풍부한 상호작용이 요구됐다. OpenAI는 처음에 Codex를 MCP 서버로 노출하는 방식을 실험했지만, VS Code에 맞는 의미론을 유지하는 것이 어렵다고 판단했다.

3. 비공식 JSON-RPC에서 안정적 플랫폼 표면으로

MCP 방식이 적합하지 않자 팀은 TUI 루프를 반영하는 JSON-RPC 프로토콜을 도입했고, 이것이 App Server의 비공식 첫 버전이 되었다. 당시에는 다른 클라이언트가 이 서버에 의존할 것이라고 예상하지 않았기 때문에 안정적인 API로 설계되지는 않았다. 그러나 Codex 채택이 늘면서 내부 팀과 외부 파트너가 같은 harness를 자기 제품에 임베드하려는 요구가 커졌다. JetBrains와 Xcode는 IDE 수준의 에이전트 경험을 원했고, Codex 데스크톱 앱은 여러 Codex 에이전트를 병렬로 조율해야 했기 때문에, 장기적으로 의존 가능한 플랫폼 표면과 하위 호환성이 중요해졌다.

4. Codex harness 내부의 핵심 역할

글은 App Server를 이해하기 위해 먼저 Codex harness 안에 무엇이 있는지 설명한다. 핵심은 사용자, 모델, 도구 사이의 상호작용을 조율하는 에이전트 루프지만, 실제 에이전트 경험에는 그보다 더 많은 요소가 포함된다. Codex는 사용자와 에이전트의 대화 단위인 thread를 생성, 재개, fork, archive하고 이벤트 이력을 저장해 클라이언트가 다시 연결해도 일관된 타임라인을 렌더링할 수 있게 한다. 또한 설정과 기본값을 불러오고, ChatGPT 로그인 같은 인증 흐름과 credential 상태를 관리하며, sandbox 안에서 shell과 file 도구를 실행하고 MCP 서버나 skill 같은 확장을 일관된 정책 모델 아래 연결한다.

5. Codex core와 App Server의 아키텍처

이 모든 에이전트 로직은 Codex CLI 코드베이스 안의 Codex core라는 부분에 들어 있다. Codex core는 에이전트 코드가 위치한 라이브러리이면서, 하나의 Codex thread를 위해 에이전트 루프를 실행하고 영속성을 관리할 수 있는 런타임이기도 하다. App Server는 이 Codex core를 클라이언트가 사용할 수 있도록 노출하는 계층이며, 동시에 JSON-RPC 프로토콜이자 Codex core thread를 호스팅하는 장기 실행 프로세스다. 글에서 제시된 구조는 stdio reader, Codex message processor, thread manager, core threads라는 네 가지 주요 구성요소로 설명된다.

6. 요청을 이벤트 스트림으로 바꾸는 변환 계층

App Server 안에서 thread manager는 각 thread마다 하나의 core session을 띄우고, Codex message processor는 각 core session과 직접 통신해 클라이언트 요청을 제출하고 업데이트를 받는다. 하나의 클라이언트 요청은 많은 이벤트 업데이트로 이어질 수 있으며, 이 세부 이벤트들이 풍부한 UI를 만들 수 있는 근거가 된다. stdio reader와 Codex message processor는 클라이언트 JSON-RPC 요청을 Codex core 작업으로 번역하고, Codex core의 내부 이벤트 스트림을 안정적이고 UI가 다루기 쉬운 JSON-RPC notification으로 바꾼다. 또한 프로토콜은 완전히 양방향이어서, 서버가 승인 같은 입력을 요청하고 클라이언트 응답이 올 때까지 turn을 멈출 수도 있다.

7. Item, Turn, Thread라는 대화 primitive

글은 에이전트 루프용 API가 단순 요청·응답 모델로는 충분하지 않다고 설명하며, 세 가지 핵심 primitive를 제시한다. Item은 Codex의 입력과 출력의 원자 단위로, 사용자 메시지, 에이전트 메시지, 도구 실행, 승인 요청, diff처럼 타입이 지정된다. 각 Item은 item/started로 시작하고, 스트리밍 가능한 타입은 item/*/delta 이벤트를 거치며, item/completed로 완료되는 명시적 생명주기를 가진다. Turn은 사용자 입력으로 시작되는 에이전트 작업의 한 단위이고, Thread는 여러 Turn을 담는 지속 가능한 Codex 세션 컨테이너로 생성, 재개, fork, archive가 가능하며 이력이 저장된다.

8. 초기화, 승인, 완료로 이어지는 대화 흐름

단순화된 대화 예시에서 클라이언트와 서버는 먼저 initialize handshake를 수행한다. 클라이언트는 다른 메서드보다 먼저 단 한 번 initialize request를 보내야 하며, 서버는 응답을 통해 capability, 프로토콜 버전, feature flag, 기본값을 협의할 수 있다. 이후 클라이언트가 새 요청을 만들면 thread와 turn이 생성되고, 서버는 thread/started와 turn/started 같은 진행 notification을 보낸다. 도구 호출도 item으로 클라이언트에 전달되며, 실행 전 승인이 필요하면 서버 요청이 발생하고 클라이언트가 allow 또는 deny로 답할 때까지 turn이 일시 중지된다.

9. 로컬 앱, IDE, 웹 런타임에서의 통합 방식

글은 App Server를 임베드하는 방식으로 로컬 앱과 IDE, Codex 웹 런타임, TUI를 언급하며, 공통 전송 방식은 stdio 위의 JSON-RPC, 즉 JSONL이라고 설명한다. JSON-RPC를 사용하면 Go, Python, TypeScript, Swift, Kotlin 같은 여러 언어로 클라이언트 binding을 만들기 쉽고, TypeScript 정의나 JSON Schema 번들을 생성해 코드 생성기에 연결할 수도 있다. 로컬 클라이언트는 보통 플랫폼별 App Server binary를 bundle하거나 가져와 장기 실행 child process로 띄우고 bidirectional stdio channel을 유지한다. Codex Web은 container 안에서 App Server binary를 실행하고, 브라우저는 백엔드와 HTTP 및 SSE로 통신해 worker가 만든 task event를 스트리밍받는 구조로 설명된다.

🧾 핵심 주장 / 시사점

• 이 글의 핵심 설계 교훈은 에이전트 제품이 많아질수록 모델 호출 자체보다 thread, turn, item, 승인, 도구 실행, 이벤트 스트리밍을 안정적으로 표현하는 프로토콜 표면이 중요해진다는 점이다.
• App Server가 임시 내부 연결 계층에서 하위 호환성을 고려한 표준 API로 발전한 과정은, 처음에는 특정 UI를 위한 구현이었더라도 채택이 늘면 제품과 파트너가 함께 의존할 수 있는 플랫폼 계약으로 재설계해야 함을 보여준다.
• 웹, IDE, 데스크톱 앱이 같은 Codex core를 공유하도록 만든 구조는 클라이언트별 UI 차이를 허용하면서도 에이전트 실행 로직과 상태 관리를 중앙화해 일관된 사용자 경험을 만들려는 접근으로 읽힌다.

✅ 액션 아이템

• 웹 앱, CLI, IDE 확장, macOS 앱 간에 동일한 Codex harness와 에이전트 루프 전제를 공유하도록 인터페이스 기준을 정한다.
• App Server를 장기 실행 프로세스로 운영하며 stdio reader와 메시지 처리기가 JSON-RPC 요청을 Codex core 작업으로 안정 변환하도록 점검한다.
• Item, Turn, Thread 대화 primitive를 중심으로 스트리밍 진행·도구 호출·승인·diff 알림을 각 UI에서 동일 의미로 표현되게 매핑을 정비한다.

❓ 열린 질문

• JSON-RPC 요청 변환 경로에서 stdio reader와 메시지 처리기가 생성한 내부 이벤트 알림이 장기 실행 App Server에서 얼마나 일관되게 유지되는가?
• Codex harness의 사용자·모델·도구 조율이 포함된 스레드 생명주기와 영속성 구조가 다중 클라이언트에서 인증 동기화 충돌 없이 동작할 수 있는가?
• Item, Turn, Thread 구조 기반 이벤트가 클라이언트별 UI에서 도구 호출 승인 요청과 diff를 같은 해석으로 보여주도록 보장하는 기준은 무엇인가?