ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

구성 기본 사항

로컬 Codex 클라이언트 설정의 기본 사항을 알아보세요

Codex는 여러 위치에서 구성 정보를 읽습니다. 개인 기본값은 ~/.codex/config.toml에 저장되며, .codex/config.toml 파일을 사용해 프로젝트별 재정의를 추가할 수 있습니다. 보안을 위해 Codex는 사용자가 신뢰하는 프로젝트에서만 프로젝트 .codex/ 계층을 로드합니다.

Codex 구성 파일

Codex는 사용자 수준 구성을 ~/.codex/config.toml에 저장합니다. 설정 범위를 특정 프로젝트나 하위 폴더로 한정하려면 리포지토리에 .codex/config.toml 파일을 추가하세요.

Codex IDE 확장 프로그램에서 구성 파일을 열려면 오른쪽 위의 톱니바퀴 아이콘을 선택한 다음 Codex 설정 > config.toml 열기 를 선택하세요.

CLI와 IDE 확장 프로그램은 동일한 구성 계층을 공유합니다. 다음 용도로 사용할 수 있습니다.

구성 우선순위

요구 사항은 동작을 제한하고, 구성 값은 기본값을 제공합니다. Work Cloud의 로컬 컴퓨터 액세스에는 다음 요구 사항이 적용됩니다:

  • 정책 간: 우선순위가 낮은 정책이 더 구체적이더라도 우선순위가 높은 정책이 우선 적용됩니다.
  • 하나의 정책 내: OS별 환경 재정의가 모든 OS에 대한 환경 재정의보다 우선하며, 그다음으로 Global이 적용됩니다.
  • 로컬 실행: MDM 및 기존 관리형 기기 요구 사항은 Agent Security보다 우선합니다. 기기의 시스템 요구 사항 파일은 Agent Security보다 우선순위가 낮습니다.
  • Work Cloud: Work 클라우드 컨테이너는 기존 Work Cloud 정책을 유지합니다. 로컬 액세스를 사용하는 Work와 dots의 경우 관리형 정책이 활성화되면 지원되는 Global 정책이 공유 클라우드 오케스트레이터에 적용되며, 연결된 컴퓨터에는 해당 로컬 실행 요구 사항이 적용됩니다.

일부 요구 사항에는 필드별 병합 규칙이 있습니다. 정책 범위와 런타임 제한은 관리형 구성을, Work 호환성은 구성 참조를 참조하세요.

Codex는 다음 순서로 값을 결정합니다(우선순위가 높은 항목부터 표시).

  1. CLI 플래그 및 --config 재정의
  2. 프로젝트 설정 파일: .codex/config.toml, 프로젝트 루트부터 현재 작업 디렉터리까지 순서대로 적용(가장 가까운 파일이 우선하며, 신뢰하는 프로젝트에만 적용)
  3. --profile profile-name로 선택한 프로필 파일(~/.codex/profile-name.config.toml)
  4. 사용자 설정: ~/.codex/config.toml
  5. 로그인한 워크스페이스에 제공되는 경우, 클라우드에서 관리하는 config.toml 기본값
  6. 시스템 설정(있는 경우): Unix의 /etc/codex/config.toml
  7. 내장 기본값

이 우선순위를 활용하여 공유 기본값은 config.toml에 설정하고, 프로필 파일에는 서로 다른 값만 포함하세요.

클라우드 관리 설정과 시스템 설정에서는 플러그인 마켓플레이스를 정의하고 플러그인의 기본 활성화 여부를 설정할 수 있습니다. 이는 강제로 적용되는 requirements.toml 정책과는 별개입니다. 플러그인 마켓플레이스 및 기본값 구성을 참조하세요.

프로젝트를 신뢰하지 않는 것으로 표시하면 Codex는 프로젝트 로컬 구성, 훅 및 규칙을 비롯하여 프로젝트 범위의 .codex/ 계층을 건너뜁니다. 사용자/전역 훅과 규칙을 포함한 사용자 및 시스템 구성은 계속 로드됩니다.

TOML 따옴표 규칙을 포함하여 -c/--config를 통한 일회성 재정의에 관해서는 고급 구성을 참조하세요.

일반적인 구성 옵션

사용자가 가장 자주 변경하는 몇 가지 옵션은 다음과 같습니다.

기본 모델

Codex가 CLI와 IDE에서 기본적으로 사용하는 모델을 선택합니다.

model = "gpt-6.1-sol"

승인 프롬프트

Codex가 생성된 명령을 실행하기 전에 승인을 요청하기 위해 일시 중지할 시점을 제어합니다.

approval_policy = "on-request"

on-request와 never의 동작 차이는 승인 프롬프트 없이 실행 및 일반적인 샌드박스 및 승인 조합을 참조하세요. 기존 설정에서 approval_policy = "untrusted"를 사용하는 경우 지원이 종료된 untrusted 승인 정책에서 마이그레이션을 참조하세요.

샌드박스 수준

Codex가 명령을 실행하는 동안 보유하는 파일 시스템 및 네트워크 액세스 범위를 조정합니다.

sandbox_mode = "workspace-write"

모드별 동작(보호되는 .git, .agents, .codex, .aws 경로와 네트워크 기본값 포함)은 샌드박스 및 승인, 쓰기 가능한 루트의 보호 경로, 네트워크 액세스를 참고하세요.

권한 프로필

Codex는 재사용 가능한 파일 시스템 및 네트워크 정책을 위한 이름 있는 권한 프로필도 지원합니다. 기본 제공 프로필은 :read-only, :workspace 및 :danger-full-access입니다. 사용자 지정 프로필은 [permissions.<name>] 테이블과 이에 일치하는 default_permissions 값을 사용합니다. 권한을 참조하세요.

Windows 샌드박스 모드

Windows에서는 기기와 정책이 지원하는 경우 MXC를 우선 사용하세요. 대체 수단으로 레거시 구현을 설정하세요:

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

관리자 권한으로 설정할 수 없고 조직 정책에서 허용하는 경우에만 unelevated를 사용하세요. 호환성 제한과 배포 제어에 관한 내용은 Windows 샌드박스 가이드를 참고하세요.

웹 검색 모드

Codex는 로컬 채팅에서 웹 검색을 기본적으로 활성화하며 웹 검색 캐시에서 결과를 제공합니다. 이 캐시는 OpenAI가 관리하는 웹 검색 결과 인덱스이므로, 캐시 모드에서는 실시간 페이지를 가져오는 대신 미리 인덱싱된 결과를 반환합니다. 이를 통해 임의의 실시간 콘텐츠에서 발생하는 프롬프트 인젝션에 노출될 가능성을 줄입니다. 웹 검색 결과는 신뢰할 수 없는 것으로 취급하세요. --yolo 또는 다른 전체 액세스 샌드박스 설정을 사용하면 웹 검색은 기본적으로 실시간 결과를 제공합니다. web_search로 모드를 선택하세요:

  • "cached"(기본값)은 웹 검색 캐시의 결과를 제공합니다.
  • "indexed"은 검색 색인이 요청을 허용할 때만 외부 웹 액세스를 허용합니다.
  • "live"는 웹에서 최신 데이터를 가져옵니다(--search와 동일).
  • "disabled"은 웹 검색 도구를 끕니다.
web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

추론 노력

지원되는 경우 모델이 적용하는 추론 노력의 정도를 조정합니다.

model_reasoning_effort = "medium"

소통 스타일

기본 제공 성격 지침을 제외하려면 다음과 같이 설정하세요:

personality = "none"

이 설정은 모델의 기본 제공 지침에서 Personality 섹션을 제거합니다. 명시적으로 지정한 사용자 정의 기본 지침은 변경하지 않습니다. 기존 friendly 및 pragmatic 값으로는 더 이상 스타일을 선택할 수 없습니다. Codex는 더 이상 /personality 명령을 제공하지 않습니다.

TUI 키맵

tui.keymap에서 터미널 단축키를 사용자 지정합니다. 선택한 작성기 작업은 일치하는 tui.keymap.global 바인딩으로 대체되며, 지원되는 경우 상황별 바인딩이 우선합니다. 빈 목록은 작업의 바인딩을 해제합니다.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

명령 환경

Codex가 생성된 명령에 전달할 환경 변수를 제어합니다. 필요한 변수만 유지하려면 키 기반 필터를 사용하세요.

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

ignore_default_excludes의 기본값은 true이며, 이 경우 이름에 KEY, SECRET 또는 TOKEN이 포함된 변수에 대한 자동 필터링을 건너뜁니다. 자동 필터링을 사용하려면 이를 false으로 설정하세요. 제외 규칙, 우선순위 및 레거시 구성에 관해서는 셸 환경 정책을 참조하세요.

로그 디렉터리

Codex가 로컬 로그 파일을 기록하는 위치를 재정의합니다. log_dir을 명시적으로 설정하면 해당 디렉터리에서 선택적으로 사용하는 일반 텍스트 TUI 로그 codex-tui.log도 활성화됩니다.

log_dir = "/absolute/path/to/codex-logs"

일회성 실행의 경우 CLI에서 설정할 수도 있습니다.

codex -c log_dir=./.codex-log

기능 플래그

config.toml의 [features] 테이블을 사용하여 선택적 기능과 실험적 기능을 전환합니다.

일반적인 기능 플래그

키 기본값 성숙도 설명
apps true 안정화 앱(커넥터) 통합 활성화
goals true 안정화 지속되는 목표 및 자동 계속 진행 활성화
hooks true 안정화 hooks.json 또는 인라인 [hooks]의 수명 주기 훅 활성화. 훅 참조.
fast_mode true 안정화 Fast 모드 선택 및 service_tier = "fast" 경로 활성화
memories false 실험적 메모리 활성화
multi_agent true 안정화 하위 에이전트 협업 도구 활성화
remote_plugin true 안정화 원격 플러그인 카탈로그 활성화
shell_snapshot true 안정화 반복되는 명령의 속도를 높이기 위해 셸 환경 스냅샷 생성
shell_tool true 안정 명령 실행 도구 활성화
unified_exec true 안정 재개 가능한 명령 실행 활성화. 관리형 요구 사항을 통해서만 비활성화 가능
web_search true 지원 중단됨 레거시 전환 옵션. 최상위 web_search 설정 사용 권장
web_search_cached false 지원 중단됨 설정되지 않은 경우 web_search = "cached"에 매핑되는 레거시 전환 옵션
web_search_request false 지원 중단됨 설정되지 않은 경우 web_search = "live"에 매핑되는 레거시 전환 옵션

수명 주기 훅 구성은 훅을 참조하세요.

기능 활성화하기

  • config.toml에서 [features] 아래에 feature_name = true을 추가합니다.
  • CLI에서 codex --enable feature_name을 실행합니다.
  • 기능을 두 개 이상 활성화하려면 codex --enable feature_a --enable feature_b을 실행합니다.
  • 기능을 비활성화하려면 config.toml에서 키를 false으로 설정합니다.