前阵子想把手上的自动化任务和聊天机器人打通正好看到 OpenClaw 这个项目。它把多平台机器人、消息驱动任务、大模型调用全封装到一起最吸引我的是可以直接对接飞书机器人和 Qwen 大模型。我一开始图省事直接在 Windows 上跑结果环境依赖一团糟Python 包冲突、后台常驻不稳、日志乱跳第一天就这么折腾掉了。后来果断换成 WSL2 Docker 的组合花了两个晚上总算稳定跑通。这篇就把我从零开始到最终跑通的全过程写出来包括 WSL2 怎么装、Docker 怎么配、OpenClaw 怎么部署、飞书机器人怎么接、Qwen 模型怎么调用以及每个环节我踩过的坑和对应的排查方法。所有步骤都尽量写得细适合刚接触 WSL/Docker、想在 Windows 上部署自托管机器人服务的朋友。如果你已经有一定基础也可以直接跳到第 6 节看常见问题速查表。1. 为什么选 WSL Docker 这套组合1.1 先搞清楚 WSL2 和 Docker 分别解决什么问题WSL2 是 Windows 下的一个轻量 Linux 子系统它不是虚拟机但内部跑的是一个完整 Linux 内核兼容性远好于第一代 WSL。我个人的理解是Windows 是宿主机WSL2 是一个随叫随到的 Linux 环境启动快、内存动态占用跟 Windows 文件系统能互访这对开发调试非常友好。Docker 解决的问题是“环境一致性”。OpenClaw 这类服务依赖一堆系统库、Python 包和运行时配置如果直接装在系统里很容易被系统升级或者其他软件搞坏。用 Docker 镜像把服务、配置、依赖全部打包只要镜像没变换到任何机器上跑行为都一致。我后两次重装环境基本就是启动容器不再重新折腾依赖非常省事。1.2 为什么不用整套虚拟机也不用纯 Windows 运行有人会问用 VMware/Hyper-V 开个完整虚拟机不是更接近 Linux 服务器吗确实更像但完整虚拟机的问题是开机慢、占内存、维护成本高。WSL2 足够跑多数容器化服务内存管理更灵活还能直接访问 Windows 磁盘文件。对比起来WSL2 更适合个人开发机和常驻型小服务。纯 Windows 直接跑 OpenClaw 也不是完全不行前提是你把所有依赖都处理好还要考虑服务开机自启、进程守护、权限问题。Windows 下 Python 环境的坑我踩过太多次比如常见的pydantic版本冲突、cryptography编译失败、控制台编码错误这些在 WSL2 Docker 里几乎不会再遇到。对技术人来说能用容器解决的问题不值得花时间跟本机环境较劲。提示这套组合适合开发调试、个人自动化、小团队试用。如果要做高可用生产部署还是建议放到云服务器上跑道理一样但运维方式不同。2. 环境准备把 WSL2 和 Docker 装到能用为止2.1 安装 WSL2 并切换到 UbuntuWindows 10 版本 2004 以上或 Windows 11 都可以用wsl命令安装。我建议直接装 Ubuntu 22.04理由很实际软件源更新及时和 Docker 官方文档里的示例一致遇到问题搜资料也方便。在管理员 PowerShell 里执行wsl --install -d Ubuntu-22.04如果wsl --install提示找不到命令说明系统版本比较旧需要手动启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个功能再重启。完成后继续设置 WSL 版本wsl --set-version Ubuntu-22.04 2检查版本wsl -l -v看到版本列是 2 就行。WSL1 和 WSL2 差异很大WSL1 不是跑真内核对 Docker 支持不完整所以必须用 WSL2。2.2 Docker 方案选择WSL 内装 Docker Engine 还是 Docker Desktop这里有两条路。第一条是安装 Docker Desktop然后在设置里勾选 WSL Integration让 Docker 指令直接在 WSL 里使用。第二条是不装 Desktop在 WSL2 内部安装 Docker Engine用service docker start启动。我用的是第二条在 WSL2 里直接安装 Docker Engine。原因有三个。第一更贴近服务器部署场景从 WSL 切到云主机基本零成本。第二资源占用比 Desktop 低常驻内存少了几百兆。第三日志和容器访问更直接不用经过 Desktop 那一层。安装 Docker Engine 的步骤不复杂sudo apt update sudo apt install -y docker.io docker-compose-v2注意Ubuntu 仓库自带的docker.io可能版本不是最新但胜在稳定日常自托管够用。装完先启动试一试sudo service docker startWSL2 默认不开启 systemd所以不要用systemctl start docker如果实验后 systemd 没生效会看到报错。用service是最稳的启动方式。2.3 把当前用户加入 docker 组省去每次 sudo这是很容易被忽略的体验优化。默认情况下 docker 命令需要 root 权限每次sudo很烦而且某些工具脚本非 root 环境下行为会不一样。执行sudo usermod -aG docker $USER然后退出 WSL 终端再重新进入再用docker version验证。如果仍提示权限不够多半是当前终端会话还没刷新用户组退出重开即可。注意Docker 服务的启动时机很重要。WSL2 的虚拟机会随 Windows 启动但 Docker 服务不会自动起来写脚本时请记得在任务计划里加上wsl -d Ubuntu-22.04 -u root service docker start否则重启电脑后容器不会跟着恢复。3. 部署 OpenClaw 服务目录规划、配置、启动3.1 拉取项目与目录规划OpenClaw 本身是通过 Docker 镜像方式分发的我们拿到的是项目仓库里面包含docker-compose.yml和配置文件模板。我在 WSL 里建了个独立目录/opt/openclaw不用 home 目录也不放到/mnt/c原因下面说。sudo mkdir -p /opt/openclaw cd /opt/openclaw git clone OpenClaw 项目仓库地址 .WSL2 访问 Windows 磁盘是通过/mnt/c挂载的性能远不如 ext4 分区。容器频繁读写配置、日志如果放在/mnt/c下IO 延迟会非常明显尤其是日志量大时更吃亏。所以尽量放到 WSL 自己的 Linux 文件系统里。目录结构大概是这样/opt/openclaw/ ├─ docker-compose.yml ├─ .env ├─ config/ │ ├─ config.yaml │ └─ profiles/ └─ logs/把配置和日志用 volume 挂载到容器外面方便修改和排查。3.2 编写 docker-compose.yml 和 .env我用 docker compose 管理服务理由很简单一条命令启动/停止配置可版本化管理。下面是开箱可用的简化版docker-compose.ymlservices: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - ./config:/app/config - ./logs:/app/logs env_file: - .env关键点restart: unless-stopped让容器在退出后自动拉起不用自己写守护脚本。ports暴露 8080供健康检查和调试使用如果走飞书长连接模式其实不需要对外暴露端口但保留一个本地调试端口总是有用的。env_file单独放在.env里避免把密钥写进仓库。.env文件的核心内容先这样写之后接入飞书和 Qwen 再补OPENCLAW_NAMEmy-openclaw OPENCLAW_PLATFORMfeishu TZAsia/Shanghai3.3 启动并确认服务状态写好后启动服务docker compose up -d用docker compose logs -f看实时日志。第一次启动会拉取镜像建议网络稳定时操作。看到类似 “OpenClaw started” 的日志就说明基础服务起来了。如果容器反复重启先看日志里是否缺少关键环境变量或者端口是否被占用。实操心得别急着往下接飞书和模型先用容器内自带健康检查接口测一下比如curl http://localhost:8080/health。这一步能把“服务本身的问题”和“外部接入问题”分开后面排查会轻松很多。4. 接入飞书机器人4.1 创建飞书应用并拿到凭证飞书机器人这块本质上和任何办公协同平台的自定义消息应用一样先建应用再开启机器人能力再拿密钥。打开飞书开放平台选择“企业自建应用”填写应用名称。创建后进入“应用能力”页面启用“机器人”。随后需要拿三项东西App ID应用唯一标识形如cli_xxxApp Secret应用密钥调用 API 时用来签名Verification Token / Encrypt Key事件订阅校验用这些是接入 OpenClaw 飞书通道的核心凭证只填到.env里不要提交到 Git。4.2 用长连接模式避开公网回调的坑飞书机器人接收消息有两种方式事件订阅回调以及长连接。回调方式需要提供一个公网 HTTPS 地址如果没有服务器和域名本地调试会很尴尬WSL 里的服务对公网不可达飞书后台无法直接访问到你的笔记本。我强烈推荐使用长连接WebSocket模式这也是我踩过坑之后换过来的最稳定方案。飞书机器人支持通过 WebSocket 长连接主动连上飞书服务器不需要任何公网入站端口只要容器能访问外网即可。OpenClaw 也支持这个模式。在.env中配置FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETxxxxx FEISHU_ENCRYPT_KEYxxxxx FEISHU_USE_WEBSOCKETtrue然后docker compose restart openclaw日志里如果出现“Feishu WebSocket connected”说明长连接建立成功。之后在飞书里搜索这个应用名称给机器人发一条消息正常会在服务日志里看到消息事件。4.3 给机器人赋予必要权限另一个容易踩的坑是权限不足。飞书机器人要能读到你发送的消息并回复消息需要在开放平台后台给应用添加权限常见至少包含im:message读取消息im:message.send发送消息contact:user.base读取用户基本信息用于展示发送者名称配置完权限后需要重新发布版本才生效。我在第一次接入时没有发布版本App 权限停留在测试模式导致日志里能收到事件但无法回复这个点特别容易漏。注意如果使用 Encrypt Key飞书事件会经过加密OpenClaw 侧必须配置同样的 Key。否则日志会反复提示解密失败而且表面上看消息“收到不处理”。这个 Key 在开放平台“事件订阅”页面可以生成。5. 配置 Qwen 大模型5.1 选择 OpenAI 兼容接口还是原生接口OpenClaw 对模型层的接入做了抽象Qwen 有两条接入路径一是 DashScope 的原生 API二是 DashScope 提供 OpenAI 兼容模式的接口。我建议直接用 OpenAI 兼容模式因为社区维护的多数插件对 OpenAI 兼容模式测试最充分参数对齐也方便。配置核心环境变量如下MODEL_PROVIDERqwen_openai OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_API_KEYsk-xxxxxxxx QWEN_MODELqwen-plus注意OPENAI_BASE_URL要指向兼容接口的根路径尾部/v1不能少。OPENAI_API_KEY填 DashScope 控制台创建的 API Key。QWEN_MODEL选择实际购买的型号常见有qwen-turbo、qwen-plus、qwen-max等。5.2 模型参数和超时调优OpenClaw 调用模型时默认超时可能是 60 秒但 Qwen 的 max 系列在复杂指令下响应较慢很容易触发超时重试。我踩过这个坑日志里出现requests.exceptions.ReadTimeout后来在配置里调大了超时时间QWEN_TIMEOUT120 QWEN_MAX_TOKENS2048 QWEN_TEMPERATURE0.7那么多参数怎么选个人习惯是日常闲聊用qwen-turbo便宜速度快做代码解释、工具调用、需要稳定输出的任务用qwen-plus如果希望模型理解细腻一点再考虑qwen-max。先用小流量测试再根据响应质量调整不要一开始就上 max省得烧钱。5.3 确认模型调用链路通不通配置完成后不要等飞书消息来验证可以直接在容器里跑一个测试命令让 OpenClaw 直接调用一次模型。比如docker exec -it openclaw python -m openclaw.tools.shell --ask 用一句话介绍你自己如果返回了 Qwen 的输出说明“OpenClaw - Qwen”链路已通。接下来再回飞书发消息问题范围就被缩小了。这一步我在调试多次后才发现能有效避免“飞书问题”和“模型问题”混在一起。常见错误401 代表 API Key 无效404 代表OPENAI_BASE_URL路径不对或模型名不存在429 代表并发/频率超限。先把这三个状态码记住后面排查省一半时间。6. 踩坑实录与常见问题排查6.1 WSL2 网络和端口访问的怪问题WSL2 与 Windows 的端口映射偶尔会出现“容器起来了但 Windows 浏览器访问不了 https://localhost:8080”的情况。原因通常是 WSL2 的网络地址和 Windows 转发对不上尤其在用了自定义局域网或代理工具时。解决思路分三步确认容器端口绑定docker ps看PORTS列是否有0.0.0.0:8080-8080/tcp。在 WSL2 内部测curl http://127.0.0.1:8080/health如果通说明容器没问题。在 Windows 侧试curl http://localhost:8080/health如果通说明映射正常。如果 Windows 侧不通最简单粗暴的办法是用netsh interface portproxy手动设置端口转发或者把 Docker 容器改用network_mode: host不推荐但本地调试很直接。重启 WSL 后 IP 会变所以尽量依赖localhost转发而不是写死某个 WSL IP。6.2 Docker daemon 无法访问刚配置好 Docker Engine 时经常会遇到Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?先执行sudo service docker status看看服务状态。如果显示 running但还是连接失败十有八九是当前用户没有权限访问/var/run/docker.sock。确认是否已加入 docker 组并重新打开终端。如果服务没起来直接启动sudo service docker start。要注意的是WSL2 默认不启动 systemd很多教程里的systemctl enable docker并不会生效反而会误导。老老实实用service才是 WSL 里的主流玩法。6.3 飞书消息不回复的排查流程我在这块卡了大半晚上。后来总结出固定的排查顺序先确认长连接是否正常。看日志里有没WebSocket connected。再确认消息事件是否到达。给机器人发消息日志里是否有收到事件的记录。然后确认模型调用是否成功。用上一节提到的内部测试命令先验证。最后看是否有报错堆栈比如权限不足、加密失败、超时。最坑的是事件到达但回复失败。原因是飞书要求回复消息前先拿到message_id和 chat 类型我的第一次配置里漏了权限OpenClaw 后台只报了一个通用错误。建议先把im:message和im:message.send权限都加上慢慢排查。6.4 时区、日志和容器重启问题日志时间默认是 UTC和北京时间差 8 小时排查问题时容易产生混淆。所以我在.env里设置了TZAsia/Shanghai容器内日志就跟本地时间一致了。另外容器重启后如果数据丢失通常是忘了挂载 volume。OpenClaw 的配置、日志、持久化数据务必映射出来我给目录说明都写好了别偷懒。6.5 常见错误速查表下表是这次部署中高频出现的错误和对应手段错误现象可能原因解决动作Docker daemon 无法连接服务未启动 / 当前用户无权限sudo service docker start将用户加入 docker 组后重新登录容器频繁重启缺少环境变量或镜像版本不兼容查看docker compose logs补全.env后重启飞书收不到消息事件长连接未启用 / 权限未发布开启 WebSocket 模式发布应用版本飞书加密解密失败Encrypt Key 不一致在.env和飞书后台同时比对Qwen 返回 401API Key 错误重新生成 DashScope API KeyQwen 返回 404Base URL 路径或模型名不对检查/v1是否缺失模型名改为qwen-plus等模型调用超时默认超时太短调大QWEN_TIMEOUTWindows 访问不到容器服务WSL2 端口映射异常从 WSL 内先测curl 127.0.0.1再排查 Windows 转发7. 踩坑后的几点个人体会这次部署折腾下来我最大的感触是先把基础链路单独验证再去拼起来效率会高很多。我一开始一窝蜂全部配好结果飞书、模型、容器混在一起出了错根本不知道是谁的问题。后来一步步拆开验证先测 Docker再测模型再测飞书很快就把问题定位了。还有一点是长连接模式真的比回调模式省心。回调模式下你不仅要有公网地址还要配 HTTPS 证书本地调试非常痛苦。飞书长连接让本地自托管机器人的复杂度降了一个量级。如果你也只是在 Windows 上自用建议直接采用这个方案别在公网回调上浪费时间。如果你要长期跑记得把容器设置成开机自动启动并额外写一个 WSL 开机启动 Docker 服务的计划任务。我一开始忽略了这点系统重启之后发现容器没起来飞书机器人“失联”了一上午。把这些细节准备好剩下的就是把模型调优和工具玩法慢慢打磨了。