# Docker 版 OpenClaw 部署飞书插件 - 难点总结

> 日期：2026-03-22  
> 环境：macsvr（192.168.254.104），项目路径：`/home/macsvr/Work/dock-openclawd-ai/`

---

## 一、版本管理问题

### 问题
- Dockerfile 使用本地 `openclaw-dist/` 目录构建镜像，不会自动更新
- 更新 openclaw 需要：先 `npm pack openclaw` 更新 `openclaw-dist/`，再 `docker compose build --no-cache` 重新构建

### 解决方案
```bash
# 在 macsvr 上执行
cd /home/macsvr/Work/dock-openclawd-ai
npm pack openclaw --pack-destination .
tar xzf openclaw-*.tgz -C openclaw-dist/ --strip-components=1
docker compose build --no-cache
docker compose up -d
```

### 注意
- 飞书插件 `@larksuite/openclaw-lark` 版本需 ≤ openclaw 版本，否则报 `Cannot find module` 错误
- 当前 npm 最新版：openclaw `2026.3.13`，飞书插件 `2026.3.18`（插件比主程序新，可能兼容性问题）

---

## 二、文件权限问题

### 问题
容器启动失败，报 `EACCES: permission denied, open '/usr/local/lib/node_modules/openclaw/openclaw.mjs'`

### 根因
Dockerfile 中 `COPY openclaw-dist/` 后用 `chown -R node:node` 修正权限，但如果 `openclaw-dist/` 目录内文件权限本身有问题（如 root 所属），构建后容器内 node 用户无法读取。

### 解决方案
重新 build 镜像（`--no-cache`）会重新执行 chown，通常可解决：
```bash
docker compose build --no-cache && docker compose up -d
```

---

## 三、Gateway Token 不一致

### 问题
`.env` 里的 `OPENCLAW_GATEWAY_TOKEN` 与 `data/config/openclaw.json` 里的 `gateway.auth.token` 不一致，导致：
- 健康检查持续 `token_mismatch`
- Control UI 无法连接

### 优先级
`OPENCLAW_GATEWAY_TOKEN` 环境变量 **优先于** config 文件中的 token。

### 解决方案
保持两者一致，推荐以 config 为准：
```bash
# 修改 .env
OPENCLAW_GATEWAY_TOKEN=openclaw_test_token

# 确认 config 中
# gateway.auth.token = "openclaw_test_token"
```

---

## 四、Control UI 跨机器访问被拒

### 问题
从局域网其他机器浏览器访问 `http://192.168.254.104:20888`，报错：
- `origin not allowed`
- `control ui requires device identity (use HTTPS or localhost secure context)`

### 解决方案
在 `data/config/openclaw.json` 中配置：
```json
{
  "gateway": {
    "controlUi": {
      "allowedOrigins": ["*"],
      "allowInsecureAuth": true,
      "dangerouslyDisableDeviceAuth": true
    }
  }
}
```

> ⚠️ 仅限内网可信环境使用，生产环境应配置 HTTPS

---

## 五、飞书插件安装扫码流程无法在 SSH 中完成

### 问题
`npx @larksuite/openclaw-lark install` 需要交互式 TTY 显示二维码并等待扫码，但：
- SSH 会话超时断开 → 二维码消失
- `docker exec -it` 在非交互式 SSH 环境中不稳定
- tmux/screen 在容器内可用，但 session 管理复杂

### 根因
飞书扫码步骤需要持久 TTY + 人工操作，不适合远程自动化。

### 解决方案
**必须在 macsvr 本地终端直接运行：**
```bash
docker exec -it openclaw-gateway npx @larksuite/openclaw-lark install
```
或在 macsvr 桌面开终端执行，不要通过 SSH 远程跑。

---

## 六、Docker 重启后插件丢失

### 问题
在运行中的容器内安装飞书插件（写入容器层），`docker compose restart` 后插件消失。

### 根因
容器非持久化层在重启时被清空；只有挂载到 volume 的目录（`./data/config:/home/node/.openclaw`）才会保留。

### 解决方案
插件必须安装到 volume 挂载路径：
```bash
# 方法一：在 macsvr 宿主机直接解压到 volume 目录
npm pack @larksuite/openclaw-lark -D /tmp/
tar xzf /tmp/larksuite-openclaw-lark-*.tgz -C /tmp/lark-extract/
cp -r /tmp/lark-extract/package /home/macsvr/Work/dock-openclawd-ai/data/config/extensions/openclaw-lark
cd /home/macsvr/Work/dock-openclawd-ai/data/config/extensions/openclaw-lark
npm install --production

# 方法二：docker compose 中增加 extensions volume 挂载（推荐长期方案）
```

---

## 七、python3 依赖（tmpfs 导致重复安装）

### 问题
`npx @larksuite/openclaw-lark install` 需要 python3，但容器内 `/tmp` 挂载为 tmpfs（`docker-compose.yml` 配置），每次重启后 apt 缓存清空，需重装。

### 解决方案
**修改 Dockerfile**，在构建时预装 python3：
```dockerfile
RUN apt-get update && apt-get install -y python3 && rm -rf /var/lib/apt/lists/*
```
或者移除 docker-compose.yml 中的 tmpfs 配置（会增加容器层大小）。

---

## 最终结论

| 方案 | 状态 | 说明 |
|------|------|------|
| npm 版 openclaw + 飞书 | ✅ 正常运行 | macsvr 本机，已配置飞书 appId，响应正常 |
| Docker 版 openclaw + 飞书 | ⏸ 暂缓 | 扫码配置流程需要本地终端，待后续补全 |

**Docker 版飞书配置的正确姿势（待操作）：**
1. Dockerfile 预装 python3
2. macsvr 本地终端跑 `docker exec -it openclaw-gateway npx @larksuite/openclaw-lark install`
3. 飞书扫码完成后 appId/appSecret 写入 `data/config/openclaw.json`
4. `docker compose restart` 使配置生效