OpenClaw安装全攻略:从报错到运行,一篇搞定

你有没有想过，拥有一个完全属于自己的AI助手？

不用付月费，不用担心隐私泄露，可以在Telegram、WhatsApp、Slack上随时召唤，回答你的问题，帮你写代码，甚至控制你的智能家居。

听起来很美好对吧？

OpenClaw让这一切成为可能。它是开源的个人AI助手框架，支持20+消息通道，可以连接OpenAI、Claude、Ollama等各种大模型。

但当你真正开始安装时，报错接二连三地来。

command not found、sharp构建失败、Node版本过低……

我踩完了所有的坑，所以你不用再踩。

这篇文章，给你一份完整的OpenClaw安装指南，外加7个常见报错的解决方案。收藏好，你会用得上的。

一、OpenClaw是什么？

OpenClaw是一个开源的个人AI助手框架。

简单说，你可以在自己的电脑或服务器上运行它，然后通过Telegram、WhatsApp、Slack、Discord等20+个消息平台和它对话。

核心特点：

特点	说明
🌐 多通道支持	WhatsApp、Telegram、Slack、Discord、微信等20+
🤖 多模型支持	OpenAI、Anthropic Claude、Ollama本地模型
🔒 隐私安全	数据在本地，不泄露给第三方
🔧 可扩展	Skills系统，可安装社区技能
💰 无月费	只付API调用费，没有订阅费
📖 开源	MIT许可证，代码完全公开

为什么选择OpenClaw？

隐私：所有数据都在你自己的设备上
成本：没有月费，只按API调用付费
灵活：可以自己写Skills扩展功能
可控：完全了解系统在做什么

二、安装前准备

系统要求

要求	最低版本	备注
Node.js	22+	安装脚本会自动安装
操作系统	macOS、Linux、Windows	Windows强烈推荐WSL2
内存	4GB+	推荐8GB以上
网络	需要访问外网	安装依赖和连接LLM

⚠️ Windows用户必看

强烈推荐使用WSL2！

OpenClaw在Windows原生环境上的支持有限，很多功能可能无法正常工作。

安装WSL2：

wsl --install

安装完成后，在WSL2中运行后续的安装命令。

三、安装方法详解

OpenClaw提供了多种安装方式，选择最适合你的：

方法一：安装脚本（推荐⭐）

最简单的方式，一条命令搞定。

macOS / Linux / WSL2：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

安装脚本会自动：

检测你的操作系统
安装Node.js（如果没有）
通过npm全局安装OpenClaw
启动入门向导

如果只想安装，不运行向导：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

方法二：npm/pnpm安装

适合已经装了Node.js的用户。

npm：

npm install -g openclaw@latest
openclaw onboard --install-daemon

pnpm：

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

💡 注意：pnpm需要运行pnpm approve-builds -g来批准构建脚本。

方法三：Docker安装

适合容器化部署或VPS用户。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker-compose up -d

方法四：从源码安装

适合开发者或想要贡献代码的用户。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

四、常见报错及解决方案（重点！）

这部分是全文精华，建议收藏。

报错1：openclaw: command not found

报错信息：

bash: openclaw: command not found

原因： npm全局安装的bin目录不在你的PATH环境变量中。

解决方案：

# 1. 检查npm全局安装路径
npm prefix -g

# 2. 查看当前PATH
echo $PATH

# 3. 添加到PATH（选择你使用的shell）
# 如果用zsh（macOS默认）：
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 如果用bash：
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证：

which openclaw
# 应该输出类似：/usr/local/bin/openclaw

报错2：sharp 构建失败

报错信息：

sharp: Please add node-gyp to your dependencies
# 或
Error: Could not load the "sharp" module

原因： libvips库冲突，或node-gyp构建工具缺失。

解决方案：

方案1：强制使用预构建二进制（推荐）

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

方案2：安装构建工具

macOS：

xcode-select --install
npm install -g node-gyp

Linux (Ubuntu/Debian)：

sudo apt-get install build-essential python3 cmake pkg-config libtool

报错3：pnpm Ignored build scripts 警告

报错信息：

 WARN  Ignored build scripts: openclaw, node-llama-cpp, sharp

原因： pnpm默认不运行包的构建脚本，需要手动批准。

解决方案：

pnpm approve-builds -g

然后在交互界面中选择：

openclaw
node-llama-cpp
sharp

报错4：Node版本过低

报错信息：

error openclaw@latest: The engine "node" is incompatible

原因： OpenClaw需要Node.js 22或更高版本。

解决方案：

检查当前版本：

node -v

使用nvm升级（推荐）：

nvm install 22
nvm use 22
nvm alias default 22

或使用Homebrew（macOS）：

brew install node@22
brew link node@22

报错5：Windows直接安装失败

报错信息：各种奇怪的错误，或安装成功但运行异常。

原因： OpenClaw对Windows原生环境支持有限。

解决方案：使用WSL2

# 1. 安装WSL2
wsl --install

# 2. 重启电脑

# 3. 打开WSL2，安装OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

报错6：Telegram通道启动后静默停止

报错信息：启动日志正常，但通道不收消息，也没有明显错误。

原因： 轮询初始化失败，或bot token配置问题。

解决方案：

# 1. 查看详细日志
openclaw gateway --verbose

# 2. 检查Telegram bot token是否正确
# 到 @BotFather 确认token

# 3. 确认网络能访问 api.telegram.org
curl -I https://api.telegram.org

# 4. 如果在国内，可能需要代理
export https_proxy=http://127.0.0.1:7890

报错7：API密钥明文存储警告

问题描述：配置的API密钥以明文形式存储在配置文件中。

解决方案：

升级到最新版本（2026.3.8+已修复大部分情况）
检查配置文件：

cat ~/.openclaw/models.json

如果发现明文key，重新配置：

openclaw config

使用环境变量（更安全）：

export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"

五、安装后验证

安装完成后，运行这些命令验证：

# 1. 运行诊断（检查配置问题）
openclaw doctor

# 2. 检查服务状态
openclaw status

# 3. 打开Web管理界面
openclaw dashboard

如果openclaw doctor发现问题：

根据提示修复
常见问题：配置文件缺失、权限问题、依赖未安装

六、入门配置指南

运行入门向导

openclaw onboard --install-daemon

向导会引导你完成：

选择模型提供商 — OpenAI / Anthropic / Ollama 等
配置认证 — 输入API Key或OAuth授权
设置工作空间 — 默认 ~/.openclaw/workspace
配置Gateway — 端口和token认证
连接消息通道 — Telegram / WhatsApp 等
安装Skills — 社区技能扩展

配置文件位置

文件	位置
主配置	~/.openclaw/openclaw.json
工作空间	~/.openclaw/workspace/
模型配置	~/.openclaw/models.json

七、常用命令速查

命令	作用
openclaw onboard	运行入门向导
openclaw doctor	诊断配置问题
openclaw status	查看服务状态
openclaw dashboard	打开Web界面
openclaw gateway	启动Gateway服务
openclaw --help	查看帮助

八、写在最后

OpenClaw是搭建个人AI助手的优秀选择。

开源、隐私、灵活，这些优点让它成为越来越多人的选择。

安装过程虽然有些坑，但只要按这篇文章一步步来，都能顺利解决。

如果你在安装过程中遇到其他问题，欢迎在评论区留言，我会尽力帮你解决。

觉得有用？点个"在看"，让更多人看到。

相关资源：

OpenClaw官网：https://openclaw.ai
GitHub仓库：https://github.com/openclaw/openclaw
Discord社区：https://discord.gg/clawd