저는 의도적으로 모델 ID를 고정(pin)합니다. 유동적인 별칭(Floating aliases)은 이전에 저를 곤란하게 만든 적이 있습니다. -latest 태그 아래에서 조용히 이루어진 변경이 프로덕션 환경의 도구 호출(tool-calling) 세부 사항을 바꿔놓았고, 그 결과 저는 git bisect와 즐겁지 않은 커피 한 잔과 함께 토요일을 통째로 날려야 했습니다. 그래서 제가 실행하는 모든 것은 날짜가 지정된 스냅샷(snapshot)을 가리킵니다. gpt-5-codex도 그중 하나였습니다.

지난주 저는 드디어 OpenAI의 중단(deprecations) 페이지를 대충 훑어보는 대신 처음부터 끝까지 정독했고, 그곳에서 발견했습니다. gpt-5-codex가 10개의 이웃 모델 옆에 조용히 앉아 2026-07-23에 은퇴한다는 사실을 말이죠. 이 글을 쓰는 지금은 7월 16일입니다. 즉, 7일 남았습니다.

만약 아래의 스냅샷 중 하나라도 고정해서 사용하고 있다면, 이것을 주의 신호로 받아들이십시오. 여기 전체 은퇴 목록, 귀하가 영향을 받는지 약 10분 만에 확인하는 방법, 제가 실제로 회귀 테스트(regression-test)를 수행할 대체 맵, 그리고 지난번 강제 마이그레이션을 공포에서 지루함으로 바꿔놓은 단 하나의 구조적 변화를 정리했습니다.

종료 목록 (2026-07-23 은퇴)

OpenAI의 API deprecations page에서 직접 가져왔습니다. 이 글을 쓰면서 각 행을 소스와 대조하며 확인했습니다. 날짜와 대체 모델은 수정될 수 있으므로, 조치를 취하기 전에 여러분도 똑같이 확인하십시오.

그 형태를 주목하십시오: *-codex 라인은 gpt-5.5로 통합됩니다. 단, gpt-5.1-codex-mini는 gpt-5.4-mini로 내려갑니다. chat-latest 별칭들도 gpt-5.5로 접히며, 두 개의 *-search-preview 스냅샷은 gpt-5.4-mini로 이동합니다. 그리고 두 개의 프리뷰 제품군(tts, computer-use)은 단순히 더 최신의 날짜가 지정된 스냅샷 또는 날짜가 지정되지 않은 별칭으로 넘어갑니다. 일단 분류(buckets)를 파악하고 나면, 마이그레이션은 11개 행의 표가 보이는 것만큼 위협적이지 않습니다.

영향 여부 확인하기 (약 10분 소요)

함정은 여러분이 하드코딩했다고 기억하는 모델 ID가 아닙니다. 여러분이 잊어버린 것들, 즉 .env 파일, 설정 테이블(config table), 기능 플래그(feature flag), 또는 팀원이 한 번 실행했던 노트북(notebook) 속에 파묻혀 있는 것들이 함정입니다. 두 번의 검토(passes)만으로 거의 모든 것을 잡아낼 수 있습니다.

1. 코드를 Grep 하세요. 하나의 정규 표현식(regex)으로 종료되는 모든 ID를 확인할 수 있습니다:

grep -rniE \\
  'gpt-5-codex|gpt-5\.1-codex|gpt-5\.2-codex|gpt-5(\.1)?-chat-latest|gpt-4o(-mini)?-search-preview-2025-03-11|gpt-4o-mini-tts-2025-03-20|computer-use-preview-2025-03-11' \\
  --include='*.py' --include='*.ts' --include='*.js' --include='*.go' \\
...

2. 실제로 배포(shipped)된 것을 Grep 하세요. 코드 검색(Code search)은 데이터베이스, 대시보드 토글(dashboard toggle), 또는 사용자가 제공한 파라미터(param)를 통해 전달되는 ID를 놓칠 수 있습니다. 만약 외부 요청(outbound requests)을 .model 필드가 포함된 JSON 라인 형식으로 로깅하고 있다면, 실제로 네트워크를 통해 전송된(went over the wire) 데이터를 집계하세요:

jq -r 'select(.model) | .model' requests.log \\
  | sort | uniq -c | sort -rn \\
  | grep -E 'codex|chat-latest|search-preview-2025-03-11|gpt-4o-mini-tts-2025-03-20|computer-use-preview-2025-03-11'

구조화된 로그(structured logs)가 없나요? OpenAI의 사용량 내보내기(usage export) 또는 대시보드(dashboard)는 모델별로 비용을 분류해 줍니다. 이름순으로 정렬하여 위의 11개 항목을 찾아보세요. 만약 종료 예정인 ID가 대시보드에는 나타나지만 Grep 결과에는 없다면, 그것이 바로 당신이 놓쳤을 설정 기반 호출자(config-driven caller)입니다.

종료 예정인 세트(retiring set)를 상수로 유지하세요. 이 문자열 중 하나라도 다시 나타나면 빌드를 실패하게 만드는 CI 체크(CI check)에서 유용하게 사용할 수 있습니다:

RETIRING_2026_07_23 = {
    "gpt-5-codex", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini",
    "gpt-5.2-codex", "gpt-5-chat-latest", "gpt-5.1-chat-latest",
...

마이그레이션 지도 — 그리고 제가 실제로 테스트할 것들

문자열을 교체하는 것은 쉬운 부분입니다. 대체 모델들은 단순히 이름만 바뀌는 쌍둥이가 아니므로, 각 범주(bucket)를 단순한 이름 변경이 아닌 동작의 변화(behavior change)로 취급해야 합니다.

• *-codex → gpt-5.5. 이것은 가장 큰 변화입니다. Codex 스냅샷(snapshots)은 에이전트 방식의 코딩(agentic coding)에 맞춰 튜닝되었으나, gpt-5.5는 범용 모델(general model)입니다. 코딩 평가(coding evals) / 골든 트랜스크립트(golden transcripts)를 다시 실행하여 추론 깊이(reasoning depth), 패치/디프(patch/diff) 포맷팅, 그리고 도구 호출 인자(tool-call arguments)를 모니터링하십시오. 만약 모델의 출력을

1. 교체된 모델과 차이(diff) 출력물에 대해 기존의 평가/골든 세트(eval/golden set)를 실행하십시오. 단일 프롬프트를 눈으로만 확인(eyeball)하지 마십시오.
2. 모델 출력(도구 호출 JSON, 코드 펜스(code fences), 함수 인자)을 소비하는 모든 파서(parser) 또는 스키마(schema)를 재검증하십시오.
3. 새로운 모델의 토큰 계산(token accounting)과 비용을 점검(sanity-check)하여, "빠른 교체"가 빈번하게 사용되는 경로(hot path)의 가격을 조용히 변경하지 않도록 하십시오.
4. 특수한 기능(검색 그라운딩(search grounding), 컴퓨터 사용(computer use), TTS 음성)에 대한 기능적 동등성(capability parity)을 확인하십시오. 교체 모델은 특정 기능을 삭제하거나 이동할 수 있습니다.

다음 파도가 이미 예정되어 있습니다 (2026-12-11)

지원 종료(deprecation) 페이지를 보고 계시다면 아래로 스크롤해 보십시오. 두 번째 배치인 gpt-5-2025-08-07, gpt-5-mini, gpt-5-nano, gpt-5-pro, o3, 그리고 o3-pro가 2026-12-11에 은퇴하고 gpt-5.5 / gpt-5.4-mini / gpt-5.4-nano / gpt-5.5-pro로 전환될 예정입니다. 이번 주에 당장 급한 일은 아니지만, 어차피 모델 설정을 수정하고 있다면 12월에 두 번째 혼란이 발생하지 않도록 지금 메모해 두십시오.

모델 ID를 하나의 레이어로 통합하여, 다음번에는 지루할 정도로 쉽게 만드십시오

이것은 제가 계속해서 다시 배우고 있는 부분입니다. 강제 마이그레이션의 고통은 모델 이름을 명시한 곳이 얼마나 많은가에 따라 규모가 커집니다. gpt-5-codex가 19개의 파일, 3개의 서비스, 그리고 하나의 설정 테이블에 리터럴 문자열(literal string)로 박혀 있다면, 지원 종료는 마감 기한 내에 19개 파일에 대한 PR(Pull Request)을 처리해야 하는 일이 됩니다. 반면 모델 이름이 정확히 하나의 라우팅/설정(routing/config) 레이어에 존재한다면, 그것은 단 한 줄의 변경과 재배포(redeploy)로 끝납니다.

그래서 저의 현재 규칙은 이렇습니다: 애플리케이션 코드에서는 절대 모델 ID를 직접 쓰지 않습니다. 대신 "code-agent", "cheap-classifier", "tts"와 같은 _역할(role)_을 요청하고, 작은 설정(config) 파일이 해당 역할을 구체적인 스냅샷(snapshot)에 매핑합니다. 이렇게 하면 강제 마이그레이션은 해당 매핑을 편집하고, 평가(evals)를 다시 실행하고, 배포하는 과정이 됩니다. 위에 언급된 11개의 모델도 단 한 번의 커밋으로 해결되었을 것입니다.

제 개인 설정에서 해당 라우팅 계층(routing layer)은 byesu로, 단일 키를 통해 gpt-5.5/gpt-5.6을 Claude, Gemini, Grok과 함께 전면에 내세우는 OpenAI 호환 게이트웨이(gateway)입니다. OpenAI 호환 방식이기 때문에, 위 표에 명시된 교체 모델들은 기존 클라이언트를 하나의 기본 URL(base URL)로 지정하고 모델 문자열을 한 곳에서 변경하는 것만으로 접근할 수 있습니다. 즉, SDK, 요청 형태(request shape), 파싱(parsing) 코드를 옮길 필요가 없습니다. 분명히 말씀드리자면, 이러한 이점을 얻기 위해 반드시 게이트웨이가 필요한 것은 아닙니다. 단순한 상수 파일(constants file)이나 MODEL_ROLES 딕셔너리(dict)만으로도 대부분의 이점을 얻을 수 있습니다. 핵심은 도구가 아니라 간접 참조(indirection)입니다. 하지만 모든 제공업체(provider)를 하나의 호환 가능한 엔드포인트(endpoint) 뒤에 두었기에, 저는 "gpt-5-codex가 사라졌다"는 상황을 여러 리포지토리(repo)를 뒤지는 작업 대신 설정(config) 편집 작업으로 처리할 수 있었습니다.

7일간

구체적으로, 7월 23일 전까지 다음을 수행하십시오: 두 번의 grep을 실행하고, 노출된 스냅샷(snapshots) 목록을 작성하며, 표에 따라 교체 모델을 선택하고, 실제 트래픽에 대한 출력값의 차이(diff)를 확인한 뒤, 배포(ship)하십시오. 만약 코드베이스 곳곳에 11개의 문자열이 흩어져 있다면, 지금이 이를 하나의 역할→모델(role→model) 매핑 뒤로 숨길 수 있는 저렴한 시기이기도 합니다. 왜냐하면 12월의 배치(batch) 작업이 이미 예정되어 있으며, 그 이후에도 항상 또 다른 작업이 있을 것이기 때문입니다.

직접 소스 페이지를 읽고 귀하의 스택(stack)과 날짜를 대조해 보십시오. 지원 종료(deprecation) 표는 "다음 스프린트(sprint)에 처리하겠다"는 말이 통하지 않는 엄격한 마감 기한이 존재하는 유일한 문서 종류입니다.

만약 저처럼 gpt-5-codex를 고정(pinned)해 두었다면, 시간은 이미 흐르고 있습니다.