# godot-cli 參考 — Godot · AI Game Developer Wiki

Godot MCP 的每個 godot-cli 指令與旗標，從 install-plugin、login、setup-mcp 到 open、exec、run-tool、configure 與 install-extension。

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

`godot-cli` 是 Godot MCP 的命令列工具，發佈於 npm。它會安裝 addon、讓你登入、寫入 AI 代理程式設定、建置並以正確的連線設定開啟編輯器，還能從腳本呼叫工具。本頁列出 `godot-cli` 0.34.0 中每個指令及其旗標。

## 安裝與基本用法

```bash
npm install -g godot-cli
godot-cli --help
godot-cli <command> --help
```

需要 Node.js `^20.19.0` 或 `>=22.12.0`，可在 Windows、macOS 與 Linux 上執行。你也可以不安裝就直接執行任何指令：`npx godot-cli <command>`。

大多數指令接受專案資料夾作為選用的位置參數 `[path]`（或 `--path <path>`），預設為目前資料夾。每個指令都接受 `-v` / `--verbose` 以輸出診斷資訊。

## 指令總覽

| 指令 | 功能說明 |
| --- | --- |
| `install-plugin [path]` | 安裝 addon、修補 `.csproj`、啟用外掛。 |
| `install-extension <id> [path]` | 在 `.csproj` 中新增或更新擴充套件。 |
| `remove-plugin [path]` | 在 `project.godot` 中停用 addon（檔案保留）。 |
| `create-project [path]` | 建立最小化的 Godot 4 專案骨架。 |
| `build [path]` | 建置專案的 C# 組件。 |
| `open [path]` | 先建置，再以連線設定開啟 Godot 編輯器。 |
| `close [path]` | 停止該專案執行中的 Godot 編輯器。 |
| `exec [code]` | 透過 `script-execute` 在編輯器中執行 C#。 |
| `login [path]` | 使用裝置流程登入 ai-game.dev。 |
| `setup-mcp <agent> [path]` | 寫入 AI 代理程式的 MCP 設定。 |
| `setup-skills <agent> [path]` | 為 AI 代理程式產生 skill 檔案。 |
| `configure [path]` | 顯示或隱藏工具、提示與資源。 |
| `run-tool <tool> [path]` | 透過 HTTP 呼叫 MCP 工具。 |
| `run-system-tool <tool> [path]` | 透過 HTTP 呼叫系統工具。 |
| `status [path]` | 檢查編輯器與 MCP 伺服器。 |
| `wait-for-ready [path]` | 等待編輯器回應 `ping`。 |
| `update` | 更新 `godot-cli` 本身。 |

## install-plugin

完整安裝 `godot_mcp` addon：從 GitHub 下載 addon 發行版（或複製本機版本）、將 NuGet `PackageReference` 與擴充套件目錄 `<EmbeddedResource>` 加入 `.csproj`、設定 `EnableDynamicLoading`，並在 `project.godot` 中啟用外掛。可安全重複執行。

| 旗標 | 說明 |
| --- | --- |
| `--source <path>` | 從本機資料夾複製 addon，而非下載（離線、開發、CI 使用）。 |
| `--version <x.y.z>` | 要下載的 addon 發行版。預設為 CLI 的版本。搭配 `--source` 時忽略。 |
| `--with-server` | 同時下載對應的 `gamedev-mcp-server` 執行檔，並依發行版 checksum 驗證。 |
| `--server-source <path>` | 從本機資料夾或 `.zip` 安裝伺服器。隱含 `--with-server`。 |
| `--server-version <x.y.z>` | 要下載的伺服器版本。預設為 addon 指定的伺服器版本。 |
| `--enroll <code>` | 兌換代理程式註冊碼（不需瀏覽器即可讓外掛登入）。 |
| `--enroll-stdin` | 從 stdin 讀取註冊碼，避免留在 shell 歷史紀錄中。 |
| `--base-url <url>` | 用來兌換註冊碼的雲端 URL。預設為 `https://ai-game.dev`。 |

```bash
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject
```

## install-extension

`godot-cli install-extension <id> [path]` 會在擴充套件目錄中解析該 id（套件 id 或名稱），並新增或更新其 `<PackageReference>`。`--version <x.y.z>` 可指定確切版本，而非最新穩定版。之後請執行 `godot-cli build`。參見[擴充套件](https://ai-game.dev/zh-hant/docs/wiki/godot/extensions)。

## remove-plugin

在 `project.godot` 的 `[editor_plugins]` 區段中停用 addon。不會刪除 `addons/godot_mcp/` 或 `.csproj` 中的項目。

## create-project

建立最小化的 Godot 4 專案骨架（`project.godot` 與 `icon.svg`）。不會覆寫既有的 Godot、Unity 或 Unreal 專案。

| 旗標 | 說明 |
| --- | --- |
| `--dotnet` | 同時建立 `Godot.NET.Sdk` 的 C# `.csproj`（Godot MCP 需要）。 |
| `--name <name>` | 專案名稱。預設為資料夾名稱。 |

## build

對專案的 `.csproj` 執行 `dotnet build`，讓 addon 在下次開啟編輯器時載入。沒有 `.csproj` 的專案會略過。

| 旗標 | 說明 |
| --- | --- |
| `--configuration <cfg>` | MSBuild 組態。預設為 `Debug`。 |
| `--dotnet-path <path>` | 使用此 `dotnet` 執行檔，而非 `PATH` 上的版本。 |

## open

建置 C# 組件、尋找 Godot 編輯器並開啟專案。若建置失敗，就不會啟動編輯器。尋找編輯器的順序為：`--editor-path`、`GODOT_BIN` 或 `GODOT4_BIN` 環境變數、`PATH` 上的 Godot 執行檔（Windows 上優先採用 .NET 版本），最後是常見的安裝資料夾。

| 旗標 | 說明 |
| --- | --- |
| `--editor-path <path>` | 要使用的 Godot 編輯器執行檔。 |
| `--no-build` | 略過 C# 建置。 |
| `--build-configuration <cfg>` | 預先開啟建置的組態設定。預設為 `Debug`。 |
| `--no-connect` | 在沒有任何 `GODOT_MCP_*` 連線變數的情況下開啟。 |
| `--mode <Cloud or Custom>` | 設定 `GODOT_MCP_CONNECTION_MODE`。 |
| `--url <url>` | 設定 `GODOT_MCP_HOST`。 |
| `--cloud-url <url>` | 設定 `GODOT_MCP_CLOUD_URL`。 |
| `--token <token>` | 設定 `GODOT_MCP_TOKEN`。 |
| `--auth <None or Required>` | 設定 `GODOT_MCP_AUTH_OPTION`。 |
| `--log-level <level>` | 設定 `GODOT_MCP_LOG_LEVEL`（`Trace`、`Debug`、`Info`、`Warning`、`Error`、`None`）。 |
| `--headless` | 在專案的本機伺服器上啟動無視窗編輯器，並等待其就緒。若已有執行中的編輯器則重複使用。 |
| `--idle-timeout <seconds>` | 搭配 `--headless`：在沒有工具呼叫的情況下經過這麼多秒後結束（`0` = 永不）。 |
| `--ready-timeout <ms>` | 搭配 `--headless`：等待編輯器就緒的時間長度。 |

## close

以正常方式停止為該專案執行中的 Godot 編輯器。

| 旗標 | 說明 |
| --- | --- |
| `--timeout <seconds>` | 等待正常結束的時間。預設 30。 |
| `--force` | 若編輯器未及時結束，強制終止它。 |
| `--owned-only` | 僅關閉由 `godot-cli` 啟動的編輯器（`exec`、`open --headless`），絕不關閉你自己的。它會先儲存已開啟的場景。 |
| `--token <token>` | 搭配 `--owned-only`：bearer token。預設為 `GODOT_MCP_TOKEN`。 |

## exec

使用 `script-execute` 工具在專案的編輯器中執行 C#。程式碼是一般的陳述式；最後一個運算式即為結果。若該專案已有編輯器在執行，會重複使用它（你的編輯器必須處於 Custom 模式並已啟動本機伺服器）。否則 `exec` 會建置專案並啟動連線到本機伺服器的無視窗編輯器，該編輯器在沒有呼叫經過 `--idle` 秒後結束（預設 300）。

```bash
godot-cli exec '1 + 2' --path ./MyGodotProject
godot-cli exec -f snippet.cs --using MyGame.Gameplay
godot-cli exec 'Helper.Twice(21)' --include helpers
```

| 旗標 | 說明 |
| --- | --- |
| `--path <path>` | 專案資料夾。 |
| `-f, --file <file>` | 從檔案讀取程式碼（`-` 代表 stdin）。 |
| `--using <namespace>` | 額外的命名空間。可重複指定。 |
| `--include <path>` | 位於 `<project>/.ai-game-dev/snippets` 下的輔助 `.cs` 檔案或資料夾。可重複指定。 |
| `--window` | 以視窗模式啟動編輯器，而非無視窗模式。 |
| `--idle <seconds>` | 已啟動的編輯器結束前的閒置時間（`0` = 永不）。 |
| `--ready-timeout <ms>` | 等待已啟動編輯器的時間長度。 |
| `--timeout <ms>` | 工具呼叫逾時。預設 310000。 |
| `--no-build` | 啟動編輯器前不進行建置。 |
| `--editor-path <path>` | Godot 編輯器執行檔。 |
| `--url <url>` | 本機 MCP 伺服器 URL。預設：專案的本機連接埠。 |
| `--token <token>` | Bearer token。預設為 `GODOT_MCP_TOKEN`。 |
| `--raw` | 輸出原始的工具回應 JSON。 |

編譯錯誤會指向程式碼片段的該行，並以代碼 1 結束。

## login

使用 OAuth 2.1 裝置流程登入 ai-game.dev，並將憑證儲存到 `~/.ai-game-dev/credentials.json`，編輯器會自動讀取。請參閱[連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients#device-flow)。

| 旗標 | 說明 |
| --- | --- |
| `--project <path>` | 改為將各專案專屬的憑證儲存在 `<path>/.ai-game-dev/` 下。 |
| `--base-url <url>` | 登入其他伺服器。預設為 `https://ai-game.dev`。 |
| `--force` | 即使憑證已存在仍重新登入。 |
| `--tools-only` | CI 模式：建立僅供工具使用的憑證，桌面應用程式不會讀取它。 |
| `--yes` | 不詢問即取代其他帳號的憑證。 |

## setup-mcp

`godot-cli setup-mcp <agent> [path]` 會寫入該代理程式的 MCP 設定，預設釘選到此專案。代理程式 id 與設定檔列於[連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients#agents)。

| 旗標 | 說明 |
| --- | --- |
| `--list` | 列出所有代理程式 id。 |
| `--url <url>` | 覆寫伺服器主機，例如本機伺服器。 |
| `--token <token>` | 覆寫 token。預設為 `GODOT_MCP_TOKEN`。 |
| `--no-pin` | 寫入單純的 `/mcp` URL，而非釘選的 URL。 |
| `--oauth` | 雲端：僅含 URL 的設定；代理程式會以自己的 OAuth 登入。 |
| `--regenerate-key` | 雲端：建立新的專案金鑰並撤銷舊的。 |

## setup-skills

`godot-cli setup-skills <agent> [path]` 會為外掛的各工具系列，將 `SKILL.md` 檔案寫入代理程式的 skills 資料夾（例如 `.claude/skills`）。不需要有執行中的編輯器。`--list` 會顯示各代理程式的 skills 支援情況。

## configure

列出或變更 MCP 用戶端能看到哪些工具、提示與資源，設定存於 `.godot-mcp/features.json`。隱藏的項目在被以名稱呼叫時仍會執行。

| 旗標 | 說明 |
| --- | --- |
| `--list` | 顯示目前的設定。 |
| `--enable-tools <names>` / `--disable-tools <names>` | 顯示或隱藏工具（以逗號分隔）。 |
| `--enable-all-tools` / `--disable-all-tools` | 顯示或隱藏所有工具。 |
| `--enable-prompts <names>` / `--disable-prompts <names>` | 顯示或隱藏提示。 |
| `--enable-all-prompts` / `--disable-all-prompts` | 顯示或隱藏所有提示。 |
| `--enable-resources <names>` / `--disable-resources <names>` | 顯示或隱藏資源。 |
| `--enable-all-resources` / `--disable-all-resources` | 顯示或隱藏所有資源。 |
| `--agent <id>` | 透過受管理的伺服器執行檔設定 agent（需要 `install-plugin --with-server`）。 |
| `--url <url>` | 搭配 `--agent`：覆寫伺服器 URL。 |

## run-tool 與 run-system-tool

直接透過伺服器的 HTTP API 呼叫工具：`run-tool` 會 POST 到 `/api/tools/<tool>`，`run-system-tool` 則 POST 到 `/api/system-tools/<tool>`（對 MCP 用戶端隱藏的工具，例如 `ping`）。

```bash
godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject
```

| 旗標 | 說明 |
| --- | --- |
| `--url <url>` | 伺服器基底 URL。 |
| `--token <token>` | Bearer token。預設為 `GODOT_MCP_TOKEN`。 |
| `--input <json>` | 以 JSON 字串表示的工具引數。 |
| `--input-file <file>` | 從檔案讀取 JSON 引數。 |
| `--raw` | 輸出原始 JSON。 |
| `--timeout <ms>` | 請求逾時。預設為 60000。 |

若未指定 `--url`，伺服器的選擇順序為：先看 `GODOT_MCP_HOST`，再看 `GODOT_MCP_CLOUD_URL`，當 `GODOT_MCP_CONNECTION_MODE=Cloud` 時使用雲端，接著是專案已登錄的伺服器，最後才是專案的本機連接埠。

## status 與 wait-for-ready

`status` 會偵測專案是否有執行中的編輯器，並探測伺服器（`--url`、`--token`、`--timeout <ms>`，預設 5000）。`wait-for-ready` 會持續輪詢 `ping`，直到編輯器回應（`--url`、`--token`、`--timeout <ms>` 預設 120000、`--interval <ms>` 預設 3000）。可在指令碼中於 `open` 之後使用。

## update

`godot-cli update` 會向 npm 檢查是否有較新的 `godot-cli` 並安裝；`--check` 僅回報結果。

## 相關

- AI Game Dev 應用程式有專屬的 `gamedev` CLI：[App CLI](https://ai-game.dev/zh-hant/docs/wiki/app/cli)。
- Unity 與 Unreal 分別有 `unity-mcp-cli` 與 `unreal-mcp-cli`：請參閱 [Unity MCP](https://ai-game.dev/zh-hant/docs/wiki/unity) 與 [Unreal MCP](https://ai-game.dev/zh-hant/docs/wiki/unreal) 的 wiki。

---

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

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