Chuyển tới nội dung chính

Thiết lập ĐƯỜNG DÂY

Chạy Đại lý Hermes dưới dạng bot LINE thông qua API nhắn tin LINE chính thức. Bộ điều hợp hoạt động như một plugin nền tảng đi kèm trong plugins/platforms/line/ — không cần chỉnh sửa cốt lõi, chỉ cần kích hoạt nó như bất kỳ nền tảng nào khác.

LINE là ứng dụng nhắn tin thống trị ở Nhật Bản, Đài Loan và Thái Lan. Nếu người dùng của bạn sống ở đó thì đây là cách họ liên hệ với bạn.

Cách bot phản hồi​

Bối cảnhHành vi
Trò chuyện 1:1 (ID
`U

) | Trả lời mọi tin nhắn | | Trò chuyện nhóm (ID `C

) | Phản hồi khi nhóm nằm trong danh sách cho phép | | Phòng nhiều người dùng (ID `R

) | Phản hồi khi phòng nằm trong danh sách cho phép |

Văn bản, hình ảnh, âm thanh, video, tệp, nhãn dán và vị trí gửi đến đều được xử lý. Văn bản gửi đi sử dụng mã thông báo trả lời miễn phí trước tiên (sử dụng một lần, khoảng thời gian ~60 giây) và quay trở lại API đẩy được đo khi mã thông báo hết hạn.

Bước 1: Tạo kênh API nhắn tin LINE​

  1. Đi tới LINE Developers Console.
  2. Tạo Nhà cung cấp, sau đó là kênh API nhắn tin.
  3. Từ tab Cài đặt cơ bản của kênh, hãy sao chép Bí mật kênh.
  4. Từ tab API nhắn tin, cuộn đến Mã thông báo truy cập kênh (tồn tại lâu) và nhấp vào Vấn đề. Sao chép mã thông báo.
  5. Trong tab API nhắn tin, hãy tắt Tin nhắn trả lời tự động và Tin nhắn chào mừng để chúng không cản trở câu trả lời của bot của bạn.

Bước 2: Hiện cổng webhook​

LINE cung cấp webhooks qua HTTPS công khai. Cổng mặc định là `8646

  • ghi đè bằng LINE_PORT nếu cần.

# Cloudflare Tunnel (recommended for production — fixed hostname)
cloudflared tunnel --url http://localhost:8646 ngrok (good for dev)
ngrok http 8646

# devtunnel
devtunnel create Hermes-line --allow-anonymous
devtunnel port create Hermes-line -p 8646 --protocol https
devtunnel host Hermes-line

`
``Sao chép URL 
`https://...
` — bạn sẽ đặt URL này làm URL webhook bên dưới. **Để đường hầm chạy** trong khi thử nghiệm. Để sản xuất, hãy thiết lập một đường hầm có tên Cloudflare cố định để URL webhook không thay đổi khi khởi động lại.

---

## Bước 3: Cấu hình Hermes

Thêm vào 

~/.Hermes/.env

:

`env
LINE_CHANNEL_ACCESS_TOKEN=YOUR_LONG_LIVED_TOKEN
LINE_CHANNEL_SECRET=YOUR_CHANNEL_SECRET

# Allowlist — at least one of these (or LINE_ALLOW_ALL_USERS=true for dev)
LINE_ALLOWED_USERS=U1234567890abcdef...           # comma-separated U-prefixed IDs
LINE_ALLOWED_GROUPS=C1234567890abcdef...          # optional group IDs
LINE_ALLOWED_ROOMS=R1234567890abcdef...           # optional room IDs

# Required for image / audio / video sends — the public HTTPS base URL
# the tunnel resolves to.  Without it, send_image/voice/video will refuse.
LINE_PUBLIC_URL=https://my-tunnel.example.com

`
``Sau đó trong 

~/.Hermes/config.yaml

:

``` yaml
gateway:
  platforms:
    line:
      enabled: true

`
``Thế là đủ — quá trình quét plugin đi kèm trong 
`gateway/config.py
` sẽ tự động chọn 
`plugins/platforms/line/

. Không chỉnh sửa enum 
`Platform.LINE

, không đăng ký 
`_create_adapter

.

---

## Bước 4: Đặt URL webhook

Quay lại bảng điều khiển LINE:
1. Mở kênh của bạn → tab **API nhắn tin**.

2. Trong **Cài đặt Webhook** → **URL Webhook**, dán 
`https://<your-tunnel/line/webhook
` (lưu ý đường dẫn 

/line/webhook
` — bộ điều hợp sẽ lắng nghe ở đó).
3. Nhấp vào **Xác minh**. LINE ping URL; bạn sẽ thấy con số 200.
4. Chuyển **Sử dụng webhook** sang **Bật**.

---

## Bước 5: Chạy cổng

``` bash
Hermes gateway

`
``Nhật ký đại lý hiển thị:

`
LINE: webhook listening on 0.0.0.0:8646/line/webhook (public: https://my-tunnel.example.com)

`
``Thêm bot làm bạn bè từ ứng dụng LINE (quét mã QR trong tab **API nhắn tin** của kênh) và gửi tin nhắn cho bot.

---

## Phản hồi LLM chậm

Mã thông báo trả lời của LINE chỉ sử dụng một lần và hết hạn khoảng 60 giây sau sự kiện gửi đến. LLM chậm không thể trả lời kịp thời, điều này thường buộc phải thực hiện lệnh gọi API Push phải trả phí.

Khi LLM vẫn chạy quá 
`LINE_SLOW_RESPONSE_THRESHOLD
` giây (
`45
` mặc định), bộ điều hợp sẽ sử dụng mã thông báo trả lời ban đầu để gửi bong bóng **Nút mẫu**:`> 🤔 Vẫn đang suy nghĩ. Hãy nhấn vào bên dưới để tìm câu trả lời khi nó sẵn sàng.
>
> [Nhận câu trả lời]

Người dùng nhấn vào **Nhận câu trả lời** khi thuận tiện — việc đăng lại đó sẽ cung cấp mã thông báo trả lời *mới* mà bộ chuyển đổi sử dụng để gửi câu trả lời được lưu trong bộ nhớ đệm (vẫn miễn phí).

Máy trạng thái: 
`PENDING → READY → DELIVERED

, cộng với 
`ERROR
` cho các lần chạy bị hủy (PENDING mồ côi chuyển thành "Chạy bị gián đoạn trước khi hoàn thành." sau 

/stop
` để nút liên tục không lặp).

Để tắt nút đăng lại và thay vào đó luôn là Dự phòng đẩy:

`env
LINE_SLOW_RESPONSE_THRESHOLD=0

`
``Để luồng đăng lại được kích hoạt một cách đáng tin cậy, hãy chặn cuộc trò chuyện sẽ sử dụng mã thông báo trả lời trước ngưỡng:

`YAML

# ~/.Hermes/config.yaml
display:
  interim_assistant_messages: false
  platforms:
    line:
      tool_progress: off

`

---

## Cron / gửi thông báo

`env
LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # default delivery target

`
``Định kỳ công việc với định tuyến 
`deliver: line
` tới 
`LINE_HOME_CHANNEL

. Bộ điều hợp cung cấp một trình gửi chỉ đẩy độc lập để các công việc định kỳ hoạt động ngay cả khi cron chạy trong một quy trình riêng biệt với cổng.

---

## Tham chiếu biến môi trường| Biến | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|
| 
`LINE_CHANNEL_ACCESS_TOKEN
` | vâng | — | Mã thông báo truy cập kênh tồn tại lâu dài |
| 
`LINE_CHANNEL_SECRET
` | vâng | — | Bí mật kênh (xác minh webhook HMAC-SHA256) |
| 
`LINE_HOST
` | không |

0.0.0.0
` | Máy chủ liên kết Webhook |
| 
`LINE_PORT
` | không |

8646
` | Cổng liên kết Webhook |
| 
`LINE_PUBLIC_URL
` | cho phương tiện truyền thông | — | URL cơ sở HTTPS công khai; cần thiết để gửi hình ảnh/giọng nói/video |
| 
`LINE_ALLOWED_USERS
` | một trong | — | ID người dùng được phân tách bằng dấu phẩy (tiền tố U) |
| 
`LINE_ALLOWED_GROUPS
` | một trong | — | ID nhóm được phân tách bằng dấu phẩy (tiền tố C) |
| 
`LINE_ALLOWED_ROOMS
` | một trong | — | ID phòng được phân tách bằng dấu phẩy (tiền tố R) |
| 
`LINE_ALLOW_ALL_USERS
` | chỉ dành cho nhà phát triển |

false
` | Bỏ qua hoàn toàn danh sách cho phép |
| 
`LINE_HOME_CHANNEL
` | không | — | Mục tiêu gửi thông báo/cron mặc định |
| 
`LINE_SLOW_RESPONSE_THRESHOLD
` | không |

45
` | Vài giây trước khi nút đăng lại kích hoạt (
`0
` = bị tắt) |
| 
`LINE_PENDING_TEXT
` | không | "🤔 Vẫn đang suy nghĩ..." | Văn bản bong bóng hiển thị dọc theo nút đăng lại |
| 
`LINE_BUTTON_LABEL
` | không | "Nhận câu trả lời" | Nhãn nút |
| 
`LINE_DELIVERED_TEXT
` | không | "Đã trả lời ✅" | Trả lời khi nhấn lại vào nút đã gửi |
| 
`LINE_INTERRUPTED_TEXT
` | không | "Chạy bị gián đoạn trước khi hoàn thành." | Trả lời khi nhấn vào nút mồ côi 

/stop
` |

---

## Khắc phục sự cố`**"chữ ký không hợp lệ" khi xác minh webhook.** 
`Channel secret
` đã được sao chép sai hoặc đường hầm của bạn đã viết lại nội dung yêu cầu. Trước tiên hãy xác minh bằng 
`curl -i https://<tunnel>/line/webhook/health

 - điều đó sẽ trả về 

\{"status":"ok","platform":"line"}

.

**Bot không nhận được gì trong nhóm.** Kiểm tra 
`LINE_ALLOWED_GROUPS
` có bao gồm ID nhóm 
`C...
` không. Để tìm ID nhóm, hãy gửi tin nhắn kiểm tra và grep 

~/.Hermes/logs/gateway.log
` cho 
`LINE: rejecting unauthoriZed source

 - lệnh nguồn bị từ chối có ID.

**
`send_image
` không thành công với "phải đặt LINE_PUBLIC_URL".** API nhắn tin của LINE không chấp nhận tải lên nhị phân — hình ảnh, âm thanh và video phải là URL HTTPS có thể truy cập được. Đặt 
`LINE_PUBLIC_URL
` thành tên máy chủ công khai của đường hầm và bộ điều hợp sẽ tự động phân phát các tệp từ 

/line/media/<token>/<filename>

.

**Nút đăng lại không bao giờ xuất hiện.** Hoặc LLM phản hồi nhanh hơn 
`LINE_SLOW_RESPONSE_THRESHOLD
` hoặc một bong bóng khác (tiến trình công cụ, phát trực tuyến) đã sử dụng mã thông báo trả lời trước tiên. Xem khối ngăn chặn trong phần "Phản hồi LLM chậm".

**"đã được sử dụng bởi một hồ sơ khác".** Mã thông báo truy cập kênh tương tự được liên kết với một hồ sơ Hermes đang chạy khác. Dừng cổng khác hoặc sử dụng một kênh riêng.

---

## Hạn chế
* **Một bong bóng trên mỗi đoạn.** Mỗi bong bóng văn bản LINE có giới hạn 5000 ký tự và tối đa 5 bong bóng được gửi cho mỗi cuộc gọi Trả lời/Đẩy. Những câu trả lời dài hơn sẽ được cắt ngắn bằng dấu chấm lửng.
* **Không chỉnh sửa tin nhắn gốc.** LINE không có API tin nhắn chỉnh sửa — phản hồi phát trực tuyến luôn gửi bong bóng mới, không bao giờ chỉnh sửa bong bóng trước đó.
* **Không hiển thị Markdown.** In đậm (

**

), in nghiêng (

*

), hàng rào mã và tiêu đề hiển thị dưới dạng ký tự chữ. Bộ chuyển đổi loại bỏ chúng trước khi gửi; URL được giữ nguyên (

[label](url)
` trở thành 
`label (url)

).
* **Chỉ báo tải chỉ dành cho DM.** LINE từ chối API trò chuyện/tải đối với các nhóm và phòng nên chỉ báo đang nhập chỉ hiển thị trong các cuộc trò chuyện 1:1.