# 疑難排解 — 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++ project**，且編譯器工具鏈可正常運作。請參閱 [Installation](https://ai-game.dev/zh-hant/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）重新安裝；該套件可能不包含你的平台。
  - **原始碼 checkout：** 使用 `unreal-mcp-cli bootstrap-local ./YourProject` 建置一個，或設定 `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`。請參閱 [Connecting AI clients](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients#pinned-url)。

## agent 出現 401 錯誤

- 在 Cloud 模式下，只有 URL 的設定需要由 agent 自行登入。你可以讓它執行自己的 OAuth 登入流程，或是在這台機器上登入（`unreal-mcp-cli login`）後再執行一次 `setup-mcp`，讓設定帶有 project key。
- 如果 project key 已被撤銷，請在編輯器中使用 **Regenerate key**，或執行 `setup-mcp --regenerate-key`。
- 在 Custom 模式搭配 **token** 驗證時，設定必須帶有與編輯器相同的 token。產生新 token 後，請使用 **Reconfigure**。

## 工具呼叫逾時

單次工具呼叫預設最多可執行 5 分鐘。若是長時間的 Python 腳本或大型匯入，請調高 `UNREAL_MCP_TOOL_TIMEOUT`（毫秒）。`python-execute` 另外有自己的 `timeout`（預設 30 秒），可由 agent 在每次呼叫時設定。

## 截圖工具傳回錯誤

像素擷取需要有 GPU 支援的編輯器。在 `-nullrhi` 之下，截圖工具會傳回結構化錯誤。`unreal-mcp-cli exec` 與 `open --headless` 啟動的編輯器會進行離屏算繪，因此在那裡截圖仍可正常運作。

## Python 工具失敗

`python-execute` 使用 Unreal 的 Python Editor Script Plugin，而 Unreal MCP 會啟用該外掛。如果 Python 無法使用，請到 **Edit, Plugins** 確認該外掛已啟用。錯誤訊息會指向 `snippet.py` 的行號，那是 agent 送出的程式碼。

## 擴充功能沒有顯示

- 擴充功能需要 Unreal Engine 5.7 以上版本，以及 Unreal MCP 0.26.0 以上版本。
- 安裝後，擴充功能必須經過編譯：重新開啟編輯器、使用 `--build`，或在 Extensions 區段使用 **Compile (Live Coding)**。
- 確認擴充功能已在 Extensions 區段中啟用。

## 還是卡住了嗎？

- 請參閱 [FAQ](https://ai-game.dev/zh-hant/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-hant/docs/wiki/unreal/troubleshooting

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