2.1 环境准备

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~140,000 tokens，输出 ~10,000 tokens（本章合计）

---

在深入阅读 OpenClaw 源码之前，你需要搭建一个完整的开发环境。本节将指导你完成从零到可运行的全部准备工作。

2.1.1 Node.js 22+ 与 pnpm 安装

OpenClaw 对运行时有明确的版本要求。package.json 中声明：

{
  "engines": {
    "node": ">=22.12.0"
  },
  "packageManager": "[email protected]"
}

安装 Node.js

推荐使用版本管理工具（如 nvm、fnm 或 volta）安装 Node.js，这样可以方便地在不同项目之间切换版本。

# 使用 nvm 安装 Node.js 22
nvm install 22
nvm use 22

# 验证版本
node --version   # 应输出 v22.x.x

如果你的系统已经安装了 Node.js 但版本低于 22，OpenClaw 会在启动时报错。这个检查在 src/infra/runtime-guard.ts 中实现——assertSupportedRuntime() 函数会比对当前 Node.js 版本与 package.json 中的 engines.node 要求。

安装 pnpm

OpenClaw 使用 pnpm 10.x 作为包管理器。Node.js 16+ 内置了 Corepack，可以直接启用 pnpm：

# 启用 Corepack（Node.js 内置的包管理器管理工具）
corepack enable

# 验证 pnpm 版本
pnpm --version   # 应输出 10.x.x

衍生解释：Corepack 是 Node.js 内置的一个实验性工具，用于管理包管理器（npm、yarn、pnpm）的版本。它读取项目 package.json 中的 packageManager 字段，自动下载并使用对应版本的包管理器。这确保了团队中每个人使用完全相同版本的 pnpm。

如果 Corepack 不可用，也可以手动安装：

npm install -g pnpm@10

2.1.2 从源码克隆与构建

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖（pnpm 会自动处理 Monorepo 中所有包的依赖）
pnpm install

pnpm install 完成后，你会注意到根目录下出现了 node_modules/ 目录以及各子包的 node_modules/。由于 pnpm 的硬链接机制，实际的包文件存储在全局的 .pnpm-store 中，项目目录只包含符号链接，因此磁盘占用比 npm 小得多。

接下来构建项目：

# 构建核心代码（tsdown 编译 TypeScript → JavaScript）
pnpm build

构建命令 pnpm build 实际上执行了一系列步骤，定义在 package.json 的 scripts.build 中：

{
  "scripts": {
    "build": "pnpm canvas:a2ui:bundle && tsdown && pnpm build:plugin-sdk:dts && node --import tsx scripts/write-plugin-sdk-entry-dts.ts && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts && node --import tsx scripts/write-cli-compat.ts"
  }
}

拆解这个构建流水线：

1. pnpm canvas:a2ui:bundle：打包 Canvas A2UI 前端代码

2. tsdown：核心 TypeScript 编译（使用 tsdown.config.ts 配置）

3. build:plugin-sdk:dts：生成插件 SDK 的类型声明文件

4. 后续脚本：复制元数据、写入构建信息、生成 CLI 兼容层

构建产物输出到 dist/ 目录：

dist/
├── index.js               # 主入口（库模式）
├── entry.js               # CLI 入口
├── extensionAPI.js         # 扩展 API
├── plugin-sdk/             # 插件 SDK
│   ├── index.js
│   └── index.d.ts         # 类型声明
└── ...

2.1.3 UI 构建

Web 控制台 UI 是一个独立的包，需要单独构建：

# 构建 Web UI（首次运行会自动安装 UI 依赖）
pnpm ui:build

这个命令通过 scripts/ui.js 脚本执行，它会：

1. 检测 UI 依赖是否已安装，未安装则自动运行 pnpm install

2. 使用 Vite 构建 Lit Web Components

3. 输出静态资源到 UI 的 dist/ 目录

构建后的 UI 文件会被 Gateway 在启动时加载并通过 HTTP 提供服务（src/gateway/control-ui.ts），用户通过浏览器访问 http://127.0.0.1:18789 即可看到控制面板。

完整的一键构建命令：

# 安装依赖 → 构建 UI → 构建核心代码
pnpm install && pnpm ui:build && pnpm build

构建成功后，你可以通过以下方式验证：

# 检查 dist/ 是否生成
ls dist/index.js

# 尝试运行 CLI 帮助
node dist/entry.js --help

如果看到 openclaw 的命令行帮助信息，说明构建成功。

关于开发模式

在日常开发中，你不需要每次修改都运行完整的 pnpm build。OpenClaw 提供了两种更高效的开发方式：

1. 直接运行 TypeScript（通过 tsx）：

# pnpm openclaw 内部使用 tsx 直接执行 TypeScript
pnpm openclaw gateway --port 18789

这背后调用的是 scripts/run-node.mjs，它会检查 dist/ 是否过期，如果过期则先自动重新构建，然后运行。

1. 文件监听模式（下一节详述）：

pnpm gateway:watch

我们将在 2.4 节详细讨论这些开发循环工具。