Codex에서 GPT-5.6 Luna를 서브에이전트로 연결하고 실제 실행까지 확인하는 방법
Codex에서 GPT-5.6 Luna를 서브에이전트로 사용하려면 단순히 모델 이름을 요청하는 것만으로는 부족합니다. Codex가 Luna를 멀티 에이전트용 모델로 인식하도록 로컬 모델 카탈로그를 연결하고, 기능을 활성화한 뒤 새 작업에서 실제 자식 세션을 확인해야 합니다.
아래 내용은 2026년 8월 1일 기준으로 실행을 확인한 구성을 바탕으로 정리한 것입니다. 당시 메인 모델은 gpt-5.6-sol, 서브에이전트는 gpt-5.6-luna였으며, 데스크톱 Codex는 0.146.0-alpha.9.2, 터미널 Codex는 0.146.0이었습니다. Codex 업데이트에 따라 파일 구조나 지원 방식은 달라질 수 있습니다.
| 구성 요소 | 확인한 값 |
|---|---|
| 메인 모델 | gpt-5.6-sol |
| 서브에이전트 | gpt-5.6-luna |
| 데스크톱 Codex | 0.146.0-alpha.9.2 |
| 터미널 Codex | 0.146.0 |
| 확인 시점 | 2026년 8월 1일 |
먼저 Codex 설정 디렉터리를 확인한다
macOS와 Linux의 Bash 또는 Zsh에서는 다음처럼 Codex 데이터 디렉터리를 변수로 지정합니다.
export CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
printf 'Codex directory: %s\n' "$CODEX_DIR"CODEX_HOME을 별도로 지정했다면 해당 경로가 사용되고, 그렇지 않으면 기본적으로 $HOME/.codex를 가리킵니다. 터미널을 새로 열었다면 변수 설정도 다시 해야 합니다. Windows는 PowerShell의 환경 변수와 경로 표기법에 맞게 별도로 바꿔야 합니다.
이번 설정에서 사용하는 파일은 config.toml, 원본 모델 목록인 models_cache.json, 그리고 이를 복사해 만든 models-luna-v2.json입니다. 원본 캐시를 직접 수정하지 않는 이유는 Codex 업데이트 과정에서 덮어쓰이거나 복구가 어려워질 수 있기 때문입니다.
현재 설정과 Luna 모델 정보를 점검한다
먼저 설정 파일에 모델 카탈로그와 멀티 에이전트 기능이 연결되어 있는지 확인합니다.
grep -nE 'model_catalog_json|multi_agent' "$CODEX_DIR/config.toml"
jq '.models[] | select(.slug == "gpt-5.6-luna") | {slug, multi_agent_version, supported_reasoning_levels}' \
"$CODEX_DIR/models-luna-v2.json"정상 구성이라면 config.toml에는 절대경로를 사용하는 model_catalog_json이 있고, 기능 설정에는 multi_agent = true가 있어야 합니다. Luna 항목은 multi_agent_version이 v2로 표시되어야 합니다.
파일이 없거나 Luna 항목이 보이지 않는다면 다른 모델을 임의로 Luna로 바꾸면 안 됩니다. 먼저 현재 Codex 버전의 models_cache.json에 해당 모델이 실제로 제공되는지 확인해야 합니다.
원본 카탈로그를 복사해 Luna V2로 만든다
변경 전에는 원본 파일과 설정을 백업하는 편이 안전합니다.
mkdir -p "$CODEX_DIR/backups/luna-v2-setup"
cp "$CODEX_DIR/models_cache.json" "$CODEX_DIR/backups/luna-v2-setup/models_cache.json"
cp "$CODEX_DIR/config.toml" "$CODEX_DIR/backups/luna-v2-setup/config.toml"
cp "$CODEX_DIR/models_cache.json" "$CODEX_DIR/models-luna-v2.json"그다음 Python으로 정확히 gpt-5.6-luna 항목 하나만 찾아 multi_agent_version을 v2로 변경합니다. 이때 일치 항목이 1개가 아니면 중단하도록 만드는 것이 중요합니다. 모델 항목이 없는데 비슷한 이름을 추정해 수정하면 Codex의 모델 검증 단계에서 더 큰 문제가 생길 수 있습니다.
python3 - <<'PY'
import json, os
from pathlib import Path
p = Path(os.environ["CODEX_DIR"]).expanduser().resolve() / "models-luna-v2.json"
data = json.loads(p.read_text(encoding="utf-8"))
items = [m for m in data.get("models", []) if m.get("slug") == "gpt-5.6-luna"]
if len(items) != 1:
raise SystemExit(f"Luna 항목 수가 올바르지 않습니다: {len(items)}")
items[0]["multi_agent_version"] = "v2"
tmp = p.with_suffix(".json.tmp")
tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
tmp.replace(p)
print("gpt-5.6-luna multi_agent_version=v2 설정 완료")
PYconfig.toml에서 카탈로그와 기능을 연결한다
model_catalog_json은 TOML의 최상위 영역, 즉 첫 번째 섹션이 시작되기 전에 배치해야 합니다. 셸 변수가 TOML 안에서 자동으로 확장되지는 않으므로 절대경로를 직접 넣어야 합니다.
model = "gpt-5.6-sol"
model_catalog_json = "/absolute/path/to/codex-home/models-luna-v2.json"기존 [features] 섹션이 있다면 그 안에 다음 항목을 추가합니다.
[features]
multi_agent = true이미 [features]가 있는데 새 섹션을 또 만들거나, 같은 키를 두 번 선언하면 TOML 파싱 오류가 발생할 수 있습니다. 설정 후에는 다음 명령으로 문법 오류를 확인합니다.
codex doctor --summarymodel_catalog_json을 [features]나 [projects] 아래에 넣는 것도 잘못된 배치입니다. 메인 모델을 Sol로 유지하려면 model = "gpt-5.6-sol"을 그대로 둡니다.
앱을 완전히 다시 시작하고 Luna를 명시한다
Codex는 실행 시점에 모델 카탈로그와 도구 스키마를 읽어 들일 수 있습니다. 따라서 파일만 수정하고 열린 작업에서 바로 확인하면 Luna가 나타나지 않을 수 있습니다. 진행 중인 작업을 정리한 뒤 데스크톱 앱을 정상 종료하고, 별도로 실행 중인 터미널 Codex 프로세스도 종료한 다음 다시 실행합니다. 검증은 기존 대화가 아닌 새 작업에서 해야 합니다.
서브에이전트를 만들 때는 모델과 추론 수준을 명시하는 것이 핵심입니다.
model: gpt-5.6-luna
reasoning_effort: max
fork_turns: noneLuna에서 사용할 수 있는 추론 수준은 low, medium, high, xhigh, max입니다. ultra는 검증 단계에서 거부될 수 있습니다. 또한 전체 대화 기록을 그대로 상속하는 방식은 부모의 모델과 추론 설정을 물려받을 수 있으므로, Luna를 강제하려면 fork_turns: none 또는 제한된 턴 수를 사용해야 합니다.
말이 아닌 세션 기록으로 실행을 검증한다
새 작업에서 다음과 같이 요청할 수 있습니다.
gpt-5.6-luna, reasoning max로 읽기 전용 서브에이전트 한 개를 생성해 줘.
다른 도구는 사용하지 말고 LUNA_SUBAGENT_OK만 반환해 줘.
자식 세션의 실제 model과 reasoning_effort도 확인해 줘.성공 여부는 세 가지를 모두 확인해야 합니다. 자식 생성 요청이 모델 검증에서 거부되지 않아야 하고, 자식이 LUNA_SUBAGENT_OK를 반환해야 하며, 자식 rollout의 turn_context에 Luna와 max가 기록되어야 합니다.
grep -R -l '"model":"gpt-5.6-luna"' "$CODEX_DIR/sessions" | tail -n 5찾은 JSONL rollout 파일에서 다음처럼 확인합니다.
jq -c 'select(.type == "turn_context") | {model: .payload.model, reasoning_effort: .payload.collaboration_mode.settings.reasoning_effort}' /절대/경로/rollout-파일.jsonl결과가 gpt-5.6-luna와 max로 나와야 합니다. 에이전트가 대화 중 자기 모델을 Luna라고 말하는 것만으로는 실제 실행 증거가 되지 않습니다.
자주 발생하는 오류와 원상 복구
Luna가 허용 모델 목록에 없으면 카탈로그 경로, Luna 항목 존재 여부, multi_agent_version = v2, multi_agent = true, 앱 재시작 여부를 차례로 확인합니다. Luna를 지정했는데 Sol이 실행되면 생성 요청에서 model을 생략했거나 전체 대화를 상속했을 가능성이 큽니다.
업데이트 뒤에는 먼저 공식 캐시를 확인합니다.
jq '.models[] | select(.slug == "gpt-5.6-luna") | {slug, multi_agent_version, supported_reasoning_levels}' "$CODEX_DIR/models_cache.json"공식 값이 이미 v2라면 별도 오버라이드가 필요 없을 수 있습니다. Luna 항목 자체가 사라졌다면 임의로 모델 정의를 만들지 말고, 현재 Codex 버전에서 지원되는지 확인해야 합니다.
설정을 되돌릴 때는 앱을 종료한 뒤 config.toml의 model_catalog_json 줄을 삭제하고 다시 시작하면 됩니다. 백업본으로 복원할 경우 다음 명령을 사용할 수 있습니다.
cp "$CODEX_DIR/backups/luna-v2-setup/config.toml" "$CODEX_DIR/config.toml"
codex doctor --summary이 설정은 공식 기능이라기보다 로컬 모델 카탈로그 오버라이드에 가깝습니다. 따라서 업데이트 후에는 Luna가 화면에 보이는지만 확인하지 말고, 새 자식 세션의 turn_context까지 검증해야 실제로 원하는 모델이 실행됐는지 판단할 수 있습니다.
