一、环境信息
- 设备:Mac mini M4(32GB)
- 系统:macOS
- OpenClaw 版本:3.13
- qmd 版本:2.0.1
- Homebrew:已安装(用于安装支持扩展的 SQLite)
二、问题根源分析
- 模型下载慢 / 卡死:qmd 首次 embed 会自动从 HuggingFace 下载 GGUF 模型,国内网络访问极慢,导致长时间无响应。
- sqlite-vec 扩展加载失败:qmd 默认使用 Bun 内置的 SQLite,而 macOS 系统自带 SQLite 不支持
loadExtension接口,导致无法加载vec0.dylib向量扩展,报错sqlite-vec is not available。 - Bun 与系统 SQLite 兼容问题:Bun 内置 SQLite 无法直接替换为系统版,需要手动修改 qmd 源码,让 Bun 调用 Homebrew 安装的支持扩展的 SQLite。
三、分步解决(核心教程)
步骤 1:加速 HuggingFace 模型下载(解决网络问题)
国内网络直接下载 HuggingFace 模型会超时,通过 HF Mirror 镜像 加速:
# 临时设置 HF 镜像环境变量(当前终端生效)
export HF_ENDPOINT=https://hf-mirror.com
# 永久生效(写入 ~/.zshrc,避免每次重启终端重新设置)
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc
source ~/.zshrc

