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

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

설치는 짧게 끝납니다. 맥과 리눅스는 설치 스크립트 한 줄, 윈도우는 PowerShell 한 줄이면 되고 npm이나 Homebrew로 받는 방법도 따로 있습니다. 준이아빠블로그에도 윈도우 설치 가이드 (윈도우 설치 순서 바로가기)와 맥 설치 가이드 (맥 설치 순서 바로가기)를 단계별로 적어 두었습니다.

막히는 곳은 그다음입니다. codex를 치면 빈 입력창에 커서만 깜빡이는데, 아무 폴더에서나 열고 승인 창을 계속 넘기다 보면 고칠 생각이 없던 파일까지 바뀌어 있기도 합니다. 본문 설명은 2026년 9월 15일에 코덱스 공식 문서와 실제로 설치된 0.154.0 버전에서 확인했고, 실행 화면 두 장은 도움말 페이지와 공식 저장소에서 가져왔습니다.

처음 온 사람에게 일할 건물을 정해 주고 그 안의 방 열쇠를 골라 건네듯, 코덱스에도 쓸 폴더를 먼저 정해 주고 권한을 골라 주는 순서로 시작합니다. 실행하면 뜨는 화면은 이렇습니다.

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

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

코덱스는 명령을 친 폴더를 작업 루트로 잡습니다. 공식 빠른 시작 안내도 프로젝트 폴더를 연 다음 codex를 실행하라고 적고 있습니다. 홈 폴더에서 그냥 열면 코덱스가 저장소 구조를 모르는 상태로 시작합니다.

그래서 순서가 하나 늘어납니다. 고칠 프로젝트로 먼저 이동한 뒤에 실행합니다.

매번 폴더를 옮겨 다니기가 번거로우면 실행할 때 폴더를 지정하는 방법도 있습니다. -C 또는 --cd 옵션에 경로를 적으면 그 폴더가 기준이 됩니다.

코덱스가 지금 어느 폴더에서 어떤 권한으로 돌아가고 있는지 모르겠으면 세션 안에서 /status를 칩니다. 현재 세션 설정과 함께 쓰기가 허용된 폴더 목록, 남은 컨텍스트 양도 같이 나옵니다.

프로젝트 폴더 바깥의 파일까지 고쳐야 하는 경우도 있습니다. 이때 권한을 통째로 여는 대신 --add-dir로 필요한 폴더만 추가합니다. 공식 안내도 쓰기 범위를 넓혀야 하면 danger-full-access로 올리기보다 --add-dir를 쓰라고 권합니다.

지금 저장소를 그대로 두고 시험해 보고 싶으면 --worktree 옵션으로 새 Git 워크트리를 만들어 그 안에서 세션을 돌리는 방법도 있습니다.

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

공식 빠른 시작 안내는 첫 작업의 예로 Tell me about this project, 즉 이 프로젝트를 설명해 달라는 요청을 보여 줍니다. 한국어로 그대로 쳐도 되고, 설치 가이드의 마지막 단계에서 한 번 해 보셨을 요청이기도 합니다.

정작 중요한 것은 그 답을 어떻게 읽느냐입니다. 파일이 바뀌지 않는 요청이라 틀려도 잃을 것이 없고, 그만큼 코덱스가 이 저장소를 제대로 보고 있는지 값싸게 확인할 기회입니다.

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

답을 받으면 두 가지를 봅니다. 첫째는 코덱스가 설명한 폴더 구조가 실제와 맞는지입니다. 둘째는 그 답에 이 저장소에만 있는 이름이 나오는지, 아니면 어느 프로젝트에나 통하는 일반론인지입니다. 둘째가 특히 중요한데, 일반론만 돌아왔다면 코덱스가 파일을 제대로 읽지 못했다는 신호이고 폴더를 잘못 열었을 가능성이 큽니다. 둘 다 맞으면 같은 세션에서 바로 다음 일을 맡겨도 됩니다.

파일을 고치는 요청으로 넘어가기 전에 공식 빠른 시작 안내가 권하는 준비가 하나 있습니다. 작업 전후로 Git 체크포인트를 만들어 두는 것입니다. 커밋을 하나 찍어 두면 결과가 엉뚱하게 나왔을 때 되돌릴 기준이 생깁니다.

/permissions로 권한 폭 정하기

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

• 샌드박스(--sandbox): 코덱스가 파일을 어디까지 쓸 수 있는지 정합니다. 값은 read-only, workspace-write, danger-full-access 셋이고, 각 값이 정확히 무엇을 여는지는 코덱스 CLI 사용법 (샌드박스 값별 설명 바로가기)에 표로 있습니다.
• 승인 정책(--ask-for-approval): 언제 사람에게 물어볼지 정합니다. 0.154.0 도움말에 있는 값은 모델이 필요할 때 물어보는 on-request와 아예 묻지 않는 never 둘입니다.

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

가운데 줄이 대화형 작업에서 승인 창을 가장 적게 띄우는 조합입니다. 공식 레퍼런스도 마찰이 적은 로컬 작업에는 이 짝을 쓰라고 적어 두었습니다. 작업 루트 안에서는 코덱스가 파일을 고치되, 그 바깥으로 나가거나 네트워크가 필요하면 그때 물어보는 방식입니다.

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

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

방 열쇠를 하나씩 건네는 것과 건물 출입증을 통째로 넘기는 것이 다르듯, 범위를 넓히는 방법에도 단계가 있습니다. 따로 격리한 가상 머신 안이 아니면 --dangerously-bypass-approvals-and-sandbox를 쓰지 말라고 공식 레퍼런스가 분명히 적어 두었습니다. 코덱스가 고칠 수 있는 범위가 좁아서 생긴 문제라면 앞에서 본 --add-dir가 먼저입니다.

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

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

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

초안은 /init이 만들어 줍니다. 다만 만들어지는 것은 뼈대뿐이라 내용은 사람이 채웁니다. 채워 두면 좋은 내용은 세 가지입니다.

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

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

1. 전역 파일: 코덱스 홈 폴더(기본값 ~/.codex)에서 AGENTS.override.md를 먼저 찾고, 없으면 AGENTS.md를 읽습니다. 둘 중 먼저 찾은 하나만 씁니다.
2. 프로젝트 파일: 프로젝트 루트에서 지금 폴더까지 내려오며 폴더마다 AGENTS.override.md를 먼저 보고 없으면 AGENTS.md를 봅니다. 한 폴더에서 한 개만 가져갑니다. 여기서 말하는 루트는 보통 Git 루트이고, 루트를 찾지 못하면 현재 폴더만 확인합니다.
3. 합치는 방향: 루트부터 차례로 이어 붙이므로 현재 폴더에 가까운 파일이 뒤에 놓여 앞의 지침을 덮습니다.

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

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

처음 맡기기 좋은 일 세 가지

읽기 요청으로 감을 잡았으면 이제 파일을 고치는 일로 넘어갑니다. 첫 며칠은 결과를 눈으로 확인할 수 있고 되돌리기도 쉬운 일부터 고릅니다. 아래 셋이 그 조건에 맞습니다.

• 문서 다듬기: README나 설정 안내처럼 틀려도 코드가 멈추지 않는 파일부터 맡깁니다. 결과를 읽어 보면 바로 판단이 섭니다.
• 테스트 하나 추가: 이미 돌아가는 기능에 테스트를 붙이는 일은 범위가 분명하고, 한 번 돌려 보면 맞는지 바로 알 수 있습니다.
• 커밋 전 검토: /review를 치면 검토 대상을 고르는 화면이 뜹니다. 아직 커밋하지 않은 변경, 특정 커밋, 기준 브랜치와의 차이, 직접 적은 검토 기준 가운데 하나를 고릅니다.

마지막 항목은 특히 부담이 적습니다. 공식 안내에 따르면 검토는 작업 루트를 고치지 않고 문제만 골라 알려 주는 방식이라, 권한을 올리지 않아도 결과가 나옵니다.

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

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

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

인터넷에서 자료를 받아야 하는 작업도 처음에는 빼 두는 쪽이 낫습니다. workspace-write에서 막히는 것은 코덱스가 실행하는 셸 명령의 네트워크 접근이고, 이 설정은 따로 열어야 합니다. 막힌 화면과 여는 옵션 한 줄은 코덱스 CLI 사용법 (네트워크가 막힌 출력과 여는 옵션 바로가기)에 있습니다. 다만 최신 자료를 참고하게 하려는 것뿐이라면 샌드박스를 여는 대신 --search로 캐시 대신 라이브 웹 검색을 쓰게 하는 쪽이 먼저입니다.

자주 묻는 질문

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

고칠 프로젝트 폴더로 이동한 뒤 codex를 실행하고, 이 저장소가 무슨 프로젝트인지 한국어로 물어봅니다. 파일이 바뀌지 않는 요청이라 잘못되어도 되돌릴 것이 없습니다. 답이 실제 폴더 구조와 맞으면 그다음부터 문서 수정처럼 작은 일을 맡깁니다.

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

프로젝트 안에서만 고치는 작업이라면 --sandbox workspace-write --ask-for-approval on-request 조합으로 시작합니다. 그 안에서는 묻지 않고, 바깥으로 나가거나 네트워크가 필요할 때만 물어봅니다. 승인을 아예 끄는 never는 사람이 지켜보지 않는 비대화형 실행에 쓰는 값이라, 평소 작업하는 폴더에서 켜 두지 않는 편이 안전합니다.

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

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

3줄 요약

1. 코덱스 CLI는 codex를 친 폴더를 작업 범위로 잡습니다. 설치한 폴더가 아니라 고칠 저장소로 이동한 뒤에 실행하고, 폴더가 더 필요하면 --add-dir로 추가합니다.
2. 권한은 쓰기 범위를 정하는 샌드박스와 언제 물어볼지 정하는 승인 정책 두 가지로 정해집니다. 세션 도중에는 /permissions로 바꿉니다.
3. 저장소 루트에 둔 AGENTS.md는 실행마다 한 번 읽혀 같은 설명을 반복하지 않게 해 줍니다. 첫 작업은 문서 다듬기나 테스트 추가처럼 결과를 눈으로 확인하고 되돌릴 수 있는 것부터 고릅니다.

Sources

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