# 配置 — 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 agent 设置；其余设置用于调优、自动化和 CI。

## 设置存放位置

Unreal MCP 没有用于编辑器连接的 Project Settings 页面。所有设置都在 **AI Game Developer** 窗口（Tools 菜单）中，并按项目保存在：

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

每个 Unreal 项目模板都会忽略版本控制中的 `Saved/`，因此该文件中的 token 默认不会进入你的代码仓库。

设置的读取顺序如下，优先级从高到低：

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 agent 的状态，以及 IPC bridge 端口 |
| MCP 服务器（Custom 模式） | **Start / Stop** 本地 `gamedev-mcp-server`，选择 **Transport**（http 或 stdio）和 **Authorization** 模式（none、token、oauth），用 **New** 生成 token |
| AI agent | 选择一个 agent，然后 **Configure**、**Reconfigure** 或 **Remove** 它的 MCP 条目；打开它的 **Tutorial** 或 **Download / Docs**；**Generate skill files**；为项目 key 执行 **Regenerate key** |
| 扩展 | 查看已安装和可用的扩展，**Refresh catalog**、**Install** 或 **Update**，实时启用或禁用某个扩展，**Compile (Live Coding)** |
| 页脚 | **Help / Talk**（Discord）、**Bug Report**（GitHub）、**GitHub Star**，以及 **Restart bridge** |

连接相关的详细信息见 [Connecting AI clients](https://ai-game.dev/zh-hans/docs/wiki/unreal/connecting-ai-clients)，扩展相关内容见 [Extensions](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)。

## MCP Tools 窗口：单个工具的可见性

打开 **Tools**，然后打开 **MCP Tools**。该窗口列出所有已注册的工具及其标题、所属类别和描述，每个工具都有一个 **Visible** 复选框，还会显示类似“27 / 27 tools visible”的摘要。

- **Visible** 决定某个工具是否会在 `tools/list` 中列给 AI agent。隐藏你不需要的工具可以缩短 agent 的工具列表并节省 token。
- 这**不是**访问控制。隐藏的工具在被客户端按名称调用时仍会执行，而且 `unreal-tool-list` 会显示隐藏的工具（标记为 hidden），因此 agent 仍然能找到它们。
- 该选择会保存为 `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` | Cloud 基础 URL；默认为 ai-game.dev |
| `UNREAL_MCP_TOKEN` | 认证 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-hans/docs/wiki/unreal/cli#configure)。

**警告：** 切勿提交 `.env`。它可能包含 `UNREAL_MCP_TOKEN`。

## 磁盘上的凭据与密钥

| 文件 | 内容 |
| --- | --- |
| `~/.ai-game-dev/credentials.json` | 整台机器范围的 ai-game.dev 登录信息，与应用、插件和各 CLI 共享 |
| `~/.ai-game-dev/project-keys.json` | 缓存的 project key，用于 Cloud MCP 配置 |
| `<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json` | 该插件的按项目设置 |
| `<project>/.env` | 可选的覆盖项，永远不会被提交 |

## 端口

- 本地 MCP 服务器使用一个固定的按项目端口，范围在 20000 到 29999 之间，由项目路径计算得出。CLI 会算出相同的数字，因此无需任何配置。
- 插件与其 bridge 通过 30000 到 39999 之间的回环端口通信（发生冲突时使用下一个空闲端口）。窗口中将其显示为 "IPC bridge port"。

你永远不需要将这些端口对外开放到网络；两者都是本地的。

---

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

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