고급 구성

공급자, 정책, 통합을 더 세밀하게 제어해야 할 때 이 옵션을 사용하세요. 빠르게 시작하려면 구성 기본 사항을 참조하세요.

프로젝트 지침, 재사용 가능한 기능, 사용자 지정 슬래시 명령, 하위 에이전트 워크플로 및 통합에 관한 배경 정보는 사용자 지정을 참조하세요. 구성 키는 구성 참조에서 확인할 수 있습니다.

프로필

프로필을 사용하면 이름이 지정된 구성 계층을 저장하고 CLI에서 해당 계층 간에 전환할 수 있습니다. --profile profile-name을 전달하면 Codex는 ~/.codex/config.toml을 로드한 다음 ~/.codex/profile-name.config.toml을 그 위에 적용합니다. 프로필 이름에는 문자, 숫자, 하이픈 및 밑줄을 사용할 수 있습니다.

각 프로필에 별도의 TOML 파일을 만드세요. 프로필 파일에서는 최상위 구성 키를 사용하고 [profiles.profile-name] 아래에 중첩하지 마세요.

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

프로필 파일은 기본 사용자 구성보다 위에 있고 프로젝트 및 CLI 구성보다 아래에 있는 계층이므로, 기본 구성과 다른 값만 포함하면 됩니다. 프로필 파일에서 model_catalog_json을 재정의할 수도 있습니다. 두 파일에 모두 이 값이 설정되어 있으면 Codex는 프로필 값을 사용합니다.

Codex 0.134.0 이상에서는 --profile이 더 이상 config.toml에서 [profiles.profile-name]을 읽지 않으며, 최상위 profile = "profile-name" 선택기도 더 이상 지원되지 않습니다. 기존 프로필 설정을 ~/.codex/profile-name.config.toml으로 옮긴 다음, config.toml에서 해당 [profiles.profile-name] 테이블과 profile = "profile-name" 선택기를 제거하세요.

CLI에서 일회성 재정의

~/.codex/config.toml을 편집하는 것 외에도 CLI에서 단일 실행에 대한 구성을 재정의할 수 있습니다.

• 전용 플래그가 있으면 이를 우선 사용하세요(예: --model).
• 임의의 키를 재정의해야 할 때는 -c / --config을 사용하세요.

예:

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

참고:

• 중첩된 값을 설정할 때 키에 점 표기법을 사용할 수 있습니다(예: mcp_servers.context7.enabled=false).
• --config 값은 TOML로 구문 분석됩니다. 확실하지 않다면 셸이 공백을 기준으로 값을 분할하지 않도록 값을 따옴표로 묶으세요.
• 값을 TOML로 구문 분석할 수 없으면 Codex는 문자열로 처리합니다.

구성 및 상태 위치

Codex는 로컬 상태를 CODEX_HOME 아래에 저장합니다(기본값: ~/.codex).

여기에서 흔히 볼 수 있는 파일은 다음과 같습니다.

• config.toml(로컬 구성)
• auth.json(파일 기반 자격 증명 저장소를 사용하는 경우) 또는 OS 키체인/키링
• history.jsonl(기록 영속성이 활성화된 경우)
• 로그 및 캐시와 같은 기타 사용자별 상태

자격 증명 저장 모드를 비롯한 인증 세부 정보는 인증을 참조하세요. 전체 구성 키 목록은 구성 참조에서 확인할 수 있습니다.

저장소나 시스템 경로에 체크인되는 공유 기본값, 규칙 및 스킬은 팀 구성을 참조하세요.

기본 제공 OpenAI 공급자가 LLM 프록시, 라우터 또는 데이터 레지던시가 활성화된 프로젝트를 가리키도록 설정하기만 하면 되는 경우에는 새 공급자를 정의하지 말고 config.toml에서 openai_base_url을 설정하세요. 이렇게 하면 별도의 model_providers.<id> 항목 없이 기본 제공 openai 공급자의 기본 URL이 변경됩니다.

openai_base_url = "https://us.api.openai.com/v1"

프로젝트 구성 파일(.codex/config.toml)

사용자 구성 외에도 Codex는 저장소 내부의 .codex/config.toml 파일에서 프로젝트 범위 재정의를 읽습니다. Codex는 프로젝트 루트에서 현재 작업 디렉터리까지 이동하며 발견한 모든 .codex/config.toml을 로드합니다. 여러 파일에서 같은 키를 정의하면 작업 디렉터리와 가장 가까운 파일이 우선합니다.

보안을 위해 Codex는 프로젝트를 신뢰하는 경우에만 프로젝트 범위 구성 파일을 로드합니다. 프로젝트를 신뢰하지 않으면 Codex는 .codex/config.toml, 프로젝트 로컬 훅 및 프로젝트 로컬 규칙을 비롯한 프로젝트 .codex/ 계층을 무시합니다. 사용자 및 시스템 계층은 별도로 유지되며 계속 로드됩니다.

프로젝트 구성 내부의 상대 경로(예: model_instructions_file)는 config.toml을 포함하는 .codex/ 폴더를 기준으로 해석됩니다.

프로젝트 구성 파일에서는 자격 증명을 리디렉션하거나, 호스트 소유 앱의 요청 메타데이터를 변경하거나, 공급자 인증을 변경하거나, 구성 프로필을 선택하거나, 머신 로컬 알림/원격 측정 명령을 실행하는 설정을 재정의할 수 없습니다. Codex는 프로젝트 로컬 .codex/config.toml에 있는 다음 키를 무시하며, 발견하면 시작 시 경고를 표시합니다. openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url 및 otel. 공급자, 알림 및 원격 측정 키는 사용자 수준 ~/.codex/config.toml에 설정하고, 구성 프로필은 --profile profile-name 및 ~/.codex/profile-name.config.toml으로 선택하세요.

훅

Codex는 활성 구성 계층 옆에 있는 hooks.json 파일 또는 config.toml 파일의 인라인 [hooks] 테이블에서도 수명 주기 훅을 로드할 수 있습니다.

실제로 가장 유용한 네 위치는 다음과 같습니다.

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

프로젝트 로컬 훅은 프로젝트 .codex/ 계층이 신뢰되는 경우에만 로드됩니다. 사용자 수준 훅은 프로젝트 신뢰 여부와 독립적으로 유지됩니다.

인라인 TOML 훅은 hooks.json과 동일한 이벤트 구조를 사용합니다.

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

단일 계층에 hooks.json과 인라인 [hooks]이 모두 있으면 Codex는 둘 다 로드하고 경고를 표시합니다. 계층마다 한 가지 표현 방식을 사용하는 것이 좋습니다.

현재 이벤트 목록, 입력 필드, 출력 동작 및 제한 사항은 훅을 참조하세요.

에이전트 역할([agents]의 config.toml)

하위 에이전트 역할 구성(config.toml의 [agents])은 하위 에이전트를 참조하세요.

프로젝트 루트 감지

Codex는 프로젝트 루트에 도달할 때까지 작업 디렉터리에서 상위로 이동하며 프로젝트 구성(예: .codex/ 계층 및 AGENTS.md)을 찾습니다.

기본적으로 Codex는 .git이 포함된 디렉터리를 프로젝트 루트로 간주합니다. 이 동작을 사용자 지정하려면 config.toml에서 project_root_markers을 설정하세요.

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

상위 디렉터리 검색을 건너뛰고 현재 작업 디렉터리를 프로젝트 루트로 처리하려면 project_root_markers = []을 설정하세요.

사용자 지정 모델 공급자

모델 공급자는 Codex가 모델에 연결하는 방식(기본 URL, 유선 API, 인증 및 선택적 HTTP 헤더)을 정의합니다. 사용자 지정 공급자는 예약된 기본 제공 공급자 ID인 openai, ollama 및 lmstudio을 재사용할 수 없습니다.

추가 공급자를 정의하고 model_provider이 이를 가리키도록 설정하세요.

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

사용자 지정 공급자가 독립 실행형 웹 검색 엔드포인트를 지원한다면 공급자 구성에 해당 기능을 명시하세요.

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

사용자 지정 공급자에서 이 설정의 기본값은 false입니다. 독립 실행형 웹 검색은 개발 중이며 기본적으로 비활성화되어 있습니다. 공급자 기능을 true으로 설정하는 것만으로는 활성화되지 않습니다. 공급자가 호환되는 엔드포인트를 지원해야 하며, 선택한 모델과 런타임도 독립 실행형 검색을 지원해야 합니다. 구성된 web_search 모드와 관리형 검색 제한도 계속 적용됩니다.

필요한 경우 요청 헤더를 추가하세요.

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

공급자에서 Codex가 외부 자격 증명 도우미를 통해 전달자 토큰을 가져와야 한다면 명령 기반 인증을 사용하세요.

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

인증 명령에는 stdin이 전달되지 않으며 토큰을 stdout에 출력해야 합니다. Codex는 앞뒤 공백을 제거하고 빈 토큰을 오류로 처리하며 refresh_interval_ms에 사전 갱신합니다. 인증 재시도 후에만 갱신하려면 refresh_interval_ms = 0을 설정하세요. [model_providers.<id>.auth]을 env_key, experimental_bearer_token 또는 requires_openai_auth과 함께 사용하지 마세요.

Amazon Bedrock 공급자

Codex에는 기본 제공 amazon-bedrock 모델 공급자가 포함되어 있습니다. 이를 model_provider으로 직접 설정하세요. 사용자 지정 공급자와 달리 이 기본 제공 공급자는 중첩된 AWS 프로필 및 리전 재정의만 지원합니다.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

profile을 생략하면 Codex는 표준 AWS 자격 증명 체인을 사용합니다. 요청을 처리할 지원 대상 Bedrock 리전을 region에 설정하세요.

전체 설정 절차, 인증 옵션, 지원 모델 및 기능 가용성은 Amazon Bedrock에서 ChatGPT Work 및 Codex 사용을 참조하세요.

OSS 모드(로컬 공급자)

--oss을 전달하면 Codex를 Ollama 또는 LM Studio와 같은 로컬 "오픈 소스" 공급자에 연결하여 실행할 수 있습니다. 단일 실행에 사용할 공급자는 --local-provider으로 선택하고, 기본값은 oss_provider으로 설정하세요. 둘 다 설정하지 않으면 대화형 CLI에서 선택하라는 메시지가 표시되며, codex exec은 오류와 함께 종료됩니다.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Azure 공급자 및 공급자별 조정

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

기본 제공 OpenAI 공급자의 기본 URL을 변경하려면 openai_base_url을 사용하세요. 기본 제공 공급자 ID는 재정의할 수 없으므로 [model_providers.openai]을 만들지 마세요.

데이터 레지던시를 사용하는 ChatGPT 고객

data residency를 활성화하여 만든 프로젝트에서는 올바른 접두사로 base_url을 업데이트하는 모델 공급자를 만들 수 있습니다.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

모델 추론, 상세도 및 제한

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity은 Responses API를 사용하는 공급자에만 적용됩니다. Chat Completions 공급자는 이 설정을 무시합니다.

승인 정책 및 샌드박스 모드

승인의 엄격도(Codex가 일시 중지하는 시점에 영향)와 샌드박스 수준(파일/네트워크 액세스에 영향)을 선택하세요.

config.toml을 편집할 때 고려해야 할 운영 세부 정보는 일반적인 샌드박스 및 승인 조합, 쓰기 가능한 루트의 보호된 경로 및 네트워크 액세스를 참조하세요.

파일 시스템과 네트워크 액세스를 함께 구성하는 베타 권한 프로필은 권한을 참조하세요.

세분화된 승인 정책(approval_policy = { granular = { ... } })을 사용하여 개별 프롬프트 범주를 허용하거나 자동으로 거부할 수도 있습니다. 일부 경우에는 일반적인 대화형 승인을 사용하되 request_permissions 또는 스킬 스크립트 프롬프트 같은 다른 경우에는 자동으로 차단되도록 하려는 경우에 유용합니다.

적격한 대화형 승인 요청이 자동 검토를 거치도록 하려면 approvals_reviewer = "auto_review"을 설정하세요. 이 설정은 검토자를 변경하며 샌드박스 경계를 변경하지 않습니다.

로컬 검토자 정책 지침에는 [auto_review].policy을 사용하세요. 관리형 guardian_policy_config이 우선합니다.

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

이름이 지정된 권한 프로필

기본 제공 프로필, 사용자 지정 프로필 구문, 전체 파일 시스템 및 네트워크 구성 모델은 권한을 참조하세요.

전체 키 목록과 요구 사항 제약 조건은 구성 참조 및 관리형 구성을 참조하세요.

샌드박스를 완전히 비활성화합니다(환경에서 프로세스를 이미 격리하는 경우에만 사용).

sandbox_mode = "danger-full-access"

셸 환경 정책

shell_environment_policy은 Codex가 생성된 명령에 전달할 환경 변수를 제어합니다. inherit = "none"을 사용하여 빈 환경에서 시작하거나 inherit = "core"을 사용하여 정리된 변수 집합을 상속하세요. 불필요한 비밀이 생성된 명령에 전달되지 않도록 명시적인 값과 키 기반 필터를 추가하세요.

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

필터 패턴은 대소문자를 구분하지 않으며 * 및 ?을 지원합니다. 일치하는 변수를 제거하려면 "exclude"을 사용하세요. 패턴 중 하나라도 "include"을 사용하면 Codex는 포함 패턴과 일치하는 변수만 유지합니다. 포함 패턴은 이미 제외된 변수를 복원하지 않습니다. 필터 키는 구성 계층 전반에서 대소문자를 구분하지 않고 병합됩니다.

ignore_default_excludes의 기본값은 true이므로 Codex는 이름에 KEY, SECRET 또는 TOKEN이 포함된 변수를 자동으로 제거하지 않습니다. 명시적 필터가 실행되기 전에 이러한 자동 제외를 적용하려면 false로 설정하세요.

Codex는 자동 제외를 먼저 적용한 다음 사용자 지정 제외, set의 값, 마지막으로 포함 패턴 허용 목록을 적용합니다. set은 제외 후에 실행되므로 제외된 변수를 복원할 수 있습니다. 포함 패턴 허용 목록은 복원된 값도 제거할 수 있습니다.

기존 exclude 및 include_only 배열은 기존 구성에서 계속 지원됩니다. 같은 구성 계층에서 두 배열 중 하나를 [shell_environment_policy.filters]과 함께 사용하지 마세요. Codex는 이 조합을 거부합니다.

MCP 서버

구성 세부 정보는 전용 MCP 문서를 참조하세요.

관측 가능성 및 원격 측정

Codex 실행(API 요청, SSE/이벤트, 프롬프트, 도구 승인/결과)을 추적하려면 OpenTelemetry(OTel) 로그 내보내기를 활성화하세요. 기본적으로 비활성화되어 있으며 [otel]을 통해 사용 설정할 수 있습니다.

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

내보내기를 선택하세요.

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

exporter = "none"이면 Codex는 이벤트를 기록하지만 아무것도 전송하지 않습니다. 내보내기는 비동기식으로 일괄 처리되며 종료 시 플러시됩니다. 이벤트 메타데이터에는 서비스 이름, CLI 버전, 환경 태그, 대화 ID, 모델, 샌드박스/승인 설정 및 이벤트별 필드가 포함됩니다(구성 참조 참조).

내보내는 항목

Codex는 실행 및 도구 사용에 관한 구조화된 로그 이벤트를 내보냅니다. 대표적인 이벤트 유형은 다음과 같습니다.

• codex.conversation_starts(모델, 추론 설정, 샌드박스/승인 정책)
• codex.api_request(시도, 상태/성공 여부, 소요 시간 및 오류 세부 정보)
• codex.sse_event(스트림 이벤트 종류, 성공/실패, 소요 시간 및 response.completed의 토큰 수)
• codex.websocket_request 및 codex.websocket_event(요청 소요 시간과 메시지별 종류/성공/오류)
• codex.user_prompt(길이, 명시적으로 활성화하지 않으면 콘텐츠는 수정 처리됨)
• codex.tool_decision(승인/거부 여부 및 결정이 구성과 사용자 중 어디에서 비롯되었는지)
• codex.tool_result(소요 시간, 성공 여부, 출력 일부)

내보내는 OTel 메트릭

OTel 메트릭 파이프라인을 활성화하면 Codex는 API, 스트림 및 도구 활동에 관한 카운터와 소요 시간 히스토그램을 내보냅니다.

아래의 각 메트릭에는 auth_mode, originator, session_source, model 및 app.version 기본 메타데이터 태그도 포함됩니다.

원격 측정과 관련된 보안 및 개인 정보 보호 지침은 보안을 참조하세요.

메트릭

기본적으로 Codex는 소량의 익명 사용량 및 상태 데이터를 OpenAI에 주기적으로 전송합니다. 이 데이터는 Codex가 올바르게 작동하지 않는 상황을 감지하고 어떤 기능과 구성 옵션이 사용되는지 파악하는 데 도움이 되므로, Codex 팀은 가장 중요한 부분에 집중할 수 있습니다. 이러한 메트릭에는 개인 식별 정보(PII)가 포함되지 않습니다. 메트릭 수집은 OTel 로그/추적 내보내기와 독립적입니다.

머신의 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램 전체에서 메트릭 수집을 완전히 비활성화하려면 구성에서 분석 플래그를 설정하세요.

[analytics]
enabled = false

각 메트릭에는 자체 필드와 아래의 기본 컨텍스트 필드가 포함됩니다.

기본 컨텍스트 필드(모든 이벤트/메트릭에 적용)

• auth_mode: swic | api | unknown.
• model: 사용한 모델의 이름.
• app.version: Codex 버전.

메트릭 카탈로그

각 메트릭에는 필수 필드와 위의 기본 컨텍스트 필드가 포함됩니다. 아래 메트릭 이름에서는 codex. 접두사를 생략했습니다. 대부분의 메트릭 이름은 codex-rs/otel/src/metrics/names.rs에 중앙화되어 있으며, 해당 파일 외부에서 내보내는 기능별 메트릭도 여기에 포함됩니다. 메트릭에 tool 필드가 있으면 사용된 내부 도구(예: apply_patch 또는 shell)를 나타내며, codex이 적용하려는 실제 셸 명령이나 패치는 포함하지 않습니다.

런타임 및 모델 전송

cloud_requirements.fetch_attempt 메트릭에는 trigger, attempt, outcome 및 status_code 필드가 포함됩니다. cloud_requirements.fetch_final 메트릭에는 trigger, outcome, reason, attempt_count 및 status_code 필드가 포함됩니다.

턴 및 도구 활동

mcp.call 및 mcp.call.duration_ms 메트릭에는 status이 포함됩니다. 일반 도구 호출 내보내기에는 tool도 포함되며, 사용 가능한 경우 connector_id 및 connector_name도 포함됩니다. 차단된 Codex Apps MCP 호출은 status만 포함하는 mcp.call을 내보낼 수 있습니다.

스레드, 작업 및 기능

shell_snapshot 메트릭에는 success이 포함되며, 실패 시에는 failure_reason도 포함됩니다.

메모리 및 로컬 상태

external_agent_config.detect 및 external_agent_config.import 메트릭에는 migration_type이 포함되며, 스킬 마이그레이션에는 skills_count도 포함됩니다.

Windows 샌드박스

Windows 설정 실패 세부 정보를 사용할 수 있는 경우 권한 상승 설정 실패 메트릭에는 code 및 message가 포함되며, 공유 설정 경로에서 내보낸 경우 originator도 포함될 수 있습니다. windows_sandbox.legacy_setup_preflight_failed 메트릭은 공유 설정 경로에서 내보낸 경우 originator를 포함하지만, 대체 프롬프트 사전 검사 실패에는 필드가 포함되지 않을 수 있습니다.

피드백 제어

기본적으로 로컬 클라이언트에서는 사용자가 /feedback에서 피드백을 보낼 수 있습니다. 한 컴퓨터의 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램 전체에서 피드백 수집을 비활성화하려면 구성을 업데이트하세요.

[feedback]
enabled = false

비활성화하면 /feedback에 비활성화 메시지가 표시되고 Codex가 피드백 제출을 거부합니다.

추론 이벤트 숨기기 또는 표시하기

노이즈가 많은 "추론" 출력(예: CI 로그)을 줄이려면 이를 숨길 수 있습니다.

hide_agent_reasoning = true

모델이 원시 추론 콘텐츠를 내보낼 때 이를 표시하려면 다음과 같이 설정하세요.

show_raw_agent_reasoning = true

워크플로에서 허용할 수 있는 경우에만 원시 추론을 활성화하세요. 일부 모델/제공자(예: gpt-oss)는 원시 추론을 내보내지 않습니다. 이 경우 이 설정은 화면에 표시되는 결과에 영향을 주지 않습니다.

알림

Codex가 지원되는 이벤트(현재는 agent-turn-complete만 해당)를 내보낼 때마다 외부 프로그램을 실행하려면 notify를 사용하세요. 기본 제공 TUI 알림으로 처리할 수 없는 데스크톱 토스트, 채팅 웹훅, CI 업데이트 또는 기타 보조 채널 알림에 유용합니다.

notify = ["python3", "/path/to/notify.py"]

agent-turn-complete에 반응하는 notify.py 예시(일부 생략):

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

스크립트는 하나의 JSON 인수를 받습니다. 일반적인 필드는 다음과 같습니다.

• type(현재 agent-turn-complete)
• thread-id(세션 식별자)
• turn-id(턴 식별자)
• cwd(작업 디렉터리)
• input-messages(해당 턴으로 이어진 사용자 메시지)
• last-assistant-message(마지막 어시스턴트 메시지 텍스트)

스크립트를 디스크의 원하는 위치에 저장하고 notify이 해당 스크립트를 가리키도록 설정하세요.

notify와 tui.notifications의 차이

• notify는 외부 프로그램을 실행합니다(웹훅, 데스크톱 알림 프로그램, CI 훅에 적합).
• tui.notifications는 TUI에 기본 제공되며 선택적으로 이벤트 유형별로 필터링할 수 있습니다(예: agent-turn-complete 및 approval-requested).
• tui.notification_method는 TUI가 터미널 알림을 내보내는 방식(auto, osc9 또는 bel)을 제어합니다.
• tui.notification_condition는 터미널이 unfocused 또는 always 상태일 때만 TUI 알림을 실행할지 제어합니다.

auto 모드에서 Codex는 OSC 9 알림(일부 터미널에서 데스크톱 알림으로 해석하는 터미널 이스케이프 시퀀스)을 우선 사용하고, 사용할 수 없으면 BEL(\x07)로 대체합니다.

정확한 키는 구성 레퍼런스를 참조하세요.

기록 유지

기본적으로 Codex는 로컬 세션 기록을 CODEX_HOME 아래에 저장합니다(예: ~/.codex/history.jsonl). 로컬 기록 유지를 비활성화하려면 다음과 같이 설정하세요.

[history]
persistence = "none"

기록 파일 크기를 제한하려면 history.max_bytes을 설정하세요. 파일이 제한을 초과하면 Codex는 가장 오래된 항목을 삭제하고 최신 레코드를 유지하면서 파일을 압축합니다.

[history]
max_bytes = 104857600 # 100 MiB

클릭 가능한 인용

이를 지원하는 터미널/편집기 통합을 사용하는 경우 Codex는 파일 인용을 클릭 가능한 링크로 렌더링할 수 있습니다. Codex에서 사용할 URI 스킴을 선택하도록 file_opener을 구성하세요.

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

예: /home/user/project/main.py:42과 같은 인용을 클릭 가능한 vscode://file/...:42 링크로 변환할 수 있습니다.

프로젝트 지침 탐색

Codex는 AGENTS.md(및 관련 파일)를 읽고 세션의 첫 번째 턴에 제한된 분량의 프로젝트 지침을 포함합니다. 다음 두 설정으로 이 동작을 제어합니다.

• project_doc_max_bytes: 각 AGENTS.md 파일에서 읽을 분량
• project_doc_fallback_filenames: 디렉터리 수준에 AGENTS.md이 없을 때 추가로 확인할 파일 이름

자세한 설명은 AGENTS.md를 사용한 사용자 지정 지침을 참조하세요.

데스크톱

이 섹션의 옵션은 ChatGPT 데스크톱 앱에만 적용됩니다.

사용자 지정 파일 핸들러 추가

사용자 수준의 ~/.codex/config.toml에서 desktop.custom_file_handlers 아래에 항목을 추가하면 ChatGPT 데스크톱 앱이 기본적으로 지원하지 않는 편집기나 내부 런처에서 파일을 열 수 있습니다. 각 항목은 앱의 연결 프로그램 메뉴에 편집기 대상을 추가합니다. command가 기존 절대 경로이거나 앱의 PATH에서 확인되는 경우 앱이 해당 대상을 표시합니다.

다음 예시는 파일을 핸들러에 전달하는 세 가지 방법을 보여 줍니다.

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

config.toml을 저장한 다음 ChatGPT 데스크톱 앱을 다시 시작하세요.

핸들러 ID는 TOML 테이블 헤더의 마지막 세그먼트입니다. 길이는 1~64자여야 하고 ASCII 문자 또는 숫자로 시작해야 하며, 나머지에는 ASCII 문자, 숫자, 마침표, 밑줄 또는 하이픈만 사용할 수 있습니다. 앱에서는 ID에 custom: 접두사를 붙여 노출합니다. 예를 들어 company_editor은 custom:company_editor이 됩니다. 마침표가 포함된 ID는 TOML이 이를 중첩 테이블로 해석하지 않도록 따옴표로 감싸세요. 예:

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

각 핸들러는 다음 필드를 지원합니다.

input 값은 args 뒤에 오는 내용을 제어합니다.

• path는 경로를 마지막 명령 인수로 추가합니다.
• json_argument는 target, path, appPath 및 location이 포함된 JSON 객체를 추가합니다. location 값은 1부터 시작하는 line 및 column 값을 가진 객체이거나 null입니다.
• json_stdin는 JSON 객체를 인수로 추가하는 대신 표준 입력에 씁니다. 이 객체에는 hostConfig, remoteWorkspaceRoot 및 remotePath도 포함되며, 해당되지 않는 경우 이러한 필드는 null입니다.

예를 들어 사용자가 특정 소스 위치를 열면 company_editor는 다음 인수를 받을 수 있습니다.

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

사용자 지정 핸들러를 기본 편집기로 선택하면 기본 제공 편집기를 선택할 때와 같은 방식으로 선택 사항이 유지되며, 여기에는 프로젝트별 설정도 포함됩니다.

TUI 옵션

하위 명령 없이 codex을 실행하면 대화형 터미널 UI(TUI)가 시작됩니다. Codex는 [tui] 아래에 다음을 포함한 일부 TUI 전용 구성을 제공합니다.

• tui.notifications: 알림 활성화/비활성화(또는 특정 유형으로 제한)
• tui.notification_method: 터미널 알림에 사용할 auto, osc9 또는 bel 선택
• tui.notification_condition: 알림이 실행되는 시점에 사용할 unfocused 또는 always 선택
• tui.animations: ASCII 애니메이션 및 쉬머 효과 활성화/비활성화
• tui.alternate_screen: 대체 화면 사용 제어(터미널 스크롤백을 유지하려면 never로 설정)
• tui.show_tooltips: 시작 화면에서 온보딩 도구 설명 표시 또는 숨기기

tui.notification_method의 기본값은 auto입니다. auto 모드에서 Codex는 터미널이 지원하는 것으로 판단되면 OSC 9 알림(일부 터미널에서 데스크톱 알림으로 해석하는 터미널 이스케이프 시퀀스)을 우선 사용하고, 사용할 수 없으면 BEL(\x07)로 대체합니다.

전체 키 목록은 구성 레퍼런스를 참조하세요.