Ch2. config.toml 설계

Codex의 동작은 config.toml로 제어합니다. 조직에서는 기본값을 표준화하고 프로젝트별로 필요한 부분만 덮어쓰는 방식이 잘 맞습니다.

설계 원칙

• 기본값은 보수적으로: 승인/샌드박스 옵션은 엄격하게
• 프로젝트 오버라이드 최소화: 팀 공용 기본값(Team Config/관리자 정책) 우선
• 비밀 정보 분리: 토큰/키는 환경 변수로 관리

설정 레이어(우선순위) 이해

Codex는 여러 레이어에서 설정을 읽습니다. 운영할 때는 "어디에 적으면 어떤 범위에 적용되는지"를 알아야 합니다.

• 프로젝트 설정: 레포 내부의 .codex/config.toml(프로젝트 루트 → 현재 작업 디렉토리까지 순회, 가장 가까운 파일이 승리, 단 trusted 프로젝트만 적용)
• 사용자 설정: ~/.codex/config.toml
• 시스템 설정(선택): Unix 기준 /etc/codex/config.toml
• 기본값: built-in defaults
• CLI 1회성 오버라이드: 전용 플래그(예: --model) 또는 --config로 단발성 덮어쓰기

팀 운영에 유용한 패턴

1) "기본 안전 + 예외만 프로필"로 설계

기본 설정은 보수적으로 두고, 역할/상황별 예외는 프로필로 분리합니다.

# ~/.codex/config.toml (예시)
model = "gpt-5.6-terra"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

# ~/.codex/deep-review.config.toml (예시)
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
review_model = "gpt-5.6-sol"

codex --profile deep-review
codex exec --profile deep-review "review this change"

2) CLI 오버라이드는 "전용 플래그 우선, 없으면 --config"

--config는 값이 JSON이 아니라 TOML로 파싱됩니다. 이 점을 팀에 미리 공유해두면 삽질이 줄어듭니다.

# 전용 플래그 (권장)
codex --model gpt-5.6

# 범용 오버라이드 (value는 TOML)
codex --config model='\"gpt-5.6-sol\"'

Amazon Bedrock built-in provider (0.148.0+)

model_provider = "amazon-bedrock"

[model_providers.amazon-bedrock.aws]
profile = "engineering"
region = "us-west-2"

0.148.0의 built-in provider는 AWS profile·region을 사용해 GPT-5.6 variant로 routing합니다. 실제 model ID와 reasoning 목록은 Bedrock 계정의 /model inventory를 기준으로 검증하세요.

0.122.0부터는 재현성 높은 자동화를 위해 사용자 전역 설정과 rules를 일부러 무시하는 플래그 --ignore-user-config, --ignore-rules도 생겼습니다. 개인 취향이 섞이면 안 되는 CI나 비교 실험에서는 이 플래그를 함께 고려하세요.

3) CODEX_HOME(로컬 상태) 기준으로 "환경 재현성" 관리

Codex는 로컬 상태를 CODEX_HOME 아래에 저장하고, 기본값은 ~/.codex입니다. 팀에서 재현/디버깅이 잦다면 문제 재현 시 CODEX_HOME과 설정 파일을 함께 수집하는 절차를 정하세요.

4) Feature Flags 관리

codex features 명령으로 실험적 기능을 켜고 끌 수 있습니다.

codex features list              # 전체 플래그 확인
codex features enable multi_agent   # 멀티에이전트 활성화
codex features disable shell_snapshot

변경은 ~/.codex/config.toml 또는 지정된 프로필에 저장됩니다.

5) 플러그인/요구사항(requirements)도 설정 레이어로 취급

최근 릴리스 기준으로 Codex는 플러그인 단위로 skills/MCP/apps를 로드할 수 있고, 관리자 requirements.toml은 웹 검색 모드와 네트워크 제약까지 강제합니다.

• 플러그인 카탈로그 운영: "실험용 → 팀 allowlist → 전사 배포" 순으로 승격시키는 절차를 둡니다
• required MCP 최소화: fail-fast 동작이 강화됐기 때문에, 정말 필수인 서버만 required로 승격합니다
• 네트워크 제약 문서화: requirements.toml에서 허용된 네트워크/검색 모드를 함께 기록해 현장 편차를 줄입니다
• cloud-managed requirements: Business/Enterprise/Edu 조직은 Codex 서비스에서 requirements.toml compatible 정책을 배포할 수 있습니다. 0.137.0 이후 cloud-managed config bundle 적용 흐름이 보강됐으므로 CLI/App/IDE 전반에 걸친 정책 적용 여부를 /debug-config와 관리자 화면에서 함께 점검하세요
• marketplace source 표준화: 0.121.0부터 codex marketplace add가 GitHub, git URL, 로컬 디렉토리, 직접 marketplace.json URL을 지원하므로, 팀은 "어떤 source만 허용할지"를 allowlist로 정하는 편이 좋습니다
• plugin sharing 정책화: 0.129.0~0.130.0부터 workspace sharing, share access controls, source filtering, link metadata, discoverability controls가 강화됐습니다. 개인 실험 plugin과 팀 공유 plugin을 같은 목록에서 다루지 말고, share 권한과 discoverability를 릴리즈 절차에 포함하세요.
• plugin JSON 감사: 0.138.0~0.139.0 기준 codex plugin add/remove --json, codex plugin list --available --json, codex plugin marketplace list --json이 marketplace source와 설치/가용 상태를 구조화해 출력합니다. 팀 감사는 /plugins 화면 캡처보다 JSON 출력을 기준으로 삼으세요.

6) TUI keymap과 입력 모드도 설정으로 관리

0.128.0부터 configurable TUI keymaps가 들어왔고, 0.129.0에서는 /keymap과 modal Vim composer 흐름이 좋아졌습니다. 팀에서 pair/mob 세션이나 원격 터미널을 많이 쓴다면 shortcut 충돌을 개인 취향에 맡기지 말고 기본 keymap만이라도 문서화하세요.

[tui.keymap.global]
# 예시는 팀 표준에 맞게 실제 CLI에서 /keymap으로 확인한 뒤 고정

조직 표준(강제/공유) 레이어

• 관리자 강제(requirements.toml): 조직이 허용하는 approval_policy/sandbox_mode 범위를 제한할 수 있습니다(예: never 또는 danger-full-access 금지).
• Team Config: 팀 공용 기본값/규칙/스킬을 공유하는 계층입니다.

Team Config 운영

Team Config는 공용 config.toml + rules/skills를 중앙에서 배포하기 위한 레이어입니다. CLI는 다음 경로에서 .codex/ 디렉토리를 순서대로 탐색하며, config.toml, rules/, skills/를 로드합니다.

1. 현재 작업 디렉토리
2. 부모 디렉토리(상위로 순회)
3. Git 리포지토리 루트
4. 사용자 홈(~/.codex)
5. 시스템(/etc/codex)

이 구조를 활용하면 팀 표준은 상위 레이어로 고정하고 프로젝트별 예외만 로컬에서 좁게 덮어쓸 수 있습니다.

설정 진단: /debug-config

설정이 꼬였을 때 /debug-config를 실행하면 각 레이어의 설정 값과 우선순위를 한눈에 볼 수 있습니다. requirements.toml이 제한한 값도 표시되므로 디버깅할 때 요긴합니다.

Permission Profile 설정 언어

최신 config reference에서는 default_permissions와 [permissions.<name>] 테이블로 파일시스템 정책과 네트워크 정책을 분리해서 선언할 수 있습니다. 0.133.0~0.135.0 이후에는 profile inheritance, managed requirements.toml, 런타임 refresh, /permissions 내 custom profile 표시가 좋아져서, 운영자가 의도한 프로필이 실제 세션에 적용됐는지 확인하기 쉬워졌습니다.

# config.toml 예시
default_permissions = "safe"

[permissions.safe]
description = "Workspace edits with OpenAI and registry access."
extends = ":workspace"

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

[permissions.safe.network]
enabled = true

[permissions.safe.network.domains]
"api.openai.com" = "allow"
"registry.npmjs.org" = "allow"

팀에서는 :read-only, :workspace, :danger-full-access 같은 built-in profile을 그대로 쓰거나, :workspace를 extends한 named permission profile로 파일/네트워크 예외를 좁게 선언한 뒤 /debug-config와 /permissions picker에서 실제 병합 결과를 확인하세요.

deny-read 정책으로 "보이되 못 읽게" 만들기 (0.122.0)

0.122.0부터 filesystem permissions는 "deny" 값을 쓴 deny-read glob 정책을 더 잘 지원합니다. "프로젝트 전체는 쓰게 두되, 비밀 파일과 일부 민감 경로만 읽지 못하게" 막는 게 핵심입니다.

[permissions.safe.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"
"secrets/**" = "deny"

• permissions.<name>.filesystem.<scope>.<path-or-glob> = "deny"로 읽기 차단
• :workspace_roots는 현재 세션의 workspace roots와 profile-defined roots에 같은 규칙을 적용
• 관리형 requirements에서도 deny-read 정책을 강제할 수 있으므로, 조직 표준으로 승격하기 좋음

팀 운영 팁:

• .env, secrets/, 배포 자격증명 디렉토리는 deny-read로 먼저 막고 시작
• 쓰기 권한이 필요해도 "읽으면 안 되는 것"은 별도로 분리
• /debug-config로 실제 profile 병합 결과를 꼭 확인

스킬 enablement 설정

최신 config reference는 skills.config로 특정 스킬 경로의 활성 여부를 관리합니다. 팀에서는 개인 실험용 스킬과 프로젝트 표준 스킬을 나누고, 위험한 스크립트가 든 스킬은 기본 disabled로 두는 편이 안전합니다.

[[skills.config]]
path = "/Users/you/.codex/skills/release-checklist"
enabled = true

[[skills.config]]
path = "/Users/you/.codex/skills/destructive-maintenance"
enabled = false

웹 검색 정책화

web_search는 disabled | cached | live를 지원합니다. 기본값은 cached이며, --yolo 같은 full access 모드에서는 기본이 live로 동작할 수 있으므로(운영/컴플라이언스 관점), 팀 정책으로 명시하는 편이 안전합니다.

최근 릴리스에서는 관리자 requirements.toml이 웹 검색 모드 제한뿐 아니라 네트워크 제약까지 함께 강제하도록 확장됐습니다. 보안팀/플랫폼팀은 "누가 live 검색을 쓸 수 있는지"와 "어떤 네트워크 경로를 열 수 있는지"를 한 문서에서 관리하는 편이 좋습니다.

0.122.0부터는 tool discovery와 image generation이 기본 활성화됩니다. Codex가 작업에 도움이 된다고 판단하면 내장 도구를 더 적극적으로 찾고 제안한다는 뜻입니다. deterministic한 CI나 감사 중심 환경에서는 프롬프트, rules, permissions에 "웹 검색 금지", "이미지 생성 금지" 같은 제약을 명시적으로 적어 두는 편이 안전합니다.

웹 검색 도구 상세 설정

웹 검색은 top-level web_search와 tools.web_search 객체형 설정으로 관리합니다. 검색 context size, allowed domains, user location을 세밀하게 제어할 수 있습니다.

# config.toml 예시
web_search = "live"

[tools.web_search]
context_size = "medium"
allowed_domains = ["developers.openai.com", "github.com"]

[tools.web_search.location]
country = "KR"
timezone = "Asia/Seoul"

팀에서 검색 범위를 사전 제한하면 비용 절감과 보안 경계 관리에 모두 도움이 됩니다.

0.152.0~0.153.0 신규 설정 키

이 구간에서 기본값이 바뀐 설정이 하나 있어 먼저 확인해야 합니다.

# 0.152.0: planning tool이 기본 비활성화됨. 계획 도구가 필요하면 명시적으로 켠다
[tools.update_plan]
enabled = true

[tui]
# 0.153.0: 자동 recap을 끄고 수동 /recap만 남긴다
auto_recap = false
# 0.153.0: top-level disable_paste_burst를 대체 (기존 키는 fallback으로 계속 인식)
disable_paste_burst = true

# 0.153.0: 기본 비활성화 실험 기능. 적격 ChatGPT Plus·Pro·Pro Lite 세션에서
# token-budget context, history notes, new_context 도구를 활성화한다.
# API key 세션, custom provider, 임시 structured thread는 제외된다.
[features.context_management]
experimental_mode = true

• tools.update_plan.enabled: 0.152.0부터 planning tool이 기본 비활성화입니다. 팀 runbook이 계획 도구 출력에 의존한다면 명시적으로 켜세요. 슬래시 명령 /plan과는 별개 개념입니다.
• MCP per-tool 출력 상한: 0.152.0부터 개별 MCP tool에 output_token_limit을 지정할 수 있고, 세션 resume 전후로 동일한 truncation이 적용됩니다.
• MCP 서버 이름 규칙 완화: 0.152.0부터 :, @, /, .를 포함한 package 스타일 이름을 CLI 명령과 인증 전 경로에서 사용할 수 있습니다.
• optional MCP discovery grace: 0.151.0에서 선택적 MCP 서버의 tool 탐색 대기 시간을 설정할 수 있게 됐습니다. 필수 서버와 선택 서버의 startup 정책을 분리하세요.
• app-server 타임아웃: 0.152.0부터 app-server 클라이언트가 thread/shellCommand 타임아웃을 1시간 이상으로도 설정할 수 있습니다.

0.145.0~0.146.0 plugin·proxy 운영

• Agent Plugin manifest와 workspace plugin publish 결과를 공급망 inventory에 포함합니다.
• Amazon Bedrock·Claude Code marketplace가 추가됐으므로 marketplace source allowlist를 다시 검토합니다.
• auth·plugin·MCP·remote/WebSocket·redirect·LM Studio까지 proxy 처리가 넓어졌습니다. HTTP_PROXY/HTTPS_PROXY/NO_PROXY가 모든 경로에서 같은 정책을 따르는지 smoke test하세요.
• remote Code Mode host와 executor-provided skill/resource는 로컬 config만 보고는 완전한 tool surface를 알 수 없으므로 /plugins, /skills, /mcp, /debug-config를 함께 캡처합니다.

참고 문서

• config 기본: https://developers.openai.com/codex/config-basic (영어)
• Team Config: https://developers.openai.com/codex/team-config (영어)
• config 고급: https://developers.openai.com/codex/config-advanced (영어)
• config 레퍼런스: https://developers.openai.com/codex/config-reference (영어)
• config 예시: https://developers.openai.com/codex/config-sample (영어)
• Permissions: https://developers.openai.com/codex/permissions (영어)
• Managed configuration: https://developers.openai.com/codex/enterprise/managed-configuration (영어)
• Customization 가이드: https://developers.openai.com/codex/concepts/customization (영어)
• GitHub Releases: https://github.com/openai/codex/releases (영어)