夜雨聆风
你有没有想过，拥有一个完全属于自己的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
