OpenClaw 部署(上)：基于 Docker 快速搭建与调试

📘 文档目的与功能

　　本文档记录了在 Ubuntu 24.04 上通过 Docker 容器化方式 部署 OpenClaw 的完整过程，并解决了部署中的各类典型问题。内容包括从运行安装脚本、模型配置，到容器重启循环的根因、配置修正、设备审批，以及开启特权模式以支持高级功能（如执行主机命令）。通过 Docker 方式，可实现环境隔离、快速迁移与版本管理。

　　如需系统级（原生）部署，见《OpenClaw 部署(下)：系统级原生部署与调试》。

一、环境准备

系统: Ubuntu 24.04
基础环境:
- 更换国内源
- 安装 Docker
- 准备好 AI Key (如百度千帆)
网络: 为避免网络受限，我这里通过代理（如 OpenWrt）上网。

二、安装 OpenClaw

克隆仓库并运行安装脚本：

git clone https://github.com/openclaw/openclaw.git
cd openclaw && chmod +x docker-setup.sh
./docker-setup.sh

2、安全模式选择:

选择 Yes，否则会退出安装

3、配置模型与技能:

选择使用的模型（本文以百度千帆为例）。
百度千帆 Key 获取地址: https://console.bce.baidu.com/qianfan/ais/console/apiKey
配置技能（Hooks），可以选择 Yes 进行配置，也可以跳过后续再配。

4、安装完成提示:

安装成功后，会生成访问 Token，请务必记下。

◇  Dashboard ready ─────────────────────────────────────────────────────╮
│                                                                        │
│  Dashboard link (with token):                                         │
│  http://127.0.0.1:18789/#token=8c165049770c3671cdb1a5d7e24b779c...    │
│  ...                                                                   │
│  Then open:                                                            │
│  http://localhost:18789/                                               │
│  http://localhost:18789/#token=8c165049770c3671cdb1a5d7e24b779c...    │

三、解决容器重启循环问题

安装后，发现容器一直重启。

查看容器状态:

2、查看 Gateway 日志:

docker logs openclaw-openclaw-gateway-1
#报错
Gateway failed to start:Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins

3、原因分析:

这是 OpenClaw 新增的安全强校验机制。如果通过非本地地址访问控制面板，必须声明允许的来源，否则 Gateway 会拒绝启动，导致 Docker 容器不断重启。

4、解决方案:

编辑 OpenClaw 的配置文件 /root/.openclaw/openclaw.json，在配置中增加 controlUi 字段。

    "controlUi": {
            "allowedOrigins": ["https://192.168.20.169"],
            "allowInsecureAuth": true
    },

6、重启容器:

docker restart openclaw-openclaw-gateway-1

四、浏览器提示 `origin not allowed`

原因: OpenClaw 的安全限制，默认只允许 Gateway 主机本地 (127.0.0.1) 访问。
提示含义: 非本地回环（non-loopback）地址访问被拒绝。

解决办法: 本地 SSH 隧道，建议通过nginx反代

#在本地电脑执行（如 Windows PowerShell）：
ssh -N -L 18789:127.0.0.1:18789 -L 18791:127.0.0.1:18791 openclaw@192.168.20.169

五、使用 HTTPS + Nginx 反向代理（推荐）

为了能够通过局域网 IP 正常访问，推荐配置 Nginx 反向代理并启用 HTTPS。

安装 Nginx:

apt install nginx -y
systemctl enable nginx
systemctl start nginx

2、生成自签 SSL 证书（一路回车）:

mkdir -p /etc/nginx/ssl

openssl req -x509 -nodes -days 3650 \
-newkey rsa:2048 \
-keyout /etc/nginx/ssl/openclaw.key \
-out /etc/nginx/ssl/openclaw.crt

3、配置反向代理:

cat > /etc/nginx/conf.d/openclaw.conf << 'EOF'
server {
    listen 443 ssl;
    server_name 192.168.20.169;  # 替换为你的服务器IP

    ssl_certificate     /etc/nginx/ssl/openclaw.crt;
    ssl_certificate_key /etc/nginx/ssl/openclaw.key;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
EOF

#重启 Nginx
systemctl restart nginx

4、通过浏览器访问:

使用 https:// 协议和之前记录的 token 访问。

https://192.168.20.169/#token=8c165049770c3671cdb1a5d7e24b779c1718a20f6974f0ad2361cdd8cb3f2b0e

六、设备配对（Pairing）

首次从浏览器访问，需要将当前设备与 OpenClaw 服务进行配对。

查看待批准的设备列表:

docker exec -it openclaw-openclaw-gateway-1 openclaw devices list

2、批准设备:

复制列表中的设备 ID，执行以下命令：

docker exec -it openclaw-openclaw-gateway-1 openclaw devices approve 97ba919c-9e2f-4f9a-bc26-d56bd093b167

七、开启特权模式（如需高级功能）

如执行主机命令，需要容器以特权模式运行并访问宿主机资源。

修改 docker-compose.yml:
- 编辑 ~/openclaw/docker-compose.yml 文件。
- 在 openclaw-gateway 服务下，增加以下4行配置：

openclaw-gateway:
....
    privileged: true
    network_mode: host
....
      - /var/run/docker.sock:/var/run/docker.sock
      - /:/host
 
#再删除以下3行
          ports:
            - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
            - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"

2、为OpenClaw 启用exec执行工具

编辑/root/.openclaw/openclaw.json,由messaging改成full，然后重启服务
cd ~/openclaw
docker compose down
docker compose up -d

3、验证:

重新访问 Dashboard，现在应该可以在 Agent 中执行更高级的命令了。