ChatGPT Codex 활용법, 설치 네 가지와 AGENTS.md·권한 모드를 CLI 도움말과 공식 문서로 확인했어요

ChatGPT Codex 를 터미널에서 써 보려고 찾아보면 설치 명령만 적힌 글과 옵션 이름만 늘어놓은 글이 섞여 나와요. 막상 켜 보면 궁금한 건 순서예요. 무엇으로 설치하고, 어떻게 로그인하고, 지시문은 어디에 두고, 얼마나 맡길지를 어디서 정하는지요.

결론부터 적을게요. 2026년 9월 23일 한국 시각 오후 1시 무렵에 Codex CLI 0.156.1 을 내려받아 도움말을 직접 출력했고, 오픈AI 공식 문서와 공개 저장소 원문을 받아 맞대어 봤어요. 공식 CLI 문서가 적은 설치 방법은 네 가지이고, 지시 파일 AGENTS.md 는 전역 한 개와 폴더마다 최대 한 개씩 읽어 합치며 기본 한도는 32KiB 예요. 샌드박스는 세 가지, 이 버전 도움말이 적은 승인 정책 값은 두 가지였어요.

미리 적어 둘 것이 있어요. 이 글은 도움말 출력과 문서만 따라가요. 로그인을 하지 않았고 작업을 한 번도 실행하지 않았어요. 그래서 결과물 품질이나 속도에 대한 이야기는 없어요. 여러 도구의 무료 한도를 견준 내용이 궁금하다면 터미널 AI 코딩 CLI 세 가지를 비교한 글 쪽이 따로 있어요.

공식 문서가 적은 설치 방법은 네 가지예요

공식 문서의 CLI 페이지는 아래 네 갈래를 적어요. 저장소 README 도 같은 네 갈래를 적고, 여기에 GitHub 최신 릴리스에서 macOS 와 Linux 용 실행 파일을 직접 내려받는 방법을 접힌 항목으로 하나 더 붙여 둬요. 저장소의 설치 문서에는 DotSlash 파일과 소스 빌드 방법도 따로 나와요.

독립 설치기가 어디서 파일을 받는지도 README 가 적어 둬요. 기본은 releases.openai.com 이고, 메타데이터나 파일을 못 받으면 GitHub Releases 로 넘어가요. 처음부터 GitHub Releases 로만 받고 싶다면 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM 을 false 로 두면 된다고 적혀 있어요. 회사 네트워크에서 한쪽 주소만 열려 있을 때 쓸 만한 스위치예요.

제가 실제로 쓴 길은 npm 쪽이에요. 전역 설치 대신 npx -y @openai/[email protected] 로 받아 바로 버전과 도움말을 찍었어요. --version 출력은 codex-cli 0.156.1 이었어요. npm 레지스트리를 조회해 보니 이 패키지의 최신판 요구 조건은 Node.js 16 이상이었고, 운영체제와 칩 종류별 태그가 따로 붙어 있었어요. Windows x64 용 태그도 그 안에 있었어요.

여기서 문서끼리 결이 다른 자리가 하나 있어요. 저장소의 설치 문서에 있는 시스템 요건 표는 운영체제를 macOS 12 이상, Ubuntu 20.04 이상과 Debian 10 이상, 그리고 Windows 11 은 WSL2 경유로 적어요. 그런데 README 와 공식 CLI 문서는 Windows 용 PowerShell 설치기를 따로 적어요. 제 경우 WSL 이 아닌 Windows 환경에서 도움말 출력까지는 문제없이 됐어요. 다만 도움말이 나오는 것과 작업이 끝까지 도는 것은 다른 이야기이고, 두 문서의 관계를 설명한 문장은 찾지 못했어요. 같은 표에는 메모리 4GB 이상(8GB 권장), Git 2.23 이상(선택, 권장)도 적혀 있어요.

첫 실행과 로그인

설치가 끝나면 프로젝트 폴더로 가서 codex 를 실행하라고 문서가 적어요. 처음 실행하면 Sign in with ChatGPT 나 다른 로그인 방법을 고르는 화면이 나온다고 해요. 챗GPT 로 로그인하면 브라우저 창이 열리고, 로그인한 뒤 자격 정보가 Codex 로 돌아오는 흐름이에요.

인증 문서가 적은 선택지를 표로 옮기면 이래요.

API 키로 들어가면 챗GPT 플랜에 포함된 사용량 대신 표준 API 요금이 적용되고, 챗GPT 워크스페이스나 클라우드 서비스에 기대는 일부 기능은 제한되거나 쓸 수 없다고 문서가 적어요. 같은 문서가 CI 같은 자동화 작업에는 API 키 인증을 쓰라고 권하면서, 믿을 수 없는 환경이나 공개된 환경에 Codex 실행을 노출하지 말라고 덧붙여요.

기기 코드 로그인은 조건이 하나 붙어요. 개인 계정이면 챗GPT 보안 설정에서, 워크스페이스라면 관리자 권한 설정에서 기기 코드 로그인을 먼저 켜 둬야 한다고 적혀 있어요.

로그인 정보가 어디에 남는지도 알아 두면 좋아요. 문서는 Codex 가 로그인 정보를 홈 폴더 아래 .codex/auth.json 평문 파일이나 운영체제의 자격 증명 저장소에 보관한다고 적어요. 평문 파일로 남을 수 있다는 뜻이니 이 폴더를 백업하거나 공유할 때 조심해야 해요.

로그인이 끝나면 문서가 권하는 첫 작업은 이 한 줄이에요.

Tell me about this project

그리고 같은 페이지가 작업 전후로 Git 체크포인트를 만들어 두라고 권해요. 되돌릴 자리를 먼저 만들어 두라는 뜻이에요.

AGENTS.md 는 이렇게 읽혀요

Codex 를 오래 쓸수록 쓸모가 커지는 것이 AGENTS.md 예요. 문서 첫 문장이 Codex 는 어떤 작업을 하기 전에 AGENTS.md 파일을 읽는다는 거예요. 테스트 명령, 쓰는 패키지 매니저, 금지 사항 같은 약속을 매번 말로 하지 않고 파일로 남겨 두는 자리예요.

읽는 순서는 세 단계로 적혀 있어요.

이 표에서 실수하기 쉬운 자리가 두 곳이에요.

• 폴더마다 한 파일뿐이에요. 같은 폴더에 AGENTS.override.md 와 AGENTS.md 가 같이 있으면 override 쪽만 읽혀요. 문서 예시 그림에도 override 가 있어서 무시된다는 설명이 붙어 있어요.
• 지금 폴더에서 멈춰요. 작업 폴더보다 더 아래에 있는 파일은 읽지 않으니, 특정 서비스용 규칙은 그 작업을 하는 폴더 가까이에 두라고 문서가 적어요. 프로젝트 루트를 찾지 못하면 지금 폴더만 확인한다고 해요.

크기 한도도 있어요. 빈 파일은 건너뛰고, 합친 크기가 project_doc_max_bytes 에 닿으면 더 붙이지 않아요. 기본값은 32KiB 예요. 규칙이 길어져 잘린다면 이 값을 올리거나 규칙을 하위 폴더로 나누라고 문서가 권해요. 문서 예시는 이 값을 65536 으로 올리는 모습이에요.

이미 다른 이름으로 팀 규칙 파일을 쓰고 있다면 설정 파일의 project_doc_fallback_filenames 목록에 그 이름을 넣으면 돼요. 문서 예시는 TEAM_GUIDE.md 와 .agents.md 를 넣고, 그러면 폴더마다 AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md 순서로 본다고 적어요. 목록에 없는 이름은 지시 파일로 취급하지 않아요.

잘 읽혔는지 확인하는 방법도 문서에 있어요. 저장소 루트에서 이렇게 실행하면 전역과 프로젝트 파일의 지시를 우선순위대로 요약해 준다고 해요.

codex --ask-for-approval never "Summarize the current instructions."

문서는 Codex 가 실행할 때마다, 그리고 대화형 화면은 세션을 열 때마다 지시 사슬을 새로 만든다고 적어요. 지워야 할 캐시가 따로 없다는 뜻이라, 파일을 고쳤는데 반영이 안 된 것 같으면 그 폴더에서 Codex 를 다시 시작하면 돼요. 임시로 전역 규칙을 바꾸고 싶을 때는 원래 파일을 지우지 말고 홈 아래 .codex/AGENTS.override.md 를 만들었다가 나중에 지우라고 권해요.

권한은 샌드박스와 승인 두 개로 나뉘어요

Codex 에게 얼마나 맡길지는 두 가지 통제가 함께 정해요. 문서 표현으로는 샌드박스가 어떤 파일과 네트워크에 닿을 수 있는지를 정하고, 승인이 언제 멈춰서 물어볼지를 정해요.

화면에서 고르는 세 모드

권한 문서가 적은 모드는 세 가지예요.

여기서 가장 많이 오해하는 자리가 Approve for me 예요. 이름만 보면 더 많이 허락하는 모드 같지만, 문서는 검토를 누가 하느냐를 바꾸는 것이 샌드박스를 넓히지는 않는다고 적어요. CLI 안에서는 /permissions 를 입력해 모드를 바꾸고, 지금 적용된 샌드박스와 쓰기 가능한 폴더를 확인할 수 있다고 해요.

도움말에 적힌 옵션

0.156.1 도움말에서 권한과 관련된 옵션만 추려 보면 이래요.

보안 문서가 적은 기본값도 같이 봐 두면 좋아요.

• 네트워크는 기본으로 꺼져 있어요. 기본 workspace-write 샌드박스는 설정에서 켜지 않는 한 네트워크를 막아 둔다고 적혀 있어요.
• 폴더 종류에 따라 권장이 달라요. 실행할 때 버전 관리 여부를 보고, 버전 관리가 되는 폴더에는 작업 폴더 쓰기와 요청 시 승인 조합인 Auto 를, 안 되는 폴더에는 read-only 를 권한다고 해요. 설정에 따라서는 폴더를 신뢰한다고 밝히기 전까지 읽기 전용으로 시작할 수도 있다고 적혀 있어요.
• 쓰기가 허용된 폴더 안에도 보호되는 자리가 있어요. 그 안의 .git 은 폴더든 파일이든 읽기 전용으로 보호되고, .agents 와 .codex 폴더도 있으면 읽기 전용이에요. 보호는 하위 폴더까지 그대로 적용된다고 해요.
• 작업 공간에는 임시 폴더도 들어가요. 지금 폴더와 함께 /tmp 같은 임시 폴더가 포함되고, /status 명령으로 어떤 폴더가 들어 있는지 볼 수 있다고 적혀 있어요.

문서와 도움말이 다른 자리

문서를 읽다 보면 이 버전 도움말 목록에는 없는 이름이 몇 개 나와요. 도움말에 안 보인다고 곧 없는 옵션은 아니어서, 두 개는 작업을 실행하지 않고 --version 과 함께 넘겨 인자로 받아들여지는지만 따로 확인했어요.

대조를 위해 아예 없는 이름인 --bogus-flag 도 같은 방식으로 넘겨 봤는데, --full-auto 와 똑같은 오류가 나왔어요. 그러니 이 버전에서 --full-auto 는 문서 설명과 달리 받아 주지 않는다고 보는 게 맞아요. 문서는 대화 없는 실행에 codex exec --sandbox workspace-write 를 쓰라고 적어요. 반대로 --yolo 는 도움말에 안 보일 뿐 받아들여졌어요. 샌드박스도 승인도 없는 조합이라, 문서 표도 권장하지 않는다고 적어 두었어요. 옛 글에서 본 옵션이 안 먹는다면 먼저 설치한 버전의 도움말을 열어 보세요. 사라진 untrusted 대신 문서가 적은 예시는 이 한 줄이에요.

codex --sandbox read-only --ask-for-approval on-request

자주 쓰게 될 하위 명령

0.156.1 도움말의 명령 목록에는 help 를 포함해 27개가 있었어요. help 를 빼면 26개이고, 그중 네 개(app-server, remote-control, cloud, exec-server)에는 실험 기능 표시가 붙어 있었어요. 처음 쓸 때 손이 갈 만한 것만 골랐어요.

codex review 가 특히 쓸모 있어요. 커밋하지 않은 변경, 특정 커밋, 기준 브랜치와의 차이 중 하나를 골라 리뷰를 받을 수 있고, 공식 문서는 이 리뷰가 작업 트리를 고치지 않고 우선순위를 매긴 지적만 보고한다고 적어요. 커밋 직전에 한 번 돌려 보는 용도로 맞아요.

대화 중에 쓰는 옵션도 두 개 알아 두면 좋아요. -i(--image)는 첫 프롬프트에 오류 화면 캡처나 설계 그림을 붙이는 옵션이고, --search 는 실시간 웹 검색을 켜는 옵션이에요. 보안 문서에 따르면 기본 웹 검색은 오픈AI 가 관리하는 캐시 색인에서 결과를 가져오고, --search 를 켜면 실시간 페이지를 봐요. 다만 --yolo 나 다른 전체 권한 설정에서는 기본값이 처음부터 실시간 검색이라고 적혀 있어요. 같은 문서가 웹 결과는 믿을 수 없는 입력으로 다루라며, 프롬프트 주입으로 에이전트가 외부 지시를 따라갈 수 있다고 경고해요.

같은 Codex 를 터미널이 아닌 곳에서 쓰는 이야기는 따로 정리해 두었어요. 휴대폰 앱은 코덱스 모바일 출시 첫 주 정리에, 윈도우 앱을 조작하는 기능은 코덱스 컴퓨터 사용 기능의 첫 주 기록에 있어요.

버전이 매우 자주 바뀌어요

이 글이 버전 번호를 굳이 박아 두는 데는 이유가 있어요. 2026년 9월 23일에 GitHub 릴리스 목록과 npm 레지스트리를 조회한 값이에요.

정식 릴리스 14건 중 한 건은 파이썬 쪽 태그라서, CLI 만 세면 13건이고 그중 12건이 9월에 나왔어요. 9월 23일 하루에만 0.156.0 과 0.156.1 두 번이 나왔어요. 이 속도라면 이 글에 적은 옵션 이름이나 명령 개수가 몇 주 안에 달라질 수 있어요. 옵션이 안 먹으면 codex --version 으로 버전부터 보고, 그 버전의 --help 를 기준으로 삼는 편이 안전해요. 문서가 앞서가거나 뒤처지는 자리가 실제로 있었으니까요.

요금은 이 글에서 판정하지 않아요

Codex 요금 문서의 카드 문구만 옮겨 둘게요. CLI 가 이름으로 적힌 칸은 Plus 부터였어요. Plus 칸에는 웹, CLI, IDE 확장, iOS 에서 Codex 를 쓴다는 항목이 있고, Pro 칸은 Plus 보다 5배 또는 20배 높은 한도를 고르는 구조로 적혀 있어요. Free 와 Go 칸에는 데스크톱 앱에서 쓰는 모델 문구만 있었고, 그렇다고 CLI 가 막힌다는 문장이 카드에 있는 것도 아니었어요. API 키 칸은 CLI, SDK, IDE 확장에서 쓸 수 있지만 GitHub 코드 리뷰나 Slack 같은 클라우드 기능은 없다고 적어요.

플랜별 사용량 숫자는 이 글에서 다루지 않았어요. 한도를 여러 도구와 나란히 놓고 보려면 앞에서 소개한 비교 글을 보는 편이 맞아요.

이 글이 확인하지 않은 것

• 로그인 화면과 작업 결과는 직접 보지 않았어요. 로그인하지 않았고 프롬프트를 한 번도 실행하지 않았어요. 로그인 흐름은 인증 문서의 서술을 옮긴 것이에요.
• Windows 에서 작업이 끝까지 도는지는 모르겠어요. 도움말 출력까지만 확인했고, 설치 문서 표는 Windows 11 을 WSL2 경유로 적어요.
• 모드별로 실제로 몇 번 멈추는지는 세지 않았어요. 샌드박스와 승인 조합의 동작은 문서 서술이에요.
• 도움말과 문서의 차이가 언제 좁혀질지는 알 수 없어요. 버전이 며칠마다 바뀌어서, 이 글의 표는 0.156.1 기준이에요.

정리하면 이 순서로 시작하면 돼요

• 설치는 편한 길 하나를 고르세요. 독립 설치기, npm, Homebrew 중 무엇이든 되고, npm 과 독립 설치기는 같은 명령을 다시 실행하면 업데이트돼요.
• 프로젝트 폴더에서 codex 를 실행하고 챗GPT 로 로그인하세요. 서버처럼 브라우저가 없으면 기기 코드 로그인을 보안 설정에서 먼저 켜야 해요.
• 첫 작업 전에 Git 커밋을 하나 만드세요. 문서가 권하는 되돌릴 자리예요.
• 저장소 루트에 AGENTS.md 를 두세요. 폴더마다 한 파일, 가까운 쪽이 덮고, 합쳐서 기본 32KiB 까지라는 세 가지만 기억하면 돼요.
• 권한은 Ask for approval 로 시작하세요. Approve for me 는 경계를 넓히지 않고 검토자만 바꿔요.
• 옵션이 안 먹으면 버전과 도움말부터 보세요. 이 글을 쓴 날 기준 0.156.1 에서는 문서가 호환용으로 남겨 뒀다는 codex exec --full-auto 가 거부됐어요.

이 글의 모든 명령, 옵션 이름, 개수는 2026년 9월 23일에 Codex CLI 0.156.1 도움말을 출력하고 오픈AI 공식 문서, 공개 저장소, GitHub 와 npm 조회 결과를 직접 받아 확인한 값이에요. 버전이 바뀌면 달라질 수 있으니 중요한 설정을 바꾸기 전에는 설치한 버전의 --help 를 한 번 더 열어 보세요.