在Mac mini M4上把OpenClaw 3.13跑起来不是难事真正让我折腾到半夜的是给qmd记忆存储接上embed能力。无论执行qmd embed还是让OpenClaw自动做记忆索引终端要么卡在一动不动要么直接甩出sqlite-vec不可用的报错。这两个问题看起来是不同故障实际是同一根因链路上的两个表现。这篇文章把我完整的排查过程和最终修复方案记录下来给正好踩在同一个坑里的人省点时间。如果你用的是Apple Silicon Mac、正在部署OpenClaw 3.13并且计划启用qmd记忆存储来管理长期记忆那这篇文章应该能帮你少走几天的弯路。1. 搞清楚调用链才知道是谁拖累了谁1.1 OpenClaw、qmd、sqlite-vec 谁依赖谁很多人在报错后第一反应是去重装sqlite-vec结果装完还是一样。原因很简单你根本没有理清这套链路里谁在调用谁。OpenClaw 3.13本身是一个Node.js写的AI代理运行时它负责调度工具、管理对话上下文。qmd是OpenClaw的本地记忆服务负责把历史对话切成片段、做embedding向量化然后写入一个带向量检索能力的SQLite数据库。这个向量检索能力来自sqlite-vec扩展它不是一个独立的服务而是SQLite的一个加载模块。也就是说调用关系是这样的OpenClawNode.js通过子进程调用 qmd CLIPythonqmd CLI 读取配置加载 embedding 模型qmd 使用 Python 内置的 sqlite3 模块连接数据库sqlite3 模块尝试加载 sqlite-vec 扩展注册vec0虚拟表之后 qmd 才能把文本向量写入数据库并在检索时用vec0做相似度查询所以当sqlite-vec 不可用出现时问题大概率出在倒数第二环Python 的 sqlite3 加载扩展失败。而qmd embed 卡死的问题则往往不是卡在SQLite而是卡在加载扩展失败后的异常处理逻辑里——qmd 可能把加载失败误判为数据库繁忙一直在重试造成假死。1.2 为什么加载失败会让 embed 看起来像卡死我一开始也以为是embed模型下载很慢等了一个小时还在转圈。后来用sample命令抓了一下进程栈发现线程根本没在跑模型推理而是卡在一个重试循环里反复调用sqlite3.load_extension。这是qmd设计上的问题它在初始化阶段如果检测到sqlite-vec加载失败不会立刻报错退出而是会进入一个带有重试逻辑的初始化流程等待扩展文件自行出现。正常情况这个等待可能只是几秒钟但在某些异常路径下它会无限循环。所以表面上是embed卡死实际上是加载失败被吞掉了。因此解决sqlite-vec 不可用是解决embed 卡死的前置条件。两个问题必须一起处理单修一个都不行。2. Mac mini M4 上容易被忽略的三个前置陷阱2.1 你的 Python 到底是 arm64 还是 x86_64这个是Mac mini M4上最隐蔽的问题。很多人是从Intel Mac迁移过来的用迁移助理把整个环境搬过来Python 还是 x86_64 版本。qmd 默认用/usr/bin/python3或者虚拟环境里的Python如果这个解释器是 x86_64 架构那么它通过 pip 安装的 sqlite-vec 也会是 x86_64 的预编译二进制。问题在于sqlite-vec 的 Python 绑定加载扩展时会调用本机 SQLite 的load_extension。在 Apple Silicon 上如果 Python 进程是 x86_64通过 Rosetta 转译而系统的 SQLite 是 arm64 原生库就会发生架构不匹配扩展加载直接失败。检查方法很简单file $(which python3) # 期望输出Mach-O 64-bit executable arm64 # 如果是 x86_64说明你的 Python 是 Rosetta 转译的如果你是使用 pyenv 或 Homebrew 安装的 Python还需要确认安装时是否带了正确的架构。我自己就踩过这个坑Homebrew 默认会装 arm64但如果之前用arch -x86_64 brew install python3.11装过那Python就是 x86_64 的。解决办法是删除重装arm64版本或者用arch -arm64强制启动。2.2 SQLite 版本与扩展加载机制sqlite-vec 对 SQLite 版本有要求最新版本需要 SQLite 3.41.0 以上因为vec0虚拟表用到了较新的 SQLite API。macOS 系统自带的 SQLite 版本通常比较老而且 Apple 会在系统更新时悄悄替换它。我当时的系统是 macOS 15.3自带 SQLite 版本是 3.43.x其实满足要求。但问题不只在版本还在于 Python 的sqlite3模块是编译时链接的 SQLite它不一定和系统自带的 SQLite 是同一个版本。如果你用 Homebrew 的 Python它链接的是 Homebrew 的 SQLite如果你用系统自带的 Python它链接的是系统的 SQLite。检查方式python3 -c import sqlite3; print(sqlite3.sqlite_version)如果这个版本低于 3.41就算sqlite-vec文件放对了位置也会加载失败。解决方案是升级 Python 或通过 Homebrew 安装新版 SQLite 后重新编译 Python更简单的做法是换用 Python 3.11 的较新补丁版本一般自带 SQLite 版本够用。2.3 模型初始化期间的静默卡死还有一个容易误判的点qmd embed卡死也可能是 embedding 模型初始化时没有输出。qmd 默认会加载一个本地 ONNX 模型首次运行需要从 HuggingFace 下载权重文件。如果你的网络环境无法直连 HuggingFace下载过程会长时间超时重试而且没有任何进度输出。我一开始看到终端卡住不动第一反应就是模型卡了但抓栈看根本不是。所以当你排查qmd embed 卡死时一定要先分清楚到底是模型下载阶段还是 SQLite 加载阶段还是真正的嵌入计算阶段。最简单的区分方法是用sample抓线程栈看卡在哪一行。这个后面详细说。3. 从看起来卡死到定位根因完整排查链路3.1 第一步抓日志而不是猜遇到卡死和报错第一步永远是找日志。OpenClaw 和 qmd 的日志位置一般在~/.openclaw/logs/~/.qmd/logs/先看 qmd 的日志尤其是embed_*.log。我当时看到的关键信息是[WARN] Failed to load sqlite-vec extension, retry in 5s这个警告出现了几十次说明它一直在重试。而 OpenClaw 的日志则显示[INFO] qmd embed child process started [INFO] waiting for qmd embed to finish...之后就没有任何输出了。所以整个链条就清楚了OpenClaw 正常启动了 qmd 子进程但 qmd 内部在反复重试加载 sqlite-vec没有继续执行。3.2 第二步用最小Python脚本复现为了不干扰qmd的业务逻辑我写了一个最小化测试脚本单独验证 sqlite-vec 能不能加载import sqlite3 import sqlite_vec db sqlite3.connect(:memory:) db.enable_load_extension(True) sqlite_vec.load(db) # 尝试创建 vec0 虚拟表 db.execute(CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[4])) print(sqlite-vec is ready)如果你跑这个脚本直接报错sqlite3.OperationalError: /usr/local/lib/python3.11/site-packages/sqlite_vec/vec0: symbol not found或者sqlite3.OperationalError: no such module: vec0说明 sqlite-vec 扩展文件确实加载不了。如果是symbol not found基本可以断定是架构不匹配或二进制依赖的库版本太新。如果这个测试通过了那问题就不在 sqlite-vec 本身而在 qmd 的初始化逻辑里。你可以继续在 qmd 的配置里开启 debug 模式看它到底在哪一步重试。3.3 第三步区分扩展加载失败与推理阻塞如果最小化脚本通过了但qmd embed还是卡死那就需要抓进程状态区分卡在哪。macOS 上我用sample命令# 找到 qmd embed 的进程 ID抓 3 秒内的线程栈 sample pid 3 -file /tmp/qmd_sample.txt查看 sample 输出中各个线程的调用栈。我当时抓完发现线程卡在select系统调用上而不是在模型推理。这说明进程在等待某个文件事件。再对应日志里的重试信息才确认是 sqlite-vec 加载失败后的重试循环。如果你看到线程卡在sgemm之类的矩阵运算函数那才说明是 embedding 模型推理阶段有问题和 SQLite 无关。3.4 用日志补齐最后一块拼图排查到最后我发现还有一个隐藏问题qmd 在加载 sqlite-vec 时不是用 pip 安装的 Python 包路径而是硬编码了外部配置文件里的路径。OpenClaw 的配置文件里填写了一个/opt/qmd/lib/vec0路径但那个路径在我的 Mac mini 上根本不存在所以每次加载都失败。这个问题很典型OpenClaw 3.13 在 Mac 上的默认配置可能沿用了一些 Linux 部署的路径。检查一下配置文件qmd: sqlite_vec_path: /opt/qmd/lib/vec0如果存在这样的字段改成你实际的 sqlite-vec 加载路径。可以用 Python 获取python3 -c import sqlite_vec; print(sqlite_vec.__file__)然后把输出路径填进去比如/opt/homebrew/lib/python3.11/site-packages/sqlite_vec/vec0。4. 终极修复三种方案按需选择4.1 方案A为 Apple Silicon 手动编译 sqlite-vec如果你的 Python 已经是 arm64且 SQLite 版本足够但 sqlite-vec 依然加载失败最稳妥的办法是从源码编译一个纯 arm64 的扩展文件。首先下载源码git clone --recurse-submodules https://github.com/asg017/sqlite-vec cd sqlite-vecMac 上需要确保有 Xcode Command Line Toolsxcode-select --install编译单文件扩展make sqlite-vec或者直接在dist/目录里找到编译好的vec0文件。如果你想让 Python 的 sqlite3 模块能够加载它需要把生成的.so或.dylib文件放到一个固定路径并在 qmd 配置里指向它。我编译后把vec0.dylib放到了/opt/qmd/lib/下然后修改 qmd 配置qmd: sqlite_vec_path: /opt/qmd/lib/vec0.dylib这里有个小细节sqlite-vec 的 Python 包在 macOS 上加载的扩展文件后缀可能是.so但实际是 Mach-O 的动态库直接改后缀不影响加载。如果你用 CMake 编译建议按官方文档来不要自己改文件名。编译过程中如果遇到clang: error: unsupported option -fopenmp说明你缺 OpenMP 库。用 Homebrew 装一下brew install libomp然后重新编译。这是 Apple Silicon 上最常见的编译报错。4.2 方案B让 qmd 切换向量索引后端如果你的业务场景对 sqlite-vec 没有强依赖只是需要记忆检索功能那更省事的方案是让 qmd 使用纯 Python 的向量索引后端。OpenClaw 3.13 的配置里可以指定 qmd 的索引类型qmd: index_backend: hnswlib或者qmd: index_backend: numpyhnswlib是纯 Python C 扩展的近似最近邻库安装体积小在 Mac mini M4 上表现也稳定。切换后qmd 会把向量存在独立文件中不再依赖 SQLite 的 vec0 虚拟表。切换后记得清理旧的 SQLite 向量库rm ~/.qmd/store.db然后重新初始化qmd reset openclaw qmd reindex这个方法适合不追求极致场景、只想要记忆功能尽快跑起来的人。我后来为了长期稳定最终选择的是 hnswlib 后端sqlite-vec 留作备用。4.3 方案C调低并发消除 embed 死锁有时候 sqlite-vec 能正常加载但qmd embed --all或者 OpenClaw 自动触发批量 embedding 时依然会卡死。这种卡死往往和并发写入 SQLite 有关。qmd 默认会用多线程并发处理文本块多个线程同时往一个 SQLite 连接里写向量时可能出现锁竞争。在 Apple Silicon 上SQLite 的线程模式如果不匹配可能卡在 pthread 锁上。解决办法是把并发数降到 1并开启 WAL 模式qmd: embed_concurrency: 1 embed_batch_size: 8 sqlite_wal: true如果你用的是 sqlite-vec还需要注意vec0虚拟表对并发写入的支持。官方文档里明确说vec0是实验性的单写入连接最稳。所以把并发调低不是性能妥协而是绕开当前扩展的稳定性边界。调完这些参数后重新执行openclaw qmd embed --incremental观察是否还会卡死。我当时调完并发后embed 的吞吐量虽然有下降但至少能稳定跑完整个历史对话的索引。4.4 我的最终选择组合修复说实话我最后不是只用了某一个方案而是三管齐下确认 Python 是 arm64并重装了所有 Python 依赖。手动编译了 sqlite-vec并让 qmd 指向编译产物。把embed_concurrency降到 2开启 WAL。这样做的原因是单独编译 sqlite-vec 解决的是加载失败但无法保证后续并发写入不卡单独调并发解决的是运行卡死但加载失败依然存在。两个问题必须同时修结论才完整。5. 修复后的验证与一段时间的使用记录5.1 验证命令与预期输出修复完成后我按以下顺序做了验证第一步验证 sqlite-vec 能正常加载python3 -c import sqlite3, sqlite_vec; dbsqlite3.connect(:memory:); db.enable_load_extension(True); sqlite_vec.load(db); db.execute(CREATE VIRTUAL TABLE t USING vec0(a float[3])); print(ok)预期输出ok没有报错。第二步验证单条 embedopenclaw qmd embed 今天在 Mac mini M4 上修复了 sqlite-vec 的问题预期输出包含向量维度信息和写入成功日志。这一步主要是确认 qmd 不会卡死。第三步验证检索openclaw qmd query Mac mini M4预期返回刚才写入的记录并带有相似度分数。第四步批量索引历史对话openclaw qmd embed --all --limit 100我放了100条历史消息进去整个过程耗时 40 秒左右没有卡死也没有报错。5.2 运行稳定性和后续维护建议距离修复完成已经跑了两个星期OpenClaw 3.13 每天都会自动触发 qmd 记忆索引和检索目前没有再次出现卡死。有几个维护建议供参考不要轻易升级 sqlite-vec Python 包。这个项目迭代很快有些新版本会改变加载方式。如果当前版本稳定锁住版本号。定期备份~/.qmd/store.db。qmd 的记忆数据都在这个文件里备份可以防止数据库损坏后丢失记忆。如果之后升级 OpenClaw 到 3.14 或更高版本注意检查配置文件里 qmd 的路径字段是否被重置。官方升级脚本有时候会覆盖配置文件。5.3 踩过几次坑之后的实在话Mac mini M4 上跑这些本地 AI 工具最大的问题不是性能而是很多 Linux 生态的扩展没有针对 Apple Silicon 做周全的轮子。sqlite-vec 就是一个典型例子。遇到报错别急着怪硬件先查架构、查SQLite版本、查路径这三个问题占了我这次故障的九成原因。如果你现在也被qmd embed 卡死折磨建议按这个顺序走一遍先看架构再测最小脚本最后改并发。多数情况下问题会在第一步或第二步暴露。如果这三步都走完了还是不行可以把日志发到 OpenClaw 的社区里附上你的 Mac 型号、Python 版本和 sqlite-vec 版本会比扔一个截图有用得多。
Mac mini M4上OpenClaw qmd记忆存储embed卡死与sqlite-vec修复指南
在Mac mini M4上把OpenClaw 3.13跑起来不是难事真正让我折腾到半夜的是给qmd记忆存储接上embed能力。无论执行qmd embed还是让OpenClaw自动做记忆索引终端要么卡在一动不动要么直接甩出sqlite-vec不可用的报错。这两个问题看起来是不同故障实际是同一根因链路上的两个表现。这篇文章把我完整的排查过程和最终修复方案记录下来给正好踩在同一个坑里的人省点时间。如果你用的是Apple Silicon Mac、正在部署OpenClaw 3.13并且计划启用qmd记忆存储来管理长期记忆那这篇文章应该能帮你少走几天的弯路。1. 搞清楚调用链才知道是谁拖累了谁1.1 OpenClaw、qmd、sqlite-vec 谁依赖谁很多人在报错后第一反应是去重装sqlite-vec结果装完还是一样。原因很简单你根本没有理清这套链路里谁在调用谁。OpenClaw 3.13本身是一个Node.js写的AI代理运行时它负责调度工具、管理对话上下文。qmd是OpenClaw的本地记忆服务负责把历史对话切成片段、做embedding向量化然后写入一个带向量检索能力的SQLite数据库。这个向量检索能力来自sqlite-vec扩展它不是一个独立的服务而是SQLite的一个加载模块。也就是说调用关系是这样的OpenClawNode.js通过子进程调用 qmd CLIPythonqmd CLI 读取配置加载 embedding 模型qmd 使用 Python 内置的 sqlite3 模块连接数据库sqlite3 模块尝试加载 sqlite-vec 扩展注册vec0虚拟表之后 qmd 才能把文本向量写入数据库并在检索时用vec0做相似度查询所以当sqlite-vec 不可用出现时问题大概率出在倒数第二环Python 的 sqlite3 加载扩展失败。而qmd embed 卡死的问题则往往不是卡在SQLite而是卡在加载扩展失败后的异常处理逻辑里——qmd 可能把加载失败误判为数据库繁忙一直在重试造成假死。1.2 为什么加载失败会让 embed 看起来像卡死我一开始也以为是embed模型下载很慢等了一个小时还在转圈。后来用sample命令抓了一下进程栈发现线程根本没在跑模型推理而是卡在一个重试循环里反复调用sqlite3.load_extension。这是qmd设计上的问题它在初始化阶段如果检测到sqlite-vec加载失败不会立刻报错退出而是会进入一个带有重试逻辑的初始化流程等待扩展文件自行出现。正常情况这个等待可能只是几秒钟但在某些异常路径下它会无限循环。所以表面上是embed卡死实际上是加载失败被吞掉了。因此解决sqlite-vec 不可用是解决embed 卡死的前置条件。两个问题必须一起处理单修一个都不行。2. Mac mini M4 上容易被忽略的三个前置陷阱2.1 你的 Python 到底是 arm64 还是 x86_64这个是Mac mini M4上最隐蔽的问题。很多人是从Intel Mac迁移过来的用迁移助理把整个环境搬过来Python 还是 x86_64 版本。qmd 默认用/usr/bin/python3或者虚拟环境里的Python如果这个解释器是 x86_64 架构那么它通过 pip 安装的 sqlite-vec 也会是 x86_64 的预编译二进制。问题在于sqlite-vec 的 Python 绑定加载扩展时会调用本机 SQLite 的load_extension。在 Apple Silicon 上如果 Python 进程是 x86_64通过 Rosetta 转译而系统的 SQLite 是 arm64 原生库就会发生架构不匹配扩展加载直接失败。检查方法很简单file $(which python3) # 期望输出Mach-O 64-bit executable arm64 # 如果是 x86_64说明你的 Python 是 Rosetta 转译的如果你是使用 pyenv 或 Homebrew 安装的 Python还需要确认安装时是否带了正确的架构。我自己就踩过这个坑Homebrew 默认会装 arm64但如果之前用arch -x86_64 brew install python3.11装过那Python就是 x86_64 的。解决办法是删除重装arm64版本或者用arch -arm64强制启动。2.2 SQLite 版本与扩展加载机制sqlite-vec 对 SQLite 版本有要求最新版本需要 SQLite 3.41.0 以上因为vec0虚拟表用到了较新的 SQLite API。macOS 系统自带的 SQLite 版本通常比较老而且 Apple 会在系统更新时悄悄替换它。我当时的系统是 macOS 15.3自带 SQLite 版本是 3.43.x其实满足要求。但问题不只在版本还在于 Python 的sqlite3模块是编译时链接的 SQLite它不一定和系统自带的 SQLite 是同一个版本。如果你用 Homebrew 的 Python它链接的是 Homebrew 的 SQLite如果你用系统自带的 Python它链接的是系统的 SQLite。检查方式python3 -c import sqlite3; print(sqlite3.sqlite_version)如果这个版本低于 3.41就算sqlite-vec文件放对了位置也会加载失败。解决方案是升级 Python 或通过 Homebrew 安装新版 SQLite 后重新编译 Python更简单的做法是换用 Python 3.11 的较新补丁版本一般自带 SQLite 版本够用。2.3 模型初始化期间的静默卡死还有一个容易误判的点qmd embed卡死也可能是 embedding 模型初始化时没有输出。qmd 默认会加载一个本地 ONNX 模型首次运行需要从 HuggingFace 下载权重文件。如果你的网络环境无法直连 HuggingFace下载过程会长时间超时重试而且没有任何进度输出。我一开始看到终端卡住不动第一反应就是模型卡了但抓栈看根本不是。所以当你排查qmd embed 卡死时一定要先分清楚到底是模型下载阶段还是 SQLite 加载阶段还是真正的嵌入计算阶段。最简单的区分方法是用sample抓线程栈看卡在哪一行。这个后面详细说。3. 从看起来卡死到定位根因完整排查链路3.1 第一步抓日志而不是猜遇到卡死和报错第一步永远是找日志。OpenClaw 和 qmd 的日志位置一般在~/.openclaw/logs/~/.qmd/logs/先看 qmd 的日志尤其是embed_*.log。我当时看到的关键信息是[WARN] Failed to load sqlite-vec extension, retry in 5s这个警告出现了几十次说明它一直在重试。而 OpenClaw 的日志则显示[INFO] qmd embed child process started [INFO] waiting for qmd embed to finish...之后就没有任何输出了。所以整个链条就清楚了OpenClaw 正常启动了 qmd 子进程但 qmd 内部在反复重试加载 sqlite-vec没有继续执行。3.2 第二步用最小Python脚本复现为了不干扰qmd的业务逻辑我写了一个最小化测试脚本单独验证 sqlite-vec 能不能加载import sqlite3 import sqlite_vec db sqlite3.connect(:memory:) db.enable_load_extension(True) sqlite_vec.load(db) # 尝试创建 vec0 虚拟表 db.execute(CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[4])) print(sqlite-vec is ready)如果你跑这个脚本直接报错sqlite3.OperationalError: /usr/local/lib/python3.11/site-packages/sqlite_vec/vec0: symbol not found或者sqlite3.OperationalError: no such module: vec0说明 sqlite-vec 扩展文件确实加载不了。如果是symbol not found基本可以断定是架构不匹配或二进制依赖的库版本太新。如果这个测试通过了那问题就不在 sqlite-vec 本身而在 qmd 的初始化逻辑里。你可以继续在 qmd 的配置里开启 debug 模式看它到底在哪一步重试。3.3 第三步区分扩展加载失败与推理阻塞如果最小化脚本通过了但qmd embed还是卡死那就需要抓进程状态区分卡在哪。macOS 上我用sample命令# 找到 qmd embed 的进程 ID抓 3 秒内的线程栈 sample pid 3 -file /tmp/qmd_sample.txt查看 sample 输出中各个线程的调用栈。我当时抓完发现线程卡在select系统调用上而不是在模型推理。这说明进程在等待某个文件事件。再对应日志里的重试信息才确认是 sqlite-vec 加载失败后的重试循环。如果你看到线程卡在sgemm之类的矩阵运算函数那才说明是 embedding 模型推理阶段有问题和 SQLite 无关。3.4 用日志补齐最后一块拼图排查到最后我发现还有一个隐藏问题qmd 在加载 sqlite-vec 时不是用 pip 安装的 Python 包路径而是硬编码了外部配置文件里的路径。OpenClaw 的配置文件里填写了一个/opt/qmd/lib/vec0路径但那个路径在我的 Mac mini 上根本不存在所以每次加载都失败。这个问题很典型OpenClaw 3.13 在 Mac 上的默认配置可能沿用了一些 Linux 部署的路径。检查一下配置文件qmd: sqlite_vec_path: /opt/qmd/lib/vec0如果存在这样的字段改成你实际的 sqlite-vec 加载路径。可以用 Python 获取python3 -c import sqlite_vec; print(sqlite_vec.__file__)然后把输出路径填进去比如/opt/homebrew/lib/python3.11/site-packages/sqlite_vec/vec0。4. 终极修复三种方案按需选择4.1 方案A为 Apple Silicon 手动编译 sqlite-vec如果你的 Python 已经是 arm64且 SQLite 版本足够但 sqlite-vec 依然加载失败最稳妥的办法是从源码编译一个纯 arm64 的扩展文件。首先下载源码git clone --recurse-submodules https://github.com/asg017/sqlite-vec cd sqlite-vecMac 上需要确保有 Xcode Command Line Toolsxcode-select --install编译单文件扩展make sqlite-vec或者直接在dist/目录里找到编译好的vec0文件。如果你想让 Python 的 sqlite3 模块能够加载它需要把生成的.so或.dylib文件放到一个固定路径并在 qmd 配置里指向它。我编译后把vec0.dylib放到了/opt/qmd/lib/下然后修改 qmd 配置qmd: sqlite_vec_path: /opt/qmd/lib/vec0.dylib这里有个小细节sqlite-vec 的 Python 包在 macOS 上加载的扩展文件后缀可能是.so但实际是 Mach-O 的动态库直接改后缀不影响加载。如果你用 CMake 编译建议按官方文档来不要自己改文件名。编译过程中如果遇到clang: error: unsupported option -fopenmp说明你缺 OpenMP 库。用 Homebrew 装一下brew install libomp然后重新编译。这是 Apple Silicon 上最常见的编译报错。4.2 方案B让 qmd 切换向量索引后端如果你的业务场景对 sqlite-vec 没有强依赖只是需要记忆检索功能那更省事的方案是让 qmd 使用纯 Python 的向量索引后端。OpenClaw 3.13 的配置里可以指定 qmd 的索引类型qmd: index_backend: hnswlib或者qmd: index_backend: numpyhnswlib是纯 Python C 扩展的近似最近邻库安装体积小在 Mac mini M4 上表现也稳定。切换后qmd 会把向量存在独立文件中不再依赖 SQLite 的 vec0 虚拟表。切换后记得清理旧的 SQLite 向量库rm ~/.qmd/store.db然后重新初始化qmd reset openclaw qmd reindex这个方法适合不追求极致场景、只想要记忆功能尽快跑起来的人。我后来为了长期稳定最终选择的是 hnswlib 后端sqlite-vec 留作备用。4.3 方案C调低并发消除 embed 死锁有时候 sqlite-vec 能正常加载但qmd embed --all或者 OpenClaw 自动触发批量 embedding 时依然会卡死。这种卡死往往和并发写入 SQLite 有关。qmd 默认会用多线程并发处理文本块多个线程同时往一个 SQLite 连接里写向量时可能出现锁竞争。在 Apple Silicon 上SQLite 的线程模式如果不匹配可能卡在 pthread 锁上。解决办法是把并发数降到 1并开启 WAL 模式qmd: embed_concurrency: 1 embed_batch_size: 8 sqlite_wal: true如果你用的是 sqlite-vec还需要注意vec0虚拟表对并发写入的支持。官方文档里明确说vec0是实验性的单写入连接最稳。所以把并发调低不是性能妥协而是绕开当前扩展的稳定性边界。调完这些参数后重新执行openclaw qmd embed --incremental观察是否还会卡死。我当时调完并发后embed 的吞吐量虽然有下降但至少能稳定跑完整个历史对话的索引。4.4 我的最终选择组合修复说实话我最后不是只用了某一个方案而是三管齐下确认 Python 是 arm64并重装了所有 Python 依赖。手动编译了 sqlite-vec并让 qmd 指向编译产物。把embed_concurrency降到 2开启 WAL。这样做的原因是单独编译 sqlite-vec 解决的是加载失败但无法保证后续并发写入不卡单独调并发解决的是运行卡死但加载失败依然存在。两个问题必须同时修结论才完整。5. 修复后的验证与一段时间的使用记录5.1 验证命令与预期输出修复完成后我按以下顺序做了验证第一步验证 sqlite-vec 能正常加载python3 -c import sqlite3, sqlite_vec; dbsqlite3.connect(:memory:); db.enable_load_extension(True); sqlite_vec.load(db); db.execute(CREATE VIRTUAL TABLE t USING vec0(a float[3])); print(ok)预期输出ok没有报错。第二步验证单条 embedopenclaw qmd embed 今天在 Mac mini M4 上修复了 sqlite-vec 的问题预期输出包含向量维度信息和写入成功日志。这一步主要是确认 qmd 不会卡死。第三步验证检索openclaw qmd query Mac mini M4预期返回刚才写入的记录并带有相似度分数。第四步批量索引历史对话openclaw qmd embed --all --limit 100我放了100条历史消息进去整个过程耗时 40 秒左右没有卡死也没有报错。5.2 运行稳定性和后续维护建议距离修复完成已经跑了两个星期OpenClaw 3.13 每天都会自动触发 qmd 记忆索引和检索目前没有再次出现卡死。有几个维护建议供参考不要轻易升级 sqlite-vec Python 包。这个项目迭代很快有些新版本会改变加载方式。如果当前版本稳定锁住版本号。定期备份~/.qmd/store.db。qmd 的记忆数据都在这个文件里备份可以防止数据库损坏后丢失记忆。如果之后升级 OpenClaw 到 3.14 或更高版本注意检查配置文件里 qmd 的路径字段是否被重置。官方升级脚本有时候会覆盖配置文件。5.3 踩过几次坑之后的实在话Mac mini M4 上跑这些本地 AI 工具最大的问题不是性能而是很多 Linux 生态的扩展没有针对 Apple Silicon 做周全的轮子。sqlite-vec 就是一个典型例子。遇到报错别急着怪硬件先查架构、查SQLite版本、查路径这三个问题占了我这次故障的九成原因。如果你现在也被qmd embed 卡死折磨建议按这个顺序走一遍先看架构再测最小脚本最后改并发。多数情况下问题会在第一步或第二步暴露。如果这三步都走完了还是不行可以把日志发到 OpenClaw 的社区里附上你的 Mac 型号、Python 版本和 sqlite-vec 版本会比扔一个截图有用得多。
