最近折腾了一个叫 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或者根本没有输出那就先把默认版本切到 2wsl --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 -vNode.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 和 python3sudo 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] Descriptionopenclaw service Afternetwork.target [Service] Useropenclaw WorkingDirectory/home/openclaw/openclaw ExecStart/usr/bin/npm run start Restartalways RestartSec5 EnvironmentNODE_ENVproduction [Install] WantedBymulti-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 和 Obsidian4.1 为什么选 qwen2.5-3b本地模型的取舍在模型选型上我最终把 qwen2.5-3b 关联到了 openclaw。选它的原因很直接资源占用适中、中文指令理解能力强、开源社区活跃。对初次使用 openclaw 的人来说3B 级别的小模型是性价比最高的起点——用 Ollama 就能跑不需要独立 GPU内存占用约 2.5G 左右还能保证响应速度。关联方式很简单。先在本机装 Ollamacurl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b然后在 openclaw 的配置里指定模型相关参数。以常见的.env配置为例OPENCLAW_MODELqwen2.5:3b OPENCLAW_BASE_URLhttp://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 常见报错速查表下面这张表是我从初次上手到部署云服务器过程里实际遇到且解决掉的典型问题。每个问题后面是我亲测有效的排查思路。报错现象根本原因解决办法提示无法安全验证 wsl2 环境WSL2 未启用或内核过旧PowerShell 执行wsl --status检查wsl --set-default-version 2更新内核npm install 阶段报错 EACCES当前用户对 node_modules 无权限不要用 root使用普通用户或sudo chown -R $(whoami) ~/.npmopenclaw 能启动但访问 404服务端口没监听或配置里的 host 不对检查启动日志确认监听地址改为0.0.0.0模型答复超时或连接失败Ollama base_url 配置错误或未启动确认OPENCLAW_BASE_URL对应的端口可访问Ollama 需保持运行Obsidian vault 加载为空路径格式错误WSL 下路径用/mnt/c/...确认 vault 目录下有 .md 文件云服务器外部无法访问安全组或 ufw 未放行端口在阿里云安全组入方向增加规则同时检查服务器内防火墙日志乱码或中文显示异常终端编码问题使用 UTF-8 环境执行export LANGen_US.UTF-85.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 还是阿里云实例都能省不少事。