기본 구성

Codex는 여러 위치에서 구성 정보를 읽습니다. 개인 기본값은 ~/.codex/config.toml에 두고, 프로젝트별 오버라이드는 .codex/config.toml 파일로 추가할 수 있습니다. 보안을 위해 Codex는 사용자가 신뢰한 프로젝트에서만 프로젝트의 .codex/ 계층을 로드합니다.

Codex 구성 파일

Codex는 사용자 수준 구성을 ~/.codex/config.toml에 저장합니다. 특정 프로젝트나 하위 폴더에만 설정을 적용하려면 저장소 안에 .codex/config.toml 파일을 추가합니다.

Codex IDE 확장에서 구성 파일을 열려면 오른쪽 위의 톱니바퀴 아이콘을 선택한 다음 Codex Settings > Open config.toml을 선택합니다.

CLI와 IDE 확장은 같은 구성 계층을 공유합니다. 이 파일들로 다음 항목을 설정할 수 있습니다.

기본 모델과 provider를 설정합니다.
승인 정책과 sandbox 설정을 구성합니다.
MCP 서버를 구성합니다.

구성 우선순위

Codex는 다음 순서로 값을 결정합니다. 위에 있을수록 우선순위가 높습니다.

CLI flag와 --config 오버라이드
Profile 값(--profile <name>에서 가져옴)
프로젝트 구성 파일: .codex/config.toml. 프로젝트 root에서 현재 작업 디렉터리까지의 순서로 적용됩니다. 가까운 파일이 우선하며, trusted 프로젝트에서만 로드됩니다.
사용자 구성: ~/.codex/config.toml
시스템 구성(있는 경우): Unix의 /etc/codex/config.toml
내장 기본값

이 우선순위를 활용해 공통 기본값은 상위 계층에 두고, profile에는 달라지는 값만 집중해서 넣습니다.

프로젝트를 untrusted로 표시하면 Codex는 프로젝트 local 구성, hook, rule을 포함한 프로젝트 범위의 .codex/ 계층을 건너뜁니다. 사용자 및 시스템 구성은 계속 로드되며, 사용자/global hook과 rule도 포함됩니다.

-c/--config로 일회성 오버라이드를 지정하는 방법과 TOML quoting 규칙은 고급 구성을 참고하십시오.

관리형 장비에서는 조직이 requirements.toml을 통해 제약을 강제할 수도 있습니다. 예를 들어 approval_policy = "never"나 sandbox_mode = "danger-full-access"를 금지할 수 있습니다.

자주 쓰는 구성 옵션

많이 변경하는 옵션은 다음과 같습니다.

기본 모델

CLI와 IDE에서 Codex가 기본으로 사용할 모델을 선택합니다.

model = "gpt-5.5"

승인 프롬프트

생성된 명령을 실행하기 전에 Codex가 언제 멈추고 확인을 요청할지 제어합니다.

approval_policy = "on-request"

Sandbox 수준

Codex가 명령을 실행할 때 사용할 수 있는 파일 시스템 및 네트워크 접근 범위를 조정합니다.

sandbox_mode = "workspace-write"

권한 profile

세션마다 같은 파일 시스템 또는 네트워크 정책을 재사용하려면 이름이 붙은 권한 profile을 사용합니다.

default_permissions = ":workspace"

내장 profile에는 :read-only, :workspace, :danger-no-sandbox가 있습니다. 사용자 지정 파일 시스템 또는 네트워크 규칙을 쓰려면 [permissions.<name>] table을 정의하고 default_permissions를 그 이름으로 설정합니다.

Windows sandbox 모드

Windows에서 Codex를 native로 실행할 때는 windows table의 native sandbox 모드를 elevated로 설정합니다. 관리자 권한이 없거나 elevated 설정이 실패할 때만 unelevated를 사용하십시오.

[windows]
sandbox = "elevated"   # 권장
# sandbox = "unelevated" # 관리자 권한이나 설정을 사용할 수 없을 때의 대안

웹 검색 모드

Codex는 local 작업에서 기본적으로 웹 검색을 켜고, 웹 검색 cache에서 결과를 제공합니다. 이 cache는 OpenAI가 관리하는 웹 결과 index이므로 cached 모드는 live page를 직접 가져오지 않고 미리 색인된 결과를 반환합니다. 이렇게 하면 임의의 live content에서 발생할 수 있는 prompt injection 노출을 줄일 수 있지만, 웹 결과는 여전히 신뢰할 수 없는 정보로 다뤄야 합니다. --yolo 또는 다른 전체 접근 sandbox 설정을 사용하면 웹 검색은 기본적으로 live 결과를 사용합니다. web_search로 모드를 선택합니다.

"cached"(기본값)는 웹 검색 cache에서 결과를 제공합니다.
"live"는 웹에서 최신 데이터를 가져옵니다(--search와 같음).
"disabled"는 웹 검색 도구를 끕니다.

web_search = "cached"  # 기본값; 웹 검색 cache에서 결과 제공
# web_search = "live"  # 웹에서 최신 데이터를 가져옴(--search와 같음)
# web_search = "disabled"

추론 노력

지원되는 모델에서 모델이 사용하는 reasoning effort의 양을 조정합니다.

model_reasoning_effort = "high"

커뮤니케이션 스타일

지원되는 모델의 기본 커뮤니케이션 스타일을 설정합니다.

personality = "friendly" # 또는 "pragmatic" 또는 "none"

활성 세션에서는 나중에 /personality로 오버라이드할 수 있고, app-server API를 사용할 때는 thread/turn 단위로도 오버라이드할 수 있습니다.

TUI keymap

Terminal shortcut은 tui.keymap 아래에서 사용자 지정합니다. Context-specific binding은 tui.keymap.global보다 우선하며, 빈 list를 지정하면 해당 action의 binding을 해제합니다.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

명령 환경

Codex가 생성한 명령에 어떤 환경 변수를 전달할지 제어합니다.

[shell_environment_policy]
include_only = ["PATH", "HOME"]

로그 디렉터리

codex-tui.log 같은 local log file을 Codex가 쓸 위치를 오버라이드합니다.

log_dir = "/absolute/path/to/codex-logs"

일회성 실행에서는 CLI에서도 설정할 수 있습니다.

codex -c log_dir=./.codex-log

기능 플래그

config.toml의 [features] table을 사용해 선택 기능과 실험적 기능을 켜거나 끕니다.

[features]
shell_snapshot = true           # 반복 명령 실행 속도 향상

지원되는 기능

Key	기본값	단계	설명
`apps`	false	실험적	ChatGPT Apps/connectors 지원 활성화
`codex_git_commit`	false	실험적	Codex가 생성하는 git commit과 commit attribution trailer 활성화
`codex_hooks`	true	안정화	`hooks.json` 또는 inline `[hooks]`의 lifecycle hook 활성화.
`fast_mode`	true	안정화	Fast mode 선택과 `service_tier = "fast"` 경로 활성화
`memories`	false	안정화	메모리 활성화
`multi_agent`	true	안정화	Subagent 협업 도구 활성화
`personality`	true	안정화	Personality 선택 control 활성화
`shell_snapshot`	true	안정화	반복 명령을 빠르게 실행하도록 shell environment snapshot 생성
`shell_tool`	true	안정화	기본 `shell` tool 활성화
`unified_exec`	`true` except Windows	안정화	통합 PTY 기반 exec tool 사용
`undo`	false	안정화	Turn별 git ghost snapshot을 통한 undo 활성화
`web_search`	true	Deprecated	Legacy toggle. 최상위 `web_search` 설정을 권장합니다.
`web_search_cached`	false	Deprecated	Legacy toggle. 설정되지 않았을 때 `web_search = "cached"`에 매핑됩니다.
`web_search_request`	false	Deprecated	Legacy toggle. 설정되지 않았을 때 `web_search = "live"`에 매핑됩니다.

기능 key를 생략하면 기본값이 유지됩니다.

현재 lifecycle hooks MVP는 Hooks를 참고하십시오.

기능 켜기

config.toml에서 [features] 아래에 feature_name = true를 추가합니다.
CLI에서는 codex --enable feature_name을 실행합니다.
둘 이상의 기능을 켜려면 codex --enable feature_a --enable feature_b를 실행합니다.
기능을 끄려면 config.toml에서 해당 key를 false로 설정합니다.