▲

Codex 에이전트 루프 해체하기

 (openai.com)
1P by GN⁺ 9시간전 | ★ favorite | 댓글 1개
  • Codex CLI는 로컬 환경에서 안전하고 효율적으로 고품질 소프트웨어 변경을 수행하는 에이전트로 설계됨
  • 핵심 구조인 에이전트 루프(agent loop) 는 사용자 입력, 모델 추론, 도구 호출을 순환적으로 연결해 의미 있는 작업을 수행
  • 루프 과정에서 생성되는 프롬프트 구성, 컨텍스트 윈도 관리, 프롬프트 캐싱이 성능과 안정성의 핵심 요소로 작동
  • Codex는 Responses API를 통해 모델과 통신하며, 각 요청은 완전한 JSON 페이로드로 구성되어 무상태(stateless) 동작을 유지
  • 이러한 구조는 Zero Data Retention(ZDR) , 프롬프트 캐싱, 자동 압축(compaction) 등 고급 기능을 가능하게 하며, 대규모 에이전트 설계의 기반을 형성

Codex 에이전트 루프 개요

  • Codex CLI는 사용자, 모델, 도구 간 상호작용을 조율하는 루프 구조를 중심으로 동작
    • 사용자의 입력을 받아 모델에 전달할 프롬프트(prompt) 를 구성
    • 모델이 응답을 생성하거나 도구 호출(tool call) 을 요청하면, 에이전트가 이를 실행하고 결과를 다시 프롬프트에 추가
    • 모델이 더 이상 도구 호출을 하지 않고 assistant 메시지를 생성하면 한 턴이 종료됨
  • 각 턴은 대화(conversation) 의 일부로, 이전 메시지와 도구 호출 내역이 모두 다음 요청의 프롬프트에 포함됨
  • 프롬프트 길이는 모델의 컨텍스트 윈도(context window) 제한에 영향을 받기 때문에, Codex는 이를 관리해야 함

Responses API와 Codex의 통신 구조

  • Codex CLI는 모델 추론을 위해 Responses API에 HTTP 요청을 보냄
    • API 엔드포인트는 설정에 따라 다르며, OpenAI, ChatGPT, Azure, 로컬(LM Studio, Ollama 등) 환경에서 모두 사용 가능
  • API 요청은 JSON 페이로드로 구성되며 주요 필드는 다음과 같음
    • system/developer 메시지: 모델의 기본 맥락 설정
    • instructions: 모델이 호출할 수 있는 도구 목록
    • tools: Codex CLI, Responses API, 사용자(MCP 서버 등)가 제공하는 도구 정의
    • input: 대화 내역 및 환경 정보를 포함한 메시지 리스트
  • Codex는 ~/.codex/config.toml 설정과 프로젝트 내 AGENTS.md, skills 파일 등을 읽어 사용자 지침과 환경 정보를 자동 삽입

프롬프트 구성과 이벤트 처리

  • Codex는 각 메시지를 JSON 객체(type, role, content)로 구성해 Responses API에 전송
  • 서버는 이 JSON을 기반으로 모델 프롬프트를 생성하고, SSE(Server-Sent Events) 스트림으로 응답을 반환
    • response.output_text.delta 이벤트는 스트리밍 출력에 사용
    • response.output_item.added 이벤트는 다음 요청의 input에 추가되어 루프를 지속
  • 이전 프롬프트가 새 프롬프트의 정확한 접두(prefix) 가 되도록 설계되어, 프롬프트 캐싱(prompt caching) 을 활용 가능

성능 최적화: 캐싱과 무상태 설계

  • Codex는 previous_response_id를 사용하지 않아 완전한 무상태(stateless) 요청 구조를 유지
    • 이는 Zero Data Retention(ZDR) 고객 지원과 데이터 보존 최소화를 가능하게 함
  • 프롬프트 캐싱은 동일한 접두부를 재사용해 샘플링 비용을 선형화(linear) 함
    • 캐시 히트는 프롬프트의 정확한 접두 일치에서만 발생
    • 도구 목록, 모델, 샌드박스 설정, 작업 디렉터리 변경은 캐시 미스를 유발
  • MCP 도구의 동적 변경은 캐시 손실을 일으킬 수 있어, Codex는 새 메시지 삽입 방식으로 변경 사항을 반영

컨텍스트 윈도 관리와 자동 압축(compaction)

  • 대화가 길어지면 컨텍스트 윈도 초과를 방지하기 위해 대화 압축(compaction) 을 수행
    • 초기에는 /compact 명령으로 수동 요약을 수행했으나, 현재는 Responses API의 /responses/compact 엔드포인트를 자동 사용
    • 이 엔드포인트는 type=compaction 항목과 암호화된 encrypted_content 를 반환해 모델의 이해를 유지
  • Codex는 auto_compact_limit을 초과하면 자동으로 압축을 실행해 대화 지속성을 확보

결론 및 향후 방향

  • Codex의 에이전트 루프는 모델 추론, 도구 호출, 캐싱, 컨텍스트 관리를 통합한 핵심 구조
  • 이 구조는 고성능·무상태·보안 중심의 에이전트 설계를 가능하게 함
  • 이후 게시물에서는 CLI 아키텍처, 도구 사용 구현, 샌드박싱 모델 등 Codex의 내부 구조를 추가로 다룰 예정
▲
GN⁺ 9시간전  [-]
Hacker News 의견들

  • 이 블로그 글의 가장 좋은 점은 전혀 놀랍지 않다는 점임. Codex CLI가 오픈소스라서 리버스 엔지니어링 없이 내부를 살펴볼 수 있음
    Eric Traut(Pyright로 유명한 개발자)의 커뮤니케이션도 훌륭함. 이슈와 PR에 적극적으로 참여하고 있음
    GitHub 저장소

    • 작년에 Codex CLI가 오픈소스로 공개됐을 때 정말 놀랐음. TypeScript에서 Rust로 포팅된 codex-rs도 포함되어 있어서, 코딩 에이전트의 작동 원리를 배우고 싶은 사람에게 매우 유용함
      나도 CLI에 몇 가지 개선을 기여했고, 릴리스와 PR을 꾸준히 따라보며 지식을 넓히고 있음
    • 많은 사람들이 Claude Code가 독점 소프트웨어라는 걸 모르는 듯함
    • 솔직히 Claude Code가 오픈소스가 아닌 이유는 코드 품질이 너무 형편없어서 부끄럽기 때문이라고 생각함. 매달 200달러짜리 구독을 쓰고 있는데, CLI가 느리고 자주 깨져서 곧 취소할 예정임
    • Codex CLI가 단순히 원격 로직을 호출하는 프론트엔드인지, 아니면 오프라인에서도 완전하게 동작할 수 있는지 궁금함. FLOW 라이선스로 가중치를 제공하는지, 빌드 과정을 문서화했는지도 알고 싶음

  • 흥미로운 점은 압축(compaction)이 “모델의 잠재적 이해를 보존하는 암호화된 메시지”로 수행된다는 부분임
    Codex는 auto_compact_limit을 초과하면 자동으로 이 엔드포인트를 사용해 대화 맥락을 효율적으로 줄임

    • Codex의 compaction 엔드포인트는 업계 최고 수준임. Claude의 것은 최악에 가까움
    • compactor 엔드포인트를 독립적으로 사용할 수 있는지 궁금함. 우리 도메인 전용 에이전트 루프가 있는데, 자체 압축 시스템보다 Codex의 것이 성능이 더 좋을 듯함
    • 이 기능이 OpenAI 모델이 아닌 다른 모델에서도 작동하는지 알고 싶음

  • Codex 내부를 살펴보면서 놀랐던 점은 reasoning 토큰이 에이전트 툴 호출 루프에서는 유지되지만, 사용자 턴이 바뀔 때마다 삭제된다는 것임
    그래서 여러 턴에 걸쳐 맥락을 유지할 수 있지만, 관련된 사용자 요청 간에는 일부 맥락이 손실될 수 있음
    나는 모델이 진행 상황이나 계획, 디버그 내용을 마크다운 파일로 기록하게 해서 여러 컨텍스트 윈도 간에 일종의 스냅샷처럼 작동하도록 함

    • API 경로에 따라 다름. Chat completions는 네가 말한 방식이지만, responses v1 API에서는 반대임. reasoning 토큰이 다음 메시지를 보낼 때도 유지됨. 다만 xhigh 모드는 컨텍스트를 훨씬 빨리 소모함
    • reasoning 토큰을 유지하지 않는 게 오히려 좋은 결정일 수도 있음. 그렇지 않으면 사용자에게 보이지 않는 맥락이 계속 쌓여서 모델과 사용자의 이해가 불일치할 위험이 있음
    • 나는 과거 대화를 반영하는 Codex Reflect Skill을 만들어서 병렬 세션으로 컨텍스트를 구축함
      GitHub 저장소
    • 코드와 함께 기록을 저장하는 건 편리하지만, 팀 환경이나 여러 브랜치를 동시에 작업할 때 문제를 일으킴. 다음 실험으로는 외부 스토리지를 가진 데몬으로 이 데이터를 분리하고, CLI 클라이언트로 접근하는 방식을 시도할 예정임
    • 나는 emacs의 agent-shell을 자주 쓰는데, 전체 대화 기록을 저장해줌. 덕분에 “이전 대화 참고해줘”라고 쉽게 말할 수 있음. 로그를 남기는 건 에이전트가 아니라 emacs라서 누락 걱정이 없음

  • Codex에서 내가 정말 원하는 건 Copilot 스타일의 체크포인트 기능임. GitHub에 관련 이슈가 몇 개 있지만 (#2788, #3585) 팀의 우선순위는 아닌 듯함

    • Gemini CLI에는 이미 이 기능이 있음
    • Codex 팀은 GitHub에서 이모지 업보트 수로 우선순위를 정한다고 함. 원하는 기능이 있다면 꼭 업보트해야 함

  • 에이전트 루프에서 사용자 지시를 집계할 때, 다중 턴 대화에서 컨텍스트 유지를 어떻게 관리하는지 궁금함. 사용자 요구가 변할 때 동적으로 조정하는 기법을 써봤는지도 알고 싶음

  • Codex를 좋아하지만, ChatGPT 웹 인터페이스보다 느리게 느껴짐. 아이디어를 빠르게 주고받을 때는 여전히 웹에서 복사·붙여넣기 하는 게 더 생산적임
    Codex는 종종 엉뚱한 코드를 수정하기 시작해서 피드백 루프가 느리고 답답함. 그래도 잘 작동할 때는 훌륭함. 언젠가 웹처럼 빠르면서도 로컬 작업이 가능한 수준이 되길 바람

    • ChatGPT Plus 웹 인터페이스에서는 5.2 모델의 xhigh reasoning effort 모드가 제공되지 않음

  • 특별히 새롭진 않지만 여전히 가치 있는 글이었음. 에이전트형 코딩 CLI에서 루프나 히스토리를 더 쉽게 반성(reflect) 할 수 있으면 좋겠음. MCP를 통해 채팅 히스토리를 질의하는 방법을 써봤지만, 명시적으로 지정해야 해서 불편함. 지속적 학습이 이런 문제를 해결할 수 있을 듯함

  • 이런 동작은 OTEL 텔레메트리로도 관찰 가능함. 나는 headless codex exec를 자주 쓰지만, 내장 텔레메트리 지원이 부족해서 디버깅이 어려움
    그래서 codex-plus를 직접 만들어 사용 중임. codex exec 인터페이스를 그대로 반영하면서 TypeScript SDK 위에 구현했고, 실행 후 세션 로그를 원격 OpenTelemetry 수집기로 내보내어 codex-plus-log-viewer로 분석할 수 있음

  • 스킬을 설명하는 부분이 이상하게 느껴졌음
    관련 코드 링크
    왜 단순히 파일을 직접 노출하지 않고, 모델이 일반 파일처럼 요청하도록 했는지 의문임

    • 그게 바로 스킬의 핵심임. 관련 파일만 열도록 해서 컨텍스트 윈도 사용량을 줄이는 구조임

  • Codex CLI를 진지하게 써본 사람이 있는지 궁금했음. 나는 VSCode Codex 확장, Gemini CLI, Claude Code CLI를 써봤는데 전부 성능이 엉망이었음.
    그런데 Rust로 새로 만든 Codex CLI는 성능이 미쳤음. UX도 완벽하고, 단축키 같은 세세한 부분도 잘 되어 있음. Theo가 “CLI 최적화보다 모델 개선에 집중했어야 한다”고 했지만, 써보니 전혀 동의할 수 없음

    • Codex CLI는 Claude Code보다 훨씬 낫다고 느낌. 지시를 정확히 따르고, 원하지 않는 행동을 하지 않음. 월 20달러 구독으로 5.2 codex high 모델을 넉넉히 쓸 수 있음. 나는 SSL 생물음향 모델을 다룸
    • OpenCode도 다른 CLI보다 빠르고 안정적임. 최근 Codex를 더 많이 쓰고 있고, Claude Pro를 취소할 예정임. OpenAI가 OpenCode를 공식 지원하는 점이 매력적임. 여러 경쟁 옵션이 있는 지금 상황이 좋음
    • Codex는 대부분의 코딩 작업에서 95% 이상 일관된 결과를 줌. 하지만 비정형 작업(예: 대화나 스토리 작성)에서는 엉뚱한 출력을 내기도 함. git rebase 중 루프에 빠진 적도 있음. Aider는 써봤는데 거의 쓸모없었음
    • Codex CLI의 메모리와 CPU 효율이 매우 좋음. 게다가 오픈소스라서 동작 원리를 직접 확인할 수 있음. Theo의 발언은 여전히 불만임
    • Codex의 문제는 아직 hook 지원이 없다는 것임. 나는 hook을 이용해 에이전트 토큰 소비를 30% 줄이는 도구를 만들었음. hook을 통해 에이전트의 비효율적인 행동을 실시간으로 교정할 수 있음
      관련 글: Scribe Swebench Benchmark
답변달기