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