故障排除 FAQ

本文档帮助你解决使用 ChatAI Plugin 时遇到的常见问题。

快速定位问题

使用 Ctrl+F 搜索错误关键词，或按目录分类查找。

安装问题

better-sqlite3 构建失败

错误信息

Could not locate the bindings file 或 node-gyp rebuild failed

解决步骤：

Step 1 - 运行 pnpm 周期脚本（推荐）

在 Yunzai 根目录 执行：

bash

pnpm approve-builds

运行周期脚本后，需要删除依赖和锁文件重新安装：

bash

rm -rf node_modules pnpm-lock.yaml
pnpm install

Step 2 - 如果仍失败，安装编译工具

WindowsLinux (Debian/Ubuntu)Linux (CentOS/RHEL)macOS

bash

# 安装 Visual Studio Build Tools
# 下载: https://visualstudio.microsoft.com/visual-cpp-build-tools/
# 安装时选择 "使用 C++ 的桌面开发"
# 安装 Visual Studio Build Tools
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
# 勾选 "使用 C++ 的桌面开发"

bash

sudo apt update
sudo apt install build-essential python3

bash

sudo yum groupinstall "Development Tools"
sudo yum install python3

bash

xcode-select --install

Step 3 - 进入依赖目录手动构建

bash

# 找到 better-sqlite3 目录（路径可能因包管理器不同而异）
cd node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3
# 或
cd node_modules/better-sqlite3

# 运行构建脚本
npm run build-release
# 或使用 node-gyp 直接构建
npx node-gyp rebuild

其他可能的解决方案

bash

# 设置 Python 路径
npm config set python /usr/bin/python3

# 全局安装 node-gyp
npm install -g node-gyp

# 清理缓存后重试
pnpm store prune

Node.js 版本不兼容

错误信息

启动报错 SyntaxError 或功能异常

解决方案：

bash

# 检查版本（需要 18.0+）
node -v

# 使用 nvm 切换版本
nvm install 18
nvm use 18

# 或使用 fnm
fnm install 18
fnm use 18

依赖安装失败

错误信息

pnpm install 报错，如 ENOENT、EPERM 等

解决方案：

bash

# 清理缓存
pnpm store prune

# 删除 lockfile 重装
rm pnpm-lock.yaml
pnpm install

Windows 用户注意

如果遇到权限问题，尝试以管理员身份运行命令行

启动问题

插件无法加载

错误信息

控制台无 [ChatAI] 相关日志，或报 Cannot find module 错误

检查清单：

检查项	说明	修复方法
入口文件	`index.js` 必须存在	重新克隆插件
依赖安装	依赖必须完整	运行 `pnpm install`
控制台日志	查看详细错误信息	根据错误修复

Web 面板无法访问

错误信息

浏览器无法打开管理面板链接，显示连接超时或拒绝

排查步骤：

1. 检查端口占用

Linux/macOSWindows

bash

netstat -tlnp | grep 3000
lsof -i :3000

powershell

netstat -ano | findstr :3000

2. 检查防火墙

Linux (ufw)Linux (firewalld)Windows

bash

sudo ufw allow 3000

bash

sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload

powershell

# 在 Windows 防火墙中添加入站规则

3. 修改监听地址

yaml

# config.yaml
web:
  host: "0.0.0.0"  # 允许外部访问（默认 127.0.0.1 仅本地）
  port: 3000       # 端口被占用时修改为其他端口

数据库初始化失败

错误信息

SQLITE_CANTOPEN 或 database is locked

解决步骤：

bash

# 1. 运行周期脚本并重新安装依赖
pnpm approve-builds
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 2. 检查目录权限（Linux/macOS）
chmod 755 plugins/chatgpt-plugin/data

# 3. 删除数据库文件重建（会丢失数据！）
rm plugins/chatgpt-plugin/data/*.db

数据备份

删除数据库前请先备份 data/ 目录，避免数据丢失

使用问题

AI 不回复

现象

发送消息后机器人无任何反应

排查流程图：

检查清单：

检查项	操作	说明
触发方式	确认使用正确的触发方式	@触发、前缀触发（如 `#chat`）
渠道配置	Web 面板检查渠道状态	点击「测试连接」验证
调试模式	发送 `#ai调试开启`	查看详细错误信息
插件冲突	检查其他插件是否拦截	调整插件优先级

API 认证失败 (401/403)

错误码

401 Unauthorized 或 403 Forbidden

可能原因	解决方案
API Key 错误	检查 Key 是否复制完整，无多余空格
Key 已过期	登录供应商后台查看 Key 状态
余额不足	充值账户余额
权限不足	检查 Key 的 API 访问权限范围
IP 限制	某些供应商限制 IP，检查是否需要配置代理

API 限流 (429)

错误码

429 Too Many Requests 或 Rate limit exceeded

解决方案：

方案	说明	推荐度
多渠道负载均衡	配置多个渠道分散请求	⭐⭐⭐
增加请求间隔	在配置中设置 `requestInterval`	⭐⭐
升级 API 套餐	提高 API 配额限制	⭐⭐⭐
使用备用渠道	配置故障转移渠道	⭐⭐⭐

消息重复

现象

同一条消息收到多次回复

检查项	说明
重复适配器	确认没有同时启用多个 Bot 适配器
消息回显	检查 `config.yaml` 中的回显配置
插件去重	插件内置去重机制，正常情况下会自动处理

工具调用失败

现象

AI 尝试调用工具但返回错误或无响应

排查步骤：

确认工具已启用
- Web 面板 → 工具管理 → 检查工具状态
检查权限配置
- 某些工具需要主人权限或群管权限
查看工具日志
txt
```
#工具日志
```
1
开启调试模式
txt
```
#ai调试开启
```
1

常见工具错误

错误	原因	解决
`Tool not found`	工具未启用或不存在	在 Web 面板启用工具
`Permission denied`	权限不足	检查用户权限配置
`Timeout`	工具执行超时	检查网络或工具逻辑

`function_response.name` 400 错误

错误信息

Gemini 渠道工具调用返回 400，错误体包含 function_response.name: Name cannot be empty 或类似描述

原因：

上游返回的工具结果 part 缺失 name 字段时，旧实现直接取 tcr.name 传出空名（甚至静默丢弃该结果 part），导致 OpenAI 兼容端点校验失败。

解决：

插件已内置 resolveToolResultName 多元兜底，空名场景会自动回退到合理名称，且不再丢弃无 name 的结果 part；升级到最新版本即可。同类逻辑同样覆盖 OpenAI 适配器的 tool_call_id 透传（见下节）。
若升级后仍出现，检查中转渠道返回的 functionResponse 结构是否异常，并将完整报错提交 GitHub Issue。

tool_call_id 400/500 错误

错误信息

OpenAI 兼容端点返回 400/500，错误中提示 tool_calls.id 必须是字符串、tool_call_id 类型非法，或消息中存在重复/数字型 ID

原因：

旧数据或部分上游中转站把数组下标当工具调用 ID 下发（数字型 id），插件检查前原样透传，请求在 OpenAI 兼容端点校验阶段被拒。Gemini 侧无原生 id 的场景同样缺少稳定 ID。

解决：

已在适配器层统一归一化：normalizeAnyToolCallId 将数字 ID 字符串化、空值兜底 crypto.randomUUID()；Gemini functionCall（含流式）改用 generateDeterministicToolCallId（工具名+参数哈希）生成恒定 ID。AbstractClient 的 6 处工具结果兜底与 ToolApprovalService 共用同一口径。
升级到最新版本后，旧历史消息中的数字 ID 会由 validateAndCleanMessages 清洗转正；若仍有报错，请保持日志完整并提交 Issue。

记忆中混入思考过程文本

现象

#ai查看记忆 或 Web 面板中，记忆条目出现「我们只需要输出……」「注意要求……」等模型思考语句

原因：

记忆总结是历史版本中唯一未强制结构化输出的环节，模型输出的推理行被整行当作记忆落库。

解决：

升级到最新版本（总结提示词已改为 [分类] 内容 结构化行硬约束，解析端带锚定正则 + 推理词过滤）。
对已污染数据：先在 Web 面板「整理记忆」重新总结，或使用 POST /api/memories/user/:userId/cleanup 清理低质量条目。
轮询总结路径（memory.enabled 开启时的历史路线）已同步加入思考行过滤。

性能问题

响应缓慢

现象

AI 回复延迟高，等待时间长

优化方案	说明	效果
减少上下文	降低 `context.maxMessages` 值	⭐⭐⭐
使用轻量模型	如 `gpt-4o-mini`、`deepseek-chat`	⭐⭐⭐
启用流式响应	配置 `stream: true`	⭐⭐
优化网络	配置代理或使用国内渠道	⭐⭐⭐

内存占用高

现象

Node.js 进程内存持续增长

优化方案	配置
减少上下文消息数	`context.maxMessages: 10`
定期清理历史	使用 `#结束对话` 命令
限制记忆条数	`memory.maxMemories: 500`
关闭不需要的功能	禁用未使用的工具类别

代理问题

代理连接失败

现象

API 请求超时或连接被拒绝

检查清单：

检查项	命令/操作
代理服务运行	检查代理软件是否启动
端口正确	确认端口号（常见：7890、1080）
代理类型	http/socks5 需要匹配

测试代理连通性：

bash

# 测试 HTTP 代理
curl -x http://127.0.0.1:7890 https://api.openai.com/v1/models

# 测试 SOCKS5 代理
curl -x socks5://127.0.0.1:1080 https://api.openai.com/v1/models

部分请求不走代理

yaml

# config.yaml
proxy:
  enabled: true
  type: http        # http 或 socks5
  host: 127.0.0.1
  port: 7890
  noProxy: []       # 确保没有误排除目标域名

MCP 问题

MCP 服务器连接失败

现象

MCP 工具不可用，状态显示离线

排查步骤：

查看 MCP 状态
txt
```
#mcp状态
```
1

检查 npm 包安装

bash

# 确认 MCP 服务器包已安装
npm list -g @anthropic/mcp-server-xxx

检查配置文件

json

// data/mcp-servers.json
{
  "servers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@xxx/mcp-server"]
    }
  }
}

工具不可用

检查项	说明
服务器连接	确认 MCP 服务器状态为在线
工具列表	检查工具是否在 `tools/list` 返回中
权限配置	检查预设的工具白名单/黑名单

日志收集

开启调试模式

txt

#ai调试开启

调试模式功能

显示详细的 API 请求/响应日志
显示工具调用详情
显示错误堆栈信息

查看日志

Yunzai 日志工具日志MCP 状态

bash

# 实时查看日志
tail -f logs/latest.log

# 搜索错误日志
grep -i "error\|fail" logs/latest.log

txt

#工具日志

txt

#mcp状态

提交问题

提交 Issue 时请附带

错误信息截图 - 完整的错误堆栈
相关配置 - 隐藏 API Key 后的配置
复现步骤 - 详细的操作步骤
运行环境 - Node.js 版本、操作系统、Yunzai 版本

常见错误码

错误码	说明	解决方案
`401`	认证失败	检查 API Key 是否正确
`403`	权限不足	检查 Key 权限范围
`429`	请求过多	降低频率或切换渠道
`500`	服务器错误	稍后重试
`502`	网关错误	检查代理或稍后重试
`503`	服务不可用	等待服务恢复
`ECONNREFUSED`	连接被拒绝	检查网络和代理配置
`ETIMEDOUT`	连接超时	检查网络或增加超时时间

前端构建问题

lint 规则误报阻塞构建

错误信息

bun run build（或 next build）被 ESLint 拦下，报 react-hooks/set-state-in-effect、react-hooks/immutability、react-hooks/refs 等规则错误

原因：

eslint-config-next 16.0.8 携带 eslint-plugin-react-hooks 7.x 新规则，存量代码中大量「effect 内同步调用初始化函数」的写法会被判定为 setState-in-effect 而报错，构建期 lint 直接失败。

排查与解决：

先确认规则来源：bun run lint 复现全部报错，确认报错文件与规则名。
修复方向（保持行为等价，不通过 eslint-disable 或降版本绕过）：
1. 删除初始值冗余置位：effect 里 setLoading(false) 之类与初始值相同的调用直接删除；
2. 缓冲变量 + finally 收拢：异步初始化中将 state 写入收敛到 try/finally 或函数末尾，避免中途多次置位；
3. 同步初始化迁移 setTimeout：纯同步初始化用 setTimeout(..., 0) 回调包裹；
4. IIFE 包裹：void (async () => { ... })() 形式。
验证命令：bun run lint（0 错误）→ bun run typecheck → bun run build / bun run export。
注意：7.x 编译器不将 Promise.resolve() 微任务边界视为可豁免形态，仅 finally 收拢、setTimeout 回调、void async IIFE 三种形态稳定免报。

标准化排查流程

预防性维护

定期维护建议

维护项	频率	说明
备份数据	每周	备份 `data/` 目录（config.yaml、数据库、预设）
检查日志	每日	关注错误和警告信息
清理缓存	每月	清理过期会话和缓存数据
更新插件	按需	关注版本更新，及时升级

监控指标

建议监控以下指标

实时 RPM：1/5 分钟请求数
API 成功率：调用成功比例
Token 用量：令牌消耗趋势
工具调用错误率：工具执行异常比例
数据库大小：存储增长趋势

更新后维护

bash

# 更新插件后执行
cd plugins/chatgpt-plugin
git pull
pnpm install
pnpm approve-builds  # 如涉及原生模块
rm -rf node_modules pnpm-lock.yaml
pnpm install

获取帮助

🆘 获取支持

渠道	链接	适用场景
GitHub Issues	提交 Issue	Bug 反馈、功能建议
项目文档	查看文档	配置和使用问题

故障排除 FAQ ​

安装问题 ​

better-sqlite3 构建失败 ​

Node.js 版本不兼容 ​

依赖安装失败 ​

启动问题 ​

插件无法加载 ​

Web 面板无法访问 ​

数据库初始化失败 ​

使用问题 ​

AI 不回复 ​

API 认证失败 (401/403) ​

API 限流 (429) ​

消息重复 ​

工具调用失败 ​

function_response.name 400 错误 ​

tool_call_id 400/500 错误 ​

记忆中混入思考过程文本 ​

性能问题 ​

响应缓慢 ​

内存占用高 ​

代理问题 ​

代理连接失败 ​

部分请求不走代理 ​

MCP 问题 ​

MCP 服务器连接失败 ​

工具不可用 ​

日志收集 ​

开启调试模式 ​

查看日志 ​

提交问题 ​

常见错误码 ​

前端构建问题 ​

lint 规则误报阻塞构建 ​

标准化排查流程 ​

预防性维护 ​

定期维护建议 ​

监控指标 ​

更新后维护 ​

获取帮助 ​

故障排除 FAQ

安装问题

better-sqlite3 构建失败

Node.js 版本不兼容

依赖安装失败

启动问题

插件无法加载

Web 面板无法访问

数据库初始化失败

使用问题

AI 不回复

API 认证失败 (401/403)

API 限流 (429)

消息重复

工具调用失败

`function_response.name` 400 错误

tool_call_id 400/500 错误

记忆中混入思考过程文本

性能问题

响应缓慢

内存占用高

代理问题

代理连接失败

部分请求不走代理

MCP 问题

MCP 服务器连接失败

工具不可用

日志收集

开启调试模式

查看日志

提交问题

常见错误码

前端构建问题

lint 规则误报阻塞构建

标准化排查流程

预防性维护

定期维护建议

监控指标

更新后维护

获取帮助