主题
安装与部署
本文带你在 Linux 服务器上完成 OpenClaw 的安装、初始化和服务化部署。整流程约 10 分钟。
前置要求
| 项目 | 要求 |
|---|---|
| Node.js | 22.22.3+、24.15+ 或 25.9+（推荐 24.x） |
| 操作系统 | Linux（推荐 Ubuntu 20.04+ / Debian 12+）、macOS、Windows (WSL2) |
| 内存 | 最低 1GB，推荐 2GB+ |
| 磁盘 | 1GB 可用空间 |
| 网络 | 能访问 npm 仓库和 AI 模型 API |
检查 Node.js 版本
bash
node --version如果未安装或版本过低，推荐用 nvm 管理 Node 版本：
bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24Windows 用户注意
Windows 原生推荐使用 Windows Hub App，或通过 WSL2 部署 Gateway。PowerShell 一键安装脚本也能用，但日常运维建议在 Linux 环境下进行。
安装步骤
方法一：一键安装（推荐）
bash
curl -fsSL https://openclaw.ai/install.sh | bash脚本会自动检测系统、安装 Node.js（如需要）、安装 OpenClaw 并启动引导向导。
跳过引导向导，只安装 CLI：
bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard方法二：npm 全局安装
适合已有 Node.js 环境的用户：
bash
npm install -g openclaw@latest验证安装
bash
openclaw --version找不到 openclaw 命令？
通常是 npm 全局 bin 目录不在 PATH 中。检查并修复：
bash
npm prefix -g # 查看全局安装路径
echo "$PATH" # 查看当前 PATH
# 把 npm 全局 bin 目录加入 PATH（通常在 ~/.bashrc 中）
export PATH="$(npm prefix -g)/bin:$PATH"方法三：Docker 部署
bash
docker pull openclaw/openclaw:latest适合容器化环境，详见 Docker 部署文档。
初始化配置
安装完成后，运行引导向导：
bash
openclaw onboard --install-daemon向导会引导你完成：
- 选择模型提供商 —— DeepSeek、Anthropic、OpenAI、Google 等
- 填写 API Key —— 你的模型提供商 API 密钥
- 设置工作区路径 —— Agent 的工作目录（默认
~/.openclaw/workspace） - 安装守护进程 ——
--install-daemon会自动配置 systemd 服务
如果跳过向导，后续可随时运行 openclaw configure 交互式配置。
配置为 systemd 服务（开机自启）
--install-daemon 会自动执行以下操作，你也可以手动完成：
bash
# 安装 systemd user 服务
openclaw gateway install
# 启用并启动服务
systemctl --user enable --now openclaw-gateway.service
# 让服务在用户未登录时继续运行（无头服务器必备）
sudo loginctl enable-linger $(whoami)什么是 enable-linger？
Linux systemd 的 user 服务默认在用户登出后停止。enable-linger 让服务在用户未登录时继续运行 —— 对于无桌面环境的云服务器至关重要。
验证安装
依次执行以下命令确认一切正常：
bash
# 1. 确认 CLI 可用
openclaw --version
# 2. 系统诊断
openclaw doctor
# 3. 查看 Gateway 状态
openclaw gateway status
# 4. 查看实时日志
openclaw logs --follow健康状态应显示：
Runtime: runningConnectivity probe: ok- Gateway 监听端口
18789
测试对话
bash
openclaw dashboard在浏览器中打开的 Control UI 里发送一条消息，收到 AI 回复即表示一切正常。
Gateway 常用运维命令
bash
openclaw gateway status # 查看运行状态
openclaw gateway status --deep # 深度扫描（含系统服务检测）
openclaw gateway restart # 重启 Gateway
openclaw gateway stop # 停止 Gateway
openclaw logs --follow # 实时日志
openclaw doctor # 诊断检查
openclaw doctor --fix # 自动修复配置问题常见安装问题
node:sqlite 报错
OpenClaw 依赖 node:sqlite，需要 Node.js 22.22.3+ 或 24.15+。
bash
node --version # 确认版本 >= 22.22.3npm 安装权限报错（EACCES）
不要用 sudo npm install -g。正确做法：
bash
# 方法 1：用 nvm 管理（推荐）
nvm install 24
# 方法 2：修改 npm 全局目录权限
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrcGateway 无法启动
bash
# 查看详细错误
openclaw doctor
# 检查配置文件
openclaw config schema # 查看 JSON Schema，确认配置格式正确
# 查看完整日志
journalctl --user -u openclaw-gateway.service -n 50 --no-pager配置文件格式
OpenClaw 配置文件使用 JSON5 格式（支持注释和尾逗号），不是严格 JSON。如果 Gateway 启动失败，先运行 openclaw doctor 定位问题。
端口 18789 被占用
bash
# 查看占用端口的进程
ss -tlnp | grep 18789
# 或
lsof -i :18789
# 使用 --force 强制杀死占用进程并启动（注意：需要 run 子命令）
openclaw gateway run --force下一步
安装完成！接下来配置 Gateway，接入 AI 模型和聊天通道：Gateway 配置 →
加载练习题中...
🎯 本章要点
- 要求 Node.js >=22.22.3 或 >=24.15.0 或 >=25.9.0
- 推荐使用 nvm 管理 Node.js 多版本，两行命令即可切换