Docker 部署问题

编号格式 #NNNNN 对应 GitHub issue，可直接搜索去重。

容器重启后无限登录循环

来源：GitHub #29955（2026-01）

现象：Docker 容器重启后，每次都要重新登录，无法维持会话状态。表现为缺少 Set-Cookie header，浏览器不断跳转到登录页。

原因：未配置 SESSION_SECRET 环境变量。每次容器重启都会随机生成新的 secret，导致所有现有 session 立即失效，进入登录循环。

解决方法：在容器环境变量中设置一个持久固定的 SESSION_SECRET：

bash

# 生成一个随机 secret（只生成一次，保存好）
openssl rand -hex 32

Docker Compose（.env 文件）：

env

SESSION_SECRET=<上面生成的随机字符串>

Fly.io：

bash

fly secrets set SESSION_SECRET=<随机字符串>

警告：SESSION_SECRET 一旦设置就不要修改，否则所有用户的 session 都会失效。

来源：GitHub #30080（2026-02）

现象：在 QNAP NAS 的 Docker 部署中，Gateway 启动后无响应，health check 超时。

原因：QNAP 的网络层对回环地址（loopback）有特殊处理，与 OpenClaw Gateway 的回环地址策略冲突，导致端口转发失败。

解决方法：

方案 1：在 openclaw.json 中将 Gateway bind 改为 lan 模式：

json5

{
  gateway: {
    bind: "lan"
  }
}

方案 2：改用 Docker host 网络模式（跳过 Docker 网络层）：

yaml

# docker-compose.yml
services:
  openclaw-gateway:
    network_mode: host