装 OpenClaw 报错，第一步该看什么？

看报错的最后几行，别被前面一堆栈吓到。真正的原因通常在最后一句，比如 No module named、port already in use、Permission denied。先把这句拷出来对照本文。

用 Docker 装是不是能少踩很多坑？

是。依赖冲突、Python 版本、编码这几类坑，Docker 镜像里都固定好了，新手用它能绕开一大半。代价是要先装 Docker，本地模型直通显卡稍麻烦。

报错本文也没有怎么办？

把最后一行报错原样搜索，加上 OpenClaw 关键词，多数安装问题别人都遇到过。实在不行，重建一个干净虚拟环境往往比逐行排查更快。

🛠️

排错 · 安装

OpenClaw 装不上？10 个常见报错对照解决

钳叔 · 龙虾AI 编辑部 · 2026-06 · 约 12 分钟

装龙虾时满屏红字弹出来，很多人第一反应是慌——其实大可不必。这么多年踩下来，安装失败九成都逃不出下面这十类，而且报错信息本身就在告诉你属于哪一类，会读就等于解决了一半。下面每类都按「现象 → 原因 → 解决」排好，对号入座即可。先教你一招通用的：报错只看最后几行，前面那一长串调用栈基本是噪音，真正的病因往往藏在最后一句。

动手前的两条通用建议

永远用独立虚拟环境装。别往系统 Python 里直接塞，一旦冲突很难收拾。新建一个干净环境，问题少一半。
记下你的环境三件套：操作系统、Python 版本、装的方式（源码 / pip / Docker）。下面很多坑跟这三个直接相关。

1. 依赖冲突：装到一半说某个包版本不兼容

现象：装的过程中红字提示 conflicting dependencies 或某个包「requires X but you have Y」。

原因：你的环境里已经装过别的项目，旧版本的包跟龙虾要的版本打架。

解决：新建一个全新的虚拟环境再装，不要在装过其他东西的环境里硬塞：

python -m venv openclaw-env
source openclaw-env/bin/activate   # Windows 用 openclaw-env\Scripts\activate
pip install -r requirements.txt

2. Python 版本不对：装好了却启动报语法错误

现象：装的时候没事，一运行就报 SyntaxError 或「unsupported Python version」。

原因：系统里有好几个 Python，默认那个版本太老（比如还停在 3.8），龙虾用到了新语法。

解决：先 python --version 确认。版本太低就装一个较新的解释器，再用它来建虚拟环境。注意 python 和 python3 在某些系统上指向不同版本，别认错。

3. 端口被占：启动后说地址已被使用

现象：启动时报 address already in use 或 port 8xxx is busy。

原因：默认端口被别的程序（甚至上一次没关干净的龙虾自己）占着。

解决：要么换个端口启动，要么找到占用端口的进程关掉。先查谁占着：

lsof -i :8080          # macOS / Linux
netstat -ano | findstr 8080   # Windows

4. 权限不足：写文件或装包时 Permission denied

现象：Permission denied，常出现在写日志、建数据目录或全局装包时。

原因：你在没有写权限的目录里操作，或者往系统目录全局装包。

解决：把项目放在自己有权限的目录（比如用户主目录下），装包加 --user 或干脆用虚拟环境。别一上来就 sudo——用 root 装出来的环境往往后面更麻烦。

5. 网络超时：下载依赖卡住或失败

现象：装包时长时间不动，最后报 timeout 或 connection reset。

原因：包源在境外，网络不稳。

解决：换一个国内镜像源装，速度立竿见影。临时指定镜像：

pip install -r requirements.txt -i https://镜像地址/simple

6. 编码乱码：日志或配置文件里中文变方块

现象：启动日志里中文是乱码，或读配置文件时报 UnicodeDecodeError。

原因：系统默认编码不是 UTF-8，Windows 上尤其常见。

解决：把终端和配置文件统一成 UTF-8。Windows 上可在启动前设环境变量 PYTHONUTF8=1，并确认配置文件保存为「UTF-8 无 BOM」。

7. 缺系统库：报缺少某个 .so 或 dll

现象：装某些带编译的包时报缺 libxxx，或运行时找不到动态库。

原因：这些 Python 包依赖系统级的编译工具或库，光有 pip 不够。

解决：按报错里提到的库名，用系统包管理器补上对应的开发库（Linux 上通常是带 -dev 后缀的包），再重装。

8. 磁盘 / 临时目录满：装到一半 No space left

现象：No space left on device，下载或解压大依赖时崩。

原因：磁盘或临时目录空间不够，模型相关依赖体积不小。

解决：清理空间，或把临时目录指到一个空间大的盘。装本地模型前预留几十 GB 比较稳妥。

9. 代理把安装搅黄：开了梯子反而连不上

现象：开着代理时装包各种失败，关掉又下不动境外源。

原因：代理只代理了一部分流量，pip 或 git 没走代理，状态错乱。

解决：要么给 pip / git 也显式配上代理，要么干脆关代理 + 换国内镜像源，两条路别混着走。

10. 装完启动闪退：缺配置或环境变量没填

现象：装是装好了，一启动就立刻退出，日志里提示某个 key 缺失。

原因：龙虾要接模型当大脑，没配 API key 或模型地址，它启动自检不过。

解决：照教程把配置文件 / 环境变量里的模型 key、地址填好再启动。怎么接模型见接 API 还是本地模型。

🦞 避坑提示 在装过别的 Python 项目的机器上裸装龙虾，最容易撞「依赖冲突」（第 1 类）——系统里别的包版本和龙虾要的对不上。与其事后排查，不如一开始就用 python -m venv 建一个干净的虚拟环境再装，这一步能挡掉相当一部分安装类报错。另一个常见的是「端口被占」（第 3 类），多半是上次没关干净的旧进程占着，用 lsof -i :8080 查出来杀掉即可。先建干净环境、再留意端口，安装阶段基本就顺了。

实在搞不定时

如果逐条对完还是不行，最省事的办法不是死磕——删掉环境，用 Docker 重来一遍。镜像里把依赖、Python 版本、编码都固定好了，新手用 Docker 能绕开本文一大半的坑。具体步骤见用 Docker 装 OpenClaw。模型那一侧连不上是另一类问题，单独看连不上模型怎么排。

常见问题

装 OpenClaw 报错，第一步该看什么？: 看报错的最后几行，别被前面一堆栈吓到。真正的原因通常在最后一句，比如 No module named、port already in use、Permission denied。先把这句拷出来对照本文。
用 Docker 装是不是能少踩很多坑？: 是。依赖冲突、Python 版本、编码这几类坑，Docker 镜像里都固定好了，新手用它能绕开一大半。代价是要先装 Docker，本地模型直通显卡稍麻烦。
报错本文也没有怎么办？: 把最后一行报错原样搜索，加上 OpenClaw 关键词，多数安装问题别人都遇到过。实在不行，重建一个干净虚拟环境往往比逐行排查更快。