Chatwoot AI 客服系统 — 项目总结
日期：2026-05-28
项目：GreatQiu.cn 外贸代理站 AI 客服系统
一、项目背景
为 GreatQiu.cn（外贸代理站）搭建 AI 客服系统，替代原有的 FluentForm 联系表单，实现：
- 在线实时聊天（Web Widget）
- AI 自动回复（多语言自适应）
- 后台客服协作（中文翻译私密备注）
- 自托管，数据自主可控
二、系统架构
客户 → 网站 Widget → Chatwoot (自托管) → 轮询脚本 → QwenPaw AI → 回复客户
↓
中文私密备注 → 后台客服可见
组件清单
| 组件 | 详情 |
|---|---|
| Chatwoot | 自托管 v4.14.0，地址 chatwoot.275763.xyz |
| AI 引擎 | QwenPaw default agent（xiaomi/mimo-v2.5-pro） |
| 轮询脚本 | chatwoot_agent.py，系统 cron 每 2 分钟执行 |
| Session 管理 | 自动续期（POST /auth/sign_in，<6h 刷新） |
| WordPress 集成 | WPCode snippet #104 嵌入 Widget SDK |
| CDN | 腾讯云 EdgeOne（支持 WebSocket） |
三、核心功能
1. Widget 在线聊天
- 网站右下角蓝色聊天气泡
- 客户无需注册即可发起对话
- 实时消息推送（WebSocket 通道）
2. AI 自动回复
- 检测客户消息语言，同语言回复
- 专业性：GreatQiu 全球采购代理定位
- 签名：
- GreatQiu Team - 回复失败时自动降级为人工待回复提示
3. 后台客服翻译
- 每次客户消息自动翻译成中文私密备注
- 后台客服无需懂英文即可了解客户需求
4. Session 自动续期
- Chatwoot 会话 token 有效期约 24 小时
- 轮询脚本自动检测 expiry，<6 小时自动续期
- 持久化存储到
chatwoot_auth.json
四、部署历程
阶段一：基础部署
- Chatwoot Docker 部署（用户手动完成）
- 管理员账号配置，创建 Website Inbox #1，获取 Widget Token
阶段二：Widget 接入
- WPCode 嵌入 SDK 到 WordPress 头部
- CSP 修复：nginx 添加
frame-ancestors策略解决 iframe 加载问题 - CDN 切换：从阿里云 ESA 切换到腾讯云 EdgeOne 以支持 WebSocket
- Widget 正常显示，后台回复前台可见 ✅
阶段三：API 打通
- 发现个人 API Token 对大部分端点返回 401
- 解决方案：使用 session-based auth（4 headers：access-token/client/expiry/uid）
- 验证通过：所有 Chatwoot API 端点可用
阶段四：AI 集成
- 使用 QwenPaw
agents chat调用 AI（避免 agent 身份冲突） - 多语言自适应回复测试通过
阶段五：轮询与通知
- 容器环境入站不通（端口未映射），只能往外请求
- 方案：轮询 Chatwoot API（每 2 分钟）
微信通知→ 改为后台私密备注（更直接）- Session 自动续期机制
五、关键决策
| 决策 | 原因 |
|---|---|
| 自托管 Chatwoot 而非 SaaS | 数据自主可控、可对接 AI/WhatsApp |
| 轮询而非 Webhook | 容器入站不通，只支持往外请求 |
| Session auth 而非 API Token | API Token 401，session headers 全面可用 |
| QwenPaw AI 而非 OpenAI | 用户无 OpenAI key，用平台自身 AI |
| 系统 Cron 而非 Daemon | 容器 daemon 启动复杂，cron 自带自动重启 |
| 后台私密备注而非微信通知 | 客服直接在 Chatwoot 后台查看，更高效 |
六、脚本功能
文件：chatwoot_agent.py
| 参数 | 用途 |
|---|---|
| （无参数） | 单次运行（cron 模式） |
--daemon |
前台 daemon 循环 |
--daemonize |
后台 daemon（double-fork） |
--dry-run |
检查但不处理 |
--renew |
手动刷新 session token |
--reset |
重置消息追踪器 |
七、配置要点
Chatwoot 凭据
- 地址：
https://chatwoot.275763.xyz - 登录：
qiuzhida@greatqiu.cn/ 后台密码 - Account ID: 1
- Website Token: token（Inbox #1）
Session 认证
- 自动存储在
chatwoot_auth.json（自动续期） - 手动续期：
python3 chatwoot_agent.py --renew
WordPress 集成
- WPCode Snippet #104: "Chatwoot Live Chat Widget"
- 嵌入位置：Site Wide Header（全站头部）
八、后续可扩展
- WhatsApp 集成（用户自行操作）
- 微信通知恢复（代码已保留）
- AI 回复质量监控
- 知识库增强（常见问题自动应答）