OpenClaw实战：从WSL2环境配置到跑通第一句Hello

如果你关注AI智能体（Agent）方向，最近大概率刷到过OpenClaw这个名字。它是一个开源的、本地优先的个人AI助手运行时，和市面上那些套壳ChatBot完全不同，它更像是给大模型装上了一套能收消息、能执行任务、能记住上下文的“身体”。我花了一个晚上从零装到跑出第一句Hello，中间踩了不少坑——WSL2环境校验失败、Node版本不兼容、模型服务连不上——这篇就把完整过程记下来。

第二篇本来应该直接讲架构和源码，但我觉得先把“跑起来”这关过了更重要，不然看再多源码也是纸上谈兵。这篇定位是实战篇：无论你是在Windows上用WSL2体验，还是打算放到云服务器上长期运行，按着我的步骤走，基本都能在一小时内听到OpenClaw亲口对你说Hello。

1. 先弄清楚OpenClaw到底是什么

1.1 它不是又一个“ChatBot套壳”

很多朋友看到OpenClaw第一反应是：又一个聊天机器人框架？这误解还挺常见。市面上大量项目做的是“对话框+大模型”的套壳应用，你问它答，上下文管理靠记忆窗口，本质上就是给模型包了一层UI。OpenClaw的定位完全不同，它是一个Agent Runtime，核心思路是把模型能力与外部世界连通起来。

我习惯把它理解成三明治结构：连接器层负责接收和发送消息，技能层负责执行具体动作，模型层负责理解和生成。消息从哪来不重要——命令行、Microsoft Teams、以后接入的Discord、邮件都行；任务落到哪也不重要——写笔记、查资料、调接口都行，只要连接器、技能、模型三方定义清楚，就能拼出一个能自己干活的数字助手。

用生活化的类比就是：大模型是大脑，OpenClaw是给大脑配了五官、手脚和通讯录。你不需要在代码里去管“Teams消息怎么解析”“技能函数怎么被调用”“上下文怎么持久化”，这些OpenClaw都处理了，你只要把各层插进去。

1.2 为什么选择OpenClaw：架构上的几个核心亮点

先看连接器架构。OpenClaw把“消息接入”抽象成了Connector接口，官方目前提供了CLI和Microsoft Teams等实现。这意味着你可以先用命令行把核心流程调通，再无缝切换到Teams里跟Agent对话，不用重写业务逻辑。这个设计对后期维护特别友好，我见过太多项目把消息处理逻辑跟业务逻辑揉在一起，换一个渠道就得伤筋动骨。

再看技能扩展机制。在OpenClaw里，写一个技能约等于导出一个包含name、description、execute方法的JavaScript对象。它跟函数调用的区别在于，技能有独立的描述元信息，模型看到描述才知道“什么时候该调它”。这种设计本质上是把工具调用（Function Calling）工程化，把技能注册、参数校验、结果回传都统一了规则。

然后就是模型可插拔。OpenClaw走的是OpenAI兼容接口，官方文档支持直接配置任意兼容服务，包括Ollama本地模型、通义千问等。我实测下来，从云端模型切到本地模型只是改两个环境变量的事，这给了用户很大的选择空间——隐私敏感的数据用本地模型，复杂推理用云端大模型。

最后是本地优先。OpenClaw的会话记录、技能状态都默认存在本地文件系统里，没有强制要求上云。对个人用户来说这意味着数据自主权，对开发者来说则意味着调试方便——出问题了直接翻本地日志和存储文件就行。

2. 安装前的环境准备：WSL2、Node.js与Git

2.1 WSL2环境检查与“无法安全验证”报错

Windows用户我强烈建议用WSL2跑OpenClaw。原因很现实：生产环境绝大部分是Linux，你在Windows里踩的路径分隔符、权限模型、进程管理问题到了服务器上全都得重来一遍；而WSL2是一个完整的Linux内核虚拟机，从开发到部署的无缝度最高。

安装OpenClaw的脚本在PowerShell里会自动检查WSL2环境，我遇到的最典型报错就是：

无法安全验证WSL2环境。请在powershell中运行wsl --status

这个提示看起来像死循环，其实定位思路很清晰：既然它要你运行wsl --status，那你就先跑一次，看输出到底卡在哪一关。我在PowerShell里执行：

wsl --status

如果输出“适用于 Linux 的 Windows 子系统”版本信息正常，说明WSL本体没问题；如果提示未安装，就执行：

wsl --install

装完之后还要确认发行版版本，因为OpenClaw要求WSL2，不是WSL1：

wsl -l -v

看到VERSION列是2就OK，是1的话用下面命令升级默认版本：

wsl --set-default-version 2

这里有个细节：这些命令必须在PowerShell或CMD里跑，不能在WSL内部跑，因为wsl.exe是Windows侧的管理工具。我第一次没注意，直接在Ubuntu终端里敲wsl --status，提示找不到命令，还以为是WSL坏了，实际是搞错了执行环境。

2.2 Node.js与Git：用nvm管理版本最省心

OpenClaw基于Node.js开发，安装前需要Node.js环境。官方要求Node 20 LTS或更高版本，低于18基本跑不起来，启动时会直接抛语法错误。我不想在系统目录里装死版本，所以用的是nvm（Node Version Manager），这套方案在Linux和WSL2下都通用。

WSL2的Ubuntu里先更新软件源、安装编译依赖：

sudo apt update && sudo apt install -y curl git build-essential

然后安装nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后让nvm生效，再装指定的Node版本：

source ~/.bashrc nvm install 20 nvm use 20

验证一下：

node -v npm -v

我这里输出的是v20.11.0和10.2.4。如果你之前装过Node，务必确认node -v是大版本20+，否则后面openclaw init会报出各种莫名其妙的模块错误。

Git是必须要有的，OpenClaw在初始化项目时要拉取模板仓库，技能市场功能也需要Git。上面apt命令里已经带上了Git，验证：

git --version

2.3 准备云服务器（可选但推荐）

如果只想体验一把，WSL2就够了。但如果你想7x24小时挂着Agent，我建议直接上云服务器。现在几家大厂都有免费试用套餐，比如阿里云的免费试用，选Ubuntu 22.04、2核4G内存的配置就够跑OpenClaw加一个小尺寸模型了。

登录云服务器后第一步不是装环境，而是先去控制台看安全组规则。OpenClaw的CLI连接器不用开端口，但如果要接Teams或其他外部服务，就得放行回调端口（比如8080或按配置指定的端口）。我吃过这个亏：服务器上服务明明起来了，外部就是连不上，查了半天发现是安全组默认只开了22端口。

地域选择上没那么多玄学，选一个离你近的节点就行，延迟会低一些。系统盘给个40G以上，因为模型文件、日志、会话记录日积月累，20G的默认盘很快就会吃紧。

3. 快速安装OpenClaw并完成初始化

3.1 用npm全局安装

环境准备好之后，安装OpenClaw本身反而很简单：

npm install -g openclaw

整个过程会拉取依赖，耗时取决于网络状况。装完验证版本：

openclaw --version

以我写这篇时的版本为参考，输出类似：

openclaw/0.4.2 linux-x64 node-v20.11.0

如果提示找不到openclaw命令，八成是npm全局安装目录没加到PATH。用nvm装Node的情况下，执行：

npm config get prefix

然后把输出里的目录加到~/.bashrc里，再source一下就行。这个问题在Linux上太常见了，不是OpenClaw的锅，是Node环境变量配置的问题。

3.2 初始化项目：把目录结构一次看清

OpenClaw不像别的工具那样直接全局跑服务，它更推崇“项目化”管理。新建一个目录并初始化：

mkdir hello-agent && cd hello-agent openclaw init

初始化过程会问几个问题，包括项目名称、默认模型、是否启用CLI连接器等。完成后目录结构是这样：

hello-agent/ ├── config/ │ └── openclaw.yaml ├── skills/ ├── connectors/ ├── data/ │ ├── memory/ │ └── sessions/ ├── logs/ └── package.json

重点在config/openclaw.yaml，这个文件是OpenClaw的全局配置中心。打开看下，核心块大概是：

model: provider: openai-compatible baseURL: http://localhost:11434/v1 modelName: qwen2.5-3b connectors: - type: cli enabled: true skills: autoLoad: true directory: ./skills

config文件里每段配置的意义比改动更重要。model这块决定了Agent的“大脑”连到哪，connectors决定了“五官”开哪些通道，skills则决定了“手脚”从哪里加载。理解了这个三层对应关系，后面调参就不慌了。

3.3 配置模型后端：从Qwen到本地模型

OpenClaw默认模型配置走向OpenAI兼容接口，所以后端选择非常灵活。先用最省事的方式：环境变量。

export OPENCLAW_API_KEY="你的密钥" export OPENCLAW_MODEL="qwen2.5-3b" export OPENCLAW_BASE_URL="https://对应服务的接口地址/v1"

这里我特别说一说Qwen2.5-3b这个组合。3B参数量的模型属于小尺寸，CPU也能跑，但效果确实有限；在OpenClaw里接它，胜在免费场景够用、响应快，适合先把流程跑通。等到要处理复杂任务时再换更大模型。

如果不想依赖云端API，用Ollama跑本地模型是另一个好选择。先装Ollama并拉取模型：

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

确认Ollama的API地址是http://localhost:11434/v1后，改一下openclaw.yaml：

model: provider: openai-compatible baseURL: http://localhost:11434/v1 modelName: qwen2.5:3b

然后验证模型连通性：

openclaw model list

能列出模型信息就说明链路通了。这一步卡住的人很多，九成是baseURL写错，OpenAI兼容接口一定要带/v1后缀，不带的话HTTP 404。

4. 运行第一句“Hello”：创建技能并对话

4.1 写一个最简单的Hello技能

OpenClaw的“第一句Hello”我建议用一个自定义技能来触发，而不是直接跟模型聊天。这么做的好处是能同时验证技能加载链路、函数执行链路、结果回传链路三条核心路径，这也是OpenClaw和普通聊天工具的本质区别。

在skills目录下新建hello.js：

module.exports = { name: "hello", description: "当用户打招呼或说hello时，回复一句欢迎语", async execute(context) { const userName = context.user?.name || "friend"; return `Hello, ${userName}! OpenClaw is ready.`; } };

注意这个文件不需要手动注册到配置里，OpenClaw在启动时会扫描skills目录并自动加载。前提是配置里skills.autoLoad为true，默认就是true。

我把description写得很具体是有原因的：OpenClaw的技能调用由模型决定，模型靠description判断要不要调这个技能。如果写成“hello技能”这种一句话，模型很可能在用户说"hi"时想不起来调它；写上“打招呼或说hello”后，触发准确率会高很多。

4.2 启动CLI并发出那句Hello

技能文件放好，启动OpenClaw：

openclaw run

看到类似这样的日志就说明连接器已经就绪：

[info] loading skills from ./skills [info] skill registered: hello [info] connector cli started [info] OpenClaw is ready, type your message or /help

这时输入：

hello

你会看到日志里出现技能调用链：

[agent] skill triggered: hello [agent] executing skill: hello [skill] Hello, friend! OpenClaw is ready.

终端里同时打印出“Hello, friend! OpenClaw is ready.”，大功告成。我之所以坚持用技能而不是直接让模型回复，是因为站在源码角度看，这一句回复背后经过了“消息解析→意图匹配→技能调度→函数执行→结果回传”的完整链路。链路通了，后面接什么都稳。

再试一个模型直答的场景，输入：

What is OpenClaw?

这时没有技能被触发，模型会直接生成答案。你会发现两种模式在日志里的区别：技能调用有明确的trigger标记，模型直答则只有一条生成日志。这个区别在调试时非常有用。

4.3 把Hello接到Microsoft Teams

CLI跑通之后，很多人想尝鲜接Teams。这个流程我完整走了一遍，说下关键路径。首先需要有一个Microsoft Entra ID（旧称Azure AD）应用，在Azure门户里创建Bot注册，拿到Client ID和Client Secret。

然后在OpenClaw里添加Teams连接器：

openclaw connector add teams

按要求填入Client ID、Client Secret，向导会生成一段连接器配置。接着编辑openclaw.yaml，在connectors段加入：

connectors: - type: cli enabled: true - type: teams enabled: true clientId: "你的client-id" clientSecret: "你的client-secret" port: 8080

启动后，OpenClaw会在8080端口监听Teams的回调消息。难点在于Teams要求回调地址必须是公网可访问的HTTPS地址。如果是在有公网IP的云服务器上部署，把端口开给公网并挂上HTTPS证书即可；如果是在本地WSL2里，就需要用内网穿透工具把8080映射出去。我建议这种场景还是放到云服务器上跑，省掉一层折腾。

接入成功的标志是日志里出现“connector teams started”，然后在Teams里给Bot发一条hello，OpenClaw会像CLI模式一样触发同一个hello技能，回复消息会通过Teams连接器原路返回。到这里，你就真正理解为什么我说“连接器架构”是OpenClaw的灵魂——同一个技能，零改动从命令行跑到了Teams里。

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

5.1 WSL2相关报错速查表

很多报错集中发生在WSL2阶段，我把遇到过的和群友反馈过的问题整理成一张表，供你对照排查：

这里我想单说一句“无法安全验证WSL2环境”这个报错的处理心态。它不是指你的WSL不安全，而是安装脚本调用wsl.exe校验环境时没拿到预期结果。先别急着怀疑系统坏了，按提示在PowerShell跑一遍wsl --status，看到具体缺失项再对症下药，大多数情况跑一次wsl --install就能解决。

5.2 Node版本与全局安装权限问题

npm安装OpenClaw时最闹心的就是权限报错，典型的像：

npm ERR! code EACCES npm ERR! syscall mkdir npm ERR! path /usr/lib/node_modules/openclaw

这个错误是因为直接用系统Node安装全局包时没有写入权限。我说几个解法，按推荐顺序排列。如果你用了nvm，直接nvm use 20切到用户级Node，全局目录就在用户目录下，不需要sudo，问题自动消失。如果你用的是apt装的系统Node，那就用sudo npm install -g openclaw强行装，但后续升级会有权限纠缠，我不推荐。

还有一种情况是Node版本太老。如果你运行openclaw init时看到“SyntaxError: Unexpected token '?'”，说明Node版本低，OpenClaw用了较新的语法，老版本解析不了。用nvm切换版本后再试就好。

5.3 模型连接失败：超时与401

模型这块的问题最五花八门，但九成集中在两类。第一类是连接拒绝，日志里出现connect ECONNREFUSED。这个说明OpenClaw访问不了你配置的baseURL，常见场景是Ollama没启动，或者baseURL写成了http://localhost:11434（少了/v1）。注意OpenAI兼容接口一定要带/v1路径，Ollama的兼容端点就是/v1。

第二类是401 Unauthorized，这通常是调用云端模型服务时API Key错误或过期。我建议在环境变量里设置时先echo出来确认没拼错，有些key带前后空格，肉眼根本看不出来。还有一点，OpenClaw读取环境变量是在启动时做的，你改了配置后必须重启openclaw run才会生效，没有热加载，别傻等。

5.4 连接器收不到消息时的排查思路

CLI连接器没消息，先看光标有没有出现、日志里有没有“connector cli started”；Teams收不到消息，链路更长，按“网络链路→Bot配置→OpenClaw配置”顺序排查。

第一步检查端口监听：在服务器上执行ss -lntp | grep 8080，如果能看到Node进程在监听，说明服务侧正常。第二步看公网连通性：从外网访问http://你的公网IP:8080，能返回内容或至少不是连接超时，说明网络链路通。第三步看Teams回调：在Azure门户的Bot配置里检查Messaging endpoint是否填对，必须以https开头，路径要指向OpenClaw的回调路由。官方日志里会打印具体路由路径，照着抄就行。

我遇到过的最不起眼问题是端口没放行。云服务器安全组、系统防火墙、Teams回调URL三个地方任何一处没配好，都会表现为“Bot无响应”。建议配完一步测一步，别全部配好再一次性测试，否则出了问题根本不知道卡在哪层。

写在最后的实操体会

我自己的经验是，第一次跑通OpenClaw的Hello时，最大的收获不是那句回复本身，而是通过这次流程把“连接器—技能—模型”这个三层架构在脑子里钉死了。后来翻源码时，很多抽象概念都能和实际操作对得上号——连接器接口怎么调度、技能注册表如何维护、模型调用怎么抽象，心里都有了具象的锚点。

再分享一个后续扩展的小建议：在CLI跑通后，可以试着给OpenClaw加一个Obsidian笔记技能。用Node.js写个函数读Markdown文件、追加内容到指定笔记，通过描述字段告诉模型“当用户提到记笔记时调用我”。这是我做过性价比最高的扩展，它能把Agent从“聊天玩具”变成真正能沉淀信息的工具。下一章深入源码时，我会围绕技能注册和调用链展开讲，那才是把OpenClaw用明白的关键。