고급 설정

공급자, 정책, 통합을 세밀하게 제어하려면 이 옵션을 사용하세요. 빠르게 시작하려면 기본 설정을 참고하세요.

프로젝트 지침, 재사용 가능한 기능, 사용자 지정 슬래시 명령어, 하위 에이전트 워크플로우, 통합에 대한 배경 설명은 사용자 지정을 참고하세요. 설정 키는 설정 레퍼런스에서 확인할 수 있습니다.

Work 클라우드의 로컬 컴퓨터 액세스에 예제 적용하기

이 예제는 Codex 설정을 설명합니다. Work 클라우드에서 로컬 컴퓨터에 액세스하도록 예제를 수정하기 전에 설정 레퍼런스를 확인하세요.

• 정책 적용 범위: 로컬 액세스를 사용하는 Work와 dot의 경우, 관리형 정책을 활성화하면 지원되는 전역 정책이 공유 클라우드 오케스트레이터에 적용됩니다. 연결된 컴퓨터에는 해당 로컬 실행 요구 사항이 적용됩니다. Work 클라우드 컨테이너에는 기존 Work 클라우드 정책이 계속 적용됩니다.
• 로컬 실행: MDM 및 기존 관리형 기기 요구 사항은 에이전트 보안 정책보다 우선합니다. 기기의 시스템 요구 사항 파일은 에이전트 보안 정책보다 우선순위가 낮습니다.
• 엔터프라이즈 훅: 워크스페이스에서 이 기능을 활성화하면 관리자가 정의한 MCP 훅을 사용할 수 있습니다. 지원되는 수명 주기 이벤트와 도구 이벤트가 발생하면 클라우드 코디네이터(오케스트레이터)에서 훅이 실행됩니다. 도구를 로컬에서 실행하더라도 클라우드 오케스트레이션은 명령어 훅이나 로컬 설정 또는 플러그인에 정의된 훅을 지원하지 않습니다.
• 감사: 이러한 훅에 의존하기 전에 콜백 연결을 테스트하고, 어떤 이벤트를 수신하는지 확인하고, 실패가 작업에 미치는 영향을 점검하세요. MCP 훅은 완전한 Compliance API 감사 기록을 제공하지 않습니다.
• 기타 설정: 사용자 지정 모델 공급자와 호스트의 로컬 경로는 관리형 설정을 통해 이 기능에 전달되지 않습니다. 관리형 설정에서 네트워크 제한과 필드별 병합 규칙을 확인하세요.

지원 범위와 설정 방법은 훅을 참고하세요.

프로필

프로필을 사용하면 설정 레이어에 이름을 붙여 저장하고 CLI에서 전환할 수 있습니다. --profile profile-name을 전달하면 Codex는 ~/.codex/config.toml을 로드한 다음 그 위에 ~/.codex/profile-name.config.toml을 적용합니다. 프로필 이름에는 문자, 숫자, 하이픈, 밑줄을 사용할 수 있습니다.

프로필마다 별도의 TOML 파일을 만드세요. 프로필 파일의 최상위에 설정 키를 작성하세요. [profiles.profile-name] 아래에 중첩하지 마세요.

예제에서는 GPT-6.1 Sol을 사용합니다. 로그인한 계정이나 워크스페이스에 이 모델을 사용할 권한이 있어야 합니다. 권한이 없다면 사용 가능한 모델을 선택하세요.

1
2
3
4
5# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
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은 더 이상 [profiles.profile-name]을 config.toml에서 읽지 않으며, 최상위 profile = "profile-name" 선택자도 더 이상 지원되지 않습니다. 기존 프로필 설정을 ~/.codex/profile-name.config.toml로 옮긴 다음, 해당 [profiles.profile-name] 테이블과 profile = "profile-name" 선택자를 config.toml에서 삭제하세요.

CLI에서 한 번만 설정 재정의하기

~/.codex/config.toml을 편집하거나 CLI에서 한 번의 실행에만 적용할 설정을 지정할 수 있습니다.

• 전용 플래그가 있으면 우선 사용하세요(예: --model).
• -c / --config를 사용하면 임의의 키를 재정의할 수 있습니다.

아래 예제에서 모델을 재정의하려면 GPT-6.1 Sol 사용 권한이 있어야 합니다. 권한이 없다면 사용 가능한 모델로 바꾸세요.

1
2
3
4
5
6# Dedicated flag
codex --model gpt-6.1-sol
# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-6.1-sol"'
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(파일 기반 자격 증명 저장소를 사용하는 경우) 또는 운영 체제의 키체인/키링
• history.jsonl(기록 저장을 활성화한 경우)
• 로그, 캐시 등 기타 사용자별 상태 정보

자격 증명 저장 방식 등 인증에 관한 자세한 내용은 인증을 참고하세요. 전체 설정 키 목록은 설정 레퍼런스를 참고하세요.

레포지토리나 시스템 경로에 배치하는 공유 기본값, 규칙, 스킬에 대해서는 팀 설정을 참고하세요.

기본 제공 OpenAI 공급자를 LLM 프록시, 라우터 또는 데이터 레지던시가 활성화된 프로젝트에 연결하기만 하면 되는 경우에는 새 공급자를 정의할 필요 없이 openai_base_url을 config.toml에 설정하세요. 이렇게 하면 기본 제공 openai 공급자의 기본 URL이 바뀌며 별도의 model_providers.<id> 항목은 필요하지 않습니다.

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

프로젝트 설정 파일(.codex/config.toml)

Codex는 사용자 설정과 함께 레포지토리 안의 .codex/config.toml 파일에서 프로젝트별 재정의 값을 읽습니다. 프로젝트 루트에서 현재 작업 디렉터리까지 경로를 따라가며 발견한 .codex/config.toml을 모두 로드합니다. 여러 파일에 같은 키가 있으면 작업 디렉터리에 가장 가까운 파일의 값이 우선합니다.

보안을 위해 Codex는 신뢰할 수 있는 프로젝트에서만 프로젝트 설정 파일을 로드합니다. 신뢰할 수 없는 프로젝트에서는 프로젝트의 .codex/ 레이어를 무시합니다. 여기에는 .codex/config.toml, 프로젝트 로컬 훅, 프로젝트 로컬 규칙이 포함됩니다. 사용자 레이어와 시스템 레이어는 별도로 계속 로드됩니다.

프로젝트 설정의 상대 경로(예: model_instructions_file)는 .codex/ 폴더를 기준으로 해석됩니다. 이 폴더에는 해당 config.toml이 있습니다.

프로젝트 설정 파일에서는 자격 증명의 전달 대상을 바꾸거나, 호스트가 관리하는 앱 요청 메타데이터 또는 공급자 인증을 변경하거나, 설정 프로필을 선택하거나, 기기에서 알림 또는 텔레메트리 명령어를 실행하는 설정을 재정의할 수 없습니다. 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 파일이나 인라인 [hooks] 테이블에서 수명 주기 훅을 로드할 수 있습니다. 인라인 테이블은 해당 레이어의 config.toml 파일에 작성합니다.

훅을 설정할 때 주로 사용하는 위치는 다음 네 곳입니다.

• ~/.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 파일)

하위 에이전트 역할 설정([agents] 테이블, config.toml 파일)은 하위 에이전트를 참고하세요.

프로젝트 루트 감지

Codex는 작업 디렉터리에서 프로젝트 루트까지 상위 디렉터리를 탐색하며 프로젝트 설정(예: .codex/ 레이어 및 AGENTS.md)을 찾습니다.

기본적으로 Codex는 .git이 있는 디렉터리를 프로젝트 루트로 간주합니다. 이 동작을 변경하려면 project_root_markers를 config.toml에 설정하세요.

# 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를 선택하세요. Codex는 openai, ollama, lmstudio, amazon-bedrock, amazon-bedrock-runtime, gcp를 기본 제공 공급자용 ID로 예약해 둡니다.

공급자를 추가로 정의한 다음 model_provider에 사용할 공급자를 지정하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13model = "gpt-6.1-sol"
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" }

브라우저에서 조직의 ID 공급자로 로그인하려면 게이트웨이 기본 제공 OAuth를 사용하세요. [model_providers.<id>.gateway_oauth]에 권한 부여 URL과 토큰 URL, 공개 클라이언트 ID, 토큰 전달 방식을 설정하세요. requires_openai_auth = false로 설정해도 동작하며 ChatGPT 로그인, PowerShell, Azure CLI, 외부 자격 증명 헬퍼는 필요하지 않습니다. 게이트웨이는 설정된 쿠키 또는 사용자 지정 헤더로 전달되는 OAuth 토큰을 수락해야 합니다.

공급자 인증을 위해 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으로 입력을 받지 않으며 토큰을 표준 출력에 써야 합니다. Codex는 토큰 앞뒤의 공백을 제거하고 빈 토큰을 오류로 처리하며, refresh_interval_ms 간격으로 토큰을 미리 갱신합니다. 인증 재시도 후에만 갱신하려면 refresh_interval_ms = 0으로 설정하세요. [model_providers.<id>.auth]는 env_key, experimental_bearer_token, requires_openai_auth와 함께 사용하지 마세요.

Amazon Bedrock 공급자

model_provider 값으로 Bedrock Mantle 엔드포인트에는 amazon-bedrock을, Runtime 엔드포인트에는 amazon-bedrock-runtime을 지정하세요. Mantle에서 사용할 AWS 자격 증명과 리전은 해당 공급자의 aws 테이블에 설정하세요.

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

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

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

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

Google Cloud Vertex AI 공급자

프로젝트에서 액세스할 수 있는 Vertex AI 모델을 사용하려면 config.toml에서 기본 제공 공급자를 다음과 같이 설정하세요.

model_provider = "gcp"

[model_providers.gcp]
project_id = "my-project"
location = "global"

project_id나 location을 생략하면 Codex는 각각 GOOGLE_CLOUD_PROJECT와 GOOGLE_CLOUD_LOCATION에서 값을 읽습니다. 위치의 기본값은 global입니다.

기본 인증을 사용하려면 Codex를 실행하는 기기에 Google Cloud CLI를 설치하세요. 로컬에서 로그인하려면 gcloud auth application-default login을 실행하세요. Codex는 gcloud auth application-default print-access-token을 실행해 액세스 토큰을 가져옵니다.

특정 ADC 파일을 사용하려면 credential_file에 파일의 절대 경로를 지정하세요. 이 키는 [model_providers.gcp] 아래에 둡니다. Codex는 인증 명령어를 실행할 때 GOOGLE_APPLICATION_CREDENTIALS를 해당 경로로 설정합니다.

배포 환경에서 다른 엔드포인트, 토큰 명령어 또는 정적 헤더를 사용한다면 각각 base_url, auth 또는 http_headers를 [model_providers.gcp] 아래에 설정하세요.

OSS 모드(로컬 공급자)

--oss를 전달하면 Ollama나 LM Studio 같은 로컬 오픈 소스 공급자로 Codex를 실행할 수 있습니다. 한 번의 실행에 사용할 공급자는 --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_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"로 설정하면 대상 조건을 충족하는 대화형 승인 요청이 자동 검토로 전달됩니다. 검토자 정책을 교체하는 방법은 자동 검토 설정을 참고하세요.

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for Auto-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

이름이 있는 권한 프로필

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

전체 키 목록과 요구 사항에 따른 제약은 설정 레퍼런스와 관리형 설정을 참고하세요.

환경에서 이미 프로세스를 격리하는 경우에만 다음 설정으로 샌드박스를 완전히 비활성화하세요.

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 문서를 참고하세요.

관측 가능성 및 텔레메트리

OpenTelemetry(OTel) 로그 내보내기를 활성화하면 Codex 실행 중의 API 요청, SSE/이벤트, 프롬프트, 도구 승인 및 결과를 추적할 수 있습니다. 기본적으로 비활성화되어 있으며 [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

관리자는 requirements.toml에서 사용할 내보내기 도구와 개별 로깅 설정을 지정해 강제 적용할 수 있습니다.

내보내기 도구를 선택하세요.

[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.agent_response(otel.log_agent_responses = true일 때 주 에이전트와 생성된 하위 에이전트의 최종 답변)
• codex.guardian_assessment(otel.log_guardian_assessments = true일 때 완료된 승인 요청 자동 검토 결과)
• codex.tool_decision(승인 또는 거부 여부, 설정에 따른 결정인지 사용자가 내린 결정인지 여부)
• codex.tool_result(소요 시간, 성공 여부, 출력 일부)

기록되는 OTel 지표

OTel 지표 파이프라인을 활성화하면 Codex는 API, 스트림, 도구 활동에 대한 카운터와 소요 시간 히스토그램을 기록합니다.

아래 지표에는 모두 기본 메타데이터 태그인 auth_mode, originator, session_source, model, app.version도 포함됩니다.

텔레메트리의 보안 및 개인정보 보호에 관한 자세한 내용은 보안을 참고하세요.

지표

기본적으로 Codex는 익명화된 소량의 사용 현황 및 작동 상태 데이터를 주기적으로 OpenAI에 전송합니다. 이 데이터로 Codex가 제대로 작동하지 않는 상황을 감지하고 어떤 기능과 설정 옵션이 사용되는지 파악할 수 있어 Codex 팀이 중요한 부분에 집중할 수 있습니다. 지표에는 개인 식별 정보(PII)가 포함되지 않습니다. 지표 수집은 OTel 로그 및 트레이스 내보내기와 독립적으로 동작합니다.

분석 기능과 기본 제공 statsig 지표 내보내기 도구를 비활성화하려면 설정 파일에서 분석 플래그를 다음과 같이 설정하세요.

[analytics]
enabled = false

사용자 지정 OTLP 지표 내보내기 도구도 비활성화하려면 otel.metrics_exporter = "none"으로 설정하세요.

각 지표에는 고유 필드와 아래의 기본 컨텍스트 필드가 포함됩니다.

기본 컨텍스트 필드(모든 이벤트 및 지표에 적용)

• 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 앱의 MCP 호출이 차단되면 mcp.call에 status만 기록될 수 있습니다.

스레드, 작업 및 기능

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)는 추론 원문을 출력하지 않으므로 이 설정을 변경해도 표시되는 내용은 달라지지 않습니다.

알림

notify를 사용하면 Codex에서 지원되는 이벤트(현재는 agent-turn-complete만 지원)가 발생할 때마다 외부 프로그램을 실행할 수 있습니다. 데스크톱 팝업 알림, 채팅 웹훅, CI 업데이트 등 기본 제공 TUI 알림이 지원하지 않는 별도 채널로 알림을 보낼 때 유용합니다.

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

다음은 notify.py가 agent-turn-complete에 반응하는 예제의 일부입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35#!/usr/bin/env python3
import argparse
import json
import subprocess
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Show a Codex turn-completion notification on macOS."
    )
    parser.add_argument("notification", type=json.loads, help="Codex notification JSON")
    notification = parser.parse_args().notification
    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)를 제어합니다.

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는 인용된 파일 위치를 클릭할 수 있는 링크로 표시합니다. file_opener에 Codex가 사용할 URI 스킴을 지정하세요.

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)가 시작됩니다. [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 알림을 지원하는 것으로 판단되면 이를 우선 사용합니다. OSC 9는 일부 터미널이 데스크톱 알림으로 해석하는 이스케이프 시퀀스입니다. 지원하지 않는 경우에는 BEL(\x07)을 사용합니다.

전체 키 목록은 설정 레퍼런스를 참고하세요.