# 常见问题 — Unity · AI Game Developer Wiki

关于 Unity MCP 的常见问题解答——支持的 Unity 版本与 AI 客户端、Cloud 与本地模式、费用、隐私、构建、CI 与 RQL。

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

简短解答大家关于 Unity MCP（Unity 的 AI Game Developer 插件）最常问的问题。每个答案都链接到包含详细信息的页面。

## 通用

### Unity MCP 是什么？

一个 Unity 编辑器插件，让 AI 智能体通过 Model Context Protocol 在你的项目中工作。智能体可以读取和修改场景、GameObject、组件、预制体和资源，编写并运行 C#，运行测试并截图。参见[概览](https://ai-game.dev/zh-hans/docs/wiki/unity)。

### 该插件是免费且开源的吗？

该插件以 Apache-2.0 许可证开源，位于 [Unity-MCP 仓库](https://github.com/IvanMurzak/Unity-MCP)。Custom 模式运行本地服务器，无需账号。Cloud 模式使用你的 ai-game.dev 账号；套餐见[价格页面](https://ai-game.dev/pricing)。

### 支持哪些 Unity 版本？

Unity 2022.3 及更新版本，包括 Unity 6。

### 哪些 AI 客户端可以配合使用？

**AI Game Developer** 窗口内置了 Claude Code、Claude Desktop、Cursor、Visual Studio Code (Copilot)、Visual Studio (Copilot)、Rider (Junie)、GitHub Copilot CLI、Gemini、Antigravity、Cline、Open Code、Codex、Kilo Code、Zoo Code 和 Unity AI 的配置器，并为任何其他 MCP 客户端提供了自定义条目。参见[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/unity/connecting-ai-clients)。

### 我需要有自己的 AI 客户端吗？

不需要。[AI Game Dev 桌面应用](https://ai-game.dev/docs/app)内置了智能体，会安装插件并完成连接。如果你已经在使用 Claude Code、Cursor 或其他 MCP 客户端，也可以使用自己的客户端。

## 安装与设置

### 最简单的安装方式是什么？

使用桌面应用。如果不使用它，可以运行 `unity-mcp-cli install-plugin`，或使用 OpenUPM 或 `.unitypackage` 安装包。参见[安装](https://ai-game.dev/zh-hans/docs/wiki/unity/installation)。

### 插件窗口在哪里？

**Window > AI Game Developer — MCP**，快捷键 Ctrl+Alt+A（macOS 上为 Cmd+Option+A），或场景视图工具栏中的 **AI** 按钮。

### Cloud 模式和 Custom 模式有什么区别？

Cloud 模式（默认）下，编辑器和你的 AI 客户端连接到 `https://ai-game.dev/mcp`，你只需登录一次。Custom 模式下，插件会根据项目路径派生出的端口运行本地 MCP 服务器，所有内容都留在你的机器上。参见[配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration#connection-modes)。

### 我需要选择端口吗？

不需要。端口由项目路径派生（范围 20000 到 29999），因此每个项目的端口固定不变，且不同项目之间互不相同。你可以在 **Server URL** 中覆盖它。

### 设置存储在哪里？

存储在项目内的 `UserSettings/AI-Game-Developer-Config.json` 中。ai-game.dev 登录信息按机器存储一次，位于 `~/.ai-game-dev/credentials.json`。

### 我可以同时使用多个 Unity 项目吗？

可以。每个项目都有自己的端口，固定 URL（`https://ai-game.dev/mcp/p/<pin>`）会把每个智能体路由到正确的编辑器。

## 使用方法

### 像 gameobject-create 这样的工具去哪了？

\\1.0.0 版本用 RQL 取代了每个动作对应一个工具的做法：`rql-query`、`rql-mutate` 和 `rql-schema` 覆盖场景、GameObject、组件、资源、Console 和编辑器状态。参见[工具与 RQL](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql#old-names)。

### AI 能撤销它的改动吗？

每次 `rql-mutate` 调用都记录为一步撤销，因此 Ctrl+Z（Cmd+Z）可以还原。更大范围的改动请使用版本控制。

### 为什么智能体只看到少数几个工具？

为了节省上下文。默认可见七个工具；其余工具已安装但被隐藏，按名称调用时仍会运行。在窗口的 **Tools > Open** 下可以显示更多。

### 我可以添加自己的工具吗？

可以。用 `[AiToolType]` 标记类，用 `[AiTool]` 标记方法。参见[自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools)。

### 如何添加对 Cinemachine、ProBuilder 或 Tilemaps 的支持？

从窗口的 **Extensions** 区域安装对应的扩展，或使用 `unity-mcp-cli install-extension`。参见[扩展](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)。

### 它在 Play 模式下能用吗？

可以。智能体可以通过 RQL 进入和退出 Play 模式（`editor` 成员，如 `isPlaying`）。域重载后连接会自动重连。

## 构建、CI 与隐私

### 插件会进入我的游戏构建吗？

运行时部分会编译进播放器构建，但构建绝不会自行连接。你可以在代码中通过 `UnityMcpPluginRuntime.Initialize(...)` 选择启用，从而在你的游戏内提供 AI 工具。要完全排除该插件，请添加 `UNITY_MCP_EXCLUDE_FROM_COMPILATION` 脚本定义。参见[配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration#runtime)。

### 如何让它不参与 CI 测试运行？

在 Unity 进程的环境变量中设置 `UNITY_MCP_DISABLE=1`，或使用 `UNITY_MCP_EXCLUDE_FROM_COMPILATION` 定义。参见[配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration#ci)。

### 我可以在没有 AI 客户端的情况下用脚本调用吗？

可以。`unity-mcp-cli run-tool` 可以在终端中调用任意工具，`unity-mcp-cli exec` 可以在编辑器中运行 C# 代码。参见 [CLI 参考](https://ai-game.dev/zh-hans/docs/wiki/unity/cli)。

### 哪些数据会离开我的机器？

在 Custom 模式下使用 `none` 或 `token` 授权时，不会有任何数据经过 ai-game.dev：Agent 和 Unity 通过本地服务器通信。你的 AI 客户端仍会将你的对话发送给它自己的模型提供商。在 Cloud 模式下，工具调用及其结果在 Agent 与编辑器之间传输时会经过 ai-game.dev 服务器。

### 如何为我的团队关闭更新弹窗？

在 **Edit > Project Settings > AI Game Developer** 中启用 **Disable update notifications for the entire team**，并提交 `ProjectSettings/AI-Game-Developer-UpdateSettings.asset`。

## 更多帮助

- 遇到错误时参见[故障排查](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)。
- 站点范围的[常见问题](https://ai-game.dev/docs/faq)和 [Unity 最佳实践](https://ai-game.dev/docs/best-practices/unity)。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/unity/faq

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