OpenAI Codex란 무엇이고, 어떻게 설치하며, 지역별 접근 조건은 무엇인가

검색 결과에서 “Codex”라는 단어는 서로 다른 세 가지를 뜻하며, 처음 검색하는 사람은 대개 무엇을 찾았는지 이해하지 못합니다. Codex 모델이 있었지만 2023년에 종료되었습니다. 오늘날 이 이름은 에이전트 프로그램을 가리키며, 같은 이름을 쓰는 제품이 십여 개 더 뒤섞여 있습니다.

여기서는 Codex 하나만 다룹니다. OpenAI의 코딩 에이전트입니다. 무엇을 하는지, 어디서 실행되는지, 비용은 얼마인지, 5분 만에 설치하는 방법, 그리고 OpenAI가 국가에 대해 어떤 내용을 안내하는지 살펴봅니다. 모든 내용은 공식 문서를 바탕으로 하며, 각 수치의 출처 링크는 글 끝에 있습니다.

도구 설정에 관한 추가 자료는 Ailoot 문서에서 확인할 수 있습니다.

OpenAI Codex란 무엇인가요?#

일반 채팅과 비교해 보세요. 채팅에서는 코드 일부를 복사해 붙여 넣고 답을 받은 다음 다시 복사합니다. 에이전트는 다르게 작동합니다. 자연어로 작업을 설명하면 프로젝트 폴더에서 관련 파일을 열고, 수정 사항을 적용하고, 검사를 실행한 뒤 결과를 보여줍니다.

OpenAI는 저장소에서 이를 한 문장으로 설명합니다.

로컬로 실행된다는 것은 프로그램이 컴퓨터에 다운로드되어 파일을 볼 수 있고 폴더에서 명령을 실행할 수 있다는 뜻입니다. 모델에 보내는 요청만 클라우드로 전달됩니다.

오픈 소스 코드는 Apache-2.0 라이선스로 GitHub에 공개되어 있습니다. 2026년 8월 1일 기준 저장소에는 별이 103,000개 있으며, 최신 버전 0.146.0은 7월 29일에 출시되었습니다. 업데이트가 거의 매일 나오므로 사용 중인 버전은 이미 달라졌을 가능성이 큽니다.

2026년의 Codex는 종료된 구형 Codex와 어떻게 다른가요?#

두 제품 모두 공식 제품이고 OpenAI에서 나왔기 때문에 사람들이 자주 혼동합니다. 날짜를 보면 구분할 수 있습니다.

첫 번째는 모델 묶음이었습니다. code-davinci-001, code-davinci-002, code-cushman-001, code-cushman-002가 있었습니다. 이 모델들은 코드 완성이라는 한 가지 일을 했고, 초기 GitHub Copilot의 기반이 되었습니다. OpenAI의 종료 모델 목록에는 네 모델 모두 한 줄에 나옵니다. 2023년 3월 20일 발표되어 3월 23일 종료되었고, 권장 대체 모델은 gpt-4o였습니다.

두 번째는 컴퓨터에 설치하는 프로그램입니다. @openai/codex 패키지는 2025년 4월 16일 npm 레지스트리에 등록되었습니다. 내부 모델은 시간이 지나면서 더 새로운 모델로 바뀌지만 프로그램 자체는 그대로 유지됩니다.

2025년 4월 이전의 Codex 안내는 모두 종료된 제품에 관한 내용입니다. Codex를 모델이라고 부르며 code-davinci-002로 호출하라고 권하는 자료를 발견하면 닫으세요.

Codex는 어디에서 작동하나요: 터미널, 편집기, 브라우저, 앱?#

하나만 골라야 하는 것은 아닙니다. 로그인 방식도 계정도 같습니다. 달라지는 것은 작업하기 더 편한 위치뿐입니다.

확장 프로그램은 Xcode 및 JetBrains에서 다른 편집기와 다르게 작동합니다.

클라우드는 다른 네 곳과 작동 방식이 다릅니다. 작업은 OpenAI 컨테이너로 전달되고, 그 안에서 GitHub의 저장소 사본을 체크아웃합니다. 에이전트는 사용자의 컴퓨터 없이 작업하며, 나중에 결과를 검토하고 자신의 사본에 변경 사항을 가져올지 결정할 수 있습니다. 설정은 세 단계입니다. GitHub를 연결하고, 필요한 종속성이 있는 환경을 만들고, 작업을 할당합니다.

API 키로 로그인하면 터미널, 편집기, 앱을 사용할 수 있습니다. 키를 사용하면 클라우드와 자동 코드 검토, Slack에서 작업 시작 등 클라우드에 연결된 기능은 사용할 수 없습니다. 이러한 기능을 사용하려면 ChatGPT 계정으로 로그인해야 합니다.

Codex 내부에서는 어떤 모델이 실행되나요?#

OpenAI는 이를 한 문장으로 요약합니다.

모델 옆에는 추론 수준이라는 두 번째 설정이 있습니다. 네 가지 옵션은 Low(앱과 편집기에서는 Light), Medium, High, Extra High입니다. OpenAI는 원하는 결과를 얻을 수 있는 가장 낮은 수준을 사용하고, 작업에 계획이 필요하면 수준을 높이라고 권합니다.

그 위에는 두 가지 모드가 더 있습니다. Max는 모델에 작업 시간을 더 줍니다. Ultra는 작업을 여러 부분으로 나누어 하위 에이전트에 병렬로 할당합니다. 문서에는 대부분의 작업에 어느 모드도 필요하지 않다고 명시되어 있습니다.

별도 항목인 gpt-5.3-codex-spark도 있습니다. 빠른 반복 작업을 위한 연구용 버전으로, Pro 요금제에서만 사용할 수 있습니다.

모델과 추론 수준을 선택하는 것 자체가 이미 컨텍스트 엔지니어링입니다. 에이전트가 얼마나 깊이 생각할지, 작업에 어떤 정보를 가져올지를 정하는 일이기 때문입니다. 이 조합은 세 가지 기둥으로 이루어집니다. AI 클론(에이전트에 담긴 사용자의 방법론), 세컨드 브레인(프로젝트 지식의 구조), 컨텍스트 엔지니어링입니다. 이 조합이 없으면 AI 에이전트는 사실을 지어내기 시작합니다.

Codex는 얼마이며 요금제에는 무엇이 포함되나요?#

2026년 8월 1일에 공식 가격 페이지에서 가격을 확인했습니다.

Business는 월간 결제 시 좌석당 $20 대신 $25입니다.

이제 사용 한도를 살펴보겠습니다. OpenAI는 단일 고정 수치를 제공하지 않습니다.

OpenAI는 하나의 수치 대신 범위를 공개합니다. 자신의 컴퓨터에서 작업할 때 5시간 동안 보낼 수 있는 메시지 수입니다. Plus와 Business의 수치는 같습니다.

100달러 Pro 요금제에서는 모든 수치가 5배, 200달러 Pro 요금제에서는 20배가 됩니다. OpenAI는 5시간 제한 외에 주간 한도도 언급하지만 구체적인 수치는 공개하지 않습니다.

같은 모델에서 한도가 10배까지 차이 나는 이유는 간단합니다. 메시지 하나가 하루 허용량의 1%를 쓸 수도, 10%를 쓸 수도 있습니다. 요청 횟수는 거의 영향을 주지 않고, 수행한 작업량이 중요하기 때문입니다. Claude를 예로 들어 토큰 사용 방식을 자세히 설명한 Claude Pro 및 Max 한도에서 다뤘는데, 작동 방식은 정확히 같습니다.

한도를 다 쓰면 세 가지 선택지가 있습니다. 요금제를 바꾸지 않고 추가 크레딧을 구매하거나, 더 가벼운 모델로 바꾸거나, API 키로 세션을 시작해 사용한 만큼 토큰 비용을 내면 됩니다.

Codex에는 어떤 지역 제한이 적용되나요?#

OpenAI는 지원 국가 및 지역의 공식 목록을 공개하고 있습니다. 벨라루스는 목록에 없습니다. 카자흐스탄, 아르메니아, 조지아, 튀르키예, 세르비아, 우크라이나는 목록에 있습니다.

같은 페이지에 적힌 문구는 다음과 같습니다.

프로그램을 설치하고 실행하는 것과 모델에 접근하는 것은 별개입니다. 국가 확인은 로그인 단계에서 이루어집니다. ChatGPT로 로그인하든 API 키로 로그인하든 OpenAI 계정이 필요합니다.

GitHub의 보고서를 보면 국가 관련 접근 거부가 어떤 모습인지 알 수 있습니다. 2026년 1월, 베네수엘라의 한 개발자는 PowerShell에서 Codex 0.88.0을 사용하다가 매번 같은 오류를 받았다고 썼습니다.

{
  "error": {
    "code": "unsupported_country_region_territory",
    "message": "Country, region, or territory not supported",
    "type": "request_forbidden"
  }
}

unsupported_country_region_territory 코드와 403 상태는 국가 관련 접근 거부를 나타냅니다. 이 오류가 보인다면 설치 과정에서 잘못한 것이 없고 Node와도 관계가 없습니다.

문서에는 전혀 설명되어 있지 않지만 실제로는 더 자주 마주치는 두 번째 장벽도 있습니다. 바로 전화번호 인증입니다. “전화번호 인증이 작동하지 않는다”는 보고서에는 댓글이 206개 달렸고, 더 이상 접근할 수 없어 교체할 수 없는 옛 번호에 관한 두 번째 보고서는 2026년 6월부터 열려 있으며 댓글이 71개입니다. 같은 이야기가 반복됩니다. 같은 계정으로 브라우저에서 ChatGPT는 작동하지만 Codex는 전화 인증을 요구하고 이를 피할 방법이 없습니다. OpenAI는 어떤 국가의 전화번호를 받는지 목록을 공개하지 않으므로 미리 자신의 번호가 되는지 확인할 방법이 없습니다.

우회 방법은 다루지 않겠습니다. 이 글은 도구의 작동 방식에 관한 내용입니다.

Anthropic도 지원 국가 목록을 공개하며 작동 방식은 같습니다. 한 도구는 “허용”되고 다른 도구는 “차단”된다고 설명하는 자료는 독자를 오도합니다. 공식적으로 두 도구는 같은 상황에 놓여 있습니다. 두 목록은 바뀔 수 있으므로 최신 버전을 확인하세요.

Codex 설치 방법: 단계별 안내#

활성 OpenAI 계정이 이미 있는 분들을 위한 기술적인 내용은 여기서 시작합니다.

1. 프로그램 설치

   시스템에 맞는 방법을 선택하세요. 나중에 프로그램을 최신 버전으로 업데이트할 때도 같은 방법을 사용하세요.

2. 프로젝트 폴더 열기

   에이전트는 실행한 폴더에서 작업합니다. 첫 명령을 실행하기 전에 해당 폴더로 이동하세요.

3. 계정에 로그인

   codex를 처음 실행하면 로그인을 제안합니다. 브라우저가 열리고 로그인한 뒤에는 터미널로 돌아옵니다.

4. 첫 작업 요청

   필요한 내용을 자연어로 설명하세요. 프로젝트를 설명해 달라고 요청하는 것처럼 부담 없는 일부터 시작하세요.

macOS 및 Linux 설치 명령:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows에서는 PowerShell로 같은 설치 프로그램을 사용하세요.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Node가 이미 있다면 npm으로 설치할 수 있습니다.

npm install -g @openai/codex

Homebrew는 macOS에서 작동합니다. --cask를 사용해야 합니다. 그렇지 않으면 잘못된 프로그램이 설치됩니다.

brew install --cask codex

Linux와 WSL2에서는 bubblewrap을 기반으로 샌드박스를 구성하므로 미리 설치해야 합니다.

sudo apt install bubblewrap

Fedora 및 관련 시스템에서는 sudo dnf install bubblewrap을 사용하세요. WSL 버전 1은 0.114까지 지원되었습니다. 0.115부터 샌드박스가 bubblewrap으로 바뀌어 WSL1은 더 이상 작동하지 않았습니다. 반면 Windows에서는 WSL 없이 자체 내장 샌드박스를 사용해도 모든 기능이 작동합니다.

처음 실행할 때 무엇을 해야 하나요?#

시작하려면 프로젝트 폴더로 이동해 codex를 입력하세요. 세션이 열립니다. 그런 다음 특별한 구문 없이 자연어로 작업을 설명하면 됩니다.

처음 몇 분 동안 사용할 다섯 가지 명령:

1. /status - 모델, 승인 정책, 에이전트가 작업 공간으로 간주하는 폴더를 표시합니다.
2. /permissions - 현재 접근 모드와 모드 전환 방법을 보여 줍니다.
3. /model - 모델과 추론 수준을 변경합니다.
4. /init - 프로젝트를 설명하는 AGENTS.md 파일을 만듭니다. 다음 섹션에서 자세히 설명합니다.
5. /review - 파일을 수정하지 않고 변경 사항을 별도로 검토합니다.

codex 외에도 터미널에서 유용하게 쓸 수 있는 명령은 세 가지입니다.

codex resume                    # 이 폴더의 이전 대화로 돌아가기
codex exec "fix the tests"      # 스크립트에서 사용할 단발 실행, 대화 없음
codex --image screenshot.png    # 작업에 이미지 첨부

터미널과 확장 프로그램 문서 모두에서 OpenAI는 같은 조언을 반복합니다. 작업 전후에 커밋하세요. 에이전트가 파일을 직접 수정하므로 첫날부터 명령 하나로 변경 사항을 되돌릴 수 있어야 합니다.

AGENTS.md로 Codex에 프로젝트를 어떻게 설명하나요?#

적용 순서는 엄격합니다. 문서의 해당 섹션 첫 줄에 바로 명시되어 있습니다.

먼저 Codex는 전역 파일 ~/.codex/AGENTS.md를 읽습니다. 여기에 모든 프로젝트에 적용되는 작업 습관을 적습니다. 다음으로 프로젝트 내부의 파일을 읽습니다. 저장소 루트부터 현재 폴더까지 폴더마다 하나씩 읽습니다. 위에서 아래로 합쳐지며 더 가까운 파일의 규칙이 더 먼 파일의 규칙보다 우선합니다. 즉, services/payments의 규칙은 루트의 일반 규칙보다 우선합니다.

간단한 파일은 다음과 같습니다.

# AGENTS.md

## 이 프로젝트 작업 방법

- `npm test`로 테스트를 실행하세요. 파일 하나씩 실행하지 마세요.
- pnpm으로 패키지를 설치하세요.
- 새로운 프로덕션 종속성을 추가하기 전에 저에게 물어보세요.
- `legacy/` 폴더는 절대 건드리지 마세요.

파일을 합친 전체 크기 제한은 32킬로바이트입니다. 이 제한을 넘으면 이후 파일은 알림 없이 추가되지 않습니다. 용량이 너무 큰 AGENTS.md는 파일 전체가 매번 컨텍스트에 들어가므로 실행할 때마다 한도를 소모합니다.

CLAUDE.md를 알고 있다면 작동 방식이 익숙할 것입니다. 이름만 다를 뿐 같은 방식입니다. 프로젝트 규칙 파일은 세컨드 브레인의 토대입니다. 에이전트는 설명을 듣기 전부터 사용자의 작업에 관한 정보를 익힙니다. 한 프로젝트에서 두 파일을 함께 사용하는 방법은 AGENTS.md와 CLAUDE.md 함께 사용하기에서 다뤘습니다.

Codex는 무엇을 직접 처리하고 어떤 작업에 승인이 필요한가요?#

두 설정은 자주 혼동되므로 OpenAI는 차이를 한 문장으로 설명합니다.

검토를 자동으로 전환해도 작업 폴더의 경계는 그대로입니다. 자동화는 클릭만 없앨 뿐 에이전트의 권한을 바꾸지 않습니다.

앱과 편집기에는 세 가지 접근 모드가 있습니다. Ask for approval은 항상 사용할 수 있으며 처음 시작할 때 권장됩니다. Approve for me와 Full access는 설정에서 먼저 활성화해야 합니다.

터미널은 자체 로직을 따릅니다. 프로그램이 폴더를 확인하고 적절한 권한 집합을 제안합니다.

로컬 모드에서는 기본적으로 네트워크 접근이 꺼져 있습니다. 에이전트는 스스로 고안한 명령을 실행하므로 기본 상태에서 인터넷에 접근하도록 허용하는 것은 누구도 원하지 않을 것입니다.

작업 폴더 안에서도 모든 모드에서 에이전트가 읽을 수 있는 위치는 제한됩니다. .git, .agents, .codex가 이에 해당합니다. /status를 사용하면 에이전트가 현재 작업 공간으로 간주하는 폴더를 확인할 수 있습니다.

전체 접근 모드도 있습니다. --dangerously-bypass-approvals-and-sandbox 플래그를 사용하는 방식입니다. 문서에서는 위험도가 더 높다고 표시하고 “권장하지 않음”으로 분류합니다. 플래그 이름만으로도 충분히 설명되므로 덧붙일 말은 없습니다.

Codex와 Claude Code 중 무엇을 선택해야 하나요?#

온라인 논쟁에서 짐작할 수 있는 것보다 두 도구의 차이는 작습니다. 둘 다 프로젝트를 읽고 파일을 직접 수정하며 폴더 범위를 벗어나기 전에 묻습니다.

처음에는 이미 무엇에 비용을 내고 있는지 보는 것이 가장 쉽습니다. ChatGPT 구독이 있으면 Codex가 이미 포함되어 있어 별도로 결제할 필요가 없습니다. 측정 결과를 포함한 자세한 비교는 별도의 Codex와 Claude Code 비교 글에 정리했습니다. 작업 설정을 한쪽에서 다른 쪽으로 옮기려면 마이그레이션 가이드를 참고하세요.

처음 실행할 때 가장 자주 발생하는 문제는 무엇인가요?#

이 목록은 프로젝트 저장소의 보고서를 바탕으로 작성했습니다. 추측은 없습니다. 각 항목은 실제로 문제를 겪은 사용자의 보고에서 나왔습니다.

1. 잘못된 패키지를 설치했습니다. 접두사 없이 npm install -g codex를 실행하면 2011년부터 있던 정적 사이트 생성기가 설치됩니다. 올바른 패키지는 @openai/codex입니다.
2. bubblewrap이 설치되어 있지 않습니다. Linux와 WSL2에서 bubblewrap이 없으면 샌드박스가 시작되지 않습니다. Codex는 내장 대체 기능으로 전환하고 시작할 때 문제를 알립니다. 명령 하나로 설치할 수 있습니다.
3. 국가 제한으로 접근이 거부되었습니다. 로그인할 때 unsupported_country_region_territory 코드와 403 상태가 나타납니다. 설치와는 관계가 없습니다.
4. 전화번호 인증이 필요합니다. 모든 사용자에게 발생하는 것은 아니며 문서에도 설명되어 있지 않습니다. 접근할 수 없는 번호를 교체할 공식 방법은 없습니다. 관련 보고서는 2026년 6월부터 열려 있습니다.
5. 사용 한도를 예상보다 빨리 소진합니다. “토큰이 너무 빨리 소진된다”는 보고서는 저장소 전체에서 가장 많은 논의가 이루어졌으며 댓글이 627개입니다. 더 가벼운 모델로 바꾸고 추론 수준을 낮추면 도움이 될 수 있습니다.

인터페이스 언어는 에이전트의 작업에 영향을 주지 않습니다. 작업 언어와 인터페이스 언어가 같을 필요는 없습니다.

다음에 할 일#

에이전트와 함께하는 첫 한 시간은 언제나 같은 일에 쓰입니다. 에이전트가 어디까지 스스로 할 수 있는지 알아보는 일입니다. 자신의 프로젝트로 직접 확인해야 합니다. 문서의 예시만으로는 알 수 없습니다.

시작할 때 권하는 순서는 다음과 같습니다.

1. 프로그램을 설치하고 활성 OpenAI 계정으로 로그인합니다.
2. 실제 프로젝트 폴더를 열고 codex를 실행합니다.
3. /status와 /permissions에서 설명만 할 작업에 읽기 전용을 명시적으로 선택하고 활성 모드를 검증한 뒤 프로젝트 구성에 관해 질문합니다.
4. 커밋을 만든 뒤 첫 편집 작업을 맡깁니다.
5. 세 줄짜리 AGENTS.md를 작성하고 작성 전후의 에이전트 응답을 비교합니다.

AI 클론 + 세컨드 브레인 + 컨텍스트 엔지니어링에 관한 도구 활용 자료는 Ailoot 문서에서 확인할 수 있습니다.