把 OpenClaw 接上飞书机器人再配上 Qwen 大模型听起来就是配几个环境变量的事。但真动手之后你会发现Windows 上的 WSL2、容器网络、飞书回调、模型服务这四个环节都想教你做人。这篇文章是我用 WSL2 里的 Docker 部署 OpenClaw并把飞书机器人接入 Qwen 的完整记录。前前后后折腾了一天半光是飞书回调验证就卡了快两个小时。文章里所有命令都是我在自己机器上跑过的遇到的报错和处理方式也会写出来。环境不同细节可能要微调但大的链路基本能照着走。1. 先把地基打牢WSL2 环境准备与 Docker 安装1.1 为什么绕不开 WSL2OpenClaw 这类消息型 AI 助手服务官方推荐以 Docker 容器方式运行镜像和容器生态也都是 Linux 优先。如果你手头有现成的云服务器直接在上面部署反而更省事。但大部分开发机是 Windows我需要在本地先把消息链路的可行性验证完再决定后面往哪里部署。这时 WSL2 就是最合适的底座。WSL2 本质上是一个轻量虚拟机但它和传统虚拟机不一样启动只要几秒内存按需分配而且 Windows 侧可以直接用 localhost 访问 WSL 里跑起来的服务这对调试飞书回调特别友好。相比之下传统虚拟机那套端口映射网络模式光配端口转发就够折腾一壶。还有一条很关键WSL2 的文件系统和容器运行时的兼容性比 WSL1 好得多Docker 在 WSL2 里跑不会再出现 inotify 失效、文件锁异常这些老毛病。有人会问为什么不用 Docker Desktop我当然知道 Docker Desktop 装起来简单它本身也支持 WSL2 后端。但它是为图形界面和跨平台场景设计的对只想跑一个轻量服务的场景显得重而且它默认接管了 Docker daemon 的生命周期出问题时你很难判断是 WSL 的问题还是 Docker Desktop 自身的问题。自己做 docker-ce 安装在排障时可控性好很多部署到生产环境时也能无缝迁移。所以下面直接用 Docker Engine。1.2 安装 WSL2 和 Ubuntu 发行版Windows 侧先要以管理员身份打开 PowerShell执行两条命令启用必要功能。dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完重启系统再安装 WSL2 内核更新包。新版 Windows 通常直接wsl --update就能解决。然后安装发行版我用的是 Ubuntu 22.04wsl --install -d Ubuntu-22.04首次进入会要求创建 Linux 用户。后续确认发行版处于 WSL2 模式wsl -l -v如果输出里显示 Version 是 1执行wsl --set-version Ubuntu-22.04 2切换。这一步很重要OpenClaw 的 Docker 容器对 WSL1 的兼容性很差尤其是文件卷挂载时可能会出现莫名其妙的 Permission denied。装完 Ubuntu 后我建议在发行版里额外做两件事。第一件在/etc/wsl.conf里开启 systemd[boot] systemdtrue有了 systemdDocker 服务可以正常用systemctl管理不用每次重启都手动启 daemon。第二件在 Windows 用户目录下建.wslconfig文件限制一下 WSL2 的内存占用。默认配置是 WSL 吃主机一半内存如果主机只有 16G跑几个容器后 Windows 会明显卡顿。我的配置是[wsl2] memory8GB swap2GB localhostForwardingtruelocalhostForwardingtrue是默认开启的写出来是为了确认。这个配置决定了 Windows 上访问localhost:8080能否正确转发到 WSL 里的 Docker 容器端口飞书回调联调时全靠它。1.3 在 WSL 内安装 Docker Engine进入 Ubuntu 终端先替换软件源并安装 Docker 官方源里的包。下面这套命令在 Ubuntu 22.04 上是通用的sudo apt update sudo apt install -y ca-certificates curl gnupg curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io如果download.docker.com拉取速度不理想可以给 Docker daemon 加 registry mirror 配置。编辑/etc/docker/daemon.json{ registry-mirrors: [https://你的镜像加速地址] }镜像加速地址根据自己的网络环境选择即可不一定非要配。装完先启动服务并验证sudo systemctl enable docker sudo systemctl start docker docker version看到 Client 和 Server 两段都有版本号说明 daemon 正常工作。这里有个 WSL 新手最容易踩的坑执行docker version如果只有 Client 有输出而 Server 报Cannot connect to the Docker daemon十有八九是 systemd 没开成功或者系统刚启动 daemon 还没起来。没有 systemd 的环境可以先用sudo service docker start顶一下但根治方式还是把/etc/wsl.conf改对然后重启 WSL。2. 把 OpenClaw 容器拉起来目录规划与 Compose 配置2.1 先搞清楚 OpenClaw 到底做了什么OpenClaw 在这个链路里的位置简单说就是一个消息型 AI 服务端。飞书把用户消息以 Webhook 形式推给 OpenClawOpenClaw 把消息整理成统一结构调用 Qwen 拿到回复再通过飞书开放平台接口把回复发回会话。整个链路里它承担了三件事事件接入、模型调度、主动发送消息。这不是把两个 API 用代码粘在一起那么简单。飞书回调有时间限制模型推理又可能耗时几秒所以 OpenClaw 的架构是先快速回确认然后异步去调用 Qwen等模型出结果再调飞书发送接口。这种设计决定了部署时不能把回调地址指向一个同步处理的 PHP 脚本必须有独立的常驻进程。用 Docker 跑它的好处也在这里进程管理、日志、重启策略都由容器统一处理不会因为 WSL 终端关掉导致服务断掉。OpenClaw 的数据目录里通常保存会话上下文和技能配置。容器删了可以重建但数据目录丢了上下文就真没了。所以部署的第一步是规划一个宿主机目录来做持久化挂载。2.2 创建项目目录与 docker-compose.yml我在 WSL 用户目录下建了openclaw目录所有配置都放在里面方便以后备份mkdir -p ~/openclaw cd ~/openclawdocker-compose.yml我采用最简结构先把服务跑通再做高级配置services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - ./openclaw-data:/app/data env_file: - .env这里几个点解释一下。restart: unless-stopped可以让容器在 daemon 重启或进程崩溃后自动拉起WSL 本身没有 Windows 服务那么完善的守护机制这个策略非常关键。ports把容器内 8080 暴露到宿主机飞书 Webhook 进到 WSL 后就是通过这个端口找到 OpenClaw。volumes把容器内/app/data映射到宿主机./openclaw-data目录如果不存在 Docker 会自动创建但我们最好手动提前建好避免权限不对导致容器启动时无法写入mkdir -p openclaw-dataenv_file指向.env。所有密钥、模型参数、飞书配置都放在这个文件里不写进 compose防止误提交到代码仓库。2.3 环境变量文件的写法在~/openclaw下创建.env内容先给一版占位配置# 服务监听配置 OPENCLAW_PORT8080 OPENCLAW_WEBHOOK_PATH/feishu/webhook # 大模型配置以 Qwen 官方 API 为例 LLM_PROVIDERopenai OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_API_KEY你的API-KEY OPENAI_MODELqwen-max # 飞书配置 FEISHU_APP_IDcli_你的AppId FEISHU_APP_SECRET你的AppSecret FEISHU_VERIFICATION_TOKEN你的VerificationToken FEISHU_ENCRYPT_KEY你的EncryptKey这套配置里OPENCLAW_WEBHOOK_PATH决定飞书事件推送时的最后一段路径后面在飞书开放平台填回调地址时会用到。LLM_PROVIDER写成openai是因为 Qwen 的官方 API 提供 OpenAI 兼容模式OpenClaw 内部走标准 OpenAI SDK 就能通信不用再为某个特定平台写适配层。配置完成后启动docker compose up -d docker compose logs -f openclaw看到类似server is running on 0.0.0.0:8080的日志说明容器起来了。先不要急着做飞书配置因为接下来还有模型服务模型没通飞书收到消息也无法正常回复。3. 接入 Qwen 大模型官方 API 与本地部署两条路3.1 走官方 OpenAI 兼容接口是最快方案接入 Qwen 时我最开始想的是它家有没有专属 SDK。后来查资料才发现Qwen 提供了 OpenAI 兼容 HTTP 接口Base URL 固定为https://dashscope.aliyuncs.com/compatible-mode/v1。这意味着任何支持 OpenAI 接口定义的工具都能直接接 Qwen不需要引入额外依赖也不需要对 OpenClaw 做定制。配置对应.env中的几个变量LLM_PROVIDERopenai OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_API_KEYsk-你的密钥 OPENAI_MODELqwen-maxqwen-max是效果最好的版本如果对延迟更敏感可以改成qwen-plus或qwen-turbo。API Key 在云平台上创建创建后只显示一次注意保存。改完.env后执行docker compose restart openclaw然后看日志确认没有报401或InvalidApiKey。这里要特别强调一点很多朋友改了.env之后只docker compose up -d但 compose 对环境变量的变更不一定触发容器重建。稳妥做法是先执行docker compose down再docker compose up -d除非 compose 文件明确写了env_file且你确认重启能重新读取环境变量。实际测试下来restart有时候确实不会重新加载 env 文件里的值最保险的是 down 掉再 up。3.2 本地部署 QwenOllama 容器方案官方 API 的优势是零部署成本但如果你对数据敏感或者想完全离线使用可以在 WSL 里用 Docker 再跑一个 Ollama 服务把 Qwen 模型拉到本地。这个方案对硬件有一定要求建议至少 8GB 可用内存显卡能用于计算更好。在docker-compose.yml里加一段 Ollama 服务services: ollama: image: ollama/ollama container_name: ollama restart: unless-stopped volumes: - ollama-data:/root/.ollama ports: - 11434:11434 volumes: ollama-data:启动后拉取模型docker compose up -d ollama docker exec -it ollama ollama pull qwen2.5:7b模型较大网络不好时会等很久这是正常现象。没有独立显卡的环境建议改用qwen2.5:3b虽然推理效果弱一些但 CPU 也能跑得动。本地模型的接入地址要改为 Ollama 的 OpenAI 兼容端点LLM_PROVIDERopenai OPENAI_BASE_URLhttp://ollama:11434/v1 OPENAI_MODELqwen2.5:7b这里用http://ollama:11434/v1而不是localhost:11434是因为 OpenClaw 和 Ollama 都在同一个 Docker 网络里Docker 会通过服务名解析到对应的容器 IP。如果 OpenClaw 容器跑在另一个网络localhost指向的是它自己容器根本连不上 Ollama。两条路线怎么选我的倾向是先用官方 API 把整个链路调通确认飞书机器人没问题后再考虑本地模型。理由很简单官方 API 稳定性和响应速度都更好本地模型还要排查 GPU 直通、模型量化、显存占用等一系列问题这些不该在链路验证阶段混进来。4. 飞书机器人接入开放平台配置与回调联通4.1 在飞书开放平台创建应用并开通机器人登录飞书开放平台后选择创建企业自建应用注意不要选商店应用商店应用要过审核不适合快速验证内部工具。创建完成后进入应用详情页添加机器人能力就是在“应用能力”里把机器人开关打开。这个操作会产生两个核心凭证App ID 和 App Secret。App ID 通常形如cli_开头App Secret 则在应用凭证页面查看。这两个值分别对应.env里的FEISHU_APP_ID和FEISHU_APP_SECRET是 OpenClaw 调用飞书接口发送消息的身份凭证。关键点是权限配置。机器人默认权限范围很小要能阅读消息和主动发送消息必须开通对应的权限。我在实际操作中至少申请了这几项im:message读取用户发给机器人的消息内容im:message:send_as_bot以机器人身份发送消息权限开通后需要创建版本并发布否则只在自己测试范围内偶尔生效其他成员根本无法使用。我当时漏了发布版本结果自己发消息机器人能回同一企业群里的同事发消息完全没反应排查了半天才发现是权限版本没上线。4.2 事件订阅回调地址和挑战校验飞书机器人要收到消息本质是飞书把“用户发消息”这个事件推送到你自己的服务端。在飞书后台进入“事件与回调”页面先开启订阅方式然后填写请求地址。这里的地址必须是可以被公网访问的 URL不能填localhost飞书服务器不可能访问到你的 Windows 本机。请求地址的格式是https://你的域名/feishu/webhook。如果你的服务是用云服务器加网关转发到 WSL 的云服务器上只需要把对应路径的请求转发到 8080 端口。这里的/feishu/webhook必须和.env里OPENCLAW_WEBHOOK_PATH保持一致。接着选择事件。必须添加接收消息 im.message.receive_v1其他事件按需添加。保存时飞书会向请求地址发送一个带challenge参数的校验请求OpenClaw 会原样返回这个值。飞书后台收到正确响应后订阅才会保存成功。这里就是很多人卡住的地方。回调验证失败通常和三个方面有关地址不可达。先用浏览器或命令行访问https://你的域名/feishu/webhook看能不能拿到 OpenClaw 的响应拿不到就说明转发链路有问题。加密参数不匹配。飞书后台需要配置加密策略其中 Verification Token 和 Encrypt Key 是两个不同概念。Token 用于校验请求合法性Encrypt Key 用于解密消息内容。错误把 Encrypt Key 当成 Token 填进.env验证就会失败。同步响应太慢。challenge校验要求快速返回如果链路中间经过慢速转发或者容器日志显示进程 IO 阻塞校验就会超时。我自己的处理方式是先在本机验证。在 WSL 终端里发一个模拟请求curl -i -X POST http://localhost:8080/feishu/webhook \ -H Content-Type: application/json \ -d {challenge:test123}如果 OpenClaw 配置正确响应里会把challenge原样带回来。比如{challenge:test123}本机通了再检查域名链路。如果域名链路不通问题大概率出在公网入口的转发配置而不是 OpenClaw。4.3 加密参数的完整配置链路飞书后台的“事件订阅”里有一项加密策略推荐开启。开启后会出现两个值Verification Token 和 Encrypt Key。注意这两个值每次保存订阅时可能会重置所以修改完后台配置要同步回.env否则会出现事件推送签名校验失败。.env对应配置FEISHU_VERIFICATION_TOKEN后台看到的token FEISHU_ENCRYPT_KEY后台看到的encrypt key改完之后同样建议docker compose down再docker compose up -d。然后回到飞书后台点“更新订阅”让平台重新校验。如果显示订阅成功说明回调链路完全打通。接下来在飞书里给机器人发一条普通消息。OpenClaw 日志里应该能看到收到事件的记录再等一两秒机器人会把 Qwen 的回复发到会话里。如果日志里已经出现模型响应但飞书里没收到消息基本可以确定是权限或发送阶段的问题按下面常见的排查清单继续定位。5. 踩坑实录高频问题与排查技巧5.1 常见故障速查表把我在这次部署里遇到、以及帮别人排查时见过的典型问题整理成了表格。遇到问题先按症状对照能省大量时间。症状大概率原因处理方式Docker 命令报Cannot connect to the Docker daemonWSL 里 systemd 未启用或 daemon 没启动执行sudo systemctl enable docker sudo systemctl start docker或暂时用sudo service docker start端口 8080 无法访问curl localhost:8080卡住容器没启动或端口映射错误检查docker compose ps确认容器状态再看docker compose logs飞书回调校验失败且本机curl正常公网入口到 WSL 的链路不通检查云服务器上的端口转发配置以及 Windows 防火墙是否拦截外部到 WSL 的流量飞书后台订阅保存成功但发消息机器人无响应事件订阅没选择im.message.receive_v1后台补选事件并重新保存机器人只回复本人群里其他人不回复应用版本没有发布或权限范围不足确认已创建版本并发布同时在权限管理里开通发送消息相关权限日志显示401 InvalidApiKeyAPI Key 错误或环境变量未重新加载检查.env中OPENAI_API_KEY执行docker compose down后重新 up日志出现中文乱码或时间差 8 小时容器时区和语言环境没设置在.env中设置TZAsia/Shanghai和LANGC.UTF-85.2 几个让我卡住的细节第一个坑是 WSL 重启后容器没有自动起来。我把restart: unless-stopped写进 compose 的初衷就是避免手动重启但 WSL 整体关机后Docker daemon 并没有随 WSL 自启。后来发现根本原因还是 systemd 没有生效。docker version能显示 Client 和 Server 都正常不代表 systemd 是存活的。正确做法是把systemdtrue放到/etc/wsl.conf的[boot]区域放到其他位置无效。改完 WSL 要用wsl --shutdown彻底关掉再进入而不是在 WSL 里重启。第二个坑是飞书校验明明成功消息却接收不到。现象是后台保存订阅成功但实际发消息时WSL 里的容器完全看不到任何请求。最后排查发现是云服务器上的转发规则把POST方法过滤了。某些网关配置默认只放行 GET飞书事件推送是 POST直接被打回。如果使用云服务器自行搭建转发务必确认监听器同时支持 HTTP POST 且不校验 Content-Type。第三个坑是 Qwen 的响应偶尔很慢飞书那边表现为机器人“已读不回”。原因是我把模型设成了qwen-max在高峰期推理耗时达到五六秒。OpenClaw 本身是异步发送理论上不受影响但模型服务端如果触发限流请求会排队。后来给.env加了请求超时相关参数同时将单轮对话的模型临时切到qwen-plus响应恢复到两秒左右。适合你的模型不是越强越好要看场景对延迟的容忍度。5.3 容器运维与资源调优建议部署完不是结束后面还要稳定跑。几个实操建议日志一定要看。OpenClaw 出现问题不会在飞书端有太明显的提示就是干脆不回复。docker compose logs -f openclaw应该作为联调期的常驻命令。等到确认日志稳定输出再关掉。openclaw-data要定期备份。里面存了会话上下文一旦容器重建而数据目录损坏连续对话的记忆会丢失。备份其实就是把openclaw-data目录压缩一份成本很低。.wslconfig的资源限制要配合实际负载调。我用 8GB 内存限制同时跑 OpenClaw 和 Ollama 时比较紧张。如果本地也用 Ollama建议把内存上限调整到 12GB或给 Ollama 单独限制模型大小。资源不够时最容易出现的现象是模型推理极慢不是报错排查起来反而不明显。Docker 镜像和日志会持续占用磁盘尤其是 WSL 的虚拟磁盘文件删了容器不一定会自动释放空间。定期执行docker system prune -f注意这个命令会清理闲置镜像和构建缓存正在使用的不会有影响。如果 WSL 的磁盘文件膨胀到夸张程度可以在 Windows 侧对发行版执行wsl --shutdown然后用磁盘压缩工具回收空闲空间。这是在 WSL2 里跑 Docker 绕不开的维护点。最后再分享一个经验这套环境我目前还在继续用。如果要重新部署一遍我会把顺序调整为先跑通飞书本机 Webhook 验证再接入 Qwen最后发布飞书版本。之所以这个顺序是因为回调链路涉及网络出口是最难排查的一环早验证早放心模型接入反而是纯配置问题改一下.env就能看到结果。Qwen 模型选择也建议从qwen-plus起步等业务确实需要更强推理能力再上qwen-max。这个组合跑了两周目前最稳定的是官方 API 加飞书 Webhook 的模式Ollama 版适合本地研究不适合长期靠 CPU 硬扛。希望这篇记录能让你少绕几个弯。