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

관리형 구성

지원되는 로컬 클라이언트 전반에 런타임 요구 사항을 적용하고 관리형 기본값을 배포합니다.

관리형 구성은 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램에서 대상 기능에 대해 지원되는 로컬 런타임 동작을 제어합니다. 지원되는 요구 사항은 클라이언트와 버전에 따라 다를 수 있습니다. 관리형 구성은 ChatGPT 워크스페이스 액세스를 부여하거나, 좌석을 할당하거나, 워크스페이스 역할 기반 액세스 제어(RBAC)를 대체하지 않습니다. 워크스페이스 기능 액세스에는 역할 및 워크스페이스 권한을 사용하고 로컬 런타임 정책에는 이 페이지를 사용하세요.

Enterprise 관리자는 다음 두 가지 방식으로 지원되는 로컬 클라이언트 동작을 제어할 수 있습니다.

  • 요구 사항: 사용자가 재정의할 수 없는 관리자 적용 제약 조건입니다.
  • 관리형 기본값: 지원되는 클라이언트가 시작될 때 적용되는 초기값입니다. 사용자는 실행 중에도 설정을 변경할 수 있지만 클라이언트가 다음에 시작될 때 관리형 기본값이 다시 적용됩니다.

관리자가 적용하는 요구 사항(requirements.toml)

요구 사항은 보안에 민감한 설정(승인 정책, 승인 검토자, 자동 검토 정책, 샌드박스 모드, 권한 프로필, 웹 검색 모드, 관리형 hook, 사용자가 활성화할 수 있는 MCP 서버, 그리고 사용자가 구성한 플러그인 마켓플레이스 소스 중 추가하거나 설치하거나 새로 고칠 수 있는 소스)을 제한합니다. 예를 들어 config.toml, 프로필 파일 또는 CLI 구성 재정의에서 구성을 확인할 때 값이 적용된 규칙과 충돌하면 로컬 클라이언트는 호환되는 값으로 대체하고 사용자에게 알립니다. mcp_servers 허용 목록을 구성한 경우 클라이언트는 이름과 ID가 모두 승인된 항목과 일치할 때만 MCP 서버를 활성화하며, 그렇지 않으면 비활성화합니다.

요구 사항은 requirements.toml의 [features] 테이블을 통해 기능 플래그도 제한할 수 있습니다. 기능이 항상 보안에 민감한 것은 아니지만, Enterprise는 필요에 따라 값을 고정할 수 있습니다. 생략한 키는 제한되지 않습니다.

Codex 0.138.0 이상에서는 allowed_permission_profiles 및 관리형 default_permissions이 포함된 권한 프로필을 사용하는 것이 좋습니다. 여전히 sandbox_mode을 구성하는 레거시 배포에서만 allowed_sandbox_modes을 사용하세요.

정확한 키 목록은 Configuration Reference의 requirements.toml 섹션을 참조하세요.

위치 및 우선순위

지원되는 각 로컬 클라이언트는 낮은 우선순위에서 높은 우선순위 순으로 요구 사항을 조합합니다.

  1. 시스템 requirements.toml(Linux 및 macOS를 포함한 Unix 시스템에서는 /etc/codex/requirements.toml, Windows에서는 %ProgramData%\OpenAI\Codex\requirements.toml).
  2. 클라우드 구성 번들로 전달되는 Enterprise 관리형 요구 사항.
  3. 로컬 클라이언트가 요구 사항으로 재해석하는 레거시 managed_config.toml 필드.
  4. com.openai.codex:requirements_toml_base64을 통해 전달되는 macOS 관리형 환경설정(MDM).

우선순위가 높은 계층은 우선순위가 낮은 계층의 일반 스칼라 및 목록 값을 재정의합니다. 테이블은 키를 기준으로 병합되지만 규칙, hook 및 파일 시스템 제한과 같은 요구 사항에는 필드별 조합 동작이 적용됩니다. 모든 필드가 동일한 방식으로 병합된다고 가정하지 말고 현재 스키마는 requirements.toml 참조를 사용하세요.

하위 호환성을 위해 지원되는 로컬 클라이언트는 레거시 approval_policy, approvals_reviewer 및 sandbox_mode 필드를 요구 사항으로 재해석합니다. 이 변환은 필요한 경우 호환성 선택지를 추가합니다. 명시적인 허용 목록에는 requirements.toml을 사용하세요.

클라우드 관리형 요구 사항

사용자가 지원되는 플랜에서 ChatGPT로 로그인하면 지원되는 로컬 클라이언트는 워크스페이스와 연결된 관리자 적용 요구 사항을 받을 수 있습니다. 이는 requirements.toml 호환 정책의 전달 채널입니다. 워크스페이스 액세스를 부여하거나 워크스페이스 RBAC를 대체하지 않습니다.

관리형 구성을 열어 클라우드 관리형 요구 사항을 생성하고 할당하세요. 예를 들어 다음 정책은 지원되는 클라이언트가 미국 데이터 레지던시를 사용하도록 요구하고, 승인 및 샌드박스 선택지를 제한하며, 지원되는 shell 진입점이 실행되기 전에 확인을 요청합니다.

enforce_residency = "us"
allowed_approval_policies = ["on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

[rules]
prefix_rules = [
  { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entry points" },
]

관리되는 모든 클라이언트 버전이 선택한 키를 지원하는지 확인하고 조직 전체에 할당하기 전에 소규모 그룹에서 정책을 테스트하세요. 현재 스키마는 구성 참조를 사용하고 현재 할당 동작은 관리 화면에서 확인하세요.

서비스는 로그인한 ID에 적용되는 Enterprise 관리형 요구 사항 계층을 선택합니다. 로컬 클라이언트는 위치 및 우선순위에 설명된 다른 요구 사항 소스와 함께 해당 계층을 평가합니다. 워크스페이스 측 생성 및 할당에는 현재 관리 화면을 사용하세요. 복사한 그룹 일치 알고리즘에 의존하지 마세요. 해당 동작은 관리 서비스가 소유하며 로컬 요구 사항 형식과 독립적으로 변경될 수 있습니다.

지원되는 키와 예시는 requirements.toml 예시 및 requirements.toml 참조를 확인하세요.

로컬 클라이언트가 클라우드 관리형 요구 사항을 적용하는 방식

사용자가 지원되는 로컬 클라이언트를 시작하고 지원되는 플랜에서 ChatGPT로 로그인하면 클라이언트는 먼저 유효하며 ID가 일치하는 캐시 항목을 확인합니다. 유효한 항목이 없으면 클라이언트는 재시도하여 적용 가능한 번들을 가져오고 성공 시 서명된 캐시 항목을 기록합니다. 요청이 실패하거나 시간 초과되고 유효한 캐시도 없으면 클라우드 구성 번들 로드는 클라우드 관리형 요구 사항 계층 없이 조용히 시작하지 않고 오류를 반환합니다.

캐시를 확인한 후 클라이언트는 클라우드 요구 사항을 위에서 설명한 다른 요구 사항 계층과 조합합니다. 백그라운드 새로 고침은 이후 시작을 위해 캐시를 업데이트할 수 있지만 현재 프로세스에 이미 로드된 요구 사항을 대체하지는 않습니다.

requirements.toml 예시

이 예시는 --ask-for-approval never 및 --sandbox danger-full-access(--yolo 포함)을 차단합니다.

allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

Appshots 비활성화

관리되는 사용자의 Appshots를 비활성화하려면 최상위 allow_appshots 요구 사항을 설정하세요.

allow_appshots = false

Appshots를 사용할 수 있는 환경에서는 allow_appshots = false이 이를 비활성화합니다. 키를 생략하면 요구 사항이 Appshots를 제한하지 않으며 일반적인 제품 가용성 검사가 적용됩니다. configRequirements/read을 통해 유효한 요구 사항을 읽는 앱 서버 클라이언트에는 allowAppshots과 동일한 제한이 적용됩니다. 생략되었거나 null인 allowAppshots 값은 Appshots를 비활성화하지 않습니다.

기기 원격 제어 비활성화

관리되는 사용자의 기기 원격 제어를 비활성화하려면 최상위 allow_remote_control 요구 사항을 설정하세요.

allow_remote_control = false

기기 원격 제어가 지원되는 환경에서는 allow_remote_control = false가 이를 비활성화합니다. 키를 생략하면 요구 사항이 기기 원격 제어를 제한하지 않으며 일반적인 제품 가용성 검사가 적용됩니다. 이 요구 사항은 SSH 원격 연결을 비활성화하지 않습니다.

사용 가능한 권한 프로필 제어

allowed_permission_profiles을 사용하여 사용자가 선택할 수 있는 기본 제공 및 사용자 지정 권한 프로필을 제어하세요. 이는 allowed_sandbox_modes에 대응하는 권한 프로필 설정입니다. 사용자가 권한을 선택하는 방식과 일치하는 허용 목록을 사용하세요.

권한 프로필 허용 목록에는 Codex 0.138.0 이상이 필요합니다. Codex 0.137.0 및 이전 버전은 allowed_permission_profiles 및 관리형 default_permissions을 무시합니다.

관리되는 모든 클라이언트가 지원되는 릴리스를 실행하게 된 후에만 아래 권한 프로필 예시를 사용하세요. 전체 클라이언트 업그레이드가 완료될 때까지 관리형 사용자 지정 프로필을 배포하지 마세요.

테이블이 있으면 허용된 프로필의 전체 목록으로 사용됩니다. true로 설정된 프로필은 허용하고, 생략되거나 false으로 설정된 프로필은 거부하며 향후 Codex 버전에 추가되는 기본 제공 프로필도 거부합니다.

표준 프로필 허용

이 정책은 읽기 전용 및 워크스페이스 액세스를 허용하지만 전체 액세스는 허용하지 않습니다.

default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# ":danger-full-access" is omitted, so it is denied.

관리형 최소 권한 기본값 추가

관리자는 동일한 요구 사항 소스에 사용자 지정 프로필을 정의할 수 있습니다. 사용자의 로드된 구성에 있는 이름과 충돌하지 않는 조직별 프로필 이름을 사용하세요. 사용자 지정 이름은 :으로 시작하거나 예약된 filesystem 이름을 사용할 수 없습니다.

Codex 0.137.0 이하를 실행하는 클라이언트에 관리형 사용자 지정 프로필을 배포하지 마세요. 해당 클라이언트는 프로필 테이블은 인식하지만 이를 선택하는 관리형 기본값은 인식하지 못합니다.

예시:

default_permissions = "acme_review_only"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
acme_review_only = true
# ":danger-full-access" is intentionally omitted, so it is denied.

[permissions.acme_review_only]
description = "Review code without modifying the workspace."
extends = ":read-only"

Enterprise 정의 프로필만 허용

사용자가 관리자 정의 프로필만 선택해야 하는 경우 모든 기본 제공 프로필을 생략하세요.

default_permissions = "acme_workspace"

[allowed_permission_profiles]
acme_workspace = true

[permissions.acme_workspace]
description = "Workspace access with sensitive files denied."
extends = ":workspace"

[permissions.acme_workspace.filesystem]
glob_scan_max_depth = 3

[permissions.acme_workspace.filesystem.":workspace_roots"]
"**/*.env" = "deny"

사용자가 기본 제공 :workspace 프로필을 직접 선택할 수 없더라도 사용자 지정 프로필은 :workspace을 확장할 수 있습니다.

다른 소스에서 허용한 프로필 비활성화

권한 허용 목록은 프로필 이름별로 조합됩니다. 클라우드 요구 사항은 시스템 요구 사항보다 우선순위가 높으므로 false을 사용하여 시스템 파일에서 허용한 프로필을 비활성화할 수 있습니다.

클라우드 요구 사항:

default_permissions = ":read-only"

[allowed_permission_profiles]
":read-only" = true
":workspace" = false

시스템 요구 사항:

[allowed_permission_profiles]
":read-only" = true
":workspace" = true  # Not honored because cloud requirements set this to false.

default_permissions을 허용된 프로필로 명시적으로 설정하세요. 생략하면 :workspace 및 :read-only이 모두 명시적으로 허용된 경우에만 로컬 런타임의 기본값이 :workspace이 됩니다. allowed_permission_profiles이 없으면 관리형 요구 사항은 사용자가 선택할 수 있는 프로필 이름을 제한하지 않습니다. 각 항목은 기본 제공 프로필이나 로드된 구성 또는 요구 사항 소스에 정의된 사용자 지정 프로필의 이름이어야 합니다. 사용자 지정 프로필을 관리형 요구 사항에 정의하여 동작을 중앙에서 제어하세요.

호스트별 샌드박스 요구 사항 재정의

하나의 관리형 정책에서 호스트별로 서로 다른 샌드박스 요구 사항을 적용해야 할 때 [[remote_sandbox_config]]을 사용하세요. 예를 들어 노트북에는 더 엄격한 기본값을 유지하면서 일치하는 개발용 컴퓨터나 CI 실행기에는 워크스페이스 쓰기를 허용할 수 있습니다. 현재 호스트별 항목은 allowed_sandbox_modes만 재정의합니다.

allowed_sandbox_modes = ["read-only"]

[[remote_sandbox_config]]
hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

로컬 런타임은 각 hostname_patterns 항목을 최선의 방식으로 확인된 호스트 이름과 비교합니다. 가능한 경우 정규화된 전체 도메인 이름을 우선 사용하고, 그렇지 않으면 로컬 호스트 이름을 사용합니다. 일치는 대소문자를 구분하지 않습니다. *는 모든 문자 시퀀스와 일치하고 ?는 한 문자와 일치합니다.

동일한 요구 사항 소스 내에서는 처음 일치하는 [[remote_sandbox_config]] 항목이 적용됩니다. 일치하는 항목이 없으면 로컬 런타임은 최상위 allowed_sandbox_modes을 유지합니다. 호스트 이름 일치는 정책 선택에만 사용됩니다. 이를 인증된 기기의 증명으로 간주하지 마세요.

웹 검색 모드도 제한할 수 있습니다.

allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

allowed_web_search_modes = []은 "disabled"만 허용합니다. 예를 들어 allowed_web_search_modes = ["cached"]은 danger-full-access 세션에서도 실시간 웹 검색을 방지합니다.

네트워크 액세스 요구 사항 구성

관리자가 네트워크 액세스 요구 사항을 중앙에서 정의해야 할 때 requirements.toml에서 [experimental_network]을 사용하세요. 이러한 요구 사항은 사용자 features.network_proxy 토글과 별개입니다. 해당 기능 플래그 없이도 샌드박스 네트워킹을 구성할 수 있지만 활성 샌드박스에서 네트워킹을 끈 경우 명령에 네트워크 액세스를 부여하지는 않습니다.

experimental_network.enabled = true
experimental_network.allowed_domains = [
  "api.openai.com",
  "*.example.com",
]
experimental_network.denied_domains = [
  "blocked.example.com",
  "*.exfil.example.com",
]

관리자가 소유한 allowed_domains도 정의하고 해당 허용 목록을 배타적으로 사용하려는 경우에만 experimental_network.managed_allowed_domains_only = true을 사용하세요. 관리형 허용 규칙 없이 true이면 사용자가 추가한 도메인 허용 규칙은 계속 적용되지 않습니다.

도메인 구문, 로컬/비공개 대상 규칙, 허용보다 거부가 우선하는 동작, DNS 리바인딩 제한은 에이전트 승인 및 보안에 설명된 샌드박스 네트워킹 동작과 같습니다.

기능 플래그 고정

관리형 requirements.toml을 받는 사용자의 기능 플래그도 고정할 수 있습니다.

[features]
personality = true
unified_exec = false

# Disable surface-specific features when needed.
browser_use = false
browser_use_full_cdp_access = false
browser_use_external = false
in_app_browser = false
in_app_updates = false
computer_use = false

런타임 기능에는 config.toml의 [features] 테이블에 있는 표준 기능 키를 사용하세요. 로컬 런타임은 인식된 기능을 이러한 고정 값에 맞게 정규화하고 config.toml 또는 프로필 파일 기능 설정에 대한 충돌하는 쓰기를 거부합니다.

  • in_app_browser = false은 기본 제공 브라우저 창을 비활성화합니다.
  • in_app_updates = false은 지원되는 경우 다시 시작할 때 ChatGPT 데스크톱 앱의 자체 업데이터를 비활성화합니다. 외부 패키지 배포에는 영향을 주지 않으며 이전 앱 버전의 지원 기간을 연장하지도 않습니다. 설정 및 출시 지침은 앱 업데이트 관리를 참조하세요.
  • browser_use = false는 브라우저의 Computer Use와 Browser Agent 가용성을 비활성화합니다.
  • browser_use_full_cdp_access = false는 Browser Developer 모드를 포함하여 로컬 런타임의 전체 CDP 액세스를 비활성화하며 ChatGPT 데스크톱 앱에서 해당 설정을 활성화하지 못하게 합니다.
  • browser_use_external = false은 외부 Browser Use를 비활성화합니다.
  • computer_use = false은 Computer Use, Record & Replay 및 관련 설치 또는 설정 흐름을 비활성화합니다.

이러한 키를 생략하면 일반적인 클라이언트, 플랫폼 및 출시 가용성에 따라 정책에서 기능을 허용합니다.

잠긴 컴퓨터 사용 제한

관리되는 Mac이 잠긴 후 Computer Use가 작동하지 못하게 하려면 다음 요구 사항을 추가하세요.

[computer_use]
allow_locked_computer_use = false

이 요구 사항은 Computer Use를 활성화하지 않습니다. macOS에서 잠긴 상태의 사용만 방지합니다. 생략하면 요구 사항이 잠긴 상태의 사용을 제한하지 않으며 일반적인 제품 가용성 및 사용자의 로컬 설정이 계속 적용됩니다.

자동 검토 정책 구성

allowed_approvals_reviewers을 사용하여 자동 검토를 요구하거나 허용하세요. 자동 검토를 요구하려면 ["auto_review"]로 설정하고 사용자가 수동 승인을 선택할 수 있게 하려면 "user"을 포함하세요.

guardian_policy_config을 설정하면 자동 검토 정책의 테넌트별 섹션이 대체됩니다. 로컬 런타임은 여전히 기본 제공 검토자 템플릿과 출력 계약을 사용합니다. 관리형 guardian_policy_config은 로컬 [auto_review].policy보다 우선합니다.

allowed_approval_policies = ["on-request"]
allowed_approvals_reviewers = ["auto_review"]

guardian_policy_config = """
## Environment Profile
- Trusted internal destinations include github.com/my-org, artifacts.example.com,
  and internal CI systems.

## Tenant Risk Taxonomy and Allow/Deny Rules
- Treat uploads to unapproved third-party file-sharing services as high risk.
- Deny actions that expose credentials or private source code to untrusted
  destinations.
"""

읽기 거부 요구 사항 적용

관리자는 [permissions.filesystem]을 사용하여 정확한 경로나 glob 패턴에 대한 읽기를 거부할 수 있습니다. 사용자는 로컬 구성으로 이러한 요구 사항을 완화할 수 없습니다.

[permissions.filesystem]
deny_read = [
  # values can be absolute paths...
  "/**/*.env",
  # ...or relative to $HOME/%USERPROFILE% using `~`.
  "~/.ssh",
  # But relative paths starting with `./` are not allowed.
]

읽기 거부 요구 사항이 있으면 로컬 런타임은 전체 액세스 권한을 거부하고 로컬 실행을 읽기 전용 또는 워크스페이스 샌드박스에서 유지하여 이를 적용할 수 있게 합니다. 네이티브 Windows에서 관리형 deny_read은 직접 파일 도구에 적용되며 shell 하위 프로세스 읽기에는 이 샌드박스 규칙이 적용되지 않습니다.

요구 사항에서 관리형 hook 적용

관리자는 requirements.toml에 관리형 수명 주기 hook을 직접 정의할 수도 있습니다. hook 구성 자체에는 [hooks]을 사용하고, MDM 또는 엔드포인트 관리 도구가 참조된 스크립트를 설치하는 디렉터리를 managed_dir로 지정하세요.

로컬에서 hook을 끈 사용자에게도 관리형 hook을 적용하려면 [hooks]과 함께 [features].hooks = true을 고정하세요. 관리형 hook은 계속 허용하면서 사용자, 프로젝트, 세션 및 플러그인 hook을 건너뛰려면 allow_managed_hooks_only = true을 설정하세요.

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"

참고:

  • 로컬 런타임은 requirements.toml의 hook 구성을 적용하지만 managed_dir의 스크립트를 배포하지는 않습니다.
  • 해당 스크립트는 MDM 또는 기기 관리 솔루션으로 전달하세요.
  • 관리형 hook 명령은 구성된 관리형 디렉터리 아래의 절대 스크립트 경로를 참조해야 합니다.
  • allow_managed_hooks_only = true는 사용자, 프로젝트, 세션 및 플러그인 소스의 hook을 건너뛰지만 requirements.toml 및 다른 관리형 구성 계층의 hook은 계속 로드합니다.

요구 사항에서 명령 규칙 적용

관리자는 [rules] 테이블을 사용하여 requirements.toml에서 제한적인 명령 규칙을 적용할 수도 있습니다. 이러한 규칙은 일반 .rules 파일과 병합되며 가장 제한적인 결정이 계속 우선합니다.

.rules과 달리 요구 사항 규칙에는 decision을 지정해야 하며 해당 결정은 "prompt" 또는 "forbidden"이어야 합니다("allow"은 사용할 수 없음).

[rules]
prefix_rules = [
  { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
  { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
]

로컬 클라이언트가 활성화할 수 있는 MCP 서버를 제한하려면 mcp_servers 승인 목록을 추가하세요. stdio 서버는 command를 기준으로, 스트리밍 가능한 HTTP 서버는 url을 기준으로 일치시키세요.

[mcp_servers.docs]
identity = { command = "codex-mcp" }

[mcp_servers.remote]
identity = { url = "https://example.com/mcp" }

문자열 형식의 identity.command은 구성된 command만 일치시킵니다. args, cwd, env 또는 env_vars은 검사하지 않습니다.

전체 stdio 호출을 제한하려면 실행 파일과 각 위치 인수를 일치시키세요.

[mcp_servers.internal.identity]
command = { executable = "/usr/local/bin/codex-mcp", args = [
  { match = "exact", value = "serve" },
  { match = "prefix", value = "--workspace=" },
] }

실행 파일, 인수 개수 및 인수 순서가 일치해야 합니다. 인수 및 URL 규칙은 exact, prefix 및 전체 값 regex 일치를 지원합니다. 구조화된 명령 규칙도 cwd, env 또는 env_vars은 검사하지 않습니다. 플러그인에 번들된 MCP 서버는 plugins.<plugin>.mcp_servers.<server> 아래에서 동일한 ID 형식을 사용합니다.

mcp_servers이 있지만 비어 있으면 로컬 클라이언트가 모든 MCP 서버를 비활성화합니다.

플러그인 가용성 제어

지원되는 로컬 클라이언트에서 플러그인을 끄려면 requirements.toml에서 features.plugins을 false로 설정하세요.

features.plugins = false

이 설정은 사용자가 API key로 Codex에 로그인할 때도 적용됩니다. 지원되는 구성은 features.plugins 참조를 확인하세요.

플러그인 마켓플레이스 소스 제한

사용자가 구성한 마켓플레이스 소스에 대한 작업을 제한하려면 restrict_to_allowed_sources = true을 설정하고 하나 이상의 소스 규칙을 정의하세요.

[marketplaces]
restrict_to_allowed_sources = true

[marketplaces.allowed_sources.company_plugins]
source = "git"
url = "https://github.com/example/company-plugins.git"
ref = "main"

[marketplaces.allowed_sources.internal_git]
source = "host_pattern"
host_pattern = '^git\.example\.com$'

[marketplaces.allowed_sources.local_plugins]
source = "local"
path = "/opt/company/codex-plugins"

Git 규칙은 정규화된 저장소 URL 및 값이 있는 경우 정확한 ref과 일치합니다. 호스트 패턴은 소문자 Git 호스트와 일치시키는 정규식입니다. 전체 호스트 일치에는 ^ 및 $을 사용하세요. 로컬 규칙에는 절대 정규화 경로가 필요합니다. 전체 스키마와 병합 동작은 requirements.toml 참조를 확인하세요.

이러한 요구 사항은 사용자가 구성한 소스 중 일치하지 않는 소스에 대한 마켓플레이스 추가, 플러그인 설치 및 구성된 Git 마켓플레이스 새로 고침 작업을 거부합니다. Codex 관리형 OpenAI 마켓플레이스는 소스와 예약된 이름이 일치하면 계속 사용할 수 있습니다. 요구 사항은 런타임에서 이미 구성된 사용자 마켓플레이스 또는 해당 플러그인을 필터링하지 않습니다.

이러한 소스 제한은 로컬 클라이언트가 플러그인 마켓플레이스 작업을 지원하는 환경, 즉 ChatGPT Work와 데스크톱 앱의 Codex 및 Codex CLI에만 적용됩니다. Chat, IDE 확장 프로그램 또는 모바일에 플러그인을 추가하지는 않습니다.

관리형 기본값(managed_config.toml)

관리형 기본값은 사용자의 로컬 config.toml 위에 병합되고 모든 CLI --config 재정의보다 우선하여 지원되는 로컬 클라이언트가 시작될 때 초기값을 설정합니다. 사용자는 실행 중에도 해당 설정을 변경할 수 있지만 클라이언트가 다음에 시작될 때 관리형 기본값이 다시 적용됩니다.

ChatGPT로 로그인한 사용자의 관리형 기본값, macOS MDM 프로필 또는 저장된 구성이 gpt-5.4 또는 gpt-5.4-mini을 고정하고 있다면 2026년 8월 31일 전에 업데이트하세요. gpt-5.4을 gpt-5.6-terra으로, gpt-5.4-mini을 gpt-5.6-luna으로 바꾸세요. 자체 API key로 인증한 OpenAI API와 Codex는 영향을 받지 않습니다. 워크스페이스 모델 가용성을 참조하세요.

관리형 기본값이 요구 사항을 충족하는지 확인하세요. 로컬 런타임은 허용되지 않은 값을 거부합니다.

우선순위 및 계층화

로컬 런타임은 다음 순서로 유효한 구성을 조합합니다(위쪽이 아래쪽보다 우선함).

  • 관리형 환경설정(macOS MDM, 가장 높은 우선순위)
  • managed_config.toml(시스템/관리형 파일)
  • config.toml(사용자의 기본 구성)

CLI --config key=value 재정의는 기본 구성에 적용되지만 관리형 계층이 이를 재정의합니다. 따라서 로컬 플래그를 제공하더라도 각 실행은 관리형 기본값으로 시작됩니다.

클라우드 관리형 요구 사항은 관리형 기본값이 아니라 요구 사항 계층에 영향을 줍니다. 우선순위는 위의 관리자가 적용하는 요구 사항 섹션을 참조하세요.

위치

  • Linux/macOS (Unix): /etc/codex/managed_config.toml
  • Windows/non-Unix: ~/.codex/managed_config.toml

파일이 없으면 로컬 런타임은 관리형 계층을 건너뜁니다.

macOS 관리형 환경설정(MDM)

macOS에서 관리자는 다음 위치에 base64로 인코딩된 TOML 페이로드를 제공하는 기기 프로필을 푸시할 수 있습니다.

  • 환경설정 도메인: com.openai.codex
  • 키:
    • config_toml_base64(관리형 기본값)
    • requirements_toml_base64(요구 사항)

로컬 런타임은 이러한 "관리형 환경설정" 페이로드를 TOML로 구문 분석합니다. 관리형 기본값(config_toml_base64)의 경우 관리형 환경설정의 우선순위가 가장 높습니다. 요구 사항(requirements_toml_base64)의 우선순위는 위에서 설명한 클라우드 관리형 요구 사항 순서를 따릅니다. 동일한 요구 사항 측 [features] 테이블을 requirements_toml_base64에서 사용할 수 있으며 여기에서도 표준 기능 키를 사용하세요.

MDM 설정 워크플로

로컬 런타임은 표준 macOS MDM 페이로드를 지원하므로 Jamf Pro, Fleet 또는 Kandji 같은 도구로 설정을 배포할 수 있습니다. 간단한 배포 과정은 다음과 같습니다.

  1. 관리형 페이로드 TOML을 작성하고 base64으로 인코딩합니다(줄 바꿈 없음).
  2. MDM 프로필의 com.openai.codex 도메인에서 config_toml_base64(관리형 기본값) 또는 requirements_toml_base64(요구 사항)에 문자열을 넣습니다.
  3. 프로필을 푸시한 다음 사용자에게 지원되는 로컬 클라이언트를 다시 시작하고 시작 구성 요약에 관리형 값이 반영되었는지 확인하도록 요청합니다.
  4. 정책을 취소하거나 변경할 때 관리형 페이로드를 업데이트합니다. 클라이언트는 다음에 시작될 때 새로 고쳐진 환경설정을 읽습니다.

페이로드에 비밀 정보나 자주 변경되는 동적 값을 포함하지 마세요. 관리형 TOML을 변경 관리 대상인 다른 MDM 설정과 동일하게 취급하세요.

managed_config.toml 예시

# Set conservative defaults
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[sandbox_workspace_write]
network_access = false             # keep network disabled unless explicitly allowed

[otel]
environment = "prod"
exporter = "otlp-http"            # point at your collector
log_user_prompt = false            # keep prompts redacted
# exporter details live under exporter tables; see Monitoring and telemetry above

권장 보호 조치

  • 대부분의 사용자에게는 승인과 함께 workspace-write을 사용하는 것이 좋으며 전체 액세스는 통제된 컨테이너에만 허용하세요.
  • 보안 검토에서 수집기 또는 워크플로에 필요한 도메인을 허용하지 않는 한 network_access = false을 유지하세요.
  • 관리형 구성을 사용하여 OTel 설정(exporter, environment)을 고정하되, 정책에서 프롬프트 콘텐츠 저장을 명시적으로 허용하지 않는 한 log_user_prompt = false을 유지하세요.
  • 로컬 config.toml과 관리형 정책의 diff를 정기적으로 감사하여 구성 드리프트를 감지하세요. 관리형 계층은 로컬 플래그 및 파일보다 우선해야 합니다.