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.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

# 필요하면 기본 프로필을 지정
# profile = "deep-review"

[profiles.deep-review]
model_reasoning_effort = "high"
review_model = "gpt-5.5"

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

--config는 값이 JSON이 아니라 TOML로 파싱된다는 점을 팀에 공유해두면 삽질을 줄일 수 있습니다.

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

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

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에서 허용된 네트워크/검색 모드를 함께 기록해 현장 편차를 줄입니다
• 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를 릴리즈 절차에 포함하세요.

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>] 테이블로 파일시스템 정책과 네트워크 정책을 분리해서 선언할 수 있습니다. 기존 sandbox_mode 한 줄로 표현하기 어려웠던 세밀한 제어가 가능해졌습니다.

# config.toml 예시
default_permissions = "safe"

[permissions.safe.filesystem]
"/Users/you/work/repo" = "write"

[permissions.safe.filesystem.":project_roots"]
"**/*.env" = "none"
"secrets/**" = "none"

[permissions.safe.network]
enabled = true
mode = "limited"

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

기존 sandbox_mode 설정과 함께 사용할 수 있습니다. 팀에서는 sandbox_mode로 큰 경계를 정하고, named permission profile로 파일/네트워크 예외를 좁게 선언한 뒤 /debug-config로 실제 병합 결과를 확인하세요.

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

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

[permissions.safe.filesystem]
"/Users/you/work/repo" = "write"
"/Users/you/work/repo/**/*.env" = "none"
"/Users/you/work/repo/secrets/**" = "none"
glob_scan_max_depth = 6

• permissions.<name>.filesystem.<path-or-glob> = "none"으로 읽기 차단
• glob_scan_max_depth로 deny-read glob 확장 범위를 제한
• 관리형 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"

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

참고 문서

• 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 (영어)
• Customization 가이드: https://developers.openai.com/codex/concepts/customization (영어)
• GitHub Releases: https://github.com/openai/codex/releases (영어)