疑難排解

大多數 Godot MCP 問題都出自以下四個原因之一：Godot 組建版本不對、.csproj 與附加元件不相符、C# 組件尚未建置，或是 AI 用戶端沒有指向正確的伺服器。請依照你看到的狀況，閱讀對應的章節。如果卡住了，把停靠面板的 Log Level 調高為 Debug，重現問題並查看 Output 面板。

附加元件無法載入#

第一次開啟時出現「Unable to load addon script」#

Godot 會在編輯器啟動時立即具現化已啟用的附加元件。第一次開啟從未建置過的 C# 專案時，還沒有任何組件，因此 Godot 會回報無法載入 res://addons/godot_mcp/Editor/GodotMcpPlugin.cs，並停用該附加元件。

修正方式：先建置，然後在 Project, Project Settings, Plugins 重新啟用外掛。

godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject

godot-cli open 一律會先建置再啟動編輯器，因此可避開這個問題。

附加元件無法編譯#

• 你用的是標準 Godot 組建。Godot MCP 需要 Godot 4.3 或更新版本的 .NET (mono) 組建。
• .csproj 缺少 NuGet 套件，或版本與你安裝的附加元件不同。請重新執行 godot-cli install-plugin，或依照你的附加元件版本，從安裝複製該區塊。
• 專案沒有 .csproj。請從 Godot 建立 C# 方案，或使用 godot-cli create-project --dotnet 建立新專案。
• 未安裝 .NET 8 SDK，或它不在 PATH 上。

NuGet 組件發生 FileNotFoundException#

Godot 在編輯器中不會自行解析專案的 NuGet 套件；附加元件會讀取建置產生的 .deps.json 和你的 NuGet 快取來完成這件事。如果仍然找不到某個組件，請執行 dotnet restore 後重新建置。若問題持續，刪除 .godot/mono/temp/obj 和 .godot/mono/temp/bin 再重新建置：過期的建置輸出通常是主因。

用 Play 啟動的遊戲無法建立 C# 指令碼#

症狀：在出現指名某個 EditorPlugin 類別的 TypeLoadException 之後，每個 C# 指令碼都會失敗並顯示「Cannot instantiate C# script because the associated class could not be found」。你的 .csproj 缺少 <EnableDynamicLoading>true</EnableDynamicLoading>，因此套件組件沒有複製到遊戲組件旁邊。請將它加到 <TargetFramework> 旁邊的 <PropertyGroup> 中並重新建置。godot-cli install-plugin 和 create-project 會自動幫你設定。

Extensions 清單是空的#

停靠面板會從你編譯後的專案讀取擴充功能目錄。你的 .csproj 需要加上這一行，然後重新建置：

<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />

LogicalName 必須完全等於 Godot-MCP.extensions.catalog.json。如果停靠面板顯示找不到 .csproj，表示附加元件不在 Godot C# 專案中。請參閱 Extensions。

編輯器無法連線#

• 雲端模式，但尚未登入。 在停靠面板按一下 Authorize，或執行 godot-cli login。停靠面板會顯示你的登入狀態。
• 被環境變數覆寫。 出現黃色提示「Overridden by environment (GODOT_MCP_*)」表示有變數或 .env 檔強制指定模式或主機，在停靠面板做的變更不會生效。請移除或修改該變數。
• 自訂模式，但沒有伺服器。 在停靠面板按一下 Start Server，或自行啟動伺服器。離線時，伺服器下載會失敗並在 Output 面板顯示警告，且不會啟動本機伺服器；請改用雲端模式，或執行你已經有的伺服器。
• 自訂模式，並在遠端主機上使用 oauth。 附加元件只會把帳號權杖傳送給 localhost 伺服器。其他主機請設定 GODOT_MCP_TOKEN，否則連線會失敗並顯示「Refusing to send your ai-game.dev account token」。

請在終端機以 godot-cli status ./MyGodotProject 和 godot-cli wait-for-ready ./MyGodotProject 檢查。

AI 代理程式看不到任何 Godot 工具#

• 代理程式在設定檔寫入之前就已啟動。請重新啟動它，或重新載入它的 MCP 伺服器。
• Claude Code 會從它啟動所在的資料夾讀取 .mcp.json。請在專案資料夾中啟動它，或把設定寫在你啟動它的位置。
• 同時連線了多個編輯器，而代理程式使用一般的 /mcp URL。請改用 setup-mcp 預設寫入的固定 URL，讓代理程式連到正確的專案。
• 設定指向的伺服器與編輯器不同（雲端 vs 本機）。變更模式後請重新執行 godot-cli setup-mcp <agent>，或在停靠面板按一下 Reconfigure。
• 工具已被隱藏。請檢查 dock 的 MCP features 區段，或執行 godot-cli configure --list。隱藏的工具不會列給 agent。

C# 重建期間工具呼叫失敗#

建置後的 DLL 變更約半秒後，Godot 會重新載入專案的 C# 組件（script-build、Build 按鈕或 dotnet build）。addon 屬於該組件的一部分，因此會被卸載、重建，並在幾秒內重新連線。重新載入前後，新的呼叫會被拒絕並回傳可重試的錯誤（「Godot is about to reload the project's C# assembly … Retry in a few seconds」）。請稍候再重試；script-build 會在重新載入後才送出結果。

在 .NET 10 上重新載入後編輯器崩潰或卡住#

這是 .NET 執行階段的錯誤（dotnet/runtime#135441）。在 .NET 10 的維護更新修正推出前，請為編輯器行程設定這個環境變數，並重新啟動 Godot：

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

在 Windows 上可以用 setx DOTNET_ThreadPool_ThreadsToKeepAlive -1 設定。透過 godot-cli open 或 exec 啟動的編輯器會自動取得此設定。等你的 .NET 執行階段包含修正後，請移除這個設定。

呼叫送到舊的建置版本#

如果工具呼叫的行為像是你程式碼的舊版本，可能是同一個專案連上了多個編輯器，例如忘記關閉的 headless 編輯器。請關閉多餘的編輯器（godot-cli close --owned-only 會關閉由 godot-cli 啟動的編輯器），只保留一個編輯器連線。

建置失敗並出現 MissingMethodException#

專案的 Godot.NET.Sdk 版本應與你執行的編輯器相符。以 4.3 建置的專案，在 API 已變更的 4.4 或更新版編輯器上可能會擲出 MissingMethodException。請將 .csproj 中的 Sdk="Godot.NET.Sdk/…" 版本更新為你的編輯器版本，然後重新建置。

還是卡住#

請查看常見問題與網站的常見問題，或帶著 Output 面板的記錄檔，以及你的 Godot、.NET 與 addon 版本，到 Godot-MCP 問題追蹤器回報問題。