덕삼
블로그

Codex 실전 가이드 3편 — config.toml·프로필·컨텍스트

Codex 실전 가이드 3편입니다. 1편은 AGENTS.md, 2편은 샌드박스와 승인 정책을 다뤘습니다. 이번 편은 설정 파일과 컨텍스트입니다. Claude Code 가이드 2편은 “컨텍스트는 유한한 자원"이라는 전제로 시작했습니다. 이번 편은 그 자원이 Codex 에서 처음부터 얼마나 쓰인 채로 시작하는지 잽니다.

이번 편이 답하는 질문은 이것입니다. 세션을 열자마자 Codex 의 컨텍스트에는 무엇이 얼마나 들어 있고, 그것을 바꾸는 설정은 어디에 있나. 답부터 말하면 제 맥의 한 저장소에서 첫 질문 전에 이미 글자 약 7만 자가 들어 있었습니다. 도구 정의는 따로 약 3만 2천 자였습니다. 가장 크게 조절할 수 있는 항목은 스킬 목록입니다. 설정은 ~/.codex/config.toml 이 바탕이고, 그 위에 프로필·프로젝트 설정·명령줄 옵션이 차례로 덮습니다.

설정은 한 파일에서 시작해 위로 겹칩니다

공식 문서가 밝힌 우선순위는 높은 것부터 이렇습니다.

  1. 명령줄 옵션과 -c/--config
  2. 프로젝트의 .codex/config.toml (신뢰한 프로젝트만)
  3. 프로필 파일
  4. 사용자 설정 ~/.codex/config.toml
  5. 클라우드에서 관리하는 기본값
  6. /etc/codex/config.toml
  7. 내장 기본값

일상에서 가장 자주 쓰는 것은 -c 입니다. 점으로 이은 경로에 값을 줍니다. 값은 TOML 로 해석하고, 해석에 실패하면 문자열로 씁니다.

codex -c model_reasoning_effort="low" "README 오탈자만 고쳐줘"
codex --enable hooks        # -c features.hooks=true 와 같다
codex --strict-config       # 모르는 키가 있으면 오류로 멈춘다

--strict-config 는 기억해 둘 만합니다. 기본 동작에서는 철자가 틀린 키가 조용히 무시될 수 있습니다. 0.160.0 에서 -c 'projects."<경로>".trust_level=...' 로 넘긴 신뢰 설정이 무시된 적이 있습니다. 그 설정은 “unrecognized configuration” 으로 처리됐습니다. 같은 값을 인라인 표(-c 'projects={"<경로>"={trust_level="trusted"}}')로 넘기자 비로소 적용됐습니다.

기능 스위치는 codex features list 로 봅니다. 0.169.0 에는 215개가 있었습니다(2026-11-18). stable 이 68개, under development 가 90개입니다. 나머지는 removed 48개, experimental 5개, deprecated 4개였습니다. 문서보다 이 목록이 먼저 바뀌니, 글에서 본 기능이 내 버전에서 켜져 있는지는 여기서 확인합니다.

프로필은 이제 별도 파일입니다

-p, --profile <이름> 은 $CODEX_HOME/<이름>.config.toml 을 사용자 설정 위에 얹습니다. 공식 문서는 0.134.0 부터 config.toml 안의 [profiles.<이름>] 표를 읽지 않는다고 적습니다.

제 config.toml 에도 그 옛 형식 표가 하나 남아 있었습니다. 지금 버전에서는 아무 일도 하지 않는 설정입니다. 실제로 쓰는 프로필은 같은 폴더의 별도 파일 세 개입니다. 하나는 사내 GPU 추론 서버, 하나는 상용 API 를 가리킵니다. 모양은 이렇습니다.

# ~/.codex/my-server.config.toml
model_provider = "my-server"
model = "서버가 서빙하는 모델 이름"

[model_providers.my-server]
name = "self-hosted"
base_url = "https://<추론 서버>/v1"
env_key = "MY_SERVER_API_KEY"   # 키 값이 아니라 키를 담은 환경변수 이름
wire_api = "responses"

codex -p my-server 로 열면 이 서버의 모델로 세션이 시작됩니다. 키는 파일에 적지 않고 env_key 가 가리키는 환경변수에서 읽습니다. 로컬 모델을 바로 붙이는 --oss 와 --local-provider lmstudio|ollama 옵션도 있습니다.

셀프호스팅 서버를 붙일 때 한 번 걸린 일이 있습니다. Codex 는 wire_api = "responses" 로 Responses API 를 부릅니다. 제가 쓰는 추론 엔진은 어느 버전부터 /v1/responses 에서 별칭 모델 이름을 404 로 돌려보냈습니다. 같은 별칭이 chat completions 경로에서는 그대로 통했습니다. 그래서 다른 클라이언트는 멀쩡한데 Codex 만 실패했습니다. 프로필의 model 에는 별칭이 아니라 서버가 실제로 서빙하는 이름을 적어야 합니다.

첫 질문 전에 이미 7만 자가 들어 있습니다

1편에서 쓴 codex debug prompt-input 은 컨텍스트 계량기로도 쓸 수 있습니다. 출력 JSON 의 항목별 글자 수를 세면 됩니다. 신뢰한 저장소 하나에서 잰 결과입니다(2026-11-18).

항목글자 수
기본 지시문21,524
스킬 목록(스킬 65개)22,073
저장소 AGENTS.md9,756
권한 안내문(승인한 규칙 목록 포함)9,270
서브에이전트 안내2,671
도구·플러그인·협업 모드 안내3,846
환경 정보1,149
합계70,289

도구 정의(JSON) 32,266자는 이 표와 별도입니다. 글자 수는 토큰 수가 아니고, 토큰으로 바꾼 값은 확인하지 못했습니다. 그래도 비율은 읽을 수 있습니다.

해석은 이렇습니다. 기본 지시문은 버전이 정하니 사용자가 줄일 수 없습니다. 사용자가 손댈 수 있는 가장 큰 항목은 스킬 목록입니다. 스킬마다 이름과 설명이 매 세션 들어가므로, 쓰지 않는 스킬을 지우거나 설명을 줄이면 바로 줄어듭니다. 2편에서 본 승인 규칙 목록과 1편의 AGENTS.md 가 그다음입니다. 이 해석은 같은 측정을 다른 저장소에서 했을 때 스킬 목록이 가장 크다는 조건에서만 맞습니다. 스킬을 거의 깔지 않았다면 AGENTS.md 가 가장 큰 항목이 됩니다.

긴 세션은 줄이고, 끊긴 세션은 잇습니다

Claude Code 의 /clear·/compact 에 해당하는 명령이 Codex 에도 있습니다. 공식 문서의 CLI 슬래시 명령 목록 기준입니다.

명령하는 일
/compact보이는 대화를 요약해 토큰을 비운다
/new새 대화를 시작한다
/clear터미널을 지우고 새 대화를 시작한다
/resume·/fork지난 대화를 잇거나 갈라 낸다

자동 압축 시점은 model_auto_compact_token_limit 로 정합니다. 비워 두면 모델 기본값을 씁니다(공식 문서 기준). Claude Code 가이드 2편의 기준은 Codex 에도 그대로 씁니다. 이슈 하나가 끝나면 새 대화를 열고, 같은 작업이 길어지면 압축합니다.

셸에서 세션을 다루는 하위 명령은 0.169.0 도움말로 확인했습니다. codex resume 은 목록에서 고르고, --last 를 주면 가장 최근 세션을 잇습니다. codex fork 는 지난 세션을 갈라 새 세션을 만듭니다. codex archive·unarchive·delete 는 저장된 세션을 정리합니다. 무인 실행 쪽에는 codex exec resume --last 가 있습니다.

영속 메모리는 공식 문서 기준으로 기본이 꺼져 있습니다. 켜면 $CODEX_HOME/memories/ 아래에 저장합니다. 제 맥의 codex features list 에서도 memories 는 stable 이면서 꺼져 있었습니다. 메모리는 저장소별이 아니라 Codex 홈 하나에 쌓입니다. 그래서 프로젝트 사실은 메모리보다 AGENTS.md 에 두는 편이 맞습니다.

Claude Code 와 다른 점 — 형식보다 범위가 다릅니다

항목Claude CodeCodex 0.169.0
설정 파일settings.json(JSON)config.toml(TOML)
저장소 설정.claude/settings.json.codex/config.toml, 신뢰한 프로젝트만
영속 메모리프로젝트별 자동 메모리홈 전역 memories/, 기본 꺼짐
대화 정리/clear, /compact/new·/clear, /compact

실무에서 가장 크게 느끼는 차이는 저장소 설정의 조건입니다. Codex 는 저장소 설정을 신뢰와 묶었습니다. 신뢰하지 않은 저장소의 .codex/config.toml 은 건너뜁니다. 남이 만든 저장소를 열어도 그 저장소의 설정이 내 세션을 바꾸지 못합니다. 한 번에 한 값만 바꾸는 -c 도 자주 씁니다. 실험할 때 설정 파일을 고쳤다 되돌리는 일이 줄었습니다.

실사례 — 같은 저장소, 다른 모델로 두 번

제 환경에서는 같은 작업을 상용 모델과 사내 GPU 서버의 오픈 모델로 번갈아 돌려 봅니다. 프로필 파일이 이 비교를 단순하게 만듭니다. 기본 세션은 config.toml 의 모델로 열고, 비교할 때만 codex -p <서버 프로필> 로 엽니다. 저장소·AGENTS.md·스킬은 그대로이고 모델 공급자만 바뀝니다.

이 방식에서 지킨 규칙은 두 가지입니다. 첫째, 프로필 파일에는 공급자와 모델만 둡니다. 샌드박스나 승인 정책까지 프로필마다 다르면 결과 차이가 모델 때문인지 권한 때문인지 가릴 수 없습니다. 둘째, 프로필을 처음 만들면 prompt-input 으로 모델 이름과 컨텍스트를 한 번 확인합니다. 옛 [profiles] 표처럼 조용히 무시되는 설정이 있었기 때문입니다.

비교 결과를 읽을 때도 조심할 점이 있었습니다. 2026-08-31~09-01 에 사내 서버의 오픈 모델로 Go 코딩 문제를 풀게 했습니다. Codex 는 2회 중 2회 통과했고, 같은 모델에 붙인 다른 CLI 중에는 한 번도 통과하지 못한 것이 있었습니다. 그런데 원인을 따라가 보니 CLI 실력보다 그 모델의 도구 호출 출력이 불안정한 탓이 컸습니다. 2026-09-10 에 모델과 도구 호출 파서를 바꾸자 같은 문제를 여섯 CLI 가 모두 통과했습니다. 표본이 CLI 당 몇 회뿐이라 순위로 읽을 결과는 아닙니다. 하네스를 비교하기 전에 모델 쪽 변수부터 고정해야 한다는 교훈만 남겼습니다.

정리

세션을 열면 첫 질문 전에 글자 약 7만 자가 이미 들어 있습니다(제 저장소 기준). 가장 큰 조절 대상은 스킬 목록이고, 그다음이 승인 규칙과 AGENTS.md 입니다. 설정은 config.toml 이 바탕이고 프로필 파일·신뢰한 프로젝트 설정·-c 가 차례로 덮습니다.

다음에 확인할 것은 하나입니다. 자기 저장소에서 prompt-input 의 스킬 목록 크기를 재 보는 것입니다. 4편에서는 그 스킬과 서브에이전트, 훅을 다룹니다.