我跟OpenClaw的第一次见面，其实不是从“Hello”开始的。作为《OpenClaw架构与源码解读》系列的第2章，这一篇按理说该老老实实讲安装，但我想先把结论甩在前面：OpenClaw的安装过程，比普通软件更接近“给一艘船补好龙骨再试水”——你装的不只是一个包，而是一整套运行时、连接器和配置体系。等这一章跑完，你会听到它亲口对你说出那句“Hello”，但更值钱的是，你会知道这一声Hello到底经过了哪些环节，这正好为后面逐层拆解源码打下地基。
这篇内容适合三类人：想快速上手OpenClaw但被各种报错劝退的初学者；准备基于OpenClaw做二次开发的工程师；以及单纯想把agent框架跑起来、再掂量掂量它架构分量的人。我会按自己实际踩过的路子，从环境准备讲到三种安装方式，再讲到第一句Hello背后的完整链路，最后附一份翻车记录。全程尽量把“为什么这么做”讲透，不搞黑盒操作。
1. 安装之前：先搞懂OpenClaw到底在跑什么东西
很多人第一次装OpenClaw，都误以为它就是一个命令行工具，跑起来就能聊。我最初也这么想，结果装完后发现，事情没那么简单。
1.1 你不是在装一个程序，而是在拉起一套运行时
OpenClaw的定位是个人AI代理框架，核心设计借鉴了生物体的信号传递机制。它的名字本身就带着线索——“Claw”指的是节肢动物的钳爪，在系统里对应“Gland”这套信号腺体网络。你可以把整个框架理解成三层的结构：
- 核心运行时（Clawdbot Runtime）：负责大脑逻辑，也就是agent的思考、工具调用、上下文管理；
- 连接器层（Connectors）：负责“张嘴说话”，对接终端、OBSIDIAN、云服务、智能设备等外部系统；
- 控制台与观测层（如OBSIDIAN）：负责让你看到它在想什么、每一步干了什么。
安装这件事，本质上是把这三层各自拉起来，并且让它们通过配置互相握手。所以你在安装时一定会接触到几个看似多余的问题，比如“要不要装OBSIDIAN？”“运行时监听哪个端口？”——它们不是为了折腾你，而是在初始化这套多层架构。
1.2 和普通npm包的本质区别
如果拿装修房子来打比方，装一个普通npm包相当于买了个成品家具，搬进来就能摆；装OpenClaw更像先把毛坯房的水电路线铺好，再决定每个房间放什么家具。这就是为什么官方文档会强调依赖Node.js 18以上、需要一个能访问模型服务的网络环境，以及某些系统组件（比如Windows下的WSL2）必须提前就位。
我在第1章讲过，OpenClaw内部有一个“Pulse”信号循环，agent每收到一条消息，会像心跳一样反复执行“感知—推理—行动”的循环，直到确认任务闭环。安装阶段其实也在验证这件事的最小版本：你的运行时能不能接收外部消息、能不能把消息传给模型、模型返回的内容能不能被连接器吐出来。第一句“Hello”之所以重要，就是因为它是这条循环第一次完整走通的标志信号。
2. 环境准备：两个最容易翻车的隐藏关卡
我在各类社区帖子里看到最多的求助，集中在两类问题上：一类是node环境不对，另一类是Windows用户压根没准备好WSL2。这两关没过，后面所有安装步骤都是白搭。
2.1 依赖清单与推荐版本
这里给一份我实测过的基准清单，照着准备基本不会踩坑：
| 依赖项 | 推荐版本/要求 | 用途 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 / 24.04；Windows 10/11（需启用WSL2） | 运行主程序 |
| Node.js | 18.x LTS及以上（建议20.x） | 运行时基础环境 |
| npm | 9.x及以上（随Node一起安装） | 包管理 |
| Git | 2.x最新版 | 拉取源码 |
| 内存 | 至少2GB空闲内存 | agent推理与上下文存储 |
| 模型API | 本地模型或远端API均可 | 提供对话与推理能力 |
Node版本这件事，我见过最典型的错误是用户直接用了Ubuntu自带的node 12，安装时看着很顺利，一启动就报模块语法错误。原因很简单，OpenClaw的代码用了比较新的JavaScript语法和API，Node 12根本不认识。
2.2 Windows用户：WSL2不是可选项，是必选项
如果你在Windows上安装，绕不开“无法安全验证WSL2环境。请在PowerShell中运行wsl -- status”这类提示。我第一次看到这个提示时很懵，明明下载的包没问题，怎么会卡在环境验证上。
说穿了，OpenClaw的连接器层在Windows原生环境下的信号处理机制不完整，需要通过WSL2的Linux内核来运行。WSL2在这里扮演的不是“虚拟机”这种笨重角色，而是一个轻量级的中转环境——它让OpenClaw能拿到完整的Linux系统调用能力，尤其是文件系统事件监听和进程间通信这两块。
正确做法是在管理员权限的PowerShell里执行：
wsl --install # 装完后重启，再执行一次状态检查 wsl --status看到“默认版本：2”这类输出说明就绪了。如果你已经装过WSL1，记得手动升级：
wsl --set-default-version 2我个人的建议是，安装OpenClaw不要直接在Windows终端跑，而是装完WSL2后用Ubuntu终端进去操作。这一章后面的所有命令我都默认在Linux环境里执行，Windows用户等于多套了一层经过WSL2转换的Ubuntu环境，命令完全一致。
3. 三种安装姿势：我为什么最终选了源码方式
OpenClaw的安装不是只有一条路，官方社区里常见的做法有三类：一键脚本、Docker容器、源码编译。三种各有用武之地，但结合本系列后面要逐层读源码的目标，我强烈推荐源码方式。
3.1 姿势一：企业级省心路线，Docker容器
如果只是临时体验、不想让系统里多一堆依赖，Docker是最快的方式：
docker pull openclaw/openclaw:latest docker run -d --name openclaw \ -p 3000:3000 \ -v openclaw-data:/app/data \ openclaw/openclaw:latest这里-v挂载的数据卷很重要，OpenClaw的配置、会话记录、记忆文件都存在这个目录下，不挂载的话容器一删就全没了。
这个姿态的优点是干净，缺点是调试时像隔着一层毛玻璃，想跟踪源码逻辑就比较费劲——容器里的文件和宿主机隔离，打断点、改代码都需要额外配置。
3.2 姿势二：想省事的官方一键脚本
官方其实提供了快速安装脚本，在Linux或者WSL里执行：
curl -fsSL https://openclaw.example.com/install.sh | bash我不太推荐这种纯管道方式，因为你看到的报错很可能不是脚本本身的错误，而是脚本里隐含的环境假设在你机器上不成立。比如脚本会默认npm registry走官方源，网络一抖动就是大半个小时的超时重试。
3.3 姿势三：源码安装，也是本章的重点
源码方式最大的优势在于——你能看到它启动那一刻到底加载了什么。后面每读一行源码，心里都有对应的实感。步骤很清晰：
# 1. 拉取主仓库 git clone https://github.com/openclaw/openclaw.git cd openclaw # 2. 安装依赖 npm install # 3. 启动前的自检 npm run doctornpm install阶段是最容易出问题的，报错大多集中在node-gyp需要编译原生模块上。常见报错是缺少Python或C++编译工具链，Ubuntu下执行：
sudo apt-get install -y python3 make g++装完后需要重新编译依赖，先清理再装：
rm -rf node_modules package-lock.json npm install我个人在这个阶段踩过一个很隐蔽的坑：系统里同时存在多个Node版本，npm解析到的依赖树是旧版本环境生成的，导致启动时报一堆莫名其妙的“Cannot find module”。后来统一用nvm管理Node版本，每个项目锁定版本后才算彻底解决。
3.4 为什么我坚持推荐源码方式
回到本章标题，既然叫《架构与源码解读》，那你装的就不仅是“能跑”的软件，而是“能读”的活代码。源码目录结构本身就是一份架构文档。
openclaw/ ├── src/ # 核心源码 │ ├── core/ # agent推理核心 │ ├── connectors/ # 连接器实现 │ └── runtime/ # 运行时调度 ├── config/ # 配置文件目录 ├── scripts/ # 辅助脚本 └── docs/ # 文档资源后面我们读源码时，会频繁回到这个目录里去对照。如果装的是Docker版，光是把源码目录映射出来就要多绕好几道弯。
4. 初始化与配置：把运行时“叫醒”的关键动作
依赖装完，不代表就能直接Hello了。OpenClaw需要初始化一个属于你的配置文件目录，并告诉你它准备以什么身份、什么端口、接什么模型来运行。
4.1 初始化命令
在项目根目录执行：
npm run init它会生成一个用于存放运行时配置的目录。生成后你会看到命令行提示“runtime config initialized”之类的字样。这一步干的事情，相当于给agent办了一张“身份证”——里面写清楚它的名字、工作目录、以及模型提供方。
配置文件通常是JSON格式，我强烈建议安装完立刻打开看一眼，因为它就是后面所有调试的入口。关键字段大概长这样：
{ "agent": { "name": "openclaw", "mode": "interactive" }, "runtime": { "host": "127.0.0.1", "port": 3000 }, "models": { "provider": "openai-compatible", "model": "qwen2.5-3b", "apiKeyEnvVar": "OPENCLAW_MODEL_API_KEY" } }注意这里的apiKeyEnvVar字段，它不直接保存密钥，而是指向一个环境变量名。这样做的好处是密钥不会明文写进配置文件，避免提交代码时把密钥一起传上去了。
4.2 配置模型提供方：以Qwen模型为例
很多人在社区问“qwen2.5-3b怎么关联到OpenClaw”，其实关键就是两处配置：
- 在
models.provider里指定兼容OpenAI协议的接口地址； - 在
models.model里填写具体的模型名。
假设你本地用Ollama跑了一个qwen2.5:3b模型，那么接口地址通常就是本机端口后面的/v1，对应配置如下：
export OPENCLAW_MODEL_API_KEY="ollama" export OPENCLAW_MODEL_BASE_URL="http://localhost:11434/v1"如果接的是云端服务，那API key和base URL就换成服务商提供的信息。这一步如果配置错了，你往往会发现程序能启动，但一问话就报“model request failed”。我在排查这类问题时总结的经验是：别急着怀疑OpenClaw，先用curl直接打一下模型服务地址，确认模型侧是通的，再回头看配置映射关系。
4.3 验证配置的命令：doctor一次看全
配置完成后，先别急着启动，用内置的doctor命令自检：
npm run doctor这个命令会依次检查Node版本、运行时配置合法性、模型服务可连通性、连接器端口占用情况。如果哪一项有问题，它会直接输出红色的失败标志和原因。我见过很多人跳过这步直接启动，结果OBSIDIAN页面白屏、终端倒是启动了，但一问话就卡死，最后来回排查浪费了大半天。doctor这一步花不了两分钟，强烈建议每次改完配置都跑一遍。
5. 第一句Hello：三种姿势与最小闭环验证
环境通了、配置填了，现在才轮到“Hello”登场。这一步的目标不是看到一句话，而是确认整条链路真的活着。
5.1 最朴素的方式：终端直连
启动运行时：
npm run start看到输出里出现类似“runtime listening on 3000”的日志后，agent就在待命了。直接在当前终端输入：
Hello正常情况下它会回你一段自然的问候。注意这里有个细节：你输入的内容会先被连接器层解析成内部消息，再进入agent核心循环，模型返回后经过同一条链路吐回终端。所以这句Hello本身就是一次完整的数据往返。
5.2 通过预设消息让启动即问候
如果你不想手动敲，也可以在配置里加一个初始消息。以“seed message”为例，效果是启动后agent会主动向你打招呼：
{ "bootstrap": { "initialPrompt": "对用户说一句Hello，并简单介绍一下你的能力范围" } }这种情况下，那句问候是agent根据用户意图主动生成的，而不是程序硬编码的。第一次看到这一幕时，我愣了一下——因为它证明了模型确实在按提示词行动。
5.3 通过OBSIDIAN控制台发送Hello
OBSIDIAN是OpenClaw的可视化观测面板，装好后按配置里的地址打开页面，你会看到类似聊天窗口的界面，同时侧边栏实时滚动agent的内心活动。在控制台输入Hello，效果比纯终端直观得多：你能同时看到模型输出、工具调用记录、上下文更新三条信息流并行滚动。
这里有个判断“闭环已跑通”的四步检查法，供你参考：
| 检查项 | 预期表现 |
|---|---|
| 1. 输入送达 | 控制台或日志出现“message received”记录 |
| 2. 模型响应 | 日志里能看到agent推理过程的请求耗时 |
| 3. 结果回传 | 消息返回到输入端，屏幕上出现真实回复 |
| 4. 状态记录 | 会话内容被写入本地存储，重启后仍可查阅 |
如果前两步通了但第三步卡住，问题大概率出在连接器回传配置上；如果第三步通了但第四步没写盘，说明存储路径没权限，检查配置目录的写权限即可。
6. 把“Hello”放到显微镜下：这条消息到底经历了什么
安装只是热身，这一章真正的价值在于让你明白那一句Hello背后发生了什么。我把这条消息的完整旅程拆成五站，每一步都能对应到架构里的一个模块，后面源码解读也会沿着这条主线往下走。
6.1 第一站：连接器层，把“人话”转成“信号”
你输入的那句Hello，对agent来说只是一个原始字符串。连接器层负责把它包装成带元数据的消息对象，包含来源渠道、时间戳、会话ID等。这就像你按门铃，门口的对讲机先把声音转成电信号，再传到屋里的人耳中。
6.2 第二站：运行时调度，决定由谁来处理
运行时收到消息后，不会立刻甩给模型，而是先做一次路由判断——这条消息是闲聊、是要调用工具还是需要刷记忆。这一层是整个框架的“中枢神经”，它决定了agent的行为模式。
6.3 第三站：与大模型对话，拿到“想法”
接下来才是调用模型。配置里指向的Qwen或云端模型返回一串自然语言文本。如果你是直接读源码，会看到这一步有一个专门的模块负责组装上下文，把历史会话、系统提示词和用户输入一起打包发给模型。
6.4 第四站：工具与记忆，Hello背后是否有隐形动作
纯Hello这种消息通常不触发工具调用，但真实的agent行为里很多问题需要查文档、读文件、发HTTP请求才能回答。OpenClaw的特点在于，它会把工具调用结果再次回填给模型，让模型做下一轮判断。这一步虽然不是“Hello”的必经路径，但它决定了这个框架的上限——安装时你哪怕只为了体验，也建议把手里的文件目录配置为一个可读取的“记忆来源”，感受一下带工具链的agent比纯聊天高在哪。
6.5 第五站：返回链路，回应重新变成“人话”
模型返回的结果经过运行时校验、再交给连接器渲染成终端或OBSIDIAN页面里你能看懂的句子。到这一站，一次完整闭环才算结束。
把这条链路走通后，你会发现OpenClaw的“Hello”和普通聊天软件的本质差别：它每一步都留下了可观测、可干预的中间状态。这也是为什么它适合做架构研究的对象——你几乎能在运行时日志里看到整个思考过程。
安装阶段我们最需要记住的是消息流的走向：输入 → 连接器 → 运行时 → 模型 → 返回值 → 输出。后面源码解读的每一章，基本都是在给这条链路的某一个环节放大特写。
7. 安装到Hello路上最容易踩的五个坑与完整排查链路
既然是快速体验，我干脆把最常见的坑一次性列出来。每一个我都亲自踩过或者给朋友排查过，基本都是同一类问题的不同变种。
7.1 坑一：启动时卡在“cannot receive hello packet”
这个报错是最有迷惑性的，字面上像在说“收不到Hello包”，实际上是指运行时之间握手失败。常见的诱因有三个：
- 端口被占用——默认3000端口被别的服务占了，运行时起不来；
- 连接器配置的host写成了0.0.0.0，但系统防火墙没放行；
- 不同组件版本不匹配，比如OBSIDIAN控制台是旧版，连不上新版运行时的消息队列。
排查链路：先用lsof -i:3000查端口占用，再用doctor命令做组件版本检查，最后再看配置文件里的host字段是否符合当前环境。大多数情况到第二步就能定位。
7.2 坑二：Windows下运行时提示无法验证WSL2环境
前文说过，这类提示的根因是WSL2没装好或内核版本太旧。排查时别急着重装OpenClaw，先在PowerShell里跑：
wsl -- status wsl --update如果wsl --status显示内核版本较旧，更新并重启终端即可。注意，如果你目前同时在用Docker，确认Docker Desktop的WSL后端用的发行版和你安装OpenClaw时进入的是同一个Ubuntu发行版，否则会互相干扰。
7.3 坑三：模型API配置好了却不生效
表现是配置里写了model: "qwen2.5-3b"，启动也正常，但问答时它却说“模型不存在”或者返回完全无关的内容。根因九成是环境变量没被运行时进程读取到。我踩过一次很隐蔽的情况：在PowerShell里设了环境变量，然后通过WSL里的bash启动OpenClaw，但bash根本继承不到PowerShell的变量。解决方式是直接在WSL的bash里重新export一遍，并用echo $OPENCLAW_MODEL_API_KEY确认值已生效。
7.4 坑四：依赖编译失败，node-gyp报错
源码安装时最烦的错误就是node-gyp编译原生模块失败。报错信息里通常会出现“gyp ERR! build error”。这类问题主要是缺少编译工具链，或者Node版本过高导致部分旧模块不兼容。解决办法分两步：
sudo apt-get install -y python3 make g++ npm rebuild如果rebuild后还是不行，把Node版本降到18.x LTS再试一次。我个人最爱用nvm卡版本，每次npm install前都确认一下node -v。
7.5 坑五：OBSIDIAN控制台一直白屏
这通常不是网络问题，而是OBSIDIAN版本和运行时版本没对齐。OpenClaw的运行时和观测面板之间有版本协商机制，差太多会直接拒绝握手。排查时先看运行时日志有没有“obsidian handshake failed”字样，有的话把OBSIDIAN更新到与运行时匹配的版本。如果日志干净但依然白屏，试试强制刷新浏览器缓存——我遇到过前端代码更新但浏览器硬缓存旧资源的奇葩情况。
7.6 一套通用排查方法论
踩坑踩多了，我总结出一套“先隔离、再放大、后对照”的方法：
- 先做最小化隔离——只开终端连接器，关掉OBSIDIAN，看核心链路是否通；
- 再加详细日志——把运行时日志级别调到debug，观察消息在哪个环节断流；
- 最后对照官方文档或社区issue——很多报错其实是已知问题，直接搜报错原文比从零推理快得多。
这套方法看起来简单，但能解决九成以上安装问题。尤其是遇到那种“日志看着都正常但就是不出结果”的诡异情况，隔离法基本都能逼出真凶——我曾经花了三个小时追一个OBSIDIAN连接问题，用隔离法五分钟就发现是端口配置写重复了。
说实话，现在回头看，安装OpenClaw这一整套流程的知识密度，远超我最初预想。它不像装个游戏那样双击下一步就完事，但正是这种略显繁琐的过程，逼着你把“agent是怎么跑起来的”这件事想清楚。我个人的建议是：别急着追求花哨的插件和工具链，先把这一段最朴素的命令行对话跑通，然后回头看看日志文件里每一行记录对应的是架构里的哪个环节。这一章你亲手验证了从安装到Hello的最小闭环，下一章我们就可以正式打开源码，沿着这条链路去看它每一步的实现细节了。
