OpenClaw（曾用名Clawdbot）AI代理安装教程｜Windows10/11+Ubuntu双系统适配，TypeScript开发，解决依赖缺失、启动失败等核心问题

目录

1. [OpenClaw 简介](#一、OpenClaw 简介)
2. 安装前核心准备（必看）
3. [Windows 系统安装步骤（详细版）](#三、Windows 系统安装步骤（详细版）)
4. 步骤1：安装Node.js（TypeScript运行环境）
5. 步骤2：安装Git（下载源码必备）
6. 步骤3：下载OpenClaw源码
7. 步骤4：配置依赖并编译项目
8. 步骤5：运行OpenClaw并验证
9. [Linux 系统安装步骤（Ubuntu 22.04 为例）](#四、Linux 系统安装步骤（Ubuntu 22.04 为例）)
10. 常见安装报错及解决方案
11. 安装后基础配置（可选）
12. 总结与扩展

一、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 核心用途拆解（贴合安装场景，新手易懂）

1. 自动化任务处理：这是OpenClaw的核心用途，接入大模型后，可自动完成本地文件检索、网络资料搜索、稿件撰写、邮件发送等任务，全流程无需人工干预；
2. 个人效率提升：适合职场人、程序员、内容创作者，可替代重复劳动，比如自动整理文件、生成报告、批量处理数据，搭配不同大模型可适配多样化需求；
3. 二次开发与定制：由于开源特性，开发者可基于其TypeScript源码进行二次开发，扩展自定义技能（Skill），适配个人专属的自动化场景；
4. 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系统，安装前需完成以下基础准备，避免因环境缺失或配置错误导致部署失败：

1. 确认系统位数：必须是64位系统（32位系统不支持高版本Node.js，且OpenClaw源码优先适配64位）；
2. 提前注册大模型API密钥（可选但建议）：OpenClaw需接入外部大模型才能正常执行任务，可提前注册OpenAI、智谱AI、月之暗面等平台，获取API密钥（后续配置使用）；
3. 预留网络带宽：下载Node.js、源码和依赖包需稳定网络，避免下载中断；
4. 关闭不必要的安全软件（Windows）：部分安全软件可能拦截依赖包安装或项目启动，安装期间可临时关闭，完成后再开启。

提示：新手优先选择Windows系统安装，步骤更直观，报错更容易排查；Linux适合有一定命令行基础的用户，部署更简洁。另外，OpenClaw本身不消耗大量资源，但接入大模型执行任务时，会产生token消耗，需注意大模型的计费规则。

三、Windows 系统安装步骤（详细版）

本章节以Windows 11 64位为例，步骤适用于Windows 10/11，每一步均附清晰操作指引，新手可直接跟着操作，全程无复杂命令。

步骤1：安装Node.js（TypeScript运行环境）

OpenClaw基于TypeScript开发，需依赖Node.js运行环境（Node.js自带npm，用于安装项目依赖），推荐安装v18版本（稳定兼容）。

1. 下载Node.js：

下载地址：https://nodejs.org/zh-cn/download/
选择“Windows 安装包（64位）”，下载v18.x.x版本（如v18.17.0，避免安装最新测试版，稳定性不足）。

2. 安装Node.js：
3. 双击安装包，勾选“我接受许可协议”，点击“下一步”；
4. 安装路径建议默认（C:\Program Files\nodejs），若需修改，需记住路径（后续配置环境变量可能用到）；
5. 勾选“Add to PATH”（自动配置环境变量，关键步骤），点击“下一步”；
6. 其他选项默认，点击“下一步”，等待安装完成（约2-5分钟）。
7. 验证Node.js是否安装成功：
8. 按下Win+R，输入“cmd”打开命令提示符；
9. 输入命令 node -v 和 npm -v；
10. 若分别显示Node.js版本（如v18.17.0）和npm版本（如9.6.7），则安装成功；若提示“不是内部或外部命令”，则环境变量配置失败，重启电脑后再验证（默认勾选Add to PATH可自动配置，无需手动操作）。

步骤2：安装Git（下载源码必备）

OpenClaw源码托管在GitHub，需通过Git下载（也可直接下载压缩包，推荐Git下载，方便后续更新）。

1. 下载Git：

下载地址：https://git-scm.com/downloads
选择Windows版本，下载后双击安装包。

2. 安装Git：
3. 点击“Next”，接受许可协议；
4. 安装路径默认即可，点击“Next”；
5. 勾选“Use Git from Git Bash only”（新手推荐），其他默认，点击“Next”；
6. 后续步骤全部默认，点击“Next”直至安装完成。
7. 验证Git是否安装成功：
8. 打开命令提示符（cmd），输入命令 git --version；
9. 若显示Git版本信息（如git version 2.42.0.windows.1），则安装成功。

步骤3：下载OpenClaw源码

通过Git命令下载最新源码，也可直接从GitHub下载压缩包，两种方式均可，推荐Git下载。

1. 打开命令提示符（cmd），进入想要存放源码的目录（如D:\OpenClaw），输入命令：

cd D:\OpenClaw
（若D盘没有OpenClaw文件夹，可先输入md OpenClaw创建文件夹，再进入）

2. 输入Git命令下载源码：

git clone https://github.com/OpenClaw/openclaw.git
若没有Git，可直接访问GitHub地址下载压缩包：https://github.com/OpenClaw/openclaw，下载后解压到D:\OpenClaw目录。

3. 下载完成后，进入源码目录（D:\OpenClaw\openclaw），确认目录下有“src”“package.json”“tsconfig.json”等文件（TypeScript项目核心文件），说明源码下载成功。

步骤4：配置依赖并编译项目

OpenClaw项目依赖多个npm包，需通过npm安装，再编译TypeScript代码（生成可运行的JavaScript文件）。

1. 打开命令提示符（cmd），进入OpenClaw源码目录：

cd D:\OpenClaw\openclaw

2. 安装项目依赖：

输入命令 npm install
等待依赖安装完成（约3-10分钟，取决于网络速度），期间不要关闭命令提示符，若出现警告可忽略，只要不报错即可。

提示：若安装失败，可尝试输入npm install --registry=https://registry.npm.taobao.org（使用淘宝镜像，提升下载速度）。

3. 编译TypeScript代码：

项目package.json中已配置编译脚本，输入命令 npm run build
编译完成后，源码目录下会生成“dist”文件夹（存放编译后的JavaScript文件），即为编译成功的标志。

注意：若编译报错，大概率是Node.js版本过低，需升级到v16及以上版本；若依赖安装失败，可删除node_modules文件夹和package-lock.json文件，重新执行npm install。

步骤5：运行OpenClaw并验证

编译完成后，即可启动OpenClaw，首次启动需简单配置，接入大模型即可正常使用。

1. 启动OpenClaw：

在命令提示符中输入命令 npm start
启动成功后，会提示“OpenClaw started successfully”，同时会自动打开浏览器，进入OpenClaw的Web界面（默认地址：http://localhost:3000）。

2. 首次配置（接入大模型）：
3. 打开Web界面后，点击“Settings”（设置），选择“Model”（模型）；
4. 选择要接入的大模型（如OpenAI GPT、智谱GLM等），输入对应的API密钥；
5. 点击“Save”保存配置，返回主界面。
6. 验证运行：
7. 在Web界面的输入框中，输入简单指令（如“帮我检索本地D盘的文档文件”）；
8. 点击“Run”，OpenClaw会调用接入的大模型，执行指令并返回结果；
9. 若能正常返回执行结果，说明OpenClaw安装并配置成功。

验证成功标志：Web界面正常加载，输入指令后能正常执行并返回结果，无报错提示。注意：执行任务时需保证网络通畅，且API密钥有效，否则会执行失败。

四、Linux 系统安装步骤（Ubuntu 22.04 为例）

Linux系统安装更简洁，依托命令行完成，适合有一定命令行基础的用户，步骤如下（全程使用终端操作）：

步骤1：安装Node.js（TypeScript运行环境）

1. 打开终端（Ctrl+Alt+T），更新软件源：

sudo apt update && sudo apt upgrade -y

2. 安装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并下载源码

1. 安装Git：

sudo apt install git -y

2. 创建并进入存放源码的目录：

mkdir -p ~/OpenClaw && cd ~/OpenClaw

3. 下载OpenClaw源码：

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

4. 进入源码目录：

cd openclaw

步骤3：配置依赖并编译项目

1. 安装项目依赖：

npm install
若下载速度慢，可切换淘宝镜像：npm config set registry https://registry.npm.taobao.org，再重新安装。

2. 编译TypeScript代码：

npm run build
编译成功后，生成dist文件夹。

步骤4：运行并验证

1. 启动OpenClaw：

npm start

2. 验证运行：
3. 打开Linux浏览器，访问地址：http://localhost:3000；
4. 按照Windows步骤的配置方法，接入大模型API密钥；
5. 输入指令测试，能正常执行即可。
6. 后台运行（可选）：
   若想关闭终端后仍运行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未安装成功，或环境变量未配置生效。

解决方案：

1. Windows系统：
   • 重新安装Node.js，安装时务必勾选“Add to PATH”；
   • 若已安装，右键“此电脑”→“属性”→“环境变量”，检查系统变量Path中是否有Node.js的bin目录（默认：C:\Program Files\nodejs），无则添加，添加后重启cmd验证；
2. 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。

解决方案：

1. 先验证Git是否安装：输入 git --version，未安装则重新安装；
2. 切换稳定网络，或使用科学上网工具（需合规）；
3. 备选方案：直接访问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缓存损坏，或依赖包下载不完整，导致完整性校验未通过。

解决方案：

1. 清除npm缓存：输入 npm cache clean --force；
2. 删除源码目录下的 node_modules 文件夹和 package-lock.json 文件；
3. 切换淘宝镜像（提升下载稳定性）：npm config set registry https://registry.npm.taobao.org；
4. 重新执行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未配置环境变量。

解决方案：

1. Windows系统：
   • 下载Python 3.8+版本（https://www.python.org/downloads/），安装时勾选“Add Python to PATH”；
   • 安装完成后，重启cmd，重新执行 npm install；
2. 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.

原因分析：依赖包未安装完整，或部分依赖包的类型声明文件缺失。

解决方案：

1. 重新执行 npm install，确保依赖包全部安装完成；
2. 若仍报错，手动安装缺失的依赖包：npm install xxx --save-dev（xxx为报错中提示的缺失模块名）；
3. 若为类型声明缺失，安装@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版本过高。

解决方案：

1. 查看项目package.json中指定的typescript版本（如"typescript": “^4.9.5”）；
2. 卸载当前过高的TypeScript版本：npm uninstall typescript -g；
3. 安装项目兼容的版本：npm install [email protected] --save-dev（版本号替换为package.json中指定的版本）；
4. 重新执行 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未启动成功，或端口配置错误，或防火墙拦截。

解决方案：

1. 检查cmd/终端是否有“OpenClaw started successfully”提示，无则重新执行 npm start，查看是否有其他报错；
2. 确认端口是否正确（默认3000），若修改过端口，访问对应端口；
3. Windows系统：关闭防火墙，或允许Node.js通过防火墙（控制面板→防火墙→允许应用通过防火墙）；
4. Linux系统：执行 sudo ufw allow 3000，开放3000端口，再重新访问。

5.5 大模型配置类报错（运行指令相关）

报错9：输入指令后提示“API key is invalid”

报错信息：Error: API key is invalid or expired.

原因分析：大模型API密钥无效、过期，或配置错误。

解决方案：

1. 登录对应大模型平台（如OpenAI、智谱AI），检查API密钥是否有效，若过期则重新生成；
2. 打开OpenClaw Web界面→Settings→Model，确认API密钥输入正确（无空格、无多余字符）；
3. 确认选择的大模型与API密钥匹配（如OpenAI的密钥不能用于智谱GLM）；
4. 检查网络是否能访问该大模型的API接口（部分大模型需科学上网，需合规）。

通用排查技巧：所有报错优先查看cmd/终端的报错信息，找到“ERR!”后面的核心提示，对照本章分类排查；若仍无法解决，可访问OpenClaw GitHub Issues（https://github.com/OpenClaw/openclaw/issues），搜索报错信息，查看社区解决方案。

六、安装后基础配置（可选）

安装并验证成功后，可根据个人需求进行基础配置，提升使用体验，以下配置均为可选，新手可先不配置，熟悉使用后再优化。

6.1 自定义OpenClaw启动端口

若3000端口被占用，除了临时关闭占用程序，也可永久修改启动端口：

1. 打开OpenClaw源码目录下的 src/config.ts 文件（可用VS Code或记事本打开）；
2. 找到 port: 3000 配置项，修改为其他未占用端口（如3001、8080）；
3. 保存文件后，重新执行 npm run build，再启动OpenClaw，访问地址改为 http://localhost:新端口。

6.2 配置默认大模型与API密钥

为避免每次启动都重新配置API密钥，可直接修改配置文件，设置默认大模型：

1. 打开源码目录下的 src/config.ts 文件；
2. 找到 model 配置项，修改默认模型（如 defaultModel: "gpt-3.5-turbo"）；
3. 找到apiKeys 配置项，添加对应模型的API密钥（如 openai: "你的OpenAI API密钥"）；
4. 保存文件，重新编译启动，后续无需重复配置。

注意：API密钥属于敏感信息，不要将修改后的配置文件上传至公开仓库，避免密钥泄露。

6.3 设置开机自启（Windows/Linux）

Windows系统

1. 创建一个批处理文件（.bat），内容为：

cd D:\OpenClaw\openclaw（替换为你的OpenClaw源码目录）

npm start

2. 将批处理文件放入 Windows 启动目录（C:\Users\你的用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup）；
3. 重启电脑，OpenClaw会自动启动。

Linux系统（Ubuntu）

1. 创建systemd服务文件：sudo nano /etc/systemd/system/openclaw.service；
2. 写入以下内容（替换路径为你的源码目录）：

[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

3. 保存退出（Ctrl+O，Enter，Ctrl+X）；
4. 启动服务并设置开机自启：

sudo systemctl start openclaw
sudo systemctl enable openclaw

七、总结与扩展

7.1 安装核心总结

OpenClaw（AI代理，曾用名Clawdbot、Moltbot）的安装核心的是“配置TypeScript运行环境+下载源码+安装依赖+编译启动”，全程无复杂操作，新手可按以下流程快速落地：

1. 优先安装Node.js（v16+）和Git，确保环境变量配置生效；
2. 下载OpenClaw源码，进入源码目录安装依赖（推荐用淘宝镜像提升速度）；
3. 编译TypeScript代码，启动项目后，接入大模型API密钥即可使用；
4. 遇到报错，优先对照第五章排查，核心解决环境、依赖、端口三大问题。

Windows系统适合新手，步骤直观；Linux系统适合有命令行基础的用户，部署更简洁，两种系统均可完美运行OpenClaw。

7.2 扩展思考与进阶使用

1. 二次开发：OpenClaw开源且基于TypeScript开发，可通过修改src目录下的代码，扩展自定义技能（如添加本地文件批量处理、自动化办公脚本等）；
2. 模型切换：支持接入多个大模型，可根据需求切换（如日常任务用GPT-3.5，复杂任务用GPT-4或智谱GLM-4）；
3. 版本更新：通过Git命令 git pull 可更新OpenClaw源码，更新后需重新执行 npm install 和 npm run build；
4. 问题反馈：若遇到未解决的报错，可在OpenClaw GitHub仓库提交Issues，或加入社区交流群，获取开发者和其他用户的帮助。

7.3 工具优势与适用人群

OpenClaw的核心优势是“轻量、开源、可定制”，无需复杂部署，个人电脑即可运行，适合：

• 职场人：自动化处理重复工作（如邮件发送、文件整理、报告生成）；
• 程序员：学习AI代理开发、TypeScript项目部署，或扩展自定义自动化工具；
• 内容创作者：自动检索资料、生成稿件大纲、批量处理素材。

最后提醒：OpenClaw仅为AI代理工具，核心功能依赖外部大模型，使用时需遵守各大模型的使用规则，避免违规操作；同时注意保护API密钥，防止泄露导致不必要的损失。