# 配置 — Godot · AI Game Developer Wiki

在 AI Game Developer 停靠面板中配置 Godot MCP，选择 AI 智能体可见的工具，并用 GODOT_MCP_* 环境变量覆盖设置。

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

大多数人从不需要修改任何设置：插件以 Cloud 模式启动，在你登录后自动连接，并公开其全部工具。本页介绍在确有需要时你可以更改的内容，包括 **AI Game Developer** 停靠面板中的设置、已保存的设置，以及用于 CI 和脚本化运行的环境变量。

## AI Game Developer 停靠面板

插件会在 Godot 编辑器右上方的停靠区域添加一个名为 **AI Game Developer** 的停靠面板。从上到下包含以下分区。

### 标题栏

标题栏显示插件版本和一个 **Log Level** 选择器。日志级别控制插件及其连接向输出面板打印的信息量（`Trace`、`Debug`、`Info`、`Warning`、`Error`、`None`；默认 `Info`）。在诊断连接问题时，可将其提高到 `Debug` 或 `Trace`。当设置了 `GODOT_MCP_LOG_LEVEL` 时，该选择器会被禁用，并显示一条说明。

### 连接

- **Cloud / Custom**：连接模式。Cloud 连接到 [ai-game.dev](https://ai-game.dev)；Custom 连接到你所选择的服务器 URL。
- **Connect / Stop**：开始或停止连接 MCP 服务器。插件会在后台持续重试，直到连接成功。
- 在 Cloud 模式下：显示你的登录状态，以及 **Authorize**（启动浏览器设备登录）和 **Sign out**。
- 一行三个圆点（Godot、MCP 服务器和 AI 智能体）显示当前已连接的内容。AI 智能体一行按名称列出已连接的客户端，若尚未连接任何客户端则显示“按需连接”。

在 Custom 模式下，**MCP server** 卡片会新增：

- **Server URL**：要连接的服务器，默认 `http://localhost:8080`。
- **Authorization Token**：`none`、`oauth`（你的 ai-game.dev 账号令牌，仅发送给 localhost 服务器）或 `token`（一个 bearer 令牌；**New** 会生成一个）。
- **Start Server / Stop Server**：下载、启动和停止与插件固定服务器版本匹配的本地服务器。参见 [连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/godot/connecting-ai-clients#custom-mode)。

如果环境变量强制指定了模式或主机，会显示一条黄色提示“Overridden by environment (GODOT\_MCP\_\*)”，此时在停靠面板中所做的更改不会生效。

### AI 智能体

选择你使用的 AI 客户端（默认为 Claude Code）。该分区随后显示：

- **Skills**：智能体技能文件的存放位置，一个在插件加载时刷新这些文件的 **Auto-generate** 开关，以及一个 **Generate** 按钮。不支持技能的智能体会显示“此智能体不支持技能”。
- **Model Context Protocol (MCP)**：智能体的 MCP 配置是否已设置好，附带 **Configure** / **Reconfigure** 和 **Remove**。如果你在配置智能体之后服务器设置发生了变化，会出现 **Reconfiguration Required** 提示。

### MCP 功能

三行分别是 **Tools**、**Prompts** 和 **Resources**，每行显示可见项数量占总数的比例（工具还会显示预估的 token 开销）和一个 **Open** 按钮。打开的窗口会列出每个条目，每个条目带一个 **Visible** 开关，并提供一个筛选输入框。

**Visible** 只决定 MCP 客户端能否在其工具列表中看到该条目。隐藏你不需要的工具可以让智能体的上下文更小。它并非访问控制：如果客户端按名称调用某个隐藏的工具，该工具仍会执行。

### 扩展

可选 Godot MCP 扩展的列表，带有 **Install** 和 **Update** 按钮。它读取嵌入在你 `.csproj` 中的扩展目录；如果列表为空，请参见 [扩展](https://ai-game.dev/zh-hans/docs/wiki/godot/extensions)。

### 页脚

用于获取帮助和报告问题的链接，以及一个 **Serialization Check** 窗口，显示所选节点或对象为 AI 序列化的方式（在报告 bug 时很有用）。

## 设置保存在哪里

停靠面板将其设置保存到 `user://godot-mcp-config.json`，位于 Godot 为该项目的每个用户分配的数据文件夹中（不在项目内部）。它保存连接模式、自定义主机、授权选项、日志级别、所选智能体、工具可见性以及你使用过的令牌。

**警告**

该文件以纯 JSON 形式存储令牌。不要提交、同步或分享它。要轮换令牌，请在停靠面板中退出登录或清除令牌（或删除该文件），然后重新连接。

Cloud 登录凭据单独存放在机器级存储 `~/.ai-game-dev/credentials.json` 中，与其他 AI Game Developer 工具共用。智能体配置的项目密钥位于 `~/.ai-game-dev/project-keys.json`。

在终端中，`godot-cli configure` 可列出并更改项目文件 `.godot-mcp/features.json` 中工具、提示和资源的可见性：

```bash
godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-tools
```

## 环境变量

环境变量会覆盖已保存的设置，无需编辑任何文件，这在 CI、无头运行和本地开发中非常方便。该插件还会从项目中的 `.env` 文件读取这些变量；进程环境优先于 `.env`。

| 变量 | 取值 | 用途 |
| --- | --- | --- |
| `GODOT_MCP_CONNECTION_MODE` | `Cloud`、`Custom` | 强制指定连接模式。默认 `Cloud`。 |
| `GODOT_MCP_CLOUD_URL` | URL | 覆盖云端基础 URL。默认 `https://ai-game.dev`。 |
| `GODOT_MCP_HOST` | URL | Custom 模式的服务器 URL。默认 `http://localhost:8080`。 |
| `GODOT_MCP_AUTH_OPTION` | `none`、`oauth`、`token` | Custom 模式的授权方式。 |
| `GODOT_MCP_TOKEN` | string | 当前模式使用的 Bearer 令牌。会覆盖已保存的令牌，且永远不会被写回。 |
| `GODOT_MCP_LOG_LEVEL` | `Trace` 至 `None` | 日志详细程度。 |
| `GODOT_MCP_CREDENTIALS_DIR` | absolute path | 使用独立的凭据存储，用于隔离测试。 |
| `GODOT_MCP_TOOL_FORMAT` | `Rql`、`Json` | 工具接收参数和返回结果的方式。默认 `Rql`（紧凑文本）；`Json` 保留 JSON schema 和结构化结果。 |
| `GODOT_MCP_SERVER_PATH` | absolute path | 仅编辑器：启动这个已有的服务器二进制文件，而不是下载固定版本的发布包。 |
| `GODOT_MCP_RUNTIME_FROM_EDITOR` | `1` | 让通过 Play 启动的游戏也能连接其自带的游戏内 MCP 运行时。 |

示例：启动编辑器并连接本地服务器。

```bash
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProject
```

`godot-cli open` 会通过 `--mode`、`--url`、`--cloud-url`、`--token`、`--auth` 和 `--log-level` 为你设置这些变量。参见 [godot-cli 参考](https://ai-game.dev/zh-hans/docs/wiki/godot/cli#open)。

## 工具格式

在默认的 `Rql` 格式下，工具以 RQL 值作为参数（例如 `"Level/Player"` 这样的节点路径，或 `godot.find("Name")`），并返回消耗更少 token 的紧凑文本。而 `Json` 格式（通过 `GODOT_MCP_TOOL_FORMAT=Json` 或 `toolFormat` 键设置）则保留完整的 JSON schema 和结构化结果，适合偏好这种方式的客户端。关于 RQL 的更多内容：[工具](https://ai-game.dev/zh-hans/docs/wiki/godot/tools#rql)。

---

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

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