Windows 11原生安装OpenClaw：本地模型配置与工具调用指南

OpenClaw在Windows 11上装起来，理论上一套文档跟着走很快，但我实际磕磕碰碰花了好几天。倒不是软件本身有多难，而是绝大多数说明默认你在Linux或macOS上跑，默认你能顺利拉取任何国际资源，默认你手头有现成的云端API密钥。这篇东西就是专门把这三个“默认”补掉：环境是Windows 11原生（不装WSL、不装Docker），网络是内地常规网络（全程不需要任何特殊通道），模型是本地模型（不注册云服务、数据不出本机）。我尽量把每一步拆细，把自己踩过的坑和排查思路都写进去，帮你少走弯路。

1. 安装前先理清三件事：运行环境、目录路径、网络策略

正式动手前，我强烈建议你先花十分钟把这三件事想清楚。它们看起来跟OpenClaw本身无关，但在我实际安装过程中，百分之七十的报错都源自这三件事没处理好。

1.1 运行时组合：纯Windows下为什么Python和Node都要备好

OpenClaw的运行依赖里同时出现了Python和Node.js两套运行时。Python负责核心逻辑、工具插件和本地模型接口的调用，Node.js则承担一部分前端界面和自动化相关组件。这在Linux上不是问题，因为系统自带或者包管理器很容易补齐，但在Windows 11原生环境下，很多人只装了其中一个，导致安装到一半才报“找不到node”或“找不到python”，非常尴尬。

我的建议是Python选择3.11或3.12的64位版本，Node选择18或20的LTS版本。不要追最新版的大版本，OpenClaw这类框架对运行时的兼容性往往滞后于新版本发布，用最稳妥的版本能省掉很多“莫名其妙”的错误。另外安装Python时一定要勾选“Add Python to PATH”，Node安装时保持默认的“Add to PATH”选项。这两个选项一旦漏掉，后面在PowerShell里执行python或node命令都会提示找不到命令，而你在安装时根本察觉不到问题，到激活虚拟环境那一步才炸出来。

为什么不建议为了省事去装WSL或Docker？我之前也想过直接用WSL里的Linux环境，但OpenClaw在Windows 11原生支持本来就是为了让普通用户能直接在桌面上跑，WSL会把文件系统隔离、网络映射、端口转发这些复杂度全带进来，调试起来反而更麻烦。更关键的是，如果你要调用Windows本地的文件、软件或浏览器自动化能力，原生模式下工具链是直通的，WSL里还得做一层桥接。既然要“纯Windows 11”，就老老实实在原生环境把两套运行时配好，一劳永逸。

1.2 目录规划：中文路径和长路径是两个隐形炸弹

项目装到哪个目录，这个问题很多人会忽略，但它直接决定了你能不能装成功。OpenClaw的依赖树很深，尤其是前端相关组件安装完之后，会出现一长串嵌套目录。Windows系统默认的路径长度上限是260个字符，一旦依赖目录层级超过这个数，安装过程就会报“文件名对目标文件夹可能太长”之类的错误。解决办法是提前开启系统的长路径支持：

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

执行完这条命令后需要重启电脑才能生效。别偷懒，这一步做不做，直接决定你后面npm install会不会在中途挂掉。

比长路径更坑的是中文路径。如果你的Windows登录用户名是中文，那么用户主目录就会是“C:\Users\中文名”，项目如果放在这个目录下，很多工具链在处理路径时会出现编码错乱或者直接拒绝执行。我不去深究每一个组件的编码实现，但经验是：OneDrive同步目录、桌面目录、带空格的Program Files目录，都是安装这类开源框架的高危区。我最后把项目放在一个纯英文路径下，比如D盘的某个多层目录，全路径只有字母、数字和下划线。这个习惯帮我躲过了后续一大半的诡异报错。

1.3 网络策略：先配镜像再拉依赖，顺序不能反

这一点非常关键，甚至可以说是整个安装过程最核心的第一步。我发现很多人会先去把源码克隆下来，然后跑pip install或npm install，结果卡在一个又一个超时上，回头还以为是软件本身的问题。真正合理的顺序是：先把网络层的基础打好，再开始拉代码装依赖。

具体来说，安装完Python和Node之后，第一件事就是把包管理器的镜像源配好。国内可用的镜像源很多，有各大云厂商提供的软件源，也有高校维护的镜像站，你选择自己网络环境下访问速度最快、最稳定的那个即可：

pip config set global.index-url <你选定的PyPI镜像地址> npm config set registry <你选定的npm镜像地址>

为什么我说顺序不能反？因为pip和npm在解析依赖时，如果默认源连不通，它会反复重试并且超时等待，这段时间足够让人误以为机器卡死了。而配好镜像之后，整个依赖安装过程通常几分钟就能跑完。这个经验适用于所有Python和Node项目，不仅仅针对OpenClaw。

网络策略还要考虑到模型文件的下载。模型文件动辄几个GB，很多资源托管在境外，内地网络直连速度非常慢。你需要提前想清楚模型从哪个渠道获取，优先选择提供国内直连加速的模型托管平台，或者找一些下载速度稳定的公开模型源。这事在安装阶段就要有预案，别等OpenClaw都装好了，卡在“拉模型拉不下来”这步。

2. Windows 11 原生环境搭设的过程记录

环境准备阶段我走了不少弯路，这里把最终跑通的完整过程原原本本写出来。每一步后面我会说明当时踩雷的情况和验证方法，方便你对照排查。

2.1 基础组件安装：Git、Python、Node的版本选择和验证

首先安装Git for Windows。Git是拉取OpenClaw源码和后续更新的必需品，安装包从官网下载即可，国内下载速度一般能接受，如果遇到下载慢，可以找一些软件分发渠道来获取安装包。安装过程中唯一需要注意的就是在“Adjusting your PATH environment”这一步选择“Git from the command line and also from 3rd-party software”，确保git命令可以在PowerShell里直接用。

然后是Python。我装的是Python 3.12的64位版本，安装器里记得勾选“Add python.exe to PATH”，然后选择“Install now”。装完之后打开一个新的PowerShell窗口验证一下：

git --version python --version node -v npm -v

这四个命令能全部输出版本号，说明基础环境已经通了。这里我想特别强调一点：一定要新开一个PowerShell窗口再验证。很多人装完软件后直接在旧窗口里执行命令，因为PATH环境变量是窗口启动时读取的，旧窗口读不到新安装的路径，就会给出“命令不存在”的假象。我当时排查这个问题花了不少时间，一度以为系统环境变量没生效。

2.2 两条必改系统配置：PowerShell执行策略与UTF-8输出

Windows默认的PowerShell执行策略是Restricted，会阻止运行本地的脚本文件。OpenClaw的启动脚本以.ps1结尾，如果不改策略，双击或命令行启动时会直接报“无法加载文件，因为在此系统上禁止运行脚本”。在管理员权限或无管理员权限下分别执行下面的命令：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

RemoteSigned的意思是：本地创建的脚本可以运行，从网络下载的脚本需要签名。这是日常开发最常用也最安全的策略组合，不要为了省事直接设成Unrestricted。改完可以用Get-ExecutionPolicy确认一下输出确实是RemoteSigned。

另一条容易被忽视的配置是控制台编码。Windows中文版默认代码页是GBK（936），而OpenClaw的日志输出是UTF-8编码。两者不一致的后果就是：程序明明跑起来了，控制台里却全是乱码方块，排查问题根本没法看日志。可以在启动前临时执行chcp 65001把代码页切到UTF-8，或者更彻底一点，在系统环境变量里新增PYTHONUTF8=1，强制Python的IO层使用UTF-8编码。两个方法我都试过，后者的体验更省心，因为不用每次打开终端都手敲一遍切换命令。

2.3 拿到OpenClaw源码并完成依赖安装

源码获取我最推荐的方式是直接去项目仓库页面下载zip压缩包，然后用git初始化接入本地版本管理。这个方案听起来有点绕，但在内地网络环境下反而最省时间。git clone命令在拉取较大仓库时经常遇到中途断流，而压缩包方式可以借助浏览器已有的下载能力，断点续传也更友好。下载完成后解压到之前规划的纯英文路径下，进入主目录：

cd D:\apps\openclaw-xxx python -m venv venv .\venv\Scripts\Activate.ps1

创建虚拟环境这步不能省。Windows下直接把依赖装到全局Python环境里，很容易跟其他项目产生版本冲突，尤其是某些科学计算相关的底层库。虚拟环境激活后，命令行提示符前面会出现venv字样，这时候再安装依赖才是安全的：

pip install -r requirements.txt

如果项目里同时有package.json，说明还需要安装Node侧依赖：

npm install

这两个安装过程在配好镜像源的前提下通常都比较顺畅。如果中途报错，先不要慌着搜错误码，先确认是不是网络超时引起的下载失败。我遇到过几次“retrying”提示，其实都是默认源连接超时导致的。网络超时类报错的重试多次没有意义，正确姿势是把镜像源重新确认一遍，然后清掉缓存再装。pip可以执行pip cache purge，npm可以执行npm cache clean --force，然后重来。依赖安装完成的标志是没有报错输出，且exit code为0。

3. 本地模型的挑选与接口对接

OpenClaw这类框架的核心价值就是把本地大语言模型变成能调用工具的智能体，所以模型选型这步直接决定最后的体验。这一节我不讲晦涩的技术原理，只给可以照着抄的选型思路和配置方法。

3.1 先定显存和模型规模的匹配关系

本地模型的推理速度和效果，最直接的影响因素是你的GPU显存。如果电脑没有独立显卡或显存很小，也不是完全不能用，但速度和上下文长度会受很大限制。我自己测试过的匹配关系大致如下：

如果你的目标是让OpenClaw稳定地完成工具调用，我建议先从一个7B或8B的量化模型开始。很多人的误区是一上来就追求最大参数模型，结果显存不够导致推理服务频繁重启，反而以为框架有问题。工具调用链路对模型的“稳定性”要求比对“聪明程度”要求更高，先跑通全链路，再换大模型，这个顺序是最省事的。

模型选好之后，你需要一个本地推理服务来加载它。市面上的本地模型加载器基本都兼容OpenAI风格的接口协议，这意味着OpenClaw不需要专门的适配器，只需要把接口地址指过去即可。我用的推理服务默认监听在127.0.0.1的11434端口，启动完成之后，可以用一条命令验证接口是否存活：

curl http://127.0.0.1:11434/v1/models

这条命令返回一个包含模型名称列表的JSON就说明推理服务正常。注意，这里返回的模型名称和你在OpenClaw配置里填写的model字段必须完全一致，大小写、连字符都不能差。

3.2 OpenAI兼容接口的配置要点

OpenClaw的配置文件里，LLM相关配置通常长这样：

llm: provider: openai-compatible base_url: http://127.0.0.1:11434/v1 api_key: local-key model: qwen3-8b temperature: 0.7 max_tokens: 8192

provider那里填openai-compatible，目的是告诉OpenClaw按OpenAI的接口协议去连接。base_url一定要写到你推理服务的/v1路径，很多人在这一步漏掉了/v1后缀，导致握手失败。api_key随便填一个非空字符串就行，本地推理服务不会真正校验密钥，但你留空的话，很多依赖库会在请求时直接报400错误，这是SDK层的非空校验逻辑，所以宁可填一个占位符也别留空。

model字段要和上一步curl返回的名称一致。如果你不确定，可以在推理服务的管理界面里看到当前已加载的模型名。temperature建议一开始设0.5到0.7之间。本地小模型的随机性本来就比云端大模型高，temperature设太高会让它自由发挥，不肯按工具调用的格式来；设太低又会让输出显得机械。我反复调过之后，0.6左右是个不错的起点。

还有一个容易忽略的参数max_tokens。工具调用场景下，模型需要先思考、再输出工具调用指令、再接收工具返回结果、再输出最终回答，整条链路会消耗较多token。如果用默认的2048，经常出现回答一半就截断的情况。我设成8192之后，复杂任务明显顺畅很多。如果你的显存不大，可以适当缩小上下文窗口但保持max_tokens足够大，这是一个权衡。

3.3 Embedding与记忆检索也必须留在本机

很多人只把对话模型配置到了本地，却忘了OpenClaw的记忆和检索功能还需要一个embedding模型。如果embedding的地址没有配置，框架可能会尝试连接默认的云端地址，导致要么慢到超时，要么数据悄悄出了本机。这跟“本地模型”的初衷是相违背的，我在配置时专门做了检查。

解决方案很简单：再下一个体积比较小的embedding模型，然后在配置文件里单独指定embedding的接口地址：

embedding: base_url: http://127.0.0.1:11434/v1 model: bge-m3

embedding模型的显存占用通常比对话模型小很多，跑起来几乎不占资源。如果你平时用不到记忆检索功能，可以在配置里把memory或rag相关开关直接关掉，也是彻底本地化的办法。我个人的建议是保留embedding但给一个本地地址，因为OpenClaw的很多工具选择逻辑会用到向量相似度，本地embedding能让整个链路都封闭在内网，无论是隐私性还是响应速度都有保障。

4. 初始化配置与首次任务实测

OpenClaw装好、模型也接上了，下一步就是初始化配置并跑通第一个任务。这一节记录的是我的完整操作过程和调试思路。

4.1 配置文件里真正需要动的那几个字段

打开项目根目录下的配置文件，我发现里面字段很多，注释也密密麻麻。但真正需要关心的就几类：LLM配置、embedding配置、工具开关、服务端口。工具开关容易让人兴奋，因为列出来的每一项功能都很有吸引力，但我的建议是第一次只保留两到三个必须的工具。

为什么不要全开？因为每开启一个工具，它的描述和调用说明都会被塞进模型的系统提示词里，工具太多会让提示词体积变得很大，而小模型对长提示词的处理能力有限，注意力会被稀释，反而出现该调用工具的时候不调用的情况。我最初把所有工具都打开了，结果模型在简单任务上胡言乱语，关掉大部分工具后立刻恢复正常。这个经验算是比较深刻的教训了。

服务端口方面，OpenClaw默认会启动一个本地API服务和简单的管理界面，如果遇到端口冲突，可以直接在配置文件里改端口号，然后重启。首次启动时Windows防火墙会弹窗询问是否允许网络访问，如果你是纯本机使用，建议勾选“专用网络”允许访问，这样使用体验最顺畅。

4.2 第一个任务怎么选：能验证工具调用链路的小任务

配置完成后的第一个任务千万不要选那种复杂的“帮我整理桌面”之类的大活，因为一旦出问题，你很难判断是模型理解错了，还是工具调用链断了。我推荐的任务是这样的：让OpenClaw列出当前工作目录下的所有文件，并按文件名排序。

这个任务至少能验证四件事：模型是否能理解用户意图、是否能正确调用文件读取工具、工具返回结果是否能被模型接收、最终回答是否格式正常。执行后你会看到控制台里出现类似“调用工具：read_dir”的日志，然后工具返回一个文件列表，最后模型基于这个列表生成回答。看到这三步依次出现，说明核心链路已经通了。

如果你的第一次尝试连工具调用日志都没有，模型只是在聊天层面回应你“我无法直接查看文件”之类的，那问题多半不在框架本身，而在模型配置上，具体调参方向见下一小节。如果工具调用了但报错，优先看工具返回的具体错误信息，大多数是路径权限或编码问题。

4.3 模型只会聊天、不调用工具时的调参顺序

这是OpenClaw本地化使用最常遇到的问题，我自己也在这上面绊了很久。模型的通用能力很强，但在工具调用场景下，它需要学习一套特定的输出格式——先输出一个工具调用指令，然后停下来等待工具结果，再继续。本地小模型如果不适合工具任务，最常见的行为就是拒绝调用工具，或者把工具调用的JSON输出在普通文本里，导致解析失败。我建议的调参顺序是：

第一步，看日志，确认模型回包里有没有tool_call字段。把日志级别调整到debug，OpenClaw会打印模型返回的原始内容和工具解析结果。这一步能快速区分问题是出在“模型没生成工具调用”还是“框架解析失败”。

第二步，调整temperature。我把它从0.7降到0.3再跑了一次，模型老老实实开始输出工具调用了。本地模型对温度的敏感度比云端模型高，工具任务需要更确定的输出，所以温度偏低没毛病。

第三步，检查系统提示词。如果你手动修改过OpenClaw自带的系统提示词，尽量先恢复默认再测。默认提示词里对工具调用格式的说明是经过调优的，随便删改很容易打破模型对格式的认知。确认默认提示词能跑通之后，再按需微调。

第四步，考虑换更擅长工具调用的模型。不同模型对工具调用支持差异很大，有的模型的泛化能力强，有的模型明显对结构化输出有偏见。如果前面的调整都没用，花点时间换个模型版本或量化方式，比死磕强得多。我当时换了另一种量化格式的同类尺寸模型后，工具调用成功率直接上了一个台阶。

5. 原生Windows下我碰到的几个坑与排查思路

最后这部分，我把实际安装和运行中遇到的几个典型问题，连同排查思路一起记录下来。这些问题在Linux下很少见，但在Windows 11原生环境里几乎人人都会碰到至少一两个。

5.1 实时防护把启动文件拦了

第一次启动OpenClaw时，程序刚跑几秒就静默退出了，控制台连错误日志都没来得及打。我最初以为是配置问题，反复检查没有结果。后来打开Windows安全中心，发现“防火墙和网络保护”底下的“防护历史记录”里躺着一条记录，提示某个可执行文件被阻止。

解决方案很直接：把OpenClaw的项目目录和模型存放目录都加入Windows安全中心的排除项。操作路径是“病毒和威胁防护” -> “管理设置” -> “排除项” -> “添加或删除排除项”，选“文件夹”，然后把目录加进去。整个过程十几秒，但解决的是让人抓狂的“无缘无故退出”问题。

排查这类问题的思路，我想单独强调一下：Windows下凡是程序无任何提示就退出的，第一反应不要只盯项目文档，先去看系统安全软件的拦截记录。我后来帮朋友排查类似问题时，顺着这个思路基本都能快速定位。

5.2 端口占用与残留进程

运行中的OpenClaw如果被强制关闭或者断电，下次再启动时经常出现端口被占用的提示。本地推理服务也一样，我遇到过明明没在界面里看到进程，但启动新实例时提示11434端口已经被使用。这是因为旧进程其实还在后台挂着，只是没有窗口。

排查命令是：

netstat -ano | findstr 11434 tasklist | findstr <PID>

第一步先看端口被哪个PID占着，第二步查这个PID对应的进程名。确认是残留进程后直接结束即可：

taskkill /PID <PID> /F

这里有个小细节容易被忽略：如果端口被pid为4的System进程占用，通常是Windows系统服务或WSL相关功能在用，不要乱杀。这时优先考虑修改OpenClaw配置里的端口号，而不是去动系统进程。我为了省事，直接把本地API服务端口改成和默认端口不同的值，从此再也没被这个问题困扰过。

5.3 日志中文乱码

控制台里全是乱码方块，这个问题我在前面已经提过，但它值得单独列为一条坑。根因是Windows中文版默认代码页是GBK，而OpenClaw的日志和模型输出都是UTF-8。解决的完整方案涉及两个层面：系统层面和环境变量层面。

先执行chcp 65001切换当前终端代码页，这是临时的。然后设置环境变量PYTHONUTF8=1，让Python解释器在读写文件和控制台时都强制UTF-8。如果你用的是Windows Terminal而不是传统控制台，还可以在终端配置文件里把默认编码改成UTF-8。这样配置之后，中英文日志都能正常显示，模型输出的中文也不再是问号。

乱码问题看似小事，但它对调试效率影响极大。日志都看不清，什么问题都无从谈起。我后来在每一台新电脑上安装类似项目时，都会第一时间把编码设置好，这已经成了标准动作。

5.4 模型文件下载中断与损坏校验

本地模型文件动辄几个GB到几十GB，下载过程中断是常事。很多人下载完就直接加载，结果模型加载到一半报错，或者推理结果明显离谱。我当时的教训是：不要跳过校验步骤。

很多模型托管平台在下载页面会提供文件的SHA256校验值，有些会按分片提供哈希值。下载完成后，务必用工具计算一下本地文件的哈希，和官方值比对。Windows下可以用PowerShell的Get-FileHash命令，虽然大文件算哈希需要一点时间，但比起加载损坏模型后花几小时排查不可名状的推理错误，这点等待时间完全是值得的。

下载中断后的断点续传也值得一说。浏览器下载虽然支持续传，但前提是不能清空浏览器缓存。如果你用了下载工具，记得选择能保留临时分片的方式。我见过有人因为下载工具不支持分片，失败后从零开始重下，白白损失几个小时。

5.5 并发请求让本地推理排队卡死

最后一个坑是在多任务场景下踩到的。OpenClaw作为智能体框架，允许同时发起多个任务。云端API可以轻松应对并发，但本地模型推理资源有限，如果在同一个显存上并发跑多个任务，推理服务就会把请求排队，表面上看起来像是程序卡死了——任务列表里所有任务都停在“运行中”，但没有任何进展。

解决方法是把并发数限制到1，让任务串行执行。OpenClaw的配置里通常有max_workers或类似字段，设置为1即可。本地推理服务端也可以把并发请求数限制到1，双保险。我一开始以为限制并发会降低效率，实际跑下来发现，单并发时每个任务都能稳定完成，整体吞吐反而比分时复用显存要高，因为避免了排队时交错的显存分配开销。

如果你确实需要同时跑多个任务，另一个思路是给推理服务配置多个模型实例并分散到不同端口，但这需要更大的显存和更复杂的调度，性价比不高。至少目前阶段，串行执行是我用过最靠谱的方案。

这篇文章基本把我从零开始在Windows 11上装OpenClaw、接入本地模型、跑通首个任务的全过程都记录下来了。回头总结个人体会，最关键的其实就三件事：安装前把镜像源和路径规划做好，模型选择先小后大，遇到问题先看日志再动手改配置。只要这三件事做对了，剩下的基本就是等待模型下载、依赖安装这些流程化操作。如果你在安装过程中遇到这篇文章没覆盖到的奇怪问题，优先顺序是：看官方文档里的FAQ、看日志报错的第一行、搜错误信息里最独特的那段关键词，大概率能定位到方向。后面如果我在长时间使用中再碰到新坑，会继续补充更新。