核心摘要

通过 Docker 部署 OpenClaw 是在云服务器或 VPS 上搭建隔离 AI 代理网关的最佳实践。借助官方提供的 scripts/docker/setup.sh 脚本，你可以在几分钟内完成网关初始化、API 密钥配置并启用 Agent Sandbox 沙盒。本指南将带你从零开始，完整走通 OpenClaw 部署 与生产环境配置的每一个环节。

📋 目录

✨ 核心要点

  • 自动化部署：使用官方安装脚本结合 GitHub Container Registry (GHCR) 预构建镜像，可大幅简化部署流程。
  • 默认安全：默认镜像以非 root 用户 node（UID 1000）运行，并剥离了不必要的网络特权。
  • 沙盒隔离：通过将大模型的工具执行环节放入临时容器中，有效保护宿主机系统安全。
  • 数据持久化：必须将 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 挂载到宿主机，以确保配置和数据在容器重启后不丢失。

💡 Quick Tool: 在修改配置文件之前？使用我们的免费 JSON 格式化工具 验证你的 openclaw.json 语法，避免容器因配置错误而崩溃。

什么是 OpenClaw？

OpenClaw 是一个功能强大的 AI Agent 网关与编排引擎。它能够将大型语言模型（LLM）与外部工具、API 以及消息渠道（如 Discord、Telegram 和 WhatsApp）无缝连接，帮助开发者构建高度自治的 AI 工作流。

与简单的单体脚本不同，OpenClaw 作为一层健壮的中间件，专门负责处理鉴权、会话状态管理、工具沙盒隔离以及提供 Web 可视化面板。

📝 术语链接: AI Agent — 了解 AI 代理是如何实现自主决策并采取行动的。

为什么选择 Docker 部署 OpenClaw

虽然你可以直接通过 Node.js 在本地安装 OpenClaw，但 Docker 部署 提供了无可替代的优势：

特性 本地直接安装 Docker 容器化部署
运行环境 污染宿主机系统环境 完全隔离的容器环境
底层依赖 强依赖特定版本的 Node.js、Bun、pnpm 仅需安装 Docker Desktop / Engine
安全级别 AI 直接在宿主机执行命令，风险极高 非 root 容器运行，支持 Sandbox 隔离
可迁移性 难以在不同服务器间复刻 基于 Docker Compose，高度可复现

如果你仅仅是为了在个人电脑上快速测试，本地安装确实足够快。但只要是面向公网的 VPS 部署或团队协作环境，Docker 绝对是必选项。

OpenClaw 架构解析

在执行部署命令前，我们需要先理解 OpenClaw 各个组件在容器环境下的交互方式：

graph TD User["用户 / 浏览器"] -->|HTTP 18789| Gateway[OpenClaw 网关容器] CLI[OpenClaw CLI 容器] -->|本地 API| Gateway Gateway -->|工具执行调度| Sandbox[Agent 沙盒容器组] Gateway -->|目录挂载| Config[("~/.openclaw 配置")] Gateway -->|目录挂载| Workspace[("workspace/ 工作区")] style User fill:#e1f5fe,stroke:#01579b style Gateway fill:#fff3e0,stroke:#e65100 style CLI fill:#fff3e0,stroke:#e65100 style Sandbox fill:#fce4ec,stroke:#c2185b style Config fill:#e8f5e9,stroke:#2e7d32 style Workspace fill:#e8f5e9,stroke:#2e7d32

在架构中，openclaw-gateway 是持续运行的后台守护进程。而 openclaw-cli 则是一个按需启动的命令行容器（用于添加渠道、审批设备等），它通过共享的网络命名空间与网关直接通信。

OpenClaw Docker 部署步骤

环境准备

请确保你的宿主机满足以下条件：

  1. 已安装 Docker Engine 及 Docker Compose v2。
  2. 服务器至少拥有 2 GB 内存（如果在 1GB 内存机器上本地构建，pnpm install 极易触发 OOM 并返回 137 错误码）。
  3. 了解 Linux 基础的文件权限管理。

方式一：使用官方自动化脚本（推荐）

最省心的方式是直接使用官方脚本拉取 GHCR 上的预构建镜像。

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

# 指定使用远程预构建镜像，避免本地编译
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# 运行自动化安装脚本
./scripts/docker/setup.sh

在运行过程中，脚本会：

  • 提示你输入 AI 供应商的 API Key（如 OpenAI、Anthropic）。
  • 自动生成网关访问 Token 并写入 .env 文件。
  • 通过 Docker Compose 启动网关容器。

启动成功后，在浏览器中访问 http://127.0.0.1:18789/，并粘贴安装过程中生成的 Token 即可进入控制台。

方式二：手动部署流程

如果你需要对构建和启动过程进行精细化控制，可以手动执行以下步骤：

bash 
# 1. 本地构建 Docker 镜像
docker build -t openclaw:local -f Dockerfile .

# 2. 以交互模式运行初始化向导
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

# 3. 配置网关的网络绑定模式
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"}]'

# 4. 后台启动网关守护进程
docker compose up -d openclaw-gateway

🔧 立即体验：使用我们的免费 JSON 格式化工具 在线校验你的配置 JSON 数组，确保格式准确无误。

OpenClaw 进阶配置

通过 CLI 添加消息渠道

因为 openclaw-cli 容器与网关共享网络命名空间，所以必须在网关启动后才能运行 CLI 命令。

bash 
# 绑定 Telegram 机器人：
docker compose run --rm openclaw-cli channels add --channel telegram --token "你的_BOT_TOKEN"

# 绑定 Discord 机器人：
docker compose run --rm openclaw-cli channels add --channel discord --token "你的_BOT_TOKEN"

常用环境变量设置

安装脚本支持传入多个环境变量来定制化部署逻辑：

变量名 作用
OPENCLAW_IMAGE 指定远程镜像地址，跳过本地构建。
OPENCLAW_DOCKER_APT_PACKAGES 在构建阶段安装额外的系统依赖（如 git curl jq）。
OPENCLAW_SANDBOX 开启 Agent 沙盒模式（设为 1 或 true）。
OPENCLAW_HOME_VOLUME 将 /home/node 目录持久化到一个具名 Volume 中。

Agent Sandbox 沙盒配置

当赋予 AI 代理执行代码或 Shell 命令的能力时，如果直接在宿主机或网关主容器内运行这些命令，将带来灾难性的安全风险。

Agent Sandbox 完美解决了这个问题：它会在后台动态拉起独立的、用完即毁的容器，专门用来执行 AI 工具调用。

快速开启沙盒模式：

bash 
# 导出环境变量
export OPENCLAW_SANDBOX=1

# 重新运行安装脚本
./scripts/docker/setup.sh

这会自动在你的配置中追加如下策略：

json 
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}

启用后，网关本身依然在安全的环境中运行，而 AI 所有的危险操作都会被严格限制在沙盒容器内。

最佳实践

  1. 务必持久化数据 — 务必将宿主机目录挂载至 OPENCLAW_CONFIG_DIR（对应容器内 /home/node/.openclaw）。这能保证你的 API 密钥、授权配置和核心的 openclaw.json 在容器更新或重启时不会丢失。
  2. 处理文件权限 — OpenClaw 容器以 node 用户（UID 1000）身份运行。请确保你挂载的宿主机目录拥有正确的权限，否则会报 Permission Denied：
    bash 
    sudo chown -R 1000:1000 /path/to/openclaw-config
  3. 优先使用预构建镜像 — 除非你在进行二次开发，否则请始终配置 OPENCLAW_IMAGE。这能避免在服务器上执行极耗内存的 pnpm install 步骤。
  4. 监控磁盘空间 — AI 代理在运行中会产生大量日志和媒体文件。定期清理 /tmp/openclaw/ 目录和过期的 JSONL 会话记录，防止磁盘被打满。

⚠️ 常见错误:

  • 在网关启动前运行 CLI → 由于 openclaw-cli 依赖 service:openclaw-gateway 网络模式，如果网关没起来，CLI 容器会直接报错退出。
  • 将 Bind 模式设为 0.0.0.0 → OpenClaw 的 gateway.bind 字段期望的是逻辑值（如 lan 或 loopback），不要直接填写 IP 地址。

常见问题 (FAQ)

Q1: 如何检查 OpenClaw 容器的健康状态？

OpenClaw 默认提供了免鉴权的健康探针接口：

bash 
# 检查存活状态 (liveness)
curl -fsS http://127.0.0.1:18789/healthz

# 检查就绪状态 (readiness)
curl -fsS http://127.0.0.1:18789/readyz

Q2: 服务器在安装时因为内存不足而崩溃怎么办？

如果你没有使用 OPENCLAW_IMAGE 而是选择本地构建，pnpm install 阶段至少需要 2GB 内存。如果是 1GB 内存的轻量级 VPS，Linux 系统的 OOM Killer 会直接杀掉进程（退出码 137）。解决方案是使用官方预构建镜像。

Q3: lan 和 loopback 绑定模式有什么区别？

  • lan：允许宿主机浏览器以及通过 Docker 端口映射进来的外部流量访问网关。这是在外网访问仪表盘的前提条件。
  • loopback：极度收紧权限，仅允许处于同一容器网络命名空间内的进程直接访问网关。

Q4: 如何在容器内安装网页浏览所需的 Playwright 依赖？

如果你的 Agent 需要使用浏览器自动化工具，必须在运行中的容器内安装相关依赖：

bash 
docker compose run --rm openclaw-cli node /app/node_modules/playwright-core/cli.js install chromium

总结

通过 Docker 部署 OpenClaw 为你的 AI Agent 应用提供了一个安全、稳定且易于扩展的基础底座。借助官方自动化脚本、合理配置数据持久化并开启 Agent Sandbox，你可以确保大模型工作流在高效运转的同时，不会对宿主机产生任何安全威胁。

👉 立即使用 JSON 格式化工具 — 为你的 OpenClaw 配置文件进行专业校验。

相关资源