1. 为什么我在本地部署了OpenClaw

1.1 OpenClaw到底解决什么问题

OpenClaw这个项目，第一次看到的时候我以为是某个游戏模组，后来仔细翻了项目说明才发现，它是一个把“AI助手”从云端拉回本地的开源工具。简单说，它给你提供了一个可以跑在你自己电脑上的智能助手服务，你可以让它处理文件、调用本地脚本、对接聊天界面，甚至把它当作一个家庭或小团队内部的统一入口。

我在本地跑通之后，最大的感受是：它把“安装一个AI服务”这件事的门槛降到了相当低的程度。你不需要自己从零搭模型服务，不需要手写一大堆API转发逻辑，也不需要面对云厂商那套复杂的鉴权体系。OpenClaw把整个链路整理成了几个标准步骤，装好依赖、填好配置、启动服务，一个可以直接访问的本地助手就起来了。

如果你手头正好有一台性能还行的电脑，又想在完全离线或纯局域网的环境里体验AI助手，那这个项目确实值得折腾一下。

1.2 本地部署 vs 云服务的取舍

很多朋友会问一个问题：现在云服务那么多，直接注册账号、调用API不就行了？为什么非要费劲在本地装一个OpenClaw？

我的回答通常分三点。第一，数据不出本地。你的文件、对话记录、脚本调用全都在自己机器上，没有传输到第三方服务器的过程，这在处理私人文档、公司内部资料时非常重要。第二，延迟低很多。局域网内访问不用走公网，响应速度直接快一个量级，而且断网照样能用。第三，可定制性完全不同。你可以改它的配置、接入自己的脚本工具、甚至换掉底层模型，这是闭源云端服务很难做到的。

当然，本地部署也有代价：你得自己维护环境、自己处理依赖冲突、自己排查各种报错。这篇文章后面写到的所有问题，几乎都是我在实际部署过程中真实踩过的。

1.3 适合谁来安装、需要什么基础

如果你是下面这几类人，OpenClaw大概率值得一试：

• 有局域网内使用AI助手的场景，比如办公室、实验室、家庭共享
• 对数据隐私比较敏感，不愿意把内容传到外部服务
• 想研究开源AI工具集成、想自己改造功能
• 平时用Windows，但愿意开一个WSL2环境来跑开发工具链

需要的基础其实不高。懂一点命令行操作、能看懂简单的配置文件就够。如果完全没接触过Node.js或Linux，也不用担心，这篇教程会把每一步都拆开讲清楚，照着操作就行。我最开始遇到的问题，十有八九你也会遇到，所以我专门整理了一节排查实录放在文末。

2. 部署前的环境准备：工具链选型与版本搭配

2.1 Windows用户的WSL2环境搭建

OpenClaw官方对Linux和macOS的支持比较顺滑，Windows下最省心的路径是先装WSL2，然后在WSL的Ubuntu环境里部署。这一点非常关键：如果你直接在Windows的CMD或PowerShell里去装OpenClaw的依赖，大概率会遇到各种路径分隔符、权限模型不一致带来的诡异报错。

WSL2的安装流程，我实测下来三步就够了。第一步，用管理员身份打开PowerShell，执行：

wsl --install

这条命令会默认安装Ubuntu并启用WSL2。第二步，重启电脑，系统会提示你设置Ubuntu的用户名和密码。第三步，验证一下环境是否正常：

wsl --status

正常的情况下，你会在输出里看到类似“默认版本: 2”的字样。这一步千万不要跳过，很多人装完WSL后直接把这一步忽略，结果后面启动OpenClaw时才发现内核版本不对，再回头找问题就非常痛苦。

另外，Windows Terminal强烈建议装一个，用它来操作WSL比默认的CMD舒服太多，而且多标签页在调试多窗口服务时非常有用。

2.2 Node.js、Git、Python的安装与验证

OpenClaw的核心运行环境是Node.js，所以Node版本是第一优先级。官方建议至少Node 18，我自己的经验是直接用Node 20 LTS，装在WSL里最稳。

这里有个比较普遍的坑：很多人直接在Windows里下载Node.js安装包，装完之后发现WSL里的Ubuntu根本调用不到这个Node。原因很简单，WSL是一个独立的Linux环境，和Windows的文件系统、环境变量并不共享。所以你必须在WSL内部重新装一遍。

推荐的方式是使用nvm管理Node版本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20

装完验证一下：

node -v npm -v

Git也顺手装一下，后面克隆源码和更新版本都要用：

sudo apt update sudo apt install -y git git --version

Python这边，OpenClaw的某些辅助脚本会用到Python 3，虽然不一定是核心依赖，但建议提前装好，避免某个功能模块启动时突然报缺少解释器：

sudo apt install -y python3 python3-pip python3 --version

2.3 Docker要不要装：我的建议

很多人一看到开源项目就先装Docker，觉得容器化部署最干净。OpenClaw确实提供了Docker镜像，如果你的目标环境是Linux服务器，用Docker跑确实方便。

但在本地自己调试的阶段，我建议先别碰Docker。原因很现实：Docker Desktop在Windows上吃内存吃得厉害，而且WSL2和Docker Desktop集成时经常出现虚拟化冲突。如果只是为了跑一个OpenClaw，直接在本机跑Node服务完全够用。

如果你确实是服务器部署场景，打算用Docker Compose，那后面再补装也不迟。实话说，我认识几个朋友第一次部署就全用Docker，最后排查网络问题时多了一层复杂度，反而把简单的事情搞复杂了。

这里我放一个建议对照表，方便你根据自己的场景选：

3. OpenClaw本体安装实操

3.1 最省事的安装方式：npm全局安装

OpenClaw把安装流程做得比我预想的简单，官方推荐的全局安装命令只有一条：

npm install -g openclaw

如果你的网络状况不太好，可以从镜像源安装，速度会快一些：

npm install -g openclaw --registry=https://registry.npmmirror.com

装完之后，先确认一下命令是否可用：

openclaw --version

这一步如果能看到版本号，说明核心安装已经没问题了。注意npm的全局bin目录是否在你的PATH里，如果提示找不到命令，多半是PATH没配置好。一般用nvm装的Node不会出现这个情况，如果你是用系统包管理器装的Node，那就需要检查一下环境变量。

3.2 源码克隆安装：什么时候需要这种方式

如果你只是正常使用，npm全局安装就够了。但如果你想改源码、调试问题，甚至给项目贡献代码，那就得走源码安装的路子。

源码安装也不复杂，克隆仓库然后安装依赖：

git clone https://github.com/openclaw/openclaw.git cd openclaw npm install

源码方式的好处是你能看到所有逻辑，坏处是依赖更新时需要手动拉取最新代码。我个人的做法是：正常用的时候用npm全局版本，需要调试或者看实现细节时再拉一份源码放在旁边参考。两个版本互不干扰。

3.3 配置文件示例与参数说明

OpenClaw启动后会在用户目录下生成一个配置目录，不同版本可能略有差异，但常见的配置文件大概长这样。这里给出一份我实际使用的基础配置，你可以直接复制改改就能用：

{ "server": { "host": "0.0.0.0", "port": 8080, "localMode": true }, "auth": { "token": "change-me-to-a-random-string", "allowLocalNetwork": true }, "model": { "provider": "local", "endpoint": "http://127.0.0.1:11434" }, "tools": { "allowFileAccess": true, "allowScriptExecution": false } }

这里几个字段值得多说一句。server.host决定服务监听在哪张网卡上，填127.0.0.1就只能在电脑本机访问，填0.0.0.0则允许局域网内其他设备通过IP访问。auth.token是访问凭证，在局域网环境下强烈建议改成一个足够随机的字符串，否则很容易被同网段的人直接连上来。model.endpoint指向本地模型服务，我这边用的是Ollama的默认地址，你可以换成你自己的模型服务。

3.4 启动、验证与自启动设置

配置写完之后，启动非常简单：

openclaw start

看到类似“Server running on http://0.0.0.0:8080”的日志，就说明服务已经起来了。然后你在浏览器里访问http://127.0.0.1:8080，能看到一个基础的Web界面。

这还不够，我们应该验证一下服务是否真的在正常工作。最简单的办法是调用一下健康检查接口：

curl http://127.0.0.1:8080/health

返回一个JSON，里面包含status: ok之类的字段，就说明核心流程没问题。

如果你想让它长期在后台跑，而不是挂在当前终端会话上，可以用systemd来托管。在WSL2里新建一个服务文件：

sudo nano /etc/systemd/system/openclaw.service

内容如下：

[Unit] Description=OpenClaw Service After=network.target [Service] ExecStart=/usr/local/bin/openclaw start Restart=always User=你的用户名 Environment=NODE_ENV=production [Install] WantedBy=multi-user.target

然后启动并设置开机自启：

sudo systemctl enable openclaw sudo systemctl start openclaw systemctl status openclaw

到这里，你的OpenClaw已经能作为一个常驻服务稳定运行了。

4. 内网使用配置全流程

4.1 局域网访问的基本条件

OpenClaw装好、本地能访问之后，接下来就是让局域网里的其他设备也能访问。这个环节我一开始以为很简单，实际排查时才发现要满足几个条件才能完全跑通。

第一，服务器的监听地址不能是127.0.0.1，必须是0.0.0.0，否则Linux内核根本不会把外部发来的连接交给这个服务。第二，服务器的防火墙要放行对应端口。第三，局域网内的其他设备需要知道你这台机器的IP地址。

把服务监听地址改成0.0.0.0之后，先不要急着去别的设备上试，先在服务器本机验证一下：

curl http://127.0.0.1:8080/health curl http://<你的局域网IP>:8080/health

第一条确认服务本身正常，第二条确认服务确实从局域网网卡接收请求。查看局域网IP可以用：

ip addr show | grep inet

或者Windows下用：

ipconfig

记下那个172.x.x.x或者192.168.x.x之类的地址，后面所有设备访问时都要用这个IP。

4.2 防火墙与端口放行

这一步是最常被忽略的。很多人在服务器本机curl都通，但手机连同一个WiFi就是打不开，十有八九都是防火墙挡掉了。

Ubuntu下用的是ufw，操作如下：

sudo ufw allow 8080/tcp sudo ufw enable sudo ufw status

Windows系统如果没走WSL，直接在“高级安全Windows Defender防火墙”里新建一条入站规则，放行TCP 8080端口就行。如果你用的是WSL2，而且访问流量是从局域网进来再转发到WSL子系统的，还需要额外检查一下端口转发规则。

一个比较隐蔽的坑是，Windows的端口代理规则在重启后可能失效。你可以在PowerShell里手动设置：

netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=127.0.0.1

如果设置之后仍然访问不了，可以用netsh interface portproxy show all来查看当前的转发规则列表。

4.3 同一局域网内多设备访问

条件都满足之后，手机、平板或者另一台电脑就可以通过浏览器访问了。地址格式就是：

http://<服务器局域网IP>:8080

比如你的服务器IP是192.168.1.100，那访问地址就是http://192.168.1.100:8080。这个时候，配置里的auth.token就起作用了，客户端连接时如果请求头里没有正确的凭证，OpenClaw会直接拒绝请求。这一点在开放局域网访问后是必须的，千万别因为嫌麻烦而不配。

如果单位或家里的路由器开启了AP隔离，那么即使在同一WiFi下，设备之间也是互相隔离的，这时你需要登录路由器后台，关闭AP隔离选项，或者改成访问访客网络的模式。

4.4 内网专属：完全不依赖外网的部署路径

有些朋友部署OpenClaw是想要一个彻底离线的本地AI助手，不希望任何请求跑到外网去。这里有一个很重要的认知：OpenClaw本身只是一个服务框架，实际对话能力取决于你给它配置的模型源。

如果你想做到纯内网运行，最重要的是把模型源也本地化。常见做法是用本地模型服务，比如在服务器上装好Ollama之后，拉一个量化版模型：

ollama pull qwen2.5:3b ollama serve

然后把OpenClaw的model.endpoint指向本地的Ollama地址，同时把网络相关的外部调用禁用。这样整个链路就完全在内网里完成，不需要访问任何外部资源，断网也能正常使用。

这里我插一句，部署之前一定要明确自己的使用场景。如果只是自己电脑上玩玩，那访问地址、凭证可以随意一些；但如果是给部门或家庭内多个人一起用，那凭证、端口、运行用户这些都要规规矩矩地处理好。联网模式下更要谨慎，不要随便暴露端口。

5. 常见问题与排查技巧实录

5.1 WSL2状态异常与修复

装好WSL之后，最常见的一个报错是在PowerShell里运行wsl --status时提示“请启用虚拟机平台”或者“WSL 2需要更新其内核组件”。

这个问题的根源通常是电脑的虚拟化功能没有完全打开，或者内核组件太旧。解决办法是先检查BIOS里的虚拟化有没有开启，然后在确保虚拟化开启的情况下重新安装或更新WSL内核。有时候问题出在WSL版本太老，可以用以下命令更新到最新版：

wsl --update

如果WSL已经可用，但状态显示“默认版本: 1”，可以手动转换：

wsl --set-version Ubuntu 2

这里有一个容易误操作的点：直接将发行版从v1转v2时，如果磁盘空间不够，会提示转换失败。转换前检查一下C盘空间是有必要的，否则执行到一半卡住，反而可能把系统搞出其他问题。

5.2 “openclaw无法安全验证”与Windows SmartScreen

有段时间我在Windows侧直接双击某个安装脚本时，系统会弹出一个“无法安全验证”的提示，很多朋友看到这个弹窗就不知道怎么办了。这其实是Windows的SmartScreen在拦截未签名的第三方脚本或程序。

处理方式有两个方向。一是用WSL命令行运行，绕过Windows侧的可执行程序检查；二是如果你确实需要直接在Windows里运行，并且该脚本来源可信，可以右键脚本文件、选择“属性”、然后勾选“解除锁定”，确认后再运行。这里提醒一下：只有你自己确认来源安全的脚本才可以这么操作，不要对来路不明的文件强行解除锁定。

我个人的建议是尽量在WSL环境里跑OpenClaw相关的东西，Windows侧的提示几乎可以完全避开，而且整个部署流程也更贴近官方文档描述的环境。

5.3 端口被占用或者启动失败

OpenClaw启动时提示端口被占用，多半是因为之前有一个没有正常退出的进程还占着端口。排查：

sudo lsof -i :8080

找到对应的进程号，然后确认没有其他重要业务占用这个端口之后，再决定是否结束该进程：

kill <进程号>

另外，有时候启动一直卡在某个环节，不要急着反复重启。先看日志：

openclaw logs

日志里通常会写明是连接模型服务超时、还是某个配置文件里的字段有问题。磨刀不误砍柴工，养成看日志的习惯能省去大量盲目尝试的时间。

5.4 模型服务连不上的排查思路

如果你配置了本地模型服务，但OpenClaw启动后对话时提示连接失败，我一般会按下面的顺序排查：

• 模型服务的健康接口通不通：如果是Ollama，就curl http://127.0.0.1:11434看返回
• OpenClaw配置里的model.endpoint有没有写错地址或端口
• 模型服务有没有真的把模型加载到内存，有时候只是服务起来了，但某个模型没有下载完整
• 如果模型服务经过代理或防火墙，检查是否被拦截

这里有一个常见的坑：当你把OpenClaw的监听地址改成0.0.0.0之后，整个服务实际上是以局域网监听方式运行的，但模型调用仍然走的是本地回环地址。只要本地回环没被防火墙拦截，就没什么问题。如果哪个环节把本地回环也拦了，那就很麻烦，所以防火墙规则一定要精确。

5.5 速查表：安装部署常见问题一览

为了方便你快速定位问题，我把部署过程中比较典型的状况整理成了一个表：

6. 一点个人经验总结

这套部署流程我前前后后在三四台不同机器上跑过，有WSL2的Windows笔记本，有纯Ubuntu的旧台式机，还有跑过虚拟机的测试环境。老实说，第一次装的时候我也踩了不少坑，从环境变量没配对到防火墙忘了放行端口，折腾了一整个下午才看到那个熟悉的启动日志。

现在回过头来看，最值得记住的经验只有一个：安装之前花十分钟把环境理清楚，比安装时东拼西凑找教程高效得多。先把WSL2状态确认了，把Node、Git、Python版本核对一遍，再动手装OpenClaw，整个过程会顺畅非常多。如果过程中遇到报错，也别慌，按日志一层一层查下去，绝大多数问题在日志里都有明确提示。

另外，如果你打算把OpenClaw真正用于日常办公协作，建议在第一次启动之前就把配置文件里的auth.token改掉，并且把allowScriptExecution保持为false，等确认了脚本来源之后再按需打开。这不算什么高深的技巧，但确实是避免后续麻烦最有效的一道防线。

最后再说一句，如果你正好有一台不常用的旧电脑，把它清出来装一个OpenClaw当作家庭或小团队的离线助手，其实挺有意思的。部署一遍之后，你会对AI服务的运行链路、模型接入方式有很直观的理解，这些经验对以后折腾其他开源项目也非常有用。