# 設定 — Unreal Engine · AI Game Developer Wiki

設定 Unreal MCP：AI Game Developer 視窗、MCP Tools 可見性、專案設定檔、.env 以及所有 UNREAL_MCP_* 環境變數。

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

本頁列出 Unreal MCP 目前所有的設定項目，以及各自該到哪裡修改。大多數人只會調整連線模式與 AI 代理設定，其餘部分則用於調校、自動化與 CI。

## 設定存放位置

Unreal MCP 沒有針對編輯器連線的 Project Settings 頁面。所有設定都在 **AI Game Developer** 視窗（Tools 選單）中，並依專案儲存於：

```text
<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.json
```

`Saved/` 在所有 Unreal 專案範本中都會被版本控制忽略，因此這個檔案裡的權杖預設不會進到你的儲存庫。

設定的讀取順序如下，優先權由高到低：

1. 行程環境變數（例如由 `unreal-mcp-cli open` 或你的 shell 設定）。
2. 專案根目錄下的 `.env` 檔案。
3. 上述的設定檔。
4. 內建預設值。

來自環境變數或 `.env` 的值會在該次工作階段覆寫檔案內容，但永遠不會寫回檔案。

## AI Game Developer 視窗

| 區塊 | 你可以做什麼 |
| --- | --- |
| 標頭 | 選擇 **Log Level**（Trace、Debug、Info、Warning、Error、Exception、None），用 **Open log file** 開啟專案的日誌資料夾，查看外掛 **Version** |
| 連線 | 切換 **Custom / Cloud**；Cloud 模式下可 **Authorize**、**Cancel** 或 **Revoke**；Custom 模式可設定 **Server URL**；**Connect / Disconnect / Stop**；查看 Unreal、MCP 伺服器與已連線 AI 代理的狀態，以及 IPC bridge 連接埠 |
| MCP 伺服器（Custom 模式） | 以 **Start / Stop** 控制本機的 `gamedev-mcp-server`，選擇 **Transport**（http 或 stdio）與 **Authorization** 模式（none、token、oauth），並可用 **New** 產生權杖 |
| AI 代理 | 選擇一個代理後，**Configure**、**Reconfigure** 或 **Remove** 它的 MCP 項目；開啟它的 **Tutorial** 或 **Download / Docs**；**Generate skill files**；為專案金鑰執行 **Regenerate key** |
| 擴充功能 | 查看已安裝與可用的擴充功能，**Refresh catalog**、**Install** 或 **Update**，即時啟用或停用擴充功能，**Compile (Live Coding)** |
| 頁尾 | **Help / Talk**（Discord）、**Bug Report**（GitHub）、**GitHub Star**，以及 **Restart bridge** |

連線細節請見[連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients)，擴充功能請見[擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions)。

## MCP Tools 視窗：個別工具的可見性

依序開啟 **Tools** 與 **MCP Tools**。視窗會列出所有已註冊的工具，包含標題、分類與說明，每個工具都有一個 **Visible** 核取方塊，以及像「27 / 27 tools visible」這樣的摘要。

- **Visible** 決定工具是否會出現在提供給 AI 代理的 `tools/list` 中。隱藏用不到的工具可讓代理的工具清單保持精簡，節省權杖。
- 這**不是**存取控制。用戶端以名稱呼叫時，隱藏的工具仍會執行，而 `unreal-tool-list` 會顯示隱藏的工具（標示為 hidden），讓代理仍能找到它們。
- 此選擇會儲存為 `hiddenTools`，在編輯器重新啟動與擴充功能重新載入後依然保留。

若要完全停止提供某個工具，請使用下方的 `UNREAL_MCP_TOOLS` 白名單。

## 其他視窗

Tools 選單中還有 **MCP Prompts** 與 **MCP Resources** 視窗。目前版本中它們會顯示空白狀態訊息；由外掛或擴充功能註冊的 prompts 與 resources 仍可供 AI 用戶端使用。**Serialization Check** 視窗會將選取的 actor 或物件序列化為 JSON，讓你檢視工具所看到的內容。

## 環境變數

外掛會從行程環境或專案的 `.env` 檔案讀取以下 `UNREAL_MCP_*` 變數：

| 變數 | 用途 |
| --- | --- |
| `UNREAL_MCP_CONNECTION_MODE` | `Cloud`（預設）或 `Custom` |
| `UNREAL_MCP_HOST` | Custom 模式下的伺服器 URL，例如 `http://localhost:<port>` |
| `UNREAL_MCP_CLOUD_URL` | 雲端基底 URL；預設為 ai-game.dev |
| `UNREAL_MCP_TOKEN` | 驗證權杖。屬於機密，切勿提交到版本庫 |
| `UNREAL_MCP_AUTH_OPTION` | Custom 模式的驗證方式：`none`、`token` 或 `oauth`（較舊的值 `required` 會以 `token` 解讀） |
| `UNREAL_MCP_KEEP_CONNECTED` | 啟動時自動恢復連線（預設為 true） |
| `UNREAL_MCP_TOOLS` | 要提供哪些工具的白名單；留空表示不篩選 |
| `UNREAL_MCP_START_SERVER` | `true`：由編輯器自行啟動本機伺服器（Custom 模式，僅支援 http），並在結束時停止 |
| `UNREAL_MCP_TRANSPORT` | `http` 或 `stdio` |
| `UNREAL_MCP_LOG_LEVEL` | 日誌詳細程度 |
| `UNREAL_MCP_TOOL_TIMEOUT` | 單次工具呼叫的最長時間，單位為毫秒；預設為 `300000`（5 分鐘） |
| `UNREAL_MCP_BRIDGE_PATH` | bridge 二進位檔的路徑；開發者覆寫用，優先於內建的版本 |
| `UNREAL_MCP_SERVER_PATH` | 本機 `gamedev-mcp-server` 的路徑；由 `unreal-mcp-cli` 讀取，會跳過其伺服器下載 |

**提示：** 如果長時間執行的 `python-execute` 腳本或大型資源匯入發生逾時，請調高 `UNREAL_MCP_TOOL_TIMEOUT`。若工具呼叫在編輯器開始執行前就逾時，該呼叫會被略過，不會稍後再執行。

## 使用 CLI 寫入 .env

`unreal-mcp-cli configure` 會將這些值寫入 `<project>/.env`，並把 `.env` 加入專案的 `.gitignore`：

```bash
unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-server
```

Unreal 專案範本預設不含 `.gitignore`，因此命令會在需要時建立一個。加上 `--no-gitignore` 可保持原狀不變。所有旗標請見 [CLI 參考](https://ai-game.dev/zh-hant/docs/wiki/unreal/cli#configure)。

**警告：** 切勿將 `.env` 提交到版本庫。它可能包含 `UNREAL_MCP_TOKEN`。

## 磁碟上的認證與金鑰

| 檔案 | 內容 |
| --- | --- |
| `~/.ai-game-dev/credentials.json` | 整台機器共用的 ai-game.dev 登入資訊，與應用程式、外掛及 CLI 共用 |
| `~/.ai-game-dev/project-keys.json` | 快取的專案金鑰，用於 Cloud MCP 設定 |
| `<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json` | 外掛的個別專案設定 |
| `<project>/.env` | 選用的覆寫設定，絕不提交 |

## 連接埠

- 本機 MCP 伺服器會使用 20000 到 29999 之間、依專案固定的一個連接埠，由專案路徑計算得出。CLI 會算出相同的數字，因此不需任何設定。
- 外掛與其橋接程式透過 30000 到 39999 之間的迴路連接埠通訊（發生衝突時使用下一個可用連接埠）。視窗會將其顯示為「IPC bridge port」。

你完全不需要對網路開放這些連接埠；兩者都是本機的。

---

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

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