KwaFlux MCP 用不了？工具不出现、app_not_running 和超时的解决办法

要点速览

• 由外向内排查：宿主有没有启动服务？服务有没有连上应用？应用有没有接下任务？
• 如果一个 KwaFlux 工具都看不到，十有八九是宿主配置的问题：JSON 或 YAML 写错、改错了文件、找不到 Node.js，或者没重新加载。
• app_not_running 说明服务本身没问题，只是 KwaFlux 没开（或者不在同一台电脑上）。
• 等了一分钟左右就失败，是宿主的超时，不是任务失败。任务在 KwaFlux 里照样在跑。

KwaFlux 的 MCP 连接出问题时，症状本身就告诉你该查哪一层：要么宿主没把服务启动起来，要么服务连不上应用，要么应用拒绝了请求。每一层的原因都不多，每个原因都有明确的解法。

本文会讲怎么区分这三层、每层的修法、KwaFlux 返回的错误信息，以及一个不依赖任何 AI 宿主、两分钟就能做完的检查。

目录

1. 一层一层看哪里会出错
2. 第一层：宿主里看不到 KwaFlux 工具
3. 第二层：工具都在，调用却报 app_not_running
4. 第三层：应用拒绝了任务
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 检查请求，把任务排进队列。

第一层：宿主里看不到 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 版本过低，需要 18 或更高版本”，就装好当前的 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。

第二层：工具都在，调用却报 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 的云端 Agent，或者另一个用户账户下的会话，都连不上它。

第三层：应用拒绝了任务

KwaFlux 拒绝请求时，工具结果会写明原因。常见的有：

像 \\server\share\clip.mp4 这样的网络路径，是有意在打开任何文件之前就拒绝的。先把文件复制到本机硬盘。原因见路径与隐私规矩。

等待超时

KwaFlux 的等待工具一次最多等 300 秒，默认 60 秒。有些宿主给一次 MCP 调用的时间比这短：

一次等待超时不会让任务停下。任务仍在 KwaFlux 的任务列表里跑，助手可以再等，或者去查它的状态。

任务失败或没有产出

• 看任务的错误原因。 问助手：“查一下这个 KwaFlux 任务，告诉我它的错误。”任务详情里有原因。
• 看看产物去哪儿了。 结果写在输入文件旁边，而不是助手指定的文件夹；那里已有同名文件时，旧文件保留，新文件改名为 name(1).ext。转换出的文件以 _kwaflux_<格式>-<档位> 结尾，修好的文件以 _repair 结尾。
• 修复需要参考文件。 如果诊断说需要参考文件，就给一段同一台相机拍的正常视频。见视频文件修复。
• 对话里做不了的事。 智能补帧，以及抠像和替换类工具，都没有通过 MCP 开放，请在应用里做。
• 还是失败？ 在 KwaFlux 窗口里亲自重试一次。如果在应用里也失败，那就不是 MCP 的问题，把任务的错误原因发给客服。

不用任何 AI 宿主的检查

如果拿不准服务到底能不能启动，就在终端里手动运行它：

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

正常的服务什么都不输出，停在那里等输入，因为它在等宿主来跟它说话。按 Ctrl+C 结束。如果出现报错，比如“不是内部或外部命令”（Node.js 不在 PATH 中）或“Cannot find module”（路径错了），先把它解决，否则换哪个宿主都没用。

速查表

结语

先找出是哪一层。看不到工具，查宿主配置；app_not_running，说明这台电脑上应用没开；被拒绝时，结果会写明原因；一分钟左右就失败，是宿主超时。拿不准的时候，手动运行一下服务：如果它安静地等着，问题就在宿主或应用，而不在服务本身。

让 KwaFlux 和你的助手顺利配合

KwaFlux 自带本地 MCP 服务，支持 Cursor、Claude、Codex、DeepSeek Harness、Hermes、OpenClaw 等 MCP 应用。AI 处理在你自己的 GPU 上运行，媒体文件不会为了处理而上传。可在 Windows 10（64 位，1809 或更新版本）、Windows 11，以及搭载 Apple Silicon 的 macOS 12 或更新版本上运行。导入文件和浏览应用都不需要账号。仅在导出、转换、文件修复和从链接下载文件时需要登录并购买付费方案。

下载 KwaFlux · 查看方案