配置
在 AI Game Developer 窗口中配置 Unity MCP——Cloud 与 Custom 模式、本地服务器、端口、传输方式、授权、工具、覆盖项以及 CI。
大多数项目无需任何配置：安装插件、登录，然后为你的 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）。
- 帮助链接：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 工具或从终端更改可见性：
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；其余全部隐藏 |
命令行参数的优先级高于环境变量。下面是连接本地服务器的批处理模式编辑器的示例：
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-tokenunity-mcp-cli open 会为你设置这些变量；参见 CLI reference。
在 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。
自托管 MCP 服务器
该服务器就是共享的 GameDev-MCP-Server，同时也以 Docker 镜像 aigamedeveloper/mcp-server 发布：
docker run -p 8080:8080 aigamedeveloper/mcp-server然后把插件设为 Custom，将 Server URL 设为 http://localhost:8080（或你的主机地址），并让你的 agent 指向同一地址。服务器支持 --port、--client-transport、--authorization 和 --idle-timeout-seconds 等设置，或对应的 MCP_PLUGIN_* 环境变量；服务器文档 列出了全部内容。
相关页面
- Connecting AI clients：agent 配置与登录。
- Troubleshooting：连接问题排查。