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

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

설치와 로그인을 마쳤다면 별도 프로그램을 더 설치하기 전에 연습 폴더에서 시작할 수 있습니다. 준이아빠블로그에도 윈도우 설치 가이드 (윈도우 설치 순서 바로가기)와 맥 설치 가이드 (맥 설치 순서 바로가기)를 단계별로 적어 두었습니다.

막히는 곳은 그다음입니다. codex를 치면 빈 입력창에 커서만 깜빡이는데, 아무 폴더에서나 열고 승인 창을 계속 넘기다 보면 고칠 생각이 없던 파일까지 바뀌어 있기도 합니다. 처음 작성할 때는 2026년 9월 15일의 0.154.0 버전을 사용했습니다. 현재 사용법은 2026년 10월 4일 공식 문서를 반영했으며 두 실행 이미지는 과거 도움말과 공식 저장소의 화면입니다.

처음 온 사람에게 일할 건물을 정해 주고 그 안의 방 열쇠를 골라 건네듯, 코덱스에도 쓸 폴더를 먼저 정해 주고 권한을 골라 주는 순서로 시작합니다. 기존 안내에 사용한 실행 화면은 다음과 같습니다. 모델과 버전은 당시 표시이며 지금 계정의 기본 설정을 유지해도 됩니다.

코덱스 도움말 페이지에 실린 실행 화면입니다. 상자 안에 지금 쓰는 모델 이름과 작업 폴더가 먼저 나오고, 그 아래에 명령 다섯 가지가 한 줄씩 이어집니다. 아래에서는 이 가운데 첫날에 필요한 것만 골라, 폴더와 권한을 확인하고 첫 읽기 요청과 규칙 파일을 시험하는 순서로 다룹니다. 명령 전체 목록과 @, !, Tab 같은 입력창 단축키는 코덱스 CLI 단축키 정리 (명령어와 단축키 전체 목록 바로가기)에 따로 모아 두었습니다.

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

작업 루트는 Codex가 일을 시작하는 기준 폴더입니다. 기본적으로 codex를 실행한 폴더가 기준이지만, 그 밖의 파일을 전혀 읽지 못하도록 격리했다는 뜻은 아닙니다.

첫날에는 중요한 자료가 없는 연습 폴더를 사용합니다. 앞의 설치 가이드에서 만든 Projects/codex-practice를 쓴다면 macOS에서 다음처럼 이동합니다.

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

경로를 찾을 수 없다고 나오면 다른 폴더에서 계속하지 말고 설치 가이드의 폴더 만들기 단계부터 확인합니다. Finder나 탐색기에서 같은 폴더를 열고, 편집기로 meeting.md를 일반 텍스트와 UTF-8로 저장합니다. 내용은 다음 두 줄입니다.

파일 이름이 meeting.md.txt로 바뀌지 않았는지 확인한 뒤 일반 터미널에서 Codex를 시작합니다.

Codex 대화 입력칸에 /status를 넣으면 모델, 권한과 작업 폴더 등을 확인할 수 있습니다. 폴더가 다르면 /exit로 나와 올바른 폴더로 이동합니다. codex -C "실제 폴더 경로"처럼 시작할 폴더를 직접 지정하는 방법도 있지만, 처음에는 위 순서 하나만 익혀도 됩니다.

첫 답을 검증하는 기준 두 가지

Codex 대화 입력칸에 아래 문장을 보냅니다.

날짜가 2026-10-12, 장소가 도서관 2층인지 파일과 대조합니다. 답변만으로는 판단하지 말고 원본 파일을 편집기에서 다시 열어 내용이 유지됐는지도 확인합니다. Codex 요청에는 계정의 사용량이 적용됩니다.

파일을 찾지 못했다면 /status의 폴더와 실제 파일 이름부터 확인합니다. 날짜나 장소를 임의로 채웠다면 원문과 다른 부분을 알려 주고 다시 읽게 합니다. 잘못된 답을 해결하려고 쓰기 권한부터 넓히지 않습니다.

코덱스 공식 저장소 README에 실린 실행 화면입니다. 요청 한 줄 아래로 코덱스가 먼저 무엇을 확인할지 적은 계획이 나오고, 그 계획을 항목으로 나눈 목록이 이어집니다. 이 화면이 올라온 당시의 값이라 지금 설치되는 것과는 모델 이름도 버전도 다릅니다.

실제 개발 프로젝트가 있다면 공식 화면처럼 “이 프로젝트를 설명해 줘. 파일은 바꾸지 마.”라고 확장할 수 있습니다. 답을 받으면 두 가지를 봅니다. 첫째는 코덱스가 설명한 폴더 구조가 실제와 맞는지입니다. 둘째는 그 답에 이 저장소에만 있는 이름이 나오는지, 아니면 어느 프로젝트에나 통하는 일반론인지입니다. 둘째가 특히 중요한데, 일반론만 돌아왔다면 어떤 파일을 읽었는지와 설명의 근거를 물어봅니다. 폴더가 잘못됐거나 요청이 모호했을 수 있습니다. 두 조건이 맞아도 프로젝트 전체와 코드 품질까지 검증한 것은 아닙니다.

파일 수정 전에는 되돌릴 원본을 남깁니다. 첫 메모 실습은 편집기나 Finder, 탐색기에서 meeting.md를 복제해 meeting-before.md로 보관하면 됩니다. 같은 이름의 사본이 이미 있으면 다른 이름을 씁니다.

Git은 파일 변경 이력을 관리하는 프로그램입니다. 이를 사용하는 실제 저장소에서는 git status로 기존 변경을 보고 git diff로 내용을 검토한 뒤, 필요한 파일만 선택해 커밋합니다. 커밋은 변경 이력을 기록하는 작업입니다. 모든 파일을 한꺼번에 추가하면 다른 업무의 변경이나 비밀 파일이 섞일 수 있으므로 이 글에서는 일괄 커밋 명령을 사용하지 않습니다.

/permissions로 권한 폭 정하기

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

• 샌드박스(--sandbox): 코덱스가 파일을 어디까지 쓸 수 있는지 정합니다. 읽기 전용인 read-only와 작업 폴더 쓰기를 허용하는 workspace-write를 먼저 구분합니다. danger-full-access는 이런 샌드박스 제한을 해제하므로 첫 실습에 필요하지 않습니다.
• 승인 정책(--ask-for-approval): 언제 사람에게 물어볼지 정합니다. on-request는 추가 허용이 필요한 작업을 물어볼 수 있고, never는 승인 요청을 하지 않습니다. never라고 해서 샌드박스가 함께 해제되지는 않습니다. 세부 승인 범주나 조직 정책이 추가로 적용될 수도 있습니다.

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

가운데 줄은 로컬 파일 수정에 흔히 쓰는 조합입니다. 허용된 파일 수정과 명령은 자동으로 진행할 수 있고, 범위 밖 작업이나 네트워크가 필요하면 추가 승인이 요구될 수 있습니다. 보호 경로, 명령 규칙과 외부 연결에 따라 폴더 안의 작업에도 별도 제한이 적용됩니다.

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

세션을 켠 뒤에 바꾸고 싶으면 /permissions를 칩니다. 공식 레퍼런스는 이 명령을 세션 도중에 승인 범위를 넓히거나 좁히는 용도로 설명하면서, Read Only와 Auto 사이를 오가는 예를 듭니다. 화면에 뜨는 항목 이름은 버전에 따라 달라지므로 이름을 외우기보다 옆에 붙은 설명을 읽고 고릅니다.

방 열쇠를 하나씩 건네는 것과 건물 출입증을 통째로 넘기는 것이 다르듯, 범위를 넓히는 방법에도 단계가 있습니다. 따로 격리한 가상 머신 안이 아니면 --dangerously-bypass-approvals-and-sandbox를 쓰지 말라고 공식 레퍼런스가 분명히 적어 두었습니다. 다른 폴더를 실제로 수정해야 할 때는 일반 터미널에서 codex --add-dir "추가할 실제 폴더 경로"처럼 필요한 폴더를 지정할 수 있습니다. 표시한 예제 문구는 실제 경로로 바꿉니다.

코덱스와 클로드 코드의 안전장치가 서로 다른 방식으로 짜여 있다는 점은 코덱스 CLI와 클로드 코드 비교 (두 도구의 안전장치 비교 바로가기)에서 직접 돌려 보고 정리했습니다.

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

같은 설명을 세션마다 다시 적고 있다면 규칙 파일을 만들 때가 된 것입니다. 현관에 붙여 둔 쪽지를 새로 온 사람이 먼저 읽듯, 코덱스도 일을 시작하기 전에 AGENTS.md를 읽습니다.

/init으로 초안을 요청할 수 있지만 기존 파일이 있으면 먼저 읽고 원본을 보관합니다. 생성된 초안에 실제 프로젝트와 다른 명령이나 규칙이 없는지 확인해야 합니다. 읽기 전용 상태에서 새 파일이 자동으로 저장된다고 기대하지 않습니다. 채워 두면 좋은 내용은 세 가지입니다.

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

연습 폴더에서는 복잡한 개발 규칙 대신 편집기로 AGENTS.md를 만들어 다음 세 줄부터 시험할 수 있습니다. 이미 같은 이름의 파일이 있으면 덮어쓰지 말고 기존 내용에 맞춰 필요한 항목만 추가합니다.

Codex를 /exit로 종료하고 앞의 읽기 전용 명령으로 새 세션을 엽니다. meeting.md의 장소 줄을 편집기에서 지운 뒤 저장하고 날짜와 장소를 다시 물어봅니다. 날짜는 원본대로, 장소는 “확인 필요”로 나오는지 확인합니다. 이 시험은 규칙 적용을 확인하는 작은 예시이며 모든 상황에서 규칙을 지킬 것이라는 보장은 아닙니다. 시험 뒤에는 사본을 참고해 장소 줄을 되돌립니다.

AGENTS.md는 AI가 따라야 할 행동 지침입니다. 파일에 금지 문장을 적었다고 운영체제의 접근 권한까지 차단되는 것은 아닙니다.

이 파일은 여러 곳에 둘 수 있어서 읽는 차례도 정해져 있습니다. 공식 안내에 적힌 차례는 이렇습니다.

1. 전역 파일: 코덱스 홈 폴더(기본값 ~/.codex)에서 AGENTS.override.md를 먼저 찾고, 없으면 AGENTS.md를 읽습니다. 내용이 있는 파일 가운데 먼저 찾은 하나만 씁니다.
2. 프로젝트 파일: 프로젝트 루트에서 지금 폴더까지 내려오며 폴더마다 AGENTS.override.md를 먼저 보고 없으면 AGENTS.md를 봅니다. 빈 파일은 건너뛰고 한 폴더에서 한 개만 가져갑니다. 설정된 대체 파일 이름이 있으면 그 순서도 이어서 확인합니다. 여기서 말하는 루트는 보통 Git 루트이고, 루트를 찾지 못하면 현재 폴더만 확인합니다.
3. 합치는 방향: 루트부터 차례로 이어 붙이므로 현재 폴더에 가까운 파일이 뒤에 놓이며 충돌하는 지침에서는 더 구체적인 지침을 따릅니다. 앞의 파일 전체를 버린다는 뜻은 아닙니다.

주의할 점이 두 가지 있습니다. 하나는 크기입니다. 모아 읽은 파일의 합계가 project_doc_max_bytes에 닿으면 그 뒤 파일은 싣지 않습니다. 기본값이 32KiB이므로 길어지면 이 값을 올리거나 하위 폴더로 나눠 둡니다. 다른 하나는 반영 시점입니다. 공식 문서는 지침을 실행마다 한 번 구성하고 대화형 화면에서는 보통 세션을 띄울 때 한 번이라고 적고 있어서, 내용을 고쳤으면 세션을 다시 열어 보는 편이 확실합니다.

클로드 코드를 써 오신 분이라면 CLAUDE.md와 하는 일이 같습니다. 두 파일의 작성 기준은 CLAUDE.md 설정 공식 문서 정리 (규칙 파일 작성 기준 바로가기)에 적어 두었습니다.

처음 맡기기 좋은 일 세 가지

읽기 요청으로 감을 잡았으면 이제 파일을 고치는 일로 넘어갑니다. 첫 메모 실습에서는 원본 사본을 보관한 뒤, Codex 대화 입력칸의 /permissions에서 작업 폴더 쓰기를 허용하는 항목의 설명을 확인해 선택합니다. 이어서 “meeting.md의 날짜만 2026-10-19로 바꿔 줘. 장소와 다른 파일은 그대로 둬.”라고 요청합니다. 실제 파일에서 날짜만 바뀌었는지 확인합니다. 다른 내용도 바뀌었다면 다음 요청을 멈추고 두 파일을 비교합니다. 이 연습에서 자신의 다른 수정이 없을 때는 meeting-before.md의 내용으로 meeting.md를 복구한 뒤 다시 시도할 수 있습니다. 실제 업무 파일에서는 이번 변경만 되돌려 다른 수정이 사라지지 않게 합니다. 혼자 반복할 때는 날짜를 2026-10-26으로 바꿔 다시 확인합니다.

그다음에는 결과를 눈으로 확인할 수 있고 되돌리기도 쉬운 일부터 고릅니다. 아래 셋이 그 조건에 맞습니다.

• 문서 다듬기: README나 설정 안내처럼 틀려도 코드가 멈추지 않는 파일부터 맡깁니다. 결과를 읽어 보면 바로 판단이 섭니다.
• 테스트 하나 추가: 테스트 실행 방법을 아는 개발 프로젝트에서 기능 하나의 예상 결과를 정하고 검사를 추가합니다. 테스트 통과가 모든 오류를 배제하는 것은 아닙니다.
• 커밋 전 검토: /review를 치면 검토 대상을 고르는 화면이 뜹니다. 아직 커밋하지 않은 변경, 특정 커밋, 기준 브랜치와의 차이, 직접 적은 검토 기준 가운데 하나를 고릅니다.

마지막 항목은 Git 저장소를 대상으로 합니다. 단순한 메모 폴더에서 반드시 실행할 단계는 아닙니다. 공식 안내상 검토는 문제를 보고하는 과정이며, 아래 명령은 일반 터미널에서 실행합니다. 지적이 없다고 오류가 없음을 보장하지는 않습니다.

처음부터 맡기지 않는 편이 나은 일

반대로 미룰 일도 정해 두면 초반에 헛걸음이 줄어듭니다. 아래 네 가지는 익숙해진 다음으로 미루시기를 권합니다.

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

첫 실습에는 인터넷이 필요하지 않습니다. 나중에 최신 자료 검색이 필요하면 --search로 실시간 웹 검색을 사용할 수 있습니다. 이 웹 검색과 셸 명령의 네트워크 접근은 별도 설정이므로, 검색이 된다고 모든 프로그램의 인터넷 접속도 허용된 것은 아닙니다.

자주 묻는 질문

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

위의 연습 폴더에서 meeting.md를 준비하고 읽기 전용 명령으로 시작합니다. 날짜와 장소를 물어보고 실제 파일과 대조합니다. 원문과 같은 답변을 받고 파일이 유지되는지 확인한 뒤 작은 수정으로 넘어갑니다.

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

어떤 작업을 승인해 달라는 것인지 먼저 읽습니다. 작업 폴더 쓰기를 허용했어도 보호 경로나 명령 규칙 때문에 승인이 필요할 수 있습니다. never는 승인 요청을 하지 않는 설정이며, 제한된 작업을 자동으로 모두 허용하는 설정은 아닙니다. 창을 줄이려고 작업과 무관한 전체 접근 권한을 열지는 않습니다.

AGENTS.md를 만들었는데 코덱스가 따르지 않으면 어디를 보면 되나요?

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

참고 자료

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

3줄 요약

1. 첫 세션은 연습 폴더에서 읽기 전용으로 시작하고 답변을 실제 파일과 대조합니다.

2. 샌드박스는 실행 범위를 제한하고 승인 정책은 추가 작업을 언제 물어볼지 정합니다.

3. AGENTS.md에는 확인할 수 있는 짧은 규칙을 적고 새 세션에서 적용 여부를 시험합니다.