疑難排解
解決 AI Game Dev 應用程式與 gamedev CLI 的常見問題：登入、模型、引擎外掛與編輯器連線、套件、本機與雲端生成。
本頁彙整 AI Game Dev 應用程式與 gamedev CLI 使用者最常遇到的問題，並說明可能原因與解決方式。請依領域尋找對應的症狀：登入、模型、引擎連線、套件、本機模型、雲端生成或 CLI。
登入
登入用的瀏覽器視窗沒有開啟。 沒有設定預設瀏覽器，或防火牆阻擋了登入。請設定預設瀏覽器，然後再次選擇 Sign in。若位於公司 Proxy 後方，請允許對 ai-game.dev 的對外 HTTPS 連線。在 CLI 中，/login 會顯示一組代碼和一個網址，您可以改用其他裝置開啟。
應用程式回到登入畫面，或 CLI 要求執行 /login。 您的工作階段已過期或被撤銷，例如從帳戶的 Connected devices 頁面撤銷。請重新登入；您的對話與設定都會保留。
無介面（headless）執行以代碼 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 可取消等待；已經啟動的編輯器會保持開啟。若事先自行開啟編輯器，長時間的工作階段就不必等待。
建立專案時顯示未安裝引擎編輯器。 請先安裝引擎，或在建立對話框中手動選擇已安裝的編輯器。
套件
「需要 AI Game Dev >=X，目前為 Y」。 該套件需要較新版本的應用程式。請更新應用程式（請參閱安裝說明）。
某個套件顯示警告數量。 開啟 Packages 視窗、選取該套件，然後查看其 Errors 分頁。應用程式記錄檔中 pkg:<id> 底下有詳細資訊。
專案中的套件停止運作。 若套件主機在五分鐘內當機三次，就不會自動重新啟動。請在 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>。
「套件 X 的工具在此工作階段無法使用」。 此工作階段已設定同名的 MCP 伺服器（由您、專案或引擎設定）。請在 Settings、MCP servers 中重新命名或移除另一個伺服器。
連結的套件資料夾沒有任何作用。 id-mismatch 表示該資料夾的 manifest 指向另一個套件；not-found 表示資料夾已移動。請執行 gamedev pkg unlink <id> 以回到已發佈的版本。
聊天中缺少某個工具。 已安裝的套件不會為每個聊天加入工具。請在工作階段的 Tools 列開啟該工具（CLI：/config、Tools）。變更會從下一則訊息開始生效。
本機影像與影片模型
我的電腦沒有提供某個模型。 每個模型都會列出適合的硬體；應用程式只會提供您的 GPU、視訊記憶體與驅動程式能執行的模型。若您更換了硬體或驅動程式，請執行 /images redetect。請參閱硬體需求表。
生成因「記憶體不足」而失敗，或速度非常慢。 視訊記憶體不足的執行會以較小的記憶體預算重試一次。若默默退回 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。
「執行中的主機尚未提供……。請關閉所有 AI Game Dev 視窗與 CLI，然後重新啟動」。 背景服務的版本比您啟動的 CLI 或應用程式舊。請關閉所有 AI Game Dev 視窗與 CLI 後重新啟動，或在 CLI 使用 /update now。
我需要記錄檔來回報錯誤。 gamedev daemon status 會顯示背景服務的狀態，gamedev daemon logs --lines 200 會印出最近的記錄。請在 Discord 或 GitHub 分享相關部分，切勿分享您的憑證。