gpt-image-bridge

codex CLI를 통해 브릿징하여 OpenAI의 GPT Image 2.5로 이미지 생성 기능을 제공하는 CLI 코딩 에이전트입니다. ChatGPT 구독을 사용하므로 API 키가 필요 없고, 이미지당 비용도 발생하지 않습니다.

이 브릿지는 독립적인 bash 스크립트이며, Claude Code, Cursor, Gemini CLI, aider 또는 셸 명령을 실행할 수 있는 다른 모든 에이전트에서 호출할 수 있습니다. Claude Code가 가장 좋은 사용성을 제공하는데, 이는 포함된 설치 프로그램이 이를 스킬로 등록하여 Claude가 별도의 프롬프트 없이도 이 기능을 사용하도록 하기 때문입니다.

Leonxlnx/taste-skill의 image-taste-frontend와 같은 모든 디자인 스킬 또는 에이전트가 그림을 생성해야 할 때 자체적으로 작동합니다.

개요

이는 얇은 bash 래퍼를 통해 코딩 에이전트에 이미지 생성을 추가하는 방식입니다. 이 래퍼는 codex exec을 호출하고, 기존 ChatGPT 인증을 사용하여 image_generation 도구를 호출하며, 요청한 위치에 PNG 파일을 복사합니다. 그런 다음 에이전트는 이 PNG 파일을 컨텍스트로 다시 읽어 들입니다.

OpenAI의 Images 2.5 발표에는 Codex에서의 사용 가능성이 포함되어 있습니다. 이 브릿지는 Codex가 제공하는 이미지 모델을 사용하며, 특정 백엔드 모델을 선택하거나 검증하지 않습니다. 실행 파일 이름은 기존 설치 및 스크립트와의 호환성을 위해 여전히 gpt-image-2로 유지됩니다. 이 파일명은 생성이 GPT Image 2를 의미하는 것은 아닙니다.

your agent ──shell──▶ gpt-image-2 wrapper ──codex exec──▶ image_generation
                              │                                  │
             read PNG ◀── copies to your ◀──── out.png in a ◀────┘
...

Codex는 격리된 환경(sandboxed)에서 실행되며 자체 작업 디렉토리 내부에만 쓸 수 있기 때문에, 이 래퍼는 이를 사설 임시 디렉터리로 지정하고 최종 복사 작업을 직접 수행합니다. 이렇게 하면 임의의 출력 경로(그리고 Windows 경로)가 안정적으로 작동하게 합니다.

전제 조건

• 셸 명령을 실행할 수 있는 모든 코딩 에이전트 — Claude Code, Cursor, Gemini CLI, aider 또는 자체 스크립트
• 설치된 codex CLI (macOS에서는 brew install codex, 어디서든 npm install -g @openai/codex`)
• codex login을 통해 로그인한 ChatGPT 구독(Plus / Pro / Team)
• macOS, Linux 또는 Windows — 래퍼는 bash이며, Windows에서는 Git Bash(Claude Code가 이미 사용하는 셸) 또는 WSL에서 실행됩니다.

검증:

codex login status   # 다음과 표시되어야 함: Logged in using ChatGPT
codex features list | grep image_generation    # 다음과 같아야 함: stable true

설치

Claude Code

git clone https://github.com/oakplank/gpt-image-bridge.git
cd gpt-image-bridge
./install.sh

설치 스크립트는 해당 기술을 ~/.claude/skills/gpt-image-bridge/에 복사하고 래퍼를 실행 가능하게 만듭니다. Claude Code는 이 디렉터리에서 기술을 자동으로 인식하므로 추가 설정이 필요 없으며, 이미지를 요청하면 Claude가 스스로 래퍼를 호출합니다.

기타 에이전트

설치할 것이 없습니다. 래퍼는 codex 외에 다른 종속성이 없는 자체 포함형 bash 스크립트입니다. 리포지토리를 클론하고, 실행 가능하게 만든 다음, 시스템의 PATH 내 적절한 위치에 배치하기만 하면 됩니다:

git clone https://github.com/oakplank/gpt-image-bridge.git
chmod +x gpt-image-bridge/skills/gpt-image-bridge/bin/gpt-image-2
ln -s "$PWD/gpt-image-bridge/skills/gpt-image-bridge/bin/gpt-image-2" /usr/local/bin/gpt-image-2

(Windows의 경우, 심볼릭 링크를 건너뛰고 전체 경로로 스크립트를 호출하거나, 해당 디렉터리를 PATH에 추가하세요.)

그런 다음 에이전트에게 이 래퍼가 존재한다고 알려주세요. 대부분의 에이전트는 규칙 또는 지침 파일(.cursorrules, AGENTS.md, GEMINI.md, 시스템 프롬프트)을 사용하며, 몇 줄만 추가하면 충분합니다:

이미지를 생성하려면 다음 명령을 실행하세요: gpt-image-2 "<상세 프롬프트>" <절대 출력 경로.png> [--size WxH]
프롬프트는 밀도 높고 예술적 방향성을 갖춰야 합니다. 호출에 4~6분이 걸리므로, 긴 타임아웃을 허용하세요.
결과를 확인하려면 나중에 PNG 파일을 다시 읽어보세요.

skills/gpt-image-bridge/SKILL.md는 에이전트가 더 긴 설명을 지원하는 경우의 전체 지침입니다. Claude Code용으로 작성되었지만, 그 본질(프롬프트 밀도, 사용 시점, 사용하지 않을 때, 타임아웃 처리 등)은 어디에나 적용됩니다.

에이전트 설치 (다음 내용을 에이전트에 붙여넣으세요)

아래 블록을 Claude Code 세션(또는 셸 기능을 지원하는 AI 에이전트)에 드롭하면, 스킬이 자동으로 설치되고, 필수 전제 조건을 확인하며, 테스트를 제공합니다.

Please install the gpt-image-bridge skill from https://github.com/oakplank/gpt-image-bridge so I can generate images with GPT Image 2.5 through Codex and my ChatGPT subscription.

1. Check that the `codex` CLI is installed and logged in:
...

사용법 (Usage)

에이전트가 이 래퍼(wrapper)에 대해 알게 되면, 이미지를 요청할 때마다 자동으로 호출합니다. 직접 호출할 수도 있습니다:

gpt-image-2 \
  "a photorealistic hummingbird hovering in front of a red desert canyon at golden hour, shallow depth of field, magazine quality" \
  /tmp/hummingbird.png

만약 install.sh를 통해 설치했고 PATH에 심링크(symlink)하지 않았다면, 래퍼는 ~/.claude/skills/gpt-image-bridge/bin/gpt-image-2에 위치합니다.

선택적 플래그:

• --size WxH — 특정 종횡비(aspect ratio)를 요청합니다 (예: --size 1792x1024). 생략하면 모델이 자체 크기를 선택합니다.

성공 시, 래퍼는 절대 출력 경로를 출력합니다. 실패 시에는 stderr로 codex 로그의 끝부분을 출력합니다.

왜 API를 직접 호출하는 대신 codex를 거쳐야 하나요?

디자인 기술과 결합하기

이 브릿지는 단지 도구일 뿐이며, 에이전트에게 Codex의 이미지 생성 기능에 대한 접근 권한을 줄 뿐, 좋은 이미지가 무엇인지 아는 '감각'은 아닙니다. 아트 디렉션(art-directed) 프론트엔드 작업에는 디자인 감각 기술과 결합하세요:

• @lexnlin의 Leonxlnx/taste-skill — 고도의 에이전시(agency) 프론트엔드, 슬롭(slop) 방지. 여기에 포함된 image-taste-frontend 기술은 이 브릿지가 원래 공급되도록 구축된 것입니다.
• '이미지를 먼저, 그 다음 코드를' 따르는 다른 모든 기술

이것을 gpt-image-bridge와 함께 설치하면, 이미지 생성 단계에서 자동으로 래퍼(wrapper)를 사용하게 됩니다:

npx skills add https://github.com/Leonxlnx/taste-skill --skill image-taste-frontend -a claude-code

주의사항 (Caveats)

• 지연 시간(Latency): 호출이 이미지 도구가 작동하기 전에 codex의 추론 루프를 거칩니다. 이미지당 4~6분 정도 예상하세요. 지연 시간은 사용자의 codex reasoning_effort 설정에 따라 달라집니다.
• 할당량(Quota): ChatGPT 구독에는 메시지 제한이 있습니다. 과도한 자동화 사용은 속도 제한(rate caps)에 도달할 수 있습니다.
• 서비스 약관(Terms of service): codex를 프로그래밍 방식으로 사용하여 이미지 생성을 구동하는 것은 이 도구의 정신 범위 내에 있습니다 (codex는 공식 OpenAI 제품임). 하지만 소비자 구독 자동화는 궁극적으로 OpenAI의 약관에 의해 제한됩니다. 본인의 책임 하에 사용하세요.
• Bash 필수 — macOS/Linux에서는 기본 제공되며, Windows에서는 Git Bash(Git for Windows에 번들되어 있고 Claude Code가 사용하는 것) 또는 WSL을 사용하세요.

라이선스

MIT — LICENSE 참조.