> ## Documentation Index > Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # 使用工具 > 工具是什麼，為什麼你從不自己呼叫，以及它說不的時候該怎麼辦。寫給人看，不是寫給工程師看。 [工具參考](/docs/docs/tools/image-generation) 按 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 是什麼？ 每個工具頁都會展示這樣一塊： ```json theme={null} { "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。 **如果你是新手，用面板。** 一次安裝，就在節點圖旁邊，也不需要單獨的應用。請看 [面板指南](/docs/docs/zh-TW/panel) 完成設定。等你想讓代理插手不是畫布的事情時，再加外面的 用戶端。 它們不是對手 —— 面板在底下跟同一台伺服器說話，一個工作階段可以兩邊都用。有人在桌面上改 節點圖，同時手機驅動同一個工作階段，這是受支援的事，不是旁門。 ## 一個工具，多項工作 你會注意到有些工具帶一個 `action`： ```json theme={null} { "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`。 更新自己不會重新啟動任何東西。讓代理做，或你自己重新啟動。 **Ctrl+Shift+R**（Mac 上是 **Cmd+Shift+R**）。瀏覽器快取了舊的面板程式碼，光重新啟動 甩不掉。跳過這一步，同一條訊息會立刻回來，所以看起來像更新失敗了，其實沒有。 ### 「沒有面板已連線」 不同的問題，看起來差不多的訊息。意思是外面的代理找不到你的 ComfyUI 瀏覽器分頁。 幾乎總是下面之一： * ComfyUI 根本沒在瀏覽器裡開啟 —— 開啟它，看側邊欄的代理分頁。 * ComfyUI 剛重新啟動過，或你重新載入了分頁。那會丟掉連線。**重新載入 ComfyUI 分頁**，它馬上 回來。 * 代理分頁開著，但從未連線過。面板在你選一個供應商並點**連線**時才附著，從不在 載入時附著，所以剛開啟、什麼都沒顯示的分頁是普通狀態，不是故障。 * 面板還沒裝。請看[面板指南](/docs/docs/zh-TW/panel)。 訊息會幫你把這些分成兩組 —— 它區分「以前連過、後來掉了」和「還什麼都沒連過」。它不 再往下走，並且會這麼說，而不是挑一個它沒法觀察的原因。以前連過的分頁證明面板已安裝 並且當時能用，所以重新載入 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__`。一份從沒提到它們的 嚴格 `allow` 清單會在傳送之前停住每一次呼叫。這就是讓一個使用者花了好幾天的那種情況： 工具看起來像在工作，恰恰因為他們在找的錯誤永遠不會出現。 **不在，而且能修 —— 從沒接上。** 用戶端會說 MCP，但從沒被告知這台伺服器，或被告知了 但條目是錯的。這是常見的那種，改一份設定就行；請看[快速上手](/docs/docs/zh-TW/quickstart) 瞭解你的用戶端期望的條目。 **不在，而且修不了 —— 一台根本沒有 MCP 用戶端的主機。** 有些代理不說 MCP，再怎麼 設定也改不了這個。`pi` 就是一個：它有自己內建的 shell 和編輯器工具，沒有 MCP 用戶端， 所以無論還裝了什麼，都交不上我們的。你選它時面板會直接說 —— *「pi 沒有 ComfyUI 工具 （沒有 MCP）」*。那一行就是答案，不是要除錯的症狀；修復是換一個後端。 **兩者都有可能 —— 夾在中間的東西。** 承載你 MCP 流量的閘道、代理或路由器，可能只把 工具面的一部分傳下去。如果目錄和實際跑起來的對不上，就懷疑中間那一層。 ### 如果原來是第三種情況 那就什麼都沒壞，也沒人配錯：一項能力存在，而你無從發現。那是我們的失敗而不是你的， 值得告訴我們 —— 讓代理去提交，它會替你附上你的環境。一項誰都找不到的功能，從你坐的 地方看，就是一項我們沒發出去的功能。 ## 如果你跑的是小型本機模型 把整份選單交給模型，等於它開口之前先讀很多東西。在大型託管模型上這沒問題。在你自己 機器上跑的小型模型上，這常常是能用和不能用的差別。 所以預設情況下代理拿到的是**三個**工具而不是完整集合：一個瀏覽目錄，一個查單個工具 的細節，一個去跑它。它在需要的時候取需要的東西，而不是一開始把所有東西讀完。 你不用做任何事就能得到這個 —— 這是預設。想要的話控制項在這裡： ```bash theme={null} # 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](/docs/docs/zh-TW/local-llms)。 ## 下一步去哪 裝上它，生成你的第一張圖。 ComfyUI 內的代理，以及它能對你的畫布做什麼。 每個工具，帶真實呼叫長什麼樣的例子。 當它不是拒絕，而是真的壞了。