빠른 설정

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "high"
personality = "friendly"

[profiles.review]
model_reasoning_effort = "high"
web_search = "disabled"

설정 위치

사용자 설정과 프로젝트 설정을 분리해야 의도가 유지된다

사용자 공통 설정은 ~/.codex/config.toml에 두고, 저장소별 설정은 .codex/config.toml에 둡니다. 개인 취향과 팀 규칙을 한 파일에 몰아넣으면 설정 의도가 흐려지고 나중에 어디에서 어떤 값이 왔는지 추적하기 어려워집니다. "사용자 파일은 내 기본값, 프로젝트 파일은 이 저장소 규칙"이라는 기준으로 나누면 유지가 쉬워집니다. 팀이 공유해야 하는 값은 프로젝트 파일에 커밋해 공유하고, 개인 취향은 사용자 파일에 분리해 두는 것이 충돌을 줄이는 방법입니다.

우선순위 체계를 알아야 설정 충돌을 예측할 수 있다

같은 키가 여러 곳에 있으면 CLI 플래그와 --config가 가장 우선이고, 그다음 프로필, 프로젝트 설정, 사용자 설정 순으로 적용됩니다. 이 순서를 모르면 프로젝트 설정을 바꿨는데 사용자 설정이 적용되는 것처럼 보이는 혼란이 생깁니다. 값이 어디에서 오는지 확인하려면 CLI 플래그로 일회성 오버라이드를 먼저 시도해 보는 것이 빠릅니다.

설정 분리 예시
- ~/.codex/config.toml: 내가 기본으로 선호하는 모델, 말투, 웹 검색 방식
- repo/.codex/config.toml: 이 저장소에서만 허용할 샌드박스와 명령 규칙
- codex --profile review: 특정 작업에서만 더 엄격한 설정 사용

프로필은 같은 저장소에서 다른 작업 모드를 전환하는 방법이다

같은 작업을 자주 반복한다면 [profiles.<name>]으로 리뷰용, 실험용, 안전 모드 같은 프로필을 나누는 방식이 편합니다. codex --profile review처럼 실행하면 기본 설정 위에 해당 프로필의 값이 덮어씌워집니다. 리뷰 작업에서는 model_reasoning_effort = "high" + web_search = "disabled", 빠른 탐색에서는 가벼운 모델 + cached 검색으로 전환하는 식입니다. 매번 플래그를 길게 입력하지 않아도 되어 반복 작업에 효율적입니다.

자주 조정하는 키의 실질적인 의미와 선택 기준

model은 작업 복잡도와 비용 균형을 결정하고, approval_policy는 에이전트가 행동 전에 확인을 거칠지를 결정합니다. sandbox_mode는 실제로 파일과 네트워크에 무엇을 허용하는지를 정합니다. model_reasoning_effort는 높을수록 더 깊이 생각하지만 느리고 비용이 올라가므로, 탐색 단계와 최종 구현 단계에 다른 값을 쓰는 것이 좋습니다. personality는 응답 말투에 영향을 주며, 팀 공유 설정에서는 중립적인 값을 기본으로 두는 편이 낫습니다.

설정 위치를 고르는 기준
- ~/.codex/config.toml: 내 기본 모델, 말투, 검색 방식
- .codex/config.toml: 저장소 공통 규칙과 권한 기본값
- [profiles.<name>]: 같은 저장소 안 다른 작업 모드
- --config key=value: 지금 한 번만 덮어쓰기

어디서 바꿀까

주의할 점

실패 예시
- review 프로필에서 web_search = "disabled" 를 켜 둔 채 프로젝트 설정이 안 먹는다고 오해함
- 실제로는 --profile review 가 프로젝트 값을 덮어쓰고 있었음
- 대응: 값이 이상하면 CLI 플래그 > 프로필 > 프로젝트 > 사용자 순서를 먼저 확인한다