快速开始
使用 Unity MCP 将你的第一个 AI 智能体连接到 Unity 编辑器，检查连接状态，并在 Claude Code、Cursor 或 Copilot 中尝试你的第一批提示词。
本页将带你从已安装插件一路走到让 AI 智能体修改你的 Unity 场景。页面使用通过 ai-game.dev 的默认 Cloud 连接，并以 Claude Code 作为示例智能体；其他客户端步骤相同。如果插件尚未安装，请先从安装开始。
第 1 步：打开 AI Game Developer 窗口
在 Unity 中打开你的项目，选择 Window > AI Game Developer — MCP（Ctrl+Alt+A，macOS 上为 Cmd+Option+A）。该窗口的标签页名称为 Game Developer。你也可以点击 Scene View 工具栏中的 AI 按钮。
窗口以从上到下的时间线展示连接关系：先是 Unity，然后是 MCP server，最后是 AI agent。每个节点都有一个状态圆圈。你的目标是让这三个节点都变为绿色。
第 2 步：登录（Cloud 模式）
顶部的 Connection 开关有两个选项：Custom 和 Cloud。全新安装默认使用 Cloud。
- 点击 Cloud Token 字段旁的 Authorize。
- 浏览器会打开 ai-game.dev 的设备登录页面。窗口中会显示一个短代码（“Code: … — Authorize in browser”）。确认浏览器显示的代码与之一致，然后批准登录。
- 该字段会变为“Signed in via account”，同时 Unity 状态变为 Connected。
登录信息会以整机为单位存储在 ~/.ai-game-dev/credentials.json 中。如果你已经通过 unity-mcp-cli login 或 AI Game Dev 应用登录过，编辑器会自动读取该凭据，你可以跳过这一步。更多细节请参阅身份验证。
第 3 步：配置你的 AI 智能体
- 在 AI agent 区域，从下拉列表中选择你的客户端，例如 Claude Code。
- 在 Model Context Protocol (MCP) 下，点击 Configure。插件会写入该客户端的 MCP 配置文件（对于 Claude Code，是项目根目录下的
.mcp.json），其中包含固定指向此项目的 URL。 - 在 Skills 下，开启 Auto-generate 或点击 Generate。这会写入技能文件，智能体通过阅读这些文件来学习如何使用 Unity MCP 和 RQL（对于 Claude Code，写入
.claude/skills）。支持技能的智能体在使用这些文件后表现会明显更好。 - 从项目文件夹启动你的 AI 客户端；如果它已经在运行，请重启它，以便加载新配置。
同样的操作也可以在终端中完成：
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-skills claude-code ./MyUnityProjectsetup-skills 需要编辑器处于打开且已连接的状态。其他客户端和手动配置方式请参阅连接 AI 客户端。
第 4 步：检查连接
- 在窗口中，Unity 状态显示为 Connected，并且 AI agent 节点显示你的客户端已完成配置。
- 在你的 AI 客户端中，列出 MCP server 或工具。在 Claude Code 中运行
/mcp；你应该能看到ai-game-developer，其中包含rql-query、rql-mutate、rql-schema、script-execute、screenshot-isolated、tests-run和unity-tool-list等工具。 - 如果你的客户端在 Unity 就绪之前就已连接，请重新连接，以便它重新列出工具。
在终端中运行 unity-mcp-cli status ./MyUnityProject，可以查看 Unity 是否正在运行，以及配置的 server 是否可访问。
第 5 步：你的第一批提示词
先从一个读取场景的请求开始，然后再尝试一个修改场景的请求：
Explain my scene hierarchy.Create 3 spheres stacked on top of each other, then save the scene.Create a metallic golden material and assign it to a new sphere.观察 Hierarchy 面板：随着智能体执行操作，对象会陆续出现。在背后，智能体发送的是 RQL，例如下面这样的变更操作：
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})每次 RQL 变更都会被记录为一步 Undo，因此 Ctrl+Z（Cmd+Z）可以像手动编辑一样将其撤销。
下面是一个会用到多个工具的更长示例：
Create a new scene called Playground. Add a plane scaled to 10, 1, 10 and a capsule
named Player at 0, 1, 0 with a Rigidbody. Write a PlayerController script that moves
the Player with WASD, attach it, and take a screenshot of the Player.更多可以尝试的想法：
- “读取 Console 并告诉我是否有任何错误。”
- “运行所有 EditMode 测试并总结失败项。”
- “列出打开场景中每个 Rigidbody 及其质量。”
- “启动 Profiler，录制几秒钟 Play 模式并报告帧时间。”
获得更好结果的技巧
- 对名称、位置和文件路径要具体明确。请求越精确，需要纠正的地方就越少。
- 在你的客户端中选择一个强大的模型；工具调用密集的工作会因此受益。
- 在 VS Code 中使用 Copilot 时，将聊天切换为 Agent 模式，否则不会调用工具。
- 保持智能体的工具列表精简。隐藏的工具在被按名称调用时仍会运行，而可见工具越少，留给推理的上下文就越多。请参阅配置。
Unity 最佳实践页面提供了更多提示词编写建议。