# 設定 — 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** 選擇器。記錄等級控制外掛與其連線在 Output 面板印出多少訊息（`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 代理那一列會列出已連線的用戶端名稱；若尚未有用戶端連線，則顯示「(connects on demand)」。

在 Custom 模式下，會多出一張 **MCP server** 卡片，內容包括：

- **Server URL**：要連線的伺服器，預設為 `http://localhost:8080`。
- **Authorization Token**：`none`、`oauth`（你的 ai-game.dev 帳號權杖，只會傳送給 localhost 伺服器）或 `token`（bearer 權杖；按 **New** 可產生一個）。
- **Start Server / Stop Server**：下載、啟動與停止符合此外掛所固定伺服器版本的本機伺服器。請參閱 [Connecting AI clients](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients#custom-mode)。

若環境變數強制指定模式或主機，會顯示一則黃色提示「Overridden by environment (GODOT\_MCP\_\*)」，此時在面板中的變更不會生效。

### AI 代理

選擇你使用的 AI 用戶端（預設為 Claude Code）。接著此區段會顯示：

- **Skills**：代理的技能檔案存放位置、載入外掛時自動更新這些檔案的 **Auto-generate** 開關，以及 **Generate** 按鈕。不支援技能的代理會顯示「Skills not supported by this agent」。
- **Model Context Protocol (MCP)**：代理的 MCP 設定是否已設定完成，並提供 **Configure** / **Reconfigure** 與 **Remove**。若在你設定代理之後伺服器設定發生變更，會出現 **Reconfiguration Required** 提示。

### MCP 功能

共三列：**Tools**、**Prompts** 與 **Resources**，每一列都會顯示可見項目數與總數（工具列還會顯示預估的權杖成本），並附有一個 **Open** 按鈕。開啟的視窗會列出所有項目，每個項目都有 **Visible** 開關，並提供篩選欄位。

**Visible** 只決定 MCP 用戶端是否會在工具清單中看到該項目。隱藏用不到的工具可讓代理的上下文更精簡。這不是存取控制：若用戶端以名稱呼叫被隱藏的工具，它仍會執行。

### 擴充功能

可選 Godot MCP 擴充功能的清單，附有 **Install** 與 **Update** 按鈕。它會讀取內嵌於你的 `.csproj` 中的擴充功能目錄；若清單為空，請參閱 [Extensions](https://ai-game.dev/zh-hant/docs/wiki/godot/extensions)。

### 頁尾

取得協助與回報問題的連結，以及一個 **Serialization Check** 視窗，可顯示所選節點或物件如何序列化給 AI（回報錯誤時很有用）。

## 設定儲存位置

此面板會將設定存到 `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 token。會覆寫已儲存的 token，且永遠不會寫回。 |
| `GODOT_MCP_LOG_LEVEL` | `Trace` 至 `None` | 記錄詳細程度。 |
| `GODOT_MCP_CREDENTIALS_DIR` | 絕對路徑 | 使用獨立的認證資料存放區，以便進行隔離測試。 |
| `GODOT_MCP_TOOL_FORMAT` | `Rql`、`Json` | 工具如何接收引數並回傳結果。預設為 `Rql`（精簡文字）；`Json` 會保留 JSON schema 與結果。 |
| `GODOT_MCP_SERVER_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-hant/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-hant/docs/wiki/godot/tools#rql)。

---

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

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