openclaw-hermes-踩坑指南: 环境依赖,5个最容易踩的坑

pip冲突、Python版本、ffmpeg缺失...装好了却跑不起来？

前言

好不容易把 OpenClaw/Hermes Agent 装好了，兴冲冲输入命令准备开始——

结果报错：Module not found

或者：ffmpeg: command not found

环境依赖问题比安装问题更隐蔽，因为安装时不会报错，但运行时才会爆雷。

这篇文章帮你把最常见的环境依赖坑全部排掉。

一、pip 冲突

现象

ERROR: externally-managed-environment

原因

Python 3.11+ 默认启用 PEP 668，不允许直接用系统 pip 安装包。

解决

使用虚拟环境：

python3 -m venv ~/.venv/openclaw
source ~/.venv/openclaw/bin/activate
pip install xxx

使用 uv（最快）：

curl -LsSf https://astral.sh/install.sh | sh
uv pip install xxx

二、Python 版本不对

现象

Error: Python 3.11+ required
Current version: 3.9.6

解决

macOS：

brew install python@3.11

Ubuntu：

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.11

三、ffmpeg 缺失

现象

Error: ffmpeg not found

解决

macOS：

brew install ffmpeg

Ubuntu：

sudo apt install ffmpeg

四、系统依赖缺失

现象

error: Microsoft Visual C++ 14.0 is required

解决

macOS：

xcode-select --install

Ubuntu：

sudo apt install build-essential gcc g++ make

五、npm 依赖损坏

现象

npm ERR! cb() never called

解决

npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw

环境一键安装脚本

# macOS
brew install node python@3.11 ffmpeg

# Ubuntu
sudo apt install build-essential ffmpeg python3.11 python3-pip

快速检查清单

python3 --version  # ≥ 3.11
ffmpeg -version    # 有版本号
node -v            # ≥ v22

下期预告

03 | 模型配置坑——API Key、中转平台、模型ID

敬请期待。