문제 해결
AI Game Dev 앱과 gamedev CLI에서 흔한 문제 해결: 로그인, 모델, 엔진 플러그인과 에디터 연결, 패키지, 로컬 및 클라우드 생성.
이 페이지는 AI Game Dev 앱과 gamedev CLI 사용자가 가장 자주 겪는 문제를 예상 원인과 해결 방법과 함께 정리합니다. 로그인, 모델, 엔진 연결, 패키지, 로컬 모델, 클라우드 생성, CLI 영역에서 증상을 찾아보세요.
로그인
로그인 브라우저 창이 열리지 않습니다. 기본 브라우저가 설정되어 있지 않거나 방화벽이 로그인을 차단한 경우입니다. 기본 브라우저를 설정하고 Sign in을 다시 선택하세요. 회사 프록시 뒤에 있다면 ai-game.dev로 나가는 HTTPS를 허용하세요. CLI에서는 /login이 코드와 주소를 보여 주므로 다른 기기에서 열 수도 있습니다.
앱이 다시 로그인 화면으로 돌아갔거나 CLI가 /login을 요구합니다. 세션이 만료되었거나 취소된 경우입니다(예: 계정의 Connected devices 페이지에서). 다시 로그인하세요. 채팅과 설정은 그대로 유지됩니다.
헤드리스 실행이 코드 2로 종료됩니다. 컴퓨터가 로그인되어 있지 않거나, 프롬프트가 비어 있거나, 폴더 또는 플래그를 사용할 수 없는 경우입니다. gamedev를 한 번 대화형으로 실행하고 /login을 입력하세요. 종료 코드를 참고하세요.
잘못된 계정으로 로그인되어 있습니다. 앱, CLI, gamedev acp는 컴퓨터당 하나의 로그인을 공유합니다. CLI에서 /login --switch를 사용하거나 데스크톱 앱에서 로그아웃한 뒤 다시 로그인하세요.
흐름에 대한 자세한 내용: 인증 가이드.
모델
모델 목록이 로딩 중이거나 연결할 수 없다고 표시됩니다. 목록은 ai-game.dev에서 가져옵니다. 연결도 없고 마지막 목록의 저장된 사본도 없다면 표시할 것이 없습니다. 연결을 확인하고 선택기를 다시 여세요.
모델이 회색으로 표시됩니다. 이유는 모델 이름 아래에 표시됩니다. 더 높은 플랜이 필요하거나(가격 페이지 참고), 청구지 주소의 국가에서 제공되지 않거나(모델 제공 지역 참고), 계정에서 연령 확인이 필요할 수 있습니다. 모델 목록 하단에 제공 여부 판단의 기준이 되는 지역이 표시됩니다.
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, Unreal, Godot 가이드를 따르세요.
사이드바에 Update Package가 표시됩니다. 더 새로운 플러그인 버전이 있습니다. 클릭하면 프로젝트의 플러그인이 업데이트됩니다.
에디터에 "Disconnected"가 표시됩니다. 에디터가 인증을 마치지 못했거나 Cloud 연결이 끊긴 경우입니다. 에디터에서 AI Game Developer 창을 열고 Cloud를 선택한 뒤 Authorize를 클릭하고 Ready가 될 때까지 기다리세요.
에이전트가 에디터를 오래 기다립니다. 큰 프로젝트는 여는 데 시간이 걸립니다. 앱은 에디터가 시작될 때까지 최대 15분, 도구가 준비될 때까지 최대 2분을 더 기다립니다. Stop을 눌러 대기를 취소하세요. 이미 시작된 에디터는 열린 채로 유지됩니다. 긴 세션 전에 에디터를 직접 열어 두면 대기를 피할 수 있습니다.
프로젝트를 만들 때 엔진 에디터가 설치되어 있지 않다고 합니다. 먼저 엔진을 설치하거나 만들기 대화상자에서 설치된 에디터를 직접 선택하세요.
패키지
"requires AI Game Dev >=X, you have Y". 패키지가 더 새로운 앱을 필요로 합니다. 앱을 업데이트하세요(설치 참고).
패키지에 경고 개수가 표시됩니다. 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를 실행하세요. 하드웨어 표를 참고하세요.
생성이 "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에 관련 부분만 공유하고, 자격 증명은 절대 공유하지 마세요.