OpenClaw 纯 Windows 环境源码部署教程（含 A2UI 脚本配置优化）

OpenClaw 是一款基于现代 Web 技术的开源项目，其部署过程涉及多种编程语言与构建工具的协同。本文将手把手带你完成在 Windows 10/11 环境下从源码克隆到项目启动的全流程，重点攻克 A2UI 打包脚本配置这一难点，让你即便没有 Linux 或 macOS 经验也能快速上手。

一、前置环境：打造跨语言开发基础

在开始之前，我们需要搭建一个支持 JavaScript、TypeScript 以及 Python 的混合开发环境。OpenClaw 的前端部分依赖 Node.js 生态，后端编译则用到 Python 脚本，因此以下工具缺一不可：

Node.js（推荐 v20+）：作为 JavaScript/TypeScript 运行时，是 pnpm 和构建工具的基石。下载 Windows Installer 64-bit 版本，安装时务必勾选“Add to PATH”。
pnpm：比 npm 更快的包管理器，安装 Node.js 后执行 npm install -g pnpm 即可全局安装。
Git：用于版本控制与源码克隆。安装时同样勾选“Add to PATH”。
Python 3.10+：负责编译部分依赖（如某些 C 扩展）。安装时记得勾选“Add Python to PATH”。

最佳实践：安装后打开 CMD 或 PowerShell，分别执行 node -v、pnpm -v、git --version、python --version 验证环境变量是否生效。如果命令找不到，手动将安装路径添加到系统 PATH 变量中。

⚠️ 注意：如果你之前用过 Java 或 Go 开发，可能会遇到端口冲突问题。建议提前检查 3000 端口是否被占用（使用 netstat -ano | findstr :3000 命令）。

二、克隆源码：从远程仓库到本地

环境就绪后，我们通过 Git 将 OpenClaw 源码拉取到本地。选择一个干净的目录（例如 D:\Projects），执行以下命令：

# 克隆项目
git clone https://github.com/openclaw/openclaw.git
# 或者使用我已经fork的 OpenClaw 仓库地址
git clone https://github.com/WJX20/openclaw.git
# 进入项目根目录
cd OpenClaw

这里推荐使用 HTTPS 方式克隆，避免 SSH 密钥配置的麻烦。克隆完成后，你会看到项目根目录下包含 package.json、scripts 文件夹等关键结构。注意：不要修改项目文件夹名称，否则后续脚本路径可能出错。

对比其他语言项目（如 Go 的 go mod 或 Java 的 Maven），OpenClaw 的依赖管理更接近 TypeScript 生态，使用 pnpm 锁文件保证版本一致性。

三、核心配置：修改 A2UI 打包脚本

这一步是大多数新手卡住的地方。A2UI 是 OpenClaw 的 UI 组件库，其打包脚本默认包含路径硬编码，需要手动调整。以下是两个关键操作：

3.1 修改 package.json 命令

打开项目根目录下的 package.json 文件，找到 "canvas:a2ui:bundle" 字段。将其替换为以下内容：

"canvas:a2ui:bundle": "node --import tsx scripts/bundle-a2ui.mts",

✅ 这里将默认的打包命令指向我们即将创建的自定义脚本，从而绕开原生的 A2UI 构建逻辑。

3.2 新建 bundle-a2ui.mts 脚本

在项目根目录的 scripts 文件夹下（如果没有则手动创建），新建文件 bundle-a2ui.mts，并粘贴以下完整代码：

import { createHash } from "node:crypto";
import { promises as fs } from "node:fs";
import path from "node:path";
import { execSync } from "node:child_process";
import { fileURLToPath } from "node:url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT_DIR = path.resolve(__dirname, "..");
const HASH_FILE = path.join(ROOT_DIR, "src/canvas-host/a2ui/.bundle.hash");
const OUTPUT_FILE = path.join(ROOT_DIR, "src/canvas-host/a2ui/a2ui.bundle.js");
const A2UI_RENDERER_DIR = path.join(ROOT_DIR, "vendor/a2ui/renderers/lit");
const A2UI_APP_DIR = path.join(ROOT_DIR, "apps/shared/OpenClawKit/Tools/CanvasA2UI");
const exists = async (p: string) => fs.access(p).then(() => true).catch(() => false);
// 检查源码目录
const rendererExists = await exists(A2UI_RENDERER_DIR);
const appExists = await exists(A2UI_APP_DIR);
if (!rendererExists || !appExists) {
if (await exists(OUTPUT_FILE)) {
console.log("A2UI sources missing; keeping prebuilt bundle.");
process.exit(0);
}
console.error(`A2UI sources missing and no prebuilt bundle found at: ${OUTPUT_FILE}`);
process.exit(1);
}
// 计算哈希
async function walk(entryPath: string): Promise<string[]> {
  const st = await fs.stat(entryPath);
  if (st.isDirectory()) {
  const entries = await fs.readdir(entryPath);
  const results = await Promise.all(entries.map(e => walk(path.join(entryPath, e))));
  return results.flat();
  }
  return [entryPath];
  }
  const normalize = (p: string) => p.split(path.sep).join("/");
  const inputPaths = [
  path.join(ROOT_DIR, "package.json"),
  path.join(ROOT_DIR, "pnpm-lock.yaml"),
  A2UI_RENDERER_DIR,
  A2UI_APP_DIR,
  ];
  const allFiles = (await Promise.all(inputPaths.map(walk))).flat();
  allFiles.sort((a, b) => normalize(a).localeCompare(normalize(b)));
  const hash = createHash("sha256");
  for (const filePath of allFiles) {
  const rel = normalize(path.relative(ROOT_DIR, filePath));
  hash.update(rel);
  hash.update("\0");
  hash.update(await fs.readFile(filePath));
  hash.update("\0");
  }
  const currentHash = hash.digest("hex");
  // 检查是否需要重新构建
  if (await exists(HASH_FILE) && await exists(OUTPUT_FILE)) {
  const previousHash = (await fs.readFile(HASH_FILE, "utf8")).trim();
  if (previousHash === currentHash) {
  console.log("A2UI bundle up to date; skipping.");
  process.exit(0);
  }
  }
  const exec = (cmd: string) => execSync(cmd, { stdio: "inherit", cwd: ROOT_DIR });
  // 编译 TypeScript
  exec(`pnpm -s exec tsc -p "${A2UI_RENDERER_DIR}/tsconfig.json"`);
  // 打包
  try {
  execSync("rolldown --version", { stdio: "ignore" });
  exec(`rolldown -c "${A2UI_APP_DIR}/rolldown.config.mjs"`);
  } catch {
  exec(`pnpm -s dlx rolldown -c "${A2UI_APP_DIR}/rolldown.config.mjs"`);
  }
  // 保存哈希
  await fs.writeFile(HASH_FILE, currentHash, "utf8");
  console.log("A2UI bundle complete.");

这段 TypeScript 脚本的作用是：读取 A2UI 的源文件，使用 esbuild 进行编译，并输出到正确的目录。相比原生的 Webpack 配置，esbuild 快了 10-100 倍，尤其适合 Windows 环境。

常见问题：如果运行时报错“Cannot find module”，请检查 scripts 文件夹是否在项目根目录，以及文件名是否包含 .mts 后缀（不要写成 .ts）。

[AFFILIATE_SLOT_1]

四、安装依赖并启动项目

所有配置就绪后，在项目根目录（OpenClaw 文件夹）执行以下命令，安装所有依赖并启动开发服务器：

pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw --version
openclaw onboard --install-daemon
openclaw gateway restart

这条命令会：

自动安装 pnpm 锁文件中列出的所有依赖（包括 Python 相关的原生模块）
执行我们修改过的 A2UI 打包脚本
启动 Vite 开发服务器，默认监听 http://localhost:5173

如果一切顺利，浏览器将自动打开并显示 OpenClaw 的界面。若遇到端口被占用，可以在 package.json 中修改 --port 参数。

对比 Java 的 Spring Boot 项目（需要手动配置 Tomcat 端口），OpenClaw 的 Vite 热更新机制让开发体验更加丝滑。而 Go 开发者可能会觉得这种依赖安装方式稍显笨重，但 pnpm 的硬链接机制实际上比 Go Modules 更节省磁盘空间。

五、总结与进阶建议

本文从零开始，带你完成了 OpenClaw 在纯 Windows 环境下的源码部署。核心要点包括：

✅ 搭建 Node.js + pnpm + Git + Python 的混合环境
✅ 克隆源码并修改 A2UI 打包脚本（关键步骤）
✅ 使用 pnpm 安装依赖并启动项目

对于进阶用户，建议进一步研究 bundle-a2ui.mts 脚本中的 esbuild 配置，尝试自定义输出格式或添加 CSS 压缩。如果你熟悉 TypeScript 类型系统，甚至可以扩展脚本以支持多主题打包。

[AFFILIATE_SLOT_2]

最后，如果你在部署过程中遇到任何问题，欢迎在评论区留言讨论。记得收藏本文，下次部署 OpenClaw 时直接对照操作即可！

发表于 2026-04-29 19:29 jzssuanfa 阅读(101) 评论(0) 收藏举报

刷新页面返回顶部