OpenClaw(曾用名Clawdbot)AI代理安装教程|Windows10/11+Ubuntu双系统适配,TypeScript开发,解决依赖缺失、启动失败等核心问题
目录
- [OpenClaw 简介](#一、OpenClaw 简介)
- 安装前核心准备(必看)
- [Windows 系统安装步骤(详细版)](#三、Windows 系统安装步骤(详细版))
- 步骤1:安装Node.js(TypeScript运行环境)
- 步骤2:安装Git(下载源码必备)
- 步骤3:下载OpenClaw源码
- 步骤4:配置依赖并编译项目
- 步骤5:运行OpenClaw并验证
- [Linux 系统安装步骤(Ubuntu 22.04 为例)](#四、Linux 系统安装步骤(Ubuntu 22.04 为例))
- 常见安装报错及解决方案
- 安装后基础配置(可选)
- 总结与扩展
一、OpenClaw 简介
1.1 什么是 OpenClaw?
OpenClaw 是一款 可部署在个人电脑上的开源AI代理工具,曾用名 Clawdbot、Moltbot,由奥地利独立程序员彼得·斯坦伯格(Peter Steinberger)开发——这位开发者曾因开发PDF处理工具PSPDFKit并成功商业化实现财务自由,OpenClaw是其后续推出的核心AI项目[3-4] [12] [14]。
OpenClaw 采用“龙虾”图标设计,核心slogan为“The AI that actually does things”(真正能做事的AI),其核心定位并非大模型本身,而是一个“AI指挥官”——接收用户指令、调用工具和组织流程,将指令理解与具体执行交由接入的外部大模型(如GPT、Kimi、智谱GLM等)完成,实现“解放双手”的自动化任务处理。
该项目核心开发语言为 TypeScript,完全开源且社区驱动,支持Windows、Linux、macOS等跨平台部署,是目前技术圈热门的个人AI辅助工具之一。
1.2 核心用途拆解(贴合安装场景,新手易懂)
- 自动化任务处理:这是OpenClaw的核心用途,接入大模型后,可自动完成本地文件检索、网络资料搜索、稿件撰写、邮件发送等任务,全流程无需人工干预;
- 个人效率提升:适合职场人、程序员、内容创作者,可替代重复劳动,比如自动整理文件、生成报告、批量处理数据,搭配不同大模型可适配多样化需求;
- 二次开发与定制:由于开源特性,开发者可基于其TypeScript源码进行二次开发,扩展自定义技能(Skill),适配个人专属的自动化场景;
- AI工具学习实践:对于想学习AI代理开发、TypeScript项目部署的新手,OpenClaw源码结构清晰,是绝佳的入门学习案例,可直观了解AI指令调度、工具调用的核心逻辑。
补充说明:OpenClaw的名字演变源于商标争议——最初命名为Clawdbot,因被Anthropic指控与旗下“Claude”商标相似,曾短暂更名为Moltbot,最终确定为OpenClaw,“Open”代表开源、社区驱动,“Claw”则保留项目初心与来路。
1.3 安装核心前提
OpenClaw 基于TypeScript开发,运行依赖Node.js环境,安装前需明确以下要求,避免后续部署失败:
- 系统要求:Windows 10/11(64位)、Linux(Ubuntu 20.04+,64位);
- 核心环境:Node.js(v16+ 版本,推荐v18,自带npm包管理工具);
- 开发工具:Git(用于下载源码)、VS Code(可选,用于查看/修改源码、调试项目);
- 其他要求:网络环境(需联网下载源码和依赖包)、预留至少300MB存储空间(含源码、依赖包、运行文件)。
二、安装前核心准备(必看)
无论Windows还是Linux系统,安装前需完成以下基础准备,避免因环境缺失或配置错误导致部署失败:
- 确认系统位数:必须是64位系统(32位系统不支持高版本Node.js,且OpenClaw源码优先适配64位);
- 提前注册大模型API密钥(可选但建议):OpenClaw需接入外部大模型才能正常执行任务,可提前注册OpenAI、智谱AI、月之暗面等平台,获取API密钥(后续配置使用);
- 预留网络带宽:下载Node.js、源码和依赖包需稳定网络,避免下载中断;
- 关闭不必要的安全软件(Windows):部分安全软件可能拦截依赖包安装或项目启动,安装期间可临时关闭,完成后再开启。
提示:新手优先选择Windows系统安装,步骤更直观,报错更容易排查;Linux适合有一定命令行基础的用户,部署更简洁。另外,OpenClaw本身不消耗大量资源,但接入大模型执行任务时,会产生token消耗,需注意大模型的计费规则。
三、Windows 系统安装步骤(详细版)
本章节以Windows 11 64位为例,步骤适用于Windows 10/11,每一步均附清晰操作指引,新手可直接跟着操作,全程无复杂命令。
步骤1:安装Node.js(TypeScript运行环境)
OpenClaw基于TypeScript开发,需依赖Node.js运行环境(Node.js自带npm,用于安装项目依赖),推荐安装v18版本(稳定兼容)。
- 下载Node.js:
下载地址:https://nodejs.org/zh-cn/download/
选择“Windows 安装包(64位)”,下载v18.x.x版本(如v18.17.0,避免安装最新测试版,稳定性不足)。
- 安装Node.js:
- 双击安装包,勾选“我接受许可协议”,点击“下一步”;
- 安装路径建议默认(C:\Program Files\nodejs),若需修改,需记住路径(后续配置环境变量可能用到);
- 勾选“Add to PATH”(自动配置环境变量,关键步骤),点击“下一步”;
- 其他选项默认,点击“下一步”,等待安装完成(约2-5分钟)。
- 验证Node.js是否安装成功:
- 按下Win+R,输入“cmd”打开命令提示符;
- 输入命令
node -v和npm -v; - 若分别显示Node.js版本(如v18.17.0)和npm版本(如9.6.7),则安装成功;若提示“不是内部或外部命令”,则环境变量配置失败,重启电脑后再验证(默认勾选Add to PATH可自动配置,无需手动操作)。
步骤2:安装Git(下载源码必备)
OpenClaw源码托管在GitHub,需通过Git下载(也可直接下载压缩包,推荐Git下载,方便后续更新)。
- 下载Git:
下载地址:https://git-scm.com/downloads
选择Windows版本,下载后双击安装包。
- 安装Git:
- 点击“Next”,接受许可协议;
- 安装路径默认即可,点击“Next”;
- 勾选“Use Git from Git Bash only”(新手推荐),其他默认,点击“Next”;
- 后续步骤全部默认,点击“Next”直至安装完成。
- 验证Git是否安装成功:
- 打开命令提示符(cmd),输入命令
git --version; - 若显示Git版本信息(如git version 2.42.0.windows.1),则安装成功。
步骤3:下载OpenClaw源码
通过Git命令下载最新源码,也可直接从GitHub下载压缩包,两种方式均可,推荐Git下载。
- 打开命令提示符(cmd),进入想要存放源码的目录(如D:\OpenClaw),输入命令:
cd D:\OpenClaw
(若D盘没有OpenClaw文件夹,可先输入md OpenClaw创建文件夹,再进入)
- 输入Git命令下载源码:
git clone https://github.com/OpenClaw/openclaw.git
若没有Git,可直接访问GitHub地址下载压缩包:https://github.com/OpenClaw/openclaw,下载后解压到D:\OpenClaw目录。
- 下载完成后,进入源码目录(D:\OpenClaw\openclaw),确认目录下有“src”“package.json”“tsconfig.json”等文件(TypeScript项目核心文件),说明源码下载成功。
步骤4:配置依赖并编译项目
OpenClaw项目依赖多个npm包,需通过npm安装,再编译TypeScript代码(生成可运行的JavaScript文件)。
- 打开命令提示符(cmd),进入OpenClaw源码目录:
cd D:\OpenClaw\openclaw
- 安装项目依赖:
输入命令 npm install
等待依赖安装完成(约3-10分钟,取决于网络速度),期间不要关闭命令提示符,若出现警告可忽略,只要不报错即可。
提示:若安装失败,可尝试输入npm install --registry=https://registry.npm.taobao.org(使用淘宝镜像,提升下载速度)。
- 编译TypeScript代码:
项目package.json中已配置编译脚本,输入命令 npm run build
编译完成后,源码目录下会生成“dist”文件夹(存放编译后的JavaScript文件),即为编译成功的标志。
注意:若编译报错,大概率是Node.js版本过低,需升级到v16及以上版本;若依赖安装失败,可删除node_modules文件夹和package-lock.json文件,重新执行npm install。
步骤5:运行OpenClaw并验证
编译完成后,即可启动OpenClaw,首次启动需简单配置,接入大模型即可正常使用。
- 启动OpenClaw:
在命令提示符中输入命令 npm start
启动成功后,会提示“OpenClaw started successfully”,同时会自动打开浏览器,进入OpenClaw的Web界面(默认地址:http://localhost:3000)。
- 首次配置(接入大模型):
- 打开Web界面后,点击“Settings”(设置),选择“Model”(模型);
- 选择要接入的大模型(如OpenAI GPT、智谱GLM等),输入对应的API密钥;
- 点击“Save”保存配置,返回主界面。
- 验证运行:
- 在Web界面的输入框中,输入简单指令(如“帮我检索本地D盘的文档文件”);
- 点击“Run”,OpenClaw会调用接入的大模型,执行指令并返回结果;
- 若能正常返回执行结果,说明OpenClaw安装并配置成功。
验证成功标志:Web界面正常加载,输入指令后能正常执行并返回结果,无报错提示。注意:执行任务时需保证网络通畅,且API密钥有效,否则会执行失败。
四、Linux 系统安装步骤(Ubuntu 22.04 为例)
Linux系统安装更简洁,依托命令行完成,适合有一定命令行基础的用户,步骤如下(全程使用终端操作):
步骤1:安装Node.js(TypeScript运行环境)
- 打开终端(Ctrl+Alt+T),更新软件源:
sudo apt update && sudo apt upgrade -y
- 安装Node.js(v18版本):
输入命令sudo apt install nodejs npm -y
安装完成后,验证版本:node -v和npm -v,确保node版本≥16。
若版本过低,可通过nvm升级(可选):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
步骤2:安装Git并下载源码
- 安装Git:
sudo apt install git -y
- 创建并进入存放源码的目录:
mkdir -p ~/OpenClaw && cd ~/OpenClaw
- 下载OpenClaw源码:
git clone https://github.com/OpenClaw/openclaw.git
- 进入源码目录:
cd openclaw
步骤3:配置依赖并编译项目
- 安装项目依赖:
npm install
若下载速度慢,可切换淘宝镜像:npm config set registry https://registry.npm.taobao.org,再重新安装。
- 编译TypeScript代码:
npm run build
编译成功后,生成dist文件夹。
步骤4:运行并验证
- 启动OpenClaw:
npm start
- 验证运行:
- 打开Linux浏览器,访问地址:http://localhost:3000;
- 按照Windows步骤的配置方法,接入大模型API密钥;
- 输入指令测试,能正常执行即可。
- 后台运行(可选):
若想关闭终端后仍运行OpenClaw,可使用nohup命令:
nohup npm start &
停止运行时,输入ps aux | grep node,找到进程ID,再输入kill -9 进程ID即可。
五、常见安装报错及解决方案
本章汇总OpenClaw安装、编译、运行全流程中最常见的报错,按“报错场景分类”,每个报错附“报错信息+原因分析+解决方案”,兼顾Windows和Linux系统,新手可直接对照排查。
5.1 环境配置类报错(Node.js/Git相关)
报错1:cmd/终端输入 node -v 提示“不是内部或外部命令”
报错信息:‘node’ 不是内部或外部命令,也不是可运行的程序或批处理文件。(Windows);command not found: node(Linux)
原因分析:Node.js未安装成功,或环境变量未配置生效。
解决方案:
- Windows系统:
- 重新安装Node.js,安装时务必勾选“Add to PATH”;
- 若已安装,右键“此电脑”→“属性”→“环境变量”,检查系统变量Path中是否有Node.js的bin目录(默认:C:\Program Files\nodejs),无则添加,添加后重启cmd验证;
- Linux系统:
- 若通过apt安装失败,改用nvm安装(参考第四章步骤1.2);
- 执行
source ~/.bashrc刷新环境变量,再重新验证。
报错2:Git clone 提示“fatal: unable to access ‘https://github.com/OpenClaw/openclaw.git/’”
报错信息:fatal: unable to access ‘https://github.com/OpenClaw/openclaw.git/’: Failed to connect to github.com port 443 after 21070 ms: Couldn’t connect to server
原因分析:网络不稳定、GitHub访问受限,或未安装Git。
解决方案:
- 先验证Git是否安装:输入
git --version,未安装则重新安装; - 切换稳定网络,或使用科学上网工具(需合规);
- 备选方案:直接访问GitHub地址(https://github.com/OpenClaw/openclaw),下载ZIP压缩包,解压后替代Git clone的源码。
5.2 依赖安装类报错(npm install相关)
报错3:npm install 提示“ERR! code EINTEGRITY”
报错信息:npm ERR! code EINTEGRITY npm ERR! sha512-xxxxxxxxx 完整性校验失败
原因分析:npm缓存损坏,或依赖包下载不完整,导致完整性校验未通过。
解决方案:
- 清除npm缓存:输入
npm cache clean --force; - 删除源码目录下的 node_modules 文件夹和 package-lock.json 文件;
- 切换淘宝镜像(提升下载稳定性):
npm config set registry https://registry.npm.taobao.org; - 重新执行
npm install。
报错4:npm install 提示“ERR! gyp ERR! find Python”
报错信息:gyp ERR! find Python Python is not set from command line or npm configuration
原因分析:部分依赖包需要Python环境编译,本地未安装Python,或Python未配置环境变量。
解决方案:
- Windows系统:
- 下载Python 3.8+版本(https://www.python.org/downloads/),安装时勾选“Add Python to PATH”;
- 安装完成后,重启cmd,重新执行
npm install;
- Linux系统:
- 执行
sudo apt install python3 python3-pip -y,安装完成后重新执行npm install。
- 执行
5.3 编译类报错(npm run build相关)
报错5:npm run build 提示“error TS2307: Cannot find module ‘xxx’”
报错信息:error TS2307: Cannot find module ‘xxx’ or its corresponding type declarations.
原因分析:依赖包未安装完整,或部分依赖包的类型声明文件缺失。
解决方案:
- 重新执行
npm install,确保依赖包全部安装完成; - 若仍报错,手动安装缺失的依赖包:
npm install xxx --save-dev(xxx为报错中提示的缺失模块名); - 若为类型声明缺失,安装@types/xxx:
npm install @types/xxx --save-dev。
报错6:npm run build 提示“error TS1086: An accessor cannot be declared in an ambient context”
报错信息:error TS1086: An accessor cannot be declared in an ambient context.
原因分析:TypeScript版本与项目依赖不兼容,通常是TypeScript版本过高。
解决方案:
- 查看项目package.json中指定的typescript版本(如"typescript": “^4.9.5”);
- 卸载当前过高的TypeScript版本:
npm uninstall typescript -g; - 安装项目兼容的版本:
npm install [email protected] --save-dev(版本号替换为package.json中指定的版本); - 重新执行
npm run build。
5.4 运行类报错(npm start相关)
报错7:npm start 提示“Port 3000 is already in use”
报错信息:Error: listen EADDRINUSE: address already in use :::3000
原因分析:3000端口被其他程序占用(OpenClaw默认使用3000端口)。
解决方案:
方案1:关闭占用3000端口的程序
- Windows:cmd中输入
netstat -ano | findstr :3000,找到PID(进程ID),打开任务管理器,结束对应PID的进程; - Linux:终端输入
lsof -i:3000,找到进程ID,执行kill -9 进程ID;
方案2:修改OpenClaw默认端口
- 打开源码目录下的src/config.ts文件,找到port配置项,修改为其他未占用端口(如3001);
- 重新执行
npm run build和npm start,访问地址改为http://localhost:3001。
报错8:启动后访问http://localhost:3000 提示“无法访问此网站”
报错信息:localhost拒绝连接,或无法加载页面。
原因分析:OpenClaw未启动成功,或端口配置错误,或防火墙拦截。
解决方案:
- 检查cmd/终端是否有“OpenClaw started successfully”提示,无则重新执行
npm start,查看是否有其他报错; - 确认端口是否正确(默认3000),若修改过端口,访问对应端口;
- Windows系统:关闭防火墙,或允许Node.js通过防火墙(控制面板→防火墙→允许应用通过防火墙);
- Linux系统:执行
sudo ufw allow 3000,开放3000端口,再重新访问。
5.5 大模型配置类报错(运行指令相关)
报错9:输入指令后提示“API key is invalid”
报错信息:Error: API key is invalid or expired.
原因分析:大模型API密钥无效、过期,或配置错误。
解决方案:
- 登录对应大模型平台(如OpenAI、智谱AI),检查API密钥是否有效,若过期则重新生成;
- 打开OpenClaw Web界面→Settings→Model,确认API密钥输入正确(无空格、无多余字符);
- 确认选择的大模型与API密钥匹配(如OpenAI的密钥不能用于智谱GLM);
- 检查网络是否能访问该大模型的API接口(部分大模型需科学上网,需合规)。
通用排查技巧:所有报错优先查看cmd/终端的报错信息,找到“ERR!”后面的核心提示,对照本章分类排查;若仍无法解决,可访问OpenClaw GitHub Issues(https://github.com/OpenClaw/openclaw/issues),搜索报错信息,查看社区解决方案。
六、安装后基础配置(可选)
安装并验证成功后,可根据个人需求进行基础配置,提升使用体验,以下配置均为可选,新手可先不配置,熟悉使用后再优化。
6.1 自定义OpenClaw启动端口
若3000端口被占用,除了临时关闭占用程序,也可永久修改启动端口:
- 打开OpenClaw源码目录下的
src/config.ts文件(可用VS Code或记事本打开); - 找到
port: 3000配置项,修改为其他未占用端口(如3001、8080); - 保存文件后,重新执行
npm run build,再启动OpenClaw,访问地址改为 http://localhost:新端口。
6.2 配置默认大模型与API密钥
为避免每次启动都重新配置API密钥,可直接修改配置文件,设置默认大模型:
- 打开源码目录下的
src/config.ts文件; - 找到
model配置项,修改默认模型(如defaultModel: "gpt-3.5-turbo"); - 找到
apiKeys配置项,添加对应模型的API密钥(如openai: "你的OpenAI API密钥"); - 保存文件,重新编译启动,后续无需重复配置。
注意:API密钥属于敏感信息,不要将修改后的配置文件上传至公开仓库,避免密钥泄露。
6.3 设置开机自启(Windows/Linux)
Windows系统
- 创建一个批处理文件(.bat),内容为:
cd D:\OpenClaw\openclaw(替换为你的OpenClaw源码目录)
npm start
- 将批处理文件放入 Windows 启动目录(C:\Users\你的用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup);
- 重启电脑,OpenClaw会自动启动。
Linux系统(Ubuntu)
- 创建systemd服务文件:
sudo nano /etc/systemd/system/openclaw.service; - 写入以下内容(替换路径为你的源码目录):
[Unit]
Description=OpenClaw AI Agent
After=network.target
[Service]
User=你的用户名
WorkingDirectory=/home/你的用户名/OpenClaw/openclaw
ExecStart=/usr/bin/npm start
Restart=always
[Install]
WantedBy=multi-user.target
- 保存退出(Ctrl+O,Enter,Ctrl+X);
- 启动服务并设置开机自启:
sudo systemctl start openclaw
sudo systemctl enable openclaw
七、总结与扩展
7.1 安装核心总结
OpenClaw(AI代理,曾用名Clawdbot、Moltbot)的安装核心的是“配置TypeScript运行环境+下载源码+安装依赖+编译启动”,全程无复杂操作,新手可按以下流程快速落地:
- 优先安装Node.js(v16+)和Git,确保环境变量配置生效;
- 下载OpenClaw源码,进入源码目录安装依赖(推荐用淘宝镜像提升速度);
- 编译TypeScript代码,启动项目后,接入大模型API密钥即可使用;
- 遇到报错,优先对照第五章排查,核心解决环境、依赖、端口三大问题。
Windows系统适合新手,步骤直观;Linux系统适合有命令行基础的用户,部署更简洁,两种系统均可完美运行OpenClaw。
7.2 扩展思考与进阶使用
- 二次开发:OpenClaw开源且基于TypeScript开发,可通过修改src目录下的代码,扩展自定义技能(如添加本地文件批量处理、自动化办公脚本等);
- 模型切换:支持接入多个大模型,可根据需求切换(如日常任务用GPT-3.5,复杂任务用GPT-4或智谱GLM-4);
- 版本更新:通过Git命令
git pull可更新OpenClaw源码,更新后需重新执行npm install和npm run build; - 问题反馈:若遇到未解决的报错,可在OpenClaw GitHub仓库提交Issues,或加入社区交流群,获取开发者和其他用户的帮助。
7.3 工具优势与适用人群
OpenClaw的核心优势是“轻量、开源、可定制”,无需复杂部署,个人电脑即可运行,适合:
- 职场人:自动化处理重复工作(如邮件发送、文件整理、报告生成);
- 程序员:学习AI代理开发、TypeScript项目部署,或扩展自定义自动化工具;
- 内容创作者:自动检索资料、生成稿件大纲、批量处理素材。
最后提醒:OpenClaw仅为AI代理工具,核心功能依赖外部大模型,使用时需遵守各大模型的使用规则,避免违规操作;同时注意保护API密钥,防止泄露导致不必要的损失。