logo

고급 구성

Provider, policy, integration을 더 세밀하게 제어해야 할 때 이 옵션을 사용합니다. 빠른 시작은 Config basics를 참고하십시오.

Project guidance, reusable capability, custom slash command, subagent workflow, integration의 배경은 Customization을 참고하십시오. 구성 key는 Configuration Reference를 참고하십시오.

Profiles

Profile은 이름이 붙은 구성 값 집합을 저장하고 CLI에서 전환할 수 있게 합니다.

Profile은 experimental이며 향후 release에서 변경되거나 제거될 수 있습니다. 현재 Codex IDE extension에서는 지원되지 않습니다.

config.toml의 [profiles.{name}] 아래에 profile을 정의한 뒤 codex --profile {name}으로 실행합니다.

model = "gpt-5.4"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"

Profile을 기본값으로 만들려면 config.toml 최상위에 profile = "deep-review"를 추가합니다. 명령줄에서 오버라이드하지 않는 한 Codex가 해당 profile을 로드합니다.

Profile은 model_catalog_json도 오버라이드할 수 있습니다. 최상위와 선택한 profile이 모두 model_catalog_json을 설정하면 Codex는 profile 값을 우선합니다.

CLI에서 일회성 오버라이드

~/.codex/config.toml을 편집하는 대신 단일 실행에 대해 CLI에서 구성을 오버라이드할 수 있습니다.

  • 전용 flag가 있으면 먼저 사용합니다. 예: --model.
  • 임의 key를 오버라이드해야 하면 -c 또는 --config를 사용합니다.

예:

# 전용 flag
codex --model gpt-5.4

# 일반 key/value 오버라이드. 값은 JSON이 아니라 TOML입니다.
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

참고:

  • Nested value는 dot notation으로 설정할 수 있습니다. 예: mcp_servers.context7.enabled=false.
  • --config 값은 TOML로 parse됩니다. 확실하지 않으면 shell이 공백에서 나누지 않도록 값을 quote하십시오.
  • 값이 TOML로 parse되지 않으면 Codex는 string으로 처리합니다.

구성과 상태 위치

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

일반적으로 볼 수 있는 파일:

  • config.toml: 로컬 구성
  • auth.json: file-based credential storage를 사용하는 경우, 또는 OS keychain/keyring
  • history.jsonl: history persistence가 활성화된 경우
  • Log와 cache 같은 기타 per-user 상태

Credential storage mode를 포함한 인증 세부 정보는 Authentication을 참고하십시오. 전체 구성 key 목록은 Configuration Reference를 참고하십시오.

저장소나 system path에 check-in하는 shared default, rule, skill은 Team Config를 참고하십시오.

내장 OpenAI provider를 LLM proxy, router, data-residency enabled project로 가리키기만 하면 된다면 새 provider를 정의하지 말고 config.toml에 openai_base_url을 설정합니다.

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

Project config file

사용자 config 외에도 Codex는 저장소 안의 .codex/config.toml에서 project-scoped override를 읽습니다. Codex는 project root에서 현재 작업 디렉터리까지 걸어 올라가며 발견한 모든 .codex/config.toml을 로드합니다. 여러 파일이 같은 key를 정의하면 현재 작업 디렉터리에 가장 가까운 파일이 우선합니다.

보안을 위해 Codex는 project가 trusted인 경우에만 project-scoped config file을 로드합니다. Project가 untrusted이면 Codex는 .codex/config.toml, project-local hook, project-local rule을 포함한 project .codex/ 계층을 무시합니다. User와 system 계층은 별도로 유지되고 계속 로드됩니다.

Project config 안의 상대 경로, 예를 들어 model_instructions_file은 해당 config.toml이 들어 있는 .codex/ 폴더 기준으로 해석됩니다.

Hooks

Codex는 활성 config layer 옆의 hooks.json 파일 또는 config.toml 안 inline [hooks] table에서 lifecycle hook을 로드할 수 있습니다.

자주 쓰는 위치:

  • ~/.codex/hooks.json
  • ~/.codex/config.toml
  • {repo}/.codex/hooks.json
  • {repo}/.codex/config.toml

Project-local hook은 project .codex/ layer가 trusted인 경우에만 로드됩니다. User-level hook은 project trust와 독립적입니다.

Hook을 켜려면 다음을 설정합니다.

[features]
codex_hooks = true

Inline TOML hook은 hooks.json과 같은 event 구조를 사용합니다.

[[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"

단일 layer에 hooks.json과 inline [hooks]가 모두 있으면 Codex는 둘 다 로드하고 경고합니다. Layer마다 하나의 표현만 사용하는 것이 좋습니다.

현재 event list, input field, output behavior, limitation은 Hooks를 참고하십시오.

Agent role

Subagent role 구성(config.toml의 [agents])은 Subagents를 참고하십시오.

Project root detection

Codex는 working directory에서 위로 올라가며 .codex/ layer와 AGENTS.md 같은 project configuration을 찾고 project root에 도달할 때까지 탐색합니다.

기본적으로 Codex는 .git이 있는 디렉터리를 project root로 취급합니다. 이 동작을 바꾸려면 config.toml에 project_root_markers를 설정합니다.

# 이 marker 중 하나를 포함한 디렉터리를 project root로 취급합니다.
project_root_markers = [".git", ".hg", ".sl"]

project_root_markers = []로 설정하면 parent directory 검색을 건너뛰고 현재 작업 디렉터리를 project root로 취급합니다.

사용자 지정 model provider

Model provider는 Codex가 모델에 연결하는 방법을 정의합니다. Base URL, wire API, authentication, optional HTTP header를 포함합니다. Custom provider는 예약된 built-in provider ID인 openai, ollama, lmstudio를 재사용할 수 없습니다.

추가 provider를 정의하고 model_provider가 해당 provider를 가리키게 합니다.

model = "gpt-5.4"
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"

필요하면 request header를 추가합니다.

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

Provider가 external credential helper에서 bearer token을 가져와야 하면 command-backed authentication을 사용합니다.

[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

Auth command는 stdin을 받지 않고 token을 stdout에 출력해야 합니다. Codex는 앞뒤 whitespace를 trim하고, empty token은 error로 처리하며, refresh_interval_ms에 따라 proactively refresh합니다. refresh_interval_ms = 0은 authentication retry 뒤에만 refresh합니다. [model_providers.{id}.auth]는 env_key, experimental_bearer_token, requires_openai_auth와 함께 사용하지 마십시오.

Amazon Bedrock provider

Codex에는 built-in amazon-bedrock model provider가 포함됩니다. Custom provider와 달리 이 built-in provider는 nested AWS profile과 region override만 지원합니다.

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

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

profile을 생략하면 Codex는 표준 AWS credential chain을 사용합니다. region은 request를 처리할 지원 Bedrock region으로 설정합니다.

OSS mode

--oss를 전달하면 Codex는 Ollama 또는 LM Studio 같은 local open source provider로 실행할 수 있습니다. Provider를 지정하지 않고 --oss만 전달하면 Codex는 oss_provider를 기본값으로 사용합니다.

oss_provider = "ollama" # 또는 "lmstudio"

Azure provider와 per-provider tuning

[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 provider의 base URL을 바꾸려면 openai_base_url을 사용합니다. Built-in provider ID는 오버라이드할 수 없으므로 [model_providers.openai]를 만들지 마십시오.

Data residency를 사용하는 ChatGPT 고객

Data residency가 활성화된 project는 올바른 prefix가 붙은 base URL을 사용하도록 model provider를 만들 수 있습니다.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1"

모델 reasoning, verbosity, limit

model_reasoning_summary = "none"          # summary 비활성화
model_verbosity = "low"                   # 응답을 짧게
model_supports_reasoning_summaries = true # reasoning 강제
model_context_window = 128000             # context window 크기

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

Approval policy와 sandbox mode

Approval strictness는 Codex가 언제 멈추는지에 영향을 주고, sandbox level은 file/network access에 영향을 줍니다.

config.toml 편집 시 고려할 operational detail은 Common sandbox and approval combinations, Protected paths in writable roots, Network access를 참고하십시오.

Granular approval policy(approval_policy = { granular = { ... } })를 사용하면 개별 prompt category를 허용하거나 자동 거절할 수 있습니다. 일부 경우에는 interactive approval을 유지하고, request_permissions나 skill-script prompt 같은 경우는 fail closed되게 만들 때 유용합니다.

적격 interactive approval request를 automatic review로 라우팅하려면 approvals_reviewer = "auto_review"를 설정합니다. 이는 reviewer를 바꾸는 것이지 sandbox boundary를 바꾸지는 않습니다.

Local reviewer policy instruction에는 [auto_review].policy를 사용합니다. Managed guardian_policy_config가 우선합니다.

approval_policy = "untrusted"
approvals_reviewer = "user"
sandbox_mode = "workspace-write"
allow_login_shell = false

# 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
exclude_slash_tmp = false
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false

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

Named permission profile

default_permissions를 설정해 sandbox profile을 이름으로 재사용할 수 있습니다. Codex에는 :read-only, :workspace, :danger-no-sandbox built-in profile이 포함됩니다.

default_permissions = ":workspace"

Custom profile은 [permissions.{name}] 아래에 정의한 이름을 default_permissions에 지정합니다.

default_permissions = "workspace"

[permissions.workspace.filesystem]
":project_roots" = { "." = "write", "**/*.env" = "none" }
glob_scan_max_depth = 3

[permissions.workspace.network]
enabled = true
mode = "limited"

[permissions.workspace.network.domains]
"api.openai.com" = "allow"

Built-in name에는 앞에 colon을 붙입니다. Custom name에는 colon을 붙이지 않으며 matching permissions table이 있어야 합니다.

Profile-scoped override와 requirement constraint를 포함한 완전한 key 목록은 Configuration Reference와 Managed configuration를 참고하십시오.

workspace-write mode에서는 나머지 workspace가 writable이어도 일부 환경에서 .git/과 .codex/가 read-only로 유지됩니다. 그래서 git commit 같은 명령이 sandbox 밖 실행 승인을 요구할 수 있습니다. 특정 명령을 건너뛰거나 차단하려면 rules를 사용합니다.

환경이 이미 process isolation을 제공할 때만 sandbox를 완전히 비활성화합니다.

sandbox_mode = "danger-full-access"

Shell environment policy

shell_environment_policy는 Codex가 시작하는 subprocess에 어떤 environment variable을 전달할지 제어합니다. inherit = "none"으로 clean start를 사용하거나 inherit = "core"로 trimmed set부터 시작한 뒤 exclude, include, override를 쌓아 secret leakage를 피하면서 task에 필요한 path, key, flag를 제공합니다.

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]

Pattern은 case-insensitive glob입니다. ignore_default_excludes = false는 사용자의 include/exclude가 적용되기 전에 KEY/SECRET/TOKEN 자동 filter를 유지합니다.

MCP servers

구성 세부 정보는 전용 MCP documentation을 참고하십시오.

Observability와 telemetry

Codex run(API request, SSE/event, prompt, tool approval/result)을 추적하려면 OpenTelemetry(OTel) log export를 활성화합니다. 기본적으로 비활성화되어 있으며 [otel]로 opt in합니다.

[otel]
environment = "staging"
exporter = "none"
log_user_prompt = false

Exporter 예:

[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는 event를 기록하지만 전송하지 않습니다. Exporter는 asynchronous batch로 동작하고 shutdown 시 flush합니다. Event metadata에는 service name, CLI version, env tag, conversation id, model, sandbox/approval setting, event별 field가 포함됩니다.

내보내는 event

대표 structured log event:

  • codex.conversation_starts: model, reasoning setting, sandbox/approval policy
  • codex.api_request: attempt, status/success, duration, error detail
  • codex.sse_event: stream event kind, success/failure, duration, response.completed token count
  • codex.websocket_request 및 codex.websocket_event: request duration, per-message kind/success/error
  • codex.user_prompt: 길이. 명시적으로 켜지 않으면 content redacted
  • codex.tool_decision: approved/denied와 decision source
  • codex.tool_result: duration, success, output snippet

OTel metric

OTel metrics pipeline이 활성화되면 Codex는 API, stream, tool activity에 대한 counter와 duration histogram을 내보냅니다. 각 metric은 기본 metadata tag인 auth_mode, originator, session_source, model, app.version를 포함합니다.

주요 metric family:

  • Runtime과 model transport: api_request, sse_event, websocket.request, websocket.event, responses_api_*, transport.fallback_to_http, remote_models.*, startup_prewarm.*, cloud_requirements.*
  • Turn과 tool activity: turn.e2e_duration_ms, turn.ttft.duration_ms, turn.token_usage, tool.call, approval.requested, mcp.call, hooks.run
  • Thread, task, feature: feature.state, thread.started, conversation.turn.count, thread.fork, thread.side, task.compact, task.review, shell_snapshot, skill.injected, plugins.startup_sync, multi_agent.spawn
  • Memory와 local state: memory.phase1, memory.phase2, memories.usage, external_agent_config.detect, external_agent_config.import, db.backfill, db.error
  • Windows sandbox: windows_sandbox.setup_success, windows_sandbox.setup_failure, windows_sandbox.setup_duration_ms, elevated setup 및 fallback prompt 관련 metric

Telemetry 관련 보안 및 개인정보 지침은 Security를 참고하십시오.

Metrics

기본적으로 Codex는 소량의 anonymous usage 및 health data를 OpenAI로 주기적으로 보냅니다. 이는 Codex가 제대로 동작하지 않는 상황을 감지하고 어떤 feature와 configuration option이 사용되는지 이해하는 데 사용됩니다. 이 metric에는 개인 식별 정보가 포함되지 않습니다. Metrics collection은 OTel log/trace export와 독립적입니다.

머신의 Codex 표면 전반에서 metric collection을 완전히 비활성화하려면 config에 analytics flag를 설정합니다.

[analytics]
enabled = false

각 metric은 자체 field와 기본 context field를 포함합니다.

기본 context field:

  • auth_mode: swic, api, unknown
  • model: 사용 모델 이름
  • app.version: Codex version

Metric catalog의 전체 목록은 Configuration Reference를 참고하십시오. tool field가 있는 metric은 apply_patch 또는 shell 같은 내부 tool을 나타내며 실제 shell command나 patch 내용은 포함하지 않습니다.

Feedback control

기본적으로 Codex는 /feedback에서 사용자가 feedback을 보낼 수 있게 합니다. 한 머신의 Codex 표면 전반에서 feedback collection을 비활성화하려면 config를 업데이트합니다.

[feedback]
enabled = false

비활성화되면 /feedback은 disabled message를 표시하고 Codex는 feedback submission을 거부합니다.

Reasoning event 숨기기 또는 표시

CI log 등에서 noisy한 "reasoning" 출력을 줄이려면 다음을 설정합니다.

hide_agent_reasoning = true

모델이 raw reasoning content를 내보낼 때 이를 표시하려면 다음을 설정합니다.

show_raw_agent_reasoning = true

Raw reasoning은 workflow에 허용 가능한 경우에만 활성화하십시오. gpt-oss 같은 일부 model/provider는 raw reasoning을 내보내지 않으며, 이 경우 설정에 visible effect가 없습니다.

Notifications

notify를 사용하면 Codex가 지원 event를 emit할 때 외부 프로그램을 실행할 수 있습니다. 현재 지원 event는 agent-turn-complete입니다. Built-in TUI notification이 다루지 않는 desktop toast, chat webhook, CI update, side-channel alerting에 유용합니다.

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())

Script는 JSON argument 하나를 받습니다. 일반 field:

  • type: 현재는 agent-turn-complete
  • thread-id: session identifier
  • turn-id: turn identifier
  • cwd: working directory
  • input-messages: 해당 turn으로 이어진 user message
  • last-assistant-message: 마지막 assistant message text

Script를 disk 어딘가에 두고 notify가 이를 가리키게 합니다.

notify와 tui.notifications

  • notify: 외부 프로그램을 실행합니다. Webhook, desktop notifier, CI hook에 적합합니다.
  • tui.notifications: TUI에 built-in되어 있고 event type으로 filter할 수 있습니다.
  • tui.notification_method: TUI가 terminal notification을 emit하는 방법을 제어합니다. auto, osc9, bel.
  • tui.notification_condition: TUI notification이 terminal이 unfocused일 때만 발생할지 always 발생할지 제어합니다.

auto mode에서 Codex는 일부 terminal이 desktop notification으로 해석하는 OSC 9 terminal escape sequence를 우선 사용하고, 아니면 BEL(\x07)로 fallback합니다.

정확한 key는 Configuration Reference를 참고하십시오.

History persistence

기본적으로 Codex는 local session transcript를 CODEX_HOME 아래, 예를 들어 ~/.codex/history.jsonl에 저장합니다. Local history persistence를 비활성화하려면 다음을 설정합니다.

[history]
persistence = "none"

History file size 상한을 두려면 history.max_bytes를 설정합니다. 파일이 상한을 넘으면 Codex는 가장 오래된 entry를 drop하고 최신 record를 유지한 채 파일을 compact합니다.

[history]
max_bytes = 104857600 # 100 MiB

Clickable citation

Terminal/editor integration이 지원한다면 Codex는 file citation을 clickable link로 렌더링할 수 있습니다. file_opener로 Codex가 사용할 URI scheme을 선택합니다.

file_opener = "vscode" # cursor, windsurf, vscode-insiders, none도 가능

예를 들어 /home/user/project/main.py:42 같은 citation은 clickable vscode://file/...:42 link로 rewritten될 수 있습니다.

Project instruction discovery

Codex는 AGENTS.md와 관련 파일을 읽고 세션 첫 턴에 제한된 양의 project guidance를 포함합니다. 두 설정이 이 동작을 제어합니다.

  • project_doc_max_bytes: 각 AGENTS.md에서 읽을 양
  • project_doc_fallback_filenames: 디렉터리 수준에 AGENTS.md가 없을 때 추가로 시도할 파일명

자세한 walkthrough는 Custom instructions with AGENTS.md를 참고하십시오.

TUI option

하위 명령 없이 codex를 실행하면 interactive terminal UI(TUI)가 시작됩니다. Codex는 [tui] 아래에 몇 가지 TUI 전용 구성을 제공합니다.

  • tui.notifications: notification 활성화/비활성화 또는 특정 type으로 제한
  • tui.notification_method: terminal notification에 auto, osc9, bel 중 선택
  • tui.notification_condition: notification이 unfocused 또는 always에서 발생할지 선택
  • tui.animations: ASCII animation과 shimmer effect 활성화/비활성화
  • tui.alternate_screen: alternate screen 사용 제어. Terminal scrollback을 유지하려면 never
  • tui.show_tooltips: welcome screen onboarding tooltip 표시 여부

tui.notification_method의 기본값은 auto입니다. 이 모드에서 Codex는 terminal이 지원하는 것으로 보이면 OSC 9 notification을 우선 사용하고, 아니면 BEL(\x07)로 fallback합니다.

전체 key 목록은 Configuration Reference를 참고하십시오.

Previous
Config 기초
Next
Config 레퍼런스