처음에는 단순한 모델 교체라고 생각했습니다. 기존 이미지 생성 경로를 GPT Image 2 쪽으로 바꾸면, 블로그 커버나 숏폼 장면 이미지를 더 안정적으로 만들 수 있겠다고 봤습니다.
그런데 막상 Codex에 붙여보니 핵심은 "이미지가 잘 나오느냐"보다 다른 데 있었습니다. 이미지를 자동화 파이프라인의 부품으로 쓸 수 있느냐가 더 중요했습니다. 한 장을 대화로 만드는 것과, 스크립트가 실패를 감지하고 다음 단계로 넘기는 것은 완전히 다른 일이었습니다.
2026년 6월 21일 기준으로 제 로컬 ~/.codex/generated_images 아래 PNG 파일은 282개였습니다. 이 숫자가 품질을 말해주지는 않습니다. 대신 여러 번 만들고, 실패하고, 다시 배선한 흔적은 보여줍니다. 그 과정에서 남은 기준을 정리합니다.
공식 문서보다 먼저 확인해야 했던 것
OpenAI 공식 문서 기준으로 gpt-image-2는 텍스트와 이미지 입력을 받아 이미지 출력을 만드는 이미지 생성·편집 모델입니다. Codex manual 기준으로는 Codex의 built-in image generation도 gpt-image-2를 사용합니다.
여기까지만 보면 질문은 간단해 보입니다.
- Codex에서 이미지를 만들 수 있나?
- 만들 수 있다면 어디에 저장되나?
- API를 따로 붙이지 않아도 되나?
그런데 실제 자동화에서는 질문이 조금 바뀝니다.
- 프롬프트는 어떤 인자로 받을 것인가?
- 참조 이미지는 몇 장까지 어떤 순서로 넘길 것인가?
- 결과 파일은 어디에, 어떤 이름으로 남길 것인가?
- 실패했을 때 이전 이미지를 조용히 재사용하지 않게 막을 수 있는가?
제가 만든 wrapper의 핵심도 여기에 있었습니다. $1은 프롬프트, $2부터는 reference image 경로로 받고, OUTPUT_DIR 환경변수를 존중하게 했습니다. 생성된 PNG는 그 디렉토리에 새 파일로 남기고, 이미지가 안 만들어지면 비정상 종료하게 했습니다.
모델을 고르는 것보다 먼저, 입출력 계약을 작게 고정하는 일이 필요했습니다.
codex exec는 가능했지만, 그냥 붙이면 부족했습니다
Codex 문서에서 codex exec는 스크립트나 CI 같은 비대화 실행에 쓰는 경로입니다. 자동화에 붙이기 좋은 모양입니다. 제 경우에도 이미지 생성 wrapper는 이 비대화 실행 경로를 전제로 만들었습니다.
다만 "비대화 실행이 된다"와 "운영 파이프라인에 안전하게 들어간다"는 다릅니다.
예를 들어 숏폼 이미지 파이프라인에서는 장면 이미지가 하나라도 빠지면 뒤 단계가 흔들립니다. 그래서 wrapper는 이미지가 없을 때 성공처럼 넘어가면 안 됩니다. 생성 실패, 파일 미발견, 잘못된 출력은 모두 실패로 닫아야 합니다.
이 원칙은 꽤 중요했습니다. 자동화에서 제일 위험한 실패는 크게 터지는 실패가 아니라, 이전 산출물을 그럴듯하게 재사용하고 지나가는 실패였습니다. 겉으로는 파일이 있으니까 다음 단계가 굴러가지만, 실제로는 오늘 만들어야 할 이미지가 아닐 수 있습니다.
그래서 저는 다음 기준을 잡았습니다.
- 출력 디렉토리를 명시한다.
- 실행 전후 파일 차이로 새 PNG를 찾는다.
- 없으면 실패한다.
- fallback은 "이전 파일 그대로 복사"가 아니라 최소한 새 생성 또는 명시적 변형이어야 한다.
이렇게 해두면 이미지 모델이 가끔 흔들려도 파이프라인이 조용히 거짓 성공을 만들 가능성이 줄어듭니다.
제일 실전적인 문제는 401 오류였습니다
가장 기억에 남는 문제는 이미지 품질이 아니라 인증이었습니다.
한 cron 작업에서 2026년 6월 8일, 10일, 12일 세 번의 run 동안 커버 배경 이미지가 byte-identical로 재사용된 적이 있었습니다. 처음에는 프롬프트가 너무 비슷했나 싶었는데, 로그를 보니 Codex 이미지 생성 쪽이 401 Unauthorized로 실패하고 있었습니다.
원인은 제 환경에서는 HOME remapping이었습니다. 자동화 작업의 HOME이 일반 사용자 홈이 아니라 샌드박스 홈으로 잡히면서, Codex가 로그인 정보가 없는 쪽의 .codex를 보고 있었습니다.
확인 과정은 단순했습니다.
- 빈
CODEX_HOME을 가리키면 Codex가 credential 없음으로 진단됨 - 실제
~/.codex를 가리키면 auth configured로 진단됨 - sandbox HOME 환경에서도
CODEX_HOME을 명시하면 새 PNG 생성까지 성공함
그래서 해결책은 모델 프롬프트가 아니라 Codex가 어떤 home에서 auth를 읽는지 고정하는 것이었습니다.
물론 이걸 일반화하면 안 됩니다. 모든 401 오류의 원인이 CODEX_HOME이라는 뜻은 아닙니다. 토큰 만료, 권한, 네트워크 등 다른 원인도 있을 수 있습니다. 다만 제 자동화에서는 인증 파일 위치가 실제 원인이었습니다.
Codex 내장 생성과 API 호출을 나눠 생각하게 됐습니다
처음에는 "Codex에서 바로 되면 API는 필요 없나?"라는 식으로 생각했습니다. 지금은 조금 다르게 봅니다.
Codex 내장 이미지 생성은 작업 중간에 필요한 커버나 숏폼 장면 이미지처럼 소량의 시각 자료를 빠르게 만들 때 좋았습니다. 특히 코드와 이미지가 한 흐름 안에 있을 때 편합니다. 프롬프트를 다듬고, 생성 결과를 보고, 파일로 이어 붙이는 루프가 짧습니다.
반대로 다음 조건이면 API 경로를 따로 검토하는 편이 맞습니다.
- 큰 배치를 규칙적으로 생성한다.
- 비용을 별도로 추적해야 한다.
- Codex 로그인 흐름과 분리된 API 운영 경로가 필요하다.
OpenAI 문서도 Image API와 Responses API를 나눠 설명합니다. 한 장 생성·편집이면 Image API가 단순하고, 대화형·반복 편집 흐름이면 Responses API가 맞습니다. Codex 내장 생성은 또 다른 층입니다. 제 기준으로는 개발 작업 안에서 바로 필요한 이미지는 Codex, 제품화된 대량 생성은 API에 가깝습니다.
제가 남긴 자동화 체크리스트
GPT Image 2를 Codex에서 쓰려는 분이라면, 저는 프롬프트보다 먼저 아래를 확인하겠습니다.
- 이 작업은 대화 중 한두 장이면 충분한가, 아니면 반복 배치인가?
- 결과 파일을 찾는 규칙이 명확한가?
- 새 파일이 없을 때 실패하도록 되어 있는가?
- 이전 산출물을 조용히 재사용하지 않게 막았는가?
- cron이나 CI 같은 환경에서
CODEX_HOME이나 인증 경로가 달라지지 않는가? - reference image를 넘긴다면 순서와 개수를 wrapper에서 고정했는가?
- API 경로로 빼야 할 만큼 대량·정량 관리가 필요한가?
제가 얻은 결론은 단순합니다.
이미지 생성 자동화의 핵심은 더 멋진 한 장이 아니라, 실패를 알아차리는 작은 계약입니다. GPT Image 2와 Codex가 좋은 도구인 건 맞지만, 파이프라인 안에서는 도구보다 계약이 먼저였습니다. 어느 디렉토리에 무엇이 생겨야 하고, 안 생기면 어떻게 멈출지. 그걸 정해놓고 나서야 이미지 생성이 자동화의 믿을 만한 부품이 됐습니다.