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

• 什么是 OpenClaw？
• 为什么选择 Docker 部署 OpenClaw
• OpenClaw 架构解析
• OpenClaw Docker 部署步骤
• OpenClaw 进阶配置
• Agent Sandbox 沙盒配置
• **实践
• 常见问题 (FAQ)
• 总结
• 相关资源

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

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

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

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

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

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

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

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

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

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

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

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

# 克隆仓库 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 即可进入控制台。

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

# 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 容器与网关共享网络命名空间，所以必须在网关启动后才能运行 CLI 命令。

# 绑定 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" 

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

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

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

快速开启沙盒模式：

# 导出环境变量 export OPENCLAW_SANDBOX=1 # 重新运行安装脚本 ./scripts/docker/setup.sh 

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

{ "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：

   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 地址。

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

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

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

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

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

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

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

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

• JSON Schema 验证指南 — 深入了解如何使用 Schema 验证复杂的 JSON 配置文件。
• AI Agent 术语解析 — 深度理解 AI 代理的核心概念。
• 大语言模型 (LLM) — 了解驱动 OpenClaw 的智能大脑底座。