# Idea file：在 Claude Code 裡一句話生圖（走 Codex CLI，免 API key）

> 這是一份 idea file：只寫目標、約束、取捨與驗收標準，不含完整實作。把它餵給你的 coding agent，讓 agent 依你的環境重建這條流程。
> This is an idea file: goal, constraints, tradeoffs and acceptance criteria, no implementation. Feed it to your coding agent to rebuild the pipeline for your own setup.

- 源文章（含 SKILL.md 核心內容與逐步過程，完整版在文末 zip）：https://paulkuo.tw/articles/claude-code-codex-imagegen/
- 源文章 raw Markdown：https://paulkuo.tw/articles/claude-code-codex-imagegen.md
- 作者：Paul Kuo（paulkuo.tw）
- 整理日期：2026-10-08。工具版本與模型名是源文章當時的狀態，重建時以當下版本為準，流程邏輯不變。

## 一句話目標

在 Claude Code 對話裡說一句「生圖」，圖就直接落到專案的 `./images/` 目錄：不切視窗、不手動下載、不用 OpenAI API key。

## 核心約束

- 授權走 Codex CLI 的 ChatGPT 帳號登入（`codex login`），不是 API key 計費；免費 ChatGPT 帳號也能用，差別在生成品質。
- 圖片必須落在使用者指定的專案路徑，不落在暫存區。
- 原專案環境是 macOS；桌面 App 與 Cowork 版需要 osascript 橋接（Control your Mac MCP）。

## 關鍵流程（重建的核心）

使用者描述需求 → Claude 整理成完整 prompt → 呼叫 Codex CLI → Codex 的 image generation tool（gpt-image-2）→ PNG 直接落檔。

最小可行指令（先手動跑通這條，再談包裝）：

```bash
mkdir -p ./images
codex exec -C "$(pwd)" -s workspace-write --skip-git-repo-check "請使用 image generation tool 生成：[圖片描述]，存成 ./images/[檔名].png"
```

## 已做的取捨（與理由）

- 先跑最小可行版本（上面那條指令），跑通再包成 Skill。不要一開始就把 CLI、Skill、MCP、Cowork 全部混在一起，出錯會不知道在哪一層。
- 兩個 Skill 分開做：gen-image-cli（Claude Code 環境，Bash 直接呼叫）、gen-image-app（桌面 App 與 Cowork 環境，走 osascript 橋）。
- SKILL.md 的要點：description 寫清楚觸發詞，讓模型知道何時載入；allowed-tools 限縮到必要工具。

## 驗收標準

- 在專案目錄對 Claude 說「生圖一張…存成 ./images/x.png」，檔案出現在該路徑，全程不開瀏覽器。
- 原專案實測：約 1 分鐘出一張 1254×1254、約 2 MB 的 PNG。

## 已知坑（重建時大概會踩到）

- `Failed to create session: Operation not permitted`：`~/.codex` 目錄權限問題，`sudo chown -R $(whoami) ~/.codex` 解決。
- 圖片落錯位置：`-C "$(pwd)"` 以執行當下的目錄為工作目錄，先 cd 到專案再跑。

## 刻意不做的事

- 不直接接 OpenAI API（要另外管 key 與計費）。
- 不做圖片後製管線；這條流程只負責「說一句話、拿到落檔的圖」。