LiteLoaderQQNT-OneBotApi中send_private_forward_msg接口调用问题解析

2025-06-30 20:58:52作者：凤尚柏Louis

在基于LiteLoaderQQNT-OneBotApi开发QQ机器人时，开发者可能会遇到send_private_forward_msg接口调用失败的问题。本文将深入分析该问题的成因及解决方案，帮助开发者正确使用这一重要接口。

问题现象

开发者在使用send_private_forward_msg接口时，主要遇到两类错误表现：

HTTP协议错误：当开发者误将HTTP请求发送到WebSocket端口时，会收到"426 Upgrade Required"错误响应。这表示服务器期望客户端升级到WebSocket协议，但客户端仍在尝试使用HTTP协议通信。
参数格式错误：即使协议使用正确，如果消息参数格式不规范，也会导致调用失败。常见错误包括：
- messages字段缺少外层中括号
- 消息内容格式不符合规范
- 转义字符处理不当

技术原理

send_private_forward_msg是OneBot协议中用于发送合并转发消息的重要接口。其核心功能是将多条消息合并为一条转发消息发送给指定用户。该接口支持通过HTTP和WebSocket两种协议调用，但需要注意：

协议区分：HTTP和WebSocket端口通常是分开配置的，开发者必须确保使用正确的端口和协议。
消息结构：合并转发消息需要严格遵循特定的数据结构格式，包括：
- messages字段必须是数组类型
- 每条消息节点必须包含type和data字段
- 消息内容需要正确转义

解决方案

HTTP调用方式

确保使用正确的HTTP端口（默认为3100），并按照以下格式构造请求：

import requests
import json

url = "http://localhost:3100/send_private_forward_msg"

payload = json.dumps({
   "user_id": "目标QQ号",
   "messages": [  # 注意这里是数组
      {
         "type": "node",
         "data": {
            "content": [
               {
                  "type": "text",
                  "data": {
                     "text": "消息内容"
                  }
               }
            ]
         }
      }
   ]
})
headers = {
   'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)

WebSocket调用方式

使用WebSocket协议时，同样需要注意messages字段必须是数组：

{
    "action": "send_private_forward_msg", 
    "params": {
        "user_id": "目标QQ号",
        "messages": [  // 必须使用数组
            {
                "type": "node",
                "data": {
                    "content": [
                        {
                            "type": "text", 
                            "data": {
                                "text": "消息内容"
                            }   
                        }
                    ]
                }
            }
        ]
    },
    "echo": "用于标识请求的唯一标识"
}

常见错误排查

协议错误：确保HTTP请求发送到HTTP端口，WebSocket请求发送到WebSocket端口。
参数格式错误：
- 检查messages字段是否为数组
- 检查每条消息节点是否包含完整的type和data字段
- 确保特殊字符正确转义
日志分析：通过LLOneBot的运行日志可以查看详细的错误信息，如"expected array but got [object Object]"提示参数类型错误。