OpenClaw 源码解析（二）：源码运行与开发环境

1. 本期目标

上一期主要从整体上认识了 OpenClaw：它不是普通聊天机器人，而是一个本地优先、多渠道、可调用工具、可扩展技能、带安全隔离机制的个人 AI 助手系统。

这一期开始进入源码学习前的第一步：

复制代码

把项目跑起来。

本期主要解决几个问题：

复制代码

1. 为什么源码解析前必须先运行项目？
2. OpenClaw 运行需要哪些基础环境？
3. 普通安装和源码运行有什么区别？
4. 如何从源码启动 Gateway？
5. pnpm openclaw setup、pnpm gateway:watch、pnpm ui:build 分别做什么？
6. OpenClaw 的配置、工作区、日志、会话文件分别放在哪里？
7. 初学者运行时容易遇到哪些问题？

官方文档中说明，OpenClaw 推荐 Node 24，或者兼容使用 Node 22 LTS；如果从源码构建，pnpm 是主要的包管理工具。官方安装文档也给出了源码安装路径：git clone 仓库后执行 pnpm install && pnpm build && pnpm ui:build，再通过全局链接或仓库内命令运行。(GitHub)

2. 为什么要先跑起来？

很多源码解析文章容易一上来就讲目录和代码。

但对于 OpenClaw 这种项目，直接看代码会比较吃力。

原因是它不是单一后端服务，而是包含：

复制代码

CLI 命令
Gateway 常驻进程
Agent Runtime
Channel 插件
Control UI
Skills
Tools
Sessions
移动端 / 桌面端节点

如果没有先运行一次，很难理解这些模块之间的关系。

源码运行的目的不是为了"安装一个工具"，而是为了建立第一条主链路：

复制代码

命令行输入
    ↓
OpenClaw CLI
    ↓
Gateway 启动
    ↓
配置和工作区加载
    ↓
Agent 接收消息
    ↓
模型或工具处理
    ↓
返回结果

后续读源码时，就可以不断把代码放回这条链路中理解。

3. 普通安装和源码运行的区别

OpenClaw 有两种常见使用方式。

第一种是普通用户安装：

复制代码

npm install -g openclaw@latest
openclaw onboard --install-daemon

官方 README 中推荐新用户通过 openclaw onboard 进行引导式配置，它会帮助设置 Gateway、workspace、channels 和 skills；--install-daemon 会安装 Gateway 守护进程，使其保持运行。(GitHub)

第二种是源码开发运行：

复制代码

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm openclaw setup
pnpm gateway:watch

官方开发文档把这种方式称为 bleeding edge workflow，目标是直接在仓库中运行 TypeScript Gateway，并通过 gateway:watch 实现热重载。(OpenClaw)

可以这样理解：

复制代码

普通安装：
适合用户使用 OpenClaw。

源码运行：
适合学习源码、调试 Gateway、修改功能和写博客。

本系列博客的目标是源码解析，所以后面主要关注源码运行方式。

4. 基础环境准备

源码运行前建议准备：

复制代码

Node.js
pnpm
Git
可选：Docker
可选：macOS app / Web Control UI

官方安装文档中写到，Node 24 是推荐运行时；如果已经自己管理 Node，也可以通过 npm、pnpm 或 bun 安装 OpenClaw，其中 pnpm 主要用于源码构建。(GitHub)

对于源码阅读，我建议优先使用：

复制代码

Node 24
pnpm
Git

原因是：

复制代码

1. Node 24 是官方推荐版本。
2. pnpm 更贴近源码仓库的 workspace 管理方式。
3. Git 方便后续查看分支、提交历史和代码变更。

Docker 不是一开始必须的。官方开发文档也说明 Docker 是可选项，主要用于容器化设置或端到端测试。(OpenClaw)

5. 获取源码

首先克隆仓库：

复制代码

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

官方安装文档中的源码安装方式也是从 GitHub 克隆仓库开始，然后进入项目目录执行后续构建命令。(GitHub)

进入目录后，先不要急着看代码，可以先看三个文件：

复制代码

README.md
package.json
openclaw.mjs

它们分别对应：

复制代码

README.md：
了解项目定位、安装方式、核心功能和安全提醒。

package.json：
了解项目脚本、依赖、workspace、CLI 命令。

openclaw.mjs：
理解 OpenClaw CLI 的本地入口。

这三个文件是源码阅读的入口。

6. 安装依赖

在仓库根目录执行：

复制代码

pnpm install

这一步会安装项目依赖。

OpenClaw 是一个比较大的工程，安装依赖不是只为了一个后端服务，而是为了后续运行：

复制代码

Gateway
CLI
Control UI
Channel 插件
Skills / Tools 相关模块
测试和构建脚本

官方开发文档中，启动 dev Gateway 的第一步就是 pnpm install。(OpenClaw)

7. 初始化配置和工作区

依赖安装完成后，执行：

复制代码

pnpm openclaw setup

官方开发文档说明，pnpm openclaw setup 是新鲜源码 checkout 的一次性本地配置和 workspace 初始化步骤。(OpenClaw)

它的意义可以理解为：

复制代码

源码仓库：
放 OpenClaw 的程序代码。

~/.openclaw/openclaw.json：
放用户配置。

~/.openclaw/workspace：
放用户工作区、skills、prompts、memories 等内容。

官方开发文档也特别提醒：个人定制内容应该放在仓库外部，例如 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace，这样更新源码时不会破坏个人配置。(OpenClaw)

这一点很重要。

因为很多初学者会误以为：

复制代码

我要改 OpenClaw 的提示词或技能，就直接改源码仓库里的文件。

更合理的方式是：

复制代码

源码归源码；
个人配置和工作区归 ~/.openclaw。

8. 启动开发版 Gateway

初始化完成后，执行：

复制代码

pnpm gateway:watch

官方文档说明，gateway:watch 会以 watch 模式运行 Gateway，并在相关源码、配置和 bundled-plugin metadata 改变时重新加载。(OpenClaw)

可以这样理解：

复制代码

pnpm gateway:watch
    ↓
启动本地 Gateway
    ↓
监听源码和配置变化
    ↓
变化后自动重载

它适合源码学习和调试。

这和普通安装中的 daemon 模式不一样。

复制代码

daemon 模式：
适合稳定运行，让 Gateway 常驻后台。

gateway:watch：
适合开发调试，让源码变更能快速生效。

9. 直接运行打包后的 CLI

如果已经执行过构建，也可以直接运行：

复制代码

node openclaw.mjs gateway --port 18789 --verbose

官方开发文档中说明，pnpm build 之后可以通过 node openclaw.mjs gateway --port 18789 --verbose 直接运行打包后的 CLI。(OpenClaw)

这里有两个参数值得注意：

复制代码

--port 18789：
指定 Gateway 端口。

--verbose：
输出更详细日志。

对于源码解析来说，--verbose 很有用，因为你可以看到更多运行过程信息。

10. Control UI 和 ui:build

OpenClaw 还有浏览器控制界面。

官方文档中提到，Gateway 启动后可以打开浏览器 Control UI；本地默认地址是 http://127.0.0.1:18789/。 (GitHub)

如果你修改了 ui/ 目录下的前端代码，需要注意：

复制代码

pnpm ui:build

官方开发文档明确说明，pnpm gateway:watch 不会重建 dist/control-ui；如果修改了 ui/，需要重新执行 pnpm ui:build，或者在开发 Control UI 时使用 pnpm ui:dev。(OpenClaw)

所以可以总结为：

复制代码

修改 Gateway 后端源码：
主要看 pnpm gateway:watch。

修改 Control UI 前端源码：
需要 pnpm ui:build 或 pnpm ui:dev。

这一点后续分析 ui 目录时会再次用到。

11. 验证 Gateway 是否运行

Gateway 启动后，可以用：

复制代码

openclaw health

官方开发文档把 openclaw health 作为验证方式之一，用于确认当前 Gateway 状态。(OpenClaw)

也可以通过浏览器访问：

复制代码

http://127.0.0.1:18789/

官方文档中提到，Control UI 的本地默认地址就是这个端口。(GitHub)

如果页面能打开，说明：

复制代码

Gateway 已经启动；
Control UI 可以访问；
CLI 和浏览器可以连接到本地 Gateway。

12. 发送一条测试消息

官方 README 的 Quick start 中给了两个常用命令。

一个是通过消息渠道发送消息：

复制代码

openclaw message send --target +1234567890 --message "Hello from OpenClaw"

另一个是直接让 agent 处理一条消息：

复制代码

openclaw agent --message "Ship checklist" --thinking high

这些命令用于验证 OpenClaw 能不能从 CLI 侧触发消息或 Agent 调用。(GitHub)

源码学习时可以先关注：

复制代码

openclaw agent --message "Hello OpenClaw"

这条命令的意义是：

复制代码

不依赖 Telegram / Slack / 微信等外部渠道，
直接通过 CLI 触发 Agent，
更适合源码调试。

后续分析 CLI 入口时，就可以沿着这条命令追踪：

复制代码

openclaw agent --message
    ↓
openclaw.mjs
    ↓
CLI 命令解析
    ↓
Gateway / Agent 调用
    ↓
模型返回结果

13. OpenClaw 的关键本地目录

运行 OpenClaw 后，要特别注意几个本地目录。

官方开发文档列出了常见状态位置：

复制代码

~/.openclaw/openclaw.json
~/.openclaw/workspace
~/.openclaw/credentials/
~/.openclaw/agents/<agentId>/sessions/
/tmp/openclaw/

其中，配置位于 ~/.openclaw/openclaw.json，工作区位于 ~/.openclaw/workspace；channel/provider 状态位于 ~/.openclaw/credentials/；sessions 位于 ~/.openclaw/agents/<agentId>/sessions/；日志位于 /tmp/openclaw/。(OpenClaw)

可以这样理解：

复制代码

源码仓库：
OpenClaw 程序本身。

~/.openclaw/openclaw.json：
用户配置文件。

~/.openclaw/workspace：
用户工作区，放 skills、prompts、memories 等。

~/.openclaw/credentials：
渠道和认证状态。

~/.openclaw/agents/<agentId>/sessions：
Agent 会话记录。

/tmp/openclaw：
运行日志。

这些目录后续非常重要。

因为你调试 OpenClaw 时，经常要判断问题来自哪里：

复制代码

是源码没生效？
是配置没改对？
是 workspace 内容没加载？
是 channel 认证状态异常？
是 session 历史影响了回答？
还是 Gateway 日志里有错误？

14. 为什么配置和工作区不放在源码仓库里？

官方文档明确建议，把个人配置和工作区保留在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace，不要把个人 prompts/config 放进 OpenClaw 源码仓库。这样更新源码时，不会破坏个人配置。(OpenClaw)

这个设计很合理。

因为源码仓库会经常变化：

复制代码

git pull
pnpm install
pnpm build

如果把个人 prompt、skills、配置都直接放在源码目录里，更新时很容易冲突。

OpenClaw 的做法是把两者分开：

复制代码

代码：
随项目更新。

个人工作区：
随用户长期保留。

这也是 local-first 个人助手系统比较重要的工程设计。

15. 常见问题一：端口不一致

官方开发文档把"Wrong port"列为常见问题，并说明 Gateway WebSocket 默认是：

复制代码

ws://127.0.0.1:18789

需要保持 app 和 CLI 使用同一端口。(OpenClaw)

如果你发现：

复制代码

CLI 可以启动 Gateway；
但是浏览器或 app 连不上；
或者 app 显示找不到 Gateway；

第一步就应该检查端口是否一致。

例如你手动启动了：

复制代码

node openclaw.mjs gateway --port 18790 --verbose

但浏览器或 app 仍然访问：

复制代码

127.0.0.1:18789

就会连接失败。

16. 常见问题二：改了 UI 但页面没变化

如果你修改了 ui/ 目录，但刷新页面没有变化，可能是因为只运行了：

复制代码

pnpm gateway:watch

官方文档说明，gateway:watch 不会重建 dist/control-ui。修改 UI 后，需要重新执行：

复制代码

pnpm ui:build

或者使用：

复制代码

pnpm ui:dev

这说明 OpenClaw 的 Gateway 和 Control UI 虽然有关联，但构建链路并不完全一样。(OpenClaw)

可以这样记：

复制代码

后端 Gateway 改动：
看 gateway:watch。

前端 UI 改动：
看 ui:build / ui:dev。

17. 常见问题三：把个人配置写进源码仓库

这是源码学习时容易犯的错误。

例如，有些人会把自己的模型配置、渠道 token、prompt、skill 都直接写进仓库目录。

这样做有几个问题：

复制代码

1. git pull 时容易冲突。
2. 可能误提交隐私配置。
3. 不利于区分源码问题和个人配置问题。
4. 不符合 OpenClaw 的工作区设计。

更合理的方式是：

复制代码

源码仓库只用于学习和修改程序代码；
个人配置放 ~/.openclaw/openclaw.json；
个人 skills 和 prompts 放 ~/.openclaw/workspace。

官方开发文档也明确建议保持 ~/.openclaw/workspace 和 ~/.openclaw/ 作为"your stuff"。(OpenClaw)

18. 常见问题四：不看日志

OpenClaw 是多模块系统，问题可能来自：

复制代码

CLI
Gateway
模型配置
channel 认证
session 历史
workspace
skills
tools
Control UI

所以运行时一定要看日志。

官方开发文档中提到，日志位置通常在：

复制代码

/tmp/openclaw/

(OpenClaw)

如果后续源码调试发现功能异常，建议先看三处：

复制代码

1. 当前终端输出
2. /tmp/openclaw/ 日志
3. ~/.openclaw/openclaw.json 配置

这比盲目改代码更有效。

19. 本期建议的最小运行流程

如果只是为了源码解析，建议先按这个最小流程来：

复制代码

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm openclaw setup
pnpm gateway:watch

然后开另一个终端验证：

复制代码

openclaw health

再尝试：

复制代码

openclaw agent --message "Hello OpenClaw"

如果浏览器 Control UI 可用，也可以访问：

复制代码

http://127.0.0.1:18789/

这个流程跑通后，至少说明你已经具备后续源码阅读所需的环境基础。

20. 从运行流程反推源码阅读重点

一旦项目能跑起来，就可以反推后续源码阅读顺序。

这期运行过的命令，对应后续源码模块：

复制代码

pnpm openclaw setup
    ↓
配置初始化、workspace 初始化、默认文件生成

pnpm gateway:watch
    ↓
Gateway 启动、watch 模式、服务监听、热重载

openclaw health
    ↓
CLI 与 Gateway 通信、健康检查接口

openclaw agent --message
    ↓
CLI 命令解析、Agent 调用链路、模型请求流程

http://127.0.0.1:18789/
    ↓
Control UI、Gateway Web 服务、前后端交互

所以运行环境不是独立的一期，而是后续所有源码解析的基础。

21. 我的理解

我认为 OpenClaw 源码学习的第一步不是"找到最核心的类"，而是先跑通一条最小链路。

因为 OpenClaw 的核心不是某一个函数，而是一组协作关系：

复制代码

CLI 负责入口；
Gateway 负责控制；
Config 和 Workspace 负责用户状态；
Agent 负责执行智能任务；
Control UI 负责可视化；
Logs 负责调试；
Sessions 负责上下文沉淀。

只有先把项目跑起来，后面分析 CLI、Gateway、Session、Tools、Skills、Channel 时才有实际参照。

22. 本期重点理解

这一期最重要的是理解 OpenClaw 的源码运行方式。

可以总结为五点：

复制代码

第一，普通安装适合使用 OpenClaw，源码运行适合学习和调试 OpenClaw。

第二，源码开发推荐使用 Node 24 和 pnpm。

第三，pnpm openclaw setup 是一次性初始化配置和 workspace 的步骤。

第四，pnpm gateway:watch 用于以 watch 模式运行 Gateway，并在相关源码或配置变化时重新加载。

第五，个人配置和工作区应保存在 ~/.openclaw，而不是直接写进源码仓库。

一句话概括：

复制代码

OpenClaw 的源码运行重点，是用 pnpm 在本地启动 Gateway，同时把源码、配置、工作区、日志和会话文件的位置区分清楚。

23. 本期小结

本期主要分析了 OpenClaw 的源码运行与开发环境。OpenClaw 推荐使用 Node 24，源码构建主要依赖 pnpm。源码运行的基本流程是：克隆仓库，执行 pnpm install 安装依赖，执行 pnpm openclaw setup 初始化本地配置和 workspace，然后通过 pnpm gateway:watch 以 watch 模式启动 Gateway。运行后，可以通过 openclaw health 检查 Gateway 状态，也可以访问 http://127.0.0.1:18789/ 打开本地 Control UI。需要特别注意的是，个人配置、workspace、credentials、sessions 和 logs 并不都在源码仓库内，而是分别位于 ~/.openclaw/ 和 /tmp/openclaw/ 等目录。

这一期可以用一句话总结：

复制代码

想读懂 OpenClaw 源码，先要把 Gateway 跑起来，并搞清楚"源码仓库负责程序代码，~/.openclaw 负责个人配置和工作区"这个基本边界。

下一期可以继续分析：

OpenClaw 源码解析（三）：仓库目录结构解析

下一期重点看 apps、config、deploy、docs、extensions、packages、security、skills、src、test、ui 等目录分别承担什么职责，并建立后续源码阅读的目录地图。