codex 설정 파일 — config.toml 위치와 옵션

Codex의 설정 파일은 ~/.codex/config.toml입니다. 윈도우라면 C:\Users\내계정\.codex\config.toml이고, 처음에는 파일이 없습니다. 직접 만들어야 합니다. 프로젝트에만 적용할 설정은 저장소 안에 .codex/config.toml을 두고, 한 번만 쓰고 버릴 값은 -c 키=값 옵션으로 넘깁니다. 아래는 codex-cli 0.153.4에서 직접 돌려 확인한 내용입니다(2026년 9월 7일 · 윈도우 11).

1. 설정 파일은 어디에 있나

파일	적용 범위
~/.codex/config.toml	내 계정 전체 (기본 설정은 여기)
~/.codex/<이름>.config.toml	--profile <이름>으로 부를 때만 얹힘
프로젝트의 .codex/config.toml	그 저장소에서만 (신뢰한 프로젝트만)
/etc/codex/config.toml	시스템 전체 (유닉스 계열, 있을 때만)

파일이 없으면 만들면 됩니다. 폴더째 없으면 폴더부터 만듭니다.

# 맥 · 리눅스
mkdir -p ~/.codex && touch ~/.codex/config.toml

# 윈도우 (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
New-Item -ItemType File "$env:USERPROFILE\.codex\config.toml"

💡 위치를 통째로 옮기고 싶으면 환경변수 CODEX_HOME을 다른 폴더로 지정하면 됩니다. 그러면 Codex는 그 폴더의 config.toml을 읽습니다. 설정을 실험해 보고 싶은데 원래 파일은 건드리기 싫을 때 편합니다.

2. 어느 값이 이기나 — 우선순위

같은 항목이 여러 곳에 있으면 위에 있는 것이 이깁니다.

1. 명령줄 옵션과 -c / --config 덮어쓰기
2. 프로젝트 설정 .codex/config.toml (저장소 뿌리에서 지금 폴더 쪽으로 내려오며, 가까운 것이 이김)
3. --profile 이름으로 고른 프로필 파일 ~/.codex/이름.config.toml
4. 사용자 설정 ~/.codex/config.toml
5. 시스템 설정 /etc/codex/config.toml
6. Codex 기본값

그래서 공통 기본값은 config.toml에 두고, 프로필 파일에는 달라지는 값만 적는 게 깔끔합니다.

⚠️ 프로젝트를 신뢰하지 않음으로 표시하면 Codex는 그 저장소의 .codex/ 층을 통째로 건너뜁니다. 프로젝트 설정뿐 아니라 훅과 규칙도 함께 무시됩니다. "저장소에 설정을 넣었는데 안 먹는다"면 여기부터 보세요.

3. 자주 바꾸는 옵션

# 기본 모델
model = "gpt-5.6"

# 명령 실행 전에 물어볼지
approval_policy = "on-request"

# 샌드박스 수준
sandbox_mode = "workspace-write"

# 웹 검색 방식 (cached · indexed · live · disabled)
web_search = "cached"

# 추론에 얼마나 힘을 쓸지
model_reasoning_effort = "high"

# 말투 (friendly · pragmatic · none)
personality = "friendly"

# 로그를 남길 폴더
log_dir = "/absolute/path/to/codex-logs"

# 윈도우에서 네이티브로 돌릴 때의 샌드박스
[windows]
sandbox = "elevated"

샌드박스와 승인 정책의 조합은 codex 샌드박스 설정 글에서 따로 정리했습니다. 윈도우에서 [windows] sandbox는 elevated가 권장값이고, 관리자 권한이 없거나 설정이 실패할 때만 unelevated로 내립니다. 설치부터 막힌다면 codex cli 윈도우 설치 쪽을 보세요.

4. 파일을 안 고치고 한 번만 바꾸기 (-c)

-c(--config)는 설정 파일에서 읽었을 값을 이번 실행에만 덮어씁니다. 점으로 이어 붙여 안쪽 값도 바꿀 수 있고, 값은 TOML로 해석됩니다.

codex -c model="gpt-5.6"
codex -c shell_environment_policy.inherit=all
codex -c log_dir=./.codex-log

실제로 먹는지 눈으로 확인할 수 있습니다. 기능 스위치 목록을 뽑아 보면 값이 바뀌는 게 보입니다.

$ codex features list | grep memories
memories        stable      false

$ codex features list -c features.memories=true | grep memories
memories        stable      true

5. 기능 스위치 — [features] 표

실험적이거나 선택적인 기능은 [features] 표에서 켜고 끕니다. 명령줄로는 codex --enable 기능이름이고, 여러 개면 --enable을 여러 번 씁니다. 지금 무엇이 켜져 있는지는 codex features list로 봅니다.

[features]
memories = true
hooks = true

💡 공식 문서 표는 memories를 Experimental로 적어 두었지만, 0.153.4의 codex features list 출력에서는 stable(기본값 false)로 나옵니다. 문서와 실제 빌드가 어긋날 수 있으니 내 버전에서 직접 목록을 뽑아 보는 편이 확실합니다.

6. 설정이 안 먹을 때 — 오타부터 잡는다

가장 흔한 원인은 키 이름 오타입니다. 그런데 Codex는 기본적으로 모르는 최상위 키를 조용히 무시합니다. 에러도 안 나고 종료 코드도 0이라, 설정을 적어 놓고 "왜 안 바뀌지" 하며 한참 헤매게 됩니다.

이때 쓰는 게 --strict-config입니다. 이 버전이 모르는 항목이 있으면 그 자리에서 세워 줍니다. 일부러 없는 키를 넣고 돌려 본 결과입니다.

$ codex --strict-config exec "say hi"
Error loading config.toml:

config.toml:2:1: unknown configuration field `notarealkey`
  |
2 | notarealkey = "oops"
  | ^^^^^^^^^^^

줄 번호와 열까지 짚어 주므로 오타를 바로 찾을 수 있습니다.

값의 자료형이 틀리면 아예 안 뜬다

키 이름은 맞는데 값의 종류가 틀리면 이야기가 다릅니다. --strict-config를 안 붙여도 기동 자체가 실패합니다. [features]에 참·거짓이 아닌 문자열을 넣어 봤습니다.

Error: failed to load bootstrap configuration

Caused by:
    invalid type: string "oops", expected a boolean
    in `features`

정리하면 모르는 키는 조용히 무시, 틀린 자료형은 즉시 실패입니다. 이 차이를 알면 증상만 보고도 어느 쪽인지 짐작할 수 있습니다.

⚠️ --strict-config와 --profile은 아무 하위 명령에나 붙지 않습니다. codex --strict-config features list를 치면 `--strict-config` is not supported for `codex features`라고 거절합니다. 실행 계열 명령(codex, codex exec, codex review, codex resume, codex sandbox 등)과 codex mcp에서만 씁니다.

자주 묻는 질문 (FAQ)

Q. ~/.codex/config.toml이 없는데 고장인가요?
아닙니다. 처음에는 없는 게 정상이고, 없어도 기본값으로 잘 돕니다. 바꿀 게 생겼을 때 직접 만들면 됩니다.

Q. AGENTS.md와 config.toml은 뭐가 다른가요?
config.toml은 도구의 동작을 정합니다(모델·샌드박스·승인·기능 스위치). AGENTS.md는 프로젝트를 어떻게 다뤄야 하는지 알려 주는 설명서입니다. 자세한 건 agents.md 작성법 글을 보세요.

Q. MCP 서버도 이 파일에 적나요?
네, 설정 층을 공유합니다. 다만 codex mcp add 명령으로 추가하는 쪽이 실수가 적습니다. 등록과 확인은 codex mcp 설정 글에 정리해 두었습니다.

Q. CLI와 IDE 확장이 설정을 따로 쓰나요?
아닙니다. 같은 설정 층을 공유합니다. IDE 확장에서는 오른쪽 위 톱니바퀴 → Codex Settings → Open config.toml로 같은 파일을 열 수 있습니다.

마무리

핵심만 추리면 이렇습니다. 파일은 ~/.codex/config.toml, 우선순위는 명령줄 → 프로젝트 → 프로필 → 사용자 → 시스템 → 기본값 순서, 그리고 설정이 안 먹으면 codex --strict-config exec ...로 오타부터 잡습니다. 프로젝트 설정이 무시된다면 그 저장소를 신뢰했는지도 확인해 보세요.

옵션은 버전마다 늘고 이름도 바뀝니다. codex --version으로 내 버전을 확인하고, codex features list로 그 버전이 실제로 아는 기능 목록을 뽑아 보는 습관을 들이면 문서와 어긋나는 부분에서 시간을 덜 버립니다. 설정 말고 터미널 하위 명령과 슬래시 명령을 한눈에 보고 싶다면 codex 명령어 정리 글을 같이 보세요.

---

📚 참고 출처 (2026년 9월 7일 확인 · codex-cli 0.153.4)
· Config basics — Codex Docs
· Configuration Reference — Codex Docs