OpenClaw 在 Windows 上的簡單安裝教程從零到跑通的完整記錄先說明一下這篇教程聊的是 OpenClaw——一個(gè)能在本地跑起來的 AI 智能體Agent框架。這么說可能有點(diǎn)抽象換個(gè)角度你可以把它理解成一個(gè)“機(jī)器人管家”給它接上飛書、微信等聊天渠道再配上一個(gè)大模型比如通義千問它就能自動回復(fù)消息、定時(shí)執(zhí)行任務(wù)、幫你處理信息流。之前我在這類工具上踩過不少坑尤其是 Windows 環(huán)境下的部署網(wǎng)上資料零零散散所以這次把自己的安裝過程完整記下來寫給那些想在 Windows 上快速把 OpenClaw 跑起來的朋友參考。這個(gè)教程適合誰一句話總結(jié)想本地部署 AI 智能體但不想碰 Linux、不想折騰復(fù)雜環(huán)境的 Windows 用戶。你不需要太深的編程基礎(chǔ)只要會打開命令行、能照著復(fù)制粘貼基本就能跟著走完。1. 安裝前先搞清楚思路OpenClaw 到底解決什么問題1.1 別急著敲命令先弄懂 OpenClaw 是什么在做任何安裝操作之前我建議你先花三分鐘理解一下這個(gè)工具的本質(zhì)。OpenClaw 本質(zhì)上是一個(gè)開源的個(gè)人 AI 助理框架它做的事情可以拆成三層接入層負(fù)責(zé)連接各種聊天平臺比如飛書、Discord、Telegram讓智能體有一個(gè)“耳朵”和“嘴巴”。大腦層調(diào)用大模型 APIOpenAI、通義千問、DeepSeek 等把接收到的消息轉(zhuǎn)化成意圖和動作。執(zhí)行層根據(jù)意圖調(diào)用工具比如查天氣、寫文件、跑腳本、發(fā)通知。這三層結(jié)構(gòu)聽起來復(fù)雜但安裝的時(shí)候你不需要全部搞懂只需要知道一點(diǎn)OpenClaw 的核心是一個(gè) Node.js 服務(wù)外加一個(gè)配置文件。你給它一個(gè) API Key告訴它“你的大腦用哪個(gè)模型”然后告訴它“你在哪個(gè)渠道上值班”它就能開始干活了。為什么我強(qiáng)調(diào)要先理解這個(gè)框架因?yàn)槲以趯?shí)際安裝過程中發(fā)現(xiàn)很多人卡住的根本原因不是命令不會敲而是不知道自己在裝什么、改了什么配置文件會對哪個(gè)環(huán)節(jié)產(chǎn)生影響。比如說你改了模型配置沒生效可能是因?yàn)榉?wù)沒重啟服務(wù)沒重啟可能是因?yàn)槟悴恢?OpenClaw 是讀取哪個(gè)文件來加載配置的。1.2 Windows 環(huán)境的兩條路線WSL vs 原生安裝OpenClaw 的官方文檔更傾向于 Linux 和 macOS 環(huán)境Windows 上則要自己做選擇。目前主流路線有兩條路線優(yōu)點(diǎn)缺點(diǎn)適合人群WSL2 Docker環(huán)境干凈、隔離性好、卸載方便需要安裝 WSL2、Docker Desktop占磁盤空間想長期使用、對穩(wěn)定性要求高的人Windows 原生 Node.js安裝快、不依賴虛擬機(jī)、直接跑偶爾遇到依賴編譯問題環(huán)境相對“臟”只想快速試一下、機(jī)器配置一般的人這兩條路線我都實(shí)測過。先說我個(gè)人的結(jié)論如果你只是想在 Windows 上體驗(yàn)一下 OpenClaw建議直接用原生 Node.js 方式如果你想把它當(dāng)作長期服務(wù)運(yùn)行建議用 Docker 方式。為什么這么建議原生方式的問題在于OpenClaw 的一些依賴包在 Windows 上偶爾需要編譯如果你的電腦沒裝 Visual Studio Build Tools可能就會卡在某個(gè)包的安裝上。而 Docker 方式雖然前期準(zhǔn)備麻煩一點(diǎn)但一旦跑起來后續(xù)升級、遷移、備份都是在容器層面操作省心很多。我在下文會給出兩條路線的完整步驟。就像做飯先備菜一樣我把每一條路線需要的環(huán)境清單先列出來你對照自己的情況二選一就行。2. 環(huán)境準(zhǔn)備Windows 上裝 OpenClaw 的必修課2.1 路線一原生 Node.js 安裝速度快適合先試水如果不是選 Docker 方式那第一步就是裝 Node.js。注意這里有一個(gè)關(guān)鍵版本要求OpenClaw 的要求是 Node.js 18 或以上版本我自己實(shí)測用的是 20 LTS 版本運(yùn)行很穩(wěn)定。去 Node.js 官網(wǎng)下載 LTS 版本安裝包就是帶“長期支持”標(biāo)識的那個(gè)一路下一步安裝即可。裝完之后我們需要驗(yàn)證一下環(huán)境變量是否生效。打開 PowerShell 或者 CMD輸入node -v npm -v如果能看到版本號說明 Node.js 和 npm 都可用。如果提示“不是內(nèi)部或外部命令”說明環(huán)境變量沒配好。這時(shí)候去檢查“系統(tǒng)屬性”里的 PATH 變量看有沒有包含 Node.js 的安裝目錄一般在C:\Program Files\nodejs\。2.2 路線二WSL2 Docker 部署環(huán)境干凈適合長期跑如果選擇 Docker 路線前置條件會多一些我一項(xiàng)一項(xiàng)拆開說。第一步安裝 WSL2。在 Windows 11 或者較新的 Windows 10 上打開管理員權(quán)限的 PowerShell執(zhí)行wsl --install這條命令會自動幫你啟用 WSL 功能并安裝默認(rèn)的 Ubuntu 發(fā)行版。裝完之后重啟電腦系統(tǒng)會要求你設(shè)置一個(gè) Linux 用戶名和密碼這個(gè)密碼是 WSL 里的 sudo 密碼建議用個(gè)能記住的后面經(jīng)常要用。第二步安裝 Docker Desktop。下載 Docker Desktop for Windows安裝時(shí)保持默認(rèn)選項(xiàng)即可。啟動 Docker Desktop然后在設(shè)置里找到“Resources” - “WSL Integration”把 “Enable integration with my default WSL distro” 勾選上并在下面的列表里選擇你剛裝的 Ubuntu。這一步很關(guān)鍵漏掉它的話后面在 WSL 里敲 docker 命令會提示連不上 Docker 引擎。我當(dāng)時(shí)就在這里卡了一回一直以為是 Docker 沒啟動其實(shí)是 WSL 集成沒打開。第三步驗(yàn)證 Docker 環(huán)境。打開 WSL 終端在 PowerShell 里輸入wsl即可進(jìn)入執(zhí)行docker --version docker compose version只要能看到版本信息環(huán)境就算備好了。2.3 無論如何都需要準(zhǔn)備的東西Git 和 API Key不管走哪條路線你都需要 Git因?yàn)?OpenClaw 的源碼托管在 GitHub 上安裝過程通常要克隆倉庫。Windows 下安裝 Git 很簡單官網(wǎng)下載安裝包一路下一步。裝完后在 PowerShell 里驗(yàn)證一下git --version然后是大模型 API Key。OpenClaw 本身不帶大模型它需要調(diào)外部模型 API。目前兼容 OpenAI 格式的接口都可以用包括 OpenAI 官方 Key、通義千問的 DashScope Key、DeepSeek 等。國內(nèi)用戶我建議優(yōu)先選通義千問或者 DeepSeek因?yàn)榫W(wǎng)絡(luò)連接穩(wěn)定不用折騰代理問題。這個(gè) Key 你先去對應(yīng)的模型服務(wù)商官網(wǎng)申請好后面配置那一步會用到。提示模型 API Key 屬于敏感信息平時(shí)不要截圖發(fā)到群里配置到 OpenClaw 后也注意別把配置文件上傳到公開倉庫。3. 兩種安裝方式實(shí)測從一鍵腳本到 Docker Compose3.1 方式A原生 Windows 一鍵腳本安裝新手首選如果你選擇原生路線OpenClaw 提供了一個(gè)自動安裝腳本這是最簡單的方式。在 PowerShell 中執(zhí)行irm https://raw.githubusercontent.com/openclaw/openclaw/main/install.ps1 | iex這里解釋一下這條命令是在干什么irm是 PowerShell 里下載網(wǎng)頁內(nèi)容的命令下載回來的是一個(gè)安裝腳本然后再通過管道符傳給iex來執(zhí)行。整個(gè)過程就是在下載并運(yùn)行遠(yuǎn)程腳本所以如果 Windows 安全中心彈出警告需要手動允許運(yùn)行。腳本執(zhí)行后會自動完成幾件事安裝必要的 npm 依賴包、生成默認(rèn)配置文件、創(chuàng)建 .openclaw 目錄。整個(gè)過程可能需要幾分鐘取決于網(wǎng)絡(luò)狀況。等腳本跑完OpenClaw 并沒有直接啟動而是提示你還需要進(jìn)行配置。這時(shí)候我們先驗(yàn)證安裝是否成功執(zhí)行openclaw --version如果能看到版本號說明安裝成功。如果提示找不到命令可能需要重啟一下 PowerShell 讓 PATH 變量生效。還有一點(diǎn)要提醒在國內(nèi)網(wǎng)絡(luò)環(huán)境下從 GitHub 下載腳本或依賴有時(shí)會比較慢甚至失敗。如果你遇到這種情況可以使用國內(nèi)的鏡像源或者多試幾次。npm 的話可以臨時(shí)設(shè)置一下 registry 為淘寶鏡像npm config set registry https://registry.npmmirror.com3.2 方式BDocker Compose 部署生產(chǎn)環(huán)境推薦Docker 路線稍微多幾個(gè)步驟但邏輯更清晰。首先在 WSL 終端里克隆 OpenClaw 的倉庫git clone https://github.com/openclaw/openclaw.git cd openclaw倉庫里有現(xiàn)成的 Docker Compose 文件。執(zhí)行docker compose up -d這里解釋一下-d參數(shù)的作用它讓容器在后臺運(yùn)行這樣你關(guān)閉終端后服務(wù)不會停止。第一次執(zhí)行時(shí)Compose 會拉取鏡像、構(gòu)建容器耗時(shí)比較長要耐心等。啟動完成后執(zhí)行docker ps如果看到 openclaw 相關(guān)的容器狀態(tài)是 Up說明服務(wù)已經(jīng)跑起來了。后續(xù)查看日志的話用docker logs -f openclaw這跟原生方式相比的好處是所有運(yùn)行環(huán)境都被隔離在容器里不會污染 Windows 系統(tǒng)。你要是哪天不想用了直接docker compose down就能清理。3.3 安裝完成后做好基礎(chǔ)驗(yàn)證不管用哪種方式裝好都建議走一遍基礎(chǔ)驗(yàn)證流程確認(rèn)服務(wù)真的在跑。OpenClaw 安裝完成后會在本地起一個(gè) HTTP 服務(wù)默認(rèn)端口是 3000。你在瀏覽器里訪問http://localhost:3000如果能看到一個(gè)簡單的頁面或者 JSON 響應(yīng)說明服務(wù)運(yùn)行正常。我當(dāng)時(shí)看到的是類似{status:ok}的 JSON 數(shù)據(jù)確認(rèn)服務(wù)在線。另外OpenClaw 在安裝時(shí)會創(chuàng)建一個(gè).openclaw目錄用來存放配置和日志。原生安裝下這個(gè)目錄在用戶主目錄下C:\Users\你的用戶名\.openclaw\Docker 方式下則在倉庫目錄里。后面改配置、看日志都在這里。4. 核心配置把 OpenClaw 真正用起來的關(guān)鍵設(shè)置4.1 修改主配置告訴智能體用什么模型安裝只是第一步真正讓 OpenClaw“聽懂人話”的是配置。OpenClaw 的主配置文件是一個(gè) JSON 文件在.openclaw目錄下名叫openclaw.json。用編輯器打開這個(gè)文件你會看到類似這樣的結(jié)構(gòu){ model: { provider: openai, name: gpt-4o-mini, apiKey: sk-xxxx } }這里面最核心的三個(gè)字段就是provider模型供應(yīng)商、name模型名稱、apiKeyAPI Key。如果使用通義千問以 DashScope 的兼容模式為例配置大致如下{ model: { provider: custom, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, name: qwen-plus, apiKey: sk-你的千問APIKey } }這里要注意baseURL是模型服務(wù)商提供的接口地址。OpenAI 格式的接口都長得差不多所以很多國產(chǎn)模型服務(wù)商都支持這種“兼容模式”直接填對地址就能用。提示有些模型服務(wù)商的 SDK 地址和 OpenAI 兼容地址不一樣配置時(shí)一定以對方文檔里寫的“OpenAI 兼容地址”為準(zhǔn)。填錯(cuò)了模型名字或者地址啟動時(shí)會在日志里報(bào) 404 或 401 錯(cuò)誤。4.2 Channel 配置讓智能體在哪個(gè)渠道值班OpenClaw 支持多個(gè)渠道官方叫 Channel其實(shí)就是消息平臺。配置文件里通常有一塊channels的配置比如飛書{ channels: { feishu: { appId: cli_xxx, appSecret: your_app_secret } } }這里的 appId 和 appSecret 需要你在飛書開放平臺創(chuàng)建應(yīng)用后獲取。創(chuàng)建應(yīng)用的時(shí)候記得給應(yīng)用添加“機(jī)器人”能力然后發(fā)布上線否則消息發(fā)不到你的智能體上。如果在同一臺機(jī)器上跑多個(gè) OpenClaw 實(shí)例或者給不同任務(wù)接不同渠道你可以在啟動時(shí)通過命令行參數(shù)指定用哪個(gè) Channelopenclaw start --channel feishu如果沒有加這個(gè)參數(shù)OpenClaw 會啟動配置里啟用的所有 Channel。這個(gè)細(xì)節(jié)很容易被忽略——我在給飛書機(jī)器人配完之后發(fā)現(xiàn)另一個(gè)測試渠道也在同步啟動日志里全是無關(guān)消息排查了半天才發(fā)現(xiàn)是沒指定 Channel。4.3 配置完必須重啟服務(wù)改配置不生效問題這一點(diǎn)我必須單獨(dú)拿出來說因?yàn)檫@是我在多個(gè)群里看到新手問得最多的問題——改了配置文件但智能體行為沒變化。原因很簡單OpenClaw 在啟動時(shí)一次性加載配置運(yùn)行期間不會自動監(jiān)聽文件變化。所以每次改完openclaw.json都需要重啟服務(wù)才能生效。原生方式下在 PowerShell 里執(zhí)行openclaw stop openclaw startDocker 方式下因?yàn)榕渲梦募ǔ燧d在容器里你需要重建容器讓配置重新加載docker compose restart openclaw4.4 給智能體寫一個(gè)“人設(shè)”系統(tǒng)提示詞配置說實(shí)話很多人在這一步就放棄了——以為裝好了就能用結(jié)果發(fā)現(xiàn)智能體回消息冷冰冰的完全沒有“助理”的感覺。別急O(jiān)penClaw 是支持配置系統(tǒng)提示詞System Prompt的。你可以在配置里加一個(gè)persona字段用一段自然語言描述智能體的性格、職責(zé)和行為邊界。比如{ persona: 你是一個(gè)耐心的個(gè)人助理回答簡潔明了不確定的事情如實(shí)說明不編造信息。 }這個(gè)字段會作為初始指令傳給大模型相當(dāng)于給智能體“畫了一個(gè)人設(shè)”。用好這個(gè)配置體驗(yàn)會提升一大截。5. 踩坑實(shí)錄從報(bào)錯(cuò)到權(quán)限的高頻問題排查5.1 Agent failed before reply: session file locked這個(gè)報(bào)錯(cuò)我印象太深了它的完整信息長這樣agent failed before reply: session file locked (timeout 60000ms)出現(xiàn)這個(gè)報(bào)錯(cuò)的原因通常是上一個(gè) OpenClaw 進(jìn)程沒有正常退出導(dǎo)致會話文件被鎖住。比如你直接關(guān)掉了 PowerShell 窗口而不是執(zhí)行openclaw stop進(jìn)程其實(shí)還在后臺跑著下次啟動時(shí)新的進(jìn)程發(fā)現(xiàn)會話文件被舊進(jìn)程占用等了一分鐘還沒等到鎖釋放就直接報(bào)錯(cuò)。解決辦法也很直接打開任務(wù)管理器找到所有 node 進(jìn)程右鍵結(jié)束任務(wù)。刪除.openclaw目錄下的會話緩存文件通常在sessions子目錄下。重新啟動 OpenClaw。這里最需要記住的是OpenClaw 不是關(guān)窗口就能停掉的要養(yǎng)成用openclaw stop停服務(wù)的習(xí)慣。5.2 飛書輸出容易被截?cái)嘤信笥言跓崴言~里提到“openclaw在飛書輸出容易被截?cái)唷蔽乙灿龅竭^類似問題。這其實(shí)是飛書機(jī)器人自身的消息長度限制在作祟飛書單條消息最長 4096 字節(jié)超出就會被截?cái)唷＝鉀Q思路是從 OpenClaw 側(cè)輸出做文章在配置里找到輸出相關(guān)設(shè)置開啟“分片發(fā)送”或“分段落發(fā)送”機(jī)制讓智能體把長內(nèi)容拆成多條消息發(fā)出來。如果 OpenClaw 版本沒有這個(gè)功能備選方案是在提示詞里明確要求“分點(diǎn)回答控制單次回復(fù)長度”靠模型自己收斂長度。這個(gè)方法治標(biāo)不治本但實(shí)測能緩解大部分截?cái)鄦栴}。比較長的文本輸出比如代碼、長報(bào)告建議還是讓智能體寫成文件再把文件發(fā)給你。5.3 端口占用、版本兼容等高頻問題速查這里我把這段時(shí)間遇到過的、以及身邊朋友常問的問題整理成一張速查表問題現(xiàn)象可能原因解決辦法啟動報(bào) EADDRINUSE3000 端口被其他程序占用換端口配置里改port字段或先找出占用進(jìn)程殺掉模型回復(fù)報(bào) 401API Key 填錯(cuò)或失效檢查openclaw.json里的 apiKey確認(rèn)沒有多余空格模型回復(fù)報(bào) 404model 名稱填錯(cuò)或 provider 地址不對對照模型服務(wù)商文檔確認(rèn) model 標(biāo)識和 baseURL啟動后 Web 頁面打不開服務(wù)沒真正啟動或端口被防火墻攔截看日志有無報(bào)錯(cuò)檢查 Windows 防火墻是否允許 node 入站W(wǎng)SL 里執(zhí)行 docker 失敗Docker Desktop 未啟動或 WSL 集成未開啟動 Docker Desktop檢查 WSL Integration 設(shè)置PowerShell 提示執(zhí)行策略不允許腳本系統(tǒng)默認(rèn)禁止運(yùn)行 ps1 腳本管理員權(quán)限執(zhí)行Set-ExecutionPolicy RemoteSigned修改配置后不生效沒有重啟服務(wù)執(zhí)行openclaw stop后再openclaw start5.4 其他安裝過程中可能遇到的小麻煩還有一個(gè)比較隱蔽的問題Windows 原生方式下如果安裝依賴時(shí)看到類似node-gyp相關(guān)的報(bào)錯(cuò)說明某些 npm 包需要本地編譯。這通常是因?yàn)闄C(jī)器上沒有安裝 C 編譯工具。解決辦法是管理員權(quán)限的 PowerShell 執(zhí)行npm install --global windows-build-tools不過這個(gè)包比較老在 Windows 11 上偶爾會失敗。我的建議是與其折騰編譯環(huán)境不如直接切到 Docker 路線省得在這一步消耗耐心。另外如果你是國內(nèi)網(wǎng)絡(luò)環(huán)境npm 裝依賴超時(shí)是很常見的事。除了上面提到的換 registry 鏡像還可以設(shè)置 npm 的超時(shí)時(shí)間npm config set fetch-retry-mintimeout 20000 npm config set fetch-retry-maxtimeout 1200005.5 日志排查問題的風(fēng)向標(biāo)最后再講一下日志。遇到任何詭異問題第一時(shí)間別瞎猜去看日志。原生方式下日志在.openclaw/logs目錄里Docker 方式下直接用docker logs openclaw查看。OpenClaw 的日志會記錄每一個(gè)步驟模型請求發(fā)出去了沒有、渠道消息收到?jīng)]有、工具調(diào)用成功沒有。排查問題的時(shí)候按照“消息入口 - 模型處理 - 消息出口”的順序依次定位很快就能找出卡在哪一環(huán)。我調(diào)試過的絕大多數(shù)問題最后都是在日志里找到答案的。寫在最后的一點(diǎn)體會這套流程走下來我的真實(shí)感受是OpenClaw 的門檻其實(shí)不高但 Windows 下的安裝確實(shí)比 Linux 多一些彎路。如果你按照上面的順序操作先把環(huán)境準(zhǔn)備工作做足再選擇一條路線裝到能跑通最后把配置一項(xiàng)一項(xiàng)過一遍大概率一個(gè)小時(shí)以內(nèi)就能看到一個(gè)能回消息的智能體。從我自己的實(shí)際體驗(yàn)來說還有一個(gè)建議剛開始不要配置太多渠道和功能。我見過不少人一上來就想把飛書、Discord、Telegram 全接通結(jié)果某個(gè)渠道配置錯(cuò)了導(dǎo)致整體啟動失敗排查起來特別費(fèi)勁。先用一個(gè)渠道、一個(gè)模型跑通全流程再加功能這是最穩(wěn)妥的順序。另外OpenClaw 的配置項(xiàng)其實(shí)有很多細(xì)節(jié)包括記憶、任務(wù)調(diào)度、定時(shí)消息等這些等你把基礎(chǔ)跑通之后再慢慢研究也不遲。工具這東西能用起來永遠(yuǎn)比“看懂所有文檔”更有價(jià)值。希望這篇教程能幫你少踩幾個(gè)坑順利在 Windows 上把 OpenClaw 跑起來。