# 문제 해결 — AI Game Dev 앱 & CLI · AI Game Developer Wiki

AI Game Dev 앱과 gamedev CLI에서 흔한 문제 해결: 로그인, 모델, 엔진 플러그인과 에디터 연결, 패키지, 로컬 및 클라우드 생성.

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

이 페이지는 AI Game Dev 앱과 `gamedev` CLI 사용자가 가장 자주 겪는 문제를 예상 원인과 해결 방법과 함께 정리합니다. 로그인, 모델, 엔진 연결, 패키지, 로컬 모델, 클라우드 생성, CLI 영역에서 증상을 찾아보세요.

## 로그인

**로그인 브라우저 창이 열리지 않습니다.** 기본 브라우저가 설정되어 있지 않거나 방화벽이 로그인을 차단한 경우입니다. 기본 브라우저를 설정하고 **Sign in**을 다시 선택하세요. 회사 프록시 뒤에 있다면 ai-game.dev로 나가는 HTTPS를 허용하세요. CLI에서는 `/login`이 코드와 주소를 보여 주므로 다른 기기에서 열 수도 있습니다.

**앱이 다시 로그인 화면으로 돌아갔거나 CLI가 `/login`을 요구합니다.** 세션이 만료되었거나 취소된 경우입니다(예: 계정의 Connected devices 페이지에서). 다시 로그인하세요. 채팅과 설정은 그대로 유지됩니다.

**헤드리스 실행이 코드 2로 종료됩니다.** 컴퓨터가 로그인되어 있지 않거나, 프롬프트가 비어 있거나, 폴더 또는 플래그를 사용할 수 없는 경우입니다. `gamedev`를 한 번 대화형으로 실행하고 `/login`을 입력하세요. [종료 코드](https://ai-game.dev/ko/docs/wiki/app/cli#headless)를 참고하세요.

**잘못된 계정으로 로그인되어 있습니다.** 앱, CLI, `gamedev acp`는 컴퓨터당 하나의 로그인을 공유합니다. CLI에서 `/login --switch`를 사용하거나 데스크톱 앱에서 로그아웃한 뒤 다시 로그인하세요.

흐름에 대한 자세한 내용: [인증 가이드](https://ai-game.dev/docs/auth).

## 모델

**모델 목록이 로딩 중이거나 연결할 수 없다고 표시됩니다.** 목록은 ai-game.dev에서 가져옵니다. 연결도 없고 마지막 목록의 저장된 사본도 없다면 표시할 것이 없습니다. 연결을 확인하고 선택기를 다시 여세요.

**모델이 회색으로 표시됩니다.** 이유는 모델 이름 아래에 표시됩니다. 더 높은 플랜이 필요하거나([가격 페이지](https://ai-game.dev/pricing) 참고), 청구지 주소의 국가에서 제공되지 않거나([모델 제공 지역](https://ai-game.dev/model-availability) 참고), 계정에서 연령 확인이 필요할 수 있습니다. 모델 목록 하단에 제공 여부 판단의 기준이 되는 지역이 표시됩니다.

**CLI에서 `--model`이 거부됩니다.** 해당 모델을 계정에서 사용할 수 없습니다. `/model`로 하나를 선택하거나 다른 id를 전달하세요.

**사용량이 빨리 소진됩니다.** 사용량은 월간 허용량의 백분율로 표시됩니다. 더 큰 모델은 같은 작업에 더 많은 사용량을 씁니다. 일상적인 편집에는 더 빠른 모델을 사용하고, 세션에 필요한 도구만 켜 두세요.

## 엔진 플러그인과 에디터 연결

**CLI가 폴더에 Unity, Godot 또는 Unreal 프로젝트가 없다고 합니다.** 프로젝트의 루트 폴더를 여세요. Unity는 `ProjectSettings/`가 있는 폴더, Godot는 `project.godot`이 있는 폴더, Unreal은 `.uproject` 파일이 있는 폴더입니다.

**플러그인이 설치되지 않았습니다.** 엔진이나 프로젝트를 찾지 못한 경우입니다. 엔진이 설치되어 있는지(Unity Hub, Unreal Engine 또는 Godot)와 실제 프로젝트 폴더를 열었는지 확인한 뒤 사이드바에서 **Install Package**를 클릭하거나 `/install-plugin`을 실행하세요. 수동으로 설치하려면 [Unity](https://ai-game.dev/ko/docs/wiki/unity/installation), [Unreal](https://ai-game.dev/ko/docs/wiki/unreal/installation), [Godot](https://ai-game.dev/ko/docs/wiki/godot/installation) 가이드를 따르세요.

**사이드바에 Update Package가 표시됩니다.** 더 새로운 플러그인 버전이 있습니다. 클릭하면 프로젝트의 플러그인이 업데이트됩니다.

**에디터에 "Disconnected"가 표시됩니다.** 에디터가 인증을 마치지 못했거나 Cloud 연결이 끊긴 경우입니다. 에디터에서 **AI Game Developer** 창을 열고 **Cloud**를 선택한 뒤 **Authorize**를 클릭하고 **Ready**가 될 때까지 기다리세요.

**에이전트가 에디터를 오래 기다립니다.** 큰 프로젝트는 여는 데 시간이 걸립니다. 앱은 에디터가 시작될 때까지 최대 15분, 도구가 준비될 때까지 최대 2분을 더 기다립니다. **Stop**을 눌러 대기를 취소하세요. 이미 시작된 에디터는 열린 채로 유지됩니다. 긴 세션 전에 에디터를 직접 열어 두면 대기를 피할 수 있습니다.

**프로젝트를 만들 때 엔진 에디터가 설치되어 있지 않다고 합니다.** 먼저 엔진을 설치하거나 만들기 대화상자에서 설치된 에디터를 직접 선택하세요.

## 패키지

**"requires AI Game Dev >=X, you have Y".** 패키지가 더 새로운 앱을 필요로 합니다. 앱을 업데이트하세요([설치](https://ai-game.dev/ko/docs/wiki/app/installation#updates) 참고).

**패키지에 경고 개수가 표시됩니다.** Packages 창을 열고 패키지를 선택한 뒤 **Errors** 탭을 읽어 보세요. 자세한 내용은 앱 로그의 `pkg:<id>` 아래에 있습니다.

**프로젝트에서 패키지가 작동을 멈췄습니다.** 패키지 호스트가 5분 이내에 세 번 충돌하면 자동으로 다시 시작되지 않습니다. Packages 창에서 **Reload**를 클릭하거나 CLI에서 `/packages reload`를 실행하세요.

**패키지가 업데이트되지 않습니다.** 자동 업데이트는 패키지별, 컴퓨터별로 적용됩니다. 해당 패키지의 **Auto-update** 스위치를 확인하세요. 로컬 폴더와 태그에 고정된 GitHub 소스의 패키지는 절대 자동으로 업데이트되지 않습니다. **Check for updates** 또는 `gamedev pkg update <id>`를 사용하세요.

**버전이 "not in registry anymore"로 표시됩니다.** 해당 버전은 철회되었습니다. 계속 작동하지만 업데이트 대상으로는 제안되지 않습니다.

**종속성이 제외되어 패키지가 차단되었습니다.** 이 프로젝트의 어느 수준에서 종속성이 꺼져 있습니다. Packages 창에서 **Include it again**을 선택하거나 `gamedev pkg include <id>`를 실행하세요.

**"Tools of package X are unavailable in this session".** 같은 이름의 MCP 서버가 이미 세션에 구성되어 있습니다(사용자, 프로젝트 또는 엔진에 의해). **Settings**, **MCP servers**에서 다른 서버의 이름을 바꾸거나 제거하세요.

**연결된 패키지 폴더가 아무 효과가 없습니다.** `id-mismatch`는 폴더의 매니페스트가 다른 패키지를 가리킨다는 뜻이고, `not-found`는 폴더가 이동했다는 뜻입니다. `gamedev pkg unlink <id>`를 실행하면 게시된 버전으로 돌아갑니다.

**채팅에서 도구가 보이지 않습니다.** 설치된 패키지가 모든 채팅에 도구를 추가하지는 않습니다. 세션의 Tools 행에서 도구를 켜세요(CLI: `/config`, **Tools**). 변경 사항은 다음 메시지부터 적용됩니다.

## 로컬 이미지 및 비디오 모델

**제 컴퓨터에는 모델이 제공되지 않습니다.** 각 모델은 지원하는 하드웨어를 나열하며, 앱은 GPU, 비디오 메모리, 드라이버가 실행할 수 있는 것만 제공합니다. 하드웨어나 드라이버를 변경했다면 `/images redetect`를 실행하세요. [하드웨어 표](https://ai-game.dev/ko/docs/wiki/app/packages-catalog#local-image-models)를 참고하세요.

**생성이 "out of memory"로 실패하거나 매우 느립니다.** 비디오 메모리가 부족한 실행은 더 작은 메모리 예산으로 한 번 재시도됩니다. CPU로 조용히 대체되는 경우는 숨기지 않고 실패로 보고됩니다. 더 가벼운 모델(예: Lightning 변형 또는 Z-Image Turbo)을 사용하거나 GPU를 많이 쓰는 다른 프로그램을 종료하세요. `/images stop`은 대기 중인 이미지를 취소하고 GPU를 해제합니다.

**디스크가 가득 찼습니다.** **Settings**, **Model storage**에서 모델 저장 위치를 더 큰 드라이브로 옮기거나 `/images storage <new folder>`를 사용하세요. `/images free-space`는 어떤 모델도 사용하지 않는 파일을 삭제합니다.

**이미지 런타임이 차단되었거나 손상되었습니다.** `/images reinstall`을 실행해 다시 설정하세요.

## 클라우드 생성

**에이전트가 클라우드 생성이 켜져 있지 않다고 합니다.** 세션의 Tools 행에서 **Cloud generation**을 켜거나 CLI에서 `/cloud ask`를 사용하세요.

**클라우드 모델을 사용할 수 없습니다.** 클라우드 생성은 유료 플랜용이며, 일부 모델은 Studio 이상이 필요하고, 일부는 모든 지역에서 제공되지 않습니다. **Models** 탭에 이유가 표시됩니다. 실패한 작업은 허용량을 사용하지 않습니다.

## SuperCollider 및 Blender

**Linux에서 음악이 시작되지 않습니다.** SuperCollider 런타임은 현재 Windows와 macOS에서 사용할 수 있습니다.

**Blender를 찾을 수 없습니다.** `/blender list`를 실행하면 앱이 찾은 모든 Blender를 볼 수 있고, `/blender setup`으로 다시 설정하거나(선택적으로 Blender 경로 지정), `/blender`가 포터블 Blender를 다운로드하도록 할 수 있습니다. Blender 4.2 이상이 필요합니다.

## CLI 및 백그라운드 서비스

**CLI가 오래되었습니다.** `gamedev update`를 실행하세요.

**"The running host does not offer … yet. Quit every AI Game Dev window and CLI, then start again".** 백그라운드 서비스가 실행한 CLI 또는 앱보다 오래되었습니다. 모든 AI Game Dev 창과 CLI를 닫고 다시 시작하거나 CLI에서 `/update now`를 사용하세요.

**버그 보고용 로그가 필요합니다.** `gamedev daemon status`는 백그라운드 서비스의 상태를 보여 주고, `gamedev daemon logs --lines 200`은 최근 로그를 출력합니다. Discord나 GitHub에 관련 부분만 공유하고, 자격 증명은 절대 공유하지 마세요.

## 여전히 막혔다면

최근 수정 사항은 [FAQ](https://ai-game.dev/ko/docs/wiki/app/faq), 사이트 [FAQ](https://ai-game.dev/docs/faq), [릴리스 노트](https://ai-game.dev/ko/releases)를 확인하세요.

---

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

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