WTO AI 客服 - 接入文档

快速开始

本系统是一套可独立部署的多平台 AI 客服系统，基于 PHP 8 + MySQL 构建，不需要 Composer 或 Node.js 构建环境。完成部署后，你可以在一个后台里管理 AI 客服、知识库、渠道、会话、套餐与订单。

推荐流程：安装系统 → 在后台配置 AI 供应商 → 创建 AI 客服并绑定知识库 → 创建渠道并填写平台回调参数 → 在网站中嵌入挂件或对外提供 API。

环境要求

项目	要求
PHP	8.0 及以上（推荐 8.1 / 8.2），需启用 PDO MySQL、OpenSSL、cURL、mbstring、ZipArchive
数据库	MySQL 5.7+ 或 8.0，字符集 utf8mb4
Web 服务器	Nginx 或 Apache，需支持 URL 重写；也可使用 PHP 内置服务器做本地体验
扩展（可选）	Redis（缓存）、zlib（二维码 PNG 压缩，缺失时自动降级）、pdftotext（PDF 解析备用方案）
目录权限	`storage/`、`config/` 需可写，用于缓存、日志、上传文件与安装配置

PHP 配置建议：upload_max_filesize 与 post_max_size 不低于 10M，max_execution_time 不低于 60 秒，以便处理知识库文件上传与 AI 请求。

安装部署

1. 上传代码

将程序文件上传到网站根目录，确保 Web 服务器的站点根目录指向项目根目录（包含 index.php）。如果部署在子目录，系统会自动识别基础路径。

2. 配置伪静态

Apache 会读取项目自带的 .htaccess。Nginx 请添加：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ ^/(config|storage|database)/ {
    deny all;
}

3. 运行安装向导

浏览器访问站点域名，系统会自动跳转到 install.php。按向导填写数据库地址、库名、用户名、密码，以及管理员账号与站点信息。安装器会：

检测 PHP 版本、扩展与目录权限；
创建数据库（如不存在）并导入数据表；
写入站点设置、默认套餐与 AI 供应商模板；
生成 config/config.php 与安装锁文件。

安装完成后请删除或重命名 install.php，并确认 config/、storage/ 无法通过浏览器直接访问。

4. 登录后台

访问 /admin 使用安装时创建的管理员账号登录，先完成「系统设置 → AI 供应商 → 套餐」的基础配置。

AI 供应商

进入「管理后台 → AI 供应商」添加模型服务。系统内置以下类型的适配器：

类型	说明	Base URL 示例
OpenAI / 兼容接口	标准 Chat Completions 协议	`https://api.openai.com/v1`
DeepSeek	DeepSeek 开放平台	`https://api.deepseek.com/v1`
通义千问	DashScope 兼容模式	`https://dashscope.aliyuncs.com/compatible-mode/v1`
豆包	火山方舟兼容接口	`https://ark.cn-beijing.volces.com/api/v3`
Azure OpenAI	需填写部署名与 api-version	`https://你的资源.openai.azure.com`
COZE	扣子智能体 v2 对话接口	按 COZE 控制台提供的 API 地址
Dify	Dify 应用 chat-messages 接口	`https://api.dify.ai/v1`
自定义	任意 OpenAI 兼容服务	你的服务地址

API Key 会使用应用密钥进行 AES-256-GCM 加密后入库，不会以明文保存。添加后可在列表中点击「测试」验证连通性。

系统级供应商由管理员统一维护，用户创建 AI 客服时可直接选用；用户也可以添加自己的供应商。

创建 AI 客服

在「控制台 → AI 客服 → 新建」中配置：

供应商与模型：选择已启用的 AI 供应商，可覆盖默认模型名；
人设提示词：定义客服身份、语气、边界与转人工策略；
温度与最大 Token：温度越高回答越发散，客服场景建议 0.3–0.7；
上下文记忆：携带最近 N 轮对话，轮数越多成本越高；
回复延迟：设置随机延迟区间，模拟真人打字节奏；
欢迎语、触发关键词、前后缀：控制首次接待与特定场景话术；
语音开关：为挂件预留语音播报能力。

保存后可在编辑页使用「测试对话」验证效果，系统会实时返回模型输出与命中的知识库来源。

知识库与问答

知识库支持上传 TXT、Markdown、CSV、JSON、HTML、XML、DOCX、PPTX、PDF，也支持直接粘贴文本。系统会抽取纯文本并按约 600 字切分、80 字重叠，建立关键词索引。

用户提问时，系统会：

先匹配该客服绑定的「常见问题」标准答案；
再检索相关知识库分块，把最相关的内容注入提示词；
要求模型优先依据知识库回答，资料不足时如实说明并引导转人工。

一个知识库可以绑定一个 AI 客服；一个客服也可以同时使用多个知识库。修改文档后可点击「重新索引」重建分块。

渠道接入总览

每个渠道创建后会生成唯一的回调地址：

https://www.wtoweld.com/webhook/wh_xxxxxxxxxxxxxxxx

将回调地址与渠道配置中的 Token、EncodingAESKey、Secret 等参数填入对应平台后台。渠道未绑定 AI 客服时，系统会自动使用该账号下最早创建的启用客服。

微信客服 / 微信小程序客服

需要：企业 CorpID、微信客服 Secret、回调 Token、EncodingAESKey、客服账号 ID（open_kfid）。

在微信客服管理后台开启「API 接收消息」，回调 URL 填上面的地址；
系统通过 sync_msg 拉取消息并调用 send_msg 回复；
仅处理来源为客户的文本消息，事件推送不触发 AI；
小程序客服使用相同的企业微信客服接口，选择「微信小程序客服」类型即可。

微信公众号

需要：AppID、AppSecret、服务器 Token，安全模式下还需 EncodingAESKey。

在公众号后台「服务器配置」中填写回调 URL 与 Token；
系统校验签名并解密消息，通过客服消息接口回复文本；
公众号需已认证并具备客服消息接口权限，且用户需在 48 小时内与公众号互动。

企业微信应用

需要：企业 CorpID、应用 Secret、应用 AgentId、回调 Token、EncodingAESKey。

在企微管理后台「应用管理 → 接收消息」中设置回调 URL；
系统解密消息后调用应用消息发送接口回复；
适用于内部员工咨询与客户联系场景，需确保应用可见范围已配置。

钉钉机器人

需要：机器人加签密钥（可选机器人 Code）。

在钉钉开放平台创建企业内部机器人，消息接收模式选择 HTTP 推送；
系统校验 timestamp 与 sign，处理文本消息；
使用回调中的 sessionWebhook 直接回复，无需额外配置发送地址。

飞书机器人

需要：App ID、App Secret，可选 Verification Token 与 Encrypt Key。

在飞书开放平台创建应用并开启「接收消息」事件 im.message.receive_v1；
事件订阅地址填回调 URL；如启用加密，填写 Encrypt Key；
系统会处理 URL 校验、消息解密与文本回复，自动忽略机器人自身消息。

个人微信网关

用于接入你自行部署且符合平台规范的微信网关。系统不提供个人微信协议实现，仅提供标准化回调：

POST https://www.wtoweld.com/webhook/wh_xxxxxxxxxxxxxxxx
{
  "user_id": "wxid_xxx",
  "nickname": "客户昵称",
  "message": "你好，请问在吗？"
}

如配置了接口密钥，需要在请求头携带 X-Webhook-Secret。系统同步返回：

{
  "ok": true,
  "reply": "你好，我在的，请问有什么可以帮你？",
  "conversation_id": 123
}

请仅接入已获得授权、符合微信平台规范的账号。使用非官方协议可能违反平台规则并导致封号，风险由使用者自行承担。

在「AI 客服 → 网站挂件」页面可获取专属挂件 Key 与嵌入代码。将以下代码放到网站页面 </body> 之前：

挂件会自动创建右下角气泡与对话面板，支持：

读取客服名称、欢迎语与头像；
以 localStorage 保存访客标识与会话 ID，刷新后继续对话；
轮询人工坐席回复，AI 接待与转人工状态实时展示；
移动端自适应，不依赖任何前端框架。

如需自定义挂件外观，可直接调用接口自行实现界面：

接口	方法	说明
`/api/widget/config?key=挂件Key`	GET	获取客服名称、欢迎语等配置
`/api/widget/chat`	POST	发送消息，参数：key、visitor_id、message、conversation_id
`/api/widget/history?key=&visitor_id=&conversation_id=&after_id=`	GET	增量拉取会话消息

挂件接口允许跨域访问，单 IP 每分钟最多 40 次消息请求。

开放 API

在「控制台 → API 密钥」创建 Key，绑定一个 AI 客服。请求头使用 Authorization: Bearer <API Key>。

curl -X POST 'https://www.wtoweld.com/api/v1/chat' \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"message":"你们支持私有化部署吗？","user_id":"u_1001"}'

响应示例：

{
  "ok": true,
  "message": "ok",
  "data": {
    "conversation_id": 128,
    "reply": "支持。系统采用 PHP + MySQL 独立部署……",
    "tokens": 386,
    "model": "deepseek-chat",
    "sources": []
  }
}

可选参数：conversation_id 继续已有会话；user_id 或 visitor_id 标识终端用户。单 Key 每分钟最多 120 次请求。

接口同时支持 application/json 与表单编码。会话按 conversation_id + user_id 隔离，未传用户标识时会按 IP 与 UA 生成匿名标识。

计费与套餐

每次 AI 回复会记录 Token 消耗：

优先使用 AI 客服绑定的套餐，未绑定时使用账号当前有效套餐；
套餐内 Token 额度用完后，超出部分按「每千 Token 单价」从余额扣除；
套餐会话额度同样受限，额度耗尽且余额为零时会拒绝新的 AI 请求；
充值、退款、消费均写入用量记录，可在控制台筛选导出。

在线支付支持迅虎支付与微信支付 v3，可在后台「系统设置 → 支付通道」选择自动、迅虎或微信。迅虎支付填写 APPID、APPSECRET 后启用，回调地址为 /pay/notify/xunhu；微信支付需配置 AppID、商户号、证书序列号、商户私钥、APIv3 密钥与回调地址。未配置在线支付时，管理员可手动确认订单或为用户充值。

PC 端订单二维码由系统使用纯 PHP 在本地生成，不依赖外部二维码服务；手机端可直接打开支付页面。

定时任务

建议配置每分钟执行一次，用于关闭过期订单、失效套餐与清理临时数据：

* * * * * /usr/bin/php /www/wwwroot/wtoweld.com/bin/cron.php >> /www/wwwroot/wtoweld.com/storage/logs/cron.log 2>&1

也可以直接访问命令行脚本：php bin/cron.php。脚本会输出本次处理的订单与套餐数量。

安全建议

生产环境开启 HTTPS，并在后台开启「强制 HTTPS」；
安装完成后删除 install.php，禁止访问 config/ 与 storage/；
定期更换管理员密码，不要使用弱口令；不同管理员使用独立账号；
为 config/config.php 设置严格权限（如 600），并做好数据库备份；
对外 API Key 按客服分配，泄露后立即删除重建；
关注各平台回调签名校验，不要关闭渠道密钥配置。

常见问题

回调地址验证失败怎么办？

检查 Token / EncodingAESKey 是否与平台后台完全一致；确认服务器时间准确；确认站点可通过公网 HTTPS 访问；查看 storage/logs/ 下的日志。

AI 回复很慢或超时？

检查服务器到模型服务的网络；降低最大 Token 与上下文轮数；确认 PHP max_execution_time 充足；必要时在 Nginx 调整 fastcgi_read_timeout。

知识库上传后没有效果？

确认知识库已绑定到对应客服；确认文档状态为「就绪」且分块数大于 0；在客服编辑页使用测试对话查看命中来源。

如何备份与迁移？

备份数据库、config/config.php 与 storage/uploads/（知识库原文件）。迁移到新服务器后修改数据库配置并恢复文件即可。