最近有好几个朋友来问我，说看到“OpenClaw”这个词，知道是个开源的智能体项目，但一听到“部署”两个字就头大，总觉得要写一堆代码、搞一堆环境。其实真上手之后你会发现，只要把几个关键步骤理顺，整个过程比想象中简单不少。这篇教程我就用自己在一台云服务器上从零跑通OpenClaw的实际经历，把每一步操作、每个命令、每个需要留意的坑都摊开来讲，保证你照着做也能把服务跑起来。
这篇内容适合两类人：一类是刚接触智能体、想在自己服务器上搭一个常驻服务来调用大模型API的；另一类是有过一些Linux使用经验，想学习用Docker部署开源项目的。文章里我不会绕弯子，全部是实操过的命令和配置，你复制过去就能用。
1. 部署前的规划：选服务器和定方案
1.1 为什么要把OpenClaw跑在云服务器上
很多人一开始喜欢在本地电脑上跑OpenClaw，图个方便。但用一阵子就会发现，本地运行有几个绕不开的问题：电脑一关服务就断；家里的网络IP不固定，想对外提供接口很麻烦；如果需要在固定的时间自动执行任务，电脑不能一直开着。所以把OpenClaw部署在一台云服务器上，才是真正适合长期使用的方案。
云服务器能够7x24小时运行，你不需要关心断电、断网。同时，服务器有一个固定的公网IP，你可以把OpenClaw的服务通过API暴露给其他系统，或者配合定时任务让它每天自动跑一些数据处理的活。再一个，云服务器上跑Docker很干净，不会污染宿主机环境，以后想升级或者换版本，直接换镜像就行。这是本地环境很难给到的体验。
1.2 服务器配置怎么选
我实际测试下来，OpenClaw本身是一个偏中轻量级的服务，核心消耗在两部分：一部分是OpenClaw进程本身，一部分是它下面挂载的数据库和缓存组件。如果你只是个人使用，一台2核4G内存的服务器完全够用，硬盘建议40G起步，因为系统、Docker镜像、日志都会占用空间，4G内存其实在运行容器后还会剩不少余量。
操作系统我推荐Ubuntu 22.04 LTS，原因是它对Docker的支持最省心，社区资料也多，真遇到问题搜一下基本都有答案。CentOS不是不行，但有些新版本的Docker依赖库在CentOS上需要额外处理，折腾起来没必要。服务器位置选一个离你近的区域就行，延迟会有差异，但OpenClaw本身调用大模型API的延迟才是大头。
域名和SSL的问题也要提前想。如果你只是自己通过API调试，直接用服务器IP加端口也没问题。但如果后面想让OpenClaw接入企业微信、钉钉这类有回调地址要求的平台，那就必须要有一个域名，并且配置好SSL证书。域名不贵，几十块一年，建议提前准备好。
2. 环境准备：装好Docker和配套工具
2.1 连接服务器并更新系统
拿到服务器之后，第一步就是用SSH连上去。Windows用户可以用系统自带的终端或者装一个流行的SSH客户端，macOS和Linux用户直接终端里输命令就行。连接命令长这样：
ssh root@你的服务器IP这里要提醒一下，很多云厂商默认不允许直接用root登录，或者只允许密钥登录，你拿到服务器后先按厂商的文档把登录方式配好。如果用了密钥，SSH命令加上-i指定私钥文件即可。
连上之后，先把系统软件源更新到最新，避免因为系统包版本太老导致后面装Docker出问题：
apt update && apt upgrade -y这个过程可能需要几分钟，取决于你的服务器带宽。更新完成后，顺手装几个基础工具，后面会用到：
apt install -y curl git vimcurl用于下载文件，git用于拉取代码，vim用于编辑配置文件。这三样基本是标配。
2.2 安装Docker和Docker Compose
现在装Docker，官方推荐用一键脚本方式，不过这个脚本在国内服务器上有时会因为网络问题失败。我实测比较好用的方法是先配置Docker的软件源，然后再安装。以Ubuntu 22.04为例：
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add - echo "deb [arch=amd64] https://download.docker.com/linux/ubuntu jammy stable" > /etc/apt/sources.list.d/docker.list apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后，验证一下：
docker --version docker compose version我用的这套方式会直接把docker compose插件装好，不需要再单独去下二进制文件。装完后把Docker设为开机自启：
systemctl enable docker systemctl start docker这里有个细节：默认情况下，使用Docker命令需要root权限。如果你不想每次敲命令都加sudo，可以把当前用户加入docker用户组：
usermod -aG docker $USER然后重新登录一下SSH，让用户组生效。这一步虽然不影响部署，但能让你后续操作舒服很多。
3. 获取OpenClaw项目并完成基础配置
3.1 拉取项目代码
OpenClaw的代码是托管在公开代码仓库里的，先用git把它克隆到服务器的/opt目录下，这样方便统一管理：
cd /opt git clone https://example.com/openclaw/openclaw.git cd openclaw注意，实际仓库地址以你拿到的项目页面为准。拉取完成后，看一下目录结构：
ls -la你会看到里面包含docker-compose.yml、.env.example、config等文件和目录。这说明项目本身已经为Docker部署做足了准备，我们后面要做的就是复制配置、填参数、启动。
3.2 配置环境变量
OpenClaw运行时需要读取一堆环境变量，包括大模型API的密钥、模型名称、服务端口等。项目里一般会给一个示例配置，叫.env.example，我们把它复制一份成真正生效的.env：
cp .env.example .env vim .env打开文件后，主要关注这几个配置项：
API_KEY：这是你调用大模型服务时用的密钥，去对应的模型服务商后台创建一个，保存好。MODEL_NAME：OpenClaw核心逻辑依赖的模型名称，不同服务商有不同叫法，填你开通的模型版本就行。OPENCLAW_PORT：OpenClaw对外提供服务的端口，默认是8080，如果这个端口被占用了，改成别的。TIMEZONE：建议改成Asia/Shanghai，这样日志里的时间戳看起来才舒服。DB_PASSWORD：如果项目依赖数据库服务，这个就是数据库的密码，务必设一个强密码。
修改完保存退出。这里有个容易踩的坑：.env文件里的值不要加引号，尤其是密钥和密码，加了引号可能导致服务启动时把引号也当成值的一部分。我第一次部署时就犯过这个错，结果日志里一直报认证失败，排查了半天才发现是引号的问题。
3.3 检查端口和防火墙
在启动之前，先确认一下服务器内部端口占用情况。比如你想用8080端口，先执行：
netstat -tlnp | grep 8080如果没有任何输出，说明端口空闲。如果有输出，说明已经有别的进程占了，你需要在.env里改一个端口，或者停掉占用进程。
另外，很多云厂商在服务器外部还有一层“安全组”策略，就算系统内部放行了端口，外部访问依然会被安全组挡住。你需要在云厂商的控制台里，找到这台服务器的安全组规则，把对应的端口（比如8080）加进去，来源IP建议先设成你自己的公网IP，这样更安全。
如果服务器本身开启了防火墙，也要放行端口：
apt install -y ufw ufw allow 8080/tcp ufw enable注意：如果你是通过SSH连接的，务必先放行SSH端口（一般是22），再启用ufw，不然SSH连接会直接被切断。这是很多新手栽过的跟头。
4. 使用Docker Compose启动OpenClaw
4.1 启动服务全过程
配置完成后，直接用Docker Compose把整套服务拉起来。在项目根目录下执行：
docker compose up -d第一次执行会自动拉取所有依赖镜像，包括OpenClaw主镜像、数据库镜像、消息队列镜像等，耗时取决于你的服务器带宽和镜像大小，通常在5到15分钟。耐心等待，看到类似Creating openclaw ... done的输出就说明启动成功了。
然后查看所有容器的运行状态：
docker compose ps正常情况下，每个服务的STATUS列应该显示Up。如果看到某个服务Restarting，多半是配置有问题，往下看日志排查：
docker compose logs -f --tail=200日志会实时刷出来，重点关注有没有error、exception、failed之类的关键词。
4.2 验证服务是否正常
服务起来之后，怎么确定它真的在正常工作？最简单的方式是测试它的接口。假设OpenClaw监听在8080端口，在服务器本机执行：
curl http://localhost:8080/health如果返回一段JSON，里面包含status: ok或者类似字段，说明主服务已经跑起来了。
更完整的验证方式是调用OpenClaw的创建对话接口。绝大多数智能体框架都会提供/v1/chat/completions风格的API，我们用curl模拟一次请求：
curl -X POST http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的API_KEY" \ -d '{"model": "你的模型名", "messages": [{"role": "user", "content": "你好，请回复收到"}]}'如果返回的内容里有choices字段，里面带上了模型的回复，那恭喜你，部署已经成功了。这时候你就可以在代码里把http://你的服务器IP:8080当做一个本地版的大模型网关来使用。
最让我意外的是，OpenClaw除了API，还会在本地起一个简单的管理后台，地址就是同一端口的根路径。用浏览器打开http://你的服务器IP:8080，能看到一个简洁的页面，在那里可以直观地查看请求记录、模型调用次数和日志。个人使用的话，这个后台非常够用。
5. 部署过程中最常见的几个坑
5.1 容器一直重启
如果你发现某个容器一直处于Restarting状态，90%的可能性是环境变量配错了。优先去查这条日志：
docker compose logs {容器名}常见的错误有这几种：
- 模型名称填错了，服务启动时验证模型不存在就直接退出。
- API密钥没填对，导致初始化认证失败。
.env文件里某个选项漏填，程序读到一个空值。
还有一种情况是数据库容器比主服务启动得慢，主服务连不上数据库就会反复重启。这时候不用慌，先把所有容器停掉，再重新启动一次，让它们在依赖关系上重新排个序：
docker compose down docker compose up -d如果还是不行，就手动把数据库容器先启动，等它就绪后再启动主服务容器，这样定位问题会更快。
5.2 外网访问不了服务
服务在服务器本机curl通了，但浏览器或者外部程序就是连不上。这个问题听起来简单，实际上有三层“门禁”需要依次检查：
第一层，服务器系统防火墙有没有放行端口。执行ufw status看看规则。第二层，云厂商的安全组有没有加上入方向规则。第三层，如果用了域名，检查域名解析是否指向了服务器IP。
我之前遇到过一个特别隐蔽的问题：安全组只放行了IPv4的端口，而我自己测试时用了IPv6地址的CDN，结果请求在边缘节点就被挡了。建议直接先用IP测试，通了之后再套域名和SSL，这样能少很多干扰因素。
5.3 请求模型API超时
OpenClaw启动正常，但一发消息就等很久，最后提示超时。这个问题多半是网络链路导致的。OpenClaw主服务所在的机器如果不能稳定访问大模型API的服务器，那么每次请求都会卡在等待响应上。
判断方法很简单，在服务器上直接用curl请求一下模型的API地址，看看耗时：
curl -o /dev/null -s -w "time_total: %{time_total}s\n" https://api.example.com/v1/models如果这个耗时就很高，那问题不在OpenClaw，而在服务器到模型服务商之间的网络质量。常规解法是检查服务器所在地是否离模型服务节点太远，或者考虑把OpenClaw迁移到离模型服务更近的区域。这个说白了就是网络路由问题，换区域往往立竿见影。
6. 部署完成后的安全加固
6.1 给OpenClaw加一层访问认证
OpenClaw默认会读取环境变量里的API_KEY来做请求认证，也就是说，你调用接口时必须带着正确的密钥，否则会被拒绝。但有的人觉得本地调试麻烦，就把认证关掉了，这在云服务器上是非常危险的行为。你的服务器一旦暴露在公网，立刻会有扫描程序来探测端口，如果发现一个没有认证的服务，马上就会被滥用，到时候你的模型账户可能会被刷爆。
所以务必确认.env里的AUTH_ENABLED是true，并且把API_KEY设成足够复杂的值。我习惯用一段32位以上的随机字符串，生成方式很简单：
openssl rand -hex 16把这个输出值复制到API_KEY字段里就行。
6.2 修改默认端口和限制来源IP
端口默认是8080，所有人都知道。为了减少被扫描到的概率，建议把端口改成一个不常见的端口，比如18080或者28080。这不能带来绝对安全，但确实能过滤掉很多自动化扫描脚本。
如果你确定只有自己的电脑会调用这个服务，那么更狠一点的做法是在安全组里把来源IP设置为你的家庭或办公网络IP。这样其他任何IP都连不上这个端口，基本就没什么暴露风险了。不过要注意，如果你的公网IP是动态的，隔一段时间IP变了，就需要去控制台更新规则，这点要自己权衡。
6.3 配置Docker自动重启和日志清理
服务器难免会重启，我们希望OpenClaw能跟着自动起来。Docker Compose默认在Docker服务启动时会自动拉起设置了restart: always策略的容器。你可以在项目的docker-compose.yml里确认一下，如果没有这个配置，自己加一行：
services: openclaw: restart: always改完之后需要重建容器让配置生效：
docker compose up -d --force-recreate另外，容器跑久了日志文件会越来越大，如果不控制，硬盘很容易被写满。建议在/etc/docker/daemon.json里配置日志轮转：
{ "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "3" } }保存后重启Docker服务：
systemctl restart docker这样每个容器的日志最多只保留3个50MB的文件，不会无限制膨胀。这个配置我建议在部署之初就做好，等日志真把磁盘占满再处理就有点被动了。
7. 实用技巧和扩展建议
7.1 用systemd定时任务实现无人值守
OpenClaw跑起来之后，最大的价值就在于能定时执行任务。比如每天早上9点让智能体自动拉取某个数据源的最新内容，处理完之后通过Webhook推送到群里。这个操作不需要额外写定时任务框架，直接借助系统的cron就行。
先写一个脚本，比如/opt/openclaw/scripts/daily_task.sh，脚本里用curl调用OpenClaw的API，把你要执行的指令作为消息发过去：
#!/bin/bash curl -X POST http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的API_KEY" \ -d '{"model": "你的模型名", "messages": [{"role": "user", "content": "请执行每日数据汇总任务"}]}'然后给脚本加执行权限，并把定时任务写进去：
chmod +x /opt/openclaw/scripts/daily_task.sh crontab -e在打开的编辑器里加入：
0 9 * * * /opt/openclaw/scripts/daily_task.sh >> /var/log/openclaw_daily.log 2>&1这样每天早上9点，系统就会自动调用OpenClaw执行任务。日志会写到指定文件里，方便事后检查。就我个人的使用经验来说，这种稳定运行、定时触发的场景，才是自托管智能体最舒服的打开方式。
7.2 数据备份策略
OpenClaw用到的数据库里会保存历史对话记录、知识库内容、任务状态等信息。这些数据一旦丢失，相当于整个服务的记忆归零。所以我强烈建议做每日备份。
备份最省事的办法是把整个docker compose项目目录打压缩包：
tar -czf openclaw_backup_$(date +%Y%m%d).tar.gz /opt/openclaw再加一条cron定时任务，每天凌晨3点执行一次。如果你用的是对象存储，还可以把这个压缩包同步到云端，这样即使服务器本身出现问题，数据也还在。实际测试下来，整个备份过程开销很小，对系统性能几乎没影响。
7.3 后续版本升级
OpenClaw项目迭代速度不慢，隔一段时间就会发布新版本。升级的时候不要直接改文件，按这个顺序操作最稳：
cd /opt/openclaw git pull docker compose down docker compose up -d --build升级前记得先备份数据。如果升级后发现异常，可以用git log查看最近一次提交，再用git checkout切回旧版本，基本能解决大部分兼容问题。我经历过几次升级，只要数据备份做好，没遇到过无法回退的情况。
最后一点个人体会
我从第一次部署OpenClaw到现在，最大的感触是：这类智能体框架的门槛已经降得很低了，真正的难点不在命令，而在理解它运行的整个链路。你只要搞明白“环境变量怎么传”“端口怎么放行”“日志怎么看”这三件事，任何类似的项目到了你手里，都能很快跑起来。
最后再分享一个小技巧：部署完成后，把.env文件单独加密存一份，记下你修改过的每个变量。半年后你再回来看这个项目，或者换一台服务器重新部署，这份记录能帮你省下大量回忆时间。我自己就用一个普通的加密压缩包存着，需要时解压出来直接照着填，非常省心。
