故障排查
解决 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> 下会有详细信息。
项目中的包停止工作。 如果包宿主在五分钟内崩溃三次，就不会自动重启。请在 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。
我需要日志来报告 bug。 gamedev daemon status 显示后台服务的状态，gamedev daemon logs --lines 200 会打印其最近的日志。请在 Discord 或 GitHub 上分享相关部分，切勿分享你的凭据。