乔木 Codex 이미지 생성 튜토리얼: Claude, Cursor 및 모든 Agent가 먼저 스타일을 선택한 후 이미지 생성

프로젝트 소개

qiaomu-codex-imagegen은 Codex에 내장된 이미지 생성 기능을 MCP 서비스, 명령줄 도구 및 Agent Skill로 패키징합니다. 설치 후 Claude Code, Codex, Cursor 또는 명령을 실행할 수 있는 다른 Agent가 자연어 요청에 따라 이미지 파일을 생성할 수 있습니다.

일반적인 “프롬프트 한 줄을 입력해 바로 이미지 생성” 방식과는 다릅니다. 기본적으로 먼저 suggest_directions를 통해 메커니즘이 서로 다른 스타일 방향을 최소 네 가지 추천하고, 사용자가 방향을 선택하면 compose_prompt가 완전한 프롬프트를 작성한 뒤 최종적으로 이미지를 생성하고 결과를 확인합니다.

프로젝트에는 24가지 장면 템플릿, 48개 프리셋, 66가지 범용 스타일 및 20명의 Mondo 포스터 디자이너 스타일이 내장되어 있습니다. 또한 텍스트, 사실, 구도 및 검수를 위한 규칙도 제공하므로 표지, 포스터, 소셜 미디어 이미지, 제품 비주얼 및 참고 이미지 편집에 적합합니다.

핵심 작업 흐름

1. 방향 추천: 주제와 사용 장면에 따라 텍스트 중심, 평면 구조, 인물 사진, 제품 클로즈업 또는 소재 공간 등 메커니즘이 서로 다른 방향을 최소 네 가지 반환합니다.
2. 방향 선택: 사용자는 하나 이상의 방향을 선택하거나 Agent가 직접 결정하도록 할 수 있습니다. 마음에 들지 않으면 기존 방향을 제외한 뒤 다시 추천받을 수도 있습니다.
3. 프롬프트 작성: 템플릿 변수에 값을 입력해 완전한 프롬프트를 만들고, 동시에 제외할 요소, 검수 조건, 가정 및 누락 정보를 제공합니다.
4. 이미지 생성: 선택한 각 방향마다 이미지 한 장을 생성하고, 재현 및 시리즈 콘텐츠 제작을 위해 실제 사용한 JSON 정보를 이미지 옆에 저장합니다.
5. 검수 및 재생성: Agent가 검수 조건에 따라 이미지를 항목별로 확인하며, 기준에 맞지 않으면 해당 부분만 수정해 한 번 더 생성합니다.

사용자가 이미 “Mondo 스타일 사용”처럼 스타일을 명확히 지정했거나 직접 T03을 제공한 경우, 시스템은 방향 선택을 건너뛰고 바로 프롬프트 구성 또는 생성 단계로 진행할 수 있습니다.

설치 전 준비

사용하기 전에 다음 환경을 준비해야 합니다.

• Node.js 18 이상: node --version으로 확인할 수 있습니다.
• Codex CLI: 설치 및 로그인이 필요하며, codex --version으로 명령을 사용할 수 있는지 확인합니다.
• 이미지 생성 권한: 현재 Codex 계정에서 이미지 생성을 사용할 수 있어야 합니다. 먼저 Codex에서 직접 이미지를 한 장 생성해 확인하는 것을 권장합니다.

프로젝트 자체는 의존성이 없는 Node.js 프로젝트이지만, 실제 이미지 생성에는 로컬에서 사용할 수 있는 Codex CLI와 계정 크레딧이 필요합니다.

Agent Skill 설치

사용 중인 Agent가 Agent Skills를 지원한다면 다음 명령을 바로 실행할 수 있습니다.

npx skills add joeseesun/qiaomu-codex-imagegen

Skill은 Agent가 장면 선택, 스타일 선택, 설명 작성 및 검수 방식을 이해하도록 돕고, MCP 또는 프로젝트에 포함된 명령줄 도구를 통해 이미지를 생성합니다.

MCP 서비스 등록

Claude Code에 등록

아래 경로를 프로젝트가 실제로 위치한 디렉터리로 바꾸십시오.

claude mcp add --scope user qiaomu-codex-imagegen -- node /절대경로/qiaomu-codex-imagegen/scripts/mcp-server.mjs

다른 MCP 클라이언트에서 구성

Cursor, Codex 또는 다른 MCP 클라이언트의 구성 파일에 다음 내용을 추가할 수 있습니다.

{
  "mcpServers": {
    "qiaomu-codex-imagegen": {
      "command": "node",
      "args": ["/절대경로/qiaomu-codex-imagegen/scripts/mcp-server.mjs"]
    }
  }
}

MCP 서비스는 일곱 가지 도구를 제공합니다.

• suggest_directions: 무료로 즉시 메커니즘이 서로 다른 스타일 방향을 최소 네 가지 추천합니다.
• compose_prompt: 템플릿과 프리셋을 완전한 프롬프트로 확장하고, 제외할 요소, 검수 조건 및 누락 정보를 반환합니다.
• generate_image: 새 이미지를 생성하거나 참고 이미지 편집을 수행하고, 파일 경로와 픽셀 크기를 반환합니다.
• search_prompts 및 get_prompt: 로컬 참고 프롬프트 코퍼스를 검색하고 읽습니다.
• build_prompt: 간단한 경로로 생성되는 프롬프트를 미리 확인하지만 실제 이미지는 생성하지 않습니다.
• list_catalog: 장면 프리셋, 템플릿, 스타일 키 및 로컬 코퍼스 상태를 확인합니다.

명령줄만 사용하기

MCP가 필요하지 않다면 저장소를 직접 복제하고 CLI를 실행할 수도 있습니다.

git clone https://github.com/joeseesun/qiaomu-codex-imagegen
cd qiaomu-codex-imagegen
node scripts/cli.mjs "창가에 펼쳐진 책, 책장 위로 피어오르는 커피의 김" --preset xiaohongshu

기본 생성 이미지는 ~/Pictures/qiaomu-codex-imagegen/<날짜>에 저장됩니다. --out, --name 및 --json으로 출력 디렉터리, 파일명 및 기계 판독 가능한 결과를 제어할 수도 있습니다.

기본 사용법: 먼저 방향 추천받기

포스터, 표지 및 소셜 미디어 이미지 작업에서는 먼저 추천받은 후 생성하는 흐름을 우선 사용하는 것이 좋습니다. 다음 명령은 “한 달간 진행되는 카페 독서 행사”에 대해 여러 방향을 추천하지만 이미지 생성 크레딧은 소모하지 않습니다.

node scripts/cli.mjs suggest "한 달간 진행되는 카페 독서 행사" --for 동영상 표지

반환 결과에는 일반적으로 각 방향의 시각적 메커니즘, 스타일 잠금, 추가로 필요한 정보 및 참고 사례가 설명됩니다. 방향 하나를 선택하거나 Agent에게 여러 방향을 병렬로 생성해 비교하도록 할 수 있습니다.

템플릿 프롬프트 확장

방향을 정한 후에는 완전한 프롬프트와 검수 조건을 먼저 확인할 수 있습니다.

node scripts/cli.mjs compose --template T03-1 --var topic=곡우 --var subject=새싹 --var headline=곡우

템플릿은 변수에 따라 구조화된 설명을 생성합니다. 주제와 스타일 외에도 텍스트 계층, 여백, 안전 영역, 실패 조건 및 검사 기준이 포함될 수 있습니다. 프롬프트를 먼저 확인하면 정식 생성 전에 변수 누락이나 문구가 지나치게 긴 문제를 발견하는 데 도움이 됩니다.

템플릿으로 이미지 생성

프롬프트에 문제가 없는지 확인한 후 바로 생성할 수 있습니다.

node scripts/cli.mjs generate --template T03-1 --var topic=곡우 --var subject=새싹 --var headline=곡우

프로젝트에는 큰 글자와 작은 서사, 사물의 프레임 돌파, 중앙 빛의 틈, 동양 수묵 편집, 종이 조각과 직물 지형, 사진 인물, 음식 클로즈업, 기술 제품 메인 비주얼, 건축 도면 및 정보 카드 등 24가지 템플릿이 포함되어 있습니다. 각 템플릿은 색상이나 필터만 바꾸는 것이 아니라 구도 메커니즘, 소재 관계, 텍스트 계층 및 주제 간 관계를 변경합니다.

프리셋과 스타일로 빠르게 생성

장면과 스타일을 이미 알고 있다면 방향 추천을 거치지 않는 간단한 경로를 사용할 수 있습니다. 예를 들어 동영상 표지 세 가지 안을 생성하려면 다음과 같이 실행합니다.

node scripts/cli.mjs "거대한 빨간 재생 버튼이 일출처럼 떠오르는 모습" --preset video-cover --style saul-bass --count 3

자주 사용하는 장면 프리셋은 다음과 같습니다.

• xiaohongshu 및 xiaohongshu-square: 샤오홍슈 3:4 또는 정사각형 표지.
• video-cover: YouTube, Bilibili 등의 16:9 가로형 표지.
• video-vertical: Douyin, WeChat Channels 및 Reels용 9:16 세로형 표지.
• wechat-cover: 공식 계정 2.35:1 헤더 이미지.
• x-cover: X 프로필 5:2 표지.
• moments: 위챗 모멘트 4:5 포스터.
• poster 및 movie-poster: 일반 포스터 및 영화 포스터.
• book-cover, album-cover, article 및 paper: 도서, 앨범, 글 및 과학 콘텐츠용 이미지.

예를 들어 Mondo 스타일로 텍스트 없는 영화 포스터를 만들 수 있습니다.

node scripts/cli.mjs "사막 속 거대한 샌드웜의 실루엣과 작은 인물" --preset movie-poster --style olly-moss

이미지 안의 텍스트 제어

포스터와 표지에는 보통 제목 하나만이 아니라 부제, 정보 줄 또는 배지 등이 필요합니다. --text로 텍스트를 지정할 수 있습니다.

node scripts/cli.mjs "등대 하나" --preset wechat-cover --text "야간 항해선"

중국어 또는 긴 문구가 포함된 경우에는 짧은 문장을 한 글자씩 명시하고, 생성 후 확대해 확인하는 것이 좋습니다. 프로젝트 설명에 따르면 모델은 중국어와 작은 글씨의 정보 줄을 생성할 때 여전히 미세한 오류를 일으킬 수 있습니다. 인물 사진이나 정보 레이어가 필요 없는 제품 클로즈업에는 텍스트 없는 방식을 사용할 수 있습니다.

참고 이미지 편집

--ref를 사용하면 하나 이상의 참고 이미지를 제공할 수 있습니다. 참고 이미지 경로는 절대 경로여야 합니다.

node scripts/cli.mjs "같은 연필을 유지하고 배경을 따뜻한 베이지색 종이로 변경" --ref /abs/pencil.png --ratio 1:1

이 방식은 배경 교체, 주제 유지 또는 부분적인 시각 조정에 적합합니다. 프로젝트는 이미지를 자동으로 잘라내지 않으므로 최종 비율이 요구 사항과 맞지 않으면 결과에 크기 차이가 표시됩니다.

프롬프트 미리 보기 및 로컬 사례 검색

이미지를 생성하지 않고 프롬프트만 확인하려면 다음 명령을 사용할 수 있습니다.

node scripts/cli.mjs "커피와 책" --preset xiaohongshu --show-prompt

선택 가능한 로컬 코퍼스를 이미 구축했다면 유사한 사례도 검색할 수 있습니다.

node scripts/cli.mjs search "절기 차" --limit 5

코퍼스에는 약 689개의 참고 프롬프트와 썸네일이 포함되어 있지만, 이러한 제3자 데이터는 저장소에 포함되어 배포되지 않습니다. 코퍼스가 없어도 템플릿, 스타일 및 이미지 생성 흐름은 정상적으로 사용할 수 있습니다.

고급 설정 및 실전 권장 사항

시리즈 이미지의 방향 고정

샤오홍슈 이미지나 여러 장의 표지를 제작할 때는 먼저 첫 번째 이미지의 템플릿과 스타일을 선택한 다음, 후속 이미지에도 동일한 스타일 잠금, 비율 및 정보 구조를 적용하는 것이 좋습니다. 이렇게 하면 이미지마다 “비슷한 스타일”을 따로 입력하는 것보다 일관성을 유지하기 쉽습니다.

병렬 변형 사용 시 크레딧 관리

--count는 1개에서 4개의 변형을 병렬로 생성할 수 있지만, 이미지마다 Codex 또는 OpenAI 계정의 사용량이 차감됩니다. 이미지 한 장을 생성하는 데는 보통 약 30~60초가 걸리며, 병렬 생성 수가 많을수록 사용량도 그에 따라 증가합니다.

투명 배경 문제 처리

프로젝트는 생성 결과의 투명 영역을 감지합니다. 기본적으로 투명 영역이 감지되면 흰색 배경으로 병합합니다. 투명 배경을 유지해야 하는 경우 transparent_background: true를 사용할 수 있습니다. 이 처리는 일부 이미지 뷰어에서 투명 영역이 검은 테두리로 표시되는 문제를 방지하기 위한 것입니다.

Codex 경로와 시간 제한 지정

시스템에서 Codex를 찾지 못하는 경우 환경 변수 QIAOMU_CODEX_BIN으로 실행 파일 경로를 지정할 수 있습니다. 생성 시간이 초과되면 --timeout 값을 늘리거나 설명을 먼저 단순화하세요.

node scripts/cli.mjs "커피숍 독서 행사 표지" --preset video-cover --timeout 120000

로컬 코퍼스 패키지 구축

자체 아카이브 디렉터리가 있고 그 안에 archive.json, prompts/, images/가 포함되어 있다면 다음을 실행할 수 있습니다.

node scripts/build-corpus.mjs /path/to/프롬프트_아카이브

기본 코퍼스 디렉터리는 ~/.local/share/qiaomu-codex-imagegen/corpus이며, QIAOMU_CORPUS_DIR으로 다른 위치를 지정할 수도 있습니다. 코퍼스 패키지는 로컬에서만 사용하는 것을 권장하며, 권한이 없는 제3자 콘텐츠를 커밋하거나 전달하지 마세요.

설치 성공 여부 확인

프로젝트는 오프라인 테스트와 디렉터리 검사 명령을 제공합니다.

npm test
node scripts/cli.mjs --list
node scripts/cli.mjs "빨간색 원 하나" --show-prompt

npm test는 이미지 생성 사용량을 차감하지 않으며, 템플릿 조립, 텍스트 모드, 구조 치환, 방향 다양성, 코퍼스 검색, 투명 배경 처리 및 프로토콜 등의 기능을 확인하는 데 사용할 수 있습니다.

자주 묻는 질문

• cannot start codex: Codex CLI가 설치되어 있는지 확인하거나 QIAOMU_CODEX_BIN을 설정하세요.
• codex finished without producing an image: Codex 로그인 상태와 계정에 이미지 생성 권한이 있는지 확인하세요.
• timed out: 시간 제한을 늘리거나 설명의 복잡도를 낮추세요.
• 비율이 예상과 다름: 설명에서 비율을 다시 강조하거나 --ratio를 사용하세요. 도구는 자동으로 조용히 자르지 않습니다.
• 참조 이미지를 찾을 수 없음: --ref 값을 절대 경로로 변경하세요.

맺음말

qiaomu-codex-imagegen의 핵심은 단순히 한 문장을 이미지 모델에 전달하는 것이 아니라, 장면, 스타일, 구도 관계, 텍스트 계층 및 검수 기준을 재사용 가능한 워크플로로 구성하는 데 있습니다. Agent Skill 또는 MCP로 시작해 Agent가 추천과 구성을 담당하도록 할 수도 있고, CLI를 통해 프리셋, 스타일, 비율, 텍스트 및 참조 이미지를 정밀하게 제어할 수도 있습니다.

표지, 포스터 및 시리즈 이미지를 안정적으로 제작해야 하는 작업에는 “먼저 방향을 추천하고, 프롬프트를 확장한 다음, 생성 후 조건에 따라 검수하는” 프로세스를 권장합니다. 정식으로 사용할 이미지 내 텍스트와 크기는 반드시 사람이 다시 확인하세요.