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

관리형 구성

관리형 구성

지원되는 로컬 클라이언트 전반에 구성 기본값을 배포하고 요구 사항을 강제 적용합니다

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

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

  • 요구 사항: 관리자가 강제 적용하는 제약 조건으로, 사용자가 재정의할 수 없습니다.
  • 구성 기본값: 시스템 또는 클라우드에서 관리하는 config.toml 설정으로, 사용자가 재정의할 수 있습니다.
  • 레거시 관리형 기본값: 지원되는 클라이언트가 시작될 때 적용되는 managed_config.toml의 초기값입니다. 사용자는 실행 중에도 설정을 변경할 수 있으며, 클라이언트는 다음에 시작될 때 이 기본값을 다시 적용합니다.

플러그인 마켓플레이스 및 기본값 구성

로컬 또는 Git 마켓플레이스와 플러그인 기본값을 시스템 config.toml 또는 관리형 구성의 config.toml 섹션에 정의하세요. 이 설정은 기본값이며 강제 적용되는 정책이 아닙니다.

구성 키는 구성 참조를, 재정의는 구성 우선순위를 참조하고, 프로젝트 수준 구성은 저장소 플러그인 설정을 참조하세요. 워크스페이스 GitHub 가져오기 및 동기화는 별개입니다.

관리자가 강제하는 요구 사항(requirements.toml)

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

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

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

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

지원이 종료된 untrusted 승인 정책 마이그레이션

Codex와 ChatGPT Work는 더 이상 approval_policy = "untrusted"를 지원하지 않습니다. 관리형 기본값, 레거시 managed_config.toml 및 해당 값을 설정하는 모든 사용자, 프로젝트, 프로필 또는 시작 구성에서 이를 제거하세요.

대화형 읽기 전용 사용 시에는 approval_policy = "on-request"를 선택하고 관리 요구 사항에서 허용하는 읽기 전용 샌드박스 또는 권한 프로필을 사용하세요. 해당 샌드박스에서 허용하는 명령은 승인 없이 실행할 수 있습니다.

더 엄격한 명령 승인 동작을 유지하려면 approval_policy를 명시적으로 지정하지 말고, 사용자 수준 설정 파일의 프로젝트 항목에 trust_level = "untrusted"를 설정하세요. 해당 파일은 ~/.codex/config.toml이며, untrusted는 allowed_approval_policies에 유지하세요. 이렇게 하면 프로젝트 로컬 설정도 비활성화됩니다. on-request를 명시적으로 설정하면 해당 정책을 재정의합니다. 예제와 보안상의 절충 사항은 폐지된 untrusted 승인 정책에서 마이그레이션을 참고하세요.

위치 및 우선순위

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

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

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

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

클라우드 관리형 요구 사항

사용자가 지원되는 요금제에서 ChatGPT로 로그인하면, 지원되는 로컬 클라이언트는 워크스페이스에 연결된 관리자 강제 요구 사항을 받을 수 있습니다. 이는 requirements.toml과 호환되는 정책의 전달 채널입니다. 워크스페이스 접근 권한을 부여하거나 워크스페이스 RBAC를 대체하지는 않습니다. 인증 요구 사항은 로컬에서 관리해야 합니다.

클라우드 관리형 요구 사항을 만들고 할당하려면 관리형 구성을 여세요. 예를 들어 다음 정책은 승인 및 샌드박스 선택지를 제한하고, 지원되는 셸 진입점이 실행되기 전에 확인을 요청합니다.

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

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

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

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

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

관리자 및 직원 환경 확인

각 관리형 정책의 담당자를 지정하고, 정책을 적용할 사용자 또는 그룹을 기록하며, 파일 시스템, 네트워크, 승인 또는 권한 프로필 제한을 설정한 비즈니스 이유를 문서화하세요.

출시 범위를 확대하기 전에 대표 사용자와 함께 승인된 워크플로와 의도적으로 허용하지 않은 워크플로를 테스트하세요. 워크스페이스 역할이나 그룹만으로 로컬 제한이 적용된다고 가정하지 말고 지원되는 클라이언트에서 유효 설정을 확인하세요.

로컬에서 인증 관리

allowed_login_methods, allowed_chatgpt_workspaces, cli_auth_credentials_store, chatgpt_base_url 네 설정을 로컬 시스템의 requirements.toml 또는 macOS MDM 요구 사항에 설정하세요. Codex는 이 네 필드를 클라우드 관리 요구 사항에서는 무시합니다. 로컬 인증 요구 사항은 자격 증명을 로드하기 전과 Codex가 클라우드 정책을 가져오기 전에 적용됩니다.

승인된 워크스페이스에 ChatGPT로 로그인하도록 요구하고 자격 증명을 OS 자격 증명 저장소에 저장하려면 다음을 사용하세요:

allowed_login_methods = ["chatgpt"]
allowed_chatgpt_workspaces = ["00000000-0000-0000-0000-000000000000"]
cli_auth_credentials_store = "keyring"

allowed_login_methods에는 chatgpt, api 또는 둘 다 지정할 수 있습니다. 생략하면 이 설정은 로그인 방식을 제한하지 않습니다. 설정하는 경우 목록에 하나 이상의 방식이 포함되어야 합니다. api는 Amazon Bedrock을 포함한 API 인증을 허용합니다. 워크스페이스 제한은 다음에도 적용됩니다: Codex 액세스 토큰.

사용자가 설정한 forced_login_method와 forced_chatgpt_workspace_id는 요구 사항을 따라야 합니다. 사용자가 선택한 워크스페이스는 관리되는 워크스페이스 허용 목록에도 있어야 합니다. 일치하는 워크스페이스가 없으면 ChatGPT 로그인을 사용할 수 없습니다. API 인증은 허용된 경우 계속 사용할 수 있습니다. 사용 가능한 로그인 방식이 없으면 Codex는 시작을 거부합니다.

요구 사항 참조에서 자격 증명 저장 모드와 서비스 URL 설정을 확인하세요.

requirements.toml 예시

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

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

여기서 untrusted는 다음 설정에서 파생된 더 엄격한 승인 동작을 유지합니다: trust_level = "untrusted". 그렇다고 approval_policy = "untrusted"를 명시적으로 지정하는 설정이 지원되는 것은 아닙니다.

Appshots 비활성화

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

allow_appshots = false

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

엔터프라이즈에서 정의한 프로필만 허용

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

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]
enabled = true
managed_allowed_domains_only = true

[experimental_network.domains]
"api.openai.com" = "allow"
"**.example.com" = "allow"
"blocked.example.com" = "deny"
"**.exfil.example.com" = "deny"

experimental_network.managed_allowed_domains_only = true는 [experimental_network.domains]에도 관리자 소유 "allow" 항목을 정의하고 해당 규칙을 배타적으로 적용하려는 경우에만 사용하세요. 관리형 허용 규칙 없이 true이면 사용자가 추가한 도메인 허용 규칙은 더 이상 유효하지 않습니다. 정식 domains 맵을 레거시 allowed_domains 또는 denied_domains 목록과 함께 사용하지 마세요.

*.example.com은 하위 도메인에만 일치합니다. **.example.com은 루트 도메인과 그 하위 도메인에 일치합니다. 일치하는 거부 규칙은 허용 규칙보다 우선합니다.

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

프록시는 샌드박스 내에서 실행되는 로컬 명령의 트래픽을 라우팅합니다. 브라우저 도구도 origin에 액세스하기 전에 관리형 네트워크 거부 및 배타적 허용 목록을 확인합니다. 이는 별도의 정책 검사이며 브라우저 트래픽을 명령 프록시를 통해 라우팅하는 것이 아닙니다. 웹 검색, 앱과 커넥터, MCP 서버, 네이티브 앱 트래픽, Codex 서비스 요청 또는 Codex 클라우드 트래픽은 필터링하지 않습니다. 각 영역에 맞는 제어 기능을 사용하세요.

  • 웹 검색을 제한하려면 allowed_web_search_modes를 사용하세요.
  • 앱 및 커넥터 통합을 비활성화하려면 features.apps = false를 사용하고, 지원되는 환경에서 플러그인을 비활성화하려면 features.plugins = false를 사용하세요.
  • MCP 서버를 제한하려면 관리형 mcp_servers 승인 목록을 사용하세요.
  • 브라우저 및 Computer Use 기능을 제한하려면 browser_use, in_app_browser 및 computer_use와 같은 기능 요구 사항을 사용하세요.
  • Codex 클라우드 네트워크 액세스는 해당 클라우드 환경 설정에서 구성하세요.

명령 도메인 허용 목록은 이러한 기능별 제어 기능을 대체하지 않습니다.

브라우저 및 Computer Use 제어

지원되는 데스크톱 클라이언트를 제한하려면 requirements.toml의 [browser_use] 및 [computer_use] 테이블을 사용하세요. 배포 환경의 클라이언트 버전과 운영 체제에서 정책을 검증하세요. 구성된 허용 규칙은 플러그인을 설치하거나, 운영 체제 권한을 부여하거나, 여전히 검토가 필요한 작업을 승인하지 않습니다.

브라우저 액세스에는 origin 정책을 구성하세요. origin은 스킴, 호스트 및 선택적 포트를 포함하며, 예를 들면 https://example.com 또는 https://*.example.com:8443입니다. 경로, 쿼리 또는 프래그먼트는 포함하지 마세요. 명령 네트워크 도메인 규칙과 달리 브라우저 origin 규칙은 HTTP와 HTTPS를 구분하고 포트도 일치시킵니다.

다음 예시는 브라우저 액세스를 승인된 사이트로 제한하고 해당 사이트에서 업로드와 전체 Chrome DevTools Protocol (CDP) 액세스를 방지합니다.

[browser_use]
allow_history_access = false
allow_global_persistent_approval = false

[browser_use.default_origin_policy]
access = "deny"

[browser_use.origins."https://example.com"]
access = "allow"
uploads = "deny"
downloads = "allow"
full_cdp_access = "deny"
persistent_approval = false
access_approval_lifetime = "turn"

일치하는 origin 규칙은 필드별로 해석됩니다. 일치하는 거부가 우선하며, 그렇지 않으면 기본 origin 정책이 일치하는 규칙에 지정되지 않은 필드를 제공합니다. 로컬 구성은 제한을 추가할 수 있지만 관리형 거부를 완화할 수는 없습니다. 네트워크 거부 및 배타적 관리형 네트워크 허용 목록도 계속 적용됩니다.

브라우저 작업의 자동 승인 검토를 비활성화하려면 browser_use.disable_auto_review = true를 설정하거나, 특정 origin에서 이를 제한하려면 origin 정책에 auto_review = "deny"를 설정하세요. 이는 승인 처리를 제어하며 모델 안전 모니터링을 비활성화하지는 않습니다.

네이티브 앱에는 기본 액세스 정책을 설정하고 허용되는 앱을 식별하세요. 예를 들어 다음 macOS 정책은 Calculator를 허용하고 저장된 승인을 방지합니다.

[computer_use]
default_app_access = "deny"
allow_persistent_approval = false

[computer_use.macos.bundle_ids]
"com.apple.calculator" = "allow"

Windows 정책은 computer_use.windows.aumids를 사용해 패키지 앱을 식별하거나 computer_use.windows.exes를 사용해 실행 파일을 식별할 수 있습니다. 실행 파일 규칙에는 publisher_name, product_name 및 access가 필요하며 binary_name은 선택 사항입니다. 표시 이름만 사용하지 말고 앱의 검증된 ID를 사용하세요.

전체 필드는 구성 참조를, 관리형 macOS 기기에 대해서는 Locked Use 제한을 참조하세요.

기능 플래그 고정

관리형 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에서 사용자가 Locked Use를 활성화하지 못하게 하려면 다음 요구 사항을 추가하세요.

[computer_use]
allow_locked_computer_use = false

이 요구 사항은 Locked Use를 활성화하는 제어 기능을 제거합니다. 이미 활성화된 Locked Use를 끄지는 않습니다. 이를 생략하면 일반적인 제품 가용성 및 사용자의 로컬 설정이 계속 적용됩니다.

자동 검토 정책 구성

자동 검토를 필수로 설정하거나 허용하려면 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이 직접 파일 도구에 적용되며, 셸 하위 프로세스의 읽기에는 이 샌드박스 규칙이 적용되지 않습니다.

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

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

로컬에서 훅을 끈 사용자에게도 관리형 훅을 적용하려면 [hooks]과 함께 [features].hooks = true을 고정하세요. 관리형 훅은 계속 허용하면서 사용자, 프로젝트, 세션 및 플러그인 훅을 건너뛰려면 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의 훅 구성을 적용하지만, managed_dir의 스크립트를 배포하지는 않습니다.
  • 해당 스크립트는 MDM 또는 기기 관리 솔루션으로 배포하세요.
  • 관리형 훅 명령은 구성된 관리형 디렉터리 아래의 절대 스크립트 경로를 참조해야 합니다.
  • allow_managed_hooks_only = true은 사용자, 프로젝트, 세션 및 플러그인 소스의 훅을 건너뛰지만, requirements.toml 및 다른 관리형 구성 계층의 훅은 계속 로드합니다.

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

관리자는 [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 마켓플레이스 새로 고침 작업을 거부합니다. 또한 런타임에 설정된 마켓플레이스와 해당 플러그인을 필터링합니다.

API key 카탈로그를 포함해 OpenAI가 큐레이션한 Git 마켓플레이스도 소스 허용 목록과 일치해야 합니다. 이를 허용하려면 다음 Git 소스를 ref 제약 조건 없이 포함하세요:

[marketplaces.allowed_sources.openai_curated]
source = "git"
url = "https://github.com/openai/plugins.git"

큐레이션된 카탈로그를 제외하려면 해당 소스를 생략하고 더 넓은 범위의 호스트 규칙에서도 허용하지 않는지 확인하세요. 번들로 제공되는 플러그인과 원격으로 설치된 워크스페이스 플러그인은 이 큐레이션된 Git 소스 정책과 별개입니다.

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

관리형 기본값(managed_config.toml)

관리형 기본값은 지원되는 로컬 클라이언트가 시작할 구성을 설정합니다. 시작할 때 사용자의 로컬 config.toml 및 모든 CLI --config 재정의를 덮어씁니다. 사용자는 현재 실행 중에도 해당 설정을 변경할 수 있으며, 다음에 클라이언트를 시작하면 기본값이 다시 적용됩니다.

관리형 기본값, macOS MDM 프로필 또는 저장된 구성에서 ChatGPT로 로그인한 Codex 사용자의 모델을 gpt-5.5로 고정했다면, 2026년 10월 14일 전에 이를 gpt-5.6-sol로 교체하세요. 해당 날짜에 GPT-5.5는 ChatGPT, ChatGPT Work, Codex의 모든 요금제에서 지원이 종료됩니다. OpenAI API는 영향을 받지 않습니다. 워크스페이스 모델 가용성을 참조하세요.

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로 교체하세요. OpenAI API와 자체 API key로 인증한 Codex는 영향을 받지 않습니다. 워크스페이스 모델 가용성을 참조하세요.

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

우선순위 및 계층화

로컬 런타임은 다음 순서로 유효 구성을 조합합니다(위 항목이 아래 항목을 재정의함).

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

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

클라우드 config.toml은 일반 설정 우선순위를 사용하며, 위의 레거시 순서를 따르지 않습니다. 클라우드 requirements.toml은 요구 사항 우선순위를 사용합니다.

위치

  • 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 설정(내보내기 도구, 환경)을 고정하되, 정책에서 프롬프트 콘텐츠 저장을 명시적으로 허용하지 않는 한 log_user_prompt = false을 유지하세요.
  • 로컬 config.toml과 관리형 정책 간의 차이를 정기적으로 감사해 드리프트를 찾으세요. 관리형 계층은 로컬 플래그 및 파일보다 우선해야 합니다.