Windows下部署OpenClaw：从WSL2到本地大模型的AI代理实战指南

简介：面向 Windows 开发者的 OpenClaw 部署指南，以 WSL2+Ubuntu 源码编译和 Git Bash 直接运行两条路径为主线，覆盖环境准备、依赖安装、源码编译、配置向导，以及 SSH 权限异常、国内镜像加速等常见排错场景，适合需要在本机快速跑通开源项目的初中级开发者。资料包共 4 个文件，以 md 操作文档、inscode 配置、html 说明页和 gitignore 版本控制文件为主，整体仅 15KB，属于轻量代码与文档组合。其中 md 文档为完整步骤说明，inscode 与 html 提供可直接参考的配置与页面，gitignore 便于纳入现有工程管理。内容还包含阿里云百炼 API 模型接入指引、常用命令与技能管理说明，并提醒通过官方渠道获取正版资源以规避安全风险。目前已有 114 人学习下载，可作为 Windows 下部署 OpenClaw 的操作索引与排错手册。

1. OpenClaw是什么，为什么值得在Windows上折腾

1.1 一句话讲透OpenClaw的定位

OpenClaw在我眼里就是一个自托管的AI代理运行壳。它本身不提供大模型，也不绑定某个固定平台，而是把“大模型”和“你能用到的各种操作入口”粘在一起：你通过聊天窗口给它发指令，它调用背后的模型做规划，再通过一系列工具或skill去执行具体动作。比如让它读某个目录下的日志、查一下天气、整理一份Markdown笔记，甚至跑一段脚本，这些都可以在对话里完成。

相比直接调用大模型API，这类Agent框架真正的价值在于“行动力”。普通AI对话只能吐文字，OpenClaw这类框架会把回复变成可执行的动作。它比较适合个人开发者、重度自动化玩家，以及小团队里想低成本搭一个内部助理的场景。而且它支持接本地模型，意味着你可以不依赖外部API，数据也能留在自己手里。我在Windows上把它跑起来之后，直观感受是：以前要手动敲命令的事，现在可以动动嘴让它去办了。

1.2 Windows部署三条路线怎么选

在Windows上部署OpenClaw，我实际试下来有三条路可以走：原生Node.js、WSL2加Node.js、Docker Desktop。我先把三个方案的基本情况列出来。

我个人给出的结论是：如果你打算认真用起来，别在纯Windows上死磕，直接WSL2。Windows原生的Node生态不是不能跑，而是很多依赖是为Linux准备的，一旦遇到编译问题，网上搜到的排错经验八成都是Linux命令，你在PowerShell里根本执行不了，只会越搞越乱。WSL2本质上就是个轻量虚拟机，但和Windows共用文件系统，日常管理不难受。

2. 环境准备：WSL2、Docker和基础运行时

2.1 先装WSL2

Windows 11和较新的Windows 10都支持一句话安装。用管理员权限打开PowerShell或者Windows Terminal，执行：

wsl --install -d Ubuntu

装完重启，系统会提示你设置Linux用户名和密码。这里有个容易被忽略的点：这个用户名不必和Windows账户一致，但密码一定要记牢，后面sudo提权经常要用。

装好之后我建议先执行一次sudo apt update && sudo apt upgrade，把系统包更新到最新，免得后面装依赖时碰到过期的索引。如果你机器上已经装了Docker Desktop，记得在设置里把WSL2 integration打开，不然Docker和WSL2各管各的，很别扭。

2.2 在WSL2里安装基础工具链

OpenClaw不管走源码还是npm，都离不开一套基础环境。我的习惯是先把这些装上：

sudo apt install -y git curl build-essential python3 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs

node版本尽量选20 LTS或更新，太老版本的依赖装不上。装完用node -v和npm -v确认一下版本号。

如果你打算走Docker路线，Docker Desktop的WSL2后端是必开的。我的经验是：Docker方案隔离性好，但前期拉镜像和配置数据卷稍显繁琐。对于OpenClaw这种需要频繁改配置和看日志的项目，我本人更倾向直接在WSL2里跑源码。

2.3 文件路径和性能的两个提醒

WSL2里访问Windows侧的文件是通过/mnt/c/...挂载的。表面上很方便，但跨文件系统读写性能差距很大，npm install时尤其明显，经常慢到怀疑人生。所以项目目录一定放在WSL2内部，比如~/projects/openclaw，不要放在/mnt/c/Users/xxx/...下面。这是我在实际使用中踩过的最不值当的一个坑。

另一个提醒是内存占用。WSL2默认会拿到不少内存，如果你只是跑一个轻量Agent，建议在%UserProfile%\.wslconfig里限制一下：

[wsl2] memory=4GB swap=2GB

改完执行wsl --shutdown再重进WSL2生效。

3. 安装OpenClaw：从源码到首次启动

3.1 获取项目代码的几种方式

OpenClaw目前主流的获取方式有npm全局安装和源码克隆两种。npm全局安装最省事，一条命令就能装好，适合只使用、不改源码的人。我因为要看启动日志和自定义一些skill，选择了源码克隆。下面是通用的思路：

git clone <官方仓库地址> openclaw cd openclaw cp .env.example .env # 如果仓库提供环境变量模板 npm install

这里有个细节：安装依赖时如果报node-gyp相关的错误，说明系统里缺编译工具链。回到上一节，把build-essential和python3装上基本能解决。

3.2 初始化配置与目录结构

首次安装完成后，一般会有一个初始化引导，用来生成配置目录和默认配置。如果你不想走交互式引导，自己写配置也完全可以。我用的是配置模板加手动修改的方式，重点设置这几个字段：

• 数据目录：日志、会话记录、skill文件会存在这里。
• 控制界面端口：默认开启的Web管理界面监听端口。
• 模型配置：指定provider和model名。

以我当时的配置片段为例，结构大致是这样：

{ "dataDir": "~/.openclaw", "controlPort": 3000, "modelProvider": "ollama", "model": "llama3.2:3b", "ollama": { "baseUrl": "http://localhost:11434/v1" } }

这份配置的键名以你拿到的模板为准，不用死记，重点是理解每个模块是干什么的。

3.3 首次启动看到什么

启动命令通常是npm run dev或者直接执行项目提供的启动脚本。正常启动后，命令行会打印出类似这样的信息：

Control UI available at http://localhost:3000 Agent started, waiting for messages...

看到这两行，说明核心进程没问题。如果只有第一行而第二行一直不出现，或者干脆第一行变成Control UI did not start，那就是踩到我后面要重点说的坑了，先不着急。

4. 连接本地大模型：Ollama与API两条路

4.1 先用Ollama把链路跑通

OpenClaw支持对接多种模型来源，但对个人部署来说，最快见效的是Ollama。Ollama可以理解成一个大模型运行器，把模型权重下载到本地，然后暴露一个OpenAI兼容的接口，应用层不用改太多代码。

在WSL2里装Ollama很简单：

curl -fsSL https://ollama.com/install.sh | sh

装完先拉一个体积适中、推理速度快的模型。我建议新手先用小参数量模型做连通性测试，别一上来就跑70B，那不光硬盘受不了，显存和内存也扛不住。比如：

ollama pull llama3.2:3b ollama list

ollama list输出的模型全名非常关键。后面OpenClaw配置里的model字段必须和它完全一致，少一个标签或者拼错一个字母，Agent就会直接报错。

4.2 最常见的unknown model错误

我遇到过一种典型报错，现象是Agent启动后发消息，很快回复：

agent failed before reply: unknown model: deepseek

光看这句话，第一反应是模型没下载。实际上我确实下载了，问题出在模型名不匹配。我在配置里写了deepseek，但Ollama里实际拉下来的模型名是带标签的，比如deepseek-r1:7b，或者压根是另一个名字。

解决办法很简单：先用ollama list拿到准确的模型标识，然后修改OpenClaw配置里的model字段。配置改完不用重装，重启服务再试一遍就行。

这里也建议大家养一个调试习惯：先直接调一下Ollama的接口，看模型是不是真的可用：

curl http://localhost:11434/v1/models

如果返回的JSON里能看到你拉取的模型名，那问题就集中在OpenClaw配置这一侧。

4.3 无本地模型时的API与NIM扩展思路

不是所有人都愿意在本地跑模型。OpenClaw也支持OpenAI兼容接口，也就是说，你可以把它指向任何提供这类接口的推理服务，只要在配置里把baseUrl换成服务地址，再把apiKey填进去即可。

如果你有NVIDIA显卡且对推理性能有要求，OpenClaw也能通过NVIDIA NIM的方式接模型。NIM本质上也是一种OpenAI兼容推理服务，配置思路和普通API一致，区别主要是模型运行依赖NVIDIA的容器环境。这个玩法对硬件有要求，适合后面进阶再看。

5. 真正有用的配置：消息渠道、Skill与日常使用

5.1 消息渠道怎么接

OpenClaw默认自带一个Web对话界面，用来测试完全够了。但要用成日常工具，还得接上你习惯的聊天渠道。根据官方文档，目前比较成熟的有Discord、Telegram、企业微信服务号这类。接入方式大多是在配置里填一个Bot Token，然后启动后它会主动建立连接。

这里我必须提醒一句：微信相关的支持，建议优先看官方渠道，使用服务号或者官方认可的方式。不要为了图方便去用非官方协议，稳定性和账号安全都没法保证。我的做法是先接Web界面把所有功能测通，再考虑渠道，能省很多排查时间。

5.2 Skill机制：让Agent学会干活

Skill是OpenClaw里最实用的机制，可以把常见操作封装成一个个可执行的小单元。比如我给自己配了一个“读日志”的skill：

{ "skills": [ { "name": "read_openclaw_log", "description": "读取OpenClaw运行日志的最后100行", "command": "tail -n 100 ~/.openclaw/logs/agent.log" } ] }

配置完成后，我在对话里说“看一下今天日志有没有报错”，Agent就会调用这个skill去执行命令，再把输出整理成结论回复给我。这比我自己用tail看日志方便得多，也是我认为OpenClaw真正提升效率的地方。

Skill的设计原则是一次只做一件事，命令要明确。别试图写一个“万能skill”，那会让Agent在判断时非常混乱。我实际调了几次后，最后把日常用到的操作拆成了五六个独立skill。

5.3 人设、上下文与隐私边界

既然Agent能执行命令，那它的人设和边界必须提前设定好。OpenClaw支持在配置里指定系统提示词，我建议至少包含三块内容：职责范围、可执行动作的边界、遇到不确定事项时的处理方式。比如我让它默认只读取日志，不执行删除操作；涉及网络请求前必须二次确认。

上下文长度也值得关注。本地模型如果上下文窗口有限，长时间会话会把前面的关键信息挤掉。我的做法是让Agent每隔一段时间把重要结论写进本地的Markdown笔记，后续对话通过检索笔记来获取长期记忆，而不是依赖无限长的上下文。

5.4 服务常驻的简单方案

Windows下最让人头疼的是服务常驻。WSL2里的service命令覆盖有限，用起来不直观。我目前的做法是给OpenClaw写一个systemd unit文件，让它在WSL2启动后自动拉起。如果你的WSL2版本不支持systemd，也可以用tmux或者screen包一层，效果差不多：

tmux new -s openclaw cd ~/projects/openclaw && npm run dev # Ctrl+B 再按 D 退出回话，服务继续在后台跑

6. 踩坑记录：Control UI不启动、端口占用和排查路径

6.1 完整排查链路：control UI did not start

这个报错我遇到时非常懵，服务进程没有退出，但打开浏览器就是访问不到管理界面。后来我总结出一条排查顺序，建议大家按顺序来，一步都别跳。

第一步，看控制台日志。很多报错信息其实已经打在日志里了，只是被刷屏刷掉了。用npm run dev前台启动，或者tail -f日志文件，等几秒看有没有异常堆栈。

第二步，查端口占用。如果Control UI没有启动，多半是它想监听的端口已经被别的进程占了。用：

netstat -tlnp | grep 3000

这里的3000换成你配置里的controlPort。看到LISTEN但进程不是OpenClaw，那就说明端口冲突，改个端口即可。

第三步，检查Windows浏览器能不能访问。WSL2里的服务对Windows来说默认是能通过localhost访问的，但如果没生效，可以先用WSL2内部的curl http://localhost:3000测试，能通而浏览器打不开，就检查Windows防火墙和WSL2的端口转发。常见解决办法是执行一次：

wsl --shutdown

重启WSL2后让端口转发规则重新生成。

6.2 PowerShell执行策略与路径空格

如果你坚持在原生Windows下运行，首先会遇到PowerShell执行策略问题。某些安装脚本需要设置执行策略，报错通常是“无法加载文件，因为在此系统上禁止运行脚本”。我建议对当前用户放开限制，而不要动系统级策略：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

另一个很容易忽视的是路径空格。Windows用户名如果带空格，比如C:\Users\Zhang San，很多npm脚本会解析出错。处理方式是用引号包住路径，或者干脆迁移到WSL2，眼不见心不烦。

6.3 日志查看与重启的正确姿势

OpenClaw运行久了之后，日志会滚动得很快。我习惯把日志按大小分割，配置里设置一个maxLogSize之类的参数，避免单文件无限膨胀。排查问题的时候，不要直接开整个日志，先用tail -n 200锁定最后阶段的记录，再配合关键字搜索：

grep -i "error" ~/.openclaw/logs/agent.log | tail -n 50

重启服务时，最稳妥的顺序是：先停进程，再确认端口释放，最后重新启动。如果发现某些状态没恢复，可以删掉临时文件目录再启动。这一套流程我复现过很多次，基本能解决大部分启动异常。

最后分享一个我的个人习惯：每次改完配置，我会先跑一个最小冒烟测试，发一条“请查看最近三条日志”这样的指令，确认Agent能收到消息、模型能回复、skill能执行，三件事都通过后再把服务挂后台。这套检查看起来简单，但能帮你省掉很多后面排查问题的力气。

本文还有配套的精品资源，点击获取