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 openclawlatest 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:buildOpenClaw 还有浏览器控制界面。官方文档中提到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/workspacechannel/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等目录分别承担什么职责并建立后续源码阅读的目录地图。
OpenClaw 源码解析（二）：源码运行与开发环境
发布时间：2026/5/24 3:27:00
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 openclawlatest 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:buildOpenClaw 还有浏览器控制界面。官方文档中提到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/workspacechannel/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等目录分别承担什么职责并建立后续源码阅读的目录地图。
相关文章
基尔代尔 才是天才吗
是的，如果“天才”指的是那种从无到有、定义整个行业基本框架的开创者，那么加里基尔代尔（Gary Kildall）无疑是真正的天才。如果说蒂姆帕特森是一位顶级的“实现者”，那基尔代尔就是站在更高维度上的“奠基人”。他与帕…
软考软件设计师每日备考资料 2026年5月16日（周六） | 距考试仅剩7天（5月23-26日）**
📚 软考软件设计师每日备考资料📅 2026年5月16日（周六） | 距考试仅剩7天（5月23-26日） 🎯 今日主题：考前7天全真模拟卷 答题节奏训练 新考纲AI终极速记 考前一周冲刺计划一、&…
词级语言识别实战：破解卡纳达语-英语混合文本的NLP难题
1. 项目背景与核心挑战在社交媒体和即时通讯工具无处不在的今天，我们每天产生的文本数据正以前所未有的速度和多样性增长。尤其是在印度这样的多语言国家，一个用户在同一条评论或消息中混合使用卡纳达语（Kannada）和英语࿰…
用格拉姆矩阵特征值调整替代SVD，高效求解带正交约束的优化问题
1. 项目概述与核心问题在机器学习和数值优化的世界里，我们经常遇到一个经典难题：如何在一个带约束的复杂空间里，找到那个“最好”的解。这就像在一个布满规则的迷宫里寻找宝藏，你不能横冲直撞，必须遵守墙壁（…
8051单片机除法运算问题解析与优化
1. 问题现象与背景分析在8051单片机开发中，使用Keil C51编译器进行除法运算时，可能会遇到一个看似"编译器bug"的问题。具体表现为：当对16位有符号整数进行256的除法运算时，结果与预期不符。例如以下代码：int…
MACCMS远程命令执行漏洞CVE-2017-17733深度解析
1. 这个漏洞不是“能打就行”，而是理解CMS底层逻辑的试金石MACCMS远程命令执行漏洞（CVE-2017-17733）在安全圈里常被简化为一句“v8.0/v8.1版本存在RCE”，但我在实际渗透测试和代码审计中反复验证过：真正卡住90%复现者的…
别再傻傻重装系统了！Windows 10/11家庭版一键升级专业版保姆级教程（附密钥获取思路）
Windows家庭版升级专业版全指南：免重装保留数据的完整方案每次看到身边的朋友为了升级Windows版本而准备重装系统时，我都会忍不住阻止——这就像为了换件外套而要把整栋房子拆掉重建一样荒谬。事实上，微软早已为版本升级设计了极其简便的通道…
告别VMware网络冲突！CentOS Stream 9虚拟机静态IP配置保姆级避坑指南
CentOS Stream 9虚拟机静态IP配置终极排错手册当你在VMware中为CentOS Stream 9配置静态IP时，是否遇到过这些诡异现象：ip addr显示两个IP地址、网络时断时续、ping外网时通时不通？这背后隐藏着DHCP与静态IP的"权力斗争"。本文将带你…
随机计算与ViT硬件加速：混合架构如何突破AI芯片能效墙
1. 项目概述：当ViT遇见随机计算最近在硬件加速领域，一个名为“ASCEND”的项目引起了我的注意。这本质上是一个专门为Vision Transformer（ViT）模型设计的硬件加速器，但其核心创新点在于采用了“随机计算”这种非常规的电…
施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录
更多请点击： https://codechina.net 第一章：施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录 在华北某大型地铁盾构施工现场，一套轻量化AI Agent系统于2024年Q2完成全栈部署ÿ…
附录 B：术语表
本术语表面向“从 MM 到 HMM”专栏阅读过程中的快速查阅。它不是内核 API 手册，而是把文章中反复出现的概念放到同一张地图上：先给出直观含义，再说明它在 Linux MM/HMM 语境里的作用。建议阅读方式： 初读专栏时，把它当…
Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表·行业首曝）
更多请点击： https://kaifayun.com 第一章：Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表行业首曝） Midjourney 的渐变美学并非传统插值实现，而是由其隐式神经渲染器（Implicit Neu…
施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录
更多请点击： https://codechina.net 第一章：施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录 在华北某大型地铁盾构施工现场，一套轻量化AI Agent系统于2024年Q2完成全栈部署ÿ…
附录 B：术语表
本术语表面向“从 MM 到 HMM”专栏阅读过程中的快速查阅。它不是内核 API 手册，而是把文章中反复出现的概念放到同一张地图上：先给出直观含义，再说明它在 Linux MM/HMM 语境里的作用。建议阅读方式： 初读专栏时，把它当…
Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表·行业首曝）
更多请点击： https://kaifayun.com 第一章：Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表行业首曝） Midjourney 的渐变美学并非传统插值实现，而是由其隐式神经渲染器（Implicit Neu…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…