1. Windows原生安装OpenClaw中国版保姆级教程
最近在折腾本地AI助手时,发现OpenClaw中国社区版真是个宝藏工具。它原生支持DeepSeek、飞书等国内常用通道,最关键的是完全不需要折腾Linux环境,直接在Windows上就能跑起来。作为一个踩过无数坑的老手,我把整个安装过程遇到的报错和解决方案都整理出来了,保证新手也能一次成功。
1.1 为什么选择原生Windows安装?
OpenClaw官方提供了两种安装方式:WSL2和原生Windows。WSL2虽然稳定,但需要配置Linux子系统,对新手不太友好。而原生Windows方案上手快,适合想快速体验AI助手的普通用户。不过要注意的是,原生安装对终端环境比较挑剔,这也是很多人卡住的地方。
提示:如果你只是想快速体验OpenClaw的功能,建议直接选择原生Windows安装。等熟悉后再考虑迁移到WSL2环境。
2. 安装前的准备工作
2.1 必备工具清单
在开始安装OpenClaw之前,我们需要准备好三个基础工具。这些都是OpenClaw运行所必需的依赖项:
- Node.js:这是OpenClaw的运行环境,建议选择LTS(长期支持)版本,目前推荐22.x系列。LTS版本稳定性更好,适合生产环境使用。
- Git:用于拉取源码和执行Shell脚本。Windows默认没有bash环境,全靠Git提供的终端工具。
- pnpm:这是一个比npm更快的包管理工具,也是OpenClaw官方指定的依赖管理工具。
2.2 Node.js安装详解
- 访问Node.js中文官网(https://nodejs.org/zh-cn/download/)
- 下载Windows平台的.msi安装包,注意选择LTS版本而非Current版本
- 双击安装包,一路点击"下一步"即可,不需要修改任何默认配置
- 安装完成后验证:
- 打开PowerShell
- 输入
node --version查看Node.js版本 - 输入
npm --version查看npm版本
注意:安装Node.js时,建议勾选"自动安装必要的工具"选项,这会帮你安装一些编译原生模块所需的工具链。
2.3 Git安装注意事项
- 从Git官网下载Windows安装包
- 安装时保持所有默认选项
- 安装完成后,在任意文件夹右键会出现"Git Bash Here"选项
- 验证安装:
- 打开Git Bash
- 输入
git --version查看版本
这里有个关键点:Git安装路径最好记住,后面配置环境变量时会用到。默认路径通常是C:\Program Files\Git。
2.4 pnpm安装与镜像配置
- 在任意空文件夹右键选择"Git Bash Here"
- 执行安装命令:
npm install -g pnpm - 配置国内镜像加速下载:
bash复制pnpm config set registry https://registry.npmmirror.com/ - 验证安装:
pnpm --version
国内用户一定要配置镜像源,否则依赖下载可能会非常慢甚至失败。除了官方镜像,也可以考虑淘宝镜像等国内源。
3. OpenClaw安装全流程
3.1 获取源码
- 找一个合适的目录(建议路径不要太长且不要包含中文)
- 右键选择"Git Bash Here"
- 执行克隆命令:
bash复制git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git - 进入项目目录:
bash复制cd openclaw-cn
3.2 安装项目依赖
在项目目录下执行:
bash复制pnpm install
这个过程可能会花费一些时间,具体取决于你的网络速度。如果遇到卡住的情况,可以尝试:
- 检查镜像源是否配置正确
- 临时关闭防火墙和杀毒软件
- 清理pnpm缓存后重试:
pnpm store prune
3.3 构建项目
构建分为两个步骤:
-
先构建UI界面:
bash复制
pnpm ui:build这一步一般比较顺利,很少出问题。
-
整体项目构建:
bash复制
pnpm build这里是最容易出问题的地方,特别是关于bash的报错。
3.4 启动安装向导
官方特别强调:必须使用PowerShell来启动向导,Git Bash会导致交互式菜单的上下键失灵。
- 以管理员身份打开PowerShell
- 进入项目目录(替换成你的实际路径):
powershell复制cd D:\OpenClaw - 启动向导:
powershell复制pnpm openclaw onboard --install-daemon
3.5 向导配置步骤
- 安全提示输入
yes确认 - 选择"QuickStart"快速开始
- 选择AI模型(如DeepSeek),输入你的API Key
- 沟通通道先选"Skip for now"(后续再配置飞书/微信)
- 最后选择"Open the Web UI",会自动打开浏览器界面
4. 常见问题解决方案
4.1 bash命令不存在报错
报错现象:
执行pnpm build时出现:
code复制'bash' 不是内部或外部命令,也不是可运行的程序或批处理文件
原因分析:
Windows默认没有bash工具,而OpenClaw构建过程需要执行.sh脚本。虽然安装了Git(自带bash),但Git的bin目录没有加入系统PATH环境变量,导致系统找不到bash程序。
解决方案:
- 找到Git安装路径(默认是
C:\Program Files\Git) - 添加环境变量:
- Win+R输入
sysdm.cpl打开系统属性 - 高级 → 环境变量
- 系统变量中找到Path,编辑 → 新建
- 添加Git的bin目录路径(如
C:\Program Files\Git\bin)
- Win+R输入
- 重启所有终端窗口
- 验证:
powershell复制bash --version - 重新执行
pnpm build
4.2 其他常见问题
-
权限不足:
- 症状:安装过程中出现各种莫名其妙的失败
- 解决:全程使用管理员身份的PowerShell
-
端口冲突:
- 症状:无法访问18789端口
- 解决:
powershell复制找到占用进程并结束netstat -ano | findstr 18789
-
杀毒软件拦截:
- 症状:安装过程突然中断
- 解决:暂时关闭杀毒软件和防火墙
-
依赖安装失败:
- 症状:
pnpm install卡住或报错 - 解决:
- 确认镜像源配置正确
- 清理缓存:
pnpm store prune - 删除node_modules后重试
- 症状:
5. 安装成功验证
完成所有步骤后,打开浏览器访问:
code复制http://127.0.0.1:18789/chat
如果能看到OpenClaw的Web界面,并能正常与AI对话,说明安装成功。
6. 进阶配置指南
6.1 配置AI模型
- 在Web UI中进入设置页面
- 选择"AI模型"选项卡
- 添加你的DeepSeek或其他支持的AI模型API Key
- 保存设置
6.2 飞书机器人集成(可选)
- 在飞书开放平台创建企业自建应用
- 启用机器人权限
- 获取App ID和App Secret
- 在OpenClaw后台填写飞书配置
- 配置事件监听URL
- 发布应用
6.3 开机自启动配置
- 打开PowerShell(管理员)
- 进入项目目录
- 执行:
powershell复制pnpm openclaw service install pnpm openclaw service start
7. 使用技巧与优化建议
-
性能优化:
- 如果感觉响应慢,可以尝试关闭其他占用资源的程序
- 在设置中调整AI模型的temperature参数(值越小响应越保守)
-
快捷键:
- Ctrl+Enter:发送消息
- Ctrl+K:快速切换对话
-
多会话管理:
- 可以创建多个独立的对话会话
- 每个会话会保持独立的上下文记忆
-
数据备份:
- 定期备份
~/.openclaw目录 - 重装系统前记得导出重要对话记录
- 定期备份
我在实际使用中发现,OpenClaw对硬件要求并不高,但在处理复杂任务时,给AI模型更详细的上下文描述会显著提升回答质量。另外,定期清理无用的对话会话也能提升整体性能。