<div id="readability-page-1" class="page"><div><div tabindex="-1"><a rel="noopener follow" href="/?source=post_page---byline--666c2ca5dd76---------------------------------------" data-discover="true"><div><p><img alt="한정(Han Jung)" src="https://miro.medium.com/v2/resize:fill:64:64/1*tQfG8hfW5vM4hbRVZucMrg.png" width="32" height="32" loading="lazy" data-testid="authorPhoto"></p></div></a></div><blockquote><p id="1dc0"><em>원문: </em><a href="https://blog.bytebytego.com/p/how-openai-codex-works" rel="noopener ugc nofollow" target="_blank"><em>https://blog.bytebytego.com/p/how-openai-codex-works</em></a></p></blockquote><p id="aad4">OpenAI가 클라우드 기반 코딩 에이전트인 Codex를 출시했을 때, 해결해야 했던 가장 어려운 문제들은 AI 모델 자체와는 거의 관련이 없었습니다.</p><p id="5a28">codex-1 모델은 소프트웨어 엔지니어링에 맞게 파인튜닝된 OpenAI o3 버전입니다. 중요한 구성 요소였지만, 훨씬 더 큰 시스템의 일부에 불과했습니다. 실제 엔지니어링은 주변 모든 것에 있었습니다.</p><p id="74c5">올바른 프롬프트를 다섯 가지 출처에서 어떻게 조합할까요? 대화 기록이 너무 커져서 모델의 메모리 한계를 초과하려 할 때는 어떻게 될까요? 동일한 에이전트가 터미널, 웹 브라우저, 세 가지 IDE에서 각각 다시 작성하지 않고도 작동하게 하려면 어떻게 해야 할까요?</p><p id="bcb9">Codex 팀이 VS Code 내에서 에이전트를 동작시켜야 했을 때, 먼저 당연한 방법을 시도했습니다. AI 모델을 도구에 연결하는 신흥 표준인 MCP(Model Context Protocol)를 통해 노출하는 것이었습니다. 그 방법은 통하지 않았습니다. 실제 에이전트에 필요한 풍부한 상호작용 패턴들 — 스트리밍 진행 상황, 사용자 승인을 위한 작업 중 일시정지, 코드 diff 출력같은 부분은 MCP가 제공하는 것과 잘 맞지 않았습니다. 그래서 팀은 처음부터 새로운 프로토콜을 만들었습니다.</p><p id="6244">이 글에서는 OpenAI가 모델 주변에 올바른 오케스트레이션 레이어를 어떻게 구축했는지 살펴봅니다.</p><p id="356b"><em>면책 조항: 이 포스트는 OpenAI 엔지니어링 팀이 공개적으로 공유한 내용을 바탕으로 합니다. 부정확한 내용이 있으면 댓글로 알려주세요.</em></p><h2 id="04a7">Codex란 무엇인가요?</h2><p id="3900">Codex는 기능을 작성하고, 버그를 수정하고, 코드베이스에 관한 질문에 답하고, 풀 리퀘스트를 제안할 수 있는 코딩 에이전트입니다.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><p id="ff35"><em>출처: </em><a href="https://openai.com/index/introducing-codex/" rel="noopener ugc nofollow" target="_blank"><em>OpenAI 엔지니어링 블로그</em></a></p><p id="c4fa">각 태스크는 저장소가 미리 로드된 격리된 클라우드 샌드박스에서 실행됩니다. 여러 태스크를 병렬로 할당하고 실시간으로 진행 상황을 모니터링할 수 있습니다.</p><p id="4eef">Codex가 내부적으로 어떻게 작동하는지도 꽤 흥미롭습니다. 이 시스템에는 이해할 만한 세 가지 레이어가 있습니다. 에이전트 루프, 프롬프트 및 컨텍스트 관리, 그리고 하나의 에이전트가 다양한 인터페이스를 지원하게 하는 다중 인터페이스 아키텍처입니다.</p><h2 id="711f">에이전트 루프</h2><p id="0e06">Codex의 핵심에는 에이전트 루프라고 불리는 것이 있습니다. 에이전트는 사용자 입력을 받아 프롬프트를 구성하고, 추론을 위해 모델에 전달한 뒤 응답을 받습니다.</p><p id="820b">그런데 이 응답이 항상 최종 답변은 아닙니다. 모델이 툴 호출로 응답하는 경우도 많습니다. “이 셸 명령을 실행하고 무슨 일이 일어났는지 알려줘” 같은 형태입니다. 그런 경우 에이전트는 툴 호출을 실행하고, 출력을 프롬프트에 추가한 뒤, 이 새로운 정보를 담아 모델에 다시 요청합니다. 이 사이클은 모델이 최종적으로 사용자에게 메시지를 출력할 때까지 때로는 수십 번 반복됩니다.</p><p id="23a7">아래 다이어그램을 참고하세요.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><p id="76ad">이 과정을 단순한 루프 이상으로 만드는 것은 하네스가 그 과정에서 중간 중간 관리하는 모든 것 때문입니다.</p><p id="d087">Codex는 파일을 읽고 편집하고, 셸 명령을 실행하고, 테스트 슈트를 실행하고, 린터를 호출하고, 타입 체커를 실행할 수 있습니다. “auth 모듈의 버그를 수정해” 같은 단일 사용자 요청이 여러 파일 읽기, 기존 테스트 실행으로 실패 항목 확인, 코드 편집, 테스트 재실행, 린팅 오류 수정, 최종 커밋 전 한 번 더 테스트 실행까지 에이전트를 움직이게 할 수 있습니다.</p><p id="689c">모델은 각 단계에서 추론을 담당하지만, 하네스는 나머지 모든 것을 처리합니다. 명령 실행, 출력 수집, 권한 관리, 루프 종료 시점 결정 등이 여기에 해당합니다.</p><p id="81e2">모델과 하네스의 이 구분은 개발자들이 실제로 Codex를 사용하는 방식을 결정하기 때문에 중요합니다. OpenAI 자체 엔지니어링 팀도 리팩터링, 이름 변경, 테스트 작성, 온콜 이슈 분류 같은 반복적이고 범위가 명확한 작업을 Codex에 위임합니다.</p><p id="a26e">에이전트 루프에는 외부 레이어도 있습니다. 추론과 툴 호출의 각 사이클이 OpenAI가 “턴(turn)”이라고 부르는 것을 구성합니다. 그런데 대화는 한 번의 턴으로 끝나지 않습니다. 사용자가 후속 메시지를 보내면, 모든 툴 호출과 그 출력을 포함한 이전 턴의 전체 기록이 다음 프롬프트에 포함됩니다. 이 지점에서 비용이 커지기 시작하고, 다음 복잡성 레이어가 등장합니다.</p><p id="319c">아래 다이어그램을 참고하세요.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><h2 id="467b">프롬프트 구성과 메모리 관리</h2><p id="a63a">Codex에 요청을 입력하면, 여러분의 메시지는 훨씬 더 큰 프롬프트의 맨 아래 레이어가 됩니다. 그 위로 시스템은 환경 컨텍스트를 쌓습니다. 현재 작업 디렉터리와 셸, 저장소 내 AGENTS.md 파일의 내용(코딩 규칙이나 실행할 테스트 명령 등 에이전트를 위한 프로젝트별 지침), 샌드박스 권한 규칙, 설정 파일의 개발자 지침, 모델 전용 지침, 툴 정의, 그리고 시스템 메시지입니다.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><p id="9e42"><em>출처: </em><a href="https://openai.com/index/unrolling-the-codex-agent-loop/" rel="noopener ugc nofollow" target="_blank"><em>OpenAI 엔지니어링 블로그</em></a></p><p id="720e">각 레이어에는 시스템, 개발자, 또는 사용자 중 하나의 역할이 있으며, 이는 모델에 우선순위를 알려줍니다. 상위 레이어의 순서는 서버가 제어하고, 나머지는 클라이언트가 제어합니다. 이 계층적 구성 덕분에 모델은 항상 자신이 동작하는 환경에 관한 풍부한 컨텍스트를 갖습니다. 하지만 사용자가 한 마디도 하기 전에 프롬프트가 이미 크다는 것을 의미하기도 합니다. 그리고 이후에는 계속 커질 뿐입니다.</p><p id="51e7">모델이 수행하는 모든 툴 호출은 프롬프트에 추가될 출력을 생성합니다. 새로운 대화 턴마다 이전 모든 턴의 전체 기록(툴 호출 포함)이 포함됩니다.</p><p id="1f21">아래 다이어그램을 참고하세요.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><p id="7b1a"><em>출처: </em><a href="https://openai.com/index/unrolling-the-codex-agent-loop/" rel="noopener ugc nofollow" target="_blank"><em>OpenAI 엔지니어링 블로그</em></a></p><p id="7e52">즉, 대화가 진행되면서 API에 전송되는 총 JSON 데이터는 이차함수적으로 증가합니다. 첫 번째 턴이 X만큼의 데이터를 보내면, 두 번째 턴은 X 전체와 새 데이터를 다시 보내고, 세 번째 턴은 그 모두에 더 많은 데이터를 더하는 방식입니다.</p><p id="2727">OpenAI는 이 비용을 의도적으로 감수합니다. API가 이전 대화 상태를 기억하게 하는 서버 사이드 파라미터를 사용하면 매번 모든 것을 재전송하지 않아도 됩니다. 하지만 그렇게 하면 각 요청의 무상태성이 깨지고, 제로 데이터 보존(Zero Data Retention)을 요구하는 고객 지원이 불가능해집니다. 따라서 모든 요청은 자체적으로 완결되며 전체 대화 내용을 담고 있습니다.</p><p id="8847">핵심 완화 수단은 프롬프트 캐싱입니다. Codex는 항상 기존 프롬프트 끝에 새 내용을 추가하므로, 이전 프롬프트는 항상 새 프롬프트의 정확한 프리픽스가 됩니다. 이 프리픽스 속성 덕분에 OpenAI는 이전 추론 호출의 계산 결과를 재사용할 수 있어, 데이터 전송량은 이차함수적으로 증가하더라도 실제 모델 계산은 선형에 가깝게 유지됩니다.</p><p id="ec7e">그런데 프리픽스 속성은 깨지기 쉽습니다. 프롬프트의 앞이나 중간을 변경하는 것 즉 모델 교체, 툴 변경, 샌드박스 설정 변경 등의 작업은 캐시를 사용할 수 없게 됩니다. OpenAI가 MCP 툴 지원을 추가했을 때, 실수로 요청 간 툴 목록이 일관된 순서로 나열되지 않는 버그를 만들어 냈습니다. 그 비일관성만으로도 캐시 히트를 파괴하기에 충분했습니다.</p><p id="901c">결국 캐싱을 사용하더라도, 대화는 컨텍스트 윈도우 한계, 즉 모델이 단일 추론 호출에서 처리할 수 있는 최대 토큰 수에 도달합니다. 그런 경우 Codex는 대화를 압축합니다. 전체 기록을 더 작고 대표적인 버전으로 대체하는데, 암호화된 페이로드를 통해 무슨 일이 있었는지에 관한 모델의 잠재 상태를 보존합니다. 실제로 압축 메커니즘은 단순한 요약보다 더 복잡하지만, 핵심 아이디어는 같습니다. 컨텍스트 윈도우 관리는 사후에 생각하는 문제가 아닌, 최우선 엔지니어링 과제입니다.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><p id="29dc">AGENTS.md 파일은 컨텍스트를 어디에 두어야 하는지에 관한 설계 결정을 보여주기 때문에 잠깐 언급할 가치가 있습니다. 프로젝트별 지식을 시스템에 하드코딩하는 대신, OpenAI는 개발자들이 저장소 내 코드 옆에 AGENTS.md 파일을 배치할 수 있게 합니다. 이 파일들은 코드베이스를 탐색하는 방법, 테스트를 위해 실행할 명령, 프로젝트의 규칙을 따르는 방법을 Codex에 알려줍니다. 모델은 이 파일이 있으면 더 잘 동작하지만, 없어도 작동합니다.</p><h2 id="f12e">모든 곳에서 작동하게 만들기</h2><p id="5a4c">Codex는 CLI 도구로 시작했습니다. 터미널에서 실행하면 로컬 코드베이스에서 작동했습니다.</p><p id="42e4">그러다 OpenAI는 VS Code에서도 필요했고, 이어서 웹 앱에서도 필요했습니다. macOS 데스크톱 앱도 필요했고, JetBrains나 Xcode 같은 서드파티 IDE도 통합을 원했습니다. 모든 인터페이스마다 에이전트 로직을 다시 작성하는 것은 선택지가 아니었습니다.</p><p id="d242">앞서 언급했듯이, 첫 번째 시도는 Codex를 MCP 서버로 노출하는 것이었습니다. 하지만 팀은 MCP의 시맨틱이 에이전트 대화의 실제 모습을 감당할 수 없다는 것을 알게 됐습니다. Codex는 모델이 추론하는 동안 점진적인 진행 상황을 스트리밍해야 했습니다. 특정 명령을 실행하기 전에 작업 중간에 멈추고 사용자의 승인을 요청해야 했습니다. 구조화된 diff를 출력해야 했습니다. 이러한 상호작용 패턴은 당시 MCP가 제공하는 것보다 훨씬 풍부했습니다.</p><p id="3b47">그래서 팀은 앱 서버를 구축했습니다. 에이전트 루프, 스레드 관리, 툴 실행, 설정, 인증 등 모든 핵심 에이전트 로직이 OpenAI가 “Codex 코어”라고 부르는 단일 코드베이스에 있습니다. 앱 서버는 이 코어를 JSON-RPC 프로토콜로 감싸며, 어떤 클라이언트든 표준 입출력(stdio)을 통해 통신할 수 있습니다.</p><p id="b67e">이 프로토콜은 완전히 양방향입니다.</p><ul><li id="6377">클라이언트는 서버에 요청을 보낼 수 있습니다 (스레드 시작, 태스크 제출).</li><li id="68a9">서버도 클라이언트에 요청을 보낼 수 있습니다. 예를 들어, 셸 명령을 실행하기 전에 승인을 요청하는 경우입니다.</li></ul><p id="2857">에이전트의 턴은 사용자가 “허용” 또는 “거부”로 응답할 때까지 일시정지됩니다. 이를 통해 에이전트는 자율성과 인간 감독 사이의 균형을 유지할 수 있으며, 그 정책을 에이전트 루프에 하드코딩할 필요가 없습니다.</p><p id="f560"><strong>서로 다른 인터페이스는 이 아키텍처를 다르게 활용합니다.</strong></p><p id="69d0">VS Code 확장과 데스크톱 앱은 앱 서버 바이너리를 번들로 포함하고, 자식 프로세스로 실행하며, 양방향 stdio 채널을 유지합니다.</p><p id="5b07">웹 앱은 클라우드 컨테이너 안에서 앱 서버를 실행합니다. 워커가 체크아웃된 저장소로 컨테이너를 프로비저닝하고, 바이너리를 실행한 뒤, HTTP를 통해 브라우저에 이벤트를 스트리밍합니다. 상태는 서버에 있어, 사용자가 탭을 닫아도 작업은 계속됩니다.</p><p id="f064">Xcode 같은 파트너들은 클라이언트를 안정적으로 유지하고 새로운 앱 서버 바이너리를 가리키는 방식으로 OpenAI의 릴리스 주기와 분리된 자체 릴리스 주기를 유지합니다. 프로토콜은 하위 호환성을 갖추도록 설계되어, 이전 클라이언트도 새 서버와 안전하게 통신할 수 있습니다.</p><figure><div role="button" tabindex="0"><p><span>Press enter or click to view image in full size</span></p></div></figure><p id="5f13">이 아키텍처는 처음부터 계획된 것이 아니었습니다. CLI에서 시작해, 실패한 MCP 시도를 거쳐, 현재 모든 Codex 인터페이스의 기반이 된 앱 서버 프로토콜로 발전했습니다. 이 여정 자체가 시스템 설계에 관한 유용한 교훈입니다. 올바른 추상화는 대개 잘못된 것을 먼저 시도해봐야 생깁니다.</p><h2 id="6c3e">결론</h2><p id="78bf">OpenAI의 경험이 증명합니다. 모델은 하나의 컴포넌트이고, 에이전트가 시스템입니다. 대부분의 엔지니어링은 시스템에 있습니다.</p><p id="3750">Codex 같은 도구를 사용한다면, 이 메커니즘을 이해하는 것이 더 효과적으로 활용하는 데 도움이 됩니다. 명확한 AGENTS.md 파일을 작성하면 에이전트에 프로젝트별 컨텍스트를 제공해 출력 품질을 의미 있게 향상시킵니다. 태스크 범위를 좁게 설정하는 것이 모호하고 열린 요청보다 효과적입니다. 에이전트 루프는 각 사이클에 명확한 다음 단계가 있을 때 가장 효율적으로 동작하기 때문입니다. 또한 긴 대화가 컨텍스트 윈도우 한계와 압축으로 인해 성능이 저하된다는 것을 알면, 새로운 태스크마다 새 스레드를 시작하는 것이 왜 더 나은 결과를 내는지 이해할 수 있습니다.</p><p id="2058">Codex에는 여전히 실제적인 한계가 있습니다. 프런트엔드 작업을 위한 이미지 입력을 받지 못합니다. 작업 중간에 에이전트 방향을 수정할 수 없습니다. 원격 에이전트에 위임하는 것은 대화형 편집보다 시간이 더 걸리며, 그 워크플로우 전환에 적응하는 데 시간이 필요합니다. OpenAI는 Codex와의 상호작용이 동료와의 비동기 협업처럼 느껴지는 미래를 지향하고 있지만, 그 비전과 현재 제품 사이의 간극은 아직 상당합니다.</p><h2 id="2d99">참고 자료</h2><ul><li id="5a3d"><a href="https://openai.com/index/introducing-codex/" rel="noopener ugc nofollow" target="_blank">Introducing Codex</a></li><li id="c17a"><a href="https://openai.com/index/unrolling-the-codex-agent-loop/" rel="noopener ugc nofollow" target="_blank">Unrolling the Codex agent loop</a></li><li id="30e2"><a href="https://openai.com/index/unlocking-the-codex-harness/" rel="noopener ugc nofollow" target="_blank">Unrolling the Codex harness: how we built the App Server</a></li></ul></div></div>

Stories by Jung Han on Medium

한정

원문: https://blog.bytebytego.com/p/how-openai-codex-works
OpenAI가 클라우드 기반 코딩 에이전트인 Codex를 출시했을 때, 해결해야 했던 가장 어려운 문제들은 AI 모델 자체와는 거의 관련이 없었습니다.
codex-1 모델은 소프트웨어 엔지니어링에 맞게 파인튜닝된 OpenAI o3 버전입니다. 중요한 구성 요소였지만, 훨씬 더 큰 시스템의 일부에 불과했습니다. 실제 엔지니어링은 주변 모든 것에 있었습니다.
올바른 프롬프트를 다섯 가지 출처에서 어떻게 조합할까요? 대화 기록이 너무 커져서 모델의 메모리 한계를 초과하려 할 때는 어떻게 될까요? 동일한 에이전트가 터미널, 웹 브라우저, 세 가지 IDE에서 각각 다시 작성하지 않고도 작동하게 하려면 어떻게 해야 할까요?
Codex 팀이 VS Code 내에서 에이전트를 동작시켜야 했을 때, 먼저 당연한 방법을 시도했습니다. AI 모델을 도구에 연결하는 신흥 표준인 MCP(Model Context Protocol)를 통해 노출하는 것이었습니다. 그 방법은 통하지 않았습니다. 실제 에이전트에 필요한 풍부한 상호작용 패턴들 — 스트리밍 진행 상황, 사용자 승인을 위한 작업 중 일시정지, 코드 diff 출력같은 부분은 MCP가 제공하는 것과 잘 맞지 않았습니다. 그래서 팀은 처음부터 새로운 프로토콜을 만들었습니다.
이 글에서는 OpenAI가 모델 주변에 올바른 오케스트레이션 레이어를 어떻게 구축했는지 살펴봅니다.
면책 조항: 이 포스트는 OpenAI 엔지니어링 팀이 공개적으로 공유한 내용을 바탕으로 합니다. 부정확한 내용이 있으면 댓글로 알려주세요.
Codex란 무엇인가요?
Codex는 기능을 작성하고, 버그를 수정하고, 코드베이스에 관한 질문에 답하고, 풀 리퀘스트를 제안할 수 있는 코딩 에이전트입니다.
출처: OpenAI 엔지니어링 블로그
각 태스크는 저장소가 미리 로드된 격리된 클라우드 샌드박스에서 실행됩니다. 여러 태스크를 병렬로 할당하고 실시간으로 진행 상황을 모니터링할 수 있습니다.
Codex가 내부적으로 어떻게 작동하는지도 꽤 흥미롭습니다. 이 시스템에는 이해할 만한 세 가지 레이어가 있습니다. 에이전트 루프, 프롬프트 및 컨텍스트 관리, 그리고 하나의 에이전트가 다양한 인터페이스를 지원하게 하는 다중 인터페이스 아키텍처입니다.
에이전트 루프
Codex의 핵심에는 에이전트 루프라고 불리는 것이 있습니다. 에이전트는 사용자 입력을 받아 프롬프트를 구성하고, 추론을 위해 모델에 전달한 뒤 응답을 받습니다.
그런데 이 응답이 항상 최종 답변은 아닙니다. 모델이 툴 호출로 응답하는 경우도 많습니다. “이 셸 명령을 실행하고 무슨 일이 일어났는지 알려줘” 같은 형태입니다. 그런 경우 에이전트는 툴 호출을 실행하고, 출력을 프롬프트에 추가한 뒤, 이 새로운 정보를 담아 모델에 다시 요청합니다. 이 사이클은 모델이 최종적으로 사용자에게 메시지를 출력할 때까지 때로는 수십 번 반복됩니다.
아래 다이어그램을 참고하세요.
이 과정을 단순한 루프 이상으로 만드는 것은 하네스가 그 과정에서 중간 중간 관리하는 모든 것 때문입니다.
Codex는 파일을 읽고 편집하고, 셸 명령을 실행하고, 테스트 슈트를 실행하고, 린터를 호출하고, 타입 체커를 실행할 수 있습니다. “auth 모듈의 버그를 수정해” 같은 단일 사용자 요청이 여러 파일 읽기, 기존 테스트 실행으로 실패 항목 확인, 코드 편집, 테스트 재실행, 린팅 오류 수정, 최종 커밋 전 한 번 더 테스트 실행까지 에이전트를 움직이게 할 수 있습니다.
모델은 각 단계에서 추론을 담당하지만, 하네스는 나머지 모든 것을 처리합니다. 명령 실행, 출력 수집, 권한 관리, 루프 종료 시점 결정 등이 여기에 해당합니다.
모델과 하네스의 이 구분은 개발자들이 실제로 Codex를 사용하는 방식을 결정하기 때문에 중요합니다. OpenAI 자체 엔지니어링 팀도 리팩터링, 이름 변경, 테스트 작성, 온콜 이슈 분류 같은 반복적이고 범위가 명확한 작업을 Codex에 위임합니다.
에이전트 루프에는 외부 레이어도 있습니다. 추론과 툴 호출의 각 사이클이 OpenAI가 “턴(turn)”이라고 부르는 것을 구성합니다. 그런데 대화는 한 번의 턴으로 끝나지 않습니다. 사용자가 후속 메시지를 보내면, 모든 툴 호출과 그 출력을 포함한 이전 턴의 전체 기록이 다음 프롬프트에 포함됩니다. 이 지점에서 비용이 커지기 시작하고, 다음 복잡성 레이어가 등장합니다.
아래 다이어그램을 참고하세요.
프롬프트 구성과 메모리 관리
Codex에 요청을 입력하면, 여러분의 메시지는 훨씬 더 큰 프롬프트의 맨 아래 레이어가 됩니다. 그 위로 시스템은 환경 컨텍스트를 쌓습니다. 현재 작업 디렉터리와 셸, 저장소 내 AGENTS.md 파일의 내용(코딩 규칙이나 실행할 테스트 명령 등 에이전트를 위한 프로젝트별 지침), 샌드박스 권한 규칙, 설정 파일의 개발자 지침, 모델 전용 지침, 툴 정의, 그리고 시스템 메시지입니다.
출처: OpenAI 엔지니어링 블로그
각 레이어에는 시스템, 개발자, 또는 사용자 중 하나의 역할이 있으며, 이는 모델에 우선순위를 알려줍니다. 상위 레이어의 순서는 서버가 제어하고, 나머지는 클라이언트가 제어합니다. 이 계층적 구성 덕분에 모델은 항상 자신이 동작하는 환경에 관한 풍부한 컨텍스트를 갖습니다. 하지만 사용자가 한 마디도 하기 전에 프롬프트가 이미 크다는 것을 의미하기도 합니다. 그리고 이후에는 계속 커질 뿐입니다.
모델이 수행하는 모든 툴 호출은 프롬프트에 추가될 출력을 생성합니다. 새로운 대화 턴마다 이전 모든 턴의 전체 기록(툴 호출 포함)이 포함됩니다.
아래 다이어그램을 참고하세요.
출처: OpenAI 엔지니어링 블로그
즉, 대화가 진행되면서 API에 전송되는 총 JSON 데이터는 이차함수적으로 증가합니다. 첫 번째 턴이 X만큼의 데이터를 보내면, 두 번째 턴은 X 전체와 새 데이터를 다시 보내고, 세 번째 턴은 그 모두에 더 많은 데이터를 더하는 방식입니다.
OpenAI는 이 비용을 의도적으로 감수합니다. API가 이전 대화 상태를 기억하게 하는 서버 사이드 파라미터를 사용하면 매번 모든 것을 재전송하지 않아도 됩니다. 하지만 그렇게 하면 각 요청의 무상태성이 깨지고, 제로 데이터 보존(Zero Data Retention)을 요구하는 고객 지원이 불가능해집니다. 따라서 모든 요청은 자체적으로 완결되며 전체 대화 내용을 담고 있습니다.
핵심 완화 수단은 프롬프트 캐싱입니다. Codex는 항상 기존 프롬프트 끝에 새 내용을 추가하므로, 이전 프롬프트는 항상 새 프롬프트의 정확한 프리픽스가 됩니다. 이 프리픽스 속성 덕분에 OpenAI는 이전 추론 호출의 계산 결과를 재사용할 수 있어, 데이터 전송량은 이차함수적으로 증가하더라도 실제 모델 계산은 선형에 가깝게 유지됩니다.
그런데 프리픽스 속성은 깨지기 쉽습니다. 프롬프트의 앞이나 중간을 변경하는 것 즉 모델 교체, 툴 변경, 샌드박스 설정 변경 등의 작업은 캐시를 사용할 수 없게 됩니다. OpenAI가 MCP 툴 지원을 추가했을 때, 실수로 요청 간 툴 목록이 일관된 순서로 나열되지 않는 버그를 만들어 냈습니다. 그 비일관성만으로도 캐시 히트를 파괴하기에 충분했습니다.
결국 캐싱을 사용하더라도, 대화는 컨텍스트 윈도우 한계, 즉 모델이 단일 추론 호출에서 처리할 수 있는 최대 토큰 수에 도달합니다. 그런 경우 Codex는 대화를 압축합니다. 전체 기록을 더 작고 대표적인 버전으로 대체하는데, 암호화된 페이로드를 통해 무슨 일이 있었는지에 관한 모델의 잠재 상태를 보존합니다. 실제로 압축 메커니즘은 단순한 요약보다 더 복잡하지만, 핵심 아이디어는 같습니다. 컨텍스트 윈도우 관리는 사후에 생각하는 문제가 아닌, 최우선 엔지니어링 과제입니다.
AGENTS.md 파일은 컨텍스트를 어디에 두어야 하는지에 관한 설계 결정을 보여주기 때문에 잠깐 언급할 가치가 있습니다. 프로젝트별 지식을 시스템에 하드코딩하는 대신, OpenAI는 개발자들이 저장소 내 코드 옆에 AGENTS.md 파일을 배치할 수 있게 합니다. 이 파일들은 코드베이스를 탐색하는 방법, 테스트를 위해 실행할 명령, 프로젝트의 규칙을 따르는 방법을 Codex에 알려줍니다. 모델은 이 파일이 있으면 더 잘 동작하지만, 없어도 작동합니다.
모든 곳에서 작동하게 만들기
Codex는 CLI 도구로 시작했습니다. 터미널에서 실행하면 로컬 코드베이스에서 작동했습니다.
그러다 OpenAI는 VS Code에서도 필요했고, 이어서 웹 앱에서도 필요했습니다. macOS 데스크톱 앱도 필요했고, JetBrains나 Xcode 같은 서드파티 IDE도 통합을 원했습니다. 모든 인터페이스마다 에이전트 로직을 다시 작성하는 것은 선택지가 아니었습니다.
앞서 언급했듯이, 첫 번째 시도는 Codex를 MCP 서버로 노출하는 것이었습니다. 하지만 팀은 MCP의 시맨틱이 에이전트 대화의 실제 모습을 감당할 수 없다는 것을 알게 됐습니다. Codex는 모델이 추론하는 동안 점진적인 진행 상황을 스트리밍해야 했습니다. 특정 명령을 실행하기 전에 작업 중간에 멈추고 사용자의 승인을 요청해야 했습니다. 구조화된 diff를 출력해야 했습니다. 이러한 상호작용 패턴은 당시 MCP가 제공하는 것보다 훨씬 풍부했습니다.
그래서 팀은 앱 서버를 구축했습니다. 에이전트 루프, 스레드 관리, 툴 실행, 설정, 인증 등 모든 핵심 에이전트 로직이 OpenAI가 “Codex 코어”라고 부르는 단일 코드베이스에 있습니다. 앱 서버는 이 코어를 JSON-RPC 프로토콜로 감싸며, 어떤 클라이언트든 표준 입출력(stdio)을 통해 통신할 수 있습니다.
이 프로토콜은 완전히 양방향입니다.
클라이언트는 서버에 요청을 보낼 수 있습니다 (스레드 시작, 태스크 제출).
서버도 클라이언트에 요청을 보낼 수 있습니다. 예를 들어, 셸 명령을 실행하기 전에 승인을 요청하는 경우입니다.
에이전트의 턴은 사용자가 “허용” 또는 “거부”로 응답할 때까지 일시정지됩니다. 이를 통해 에이전트는 자율성과 인간 감독 사이의 균형을 유지할 수 있으며, 그 정책을 에이전트 루프에 하드코딩할 필요가 없습니다.
서로 다른 인터페이스는 이 아키텍처를 다르게 활용합니다.
VS Code 확장과 데스크톱 앱은 앱 서버 바이너리를 번들로 포함하고, 자식 프로세스로 실행하며, 양방향 stdio 채널을 유지합니다.
웹 앱은 클라우드 컨테이너 안에서 앱 서버를 실행합니다. 워커가 체크아웃된 저장소로 컨테이너를 프로비저닝하고, 바이너리를 실행한 뒤, HTTP를 통해 브라우저에 이벤트를 스트리밍합니다. 상태는 서버에 있어, 사용자가 탭을 닫아도 작업은 계속됩니다.
Xcode 같은 파트너들은 클라이언트를 안정적으로 유지하고 새로운 앱 서버 바이너리를 가리키는 방식으로 OpenAI의 릴리스 주기와 분리된 자체 릴리스 주기를 유지합니다. 프로토콜은 하위 호환성을 갖추도록 설계되어, 이전 클라이언트도 새 서버와 안전하게 통신할 수 있습니다.
이 아키텍처는 처음부터 계획된 것이 아니었습니다. CLI에서 시작해, 실패한 MCP 시도를 거쳐, 현재 모든 Codex 인터페이스의 기반이 된 앱 서버 프로토콜로 발전했습니다. 이 여정 자체가 시스템 설계에 관한 유용한 교훈입니다. 올바른 추상화는 대개 잘못된 것을 먼저 시도해봐야 생깁니다.
결론
OpenAI의 경험이 증명합니다. 모델은 하나의 컴포넌트이고, 에이전트가 시스템입니다. 대부분의 엔지니어링은 시스템에 있습니다.
Codex 같은 도구를 사용한다면, 이 메커니즘을 이해하는 것이 더 효과적으로 활용하는 데 도움이 됩니다. 명확한 AGENTS.md 파일을 작성하면 에이전트에 프로젝트별 컨텍스트를 제공해 출력 품질을 의미 있게 향상시킵니다. 태스크 범위를 좁게 설정하는 것이 모호하고 열린 요청보다 효과적입니다. 에이전트 루프는 각 사이클에 명확한 다음 단계가 있을 때 가장 효율적으로 동작하기 때문입니다. 또한 긴 대화가 컨텍스트 윈도우 한계와 압축으로 인해 성능이 저하된다는 것을 알면, 새로운 태스크마다 새 스레드를 시작하는 것이 왜 더 나은 결과를 내는지 이해할 수 있습니다.
Codex에는 여전히 실제적인 한계가 있습니다. 프런트엔드 작업을 위한 이미지 입력을 받지 못합니다. 작업 중간에 에이전트 방향을 수정할 수 없습니다. 원격 에이전트에 위임하는 것은 대화형 편집보다 시간이 더 걸리며, 그 워크플로우 전환에 적응하는 데 시간이 필요합니다. OpenAI는 Codex와의 상호작용이 동료와의 비동기 협업처럼 느껴지는 미래를 지향하고 있지만, 그 비전과 현재 제품 사이의 간극은 아직 상당합니다.
참고 자료
Introducing Codex
Unrolling the Codex agent loop
Unrolling the Codex harness: how we built the App Server

(번역)OpenAI Codex의 작동 원리

댓글