# Unity 插件设置 — AI Game Developer

逐步设置 Unity 的 AI Game Developer 插件：安装、登录、连接 AI 客户端并添加扩展，同时解决常见问题。

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

Unity · 手动设置

从空的 Unity 项目到 AI 代理在编辑器中工作，你需要的一切都在这里：安装插件、登录、连接 AI 客户端，并添加所需扩展。[Unity 安装页面](https://ai-game.dev/zh-hans/engines/unity)提供了简版说明。

01

## 开始之前

Unity 2022.3 或更高版本、一个 ai-game.dev 账号，以及一个 AI 客户端。

- **Unity 2022.3 或更高版本** — 支持 Unity 6。
- **一个 ai-game.dev 账号**，用于默认云端连接；如果没有，请[创建一个](https://ai-game.dev/create-account)。
- **一个 AI 客户端** — AI Game Dev 应用、Claude Code、Cursor、Copilot、Gemini、Codex，或 [14 个受支持的 MCP 客户端](https://ai-game.dev/zh-hans/mcp-endpoint-info)中的任意一个。
- **首次打开时需联网**：插件会从 NuGet 下载 .NET 包。

02

## 安装插件

可通过应用、CLI、OpenUPM 或安装包完成——任选一种。

添加插件有四种方式，从最简单的开始：

**桌面应用**

在[AI Game Dev 应用](https://ai-game.dev/zh-hans/download)中打开 Unity 项目，点击 **安装包**。应用会从 OpenUPM 安装最新插件、完成登录并配置你的代理。

**unity-mcp-cli**

从 npm 安装 CLI，然后把插件添加到项目（它会替你修改 `Packages/manifest.json`）：

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
```

**OpenUPM 安装**

使用 OpenUPM CLI 时，在项目文件夹中运行：

```bash
openupm add com.ivanmurzak.unity.mcp
```

没有 OpenUPM CLI？先将作用域注册表添加到 `Packages/manifest.json`，然后在**窗口 → 包管理器**中添加包：

```json
{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.ivanmurzak", "extensions.unity"]
    }
  ]
}
```

**.unitypackage 安装**

下载安装器，并用 **Assets → Import Package → Custom Package…** 导入。它会将 OpenUPM 注册表和插件包添加到项目，之后即可通过包管理器获取更新。

[⬇ 下载 AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)

03

## 打开窗口并登录

打开 AI Game Developer 窗口，并用你的账号登录一次。

1. 在 Unity 中选择 **Window → AI Game Developer — MCP**（`Ctrl+Alt+A`，macOS 上为 `Cmd+Option+A`）。
2. 让**连接**开关保持在**云端**，然后点击**授权**。
3. 浏览器会打开 ai-game.dev 登录页并显示一个短代码。确认代码一致后批准即可。
4. Unity 状态会变为**已连接**。

登录状态会保存在整台电脑上：如果你已通过应用或 `unity-mcp-cli login` 登录，编辑器会直接使用该登录状态，你可以跳过这一步。

04

## 连接 AI 客户端

一条命令，或在窗口中点一下，即可写入客户端配置。

在窗口中点击 AI 代理旁的**配置**，或在终端运行 `setup-mcp`。两者都会把项目固定的 URL 和项目密钥写入客户端配置，因此可以立即连接：

```bash
# Claude Code — use your agent's id (cursor, codex, gemini, vscode-copilot, …)
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
```

配置更改后请重启 AI 客户端。其他客户端和手动配置请参阅[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/unity/connecting-ai-clients)及[MCP 端点页面](https://ai-game.dev/zh-hans/mcp-endpoint-info)。

05

## 添加扩展（可选）

动画、Cinemachine、地形、时间轴等，只安装你需要的即可。

每个扩展都是独立的 Unity 包。安装后，它会通过 RQL 让 agent 掌握 Unity 的某个领域。几个常用的扩展：

- [AI Animation](https://ai-game.dev/docs/extensions/unity/animation) 3 项能力
  ```bash
  openupm add com.ivanmurzak.unity.mcp.animation
  ```
- [AI Cinemachine](https://ai-game.dev/docs/extensions/unity/cinemachine) 4 项能力
  ```bash
  openupm add com.ivanmurzak.unity.mcp.cinemachine
  ```
- [AI Terrain](https://ai-game.dev/docs/extensions/unity/terrain) 4 项能力
  ```bash
  openupm add com.ivanmurzak.unity.mcp.terrain
  ```
- [AI Timeline](https://ai-game.dev/docs/extensions/unity/timeline) 5 项能力
  ```bash
  openupm add com.ivanmurzak.unity.mcp.timeline
  ```

[全部 10 个 Unity 扩展 →](https://ai-game.dev/docs/extensions/unity)

?

## 故障排查

常见问题的解决办法。更多内容见[Unity 故障排查指南](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)。

**我的 AI 客户端能连接，但看不到任何工具**

确认 Unity 状态显示为**已连接**，然后重新连接客户端（在 Claude Code 中为 `/mcp`）或重启客户端。如果仍然没有列出任何工具，请再次为你的 agent 点击**配置**，然后重启客户端。

**AI Game Developer 窗口没有出现**

插件只在项目编译完成后才会加载。请检查 Console 中项目任意位置的编译错误，然后重新打开编辑器。缺少 McpPlugin 或 ReflectorNet 的类型通常说明首次导入尚未完成：请稍等，或使用**Tools → AI Game Developer → Dependencies → Force Resolve NuGet DLLs**。

**自定义模式：本地 MCP 服务器无法启动**

在自定义模式下，插件会把 `gamedev-mcp-server` 下载到 `Library/mcp-server/<platform>/`。如果被防火墙或代理拦截，窗口会显示服务器错误，并带有**下载 / 重试**按钮。云模式下不需要本地服务器。

**自定义模式下的端口冲突**

每个项目会根据自身路径分配一个 20000 到 29999 之间的固定本地端口。如果该端口已被其他进程占用，服务器会显示为**外部**：请停止该进程，或在**服务器 URL** 中输入其他端口，然后再次点击**配置**。

**Package Manager 提示该包需要更新版本的 Unity**

该插件需要 Unity 2022.3 或更高版本。请升级项目，或使用 `unity-mcp-cli install-unity` 安装更新版本的编辑器。

### 下一步

[**Unity 维基 →** 配置、工具与 RQL、自定义工具、CLI 参考等。](https://ai-game.dev/zh-hans/docs/wiki/unity) [**Unity 工具 →** agent 在 Unity 中能做的所有事情，附示例。](https://ai-game.dev/docs/tools/unity) [**最佳实践 →** 如何让 agent 做它擅长的工作。](https://ai-game.dev/docs/best-practices/unity)

---

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

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