# 문제 해결 — Godot · AI Game Developer Wiki

애드온이 로드되거나 컴파일되지 않는 문제부터 빈 Extensions 목록, 도구 누락, 재로드 오류, .NET 10 크래시까지 Godot MCP의 흔한 문제를 해결합니다.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/godot/troubleshooting).

대부분의 Godot MCP 문제는 네 가지 원인 중 하나에서 비롯됩니다: 잘못된 Godot 빌드, 애드온과 맞지 않는 `.csproj`, 빌드되지 않은 C# 어셈블리, 또는 올바른 서버를 가리키지 않는 AI 클라이언트입니다. 화면에 보이는 증상과 일치하는 섹션을 순서대로 확인하세요. 막혔다면 독의 **Log Level**을 `Debug`로 올리고 문제를 재현한 뒤 Output 패널을 읽어 보세요.

## 애드온이 로드되지 않음

### 처음 열 때 "Unable to load addon script" 발생

Godot은 에디터가 시작되자마자 활성화된 애드온을 인스턴스화합니다. 한 번도 빌드한 적 없는 C# 프로젝트를 처음 열면 어셈블리가 아직 없으므로, Godot은 `res://addons/godot_mcp/Editor/GodotMcpPlugin.cs`를 로드할 수 없다고 보고하고 애드온을 비활성화합니다.

해결 방법: 먼저 빌드한 다음 **Project, Project Settings, Plugins**에서 플러그인을 다시 활성화하세요.

```bash
godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject
```

`godot-cli open`은 항상 빌드한 뒤 에디터를 시작하므로 이 문제를 피할 수 있습니다.

### 애드온이 컴파일되지 않음

- 표준 Godot 빌드를 사용하고 있습니다. Godot MCP는 Godot 4.3 이상의 **.NET (mono)** 빌드가 필요합니다.
- `.csproj`에 NuGet 패키지가 없거나, 설치한 애드온과 버전이 다릅니다. `godot-cli install-plugin`을 다시 실행하거나, [Installation](https://ai-game.dev/ko/docs/wiki/godot/installation#nuget-packages)에서 사용 중인 애드온 릴리스 버전에 맞는 블록을 복사하세요.
- 프로젝트에 `.csproj`가 없습니다. Godot에서 C# 솔루션을 생성하거나, 새 프로젝트라면 `godot-cli create-project --dotnet`을 사용하세요.
- .NET 8 SDK가 설치되어 있지 않거나 `PATH`에 없습니다.

### NuGet 어셈블리에 대한 FileNotFoundException

Godot은 에디터에서 프로젝트의 NuGet 패키지를 스스로 확인하지 않습니다. 애드온이 빌드의 `.deps.json`과 NuGet 캐시를 읽어 이를 처리합니다. 그래도 어셈블리를 찾지 못하면 `dotnet restore`를 실행하고 다시 빌드하세요. 문제가 계속되면 `.godot/mono/temp/obj`와 `.godot/mono/temp/bin`을 삭제하고 다시 빌드하세요. 오래된 빌드 출력이 흔한 원인입니다.

## Play로 시작한 게임이 C# 스크립트를 생성할 수 없음

증상: `EditorPlugin` 클래스를 지목하는 `TypeLoadException`이 발생한 뒤 모든 C# 스크립트가 "Cannot instantiate C# script because the associated class could not be found"로 실패합니다. `.csproj`에 `<EnableDynamicLoading>true</EnableDynamicLoading>`가 빠져 있어 패키지 어셈블리가 게임 어셈블리 옆에 복사되지 않은 것입니다. `<TargetFramework>` 옆의 `<PropertyGroup>`에 이 항목을 추가하고 다시 빌드하세요. `godot-cli install-plugin`과 `create-project`는 이 설정을 자동으로 넣어 줍니다.

## Extensions 목록이 비어 있음

독은 컴파일된 프로젝트에서 확장 카탈로그를 읽습니다. `.csproj`에 다음 줄이 필요하며, 그다음 다시 빌드해야 합니다:

```xml
<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
```

`LogicalName`은 정확히 `Godot-MCP.extensions.catalog.json`이어야 합니다. 독에서 `.csproj`를 찾을 수 없다고 표시되면 애드온이 Godot C# 프로젝트 안에 없는 것입니다. [Extensions](https://ai-game.dev/ko/docs/wiki/godot/extensions#catalog)를 참고하세요.

## 에디터가 연결되지 않음

- **클라우드 모드, 로그인하지 않음.** 독에서 **Authorize**를 클릭하거나 `godot-cli login`을 실행하세요. 독에 로그인 상태가 표시됩니다.
- **환경 변수로 재정의됨.** "Overridden by environment (GODOT\_MCP\_\*)"라는 노란색 안내는 변수나 `.env` 파일이 모드나 호스트를 강제하고 있어 독에서 변경한 내용이 아무 효과가 없다는 뜻입니다. 해당 변수를 제거하거나 값을 변경하세요.
- **커스텀 모드, 서버 없음.** 독에서 **Start Server**를 클릭하거나 직접 서버를 시작하세요. 오프라인일 때는 서버 다운로드가 Output 패널에 경고와 함께 실패하고 로컬 서버가 시작되지 않습니다. 클라우드 모드를 사용하거나 이미 가지고 있는 서버를 실행하세요.
- **원격 호스트에서 `oauth`를 사용하는 커스텀 모드.** 애드온은 localhost 서버에만 계정 토큰을 보냅니다. 다른 호스트의 경우 `GODOT_MCP_TOKEN`을 설정하세요. 그렇지 않으면 "Refusing to send your ai-game.dev account token" 오류와 함께 연결이 실패합니다.

터미널에서 `godot-cli status ./MyGodotProject`와 `godot-cli wait-for-ready ./MyGodotProject`로 확인하세요.

## AI 에이전트에 Godot 도구가 보이지 않음

- 에이전트가 설정이 작성되기 전에 시작되었습니다. 에이전트를 다시 시작하거나 MCP 서버를 다시 로드하세요.
- Claude Code는 시작한 폴더에서 `.mcp.json`을 읽습니다. 프로젝트 폴더에서 시작하거나, 시작하는 위치에 설정을 작성하세요.
- 여러 에디터가 연결되어 있는데 에이전트가 단순한 `/mcp` URL을 사용하고 있습니다. `setup-mcp`가 기본으로 작성하는 고정 URL을 사용해 에이전트가 올바른 프로젝트에 접속하도록 하세요.
- 설정이 에디터와 다른 서버(클라우드 vs 로컬)를 가리키고 있습니다. 모드를 변경한 뒤 `godot-cli setup-mcp <agent>`를 다시 실행하거나 독에서 **Reconfigure**를 클릭하세요.
- 도구가 숨겨져 있습니다. 도크의 MCP 기능 섹션이나 `godot-cli configure --list`를 확인하세요. 숨겨진 도구는 에이전트에게 나열되지 않습니다.

## C# 다시 빌드 중 도구 호출 실패

Godot는 빌드된 DLL이 변경된 후 약 0.5초 뒤에 프로젝트의 C# 어셈블리를 다시 로드합니다(`script-build`, Build 버튼 또는 `dotnet build`). 애드온은 해당 어셈블리의 일부이므로 해제되었다가 다시 빌드되고 몇 초 안에 다시 연결됩니다. 다시 로드되는 시점에는 새 호출이 재시도 가능한 오류("Godot is about to reload the project's C# assembly … Retry in a few seconds")와 함께 거부됩니다. 기다렸다가 다시 시도하세요. `script-build`는 다시 로드된 후에 결과를 반환합니다.

## .NET 10에서 다시 로드 후 에디터가 충돌하거나 멈춤

이것은 .NET 런타임 버그입니다(dotnet/runtime#135441). .NET 10 서비스 수정이 배포될 때까지 에디터 프로세스에 이 환경 변수를 설정하고 Godot를 재시작하세요:

```text
DOTNET_ThreadPool_ThreadsToKeepAlive=-1
```

Windows에서는 `setx DOTNET_ThreadPool_ThreadsToKeepAlive -1`로 설정할 수 있습니다. `godot-cli open`이나 `exec`로 시작한 에디터에는 자동으로 적용됩니다. .NET 런타임에 수정 사항이 포함되면 이 변수를 제거하세요.

## 호출이 이전 빌드로 전달됨

도구 호출이 코드의 이전 버전처럼 동작한다면 같은 프로젝트에 에디터가 두 개 이상 연결되어 있을 수 있습니다. 예를 들어 잊고 있던 헤드리스 에디터가 그렇습니다. 여분의 에디터를 닫고(`godot-cli close --owned-only`는 `godot-cli`가 시작한 에디터를 닫습니다) 에디터 하나만 연결된 상태로 유지하세요.

## 빌드가 MissingMethodException으로 실패함

프로젝트의 `Godot.NET.Sdk` 버전은 실행하는 에디터와 일치해야 합니다. 4.3을 대상으로 빌드된 프로젝트는 API가 바뀐 4.4 이상 에디터에서 `MissingMethodException`을 발생시킬 수 있습니다. `.csproj`의 `Sdk="Godot.NET.Sdk/…"` 버전을 에디터 버전에 맞게 업데이트하고 다시 빌드하세요.

## 여전히 해결되지 않는다면

[FAQ](https://ai-game.dev/ko/docs/wiki/godot/faq)와 사이트 [FAQ](https://ai-game.dev/docs/faq)를 확인하거나, Output 패널 로그와 Godot, .NET, 애드온 버전을 함께 [Godot-MCP 이슈 트래커](https://github.com/IvanMurzak/Godot-MCP/issues)에 문제를 보고하세요.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/godot/troubleshooting

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/godot/troubleshooting