1. OpenClaw(小龙虾)项目概述
OpenClaw(昵称"小龙虾")是一款基于Node.js开发的AI助手工具,它提供了终端(TUI)和网页(Web UI)两种交互界面。作为一个本地化部署的AI解决方案,它特别适合想要在Windows环境下快速搭建AI助手的国内用户。我在实际部署过程中发现,官方文档对新手不够友好,特别是在国内网络环境下会遇到各种依赖安装问题。经过多次尝试和踩坑,我整理出了这份最适合国内新手的部署指南。
这个项目的核心价值在于:
- 完全本地运行,无需依赖外部API密钥
- 支持Qwen等开源大语言模型
- 提供双界面操作方式(命令行+网页)
- 针对国内网络环境优化了安装流程
整个部署过程大约需要30分钟,只要跟着步骤操作,即使没有Node.js基础也能顺利完成。下面我会从环境准备开始,详细说明每个环节的操作要点和避坑技巧。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与工具安装
2.1 Node.js安装与配置
Node.js是OpenClaw运行的基础环境,相当于整个系统的"发动机"。它让JavaScript代码能在你的电脑上直接运行,而不是只能在浏览器中执行。
2.1.1 下载与安装
- 访问Node.js官网下载页面:Node.js官方下载
- 选择"Windows安装程序(.msi)"的LTS版本(长期支持版更稳定)
- 下载完成后双击安装包,保持默认设置,连续点击"下一步"完成安装
注意:安装路径不要包含中文或特殊字符,使用默认的"C:\Program Files\nodejs"最为稳妥。我在测试时曾因路径包含空格导致后续模块安装失败。
2.1.2 验证安装
安装完成后需要确认Node.js和npm(Node.js的包管理器)能正常工作:
- 按下Win+R,输入"cmd"打开命令提示符
- 依次执行以下命令检查版本:
bash复制node -v
npm -v
正常情况会显示类似这样的版本号(具体数字可能不同):
code复制v18.16.0
9.5.1
如果提示"不是内部或外部命令",说明环境变量未正确设置。这时需要:
- 右键"此电脑"→"属性"→"高级系统设置"→"环境变量"
- 在"系统变量"中找到Path,确认包含Node.js的安装路径(如C:\Program Files\nodejs\)
2.2 pnpm安装与加速配置
pnpm是一个更高效的Node.js包管理工具,相比npm有三大优势:
- 磁盘空间占用更少(所有项目共享依赖)
- 安装速度更快
- 版本控制更严格,避免"在我机器上能运行"的问题
2.2.1 安装pnpm
在已安装Node.js的基础上,执行以下命令全局安装pnpm:
bash复制npm install -g pnpm
安装完成后验证版本:
bash复制pnpm -v
2.2.2 配置国内镜像源
为了提升国内下载速度,需要将pnpm的仓库地址改为国内镜像:
bash复制pnpm config set registry https://registry.npmmirror.com
这个命令会将包下载源切换为淘宝npm镜像,速度能提升10倍以上。我在测试时不配置镜像的情况下,某些大包的下载经常超时失败。
3. OpenClaw核心安装
3.1 全局安装OpenClaw
确保pnpm配置完成后,执行以下命令安装最新版OpenClaw:
bash复制pnpm add -g openclaw
这个命令会:
- 从配置的镜像源下载OpenClaw及其所有依赖
- 将openclaw命令添加到系统PATH
- 在全局node_modules中安装所需组件
安装过程大约需要5-15分钟,具体时间取决于网络状况。如果遇到长时间卡顿,可以尝试:
- 检查网络连接
- 确认镜像源配置正确
- 清理pnpm缓存后重试:
bash复制pnpm store prune
3.2 初始化配置向导
安装完成后,首次运行会进入交互式配置向导:
bash复制openclaw init
3.2.1 模型选择
向导会提示选择AI模型,推荐选择"Qwen"系列,原因有三:
- 完全开源可商用
- 支持中文效果优秀
- 无需API密钥即可使用
根据你的硬件配置选择适当大小的模型:
- 低配电脑:Qwen-1.8B
- 中端配置:Qwen-7B
- 高性能设备:Qwen-14B
实测建议:我的RTX 3060笔记本运行Qwen-7B勉强可用,更推荐台式机+Qwen-14B的组合。如果只有集成显卡,建议选择1.8B版本。
3.2.2 网关配置
接下来需要配置服务端口(默认3000)和访问权限。关键注意事项:
- 如果只想本地访问,保持默认的127.0.0.1即可
- 需要局域网其他设备访问时,改为0.0.0.0
- 首次运行Windows防火墙会弹出提示,务必选择"允许访问"
4. 启动与使用
4.1 终端界面(TUI)启动
执行以下命令启动终端交互界面:
bash复制openclaw tui
这个模式下支持:
- 直接输入问题与AI对话
- 使用快捷键导航(Ctrl+C退出)
- 查看对话历史记录
4.2 网页界面(Web UI)启动
执行以下命令启动网页服务:
bash复制openclaw web
启动成功后,浏览器访问 http://localhost:3000 即可看到操作界面。Web UI提供更丰富的功能:
- 多会话管理
- 对话导出/导入
- 主题切换
- 模型参数调整
性能提示:首次加载模型可能需要较长时间(尤其是大模型),请耐心等待直到终端显示"Ready"状态。我的Qwen-7B大约需要2分钟加载。
5. 常见问题解决
5.1 安装失败排查
问题现象:pnpm install过程中报错"ETIMEDOUT"或"ECONNRESET"
解决方案:
- 确认镜像源配置正确
- 尝试使用npm替代pnpm临时安装:
bash复制npm install -g openclaw --registry=https://registry.npmmirror.com
- 如仍失败,可能是特定包被墙,需要手动下载:
- 根据错误信息找到包名
- 在npmmirror.com搜索该包
- 下载对应版本的.tgz文件
- 通过
pnpm add ./包名.tgz本地安装
5.2 模型加载异常
问题现象:启动时卡在"Loading model..."或报错"CUDA out of memory"
解决方案:
- 检查显卡驱动是否为最新版
- 降低模型尺寸(换用更小的Qwen版本)
- 添加--cpu-only参数强制使用CPU模式:
bash复制openclaw web --cpu-only
- 调整Web UI中的"max_memory"参数,限制显存使用量
5.3 端口冲突处理
问题现象:启动时报错"Address already in use"
解决方案:
- 找出占用端口的进程:
bash复制netstat -ano | findstr 3000
- 根据PID结束对应进程:
bash复制taskkill /PID 1234 /F
- 或者修改OpenClaw的监听端口:
bash复制openclaw web --port 3001
6. 进阶配置与优化
6.1 自定义模型路径
默认情况下模型会下载到C盘,可以通过环境变量修改存储位置:
- 创建模型存放目录,如D:\ai_models
- 设置环境变量:
bash复制set OPENCLAW_MODEL_DIR=D:\ai_models
- 重新运行openclaw init选择模型
6.2 开机自启动服务
如需将OpenClaw作为后台服务运行:
- 创建启动脚本start_claw.bat:
bat复制@echo off
openclaw web --port 3000
- 将脚本放入启动文件夹(Win+R输入shell:startup)
- 如需隐藏命令行窗口,可将脚本改为:
bat复制@echo off
start /B openclaw web --port 3000
6.3 性能调优建议
根据我的实测经验,以下配置能显著提升响应速度:
-
在web界面调整这些参数:
- temperature=0.7(降低随机性)
- top_p=0.9(平衡多样性与相关性)
- max_length=512(控制生成长度)
-
硬件加速配置:
- 确保启用CUDA(NVIDIA显卡)
- 安装对应版本的cudnn库
- 在启动命令添加--device cuda:0
-
对于多轮对话,适当减小"context_length"可以降低内存占用
