Codex CLI 치트 시트: 모든 명령어와 config.toml 키 (2026)
codex 는 대화형 세션을 열고, codex exec 는 CI용으로 헤드리스 실행돼요. 세션 안에서 / 를 입력하면 전체 슬래시 명령어 목록이 나오고, codex --help 나 ? 로 설치된 버전의 모든 명령어를 볼 수 있어요. 이 페이지는 훑어보기 좋은 레퍼런스예요. 최상위 명령어, 전역 플래그, 카테고리별 슬래시 명령어, 실제로 중요한 config.toml 키, MCP 설정, 샌드박스/승인 모드, 그리고 정말 (짧은) 키보드 단축키 목록까지 다뤄요.
- Codex CLI 는 거의 매달 새 버전을 내놓고 정확한 명령어 목록도 바뀔 수 있어요. 아래 내용은 모두 작성 시점의 공식 문서와 대조했지만, 정확한 플래그 이름에 의존하기 전에 본인의 설치 환경에서 codex --help, /, 또는 ? 를 실행해 보세요.
이 치트 시트가 다루는 범위
이것은 오직 Codex CLI, 즉 codex 로 실행하는 터미널 도구에 관한 내용이에요. ChatGPT 데스크톱 앱이나 VS Code/JetBrains IDE 확장은 다루지 않아요. 그것들은 서로 다른 단축키 세트를 갖고 있고, 온라인의 일부 페이지는 셋을 뒤섞어 놓아서 그런 「키보드 단축키」 섹션은 오해를 부르기 쉬워요. Codex 가 완전히 처음이라면 먼저 OpenAI Codex 란 무엇인가 부터 보세요.
이름이 서로 헷갈리니 분명히 짚고 넘어갈 구분이 하나 있어요. OpenAI Codex(이 CLI)는 AgentKit(agentkit.best, Codex 안에서 동작하는 유료 서드파티 애드온)이 아니고, OpenAI 자체의 AgentKit(별개 제품인 Agent Builder로, OpenAI 의 2026-06-03 지원 종료 공지에 따라 그 자체도 축소되는 중)도 아니에요. 이 페이지는 무료 CLI 에 관한 것이고, AgentKit 은 마지막에 딱 한 번 솔직하게 언급해요.
필요한 곳으로 바로 건너뛸 수 있게 묶어 놓았어요. 먼저 명령어와 플래그, 그다음 가장 큰 섹션(슬래시 명령어. 일상적인 제어의 대부분이 실제로 이걸로 이뤄지니까요), 이어서 config 키, MCP, 샌드박스/승인, 마지막으로 솔직한 단축키 목록이에요.
설치 & 로그인 - 빠른 명령어
Codex CLI 는 오픈소스(Rust)이고, macOS, Linux, Windows 어디서든 스크립트 하나로 설치돼요.
| 명령어 | 기능 |
|---|---|
curl -fsSL https://chatgpt.com/codex/install.sh | sh | CLI 를 설치해요 (mac/Linux. Windows 에서는 WSL/Git Bash 를 통해서도 동작해요). |
codex login | 브라우저에서 ChatGPT 계정으로 로그인해요. |
codex login --device-auth | 헤드리스 머신(SSH 환경, 컨테이너)용 디바이스 코드 로그인이에요. 이번 세션에서는 1차 자료 페이지와 별도로 재확인하지 못했어요. 정확한 플래그에 의존하기 전에 codex login --help 로 확인하세요. |
codex logout | 로그아웃하고 로컬 인증 토큰을 지워요. |
설치가 끝나면 codex --version 을 실행해 제대로 됐는지 확인하고, 그다음 codex 만 실행해 첫 대화형 세션에 들어가세요. 프록시/회사 네트워크 예외 상황을 포함한 모든 설치 경로의 자세한 안내는 Codex CLI 설치 방법 을 보세요.
최상위 CLI 명령어
codex 바로 뒤에 직접 입력하는 명령어예요.
| 명령어 | 기능 | 예시 |
|---|---|---|
codex | 현재 프로젝트에서 대화형 세션을 열어요. | codex |
codex exec | TUI 없이 프롬프트 하나를 헤드리스로 실행해요. 스크립트와 CI 용이에요. | codex exec "add a health-check route" |
codex resume | 이전 세션을 다시 열어요. | codex resume |
codex login | ChatGPT 계정으로 로그인해요. | codex login |
codex mcp | MCP 서버 연결을 관리해요. | codex mcp add docs -- npx -y mcp-server-docs |
codex cloud | Codex Cloud 샌드박스 작업을 열고 관리해요. | codex cloud |
codex apply | Codex Cloud 작업이 만든 diff 를 로컬 체크아웃에 적용해요. | codex apply <task-id> |
codex doctor | 설치/설정을 진단 점검해요. 서드파티 자료에 따르면 v0.131.0 무렵에 추가됐고 1차 문서는 아니에요. codex --help 로 본인 버전에 있는지 확인하세요. | codex doctor |
codex features enable <flag> | 기능 플래그가 걸린 기능(예: 목표 모드)을 켜요. | codex features enable goals |
전역 플래그 (대부분의 명령어에서 동작)
| 플래그 | 기능 |
|---|---|
-m, --model | 이번 실행에 사용할 모델을 덮어써요. |
-s, --sandbox | 샌드박스 모드를 설정해요 (아래 매트릭스 참고). |
-a, --ask-for-approval | 이번 실행의 승인 정책을 설정해요. |
-p, --profile | config.toml 에서 이름 붙은 프로필을 불러와요. |
-c, --config key=value | 파일을 편집하지 않고 설정 키 하나를 인라인으로 덮어써요. |
-i, --image | 프롬프트에 이미지를 첨부해요. |
--search | 이번 실행에 실시간 웹 검색 도구를 활성화해요. |
-C, --cd | 다른 작업 디렉터리를 대상으로 실행해요. |
--add-dir | 프로젝트 루트 밖의 추가 디렉터리에 읽기/쓰기 접근을 허용해요. |
--oss | 호스팅 모델 대신 로컬 오픈 웨이트 모델을 대상으로 실행해요. |
--local-provider | Codex 를 자체 호스팅/로컬 모델 프로바이더로 향하게 해요. |
codex exec 를 CI/CD 에서 쓰기
codex exec 는 파이프라인을 위한 헤드리스 진입점이에요. 전형적인 CI 호출은 다음과 같아요.
codex exec --json --sandbox workspace-write --ephemeral \
--skip-git-repo-check \
"Fix the failing test in tests/auth.spec.ts and summarize the change"| 플래그 | 기능 |
|---|---|
--json | TUI 출력 대신 구조화된 JSON 이벤트를 내보내요. |
-o, --output-last-message | 최종 메시지만 파일에 써요. 파이프라인 단계에서 가져오기 쉬워요. |
--output-schema | 최종 메시지를 지정한 JSON 스키마에 맞추도록 강제해요. |
--ephemeral | 실행 후 세션/기록을 남기지 않아요. |
--skip-git-repo-check | 작업 디렉터리가 git 저장소 안이 아니어도 실행해요. |
--ignore-rules | 이번 실행에서는 프로젝트의 일반 규칙/lint 검사를 건너뛰어요. |
위험한 플래그 - 격리된 CI 러너 전용:
--dangerously-bypass-approvals-and-sandbox(별칭--yolo)와--dangerously-bypass-hook-trust는 샌드박스와 승인 게이트를 완전히 없애요. 실제 자격 증명이나 프로덕션 접근 권한이 있는 머신에서는 절대 실행하지 마세요. 일회용으로 격리된 CI 컨테이너에서만 쓰세요.
슬래시 명령어 (카테고리별)
세션 안에서 / 를 입력하면 본인 버전의 실시간 목록이 나와요. 이 표는 자주 쓰는 것들을 묶은 거예요. 매일 가장 많이 쓰는 다섯 개는 /review, /goal, /permissions, /compact, /mcp 예요.
| 명령어 | 그룹 | 기능 |
|---|---|---|
/clear | 세션 & 컨텍스트 | 새 컨텍스트를 시작하고 세션은 유지해요. |
/compact | 세션 & 컨텍스트 | 컨텍스트를 수동으로 압축해 공간을 확보해요. |
/new | 세션 & 컨텍스트 | 완전히 새로운 세션을 시작해요. |
/resume | 세션 & 컨텍스트 | TUI 안에서 이전 세션을 다시 열어요. |
/rename | 세션 & 컨텍스트 | 현재 세션의 이름을 바꿔요. |
/archive | 세션 & 컨텍스트 | 현재 세션을 보관해요. |
/delete | 세션 & 컨텍스트 | 세션을 삭제해요. |
/diff | 세션 & 컨텍스트 | 현재 작업 diff 를 보여줘요. |
/copy | 세션 & 컨텍스트 | 마지막 응답을 클립보드에 복사해요. |
/status | 세션 & 컨텍스트 | 세션과 사용량 상태를 보여줘요. |
/model | 모델·권한 & 성격 | 활성 모델을 전환해요. |
/permissions | 모델·권한 & 성격 | 샌드박스/승인 정책을 실시간으로 보거나 편집해요. |
/personality | 모델·권한 & 성격 | 응답 톤/스타일을 바꿔요. |
/sandbox-add-read-dir | 모델·권한 & 성격 | 이번 세션에 추가 디렉터리 읽기 접근을 허용해요. |
/review | 리뷰 & 목표 | 코드 리뷰 프리셋을 실행해요 (diff, 미커밋, 특정 커밋, 또는 커스텀). |
/goal | 리뷰 & 목표 | 목표 모드를 시작해요. 길고 지속적인 실행 루프예요. |
/plan | 리뷰 & 목표 | Codex 가 실행을 시작하기 전에 계획을 세워요. |
/mcp | 확장 | 세션 안에서 MCP 서버 연결을 관리해요. |
/skills | 확장 | 설치된 skill 을 나열하고 관리해요. |
/hooks | 확장 | 설정된 hook 을 보여줘요. |
/apps | 확장 | 연결된 앱/통합을 관리해요. |
/plugins | 확장 | 플러그인 마켓플레이스 설치를 관리해요. 비교적 새롭고 서드파티에서 나온 구문이에요. 덜 안정적이라고 보고 실제 환경에서 확인하세요. |
/agent | 확장 | 범위가 한정된 하위 작업을 위해 subagent 를 파견해요. |
/import | 확장 | 파일이나 URL 에서 컨텍스트를 가져와요. |
/keymap | 인터페이스 & 유틸리티 | 키보드 단축키를 다시 매핑해요. |
/vim | 인터페이스 & 유틸리티 | 입력에 vim 스타일 키 바인딩을 켜고 꺼요. |
/theme | 인터페이스 & 유틸리티 | 색상 테마를 바꿔요. |
/ide | 인터페이스 & 유틸리티 | IDE 통합 명령어예요. |
/raw | 인터페이스 & 유틸리티 | 일반 파싱을 건너뛰고 원시 입력을 보내요. |
/experimental | 인터페이스 & 유틸리티 | 실험적/기능 플래그 동작을 켜고 꺼요 (목표 모드 포함). |
/debug-config | 인터페이스 & 유틸리티 | 우선순위가 적용된, 완전히 병합된 설정을 출력해요. |
/feedback | 인터페이스 & 유틸리티 | OpenAI 에 피드백을 보내요. |
/exit | 인터페이스 & 유틸리티 | Codex 를 종료해요. |
핵심 config.toml 키
Codex 는 기본적으로 ~/.codex/config.toml 에서 설정을 읽어요. 일상에서 가장 중요한 건 네 개의 키예요.
| 키 | 값 | 기능 |
|---|---|---|
model | 예: gpt-5.6-terra | 새 세션의 기본 모델 티어예요. |
sandbox_mode | read-only / workspace-write(기본값) / danger-full-access | 기본적으로 파일시스템/네트워크 접근이 어떻게 되는지 정해요. |
approval_policy | untrusted / on-request / never | Codex 가 행동하기 전에 멈추고 물어봐야 하는 시점이에요. |
project_doc_max_bytes | 정수, 기본값 32768 (32 KiB) | AGENTS.md 파일의 합산 크기 상한이에요. 넘는 부분은 조용히 버려져요. |
project_doc_fallback_filenames | 파일 이름 목록 | AGENTS.md 가 없을 때 Codex 가 읽는 대체 파일이에요. |
web_search | true/false | 실시간 웹 검색 도구를 허용해요. |
model_reasoning_effort | low/medium/high | 요청마다 들이는 추론 깊이예요. |
[features] | 플래그 테이블 | 기능 플래그 블록이에요. 예: 목표 모드에는 goals = true. |
우선순위: CLI 플래그 > 프로젝트 설정 > 프로필 > 사용자 설정. -c key=value 플래그가 항상 이겨요. 프로젝트 수준 config.toml 은 개인 설정을 이겨요. AGENTS.md 의 전체 병합 규칙(그리고 32 KiB 상한의 자세한 내용)은 Codex 용 AGENTS.md 를 보세요.
MCP - 명령어 하나로 서버 연결하기
CLI 에서 서버를 추가해요.
codex mcp add docs --env API_KEY=$DOCS_KEY -- npx -y mcp-server-docs그러면 대응하는 블록이 ~/.codex/config.toml 에 기록돼요.
[mcp_servers.docs]
command = "npx"
args = ["-y", "mcp-server-docs"]
env = { API_KEY = "..." }Codex 는 MCP 클라이언트일 뿐이에요. 서버에 연결하지만 서버를 노출하지는 않아요. 한번 추가하면 그 서버의 도구가 다음 세션에서 자동으로 나타나요. 작업 도중에 의존하기 전에 /mcp 로 연결을 확인하세요. 전체 설정 가이드는 Codex 에서 첫 MCP 서버 연결하기 를 보세요.
샌드박스 & 승인 - 빠른 매트릭스
| sandbox_mode ↓ / approval_policy → | untrusted | on-request | never |
|---|---|---|---|
| read-only | 거의 모든 것 전에 물어봐요. | 위험한 읽기에만 물어봐요. | 묻지 않아요. 읽기만 가능해요. |
| workspace-write(기본값) | 샌드박스 밖으로 쓰기 전에 물어봐요. | 워크스페이스 이상이 필요할 때만 물어봐요. | 워크스페이스 안에서는 확인 없이 자유롭게 써요. |
| danger-full-access | 파괴적/시스템 수준 작업 전에 물어봐요. | 드물게, 주로 되돌릴 수 없는 작업에만 물어봐요. | 전체 접근, 확인 전혀 없음. 정말 조심해서 쓰세요. |
기본 설치 동작은 workspace-write + on-request, 즉 위 표의 가운데 행·가운데 열이에요. 대부분은 나머지 여덟 조합을 건드릴 일이 없지만, Codex 가 예상 못 한 권한을 물어올 때를 대비해 그것들이 존재한다는 걸 알아 두면 도움이 돼요. 각 모드가 실제로 무엇을 허용하는지는 Codex 샌드박스와 승인 모드 설명 을 보세요.
키보드 단축키 (짧고 솔직한 목록)
Codex CLI 는 핫키가 아니라 슬래시 명령어에 기대고 있어서, CLI 전용의 진짜 단축키 목록은 짧아요. 온라인 어떤 페이지가 열두 개가 넘는 「Codex 키보드 단축키」 를 나열한다면, 십중팔구 데스크톱 앱이나 IDE 확장을 섞어 놓은 거예요.
| 키 | 동작 |
|---|---|
Ctrl+C | 현재 턴을 취소해요. |
Ctrl+D | Codex 를 종료해요. |
Ctrl+J | 입력 상자에 줄바꿈을 넣어요. |
Ctrl+L | 화면을 지워요. |
Ctrl+R | 기록 역방향 검색이에요. 버전에 따라 달라요 (서드파티 자료 기준 ~v0.121.0 이상). 본인 설치 환경에서 확인하세요. |
Esc | 현재 턴을 중단해요. |
Esc Esc | 마지막 동작을 되돌려요. |
Tab | Codex 가 아직 작업 중일 때 후속 메시지를 대기열에 넣어요. |
Enter | 메시지를 보내요. |
다른 바인딩을 원하세요? /keymap 을 실행해 다시 매핑하세요.
AGENTS.md & Skills - 더 깊이 보려면
Codex 는 CLAUDE.md 가 아니라 AGENTS.md 에서 프로젝트 지시를 읽어요. 전체 병합/재정의 규칙은 Codex 용 AGENTS.md 를 보세요. 재사용 가능하고 서로 호환되는 워크플로는 SKILL.md 파일에 있어요. Codex Skills 설명 을 보세요.
기성 워크플로를 위에 얹기
Codex CLI 자체는 ChatGPT 요금제 안에서 무료예요. 직접 워크플로를 짜는 게 내키지 않는다면, AgentKit 이 ak kit init engineer --target codex --global 을, 그다음 세션 안에서 $ak:cook 을 실행하는 식으로 기성 skill 과 워크플로를 위에 얹어 줘요. 유료 애드온이고 Codex 자체의 일부는 아니에요. AgentKit 보기 →
빠른 답변
내 정확한 버전의 모든 명령어를 보려면?
터미널에서 codex --help 를 실행하거나, 세션 안에서 / 를 입력해 실시간 슬래시 명령어 목록을 보세요.
실제로 로드된 설정을 확인하려면?
세션 안에서 /debug-config 를 실행하세요. 우선순위가 적용된 뒤 완전히 병합된 설정을 출력해요.
Codex 는 설정을 어디에 저장하나요?
CODEX_HOME 안, 기본값은 ~/.codex 예요. config.toml, auth.json, history.jsonl 을 담고 있어요. 다른 디렉터리를 쓰려면 환경 변수를 다른 곳으로 향하게 하세요.
CLI 를 업데이트하려면?
이번 세션에서는 자체 업데이트 하위 명령어를 개별적으로 확인하지 못했어요. 가장 안전한 방법은 설치 스크립트(curl -fsSL https://chatgpt.com/codex/install.sh | sh)를 다시 실행한 뒤 codex --version 을 확인하는 거예요.
다른 글의 명령어가 왜 여기에 안 보이나요?
이 목록은 작성 시점에 공식 문서에서 확인하고 대조한 내용을 반영해요. Codex 는 거의 매달 출시되니, 새로 추가된 명령어나 이름이 바뀐 플래그는 이 페이지를 포함한 어떤 정적 페이지보다 뒤처질 수 있어요. codex --help 와 본인 설치 환경의 / 가 항상 진짜 기준이에요.
결론
설치하고, / 로 명령어를 확인하고, ? 나 codex --help 로 단축키를 확인한 뒤 이 페이지를 북마크하세요. 목록이 자주 바뀌니 업데이트할 때마다 다시 확인할 가치가 있어요. Codex 가 아예 처음인가요? 먼저 OpenAI Codex 란 무엇인가 부터 보고, 그다음 CLI 를 설치 하세요.