OpenClaw Linux 部署手册：常规安装、Docker 与 Docker Compose 三种主流方式常规安装— curl 脚本 / npm 全局安装Docker 部署— 单容器或预构建镜像Docker Compose 部署— 官方推荐的生产方式本文按上述三种方式分别说明含验收命令与常见问题。一、系统要求项目要求操作系统Ubuntu 20.04、Debian 11、CentOS/RHEL 等主流 LinuxNode.js常规安装24推荐或 22.19Docker容器部署Docker Engine Compose v2内存常规安装 ≥ 1 GBDocker 本地构建镜像 ≥ 2 GB磁盘预留镜像、日志、配置目录空间默认端口Gateway18789Bridge18790二、方式一常规安装2.1 一键安装脚本推荐curl -fsSL https://openclaw.ai/install.sh | bash跳过 onboardingcurl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard2.2 本地 prefix 安装不依赖系统 Nodecurl -fsSL https://openclaw.ai/install-cli.sh | bashOpenClaw 和 Node 安装在~/.openclaw前缀下。2.3 npm / pnpm / bun 全局安装# npm npm install -g openclawlatest openclaw onboard --install-daemon # pnpm pnpm add -g openclawlatest pnpm approve-builds -g openclaw onboard --install-daemon # bun bun add -g openclawlatest openclaw onboard --install-daemon2.4 配置与守护进程openclaw onboard --install-daemonLinux/WSL2 会创建systemd user service实现 Gateway 开机自启。2.5 验证openclaw --version openclaw doctor openclaw gateway status curl -fsS http://127.0.0.1:18789/healthz浏览器打开http://127.0.0.1:18789/在 Settings 粘贴 Gateway Token。2.6 从源码安装git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build pnpm ui:build pnpm link --global openclaw onboard --install-daemon三、方式二Docker 部署适合不想污染宿主机环境或VPS 隔离运行的场景。3.1 前置条件# 确认 Docker 与 Compose v2 docker --version docker compose version3.2 使用官方 setup 脚本推荐克隆仓库后执行git clone https://github.com/openclaw/openclaw.git cd openclaw ./scripts/docker/setup.sh使用预构建镜像小内存 VPS 推荐避免 OOMexport OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh脚本会自动构建或拉取镜像交互式 onboardingAPI Key 等生成.env和 Gateway Token通过 Docker Compose 启动 Gateway3.3 手动 Docker 流程docker build -t openclaw:local -f Dockerfile . docker compose run --rm --no-deps --entrypoint node openclaw-gateway \ dist/index.js onboard --mode local --no-install-daemon docker compose run --rm --no-deps --entrypoint node openclaw-gateway \ dist/index.js config set --batch-json [{path:gateway.mode,value:local},{path:gateway.bind,value:lan},{path:gateway.controlUi.allowedOrigins,value:[http://localhost:18789,http://127.0.0.1:18789]}] docker compose up -d openclaw-gateway3.4 打开 Control UIhttp://127.0.0.1:18789/获取 dashboard 链接docker compose run --rm openclaw-cli dashboard --no-open3.5 健康检查curl -fsS http://127.0.0.1:18789/healthz # liveness curl -fsS http://127.0.0.1:18789/readyz # readiness四、方式三Docker Compose 部署生产推荐官方docker-compose.yml包含两个服务服务作用openclaw-gateway常驻 Gateway对外暴露 18789/18790openclaw-cli一次性 CLI 容器执行管理命令4.1 标准 Compose 结构services: openclaw-gateway: image: ${OPENCLAW_IMAGE:-openclaw:local} environment: HOME: /home/node OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN} volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace ports: - ${OPENCLAW_GATEWAY_PORT:-18789}:18789 - ${OPENCLAW_BRIDGE_PORT:-18790}:18790 restart: unless-stopped command: [node, dist/index.js, gateway, --bind, lan, --port, 18789] openclaw-cli: image: ${OPENCLAW_IMAGE:-openclaw:local} network_mode: service:openclaw-gateway volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace entrypoint: [node, dist/index.js]完整文件以官方仓库docker-compose.yml为准。4.2 一键启动setup 脚本cd openclaw export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh4.3 常用 Compose 命令# 启动 Gateway docker compose up -d openclaw-gateway # 查看日志 docker compose logs -f openclaw-gateway # 停止 docker compose down # CLI添加 Telegram 渠道 docker compose run --rm openclaw-cli channels add --channel telegram --token token # CLIWhatsApp 扫码登录 docker compose run --rm openclaw-cli channels login # 设备审批 docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve requestId4.4 环境变量常用变量用途OPENCLAW_IMAGE使用远程预构建镜像OPENCLAW_GATEWAY_TOKENGateway 认证 TokenOPENCLAW_CONFIG_DIR配置目录挂载路径OPENCLAW_WORKSPACE_DIR工作区挂载路径OPENCLAW_SANDBOX启用 Agent Sandbox1/trueOPENCLAW_SKIP_ONBOARDING跳过交互式 onboarding4.5 持久化目录容器 bind-mount 以下路径替换容器后数据保留~/.openclaw— 配置、openclaw.json、.env~/.openclaw/workspace— Agent 工作区权限注意容器以 uid 1000node运行宿主机挂载目录需sudo chown -R 1000:1000 ~/.openclaw4.6 启用 Agent Sandboxexport OPENCLAW_SANDBOX1 ./scripts/docker/setup.shSandbox 在独立 Docker 容器中执行 Agent 工具Gateway 仍在宿主机/主容器中运行。五、三种方式对比维度常规安装DockerDocker Compose上手速度★★★ 最快★★★★环境隔离低高高适合场景个人本机/dev单容器验证VPS/生产依赖Node.jsDocker EngineDocker Compose v2升级openclaw update拉取新镜像compose pull up六、常见问题1构建镜像 OOMexit 1371 GB 内存 VPS 构建会失败。改用预构建镜像export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh2EACCES 权限错误sudo chown -R 1000:1000 ~/.openclaw3Gateway 重启循环检查gateway.bind是否使用了lan或loopback不要写0.0.0.0作为 bind 值。4Docker 内访问宿主机 Ollama/LM Studio容器内用host.docker.internal替代127.0.0.1ProviderDocker 内 URLOllamahttp://host.docker.internal:11434LM Studiohttp://host.docker.internal:1234宿主机服务需监听0.0.0.0。5openclaw 命令找不到常规安装export PATH$(npm prefix -g)/bin:$PATH echo export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc七、结语Linux 部署 OpenClaw 的推荐路径本机开发→curl install.sh或 npm 全局安装VPS/生产→ Docker Compose 预构建 GHCR 镜像安全隔离→ 启用 OPENCLAW_SANDBOX