Codex 환경 변수 사용법: CODEX_HOME과 config.toml로 자동화 상태를 분리하기 | DAKER 커뮤니티
Codex 환경 변수는 한 번 실행할 작업의 위치, 인증, 로그, 진단 범위를 셸에서 임시로 바꾸는 설정입니다. 반복 자동화를 돌릴 때는 CODEX_HOME과 config.toml을 나눠야 상태가 섞이지 않고, 2026년 7월 5일 기준 공식 문서의 설정 우선순위를 그대로 검증할 수 있습니다.
DAKER 코덱스 Codex 환경 변수 사용법 대표 이미지: 개인 기본값, 프로젝트 설정, 자동화 셸 변수를 분리하는 흐름.
한 줄 요약: 매일 도는 Codex 자동화는 개인 기본값은 config.toml에 두고, 실행마다 바뀌는 상태 위치와 로그 경계는 환경 변수로 분리하는 편이 안전합니다.
문제 상황: Codex 자동화 상태가 왜 자꾸 섞일까요?
Codex를 로컬 대화형 도구로만 쓸 때는 기본 설정 하나로도 충분합니다. 하지만 매일 실행되는 자동화, CI 보조 스크립트, 여러 프로젝트의 반복 점검을 같은 계정과 같은 홈 디렉터리에서 돌리면 문제가 생깁니다. 어느 실행의 세션, 로그, 인증 상태, 스킬, MCP 설정을 보고 있는지 흐려지고, 디버깅할 때도 “이번 실행만의 증거”를 분리하기 어려워집니다.
공식 Codex 문서는 개인 기본 설정은 ~/.codex/config.toml에 두고, 프로젝트별 설정은 신뢰한 프로젝트의 .codex/config.toml에서 읽는다고 설명합니다. 동시에 환경 변수 문서는 Codex가 durable setting에는 config.toml을 쓰고, 셸 범위의 override, 자동화 secret, 설치 동작, diagnostics에는 환경 변수를 쓰라고 구분합니다. 이 구분이 오늘 글의 핵심입니다.
이미 권한 경계를 먼저 잡고 있다면 https://daker.ai/community/codex-tool-usage-25-secure-workspace-permission-pr 글과 함께 보세요. 명령 승인 기준을 파일로 고정하는 흐름은 https://daker.ai/community/codex-tool-24-rules-command-approval-file 글과 이어집니다.
핵심 개념: CODEX_HOME과 config.toml은 무엇이 다른가요?
CODEX_HOME은 Codex 상태의 루트 위치를 바꾸는 환경 변수입니다. config.toml은 모델, 승인 정책, 샌드박스, MCP 서버 같은 지속 설정을 담는 파일입니다. 둘은 경쟁 관계가 아니라 역할이 다릅니다.
구분 | 어디에 두나요? | 좋은 용도 | 주의할 점 |
|---|---|---|---|
~/.codex/config.toml | 사용자 홈 | 개인 기본 모델, 승인 정책, MCP 기본값 | 모든 프로젝트에 영향을 줄 수 있음 |
.codex/config.toml | 프로젝트 안 | 저장소별 기본값, 팀 작업 경계 | 신뢰한 프로젝트에서만 로드됨 |
CODEX_HOME | 셸 환경 변수 | 자동화별 상태, 로그, 세션 분리 | 지정한 디렉터리가 이미 있어야 함 |
CODEX_SQLITE_HOME | 셸 환경 변수 | SQLite 기반 상태 위치 분리 | sqlite_home config가 우선할 수 있음 |
codex -c key=value | 명령 인자 | 한 번 실행의 임시 override | TOML quoting을 잘못 쓰면 의도와 달라짐 |
2026년 7월 5일 기준 공식 Configuration Reference는 프로젝트 .codex/config.toml이 일부 machine-local provider, auth, profile, notification, telemetry routing 키를 덮어쓸 수 없다고 설명합니다. 즉 팀 저장소에 모든 것을 넣으려 하기보다, 사용자·프로젝트·실행 단위의 경계를 나눠야 합니다.
DAKER 코덱스 Codex 환경 변수 체크리스트 이미지: 디렉터리 생성, secret 로그 금지, auth 덮어쓰기 금지.
단계별 사용법: 자동화용 CODEX_HOME은 어떻게 나누면 좋을까요?
먼저 자동화 이름을 하나 정합니다. 예를 들어 codex-nightly-review, codex-daker-publisher처럼 사람이 봐도 목적을 알 수 있는 이름이 좋습니다.
자동화 전용 디렉터리를 만듭니다. 예: ~/.codex-automations/codex-nightly-review.
해당 디렉터리에 필요한 config.toml, auth 상태, 로그, 세션이 쌓일 수 있는지 확인합니다.
자동화 실행 스크립트에서 CODEX_HOME을 그 디렉터리로 지정합니다.
프로젝트별 규칙은 저장소의 .codex/config.toml 또는 AGENTS.md에 두고, 개인 인증과 provider 설정은 사용자 레벨에 둡니다.
한 번만 바꿀 값은 codex -c key=value 또는 CLI flag로 넘깁니다.
실행 후 로그와 세션을 자동화 디렉터리에서만 확인합니다.
실무 기준은 간단합니다. “계속 유지할 기본값”은 config.toml, “이번 실행만 바뀌는 경계”는 환경 변수, “이번 명령만 바뀌는 값”은 CLI flag나 -c override로 둡니다.
짧은 예시: 매일 점검 자동화는 어떻게 실행하면 좋을까요?
아래 예시는 공개 본문용으로 단순화한 형태입니다. 실제 팀에서는 경로, 승인 정책, 로그 보관 기간, secret 주입 방식을 조직 기준에 맞춰 조정해야 합니다.
mkdir -p ~/.codex-automations/daily-check
CODEX_HOME=~/.codex-automations/daily-check \
codex exec "오늘 실패한 테스트와 변경 위험을 요약해줘"이 방식의 장점은 실행 흔적이 개인 대화형 Codex 상태와 섞이지 않는다는 점입니다. 실패가 나도 daily-check 전용 상태만 보면 되고, 다른 프로젝트의 세션이나 로그를 착각할 가능성이 줄어듭니다.
CI나 스크립트에서 결과 형식을 함께 고정하고 싶다면 https://daker.ai/community/codex-exec-usage-automate-ci-jsonl-schema 글을 먼저 읽어보세요. 사내 도구에서 Codex 실행을 버튼으로 묶는 구조가 필요하다면 https://daker.ai/community/codex-sdk-typescript-internal-tool-integration 글이 더 가깝습니다.
실수 방지 체크리스트: 환경 변수로 무엇까지 바꾸면 위험할까요?
CODEX_HOME 디렉터리를 만들지 않고 실행하지 않습니다.
개인 기본 설정과 자동화 전용 설정을 같은 config.toml에 계속 섞지 않습니다.
project .codex/config.toml이 auth, provider, telemetry 같은 machine-local 키까지 덮어쓴다고 가정하지 않습니다.
secret 값은 글 본문, 이슈, PR 댓글, 로그에 붙이지 않습니다.
자동화마다 로그 보관 위치와 삭제 기준을 정합니다.
risky flag나 approval_policy 변경은 실행 목적과 외부 격리 환경을 함께 확인합니다.
공식 CLI reference에서 deprecated 옵션이나 risky combination 표시를 다시 확인합니다.
2026년 7월 1일 Codex CLI 0.142.5처럼 trace log 관련 패치가 나온 경우, 로그에 무엇이 남는지 업데이트 후 재점검합니다.
공식 출처: 이 글은 무엇을 기준으로 작성했나요?
이 글은 2026년 7월 5일 KST 기준 OpenAI Developers의 Codex Environment variables, Config basics, Configuration Reference, Codex CLI command line options, Codex changelog 공개 문서를 확인해 작성했습니다. DAKER 공개 본문 정책상 외부 OpenAI URL은 본문에 직접 노출하지 않고, 브라우저에서 확인한 DAKER 내부 글만 연결했습니다.
확인된 한계도 있습니다. Codex의 환경 변수 목록과 CLI 옵션은 버전별로 바뀔 수 있고, 조직 관리형 요구사항이 있는 장비에서는 requirements.toml이나 관리자 정책이 개인 설정보다 강하게 적용될 수 있습니다. 실제 운영 전에는 현재 설치된 Codex 버전, 조직 정책, 실행 로그 보관 기준을 함께 확인해야 합니다.
FAQ: Codex 환경 변수 사용자가 자주 묻는 질문
CODEX_HOME은 언제 바꾸는 게 좋나요?
자동화, CI 보조 스크립트, 실험용 Codex 실행처럼 상태와 로그를 개인 기본 Codex 사용과 분리하고 싶을 때 바꾸는 것이 좋습니다.
config.toml 대신 환경 변수만 써도 되나요?
권장하지 않습니다. 반복되는 기본 모델, 승인 정책, MCP 설정은 config.toml에 두고, 실행마다 달라지는 위치와 진단 범위만 환경 변수로 넘기는 편이 관리하기 쉽습니다.
프로젝트 .codex/config.toml에 모든 설정을 넣어도 되나요?
아닙니다. 공식 문서 기준 일부 provider, auth, profile, notification, telemetry routing 관련 키는 프로젝트 로컬 설정이 덮어쓸 수 없습니다. 팀 규칙과 프로젝트 기본값 중심으로만 두는 편이 안전합니다.
codex -c key=value는 언제 쓰나요?
한 번의 실행에서만 설정을 바꿀 때 씁니다. 예를 들어 특정 테스트 실행에서만 모델이나 sandbox 관련 값을 조정해야 할 때 유용하지만, 자주 쓰는 값은 config.toml로 옮기는 편이 낫습니다.
로그 보안은 왜 따로 봐야 하나요?
Codex 자동화는 명령, 출력, 도구 호출 근거를 남길 수 있습니다. 2026년 7월 1일 Codex CLI 0.142.5 changelog도 trace log 관련 패치를 언급하므로, 자동화 디렉터리와 로그 보관 기준을 분리해 두는 것이 좋습니다.
오늘 자동화를 하나 운영하고 있다면, 먼저 그 자동화만의 CODEX_HOME 디렉터리와 “config.toml에 남길 값, 환경 변수로 넘길 값, CLI flag로만 바꿀 값” 세 줄을 적어보세요.