适用于 Ubuntu 24.04 LTS
适用于 Azure / 云服务器 / 本地服务器
目标：稳定运行 OpenClaw Gateway + Skills

一、Ubuntu 24 的特殊性（必须先理解）

Ubuntu 24 默认启用：

PEP 668 — externally managed environment

意味着：

pip install xxx

会报：

externally-managed-environment

因此：

👉 不建议直接用系统 pip 安装 Python 工具
👉 必须使用 uv 或 pipx 进行隔离安装

二、必须安装的基础环境工具

1️⃣ 系统更新

sudo apt update
sudo apt upgrade -y

2️⃣ 安装 Node.js（OpenClaw 依赖）

建议 Node 20+：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs -y

验证：

node -v
npm -v

3️⃣ 安装 OpenClaw

sudo npm install -g openclaw

验证：

openclaw --version

三、必须安装的 Python 工具体系

Ubuntu 24 不允许直接 pip 安装系统包，因此必须使用：

四、安装 uv（强烈推荐）

OpenClaw 的多个 skill 会提示：

Install xxx (uv)

安装方式：

curl -LsSf https://astral.sh/uv/install.sh | sh
exec $SHELL -l

验证：

uv --version

uv 的作用

• 替代 pip

• 替代 pipx

• 隔离安装 Python CLI 工具

• 解决 PEP 668 问题

• 推荐安装方式：

uv tool install <package-name>

例如：

uv tool install nano-pdf
uv tool install openai-whisper

五、OpenClaw 插件（Skills）管理体系

⚠ 重要说明：

OpenClaw 官方 Skills 命令只有以下几个：

openclaw skills list
openclaw skills list --eligible
openclaw skills info <name>
openclaw skills doctor

❌ 没有 install 命令
❌ 没有 remove 命令
❌ 没有 enable 命令

六、Skills 的本质

OpenClaw 的 Skills 分两类：

1️⃣ openclaw-bundled（内置技能）

例如：

nano-pdf
openai-whisper

这些已经存在：

/usr/lib/node_modules/openclaw/skills/

但它们依赖：

系统中存在某个二进制（bin）

比如：

Requirements:
  Binaries: ✗ whisper

这意味着：

👉 你要安装 whisper 命令
👉 而不是安装 skill

2️⃣ 外部 Skills（通过 clawhub）

提示：

Tip: use `npx clawhub` to search, install, and sync skills.

这类是 npm 生态技能。

七、常见 Skills 依赖说明

nano-pdf

Binaries: nano-pdf
Install option: uv

安装：

uv tool install nano-pdf

openai-whisper

Binaries: whisper
Install option: brew

在 Ubuntu 中应使用：

uv tool install openai-whisper
sudo apt install ffmpeg -y

八、npx / npm / pnpm 的作用区别

九、常见错误与解决

1️⃣ externally-managed-environment

解决：

使用 uv tool install

2️⃣ Binaries: ✗ xxx

说明：

缺少系统命令

解决：

安装对应 CLI

3️⃣ npm token expired

说明：

私有 registry 失效

解决：

npm logout
npm login

十、完整推荐环境清单

sudo apt install git curl ffmpeg build-essential -y

# Node
sudo apt install nodejs -y

# OpenClaw
sudo npm install -g openclaw

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

# 常见工具
uv tool install nano-pdf
uv tool install openai-whisper

十一、企业级建议

1. 不要使用系统 pip

2. 所有 Python CLI 使用 uv

3. 所有 Node CLI 使用 npm 全局

4. 生产环境使用 systemd 运行 openclaw

5. Gateway 建议使用 Caddy 做 HTTPS 反代

十二、最终架构图（逻辑层）

Ubuntu 24
 ├── Node.js
 │     └── OpenClaw Gateway
 │           └── Skills (bundled)
 │
 ├── uv
 │     └── nano-pdf
 │     └── openai-whisper
 │
 ├── ffmpeg
 │
 └── systemd / Caddy

总结

在 Ubuntu 24 下运行 OpenClaw 的关键点是：

不要用系统 pip
必须使用 uv
Skills 不等于包
Skills 只是调用系统命令