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等目录分别承担什么职责，并建立后续源码阅读的目录地图。