# 故障排查 — 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/zh-hans/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/zh-hans/docs/wiki/unity/installation)、[Unreal](https://ai-game.dev/zh-hans/docs/wiki/unreal/installation) 或 [Godot](https://ai-game.dev/zh-hans/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/zh-hans/docs/wiki/app/installation#updates)）。

**某个包显示警告数量。** 打开 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`。参见[硬件表](https://ai-game.dev/zh-hans/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`。

**我需要日志来报告 bug。** `gamedev daemon status` 显示后台服务的状态，`gamedev daemon logs --lines 200` 会打印其最近的日志。请在 Discord 或 GitHub 上分享相关部分，切勿分享你的凭据。

## 仍然卡住

请查看[常见问题](https://ai-game.dev/zh-hans/docs/wiki/app/faq)、网站[常见问题](https://ai-game.dev/docs/faq)以及[发布说明](https://ai-game.dev/zh-hans/releases)，了解最近的修复。

---

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

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