跳到主要内容

🐧 Linux 原生安装

直接在 Linux 系统上安装 OpenClaw，享受原生性能和灵活性

⚠️ 重要提醒​

强烈建议使用 Docker 方式安装！ 原生安装可能带来的风险：

  • ❌ 难以彻底停止程序
  • ❌ 获得系统完整权限
  • ❌ 依赖安装污染系统环境
  • ❌ 文件散落，难以卸载

如果您追求便捷和安全，请参考 云服务器安装 使用 Docker 方式。

📋 前置要求​

支持的 Linux 发行版​

  • Ubuntu 18.04+
  • CentOS 7+
  • Debian 9+
  • Fedora 28+

系统要求​

  • CPU：2 核心或以上
  • 内存：4GB 或以上
  • 硬盘：10GB 或以上可用空间
  • 网络：稳定的互联网连接

必需软件​

  • Node.js 18+ 和 npm
  • Git（用于克隆仓库）
  • Python 3.8+（可选，某些插件需要）

🔧 环境准备​

Ubuntu/Debian 系统​

安装 Node.js 和 npm​

# 更新包索引
sudo apt update

# 安装 Node.js 18.x
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 验证安装
node --version
npm --version

安装 Git​

sudo apt install -y git

安装 Python（可选）​

sudo apt install -y python3 python3-pip

CentOS/RHEL 系统​

安装 Node.js 和 npm​

# 安装 Node.js 18.x
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

安装 Git​

sudo yum install -y git

安装 Python（可选）​

sudo yum install -y python3 python3-pip

📦 安装步骤​

步骤 1：克隆 OpenClaw 仓库​

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git

# 进入项目目录
cd openclaw

步骤 2：安装依赖​

# 安装项目依赖
npm install

# 验证依赖安装
npm list

步骤 3：配置环境变量​

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量
nano .env

在 .env 文件中填入必要的配置：

# 飞书应用配置
FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxx
FEISHU_ENCRYPT_KEY=xxxxxx

# 智谱 AI 配置
ZHIPU_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 模型配置
OPENCLAW_AGENT_MODEL=glm-4.7

# Gateway 配置
GATEWAY_PORT=18789
GATEWAY_MODE=local

步骤 4：启动服务​

# 开发模式启动
npm start

# 生产模式启动（推荐）
npm run build
npm run serve

步骤 5：验证安装​

# 检查服务状态
curl http://localhost:18789/health

# 查看日志
tail -f logs/openclaw.log

🎯 使用 systemd 管理服务（推荐）​

创建 systemd 服务文件​

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

填入以下内容：

[Unit]
Description=OpenClaw AI Automation Service
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username/openclaw
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10
StandardOutput=append:/var/log/openclaw.log
StandardError=append:/var/log/openclaw-error.log

[Install]
WantedBy=multi-user.target

启用并启动服务​

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable openclaw

# 启动服务
sudo systemctl start openclaw

# 查看服务状态
sudo systemctl status openclaw

# 查看服务日志
sudo journalctl -u openclaw -f

🔄 配置 OpenClaw​

配置飞书应用​

参考配置指南：

配置模型​

根据需要配置不同的 AI 模型：

# 编辑配置文件
nano ~/.openclaw/openclaw.json

🐛 常见问题排查​

问题 1：Node.js 版本过低​

症状：启动时提示 Node.js 版本不支持

解决方案：

# 使用 nvm 安装最新版 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

问题 2：端口被占用​

症状：启动失败，提示端口 18789 被占用

解决方案：

# 查找占用端口的进程
sudo lsof -i :18789

# 杀死进程
sudo kill -9 <PID>

# 或修改配置使用其他端口
nano .env
# 修改 GATEWAY_PORT=18888

问题 3：权限不足​

症状：无法启动或读写文件

解决方案：

# 使用正确的用户启动服务
sudo -u your_username npm start

# 或修改文件权限
sudo chown -R your_username:your_username /home/your_username/openclaw

问题 4：依赖安装失败​

症状：npm install 失败

解决方案：

# 清除 npm 缓存
npm cache clean --force

# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json

# 重新安装
npm install

# 或使用淘宝镜像
npm install --registry=https://registry.npmmirror.com

📚 升级和更新​

升级 OpenClaw​

# 停止服务
sudo systemctl stop openclaw

# 拉取最新代码
cd /home/your_username/openclaw
git pull origin main

# 安装新依赖
npm install

# 重新构建
npm run build

# 启动服务
sudo systemctl start openclaw

🗑️ 卸载​

停止并禁用服务​

sudo systemctl stop openclaw
sudo systemctl disable openclaw
sudo rm /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload

删除文件​

# 删除项目目录
rm -rf /home/your_username/openclaw

# 删除配置文件
rm -rf ~/.openclaw

# 删除日志文件
sudo rm /var/log/openclaw.log /var/log/openclaw-error.log

💡 性能优化建议​

使用 PM2 管理进程​

# 安装 PM2
sudo npm install -g pm2

# 启动服务
pm2 start npm --name "openclaw" -- start

# 设置开机自启
pm2 startup
pm2 save

配置 Nginx 反向代理​

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

配置防火墙​

# Ubuntu/Debian
sudo ufw allow 18789/tcp
sudo ufw enable

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

📚 相关文档​

🆘 获取帮助​

如果您在安装过程中遇到问题，可以通过以下方式获取帮助：