오픈AI 코덱스 사용법 총정리: 승인 정책과 샌드박스, 워크트리, AGENTS.md, 서브에이전트까지

핵심 메시지

• AI 에이전트는 계획하고, 도구로 행동하고, 기억을 남기는 세 가지 원리로 움직이며 중간에 실패하면 스스로 다시 계획하는 루프를 돈다.
• 코덱스는 계획에 시간을 덜 쓰고 빠르게 실행하는 쪽이라 토큰을 아끼는 대신 수정 반복이 늘어난다. 도구 선택은 우열이 아니라 작업 성격에 맞춰야 한다.
• 요금은 정액 구독과 API 종량제로 나뉘고, 사용량은 5시간 롤링 윈도와 주간 한도로 관리되며 2026년 4월부터 메시지 수가 아닌 토큰 기준으로 바뀌었다.
• 승인 정책과 샌드박스가 안전장치다. 기본값은 프로젝트 밖 접근 시 사용자에게 묻는 것이고, 정책은 운영체제 수준 도구로도 강제된다.
• AGENTS.md에 프로젝트 규칙을 적고, 반복 작업은 스킬로, 위임할 일은 서브에이전트로 분리하면 매번 같은 지시를 다시 쓰지 않아도 된다.

쉽게 이해하기

강좌는 코덱스를 설명하기 전에 AI 에이전트가 무엇인지부터 짚는다. 2022년 챗봇이 등장했을 때 사람들은 질문에 대한 답을 받아 복사해 쓰는 데 그쳤지만, 지금은 AI가 사용자를 대신해, 그리고 사용자와 나란히 작업을 수행한다. 그 원리는 세 단계다. 먼저 계획하고 판단하는 추론, 다음으로 외부 자원에 접근하기 위해 도구를 쓰는 행동, 마지막으로 같은 일을 처음부터 다시 하지 않기 위한 기억이다. 강사는 앞의 둘을 묶어 리액트(ReAct)라고 부른다.

날씨를 묻는 간단한 예시가 이 흐름을 보여 준다. 에이전트는 도시가 지정되지 않았음을 파악해 위치를 먼저 찾고, 위치 도구를 호출해 결과를 관찰한 뒤 다시 계획을 세우고 날씨 API를 부른다. 중간에 네트워크 오류로 호출이 실패하면 사용자가 오류를 되먹여 줄 필요 없이 결과를 보고 다시 계획을 세워 반복한다. 이 되풀이 구조가 에이전틱 루프이며, 코덱스만이 아니라 대부분의 에이전트가 같은 방식으로 움직인다.

그렇다면 비슷해 보이는 에이전트들은 무엇이 다를까. 강사는 기능이 아니라 '성격'이 다르다고 설명한다. 어떤 에이전트는 지시를 받자마자 곧바로 행동에 들어가고, 어떤 에이전트는 계획에 시간을 더 들인다. 코덱스는 빠르게 움직이는 쪽이라 토큰을 적게 쓰지만 결과물을 다듬는 반복이 늘어난다. 반대로 계획을 오래 하는 도구는 한 번에 더 나은 결과를 주는 대신 토큰을 더 쓴다. 그의 결론은 명확하다. 어느 쪽이 더 낫냐가 아니라 내 작업이 어느 쪽에 맞느냐를 봐야 하고, 성능 순위는 계속 뒤바뀐다.

안전 장치도 비중 있게 다룬다. 기본 승인 정책은 프로젝트 밖 파일이나 인터넷에 접근할 때마다 사용자에게 묻는 것이고, 민감한 작업에만 묻게 하거나 전면 허용으로 바꿀 수도 있다. 코덱스는 샌드박스로 프로젝트별 격리 환경을 만들고, 그 정책을 운영체제에도 넘겨 macOS의 샌드박스 도구 같은 수단으로 실제 접근을 제한한다. 여기에 워크트리가 더해진다. 메인 저장소를 직접 고치는 대신 복사본을 만들어 변경을 적용하므로, 결과를 검토한 뒤 본 저장소에 반영할 수 있고 오래된 복사본은 개수 제한으로 자동 정리된다.

실무에 붙이는 방법은 규칙과 위임, 그리고 자동화다. /init 명령으로 만드는 AGENTS.md에는 신입 개발자에게 알려 주듯 기술 스택, 명명 규칙, 코드 생성 후 테스트를 돌리라는 지시 같은 프로젝트 규칙을 적어 둔다. 서브에이전트는 이름과 목적, 샌드박스 모드, 사용할 모델까지 설정 파일로 정의해 두고 프롬프트에서 불러 쓰는데, 검토 같은 일을 떼어 내면 메인 에이전트의 맥락을 깨끗하게 유지할 수 있다. 반복되는 작업은 스킬로 저장해 매번 같은 설명을 다시 쓰지 않는다. 마지막으로 헤드리스 실행 명령을 쓰면 CI 파이프라인이나 깃허브 액션 안에서 코덱스가 변경을 검토하고 수정해 되돌려 주는 자동화도 가능하다.

주요 인사이트

• 토큰 한도가 5시간 슬라이딩 윈도로 돌아온다는 점은 실무 감각에 직접 영향을 준다. 오전에 크게 쓴 만큼이 정확히 다섯 시간 뒤에 되돌아오므로, 한도가 다 찼다고 하루를 통째로 기다릴 필요는 없다.
• 샌드박스 정책이 도구 안에서만 선언되는 것이 아니라 운영체제 차원의 수단으로 강제된다는 설명은, 에이전트에게 터미널 권한을 주는 일의 위험을 어떻게 줄이는지 보여 준다.
• 워크트리는 '에이전트를 믿되 본 저장소는 건드리지 않게 한다'는 절충안이다. 검토 단계를 구조적으로 강제한다는 점에서 승인 정책보다 실질적인 안전장치가 될 수 있다.
• AGENTS.md, 스킬, 서브에이전트는 결국 같은 문제, 즉 같은 지시를 매번 다시 쓰는 낭비를 각각 프로젝트 규칙·반복 작업·역할 분담의 층위에서 푸는 장치다.
• 헤드리스 모드가 열리면 에이전트는 사람이 대화하는 도구에서 파이프라인의 한 단계로 성격이 바뀐다. 코드 리뷰를 사람이 아니라 워크플로가 먼저 돌리는 구성이 가능해진다.

자주 묻는 질문

관련 AI 소식