ChatAI Plugin

主题

故障排除 ​

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

安装问题 ​

better-sqlite3 构建失败 ​

现象：启动时报 Could not locate the bindings file

解决方案：

  1. 在 Yunzai 根目录重建：
bash
pnpm rebuild better-sqlite3
  1. 如果仍失败，检查编译工具：
bash
# 安装 Visual Studio Build Tools
npm install -g windows-build-tools
bash
sudo apt install build-essential python3
bash
xcode-select --install
  1. 完全重装：
bash
rm -rf node_modules
pnpm install
pnpm rebuild better-sqlite3

Node.js 版本不兼容 ​

现象：启动报错或功能异常

解决方案：

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

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

依赖安装失败 ​

现象：pnpm install 报错

解决方案：

bash
# 清理缓存
pnpm store prune

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

启动问题 ​

插件无法加载 ​

检查项：

  1. 确认插件目录名称正确：plugins/chatgpt-plugin
  2. 检查 index.js 是否存在
  3. 查看 Yunzai 控制台错误日志

Web 面板无法访问 ​

检查项：

  1. 端口占用
bash
# 检查端口占用
netstat -tlnp | grep 3000

# 使用其他端口
# 修改 config.yaml 中的 web.port
  1. 防火墙
bash
# 开放端口
sudo ufw allow 3000
  1. 监听地址
yaml
web:
  host: "0.0.0.0"  # 允许外部访问

数据库初始化失败 ​

解决方案：

bash
# 1. 重建 better-sqlite3
pnpm rebuild better-sqlite3

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

# 3. 删除数据库文件重建
rm plugins/chatgpt-plugin/data/chatai.db

使用问题 ​

AI 不回复 ​

检查项：

  1. 触发方式

    • 确认使用了正确的触发方式（@/前缀）
    • 检查群组的触发配置

  2. 渠道配置

    • 进入 Web 面板检查渠道是否启用
    • 点击「测试连接」验证 API 可用

  3. 控制台日志

    • 开启调试模式：#ai调试开启
    • 查看详细错误信息

  4. 其他插件冲突

    • 检查是否被其他插件拦截
    • 调整插件优先级

API 认证失败 (401/403) ​

解决方案：

  1. 检查 API Key 是否正确
  2. 确认 Key 未过期
  3. 验证账户余额充足
  4. 检查 Key 权限范围

API 限流 (429) ​

解决方案：

  1. 配置多渠道负载均衡
  2. 增加请求间隔
  3. 升级 API 套餐
  4. 使用备用渠道

消息重复 ​

检查项：

  1. 确认没有重复的适配器
  2. 检查消息回显配置
  3. 插件内置去重机制

工具调用失败 ​

检查项：

  1. 确认工具已启用
  2. 检查工具权限配置
  3. 查看工具调用日志：#工具日志
  4. 开启调试模式查看详情

性能问题 ​

响应缓慢 ​

优化建议：

  1. 减少上下文消息数量
  2. 使用更快的模型（如 gpt-4o-mini）
  3. 启用流式响应
  4. 配置代理优化网络

内存占用高 ​

优化建议：

  1. 减少 context.maxMessages
  2. 定期清理对话历史
  3. 限制记忆条数
  4. 关闭不需要的功能

代理问题 ​

代理连接失败 ​

检查项：

  1. 代理服务是否运行
  2. 端口配置是否正确
  3. 代理类型是否匹配

测试代理：

bash
curl -x http://127.0.0.1:7890 https://api.openai.com/v1/models

部分请求不走代理 ​

解决方案：

yaml
proxy:
  enabled: true
  type: http
  host: 127.0.0.1
  port: 7890
  noProxy: []  # 确保没有误排除

MCP 问题 ​

MCP 服务器连接失败 ​

检查项：

  1. npm 包是否已安装
  2. 命令路径是否正确
  3. 环境变量是否设置

查看状态：

bash
#mcp状态

工具不可用 ​

检查项：

  1. 服务器是否已连接
  2. 工具是否在 tools/list 中
  3. 权限配置是否正确

日志收集 ​

开启调试 ​

bash
#ai调试开启

查看日志 ​

bash
# Yunzai 日志
tail -f logs/latest.log

# 工具日志
#工具日志

提交问题 ​

提交 Issue 时请附带：

  1. 错误信息截图
  2. 相关配置（隐藏 API Key）
  3. 复现步骤
  4. 运行环境信息

常见错误码 ​

错误码说明解决方案
401认证失败检查 API Key
403权限不足检查 Key 权限
429请求过多降低频率或切换渠道
500服务器错误稍后重试
502/503服务不可用等待服务恢复

获取帮助 ​

基于 MIT 许可发布

Copyright © 2024 ChatAI Plugin Team