Windows上跑通OpenClaw：WSL2+Docker部署飞书机器人并接入Qwen

前阵子想把手上的自动化任务和聊天机器人打通，正好看到 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 并切换到 Ubuntu

Windows 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 start

WSL2 默认不开启 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.yml：

services: 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_NAME=my-openclaw OPENCLAW_PLATFORM=feishu TZ=Asia/Shanghai

3.3 启动并确认服务状态

写好后启动服务：

docker compose up -d

用docker compose logs -f看实时日志。第一次启动会拉取镜像，建议网络稳定时操作。看到类似 “OpenClaw started” 的日志就说明基础服务起来了。如果容器反复重启，先看日志里是否缺少关键环境变量，或者端口是否被占用。

实操心得：别急着往下接飞书和模型，先用容器内自带健康检查接口测一下，比如curl http://localhost:8080/health。这一步能把“服务本身的问题”和“外部接入问题”分开，后面排查会轻松很多。

4. 接入飞书机器人

4.1 创建飞书应用并拿到凭证

飞书机器人这块，本质上和任何办公协同平台的自定义消息应用一样：先建应用，再开启机器人能力，再拿密钥。打开飞书开放平台，选择“企业自建应用”，填写应用名称。创建后进入“应用能力”页面，启用“机器人”。

随后需要拿三项东西：

• App ID：应用唯一标识，形如cli_xxx
• App Secret：应用密钥，调用 API 时用来签名
• Verification Token / Encrypt Key：事件订阅校验用

这些是接入 OpenClaw 飞书通道的核心凭证，只填到.env里，不要提交到 Git。

4.2 用长连接模式避开公网回调的坑

飞书机器人接收消息有两种方式：事件订阅回调，以及长连接。回调方式需要提供一个公网 HTTPS 地址；如果没有服务器和域名，本地调试会很尴尬，WSL 里的服务对公网不可达，飞书后台无法直接访问到你的笔记本。

我强烈推荐使用长连接（WebSocket）模式，这也是我踩过坑之后换过来的最稳定方案。飞书机器人支持通过 WebSocket 长连接主动连上飞书服务器，不需要任何公网入站端口，只要容器能访问外网即可。OpenClaw 也支持这个模式。

在.env中配置：

FEISHU_APP_ID=cli_xxxxxxxx FEISHU_APP_SECRET=xxxxx FEISHU_ENCRYPT_KEY=xxxxx FEISHU_USE_WEBSOCKET=true

然后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_PROVIDER=qwen_openai OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_API_KEY=sk-xxxxxxxx QWEN_MODEL=qwen-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_TIMEOUT=120 QWEN_MAX_TOKENS=2048 QWEN_TEMPERATURE=0.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 转发对不上，尤其在用了自定义局域网或代理工具时。

解决思路分三步：

1. 确认容器端口绑定：docker ps看PORTS列是否有0.0.0.0:8080->8080/tcp。
2. 在 WSL2 内部测：curl http://127.0.0.1:8080/health，如果通说明容器没问题。
3. 在 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 飞书消息不回复的排查流程

我在这块卡了大半晚上。后来总结出固定的排查顺序：

1. 先确认长连接是否正常。看日志里有没WebSocket connected。
2. 再确认消息事件是否到达。给机器人发消息，日志里是否有收到事件的记录。
3. 然后确认模型调用是否成功。用上一节提到的内部测试命令先验证。
4. 最后看是否有报错堆栈，比如权限不足、加密失败、超时。

最坑的是事件到达但回复失败。原因是飞书要求回复消息前先拿到message_id和 chat 类型，我的第一次配置里漏了权限，OpenClaw 后台只报了一个通用错误。建议先把im:message和im:message.send权限都加上，慢慢排查。

6.4 时区、日志和容器重启问题

日志时间默认是 UTC，和北京时间差 8 小时，排查问题时容易产生混淆。所以我在.env里设置了TZ=Asia/Shanghai，容器内日志就跟本地时间一致了。另外，容器重启后如果数据丢失，通常是忘了挂载 volume。OpenClaw 的配置、日志、持久化数据务必映射出来，我给目录说明都写好了，别偷懒。

6.5 常见错误速查表

下表是这次部署中高频出现的错误和对应手段：

7. 踩坑后的几点个人体会

这次部署折腾下来，我最大的感触是：先把基础链路单独验证，再去拼起来，效率会高很多。我一开始一窝蜂全部配好，结果飞书、模型、容器混在一起，出了错根本不知道是谁的问题。后来一步步拆开验证，先测 Docker，再测模型，再测飞书，很快就把问题定位了。

还有一点是，长连接模式真的比回调模式省心。回调模式下你不仅要有公网地址，还要配 HTTPS 证书，本地调试非常痛苦。飞书长连接让本地自托管机器人的复杂度降了一个量级。如果你也只是在 Windows 上自用，建议直接采用这个方案，别在公网回调上浪费时间。

如果你要长期跑，记得把容器设置成开机自动启动，并额外写一个 WSL 开机启动 Docker 服务的计划任务。我一开始忽略了这点，系统重启之后发现容器没起来，飞书机器人“失联”了一上午。把这些细节准备好，剩下的就是把模型调优和工具玩法慢慢打磨了。