前陣子想把手上的自動(dòng)化任務(wù)和聊天機(jī)器人打通正好看到 OpenClaw 這個(gè)項(xiàng)目。它把多平臺(tái)機(jī)器人、消息驅(qū)動(dòng)任務(wù)、大模型調(diào)用全封裝到一起最吸引我的是可以直接對(duì)接飛書機(jī)器人和 Qwen 大模型。我一開始圖省事直接在 Windows 上跑結(jié)果環(huán)境依賴一團(tuán)糟Python 包沖突、后臺(tái)常駐不穩(wěn)、日志亂跳第一天就這么折騰掉了。后來果斷換成 WSL2 Docker 的組合花了兩個(gè)晚上總算穩(wěn)定跑通。這篇就把我從零開始到最終跑通的全過程寫出來包括 WSL2 怎么裝、Docker 怎么配、OpenClaw 怎么部署、飛書機(jī)器人怎么接、Qwen 模型怎么調(diào)用以及每個(gè)環(huán)節(jié)我踩過的坑和對(duì)應(yīng)的排查方法。所有步驟都盡量寫得細(xì)適合剛接觸 WSL/Docker、想在 Windows 上部署自托管機(jī)器人服務(wù)的朋友。如果你已經(jīng)有一定基礎(chǔ)也可以直接跳到第 6 節(jié)看常見問題速查表。1. 為什么選 WSL Docker 這套組合1.1 先搞清楚 WSL2 和 Docker 分別解決什么問題WSL2 是 Windows 下的一個(gè)輕量 Linux 子系統(tǒng)它不是虛擬機(jī)但內(nèi)部跑的是一個(gè)完整 Linux 內(nèi)核兼容性遠(yuǎn)好于第一代 WSL。我個(gè)人的理解是Windows 是宿主機(jī)WSL2 是一個(gè)隨叫隨到的 Linux 環(huán)境啟動(dòng)快、內(nèi)存動(dòng)態(tài)占用跟 Windows 文件系統(tǒng)能互訪這對(duì)開發(fā)調(diào)試非常友好。Docker 解決的問題是“環(huán)境一致性”。OpenClaw 這類服務(wù)依賴一堆系統(tǒng)庫、Python 包和運(yùn)行時(shí)配置如果直接裝在系統(tǒng)里很容易被系統(tǒng)升級(jí)或者其他軟件搞壞。用 Docker 鏡像把服務(wù)、配置、依賴全部打包只要鏡像沒變換到任何機(jī)器上跑行為都一致。我后兩次重裝環(huán)境基本就是啟動(dòng)容器不再重新折騰依賴非常省事。1.2 為什么不用整套虛擬機(jī)也不用純 Windows 運(yùn)行有人會(huì)問用 VMware/Hyper-V 開個(gè)完整虛擬機(jī)不是更接近 Linux 服務(wù)器嗎確實(shí)更像但完整虛擬機(jī)的問題是開機(jī)慢、占內(nèi)存、維護(hù)成本高。WSL2 足夠跑多數(shù)容器化服務(wù)內(nèi)存管理更靈活還能直接訪問 Windows 磁盤文件。對(duì)比起來WSL2 更適合個(gè)人開發(fā)機(jī)和常駐型小服務(wù)。純 Windows 直接跑 OpenClaw 也不是完全不行前提是你把所有依賴都處理好還要考慮服務(wù)開機(jī)自啟、進(jìn)程守護(hù)、權(quán)限問題。Windows 下 Python 環(huán)境的坑我踩過太多次比如常見的pydantic版本沖突、cryptography編譯失敗、控制臺(tái)編碼錯(cuò)誤這些在 WSL2 Docker 里幾乎不會(huì)再遇到。對(duì)技術(shù)人來說能用容器解決的問題不值得花時(shí)間跟本機(jī)環(huán)境較勁。提示這套組合適合開發(fā)調(diào)試、個(gè)人自動(dòng)化、小團(tuán)隊(duì)試用。如果要做高可用生產(chǎn)部署還是建議放到云服務(wù)器上跑道理一樣但運(yùn)維方式不同。2. 環(huán)境準(zhǔn)備把 WSL2 和 Docker 裝到能用為止2.1 安裝 WSL2 并切換到 UbuntuWindows 10 版本 2004 以上或 Windows 11 都可以用wsl命令安裝。我建議直接裝 Ubuntu 22.04理由很實(shí)際軟件源更新及時(shí)和 Docker 官方文檔里的示例一致遇到問題搜資料也方便。在管理員 PowerShell 里執(zhí)行wsl --install -d Ubuntu-22.04如果wsl --install提示找不到命令說明系統(tǒng)版本比較舊需要手動(dòng)啟用“適用于 Linux 的 Windows 子系統(tǒng)”和“虛擬機(jī)平臺(tái)”兩個(gè)功能再重啟。完成后繼續(xù)設(shè)置 WSL 版本wsl --set-version Ubuntu-22.04 2檢查版本wsl -l -v看到版本列是 2 就行。WSL1 和 WSL2 差異很大WSL1 不是跑真內(nèi)核對(duì) Docker 支持不完整所以必須用 WSL2。2.2 Docker 方案選擇WSL 內(nèi)裝 Docker Engine 還是 Docker Desktop這里有兩條路。第一條是安裝 Docker Desktop然后在設(shè)置里勾選 WSL Integration讓 Docker 指令直接在 WSL 里使用。第二條是不裝 Desktop在 WSL2 內(nèi)部安裝 Docker Engine用service docker start啟動(dòng)。我用的是第二條在 WSL2 里直接安裝 Docker Engine。原因有三個(gè)。第一更貼近服務(wù)器部署場景從 WSL 切到云主機(jī)基本零成本。第二資源占用比 Desktop 低常駐內(nèi)存少了幾百兆。第三日志和容器訪問更直接不用經(jīng)過 Desktop 那一層。安裝 Docker Engine 的步驟不復(fù)雜sudo apt update sudo apt install -y docker.io docker-compose-v2注意Ubuntu 倉庫自帶的docker.io可能版本不是最新但勝在穩(wěn)定日常自托管夠用。裝完先啟動(dòng)試一試sudo service docker startWSL2 默認(rèn)不開啟 systemd所以不要用systemctl start docker如果實(shí)驗(yàn)后 systemd 沒生效會(huì)看到報(bào)錯(cuò)。用service是最穩(wěn)的啟動(dòng)方式。2.3 把當(dāng)前用戶加入 docker 組省去每次 sudo這是很容易被忽略的體驗(yàn)優(yōu)化。默認(rèn)情況下 docker 命令需要 root 權(quán)限每次sudo很煩而且某些工具腳本非 root 環(huán)境下行為會(huì)不一樣。執(zhí)行sudo usermod -aG docker $USER然后退出 WSL 終端再重新進(jìn)入再用docker version驗(yàn)證。如果仍提示權(quán)限不夠多半是當(dāng)前終端會(huì)話還沒刷新用戶組退出重開即可。注意Docker 服務(wù)的啟動(dòng)時(shí)機(jī)很重要。WSL2 的虛擬機(jī)會(huì)隨 Windows 啟動(dòng)但 Docker 服務(wù)不會(huì)自動(dòng)起來寫腳本時(shí)請(qǐng)記得在任務(wù)計(jì)劃里加上wsl -d Ubuntu-22.04 -u root service docker start否則重啟電腦后容器不會(huì)跟著恢復(fù)。3. 部署 OpenClaw 服務(wù)目錄規(guī)劃、配置、啟動(dòng)3.1 拉取項(xiàng)目與目錄規(guī)劃OpenClaw 本身是通過 Docker 鏡像方式分發(fā)的我們拿到的是項(xiàng)目倉庫里面包含docker-compose.yml和配置文件模板。我在 WSL 里建了個(gè)獨(dú)立目錄/opt/openclaw不用 home 目錄也不放到/mnt/c原因下面說。sudo mkdir -p /opt/openclaw cd /opt/openclaw git clone OpenClaw 項(xiàng)目倉庫地址 .WSL2 訪問 Windows 磁盤是通過/mnt/c掛載的性能遠(yuǎn)不如 ext4 分區(qū)。容器頻繁讀寫配置、日志如果放在/mnt/c下IO 延遲會(huì)非常明顯尤其是日志量大時(shí)更吃虧。所以盡量放到 WSL 自己的 Linux 文件系統(tǒng)里。目錄結(jié)構(gòu)大概是這樣/opt/openclaw/ ├─ docker-compose.yml ├─ .env ├─ config/ │ ├─ config.yaml │ └─ profiles/ └─ logs/把配置和日志用 volume 掛載到容器外面方便修改和排查。3.2 編寫 docker-compose.yml 和 .env我用 docker compose 管理服務(wù)理由很簡單一條命令啟動(dòng)/停止配置可版本化管理。下面是開箱可用的簡化版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關(guān)鍵點(diǎn)restart: unless-stopped讓容器在退出后自動(dòng)拉起不用自己寫守護(hù)腳本。ports暴露 8080供健康檢查和調(diào)試使用如果走飛書長連接模式其實(shí)不需要對(duì)外暴露端口但保留一個(gè)本地調(diào)試端口總是有用的。env_file單獨(dú)放在.env里避免把密鑰寫進(jìn)倉庫。.env文件的核心內(nèi)容先這樣寫之后接入飛書和 Qwen 再補(bǔ)OPENCLAW_NAMEmy-openclaw OPENCLAW_PLATFORMfeishu TZAsia/Shanghai3.3 啟動(dòng)并確認(rèn)服務(wù)狀態(tài)寫好后啟動(dòng)服務(wù)docker compose up -d用docker compose logs -f看實(shí)時(shí)日志。第一次啟動(dòng)會(huì)拉取鏡像建議網(wǎng)絡(luò)穩(wěn)定時(shí)操作?？吹筋愃?“OpenClaw started” 的日志就說明基礎(chǔ)服務(wù)起來了。如果容器反復(fù)重啟先看日志里是否缺少關(guān)鍵環(huán)境變量或者端口是否被占用。實(shí)操心得別急著往下接飛書和模型先用容器內(nèi)自帶健康檢查接口測一下比如curl http://localhost:8080/health。這一步能把“服務(wù)本身的問題”和“外部接入問題”分開后面排查會(huì)輕松很多。4. 接入飛書機(jī)器人4.1 創(chuàng)建飛書應(yīng)用并拿到憑證飛書機(jī)器人這塊本質(zhì)上和任何辦公協(xié)同平臺(tái)的自定義消息應(yīng)用一樣先建應(yīng)用再開啟機(jī)器人能力再拿密鑰。打開飛書開放平臺(tái)選擇“企業(yè)自建應(yīng)用”填寫應(yīng)用名稱。創(chuàng)建后進(jìn)入“應(yīng)用能力”頁面啟用“機(jī)器人”。隨后需要拿三項(xiàng)東西App ID應(yīng)用唯一標(biāo)識(shí)形如cli_xxxApp Secret應(yīng)用密鑰調(diào)用 API 時(shí)用來簽名Verification Token / Encrypt Key事件訂閱校驗(yàn)用這些是接入 OpenClaw 飛書通道的核心憑證只填到.env里不要提交到 Git。4.2 用長連接模式避開公網(wǎng)回調(diào)的坑飛書機(jī)器人接收消息有兩種方式事件訂閱回調(diào)以及長連接?；卣{(diào)方式需要提供一個(gè)公網(wǎng) HTTPS 地址如果沒有服務(wù)器和域名本地調(diào)試會(huì)很尷尬WSL 里的服務(wù)對(duì)公網(wǎng)不可達(dá)飛書后臺(tái)無法直接訪問到你的筆記本。我強(qiáng)烈推薦使用長連接WebSocket模式這也是我踩過坑之后換過來的最穩(wěn)定方案。飛書機(jī)器人支持通過 WebSocket 長連接主動(dòng)連上飛書服務(wù)器不需要任何公網(wǎng)入站端口只要容器能訪問外網(wǎng)即可。OpenClaw 也支持這個(gè)模式。在.env中配置FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETxxxxx FEISHU_ENCRYPT_KEYxxxxx FEISHU_USE_WEBSOCKETtrue然后docker compose restart openclaw日志里如果出現(xiàn)“Feishu WebSocket connected”說明長連接建立成功。之后在飛書里搜索這個(gè)應(yīng)用名稱給機(jī)器人發(fā)一條消息正常會(huì)在服務(wù)日志里看到消息事件。4.3 給機(jī)器人賦予必要權(quán)限另一個(gè)容易踩的坑是權(quán)限不足。飛書機(jī)器人要能讀到你發(fā)送的消息并回復(fù)消息需要在開放平臺(tái)后臺(tái)給應(yīng)用添加權(quán)限常見至少包含im:message讀取消息im:message.send發(fā)送消息contact:user.base讀取用戶基本信息用于展示發(fā)送者名稱配置完權(quán)限后需要重新發(fā)布版本才生效。我在第一次接入時(shí)沒有發(fā)布版本App 權(quán)限停留在測試模式導(dǎo)致日志里能收到事件但無法回復(fù)這個(gè)點(diǎn)特別容易漏。注意如果使用 Encrypt Key飛書事件會(huì)經(jīng)過加密OpenClaw 側(cè)必須配置同樣的 Key。否則日志會(huì)反復(fù)提示解密失敗而且表面上看消息“收到不處理”。這個(gè) Key 在開放平臺(tái)“事件訂閱”頁面可以生成。5. 配置 Qwen 大模型5.1 選擇 OpenAI 兼容接口還是原生接口OpenClaw 對(duì)模型層的接入做了抽象Qwen 有兩條接入路徑一是 DashScope 的原生 API二是 DashScope 提供 OpenAI 兼容模式的接口。我建議直接用 OpenAI 兼容模式因?yàn)樯鐓^(qū)維護(hù)的多數(shù)插件對(duì) OpenAI 兼容模式測試最充分參數(shù)對(duì)齊也方便。配置核心環(huán)境變量如下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 控制臺(tái)創(chuàng)建的 API Key。QWEN_MODEL選擇實(shí)際購買的型號(hào)常見有qwen-turbo、qwen-plus、qwen-max等。5.2 模型參數(shù)和超時(shí)調(diào)優(yōu)OpenClaw 調(diào)用模型時(shí)默認(rèn)超時(shí)可能是 60 秒但 Qwen 的 max 系列在復(fù)雜指令下響應(yīng)較慢很容易觸發(fā)超時(shí)重試。我踩過這個(gè)坑日志里出現(xiàn)requests.exceptions.ReadTimeout后來在配置里調(diào)大了超時(shí)時(shí)間QWEN_TIMEOUT120 QWEN_MAX_TOKENS2048 QWEN_TEMPERATURE0.7那么多參數(shù)怎么選個(gè)人習(xí)慣是日常閑聊用qwen-turbo便宜速度快做代碼解釋、工具調(diào)用、需要穩(wěn)定輸出的任務(wù)用qwen-plus如果希望模型理解細(xì)膩一點(diǎn)再考慮qwen-max。先用小流量測試再根據(jù)響應(yīng)質(zhì)量調(diào)整不要一開始就上 max省得燒錢。5.3 確認(rèn)模型調(diào)用鏈路通不通配置完成后不要等飛書消息來驗(yàn)證可以直接在容器里跑一個(gè)測試命令讓 OpenClaw 直接調(diào)用一次模型。比如docker exec -it openclaw python -m openclaw.tools.shell --ask 用一句話介紹你自己如果返回了 Qwen 的輸出說明“OpenClaw - Qwen”鏈路已通。接下來再回飛書發(fā)消息問題范圍就被縮小了。這一步我在調(diào)試多次后才發(fā)現(xiàn)能有效避免“飛書問題”和“模型問題”混在一起。常見錯(cuò)誤401 代表 API Key 無效404 代表OPENAI_BASE_URL路徑不對(duì)或模型名不存在429 代表并發(fā)/頻率超限。先把這三個(gè)狀態(tài)碼記住后面排查省一半時(shí)間。6. 踩坑實(shí)錄與常見問題排查6.1 WSL2 網(wǎng)絡(luò)和端口訪問的怪問題WSL2 與 Windows 的端口映射偶爾會(huì)出現(xiàn)“容器起來了但 Windows 瀏覽器訪問不了 https://localhost:8080”的情況。原因通常是 WSL2 的網(wǎng)絡(luò)地址和 Windows 轉(zhuǎn)發(fā)對(duì)不上尤其在用了自定義局域網(wǎng)或代理工具時(shí)。解決思路分三步確認(rèn)容器端口綁定docker ps看PORTS列是否有0.0.0.0:8080-8080/tcp。在 WSL2 內(nèi)部測curl http://127.0.0.1:8080/health如果通說明容器沒問題。在 Windows 側(cè)試curl http://localhost:8080/health如果通說明映射正常。如果 Windows 側(cè)不通最簡單粗暴的辦法是用netsh interface portproxy手動(dòng)設(shè)置端口轉(zhuǎn)發(fā)或者把 Docker 容器改用network_mode: host不推薦但本地調(diào)試很直接。重啟 WSL 后 IP 會(huì)變所以盡量依賴localhost轉(zhuǎn)發(fā)而不是寫死某個(gè) WSL IP。6.2 Docker daemon 無法訪問剛配置好 Docker Engine 時(shí)經(jīng)常會(huì)遇到Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?先執(zhí)行sudo service docker status看看服務(wù)狀態(tài)。如果顯示 running但還是連接失敗十有八九是當(dāng)前用戶沒有權(quán)限訪問/var/run/docker.sock。確認(rèn)是否已加入 docker 組并重新打開終端。如果服務(wù)沒起來直接啟動(dòng)sudo service docker start。要注意的是WSL2 默認(rèn)不啟動(dòng) systemd很多教程里的systemctl enable docker并不會(huì)生效反而會(huì)誤導(dǎo)。老老實(shí)實(shí)用service才是 WSL 里的主流玩法。6.3 飛書消息不回復(fù)的排查流程我在這塊卡了大半晚上。后來總結(jié)出固定的排查順序先確認(rèn)長連接是否正常。看日志里有沒WebSocket connected。再確認(rèn)消息事件是否到達(dá)。給機(jī)器人發(fā)消息日志里是否有收到事件的記錄。然后確認(rèn)模型調(diào)用是否成功。用上一節(jié)提到的內(nèi)部測試命令先驗(yàn)證。最后看是否有報(bào)錯(cuò)堆棧比如權(quán)限不足、加密失敗、超時(shí)。最坑的是事件到達(dá)但回復(fù)失敗。原因是飛書要求回復(fù)消息前先拿到message_id和 chat 類型我的第一次配置里漏了權(quán)限OpenClaw 后臺(tái)只報(bào)了一個(gè)通用錯(cuò)誤。建議先把im:message和im:message.send權(quán)限都加上慢慢排查。6.4 時(shí)區(qū)、日志和容器重啟問題日志時(shí)間默認(rèn)是 UTC和北京時(shí)間差 8 小時(shí)排查問題時(shí)容易產(chǎn)生混淆。所以我在.env里設(shè)置了TZAsia/Shanghai容器內(nèi)日志就跟本地時(shí)間一致了。另外容器重啟后如果數(shù)據(jù)丟失通常是忘了掛載 volume。OpenClaw 的配置、日志、持久化數(shù)據(jù)務(wù)必映射出來我給目錄說明都寫好了別偷懶。6.5 常見錯(cuò)誤速查表下表是這次部署中高頻出現(xiàn)的錯(cuò)誤和對(duì)應(yīng)手段錯(cuò)誤現(xiàn)象可能原因解決動(dòng)作Docker daemon 無法連接服務(wù)未啟動(dòng) / 當(dāng)前用戶無權(quán)限sudo service docker start將用戶加入 docker 組后重新登錄容器頻繁重啟缺少環(huán)境變量或鏡像版本不兼容查看docker compose logs補(bǔ)全.env后重啟飛書收不到消息事件長連接未啟用 / 權(quán)限未發(fā)布開啟 WebSocket 模式發(fā)布應(yīng)用版本飛書加密解密失敗Encrypt Key 不一致在.env和飛書后臺(tái)同時(shí)比對(duì)Qwen 返回 401API Key 錯(cuò)誤重新生成 DashScope API KeyQwen 返回 404Base URL 路徑或模型名不對(duì)檢查/v1是否缺失模型名改為qwen-plus等模型調(diào)用超時(shí)默認(rèn)超時(shí)太短調(diào)大QWEN_TIMEOUTWindows 訪問不到容器服務(wù)WSL2 端口映射異常從 WSL 內(nèi)先測curl 127.0.0.1再排查 Windows 轉(zhuǎn)發(fā)7. 踩坑后的幾點(diǎn)個(gè)人體會(huì)這次部署折騰下來我最大的感觸是先把基礎(chǔ)鏈路單獨(dú)驗(yàn)證再去拼起來效率會(huì)高很多。我一開始一窩蜂全部配好結(jié)果飛書、模型、容器混在一起出了錯(cuò)根本不知道是誰的問題。后來一步步拆開驗(yàn)證先測 Docker再測模型再測飛書很快就把問題定位了。還有一點(diǎn)是長連接模式真的比回調(diào)模式省心?；卣{(diào)模式下你不僅要有公網(wǎng)地址還要配 HTTPS 證書本地調(diào)試非常痛苦。飛書長連接讓本地自托管機(jī)器人的復(fù)雜度降了一個(gè)量級(jí)。如果你也只是在 Windows 上自用建議直接采用這個(gè)方案別在公網(wǎng)回調(diào)上浪費(fèi)時(shí)間。如果你要長期跑記得把容器設(shè)置成開機(jī)自動(dòng)啟動(dòng)并額外寫一個(gè) WSL 開機(jī)啟動(dòng) Docker 服務(wù)的計(jì)劃任務(wù)。我一開始忽略了這點(diǎn)系統(tǒng)重啟之后發(fā)現(xiàn)容器沒起來飛書機(jī)器人“失聯(lián)”了一上午。把這些細(xì)節(jié)準(zhǔn)備好剩下的就是把模型調(diào)優(yōu)和工具玩法慢慢打磨了。