1. 安装前的一轮自查忘了哪一步都别急着动手先说结论如果你是从零开始接触openclaw我建议先把前两篇的准备工作完整走一遍。openclaw这个AI应用框架对运行环境不算苛刻但它依赖的底层组件比较多CentOS 7 作为老系统最大的问题不是安装本身而是各种基础库版本偏老、依赖冲突、权限问题。第三篇我会按实际踩坑顺序把“源码拉取—依赖安装—配置初始化—服务启动—问题排查”串起来讲每步都给可直接复制的命令和参数。这里先明确openclaw是什么。简单来说它是一套面向智能体Agent的工作流编排与运行框架负责把模型调用、工具调用、任务调度、记忆存储这些能力统一封装成服务。你可以在本地或服务器上跑起一个智能体服务再通过API或Web界面调用。实际部署中我们需要解决三件事代码落地、运行时依赖、配置与启停。在动手之前请务必确认两件事。第一你的服务器是不是干净的CentOS 7环境我指的是最小化安装不要装了一堆乱七八糟的东西再开始排错。第二你是否已经把前两篇中提到的系统基础环境准备好了比如yum源可用、时间同步正常、防火墙规则放行。没准备好的话别看后面命令简单你会被各种网络超时和依赖缺失折磨到怀疑人生。我自己的习惯是开工前先建一份检查清单贴在这里供你参考操作系统版本CentOS 7内核3.10.x64位可用磁盘空间至少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-size2048 npm run build千万不能盲目加大堆内存参数2G内存的机器你给Node分了4G系统直接卡死。3. 配置编写与数据库初始化关键参数逐项说清楚3.1 主配置文件的整体结构openclaw的配置通常是一个主配置文件加一个环境变量文件。主配置文件负责服务端口、存储路径、日志级别、模型接入等环境变量文件保存密钥、数据库连接串等敏感信息。我的习惯是先把.env.example复制成.env再根据实际环境逐项修改cp .env.example .env然后用vim打开配置文件逐项确认。这里不推荐直接照搬别人博客里的配置因为版本不同参数名可能完全不同。最可靠的方式是以官方模板为基准只改动必要项。3.2 模型接口与密钥配置openclaw作为AI应用框架核心功能就是把模型接入进来。你需要配置模型提供方的API地址、密钥和模型名称。举个常见例子LLM_PROVIDERopenai LLM_API_KEYsk-xxxx LLM_BASE_URLhttps://api.example.com/v1 LLM_MODELgpt-4o-mini这里的LLM_BASE_URL不一定是OpenAI官方地址很多开源模型服务商也会提供兼容接口。如果你用的是本地模型服务比如vLLM、Ollama那LLM_BASE_URL就填你的内网地址。这种情况下密钥可以随便填一个非空字符串因为本地服务通常不校验。另外要注意上下文长度设置。如果你的模型上下文窗口只有8k却在配置里写了32k运行时会频繁报token超限而且这个报错在日志里看起来像网络问题排查起来很绕。3.3 数据库初始化与迁移openclaw的数据存储可以选SQLite、MySQL或PostgreSQL。我建议正式环境用MySQL/PostgreSQLSQLite只适合本地测试。先建库建账号。以MySQL为例CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER openclawlocalhost IDENTIFIED BY 你的强密码; GRANT ALL PRIVILEGES ON openclaw.* TO openclawlocalhost; FLUSH PRIVILEGES;建完库后修改.env里对应的连接串DB_TYPEmysql DB_HOST127.0.0.1 DB_PORT3306 DB_NAMEopenclaw DB_USERopenclaw DB_PASSWORD你的强密码然后执行数据库初始化命令。不同版本的初始化命令不完全一样常见的是python manage.py migrate # 或者 openclaw db init需要注意的是初始化命令要执行成功前提是主配置文件已经能被正确解析。所以第一次跑初始化之前建议先敲一遍openclaw config --check之类的自检命令有的话一定要用它能把绝大多数写错的参数提前暴露出来。如果你在初始化的过程中遇到数据表创建失败先不要急着删库重建。查一下是不是数据库账号权限不够或者数据库版本低于项目要求MySQL 5.6和5.7在字符集处理上就有明显差异。这里是经验教训不要遇到问题就重来先查日志再动手。还有一个很多人会忽略的地方数据库连接数。openclaw在并发任务多的时候数据库连接数占用可能非常高如果你用了默认的max_connections151后期会频繁出现“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] Descriptionopenclaw AI Workflow Service Afternetwork.target mysql.service Requiresmysql.service [Service] Typesimple Userwww Groupwww WorkingDirectory/opt/openclaw ExecStart/opt/openclaw/venv/bin/openclaw serve --host 0.0.0.0 --port 8080 Restarton-failure RestartSec5 EnvironmentFile/opt/openclaw/.env [Install] WantedBymulti-user.target注意这里我没有把环境变量写在ExecStart前面而是用了EnvironmentFile这样密钥配置都在.env里统一管理后续改配置只需要改这一个文件。启动并设置开机自启systemctl daemon-reload systemctl enable openclaw systemctl start openclaw启动后查看状态systemctl status openclaw如果状态是active (running)说明已经是受systemd托管的状态了。以后看日志不用去翻文件直接用journalctl -u openclaw -f4.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跑起来之后最常见的问题是“任务执行到一半报超时”。遇到这个问题我的排查路径是先看是不是模型服务本身响应慢。如果调的是第三方API可以单独curl测试接口延迟。再看openclaw的超时参数。很多超时参数是分层的包括HTTP连接超时、读超时、Agent执行超时、工具调用超时。要逐层排查别只盯着最外层。检查是否有代理环境变量影响。如果你的服务器配置了http_proxy或https_proxy而代理本身不稳定会导致请求偶发超时。可以在启动脚本里显式清空或指定。5.3 升级注意千万别直接覆盖式更新openclaw版本更新很快我见过有人直接git pull然后重启结果整个服务起不来。原因是新版依赖变了、配置结构变了但旧配置没同步更新。我的升级流程是停服务systemctl stop openclaw备份cp -r /opt/openclaw /opt/openclaw.bak.日期拉代码git pull比对依赖pip install -r requirements.txt或npm install查配置变更看项目升级文档尤其注意BREAKING CHANGES跑数据库迁移python manage.py migrate启动服务systemctl start openclaw验证curl健康接口跑一个最简单的Agent任务这套流程看起来繁琐但能让你在出问题时随时回滚到上一个可用版本。切记不要把备份这一步省略这是我用生产事故换来的经验。我在实际部署中还有一个习惯每步操作前先记下当前状态。比如git log --oneline -5看一下当前版本pip freeze requirements.lock锁定依赖版本。这样出了问题能清楚知道自己改了什么。最后分享一段个人体会装openclaw这件事说难不难说简单也不简单。很多人的问题不是命令敲错而是不知道自己装的是什么、每个配置项背后的原理是什么。比如数据库连接串里的utf8mb4为什么不能改成utf8比如系统级环境变量和.env文件的优先级关系这些细节弄清楚了后面的路才会顺畅。如果你和我一样是第一次在CentOS 7上部署我给的建议是别图快一步一步来每完成一个环节就验证一次。前两篇准备好环境这一篇把服务跑起来并验证核心功能下一篇文章就可以讨论如何接入真实模型、配置自动化工作流了。到时候你会觉得前面受的这些折腾都值得。