# 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 上。它会安装插件、让你登录、写入 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]` | 安装插件、修补 `.csproj`、启用插件。 |
| `install-extension <id> [path]` | 在 `.csproj` 中添加或更新扩展包。 |
| `remove-plugin [path]` | 在 `project.godot` 中禁用插件（文件保留）。 |
| `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 智能体生成技能文件。 |
| `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` 插件：从 GitHub 下载插件发布版（或复制本地版本），将 NuGet `PackageReference` 和扩展目录 `<EmbeddedResource>` 添加到 `.csproj`，设置 `EnableDynamicLoading`，并在 `project.godot` 中启用插件。可安全重复运行。

| 参数 | 含义 |
| --- | --- |
| `--source <path>` | 从本地文件夹复制插件，而不是下载（适用于离线、开发和 CI 场景）。 |
| `--version <x.y.z>` | 要下载的插件发布版本。默认为 CLI 自身的版本。使用 `--source` 时忽略。 |
| `--with-server` | 同时下载与之匹配的 `gamedev-mcp-server` 二进制文件，并按发布版校验和进行校验。 |
| `--server-source <path>` | 从本地文件夹或 `.zip` 安装服务器。隐含启用 `--with-server`。 |
| `--server-version <x.y.z>` | 要下载的服务器版本。默认为插件中固定的服务器版本。 |
| `--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-hans/docs/wiki/godot/extensions)。

## remove-plugin

在 `project.godot` 的 `[editor_plugins]` 段中禁用插件。它不会删除 `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`，以便插件在下次打开编辑器时加载。没有 `.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-hans/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]` 写入该 agent 的 MCP 配置，默认固定到此项目。agent id 与配置文件列在[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/godot/connecting-ai-clients#agents)中。

| 参数 | 说明 |
| --- | --- |
| `--list` | 列出所有 agent id。 |
| `--url <url>` | 服务器主机覆盖，例如本地服务器。 |
| `--token <token>` | Token 覆盖。默认 `GODOT_MCP_TOKEN`。 |
| `--no-pin` | 写入普通的 `/mcp` URL，而非固定到此项目的 URL。 |
| `--oauth` | 云端：仅配置 URL；agent 使用自己的 OAuth 登录。 |
| `--regenerate-key` | 云端：创建新的项目密钥并吊销旧密钥。 |

## setup-skills

`godot-cli setup-skills <agent> [path]` 将插件各工具族的 `SKILL.md` 文件写入该 agent 的 skills 文件夹（例如 `.claude/skills`）。它不需要运行中的编辑器。`--list` 显示每个 agent 的 skills 支持情况。

## configure

在 `.godot-mcp/features.json` 中列出或更改 MCP 客户端可见的工具、提示和资源。隐藏的条目在按名称调用时仍会运行。

| 参数 | 说明 |
| --- | --- |
| `--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` 向 `/api/tools/<tool>` 发送 POST 请求，`run-system-tool` 向 `/api/system-tools/<tool>` 发送 POST 请求（后者用于对 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-hans/docs/wiki/app/cli)。
- Unity 和 Unreal 分别有 `unity-mcp-cli` 和 `unreal-mcp-cli`：请参阅 [Unity MCP](https://ai-game.dev/zh-hans/docs/wiki/unity) 和 [Unreal MCP](https://ai-game.dev/zh-hans/docs/wiki/unreal) 的 wiki。

---

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

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