最近折腾了一个叫 openclaw 的个人 AI 助理框架，连着搞了几天，从 Windows 到 WSL2，再搬到 Linux 和云服务器，中间踩了不少坑。这个项目把本地大模型、笔记库和自动化任务串在一起，有点像我一直在找的那种"本地优先的智能副驾"。如果你也想在 Windows 或 Ubuntu 上把 openclaw 跑起来，或者想让它接上 qwen2.5-3b 和 Obsidian，这篇文章应该能帮你少走弯路。我会把从零开始的整个初次使用过程、关键配置逻辑和排查方法都写出来，适合刚接触这个项目的同学参考。

1. 一句话说清 openclaw 是什么，以及我为什么上手它

1.1 从"本地 AI 助手"角度看 openclaw 的定位

openclaw 不是那种开个网页就能聊天的 AI，它更像一个跑在自己机器上的 AI Agent 框架，负责把你的模型能力、知识库、日常任务工作流串起来。你可以理解为：别人用 ChatGPT 是进了一家"云上餐厅"，openclaw 是让你在自己家的厨房里开火。食材（数据）、刀具（工具链）、火候（模型）都在本地，想怎么搭配自己说了算。

我选择它的第一个原因是数据自主性。知识库里的笔记、文档、对话记录都是私有内容，直接丢给在线 API 总觉得不踏实。而 openclaw 这种本地优先的设计，可以把全文检索、上下文注入和 Agent 调度全部放在本机完成，模型用 qwen2.5-3b 这种开源小模型也行，用云端 API 也行。第二个原因是它把几个原本割裂的系统拉通了——聊天界面、笔记库、任务脚本、甚至 Windows 上的应用程序操作，都能通过统一接口调度。初次上手时你可能觉得它只是个聊天机器人，实际用进去会发现，它更像一个"以自然语言为入口的个人工作站"。

1.2 哪些场景值得用它：我的试用前评估

我上手前的判断很简单：如果你每天有大量碎片信息要整理、经常在笔记和任务之间来回跳转、或者想尝试让 AI 帮你执行重复性操作，openclaw 就值得试试。它尤其适合程序员、知识管理重度用户和喜欢折腾自托管服务的人。程序员可以在里面写脚本工具，知识工作者可以把 Obsidian 变成问答库，爱折腾的人则能把它部署到云服务器上做个 24 小时在线的个人助理。

另外我看到社区里有人问"WorkBuddy 这类产品是不是也参考了 openclaw 才搞出来的，时间对得上吗"。我没有内部消息，不好下结论，但只要把这类产品的架构拆开看，就能发现大家都走在相近的路上：模型接入层、知识库索引层、Agent 调度层，再加一个对外接口。openclaw 在这套思路上做得比较早，所以后来很多同类项目参考它的设计也不奇怪。这也是我选择它作为入门研究对象的原因——先把一个生态比较完整的框架吃透，后面再看其他方案就轻松多了。

2. 初次部署：先在 Windows + WSL2 上把环境跑起来

2.1 WSL2 环境检查与修复（wsl --status 的正确用法）

在 Windows 上部署 openclaw，官方推荐路径是先通过 WSL2 跑一个 Linux 环境，而不是直接在原生 Windows 上跑。最开始我没太在意，直接拉代码、装依赖，结果 PowerShell 里冒出一句"无法安全验证 wsl2 环境"的提示，卡了很久。后来才反应过来，这是 openclaw 在启动前会检查 WSL2 是否可用并验证环境类型，如果系统里是 WSL1、或者内核没更新、又或者虚拟机平台功能没打开，都会触发这个报错。

解决思路也简单。先在 PowerShell 里执行：

wsl --status

这条命令会输出当前默认版本、内核版本和发行版信息。如果显示默认版本是 1，或者根本没有输出，那就先把默认版本切到 2：

wsl --set-default-version 2

注意，WSL2 依赖 Windows 的虚拟机平台功能。如果切换时提示"需要启用虚拟机平台"，用管理员身份打开 PowerShell 执行：

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完重启 Windows，再回来跑wsl --status就能看到 WSL2 就绪了。这里要特别提醒，不要只盯着报错本身，报错里的两个关键词很关键："由于未安装或未启用虚拟机平台"和"由于 Linux 内核版本过旧"。前者用 dism 指令解决，后者需要去微软官网下载最新的 WSL2 内核更新包。我一开始只执行了wsl --update，发现不够，还得手动更新内核。

2.2 Node.js 与 openclaw 核心安装

WSL2 环境就绪后，接下来要把 openclaw 本体跑起来。很多人搜"node.js官网下载 openclaw"，其实逻辑是先装 Node.js 运行时，再安装 openclaw 项目。我建议在 WSL2 的 Linux 环境里装 Node.js，而不是在 Windows 里装，因为 openclaw 很多依赖都是 Linux 原生的，跨平台编译容易出问题。

在 WSL2 终端中，我用的安装方式是：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v

Node.js 版本建议用 18 或 20 LTS。装完 Node.js，再拉 openclaw 的代码仓库。我用的是 git clone 方式：

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

初次npm install会比较慢，因为依赖里包含一些编译型包。如果安装中途报错，常见原因是缺 build-essential 和 python3：

sudo apt-get update sudo apt-get install -y build-essential python3

装完后先用npm run dev启动看看，看日志是否正常监听本地端口。这里要说一下我的体会：很多人第一次启动就急着配一堆东西，结果日志刷屏、报错满天飞。正确做法是先用默认配置跑一个最小实例，确认框架能起来、能对话，再逐步加外部依赖。我第一轮先跑通默认模型接口，第二轮才接到 qwen2.5-3b，整个调试过程清晰很多。

2.3 Windows Companion 怎么配置

openclaw 在 Windows 上有两个组成部分：一个是跑在 WSL2 里的核心服务，另一个是 Windows Companion。后者负责让 openclaw 能调用原生 Windows 应用，比如打开记事本、模拟键盘输入、读取窗口标题等。核心服务和 Windows Companion 之间通过本地 WebSocket 通信。

首次配置时，我遇到的最大问题是不清楚 Companion 的端口。openclaw 默认会让核心服务监听某个本地端口，比如 4317 或 7800（具体以你拉取版本的文档为准），Companion 必须以相同的端口连接。我一开始两个组件各用各的配置，结果一直连不上。后来检查启动日志才发现两边通信地址不一致。

操作方法：先启动核心服务，看日志里打印的 WebSocket 地址；再打开 Windows Companion 的设置页，把地址填成相同的 host 和 port。这里有个细节，Windows 防火墙通常会在第一次启动时弹窗询问是否放行 Node.js，一定要选"允许"。如果之前不小心点了取消，打开"Windows 安全中心-防火墙-允许应用通过防火墙"，把 Node.js 的专用和公用网络都勾上。防火墙没放行时，表现是：核心服务日志显示客户端已连接，但 Companion 那边一直报"连接被拒绝"。

3. 搬到 Linux 与云服务器：Ubuntu 部署要点

3.1 Ubuntu 安装完整流程（含依赖与目录安排）

在 Windows 上跑通后，我决定把 openclaw 部署到一台 Ubuntu 服务器上，做一个常驻后台的个人助理。Ubuntu 22.04 LTS 是我推荐的系统版本，依赖相对新，社区文档也齐全。流程比 Windows 简单，因为没有 WSL 那层，直接面向 Linux。

先更新系统，再装基础依赖：

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

然后用一个低权限用户运行 openclaw，不要直接塞在 root 下：

sudo useradd -m -s /bin/bash openclaw sudo -u openclaw git clone https://github.com/openclaw/openclaw.git /home/openclaw/openclaw cd /home/openclaw/openclaw sudo -u openclaw npm install

目录规划上，我的建议是明确区分代码目录、数据目录和日志目录。代码目录放仓库本身；数据目录用环境变量指定，比如/home/openclaw/data，用来放索引、向量库和对话记录；日志目录单独建，方便排查问题。如果一股脑全堆在默认路径，后面升级或备份会非常痛苦。

启动方面，我优先用 systemd 而不是终端开着跑。在/etc/systemd/system/openclaw.service里写：

[Unit] Description=openclaw service After=network.target [Service] User=openclaw WorkingDirectory=/home/openclaw/openclaw ExecStart=/usr/bin/npm run start Restart=always RestartSec=5 Environment=NODE_ENV=production [Install] WantedBy=multi-user.target

然后sudo systemctl daemon-reload && sudo systemctl enable --now openclaw。用 systemd 的好处是崩溃自动拉起、开机自启、日志统一走 journalctl，省心不少。

3.2 阿里云免费试用实例上的部署注意点

阿里云免费试用实例通常给的是 2 核 4G 或 2 核 2G 的配置。这种配置跑 openclaw 核心服务完全够，但如果想本地跑 qwen2.5-3b 这类模型，会有点紧张。我的做法是把模型推理放到另一台机器上（或者直接用 Ollama 搭配 4G 以上的机器），云服务器上只跑 openclaw 的调度和知识库服务。

部署到云服务器时，有三个坑要注意。

第一个是安全组。阿里云控制台的"安全组-入方向规则"默认可能只放行 22 端口。openclaw 的 Web 界面端口（比如 3000 或 4317）和 API 端口必须手动添加安全组规则，否则外部永远访问不了。我一开始在服务器上把 ufw 也打开了，结果忘了放行对应端口，双重拦截。后来统一改成只在阿里云安全组层控制，服务器内部 ufw 只开 22，省了很多麻烦。

第二个是配置文件里的地址。在本地调试时，openclaw 的 API 地址可能写成了 localhost。部署到服务器后，要让服务监听0.0.0.0才能被外部访问。如果想让接入更安全，最好不要把 Web 界面直接暴露到公网，而是通过 SSH 隧道访问，或者在前面套一层带认证的反代。

第三个是内存占用。openclaw 加载索引和启动 Node 进程会吃掉一部分内存，如果实例只有 2G，再跑个 qwen2.5-3b 的 Ollama 就基本满载了。建议在免费实例上只跑 openclaw + 云数据库或远程模型 API，把资源密集型任务拆出去。真要在本地跑模型，就升级到 4G 或 8G 实例。

4. 接入模型与知识库：qwen2.5-3b 和 Obsidian

4.1 为什么选 qwen2.5-3b：本地模型的取舍

在模型选型上，我最终把 qwen2.5-3b 关联到了 openclaw。选它的原因很直接：资源占用适中、中文指令理解能力强、开源社区活跃。对初次使用 openclaw 的人来说，3B 级别的小模型是性价比最高的起点——用 Ollama 就能跑，不需要独立 GPU，内存占用约 2.5G 左右，还能保证响应速度。

关联方式很简单。先在本机装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b

然后在 openclaw 的配置里指定模型相关参数。以常见的.env配置为例：

OPENCLAW_MODEL=qwen2.5:3b OPENCLAW_BASE_URL=http://localhost:11434

如果你用的是 openclaw 的配置文件（config.yaml 或其他），逻辑也是一样的：模型名指向 Ollama 里的 qwen2.5:3b，接口地址指向 Ollama 的默认端口 11434。配置完成后，重启服务并随便提一个问题，如果日志里能看到模型加载，就说明关联成功。

但要提醒一句：3B 模型的能力边界是有的，它适合摘要、结构化提取、普通问答，不适合复杂推理和长文生成。如果你拿它写代码或做深度分析，会觉得"不太聪明"。这很正常，毕竟参数量摆在那里。我建议先用 3B 跑通流程，确认真个链路没问题后，再决定是否换 7B、14B 或者接云端更大的 API。别一上来就调大模型，否则你会分不清是 openclaw 的问题还是模型的问题。

4.2 关联 openclaw 与 Obsidian 的实践

Obsidian 是很多人知识库的大本营，openclaw 能和它联动是我决定仔细研究它的最大原因。联动后的效果是：你可以用自然语言直接问"我上周关于 openclaw 部署的笔记里，提到端口冲突的解决办法是什么"，openclaw 会去你的 Obsidian 仓库里检索，找到相关片段，再结合上下文回答。

我的配置思路是让 openclaw 直接读取 Obsidian vault 的本地文件目录。Obsidian 的 vault 本质就是一堆 Markdown 文件，所以只需要在 openclaw 里把 vault 路径加进来。实际操作时，先找到你的 Obsidian 仓库根目录，比如D:\Documents\ObsidianVault，然后在 openclaw 的知识库配置里填这个路径。

这里有几个隐藏问题。第一，Windows 路径在 WSL2 里的写法不一样，D:\Documents\ObsidianVault要写成/mnt/d/Documents/ObsidianVault，否则 WSL2 里的 openclaw 找不到。第二，Obsidian 的 vault 里如果有大量附件和二进制文件，openclaw 建立索引时会非常慢，建议配置只扫描.md文件或指定排除目录。第三，Obsidian 端需要支持外部程序读取文件，不用额外开插件；但如果你想让 openclaw 反向写入笔记，一般需要安装"Local REST API"插件并启用。注意，反向写入有风险，我建议先只读测试，确认稳定后再开写权限。

实际体验下来，openclaw 接上 Obsidian 后，搜索效率比 Obsidian 自带的全文搜索高很多，因为 openclaw 会先做分词和向量化，再结合模型回答。如果你有个几百篇笔记的仓库，喂进去后几乎可以当私有小助手用。

5. 初次使用过程中的坑与排查实录

5.1 常见报错速查表

下面这张表是我从初次上手到部署云服务器过程里，实际遇到且解决掉的典型问题。每个问题后面是我亲测有效的排查思路。

5.2 几个亲测有用的实操技巧

最后分享几个我第一次跑 openclaw 时觉得特别值得记住的技巧。

第一条，永远从最小闭环开始。所谓最小闭环，就是"能启动、能对话、能说一句正常的话"。在没有连通模型之前，不要让知识库、Companion、外部服务等一堆组件参和进来。我第一次直接把 Obsidian 和 qwen2.5-3b 一起配置，结果报错的时候根本分不清是哪一环出了问题。后来我把所有外部依赖都停掉，只留默认配置，一条条排查，半小时就定位到是路径写错了。这比大海捞针快得多。

第二条，善用 verbose 日志模式。openclaw 的日志输出平时比较精简，但遇到连接类问题时，开启 verbose 级别会打印详细的请求和响应体。我遇到过一次 "openclaw 与 Obsidian 连接失败" 的报错，普通日志只显示一句失败原因，开启 verbose 后才发现是读取 vault 时把隐藏目录.obsidian也当成笔记目录去索引了，导致疯狂扫描小文件。在配置里排除.obsidian目录后，问题立刻消失。这个小问题如果你只看表面报错，能折腾半小时。

第三条，固定端口和环境变量。openclaw 涉及多个子服务时，端口经常冲突。我建议把核心服务、模型服务和知识库服务的端口固定下来，别用默认随机分配的模式，否则每次重启可能变端口，日志里到处都是连接失败。环境变量也一样，全部集中在一个.env文件里管理，不要在多个配置文件里散着改。

第四条，也是我自己这次最深的体会：把"跑起来"和"用起来"分开看待。初次使用 openclaw，真正的价值不是把服务部署到云服务器上就算成功，而是让 AI 在你的数据里干活。我自己在本地先用 WSL2 把最小闭环跑通，观察它如何检索、如何组织上下文、如何处理长文本，然后才决定部署到哪、用哪种模型。在本地 WSL2 阶段收集的问题，比在云服务器上纠结防火墙问题更有价值——因为后者网上随手一搜就有答案，前者却只有在你真正用它处理自己的数据时才会浮现。

如果你也想上手 openclaw，我的建议是先把本文的第二章看完，在 Windows 上把环境跑起来，然后用 qwen2.5-3b 做一次完整的对话，再去考虑 Obsidian 和云服务器。这样最不容易劝退。

最后再说一个小细节：我后来重装时发现，openclaw 的配置目录其实可以在不同机器间直接复制，只要把.env里的路径改一下就能用。所以我建议你在首次配置完成后，第一时间备份一下配置文件。后面不管是迁移到 Ubuntu 还是阿里云实例，都能省不少事。