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

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

대화에서 받은 코드를 파일에 붙여 넣고 실행하는 과정을 직접 해 본 적이 있나요? 코덱스 CLI는 터미널에서 요청을 받아 파일을 읽고 수정하며 필요한 명령을 실행합니다. 다른 대화형 AI도 연결된 도구에 따라 파일 작업을 할 수 있으므로, 화면 이름보다 실제 연결된 기능과 권한을 확인합니다.

이 글에서는 설치 여부 확인, 로그인과 사용량 확인, 연습 파일 읽기 순서로 시작합니다. 요금과 기능은 실제 계정에 적용된 조건을 함께 확인합니다.

🔑 코덱스 CLI의 정의

코덱스 CLI는 터미널에서 요청을 받아 파일을 읽고 수정하며 명령을 실행하는 OpenAI의 코딩 에이전트입니다. 이 글은 내 컴퓨터의 연습 폴더에서 실행하는 경우를 다룹니다. 원격 연결이나 클라우드 작업을 사용하면 실행 위치가 달라집니다.

CLI는 Command Line Interface의 줄임말로, 글자로 명령을 입력해 프로그램을 사용하는 방식입니다. 터미널이 처음이라면 터미널과 CLI를 먼저 읽으면 이어지는 설명이 쉬워집니다. 코딩 에이전트라는 말은 도구를 사용해 파일 수정과 실행 같은 여러 단계를 진행하는 AI를 가리키고, 자세한 차이는 코딩 에이전트 뜻에 따로 적었습니다.

설치 버전은 터미널에서 codex --version으로 확인합니다. 인터넷 글의 버전 번호를 최신이라고 가정하지 않습니다. 사용할 수 있는 옵션은 codex --help에서 확인할 수 있습니다. 두 명령은 AI에게 작업을 요청하지 않고 설치된 프로그램의 정보를 보여 줍니다.

🧩 같은 이름, 다른 작업 화면

IDE는 코드를 작성하고 실행하는 개발 환경입니다. 화면이 달라도 설정을 공유하는 경우가 있지만, 한 세션의 모델 변경이 모든 화면의 설정을 바꾼다고 생각하지 않습니다. 각 세션의 모델, 작업 경로와 권한을 확인합니다. 화면과 실행 위치의 차이는 코딩 에이전트의 실행 환경에서 이어집니다.

💳 어떤 요금제로 쓰는지

로그인 방식에 따라 비용이 처리되는 계정이 달라집니다.

• Sign in with ChatGPT: 이용 계정의 코덱스 포함 범위와 남은 사용량이 적용됩니다.
• API 키: API 결제 계정에 사용료가 청구되며 ChatGPT 구독 사용량과 구분합니다.

2026년 10월 3일 공식 요금 안내에는 Plus의 CLI 이용이 명시되어 있습니다. Free와 Go 카드는 데스크톱 앱의 제한된 제공을 안내하므로 “코덱스 포함”이라는 문구만으로 CLI도 이용 가능하다고 판단하지 않습니다. 먼저 자신의 계정에서 이용 가능한 화면과 로그인 안내를 확인합니다. 시작하기 위해 곧바로 새 구독을 결제할 필요는 없습니다.

로그인 뒤 /status에서 현재 세션 정보를 확인하고 계정의 사용량 화면과 대조합니다. 한도에 도달하면 초기화를 기다릴지, 작업을 줄일지, 추가 결제할지 구분합니다. 구독 로그인과 별도 API 과금은 요금과 한도 비교에서도 다룹니다.

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

먼저 터미널에서 codex --version을 입력합니다. 버전이 나오면 설치된 상태이므로 설치 명령을 다시 실행할 필요가 없습니다. 명령을 찾을 수 없다는 오류가 나오면 공식 안내에서 내 운영체제에 맞는 방법 하나를 선택합니다. 아래 명령은 프로그램을 설치하므로 회사 기기에서는 승인된 설치 경로를 사용합니다.

설치 후 터미널을 새로 열고 codex --version을 다시 입력합니다. 여전히 명령을 찾지 못하면 설치 결과의 오류와 프로그램 경로 설정을 확인합니다. 다른 운영체제의 설치 명령을 연달아 실행하지 않습니다.

윈도우는 공식 PowerShell 설치 안내를 따를 수 있습니다. WSL은 윈도우에서 리눅스 환경을 쓰는 기능이며, 이미 WSL에서 관리하는 작업이라면 그 환경의 설치 안내를 확인합니다. 설치 방법을 섞기보다 파일이 있는 환경과 실행 환경을 맞춥니다.

🔒 샌드박스와 승인 정책

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

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

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

쓰기 허용 범위가 읽을 수 있는 모든 파일의 범위와 같지는 않습니다. 네트워크, 추가 허용 폴더와 연결된 도구도 별도로 확인합니다. on-request는 필요한 승인을 요청한다는 뜻이며 모든 명령을 하나씩 확인받는다는 뜻이 아닙니다.

실제 적용 값은 실행 옵션, 설정과 관리자 정책에 따라 달라집니다. 세션의 /status와 /permissions에서 확인하고, 첫 읽기 연습에는 읽기 전용 범위를 사용합니다. 이 제한이 AI 서비스로 보내는 요청이나 연결된 모든 외부 도구의 행동까지 차단하는 것은 아닙니다. 막힌 작업이 있다는 이유만으로 전체 제한을 해제하지 않습니다. 자세한 구분은 코딩 에이전트 권한과 안전에 있습니다.

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

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

• 만드는 법: /init은 작업 지침 초안을 만듭니다. 기존 AGENTS.md가 있는지 먼저 확인하고 내용을 검토합니다.
• 전역 위치: 기본은 사용자 홈 자체가 아닌 ~/.codex이며 CODEX_HOME 설정으로 달라질 수 있습니다.
• 프로젝트 위치: 프로젝트 루트부터 현재 작업 폴더까지 지침을 찾습니다. 같은 폴더에 AGENTS.override.md가 있으면 AGENTS.md보다 우선합니다.
• 크기 한도: 프로젝트 지침의 기본 합산 한도는 32KiB이며 설정으로 달라집니다.

지침은 AI에게 주는 작업 규칙입니다. “원본 수정 금지”라고 적는 것만으로 운영체제의 쓰기 권한이 차단되는 것은 아닙니다. 그림의 npm test도 해당 프로젝트에 그 테스트가 준비되어 있을 때 쓰는 예시입니다.

본문의 AGENTS.md 용도를 가상 문서로 표현했습니다. 특정 프로젝트의 실제 지침이나 도구 기본 설정은 아닙니다.

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

아래 슬래시 명령은 코덱스의 대화 입력창에 입력합니다. 운영체제 터미널에 직접 입력하는 codex --version과 구분합니다.

대화형 세션을 익힌 뒤에는 codex exec "할 일"로 한 번의 작업을 실행할 수 있습니다. 이 명령도 AI 사용량을 소비합니다. 실행 전에 codex exec --help로 옵션을 확인하고 실제 적용 권한을 확인합니다. 저장된 대화는 codex resume으로 다시 열 수 있습니다.

모델은 /model에서 현재 이용 가능한 목록을 확인합니다. 첫 연습은 현재 선택된 모델로 시작하고, 다른 모델이 필요한 이유가 생겼을 때 비용과 이용 조건을 비교합니다. /review의 검토 결과도 실제 변경 내용과 테스트로 확인해야 합니다.

⚠️ 자주 하는 실수

• 원본만 두고 수정합니다: 연습용 사본을 만들고 원본을 보존합니다. Git을 쓴다면 작업 전후 기록을 남기되 기록하지 않은 파일까지 복구된다고 생각하지 않습니다.
• 연결 오류를 전부 샌드박스 탓으로 봅니다: 주소 오타, 인터넷 연결과 네트워크 제한을 구분합니다. 오류 문장을 확인한 뒤 원인에 맞게 대응합니다.
• 설명만 보고 파일이 바뀌었다고 생각합니다: “수정했다”는 답과 실제 저장된 파일을 비교합니다. 쓰기 제한에 막혔다면 허용 범위와 요청을 먼저 확인합니다.
• 모든 화면에서 같은 모델을 쓴다고 생각합니다: 현재 세션의 모델과 설정을 확인합니다.

❓ 자주 묻는 질문

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

프로그램 설치와 AI 사용 비용은 별개입니다. 실제 이용 비용은 계정의 포함 범위와 남은 사용량 또는 API 과금에 따라 정해집니다. 설치가 끝났다는 이유만으로 사용료도 무료라고 생각하지 않습니다.

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

둘 다 파일을 읽고 수정하며 명령을 실행하는 코딩 에이전트입니다. 두 도구 모두 권한과 샌드박스 관련 기능이 있으며 지원 환경과 적용 방식이 다릅니다. 같은 이름의 설정을 찾기보다 실제 읽기, 쓰기와 명령 실행 범위를 확인합니다.

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

한국어로 요청하고 답변 언어도 지정할 수 있습니다. AGENTS.md에도 한국어로 작업 지침을 적을 수 있습니다.

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

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

두 줄의 메모를 읽는 첫 실행

설치와 로그인 조건을 확인했다면 새 codex-practice 폴더를 만들고, 그 안에 아래 내용으로 meeting.txt를 저장합니다. 서식 없는 텍스트 파일로 저장하고 파일명이 meeting.txt.txt가 되지 않았는지 확인합니다.

터미널에서 cd 뒤에 이 폴더의 실제 경로를 따옴표로 감싸 입력해 이동합니다. 예를 들어 경로가 /Users/name/codex-practice인 맥이라면 cd "/Users/name/codex-practice"입니다. 예시의 name을 그대로 쓰지 말고 본인 폴더 경로로 바꿉니다. 윈도우 PowerShell에서도 cd "C:\Users\name\codex-practice"처럼 실제 경로를 씁니다.

폴더를 이동한 뒤 다음 명령으로 읽기 전용 세션을 시작합니다. 관리자 정책 때문에 이 옵션을 사용할 수 없다는 안내가 나오면 정책을 해제하지 말고 허용된 실행 방법을 확인합니다.

로그인 안내가 나오면 이용할 계정을 확인합니다. /status에서 작업 폴더와 권한을 확인한 뒤 다음과 같이 요청합니다.

meeting.txt만 읽고 회의 날짜, 시간, 장소를 각각 한 줄로 적어 줘. 파일을 만들거나 고치지 마. 원문에 없는 연도나 요일은 추정하지 마.

예상 답은 10월 15일, 오후 2시, 2층 회의실입니다. 파일을 못 찾는다면 현재 작업 폴더와 확장자를 확인합니다. 엉뚱한 날짜를 답하면 원문 두 줄을 다시 읽게 하고 직접 비교합니다. 결과를 설명한 답만 보고 실제로 파일을 읽었다고 단정하지 말고 실제 파일 읽기 기록의 경로와 내용을 확인합니다.

날짜, 시간과 장소를 맞히고 원본이 보존됐는지 확인합니다. 다시 연습하려면 사람이 메모의 장소만 3층 회의실로 저장한 뒤 같은 요청을 보냅니다. 날짜와 시간은 그대로이고 장소만 바뀌어야 합니다. 새 파일이 생기거나 원본 내용이 예상과 다르게 바뀌지 않았는지도 확인하면 첫 연습을 마친 것입니다.

📋 3줄 요약

1. 코덱스 CLI는 터미널에서 요청을 받아 파일을 읽고 수정하며 명령을 실행합니다.

2. 프로그램 설치와 AI 이용 비용은 별개이며 구독 포함 사용량과 API 과금을 구분합니다.

3. 작업 경로와 권한을 확인한 뒤 작은 연습 파일을 읽게 하고 답을 원본과 대조합니다.

참고 자료

• 코덱스 CLI 공식 설치와 시작 안내
• 코덱스 이용 범위와 과금
• 승인 정책과 샌드박스
• AGENTS.md 탐색과 적용

공식 안내 확인: 2026년 10월 3일. 연습 메모는 가상 자료입니다.