공개 노트

OpenAI Codex CLI - MCP/설정 파일 로드 순서(우선순위)

2026-03-13Views 190약 3분생성형 AI 활용

Summary

요약(한 줄)

Codex CLI 설정은 "명령줄/환경변수 → (신뢰한)프로젝트 → 사용자 → 시스템 → 내장 기본값" 순으로 덮어씁니다.¹

우선순위(높음→낮음)

CLI 플래그 (예: 실행할 때 --profile 같은 옵션으로 즉시 덮어쓰기)
환경변수 (예: 모델/엔드포인트/키 같은 값이 환경에서 주입되면 파일보다 우선)
프로젝트 설정: .codex/config.toml (단, 프로젝트를 trust 했을 때만 로드)¹
사용자 설정: ~/.codex/config.toml²
시스템 설정(Unix): /etc/codex/config.toml (파일이 있을 때)¹
내장 기본값(built-in defaults)¹

프로젝트 설정이 "오버라이드"로 동작한다는 말은, 같은 키가 여러 곳에 있으면 더 높은 우선순위가 이긴다는 뜻입니다. 그래서 팀 공통값은 프로젝트에, 개인 취향(모델/출력 스타일 등)은 사용자 파일에 두는 식으로 나누는 게 안전합니다.

MCP 설정은 어디에 두나

MCP 서버 정의는 보통 config.toml 안에 mcp_servers 아래에 둡니다. 전역으로 항상 쓰는 MCP는 ~/.codex/config.toml에, 레포에서만 필요한 MCP는 .codex/config.toml에 두면 "개인 기본값 + 프로젝트 덮어쓰기" 구조가 됩니다(단, 프로젝트 trust 필요).¹²

예시는 이런 모양입니다(키 이름은 서버 ID로 생각하면 됩니다).

[mcp_servers.openfeature]
command = "npx"
args = ["-y", "@openfeature/mcp"]

서버를 프로젝트에만 두면 팀원들이 같은 레포에서 같은 도구 구성을 공유하기 좋지만, 그만큼 "신뢰하지 않은 프로젝트에서 자동으로 외부 도구가 붙는 것"을 막기 위해 trust가 로딩 조건이 됩니다.¹

`.mcp.json` vs `config.toml` (Claude Code와 차이)

Codex CLI(OpenAI)는 MCP 서버 설정을 TOML 기반 config.toml에 넣는 방식이 정식입니다. 전역은 ~/.codex/config.toml, 프로젝트는 .codex/config.toml(프로젝트 trust 시 로드)로 나뉘고, 보통 mcp_servers 아래에 서버를 정의합니다.⁴

반면 Claude Code(Anthropic)는 MCP 서버 설정을 JSON으로 분리해 관리하는 편입니다. 팀 공유용 프로젝트 설정은 레포 루트의 .mcp.json에 두고, 사용자/로컬 상태는 ~/.claude.json 등 다른 저장소에 들어갈 수 있습니다.³

정리하면, .mcp.json은 Claude Code 쪽 관례/구현이고 Codex CLI는 config.toml이 기본 설정 파일이라 파일명과 포맷을 서로 바꿔 쓸 수 없습니다.

자주 겪는 문제와 체크리스트

프로젝트 설정이 안 먹는 경우는 대부분 "프로젝트를 trust 하지 않아서"입니다. Codex는 보안 때문에 trust 전에는 .codex/config.toml을 읽지 않습니다.¹

중복 정의가 있을 때는, 같은 설정 키가 여러 파일에 있으면 더 높은 우선순위의 값으로 최종 결정됩니다. 그래서 프로젝트 파일에 MCP를 켰는데도 세션에서 다르게 보이면, CLI 플래그나 환경변수가 위에서 덮고 있는지부터 의심하는 게 빠릅니다.¹

프로젝트 설정이 안 먹는다: 해당 레포를 trust 했는지 확인¹
같은 값이 자꾸 바뀐다: CLI 플래그로 실행 중인지 확인(실행 스크립트/alias 포함)¹
환경변수로 덮는지 확인: 쉘 프로필(.zshrc 등), direnv, CI 환경에서 주입 여부 점검¹
파일 위치 확인: 프로젝트는 .codex/config.toml, 전역은 ~/.codex/config.toml, 시스템은 /etc/codex/config.toml¹²