最近我把 OpenClaw 部署到了 Windows 11 办公机的 WSL2 里,整个过程折腾了差不多一个周末。OpenClaw 是当前挺火的一个开源智能体运行框架,能在本地跑一个会对话、能调工具、能接第三方平台的 AI Agent。它本身是典型的 Linux 生态产物,依赖 bash 脚本、Docker 中间件、Linux 文件锁机制,原生 Windows 根本不好好干活,所以我一开始就没打算绕开子系统这条路。
这篇文章就是把我从零到一跑通 WSL2 + OpenClaw 的完整过程记录下来,包括 Windows 侧该做什么准备、WSL2 怎么配才顺手、OpenClaw 依赖装哪些、本体怎么启动、怎么接 Teams 和 Obsidian,还有我踩过的十几个坑。最适合的人群是:想在自己 Windows 电脑上把 OpenClaw 跑起来做 Agent 开发、本地自动化,或者单纯想折腾一个本地助手的同学。我尽量把每个操作背后的为什么也讲清楚,而不是只丢给你一串命令。
1. 部署前先想清楚:为什么 Windows 上用 OpenClaw 绕不开 WSL2
1.1 OpenClaw 实际依赖什么样的运行环境
很多人第一步就跑偏,是因为没搞清楚 OpenClaw 到底跑在什么环境里。简单说,OpenClaw 不是一个单文件程序,它是一整套 Agent 运行时:需要常驻进程管理会话、需要 bash 执行本地操作、需要 Redis 做缓存和状态存储、可能还需要 Elasticsearch 做语义检索,模型推理还要走 GPU 或远程 API。这一整套东西从设计之初就是为 Linux 写的。
举几个我实际遇到的细节:OpenClaw 的会话文件用的是 JSONL 格式,读写时要靠 flock 做文件锁,Windows 原生文件系统对 flock 的支持非常别扭;它的启动脚本是 bash 写的,路径全是/home/user/...这种 Unix 风格;它内部调用的很多 CLI 工具(比如 jq、curl、docker)在 Windows 原生环境里要么没有要么是残废版本。你就算用 Git Bash 或者 MSYS 硬跑,也会在权限、路径、信号处理这些地方不断踩雷。
所以结论很直接:在 Windows 上要稳定跑 OpenClaw,必须有一个完整的 Linux 运行环境,而 WSL2 就是目前最平滑的方案。
1.2 原生、Docker Desktop、WSL2 三种路线的取舍
我见过有人问“直接用 Docker Desktop 装 OpenClaw 不就行了”?这个说法对了一半。Docker Desktop 在 Windows 上走的是 WSL2 后端,你装好 Docker Desktop 的时候,其实已经隐式依赖了 WSL2。所以它不是和 WSL2 二选一的关系,而是 WSL2 之上的一个附加层。我把三条路线对比了一下,方便你自己判断。
| 路线 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|
| Windows 原生跑 | 无额外虚拟化开销 | 脚本兼容性差、文件锁和路径全是问题 | 基本不可行,不推荐 |
| Docker Desktop 容器化 | 环境隔离干净、可复现性好 | 多一层抽象,移植 WSL2 内 GPU 和端口转发多一道手续 | 团队标准化交付、想快速起依赖中间件 |
| WSL2 裸装 | 贴近生产 Linux、IO 快、可直接用 systemd 托管服务 | 需要自己维护 Ubuntu 环境 | 个人开发、本地长期跑 Agent,我最推荐 |
我最后选的是 WSL2 裸装,再在 WSL2 内部单独装 Docker 跑 Redis 这些中间件。这样 OpenClaw 本体直接以 Linux 进程方式运行,调试、看日志、接管服务都要方便很多,遇到的问题也更接近生产环境。
2. Windows 侧准备:先把 WSL2 扶上正轨
2.1 检查系统版本并开启 WSL2 的两种方式
动手之前先确认系统版本。Windows 10 2004 及以上、Windows 11 全系基本都支持 WSL2,我的办公机是 Windows 11 24H2 环境,用起来没有任何问题。如果你的机器比较老,先把系统更新做了,不然很多步骤会卡在奇怪的报错上。
开启 WSL2 有两种方式,我推荐直接命令行搞定。用管理员身份打开 PowerShell 或者 Windows Terminal,然后跑:
wsl --install这条命令会自动开启“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个 Windows 功能,装好默认的 WSL 内核,顺带把发行版也装了。跑完大概率需要重启,重启后接着看 2.2 节就行。
如果你的机器因为各种原因走不了这条捷径,那就手动打开:按Win + R输入optionalfeatures,在弹出的窗口里勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”,点确定后重启,再装内核更新包。注意 BIOS 里必须开启虚拟化,不然装了也会启动失败。可以在任务管理器“性能”标签页里看“虚拟化”是否已启用。
2.2 安装并切换到 Ubuntu 22.04
wsl --install默认装的可能是 Ubuntu 最新版,但我在生产环境里长期用的还是 Ubuntu 22.04 LTS,稳,资料也多。如果你没装或者想单独装 22.04,可以指定发行版:
wsl --install -d Ubuntu-22.04装好以后第一次启动 Ubuntu,会让你设置 Linux 用户名和密码,这个密码和 Windows 登录密码没关系,是独立的,记住就行,后面 sudo 要用。装完检查一下当前发行版的状态:
wsl -l -v正常输出会看到 Ubuntu-22.04 的VERSION列是2。如果你是老机器从 WSL1 升上来的,或者输出显示1,那就手动转换:
wsl --set-version Ubuntu-22.04 2 wsl --set-default-version 2转换可能需要几分钟,中途别关窗口,过程中最好先wsl --shutdown把发行版关掉,避免文件占用导致转换失败。这里有个很容易踩的坑:如果你以前装的是 WSL1 的发行版,里面已经有一堆项目文件,转 WSL2 时文件系统格式转换耗时会特别长,耐心等,不要手动强制中断。
2.3 让 WSL2 好用的三个配置
装好只是开始,不经过配置的 WSL2 默认只分配机器一半内存,磁盘文件还放在 C 盘,跑 OpenClaw 这种常驻服务会很难受。我每次都直接做三件事。
第一件事,在 Windows 侧配置.wslconfig文件。路径是C:\Users\你的用户名\.wslconfig,不存在就新建。文件内容可以这样写:
[wsl2] memory=8GB processors=4 swap=4GB localhostForwarding=true配置完在 PowerShell 里执行wsl --shutdown,然后再进 WSL2 才会生效。memory和processors别乱拉满,要给 Windows 本体留余量,因为 WSL2 跑在轻量虚拟机里,内存是动态分配的,但上限你得控制住。如果你的机器只有 16G 内存,建议memory=6GB就够 OpenClaw 加 Redis 跑了。
第二件事,启用 systemd。默认 WSL2 是不跑 systemd 的,OpenClaw 如果要做成开机自启服务,或者你想用systemctl管理 Docker,没有 systemd 会很蛋疼。在 Ubuntu 里执行:
sudo tee /etc/wsl.conf <<EOF [boot] systemd=true EOF然后回到 PowerShell 执行wsl --shutdown,重新进入后运行systemctl is-system-running,能返回running就说明生效了。这一步不做,后面 Docker 安装就得手动启动服务,重启进 WSL 后所有容器全部失效,烦到怀疑人生。
第三件事,换 apt 镜像源。Ubuntu 默认的 apt 源在本地网络环境下经常不稳定,你安装 git、docker、jdk 这类基础包时会明显感觉速度不行。在 Ubuntu 22.04 中把/etc/apt/sources.list或/etc/apt/sources.list.d/ubuntu.sources里的默认源地址替换成你本地访问顺畅的镜像站即可,阿里云、清华源都行。替换完执行:
sudo apt update我建议把它和sudo apt upgrade一起跑一遍,确保系统内核和基础库都是新的。这一步能避掉不少奇怪的兼容性报错,尤其是后面要装 CUDA 的时候,老内核和新驱动容易打架。
3. OpenClaw 的底座依赖安装
3.1 为什么用 Docker 跑中间件,以及 Docker 和 WSL2 的关系
OpenClaw 本体不是一个孤立进程,它运行时要访问 Redis,做知识库索引的话还要 Elasticsearch。这些中间件在你本地以什么形式存在直接影响稳定性。我的做法是:在 WSL2 内部装 Docker,用容器跑 Redis 和可选的 ES,OpenClaw 本体直接跑在 Ubuntu 环境里。
先回答很多人常问的“装 Docker 之前要装 WSL2 吗”。如果你用的是 Docker Desktop,答案是要,而且不是建议,是必须。Docker Desktop 从 2.0 开始就把后端构建在 WSL2 之上,它需要 WSL2 提供 Linux 内核才能运行 Linux 容器。你如果不先把 WSL2 装好,Docker Desktop 会提示你启用相关功能。如果你想轻量一点,直接在 WSL2 里装 Docker Engine 也行,我实际更推荐这种方式,省掉 Docker Desktop 那层资源消耗,而且和 Linux 服务器上操作完全一致。
3.2 在 WSL2 里安装 Docker 并验证
在 WSL2 的 Ubuntu 里,我最推荐用官方脚本装 Docker Engine:
curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh先下载再执行,不要直接curl | sh一把梭,养成看脚本内容的习惯。装完后因为启用了 systemd,可以直接:
sudo systemctl enable --now docker docker version输出能看到 client 和 server 版本就说明 Docker 跑起来了。然后拉一个 Redis 容器当测试,顺便给 OpenClaw 备好缓存中间件:
sudo docker run -d --name openclaw-redis -p 6379:6379 redis:7-alpine用sudo docker ps查看容器状态,看到 STATUS 是 Up 就正常了。这里有个细节:端口6379映射出来是为了方便 OpenClaw 通过 localhost 访问,如果你后续要接 Windows 侧的工具,WSL2 的localhostForwarding=true会自动把 localhost 流量转发到 Windows,两边都能用127.0.0.1:6379访问。
如果你的 WSL2 内存紧张,Elasticsearch 可以先不装。ES 是个内存大户,至少 2G 起步,跑起来以后你的 OpenClaw 会被它拖得很卡。我建议先用最小依赖跑通 OpenClaw,需要语义检索的时候再单独把 ES 容器拉起来,这样排查问题也更容易定位。
3.3 需要 GPU 的场合:NVIDIA 驱动与 WSL2
很多 Agent 场景要本地跑模型,OpenClaw 如果接了本地推理引擎就绕不开 GPU。这里回答一个高频问题:WSL2 里英伟达驱动生效吗?答案是生效,但前提是 Windows 侧先装好支持 WSL 的 NVIDIA 驱动。
WSL2 的 GPU 加速机制比较特别:你不需要在 WSL2 里单独安装显卡驱动,Windows 侧装好驱动后,WSL2 里是直接复用那套驱动的。测试方式很简单:
nvidia-smi如果能看到和 Windows 侧一致的显卡信息和驱动版本,说明一切正常。我看到很多人卡在“WSL2 里 nvidia-smi 报错找不到设备”,九成原因是 Windows 侧驱动太老或者装的是只有 CUDA 没有完整驱动的包。去 NVIDIA 官网下载最新的 Game Ready 或者 Studio 驱动装一遍就行。
如果你确定要在 WSL2 里跑 CUDA 计算,还需要在 Ubuntu 里单独装 CUDA Toolkit:
sudo apt install -y nvidia-cuda-toolkit注意这个包版本可能比 NVIDIA 官方新版旧一些,但对 OpenClaw 这种调用推理引擎的场景够用。真要做训练或跑最新框架,建议按 NVIDIA 官方文档走 runfile 方式安装,别用 apt 偷懒。
3.4 其他依赖:Git、JDK 17、常用工具链
OpenClaw 部署时需要从代码仓库拉取源码,工具链里 git、curl、wget、build-essential 是必须的。JDK 17 也是很多自动化扩展的硬依赖,比如将来要跑 Java 系的 MCP Server 插件,没有 JDK 会直接启动失败。一次性装齐:
sudo apt install -y git curl wget build-essential python3 python3-pip openjdk-17-jdk装完验证一下:
git --version java -version python3 --version我在这里吃过一个亏:一开始为了省时间只装了 git 和 python3,结果 OpenClaw 的 install.sh 跑到中间报缺 build-essential,又得中断装依赖,再重新跑脚本。虽然脚本可以恢复进度,但这类中断很容易留下半配置状态。建议先把上面这一行装完再往下走,省得来回折腾。
4. OpenClaw 本体安装与初始化
4.1 获取源码与本地一键部署脚本
环境就绪后,开始拉 OpenClaw。进入你准备放项目的目录,比如~/apps:
mkdir -p ~/apps cd ~/apps git clone https://github.com/openclaw/openclaw.git cd openclaw先别急着运行任何脚本,先把仓库目录结构看一眼:
ls -la正常情况下你会看到若干配置文件模板、README、以及一个或多个install*.sh或setup.sh部署脚本。OpenClaw 社区版本提供一键部署能力,网上传的“本地一键部署”指的就是这里的脚本。执行前建议先读脚本内容:
head -80 install.sh确认脚本做的事情在你接受范围内,然后运行:
bash install.sh安装脚本会自动安装 Python/Node 依赖、初始化配置目录、创建默认智能体配置。整个过程依赖网络,偶尔会因为网络状况卡住,我的建议是:多试几次,断在哪个阶段就查看哪个阶段的输出信息,不要反复重跑整个脚本。
如果网络实在不稳,可以先用浏览器手动下载仓库 zip 包拷进 WSL2,再解压运行。路径放在/mnt/c/Users/你的用户名/Downloads下就行,通过/mnt/c/...访问 Windows 文件,这是 WSL2 的标准姿势。
4.2 配置环境变量与模型接入
OpenClaw 启动前需要告诉它用哪个模型服务商、API Key 是什么、默认端口是多少。安装完后在配置目录(通常是~/.openclaw/或项目目录)下会生成.env.example模板。我的习惯是先复制一份再编辑:
cp .env.example .env vi .env核心配置大概长这样:
OPENCLAW_DEFAULT_AGENT=demo OPENCLAW_PORT=8080 OPENCLAW_MODEL_PROVIDER=anthropic OPENCLAW_MODEL=claude-sonnet-4-5 OPENCLAW_MODEL_API_KEY=你的模型服务Key OPENCLAW_SESSION_DIR=~/.openclaw/sessions不同版本字段名可能略有差异,以仓库内.env.example原始注释为准。这里最重要的一个教训是:API Key 必须妥善保存,.env文件本身不要提交到 git,也不要随便发给别人。我习惯把OPENCLAW_SESSION_DIR单独指出来,方便备份和清理,后面排查文件锁问题也靠这个路径。
如果你的模型服务商不是 Anthropic,而是 OpenAI 兼容接口、本地 Ollama 或者其他国内服务商,把OPENCLAW_MODEL_PROVIDER和OPENCLAW_MODEL改成对应值即可。OpenClaw 的模型层是抽象过的,切换成本不高。
4.3 首次启动服务并验证运行状态
配置完成后启动服务。不同版本的子命令不一样,最常见的是这样:
./openclaw start如果你更习惯前台运行,方便看实时日志,可以:
./openclaw serve --port 8080看到类似Server started at 0.0.0.0:8080的字样,说明服务起来了。这时候开另一个终端,验证一下健康检查接口:
curl http://localhost:8080/health能返回正常的 JSON 状态就说明 OpenClaw 本体没问题。接下来创建一个最小的测试会话,看看 Agent 能不能完整回复:
./openclaw chat --message "你好,简单介绍一下你自己"第一次对话模型服务商的网络请求会比较慢,多等几秒。如果报错,先看日志:
tail -n 100 ~/.openclaw/logs/openclaw.log我个人强烈建议从这一版最小可用配置开始跑,不要一上来就接 Teams、Obsidian、一堆 MCP 工具。先把“核心对话链路”走通,再一层层往上加,出问题时才能快速界定是框架问题、模型问题还是扩展问题。
5. 把 OpenClaw 接到 Teams 和 Obsidian
5.1 接入 Microsoft Teams:从注册到配置
OpenClaw 的一个卖点是可以作为一个智能体直接出现在 Microsoft Teams 里,群里 @ 它就能交互。接入的完整链路是这样的:Teams 后台把消息转发给 OpenClaw,OpenClaw 处理后调用 Teams API 回消息。
实际操作分三步。第一步,在 Azure 门户里创建一个 Bot 资源,选“Azure Bot”就好。创建完成后记下 Microsoft App ID,再生成一个 Client secret(也叫客户端密码)。这个 App ID 和 Secret 就是 Teams 验证 OpenClaw 身份的凭证。第二步,在 Azure Bot 的“Channels”页面里把 Teams 通道启用。第三步,在 OpenClaw 的.env中加:
OPENCLAW_TEAMS_ENABLED=true OPENCLAW_TEAMS_APP_ID=你的AppId OPENCLAW_TEAMS_APP_SECRET=你的ClientSecret OPENCLAW_TEAMS_WEBHOOK_PUBLIC_URL=OpenClaw可被Teams访问的回调地址最关键的是OPENCLAW_TEAMS_WEBHOOK_PUBLIC_URL,Teams 后台需要能回调到你 OpenClaw 进程。在本地开发环境,你可以先用内网穿透把 8080 端口暴露到一个公网地址,填到这里;如果在云服务器上部署,直接填服务器的公网 IP 加端口就行。我第一次配置时在这里卡了很久,一直报401,后来发现是 Teams 后台回调地址的路径没写对,必须以 Teams 要求的 webhook 路径结尾,具体路径以 OpenClaw 文档为准。
接入完成后,在 Teams 里搜索你 Bot 的名称,开启一对一聊天,或者把它拉进某个频道,@ 它说话就能触发 Agent 回复了。这个方法很适合团队里做 AIGC 助手,相当于把一个开源 Agent 包装成企业微信机器人或是 Teams Bot,数据可控。
5.2 接 Obsidian:让 Agent 读你的笔记
Obsidian 是很多人的第二大脑,OpenClaw 接上 Obsidian 之后,可以直接让它检索你笔记里的内容,或者把对话记录自动归档到指定 Vault。这个功能的原理是调用 Obsidian 本地的 REST API。
先在 Obsidian 里安装“Local REST API”社区插件,启用后在插件设置里开启 API,设置一个自定义 API Key,默认端口通常是27123。然后在 OpenClaw 的.env里加:
OPENCLAW_OBSIDIAN_ENABLED=true OPENCLAW_OBSIDIAN_ENDPOINT=http://127.0.0.1:27123 OPENCLAW_OBSIDIAN_API_KEY=你的ObsidianKey OPENCLAW_OBSIDIAN_VAULT=/mnt/c/Users/你的用户名/Documents/MyVault这里请注意路径格式:Obsidian 跑在 Windows 原生环境里,Vault 的物理路径在 Windows 上;而 OpenClaw 跑在 WSL2 里,访问 Windows 盘符要用/mnt/c/...这种映射路径,千万不要写成C:\Users\...,这是新手最容易出错的点。
验证配置是否生效,可以先在 WSL2 里用 curl 直接请求 Obsidian API:
curl -X POST http://127.0.0.1:27123/search \ -H "Authorization: Bearer 你的ObsidianKey" \ -H "Content-Type: application/json" \ -d '{"query":"OpenClaw部署"}'能返回笔记片段,说明 OpenClaw 到 Obsidian 的链路是通的。日常使用时,我习惯让 OpenClaw 在每次对话结束后把生成的内容整理成 Markdown 笔记写入 Vault,相当于给 Agent 加了一层长期记忆。比让它裸奔着只靠上下文窗口靠谱多了。
5.3 第三方扩展的通用套路
Teams 和 Obsidian 只是 OpenClaw 众多适配器中的两个,理解了它们,其他扩展基本都是一个套路:在对应平台注册一个入口(Bot/插件/API),拿到凭证,然后在 OpenClaw 的.env里把对应开关打开,填好回调地址和凭证,重启服务。
有人问过我“OpenClaw 和 WorkBuddy 这类现成助手选哪个”。我的看法是:如果你要的是可定制、数据完全在自己的环境里流转,OpenClaw 这种开源框架明显更有优势;如果只是想要开箱即用、不想碰配置文件,商业产品确实省心。没有标准答案,看你控制欲有多强。就我而言,从 WSL2 开始一步步搭起来,本身就是把整个链路摸透的过程,后面再做自动化扩张会非常顺手。
6. 高频报错排查实录:这些坑我踩了不止一遍
6.1 agent failed before reply: session file locked,怎么解
这个错误是部署 OpenClaw 的人群里最经典的报错,完整提示一般是:
agent failed before reply: session file locked (timeout 60000ms)第一次见到时我以为是 Agent 逻辑崩了,查了半天代码,后来才明白是会话文件锁超时。OpenClaw 为每个会话维护一个 JSONL 文件,并在写入前利用文件锁机制保证同一会话不被并发写坏。锁等待默认超时是 60000ms,也就是 60 秒。如果某个会话文件一直被锁着不释放,60 秒后就会抛出这个错误,然后整个对话请求被判失败。
常见触发原因有三个:一是上次 OpenClaw 进程还在后台跑,你又启动了新实例,两个进程抢同一个会话;二是进程被强杀,锁文件残留在磁盘;三是同一台机器上居然开了两个 OpenClaw 服务,同时用了同一个配置目录。
排查命令顺手分享:
ps aux | grep -i openclaw如果发现确实有残留进程,直接清理:
kill -9 进程PID然后找到并删除锁文件。锁文件一般在OPENCLAW_SESSION_DIR指向的目录里,后缀是.lock:
find ~/.openclaw -name "*.lock" -type f find ~/.openclaw -name "*.lock" -delete删完再启动一次,基本就好了。如果你不想让这个问题再犯,两个建议:一是用 systemd 托管 OpenClaw 服务,确保只有一个受控实例;二是在启动脚本里加flock -n /tmp/openclaw.lock,保证同机器同时只能起一个主进程。操作虽然简单,但能省去后续无数个 60 秒的等待。
6.2 端口被占用,Windows 上怎么关掉对应进程
OpenClaw 默认 8080 端口,但 WSL2 和 Windows 共享 localhost 转发,所以这个端口可能被两边任意一端的进程占用。报错表现是启动时提示address already in use。
在 Windows 侧排查,用 PowerShell:
netstat -ano | findstr :8080输出的最后一列就是占用端口的进程 PID,继续查是谁:
tasklist /FI "PID eq 对应PID"确认是你的旧进程或者其他无关程序,就杀掉:
taskkill /PID 对应PID /F在 WSL2 内部排查,则用:
ss -ltnp | grep 8080查到 PID 后用kill -9处理。如果两边都查了还是冲突,还有一种情况是 WSL2 内核里的端口转发和 Windows 本身的服务占用了同一端口。最快的办法是把 OpenClaw 换一个冷门端口,比如 18080,在.env里修改OPENCLAW_PORT,重启服务即可,省得跟系统服务抢端口。
6.3 Windows 侧脚本闪退、路径不对的问题
后台经常看到有人问“Windows 脚本命令闪退怎么办”,这类问题和 WSL2 部署 OpenClaw 高度相关。最典型的场景是你在 Windows 资源管理器里直接双击install.sh,弹一个窗口闪一下就消失了。这不叫错误,这是正常的——.sh文件是给 bash 解释用的,Windows 资源管理器默认没法正确处理它,于是跑完(或者根本没跑)就关了,你什么都看不到。
正确姿势是:在 Windows Terminal 里新建一个 Ubuntu 标签页,进入 WSL2,然后在里面用 bash 显式执行脚本:
bash install.sh还有一个更隐蔽的坑:在 PowerShell 里执行bash -c "cd /home/user/openclaw && ./openclaw start",如果你把路径写成了 Windows 风格,比如cd C:\Users\...,bash 根本认不出来,会直接报错。在 WSL2 里访问 Windows 文件一律用/mnt/c/Users/...,访问 Linux 文件用/home/...,这个路径心智模型要转变过来。
我把 Windows Terminal 的默认配置文件改成了 Ubuntu,新建标签页直接进 WSL2,相关操作全程都在 Linux 环境里完成,Windows 侧脚本闪退这类问题就从根上消失了。
6.4 其他高频疑问快解
整理几个我在部署期间被问得最多的问题,直接给结论。
| 问题 | 结论 |
|---|---|
| Docker 安装前要装 WSL2 吗 | 要,Docker Desktop 依赖 WSL2 后端才能运行 Linux 容器 |
| Redis 用 Windows 版还是 WSL2 里跑 | 用 WSL2 内 Docker 跑 Linux 版 Redis,Windows 没有官方版本,兼容性差 |
| WSL2 里英伟达驱动生效吗 | 生效,Windows 侧装好驱动,WSL2 里nvidia-smi直接可用 |
| Ubuntu 需要有图形界面吗 | WSLg 默认支持 GUI 应用,但 OpenClaw 是 CLI 为主,基本用不到 |
| 需要装 Elasticsearch 吗 | 不是必须,做语义检索/知识库索引才需要,内存不足可以先不装 |
| 本地跑不动怎么办 | 可以把这套环境原样迁到云服务器,比如阿里云免费试用额度里的 Ubuntu 22.04 实例 |
6.5 常见问题速查表
最后放一张速查表,遇到问题直接对着找。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
agent failed before reply: session file locked | 多个 OpenClaw 实例抢占会话锁、残留锁文件 | 清理残留进程,删除~/.openclaw下.lock文件 |
| 启动提示端口被占用 | Windows 或 WSL2 任一端进程占用端口 | netstat -ano/ss -ltnp查 PID 并结束进程,或换端口 |
curl localhost:8080不通 | 服务没起来、端口配置错 | 查看日志、确认.env配置 |
nvidia-smi没输出 | Windows 驱动太老或未装支持 WSL 的驱动 | 装最新 NVIDIA 驱动后重启 WSL |
双击.sh闪退 | 资源管理器不能直接执行 shell 脚本 | 在 WSL2 里用bash 脚本名执行 |
| Teams 回调报 401 | App ID/Secret 或回调地址配置错 | 核对 Azure Bot 凭证,确认公网回调地址路径正确 |
| Obsidian 无法连接 | Vault 路径写成了 Windows 盘符 | 改成/mnt/c/...映射路径,确认插件 API 已开启 |
写在最后的实际体验
把 Windows、WSL2、OpenClaw 这三层串起来以后,最大的体会是:问题往往不出在 OpenClaw 本身,而出在“你以为自己在 Windows 底下运行,实际代码跑在 Linux 虚拟机里”这个观念没换过来。文件路径、端口转发、进程管理、文件锁、驱动器映射,这些环节每错一步都有可能让你怀疑人生。我在部署过程中最大的转折点,就是确立了“用 systemd 托管服务”、“所有临时文件放 WSL2 内部”、“只在 Windows 侧处理界面和浏览器”这三个边界原则,后续再也没出过玄学问题。
最后分享一个小技巧:把 OpenClaw 的启动做成 Windows Terminal 的 profile,开个新标签页就能进到项目目录并自动启动服务。Windows Terminal 的 settings.json 里新增一个 profile,命令行指向wsl.exe -d Ubuntu-22.04 --cd ~/apps/openclaw,配合"startingDirectory": "//wsl$/Ubuntu-22.04/home/你的用户名/apps/openclaw",基本就能一键进入工作环境。作为长期用 Windows 做 Agent 开发的人,这套组合是我现在最满意的本地运行方案,希望你也能一次跑通。