Nền tảng hỗ trợ
| Nền tảng | Hỗ trợ |
|---|---|
| Flespi Free | 1.000 AI credit/tháng |
| Flespi Commercial | 1.000 AI credit/tháng + tính phí vượt mức |
Điều kiện tiên quyết
- Tài khoản Flespi tại flespi.io.
- Quyền truy cập Flespi panel để tạo và quản lý API token.
- Với môi trường production, ACL token có quyền giới hạn cho các module CloudThinker cần.
Thiết lập
CloudThinker kết nối với Flespi qua MCP server chính thức của họ bằng API token của Flespi.Tạo tài khoản Flespi
Đăng ký tại flespi.io nếu bạn chưa có tài khoản.
Tạo API token
Trong flespi panel, điều hướng đến Tokens trong menu bên trái và nhấn nút ”+”:
- Name:
CloudThinker Agent - Type: Standard (development) hoặc ACL (production)
- TTL: Đặt thời gian hết hạn — ví dụ:
7776000(90 ngày). Flespi yêu cầu tất cả token phải có TTL hoặc ngày hết hạn.
Chi tiết kết nối
| Trường | Mô tả | Ví dụ |
|---|---|---|
| Flespi Token | API token Flespi (64 byte) | 7Bf3...xK9z |
Quyền yêu cầu
Loại token
| Loại | Mức truy cập | Khi nào dùng |
|---|---|---|
| Standard | CRUD đầy đủ trên tất cả thực thể Telematics (device, channel, stream, plugin, geofence, calculator) | Development và testing |
| ACL | Chi tiết — từ chối tất cả theo mặc định, cấp theo module/method/item | Khuyến nghị cho production |
| Master | Admin đầy đủ bao gồm platform API | Không bao giờ dùng với AI agent |
Thời hạn token
Flespi yêu cầu tất cả token phải hết hạn. Đặt ít nhất một trong hai:ttl— giây không hoạt động trước khi hết hạn (đặt lại sau mỗi lần gọi API)expire— Unix timestamp cho thời điểm hết hạn cứng
Quyền ACL khuyến nghị (production)
Chỉ đọc (tối thiểu):| Module | Method | Mục đích |
|---|---|---|
gw/devices | GET | Danh sách thiết bị, trạng thái, telemetry, message |
gw/channels | GET | Danh sách channel, cấu hình, trạng thái |
gw/streams | GET | Danh sách stream, sức khỏe, thống kê gửi |
gw/calculators | GET | Cấu hình calculator |
ai | POST | Bắt buộc cho MCP tool call |
| Module | Method | Mục đích |
|---|---|---|
gw/devices | GET, POST, PUT | Tạo/cập nhật thiết bị |
gw/channels | GET, POST, PUT | Tạo/cập nhật channel |
gw/streams | GET, POST, PUT, DELETE | Quản lý stream đầy đủ |
ACL token từ chối tất cả theo mặc định. Chỉ các quyền được cấp rõ ràng mới được phép. Token với POST trên
gw/devices sẽ không có GET trừ khi cũng được cấp.Khả năng của agent
Sau khi kết nối, các agent có thể:| Khả năng | Mô tả |
|---|---|
| Quản lý thiết bị | Liệt kê thiết bị, xem trạng thái, đọc telemetry và lịch sử message |
| Giám sát channel | Kiểm tra cấu hình channel, trạng thái và protocol đã kết nối |
| Sức khỏe stream | Giám sát thống kê gửi stream và sức khỏe |
| Telemetry đội xe | Truy vấn vị trí GPS, tốc độ, nhiên liệu và dữ liệu cảm biến trên các thiết bị |
| Geofence | Xem và quản lý vùng geofence và trigger |
| Calculator | Kiểm tra cấu hình calculator để phát hiện chuyến đi, mức tiêu thụ nhiên liệu, v.v. |
Công cụ MCP có sẵn
Công cụ miễn phí (0 credit):| Công cụ | Mô tả |
|---|---|
search-api-methods | Khám phá các phương thức Flespi REST API theo truy vấn ngôn ngữ tự nhiên |
get-api-schema | Lấy Swagger schema đầy đủ cho một phương thức API cụ thể |
flespi-api-read | Thực thi yêu cầu GET chỉ đọc đến flespi REST API |
flespi-api-write | Thực thi thao tác ghi (POST/PUT/PATCH/DELETE) |
| Công cụ | Credit | Mô tả |
|---|---|---|
search-flespi-documentation | 5 | Tìm kiếm tài liệu nền tảng flespi |
search-device-documentation | 10 | Tìm kiếm tài liệu nhà sản xuất thiết bị/protocol |
generate-flespi-expression | 2 | Tạo flespi expression cho selector, calculator |
generate-pvm-code | 10 | Tạo mã PVM (Protocol Virtual Machine) |
consult-flespi-account | 30 | Ủy quyền phân tích phức tạp cho chuyên gia AI của flespi với quyền đọc tài khoản |
AI credit
| Gói | Credit miễn phí/tháng | Vượt mức |
|---|---|---|
| Free | 1.000 | Bị chặn đến tháng sau |
| Commercial | 1.000 | €1 mỗi 100 credit bổ sung |
GET /ai/logs, hoặc MQTT topic flespi/log/ai/#.
Xác minh kết nối
Ví dụ prompt
Xử lý sự cố
Access token không hợp lệ hoặc đã hết hạn
Access token không hợp lệ hoặc đã hết hạn
- Token có thể đã hết hạn — kiểm tra cài đặt TTL và ngày hết hạn trong flespi panel.
- Tạo token mới và cập nhật kết nối trong CloudThinker.
- Token hết hạn sẽ bị flespi tự động xóa.
Hành động không được phép bởi ACL
Hành động không được phép bởi ACL
- ACL token của bạn thiếu tổ hợp module + HTTP method bắt buộc.
- Cập nhật ACL token để cấp quyền cần thiết.
- Nhớ rằng: ACL từ chối tất cả theo mặc định — mỗi quyền phải được cấp rõ ràng.
HTTP 403 trên AI tools
HTTP 403 trên AI tools
- AI credit hàng tháng đã cạn kiệt.
- Gói Free: chờ đến tháng sau. Gói Commercial: kiểm tra cài đặt vượt mức.
- Theo dõi mức sử dụng credit qua
GET /ai/logshoặc mã sự kiện1710.
HTTP 429 rate limit
HTTP 429 rate limit
- flespi tính tổng mức sử dụng API + MQTT + lưu lượng mỗi phút.
- Giảm tần suất yêu cầu hoặc gộp thao tác.
- Token có mức sử dụng cao nhất bị chặn trước; các token khác tiếp tục hoạt động.
Dùng token từ vị trí không được phép
Dùng token từ vị trí không được phép
- Danh sách trắng IP được cấu hình trên token nhưng IP máy chủ của bạn chưa được thêm.
- Cập nhật danh sách trắng IP của token trong flespi panel: Token settings → IPs whitelist.
Bảo mật
- Quyền tối thiểu — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
- Chỉ đọc theo mặc định — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
- Xoay vòng thông tin xác thực — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
- Thu hồi khi bàn giao — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.
- Token riêng biệt — tạo token riêng cho CloudThinker; không bao giờ chia sẻ nó giữa các tích hợp hoặc dùng Master token
- ACL cho production — sử dụng ACL token với chỉ các quyền tối thiểu cần thiết; ACL token từ chối tất cả theo mặc định
Liên quan
Kết nối MCP
Tích hợp MCP tùy chỉnh
Kết nối Kubernetes
Điều phối container cho workload IoT