1. OpenClaw 在 Windows 上到底能做什么為什么值得本地部署OpenClaw 是近期在 GitHub 上增長(zhǎng)很快的 AI Agent 框架很多人把它叫做「開(kāi)源版 AI Agent 操作系統(tǒng)」。它和普通聊天工具最大的區(qū)別在于普通工具是你問(wèn)一句它答一句而 OpenClaw 是你給一個(gè)任務(wù)它會(huì)自己拆步驟、調(diào)工具、抓網(wǎng)頁(yè)、讀文件、寫(xiě)代碼最后把結(jié)果交給你。比如你說(shuō)「幫我總結(jié)今天的 AI 新聞」它會(huì)自動(dòng)搜索、抓取網(wǎng)頁(yè)、閱讀內(nèi)容、生成總結(jié)整個(gè)過(guò)程不需要你手動(dòng)干預(yù)。那為什么要在 Windows 本地部署而不是直接用網(wǎng)頁(yè)版原因有三個(gè)。第一是數(shù)據(jù)可控你的文件、GitHub 倉(cāng)庫(kù)、本地筆記都在自己機(jī)器上Agent 讀取和處理都不出本地。第二是模型可換你可以接云端大模型也可以用 Ollama 跑本地模型靈活度比固定網(wǎng)頁(yè)服務(wù)高很多。第三是插件可擴(kuò)展OpenClaw 的 Skills 系統(tǒng)允許你裝 GitHub 操作、瀏覽器自動(dòng)化、文件系統(tǒng)等插件等于給 Agent 裝上了手腳。適合誰(shuí)來(lái)跟做這篇教程如果你滿(mǎn)足下面任意一條就可以繼續(xù)往下看會(huì)用命令行基本操作、裝過(guò) Python、想讓 AI 幫自己自動(dòng)處理重復(fù)任務(wù)、對(duì) AI Agent 開(kāi)發(fā)感興趣。不需要你懂深度學(xué)習(xí)也不需要顯卡普通 Windows 筆記本就能跑起來(lái)。我實(shí)測(cè)下來(lái)整個(gè)流程分四塊環(huán)境準(zhǔn)備、拉源碼裝依賴(lài)、配置模型通道、啟動(dòng)驗(yàn)證。其中最容易卡住的地方不是安裝本身而是模型接入配置——很多人源碼跑起來(lái)了但 Agent 一執(zhí)行任務(wù)就報(bào) 401 或者連接失敗。所以這篇會(huì)把配置部分寫(xiě)細(xì)并且用統(tǒng)一的 Key/API 通道來(lái)接入模型服務(wù)避免你在多個(gè)平臺(tái)之間來(lái)回切換。先明確一個(gè)概念OpenClaw 本身不提供模型它只是一個(gè)調(diào)度框架。你需要給它一個(gè)能調(diào)用的模型接口它才能思考。這個(gè)接口可以是官方 API也可以是兼容 OpenAI 協(xié)議的統(tǒng)一通道。后面第 3 節(jié)會(huì)給出可直接復(fù)制的配置片段。2. 環(huán)境準(zhǔn)備與依賴(lài)安裝Python、Git、虛擬環(huán)境一個(gè)都不能少Windows 上部署 OpenClaw第一步是把基礎(chǔ)環(huán)境搭好。很多人跳過(guò)這步直接 clone 代碼結(jié)果pip install報(bào)一堆編譯錯(cuò)誤回頭再補(bǔ)環(huán)境反而更費(fèi)時(shí)間。所以按順序來(lái)。Python 推薦 3.10 及以上版本3.11 或 3.12 都可以。去 python.org 下載 Windows 安裝包時(shí)記得勾選「Add Python to PATH」這一步漏了后面命令行會(huì)找不到 python。裝完打開(kāi) PowerShell 驗(yàn)證python --version pip --version正常輸出類(lèi)似Python 3.11.9和pip 24.x。如果提示不是內(nèi)部命令說(shuō)明 PATH 沒(méi)配好重新運(yùn)行安裝包選 Modify 補(bǔ)上。Git 同樣去 git-scm.com 下載安裝時(shí)保持默認(rèn)選項(xiàng)即可。驗(yàn)證git --version接下來(lái)是虛擬環(huán)境。這一步很多人省略但強(qiáng)烈建議做因?yàn)?OpenClaw 依賴(lài)較多裝到全局環(huán)境容易和別的項(xiàng)目沖突。在你想放項(xiàng)目的目錄下執(zhí)行python -m venv openclaw-env .\openclaw-env\Scripts\Activate.ps1激活成功后命令行前面會(huì)出現(xiàn)(openclaw-env)。如果 PowerShell 提示執(zhí)行策略限制用這行臨時(shí)放開(kāi)Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass然后拉源碼git clone https://github.com/openclaw/openclaw cd openclaw進(jìn)入目錄后先看一眼根目錄有什么文件。如果存在requirements.txt就執(zhí)行pip install -r requirements.txt如果只有pyproject.toml新版項(xiàng)目常見(jiàn)就用pip install .這里有個(gè)坑要提醒Windows 上部分依賴(lài)需要 C 編譯工具如果報(bào)Microsoft Visual C 14.0 or greater is required去裝一個(gè) Visual Studio Build Tools勾選「使用 C 的桌面開(kāi)發(fā)」即可。裝完重新執(zhí)行 pip 命令。依賴(lài)裝完后建議再跑一次pip list確認(rèn)關(guān)鍵包在列表里比如openai、httpx、pydantic這些。到這一步環(huán)境就算齊了接下來(lái)進(jìn)入配置環(huán)節(jié)。3. 模型接入配置用統(tǒng)一 Key/API 通道填好 Base URL、Key 和 Model ID這是整篇最關(guān)鍵的一節(jié)。OpenClaw 啟動(dòng)后要調(diào)用模型而模型調(diào)用需要三個(gè)東西Base URL、API Key、Model ID。三者缺一不可任何一個(gè)寫(xiě)錯(cuò)都會(huì)導(dǎo)致任務(wù)執(zhí)行失敗。我推薦用統(tǒng)一通道來(lái)管理 Key好處是一個(gè) Key 可以切換不同模型不用為每個(gè)模型單獨(dú)注冊(cè)和配置。TaoToken 就是這樣一個(gè)通道官網(wǎng)在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先去控制臺(tái)創(chuàng)建一個(gè) Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 創(chuàng)建入口在 API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后在 OpenClaw 項(xiàng)目根目錄創(chuàng)建配置文件。不同版本配置文件名可能不同常見(jiàn)的是.env或config.toml。先看項(xiàng)目里有沒(méi)有config.example.toml或.env.example有就復(fù)制一份改名。如果是.env形式寫(xiě)入OPENAI_API_KEYsk-你的TaoToken密鑰 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODELgpt-4o-mini如果是config.toml形式寫(xiě)入[llm] provider openai base_url https://taotoken.net/api api_key sk-你的TaoToken密鑰 model gpt-4o-mini temperature 0.7 max_tokens 4096注意 Base URL 結(jié)尾不要多加/v1OpenClaw 內(nèi)部一般會(huì)自己拼接路徑多寫(xiě)反而會(huì) 404。Model ID 要和你通道里支持的模型名一致不確定的話先去模型對(duì)話頁(yè)面確認(rèn)可用模型 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算用本地 Ollama 模型配置改成[llm] provider ollama base_url http://localhost:11434 model llama3Ollama 不需要 API Key但要先ollama run llama3把模型拉下來(lái)。本地模型的好處是零成本、數(shù)據(jù)不出機(jī)器缺點(diǎn)是推理速度和效果取決于你的硬件。配置寫(xiě)完后建議用一個(gè)最小腳本先驗(yàn)證通道是否通再啟動(dòng) OpenClaw。這樣能把「配置錯(cuò)誤」和「框架錯(cuò)誤」分開(kāi)排查。驗(yàn)證腳本from openai import OpenAI client OpenAI( api_keysk-你的TaoToken密鑰, base_urlhttps://taotoken.net/api ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 回復(fù)通道正常}] ) print(resp.choices[0].message.content)能打印出「通道正?！咕驼f(shuō)明 Base URL、Key、Model ID 三件套沒(méi)問(wèn)題可以進(jìn)入下一步。4. 啟動(dòng) OpenClaw 并跑通第一個(gè) Agent 任務(wù)配置驗(yàn)證通過(guò)后回到項(xiàng)目目錄啟動(dòng)主程序python main.py如果項(xiàng)目入口是別的文件名比如app.py或run.py看 README 里的啟動(dòng)說(shuō)明。啟動(dòng)成功后終端會(huì)顯示監(jiān)聽(tīng)端口或交互提示符。有些版本會(huì)起一個(gè)本地 Web 界面默認(rèn)在http://localhost:8000或http://localhost:3000瀏覽器打開(kāi)就能看到任務(wù)輸入框。先跑一個(gè)最簡(jiǎn)單的任務(wù)驗(yàn)證鏈路summarize todays AI news正常情況下你會(huì)看到 Agent 分步驟輸出先調(diào)用搜索工具、再抓取網(wǎng)頁(yè)、然后閱讀、最后生成總結(jié)。這個(gè)過(guò)程可能需要幾十秒取決于模型響應(yīng)速度和網(wǎng)頁(yè)數(shù)量。如果任務(wù)涉及 GitHub 操作需要先裝 Skills 插件。OpenClaw 的插件系統(tǒng)叫 Skills安裝命令類(lèi)似openclaw install github裝完后 Agent 就能分析倉(cāng)庫(kù)、生成 README、創(chuàng)建 PR。插件安裝后建議重啟一次主程序讓插件注冊(cè)生效。再試一個(gè)文件處理任務(wù)比如讓它讀取本地某個(gè)目錄下的 Markdown 文件并生成摘要。這類(lèi)任務(wù)能驗(yàn)證文件系統(tǒng)插件是否正常工作。如果報(bào)權(quán)限錯(cuò)誤檢查你啟動(dòng)程序的目錄是否有讀寫(xiě)權(quán)限。跑通第一個(gè)任務(wù)后你可以嘗試更復(fù)雜的組合任務(wù)比如「抓取某個(gè) GitHub 項(xiàng)目的最近 10 個(gè) issue總結(jié)成日?qǐng)?bào)并保存到本地文件」。這種任務(wù)會(huì)同時(shí)用到搜索、GitHub、文件系統(tǒng)三個(gè)插件是檢驗(yàn)配置完整性的好方式。實(shí)測(cè)下來(lái)第一次跑復(fù)雜任務(wù)時(shí)最容易出現(xiàn)的是超時(shí)。原因是默認(rèn)超時(shí)時(shí)間較短而多步任務(wù)耗時(shí)較長(zhǎng)。可以在配置里把timeout調(diào)到 120 秒以上。另外如果任務(wù)步驟太多模型可能會(huì)「忘記」前面的上下文這時(shí)候需要開(kāi)啟框架的記憶功能或分步執(zhí)行。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices 逐個(gè)擊破這一節(jié)把部署過(guò)程中最常遇到的幾個(gè)報(bào)錯(cuò)列出來(lái)對(duì)照解決。報(bào)錯(cuò)一401 UnauthorizedError code: 401 - {error: {message: Invalid API key}}原因通常是 Key 寫(xiě)錯(cuò)、Key 過(guò)期、或者 Base URL 和 Key 不匹配。排查順序先確認(rèn).env或config.toml里的 Key 沒(méi)有多余空格和引號(hào)再用第 3 節(jié)的最小腳本單獨(dú)測(cè)一次如果腳本也報(bào) 401說(shuō)明 Key 本身有問(wèn)題去控制臺(tái)重新生成一個(gè)。注意不要把 Key 提交到 Git 倉(cāng)庫(kù)建議把配置文件加入.gitignore。報(bào)錯(cuò)二local proxy failed / connection refusedopenai.APIConnectionError: Connection error.這個(gè)報(bào)錯(cuò)說(shuō)明程序連不上 Base URL。檢查三點(diǎn)Base URL 是否寫(xiě)成了https://taotoken.net/api而不是別的地址本機(jī)網(wǎng)絡(luò)是否能正常訪問(wèn)該域名有沒(méi)有誤配系統(tǒng)代理導(dǎo)致請(qǐng)求被攔截。如果你在配置里寫(xiě)了http://localhost:11434但 Ollama 沒(méi)啟動(dòng)也會(huì)報(bào)這個(gè)錯(cuò)先運(yùn)行ollama serve。報(bào)錯(cuò)三reading choices / KeyError: choicesKeyError: choices這個(gè)報(bào)錯(cuò)通常不是模型的問(wèn)題而是返回結(jié)構(gòu)和你代碼里取值的路徑不一致。常見(jiàn)原因是 Base URL 多寫(xiě)了/v1導(dǎo)致請(qǐng)求打到了錯(cuò)誤端點(diǎn)返回了一個(gè)不含choices字段的響應(yīng)。把 Base URL 改回https://taotoken.net/api再試。另一個(gè)原因是 Model ID 寫(xiě)錯(cuò)通道返回了錯(cuò)誤信息而不是正常補(bǔ)全結(jié)果打印完整響應(yīng)體就能看到真實(shí)錯(cuò)誤。報(bào)錯(cuò)四OAuth / 認(rèn)證回調(diào)失敗如果你用的是需要 OAuth 的模型服務(wù)回調(diào)地址必須和注冊(cè)時(shí)填寫(xiě)的一致。本地部署時(shí)回調(diào)一般填http://localhost:端口/callback。端口被占用會(huì)導(dǎo)致回調(diào)失敗換個(gè)端口即可。報(bào)錯(cuò)五pip 安裝依賴(lài)失敗error: Microsoft Visual C 14.0 or greater is required裝 Visual Studio Build Tools勾選 C 桌面開(kāi)發(fā)組件。如果報(bào)的是某個(gè)包版本沖突先pip install --upgrade pip再單獨(dú)裝沖突的包最后重跑pip install .。排查時(shí)有個(gè)通用技巧把日志級(jí)別調(diào)到 DEBUG能看到完整的請(qǐng)求 URL 和響應(yīng)體比猜要快得多。大多數(shù)配置問(wèn)題在日志里一眼就能看出來(lái)。6. 長(zhǎng)期跑 Agent 任務(wù)怎么把通道和額度管理好跑通第一個(gè)任務(wù)只是開(kāi)始。如果你打算長(zhǎng)期用 OpenClaw 做自動(dòng)化比如每天定時(shí)抓新聞、定期分析倉(cāng)庫(kù)、自動(dòng)生成報(bào)告那模型調(diào)用的穩(wěn)定性和成本就需要認(rèn)真管理。首先是 Key 的管理。不要把 Key 硬編碼在代碼里統(tǒng)一放配置文件并加入.gitignore。如果多人協(xié)作每個(gè)人用自己的 Key避免互相影響額度。TaoToken 的控制臺(tái)可以查看用量和余額地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 定期看一眼能避免任務(wù)跑到一半因?yàn)轭~度不足中斷。其次是模型選擇。日常簡(jiǎn)單任務(wù)用便宜的小模型就夠復(fù)雜推理任務(wù)再切到大模型。統(tǒng)一通道的好處就在這里改一個(gè) Model ID 就能切換不用改代碼。如果你主要做編碼類(lèi) Agent 任務(wù)可以關(guān)注 Coding Plan 方案 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它針對(duì)長(zhǎng)期編碼場(chǎng)景做了額度優(yōu)化。第三是任務(wù)編排。OpenClaw 支持定時(shí)任務(wù)和鏈?zhǔn)饺蝿?wù)建議把長(zhǎng)任務(wù)拆成多個(gè)短步驟每步單獨(dú)驗(yàn)證。這樣某一步失敗時(shí)不用從頭重跑也方便定位問(wèn)題。日志要保留至少保留最近幾天的執(zhí)行記錄出問(wèn)題時(shí)能回溯。第四是本地模型和云端模型的混合使用。敏感數(shù)據(jù)處理用本地 Ollama需要強(qiáng)推理的任務(wù)走云端通道。OpenClaw 支持配置多個(gè) provider在任務(wù)級(jí)別指定用哪個(gè)靈活度很高。最后提醒一點(diǎn)Agent 自動(dòng)執(zhí)行任務(wù)時(shí)可能會(huì)調(diào)用文件寫(xiě)入、GitHub 操作等有副作用的工具建議先在測(cè)試倉(cāng)庫(kù)和測(cè)試目錄里跑確認(rèn)行為符合預(yù)期后再放到生產(chǎn)環(huán)境。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置細(xì)節(jié)和參數(shù)說(shuō)明都可以在里面查到。需要新建或管理 Key 時(shí)走 API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先體驗(yàn)?zāi)Ｐ蛯?duì)話效果可以直接打開(kāi) https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 試幾個(gè) prompt確認(rèn)模型行為符合你的預(yù)期再接入 OpenClaw。