관리형 구성

엔터프라이즈 관리자는 관리형 구성으로 ChatGPT Work와 Codex에서 지원하는 요구 사항과 기본값을 설정할 수 있습니다. 요구 사항은 사용자와 작업이 수행할 수 있는 동작을 제한하고, 기본값은 시작 시 사용할 값을 지정합니다. 지원 범위는 제품, 클라이언트 버전, 실행 환경에 따라 다릅니다.

클라우드에서 관리할 수 있는 설정은 관리 콘솔의 에이전트 보안에서 구성하세요. 일반적인 작업에는 설정 컨트롤을 사용하세요. 구성 텍스트를 확인하거나 복사 또는 편집하려면 TOML로 편집을 선택하세요. 두 보기에서 편집하는 정책은 같습니다. TOML 보기에서는 전용 컨트롤이 없는 지원 필드도 편집할 수 있습니다. 클라우드 관리형 설정을 사용하기 위해 로컬 파일을 배포할 필요는 없습니다. 인증 제한과 디바이스 관리형 배포에는 별도의 로컬 설정 절차가 있습니다.

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

• 요구 사항은 관리자가 강제하는 제한으로, 사용자가 재정의할 수 없습니다.

• 구성 기본값은 시스템 또는 클라우드에서 관리하는 config.toml 설정으로, 사용자가 재정의할 수 있습니다.

• 레거시 관리형 기본값은 지원되는 클라이언트를 시작할 때 적용하는 managed_config.toml의 초기값입니다. 사용자는 실행 중에도 설정을 변경할 수 있습니다. 다음에 클라이언트를 시작하면 클라이언트가 이 기본값을 다시 적용합니다.

전역 기준 설정, 환경별 재정의, 오케스트레이터와 실행기의 필드 목록은 에이전트 보안을 참조하세요.

사용자가 ChatGPT로 Codex에 로그인하지 않는 경우, 직접 운영하는 HTTPS 엔드포인트에서 Codex CLI와 데스크톱 앱에 기본값과 요구 사항을 배포할 수 있습니다. 팀의 Codex 구성 서버 직접 호스팅을 참조하세요.

에이전트 보안에서 정책 구성하기

에이전트 보안이 활성화된 워크스페이스에서는 워크스페이스 소유자, 워크스페이스 관리자, Codex 관리자 권한이 있는 멤버가 정책을 관리할 수 있습니다. 멤버에게 정책 편집기 접근 권한이 있어도 해당 정책이 제어하는 기능에 대한 접근 권한이 부여되지는 않습니다.

워크스페이스의 기준 설정에는 워크스페이스 기본값을 사용하세요. 특정 사용자, 그룹 또는 역할에 다른 설정이 필요하면 재정의를 사용하세요. 대상별 재정의는 정책을 받을 대상을 정하고, 환경 설정은 지원되는 실행 제어가 적용될 위치를 정합니다.

1. 관리 콘솔 > 에이전트 보안을 열고 워크스페이스 기본값을 선택하거나 재정의에서 편집할 정책을 선택하세요.
2. 강제할 제한을 설정하려면 요구 사항을 여세요. 멤버가 해당 제한 내에서 변경할 수 있는 초기값을 설정하려면 기본값을 여세요.
3. 승인, 웹 검색 등 에이전트 전체에 적용되는 설정은 전역에 두세요. 해당 카드에서 환경 설정 추가를 사용할 수 있으면 로컬 환경 또는 Codex Cloud 환경을 추가해 지원되는 실행 설정을 구성하세요. 빈 환경 문서는 전역 설정을 상속합니다. 현재 기준 설정을 복사하거나 고정하지 않습니다.
4. 이 가이드에 설명된 컨트롤을 사용하세요. 고급 필드를 설정하려면 TOML로 편집을 선택하고 해당 범위의 requirements.toml 또는 config.toml을 편집하세요. 시각적 편집기로 돌아가려면 설정 컨트롤 사용을 선택하세요.
5. 유효성 검사 메시지를 확인한 다음 변경 사항 저장을 선택하세요. 규칙 편집기에서 규칙을 적용하면 초안이 업데이트됩니다. 정책은 별도로 저장해야 합니다.
6. 관리자와 직원의 사용 환경 확인하기에 따라 선택된 정책과 지원되는 클라이언트의 동작을 확인하세요.

사용할 수 있는 환경 편집기와 지원 필드는 워크스페이스와 정책에 따라 다릅니다. 전역 설정을 환경으로 옮기기 전에 설정 적용 범위를 확인하세요. 전역에 둔 설정이라도 모든 제품이나 실행 경로에 적용되는 것은 아닙니다.

구성 복사 또는 재사용하기

시각적 편집기를 사용해도 TOML을 계속 사용할 수 있습니다. 구성을 복사하거나 참조용 사본을 보관하거나 다른 정책에서 설정을 재사용하려면 TOML로 편집을 선택하세요. 시각적 편집기로 돌아가려면 설정 컨트롤 사용을 선택하세요.

1. 원본 정책을 열고 TOML로 편집을 선택하세요.
2. 복사할 범위로 전역 또는 사용 가능한 환경 탭을 선택하세요. 재사용할 항목에 따라 요구 사항(requirements.toml), 기본값(config.toml) 또는 둘 다에서 텍스트를 복사하세요.
3. 대상 정책을 열고 TOML로 편집을 선택한 다음 원본과 같은 범위를 선택하세요. 요구 사항은 requirements.toml에, 기본값은 config.toml에 붙여 넣으세요. 텍스트를 교체하기 전에 대상 정책의 기존 설정을 검토하고, 계속 적용해야 하는 다른 설정은 유지하세요.
4. 유효성 검사 메시지와 대상 정책의 적용 대상 및 우선순위를 확인한 다음 변경 사항 저장을 선택하세요. 복사한 정책을 실제로 사용하기 전에 클라이언트가 의도대로 동작하는지 확인하세요.

복사한 텍스트에는 해당 정책의 해당 범위에 직접 작성한 설정이 들어 있습니다. 정책 할당, 정책 순서, 다른 환경 문서, 다른 정책과 디바이스 설정을 조합한 최종 구성은 포함되지 않습니다. 필요한 환경 설정은 별도로 복사하세요. 보기를 전환하거나 텍스트를 복사해도 정책 변경 사항은 저장되지 않습니다.

아래 예제에서 설정을 변경한 다음 TOML로 편집을 선택해 해당 구성을 확인하세요. 설정 컨트롤 사용을 선택해 돌아가면 다른 설정도 시험해 볼 수 있습니다.

작업에 맞는 설정 선택하기

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

지원되는 데스크톱 클라이언트의 브라우저 및 네이티브 앱 접근은 관리 콘솔의 에이전트 보안에서 관리하세요. 먼저 UI 컨트롤을 사용하세요. 파일로 정책을 배포하거나 TOML 편집기가 필요한 설정을 구성할 때는 아래 TOML 예제를 참고하세요.

브라우저 기능은 에이전트가 브라우저에서 수행하는 동작을 제어합니다. 컴퓨터 사용 기능은 에이전트가 네이티브 데스크톱 앱에서 수행하는 동작을 제어합니다. 내장 브라우저 창은 브라우저 기능과 별도로 설정합니다. 브라우저 접근 경로별 차이점은 브라우저 세션 및 기존 로그인을 참조하세요.

시작하기 전에

에이전트 보안 정책을 관리할 권한이 있는 계정을 사용하세요. 정책을 받을 사용자와 지원해야 하는 클라이언트 버전 및 운영 체제를 확인하세요. 정책 할당, 전역 설정, 지원되는 환경별 재정의는 에이전트 보안을 참조하세요.

사용자가 재정의할 수 없는 제한은 요구 사항에서 설정하세요. 기본값은 해당 제한 내에서 초기값을 정합니다. 사이트나 앱을 허용해도 플러그인 설치, 운영 체제 권한 부여, 사용자 로그인, 검토가 필요한 동작의 승인이 자동으로 이루어지지는 않습니다.

데스크톱 기능 사용 가능 여부에서 브라우저, 외부 브라우저, 컴퓨터 사용을 확인하세요. 강제 비활성화는 해당 기능을 끕니다. 사이트나 앱의 허용 규칙으로 이 설정을 재정의할 수 없습니다. 전체 CDP 접근은 별도로 검토하세요. 사용자 활성화 차단을 선택하면 사용자가 이 기능을 켤 수 없습니다.

이 데스크톱 설정은 호스팅되는 Work Cloud 브라우저에 적용되지 않습니다. 클라우드 브라우저 사용과 클라우드 네트워크 접근은 관리 콘솔 > 권한 및 역할 > 워크스페이스 기능 > 클라우드 컴퓨터 기능에서 별도로 관리하세요. Work Cloud에 에이전트 보안이 적용되는 방식을 참조하세요.

브라우저 접근 구성하기

1. 관리 콘솔 > 에이전트 보안을 여세요. 워크스페이스 기준 설정에는 워크스페이스 기본값을 사용하세요. 다른 정책을 편집하려면 재정의에서 해당 정책을 여세요. 요구 사항에서 데스크톱 브라우저 제어로 이동하세요.
2. 사이트 규칙에서 기본값 행의 작업 메뉴를 열고 기본값 편집을 선택하세요. 승인된 사이트에만 접근하도록 제한하려면 사이트 접근을 차단으로 설정한 다음 규칙 적용을 선택하세요. 기본값 행은 일치하는 사이트 규칙에서 기본 규칙 사용으로 둔 항목의 값을 제공합니다.
3. 사이트 규칙 추가를 선택하세요. 사이트 또는 패턴에 스킴, 호스트 이름, 필요한 경우 포트로 구성된 출처를 입력하세요. 예를 들어 https://example.com은 유효하지만 https://example.com/files는 유효하지 않습니다. 경로, 쿼리 또는 프래그먼트는 포함하지 마세요. HTTP와 HTTPS는 서로 다른 출처입니다. 스킴의 기본 포트와 다른 포트를 사용하면 포트도 지정하세요.
4. 사이트 접근을 설정하고 다운로드, 업로드, 디버그/CDP를 확인하세요. 필요에 따라 허용 또는 차단을 선택하거나 기본 규칙 사용을 유지하세요. 디버그/CDP는 브라우저 디버깅을 위한 Chrome DevTools Protocol 전체 접근을 제어합니다. 허용을 선택하면 일반 정책 및 승인 검사가 계속 진행됩니다.
5. 사이트의 자동 검토, 항상 허용, 승인 유효 기간을 확인하세요. 승인 유효 기간은 이번 턴 또는 이 스레드로 설정할 수 있습니다. 브라우저 기록, 사이트 승인 저장, 요청 자동 승인도 데스크톱 브라우저 제어에서 확인하세요.
6. 규칙 추가를 선택하고 유효성 검사 메시지를 확인한 다음 변경 사항 저장을 선택하세요. 정책을 받는 지원 클라이언트에서 허용된 사이트와 차단된 사이트를 각각 테스트하세요. 업로드, 다운로드, 그 밖의 제한된 동작도 각각 테스트하세요.

사이트 규칙 추가

사이트 규칙에서 권한을 기본값으로 두면 기본값 행의 설정이 적용됩니다. 규칙이 겹치면 권한별로 차단이 우선합니다.

사이트 또는 패턴 

사이트 접근기본 규칙 사용

다운로드기본 규칙 사용

업로드기본 규칙 사용

디버그/CDP기본 규칙 사용

자동 검토기본 규칙 사용

항상 허용기본 규칙 사용

승인 유효 기간기본 규칙 사용

브라우저 동작의 자동 검토를 끄면 해당 동작에 대해 사용자에게 승인을 요청합니다. 모델 안전 모니터링은 계속 작동합니다.

여러 출처 패턴이 일치하면 설정별로 가장 엄격한 값이 적용됩니다. 로컬 구성으로 관리형 정책의 거부를 완화할 수 없습니다. 관리형 네트워크 거부 규칙과 지정된 대상만 허용하는 목록은 브라우저 도구에도 적용됩니다. 출처 패턴과 승인 동작은 브라우저 정책 필드를 참조하세요.

컴퓨터 사용 기능으로 브라우저를 네이티브 앱처럼 조작할 수도 있습니다. 브라우저 기능의 사이트 및 기능 규칙은 이 경로에 적용되지 않습니다. 네이티브 앱 접근을 별도로 검토하세요. 자세한 내용은 브라우저 보안 경계를 참조하세요.

네이티브 앱 접근 구성하기

1. 요구 사항에서 데스크톱 앱 제어 > 앱 규칙으로 이동하세요.
2. 기본값 행의 작업 메뉴에서 일치하는 규칙이 없는 앱의 접근을 구성하세요. 컴퓨터 사용을 승인된 앱으로 제한하려면 기본적으로 접근을 차단하고 해당 앱에 허용 규칙을 추가하세요.
3. 앱 규칙 추가를 선택하세요. 규칙 편집 대화 상자에서 macOS 번들 ID, Windows AUMID, Windows 실행 파일 중 하나를 App에서 선택하세요. 번들 ID 또는 AUMID(Application User Model ID)를 사용하는 경우 정확한 앱 식별자를 입력하세요. Windows 실행 파일의 경우 게시자 이름과 제품 이름을 입력하세요. 바이너리 이름은 선택 사항입니다. 표시 이름이나 파일 경로 대신 검증된 앱 식별 정보를 사용하세요.
4. 규칙의 앱 접근을 설정하고 규칙 추가를 선택하세요. 앱 승인 저장 설정을 데스크톱 앱 제어에서 확인하고 유효성 검사 메시지를 검토한 다음 변경 사항 저장을 선택하세요. 승인 저장을 꺼도 현재 세션에서는 승인할 수 있습니다. 승인 저장을 허용하는 것만으로 앱이 승인되지는 않습니다.
5. 배포 환경에서 지원하는 각 운영 체제에서 허용된 앱과 차단된 앱을 테스트하세요. 운영 체제 권한이 계속 적용되고 필요한 승인은 여전히 사용자가 해야 하는지 확인하세요.

규칙 편집

기본 앱 접근을 설정하고 규칙과 일치하는 앱에는 다른 값을 적용하세요.

AppmacOS 번들 ID

앱 식별자 

앱 접근접근 권한 선택

Windows의 앱 식별 요구 사항은 컴퓨터 사용 정책 필드를, 관리 대상 Mac의 잠금 상태 사용 제한은 잠금 상태에서 컴퓨터 사용 제한하기를 참조하세요.

실제 적용되는 정책 확인하기

허용한 사이트나 앱이 계속 차단되면 일치하는 다른 규칙, 정책 할당과 우선순위, 디바이스 요구 사항, 사용자 구성을 확인하세요. 한 소스의 허용 규칙으로 다른 소스의 유효한 거부 규칙을 우회할 수 없습니다. 요구 사항의 위치와 우선순위를 참조하세요.

설정이 적용되지 않으면 클라이언트, 운영 체제, 정책 전달 경로에서 해당 설정을 지원하는지 확인하세요. 특히 로컬 컴퓨터 접근을 사용하는 Work Cloud에서는 일부 필드가 부분적으로만 지원되거나 검증이 필요합니다. 구성 레퍼런스의 Work 호환성을 참조하세요.

사용자가 기능이나 필수 플러그인에 접근할 수 없으면 워크스페이스 권한과 플러그인 제어를 별도로 확인하세요.

TOML 구성 레퍼런스

다음 예제는 앞에서 설명한 정책을 requirements.toml로 구성하는 방법을 보여 줍니다. 파일이나 TOML 편집기로 정책을 관리할 때 사용하세요. 에이전트 보안에서 제공하는 컨트롤을 사용하기 위해 로컬 파일을 편집할 필요는 없습니다.

이 브라우저 예제는 접근을 기본적으로 거부하고 https://example.com은 허용합니다. 해당 사이트에서는 업로드와 전체 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"를 설정하세요.

지원되는 관리형 플랜에서 browser_use.allow_webmcp를 설정하지 않거나 true로 설정하면 워크스페이스 정책을 통해 데스크톱 앱의 내장 브라우저에서 사이트 도구를 허용할 수 있습니다. 이 정책을 통한 접근을 끄려면 false로 설정하세요. 계정별 순차 배포를 통해 이미 접근 권한을 받은 사용자는 사이트 도구를 계속 사용할 수 있습니다. 모델의 지원 여부, 브라우저 설정, 사이트 권한도 적용됩니다.

이 네이티브 앱 예제는 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은 선택 사항입니다.

지원되는 모든 필드와 값은 requirements.toml 레퍼런스를 참조하세요. 개별 사이트나 앱을 제한하는 대신 기능 자체를 끄려면 기능 플래그 고정하기를 참조하세요.

기타 데스크톱 제어

다음 데스크톱 설정은 기능 가용성, 잠금 상태 사용, Appshots, 디바이스 원격 제어에 적용됩니다. 기능 가용성과 잠금 상태 사용에는 전용 설정을 사용하세요. Appshots와 디바이스 원격 제어는 TOML로 편집에서 구성하세요. 데스크톱 앱 트래픽의 대상을 제한하려면 데스크톱 앱의 네트워크 대상 제어하기를 참조하세요.

기능 플래그 고정하기

에이전트 보안에서 제공하는 데스크톱 기능을 설정하려면 전역 > 요구 사항 > 데스크톱 기능 사용 가능 여부를 여세요. 앱 내 브라우저, 브라우저, 외부 브라우저 또는 컴퓨터 사용을 강제 비활성화로 설정해 해당 기능을 끈 다음 변경 사항 저장을 선택하세요. 전체 CDP 접근은 사용자 활성화 차단을 선택하면 사용자가 켤 수 없습니다. 기능을 허용해도 제품, 플랫폼, 출시 단계에 따른 가용성 제한은 그대로 적용됩니다.

그 밖에 지원되는 기능 플래그는 TOML로 편집에서 전역 requirements.toml 문서를 사용하거나 지원되는 로컬 요구 사항 소스를 사용하세요. 다음 예제에는 런타임 기능과 데스크톱 전용 기능을 고정하는 설정이 모두 포함되어 있습니다.

[features]
hooks = 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이나 프로필 파일에 이와 충돌하는 기능 설정을 쓰려는 요청을 거부합니다.

관리형 설정에서 unified_exec = false를 지정해도 명령어를 실행할 수 있지만, 재개 가능한 프로세스와 write_stdin 도구는 비활성화됩니다. 사용자 구성으로는 이 기능을 끌 수 없습니다.

• 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는 브라우저를 네이티브 앱으로 조작하는 동작을 포함해 네이티브 앱의 컴퓨터 사용 기능을 비활성화합니다. 기록 및 재생 기능과 관련 설치 또는 설정 플로우도 비활성화됩니다.

브라우저 기능만 꺼서는 모든 브라우저 접근 경로를 차단할 수 없습니다. 네이티브 앱의 컴퓨터 사용 기능과 해당 앱에 대한 접근이 허용되면 여전히 브라우저를 조작할 수 있습니다. 브라우저 기능의 사이트 및 기능 규칙은 이 경로에 적용되지 않습니다. 이 경로를 차단하려면 컴퓨터 사용을 강제 비활성화(computer_use = false)로 설정하세요. 다른 네이티브 앱은 계속 사용할 수 있어야 한다면 앱 규칙에서 브라우저 앱을 거부하세요. 외부 브라우저와 앱 내 브라우저도 별도로 검토하세요. 각 경로에 적용되는 설정은 브라우저 세션 및 기존 로그인을 참조하세요.

이 키들을 생략하면 정책은 해당 기능을 허용하며, 일반적인 클라이언트, 플랫폼 및 출시 단계별 가용성 조건이 적용됩니다.

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

관리 대상 Mac에서 사용자가 잠금 상태 사용을 켜지 못하게 하려면 전역 > 요구 사항 > 데스크톱 앱 제어를 열고 잠금 상태에서 사용 허용을 비활성화로 설정한 다음 변경 사항 저장을 선택하세요. 이미 잠금 상태 사용이 활성화된 Mac에서는 이 설정으로 기능이 꺼지지 않습니다.

TOML 편집기나 디바이스 관리형 배포에서 같은 요구 사항을 설정하려면 다음을 사용하세요.

[computer_use]
allow_locked_computer_use = false

이 요구 사항은 잠금 상태 사용을 켜는 컨트롤을 제거합니다. 이미 켜져 있는 기능을 끄지는 않습니다. 요구 사항을 생략하면 일반적인 제품 가용성 조건과 사용자의 로컬 설정이 그대로 적용됩니다.

Appshots 비활성화하기

Appshots를 사용하면 지원되는 클라이언트에서 애플리케이션 스냅샷을 포함할 수 있습니다. 클라우드 관리 대상 사용자의 Appshots를 끄려면 에이전트 보안에서 TOML로 편집을 여세요. 최상위 allow_appshots 필드를 전역 requirements.toml에 설정하세요. 디바이스 관리형 배포에서는 해당 로컬 요구 사항 소스를 사용하세요.

allow_appshots = false

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

디바이스 원격 제어 비활성화하기

클라우드 관리 대상 사용자의 디바이스 원격 제어를 끄려면 에이전트 보안에서 TOML로 편집을 여세요. 최상위 allow_remote_control 필드를 전역 requirements.toml에 설정하세요. 지원되는 로컬 요구 사항 소스에서도 allow_remote_control을 설정할 수 있습니다.

allow_remote_control = false

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

승인 및 실행 권한 설정하기

이 섹션에서는 승인 동작, 권한 범위, 시작 시 적용할 기본값을 설정합니다. 먼저 정책 가드레일과 기본값을 설정하세요. 이어지는 작업에서는 검토자 지정, 사용자 지정 권한 프로필, 파일 시스템 제한, 호스트별 재정의, 명령어 규칙에 필요한 TOML 요구 사항을 설명합니다.

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

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

요구 사항으로 기능 플래그를 제한할 수도 있습니다. [features] 테이블을 requirements.toml에 구성하세요. 모든 기능이 보안에 민감한 것은 아니지만 엔터프라이즈에서는 필요한 값을 고정할 수 있습니다. 생략한 키에는 제한이 적용되지 않습니다.

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

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

승인, 샌드박스, 웹 검색 가드레일 설정하기

요구 사항 > 정책 가드레일에서 지원 클라이언트가 선택할 수 있는 옵션을 제한하세요. 이 컨트롤은 구성을 제한하지만 초기값을 지정하지 않습니다. 초기값은 기본값에서 별도로 설정하세요.

1. 전역에서 승인 정책을 열고 허용할 승인 방식을 선택하세요. 예를 들어 필요할 때 요청은 샌드박스 권한 상승 등의 동작에 대해 에이전트가 승인을 요청할 수 있게 합니다. 요청 안 함은 승인 요청을 막습니다. 무제한 실행 권한을 부여하지는 않습니다.
2. 샌드박스 모드를 열어 레거시 샌드박스 옵션을 제한하세요. 읽기 전용은 쓰기를 제한하고, 워크스페이스 쓰기는 워크스페이스와 쓰기가 가능하도록 구성된 루트 경로 내에서 쓰기를 허용합니다. 전체 권한은 파일 시스템 샌드박스를 해제합니다. 권한 프로필 요구 사항은 sandbox_mode 대신 권한 프로필을 사용하는 배포에 적용하세요.
3. 전역에서 웹 검색 모드를 열어 웹 검색을 제한하세요. 실시간 검색 없이 캐시된 검색만 허용하려면 캐시됨을, 웹 검색을 끄려면 비활성화를 선택하세요. 웹 검색 제한은 명령어 네트워크 규칙과 별개입니다.
4. 허용되는 옵션과 해당 기본값을 검토한 다음 변경 사항 저장을 선택하세요.

요구 사항을 설정하지 않으면 해당 정책에서는 그 항목을 제한하지 않습니다. 다른 적용 대상 정책은 그대로 적용됩니다. 신뢰할 수 없는 명령어에 승인 요청 옵션은 요구 사항 허용 목록의 untrusted에 해당합니다. 지원이 종료된 명시적 approval_policy = "untrusted" 설정을 복원하지는 않습니다. 이 경우에는 아래 마이그레이션 안내를 따르세요.

웹 검색을 제한하려면 전역 > 요구 사항 > 정책 가드레일 > 웹 검색 모드를 사용하세요. 이에 해당하는 TOML은 다음과 같습니다.

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

allowed_web_search_modes = []는 "disabled"만 허용합니다. 예를 들어 allowed_web_search_modes = ["cached"]를 설정하면 danger-full-access 세션에서도 실시간 웹 검색이 차단됩니다.

구성 기본값 설정하기

기본값은 멤버가 처음 사용할 구성을 지정합니다. 제한을 강제하거나 워크스페이스 기능에 대한 접근 권한을 부여하지는 않습니다.

1. 정책의 기본값 카드를 여세요. 에이전트 전체의 기본값은 전역에 두고, 지원되는 실행 기본값은 사용 가능한 환경 탭에서 설정하세요.
2. 명령어 실행에서 초기 승인 정책과 승인 검토자를 선택하고, 해당하는 샌드박스 모드 또는 기본 권한을 선택하세요. 검토자는 기본적으로 누가 승인 요청을 검토할지 정하고, 승인 정책은 언제 요청할 수 있는지 정합니다.
3. 웹 검색에서 초기 웹 검색 모드와 웹 검색 컨텍스트를 선택하세요. 앱 및 도구에서 지원되는 앱 도구의 앱/커넥터, 외부에 영향을 주는 도구, 파괴적 도구 설정을 확인하세요.
4. 기본값이 요구 사항을 충족하는지 확인한 다음 변경 사항 저장을 선택하세요.

플러그인 마켓플레이스 구성처럼 시각적 컨트롤이 없는 지원 기본값은 TOML로 편집을 사용하세요. 이러한 클라우드 기본값은 일반 구성 우선순위를 따릅니다. 시작 시 관리형 기본값을 로컬 구성보다 우선하는 레거시 managed_config.toml 우선순위와는 다릅니다.

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"를 명시적으로 설정할 수 있게 하는 것은 아닙니다.

지원이 종료된 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 승인 정책에서 마이그레이션하기를 참조하세요.

자동 검토 정책 구성하기

자동 검토를 기본값으로 지정하려면 전역 > 기본값 > 명령어 실행 > 승인 검토자를 선택하세요. 사용자는 허용된 다른 검토자를 선택할 수 있습니다. 자동 검토를 강제하거나 검토자 정책을 교체하려면 TOML로 편집을 선택하고 전역 requirements.toml을 편집하세요. 브라우저 동작에 대한 자동 검토는 별도로 설정합니다.

다음 예제는 자동 검토가 가능한 승인 요청에 자동 검토를 의무화합니다. 수동 승인도 허용하려면 "user"를 allowed_approvals_reviewers에 포함하세요.

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

정책 전체를 교체하려면 guardian_policy_config를 사용하세요. 기본 정책의 내용과 대체 정책을 준비하는 방법은 자동 검토 구성을 참조하세요.

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

기본값 > 명령어 실행 > 기본 권한에서 사용자가 처음 사용할 내장 프로필을 선택하세요. 선택할 수 있는 프로필을 제한하거나 사용자 지정 프로필을 정의하려면 TOML로 편집을 사용해 전역 또는 지원되는 실행 환경 범위의 requirements.toml을 구성하세요. 기본값을 선택하는 것만으로는 사용 가능한 프로필이 제한되지 않습니다.

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를 기본값으로 사용하되, :workspace와 :read-only가 모두 명시적으로 허용된 경우에만 그렇게 합니다. allowed_permission_profiles가 없으면 관리형 요구 사항은 사용자가 선택할 수 있는 프로필 이름을 제한하지 않습니다. 각 항목은 내장 프로필이나 불러온 구성 또는 요구 사항 소스에 정의된 사용자 지정 프로필의 이름이어야 합니다. 사용자 지정 프로필의 동작을 중앙에서 제어하려면 관리형 요구 사항에 정의하세요.

읽기 거부 요구 사항 적용하기

TOML로 편집을 사용해 전역 또는 지원되는 실행 환경의 requirements.toml에 파일 시스템 제한을 추가하세요. 이 제한은 민감한 경로의 읽기를 차단합니다. 읽기 전용 기본값만으로는 파일을 숨길 수 없습니다.

관리자는 [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는 파일에 직접 접근하는 도구에 적용됩니다. 셸 하위 프로세스가 파일을 읽을 때는 이 샌드박스 규칙이 적용되지 않습니다.

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

에이전트 보안에서 TOML로 편집을 사용해 호스트별 요구 사항을 작성하세요. 환경 컨트롤은 실행 환경을 선택하고, 호스트 패턴은 지원되는 런타임에서 패턴과 일치하는 머신을 선택합니다.

하나의 관리형 정책에서 호스트마다 다른 샌드박스 요구 사항을 적용하려면 [[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 항목을 확인 가능한 호스트 이름과 비교합니다. 전체 도메인 이름(FQDN)을 확인할 수 있으면 우선 사용하고, 그렇지 않으면 로컬 호스트 이름을 사용합니다. 패턴은 대소문자를 구분하지 않습니다. *는 임의 길이의 문자열과 일치하고 ?는 한 문자와 일치합니다.

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

요구 사항으로 명령어 규칙 적용하기

에이전트 보안에서 TOML로 편집을 사용해 전역 requirements.toml에 명령어 규칙과 MCP 서버 제한을 추가하세요. 명령어 규칙은 일치하는 명령어의 승인 요청 또는 거부 여부를 지정합니다. MCP 제한은 클라이언트가 활성화할 수 있는 서버의 식별 정보를 제한합니다. 승인 정책 컨트롤에서는 이 두 종류의 규칙을 작성할 수 없습니다.

관리자는 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 서버를 비활성화합니다.

네트워크 접근 구성하기

명령어 네트워크와 데스크톱 앱 네트워크는 서로 다른 설정을 사용합니다. 지원되는 명령어 트래픽은 먼저 네트워크 사용 제어에서 설정하세요. 환경 및 런타임 제한을 검토한 후 필요한 경우 데스크톱 앱 전용 요구 사항을 사용하세요. 브라우저 사이트 규칙은 브라우저 및 컴퓨터 사용 제어하기를 참조하세요.

네이티브 클라이언트 요청에 시스템 프록시 사용하기

실험적 설정인 features.respect_system_proxy를 사용하면 ChatGPT 데스크톱과 Codex에서 사용하는 네이티브 Codex 런타임이 자체 네트워크 요청에 운영 체제의 프록시 설정을 사용할 수 있습니다. 시스템 프록시나 프록시 자동 구성(PAC)이 필요한 디바이스에서 활성화하세요. 기본값은 false입니다.

지원되는 config.toml 기본값 소스 또는 managed_config.toml에 다음을 추가하세요.

[features]
respect_system_proxy = true

프로젝트 로컬 구성에서는 이 설정을 켤 수 없습니다. macOS MDM의 경우 config_toml_base64에 같은 TOML을 포함하세요. 로컬 구성을 변경한 후 클라이언트를 다시 시작하세요. 이 기능을 다시 끄려면 활성화에 사용한 구성 소스에서 false로 설정하세요.

로그인 및 클라우드 기본값

별도 기능인 system_proxy_fallback은 기본적으로 켜져 있습니다. 연결이 실패하면 지원되는 로그인 및 클라우드 구성 요청을 시스템 프록시를 통해 다시 시도할 수 있습니다. respect_system_proxy가 false여도 마찬가지입니다. 이 대체 경로 덕분에 지원되는 클라이언트는 로컬에서 별도로 활성화하지 않아도 로그인하고 클라우드 기본값을 가져올 수 있습니다. respect_system_proxy만 꺼서는 대체 경로가 비활성화되지 않습니다.

직접 접근이 되지 않고 대체 경로를 사용할 수 없거나 꺼져 있거나 재시도에 실패하면 로그인 전에 respect_system_proxy를 로컬에 배포하세요.

범위와 제한 사항

사용할 클라이언트 버전과 네트워크에서 로그인 및 인증된 요청을 검증하세요. 다음 사항을 고려하세요.

• 요청 범위: 이 설정은 Codex 런타임이 관리하는 네트워크 클라이언트에 적용됩니다. ChatGPT 데스크톱 요청, 브라우저 요청, 플러그인 프로세스, 셸 명령어 전체를 구성하지 않습니다. 대상 허용 목록을 강제하거나 직접 연결 차단을 보장하지도 않습니다. 지원되는 트래픽은 명령어 네트워크 요구 사항과 데스크톱 앱 네트워크 요구 사항을 참조하세요.
• 플랫폼 지원: macOS와 Windows에서는 운영 체제의 기능으로 시스템 프록시를 찾을 수 있습니다. 시스템에서 프록시를 확인할 수 없으면 런타임은 명시적인 프록시 환경 설정이 있을 때 그 설정을 사용하고, 없으면 직접 연결합니다. 다른 플랫폼에서는 시스템 프록시를 검색하지 않고 같은 방식으로 환경 설정 또는 직접 연결을 사용합니다.
• PAC 라우팅: 런타임은 PAC 결과에서 경로 하나를 선택합니다. 해당 연결이 실패해도 결과에 나열된 이후 프록시나 DIRECT 항목으로 다시 시도하지 않습니다.
• Windows 인증: 지원되는 빌드는 터널 설정 중 HTTP 407 프록시 인증 요청을 받으면 로그인한 Windows 사용자의 자격 증명으로 Negotiate 또는 NTLM 인증을 수행할 수 있습니다. 프록시의 TLS 연결에 바인딩된 인증 토큰이 필요한 HTTPS 프록시는 지원하지 않습니다.

네트워크 접근 요구 사항 구성하기

에이전트 보안에서 요구 사항 > 네트워크 사용 제어를 사용해 지원되는 명령어의 네트워크 접근을 관리하세요. 공유 기준 설정은 전역에서 구성하세요. 환경별 실행 설정은 사용 가능한 로컬 환경 또는 Codex Cloud 환경 탭에서 구성하세요.

1. 관리 대상 명령어 트래픽에 도메인 규칙을 적용하려면 관리형 네트워크를 켜짐으로 설정하세요. 도메인 규칙만 추가해서는 관리형 프록시가 활성화되지 않습니다.
2. 네트워크 규칙에서 네트워크 규칙 추가를 선택하세요. 도메인에 api.openai.com 또는 **.example.com과 같이 URL 스킴이나 경로를 제외한 값을 입력하세요. 허용 또는 거부를 접근에서 선택하고 규칙 저장을 선택해 초안을 업데이트하세요. 다른 대상에도 반복하세요.
3. 사용자 설정이나 도메인별 승인으로 관리형 허용 목록을 확장하지 못하게 하려면 관리자가 추가한 도메인만 허용을 켜짐으로 설정하세요. 필요한 허용 항목을 포함하세요. 거부 항목만 있는 목록은 다른 대상을 허용하지 않습니다.
4. 로컬 리스너나 사설 네트워크 대상이 필요한 워크플로우라면 로컬 네트워크 접근 허용을 검토하세요. 로컬 직접 연결은 프록시의 도메인 규칙을 우회할 수 있습니다. 이 설정을 변경하기 전에 아래의 Codex Cloud 연결 제한을 검토하세요.
5. 상속된 규칙과 유효성 검사 메시지를 확인한 다음 변경 사항 저장을 선택하세요. 영향을 받는 모든 실행 환경에서 성공해야 하는 요청과 차단되어야 하는 요청을 각각 테스트하세요.

관리형 네트워크를 꺼짐으로 설정하면 해당 범위에 직접 작성한 네트워크 규칙을 지우고 명시적인 꺼짐 값을 저장합니다. 인터넷 접근을 비활성화하지는 않습니다. 설정 안 함은 해당 범위에 직접 작성한 네트워크 설정을 제거해 적용 대상 정책이나 런타임 기본값이 적용되도록 합니다. 환경 설정을 제거하면 상속된 전역 규칙이 다시 적용될 수 있습니다. 고급 네트워크 필드나 시각적 편집기로 표현할 수 없는 기존 레거시 도메인 목록은 TOML로 편집을 사용하세요.

Codex 0.166.0에서는 [network_proxy]가 requirements.toml에서 명령어의 네트워크 접근을 관리하는 표준 테이블입니다. Codex는 기존 이름인 [experimental_network]도 인식합니다. 한 계층에서는 테이블 이름을 하나만 사용하세요. 계층마다 다른 이름을 사용하면 Codex는 일반적인 요구 사항 우선순위를 적용합니다.

관리형 테이블에 enabled = true를 설정하면 사용자 설정인 features.network_proxy와 관계없이 프록시가 시작됩니다. 명령어가 네트워크에 접근하려면 현재 샌드박스에서도 이를 허용해야 합니다. 다음 예제에서는 이전 버전의 클라이언트와 정책 검증 계층이 인식하는 이름을 사용합니다.

[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는 관리자가 직접 "allow" 항목을 [experimental_network.domains]에 정의하고 그 규칙으로만 허용 대상을 정하려는 경우에 사용하세요. 관리형 허용 규칙 없이 true로 설정하면 사용자가 추가한 도메인 허용 규칙은 효력을 잃습니다. 표준 domains 맵을 레거시 allowed_domains 또는 denied_domains 목록과 함께 사용하지 마세요.

*.example.com은 하위 도메인에만 일치합니다. **.example.com은 해당 도메인 자체와 그 하위 도메인에 모두 일치합니다. 일치하는 거부 규칙은 허용 규칙보다 우선합니다.

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

프록시는 샌드박스 안에서 실행되는 로컬 명령어의 트래픽을 라우팅합니다. 브라우저 도구도 출처에 접근하기 전에 관리형 네트워크의 거부 규칙과 지정된 대상만 허용하는 목록을 확인합니다. 이는 별도의 정책 검사로, 브라우저 트래픽을 명령어 프록시를 통해 라우팅하는 방식이 아닙니다. 명령어 프록시는 웹 검색, 앱과 커넥터, MCP 서버, 네이티브 앱 트래픽, Codex 서비스 요청이나 그 밖의 기능별 트래픽을 필터링하지 않습니다. 각 기능에 맞는 설정을 사용하세요.

• 웹 검색을 제한하려면 allowed_web_search_modes를 사용하세요.
• 앱 및 커넥터 통합을 끄려면 features.apps = false를 사용하고, 지원되는 환경에서 플러그인을 끄려면 features.plugins = false를 사용하세요.
• MCP 서버를 제한하려면 관리형 mcp_servers 승인 목록을 사용하세요.
• 브라우저 및 컴퓨터 사용 기능을 제한하려면 browser_use, in_app_browser, computer_use 등의 기능 요구 사항을 사용하세요.
• 지원되는 관리형 Codex Cloud 명령어의 경우 에이전트 보안 설정과 해당 환경의 인터넷 설정을 모두 확인하세요. 에이전트 보안에서 허용한 도메인도 환경의 인터넷 설정에 따라 차단될 수 있습니다.

일반 명령어 실행과 정책에서 허용하는 샌드박스 전체 권한 상승을 각각 테스트하세요. 샌드박스 전체 권한 상승이 승인되면 해당 명령어는 관리형 명령어 프록시를 우회할 수 있습니다. 네트워크 격리를 참조하세요.

실제로 허용되는 대상이 없는 경우: 관리형 네트워크와 관리자가 추가한 도메인만 허용이 모두 켜져 있으면 일반 관리형 명령어가 대상에 접근하려면 직접 지정하거나 상속한 허용 항목이 있어야 합니다. 저장하기 전에 실제로 허용되는 대상을 확인하세요.

Codex Cloud의 로컬 및 사설 네트워크 연결: 클라우드 명령어가 허용된 도메인에 연결하지 못하면 실제로 적용되는 allow_local_binding 값을 확인하세요. 상속된 값이 꺼짐이면 업스트림 프록시 연결이 차단될 수 있습니다. 클라우드 전용 기본값과 재정의 방법은 Codex Cloud의 로컬 및 사설 네트워크 연결을 참조하세요.

환경 요구 사항이 비어 있으면 전역 요구 사항이 적용됩니다. 관리형 네트워크의 꺼짐 값은 클라우드 환경의 인터넷 접근 설정과 별개입니다. 실행 범위에 대한 자세한 내용은 에이전트 보안 실행 제어를 참조하세요.

네트워크 정책 우선순위와 런타임 제한

같은 정책 안에서는 우선순위가 높은 것부터 OS별 환경 재정의 → 모든 OS에 대한 환경 재정의 → 전역 순입니다. 서로 다른 정책 간에는 우선순위가 낮은 정책의 설정이 더 구체적이어도 우선순위가 높은 정책이 적용됩니다. 일부 요구 사항에는 필드별 병합 규칙이 있습니다. 런타임은 이렇게 결정된 요구 사항을 강제합니다. 아래의 필드별 네트워크 동작은 정책 우선순위와 구분해 살펴보세요.

다음 예제는 관리형 네트워크가 이미 구성되어 있고 더 높은 우선순위의 정책이 값을 변경하지 않는 조건에서 같은 정책의 환경 설정과 전역 설정을 비교합니다. 각 필드의 병합 방식과 런타임 동작을 설명합니다.

환경별 도메인 접근 설정하기

같은 정책에서 같은 도메인 규칙에 대해 관리자는 환경별 재정의로 전역에서 거부한 도메인을 허용하거나 전역에서 허용한 도메인을 거부할 수 있습니다. 환경별 재정의가 없으면 전역 규칙을 상속합니다. 적용되는 다른 거부 규칙이나 접근 제어가 있으면 요청이 여전히 차단될 수 있습니다.

도메인 규칙 병합 방식

이 결과는 우선순위가 더 높은 정책이 결과를 변경하지 않는 조건에서 한 정책 내의 같은 도메인 키를 비교한 것입니다. 우선순위가 높은 값은 같은 키의 값을 대체합니다. 상속된 다른 키는 유지됩니다. 한 규칙에서 허용해도 상속된 와일드카드 규칙처럼 일치하는 다른 거부 규칙을 우회할 수 없습니다. 환경 맵이 비어 있어도 상속된 규칙이 지워지지는 않습니다.

예제: 전역에서 packages.example.com을 거부하고 개발 환경에서는 허용합니다. 개발 환경은 위 조건에 따라 이 도메인을 허용할 수 있습니다. 프로덕션 환경은 재정의하지 않는 한 전역 거부 규칙을 상속합니다.

배포한 실행기가 이 병합 규칙을 지원하는지 확인하세요. 일반 관리형 실행기의 지원 범위는 아직 검증이 필요합니다.

오케스트레이터에는 제한이 있습니다. 클라우드 런타임은 관리형 HTTP/SOCKS 리스너 포트와 루프백 이외의 프록시 리스너를 지원하지 않으며, 소켓 규칙의 지원 여부는 실행 경로에 따라 다릅니다. 아래 표의 로컬 실행 설정은 오케스트레이터에서 지원되는 구성이 아닙니다.

기타 네트워크 런타임 제한

아래 필드는 모두 관리형 network_proxy 테이블에 속합니다. 이 테이블에는 experimental_network라는 이름도 사용할 수 있으며, 두 이름 모두 requirements.toml에서 인식됩니다. 화살표 왼쪽은 전역 값이고 오른쪽은 같은 정책의 환경 값입니다. 이 로컬 실행 사례만으로 오케스트레이터가 같은 설정을 지원한다고 판단할 수 없습니다.

프록시 활성화, 지정된 대상만 허용하는 설정, 업스트림 프록시 동작, Unix 소켓 규칙은 실행기별로 동작이 다릅니다. 도메인 키 병합 방식을 이 설정들에 일반화하지 마세요. 실제 적용값을 확인하고 배포한 런타임을 테스트하세요. Codex Cloud의 로컬 및 사설 네트워크 연결은 네트워크 접근 요구 사항 구성하기를 참조하세요.

배포 전 동작 검증하기

워크플로우에서 실제로 사용하는 대상, 로컬 리스너, 프록시 동작, 소켓 경로를 테스트하세요. 영향을 받는 각 환경에서 성공해야 하는 동작과 차단되어야 하는 동작을 하나씩 확인하세요. 배포한 런타임 버전이 사용하는 각 설정을 지원하는지도 확인하세요.

데스크톱 앱의 네트워크 대상 제어하기

에이전트 보안에서 TOML로 편집을 사용해 전역 범위에 데스크톱 전용 요구 사항을 구성하세요. 네트워크 사용 제어 UI는 별도 정책인 명령어 네트워크를 관리합니다.

데스크톱 앱의 네트워크 대상을 제한하려면 [application.network]를 requirements.toml에 구성하세요. enabled = true이면 외부 요청은 HTTPS 또는 WSS를 사용해야 하며, "allow" 값이 지정된 [application.network.domains]의 도메인과 정확히 일치해야 합니다. 하위 도메인은 암묵적으로 허용되지 않습니다. 도메인 맵이 비어 있으면 외부 대상을 하나도 허용하지 않습니다. 지원되는 키는 구성 레퍼런스를 참조하세요.

이 정책은 명령어 네트워크 및 브라우저 출처 규칙과 별개입니다. 네이티브 모듈이나 새로 생성된 프로세스에는 대상 제한을 적용하지 않으며, Work Cloud 실행도 제어하지 않습니다.

플러그인 및 관리형 훅 구성하기

이 작업에는 에이전트 보안의 TOML로 편집 또는 지원되는 로컬 구성 소스를 사용하세요. 마켓플레이스 기본값, 강제되는 플러그인 제한, 관리형 훅은 각각 용도가 다릅니다. 필요한 정책에 맞는 작업을 선택하세요.

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

에이전트 보안 > TOML로 편집에서 전역 config.toml 문서에 로컬 또는 Git 마켓플레이스와 플러그인 기본값을 정의하세요. 시스템 config.toml로도 이 설정을 배포할 수 있습니다. 이 설정은 마켓플레이스와 플러그인의 초기 구성을 제공하며 정책을 강제하지 않습니다. 멤버가 사용할 수 있는 소스를 제한하려면 마켓플레이스 소스 요구 사항을 구성하세요.

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

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

에이전트 보안의 TOML로 편집에서 전역 requirements.toml에 강제할 플러그인 기능 설정을 지정하세요. 디바이스 관리형 클라이언트에는 로컬 요구 사항으로 배포할 수도 있습니다. 기본값 > 앱 및 도구 > 앱/커넥터는 앱 도구의 기본값을 설정합니다. 플러그인을 강제로 제어하는 features.plugins 스위치와는 다릅니다. 워크스페이스 플러그인 권한은 앱 및 커넥터를 참조하세요.

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

features.plugins = false

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

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

TOML로 편집을 사용해 전역 requirements.toml에 마켓플레이스 소스 요구 사항을 구성하거나 로컬 요구 사항으로 전달하세요. 이 규칙은 사용자가 추가하고 사용할 수 있는 로컬 또는 Git 소스를 제한합니다. 마켓플레이스 기본값과는 별개입니다.

플러그인 마켓플레이스 소스를 제한하려면 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 마켓플레이스도 소스 허용 목록과 일치해야 합니다. 허용하려면 ref 제한 없이 다음 Git 소스를 포함하세요.

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

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

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

요구 사항으로 관리형 훅 적용하기

에이전트 보안에서 전역 > 요구 사항 > TOML로 편집을 여세요. 로컬 컴퓨터 접근을 사용하는 Work와 dot의 경우, 지원되는 mcp_tool 핸들러를 전역 requirements.toml에 구성하세요. 배포하기 전에 콜백이 연결되는지, 콜백 시간이 초과되면 어떻게 동작하는지 테스트하세요. 지원되는 이벤트와 실패 시 동작은 클라우드 오케스트레이션에서 사용하는 훅을 참조하세요.

로컬 Codex의 경우 디바이스 관리 도구로 훅 스크립트를 배포하세요. 사용자가 훅을 꺼도 관리형 훅이 실행되도록 하려면 [features].hooks = true를 requirements.toml에 고정하세요. 스크립트 경로와 관리형 훅만 허용하는 방법은 관리형 훅 구성 예제를 참조하세요.

정책 범위와 우선순위 이해하기

이 섹션에서는 정책의 적용 범위, 요구 사항의 병합 방식, 클라이언트가 클라우드 관리형 설정을 받는 방식, 결과 확인 방법을 설명합니다.

로컬 접근을 사용하는 Work와 dot에서는 관리형 정책이 활성화된 경우 지원되는 전역 정책이 공유 클라우드 오케스트레이터에 적용됩니다. 연결된 컴퓨터에는 해당 로컬 실행 요구 사항이 적용됩니다. Work 클라우드 컨테이너에는 기존 Work Cloud 정책이 유지되며, 로컬 실행에는 지원되는 디바이스 제어가 계속 적용됩니다. Codex의 구성 동작은 기존과 같습니다. 관리형 구성은 워크스페이스 시트나 기능 접근 권한을 부여하지 않습니다. 해당 권한은 역할 및 워크스페이스 권한에서 관리하세요.

에이전트 보안과 Work Cloud의 로컬 컴퓨터 접근

관리 콘솔의 에이전트 보안에서 정책과 구성을 관리하세요. 에이전트 보안은 기존 정책 및 구성 메뉴를 대체합니다. Work Cloud의 로컬 컴퓨터 접근 사용 여부와 관계없이 관리 콘솔에서 에이전트 보안을 사용할 수 있습니다. 기존 정책, 할당, 순서는 유지됩니다. 에이전트 보안에서 기존 정책을 검토하세요. Work Cloud의 로컬 컴퓨터 접근은 별도로 활성화해야 합니다. 마이그레이션 안내는 에이전트 보안을 참조하세요.

정책 자동화를 에이전트 보안으로 이전하기 전에 다음을 수행하세요.

1. 영향을 받는 통합을 파악하세요. 정책을 업데이트하는 Terraform 구성과 스크립트의 목록을 만들고 각각 어떤 정책을 관리하는지 기록하세요.

2. 전역 설정은 정책 API로 관리하세요. 로컬 또는 Codex Cloud 설정은 에이전트 보안 UI를 사용하세요. 기존 전역 API 워크플로우는 마이그레이션 후에도 사용할 수 있습니다. 스크립트와 Terraform 통합을 테스트하고 정책 할당과 순서가 유지되었는지 확인하세요.

3. 필요한 변경을 적용하고 자동화를 테스트하세요. 업데이트가 의도한 에이전트 보안 정책에 반영되고 그에 따른 제어가 실제로 적용되는지 확인하세요.

정책을 마이그레이션해도 Work 또는 dot에 로컬 컴퓨터 접근 권한이 부여되지는 않습니다. 배포 전에 정책을 검토하거나 만드는 것이 좋지만, 접근 활성화 확인 절차에서 정책 생성을 요구하지는 않습니다. 로컬 컴퓨터 접근 허용을 켜기 전에 이전된 기준 설정을 검토하세요. 현재 정책을 MDM으로만 전달하고 있다면 클라우드 기준 설정을 만드세요. 클라우드 정책 중 하나라도 enforce_residency가 켜져 있으면 로컬 컴퓨터 접근 허용은 Work와 dot 모두에서 비활성화됩니다. 이 보호 조치는 워크스페이스의 데이터 레지던시를 구성하지 않으며, 그 자체로 Work Cloud나 dot을 비활성화하지도 않습니다.

환경별 재정의를 사용하면 한 정책 안에서 지원되는 설정을 환경에 따라 다르게 적용할 수 있습니다. 같은 정책 안에서는 우선순위가 높은 것부터 OS별 환경 재정의 → 모든 OS에 대한 환경 재정의 → 전역 순입니다. 서로 다른 정책 간에는 우선순위가 낮은 정책의 설정이 더 구체적이어도 우선순위가 높은 정책이 적용됩니다. 일부 요구 사항에는 필드별 병합 규칙이 있습니다. 워크스페이스에서 사용할 수 있는 재정의 편집기와 필드를 확인하세요.

훅을 사용하는 워크플로우에서 로컬 접근을 켜기 전에 클라우드 오케스트레이션에서 어떤 훅이 실행되는지 확인하세요.

위치와 우선순위

로컬 실행 시 요구 사항은 다음과 같이 우선순위가 낮은 항목부터 높은 항목 순으로 적용됩니다. Work Cloud의 로컬 컴퓨터 접근에서 로컬로 실행되는 단계에도 같은 순서가 적용됩니다.

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을 사용하세요.

Work Cloud의 로컬 컴퓨터 접근에 적용되는 우선순위

로컬 접근을 사용하는 Work와 dot에서는 전역 오케스트레이터 정책과 실행 정책을 구분하세요. 연결된 컴퓨터에는 해당 로컬 요구 사항이 적용됩니다. Work 클라우드 컨테이너와 dot 클라우드 컴퓨터는 다른 실행기가 사용하는 관리형 환경 번들 대신 자체 실행 구성과 요구 사항을 사용합니다.

로컬 실행에서는 MDM 및 레거시 관리 대상 디바이스 요구 사항이 에이전트 보안보다 우선합니다. 디바이스의 시스템 요구 사항 파일은 에이전트 보안보다 우선순위가 낮습니다. 각 정책에서는 OS별 환경 재정의, 모든 OS에 대한 환경 재정의, 전역 순서로 값을 결정하세요. 서로 다른 정책 간에는 설정의 구체성보다 정책 우선순위가 우선합니다.

요구 사항은 제한을 적용하고 구성 기본값은 초기값을 제공합니다. 로컬 접근을 사용하는 Work와 dot에서는 관리형 정책이 활성화되면 공유 클라우드 오케스트레이터를 통해 지원되는 전역 정책이 적용됩니다. 연결된 컴퓨터에서의 실행에는 해당 로컬 requirements.toml 요구 사항이 적용됩니다. Work 클라우드 컨테이너와 dot 클라우드 컴퓨터는 다른 유형의 실행기가 사용하는 관리형 환경 번들 대신 자체 실행 구성과 요구 사항을 사용합니다. 로컬 실행 제한이 이 클라우드 컴퓨터에 자동으로 적용되지는 않습니다. 클라우드 기능 권한을 검토하고 로컬 실행과 클라우드 실행을 별도로 테스트하세요.

승인과 웹 검색을 포함한 오케스트레이터 제어는 전역에 두세요. 제공되는 경우 허용된 승인 정책과 허용된 웹 검색 모드 전용 컨트롤을 사용하고, 그 밖의 지원 필드에는 TOML을 사용하세요. 필드 목록과 실행 범위는 구성 레퍼런스를 참조하세요.

클라우드 관리형 요구 사항

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

일반적인 요구 사항은 에이전트 보안 컨트롤로 구성하세요. 요청 시 승인과 읽기 전용 또는 workspace-write 샌드박스만 허용하려면 승인 정책과 샌드박스 모드를 정책 가드레일에서 설정하세요. 지원되는 셸 진입점을 실행하기 전에도 승인을 요청하려면 TOML로 편집에서 [rules] 테이블을 전역 requirements.toml에 추가하세요.

이에 해당하는 전체 TOML은 다음과 같습니다.

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 레퍼런스를 참조하세요.

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

아래의 로딩 및 캐시 동작은 지원되는 로컬 클라이언트에 해당합니다. 이 설명만으로는 Work Cloud의 로컬 컴퓨터 접근을 사용해 이미 실행 중인 작업에 변경된 클라우드 정책이 언제 적용되는지 알 수 없습니다. 변경한 제한에 의존하기 전에 실제 적용되는 정책을 확인하세요.

지원되는 플랜의 사용자가 지원되는 로컬 클라이언트를 시작하고 ChatGPT로 로그인하면 클라이언트는 먼저 사용자 ID와 일치하는 유효한 캐시 항목이 있는지 확인합니다. 유효한 항목이 없으면 해당 번들을 가져오고 필요하면 재시도합니다. 성공하면 서명된 캐시 항목을 기록합니다. 요청이 실패하거나 시간 초과가 발생했는데 유효한 캐시도 없으면 클라우드 관리형 요구 사항 계층을 누락한 채 시작하지 않고 클라우드 구성 번들 로딩 오류를 반환합니다.

캐시 확인이 끝나면 클라이언트는 클라우드 요구 사항을 위에 설명한 다른 요구 사항 계층과 조합합니다. 백그라운드 새로 고침은 캐시된 번들을 업데이트해 이후 구성을 불러올 때 사용할 수 있게 합니다. 이미 실행 중인 작업에 변경된 정책이 즉시 적용된다는 보장은 없습니다. 일부 데스크톱 설정은 앱을 다시 시작해야 합니다. 다시 시작하라는 안내가 있으면 따르고, 변경 사항에 의존하기 전에 실제 설정을 확인하세요.

관리자와 직원의 사용 환경 확인하기

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

의도한 권한을 가진 사용자로 허용되는 워크플로우와 차단되는 워크플로우를 테스트하세요. 지원되는 클라이언트에서 실제 적용되는 설정을 확인하세요. 워크스페이스 역할이나 그룹만으로는 로컬 런타임 제한이 강제되지 않습니다.

에이전트 보안의 정책 테스트에서 선택한 멤버, 그룹 또는 역할과 일치하는 정책을 확인하세요. 편집 가능한 세션에서는 현재 초안을 저장하지 않고 확인합니다. 결과는 선택된 정책을 보여 주며, 병합된 최종 구성이나 클라이언트가 실제로 제한을 강제하는지까지 보여 주지는 않습니다. 저장한 후 관련 클라이언트와 실행 경로 각각에서 허용 및 차단 대상 워크플로우를 테스트하세요.

디바이스 관리형 구성 배포하기

인증 제한 및 디바이스 관리형 정책에는 로컬 시스템 요구 사항 또는 MDM을 사용하세요. 레거시 managed_config.toml 방식은 시작 시 에이전트 보안의 기본값과 다른 우선순위를 따릅니다. MDM 워크플로우에서는 요구 사항과 레거시 기본값을 모두 배포할 수 있습니다.

로컬에서 인증 관리하기

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 구성은 요구 사항 레퍼런스를 참조하세요.

OpenTelemetry 설정 강제하기

Codex CLI 0.166.0에서는 [otel]을 requirements.toml에 추가해 로그, 트레이스, 메트릭의 내보내기 도구를 각각 설정하고 환경 레이블과 Codex가 내보낼 내용을 지정할 수 있습니다. 다음 예제는 로그를 OTLP/HTTP 수집기로 보내고, 도구 결과 하나당 로그에 기록할 텍스트를 UTF-8 기준 256바이트로 제한합니다. 프롬프트 본문, 최종 응답 본문, 자동 승인 평가 내용은 기록하지 않습니다.

macOS 데스크톱 앱 26.1027.30824에는 CLI 0.166.0-alpha.5.1이 포함되어 있습니다. 이 빌드는 [otel]을 requirements.toml에서 지원하지 않으므로 이 정책으로 log_user_prompt = false를 강제할 수 없습니다.

[otel]
environment = "prod"
exporter = { otlp-http = { endpoint = "https://otel.example.com/v1/logs", protocol = "binary" } }
log_user_prompt = false
log_agent_responses = false
log_guardian_assessments = false
tool_result = { max_bytes = 256 }
span_attributes = { team = "platform" }
tracestate = { acme = { region = "eu" } }

관리형 값은 로컬 구성보다 우선합니다. exporter, trace_exporter, metrics_exporter 각각에 대해 해당 내보내기 도구를 설정한 요구 사항 중 우선순위가 가장 높은 요구 사항의 정의 전체가 적용됩니다. 여기에는 헤더와 TLS 설정도 포함됩니다. 스칼라 설정과 tool_result 테이블에도 각각 지정된 값 중 우선순위가 가장 높은 값이 적용됩니다. 생략한 설정은 다른 요구 사항 계층에서 지정하지 않는 한 사용자가 구성할 수 있습니다.

스팬 속성은 속성 이름을 기준으로 병합합니다. tracestate 필드는 멤버와 필드 이름을 기준으로 병합합니다. 일치하는 항목은 우선순위가 더 높은 값을 사용합니다. 다른 항목은 유지되며, 빈 메타데이터 테이블로 지워지지 않습니다. 내보내기 도구 옵션과 로그 내용은 관측 가능성 및 텔레메트리를 참조하세요.

NFS의 SQLite 데이터베이스 마이그레이션하기

Linux에서 Codex는 NFS에 새 SQLite 데이터베이스를 만들 때 DELETE 저널 모드를 사용합니다. 기존 데이터베이스를 선행 기록 로그(WAL) 모드에서 이 모드로 전환하려면 unsafe_enforce_sqlite_journal_mode = true를 requirements.toml의 최상위에 설정하세요. 이 설정은 기본적으로 꺼져 있습니다. 활성화하면 Codex는 데이터베이스를 쓰기용으로 열기 전에 마이그레이션합니다.

NFS 마운트가 호스트 간 POSIX 잠금을 지원해야 합니다. nolock이나 local_lock=all 같은 마운트 옵션을 사용하면 이 잠금이 작동하지 않습니다. 모든 호스트에서 Codex를 포함해 해당 데이터베이스를 사용하는 SQLite 클라이언트를 모두 중지하세요. Codex 인스턴스 하나만 시작하고 마이그레이션이 성공할 때까지 다른 모든 클라이언트는 중지된 상태로 두세요. 해당 인스턴스를 실행하는 사용자에게는 데이터베이스 디렉터리와 마이그레이션 잠금에 대한 쓰기 권한이 필요합니다. 교체된 파일은 기존 Unix 권한 비트를 유지하며 해당 사용자 소유가 됩니다. 마이그레이션 시 원본의 소유자, 그룹, 확장 접근 제어 목록은 복사하지 않습니다. Codex는 원본 파일을 비공개 백업 디렉터리에 보관합니다.

관리형 기본값(managed_config.toml)

지원되는 클라우드 관리형 초기값에는 에이전트 보안 기본값을 사용하세요. 이 섹션에서는 레거시 디바이스 관리형 managed_config.toml 방식과 이 방식의 시작 우선순위를 설명합니다. 에이전트 보안에서 기본값을 편집해도 멤버의 디바이스에 managed_config.toml 파일이 배포되지는 않습니다.

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

ChatGPT로 로그인하는 Codex에서 GPT-5.5 지원은 2026년 10월 14일 정오 PDT(19:00 UTC)에 종료됩니다. 관리형 기본값, macOS MDM 프로필 또는 저장된 구성에서 해당 사용자의 모델을 gpt-5.5로 고정했다면 사용 가능한 모델로 교체하세요. 관리자가 해당 사용자에게 활성화한 후에는 gpt-6.1-sol을 선택하세요. OpenAI API 및 API 키로 인증한 Codex 세션에는 영향이 없습니다. 워크스페이스 모델 가용성을 참조하세요.

아직 gpt-5.4 또는 gpt-5.4-mini를 고정한 구성은 GPT-5.4 마이그레이션 안내를 따르세요.

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

우선순위와 구성 계층

로컬 런타임은 다음 순서로 최종 구성을 결정합니다. 위쪽 항목이 아래쪽 항목보다 우선합니다.

• 관리형 환경설정(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

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

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 = { endpoint = "https://otel.example.com/v1/logs", protocol = "binary" } }
log_user_prompt = false            # keep prompts redacted

권장 가드레일

• 대부분의 사용자에게는 workspace-write와 승인을 함께 사용하세요. 전체 권한은 통제된 컨테이너에만 부여하세요.
• 보안 검토에서 수집기 또는 워크플로우에 필요한 도메인에 대한 접근을 허용하지 않는 한 network_access = false를 유지하세요.
• 텔레메트리 설정을 강제하려면 OpenTelemetry 요구 사항을 사용하세요. 정책에서 프롬프트 내용 저장을 허용하지 않는 한 log_user_prompt = false를 유지하세요.
• 로컬 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 설정과 동일한 변경 관리 절차를 적용하세요.