picoclaw/docs/channels/wecom/wecom_aibot/README.vi.md

Quay lại README

WeCom AI Bot

WeCom AI Bot là phương thức tích hợp hội thoại AI chính thức do WeCom cung cấp. Hỗ trợ cả chat riêng tư và chat nhóm, tích hợp giao thức phản hồi streaming, và hỗ trợ chủ động đẩy phản hồi cuối cùng qua response_url sau khi hết thời gian chờ.

So sánh với các kênh WeCom khác

Tính năng	WeCom Bot	WeCom App	WeCom AI Bot
Chat riêng tư	✅	✅	✅
Chat nhóm	✅	❌	✅
Đầu ra streaming	❌	❌	✅
Đẩy chủ động khi timeout	❌	✅	✅
Độ phức tạp cấu hình	Thấp	Cao	Trung bình

Cấu hình

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "你好！有什么可以帮助你的吗？",
      "max_steps": 10
    }
  }
}

Trường	Kiểu	Bắt buộc	Mô tả
token	string	Có	Token xác minh callback, cấu hình trên trang quản lý AI Bot
encoding_aes_key	string	Có	Khóa AES 43 ký tự, được tạo ngẫu nhiên trên trang quản lý AI Bot
webhook_path	string	Không	Đường dẫn webhook (mặc định: /webhook/wecom-aibot)
allow_from	array	Không	Danh sách cho phép ID người dùng; mảng rỗng cho phép tất cả người dùng
welcome_message	string	Không	Tin nhắn chào mừng gửi khi người dùng mở chat; để trống để tắt
reply_timeout	int	Không	Thời gian chờ phản hồi tính bằng giây (mặc định: 5)
max_steps	int	Không	Số bước thực thi tối đa của agent (mặc định: 10)

Hướng dẫn thiết lập

1. Đăng nhập vào Bảng điều khiển quản trị WeCom
2. Vào "Quản lý ứng dụng" → "AI Bot", sau đó tạo hoặc chọn một AI Bot
3. Trên trang cấu hình AI Bot, điền thông tin "Nhận tin nhắn":
   • URL: http://<your-server-ip>:18790/webhook/wecom-aibot
   • Token: Tạo ngẫu nhiên hoặc tùy chỉnh
   • EncodingAESKey: Nhấp "Tạo ngẫu nhiên" để lấy khóa 43 ký tự
4. Nhập Token và EncodingAESKey vào file cấu hình PicoClaw, khởi động dịch vụ rồi quay lại bảng điều khiển quản trị để lưu (WeCom sẽ gửi yêu cầu xác minh)

Tip

Máy chủ cần có thể truy cập được từ các máy chủ WeCom. Nếu bạn đang ở mạng nội bộ hoặc phát triển cục bộ, hãy sử dụng ngrok hoặc frp để tạo tunnel.

Giao thức phản hồi streaming

WeCom AI Bot sử dụng giao thức "pull streaming", khác với phản hồi một lần của webhook thông thường:

Người dùng gửi tin nhắn
  │
  ▼
PicoClaw trả về ngay {finish: false} (Agent bắt đầu xử lý)
  │
  ▼
WeCom pull khoảng mỗi 1 giây với {msgtype: "stream", stream: {id: "..."}}
  │
  ├─ Agent chưa xong → trả về {finish: false} (tiếp tục chờ)
  │
  └─ Agent xong → trả về {finish: true, content: "nội dung phản hồi"}

Xử lý timeout (tác vụ vượt quá 30 giây):

Nếu thời gian xử lý của agent vượt quá khoảng 30 giây (cửa sổ polling tối đa của WeCom là 6 phút), PicoClaw sẽ:

1. Đóng stream ngay lập tức và hiển thị cho người dùng: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. Agent tiếp tục chạy ở nền
3. Sau khi agent hoàn thành, phản hồi cuối cùng được chủ động đẩy đến người dùng qua response_url có trong tin nhắn

response_url do WeCom cấp, có hiệu lực 1 giờ, chỉ dùng được một lần, không cần mã hóa — chỉ cần POST trực tiếp nội dung tin nhắn markdown.

Tin nhắn chào mừng

Khi welcome_message được cấu hình, PicoClaw sẽ tự động phản hồi bằng tin nhắn đó khi người dùng mở cửa sổ chat với AI Bot (sự kiện enter_chat). Để trống để bỏ qua im lặng.

"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"

Câu hỏi thường gặp

Xác minh URL callback thất bại

• Xác nhận tường lửa máy chủ đã mở cổng tương ứng (mặc định 18790)
• Xác nhận token và encoding_aes_key được điền đúng
• Kiểm tra log PicoClaw xem có nhận được yêu cầu GET từ WeCom không

Tin nhắn không nhận được phản hồi

• Kiểm tra xem allow_from có vô tình hạn chế người gửi không
• Tìm context canceled hoặc lỗi agent trong log
• Xác nhận cấu hình agent (ví dụ: model_name) là đúng

Không nhận được push cuối cùng cho tác vụ dài

• Xác nhận callback tin nhắn có chứa response_url (chỉ hỗ trợ bởi WeCom AI Bot phiên bản mới)
• Xác nhận máy chủ có thể thực hiện yêu cầu ra ngoài (cần POST đến response_url)
• Kiểm tra log với từ khóa response_url mode và Sending reply via response_url

Tài liệu tham khảo

• Tài liệu tích hợp WeCom AI Bot
• Mô tả giao thức phản hồi streaming
• Phản hồi chủ động qua response_url