OpenClaw部署实战：从阿里云到Windows本地，一分钟跑通AI Agent

如果你最近在折腾AI Agent，大概率已经听到过OpenClaw这个名字，它的前身代号叫Clawdbot，一个开源的多通道AI助理框架。简单说，它就是给你一个常驻后台的“大脑外壳”，可以把飞书、钉钉、Teams这些IM通道全部统一接进来，收到消息之后自动调用大模型（通义千问、DeepSeek、Ollama本地模型都行），再把结果回传。很多人第一反应是：这玩意儿要部署在服务器上，还得配通道配模型，听起来就劝退。其实真到了2026年，OpenClaw的部署已经比两年前简单太多了：一台阿里云轻量服务器，提前装好Docker，跑一条docker run命令，1分钟之内容器就能起来；Windows本地搭建更适合零成本试水，装个Docker Desktop或WSL2，同样几分钟搞定。这篇文章就把这两种场景拆开揉碎讲，安全组怎么配、session file locked这种报错怎么查，我都会写清楚，适合刚接触AI Agent、又不想啃英文文档的开发者。下面按我实际跑通过的路子来。

1. 方案选型与整体拆解：先想清楚再动手

1.1 OpenClaw到底是个什么东西

可以先理解成一个“消息路由网关 + 插件管理器”。它本身不带大模型，也不绑定某个IM平台，而是把“接收消息、调模型、返回结果”这条链路做成了一套标准插件机制。任何IM平台接入后，平台侧的事件会推给OpenClaw，OpenClaw把不同平台的格式统一成内部消息结构，交给下游的Agent执行器处理。Agent执行器可以是本地Python脚本，也可以是一组Docker插件，它再去调用模型API或工具API。

为什么叫Clawdbot？早期版本确实叫Clawdbot，原因是它的架构像一只机械爪，一只手抓住多个通道，另一只手抓住各种模型后端，中间全靠一个统一调度核心。后来项目改名OpenClaw，但社区里很多人习惯继续叫Clawdbot，所以你在搜教程时看到两个名字不要懵，指的是同一个东西。

我用一个生活化的类比：OpenClaw就像公司前台。用户通过飞书、钉钉这些“电话线”打进来，前台按规则转给对应“业务部门”（Agent），业务部门背后干活的是“员工”（大模型API或本地模型），最后前台再把结果回复给用户。这个类比基本就能解释OpenClaw的所有核心设计：通道可插拔、Agent可编排、模型可替换。

1.2 阿里云路线和Windows本地路线怎么选

这是我被问得最多的问题。直接给结论：如果你要跑正式机器人，比如团队里用的飞书机器人，选阿里云；如果你只是自己电脑上倒腾研究，选Windows本地。

两者差异我用表格列一下：

在2026年这个节点，OpenClaw已经支持了飞书、钉钉、Teams等平台的WebSocket长连接模式。这对Windows本地开发是个重大利好：不需要公网回调地址，OpenClaw主动连上IM平台的长连接即可收发消息，所以本地跑通对话链路完全没问题。

我自己的习惯是本地先用Ollama调通Agent逻辑，确认没问题之后，再把同一份配置搬到阿里云上，换成稳定的云端模型API。这样既省了反复刷API账单的时间，也避免在服务器上瞎试浪费生命。

1.3 部署前必须搞清楚的三个核心概念

动手之前，请先把下面三个词理解透，不然配置的时候一定会晕。

• 通道（Channel）：指IM平台接入层，比如飞书通道、钉钉通道。每个通道有独立的适配器。
• Agent：指消息处理单元，对应一组技能定义。比如“翻译Agent”收到消息后调翻译模型，“搜索Agent”收到消息后调搜索API。
• 模型后端（Provider）：OpenClaw支持的模型调用方式，比如OpenAI兼容接口、Ollama本地接口、阿里云百炼兼容接口。

这三个概念对应到配置里就是你填的三个部分：channels配置接入平台，agents配置消息处理逻辑，model配置模型来源。搞清楚这一点，后面所有步骤就不会乱。

2. 阿里云1分钟部署：真实前提与完整步骤

2.1 “1分钟部署”的真实前提

标题说1分钟，我得先把丑话说在前面：实测下来，1分钟指的是“容器启动时间”，不是说你从买服务器到机器人跑通只需要1分钟。整个流程包含买服务器、装Docker、配安全组、填模型APIKey、配通道回调，熟练之后全流程可以控制在10分钟以内，新手按本文一步步来30分钟也够了。所以“1分钟”不是吹牛，只是指最核心的docker run阶段。

要达成这个速度，服务器端需要满足这些前提：

• 一台阿里云ECS，推荐2核2G起步，系统用Ubuntu 22.04或Debian 12。轻量应用服务器也行，配置越高模型调用时越不容易JVM内存溢出。
• 提前装好Docker。不会装的不要慌，SSH连上机器后跑一行官方脚本就行，脚本会自动安装。
• 安全组至少要放行SSH端口（22）和OpenClaw管理端口（8080）。如果你要接IM平台的HTTPS回调，再放行443。
• 准备好模型API Key，比如阿里云百炼的API Key，或者DeepSeek的API Key。

2.2 安全组与服务器基础配置

安全组是阿里云的第一道防火墙，很多人部署失败都是因为安全组没放行端口，结果本地能连上Docker，但外部IM平台回调就是不通。操作路径是：阿里云控制台 -> ECS实例 -> 安全组 -> 管理规则 -> 入方向，然后添加规则。

我建议的最小放行规则是这样：

端口不是开得越多越好。我见过有人图省事直接放行0.0.0.0/0的所有端口，结果Docker容器里跑的某个服务被全网扫描爆破，最后整台服务器被重装。安全组按最小化原则配置，宁可后面再加，也不要一开始全放开。

SSH连上服务器之后，可以先执行几个基础命令确认环境：

bash复制whoami
cat /etc/os-release
docker version

看到Docker版本信息就说明环境没问题。如果docker命令找不到，就装一下：

bash复制curl -fsSL https://get.docker.com | bash
systemctl enable --now docker

这里有个容易踩的坑：国内服务器拉Docker Hub官方镜像时，速度可能会非常慢，docker pull动不动就超时。解决办法是给Docker配置阿里云容器镜像加速器。登录阿里云容器镜像服务控制台，复制你的专属加速器地址，然后修改/etc/docker/daemon.json：

json复制{
  "registry-mirrors": ["https://xxx.mirror.aliyuncs.com"]
}

改完执行重启Docker，再拉镜像就快多了。这一步在2026年依然适用。

2.3 拉镜像、跑容器：核心一分钟操作

环境准备好之后，核心命令就这三条：

bash复制docker pull openclaw/openclaw:latest

docker run -d --name openclaw \
  --restart=always \
  -p 8080:8080 \
  -e OPENCLAW_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 \
  -e OPENCLAW_API_KEY=你的APIKey \
  -e OPENCLAW_MODEL=qwen-max \
  -v openclaw_data:/data \
  openclaw/openclaw:latest

这里我先把参数逐个说清楚：

• --restart=always：让容器在服务器重启或进程崩溃后自动拉起。生产环境必须加，不然半夜机器人挂了没人知道。
• -p 8080:8080：把容器内8080端口映射到宿主机，这是OpenClaw的管理API端口。
• -e OPENCLAW_API_BASE：模型API地址。上面写的是阿里云百炼的OpenAI兼容接口。
• -e OPENCLAW_API_KEY：模型平台的API Key。注意这是敏感信息，命令行里直接写会留下shell历史记录，建议用--env-file方式传。
• -e OPENCLAW_MODEL：默认模型名。阿里云百炼上对应qwen-max。
• -v openclaw_data:/data：持久化数据目录。OpenClaw的会话、session文件、Agent配置都会存在这里，不挂载数据卷的话容器一删全没了。

跑完查看日志：

bash复制docker logs -f openclaw

正常情况下几秒到一分钟内会出现类似“OpenClaw started, listening on 0.0.0.0:8080”的日志。看到这行，容器层面的部署就成了。注意标题里的“1分钟”指的就是从这里开始容器能被正常拉起的时间。

如果你不想在命令行里明文写API Key，可以创建env文件：

bash复制cat > /opt/openclaw.env <<'EOF'
OPENCLAW_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENCLAW_API_KEY=你的APIKey
OPENCLAW_MODEL=qwen-max
EOF

然后启动时改成--env-file /opt/openclaw.env。这样文件权限设成600，只有root自己能看，安全性好很多。

2.4 接入通义千问、DeepSeek等模型API

2026年阿里云百炼平台提供了标准的OpenAI兼容接口，所以OpenClaw不需要装额外插件，直接把它当成OpenAI兼容服务配置就行。如果你的API Key是阿里云百炼的，那上面那段配置已经够用了。

如果想用DeepSeek，只需换两个环境变量：

bash复制-e OPENCLAW_API_BASE=https://api.deepseek.com/v1 \
-e OPENCLAW_API_KEY=你的DeepSeekKey \
-e OPENCLAW_MODEL=deepseek-chat

想用本地模型或别的兼容平台也同理。OpenClaw的模型接入层本身不绑定任何厂商，只要对方提供OpenAI兼容接口就能直接用。这也是我推荐用OpenClaw而不是某些封闭平台SDK的原因：换模型只改环境变量，业务代码完全不用动。

2.5 让机器人能被IM平台真正回调到

容器起来只是第一步。你要接飞书或钉钉的话，IM平台在2026年多数支持WebSocket长连接方式，本地和云端都可以不配公网回调地址。但如果你偏要用传统的Webhook回调模式（比如某些老项目），就必须在阿里云上配一个HTTPS公网地址。

最简单的做法是用nginx反向代理OpenClaw的8080端口，再用acme.sh给域名续免费SSL证书。nginx配置大致是这样：

nginx复制server {
    listen 443 ssl http2;
    server_name your.domain.com;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

这个配置里最核心的是proxy_pass http://127.0.0.1:8080，把公网443流量转给本机Docker映射出来的端口。证书部分可以从阿里云证书服务申请免费证书，也可以用acme.sh自动续期。

Nginx装好、SSL证书生效之后，在IM平台后台把回调地址填成https://your.domain.com/feishu/callback之类路径，同时把对应Token、Secret填进OpenClaw配置即可。

3. Windows本地搭建：从零到能跑通对话

3.1 本地环境准备：Docker Desktop与WSL2

Windows本地部署OpenClaw，我试过两种路子：原生二进制跑，和Docker跑。2026年官方推荐的是Docker方式，因为它把依赖和配置封装得太干净了，不用自己装一堆Python包。

第一步装Docker Desktop。安装过程中会提示启用WSL2，这是Windows的Linux子系统，Docker Desktop依赖它来跑Linux容器。安装完成后打开Docker Desktop，在设置里确认WSL2模式已经启用。

如果你完全不想用Docker，也可以直接下载OpenClaw的Windows发行版exe，解压后命令行里运行openclaw start。但这种方式我不推荐新手用，因为后续升级、切换模型版本都要手动管理，很容易出现DLL缺失或版本冲突。用Docker至少所有依赖都在镜像里，Windows系统坏了都不影响OpenClaw。

需要注意的是，Windows上拉Docker镜像同样可以用阿里云镜像加速器。Docker Desktop的配置路径是Settings -> Docker Engine，在JSON里加上registry-mirrors字段，方法和服务器上一样。改完保存后Docker Desktop会自动重启。

环境就绪后，执行：

bash复制docker pull openclaw/openclaw:latest

在Windows上拉镜像需要多花点时间，等镜像下载完成后，创建并启动容器：

bash复制docker run -d --name openclaw-local \
  -p 8080:8080 \
  -v openclaw_data:/data \
  openclaw/openclaw:latest

本地测试阶段API Key可以先不配，后面初始化配置时再填。如果你只接Ollama本地模型，连API Key都可以用占位符。

3.2 初始化配置文件与常用命令

OpenClaw启动后，首次使用建议跑初始化命令，它会生成一个基础配置文件。Windows下打开PowerShell或Windows Terminal，执行：

bash复制docker exec -it openclaw-local openclaw init

这个命令会在卷目录里生成config.yaml。你也可以直接手动编辑数据卷里的配置文件，路径一般在%USERPROFILE%\docker\volumes\openclaw_data\_data\config.yaml，取决于你的Docker Desktop卷存储位置。

一个最简配置长这样：

yaml复制model:
  provider: ollama
  base_url: http://host.docker.internal:11434/v1
  api_key: unused
  name: qwen2.5:14b

agents:
  main:
    greeting: "你好，我是OpenClaw"
    max_reply_length: 4000

这里有个Windows专属的坑：容器内部不能直接用127.0.0.1访问宿主机上的Ollama，要用host.docker.internal这个Docker Desktop提供的特殊域名。如果你在Linux服务器上这样写肯定不行，那是另外的坑。

配置文件准备好后，重启容器：

bash复制docker restart openclaw-local
docker logs -f openclaw-local

看到日志输出没有报错，说明本地核心已经跑通了。到这一步，你已经可以在浏览器打开http://localhost:8080看一下管理面板（如果镜像自带面板的话），或者直接用命令行CLI发一条测试消息。

3.3 通道Channel配置：飞书、钉钉、Teams接入思路

本地和云端的通道配置逻辑完全一样，只是网络接入方式不同。我用飞书举例，你在OpenClaw的config.yaml里加这么一段：

yaml复制channels:
  feishu:
    app_id: cli_xxxx
    app_secret: xxxx
    verify_token: xxxx
    mode: websocket

2026年OpenClaw对飞书、钉钉都默认支持WebSocket模式，这是本地开发的救命功能。你不需要公网回调地址，OpenClaw启动时会主动连飞书开放平台的WebSocket服务，机器人就能正常收发消息。Teams目前在Windows本地走WebSocket也没有问题，如果你用网关/WORKER模式则更稳，但本地调试直接WebSocket最省事。

配好之后在容器内测试某个通道是否连通：

bash复制docker exec -it openclaw-local openclaw channel test feishu

我个人实测遇到最多的问题不是配置错误，而是粗心填错了app_secret，多一个空格令牌都验不过。这类细节很难从日志里看出来，所以我建议每个通道配完后都跑一次channel test，别急着去IM里发消息。

3.4 本地模型与云端模型混用

Windows本地最舒服的玩法是接Ollama。Ollama装好后在Windows Terminal里拉一个模型：

bash复制ollama pull qwen2.5:14b
ollama serve

默认情况下Ollama会在11434端口提供OpenAI兼容接口。前面config.yaml里已经写了http://host.docker.internal:11434/v1，所以OpenClaw容器可以通过这个地址访问宿主机上的模型。

为什么要混用？本地模型跑得快但效果一般，云端模型效果好但费钱。我的方案是：平时在本地用14B模型调试Agent逻辑，验证消息解析、分片、通道回复都没问题后，把生产环境的模型Provider切到云端API。这样既不会在调试阶段烧掉几十块API费用，又能保证正式环境的质量。

OpenClaw还支持按Agent配置不同模型，也就是同一套系统里部分Agent走Ollama，部分Agent走千问。这个在config.yaml里分别指定就行：

yaml复制agents:
  translate:
    model:
      provider: dashscope
      base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
      api_key: sk-xxx
      name: qwen-max
  local_debug:
    model:
      provider: ollama
      base_url: http://host.docker.internal:11434/v1
      name: qwen2.5:14b

这种混用非常实用，翻译类任务交给强模型，内部日志整理交给本地小模型，成本和效果两头兼顾。

4. 实际部署中遇到的坑与排查实录

4.1 “agent failed before reply: session file locked (timeout 60000ms)”怎么办

这个报错我在社区里看到很多人贴过。OpenClaw为每个会话维护一个session文件，当多个进程同时想去写同一个session文件时，系统会加文件锁。如果60秒内拿不到锁，就抛这个错。出现原因基本有三类：

第一，同一份config.yaml被多个OpenClaw实例共用。比如你本地跑了一个，云服务器上又跑一个，两边数据卷挂到了同一个远端存储，这就会互相抢锁。解决办法是让每个实例使用独立的数据目录或数据卷。

第二，上一个OpenClaw进程没有正常退出，锁文件残留。Windows下尤其常见，Ctrl+C没杀干净进程，再次启动时旧进程还占着锁。用任务管理器检查有没有残留的openclaw进程，杀掉之后删除session目录里的.lock文件。

第三，文件系统不支持锁。某些网络挂载盘、samba共享目录对文件锁支持不完善，把数据目录放在这种盘上就容易出问题。解决办法是把数据卷改成纯本地路径。

排查顺序建议先查锁文件，再查多实例。在Windows本地一般是第二个原因，阿里云上一般是第一个原因。日志里打开debug模式能看得更清楚：

bash复制set OPENCLAW_LOG_LEVEL=debug
openclaw start

Linux/容器里则是：

bash复制OPENCLAW_LOG_LEVEL=debug docker logs -f openclaw

看到具体的session路径后，删除或等待超时，基本都能解决。

4.2 飞书输出容易被截断

OpenClaw默认对大模型回复没有强限制，但飞书文本消息长度是有限制的。2026年飞书普通文本消息上限大约是15330字节，超出之后消息会被截断，看起来就是回复了一半戛然而止。很多人以为是模型生成中断了，其实不是，是飞书不让发那么长。

解决方式有两种：

第一种是设置max_reply_length，让OpenClaw在生成前就限制长度。比如：

yaml复制agents:
  main:
    max_reply_length: 4000

超过长度时OpenClaw会按截断返回并附带提示。这是最简单粗暴的保底方案。

第二种是开启自动分片。在Agent配置里加：

yaml复制split_reply: true

OpenClaw会把长回复按段落拆成多条消息，依次发送到飞书。这样既保留完整内容，又不会被飞书截断。注意分片之后每条消息依然是独立的会话上下文，不要把它当成多轮对话，避免上下文错乱。

如果你用的是飞书卡片消息，限制规则又不一样。卡片消息的JSON总大小有限制，所以配置卡片模式时最好测试一下你生成的卡片内容是否在限制内。

4.3 常见问题速查表

我把实操中遇到的高频问题整理成一张表，方便你截图保存：

这些坑大多数不是OpenClaw本身的问题，而是运行环境差异导致的。先怀疑环境，再怀疑配置文件，最后再怀疑项目本身，排查效率会高很多。

4.4 排查思路：三分靠命令，七分靠日志

最后说一个通用排查心法。很多新手遇到报错第一反应是删容器重新跑，这其实是最浪费时间的方式。正确的做法是先把日志拉出来看。

OpenClaw的日志位置在不同平台不太一样。阿里云Docker容器里的日志在宿主机上可以直接用docker logs openclaw查看；Windows本地如果也是Docker方式，同样用docker logs openclaw-local。如果日志太长，可以加tail和grep过滤：

bash复制docker logs --tail 100 openclaw | grep -i error

日志文件的持久化路径则在数据卷的logs目录下。Linux服务器一般在/var/lib/docker/volumes/openclaw_data/_data/logs，Windows则类似。我的习惯是拿到报错信息后，先搜索关键词，比如session locked、timeout、401、invalid webhook，90%的问题都能在日志里找到直接线索。

还有一个实用技巧：把OpenClaw的debug日志打开，然后去IM平台手动发一条测试消息，同时终端持续刷日志。你能看到完整的事件流：消息进来、会话加载、Agent匹配、模型调用、消息返回。这五个环节哪个卡住了，日志就停在哪个环节，问题定位得非常清楚。

最后说点实际的

我自己折腾OpenClaw最深的体会是，部署本身不复杂，真正耗时间的是理解它为什么这样设计。通道、Agent、模型Provider这三个概念搞清楚了，你在阿里云和Windows之间的切换就只是换几个环境变量的问题。如果你同时管理云上和本地两套实例，千万记得给它们分不同的数据目录或者不同端口，不然session文件锁就够你折腾一晚上。最后分享一个小技巧：如果你在Windows本地用Docker跑OpenClaw，配置文件改完后别急着重启容器，先执行docker exec openclaw-local openclaw config check，这个命令会把配置里的语法错误、缺失字段一次列出来。我靠着它少踩了无数个缩进和拼写坑。OpenClaw迭代快，但底层这些使用习惯和排查思路，放哪个版本都通用。