Codex 사용법: 코덱스 CLI 설치 다음 첫 세션에서 정할 네 가지

코덱스 CLI(Codex CLI)는 터미널에서 파일을 직접 읽고 고치는 OpenAI의 코딩 도구입니다. 설치를 마치고 첫 세션에서 정할 것은 네 가지입니다. 어느 폴더에서 열지, 어디까지 허용할지, 어떤 규칙 파일을 읽게 할지, 무엇부터 맡길지입니다. 설치 명령과 달리 이 네 가지는 한 줄로 끝나지 않고, 어느 것부터 정할지도 화면에 나오지 않습니다.

설치와 로그인이 아직이라면 윈도우 설치 가이드나 맥 설치 가이드를 먼저 따라 합니다.

막히는 곳은 그다음입니다. codex를 입력하면 빈 입력창에 커서만 깜빡이는데, 아무 폴더에서나 열고 승인 창을 계속 넘기다 보면 고칠 생각이 없던 파일까지 바뀌어 있기도 합니다. 그래서 쓸 폴더를 먼저 정하고, 그다음 권한을 고르는 순서로 시작합니다. 사용법은 2026년 10월 4일 공식 문서 기준입니다.

코덱스 도움말 페이지에 실린 실행 화면입니다. 상자 안에 지금 쓰는 모델 이름과 작업 폴더가 먼저 나오고, 그 아래에 명령 다섯 가지가 한 줄씩 이어집니다. 아래에서는 이 가운데 첫날에 필요한 것만 골라 다룹니다. 명령 전체 목록과 @, !, Tab 같은 입력창 단축키는 코덱스 CLI 단축키 정리에 따로 모았습니다.

1. 시작 폴더가 코덱스의 작업 범위를 정합니다

작업 루트는 코덱스가 일을 시작하는 기준 폴더이고, 기본값은 codex를 실행한 폴더입니다. 다만 이 기준은 폴더 밖의 파일을 읽는 것까지 막지는 않습니다. 첫 세션은 Git으로 관리되는 프로젝트 폴더에서 엽니다. Git은 파일의 변경 이력을 관리하는 프로그램입니다. Git으로 관리되는 폴더에서는 코덱스가 무엇을 바꿨는지 보고 되돌릴 수 있습니다.

1~2. 프로젝트 폴더로 이동하고 위치를 봅니다. 프로젝트가 Projects/my-app에 있다면 macOS에서는 이렇게 입력합니다.

Windows PowerShell에서는 다음을 입력합니다.

경로를 찾을 수 없다고 나오면 다른 폴더에서 계속하지 말고 Finder나 탐색기에서 폴더의 실제 위치를 다시 봅니다.

3. 읽기 전용으로 코덱스를 시작합니다.

4. /status로 확인합니다. 코덱스 입력창에 /status를 넣으면 모델, 권한, 작업 폴더가 나옵니다. 폴더가 다르면 /exit로 나와 올바른 폴더로 이동합니다. codex -C "실제 폴더 경로"처럼 시작할 폴더를 직접 지정하는 방법도 있습니다.

첫 답이 맞는지 판단하는 기준 두 가지

첫 요청으로는 파일을 바꾸지 않는 설명 요청이 알맞습니다. 입력창에 이렇게 보냅니다.

코덱스 공식 저장소 README에 실린 실행 화면입니다. 요청 한 줄 아래로 코덱스가 먼저 무엇을 확인할지 적은 계획이 나오고, 그 계획을 항목으로 나눈 목록이 이어집니다.

답을 받으면 두 가지를 봅니다. 첫째는 코덱스가 설명한 폴더 구조가 실제와 맞는지입니다. 둘째는 답에 이 저장소에만 있는 파일 이름이나 함수 이름이 나오는지, 아니면 어느 프로젝트에나 통하는 일반론인지입니다. 일반론만 돌아왔다면 엉뚱한 폴더에서 열었거나 요청이 모호했을 수 있으므로, 어떤 파일을 읽었는지와 설명의 근거를 묻습니다. 답이 틀렸다고 쓰기 권한부터 넓히지는 않습니다. 권한을 넓혀도 답의 근거는 생기지 않습니다.

파일을 고치게 하기 전에는 되돌릴 기준을 남깁니다. 터미널에서 git status로 기존 변경이 있는지 보고, 코덱스가 고친 뒤에는 git diff로 내용을 검토한 다음 필요한 파일만 골라 커밋합니다. 커밋은 변경 이력을 기록하는 작업입니다. 모든 파일을 한꺼번에 추가하면 다른 업무의 변경이나 비밀 파일이 섞일 수 있으므로, 필요한 파일 이름을 하나씩 지정합니다.

2. /permissions로 권한 폭 정하기

권한은 첫 세션에서 가장 오래 고민하게 되는 설정입니다. 코덱스의 권한을 정하는 설정이 하나가 아니라 둘이기 때문입니다.

• 샌드박스(--sandbox): 코덱스가 파일을 어디까지 쓸 수 있는지 정합니다. 읽기 전용인 read-only와 작업 폴더 쓰기를 허용하는 workspace-write를 먼저 구분합니다. danger-full-access는 샌드박스 제한을 해제합니다.
• 승인 정책(--ask-for-approval): 언제 사람에게 물어볼지 정합니다. on-request는 추가 허용이 필요한 작업을 묻고, never는 묻지 않습니다. never여도 샌드박스 제한은 그대로입니다.

두 값이 맞물려 지금 세션에서 코덱스가 할 수 있는 일의 범위가 정해집니다. 값 하나만 보고 판단하기보다 하려는 일에 맞춰 짝을 고르는 편이 빠릅니다.

하려는 일별 샌드박스와 승인 정책 조합

하려는 일	샌드박스	승인 정책
코드를 읽고 설명만 받기	read-only	on-request
프로젝트 안에서 고치게 하기	workspace-write	on-request
사람 없이 읽기만 자동 실행하기	read-only	never

가운데 줄 조합에서는 폴더 안의 파일 수정과 명령은 묻지 않고 진행하고, 폴더 밖 작업이나 네트워크가 필요할 때 승인을 묻습니다. 보호 경로, 명령 규칙, 외부 연결 설정에 따라 폴더 안에서도 승인을 묻는 작업이 있습니다.

코덱스는 이 조합을 Git으로 관리되는 폴더에서 쓰라고 권하고, 버전 관리가 되지 않는 폴더에서는 읽기 전용으로 시작하라고 안내합니다. 되돌릴 수단이 없는 폴더에는 쓰기를 허용하지 않는다는 뜻입니다.

세션을 켠 뒤에 바꾸려면 /permissions를 입력합니다. 공식 레퍼런스는 이 명령을 세션 도중에 승인 범위를 넓히거나 좁히는 용도로 설명하며, Read Only와 Auto 사이를 오가는 예를 듭니다. 화면에 뜬 항목은 이름보다 옆에 붙은 설명을 읽고 고릅니다.

범위를 넓힐 때는 한 번에 다 열지 않고 아래 순서로 한 단계씩 넓힙니다.

다른 폴더를 실제로 고쳐야 할 때는 일반 터미널에서 codex --add-dir "추가할 실제 폴더 경로"처럼 필요한 폴더만 지정합니다. 공식 레퍼런스는 따로 격리한 가상 머신 안이 아니면 --dangerously-bypass-approvals-and-sandbox를 쓰지 말라고 분명히 적어 두었습니다.

코덱스와 클로드 코드의 안전장치가 서로 다른 방식으로 짜여 있다는 점은 코덱스 CLI와 클로드 코드 비교에서 직접 실행해 보고 정리했습니다.

3. AGENTS.md로 같은 설명 반복 줄이기

같은 설명을 세션마다 다시 적고 있다면 규칙 파일을 만들 때입니다. 코덱스는 일을 시작하기 전에 AGENTS.md를 읽습니다. AGENTS.md는 AI가 따를 행동 지침이고, 파일에 금지 문장을 적어도 운영체제의 접근 권한까지 막지는 못합니다. 권한은 앞의 샌드박스가 정합니다.

/init으로 초안을 만들게 할 수 있습니다. 기존 파일이 있으면 먼저 읽고 원본을 보관하고, 만든 초안에 실제 프로젝트와 다른 명령이나 규칙이 없는지 봅니다. 읽기 전용 세션에서는 코덱스가 새 파일을 저장하지 못하므로 쓰기 권한이 있는 세션에서 실행합니다. 채워 두면 좋은 내용은 세 가지입니다.

• 빌드와 테스트 명령: 실제로 실행되는 명령을 그대로 적습니다. 코덱스가 결과를 스스로 확인할 때 씁니다.
• 쓰지 않기로 한 것: 이미 걷어낸 라이브러리나 더는 쓰지 않는 패턴을 적어 두면 그것을 다시 들여오는 변경이 줄어듭니다.
• 파일 배치 규칙: 새 파일을 어디에 만들지 정해 두면 엉뚱한 폴더에 생기는 일이 줄어듭니다.

처음에는 세 줄부터 시작합니다. 테스트 명령은 프로젝트에서 실제로 쓰는 것으로 바꿉니다.

저장한 뒤 /exit로 나와 새 세션을 열고 “AGENTS.md에서 읽은 규칙을 알려 줘”라고 묻습니다. 세 줄이 그대로 나오면 코덱스가 파일을 읽은 것입니다. 이 파일은 여러 곳에 둘 수 있어서 읽는 순서가 정해져 있습니다.

전역 파일을 찾을 때 코덱스는 홈 폴더(기본값 ~/.codex)에서 AGENTS.override.md를 먼저 찾고, 없으면 AGENTS.md를 읽습니다. 프로젝트 쪽도 폴더마다 AGENTS.override.md를 먼저 보고 없으면 AGENTS.md를 보며, 빈 파일은 건너뛰고 한 폴더에서 한 개만 가져갑니다. 설정된 대체 파일 이름이 있으면 그 이름도 이어서 찾습니다. 프로젝트 루트를 찾지 못하면 현재 폴더만 봅니다.

크기와 반영 시점도 정해져 있습니다. 모아 읽은 파일의 합계가 project_doc_max_bytes에 닿으면 그 뒤 파일은 싣지 않고, 기본값은 32KiB입니다. 규칙이 길어지면 이 값을 올리거나 하위 폴더로 나눕니다. 공식 문서에 따르면 지침은 실행마다 한 번 구성되고, 대화형 화면에서는 보통 세션을 띄울 때 한 번 구성됩니다. 그래서 내용을 고쳤으면 세션을 다시 엽니다.

클로드 코드를 써 왔다면 CLAUDE.md와 하는 일이 같습니다. 두 파일의 작성 기준은 CLAUDE.md 설정 공식 문서 정리에 적었습니다.

4. 처음 맡길 일과 미룰 일

설명 요청으로 결과를 확인했으면 /permissions에서 작업 폴더 쓰기를 허용하는 항목을 고르고 파일을 고치는 일로 넘어갑니다. 결과를 눈으로 바로 판단할 수 있고 되돌리기도 쉬운 일부터 고릅니다.

• 문서 다듬기: README나 설정 안내처럼 틀려도 코드가 멈추지 않는 파일부터 맡깁니다. 결과를 읽어 보면 바로 판단이 섭니다.
• 테스트 하나 추가: 테스트 실행 방법을 아는 프로젝트에서 기능 하나의 예상 결과를 정하고 검사를 추가합니다.
• 커밋 전 검토: /review를 입력하면 검토 대상을 고르는 화면이 뜹니다.

/review는 Git 저장소의 변경을 읽고 문제를 찾아 보고합니다. 일반 터미널에서는 아래 명령으로 바로 실행합니다.

반대로 익숙해진 다음으로 미룰 일도 있습니다.

• 커밋하지 않은 변경이 쌓인 폴더에서 시작하기: 되돌릴 기준이 없으면 코덱스가 고친 부분과 내가 고치던 부분이 뒤섞입니다. 기존 변경을 먼저 커밋하거나 사본을 만든 뒤 시작합니다.
• 폴더 바깥까지 고치려고 권한을 통째로 열기: 필요한 폴더만 --add-dir로 추가하면 잘못돼도 번지는 범위가 좁습니다.
• 결과가 맞는지 판단할 방법이 없는 일: 실행해 볼 수도 읽어 볼 수도 없는 코드를 맡기면 틀린 코드가 그대로 쌓입니다. 확인 절차가 있는 작업부터 고릅니다.
• 여러 파일을 한꺼번에 뜯어고치는 큰 작업: 어디가 어떻게 바뀌었는지 따라가기 어려워 검토가 밀립니다. 파일 한두 개 단위로 끊어 맡기고 중간중간 커밋합니다.

최신 자료 검색이 필요하면 --search로 실시간 웹 검색을 켤 수 있습니다. 이 웹 검색과 셸 명령의 네트워크 접근은 따로 설정하므로, 검색을 켰다고 셸 명령의 인터넷 접속까지 열리지는 않습니다.

자주 묻는 질문

설치만 하고 아직 아무것도 못 했는데 무엇부터 입력하나요?

프로젝트 폴더로 이동해 읽기 전용 명령으로 시작하고, “이 프로젝트를 설명해 줘. 파일은 바꾸지 마.”라고 요청합니다. 설명한 폴더 구조가 실제와 맞고 그 저장소에만 있는 이름이 나오는지 본 뒤 작은 수정으로 넘어갑니다.

승인 창이 계속 떠서 번거로운데 꺼도 되나요?

어떤 작업을 승인해 달라는 것인지 먼저 읽습니다. 작업 폴더 쓰기를 허용했어도 보호 경로나 명령 규칙 때문에 승인이 필요한 작업이 있습니다. never는 묻지 않을 뿐이고, 샌드박스가 막는 작업을 허용하지는 않습니다. 창을 줄이려고 작업과 무관한 전체 접근 권한을 열지는 않습니다.

AGENTS.md를 만들었는데 코덱스가 따르지 않으면 어디부터 확인하나요?

먼저 세션을 다시 엽니다. 지침은 실행마다 한 번 구성되므로 세션을 열어 둔 채로 고친 내용은 다음 세션부터 반영됩니다. 그래도 달라지지 않으면 프로젝트 루트부터 현재 폴더까지, 그리고 코덱스 홈 폴더에 AGENTS.override.md가 있는지 봅니다. 같은 폴더에 내용이 있는 이 파일이 있으면 코덱스는 AGENTS.md 대신 이 파일을 읽습니다.

참고 자료

• Codex CLI 공식 문서
• Codex CLI 명령과 옵션 레퍼런스
• AGENTS.md 공식 가이드
• Codex 승인과 샌드박스 공식 안내
• Codex 샌드박스 개념 공식 문서
• openai/codex 공식 저장소

3줄 요약

1. 코덱스 CLI는 실행한 폴더를 작업 기준으로 삼으므로 첫 세션은 Git으로 관리되는 프로젝트 폴더에서 --sandbox read-only로 엽니다.

2. 샌드박스는 파일을 어디까지 쓸지, 승인 정책은 언제 사람에게 물을지 정하며 로컬 수정에는 workspace-write와 on-request 조합을 씁니다.

3. AGENTS.md는 전역 파일부터 현재 폴더 쪽으로 이어 붙여 읽고 합계가 기본값 32KiB에 닿으면 그 뒤 파일은 싣지 않습니다.