Codex OAuth で GPT Image 2 によるネイティブ画像生成

01PR #1002 以前の問題

旧 create_image は API キーでしか動作しなかった

PR #1002 以前、GoClaw の create_image ツールは credentialProvider インターフェース経由でプロバイダーを検索していました — つまりプロバイダーは APIKey() string と APIBase() string の 2 つのメソッドを実装している必要がありました。CodexProvider は OAuth フローを使用しているため、これら 2 つのメソッドを意図的に実装していません。トークンは refresh_token グラントで更新されます（internal/oauth/token.go を参照）。デフォルトのバックエンド URL https://chatgpt.com/backend-api（定数 DefaultProviderAPIBase）は内部専用であり、ツール層が触れることのできるクレデンシャルサーフェスには含まれません。

その結果: ChatGPT Plus/Pro サブスクリプションにはクォータに gpt-image-2 が含まれており、ウェブ（chatgpt.com/images）や Codex CLI からは呼び出せるのに、GoClaw のエージェントからは APIKey()/APIBase() チェックで create_image がブロックされるため呼び出せませんでした。ユーザーは並行する API キーパスを使わざるを得ませんでした。最も人気だったのは OpenRouter 経由の Gemini Nano Banana 2 で、その理由は:

• ほとんどのユースケース（ポスター、サムネイル、イラスト）で十分なクオリティ。
• OpenRouter なら OpenAI / Google の API キーを個別管理せず、1 つのキーで多くの画像生成モデルを使用できる。
• 画像ごとの従量課金 — 第 2 のサブスクリプションは不要。

GoClaw のデフォルトチェーン imageGenModelDefaults は各プロバイダーを 1 つのモデルにマッピングしています: openai → gpt-image-1.5、openrouter → google/gemini-2.5-flash-image（Nano Banana 2）、gemini → gemini-2.5-flash-image、minimax → image-01、dashscope → wan2.6-image、byteplus → seedream-5-0-260128。プロバイダーの優先順位は openrouter → gemini → openai → minimax → dashscope → byteplus。すべてそれぞれの API キーが必要です。

問題: ユーザーはコーディングワークフローのために ChatGPT Plus/Pro を毎月すでに支払っており、gpt-image-2 は最高品質の画像生成モデルの 1 つ — しかしそのクォータはエージェントから使えず、眠ったままでした。

プロンプトエンジニアリングの分散

gpt-image-2 コミュニティは X/Twitter でプロンプトテンプレートを散発的に共有しています。EvoLinkAI が awesome-gpt-image-2-prompts リポジトリ（約 370 ケース）を管理していますが、データは README とツイートリンクの形式で、検索エンジンはありません。エージェントがそれを活用するには手動で読み込んでフィルタリングする必要があります。

02OAuth 向けネイティブ画像アーキテクチャ

PR #1002 は internal/providers/native_image.go に新しいインターフェースを追加します。エンドツーエンドのフローは以下の図のとおりです。

実際のコードは短いインターフェースです。

type NativeImageProvider interface {
    GenerateImage(ctx context.Context, req NativeImageRequest) (*NativeImageResult, error)
}

create_image ツールは MediaProviderChain 経由でプロバイダーを検索します。チェーンエントリが Codex OAuth の場合、生のプロバイダーオブジェクトが params["_native_provider"] に渡されます。callProvider 内では:

if rawProvider, ok := params["_native_provider"]; ok {
    if np, ok := rawProvider.(providers.NativeImageProvider); ok {
        // ネイティブパス — APIKey/APIBase 不要
        return np.GenerateImage(ctx, ...)
    }
}
if cp == nil {
    return error("provider does not expose API credentials")
}
// openai、gemini、minimax、dashscope、byteplus、openrouter のクレデンシャルパス

ネイティブチェックは cp == nil ガードの前に実行されます。OAuth プロバイダーは意図的にクレデンシャルを公開しません。順序を逆にすると、リクエストは誤った方向を指すエラーで失敗します —— ユーザーは「クレデンシャル不足」と見てクレデンシャル設定に走りますが、本当の原因はネイティブパスの間違いです。

2 層ゲート

image_generation ツールは以下の 2 つの条件が両方満たされた場合にのみリクエストに付与されます。

1. プロバイダーケーパビリティ: プロバイダーが CapabilitiesAware を実装し、Capabilities().ImageGeneration == true であること。Codex プロバイダーは OpenAI Responses API が image_generation ツールをサポートしているため true にハードコードされています。
2. エージェント設定: AgentConfig の AllowImageGeneration フィールド（デフォルト true）。管理者は other_config.allow_image_generation: false を設定して画像生成を禁止できます。

loop_tool_filter.go::buildFilteredTools のロジック:

if l.allowImageGeneration {
    if aware, ok := l.provider.(providers.CapabilitiesAware); ok {
        if aware.Capabilities().ImageGeneration {
            toolDefs = append(toolDefs, imageGenToolDef)
        }
    }
}

imageGenToolDef はフラグ {Type: "image_generation"} だけ — name も parameters スキーマもありません。通常の function calling ではクライアントがすべてを定義する必要があります（例: {type: "function", function: {name, description, parameters}}）が、ここで image_generation は Codex Responses API の組み込みツールです — サーバーがスキーマを付与し、ハンドラーを実行します。クライアントはセンチネルで有効化するだけで済みます。

03Codex Responses API ワイヤーフォーマット

エンドポイント: POST {apiBase}/codex/responses

map[string]any{
    "model":        "gpt-5.4",  // 親 LLM（画像モデルではない）
    "stream":       true,        // 必須 — false は HTTP 400 で拒否される
    "store":        false,
    "instructions": "Generate an image matching the user's description using the image_generation tool. Return only the image; do not describe it in text.",
    "input":        []any{...user message...},
    "tools": []map[string]any{{
        "type":          "image_generation",
        "action":        "generate",
        "model":         "gpt-image-2",   // 画像モデルはここ
        "output_format": "png",
        "size":          "1024x1024",
    }},
    "tool_choice": map[string]any{"type": "image_generation"},  // force tool call
}

注意点:

• stream: true は必須 — 非ストリーミングは Stream must be set to true で拒否されます。
• instructions は空でなく明確な値が必要です。空のままにするとモデルがツールを呼び出す代わりに説明テキストを返す可能性があります。
• tool_choice は image_generation を強制する必要があります。そうしないとモデルがツールをスキップする可能性があります。
• 同じリクエストに 2 つのモデルが存在します: model（親 — gpt-5.4）と tools[0].model（画像 — gpt-image-2）。混同すると曖昧な API エラーが発生します。

レスポンスのパース

メインパスは SSE ストリームです（stream:true が必須のため）。エンドツーエンドのフロー:

コードにはまだ非ストリーミング JSON パースのフォールバックがあります。サーバーが予期せず生の JSON オブジェクト（data: 行でなく）を返した場合、parseNativeImageResponse は output[] を走査し、type == "image_generation_call" を見つけて result を base64 デコードします。stream:false を設定してこのパスをトリガーすることはできません — リクエストは先に HTTP 400 で拒否されるためです。

SSE パス: data: 行をスキャンし、2 つのイベントを優先します。

• response.output_item.done — 画像アイテム準備完了、event.Item.Result（base64）+ OutputFormat を取得。
• response.completed — 最終利用トークン、アイテムが未取得の場合は event.Response.Output[] を再度走査。

for line := range bytes.SplitSeq(data, []byte("\n")) {
    if !bytes.HasPrefix(line, []byte("data: ")) { continue }
    payload := line[len("data: "):]
    if bytes.Equal(payload, []byte("[DONE]")) { break }
    // ... イベントをアンマーシャル、event.Type で switch
}

04モデルホワイトリスト + チェーン設定

サーバーサイドのホワイトリスト

var allowedImageModels = map[string]bool{
    "gpt-image-2":   true, // デフォルト — 最新品質
    "gpt-image-1.5": true, // レガシーフォールバック
}

ValidateImageModel は他の値（例: dall-e-3）をプロバイダーレベルで即座に拒否します — アップストリームに黙って拒否させません。ユーザーはチェーンエントリパラメーター image_model でモデルを選択します。この値は NativeImageRequest.ImageModel に渡され、検証されてから Responses API リクエストの tools[0].model に付与されます。

チェーン設定

デフォルトの MediaProviderChainEntry:

Timeout    int  // 秒、デフォルト 600（10 分 — 画像/動画生成は低速）
MaxRetries int  // デフォルト 1（画像生成はリトライで成功することはまれ）

タイムアウトは 120s から 600s に引き上げられました。gpt-image-2 は実際に 30〜180s かかることがあるためです。タイムアウトが途中で発生してもアップストリームのリクエストが引き続き実行されることがあるため、リトライはほとんど効果がありません。そのため MaxRetries はリトライループでエラーを隠すのではなく早期に表面化させるため、2 から 1 に削減されました。

UI は ui/web/src/pages/builtin-tools/media-provider-params-schema.ts のスキーマを使用して設定フォームをレンダリングするため、管理者はテナントとツールごとに調整できます。

05出所情報: PNG tEXt チャンク + キャプション UI

create_image がファイルを保存するとき、pngEmbedPrompt は PNG のバイトストリームを書き換え、IEND の直前に tEXt チャンク Description を挿入します。tools→agent のインポートサイクルを避けるため、この関数は tools/png_embed.go に配置されています。

Description = <ユーザーが送信したプロンプト>

PNG tEXt チャンクの標準フォーマットとバイトストリームへの挿入位置:

関数は入力に PNG シグネチャ（8 バイトマジック）がないか IEND チャンクが見つからない場合は静かにスキップします。失敗モード: 元のバイト列をそのまま返し、エラーなし。

結果: 元のプロンプトがダウンロードファイルに同行します。exiftool image.png（Description フィールド）または PNG メタデータビューアーで読み返せます。監査、類似画像の再生成、プロンプトのデバッグがすべて簡単になります。

UI は MediaGallery 内の画像の下にキャプションをレンダリングします: ミュートイタリック、2 行クランプ、ホバー時に全プロンプトを表示するツールチップ。ファイルは次のパスに保存されます: {workspace}/generated/{YYYY-MM-DD}/image_{hint}_{timestamp}.png。

06スキル gpt-image-2-pro-max: Skill システム経由のプロンプトレジストリ

GoClaw コントリビューターの Richard Ng 氏によるスキル gpt-image-2-pro-max は MIT ライセンスのオープンソースです。コーパス内の 3,000 以上のプロンプトテンプレートは Twitter/X クリエイターのものです。スキルは検索を高速化するためにインデックスを作成するだけで、返される各プロンプトには元の著者が引用され、コーパスは上流の EvoLinkAI/awesome-gpt-image-2-prompts リポジトリにクレジットを記載しています。スキルは Claude Code スキル規約に準拠してパッケージ化されており、GoClaw は互換性のある Skill システムを搭載しているため、同じスキルディレクトリが両方で動作します。

Anatomy

コーパス: コミュニティが審査した 3,238 のプロンプトが https://gpt-image-2-prompts.goclawoffice.com でホストされています。タグは 10 のファセットで推定されます: subjects、styles、lighting、cameras、moods、palettes、compositions、mediums、techniques、usecases。各レコードにはプロンプト本文、Twitter/X の帰属、参照画像が含まれます。エンドポイントは IP レート制限があり、フェアユースに配慮しています。

エージェントが呼び出す CLI インターフェース:

python scripts/search.py "luxury shoe ecommerce ad cream pastel" -n 5
python scripts/search.py "perfume bottle" --shape ecommerce -n 3
python scripts/search.py "neon ui" --persist plans/neon-refs.md

最初のクエリのサンプル出力（3 件表示、プロンプト本文は省略）:

#1  bm25=-10.76  shape=ecommerce  source=None
  id    : 64dp29km
  title : E-commerce Main Image - Luxury Perfume Ad on Marble Vanity
  author: @MiguelMaestroIA
  tweet : https://x.com/MiguelMaestroIA/status/2047555836252151831
  image : https://gpt-image-2-prompts.goclawoffice.com/img/64dp29km_0
  imgid : 64dp29km_0
  tags  : cameras=1-1 | compositions=negative-space | moods=dreamy,edgy,elegant,intense,luxurious,minimal | palettes=crimson-burgundy,duotone,monochrome | styles=cinematic,editorial | subjects=product | techniques=parameterised-template,text-overlay-explicit | usecases=ecommerce-main-image,poster-flyer
  prompt:
    A luxury cosmetics advertisement poster featuring a single upright {argument name="product type" default="lipstick"} centered on a glossy black cube pedestal against a rich monochrome {argument name="background color" default="deep crimson red"} studio background. The product is a bold satin-finish {argument name="product shade" default="true red"} lipstick with the bullet fully extended, dramatic...

#2  bm25=-9.85  shape=  source=None
  id    : z9q36mnc
  title : Futuristic Bionic Super Shoe
  author: @Ericool 🇲🇾
  tweet : https://x.com/EricoolWong/status/2048353098897453286
  image : https://gpt-image-2-prompts.goclawoffice.com/img/z9q36mnc_0
  imgid : z9q36mnc_0
  tags  : cameras=low-angle | moods=energetic,futuristic,intense,luxurious | palettes=gold-black | styles=cinematic | subjects=fashion-item,product | techniques=parameterised-template
  prompt:
    Extreme futuristic {argument name="subject" default="cheetah bionic super shoe"}, hybrid of supercar and running sneaker, aggressive mechanical structure, layered carbon fiber, glowing energy core, dynamic speed trails, {argument name="colors" default="black gold"} luxury finish, dramatic low angle, cinematic lighting, high-end sports ad, ultra detailed, 8k

#3  bm25=-9.82  shape=ecommerce  source=None
  id    : 0zjvnji7
  title : Vitamin C Skincare Ad
  author: @Gem Alpha
  tweet : https://x.com/Gemalpha_88/status/2046796479562678589
  image : https://gpt-image-2-prompts.goclawoffice.com/img/0zjvnji7_0
  imgid : 0zjvnji7_0
  tags  : cameras=1-1 | moods=dreamy,edgy,elegant,luxurious,minimal,warm-emotional | palettes=earth-tones | styles=photorealistic | subjects=abstract,product | techniques=aspect-explicit,parameterised-template
  prompt:
    Create a clean luxury skincare product advertisement in a square 1:1 layout with a warm beige studio background and strong natural sunlight casting soft palm-leaf shadows across the wall. Place 1 amber glass dropper bottle on the left-center, standing upright on a round cream stone pedestal. The bottle has a glossy gold collar and a matte white rubber dropper top. Add a white rectangular label wit...

(3 matched, showing 3)

出力は BM25 でランク付けされ、prompt_body、tags.{moods,palettes,subjects,...}、author、tweet、image を含みます。主なフィルター: --shape、--has-image、-n、--full、--persist。

07Web ダッシュボードからのセットアップ

GoClaw は Core / Capabilities / System でグループ化されたサイドバーを持つ Web ダッシュボードを提供します。このセットアップには 4 つのセクションが必要です: Agents（Core）、Skills（Capabilities）、Providers + Builtin Tools（System）。最小セットアップではエージェント 1 つだけで十分です — Step 2a のグローバル Provider Chain により、すべてのエージェントが create_image ツールを使用できます（Step 2b の read_image 設定はオプションで、ネイティブビジョン搭載モデルはスキップ可）。

Step 1 — Codex プロバイダーを接続する

サイドバー → System / Providers → Add Provider ボタン。Add Provider モーダルで ChatGPT Subscription (OAuth) を選択し、Account Alias（例: openai-codex）を保持または編集、必要に応じて Display Name を入力して Connect OpenAI Account をクリックします。システムが新しい OAuth タブを開き、ChatGPT アカウント（Plus / Pro / Team / Enterprise いずれも可）へのサインインとアクセス許可を求めます。

サインイン後、ブラウザは http://localhost:1455/auth/callback?code=...&state=... のようなコールバックにリダイレクトされます。リモート/VPS ホストでブラウザが localhost に接続できない場合は、アドレスバーの URL 全体をコピーしてモーダルのコールバックフィールドに貼り付け、Submit をクリックします。Providers リストに新しいプロバイダーが Connected ステータスで表示されれば完了です。

Step 2a — create_image を有効化 + 設定する

サイドバー → System / Builtin Tools（ルート /builtin-tools）→ Media タブ → Create Image。Enabled フラグはデフォルト OFF（cmd/gateway_builtin_tools.go:55 のシードデータを参照）— まずトグルを ON にします（テナント全体のマスタースイッチ）。次に Configure をクリックして Provider Chain モーダルに進みます。

Create Image — Provider Chain モーダルでフォールバックプロバイダーの順序を設定できます。最初の enabled エントリが最初に試行されます。最小セットアップ: Codex Plus エントリを 1 つ追加し、モデル GPT-5.4、Timeout 600s（複雑なプロンプトの場合、画像生成に時間がかかることがある）、Retries 1、最も重要なのは Image model で Default · gpt-image-2 (recommended) を選択。Save をクリック。OAuth クォータが枯渇した際のグレースフルデグラデーションのため Add Provider でフォールバック（例: OpenAI API キー）を追加することもできます。

Step 2b — read_image を有効化 + 設定する （オプション）

エージェントのメインモデルがすでにネイティブビジョンを持つ場合（Qwen3.6-Plus など）はスキップしてください — ランタイムがインラインモードにフォールバックし、画像バイナリをメッセージに添付して LLM が直接読み取ります。テキストのみのモデルを使用する場合、またはコスト/レイテンシを最適化するためにビジョンプロバイダーを推論モデルから分離したい場合は設定が必要です。

同じ /builtin-tools ページ → Media タブ → Read Image。Enabled トグルをオンにします（デフォルト OFF）。ツール名の横にある req バッジに注意してください — "requires"（依存関係）の略です。ホバーすると vision_provider 要件が表示されます: トグルが意味を持つには Step 1 で少なくとも 1 つのビジョン対応プロバイダー（Gemini、OpenAI、Anthropic、OpenRouter、dashscope qwen-vl など）が登録されている必要があります — そうでなければ、ツールは実行時に "No vision provider configured" エラーをスローします。

有効化後、Configure をクリック → Read Image — Provider Chain モーダル。スクリーンショットのサンプルセットアップ: OpenRouter エントリ 1 つ、モデル google/gemini-2.5-flash-image、Timeout 120s（ビジョン呼び出しは通常高速で 600s は不要）、Retries 3（ビジョン呼び出しは安価でプロバイダーが不安定な場合のリトライは安全）。これは read_image 専用のチェーンであり、create_image とは共有されません。

Step 3 — エージェントを作成する

サイドバー → Core / Agents → New Agent。最小フィールド: Name、Provider、Model（例: Tiểu Hổ + qwen3.6-plus、または画像を読み取りスキルを実行できる十分に賢いモデル）。保存するとエージェントがリストに表示されます。このエージェントの役割は推論を実行することです: ブリーフを分析し、画像を読み取り、コーパスを検索し、プロンプトをリファクタリングして、create_image ツールを呼び出します。

Step 4 — スキル gpt-image-2-pro-max をアップロードする

上流からスキルをクローンして ZIP 圧縮:

git clone https://github.com/therichardngai-code/gpt-image-2-pro-max /tmp/g2pm
cd /tmp/g2pm/.claude/skills/gpt-image-2-pro-max
zip -r ~/Desktop/gpt-image-2-pro-max.zip .

git clone https://github.com/therichardngai-code/gpt-image-2-pro-max $env:TEMP\g2pm
Set-Location $env:TEMP\g2pm\.claude\skills\gpt-image-2-pro-max
Compress-Archive -Path * -DestinationPath $HOME\Desktop\gpt-image-2-pro-max.zip -Force

サイドバー → Capabilities / Skills → Upload Skill → ZIP ファイルをドロップ → ダッシュボードが SKILL.md フロントマターをパースし name + description を取得、DB にスキルレコードを保存（version は DB が自動採番する整数で、アップロードのたびにインクリメント — フロントマターからは取得しない）。スキルが Enabled トグル付きでリストに表示されます。

最後に、作成したエージェントにスキルをグラントします: Agent detail → Skills セクション → gpt-image-2-pro-max を granted にトグル。ローダーが次のターンからエージェントのシステムプロンプトに SKILL.md を注入します — 再起動不要。このスキルは プロンプトエンジニアリングパイプライン — エージェントに、ブリーフの診断、3,238 プロンプトのコーパス検索、ムードに合ったテンプレートの選択、スロットのリファクタリングと解決、そして最後に磨かれたプロンプトで create_image を呼び出す方法を教えます。

1 ターントレース（セットアップ後）

ユーザーブリーフ: "poster cao điểm Tết với cáo đỏ Việt Nam, style infographic"

実際の実行からの詳細なビジュアルトレース: PR #1002 · UX trace。

08ワークフロー: GoClaw で画像を生成する

"GoClaw ユーザーの皆さん — GPT Image 2 を使ってプロンプト 1 つで画像を生成できます。ベース画像をアップロード → エージェントがプロンプトを最適化 → GoClaw 内で画像を生成。

P.S. メインモデルは Qwen3.6-Plus（+ read_image）、画像生成は GPT_Image_2（create_image）で設定しました。" — 著者 (Richard Ng)

これは著者自身が共有したワークフローです: 作りたい画像をアップロードして数個の説明キーワードを入力するだけ（例: "ecommerce 広告ポスターを作成"）。残りはエージェントがすべて行います — アップロード 1 回で完結します。

GoClaw の最小セットアップ

ワークフロー: ブリーフ → 完成画像

09ベストプラクティス

このコンボを運用する際の最重要ヒント 2 つ:

1. ブリーフが詳細なほど、エージェントの検索精度が上がる。 ユーザーが "red fox" とだけ入力すると、エージェントは "red fox" で検索し、無関係なテンプレートが大量に返ります（森の狐、カートゥーン狐、リアル狐など）。ブリーフに shape（poster / infographic / portrait / ad…）、mood（festive / moody / minimal…）、palette（red-gold / pastel / neon…）のキーワードを追加すれば、検索結果がインテントに大幅に絞り込まれます。例: "Tet poster, Vietnamese red fox, infographic style, festive red-gold palette" → エージェントの検索クエリに infographic festive red-gold が含まれ、適切なテンプレートへのフィルタリングが可能になります。
2. タイムアウトを 600s 未満に下げないこと。 複雑な画像の生成（例: テキストを多く含む infographic）は通常サーバー側で 4〜8 分かかります — これはエラーではなくリアルな数値です。旧デフォルトの 120s × 2 retries は処理途中で切断されることが多く（context deadline exceeded）、実行を台無しにしていました。PR #1002 で 600s × 1 retry に変更しました: 待機時間は長くなりますがサーバーに十分な時間を与えられます。リトライは 1 回のみ — タイムアウト後のリトライはコストが 2 倍になる割に成功することはほとんどないためです。オペレーターは必要に応じて変更できますが、600s を下回ると設定しないでください — 旧来の失敗モードが再発することはほぼ確実です。

10技術サマリー

ファイルリファレンス

スキルバックエンド

スキルはダッシュボード経由でアップロードします（Section 07 · Step 4 参照）。scripts/search.py は外部コーパスホストを呼び出します。BM25 + タグブーストランキングはサーバー側にあり、GoClaw コアには含まれません。