Codex 설정이 적용되지 않는 이유: .codex/ 폴더 구조 문제

Codex 설정이 적용되지 않았습니다. config.toml을 편집하고, AGENTS.md에 규칙을 추가하고, 문서를 두 번 다시 읽었습니다. 그래도 아무것도 바뀌지 않았습니다. 에이전트는 모든 것을 무시했습니다.

결국 전체 폴더 구조를 직접 뜯어보았습니다. 문제는 파일에 무엇을 작성했느냐가 아니었습니다. 파일이 어디에 놓여 있느냐가 문제였습니다.

하나의 저장소에 두 가지 목적이 공존합니다

Codex는 두 가지 문제를 동시에 해결하려 합니다. 하나는 자체 베타 기능의 빠른 실험이고, 다른 하나는 Claude Code나 OpenCode 같은 도구들도 읽을 수 있는 크로스 에이전트 호환성, 즉 공유 표준입니다.

이 두 목적이 두 개의 폴더를 만들어냅니다.

.codex/는 Codex 전용 설정 공간입니다. 샌드박스 정책, 승인 규칙, 런타임 가드레일이 여기에 들어갑니다. .agents/는 공유 포맷입니다. 스킬, 플러그인, 마켓플레이스 레지스트리가 이쪽에 위치하며, 표준을 따르는 어떤 에이전트든 읽을 수 있습니다.

처음에는 이 구분을 몰랐습니다. SKILL.md 파일을 .codex/에 넣었는데 스킬이 전혀 로드되지 않았습니다. .agents/skills/로 옮기자 즉시 해결되었습니다. 경계는 엄격합니다. 다른 에이전트가 읽어야 하는 파일이라면 .agents/에 두어야 합니다. 그 외의 것은 .codex/에 들어갑니다.

두 폴더 모두 workspace-write 모드에서 .git/과 동일하게 읽기 전용 보호가 적용됩니다.

프로젝트 설정과 사용자 설정이 같은 이름을 씁니다

프로젝트 루트에 .codex/가 있고, 홈 디렉토리에도 ~/.codex/가 있습니다. 이 두 폴더는 완전히 다른 역할을 담당합니다.

프로젝트의 .codex/에는 팀과 공유하는 설정이 들어갑니다. 샌드박스 정책, 승인 워크플로우, 에이전트 정의가 여기에 해당합니다. ~/.codex/에는 개인 상태가 저장됩니다. 인증 토큰, 명령 기록, 워크트리 관리 파일들이 여기에 쌓입니다.

저는 ~/.codex/agents/에 리뷰어 에이전트를 만들어두고 팀원들이 왜 그걸 쓸 수 없는지 한참 이해하지 못했습니다. 그 파일은 제 컴퓨터에만 존재했습니다. 파일을 프로젝트의 .codex/agents/reviewer.toml로 옮기고 나서야 저장소를 클론할 때 함께 따라오게 되었습니다.

Codex가 아직 베타 단계라는 점이 혼란을 더 심하게 만듭니다. 데스크탑 앱 워크트리 파일, 세션 데이터, 인증 자격증명이 모두 ~/.codex/에 뒤섞여 명확한 구분 없이 쌓입니다. “내 것”과 “프로젝트 것”의 경계가 필요 이상으로 흐릿합니다.

설정 우선순위는 특정 순서를 따릅니다. 관리형 설정이 세션 오버라이드보다 우선하고, 세션 오버라이드가 사용자 설정보다 우선합니다. 설정이 적용되지 않을 때는 어느 레벨을 편집하고 있는지 확인하는 것이 첫 번째 점검 사항입니다.

신뢰 수준이 진짜 관문입니다

대부분의 사람들이 여기서 막히고, 저도 이 이유를 이해하기 전까지 실제로 많은 시간을 낭비했습니다.

Codex는 신뢰하지 않는 저장소의 프로젝트 .codex/를 로드하지 않습니다. 전혀 로드하지 않습니다. 새로 클론한 저장소에서 config.toml을 아무리 편집해도 아무것도 적용되지 않습니다. 파일은 거기 있고, 문법도 맞는데, Codex는 이 모든 것을 조용히 무시합니다.

이유를 알고 나면 납득이 됩니다. .agents/는 외부 스킬이 사용자 환경으로 흘러들어오는 경로를 열어둡니다. 어떤 저장소든 악의적인 설정을 심을 수 있습니다. 그래서 Codex는 이런 트레이드오프를 선택했습니다. 에이전트 생태계와의 호환성을 넓히는 대신, 저장소가 제공하는 설정에 대해서는 더 엄격한 신뢰 검증을 요구합니다. 프로젝트의 .codex/ 설정이 활성화되려면 해당 프로젝트를 명시적으로 신뢰 대상으로 표시해야 합니다.

사용자 설정에서 projects.<path>.trust_level = "trusted"를 설정하면 됩니다. 네트워크 접근도 기본적으로 차단되어 있으며, 웹 검색은 캐시, 실시간, 비활성화 세 가지 모드를 지원합니다. workspace-write 모드에서도 .git/과 .codex/는 쓰기 보호 상태를 유지합니다.

저는 신뢰 수준을 설정하지 않은 채로 프로젝트 config.toml을 약 한 시간 동안 편집했고, 그 설정은 완전히 무시되고 있었습니다. 오류 메시지도 없고, 경고도 없었습니다. 그냥 조용했습니다. 이것이 아마도 Codex 설정에서 가장 흔한 불만의 원인일 것이며, 여기서 더 나은 오류 메시지가 제공된다면 많은 사람의 시간을 절약할 수 있을 것입니다.

복잡성은 우연이 아닙니다

폴더 구조는 복잡하지만, 무작위로 복잡한 것은 아닙니다. Codex는 서로 반대 방향으로 당기는 두 가지 목표를 동시에 추구하고 있습니다.

빠른 베타 반복은 .codex/에 설정 파일, 규칙 정의, 훅, 앱 관리 아티팩트가 문서화 속도를 앞질러 쌓이도록 만듭니다. 크로스 에이전트 호환성은 .agents/에 스킬과 마켓플레이스 콘텐츠를 위한 별도의 이식 가능한 구조를 요구합니다. 그리고 .agents/가 외부 코드에 문을 열기 때문에, 신뢰 검증 레이어가 반드시 존재해야 합니다.

파일을 어디에 두어야 할지 확신이 서지 않을 때는 한 가지 질문을 던져보면 됩니다. 이것이 Codex 전용인가, 아니면 다른 에이전트도 읽어야 하는가? 첫 번째 답이라면 .codex/가 맞고, 두 번째 답이라면 .agents/가 맞습니다.

설정이 작동하지 않을 때는 파일 내용을 편집하는 것부터 시작하지 마십시오. 파일이 올바른 폴더에 있는지, 저장소가 신뢰 대상으로 설정되어 있는지를 먼저 확인하십시오. 문제는 거의 항상 거기에 있습니다.