故障排查

本文覆盖新用户最常遇到的配置障碍。如果你刚完成注册但还没完成 Key 配置，请先阅读快速开始和模型配置；本文假设你已完成注册并尝试过添加 Key。

模型与 Key 配置问题

为什么添加了 Key 还是看不到任何模型？

这是最常见的首次上手障碍，通常由以下原因之一引起：

1. Key 未通过连通性验证

添加 Key 后，平台会自动向供应商发起一次模型列表同步。如果网络不通或 Key 有误，这次同步会失败，该供应商将显示为「不可达」，其模型不会出现在选择器中。

排查步骤：

打开「设置 → 模型配置」，查看该供应商的状态。
点击详情面板中的「校验连接」查看详细错误信息。
常见失败原因：Key 填错（多了空格或漏了字符）、Base URL 填错（尤其是 Google AI Studio）、国内网络无法直连海外服务。

2. 供应商开关被关闭

列表右侧每家供应商有一个开关。若开关已关闭（灰色），该供应商的所有模型在全站模型选择器中均不可见，即使 Key 是有效的。点击开关重新启用即可。

3. 所有模型被手动隐藏

通过「管理显示模型」可以隐藏具体模型。如果把某供应商下的所有模型都隐藏了，选择器同样看不到任何模型。进入详情面板 → 「管理显示模型」，勾选要恢复的模型。

4. 供应商模型列表从未同步

新添加的供应商，若同步动作因网络原因失败，本地模型列表为空。手动在详情面板点「校验连接」触发一次重新同步。

credentials_required 是什么，怎么解决？

credentials_required 是后端返回的标准错误信号，表示当前操作所需的模型供应商没有配置可用的 API Key。

前端检测到这个信号后，会弹出「模型配置」拦截弹窗，让你：

选已有模型：切换到另一个已配好 Key 的供应商的模型；或者
补 Key：直接在弹窗内为当前供应商填入 API Key，保存后平台自动重试。

这个错误会在以下场景触发：

游戏内发送消息，但当前选中的模型所属供应商没有配 Key。
触发生图、提取等功能，但对应能力（图像生成、向量嵌入）所需供应商没有配 Key。

根本解决方法：去「设置 → 模型配置」为该供应商添加有效 Key，或切换到已配好 Key 的模型。

如何确认 Key 已生效？

Key 生效的可靠判断方式：

打开「设置 → 模型配置」，找到该供应商。
供应商行的连通性状态显示绿色（可达），说明 Key 有效且网络可达。
点击供应商展开详情面板，「模型」标签页下可以看到已同步的模型列表。
打开游戏内的模型选择器（游戏台顶部）或「设置 → 模块配置」，该供应商的模型出现在列表中。

如果步骤 2 显示黄色（降级）或红色（不可达），点「校验连接」可看到具体错误文案。

OpenAI 兼容端点的 Base URL 应该填什么？

不同场景有不同写法：

场景	Base URL 示例
OpenAI 官方直连	`https://api.openai.com/v1`（默认，无需修改）
Google AI Studio（Gemini）	`https://generativelanguage.googleapis.com/v1beta/openai`（必须含 `/v1beta/openai`）
中转站 / 自建代理	`https://your-relay.example.com/v1`
本地 vLLM / Ollama	`http://127.0.0.1:8000/v1`
DashScope（通义千问）OpenAI 兼容模式	`https://dashscope.aliyuncs.com/compatible-mode/v1`

最常见的填写错误：Google AI Studio 的 Base URL 写成了 https://generativelanguage.googleapis.com/v1beta，少了末尾的 /openai，导致所有请求返回 404。正确写法必须包含完整路径 /v1beta/openai。

Base URL 是 per-user 字段，修改只影响你自己，不会影响其他用户。

使用中转站时，在供应商下拉选「自定义」或选择对应供应商，将 Base URL 改为中转站地址，填入中转站提供的 Key 即可。

嵌入模型和对话模型有什么区别？为什么要单独配？

**对话模型（LLM）**负责 GM 叙事、意图解析、角色卡提取等文本生成任务。

**嵌入模型（Embedding）**负责向量化——把文本转成数字向量，用于记忆召回和剧本语义检索（RAG）。这是一个完全不同的接口，普通对话模型无法用于嵌入。

两类模型需要分别配置，原因：

提供嵌入接口的供应商是另一个子集。Anthropic 和 DeepSeek 均无嵌入接口，不会出现在嵌入模型选择器中，即使你已经配了这两家的 Key。
常见的嵌入模型供应商：Vertex AI（Google）、OpenAI、Cohere 等。

配置入口：「设置 → 模块配置」→「向量嵌入 (RAG)」行 → 选择嵌入模型。

普通用户如未配置嵌入 Key，RAG 召回会降级；admin 和 VIP 用户有平台兜底（Gemini 免费额度）。

嵌入模型一旦切换，已处理过的剧本需要重新嵌入，旧向量与新模型不互通。

游戏运行问题

游戏点了「开始」或「发送」后没有反应

可能原因及排查顺序：

没有可用模型 — 模型选择器为空或当前模型不可用。检查「设置 → 模型配置」，确认至少有一家供应商状态为绿色，且模型选择器中有可选模型。
凭据信号拦截 — 后端返回 credentials_required，前端弹出拦截弹窗。检查浏览器页面是否有弹窗（可能被遮住），按弹窗引导补 Key 或换模型。
网络问题 — 页面无响应可能是请求发出后超时。查看浏览器开发者工具 Network 面板，看是否有请求一直挂起。如果使用海外供应商，检查代理设置。
剧本未就绪 — 新建向导里剧本标注「未就绪」时，开始按钮不可点击。等待后台提取完成（「剧本管理」页面状态列变绿）后重试。

本地大模型很慢，或者请求超时后游戏中断

本地部署（桌面版 / 自托管）运行 CPU 推理时，首 token 响应常需数分钟，默认超时可能不够。

平台默认超时时间：

服务器部署：300 秒
本地 / 桌面部署：1800 秒

调整方法：「设置 → 模型参数」→「请求超时」，填入需要的秒数。本地部署上限为 7200 秒（2 小时），服务器部署上限为 900 秒。

如果多次超时但本地模型本身能工作，可以：

降低「最大输出 Tokens」（Max Tokens）减少单次生成量。
切换到更小的本地模型。
检查本地推理服务（vLLM / llama.cpp 等）是否仍在运行，是否已加载模型。

存档加载失败或进入游戏后一直显示加载中

刷新页面重试——网络抖动导致的瞬时失败通常刷新可解决。
检查浏览器控制台是否有报错，具体错误文案有助于定位问题。
确认当前所用模型可用：游戏台顶部的模型标签，点击确认选中的模型处于可用状态。
若长时间（>5 分钟）加载无进展，去「设置 → 模型配置」点「校验连接」确认供应商在线。

网络与连通性问题

国内直连海外供应商失败

OpenAI、Anthropic、Google AI Studio 等海外供应商在中国大陆通常无法直连。

解决方案（任选其一）：

HTTP 代理：在添加或编辑 Key 的弹窗中，「连接方式」选「HTTP 代理」，填写本地代理地址（如 http://127.0.0.1:7890）。代理地址必须是 http:// 协议。
OpenRouter：一个 Key 聚合数十家供应商，通过 OpenRouter 的端点访问，国内连通性通常更好。去 openrouter.ai 注册，供应商选「OpenRouter」填入 Key 即可。
DashScope（通义千问）/ DeepSeek / 混元：国产供应商，无需代理。

代理设置是 per-user 字段，只影响你自己的调用。