KwaFlux MCP 無法使用？看不到工具、app_not_running 與逾時的解決方法

重點速覽

• 由外往內逐層檢查：宿主有沒有啟動伺服器？伺服器有沒有連到應用程式？應用程式有沒有接受任務？
• 如果一個 KwaFlux 工具都看不到，原因幾乎都出在宿主的設定：JSON 或 YAML 格式錯誤、改錯檔案、找不到 Node.js，或沒有重新載入。
• app_not_running 代表伺服器運作正常，但 KwaFlux 沒有開啟（或不在同一台電腦上）。
• 等了約一分鐘就失敗的長時間等待，是宿主的逾時，不是任務失敗。任務仍會在 KwaFlux 裡繼續執行。

KwaFlux 的 MCP 連線出問題時，症狀會告訴你該看哪一層：要嘛是宿主沒有啟動伺服器，要嘛是伺服器連不到應用程式，要嘛是應用程式拒絕了請求。每一層的可能原因都不多，每個原因也都有明確的解法。

本文會說明：如何分辨這三層、每一層的解決方法、KwaFlux 回傳的錯誤訊息，以及一個不需要任何 AI 宿主、兩分鐘就能做完的檢查。

目錄

1. 逐層看可能出錯的地方
2. 第 1 層：宿主裡看不到 KwaFlux 的工具
3. 第 2 層：工具有出現，但呼叫時回傳 app_not_running
4. 第 3 層：應用程式拒絕任務
5. 等待逾時
6. 任務失敗或沒有產生檔案
7. 不需要 AI 宿主的檢查
8. 速查表
9. 常見問題

逐層看可能出錯的地方

一個請求會經過三個環節：

1. 宿主（Cursor、Claude、Codex、DeepSeek Harness、Hermes、OpenClaw）讀取自己的設定，並啟動 KwaFlux 的 MCP 伺服器。
2. MCP 伺服器（在 Windows 上是一支 Node.js 指令碼，在 Mac 上是應用程式內的輔助程式）連到執行中的 KwaFlux 應用程式。
3. KwaFlux 檢查請求，再把任務排進佇列。

第 1 層：宿主裡看不到 KwaFlux 的工具

1. 設定檔格式錯誤。 只要一個錯誤，宿主就可能把檔案裡所有伺服器都略過。

• JSON（Cursor、Claude、OpenClaw）：Windows 路徑要用雙反斜線，例如 C:\\Program Files\\...。不能有註解，也不能有結尾多出來的逗號。
• TOML（Codex）：像 KwaFlux 產生的範例那樣，用單引號括住 Windows 路徑，或把每個反斜線都寫兩次。
• YAML（DeepSeek Harness、Hermes）：保持範例的縮排；單引號會原樣保留反斜線。

2. 放錯檔案或範圍。

3. 找不到 Node.js。 在 Windows 上，宿主會用 Node.js 18 或更新版本啟動伺服器。KwaFlux 的設定卡片會尋找 Node.js，並把它的完整路徑寫進設定。如果卡片顯示「未偵測到 Node.js。宿主需以 Node.js 18 或更高版本啟動此服務，請先安裝。」，或提示你的 Node.js「版本過低」，請安裝目前的 LTS 版本，按下 重新偵測 Node.js，再重新複製一次設定。如果你是自己手寫設定、只填了 "node"，請換成完整路徑，例如 C:\Program Files\nodejs\node.exe，或重新啟動宿主，讓它讀到新的 PATH。

4. 伺服器的路徑不對。 這支指令碼是 KwaFlux 安裝資料夾內 Tools\kwaflux-mcp 裡的 kwaflux_mcp.mjs。如果你沒有把 KwaFlux 裝在 C:\Program Files\KwaFlux，請從 KwaFlux 的 設定 › Agent（MCP） 卡片複製設定，卡片會填入實際路徑。如果卡片警告「未偵測到隨附的 MCP 服務，下方路徑只是佔位符。」，請重新安裝 KwaFlux。

5. 宿主沒有重新載入。 每個宿主的做法不同：

各宿主的詳細設定步驟：Cursor、Claude Code 與 Claude Desktop、Codex、DeepSeek Harness、Hermes 與 OpenClaw。

第 2 層：工具有出現，但呼叫時回傳 app_not_running

這是最容易處理的一種。在 Windows 上，完整訊息長這樣：

app_not_running: Error: app_not_running: no control file of a running KwaFlux in C:\Users\<you>\AppData\Local\KwaFlux\agent

意思是伺服器已經順利啟動，卻找不到正在執行的 KwaFlux 可以溝通。解決方法：

• 開啟 KwaFlux，等視窗出現後再問一次。不需要重新載入宿主。
• 同一台電腦、同一個使用者。 伺服器只連得到在同一台電腦、同一個 Windows 或 macOS 帳號下執行的 KwaFlux。VPS 上的 Agent、Cursor Cloud Agent，或在其他使用者帳號下的工作階段，都連不到它。

第 3 層：應用程式拒絕任務

KwaFlux 拒絕請求時，工具結果會說明原因。常見的有：

像 \\server\share\clip.mp4 這樣的網路路徑，會在開啟任何檔案之前就被刻意拒絕。請先把檔案複製到本機磁碟。原因請見路徑與隱私規則。

等待逾時

KwaFlux 的等待工具一次呼叫最多等 300 秒，預設 60 秒。有些宿主給單次 MCP 呼叫的時間比這更短：

等待逾時並不會中止任務。任務仍會在 KwaFlux 的任務清單裡繼續執行，AI 助理可以再等一次，或查詢它的狀態。

任務失敗或沒有產生檔案

• 看任務的錯誤原因。 問 AI 助理：「取得這個 KwaFlux 任務，告訴我它的錯誤。」任務詳細資料裡會有原因。
• 確認輸出檔放到哪裡。 結果會寫在輸入檔旁邊，而不是 AI 助理指定的資料夾；如果已有同名檔案，舊檔會保留，新檔則改名為 name(1).ext。轉檔後的檔名結尾是 _kwaflux_<format>-<tier>，修復後的檔名結尾是 _repair。
• 修復需要參考檔。 如果診斷結果說需要參考檔，請提供同一台相機拍攝的正常片段。請見影片檔案修復。
• 無法從對話中使用的功能。 補幀，以及去背和替換類工具，不會透過 MCP 提供，請在應用程式裡操作。
• 還是失敗？ 在 KwaFlux 視窗裡直接重試一次。如果在那裡也失敗，那就不是 MCP 的問題；請把任務的錯誤原因寄給客服。

不需要 AI 宿主的檢查

如果不確定伺服器到底能不能啟動，可以在終端機裡手動執行：

node "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

正常的伺服器不會印出任何東西，只會停在那裡等待輸入，因為它在等宿主跟它溝通。按 Ctrl+C 結束。如果反而出現錯誤，例如「not recognized」（中文版 Windows 顯示「不是內部或外部命令、可執行的程式或批次檔」；Node.js 不在 PATH 中）或「Cannot find module」（路徑不對），請先解決這個問題；換哪個宿主結果都一樣。

速查表

結語

先找出是哪一層。看不到工具，就是宿主設定的問題；app_not_running 代表這台電腦上的應用程式沒有開啟；被拒絕時會附上原因；一分鐘左右就失敗，是宿主的逾時。拿不定主意時，就手動執行伺服器：如果它安靜地等待，問題就出在宿主或應用程式，而不是伺服器。

讓 KwaFlux 和你的 AI 助理順利連線

KwaFlux 內建本機 MCP 伺服器，支援 Cursor、Claude、Codex、DeepSeek Harness、Hermes、OpenClaw 和其他 MCP 應用程式。AI 處理在你自己的 GPU 上執行，媒體檔案不會為了處理而上傳。可在 Windows 10（64 位元，1809 或更新版本）、Windows 11，以及搭載 Apple Silicon 的 macOS 12 或更新版本上執行。匯入檔案和瀏覽應用程式都不需要帳號。僅在匯出、轉換、檔案修復和從連結下載檔案時需要登入並購買付費方案。

下載 KwaFlux · 查看方案