OpenClaw 安装教程：从零搭建你的 AI 助手

OpenClaw 是什么？为什么你需要它

如果你曾经想过拥有一个真正属于自己的 AI 助手——不只是一个聊天窗口，而是一个能帮你查邮件、管文件、自动化工作流、甚至记住你偏好的"数字伙伴"——那么 OpenClaw 正是你在找的东西。

OpenClaw 是一个开源的个人 AI 助手平台，它把大语言模型（LLM）的能力和本地工具链结合在一起。你可以通过 Telegram、Discord、WhatsApp 甚至网页与它交互，它能执行文件操作、搜索网页、管理日程、运行 shell 命令，还能通过 Skills 系统无限扩展功能。

和 ChatGPT 这类在线聊天机器人不同，OpenClaw 运行在你自己的机器上，数据完全由你掌控。它有记忆系统、有性格、有主动性——它会定时检查你的邮箱、提醒你日程、甚至在你没问的时候主动告诉你天气。

系统要求

在开始安装之前，先确认你的环境满足以下要求：

项目	最低要求	推荐配置
操作系统	Linux / macOS / Windows (WSL2)	Ubuntu 22.04+ / macOS 14+
Node.js	v18.0+	v22 LTS
内存	512MB 可用	2GB+
磁盘空间	500MB	2GB+（含模型缓存）
网络	能访问 OpenRouter / OpenAI API	稳定网络连接

支持的操作系统：

• Linux：Ubuntu、Debian、CentOS、Arch 等主流发行版均可
• macOS：12 Monterey 及以上版本
• Windows：需要通过 WSL2 运行（推荐 Ubuntu on WSL）
• 树莓派：ARM64 架构同样支持

第一步：安装 Node.js

OpenClaw 基于 Node.js 开发，所以第一步是确保你的系统安装了 Node.js v18 或更高版本。

Linux（Ubuntu/Debian）

# 使用 NodeSource 安装 Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v  # 应显示 v22.x.x
npm -v   # 应显示 10.x.x

macOS

# 使用 Homebrew 安装
brew install node@22

# 或者从 nodejs.org 下载安装包
# 访问 https://nodejs.org 下载 LTS 版本

# 验证
node -v
npm -v

Windows（WSL2）

# 先安装 WSL2（以管理员身份运行 PowerShell）
wsl --install

# 进入 WSL 后按 Linux 方式安装
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

第二步：全局安装 OpenClaw

Node.js 就绪后，一行命令即可安装 OpenClaw：

npm install openclaw -g

安装完成后，验证版本：

openclaw --version

如果看到版本号输出，恭喜你，OpenClaw 已经成功安装到你的系统中了。

💡 小贴士：如果遇到权限问题（EACCES），不要用 sudo npm install。正确做法是配置 npm 全局目录：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

第三步：初始化工作空间

安装完成后，运行初始化命令来创建你的 OpenClaw 工作空间：

openclaw init

这个命令会引导你完成初始配置，包括：

1. 选择 AI 模型提供商（OpenRouter / OpenAI / Anthropic 等）
2. 配置 API Key
3. 选择默认模型
4. 设置时区
5. 配置消息通道（Telegram / Discord / WhatsApp 等）

初始化完成后，你会在 ~/.openclaw/ 目录下看到完整的工作空间结构。

第四步：了解配置文件

OpenClaw 的核心配置文件位于 ~/.openclaw/workspace/ 目录下，每个文件都有特定的用途：

文件名	作用	必须编辑？
SOUL.md	AI 的性格、风格、行为准则	强烈推荐
USER.md	关于你的信息（名字、偏好、时区等）	强烈推荐
AGENTS.md	工作规则和约定	保持默认即可
MEMORY.md	AI 的长期记忆	自动生成
TOOLS.md	工具相关的本地配置笔记	按需编辑
HEARTBEAT.md	定时任务配置	按需编辑

SOUL.md：定义 AI 的灵魂

这是最重要的配置文件之一。它决定了你的 AI 助手的说话风格、性格特征和行为准则。比如你可以让它幽默风趣，也可以让它严肃专业：

# SOUL.md 示例
## 性格
幽默、直接、不废话。有问题就解决，没空说"我很乐意帮助你"。

## 风格
简洁为主，技术问题给代码，生活问题给建议。偶尔吐槽。

USER.md：让 AI 认识你

填写你的基本信息，AI 会用这些信息来个性化服务：

# USER.md 示例
- 名字：小明
- 时区：Asia/Shanghai
- 职业：全栈开发者
- 偏好：喜欢简洁的回答，技术栈以 Node.js 为主

第五步：启动和验证

配置完成后，启动 OpenClaw Gateway 服务：

# 启动 Gateway
openclaw gateway start

# 查看状态
openclaw gateway status

如果一切正常，你会看到类似以下的输出，表示 Gateway 已经在运行并等待连接。

接下来，打开你配置的消息通道（比如 Telegram），向你的 bot 发送一条消息试试。如果你能收到回复，说明整个系统已经成功运行了！

🎯 验证清单：

✅ Gateway 运行正常（openclaw gateway status）
✅ 消息通道连接成功
✅ 能收到 AI 的回复
✅ AI 能执行基本命令（如 /status）

常见安装问题及解决方案

问题 1：npm install 报错 EACCES

原因：npm 全局安装目录权限不足。

解决：配置用户级 npm 目录，或者使用 nvm 管理 Node.js 版本（推荐）：

# 使用 nvm 安装 Node.js（推荐方式）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
npm install openclaw -g

问题 2：Node.js 版本过低

原因：系统自带的 Node.js 版本太旧（常见于 Ubuntu 仓库版本）。

解决：使用 NodeSource 或 nvm 安装 v18+ 版本，不要用系统包管理器的默认版本。

问题 3：Gateway 启动失败

原因：通常是 API Key 配置错误或网络问题。

解决步骤：

1. 检查配置文件中的 API Key 是否正确
2. 确认网络能访问对应的 API 端点
3. 查看日志：openclaw gateway logs
4. 尝试重启：openclaw gateway restart

问题 4：消息通道收不到消息

原因：Telegram Bot Token 错误，或 bot 未正确配置。

解决：确认 Bot Token 有效，且已在 Telegram 中正确与 bot 对话。运行 openclaw init 重新配置通道。

可选：Docker 部署

如果你不想在主机上直接安装 Node.js 环境，Docker 是一个干净的替代方案：

# 拉取镜像
docker pull openclaw/openclaw:latest

# 创建数据目录
mkdir -p ~/openclaw-data

# 运行容器
docker run -d \
  --name openclaw \
  -v ~/openclaw-data:/root/.openclaw \
  -p 3000:3000 \
  openclaw/openclaw:latest

# 查看日志
docker logs -f openclaw

Docker 部署的好处是环境隔离、易于迁移、不影响宿主机环境。适合在 VPS 上运行，或者想要快速测试的场景。

⚠️ 注意：使用 Docker 时，工作空间数据需要持久化挂载到宿主机，否则容器销毁后数据会丢失。

下一步

安装完成后，建议你：

1. 编辑 SOUL.md 和 USER.md，让 AI 更了解你
2. 试试基本聊天功能，发送 /help 查看可用命令
3. 探索 Skills 系统，给 AI 安装额外的能力
4. 配置 Heartbeat，让 AI 主动为你做定时任务

OpenClaw 的真正魅力在于它的可定制性和扩展性。安装只是开始，接下来的"入门指南"会带你快速上手核心功能。