故障排查
常见问题的排查方法和解决方案。
诊断工具
在排查问题前，先试试 OpenVort 自带的诊断功能：
CLI 诊断
openvort doctor
自动检查 LLM 连通性、数据库状态、IM 通道状态、插件健康、安全策略等。
Web 面板日志
在管理面板 → 运行日志 页面可以实时查看服务日志，支持按级别过滤。
对话中诊断
对管理员用户，可以直接让 AI 诊断：
用户: 系统状态怎么样？
AI: （调用 system_diagnose）LLM 正常、数据库正常、企微在线...
服务启动问题
启动报错 "database connection refused"
原因：PostgreSQL 未启动或连接字符串不正确。
排查：
- 检查 PostgreSQL 是否运行：
pg_isready - 检查
.env中的OPENVORT_DATABASE_URL格式：OPENVORT_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/openvort - 确认数据库存在：
psql -l | grep openvort
启动报错 "pgvector extension not found"
原因：知识库功能需要 PostgreSQL 的 pgvector 扩展。
解决：
-- 在 openvort 数据库中执行
CREATE EXTENSION IF NOT EXISTS vector;
如果未安装 pgvector，参考 pgvector 安装指南。
启动报错 "LLM API key not configured"
原因：未配置 LLM API Key。
解决：在 .env 中添加：
OPENVORT_LLM_PROVIDER=anthropic
OPENVORT_LLM_API_KEY=sk-ant-xxxxx
IM 通道问题
企微机器人不回复消息
排查步骤：
- 检查通道状态：
openvort channels list - 确认环境变量配置完整（CORP_ID / APP_SECRET / AGENT_ID / CALLBACK_TOKEN / CALLBACK_AES_KEY）
- 确认机器人的回调地址配置正确（智能机器人模式不需要）
- 查看日志中是否有
wecom相关错误
钉钉 Stream 连接失败
排查步骤：
- 确认
OPENVORT_DINGTALK_APP_KEY和OPENVORT_DINGTALK_APP_SECRET正确 - 确认钉钉开放平台中机器人已开启 Stream 模式
- 检查网络是否能访问
https://api.dingtalk.com
飞书收不到消息
排查步骤：
- 确认
OPENVORT_FEISHU_APP_ID和OPENVORT_FEISHU_APP_SECRET正确 - 确认飞书开放平台中应用已发布
- 确认事件订阅已配置（接收消息事件）
Docker / 工作电脑问题
工作电脑创建失败
排查步骤：
- 检查 Docker 是否运行：
docker info - 检查基础镜像是否存在：
docker images | grep openvort/worker - 如果镜像不存在，手动拉取或构建
- 检查磁盘空间：
df -h
node_shell 执行超时
可能原因：
- 命令执行时间超过默认 timeout（120 秒）
- 容器资源不足（CPU/内存被限制）
解决：
- 对长时间任务，AI 员工会自动使用后台执行 + 轮询模式
- 检查容器资源：
docker stats <container_id>
工作电脑显示离线
排查步骤：
- 检查容器状态：
docker ps -a | grep <container_name> - 如果容器已停止，尝试重启：
docker start <container_id> - OpenVort 也会在工具调用时自动尝试重启已停止的容器
- 检查宿主机磁盘空间和内存
AI 回复质量问题
AI 回复不相关或质量差
排查：
- 检查模型配置：确认使用的是 Claude Sonnet 等高质量模型
- 检查 Skill 配置：AI 员工是否绑定了正确的岗位和 Skill
- 尝试开启 Extended Thinking（在会话设置中调整思考级别）
- 检查上下文长度：对话太长可能导致信息丢失，尝试开新会话
AI 不调用工具
可能原因：
- 插件未启用
- 对话中未明确指出要操作什么系统
- 工具描述与用户意图不匹配
排查：
- 确认相关插件已启用：管理面板 → 插件管理
- 更明确地描述需求（如"在 VortFlow 中创建一个需求"而非"帮我记一下"）
- 查看
openvort tools list确认工具已注册
性能问题
AI 回复很慢
排查：
- 检查 LLM API 延迟：
openvort doctor会测试 API 响应时间 - 上下文过长：长时间对话积累大量历史，尝试新会话
- 网络问题：确认服务器到 LLM API 的网络通畅
- 考虑使用 Claude（支持 Prompt Caching，多轮对话更快）
Web 面板加载慢
排查：
- 检查前端是否正确构建：
cd web && pnpm build - 配置 Nginx 反向代理并开启 gzip
- 检查数据库查询性能