# 設定 — Unity · AI Game Developer Wiki

在 AI Game Developer 視窗中設定 Unity MCP：Cloud 與 Custom 模式、本機伺服器、連接埠、傳輸方式、授權、工具、覆寫與 CI。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/unity/configuration)。

大多數專案不需要任何設定：安裝外掛、登入，然後為你的代理點選 **Configure**。本頁說明 AI Game Developer 視窗中每個設定的作用、設定儲存的位置、如何為自動化覆寫這些設定，以及外掛在 CI 與播放器組建中的行為。

## AI Game Developer 視窗

使用 **Window > AI Game Developer — MCP**（Ctrl+Alt+A，macOS 上為 Cmd+Option+A）或 Scene View 工具列中的 **AI** 按鈕開啟。由上而下包含：

- **Log Level**、**Timeout (ms)** 與 **Tool timeout (ms)**，以及外掛**版本**。
- **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-hant/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** 中的 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` 時，代理會連線到執行中的伺服器，多個代理可以共用，伺服器也可在另一台機器上執行。使用 `stdio` 時，代理會將伺服器啟動為自己的子程序，一次只能有一個代理連線，且 Start / Stop 按鈕會停用。
- **Authorization Token**：`none`、`oauth` 或 `token`。
  - `none`：伺服器接受任何連線。僅在連接埠無法從其他機器存取時才安全。
  - `oauth`：代理以其 ai-game.dev 帳號登入；伺服器會線上驗證權杖。
  - `token`：共用密鑰，完全離線。點選 **New** 產生權杖，然後按 **Configure**（或手動將權杖複製到代理的設定中）。

## 連接埠

本機連接埠不是像 8080 這樣的固定值。它是由你的專案資料夾推導而來：將正規化後的專案路徑取 SHA-256 雜湊，再對應到 **20000 到 29999** 的範圍。同一個專案永遠取得相同的連接埠，不同的專案則取得不同的連接埠，因此多個 Unity 執行個體可以並行運作。CLI 使用相同的公式，因此其命令不需額外旗標就能找到正確的伺服器。

若要使用其他連接埠，請先中斷連線，然後在 **Server URL** 中輸入（例如 `http://localhost:25000`）。設定器會將你輸入的連接埠寫入代理設定。

## 設定檔

設定會以每位使用者為單位儲存在 `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** 計數顯示代理能看到多少已安裝的工具，以及它們在 AI 上下文中大約佔用的權杖數。點選 **Open** 可顯示或隱藏個別工具；**MCP Prompts** 與 **MCP Resources** 視窗的運作方式相同。

隱藏的工具不會被刪除：它會從代理的工具清單中消失，但以名稱呼叫時仍會執行。可見的工具越少，就能留給推理更多上下文。你也可以用 `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 參考文件](https://ai-game.dev/zh-hant/docs/wiki/unity/cli#open)。

## 在 CI 中停用 Unity MCP

此外掛會偵測 CI 環境，然後跳過伺服器下載與自動連線。若要在一般的 CI 測試工作中完全關閉它，可使用下列兩種退出方式之一：

- **`UNITY_MCP_DISABLE=1`**（或 `true`），設定在啟動 Unity 之程序的環境中。此外掛會略過啟動、工具註冊、伺服器下載、NuGet 解析及其編輯器掛鉤。其程式碼仍會編譯，因此專案仍必須能編譯。
- **`UNITY_MCP_EXCLUDE_FROM_COMPILATION`**，作為 **Project Settings > Player > Other Settings** 中的 Scripting Define Symbol。這會將所有外掛組件（以及更新後的第一方擴充功能）排除於編譯之外。你自己參考外掛型別的程式碼需要加上 `#if !UNITY_MCP_EXCLUDE_FROM_COMPILATION`。

這兩者都不會因為 `-batchmode` 或 `-runTests` 而自動啟用，因為無頭 MCP 工作階段需要此外掛。

## 播放器組建與執行階段

此外掛的執行階段組件會為每個平台編譯，因此除非你用上述的定義符號排除它，它都會包含在你的播放器組建中。組建永遠不會自行連線：在遊戲中，你需在程式碼中透過 `UnityMcpPluginRuntime.Initialize(...)` 選擇啟用，這就是將遊戲內工具開放給 AI 的方式（例如 AI 西洋棋對手）。請參閱 [Custom tools](https://ai-game.dev/zh-hant/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`（或你的主機），再讓你的代理指向相同位址。伺服器接受 `--port`、`--client-transport`、`--authorization` 與 `--idle-timeout-seconds` 等設定，或對應的 `MCP_PLUGIN_*` 環境變數；[伺服器文件](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/mcp-server.md) 列出了全部。

## 相關頁面

- [連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unity/connecting-ai-clients) 說明代理設定與登入。
- [疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting) 說明連線問題。

---

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

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