관리형 구성

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

엔터프라이즈 관리자는 다음 항목으로 지원되는 로컬 클라이언트의 동작을 제어할 수 있습니다.

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

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

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

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

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

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

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

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

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

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

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

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

더 엄격한 명령어 승인을 유지하려면 approval_policy을 명시적으로 설정하지 말고, 사용자 수준 ~/.codex/config.toml의 프로젝트 항목에 trust_level = "untrusted"를 설정한 뒤, allowed_approval_policies에 untrusted를 유지하세요. 이렇게 하면 프로젝트 로컬 구성도 비활성화됩니다. 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" },
]

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

서비스는 로그인한 사용자에게 적용할 엔터프라이즈 관리형 요구 사항 계층을 선택합니다. 로컬 클라이언트는 이 계층을 위치 및 우선순위에 설명된 다른 요구 사항 소스와 함께 평가합니다. 워크스페이스에서 요구 사항을 만들고 할당하려면 현재 관리 화면을 사용하세요. 복사한 그룹 매칭 알고리즘에 의존하지 마세요. 이 동작은 관리 서비스가 담당하며, 로컬 요구 사항 형식과 별개로 변경될 수 있습니다.

지원되는 키와 예시는 requirements.toml 예시와 requirements.toml 참조 자료를 참고하세요.

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

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

캐시 처리가 끝나면 클라이언트는 클라우드 요구 사항을 앞서 설명한 다른 요구 사항 계층과 결합합니다. 백그라운드 새로고침은 다음 시작에 사용할 캐시를 업데이트할 수 있지만, 현재 프로세스에 이미 로드된 요구 사항을 교체하지는 않습니다.

관리자 및 직원 경험 확인

각 관리형 정책의 담당자를 지정하고, 정책을 받을 사용자나 그룹을 기록하세요. 파일 시스템, 네트워크, 승인 또는 권한 프로필에 제한을 두는 경우에는 그 업무상 이유를 문서화하세요.

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

로컬에서 인증 관리

로컬 시스템 requirements.toml 또는 macOS MDM 요구 사항에서 allowed_login_methods, allowed_chatgpt_workspaces, cli_auth_credentials_store, chatgpt_base_url를 설정하세요. 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"을 명시적으로 설정하는 방식이 지원되는 것은 아닙니다.

앱샷 비활성화

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

allow_appshots = false

앱샷을 사용할 수 있는 환경에서는 allow_appshots = false로 앱샷을 비활성화할 수 있습니다. 이 키를 생략하면 요구 사항은 앱샷을 제한하지 않으며, 일반적인 제품 이용 가능 여부 확인이 적용됩니다. 실제 적용된 요구 사항을 configRequirements/read로 읽는 App Server 클라이언트는 allowAppshots 필드로 동일한 제한을 전달받습니다. allowAppshots 값이 생략되거나 null인 경우에는 앱샷이 비활성화되지 않습니다.

기기 원격 제어 비활성화

관리 대상 사용자의 기기 원격 제어를 비활성화하려면 최상위 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.domains]에 관리자가 관리하는 "allow" 항목을 함께 정의하고 해당 규칙만 적용하려는 경우에만 experimental_network.managed_allowed_domains_only = true를 사용하세요. 관리형 허용 규칙 없이 true로 설정하면 사용자가 추가한 도메인 허용 규칙은 더 이상 적용되지 않습니다. 표준 domains 맵을 레거시 allowed_domains 또는 denied_domains 목록과 함께 사용하지 마세요.

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

도메인 구문, 로컬 및 사설 목적지 규칙, 허용보다 거부를 우선하는 동작, DNS 리바인딩 제한은 에이전트 승인 및 보안에 설명된 샌드박스 네트워킹 동작과 동일합니다.

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

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

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

브라우저 및 컴퓨터 사용 제어

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

브라우저 접근에는 오리진 정책을 구성하세요. 오리진은 https://example.com 또는 https://*.example.com:8443처럼 스킴, 호스트, 선택적 포트를 포함합니다. 경로, 쿼리 또는 프래그먼트는 포함하지 마세요. 명령어 네트워크의 도메인 규칙과 달리 브라우저 오리진 규칙은 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"

일치하는 오리진 규칙은 필드별로 평가됩니다. 일치하는 거부 규칙이 우선하며, 그 외에는 일치하는 규칙에서 지정하지 않은 필드를 기본 오리진 정책으로 채웁니다. 로컬 구성으로 제한을 추가할 수 있지만 관리형 거부 규칙을 완화할 수는 없습니다. 네트워크 거부 규칙과 배타적 관리형 네트워크 허용 목록도 계속 적용됩니다.

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

네이티브 앱에는 기본 접근 정책을 설정하고 허용할 앱을 지정하세요. 예를 들어 다음 macOS 정책은 계산기를 허용하고 승인 저장을 차단합니다.

[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은 선택 사항입니다. 앱의 표시 이름만 사용하지 말고 검증된 식별 정보를 사용하세요.

전체 필드는 구성 참조 자료를 확인하세요. 관리 대상 macOS 기기에 대해서는 잠금 상태에서의 사용 제한을 참조하세요.

기능 플래그 고정

관리형 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로 설정하면 브라우저에서 컴퓨터 사용 기능과 브라우저 에이전트를 사용할 수 없게 됩니다.
• browser_use_full_cdp_access = false로 설정하면 브라우저 개발자 모드를 포함한 로컬 런타임의 전체 CDP 접근이 비활성화되며, ChatGPT 데스크톱 앱에서 해당 설정을 활성화할 수 없게 됩니다.
• browser_use_external = false로 설정하면 외부 브라우저 기능이 비활성화됩니다.
• computer_use = false로 설정하면 컴퓨터 사용, 기록 및 재생, 관련 설치 또는 설정 플로우가 비활성화됩니다.

이 키들을 생략하면 정책상 해당 기능이 허용되며, 실제 사용 가능 여부는 일반적인 클라이언트, 플랫폼 및 배포 상태에 따라 결정됩니다.

잠금 상태에서의 컴퓨터 사용 제한

사용자가 관리 대상 Mac에서 잠금 상태에서 사용을 활성화하지 못하도록 하려면 다음 요구 사항을 추가하세요.

[computer_use]
allow_locked_computer_use = false

이 요구 사항은 잠금 상태에서 사용 기능을 활성화하는 제어 항목을 제거합니다. 이미 활성화된 잠금 상태에서 사용 기능을 끄지는 않습니다. 이 요구 사항을 생략하면 일반적인 제품 제공 범위와 사용자의 로컬 설정이 계속 적용됩니다.

자동 검토 정책 구성

자동 검토를 필수로 지정하거나 허용하려면 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 및 다른 관리형 구성 계층의 훅은 계속 로드합니다.

요구사항으로 명령어 규칙 강제 적용

관리자는 requirements.toml의 [rules] 테이블을 사용해 명령어를 제한하는 규칙을 강제 적용할 수도 있습니다. 이 규칙은 일반 .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> 아래에서 동일한 식별 정보 구조를 사용합니다.

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

플러그인 사용 가능 여부 제어

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

features.plugins = false

이 설정은 사용자가 API 키로 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 키 카탈로그를 비롯해 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로 지정한 재정의 값보다 우선합니다. 사용자는 현재 실행 중에도 이 설정을 변경할 수 있으며, 다음에 클라이언트를 시작하면 기본값이 다시 적용됩니다.

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 키로 인증한 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/비 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과 관리형 정책의 차이를 주기적으로 점검해 설정이 정책에서 벗어나는지 확인하세요. 관리형 계층이 로컬 플래그와 파일보다 우선해야 합니다.