설정 우선순위와 진단

Codex 학습 목차로 돌아가기

목표와 준비

검사기는 이 강의의 web_search만 다루며 Codex 전체 schema가 아닙니다. 다른 설정이나 네트워크를 사용하지 않습니다. 통과는 해당 파일 문법/키 확인이지 로드/조직 허가/다른 도구 동작을 보장하지 않습니다. 성공의 범위를 명확히 합니다.

1단계: 오프라인 예시와 검사기 만들기

codex-config-checks의 check_config.py에 다음 전체 코드를 저장합니다. 지정 파일만 열고 문법 위치나 대상 키만 표시하며 설정 전체는 출력하지 않습니다. 화면 증거에는 독립 예시를 쓰고 인증 정보가 있는 실제 파일을 넘기지 않습니다.

from pathlib import Path
import sys
import tomllib

if len(sys.argv) != 2:
    raise SystemExit("Usage: check_config.py SAMPLE.toml")
path = Path(sys.argv[1])
try:
    with path.open("rb") as stream:
        data = tomllib.load(stream)
except (OSError, tomllib.TOMLDecodeError) as exc:
    print(f"FAIL: {exc}")
    raise SystemExit(1)
if "web_search" not in data:
    print("FAIL: missing top-level web_search; inspect table placement")
    raise SystemExit(1)
value = data["web_search"]
if not isinstance(value, str) or value not in {"disabled", "cached", "indexed", "live"}:
    print("FAIL: unsupported web_search value for this exercise")
    raise SystemExit(1)
print(f"PASS: sample syntax and web_search={value}; Codex loading is not verified")

먼저 good.toml로 Python/검사기가 동작하는 정상 기준을 확인합니다. 처음부터 오류 예시를 쓰면 도구 문제와 의도된 실패를 구분할 수 없습니다. 두 파일을 UTF-8과 올바른 확장자로 저장합니다.

web_search = "disabled"

실습 폴더에서 Windows는 첫째 줄, macOS/Linux는 둘째 줄을 실행합니다. PASS와 로드 미검증 표시가 예상됩니다. No module named tomllib이면 Python을 확인합니다. 3.11에 추가된 표준 기능이며 Codex 플러그인 누락이 아닙니다.

py -3 check_config.py good.toml

python3 check_config.py good.toml

종료 코드로 이번 결과 확인하기

실행 직후 같은 터미널에서 종료 코드를 확인하세요. Windows PowerShell은 $LASTEXITCODE, macOS/Linux는 echo $?를 사용합니다. 중간에 다른 프로그램을 실행하지 마세요. good.toml은 0, 수정 전 오류 네 개는 각각 1이 예상됩니다. fixed-quote.toml, fixed-duplicate.toml, fixed-scope.toml, fixed-value.toml로 따로 저장해 고치면 각각 0이어야 하며 원본 오류 파일은 보존합니다.

2단계: 서로 다른 실패 네 가지 진단

broken-quote.toml은 닫는 따옴표가 없어 문법 실패합니다. 명령 끝 파일명을 바꿉니다. 위치가 줄 끝이나 다음 문자를 가리킬 수 있으므로 해당 줄을 거슬러 보고 일반 따옴표를 보완해 재실행합니다. 원본/수정본을 남겨 비교합니다.

web_search = "disabled

broken-duplicate.toml은 같은 최상위 키를 두 번 정의합니다. 마지막 줄이 이기는 방식이 아니라 오류입니다. disabled를 남기고 중복 줄을 제거해 재확인합니다. 파일 간 우선순위와 한 파일 내부 중복은 별개입니다.

web_search = "disabled"
web_search = "live"

broken-scope.toml은 TOML 문법은 맞아도 features 안의 다른 키 경로입니다. 검사기는 최상위 누락을 표시합니다. Codex도 위치/형식 때문에 거부할 수 있으므로 파싱 성공만으로 지원 설정이라 하지 않습니다. 키를 테이블 헤더 앞으로 옮기고 실험용 features는 남기지 않습니다.

[features]
web_search = "disabled"

broken-value.toml의 off는 문자열로는 맞아도 지원 web_search 값이 아닙니다. disabled로 고쳐 재확인하며 다른 소프트웨어의 on/off에 맞춰 번역하지 않습니다. 모델/추론은 계정과 버전을 별도로 확인하며 이 좁은 검사기로 검증하지 않습니다.

web_search = "off"

PASS가 확인하지 않은 것

검사기의 경계 사례입니다. 아래도 web_search 조건을 만족하고 extra_practice_key는 검사하지 않으므로 PASS가 나옵니다. .codex 밖에 limits.toml로 저장해 오프라인 검사에만 사용하세요. Codex가 추가 키를 허용하거나 전체 스키마 검증을 통과한다는 뜻은 아닙니다. 검사하지 않은 부분을 기록하세요.

web_search = "disabled"
extra_practice_key = "not checked by this exercise"

3단계: 문법은 맞지만 효과가 없을 때

설정 기초의 실제 실습으로 돌아가며 오류 예시는 시작 설정에 넣지 않습니다. 새 CLI의 /debug-config로 경로/활성 층/요구를 보고 편집 경로와 비교합니다. 하위 폴더와 --search/-c/--profile도 확인하고 한 요소씩 바꿔 재시작합니다. 모델/인증/권한을 동시에 바꾸지 않습니다.

표는 일반 값 병합이며 requirements.toml의 강제 제약은 별도로 지킵니다. 미신뢰로 생략되면 출처/정상 신뢰 절차를 확인하고 개명/이동으로 우회하지 않습니다. Windows/WSL 차이는 실행 파일/홈을 식별합니다. 이름이 같아도 설정/인증은 별개일 수 있습니다.

수정, 복구, 기록

실제 수정은 로드 파일을 확인해 백업하고 해당 키만 바꿉니다. 인증/공급자/다른 설정을 예시 묶음으로 대체하지 않습니다. 재시작 후 진단/로컬 표식을 보고 유효값을 확인할 수 없으면 이유와 미확인을 적습니다. 새 문제는 해당 키/파일만 복원하며 .codex 전체를 지우지 않습니다.

Symptom: record the actual error or unchanged setting.
File and layer: record the relevant path and whether it loaded.
Diagnosis: syntax / key scope / unsupported value / precedence / trust / policy.
Minimal change: record exactly one repaired cause.
Validation: distinguish sample parser checks from actual client diagnostics.
Restoration: record the backup or original value and the result after restarting.

정상 기준, 원인을 설명할 네 실패, 수정본 성공을 남깁니다. 실제 세션에서는 미로드와 로드 후 덮어쓰기를 구분하고 증거 부족도 인정합니다. Python 예시는 오프라인 파싱, Codex 층은 공식 진단으로 확인합니다. 모델/MCP/권한은 해당 강의에서 다루며 단일 키 검사로 결론내리지 않습니다.

Codex 학습 목차로 돌아가기

자세한 설명 보기

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 도구
• 튜토리얼
• Codex