企业官网建设流程全解析

简介：这份资源面向在 Ubuntu 24.04 上部署 OpenClaw 3.2 的开发者与运维人员，聚焦安装过程中两个高频故障的排查与修复：选择千问大模型后登录页面卡死，以及 systemctl 命令报「找不到介质」导致服务无法启动。资源包共 3 个文件，以 html 页面、inscode 配置与 gitignore 忽略规则为主，压缩后约 8KB，体积轻量，便于随取随用。内容围绕服务文件创建、nvm 补充安装、Node.js 版本升级与一键脚本重跑等关键环节展开，并附带 Ubuntu、OpenClaw、npm 与 node 的版本对照信息，帮助读者快速定位环境不兼容的根因。已有 117 人学习，适合刚接触 OpenClaw 部署、需要一份可对照排错思路的初中级用户参考，也可作为搭建同类 Node.js 服务时的环境配置模板。

1. 在 Ubuntu 上装 OpenClaw：为什么你会在第三步就卡住

OpenClaw 这类开源智能体框架，最近在开发者圈子里热度不低。它主打的是让大模型直接操作本地终端、文件系统和浏览器，把「对话」变成「动手」。但很多人第一次在 Ubuntu 上装它时，往往在依赖解析或权限配置那一步就翻车了——不是 Python 版本对不上，就是某个系统库死活找不到，再不然就是装完了跑起来报一堆权限错误。这篇笔记不讲虚的，就围绕 Ubuntu 安装 OpenClaw 这条主线，把依赖准备、源码拉取、虚拟环境隔离、常见报错排查到最终跑通一个最小任务，完整走一遍。适合两类人：一是在 Ubuntu 上折腾过 Python 项目但被系统依赖搞烦的开发者，二是想拿 OpenClaw 做本地自动化但不想在环境问题上耗一整天的从业者。下面所有命令和配置都按可复现的标准写，你照着敲就能跑。

2. 装之前先把地基打牢：Ubuntu 版本、Python 与系统依赖的选型逻辑

2.1 为什么 Ubuntu 22.04 和 Python 3.10 是当前最稳的组合

OpenClaw 对运行环境有比较明确的要求，但官方文档往往只写「Python 3.10+」，实际踩下来，Ubuntu 22.04 LTS 配 Python 3.10 是兼容性最好的组合。原因不复杂：22.04 自带的 Python 就是 3.10，系统包管理器和第三方库的适配都经过大量验证，你不需要额外编译 Python 解释器，省掉一堆libssl、libffi的版本冲突。如果你用的是 Ubuntu 24.04，默认 Python 是 3.12，部分依赖包还没跟上，装的时候容易遇到ModuleNotFoundError或者 C 扩展编译失败。我一般会先确认系统版本和 Python 版本：

# 查看 Ubuntu 版本，确认是 22.04 还是 24.04 lsb_release -a # 查看系统默认 Python 版本 python3 --version # 查看 pip 版本，确保是给 python3 用的 pip3 --version

逻辑说明：lsb_release -a输出里的Release字段就是版本号。如果显示 24.04，建议要么换 22.04，要么用deadsnakes源装一个 Python 3.10 并显式指定路径。python3 --version确认解释器版本，pip3 --version确认包管理器没串到别的 Python 上。参数上没什么可调的，关键是看输出别跳过。

2.2 系统级依赖一次装齐：apt 包清单与作用说明

OpenClaw 在运行时会调用一些底层能力，比如浏览器自动化需要 Chromium 的依赖库，文件监听需要inotify工具，编译某些 Python C 扩展需要build-essential和python3-dev。这些如果等到报错再装，会反复打断流程。我习惯在创建虚拟环境之前，先把系统依赖一次性装好：

# 更新 apt 索引，确保拿到最新的包信息 sudo apt update # 安装编译工具链和 Python 开发头文件 sudo apt install -y build-essential python3-dev python3-pip python3-venv # 安装 OpenClaw 浏览器自动化所需的系统库 sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 \ libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \ libxfixes3 libxrandr2 libgbm1 libasound2 # 安装文件监听和进程管理工具 sudo apt install -y inotify-tools psmisc curl git

逻辑说明：build-essential提供 gcc、g++、make，很多 Python 包安装时要现场编译。python3-dev提供 Python.h，没有它编译会报fatal error: Python.h: No such file or directory。中间那一长串libnss3到libasound2是 Chromium 无头模式运行必需的，缺一个就可能报error while loading shared libraries。inotify-tools用于文件变更监听，psmisc里的fuser和killall在排查端口占用和残留进程时很好用。参数上-y是自动确认，批量安装时省去逐条回车。

2.3 虚拟环境隔离：为什么不能直接用系统 Python 装

直接在系统 Python 里pip install是血泪教训的重灾区。Ubuntu 22.04 开始，系统 Python 受EXTERNALLY-MANAGED保护，你强行装会报error: externally-managed-environment。就算你加了--break-system-packages绕过去，后续 OpenClaw 依赖的某个包版本和系统包冲突，整个系统工具都可能受影响。正确做法是建一个独立虚拟环境：

# 在用户目录下创建项目文件夹 mkdir -p ~/projects/openclaw-demo && cd ~/projects/openclaw-demo # 用系统 Python 3.10 创建虚拟环境 python3 -m venv venv # 激活虚拟环境，后续所有操作都在这个环境里 source venv/bin/activate # 升级 pip 和 setuptools，避免旧版解析依赖出错 pip install --upgrade pip setuptools wheel

逻辑说明：python3 -m venv venv会在当前目录生成一个venv文件夹，里面是独立的 Python 解释器和包目录。source venv/bin/activate激活后，命令行提示符前面会出现(venv)，此时pip和python都指向虚拟环境内的版本。pip install --upgrade pip setuptools wheel是必做步骤，旧版 pip 在解析复杂依赖树时经常给出错误结论，升级后能省掉很多「明明装了却导入失败」的玄学问题。参数上--upgrade表示升级到最新，不加则只在未安装时安装。

3. 从源码到跑通：OpenClaw 安装的完整命令链路

3.1 拉取源码与目录结构确认

假设你已经拿到了 OpenClaw 的源码包或仓库地址，第一步是把它放到项目目录下。常见做法是直接git clone，或者解压已有的压缩包。这里以源码目录已经在本地为例：

# 确认当前在项目根目录，且虚拟环境已激活 pwd # 输出应为 /home/你的用户名/projects/openclaw-demo # 查看源码目录结构，确认关键文件存在 ls -la # 应能看到 pyproject.toml 或 setup.py、requirements.txt、README 等

逻辑说明：pwd确认路径，避免在错误目录下操作。ls -la列出所有文件包括隐藏文件，重点看有没有pyproject.toml或setup.py，这决定了后面用哪种方式安装。如果有requirements.txt，说明依赖是显式列出的，可以先用它装依赖。参数-la中-l是长格式，-a是显示隐藏文件。

3.2 安装依赖：requirements.txt 与可编辑安装的先后顺序

依赖安装顺序有讲究。如果项目同时有requirements.txt和pyproject.toml，我一般先装requirements.txt里的固定版本依赖，再用pip install -e .做可编辑安装。这样做的原因是：requirements.txt通常锁定了经过测试的版本组合，先装它能避免 pip 在解析pyproject.toml时自动拉取不兼容的新版本。

# 先安装锁定版本的依赖 pip install -r requirements.txt # 再以可编辑模式安装 OpenClaw 本体 pip install -e . # 验证安装是否成功，查看版本和路径 pip show openclaw

逻辑说明：-r requirements.txt表示从文件读取依赖列表，逐条安装。-e .表示可编辑安装，把当前目录作为包安装，同时源码修改后无需重新安装即可生效，适合需要调试的场景。pip show openclaw会输出包名、版本、安装路径和依赖列表，如果这里报Package(s) not found，说明包名可能不叫openclaw，需要看pyproject.toml里的name字段。参数上-e是--editable的缩写，.代表当前目录。

3.3 初始化配置与最小运行验证

装完之后别急着跑复杂任务，先用一个最小命令验证核心链路是否通。OpenClaw 通常有一个 CLI 入口，可能是openclaw或者python -m openclaw。先看帮助信息：

# 查看 CLI 是否可用 openclaw --help # 如果上面的命令找不到，尝试模块方式 python -m openclaw --help # 初始化配置文件，通常会在用户目录生成默认配置 openclaw init

逻辑说明：--help是最安全的验证方式，能输出帮助就说明入口脚本和依赖都正常。如果openclaw命令找不到，大概率是虚拟环境的bin目录没在 PATH 里，激活虚拟环境后应该自动加入，没加入就手动export PATH=$PATH:~/projects/openclaw-demo/venv/bin。openclaw init会生成配置文件，常见位置是~/.config/openclaw/config.yaml或项目目录下的.openclaw文件夹，具体看输出提示。参数上init是子命令，不同项目可能叫setup或configure，以--help输出为准。

3.4 跑一个最小任务：让 OpenClaw 执行一条 shell 命令

验证安装的终极标准是让它真的干一件事。下面是一个最小示例，让 OpenClaw 执行echo并返回结果：

# minimal_task.py # 导入 OpenClaw 的核心执行器，具体模块名以实际包结构为准 from openclaw import Agent # 创建一个 Agent 实例，指定使用本地执行模式 agent = Agent(mode="local") # 下发一个最简单的 shell 任务 result = agent.run("echo 'OpenClaw is running'") # 打印执行结果和状态 print("状态:", result.status) print("输出:", result.output)

逻辑说明：Agent(mode="local")表示在本地环境执行，不走远程。agent.run()接收自然语言或命令字符串，返回一个结果对象。result.status通常是success或error，result.output是命令的标准输出。如果这里报ImportError，说明包名或模块路径和实际不符，需要看pip show openclaw输出的Location字段，进到那个目录看实际模块名。参数上mode可能还支持docker或remote，本地验证用local最直接。

4. 避坑指南：Ubuntu 装 OpenClaw 最常见的 5 个翻车现场

4.1 报错externally-managed-environment：系统 Python 保护机制

现象：在系统 Python 下执行pip install时，终端输出error: externally-managed-environment，并提示This environment is externally managed。

原因：Ubuntu 22.04 及以后版本，系统 Python 被标记为「外部管理」，pip 默认拒绝往系统目录装包，防止破坏系统工具依赖。

解决：不要用--break-system-packages硬绕，正确做法是建虚拟环境。如果已经建了虚拟环境还报这个错，说明你没激活虚拟环境，或者pip指向了系统路径。执行which pip确认路径里包含venv/bin，没有就重新source venv/bin/activate。

4.2 报错Python.h: No such file or directory：缺开发头文件

现象：安装某个依赖时，编译阶段报fatal error: Python.h: No such file or directory，然后安装中断。

原因：系统只装了 Python 运行时，没装开发头文件。很多 Python 包包含 C 扩展，安装时需要Python.h来编译。

解决：sudo apt install python3-dev。如果你用的是自己编译的 Python，需要装对应版本的-dev包，并且确保python3-config --includes能输出正确的头文件路径。装完重新执行pip install。

4.3 报错error while loading shared libraries: libgbm.so.1：浏览器依赖缺失

现象：OpenClaw 启动浏览器自动化时，报error while loading shared libraries: libgbm.so.1: cannot open shared object file。

原因：Chromium 无头模式依赖一系列系统图形库，libgbm是其中之一，Ubuntu 最小化安装或服务器版默认不带。

解决：把 2.2 节里那串libnss3到libasound2的包全部装一遍。如果还缺，用ldd命令查具体缺哪个：ldd $(which chromium) | grep "not found"，然后apt install对应的包。注意包名可能带版本号，用apt search找。

4.4 报错Address already in use：端口被残留进程占用

现象：OpenClaw 启动服务时，报OSError: [Errno 98] Address already in use，端口被占。

原因：上次运行没正常退出，进程还在后台监听端口。或者系统里别的服务占用了同一个端口。

解决：先用sudo lsof -i :端口号或sudo fuser 端口号/tcp查出占用进程的 PID，然后kill -9 PID杀掉。如果经常遇到，写个清理脚本：fuser -k 端口号/tcp直接杀掉占用该端口的进程。改端口也行，在配置文件里把port字段换成别的值。

4.5 报错ModuleNotFoundError: No module named 'xxx'：依赖装到了错误的环境

现象：明明pip install成功了，运行时报ModuleNotFoundError，说找不到某个模块。

原因：pip和python指向了不同的环境。比如用系统pip装了包，但运行时用的是虚拟环境的python，或者反过来。

解决：激活虚拟环境后，用which pip和which python确认两者路径都在同一个venv目录下。然后用pip list看包是否在列表里。如果不在，用python -m pip install 包名强制用当前 Python 的 pip 安装。养成习惯：永远用python -m pip代替裸pip，能避免大部分环境串位问题。

5. 进阶技巧：用 systemd 托管 OpenClaw 并做健康检查

装好能跑只是第一步，真要长期用，得让它像服务一样稳定运行。我一般会用 systemd 把 OpenClaw 托管起来，配合一个简单的健康检查脚本，挂了自动重启。下面是一个可复用的 unit 文件模板：

# /etc/systemd/system/openclaw.service [Unit] Description=OpenClaw Agent Service After=network.target [Service] # 指定运行用户，不要用 root User=your_username # 工作目录设为项目根目录 WorkingDirectory=/home/your_username/projects/openclaw-demo # 用虚拟环境里的 Python 解释器启动，避免路径问题 ExecStart=/home/your_username/projects/openclaw-demo/venv/bin/python -m openclaw serve # 崩溃后自动重启 Restart=on-failure RestartSec=5 # 环境变量，按需添加 Environment=OPENCLAW_CONFIG=/home/your_username/.config/openclaw/config.yaml [Install] WantedBy=multi-user.target

逻辑说明：User字段指定非 root 用户，避免权限过大。WorkingDirectory确保相对路径正确。ExecStart用虚拟环境里的 Python 绝对路径，这是关键，否则 systemd 可能调用系统 Python 导致依赖找不到。Restart=on-failure表示非正常退出时自动拉起，RestartSec=5是重启间隔。Environment可以传配置文件路径等变量。写完执行sudo systemctl daemon-reload重载配置，然后sudo systemctl enable --now openclaw开机自启并立即启动。

健康检查可以用一个简单的 curl 或进程检测脚本，配合 systemd 的ExecStartPost或者独立的 timer 实现。我习惯在 OpenClaw 里暴露一个/health接口，然后用curl -f http://localhost:端口/health判断，失败就systemctl restart openclaw。这样即使遇到内存泄漏或死锁，也能自动恢复，不用半夜爬起来手动重启。

最后说个我自己的习惯：每次装完新环境，先pip freeze > requirements-lock.txt把当前所有包的精确版本存下来。下次换机器或者重装，直接pip install -r requirements-lock.txt，能避开 90% 的「上次能跑这次不行」的玄学问题。环境这东西，能锁死就别留活口。希望帮到你。

本文还有配套的精品资源，点击获取