欢迎光临
我们一直在努力
        找回密码
当前位置：171主机测评 > 服务器技术 > 正文

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

2026-03-13 分类：服务器技术 阅读(76) 评论(0)

目录

  • [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 typescript@4.9.5 –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密钥，防止泄露导致不必要的损失。

    赞(0)
    未经允许不得转载：171主机测评 » OpenClaw（曾用名Clawdbot）AI代理安装教程｜Windows10/11+Ubuntu双系统适配，TypeScript开发，解决依赖缺失、启动失败等核心问题
    分享到： 更多 (0)
    标签：

    相关推荐

    评论 抢沙发

    取消

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址

    热门标签

    #人工智能(58552)#python(19893)#开发语言(16712)#java(15341)#运维(15252)#linux(14867)#大数据(14462)#服务器(12984)#算法(11687)#前端(10777)#网络(9295)#数据库(8816)#ai(8773)#c++(8106)#课程设计(6782)#学习(6707)#机器学习(6658)#区块链(5884)#OpenClaw(5385)#后端(5103)#spring boot(4978)#深度学习(4888)#c语言(4353)#毕业设计(4287)#数据结构(4168)#安全(4002)#docker(3909)#架构(3821)#javascript(3783)#大模型(3617)

    热门文章

    最新文章

    归档

    分类