Codex CLI config.toml 위치와 우선순위: 값이 무시될 때

git 저장소 안에 .codex/config.toml을 만들고 model = "project-level-model"을 적었습니다. 그런데 codex doctor의 model 줄은 사용자 설정 값(gpt-5.1-codex) 그대로였어요. 파일 이름도 위치도 맞았는데 말이죠.

이유는 그 폴더를 신뢰로 표시하지 않았기 때문이었습니다. Codex CLI의 설정은 이렇게 “적었는데 안 먹는” 경우가 몇 가지 있어서, 우선순위와 함께 한 번에 정리해 두기로 했습니다. 같은 키를 여러 곳에 적으면 명령줄(-c, -m) > 신뢰한 프로젝트 폴더의 .codex/config.toml > --profile 파일 > ~/.codex/config.toml > 내장 기본값 순으로 이기고, 위 층에 적지 않은 키는 아래 층 값이 그대로 남습니다.

설정 파일은 두 군데입니다. 모든 프로젝트에 적용되는 사용자 설정 ~/.codex/config.toml(Windows는 %USERPROFILE%\.codex\config.toml)과, 신뢰한 프로젝트 폴더 안의 .codex/config.toml이에요. CODEX_HOME 환경 변수를 주면 사용자 설정을 그 폴더에서 읽습니다. Codex CLI 설치 글의 첫 설치 상태 점검도 빈 폴더를 CODEX_HOME으로 줘서 한 것입니다.

2026년 9월 26일 Ubuntu 24.04 · bash 테스트 환경에서 Codex CLI 0.157.1(npm)로 직접 확인한 결과이고, 근거는 직접 실행 결과와 CLI 도움말입니다. Windows 부분은 10월 13일 Windows 11 · Codex CLI 0.162.1에서 다시 확인했습니다.

같은 키는 어디가 이기나

~/.codex/config.toml에 model = "gpt-5.1-codex"를 적어 두고, 같은 model을 프로필·프로젝트 폴더·명령줄에 하나씩 얹어 봤습니다. codex exec가 시작할 때 찍는 헤더의 model: 줄이 이렇게 바뀌더라고요.

얹은 것	헤더의 model:
없음(사용자 설정만)	gpt-5.1-codex
-p review(프로필)	gpt-5.1-codex-mini
신뢰한 프로젝트 폴더 + -p review	project-level-model
-p review -c model="o3"	o3
-p review -m gpt-5.1	gpt-5.1

아래로 갈수록 셉니다. 그림으로 보면 이렇습니다.

중요한 건 층을 통째로 갈아치우지 않고 각 층에 적힌 키만 덮어쓴다는 점이에요. 그래서 위에 얹는 파일에는 바꿀 키만 적으면 됩니다.

혼자 한 저장소만 쓴다면 ~/.codex/config.toml 하나에 다 적어도 충분합니다. 층이 문제 되는 건 저장소에 .codex/config.toml이 들어 있거나 실행 스크립트가 -c를 넘길 때예요. 내 설정이 안 먹는 이유는 대개 거기에 있습니다.

지금 적용된 값은 codex doctor로 봅니다. 로그인 없이 돌고, config.toml 줄은 읽은 파일, model 줄은 결정된 값, parse 줄은 문법이 맞는지를 알려 줘요.

Configuration
  ✓ config       loaded
      model                    gpt-5.1-codex · openai
      config.toml              ~/.codex/config.toml
      config.toml parse        ok

다만 codex doctor는 -p를 받지 않습니다(error: unexpected argument '-p' found). 프로필까지 얹은 결과는 위 표처럼 codex exec의 헤더로 보세요.

-c로 넘길 때

-c는 점으로 중첩 키를 씁니다. -c sandbox_workspace_write.network_access=true처럼 표 안의 키를 바로 지정할 수 있어요.

TOML로 읽히지 않는 값은 문자열로 들어갑니다. codex doctor -c model=o3처럼 따옴표를 빼도 o3가 들어갔어요. 숫자나 true처럼 다른 타입으로 읽힐 값을 문자열로 넘기려면 -c model="o3"처럼 따옴표를 붙이면 됩니다.

그리고 --enable <기능>은 별도 층이 아니라 -c features.<기능>=true의 줄임이에요.

같은 키를 -c와 -m으로 함께 주지 말고, 한 실행에서는 둘 중 하나만 쓰세요.

조직이 설정을 잠그는 장치는 위 다섯 층과 별도로 있습니다. 조직용 requirements.toml인데, 공식 docs/config.md의 훅 문단에 따르면 관리자가 여기에 최상위 allow_managed_hooks_only = true를 넣으면 관리형 훅은 두고 사용자·프로젝트·세션의 훅 설정을 무시하게 합니다.

같은 문서에 따르면 이 설정은 config.toml에 넣어서는 켜지지 않습니다(2026년 9월 26일 기준).

프로필은 바꿀 키만 적은 파일

프로필은 config.toml 안의 [profiles.x] 표가 아니라 $CODEX_HOME/<이름>.config.toml 파일 하나입니다. 기본 사용자 설정에 세 키를 적고,

model = "gpt-5.1-codex"
approval_policy = "never"
sandbox_mode = "read-only"

프로필 파일 ~/.codex/review.config.toml에 두 키만 적은 뒤 비교했습니다.

model = "gpt-5.1-codex-mini"
sandbox_mode = "workspace-write"

실행	model	approval	sandbox
codex exec "hi"	gpt-5.1-codex	never	read-only
codex exec -p review "hi"	gpt-5.1-codex-mini	never	workspace-write

프로필이 적은 두 키만 바뀌고, 적지 않은 approval_policy는 never가 남았습니다. -p를 두 번 줘서 프로필을 겹칠 수는 없어요(error: the argument '--profile <CONFIG_PROFILE_V2>' cannot be used multiple times). 여러 프로필이 필요하면 파일을 합치거나 차이 나는 키만 -c로 주세요.

CODEX_HOME을 바꾸면 프로필 파일도 따라갑니다. 프로필 파일 위치가 $CODEX_HOME/<이름>.config.toml이고, codex doctor의 config.toml 줄도 지정한 폴더를 가리켰어요. 지정하지 않으면 ~/.codex입니다.

폴더 설정이 안 읽혔던 이유

여기서 가장 오래 헤맸습니다. 파일은 맞는 자리에 있었는데, 그 폴더를 신뢰로 표시하지 않았던 게 원인이었어요. 사용자 설정 ~/.codex/config.toml에 이렇게 적자 바로 읽혔습니다.

[projects."<프로젝트 경로>"]
trust_level = "trusted"

      model                    project-level-model · openai
      approval policy          Never

폴더 설정의 model이 이겼고, 폴더 설정에 없는 approval_policy는 사용자 설정의 never가 남았습니다. 신뢰하지 않은 폴더에서 codex exec를 그냥 실행하면 아예 Not inside a trusted directory and --skip-git-repo-check was not specified.로 멈췄고요.

Windows 11 · Codex CLI 0.162.1에서는 조금 달랐어요. 새 git 폴더에 .codex/config.toml을 두고 model = "project-level-model"을 적은 뒤 처음 codex exec를 돌리니, 멈추지 않고 실행은 됐는데 헤더의 model:은 사용자 설정 값 그대로였어요. 같은 자리에서 -c model='"gpt-5.5"'를 주면 model: gpt-5.5로 바뀌었고요.

Ubuntu 0.157.1에서는 멈췄고 Windows 0.162.1에서는 실행됐지만, 신뢰 표시가 없는 폴더의 설정이 적용되지 않은 것은 둘 다 같았습니다.

신뢰 표시는 codex 실행 중에 자동으로 기록되는 경우도 있으니, 테스트 폴더를 지웠다면 ~/.codex/config.toml에 그 폴더의 [projects.…] 항목이 남아 있지 않은지도 한 번 보세요.

그렇다고 설정을 먹이려는 목적만으로 낯선 저장소를 신뢰하지는 마세요. 신뢰한 폴더에서 무엇이 허용되는지는 Codex CLI 샌드박스 모드와 승인 정책에 썼습니다.

프로젝트의 .codex/config.toml은 모델이나 샌드박스 모드 같은 값이라 팀과 공유해도 됩니다. ~/.codex 쪽은 올리지 마세요. projects 신뢰 표시처럼 개인 경로가 쌓이고, 같은 폴더에 인증 정보 파일(auth.json)도 놓이거든요.

파일은 git 저장소 루트까지만 찾는다

현재 폴더에서 시작해 git 저장소 루트까지 올라가며 가장 가까운 파일 하나를 씁니다.

.codex/config.toml 위치	실행한 곳	결과
저장소 루트	하위 폴더	적용됨
루트와 하위 폴더 양쪽	하위 폴더	하위 폴더 것
저장소 바깥 상위 폴더	저장소 루트	적용 안 됨
상위 폴더(git 저장소 아님)	하위 폴더	적용 안 됨

여러 저장소에 공통으로 쓸 설정은 이 층이 아니라 ~/.codex/config.toml에 두세요.

프로필로는 폴더 설정을 못 덮는다

신뢰한 그 폴더에서 -p review를 주면, 둘 다 적은 model은 폴더 값(project-level-model)이 이기고 프로필만 적은 sandbox_mode는 프로필 값(workspace-write)이 남았습니다. 프로필은 사용자 설정 위에 얹히고, 폴더 설정은 그 결과 위에 다시 얹히기 때문이에요(0.157.1 기준).

표 아래 적은 키는 조용히 무시된다

이 파일은 문법이 올바른 TOML인데도 model이 먹지 않습니다.

approval_policy = "never"

[shell_environment_policy]
inherit = "core"

model = "gpt-5.1-codex-mini"

codex doctor는 model을 <default>로, parse는 ok로 보여 줍니다. TOML에서는 [표이름] 줄 뒤의 모든 키가 그 표에 속하기 때문에, 이 model은 최상위 키가 아니라 shell_environment_policy.model이 돼요. 파일 끝에 키를 덧붙이는 습관이 있으면 누구나 걸릴 수 있는 함정입니다.

이럴 때 --strict-config를 붙이면 어느 표로 들어갔는지 알려 줍니다.

$ codex exec --strict-config "hi"
Error loading config.toml:
~/.codex/config.toml:6:1: unknown configuration field `shell_environment_policy.model`

키 앞에 표 이름이 붙어 나오면(shell_environment_policy.model) 자리 문제예요. 그 키를 첫 [표] 줄보다 위로 옮기면 됩니다.

키 이름만 나오면(not_a_real_key) 이름 문제입니다. 오타이거나 이 버전에 없는 키예요.

주의: --strict-config를 평소 실행에 늘 붙이면 버전을 올릴 때마다 예전 키 때문에 멈출 수 있습니다. 설정을 손본 직후 한 번만 돌려 보세요.

오류 문장은 doctor보다 exec가 정확하다

설정 때문에 막혔을 때 codex doctor만 보면 원인을 모를 때가 있습니다. 그럴 땐 codex exec를 한 번 실행해 보세요. 실제 문장이 나옵니다.

legacy profile = "..." config is no longer supported

config.toml 최상위에 profile = "openai-chatgpt"를 적고 codex exec를 실행하자 이 한 줄을 남기고 끝났습니다(0.157.1).

Error: legacy `profile = "openai-chatgpt"` config is no longer supported; use `--profile openai-chatgpt` with `openai-chatgpt.config.toml` instead

같은 설정에서 codex doctor는 error invalid data라고만 보여 줘서 원인을 알 수 없었어요.

config.toml에 기본 프로필을 지정하던 방식이 없어진 겁니다. 대신 쓸 수단은 실행할 때 주는 -p뿐이었습니다. --help에 프로필용 환경 변수가 없고, CODEX_PROFILE을 설정해 봐도 적용되지 않았거든요.

profile = 줄을 지우고 그 내용을 ~/.codex/<이름>.config.toml에 옮긴 뒤 실행마다 -p <이름>을 주면 됩니다. 늘 쓸 프로필이라면 저는 내용을 config.toml 본체로 옮기는 쪽이 간단하다고 봅니다.

config could not be loaded / invalid configuration

codex doctor의 Configuration이 ✗로 나오고 file 줄에 파일 경로가 찍힙니다. model = 처럼 값이 빠진 줄 하나만 있어도 이렇게 돼요.

  ✗ config       config could not be loaded — Fix the reported config error, then rerun codex doctor.
      error                    invalid configuration
      file                     ~/.codex/config.toml

TOML 문법이 깨졌다는 뜻입니다(값이 빠진 줄, 닫히지 않은 따옴표, 중복된 표 이름 등). file 줄이 가리키는 파일을 열어 고치세요. 반대로 파일이 아예 없으면 오류 없이 기본값으로 돌고, model 자리에 <default>가 찍힙니다.

다른 사람들이 겪은 문제

아래 세 건은 공개 저장소에 올라온 보고입니다. 모두 프로필이 별도 파일로 바뀐 변화와 관련돼 있어요.

• igorshos는 CLI 0.134.0에서 기존 config.toml의 최상위 profile 키 때문에 CLI가 아예 시작되지 않았고, 마이그레이션이나 경고가 없다는 점을 문제로 적었습니다(#24858, 2026-05-28, 열림). 보고의 오류는 Error loading configuration:으로 시작해 위 0.157.1 출력(Error:)과 접두사만 다르고, 보고자는 인자 없이 codex를 실행했습니다.
• siddhpant는 예전 키를 되살려 달라며 실행마다 --profile을 넘겨야 하는 불편을 들었습니다(#24724, 2026-05-27, 열림).
• btomaj의 프로젝트 설정 안의 프로필 요청은 계획 없음으로 닫혔습니다(#21580, 2026-05-07). 폴더 설정 안의 프로필 이야기라 위 “프로필로는 폴더 설정을 못 덮는다”와 같은 사안은 아닙니다.

마치며

Codex CLI 설정에서 제가 실제로 막힌 곳은 우선순위가 아니라 “애초에 읽혔느냐”였습니다. 신뢰하지 않은 폴더의 설정, 표 아래로 들어간 키 둘 다 오류 없이 조용히 무시되거든요.

그래서 설정을 바꿨는데 반영이 안 되면 이 순서로 보시길 권합니다. codex doctor로 읽은 파일이 생각한 그 파일인지, parse가 ok인지 먼저 보세요. 둘 다 맞는데 값이 그대로면 --strict-config로 키가 표 안에 들어갔는지, 프로젝트 폴더 설정이라면 그 폴더를 신뢰했는지 확인하면 됩니다.

설정에 적는 sandbox_mode와 approval_policy가 실제로 무엇을 막는지는 Codex CLI 샌드박스 모드와 승인 정책에서 이어집니다.

다른 도구의 같은 문제는 Claude Code 설정 파일 4계층과 우선순위와 Gemini CLI settings.json 네 파일이 겹칠 때 이기는 값에 있어요.