config.toml 마스터: 모델·추론 강도·프로파일·프로젝트 신뢰도
설정 파일은 '프롬프트'보다 강력한 생산성 레버다
Codex를 잘 쓰는 사람들의 공통점은 프롬프트를 길게 쓰는 게 아니라, "기본값"을 잘 설계한다는 점입니다. 같은 일을 시켜도 어떤 사람은 매번 --model, -c, --sandbox, -a를 붙여야 하고, 어떤 사람은 한 줄로 끝냅니다. 차이는 대부분 ~/.codex/config.toml에 있습니다.
프롬프트는 "이번 작업"을 지시하지만, 설정 파일은 "매번 반복되는 환경과 규칙"을 고정합니다. 즉, 반복 비용을 0으로 만들고, 실수 가능성을 줄이며, 팀 내 일관성을 만듭니다.
config.toml의 레이어: 어디에 두고, 어떻게 합쳐지나
파일 위치: 사용자 기본값과 프로젝트 오버라이드
Codex의 개인 기본값은 보통 ~/.codex/config.toml에 둡니다(환경변수 CODEX_HOME을 쓰는 경우 위치가 달라질 수 있습니다).1
프로젝트별로는 레포 안에 .codex/config.toml을 두어 "이 레포에서만" 정책을 덮어쓸 수 있습니다.1
로딩 방식: 프로젝트 레이어는 '현재 위치 기준'으로 달라질 수 있다
프로젝트 설정은 단일 파일만 읽는 형태가 아니라, 현재 작업 디렉터리와 프로젝트 루트 판별 방식에 따라 적용 범위가 달라질 수 있습니다. 모노레포에서 폴더별 정책을 다르게 두고 싶다면, 어느 위치에서 codex를 실행하느냐가 곧 '어떤 프로젝트 레이어가 적용되느냐'를 결정합니다.
메모: 세부 로딩 규칙은 버전마다 바뀔 수 있습니다. 팀 표준을 만들기 전에는 한 번
codex --help(또는 공식 설정 레퍼런스)로 "프로젝트 레이어 탐색 규칙"을 확인해두는 편이 안전합니다.1
우선순위: "한 번만 바꾸고 싶다"면 어디를 만져야 하나
실무에서 유용한 우선순위 감각은 다음 정도면 충분합니다.1
CLI 플래그/
-c오버라이드--profile <name>로 선택한 프로파일config.toml(사용자/프로젝트 레이어)
Codex CLI 내장 기본값
주의: 운영체제 전역(
/etc/...) 같은 시스템 레이어가 항상 존재한다고 가정하면 오히려 혼란이 커집니다. 이 책에서는 "내가 실제로 만질 수 있는 레이어(CLI/프로파일/사용자/프로젝트)"만 기준으로 설명합니다.
모델 선택과 '추론 강도': 품질·속도·비용의 다이얼
model: 기본 모델을 박아두면 작업 시작이 빨라진다
model은 말 그대로 Codex가 사용할 모델 식별자입니다.
model = "gpt-5-codex" # 예시작업 성격이 크게 둘로 나뉜다면(빠른 잔수정 vs 깊은 설계/디버깅), 모델을 고정하기보다 프로파일로 스위칭하는 편이 낫습니다. (뒤에서 ci, paranoid 예시를 만듭니다.)
model_reasoning_effort: "생각을 얼마나" 할지
추론(Reasoning)을 지원하는 모델에서는 model_reasoning_effort로 "생각의 강도"를 정할 수 있습니다.1
값은 보통 다음 범위로 설명됩니다.
minimal(가능한 한 최소)lowmedium(기본값으로 취급되는 경우가 많음)high
설정의 핵심은 "항상 high"가 아닙니다. 기본은 medium, 깊은 문제(원인 추적, 다단계 리팩터링, 테스트 실패 루프)에서만 high 프로파일로 올리는 방식이 현실적입니다.
model_reasoning_summary: 이유를 '보여줄지'(요약 수준)
추론 요약은 모델이 내부적으로 생각한 내용을 "요약" 형태로 노출하는 옵션입니다.
model_reasoning_summary = "auto" # 기본
# model_reasoning_summary = "concise"
# model_reasoning_summary = "detailed"
# model_reasoning_summary = "none" # 요약 끄기팀에서 Codex를 리뷰 도구로도 쓴다면 detailed가 디버깅에 도움이 되지만, CI 로그나 자동화 출력에서는 오히려 소음이 될 수 있습니다. 이런 이유로 대화형 개발 프로파일과 CI 프로파일을 분리하는 편이 좋습니다.
model_verbosity: 출력 분량을 컨트롤한다
자동화(특히 codex exec)에서는 답변이 길수록 파이프라인에서 처리하기 불편해집니다. 반대로 온보딩/리뷰에서는 설명이 길수록 좋습니다. model_verbosity는 이런 출력 성향을 조정하는 손잡이입니다.
model_verbosity = "medium" # low | medium | high프로파일(profiles): 상황별 '작동 모드'를 버튼처럼
프로파일은 설정 묶음입니다. 한 파일에 여러 모드를 정의해두고, 실행할 때 --profile만 바꿔 타면 됩니다.
codex --profile ci "run tests and fix any failures"
codex --profile paranoid "review this repo for security issues"프로파일 설계 원칙: "베이스는 공통, 프로파일은 차이만"
프로파일을 많이 만들수록 관리가 어렵습니다. 따라서 루트(베이스)에는 공통만 두고, 프로파일에는 "차이"만 둡니다.
베이스: 기본 모델, 기본 승인 정책, 기본 샌드박스
프로파일: CI용(무인 실행), 안전 점검용(읽기 전용), 깊은 추론용(고추론)
추천 2종 세트: ci / paranoid
아래는 바로 복사해 시작할 수 있는 패턴입니다.
# ~/.codex/config.toml
# 1) 베이스: 평소 개발용 (안전 + 생산성의 균형)
model = "gpt-5-codex"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
model_verbosity = "medium"
# 2) 프로파일: CI/자동화용 (사람이 개입하지 않는 전제)
[profiles.ci]
approval_policy = "never"
model_verbosity = "low"
model_reasoning_summary = "none"
model_reasoning_effort = "low"
# 3) 프로파일: paranoid (최대한 보수적으로)
[profiles.paranoid]
approval_policy = "untrusted"
sandbox_mode = "read-only"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"여기서 핵심은 "자동화는 짧게, 리뷰는 자세히"입니다. 같은 작업이라도 모드가 다르면 결과물의 사용성이 달라집니다.
프로파일은 '정의'이고, 선택은 런타임이다
profile = "..."를 루트에 두면 기본 프로파일처럼 동작하지만, 보통은 명시적으로 --profile을 써서 선택하는 편이 혼란이 적습니다. 특히 CI에서는 명시가 안전합니다.
프로젝트 신뢰도(Trust): 프로젝트 설정을 '읽을지 말지'를 결정한다
프로젝트 레이어의 .codex/config.toml은 "어디서 받은 레포든 자동 적용"되면 위험할 수 있습니다. 그래서 Codex는 버전에 따라 프로젝트 설정을 신뢰(trust)한 경우에만 적용하도록 설계된 흐름을 제공합니다.12
이 구조 덕분에, 인터넷에서 받은 낯선 레포가 .codex/config.toml로 과도한 권한(예: 승인 끄기/샌드박스 완화)을 강제하는 것을 막을 수 있습니다.
실전: 팀 레포에 커밋할 .codex/config.toml 예시
팀 레포에서는 개인 취향보다 "팀이 원하는 기본 안전장치"를 고정하는 게 좋습니다.
# .codex/config.toml (레포에 커밋)
approval_policy = "on-failure"
# (가능하다면) 레포 안에서만 쓰기 허용
sandbox_mode = "workspace-write"
# 도메인이 복잡하면 기본 추론을 한 단계 올려두는 것도 방법
model_reasoning_effort = "high"Trust를 '문서로만' 두지 말고, 온보딩에 포함하라
구체 문법(예: 어떤 경로를 어떤 trust_level로 등록하는지)은 버전별로 달라질 수 있습니다. 다만 공개 이슈에서 확인되는 형태로는 다음처럼 "경로 → trust_level" 매핑을 두는 방식이 존재합니다.2
# 예시(버전별로 다를 수 있음): 특정 경로를 trusted로 등록
[projects."/path/to/your/repo"]
trust_level = "trusted"팀 온보딩 문서에는 최소한 아래 두 문장을 넣어두는 걸 권합니다.
"이 레포의
.codex/config.toml을 적용하려면 프로젝트를 trust로 등록해야 한다.""trust를 켜기 전에는 설정을 읽지 않으니, 첫 실행에서 설정이 먹지 않으면 trust부터 확인한다."
.codex/config.toml (레포에 커밋)
이 레포는 테스트/빌드가 많으니 실패 시에만 승인
approval_policy = "on-failure"
작업 디렉터리 안에서만 쓰기 허용(일반적인 개발 모드)
sandbox_mode = "workspace-write"
복잡한 도메인이라 기본 추론을 약간 올려둠
model_reasoning_effort = "high"
개인이 더 보수적으로 쓰고 싶다면 `~/.codex/config.toml`에서 덮어쓰면 됩니다. 반대로 CI는 `--profile ci`로 "무조건 짧고 자동"으로 바꿔 탑니다.
---
## 모델 프로바이더(model_providers): OpenAI 외 경로, 프록시, Azure까지
Codex는 `model_provider`로 "어디로 요청을 보낼지"를 고릅니다. 기본은 보통 `openai`지만, 프록시(예: LiteLLM), Azure, 로컬 게이트웨이 등으로 바꿀 수 있습니다.
### 가장 중요한 감각: model과 model_provider는 한 쌍이다
프로바이더를 바꿨는데 모델 이름은 그대로 두면, 실제로는 동작이 꼬일 가능성이 큽니다. 프로바이더가 기대하는 모델 네이밍이 다를 수 있기 때문입니다. 그래서 보통은 프로파일에서 둘을 함께 묶어 둡니다.
### provider 정의 예시(개념 잡기)
```toml
model = "o3"
model_provider = "openai"
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"base_url: 요청을 보낼 API의 기본 URLenv_key: 토큰을 읽을 환경변수wire_api:chat또는responses계열 프로토콜
네트워크 튜닝: 재시도/스트리밍 타임아웃은 프로바이더 블록 안에서
장시간 작업이나 불안정한 네트워크에서 "가끔 끊기는" 문제가 있으면, 프로바이더별 네트워크 옵션이 실전에서 체감이 큽니다.
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000이 값은 '품질'이 아니라 안정성을 올리는 설정입니다. CI처럼 네트워크 실패가 곧 실패로 이어지는 환경에서 특히 유용합니다.
-c/--config로 한 번만 덮어쓰기: "TOML 값"이라는 점이 포인트
가끔은 파일을 바꾸고 싶지 않습니다. 그럴 땐 -c key=value가 가장 빠릅니다.
# 이번 한 번만 모델과 추론 강도를 바꾼다
codex -c model="o3" -c model_reasoning_effort="high" "trace the root cause"여기서 중요한 점은 value가 JSON이 아니라, TOML 값으로 파싱된다는 감각입니다.
공백이 들어가는 테이블/배열은 따옴표로 감싸는 편이 안전합니다.
shell_environment_policy.include_only='["PATH", "HOME"]'처럼 "배열 자체"를 값으로 넣을 수 있습니다.
이 기능을 습관화하면, 설정 파일은 안정적으로 유지하면서도 실험은 민첩하게 할 수 있습니다.
프로젝트별 설정의 마지막 퍼즐: 환경변수 정책과 문서 로딩(운영 관점)
설정은 모델만 정하는 게 아닙니다. 운영에서 더 중요한 건 "무엇을 노출하고 무엇을 막을지"입니다.
shell_environment_policy: 비밀은 코드가 아니라 환경변수에 숨어 있다
Codex가 실행하는 명령은 당신의 쉘 환경을 일부 물려받습니다. 여기에 토큰, DB 비밀번호, 내부 엔드포인트가 들어있을 수 있습니다. 따라서 팀/회사 레포에서는 기본적으로 화이트리스트 방식을 권합니다.
[shell_environment_policy]
include_only = ["PATH", "HOME", "USER"]로컬 개발에서 필요한 변수가 생기면 프로젝트 레이어나 개인 레이어에서 점진적으로 추가합니다. "필요할 때만 열기"가 안전합니다.
project 문서(AGENTS.md 등) 로딩은 다음 챕터의 기반
Codex는 프로젝트 지시사항 문서를 특정 파일명 우선순위로 읽습니다. 이 동작은 config.toml에서 파일명 후보나 최대 바이트 같은 운영 파라미터로 제어할 수 있습니다. 다음 챕터에서 AGENTS.md를 다루기 전에, 이 장에서 기억할 것은 하나입니다.
지시사항은 문서(AGENTS.md)로, 동작 방식은 설정(config.toml)으로 분리하면 프로젝트가 커져도 유지보수가 쉬워집니다.
이 챕터의 최소 체크리스트
config.toml을 "한 번 세팅하고 잊는 파일"로 만들려면, 아래 네 가지를 결정하면 됩니다.
기본 모델과 기본 추론 강도를 정한다(
model,model_reasoning_effort).자동화와 안전 점검을 위한 프로파일 두 개를 만든다(예:
profiles.ci,profiles.paranoid).팀 레포에는
.codex/config.toml로 레포 고유 정책을 고정한다.프로젝트 신뢰(Trust)가 켜져야 프로젝트 설정이 적용될 수 있다는 점을 온보딩에 명시하고, 설정이 적용되지 않을 때의 1차 점검 항목으로 만든다.
이 네 가지가 갖춰지면, 프롬프트를 짧게 써도 Codex가 "원하는 방식으로" 움직이기 시작합니다. 다음 장에서는 이 기반 위에 AGENTS.md로 지속되는 지시사항을 설계합니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.