OpenClaw飛書渠道的配置問題排查與解決指南

發(fā)布時間：2026-04-09 09:20:28 作者：AI仙人掌

本文主要分享了OpenClaw從3.28升級到2026.4.7后容器啟動卡住的問題,原因是1Panel鏡像路徑錯誤和舊配置字段不兼容,解決方案包括修改docker-compose.yml添加環(huán)境變量,重建容器并保留該環(huán)境變量，希望對大家有所幫助

問題背景

日期：2026-04-08

版本：1Panel 部署的 OpenClaw，從 3.28（2026.3.28）升級至 2026.4.7

現(xiàn)象：容器啟動后卡住循環(huán)重啟，日志反復(fù)出現(xiàn)：

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
- channels.feishu: unknown channel id: feishu
Run: openclaw doctor --fix

根本原因

原因一：1Panel 鏡像的飛書插件路徑問題

路徑	說明
`OPENCLAW_BUNDLED_PLUGINS_DIR=/app/extensions`	容器默認的 bundled 插件目錄（不含 feishu）
`/app/dist/extensions/feishu/`	feishu 插件的實際位置（編譯好的 `.js` 版本）

結(jié)論：1Panel 的 openclaw:latest 鏡像打包時，/app/extensions/ 目錄里沒有包含 feishu 插件，但 feishu 的編譯版本存在于 /app/dist/extensions/feishu/。環(huán)境變量指向錯誤，導(dǎo)致 openclaw 始終找不到 feishu 插件。

原因二：舊版配置字段不兼容

舊配置中包含以下字段，在新版本 schema 嚴格校驗下不被支持，會導(dǎo)致 must NOT have additional properties 錯誤：

"replyInThread": "disabled",
"topicSessionMode": "disabled",
"reactionNotifications": "own",
"renderMode": "card",
"actions": { "reactions": true },
"typingIndicator": true,
"resolveSenderNames": true,
"streaming": true,
"blockStreaming": true,
"textChunkLimit": 2000,
"mediaMaxMb": 30,
"webhookPath": "/feishu/events"

注意：typingIndicator、resolveSenderNames、streaming 等字段在 2026.4.x 版本中已移至插件內(nèi)部默認值，不再允許在 channel 配置中手動指定。

解決方案

步驟一：修改 docker-compose.yml（需要 root 權(quán)限）

文件路徑：/opt/1panel/apps/openclaw/openclaw/docker-compose.yml

在 environment 下添加一行環(huán)境變量，并將鏡像版本指定為 2026.4.7：

environment:
    HOME: /home/node
    TERM: xterm-256color
    OPENCLAW_BUNDLED_PLUGINS_DIR: /app/dist/extensions  # ← 新增此行
image: 1panel/openclaw:2026.4.7                         # ← 指定版本

作用：將 openclaw 的 bundled 插件目錄覆蓋為 /app/dist/extensions，使其能正確找到 feishu 插件。

步驟二：重建容器

docker stop 1Panel-openclaw-7tjZ
docker rm 1Panel-openclaw-7tjZ
cd /opt/1panel/apps/openclaw/openclaw
docker compose up -d

或在 1Panel 管理面板中保存配置后重啟。

步驟三：寫入正確的飛書 channel 配置

容器啟動后執(zhí)行：

docker exec 1Panel-openclaw-7tjZ python3 -c "
import json

with open('/home/node/.openclaw/openclaw.json', 'r') as f:
    config = json.load(f)

# 添加 feishu 插件
plugins = config.setdefault('plugins', {})
allow = plugins.setdefault('allow', [])
if 'feishu' not in allow:
    allow.append('feishu')
plugins.setdefault('entries', {})['feishu'] = {'enabled': True, 'config': {}}

# 寫入 feishu channel 配置（僅使用 2026.4.x 支持的字段）
config['channels']['feishu'] = {
    'enabled': True,
    'defaultAccount': 'main',
    'accounts': {
        'main': {
            'appId': 'cli_a94ba863b9f9dcb1',
            'appSecret': 'DWJWRZMIqMRIXriLsxNBYfTw'
        },
        'hoare': {
            'appId': 'cli_a948989a8879dcd3',
            'appSecret': 'z2Xj6thGjUzHccuFDwBfCjbN8'
        }
    },
    'domain': 'feishu',
    'connectionMode': 'websocket',
    'dmPolicy': 'open',
    'allowFrom': ['*'],
    'groupPolicy': 'open',
    'requireMention': True
}

with open('/home/node/.openclaw/openclaw.json', 'w') as f:
    json.dump(config, f, indent=2, ensure_ascii=False)
print('配置寫入完成')
"

驗證成功的標志

容器日志出現(xiàn)以下內(nèi)容即為成功：

[gateway] feishu_doc: Registered feishu_doc, feishu_app_scopes
[gateway] feishu_chat: Registered feishu_chat tool
[gateway] feishu_wiki: Registered feishu_wiki tool
[gateway] feishu_drive: Registered feishu_drive tool
[gateway] feishu_bitable: Registered bitable tools
[gateway] ready (4 plugins, 1.4s) ← 插件數(shù)從3變4
[feishu] feishu[main]: bot open_id recovered: ou_xxx ← WebSocket連接成功

最終配置狀態(tài)

docker-compose.yml 關(guān)鍵配置

environment:
    HOME: /home/node
    TERM: xterm-256color
    OPENCLAW_BUNDLED_PLUGINS_DIR: /app/dist/extensions
image: 1panel/openclaw:2026.4.7

openclaw.json 飛書 channel 配置（2026.4.x 兼容版）

"feishu": {
  "enabled": true,
  "defaultAccount": "main",
  "accounts": {
    "main": {
      "appId": "cli_a94ba863b9f9dcb1",
      "appSecret": "DWJWRZMIqMRIXriLsxNBYfT"
    },
    "hoare": {
      "appId": "cli_a948989a8879dcd3",
      "appSecret": "z2Xj6thGjUzHccuFDwBfCjbN8"
    }
  },
  "domain": "feishu",
  "connectionMode": "websocket",
  "dmPolicy": "open",
  "allowFrom": ["*"],
  "groupPolicy": "open",
  "requireMention": true
}

問題根因（兩個）

鏡像路徑問題：1Panel 的 openclaw 鏡像默認 OPENCLAW_BUNDLED_PLUGINS_DIR=/app/extensions，但 feishu 插件實際在 /app/dist/extensions/feishu/，路徑對不上所以始終報 unknown channel id: feishu

配置字段不兼容：舊配置里的 replyInThread、topicSessionMode、renderMode、typingIndicator 等字段在新版本 schema 嚴格校驗下不被支持