OpenClaw Docker 安装指南 - 快速部署 AI 智能体网关

清夏晚风 Lv7
  2026-03-23 11:32:56 2026-03-23 11:32:56 Created   2026-05-29 14:43:35 2026-05-29 14:43:35 Updated      

什么是 OpenClaw？

OpenClaw 是一个开源的 AI Agent Gateway（AI 智能体网关），用 Node.js 运行时构建。它是整个系统的核心中枢，负责连接外部聊天软件与 AI 智能体，并执行本地操作。

核心架构

OpenClaw 的架构可以用四层来理解：

1
2
3
4
5
6
7
8
9
10
11
12
13
┌─────────────────────────────────────┐
│  接入层 (Channels + CLI + Web)       │
│  入口: 飞书/微信/命令行/面板          │
├─────────────────────────────────────┤
│  控制平面 (Gateway)                  │
│  中枢: 路由、会话、状态、安全          │
├─────────────────────────────────────┤
│  执行平面 (Agent Runtime)            │
│  大脑: LLM 推理、任务规划             │
├─────────────────────────────────────┤
│  工具层 (Skills)                     │
│  手脚: 文件操作、代码执行、API 调用    │
└─────────────────────────────────────┘

Docker 适合我吗？

场景 建议
✅ 想要隔离的、可丢弃的 Gateway 环境 使用 Docker
✅ 在没有本地安装的主机上运行 使用 Docker
❌ 在自己的机器上运行，追求最快开发循环 使用正常安装流程

💡 注意：智能体沙箱隔离也使用 Docker，但它不需要完整的 Gateway 网关在 Docker 中运行。

前置要求

  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 足够的磁盘空间用于镜像 + 日志
  • 网络连接（下载镜像和依赖）

快速开始（推荐）

最简单的方式是使用官方提供的安装脚本：

指定官方构建好的镜像（可以跳过构建过程，默认 latest）：

1
export OPENCLAW_IMAGE=ghcr.nju.edu.cn/openclaw/openclaw:latest

开启沙箱隔离（可选）：

1
export OPENCLAW_SANDBOX=1
1
2
# 从仓库根目录运行
./docker-setup.sh

脚本功能

此脚本会自动完成以下操作：

  1. 构建 Gateway 网关镜像
  2. 运行新手引导向导（onboard）
  3. 打印可选的提供商设置提示
  4. 通过 Docker Compose 启动 Gateway 网关
  5. 生成 Gateway 网关令牌并写入 .env

访问控制界面

脚本执行完成后：

  1. 在浏览器中打开 http://127.0.0.1:18789/
  2. 将令牌粘贴到控制 UI（设置 → token）

如果需要再次获取带令牌的 URL：

1
docker compose run --rm openclaw-cli dashboard --no-open

主机目录映射

安装完成后，以下目录会被映射到主机：

  • ~/.openclaw/ - 配置文件
  • ~/.openclaw/workspace - 工作区/沙箱目录

如果是root用户，宿主机数据存放目录为 /root/.openclaw，环境变量在源码的.env文件中（已被脚本更新）。

关闭https验证：

在/root/.openclaw的配置文件中添加："dangerouslyDisableDeviceAuth": true 。

允许局域网访问：

在/root/.openclaw的配置文件中添加：运行的IP配置，类似于：

1
2
3
4
5
6
7
8
9
10
11
{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "http://192.168.x.x:18789"
      ]
    }
  }
}

手动部署流程

如果你想手动控制部署过程：

1
2
3
4
5
6
7
8
# 1. 构建镜像
docker build -t openclaw:local -f Dockerfile .

# 2. 运行新手引导
docker compose run --rm openclaw-cli onboard

# 3. 启动 Gateway 服务
docker compose up -d openclaw-gateway

⚠️ 注意：从仓库根目录运行 docker compose 命令。

环境变量配置

可选环境变量

环境变量 说明 示例
OPENCLAW_DOCKER_APT_PACKAGES 构建期间安装额外的 apt 包 ffmpeg build-essential
OPENCLAW_EXTRA_MOUNTS 添加额外的主机绑定挂载 见下文
OPENCLAW_HOME_VOLUME 在命名卷中持久化 /home/node openclaw_home

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
# 安装额外的系统包
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

# 持久化整个容器 home 目录
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

# 组合使用
export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

额外挂载配置（可选）

如果你想将额外的主机目录挂载到容器中，在运行 docker-setup.sh 之前设置 OPENCLAW_EXTRA_MOUNTS。

配置格式

接受逗号分隔的 Docker 绑定挂载列表：

1
2
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

格式说明：主机路径:容器路径:权限

  • ro - 只读（read-only）
  • rw - 读写（read-write）

注意事项

  • 路径必须在 macOS/Windows 上与 Docker Desktop 共享
  • 如果编辑 OPENCLAW_EXTRA_MOUNTS，重新运行 docker-setup.sh 以重新生成配置
  • docker-compose.extra.yml 是生成的，不要手动编辑它

持久化配置

方案 1：使用命名卷（推荐）

如果你想让 /home/node 在容器重建后持久化：

1
2
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

这会创建一个 Docker 卷并将其挂载到 /home/node，同时保持标准的配置/工作区绑定挂载。

方案 2：使用绑定挂载

对于绑定挂载，使用 OPENCLAW_EXTRA_MOUNTS：

1
2
export OPENCLAW_EXTRA_MOUNTS="$HOME/openclaw-home:/home/node:rw"
./docker-setup.sh

删除命名卷

命名卷会持久化直到手动删除：

1
docker volume rm openclaw_home

控制 UI 令牌 + 设备配对

常见问题

如果你看到以下错误：

  • "unauthorized"
  • "disconnected (1008): pairing required"

说明需要进行设备配对。

解决方案

1
2
3
4
5
6
7
8
# 获取新的仪表板链接
docker compose run --rm openclaw-cli dashboard --no-open

# 查看待批准的设备列表
docker compose run --rm openclaw-cli devices list

# 批准指定设备
docker compose run --rm openclaw-cli devices approve <requestId>

高级配置

安装额外的 apt 包

如果你需要镜像内的系统包（例如构建工具或媒体库）：

1
2
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential libpq-dev"
./docker-setup.sh
  • 接受空格分隔的 apt 包名称列表
  • 包会在镜像构建期间安装，即使容器被删除也会持久化
  • 如果更改此变量，重新运行 docker-setup.sh 以重建镜像

功能完整的容器（选择加入）

默认的 Docker 镜像是安全优先的，以非 root 的 node 用户运行。这意味着：

  • ❌ 运行时无法安装系统包
  • ❌ 默认没有 Homebrew
  • ❌ 没有捆绑的 Chromium/Playwright 浏览器

如果你想要功能更完整的容器，使用以下选择加入选项：

1
2
3
4
5
6
7
8
# 1. 持久化 /home/node 以便浏览器下载和工具缓存能够保留
export OPENCLAW_HOME_VOLUME="openclaw_home"

# 2. 将系统依赖烘焙到镜像中（可重复 + 持久化）
export OPENCLAW_DOCKER_APT_PACKAGES="chromium-browser build-essential"

# 3. 运行安装脚本
./docker-setup.sh

常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 查看运行中的容器
docker compose ps

# 查看日志
docker compose logs -f openclaw-gateway

# 重启服务
docker compose restart openclaw-gateway

# 停止服务
docker compose down

# 进入容器 shell
docker compose exec openclaw-gateway bash

# 使用 CLI
docker compose run --rm openclaw-cli <command>

故障排除

构建卡在 100%

如果构建过程卡在 100%，请：

  1. 耐心等待（网络问题可能导致下载缓慢）
  2. 检查网络连接
  3. 检查代理设置

权限问题

如果遇到权限错误，确保：

  1. Docker 守护进程正在运行
  2. 当前用户有权限访问 Docker
  3. 在 Linux 上，可能需要将用户添加到 docker 组：
    1
    2
    sudo usermod -aG docker $USER
    newgrp docker

端口冲突

如果 18789 端口被占用，修改 docker-compose.yml：

1
2
3
4
services:
  openclaw-gateway:
    ports:
      - "8080:18789"  # 将主机 8080 映射到容器 18789

局域网部署常见问题（树莓派/服务器）

在树莓派或服务器上部署 OpenClaw 并通过局域网访问时，可能会遇到以下四个核心问题。以下是完整的解决方案：

第一关：局域网无法访问（端口监听问题）

❌ 现象描述

OpenClaw Gateway 服务已启动，日志显示正常监听 18789 端口。但在同一局域网的其他电脑浏览器中输入 http://<服务器IP>:18789，却显示无法连接或连接超时。

💡 原因分析

默认情况下，服务可能只绑定在 localhost (127.0.0.1) 上，这意味着它只接受来自服务器内部的请求，拒绝外部局域网设备的访问。

✅ 解决方案：修改 Bind 模式

编辑配置文件，将监听地址改为允许所有网卡接口访问：

1
2
# 编辑配置文件
sudo vi ~/.openclaw/openclaw.json

找到 gateway 的 bind 部分，修改 bind 模式为 lan：

1
2
3
4
5
6
7
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan"
  }
}

保存并重启服务：

1
sudo openclaw gateway restart

验证：现在应该可以在局域网其他设备上通过 http://<IP>:18789 访问了。

第二关：跨域错误 CORS（白名单配置）

❌ 现象描述

网页能打开了，但会话界面显示错误信息，提示：

1
origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)

中文翻译：”来源不被允许（请从网关主机打开控制界面，或在 gateway.controlUi.allowedOrigins 配置项中允许该来源）”

💡 原因分析

浏览器的同源策略 (Same-Origin Policy) 阻止了网页向不同源（即使只是 IP 不同）发起请求。OpenClaw 默认可能只允许特定的域名访问。

✅ 解决方案：配置 Gateway 白名单

编辑配置文件，添加允许的访问地址：

1
sudo vi ~/.openclaw/openclaw.json

找到 gateway 的 allowedOrigins 部分，添加服务器的访问地址：

1
2
3
4
5
6
7
8
9
10
11
{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "http://192.168.x.x:18789"
      ]
    }
  }
}

重启服务：

1
sudo openclaw gateway restart

第三关：安全上下文限制（必须启用 HTTPS）

❌ 现象描述

跨域问题解决后，页面弹出红色警告或无法建立 WebSocket 连接，提示：

1
Control UI requires device identity (use HTTPS or localhost secure context)

中文翻译：”控制界面需要设备身份验证（请使用 HTTPS 或 localhost 安全上下文）”

或者浏览器控制台报错：

1
WebSocket connection failed: Mixed Content / Secure Context required

💡 原因分析

现代浏览器（Chrome, Edge, Safari 等）出于安全考虑，禁止在非安全上下文（即非 HTTPS 且非 localhost）中使用某些敏感 API。由于你是通过局域网 IP 访问，不属于 localhost，因此必须启用 HTTPS。

✅ 解决方案：生成自签名证书并启用 HTTPS

1. 生成自签名证书

在服务器上运行以下命令（注意国家代码必须是 2 位，Common Name 必须是您的 IP）：

1
2
3
4
5
6
7
8
9
# 创建证书目录
mkdir -p ~/.openclaw/certs

# 生成自签名证书
openssl req -x509 -newkey rsa:4096 \
  -keyout ~/.openclaw/certs/key.pem \
  -out ~/.openclaw/certs/cert.pem \
  -days 365 -nodes \
  -subj "/C=CN/ST=Beijing/L=Haidian/O=HomeLab/CN=192.168.x.x"

⚠️ 注意：将 CN=192.168.x.x 替换为你的实际 IP 地址。

2. 配置 Gateway 使用证书

编辑配置文件，启用 SSL 并指向证书路径：

1
sudo vi ~/.openclaw/openclaw.json

添加 TLS 配置：

1
2
3
4
5
6
7
8
9
{
  "server": {
    "tls": {
      "enabled": true,
      "certFile": "/home/pi/.openclaw/certs/cert.pem",
      "keyFile": "/home/pi/.openclaw/certs/key.pem"
    }
  }
}

💡 提示：根据实际用户名修改路径，如 /home/ubuntu/ 或 /root/。

3. 重启服务并信任证书

1
sudo openclaw gateway restart

注意：浏览器会提示”连接不安全”，因为是自签名证书。请点击”高级” -> “继续访问”即可。此时，访问地址变为 https://<IP>:18789。

第四关：Pairing Required（设备身份验证）

❌ 现象描述

一切配置就绪，HTTPS 也通了，但页面显示：

1
disconnected (1008): pairing required

或者

1
Pairing required

💡 原因分析

这是 OpenClaw 的零信任安全机制。即使通过了 HTTPS 验证，网关仍不认识这台浏览器设备。首次连接必须经过管理员显式批准，防止未授权控制。

✅ 解决方案：命令行批准设备

在服务器上运行以下命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. 查看待批准的设备列表
openclaw devices list

# 输出示例：
# Request ID: abc123def456
# Device: Chrome on Windows
# Status: pending

# 2. 批准指定设备
openclaw devices approve <requestId>

# 例如：
openclaw devices approve abc123def456

批准成功后，刷新浏览器页面即可正常连接。

快速关闭设备验证（开发/测试环境）

如果是内部测试环境，可以关闭设备身份验证：

1
sudo vi ~/.openclaw/openclaw.json

添加配置：

1
2
3
{
  "dangerouslyDisableDeviceAuth": true
}

⚠️ 警告：此选项会降低安全性，仅建议在受信任的局域网环境中使用。

完整配置示例

以下是一个完整的 openclaw.json 配置示例，适用于局域网部署：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "https://192.168.x.x:18789"
      ]
    }
  },
  "server": {
    "tls": {
      "enabled": true,
      "certFile": "/home/pi/.openclaw/certs/cert.pem",
      "keyFile": "/home/pi/.openclaw/certs/key.pem"
    }
  }
}

卸载

1
2
3
4
5
6
7
8
9
10
11
# 停止并删除容器
docker compose down

# 删除镜像
docker rmi openclaw:local

# 删除命名卷（如果使用了 OPENCLAW_HOME_VOLUME）
docker volume rm openclaw_home

# 删除主机上的配置和数据
rm -rf ~/.openclaw

总结

通过 Docker 部署 OpenClaw 可以：

  • ✅ 获得隔离、可复现的运行环境
  • ✅ 避免污染主机系统
  • ✅ 方便地在多台机器上部署
  • ✅ 快速重置和清理

对于追求开发效率的本地开发，建议使用正常的安装流程。对于生产环境或需要隔离的场景，Docker 是最佳选择。

参考链接：

  • Title: OpenClaw Docker 安装指南 - 快速部署 AI 智能体网关
  • Author: 清夏晚风
  • Created at : 2026-03-23 11:32:56
  • Updated at : 2026-05-29 14:43:35
  • Link: https://blog.yuil.cn/2026/03/23/AI相关工具/OpenClaw Docker 安装指南/
  • License: This work is licensed under CC BY-NC-SA 4.0.
Comments
On this page
OpenClaw Docker 安装指南 - 快速部署 AI 智能体网关
  1. 什么是 OpenClaw？
    1. 核心架构
    2. Docker 适合我吗？
  2. 前置要求
  3. 快速开始（推荐）
    1. 脚本功能
    2. 访问控制界面
    3. 主机目录映射
    4. 关闭https验证：
    5. 允许局域网访问：
  4. 手动部署流程
  5. 环境变量配置
    1. 可选环境变量
    2. 使用示例
  6. 额外挂载配置（可选）
    1. 配置格式
    2. 注意事项
  7. 持久化配置
    1. 方案 1：使用命名卷（推荐）
    2. 方案 2：使用绑定挂载
    3. 删除命名卷
  8. 控制 UI 令牌 + 设备配对
    1. 常见问题
    2. 解决方案
  9. 高级配置
    1. 安装额外的 apt 包
    2. 功能完整的容器（选择加入）
  10. 常用命令
  11. 故障排除
    1. 构建卡在 100%
    2. 权限问题
    3. 端口冲突
  12. 局域网部署常见问题（树莓派/服务器）
    1. 第一关：局域网无法访问（端口监听问题）
    2. 第二关：跨域错误 CORS（白名单配置）
    3. 第三关：安全上下文限制（必须启用 HTTPS）
    4. 第四关：Pairing Required（设备身份验证）
    5. 快速关闭设备验证（开发/测试环境）
    6. 完整配置示例
  13. 卸载
  14. 总结