# 配置 — Unity · AI Game Developer Wiki

在 AI Game Developer 窗口中配置 Unity MCP——Cloud 与 Custom 模式、本地服务器、端口、传输方式、授权、工具、覆盖项以及 CI。

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

大多数项目无需任何配置：安装插件、登录，然后为你的 agent 点击 **Configure**。本页介绍 AI Game Developer 窗口中每一项设置的作用、设置存储的位置、如何为自动化流程覆盖这些设置，以及插件在 CI 和播放器构建中的行为。

## AI Game Developer 窗口

用 **Window > AI Game Developer — MCP**（Ctrl+Alt+A，macOS 上为 Cmd+Option+A）或 Scene 视图工具栏中的 **AI** 按钮打开它。从上到下依次包含：

- **Log Level**、**Timeout (ms)** 和 **Tool timeout (ms)**，以及插件 **Version**。
- **Connection**：**Custom** / **Cloud** 切换开关以及所选模式的设置。
- 连接时间线：**Unity**（带 **Connect** / **Disconnect** 按钮）、**MCP server** 和 **AI agent**。
- **AI agent** 下拉菜单以及每个客户端的配置器：**Model Context Protocol (MCP)** 配 **Configure** / **Remove**，**Skills** 配 **Auto-generate** 和 **Generate**。
- **Tools**、**Prompts** 和 **Resources** 计数，每一项都有一个 **Open** 按钮。
- **Extensions**：安装可选的工具包（参见 [Extensions](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)）。
- 帮助链接：**Help / Talk**（Discord）、**Bug Report**（GitHub issues），以及用于序列化诊断的 **Check** 按钮。

## 连接模式

### Cloud（默认）

插件连接到托管服务器 `https://ai-game.dev/mcp`。不会启动本地服务器，URL 也不可编辑。Cloud 模式需要登录：点击 **Cloud Token** 旁边的 **Authorize** 并在浏览器中确认设备码，或者用 `unity-mcp-cli login` 或 AI Game Dev 应用登录一次。**Revoke** 会让本机上所有 AI Game Dev 工具退出登录。

### Custom（本地服务器或你自己的服务器）

插件连接到 **Server URL** 中的地址。默认是本地服务器 `http://localhost:<port>`，插件会替你下载、启动和停止该服务器（`gamedev-mcp-server`）。你也可以填写自己托管的远程 MCP 服务器 URL。只有在 Unity 与服务器断开连接时，**Server URL** 才可编辑。

Custom 模式会额外提供以下设置：

- **MCP server**：一个 **Start** / **Stop** 按钮和状态（Running、Starting、Stopping、Downloading，或当端口已被其他进程占用时显示 External）。如果二进制文件下载失败，会出现 **Download / Retry server**。
- **Transport**：`http`（推荐）或 `stdio`。使用 `http` 时，agent 连接到正在运行的服务器，多个 agent 可以共享它，服务器也可以跑在另一台机器上。使用 `stdio` 时，agent 会把服务器作为自己的子进程启动，只能有一个 agent 连接，Start / Stop 按钮处于禁用状态。
- **Authorization Token**：`none`、`oauth` 或 `token`。
  - `none`：服务器接受任何连接。仅在端口无法从其他机器访问时才是安全的。
  - `oauth`：agent 使用自己的 ai-game.dev 账号登录；服务器在线校验令牌。
  - `token`：一个共享密钥，完全离线。点击 **New** 生成令牌，然后点击 **Configure**（或手动把令牌复制到 agent 的配置中）。

## 端口

本地端口并不是 8080 这样的固定值，而是由你的项目文件夹推导出来的：对规范化后的项目路径取 SHA-256 哈希，再映射到 **20000 到 29999** 的范围内。同一个项目总是得到同一个端口，不同项目得到不同端口，因此多个 Unity 实例可以并行运行。CLI 使用相同的公式，因此它的命令无需额外参数就能找到正确的服务器。

要使用其他端口，请先断开连接，然后在 **Server URL** 中输入端口（例如 `http://localhost:25000`）。配置器会把你输入的端口写入 agent 配置。

## 配置文件

设置按用户保存在 `UserSettings/AI-Game-Developer-Config.json` 中，首次启动时创建。主要键如下：

| 键 | 含义 | 默认值 |
| --- | --- | --- |
| `connectionMode` | `Cloud` 或 `Custom` | `Cloud` |
| `host` | Custom 模式的服务器 URL | `http://localhost:<port>` |
| `token` | `token` 授权模式使用的共享令牌 | 自动生成 |
| `transportMethod` | `streamableHttp` 或 `stdio` | `streamableHttp` |
| `authOption` | `none`、`oauth` 或 `token` | `none` |
| `keepConnected` | 自动连接到服务器 | `true`，在 CI 中为 `false` |
| `keepServerRunning` | 启动并保持本地服务器运行 | `true`，在 CI 中为 `false` |
| `logLevel` | `Trace`、`Debug`、`Information`、`Warning`、`Error`、`Critical` | `Warning` |
| `timeoutMs` | 插件到服务器的超时时间 | `10000` |
| `toolTimeoutMs` | 单次工具调用可以运行多长时间 | `300000` |
| `tools`、`prompts`、`resources` | 每一项的可见性 | 默认值 |

Cloud 凭据不保存在这里，而是存放在 `~/.ai-game-dev/credentials.json`。要重新开始，请使用 **Tools > AI Game Developer > Reset Config**，它会恢复默认值并重新加载脚本。

## 工具、提示和资源

**Tools** 计数显示 agent 能看到多少个已安装的工具，以及它们在 AI 上下文中大约占用多少 token。点击 **Open** 可显示或隐藏单个工具；**MCP Prompts** 和 **MCP Resources** 窗口的工作方式相同。

隐藏的工具不会被删除：它从 agent 的工具列表中消失，但按名称调用时仍然会执行。可见工具越少，留给推理的上下文就越多。你也可以用 `tool-set-visibility` 工具或从终端更改可见性：

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools screenshot-scene-view,script-read
unity-mcp-cli configure ./MyUnityProject --list
```

## 环境变量与命令行覆盖

对于 CI 和脚本化启动，插件会在启动时读取以下变量（或对应的 Unity 命令行参数）。覆盖只在内存中生效，绝不会写入配置文件。

| 变量 | 命令行参数 | 取值 |
| --- | --- | --- |
| `UNITY_MCP_CLOUD_URL` | `-url` | 服务器 URL（`UNITY_MCP_HOST` 是旧版别名） |
| `UNITY_MCP_CONNECTION_MODE` | `-UNITY_MCP_CONNECTION_MODE` | `Cloud` 或 `Custom`；环回地址 URL 意味着 `Custom` |
| `UNITY_MCP_KEEP_CONNECTED` | `-UNITY_MCP_KEEP_CONNECTED` | `true` 或 `false` |
| `UNITY_MCP_AUTH_OPTION` | `-auth` | `none`、`oauth` 或 `token` |
| `UNITY_MCP_TOKEN` | `-token` | 本地服务器令牌 |
| `UNITY_MCP_TRANSPORT` | `-UNITY_MCP_TRANSPORT` | `stdio` 或 `streamableHttp` |
| `UNITY_MCP_START_SERVER` | `-UNITY_MCP_START_SERVER` | `true` 或 `false` |
| `UNITY_MCP_TOOLS` | `-UNITY_MCP_TOOLS` | 要显示的以逗号分隔的工具 id；其余全部隐藏 |

命令行参数的优先级高于环境变量。下面是连接本地服务器的批处理模式编辑器的示例：

```bash
Unity -batchmode -projectPath ./MyUnityProject \
  -UNITY_MCP_CLOUD_URL=http://localhost:8080 \
  -UNITY_MCP_KEEP_CONNECTED=true \
  -UNITY_MCP_AUTH_OPTION=token \
  -UNITY_MCP_TOKEN=my-secret-token
```

`unity-mcp-cli open` 会为你设置这些变量；参见 [CLI reference](https://ai-game.dev/zh-hans/docs/wiki/unity/cli#open)。

## 在 CI 中禁用 Unity MCP

插件会检测 CI 环境，然后跳过服务器下载和自动连接。要在普通的 CI 测试任务中完全关闭它，可使用以下两种关闭方式之一：

- **`UNITY_MCP_DISABLE=1`**（或 `true`），设置在启动 Unity 的进程的环境中。插件会跳过启动流程、工具注册、服务器下载、NuGet 解析以及它的编辑器钩子。其代码仍会参与编译，因此项目仍然必须能编译通过。
- 在 **Project Settings > Player > Other Settings** 中将 **`UNITY_MCP_EXCLUDE_FROM_COMPILATION`** 设为 Scripting Define Symbol。这会将所有插件程序集（以及更新过的一方可扩展组件）排除在编译之外。你自己引用了插件类型的代码需要加上 `#if !UNITY_MCP_EXCLUDE_FROM_COMPILATION`。

这两者都不会对 `-batchmode` 或 `-runTests` 自动启用，因为无头 MCP 会话需要该插件。

## 播放器构建与运行时

插件的运行时程序集会为所有平台编译，因此除非你用上面的定义符号排除它，否则它会成为播放器构建的一部分。构建产物绝不会自行连接：在游戏中，你需要在代码中通过 `UnityMcpPluginRuntime.Initialize(...)` 主动启用，这也是向 AI 暴露游戏内工具（例如一个 AI 国际象棋对手）的方式。参见 [Custom tools](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools#runtime)。

## 自托管 MCP 服务器

该服务器就是共享的 [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server)，同时也以 Docker 镜像 `aigamedeveloper/mcp-server` 发布：

```bash
docker run -p 8080:8080 aigamedeveloper/mcp-server
```

然后把插件设为 **Custom**，将 **Server URL** 设为 `http://localhost:8080`（或你的主机地址），并让你的 agent 指向同一地址。服务器支持 `--port`、`--client-transport`、`--authorization` 和 `--idle-timeout-seconds` 等设置，或对应的 `MCP_PLUGIN_*` 环境变量；[服务器文档](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/mcp-server.md) 列出了全部内容。

## 相关页面

- [Connecting AI clients](https://ai-game.dev/zh-hans/docs/wiki/unity/connecting-ai-clients)：agent 配置与登录。
- [Troubleshooting](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)：连接问题排查。

---

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

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