OpenClaw 源码部署教程：构建、坑点与启动全流程

系列：Windows AI 环境搭建
环境：Windows 11 · OpenClaw 2026.3.14 · Node.js v25 · pnpm v10 · Python 3.12 · PyCharm

• OpenClaw 本地部署 LM Studio 全模型接入热切换教程

• OpenClaw 及衍生版本官方链接整理（2026年3月最新）

• OpenClaw 手机直连配置全流程

• OpenClaw搭配LM Studio VS Ollama：Windows CUDA实战深度对比与完全配置指南

• 【OpenClaw 本地实战 Ep.4】终极提效：一劳永逸解决切换浏览器 Token 鉴权失败与断连问题

• 【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆

• 【OpenClaw 本地实战 Ep.2】零代码对接：使用交互式向导快速连接本地 LM Studio 用 CUDA GPU 推理

• 【OpenClaw 本地实战 Ep.1】抛弃 Ollama？转向 LM Studio！Windows 下用 NVIDIA 显卡搭建 OpenClaw 本地极速推理服务

• Windows 从源代码部署 OpenClaw

• OpenClaw安装排错笔记

• Openclaw

• openclaw/openclaw：你专属的个人AI助手。任何操作系统。任何平台。龙虾的方式。🦞

• openclaw/clawhub: Skill Directory for OpenClaw

• openclaw/技能：所有已存档 clawhub.com 技能的所有版本

• openclaw/acpx：用于有状态代理客户端协议（ACP）会话的无头CLI客户端

• OpenClaw/Lobster：Lobster 是一个 Openclaw 原生的工作流程 shell：一个类型化、本地优先的“宏引擎”，将技能/工具转化为可组合的流水线和安全自动化——并让 Openclaw 能够一步调用这些工作流。

• openclaw/nix-openclaw：为 nix 提供 OpenClaw 包。

---

---

前言

OpenClaw 官方提供 npm 全局安装方式，但如果你想跑最新代码、修改配置逻辑、或者在 IDE 里管理项目，就需要从源码构建。

本文记录 Windows 下从 git clone 到 gateway 正常跑起来的完整流程，包含所有容易踩的坑。

---

一、前置环境要求

工具	要求	说明
Node.js	v18+ 推荐 v20/v22/v25	官网下载 LTS 版即可
pnpm	v8+ 推荐 v10	npm install -g pnpm
Git	任意版本	需在 PATH 里
Python	3.10+ 推荐 3.12	配合 PyCharm 管理项目可选

验证环境：

node -v
pnpm -v
git --version

注意：OpenClaw 使用 pnpm workspace 管理 monorepo，不要用 npm 或 yarn 安装依赖，会破坏 workspace 结构。

---

二、克隆源码

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

建议克隆到空间充足的非系统盘，项目依赖安装后体积较大：

# 例如克隆到 J 盘
cd J:\PythonProjects4
git clone https://github.com/openclaw/openclaw.git
cd openclaw

---

三、用 PyCharm 管理项目（可选但推荐）

如果你已经在用 PyCharm 管理其他 AI 项目，建议把 OpenClaw 也纳入 PyCharm 管理，好处：

• Terminal 直接在项目目录下打开，不用每次 cd
• 内置 Git 管理，拉取新版本方便
• 可以配置 Python 虚拟环境，和其他项目隔离

操作步骤：

1. PyCharm → File → Open → 选择 openclaw 目录
2. 右下角配置 Python 解释器 → Add Interpreter → Virtualenv → 新建 .venv
3. Terminal 默认会自动激活 .venv

注意：OpenClaw 本身是 Node.js 项目，Python 虚拟环境只是用于 PyCharm 的项目识别和 Terminal 管理，不影响 Node.js 构建流程。激活 .venv 后正常跑 pnpm 命令即可。

---

四、三步构建（顺序不能错）

第一步：安装依赖

pnpm install

正常输出（可忽略的警告见第六节）：

Scope: all 74 workspace projects
Done in 3s using pnpm v10.23.0

第二步：构建主程序

pnpm build

这一步会依次执行：TypeScript 编译、插件 SDK 类型生成、资源文件复制等。正常输出末尾：

[copy-hook-metadata] Copied 4 hook metadata files.
[copy-export-html-templates] Copied 5 export-html assets.

第三步：构建前端 UI

# 关键：必须先进 ui/ 子目录单独安装一次依赖
cd ui
pnpm add -D vite --ignore-workspace
cd ..

# 再构建 UI
pnpm ui:build

正常输出：

vite v8.0.0 building client environment for production...
✓ 212 modules transformed.
../dist/control-ui/index.html   2.73 kB
...
✓ built in 410ms

⚠️ 坑点：为什么要单独进 ui/ 装 vite？

pnpm workspace 模式下，vite 作为 devDependency 会被 hoist（提升）到根目录的 node_modules/.pnpm/ 里，但 ui/ 子包在执行 vite build 时会去找 ui/node_modules/vite/bin/vite.js 这个本地路径，而这个路径不存在。

解决方法是在 ui/ 子目录里用 pnpm add -D vite --ignore-workspace 强制在子包本地创建一个软链接，指向根目录已有的 vite 包。只需做一次，后续重新构建不需要重复这步。

错误现象：

Error: Cannot find module 'J:\...\openclaw\ui\node_modules\vite\bin\vite.js'

---

五、PowerShell 引号转义坑

OpenClaw 提供了 config set 命令来修改配置，但在 PowerShell 下设置数组或对象类型的值时会遇到引号问题：

错误写法（PowerShell 吃掉单引号内的 JSON 结构）：

# 报错：expected array, received string
pnpm openclaw config set gateway.controlUi.allowedOrigins '["https://example.com"]'

正确写法（用转义双引号）：

pnpm openclaw config set gateway.controlUi.allowedOrigins '[\"https://example.com\"]'

# 多个值
pnpm openclaw config set gateway.controlUi.allowedOrigins '[\"https://example.com\",\"http://127.0.0.1:18789\"]'

根本原因：PowerShell 对单引号内的内容不做转义，导致 JSON 数组的双引号被剥离，传给 CLI 的是裸字符串 [https://example.com] 而不是合法 JSON。

建议：涉及数组或对象类型的配置，直接编辑 C:\Users\你的用户名\.openclaw\openclaw.json 更可靠，避免引号问题。

---

六、可忽略的警告清单

构建和启动过程中会出现几条警告，均不影响使用：

警告内容	原因	是否影响使用
[DEP0190] DeprecationWarning: Passing args to a child process with shell option true	Node.js v22+ 对 shell 参数拼接的新版警告	不影响
prepare$ command -v git ... The system cannot find the path specified.	git hooks 配置脚本用了 bash 语法（command -v），在 Windows 上不存在但脚本正常以 exit 0 退出	不影响
Ignored build scripts: @discordjs/opus	pnpm 安全机制，需手动审批 native build script 的包，OpenClaw 不依赖 Discord 语音功能	不影响
[model-pricing] pricing bootstrap failed: TimeoutError	启动时尝试从外网拉取模型定价数据超时，本地模型不需要这个数据	不影响
[bonjour] restarting advertiser (service stuck in announcing)	局域网服务发现组件偶发的状态重置，不影响 WebSocket 连接	不影响

---

七、日常启动命令

构建完成后，日常使用只需一条命令：

pnpm openclaw gateway

确认以下日志出现说明启动成功：

[gateway] listening on ws://127.0.0.1:18789
[tailscale] serve enabled: https://你的节点.ts.net/   # 如果配置了 Tailscale

在 PyCharm 里启动的方式：

1. 打开 PyCharm Terminal（底部 Terminal 标签）
2. 确认路径在项目根目录（J:\PythonProjects4\openclaw）
3. 直接输入 pnpm openclaw gateway

PyCharm Terminal 会自动激活 .venv，pnpm 命令正常可用。

访问 Control UI：

# 本机浏览器
http://127.0.0.1:18789?token=你的token

# 或用命令自动打开（自动附带 token）
pnpm openclaw dashboard

---

八、完整构建流程速查

# 1. 克隆（首次）
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖
pnpm install

# 3. 构建主程序
pnpm build

# 4. 修复 ui/ 子包 vite 链接（首次必须，后续不需要）
cd ui
pnpm add -D vite --ignore-workspace
cd ..

# 5. 构建前端 UI
pnpm ui:build

# 6. 启动 Gateway
pnpm openclaw gateway

---

九、更新到新版本

cd J:\PythonProjects4\openclaw

# 拉取最新代码
git pull

# 重新构建（ui/ 的 vite 链接已存在，不需要重做）
pnpm install
pnpm build
pnpm ui:build

# 启动
pnpm openclaw gateway

注意：大版本更新后如果 pnpm build 报错，先清理构建产物再试：

Remove-Item -Recurse -Force dist
pnpm build

---

小结

步骤	命令	备注
安装依赖	pnpm install	workspace 根目录执行
构建主程序	pnpm build	TypeScript 编译
修复 vite 链接	cd ui && pnpm add -D vite --ignore-workspace	首次必须，后续不需要
构建前端 UI	pnpm ui:build	产物输出到 dist/control-ui/
启动	pnpm openclaw gateway	日常使用这一条

源码部署的核心坑就一个：pnpm workspace 下 ui/ 子包找不到 vite。理解这个原因之后，整个构建流程就非常清晰了。