脑袋被门夹得好痛说出来你可能不信，我去年第一次在本地装OpenClaw，光环境就折腾了一个周末。Python版本冲突、Docker Desktop在Windows上的npipe连接错误、模型API怎么都连不上……最后发现真正跑起来只需要两件事：一台干净的Linux服务器，一个能用的模型API。所以后来再有人问我“怎么安装OpenClaw”，我都直接推荐这套组合：京东云轻量应用服务器打底，阿里云百炼出模型，实测从开机到Agent回复第一条消息，两分钟左右。
这篇教程不是简单贴几步命令，而是把整套部署链路拆开讲清楚。读完你会知道OpenClaw到底是个什么东西、为什么选京东云和百炼、每一步在做什么、出问题该往哪个方向查。适合刚接触AI Agent的开发者，也适合用过Docker但不想在本地折腾环境的朋友。
1. 部署之前，先把OpenClaw、京东云和阿里云百炼这三块拼图看清
1.1 OpenClaw到底是个什么项目
OpenClaw本质上是一个能对接大模型、自动拆解并执行任务的AI Agent框架。你可以把它理解成一个“会动手的助理”：你给它一个目标，它会自己规划步骤、调用工具、整理结果，而不是像普通聊天机器人那样只输出文字。
社区里最常见的玩法是把它接入微信或飞书，当私人助理用。也有人拿它写小说、做会议纪要、定时抓取网站信息，甚至对接内部系统做自动化。它和普通对话机器人的最大区别在于“执行”二字——你说“查一下某网站今天有没有更新几个栏目”，它不只是嘴上答应，而是真的会去抓取、比对、分析，再把结论发给你。
这也是它必须部署在独立环境里的原因。OpenClaw不是一个跑完就退出的脚本，而是一个长时间运行的常驻服务，需要稳定的网络、持续的内存和可靠的模型API通道。理解了这一点，你就能明白为什么“部署”是绕不开的一步。
1.2 部署载体为什么选京东云轻量服务器
本地部署的坑，我基本上全踩过。Docker Desktop在Windows上那个npipe连接错误，第一次遇到能把人绕晕；macOS上ARM架构和x86镜像的兼容问题也时不时冒出来；更麻烦的是，家用宽带往往没有公网IP，Agent后续要接入微信、飞书这类需要回调的渠道时，本地环境根本打通不了。
云服务器解决的就是这些历史包袱。下单那一刻，你就拥有一个干净得不能再干净的Linux环境，所有依赖从零装起，不会和你本地的开发环境打架。京东云轻量应用服务器是目前门槛最低的入口之一，控制台操作直观，新用户通常还有体验活动（以官网实时活动为准），一年成本也就两三百块钱的事。
很多人会纠结要不要买GPU服务器，我直接说结论：不需要。OpenClaw本身不跑模型，它只负责调度和调用API，真正做推理的是云端的大模型服务。2核4G的轻量实例足够跑得很稳，省下的预算不如留着买模型API的token。
1.3 模型API为何选阿里云百炼
模型API的选项其实很多，OpenAI官方接口、DeepSeek官方API、各种二手中转站都会出现在搜索结果里。我最终推荐阿里云百炼，核心是三点。
第一，百炼上的模型选择足够丰富。通义千问系列对中文任务的支持很稳，qwen-plus跑日常对话性价比高，qwen-max处理复杂分析更给力；平台上还能用到DeepSeek系列模型，等于一个控制台覆盖多种需求。第二，百炼提供了OpenAI兼容的Endpoint，OpenClaw这类框架几乎不用改业务代码，把Base URL和Key填进去就能用，集成成本极低。第三，百炼的API Key走的是阿里云RAM权限体系，可以为不同项目创建独立Key，出了问题只吊销一个，不会牵连整个账号。
关于成本也可以放心。百炼对首次使用通常有免费额度，具体以控制台为准；就算按量付费，OpenClaw这类文本Agent一天跑几百条消息、几十万token，成本也就是几毛钱到几块钱的量级。比起自己折腾GPU推理，这个投入产出比高太多了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 准备工作：一台云主机、一串API Key、一条通畅的SSH通道
2.1 京东云主机的选择与系统配置建议
打开京东云控制台，找到轻量应用服务器的购买入口。地区选离你最近的就行，华北、华东都可以。套餐直接选2核4G，这是我在多台机器上试出来的“甜点配置”——跑OpenClaw加日常Agent任务完全够用，内存再小的话，遇到长任务容易触发OOM。
系统镜像这里建议选Ubuntu 22.04，理由很简单：Docker安装源最省事，社区的教程和脚本也基本都是基于这个版本写的。CentOS虽然也能跑，但你会发现很多命令、源配置都要额外适配，没必要给自己找麻烦。
带宽选项容易被忽略。轻量服务器默认带宽通常不大，1M到3M之间。OpenClaw本身以文本交互为主，对带宽不敏感，但如果你打算让Agent定时抓取网页、处理图片，建议一步到位选3M或更高，省得后面再升级。
下单时还有个选择：密钥登录还是密码登录。我的建议是直接用密钥对，因为云服务器从创建第一天起就暴露在公网，暴力破解的扫描请求基本没停过。密钥登录能直接杜绝这类风险。如果你手里还没有密钥，京东云控制台可以一键生成，下载私钥保存好，后面SSH登录时指定这个私钥文件就行。
2.2 阿里云百炼开通与API Key申请，以及几个安全习惯
登录阿里云百炼控制台，第一次进入会提示开通服务，这个流程是免费的。开通之后，左侧菜单里找到“API-KEY管理”，点“创建我的API-KEY”，系统会生成一串以sk-开头的密钥。
这里有两个习惯建议从一开始就养好。第一，创建后立刻把Key复制到本地密码管理器，因为百炼的Key只在创建时完整显示一次，刷新页面就再也看不到了。第二，给Key加上备注，比如“OpenClaw-prod”，别等三个月后面对一串乱码猜这是哪个项目在用的。
还有一个进阶操作：如果你的阿里云账号还有其他业务，建议为OpenClaw单独创建一个RAM子账号，只授予百炼的调用权限，再把API Key创建在子账号下。这样即使Key不小心泄露，影响面也被限制在百炼服务内，不会波及账号里的其他云资源。个人使用可以不搞这么复杂，但这个思路建议了解一下。
2.3 首次SSH登录与安全组设置
服务器创建完成后，你会拿到公网IP和登录凭据。如果你对Linux命令不熟悉，可以先在京东云控制台用网页版终端登录一次，验证环境是否正常。
本地SSH连接也很简单。Windows用户可以用Termius或者Windows Terminal自带的ssh命令，macOS用户直接用终端。连接命令格式是ssh root@你的服务器IP，如果用了密钥对，再加上-i参数指定私钥文件路径。第一次连接会提示确认指纹，输入yes回车，进入命令行就算成功。
安全组这块特别说一下。京东云默认的安全组规则通常只放行22端口（SSH）和少量常用端口，OpenClaw的Control UI端口默认不开放。这里的关键原则是：管理界面不要裸奔到公网。最安全的方式是Control UI端口只允许来自你本地IP的访问，或者干脆不开安全组端口，用SSH隧道访问。SSH隧道命令也不复杂：ssh -L 8080:localhost:8080 root@你的服务器IP，执行后在你本地浏览器访问http://localhost:8080，就把远程的Web界面安全地映射到本地了。
3. 京东云上2分钟拉起OpenClaw：从Docker预检到首次启动
3.1 预检Docker环境，避免Compose版本不一致
OpenClaw官方推荐用Docker Compose方式部署，所以第一步是确认服务器上有没有可用的Docker环境。
我搬过不少次环境，这里最有必要提醒的是Compose版本问题。现在官方都推荐用docker compose（v2，没有横杠），而很多老教程还在教docker-compose（v1）。两者的配置文件语法基本兼容，但v1版本在个别参数上有差异，而且在新系统上经常遇到“命令找不到”的尴尬。装好之后先跑一下docker compose version确认是v2版本，这一步花不了十秒钟，能省下后面半小时的排查时间。
至于安装方式，用Ubuntu官方源就行，不需要装Docker Desktop那种带图形界面的东西。安装完成后，把当前用户加入docker组，否则每次执行docker命令都要加sudo，很影响操作体验。
3.2 编写Compose配置与环境变量文件
预检完Docker，就在服务器上建一个工作目录，比如/opt/openclaw，然后进入这个目录编写两个文件：docker-compose.yml和.env。
Compose文件的核心作用是把OpenClaw容器跑起来，同时定义数据卷、端口映射、环境变量和日志策略。下面是一个通用的模板，具体版本号、端口、环境变量名请以你下载的OpenClaw官方仓库README为准，不同版本之间确实会有小差异：
yaml复制services:
openclaw:
image: openclaw/openclaw:latest # 以官方仓库实际镜像名为准
container_name: openclaw
restart: unless-stopped
env_file: .env
volumes:
- ./data:/app/data
ports:
- "8080:8080"
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
这里有两个容易犯错的点。
第一个是volumes。一定要把数据目录挂载出来，否则以后升级容器、重建容器，对话记录和配置就全丢了。只要数据在宿主机目录里，容器随便删重建都没关系。
第二个是密钥的存放位置。很多教程把API Key直接写在compose文件里，然后整个目录被传阅、提交到Git仓库，这是非常危险的做法。正确姿势是单独建一个.env文件存放密钥，由compose的env_file字段自动加载。记住要在.gitignore里排除.env，这个文件绝不能进版本库。
3.3 启动镜像、查看日志并确认Control UI可访问
文件准备好后，执行docker compose up -d启动服务。第一次启动会拉取镜像，耗时取决于网络情况，可能一两分钟；镜像拉取完成之后，以后的启动基本是秒级。
启动后执行docker compose ps查看容器状态，看到running说明进程活着。接着执行docker compose logs -f看日志，如果出现类似Control UI started或listening on port的输出，就说明Web界面已经起来了。
接下来在浏览器访问Control UI。如果你按照前面说的用SSH隧道，就访问http://localhost:8080；如果你配置了云主机公网IP加安全组，就访问http://服务器IP:8080。看到Web管理界面，部署这一关就算过了。
但先别急着高兴。Control UI能打开，只代表服务在运行，不代表Agent能正常回复消息。你还需要把模型通道打通——也就是下一章要说的阿里云百炼API配置。这也是新手最容易卡壳的地方，我甚至见过有人在这步卡了整整两天，最后发现只是模型名写错了一个字母。
4. 阿里云百炼API接入：模型选型、参数对照与连通性验证
4.1 模型选择：qwen-plus、qwen-max还是DeepSeek
在阿里云百炼控制台，你能看到一批可用的模型，选哪个完全取决于用途。
日常对话、工具调用、写小说这类任务，qwen-plus是我最常用的选择。它的响应速度快，价格便宜，中文理解能力也在线，跑Agent的日常工作流非常合适。如果你需要更强的推理能力，比如复杂的多步任务拆解、长文本分析，qwen-max更合适，它的逻辑性和指令遵循能力都更好，当然价格也更高一档。
百炼上也能用到DeepSeek系列模型，代码能力突出，不少技术类Agent任务表现很好。但这里有个高频坑：不同模型在百炼上的“模型名”不一定和社区里流传的简写一致。比如你可能看到的是deepseek-v3，也可能是更新一点的版本号，必须以百炼控制台当前显示的模型名为准。名字写不对，其他配置再正确也是白搭。
选好模型后，建议顺手在控制台看一下这个模型的具体计费方式和免费额度。百炼对新用户通常有一定量免费token，能用一段时间。反正我的做法是：先跑通流程，再观察一两天的实际消耗，确认成本可控后再放心用。
4.2 Base URL、API Key、模型名三项配置逐个对齐
接入百炼API，本质上就是要告诉OpenClaw三件事：请求发到哪里、用什么身份、调哪个模型。
- Base URL：阿里云百炼OpenAI兼容模式的地址，通常形如
https://dashscope.aliyuncs.com/compatible-mode/v1。这个地址就是OpenClaw去发请求的Endpoint。 - API Key：上一章创建的
sk-开头的字符串。 - 模型名：控制台里显示的完整名称，比如
qwen-plus、qwen-max、deepseek-v3这样的精确字符串。
在OpenClaw里，这三个值的配置入口通常是Control UI的设置页面，或者.env环境变量。具体环境变量名在不同版本里略有差别，常见的是MODEL_API_KEY、MODEL_BASE_URL、MODEL_NAME这一类。如果你用的是官方Docker镜像，建议通过.env注入，而不是直接改容器内部文件，否则下次重建容器配置就丢了。
这里我多说一句：模型名一定要“一字不差”地复制。有些版本的百炼控制台会显示qwen-plus，有些可能带有版本后缀。我曾经因为在配置里把deepseek-v3简写成了deepseek，浪费了一整个下午。这不是技术难题，纯粹是细节问题，但真实部署中恰巧这类问题占比最高。
4.3 先用curl验证百炼API，再让OpenClaw接管
很多人在OpenClaw里配置完API后直接发消息测试，报错了就一脸懵。其实有一个很有效的排查手段：先用curl直接测百炼API，把“API问题”和“OpenClaw部署问题”这两件事彻底切分开。
在服务器命令行执行一个最小请求，格式大致是向Base URL发一个chat/completions请求，Headers里带上Authorization和Content-Type，Body里指定model和messages。如果返回的JSON里包含模型生成的文本，就说明API Key、模型名、网络路径全部正常——问题只可能在OpenClaw的配置映射上。
如果curl返回401，就是Key不对或权限不足；返回404，多半是Base URL或路径拼错了；返回529，说明服务端过载，跟你的配置无关；返回unknown model，那模型名肯定没写对。每条错误都有自己的含义，学会看返回信息，比瞎猜配置高效得多。这个“先边界后内部”的排查思路，不只是OpenClaw，做其他Agent项目、API集成项目也都通用。
5. 高频报错排查：529过载、模型名不识别、Control UI启动失败
5.1 529 overloaded：先忍住别重启，按这三步排查
api error: 529 overloaded. this is a server-side issue, usually temporary这个报错，混OpenClaw社区的人应该都见过。官方已经写得很明白：这是服务端过载，通常是暂时的。也就是说，它大概率不是你的配置问题。
但“大概率不是”并不能让用户安心。我的建议是分三步处理。
第一步，确认是所有请求都报529，还是只有部分请求报。如果所有请求都报，那基本可以断定是模型服务方整体过载，这时候要做的就是等等再试，或者临时切换到另一个模型顶上。如果只是部分请求报529，可能是你的Agent在短时间内发了大量请求触发了限流，检查一下是不是有循环任务在疯狂调用。
第二步，观察持续时长。过载一般是几分钟到半小时级别，如果持续一小时以上还在报，去百炼控制台看服务公告，可能是有故障处理中。
第三步，也是最容易犯的错：不要反复重启OpenClaw容器。平台侧过载时，重启容器没有任何意义，反而把日志刷得乱七八糟，等故障恢复后你想查什么都找不到重点。我见过有朋友半小时内重启了十几次，最后发现过载恢复后服务自己就正常了。
5.2 unknown model: deepseek：模型名单词和版本号必须精确匹配
unknown model: deepseek这类报错，在热词搜索结果里频繁出现，典型的用户配置是：在OpenClaw里填了deepseek，百炼平台却表示查无此模型。
原因我在前面提过：模型名不匹配。百炼上的模型名通常带有版本号或具体产品名，比如deepseek-v3、qwen-plus，不会只是一个光秃秃的deepseek或qwen。你填的字符串必须是控制台模型列表里显示的完整名称。
修正方法也很简单：打开百炼控制台，找到模型列表页，把准确的模型名复制粘贴到OpenClaw的配置里。别手动敲，别凭记忆，复制粘贴是最稳的。
还有一个延伸场景：如果你在OpenClaw里配置了模型路由，比如某些任务走qwen-plus，某些任务走deepseek，务必要把每个路由项的模型名都核对一遍。我遇到过主模型配置正确、正常回复，但特定任务一直报unknown model的情况，最后发现就是路由表里某个模型名简写了。
5.3 Control UI did not start：日志-端口-配置的固定排查链路
openclaw control ui did not start这个报错在热词里也出现了，排查起来其实有规律可循，我总结了一条固定链路：先看日志，再测端口，最后查配置。
先看日志。执行docker compose logs查看启动日志，定位到报错的具体行。绝大多数情况下，日志会告诉你真正的原因，比如端口被占用、权限不足、某个依赖没加载。这一步往往就能解决问题。
如果日志里看不出端倪，就测端口。在服务器上执行netstat -tlnp | grep 8080（换成你实际用的端口），看看端口有没有被监听。如果端口没监听，说明服务没起来；如果端口被监听但浏览器访问不了，那就可能是配置问题。
配置问题最常见的有两个。一是Control UI实际绑定在127.0.0.1上，只允许本机访问，从公网自然连不上；改成0.0.0.0可以外部访问，但前面强调过，直接暴露公网有安全风险，建议还是用SSH隧道。二是端口映射不一致，容器内监听的端口和compose里映射到宿主机的外网端口没对齐。
按日志-端口-配置这个顺序排查，Control UI的问题基本都能在十分钟内定位。我见过太多人一上来就重装、重置，折腾半天发现只是端口没映射对，这种无用功真没必要。
6. 部署完成之后：日志轮转、数据备份与几个日常使用技巧
6.1 日志轮转配置，别让Docker日志撑爆系统盘
OpenClaw跑起来之后，长期稳定运行要面对的最大敌人不是崩溃，而是日志。容器持续输出日志，如果不加限制，一个月下来可能吃掉几个GB磁盘。云服务器的系统盘通常只有40G到60G，日志把磁盘写满之后，连SSH登录都可能失败，那才是真麻烦。
解决办法是配置Docker的日志轮转。前面那个compose模板里已经加了logging字段，设置了max-size: 10m和max-file: 3，意思是单个日志文件最大10MB，最多保留3个文件，超过就自动清理。这个配置强烈建议加上，它可能救你于水火。
如果你已经有正在运行的容器，可以执行docker compose up -d --force-recreate让日志配置生效，或者直接编辑compose文件后重启服务。数据卷里的数据不会因为这个操作丢失。
6.2 数据备份和安全加固的基本操作
OpenClaw的数据——对话记录、任务配置、自动化规则——通常都存在数据卷对应的宿主机目录里。备份最简单的方式就是把整个工作目录打包，比如/opt/openclaw目录。
我的习惯是写一个简单的shell脚本，用tar把目录打成压缩包，再配合crontab每天凌晨自动执行一次，只保留最近7天的备份。如果机器上有对象存储工具，还可以把压缩包再传到云端异地保存。个人使用不强制，但养成习惯后，哪天误删了数据你会感谢自己的。
安全加固方面，再把几件小事说透。SSH建议改成密钥登录并禁用root密码登录，这个在京东云控制台和服务器配置里都能设置；API Key建议每三个月轮换一次，轮换时在百炼控制台创建新Key、更新OpenClaw配置、确认正常后再吊销旧Key；安全组规则收得越紧越好，凡是能用SSH隧道解决的管理入口，都不要直接开公网端口。
6.3 几个让OpenClaw更好用的日常小技巧
部署完之后，分享几个我实际使用过程中沉淀下来的技巧。
第一个技巧是给重复任务做固定指令模板。OpenClaw这类Agent很适合跑固定流程，比如“每天早上九点抓取某个网站的热榜，整理前十条发到我的飞书机器人”。把这类提示词做成模板，存在配置里或者对话记录里，每天只需要触发一下就行，它能自动完成整条链路。用得越久，你觉得它能做的事就越多。
第二个技巧是调大模型请求的超时时间。OpenClaw处理长任务——写小说、多步推理、长文本分析——时，模型响应时间比普通对话长很多，默认超时限制可能不够用，导致请求被中断。具体数值可以根据你的使用场景调整，我的习惯是至少设置到120秒以上，宁可多等几秒，也不要频繁断掉。
第三个技巧是镜像升级要谨慎。OpenClaw迭代速度很快，新版本通常会修bug、加功能，但升级也可能带来配置格式的变化。我在正式环境里的策略是：先在另一台临时机器上拉新版本镜像，跑通一次完整任务，确认没有兼容性问题后，再回到主力机器上执行升级。虽然看起来多了一步，但能避免“升完级全部配置失效”的尴尬。
写这篇教程的时候，我把整个部署流程又从头到尾走了一遍，确认每个步骤都还是通的。OpenClaw这类工具最难的地方从来不是安装本身，而是装完之后如何稳定运行、如何和你自己的工作流融合。这篇把地基给你打好了，剩下的玩法，就看你自己怎么拓展了。如果在部署过程中遇到这篇没提到的报错，欢迎在评论区把完整日志贴出来——带日志的提问，解决问题最快。