第一步，基础问题排查（快速自查）

openclaw openclaw解答 2026-04-09 2

环境检查
- 网络连接：确保你的网络稳定，能正常访问所需的API服务（如OpenAI、国内大模型平台）或下载模型。
- API密钥/令牌：如果使用云端API，请检查密钥是否有效、未过期、有足够余额且未设置过于严格的频率限制。
- 配置文件：检查配置文件（通常是 config.yaml、.env 或 config.json）中的路径、参数、模型名称是否正确。
依赖与安装
- 版本匹配：使用 pip list 或 conda list 检查关键库（如 torch, transformers, openai 等）的版本是否符合项目要求,版本冲突是常见问题。
- 重新安装：尝试在干净的虚拟环境中，按照项目 README.md 或 requirements.txt 重新安装依赖。
```
# 示例
conda create -n openclaw_env python=3.10
conda activate openclaw_env
pip install -r requirements.txt
```
资源状态
- GPU/显存：如果项目需要GPU，使用 nvidia-smi 检查GPU是否可用、驱动是否正确安装、CUDA版本是否匹配。
- 内存与磁盘：检查内存和磁盘空间是否充足。

第二步：诊断错误信息（最关键的一步）

异常信息是解决问题的钥匙，请提供完整的错误日志（Traceback）。

控制台/终端输出：复制运行命令后出现的全部红色或错误信息。
日志文件：查看项目目录下的 logs/ 文件夹或应用内的日志记录。
常见错误类型及处理方向：
- ModuleNotFoundError 或 ImportError：缺少Python包或版本不对。
- CUDA out of memory：显存不足，尝试减小 batch_size，使用更小的模型，或在CPU上运行（如果支持）。
- ConnectionError/Timeout：网络问题,或API服务不可用。
- KeyError/FileNotFoundError：配置文件错误或缺失关键文件（如模型权重文件）。
- AttributeError：代码版本与库版本不兼容。

明确是哪个具体功能异常：

对话/问答异常：
- 检查调用的大模型名称是否正确。
- 检查提示词模板是否被意外修改。
- 尝试向模型发送一个最简单的测试问题,排除复杂逻辑干扰。
文件处理/知识库异常：
- 检查待处理的文件路径是否存在，格式是否支持（如 .txt, .pdf, .docx）。
- 如果是向量数据库检索失败，检查知识库是否成功构建（如索引文件是否存在）。
- 尝试重新初始化或重建知识库。
Web/图形界面异常：
- 检查端口是否被占用（如默认的 7860, 8501 端口）。
- 清除浏览器缓存或尝试无痕模式。
- 查看后端服务的启动日志。

如果以上步骤无法解决：

查阅项目文档：再次仔细阅读项目的 README.md、docs/ 目录和 issues 页面。
搜索与提问：
- 项目地址：在项目的 GitHub/Gitee Issues 页面,用关键词搜索是否已有类似问题及解决方案。
- 提问格式：
  - ：如“执行 python app.py 时出现 CUDA out of memory 错误”。
  - 详细描述：你的操作系统、Python版本、关键库版本、复现步骤、完整的错误日志。
  - 已尝试方法：列出你已做过的排查,这能大大提高获得帮助的效率。
回退版本：如果是在更新代码或库之后出现的问题,尝试回退到上一个能正常工作的版本。