# 快速开始 — Godot · AI Game Developer Wiki

将 Godot MCP 连接到云端，接入 Claude Code 等 AI 代理，检查连接，并在 Godot 编辑器中运行你的第一批 AI 提示词。

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

本页将带你从已安装的插件走到能编辑 Godot 场景的 AI 代理。这里假设插件已经在你的项目中；如果没有，请先阅读[安装](https://ai-game.dev/zh-hans/docs/wiki/godot/installation)。以下步骤使用默认的 Cloud 模式，编辑器和你的代理都连接到 [ai-game.dev](https://ai-game.dev)，你只需登录一次。

## 第 1 步：打开项目

用 CLI 打开项目：

```bash
godot-cli open ./MyGodotProject
```

`open` 会先构建 C# 程序集，然后启动编辑器。首次打开时这次构建非常关键：Godot 会立即加载已启用的插件，如果没有构建好的程序集，它会报告无法加载 `GodotMcpPlugin.cs` 并禁用该插件。如果你改为从 Godot 项目管理器打开项目，请先构建一次（编辑器中的 Build 按钮或 `godot-cli build`），并且如果 Godot 关闭了插件，再重新启用它。

插件加载后，编辑器的 Output 面板会输出 `[Godot-MCP] plugin loaded`，**AI Game Developer** 停靠面板会出现在右上方的停靠区域。

## 第 2 步：登录

Cloud 模式需要你的 ai-game.dev 账号。任选以下一种方式：

- 在停靠面板中，保持模式为 **Cloud**，然后点击 **Authorize**。浏览器会打开并显示一个短代码，用你的 ai-game.dev 账号批准即可。
- 在终端中运行 `godot-cli login`。它使用相同的 OAuth 设备流程，并把凭据保存到 `~/.ai-game-dev/credentials.json`，编辑器会自动读取。

每台机器只需登录一次。同一份凭据可用于 Godot MCP、Unity MCP、Unreal MCP、各引擎 CLI 以及 AI Game Dev 应用。该会话会出现在你账号的已连接设备中，你可以在那里撤销它。详情见[身份验证](https://ai-game.dev/docs/auth)。

## 第 3 步：连接你的 AI 代理

为你使用的代理写入 MCP 配置。以 Claude Code 为例：

```bash
godot-cli setup-mcp claude-code ./MyGodotProject
```

这会在项目中写入 `.mcp.json`，其中的 URL 固定指向本项目，因此即使你同时打开多个编辑器，代理也能连到这个编辑器。你也可以在停靠面板中完成同样的操作：在 **AI agent** 区域选择你的代理，然后点击 **Configure**。其他代理（Cursor、VS Code Copilot、Codex、Gemini 等）见[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/godot/connecting-ai-clients)。

配置写入后，重启代理或重新加载它的 MCP 服务器。如果配置位于项目文件夹中，请从该文件夹启动代理（Claude Code 会从它启动时所在的文件夹读取 `.mcp.json`）。

## 第 4 步：检查连接

停靠面板的 **Connection** 区域显示三个代表点的一行：Godot、MCP 服务器和 AI 代理。当编辑器已连接且代理会话处于活动状态时，三个点都会亮起，代理那一行会显示客户端名称。你也可以在终端中等待编辑器响应：

```bash
godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject
```

`wait-for-ready` 会轮询就绪探针（`ping`）直到它响应，默认最长等待两分钟。`status` 会报告该项目是否有编辑器在运行，以及服务器是否响应。

在你的代理中让它列出可用工具，或在 Claude Code 中运行 `/mcp`。你应该能看到 `rql-query`、`rql-mutate`、`script-create` 和 `screenshot-viewport` 等工具。

## 第 5 步：第一批提示词

在代理的对话中试试这些提示词。每一条都对应真实的工具调用，因此你可以看到编辑器中的场景发生变化：

- “添加一个 Node3D 场景，包含一个 Camera3D 和一个 MeshInstance3D 立方体，然后把它保存为 Main.tscn。”
- “创建 3 个立方体，围成半径为 2 的圆。”
- “列出场景中所有 OmniLight3D 及其 energy 值。”
- “为地板创建一个 StandardMaterial3D，并把它的 albedo 颜色设为灰色。”
- “创建一个包含 public float Speed 的 Player.cs 脚本，把它挂到 Player 节点上，然后构建项目。”
- “添加一个名为 jump 的输入动作，绑定到 Space 键。”
- “截取视口的截图，并告诉我你看到了什么。”

代理所做的场景编辑可以撤销：在编辑器中按 Ctrl+Z 即可回退，和你自己的编辑完全一样。场景改动会把场景标记为未保存，所以请让代理保存，或者你自己保存。更多提示词示例见 [Godot 最佳实践](https://ai-game.dev/docs/best-practices/godot)。

## 代理能看到什么、不能看到什么

代理通过插件暴露的工具来工作。它可以借助 RQL 读取场景树、Godot 属性（包括 GDScript 变量）、资源、文件、项目设置、输入映射、autoload、控制台和编辑器状态，也可以查看截图。它无法点击编辑器 UI。完整列表见[工具](https://ai-game.dev/zh-hans/docs/wiki/godot/tools)和 [Godot 工具目录](https://ai-game.dev/docs/tools/godot)。

## 想要完全离线使用？

你可以在自己的机器上运行 MCP 服务器，而不用云端服务。在停靠面板中，将模式切换为 **Custom** 并点击 **Start Server**：插件会从 GitHub 下载对应的服务器构建，启动它并建立连接。然后让你的智能体指向这个本地 URL。参见 [Connecting AI clients](https://ai-game.dev/zh-hans/docs/wiki/godot/connecting-ai-clients#custom-mode)。

## 后续步骤

- [Configuration](https://ai-game.dev/zh-hans/docs/wiki/godot/configuration)：停靠面板、日志级别，以及智能体可以看到哪些工具。
- [Extensions](https://ai-game.dev/zh-hans/docs/wiki/godot/extensions)：添加 AnimationPlayer、CSG、导航、tilemap 和插件支持。
- [Troubleshooting](https://ai-game.dev/zh-hans/docs/wiki/godot/troubleshooting)：如果上述某一步没有成功。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/godot/getting-started

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