Codex는 여러 위치에서 설정을 읽습니다. 개인 기본값은 ~/.codex/config.toml에 저장되며, .codex/config.toml 파일을 추가해 프로젝트별로 기본값을 재정의할 수 있습니다. 보안을 위해 Codex는 사용자가 신뢰하는 프로젝트에서만 프로젝트의 .codex/ 설정 계층을 불러옵니다.
Codex 설정 파일
Codex는 사용자 수준 설정을 ~/.codex/config.toml에 저장합니다. 특정 프로젝트나 하위 폴더에만 설정을 적용하려면 레포지토리의 해당 위치에 .codex/config.toml 파일을 추가하세요.
Codex IDE 확장 프로그램에서 설정 파일을 열려면 오른쪽 위의 톱니바퀴 아이콘을 선택한 다음 Codex 설정 > config.toml 열기를 선택하세요.
CLI와 IDE 확장 프로그램은 같은 설정 계층을 사용합니다. 다음 항목을 설정할 수 있습니다.
- 기본 모델과 제공업체를 지정합니다.
- 승인 정책과 샌드박스 설정을 구성합니다.
- MCP 서버를 구성합니다.
설정 우선순위
요구 사항은 허용되는 동작을 제한하고, 설정값은 기본 동작을 정합니다. Work Cloud에서 로컬 컴퓨터에 액세스할 때는 다음 요구 사항이 적용됩니다.
- 정책 간 우선순위: 우선순위가 낮은 정책이 더 구체적이어도 우선순위가 높은 정책이 적용됩니다.
- 단일 정책 내 우선순위: 특정 OS에 대한 환경 재정의가 가장 우선하며, 그다음은 모든 OS에 대한 환경 재정의, 마지막은 Global 설정입니다.
- 로컬 실행: MDM 요구 사항과 기존 관리형 기기 요구 사항이 Agent Security보다 우선합니다. 기기의 시스템 요구 사항 파일은 Agent Security보다 우선순위가 낮습니다.
- Work Cloud: Work 클라우드 컨테이너에는 기존 Work Cloud 정책이 계속 적용됩니다. 로컬 액세스를 사용하는 Work와 dot의 경우, 관리형 정책을 활성화하면 공유 클라우드 오케스트레이터에 지원되는 Global 정책이 적용됩니다. 연결된 컴퓨터에는 해당 로컬 실행 요구 사항이 적용됩니다.
일부 요구 사항에는 필드별 병합 규칙이 있습니다. 정책의 적용 범위와 런타임 제한은 관리형 설정을, Work 호환성은 설정 레퍼런스를 참고하세요.
Codex가 설정값을 결정할 때 적용하는 우선순위는 다음과 같습니다. 위쪽 항목일수록 우선순위가 높습니다.
- CLI 플래그와
--config로 재정의한 값 - 프로젝트 설정 파일: 프로젝트 루트부터 현재 작업 디렉터리까지 각 디렉터리의
.codex/config.toml을 순서대로 적용합니다. 현재 작업 디렉터리에 가장 가까운 파일이 우선하며, 신뢰하는 프로젝트에만 적용됩니다. - 프로필 파일:
--profile profile-name으로 선택한 파일(~/.codex/profile-name.config.toml) - 사용자 설정:
~/.codex/config.toml - 클라우드에서 관리하는
config.toml기본값(로그인한 워크스페이스에 제공되는 경우) - 시스템 설정(파일이 있는 경우): Unix에서는
/etc/codex/config.toml - 내장 기본값
이 우선순위에 따라 config.toml에는 공통 기본값을 지정하고, 프로필 파일에는 기본값과 다른 값만 지정하세요.
클라우드 관리형 설정과 시스템 설정에서는 플러그인 마켓플레이스를 정의하고 플러그인을 기본으로 활성화할지 지정할 수 있습니다. 이러한 설정은 requirements.toml로 강제하는 정책과 별개입니다. 플러그인 마켓플레이스 및 기본값 설정을 참고하세요.
프로젝트를 신뢰하지 않는 것으로 표시하면 Codex는 프로젝트 범위의 .codex/ 계층을 건너뜁니다. 여기에는 프로젝트 로컬 설정, 훅, 규칙이 포함됩니다. 사용자 및 전역 훅과 규칙을 비롯한 사용자 설정과 시스템 설정은 계속 불러옵니다.
-c/--config로 설정을 일회성으로 재정의하는 방법과 TOML 인용 부호 규칙은 고급 설정을 참고하세요.
조직은 관리 대상 기기에서 requirements.toml로 추가 제약을 적용할 수 있습니다. 예를 들어 approval_policy = "never" 또는 sandbox_mode = "danger-full-access"를 허용하지 않을 수 있습니다. 관리형 설정과 관리자가 강제하는 요구 사항을 참고하세요.
자주 사용하는 설정 옵션
사용자가 자주 변경하는 옵션은 다음과 같습니다.
기본 모델
Codex가 CLI와 IDE에서 기본으로 사용할 모델을 선택하세요.
model = "gpt-6.1-sol"승인 요청
Codex가 생성한 명령어를 실행하기 전에 언제 일시 중지하고 승인을 요청할지 지정하세요.
approval_policy = "on-request"on-request와 never의 동작 차이는 승인 요청 없이 실행하기와 자주 사용하는 샌드박스 및 승인 설정 조합을 참고하세요. 기존 설정에서 approval_policy = "untrusted"를 사용한다면 지원이 종료된 untrusted 승인 정책에서 마이그레이션하기를 참고하세요.
샌드박스 수준
Codex가 명령어를 실행할 때 파일 시스템과 네트워크에 액세스할 수 있는 범위를 조정하세요.
sandbox_mode = "workspace-write"보호되는 .git, .agents, .codex, .aws 경로와 네트워크 기본값을 비롯한 모드별 동작은 샌드박스 및 승인, 쓰기 가능한 루트의 보호 경로, 네트워크 액세스를 참고하세요.
권한 프로필
Codex는 파일 시스템 및 네트워크 정책을 재사용할 수 있도록 이름이 있는 권한 프로필도 지원합니다. 내장 프로필은 :read-only, :workspace, :danger-full-access입니다. 사용자 지정 프로필을 만들려면 [permissions.<name>] 테이블을 정의하고 default_permissions 값을 해당 프로필 이름으로 지정하세요. 권한을 참고하세요.
Windows 샌드박스 모드
Windows에서는 기기와 정책이 지원하는 경우 MXC를 우선 사용하세요. MXC를 사용할 수 없을 때를 대비해 기존 구현도 지정하세요.
[windows]
sandbox = "elevated" # Legacy fallback
[features]
prefer_mxc = trueunelevated는 권한을 높여 설정할 수 없고 조직 정책에서 허용하는 경우에만 사용하세요. 호환성 제한과 단계적 배포를 제어하는 방법은 Windows 샌드박스 가이드를 참고하세요.
웹 검색 모드
Codex는 로컬 채팅에서 기본적으로 웹 검색을 활성화하고 웹 검색 캐시의 결과를 제공합니다. 이 캐시는 OpenAI가 관리하는 웹 검색 결과 색인입니다. 캐시 모드에서는 웹 페이지를 실시간으로 가져오는 대신 미리 색인된 결과를 반환하므로 임의의 실시간 콘텐츠를 통한 프롬프트 인젝션에 노출될 위험이 줄어듭니다. 웹 검색 결과는 신뢰할 수 없는 데이터로 취급하세요. --yolo 또는 다른 전체 권한 샌드박스 설정을 사용하면 웹 검색은 기본적으로 실시간 결과를 제공합니다. web_search로 모드를 선택하세요.
"cached"(기본값)는 웹 검색 캐시의 결과를 제공합니다."indexed"를 사용하면 검색 색인이 요청을 허용한 경우에만 외부 웹에 액세스할 수 있습니다."live"는 웹에서 최신 데이터를 가져옵니다(--search와 동일)."disabled"는 웹 검색 도구를 비활성화합니다.
web_search = "cached" # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live" # fetch the most recent data from the web (same as --search)
# web_search = "disabled"추론 수준
이 설정을 지원하는 모델에서는 추론에 들이는 노력을 조정할 수 있습니다.
model_reasoning_effort = "medium"대화 스타일
내장 성격 지침을 제외하려면 다음과 같이 설정하세요.
personality = "none"이 설정은 모델의 내장 지침에서 Personality 섹션을 제거합니다. 명시적으로 지정한 사용자 지정 기본 지침에는 영향을 주지 않습니다. 기존의 friendly와 pragmatic 값으로는 더 이상 스타일을 선택할 수 없습니다. Codex는 더 이상 /personality 명령어를 제공하지 않습니다.
TUI 키 매핑
tui.keymap에서 터미널 단축키를 지정하세요. 일부 Composer 동작은 별도 키 매핑이 없으면 tui.keymap.global의 해당 매핑을 사용합니다. 컨텍스트별 키 매핑을 지원하는 경우에는 해당 매핑이 우선합니다. 빈 목록을 지정하면 해당 동작의 키 매핑이 해제됩니다.
[tui.keymap.global]
open_transcript = "ctrl-t"
[tui.keymap.composer]
submit = ["enter", "ctrl-m"]
[tui.keymap.chat]
interrupt_turn = "f12"명령어 실행 환경
Codex가 명령어를 실행할 때 전달할 환경 변수를 지정하세요. 변수 이름별로 필터를 설정하면 필요한 변수만 남길 수 있습니다.
[shell_environment_policy]
ignore_default_excludes = false
[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"ignore_default_excludes의 기본값은 true입니다. 기본값을 사용하면 이름에 KEY, SECRET 또는 TOKEN이 포함된 변수를 자동으로 필터링하지 않습니다. 자동 필터링을 적용하려면 false로 설정하세요. 제외 규칙, 우선순위, 기존 설정 방식은 셸 환경 정책을 참고하세요.
로그 디렉터리
Codex가 로컬 로그 파일을 저장할 위치를 변경할 수 있습니다. log_dir를 명시적으로 지정하면 평소에는 비활성화되어 있는 일반 텍스트 형식의 TUI 로그 codex-tui.log도 해당 디렉터리에 기록됩니다.
log_dir = "/absolute/path/to/codex-logs"한 번 실행할 때만 적용하려면 CLI에서도 지정할 수 있습니다.
codex -c log_dir=./.codex-log기능 플래그
[features] 테이블은 config.toml에서 선택적 기능과 실험적 기능을 켜거나 끄는 데 사용합니다.
자주 사용하는 기능 플래그
| 키 | 기본값 | 성숙도 | 설명 |
|---|---|---|---|
apps |
true | 안정 | 앱(커넥터) 연동을 활성화합니다. |
goals |
true | 안정 | 목표를 저장하고 작업을 자동으로 이어갈 수 있습니다. |
hooks |
true | 안정 | hooks.json 또는 인라인 [hooks]에 정의한 수명 주기 훅을 활성화합니다. 훅을 참고하세요. |
fast_mode |
true | 안정 | 패스트 모드를 선택하거나 service_tier = "fast" 설정을 사용할 수 있습니다. |
memories |
false | 안정 | 메모리를 활성화합니다. |
multi_agent |
true | 안정 | 하위 에이전트 협업 도구를 활성화합니다. |
remote_plugin |
true | 안정 | 원격 플러그인 카탈로그를 활성화합니다. |
shell_snapshot |
true | 안정 | 셸 환경의 스냅샷을 만들어 반복 실행하는 명령어의 속도를 높입니다. |
shell_tool |
true | 안정 | 명령어 실행 도구를 활성화합니다. |
unified_exec |
true | 안정 | 명령어 실행을 재개할 수 있습니다. 관리형 요구 사항으로만 비활성화할 수 있습니다. |
web_search |
true | 사용 중단 예정(deprecated) | 기존 플래그입니다. 최상위 web_search 설정을 우선 사용하세요. |
web_search_cached |
false | 사용 중단 예정(deprecated) | 최상위 설정을 지정하지 않았을 때 web_search = "cached"에 대응하는 기존 플래그입니다. |
web_search_request |
false | 사용 중단 예정(deprecated) | 최상위 설정을 지정하지 않았을 때 web_search = "live"에 대응하는 기존 플래그입니다. |
이 표에는 사용자가 자주 쓰는 플래그를 정리했습니다. 내부 기능이나 개발 중인 기능을 모두 포함하지는 않습니다. 성숙도 열에는 실험적, 베타, 안정 등의 단계가 표시됩니다. 각 단계의 의미는 기능 성숙도를 참고하세요.
수명 주기 훅 설정 방법은 훅을 참고하세요.
기능 활성화
config.toml에서feature_name = true를[features]아래에 추가하세요.- CLI에서는
codex --enable feature_name을 실행하세요. - 여러 기능을 활성화하려면
codex --enable feature_a --enable feature_b를 실행하세요. - 기능을 비활성화하려면 해당 키의 값을
false로 지정하세요. 이 값은config.toml에서 설정합니다.