OpenClaw Linux 服务器安装部署教程

为什么在 Linux 上部署 OpenClaw？

Linux 是运行 OpenClaw 最常见也最推荐的平台。绝大多数云服务器默认运行 Linux 系统，生产环境部署几乎都选择 Linux。相比 macOS 或 Windows：

• 服务器生态成熟 — 所有主流云厂商（阿里云、腾讯云、AWS、Hetzner）都提供 Linux 服务器，价格低、选择多。
• Docker 原生支持 — Docker 本身就是为 Linux 设计的，在 Linux 上运行效率最高、兼容性最好，不需要虚拟机层。
• 7x24 小时运行 — 服务器持续在线，AI 智能体随时可用。不像本地电脑关机就停。
• 公网 IP — 云服务器自带公网 IP，Telegram 和 Discord Webhook 回调直接可用，无需内网穿透。

系统要求

如果只使用 Web UI 聊天（无 Telegram/Discord），不需要公网 IP。但大多数用户都会接入聊天平台，因此公网 IP 是实际部署中的必备条件。

Ubuntu / Debian 安装（推荐）

Ubuntu 和 Debian 是部署 OpenClaw 最受欢迎的 Linux 发行版。社区资源丰富，教程和文档最多，Docker 安装最简单。以下是完整的安装步骤：

第一步：更新系统

sudo apt update && sudo apt upgrade -y

更新系统包列表并升级已安装的包。保持系统最新可以避免安全漏洞和兼容性问题。

第二步：安装 Docker

sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker
docker --version

docker.io 是 Ubuntu/Debian 官方仓库中的 Docker 包，docker-compose-plugin 提供 docker compose 命令。enable --now 同时启用开机自启和立即启动。

第三步：配置 Docker 权限

sudo usermod -aG docker $USER
# 重新登录终端使 docker 组生效（或执行 newgrp docker）
docker ps    # 验证无需 sudo 即可运行

将当前用户加入 docker 组，避免每次运行 Docker 命令都需要 sudo。

第四步：拉取 OpenClaw 镜像

docker pull ghcr.io/openclaw/openclaw:latest

镜像托管在 GitHub Container Registry（ghcr.io），大小约 500MB。:latest 标签指向最新稳定版。不要使用 :main 标签（开发分支，可能有 Bug）。

第五步：创建配置目录和配置文件

mkdir -p ~/.openclaw/credentials
chmod 777 ~/.openclaw
chmod 777 ~/.openclaw/credentials

credentials 目录用于 Telegram dmPolicy: "pairing" 模式存储配对凭证。如果该目录不存在，Telegram 插件会静默丢弃所有消息。权限设为 777 是因为容器内以 node 用户（uid 1000）运行，宿主机用户 uid 可能不同。

第六步：编写配置文件

cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-v1-你的OpenRouter密钥"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "你的Telegram Bot Token",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.6"
      }
    }
  },
  "gateway": {
    "auth": {
      "token": "替换为随机UUID"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}
EOF

配置文件详细说明请参考 Docker 部署教程 中的"配置文件结构详解"章节。

第七步：启动 OpenClaw 容器

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  --memory=2g \
  --memory-swap=3g \
  --restart unless-stopped \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

第八步：配置防火墙

# 允许 HTTPS（反向代理用）
sudo ufw allow 443/tcp

# 允许 HTTP（Caddy 自动跳转到 HTTPS）
sudo ufw allow 80/tcp

# 启用防火墙（如果尚未启用）
sudo ufw enable

# 查看防火墙状态
sudo ufw status

不要直接暴露 18789 端口到公网 — 应通过反向代理（Caddy/Nginx）提供 HTTPS 访问。

CentOS / RHEL / Rocky Linux 安装

CentOS Stream 9、Rocky Linux 9、AlmaLinux 9 以及 RHEL 9 的安装步骤基本相同。主要区别在于包管理器使用 dnf（或 yum）。

第一步：更新系统

sudo dnf update -y

第二步：安装 Docker

# 添加 Docker 官方仓库
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动并设置开机自启
sudo systemctl enable --now docker

# 添加用户到 docker 组
sudo usermod -aG docker $USER

第三步：处理 SELinux（重要）

# 查看 SELinux 状态
getenforce

# 如果是 Enforcing，需要配置 Docker 与 SELinux 兼容
# 方案一：为挂载目录添加 SELinux 标签（推荐）
chcon -Rt svirt_sandbox_file_t ~/.openclaw

# 方案二：在 docker run 中使用 :Z 后缀
# -v ~/.openclaw:/home/node/.openclaw:Z

# 方案三：临时设为 Permissive（不推荐用于生产）
# sudo setenforce 0

CentOS/RHEL 默认启用 SELinux，如果不处理，Docker 容器可能无法读取挂载的配置目录。这是 CentOS 部署中最常见的问题之一。

后续步骤

拉取镜像、创建配置目录、编写配置文件、启动容器的步骤与 Ubuntu 完全相同（见上方）。唯一的区别是防火墙命令：

# CentOS 防火墙（firewalld）
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

配置文件概述

OpenClaw 从 ~/.openclaw/openclaw.json 读取配置。配置文件是标准 JSON 格式，包含以下主要部分：

• models.providers — AI 模型 API 密钥（OpenRouter、OpenAI、Anthropic 等）
• channels — 聊天渠道配置（Telegram、Discord、WhatsApp 等）
• plugins.entries — 插件启用开关（必须同时启用渠道和插件）
• agents.defaults — 默认 AI 模型和行为设置
• gateway.auth — 网关认证 Token（必须是对象格式）

完整的配置文件结构、各字段详解和常见错误，请参考 Docker 部署教程 中的"配置文件结构详解"章节。

反向代理和 HTTPS 配置

生产部署必须配置 HTTPS — Telegram Webhook 强制要求 HTTPS，浏览器 Web UI 也需要 HTTPS 才能安全使用。推荐使用 Caddy，它会自动申请和续期 Let's Encrypt SSL 证书。

Caddy（推荐）

# Ubuntu/Debian 安装 Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | \
  sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | \
  sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

# CentOS/RHEL 安装 Caddy
sudo dnf install -y 'dnf-command(copr)'
sudo dnf copr enable @caddy/caddy
sudo dnf install -y caddy

编辑 Caddy 配置文件：

# /etc/caddy/Caddyfile
your-domain.com {
    reverse_proxy localhost:18789
}

# 启动 Caddy
sudo systemctl enable --now caddy

# 重载配置（修改 Caddyfile 后）
sudo systemctl reload caddy

Caddy 会自动申请 SSL 证书、自动续期、自动将 HTTP 重定向到 HTTPS。全程无需手动管理证书，是最简单的方案。

Nginx（替代方案）

# 安装 Nginx 和 Certbot
sudo apt install -y nginx certbot python3-certbot-nginx  # Ubuntu/Debian
# sudo dnf install -y nginx certbot python3-certbot-nginx  # CentOS

# Nginx 配置 /etc/nginx/sites-available/openclaw
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# 启用站点配置
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# 申请 SSL 证书
sudo certbot --nginx -d your-domain.com

Nginx 配置相对复杂，但灵活性更高。WebSocket 连接需要额外的 Upgrade 和 Connection 头。Certbot 负责自动续期证书。

进程管理

Docker 容器设置 --restart unless-stopped 后会自动重启。但如果你想更精细地管理，可以使用 systemd 或 PM2。

systemd 服务文件（推荐）

# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw AI Gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/docker start openclaw
ExecStop=/usr/bin/docker stop openclaw
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

# 启用 systemd 服务
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

# 查看状态
sudo systemctl status openclaw

使用 systemd 管理的好处是可以用标准的 systemctl start/stop/status 命令，并且服务器重启后自动启动。

PM2（Node.js 进程管理器）

如果你在同一台服务器上还运行其他 Node.js 应用，可以使用 PM2 统一管理：

# 安装 PM2
npm install -g pm2

# 用 PM2 管理 Docker 容器
pm2 start "docker start -a openclaw" --name openclaw
pm2 save
pm2 startup    # 开机自启

云服务器推荐（中国用户）

选择云服务器时需要考虑：价格、网络质量（能否访问海外 AI API）、机房位置、操作系统支持。以下是针对中国用户的推荐：

常见 Linux 问题排查

Docker 权限被拒绝（Permission Denied）

运行 docker 命令时提示 permission denied：

# 将用户加入 docker 组
sudo usermod -aG docker $USER

# 重新登录终端（或执行 newgrp docker）
# 验证
docker ps

如果仍然报错，检查 Docker 服务是否在运行：sudo systemctl status docker。

防火墙阻止端口

# Ubuntu (ufw)
sudo ufw status
sudo ufw allow 443/tcp
sudo ufw allow 80/tcp

# CentOS (firewalld)
sudo firewall-cmd --list-ports
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload

# 检查端口是否在监听
ss -tlnp | grep -E '(443|80|18789)'

SELinux 干扰（CentOS/RHEL）

CentOS 和 RHEL 默认启用 SELinux（Security-Enhanced Linux），可能阻止 Docker 读写挂载目录：

# 检查 SELinux 是否是问题原因
sudo ausearch -m avc --start recent

# 为 OpenClaw 目录添加正确的 SELinux 上下文
sudo chcon -Rt svirt_sandbox_file_t ~/.openclaw

# 或在 docker run 中使用 :Z 标志
# -v ~/.openclaw:/home/node/.openclaw:Z

症状通常是容器启动后立即退出，日志显示无法读取配置文件。

Docker 容器内 DNS 解析失败

某些 Linux 系统的 DNS 配置可能导致 Docker 容器内无法解析域名（如 api.openai.com）：

# 检查容器内 DNS
docker exec openclaw cat /etc/resolv.conf

# 如果 DNS 不正常，在 docker run 时指定 DNS
docker run -d --name openclaw \
  --dns 8.8.8.8 --dns 1.1.1.1 \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  --memory=2g --memory-swap=3g \
  --restart unless-stopped \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

# 或全局配置 Docker DNS
# 编辑 /etc/docker/daemon.json
{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

挂载目录权限问题

OpenClaw 容器以 node 用户（uid 1000）运行。如果宿主机用户 uid 不是 1000，容器无法写入挂载目录：

chmod 777 ~/.openclaw
chmod 777 ~/.openclaw/credentials

OOM（内存不足）被 Kill

如果 docker logs openclaw 显示 Killed 或 OOMKilled，说明内存不足。确保服务器至少 2GB 内存，容器设置 --memory=2g --memory-swap=3g。512MB 内存必定 OOM。

完整部署步骤汇总

不想自建？试试 OpenClaw Launch

如果你不想管理 Linux 服务器、不想折腾 Docker 和配置文件，OpenClaw Launch 提供完全托管的解决方案：

• 10 秒部署 — 可视化编辑器配置，一键启动，无需任何命令行操作
• 零运维 — 无需管理服务器、Docker、SSL 证书、防火墙、进程管理
• 全球可用 — 服务器在美国，直连所有 AI API（OpenRouter、OpenAI、Anthropic、Google），无需代理
• $3/月起 — 比多数云服务器还便宜，且省去所有运维时间
• 自动更新 — OpenClaw 新版本发布后自动升级，无需手动操作
• 支付宝/微信 — 支持国内常用支付方式

常见问题（FAQ）

哪个 Linux 发行版最适合部署 OpenClaw？

Ubuntu 22.04 LTS 或 24.04 LTS 是最推荐的选择。原因：社区最大、教程最多、Docker 安装最简单、长期支持（5 年安全更新）。Debian 12 也很好，更轻量但社区相对小一些。CentOS/Rocky Linux 适合企业环境中已有 RHEL 系基础设施的场景。

OpenClaw 需要多少内存？

最低 1GB 可用内存，推荐 2GB 以上。容器应设置 --memory=2g --memory-swap=3g。512MB 内存会导致 OOM 崩溃。如果服务器上还有其他服务，总内存建议 4GB。

VPS（云服务器）和独立服务器哪个好？

对于 OpenClaw 而言，VPS 完全足够。OpenClaw 对 CPU 和 IO 的要求不高，2 vCPU / 2GB RAM 的 VPS 即可流畅运行。独立服务器成本更高（通常 $50+/月），除非你同时运行多个 OpenClaw 实例或其他重型服务，否则没有必要。

可以用宝塔面板管理 OpenClaw 吗？

可以。宝塔面板（BT Panel）提供 Docker 管理功能，可以在面板中拉取镜像、创建容器、管理端口。但你仍然需要手动编写 openclaw.json 配置文件，宝塔面板不能替代这一步。如果你习惯用宝塔管理服务器，可以：

1. 在宝塔面板中安装 Docker 管理器
2. 通过 SSH 创建配置目录和配置文件（宝塔面板 > 终端）
3. 在 Docker 管理器中创建 OpenClaw 容器
4. 使用宝塔的 Nginx 反向代理功能配置 HTTPS

或者直接使用 OpenClaw Launch，无需宝塔面板或任何服务器管理。

国内服务器能运行 OpenClaw 吗？

OpenClaw 本身可以在任何 Linux 服务器上运行。但如果使用海外 AI API（OpenRouter、OpenAI、Anthropic），国内大陆服务器可能无法直接访问。解决方案：选择香港/海外机房、使用国产 AI 模型（DeepSeek、通义千问）、或使用 OpenClaw Launch 托管服务。