코덱스 CLI (OpenAI Codex CLI) 이해하기

🤔 챗GPT를 쓰고 있는데 코덱스는 무엇인지 헷갈릴 때

챗GPT에게 코드를 물어보면 답은 대화창에 나옵니다. 그 코드를 파일에 붙여 넣고, 실행해 보고, 오류가 나면 오류 문장을 다시 복사해 대화창에 붙이는 일은 사람이 합니다. 코덱스는 이 왕복을 대신하는 도구인데, 이름이 붙은 제품이 CLI, 데스크톱 앱, 에디터 확장, 웹까지 여러 개라서 처음에는 무엇을 설치해야 하는지부터 헷갈립니다.

지금부터 그 가운데 터미널에서 쓰는 코덱스 CLI가 무엇인지, 어떤 요금제로 쓰는지, 설치는 어느 글을 따라가면 되는지, 처음 켜기 전에 알아 둘 안전장치는 무엇인지 차례로 정리합니다. 요금과 모델, 버전은 2026년 9월 28일 공식 문서 기준입니다.

🔑 코덱스 CLI의 정의

코덱스 CLI는 OpenAI가 만든 코딩 에이전트로, 내 컴퓨터의 터미널에서 실행되어 폴더 안의 파일을 읽고 고치고 명령을 실행합니다.

CLI는 Command Line Interface의 줄임말로, 마우스 대신 글자로 명령을 입력하는 화면을 말합니다. 터미널이 처음이라면 터미널과 CLI를 먼저 읽으면 이어지는 설명이 쉬워집니다. 코딩 에이전트라는 말은 대답만 하는 챗봇과 달리 도구를 직접 써서 일을 끝까지 진행하는 AI를 가리키고, 자세한 차이는 코딩 에이전트 뜻에 따로 적었습니다.

코덱스 CLI는 소스 코드가 공개된 오픈소스이고 라이선스는 Apache-2.0입니다. 2026년 9월 28일 기준 최신 안정 버전은 0.158.0이며 거의 매주 새 버전이 나옵니다.

🧩 코덱스라는 이름이 붙은 네 가지 제품

같은 코덱스라도 쓰는 화면에 따라 이름이 다릅니다. 공식 문서 표기를 그대로 옮기면 다음과 같습니다.

CLI와 IDE 확장, 데스크톱 앱은 같은 설정 파일(config.toml)을 쓰고, CLI와 IDE 확장은 로그인 정보도 함께 씁니다. 그래서 한쪽에서 모델을 바꾸면 다른 쪽에도 반영됩니다. 클라우드 쪽은 CLI에서 codex cloud로 작업을 보내고 codex apply로 결과를 내 폴더에 가져올 수 있습니다.

지금부터는 CLI만 다룹니다. 앱과 확장도 같은 설정 파일을 쓰기 때문에 CLI에서 익힌 모델과 권한 개념이 대부분 그대로 통합니다.

💳 어떤 요금제로 쓰는지

로그인 방법은 두 가지이고, 무엇으로 로그인하느냐에 따라 돈이 나가는 곳이 달라집니다.

• Sign in with ChatGPT: 챗GPT 요금제에 포함된 사용량으로 씁니다. 처음 codex를 실행하면 브라우저가 열리고 로그인하면 끝납니다
• API 키: OpenAI 플랫폼 계정으로 표준 API 요금이 청구되고, 챗GPT 요금제의 사용량은 쓰지 않습니다. 자동화나 CI에 붙일 때 공식 문서가 권하는 방식입니다

2026년 9월 28일 공식 요금 페이지 기준으로 정리하면 다음과 같습니다.

Free와 Go에서 CLI를 쓸 수 있는지는 공식 문서끼리 표현이 다릅니다. 요금 카드는 두 요금제에 데스크톱 앱만 적었고, 도움말 센터는 "Free와 Go를 포함한 요금제 전반에 코덱스가 포함된다"고만 씁니다. CLI를 뺀다는 문장도 넣는다는 문장도 찾지 못했으므로, CLI를 꾸준히 쓸 계획이라면 요금 카드에 CLI가 명시된 Plus부터 보는 편이 안전합니다. 다른 코딩 에이전트와 요금을 나란히 놓은 비교는 코딩 에이전트 요금과 한도 비교에 있습니다.

남은 사용량은 CLI 안에서 /status를 입력하면 보입니다.

🛠️ 설치는 어느 글을 따라가면 되는지

설치 명령은 한 줄이지만, 운영체제마다 막히는 대목이 달라서 준이아빠블로그는 운영체제별 설치 글을 따로 두었습니다.

윈도우는 이제 WSL(윈도우 안에서 리눅스를 돌리는 기능) 없이 PowerShell에서 바로 돌아갑니다. 공식 문서는 윈도우 11을 권장하고, 최신 업데이트를 한 윈도우 10(1809 이상)은 "최선을 다해 지원"으로 적었습니다. WSL은 리눅스 전용 도구가 필요하거나 작업이 이미 WSL 안에 있을 때만 고르면 됩니다.

설치가 끝났는데 무언가 이상하면 codex doctor가 설치, 로그인, Git, 터미널 상태를 한 번에 점검해 보고서를 만들어 줍니다.

🔒 샌드박스와 승인 정책

코덱스 CLI의 안전장치는 두 가지로 나뉩니다. 이 둘을 구분하면 옵션 이름이 한결 덜 복잡해 보입니다.

• 샌드박스: 코덱스가 기술적으로 어디까지 쓸 수 있고 네트워크에 나갈 수 있는지 정합니다
• 승인 정책: 어떤 일을 하기 전에 사람에게 물어볼지 정합니다

샌드박스 값은 세 가지입니다.

플래그 없이 실행하면 Git으로 관리되는 폴더에서는 공식 문서가 Auto라고 부르는 조합(workspace-write와 on-request)이 권해지고, 그 밖의 폴더에서는 read-only가 권해집니다. Auto에서도 네트워크는 기본으로 꺼져 있고, .git과 .codex 폴더는 읽기 전용으로 보호됩니다. 세션 도중에 범위를 바꾸려면 /permissions를 씁니다.

승인과 샌드박스를 모두 끄는 --dangerously-bypass-approvals-and-sandbox(별칭 --yolo)도 있지만 공식 문서는 쓰지 말라고 안내합니다. 다른 폴더에 써야 한다면 전체를 여는 대신 --add-dir로 폴더를 하나 더 허용하는 편이 낫습니다. 자동 승인이 왜 위험한지는 코딩 에이전트 권한과 안전에서 이어서 다룹니다.

📄 AGENTS.md: 폴더마다 두는 작업 지침

코덱스는 작업을 시작하기 전에 AGENTS.md라는 마크다운 파일을 읽습니다. 이 프로젝트에서 지킬 규칙, 테스트 명령, 건드리면 안 되는 폴더 같은 것을 적어 두면 매번 같은 설명을 반복하지 않아도 됩니다. 클로드 코드의 CLAUDE.md와 같은 역할입니다.

• 만드는 법: 세션 안에서 /init을 입력하면 현재 폴더에 뼈대를 만들어 줍니다
• 읽는 순서: 홈 폴더의 전역 파일을 먼저 읽고, 프로젝트 맨 위 폴더부터 지금 폴더까지 내려오며 폴더마다 하나씩 이어 붙입니다. 지금 폴더에 가까운 지침이 뒤에 붙습니다
• 크기 한도: 합친 크기가 기본 32KiB를 넘으면 그 뒤는 읽지 않습니다

⌨️ 처음 알아 둘 명령과 모델

시작 화면에 안내되는 슬래시 명령 다섯 개가 기본입니다.

대화하지 않고 한 번에 시키고 끝내려면 codex exec "할 일"을 씁니다. 이 방식은 기본이 읽기 전용이어서, 파일을 고치게 하려면 --sandbox workspace-write를 붙여야 합니다. 어제 하던 대화는 codex resume으로 다시 엽니다.

모델은 2026년 9월 28일 모델 문서 기준 GPT-6 Astra(어려운 여러 단계 작업), GPT-6 Sol(일상 작업과 복잡한 코딩), GPT-6 Luna(명확하고 반복되는 작업) 세 가지가 추천됩니다. 설정 없이 실행했을 때 어느 모델이 잡히는지는 공식 문서가 이름을 밝히지 않고 요금제와 배포 단계에 따라 다를 수 있어서, /model 화면에서 직접 확인하는 것이 가장 정확합니다.

⚠️ 자주 하는 실수

• Git으로 관리하지 않는 폴더에서 시작합니다: 되돌릴 기록이 없어 결과가 마음에 들지 않을 때 원래대로 돌리기 어렵습니다. 공식 빠른 시작도 작업 전후 Git 체크포인트를 권합니다
• 네트워크가 막힌 줄 모르고 오류를 반복합니다: 패키지 설치나 외부 주소 호출이 Could not resolve host로 실패하면 샌드박스가 네트워크를 막은 것일 수 있습니다
• codex exec에 수정 권한을 주지 않습니다: 기본이 읽기 전용이라 결과 설명만 나오고 파일은 그대로입니다
• 오래된 글의 모델 이름을 그대로 씁니다: 2026년 8월 글에 나오는 GPT-5.x 이름은 순차 은퇴 중입니다

❓ 자주 묻는 질문

코덱스 CLI는 무료로 쓸 수 있나요?

코덱스 CLI 프로그램 자체는 오픈소스라 무료로 설치할 수 있습니다. 쓸 때는 챗GPT 요금제 사용량이나 API 요금이 듭니다. 2026년 9월 28일 요금 페이지 기준으로 CLI가 명시된 가장 싼 요금제는 월 20달러 Plus이고, Free와 Go에서 CLI가 되는지는 공식 문서 표현이 달라 확인하지 못했습니다.

클로드 코드와 무엇이 다른가요?

둘 다 터미널에서 파일을 읽고 고치는 코딩 에이전트입니다. 안전장치를 거는 방식이 다른데, 코덱스는 샌드박스로 쓸 수 있는 폴더 범위를 먼저 정하고 클로드 코드는 권한 모드로 어떤 행동을 묻지 않고 할지 정합니다. 같은 요청으로 두 도구를 돌린 결과는 코덱스 CLI와 클로드 코드 비교에 정리되어 있습니다.

한국어로 요청해도 되나요?

됩니다. 언어 설정 메뉴는 따로 없고 한국어로 요청하면 한국어로 답합니다. AGENTS.md도 한국어로 적어도 읽습니다.

설치한 뒤 첫 요청은 무엇이 좋나요?

공식 빠른 시작은 Tell me about this project처럼 폴더를 설명해 달라는 요청을 첫 예시로 듭니다. 파일을 고치지 않는 요청이라 권한을 넓히기 전에 코덱스가 폴더를 어떻게 읽는지 볼 수 있습니다. 실제 작업 예시는 코덱스 CLI 사용법과 코덱스 CLI 실전 가이드에서 이어집니다.

📋 3줄 요약

1. 코덱스 CLI는 OpenAI가 만든 오픈소스(Apache-2.0) 코딩 에이전트로, 내 컴퓨터 터미널에서 폴더 안의 파일을 읽고 고치고 명령을 실행합니다.

2. 2026년 9월 28일 요금 페이지 기준으로 CLI가 요금 카드에 명시되는 것은 월 20달러 Plus부터이고, API 키로 로그인하면 요금제 사용량 대신 API 요금이 청구됩니다.

3. 샌드박스는 어디까지 쓸 수 있는지를, 승인 정책은 언제 물어볼지를 정하며 기본값은 작업 폴더 안만 자동으로 고치고 네트워크는 꺼 둔 상태입니다.