安装相关问题

本页收录近期 GitHub Issues 中高频出现的安装问题，精选有明确解决方案的案例。

---

问题 1：Windows CLI 冷启动极慢（10-14 秒）

来源：GitHub #30072（2026-02）

现象：升级到 v2026.2.26 后，Windows 上 CLI 冷启动时间从约 3 秒退化到 10-14 秒。

原因：该版本 dist 文件数量增加了 433 个，导致 Windows 文件 I/O 在启动时阻塞。Linux/macOS 不受影响。

解决方法：

1. 降级到 v2026.2.19（已确认不受影响）：

   npm install -g openclaw@2026.2.19

2. 等待官方修复（已列入 backlog）。

注意：此问题仅影响 Windows 原生环境，WSL2 不受影响。这也是推荐 Windows 用户使用 WSL2 的原因之一。

---

问题 2：容器重启后无限登录循环

来源：GitHub #29955（2026-01）

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

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

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

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

# Docker Compose 方式（在 .env 文件中）
SESSION_SECRET=<上面生成的随机字符串>

# Fly.io 方式
fly secrets set SESSION_SECRET=<随机字符串>

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

---

问题 3：QNAP NAS / 非标准 Docker 部署卡死

来源：GitHub #30080（2026-02）

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

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

解决方法：

1. 禁用回环限制：在 openclaw.json 中将 Gateway bind 改为 lan 模式：

   {
     "gateway": {
       "bind": "lan"
     }
   }

2. 或改用 Docker host 网络模式（跳过 Docker 网络层）：

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

---

另见

• Gateway 启动问题
• 安装总览