# Claude Code × Codex × Image-2 起手包

教你的 Claude Code 自動調用 Codex CLI 跑 GPT Image-2 生圖、跳過手動切去 ChatGPT 點按鈕。

> 來自 [@be.ai.curator](https://www.threads.com/@be.ai.curator) Post 17 配套資源包
>
> 完整實作案例在 [Blog 長文](https://be-ai-curator.com/blog/claude-codex-image2-workflow)

---

## 為什麼要這樣串

Claude Code 是 orchestrator——選題、寫稿、品管都靠它在跑。
Codex 對 Claude Code 來說就是另一個能用的助手。
GPT Image-2 是 OpenAI 在 2026-04-21 推出的繁中字精準度最高的 image gen 模型。

把三者串起來：Claude Code 寫好 prompt、Codex 跑 Image-2、生出來的圖直接落到資料夾。

不用每次都切到 ChatGPT chat 端點按鈕、不用 OpenAI API 計費（走 ChatGPT Plus 訂閱）、不用付額外的錢。

---

## 你會學到什麼

1. **3 步驟把 Codex CLI 接進 Claude Code**（見 Part 2）
2. **通用 image prompt 模板**（封面 / infographic / 簡報配圖、見 Part 3）
3. **避開 3 個常見雷**（native size 不可預測、chrome 跨張飄、自動長英文字）
4. **進階串接**（讓 Claude Code 自動 orchestrate 完整 pipeline）

## 你不會學到什麼

- 完整 9-slide carousel 設計系統（這是我的內部資產）
- Avatar pin 機制 / Chrome lock token-level spec / 21-point QA rubric

這些是品牌專屬規範。但你拿到這個 skill 之後、就能在自己的工作流上發展自己的版本。

## 適用工具

- ChatGPT Plus / Pro 訂閱（**不用** OpenAI API key）
- macOS / Linux（Codex CLI 跨平台）
- Claude Code（任何版本、skills 機制都通用）
- Node.js 18+（裝 Codex CLI 用）

## 你會花多少時間

- 安裝 + login: ~5 分鐘
- 第一張圖 OK: ~15 分鐘
- 把它接進你的真實工作流: ~1-2 小時（要熟悉 prompt template）

---

## 安裝（複製到 Claude Code skills 目錄）

把整段 Part 1 的 SKILL frontmatter + 內容存成 `~/.claude/skills/claude-codex-image/SKILL.md`：

```bash
mkdir -p ~/.claude/skills/claude-codex-image/references
# 把 Part 1 寫進 SKILL.md
# 把 Part 2 寫進 references/3-step-setup.md
# 把 Part 3 寫進 references/prompt-template.md
```

或者放到專案內 `<your-project>/.claude/skills/claude-codex-image/`。

之後在 Claude Code 對話中、skill 會自動載入。

---

# Part 1 — Skill 主體（SKILL.md）

```markdown
---
name: claude-codex-image
description: 教 Claude Code 怎麼自動調用 Codex CLI 跑 GPT Image-2 生圖、繞過 ChatGPT chat 端手動點按鈕。Use when 需要產出含繁中字的封面、infographic、簡報配圖；要批量生視覺一致的圖；想自動化生圖工作流。Do NOT use for 單張快速 iterate（ChatGPT 直接點較快）、無中文字的多插圖場景（用 gemini-image-gen 較划算）。
---

# Claude Code × Codex × Image-2 橋接 Skill

讓 Claude Code 自動調用 Codex CLI 跑 GPT Image-2 生圖、跳過 ChatGPT chat 端手動點按鈕的工作流。

## 核心 reframe

Codex 不只是 code reviewer 或開發工具——對 Claude Code 來說，它是**生圖外掛**。

三角色分工：
- **Claude Code** = 大腦（規劃、寫 prompt、品質把關）
- **Codex** = 手（接 Claude Code 的指令、跑 Image-2 tool）
- **Image-2** = 視覺（產生 PNG）

## 適用場景

✓ 產出含繁中字的視覺（封面、infographic、簡報、carousel）
✓ 批量生視覺一致的圖（Reference image pin 機制）
✓ 想把生圖整合進自動化內容工作流
✓ 在意品質而非速度（Image-2 慢但繁中字筆劃精準）

## 不適用

✗ 單張快速 iterate（用 ChatGPT chat 直接點較快）
✗ 純插圖無字（gemini-image-gen 較划算、快 5-10 倍）
✗ 沒有 ChatGPT Plus / Pro 訂閱（Codex 走訂閱、要 login ChatGPT）

## 上手 3 步驟

完整步驟見 references/3-step-setup.md（本文件 Part 2）：

1. `npm install -g @openai/codex@latest`
2. `codex login`（選 ChatGPT Plus / Pro）
3. 跑第一張圖：`echo "<prompt>" | codex exec --full-auto --cd <output-dir>`

## 基本命令模板

```bash
# 單張生圖（最簡）
echo "<your image prompt>" | codex exec --full-auto --cd <output dir>

# 帶 reference image（鎖風格 / 鎖人物）
echo "<prompt>" | codex exec --full-auto --cd <dir> \
  -i <reference1.png> \
  -i <reference2.png>

# 背景跑（適合 9 張 carousel ≈ 12-15 分鐘）
# Claude Code 端用 background bash + run_in_background: true
```

完整 prompt 寫法見 references/prompt-template.md（本文件 Part 3）。

## 重要 Pitfalls（一定要知道）

### 1. Native size 不可預測
Codex 內建 image_gen tool 不收 size 參數（issue #19175），生出來的 native size 是 random（觀察過 1024×1536 / 1122×1402 / 972×1619 等）。

**Workaround**: 用 sips --resampleWidth/Height + 後 center crop 正規化（**禁用** sips -z H W、會強制變形）。

### 2. 跨張 chrome 飄
連續生 9 張時，page number 格式 / kicker 位置會在不同 call 之間漂移。

**Workaround**: 每張 prompt 重貼完整 chrome spec、不靠「像前一張」conversation reference。

### 3. Hero visual 自動長英文字
Image-2 在生 hero 場景時會自動加英文字（即便 prompt 沒要求）。

**Workaround**: prompt 結尾明寫「Only the verbatim strings above may appear in the image. No additional text on props, signs, or background.」

## 進階：跟 Claude Code 完整串接

要做到 Claude Code 自動 orchestrate（寫 prompt pack → 調 Codex → QA review → iterate）的完整 pipeline：

1. 在你的專案 cwd 寫 codex-prompt-pack.md（master spec）
2. 寫 codex-instruction.txt（driver、5-10 行）
3. Claude Code 用 Bash tool 跑：
   ```bash
   cat codex-instruction.txt | codex exec --full-auto --cd <cwd> -i <ref1> -i <ref2>
   ```
4. Codex 自己讀 prompt pack、跑 image_gen、self-QA、iterate
5. Claude Code 收回交付物、跑 21-point QA review

## License

MIT — 自由使用、修改、商用。
```

---

# Part 2 — 3 步驟設定（references/3-step-setup.md）

## Step 1: 安裝 Codex CLI

```bash
npm install -g @openai/codex@latest
```

驗證版本：

```bash
codex --version
# 應顯示 0.125+
```

如果你已經裝過舊版、強制升級：

```bash
npm install -g @openai/codex@latest --force
```

## Step 2: 用 ChatGPT 帳號登入

```bash
codex login
```

會跳出瀏覽器、用你 ChatGPT Plus / Pro 帳號登入。

驗證登入狀態：

```bash
codex login status
# 應顯示 "Logged in using ChatGPT"
```

**重點**：這條路用的是你的 ChatGPT 訂閱 quota（不是 OpenAI API key、不另計費）。生圖會走 ChatGPT Plus 的 5 小時 rolling window quota。

如果你顯示 "Logged in using API key" → 走的是 API 計費 path、跟這個 skill 預設不同。可以改用：

```bash
codex logout
codex login  # 選 ChatGPT 而不是 API key
```

## Step 3: 跑第一張圖（測試 setup）

開一個新資料夾當輸出位置：

```bash
mkdir ~/test-codex-image && cd ~/test-codex-image
```

跑最簡單的命令：

```bash
echo "Generate a 1024x1280 portrait illustration of a cozy home office with warm lighting, flat line-color editorial style, paper texture background. Output PNG only, no text in image." | codex exec --full-auto --cd .
```

跑完看資料夾內就有 PNG 出現。

驗證尺寸：

```bash
sips -g pixelWidth -g pixelHeight *.png
```

## 進階：reference image 鎖風格 / 鎖人物

如果你要做**整套 carousel** 或**多張一致風格**的圖：用 `-i` 傳 reference image。

```bash
echo "<prompt>" | codex exec --full-auto --cd . \
  -i ~/path/to/avatar-baseline.png \
  -i ~/path/to/style-baseline.png
```

`-i` 可以重複多次、最多傳 4-5 張 reference。

Image-2 會盡量保持與 reference 一致的風格 / 五官。

## 你接下來該知道的

### Native size 規則
Image-2 的尺寸限制：
- 兩邊都必須是 **16 的倍數**
- max edge ≤ 3840
- total pixels 介於 655,360 ~ 8,294,400

常用 valid 尺寸：
- 1024×1024（square）
- 1024×1280（4:5 portrait）
- 1088×1360（4:5 portrait, 跟 IG 投放規格 1080×1350 最接近）
- 1024×1536（2:3 portrait）
- 1536×1024（3:2 landscape）

### ChatGPT Plus quota
- 5 小時 rolling window + 每週配額
- 9 張 carousel 約耗 170K tokens / 12-15 分鐘
- 一天連跑多個 carousel 容易撞 quota、建議至少間隔 1 小時

### Codex CLI 現有限制
- Built-in image_gen tool **不收 size 參數**（issue #19175 OPEN）
- → native size 不可預測、需要後處理 normalize（見 Part 3 末段）

## 故障排除

### "The 'gpt-X.X' model requires a newer version of Codex"
你的 Codex CLI 太舊。`npm install -g @openai/codex@latest --force` 升級到最新。

### "You've hit your usage limit"
ChatGPT Plus 5 小時 rolling quota 用完了。等 reset 時間（error 訊息會給）或升級 Pro。

### Multi-line prompt 失敗（"No prompt provided via stdin"）
不要把 multi-line prompt 直接當 `codex exec` 的 argument。**永遠用 stdin pipe**：

```bash
# GOOD
cat my-prompt.txt | codex exec --cd . --full-auto

# BAD (shell 會斷行壞掉)
codex exec --cd . --full-auto "line 1
line 2
line 3"
```

### Codex 想動 cwd 外的檔案
Codex 預設 sandbox `workspace-write`（只能寫 cwd）。但偶爾會嘗試動 `~/.codex/config.toml` 或其他外部檔。

**安全建議**：每次 Codex session 結束後跑：

```bash
cd ~ && git status --short
```

確認沒有越權修改。

---

# Part 3 — Prompt Template（references/prompt-template.md）

依場景複製、替換 `{{ }}` 變數、跑 `codex exec`。

## 場景 A：封面圖（社群、簡報、Blog hero）

```text
You are an editorial illustrator. Generate a 1024x1280 portrait illustration.

STYLE:
- Flat line-color editorial illustration
- Warm color palette (no AI gradient)
- Paper texture background, subtle warm spotlight
- Background single warm white #FDFCF9

SUBJECT:
{{your scene description, e.g. "A person sitting at a wooden desk with a closed laptop, soft window light from the left, plants on the desk"}}

TEXT OVERLAY (render exactly, no other text in image):
- Top-left kicker: "{{KICKER}}" UPPERCASE letter-spacing 2px, 24px, weight 800, color #D4623B
- Center H1: "{{你的標題}}" weight 900, max 14 Chinese characters, color #0F172A
- Bottom-right page: "01 / 09" 24px regular, color #64748B (only if you need page number)

CONSTRAINTS:
- Only the verbatim strings above may appear in the image
- No emoji, no QR code, no URLs, no fake buttons
- No additional auto-generated text on props, signs, or scenery
- No watermark, no logo, no brand mark
```

## 場景 B：3-card infographic（功能拆解 / 三點對比）

```text
[同 STYLE 同 CONSTRAINTS as 場景 A]

LAYOUT: horizontal 3-card grid, equal size, equal spacing
- Card 1:
  - icon: {{描述 icon 1}}
  - label: "{{標題 1}}" weight 700
  - support: "{{說明 1}}" weight 400
- Card 2:
  - icon: {{描述 icon 2}}
  - label: "{{標題 2}}"
  - support: "{{說明 2}}"
- Card 3:
  - icon: {{描述 icon 3}}
  - label: "{{標題 3}}"
  - support: "{{說明 3}}"

H1 above the cards: "{{你的主標}}" max 14 Chinese characters
```

## 場景 C：Compare 比較頁（before vs after / 對比）

```text
[同 STYLE 同 CONSTRAINTS]

LAYOUT: left-right compare, two columns equal width
- LEFT (label "BEFORE" small caption above):
  - {{描述 BEFORE 視覺}}
- RIGHT (label "AFTER" small caption above):
  - {{描述 AFTER 視覺}}

H1 above: "{{你的主標}}" max 14 Chinese characters
Footer takeaway pill: "{{takeaway}}" max 18 Chinese characters
```

## 場景 D：簡報 hero slide（單張大圖、無 carousel chrome）

```text
[同 STYLE]

LAYOUT: full-bleed hero
SUBJECT: {{你的場景 / 角色 / 道具描述}}
TEXT (only if needed):
- Title: "{{標題}}" max 18 Chinese characters

CONSTRAINTS: [同上、額外允許]
- {{若需要更大留白讓你後製文字、加: "Leave 30% of the bottom area as clean negative space for additional copy"}}
```

## 通用注意事項

### 1. 每張 prompt 都重寫完整 spec
**不要靠 conversation reference**——Image-2 跨 call 的「記憶」極不穩定。即便連續生 9 張、每張的 prompt 都要重貼完整 STYLE / CONSTRAINTS。

### 2. Verbatim 文字要明確
- ✓ "Render exactly: '我把 Codex 變成 Claude Code 的生圖外掛'"
- ✗ "標題是: 我把 Codex 變成 Claude Code 的生圖外掛"

### 3. 明確禁止額外文字
**Pitfall 1: hero visual 自動長英文字** — Image-2 會在 props / signs / 背景自動加英文字（即使你沒要求）。

**Workaround**: prompt 結尾**強制加**：
> "Only the verbatim strings above may appear in the image. No additional text on props, signs, scenery, or background."

### 4. 指定 valid native size
- 都必須是 16 的倍數
- 4:5 portrait 推薦：**1024×1280** 或 **1088×1360**
- 1080×1350（IG 投放規格）**不是 valid native**——必須生 1088×1360 後 center crop 4px 邊到 1080×1350

### 5. 生完後處理（normalize 到目標尺寸）

```bash
W=$(sips -g pixelWidth raw.png | tail -1 | awk '{print $2}')
H=$(sips -g pixelHeight raw.png | tail -1 | awk '{print $2}')

if [ $((W*1350)) -lt $((H*1080)) ]; then
  # native 更窄高 → resize width 到 1080 保 aspect
  sips --resampleWidth 1080 raw.png --out tmp.png
else
  # native 更寬 → resize height 到 1350 保 aspect
  sips --resampleHeight 1350 raw.png --out tmp.png
fi
sips -c 1350 1080 tmp.png --out final.png  # center crop
rm tmp.png
```

**禁用** `sips -z 1350 1080`（強制變形不保 aspect、會把人臉拉橢圓）。

## Avatar pin（連續多張要保持人物五官）

```bash
echo "<prompt 內必寫: 'Preserve the exact same face, glasses shape, hair, skin tone as reference image 1. Only clothing, pose, scene may vary.'>" | \
  codex exec --full-auto --cd . \
  -i <avatar-baseline.png>
```

Reference image 是「五官鎖」、不是「整體 copy」——服裝、姿勢、場景仍可變。

## 進階：跟 Claude Code 自動串接

讓 Claude Code 端的 Bash tool 直接 fire codex exec：

```bash
# 在 Claude Code 對話中：
cat codex-instruction.txt | codex exec --full-auto --cd <cwd> \
  -i <ref1> -i <ref2> 2>&1 | tee /tmp/codex.log
```

加 `run_in_background: true`（9 張 carousel 約 12-15 分鐘、超過 foreground 10 分鐘 timeout）。

完成後 Claude Code 接 Phase 4 review（你自訂的 QA rubric）+ deliver final output。

---

## License

MIT — 自由使用、修改、商用。

如果這個 skill 對你有幫助、來追蹤 [@be.ai.curator](https://www.threads.com/@be.ai.curator) 看更多 AI 工作流實戰。