跳到主要内容

常见问题排查

本文按安装、配置、渠道和技能四个维度整理当前 CountBot 最常见的问题。

安装与运行​

提示 python: command not found​

原因：

  • Python 未安装
  • Python 未加入系统 PATH

建议：

  • Windows 重新安装 Python 时勾选“Add Python to PATH”
  • macOS / Linux 优先使用 python3

提示 ModuleNotFoundError: No module named 'xxx'​

原因：

  • 依赖未安装完整
  • 虚拟环境未激活

建议：

pip install -r requirements.txt

如果你使用虚拟环境，先激活再安装。

pip install 报 SSL: CERTIFICATE_VERIFY_FAILED​

建议先尝试镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

启动时报 Address already in use​

表示端口已被占用。

可以：

  • 换一个端口启动
  • 结束占用 8000 端口的进程

在桌面模式里，start_desktop.py 也对这一类错误做了识别。

桌面环境​

Windows 缺少 WebView2​

桌面版依赖 Edge WebView2。若提示缺失，请安装：

  • WebView2 Runtime

Linux 缺少 webkit2gtk​

桌面模式通常需要系统安装对应 WebKit 依赖。

例如 Ubuntu / Debian：

sudo apt install -y libwebkit2gtk-4.0-37

模型与配置​

API Key 无效或测试失败​

优先检查：

  1. 是否把 key 粘贴完整
  2. provider 与 API Base 是否对应
  3. 该模型是否可用
  4. 后端日志中是否已经给出更明确的错误

保存配置后没有生效​

当前有两类情况：

  • 纯运行时参数会立即生效
  • 部分安全 / 工作空间相关配置可能需要重启

尤其要留意：

  • restrict_to_workspace
  • Shell 安全相关配置

默认模型与注册表默认值不一致​

这是当前代码允许的行为。

例如应用默认模型配置来自 backend/modules/config/schema.py，而 provider 注册表里也会维护各自默认模型。最终使用哪个值，取决于你是否在应用配置里显式覆盖。

渠道接入​

飞书机器人不回复​

建议检查：

  1. App ID / App Secret 是否正确
  2. 应用是否已发布
  3. 事件订阅是否已开启
  4. 后端日志里是否有飞书 worker 相关错误

当前实现中，飞书使用独立 worker：

  • backend/modules/channels/feishu.py
  • backend/modules/channels/feishu_websocket_worker.py

钉钉机器人不回复​

建议检查：

  1. 是否安装 dingtalk-stream
  2. Client ID / Client Secret 是否正确
  3. Stream 模式是否已开启

安装依赖：

pip install dingtalk-stream

Telegram 无法连接​

当前 Telegram 渠道支持代理配置，字段在配置模型里就是 proxy。

可用格式例如：

  • socks5://127.0.0.1:1080
  • http://127.0.0.1:7890

对应实现可参考：

  • backend/modules/channels/telegram.py

提示 python-telegram-bot not installed​

说明 Telegram 依赖未安装。重新安装依赖或单独安装对应包即可。

技能与工具​

技能调用时报 python: command not found​

本质上仍是 Python 环境问题，优先回到安装章节排查。

Shell 工具执行失败​

重点检查：

  1. 是否命中了危险命令拦截
  2. 是否开启了命令白名单
  3. 是否开启了工作空间限制
  4. 命令是否超时或输出过长

相关实现：

  • backend/modules/tools/shell.py
  • backend/modules/config/schema.py

文件读写被拒绝​

通常与 restrict_to_workspace 有关。

如果开启该选项，文件工具会优先限制在工作空间内运行。

认证与远程访问​

远程打开页面后提示需要初始化认证​

这通常是正常行为。

当前首次初始化管理员密码默认只能在本机完成；远程初始化必须携带合法的 setup secret。

登录成功但 WebSocket 仍然报认证失败​

优先检查：

  1. Cookie 是否成功写入
  2. 反向代理是否透传 Cookie / Authorization
  3. 是否把远程访问误认为本地访问

排查建议​

遇到问题时，建议按以下顺序排查：

  1. 看前端报错信息
  2. 看后端日志
  3. 确认当前配置是否真的保存成功
  4. 再定位到具体 provider、渠道或工具模块

相关文档​