OpenClaw 2026 最终安装指南：从零开始部署你的个人 AI 助理

凌晨两点，我对着屏幕上第17个报错信息发呆。

“Cannot find module ‘@anthropic-ai/sdk’“——这行红字我已经看了三天。作为一个折腾过无数开源项目的开发者，我以为自己见惯了各种安装失败的场面。但 OpenClaw 的部署过程，确实让我体验了一把从”自信满满”到”怀疑人生”的完整心路历程。

说实话，当我终于在 Mac Mini 上跑通第一个对话时，那种成就感堪比当年第一次写出 “Hello World”。OpenClaw 这东西，一旦装好了确实香——你能在 WhatsApp、Telegram、Discord 甚至 iMessage 上随时调用 Claude、GPT-4 这些顶级 AI，而且数据完全私有，不用担心隐私泄露。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

但问题就是：安装过程对新手真的不太友好。

这篇指南不会给你画大饼，也不会堆砌官方文档里那些你已经看过十遍的废话。我会把我踩过的坑、试过的路、最终跑通的方法，原原本本地告诉你。不管你是 Windows 用户、Mac 党，还是准备往服务器上部署的老司机，都能找到适合你的方案。

安装前准备：先别急着动手

很多人一看到”一键安装脚本”就兴奋地直接复制粘贴——别，先等等。

OpenClaw 对系统环境有硬性要求，跳过后续全是坑。根据官方文档和社区反馈，以下是你需要确认的几件事：

Node.js 版本必须是 22 或更高

这点特别重要。我用 Node 20 试过，各种依赖报错，升级到 24 之后瞬间顺畅。检查命令很简单：

node --version

如果显示低于 v22，先去 Node.js 官网下载最新 LTS 版本。Windows 用户建议直接安装 24.x，别在版本上抠抠搜搜。

操作系统兼容性

• macOS：12.0 (Monterey) 及以上，Intel 和 Apple Silicon 都支持
• Windows：必须通过 WSL2 运行，原生 Windows 不支持
• Linux：Ubuntu 20.04+、Debian 11+、CentOS 8+ 测试通过

API 密钥准备

OpenClaw 本身只是个”网关”，你需要接入具体的 AI 服务才能用。目前支持 Claude (Anthropic)、OpenAI、Google Gemini 等。建议至少准备一个 Claude API Key，体验最好。

国内用户特别提示

npm 官方源在国内龟速，建议提前切换淘宝镜像：

npm config set registry https://registry.npmmirror.com

还有就是 API 调用的网络问题——Anthropic 和 OpenAI 的接口都需要海外网络环境。如果你没有稳定的出海线路，建议寻找合规的中转方案。

方案一：一键脚本安装（最快，5分钟搞定）

如果你符合以下条件，直接选这个方案：

• 系统是 macOS、Linux 或 WSL2
• 只是想快速体验，不想折腾
• 对系统改动接受度较高

安装命令

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

这个脚本会自动完成以下操作：

1. 检查 Node.js 版本（不够就提示你升级）
2. 全局安装 openclaw npm 包
3. 创建必要的配置文件目录（~/.openclaw/）
4. 设置系统服务（可选）

安装后初始化

openclaw onboard --install-daemon

这一步会让你输入 API Key，并配置默认的对话渠道。按照提示走就行，没有什么需要特别注意的。

验证安装

openclaw --version

看到版本号输出，说明安装成功。整个过程顺利的话，确实只要 5 分钟。

但我得说实话——这个”一键”脚本在我的一台 Ubuntu 服务器上跑挂了两次，原因都是权限问题。如果你也遇到类似情况，别急，看下面的 npm 手动安装方案。

方案二：npm 全局安装（最灵活，推荐进阶用户）

这是我自己最常用、也最推荐的安装方式。虽然步骤多一点，但出了问题容易排查，对系统的侵入性也更小。

步骤 1：确认 Node.js 环境

# 检查版本
node --version

# 如果版本不够，建议用 nvm 管理
# macOS/Linux 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 然后安装 Node 24
nvm install 24
nvm use 24

步骤 2：安装 OpenClaw

npm install -g openclaw@latest

这里用 @latest 确保安装的是最新版本。OpenClaw 更新挺频繁的，2026 年 2 月的版本已经到 v2026.2.24。

如果安装过程中遇到 EACCES 权限错误（这在 macOS 上很常见），说明 npm 的全局目录权限没配好。修复方法：

# 创建专属目录
mkdir ~/.npm-global

# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'

# 添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g openclaw@latest

步骤 3：初始化配置

openclaw onboard --install-daemon

这一步会交互式地引导你完成：

1. 选择要连接的 AI 提供商（Claude、OpenAI、Gemini 等）
2. 输入对应的 API Key
3. 配置消息渠道（Telegram Bot、Discord 等）
4. 设置系统服务（可选但推荐）

步骤 4：启动服务

# 前台运行（调试时用）
openclaw start

# 后台运行（正式使用）
openclaw start --daemon

方案三：Docker 安装（最安全，推荐服务器部署）

如果你要把 OpenClaw 跑在 VPS、NAS 或者任何需要长期稳定运行的环境上，Docker 是最明智的选择。容器隔离能有效防止 AI 智能体的误操作影响宿主系统——别笑，真有人的 OpenClaw 实例误删过文件。

步骤 1：确认 Docker 环境

docker --version
docker-compose --version

版本没有硬性要求，但建议 Docker 20.10+。

步骤 2：创建配置文件目录

mkdir -p ~/openclaw-data/config
mkdir -p ~/openclaw-data/data

步骤 3：准备 Docker Compose 文件

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ~/openclaw-data/config:/app/config
      - ~/openclaw-data/data:/app/data
    environment:
      - NODE_ENV=production
      - ANTHROPIC_API_KEY=${{ANTHROPIC_API_KEY}}
      - OPENAI_API_KEY=${{OPENAI_API_KEY}}

步骤 4：配置环境变量

# 创建 .env 文件
cat > ~/openclaw-data/.env << EOF
ANTHROPIC_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
EOF

步骤 5：启动容器

cd ~/openclaw-data
docker-compose up -d

步骤 6：查看日志确认状态

docker logs -f openclaw

看到 “OpenClaw Gateway started on port 3000” 就是成功了。

对了，Docker 方案的一个额外好处是：你可以在 Mac Mini、树莓派或者任何能跑 Docker 的设备上部署，然后通过手机上的 Telegram、WhatsApp 随时调用。这其实是很多人使用 OpenClaw 的主要场景。

Windows WSL2 安装详细步骤

Windows 用户必须通过 WSL2 运行 OpenClaw，原生 Windows 不支持。这里有几个容易踩的坑：

坑 1：WSL 版本不对

# 检查 WSL 版本
wsl --list --verbose

如果显示 Version 1，需要升级：

# 在 PowerShell（管理员）中运行
wsl --set-version Ubuntu 2

坑 2：WSL2 内存不足

OpenClaw 运行时会占用一定内存，WSL2 默认配置可能不够。建议在 Windows 用户目录创建 .wslconfig：

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

[wsl2]
memory=4GB
processors=2

然后重启 WSL：

wsl --shutdown

坑 3：Windows 防火墙拦截

如果你要从 Windows 浏览器访问 WSL2 里运行的 OpenClaw Web 界面，可能需要在 Windows 防火墙里放行相应端口。

如何在 Mac Mini 运行 OpenClaw

用 Mac Mini 跑 OpenClaw 是个相当不错的方案——低功耗、静音、性能又够。我自己的那台 M1 Mac Mini 已经稳定运行了三个月。

M 系列芯片注意事项

Docker 镜像需要选择支持 ARM64 的版本。最新的 OpenClaw 官方镜像已经原生支持 Apple Silicon，不需要 Rosetta 转译。

# docker-compose.yml 中指定平台（一般不需要，但如果拉取失败可以试试）
services:
  openclaw:
    platform: linux/arm64
    image: openclaw/openclaw:latest

常驻后台运行

macOS 上推荐使用 launchd 管理服务。安装时的 --install-daemon 参数会自动创建 plist 文件，但如果你手动安装的，可能需要自己配置：

# 检查服务状态
launchctl list | grep openclaw

# 手动加载
launchctl load ~/Library/LaunchAgents/ai.openclaw.daemon.plist

OpenClaw 常见错误排查

即使按照步骤来，你也可能遇到各种问题。这里列出几个高频错误和解决方法：

错误 1：“Cannot find module” 系列

原因：npm 安装不完整或版本不兼容

解决：

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

错误 2：“EACCES: permission denied”

原因：npm 全局目录权限问题

解决：参考前面 npm 安装章节的权限修复步骤

错误 3：API 调用返回 401/403

原因：API Key 无效或额度用尽

排查：

# 检查配置
openclaw config get

# 重新设置
openclaw config set anthropic.apiKey=your_new_key

错误 4：Docker 容器不断重启

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

原因：环境变量配置错误或端口冲突

排查：

# 查看详细日志
docker logs openclaw

# 检查端口占用
lsof -i :3000

错误 5：消息渠道收不到回复

原因：Webhook 配置错误或网络不通

排查：

• Telegram：确认 Bot Token 正确，Webhook URL 可访问
• Discord：确认 Bot 权限设置正确，Intents 已启用
• 国内服务器：检查是否能访问 Telegram/Discord 服务器

安装后的配置建议

OpenClaw 装好后，还有一些配置能让体验更上一层楼：

1. 配置多个 AI 提供商

建议同时配置 Claude 和 GPT-4，这样当一个服务不稳定时可以自动切换。

2. 设置系统级快捷键

macOS 可以用 Alfred + Workflow，Windows 用 PowerToys Run，实现全局快捷调用。

3. 定期备份配置

# 配置文件都在 ~/.openclaw/
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)

4. 监控运行状态

Docker 部署的建议加上健康检查：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

总结

说了这么多，如果你还在纠结选哪种安装方式，我的建议是：

• 想最快体验 → 一键脚本
• 日常主力使用 → npm 全局安装
• 服务器长期运行 → Docker

其实 OpenClaw 的安装并没有想象中那么难，很多”坑”都是因为文档不够友好、错误提示不够明确造成的。希望这篇指南能帮你少走些弯路。

最后说两句题外话。部署 OpenClaw 这件事本身，其实不只是装个软件那么简单——它代表了一种对 AI 使用的态度：数据私有、自主可控、不被某个平台绑定。在 AI 能力越来越强的今天，这种”主权意识”可能比你想象的更重要。

好了，去试试吧。如果遇到文档里没提到的问题，欢迎来评论区交流——我踩过的坑，可能比你想象的更多。

9 分钟阅读 · 发布于: 2026年2月26日 · 修改于: 2026年3月3日

Easton

AI与智能