고급 구성

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

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

프로필

프로필을 사용하면 이름이 지정된 구성 계층을 저장하고 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.6-sol"
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는 활성 구성 계층 옆에 있는 config.toml 파일의 인라인 [hooks] 테이블이나 hooks.json 파일에서도 수명 주기 훅을 로드할 수 있습니다.

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

• ~/.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는 둘 다 로드하고 경고합니다. 계층마다 한 가지 표현 방식을 사용하는 것이 좋습니다.

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

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

하위 에이전트 역할 구성(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]을 만들지 마세요.

데이터 레지던시를 사용하는 API 조직

데이터 레지던시가 활성화된 상태로 생성된 프로젝트는 모델 공급자를 만들어 base_url을 올바른 접두사로 업데이트할 수 있습니다. 데이터 레지던시가 적용된 ChatGPT 워크스페이스에는 사용자 지정 공급자가 필요하지 않습니다. ChatGPT로 로그인하면 Codex가 워크스페이스 레지던시 설정을 준수합니다.

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

Codex와 ChatGPT Work는 더 이상 approval_policy = "untrusted"를 지원하지 않습니다. 지원이 종료된 untrusted 승인 정책에서 마이그레이션에서 지원되는 설정과 프로젝트를 기반으로 하는 더 엄격한 승인을 알아보세요.

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

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

적합한 대화형 승인 요청을 자동 검토를 통해 처리하려면 approvals_reviewer = "auto_review"을 설정하세요. 이렇게 하면 검토자는 변경되지만 샌드박스 경계는 변경되지 않습니다.

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

approval_policy = "on-request"  # Other options: 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를 사용하세요. 데스크톱 토스트, 채팅 웹훅, CI 업데이트 또는 내장 TUI 알림이 지원하지 않는 별도 채널의 알림에 유용합니다.

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)로 대체합니다.

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