CentOS 7部署openclaw全指南：环境检查、依赖安装与服务托管避坑实录

1. 安装前的一轮自查，忘了哪一步都别急着动手

先说结论：如果你是从零开始接触openclaw，我建议先把前两篇的准备工作完整走一遍。openclaw这个AI应用框架对运行环境不算苛刻，但它依赖的底层组件比较多，CentOS 7 作为老系统，最大的问题不是安装本身，而是各种基础库版本偏老、依赖冲突、权限问题。第三篇我会按实际踩坑顺序，把“源码拉取—依赖安装—配置初始化—服务启动—问题排查”串起来讲，每步都给可直接复制的命令和参数。

这里先明确openclaw是什么。简单来说，它是一套面向智能体（Agent）的工作流编排与运行框架，负责把模型调用、工具调用、任务调度、记忆存储这些能力统一封装成服务。你可以在本地或服务器上跑起一个智能体服务，再通过API或Web界面调用。实际部署中，我们需要解决三件事：代码落地、运行时依赖、配置与启停。

在动手之前，请务必确认两件事。第一，你的服务器是不是干净的CentOS 7环境，我指的是最小化安装，不要装了一堆乱七八糟的东西再开始排错。第二，你是否已经把前两篇中提到的系统基础环境准备好了，比如yum源可用、时间同步正常、防火墙规则放行。没准备好的话，别看后面命令简单，你会被各种网络超时和依赖缺失折磨到怀疑人生。

我自己的习惯是开工前先建一份检查清单，贴在这里供你参考：

• 操作系统版本：CentOS 7，内核3.10.x，64位
• 可用磁盘空间：至少10GB，建议20GB以上
• 内存：至少2GB，推荐4GB
• 已安装基础工具：git、curl、wget、vim、tar
• 已安装运行时：Python 3.8+ 或 Node.js 16+（取决于openclaw版本）
• 数据库：MySQL 5.7+ 或 PostgreSQL 12+（二选一）
• 外网访问：能正常拉取代码仓库和安装依赖包
• 域名或IP：用于访问控制台，以及配置回调地址

如果你用的是一台低配机器，比如1核1G，那后面的构建过程会非常痛苦。我试过在1G内存的机器上跑前端构建，构建中途直接被OOM killer干掉，连报错信息都来不及看。所以有条件的话，至少2G内存起步，这是最实在的建议。

2. 源码拉取与运行时依赖安装，这些坑我都踩过

2.1 代码目录规划与拉取

openclaw这类项目，我建议单独建一个应用目录，不要直接丢在root家目录里，也别放在/tmp下面。原因很简单：后续升级、备份、迁移时，一个独立目录能省掉一堆麻烦。

mkdir -p /opt/openclaw cd /opt/openclaw

从代码仓库拉取时，注意确认默认分支。很多项目默认分支已经从master改成main了，拉代码前可以用git ls-remote快速看下，避免拉到空分支还一脸懵。

git ls-remote --heads <仓库地址>

然后按实际分支拉取，比如：

git clone -b main <仓库地址> .

为什么要指定分支？因为openclaw这种迭代快的项目，开发分支可能随时编译不过，稳定分支才是社区验证过的。你不想半夜部署的时候发现代码里有未完成的调试输出吧。

拉完代码后，第一件事不是急着装依赖，而是看目录里的README和部署文档，还有.env.example这类模板文件。很多问题都出在版本不匹配上，仓库里的文档和配置模板通常能帮你少走一半弯路。

2.2 Python依赖安装的正确姿势

如果你下载的openclaw版本是基于Python的，推荐用虚拟环境隔离依赖，不要直接用系统Python，更不要用root去pip install全局包。之前我看到有人在生产服务器上把全局Python环境弄得一团糟，后来系统工具都启动不了，只能重装系统。

python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt

这里注意几点：

• 安装慢的话，可以换国内PyPI镜像源，比如在pip命令里加-i参数。但要注意，某些私有依赖包在镜像源里没有，这种情况下还是切回官方源。
• requirements.txt里如果包含torch、numpy这类编译型包，建议直接安装对应版本的wheel包，避免源码编译踩坑。CentOS 7自带的gcc版本为4.8.5，编译新版Python C扩展时经常因为C++标准不兼容而失败。
• 装完依赖后，顺手验证下关键包是否能正常导入。

python -c "import openclaw"

如果导入时报缺少动态库，通常是因为系统缺少某些so库，比如libssl.so.1.1，可以通过yum install openssl11解决。

2.3 Node.js 依赖安装与前端构建

openclaw如果有Web控制台，大概率你还会碰到前端依赖安装。CentOS 7上安装Node.js要特别注意版本，系统自带的Node版本一般是6.x或8.x，对于现代前端工程来说完全不够用。

curl -sL https://rpm.nodesource.com/setup_16.x | bash - yum install -y nodejs

装完确认版本：

node -v npm -v

如果npm下载依赖非常慢，同样可以配置镜像源。改了npm配置后，记得清理缓存再重新安装：

npm cache clean --force npm install

前端构建命令一般是npm run build或者npm run build:prod，构建输出的静态文件目录通常是dist/，后续需要把它们配置到Nginx或openclaw的静态资源目录中。

这里有个教训：构建时如果报内存不足，先检查是不是机器内存太小，再检查Node的堆内存上限。可以在构建命令前加上环境变量：

export NODE_OPTIONS=--max-old-space-size=2048 npm run build

千万不能盲目加大堆内存参数，2G内存的机器你给Node分了4G，系统直接卡死。

3. 配置编写与数据库初始化，关键参数逐项说清楚

3.1 主配置文件的整体结构

openclaw的配置通常是一个主配置文件加一个环境变量文件。主配置文件负责服务端口、存储路径、日志级别、模型接入等；环境变量文件保存密钥、数据库连接串等敏感信息。

我的习惯是先把.env.example复制成.env，再根据实际环境逐项修改：

cp .env.example .env

然后用vim打开配置文件，逐项确认。这里不推荐直接照搬别人博客里的配置，因为版本不同参数名可能完全不同。最可靠的方式是以官方模板为基准，只改动必要项。

3.2 模型接口与密钥配置

openclaw作为AI应用框架，核心功能就是把模型接入进来。你需要配置模型提供方的API地址、密钥和模型名称。举个常见例子：

LLM_PROVIDER=openai LLM_API_KEY=sk-xxxx LLM_BASE_URL=https://api.example.com/v1 LLM_MODEL=gpt-4o-mini

这里的LLM_BASE_URL不一定是OpenAI官方地址，很多开源模型服务商也会提供兼容接口。如果你用的是本地模型服务，比如vLLM、Ollama，那LLM_BASE_URL就填你的内网地址。这种情况下，密钥可以随便填一个非空字符串，因为本地服务通常不校验。

另外要注意上下文长度设置。如果你的模型上下文窗口只有8k，却在配置里写了32k，运行时会频繁报token超限，而且这个报错在日志里看起来像网络问题，排查起来很绕。

3.3 数据库初始化与迁移

openclaw的数据存储可以选SQLite、MySQL或PostgreSQL。我建议正式环境用MySQL/PostgreSQL，SQLite只适合本地测试。

先建库建账号。以MySQL为例：

CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'openclaw'@'localhost' IDENTIFIED BY '你的强密码'; GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw'@'localhost'; FLUSH PRIVILEGES;

建完库后，修改.env里对应的连接串：

DB_TYPE=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_NAME=openclaw DB_USER=openclaw DB_PASSWORD=你的强密码

然后执行数据库初始化命令。不同版本的初始化命令不完全一样，常见的是：

python manage.py migrate # 或者 openclaw db init

需要注意的是，初始化命令要执行成功，前提是主配置文件已经能被正确解析。所以第一次跑初始化之前，建议先敲一遍openclaw config --check之类的自检命令，有的话一定要用，它能把绝大多数写错的参数提前暴露出来。

如果你在初始化的过程中遇到数据表创建失败，先不要急着删库重建。查一下是不是数据库账号权限不够，或者数据库版本低于项目要求，MySQL 5.6和5.7在字符集处理上就有明显差异。这里是经验教训：不要遇到问题就重来，先查日志，再动手。

还有一个很多人会忽略的地方：数据库连接数。openclaw在并发任务多的时候，数据库连接数占用可能非常高，如果你用了默认的max_connections=151，后期会频繁出现“Too many connections”错误。建议顺手改大一点，比如512。

4. 启动服务、验证功能与开机自启

4.1 首次启动前的重要检查

在真正敲下启动命令之前，花两分钟做一个快速检查，能避免99%的启动失败：

• 检查.env里的密钥是否填全，有没有残留的your-key-here这类占位符
• 检查日志目录是否存在，不存在就提前创建
• 检查服务端口是否被占用

ss -lntp | grep 8080

如果没有输出，说明端口空闲。如果被占用，要么改openclaw的监听端口，要么把占用端口的进程处理掉。

4.2 前台启动与首次运行日志

第一次启动服务，强烈建议用前台模式跑，这样日志直接打在终端上，方便实时观察。

openclaw serve --host 0.0.0.0 --port 8080

当看到类似下面的日志时，说明服务已经正常起来：

INFO Application started on http://0.0.0.0:8080 INFO Worker manager started with 4 workers

看到Application started之后，不要急着关掉终端。打开另一个终端窗口，验证一下健康检查接口：

curl http://127.0.0.1:8080/health

如果返回{"status":"ok"}这类JSON，恭喜你，服务活着。

4.3 用systemd把服务托管起来

前台验证通过后，就可以把它交给systemd管了。创建服务文件：

vim /etc/systemd/system/openclaw.service

内容大致如下：

[Unit] Description=openclaw AI Workflow Service After=network.target mysql.service Requires=mysql.service [Service] Type=simple User=www Group=www WorkingDirectory=/opt/openclaw ExecStart=/opt/openclaw/venv/bin/openclaw serve --host 0.0.0.0 --port 8080 Restart=on-failure RestartSec=5 EnvironmentFile=/opt/openclaw/.env [Install] WantedBy=multi-user.target

注意这里我没有把环境变量写在ExecStart前面，而是用了EnvironmentFile，这样密钥配置都在.env里统一管理，后续改配置只需要改这一个文件。

启动并设置开机自启：

systemctl daemon-reload systemctl enable openclaw systemctl start openclaw

启动后查看状态：

systemctl status openclaw

如果状态是active (running)，说明已经是受systemd托管的状态了。以后看日志不用去翻文件，直接用：

journalctl -u openclaw -f

4.4 日志轮转与日常运维

服务跑起来之后，第一件事是确认日志会不会无限膨胀。openclaw日志如果级别设成INFO，一天下来几百MB很正常。配置logrotate让它按天切割：

vim /etc/logrotate.d/openclaw

/opt/openclaw/logs/*.log { daily rotate 14 compress delaycompress missingok notifempty copytruncate }

这里用了copytruncate，是因为openclaw进程把日志文件句柄持有不放，直接rename可能导致进程继续往旧文件写日志，copytruncate可以避免这个问题。这是我实际运维中踩过坑才加的。

5. 常见问题排查与避坑实录

5.1 启动失败的问题定位思路

最常见的启动失败场景有两个：端口被占用和依赖缺失。端口问题上面已经说了。依赖缺失的表现通常是：

ImportError: libcrypto.so.1.1: cannot open shared object file

这类问题在CentOS 7上特别典型，因为系统自带的OpenSSL版本是1.0.2，而Python 3.8+编译的包需要OpenSSL 1.1。解决办法是安装兼容版本：

yum install openssl11 yum install openssl11-devel

装完之后，如果还是报同样的错，请确认你的Python虚拟环境是否重新编译过相关扩展包。某些场景下需要重建虚拟环境才能正确链接到新版OpenSSL。

还有一类非常隐蔽的问题，是系统时间和实际时间偏差过大。openclaw在调用模型接口时，如果本机时间和实际时间相差超过5分钟，HTTPS证书校验会直接失败，报错却是Connection reset by peer。排查网络问题前先执行date看一眼，我在生产环境排查过两次这种问题，每次都是时间漂移。

5.2 模型调用超时的排查路径

openclaw跑起来之后，最常见的问题是“任务执行到一半报超时”。遇到这个问题，我的排查路径是：

1. 先看是不是模型服务本身响应慢。如果调的是第三方API，可以单独curl测试接口延迟。
2. 再看openclaw的超时参数。很多超时参数是分层的，包括HTTP连接超时、读超时、Agent执行超时、工具调用超时。要逐层排查，别只盯着最外层。
3. 检查是否有代理环境变量影响。如果你的服务器配置了http_proxy或https_proxy，而代理本身不稳定，会导致请求偶发超时。可以在启动脚本里显式清空或指定。

5.3 升级注意，千万别直接覆盖式更新

openclaw版本更新很快，我见过有人直接git pull然后重启，结果整个服务起不来。原因是新版依赖变了、配置结构变了，但旧配置没同步更新。

我的升级流程是：

1. 停服务：systemctl stop openclaw
2. 备份：cp -r /opt/openclaw /opt/openclaw.bak.日期
3. 拉代码：git pull
4. 比对依赖：pip install -r requirements.txt或npm install
5. 查配置变更：看项目升级文档，尤其注意BREAKING CHANGES
6. 跑数据库迁移：python manage.py migrate
7. 启动服务：systemctl start openclaw
8. 验证：curl健康接口，跑一个最简单的Agent任务

这套流程看起来繁琐，但能让你在出问题时随时回滚到上一个可用版本。切记不要把备份这一步省略，这是我用生产事故换来的经验。

我在实际部署中还有一个习惯：每步操作前先记下当前状态。比如git log --oneline -5看一下当前版本，pip freeze > requirements.lock锁定依赖版本。这样出了问题，能清楚知道自己改了什么。

最后分享一段个人体会

装openclaw这件事，说难不难，说简单也不简单。很多人的问题不是命令敲错，而是不知道自己装的是什么、每个配置项背后的原理是什么。比如数据库连接串里的utf8mb4为什么不能改成utf8，比如系统级环境变量和.env文件的优先级关系，这些细节弄清楚了，后面的路才会顺畅。

如果你和我一样是第一次在CentOS 7上部署，我给的建议是：别图快，一步一步来，每完成一个环节就验证一次。前两篇准备好环境，这一篇把服务跑起来并验证核心功能，下一篇文章就可以讨论如何接入真实模型、配置自动化工作流了。到时候你会觉得，前面受的这些折腾都值得。