本页由英文机器翻译而成。阅读英文原文。

故障排查

解决常见的 Unreal MCP 问题：插件无法加载、缺少 bridge、连接卡住、AI agent 没有 Unreal 工具、构建过期以及工具报错。

更新于 2026年11月4日 查看 Markdown 版本

本页列出人们在使用 Unreal MCP 时最常遇到的问题以及解决方法。请先做快速检查，然后跳转到对应的小节。

快速检查

  1. 插件是否已加载？ 编辑器启动后，Output Log 中应出现 [Unreal-MCP] plugin loaded。
  2. 窗口显示了什么？ 打开 Tools、AI Game Developer，查看状态行（Connected、Connecting、Reconnecting、Disconnected 或 No MCP bridge）。
  3. CLI 看到了什么？ 运行 unreal-mcp-cli status --path ./YourProject。
  4. 查看日志。 使用窗口中的 Open log file，在 Output Log 中按 LogUnrealMcp 类别过滤，或者让 agent 执行 console | where Verbosity == "Error"。

插件无法加载

如果没有 [Unreal-MCP] plugin loaded 这一行，说明编辑器模块启动失败。

  • 在 Output Log 中查找插件启动错误或损坏的 .uplugin。
  • 确认该项目是C++ 项目，并且编译器工具链可正常工作。参见安装。
  • 如果 Unreal 提示缺少模块或插件不兼容，请让它重新构建，或者用 unreal-mcp-cli open ./YourProject 打开项目，该命令会先构建原生模块并自动跳过这些提示。

更新后没有生效

当插件源码发生变化、但旧的 Intermediate/ 文件夹仍然存在时，Unreal 的增量构建可能会保留旧的插件代码。

  • 使用 unreal-mcp-cli update ./YourProject 进行更新，该命令默认会清理构建缓存。
  • 如果是手动复制：关闭编辑器，删除 Plugins/UnrealMCP/Intermediate/ 以及 Plugins/UnrealMCP/Binaries/ 中的 C++ 文件（保留 Binaries/ThirdParty/），然后重新打开。

“No MCP bridge”或 bridge 反复重启

插件需要其 bridge 进程 unreal-mcp-bridge。窗口中会显示 bridge 状态和重启次数。

  • 如果日志中出现 no sidecar binary resolved for rid <rid>，说明没有找到 bridge。
    • App 或 CLI 安装： bridge 是随包附带的。请用 unreal-mcp-cli install-plugin ./YourProject（或通过 App）重新安装；该软件包可能不包含你所在的平台。
    • 源码检出： 用 unreal-mcp-cli bootstrap-local ./YourProject 构建一个 bridge，或者设置 UNREAL_MCP_BRIDGE_PATH。
  • 排除原因后，在窗口底部点击 Restart bridge。

卡在“Connecting”或“Reconnecting”

  • Cloud 模式： 检查是否已登录。如果窗口显示“Sign in required”，说明保存的登录已过期；点击 Authorize 并批准新的验证码。
  • 检查该机器能否访问 ai-game.dev（代理或防火墙规则）。
  • Custom 模式： 确认本地服务器正在运行（在 MCP server 卡片中点击 Start，或使用 --start-server），并且 Server URL 指向它。
  • 使用 Disconnect，然后 Connect，或点击 Restart bridge。

本地服务器提示“No connected clients”

如果本地的 gamedev-mcp-server 记录 No connected clients. Retrying 并以 HTTP 500 响应，说明编辑器仍处于 Cloud 模式，连接的是 ai-game.dev 而不是你的本地服务器。请在窗口中切换到 Custom，设置 UNREAL_MCP_CONNECTION_MODE=Custom，或者向 unreal-mcp-cli open 传入 --connection-mode Custom（或 --host）。

AI agent 没有 Unreal 工具

  • 检查 agent 的配置：运行 unreal-mcp-cli setup-mcp <agent> --path ./YourProject --dry-run 并对比结果，或者在 AI agent 区域点击 Configure（或 Reconfigure）。
  • 配置更改后重启或重新加载 agent。许多客户端只在启动时读取 MCP 配置。
  • Claude Code 会从启动它时所在的文件夹读取 .mcp.json；请在项目文件夹中启动它。
  • 如果你在从未打开过编辑器的情况下用 setup-mcp 进行了配置，配置可能指向 localhost 而不是云端。请先打开一次项目，然后再次运行 setup-mcp，或者传入 --url。
  • 检查 Connection 区域中的 AI agents 行。如果你的 agent 未列出，说明它没有连接到与编辑器相同的服务器。
  • 如果你在 MCP Tools 窗口中隐藏了工具或设置了 UNREAL_MCP_TOOLS，agent 能看到的工具会变少。

agent 连接到了错误的编辑器

同一账号下有多个编辑器时，请使用项目固定 URL（/mcp/p/<pin>），setup-mcp 默认会写入该地址。重新运行 setup-mcp，不要加 --no-pin。参见连接 AI 客户端。

agent 中出现 401 错误

  • 在 Cloud 模式下，仅含 URL 的配置需要智能体自行登录。可以让它执行自己的 OAuth 登录，或者先在这台机器上登录（unreal-mcp-cli login）并再次运行 setup-mcp，这样配置中就会带上项目密钥。
  • 如果项目密钥已被吊销，请使用编辑器中的 Regenerate key 或 setup-mcp --regenerate-key。
  • 在使用 token 认证的 Custom 模式下，配置中的 token 必须与编辑器中的一致。生成新 token 后请使用 Reconfigure。

工具调用超时

单次工具调用默认最多运行 5 分钟。对于耗时较长的 Python 脚本或大型导入，可以调高 UNREAL_MCP_TOOL_TIMEOUT（毫秒）。python-execute 还有自己的 timeout（默认 30 秒），可由智能体在每次调用时设置。

截图工具返回错误

像素捕获需要由 GPU 支持的编辑器。在 -nullrhi 下，截图工具会返回结构化错误。unreal-mcp-cli exec 和 open --headless 启动的编辑器会进行离屏渲染，因此在那里捕获仍然可用。

Python 工具失败

python-execute 使用 Unreal 的 Python Editor Script Plugin，该插件由 Unreal MCP 启用。如果 Python 不可用，请检查是否已在 Edit, Plugins 中启用该插件。错误会指向 snippet.py 中的行，该文件就是智能体发送的代码。

扩展未显示

  • 扩展需要 Unreal Engine 5.7 或更高版本，以及 Unreal MCP 0.26.0 或更高版本。
  • 安装后，扩展必须被编译：重新打开编辑器、使用 --build，或在 Extensions 区域使用 Compile (Live Coding)。
  • 检查该扩展是否已在 Extensions 区域中启用。

仍然卡住了？

  • 请参阅 FAQ 和通用 FAQ。
  • 使用窗口中的 Help / Talk 在 Discord 上提问，或使用 Bug Report 提交 GitHub issue。请附上 Unreal 版本、操作系统、窗口的状态行以及相关日志行（切勿附上你的 token）。