# 故障排查 — Unreal Engine · AI Game Developer Wiki

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

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unreal/troubleshooting)。

本页列出人们在使用 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++ 项目**，并且编译器工具链可正常工作。参见[安装](https://ai-game.dev/zh-hans/docs/wiki/unreal/installation#requirements)。
- 如果 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 客户端](https://ai-game.dev/zh-hans/docs/wiki/unreal/connecting-ai-clients#pinned-url)。

## 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](https://ai-game.dev/zh-hans/docs/wiki/unreal/faq) 和通用 [FAQ](https://ai-game.dev/docs/faq)。
- 使用窗口中的 **Help / Talk** 在 Discord 上提问，或使用 **Bug Report** 提交 GitHub issue。请附上 Unreal 版本、操作系统、窗口的状态行以及相关日志行（切勿附上你的 token）。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/unreal/troubleshooting

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/unreal/troubleshooting