故障排查

大多数 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# 项目中。参见扩展。

编辑器无法连接#

• 云模式，未登录。 在停靠面板中点击 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。
• 工具被隐藏了。请查看停靠面板的 MCP 功能区域，或运行 godot-cli configure --list。隐藏的工具不会向 agent 列出。

C# 重新构建期间工具调用失败#

构建出的 DLL 发生变化后（script-build、Build 按钮或 dotnet build），Godot 会在约半秒后重新加载项目的 C# 程序集。该插件是此程序集的一部分，因此它会被销毁、重新构建，并在几秒内重新连接。在重新加载前后，新的调用会被拒绝并返回可重试的错误（“Godot is about to reload the project's C# assembly … Retry in a few seconds”）。请稍等后重试；script-build 会在重新加载完成后返回结果。

在 .NET 10 上重新加载后编辑器崩溃或卡死#

这是 .NET 运行时的一个 bug（dotnet/runtime#135441）。在 .NET 10 的维护修复版本发布之前，请为编辑器进程设置以下环境变量，并重启 Godot：

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

在 Windows 上，可以用 setx DOTNET_ThreadPool_ThreadsToKeepAlive -1 进行设置。由 godot-cli open 或 exec 启动的编辑器会自动获得该设置。当你的 .NET 运行时包含此修复后，请移除该变量。

调用发往了旧的构建版本#

如果工具调用的表现像是你代码的旧版本，那么同一个项目可能连接了多个编辑器，例如一个被遗忘的无头编辑器。请关闭多余的编辑器（godot-cli close --owned-only 会关闭由 godot-cli 启动的编辑器），只保留一个编辑器连接。

构建失败并报 MissingMethodException#

项目的 Godot.NET.Sdk 版本应与你所运行的编辑器一致。基于 4.3 构建的项目在 4.4 或更新版本的编辑器上（API 已发生变化）可能抛出 MissingMethodException。请把 .csproj 中 Sdk="Godot.NET.Sdk/…" 的版本改为你的编辑器版本，然后重新构建。

仍然卡住#

请查看常见问题和站点常见问题，或者到 Godot-MCP issue tracker 上报告问题，并附上 Output 面板日志以及你的 Godot、.NET 和插件版本。