OpenClaw LaunchOpenClaw Launch
← 中文首页

Linux 部署

Linux Docker 部署 OpenClaw 完整教程

在 Ubuntu / Debian / CentOS 或任意 Linux VPS 上用 Docker 部署 OpenClaw 的中文操作手册。 一键脚本、docker run、docker-compose、国内镜像、systemd 自启、代理穿透 — 这一篇就够。

开始前先确认 3 件事

  • Linux 内核 ≥ 5.0，64 位。任意主流发行版都行（Ubuntu 22.04+ 推荐）。
  • 2GB 内存 + 10GB 硬盘 是起步线。带浏览器自动化、本地模型时建议 4GB+。
  • 是否需要代理 — 如果你的 OpenClaw 要调用 OpenAI / Anthropic / Gemini， 而服务器在中国大陆境内，请先准备好代理。具体可参考 OpenClaw 代理配置 和 Gemini 翻墙指南。

方式一：install.sh 一键脚本（最快）

官方提供了一个一键安装脚本，会自动检测系统、安装 Docker（如未安装）、拉取镜像、生成默认配置并启动容器：

curl -fsSL https://openclaw.ai/install.sh | bash

如果你之前已经手动装好 Docker，想跳过 Docker 安装步骤、只跑 OpenClaw，可以加参数：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

脚本运行完会输出 gateway 地址（默认 http://<服务器IP>:18789）和管理 token。 第一次连上 gateway 时把 token 粘贴进去就能开始用。

国内服务器的小坑

脚本本身要从 openclaw.ai 拉。国内 VPS 如果直连超时，先在服务器上开好代理再跑：

export https_proxy=http://127.0.0.1:7890
curl -fsSL https://openclaw.ai/install.sh | bash

方式二：纯 docker run（最透明）

不喜欢一键脚本、想看清每一步在做什么？直接 docker run：

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v openclaw_data:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:latest

参数说明：

  • -p 18789:18789 — 暴露 gateway 控制端口给本地或局域网
  • -v openclaw_data:/home/node/.openclaw — 持久化配置、凭证、对话历史
  • --restart unless-stopped — 容器异常退出自动重启，宿主机重启后也会拉起

关于镜像标签：生产环境强烈建议把 :latest 换成具体版本号，比如ghcr.io/openclaw/openclaw:2026.5。这样升级是可控的，不会因为一次 docker pull 踩到上游 breaking change。OpenClaw Launch 自己就是这么做的。

方式三：docker-compose（推荐生产用）

如果你计划长期跑、或者要和其他服务（数据库、反向代理、监控）一起编排，用 compose 最舒服。 新建 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:2026.5
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace
    environment:
      - TZ=Asia/Shanghai
      # 中国大陆服务器去掉下面三行的注释，填入你的代理
      # - HTTP_PROXY=http://host.docker.internal:7890
      # - HTTPS_PROXY=http://host.docker.internal:7890
      # - NO_PROXY=localhost,127.0.0.1
    extra_hosts:
      - "host.docker.internal:host-gateway"

然后：

docker compose up -d
docker compose logs -f openclaw

extra_hosts 那一行在 Linux 上必须加 — 否则容器里 host.docker.internal 无法解析，代理那条规则就失效了。

国内 Docker 镜像加速

ghcr.io（GitHub Container Registry）在国内拉镜像非常慢甚至超时。三种解法：

  • 用阿里云容器镜像加速器（最稳）— 登录阿里云控制台， 镜像服务 → 镜像工具 → 镜像加速器，会给你一个 https://xxx.mirror.aliyuncs.com 地址。写入 /etc/docker/daemon.json：
    {
  "registry-mirrors": ["https://xxx.mirror.aliyuncs.com"]
}
    然后 systemctl restart docker。
  • 用 docker.io 中转 — ghcr.io 镜像可以通过 docker.io 镜像同步，但延迟较高，不推荐生产用。
  • 提前 docker save 再 scp — 在能访问 ghcr.io 的机器上 docker save 打包成 tar，scp 到国内服务器再 docker load。适合大镜像第一次拉。

systemd 开机自启

如果你用 docker-compose 跑且想跟着系统启动，新建 /etc/systemd/system/openclaw.service：

[Unit]
Description=OpenClaw via docker compose
Requires=docker.service
After=docker.service network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/openclaw
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

启用：systemctl enable --now openclaw。注意 WorkingDirectory 改成你docker-compose.yml 实际所在的路径。

容器跑起来之后做什么

  1. 开放端口 — 默认 18789 只在内网。如果你想从家里电脑通过浏览器连服务器上的 OpenClaw gateway， 需要 ufw allow 18789 或者更安全的方式：起一个 Caddy / Nginx 反代加 HTTPS。
  2. 第一次访问 gateway — 在浏览器打开 http://<服务器IP>:18789， 粘贴启动时输出的 token，进入控制面板。
  3. 配置模型 — 在控制面板里填入 OpenAI / Anthropic / OpenRouter 的 API Key， 或者用 OpenRouter 一个 Key 覆盖所有模型。具体见 模型选择。
  4. 接入聊天频道 — Telegram、Discord、WeChat 任选其一。配置流程参考 Telegram 接入 或 微信接入。
  5. 加 MCP / Skills — 在控制面板里浏览社区 Skills 一键启用，或者参考 MCP 配置指南 手动添加 MCP Server。

常见报错排查

容器起来后立刻 Exited (1)

docker logs openclaw 查日志。最常见的两类原因：(a) 端口冲突，18789 被占用 — 换一个或者 lsof -i:18789 找出来杀掉；(b) 配置文件被改坏 —docker volume rm openclaw_data 重置（注意会丢历史）。

容器跑着但访问超时

99% 是宿主机防火墙挡了。ufw status 检查规则，或者临时ufw allow 18789/tcp 排除问题。云厂商（阿里云、腾讯云、AWS）还需要在控制台 安全组里再放一次。

调用 OpenAI / Gemini 时一直 timeout

代理没穿透到容器。回到 docker-compose.yml 里把 HTTP_PROXY / HTTPS_PROXY 和 extra_hosts 写对，重启容器。详细排查见 中国大陆使用 OpenClaw + Gemini 完整指南。

docker pull 拉到一半 EOF

ghcr.io 在国内不稳定。换镜像加速器，或者用 docker save / load 的方式中转。

什么时候应该选 OpenClaw Launch 而不是自己 Docker？

自己 Docker 部署适合：(a) 完全的数据自主、(b) 有服务器运维能力、(c) 高度定制需求。 但以下情况建议直接用 OpenClaw Launch 托管：

  • 不想自己折腾代理 — 我们的容器节点在海外（美国/欧洲），对 OpenAI / Gemini 直连。
  • 不想自己排查 Docker 报错 — 托管版自带健康检查、自动重启、版本回滚。
  • 不想为了一个 AI 机器人单独买一台 VPS — 托管版按月计费比自建便宜得多。
  • 需要预热的 Skills、MCP、模型 — 都已经准备好，开关即用。

如果只是想快速验证 OpenClaw 是不是你需要的，托管版有免费试用，5 秒部署一个实例，跑得通了再决定要不要自建。

不想折腾 Linux？试试托管版

免费 trial 5 秒部署一个 OpenClaw 实例，所有依赖、代理、模型 Key 都不用自己配。

开始部署