OpenClaw 龙虾 Docker 部署指南（小蜘蛛版）

如果你更习惯容器化部署，可以直接沿着这篇完成 OpenClaw 的 Docker 版本搭建。

本文由群友”小蜘蛛”使用 Claude 总结，感谢贡献。

部署完整指南#

基于实际部署经验整理，包含所有遇到的问题及解决方案。环境：Linux + Docker 29.2.1 + Docker Compose v5.1.0

一、环境准备#

1
## 确认 Docker 和 Docker Compose 已安装
2
docker --version
3
docker compose version

二、获取源码#

1
git clone https://github.com/openclaw/openclaw.git
2
cd ~/openclaw

三、构建镜像并初始化配置#

运行官方脚本，自动完成镜像构建 + 交互式配置向导：

1
chmod +x docker-setup.sh
2
./docker-setup.sh

向导中的填写建议：

提示项	填写值
Gateway bind	`lan`
Gateway auth	`token`
Gateway token	脚本自动生成，记录备用
Tailscale exposure	Off
Install Gateway daemon	No

脚本执行完毕后会自动生成： - `~/openclaw/.env` — 环境变量配置文件 - `~/.openclaw/` — 配置目录（API Key、记忆等） - `~/.openclaw/workspace/` — Agent 工作目录 --- ## 四、配置 AI 提供商（API Key）编辑 `~/.openclaw/openclaw.json`，在 `models.providers` 中添加： ```plain text { "models": { "mode": "merge", "providers": { "zhipu": { "baseUrl": "https://api.edgefn.net/v1", "apiKey": "your-api-key-here", "api": "openai-completions", "models": [ { "id": "GLM-5", "name": "GLM-5 (Custom Provider)", "api": "openai-completions", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 200000, "maxTokens": 8192 } ] } } } } ``` \\> **Base URL 填写规则（重要）：** \\> 填 \\`https://your-api-host.com/v1\\`，**不要**加 \\`/chat/completions\\` > 客户端会自动拼接 `/chat/completions`，手动加上会导致 404 错误。 --- ## 五、端口与目录映射说明 `docker-compose.yml` 默认配置：

映射类型	宿主机	容器内	说明
端口（Web UI）	`18789`	`18789`	Gateway 控制面板
端口（Bridge）	`18790`	`18790`	内部通信端口
目录（配置）	`~/.openclaw`	`/home/node/.openclaw`	配置持久化（必须映射）
目录（工作区）	`~/.openclaw/workspace`	`/home/node/.openclaw/workspace`	Agent 文件读写（必须映射）

--- ## 六、启动 Gateway ```plain text cd ~/openclaw docker compose --env-file .env up -d openclaw-gateway ``` **首次启动约需 8～10 分钟**（jiti 运行时 JIT 编译数百个 ESM 模块），后续重启因有缓存会快很多。查看启动日志： ```plain text docker compose logs -f openclaw-gateway ``` 启动成功标志： ```plain text [gateway] listening on ws://0.0.0.0:18789 (PID 7) bonjour: advertised gateway fqdn=... state=announcing ``` --- ## 七、常见问题及解决方案 ### 问题 1：端口已被占用 `address already in use`

原因： 原生 openclaw-gateway 进程已占用默认端口。

解决： 修改 ~/openclaw/.env 中的端口：

1
OPENCLAW_GATEWAY_PORT=18790   # 改为未占用的端口
2
OPENCLAW_BRIDGE_PORT=18793

检查可用端口：

1
ss -tlnp | grep 1879

问题 2：`Permission denied` 配置目录无法写入#

原因： 配置目录由 root(uid=0) 创建，容器以 node(uid=1000) 运行，无写权限。

解决：

1
## 方案 A：开放所有权限（快速）
2
chmod -R 777 ~/.openclaw
3

4
## 方案 B：更规范，改变所有者为 uid=1000
5
chown -R 1000:1000 ~/.openclaw

问题 3：`Missing config. Run openclaw setup`#

原因： 容器内 node 用户无法读取配置目录。

解决： 同问题 2，修复 ~/.openclaw 目录权限后重启容器：

1
chmod -R 755 ~/.openclaw
2
chmod 644 ~/.openclaw/openclaw.json
3
docker compose --env-file .env restart openclaw-gateway

问题 4：`Gateway failed to start: non-loopback Control UI requires gateway.controlUi.allowedOrigins`#

原因： 使用 --bind lan 模式时，网关要求配置 CORS 来源。

解决： 在 ~/.openclaw/openclaw.json 的 gateway 字段添加：

1
"gateway": {
2
  "mode": "local",
3
  "auth": {
4
    "mode": "token",
5
    "token": "your-token-here"
6
  },
7
  "controlUi": {
8
    "dangerouslyAllowHostHeaderOriginFallback": true
9
  }
10
}

问题 5：Web UI 显示”健康状态离线 / 已断开连接”#

原因： 浏览器 WebCrypto API 要求 HTTPS 或 localhost 安全上下文，通过 HTTP 公网 IP 访问时无法建立设备身份。 解决（HTTP 临时方案）： 在 ~/.openclaw/openclaw.json 中配置：

1
"gateway": {
2
  "controlUi": {
3
    "dangerouslyAllowHostHeaderOriginFallback": true,
4
    "allowInsecureAuth": true,
5
    "dangerouslyDisableDeviceAuth": true
6
  }
7
}

修改后重启容器生效：

1
docker compose --env-file .env restart openclaw-gateway

⚠️ 以上三个 dangerously* 标志会降低安全性，适合内网或个人使用。生产环境建议配置 HTTPS（见下方远程访问方式三）。

八、远程访问方式#

方式一：直接 IP 访问（HTTP）#

1
http://<服务器IP>:18790/?token=<your-token>

Token 查看方式：

1
grep OPENCLAW_GATEWAY_TOKEN ~/openclaw/.env
2
## 或查看配置文件
3
cat ~/.openclaw/openclaw.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['gateway']['auth']['token'])"

方式二：SSH 隧道（更安全）#

在本地机器执行：

1
ssh -N -L 18790:localhost:18790 user@<服务器IP>

浏览器访问：

1
http://localhost:18790/?token=<your-token>

方式三：Nginx 反向代理 + HTTPS（推荐）#

1
server {
2
    listen 443 ssl;
3
    server_name openclaw.yourdomain.com;
4

5
    ssl_certificate     /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
6
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
7

8
    location / {
9
        proxy_pass http://127.0.0.1:18790;
10
        proxy_http_version 1.1;
11
        proxy_set_header Upgrade $http_upgrade;
12
        proxy_set_header Connection "upgrade";
13
        proxy_set_header Host $host;
14
        proxy_set_header X-Real-IP $remote_addr;
15
    }
16
}

配置 HTTPS 后可移除 `dangerously*` 标志，恢复默认安全设置。#

九、常用运维命令#

1
cd ~/openclaw
2

3
## 查看容器状态
4
docker compose ps
5

6
## 查看实时日志
7
docker compose logs -f openclaw-gateway
8

9
## 查看 openclaw 详细日志（含错误信息）
10
docker exec openclaw-openclaw-gateway-1 tail -50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
11

12
## 重启服务
13
docker compose --env-file .env restart openclaw-gateway
14

15
## 停止服务
16
docker compose down
17

18
## 重新构建镜像（更新版本后）
19
docker build -t openclaw:local -f Dockerfile .
20

21
## Token 丢失时重新获取
22
docker compose run --rm openclaw-cli dashboard --no-open

十、完整 `.openclaw/openclaw.json` 配置参考#

1
{
2
  "meta": {
3
    "lastTouchedVersion": "2026.2.25"
4
  },
5
  "models": {
6
    "mode": "merge",
7
    "providers": {
8
      "zhipu": {
9
        "baseUrl": "https://api.edgefn.net/v1",
10
        "apiKey": "your-api-key",
11
        "api": "openai-completions",
12
        "models": [
13
          {
14
            "id": "GLM-5",
15
            "name": "GLM-5 (Custom Provider)",
16
            "api": "openai-completions",
17
            "reasoning": false,
18
            "input": ["text"],
19
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
20
            "contextWindow": 200000,
21
            "maxTokens": 8192
22
          }
23
        ]
24
      }
25
    }
26
  },
27
  "agents": {
28
    "defaults": {
29
      "model": { "primary": "zhipu/GLM-5" },
30
      "compaction": { "mode": "safeguard" },
31
      "maxConcurrent": 4,
32
      "subagents": { "maxConcurrent": 8 }
33
    }
34
  },
35
  "gateway": {
36
    "mode": "local",
37
    "auth": {
38
      "mode": "token",
39
      "token": "your-gateway-token"
40
    },
41
    "controlUi": {
42
      "dangerouslyAllowHostHeaderOriginFallback": true,
43
      "allowInsecureAuth": true,
44
      "dangerouslyDisableDeviceAuth": true
45
    }
46
  }
47
}

十一、.env 文件参考#

1
OPENCLAW_CONFIG_DIR=/root/.openclaw
2
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
3
OPENCLAW_GATEWAY_PORT=18790
4
OPENCLAW_BRIDGE_PORT=18793
5
OPENCLAW_GATEWAY_BIND=lan
6
OPENCLAW_GATEWAY_TOKEN=your-token-here
7
OPENCLAW_IMAGE=openclaw:local
8
OPENCLAW_EXTRA_MOUNTS=
9
OPENCLAW_HOME_VOLUME=
10
OPENCLAW_DOCKER_APT_PACKAGES=

文档生成时间：2026-02-26