# OpenAI Codex CLI 내부 동작 분석: 에이전트 루프와 프롬프트 캐싱 전략

> Clean Markdown view of GeekNews topic #26089. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=26089](https://news.hada.io/topic?id=26089)
- GeekNews Markdown: [https://news.hada.io/topic/26089.md](https://news.hada.io/topic/26089.md)
- Type: news
- Author: [darjeeling](https://news.hada.io/@darjeeling)
- Published: 2026-01-24T22:52:08+09:00
- Updated: 2026-01-24T22:52:08+09:00
- Original source: [openai.com](https://openai.com/index/unrolling-the-codex-agent-loop/)
- Points: 18
- Comments: 2

## Summary

**Codex CLI의 ‘에이전트 루프’는** 사용자 명령을 모델 추론과 도구 실행으로 순환적으로 연결해 실제 작업을 완수하는 구조로 설계되었습니다. 이 과정에서 모든 대화 상태를 JSON 기반 `Responses API`로 주고받으며, **프롬프트 캐싱**을 극대화하기 위해 이전 요청의 접두사를 유지하는 전략을 사용합니다. 또한 서버에 데이터를 남기지 않는 **ZDR(Zero Data Retention)** 원칙을 지키기 위해 무상태 통신과 암호화된 추론 복원을 결합해, 보안성과 효율성을 동시에 확보합니다.

## Topic Body

요약:   
* **에이전트 루프(Agent Loop)의 구조**: Codex CLI가 사용자 입력, 모델 추론, 도구(Tool) 실행을 조율하여 실제 작업을 수행하는 순환적 프로세스를 상세히 설명합니다.  
* **프롬프트 구성 및 Responses API**: 시스템 명령, 도구 정의, 로컬 환경 컨텍스트가 `Responses API`의 JSON 페이로드로 변환되는 과정과 데이터 흐름을 분석합니다.  
* **성능 최적화 및 상태 관리**: 프롬프트 캐싱(Prompt Caching)을 극대화하기 위한 전략과 컨텍스트 윈도우 제한을 극복하기 위한 대화 압축(Compaction) 기술, 그리고 ZDR(Zero Data Retention)을 위한 무상태(Stateless) 설계 원칙을 다룹니다.  
  
  
상세요약:   
OpenAI 엔지니어링 팀은 로컬 소프트웨어 에이전트인 **Codex CLI**의 핵심 로직인 '에이전트 루프(Agent Loop)'의 작동 원리를 심층 분석한 기술 아티클을 공개했습니다. 이 글은 사용자의 명령을 받아 모델과 상호작용하고, 도구를 실행하며 결과를 반환하는 전체 라이프사이클을 기술적인 관점에서 설명합니다.  
  
##### 1. 에이전트 루프 (The Agent Loop)  
에이전트 루프는 사용자의 입력을 받아 작업을 완료할 때까지 모델과 상호작용하는 순환 구조입니다.  
* **프로세스**: 사용자 입력 -> 프롬프트 생성 -> 모델 추론(Inference) -> (도구 호출 요청 -> 도구 실행 -> 결과 첨부 -> 재추론) 반복 -> 최종 응답.  
* **턴(Turn)**: 사용자의 입력부터 모델이 최종적으로 사용자에게 메시지(Assistant Message)를 보낼 때까지의 과정을 하나의 '턴'이라고 합니다. 이 과정에서 에이전트는 수백 번의 도구 호출(예: `ls` 실행, 파일 수정 등)을 수행할 수 있습니다.  
  
##### 2. 모델 추론과 Responses API  
Codex CLI는 `Responses API`를 통해 모델과 통신합니다. 이 API는 `https://chatgpt.com/backend-api/codex/responses`, `https://api.openai.com/v1/responses`, 또는 로컬 호스트(Ollama 등)와 같이 설정 가능합니다.  
  
###### 초기 프롬프트 구성 (Building the Initial Prompt)  
프롬프트는 단순한 텍스트가 아니라 `instructions`, `tools`, `input` 등으로 구성된 구조화된 데이터입니다.  
* **Instructions**: 시스템 또는 개발자 메시지로, 모델의 행동 지침을 정의합니다. (예: `~/.codex/config.toml` 설정 파일 참조)  
* **Tools**: 모델이 사용할 수 있는 도구 정의 목록입니다. 쉘(shell) 실행, 계획 업데이트(update_plan), 웹 검색, 그리고 사용자 정의 MCP(Model Context Protocol) 서버 도구 등이 포함됩니다.  
* **Input**: 모델에 전달되는 실제 데이터 목록입니다. 여기에는 샌드박스 권한 설정, 프로젝트별 지침, 그리고 현재 작업 디렉토리(cwd) 및 쉘 종류와 같은 **환경 컨텍스트(Environment Context)** 가 포함됩니다.  
  
**JSON 페이로드 예시:**  
```javascript  
{  
  "type": "message",  
  "role": "user",  
  "content": [  
    {  
      "type": "input_text",  
      "text": "README.md에 아키텍처 다이어그램을 추가해줘"  
    }  
  ]  
  // ... 이전에 정의된 환경 컨텍스트 및 권한 설정 등이 함께 전송됨  
}  
  
```  
  
##### 3. 도구 실행과 데이터 흐름  
  
모델이 도구 호출(Function Call)을 요청하면, 에이전트는 이를 실행하고 결과를 대화 기록에 추가하여 다시 모델을 호출합니다.  
  
**도구 실행 후 재요청 JSON 예시:**  
  
```javascript  
[  
  /* ... 이전 입력 항목들 ... */  
  {  
    "type": "reasoning", // 모델의 추론 과정 (CoT)  
    "summary": [...],  
    "encrypted_content": "gAAAAABpaDW..." // 암호화된 추론 내용  
  },  
  {  
    "type": "function_call",  
    "name": "shell",  
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",  
    "call_id": "call_8675309..."  
  },  
  {  
    "type": "function_call_output", // 도구 실행 결과  
    "call_id": "call_8675309...",  
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."  
  }  
]  
  
```  
  
이전 프롬프트가 새 프롬프트의 **정확한 접두사(Prefix)** 가 되도록 구성하는 것이 중요합니다. 이는 후술할 프롬프트 캐싱 효율을 결정짓습니다.  
  
##### 4. 성능 고려사항: 캐싱과 ZDR  
  
대화가 길어질수록 프롬프트의 크기는 선형적으로 증가하며, 이는 비용과 지연 시간을 증가시킵니다.  
  
* **프롬프트 캐싱(Prompt Caching)**: OpenAI 모델은 프롬프트의 앞부분이 일치할 경우(Prefix Match) 이전 연산 결과를 재사용하여 속도를 높입니다.  
* **캐시 미스(Cache Miss) 방지**: 도구 목록 변경, 샌드박스 설정 변경 등이 대화 중간에 발생하면 캐시가 깨질 수 있습니다. 이를 방지하기 위해 Codex는 설정 변경을 기존 메시지 수정이 아닌 **새 메시지 추가(Append)** 방식으로 처리합니다.  
  
  
* **무상태(Stateless) 및 ZDR**: `previous_response_id`와 같은 파라미터를 사용하지 않고 매번 전체 문맥을 전송합니다. 이는 서버에 데이터를 저장하지 않는 **Zero Data Retention (ZDR)** 정책을 준수하기 위함입니다. 암호화된 추론 내용(`encrypted_content`)을 클라이언트가 받아 다시 서버로 보내는 방식을 통해, 서버는 상태를 저장하지 않고도 이전 추론 문맥을 복원할 수 있습니다.  
  
##### 5. 컨텍스트 윈도우 관리 (Compaction)  
  
토큰 제한을 넘지 않기 위해 Codex는 `/responses/compact` 엔드포인트를 사용해 대화 기록을 압축합니다. 단순 요약이 아니라, 모델의 잠재적 이해(Latent understanding)를 보존하는 `encrypted_content`를 포함한 압축된 항목 리스트를 반환받아 기존 입력을 대체합니다.

## Comments



### Comment 49863

- Author: iolothebard
- Created: 2026-01-24T23:20:13+09:00
- Points: 1

클로드 코드는 초반부터 공식 문서에 있었는데…

### Comment 49864

- Author: iolothebard
- Created: 2026-01-24T23:20:20+09:00
- Points: 2
- Parent comment: 49863
- Depth: 1

https://code.claude.com/docs/en/how-claude-code-works