갑작스럽지만, Codex App Server를 알고 계시나요?

codex를 CLI에서 조작하는 대신, JSON-RPC를 통해 Codex 에이전트를 제어할 수 있는 것이 Codex App Server입니다.

즉, 직접 GUI나 TUI, 태스크 큐(Task Queue), 오케스트레이터(Orchestrator)를 만들 수 있습니다.

기사 자체는 템포를 중시하므로

사양 등 정확한 정보를 알고 싶은 분은 이 README.md를 참조해 주세요.

Codex App Server | README

Codex App Server의 기동 방법은

codex app-server

뿐입니다.

이렇게 하면 표준 입력(Standard Input) 대기 상태가 되므로, 이후에는 프로토콜에 따라 JSON (JSONL이므로 한 줄로 합칠 필요가 있습니다.)을 흘려보내면 프로그램으로부터 Codex App Server를 경유하여 에이전트를 실행시키고 작업을 수행하게 할 수 있습니다.

대화의 흐름

대화의 흐름은 다음과 같은 형태입니다.

• initialize용 메시지를 보내 서버를 초기화
• thread/start 메시지로 에이전트와의 Thread 시작
• turn/start로 에이전트에게 작업 지시
• turn/completed로 다음 작업 지시 대기 - 3.4를 반복
• 작업 완료

라는 형태입니다.

최소한의 개념 설명: Thread와 Turn

처음 제가 이해하려고 했을 때 이미지가 잘 떠오르지 않았기에,

설명을 넣어두자면,

Thread와 Turn의 관계는 이런 이미지입니다.

Thread:
├── Turn 1
│ User:
...

Thread가 Codex CLI의 세션(Session)과 같은 이미지이며, 대화의 1 랠리(Rally)가 Turn입니다.

핸즈온

Codex App Server는 JSON-RPC를 기본적으로 표준 입력으로 받아들이므로, 이 JSON을 기동한 서버에 복사/붙여넣기 하면 상주형 에이전트와 대화할 수 있습니다.

이 JSON을 한 줄로 만들어 터미널에 복사/붙여넣기 하면

{
"id": 1,
"method": "initialize",
...

이런 형태로 서버의 초기화가 완료됩니다.

% codex app-server
{"id":1,"method":"initialize","params":{"clientInfo":{"name":"tutorial","title":"Tutorial","version":"1.0"}}}
{"id":1,"result":{"userAgent":"tutorial/0.144.5 (Mac OS 26.5.0; arm64) xterm-256color (tutorial; 1.0)","codexHome":"~/.codex","platformFamily":"unix","platformOs":"macos"}}
...

다음은 thread/start 명령을 보내 에이전트의 대화를 시작합니다.

{"id":2,"method":"thread/start","params":{}}

이것을 보낸 결과가 이런 느낌이 됩니다.

조금 읽기 어려울 수도 있지만, thread/started
같은 표가 나타나고, mcp 서버가 시작해서라는 느낌으로 codex
명령어로 대화를 시작했을 때의 분위기가 느껴집니다.

다음으로 turn/start로 작업 지시를 내립니다.

이번에는 '안녕하세요! 자기소개해 주세요.'라는 지시를 내보겠습니다.

{"id":3,"method":"turn/start","params":{"threadId":"019f7960-95a5-7140-8749-a3cf59e0ffab","input":[{"type":"text","text":"안녕하세요! 자기소개해 주세요."}]}}

응답이 길기 때문에 아래에 모아두겠습니다.

응답

{"id":3,"result":{"turn":{"id":"019f7968-a116-7f13-bf24-c56fddd4373d","items":[],"itemsView":"notLoaded","status":"inProgress","error":null,"startedAt":null,"completedAt":null,"durationMs":null}}}
{"method":"thread/status/changed","params":{"threadId":"019f7960-95a5-7140-8749-a3cf59e0ffab","status":{"type":"active","activeFlags":[]}}}
{"method":"turn/started","params":{"threadId":"019f7960-95a5-7140-8749-a3cf59e0ffab","turn":{"id":"019f7968-a116-7f13-bf24-c56fddd4373d","items":[],"itemsView":"notLoaded","status":"inProgress","error":null,"startedAt":1784448327,"completedAt":null,"durationMs":null}}}
...

메인 응답 부분은 이런 느낌입니다.

좋게 자기소개를 해주고 있습니다.

{
"method": "item/completed",
"params": {
...

응답은 몇 개의 섹션으로 나뉘어 있는데, item/agentMessage/delta가 끊어지는 지시에 대한 답변을 반환하고, 그것을 모아주는 것이 item/completed 부분입니다.

여기까지로 일련의 흐름은 완료되었으므로, 이제 순서대로 turn/start 메시지를 보내면서 작업을 완료시키면 에이전트가 태스크를 완료할 수 있을 것입니다.

무엇이 좋은가

따라서, Codex로 평소 개발을 진행할 때는 codex 명령어로 대화형 콘솔(Interactive Console)을 열어 작업하시겠지만, Codex App Server를 로컬에 구축한 상태에서 App Server로 JSONL 요청을 보내도록 구성하면 다음과 같은 것들이 가능해집니다.

• Headless 방식으로 Codex 에이전트(Agent)를 다룰 수 있음
• 작업마다 codex 세션을 열어 하나씩 지시를 내릴 필요 없이, App Server에 JSONL을 던지기만 하면 됨
• GUI, TUI, Web 앱 등 자신만의 전용 클라이언트를 만들 수 있음

또한, OpenAI는 Codex Symphony와 같은 오케스트레이션(Orchestration)을 위한 사양도 제공하므로, 이를 기반으로 직접 오케스트레이터를 만들어 보는 것도 재미있을 것입니다.

Codex App Server로부터 오는 응답을 통해 에이전트의 상태도 모니터링할 수 있으므로, 이를 활용하여 Herdr와 같이 에이전트의 상태를 관리할 수 있는 기능을 포함한 도구를 만들어 보는 것도 흥미로운 시도가 될 것입니다.

Tasq: 자체 제작 OSS 소개

결과적으로 홍보가 되어버렸습니다만, 저 또한 이 Codex App Server를 활용한 OSS를 직접 제작했습니다. README에 있는 영상을 보시면 사용감을 쉽게 이해하실 수 있을 것입니다.

로컬에서 Issue 관리를 기본으로 하여,

Claude Code/Codex 등으로 작성한 Plan을 Backlog에 쌓아두면,

에이전트가 자동으로 PR(Pull Request) 생성까지 수행하도록 만드는 도구입니다.

여기까지 읽어주셔서 감사합니다. Tasq에도 관심이 있다면 한 번 사용해 보세요.

잘 부탁드립니다.

Discussion