Codex 설정 우선순위와 프로필 분리
같은 설정을 바꿨는데 CLI와 다른 프로젝트의 동작이 다르다면 먼저 어떤 설정층이 선택됐는지 확인해야 합니다. 사용자 기본값, 프로젝트별 값, 한 번만 적용하는 옵션, 조직이 강제하는 요구사항은 역할이 다릅니다.
공식 문서를 참고한 비공식 한국어 가이드입니다. 설정 내용은 합성 예시이며 로딩·권한 차단의 실제 동작은 미검증입니다. 사용자 파일을 덮어쓰기 전에 기존 내용을 읽고, 팀 관리 파일인지 확인합니다.
설정이 선택되는 순서
공식 기본 문서는 기본값의 우선순위를 높은 쪽부터 CLI 옵션/--config, 신뢰된 프로젝트 설정, 선택한 프로필 파일, 사용자 설정, 클라우드 관리 기본값, 시스템 설정, 내장 기본값으로 설명합니다. 프로젝트 안에서는 루트에서 현재 디렉터리로 내려오며 가까운 .codex/config.toml이 우선합니다.
조직의 requirements.toml은 이 순위표에서 단순히 한 칸 낮은 사용자 설정이 아닙니다. 허용되는 동작을 제한하는 요구사항입니다. 사용자 override로 관리자 제한을 무력화할 수 있다고 생각하면 안 됩니다.
프로젝트를 신뢰하지 않으면 프로젝트 범위의 .codex/ 설정·훅·규칙이 로드되지 않습니다. 반면 사용자/시스템 층은 여전히 로드됩니다. 다른 사람의 저장소를 여는 것만으로 로컬 사용자 훅까지 없어지는 것은 아닙니다.
현재 프로필은 별도 파일
현재 공식 문서의 프로필은 ~/.codex/<이름>.config.toml입니다. 예전 글의 [profiles.<이름>] 테이블을 그대로 붙여 넣지 마세요. 공식 고급 설정은 0.134.0 이후 이 방식이 바뀌었다고 명시합니다.
다음은 사용자가 직접 만들고 검토할 ~/.codex/review-notes.config.toml의 작은 예시입니다.
approval_policy = "on-request"
sandbox_mode = "read-only"
web_search = "disabled"
codex --profile review-notes
이 예시는 특정 프로젝트 설정이나 강제 요구사항이 없다는 가정을 두고 있습니다. 프로필보다 프로젝트/CLI 값이 높으므로 파일 이름만 보고 최종 권한이 읽기 전용이라고 확정하지 않습니다. 실제 적용 상태를 확인한 뒤 권한 문서의 제한과 함께 판단합니다.
검색과 환경변수도 따로 점검
web_search의 cached는 캐시 결과, indexed는 검색 인덱스로 접근을 제한하는 선택, live는 최신 페이지 조회, disabled는 검색 도구 비활성화입니다. cached라고 인터넷 전체가 OS 수준에서 차단되는 것은 아닙니다. 셸·MCP·브라우저 등 다른 접근 경로의 권한을 따로 확인해야 합니다.
하위 명령에 넘길 환경변수는 shell_environment_policy로 관리합니다. 비밀값 이름에 KEY나 TOKEN이 있다는 이유만으로 항상 자동 제거된다고 가정하지 마세요. 현재 기본 문서는 ignore_default_excludes의 의미를 별도로 설명합니다. 필요한 키 이름과 전달 대상을 검토하되 값은 가이드·Git·로그에 쓰지 않습니다.
잘못된 설정을 찾는 순서
- 실행한 디렉터리와
CODEX_HOME을 확인합니다. - 사용자·프로필·프로젝트 파일에서 같은 키가 중복되는지 확인합니다.
- 정확한 버전의 공식 reference에서 키와 타입을 확인합니다. TOML의 문자열·불리언·배열을 섞지 않습니다.
- 관리 요구사항이나 신뢰 설정 때문에 로딩이 제한됐는지 확인합니다.
- 한 번에 한 설정만 바꾸고 새 세션에서 결과를 확인합니다.
샘플 설정 전체를 기본 템플릿처럼 복사하면 필요 없는 provider·hook·MCP 설정까지 들어올 수 있습니다. 구조 설명에 필요한 부분만 가져오고 공식 전체 참조에서 나머지를 확인하세요. 다음은 모델과 속도입니다.
공식 한국어 도움말: ChatGPT 플랜과 Codex에서 계정별 이용 안내를 확인할 수 있습니다. 이 글은 해당 도움말의 공식 번역이 아니며 계정 조건과 요금은 공식 안내를 우선합니다.
추가 공식 참조
다음은 관련 세부 기능과 전체 참조 문서입니다. 아래 항목은 원문 전체를 한국어로 설명하거나 실행 검증한 범위가 아닙니다. 적용 조건과 정확한 옵션은 공식 원문을 확인하세요.