常见问题
本页收集了 Elftia 使用过程中最常见的问题及其解决方案。每个问题包含症状描述、可能原因和具体的解决步骤。
启动与界面问题
应用启动后白屏
症状： 打开 Elftia 后，窗口显示空白或白屏，没有任何界面内容。
可能原因：
- GPU 加速与显卡驱动不兼容
- 前端渲染进程崩溃
- 安装文件损坏
解决步骤：
- 关闭 Elftia，使用命令行启动并添加
--disable-gpu参数，测试是否为 GPU 问题。 - 更新显卡驱动到最新版本。
- 检查系统是否有其他 Elftia 进程残留，使用任务管理器结束所有相关进程后重试。
- 如果问题持续，尝试重新安装 Elftia。
应用启动即闪退
症状： 双击启动后窗口闪现然后立即关闭。
可能原因：
- 缺少系统运行时依赖（如 Visual C++ Redistributable）
- 用户数据目录权限问题
- 旧版本的残留数据导致冲突
解决步骤：
- Windows：安装最新版本的 Visual C++ Redistributable。
- 检查用户数据目录是否有写入权限。
- 尝试删除用户数据目录中的缓存文件后重启（不会丢失对话数据）。
- 以管理员权限运行 Elftia。
界面文字乱码
症状： 界面上的文字显示为方块或乱码。
可能原因：
- 自定义字体设置了系统未安装的字体
- 字体文件损坏
解决步骤：
- 打开 设置 → 外观，清空 UI 字体和代码字体的自定义输入框。
- 如果无法进入设置页面，手动删除用户数据目录中的主题配置文件。
LLM 提供商问题
提供商测试连接失败 — 401
症状： 测试连接时显示 401 Unauthorized 或 Invalid API Key。
可能原因：
- API Key 输入错误（多余空格、缺少前缀等）
- API Key 已过期或被撤销
- 使用了错误提供商的 API Key
解决步骤：
- 重新复制 API Key，确保没有多余的空格或换行。
- 前往提供商的控制台确认 Key 仍然有效。
- 确认 API Key 对应的提供商选择正确。
提供商测试连接失败 — 403
症状： 测试连接时显示 403 Forbidden。
可能原因：
- 账号余额不足或未绑定支付方式
- API Key 的权限不够（如只读 Key）
- IP 地址被提供商封禁
解决步骤：
- 检查提供商账户的余额和支付状态。
- 确认 API Key 具有模型调用权限。
- 如果使用代理，尝试更换代理节点。
提供商测试连接超时
症状： 测试连接时长时间无响应，最终超时。
可能原因：
- 网络连接问题
- 代理配置错误
- 防火墙阻止了出站请求
解决步骤：
- 检查网络连接是否正常。
- 如果使用代理，确认代理正在运行且配置正确（参见 使用代理）。
- 确认防火墙允许 Elftia 访问互联网。
- 尝试在浏览器中直接访问提供商的 API 域名（如
api.openai.com），确认域名可以解析。
流式回复中断
症状： AI 回复到一半突然停止，消息不完整。
可能原因：
- 网络连接不稳定导致 SSE 流中断
- 响应达到模型的最大 Token 限制
- 代理的连接超时设置过短
解决步骤：
- 尝试重新生成回复。
- 如果反复出现，检查网络连接稳定性。
- 确认代理（如有）的超时设置不低于 120 秒。
- 在模型参数中减少
max_tokens的值，或拆分长回复请求。
Agent 相关问题
Agent 工具无法执行
症状： Agent 尝试使用工具（如 Bash、Write 等）但显示权限被拒绝。
可能原因：
- GuardianAgent 设置为严格模式阻止了操作
- 权限模式设置为「仅规划」
- 操作被执行防火墙的确定性规则拦截
解决步骤：
- 检查 设置 → Clawia → GuardianAgent 模式，按需降低安全级别。
- 检查权限模式是否设置为「仅规划」。
- 查看 审计日志，确认是哪个安全层阻止了操作。
Agent 工具执行失败 — command not found
症状： Agent 执行 Shell 命令时提示 command not found。
可能原因：
- 系统中未安装所需的命令行工具
- 环境变量 PATH 中未包含工具路径
解决步骤：
- 打开 设置 → 通用 → 环境，检查工具的安装状态。
- 安装缺失的工具（Node.js、Git 等）。
- 如果工具已安装但仍找不到，可能需要重启 Elftia 以刷新环境变量。
MCP 相关问题
MCP 服务器无法连接 — stdio 模式
症状： 添加的 MCP 服务器显示连接失败，使用 stdio（子进程）模式。
可能原因：
- 命令不存在或路径错误
- 依赖未安装（如 Node.js 包未安装）
- 环境变量缺失
解决步骤：
- 确认 MCP 服务器的命令可以在终端中直接运行（如
npx -y @modelcontextprotocol/server-filesystem /path）。 - 检查是否安装了 Node.js（
node --version）或 Python（python --version）。 - 如果 MCP 服务器需要额外的环境变量（如 API Key），确认在 MCP 配置的
env中正确设置。 - 重启 Elftia 后重试。
MCP 服务器无法连接 — SSE/HTTP 模式
症状： 远程 MCP 服务器连接超时或被拒绝。
可能原因：
- MCP 服务器未运行
- URL 或端口错误
- 网络/防火墙阻止了连接
解决步骤：
- 确认 MCP 服务器正在运行且可以访问。
- 检查 URL 格式是否正确（包含
http://或https://前缀）。 - 如果使用代理，确认代理规则允许访问 MCP 服务器地址。
Channel 相关问题
Channel 机器人无响应
症状： 通过 Discord/Telegram 等平台发送消息，机器人不回复。
可能原因：
- 触发规则未匹配（如需要 @mention 但未 @）
- PromptGuardian 阻止了消息
- Channel 未启动或 Token 配置错误
- 速率限制触发
解决步骤：
- 确认消息满足 Channel 的触发规则（@mention、关键词、前缀等）。
- 检查 PromptGuardian 模式，临时设为「关闭」测试是否为注入检测误报。
- 确认 Channel 的 Bot Token 正确且 Bot 已上线。
- 查看审计日志是否有被阻止的消息记录。
媒体生成问题
图片/视频/音乐生成失败
症状： 请求生成媒体内容时报错。
可能原因：
- 对应的媒体生成提供商未配置或余额不足
- 请求内容被提供商的安全过滤拒绝
- 网络连接问题
解决步骤：
- 确认用于媒体生成的提供商已正确配置且余额充足。
- 尝试简化或修改生成提示词，避免敏感内容。
- 检查网络连接和代理配置。
界面显示问题
壁纸设置后文字不可读
症状： 设置壁纸后，部分界面文字因透明度过高而难以辨认。
解决步骤：
- 增大 遮罩透明度 值（推荐 70-85）。
- 增大 模糊强度 值（推荐 8-15）。
- 如果特定区域仍不可读，使用自定义 CSS 调整。
深色模式下界面元素不可见
症状： 深色模式下部分边框、分隔线或文字颜色过浅，难以辨认。
解决步骤：
- 尝试切换到另一个强调色，部分颜色在深色模式下对比度更好。
- 检查是否有自定义 CSS 影响了颜色显示，尝试清空自定义 CSS。
- 调高显示器亮度。
性能问题
高内存占用
症状： Elftia 占用的内存持续增长。
可能原因：
- 打开了过多的对话标签页
- 单个对话包含大量消息（数百条以上）
- 附件（尤其是图片）过多
解决步骤：
- 关闭不需要的对话标签页。
- 对于过长的对话，考虑新建对话继续。
- 打开 设置 → 系统，执行 Clear Caches 清理缓存。
- 重启 Elftia 释放内存。
数据库相关错误
症状： 出现数据库操作错误或数据不一致。
解决步骤：
- 打开 设置 → 系统，执行 VACUUM 数据库优化。
- 如果问题持续，导出诊断信息（Export Diagnostics）用于进一步排查。
- 在极端情况下，用户数据目录中的数据库文件（
.db）可以被安全地备份和替换。
更新相关问题
更新后出现异常
症状： 更新到新版本后，应用行为异常。
解决步骤：
- 打开 设置 → 系统，依次执行 Clear Caches 和 VACUUM。
- 重启 Elftia。
- 如果问题持续，参考 更新 Elftia 中的回滚步骤。