memory_research/docker-openclaw-feishu-issues.md

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 重新构建

解决方案

# 在 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，通常可解决：

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 为准：

# 修改 .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 中配置：

{
  "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 本地终端直接运行：

docker exec -it openclaw-gateway npx @larksuite/openclaw-lark install

或在 macsvr 桌面开终端执行，不要通过 SSH 远程跑。

---

六、Docker 重启后插件丢失

问题

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

根因

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

解决方案

插件必须安装到 volume 挂载路径：

# 方法一：在 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：

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 使配置生效