For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색

추천 검색어

맞춤 설정

구성 파일

에이전트 구성

ChatGPT와 Codex 확장

Linux

Windows

API Dashboard
ChatGPT 사용해 보기

구성 참조 자료

Codex config.toml 및 requirements.toml 전체 참조 자료

이 페이지에서 Codex 구성 파일에 대한 참조 정보를 검색할 수 있습니다. 개념 설명과 예시는 기본 구성과 고급 구성부터 살펴보세요.

config.toml

사용자 수준 구성은 ~/.codex/config.toml에 저장됩니다. .codex/config.toml 파일에 프로젝트 범위의 재정의를 추가할 수도 있습니다. Codex는 사용자가 프로젝트를 신뢰할 때만 프로젝트 범위 구성 파일을 로드합니다.

프로젝트 범위 구성에서는 머신 로컬 공급자, 인증, 호스트가 관리하는 앱 요청 메타데이터, 알림, 구성 프로필 선택, 텔레메트리 라우팅 키를 재정의할 수 없습니다. Codex는 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 파일에 있으면 무시합니다. 공급자, 알림, 텔레메트리 키는 사용자 수준 구성에 넣으세요. 구성 프로필 파일은 config.toml 파일과 같은 디렉터리의 $CODEX_HOME/profile-name.config.toml에 저장됩니다. --profile profile-name 옵션으로 원하는 프로필을 선택하세요.

샌드박스 및 승인 키(approval_policy, sandbox_mode, sandbox_workspace_write.*)에 대해서는 이 참조 자료와 샌드박스 및 승인, 쓰기 가능한 루트의 보호된 경로, 네트워크 액세스를 함께 참고하세요. 베타 권한 프로필은 권한을 참고하세요.

Key
agents
Type / Values
table
Details
멀티 에이전트 설정과 사용자 지정 역할 선언입니다. 스칼라 설정 이름은 예약되어 있어 사용자 지정 역할 이름으로 사용할 수 없습니다.
Key
agents.<name>.config_file
Type / Values
string (path)
Details
해당 역할의 TOML 구성 레이어 경로입니다. 상대 경로는 역할을 선언한 구성 파일을 기준으로 해석됩니다.
Key
agents.<name>.description
Type / Values
string
Details
해당 유형의 에이전트를 선택하고 생성할 때 Codex에 표시되는 역할 지침입니다.
Key
agents.default_subagent_model
Type / Values
string
Details
생성할 에이전트의 기본 모델입니다. 생성 시 모델을 명시하면 해당 모델이 우선합니다.
Key
agents.default_subagent_reasoning_effort
Type / Values
string
Details
생성할 에이전트의 기본 추론 수준입니다. 생성 시 추론 수준을 명시하면 해당 값이 우선합니다.
Key
agents.enabled
Type / Values
boolean
Details
멀티 에이전트 도구를 활성화하거나 비활성화합니다(기본값: true).
Key
agents.interrupt_message
Type / Values
boolean
Details
에이전트 턴이 중단될 때 모델이 볼 수 있는 메시지를 기록합니다(기본값: true).
Key
agents.max_concurrent_threads_per_session
Type / Values
number
Details
생성된 에이전트 스레드 중 동시에 열어 둘 수 있는 최대 개수입니다. 주 스레드는 제외합니다. 설정하지 않으면 Codex가 기본값을 선택합니다.
Key
agents.max_threads
Type / Values
number
Details
agents.max_concurrent_threads_per_session의 레거시 별칭입니다.
Key
allow_login_shell
Type / Values
boolean
Details
셸 기반 도구에서 로그인 셸 동작을 사용하도록 허용합니다. 기본값은 true입니다. false로 설정하면 login = true 요청이 거부되고, login을 생략하면 기본적으로 비로그인 셸을 사용합니다.
Key
analytics.enabled
Type / Values
boolean
Details
이 머신 또는 프로필의 분석 기능을 활성화하거나 비활성화합니다. 설정하지 않으면 클라이언트 기본값이 적용됩니다.
Key
approval_policy
Type / Values
untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }
Details
명령어를 실행하기 전에 Codex가 승인을 기다리며 일시 중지하는 시점을 제어합니다. approval_policy = { granular = { ... } }를 사용하면 다른 프롬프트는 대화형으로 유지하면서 특정 프롬프트 범주를 허용하거나 자동으로 거부할 수도 있습니다. on-failure는 사용 중단 예정(deprecated)입니다. 대화형 실행에는 on-request, 비대화형 실행에는 never를 사용하세요.
Key
approval_policy.granular.mcp_elicitations
Type / Values
boolean
Details
true로 설정하면 MCP 유도 프롬프트가 자동으로 거부되지 않고 표시되도록 허용합니다.
Key
approval_policy.granular.request_permissions
Type / Values
boolean
Details
true로 설정하면 request_permissions 도구의 프롬프트 표시를 허용합니다.
Key
approval_policy.granular.rules
Type / Values
boolean
Details
true로 설정하면 execpolicy의 prompt 규칙에 따른 승인 요청 표시를 허용합니다.
Key
approval_policy.granular.sandbox_approval
Type / Values
boolean
Details
true로 설정하면 샌드박스 권한 상승 승인 프롬프트 표시를 허용합니다.
Key
approval_policy.granular.skill_approval
Type / Values
boolean
Details
true로 설정하면 스킬 스크립트 승인 프롬프트 표시를 허용합니다.
Key
approvals_reviewer
Type / Values
user | auto_review
Details
on-request 또는 세분화된 승인 정책에서 검토 대상 승인 프롬프트를 검토할 주체입니다. 기본값은 user이며, auto_review는 검토자 하위 에이전트를 사용합니다. 이 설정은 샌드박스 적용 방식을 변경하지 않으며, 샌드박스 내에서 이미 허용된 작업을 검토하지도 않습니다.
Key
apps._default.approvals_reviewer
Type / Values
user | auto_review
Details
앱별 재정의가 없을 때 앱 도구 승인 프롬프트에 적용되는 기본 검토자입니다. 생략하면 앱은 최상위 approvals_reviewer 값을 상속합니다.
Key
apps._default.default_tools_approval_mode
Type / Values
auto | prompt | writes | approve
Details
앱별 또는 도구별 재정의가 없는 앱 도구의 기본 승인 동작입니다.
Key
apps._default.destructive_enabled
Type / Values
boolean
Details
destructive_hint = true인 앱 도구의 기본 허용/거부 설정입니다.
Key
apps._default.enabled
Type / Values
boolean
Details
앱별 재정의가 없을 때 모든 앱에 적용되는 기본 활성화 상태입니다.
Key
apps._default.open_world_enabled
Type / Values
boolean
Details
open_world_hint = true인 앱 도구의 기본 허용/거부 설정입니다.
Key
apps.<id>.approvals_reviewer
Type / Values
user | auto_review
Details
이 앱의 도구 승인 프롬프트를 검토할 주체입니다. apps._default.approvals_reviewer를 재정의합니다.
Key
apps.<id>.default_tools_approval_mode
Type / Values
auto | prompt | writes | approve
Details
도구별 재정의가 없을 때 이 앱의 도구에 적용되는 기본 승인 동작입니다.
Key
apps.<id>.default_tools_enabled
Type / Values
boolean
Details
도구별 재정의가 없을 때 이 앱의 도구에 적용되는 기본 활성화 상태입니다.
Key
apps.<id>.destructive_enabled
Type / Values
boolean
Details
이 앱에서 destructive_hint = true를 명시한 도구를 허용하거나 차단합니다.
Key
apps.<id>.enabled
Type / Values
boolean
Details
ID를 기준으로 특정 앱/커넥터를 활성화하거나 비활성화합니다(기본값: true).
Key
apps.<id>.open_world_enabled
Type / Values
boolean
Details
이 앱에서 open_world_hint = true를 명시한 도구를 허용하거나 차단합니다.
Key
apps.<id>.tools.<tool>.approval_mode
Type / Values
auto | prompt | writes | approve
Details
개별 앱 도구의 승인 동작 재정의입니다.
Key
apps.<id>.tools.<tool>.enabled
Type / Values
boolean
Details
개별 앱 도구의 활성화 상태 재정의입니다(예: repos/list).
Key
auto_review.policy
Type / Values
string
Details
자동 검토에 적용할 로컬 Markdown 정책 지침입니다. 관리형 guardian_policy_config가 우선합니다. 빈 값은 무시됩니다.
Key
background_terminal_max_timeout
Type / Values
number
Details
빈 입력으로 수행하는 write_stdin 폴링(백그라운드 터미널 폴링)의 최대 대기 시간(밀리초)입니다. 기본값은 300000(5분)이며, 기존 background_terminal_timeout 키를 대체합니다.
Key
chatgpt_base_url
Type / Values
string
Details
ChatGPT 로그인 플로우에서 사용하는 기본 URL을 재정의합니다.
Key
check_for_update_on_startup
Type / Values
boolean
Details
시작할 때 Codex 업데이트를 확인합니다(업데이트를 중앙에서 관리하는 경우에만 false로 설정하세요).
Key
cli_auth_credentials_store
Type / Values
file | keyring | auto
Details
CLI가 캐시된 자격 증명을 저장할 위치를 제어합니다(auth.json 파일 또는 OS 키체인).
Key
compact_prompt
Type / Values
string
Details
대화 기록의 컨텍스트 압축 프롬프트를 인라인으로 재정의합니다.
Key
computer_use.windows.always_allowed_app_ids
Type / Values
array<string>
Details
컴퓨터 사용 기능에서 프롬프트 없이 열 수 있는 Windows 앱의 식별자입니다. 목록에 없는 앱은 승인이 필요합니다. 저장된 항목은 ChatGPT 데스크톱 앱의 컴퓨터 사용 설정에서 삭제하세요.
Key
default_permissions
Type / Values
string
Details
샌드박스에서 실행되는 도구 호출에 적용할 기본 권한 프로필의 이름입니다. 기본 제공 프로필은 :read-only, :workspace, :danger-full-access이며, 사용자 지정 프로필 이름에는 일치하는 [permissions.<name>] 테이블이 필요합니다. sandbox_mode 또는 [sandbox_workspace_write]와 함께 사용하지 마세요.
Key
desktop.custom_file_handlers.<id>
Type / Values
table
Details
사용자 수준에서만 설정할 수 있습니다. ChatGPT 데스크톱 앱의 다음에서 열기 대상을 추가로 정의합니다. 예시와 핸들러 ID 제약 조건은 사용자 지정 파일 핸들러 추가를 참조하세요.
Key
desktop.custom_file_handlers.<id>.args
Type / Values
array<string>
Details
명령어와 파일 입력 사이에 삽입할 인수입니다(기본값: []).
Key
desktop.custom_file_handlers.<id>.command
Type / Values
string
Details
감지하고 실행할 실행 파일의 경로 또는 명령어 이름입니다. 필수 항목입니다.
Key
desktop.custom_file_handlers.<id>.icon
Type / Values
string
Details
핸들러 아이콘에 사용할 번들 에셋 경로, Base64로 인코딩된 data:image/... URL, 파일 URI 또는 로컬 절대 경로입니다. 필수 항목이며, 지원되지 않는 소스에는 기본 VS Code 아이콘이 사용됩니다.
Key
desktop.custom_file_handlers.<id>.input
Type / Values
path | json_argument | json_stdin
Details
앱이 파일 입력을 핸들러로 전송하는 방식입니다(기본값: path).
Key
desktop.custom_file_handlers.<id>.label
Type / Values
string
Details
다음에서 열기 메뉴에 표시되는 이름입니다. 필수 항목입니다.
Key
desktop.custom_file_handlers.<id>.supports_ssh
Type / Values
boolean
Details
SSH 워크스페이스의 파일에도 이 핸들러를 제공합니다(기본값: false).
Key
developer_instructions
Type / Values
string
Details
세션에 추가되는 개발자 지침입니다(선택 사항).
Key
disable_paste_burst
Type / Values
boolean
Details
TUI에서 버스트 붙여넣기 감지를 비활성화합니다.
Key
experimental_compact_prompt_file
Type / Values
string (path)
Details
컨텍스트 압축 프롬프트의 재정의 내용을 파일에서 로드합니다(실험적).
Key
experimental_use_unified_exec_tool
Type / Values
boolean
Details
통합 실행을 활성화하는 레거시 이름입니다. [features].unified_exec 또는 codex --enable unified_exec 사용을 권장합니다.
Key
features.apps
Type / Values
boolean
Details
앱(커넥터) 통합을 활성화합니다(안정화됨, 기본적으로 활성화). 앱 및 커넥터 트래픽은 샌드박스 내 명령어에 적용되는 네트워크 프록시나 해당 프록시의 도메인 허용 목록으로 제어되지 않습니다.
Key
features.code_mode.direct_only_tool_namespaces
Type / Values
array<string>
Details
코드 모드에서 직접 도구 호출로만 사용할 수 있는 도구 네임스페이스입니다.
Key
features.code_mode.enabled
Type / Values
boolean
Details
코드 모드 기능 구성을 활성화합니다. 이 기능은 개발 중이며 기본적으로 비활성화되어 있습니다.
Key
features.code_mode.excluded_tool_namespaces
Type / Values
array<string>
Details
코드 모드가 중첩 코드 모드의 도구 안내와 실행기 노출 대상에서 제외하는 도구 네임스페이스입니다.
Key
features.enable_request_compression
Type / Values
boolean
Details
지원되는 경우 스트리밍 요청 본문을 zstd로 압축합니다(안정화된 기능, 기본적으로 활성화).
Key
features.fast_mode
Type / Values
boolean
Details
TUI에서 모델 카탈로그의 서비스 등급을 선택할 수 있도록 합니다. 활성 모델이 Fast 등급 명령어 지원을 명시하면 해당 명령어도 사용할 수 있습니다(안정화된 기능, 기본적으로 활성화).
Key
features.goals
Type / Values
boolean
Details
목표 저장과 자동 이어서 진행을 활성화합니다(안정화된 기능, 기본적으로 활성화).
Key
features.hooks
Type / Values
boolean
Details
hooks.json 또는 인라인 [hooks] 구성에서 불러온 라이프사이클 훅을 활성화합니다. features.codex_hooks는 사용 중단 예정(deprecated)인 별칭입니다.
Key
features.memories
Type / Values
boolean
Details
메모리를 활성화합니다(기본적으로 비활성화됨).
Key
features.multi_agent
Type / Values
boolean
Details
멀티 에이전트 협업 도구(spawn_agent, send_input, resume_agent, wait_agent, close_agent)를 활성화합니다(안정화된 기능, 기본적으로 활성화됨).
Key
features.network_proxy
Type / Values
boolean | table
Details
샌드박스에서 실행되는 명령어의 네트워크 프록시를 시작합니다(실험적 기능, 기본적으로 비활성화). 활성화된 관리자 관리형 experimental_network 요구 사항이 프록시를 시작하는 경우를 제외하면, 권한 프로필의 도메인 규칙을 적용하려면 이 설정이 필요합니다. domains와 같은 기능 수준의 정책 옵션을 설정할 때는 테이블 형식을 사용하세요. 웹 검색, 앱, MCP 또는 기타 호스팅 도구는 필터링하지 않습니다.
Key
features.network_proxy.allow_local_binding
Type / Values
boolean
Details
로컬/사설 네트워크에 대한 더 광범위한 액세스를 허용합니다. 기본값은 false이지만, 정확한 로컬 IP 리터럴이나 localhost를 허용하는 규칙으로 특정 로컬 대상에 대한 액세스를 허용할 수 있습니다.
Key
features.network_proxy.allow_upstream_proxy
Type / Values
boolean
Details
환경에 설정된 업스트림 프록시를 통한 체이닝을 허용합니다. 기본값은 true입니다.
Key
features.network_proxy.dangerously_allow_all_unix_sockets
Type / Values
boolean
Details
허용 목록으로 액세스를 제한하는 대신 임의의 Unix 소켓 대상에 대한 액세스를 허용합니다. 기본값은 false이며, 엄격하게 통제되는 환경에서만 사용하세요.
Key
features.network_proxy.dangerously_allow_non_loopback_proxy
Type / Values
boolean
Details
루프백이 아닌 리스너 주소를 허용합니다. 기본값은 false이며, 활성화하면 프록시 리스너가 로컬호스트 외부에 노출될 수 있습니다.
Key
features.network_proxy.domains
Type / Values
map<string, allow | deny>
Details
샌드박스 네트워킹의 도메인 정책입니다. 기본적으로 설정되어 있지 않으므로 allow 규칙을 추가하기 전에는 외부 대상이 허용되지 않습니다. 정확히 일치하는 호스트, 하위 도메인만 허용하는 *.example.com, 루트 도메인과 하위 도메인을 허용하는 **.example.com, 전체에 적용되는 * 허용 규칙을 지원합니다. *는 공용 네트워크에 대한 아웃바운드 액세스를 광범위하게 허용하므로 범위를 제한한 규칙을 사용하는 것이 좋습니다. 차단할 대상에는 deny 규칙을 추가하세요. 규칙이 충돌하면 deny가 우선합니다.
Key
features.network_proxy.enable_socks5
Type / Values
boolean
Details
SOCKS5를 사용할 수 있도록 합니다. 기본값은 true입니다.
Key
features.network_proxy.enable_socks5_udp
Type / Values
boolean
Details
SOCKS5를 통한 UDP 사용을 허용합니다. 기본값은 true입니다.
Key
features.network_proxy.enabled
Type / Values
boolean
Details
명령어의 네트워크 액세스가 활성화된 경우 샌드박스에서 실행되는 명령어의 네트워크 프록시를 시작합니다. 기본값은 false이며, 프록시가 비활성화된 동안에는 권한 프로필의 도메인 규칙이 적용되지 않습니다.
Key
features.network_proxy.proxy_url
Type / Values
string
Details
샌드박스 네트워킹용 HTTP 리스너 URL입니다. 기본값은 "http://127.0.0.1:3128"입니다.
Key
features.network_proxy.socks_url
Type / Values
string
Details
SOCKS5 리스너 URL입니다. 기본값은 "http://127.0.0.1:8081"입니다.
Key
features.network_proxy.unix_sockets
Type / Values
map<string, allow | deny>
Details
샌드박스 네트워킹의 Unix 소켓 정책입니다. 기본적으로 설정되어 있지 않습니다. 허용할 소켓에는 allow 항목을 추가하세요.
Key
features.personality
Type / Values
boolean
Details
성격 선택 기능을 활성화합니다(안정화된 기능, 기본적으로 활성화).
Key
features.prevent_idle_sleep
Type / Values
boolean
Details
턴이 실행되는 동안 컴퓨터가 절전 모드로 전환되지 않도록 합니다(실험적 기능, 기본적으로 비활성화).
Key
features.remote_plugin
Type / Values
boolean
Details
원격 플러그인 카탈로그를 활성화합니다(안정화된 기능, 기본적으로 활성화).
Key
features.rollout_budget.enabled
Type / Values
boolean
Details
롤아웃 예산 추적을 활성화합니다. 이 기능은 개발 중이며 기본적으로 비활성화되어 있습니다. 활성화하면 features.rollout_budget.limit_tokens가 필요합니다.
Key
features.rollout_budget.limit_tokens
Type / Values
integer
Details
롤아웃 예산 추적에 사용할 0보다 큰 토큰 한도입니다. 롤아웃 예산을 활성화하면 필수입니다.
Key
features.rollout_budget.prefill_token_weight
Type / Values
number
Details
롤아웃 예산 계산에서 프리필 토큰에 적용하는 배율입니다. 0 이상의 유한한 값이어야 하며 기본값은 1.0입니다.
Key
features.rollout_budget.reminder_interval_tokens
Type / Values
integer
Details
롤아웃 예산 알림 사이의 0보다 큰 토큰 간격입니다. 기본값은 limit_tokens의 10%이며 최솟값은 토큰 1개입니다.
Key
features.rollout_budget.sampling_token_weight
Type / Values
number
Details
롤아웃 예산 계산에서 샘플링된 토큰에 적용하는 배율입니다. 0 이상의 유한한 값이어야 하며 기본값은 1.0입니다.
Key
features.shell_snapshot
Type / Values
boolean
Details
반복 명령어의 실행 속도를 높이기 위해 셸 환경의 스냅샷을 생성합니다(안정화된 기능, 기본적으로 활성화됨).
Key
features.shell_tool
Type / Values
boolean
Details
명령어를 실행하는 기본 shell 도구를 활성화합니다(안정화된 기능, 기본적으로 활성화).
Key
features.skill_mcp_dependency_install
Type / Values
boolean
Details
스킬에 필요한 MCP 종속성이 없을 때 설치 여부를 묻고 설치할 수 있도록 허용합니다(안정화된 기능, 기본적으로 활성화).
Key
features.unified_exec
Type / Values
boolean
Details
PTY 기반 통합 exec 도구를 사용합니다(안정화된 기능, Windows를 제외하고 기본적으로 활성화됨).
Key
features.web_search
Type / Values
boolean
Details
사용 중단 예정(deprecated)인 레거시 토글입니다. 최상위 web_search 설정을 사용하는 것이 좋습니다.
Key
features.web_search_cached
Type / Values
boolean
Details
사용 중단 예정(deprecated)인 레거시 토글입니다. web_search가 설정되어 있지 않으면 true는 web_search = "cached"로 매핑됩니다.
Key
features.web_search_request
Type / Values
boolean
Details
사용 중단 예정(deprecated)인 레거시 토글입니다. web_search가 설정되어 있지 않으면 true는 web_search = "live"로 매핑됩니다.
Key
feedback.enabled
Type / Values
boolean
Details
모든 로컬 클라이언트에서 /feedback을 통한 피드백 제출을 활성화합니다(기본값: true).
Key
file_opener
Type / Values
vscode | vscode-insiders | windsurf | cursor | none
Details
Codex 출력의 인용을 열 때 사용하는 URI 스킴입니다(기본값: vscode).
Key
forced_chatgpt_workspace_id
Type / Values
string (uuid)
Details
ChatGPT 로그인을 특정 워크스페이스 식별자로 제한합니다.
Key
forced_login_method
Type / Values
chatgpt | api
Details
특정 인증 방식만 사용하도록 Codex를 제한합니다.
Key
hide_agent_reasoning
Type / Values
boolean
Details
TUI와 codex exec 출력 모두에서 추론 이벤트를 표시하지 않습니다.
Key
history.max_bytes
Type / Values
number
Details
설정하면 가장 오래된 항목부터 삭제해 기록 파일의 크기를 지정된 바이트 수 이내로 제한합니다.
Key
history.persistence
Type / Values
save-all | none
Details
Codex가 세션 기록을 history.jsonl에 저장할지 제어합니다.
Key
hooks
Type / Values
table
Details
config.toml에서 인라인으로 구성하는 라이프사이클 훅입니다. hooks.json과 동일한 이벤트 스키마를 사용합니다. 예시와 지원되는 이벤트는 훅 가이드를 참조하세요.
Key
hooks.<Event>
Type / Values
array<table>
Details
PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit, Stop과 같은 훅 이벤트의 매처 그룹입니다.
Key
hooks.<Event>[].hooks
Type / Values
array<table>
Details
매처 그룹의 훅 핸들러입니다. 명령어 훅과 MCP 도구 훅을 지원하며, 프롬프트 및 에이전트 훅 핸들러는 파싱 후 건너뜁니다.
Key
hooks.<Event>[].hooks[].additionalContextLimit
Type / Values
integer
Details
크기가 너무 큰 additionalContext를 디스크에 저장하고 모델에는 더 짧은 미리보기를 표시하기 위한 핸들러별 대략적인 토큰 임곗값입니다. 기본값은 2500이며 0이면 전체 컨텍스트를 모델에 직접 전달합니다. 대용량 훅 출력을 참조하세요.
Key
hooks.<Event>[].hooks[].async
Type / Values
boolean
Details
훅을 트리거한 작업을 지연시키지 않고 명령어 훅을 백그라운드에서 실행합니다. 기본값은 false이며 SessionEnd는 항상 동기식으로 실행됩니다. 백그라운드에서 훅 실행을 참조하세요.
Key
hooks.<Event>[].hooks[].commandWindows
Type / Values
string
Details
명령어 훅에서 사용할 Windows 전용 명령어 재정의입니다. TOML 별칭 command_windows도 사용할 수 있습니다.
Key
instructions
Type / Values
string
Details
향후 사용을 위해 남겨둔 설정입니다. 가급적 model_instructions_file 또는 AGENTS.md를 사용하세요.
Key
log_dir
Type / Values
string (path)
Details
Codex가 로그 파일을 쓰는 디렉터리입니다. 기본값은 $CODEX_HOME/log입니다. 명시적으로 설정하면 옵트인 방식의 일반 텍스트 TUI 로그 codex-tui.log도 활성화되어 해당 디렉터리에 기록됩니다.
Key
mcp_oauth_callback_port
Type / Values
integer
Details
MCP OAuth 로그인에 사용하는 로컬 HTTP 콜백 서버의 전역 고정 포트를 선택적으로 지정합니다. 서버별 oauth.callback_port가 우선합니다. 둘 다 설정하지 않으면 Codex가 OS에서 선택한 임시 포트에 바인딩합니다.
Key
mcp_oauth_callback_url
Type / Values
string
Details
MCP OAuth 로그인에 사용할 기본 콜백 URL을 선택적으로 지정합니다(예: devbox 인그레스 URL). 인가 서버가 발급자 식별을 지원하면 새로 추가된 사전 등록 클라이언트는 이 URL을 그대로 사용하며, 저장된 콜백이 없는 기존 클라이언트는 서버별 콜백 ID를 덧붙입니다. 발급자 식별을 지원하지 않는 경우, 사전 등록된 MCP 서버에 설정된 콜백에 필수 ID가 없으면 이 URL에 ID를 덧붙인 주소를 대신 사용합니다. 콜백 URL의 포트는 리스너 포트를 결정하지 않습니다.
Key
mcp_oauth_credentials_store
Type / Values
auto | file | keyring
Details
MCP OAuth 자격 증명을 저장할 때 우선 사용할 저장소입니다.
Key
mcp_servers.<id>.args
Type / Values
array<string>
Details
MCP stdio 서버 명령어에 전달하는 인수입니다.
Key
mcp_servers.<id>.auth
Type / Values
oauth | chatgpt
Details
구성된 베어러 토큰과 권한 부여 헤더 다음 순서로 사용하는 MCP HTTP 서버의 대체 인증 방식입니다. oauth(기본값)는 저장된 MCP OAuth 자격 증명이 있으면 이를 사용합니다. chatgpt는 신뢰할 수 있는 자사 ChatGPT 오리진에 현재 ChatGPT 세션을 사용하며, 이를 사용할 수 없으면 저장된 OAuth 자격 증명을 사용합니다. 두 모드 모두 어느 소스에서도 자격 증명을 얻을 수 없으면 인증 없이 연결할 수 있습니다.
Key
mcp_servers.<id>.bearer_token_env_var
Type / Values
string
Details
MCP HTTP 서버의 베어러 토큰을 제공하는 환경 변수입니다.
Key
mcp_servers.<id>.command
Type / Values
string
Details
MCP stdio 서버를 시작하는 명령어입니다.
Key
mcp_servers.<id>.cwd
Type / Values
string
Details
MCP stdio 서버 프로세스의 작업 디렉터리입니다.
Key
mcp_servers.<id>.default_tools_approval_mode
Type / Values
auto | prompt | writes | approve
Details
도구별 재정의가 없을 때 이 서버의 MCP 도구에 적용되는 기본 승인 동작입니다.
Key
mcp_servers.<id>.disabled_tools
Type / Values
array<string>
Details
MCP 서버에서 enabled_tools 다음에 적용되는 거부 목록입니다.
Key
mcp_servers.<id>.enabled
Type / Values
boolean
Details
구성을 제거하지 않고 MCP 서버를 비활성화합니다.
Key
mcp_servers.<id>.enabled_tools
Type / Values
array<string>
Details
MCP 서버가 노출하는 도구 이름의 허용 목록입니다.
Key
mcp_servers.<id>.env
Type / Values
map<string,string>
Details
MCP stdio 서버에 전달하는 환경 변수입니다.
Key
mcp_servers.<id>.env_http_headers
Type / Values
map<string,string>
Details
환경 변수에서 값을 가져오는 MCP HTTP 서버용 HTTP 헤더입니다.
Key
mcp_servers.<id>.env_vars
Type / Values
array<string | { name = string, source = "local" | "remote" }>
Details
MCP stdio 서버에 추가로 허용할 환경 변수입니다. 문자열 항목의 기본값은 source = "local"입니다. source = "remote"는 실행기 기반 원격 stdio에서만 사용하세요.
Key
mcp_servers.<id>.experimental_environment
Type / Values
local | remote
Details
MCP 서버의 실험적 배치 설정입니다. remote는 원격 실행기 환경을 통해 stdio 서버를 시작합니다. streamable HTTP의 원격 배치는 구현되지 않았습니다.
Key
mcp_servers.<id>.http_headers
Type / Values
map<string,string>
Details
각 MCP HTTP 요청에 포함되는 정적 HTTP 헤더입니다.
Key
mcp_servers.<id>.oauth_resource
Type / Values
string
Details
MCP 로그인 시 포함할 수 있는 선택적 RFC 8707 OAuth 리소스 매개변수입니다.
Key
mcp_servers.<id>.oauth.callback_port
Type / Values
integer
Details
이 MCP 서버의 고정 OAuth 콜백 리스너 포트입니다. mcp_oauth_callback_port를 재정의합니다. 직접 루프백 콜백을 사용하고 URL에 포트를 명시했다면 리스너 포트도 동일하게 설정하세요.
Key
mcp_servers.<id>.oauth.callback_url
Type / Values
string
Details
서버별 OAuth 콜백입니다. 사전 등록된 클라이언트는 발급자 식별이 지원되거나 URL이 이미 서버별 콜백 ID로 끝나면 이 콜백을 재사용합니다. 그렇지 않으면 Codex는 전역 콜백 또는 기본 콜백에 해당 ID를 덧붙여 사용합니다. 사전 등록된 ID가 없는 클라이언트는 클라이언트 등록 시 이 콜백을 사용합니다.
Key
mcp_servers.<id>.oauth.client_id
Type / Values
string
Details
이 MCP 서버에서 권한 부여와 토큰 교환에 사용하는 사전 등록된 OAuth 클라이언트 ID입니다.
Key
mcp_servers.<id>.required
Type / Values
boolean
Details
true이면 활성화된 이 MCP 서버를 초기화할 수 없을 때 시작 또는 재개에 실패합니다.
Key
mcp_servers.<id>.scopes
Type / Values
array<string>
Details
해당 MCP 서버에서 인증할 때 요청하는 OAuth 범위입니다.
Key
mcp_servers.<id>.startup_timeout_ms
Type / Values
number
Details
startup_timeout_sec의 밀리초 단위 별칭입니다.
Key
mcp_servers.<id>.startup_timeout_sec
Type / Values
number
Details
MCP 서버의 기본 시작 제한 시간인 10초를 재정의합니다.
Key
mcp_servers.<id>.tool_timeout_sec
Type / Values
number
Details
MCP 서버의 도구별 기본 제한 시간인 60초를 재정의합니다.
Key
mcp_servers.<id>.tools.<tool>.approval_mode
Type / Values
auto | prompt | writes | approve
Details
이 서버의 특정 MCP 도구에 적용할 승인 동작 재정의입니다.
Key
mcp_servers.<id>.url
Type / Values
string
Details
MCP streamable HTTP 서버의 엔드포인트입니다.
Key
memories.consolidation_model
Type / Values
string
Details
전역 메모리 통합에 사용할 모델을 재정의하는 선택적 설정입니다.
Key
memories.disable_on_external_context
Type / Values
boolean
Details
true이면 MCP 도구 호출, 웹 검색 또는 도구 검색과 같은 외부 컨텍스트를 사용하는 스레드는 메모리 생성에서 제외됩니다. 기본값은 false입니다. 레거시 별칭: memories.no_memories_if_mcp_or_web_search.
Key
memories.extract_model
Type / Values
string
Details
스레드별 메모리 추출에 사용할 모델을 재정의하는 선택적 설정입니다.
Key
memories.generate_memories
Type / Values
boolean
Details
false이면 새로 생성된 스레드를 메모리 생성용 입력으로 저장하지 않습니다. 기본값은 true입니다.
Key
memories.max_raw_memories_for_consolidation
Type / Values
number
Details
전역 통합을 위해 유지하는 최근 원시 메모리의 최대 개수입니다. 기본값은 256이며 최대 4096으로 제한됩니다.
Key
memories.max_rollout_age_days
Type / Values
number
Details
메모리 생성 대상으로 고려할 스레드의 최대 경과 기간입니다. 기본값은 30이며 0~`90` 범위로 제한됩니다.
Key
memories.max_rollouts_per_startup
Type / Values
number
Details
시작 시 한 번에 처리하는 롤아웃 후보의 최대 개수입니다. 기본값은 16이며 최대 128로 제한됩니다.
Key
memories.max_unused_days
Type / Values
number
Details
메모리가 마지막으로 사용된 후 통합 대상에서 제외되기까지의 최대 일수입니다. 기본값은 30이며 0~`365` 범위로 제한됩니다.
Key
memories.min_rate_limit_remaining_percent
Type / Values
number
Details
메모리 생성을 시작하는 데 필요한 Codex 요청 한도의 기간별 최소 잔여 비율(%)입니다. 기본값은 25이며 0~`100` 범위로 제한됩니다.
Key
memories.min_rollout_idle_hours
Type / Values
number
Details
스레드를 메모리 생성 대상으로 고려하기 전 필요한 최소 유휴 시간입니다. 기본값은 6이며 1~`48` 범위로 제한됩니다.
Key
memories.use_memories
Type / Values
boolean
Details
false이면 Codex가 이후 세션에 기존 메모리를 포함하지 않습니다. 기본값은 true입니다.
Key
model
Type / Values
string
Details
사용할 모델입니다(예: gpt-5.5).
Key
model_auto_compact_token_limit
Type / Values
number
Details
대화 기록의 자동 컨텍스트 압축을 시작하는 토큰 임계값입니다(설정하지 않으면 모델 기본값 사용).
Key
model_auto_compact_token_limit_scope
Type / Values
total | body_after_prefix
Details
자동 컨텍스트 압축 임계값을 계산할 때 활성 컨텍스트 전체(total, 기본값)를 포함할지, 이어받은 컨텍스트 압축 윈도우의 접두사 이후 증가분(body_after_prefix)만 포함할지 제어합니다.
Key
model_catalog_json
Type / Values
string (path)
Details
시작 시 로드할 JSON 모델 카탈로그의 경로입니다(선택 사항). 선택한 $CODEX_HOME/profile-name.config.toml 프로필 파일에서 프로필별로 이 경로를 재정의할 수 있습니다.
Key
model_context_window
Type / Values
number
Details
활성 모델에서 사용할 수 있는 컨텍스트 윈도우의 토큰 수입니다.
Key
model_instructions_file
Type / Values
string (path)
Details
AGENTS.md가 아니라 기본 제공 지침을 대체합니다.
Key
model_provider
Type / Values
string
Details
model_providers의 공급자 ID입니다(기본값: openai).
Key
model_providers.<id>
Type / Values
table
Details
사용자 지정 제공자 정의입니다. 기본 제공자 ID(openai, ollama, lmstudio)는 예약되어 있어 재정의할 수 없습니다.
Key
model_providers.<id>.auth
Type / Values
table
Details
사용자 지정 제공자의 명령어 기반 베어러 토큰 구성입니다. env_key, experimental_bearer_token, requires_openai_auth와 함께 사용하지 마세요.
Key
model_providers.<id>.auth.args
Type / Values
array<string>
Details
토큰 명령어에 전달하는 인수입니다.
Key
model_providers.<id>.auth.command
Type / Values
string
Details
Codex에 베어러 토큰이 필요할 때 실행할 명령어입니다. 이 명령어는 토큰을 stdout에 출력해야 합니다.
Key
model_providers.<id>.auth.cwd
Type / Values
string (path)
Details
토큰 명령어의 작업 디렉터리입니다.
Key
model_providers.<id>.auth.refresh_interval_ms
Type / Values
number
Details
Codex가 토큰을 선제적으로 갱신하는 주기(밀리초)입니다(기본값: 300000). 인증 재시도 후에만 갱신하려면 0으로 설정하세요.
Key
model_providers.<id>.auth.timeout_ms
Type / Values
number
Details
토큰 명령어의 최대 실행 시간(밀리초)입니다(기본값: 5000).
Key
model_providers.<id>.base_url
Type / Values
string
Details
모델 제공자의 API 기본 URL입니다.
Key
model_providers.<id>.env_http_headers
Type / Values
map<string,string>
Details
환경 변수가 있으면 해당 변수 값으로 채우는 HTTP 헤더입니다.
Key
model_providers.<id>.env_key
Type / Values
string
Details
제공자의 API 키를 제공하는 환경 변수입니다.
Key
model_providers.<id>.env_key_instructions
Type / Values
string
Details
선택적으로 지정할 수 있는 제공자 API 키 설정 안내입니다.
Key
model_providers.<id>.experimental_bearer_token
Type / Values
string
Details
제공자에 직접 지정하는 베어러 토큰입니다(권장하지 않으며, env_key를 사용하세요).
Key
model_providers.<id>.http_headers
Type / Values
map<string,string>
Details
제공자 요청에 추가되는 고정 HTTP 헤더입니다.
Key
model_providers.<id>.name
Type / Values
string
Details
사용자 지정 모델 제공자의 표시 이름입니다.
Key
model_providers.<id>.query_params
Type / Values
map<string,string>
Details
제공자 요청에 추가되는 쿼리 매개변수입니다.
Key
model_providers.<id>.request_max_retries
Type / Values
number
Details
제공자에 보내는 HTTP 요청의 재시도 횟수입니다(기본값: 4).
Key
model_providers.<id>.requires_openai_auth
Type / Values
boolean
Details
제공자가 OpenAI 인증을 사용할지 여부입니다(기본값: false).
Key
model_providers.<id>.stream_idle_timeout_ms
Type / Values
number
Details
SSE 스트림의 유휴 제한 시간(밀리초)입니다(기본값: 300000).
Key
model_providers.<id>.stream_max_retries
Type / Values
number
Details
SSE 스트리밍 중단 시 재시도 횟수입니다(기본값: 5).
Key
model_providers.<id>.supports_standalone_web_search
Type / Values
boolean
Details
호환되는 독립형 웹 검색 엔드포인트를 지원한다고 표시합니다(기본값: false). 독립형 검색은 아직 개발 중이며 기본적으로 비활성화되어 있습니다. 제공자가 호환된다는 것만으로는 이 기능이 활성화되지 않습니다.
Key
model_providers.<id>.supports_websockets
Type / Values
boolean
Details
해당 제공자가 Responses API WebSocket 전송 방식을 지원하는지 여부입니다.
Key
model_providers.<id>.wire_api
Type / Values
responses
Details
제공자가 사용하는 프로토콜입니다. 지원되는 값은 responses뿐이며, 생략하면 이 값이 기본값으로 사용됩니다.
Key
model_providers.amazon-bedrock.aws.profile
Type / Values
string
Details
기본 제공 amazon-bedrock 제공자가 사용하는 AWS 프로필 이름입니다.
Key
model_providers.amazon-bedrock.aws.region
Type / Values
string
Details
기본 제공 amazon-bedrock 제공자가 사용하는 AWS 리전입니다.
Key
model_reasoning_effort
Type / Values
minimal | low | medium | high | xhigh
Details
지원되는 모델의 추론 수준을 조정합니다(Responses API에서만 사용 가능하며, xhigh 지원 여부는 모델에 따라 다름).
Key
model_reasoning_summary
Type / Values
auto | concise | detailed | none
Details
추론 요약의 상세 수준을 선택하거나 요약을 완전히 비활성화합니다.
Key
model_supports_reasoning_summaries
Type / Values
boolean
Details
Codex의 추론 메타데이터 전송 여부를 강제로 지정합니다.
Key
model_verbosity
Type / Values
low | medium | high
Details
GPT-5 Responses API의 응답 상세도를 선택적으로 재정의합니다. 설정하지 않으면 선택한 모델/프리셋의 기본값을 사용합니다.
Key
notice.hide_full_access_warning
Type / Values
boolean
Details
전체 권한 경고 프롬프트의 확인 여부를 기록합니다.
Key
notice.hide_gpt-5.1-codex-max_migration_prompt
Type / Values
boolean
Details
gpt-5.1-codex-max 마이그레이션 프롬프트의 확인 여부를 기록합니다.
Key
notice.hide_gpt5_1_migration_prompt
Type / Values
boolean
Details
GPT-5.1 마이그레이션 프롬프트의 확인 여부를 기록합니다.
Key
notice.hide_rate_limit_model_nudge
Type / Values
boolean
Details
요청 한도에 따른 모델 전환 알림을 끄기로 선택했는지 기록합니다.
Key
notice.hide_world_writable_warning
Type / Values
boolean
Details
Windows에서 모든 사용자가 쓸 수 있는 디렉터리에 대한 경고를 확인했는지 기록합니다.
Key
notice.model_migrations
Type / Values
map<string,string>
Details
사용자가 확인한 모델 마이그레이션을 old->new 매핑으로 기록합니다.
Key
notify
Type / Values
array<string>
Details
알림을 위해 호출되는 명령어로, Codex에서 JSON 페이로드를 받습니다.
Key
openai_base_url
Type / Values
string
Details
기본 제공 openai 모델 공급자의 기본 URL을 재정의합니다.
Key
oss_provider
Type / Values
lmstudio | ollama
Details
--oss로 실행할 때 사용하는 기본 로컬 공급자입니다(설정하지 않으면 선택 프롬프트 표시).
Key
otel.environment
Type / Values
string
Details
내보내는 OpenTelemetry 이벤트에 적용되는 환경 태그입니다(기본값: dev).
Key
otel.exporter
Type / Values
none | otlp-http | otlp-grpc
Details
OpenTelemetry 익스포터를 선택하고 엔드포인트 메타데이터를 지정합니다.
Key
otel.exporter.<id>.endpoint
Type / Values
string
Details
OTEL 로그 익스포터의 엔드포인트입니다.
Key
otel.exporter.<id>.headers
Type / Values
map<string,string>
Details
OTEL 익스포터 요청에 포함되는 정적 헤더입니다.
Key
otel.exporter.<id>.protocol
Type / Values
binary | json
Details
OTLP/HTTP 익스포터에서 사용하는 프로토콜입니다.
Key
otel.exporter.<id>.tls.ca-certificate
Type / Values
string
Details
OTEL 익스포터의 TLS에 사용할 CA 인증서 경로입니다.
Key
otel.exporter.<id>.tls.client-certificate
Type / Values
string
Details
OTEL 익스포터의 TLS에 사용할 클라이언트 인증서 경로입니다.
Key
otel.exporter.<id>.tls.client-private-key
Type / Values
string
Details
OTEL 익스포터의 TLS에 사용할 클라이언트 개인 키 경로입니다.
Key
otel.log_user_prompt
Type / Values
boolean
Details
사용자 프롬프트 원문을 OpenTelemetry 로그와 함께 내보내도록 명시적으로 허용합니다.
Key
otel.metrics_exporter
Type / Values
none | statsig | otlp-http | otlp-grpc
Details
OpenTelemetry 메트릭 익스포터를 선택합니다(기본값: statsig).
Key
otel.trace_exporter
Type / Values
none | otlp-http | otlp-grpc
Details
OpenTelemetry 트레이스 익스포터를 선택하고 엔드포인트 메타데이터를 지정합니다.
Key
otel.trace_exporter.<id>.endpoint
Type / Values
string
Details
OTEL 로그의 트레이스 익스포터 엔드포인트입니다.
Key
otel.trace_exporter.<id>.headers
Type / Values
map<string,string>
Details
OTEL 트레이스 익스포터 요청에 포함되는 정적 헤더입니다.
Key
otel.trace_exporter.<id>.protocol
Type / Values
binary | json
Details
OTLP/HTTP 트레이스 익스포터에서 사용하는 프로토콜입니다.
Key
otel.trace_exporter.<id>.tls.ca-certificate
Type / Values
string
Details
OTEL 트레이스 익스포터의 TLS에 사용할 CA 인증서 경로입니다.
Key
otel.trace_exporter.<id>.tls.client-certificate
Type / Values
string
Details
OTEL 트레이스 익스포터의 TLS에 사용할 클라이언트 인증서 경로입니다.
Key
otel.trace_exporter.<id>.tls.client-private-key
Type / Values
string
Details
OTEL 트레이스 익스포터의 TLS에 사용할 클라이언트 개인 키 경로입니다.
Key
permissions.<name>.description
Type / Values
string
Details
이름이 지정된 이 프로필을 사람이 이해할 수 있도록 작성한 설명입니다. 프로필은 extends를 통해 상위 프로필의 설명을 상속하지 않습니다.
Key
permissions.<name>.extends
Type / Values
string
Details
이름이 지정된 이 프로필에 앞서 적용할 상위 프로필입니다(선택 사항). 이름이 지정된 다른 프로필, :read-only 또는 :workspace로 설정하세요. :danger-full-access, 정의되지 않은 상위 프로필, 순환 참조는 허용되지 않습니다.
Key
permissions.<name>.filesystem
Type / Values
table
Details
이름이 지정된 파일 시스템 권한 프로필입니다. 각 키는 절대 경로 또는 :minimal, :workspace_roots 같은 특수 토큰입니다.
Key
permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>
Type / Values
"read" | "write" | "deny"
Details
실제 적용되는 각 워크스페이스 루트를 기준으로 설정하는 파일 시스템 접근 범위입니다. 루트 자체에는 "."을 사용하세요. "**/*.env" 같은 glob 하위 경로에 "deny"를 설정해 읽기를 거부할 수 있습니다.
Key
permissions.<name>.filesystem.<path-or-glob>
Type / Values
"read" | "write" | "deny" | table
Details
경로, glob 패턴 또는 특수 토큰에 대한 직접 접근을 허용하거나 중첩 항목의 범위를 해당 루트 아래로 지정합니다. 일치하는 경로의 읽기를 거부하려면 "deny"를 사용하세요.
Key
permissions.<name>.filesystem.glob_scan_max_depth
Type / Values
number
Details
샌드박스가 시작되기 전에 일치 결과의 스냅샷을 생성하는 플랫폼에서 읽기 거부 glob 패턴을 확장할 최대 깊이입니다. 설정할 때는 1 이상이어야 합니다.
Key
permissions.<name>.network.allow_local_binding
Type / Values
boolean
Details
샌드박스 네트워킹을 통한 더 넓은 범위의 로컬/사설 네트워크 접근을 허용합니다. 이 설정이 false여도 정확한 로컬 IP 리터럴이나 localhost를 지정한 허용 규칙으로 특정 로컬 대상에 대한 접근을 허용할 수 있습니다.
Key
permissions.<name>.network.allow_upstream_proxy
Type / Values
boolean
Details
샌드박스 네트워킹에서 다른 업스트림 프록시를 경유하도록 허용합니다.
Key
permissions.<name>.network.dangerously_allow_all_unix_sockets
Type / Values
boolean
Details
기본 허용 범위에 한정하지 않고 임의의 Unix 소켓 대상을 허용합니다. 엄격하게 통제되는 환경에서만 사용하세요.
Key
permissions.<name>.network.dangerously_allow_non_loopback_proxy
Type / Values
boolean
Details
샌드박스 네트워킹 리스너가 루프백이 아닌 주소에 바인딩하도록 허용합니다. 활성화하면 리스너가 로컬호스트 외부에 노출될 수 있습니다.
Key
permissions.<name>.network.domains
Type / Values
table
Details
샌드박스에서 실행하는 명령어에 적용되는 도메인 규칙입니다. features.network_proxy 또는 활성화된 관리자 지정 네트워킹 요구 사항이 프록시를 활성화하는 경우에만 적용됩니다. 정확히 일치하는 호스트, *.example.com, **.example.com, 전역 * 허용 규칙을 지원하며, deny가 우선합니다. 웹 검색, 앱, MCP 서버는 제한하지 않습니다.
Key
permissions.<name>.network.domains.<pattern>
Type / Values
allow | deny
Details
정확히 일치하는 호스트 또는 *.example.com, **.example.com 같은 범위가 지정된 와일드카드 패턴을 허용하거나 거부합니다.
Key
permissions.<name>.network.enable_socks5
Type / Values
boolean
Details
이 권한 프로필에서 샌드박스 네트워킹을 활성화할 때 SOCKS5 기능을 제공합니다.
Key
permissions.<name>.network.enable_socks5_udp
Type / Values
boolean
Details
활성화하면 SOCKS5 리스너를 통한 UDP를 허용합니다.
Key
permissions.<name>.network.enabled
Type / Values
boolean
Details
이 권한 프로필에서 명령어의 네트워크 접근을 활성화합니다. 이 설정만으로는 네트워크 프록시가 시작되지 않습니다. features.network_proxy가 활성화되지 않았고 관리자가 설정한 네트워킹 요구 사항도 활성화되지 않은 경우, 명령어는 네트워크에 직접 접근하며 프로필의 도메인 규칙은 적용되지 않습니다.
Key
permissions.<name>.network.mode
Type / Values
limited | full
Details
하위 프로세스 트래픽에 사용하는 네트워크 프록시 모드입니다.
Key
permissions.<name>.network.proxy_url
Type / Values
string
Details
이 권한 프로필에서 샌드박스 네트워킹을 활성화할 때 사용하는 HTTP 리스너 URL입니다.
Key
permissions.<name>.network.socks_url
Type / Values
string
Details
이 권한 프로필에서 사용하는 SOCKS5 프록시 엔드포인트입니다.
Key
permissions.<name>.network.unix_sockets
Type / Values
table
Details
샌드박스 네트워킹의 Unix 소켓 허용 목록을 재정의합니다. 소켓 경로를 키로 사용하세요. allow는 경로를 추가하고 deny는 거부합니다.
Key
permissions.<name>.network.unix_sockets.<path>
Type / Values
allow | deny
Details
allow로 Unix 소켓의 절대 경로를 실제 적용되는 허용 목록에 추가하거나 deny로 거부합니다. 거부된 항목은 실제 적용되는 허용 목록에서 제외됩니다.
Key
permissions.<name>.workspace_roots
Type / Values
table
Details
프로필에서 정의한 워크스페이스 루트입니다. 세션의 런타임 워크스페이스 루트와 함께 :workspace_roots 파일 시스템 규칙이 적용됩니다.
Key
permissions.<name>.workspace_roots.<path>
Type / Values
boolean
Details
true이면 해당 경로를 프로필의 워크스페이스 루트 집합에 포함합니다. 비활성화된 항목은 적용되지 않습니다.
Key
personality
Type / Values
none | friendly | pragmatic
Details
supportsPersonality 지원을 명시하는 모델의 기본 커뮤니케이션 스타일입니다. 스레드나 턴별로 또는 /personality를 통해 재정의할 수 있습니다.
Key
plan_mode_reasoning_effort
Type / Values
none | minimal | low | medium | high | xhigh
Details
플랜 모드 전용 추론 설정 재정의입니다. 설정하지 않으면 플랜 모드에 내장된 프리셋의 기본값이 적용됩니다.
Key
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode
Type / Values
auto | prompt | writes | approve
Details
플러그인이 제공하는 MCP 서버의 도구에 적용되는 기본 승인 동작입니다.
Key
plugins.<plugin>.mcp_servers.<server>.disabled_tools
Type / Values
array<string>
Details
플러그인이 제공하는 MCP 서버에서 enabled_tools 다음에 적용되는 거부 목록입니다.
Key
plugins.<plugin>.mcp_servers.<server>.enabled
Type / Values
boolean
Details
플러그인 매니페스트를 변경하지 않고 설치된 플러그인에 포함된 MCP 서버를 활성화하거나 비활성화합니다.
Key
plugins.<plugin>.mcp_servers.<server>.enabled_tools
Type / Values
array<string>
Details
플러그인이 제공하는 MCP 서버에서 노출하는 도구의 허용 목록입니다.
Key
plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode
Type / Values
auto | prompt | writes | approve
Details
플러그인이 제공하는 MCP 도구의 승인 동작을 도구별로 재정의합니다.
Key
project_doc_fallback_filenames
Type / Values
array<string>
Details
AGENTS.md가 없을 때 추가로 확인할 파일 이름입니다.
Key
project_doc_max_bytes
Type / Values
number
Details
프로젝트 지침을 만들 때 AGENTS.md에서 읽을 최대 바이트 수입니다.
Key
project_root_markers
Type / Values
array<string>
Details
프로젝트 루트를 식별하는 파일 이름 목록입니다. 상위 디렉터리에서 프로젝트 루트를 검색할 때 사용됩니다.
Key
projects.<path>.trust_level
Type / Values
string
Details
프로젝트나 작업 트리를 신뢰함 또는 신뢰하지 않음("trusted" | "untrusted")으로 표시합니다. 신뢰할 수 없는 프로젝트에서는 프로젝트 로컬 구성, 훅, 규칙을 비롯한 프로젝트 범위의 .codex/ 레이어를 건너뜁니다.
Key
review_model
Type / Values
string
Details
/review에 사용할 모델을 별도로 지정합니다(선택 사항, 기본값: 현재 세션 모델).
Key
sandbox_mode
Type / Values
read-only | workspace-write | danger-full-access
Details
명령어 실행 중 파일 시스템 및 네트워크 액세스에 적용되는 샌드박스 정책입니다.
Key
sandbox_workspace_write.exclude_slash_tmp
Type / Values
boolean
Details
workspace-write 모드의 쓰기 가능한 루트에서 /tmp를 제외합니다.
Key
sandbox_workspace_write.exclude_tmpdir_env_var
Type / Values
boolean
Details
workspace-write 모드의 쓰기 가능한 루트에서 $TMPDIR을 제외합니다.
Key
sandbox_workspace_write.network_access
Type / Values
boolean
Details
workspace-write 샌드박스 내에서 아웃바운드 네트워크 액세스를 허용합니다.
Key
sandbox_workspace_write.writable_roots
Type / Values
array<string>
Details
sandbox_mode = "workspace-write"일 때 추가로 쓰기 가능한 루트입니다.
Key
service_tier
Type / Values
string
Details
새 턴에 사용할 선호 서비스 등급입니다. fast 또는 활성 모델이 지원한다고 명시한 다른 등급을 사용하세요. fast는 요청 값 priority에 매핑됩니다.
Key
shell_environment_policy.exclude
Type / Values
array<string>
Details
레거시 환경 변수 제외 패턴입니다. 새 구성에서는 shell_environment_policy.filters를 사용하고, 같은 레이어에서 두 형식을 함께 사용하지 마세요.
Key
shell_environment_policy.experimental_use_profile
Type / Values
boolean
Details
하위 프로세스를 생성할 때 사용자 셸 프로필을 사용합니다.
Key
shell_environment_policy.filters
Type / Values
map<string, include | exclude>
Details
대소문자를 구분하지 않는 표준 환경 변수 패턴 필터입니다. 포함 항목은 허용 목록을 구성하며, 이미 제외된 값은 복원할 수 없습니다. 명시적으로 지정한 set 값은 제외 처리 후 적용됩니다. 같은 레이어에서 필터를 레거시 exclude 또는 include_only 배열과 함께 사용하지 마세요.
Key
shell_environment_policy.ignore_default_excludes
Type / Values
boolean
Details
다른 필터를 적용하기 전에 이름에 KEY, SECRET 또는 TOKEN이 포함된 변수를 유지합니다(기본값: true). 비밀 정보를 나타내는 이름의 변수를 자동으로 제외하려면 false로 설정하세요.
Key
shell_environment_policy.include_only
Type / Values
array<string>
Details
환경 변수 패턴의 레거시 허용 목록입니다. 새 구성에서는 shell_environment_policy.filters를 사용하고, 같은 레이어에서 두 형식을 함께 사용하지 마세요.
Key
shell_environment_policy.inherit
Type / Values
all | core | none
Details
하위 프로세스를 생성할 때 적용할 기본 환경 상속 방식입니다.
Key
shell_environment_policy.set
Type / Values
map<string,string>
Details
제외 처리 후에 삽입할 환경 변수 값을 명시적으로 지정합니다. 포함 필터는 이 값도 제거할 수 있습니다.
Key
show_raw_agent_reasoning
Type / Values
boolean
Details
활성 모델이 추론 원문을 출력하면 이를 표시합니다.
Key
skills.config
Type / Values
array<object>
Details
config.toml에 저장되는 스킬별 활성화 상태 재정의입니다.
Key
skills.config.<index>.enabled
Type / Values
boolean
Details
참조된 스킬을 활성화하거나 비활성화합니다.
Key
skills.config.<index>.path
Type / Values
string (path)
Details
SKILL.md가 포함된 스킬 폴더의 경로입니다.
Key
sqlite_home
Type / Values
string (path)
Details
Codex가 에이전트 작업 및 기타 재개 가능한 런타임 상태에 사용하는 SQLite 기반 상태 DB를 저장하는 디렉터리입니다.
Key
suppress_unstable_features_warning
Type / Values
boolean
Details
개발 중인 기능 플래그를 활성화했을 때 나타나는 경고를 숨깁니다.
Key
tool_output_token_limit
Type / Values
number
Details
개별 도구/함수 출력을 기록에 저장하는 데 사용할 토큰 한도입니다.
Key
tool_suggest.disabled_tools
Type / Values
array<table>
Details
검색 가능한 특정 커넥터나 플러그인에 대한 제안을 비활성화합니다. 각 항목에는 type = "connector" 또는 "plugin"과 id를 사용합니다.
Key
tool_suggest.discoverables
Type / Values
array<table>
Details
검색 가능한 추가 커넥터나 플러그인에 대한 도구 제안을 허용합니다. 각 항목에는 type = "connector" 또는 "plugin"과 id를 사용합니다.
Key
tools.view_image
Type / Values
boolean
Details
로컬 이미지 첨부 도구인 view_image를 활성화합니다.
Key
tools.web_search
Type / Values
boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }
Details
선택적 웹 검색 도구 구성입니다. 객체 형식을 사용하면 검색 컨텍스트 크기, 허용되는 검색 도메인, 대략적인 사용자 위치를 설정할 수 있습니다. 이러한 검색 도메인 필터는 샌드박스에서 실행되는 명령어의 네트워크 도메인 규칙과 별개이며 커넥터나 MCP 서버를 제한하지 않습니다.
Key
tui
Type / Values
table
Details
인라인 데스크톱 알림 활성화와 같은 TUI 전용 옵션입니다.
Key
tui.alternate_screen
Type / Values
auto | always | never
Details
TUI의 대체 화면 사용을 제어합니다(기본값: auto. auto에서는 스크롤백을 유지하기 위해 Zellij에서 대체 화면을 사용하지 않습니다).
Key
tui.animations
Type / Values
boolean
Details
터미널 애니메이션(환영 화면, 시머 효과, 스피너)을 활성화합니다(기본값: true).
Key
tui.keymap.<context>.<action>
Type / Values
string | array<string>
Details
TUI 작업에 대한 키보드 단축키 바인딩입니다. 지원되는 컨텍스트에는 global, chat, composer, editor, vim_normal, vim_operator, vim_text_object, pager, list, approval이 포함됩니다. 일부 Composer 작업은 일치하는 tui.keymap.global 바인딩을 폴백으로 사용하며, 컨텍스트별 바인딩이 지원되면 해당 바인딩이 우선합니다.
Key
tui.keymap.<context>.<action> = []
Type / Values
empty array
Details
해당 키맵 컨텍스트에서 작업의 바인딩을 해제합니다. 키 이름에는 ctrl-a, shift-enter, page-down, minus와 같은 정규화된 문자열을 사용합니다.
Key
tui.model_availability_nux.<model>
Type / Values
integer
Details
모델 슬러그를 키로 사용하는 시작 툴팁의 내부 상태입니다.
Key
tui.notification_condition
Type / Values
unfocused | always
Details
터미널에 포커스가 없을 때만 TUI 알림을 표시할지, 포커스와 관계없이 표시할지 제어합니다. 기본값은 unfocused입니다.
Key
tui.notification_method
Type / Values
auto | osc9 | bel
Details
터미널 알림을 표시하는 방식입니다(기본값: auto).
Key
tui.notifications
Type / Values
boolean | array<string>
Details
TUI 알림을 활성화하며, 필요에 따라 특정 이벤트 유형으로 제한할 수 있습니다.
Key
tui.raw_output_mode
Type / Values
boolean
Details
TUI를 원시 스크롤백 모드로 시작해 터미널에서 텍스트를 쉽게 선택하고 복사할 수 있도록 합니다(기본값: false). /raw 또는 기본 alt-r 키 바인딩으로 전환할 수 있습니다.
Key
tui.resume_cwd
Type / Values
current | session
Details
세션을 재개하거나 포크할 때 사용할 작업 디렉터리입니다. 설정하지 않은 상태에서 현재 디렉터리가 세션에 저장된 디렉터리와 다르면 Codex가 사용할 디렉터리를 선택하도록 요청합니다.
Key
tui.show_tooltips
Type / Values
boolean
Details
TUI 환영 화면에 온보딩 툴팁을 표시합니다(기본값: true).
Key
tui.status_line
Type / Values
array<string> | null
Details
TUI 하단 상태 표시줄의 항목 식별자를 순서대로 나열한 목록입니다. null로 설정하면 상태 표시줄을 비활성화합니다.
Key
tui.terminal_title
Type / Values
array<string> | null
Details
터미널 창 및 탭의 제목 항목 식별자를 순서대로 나열한 목록입니다. 기본값은 ["spinner", "project"]이며, null로 설정하면 제목 업데이트를 비활성화합니다.
Key
tui.theme
Type / Values
string
Details
구문 강조 테마를 재정의합니다(케밥 케이스 형식의 테마 이름).
Key
tui.vim_mode_default
Type / Values
boolean
Details
Composer를 Vim 삽입 모드 대신 일반 모드로 시작합니다(기본값: false). 세션별로 /vim을 사용해 전환할 수도 있습니다.
Key
web_search
Type / Values
disabled | cached | indexed | live
Details
웹 검색 모드입니다(기본값: "cached". cached는 외부 웹에 액세스하지 않고 OpenAI가 관리하는 인덱스를 사용하며, indexed는 검색 인덱스에서 허용하는 경우에만 외부 액세스를 허용합니다. --yolo 또는 다른 전체 권한 샌드박스 설정을 사용하면 기본값은 "live"입니다). 제한 없는 실시간 검색에는 "live"를 사용하고, 도구를 제거하려면 "disabled"를 사용하세요.
Key
windows_wsl_setup_acknowledged
Type / Values
boolean
Details
Windows 온보딩 확인 여부를 추적합니다(Windows 전용).
Key
windows.sandbox
Type / Values
unelevated | elevated
Details
Codex를 Windows에서 네이티브로 실행할 때 사용하는 Windows 전용 네이티브 샌드박스 모드입니다.
Key
windows.sandbox_private_desktop
Type / Values
boolean
Details
Windows에서 네이티브로 실행할 때는 기본적으로 샌드박스가 적용된 최종 자식 프로세스를 프라이빗 데스크톱에서 실행합니다. 이전 Winsta0\\Default 동작과의 호환성이 필요한 경우에만 false로 설정하세요.

config.toml의 최신 JSON 스키마는 여기에서 확인할 수 있습니다.

VS Code 또는 Cursor에서 config.toml을 편집할 때 자동 완성과 진단 기능을 사용하려면 Even Better TOML 확장 프로그램을 설치하고 config.toml 맨 위에 다음 줄을 추가하세요:

#:schema https://developers.openai.com/codex/config-schema.json

참고: experimental_instructions_file의 이름을 model_instructions_file로 변경하세요. Codex에서 이전 키는 사용 중단 예정(deprecated)입니다. 기존 구성도 새 이름을 사용하도록 업데이트하세요.

requirements.toml

requirements.toml은 관리자가 강제 적용하는 구성 파일로, 보안에 민감한 설정을 사용자가 재정의할 수 없도록 제한합니다. 자세한 내용과 파일 위치, 예시는 관리자 강제 적용 요구 사항을 참조하세요.

ChatGPT Business 및 ChatGPT Enterprise 사용자의 경우 Codex는 클라우드에서 가져온 요구 사항도 적용할 수 있습니다. 우선순위에 관한 자세한 내용은 보안 페이지를 참조하세요.

requirements.toml의 [features]에서 config.toml과 동일한 정식 키를 사용해 런타임 기능 플래그를 고정하세요. 요구 사항에는 문서에 명시된 앱 전용 키도 포함할 수 있으며, 이러한 키는 config.toml에서 사용하지 않습니다. 생략한 키에는 제약이 적용되지 않습니다.

일부 관리형 요구 사항은 허용 목록 대신 특정 구성 값을 강제 적용합니다. 사용자는 강제 적용된 경로, 업데이트 기본 설정, 로그인 셸 정책, 피드백 설정 또는 Windows 비공개 데스크톱 설정을 재정의할 수 없습니다.

관리형 권한 프로필 허용 목록을 사용하려면 Codex 0.138.0 이상이 필요합니다. Codex 0.137.0 이하에서는 allowed_permission_profiles 설정과 관리형 default_permissions 설정이 무시됩니다.

allowed_sandbox_modes 설정은 sandbox_mode 설정과 함께 사용하세요. 권한 프로필을 사용하는 배포에서는 allowed_permission_profiles 설정을 관리형 default_permissions 설정과 함께 사용하세요.

[models.new_thread] 테이블은 관리형 기본값을 제공하며, 값을 강제하지는 않습니다. 전용 CLI 플래그나 --config 재정의로 명시한 실행 옵션이 우선합니다. 모델이나 추론 수준을 명시적으로 재정의하면 관리형 모델 필드 두 개를 모두 건너뜁니다. service_tier 설정은 이와 독립적으로 적용됩니다.

Key
allow_appshots
Type / Values
boolean
Details
관리 대상 사용자의 앱샷을 비활성화하려면 false로 설정하세요. 생략하면 앱샷은 요구사항의 제한 없이 일반적인 제품 제공 조건을 따릅니다.
Key
allow_login_shell
Type / Values
boolean
Details
셸 도구가 로그인 셸을 시작할 수 있는지 여부를 강제 적용합니다.
Key
allow_managed_hooks_only
Type / Values
boolean
Details
true이면 Codex는 사용자, 프로젝트, 세션 및 플러그인 훅을 건너뛰지만, requirements.toml 및 다른 관리형 설정 레이어의 관리형 훅은 계속 허용합니다.
Key
allow_remote_control
Type / Values
boolean
Details
관리 대상 사용자의 기기 원격 제어를 비활성화하려면 false로 설정하세요. 생략하면 기기 원격 제어는 요구사항의 제한 없이 일반적인 제품 제공 조건을 따릅니다.
Key
allowed_approval_policies
Type / Values
array<string>
Details
approval_policy에 허용되는 값입니다(예: untrusted, on-request, never, granular).
Key
allowed_approvals_reviewers
Type / Values
array<string>
Details
approvals_reviewer에 허용되는 값입니다(예: user, auto_review).
Key
allowed_permission_profiles
Type / Values
table<boolean>
Details
허용되는 권한 프로필의 전체 목록입니다. true로 설정된 프로필은 허용됩니다. 생략되었거나 false로 설정된 프로필은 향후 버전에 추가되는 프로필을 포함해 모두 거부됩니다. 요구 사항 소스를 결합할 때는 프로필 이름을 기준으로 항목을 일치시킵니다.
Key
allowed_permission_profiles.<name>
Type / Values
boolean
Details
로드된 구성 또는 요구 사항 소스에 정의된 기본 제공 또는 사용자 지정 권한 프로필을 허용하거나 거부합니다. 우선순위가 더 높은 후속 요구 사항 소스에서는 false를 사용해 우선순위가 낮은 이전 소스에서 허용한 프로필을 비활성화할 수 있습니다.
Key
allowed_sandbox_modes
Type / Values
array<string>
Details
sandbox_mode에 허용되는 값입니다.
Key
allowed_web_search_modes
Type / Values
array<string>
Details
web_search에 허용되는 값(disabled, cached, indexed, live)입니다. disabled는 항상 허용되며, 빈 목록을 설정하면 사실상 disabled만 허용됩니다.
Key
apps
Type / Values
table
Details
앱 식별자를 키로 사용하는 관리형 앱 요구사항입니다. 요구사항으로 앱을 비활성화하거나 개별 도구의 승인 동작을 제한할 수 있습니다.
Key
apps.<id>.enabled
Type / Values
boolean
Details
false로 설정하면 앱을 비활성화합니다. 앱 비활성화 요구사항은 여러 요구사항 소스를 병합해도 제한 효력을 유지합니다.
Key
apps.<id>.tools.<tool>.approval_mode
Type / Values
auto | prompt | writes | approve
Details
개별 앱 도구의 관리형 승인 모드를 설정합니다.
Key
check_for_update_on_startup
Type / Values
boolean
Details
Codex가 시작할 때 업데이트를 확인할지 여부를 강제 적용합니다.
Key
computer_use
Type / Values
table
Details
requirements.toml에서 강제 적용하는 컴퓨터 사용 요구사항입니다.
Key
computer_use.allow_locked_computer_use
Type / Values
boolean
Details
관리 대상 macOS 기기가 잠긴 후 컴퓨터 사용 기능이 작동하지 않도록 하려면 false로 설정하세요. 생략하면 잠긴 상태에서의 사용은 요구사항의 제한을 받지 않습니다.
Key
default_permissions
Type / Values
string
Details
관리형 기본 권한 프로필입니다. 프로필은 allowed_permission_profiles에서 허용되어야 합니다. 예측 가능한 동작을 위해 이 값을 명시적으로 설정하세요. 생략하면 :workspace와 :read-only가 모두 명시적으로 허용된 경우에만 Codex에서 :workspace를 기본값으로 사용합니다.
Key
enforce_residency
Type / Values
string
Details
Codex 서비스 트래픽에 지원되는 데이터 레지던시를 사용하도록 요구합니다. 현재 허용되는 값은 us입니다.
Key
experimental_network
Type / Values
table
Details
관리자가 설정하고 requirements.toml에서 강제 적용하는 샌드박스 내 로컬 명령어의 네트워크 요구사항입니다. 활성화하면 features.network_proxy 없이도 명령어용 네트워크 프록시를 시작할 수 있습니다. 웹 검색, 앱, MCP 서버, 브라우저 또는 Codex 클라우드의 네트워크 연결은 제어하지 않습니다.
Key
experimental_network.allow_local_binding
Type / Values
boolean
Details
샌드박스 네트워킹에서 더 광범위한 로컬 및 사설 네트워크 접근을 허용합니다. 이 값이 false여도 정확한 로컬 IP 리터럴 또는 localhost 허용 규칙으로 특정 로컬 대상에 대한 접근을 허용할 수 있습니다.
Key
experimental_network.allow_upstream_proxy
Type / Values
boolean
Details
샌드박스 네트워킹이 환경에 설정된 업스트림 프록시를 경유하도록 허용합니다.
Key
experimental_network.allowed_domains
Type / Values
array<string>
Details
관리형 네트워크 프록시가 활성화된 동안 샌드박스 내 명령어의 네트워크 연결에 적용되는 관리자 허용 규칙입니다. 이 규칙은 웹 검색, 앱 또는 MCP 서버에는 적용되지 않습니다. experimental_network.domains와 함께 사용하지 마세요.
Key
experimental_network.dangerously_allow_all_unix_sockets
Type / Values
boolean
Details
허용 목록에 한정하지 않고 임의의 Unix 소켓 대상으로의 접근을 허용합니다. 엄격하게 통제되는 환경에서만 사용하세요.
Key
experimental_network.dangerously_allow_non_loopback_proxy
Type / Values
boolean
Details
[experimental_network] 요구사항에서 루프백 이외의 리스너 주소를 허용합니다. 활성화하면 리스너가 로컬호스트 외부에 노출될 수 있습니다.
Key
experimental_network.denied_domains
Type / Values
array<string>
Details
샌드박스 네트워킹을 위한 목록 형식의 관리자 거부 규칙입니다. experimental_network.domains와 함께 사용하지 마세요.
Key
experimental_network.domains
Type / Values
map<string, allow | deny>
Details
샌드박스 네트워킹을 위한 맵 형식의 관리자 도메인 정책입니다. 정확히 일치하는 호스트, 하위 도메인만 지정하는 *.example.com, 루트 도메인과 하위 도메인을 지정하는 **.example.com, 전역 * 허용 규칙을 지원합니다. *는 공용 네트워크로의 아웃바운드 접근을 광범위하게 허용하므로 범위가 제한된 규칙을 사용하는 것이 좋습니다. 충돌할 때는 deny가 우선합니다. experimental_network.allowed_domains 또는 experimental_network.denied_domains와 함께 사용하지 마세요.
Key
experimental_network.enabled
Type / Values
boolean
Details
샌드박스 네트워킹 요구사항을 활성화합니다. 현재 샌드박스에서 명령어의 네트워크 사용을 비활성화한 경우, 이 설정으로 네트워크 접근 권한이 부여되지는 않습니다.
Key
experimental_network.http_port
Type / Values
integer
Details
[experimental_network] 요구사항에 사용할 루프백 HTTP 리스너 포트입니다.
Key
experimental_network.managed_allowed_domains_only
Type / Values
boolean
Details
true이면 샌드박스 네트워킹 요구사항이 적용되는 동안 관리자가 설정한 허용 규칙만 유효하며, 사용자가 허용 목록에 추가한 항목은 무시됩니다. 관리형 허용 규칙이 없는 경우에도 사용자가 추가한 도메인 허용 규칙은 유효하지 않습니다.
Key
experimental_network.socks_port
Type / Values
integer
Details
[experimental_network] 요구사항에 사용할 루프백 SOCKS5 리스너 포트입니다.
Key
experimental_network.unix_sockets
Type / Values
map<string, allow | deny>
Details
관리자가 설정하는 샌드박스 네트워킹용 Unix 소켓 정책입니다.
Key
features
Type / Values
table
Details
고정된 기능 값입니다. 런타임 기능에는 config.toml의 정식 이름을 사용하세요. 문서에 명시된 앱 전용 요구사항 키도 여기에서 지원합니다.
Key
features.<name>
Type / Values
boolean
Details
문서에 명시된 런타임 또는 앱 기능을 활성화 또는 비활성화 상태로 유지하도록 강제합니다.
Key
features.apps
Type / Values
boolean
Details
관리 대상 사용자의 앱 통합 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.browser_use
Type / Values
boolean
Details
브라우저에서의 컴퓨터 사용 기능과 브라우저 에이전트를 비활성화하려면 requirements.toml에서 false로 설정하세요.
Key
features.browser_use_external
Type / Values
boolean
Details
외부 브라우저에서의 컴퓨터 사용 기능을 비활성화하려면 requirements.toml에서 false로 설정하세요.
Key
features.browser_use_full_cdp_access
Type / Values
boolean
Details
requirements.toml에서 false로 설정하면 브라우저 개발자 모드를 비롯해 로컬 런타임의 Chrome DevTools Protocol에 대한 전체 접근이 비활성화되며, ChatGPT 데스크톱 앱에서도 해당 설정을 활성화할 수 없게 됩니다. 생략하면 일반적인 제품 제공 조건이 적용됩니다.
Key
features.computer_use
Type / Values
boolean
Details
컴퓨터 사용, 기록 및 재생, 관련 설치 또는 활성화 플로우를 비활성화하려면 requirements.toml에서 false로 설정하세요.
Key
features.fast_mode
Type / Values
boolean
Details
관리 대상 사용자의 정식 fast_mode 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.guardian_approval
Type / Values
boolean
Details
관리 대상 사용자의 Guardian 승인 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.in_app_browser
Type / Values
boolean
Details
내장 브라우저 패널을 비활성화하려면 requirements.toml에서 false로 설정하세요.
Key
features.in_app_updates
Type / Values
boolean
Details
앱 내 업데이트를 비활성화하려면 requirements.toml에서 false로 설정하세요. 이 요구사항을 생략하면 업데이트는 기본적으로 활성화됩니다.
Key
features.memories
Type / Values
boolean
Details
관리 대상 사용자의 메모리 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.multi_agent
Type / Values
boolean
Details
관리 대상 사용자의 다중 에이전트 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.plugin_sharing
Type / Values
boolean
Details
로컬에서 빌드한 플러그인의 워크스페이스 공유를 비활성화하려면 클라우드에서 관리하는 requirements.toml에서 false로 설정하세요.
Key
features.plugins
Type / Values
boolean
Details
관리 대상 사용자의 플러그인 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.remote_plugin
Type / Values
boolean
Details
관리 대상 사용자의 원격 플러그인 카탈로그 기능을 활성화 또는 비활성화 상태로 고정합니다.
Key
features.workspace_dependencies
Type / Values
boolean
Details
관리 대상 사용자에게 번들로 제공되는 워크스페이스 종속성 런타임을 활성화 또는 비활성화 상태로 고정합니다.
Key
feedback
Type / Values
table
Details
관리형 피드백 설정입니다.
Key
feedback.enabled
Type / Values
boolean
Details
사용자가 모든 Codex 클라이언트에서 피드백을 제출할 수 있는지 여부를 강제 적용합니다.
Key
guardian_policy_config
Type / Values
string
Details
자동 검토를 위한 관리형 Markdown 정책 지침입니다. 로컬 [auto_review].policy보다 우선합니다. 빈 값은 무시됩니다.
Key
hooks
Type / Values
table
Details
관리자가 강제 적용하는 관리형 수명 주기 훅입니다. 관리형 훅 디렉터리가 필요하며 config.toml의 인라인 [hooks]와 동일한 이벤트 스키마를 사용합니다.
Key
hooks.<Event>
Type / Values
array<table>
Details
PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit, Stop 등의 훅 이벤트에 대한 매처 그룹입니다.
Key
hooks.<Event>[].hooks
Type / Values
array<table>
Details
매처 그룹의 훅 핸들러입니다. 명령어 훅과 MCP 도구 훅을 지원하며, 프롬프트 및 에이전트 훅 핸들러는 파싱하지만 실행은 건너뜁니다.
Key
hooks.<Event>[].hooks[].additionalContextLimit
Type / Values
integer
Details
크기가 너무 큰 additionalContext를 디스크에 저장하고 모델에는 더 짧은 미리 보기를 표시하기 위한 핸들러별 대략적인 토큰 임곗값입니다. 기본값은 2500이며 0으로 설정하면 전체 컨텍스트를 모델에 직접 전달합니다. 대용량 훅 출력을 참고하세요.
Key
hooks.<Event>[].hooks[].async
Type / Values
boolean
Details
훅을 트리거한 작업을 지연시키지 않고 명령어 훅을 백그라운드에서 실행합니다. 기본값은 false이며 SessionEnd는 항상 동기식으로 실행됩니다. 백그라운드에서 훅 실행을 참고하세요.
Key
hooks.<Event>[].hooks[].commandWindows
Type / Values
string
Details
명령어 훅의 명령어를 재정의하는 Windows 전용 설정입니다. TOML 별칭 command_windows도 사용할 수 있습니다.
Key
hooks.managed_dir
Type / Values
string (absolute path)
Details
macOS 및 Linux에서 관리형 훅 스크립트가 들어 있는 디렉터리입니다. Codex는 관리형 훅을 로드하기 전에 경로가 절대 경로이며 해당 디렉터리가 존재하는지 확인합니다.
Key
hooks.windows_managed_dir
Type / Values
string (absolute path)
Details
Windows에서 관리형 훅 스크립트가 들어 있는 디렉터리입니다. Codex는 관리형 훅을 로드하기 전에 경로가 절대 경로이며 해당 디렉터리가 존재하는지 확인합니다.
Key
log_dir
Type / Values
string (path)
Details
Codex가 로컬 로그 파일을 기록할 디렉터리를 강제 지정합니다.
Key
marketplaces
Type / Values
table
Details
플러그인 마켓플레이스 소스에 대한 관리자 요구사항입니다. restrict_to_allowed_sources가 true일 때 규칙이 적용됩니다.
Key
marketplaces.allowed_sources
Type / Values
table
Details
관리자가 지정한 규칙 이름을 키로 사용하는 허용된 마켓플레이스 소스입니다. 서로 다른 이름의 규칙은 요구사항 레이어 간에 누적되며, 같은 이름 아래의 필드에는 일반적인 레이어 우선순위가 적용됩니다.
Key
marketplaces.allowed_sources.<name>
Type / Values
table
Details
허용할 소스를 지정하는 규칙 하나입니다. 요구사항 병합 후의 최종 source 값에 따라 Codex가 같은 수준의 필드 중 어떤 필드를 해석할지 결정됩니다.
Key
marketplaces.allowed_sources.<name>.host_pattern
Type / Values
string
Details
source = "host_pattern"일 때 필요한 정규식입니다. Codex는 HTTPS, SSH 또는 SCP 형식의 Git 소스에서 파싱한 소문자 호스트 이름과 이 정규식을 대조합니다. 호스트 이름 전체가 일치하도록 하려면 ^와 $를 사용합니다.
Key
marketplaces.allowed_sources.<name>.path
Type / Values
string (absolute path)
Details
source = "local"일 때 필요한 로컬 마켓플레이스 디렉터리입니다. Codex는 절대 경로를 요구하며 경로를 정규화한 후 비교합니다.
Key
marketplaces.allowed_sources.<name>.ref
Type / Values
string
Details
git 규칙에서 정확히 일치시킬 Git ref입니다. 선택 사항이며, 생략하면 일치하는 레포지토리의 모든 ref를 허용합니다.
Key
marketplaces.allowed_sources.<name>.source
Type / Values
git | host_pattern | local
Details
마켓플레이스 소스 매처 유형입니다. 하나의 레포지토리에는 git, 정규식과 일치하는 Git 호스트에는 host_pattern, 하나의 디렉터리에는 local을 사용합니다.
Key
marketplaces.allowed_sources.<name>.url
Type / Values
string
Details
source = "git"일 때 필요한 Git 레포지토리 URL입니다. Codex는 설정된 URL과 허용된 URL을 정규화한 후, 두 URL이 정확히 같은 레포지토리를 가리키는 경우에만 허용합니다.
Key
marketplaces.restrict_to_allowed_sources
Type / Values
boolean
Details
true이면 마켓플레이스 추가, 플러그인 설치, 설정된 Git 마켓플레이스 새로 고침 작업에서 사용자가 설정한 마켓플레이스 소스가 allowed_sources와 일치해야 합니다. Codex가 관리하는 OpenAI 마켓플레이스는 예약된 소스와 이름이 일치하면 계속 허용됩니다. 이미 설정된 사용자 마켓플레이스를 런타임에 필터링하지는 않습니다.
Key
mcp_servers
Type / Values
table
Details
활성화할 수 있는 MCP 서버의 허용 목록입니다. MCP 서버를 활성화하려면 서버 이름(<id>)과 식별 정보가 모두 일치해야 합니다. 설정된 MCP 서버가 허용 목록에 없거나 식별 정보가 일치하지 않으면 비활성화됩니다.
Key
mcp_servers.<id>.identity
Type / Values
table
Details
단일 MCP 서버의 식별 규칙입니다. command(stdio) 또는 url(streamable HTTP) 중 하나를 설정하세요.
Key
mcp_servers.<id>.identity.command
Type / Values
string | table
Details
정확히 일치하는 명령어 문자열로 MCP stdio 서버를 허용합니다. 또는 매처 테이블을 사용해 실행 파일이 정확히 일치하고 각 인수가 지정된 순서의 매처와 일치하도록 요구할 수 있습니다. 문자열 형식은 인수, cwd, env, env_vars를 검사하지 않습니다.
Key
mcp_servers.<id>.identity.command.args
Type / Values
array<table>
Details
stdio 서버에 사용할 순서가 지정된 인수 매처입니다. 설정된 인수 목록은 매처 목록과 길이가 같아야 하며 각 위치의 인수가 해당 매처와 일치해야 합니다. 명령어 매처는 cwd, env, env_vars를 검사하지 않습니다.
Key
mcp_servers.<id>.identity.command.args[].expression
Type / Values
string
Details
regex 인수 매처에 사용하는 정규 표현식입니다. 표현식은 유효해야 하며 전체 인수 값과 일치해야 합니다.
Key
mcp_servers.<id>.identity.command.args[].match
Type / Values
exact | prefix | regex
Details
이 인수 위치에 적용할 매칭 연산입니다.
Key
mcp_servers.<id>.identity.command.args[].value
Type / Values
string
Details
exact 또는 prefix 인수 매처에 사용하는 값입니다.
Key
mcp_servers.<id>.identity.command.executable
Type / Values
string
Details
stdio 서버에 설정된 command가 정확히 일치해야 하는 실행 파일입니다.
Key
mcp_servers.<id>.identity.url
Type / Values
string | table
Details
정확히 일치하는 URL 문자열로 MCP streamable HTTP 서버를 허용하거나, exact, prefix, regex 값 매처 테이블을 사용합니다.
Key
mcp_servers.<id>.identity.url.expression
Type / Values
string
Details
regex URL 매처에 사용하는 정규 표현식입니다. 표현식은 유효해야 하며 전체 URL 값과 일치해야 합니다.
Key
mcp_servers.<id>.identity.url.match
Type / Values
exact | prefix | regex
Details
설정된 MCP 서버 URL에 적용할 매칭 연산입니다.
Key
mcp_servers.<id>.identity.url.value
Type / Values
string
Details
exact 또는 prefix URL 매처에 사용하는 값입니다.
Key
model_catalog_json
Type / Values
string (path)
Details
Codex가 시작할 때 사용할 JSON 모델 카탈로그를 강제 지정합니다.
Key
models
Type / Values
table
Details
새 스레드의 관리형 모델 기본값입니다. 이 값은 사용자 및 프로젝트 기본값보다 우선하지만, 새 스레드에 사용할 값을 명시적으로 선택하면 이를 재정의할 수 있습니다.
Key
models.new_thread
Type / Values
table
Details
새 로컬 스레드가 시작될 때 적용할 기본값입니다. 각 모델 설정은 선택 사항입니다.
Key
models.new_thread.model
Type / Values
string
Details
새 스레드의 기본 모델입니다. --model로 모델을 명시하거나 --config로 모델/추론 설정을 명시적으로 재정의하면 해당 값이 우선합니다.
Key
models.new_thread.model_reasoning_effort
Type / Values
string
Details
새 스레드의 기본 추론 수준입니다. 모델 또는 추론 수준을 명시적으로 재정의하면 관리형 모델 필드 두 개를 모두 건너뜁니다.
Key
models.new_thread.service_tier
Type / Values
string
Details
새 스레드의 기본 서비스 등급입니다. 명시적으로 재정의한 서비스 등급은 모델 필드와 별개로 우선 적용됩니다.
Key
permissions
Type / Values
table
Details
관리자가 정의한 권한 프로필이며, 프로필 이름을 키로 사용합니다. config.toml과 동일한 프로필 필드를 사용합니다.
Key
permissions.<name>
Type / Values
table
Details
관리자가 정의한 권한 프로필입니다. 이름은 :으로 시작할 수 없으며, 예약 이름인 filesystem이나 로드된 구성의 기존 프로필 이름을 사용할 수도 없습니다. config.toml과 동일한 프로필 필드를 사용합니다. 전체 프로필 스키마는 권한 가이드를 참조하세요.
Key
permissions.filesystem.deny_read
Type / Values
array<string>
Details
관리자가 강제 적용하는 파일 시스템 읽기 거부 규칙입니다. 항목은 경로나 glob 패턴으로 지정할 수 있으며, 사용자는 로컬 설정으로 규칙을 완화할 수 없습니다.
Key
plugins
Type / Values
table
Details
플러그인 식별자를 키로 사용하는 플러그인별 MCP 서버 허용 목록입니다. 이 테이블이 있으면 플러그인에 번들로 제공되는 서버는 일치하는 플러그인 및 서버 항목이 없을 경우 비활성화됩니다.
Key
plugins.<plugin>.mcp_servers
Type / Values
table
Details
하나의 플러그인에 번들로 제공되는 MCP 서버의 허용 목록입니다. 플러그인 서버 요구사항에서 식별 정보의 정확한 일치 여부를 지정하거나 매처를 정의할 때는 최상위 mcp_servers 요구사항과 같은 형식을 사용합니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity
Type / Values
table
Details
플러그인에 번들로 제공되는 단일 MCP 서버의 식별 규칙입니다. command(stdio) 또는 url(streamable HTTP) 중 하나를 설정하세요.
Key
plugins.<plugin>.mcp_servers.<server>.identity.command
Type / Values
string | table
Details
플러그인의 stdio MCP 서버를 정확히 일치하는 명령어 문자열로 허용하거나, 매처 테이블을 사용해 실행 파일이 정확히 일치하고 인수가 순서대로 지정된 매처와 일치하도록 요구합니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.command.args
Type / Values
array<table>
Details
플러그인에 포함된 stdio 서버의 인수 매처를 순서대로 나열한 목록입니다. 설정된 인수 목록은 길이가 같아야 하며, 각 위치의 인수가 해당 매처와 일치해야 합니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression
Type / Values
string
Details
regex 인수 매처가 사용하는 정규식입니다. 이 정규식은 인수 값 전체와 일치해야 합니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match
Type / Values
exact | prefix | regex
Details
이 인수 위치에 적용할 매칭 연산입니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value
Type / Values
string
Details
exact 또는 prefix 인수 매처가 사용하는 값입니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.command.executable
Type / Values
string
Details
플러그인에 포함된 stdio 서버의 명령어 설정이 정확히 일치해야 하는 실행 파일입니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.url
Type / Values
string | table
Details
플러그인의 스트리밍 가능한 HTTP MCP 서버를 정확히 일치하는 URL 문자열로 허용하거나, exact, prefix 또는 regex 값 매처 테이블을 사용합니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.url.expression
Type / Values
string
Details
regex URL 매처가 사용하는 정규식입니다. 이 정규식은 URL 값 전체와 일치해야 합니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.url.match
Type / Values
exact | prefix | regex
Details
플러그인에 포함된 MCP 서버 URL에 적용할 매칭 연산입니다.
Key
plugins.<plugin>.mcp_servers.<server>.identity.url.value
Type / Values
string
Details
exact 또는 prefix URL 매처가 사용하는 값입니다.
Key
remote_sandbox_config
Type / Values
array<table>
Details
호스트별 샌드박스 요구사항입니다. 확인된 호스트 이름과 hostname_patterns가 일치하는 첫 번째 항목이 해당 요구사항 소스의 최상위 allowed_sandbox_modes를 재정의합니다. 현재 호스트별 항목은 샌드박스 모드만 재정의합니다.
Key
remote_sandbox_config[].allowed_sandbox_modes
Type / Values
array<string>
Details
이 호스트별 항목과 일치하는 경우 적용할 허용 샌드박스 모드입니다.
Key
remote_sandbox_config[].hostname_patterns
Type / Values
array<string>
Details
대소문자를 구분하지 않는 호스트 이름 패턴입니다. 임의 길이의 문자열을 나타내는 *와 문자 하나를 나타내는 ?를 지원합니다.
Key
rules
Type / Values
table
Details
관리자가 강제 적용하며 .rules 파일과 병합되는 명령어 규칙입니다. 요구사항 규칙은 반드시 제한적이어야 합니다.
Key
rules.prefix_rules
Type / Values
array<table>
Details
강제 적용되는 접두사 규칙 목록입니다. 각 규칙에는 pattern과 decision이 포함되어야 합니다.
Key
rules.prefix_rules[].decision
Type / Values
prompt | forbidden
Details
필수입니다. 요구사항 규칙은 승인 요청이나 금지만 할 수 있으며, 허용할 수는 없습니다.
Key
rules.prefix_rules[].justification
Type / Values
string
Details
승인 프롬프트나 거부 메시지에 표시할 사유입니다. 선택 사항이지만 지정할 경우 비어 있으면 안 됩니다.
Key
rules.prefix_rules[].pattern
Type / Values
array<table>
Details
패턴 토큰으로 표현한 명령어 접두사입니다. 각 토큰에는 token 또는 any_of 중 하나를 설정합니다.
Key
rules.prefix_rules[].pattern[].any_of
Type / Values
array<string>
Details
이 위치에서 허용되는 대체 토큰 목록입니다.
Key
rules.prefix_rules[].pattern[].token
Type / Values
string
Details
이 위치의 단일 리터럴 토큰입니다.
Key
sqlite_home
Type / Values
string (path)
Details
Codex가 SQLite 기반 런타임 상태를 저장할 디렉터리를 강제 지정합니다.
Key
windows
Type / Values
table
Details
Windows 네이티브 샌드박스 요구 사항입니다.
Key
windows.allowed_sandbox_implementations
Type / Values
array<string>
Details
windows.sandbox에 허용되는 Windows 네이티브 샌드박스 구현(elevated, unelevated)입니다. 목록은 비어 있을 수 없습니다. 둘 다 허용되며 모드를 선택하지 않은 경우 Codex는 elevated를 우선 사용합니다.
Key
windows.sandbox_private_desktop
Type / Values
boolean
Details
네이티브 Windows 샌드박스가 전용 데스크톱에서 자식 프로세스를 시작할지 여부를 강제 설정합니다.