Codex CLI 입문(8) : 슬래시 명령어 정리 - Codex 슬래시 명령어 사용방법

안녕하세요! 갓대희 입니다.

codex CLI 안에서 /를 누르면 명령이 한꺼번에 쏟아져서 어떤 것부터 익혀야 할지 망설이게 된다.

이번에는 Codex CLI의 슬래시 명령어 들을 정리 해보려 한다.

앞부분은 초보자용 사전, 뒷부분은 기존 글에서 정리해 둔 config.toml 키 사전과 CLI 플래그 사전을 부록으로 작성해보려 한다.

이 글은 2026년 5월 기준 codex-cli 0.130.0 공식 문서(developers.openai.com/codex/cli/slash-commands)와 릴리즈 노트를 바탕으로 작성되었다. 슬래시 명령 목록은 릴리즈마다 추가·제거가 있으므로, 자신의 설치 버전에서 / 입력으로 popup을 띄워 직접 확인하기를 권장한다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills Part 6: 자동화 Part 7: 마이그레이션 (현재 글) Part 8: 슬래시 명령어 정리(예정)

이 편에서 처음 나오는 용어 미리 보기

• 슬래시 명령(slash command): Codex TUI에서 /로 시작하는 인터랙티브 명령. 채팅 메시지가 아니라 TUI 동작을 직접 제어한다.
• popup: /를 입력하면 composer 위에 뜨는 명령 자동완성 창. 화살표로 선택, Tab으로 큐잉, Enter로 즉시 실행한다.
• 큐잉(queueing): 현재 턴이 끝나기 전에 다음 명령을 미리 등록해 두는 동작. Codex가 응답 중에 /clear 같은 명령을 미리 예약할 때 쓴다.
• feature 플래그(게이트): 일부 명령은 [features] 테이블의 특정 키가 켜져 있어야만 동작한다. 사용 전에 게이트 조건을 함께 확인한다.
• [공식 문서 미등재]: 소스 코드나 릴리즈 노트에서만 확인되고 공식 slash-commands 페이지에 올라오지 않은 명령. 동작·인터페이스가 버전마다 다를 수 있다.

목차

1. 슬래시 명령 기본기 — popup·큐잉·별칭
2. 세션 관리 (8개): /new, /resume, /fork, /side, /clear, /compact, /exit, /logout
3. 모델·승인·권한 (5개): /model, /fast, /permissions, /sandbox-add-read-dir, /experimental
4. 도구·맥락 (5개): /mention, /mcp, /plugins, /apps, /agent
5. 코드 작업 (4개): /init, /diff, /review, /plan
6. 진단·디버그 (4개): /status, /debug-config, /feedback, /copy
7. UI·UX·테마 (4개): /theme, /title, /statusline, /keymap
8. 게이트·조건부 명령 (4개): /goal, /personality, /ps, /stop
9. 공식 미등재 명령 (8개): /rename, /raw, /skills, /approve, /realtime, /settings, /collab, /setup-default-sandbox
10. 부록 A — config.toml 키 사전
11. 부록 B — CLI 플래그·codex exec 사전
12. 마무리 — 안전 기본값 + 캡쳐 체크리스트

 

1. 슬래시 명령 기본기

명령 목록을 보기 전에, TUI에서 어떻게 명령을 불러서 실행하는지 흐름부터 잡아두자. 크게 세 단계다.

 

1.1 popup 띄우고 명령 고르기

composer(메시지 입력란)에서 /를 입력하면 명령 popup이 열린다. 키워드 일부를 더 치면 목록이 좁혀지고, 화살표로 골라 Enter로 즉시 실행하거나 Tab으로 예약할 수 있다.

# composer에서
    /mod      ← '/'로 popup, 'mod' 입력 시 /model이 위로 올라옴
    ↑/↓       ← 화살표로 항목 이동
    Enter     ← 즉시 실행

활용 주제 전환 시 이전 맥락 끊고 새로 시작.

 

/resume — 이전 세션 이어 받기

picker가 열려 최근 세션 목록을 보여준다. 어제 작업하다 만 세션을 그대로 이어가고 싶을 때 사용한다.

CLI에서 codex resume --last로 한 단계 건너뛰는 방법도 있다.

/resume

활용 중단된 작업 이어서 컨텍스트 복구.

ex)

 

/fork — 현재 스레드 분기

현재 대화 기록이 정상적으로 저장된 상태라면, 현재 스레드를 새 분기로 복제한다. 본 흐름을 망가뜨리지 않고 "이 부분을 다르게 가면 어떻게 될까?"를 시험해볼 때 유용하다. 다만 앱 서버가 대상 스레드의 rollout 기록을 찾지 못하면 no rollout found for thread id 같은 오류가 날 수 있다. 이 경우 명령 부재가 아니라 로컬 세션 인덱스/앱 서버 상태 문제로 보는 편이 맞다.

/fork

활용 기존 맥락을 보존한 채 분기 실험. 실패하면 터미널에서 codex fork --last 또는 codex fork <SESSION_ID>로 확인.

 

/side — 보조 대화 열기

메인 스레드를 그대로 둔 채 별도의 보조 창을 띄운다. "이 함수 의미만 잠깐 물어보고 싶다" 같은 곁가지 질문을 메인 흐름에 흘리지 않는 용도다. ESC로 닫으면 메인 스레드로 돌아간다.

/side

활용 메인 흐름 건드리지 않고 버그 원인 가설 검증(로그 추가, 임시 패치)에 유용. 본선 컨텍스트 오염 방지 목적.

ex) 진행 중 /side

  - 보조 대화창 열림

 - esc를 통해 해당 보조 대화창을 종료 하면 기존 대화창으로 복귀 된다.

 

/clear — 화면 초기화

같은 스레드를 유지한 채 터미널 화면과 대화 컨텍스트를 정리한다. 화면이 너무 길어져 가독성이 떨어지거나 컨텍스트 누적으로 모델이 산만해질 때 사용한다. 새 스레드를 통째로 여는 /new와는 동작 범위가 다르다.

/clear

활용 컨텍스트 누적으로 판단 흔들릴 때 초기화. 초기화 전 TODO·결정사항 3줄 요약을 남기는 습관 권장.

 

/compact — 대화 축약

긴 대화를 요약해서 압축한다. AI 모델은 한 번에 기억할 수 있는 대화 길이(컨텍스트 윈도우)에 한계가 있는데, 대화가 너무 길어지면 응답이 느려지거나 앞 내용을 놓치기 시작한다. 그럴 때 이 명령으로 핵심만 남기면 된다. 압축된 요약은 새 메시지 형태로 들어가고, 원본 대화는 백그라운드에 보존된다.

/compact

활용 긴 대화 토큰 줄여 핵심만 남길 때.

ex)

 

/exit · /quit — 세션 종료

두 명령은 완전히 동일하다(공식 docs에서 alias로 명시). 작업을 마치고 TUI를 닫을 때 쓴다. 키보드 단축키 Ctrl+C와 달리 정상 종료 경로를 타므로 세션 메타데이터가 깔끔하게 저장된다.

/exit
    # 또는
    /quit

활용 현재 세션 작업 마감하고 종료. 종료 전 /diff·미커밋 여부 확인 후 실행("끝냈다" 착각 방지).

 

/logout — 로그아웃

저장된 인증 자격을 모두 제거한다. 다른 계정으로 전환하거나 공용 노트북에서 흔적을 지워야 할 때 사용한다. 재로그인은 codex login으로 다시 시작한다.

/logout

활용 계정 전환·보안 정리 위해 인증 해제.

 

3. 모델·승인·권한 (5개)

Codex가 어느 수준까지 자율로 움직일지를 제어하는 명령들이다.

처음엔 기본값이 낯설 수 있는데, 각 명령이 뭘 하는지 한 번만 파악해두면 의도치 않은 동작을 방지하는 데 도움이 된다.

 

/model — 모델 선택

사용할 AI 모델을 picker로 고른다. 가벼운 질문은 작은 모델로, 깊은 분석이 필요할 땐 큰 모델로 그때그때 전환할 수 있다. 버전에 따라 같은 화면에서 추론 강도(reasoning effort, 얼마나 깊이 생각할지)까지 함께 조정할 수 있다.

/model

활용 작업 난도에 맞춰 모델 성향 교체.

ex)

 

/fast — 빠른 응답 모드 토글

빠른 응답을 우선하는 모드를 켜고 끈다. 코드 탐색이나 간단한 질문처럼 답의 정밀도보다 빠른 피드백이 더 중요한 상황에서 유용하다. 복잡한 분석이나 코드 수정처럼 깊은 추론이 필요한 작업에서는 다시 끄는 것을 권장한다.

/fast

활용 아이디어 발산·로그 훑기 초반 탐색에 좋음. 최종 수정안·릴리즈 판단 전에는 해제 권장.

 

/permissions — 승인 정책·샌드박스 보기/변경

현재 승인 정책(approval policy)과 샌드박스 수준을 한 화면에서 확인하고 바꾼다. 위험한 작업 전에 가장 먼저 들여다봐야 할 명령이다. 공식 docs에서 /approvals가 popup에서 사라졌다고 명시했으므로 신규 사용자는 이쪽을 외운다.

/permissions

활용 실행 권한 경계 먼저 확인.

ex)

 

/sandbox-add-read-dir — 읽기 가능 경로 추가 (Windows)

공식 docs에서 Windows 전용이라고 명시된 명령이다. 워크스페이스 바깥의 디렉터리를 한시적으로 읽기 허용 목록에 추가한다. macOS/Linux 사용자는 동일한 효과를 --add-dir CLI 플래그(부록 B)로 처리한다.

/sandbox-add-read-dir

활용 참조 폴더 읽기 범위 확장 필요.

 

/experimental — 실험 기능 토글 메뉴

메모리·목표·터미널 리플로우 같은 실험 기능을 그 자리에서 켜고 끄는 토글 메뉴를 연다. config.toml을 직접 손대지 않고 즉시 반영된다. 토글 가능한 항목 표는 섹션 8에서 자세히 다룬다.

/experimental

활용 개인 브랜치에서 A/B 테스트 후 채택 판단. 팀 표준 브랜치에서는 비권장.

ex) Goals 같은 기능은 현재 아직 실험적 단계이다.

 

4. 도구·맥락 (5개)

에이전트가 쓸 수 있는 도구와 맥락을 관리하는 명령들이다. Codex가 갑자기 모르는 답을 내거나 도구가 안 보일 때 가장 먼저 들여다본다.

 

/mention — 컨텍스트 참조 삽입

파일·앱·플러그인 등 특정 컨텍스트 항목을 메시지에 정확히 박는다. @ 자동완성과 유사하지만, popup 기반이라 모르는 이름을 검색해서 고를 수 있어 초보자에게 더 친화적이다.

/mention

활용 특정 리소스·앱 컨텍스트를 정확히 지목.

 

/mcp — MCP 서버 상태 보기

연결된 MCP(Model Context Protocol) 서버 목록과 각 서버에서 노출되는 도구 정보를 본다. 도구가 작동 안 할 때 가장 먼저 의심해야 하는 지점이 MCP 연결 상태다.

/mcp

활용 도구 서버 연결 상태·기능 범위 확인. 인증 만료·스키마 불일치·권한 부족을 먼저 분리 진단.

ex)

 

/plugins — 플러그인 마켓·설치 관리

설치된 플러그인과 마켓플레이스에서 찾을 수 있는 플러그인을 탐색한다.

v0.128.0에서 마켓 설치 워크플로가 정식 추가됐다(v0.128.0 릴리즈 노트).

/plugins

활용 플러그인 가용성·작업 적합성 먼저 판단.

ex)

 

/apps — 앱·커넥터 탐색

외부 앱·커넥터를 프롬프트에 끌어다 쓰는 워크플로다. 채팅 결과를 바로 출력하는 명령이 아니라 전체 화면 앱 선택기를 열고, 앱을 고르면 composer에 $app-slug 형태로 삽입한다. 현재 버전에서는 apps 기능이 기본 활성화된 환경도 있으므로, 아무 출력이 없어 보이면 Enter로 선택기가 열리는지 먼저 확인한다.

/apps

활용 외부 서비스 연동 작업 흐름 점검. 앱을 선택한 뒤 프롬프트에 삽입된 mention과 연결 계정이 올바른지 확인.

ex)

 

/agent — 에이전트 스레드 선택

이미 생성된 메인 스레드와 서브에이전트 스레드 사이를 전환하거나 관찰하는 명령이다. 새 서브에이전트를 직접 호출하는 명령은 아니며, 서브에이전트가 생성된 뒤 해당 작업 흐름을 확인하거나 이어갈 때 사용한다.
현재 서브에이전트가 없으면 Main [default]만 표시될 수 있다.

/agent

활용 병렬 조사·구현 중 어느 에이전트가 작업 중인지 확인하고, 필요한 스레드로 전환할 때 사용.

ex)

 

5. 코드 작업 (4개)

코드 파일을 실제로 읽고 수정하는 명령들이다. 직접 코드에 손을 대는 만큼, 실행 전에 섹션 12의 안전 기본값을 한 번 확인해두는 것이 좋다.

 

/init — AGENTS.md 초기화

저장소 루트에 AGENTS.md를 만들거나 보강한다. Codex가 매 세션 자동으로 읽는 파일이라 프로젝트 규칙을 한 번만 적어 두면 다음부터 반복 설명할 필요가 없다. Part 5에서 AGENTS.md 작성법을 다룬다.

/init

활용 저장소 규칙·환경 맥락을 시작점에 주입.

 

/diff — 변경 사항 미리 보기

현재 워킹 트리의 변경 내역을 시각화해서 보여준다. Codex가 방금 만든 변경이 의도와 일치하는지 검증할 때 가장 자주 누르게 되는 명령이다. 큰 변경은 화살표·페이지 키로 스크롤한다.

/diff

활용 수정 전후 변경 의도 빠르게 검증.

 

/review — 코드 리뷰 모드

현재 변경 또는 지정한 베이스 브랜치/커밋을 대상으로 코드 리뷰 흐름을 시작한다. 머지 직전 회귀·품질 리스크를 한 번 더 훑을 때 쓴다. CLI에서 codex review 서브커맨드로도 진입 가능하다.

/review

활용 병합 전 회귀·품질 리스크 집중 점검. 보안·성능·회귀·테스트 누락 등 관점을 명시하면 효과 상승.

ex) 1. Review against a base branch  (PR Style)

 - 소스리뷰 base branch를 선택 하는 화면

 

ex) Review a commit

 - 특정 커밋에 대한 리뷰

 

/plan — 계획 모드

바로 코드를 고치는 대신 단계별 실행 계획을 먼저 짠다. 복잡한 변경에서 충돌·범위를 미리 식별할 수 있어 안전하다. 계획에 동의해야 다음 단계로 넘어간다.

/plan

활용 구현 전 단계·리스크를 구조화.

ex) shift + tab 으로 모드를 변경 가능하며 계획을 먼저 세우게 된다. (너무 간단한 내용은 바로 수행하기도 한다.)

 - 계획을 세워주며

 - 해당 계획대로 수행할지, 쌓여있는 context를 비우고 수행할지, 플랜모드를 통해 계속 계획모드를 개선할지 등 선택 가능하다.

 

6. 진단·디버그 (4개)

"왜 안 되지?"가 들 때 가장 먼저 누르는 명령들이다. 보통 이 카테고리에서 답이 거의 다 나온다.

 

/status — 현재 세션 상태 한눈에 보기

모델, 승인 정책, 샌드박스, 연결된 MCP 수, 토큰 사용량 같은 핵심 상태를 한 화면에 정리한다. 다른 사람과 환경을 비교하거나 이슈 리포트 쓸 때 첫 줄에 붙이기 좋은 자료다.

/status

활용 현재 모드·제약·연결 상태 빠르게 확인.

 

/debug-config — 설정 레이어 진단

전역·프로젝트·CLI 플래그가 어떻게 병합되어 현재 설정이 만들어졌는지 보여준다. "내 config.toml이 제대로 읽히고 있나?" 의심이 들면 가장 먼저 누른다. feature 플래그가 안 먹는 문제는 거의 다 여기서 답이 나온다.

/debug-config

활용 설정 파일·프로필·환경변수 우선순위 충돌 확인. 오작동 원인 분리 진단 첫 번째 수단.

 

/feedback — 로그와 함께 피드백 보내기

현재 세션 로그를 첨부해 Codex 팀에 의견·버그 리포트를 전송한다. 재현 단계를 직접 정리하지 않아도 로그가 자동 동봉되므로 작은 이상도 가볍게 보낼 수 있다.

/feedback

활용 사용성 불편·버그 체감 즉시 전달. 재현 단계(명령→기대결과→실제결과)를 포함해야 처리 속도 빠름.

 

/copy — 마지막 출력 클립보드 복사

방금 받은 마지막 응답을 클립보드로 옮긴다. v0.129.0에서 tmux passthrough 없이도 동작하도록 버그가 수정됐다(v0.129.0 릴리즈 노트). 결과를 다른 문서로 옮기기 직전에 가장 가볍게 쓰는 명령이다.

/copy

활용 PR 템플릿·위키·이슈 본문으로 이동할 때 유용. 코드블록·링크 형식 깨짐 여부 붙여넣기 후 점검.

 

7. UI·UX·테마 (4개)

TUI의 외관과 입력 환경을 손에 맞게 다듬는 명령들이다. 한 번 정한 뒤에는 잘 안 건드리지만, 처음에 맞춰 두면 장시간 작업 피로가 크게 줄어든다.

 

/theme — 구문 강조 테마 선택

코드 블록의 구문 강조 테마를 picker로 고른다. 터미널 배경이 어두운지 밝은지에 따라 가독성이 크게 달라지므로 OS 다크모드 전환 시 같이 바꾸는 것이 자연스럽다.

/theme

활용 장시간 작업 피로 줄이려 UI 대비 조정.

 

/title — 터미널 창 제목 설정

터미널 창 또는 탭 제목을 설정한다. v0.128.0에서 활성 턴 중에도 편집할 수 있게 개선됐다. 여러 프로젝트 세션을 동시에 열어 둘 때 창 구분에 가장 유용하다.

/title

활용 세션 목적이 드러나게 작업 제목 정리. "레포-브랜치-목표" 패턴(예: api-fix/1234-auth-timeout)으로 통일하면 검색·회고에 유리.

 

/statusline — 상태 표시줄 구성 (v0.128.0~)

TUI 하단 상태 표시줄에 표시할 항목을 대화형으로 고른다. v0.129.0에서 테마 색상 추적과 PR 요약 세그먼트가 추가됐다. 브랜치명·작업 상태가 늘 눈에 띄게 둘 때 컨텍스트 상실이 줄어든다.

/statusline

활용 상태바 정보 밀도·표시 항목 튜닝. 승인 정책·샌드박스·모델명을 우선 노출하도록 설정하면 실수 예방.

 

/keymap — 단축키 재매핑 (v0.128.0~)

TUI 키보드 단축키를 대화형으로 다시 잡는다. [tui.keymap.*] config 키와 동기화되며, TUI에서 즉시 변경하거나 config.toml에 영구 저장할 수 있다(부록 A 참고).

/keymap

활용 단축키 동작이 손에 안 맞을 때 조정. IDE 공통 단축키와 충돌 최소화 기준으로 설정 권장.

 

8. 게이트·조건부 명령 (4개)

이 명령들은 특정 기능 스위치(feature 플래그)가 켜져 있어야만 popup에 표시된다. "왜 내 화면엔 이 명령이 없지?"라는 의문이 든다면, 명령이 없는 게 아니라 게이트 조건이 닫혀 있는 것이다. 각 명령 옆에 어떤 조건이 필요한지 함께 표기해뒀다.

 

/goal — 세션 목표 설정 [게이트: features.goals = true]

긴 작업의 목표를 명시적으로 박아 두면 Codex가 응답마다 목표 정합성을 따져준다. /experimental에서 켜거나 config.toml에 직접 적는다. 설정·일시정지·재개·초기화를 모두 지원한다.

/goal "feature X 구현 끝내고 회귀 없도록 머지"

활용 장기 작업 목표·진행 기준 명확히 고정.

ex) 현재 정식 기능은 아닌고 실험적 기능이며 하기 글에 자세하게 리뷰해 두었다.

Codex CLI /goal 사용방법 : 목표를 기억하고 스스로 이어가는 자율 루프 - /goal과 Ralph Loop 비교

 

/personality — 응답 톤 선택 [모델 의존]

응답 톤을 friendly·pragmatic·none 중에서 고른다.

config.toml 최상위 personality 키와 연동된다.

사용 중인 모델이 personality를 지원하지 않으면 popup에서 숨겨질 수 있다.

/personality

활용 답변 톤을 팀 규칙에 맞춰 고정. 리뷰 기준(근거 중심, 라인 인용 필수)도 함께 고정하면 실무 일관성 향상.

ex) 

 

/ps — 백그라운드 터미널 목록 [게이트: features.unified_exec = true]

에이전트가 띄워 둔 백그라운드 셸 프로세스를 보여준다. 빌드·서버처럼 길게 도는 작업이 어떤 상태인지 한눈에 본다. unified_exec 플래그가 켜져 있어야 활성화된다.

/ps

활용 백그라운드 에이전트 상태 추적.

ex)

 

/stop — 백그라운드 터미널 중지

백그라운드에서 돌고 있는 터미널을 일괄 중지한다. 빌드가 폭주하거나 무한 루프에 빠진 프로세스를 한 번에 정리할 때 쓴다. /ps와 마찬가지로 features.unified_exec이 켜진 환경에서 의미를 갖는다.

/stop

활용 비용 급증·잘못된 대량 수정 조짐 시 즉시 중단하는 안전 스위치. 망설이지 말고 먼저 멈출 것.

 

9. 공식 미등재 명령 (8개)

⚠️ 공식 문서 미등재 항목

이 섹션의 명령들은 소스 코드(codex-rs/tui/src/slash_command.rs)나 릴리즈 노트에서 확인됐으나 공식 slash-commands 페이지에는 등재되어 있지 않다.
동작과 인터페이스는 버전마다 달라질 수 있으므로 자신의 설치 버전에서 /debug-config로 먼저 확인하기를 권장한다.

 

/rename — 스레드 이름 변경 [공식 문서 미등재]

현재 TUI 스레드의 이름을 변경한다. 여러 스레드를 동시에 운영할 때 각 스레드를 프로젝트명이나 작업 목적에 맞춰 구분하는 데 유용하다. 소스 코드 enum에서만 확인됐다.

/rename

활용 세션 이름을 이력 검색 친화적으로 바꿀 때.

 

/raw — 원시 스크롤백 토글 [공식 문서 미등재] (v0.129.0~)

스크롤백 렌더링을 원시(raw) 텍스트와 서식 적용 사이에서 토글한다. v0.129.0 릴리즈 노트에서 확인됐다. ANSI 코드가 섞여 출력이 깨질 때 한 번 눌러보면 원인을 가린다.

/raw

활용 로그·JSON·에러 원문 전달 시 유용. 민감 정보 마스킹 후 전송하는 원칙 준수.

 

/skills — 설치된 스킬 보기 [공식 문서 미등재]

설치된 스킬 목록을 TUI에서 탐색한다. Part 6에서 스킬 config 설정을 다루었지만 슬래시 명령 자체는 공식 docs에 없다. 스킬이 제대로 로드됐는지 빠르게 확인할 때 시도해본다.

/skills

활용 사용 가능 스킬 목록 확인 후 전략 짤 때.

 

/approve — 자동 리뷰 승인 [공식 문서 미등재] (v0.129.0~)

v0.129.0에서 구 /autoreview가 이 이름으로 바뀌었고 동시에 /approvals가 popup에서 빠졌다. 자동 리뷰 재시도 흐름을 명시 승인할 때 사용한다.

/approve

활용 보안 경계 넘는 실행을 명시 승인. 명령 목적·영향 파일·롤백 가능성을 체크한 뒤 승인.

 

/realtime — 실시간 음성 모드 [공식 문서 미등재]

오디오 디바이스와 실시간 음성 입력 관련 실험 기능이다. 하드웨어 의존이 커서 이 글에서는 핸즈온을 다루지 않는다. 자신의 환경에서 feature 플래그를 켠 뒤 직접 확인하기를 권장한다.

/realtime

활용 디버깅 대화형 탐색에 적합. 장문 생성보다 빠른 피드백 루프가 필요한 탐색 초반에 유용.

 

/settings — 기본 동작 일괄 조정 [공식 문서 미등재]

선호 옵션을 한 화면에서 묶어 조정하는 진입점이다. 소스 코드에서만 확인되고 공식 docs에는 없다. 동작 범위가 버전에 따라 다를 수 있으므로 적용 후 /debug-config로 결과를 확인한다.

/settings

활용 팀 공통 프로필(모델·승인정책·출력 스타일)을 템플릿화해 신규 멤버 온보딩에 활용 가능.

 

/collab — 협업 모드 [공식 문서 미등재]

collaboration_modes_enabled 플래그로 게이트된 명령이다. UX 문서가 없어 동작 세부는 직접 확인이 필요하다. 새 키 후보는 multi_agent로 옮겨질 가능성이 있다(부록 A 마이그레이션 표 참고).

/collab

활용 협업 세션에서 역할 분담·동기화. 파일 오너십을 먼저 나눠 역할 충돌을 방지할 것.

 

/setup-default-sandbox — 기본 샌드박스 상승 [공식 문서 미등재]

⚠️ 보안 경고

이 명령은 allow_elevate_sandbox 플래그로 게이트되어 있으며, 실행하면 기본 샌드박스 수준이 상승한다. Codex가 더 넓은 파일시스템·네트워크 범위에 접근할 수 있게 된다는 의미다. 소스 코드에서만 확인됐고 공식 docs 미등재다. 대부분의 개발자에게 필요한 상황은 드물다. 꼭 필요한 경우가 아니라면 기본 sandbox_mode를 유지하는 것을 권장한다.

/setup-default-sandbox

활용 반복 작업용 기본 샌드박스 정책 고정.

 

10. 부록 A — config.toml 키 사전

슬래시 명령으로 잠깐 토글한 항목을 영구 적용할 때, 또는 팀 전체가 같은 기본값을 공유할 때 config.toml을 편집한다. 공식 config-basic 문서에 등재된 키 중 Part 1~9에서 다루지 않았거나 자주 묻는 것들을 모았다.

 

A.1 [tui.keymap.*] — TUI 키맵 재정의 (v0.128.0~)

[tui.keymap.global]은 전체 TUI 단축키, [tui.keymap.composer]는 composer 특화 단축키를 재정의한다. /keymap으로 임시 변경, config.toml로 영구 저장한다.

# config.toml — TUI 키맵 재정의 (v0.128.0~)
    [tui.keymap.global]
    open_transcript = "ctrl-t"
    
    [tui.keymap.composer]
    submit = ["enter", "ctrl-m"]

한글로 이해하기
submit = ["enter", "ctrl-m"]은 Enter와 Ctrl+M 어느 쪽을 눌러도 메시지가 전송된다는 뜻이다. 배열로 여러 키를 동시에 바인딩한다.

 

A.2 personality · log_dir · animations · web_search

# config.toml — 자주 묻는 최상위 키
    personality = "pragmatic"       # friendly | pragmatic | none
    log_dir = "/tmp/codex-logs"     # 로그 위치 재정의 (CI·디버깅)
    animations = false              # TUI 애니메이션 비활성화 (v0.129.0~)
    web_search = "cached"           # cached | live | disabled

animations = false는 v0.129.0에서 추가된 접근성 옵션이다. 스크린 리더 사용이나 저사양 터미널에서 유용하다. web_search는 기존 두 개의 [features] 하위 키(web_search_request, web_search_cached)를 단일 최상위 키로 통합한 것이다.

 

A.3 [features] 테이블

# config.toml — [features] 테이블 자주 쓰는 키
    [features]
    undo            = true    # 턴별 git 스냅샷
    memories        = true    # 메모리 저장소 (v0.129.0~ Memories MCP v1)
    shell_snapshot  = true    # 셸 상태 스냅샷
    unified_exec    = true    # 백그라운드 터미널 — /ps, /stop 활성화
    apps            = true    # 앱·커넥터. 기본 ON인 버전도 있으므로 필요 시에만 명시
    goals           = true    # /goal 활성화
    terminal_resize_reflow = true   # 터미널 크기 변경 시 스크롤백 재구성 (기본 ON)
    prevent_idle_sleep     = false  # 장시간 작업 절전 방지 (macOS/Windows)
    
    # ⚠️ EXPERIMENTAL — 공유 저장소에서 활성화 금지
    codex_git_commit = false  # Codex가 git 커밋 자동 작성 (v0.129.0~)

⚠️ codex_git_commit 활성화 전 확인

Codex가 직접 git 커밋을 작성하는 실험 기능이다. 공유 저장소에서는 활성화하지 않는 것을 강력히 권장한다. 자동 생성된 커밋이 의도하지 않은 변경을 남길 수 있다. 개인 저장소에서 켜더라도 push 직전 git log --oneline -5로 검토하는 루틴을 더해 두면 안전하다.

 

A.4 [shell_environment_policy] — 환경 변수 화이트리스트

# config.toml — 셸에 전달할 환경 변수만 화이트리스트
    [shell_environment_policy]
    include_only = ["PATH", "HOME", "LANG", "TERM"]
    # OPENAI_API_KEY 등 민감 변수는 이 목록 밖으로 격리된다

보안이 중요한 공유 환경이나 CI에서는 적극 활용한다. 허용 범위를 좁힐수록 의도치 않은 정보 노출 표면이 줄어든다.

 

A.5 [hooks] managed_dir — 엔터프라이즈 훅 경로

# config.toml — 엔터프라이즈 훅 경로
    [hooks]
    managed_dir = "/enterprise/hooks"
    windows_managed_dir = 'C:\enterprise\hooks'
    
    [[hooks.PreToolUse]]
    matcher = "^Bash$"
    
    [[hooks.PreToolUse.hooks]]
    type    = "command"
    command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

Codex가 managed_dir 안의 스크립트를 직접 배포하지 않는다. 스크립트 설치·업데이트는 조직의 엔터프라이즈 툴링이 담당해야 한다. 훅 이벤트는 PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, PermissionRequest 여섯 가지다(hooks 공식 문서).

 

A.6 [agents] · MCP 키 모음

[agents] job_max_runtime_seconds는 배치 작업 타임아웃을, interrupt_message는 인터럽트 안내 문구를 설정한다(v0.128.0~). MCP 쪽에서는 mcp_servers.<name>.experimental_environment = "remote"로 원격 실행기를 지정하고, mcp_oauth_callback_port·mcp_oauth_callback_url로 headless 환경의 OAuth 콜백을 고정한다(MCP 공식 문서).

 

A.7 옛 키 → 새 키 마이그레이션 치트시트

옛 키 (레거시)	새 키	비고
connectors	apps	[features] 하위
codex_hooks	hooks	최상위 섹션
memory_tool	memories	[features] 하위, v0.129.0 Memories MCP v1
web_search_request / web_search_cached	web_search	최상위 통합 키 (cached / live / disabled)
collab	multi_agent	[UNVERIFIED] 소스 코드 확인, 공식 문서 미등재
telepathy	chronicle	[UNVERIFIED] 소스 코드 확인, 공식 문서 미등재

Deprecated 플래그

소스 코드에서 deprecated로 표시된 키: web_search_request, web_search_cached, use_legacy_landlock. CLI 플래그 --full-auto도 v0.128.0에서 deprecated됐다. 명시적 권한 프로파일과 신뢰 흐름 설정(approval_policy + sandbox_mode)으로 대체한다.

 

11. 부록 B — CLI 플래그·codex exec 사전

B.1 자주 쓰는 CLI 플래그

플래그	설명	주요 용도
--cd / -C <path>	작업 디렉터리 변경	모노레포 서브 패키지 지정
--profile / -p <name>	[profiles.<name>] config 로드	CI 환경별 설정 분리
--enable / --disable <feature>	단일 실행에 한해 feature 토글	config.toml 안 건드리고 테스트
--image / -i	이미지 첨부	스크린샷 분석, UI 버그 설명
--no-alt-screen	대체 스크린 버퍼 비활성화	tmux / cmux 멀티 패널
--oss	오픈소스 모드	OSS 기여 컨텍스트
--search	웹 검색 활성화	실시간 정보 필요할 때

가장 자주 쓰는 조합은 -C(경로 지정) + -p(프로파일)이고, tmux에서는 --no-alt-screen이 거의 기본 옵션처럼 따라붙는다.

⚠️ CI 인증 키 — CODEX_API_KEY vs OPENAI_API_KEY

Part 2·7의 CI 예시에서 OPENAI_API_KEY를 사용한 부분이 있다. CI 환경에서는 CODEX_API_KEY를 별도로 발급·관리하는 것이 권장된다. 두 키는 서로 다른 인증 경로이며, OPENAI_API_KEY를 그대로 쓰면 권한 범위가 지나치게 넓어질 수 있다.

 

B.2 codex exec 핵심 플래그

플래그	설명
--ephemeral	세션 지속성 비활성화. CI에서 매 실행을 독립적으로
--ignore-rules	Rules 파일 무시
--ignore-user-config	사용자 전역 config 무시, 프로젝트 config만 사용
-o / --output-last-message <path>	마지막 어시스턴트 메시지를 파일로 저장
--output-schema	출력 JSON 스키마 지정
exec resume --last	마지막 세션을 이어 실행
exec -	표준 입력에서 프롬프트 읽기 (파이프라인용)

 

B.3 파이프라인 예시 — stdin + 파일 출력

# git diff 결과를 Codex에 넘겨 코드 리뷰 요약을 파일로 받는다
    git diff HEAD~1 | codex exec - \
      --ephemeral \
      --ignore-user-config \
      -o /tmp/review-summary.txt \
      --profile ci

한글로 이해하기
exec -는 파이프(|)로 들어온 내용을 프롬프트로 받고, -o로 결과를 파일로 떨군다. --ephemeral까지 합치면 각 CI 실행이 서로 영향을 주지 않는다.

 

B.4 새 서브커맨드 카탈로그

• codex update (v0.128.0~): CLI 업데이트 확인·적용.
• codex completion: 셸 자동완성 스크립트 생성. 예: codex completion zsh >> ~/.zshrc.
• codex features (v0.129.0~): feature 플래그 조회·토글. --enable / --disable과 함께 쓴다.
• codex app: 데스크톱 앱 진입(없으면 설치 안내).
• codex app-server (EXPERIMENTAL): 앱 서버 시작.

 

12. 마무리 — 안전 기본값 + 캡쳐 체크리스트

안전 기본값 권장 세트

어디서 시작할지 모르겠다면 아래 네 가지를 기본값으로 잡는다.

# config.toml — 안전 기본값
    approval_policy = "on-request"    # on-request | untrusted | never
    sandbox_mode    = "workspace-write" # 파일·네트워크 접근 수준
    
    # CI 환경에서는 OPENAI_API_KEY 대신 CODEX_API_KEY를 별도 관리
    # export CODEX_API_KEY="sk-..."
    
    # tmux / cmux 환경에서 실행
    # codex --no-alt-screen "프롬프트"

• approval_policy = "on-request": Codex가 실행 전 승인을 요청한다. 의도하지 않은 변경의 첫 번째 방어선이다.
• sandbox_mode = "workspace-write": 작업 디렉터리는 쓰되 그 외 파일시스템·네트워크는 제한한다.
• CODEX_API_KEY: CI에서 개인 OpenAI 키 대신 별도 발급한 Codex 전용 키를 쓰면 권한 범위를 좁게 유지한다.
• --no-alt-screen: tmux 환경에서 대체 스크린 버퍼를 끄면 다른 패널과 스크롤백이 섞이지 않는다.

 

캡쳐 체크리스트 — 직접 검증하기

이 글은 codex-cli 0.130.0 기준으로 작성됐다. 자신의 환경에서 명령을 실행해 화면을 캡쳐할 때 다음 항목을 함께 확인하면 글의 정확성을 직접 검증할 수 있다.

섹션 1 기본기
□ / 입력 시 popup이 뜨는가
□ Tab으로 큐잉 표시("Queued")가 나타나는가
□ /approvals 입력 시 비활성/안내 메시지가 뜨는가

섹션 2-7 공식 등재 명령
□ /new, /resume, /fork, /side, /clear, /compact, /exit, /logout — 화면 변화 캡쳐
□ /model, /fast, /permissions, /experimental — picker·토글 UI 캡쳐
□ /mention, /mcp, /plugins, /apps, /agent — 카드·표 형태 캡쳐
□ /init, /diff, /review, /plan — 결과 view 캡쳐
□ /status, /debug-config, /feedback, /copy — 상태표·진단 결과 캡쳐
□ /theme, /title, /statusline, /keymap — 변경 즉시 반영 캡쳐

섹션 8 게이트 명령
□ /goal — config.toml에 features.goals = true 세팅 후 실행
□ /personality — 사용 모델이 지원하는지 popup 표시 여부 확인
□ /ps, /stop — features.unified_exec = true 세팅 후 백그라운드 셸 띄워보기

섹션 9 미등재 명령
□ /rename, /raw, /skills, /approve, /realtime, /settings, /collab, /setup-default-sandbox — 자신의 버전에 존재하는지 popup·직접 입력으로 확인
□ 비활성 상태로 표시되면 어떤 플래그가 필요한지 /debug-config에서 점검

 

자주 겪는 문제

• 슬래시 명령이 popup에 안 나온다: alias이거나(/quit↔/exit) feature 플래그가 꺼져 있을 수 있다. 직접 입력 후 Enter로 시도하고 /debug-config로 게이트 조건을 확인한다.
• 명령이 "비활성" 상태로 보인다: 필요한 feature 플래그가 꺼져 있다는 뜻이다. /experimental로 즉시 토글하거나 config.toml에서 영구 설정한다.
• config.toml 변경이 반영되지 않는다: TUI를 완전히 재시작한다. 일부 키는 세션 재시작이 필요하다.
• tmux에서 화면이 깨진다: --no-alt-screen 플래그를 붙이거나 /raw로 렌더링 모드를 전환해본다(v0.129.0~).

 

참고 자료

• 공식 slash-commands 문서
• 공식 config-basic 문서
• hooks 공식 문서
• MCP 공식 문서
• v0.128.0 릴리즈 노트
• v0.129.0 릴리즈 노트