OpenAI Codex CLI 에이전트 루프 기술 개요

OpenAI는 Codex CLI 에이전트 루프의 내부 아키텍처를 상세히 설명합니다. 이 루프는 사용자, LLM, 로컬 소프트웨어 도구 간의 상호작용을 관리하는 핵심 오케스트레이션 로직으로, 도구 호출을 반복 실행하고 대화 컨텍스트를 점진적으로 관리하여 성능과 안정성을 유지하면서 신뢰할 수 있는 소프트웨어 변경을 생성하도록 설계되었습니다.

에이전트 루프 아키텍처

에이전트 루프는 사용자와 모델 사이의 정보 흐름을 조정하는 중심 메커니즘입니다. 대화의 하나의 "턴"은 최종 상태에 도달할 때까지 추론과 도구 실행을 여러 번 반복합니다.

반복 프로세스

  1. 입력 및 프롬프트: 에이전트는 사용자 입력을 받아 모델을 위한 텍스트 프롬프트를 준비합니다.
  2. 추론: 프롬프트가 토큰화되어 모델에 전송되어 응답을 생성합니다.
  3. 결정 지점: 모델은 최종 어시스턴트 메시지를 생성하여(턴 종료) 혹은 툴 호출을 요청합니다(예: ls와 같은 셸 명령 실행).
  4. 실행 및 피드백: 툴이 호출되면 에이전트는 명령을 실행하고, 출력 결과를 프롬프트에 추가한 뒤 모델에 다시 질의합니다.

이 사이클은 모델이 어시스턴트 메시지를 내보낼 때까지 반복되며, 작업이 완료되고 제어가 사용자에게 반환됩니다.

모델 추론 및 프롬프트 구성

Codex CLI는 Responses API를 활용해 에이전트 루프를 구동합니다. 설정에 따라 ChatGPT 로그인, API 키를 통한 OpenAI 호스팅 모델, 혹은 gpt-oss와 Ollama 또는 LM Studio를 사용한 로컬 인스턴스 등 다양한 엔드포인트에 연결합니다.

초기 프롬프트 구성

직접적인 프롬프트를 보내는 대신, Codex는 특정 입력 유형을 포함한 JSON 페이로드를 전송합니다. Responses API 서버는 이를 역할에 따라 다음 우선순위(높은 순서부터)로 프롬프트를 구성합니다: system, developer, user, assistant.

초기 프롬프트의 핵심 요소는 다음과 같습니다:

  • 지시사항: 시스템 또는 개발자 메시지가 컨텍스트에 삽입됩니다.
  • 툴: Codex가 제공하는 셸 툴, Responses API 툴, 그리고 MCP(Model Context Protocol) 서버를 통한 사용자 제공 툴을 포함한 스키마 정의된 툴 목록.
  • 입력: 텍스트, 이미지, 파일을 집계한 내용. 여기에는 config.toml의 개발자 지시사항과 프로젝트 루트 또는 $CODEX_HOME에 있는 AGENTS.md 또는 AGENTS.override.md 파일에서 가져온 사용자 지시사항이 포함됩니다.

대화 턴 처리

각 턴은 Server-Sent Events(SSE) 스트림으로 처리됩니다. 모델이 추론이나 함수 호출을 생성하면, 이는 이후 요청을 위해 input 필드에 추가됩니다. 성능 최적화를 위해 Codex는 이전 프롬프트가 새로운 프롬프트의 정확한 접두사로 유지되도록 보장하며, 이는 프롬프트 캐싱을 가능하게 하는 핵심 요소입니다.

성능 및 컨텍스트 관리

대화가 진행될수록 프롬프트 길이가 늘어나 모델의 컨텍스트 윈도우를 소진하고 지연 시간이 증가할 수 있습니다. Codex는 이를 완화하기 위해 두 가지 주요 전략을 사용합니다: 프롬프트 캐싱과 대화 압축.

프롬프트 캐싱

점점 커지는 JSON 페이로드 전송에 따른 2차 비용을 피하기 위해 Codex는 프롬프트 캐싱에 의존합니다. 캐시 히트는 정확한 접두사 일치 시에만 발생합니다. 이러한 히트를 유지하기 위해 Codex는 대화 초반 메시지를 수정하지 않고, 대신 변경 사항을 반영하기 위해 새 메시지를 추가합니다:

  • 구성 변경: 샌드박스 구성이나 승인 모드 변경은 새로운 role=developer 메시지로 추가됩니다.
  • 환경 변경: 현재 작업 디렉터리 변경은 새로운 role=user 메시지로 추가됩니다.

툴 순서를 일관되게 유지하지 못하면(예: 초기 MCP 툴 구현) 캐시 미스가 발생하고 성능이 저하될 수 있습니다.

컨텍스트 윈도우 압축

토큰 수가 auto_compact_limit을 초과하면 Codex는 Responses API의 /responses/compact 엔드포인트를 사용합니다. 이 과정은 방대한 대화 기록을 더 작고 대표적인 항목 목록으로 교체합니다. 여기에는 전체 토큰 기록 없이도 모델이 대화를 잠재적으로 이해하도록 encrypted_content를 포함한 특수 type=compaction 항목이 포함됩니다.

SUMMARY: OpenAI는 Codex CLI의 에이전트 루프 아키텍처를 설명하며, 모델 추론, 프롬프트 구성, 그리고 프롬프트 캐싱 및 압축을 통한 컨텍스트 윈도우 최적화 방식을 상세히 다룹니다.

TITLE: OpenAI Codex CLI 에이전트 루프 기술 개요

Sources