Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
107 lines (79 loc) · 2.62 KB

TROUBLESHOOTING.md

File metadata and controls

107 lines (79 loc) · 2.62 KB
Raw

🔧 常见问题排查

跑教程时遇到报错？来这里找答案。按 Ctrl+F 搜报错关键词。

API Key 相关

❌ openai.AuthenticationError: Incorrect API key provided

原因：API Key 写错了，或者环境变量没有正确设置。
解决：
  1. 确认你已经申请了 API Key（DeepSeek / OpenAI / 通义千问等）
  2. 检查环境变量：
     Linux/Mac: echo $OPENAI_API_KEY
     Windows:   echo %OPENAI_API_KEY%
  3. 重新设置：
     Linux/Mac: export OPENAI_API_KEY="sk-你的key"
     Windows:   $env:OPENAI_API_KEY="sk-你的key"

❌ openai.APIConnectionError: Connection error

原因：网络连不上 API 服务器。
解决：
  1. 如果用的是 OpenAI 官方 → 国内可能被墙，换 DeepSeek：
     export OPENAI_BASE_URL="https://api.deepseek.com/v1"
  2. 检查 base_url 是否正确
  3. 检查是否需要代理：export HTTP_PROXY="http://127.0.0.1:7890"

❌ openai.RateLimitError

原因：API 调用太频繁，或账户余额不足。
解决：等几秒再试 / 检查账户余额 / 免费额度可能用完了。

依赖安装

❌ pip install 报错 / ModuleNotFoundError

原因：缺少 Python 包。
解决：
  1. cd agent-builder-pro
  2. pip install -r requirements.txt
  3. 单独装：pip install openai sentence-transformers gradio

❌ sentence-transformers 下载模型卡住

原因：从 HuggingFace 下载，国内可能慢。
解决：
  export HF_ENDPOINT="https://hf-mirror.com"
  或等一会儿（首次约 80MB），代码在下载失败时会降级为关键词匹配。

❌ Gradio 启动后打不开 localhost:7860

原因：端口被占用，或防火墙阻止。
解决：
  1. 换个端口：ui.launch(server_port=8080)
  2. 检查是否有其他程序占用了 7860 端口
  3. Windows 防火墙可能会弹窗——点"允许"

代码运行

❌ Step P1 Shell 执行器：命令不在白名单

原因：白名单只允许安全命令。
解决：在 ALLOWED_CMDS 列表里加你想用的命令。生产环境请谨慎。

❌ Step P5 数据库文件找不到

信息：agent_memory.db 或 pro_memory.db 不存在。
解决：第一次运行时会自动创建，不需要手动建。

❌ Step P2 流式输出不"流"

原因：某些终端缓冲输出，看起来还是一下子出来。
解决：
  1. 换 Windows Terminal（不要用 CMD）
  2. 确保 print() 用了 flush=True

还是解决不了？

  1. 复制完整报错信息
  2. 在 GitHub Issues 提问
  3. 或问 AI："我跑 agent-builder-pro 的 step_p3 遇到这个错误：[粘贴报错]"