OpenClaw 接入 gpt-image-2 完整教程: 2 種方案 + 10 分鐘上手

一句話結論: 把 gpt-image-2 接入 OpenClaw 有兩條路徑——方案 A 是用 APIYI 的 GPT-Image Skills，5 分鐘即可完成，適合 Codex CLI/Cursor 等支持 Skills 的客戶端；方案 B 是用 OpenAI 對話兼容模式 + 官逆模型 gpt-image-2-all，按次計費 （$0.03/次，折扣前），最適合 OpenClaw 通過 WhatsApp/Telegram/Discord 等消息平臺直接生圖的場景。

OpenClaw （github.com/openclaw/openclaw） 是 2026 年最受關注的開源自主 AI Agent 之一，支持 WhatsApp、Telegram、Slack、Discord、iMessage、Feishu、微信、企業微信等 20+ 消息平臺。它本身模型無關 （model-agnostic），通過 OpenAI 兼容協議接入第三方 API 服務，這給 gpt-image-2 這種頂級圖像模型提供了完美的整合入口。

本文從架構選型到落地配置，完整講清楚兩種接入方案的差異，並給出可直接複用的 openclaw.json 配置代碼。

一、爲什麼 OpenClaw 接 gpt-image-2 需要專門的方案

很多用戶的第一反應是: "OpenClaw 不是已經支持 OpenAI 了嗎，直接配置 OpenAI API Key 不就行了？" 這個想法在原理上沒錯，但在工程落地上有 3 個繞不過的問題。

1.1 直接接 OpenAI 官方 API 的三個限制

🎯 快速上手建議: 如果你已經在 OpenClaw 中接入了其他模型 （例如 Claude），只需要替換 models.providers 配置即可讓 gpt-image-2 在所有 OpenClaw 支持的消息平臺 （WhatsApp/Telegram/Discord 等） 中可用。我們建議通過 API易 apiyi.com 平臺接入，該平臺已經處理好上述三個問題，提供國內低延遲節點和按次計費方案。

1.2 OpenClaw 調用圖像生成的兩種內部機制

OpenClaw 在內部對圖像生成有兩種實現路徑:

路徑 A: 走 image_generate 工具
  - 配置: models.providers.openai.baseUrl
  - 調用: 標準 OpenAI Images API （POST /v1/images/generations）
  - 適用: gpt-image-2 / gpt-image-1 / DALL-E 3

路徑 B: 走 chat completions 工具
  - 配置: 自定義 OpenAI 兼容 provider
  - 調用: 標準 Chat API （POST /v1/chat/completions）
  - 適用: 任何能在對話流中返回圖片的"對話型圖像模型"

關鍵認知: gpt-image-2-all 是 APIYI 提供的"對話兼容版"圖像模型，它把圖像生成能力封裝在標準 chat completions 協議中，響應格式中直接返回圖片 URL。這種設計讓 OpenClaw 可以像調用普通對話模型一樣調用它，無需切換到專門的 image API。

1.3 兩種方案的本質差異

二、方案 A: 通過 APIYI Skills 接入 gpt-image-2

如果你的工作流是: 在 Codex CLI / Cursor / OpenCode / Gemini CLI 等開發工具中，調用 OpenClaw Agent 執行任務時順便生成圖片，Skills 方案是最優雅的接入方式。

2.1 Skills 方案的兩個可選模型

APIYI 在 GitHub 開源了兩個 Skills （作者: wuchubuzai2018，倉庫: expert-skills-hub）:

2.2 安裝 Skills （3 行命令）

# 1. 安裝官轉版 （推薦商用）
npx skills add https://github.com/wuchubuzai2018/expert-skills-hub --skill apiyi-gpt-image-2-gen

# 2. 或者安裝官逆版 （按次計費版）
npx skills add https://github.com/wuchubuzai2018/expert-skills-hub --skill apiyi-gpt-image-2-all-gen

# 3. 配置環境變量
export APIYI_API_KEY="sk-your-key-from-apiyi-console"

🎯 API Key 獲取: 註冊賬號後，進入"API Keys"頁面創建新的 Key，以 sk- 開頭。Key 在所有提供的服務中通用，包括官轉和官逆模型。

2.3 在 OpenClaw 中調用已安裝的 Skills

OpenClaw 通過 Agent 配置，可以在執行復雜任務時子調用已安裝的 Skills:

# openclaw 配置片段 （示意）
agents:
  - id: image-helper
    description: "圖片生成助手"
    skills:
      - apiyi-gpt-image-2-gen
      - apiyi-gpt-image-2-all-gen
    triggers:
      - keyword: "生成圖片"
      - keyword: "畫一張"

實際使用時，只需要在 OpenClaw 接入的消息平臺中（例如 Telegram）發送:

@OpenClawBot 幫我生成一張賽博朋克風格的咖啡館插圖，1024x1024

OpenClaw 會:

1. 識別觸發詞，激活 image-helper agent
2. 調用 apiyi-gpt-image-2-gen Skill
3. 通過 APIYI 平臺調用 gpt-image-2
4. 返回圖片 URL 到對話中

2.4 Skills 方案的優勢與限制

優勢:

• ✅ 複用社區維護的 Skill 代碼，不用自己寫圖像生成邏輯
• ✅ 自動處理 prompt 優化、錯誤重試、圖片格式轉換
• ✅ 與開發工具 （Codex CLI/Cursor） 原生兼容

限制:

• ❌ OpenClaw 對 Skills 的支持依賴具體 Agent 配置
• ❌ 需要 Node.js 環境
• ❌ 不支持純消息平臺 （例如純 WhatsApp 用戶） 的開箱即用調用

如果你的 OpenClaw 主要用於消息平臺，直接看方案 B。

三、方案 B: OpenAI 兼容模式接入 gpt-image-2-all

這是最適合 OpenClaw 主流場景的接入方式——通過修改 OpenClaw 的 models.providers 配置，把 APIYI 作爲自定義 OpenAI 兼容 provider 註冊進去，然後調用 gpt-image-2-all 這個對話兼容版本的圖像模型。

3.1 修改 openclaw.json 配置

OpenClaw 的核心配置文件位於 ~/.openclaw/openclaw.json （macOS/Linux） 或 %APPDATA%\openclaw\openclaw.json （Windows）。

{
  "models": {
    "providers": {
      "apiyi": {
        "api": "openai-completions"，
        "baseUrl": "https://api.apiyi.com/v1"，
        "apiKey": "sk-your-key-from-apiyi-console"，
        "models": [
          {
            "id": "gpt-image-2-all"，
            "name": "GPT Image 2 （對話兼容版）"，
            "contextWindow": 8000，
            "maxTokens": 4096，
            "capabilities": ["text"， "image_generation"]
          }
        ]
      }
    }
  }，
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

🎯 base_url 配置: 上述配置的 baseUrl 必須以 /v1 結尾。標準 endpoint 與 OpenAI 官方接口完全兼容，無需修改其他參數。

3.2 重啓 OpenClaw 並驗證

# 重啓 OpenClaw 服務 （根據安裝方式）
openclaw restart

# 或者通過 systemd
sudo systemctl restart openclaw

# 驗證 provider 已加載
openclaw models list | grep apiyi

成功輸出示例:

Provider: apiyi （status: ✓ healthy）
  Models:
    - apiyi/gpt-image-2-all （chat + image_generation）

3.3 在消息平臺中調用

配置完成後，任何接入 OpenClaw 的消息平臺都可以直接生圖。以 Telegram 爲例:

[用戶消息]
畫一張穿宇航服的小貓坐在月球表面的圖片，卡通風格

[OpenClaw 響應]
🎨 正在爲您生成圖片...
[圖片] https://files.apiyi.com/generated/xxx.png
✅ 生成完成，本次消耗 $0.03

3.4 完整的 chat completions 調用示例 （開發者參考）

如果你想從代碼層調試，以下是 OpenClaw 內部對 gpt-image-2-all 的調用方式:

import openai

client = openai.OpenAI（
    api_key="sk-your-key"，
    base_url="https://api.apiyi.com/v1"
）

response = client.chat.completions.create（
    model="gpt-image-2-all"，
    messages=[
        {
            "role": "user"，
            "content": "畫一張穿宇航服的小貓坐在月球表面的圖片，卡通風格"
        }
    ]
）

# response 中會包含圖片 URL （Markdown 格式）
print（response.choices[0].message.content）
# 輸出: ！[Generated Image]（https://files.apiyi.com/generated/xxx.png）

import os
import openai
import logging
from openai import APIError， RateLimitError

client = openai.OpenAI（
    api_key=os.environ["APIYI_API_KEY"]，
    base_url="https://api.apiyi.com/v1"，
    timeout=120.0  # 圖像生成需要更長超時
）

def generate_image_via_chat（prompt: str， max_retries: int = 3）:
    """通過 chat completions 調用 gpt-image-2-all"""
    for attempt in range（max_retries）:
        try:
            response = client.chat.completions.create（
                model="gpt-image-2-all"，
                messages=[{"role": "user"， "content": prompt}]，
                stream=False
            ）
            content = response.choices[0].message.content
            return parse_image_url（content）
        except RateLimitError:
            logging.warning（f"Rate limit， retry {attempt+1}/{max_retries}"）
            continue
        except APIError as e:
            logging.error（f"API error: {e}"）
            if attempt == max_retries - 1:
                raise
    return None


def parse_image_url（content: str） -> str:
    """從 Markdown 響應中提取圖片 URL"""
    import re
    match = re.search（r'！\[.*？\]\（（.*？）\）'， content）
    return match.group（1） if match else None


if __name__ == "__main__":
    url = generate_image_via_chat（
        "畫一張穿宇航服的小貓坐在月球表面的圖片，卡通風格"
    ）
    print（f"圖片 URL: {url}"）

四、gpt-image-2 vs gpt-image-2-all: 模型選型決策

OpenClaw 用戶最常問的問題是: 到底用官轉還是官逆？ 這取決於你的具體場景和優先級。

4.1 兩個模型的關鍵差異

4.2 不同場景的選型建議

🎯 混合策略建議: 實際項目中，我們建議開發階段使用 gpt-image-2-all 控制成本，正式上線切換到 gpt-image-2。API易 apiyi.com 平臺兩個模型共用同一個 API Key，只需要修改請求中的 model 字段即可切換，遷移成本接近零。

4.3 計費實例對比

假設一個 OpenClaw 羣機器人每天處理 100 次圖片生成請求:

關鍵洞察: 對於個人/小團隊的 OpenClaw 部署，選 gpt-image-2-all 一年能省 $5，000+，且功能差異在消息平臺場景中並不明顯。

五、OpenClaw + gpt-image-2 實戰場景示例

講完原理和配置，看幾個真實可複製的應用場景。

5.1 場景一: Telegram 羣組的圖片生成助手

配置: OpenClaw 接入 Telegram + APIYI 自定義 provider + gpt-image-2-all

用戶體驗:

[羣成員 A]
@OpenClawBot 給我畫一張週一早會的卡通插圖，要有睏倦的程序員和大杯咖啡

[OpenClawBot]
🎨 正在生成，預計 15 秒...
[圖片顯示]
✅ 已生成 （本次 $0.03）
👍 喜歡的話發我 ⭐️

配置要點:

• 在 openclaw.json 中添加 telegram channel 配置
• 設置圖片生成的關鍵詞觸發器: "畫一張" / "生成圖片" / "draw" / "create image"
• 啓用 rate limiting，避免羣成員濫用

5.2 場景二: WhatsApp 客服自動配圖

業務背景: 跨境電商客服在 WhatsApp 上回復客戶，需要快速生成商品場景圖。

配置:

{
  "agents": {
    "wa-cs-agent": {
      "channel": "whatsapp"，
      "model": "apiyi/gpt-image-2-all"，
      "system_prompt": "你是電商客服助手，當用戶詢問商品時，可以生成商品場景圖輔助說明。"，
      "tools": ["image_generate"， "knowledge_search"]
    }
  }
}

對話示例:

[客戶]
這款藍牙耳機戴起來好看嗎？

[客服 Agent]
我幫您生成一張實際佩戴場景的參考圖 👇
[圖片: 年輕人戶外慢跑佩戴藍牙耳機的場景]
您可以參考這個佩戴效果，我們的耳機重量僅 8g，長時間佩戴也不會感覺沉重 🏃

5.3 場景三: Discord 社區的內容創作機器人

業務背景: 一個遊戲社區 Discord，管理員希望機器人能根據用戶描述生成遊戲角色立繪。

實現思路:

• OpenClaw 接入 Discord
• 使用 slash command /generate 觸發圖像生成
• 結合用戶 role 做權限管理 （普通用戶每日 5 次，會員無限）
• 調用 gpt-image-2-all 節省成本

Discord 命令註冊片段:

@bot.command（name="generate"）
async def generate_image（ctx， *， prompt: str）:
    # 檢查用戶權限和當日配額
    if not check_quota（ctx.author）:
        await ctx.send（"❌ 今日配額已用完，升級會員解除限制"）
        return
    
    # 調用 OpenClaw 的 chat completions endpoint
    image_url = await openclaw_client.generate（
        model="apiyi/gpt-image-2-all"，
        prompt=prompt
    ）
    
    await ctx.send（f"🎨 {ctx.author.mention} 你的角色立繪:\n{image_url}"）
    decrement_quota（ctx.author）

5.4 場景四: 企業微信 + 飛書內部工具

業務背景: 企業內部需要快速生成會議海報、社交媒體配圖、活動 banner。

OpenClaw 配置策略:

• 接入企業微信和飛書雙 channel
• 配置使用 gpt-image-2 （官轉，商用合規）
• 加入企業品牌詞關鍵詞審覈 （避免生成競品 logo）
• 所有生成圖片記錄到內部對象存儲，便於二次使用

🎯 企業級集成建議: 企業級場景建議使用官轉模型 （gpt-image-2） 以確保 Indemnification 保護。同時建議通過 API易 apiyi.com 這類支持企業對公賬戶、月度發票的中轉平臺接入，便於財務記賬和合規審計。

六、按次計費 $0.03 是怎麼算的: 成本透明化

很多用戶對"按次計費"的具體含義有疑問。這一節把 gpt-image-2-all 的計費邏輯講清楚。

6.1 單次調用的成本明細

gpt-image-2-all 計費規則 （折扣前）
─────────────────────────────────
基礎生成成本: $0.03 / 次
├─ 1024×1024 標準分辨率: 包含
├─ 1024×1792 （豎圖）: 包含
├─ 1792×1024 （橫圖）: 包含
└─ 失敗請求 （safety violations）: 不計費

附加成本: $0
├─ 不按 token 計費
├─ 不按圖片字節計費
└─ 不區分 prompt 長度

6.2 與官轉模型的成本對比

6.3 折扣後的實際成本

APIYI 平臺對充值金額提供階梯折扣:

🎯 成本優化建議: 如果你的 OpenClaw 部署預計每月調用超過 5000 次圖片生成，建議聯繫 API易 apiyi.com 商務團隊申請企業月結方案，可以拿到 7 折以下的價格，適合做 AI 產品的開發者和創業團隊。

6.4 爲什麼按次計費比按 token 更適合 OpenClaw 場景

OpenClaw 主要使用消息平臺，用戶的生圖請求長度差異很大:

• 短 prompt: "畫一隻貓" （~5 token）
• 長 prompt: "畫一張賽博朋克風格的未來城市夜景，霓虹燈倒映在溼漉漉的街道上，遠處有飛行汽車…" （~80 token）

如果按 token 計費，長 prompt 用戶會"心理負擔"主動縮短描述，反而損失圖片質量。按次計費讓用戶專注於描述質量，而非 token 長度——這是 gpt-image-2-all 設計的核心理念。

七、OpenClaw 接 gpt-image-2 高頻 FAQ

Q1: OpenClaw 默認配置就支持 gpt-image-2 嗎？

不支持。OpenClaw 默認只接 OpenAI 官方 API，中國大陸用戶無法直連，且 gpt-image-2 需要 Tier 5 以上賬戶才能穩定使用。必須通過自定義 provider （例如配置 APIYI 作爲 OpenAI 兼容服務） 才能用上。

Q2: 我修改了 openclaw.json 後，OpenClaw 沒識別到新 provider？

排查步驟:

1. JSON 格式檢查: cat ~/.openclaw/openclaw.json | jq . （無報錯說明格式正確）
2. 重啓服務: openclaw restart 或對應的 systemctl 命令
3. 查看日誌: openclaw logs --tail 100 檢查是否有 provider 加載錯誤
4. 驗證 baseUrl: 確保以 /v1 結尾，不要寫 /v1/ （尾隨斜槓）
5. 驗證 apiKey: 在控制檯確認 Key 仍有效

Q3: 調用 gpt-image-2-all 時報 "model not found" 錯誤？

通常是以下原因之一:

• models 數組中的 id 字段拼錯 （應該是 gpt-image-2-all，不是 gpt-image-2-all-model）
• api 字段寫成 openai 而非 openai-completions
• OpenClaw 版本過舊 （需要 ≥ v0.45 才完整支持自定義 provider）

Q4: gpt-image-2-all 生成的圖片可以商用嗎？

法律層面: APIYI 在用戶協議中說明了官逆模型的使用限制，嚴格商用建議使用官轉模型 （gpt-image-2）。原因是官逆通道本身違反 OpenAI ToS，產生的圖片在 Indemnification 保護範圍之外。

實際選擇:

• 個人項目、內部工具、原型驗證: ✅ 用 gpt-image-2-all
• 商品廣告、客戶交付物、品牌素材: ✅ 用 gpt-image-2

Q5: 在 WhatsApp/Telegram 中調用 gpt-image-2-all 經常超時？

圖像生成的實際耗時是 10-20 秒，如果消息平臺顯示超時，可能是:

• OpenClaw requestTimeout 配置過短 （建議設置 ≥ 60 秒）
• 網絡抖動 （中轉節點可選 Hong Kong / Singapore 改善延遲）
• 模型負載高峯 （建議加 retry 邏輯，通常重試一次成功率 > 95%）

Q6: 一個 API Key 能同時供多個 OpenClaw 實例使用嗎？

可以。但建議:

• 單 Key 總 QPS 控制在 50 以內 （避免觸發限流）
• 大規模部署 （10+ 實例） 時使用多個 Key 做負載分攤
• 在控制檯啓用"使用日誌"，方便排查跨實例的問題

Q7: OpenClaw 調用圖片生成時，如何把圖片永久保存到自己的對象存儲？

OpenClaw 默認會把圖片 URL 直接返回給消息平臺，但生成的 URL 通常有有效期 （24-72 小時）。如果需要永久保存:

# 在 OpenClaw agent hook 中配置
async def post_image_generation_hook（image_url: str）:
    # 下載圖片到本地
    image_data = await download（image_url）
    # 上傳到企業對象存儲
    permanent_url = await upload_to_oss（image_data， bucket="ai-images"）
    return permanent_url

Q8: 如何在 OpenClaw 中限制單用戶的每日生圖次數？

OpenClaw 自帶 rate limiting 機制，在 openclaw.json 中配置:

{
  "rateLimits": {
    "imageGeneration": {
      "perUser": {
        "daily": 50，
        "hourly": 10
      }，
      "perChannel": {
        "daily": 500
      }
    }
  }
}

Q9: gpt-image-2-all 不支持參考圖編輯 （image-to-image） 嗎？

當前版本不支持。如果需要參考圖編輯，有兩個方案:

• 使用 gpt-image-2 官轉模型，通過 /v1/images/edits 端點 （需用 Skills 方案接入）
• 等待 APIYI 後續推出的 gpt-image-2-all-edit 變體 （路線圖中）

Q10: OpenClaw 接 gpt-image-2 會上報使用數據給 OpenAI 嗎？

API 調用本身一定會。任何通過 API 調用的 prompt 和生成的圖片，OpenAI 服務器都會有日誌記錄 （用於安全審查，默認 30 天保留）。但 OpenAI 明確承諾不會用 API 數據訓練模型，這一點寫在 Service Terms 中。

八、總結: OpenClaw 接入 gpt-image-2 的最佳實踐

回顧本文，接入路徑的選擇可以歸納爲三句話。

8.1 三句話決策建議

✅ 如果你只用 OpenClaw + 消息平臺 （WhatsApp/Telegram/Discord）
   → 選方案 B: OpenAI 兼容模式 + gpt-image-2-all
   理由: 配置最簡單、按次計費最透明、與 chat 流原生兼容

✅ 如果你用 Codex CLI / Cursor + OpenClaw 聯動開發
   → 選方案 A: APIYI Skills （apiyi-gpt-image-2-gen）
   理由: Skills 生態更適合開發工具鏈

✅ 如果你做企業級商用產品
   → 選方案 A + gpt-image-2 官轉
   理由: Indemnification 保護、商用合規、2K 分辨率

8.2 完整接入 Checklist

接入完成後，用以下清單做最後檢查:

8.3 進一步優化方向

接入完成只是起點。在生產環境中，還可以做這些優化:

• Prompt 增強: 在 OpenClaw agent 配置中加 system prompt，自動給用戶的簡短描述補全風格、構圖等參數
• 圖片緩存: 對相同 prompt 做哈希，命中緩存的請求不重複調用 API
• 多模型 fallback: 主模型 （gpt-image-2-all） 失敗時，自動降級到備用模型 （例如 Imagen 4）
• 生成日誌: 把 prompt 和生成結果記錄到數據庫，便於事後審計和數據分析

🎯 總體建議: gpt-image-2 與 OpenClaw 的組合是 2026 年 AI Agent 落地最值得嘗試的搭配之一——把頂級圖像模型直接放到日常使用的消息平臺中，極大降低了 AI 工具的使用門檻。建議通過 API易 apiyi.com 平臺快速完成接入，該平臺同時支持官轉和官逆兩種模式，可以根據實際使用情況靈活切換。

OpenClaw 的開放架構讓它能接入幾乎任何 OpenAI 兼容服務，而 gpt-image-2 是當前圖像生成領域的最強模型之一。把這兩者結合，你就擁有了一個跑在 WhatsApp/Telegram/Discord 上的 SOTA 級圖像生成助手——這在一年前還是不可想象的能力組合。

最後送一句話: "工具的價值不在於功能多強，而在於多快能用到日常工作流中。" OpenClaw + gpt-image-2 的組合恰好滿足這個標準——10 分鐘完成配置，馬上就能用，這是它最大的魅力。

作者: APIYI Team — 企業級 AI 大模型 API 接入平臺 apiyi.com，提供 gpt-image-2、gpt-image-2-all、Claude 4.7、Gemini 3 Pro 等 200+ 主流模型的統一接口調用，支持 OpenAI 兼容協議，適配 OpenClaw、Cursor、Codex CLI、Open WebUI 等主流客戶端。

參考資料: OpenClaw 官方文檔 docs.openclaw.ai · GPT-Image Skills GitHub: github.com/wuchubuzai2018/expert-skills-hub