Codex 권한 프로필은 config.toml에 정의하는 이름 있는 정책으로, Codex가 내 컴퓨터에서 실행하는 명령이 파일을 읽고 쓰거나 네트워크에 접근할 수 있는 범위를 결정합니다. default_permissions로 하나를 선택하고, 기본 제공 프로필(:read-only, :workspace, :danger-full-access)에서 시작한 다음 read, write, deny 경로와 도메인 허용 목록을 추가합니다.
이 가이드에서는 가장 일반적인 설정에 바로 복사해 쓸 수 있는 config.toml 예시를 제공합니다. 여기에는 코딩 에이전트가 인터넷 전체를 열지 않고도 자사 API 호스트를 대상으로 Apidog CLI 테스트를 실행할 수 있게 하는 API 작업용 예시도 포함됩니다.
Codex 권한 프로필이란?
권한 프로필은 Codex에서 재사용할 수 있는 샌드박스 정책입니다. 파일 시스템 규칙(명령이 읽거나 쓰거나 아예 건드리지 못할 경로)과 네트워크 규칙(명령이 네트워크에 접근할 수 있는지, 어떤 도메인에 접근할 수 있는지)을 결합합니다. Codex는 macOS에서는 Seatbelt, Linux와 WSL에서는 bubblewrap과 seccomp, Windows에서는 MXC로 이 정책을 적용합니다.
OpenAI는 2026년 11월 18일 게시한 Inside the Codex sandbox에서 이 설계를 설명했습니다. Codex는 작업을 컨테이너로 옮기는 대신 기존 환경에서 명령을 제한하므로 네이티브 툴체인을 그대로 실행할 수 있습니다.
Codex에는 세 가지 기본 제공 프로필이 있습니다:
| 프로필 | 파일 시스템 | 네트워크 |
|---|---|---|
:read-only |
명령은 읽을 수 있지만 쓸 수 없음 | 꺼짐 |
:workspace |
워크스페이스 루트와 임시 디렉터리 안에서는 쓰기 가능; .git, .agents, .codex, .aws는 읽기 전용 유지 |
꺼짐 |
:danger-full-access |
로컬 샌드박스 제한 없음 | 전체, 직접 |
권한 문서에서는 아직 이 기능을 Beta로 표시하므로 릴리스마다 키가 바뀔 수 있습니다.
config.toml에서 permissions 테이블의 위치
프로필은 ~/.codex/config.toml(또는 프로젝트나 시스템 계층)에 위치합니다. 중요한 최상위 요소는 두 가지입니다:
default_permissions는 Codex가 기본으로 적용할 프로필의 이름을 지정합니다. 기본 제공 프로필이나[permissions]아래의 프로필과 일치해야 합니다.[permissions.<name>]은 프로필을 정의합니다.description을 지정하면/permissions선택기에 표시됩니다.
많은 사람이 놓치는 규칙이 하나 있습니다. 권한 프로필은 이전 샌드박스 설정과 함께 사용할 수 없습니다. 불러온 구성 파일 중 하나라도 sandbox_mode를 포함하거나 --sandbox를 전달하면 Codex는 이전 설정을 사용하고 default_permissions를 무시합니다. 전환하기 전에 sandbox_mode와 [sandbox_workspace_write]를 제거하세요.
프로필은 일반적인 구성 우선순위 모델을 따릅니다. 테이블이 재귀적으로 병합되므로 팀 구성에서 전체 내용을 다시 작성하지 않고도 조직 프로필에 도메인 하나나 경로 하나를 추가할 수 있습니다.
파일 시스템 규칙: read, write, deny
각 파일 시스템 항목은 경로를 read, write, deny 중 하나에 매핑합니다. 더 구체적인 경로가 더 넓은 경로보다 우선하며, 두 항목이 같은 경로를 대상으로 하면 deny가 write보다, write가 read보다 우선합니다.
가장 자주 사용할 경로 형식은 다음과 같습니다:
:minimal: 일반적인 도구에 필요한 플랫폼 및 런타임 경로:workspace_roots: 세션의 워크스페이스 루트와 프로필이 추가하는 루트:root,:tmpdir,:slash_tmp, 절대 경로 및~/경로
기본 제공 보호 장치를 다시 만드는 대신 extends로 상속하세요. 다음은 :workspace 기본값을 유지하면서 시크릿을 잠그는 프로필입니다:
default_permissions = "dev"
[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
:workspace_roots 아래의 규칙은 모든 루트에 적용되므로 secrets는 각 프로젝트 루트의 secrets 폴더를 의미합니다. 프로필은 :read-only, :workspace 또는 다른 이름 있는 프로필을 확장할 수 있습니다. :danger-full-access는 확장할 수 없습니다.
Linux, WSL 및 네이티브 Windows에서는 범위 제한 없는 ** deny 글롭에 [permissions.<name>.filesystem] 아래의 glob_scan_max_depth(최소 1)가 필요할 수 있습니다. 그래야 Codex가 샌드박스가 시작되기 전에 이를 확장할 수 있습니다.

네트워크 규칙: 끄기, 열기, 허용 목록
네트워크에는 세 가지 상태가 있으며 두 가지 설정으로 제어합니다:
- 네트워크 끄기(
enabled = false,:workspace기본값): 명령이 네트워크에 접근할 수 없습니다. - 네트워크 켜기, 프록시 끄기: 명령이 제한 없이 직접 접근합니다. 도메인 규칙은 무시됩니다.
- 네트워크 켜기, 프록시 켜기: 트래픽이 Codex 네트워크 프록시를 거치며, 프록시가 프로필의 도메인 규칙을 적용합니다.
두 번째 상태가 함정입니다. permissions.<name>.network.enabled = true를 설정해도 프록시는 시작되지 않습니다. 최상위 수준에 다음도 필요합니다:
[features]
network_proxy = true
도메인 패턴은 정확한 호스트(api.example.com), 하위 도메인만 나타내는 *.example.com, 에이펙스와 하위 도메인을 모두 나타내는 **.example.com, 허용 전용 전역 와일드카드인 *를 지원합니다. deny 항목은 allow 항목보다 우선하며, allow 항목이 없는 활성 프록시는 모든 외부 연결을 차단합니다.
프록시가 활성화되면 기본적으로 로컬 및 사설 네트워크 대상도 차단합니다. 로컬 서비스에 접근하려면 "localhost" = "allow" 또는 "127.0.0.1" = "allow"처럼 호스트를 그대로 허용 목록에 추가하세요.
API 작업을 위한 Codex 권한 프로필
다음은 API 개발용으로 테스트한 프로필입니다. 워크스페이스의 코드를 편집하고, .env 파일이나 secrets 폴더는 절대 읽지 않으며, 자사 API 호스트와 Apidog에만 접근할 수 있습니다:
default_permissions = "api-work"
[features]
network_proxy = true
[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"
[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"
[permissions.api-work.network]
enabled = true
[permissions.api-work.network.domains]
"api.your-company.com" = "allow" # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow" # Apidog CLI and its API
두 호스트를 테스트가 실제로 요청하는 호스트로 바꾸세요. Apidog CLI는 내 컴퓨터에서 테스트 대상 API로 요청을 보내므로 Apidog 호스트뿐 아니라 해당 API 호스트도 허용 목록에 있어야 합니다. 로컬 서버를 테스트한다면 "localhost" = "allow"를 추가하세요.
패키지는 세션 안이 아니라 세션 전에 설치하세요. npm install -g apidog-cli@latest를 실행하려면 registry.npmjs.org가 필요한데, 이 프로필은 해당 도메인을 의도적으로 차단합니다.
테스트 실행 중 발견한 주의 사항이 하나 있습니다. 프록시 앱이나 VPN을 fake-IP DNS 모드로 실행하는 Mac에서는 허용된 모든 호스트가 198.18.x.x 주소로 확인되었습니다. 로컬/사설 주소 가드가 이를 사설 주소로 간주해 차단했고, Codex는 “local/private network addresses are blocked by the sandbox policy.”라고 보고했습니다. [permissions.api-work.network] 아래에 allow_local_binding = true를 추가하면 해결되지만, 사설 주소로 확인되는 허용 목록의 호스트 이름도 열리므로 꼭 필요할 때만 설정하세요.
codex sandbox로 프로필 테스트하기
프로필이 무언가를 차단하는 모습을 직접 확인하기 전까지는 믿지 마세요. codex sandbox 명령은 지정한 프로필 아래에서 임의의 명령을 실행하고 현재 디렉터리를 워크스페이스 루트로 취급합니다:
codex sandbox --permission-profile api-work -- cat README.md .env
위 프로필로 실행했을 때 README가 출력된 다음 다음과 같은 메시지가 나왔습니다:
cat: .env: Operation not permitted
워크스페이스 밖에 쓰기는 같은 방식으로 실패했고(Operation not permitted), 워크스페이스 안의 새 파일은 생성되었습니다. 네트워크의 경우 목록에 추가하지 않은 호스트를 프록시가 차단하는지 확인하세요:
codex sandbox -P api-work -- curl -sI https://example.org
프록시는 x-proxy-error: blocked-by-allowlist와 함께 403 Forbidden을 반환했고, apidog.com은 200을 반환했습니다. macOS에서는 --log-denials를 추가하면 명령이 종료된 후 Seatbelt 거부 내역을 출력합니다.
codex sandbox를 사용해 Codex가 자체적으로 샌드박스하지 않는 프로세스를 감쌀 수도 있습니다. OpenAI의 글에서는 config.toml의 stdio MCP 서버가 샌드박스 없이 실행된다고 설명하며, "~/mcp-data" = "write" 및 network.enabled = false를 사용하는 memory-mcp 프로필로 서버의 npx 명령을 감싸는 예를 보여 줍니다.
/permissions로 세션 중간에 프로필 전환하기
Codex CLI에서 /permissions를 입력하면 선택기가 열립니다. 이름 있는 프로필이 있으면 설명과 함께 목록에 표시됩니다. 프로필을 바로 선택하려면:
/permissions api-work --approval-policy=on-request --reviewer=user
그러면 현재 세션의 프로필이 설정되고 승인 요청이 사용자에게 전달됩니다. 프로필과 승인은 별개의 제어 수단입니다. 프로필은 샌드박스된 명령이 무엇에 접근할 수 있는지 결정하고, 승인 정책은 Codex가 샌드박스 범위를 벗어나기 전에 언제 사용자에게 물을지 결정합니다. CLI 명령 참조에서 다른 세션 명령을 확인할 수 있습니다.
Apidog CLI로 Codex가 API를 테스트하게 하기
api-work가 활성화되어 있으면 Codex는 인터넷 전체를 열지 않고도 실제 API 테스트를 실행할 수 있습니다. Apidog CLI는 에이전트가 읽을 수 있는 JSON 출력과 함께 엔드포인트, 테스트 케이스, 실행을 위한 명령을 제공합니다. 샌드박스 밖에서 한 번만 설정하면 됩니다:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
그런 다음 Codex에 다음 프롬프트를 주세요:
Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.
Codex는 페이로드 스키마를 읽고 JSON을 검증한 다음 케이스를 실행합니다:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json
테스트에서 apidog auth status와 apidog project list는 **.apidog.com만 허용 목록에 있는 api-work 샌드박스 안에서 모두 실행되었습니다. 토큰은 ~/.apidog에 남아 있으며, 프로필은 이를 읽을 수는 있지만 변경할 수는 없습니다. 전체 과정은 Codex에서 Apidog CLI 사용하기를 참고하고, 같은 실행을 CI 파이프라인으로 옮길 때는 -r cli,json을 -r junit으로 바꾸세요. Apidog의 Free 플랜은 최대 4명의 사용자를 지원합니다.

프로필을 신뢰하기 전에 알아야 할 한계
권한 프로필은 피해 범위를 줄여 주지만, 그 자체로 에이전트를 안전하게 만들지는 않습니다. 문서와 OpenAI의 글에서 다음과 같은 한계를 설명합니다:
:workspace에서는 광범위한 읽기가 계속 허용됩니다. 컴파일러에는 저장소 밖의 SDK와 구성이 필요하므로 API 키가 들어 있는 다른 위치의 구성 파일이 계속 읽힐 수 있습니다.~/.ssh및 유사한 경로를 명시적으로 거부하거나":root" = "deny"와":minimal" = "read"를 함께 사용하세요.- deny 글롭은 스냅샷입니다. Linux, WSL, Windows에서는 각 샌드박스 프로세스가 시작될 때 일치 항목이 확장됩니다. 나중에 생성된
.env는 오래 실행 중인 셸이나 개발 서버에서 읽을 수 있습니다. - 와일드카드는 여전히 DNS를 통해 유출될 수 있습니다. 프록시는 호스트 이름이 허용된 후에만 확인하지만, 광범위한 와일드카드 규칙이나 DNS 서비스 접근은 DNS 기반 유출을 허용할 수 있습니다.
- 프록시는 샌드박스된 명령만 포괄합니다. 웹 검색, 커넥터, MCP 서버, 브라우저, Codex 자체의 모델 트래픽은 별도 제어를 사용합니다.
- 쓰기는 세션보다 오래 지속될 수 있습니다. OpenAI의 예시는 변조된
node_modules/prettier로, 나중에 편집기가 저장 시 샌드박스 밖에서 실행합니다.
Codex 샌드박스를 우회하는 편법을 사용해 왔다면, 범위를 좁힌 사용자 지정 프로필이 보통 더 깔끔한 해결책입니다. 여러 머신에 정책을 적용해야 하는 팀은 Codex 보안 쿡북과 관리형 allowed_permission_profiles를 참고하세요.
FAQ
기본 Codex 권한 프로필은 무엇인가요?
의존할 만한 기본값은 없습니다. 문서에서는 예측 가능한 동작을 위해 default_permissions를 명시적으로 설정하라고 안내합니다. 대부분의 코딩 작업에는 :workspace가 합리적인 기반입니다. 워크스페이스 루트와 임시 디렉터리에서는 쓰기가 가능하고 네트워크는 꺼져 있습니다.
도메인 규칙이 무시되는 이유는 무엇인가요?
보통 features.network_proxy가 빠져 있기 때문입니다. network.enabled = true이고 프록시가 없으면 명령이 제한 없이 네트워크에 직접 접근합니다. 불러온 구성 중 sandbox_mode를 설정한 것이 없는지도 확인하세요. sandbox_mode는 프로필을 완전히 비활성화합니다.
Codex가 .env 파일을 읽지 못하게 하려면 어떻게 하나요?
[permissions.<name>.filesystem.":workspace_roots"] 아래에 "**/*.env" = "deny"를 추가하세요. Linux, WSL, Windows에서는 범위 제한 없는 ** 패턴에 glob_scan_max_depth를 설정하고, 이미 실행 중인 프로세스에는 새 일치 항목이 추가되지 않는다는 점을 기억하세요.
Codex 권한 프로필에서 localhost를 허용할 수 있나요?
네. "localhost" = "allow" 또는 "127.0.0.1" = "allow"처럼 호스트를 그대로 허용 목록에 추가하세요. 허용 목록의 호스트 이름이 로컬 또는 사설 주소로 확인될 때만 allow_local_binding = true를 설정하세요.
권한 프로필이 MCP 서버를 샌드박스하나요?
아니요. config.toml의 stdio MCP 서버는 샌드박스 없이 시작됩니다. 서버 명령을 codex sandbox --permission-profile <name> --로 감싸고 전용 프로필을 사용하세요.
--sandbox 플래그와 함께 프로필을 사용할 수 있나요?
아니요. --sandbox를 전달하거나 sandbox_mode를 설정하면 Codex는 default_permissions 대신 이전 샌드박스 설정을 사용합니다. 세션마다 한 가지 시스템만 선택하세요.
