Providers
ComfyUI
OpenClaw 隨附一個內建的 comfy 外掛，用於執行由工作流程驅動的 ComfyUI。此
外掛完全由工作流程驅動：OpenClaw 不會將通用的 size、
aspectRatio、resolution、durationSeconds 或文字轉語音式控制項對應至
您的圖形。
| 屬性 | 詳細資料 |
|---|---|
| 提供者 | comfy |
| 模型 | comfy/workflow |
| 共用工具 | image_generate、video_generate、music_generate |
| 驗證 | 本機 ComfyUI 不需要；Comfy Cloud 使用 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY |
| API | ComfyUI /prompt / /history / /view；Comfy Cloud /api/* |
支援的功能
- 使用工作流程 JSON 產生及編輯圖片（編輯時接受 1 張上傳的參考圖片）
- 使用工作流程 JSON 進行文字轉影片或圖片轉影片（1 張參考圖片）
- 透過共用的
music_generate工具產生音樂／音訊，可選擇提供 1 張參考圖片 - 從已設定的節點下載輸出；若未設定節點，則從所有相符的輸出節點下載
開始使用
選擇在自己的機器上執行 ComfyUI，或使用 Comfy Cloud。
Local
最適合： 在您的機器或區域網路上執行自己的 ComfyUI 執行個體。
Start ComfyUI locally
確認您的本機 ComfyUI 執行個體正在執行（預設為 http://127.0.0.1:8188）。
Prepare your workflow JSON
匯出或建立 ComfyUI 工作流程 JSON 檔案。記下提示詞輸入節點，以及您希望 OpenClaw 讀取之輸出節點的節點 ID。
Configure the provider
設定 mode: "local" 並指向您的工作流程檔案。最小圖片範例：
{ plugins: { entries: { comfy: { config: { mode: "local", baseUrl: "http://127.0.0.1:8188", image: { workflowPath: "./workflows/flux-api.json", promptNodeId: "6", outputNodeId: "9", }, }, }, }, },}Set the default model
將 OpenClaw 指向您已設定之功能的 comfy/workflow 模型：
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}Verify
openclaw models list --provider comfyComfy Cloud
最適合： 在 Comfy Cloud 上執行工作流程，而無須管理本機 GPU 資源。
Get an API key
在 comfy.org 註冊，並從您的帳戶儀表板產生 API 金鑰。
Set the API key
使用下列任一方式提供金鑰：
# Onboarding flagopenclaw onboard --comfy-api-key "your-key" # Environment variable (preferred for daemons)export COMFY_API_KEY="your-key" # Alternative environment variableexport COMFY_CLOUD_API_KEY="your-key" # Or inline in configopenclaw config set plugins.entries.comfy.config.apiKey "your-key"Prepare your workflow JSON
匯出或建立 ComfyUI 工作流程 JSON 檔案。記下提示詞輸入節點及輸出節點的節點 ID。
Configure the provider
設定 mode: "cloud" 並指向您的工作流程檔案：
{ plugins: { entries: { comfy: { config: { mode: "cloud", image: { workflowPath: "./workflows/flux-api.json", promptNodeId: "6", outputNodeId: "9", }, }, }, }, },}Set the default model
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}Verify
openclaw models list --provider comfy設定
Comfy 支援共用的頂層連線設定，以及各功能的工作流程區段（image、video、music）：
{ plugins: { entries: { comfy: { config: { mode: "local", baseUrl: "http://127.0.0.1:8188", image: { workflowPath: "./workflows/flux-api.json", promptNodeId: "6", outputNodeId: "9", }, video: { workflowPath: "./workflows/video-api.json", promptNodeId: "12", outputNodeId: "21", }, music: { workflowPath: "./workflows/music-api.json", promptNodeId: "3", outputNodeId: "18", }, }, }, }, },}共用鍵
| 鍵 | 類型 | 說明 |
|---|---|---|
mode |
"local" 或 "cloud" |
連線模式。預設為 "local"。 |
baseUrl |
字串 | 本機預設為 http://127.0.0.1:8188，雲端預設為 https://cloud.comfy.org。 |
apiKey |
字串 | 選用的內嵌金鑰，可取代 COMFY_API_KEY / COMFY_CLOUD_API_KEY 環境變數。 |
allowPrivateNetwork |
布林值 | 允許在雲端模式中使用私人／區域網路 baseUrl，或使用本機私人 DNS FQDN。 |
各功能的鍵
這些鍵適用於 image、video 或 music 區段內：
| 鍵 | 必要 | 預設值 | 說明 |
|---|---|---|---|
workflow 或 workflowPath |
是 | -- | 內嵌工作流程 JSON，或 ComfyUI 工作流程 JSON 檔案的路徑。 |
promptNodeId |
是 | -- | 接收文字提示詞的節點 ID。 |
promptInputName |
否 | "text" |
提示詞節點上的輸入名稱。 |
outputNodeId |
否 | -- | 要讀取輸出的節點 ID。若省略，則使用所有相符的輸出節點。 |
pollIntervalMs |
否 | 1500 |
等待工作完成時的輪詢間隔，以毫秒為單位。 |
timeoutMs |
否 | 300000 |
工作流程執行的逾時時間，以毫秒為單位。 |
image 與 video 區段也支援參考圖片輸入節點：
| 鍵 | 必要 | 預設值 | 說明 |
|---|---|---|---|
inputImageNodeId |
是（傳入參考圖片時） | -- | 接收已上傳參考圖片的節點 ID。 |
inputImageInputName |
否 | "image" |
圖片節點上的輸入名稱。 |
apiKey 接受常值字串或密鑰參照物件。
工作流程詳細資料
Image workflows
將預設圖片模型設定為 comfy/workflow：
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}參考圖片編輯範例：
若要使用上傳的參考圖片啟用圖片編輯，請將 inputImageNodeId 加入圖片設定：
{ plugins: { entries: { comfy: { config: { image: { workflowPath: "./workflows/edit-api.json", promptNodeId: "6", inputImageNodeId: "7", inputImageInputName: "image", outputNodeId: "9", }, }, }, }, },}Video workflows
將預設影片模型設定為 comfy/workflow：
{ agents: { defaults: { videoGenerationModel: { primary: "comfy/workflow", }, }, },}Comfy 影片工作流程透過已設定的圖形支援文字轉影片及圖片轉影片。
Music workflows
內建外掛會註冊一個音樂產生提供者，用於工作流程定義的音訊或音樂輸出，並透過共用的 music_generate 工具呈現。它接受選用的參考圖片（最多 1 張）：
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"使用 music 設定區段指向您的音訊工作流程 JSON 及輸出節點。
Backward compatibility
現有的頂層圖片設定（不含巢狀 image 區段）仍可運作：
{ plugins: { entries: { comfy: { config: { workflowPath: "./workflows/flux-api.json", promptNodeId: "6", outputNodeId: "9", }, }, }, },}OpenClaw 會將該舊版結構視為圖片工作流程設定。您不需要立即遷移，但新設定建議使用巢狀的 image / video / music 區段。如果您只使用圖片產生功能，舊版扁平設定與新版巢狀 image 區段在功能上相同。
Live tests
內建外掛提供可選擇啟用的即時測試涵蓋範圍：
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts除非已設定對應的 Comfy 工作流程區段，否則即時測試會略過個別的圖片、影片或音樂案例。
