OpenClaw 部署教程 - Linux 篇（2026 终极版）

更新时间：2026-03-17 阅读时间：约 20 分钟难度等级：初级实测环境：Ubuntu 22.04 LTS / Node.js v22.12.0 / Python 3.10.12

部署前必读

电气安全

服务器供电：确保使用稳压电源，电压波动 < ±5%
散热要求：工作环境温度 15-35℃，湿度 40-60%
ESD 防护：接触服务器前佩戴防静电手环

系统安全

root 权限：生产环境建议使用普通用户 + sudo
防火墙：仅开放必要端口（默认 18789）
备份：部署前备份重要数据

网络要求

带宽：≥ 10Mbps（推荐 100Mbps+）
代理：中国大陆用户需配置 Clash 代理（端口 7890）
域名：可选，用于 HTTPS 访问

内存要求

最低：2GB（需配置 Swap）
推荐：4GB+（无需 Swap）
生产：8GB+（流畅运行）

2GB 内存服务器必须配置 Swap，否则 OOM（内存溢出）会导致安装失败。

系统要求

项目	最低要求	推荐配置	生产环境
操作系统	Ubuntu 20.04	Ubuntu 22.04 LTS	Ubuntu 22.04.3 LTS
CPU	1 核心	2 核心+	4 核心+
内存	2GB	4GB+	8GB+
磁盘	5GB	10GB SSD	20GB+ NVMe SSD
Node.js	v18+	v20+	v22.12.0 (最新 LTS)
Python	3.8+	3.10+	3.10.12 (系统自带)
Git	任意版本	最新	2.34.1+

说明：

Node.js v22 是 OpenClaw 官方推荐版本，兼容性最佳
2GB 内存服务器必须配置 2GB+ Swap
Git 用于克隆仓库和管理依赖，必装

快速安装

方法一：官方一键安装脚本

# ============ 步骤 1：系统更新及基础依赖 ============
sudo apt update
sudo apt install -y git curl

# ============ 步骤 2：执行官方安装脚本 ============
curl -fsSL https://openclaw.ai/install.sh | bash

# ============ 步骤 3：验证安装 ============
openclaw --version

预计耗时：5-10 分钟（取决于网络）

注意事项：

国内服务器若安装失败，需先配置代理
2GB 内存可能出现 OOM，需先配置 Swap（见下文）
安装过程耗时较长，请耐心等待

方法二：手动安装（可控性更强）

适合需要精确控制版本的生产环境。

步骤 1：安装 Git

sudo apt update
sudo apt install -y git

# 验证版本
git --version # 应显示：git version 2.34.1+

步骤 2：安装 NVM（Node 版本管理器）

国内服务器（使用 Gitee 镜像源）：

curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash

海外服务器（使用官方源）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

步骤 3：重新加载环境变量

source ~/.bashrc

# 验证 NVM 已安装
command -v nvm # 应输出：nvm

步骤 4：安装 Node.js 22

# 安装 Node.js 22（最新 LTS）
nvm install 22

# 设置为默认版本
nvm alias default 22

# 验证版本
node --version # 应显示：v22.12.0
npm --version # 应显示：10.9.0+

步骤 5：安装 OpenClaw

# 全局安装
npm install -g openclaw

# 验证安装
openclaw --version # 应显示：openclaw/x.x.x linux-x64 node-v22.12.0

初始化配置（Onboarding 向导）

安装成功后会自动进入初始化向导，按以下步骤操作。

步骤详解

步骤	提示内容	操作	说明
1	安全提示确认	输入 `Yes`	知晓权限风险
2	选择部署模式	选择 `QuickStart`	后续可补充配置
3	选择模型服务商	选择 `OpenAI`	或其他服务商
4	模型授权	复制链接到浏览器	登录账号完成授权
5	通信通道配置	选择 `Skip for now`	后续可配置
6	技能配置	选择 `No`	暂不配置
7	Hooks 配置	选择 `Session`	暂不启用
8	启动方式	选择 `TUI`	终端聊天界面
9	测试	输入 `Hello`	确认安装成功

详细流程

安全提示确认：

OpenClaw is a hobby project and still in beta...
Do you want to continue? (Yes/No)
> Yes

选择部署模式：

Select deployment mode:
 1) QuickStart (推荐)
 2) Advanced
> 1

选择模型服务商：

Select model provider:
 1) OpenAI
 2) Anthropic
 3) Google
 4) Custom
> 1

模型授权：

Please visit the following URL to authorize:
https://openclaw.ai/auth/xxxxx

Enter the authorization code:
> [粘贴授权码]

5-7. 跳过可选配置：

Configure communication channels? (y/N) > N
Configure skills? (y/N) > N
Configure hooks? (y/N) > N

启动 TUI 测试：

Start OpenClaw in TUI mode? (Y/n) > Y

# 出现聊天界面后输入：
> Hello

# 应收到 AI 回复

退出 TUI：

按 Ctrl+C 退出

高级配置

1. 配置 Swap（2GB 内存服务器必须）

检查当前 Swap：

free -h
# 如果 Swap 为 0B，需要配置

创建 2GB Swap：

# 1. 创建 swap 文件
sudo fallocate -l 2G /swapfile

# 2. 设置权限（仅 root 可读写）
sudo chmod 600 /swapfile

# 3. 格式化为 swap
sudo mkswap /swapfile

# 4. 启用 swap
sudo swapon /swapfile

# 5. 验证
swapon --show
# 应显示：/swapfile file 2G 0B

永久生效（重启后自动挂载）：

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

调整 Swappiness（降低使用 swap 的频率）：

# 查看当前值（默认 60）
cat /proc/sys/vm/swappiness

# 修改为 10（更保守）
sudo sysctl vm.swappiness=10

# 永久生效
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

2. 配置 API Keys

编辑配置文件：

nano ~/.openclaw/workspace/TOOLS.md

添加以下内容（替换为你的 Key）：

## API Keys

### 阿里云百炼（推荐，国内访问快）
- API Key: `sk-sp-xxxxxxxxxxxxxxxx`
- 模型: qwen3.5-plus, qwen3-max-2026-01-23
- 状态: 已配置
- 用途: 代码生成/审查/优化

### OpenAI（备选）
- API Key: `sk-proj-xxxxxxxxxxxxxxxx`
- 模型: gpt-4o, gpt-4-turbo

### 火山引擎（备选）
- API Key: `xxxxxxxxxxxxxxxx`
- 模型: doubao-seed-2.0-code

Key 获取地址：

阿里云百炼：https://bailian.console.aliyun.com/
OpenAI：https://platform.openai.com/api-keys
火山引擎：https://www.volcengine.com/

3. 配置 Clash 代理（中国大陆用户必须）

检查 Clash 是否运行：

ps aux | grep clash
# 应看到：clash -d ~/.config/clash/

如未运行，启动 Clash：

# 后台启动 Clash
nohup clash -d ~/.config/clash/ > /tmp/clash.log 2>&1 &

# 验证端口（7890 应处于 LISTEN 状态）
netstat -tlnp | grep 7890

配置环境变量：

# 临时生效
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 永久生效（添加到 ~/.bashrc）
echo 'export HTTP_PROXY=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export HTTPS_PROXY=http://127.0.0.1:7890' >> ~/.bashrc
source ~/.bashrc

验证代理：

curl -x http://127.0.0.1:7890 -I https://www.google.com
# 应返回：HTTP/2 200

systemd 服务配置（开机自启）

创建服务文件

sudo nano /etc/systemd/system/openclaw-gateway.service

完整配置内容

[Unit]
Description=OpenClaw Gateway Service
Documentation=https://docs.openclaw.ai
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/root/.openclaw/workspace

# 环境变量（代理配置）
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"

# Node.js 内存优化
Environment="NODE_OPTIONS=--max-old-space-size=2048"

# 启动命令
ExecStart=/usr/local/bin/openclaw gateway start
ExecReload=/bin/kill -HUP $MAINPID

# 重启策略
Restart=always
RestartSec=10

# 资源限制
LimitNOFILE=65535
LimitNPROC=4096

# 日志配置
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-gateway

[Install]
WantedBy=multi-user.target

启用服务

# 重载 systemd 配置
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable openclaw-gateway

# 启动服务
sudo systemctl start openclaw-gateway

# 查看状态（应显示 Active: active (running)）
sudo systemctl status openclaw-gateway

日志管理

# 实时查看日志
sudo journalctl -u openclaw-gateway -f

# 查看最近 100 行
sudo journalctl -u openclaw-gateway -n 100

# 按时间筛选
sudo journalctl -u openclaw-gateway --since "2026-03-17 10:00:00"

# 清理旧日志（保留 7 天）
sudo journalctl -u openclaw-gateway --vacuum-time=7d

# 限制日志大小（最多 100MB）
sudo journalctl -u openclaw-gateway --vacuum-size=100M

故障排查

问题 1：安装过程中 OOM（内存溢出）

症状：安装过程中服务器卡死，SSH 断开连接

诊断：

# 查看内存使用
free -h

# 查看 OOM 日志
dmesg | grep -i "out of memory"

解决方案：

# 1. 配置 Swap（见上文）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 2. 重启安装
npm install -g openclaw

问题 2：Node.js 版本不兼容

症状：Error: Unsupported Node.js version

解决方案：

# 1. 查看当前版本
node --version

# 2. 使用 NVM 切换到 v22
nvm install 22
nvm use 22
nvm alias default 22

# 3. 重新安装 OpenClaw
npm uninstall -g openclaw
npm install -g openclaw

问题 3：网络超时

症状：Error: connect ETIMEDOUT

诊断步骤：

# 1. 测试基础网络
ping -c 4 www.baidu.com

# 2. 测试代理
curl -x http://127.0.0.1:7890 -I https://www.google.com

# 3. 检查 Clash 状态
ps aux | grep clash
netstat -tlnp | grep 7890

解决方案：

# 启动 Clash
nohup clash -d ~/.config/clash/ > /tmp/clash.log 2>&1 &

# 配置环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

问题 4：初始化向导卡住

症状：卡在某个步骤无法继续

解决方案：

# 1. 退出向导（Ctrl+C）

# 2. 清除配置重新初始化
rm -rf ~/.openclaw/config.json
openclaw init

# 3. 或者手动编辑配置
nano ~/.openclaw/config.json

问题 5：TUI 界面无法启动

症状：选择 TUI 后黑屏或闪退

解决方案：

# 1. 检查终端兼容性
echo $TERM # 应显示：xterm-256color 或 screen

# 2. 设置终端类型
export TERM=xterm-256color

# 3. 重新启动
openclaw start

# 4. 或者使用 Web UI
openclaw gateway start
# 浏览器访问：http://localhost:18789

验证安装

逐项检查，全部通过才算部署成功：

# □ 1. 检查版本号
openclaw --version
# 期望输出：openclaw/x.x.x linux-x64 node-v22.12.0

# □ 2. 检查网关状态
openclaw gateway status
# 期望输出：Gateway is running

# □ 3. 检查端口监听
netstat -tlnp | grep 18789
# 期望输出：tcp6 0 0 :::18789 :::* LISTEN

# □ 4. 测试本地访问
curl http://localhost:18789/health
# 期望输出：{"status":"ok"}

# □ 5. 发送测试消息
openclaw message send "Hello OpenClaw!"
# 期望：收到 AI 回复

# □ 6. 检查日志无 ERROR
sudo journalctl -u openclaw-gateway -n 50 | grep ERROR
# 期望：无输出

# □ 7. 检查 systemd 服务状态
sudo systemctl status openclaw-gateway
# 期望输出：Active: active (running)

# □ 8. 测试开机自启
sudo reboot
# 重启后检查：
sudo systemctl status openclaw-gateway
# 期望：服务自动启动

成功标志：

8 项检查全部通过
日志无 ERROR 级别错误
服务重启后自动恢复

性能优化

1. Node.js 内存优化

编辑 systemd 服务：

sudo nano /etc/systemd/system/openclaw-gateway.service

根据服务器内存调整配置：

# 4GB 内存服务器
Environment="NODE_OPTIONS=--max-old-space-size=2048"

# 8GB 内存服务器
Environment="NODE_OPTIONS=--max-old-space-size=4096"

# 16GB 内存服务器
Environment="NODE_OPTIONS=--max-old-space-size=8192"

重载并重启：

sudo systemctl daemon-reload
sudo systemctl restart openclaw-gateway

2. 定期清理缓存

创建清理脚本：

nano ~/cleanup-openclaw.sh

脚本内容：

#!/bin/bash
echo "开始清理 OpenClaw 缓存..."

# 清理 npm 缓存
npm cache clean --force
echo "npm 缓存已清理"

# 清理系统日志（保留 7 天）
sudo journalctl --vacuum-time=7d
echo "系统日志已清理"

# 清理 OpenClaw 日志（保留 100MB）
sudo journalctl -u openclaw-gateway --vacuum-size=100M
echo "OpenClaw 日志已清理"

# 清理临时文件
rm -rf /tmp/openclaw-*
echo "临时文件已清理"

echo "清理完成"

赋予执行权限并运行：

chmod +x ~/cleanup-openclaw.sh
~/cleanup-openclaw.sh

添加到 crontab（每周日凌晨 3 点自动清理）：

crontab -e
# 添加：
0 3 * * 0 /home/ubuntu/cleanup-openclaw.sh

更新日志

版本	日期	更新内容
v3.0	2026-03-17	整合官方一键脚本 + NVM 安装 + 初始化向导详解
v2.0	2026-03-17	增加电气安全警示、精准参数、故障排查流程图
v1.5	2026-03-10	增加 systemd 服务配置、性能优化章节
v1.0	2026-03-01	初始版本发布

最后更新：2026-03-17 作者：OpenClaw 社区 许可：MIT

OpenClaw 部署教程 - Linux 篇（2026 终极版）

部署前必读

电气安全

系统安全

网络要求

内存要求

系统要求

快速安装

方法一：官方一键安装脚本

方法二：手动安装（可控性更强）

步骤 1：安装 Git

步骤 2：安装 NVM（Node 版本管理器）

步骤 3：重新加载环境变量

步骤 4：安装 Node.js 22

步骤 5：安装 OpenClaw

初始化配置（Onboarding 向导）

步骤详解

详细流程

高级配置

1. 配置 Swap（2GB 内存服务器必须）

2. 配置 API Keys

3. 配置 Clash 代理（中国大陆用户必须）

systemd 服务配置（开机自启）

创建服务文件

完整配置内容

启用服务

日志管理

故障排查

问题 1：安装过程中 OOM（内存溢出）

问题 2：Node.js 版本不兼容

问题 3：网络超时

问题 4：初始化向导卡住

问题 5：TUI 界面无法启动

验证安装

性能优化

1. Node.js 内存优化

2. 定期清理缓存

更多资源

官方文档

社区教程

其他平台部署

更新日志