在 Ubuntu 24 上运行 OpenClaw 时遭遇 PEP 668 的完整解决方案 —— 不修改 Skills，让 OpenClaw 自动管理 Python 依赖

最近openclaw很火，我也尝试尝试，但收集整理网页资料就卡住了........

一、问题背景

在 Ubuntu 24（Python 3.12）环境下部署 OpenClaw 后，在执行 Python 类型的 skill 或脚本时，频繁遇到以下错误：

error: externally-managed-environment
This environment is externally managed
See PEP 668 for details.

或者：

ModuleNotFoundError: No module named 'xxx'

当尝试通过：

pip install xxx

安装依赖时，又被 PEP 668 拦截。

二、问题根源分析

Ubuntu 23+ 开始引入 PEP 668 机制，其核心规则是：

禁止通过 pip 向系统 Python 的 site-packages 写入依赖。

而 OpenClaw 的工具执行环境具有以下特性：

1. 使用 /usr/bin/python3

2. 在执行 tools 时会“清洗 / 重排 PATH”

3. 不一定继承 systemd 注入的 PATH 顺序

4. Skills 内部可能直接调用 pip install

因此：

• 修改 PATH 强制使用 venv 不稳定

• 修改 skills 不现实（skills 会更新覆盖）

• 使用 --break-system-packages 不安全

必须找到一个 既不改 skills，又不破坏系统 Python，还能自动安装依赖 的方案。

三、最终稳定架构方案

核心思路：

让 pip 默认安装到一个“专用依赖目录”，并通过 PYTHONPATH 让 Python 自动加载。

这样可以：

• 避免写入系统 site-packages

• 不触发 PEP 668

• 不依赖 venv

• 不修改 skills

• 支持新增 skill 自动安装依赖

四、完整实施步骤

1️⃣ 创建专用依赖目录

sudo mkdir -p /data/openclaw/pip-target
sudo mkdir -p /data/openclaw/pip-cache
sudo chown -R openclaw-user:openclaw-user /data/openclaw

2️⃣ 为 systemd 服务注入环境变量

执行：

sudo systemctl edit openclaw

添加：

[Service]
Environment="PIP_TARGET=/data/openclaw/pip-target"
Environment="PYTHONPATH=/data/openclaw/pip-target"
Environment="PIP_CACHE_DIR=/data/openclaw/pip-cache"
Environment="PIP_USER=0"

然后：

sudo systemctl daemon-reload
sudo systemctl restart openclaw

3️⃣ 验证环境变量是否生效

在 OpenClaw tools 中执行：

env | egrep '^(PIP_TARGET|PYTHONPATH|PIP_CACHE_DIR)='

确认变量存在。

4️⃣ 测试自动安装机制

在 OpenClaw tools 中执行：

python3 -m pip install beautifulsoup4
python3 -c "from bs4 import BeautifulSoup; print('OK')"

如果输出 OK，说明机制成功。

五、为什么必须设置 PIP_USER=0？

部分环境下 pip 默认附带 --user 参数。

但：

• --user

• --target

不能同时使用。

因此必须通过：

Environment="PIP_USER=0"

关闭 user 安装模式，避免冲突。

六、最终架构模型

当前环境结构如下：

系统 python3 (/usr/bin/python3)
        ↓
PIP_TARGET 指向专用目录
        ↓
pip 安装到 /data/openclaw/pip-target
        ↓
PYTHONPATH 指向该目录
        ↓
python3 自动 import 成功

优点：

• 不触发 PEP 668

• 不污染系统 Python

• 不依赖 venv

• 不修改 skills

• 新 skill 自动支持 pip 安装

七、常见问题补充

Q1：是否还需要 virtualenv？

不需要。

在 OpenClaw 沙箱策略下，PATH 可能被重排，venv 优先级不可靠。

使用 PIP_TARGET + PYTHONPATH 更稳定。

Q2：是否可以使用 apt？

可以。

对于常见包（如 requests、lxml），apt 更稳定：

sudo apt install python3-requests python3-lxml

但对于冷门包或新 skill 依赖，pip-target 更灵活。

Q3：是否支持新增 skill 自动管理依赖？

支持。

只要 skill 内执行：

pip install xxx

依赖会自动安装到 pip-target 目录。

八、总结

在 Ubuntu 24 + Python 3.12 + OpenClaw 环境中：

• PEP 668 是系统级安全机制

• OpenClaw tools 会清洗 PATH

• venv 强制注入并不可靠

最终最稳定的工程解是：

使用 PIP_TARGET + PYTHONPATH 让 OpenClaw 自管理依赖，而不修改 skills。

这是一个：

• 安全

• 可扩展

• 低维护成本

• 适合生产环境

的解决方案。