阶段一：入门 | 预计用时：45分钟
学习目标
完成本课后，你将能够：
- 成功安装OpenClaw
- 理解安装过程发生了什么
- 运行初始化向导
- 验证安装成功
理论知识
2.1 系统要求
| 要求 | 说明 |
|---|---|
| Node.js | 24推荐，22.14+兼容 |
| 操作系统 | macOS / Linux / Windows |
| 内存 | 至少4GB |
| 磁盘 | 至少1GB可用空间 |
检查Node版本：
node --version
# 预期输出：v24.x.x 或 v22.14+
2.2 安装方式对比
| 方式 | 命令 | 适用场景 | 推荐度 |
|---|---|---|---|
| 官方脚本 | curl -fsSL https://openclaw.ai/install.sh | bash | macOS/Linux | ⭐⭐⭐⭐⭐ |
| PowerShell | iwr -useb https://openclaw.ai/install.ps1 | iex | Windows | ⭐⭐⭐⭐⭐ |
| npm | npm install -g openclaw@latest | 全平台 | ⭐⭐⭐⭐ |
2.3 安装过程详解
安装脚本执行流程：
1. 检测操作系统
└── Linux / macOS / Windows
2. 检查Node.js版本
└── 要求 >= 22.14
3. 下载OpenClaw包
└── 从npm获取最新版本
4. 安装到全局
└── /usr/local/bin/openclaw
└── 或 ~/.npm-global/bin/openclaw
5. 配置PATH
└── 确保命令可直接使用
6. 创建配置目录
└── ~/.openclaw/
2.4 目录结构
安装完成后，OpenClaw会在以下位置创建文件：
~/.openclaw/ # 主目录（OPENCLAW_HOME）
│
├── openclaw.json # 主配置文件
│
├── workspace/ # 默认工作空间
│ ├── AGENTS.md # Agent行为指南
│ ├── SOUL.md # Agent人格设定
│ ├── USER.md # 用户信息
│ ├── MEMORY.md # 长期记忆
│ └── memory/ # 记忆文件目录
│
├── agents/ # Agent目录
│ └── main/ # 默认Agent
│ ├── agent/ # Agent配置
│ │ └── auth-profiles.json
│ └── sessions/ # 会话存储
│
├── skills/ # 共享Skills
│
└── logs/ # 日志目录
└── gateway.log
2.5 初始化向导
命令：
openclaw onboard --install-daemon
向导步骤：
1. Gateway配置
└── 端口：默认18789
└── 认证：生成Token
2. 模型选择
└── 选择默认AI模型
└── 配置API Key
3. 通道配置（可选）
└── Telegram Bot Token
└── 其他Channel
4. 服务安装
└── 安装为系统服务
└── 开机自启动
验证步骤
验证1：检查Node版本
node --version
# 预期输出：v24.x.x 或 v22.14+
# 如果版本过低，使用nvm升级
nvm install 24
nvm use 24
验证2：检查安装
openclaw --version
# 预期输出：OpenClaw 2026.3.23-2 (xxxxx)
openclaw --help
# 预期输出：显示所有可用命令
验证3：检查目录结构
ls -la ~/.openclaw/
# 预期输出：看到配置文件和目录
cat ~/.openclaw/openclaw.json
# 预期输出：配置文件内容
实战任务
任务1：安装OpenClaw
macOS/Linux：
# 方式1：官方脚本（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash
# 方式2：npm安装
npm install -g openclaw@latest
# 验证安装
openclaw --version
Windows（PowerShell）：
# 官方脚本
iwr -useb https://openclaw.ai/install.ps1 | iex
# 验证安装
openclaw --version
完成标准：
- 安装过程无错误
-
openclaw --version显示正确版本 -
openclaw --help显示帮助信息
任务2：运行初始化向导
# 运行初始化向导
openclaw onboard --install-daemon
# 向导会引导你完成：
# 1. Gateway配置
# 2. 模型选择和API Key
# 3. 可选Channel配置
# 4. 安装系统服务
配置建议：
| 配置项 | 建议值 | 说明 |
|---|---|---|
| Gateway端口 | 18789 | 默认即可 |
| Gateway Token | 自动生成 | 记住这个Token |
| 模型 | DeepSeek | 性价比高 |
| API Key | 你的Key | 从平台获取 |
| Channel | 暂时跳过 | 第5课配置 |
完成标准：
- 向导运行成功
- Gateway服务启动
- 配置文件生成
任务3：检查Gateway服务
# 查看服务状态
openclaw gateway status
# 预期输出：
# Gateway is running on port 18789
# 如果未启动，手动启动
openclaw gateway start
完成标准：
- Gateway状态为running
- 端口18789被监听
任务4：验证配置文件
# 查看配置目录
ls -la ~/.openclaw/
# 查看配置文件
cat ~/.openclaw/openclaw.json
# 验证配置
openclaw config validate
完成标准：
- 配置文件存在
- 配置格式正确
- 验证通过
常见问题
问题1：Node版本过低
症状：
Error: OpenClaw requires Node.js 22.14 or higher
解决方案：
# 使用nvm安装Node 24
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
nvm alias default 24
问题2：权限不足
症状：
npm ERR! Error: EACCES: permission denied
解决方案：
# 方式1：修复npm权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
# 方式2：使用nvm管理Node
nvm install 24
nvm use 24
问题3：安装后命令找不到
症状：
bash: openclaw: command not found
解决方案：
# 检查npm全局路径
npm config get prefix
# 添加到PATH（bash）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 添加到PATH（zsh）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
问题4：Gateway启动失败
症状：
Error: Port 18789 is already in use
解决方案：
# 方式1：查找并结束占用进程
lsof -i :18789
kill -9 <PID>
# 方式2：使用其他端口
openclaw gateway --port 18790
# 方式3：强制启动（结束占用进程）
openclaw gateway --force
课后思考
思考题
-
为什么推荐使用官方脚本安装？
点击查看参考答案
- 自动检测系统和依赖
- 自动配置PATH
- 处理权限问题
- 提供卸载脚本
- 更新更方便
-
~/.openclaw/目录下各子目录的作用是什么？点击查看参考答案
目录 作用 openclaw.json主配置文件 workspace/工作空间，存储记忆和配置 agents/Agent配置和会话 skills/共享技能包 logs/日志文件 -
Gateway作为服务运行和前台运行有什么区别？
点击查看参考答案
方式 优点 缺点 服务模式 后台运行、开机自启 调试不便 前台运行 可见日志、调试方便 关闭终端就停止 生产环境用服务模式，开发调试用前台运行。
扩展阅读
| 资源 | 说明 |
|---|---|
| 安装文档 | 官方安装指南 |
| 环境变量 | 环境变量配置 |
| 配置文件 | 配置文件详解 |
课时：第2课 / 共29课 阶段：入门 / 共5阶段
