🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

OpenAI는 Codex CLI의 핵심인 에이전트 루프가 사용자 입력, 모델 추론, 도구 호출, 실행 결과 반영을 반복하며 소프트웨어 작업을 완수하는 방식을 설명한다.

📌 핵심 요약

• Codex CLI는 사용자의 로컬 환경에서 안전하고 효율적으로 소프트웨어 변경을 수행하도록 설계된 크로스플랫폼 로컬 소프트웨어 에이전트이며, 이 글은 그 핵심 실행 구조인 에이전트 루프를 다룬다.
• 에이전트 루프는 사용자 입력을 프롬프트로 구성하고, 모델 추론을 실행한 뒤, 모델이 최종 답변을 내거나 도구 호출을 요청하는지에 따라 다음 단계를 결정하는 반복 구조다.
• 모델이 도구 호출을 요청하면 Codex는 해당 도구를 실행하고 결과를 기존 프롬프트에 추가한 뒤 다시 모델을 호출하며, 이 과정은 모델이 더 이상 도구 호출을 내지 않고 사용자에게 보낼 assistant message를 생성할 때까지 반복된다.
• Codex CLI는 Responses API에 HTTP 요청을 보내 모델 추론을 실행하며, 엔드포인트는 ChatGPT 로그인, API 키 인증, 로컬 gpt-oss 실행, 클라우드 제공자의 Responses API 등 구성에 따라 달라질 수 있다.
• 첫 추론 요청을 만들 때 Codex는 모델 지시문, 도구 정의, 사용자 입력뿐 아니라 샌드박스 설명, 개발자 지시문, AGENTS 문서와 스킬 메타데이터, 현재 작업 디렉터리와 셸 같은 로컬 환경 정보를 조합해 입력 목록을 구성한다.

🧩 주요 포인트

1. Codex CLI는 사용자의 로컬 환경에서 안전하고 효율적으로 소프트웨어 변경을 수행하도록 설계된 크로스플랫폼 로컬 소프트웨어 에이전트이며, 이 글은 그 핵심 실행 구조인 에이전트 루프를 다룬다.
2. 에이전트 루프는 사용자 입력을 프롬프트로 구성하고, 모델 추론을 실행한 뒤, 모델이 최종 답변을 내거나 도구 호출을 요청하는지에 따라 다음 단계를 결정하는 반복 구조다.
3. 모델이 도구 호출을 요청하면 Codex는 해당 도구를 실행하고 결과를 기존 프롬프트에 추가한 뒤 다시 모델을 호출하며, 이 과정은 모델이 더 이상 도구 호출을 내지 않고 사용자에게 보낼 assistant message를 생성할 때까지 반복된다.
4. Codex CLI는 Responses API에 HTTP 요청을 보내 모델 추론을 실행하며, 엔드포인트는 ChatGPT 로그인, API 키 인증, 로컬 gpt-oss 실행, 클라우드 제공자의 Responses API 등 구성에 따라 달라질 수 있다.
5. 첫 추론 요청을 만들 때 Codex는 모델 지시문, 도구 정의, 사용자 입력뿐 아니라 샌드박스 설명, 개발자 지시문, AGENTS 문서와 스킬 메타데이터, 현재 작업 디렉터리와 셸 같은 로컬 환경 정보를 조합해 입력 목록을 구성한다.

🧠 상세 정리

1. Codex CLI와 글의 초점

이 글은 OpenAI의 Codex CLI가 어떻게 소프트웨어 에이전트로 동작하는지 설명하는 시리즈의 첫 번째 글이다. Codex CLI는 로컬 머신에서 실행되는 크로스플랫폼 소프트웨어 에이전트로, 고품질의 신뢰할 수 있는 코드 변경을 안전하고 효율적으로 만드는 것을 목표로 한다. 글은 Codex CLI가 처음 공개된 이후 축적한 설계상의 교훈을 풀어내겠다고 밝히며, 특히 이번 글에서는 Codex의 핵심 실행 논리인 에이전트 루프에 집중한다. 또한 더 세부적인 구현 결정은 오픈소스 저장소의 이슈와 풀 리퀘스트에 남아 있다고 안내한다.

2. Codex라는 용어와 하네스의 범위

OpenAI 내부에서 ‘Codex’는 단일 제품만을 가리키지 않고 Codex CLI, Codex Cloud, Codex VS Code 확장 등 여러 소프트웨어 에이전트 제품군을 포괄한다. 다만 이 글에서 다루는 중심 대상은 모든 Codex 경험의 기반이 되는 Codex 하네스다. 이 하네스는 핵심 에이전트 루프와 실행 로직을 제공하며, Codex CLI를 통해 사용자에게 드러난다. 글은 설명의 편의를 위해 ‘Codex’와 ‘Codex CLI’를 어느 정도 바꿔 사용하겠다고 전제하지만, 실제 초점은 사용자 인터페이스보다 그 아래에서 모델과 도구 실행을 조율하는 구조에 있다.

3. 에이전트 루프의 기본 구조

AI 에이전트의 중심에는 에이전트 루프가 있으며, Codex에서는 이 루프가 사용자, 모델, 도구 사이의 상호작용을 조율한다. 시작점은 사용자의 입력이며, 에이전트는 이 입력을 모델에 전달할 텍스트 지시문 집합, 즉 프롬프트의 일부로 포함한다. 그다음 모델에 질의해 응답을 생성하는 추론 단계가 이어진다. 이때 프롬프트는 먼저 모델의 어휘를 가리키는 정수 시퀀스인 입력 토큰으로 변환되고, 모델은 이를 바탕으로 새로운 출력 토큰 시퀀스를 샘플링한다.

4. 토큰, 스트리밍, 모델 응답

모델이 만든 출력 토큰은 다시 텍스트로 변환되어 모델의 응답이 된다. 토큰은 한꺼번에 완성되는 것이 아니라 점진적으로 생성되기 때문에, 많은 LLM 기반 애플리케이션은 모델이 실행되는 동안 결과를 스트리밍 형태로 표시할 수 있다. 실제 서비스에서는 이런 토큰화와 역변환 과정이 대개 텍스트 기반 API 뒤에 감춰져 있어, 사용자는 입력 텍스트를 보내고 출력 텍스트를 받는 방식으로 경험한다. 글은 이 추론 과정을 에이전트 루프의 한 단계로 설명하면서, 이후 도구 호출 여부에 따라 흐름이 갈라진다고 정리한다.

5. 도구 호출과 반복 실행

추론 결과 모델은 두 가지 중 하나를 내놓을 수 있다. 하나는 사용자의 원래 입력에 대한 최종 답변이고, 다른 하나는 에이전트가 수행해야 하는 도구 호출 요청이다. 예를 들어 모델이 ‘ls를 실행하고 그 출력을 보고하라’는 식의 요청을 내면, 에이전트는 해당 도구 호출을 실행하고 그 결과를 원래 프롬프트에 덧붙인다. 그런 뒤 갱신된 입력으로 모델을 다시 호출하며, 모델은 새로 얻은 정보를 바탕으로 다음 결정을 내린다. 이 반복은 모델이 더 이상 도구 호출을 생성하지 않고 사용자에게 보낼 메시지를 만들 때까지 계속된다.

6. 한 턴의 종료와 에이전트의 실제 산출물

Codex에서 한 대화 턴은 사용자 입력에서 시작해 최종 assistant message가 생성될 때 끝난다. 이 메시지는 사용자의 요청에 대한 직접 답변일 수도 있고, 추가 확인이 필요한 경우 후속 질문일 수도 있다. 하지만 소프트웨어 에이전트의 산출물은 단순히 마지막 텍스트 메시지에만 한정되지 않는다. 에이전트는 로컬 환경을 수정하는 도구 호출을 실행할 수 있으므로, 실제 주요 산출물은 사용자의 컴퓨터에 작성되거나 편집된 코드일 수 있다. 그럼에도 각 턴은 ‘요청한 architecture.md를 추가했다’ 같은 assistant message로 종료되며, 이는 제어권이 다시 사용자에게 돌아간다는 신호다.

7. 대화 기록, 컨텍스트 윈도우, 관리 책임

Codex에서 하나의 대화 턴 안에는 여러 번의 모델 추론과 도구 호출 반복이 포함될 수 있다. 사용자가 기존 대화에 새 메시지를 보내면 이전 메시지와 도구 호출 기록이 새 턴의 프롬프트 일부로 포함된다. 따라서 대화가 길어질수록 모델 샘플링에 사용되는 프롬프트도 길어진다. 이는 모델마다 한 번의 추론 호출에서 사용할 수 있는 최대 토큰 수인 컨텍스트 윈도우가 있기 때문에 중요한 제약이 된다. 특히 에이전트가 한 턴 안에서 수백 번의 도구 호출을 수행할 수도 있으므로, 컨텍스트 윈도우 관리는 에이전트가 맡아야 할 주요 책임 중 하나로 제시된다.

8. Responses API와 구성 가능한 추론 엔드포인트

Codex CLI는 모델 추론을 실행하기 위해 Responses API에 HTTP 요청을 보낸다. 이때 사용하는 Responses API 엔드포인트는 구성 가능하므로, Responses API를 구현하는 다양한 엔드포인트와 함께 사용할 수 있다. ChatGPT 로그인으로 Codex CLI를 사용할 때는 chatgpt.com의 Codex responses 엔드포인트를 사용하고, API 키 인증으로 OpenAI 호스팅 모델을 사용할 때는 api.openai.com의 responses 엔드포인트를 사용한다. 또한 --oss 옵션으로 로컬 gpt-oss를 사용할 경우 로컬 컴퓨터의 localhost 엔드포인트를 기본으로 하며, 클라우드 제공자가 호스팅하는 Responses API와도 함께 사용할 수 있다고 설명한다.

9. 첫 추론 요청을 위한 입력 구성

사용자는 Responses API를 호출할 때 모델이 실제로 소비하는 프롬프트를 그대로 지정하지 않는다. 대신 instructions, tools, input 같은 여러 입력 유형을 JSON 페이로드에 담아 보내고, 서버가 이를 모델에 맞는 프롬프트 구조로 구성한다. Codex에서 instructions 필드는 사용자가 config.toml에 model_instructions_file을 지정한 경우 그 파일에서 읽고, 그렇지 않으면 모델에 연결된 기본 지시문을 사용한다. tools 필드에는 Codex CLI가 제공하는 도구, Responses API가 제공해 Codex에 노출되는 도구, 그리고 사용자가 MCP 서버 등을 통해 제공하는 도구 정의가 포함된다. input 필드는 텍스트, 이미지, 파일 입력의 목록이며, Codex는 여기에 여러 사전 메시지를 추가한 뒤 사용자 메시지를 붙인다.

10. 샌드박스, 사용자 지시문, 로컬 환경 정보

Codex는 첫 사용자 메시지를 추가하기 전에 input 목록에 여러 항목을 삽입한다. 먼저 Codex가 제공하는 셸 도구에만 적용되는 샌드박스를 설명하는 developer 역할의 메시지를 넣는데, 여기에는 파일 권한, 네트워크 접근, 셸 명령 실행 시 사용자 허가를 요청해야 하는 조건 등이 포함된다. 이어 사용자의 config.toml에 developer_instructions 값이 있으면 developer 역할 메시지로 추가하고, AGENTS.override.md, AGENTS.md, 프로젝트 문서, 스킬 관련 메타데이터 등에서 모은 사용자 지시문을 user 역할 메시지로 넣을 수 있다. 마지막으로 현재 작업 디렉터리와 사용자의 셸 같은 로컬 실행 환경을 설명하는 user 역할 메시지를 추가한 뒤, 실제 사용자 메시지를 붙여 대화를 시작한다.

🧾 핵심 주장 / 시사점

• Codex의 핵심은 모델 자체보다 모델이 도구를 호출하고 그 결과를 다시 문맥에 반영하도록 조율하는 하네스 구조에 있으며, 이 구조가 소프트웨어 에이전트의 실질적 작업 능력을 만든다.
• 에이전트의 최종 응답은 텍스트 메시지이지만, 소프트웨어 작업에서는 파일 생성·수정 같은 로컬 환경 변화가 더 중요한 산출물일 수 있으므로 평가 기준도 메시지 품질만으로 제한되기 어렵다.
• 프롬프트는 단순히 사용자 질문 하나가 아니라 지시문, 도구 정의, 샌드박스 정책, 프로젝트 문서, 스킬 메타데이터, 로컬 환경 정보가 결합된 구조이며, 이 구성 방식이 에이전트의 안전성과 작업 품질에 직접 영향을 준다.

✅ 액션 아이템

• 에이전트형 CLI를 설계할 때 사용자 입력→모델 추론→도구 호출→결과 반영의 반복 루프를 기본 실행 단위로 정의한다.
• 첫 모델 요청에 포함할 컨텍스트를 모델 지시문, 도구 정의, 샌드박스 설명, 개발자 지시문, 작업 디렉터리·셸 정보로 분리해 점검한다.
• 도구 호출 결과를 프롬프트에 다시 추가한 뒤 최종 assistant message가 나올 때까지 반복하는 흐름을 로컬 자동화 설계에 반영한다.

❓ 열린 질문

• 로컬 소프트웨어 에이전트에서 도구 호출을 반복할 때 어느 시점에 최종 답변으로 전환하도록 판단해야 하는가?
• Responses API 엔드포인트가 ChatGPT 로그인, API 키, 로컬 실행, 클라우드 제공자별로 달라질 때 설정 관리는 어떻게 단순화할 수 있는가?
• 첫 추론 요청에 포함되는 AGENTS 문서, 스킬 메타데이터, 로컬 환경 정보는 안전성과 효율성에 각각 어떤 영향을 주는가?