Codex config.toml 고급 가이드

이 문서는 Codex CLI의 모델, Provider, 권한, 저장된 세션, 토큰 사용량에 영향을 주는 ~/.codex/config.toml 설정을 설명합니다.

내용은 Codex CLI 0.146.0에서 확인했습니다. Codex는 빠르게 변경되므로 업그레이드 후에는 문서 끝의 엄격한 검증을 다시 실행하세요. 처음 설치한다면 Codex 설정부터 진행하세요.

API Key와 Bearer Token을 config.toml, 저장소, 문서 또는 셸 기록에 직접 저장하지 마세요.

품질 우선 기본 설정

품질을 우선하는 개인 개발 머신에는 다음 구성을 기준으로 사용할 수 있습니다.

model_provider = "icodeeasy"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
cli_auth_credentials_store = "file"

approval_policy = "on-request"
sandbox_mode = "danger-full-access"
personality = "pragmatic"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Codex가 ~/.codex/auth.json을 생성하고 관리하게 하세요. 환경 변수는 표준 입력을 통한 일회성 가져오기에만 사용합니다.

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

기본 도메인이 느리면 base_url을 https://jp.icodeeasy.cc 또는 https://sg.icodeeasy.cc로 변경할 수 있습니다. Provider ID는 그대로 유지하세요.

설정 위치와 우선순위

사용자 설정의 기본 경로는 ~/.codex/config.toml입니다. 우선순위는 다음과 같습니다.

1. CLI 옵션과 -c / --config 임시 재정의
2. 신뢰한 프로젝트의 .codex/config.toml
3. 선택한 ~/.codex/<name>.config.toml Profile
4. 사용자 설정
5. 시스템 설정
6. Codex 기본값

한 번만 추론 강도를 바꾸는 예:

codex -c 'model_reasoning_effort="xhigh"'

TOML 최상위 키는 첫 table보다 앞에 있어야 합니다.

model = "gpt-5.6-sol"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"

table이 시작된 뒤의 키는 다음 table이 나올 때까지 해당 table에 속합니다.

모델과 추론 강도

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

model은 활성 Provider에 전달되는 모델 식별자입니다. 선택 화면에 모델 이름이 표시된다고 해서 Provider가 모든 기능을 지원하는 것은 아닙니다. 텍스트 생성뿐 아니라 도구 호출, 스트리밍 종료 이벤트, usage도 실제로 검증하세요.

지원되는 강도는 모델마다 다릅니다. 모델 카탈로그와 Provider가 모두 지원을 확인할 때만 max 또는 ultra를 사용하세요. plan_mode_reasoning_effort는 Plan 모드에만 적용됩니다. 현재 Provider의 실제 한계를 확인하지 않았다면 model_context_window를 수동 지정하지 않는 것이 안전합니다.

Provider ID, 표시 이름, Base URL

model_provider = "icodeeasy"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

name = "OpenAI"를 name = "I Code Easy"로 바꾸면 상태 표시가 더 정확해질 뿐입니다. 품질, 속도, 인증, 캐시, 과금, 이전 세션에는 영향을 주지 않습니다.

반면 icodeeasy는 세션 메타데이터에 저장되는 Provider ID입니다. 이를 삭제하거나 바꾸면 이전 세션이 목록에 남아 있어도 재개할 때 다음 오류가 발생할 수 있습니다.

failed to load configuration: Model provider `icodeeasy` not found

새 ID가 필요하면 이전 [model_providers.icodeeasy] 정의를 호환 별칭으로 남기세요. 저장된 JSONL이나 상태 데이터베이스를 일괄 수정할 필요가 없습니다.

인증, 권한, 승인

requires_openai_auth = true이면 Codex가 OpenAI 인증 저장소를 사용합니다. 이 사이트에서는 파일 기반 자격 증명을 권장합니다.

cli_auth_credentials_store = "file"

자격 증명은 ~/.codex/auth.json에 저장됩니다. JSON을 직접 만들거나 편집하지 말고 API Key를 .bashrc, .zshrc 또는 Windows 사용자 환경 변수에 영구 저장하지 마세요. 최초 설정과 키 교체에 같은 로그인 절차를 사용합니다.

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

config.toml은 모델, Provider, Base URL, 권한 및 도구를 관리하고, auth.json은 API Key 또는 ChatGPT 로그인 자격 증명을 보관합니다. auth.json을 암호처럼 다루세요. Linux/macOS에서는 chmod 600 ~/.codex/config.toml ~/.codex/auth.json을 실행하고 Git 커밋, 공유, 공개 백업을 하지 마세요. 키 교체는 다시 로그인하고, 삭제는 codex logout을 사용합니다.

장기 환경 변수보다 shell, tmux, IDE 및 백그라운드 실행에서 자격 증명을 일관되게 찾으므로 개발 환경에서 더 안정적입니다. 하지만 네트워크, 사용량 제한 또는 모델 호환성을 개선하지는 않습니다. 저장 방식을 바꿔도 이전 Session은 숨겨지지 않습니다. 재개 호환성은 Provider ID와 로컬 Session 상태에 달려 있습니다.

Account: API key configured (run codex login to use ChatGPT)

이 문구는 오류가 아니라 ChatGPT 로그인이 아닌 API Key를 사용한다는 뜻입니다.

approval_policy = "on-request"
sandbox_mode = "danger-full-access"

sandbox_mode는 명령의 기술적 접근 범위를, approval_policy는 사용자 확인을 요청할 수 있는 시점을 결정합니다.

개발 전용 머신도 새 저장소, 의존성 스크립트, 웹 페이지, hooks, MCP 결과를 자동으로 신뢰할 수 있다는 의미는 아닙니다. 필요하면 codex -s workspace-write로 일시 제한하세요.

프로젝트 신뢰, Web Search, MCP

[projects."/absolute/path/to/repository"]
trust_level = "trusted"

신뢰한 프로젝트에서는 .codex/config.toml, hooks, rules를 읽을 수 있지만 sandbox가 자동으로 danger-full-access가 되지는 않습니다.

web_search = "live"

Web Search 모드는 cached, indexed, live, disabled입니다. 최신 기술 문서에는 live가 유용하지만 웹 콘텐츠는 신뢰할 수 없는 외부 입력으로 다루세요.

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 60

해당 MCP 없이는 작업할 수 없는 경우에만 required = true를 사용하세요. 초기화 실패가 새 thread 시작이나 재개를 막을 수 있습니다.

Profile로 속도와 안전성 분리

# ~/.codex/quick.config.toml
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

codex --profile quick

# ~/.codex/readonly.config.toml
approval_policy = "never"
sandbox_mode = "read-only"
web_search = "cached"

codex --profile readonly

Provider ID처럼 세션 호환성에 영향을 주는 값은 기본 사용자 설정에 두세요.

/status, Token, Context Window

Model:              gpt-5.6-sol (reasoning xhigh, summaries auto)
Model provider:     I Code Easy - https://api.icodeeasy.cc
Permissions:        Custom (danger-full-access, Ask for approval)
Account:            API key configured
Token usage:        708K total (679K input + 28.9K output)
Context window:     51% left (132K used / 258K)
Limits:             not available for this account

실제 요청 대상은 Provider 표시 이름이 아니라 URL로 판단합니다. Limits: not available은 현재 인증으로 ChatGPT 제한 정보를 읽을 수 없다는 뜻이며 무제한이라는 의미가 아닙니다.

긴 세션은 매번 유효한 기록을 다시 보내므로 누적 입력이 Context Window보다 클 수 있습니다. Codex 0.146.0의 표시 계산은 다음과 같습니다.

displayed input = input_tokens - cached_input_tokens
displayed total = displayed input + output_tokens

reasoning token은 output에 이미 포함되어 있으므로 다시 더하지 않습니다. 캐시된 입력도 입력 Token이며 과금은 실제 서비스 규칙에 따릅니다.

132K used / 258K가 51% left로 보이는 이유는 이 버전이 사용량과 전체 용량에서 각각 약 12K 고정 기준을 뺀 뒤 사용자가 제어할 수 있는 남은 비율을 계산하기 때문입니다.

작업 단계 경계나 컨텍스트 부족이 가까우면 /compact, 관련 없는 새 작업에는 /new를 사용하세요.

세션 재개

codex resume <session-id>
codex resume --last
codex resume --all

기본 선택기와 --last는 현재 디렉터리를 고려하고 --all은 디렉터리 전체를 검색합니다. 재개는 메시지와 세션 메타데이터를 복원하지만 종료된 프로세스를 되살리지는 않습니다. 파일, Git, 외부 서비스는 현재 실제 상태를 사용합니다.

무효 필드와 엄격한 검증

Codex 0.146.0에서는 다음 이전 필드를 설정하지 마세요.

disable_response_storage = true
preferred_auth_method = "apikey"

일반 실행은 알 수 없는 필드를 무시할 수 있습니다. 이 버전의 비 Azure Responses 요청은 이미 store = false를 사용하며 disable_response_storage로 제어되지 않습니다.

Linux / macOS:

codex --strict-config mcp-server </dev/null
codex doctor --summary --ascii

PowerShell:

"" | codex --strict-config mcp-server
codex doctor --summary --ascii

첫 명령은 알 수 없는 키를 거부하고 EOF 뒤 종료합니다. 두 번째 명령은 설치, 인증, MCP, 로컬 상태, Provider 연결을 진단합니다. TUI에서는 /status와 /debug-config로 실제 설정을 확인하세요.

참고 자료

• Codex Authentication
• Codex Configuration Reference
• Codex Advanced Configuration
• Codex CLI command reference

이 페이지는 2026-08-03에 Codex CLI 0.146.0 및 OpenAI 공식 문서와 대조했습니다.