使用工具 - ComfyUI MCP

工具參考按 AI 閱讀的形式列出這個專案能做的一切。本頁是給你看的版本。

這裡不要求你寫程式碼、打 JSON，或學一套 API。如果你曾經對人說過「開啟我的肖像工作流程，把步數調到 30」，你已經知道這個介面了。

工具是代理可以做的事，不是你要輸入的東西

單靠自己，聊天模型只能產出文字。它可以描述一條工作流程；它打不開一條。工具是我們交給模型的、具體、有名字的動作，好讓它真正夠到你的 ComfyUI —— 載入檔案、把算圖排入佇列、安裝節點包、看剛出來的那張圖。模型不能發明這些。它拿到一份固定選單，選單上每一項都精確說明自己需要什麼。 你從不從那份選單裡挑。 你用自然冒出來的詞說想要什麼，代理來選。

你說	它悄悄跑的
「我存了些什麼？」	`get_workflow` with `action: "list"`
「開啟那個肖像的，告訴我它做什麼」	`get_workflow` with `action: "list"`，然後 `action: "analyze"`
「給我做一隻雪地裡的紅狐狸」	`generate_image`（`image` 任務）
「做好了嗎？」	`queue`（`list` 任務）
「失敗了，我不明白為什麼」	`get_history`（`diagnose` 任務）
「一半節點都是紅的」	`list_packs`（`install_deps` 任務）
「磁碟滿了，哪些大？」	`list_local_models`

注意第二行：一句話，兩個工具，順序你不必知道。這就是整套安排的要點。你不需要知道找檔案和讀檔案是兩步操作。

你想多含糊都可以。「有東西壞了」就是很好的開頭 —— 代理會從 get_system_stats (action:"health") 開始往下收。說得具體會更快，但從來不是必須的。

參考頁裡那些 JSON 是什麼？

每個工具頁都會展示這樣一塊：

{
  "tool": "generate_image",
  "arguments": {
    "prompt": "a red fox in deep snow, golden hour, sharp focus",
    "steps": 30
  }
}

那是代理發出去的記錄，不是給你的說明書。你說的是「給我做一隻雪地裡的紅狐狸，細節再多一點」；從另一頭出來的就是這個。值得能讀懂一份，理由有兩個：你想核對代理是不是聽懂了，以及出問題時你要跟別人描述。不值得背下來。

工具來自兩個地方

有兩面，它們存在是因為回答的是不同問題。

側邊欄面板

住在 ComfyUI 裡面，代理分頁裡。它的工具（panel_*）作用在你此刻看著的節點圖上 —— 那塊真實畫布，帶著你還沒儲存的改動。

外面的用戶端

Claude Desktop、Claude Code、編輯器、你的手機。它的工具作用在伺服器上：磁碟上的檔案、任務佇列、模型、節點包、ComfyUI 行程本身。

分界其實是「這個」這個詞。你說「給這個加一個 LoRA」時，面板知道「這個」是什麼，因為它看得見你的螢幕。外面的用戶端看不見 —— 得告訴它一個檔名。所以面板處理的是這類事：

讀你眼前的節點圖（panel_graph_outline）
跑它，就跟你自己按了 Queue Prompt 一模一樣（panel_run）
接進一個節點、改一個控制項、告訴你節點為什麼變紅（panel_add_node、panel_set_widget、panel_get_errors）
把整條工作流程載入到畫布上，或儲存畫布上現有的（panel_load_workflow、panel_save_workflow）

而外面的用戶端處理的是從零生成一張圖、管理模型和節點包、過一遍已儲存的檔案、重新啟動 ComfyUI。

如果你是新手，用面板。 一次安裝，就在節點圖旁邊，也不需要單獨的應用。請看面板指南完成設定。等你想讓代理插手不是畫布的事情時，再加外面的用戶端。

它們不是對手 —— 面板在底下跟同一台伺服器說話，一個工作階段可以兩邊都用。有人在桌面上改節點圖，同時手機驅動同一個工作階段，這是受支援的事，不是旁門。

一個工具，多項工作

你會注意到有些工具帶一個 action：

{ "tool": "workspace", "arguments": { "action": "get" } }

這看起來像暗號，其實不是。workspace 是一個話題 —— 我們在說哪一份 ComfyUI 安裝 —— 而 action 說你就這個話題問的是哪一個問題：讀它、改預設、列出有什麼。讀起來就跟日常說話一樣，動詞和賓語是分開的詞：

你說	動作
「我在用哪份 ComfyUI？」	`get`
「以後一直用 D 盤那份」	`set_default`
「你能看見哪些安裝？」	`list`

沒有刪掉任何東西

這種形狀還比較新，很容易讀成能力被砍了。並沒有，而這種誤會值得正面先攔住，因為它已經出現過。以前是一個問題一個工具 —— 讀工作區一個名字，設定另一個，列出再一個。那些名字沒了，如果你盯著工具數量看，會看見它在急劇下降。實際發生的是相關工具被合併了，不是刪除：

The old name	The same thing today
`get_workspace`	`workspace` with `action: "get"`
`get_queue`	`queue` with `action: "list"`
`apps_run_status`	`apps` with `action: "run_status"`
`install_workflow_dependencies`	`list_packs` with `action: "install_deps"`
`list_workflows`	`get_workflow` with `action: "list"`
`analyze_workflow`	`get_workflow` with `action: "analyze"`
`validate_workflow`	`create_workflow` with `action: "validate"`

底下的程式碼一樣，行為一樣，答案一樣。只有前面的標籤變了。原因是選單長到開始傷人。每個工具的完整描述都得在模型選擇之前交給它，過了某個體量，選擇本身就會變差 —— 尤其是較小的模型，會開始挑一個看起來像鄰居的，而不是對的那個。更少、更寬、帶著清楚 action 的工具，實測能修好這個。這也意味著模型把注意力花在你的請求上，而不是讀一份目錄。這些你都不該察覺。你以前也沒打過舊名字；你說的是「我在用哪份 ComfyUI？」，這句話現在仍然管用。

如果某份更舊的指南，或模型自己的記憶，伸手去夠一個已經不存在的名字，你會拿到一條點名替代品的具體錯誤，而不是空白的「未知工具」—— 例如：removed in 0.49.0. Call workspace (action:“get”) instead. 代理通常能自己糾正並重試，你什麼都不用做。

想要不一樣的結果

每個工具頁都列出參數 —— max_chars、limit、depth、fields。你會合理地問它們該打在哪，誠實的答案是：哪都不打。沒有給 max_chars 的設定框，因為它不是一項設定。它是代理每次呼叫工具時當場填的參數。這並不把你排除在外。它改的是控制長什麼樣：

你不設定參數。你開口要一個 —— 就寫在你本來就要寫的那句話裡。

兩種問法

兩種都管用。它們失敗的方式不同，這是唯一需要兩種都知道的理由。

	聽起來像	什麼時候用
白話	「詳細讀節點 42 —— 只要那個節點，不要整張圖。」	永遠從這裡開始。這是人們實際會打的，而且通常管用。
顯式	「用 `panel_query_graph`，`ids` 為 [42]，`max_chars` 為 20000。」	模型已經錯過一次，你想不給它留下餘地。

點名工具和參數不是正確形式 —— 它是強硬形式。留給重試。

答案被截斷時

長讀取會封頂，免得一張巨大的節點圖吞掉整段對話。兩個不同的天花板可以停住同一次讀取 —— 列出的節點數（limit）和字元預算（max_chars）—— 調高那個不是問題的，什麼都不會變，讀起來就跟重試失敗一模一樣。你不需要自己算是哪一個。在已儲存的檔案上，說明會點名觸發的那根槓桿，並排除另一根，原話就是這麼說的：

… truncated at 40 of 300 by limit=40 — raise limit up to 200, or narrow with types/where/ids/depth. max_chars is not the constraint here.

而當那根槓桿已經頂到天花板時，它會這麼說，而不是再讓你去調高，因為已經沒什麼可調了。

在即時畫布上（panel_query_graph），同一次讀取由面板自己那份引擎執行，它還沒跟上那套措辭。如果那裡的說明點名了一個參數，調高它卻什麼都沒變，先試試另一根，再下結論說工具壞了。

代理本該讀自己的說明並自己重試。它沒這麼做時，你就是後備，而這句話就是：

被截斷了 —— 讀那條說明，重試同一個查詢，把它們點名的那個上限調高。

上限在哪裡

這些是兩個按預算讀節點圖的工具的數字 —— panel_query_graph（即時畫布）和 get_workflow 配合 action: "query"（已儲存的檔案）：

參數	預設	你最多能要到
`max_chars`	12000	60000
`limit`（列出的節點）	40	200

在這兩個工具上，要過天花板會被當成無效參數拒絕，而不是悄悄向下取整，所以代理立刻知道並能自己糾正。這些數字也不是通用的：另外幾個工具也收 max_chars，並設自己的天花板，寫在那個工具自己的描述裡。

範圍比預算更管用

調高天花板是第二件該試的事，不是第一件。在一張 600 節點的工作流程上，更大的預算多半隻是給你更多錯的節點，把答案埋進幾百個無關的裡面，即使技術上裝得下，回覆也會變差。先收窄，用任何自然的詞：

你說	它收到哪
「只看節點 42 和 43。」	只有那些 id
「取樣器吃進了什麼？」	一個節點的上游一側
「……只往回兩跳。」	從那裡算起的有界距離
「這裡每種節點型別有多少？」	計數而不是清單

然後，如果還是被截斷，再放寬。

當它說不

工具拒絕通常不是缺陷。大多數拒絕是護欄開火了，因為這次呼叫會做一件你沒要求的事。

「它拒絕了，我不知道為什麼」

你會看到白話，而不是堆疊追蹤 —— 點名它不肯做什麼、改做什麼。把它讀成代理在小心，而不是卡住了。常見的誠實拒絕：

它分不清你說的是哪條工作流程。 開啟了不止一個分頁，或節點圖還沒有已儲存的身份。儲存它，或說出是哪一個。
它會覆寫某些東西。 要一個新檔名，它就會繼續。
那東西確實不在。 模型檔案、節點包、正在跑的伺服器。

如果一次拒絕讀起來像胡話而不是謹慎，那就值得報告 —— 讓代理去提交，它會替你附上你的環境細節。

「這個面板太舊了」

最常見、而且有真正修復的拒絕。讀起來大致像：

This ComfyUI-MCP panel is too old for ”…” — update the ComfyUI-MCP panel, then reconnect.

側邊欄面板和這個伺服器是分開出貨的兩塊，所以一塊可以落後於另一塊。伺服器要的東西，已安裝的面板沒法安全做到時，它會拒絕而不是猜 —— 一塊舊面板如果沒法確認命令會落到哪條工作流程上，就可能把你的編輯打到錯誤的分頁，所以在更新之前它被限制在只讀。修復是三步，第三步是人們會跳過的那步：

更新面板

讓代理更新它（install_comfyui(action:'panel', panel_action:'update')），或從 ComfyUI-Manager 做，那裡它列名為 comfyui-agent-panel。

重新啟動 ComfyUI

更新自己不會重新啟動任何東西。讓代理做，或你自己重新啟動。

硬重新整理 ComfyUI 瀏覽器分頁

Ctrl+Shift+R（Mac 上是 Cmd+Shift+R）。瀏覽器快取了舊的面板程式碼，光重新啟動甩不掉。跳過這一步，同一條訊息會立刻回來，所以看起來像更新失敗了，其實沒有。

「沒有面板已連線」

不同的問題，看起來差不多的訊息。意思是外面的代理找不到你的 ComfyUI 瀏覽器分頁。幾乎總是下面之一：

ComfyUI 根本沒在瀏覽器裡開啟 —— 開啟它，看側邊欄的代理分頁。
ComfyUI 剛重新啟動過，或你重新載入了分頁。那會丟掉連線。重新載入 ComfyUI 分頁，它馬上回來。
代理分頁開著，但從未連線過。面板在你選一個供應商並點連線時才附著，從不在載入時附著，所以剛開啟、什麼都沒顯示的分頁是普通狀態，不是故障。
面板還沒裝。請看面板指南。

訊息會幫你把這些分成兩組 —— 它區分「以前連過、後來掉了」和「還什麼都沒連過」。它不再往下走，並且會這麼說，而不是挑一個它沒法觀察的原因。以前連過的分頁證明面板已安裝並且當時能用，所以重新載入 ComfyUI 分頁是第一件該試的，通常也是唯一一件；如果重新載入沒把它帶回來，就當第二組，順著上面的檢查往下走。

當它什麼都不說

更難的失敗是裡面完全沒有錯誤的那種。代理不呼叫工具，不拒絕，也不抱怨。它只是說話：描述你的工作流程大概包含什麼，或提出給你寫指令碼。聽起來很幫忙，而且它什麼都沒看過。三種完全不同的情況會產出同一種行為，從你坐的地方看，它們無法區分：

不在

你的用戶端從沒拿到工具。它們不在它交給模型的清單裡，所以沒什麼可呼叫。

被擋住

你的用戶端有工具，但不讓模型跑它們。呼叫停在用戶端內部。

沒被要過

一切都在工作。你想要的東西住在一個從沒被提起的名字下面，所以沒人伸手去夠。

補救指向三個不同方向，其中兩個如果你猜錯會主動傷人：重裝已經裝好的東西，或放鬆從來不是問題的權限。所以第一步不是去修任何東西。是先搞清楚你在哪一種。

把它們分開的兩個問題

用白話問代理：

問它能看見什麼

你從 comfyui-mcp 拿到哪些工具？只列名字。

幾十個名字的清單是正常且健康的 —— 那是直接面，從 0.50.0 起就是預設。三個名字 —— list_tools、describe_tool、call_tool —— 也正常且健康。那是精簡工具模式，透過傳入 --compact 得到，小型本機模型現在仍會自動選擇。目錄的其餘部分離一次 list_tools 呼叫只有一步，所以讓它跑那個，你就會看到真正的清單。兩種答案都不意味著有東西被扣下。一個名字都沒有，或「我沒有任何 ComfyUI 工具」，只排除第三種情況，別的都不排除。它不意味著不在。權限策略可以從展示給模型的清單裡扣下工具，所以一台已安裝、已連線、正在工作的伺服器會給出正好這個答案。這一步裡，不在和被擋住無法區分，而這就是讓一個使用者花了好幾天的那條枝 —— 他確信是接線問題。有一項檢查能收窄，而這不是代理能看見的：開啟你用戶端自己的 MCP 伺服器清單 —— 它展示連上了哪些伺服器的那個地方，和它交給模型的工具清單不是同一份。

comfyui-mcp 不在，或顯示失敗 → 不在。用戶端一側的接線問題，不是面板或伺服器故障。它再分成兩種 —— 從沒接上，或一台根本握不住它們的主機 —— 下面的清單把它們分開。
它在而且已連線，模型仍然列不出任何東西 → 工具已經到了你的用戶端。之後停在哪仍然開放：它們可能被權限規則從模型那裡扣下，或者模型只是沒能或拒絕列出它們，從這裡看完全一樣。不要單憑這個就開始放鬆權限。如果那份伺服器清單還顯示它從 comfyui-mcp 拿走了哪些工具，事情就定了：那裡列了而模型沒列，說明問題在模型，不在你的權限；那裡一個都沒有，說明它們在模型看見之前就被過濾了。如果你的用戶端不顯示那個 —— 很多都不顯示 —— 這裡沒有任何你能拿到的東西能區分這兩種，第二步機會更好，因為拒絕會用文字回來。

讓它試一次，並原樣回報

現在呼叫那個你會用來做這件沒在工作的事的工具，並把回來的東西原樣貼出來 —— 包括任何錯誤。不要繞開它。

那句話裡有兩個細節在做事。你會用來做這件沒在工作的事的那個工具，特指這個。權限規則通常按工具寫，所以另一個工具成功證明不了你在乎的那個 —— 擋住就是這樣藏起來的。如果沒被讀的是畫布，測試就必須是一次畫布讀取。不要繞開它。 整套失敗模式就是代理悄悄繞過障礙而不點名它，由著它自己，它會再做一次。

真實結果 —— 那個工具能用。你在第三種情況。
「被拒絕了」/「不允許」/「我需要權限」 —— 被擋住，在你的用戶端內部。這一條是定論：代理問了，被拒絕了。
「我沒有那個工具」 —— 仍然是不在或被擋住。被扣下的工具和缺失的工具從模型的座位上看一模一樣，所以不要單憑這個行動：把它帶回第一步的伺服器清單，如果那份清單也不顯示按伺服器的工具，那你能碰到的東西就分不開這兩種，誠實的下一步是去 issue 追蹤器問，而不是開始改設定。
還是散文，仍然沒有呼叫 —— 直問：「你呼叫工具了嗎？如果沒有，為什麼沒有？」 躲兩次的代理，通常是在繞開一件它沒提過的事。

我們從這裡能看到什麼，看不到什麼

當你的用戶端拒絕一次工具呼叫時，那次呼叫從不離開你的用戶端。什麼都到不了這台伺服器，所以它的記錄裡不會出現任何東西，我們能到達的任何地方也不會產出錯誤。我們偵測不到擋住，也不會假裝能：任何聲稱能告訴你「你的用戶端擋住了這個」的頁面或訊息都會是在猜。

同一事實反過來切，而這正是誤導人的那一半：安靜的記錄不是什麼都沒試過的證據。不在、被擋住、以及從沒被要過，從這裡看都像沉默。所以上面兩個問題才是真正的診斷。它們管用，是因為它們問的是當時在場的那個參與者 —— 你的代理 —— 讓它說出試了什麼，並拒絕它繞開答案的選項。

每種答案通常從哪來

被擋住 —— 你用戶端自己的權限規則。 在 Claude Code 裡，那是 settings.json 的 permissions 塊（~/.claude/settings.json，或專案的 .claude/settings.json）； MCP 工具以帶命名空間的名字出現在那裡，mcp__comfyui__<tool>。一份從沒提到它們的嚴格 allow 清單會在傳送之前停住每一次呼叫。這就是讓一個使用者花了好幾天的那種情況：工具看起來像在工作，恰恰因為他們在找的錯誤永遠不會出現。 不在，而且能修 —— 從沒接上。 用戶端會說 MCP，但從沒被告知這台伺服器，或被告知了但條目是錯的。這是常見的那種，改一份設定就行；請看快速上手瞭解你的用戶端期望的條目。 不在，而且修不了 —— 一台根本沒有 MCP 用戶端的主機。 有些代理不說 MCP，再怎麼設定也改不了這個。pi 就是一個：它有自己內建的 shell 和編輯器工具，沒有 MCP 用戶端，所以無論還裝了什麼，都交不上我們的。你選它時面板會直接說 —— 「pi 沒有 ComfyUI 工具（沒有 MCP）」。那一行就是答案，不是要除錯的症狀；修復是換一個後端。 兩者都有可能 —— 夾在中間的東西。 承載你 MCP 流量的閘道、代理或路由器，可能只把工具面的一部分傳下去。如果目錄和實際跑起來的對不上，就懷疑中間那一層。

如果原來是第三種情況

那就什麼都沒壞，也沒人配錯：一項能力存在，而你無從發現。那是我們的失敗而不是你的，值得告訴我們 —— 讓代理去提交，它會替你附上你的環境。一項誰都找不到的功能，從你坐的地方看，就是一項我們沒發出去的功能。

如果你跑的是小型本機模型

把整份選單交給模型，等於它開口之前先讀很多東西。在大型託管模型上這沒問題。在你自己機器上跑的小型模型上，這常常是能用和不能用的差別。所以預設情況下代理拿到的是三個工具而不是完整集合：一個瀏覽目錄，一個查單個工具的細節，一個去跑它。它在需要的時候取需要的東西，而不是一開始把所有東西讀完。你不用做任何事就能得到這個 —— 這是預設。想要的話控制項在這裡：

# force the small three-tool mode
npx -y comfyui-mcp --compact

# or hand the model everything at once
npx -y comfyui-mcp --full

也可以用 COMFYUI_MCP_TOOL_MODE=compact 或 COMFYUI_MCP_TOOL_MODE=full 設定。代價是第一次真正動作之前多一兩輪往返，換來模型還剩思考的空間。大模型通常更喜歡 --full。哪些模型扛得住哪種，請看本機 LLM。

下一步去哪

快速上手

裝上它，生成你的第一張圖。

側邊欄面板

ComfyUI 內的代理，以及它能對你的畫布做什麼。

工具參考

每個工具，帶真實呼叫長什麼樣的例子。

疑難排解

當它不是拒絕，而是真的壞了。

​工具是代理可以做的事，不是你要輸入的東西

​參考頁裡那些 JSON 是什麼？

​工具來自兩個地方

側邊欄面板

外面的用戶端

​一個工具，多項工作

​沒有刪掉任何東西

​想要不一樣的結果

​兩種問法

​答案被截斷時

​上限在哪裡

​範圍比預算更管用

​當它說不

​「它拒絕了，我不知道為什麼」

​「這個面板太舊了」

​「沒有面板已連線」

​當它什麼都不說

不在

被擋住

沒被要過

​把它們分開的兩個問題

​我們從這裡能看到什麼，看不到什麼

​每種答案通常從哪來

​如果原來是第三種情況

​如果你跑的是小型本機模型

​下一步去哪

快速上手

側邊欄面板

工具參考

疑難排解

工具是代理可以做的事，不是你要輸入的東西

參考頁裡那些 JSON 是什麼？

工具來自兩個地方

一個工具，多項工作

沒有刪掉任何東西

想要不一樣的結果

兩種問法

答案被截斷時

上限在哪裡

範圍比預算更管用

當它說不

「它拒絕了，我不知道為什麼」

「這個面板太舊了」

「沒有面板已連線」

當它什麼都不說

把它們分開的兩個問題

我們從這裡能看到什麼，看不到什麼

每種答案通常從哪來

如果原來是第三種情況

如果你跑的是小型本機模型

下一步去哪