Copaw Troubleshooting
CoPaw 故障排查与常见问题
本文介绍 CoPaw 常见问题的排查方法和解决方案。
故障排查步骤
基本步骤
- 确认问题：清晰描述问题现象，记录错误信息
- 收集信息：查看日志、检查配置、确认环境
- 分析原因：根据错误信息定位问题
- 尝试解决：应用解决方案，测试是否解决
- 验证恢复：确认问题已解决，检查副作用
诊断工具
# 运行系统诊断
copaw doctor
详细诊断
copaw doctor --verbose
检查特定项目
copaw doctor --check api,skills,channels
安装和启动问题
问题 1：安装失败
症状
：
pip install copaw
ERROR: Could not find a version
解决方案
：
- 检查 Python 版本（需要 Python 3.8+）
- 升级 pip：
pip install --upgrade pip - 使用镜像源：
pip install copaw -i https://pypi.tuna.tsinghua.edu.cn/simple
问题 2：启动失败
症状
：
copaw app start
ERROR: Failed to start CoPaw
解决方案
：
- 检查端口占用：
lsof -i :8088
- 检查配置文件：
copaw config get
- 查看详细日志：
copaw app start --debug
问题 3：启动后无法访问
症状
：CoPaw 启动成功，但无法访问控制台
解决方案
：
- 检查主机地址：
copaw config set server.host 0.0.0.0
- 检查防火墙：
sudo ufw allow 8088/tcp
- 检查网络连接：
ping <服务器地址>
配置问题
问题 4：API 密钥无效
症状
：
ERROR: Invalid API key
解决方案
：
- 检查 API 密钥：
copaw env get OPENAI_API_KEY
- 更新 API 密钥（通过控制台或 CLI）
- 验证 API 密钥：
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
问题 5：模型配置错误
症状
：
ERROR: Model not found
解决方案
：
- 检查模型配置：
copaw config get agent.model_provider
copaw config get agent.model_name
- 查看支持的模型（控制台 → 设置 → 模型）
- 更新模型配置：
copaw config set agent.model_provider dashscope
copaw config set agent.model_name qwen3.5-plus
问题 6：配置文件损坏
症状
：
ERROR: Failed to load configuration file
解决方案
：
- 检查配置文件：
cat ~/.copaw/config.json
python -m json.tool ~/.copaw/config.json
- 重置配置：
copaw config reset
频道问题
问题 7：钉钉频道无法连接
症状
：钉钉频道显示"连接失败"
解决方案
：
- 检查配置（控制台 → 频道 → 钉钉）
- 重新获取 Client ID 和 Client Secret
- 检查应用权限（机器人、群组）
- 查看日志：
copaw app logs --filter dingtalk
问题 8：Webhook 频道不工作
症状
：Webhook 消息发送失败
解决方案
：
- 检查 Webhook URL
- 测试 Webhook：
curl -X POST https://example.com/webhook \
-H "Content-Type: application/json" \
-d '{"test": "message"}'
- 检查目标服务器状态
Skills 问题
问题 9：Skill 加载失败
症状
：
ERROR: Failed to load skill: xxx
解决方案
：
- 检查 Skill 状态：
copaw skills list
- 检查依赖：
pip install -r requirements.txt
- 重新加载 Skill：
copaw skills disable <skill_name>
copaw skills enable <skill_name>
问题 10：PDF 处理失败
症状
：无法读取 PDF 文件
解决方案
：
- 检查 PDF 文件是否存在和有效
- 检查依赖：
python -c "import PyPDF2"
pip install PyPDF2 pypdfium2
- 查看日志：
copaw app logs --filter pdf
定时任务问题
问题 11：定时任务不执行
症状
：定时任务没有执行
解决方案
：
- 检查任务状态：
copaw cron list
- 恢复任务：
copaw cron resume <task_id>
- 检查 Cron 表达式（使用在线工具验证）
- 检查时区设置
性能问题
问题 12：响应速度慢
症状
：CoPaw 响应速度慢
解决方案
：
- 检查网络连接
- 选择更快的模型
- 优化配置：
copaw config set agent.max_iterations 5
copaw config set agent.max_input_length 4096
- 检查系统资源：
top
free -h
问题 13：内存占用过高
症状
：CoPaw 占用大量内存
解决方案
：
- 检查内存使用：
ps aux | grep copaw
top -p <pid>
- 清理缓存：
copaw app restart --clear-cache
- 限制并发：
export COPAW_MAX_CONCURRENT=5
日志和监控
查看日志
# 查看最新日志
copaw app logs
实时查看
copaw app logs --follow
过滤日志
copaw app logs --filter ERROR
最近 50 行
copaw app logs --lines 50
日志级别
| 级别 | 说明 | 使用场景 |
|------|------|----------|
| DEBUG | 调试信息 | 开发调试 |
| INFO | 常规信息 | 正常运行 |
| WARNING | 警告信息 | 潜在问题 |
| ERROR | 错误信息 | 需要关注 |
常见错误代码
HTTP 错误
| 状态码 | 说明 | 解决方案 |
|--------|------|----------|
| 400 | 请求错误 | 检查请求参数 |
| 401 | 未授权 | 检查 API 密钥 |
| 403 | 禁止访问 | 检查权限设置 |
| 404 | 未找到 | 检查 URL 路径 |
| 500 | 服务器错误 | 查看服务器日志 |
CoPaw 错误
| 错误代码 | 说明 | 解决方案 |
|----------|------|----------|
| ERR_API_KEY | API 密钥无效 | 更新 API 密钥 |
| ERR_MODEL | 模型错误 | 检查模型配置 |
| ERR_CHANNEL | 频道错误 | 检查频道配置 |
| ERR_SKILL | Skill 错误 | 检查 Skill 依赖 |
| ERR_CONFIG | 配置错误 | 检查配置文件 |
获取帮助
官方资源
提交问题
提交问题时请包含：
- 版本信息：
copaw --version
- 错误信息：完整的错误堆栈信息
- 配置信息：
copaw config get --json
- 日志：
copaw app logs --lines 100
- 环境信息：
uname -a
python --version
预防措施
1. 定期备份
# 备份配置
cp ~/.copaw/config.json ~/.copaw/config.json.backup
导出数据
copaw export all > copaw_backup.json
2. 监控和告警
#!/bin/bash
while true; do
if ! copaw app status; then
echo "CoPaw 已停止！" | mail -s "CoPaw 告警" admin@example.com
fi
sleep 60
done
3. 健康检查
# 定期运行诊断
copaw doctor --verbose
