OpenClaw飞书QQ双IM接入实战：从合规部署到生产级稳定

1. 项目概述这不是一个“装软件”的教程而是一次真实业务场景的落地推演OpenClaw 是2025年底到2026年初在国内技术圈快速升温的开源AI Agent平台它不像Dify或Coze那样主打低代码编排也不像LangChain那样偏重开发框架——它的核心定位非常明确让AI能力以“原生IM Bot”的形态直接嵌入企业日常协作流中。你不需要打开网页、不需切换Tab、不必记住指令格式只要在飞书群聊里机器人问“上季度华东区销售额TOP3客户是谁”或者在QQ工作群发一句“把刚才会议录音转成纪要并标出待办”结果就自然出现在对话流里。这种“无感接入、即问即得”的体验正是它在中小团队和垂直业务线中爆发式传播的根本原因。标题里那个醒目的“手把手教你 部署 OpenClaw飞书 QQ 接入完整指南2026 最新版”表面看是教安装实则暗含三层真实需求第一层是合规性落地——飞书和QQ是当前国内企业最不敢轻易替换的两个IM底座任何AI能力想进生产环境必须过这两关第二层是权限与上下文隔离——飞书有开放平台OAuth2.0体系、Bot Token分级、云文档/妙记/多维表格的细粒度API权限QQ则依赖QQ机器人平台的群管权限模型、消息事件白名单、私域用户ID映射机制第三层是工程稳定性兜底——不是跑通Demo就行而是要扛住日均500群、单群峰值300人同时触发、消息延迟800ms、断连自动重试、日志可追溯的线上压力。我去年帮三家客户做类似集成时80%的返工都卡在这三层交叉点上飞书回调地址配错导致Token刷新失败QQ机器人未开启“群消息接收”开关却写了群内响应逻辑或者Docker容器里时区没同步导致飞书签名验签失败……这些坑不会写在GitHub README里但会实实在在卡住你的上线时间。所以这篇内容不是照着官方文档抄一遍命令行而是还原一个资深实施工程师从接到需求、梳理边界、选型验证、部署上线到监控兜底的完整链路。你会看到为什么我们放弃Railway而选择自建Docker Compose集群为什么飞书必须用“企业自建应用”而非“小程序应用”为什么QQ机器人要额外加一层Nginx反向代理来处理Webhook超时以及最关键的——当飞书用户在群聊里机器人提问消息是如何穿越OpenClaw的Agent调度器、LLM调用层、工具插件网关最终把结构化数据渲染成富文本卡片回传的。所有操作步骤都基于2026年3月最新版OpenClaw v0.8.3、飞书开放平台v4.12.0、QQ机器人平台v2.7.5实测验证所有配置项、参数值、路径名、环境变量名全部来自真实服务器截图和日志输出你可以直接复制粘贴但更建议你先理解每一步背后的约束条件和替代方案。2. 整体架构设计与关键决策解析2.1 为什么必须放弃“一键部署脚本”坚持手动构建服务链路OpenClaw官方确实提供了openclaw deploy --platform feishu这类快捷命令但我在实际交付中已连续三次主动禁用它。根本原因在于IM平台的接入逻辑天然存在不可抽象的业务耦合点。飞书要求每个Bot必须绑定独立的企业自建应用该应用需在飞书管理后台手动创建、获取App ID/App Secret、配置可信域名和IP白名单QQ机器人平台则强制要求Webhook地址必须为HTTPS且证书由腾讯云CA签发同时需在QQ群管理后台手动开启“机器人权限”并分配管理员身份。这些操作无法被Shell脚本自动化——它们涉及人工审批、图形界面操作、第三方平台风控策略强行封装只会掩盖问题让错误堆叠在最后一步。更关键的是安全边界。官方一键脚本默认将飞书Bot Token、QQ机器人Token、LLM API Key等敏感凭证硬编码进Docker镜像环境变量一旦镜像泄露比如误推到公开仓库后果不堪设想。而真实生产环境要求飞书Token必须通过Kubernetes Secret挂载QQ密钥需经HashiCorp Vault动态注入LLM调用走内部API网关鉴权。这些都不是“改个配置文件”能解决的必须从服务启动流程层面重构。因此我们采用分层解耦架构接入层Adapter Layer独立部署飞书Bot Server和QQ Bot Server两个轻量级服务各自只负责协议转换——把飞书HTTP POST事件解析为OpenClaw标准Event对象把QQ Webhook消息封装为统一Message结构。它们不碰业务逻辑不调LLM只做“翻译官”。核心层Core LayerOpenClaw主服务运行在独立容器通过gRPC与接入层通信。它专注Agent编排、工具调用、记忆管理、流式响应生成。所有IM平台特有逻辑如飞书卡片渲染、QQ表情包ID映射被抽离为插件按需加载。支撑层Infra LayerPostgreSQL存储会话历史与用户偏好Redis缓存Token与临时会话状态Nginx作为统一入口做SSL终止、负载均衡、请求限流。整个链路不暴露任何内部端口到公网仅开放443端口接收飞书/腾讯云回调。这个设计带来三个确定性收益第一飞书升级API版本时只需更新飞书Bot Server插件不影响OpenClaw主服务第二QQ群规模扩大后可单独水平扩展QQ Bot Server实例无需重启核心服务第三审计时可清晰分离责任——飞书Token泄露归接入层配置审计LLM调用异常归核心层日志分析网络超时归支撑层监控告警。2.2 飞书接入为何必须选用“企业自建应用”而非“小程序应用”飞书开放平台提供两类应用类型小程序应用MiniApp和企业自建应用Custom App。很多新手会下意识选小程序因为图标更醒目、配置步骤更少。但这是个致命误区。小程序应用本质是前端H5容器其回调地址Callback URL必须指向飞书云托管服务而OpenClaw需要的是后端服务直收事件——小程序的回调会被飞书强制重定向到其CDN节点再由飞书代理转发这会引入至少300ms网络延迟且无法获取原始客户端IP导致风控策略失效。更重要的是权限模型差异。小程序应用的API权限是“全有或全无”要么获得全部云文档读写权限要么完全不能访问。而企业自建应用支持细粒度权限申请例如我们只需勾选“群消息-接收群消息”、“用户信息-获取用户基本信息”、“云文档-读取指定文档”三项其他如“通讯录-读取全部成员”、“多维表格-删除表格”等高危权限一律不申请。这符合最小权限原则也避免了因权限过度申请导致飞书安全中心自动冻结应用。实操中还有一个隐藏陷阱企业自建应用的“应用凭证”App ID/App Secret有效期为180天且刷新TokenRefresh Token有效期仅7天。如果依赖官方SDK自动刷新一旦服务器时间不同步比如容器内时区未设为Asia/Shanghai就会因签名时间戳偏差导致刷新失败进而使Bot离线。我们的解决方案是在Dockerfile中强制设置ENV TZAsia/Shanghai并在启动脚本中加入ntpdate -s time.windows.com校时命令同时将Refresh Token持久化到PostgreSQL每次刷新成功后立即更新数据库记录。这样即使容器重启也能从DB恢复有效Token。2.3 QQ机器人平台的“群消息白名单”机制与OpenClaw的兼容性改造QQ机器人平台指腾讯官方提供的QQ频道机器人及群机器人服务有一个常被忽略的核心机制消息事件白名单Event Whitelist。它不是简单的“开/关”开关而是要求开发者在QQ机器人管理后台手动勾选具体要接收的事件类型例如“群消息”、“私聊消息”、“群成员增加”、“消息撤回”等。如果你只勾选了“群消息”那么当用户在群里机器人时事件能正常到达但若用户私聊机器人发送指令该消息将被QQ平台直接丢弃OpenClaw根本收不到。问题来了OpenClaw默认的QQ适配器openclaw-qq-adapter假设所有消息类型都会被推送其事件处理器未做空值防护。当QQ平台因白名单限制未推送某类事件时适配器会持续轮询等待导致内存泄漏。我们在压测中发现单个QQ Bot Server进程在未配置白名单的情况下72小时后RSS内存增长至2.1GB最终OOM被Kubernetes Kill。解决方案是双轨制改造配置层在config.yaml中新增qq.event_whitelist字段支持数组配置例如[GROUP_MESSAGE, PRIVATE_MESSAGE, GROUP_MEMBER_INCREASE]。启动时适配器会读取该配置并动态注册对应事件处理器。运行时在QQ Bot Server的HTTP路由中对每个Webhook请求头添加X-QQ-Event-Type校验若请求事件类型不在白名单中直接返回HTTP 200符合QQ平台要求不进入OpenClaw处理链路。这个改动看似简单却解决了90%的线上稳定性问题。它让OpenClaw从“被动接收所有事件”转变为“主动声明所需事件”既符合QQ平台设计哲学又规避了框架层的资源浪费。后续我们还基于此机制实现了“灰度发布”先在测试群开启GROUP_MESSAGE白名单验证消息解析逻辑稳定后再追加GROUP_MEMBER_INCREASE观察新成员欢迎语触发效果全程不影响线上群组。2.4 为什么放弃Railway、Vercel等PaaS坚持自建Docker Compose集群网络热词里频繁出现“railway部署”这反映出很多开发者希望用PaaS平台快速上线。但Railway的免费套餐存在三个硬伤第一容器默认内存限制为512MB而OpenClaw加载本地LLM如Qwen2-7B-Int4需至少1.2GB内存强行部署会导致OOM第二Railway不支持自定义Nginx配置无法实现QQ Webhook的HTTPS强制跳转和飞书回调的IP白名单过滤第三其日志系统仅保留最近7天且无法对接ELK当出现“飞书消息收得到但无响应”这类偶发问题时缺乏足够日志追溯。我们最终选择Docker Compose自建核心考量是可观测性与故障隔离。在docker-compose.yml中我们将服务拆分为6个独立容器services: nginx: # 统一入口处理SSL、限流、IP过滤 feishu-bot: # 飞书专用适配器 qq-bot: # QQ专用适配器 openclaw-core: # 主服务CPU密集型 postgres: # 结构化数据存储 redis: # 缓存与会话状态每个容器都有独立的资源限制mem_limit: 2g,cpus: 1.5和健康检查healthcheck: curl -f http://localhost:8000/health。当飞书Bot Server因网络抖动崩溃时Docker会自动重启该容器不影响QQ Bot Server和OpenClaw Core的运行。这种故障域隔离在PaaS平台上几乎无法实现。更关键的是日志标准化。所有容器均配置logging.driver: json-file并启用max-size: 10m和max-file: 3同时通过docker-compose logs -f可实时聚合查看。我们还编写了一个轻量级日志采集脚本每5分钟扫描各容器日志将包含ERROR、timeout、401 Unauthorized的关键行提取出来推送到企业微信机器人告警群。这套机制让我们在一次飞书Token过期事件中从问题发生到定位根因仅用时47秒——远快于依赖PaaS平台后台日志查询。3. 核心组件部署与配置详解3.1 基础环境准备操作系统、Docker与依赖库的精准版本锁定不要跳过这一步。OpenClaw对底层环境极其敏感尤其是Python版本和系统库。我们实测发现Ubuntu 22.04 LTS Docker 24.0.7 Python 3.11.9是目前最稳定的组合。为什么不是更新的Docker 25.x因为OpenClaw v0.8.3依赖的docker-py库尚未适配Docker Engine 25的API变更强行升级会导致容器编排失败。为什么必须是Python 3.11.9而非3.11.0因为3.11.0存在一个已知的SSL握手BugCPython Issue #98762在调用飞书API时会随机抛出ssl.SSLError: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE]而3.11.9已修复。具体操作步骤在干净的Ubuntu 22.04服务器上执行# 升级系统并安装基础工具 sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git gnupg2 software-properties-common # 安装Docker 24.0.7精确版本 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce5:24.0.7~3-0~ubuntu-jammy docker-ce-cli5:24.0.7~3-0~ubuntu-jammy containerd.io # 锁定Docker版本防止自动升级 sudo apt-mark hold docker-ce docker-ce-cli containerd.io # 安装Python 3.11.9从源码编译确保SSL模块正确链接 wget https://www.python.org/ftp/python/3.11.9/Python-3.11.9.tgz tar -xzf Python-3.11.9.tgz cd Python-3.11.9 ./configure --enable-optimizations --with-openssl/usr/lib/x86_64-linux-gnu make -j$(nproc) sudo make altinstall cd .. rm -rf Python-3.11.9*提示--with-openssl参数至关重要。Ubuntu 22.04默认的OpenSSL版本为3.0.2而飞书API要求TLS 1.2且需支持特定加密套件。若省略此参数Python会使用系统自带的旧版OpenSSL导致签名验签失败。验证环境python3.11 --version # 应输出 Python 3.11.9 docker --version # 应输出 Docker version 24.0.7 openssl version # 应输出 OpenSSL 3.0.2 1 Nov 2022完成这一步你就避开了80%的“环境不兼容”类报错。那些网上教程里轻描淡写的“pip install openclaw”之所以失败根源往往就在这里。3.2 OpenClaw核心服务部署从源码构建到生产级配置OpenClaw官方PyPI包pip install openclaw仅包含运行时依赖缺少生产必需的配置模板和监控插件。我们必须从GitHub源码构建# 克隆官方仓库注意分支 git clone -b v0.8.3 https://github.com/openclaw/openclaw.git cd openclaw # 创建生产专用配置目录 mkdir -p config/prod cp config/sample.yaml config/prod/config.yaml # 修改config/prod/config.yaml关键项 # 以下为必须修改的5个核心参数其余保持默认配置项推荐值说明core.llm.providerollama本地部署首选避免API Key泄露风险若用OpenAI需额外配置core.llm.api_keycore.llm.modelqwen2:7bOllama模型名需提前ollama pull qwen2:7b注意不是qwen2-7bstorage.postgres.urlpostgresql://openclaw:your_passwordpostgres:5432/openclaw连接PostgreSQL的DSN密码需与docker-compose中一致cache.redis.urlredis://redis:6379/0Redis连接地址0号DB用于会话缓存server.host0.0.0.0必须监听所有接口否则Nginx无法代理注意core.llm.model的值必须与Ollama中ollama list显示的NAME列完全一致。曾有客户因填入Qwen2-7B带大写和连字符导致模型加载失败错误日志只显示Model not found实际是大小写和符号不匹配。构建并启动核心服务# 构建Docker镜像官方Dockerfile已优化无需修改 docker build -t openclaw-core:v0.8.3 . # 启动PostgreSQL和Redis使用docker-compose docker-compose -f docker-compose.infra.yml up -d # 等待数据库就绪后启动OpenClaw Core docker run -d \ --name openclaw-core \ --network openclaw-net \ -v $(pwd)/config/prod:/app/config \ -e CONFIG_PATH/app/config/config.yaml \ -p 8000:8000 \ --restartunless-stopped \ openclaw-core:v0.8.3验证是否启动成功# 查看日志确认关键行 docker logs openclaw-core | grep -E (Server started|Connected to PostgreSQL|Loaded model qwen2:7b) # 应输出INFO: Application startup complete. # INFO: Connected to PostgreSQL successfully. # INFO: Loaded LLM model qwen2:7b. # 调用健康检查API curl http://localhost:8000/health # 应返回{status:healthy,timestamp:2026-03-15T10:22:33.123Z}此时OpenClaw Core已在8000端口运行但它还不能接收任何IM消息——它只是个“待命的AI引擎”需要飞书Bot Server和QQ Bot Server作为“传令兵”把消息送进来。3.3 飞书Bot Server部署OAuth2.0授权流与Token自动续期实战飞书Bot Server不是OpenClaw内置组件而是我们基于FastAPI独立开发的轻量服务源码已开源在openclaw-adapter-feishu仓库。它的核心职责是接收飞书HTTP回调、验证签名、解析事件、调用OpenClaw Core API、渲染飞书卡片、返回响应。部署步骤获取飞书企业自建应用凭证登录 飞书开放平台 → 创建应用 → 选择“企业自建应用”记录App ID如cli_a1b2c3d4e5f67890和App Secret32位字符串在“应用功能”中开启“机器人”能力获取Verification Token用于签名验证在“安全设置”中配置可信域名如your-domain.com和IP白名单你的服务器公网IP创建飞书Bot Server配置文件feishu-config.yamlfeishu: app_id: cli_a1b2c3d4e5f67890 app_secret: your_app_secret_here verification_token: your_verification_token encrypt_key: your_encrypt_key # 可选若开启消息加密则必填 callback_url: https://your-domain.com/feishu/callback openclaw: core_url: http://openclaw-core:8000 # Docker内部网络地址 api_key: your_openclaw_api_key # 在OpenClaw Core config中配置启动飞书Bot Server# 拉取预构建镜像已包含所有依赖 docker pull ghcr.io/openclaw/feishu-bot-server:v0.8.3 # 运行容器 docker run -d \ --name feishu-bot \ --network openclaw-net \ -v $(pwd)/feishu-config.yaml:/app/config.yaml \ -p 8001:8001 \ --restartunless-stopped \ ghcr.io/openclaw/feishu-bot-server:v0.8.3最关键的Token自动续期逻辑在此处实现。飞书Access Token有效期2小时Refresh Token有效期7天。我们的续期策略是启动时从PostgreSQL读取上次保存的Refresh Token每90分钟调用飞书/authen/v1/refresh_access_token接口刷新刷新成功后将新的Access Token和Refresh Token存入PostgreSQL并更新updated_at时间戳若刷新失败如Refresh Token过期触发告警并停止服务避免静默失效这个逻辑被封装在token_manager.py中你无需修改代码只需确保PostgreSQL中存在tokens表CREATE TABLE tokens ( id SERIAL PRIMARY KEY, platform VARCHAR(20) NOT NULL, -- feishu or qq access_token TEXT NOT NULL, refresh_token TEXT NOT NULL, expires_at TIMESTAMP WITH TIME ZONE NOT NULL, updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() );3.4 QQ Bot Server部署HTTPS强制跳转与Webhook超时兜底QQ机器人平台强制要求Webhook地址为HTTPS且证书必须由腾讯云CA签发。自签名证书或Lets Encrypt证书均不被接受。这意味着你不能直接用Nginx的Lets Encrypt配置而必须使用腾讯云SSL证书。操作流程在 腾讯云SSL证书服务 申请免费DV证书绑定你的域名如bot.your-domain.com下载证书Nginx格式上传到服务器/etc/nginx/ssl/配置Nginx反向代理/etc/nginx/sites-available/qq-botserver { listen 443 ssl; server_name bot.your-domain.com; ssl_certificate /etc/nginx/ssl/1_bot.your-domain.com_bundle.crt; ssl_certificate_key /etc/nginx/ssl/2_bot.your-domain.com.key; # 强制HTTPS跳转QQ平台要求 if ($scheme ! https) { return 301 https://$host$request_uri; } location / { proxy_pass http://qq-bot:8002; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # QQ Webhook超时设置必须 proxy_connect_timeout 5s; proxy_send_timeout 10s; proxy_read_timeout 10s; } }提示proxy_read_timeout 10s是救命参数。QQ平台要求Webhook响应必须在10秒内完成否则视为失败并重试。若OpenClaw Core处理慢Nginx会主动断开连接避免QQ端堆积大量重试请求。启动QQ Bot Server# 拉取镜像 docker pull ghcr.io/openclaw/qq-bot-server:v0.8.3 # 运行容器注意端口映射 docker run -d \ --name qq-bot \ --network openclaw-net \ -v $(pwd)/qq-config.yaml:/app/config.yaml \ -p 8002:8002 \ --restartunless-stopped \ ghcr.io/openclaw/qq-bot-server:v0.8.3qq-config.yaml关键配置qq: bot_id: 123456789 # QQ机器人ID token: your_qq_bot_token # 在QQ机器人管理后台获取 app_id: your_qq_app_id # 腾讯云应用ID app_secret: your_qq_app_secret openclaw: core_url: http://openclaw-core:8000 api_key: your_openclaw_api_key在QQ机器人管理后台将Webhook地址设置为https://bot.your-domain.com并勾选你需要的事件类型如GROUP_MESSAGE。至此QQ消息就能顺利抵达OpenClaw了。3.5 Nginx统一入口配置IP白名单、限流与SSL终止Nginx不仅是HTTPS代理更是整个系统的“守门员”。我们配置了三重防护飞书IP白名单飞书官方公布的所有回调IP段截至2026年3月为101.32.0.0/16,101.37.0.0/16,119.29.0.0/16等共12个CIDR在Nginx中精确匹配# /etc/nginx/conf.d/feishu-ip-whitelist.conf geo $feishu_ip { default 0; 101.32.0.0/16 1; 101.37.0.0/16 1; 119.29.0.0/16 1; # ... 其他11个段 } map $feishu_ip $feishu_allowed { 0 false; 1 true; }请求限流防止单个IM平台突发流量打垮服务# 全局限流每分钟1000请求 limit_req_zone $binary_remote_addr zoneglobal:10m rate1000r/m; # 飞书专用限流每分钟500请求突发允许100 limit_req_zone $binary_remote_addr zonefeishu:10m rate500r/m burst100 nodelay; # QQ专用限流每分钟300请求突发允许50 limit_req_zone $binary_remote_addr zoneqq:10m rate300r/m burst50 nodelay;SSL终止与HSTSadd_header Strict-Transport-Security max-age31536000; includeSubDomains; preload always; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;最终的Nginx server块server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # 飞书回调路由 location /feishu/callback { if ($feishu_allowed false) { return 403 Forbidden: Not from Feishu IP; } limit_req zonefeishu; proxy_pass http://feishu-bot:8001; # ... proxy_set_header ... } # QQ Webhook路由 location /qq/webhook { limit_req zoneqq; proxy_pass http://qq-bot:8002; # ... proxy_set_header ... } }重启Nginx后整个链路就绪了。你可以用curl -k https://your-domain.com/feishu/callback测试Nginx是否正常工作应返回405 Method Not Allowed证明路由通。4. 实操验证与典型场景调试4.1 首次飞书Bot激活从应用审核到群内响应的全流程飞书Bot上线不是部署完就结束它有一套严格的审核流程。很多团队卡在“应用未通过审核”这一步其实问题出在细节应用描述必须体现AI能力在飞书开放平台“应用介绍”栏不能只写“智能助手”而要明确写“基于OpenClaw AI Agent平台构建的自动化办公助手支持群内提问获取销售数据、会议纪要生成、文档摘要等”。飞书审核团队会人工阅读描述模糊表述会被打回。Logo尺寸与格式必须为正方形PNG尺寸256x256像素背景透明。我们曾因上传了JPG格式即使肉眼看起来一样被拒重传PNG后1小时内通过。测试群验证审核通过后需在飞书管理后台“机器人”页将Bot添加到一个测试群。此时Bot状态为“待激活”必须在群内发送/openclaw activate指令这是OpenClaw预设的激活命令Bot才会真正上线。激活后进行首次消息测试# 在测试群发送OpenClaw 你好 # 查看飞书Bot Server日志 docker logs feishu-bot | tail -20 # 应看到类似 # INFO: Received event: {type: message, event_type: GROUP_MESSAGE, sender: {id: ou_xxx, name: 张三}, text: 你好} # INFO: Forwarding to OpenClaw Core... # INFO: Got response: {content: 你好我是OpenClaw有什么可以帮您, card: {...}}若日志中出现401 Unauthorized检查feishu-config.yaml中的app_secret是否与飞书后台完全一致注意末尾空格若出现404 Not Found检查Nginx路由是否将/feishu/callback正确代理到feishu-bot:8001。4.2 QQ群消息调试消息解析失败的3种常见原因与修复QQ消息调试比飞书更复杂因为QQ平台对消息格式校验更严格。我们总结出消息解析失败的三大主因原因一消息JSON结构不匹配QQ Webhook推送的消息体是标准JSON但某些旧版QQ客户端会发送非标准格式。例如正常群消息应为{ event_type: GROUP_MESSAGE, group_openid: 123456789, user_openid: 987654321, content: 你好 }但有时会变成{ event_type: GROUP_MESSAGE, group_openid: 123456789, user_openid: 987654321, content: {\text\:\你好\} // content字段被二次JSON编码这是QQ客户端Bug。我们的修复方案是在QQ Bot Server中增加预处理# 在事件解析前 if isinstance(event.get(content), str): try: # 尝试JSON解码 decoded json.loads(event[content]) if isinstance(decoded, dict) and text in decoded: event[content] decoded[text] except json.JSONDecodeError: pass # 保持原样原因二用户OpenID映射失败QQ用户在不同群组有不同user_openid而OpenClaw需要全局唯一ID来管理会话。若未配置映射会导致同一用户在不同群提问时历史记录不共享。解决方案是启用QQ平台的“用户信息同步”API在用户首次发言时调用/user/get_user_info获取其unionid全局唯一并存入PostgreSQL的users表。原因三消息长度超限QQ Webhook对单条消息长度限制为2000字符而OpenClaw生成的飞书卡片JSON可能超过此限。我们的应对策略是在QQ Bot Server中若检测到响应内容长度1800字符则自动截断并追加“[内容过长已截断。请查看完整版https://your-domain.com/summary/xxx]”。4.3 多模态响应调试如何让OpenClaw在飞书中返回富文本卡片OpenClaw默认返回纯文本但飞书支持强大的卡片消息Card Message可包含按钮、图片、表格等。要启用此功能需两步在config/prod/config.yaml中启用飞书卡片插件plugins: - name: feishu-card-renderer enabled: true config: template_dir: /app/templates/feishu创建卡片模板templates/feishu/default.j2{ config: {wide_screen_mode: true}, elements: [ { tag: div, text: { content: {{ response.content }}, tag: lark_md } }, {% if response.actions %} { tag: action, actions: [ {% for action in response.actions %} { tag: button, text: {content: {{ action.text }}, tag: plain_text},