Godot AI 使用文档与踩坑记录

Godot AI 是一个开源的 Godot 编辑器插件，它把正在运行的 Godot 编辑器接入 MCP，让 Claude Code、Claude 桌面版、Codex、Cursor 这类 AI 客户端可以直接建场景、改节点、写脚本、连信号、运行游戏。我的五子棋、十点半、大富翁都是用它加 Claude Code 做的。

这篇是我自己的使用笔记，前半部分是用法，后半部分是实际踩过的坑。插件更新很快，具体细节以官方 README 为准。

它是怎么工作的

AI 客户端（Claude Code 等）
  → godot-ai attach（stdio，客户端自己拉起）
  → Python 后端（本机 HTTP，默认端口 8000）
  → Godot 编辑器插件（本机 WebSocket，默认端口 9500）

几点要先搞清楚，后面排错全靠它：

  • 插件版本和 Godot 版本是两回事。 插件也叫 v4.x，很容易跟 Godot 4.x 搞混。v4 插件要求 Godot 4.7 及以上。
  • 后端是 Python，用 uvx 临时下载运行，所以电脑上必须装 uv。
  • 两段连接都只走本机（127.0.0.1），而且带轮换的认证。所以客户端配置不能手写成一个 http://127.0.0.1:8000/mcp 地址，必须用插件生成的那条 godot-ai attach 命令。
  • GDScript 完全支持；C# 只能写文件，不会帮你编译、也不报编译错误。

安装

新项目

  1. 装好 uv（Windows 用官方安装命令，不要用来路不明的“懒人包”）。
  2. 从 GitHub Releases 下载发布包，不要直接下载仓库源码。
  3. 放到 你的项目/addons/godot_ai/，确认 plugin.cfg 就在这个目录里，而不是在 addons/plugin.cfg。
  4. Godot 里打开 项目 → 项目设置 → 插件，勾选 Godot AI。右侧会出现 Godot AI 面板。

已经装过的项目

在 Godot AI 面板里点 Update。不要把新版本解压覆盖到旧的 addons/godot_ai 上，原因见后面“插件更新/迁移”一节。

小技巧：做一个模板项目

我把一个装好插件、写好通用 CLAUDE.md（用 GDScript、注释用中文、先讲方案再写代码）的空项目存成模板。以后开新游戏就复制整个文件夹、改名，在项目管理器里点 导入，再到 项目设置 → 应用 → 配置 → 名称 改成新名字。

连接 AI 客户端

  1. 在 Godot AI 面板里，找到要用的客户端，点它那行的 Configure（或者 Configure all）。
  2. 完全重启客户端：
    • Claude Code：退出后在项目根目录重新运行 claude。
    • Claude 桌面版：不只是关窗口，要在任务栏托盘图标上右键退出，再重新打开。
  3. 确认连上了：
    • Claude Code：输入 /mcp，看 godot-ai 是否为 connected。
    • Claude 桌面版：看 设置 → 开发者（不是“连接器”页面），godot-ai 显示 running 就成功。

几条容易忽略的规则：

  • 生成的命令很长（pythonw 包一层 uvx 再调 godot-ai），不要手动“简化”它。Windows 上 pythonw 那层是必需的。
  • 改了端口、遥测设置或工具范围之后，要重新点一次 Configure。
  • Claude Code 默认写入全局（user）配置。想按项目配置，在 编辑器设置 → Plugins → godot_ai/mcp_client_scope 改成 project，再点 Configure。注意 Configure 会先删掉其他范围里的 godot-ai 条目，可能改到你提交过的 .mcp.json。
  • 最好从项目目录启动 Godot 和 Claude Code。Claude Code 第一次在项目里用项目级配置，还需要在项目里运行 claude 批准一次。

日常用法

在 Claude Code 里直接用中文说需求，它会自己调用 Godot 的工具。先试几个简单的确认能用：

看一下当前场景里有哪些节点

在 /Main 下面建一个叫 MainCamera 的 Camera3D

然后再做正经的东西。我总结的几个习惯：

  • 先让它用中文讲方案，确认后再写代码。 能避免它跑偏、白白浪费 token。
  • 开发文档放进项目文件夹（比如 docs/设计文档.md），用 @docs/设计文档.md 引用，不要整段粘贴。长期要遵守的规则写进 CLAUDE.md，它每次启动都会自动读。
  • Godot 编辑器要一直开着这个项目，插件服务跟着编辑器跑。
  • 从项目根目录启动 claude，不要在 scripts 之类的子文件夹里启动，否则它看不到整个项目和 CLAUDE.md。
  • 手感还得自己试。 AI 能自己运行游戏、截图检查，但像素级对齐、动画手感这些，还是自己按 F5 玩一下，再给具体反馈（比如“粒子出现在棋盘左侧，应该在落子位置”）。
  • 开工前先 git 初始化并提交一次，改坏了能回退。

踩坑记录

1. Claude 桌面版显示 “Server disconnected”

现象： Claude 桌面版里的 godot-ai 一直是 Server disconnected。

排查： 在 设置 → 开发者 里点 查看日志。我的日志里每次启动都报：

godot-ai attach [PORT_OCCUPIED]: Port 8001 is occupied by a process the bridge cannot adopt

意思是端口被别的东西占着，attach 桥既不能复用它，也起不了自己的后端，只能退出。

原因： 出问题那天我刚装了 WSL 和 Docker。装了 WSL、Docker 或 Hyper-V 之后，Windows 会随机保留一批端口给虚拟网络用。被保留的端口在 netstat 里看不到任何程序在监听，但谁都绑不上。

解决：

  1. 先看是不是真有程序占着：

    netstat -ano | findstr :8001
tasklist /fi "pid eq 这里填PID"

    如果是残留的 python.exe、pythonw.exe 或 godot-ai.exe，关掉 Godot 和 Claude，再 taskkill /pid PID /f。

  2. netstat 什么都没有，就看是不是被系统保留了：

    netsh interface ipv4 show excludedportrange protocol=tcp

    如果 8001 落在某个保留段里，换一对不在保留段里的端口（比如 8765/8766）：在 编辑器设置 → Plugins → godot_ai 里改端口，然后在面板里重新点 Configure，再彻底退出并重开 Claude。

    也可以用管理员身份运行 net stop winnat 和 net start winnat 让系统重新分配，但保留段每次重启都可能变，换端口更省心。

其他可能原因： Windows 上 uvx 安装 pywin32 失败；第一次从 PyPI 下载太慢导致超时。通用处理方法都是：关掉 Godot 和客户端，结束残留的 Python 进程，重开 Godot，点 Configure，再开客户端。

2. 插件更新/迁移被拦下：“An open scene or resource references addon script…”

现象： 在面板里点更新，提示：

An open scene or resource references addon script res://addons/godot_ai/migration_bridge.gd.
In-editor activation would change its saved script path. Close the scene or resource
before retrying; the update was not installed.

意思是：有一个打开着的场景或资源引用了插件的 migration_bridge.gd，这时激活新版会改掉它保存的脚本路径，所以更新没装。

处理顺序：

  1. 关掉所有场景标签页，再点 Retry migration。
  2. 还不行，去 脚本 工作区，用 文件 → 全部关闭 关掉所有打开的脚本。脚本编辑器里开着的文件也算“打开的资源”。
  3. 再不行，项目 → 重新加载当前项目。重开后先别打开任何场景或脚本，直接点 Retry migration。

不要做的事：

  • 不要把新版解压覆盖到旧的 addons/godot_ai 上。 官方迁移是“校验新版文件 → 准备一份全新目录 → 整个替换旧目录，旧目录移到项目外的恢复位置”，新旧版本的文件从不混在一起。手动覆盖会把两个版本混在一起。
  • 不要为了“强制推进”去删 .godot 里的迁移记录、插件目录或恢复目录。 迁移是有记录的，重开项目时由这些记录决定是继续、回滚还是停住。
  • 如果提示需要修复（repair required），关掉 Godot，保留完整的报错和那些目录，带着报错里的原始路径去 GitHub Issues 或 Discord 提问。

迁移前最好先 git 提交一次。Godot 4.5/4.6 只能看到“需要 Godot 4.7”的提示，先升级 Godot 再点 Retry migration。

3. 复制插件到新项目后报 Parse error

现象： Failed to load script "res://addons/godot_ai/utils/release_verifier.gd" with error "Parse error"。

原因： 多半是插件刚复制进来或刚更新，Godot 还没扫描完所有文件，插件脚本互相引用时误报；也可能是 Godot 开着时复制，文件没复制完整。

解决： 先 项目 → 重新加载当前项目，一般就好了。不行的话，关掉 Godot 重新完整复制一份插件。

现在回头看，新项目更规范的做法是从 Release 包安装，而不是从旧项目复制插件文件夹。另外，如果插件正在迁移中，不要去删 .godot（见上一条）。

4. 插件被 .gitignore 排除后，别的电脑打不开项目

现象： 项目里把 addons/godot_ai 加进了 .gitignore，但 project.godot 是提交的。

问题： 插件可能会往 project.godot 里注册东西（比如 [autoload] 下的 _mcp_game_helper，或者 [editor_plugins] 里的启用项）。换台电脑拉代码时插件不在，autoload 指向的文件找不到，项目就会报错；导出的安装包里也可能带上这个调试辅助脚本。

检查方法：

  • 快速看：用记事本打开 project.godot，搜 godot_ai 和 _mcp_game_helper。出现在 [autoload] 下就有问题；只在 [editor_plugins] 下问题不大，只是没装插件时编辑器提示一下。
  • 实际验证：git clone 项目目录 项目目录_check，克隆出的副本没有插件，用 Godot 导入打开、按 F5 跑一下，看有没有相关报错。检查完在项目管理器里移除它，再删掉文件夹。

解决： 让 Claude Code 改成“没装插件的副本也能正常打开运行，导出包里不包含插件和它的辅助脚本”。

5. 用 DeepSeek 跑 Claude Code 时报 422

这个不是插件本身的问题，但装了 Godot AI 后工具变多，很容易遇到。

  • Invalid schema for function 'Artifact'： DeepSeek 的兼容接口不认 Claude Code 某些内置工具的参数格式。启动时禁掉它：claude --disallowedTools Artifact，报别的工具名就一起加上。
  • 会话前半段是 Claude 做的，切到 DeepSeek 后一直 422： 聊天记录里已经混进了 DeepSeek 不认的格式。开新会话（/clear），用进度文件交接，不要让 DeepSeek 接着 Claude 做了一半的会话。
  • 在 DeepSeek 下也先 /mcp 看看 godot-ai 连没连上，再给个只读的小任务试一下工具调用。
  • Godot 编辑器的操作最好只让一个窗口做，两个窗口同时操作编辑器、同时改同一个文件，容易互相覆盖。

一张速查表

现象 先做什么
插件列表里没有 Godot AI 确认 plugin.cfg 在 addons/godot_ai/ 里
客户端看不到工具 重新 Configure，再彻底重启客户端
Server disconnected 看日志；端口被占或被保留就换端口
更新提示有场景/资源引用插件脚本 关场景、关脚本，重新加载项目，Retry migration
插件脚本 Parse error 重新加载项目
别的电脑打不开项目 查 project.godot 里的 autoload
DeepSeek 422 禁掉不兼容的工具，开新会话

参考