diff --git a/docs/vi/channels/pairing.md b/docs/vi/channels/pairing.md index 52865ff27..9f9dd55a6 100644 --- a/docs/vi/channels/pairing.md +++ b/docs/vi/channels/pairing.md @@ -2,40 +2,40 @@ read_when: - Thiết lập kiểm soát truy cập DM - Ghép nối một Node iOS/Android mới - - Đánh giá trạng thái bảo mật của OpenClaw -summary: 'Tổng quan về ghép đôi: phê duyệt ai có thể nhắn tin trực tiếp cho bạn + Node nào có thể tham gia' + - Đánh giá tình trạng bảo mật của OpenClaw +summary: 'Tổng quan về ghép nối: phê duyệt ai có thể nhắn tin trực tiếp cho bạn + những Node nào có thể tham gia' title: Ghép nối x-i18n: - generated_at: "2026-05-04T02:21:42Z" + generated_at: "2026-05-04T09:37:05Z" model: gpt-5.5 provider: openai - source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874 + source_hash: f2bce4cfba7708b0003f2ffeacada8bc1849cc301f28178b499a9a67bddcf36d source_path: channels/pairing.md workflow: 16 --- -“Ghép đôi” là bước phê duyệt quyền truy cập tường minh của OpenClaw. +“Ghép cặp” là bước phê duyệt quyền truy cập rõ ràng của OpenClaw. Nó được dùng ở hai nơi: -1. **Ghép đôi tin nhắn trực tiếp (DM)** (ai được phép trò chuyện với bot) -2. **Ghép đôi Node** (thiết bị/nút nào được phép tham gia mạng Gateway) +1. **Ghép cặp DM** (ai được phép trò chuyện với bot) +2. **Ghép cặp Node** (thiết bị/nút nào được phép tham gia mạng Gateway) -Ngữ cảnh bảo mật: [Bảo mật](/vi/gateway/security) +Bối cảnh bảo mật: [Bảo mật](/vi/gateway/security) -## 1) Ghép đôi tin nhắn trực tiếp (quyền truy cập trò chuyện đến) +## 1) Ghép cặp DM (quyền truy cập trò chuyện đến) -Khi một kênh được cấu hình với chính sách DM `pairing`, người gửi chưa biết sẽ nhận một mã ngắn và tin nhắn của họ sẽ **không được xử lý** cho đến khi bạn phê duyệt. +Khi một kênh được cấu hình với chính sách DM `pairing`, người gửi chưa xác định sẽ nhận một mã ngắn và tin nhắn của họ sẽ **không được xử lý** cho đến khi bạn phê duyệt. -Các chính sách DM mặc định được ghi lại trong: [Bảo mật](/vi/gateway/security) +Các chính sách DM mặc định được ghi lại tại: [Bảo mật](/vi/gateway/security) -`dmPolicy: "open"` chỉ công khai khi danh sách cho phép DM hiệu lực bao gồm `"*"`. -Thiết lập và xác thực yêu cầu ký tự đại diện đó cho các cấu hình công khai-mở. Nếu trạng thái hiện có chứa `open` với các mục `allowFrom` cụ thể, thời gian chạy vẫn chỉ cho phép những người gửi đó, và các phê duyệt trong kho ghép đôi không mở rộng quyền truy cập `open`. +`dmPolicy: "open"` chỉ là công khai khi danh sách cho phép DM hiệu lực bao gồm `"*"`. +Thiết lập và xác thực yêu cầu ký tự đại diện đó cho các cấu hình công khai-mở. Nếu trạng thái hiện có chứa `open` với các mục `allowFrom` cụ thể, thời gian chạy vẫn chỉ cho phép các người gửi đó, và các phê duyệt trong kho ghép cặp không mở rộng quyền truy cập `open`. -Mã ghép đôi: +Mã ghép cặp: - 8 ký tự, chữ hoa, không có ký tự dễ nhầm lẫn (`0O1I`). -- **Hết hạn sau 1 giờ**. Bot chỉ gửi tin nhắn ghép đôi khi một yêu cầu mới được tạo (khoảng một lần mỗi giờ cho mỗi người gửi). -- Các yêu cầu ghép đôi DM đang chờ được giới hạn mặc định ở **3 yêu cầu mỗi kênh**; các yêu cầu bổ sung bị bỏ qua cho đến khi một yêu cầu hết hạn hoặc được phê duyệt. +- **Hết hạn sau 1 giờ**. Bot chỉ gửi tin nhắn ghép cặp khi một yêu cầu mới được tạo (xấp xỉ mỗi giờ một lần cho mỗi người gửi). +- Các yêu cầu ghép cặp DM đang chờ được giới hạn ở **3 yêu cầu mỗi kênh** theo mặc định; các yêu cầu bổ sung sẽ bị bỏ qua cho đến khi một yêu cầu hết hạn hoặc được phê duyệt. ### Phê duyệt người gửi @@ -44,18 +44,16 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` -Nếu chưa cấu hình chủ sở hữu lệnh, việc phê duyệt mã ghép đôi DM cũng khởi tạo -`commands.ownerAllowFrom` cho người gửi đã được phê duyệt, chẳng hạn `telegram:123456789`. -Điều đó cung cấp cho các thiết lập lần đầu một chủ sở hữu tường minh cho các lệnh đặc quyền và lời nhắc phê duyệt exec. Sau khi đã có chủ sở hữu, các phê duyệt ghép đôi sau đó chỉ cấp quyền truy cập DM; chúng không thêm chủ sở hữu khác. +Nếu chưa cấu hình chủ sở hữu lệnh, việc phê duyệt mã ghép cặp DM cũng khởi tạo `commands.ownerAllowFrom` thành người gửi được phê duyệt, chẳng hạn như `telegram:123456789`. +Điều đó cung cấp cho các thiết lập lần đầu một chủ sở hữu rõ ràng cho các lệnh đặc quyền và lời nhắc phê duyệt thực thi. Sau khi đã có chủ sở hữu, các phê duyệt ghép cặp sau này chỉ cấp quyền truy cập DM; chúng không thêm chủ sở hữu mới. -Kênh được hỗ trợ: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. +Các kênh được hỗ trợ: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. -### Nhóm người gửi có thể tái sử dụng +### Nhóm người gửi có thể dùng lại Dùng `accessGroups` cấp cao nhất khi cùng một tập người gửi đáng tin cậy cần áp dụng cho nhiều kênh nhắn tin hoặc cho cả danh sách cho phép DM và nhóm. -Nhóm tĩnh dùng `type: "message.senders"` và được tham chiếu bằng -`accessGroup:` từ danh sách cho phép của kênh: +Nhóm tĩnh dùng `type: "message.senders"` và được tham chiếu bằng `accessGroup:` từ danh sách cho phép của kênh: ```json5 { @@ -87,48 +85,49 @@ Nhóm truy cập được ghi lại chi tiết tại đây: [Nhóm truy cập](/ - Tài khoản mặc định: `-allowFrom.json` - Tài khoản không mặc định: `--allowFrom.json` -Hành vi phạm vi tài khoản: +Hành vi phạm vi theo tài khoản: -- Tài khoản không mặc định chỉ đọc/ghi tệp danh sách cho phép theo phạm vi của chúng. -- Tài khoản mặc định dùng tệp danh sách cho phép không phạm vi theo kênh. +- Tài khoản không mặc định chỉ đọc/ghi tệp danh sách cho phép trong phạm vi của chúng. +- Tài khoản mặc định dùng tệp danh sách cho phép không có phạm vi theo kênh. Hãy xem các tệp này là nhạy cảm (chúng kiểm soát quyền truy cập vào trợ lý của bạn). -Kho danh sách cho phép ghép đôi dùng cho quyền truy cập DM. Ủy quyền nhóm là riêng biệt. -Phê duyệt mã ghép đôi DM không tự động cho phép người gửi đó chạy lệnh nhóm hoặc điều khiển bot trong nhóm. Khởi tạo chủ sở hữu đầu tiên là trạng thái cấu hình riêng trong `commands.ownerAllowFrom`, và việc gửi trò chuyện nhóm vẫn tuân theo danh sách cho phép nhóm của kênh (ví dụ `groupAllowFrom`, `groups`, hoặc ghi đè theo nhóm hoặc theo chủ đề tùy kênh). +Kho danh sách cho phép ghép cặp dùng cho quyền truy cập DM. Ủy quyền nhóm là riêng biệt. +Việc phê duyệt mã ghép cặp DM không tự động cho phép người gửi đó chạy lệnh nhóm hoặc điều khiển bot trong nhóm. Khởi tạo chủ sở hữu đầu tiên là trạng thái cấu hình riêng trong `commands.ownerAllowFrom`, và việc gửi trong trò chuyện nhóm vẫn tuân theo danh sách cho phép nhóm của kênh (ví dụ `groupAllowFrom`, `groups`, hoặc ghi đè theo từng nhóm hay từng chủ đề tùy kênh). -## 2) Ghép đôi thiết bị Node (Node iOS/Android/macOS/headless) +## 2) Ghép cặp thiết bị Node (iOS/Android/macOS/nút không giao diện) -Node kết nối tới Gateway dưới dạng **thiết bị** với `role: node`. Gateway -tạo yêu cầu ghép đôi thiết bị cần được phê duyệt. +Các Node kết nối với Gateway dưới dạng **thiết bị** với `role: node`. Gateway tạo một yêu cầu ghép cặp thiết bị cần được phê duyệt. -### Ghép đôi qua Telegram (khuyến nghị cho iOS) +### Ghép cặp qua Telegram (khuyến nghị cho iOS) -Nếu bạn dùng Plugin `device-pair`, bạn có thể thực hiện ghép đôi thiết bị lần đầu hoàn toàn từ Telegram: +Nếu bạn dùng Plugin `device-pair`, bạn có thể ghép cặp thiết bị lần đầu hoàn toàn từ Telegram: -1. Trong Telegram, nhắn tin cho bot của bạn: `/pair` +1. Trong Telegram, nhắn cho bot của bạn: `/pair` 2. Bot trả lời bằng hai tin nhắn: một tin nhắn hướng dẫn và một tin nhắn **mã thiết lập** riêng (dễ sao chép/dán trong Telegram). -3. Trên điện thoại, mở ứng dụng OpenClaw iOS → Settings → Gateway. -4. Dán mã thiết lập và kết nối. +3. Trên điện thoại của bạn, mở ứng dụng OpenClaw iOS → Settings → Gateway. +4. Quét mã QR hoặc dán mã thiết lập và kết nối. 5. Quay lại Telegram: `/pair pending` (xem lại ID yêu cầu, vai trò và phạm vi), rồi phê duyệt. -Mã thiết lập là payload JSON được mã hóa base64 chứa: +Mã thiết lập là một tải JSON được mã hóa base64 chứa: - `url`: URL WebSocket của Gateway (`ws://...` hoặc `wss://...`) -- `bootstrapToken`: token khởi tạo ngắn hạn cho một thiết bị, dùng cho bắt tay ghép đôi ban đầu +- `bootstrapToken`: một token khởi tạo ngắn hạn cho một thiết bị, dùng cho bắt tay ghép cặp ban đầu -Token khởi tạo đó mang hồ sơ khởi tạo ghép đôi tích hợp sẵn: +Token khởi tạo đó mang hồ sơ khởi tạo ghép cặp tích hợp sẵn: -- token `node` chính được bàn giao giữ nguyên `scopes: []` -- mọi token `operator` được bàn giao vẫn bị giới hạn trong danh sách cho phép khởi tạo: +- token `node` chính được chuyển giao vẫn giữ `scopes: []` +- bất kỳ token `operator` nào được chuyển giao vẫn bị giới hạn trong danh sách cho phép khởi tạo: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` - kiểm tra phạm vi khởi tạo có tiền tố theo vai trò, không phải một nhóm phạm vi phẳng: các mục phạm vi operator chỉ thỏa mãn yêu cầu operator, và các vai trò không phải operator vẫn phải yêu cầu phạm vi dưới tiền tố vai trò riêng của chúng -- việc xoay vòng/thu hồi token sau đó vẫn bị giới hạn bởi cả hợp đồng vai trò đã phê duyệt của thiết bị và phạm vi operator của phiên gọi +- việc xoay vòng/thu hồi token sau này vẫn bị giới hạn bởi cả hợp đồng vai trò đã phê duyệt của thiết bị và các phạm vi operator của phiên gọi -Hãy xử lý mã thiết lập như mật khẩu khi nó còn hiệu lực. +Hãy xem mã thiết lập như mật khẩu trong thời gian nó còn hiệu lực. + +Đối với Tailscale, công khai hoặc ghép cặp di động không phải loopback khác, hãy dùng Tailscale Serve/Funnel hoặc URL Gateway `wss://` khác. URL thiết lập `ws://` trực tiếp không phải loopback sẽ bị từ chối trước khi phát hành QR/mã thiết lập. Mã thiết lập `ws://` dạng văn bản thuần chỉ giới hạn cho URL loopback; máy khách `ws://` trong mạng riêng vẫn cần cơ chế phá kính rõ ràng `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` được mô tả trong hướng dẫn Gateway từ xa. ### Phê duyệt thiết bị Node @@ -138,18 +137,17 @@ openclaw devices approve openclaw devices reject ``` -Khi một phê duyệt tường minh bị từ chối vì phiên thiết bị đã ghép đôi dùng để phê duyệt được mở với phạm vi chỉ-ghép-đôi, CLI thử lại cùng yêu cầu với -`operator.admin`. Điều này cho phép một thiết bị đã ghép đôi có khả năng quản trị hiện có khôi phục một lần ghép đôi Control UI/trình duyệt mới mà không cần chỉnh sửa thủ công `devices/paired.json`. Gateway vẫn xác thực kết nối được thử lại; các token không thể xác thực với `operator.admin` vẫn bị chặn. +Khi một phê duyệt rõ ràng bị từ chối vì phiên thiết bị đã ghép cặp đang phê duyệt được mở với phạm vi chỉ dành cho ghép cặp, CLI thử lại cùng yêu cầu với `operator.admin`. Điều này cho phép một thiết bị đã ghép cặp có quyền quản trị hiện có khôi phục một lần ghép cặp Control UI/trình duyệt mới mà không phải chỉnh sửa thủ công `devices/paired.json`. Gateway vẫn xác thực kết nối được thử lại; các token không thể xác thực với `operator.admin` vẫn bị chặn. -Nếu cùng thiết bị thử lại với chi tiết xác thực khác (ví dụ vai trò/phạm vi/khóa công khai khác), yêu cầu đang chờ trước đó sẽ bị thay thế và một `requestId` mới được tạo. +Nếu cùng thiết bị thử lại với chi tiết xác thực khác (ví dụ vai trò/phạm vi/khóa công khai khác), yêu cầu đang chờ trước đó sẽ được thay thế và một `requestId` mới được tạo. -Một thiết bị đã ghép đôi không âm thầm nhận quyền truy cập rộng hơn. Nếu nó kết nối lại và yêu cầu nhiều phạm vi hơn hoặc vai trò rộng hơn, OpenClaw giữ nguyên phê duyệt hiện có và tạo một yêu cầu nâng cấp đang chờ mới. Dùng `openclaw devices list` để so sánh quyền truy cập hiện được phê duyệt với quyền truy cập mới được yêu cầu trước khi bạn phê duyệt. +Thiết bị đã ghép cặp không âm thầm nhận quyền truy cập rộng hơn. Nếu nó kết nối lại và yêu cầu thêm phạm vi hoặc vai trò rộng hơn, OpenClaw giữ nguyên phê duyệt hiện có và tạo một yêu cầu nâng cấp mới đang chờ. Dùng `openclaw devices list` để so sánh quyền truy cập hiện được phê duyệt với quyền truy cập mới được yêu cầu trước khi bạn phê duyệt. -### Tự động phê duyệt Node theo CIDR tin cậy tùy chọn +### Tự động phê duyệt Node theo CIDR đáng tin cậy tùy chọn -Ghép đôi thiết bị vẫn là thủ công theo mặc định. Với các mạng Node được kiểm soát chặt chẽ, bạn có thể chọn tham gia tự động phê duyệt Node lần đầu bằng CIDR tường minh hoặc IP chính xác: +Ghép cặp thiết bị mặc định vẫn là thủ công. Với các mạng Node được kiểm soát chặt chẽ, bạn có thể bật tự động phê duyệt Node lần đầu bằng CIDR rõ ràng hoặc IP chính xác: ```json5 { @@ -163,23 +161,24 @@ Ghép đôi thiết bị vẫn là thủ công theo mặc định. Với các m } ``` -Điều này chỉ áp dụng cho các yêu cầu ghép đôi `role: node` mới không có phạm vi được yêu cầu. Các máy khách operator, trình duyệt, Control UI và WebChat vẫn yêu cầu phê duyệt thủ công. Các thay đổi về vai trò, phạm vi, siêu dữ liệu và khóa công khai vẫn yêu cầu phê duyệt thủ công. +Điều này chỉ áp dụng cho các yêu cầu ghép cặp `role: node` mới không có phạm vi được yêu cầu. +Máy khách Operator, trình duyệt, Control UI và WebChat vẫn cần phê duyệt thủ công. Các thay đổi về vai trò, phạm vi, siêu dữ liệu và khóa công khai vẫn cần phê duyệt thủ công. -### Lưu trữ trạng thái ghép đôi Node +### Lưu trữ trạng thái ghép cặp Node Được lưu dưới `~/.openclaw/devices/`: - `pending.json` (ngắn hạn; yêu cầu đang chờ sẽ hết hạn) -- `paired.json` (thiết bị đã ghép đôi + token) +- `paired.json` (thiết bị đã ghép cặp + token) ### Ghi chú -- API `node.pair.*` cũ (CLI: `openclaw nodes pending|approve|reject|remove|rename`) là một kho ghép đôi riêng do Gateway sở hữu. Node WS vẫn yêu cầu ghép đôi thiết bị. -- Bản ghi ghép đôi là nguồn sự thật bền vững cho các vai trò đã phê duyệt. Token thiết bị đang hoạt động vẫn bị giới hạn trong tập vai trò đã phê duyệt đó; một mục token lạc ngoài các vai trò đã phê duyệt không tạo quyền truy cập mới. +- API `node.pair.*` cũ (CLI: `openclaw nodes pending|approve|reject|remove|rename`) là một kho ghép cặp riêng do Gateway sở hữu. Các Node WS vẫn cần ghép cặp thiết bị. +- Bản ghi ghép cặp là nguồn sự thật bền vững cho các vai trò đã phê duyệt. Token thiết bị đang hoạt động vẫn bị giới hạn trong tập vai trò đã phê duyệt đó; một mục token lạc ngoài các vai trò đã phê duyệt không tạo quyền truy cập mới. ## Tài liệu liên quan -- Mô hình bảo mật + prompt injection: [Bảo mật](/vi/gateway/security) +- Mô hình bảo mật + chèn lệnh nhắc: [Bảo mật](/vi/gateway/security) - Cập nhật an toàn (chạy doctor): [Cập nhật](/vi/install/updating) - Cấu hình kênh: - Telegram: [Telegram](/vi/channels/telegram) diff --git a/docs/vi/channels/telegram.md b/docs/vi/channels/telegram.md index 98ea13d4a..e44246600 100644 --- a/docs/vi/channels/telegram.md +++ b/docs/vi/channels/telegram.md @@ -4,39 +4,39 @@ read_when: summary: Trạng thái hỗ trợ, khả năng và cấu hình của bot Telegram title: Telegram x-i18n: - generated_at: "2026-05-04T07:02:52Z" + generated_at: "2026-05-04T09:36:59Z" model: gpt-5.5 provider: openai - source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6 + source_hash: 5711d53cf908a14024bc5a94f7d590bb4bcb6963a1d78049d7782871f4eae932 source_path: channels/telegram.md workflow: 16 --- -Sẵn sàng cho production cho DM bot và nhóm thông qua grammY. Long polling là chế độ mặc định; chế độ webhook là tùy chọn. +Sẵn sàng cho production với tin nhắn DM và nhóm của bot qua grammY. Long polling là chế độ mặc định; chế độ Webhook là tùy chọn. - + Chính sách DM mặc định cho Telegram là ghép nối. - - Chẩn đoán xuyên kênh và playbook sửa chữa. + + Chẩn đoán liên kênh và playbook sửa lỗi. - - Các mẫu và ví dụ cấu hình kênh đầy đủ. + + Đầy đủ mẫu cấu hình kênh và ví dụ. ## Thiết lập nhanh - + Mở Telegram và trò chuyện với **@BotFather** (xác nhận handle chính xác là `@BotFather`). Chạy `/newbot`, làm theo lời nhắc và lưu token. - + ```json5 { @@ -51,12 +51,12 @@ Sẵn sàng cho production cho DM bot và nhóm thông qua grammY. Long polling } ``` - Dự phòng env: `TELEGRAM_BOT_TOKEN=...` (chỉ tài khoản mặc định). - Telegram **không** dùng `openclaw channels login telegram`; hãy cấu hình token trong config/env, rồi khởi động gateway. + Env fallback: `TELEGRAM_BOT_TOKEN=...` (chỉ tài khoản mặc định). + Telegram **không** dùng `openclaw channels login telegram`; cấu hình token trong config/env, rồi khởi động gateway. - + ```bash openclaw gateway @@ -68,38 +68,38 @@ openclaw pairing approve telegram - - Thêm bot vào nhóm của bạn, rồi đặt `channels.telegram.groups` và `groupPolicy` để khớp với mô hình truy cập của bạn. + + Thêm bot vào nhóm của bạn, rồi đặt `channels.telegram.groups` và `groupPolicy` cho khớp với mô hình truy cập của bạn. -Thứ tự phân giải token nhận biết theo tài khoản. Trên thực tế, giá trị config được ưu tiên hơn dự phòng env, và `TELEGRAM_BOT_TOKEN` chỉ áp dụng cho tài khoản mặc định. +Thứ tự phân giải token có nhận biết tài khoản. Trên thực tế, giá trị config thắng env fallback, và `TELEGRAM_BOT_TOKEN` chỉ áp dụng cho tài khoản mặc định. ## Cài đặt phía Telegram - - Bot Telegram mặc định dùng **Privacy Mode**, giới hạn các tin nhắn nhóm mà chúng nhận được. + + Bot Telegram mặc định dùng **Privacy Mode**, giới hạn những tin nhắn nhóm mà bot nhận được. - Nếu bot phải thấy tất cả tin nhắn nhóm, hãy: + Nếu bot phải thấy mọi tin nhắn nhóm, hãy: - - tắt chế độ riêng tư qua `/setprivacy`, hoặc + - tắt chế độ riêng tư bằng `/setprivacy`, hoặc - đặt bot làm quản trị viên nhóm. - Khi bật/tắt chế độ riêng tư, hãy xóa + thêm lại bot trong từng nhóm để Telegram áp dụng thay đổi. + Khi bật/tắt chế độ riêng tư, hãy gỡ + thêm lại bot trong từng nhóm để Telegram áp dụng thay đổi. - + Trạng thái quản trị viên được kiểm soát trong cài đặt nhóm Telegram. - Bot quản trị viên nhận tất cả tin nhắn nhóm, hữu ích cho hành vi nhóm luôn bật. + Bot quản trị viên nhận mọi tin nhắn nhóm, hữu ích cho hành vi nhóm luôn bật. - + - `/setjoingroups` để cho phép/từ chối thêm vào nhóm - `/setprivacy` cho hành vi hiển thị trong nhóm @@ -110,7 +110,7 @@ Thứ tự phân giải token nhận biết theo tài khoản. Trên thực tế ## Kiểm soát truy cập và kích hoạt - + `channels.telegram.dmPolicy` kiểm soát quyền truy cập tin nhắn trực tiếp: - `pairing` (mặc định) @@ -118,21 +118,21 @@ Thứ tự phân giải token nhận biết theo tài khoản. Trên thực tế - `open` (yêu cầu `allowFrom` bao gồm `"*"`) - `disabled` - `dmPolicy: "open"` với `allowFrom: ["*"]` cho phép bất kỳ tài khoản Telegram nào tìm thấy hoặc đoán được tên người dùng bot có thể ra lệnh cho bot. Chỉ dùng tùy chọn này cho các bot công khai có chủ đích với công cụ bị hạn chế chặt chẽ; bot một chủ sở hữu nên dùng `allowlist` với ID người dùng dạng số. + `dmPolicy: "open"` với `allowFrom: ["*"]` cho phép bất kỳ tài khoản Telegram nào tìm thấy hoặc đoán được tên người dùng bot ra lệnh cho bot. Chỉ dùng cho bot công khai có chủ đích với công cụ bị hạn chế chặt chẽ; bot một chủ sở hữu nên dùng `allowlist` với ID người dùng dạng số. `channels.telegram.allowFrom` chấp nhận ID người dùng Telegram dạng số. Tiền tố `telegram:` / `tg:` được chấp nhận và chuẩn hóa. - Trong cấu hình nhiều tài khoản, `channels.telegram.allowFrom` cấp cao nhất có tính hạn chế được xem là ranh giới an toàn: các mục `allowFrom: ["*"]` cấp tài khoản không làm tài khoản đó công khai trừ khi allowlist hiệu lực của tài khoản vẫn chứa wildcard rõ ràng sau khi hợp nhất. - `dmPolicy: "allowlist"` với `allowFrom` rỗng sẽ chặn tất cả DM và bị xác thực cấu hình từ chối. + Trong config nhiều tài khoản, `channels.telegram.allowFrom` ở cấp cao nhất có tính hạn chế được xem là ranh giới an toàn: các mục `allowFrom: ["*"]` ở cấp tài khoản không làm tài khoản đó trở thành công khai trừ khi allowlist hiệu lực của tài khoản vẫn chứa wildcard rõ ràng sau khi hợp nhất. + `dmPolicy: "allowlist"` với `allowFrom` trống sẽ chặn mọi DM và bị xác thực config từ chối. Thiết lập chỉ yêu cầu ID người dùng dạng số. - Nếu bạn đã nâng cấp và cấu hình của bạn chứa các mục allowlist `@username`, hãy chạy `openclaw doctor --fix` để phân giải chúng (nỗ lực tối đa; yêu cầu token bot Telegram). - Nếu trước đây bạn dựa vào các tệp allowlist của kho ghép nối, `openclaw doctor --fix` có thể khôi phục các mục vào `channels.telegram.allowFrom` trong các luồng allowlist (ví dụ khi `dmPolicy: "allowlist"` chưa có ID rõ ràng). + Nếu bạn đã nâng cấp và config chứa các mục allowlist `@username`, hãy chạy `openclaw doctor --fix` để phân giải chúng (best-effort; cần token bot Telegram). + Nếu trước đây bạn phụ thuộc vào tệp allowlist của kho ghép nối, `openclaw doctor --fix` có thể khôi phục các mục vào `channels.telegram.allowFrom` trong luồng allowlist (ví dụ khi `dmPolicy: "allowlist"` chưa có ID rõ ràng). - Với bot một chủ sở hữu, nên dùng `dmPolicy: "allowlist"` với ID `allowFrom` dạng số rõ ràng để giữ chính sách truy cập bền vững trong config (thay vì phụ thuộc vào các phê duyệt ghép nối trước đó). + Với bot một chủ sở hữu, ưu tiên `dmPolicy: "allowlist"` với ID `allowFrom` dạng số rõ ràng để giữ chính sách truy cập bền vững trong config (thay vì phụ thuộc vào các phê duyệt ghép nối trước đó). Nhầm lẫn thường gặp: phê duyệt ghép nối DM không có nghĩa là "người gửi này được ủy quyền ở mọi nơi". Ghép nối cấp quyền truy cập DM. Nếu chưa có chủ sở hữu lệnh, lần ghép nối được phê duyệt đầu tiên cũng đặt `commands.ownerAllowFrom` để các lệnh chỉ dành cho chủ sở hữu và phê duyệt exec có tài khoản vận hành rõ ràng. - Ủy quyền người gửi trong nhóm vẫn đến từ các allowlist cấu hình rõ ràng. - Nếu bạn muốn "Tôi được ủy quyền một lần và cả DM lẫn lệnh nhóm đều hoạt động", hãy đặt ID người dùng Telegram dạng số của bạn trong `channels.telegram.allowFrom`; với các lệnh chỉ dành cho chủ sở hữu, hãy đảm bảo `commands.ownerAllowFrom` chứa `telegram:`. + Ủy quyền người gửi trong nhóm vẫn đến từ allowlist config rõ ràng. + Nếu bạn muốn "tôi được ủy quyền một lần và cả DM lẫn lệnh nhóm đều hoạt động", hãy đặt ID người dùng Telegram dạng số của bạn trong `channels.telegram.allowFrom`; với lệnh chỉ dành cho chủ sở hữu, hãy đảm bảo `commands.ownerAllowFrom` chứa `telegram:`. ### Tìm ID người dùng Telegram của bạn @@ -152,8 +152,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Hai kiểm soát áp dụng cùng nhau: + + Hai cơ chế kiểm soát áp dụng cùng nhau: 1. **Những nhóm nào được phép** (`channels.telegram.groups`) - không có config `groups`: @@ -166,15 +166,15 @@ curl "https://api.telegram.org/bot/getUpdates" - `allowlist` (mặc định) - `disabled` - `groupAllowFrom` được dùng để lọc người gửi trong nhóm. Nếu không đặt, Telegram quay về dùng `allowFrom`. + `groupAllowFrom` được dùng để lọc người gửi trong nhóm. Nếu chưa đặt, Telegram fallback về `allowFrom`. Các mục `groupAllowFrom` nên là ID người dùng Telegram dạng số (tiền tố `telegram:` / `tg:` được chuẩn hóa). - Không đặt ID chat nhóm hoặc siêu nhóm Telegram trong `groupAllowFrom`. ID chat âm thuộc về `channels.telegram.groups`. - Các mục không phải dạng số bị bỏ qua cho ủy quyền người gửi. - Ranh giới bảo mật (`2026.2.25+`): xác thực người gửi nhóm **không** kế thừa phê duyệt kho ghép nối DM. - Ghép nối vẫn chỉ dành cho DM. Với nhóm, đặt `groupAllowFrom` hoặc `allowFrom` theo nhóm/theo topic. - Nếu `groupAllowFrom` chưa đặt, Telegram quay về dùng config `allowFrom`, không dùng kho ghép nối. + Không đặt ID chat của nhóm hoặc siêu nhóm Telegram trong `groupAllowFrom`. ID chat âm thuộc về `channels.telegram.groups`. + Các mục không phải dạng số bị bỏ qua khi ủy quyền người gửi. + Ranh giới bảo mật (`2026.2.25+`): xác thực người gửi trong nhóm **không** kế thừa phê duyệt kho ghép nối DM. + Ghép nối vẫn chỉ dành cho DM. Với nhóm, hãy đặt `groupAllowFrom` hoặc `allowFrom` theo từng nhóm/từng chủ đề. + Nếu chưa đặt `groupAllowFrom`, Telegram fallback về config `allowFrom`, không phải kho ghép nối. Mẫu thực tế cho bot một chủ sở hữu: đặt ID người dùng của bạn trong `channels.telegram.allowFrom`, để `groupAllowFrom` chưa đặt, và cho phép các nhóm mục tiêu trong `channels.telegram.groups`. - Ghi chú runtime: nếu `channels.telegram` hoàn toàn thiếu, runtime mặc định fail-closed `groupPolicy="allowlist"` trừ khi `channels.defaults.groupPolicy` được đặt rõ ràng. + Ghi chú runtime: nếu thiếu hoàn toàn `channels.telegram`, runtime mặc định fail-closed `groupPolicy="allowlist"` trừ khi `channels.defaults.groupPolicy` được đặt rõ ràng. Ví dụ: cho phép bất kỳ thành viên nào trong một nhóm cụ thể: @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Ví dụ: chỉ cho phép người dùng cụ thể bên trong một nhóm cụ thể: + Ví dụ: chỉ cho phép người dùng cụ thể trong một nhóm cụ thể: ```json5 { @@ -211,34 +211,34 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Lỗi thường gặp: `groupAllowFrom` không phải là allowlist nhóm Telegram. + Lỗi thường gặp: `groupAllowFrom` không phải allowlist nhóm Telegram. - - Đặt ID chat nhóm hoặc siêu nhóm Telegram dạng âm như `-1001234567890` dưới `channels.telegram.groups`. - - Đặt ID người dùng Telegram như `8734062810` dưới `groupAllowFrom` khi bạn muốn giới hạn những người bên trong một nhóm được phép có thể kích hoạt bot. - - Chỉ dùng `groupAllowFrom: ["*"]` khi bạn muốn bất kỳ thành viên nào của một nhóm được phép đều có thể nói chuyện với bot. + - Đặt ID chat nhóm hoặc siêu nhóm Telegram âm như `-1001234567890` trong `channels.telegram.groups`. + - Đặt ID người dùng Telegram như `8734062810` trong `groupAllowFrom` khi bạn muốn giới hạn những người trong một nhóm được phép có thể kích hoạt bot. + - Chỉ dùng `groupAllowFrom: ["*"]` khi bạn muốn bất kỳ thành viên nào của một nhóm được phép cũng có thể nói chuyện với bot. - + Trả lời trong nhóm mặc định yêu cầu mention. Mention có thể đến từ: - mention gốc `@botusername`, hoặc - - các mẫu mention trong: + - mẫu mention trong: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Các công tắc lệnh cấp phiên: + Các nút bật/tắt lệnh cấp phiên: - `/activation always` - `/activation mention` - Những lệnh này chỉ cập nhật trạng thái phiên. Dùng config để duy trì lâu dài. + Những lệnh này chỉ cập nhật trạng thái phiên. Dùng config để lưu bền vững. - Ví dụ config duy trì lâu dài: + Ví dụ config bền vững: ```json5 { @@ -263,34 +263,34 @@ curl "https://api.telegram.org/bot/getUpdates" ## Hành vi runtime -- Telegram do quy trình gateway sở hữu. -- Định tuyến là xác định: tin nhắn vào từ Telegram trả lời lại Telegram (model không chọn kênh). -- Tin nhắn vào được chuẩn hóa thành phong bì kênh dùng chung với siêu dữ liệu trả lời và placeholder media. -- Phiên nhóm được cô lập theo ID nhóm. Topic diễn đàn thêm `:topic:` để giữ các topic cô lập. -- Tin nhắn DM có thể mang `message_thread_id`; OpenClaw giữ nguyên ID thread cho trả lời nhưng mặc định vẫn giữ DM trên phiên phẳng. Cấu hình `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true`, hoặc config topic khớp khi bạn chủ ý muốn cô lập phiên topic DM. -- Long polling dùng grammY runner với sắp trình tự theo từng chat/từng thread. Đồng thời tổng thể của runner sink dùng `agents.defaults.maxConcurrent`. -- Long polling được bảo vệ bên trong từng quy trình gateway để chỉ một poller đang hoạt động có thể dùng một token bot tại một thời điểm. Nếu bạn vẫn thấy xung đột `getUpdates` 409, có thể một gateway OpenClaw khác, script, hoặc poller bên ngoài đang dùng cùng token. -- Khởi động lại watchdog long-polling được kích hoạt mặc định sau 120 giây không có liveness `getUpdates` hoàn tất. Chỉ tăng `channels.telegram.pollingStallThresholdMs` nếu deployment của bạn vẫn thấy khởi động lại do polling-stall giả trong khi công việc chạy lâu. Giá trị tính bằng mili giây và được phép từ `30000` đến `600000`; hỗ trợ ghi đè theo tài khoản. +- Telegram do tiến trình gateway sở hữu. +- Định tuyến có tính xác định: tin nhắn Telegram đến sẽ trả lời lại Telegram (model không chọn kênh). +- Tin nhắn đến được chuẩn hóa vào envelope kênh dùng chung với metadata trả lời và placeholder media. +- Phiên nhóm được cô lập theo ID nhóm. Chủ đề diễn đàn thêm `:topic:` để giữ các chủ đề tách biệt. +- Tin nhắn DM có thể mang `message_thread_id`; OpenClaw giữ nguyên ID luồng cho trả lời nhưng mặc định vẫn giữ DM trên phiên phẳng. Cấu hình `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true`, hoặc config chủ đề khớp khi bạn cố ý muốn cô lập phiên chủ đề DM. +- Long polling dùng grammY runner với sắp thứ tự theo từng chat/từng luồng. Mức đồng thời sink tổng thể của runner dùng `agents.defaults.maxConcurrent`. +- Long polling được bảo vệ bên trong từng tiến trình gateway để mỗi lần chỉ một poller hoạt động có thể dùng một token bot. Nếu bạn vẫn thấy xung đột `getUpdates` 409, có khả năng một OpenClaw gateway, script hoặc poller bên ngoài khác đang dùng cùng token. +- Khởi động lại watchdog của long-polling mặc định kích hoạt sau 120 giây không có liveness `getUpdates` hoàn tất. Chỉ tăng `channels.telegram.pollingStallThresholdMs` nếu triển khai của bạn vẫn thấy các lần khởi động lại do polling-stall giả trong khi chạy tác vụ lâu. Giá trị tính bằng mili giây và được phép từ `30000` đến `600000`; hỗ trợ override theo tài khoản. - Telegram Bot API không hỗ trợ biên nhận đã đọc (`sendReadReceipts` không áp dụng). ## Tham chiếu tính năng - - OpenClaw có thể stream trả lời từng phần theo thời gian thực: + + OpenClaw có thể stream trả lời một phần theo thời gian thực: - chat trực tiếp: tin nhắn xem trước + `editMessageText` - - nhóm/topic: tin nhắn xem trước + `editMessageText` + - nhóm/chủ đề: tin nhắn xem trước + `editMessageText` Yêu cầu: - `channels.telegram.streaming` là `off | partial | block | progress` (mặc định: `partial`) - - `progress` giữ một bản nháp trạng thái có thể chỉnh sửa và cập nhật nó với tiến trình công cụ cho đến khi gửi cuối cùng - - `streaming.preview.toolProgress` kiểm soát việc cập nhật công cụ/tiến trình có tái sử dụng cùng tin nhắn xem trước đã chỉnh sửa hay không (mặc định: `true` khi stream xem trước đang hoạt động) - - `streaming.preview.commandText` kiểm soát chi tiết command/exec bên trong các dòng tiến trình công cụ đó: `raw` (mặc định, giữ nguyên hành vi đã phát hành) hoặc `status` (chỉ nhãn công cụ) - - `channels.telegram.streamMode` kế thừa và giá trị boolean `streaming` được phát hiện; chạy `openclaw doctor --fix` để di chuyển chúng sang `channels.telegram.streaming.mode` + - `progress` giữ một bản nháp trạng thái có thể chỉnh sửa và cập nhật nó bằng tiến trình công cụ cho đến khi gửi cuối cùng + - `streaming.preview.toolProgress` kiểm soát việc các cập nhật công cụ/tiến trình có dùng lại cùng tin nhắn xem trước đã chỉnh sửa hay không (mặc định: `true` khi preview streaming đang hoạt động) + - `streaming.preview.commandText` kiểm soát chi tiết lệnh/exec trong các dòng tiến trình công cụ đó: `raw` (mặc định, giữ nguyên hành vi đã phát hành) hoặc `status` (chỉ nhãn công cụ) + - `channels.telegram.streamMode` cũ và giá trị boolean `streaming` được phát hiện; chạy `openclaw doctor --fix` để di chuyển chúng sang `channels.telegram.streaming.mode` - Cập nhật xem trước tiến trình công cụ là các dòng trạng thái ngắn hiển thị trong khi công cụ chạy, ví dụ thực thi lệnh, đọc tệp, cập nhật lập kế hoạch, hoặc tóm tắt patch. Telegram giữ chúng bật theo mặc định để khớp hành vi OpenClaw đã phát hành từ `v2026.4.22` trở về sau. Để giữ bản xem trước đã chỉnh sửa cho văn bản câu trả lời nhưng ẩn các dòng tiến trình công cụ, hãy đặt: + Cập nhật xem trước tiến trình công cụ là các dòng trạng thái ngắn hiển thị khi công cụ chạy, ví dụ thực thi lệnh, đọc tệp, cập nhật lập kế hoạch hoặc tóm tắt patch. Telegram giữ chúng bật mặc định để khớp với hành vi OpenClaw đã phát hành từ `v2026.4.22` trở về sau. Để giữ phần xem trước đã chỉnh sửa cho văn bản trả lời nhưng ẩn các dòng tiến trình công cụ, hãy đặt: ```json { @@ -307,7 +307,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Để giữ tiến trình công cụ hiển thị nhưng ẩn văn bản command/exec, hãy đặt: + Để giữ tiến trình công cụ hiển thị nhưng ẩn văn bản lệnh/exec, hãy đặt: ```json { @@ -342,26 +342,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Chỉ dùng `streaming.mode: "off"` khi bạn muốn chỉ phân phối kết quả cuối cùng: các chỉnh sửa xem trước của Telegram bị tắt và thông tin trò chuyện chung về công cụ/tiến trình bị chặn thay vì được gửi dưới dạng các thông báo trạng thái độc lập. Lời nhắc phê duyệt, payload phương tiện và lỗi vẫn đi qua luồng phân phối cuối cùng bình thường. Dùng `streaming.preview.toolProgress: false` khi bạn chỉ muốn giữ các chỉnh sửa xem trước câu trả lời trong khi ẩn các dòng trạng thái tiến trình công cụ. + Chỉ dùng `streaming.mode: "off"` khi bạn muốn chỉ gửi kết quả cuối cùng: các chỉnh sửa bản xem trước của Telegram bị tắt và các thông báo chung về công cụ/tiến trình bị chặn thay vì được gửi dưới dạng thông báo trạng thái riêng lẻ. Lời nhắc phê duyệt, payload phương tiện và lỗi vẫn đi qua luồng gửi cuối cùng thông thường. Dùng `streaming.preview.toolProgress: false` khi bạn chỉ muốn giữ các chỉnh sửa bản xem trước câu trả lời trong khi ẩn các dòng trạng thái tiến trình công cụ. - Trả lời trích dẫn đã chọn của Telegram là ngoại lệ. Khi `replyToMode` là `"first"`, `"all"` hoặc `"batched"` và tin nhắn đến có văn bản trích dẫn đã chọn, OpenClaw gửi câu trả lời cuối cùng qua đường dẫn trả lời trích dẫn gốc của Telegram thay vì chỉnh sửa bản xem trước câu trả lời, nên `streaming.preview.toolProgress` không thể hiển thị các dòng trạng thái ngắn cho lượt đó. Các trả lời cho tin nhắn hiện tại không có văn bản trích dẫn đã chọn vẫn giữ phát trực tuyến bản xem trước. Đặt `replyToMode: "off"` khi khả năng nhìn thấy tiến trình công cụ quan trọng hơn trả lời trích dẫn gốc, hoặc đặt `streaming.preview.toolProgress: false` để chấp nhận đánh đổi này. + Phản hồi trích dẫn được chọn của Telegram là ngoại lệ. Khi `replyToMode` là `"first"`, `"all"` hoặc `"batched"` và tin nhắn đến có văn bản trích dẫn được chọn, OpenClaw gửi câu trả lời cuối cùng qua đường dẫn phản hồi trích dẫn gốc của Telegram thay vì chỉnh sửa bản xem trước câu trả lời, vì vậy `streaming.preview.toolProgress` không thể hiển thị các dòng trạng thái ngắn cho lượt đó. Các phản hồi cho tin nhắn hiện tại không có văn bản trích dẫn được chọn vẫn giữ phát trực tuyến bản xem trước. Đặt `replyToMode: "off"` khi khả năng hiển thị tiến trình công cụ quan trọng hơn phản hồi trích dẫn gốc, hoặc đặt `streaming.preview.toolProgress: false` để chấp nhận đánh đổi này. - Với trả lời chỉ có văn bản: + Với phản hồi chỉ có văn bản: - - bản xem trước ngắn trong DM/nhóm/chủ đề: OpenClaw giữ cùng một tin nhắn xem trước và thực hiện chỉnh sửa cuối cùng tại chỗ, trừ khi một tin nhắn hiển thị không phải bản xem trước đã được gửi sau khi bản xem trước xuất hiện - - bản xem trước theo sau bởi đầu ra hiển thị không phải bản xem trước: OpenClaw gửi câu trả lời hoàn chỉnh dưới dạng tin nhắn cuối cùng mới và dọn dẹp bản xem trước cũ hơn, để câu trả lời cuối cùng xuất hiện sau đầu ra trung gian - - bản xem trước cũ hơn khoảng một phút: OpenClaw gửi câu trả lời hoàn chỉnh dưới dạng tin nhắn cuối cùng mới rồi dọn dẹp bản xem trước, để dấu thời gian hiển thị của Telegram phản ánh thời điểm hoàn tất thay vì thời điểm tạo bản xem trước + - bản xem trước ngắn trong DM/nhóm/chủ đề: OpenClaw giữ cùng tin nhắn xem trước và thực hiện chỉnh sửa cuối cùng tại chỗ, trừ khi một tin nhắn không phải bản xem trước hiển thị đã được gửi sau khi bản xem trước xuất hiện + - bản xem trước được theo sau bởi đầu ra không phải bản xem trước hiển thị: OpenClaw gửi phản hồi hoàn chỉnh dưới dạng tin nhắn cuối cùng mới và dọn dẹp bản xem trước cũ, để câu trả lời cuối cùng xuất hiện sau đầu ra trung gian + - bản xem trước cũ hơn khoảng một phút: OpenClaw gửi phản hồi hoàn chỉnh dưới dạng tin nhắn cuối cùng mới rồi dọn dẹp bản xem trước, để dấu thời gian hiển thị của Telegram phản ánh thời điểm hoàn tất thay vì thời điểm tạo bản xem trước - Với các trả lời phức tạp (ví dụ payload phương tiện), OpenClaw quay về phân phối cuối cùng bình thường rồi dọn dẹp tin nhắn xem trước. + Với phản hồi phức tạp (ví dụ payload phương tiện), OpenClaw quay về luồng gửi cuối cùng thông thường rồi dọn dẹp tin nhắn xem trước. Phát trực tuyến bản xem trước tách biệt với phát trực tuyến khối. Khi phát trực tuyến khối được bật rõ ràng cho Telegram, OpenClaw bỏ qua luồng xem trước để tránh phát trực tuyến hai lần. Luồng suy luận chỉ dành cho Telegram: - `/reasoning stream` gửi suy luận vào bản xem trước trực tiếp trong khi tạo - - bản xem trước suy luận bị xóa sau khi phân phối cuối cùng; dùng `/reasoning on` khi suy luận cần tiếp tục hiển thị + - bản xem trước suy luận bị xóa sau khi gửi kết quả cuối cùng; dùng `/reasoning on` khi suy luận cần tiếp tục hiển thị - câu trả lời cuối cùng được gửi không kèm văn bản suy luận @@ -370,10 +370,10 @@ curl "https://api.telegram.org/bot/getUpdates" Văn bản gửi ra dùng Telegram `parse_mode: "HTML"`. - Văn bản kiểu Markdown được kết xuất thành HTML an toàn cho Telegram. - - HTML thô từ mô hình được thoát ký tự để giảm lỗi phân tích cú pháp của Telegram. - - Nếu Telegram từ chối HTML đã phân tích, OpenClaw thử lại dưới dạng văn bản thuần. + - HTML thô từ mô hình được thoát để giảm lỗi phân tích cú pháp Telegram. + - Nếu Telegram từ chối HTML đã phân tích cú pháp, OpenClaw thử lại dưới dạng văn bản thuần. - Xem trước liên kết được bật theo mặc định và có thể tắt bằng `channels.telegram.linkPreview: false`. + Bản xem trước liên kết được bật theo mặc định và có thể tắt bằng `channels.telegram.linkPreview: false`. @@ -404,25 +404,25 @@ curl "https://api.telegram.org/bot/getUpdates" - tên được chuẩn hóa (bỏ `/` ở đầu, chuyển thành chữ thường) - mẫu hợp lệ: `a-z`, `0-9`, `_`, độ dài `1..32` - lệnh tùy chỉnh không thể ghi đè lệnh gốc - - xung đột/trùng lặp bị bỏ qua và ghi log + - xung đột/trùng lặp được bỏ qua và ghi nhật ký Ghi chú: - lệnh tùy chỉnh chỉ là mục menu; chúng không tự động triển khai hành vi - - lệnh plugin/skill vẫn có thể hoạt động khi được nhập, ngay cả khi không hiển thị trong menu Telegram + - lệnh Plugin/Skills vẫn có thể hoạt động khi được nhập ngay cả khi không hiển thị trong menu Telegram - Nếu lệnh gốc bị tắt, các lệnh tích hợp sẽ bị gỡ bỏ. Lệnh tùy chỉnh/plugin vẫn có thể đăng ký nếu được cấu hình. + Nếu lệnh gốc bị tắt, các lệnh tích hợp sẽ bị xóa. Lệnh tùy chỉnh/Plugin vẫn có thể đăng ký nếu được cấu hình. Lỗi thiết lập thường gặp: - - `setMyCommands failed` với `BOT_COMMANDS_TOO_MUCH` nghĩa là menu Telegram vẫn vượt giới hạn sau khi cắt bớt; hãy giảm lệnh plugin/skill/tùy chỉnh hoặc tắt `channels.telegram.commands.native`. - - `deleteWebhook`, `deleteMyCommands` hoặc `setMyCommands` lỗi với `404: Not Found` trong khi lệnh curl trực tiếp tới Bot API hoạt động có thể nghĩa là `channels.telegram.apiRoot` đã được đặt thành toàn bộ endpoint `/bot`. `apiRoot` chỉ được là gốc Bot API, và `openclaw doctor --fix` sẽ xóa phần đuôi `/bot` vô tình thêm vào. - - `getMe returned 401` nghĩa là Telegram đã từ chối token bot đã cấu hình. Cập nhật `botToken`, `tokenFile` hoặc `TELEGRAM_BOT_TOKEN` bằng token BotFather hiện tại; OpenClaw dừng trước khi polling nên lỗi này không được báo cáo như lỗi dọn dẹp Webhook. - - `setMyCommands failed` với lỗi mạng/fetch thường nghĩa là DNS/HTTPS đi ra tới `api.telegram.org` bị chặn. + - `setMyCommands failed` với `BOT_COMMANDS_TOO_MUCH` nghĩa là menu Telegram vẫn vượt giới hạn sau khi cắt bớt; hãy giảm lệnh Plugin/Skills/tùy chỉnh hoặc tắt `channels.telegram.commands.native`. + - `deleteWebhook`, `deleteMyCommands` hoặc `setMyCommands` lỗi với `404: Not Found` trong khi lệnh curl trực tiếp tới Bot API hoạt động có thể nghĩa là `channels.telegram.apiRoot` đã được đặt thành endpoint đầy đủ `/bot`. `apiRoot` chỉ được là gốc Bot API, và `openclaw doctor --fix` sẽ xóa phần `/bot` vô tình ở cuối. + - `getMe returned 401` nghĩa là Telegram đã từ chối token bot được cấu hình. Cập nhật `botToken`, `tokenFile` hoặc `TELEGRAM_BOT_TOKEN` bằng token BotFather hiện tại; OpenClaw dừng trước khi polling nên việc này không được báo cáo là lỗi dọn dẹp Webhook. + - `setMyCommands failed` với lỗi mạng/fetch thường nghĩa là DNS/HTTPS gửi ra tới `api.telegram.org` bị chặn. - ### Lệnh ghép nối thiết bị (plugin `device-pair`) + ### Lệnh ghép nối thiết bị (Plugin `device-pair`) - Khi plugin `device-pair` được cài đặt: + Khi Plugin `device-pair` được cài đặt: 1. `/pair` tạo mã thiết lập 2. dán mã vào ứng dụng iOS @@ -432,11 +432,11 @@ curl "https://api.telegram.org/bot/getUpdates" - `/pair approve` khi chỉ có một yêu cầu đang chờ - `/pair approve latest` cho yêu cầu gần đây nhất - Mã thiết lập mang token bootstrap tồn tại ngắn hạn. Bàn giao bootstrap tích hợp giữ token nút chính ở `scopes: []`; mọi token toán tử được bàn giao vẫn bị giới hạn trong `operator.approvals`, `operator.read`, `operator.talk.secrets` và `operator.write`. Kiểm tra phạm vi bootstrap có tiền tố vai trò, nên danh sách cho phép toán tử đó chỉ đáp ứng các yêu cầu toán tử; các vai trò không phải toán tử vẫn cần phạm vi dưới tiền tố vai trò riêng của chúng. + Mã thiết lập mang một token bootstrap có thời hạn ngắn. Cơ chế chuyển giao bootstrap tích hợp giữ token nút chính ở `scopes: []`; mọi token người vận hành được chuyển giao vẫn bị giới hạn trong `operator.approvals`, `operator.read`, `operator.talk.secrets` và `operator.write`. Kiểm tra phạm vi bootstrap có tiền tố vai trò, vì vậy danh sách cho phép người vận hành đó chỉ thỏa mãn các yêu cầu người vận hành; các vai trò không phải người vận hành vẫn cần phạm vi dưới tiền tố vai trò riêng của chúng. Nếu một thiết bị thử lại với chi tiết xác thực đã thay đổi (ví dụ vai trò/phạm vi/khóa công khai), yêu cầu đang chờ trước đó sẽ bị thay thế và yêu cầu mới dùng một `requestId` khác. Chạy lại `/pair pending` trước khi phê duyệt. - Chi tiết khác: [Ghép nối](/vi/channels/pairing#pair-via-telegram-recommended-for-ios). + Chi tiết thêm: [Ghép nối](/vi/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -481,7 +481,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (mặc định) - `capabilities: ["inlineButtons"]` cũ ánh xạ sang `inlineButtons: "all"`. + `capabilities: ["inlineButtons"]` cũ ánh xạ tới `inlineButtons: "all"`. Ví dụ hành động tin nhắn: @@ -501,13 +501,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Lượt bấm callback được chuyển cho agent dưới dạng văn bản: + Các lần nhấp callback được chuyển cho agent dưới dạng văn bản: `callback_data: ` - Hành động công cụ Telegram bao gồm: + Hành động công cụ Telegram gồm: - `sendMessage` (`to`, `content`, tùy chọn `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) @@ -515,27 +515,27 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, tùy chọn `iconColor`, `iconCustomEmojiId`) - Hành động tin nhắn kênh cung cấp các bí danh tiện dụng (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + Hành động tin nhắn kênh cung cấp các alias tiện dụng (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Điều khiển chặn: + Kiểm soát cổng: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (mặc định: tắt) - Ghi chú: `edit` và `topic-create` hiện được bật theo mặc định và không có công tắc `channels.telegram.actions.*` riêng. - Lệnh gửi lúc chạy dùng ảnh chụp nhanh cấu hình/bí mật đang hoạt động (khởi động/tải lại), nên các đường dẫn hành động không thực hiện phân giải lại SecretRef ad-hoc cho từng lần gửi. + Lưu ý: `edit` và `topic-create` hiện được bật theo mặc định và không có công tắc `channels.telegram.actions.*` riêng. + Lần gửi ở runtime dùng ảnh chụp cấu hình/bí mật đang hoạt động (khởi động/tải lại), vì vậy các đường dẫn hành động không thực hiện phân giải lại SecretRef tùy biến theo từng lần gửi. - Ngữ nghĩa gỡ phản ứng: [/tools/reactions](/vi/tools/reactions) + Ngữ nghĩa xóa reaction: [/tools/reactions](/vi/tools/reactions) - - Telegram hỗ trợ thẻ luồng trả lời rõ ràng trong đầu ra được tạo: + + Telegram hỗ trợ thẻ phân luồng phản hồi rõ ràng trong đầu ra được tạo: - - `[[reply_to_current]]` trả lời tin nhắn kích hoạt - - `[[reply_to:]]` trả lời một ID tin nhắn Telegram cụ thể + - `[[reply_to_current]]` phản hồi tin nhắn kích hoạt + - `[[reply_to:]]` phản hồi một ID tin nhắn Telegram cụ thể `channels.telegram.replyToMode` kiểm soát cách xử lý: @@ -543,9 +543,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Khi luồng trả lời được bật và văn bản hoặc chú thích Telegram gốc có sẵn, OpenClaw tự động bao gồm một đoạn trích dẫn Telegram gốc. Telegram giới hạn văn bản trích dẫn gốc ở 1024 đơn vị mã UTF-16, nên các tin nhắn dài hơn được trích dẫn từ đầu và quay về trả lời thuần nếu Telegram từ chối trích dẫn. + Khi phân luồng phản hồi được bật và văn bản hoặc chú thích Telegram gốc có sẵn, OpenClaw tự động thêm một đoạn trích dẫn Telegram gốc. Telegram giới hạn văn bản trích dẫn gốc ở 1024 đơn vị mã UTF-16, vì vậy tin nhắn dài hơn được trích dẫn từ đầu và quay về phản hồi thuần nếu Telegram từ chối trích dẫn. - Ghi chú: `off` tắt luồng trả lời ngầm định. Các thẻ `[[reply_to_*]]` rõ ràng vẫn được tôn trọng. + Lưu ý: `off` tắt phân luồng phản hồi ngầm định. Các thẻ `[[reply_to_*]]` rõ ràng vẫn được tôn trọng. @@ -553,19 +553,19 @@ curl "https://api.telegram.org/bot/getUpdates" Siêu nhóm diễn đàn: - khóa phiên chủ đề thêm `:topic:` - - trả lời và trạng thái đang nhập nhắm tới luồng chủ đề + - phản hồi và thao tác nhập nhắm tới luồng chủ đề - đường dẫn cấu hình chủ đề: `channels.telegram.groups..topics.` - Trường hợp đặc biệt của chủ đề chung (`threadId=1`): + Trường hợp đặc biệt của chủ đề Chung (`threadId=1`): - - lệnh gửi tin nhắn bỏ qua `message_thread_id` (Telegram từ chối `sendMessage(...thread_id=1)`) - - hành động đang nhập vẫn bao gồm `message_thread_id` + - gửi tin nhắn bỏ qua `message_thread_id` (Telegram từ chối `sendMessage(...thread_id=1)`) + - hành động nhập vẫn bao gồm `message_thread_id` - Kế thừa chủ đề: các mục chủ đề kế thừa cài đặt nhóm trừ khi được ghi đè (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` chỉ thuộc chủ đề và không kế thừa từ mặc định nhóm. + Kế thừa chủ đề: mục chủ đề kế thừa thiết lập nhóm trừ khi bị ghi đè (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` chỉ thuộc về chủ đề và không kế thừa từ mặc định nhóm. - **Định tuyến agent theo từng chủ đề**: Mỗi chủ đề có thể định tuyến tới một agent khác bằng cách đặt `agentId` trong cấu hình chủ đề. Điều này cấp cho mỗi chủ đề workspace, bộ nhớ và phiên riêng biệt. Ví dụ: + **Định tuyến agent theo từng chủ đề**: Mỗi chủ đề có thể định tuyến tới một agent khác bằng cách đặt `agentId` trong cấu hình chủ đề. Việc này cho mỗi chủ đề workspace, bộ nhớ và phiên cô lập riêng. Ví dụ: ```json5 { @@ -587,24 +587,24 @@ curl "https://api.telegram.org/bot/getUpdates" Sau đó mỗi chủ đề có khóa phiên riêng: `agent:zu:telegram:group:-1001234567890:topic:3` - **Liên kết chủ đề ACP bền vững**: Chủ đề diễn đàn có thể ghim phiên harness ACP thông qua liên kết ACP có kiểu ở cấp cao nhất (`bindings[]` với `type: "acp"` và `match.channel: "telegram"`, `peer.kind: "group"` và id đủ điều kiện theo chủ đề như `-1001234567890:topic:42`). Hiện được giới hạn trong các chủ đề diễn đàn trong nhóm/siêu nhóm. Xem [Agent ACP](/vi/tools/acp-agents). + **Liên kết chủ đề ACP bền vững**: Chủ đề diễn đàn có thể ghim phiên harness ACP thông qua liên kết ACP có kiểu ở cấp cao nhất (`bindings[]` với `type: "acp"` và `match.channel: "telegram"`, `peer.kind: "group"`, và một id đủ điều kiện theo chủ đề như `-1001234567890:topic:42`). Hiện được giới hạn cho chủ đề diễn đàn trong nhóm/siêu nhóm. Xem [Agent ACP](/vi/tools/acp-agents). - **Sinh ACP gắn với luồng từ chat**: `/acp spawn --thread here|auto` liên kết chủ đề hiện tại với một phiên ACP mới; các lượt tiếp theo định tuyến trực tiếp tới đó. OpenClaw ghim xác nhận sinh trong chủ đề. Yêu cầu `channels.telegram.threadBindings.spawnSessions` vẫn được bật (mặc định: `true`). + **Spawn ACP gắn với luồng từ chat**: `/acp spawn --thread here|auto` liên kết chủ đề hiện tại với một phiên ACP mới; các lượt tiếp theo định tuyến trực tiếp tới đó. OpenClaw ghim xác nhận spawn trong chủ đề. Yêu cầu `channels.telegram.threadBindings.spawnSessions` vẫn được bật (mặc định: `true`). - Ngữ cảnh mẫu hiển thị `MessageThreadId` và `IsForum`. Các cuộc trò chuyện DM có `message_thread_id` giữ định tuyến DM và siêu dữ liệu trả lời trên phiên phẳng theo mặc định; chúng chỉ dùng khóa phiên nhận biết luồng khi được cấu hình với `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true`, hoặc cấu hình chủ đề khớp. Dùng `channels.telegram.dm.threadReplies` cấp cao nhất cho mặc định của tài khoản, hoặc `direct..threadReplies` cho một DM. + Ngữ cảnh mẫu hiển thị `MessageThreadId` và `IsForum`. Các cuộc trò chuyện DM có `message_thread_id` giữ định tuyến DM và siêu dữ liệu trả lời trên các phiên phẳng theo mặc định; chúng chỉ dùng khóa phiên nhận biết luồng khi được cấu hình với `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true`, hoặc cấu hình chủ đề khớp. Dùng `channels.telegram.dm.threadReplies` cấp cao nhất cho mặc định của tài khoản, hoặc `direct..threadReplies` cho một DM. ### Tin nhắn âm thanh - Telegram phân biệt ghi âm thoại và tệp âm thanh. + Telegram phân biệt ghi âm thoại với tệp âm thanh. - mặc định: hành vi tệp âm thanh - - thẻ `[[audio_as_voice]]` trong phản hồi của agent để buộc gửi dạng ghi âm thoại - - bản chép lời ghi âm thoại đầu vào được đóng khung là văn bản do máy tạo, - không đáng tin cậy trong ngữ cảnh agent; phát hiện đề cập vẫn dùng bản chép lời - thô nên tin nhắn thoại có cổng đề cập vẫn tiếp tục hoạt động. + - thẻ `[[audio_as_voice]]` trong trả lời của agent để buộc gửi ghi âm thoại + - bản chép lời ghi âm thoại gửi đến được đóng khung là văn bản do máy tạo, + không đáng tin cậy trong ngữ cảnh agent; phát hiện lượt nhắc vẫn dùng bản + chép lời thô nên các tin nhắn thoại được chặn bằng lượt nhắc vẫn tiếp tục hoạt động. Ví dụ hành động tin nhắn: @@ -620,7 +620,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Tin nhắn video - Telegram phân biệt tệp video và ghi chú video. + Telegram phân biệt tệp video với ghi chú video. Ví dụ hành động tin nhắn: @@ -638,9 +638,9 @@ curl "https://api.telegram.org/bot/getUpdates" ### Sticker - Xử lý sticker đầu vào: + Xử lý sticker gửi đến: - - WEBP tĩnh: được tải xuống và xử lý (placeholder ``) + - WEBP tĩnh: tải xuống và xử lý (placeholder ``) - TGS động: bỏ qua - WEBM video: bỏ qua @@ -656,7 +656,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Sticker được mô tả một lần (khi có thể) và được lưu vào bộ nhớ đệm để giảm các lệnh gọi thị giác lặp lại. + Sticker được mô tả một lần (khi có thể) và được lưu vào bộ nhớ đệm để giảm các lần gọi thị giác lặp lại. Bật hành động sticker: @@ -696,10 +696,10 @@ curl "https://api.telegram.org/bot/getUpdates" - - Phản ứng Telegram đến dưới dạng bản cập nhật `message_reaction` (tách biệt với payload tin nhắn). + + Reaction của Telegram đến dưới dạng bản cập nhật `message_reaction` (tách riêng với payload tin nhắn). - Khi được bật, OpenClaw đưa các sự kiện hệ thống vào hàng đợi, ví dụ: + Khi được bật, OpenClaw đưa các sự kiện hệ thống vào hàng đợi như: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -710,18 +710,18 @@ curl "https://api.telegram.org/bot/getUpdates" Ghi chú: - - `own` nghĩa là chỉ phản ứng của người dùng đối với tin nhắn do bot gửi (nỗ lực tốt nhất thông qua bộ nhớ đệm tin nhắn đã gửi). - - Sự kiện phản ứng vẫn tuân thủ kiểm soát truy cập Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); người gửi không được phép sẽ bị loại bỏ. - - Telegram không cung cấp ID luồng trong bản cập nhật phản ứng. + - `own` nghĩa là chỉ reaction của người dùng đối với tin nhắn do bot gửi (nỗ lực tối đa qua bộ nhớ đệm tin nhắn đã gửi). + - Sự kiện reaction vẫn tuân thủ các kiểm soát truy cập của Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); người gửi không được phép sẽ bị loại bỏ. + - Telegram không cung cấp ID luồng trong bản cập nhật reaction. - nhóm không phải diễn đàn định tuyến đến phiên trò chuyện nhóm - - nhóm diễn đàn định tuyến đến phiên chủ đề chung của nhóm (`:topic:1`), không phải đúng chủ đề gốc + - nhóm diễn đàn định tuyến đến phiên chủ đề chung của nhóm (`:topic:1`), không phải đúng chủ đề nguồn gốc chính xác `allowed_updates` cho polling/webhook tự động bao gồm `message_reaction`. - - `ackReaction` gửi một emoji xác nhận trong khi OpenClaw đang xử lý tin nhắn đầu vào. + + `ackReaction` gửi một emoji xác nhận trong khi OpenClaw đang xử lý tin nhắn gửi đến. Thứ tự phân giải: @@ -732,8 +732,8 @@ curl "https://api.telegram.org/bot/getUpdates" Ghi chú: - - Telegram mong đợi emoji unicode (ví dụ "👀"). - - Dùng `""` để tắt phản ứng cho một kênh hoặc tài khoản. + - Telegram yêu cầu emoji unicode (ví dụ "👀"). + - Dùng `""` để tắt reaction cho một kênh hoặc tài khoản. @@ -762,33 +762,34 @@ curl "https://api.telegram.org/bot/getUpdates" Mặc định là long polling. Đối với chế độ webhook, đặt `channels.telegram.webhookUrl` và `channels.telegram.webhookSecret`; tùy chọn `webhookPath`, `webhookHost`, `webhookPort` (mặc định `/telegram-webhook`, `127.0.0.1`, `8787`). - Trình nghe cục bộ bind vào `127.0.0.1:8787`. Đối với ingress công khai, hãy đặt reverse proxy trước cổng cục bộ hoặc chủ ý đặt `webhookHost: "0.0.0.0"`. + Trình lắng nghe cục bộ bind vào `127.0.0.1:8787`. Đối với ingress công khai, hoặc đặt proxy ngược phía trước cổng cục bộ hoặc cố ý đặt `webhookHost: "0.0.0.0"`. - Chế độ webhook xác thực các guard yêu cầu, token bí mật Telegram và thân JSON trước khi trả về `200` cho Telegram. - Sau đó OpenClaw xử lý bản cập nhật bất đồng bộ thông qua cùng các làn bot theo từng cuộc trò chuyện/từng chủ đề được long polling dùng, nên lượt agent chậm không giữ ACK giao hàng của Telegram. + Chế độ webhook xác thực guard yêu cầu, token bí mật Telegram và thân JSON trước khi trả về `200` cho Telegram. + Sau đó OpenClaw xử lý bản cập nhật bất đồng bộ qua cùng các lane bot theo từng cuộc trò chuyện/từng chủ đề mà long polling sử dụng, nên lượt agent chậm không giữ ACK gửi của Telegram. - - - `channels.telegram.textChunkLimit` mặc định là 4000. + + - Mặc định của `channels.telegram.textChunkLimit` là 4000. - `channels.telegram.chunkMode="newline"` ưu tiên ranh giới đoạn văn (dòng trống) trước khi chia theo độ dài. - - `channels.telegram.mediaMaxMb` (mặc định 100) giới hạn kích thước media Telegram đầu vào và đầu ra. - - `channels.telegram.mediaGroupFlushMs` (mặc định 500) kiểm soát thời gian album/nhóm media Telegram được đệm trước khi OpenClaw dispatch chúng thành một tin nhắn đầu vào. Tăng giá trị này nếu các phần album đến muộn; giảm giá trị này để giảm độ trễ phản hồi album. - - `channels.telegram.timeoutSeconds` ghi đè thời gian chờ của client Telegram API (nếu chưa đặt, mặc định grammY được áp dụng). Client bot kẹp các giá trị đã cấu hình thấp hơn guard yêu cầu văn bản/typing đầu ra 60 giây để grammY không hủy giao hàng phản hồi hiển thị trước khi guard vận chuyển và dự phòng của OpenClaw có thể chạy. Long polling vẫn dùng guard yêu cầu `getUpdates` 45 giây để các poll nhàn rỗi không bị bỏ mặc vô thời hạn. - - `channels.telegram.pollingStallThresholdMs` mặc định là `120000`; chỉ tinh chỉnh trong khoảng `30000` đến `600000` cho các lần khởi động lại do polling bị kẹt dương tính giả. + - `channels.telegram.mediaMaxMb` (mặc định 100) giới hạn kích thước media Telegram gửi đến và gửi đi. + - `channels.telegram.mediaGroupFlushMs` (mặc định 500) kiểm soát thời gian các album/nhóm media Telegram được buffer trước khi OpenClaw dispatch chúng thành một tin nhắn gửi đến. Tăng giá trị này nếu các phần album đến muộn; giảm để giảm độ trễ trả lời album. + - `channels.telegram.timeoutSeconds` ghi đè timeout của client Telegram API (nếu chưa đặt, mặc định grammY được áp dụng). Client bot kẹp các giá trị cấu hình thấp hơn guard yêu cầu văn bản/typing gửi đi 60 giây để grammY không hủy gửi trả lời hiển thị trước khi guard transport và dự phòng của OpenClaw có thể chạy. Long polling vẫn dùng guard yêu cầu `getUpdates` 45 giây để các lượt poll nhàn rỗi không bị bỏ vô thời hạn. + - `channels.telegram.pollingStallThresholdMs` mặc định là `120000`; chỉ tinh chỉnh trong khoảng `30000` đến `600000` cho các lần khởi động lại polling-stall dương tính giả. - lịch sử ngữ cảnh nhóm dùng `channels.telegram.historyLimit` hoặc `messages.groupChat.historyLimit` (mặc định 50); `0` sẽ tắt. - ngữ cảnh bổ sung trả lời/trích dẫn/chuyển tiếp hiện được truyền như đã nhận. - - allowlist Telegram chủ yếu kiểm soát ai có thể kích hoạt agent, không phải ranh giới biên tập lại ngữ cảnh bổ sung đầy đủ. - - Điều khiển lịch sử DM: + - allowlist của Telegram chủ yếu chặn ai có thể kích hoạt agent, không phải một ranh giới biên tập ngữ cảnh bổ sung đầy đủ. + - điều khiển lịch sử DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - cấu hình `channels.telegram.retry` áp dụng cho helper gửi Telegram (CLI/công cụ/hành động) đối với lỗi API đầu ra có thể khôi phục. Giao hàng phản hồi cuối đầu vào cũng dùng một lần thử lại gửi an toàn có giới hạn cho lỗi Telegram trước khi kết nối, nhưng không thử lại các envelope mạng mơ hồ sau khi gửi có thể nhân đôi tin nhắn hiển thị. + - Cấu hình `channels.telegram.retry` áp dụng cho các helper gửi Telegram (CLI/công cụ/hành động) đối với lỗi API gửi đi có thể khôi phục. Gửi trả lời cuối cùng đến cũng dùng một lần thử lại safe-send có giới hạn cho lỗi Telegram trước khi kết nối, nhưng không thử lại các envelope mạng sau khi gửi có tính mơ hồ có thể nhân đôi tin nhắn hiển thị. - Đích gửi CLI có thể là ID cuộc trò chuyện dạng số hoặc tên người dùng: + Mục tiêu gửi của CLI và công cụ tin nhắn có thể là ID trò chuyện dạng số, username, hoặc mục tiêu chủ đề diễn đàn: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" +openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic" ``` Poll Telegram dùng `openclaw message poll` và hỗ trợ chủ đề diễn đàn: @@ -801,57 +802,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Cờ poll chỉ dành cho Telegram: + Flag poll chỉ dành cho Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` cho chủ đề diễn đàn (hoặc dùng đích `:topic:`) + - `--thread-id` cho chủ đề diễn đàn (hoặc dùng mục tiêu `:topic:`) Gửi Telegram cũng hỗ trợ: - `--presentation` với khối `buttons` cho bàn phím inline khi `channels.telegram.capabilities.inlineButtons` cho phép - - `--pin` hoặc `--delivery '{"pin":true}'` để yêu cầu giao hàng được ghim khi bot có thể ghim trong cuộc trò chuyện đó - - `--force-document` để gửi hình ảnh và GIF đầu ra dưới dạng tài liệu thay vì tải lên ảnh nén hoặc media động + - `--pin` hoặc `--delivery '{"pin":true}'` để yêu cầu gửi ghim khi bot có thể ghim trong cuộc trò chuyện đó + - `--force-document` để gửi hình ảnh gửi đi và GIF dưới dạng tài liệu thay vì tải lên ảnh nén hoặc media động - Kiểm soát hành động: + Chặn hành động: - - `channels.telegram.actions.sendMessage=false` tắt tin nhắn Telegram đầu ra, bao gồm cả poll + - `channels.telegram.actions.sendMessage=false` tắt tin nhắn Telegram gửi đi, bao gồm poll - `channels.telegram.actions.poll=false` tắt tạo poll Telegram trong khi vẫn bật gửi thông thường - Telegram hỗ trợ phê duyệt exec trong DM của người phê duyệt và có thể tùy chọn đăng prompt trong cuộc trò chuyện hoặc chủ đề gốc. Người phê duyệt phải là ID người dùng Telegram dạng số. + Telegram hỗ trợ phê duyệt exec trong DM của người phê duyệt và có thể tùy chọn đăng lời nhắc trong cuộc trò chuyện hoặc chủ đề nguồn gốc. Người phê duyệt phải là ID người dùng Telegram dạng số. Đường dẫn cấu hình: - - `channels.telegram.execApprovals.enabled` (tự động bật khi ít nhất một người phê duyệt có thể phân giải) - - `channels.telegram.execApprovals.approvers` (dự phòng về ID chủ sở hữu dạng số từ `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.enabled` (tự động bật khi có thể phân giải ít nhất một người phê duyệt) + - `channels.telegram.execApprovals.approvers` (dự phòng sang ID chủ sở hữu dạng số từ `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (mặc định) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` và `defaultTo` kiểm soát ai có thể nói chuyện với bot và nơi bot gửi phản hồi thông thường. Chúng không biến ai đó thành người phê duyệt exec. Ghép cặp DM được phê duyệt đầu tiên bootstrap `commands.ownerAllowFrom` khi chưa có chủ sở hữu lệnh nào, nên thiết lập một chủ sở hữu vẫn hoạt động mà không cần sao chép ID trong `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom`, và `defaultTo` kiểm soát ai có thể nói chuyện với bot và nơi bot gửi trả lời thông thường. Chúng không biến ai đó thành người phê duyệt exec. Ghép cặp DM được phê duyệt đầu tiên sẽ bootstrap `commands.ownerAllowFrom` khi chưa có chủ sở hữu lệnh nào, nên thiết lập một chủ sở hữu vẫn hoạt động mà không cần nhân đôi ID dưới `execApprovals.approvers`. - Giao hàng kênh hiển thị văn bản lệnh trong cuộc trò chuyện; chỉ bật `channel` hoặc `both` trong các nhóm/chủ đề đáng tin cậy. Khi prompt đến trong một chủ đề diễn đàn, OpenClaw giữ nguyên chủ đề cho prompt phê duyệt và phần theo dõi. Phê duyệt exec hết hạn sau 30 phút theo mặc định. + Gửi qua kênh hiển thị văn bản lệnh trong cuộc trò chuyện; chỉ bật `channel` hoặc `both` trong các nhóm/chủ đề đáng tin cậy. Khi lời nhắc đến trong một chủ đề diễn đàn, OpenClaw giữ nguyên chủ đề cho lời nhắc phê duyệt và lượt theo sau. Phê duyệt exec hết hạn sau 30 phút theo mặc định. - Nút phê duyệt inline cũng yêu cầu `channels.telegram.capabilities.inlineButtons` cho phép bề mặt đích (`dm`, `group`, hoặc `all`). ID phê duyệt có tiền tố `plugin:` phân giải qua phê duyệt plugin; các ID khác phân giải qua phê duyệt exec trước. + Nút phê duyệt inline cũng yêu cầu `channels.telegram.capabilities.inlineButtons` cho phép bề mặt mục tiêu (`dm`, `group`, hoặc `all`). ID phê duyệt có tiền tố `plugin:` phân giải qua phê duyệt Plugin; các ID khác phân giải qua phê duyệt exec trước. Xem [Phê duyệt exec](/vi/tools/exec-approvals). -## Điều khiển phản hồi lỗi +## Điều khiển trả lời lỗi -Khi agent gặp lỗi giao hàng hoặc lỗi provider, Telegram có thể trả lời bằng văn bản lỗi hoặc chặn lỗi đó. Hai khóa cấu hình kiểm soát hành vi này: +Khi agent gặp lỗi gửi hoặc lỗi provider, Telegram có thể trả lời bằng văn bản lỗi hoặc ẩn lỗi đó. Hai khóa cấu hình kiểm soát hành vi này: | Khóa | Giá trị | Mặc định | Mô tả | | ----------------------------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` gửi tin nhắn lỗi thân thiện đến cuộc trò chuyện. `silent` chặn hoàn toàn phản hồi lỗi. | -| `channels.telegram.errorCooldownMs` | số (ms) | `60000` | Thời gian tối thiểu giữa các phản hồi lỗi đến cùng một cuộc trò chuyện. Ngăn spam lỗi khi có sự cố mất dịch vụ. | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` gửi một tin nhắn lỗi thân thiện đến cuộc trò chuyện. `silent` ẩn hoàn toàn trả lời lỗi. | +| `channels.telegram.errorCooldownMs` | số (ms) | `60000` | Thời gian tối thiểu giữa các trả lời lỗi đến cùng một cuộc trò chuyện. Ngăn spam lỗi khi sự cố. | -Hỗ trợ ghi đè theo từng tài khoản, từng nhóm và từng chủ đề (cùng cơ chế kế thừa như các khóa cấu hình Telegram khác). +Hỗ trợ ghi đè theo từng tài khoản, từng nhóm và từng chủ đề (cùng kế thừa như các khóa cấu hình Telegram khác). ```json5 { @@ -872,13 +873,13 @@ Hỗ trợ ghi đè theo từng tài khoản, từng nhóm và từng chủ đ ## Khắc phục sự cố - + - - Nếu `requireMention=false`, chế độ riêng tư Telegram phải cho phép hiển thị đầy đủ. + - Nếu `requireMention=false`, chế độ quyền riêng tư của Telegram phải cho phép hiển thị đầy đủ. - BotFather: `/setprivacy` -> Disable - - sau đó xóa + thêm lại bot vào nhóm - - `openclaw channels status` cảnh báo khi cấu hình mong đợi tin nhắn nhóm không được đề cập. - - `openclaw channels status --probe` có thể kiểm tra ID nhóm dạng số rõ ràng; wildcard `"*"` không thể được probe tư cách thành viên. + - sau đó xóa bot khỏi nhóm rồi thêm lại + - `openclaw channels status` cảnh báo khi cấu hình mong đợi tin nhắn nhóm không nhắc tên. + - `openclaw channels status --probe` có thể kiểm tra ID nhóm dạng số rõ ràng; ký tự đại diện `"*"` không thể được kiểm tra tư cách thành viên. - kiểm tra phiên nhanh: `/activation always`. @@ -886,7 +887,7 @@ Hỗ trợ ghi đè theo từng tài khoản, từng nhóm và từng chủ đ - khi `channels.telegram.groups` tồn tại, nhóm phải được liệt kê (hoặc bao gồm `"*"`) - - xác minh bot là thành viên trong nhóm + - xác minh tư cách thành viên của bot trong nhóm - xem lại nhật ký: `openclaw logs --follow` để biết lý do bỏ qua @@ -895,33 +896,33 @@ Hỗ trợ ghi đè theo từng tài khoản, từng nhóm và từng chủ đ - ủy quyền danh tính người gửi của bạn (ghép nối và/hoặc `allowFrom` dạng số) - ủy quyền lệnh vẫn áp dụng ngay cả khi chính sách nhóm là `open` - - `setMyCommands failed` với `BOT_COMMANDS_TOO_MUCH` nghĩa là menu gốc có quá nhiều mục; giảm số lượng lệnh plugin/skill/tùy chỉnh hoặc tắt menu gốc - - các lệnh khởi động `deleteMyCommands` / `setMyCommands` và lệnh hiển thị đang nhập `sendChatAction` được giới hạn thời gian và thử lại một lần qua phương án dự phòng truyền tải của Telegram khi yêu cầu hết thời gian chờ. Lỗi mạng/fetch kéo dài thường cho thấy vấn đề về khả năng truy cập DNS/HTTPS tới `api.telegram.org` + - `setMyCommands failed` với `BOT_COMMANDS_TOO_MUCH` nghĩa là menu gốc có quá nhiều mục; hãy giảm lệnh Plugin/Skills/tùy chỉnh hoặc tắt menu gốc + - các lệnh khởi động `deleteMyCommands` / `setMyCommands` và các lệnh nhập `sendChatAction` được giới hạn thời gian và thử lại một lần qua cơ chế dự phòng truyền tải của Telegram khi yêu cầu hết thời gian chờ. Lỗi mạng/fetch kéo dài thường cho thấy vấn đề DNS/HTTPS khi truy cập `api.telegram.org` - + - `getMe returned 401` là lỗi xác thực Telegram đối với token bot đã cấu hình. - - Sao chép lại hoặc tạo lại token bot trong BotFather, rồi cập nhật `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken`, hoặc `TELEGRAM_BOT_TOKEN` cho tài khoản mặc định. - - `deleteWebhook 401 Unauthorized` trong quá trình khởi động cũng là lỗi xác thực; coi nó là "không có webhook nào tồn tại" sẽ chỉ trì hoãn cùng lỗi token sai đó sang các lệnh gọi API sau. + - Sao chép lại hoặc tạo lại token bot trong BotFather, sau đó cập nhật `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken`, hoặc `TELEGRAM_BOT_TOKEN` cho tài khoản mặc định. + - `deleteWebhook 401 Unauthorized` trong khi khởi động cũng là lỗi xác thực; xử lý lỗi này như “không có webhook nào tồn tại” sẽ chỉ trì hoãn cùng lỗi token sai đó sang các lệnh gọi API sau. - Node 22+ + fetch/proxy tùy chỉnh có thể kích hoạt hành vi hủy ngay lập tức nếu kiểu AbortSignal không khớp. - - Một số máy chủ phân giải `api.telegram.org` sang IPv6 trước; đầu ra IPv6 bị lỗi có thể gây lỗi Telegram API gián đoạn. + - Một số máy chủ phân giải `api.telegram.org` sang IPv6 trước; đường ra IPv6 bị lỗi có thể gây lỗi API Telegram gián đoạn. - Nếu nhật ký bao gồm `TypeError: fetch failed` hoặc `Network request for 'getUpdates' failed!`, OpenClaw hiện thử lại các lỗi này như lỗi mạng có thể khôi phục. - - Trong quá trình khởi động polling, OpenClaw tái sử dụng probe `getMe` khởi động thành công cho grammY để runner không cần `getMe` lần thứ hai trước `getUpdates` đầu tiên. - - Nếu `deleteWebhook` thất bại với lỗi mạng tạm thời trong quá trình khởi động polling, OpenClaw tiếp tục vào long polling thay vì thực hiện một lệnh gọi control-plane trước poll khác. Webhook vẫn đang hoạt động sẽ xuất hiện dưới dạng xung đột `getUpdates`; sau đó OpenClaw dựng lại truyền tải Telegram và thử lại dọn dẹp webhook. - - Nếu socket Telegram tái tạo theo chu kỳ cố định ngắn, hãy kiểm tra `channels.telegram.timeoutSeconds` thấp; client bot kẹp các giá trị đã cấu hình thấp hơn các guard yêu cầu outbound và `getUpdates`, nhưng các bản phát hành cũ hơn có thể hủy mọi poll hoặc phản hồi khi giá trị này được đặt thấp hơn các guard đó. - - Nếu nhật ký bao gồm `Polling stall detected`, OpenClaw khởi động lại polling và dựng lại truyền tải Telegram sau 120 giây không có liveness long-poll hoàn tất theo mặc định. + - Trong khi khởi động polling, OpenClaw tái sử dụng lần thăm dò `getMe` khởi động thành công cho grammY để runner không cần `getMe` lần thứ hai trước `getUpdates` đầu tiên. + - Nếu `deleteWebhook` thất bại với lỗi mạng tạm thời trong khi khởi động polling, OpenClaw tiếp tục vào long polling thay vì thực hiện thêm một lệnh gọi control-plane trước polling. Webhook vẫn đang hoạt động sẽ xuất hiện dưới dạng xung đột `getUpdates`; khi đó OpenClaw dựng lại truyền tải Telegram và thử dọn dẹp webhook lại. + - Nếu socket Telegram được tái tạo theo chu kỳ cố định ngắn, hãy kiểm tra `channels.telegram.timeoutSeconds` có thấp không; client bot sẽ kẹp các giá trị cấu hình thấp hơn các chốt bảo vệ yêu cầu gửi ra và `getUpdates`, nhưng các bản phát hành cũ hơn có thể hủy mọi lượt polling hoặc phản hồi khi giá trị này được đặt thấp hơn các chốt bảo vệ đó. + - Nếu nhật ký bao gồm `Polling stall detected`, mặc định OpenClaw khởi động lại polling và dựng lại truyền tải Telegram sau 120 giây không có long-poll liveness hoàn tất. - `openclaw channels status --probe` và `openclaw doctor` cảnh báo khi một tài khoản polling đang chạy chưa hoàn tất `getUpdates` sau thời gian gia hạn khởi động, khi một tài khoản webhook đang chạy chưa hoàn tất `setWebhook` sau thời gian gia hạn khởi động, hoặc khi hoạt động truyền tải polling thành công gần nhất đã cũ. - - Chỉ tăng `channels.telegram.pollingStallThresholdMs` khi các lệnh gọi `getUpdates` chạy lâu vẫn khỏe mạnh nhưng máy chủ của bạn vẫn báo cáo sai các lần khởi động lại do polling bị đình trệ. Đình trệ kéo dài thường chỉ ra vấn đề proxy, DNS, IPv6 hoặc đầu ra TLS giữa máy chủ và `api.telegram.org`. - - Telegram cũng tôn trọng env proxy của tiến trình cho truyền tải Bot API, bao gồm `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, và các biến chữ thường tương ứng. `NO_PROXY` / `no_proxy` vẫn có thể bỏ qua `api.telegram.org`. - - Nếu proxy do OpenClaw quản lý được cấu hình qua `OPENCLAW_PROXY_URL` cho môi trường dịch vụ và không có env proxy chuẩn nào, Telegram cũng dùng URL đó cho truyền tải Bot API. - - Trên máy chủ VPS có đầu ra/TLS trực tiếp không ổn định, định tuyến các lệnh gọi Telegram API qua `channels.telegram.proxy`: + - Chỉ tăng `channels.telegram.pollingStallThresholdMs` khi các lệnh gọi `getUpdates` chạy dài vẫn khỏe mạnh nhưng máy chủ của bạn vẫn báo cáo sai việc khởi động lại do polling bị treo. Tình trạng treo kéo dài thường chỉ ra vấn đề proxy, DNS, IPv6, hoặc đường ra TLS giữa máy chủ và `api.telegram.org`. + - Telegram cũng tôn trọng biến môi trường proxy của tiến trình cho truyền tải Bot API, bao gồm `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, và các biến chữ thường tương ứng. `NO_PROXY` / `no_proxy` vẫn có thể bỏ qua `api.telegram.org`. + - Nếu proxy do OpenClaw quản lý được cấu hình qua `OPENCLAW_PROXY_URL` cho môi trường dịch vụ và không có biến môi trường proxy tiêu chuẩn nào, Telegram cũng dùng URL đó cho truyền tải Bot API. + - Trên máy chủ VPS có đường ra/TLS trực tiếp không ổn định, định tuyến các lệnh gọi API Telegram qua `channels.telegram.proxy`: ```yaml channels: @@ -929,8 +930,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ mặc định là `autoSelectFamily=true` (trừ WSL2). Thứ tự kết quả DNS của Telegram tôn trọng `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, rồi `channels.telegram.network.dnsResultOrder`, rồi mặc định của tiến trình như `NODE_OPTIONS=--dns-result-order=ipv4first`; nếu không có cấu hình nào áp dụng, Node 22+ quay về `ipv4first`. - - Nếu máy chủ của bạn là WSL2 hoặc rõ ràng hoạt động tốt hơn với hành vi chỉ IPv4, hãy ép chọn họ địa chỉ: + - Node 22+ mặc định dùng `autoSelectFamily=true` (trừ WSL2). Thứ tự kết quả DNS của Telegram tôn trọng `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, rồi `channels.telegram.network.dnsResultOrder`, rồi mặc định của tiến trình như `NODE_OPTIONS=--dns-result-order=ipv4first`; nếu không có mục nào áp dụng, Node 22+ quay về `ipv4first`. + - Nếu máy chủ của bạn là WSL2 hoặc rõ ràng hoạt động tốt hơn với hành vi chỉ IPv4, hãy ép chọn family: ```yaml channels: @@ -939,11 +940,11 @@ channels: autoSelectFamily: false ``` - - Các phản hồi thuộc dải benchmark RFC 2544 (`198.18.0.0/15`) đã được cho phép - cho tải xuống media Telegram theo mặc định. Nếu một proxy fake-IP hoặc - proxy trong suốt đáng tin cậy ghi lại `api.telegram.org` thành một địa chỉ - private/internal/special-use khác trong quá trình tải xuống media, bạn có thể chọn - tham gia cơ chế bỏ qua chỉ dành cho Telegram: + - Câu trả lời thuộc dải benchmark RFC 2544 (`198.18.0.0/15`) đã được cho phép + theo mặc định đối với tải xuống media Telegram. Nếu một fake-IP đáng tin cậy hoặc + proxy trong suốt ghi lại `api.telegram.org` thành một địa chỉ + riêng tư/nội bộ/dùng đặc biệt khác trong khi tải xuống media, bạn có thể chọn + bật bỏ qua chỉ dành cho Telegram: ```yaml channels: @@ -952,25 +953,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Tùy chọn tham gia tương tự có sẵn theo từng tài khoản tại + - Tùy chọn bật tương tự có sẵn theo từng tài khoản tại `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - Nếu proxy của bạn phân giải máy chủ media Telegram thành `198.18.x.x`, trước tiên hãy để cờ nguy hiểm tắt. Media Telegram đã cho phép dải benchmark RFC 2544 theo mặc định. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` làm yếu các biện pháp - bảo vệ SSRF cho media Telegram. Chỉ dùng nó cho các môi trường proxy do - operator đáng tin cậy kiểm soát như định tuyến fake-IP Clash, Mihomo hoặc Surge khi chúng - tổng hợp các phản hồi private hoặc special-use ngoài dải benchmark RFC 2544. - Hãy để tắt cho truy cập Telegram qua internet công cộng thông thường. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` làm suy yếu khả năng bảo vệ SSRF + media Telegram. Chỉ dùng tùy chọn này cho các môi trường proxy đáng tin cậy do operator kiểm soát + như định tuyến fake-IP của Clash, Mihomo, hoặc Surge khi chúng + tổng hợp các câu trả lời riêng tư hoặc dùng đặc biệt nằm ngoài dải benchmark + RFC 2544. Hãy để tắt đối với truy cập Telegram qua internet công cộng bình thường. - - Ghi đè môi trường (tạm thời): + - Ghi đè bằng môi trường (tạm thời): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Xác thực phản hồi DNS: + - Xác thực câu trả lời DNS: ```bash dig +short api.telegram.org A @@ -988,13 +989,13 @@ Tham chiếu chính: [Tham chiếu cấu hình - Telegram](/vi/gateway/config-ch -- khởi động/xác thực: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` phải trỏ tới một tệp thông thường; symlink bị từ chối) +- khởi động/xác thực: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` phải trỏ đến một tệp thông thường; symlink bị từ chối) - kiểm soát truy cập: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` cấp cao nhất (`type: "acp"`) - phê duyệt exec: `execApprovals`, `accounts.*.execApprovals` - lệnh/menu: `commands.native`, `commands.nativeSkills`, `customCommands` - luồng/phản hồi: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` -- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` -- định dạng/phân phối: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- streaming: `streaming` (bản xem trước), `streaming.preview.toolProgress`, `blockStreaming` +- định dạng/gửi: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - media/mạng: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - gốc API tùy chỉnh: `apiRoot` (chỉ gốc Bot API; không bao gồm `/bot`) - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` @@ -1006,26 +1007,26 @@ Tham chiếu chính: [Tham chiếu cấu hình - Telegram](/vi/gateway/config-ch -Độ ưu tiên nhiều tài khoản: khi hai hoặc nhiều ID tài khoản được cấu hình, hãy đặt `channels.telegram.defaultAccount` (hoặc bao gồm `channels.telegram.accounts.default`) để định tuyến mặc định rõ ràng. Nếu không, OpenClaw quay về ID tài khoản đã chuẩn hóa đầu tiên và `openclaw doctor` cảnh báo. Tài khoản có tên kế thừa `channels.telegram.allowFrom` / `groupAllowFrom`, nhưng không kế thừa các giá trị `accounts.default.*`. +Thứ tự ưu tiên đa tài khoản: khi cấu hình hai ID tài khoản trở lên, hãy đặt `channels.telegram.defaultAccount` (hoặc bao gồm `channels.telegram.accounts.default`) để định tuyến mặc định rõ ràng. Nếu không, OpenClaw quay về ID tài khoản đã chuẩn hóa đầu tiên và `openclaw doctor` cảnh báo. Tài khoản được đặt tên kế thừa `channels.telegram.allowFrom` / `groupAllowFrom`, nhưng không kế thừa các giá trị `accounts.default.*`. ## Liên quan - Ghép nối người dùng Telegram với Gateway. + Ghép nối người dùng Telegram với gateway. - Hành vi danh sách cho phép của nhóm và chủ đề. + Hành vi allowlist cho nhóm và chủ đề. - Định tuyến tin nhắn đến vào các agent. + Định tuyến tin nhắn đến đến agent. - Mô hình mối đe dọa và gia cố. + Mô hình đe dọa và gia cố bảo mật. - - Ánh xạ nhóm và chủ đề tới các agent. + + Ánh xạ nhóm và chủ đề tới agent. Chẩn đoán liên kênh. diff --git a/docs/vi/cli/message.md b/docs/vi/cli/message.md index 26e786274..b3bdfd953 100644 --- a/docs/vi/cli/message.md +++ b/docs/vi/cli/message.md @@ -2,23 +2,23 @@ read_when: - Thêm hoặc sửa đổi các hành động CLI cho tin nhắn - Thay đổi hành vi kênh gửi đi -summary: Tham chiếu CLI cho `openclaw message` (gửi + hành động kênh) +summary: Tham chiếu CLI cho `openclaw message` (send + các hành động kênh) title: Tin nhắn x-i18n: - generated_at: "2026-05-02T20:42:23Z" + generated_at: "2026-05-04T09:37:06Z" model: gpt-5.5 provider: openai - source_hash: 6b73a50da34838f80ad5d0d266f5c66f95436f8535e6312296ae022918b1ab55 + source_hash: 9ef57d33c93206a61a6d044667de4faf6340f7d8cc324300f235e838ee3b7ff1 source_path: cli/message.md workflow: 16 --- # `openclaw message` -Lệnh gửi đi duy nhất để gửi tin nhắn và hành động kênh +Lệnh gửi đi duy nhất để gửi tin nhắn và thao tác kênh (Discord/Google Chat/iMessage/Matrix/Mattermost (Plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp). -## Cách sử dụng +## Cách dùng ``` openclaw message [flags] @@ -26,50 +26,50 @@ openclaw message [flags] Chọn kênh: -- Bắt buộc có `--channel` nếu đã cấu hình nhiều hơn một kênh. -- Nếu chỉ cấu hình đúng một kênh, kênh đó trở thành mặc định. +- Bắt buộc có `--channel` nếu cấu hình nhiều hơn một kênh. +- Nếu cấu hình đúng một kênh, kênh đó trở thành mặc định. - Giá trị: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost yêu cầu Plugin) -- `openclaw message` phân giải kênh đã chọn tới Plugin sở hữu kênh đó khi có `--channel` hoặc mục tiêu có tiền tố kênh; nếu không, lệnh sẽ tải các Plugin kênh đã cấu hình để suy luận kênh mặc định. +- `openclaw message` phân giải kênh đã chọn tới Plugin sở hữu kênh đó khi có `--channel` hoặc một đích có tiền tố kênh; nếu không, nó tải các Plugin kênh đã cấu hình để suy luận kênh mặc định. -Định dạng mục tiêu (`--target`): +Định dạng đích (`--target`): - WhatsApp: E.164, JID nhóm, hoặc JID WhatsApp Channel/Newsletter (`...@newsletter`) -- Telegram: ID cuộc trò chuyện hoặc `@username` -- Discord: `channel:` hoặc `user:` (hoặc đề cập `<@id>`; ID số thô được xem là kênh) +- Telegram: id cuộc trò chuyện, `@username`, hoặc đích chủ đề diễn đàn (`-1001234567890:topic:42`, hoặc `--thread-id 42`) +- Discord: `channel:` hoặc `user:` (hoặc mention `<@id>`; id số thô được xem là kênh) - Google Chat: `spaces/` hoặc `users/` -- Slack: `channel:` hoặc `user:` (chấp nhận ID kênh thô) -- Mattermost (Plugin): `channel:`, `user:`, hoặc `@username` (ID trần được xem là kênh) +- Slack: `channel:` hoặc `user:` (chấp nhận id kênh thô) +- Mattermost (Plugin): `channel:`, `user:`, hoặc `@username` (id trần được xem là kênh) - Signal: `+E.164`, `group:`, `signal:+E.164`, `signal:group:`, hoặc `username:`/`u:` - iMessage: định danh, `chat_id:`, `chat_guid:`, hoặc `chat_identifier:` - Matrix: `@user:server`, `!room:server`, hoặc `#alias:server` -- Microsoft Teams: ID cuộc hội thoại (`19:...@thread.tacv2`) hoặc `conversation:` hoặc `user:` +- Microsoft Teams: id cuộc hội thoại (`19:...@thread.tacv2`) hoặc `conversation:` hoặc `user:` Tra cứu tên: -- Với các nhà cung cấp được hỗ trợ (Discord/Slack/etc), tên kênh như `Help` hoặc `#help` được phân giải qua bộ nhớ đệm thư mục. -- Khi trượt bộ nhớ đệm, OpenClaw sẽ thử tra cứu thư mục trực tiếp nếu nhà cung cấp hỗ trợ. +- Với các nhà cung cấp được hỗ trợ (Discord/Slack/v.v.), tên kênh như `Help` hoặc `#help` được phân giải qua bộ nhớ đệm thư mục. +- Khi không tìm thấy trong bộ nhớ đệm, OpenClaw sẽ thử tra cứu thư mục trực tiếp nếu nhà cung cấp hỗ trợ. ## Cờ thường dùng - `--channel ` - `--account ` -- `--target ` (kênh hoặc người dùng mục tiêu cho send/poll/read/etc) -- `--targets ` (lặp lại; chỉ phát rộng) +- `--target ` (kênh hoặc người dùng đích cho send/poll/read/v.v.) +- `--targets ` (lặp lại; chỉ broadcast) - `--json` - `--dry-run` - `--verbose` ## Hành vi SecretRef -- `openclaw message` phân giải các SecretRef kênh được hỗ trợ trước khi chạy hành động đã chọn. -- Việc phân giải được giới hạn trong mục tiêu hành động đang hoạt động khi có thể: - - theo phạm vi kênh khi đặt `--channel` (hoặc suy luận từ các mục tiêu có tiền tố như `discord:...`) +- `openclaw message` phân giải các SecretRef kênh được hỗ trợ trước khi chạy thao tác đã chọn. +- Việc phân giải được giới hạn theo đích thao tác đang hoạt động khi có thể: + - theo phạm vi kênh khi đặt `--channel` (hoặc được suy luận từ các đích có tiền tố như `discord:...`) - theo phạm vi tài khoản khi đặt `--account` (biến toàn cục của kênh + các bề mặt tài khoản đã chọn) - khi bỏ qua `--account`, OpenClaw không ép phạm vi SecretRef tài khoản `default` -- SecretRef chưa phân giải trên các kênh không liên quan không chặn hành động nhắn tin có mục tiêu. -- Nếu SecretRef của kênh/tài khoản đã chọn chưa được phân giải, lệnh sẽ thất bại đóng cho hành động đó. +- SecretRef chưa phân giải trên các kênh không liên quan không chặn một thao tác nhắn tin có đích cụ thể. +- Nếu SecretRef của kênh/tài khoản đã chọn chưa được phân giải, lệnh sẽ đóng thất bại cho thao tác đó. -## Hành động +## Thao tác ### Lõi @@ -77,10 +77,10 @@ Tra cứu tên: - Kênh: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix/Microsoft Teams - Bắt buộc: `--target`, cộng với `--message`, `--media`, hoặc `--presentation` - Tùy chọn: `--media`, `--presentation`, `--delivery`, `--pin`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent` - - Tải trình bày dùng chung: `--presentation` gửi các khối ngữ nghĩa (`text`, `context`, `divider`, `buttons`, `select`) mà lõi kết xuất thông qua các năng lực đã khai báo của kênh được chọn. Xem [Trình Bày Tin Nhắn](/vi/plugins/message-presentation). - - Tùy chọn giao nhận chung: `--delivery` chấp nhận các gợi ý giao nhận như `{ "pin": true }`; `--pin` là cách viết tắt cho giao nhận được ghim khi kênh hỗ trợ. + - Payload trình bày dùng chung: `--presentation` gửi các khối ngữ nghĩa (`text`, `context`, `divider`, `buttons`, `select`) mà lõi kết xuất qua các khả năng đã khai báo của kênh đã chọn. Xem [Trình bày tin nhắn](/vi/plugins/message-presentation). + - Tùy chọn phân phối chung: `--delivery` chấp nhận các gợi ý phân phối như `{ "pin": true }`; `--pin` là cách viết tắt cho phân phối được ghim khi kênh hỗ trợ. - Chỉ Telegram: `--force-document` (gửi ảnh và GIF dưới dạng tài liệu để tránh Telegram nén) - - Chỉ Telegram: `--thread-id` (ID chủ đề diễn đàn) + - Chỉ Telegram: `--thread-id` (id chủ đề diễn đàn) - Chỉ Slack: `--thread-id` (dấu thời gian luồng; `--reply-to` dùng cùng trường) - Telegram + Discord: `--silent` - Chỉ WhatsApp: `--gif-playback`; WhatsApp Channels/Newsletters được định địa chỉ bằng JID `@newsletter` gốc của chúng. @@ -109,7 +109,7 @@ Tra cứu tên: - Kênh: Discord/Slack/Matrix - Bắt buộc: `--target` - Tùy chọn: `--limit`, `--message-id`, `--before`, `--after` - - Chỉ Slack: `--message-id` đọc dấu thời gian của một tin nhắn Slack cụ thể; kết hợp với `--thread-id` để đọc chính xác một trả lời trong luồng. + - Chỉ Slack: `--message-id` đọc một dấu thời gian tin nhắn Slack cụ thể; kết hợp với `--thread-id` để đọc một phản hồi luồng chính xác. - Chỉ Discord: `--around` - `edit` @@ -131,7 +131,7 @@ Tra cứu tên: - `permissions` - Kênh: Discord/Matrix - Bắt buộc: `--target` - - Chỉ Matrix: khả dụng khi mã hóa Matrix được bật và các hành động xác minh được phép + - Chỉ Matrix: khả dụng khi mã hóa Matrix được bật và các thao tác xác minh được cho phép - `search` - Kênh: Discord @@ -142,7 +142,7 @@ Tra cứu tên: - `thread create` - Kênh: Discord - - Bắt buộc: `--thread-name`, `--target` (ID kênh) + - Bắt buộc: `--thread-name`, `--target` (id kênh) - Tùy chọn: `--message-id`, `--message`, `--auto-archive-min` - `thread list` @@ -152,10 +152,10 @@ Tra cứu tên: - `thread reply` - Kênh: Discord - - Bắt buộc: `--target` (ID luồng), `--message` + - Bắt buộc: `--target` (id luồng), `--message` - Tùy chọn: `--media`, `--reply-to` -### Biểu tượng cảm xúc +### Emoji - `emoji list` - Discord: `--guild-id` @@ -194,12 +194,12 @@ Tra cứu tên: ### Kiểm duyệt (Discord) -- `timeout`: `--guild-id`, `--user-id` (tùy chọn `--duration-min` hoặc `--until`; bỏ qua cả hai để xóa thời gian chờ) +- `timeout`: `--guild-id`, `--user-id` (tùy chọn `--duration-min` hoặc `--until`; bỏ qua cả hai để xóa timeout) - `kick`: `--guild-id`, `--user-id` (+ `--reason`) - `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`) - `timeout` cũng hỗ trợ `--reason` -### Phát rộng +### Broadcast - `broadcast` - Kênh: bất kỳ kênh đã cấu hình nào; dùng `--channel all` để nhắm tới tất cả nhà cung cấp @@ -208,14 +208,14 @@ Tra cứu tên: ## Ví dụ -Gửi một trả lời Discord: +Gửi một phản hồi Discord: ``` openclaw message send --channel discord \ --target channel:123 --message "hi" --reply-to 456 ``` -Gửi tin nhắn có các nút ngữ nghĩa: +Gửi tin nhắn với các nút ngữ nghĩa: ``` openclaw message send --channel discord \ @@ -223,9 +223,9 @@ openclaw message send --channel discord \ --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}' ``` -Lõi kết xuất cùng tải `presentation` thành thành phần Discord, khối Slack, nút nội tuyến Telegram, props Mattermost, hoặc thẻ Teams/Feishu tùy theo năng lực kênh. Xem [Trình Bày Tin Nhắn](/vi/plugins/message-presentation) để biết hợp đồng đầy đủ và quy tắc dự phòng. +Lõi kết xuất cùng payload `presentation` thành các thành phần Discord, khối Slack, nút nội tuyến Telegram, props Mattermost, hoặc thẻ Teams/Feishu tùy theo khả năng của kênh. Xem [Trình bày tin nhắn](/vi/plugins/message-presentation) để biết hợp đồng đầy đủ và quy tắc dự phòng. -Gửi tải trình bày phong phú hơn: +Gửi một payload trình bày phong phú hơn: ```bash openclaw message send --channel googlechat --target spaces/AAA... \ @@ -233,7 +233,7 @@ openclaw message send --channel googlechat --target spaces/AAA... \ --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Choose a path"},{"type":"buttons","buttons":[{"label":"Approve","value":"approve"},{"label":"Decline","value":"decline"}]}]}' ``` -Tạo bình chọn Discord: +Tạo một cuộc thăm dò Discord: ``` openclaw message poll --channel discord \ @@ -243,7 +243,7 @@ openclaw message poll --channel discord \ --poll-multi --poll-duration-hours 48 ``` -Tạo bình chọn Telegram (tự động đóng sau 2 phút): +Tạo một cuộc thăm dò Telegram (tự động đóng sau 2 phút): ``` openclaw message poll --channel telegram \ @@ -260,7 +260,7 @@ openclaw message send --channel msteams \ --target conversation:19:abc@thread.tacv2 --message "hi" ``` -Tạo bình chọn Teams: +Tạo một cuộc thăm dò Teams: ``` openclaw message poll --channel msteams \ @@ -269,14 +269,14 @@ openclaw message poll --channel msteams \ --poll-option Pizza --poll-option Sushi ``` -Thả phản ứng trong Slack: +Phản ứng trong Slack: ``` openclaw message react --channel slack \ --target C123 --message-id 456 --emoji "✅" ``` -Thả phản ứng trong nhóm Signal: +Phản ứng trong một nhóm Signal: ``` openclaw message react --channel signal \ @@ -284,14 +284,14 @@ openclaw message react --channel signal \ --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000 ``` -Gửi nút nội tuyến Telegram thông qua trình bày chung: +Gửi các nút nội tuyến Telegram qua trình bày chung: ``` openclaw message send --channel telegram --target @mychat --message "Choose:" \ --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}' ``` -Gửi thẻ Teams thông qua trình bày chung: +Gửi một thẻ Teams qua trình bày chung: ```bash openclaw message send --channel msteams \ @@ -309,4 +309,4 @@ openclaw message send --channel telegram --target @mychat \ ## Liên quan - [Tham chiếu CLI](/vi/cli) -- [Gửi Agent](/vi/tools/agent-send) +- [Agent send](/vi/tools/agent-send) diff --git a/docs/vi/cli/plugins.md b/docs/vi/cli/plugins.md index 9b9cabe0f..de7eddae6 100644 --- a/docs/vi/cli/plugins.md +++ b/docs/vi/cli/plugins.md @@ -1,27 +1,27 @@ --- read_when: - Bạn muốn cài đặt hoặc quản lý các Plugin Gateway hoặc các gói tương thích - - Bạn muốn gỡ lỗi khi tải Plugin thất bại + - Bạn muốn gỡ lỗi các lỗi tải Plugin sidebarTitle: Plugins -summary: Tham chiếu CLI cho `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) +summary: Tài liệu tham khảo CLI cho `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) title: Plugin x-i18n: - generated_at: "2026-05-04T07:03:05Z" + generated_at: "2026-05-04T09:37:04Z" model: gpt-5.5 provider: openai - source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776 + source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4 source_path: cli/plugins.md workflow: 16 --- -Quản lý Plugin Gateway, gói hook và các bundle tương thích. +Quản lý các Plugin Gateway, gói hook và bundle tương thích. - Hướng dẫn cho người dùng cuối về cài đặt, bật và khắc phục sự cố Plugin. + Hướng dẫn cho người dùng cuối về cài đặt, bật và khắc phục sự cố plugin. - - Ví dụ nhanh về cài đặt, liệt kê, cập nhật, gỡ cài đặt và phát hành. + + Ví dụ nhanh cho cài đặt, liệt kê, cập nhật, gỡ cài đặt và xuất bản. Mô hình tương thích của bundle. @@ -30,7 +30,7 @@ Quản lý Plugin Gateway, gói hook và các bundle tương thích. Các trường manifest và schema cấu hình. - Gia cố bảo mật cho các lượt cài đặt Plugin. + Tăng cường bảo mật cho các bản cài đặt plugin. @@ -62,16 +62,16 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Để điều tra quá trình cài đặt, kiểm tra, gỡ cài đặt hoặc làm mới registry bị chậm, hãy chạy -lệnh với `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace ghi thời gian từng pha -vào stderr và vẫn giữ cho đầu ra JSON có thể phân tích được. Xem [Gỡ lỗi](/vi/help/debugging#plugin-lifecycle-trace). +Để điều tra thao tác cài đặt, kiểm tra, gỡ cài đặt hoặc làm mới registry bị chậm, hãy chạy +lệnh với `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace ghi thời lượng từng pha +vào stderr và vẫn giữ đầu ra JSON có thể phân tích cú pháp. Xem [Gỡ lỗi](/vi/help/debugging#plugin-lifecycle-trace). -Các Plugin đi kèm được phát hành cùng OpenClaw. Một số được bật theo mặc định (ví dụ các provider mô hình đi kèm, provider giọng nói đi kèm và Plugin trình duyệt đi kèm); những Plugin khác yêu cầu `plugins enable`. +Plugin đi kèm được phân phối cùng OpenClaw. Một số được bật theo mặc định (ví dụ: nhà cung cấp mô hình đi kèm, nhà cung cấp giọng nói đi kèm và plugin trình duyệt đi kèm); các plugin khác yêu cầu `plugins enable`. -Plugin OpenClaw native phải phát hành `openclaw.plugin.json` cùng JSON Schema nội tuyến (`configSchema`, kể cả khi rỗng). Các bundle tương thích dùng manifest bundle riêng của chúng. +Plugin OpenClaw gốc phải phân phối `openclaw.plugin.json` với JSON Schema nội tuyến (`configSchema`, ngay cả khi rỗng). Các bundle tương thích dùng manifest bundle riêng của chúng. -`plugins list` hiển thị `Format: openclaw` hoặc `Format: bundle`. Đầu ra danh sách/thông tin chi tiết cũng hiển thị subtype của bundle (`codex`, `claude` hoặc `cursor`) cùng các capability bundle được phát hiện. +`plugins list` hiển thị `Format: openclaw` hoặc `Format: bundle`. Đầu ra list/info dạng verbose cũng hiển thị subtype của bundle (`codex`, `claude` hoặc `cursor`) cùng các capability bundle được phát hiện. ### Cài đặt @@ -93,101 +93,101 @@ openclaw plugins install --marketplace https://github.com// -Tên package trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi ra mắt. Dùng `clawhub:` cho ClawHub. Hãy xem việc cài đặt Plugin như chạy mã. Ưu tiên các phiên bản được pin. +Tên package trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi khi ra mắt. Dùng `clawhub:` cho ClawHub. Hãy coi việc cài đặt plugin như chạy mã. Ưu tiên các phiên bản đã ghim. -`plugins search` truy vấn ClawHub để tìm các package Plugin có thể cài đặt và in ra -tên package sẵn sàng để cài đặt. Lệnh này tìm kiếm các package code-plugin và bundle-plugin, -không phải Skills. Dùng `openclaw skills search` cho ClawHub Skills. +`plugins search` truy vấn ClawHub để tìm các package plugin có thể cài đặt và in ra +tên package sẵn sàng cài đặt. Lệnh này tìm kiếm package code-plugin và bundle-plugin, +không phải Skills. Dùng `openclaw skills search` cho Skills trên ClawHub. -ClawHub là bề mặt phân phối và khám phá chính cho hầu hết Plugin. Npm -vẫn là đường dự phòng được hỗ trợ và là đường cài đặt trực tiếp. Các package Plugin -`@openclaw/*` do OpenClaw sở hữu đã được phát hành lại trên npm; xem danh sách hiện tại +ClawHub là bề mặt phân phối và khám phá chính cho hầu hết plugin. Npm +vẫn là đường dẫn dự phòng và cài đặt trực tiếp được hỗ trợ. Các package plugin +`@openclaw/*` do OpenClaw sở hữu đã được xuất bản lại trên npm; xem danh sách hiện tại trên [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) hoặc -[kho Plugin](/vi/plugins/plugin-inventory). Các lượt cài đặt ổn định dùng `latest`. -Các lượt cài đặt và cập nhật kênh beta ưu tiên dist-tag `beta` của npm khi tag đó -có sẵn, rồi mới quay về `latest`. +[kho plugin](/vi/plugins/plugin-inventory). Bản cài đặt ổn định dùng `latest`. +Bản cài đặt và cập nhật kênh beta ưu tiên dist-tag `beta` của npm khi tag đó +có sẵn, rồi quay về `latest`. - - Nếu phần `plugins` của bạn được hỗ trợ bởi một `$include` dạng một tệp, `plugins install/update/enable/disable/uninstall` sẽ ghi xuyên qua tệp được include đó và giữ nguyên `openclaw.json`. Include gốc, mảng include và include có override cùng cấp sẽ fail closed thay vì làm phẳng. Xem [Include cấu hình](/vi/gateway/configuration) để biết các dạng được hỗ trợ. + + Nếu phần `plugins` của bạn được hỗ trợ bởi một `$include` một tệp, `plugins install/update/enable/disable/uninstall` sẽ ghi xuyên tới tệp được include đó và giữ nguyên `openclaw.json`. Include gốc, mảng include và include có override cùng cấp sẽ fail closed thay vì làm phẳng. Xem [Config include](/vi/gateway/configuration) để biết các dạng được hỗ trợ. - Nếu cấu hình không hợp lệ trong lúc cài đặt, `plugins install` thường fail closed và yêu cầu bạn chạy `openclaw doctor --fix` trước. Trong quá trình khởi động Gateway và hot reload, cấu hình Plugin không hợp lệ fail closed như mọi cấu hình không hợp lệ khác; `openclaw doctor --fix` có thể cách ly mục Plugin không hợp lệ. Ngoại lệ duy nhất được ghi tài liệu tại thời điểm cài đặt là đường phục hồi hẹp cho Plugin đi kèm đối với các Plugin chủ động chọn `openclaw.install.allowInvalidConfigRecovery`. + Nếu cấu hình không hợp lệ trong khi cài đặt, `plugins install` thường fail closed và yêu cầu bạn chạy `openclaw doctor --fix` trước. Trong quá trình khởi động Gateway và hot reload, cấu hình plugin không hợp lệ fail closed như mọi cấu hình không hợp lệ khác; `openclaw doctor --fix` có thể cách ly mục plugin không hợp lệ. Ngoại lệ duy nhất được ghi nhận ở thời điểm cài đặt là đường dẫn phục hồi hẹp cho plugin đi kèm chủ động chọn tham gia `openclaw.install.allowInvalidConfigRecovery`. - `--force` tái sử dụng đích cài đặt hiện có và ghi đè một Plugin hoặc gói hook đã được cài đặt ngay tại chỗ. Dùng tùy chọn này khi bạn cố ý cài đặt lại cùng một id từ đường dẫn cục bộ, archive, package ClawHub hoặc artifact npm mới. Với các bản nâng cấp thường lệ của một Plugin npm đã được theo dõi, ưu tiên `openclaw plugins update `. + `--force` tái sử dụng mục tiêu cài đặt hiện có và ghi đè trực tiếp một plugin hoặc gói hook đã được cài đặt. Dùng tùy chọn này khi bạn chủ ý cài đặt lại cùng một id từ đường dẫn cục bộ, archive, package ClawHub hoặc artifact npm mới. Với nâng cấp thường lệ cho một plugin npm đã được theo dõi, hãy ưu tiên `openclaw plugins update `. - Nếu bạn chạy `plugins install` cho một id Plugin đã được cài đặt, OpenClaw sẽ dừng lại và chỉ bạn tới `plugins update ` cho bản nâng cấp thông thường, hoặc tới `plugins install --force` khi bạn thật sự muốn ghi đè cài đặt hiện tại từ một nguồn khác. + Nếu bạn chạy `plugins install` cho một id plugin đã được cài đặt, OpenClaw sẽ dừng và chỉ bạn tới `plugins update ` để nâng cấp thông thường, hoặc tới `plugins install --force` khi bạn thực sự muốn ghi đè bản cài đặt hiện tại từ một nguồn khác. - `--pin` chỉ áp dụng cho lượt cài đặt npm. Tùy chọn này không được hỗ trợ với cài đặt `git:`; hãy dùng git ref rõ ràng như `git:github.com/acme/plugin@v1.2.3` khi bạn muốn một nguồn được pin. Tùy chọn này không được hỗ trợ với `--marketplace`, vì cài đặt marketplace lưu metadata nguồn marketplace thay vì spec npm. + `--pin` chỉ áp dụng cho cài đặt npm. Tùy chọn này không được hỗ trợ với cài đặt `git:`; hãy dùng git ref rõ ràng như `git:github.com/acme/plugin@v1.2.3` khi bạn muốn một nguồn đã ghim. Tùy chọn này không được hỗ trợ với `--marketplace`, vì cài đặt marketplace lưu metadata nguồn marketplace thay vì spec npm. - `--dangerously-force-unsafe-install` là tùy chọn khẩn cấp cho các false positive trong bộ quét mã nguy hiểm tích hợp. Nó cho phép quá trình cài đặt tiếp tục ngay cả khi bộ quét tích hợp báo cáo phát hiện `critical`, nhưng **không** bỏ qua các chặn chính sách hook `before_install` của Plugin và **không** bỏ qua lỗi quét. + `--dangerously-force-unsafe-install` là tùy chọn khẩn cấp cho lỗi dương tính giả trong trình quét mã nguy hiểm tích hợp. Tùy chọn này cho phép tiếp tục cài đặt ngay cả khi trình quét tích hợp báo cáo phát hiện `critical`, nhưng **không** bỏ qua các chặn chính sách hook `before_install` của plugin và **không** bỏ qua lỗi quét. - Cờ CLI này áp dụng cho luồng cài đặt/cập nhật Plugin. Các lượt cài đặt dependency của skill do Gateway hỗ trợ dùng override yêu cầu tương ứng `dangerouslyForceUnsafeInstall`, trong khi `openclaw skills install` vẫn là một luồng tải xuống/cài đặt ClawHub skill riêng. + Cờ CLI này áp dụng cho luồng cài đặt/cập nhật plugin. Các bản cài đặt phụ thuộc skill do Gateway hỗ trợ dùng override yêu cầu tương ứng `dangerouslyForceUnsafeInstall`, trong khi `openclaw skills install` vẫn là luồng tải xuống/cài đặt Skills ClawHub riêng. - Nếu một Plugin bạn phát hành trên ClawHub bị chặn bởi lần quét registry, hãy dùng các bước dành cho nhà phát hành trong [ClawHub](/vi/tools/clawhub). + Nếu một plugin bạn đã xuất bản trên ClawHub bị chặn bởi quét registry, hãy dùng các bước dành cho nhà xuất bản trong [ClawHub](/vi/tools/clawhub). - `plugins install` cũng là bề mặt cài đặt cho các gói hook expose `openclaw.hooks` trong `package.json`. Dùng `openclaw hooks` để xem hook có lọc và bật từng hook, không phải để cài đặt package. + `plugins install` cũng là bề mặt cài đặt cho các gói hook expose `openclaw.hooks` trong `package.json`. Dùng `openclaw hooks` để xem hook đã lọc và bật từng hook, không phải để cài đặt package. - Spec npm là **chỉ registry** (tên package + **phiên bản chính xác** tùy chọn hoặc **dist-tag** tùy chọn). Spec Git/URL/file và khoảng semver bị từ chối. Cài đặt dependency chạy ở phạm vi cục bộ của project với `--ignore-scripts` để an toàn, kể cả khi shell của bạn có thiết lập cài đặt npm toàn cục. + Spec npm là **chỉ registry** (tên package + **phiên bản chính xác** hoặc **dist-tag** tùy chọn). Spec Git/URL/file và dải semver bị từ chối. Cài đặt phụ thuộc chạy cục bộ theo dự án với `--ignore-scripts` để an toàn, ngay cả khi shell của bạn có thiết lập cài đặt npm toàn cục. - Dùng `npm:` khi bạn muốn làm rõ việc phân giải npm. Spec package trần cũng cài đặt trực tiếp từ npm trong giai đoạn chuyển đổi ra mắt. + Dùng `npm:` khi bạn muốn làm rõ quá trình phân giải npm. Spec package trần cũng cài đặt trực tiếp từ npm trong giai đoạn chuyển đổi khi ra mắt. - Spec trần và `@latest` ở lại nhánh ổn định. Các phiên bản sửa lỗi có đóng dấu ngày của OpenClaw như `2026.5.3-1` là bản phát hành ổn định cho kiểm tra này. Nếu npm phân giải một trong hai loại đó thành prerelease, OpenClaw sẽ dừng và yêu cầu bạn chủ động opt in bằng tag prerelease như `@beta`/`@rc` hoặc một phiên bản prerelease chính xác như `@1.2.3-beta.4`. + Spec trần và `@latest` ở lại track ổn định. Các phiên bản sửa lỗi có dấu ngày của OpenClaw như `2026.5.3-1` là bản phát hành ổn định cho kiểm tra này. Nếu npm phân giải một trong các spec đó thành bản prerelease, OpenClaw sẽ dừng và yêu cầu bạn chọn tham gia rõ ràng bằng tag prerelease như `@beta`/`@rc` hoặc phiên bản prerelease chính xác như `@1.2.3-beta.4`. - Nếu một spec cài đặt trần khớp với id Plugin chính thức (ví dụ `diffs`), OpenClaw sẽ cài trực tiếp mục catalog. Để cài package npm có cùng tên, hãy dùng spec scoped rõ ràng (ví dụ `@scope/diffs`). + Nếu một spec cài đặt trần khớp với id plugin chính thức (ví dụ `diffs`), OpenClaw sẽ cài đặt trực tiếp mục catalog. Để cài đặt một package npm cùng tên, hãy dùng spec có scope rõ ràng (ví dụ `@scope/diffs`). - Dùng `git:` để cài đặt trực tiếp từ một kho git. Các dạng được hỗ trợ gồm `git:github.com/owner/repo`, `git:owner/repo`, URL clone đầy đủ `https://`, `ssh://`, `git://`, `file://` và `git@host:owner/repo.git`. Thêm `@` hoặc `#` để checkout một branch, tag hoặc commit trước khi cài đặt. + Dùng `git:` để cài đặt trực tiếp từ kho git. Các dạng được hỗ trợ gồm `git:github.com/owner/repo`, `git:owner/repo`, URL clone đầy đủ `https://`, `ssh://`, `git://`, `file://` và `git@host:owner/repo.git`. Thêm `@` hoặc `#` để checkout branch, tag hoặc commit trước khi cài đặt. - Cài đặt Git clone vào một thư mục tạm, checkout ref được yêu cầu nếu có, rồi dùng trình cài đặt thư mục Plugin bình thường. Điều đó có nghĩa là xác thực manifest, quét mã nguy hiểm, công việc cài đặt package-manager và bản ghi cài đặt hoạt động như cài đặt npm. Các lượt cài đặt git được ghi lại bao gồm URL/ref nguồn cùng commit đã phân giải để `openclaw plugins update` có thể phân giải lại nguồn sau này. + Cài đặt Git clone vào thư mục tạm, checkout ref được yêu cầu nếu có, rồi dùng trình cài đặt thư mục plugin thông thường. Điều đó có nghĩa là xác thực manifest, quét mã nguy hiểm, công việc cài đặt package-manager và bản ghi cài đặt hoạt động như cài đặt npm. Bản ghi cài đặt git bao gồm URL/ref nguồn cùng commit đã phân giải để `openclaw plugins update` có thể phân giải lại nguồn sau này. - Sau khi cài đặt từ git, dùng `openclaw plugins inspect --runtime --json` để xác minh các đăng ký runtime như phương thức gateway và lệnh CLI. Nếu Plugin đã đăng ký CLI root bằng `api.registerCli`, hãy thực thi lệnh đó trực tiếp qua CLI root của OpenClaw, ví dụ `openclaw demo-plugin ping`. + Sau khi cài đặt từ git, dùng `openclaw plugins inspect --runtime --json` để xác minh các đăng ký runtime như phương thức gateway và lệnh CLI. Nếu plugin đã đăng ký một CLI root với `api.registerCli`, hãy thực thi lệnh đó trực tiếp qua CLI root của OpenClaw, ví dụ `openclaw demo-plugin ping`. - Archive được hỗ trợ: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archive Plugin OpenClaw native phải chứa `openclaw.plugin.json` hợp lệ tại root Plugin đã giải nén; archive chỉ chứa `package.json` sẽ bị từ chối trước khi OpenClaw ghi bản ghi cài đặt. + Archive được hỗ trợ: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archive plugin OpenClaw gốc phải chứa `openclaw.plugin.json` hợp lệ tại root plugin đã giải nén; archive chỉ chứa `package.json` bị từ chối trước khi OpenClaw ghi bản ghi cài đặt. Cài đặt marketplace Claude cũng được hỗ trợ. -Cài đặt ClawHub dùng locator `clawhub:` rõ ràng: +Cài đặt ClawHub dùng locator rõ ràng `clawhub:`: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Spec Plugin an toàn cho npm dạng trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi ra mắt: +Spec plugin an toàn với npm dạng trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi khi ra mắt: ```bash openclaw plugins install openclaw-codex-app-server ``` -Dùng `npm:` để làm rõ phân giải chỉ npm: +Dùng `npm:` để làm rõ quá trình phân giải chỉ npm: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw kiểm tra API Plugin được quảng bá / mức tương thích gateway tối thiểu trước khi cài đặt. Khi phiên bản ClawHub đã chọn phát hành artifact ClawPack, OpenClaw tải xuống `.tgz` npm-pack có phiên bản, xác minh header digest ClawHub và digest artifact, rồi cài đặt qua đường archive bình thường. Các phiên bản ClawHub cũ hơn không có metadata ClawPack vẫn cài đặt qua đường xác minh archive package legacy. Các lượt cài đặt được ghi lại giữ metadata nguồn ClawHub, loại artifact, npm integrity, npm shasum, tên tarball và các thông tin digest ClawPack để cập nhật sau này. -Các lượt cài đặt ClawHub không có phiên bản giữ spec được ghi lại không có phiên bản để `openclaw plugins update` có thể theo các bản phát hành ClawHub mới hơn; các selector phiên bản hoặc tag rõ ràng như `clawhub:pkg@1.2.3` và `clawhub:pkg@beta` vẫn được pin vào selector đó. +OpenClaw kiểm tra khả năng tương thích plugin API / gateway tối thiểu được quảng bá trước khi cài đặt. Khi phiên bản ClawHub đã chọn xuất bản artifact ClawPack, OpenClaw tải xuống npm-pack `.tgz` có phiên bản, xác minh header digest ClawHub và digest artifact, rồi cài đặt qua đường dẫn archive thông thường. Các phiên bản ClawHub cũ hơn không có metadata ClawPack vẫn cài đặt qua đường dẫn xác minh archive package cũ. Bản ghi cài đặt giữ metadata nguồn ClawHub, loại artifact, integrity npm, shasum npm, tên tarball và thông tin digest ClawPack để dùng cho các lần cập nhật sau. +Cài đặt ClawHub không có phiên bản giữ spec đã ghi không có phiên bản để `openclaw plugins update` có thể theo các bản phát hành ClawHub mới hơn; bộ chọn phiên bản hoặc tag rõ ràng như `clawhub:pkg@1.2.3` và `clawhub:pkg@beta` vẫn được ghim vào bộ chọn đó. -#### Viết tắt marketplace +#### Cú pháp rút gọn marketplace -Dùng viết tắt `plugin@marketplace` khi tên marketplace tồn tại trong cache registry cục bộ của Claude tại `~/.claude/plugins/known_marketplaces.json`: +Dùng cú pháp rút gọn `plugin@marketplace` khi tên marketplace tồn tại trong cache registry cục bộ của Claude tại `~/.claude/plugins/known_marketplaces.json`: ```bash openclaw plugins marketplace list @@ -204,28 +204,28 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - tên chợ ứng dụng đã biết của Claude từ `~/.claude/plugins/known_marketplaces.json` - - gốc chợ ứng dụng cục bộ hoặc đường dẫn `marketplace.json` - - dạng viết tắt kho GitHub như `owner/repo` + + - tên marketplace đã biết của Claude từ `~/.claude/plugins/known_marketplaces.json` + - gốc marketplace cục bộ hoặc đường dẫn `marketplace.json` + - cách viết tắt kho GitHub như `owner/repo` - URL kho GitHub như `https://github.com/owner/repo` - URL git - - Đối với các chợ ứng dụng từ xa được tải từ GitHub hoặc git, các mục Plugin phải nằm bên trong kho chợ ứng dụng đã được sao chép. OpenClaw chấp nhận các nguồn đường dẫn tương đối từ kho đó và từ chối HTTP(S), đường dẫn tuyệt đối, git, GitHub, và các nguồn Plugin không phải đường dẫn khác từ manifest từ xa. + + Với marketplace từ xa được tải từ GitHub hoặc git, các mục plugin phải nằm bên trong kho marketplace đã clone. OpenClaw chấp nhận nguồn đường dẫn tương đối từ kho đó và từ chối HTTP(S), đường dẫn tuyệt đối, git, GitHub, và các nguồn plugin không phải đường dẫn khác từ manifest từ xa. -Đối với đường dẫn cục bộ và tệp lưu trữ, OpenClaw tự động phát hiện: +Với đường dẫn cục bộ và tệp lưu trữ, OpenClaw tự động phát hiện: -- Plugin OpenClaw gốc (`openclaw.plugin.json`) +- plugin OpenClaw gốc (`openclaw.plugin.json`) - gói tương thích với Codex (`.codex-plugin/plugin.json`) - gói tương thích với Claude (`.claude-plugin/plugin.json` hoặc bố cục thành phần Claude mặc định) - gói tương thích với Cursor (`.cursor-plugin/plugin.json`) -Các gói tương thích được cài vào gốc Plugin thông thường và tham gia cùng luồng liệt kê/thông tin/bật/tắt. Hiện tại, Skills trong gói, command-skills của Claude, giá trị mặc định `settings.json` của Claude, giá trị mặc định `.lsp.json` / `lspServers` khai báo trong manifest của Claude, command-skills của Cursor, và các thư mục hook Codex tương thích được hỗ trợ; các khả năng gói khác được phát hiện sẽ hiển thị trong chẩn đoán/thông tin nhưng chưa được nối vào thực thi thời gian chạy. +Các gói tương thích được cài đặt vào gốc plugin thông thường và tham gia cùng luồng liệt kê/thông tin/bật/tắt. Hiện tại, bundle skills, command-skills của Claude, giá trị mặc định `settings.json` của Claude, giá trị mặc định `.lsp.json` của Claude / `lspServers` được khai báo trong manifest, command-skills của Cursor, và các thư mục hook Codex tương thích được hỗ trợ; các khả năng gói khác được phát hiện sẽ hiển thị trong chẩn đoán/thông tin nhưng chưa được nối vào thực thi runtime. ### Liệt kê @@ -241,59 +241,48 @@ openclaw plugins search --json ``` - Chỉ hiển thị các Plugin đã bật. + Chỉ hiển thị các plugin đã bật. - Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng Plugin với siêu dữ liệu nguồn/xuất xứ/phiên bản/kích hoạt. + Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng plugin với siêu dữ liệu nguồn/xuất xứ/phiên bản/kích hoạt. - Kiểm kê đọc được bằng máy cùng với chẩn đoán registry và trạng thái cài đặt phụ thuộc gói. + Bản kiểm kê máy đọc được cùng chẩn đoán registry và trạng thái cài đặt phụ thuộc của package. -`plugins list` đọc registry Plugin cục bộ đã lưu trước, với phương án dự phòng dẫn xuất chỉ từ manifest khi registry bị thiếu hoặc không hợp lệ. Lệnh này hữu ích để kiểm tra liệu một Plugin đã được cài đặt, đã bật, và hiển thị với kế hoạch khởi động lạnh hay chưa, nhưng không phải là phép dò thời gian chạy trực tiếp của một tiến trình Gateway đang chạy. Sau khi thay đổi mã Plugin, trạng thái bật, chính sách hook, hoặc `plugins.load.paths`, hãy khởi động lại Gateway phục vụ kênh trước khi kỳ vọng mã `register(api)` mới hoặc hook chạy. Với triển khai từ xa/container, hãy xác minh rằng bạn đang khởi động lại đúng tiến trình con `openclaw gateway run`, không chỉ một tiến trình bao bọc. +`plugins list` đọc registry plugin cục bộ đã lưu trước, với phương án dự phòng suy ra chỉ từ manifest khi registry bị thiếu hoặc không hợp lệ. Lệnh này hữu ích để kiểm tra liệu một plugin đã được cài đặt, bật và hiển thị cho việc lập kế hoạch khởi động lạnh hay chưa, nhưng không phải là phép dò runtime trực tiếp của một tiến trình Gateway đang chạy. Sau khi thay đổi mã plugin, trạng thái bật, chính sách hook, hoặc `plugins.load.paths`, hãy khởi động lại Gateway phục vụ kênh trước khi kỳ vọng mã `register(api)` mới hoặc hook chạy. Với triển khai từ xa/container, hãy xác minh bạn đang khởi động lại đúng tiến trình con `openclaw gateway run`, không chỉ một tiến trình wrapper. -`plugins list --json` bao gồm `dependencyStatus` của từng Plugin từ `package.json` -`dependencies` và `optionalDependencies`. OpenClaw kiểm tra liệu các tên gói đó -có hiện diện dọc theo đường dẫn tra cứu `node_modules` Node thông thường của Plugin hay không; OpenClaw -không nhập mã thời gian chạy của Plugin, không chạy trình quản lý gói, và không sửa chữa -các phụ thuộc bị thiếu. +`plugins list --json` bao gồm `dependencyStatus` của từng plugin từ `dependencies` và `optionalDependencies` trong `package.json`. OpenClaw kiểm tra liệu các tên package đó có hiện diện dọc theo đường dẫn tra cứu `node_modules` thông thường của Node cho plugin hay không; nó không import mã runtime của plugin, chạy trình quản lý package, hoặc sửa các phụ thuộc bị thiếu. -`plugins search` là phép tra cứu danh mục ClawHub từ xa. Lệnh này không kiểm tra trạng thái -cục bộ, không thay đổi cấu hình, không cài gói, và không tải mã thời gian chạy của Plugin. Kết quả -tìm kiếm bao gồm tên gói ClawHub, họ, kênh, phiên bản, tóm tắt, và -gợi ý cài đặt như `openclaw plugins install clawhub:`. +`plugins search` là tra cứu danh mục ClawHub từ xa. Nó không kiểm tra trạng thái cục bộ, thay đổi cấu hình, cài đặt package, hoặc tải mã runtime của plugin. Kết quả tìm kiếm bao gồm tên package ClawHub, họ, kênh, phiên bản, tóm tắt, và gợi ý cài đặt như `openclaw plugins install clawhub:`. -Đối với công việc trên Plugin đi kèm bên trong ảnh Docker đã đóng gói, hãy bind-mount thư mục -nguồn Plugin đè lên đường dẫn nguồn đã đóng gói tương ứng, chẳng hạn -`/app/extensions/synology-chat`. OpenClaw sẽ phát hiện lớp phủ nguồn đã mount đó -trước `/app/dist/extensions/synology-chat`; một thư mục nguồn được sao chép đơn thuần -vẫn bất hoạt, nên các bản cài đặt đã đóng gói thông thường vẫn dùng dist đã biên dịch. +Với công việc plugin đi kèm bên trong ảnh Docker đã đóng gói, hãy bind-mount thư mục nguồn plugin lên đường dẫn nguồn đã đóng gói tương ứng, chẳng hạn `/app/extensions/synology-chat`. OpenClaw sẽ phát hiện lớp phủ nguồn đã mount đó trước `/app/dist/extensions/synology-chat`; một thư mục nguồn được sao chép thông thường sẽ không hoạt động để các bản cài đặt đóng gói bình thường vẫn dùng dist đã biên dịch. -Để gỡ lỗi hook thời gian chạy: +Để gỡ lỗi hook runtime: -- `openclaw plugins inspect --runtime --json` hiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra đã tải module. Kiểm tra thời gian chạy không bao giờ cài phụ thuộc; dùng `openclaw doctor --fix` để dọn trạng thái phụ thuộc cũ hoặc cài các Plugin tải xuống đã cấu hình nhưng còn thiếu. -- `openclaw gateway status --deep --require-rpc` xác nhận Gateway có thể truy cập, gợi ý dịch vụ/tiến trình, đường dẫn cấu hình, và tình trạng RPC. -- Các hook hội thoại không đi kèm (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) yêu cầu `plugins.entries..hooks.allowConversationAccess=true`. +- `openclaw plugins inspect --runtime --json` hiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra đã tải module. Kiểm tra runtime không bao giờ cài đặt phụ thuộc; dùng `openclaw doctor --fix` để dọn trạng thái phụ thuộc legacy hoặc cài các plugin tải xuống đã cấu hình bị thiếu. +- `openclaw gateway status --deep --require-rpc` xác nhận Gateway có thể truy cập, gợi ý service/tiến trình, đường dẫn cấu hình, và sức khỏe RPC. +- Hook hội thoại không đi kèm (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) yêu cầu `plugins.entries..hooks.allowConversationAccess=true`. -Dùng `--link` để tránh sao chép một thư mục cục bộ (thêm vào `plugins.load.paths`): +Dùng `--link` để tránh sao chép thư mục cục bộ (thêm vào `plugins.load.paths`): ```bash openclaw plugins install -l ./my-plugin ``` -`--force` không được hỗ trợ cùng với `--link` vì bản cài liên kết dùng lại đường dẫn nguồn thay vì sao chép đè lên một đích cài đặt được quản lý. +`--force` không được hỗ trợ cùng `--link` vì cài đặt liên kết tái sử dụng đường dẫn nguồn thay vì sao chép đè lên mục tiêu cài đặt do hệ thống quản lý. -Dùng `--pin` trên bản cài npm để lưu đặc tả chính xác đã phân giải (`name@version`) trong chỉ mục Plugin được quản lý, đồng thời giữ hành vi mặc định không ghim. +Dùng `--pin` trên các bản cài đặt npm để lưu spec chính xác đã phân giải (`name@version`) trong chỉ mục plugin được quản lý, đồng thời giữ hành vi mặc định là không ghim. ### Chỉ mục Plugin -Siêu dữ liệu cài đặt Plugin là trạng thái do máy quản lý, không phải cấu hình người dùng. Các lượt cài đặt và cập nhật ghi dữ liệu này vào `plugins/installs.json` trong thư mục trạng thái OpenClaw đang hoạt động. Bản đồ `installRecords` cấp cao nhất của tệp này là nguồn bền vững cho siêu dữ liệu cài đặt, bao gồm cả bản ghi cho các manifest Plugin bị hỏng hoặc bị thiếu. Mảng `plugins` là bộ nhớ đệm registry lạnh dẫn xuất từ manifest. Tệp này bao gồm cảnh báo không chỉnh sửa và được dùng bởi `openclaw plugins update`, gỡ cài đặt, chẩn đoán, và registry Plugin lạnh. +Siêu dữ liệu cài đặt Plugin là trạng thái do máy quản lý, không phải cấu hình người dùng. Các lần cài đặt và cập nhật ghi nó vào `plugins/installs.json` trong thư mục trạng thái OpenClaw đang hoạt động. Bản đồ `installRecords` cấp cao nhất là nguồn bền vững của siêu dữ liệu cài đặt, bao gồm các bản ghi cho manifest plugin bị hỏng hoặc bị thiếu. Mảng `plugins` là bộ nhớ đệm registry lạnh suy ra từ manifest. Tệp này bao gồm cảnh báo không chỉnh sửa và được dùng bởi `openclaw plugins update`, gỡ cài đặt, chẩn đoán, và registry plugin lạnh. -Khi OpenClaw thấy các bản ghi `plugins.installs` cũ được phân phối trong cấu hình, OpenClaw chuyển chúng vào chỉ mục Plugin và xóa khóa cấu hình; nếu một trong hai thao tác ghi thất bại, các bản ghi cấu hình được giữ lại để siêu dữ liệu cài đặt không bị mất. +Khi OpenClaw thấy các bản ghi legacy `plugins.installs` được phát hành trong cấu hình, nó chuyển chúng vào chỉ mục plugin và xóa khóa cấu hình; nếu một trong hai thao tác ghi thất bại, các bản ghi cấu hình được giữ lại để siêu dữ liệu cài đặt không bị mất. ### Gỡ cài đặt @@ -303,10 +292,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` xóa các bản ghi Plugin khỏi `plugins.entries`, chỉ mục Plugin đã lưu, các mục danh sách cho phép/từ chối Plugin, và các mục `plugins.load.paths` đã liên kết khi áp dụng. Trừ khi đặt `--keep-files`, gỡ cài đặt cũng xóa thư mục cài đặt được quản lý đã theo dõi khi thư mục đó nằm bên trong gốc tiện ích mở rộng Plugin của OpenClaw. Với các Plugin Active Memory, slot bộ nhớ đặt lại về `memory-core`. +`uninstall` xóa bản ghi plugin khỏi `plugins.entries`, chỉ mục plugin đã lưu, các mục danh sách cho phép/từ chối plugin, và các mục `plugins.load.paths` đã liên kết khi áp dụng. Trừ khi đặt `--keep-files`, gỡ cài đặt cũng xóa thư mục cài đặt do hệ thống quản lý đã theo dõi khi nó nằm bên trong gốc tiện ích mở rộng plugin của OpenClaw. Với plugin active memory, slot bộ nhớ đặt lại thành `memory-core`. -`--keep-config` được hỗ trợ như bí danh đã lỗi thời cho `--keep-files`. +`--keep-config` được hỗ trợ như alias đã lỗi thời cho `--keep-files`. ### Cập nhật @@ -319,29 +308,29 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Các bản cập nhật áp dụng cho những bản cài Plugin đã theo dõi trong chỉ mục Plugin được quản lý và những bản cài hook-pack đã theo dõi trong `hooks.internal.installs`. +Cập nhật áp dụng cho các bản cài đặt plugin được theo dõi trong chỉ mục plugin được quản lý và các bản cài đặt hook-pack được theo dõi trong `hooks.internal.installs`. - - Khi bạn truyền một id Plugin, OpenClaw dùng lại đặc tả cài đặt đã ghi cho Plugin đó. Điều này nghĩa là các dist-tag đã lưu trước đó như `@beta` và các phiên bản ghim chính xác tiếp tục được dùng trong những lần chạy `update ` về sau. + + Khi bạn truyền một plugin id, OpenClaw tái sử dụng spec cài đặt đã ghi cho plugin đó. Điều đó có nghĩa là các dist-tag đã lưu trước đó như `@beta` và các phiên bản ghim chính xác tiếp tục được dùng trong những lần chạy `update ` sau này. - Đối với bản cài npm, bạn cũng có thể truyền một đặc tả gói npm rõ ràng với dist-tag hoặc phiên bản chính xác. OpenClaw phân giải tên gói đó ngược về bản ghi Plugin đã theo dõi, cập nhật Plugin đã cài đó, và ghi lại đặc tả npm mới cho các bản cập nhật dựa trên id trong tương lai. + Với bản cài đặt npm, bạn cũng có thể truyền một spec package npm rõ ràng với dist-tag hoặc phiên bản chính xác. OpenClaw phân giải tên package đó trở lại bản ghi plugin được theo dõi, cập nhật plugin đã cài đó, và ghi lại spec npm mới cho các lần cập nhật dựa trên id trong tương lai. - Truyền tên gói npm mà không có phiên bản hoặc thẻ cũng phân giải ngược về bản ghi Plugin đã theo dõi. Dùng cách này khi một Plugin đã được ghim vào một phiên bản chính xác và bạn muốn chuyển nó trở lại dòng phát hành mặc định của registry. + Truyền tên package npm không kèm phiên bản hoặc tag cũng phân giải trở lại bản ghi plugin được theo dõi. Dùng cách này khi một plugin đã được ghim vào phiên bản chính xác và bạn muốn chuyển nó trở lại dòng phát hành mặc định của registry. - - `openclaw plugins update` dùng lại đặc tả Plugin đã theo dõi trừ khi bạn truyền một đặc tả mới. `openclaw update` còn biết kênh cập nhật OpenClaw đang hoạt động: trên kênh beta, các bản ghi Plugin npm dòng mặc định và ClawHub thử `@beta` trước, rồi quay lại đặc tả mặc định/mới nhất đã ghi nếu không có bản phát hành beta của Plugin. Các phiên bản chính xác và thẻ rõ ràng vẫn được ghim vào bộ chọn đó. + + `openclaw plugins update` tái sử dụng spec plugin được theo dõi trừ khi bạn truyền spec mới. `openclaw update` còn biết kênh cập nhật OpenClaw đang hoạt động: trên kênh beta, các bản ghi plugin npm và ClawHub thuộc dòng mặc định sẽ thử `@beta` trước, rồi quay lại spec mặc định/latest đã ghi nếu không có bản phát hành beta của plugin. Phiên bản chính xác và tag rõ ràng vẫn được ghim vào bộ chọn đó. - - Trước một bản cập nhật npm trực tiếp, OpenClaw kiểm tra phiên bản gói đã cài so với siêu dữ liệu registry npm. Nếu phiên bản đã cài và danh tính artifact đã ghi đã khớp với đích đã phân giải, bản cập nhật được bỏ qua mà không tải xuống, cài đặt lại, hoặc ghi lại `openclaw.json`. + + Trước một bản cập nhật npm trực tiếp, OpenClaw kiểm tra phiên bản package đã cài so với siêu dữ liệu npm registry. Nếu phiên bản đã cài và danh tính artifact đã ghi đã khớp với mục tiêu đã phân giải, bản cập nhật được bỏ qua mà không tải xuống, cài đặt lại, hoặc ghi lại `openclaw.json`. - Khi có hash toàn vẹn đã lưu và hash artifact đã lấy thay đổi, OpenClaw xem đó là lệch artifact npm. Lệnh tương tác `openclaw plugins update` in ra hash kỳ vọng và hash thực tế rồi yêu cầu xác nhận trước khi tiếp tục. Các trình trợ giúp cập nhật không tương tác sẽ thất bại đóng trừ khi bên gọi cung cấp một chính sách tiếp tục rõ ràng. + Khi có hash integrity đã lưu và hash artifact đã fetch thay đổi, OpenClaw coi đó là drift artifact npm. Lệnh tương tác `openclaw plugins update` in hash kỳ vọng và hash thực tế, rồi hỏi xác nhận trước khi tiếp tục. Các helper cập nhật không tương tác sẽ fail closed trừ khi bên gọi cung cấp chính sách tiếp tục rõ ràng. - - `--dangerously-force-unsafe-install` cũng có sẵn trên `plugins update` dưới dạng ghi đè phá kính cho các dương tính giả từ quét mã nguy hiểm tích hợp sẵn trong quá trình cập nhật Plugin. Nó vẫn không bỏ qua các chặn chính sách `before_install` của Plugin hoặc chặn do lỗi quét, và chỉ áp dụng cho cập nhật Plugin, không áp dụng cho cập nhật hook-pack. + + `--dangerously-force-unsafe-install` cũng có sẵn trên `plugins update` như một override khẩn cấp cho các kết quả dương tính giả của quét dangerous-code tích hợp trong khi cập nhật plugin. Nó vẫn không bỏ qua các chặn chính sách `before_install` của plugin hoặc chặn do lỗi quét, và chỉ áp dụng cho cập nhật plugin, không áp dụng cho cập nhật hook-pack. @@ -353,34 +342,34 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Kiểm tra hiển thị danh tính, trạng thái tải, nguồn, khả năng trong manifest, cờ chính sách, chẩn đoán, siêu dữ liệu cài đặt, khả năng gói, và mọi hỗ trợ máy chủ MCP hoặc LSP được phát hiện mà mặc định không nhập thời gian chạy Plugin. Thêm `--runtime` để tải module Plugin và bao gồm các hook, công cụ, lệnh, dịch vụ, phương thức Gateway, và tuyến HTTP đã đăng ký. Kiểm tra thời gian chạy báo cáo trực tiếp các phụ thuộc Plugin bị thiếu; cài đặt và sửa chữa vẫn nằm trong `openclaw plugins install`, `openclaw plugins update`, và `openclaw doctor --fix`. +Inspect hiển thị danh tính, trạng thái tải, nguồn, khả năng manifest, cờ chính sách, chẩn đoán, siêu dữ liệu cài đặt, khả năng gói, và mọi hỗ trợ máy chủ MCP hoặc LSP được phát hiện mà mặc định không import runtime plugin. Thêm `--runtime` để tải module plugin và bao gồm các hook, công cụ, lệnh, service, phương thức gateway, và tuyến HTTP đã đăng ký. Kiểm tra runtime báo cáo trực tiếp các phụ thuộc plugin bị thiếu; việc cài đặt và sửa chữa nằm trong `openclaw plugins install`, `openclaw plugins update`, và `openclaw doctor --fix`. -Các lệnh CLI do Plugin sở hữu được cài dưới dạng các nhóm lệnh gốc `openclaw`. Sau khi `inspect --runtime` hiển thị một lệnh trong `cliCommands`, hãy chạy lệnh đó dưới dạng `openclaw ...`; ví dụ, một Plugin đăng ký `demo-git` có thể được xác minh bằng `openclaw demo-git ping`. +Các lệnh CLI do plugin sở hữu được cài đặt dưới dạng nhóm lệnh `openclaw` gốc. Sau khi `inspect --runtime` hiển thị một lệnh dưới `cliCommands`, hãy chạy nó dưới dạng `openclaw ...`; ví dụ một plugin đăng ký `demo-git` có thể được xác minh bằng `openclaw demo-git ping`. -Mỗi Plugin được phân loại theo những gì nó thực sự đăng ký tại thời gian chạy: +Mỗi plugin được phân loại theo những gì nó thực sự đăng ký tại runtime: -- **plain-capability** — một loại khả năng (ví dụ: Plugin chỉ dành cho provider) +- **plain-capability** — một loại khả năng (ví dụ: plugin chỉ dành cho provider) - **hybrid-capability** — nhiều loại khả năng (ví dụ: văn bản + giọng nói + hình ảnh) - **hook-only** — chỉ hook, không có khả năng hoặc bề mặt -- **non-capability** — công cụ/lệnh/dịch vụ nhưng không có khả năng +- **non-capability** — công cụ/lệnh/service nhưng không có khả năng -Xem [Hình dạng Plugin](/vi/plugins/architecture#plugin-shapes) để biết thêm về mô hình khả năng. +Xem [Kiểu Plugin](/vi/plugins/architecture#plugin-shapes) để biết thêm về mô hình khả năng. -Cờ `--json` xuất báo cáo đọc được bằng máy phù hợp cho scripting và kiểm toán. `inspect --all` kết xuất một bảng toàn đội với hình dạng, loại khả năng, thông báo tương thích, khả năng gói, và các cột tóm tắt hook. `info` là bí danh của `inspect`. +Cờ `--json` xuất một báo cáo máy đọc được phù hợp cho script và kiểm toán. `inspect --all` hiển thị bảng toàn bộ đội hình với các cột kiểu, loại khả năng, thông báo tương thích, khả năng gói, và tóm tắt hook. `info` là alias cho `inspect`. -### Chẩn đoán +### Doctor ```bash openclaw plugins doctor ``` -`doctor` báo cáo lỗi tải Plugin, chẩn đoán manifest/phát hiện, và thông báo tương thích. Khi mọi thứ sạch, lệnh in `No plugin issues detected.` +`doctor` báo cáo lỗi tải plugin, chẩn đoán manifest/discovery, và thông báo tương thích. Khi mọi thứ sạch, nó in `No plugin issues detected.` -Nếu một Plugin đã cấu hình hiện diện trên đĩa nhưng bị chặn bởi các kiểm tra an toàn đường dẫn của loader, xác thực cấu hình giữ lại mục Plugin và báo cáo là `present but blocked`. Hãy sửa chẩn đoán Plugin bị chặn đứng trước đó, chẳng hạn quyền sở hữu đường dẫn hoặc quyền world-writable, thay vì xóa cấu hình `plugins.entries.` hoặc `plugins.allow`. +Nếu một plugin đã cấu hình hiện diện trên đĩa nhưng bị chặn bởi kiểm tra an toàn đường dẫn của loader, xác thực cấu hình giữ mục plugin và báo cáo nó là `present but blocked`. Hãy sửa chẩn đoán plugin bị chặn ở trước đó, chẳng hạn quyền sở hữu đường dẫn hoặc quyền ghi của mọi người, thay vì xóa cấu hình `plugins.entries.` hoặc `plugins.allow`. -Đối với lỗi dạng module như thiếu export `register`/`activate`, hãy chạy lại với `OPENCLAW_PLUGIN_LOAD_DEBUG=1` để bao gồm tóm tắt dạng export gọn trong đầu ra chẩn đoán. +Với lỗi hình dạng module như thiếu export `register`/`activate`, chạy lại với `OPENCLAW_PLUGIN_LOAD_DEBUG=1` để bao gồm tóm tắt hình dạng export gọn trong đầu ra chẩn đoán. ### Registry @@ -390,25 +379,27 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -Registry Plugin cục bộ là mô hình đọc lạnh đã lưu của OpenClaw cho danh tính Plugin đã cài, trạng thái bật, siêu dữ liệu nguồn, và quyền sở hữu đóng góp. Khởi động thông thường, tra cứu chủ sở hữu provider, phân loại thiết lập kênh, và kiểm kê Plugin có thể đọc registry này mà không cần nhập các module thời gian chạy Plugin. +Registry plugin cục bộ là mô hình đọc lạnh đã lưu của OpenClaw cho danh tính plugin đã cài, trạng thái bật, siêu dữ liệu nguồn, và quyền sở hữu đóng góp. Khởi động bình thường, tra cứu chủ sở hữu provider, phân loại thiết lập kênh, và kiểm kê plugin có thể đọc nó mà không cần import các module runtime plugin. -Dùng `plugins registry` để kiểm tra registry được lưu bền vững có tồn tại, hiện hành hay đã cũ hay không. Dùng `--refresh` để dựng lại nó từ chỉ mục Plugin được lưu bền vững, chính sách cấu hình và siêu dữ liệu manifest/package. Đây là đường dẫn sửa chữa, không phải đường dẫn kích hoạt lúc chạy. +Sử dụng `plugins registry` để kiểm tra registry đã lưu có hiện diện, hiện hành hay đã cũ. Sử dụng `--refresh` để xây dựng lại registry từ chỉ mục plugin đã lưu, chính sách cấu hình và siêu dữ liệu manifest/package. Đây là đường dẫn sửa chữa, không phải đường dẫn kích hoạt khi chạy. + +`openclaw doctor --fix` cũng sửa lỗi lệch npm được quản lý liền kề registry: nếu một package `@openclaw/*` mồ côi hoặc được khôi phục dưới gốc npm plugin được quản lý che khuất một plugin được đóng gói sẵn, doctor sẽ xóa package cũ đó và xây dựng lại registry để quá trình khởi động xác thực theo manifest được đóng gói sẵn. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` là công tắc tương thích phá kính đã lỗi thời dành cho các lỗi đọc registry. Ưu tiên `plugins registry --refresh` hoặc `openclaw doctor --fix`; cơ chế dự phòng bằng biến môi trường chỉ dành cho khôi phục khởi động khẩn cấp trong khi quá trình di chuyển đang được triển khai. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` là công tắc tương thích khẩn cấp đã lỗi thời cho các lỗi đọc registry. Ưu tiên `plugins registry --refresh` hoặc `openclaw doctor --fix`; fallback bằng env chỉ dành cho khôi phục khởi động khẩn cấp trong khi quá trình di chuyển đang được triển khai. -### Chợ ứng dụng +### Marketplace ```bash openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Danh sách chợ ứng dụng chấp nhận đường dẫn chợ ứng dụng cục bộ, đường dẫn `marketplace.json`, cách viết tắt GitHub như `owner/repo`, URL repo GitHub hoặc URL git. `--json` in nhãn nguồn đã phân giải cùng với manifest chợ ứng dụng đã phân tích và các mục Plugin. +Danh sách Marketplace chấp nhận đường dẫn marketplace cục bộ, đường dẫn `marketplace.json`, cách viết tắt GitHub như `owner/repo`, URL repo GitHub hoặc URL git. `--json` in nhãn nguồn đã phân giải cùng với manifest marketplace đã phân tích cú pháp và các mục plugin. ## Liên quan -- [Xây dựng Plugin](/vi/plugins/building-plugins) +- [Xây dựng plugin](/vi/plugins/building-plugins) - [Tham chiếu CLI](/vi/cli) - [Plugin cộng đồng](/vi/plugins/community) diff --git a/docs/vi/gateway/doctor.md b/docs/vi/gateway/doctor.md index db700a845..203db140f 100644 --- a/docs/vi/gateway/doctor.md +++ b/docs/vi/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - Thêm hoặc sửa đổi các bản di trú của lệnh doctor + - Thêm hoặc sửa đổi các chuyển đổi của doctor - Đưa vào các thay đổi cấu hình phá vỡ tương thích sidebarTitle: Doctor summary: 'Lệnh doctor: kiểm tra tình trạng, di chuyển cấu hình và các bước sửa chữa' -title: Công cụ chẩn đoán +title: Trình chẩn đoán x-i18n: - generated_at: "2026-05-03T10:36:56Z" + generated_at: "2026-05-04T09:37:05Z" model: gpt-5.5 provider: openai - source_hash: 20b2cb3c3cd88e01050cb285a08a020603642439bd35668b7414360801fc03ff + source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798 source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` là công cụ sửa chữa + di chuyển dữ liệu cho OpenClaw. Công cụ này sửa cấu hình/trạng thái cũ, kiểm tra sức khỏe và cung cấp các bước sửa chữa có thể thực hiện. +`openclaw doctor` là công cụ sửa chữa + di trú cho OpenClaw. Công cụ này sửa cấu hình/trạng thái cũ, kiểm tra tình trạng, và cung cấp các bước sửa chữa có thể thực hiện. ## Bắt đầu nhanh @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### Chế độ headless và tự động hóa +### Chế độ không giao diện và tự động hóa @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Chấp nhận mặc định mà không nhắc hỏi (bao gồm các bước sửa chữa khởi động lại/dịch vụ/sandbox khi áp dụng). + Chấp nhận mặc định mà không hỏi (bao gồm các bước sửa chữa khởi động lại/dịch vụ/sandbox khi áp dụng). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - Áp dụng các sửa chữa được khuyến nghị mà không nhắc hỏi (sửa chữa + khởi động lại ở những nơi an toàn). + Áp dụng các sửa chữa được khuyến nghị mà không hỏi (sửa chữa + khởi động lại ở nơi an toàn). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Chạy không có lời nhắc và chỉ áp dụng các di chuyển dữ liệu an toàn (chuẩn hóa cấu hình + di chuyển trạng thái trên đĩa). Bỏ qua các hành động khởi động lại/dịch vụ/sandbox cần xác nhận của con người. Các di chuyển trạng thái cũ tự động chạy khi được phát hiện. + Chạy không có lời nhắc và chỉ áp dụng các di trú an toàn (chuẩn hóa cấu hình + di chuyển trạng thái trên đĩa). Bỏ qua các hành động khởi động lại/dịch vụ/sandbox cần xác nhận của người dùng. Các di trú trạng thái cũ tự động chạy khi được phát hiện. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Quét dịch vụ hệ thống để tìm các bản cài đặt gateway bổ sung (launchd/systemd/schtasks). + Quét các dịch vụ hệ thống để tìm thêm các bản cài đặt gateway (launchd/systemd/schtasks). @@ -73,123 +73,123 @@ Nếu bạn muốn xem lại thay đổi trước khi ghi, hãy mở tệp cấu cat ~/.openclaw/openclaw.json ``` -## Công cụ làm gì (tóm tắt) +## Công cụ này làm gì (tóm tắt) - - - Cập nhật pre-flight tùy chọn cho bản cài đặt git (chỉ tương tác). + + - Cập nhật trước khi chạy tùy chọn cho các bản cài đặt git (chỉ tương tác). - Kiểm tra độ mới của giao thức UI (xây dựng lại Control UI khi schema giao thức mới hơn). - - Kiểm tra sức khỏe + lời nhắc khởi động lại. + - Kiểm tra tình trạng + lời nhắc khởi động lại. - Tóm tắt trạng thái Skills (đủ điều kiện/thiếu/bị chặn) và trạng thái Plugin. - + - Chuẩn hóa cấu hình cho các giá trị cũ. - - Di chuyển cấu hình talk từ các trường phẳng `talk.*` cũ sang `talk.provider` + `talk.providers.`. - - Kiểm tra di chuyển trình duyệt cho cấu hình Chrome extension cũ và mức sẵn sàng Chrome MCP. + - Di trú cấu hình Talk từ các trường phẳng `talk.*` cũ sang `talk.provider` + `talk.providers.`. + - Kiểm tra di trú trình duyệt cho cấu hình tiện ích Chrome cũ và mức sẵn sàng Chrome MCP. - Cảnh báo ghi đè provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - - Cảnh báo che khuất OAuth của Codex (`models.providers.openai-codex`). - - Kiểm tra điều kiện tiên quyết OAuth TLS cho hồ sơ OpenAI Codex OAuth. - - Cảnh báo allowlist Plugin/công cụ khi `plugins.allow` bị hạn chế nhưng chính sách công cụ vẫn yêu cầu ký tự đại diện hoặc công cụ do Plugin sở hữu. - - Di chuyển trạng thái cũ trên đĩa (phiên/thư mục agent/xác thực WhatsApp). - - Di chuyển khóa hợp đồng manifest Plugin cũ (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Di chuyển kho cron cũ (`jobId`, `schedule.cron`, các trường delivery/payload cấp cao nhất, payload `provider`, các tác vụ webhook dự phòng đơn giản `notify: true`). - - Di chuyển runtime-policy agent cũ sang `agents.defaults.agentRuntime` và `agents.list[].agentRuntime`. - - Dọn dẹp cấu hình Plugin cũ khi Plugin được bật; khi `plugins.enabled=false`, các tham chiếu Plugin cũ được coi là cấu hình cách ly bất hoạt và được giữ lại. + - Cảnh báo che khuất OAuth Codex (`models.providers.openai-codex`). + - Kiểm tra điều kiện tiên quyết TLS OAuth cho hồ sơ OAuth OpenAI Codex. + - Cảnh báo danh sách cho phép Plugin/công cụ khi `plugins.allow` bị giới hạn nhưng chính sách công cụ vẫn yêu cầu ký tự đại diện hoặc công cụ thuộc sở hữu Plugin. + - Di trú trạng thái cũ trên đĩa (sessions/thư mục agent/xác thực WhatsApp). + - Di trú khóa hợp đồng manifest Plugin cũ (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Di trú kho cron cũ (`jobId`, `schedule.cron`, các trường delivery/payload cấp cao nhất, payload `provider`, các job dự phòng webhook `notify: true` đơn giản). + - Di trú chính sách runtime agent cũ sang `agents.defaults.agentRuntime` và `agents.list[].agentRuntime`. + - Dọn dẹp cấu hình Plugin cũ khi Plugin được bật; khi `plugins.enabled=false`, các tham chiếu Plugin cũ được xem là cấu hình cô lập không hoạt động và được giữ nguyên. - Kiểm tra tệp khóa phiên và dọn dẹp khóa cũ. - - Sửa chữa transcript phiên cho các nhánh prompt-rewrite trùng lặp do các bản build 2026.4.24 bị ảnh hưởng tạo ra. - - Phát hiện tombstone phục hồi khởi động lại của subagent bị kẹt, có hỗ trợ `--fix` để xóa các cờ phục hồi đã hủy cũ để quá trình khởi động không tiếp tục coi tiến trình con là đã bị hủy khi khởi động lại. - - Kiểm tra tính toàn vẹn trạng thái và quyền (phiên, transcript, thư mục trạng thái). + - Sửa chữa bản ghi phiên cho các nhánh viết lại prompt bị trùng lặp do các bản dựng 2026.4.24 bị ảnh hưởng tạo ra. + - Phát hiện tombstone phục hồi-khởi động lại của subagent bị kẹt, có hỗ trợ `--fix` để xóa cờ phục hồi bị hủy đã cũ để lúc khởi động không tiếp tục xem child là đã bị hủy khởi động lại. + - Kiểm tra tính toàn vẹn trạng thái và quyền (sessions, transcripts, thư mục trạng thái). - Kiểm tra quyền tệp cấu hình (chmod 600) khi chạy cục bộ. - - Sức khỏe xác thực mô hình: kiểm tra OAuth hết hạn, có thể làm mới token sắp hết hạn và báo cáo trạng thái cooldown/vô hiệu hóa của auth-profile. - - Phát hiện thư mục workspace bổ sung (`~/openclaw`). + - Tình trạng xác thực mô hình: kiểm tra OAuth hết hạn, có thể làm mới token sắp hết hạn, và báo cáo trạng thái cooldown/bị vô hiệu hóa của hồ sơ xác thực. + - Phát hiện thư mục workspace thừa (`~/openclaw`). - - - Sửa chữa ảnh sandbox khi sandboxing được bật. - - Di chuyển dịch vụ cũ và phát hiện gateway bổ sung. - - Di chuyển trạng thái cũ của kênh Matrix (ở chế độ `--fix` / `--repair`). - - Kiểm tra runtime Gateway (dịch vụ đã cài đặt nhưng không chạy; nhãn launchd được lưu trong bộ nhớ đệm). + + - Sửa chữa image sandbox khi sandboxing được bật. + - Di trú dịch vụ cũ và phát hiện gateway thừa. + - Di trú trạng thái cũ của kênh Matrix (ở chế độ `--fix` / `--repair`). + - Kiểm tra runtime Gateway (dịch vụ đã cài nhưng không chạy; nhãn launchd được lưu cache). - Cảnh báo trạng thái kênh (được thăm dò từ gateway đang chạy). - - Kiểm tra cấu hình trình giám sát (launchd/systemd/schtasks) với tùy chọn sửa chữa. - - Dọn dẹp môi trường proxy nhúng cho các dịch vụ gateway đã ghi lại các giá trị shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` trong quá trình cài đặt hoặc cập nhật. + - Kiểm tra cấu hình supervisor (launchd/systemd/schtasks) với sửa chữa tùy chọn. + - Dọn dẹp môi trường proxy nhúng cho các dịch vụ gateway đã thu thập giá trị shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` trong quá trình cài đặt hoặc cập nhật. - Kiểm tra thực hành tốt nhất cho runtime Gateway (Node so với Bun, đường dẫn trình quản lý phiên bản). - Chẩn đoán xung đột cổng Gateway (mặc định `18789`). - + - Cảnh báo bảo mật cho chính sách DM mở. - - Kiểm tra xác thực Gateway cho chế độ token cục bộ (đề xuất tạo token khi không có nguồn token; không ghi đè cấu hình SecretRef của token). - - Phát hiện sự cố ghép đôi thiết bị (yêu cầu ghép đôi lần đầu đang chờ, nâng cấp vai trò/phạm vi đang chờ, sai lệch bộ nhớ đệm token thiết bị cục bộ đã cũ, và sai lệch xác thực bản ghi đã ghép đôi). + - Kiểm tra xác thực Gateway cho chế độ token cục bộ (đề xuất tạo token khi không có nguồn token; không ghi đè cấu hình token SecretRef). + - Phát hiện sự cố ghép nối thiết bị (yêu cầu ghép nối lần đầu đang chờ, nâng cấp vai trò/phạm vi đang chờ, lệch cache token thiết bị cục bộ đã cũ, và lệch xác thực bản ghi đã ghép nối). - + - Kiểm tra systemd linger trên Linux. - - Kiểm tra kích thước tệp bootstrap không gian làm việc (cảnh báo bị cắt ngắn/gần giới hạn cho các tệp ngữ cảnh). - - Kiểm tra mức sẵn sàng của Skills cho agent mặc định; báo cáo các skill được phép nhưng thiếu bin, env, cấu hình hoặc yêu cầu hệ điều hành, và `--fix` có thể tắt các skill không khả dụng trong `skills.entries`. - - Kiểm tra trạng thái shell completion và tự động cài đặt/nâng cấp. - - Kiểm tra mức sẵn sàng của nhà cung cấp embedding tìm kiếm bộ nhớ (mô hình cục bộ, khóa API từ xa hoặc binary QMD). - - Kiểm tra bản cài đặt từ mã nguồn (pnpm workspace không khớp, thiếu tài sản UI, thiếu binary tsx). - - Ghi cấu hình đã cập nhật + siêu dữ liệu wizard. + - Kiểm tra kích thước tệp bootstrap workspace (cảnh báo bị cắt/gần giới hạn cho tệp ngữ cảnh). + - Kiểm tra mức sẵn sàng Skills cho agent mặc định; báo cáo các skill được phép nhưng thiếu bin, env, config hoặc yêu cầu OS, và `--fix` có thể vô hiệu hóa các skill không khả dụng trong `skills.entries`. + - Kiểm tra trạng thái hoàn thành shell và tự động cài đặt/nâng cấp. + - Kiểm tra mức sẵn sàng provider embedding tìm kiếm bộ nhớ (mô hình cục bộ, khóa API từ xa hoặc binary QMD). + - Kiểm tra bản cài đặt từ mã nguồn (pnpm workspace không khớp, thiếu asset UI, thiếu binary tsx). + - Ghi cấu hình đã cập nhật + metadata wizard. -## Điền bù và đặt lại giao diện người dùng Dreams +## Điền ngược và đặt lại Dreams UI -Cảnh Dreams trong Control UI bao gồm các hành động **Điền bù**, **Đặt lại**, và **Xóa mục có căn cứ** cho quy trình dreaming có căn cứ. Các hành động này dùng những phương thức RPC kiểu doctor của gateway, nhưng chúng **không** phải là một phần của sửa chữa/di chuyển `openclaw doctor` trong CLI. +Cảnh Dreams trong Control UI bao gồm các hành động **Backfill**, **Reset** và **Clear Grounded** cho quy trình grounded dreaming. Các hành động này dùng phương thức RPC kiểu gateway doctor, nhưng chúng **không** phải là một phần của sửa chữa/di trú CLI `openclaw doctor`. -Những việc chúng làm: +Các hành động này làm gì: -- **Điền bù** quét các tệp lịch sử `memory/YYYY-MM-DD.md` trong không gian làm việc đang hoạt động, chạy lượt nhật ký REM có căn cứ, và ghi các mục điền bù có thể đảo ngược vào `DREAMS.md`. -- **Đặt lại** chỉ xóa các mục nhật ký điền bù đã đánh dấu đó khỏi `DREAMS.md`. -- **Xóa mục có căn cứ** chỉ xóa các mục ngắn hạn chỉ có căn cứ đã được đưa vào vùng staging, đến từ phát lại lịch sử và chưa tích lũy thu hồi trực tiếp hoặc hỗ trợ hằng ngày. +- **Backfill** quét các tệp `memory/YYYY-MM-DD.md` lịch sử trong workspace đang hoạt động, chạy lượt nhật ký REM grounded, và ghi các mục điền ngược có thể đảo ngược vào `DREAMS.md`. +- **Reset** chỉ xóa các mục nhật ký điền ngược đã được đánh dấu đó khỏi `DREAMS.md`. +- **Clear Grounded** chỉ xóa các mục ngắn hạn chỉ-grounded đã được staging đến từ phát lại lịch sử và chưa tích lũy recall trực tiếp hoặc hỗ trợ hằng ngày. -Những việc chúng **không** tự làm: +Bản thân các hành động này **không** làm gì: - chúng không chỉnh sửa `MEMORY.md` -- chúng không chạy đầy đủ các di chuyển doctor -- chúng không tự động đưa các ứng viên có căn cứ vào kho thăng hạng ngắn hạn trực tiếp trừ khi bạn chạy rõ ràng đường dẫn CLI có staging trước +- chúng không chạy toàn bộ di trú doctor +- chúng không tự động staging các ứng viên grounded vào kho thăng cấp ngắn hạn trực tiếp trừ khi bạn chạy rõ ràng đường dẫn CLI đã staging trước -Nếu bạn muốn phát lại lịch sử có căn cứ ảnh hưởng đến làn thăng hạng sâu thông thường, hãy dùng luồng CLI thay vào đó: +Nếu bạn muốn phát lại lịch sử grounded ảnh hưởng đến lane thăng cấp sâu thông thường, hãy dùng luồng CLI thay thế: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Lệnh đó đưa các ứng viên bền vững có căn cứ vào kho dreaming ngắn hạn trong khi vẫn giữ `DREAMS.md` làm bề mặt đánh giá. +Lệnh đó staging các ứng viên bền vững grounded vào kho Dreaming ngắn hạn trong khi vẫn giữ `DREAMS.md` làm bề mặt xem xét. ## Hành vi chi tiết và lý do - Nếu đây là một git checkout và doctor đang chạy tương tác, nó sẽ đề xuất cập nhật (fetch/rebase/build) trước khi chạy doctor. + Nếu đây là checkout git và doctor đang chạy tương tác, công cụ sẽ đề xuất cập nhật (fetch/rebase/build) trước khi chạy doctor. - Nếu cấu hình chứa các dạng giá trị cũ (ví dụ `messages.ackReaction` không có ghi đè riêng theo kênh), doctor sẽ chuẩn hóa chúng vào schema hiện tại. + Nếu cấu hình chứa các dạng giá trị cũ (ví dụ `messages.ackReaction` không có ghi đè riêng theo kênh), doctor chuẩn hóa chúng vào schema hiện tại. - Điều đó bao gồm các trường phẳng Talk cũ. Cấu hình Talk công khai hiện tại là `talk.provider` + `talk.providers.`. Doctor ghi lại các dạng `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` cũ vào bản đồ nhà cung cấp. + Điều đó bao gồm các trường phẳng Talk cũ. Cấu hình Talk công khai hiện tại là `talk.provider` + `talk.providers.`. Doctor viết lại các dạng `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` cũ vào map provider. Doctor cũng cảnh báo khi `plugins.allow` không rỗng và chính sách công cụ dùng - ký tự đại diện hoặc mục công cụ thuộc sở hữu Plugin. `tools.allow: ["*"]` chỉ khớp với các công cụ - từ các plugin thực sự tải; nó không bỏ qua allowlist Plugin độc quyền. + ký tự đại diện hoặc các mục công cụ thuộc sở hữu Plugin. `tools.allow: ["*"]` chỉ khớp các công cụ + từ Plugin thật sự được tải; nó không bỏ qua danh sách cho phép Plugin độc quyền. - - Khi cấu hình chứa các khóa không còn dùng nữa, các lệnh khác sẽ từ chối chạy và yêu cầu bạn chạy `openclaw doctor`. + + Khi cấu hình chứa các khóa không còn dùng, các lệnh khác sẽ từ chối chạy và yêu cầu bạn chạy `openclaw doctor`. Doctor sẽ: - - Giải thích những khóa cũ nào đã được tìm thấy. - - Hiển thị quá trình di chuyển đã áp dụng. - - Ghi lại `~/.openclaw/openclaw.json` với schema đã cập nhật. + - Giải thích những khóa cũ nào được tìm thấy. + - Hiển thị di trú đã áp dụng. + - Viết lại `~/.openclaw/openclaw.json` bằng schema đã cập nhật. - Gateway cũng tự động chạy các di chuyển doctor khi khởi động nếu phát hiện định dạng cấu hình cũ, vì vậy cấu hình lỗi thời được sửa chữa mà không cần can thiệp thủ công. Di chuyển kho tác vụ Cron được xử lý bằng `openclaw doctor --fix`. + Gateway cũng tự động chạy di trú doctor khi khởi động nếu phát hiện định dạng cấu hình cũ, vì vậy cấu hình lỗi thời được sửa mà không cần can thiệp thủ công. Di trú kho job Cron được xử lý bởi `openclaw doctor --fix`. - Các di chuyển hiện tại: + Các di trú hiện tại: - `routing.allowFrom` → `channels.whatsapp.allowFrom` - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention` @@ -213,66 +213,66 @@ Lệnh đó đưa các ứng viên bền vững có căn cứ vào kho dreaming - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Với các kênh có `accounts` được đặt tên nhưng vẫn còn các giá trị kênh cấp cao nhất kiểu một tài khoản, hãy chuyển các giá trị theo phạm vi tài khoản đó vào tài khoản được nâng cấp đã chọn cho kênh đó (`accounts.default` cho hầu hết kênh; Matrix có thể giữ nguyên một đích được đặt tên/mặc định hiện có khớp) + - Với các kênh có `accounts` được đặt tên nhưng vẫn còn các giá trị kênh cấp cao nhất cho một tài khoản đơn, hãy di chuyển các giá trị thuộc phạm vi tài khoản đó vào tài khoản được nâng cấp đã chọn cho kênh đó (`accounts.default` cho hầu hết các kênh; Matrix có thể giữ nguyên một đích được đặt tên/mặc định hiện có khớp) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - xóa `agents.defaults.llm`; dùng `models.providers..timeoutSeconds` cho thời gian chờ provider/model chậm - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - xóa `browser.relayBindHost` (thiết lập relay extension cũ) - - `models.providers.*.api: "openai"` cũ → `"openai-completions"` (quá trình khởi động Gateway cũng bỏ qua các provider có `api` được đặt thành giá trị enum tương lai hoặc không xác định thay vì đóng lỗi) + - xóa `browser.relayBindHost` (thiết lập chuyển tiếp extension cũ) + - `models.providers.*.api: "openai"` cũ → `"openai-completions"` (Gateway khi khởi động cũng bỏ qua các provider có `api` được đặt thành giá trị enum trong tương lai hoặc không xác định thay vì đóng lỗi) - Cảnh báo của doctor cũng bao gồm hướng dẫn tài khoản mặc định cho kênh nhiều tài khoản: + Cảnh báo của doctor cũng bao gồm hướng dẫn tài khoản mặc định cho các kênh đa tài khoản: - - Nếu hai hoặc nhiều mục `channels..accounts` được cấu hình mà không có `channels..defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản ngoài dự kiến. + - Nếu hai mục `channels..accounts` trở lên được cấu hình mà không có `channels..defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản không mong muốn. - Nếu `channels..defaultAccount` được đặt thành ID tài khoản không xác định, doctor cảnh báo và liệt kê các ID tài khoản đã cấu hình. - Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, nó sẽ ghi đè danh mục OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể buộc model dùng sai API hoặc đưa chi phí về không. Doctor cảnh báo để bạn có thể xóa ghi đè và khôi phục định tuyến API + chi phí theo từng model. + Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, nó sẽ ghi đè catalog OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể ép các model dùng sai API hoặc đưa chi phí về 0. Doctor cảnh báo để bạn có thể xóa phần ghi đè và khôi phục định tuyến API + chi phí theo từng model. - - Nếu cấu hình trình duyệt của bạn vẫn trỏ tới đường dẫn Chrome extension đã bị xóa, doctor chuẩn hóa nó sang mô hình đính kèm Chrome MCP cục bộ trên host hiện tại: + + Nếu cấu hình trình duyệt của bạn vẫn trỏ tới đường dẫn Chrome extension đã bị xóa, doctor sẽ chuẩn hóa nó sang mô hình gắn Chrome MCP host-local hiện tại: - `browser.profiles.*.driver: "extension"` trở thành `"existing-session"` - `browser.relayBindHost` bị xóa - Doctor cũng kiểm tra đường dẫn Chrome MCP cục bộ trên host khi bạn dùng `defaultProfile: "user"` hoặc một hồ sơ `existing-session` đã cấu hình: + Doctor cũng kiểm tra đường dẫn Chrome MCP host-local khi bạn dùng `defaultProfile: "user"` hoặc một hồ sơ `existing-session` đã cấu hình: - - kiểm tra Google Chrome có được cài đặt trên cùng host cho các hồ sơ tự động kết nối mặc định hay không + - kiểm tra Google Chrome có được cài trên cùng host cho các hồ sơ tự động kết nối mặc định hay không - kiểm tra phiên bản Chrome phát hiện được và cảnh báo khi thấp hơn Chrome 144 - nhắc bạn bật gỡ lỗi từ xa trong trang kiểm tra của trình duyệt (ví dụ `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, hoặc `edge://inspect/#remote-debugging`) - Doctor không thể bật thiết lập phía Chrome thay bạn. Chrome MCP cục bộ trên host vẫn yêu cầu: + Doctor không thể bật thiết lập phía Chrome cho bạn. Chrome MCP host-local vẫn yêu cầu: - - trình duyệt dựa trên Chromium 144+ trên host gateway/node + - trình duyệt dựa trên Chromium phiên bản 144+ trên host gateway/node - trình duyệt đang chạy cục bộ - - đã bật gỡ lỗi từ xa trong trình duyệt đó - - chấp thuận lời nhắc đồng ý đính kèm đầu tiên trong trình duyệt + - gỡ lỗi từ xa được bật trong trình duyệt đó + - chấp thuận lời nhắc đồng ý gắn lần đầu trong trình duyệt - Mức sẵn sàng ở đây chỉ nói về các điều kiện tiên quyết để đính kèm cục bộ. Existing-session giữ các giới hạn tuyến Chrome MCP hiện tại; các tuyến nâng cao như `responsebody`, xuất PDF, chặn tải xuống, và thao tác hàng loạt vẫn yêu cầu trình duyệt được quản lý hoặc hồ sơ CDP thô. + Trạng thái sẵn sàng ở đây chỉ liên quan đến điều kiện tiên quyết để gắn cục bộ. Existing-session giữ các giới hạn tuyến Chrome MCP hiện tại; các tuyến nâng cao như `responsebody`, xuất PDF, chặn tải xuống và hành động hàng loạt vẫn yêu cầu trình duyệt được quản lý hoặc hồ sơ CDP thô. - Kiểm tra này **không** áp dụng cho Docker, sandbox, remote-browser, hoặc các luồng headless khác. Các luồng đó tiếp tục dùng CDP thô. + Kiểm tra này **không** áp dụng cho Docker, sandbox, remote-browser hoặc các luồng headless khác. Các luồng đó tiếp tục dùng CDP thô. - Khi một hồ sơ OpenAI Codex OAuth được cấu hình, doctor thăm dò endpoint ủy quyền OpenAI để xác minh rằng ngăn xếp TLS Node/OpenSSL cục bộ có thể xác thực chuỗi chứng chỉ. Nếu thăm dò thất bại với lỗi chứng chỉ (ví dụ `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, chứng chỉ hết hạn, hoặc chứng chỉ tự ký), doctor in hướng dẫn sửa lỗi theo từng nền tảng. Trên macOS với Node từ Homebrew, cách sửa thường là `brew postinstall ca-certificates`. Với `--deep`, thăm dò vẫn chạy ngay cả khi gateway khỏe mạnh. + Khi một hồ sơ OpenAI Codex OAuth được cấu hình, doctor thăm dò endpoint ủy quyền OpenAI để xác minh rằng ngăn xếp TLS Node/OpenSSL cục bộ có thể xác thực chuỗi chứng chỉ. Nếu thăm dò thất bại với lỗi chứng chỉ (ví dụ `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, chứng chỉ hết hạn hoặc chứng chỉ tự ký), doctor in hướng dẫn sửa theo từng nền tảng. Trên macOS với Homebrew Node, cách sửa thường là `brew postinstall ca-certificates`. Với `--deep`, thăm dò sẽ chạy ngay cả khi gateway khỏe mạnh. - Nếu trước đây bạn đã thêm các thiết lập truyền tải OpenAI cũ trong `models.providers.openai-codex`, chúng có thể che khuất đường dẫn provider Codex OAuth tích hợp mà các bản phát hành mới hơn tự động sử dụng. Doctor cảnh báo khi thấy các thiết lập truyền tải cũ đó đi kèm Codex OAuth để bạn có thể xóa hoặc viết lại ghi đè truyền tải đã lỗi thời và lấy lại hành vi định tuyến/dự phòng tích hợp. Proxy tùy chỉnh và ghi đè chỉ header vẫn được hỗ trợ và không kích hoạt cảnh báo này. + Nếu trước đây bạn đã thêm các thiết lập truyền tải OpenAI cũ dưới `models.providers.openai-codex`, chúng có thể che khuất đường dẫn provider Codex OAuth tích hợp mà các bản phát hành mới hơn tự động sử dụng. Doctor cảnh báo khi thấy các thiết lập truyền tải cũ đó cùng với Codex OAuth để bạn có thể xóa hoặc viết lại phần ghi đè truyền tải lỗi thời và lấy lại hành vi định tuyến/dự phòng tích hợp. Proxy tùy chỉnh và ghi đè chỉ-header vẫn được hỗ trợ và không kích hoạt cảnh báo này. - Khi Plugin Codex đi kèm được bật, doctor cũng kiểm tra xem các tham chiếu model chính `openai-codex/*` có còn phân giải qua PI runner mặc định hay không. Tổ hợp đó hợp lệ khi bạn muốn xác thực Codex OAuth/subscription thông qua PI, nhưng dễ bị nhầm với harness app-server Codex gốc. Doctor cảnh báo và trỏ tới dạng app-server tường minh: `openai/*` cộng với `agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex`. + Khi Plugin Codex đi kèm được bật, doctor cũng kiểm tra liệu các tham chiếu model chính `openai-codex/*` có còn phân giải qua trình chạy PI mặc định hay không. Tổ hợp đó hợp lệ khi bạn muốn xác thực Codex OAuth/đăng ký qua PI, nhưng rất dễ nhầm với bộ chạy app-server Codex gốc. Doctor cảnh báo và trỏ tới dạng app-server rõ ràng: `openai/*` cộng với `agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor không tự động sửa điều này vì cả hai tuyến đều hợp lệ: + Doctor không tự động sửa lỗi này vì cả hai tuyến đều hợp lệ: - - `openai-codex/*` + PI nghĩa là "dùng xác thực Codex OAuth/subscription thông qua runner OpenClaw bình thường." - - `openai/*` + `agentRuntime.id: "codex"` nghĩa là "chạy lượt nhúng thông qua app-server Codex gốc." + - `openai-codex/*` + PI nghĩa là "dùng xác thực Codex OAuth/đăng ký qua trình chạy OpenClaw thông thường." + - `openai/*` + `agentRuntime.id: "codex"` nghĩa là "chạy lượt nhúng qua app-server Codex gốc." - `/codex ...` nghĩa là "điều khiển hoặc liên kết một cuộc trò chuyện Codex gốc từ chat." - - `/acp ...` hoặc `runtime: "acp"` nghĩa là "dùng adapter ACP/acpx bên ngoài." + - `/acp ...` hoặc `runtime: "acp"` nghĩa là "dùng bộ điều hợp ACP/acpx bên ngoài." - Nếu cảnh báo xuất hiện, hãy chọn tuyến bạn định dùng và sửa cấu hình thủ công. Giữ nguyên cảnh báo khi PI Codex OAuth là chủ ý. + Nếu cảnh báo xuất hiện, hãy chọn tuyến bạn định dùng và chỉnh sửa cấu hình thủ công. Giữ nguyên cảnh báo khi PI Codex OAuth là chủ ý. @@ -280,89 +280,89 @@ Lệnh đó đưa các ứng viên bền vững có căn cứ vào kho dreaming - Kho phiên + bản ghi: - từ `~/.openclaw/sessions/` sang `~/.openclaw/agents//sessions/` - - Thư mục tác nhân: + - Thư mục agent: - từ `~/.openclaw/agent/` sang `~/.openclaw/agents//agent/` - Trạng thái xác thực WhatsApp (Baileys): - từ `~/.openclaw/credentials/*.json` cũ (ngoại trừ `oauth.json`) - sang `~/.openclaw/credentials/whatsapp//...` (id tài khoản mặc định: `default`) - Các lần di chuyển này theo nguyên tắc cố gắng tối đa và có tính lặp lại an toàn; doctor sẽ phát cảnh báo khi để lại bất kỳ thư mục cũ nào làm bản sao lưu. Gateway/CLI cũng tự động di chuyển kho phiên cũ + thư mục tác nhân khi khởi động để lịch sử/xác thực/model nằm trong đường dẫn theo từng tác nhân mà không cần chạy doctor thủ công. Xác thực WhatsApp được chủ ý chỉ di chuyển qua `openclaw doctor`. Việc chuẩn hóa provider/bản đồ provider của talk hiện so sánh bằng bình đẳng cấu trúc, nên các khác biệt chỉ do thứ tự khóa không còn kích hoạt lặp lại các thay đổi `doctor --fix` không có tác dụng. + Những lần di chuyển này là nỗ lực tối đa và có tính lặp lại an toàn; doctor sẽ phát cảnh báo khi để lại bất kỳ thư mục cũ nào làm bản sao lưu. Gateway/CLI cũng tự động di chuyển kho phiên cũ + thư mục agent khi khởi động để lịch sử/xác thực/model nằm trong đường dẫn theo từng agent mà không cần chạy doctor thủ công. Xác thực WhatsApp được cố ý chỉ di chuyển qua `openclaw doctor`. Việc chuẩn hóa provider/bản đồ provider của Talk hiện so sánh bằng bình đẳng cấu trúc, nên các khác biệt chỉ do thứ tự khóa không còn kích hoạt lại các thay đổi `doctor --fix` không tác dụng. - Doctor quét tất cả manifest Plugin đã cài đặt để tìm các khóa khả năng cấp cao nhất đã ngừng dùng (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Khi tìm thấy, nó đề nghị chuyển chúng vào đối tượng `contracts` và ghi lại trực tiếp tệp manifest. Di chuyển này có tính lặp lại an toàn; nếu khóa `contracts` đã có cùng các giá trị, khóa cũ bị xóa mà không nhân đôi dữ liệu. + Doctor quét tất cả manifest Plugin đã cài đặt để tìm các khóa capability cấp cao nhất đã lỗi thời (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Khi tìm thấy, nó đề xuất di chuyển chúng vào đối tượng `contracts` và ghi lại file manifest tại chỗ. Việc di chuyển này có tính lặp lại an toàn; nếu khóa `contracts` đã có cùng các giá trị, khóa cũ sẽ bị xóa mà không nhân đôi dữ liệu. - - Doctor cũng kiểm tra kho tác vụ cron (`~/.openclaw/cron/jobs.json` theo mặc định, hoặc `cron.store` khi bị ghi đè) để tìm các dạng tác vụ cũ mà bộ lập lịch vẫn chấp nhận vì tương thích. + + Doctor cũng kiểm tra kho công việc Cron (`~/.openclaw/cron/jobs.json` theo mặc định, hoặc `cron.store` khi được ghi đè) để tìm các dạng công việc cũ mà bộ lập lịch vẫn chấp nhận để tương thích. - Các dọn dẹp cron hiện tại bao gồm: + Các dọn dẹp Cron hiện tại bao gồm: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - - trường payload cấp cao nhất (`message`, `model`, `thinking`, ...) → `payload` - - trường gửi cấp cao nhất (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - bí danh gửi `provider` của payload → `delivery.channel` tường minh - - tác vụ dự phòng webhook `notify: true` cũ đơn giản → `delivery.mode="webhook"` tường minh với `delivery.to=cron.webhook` + - các trường payload cấp cao nhất (`message`, `model`, `thinking`, ...) → `payload` + - các trường delivery cấp cao nhất (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` + - bí danh delivery `provider` trong payload → `delivery.channel` rõ ràng + - các công việc dự phòng webhook `notify: true` đơn giản cũ → `delivery.mode="webhook"` rõ ràng với `delivery.to=cron.webhook` - Doctor chỉ tự động di chuyển các tác vụ `notify: true` khi có thể làm vậy mà không thay đổi hành vi. Nếu một tác vụ kết hợp dự phòng notify cũ với một chế độ gửi không phải webhook hiện có, doctor cảnh báo và để tác vụ đó lại để xem xét thủ công. + Doctor chỉ tự động di chuyển các công việc `notify: true` khi có thể làm vậy mà không thay đổi hành vi. Nếu một công việc kết hợp dự phòng notify cũ với một chế độ delivery hiện có không phải webhook, doctor cảnh báo và để công việc đó cho bạn xem xét thủ công. - Trên Linux, doctor cũng cảnh báo khi crontab của người dùng vẫn gọi `~/.openclaw/bin/ensure-whatsapp.sh` cũ. Script cục bộ trên host đó không được OpenClaw hiện tại bảo trì và có thể ghi thông báo `Gateway inactive` sai vào `~/.openclaw/logs/whatsapp-health.log` khi cron không thể tiếp cận systemd user bus. Xóa mục crontab lỗi thời bằng `crontab -e`; dùng `openclaw channels status --probe`, `openclaw doctor`, và `openclaw gateway status` cho các kiểm tra sức khỏe hiện tại. + Trên Linux, doctor cũng cảnh báo khi crontab của người dùng vẫn gọi `~/.openclaw/bin/ensure-whatsapp.sh` cũ. Script host-local đó không được OpenClaw hiện tại bảo trì và có thể ghi các thông báo `Gateway inactive` sai vào `~/.openclaw/logs/whatsapp-health.log` khi cron không thể truy cập bus người dùng systemd. Xóa mục crontab lỗi thời bằng `crontab -e`; dùng `openclaw channels status --probe`, `openclaw doctor`, và `openclaw gateway status` cho các kiểm tra sức khỏe hiện tại. - Doctor quét mọi thư mục phiên agent để tìm các tệp khóa ghi cũ — các tệp bị bỏ lại khi một phiên thoát bất thường. Với mỗi tệp khóa tìm thấy, công cụ báo cáo: đường dẫn, PID, PID có còn đang chạy hay không, tuổi của khóa, và khóa đó có được xem là cũ hay không (PID đã chết hoặc cũ hơn 30 phút). Ở chế độ `--fix` / `--repair`, công cụ tự động xóa các tệp khóa cũ; nếu không, công cụ in ghi chú và hướng dẫn bạn chạy lại với `--fix`. + Doctor quét mọi thư mục phiên tác tử để tìm các tệp khóa ghi cũ — các tệp bị bỏ lại khi một phiên thoát bất thường. Với mỗi tệp khóa tìm thấy, công cụ báo cáo: đường dẫn, PID, liệu PID còn hoạt động hay không, tuổi khóa, và liệu khóa có được xem là cũ hay không (PID đã chết hoặc cũ hơn 30 phút). Ở chế độ `--fix` / `--repair`, công cụ tự động xóa các tệp khóa cũ; nếu không, công cụ in ghi chú và hướng dẫn bạn chạy lại với `--fix`. - - Doctor quét các tệp JSONL phiên agent để tìm hình dạng nhánh bị trùng lặp do lỗi viết lại bản ghi prompt ngày 2026.4.24 tạo ra: một lượt người dùng bị bỏ rơi có ngữ cảnh runtime nội bộ của OpenClaw cùng với một nhánh anh em đang hoạt động chứa cùng prompt người dùng hiển thị. Ở chế độ `--fix` / `--repair`, doctor sao lưu từng tệp bị ảnh hưởng cạnh tệp gốc và viết lại bản ghi về nhánh đang hoạt động để lịch sử Gateway và các trình đọc bộ nhớ không còn thấy các lượt trùng lặp. + + Doctor quét các tệp JSONL phiên tác tử để tìm cấu trúc nhánh bị nhân đôi do lỗi viết lại bản ghi lời nhắc 2026.4.24 tạo ra: một lượt người dùng bị bỏ lại với ngữ cảnh runtime nội bộ của OpenClaw cùng một nhánh ngang hàng đang hoạt động chứa cùng lời nhắc người dùng hiển thị. Ở chế độ `--fix` / `--repair`, doctor sao lưu từng tệp bị ảnh hưởng bên cạnh tệp gốc và viết lại bản ghi sang nhánh đang hoạt động để lịch sử gateway và các trình đọc bộ nhớ không còn thấy các lượt bị trùng lặp. - - Thư mục trạng thái là thân não vận hành. Nếu nó biến mất, bạn sẽ mất phiên, thông tin xác thực, nhật ký và cấu hình (trừ khi bạn có bản sao lưu ở nơi khác). + + Thư mục trạng thái là trung khu vận hành. Nếu thư mục này biến mất, bạn sẽ mất phiên, thông tin xác thực, nhật ký và cấu hình (trừ khi bạn có bản sao lưu ở nơi khác). Doctor kiểm tra: - - **Thiếu thư mục trạng thái**: cảnh báo về mất trạng thái nghiêm trọng, nhắc tạo lại thư mục, và nhắc bạn rằng công cụ không thể khôi phục dữ liệu bị thiếu. + - **Thiếu thư mục trạng thái**: cảnh báo về mất trạng thái nghiêm trọng, nhắc tạo lại thư mục, và nhắc rằng công cụ không thể khôi phục dữ liệu đã mất. - **Quyền thư mục trạng thái**: xác minh khả năng ghi; đề xuất sửa quyền (và phát gợi ý `chown` khi phát hiện chủ sở hữu/nhóm không khớp). - - **Thư mục trạng thái macOS được đồng bộ qua đám mây**: cảnh báo khi trạng thái được phân giải dưới iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) hoặc `~/Library/CloudStorage/...` vì các đường dẫn dựa trên đồng bộ có thể gây I/O chậm hơn và các cuộc đua khóa/đồng bộ. - - **Thư mục trạng thái Linux SD hoặc eMMC**: cảnh báo khi trạng thái được phân giải tới một nguồn gắn kết `mmcblk*`, vì I/O ngẫu nhiên dựa trên SD hoặc eMMC có thể chậm hơn và hao mòn nhanh hơn khi ghi phiên và thông tin xác thực. - - **Thiếu thư mục phiên**: `sessions/` và thư mục kho phiên là bắt buộc để lưu lịch sử và tránh lỗi sập `ENOENT`. - - **Bản ghi không khớp**: cảnh báo khi các mục phiên gần đây bị thiếu tệp bản ghi. - - **Phiên chính "JSONL 1 dòng"**: đánh dấu khi bản ghi chính chỉ có một dòng (lịch sử không được tích lũy). - - **Nhiều thư mục trạng thái**: cảnh báo khi tồn tại nhiều thư mục `~/.openclaw` trên các thư mục home hoặc khi `OPENCLAW_STATE_DIR` trỏ tới nơi khác (lịch sử có thể bị chia giữa các bản cài đặt). + - **Thư mục trạng thái được đồng bộ đám mây trên macOS**: cảnh báo khi trạng thái phân giải dưới iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) hoặc `~/Library/CloudStorage/...` vì các đường dẫn có đồng bộ hỗ trợ có thể gây I/O chậm hơn và các cuộc đua khóa/đồng bộ. + - **Thư mục trạng thái trên SD hoặc eMMC của Linux**: cảnh báo khi trạng thái phân giải tới nguồn gắn kết `mmcblk*`, vì I/O ngẫu nhiên dựa trên SD hoặc eMMC có thể chậm hơn và hao mòn nhanh hơn khi ghi phiên và thông tin xác thực. + - **Thiếu thư mục phiên**: `sessions/` và thư mục lưu trữ phiên là bắt buộc để duy trì lịch sử và tránh lỗi sập `ENOENT`. + - **Bản ghi không khớp**: cảnh báo khi các mục phiên gần đây thiếu tệp bản ghi. + - **Phiên chính "JSONL 1 dòng"**: gắn cờ khi bản ghi chính chỉ có một dòng (lịch sử không được tích lũy). + - **Nhiều thư mục trạng thái**: cảnh báo khi nhiều thư mục `~/.openclaw` tồn tại trên các thư mục home hoặc khi `OPENCLAW_STATE_DIR` trỏ tới nơi khác (lịch sử có thể bị chia tách giữa các bản cài đặt). - **Nhắc nhở chế độ từ xa**: nếu `gateway.mode=remote`, doctor nhắc bạn chạy công cụ trên máy chủ từ xa (trạng thái nằm ở đó). - - **Quyền tệp cấu hình**: cảnh báo nếu `~/.openclaw/openclaw.json` có thể đọc bởi nhóm/mọi người và đề xuất siết lại thành `600`. + - **Quyền tệp cấu hình**: cảnh báo nếu `~/.openclaw/openclaw.json` có thể đọc bởi nhóm/toàn bộ người dùng và đề xuất siết chặt thành `600`. - Doctor kiểm tra các hồ sơ OAuth trong kho xác thực, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể làm mới chúng khi an toàn. Nếu hồ sơ OAuth/token của Anthropic đã cũ, công cụ đề xuất khóa API Anthropic hoặc đường dẫn setup-token Anthropic. Lời nhắc làm mới chỉ xuất hiện khi chạy tương tác (TTY); `--non-interactive` bỏ qua các lần thử làm mới. + Doctor kiểm tra các hồ sơ OAuth trong kho xác thực, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể làm mới chúng khi an toàn. Nếu hồ sơ OAuth/token Anthropic đã cũ, công cụ đề xuất khóa API Anthropic hoặc đường dẫn setup-token Anthropic. Lời nhắc làm mới chỉ xuất hiện khi chạy tương tác (TTY); `--non-interactive` bỏ qua các lần thử làm mới. - Khi làm mới OAuth thất bại vĩnh viễn (ví dụ `refresh_token_reused`, `invalid_grant`, hoặc nhà cung cấp yêu cầu bạn đăng nhập lại), doctor báo rằng cần xác thực lại và in lệnh `openclaw models auth login --provider ...` chính xác cần chạy. + Khi làm mới OAuth thất bại vĩnh viễn (ví dụ `refresh_token_reused`, `invalid_grant`, hoặc nhà cung cấp yêu cầu bạn đăng nhập lại), doctor báo rằng cần xác thực lại và in chính xác lệnh `openclaw models auth login --provider ...` cần chạy. Doctor cũng báo cáo các hồ sơ xác thực tạm thời không dùng được do: - - thời gian hồi ngắn (giới hạn tốc độ/hết thời gian chờ/lỗi xác thực) + - thời gian chờ ngắn (giới hạn tốc độ/hết thời gian chờ/lỗi xác thực) - vô hiệu hóa lâu hơn (lỗi thanh toán/tín dụng) - - Nếu `hooks.gmail.model` được đặt, doctor xác thực tham chiếu mô hình với catalog và danh sách cho phép, rồi cảnh báo khi nó không phân giải được hoặc không được phép. + + Nếu `hooks.gmail.model` được đặt, doctor xác thực tham chiếu mô hình với catalog và allowlist, đồng thời cảnh báo khi tham chiếu không phân giải được hoặc không được cho phép. - - Khi sandbox được bật, doctor kiểm tra ảnh Docker và đề xuất build hoặc chuyển sang tên cũ nếu ảnh hiện tại bị thiếu. + + Khi sandboxing được bật, doctor kiểm tra ảnh Docker và đề xuất build hoặc chuyển sang tên cũ nếu ảnh hiện tại bị thiếu. - Doctor xóa trạng thái dàn dựng phụ thuộc Plugin do OpenClaw tạo theo kiểu cũ ở chế độ `openclaw doctor --fix` / `openclaw doctor --repair`. Việc này bao gồm các gốc phụ thuộc đã tạo bị cũ, các thư mục giai đoạn cài đặt cũ, và mảnh vụn cục bộ trong package từ mã sửa chữa phụ thuộc Plugin đóng gói trước đây. + Doctor xóa trạng thái staging phụ thuộc Plugin cũ do OpenClaw tạo ở chế độ `openclaw doctor --fix` / `openclaw doctor --repair`. Việc này bao gồm các gốc phụ thuộc được tạo đã cũ, thư mục giai đoạn cài đặt cũ, mảnh vụn cục bộ theo gói từ mã sửa phụ thuộc Plugin đóng gói trước đây, và các bản sao npm được quản lý của Plugin `@openclaw/*` đóng gói bị mồ côi hoặc được khôi phục có thể che khuất manifest đóng gói hiện tại. - Doctor cũng có thể cài đặt lại các Plugin có thể tải xuống đã cấu hình khi cấu hình tham chiếu đến chúng nhưng sổ đăng ký Plugin cục bộ không tìm thấy. Với việc ngoại hóa Plugin đóng gói ngày 2026.5.2, doctor tự động cài đặt các Plugin có thể tải xuống mà cấu hình hiện có đã dùng, rồi dựa vào `meta.lastTouchedVersion` để chỉ chạy lượt phát hành đó một lần. Khởi động Gateway và tải lại cấu hình không chạy trình quản lý package; cài đặt Plugin vẫn là công việc doctor/install/update rõ ràng. + Doctor cũng có thể cài đặt lại các Plugin có thể tải xuống đã cấu hình khi cấu hình tham chiếu chúng nhưng registry Plugin cục bộ không tìm thấy. Với việc tách Plugin đóng gói ra ngoài trong 2026.5.2, doctor tự động cài đặt các Plugin có thể tải xuống mà cấu hình hiện có đã dùng, rồi dựa vào `meta.lastTouchedVersion` để chỉ chạy lượt phát hành đó một lần. Khởi động Gateway và tải lại cấu hình không chạy trình quản lý gói; cài đặt Plugin vẫn là công việc rõ ràng của doctor/install/update. - - Doctor phát hiện các dịch vụ Gateway kiểu cũ (launchd/systemd/schtasks) và đề xuất xóa chúng rồi cài đặt dịch vụ OpenClaw bằng cổng Gateway hiện tại. Công cụ cũng có thể quét các dịch vụ giống Gateway thừa và in gợi ý dọn dẹp. Các dịch vụ Gateway OpenClaw có tên theo hồ sơ được xem là hạng nhất và không bị đánh dấu là "thừa." + + Doctor phát hiện các dịch vụ gateway cũ (launchd/systemd/schtasks) và đề xuất xóa chúng rồi cài đặt dịch vụ OpenClaw bằng cổng Gateway hiện tại. Công cụ cũng có thể quét các dịch vụ giống gateway bổ sung và in gợi ý dọn dẹp. Các dịch vụ Gateway OpenClaw có tên theo hồ sơ được xem là hạng nhất và không bị gắn cờ là "bổ sung." - Trên Linux, nếu thiếu dịch vụ Gateway cấp người dùng nhưng có một dịch vụ Gateway OpenClaw cấp hệ thống, doctor không tự động cài đặt dịch vụ cấp người dùng thứ hai. Kiểm tra bằng `openclaw gateway status --deep` hoặc `openclaw doctor --deep`, sau đó xóa bản trùng lặp hoặc đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một trình giám sát hệ thống sở hữu vòng đời Gateway. + Trên Linux, nếu dịch vụ Gateway cấp người dùng bị thiếu nhưng một dịch vụ Gateway OpenClaw cấp hệ thống tồn tại, doctor không tự động cài đặt dịch vụ cấp người dùng thứ hai. Kiểm tra bằng `openclaw gateway status --deep` hoặc `openclaw doctor --deep`, rồi xóa bản trùng lặp hoặc đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một supervisor hệ thống sở hữu vòng đời Gateway. - - Khi tài khoản kênh Matrix có một di chuyển trạng thái cũ đang chờ hoặc có thể thực hiện, doctor (ở chế độ `--fix` / `--repair`) tạo một ảnh chụp nhanh trước di chuyển rồi chạy các bước di chuyển nỗ lực tối đa: di chuyển trạng thái Matrix cũ và chuẩn bị trạng thái mã hóa cũ. Cả hai bước đều không gây lỗi nghiêm trọng; lỗi được ghi nhật ký và quá trình khởi động tiếp tục. Ở chế độ chỉ đọc (`openclaw doctor` không có `--fix`), kiểm tra này bị bỏ qua hoàn toàn. + + Khi tài khoản kênh Matrix có di trú trạng thái cũ đang chờ hoặc có thể thực hiện, doctor (ở chế độ `--fix` / `--repair`) tạo ảnh chụp trước di trú rồi chạy các bước di trú nỗ lực tối đa: di trú trạng thái Matrix cũ và chuẩn bị trạng thái mã hóa cũ. Cả hai bước đều không gây lỗi nghiêm trọng; lỗi được ghi nhật ký và quá trình khởi động tiếp tục. Ở chế độ chỉ đọc (`openclaw doctor` không có `--fix`), kiểm tra này bị bỏ qua hoàn toàn. Doctor hiện kiểm tra trạng thái ghép nối thiết bị như một phần của lượt kiểm tra sức khỏe thông thường. @@ -370,125 +370,125 @@ Lệnh đó đưa các ứng viên bền vững có căn cứ vào kho dreaming Nội dung được báo cáo: - yêu cầu ghép nối lần đầu đang chờ - - nâng cấp vai trò đang chờ cho các thiết bị đã ghép nối - - nâng cấp phạm vi đang chờ cho các thiết bị đã ghép nối - - sửa chữa không khớp khóa công khai khi id thiết bị vẫn khớp nhưng danh tính thiết bị không còn khớp với bản ghi đã phê duyệt - - bản ghi đã ghép nối thiếu token đang hoạt động cho một vai trò đã phê duyệt - - token đã ghép nối có phạm vi lệch khỏi đường cơ sở ghép nối đã phê duyệt - - các mục token thiết bị được lưu đệm cục bộ cho máy hiện tại có trước một lần xoay token phía Gateway hoặc mang metadata phạm vi cũ + - nâng cấp vai trò đang chờ cho thiết bị đã ghép nối + - nâng cấp phạm vi đang chờ cho thiết bị đã ghép nối + - sửa lỗi khóa công khai không khớp khi id thiết bị vẫn khớp nhưng danh tính thiết bị không còn khớp với bản ghi đã phê duyệt + - bản ghi đã ghép nối thiếu token đang hoạt động cho vai trò đã phê duyệt + - token đã ghép nối có phạm vi lệch khỏi baseline ghép nối đã phê duyệt + - mục token thiết bị được lưu đệm cục bộ cho máy hiện tại có trước lần xoay vòng token phía gateway hoặc mang metadata phạm vi đã cũ - Doctor không tự động phê duyệt yêu cầu ghép nối hoặc tự động xoay token thiết bị. Thay vào đó, công cụ in các bước tiếp theo chính xác: + Doctor không tự động phê duyệt yêu cầu ghép nối hoặc tự động xoay vòng token thiết bị. Công cụ in chính xác các bước tiếp theo thay vào đó: - kiểm tra yêu cầu đang chờ bằng `openclaw devices list` - phê duyệt yêu cầu chính xác bằng `openclaw devices approve ` - - xoay token mới bằng `openclaw devices rotate --device --role ` + - xoay vòng token mới bằng `openclaw devices rotate --device --role ` - xóa và phê duyệt lại bản ghi cũ bằng `openclaw devices remove ` - Điều này khép lại lỗ hổng phổ biến "đã ghép nối nhưng vẫn bị yêu cầu ghép nối": doctor hiện phân biệt ghép nối lần đầu với nâng cấp vai trò/phạm vi đang chờ và với độ lệch token/danh tính thiết bị cũ. + Việc này khép lại lỗ hổng phổ biến "đã ghép nối nhưng vẫn bị yêu cầu ghép nối": doctor hiện phân biệt ghép nối lần đầu với nâng cấp vai trò/phạm vi đang chờ và với lệch token/danh tính thiết bị đã cũ. - Doctor phát cảnh báo khi một nhà cung cấp mở cho tin nhắn trực tiếp mà không có danh sách cho phép, hoặc khi một chính sách được cấu hình theo cách nguy hiểm. + Doctor phát cảnh báo khi một nhà cung cấp mở DM mà không có allowlist, hoặc khi một chính sách được cấu hình theo cách nguy hiểm. - Nếu chạy như một dịch vụ người dùng systemd, doctor đảm bảo linger được bật để Gateway tiếp tục chạy sau khi đăng xuất. + Nếu đang chạy dưới dạng dịch vụ người dùng systemd, doctor đảm bảo linger được bật để gateway vẫn hoạt động sau khi đăng xuất. - Doctor in tóm tắt trạng thái workspace cho agent mặc định: + Doctor in bản tóm tắt trạng thái workspace cho tác tử mặc định: - - **Trạng thái Skills**: đếm các Skills đủ điều kiện, thiếu yêu cầu và bị chặn bởi danh sách cho phép. - - **Thư mục workspace cũ**: cảnh báo khi `~/openclaw` hoặc các thư mục workspace cũ khác tồn tại cạnh workspace hiện tại. - - **Trạng thái Plugin**: đếm Plugin đã bật/đã tắt/lỗi; liệt kê ID Plugin cho mọi lỗi; báo cáo khả năng của Plugin gói. - - **Cảnh báo tương thích Plugin**: đánh dấu các Plugin có vấn đề tương thích với runtime hiện tại. - - **Chẩn đoán Plugin**: hiển thị mọi cảnh báo hoặc lỗi lúc tải do sổ đăng ký Plugin phát ra. + - **Trạng thái Skills**: đếm các skill đủ điều kiện, thiếu yêu cầu và bị allowlist chặn. + - **Thư mục workspace cũ**: cảnh báo khi `~/openclaw` hoặc các thư mục workspace cũ khác tồn tại bên cạnh workspace hiện tại. + - **Trạng thái Plugin**: đếm Plugin đã bật/đã tắt/có lỗi; liệt kê ID Plugin cho mọi lỗi; báo cáo khả năng của Plugin đóng gói. + - **Cảnh báo tương thích Plugin**: gắn cờ các Plugin có vấn đề tương thích với runtime hiện tại. + - **Chẩn đoán Plugin**: hiển thị mọi cảnh báo hoặc lỗi tại thời điểm tải do registry Plugin phát ra. - Doctor kiểm tra liệu các tệp bootstrap workspace (ví dụ `AGENTS.md`, `CLAUDE.md`, hoặc các tệp ngữ cảnh được tiêm khác) có gần hoặc vượt ngân sách ký tự đã cấu hình hay không. Công cụ báo cáo số ký tự thô so với đã tiêm theo từng tệp, phần trăm cắt ngắn, nguyên nhân cắt ngắn (`max/file` hoặc `max/total`), và tổng số ký tự đã tiêm dưới dạng tỷ lệ của tổng ngân sách. Khi tệp bị cắt ngắn hoặc gần giới hạn, doctor in mẹo điều chỉnh `agents.defaults.bootstrapMaxChars` và `agents.defaults.bootstrapTotalMaxChars`. + Doctor kiểm tra xem các tệp bootstrap workspace (ví dụ `AGENTS.md`, `CLAUDE.md`, hoặc các tệp ngữ cảnh được chèn khác) có gần hoặc vượt ngân sách ký tự đã cấu hình hay không. Công cụ báo cáo số ký tự thô so với đã chèn theo từng tệp, phần trăm cắt bớt, nguyên nhân cắt bớt (`max/file` hoặc `max/total`), và tổng ký tự đã chèn như một phần của tổng ngân sách. Khi tệp bị cắt bớt hoặc gần giới hạn, doctor in mẹo để tinh chỉnh `agents.defaults.bootstrapMaxChars` và `agents.defaults.bootstrapTotalMaxChars`. - - Khi `openclaw doctor --fix` xóa một Plugin kênh bị thiếu, công cụ cũng xóa cấu hình trong phạm vi kênh bị treo đã tham chiếu đến Plugin đó: các mục `channels.`, mục tiêu Heartbeat đã đặt tên kênh, và các ghi đè `agents.*.models["/*"]`. Điều này ngăn vòng lặp khởi động Gateway khi runtime kênh đã mất nhưng cấu hình vẫn yêu cầu Gateway bind tới nó. + + Khi `openclaw doctor --fix` xóa một Plugin kênh bị thiếu, công cụ cũng xóa cấu hình theo phạm vi kênh bị treo đã tham chiếu Plugin đó: mục `channels.`, mục tiêu Heartbeat đã đặt tên kênh, và các ghi đè `agents.*.models["/*"]`. Việc này ngăn vòng lặp khởi động Gateway khi runtime kênh đã mất nhưng cấu hình vẫn yêu cầu gateway liên kết với nó. - Doctor kiểm tra liệu tính năng hoàn tất tab đã được cài đặt cho shell hiện tại hay chưa (zsh, bash, fish, hoặc PowerShell): + Doctor kiểm tra xem tính năng hoàn tất bằng phím Tab đã được cài đặt cho shell hiện tại hay chưa (zsh, bash, fish hoặc PowerShell): - Nếu hồ sơ shell dùng mẫu hoàn tất động chậm (`source <(openclaw completion ...)`), doctor nâng cấp nó lên biến thể tệp lưu đệm nhanh hơn. - - Nếu hoàn tất được cấu hình trong hồ sơ nhưng thiếu tệp lưu đệm, doctor tự động tạo lại bộ nhớ đệm. - - Nếu chưa cấu hình hoàn tất, doctor nhắc cài đặt nó (chỉ chế độ tương tác; bỏ qua với `--non-interactive`). + - Nếu hoàn tất được cấu hình trong hồ sơ nhưng tệp cache bị thiếu, doctor tự động tạo lại cache. + - Nếu hoàn toàn chưa cấu hình hoàn tất, doctor nhắc cài đặt (chỉ ở chế độ tương tác; bị bỏ qua với `--non-interactive`). - Chạy `openclaw completion --write-state` để tạo lại bộ nhớ đệm thủ công. + Chạy `openclaw completion --write-state` để tạo lại cache thủ công. Doctor kiểm tra mức sẵn sàng xác thực token Gateway cục bộ. - Nếu chế độ token cần token và không có nguồn token nào tồn tại, doctor đề xuất tạo một token. - - Nếu `gateway.auth.token` do SecretRef quản lý nhưng không khả dụng, doctor cảnh báo và không ghi đè nó bằng bản rõ. - - `openclaw doctor --generate-gateway-token` chỉ buộc tạo khi không cấu hình token SecretRef nào. + - Nếu `gateway.auth.token` do SecretRef quản lý nhưng không khả dụng, doctor cảnh báo và không ghi đè bằng văn bản thuần. + - `openclaw doctor --generate-gateway-token` chỉ ép tạo khi không cấu hình SecretRef token nào. - Một số luồng sửa chữa cần kiểm tra thông tin xác thực đã cấu hình mà không làm suy yếu hành vi runtime fail-fast. + Một số luồng sửa chữa cần kiểm tra thông tin xác thực đã cấu hình mà không làm suy yếu hành vi fail-fast của runtime. - - `openclaw doctor --fix` hiện dùng cùng mô hình tóm tắt SecretRef chỉ đọc như các lệnh nhóm trạng thái cho các sửa chữa cấu hình có mục tiêu. - - Ví dụ: sửa chữa `allowFrom` / `groupAllowFrom` `@username` của Telegram cố gắng dùng thông tin xác thực bot đã cấu hình khi có. - - Nếu token bot Telegram được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại, doctor báo rằng thông tin xác thực đã được cấu hình nhưng không khả dụng và bỏ qua tự động phân giải thay vì sập hoặc báo nhầm token là bị thiếu. + - `openclaw doctor --fix` hiện dùng cùng mô hình tóm tắt SecretRef chỉ đọc như các lệnh họ trạng thái cho những sửa chữa cấu hình có mục tiêu. + - Ví dụ: sửa Telegram `allowFrom` / `groupAllowFrom` `@username` cố gắng dùng thông tin xác thực bot đã cấu hình khi có. + - Nếu token bot Telegram được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại, doctor báo rằng thông tin xác thực đã được cấu hình-nhưng-không-khả dụng và bỏ qua tự động phân giải thay vì bị sập hoặc báo sai rằng token bị thiếu. - Doctor chạy kiểm tra tình trạng và đề nghị khởi động lại Gateway khi có vẻ không khỏe. + Lệnh doctor chạy kiểm tra tình trạng và đề xuất khởi động lại gateway khi có vẻ không khỏe. - Doctor kiểm tra xem nhà cung cấp embedding tìm kiếm bộ nhớ đã cấu hình có sẵn sàng cho tác nhân mặc định hay không. Hành vi phụ thuộc vào backend và nhà cung cấp đã cấu hình: + Lệnh doctor kiểm tra xem nhà cung cấp embedding tìm kiếm bộ nhớ đã cấu hình có sẵn sàng cho agent mặc định hay không. Hành vi phụ thuộc vào backend và nhà cung cấp đã cấu hình: - - **Backend QMD**: thăm dò xem binary `qmd` có khả dụng và có thể khởi động hay không. Nếu không, in hướng dẫn khắc phục bao gồm gói npm và tùy chọn đường dẫn binary thủ công. - - **Nhà cung cấp cục bộ tường minh**: kiểm tra tệp mô hình cục bộ hoặc URL mô hình từ xa/có thể tải xuống được nhận diện. Nếu thiếu, đề xuất chuyển sang nhà cung cấp từ xa. - - **Nhà cung cấp từ xa tường minh** (`openai`, `voyage`, v.v.): xác minh khóa API có trong môi trường hoặc kho xác thực. In gợi ý khắc phục có thể thực hiện nếu bị thiếu. - - **Nhà cung cấp tự động**: kiểm tra khả năng có sẵn của mô hình cục bộ trước, rồi thử từng nhà cung cấp từ xa theo thứ tự tự động chọn. + - **Backend QMD**: thăm dò xem binary `qmd` có sẵn và có thể khởi động hay không. Nếu không, in hướng dẫn khắc phục bao gồm gói npm và tùy chọn đường dẫn binary thủ công. + - **Nhà cung cấp cục bộ tường minh**: kiểm tra tệp mô hình cục bộ hoặc một URL mô hình từ xa/có thể tải xuống được nhận diện. Nếu thiếu, đề xuất chuyển sang nhà cung cấp từ xa. + - **Nhà cung cấp từ xa tường minh** (`openai`, `voyage`, v.v.): xác minh có khóa API trong môi trường hoặc kho xác thực. In gợi ý khắc phục có thể thực hiện nếu thiếu. + - **Nhà cung cấp tự động**: kiểm tra tính sẵn có của mô hình cục bộ trước, sau đó thử từng nhà cung cấp từ xa theo thứ tự tự động chọn. - Khi có kết quả thăm dò Gateway được lưu trong bộ nhớ đệm (Gateway khỏe tại thời điểm kiểm tra), doctor đối chiếu kết quả đó với cấu hình hiển thị được qua CLI và ghi chú mọi sai lệch. Doctor không khởi động lượt ping embedding mới trên đường dẫn mặc định; hãy dùng lệnh trạng thái bộ nhớ sâu khi bạn muốn kiểm tra nhà cung cấp trực tiếp. + Khi có kết quả thăm dò gateway được lưu trong bộ nhớ đệm (gateway khỏe tại thời điểm kiểm tra), doctor đối chiếu chéo kết quả đó với cấu hình nhìn thấy từ CLI và ghi chú mọi điểm không khớp. Doctor không bắt đầu ping embedding mới trên đường dẫn mặc định; hãy dùng lệnh trạng thái bộ nhớ sâu khi bạn muốn kiểm tra nhà cung cấp trực tiếp. - Dùng `openclaw memory status --deep` để xác minh mức sẵn sàng của embedding tại thời gian chạy. + Dùng `openclaw memory status --deep` để xác minh mức sẵn sàng của embedding khi chạy. - Nếu Gateway khỏe, doctor chạy thăm dò trạng thái kênh và báo cáo cảnh báo kèm các bản sửa được đề xuất. + Nếu gateway khỏe, doctor chạy thăm dò trạng thái kênh và báo cáo cảnh báo kèm các cách khắc phục được đề xuất. - - Doctor kiểm tra cấu hình supervisor đã cài đặt (launchd/systemd/schtasks) để tìm các mặc định bị thiếu hoặc lỗi thời (ví dụ: phụ thuộc systemd network-online và độ trễ khởi động lại). Khi phát hiện không khớp, nó đề xuất cập nhật và có thể ghi lại tệp dịch vụ/tác vụ theo các mặc định hiện tại. + + Doctor kiểm tra cấu hình supervisor đã cài đặt (launchd/systemd/schtasks) để tìm các mặc định bị thiếu hoặc lỗi thời (ví dụ: phụ thuộc network-online của systemd và độ trễ khởi động lại). Khi tìm thấy điểm không khớp, nó đề xuất cập nhật và có thể ghi lại tệp service/task theo các mặc định hiện tại. Ghi chú: - - `openclaw doctor` nhắc trước khi ghi lại cấu hình supervisor. + - `openclaw doctor` hỏi trước khi ghi lại cấu hình supervisor. - `openclaw doctor --yes` chấp nhận các lời nhắc sửa chữa mặc định. - - `openclaw doctor --repair` áp dụng các bản sửa được đề xuất mà không nhắc. - - `openclaw doctor --repair --force` ghi đè cấu hình supervisor tùy chỉnh. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` giữ doctor ở chế độ chỉ đọc đối với vòng đời dịch vụ Gateway. Nó vẫn báo cáo tình trạng dịch vụ và chạy các sửa chữa không liên quan đến dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ, ghi lại cấu hình supervisor và dọn dẹp dịch vụ kế thừa vì một supervisor bên ngoài sở hữu vòng đời đó. - - Trên Linux, doctor không ghi lại siêu dữ liệu lệnh/entrypoint khi unit Gateway systemd khớp đang hoạt động. Nó cũng bỏ qua các unit bổ sung không hoạt động giống Gateway nhưng không phải kế thừa trong quá trình quét dịch vụ trùng lặp để các tệp dịch vụ đồng hành không tạo nhiễu dọn dẹp. - - Nếu xác thực bằng token yêu cầu token và `gateway.auth.token` do SecretRef quản lý, cài đặt/sửa chữa dịch vụ của doctor xác thực SecretRef nhưng không lưu các giá trị token văn bản thuần đã phân giải vào siêu dữ liệu môi trường dịch vụ supervisor. - - Doctor phát hiện các giá trị môi trường dịch vụ được quản lý bằng `.env`/SecretRef mà các bản cài đặt LaunchAgent, systemd hoặc Windows Scheduled Task cũ hơn đã nhúng nội tuyến và ghi lại siêu dữ liệu dịch vụ để các giá trị đó tải từ nguồn thời gian chạy thay vì định nghĩa supervisor. - - Doctor phát hiện khi lệnh dịch vụ vẫn ghim `--port` cũ sau khi `gateway.port` thay đổi và ghi lại siêu dữ liệu dịch vụ sang cổng hiện tại. - - Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình không phân giải được, doctor chặn đường dẫn cài đặt/sửa chữa kèm hướng dẫn có thể thực hiện. + - `openclaw doctor --repair` áp dụng các cách khắc phục được đề xuất mà không hỏi. + - `openclaw doctor --repair --force` ghi đè các cấu hình supervisor tùy chỉnh. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` giữ doctor ở chế độ chỉ đọc đối với vòng đời dịch vụ gateway. Nó vẫn báo cáo tình trạng dịch vụ và chạy các sửa chữa không thuộc dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ, ghi lại cấu hình supervisor, và dọn dẹp dịch vụ cũ vì một supervisor bên ngoài sở hữu vòng đời đó. + - Trên Linux, doctor không ghi lại metadata lệnh/entrypoint trong khi unit gateway systemd khớp đang hoạt động. Nó cũng bỏ qua các unit bổ sung giống gateway nhưng không hoạt động và không phải legacy trong quá trình quét dịch vụ trùng lặp để các tệp dịch vụ đi kèm không tạo nhiễu dọn dẹp. + - Nếu xác thực bằng token yêu cầu token và `gateway.auth.token` do SecretRef quản lý, thao tác cài đặt/sửa chữa dịch vụ của doctor xác thực SecretRef nhưng không lưu các giá trị token plaintext đã phân giải vào metadata môi trường dịch vụ supervisor. + - Doctor phát hiện các giá trị môi trường dịch vụ được quản lý bằng `.env`/SecretRef mà các bản cài đặt LaunchAgent, systemd hoặc Windows Scheduled Task cũ đã nhúng inline và ghi lại metadata dịch vụ để các giá trị đó tải từ nguồn runtime thay vì định nghĩa supervisor. + - Doctor phát hiện khi lệnh dịch vụ vẫn ghim `--port` cũ sau khi `gateway.port` thay đổi và ghi lại metadata dịch vụ sang cổng hiện tại. + - Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, doctor chặn đường dẫn cài đặt/sửa chữa kèm hướng dẫn có thể thực hiện. - Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, doctor chặn cài đặt/sửa chữa cho đến khi mode được đặt tường minh. - - Với các unit user-systemd trên Linux, kiểm tra sai lệch token của doctor hiện bao gồm cả nguồn `Environment=` và `EnvironmentFile=` khi so sánh siêu dữ liệu xác thực dịch vụ. - - Sửa chữa dịch vụ của Doctor từ chối ghi lại, dừng hoặc khởi động lại dịch vụ Gateway từ binary OpenClaw cũ hơn khi cấu hình được ghi lần cuối bởi phiên bản mới hơn. Xem [Khắc phục sự cố Gateway](/vi/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - - Bạn luôn có thể buộc ghi lại toàn bộ qua `openclaw gateway install --force`. + - Với các unit user-systemd trên Linux, kiểm tra drift token của doctor hiện bao gồm cả nguồn `Environment=` và `EnvironmentFile=` khi so sánh metadata xác thực dịch vụ. + - Các sửa chữa dịch vụ của doctor từ chối ghi lại, dừng hoặc khởi động lại dịch vụ gateway từ binary OpenClaw cũ hơn khi cấu hình được ghi lần cuối bởi phiên bản mới hơn. Xem [khắc phục sự cố Gateway](/vi/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - Bạn luôn có thể buộc ghi lại toàn bộ bằng `openclaw gateway install --force`. - - Doctor kiểm tra thời gian chạy dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã được cài đặt nhưng không thực sự đang chạy. Nó cũng kiểm tra xung đột cổng trên cổng Gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng xảy ra (Gateway đã chạy, đường hầm SSH). + + Doctor kiểm tra runtime dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã được cài đặt nhưng thực tế không chạy. Nó cũng kiểm tra xung đột cổng trên cổng gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng xảy ra (gateway đã chạy, đường hầm SSH). - - Doctor cảnh báo khi dịch vụ Gateway chạy trên Bun hoặc đường dẫn Node do trình quản lý phiên bản quản lý (`nvm`, `fnm`, `volta`, `asdf`, v.v.). Các kênh WhatsApp + Telegram yêu cầu Node, và đường dẫn trình quản lý phiên bản có thể hỏng sau khi nâng cấp vì dịch vụ không tải shell init của bạn. Doctor đề nghị di chuyển sang bản cài đặt Node hệ thống khi có sẵn (Homebrew/apt/choco). + + Doctor cảnh báo khi dịch vụ gateway chạy trên Bun hoặc đường dẫn Node do trình quản lý phiên bản quản lý (`nvm`, `fnm`, `volta`, `asdf`, v.v.). Các kênh WhatsApp + Telegram yêu cầu Node, và đường dẫn trình quản lý phiên bản có thể hỏng sau khi nâng cấp vì dịch vụ không tải init shell của bạn. Doctor đề xuất chuyển sang bản cài đặt Node hệ thống khi có sẵn (Homebrew/apt/choco). - LaunchAgent macOS mới cài đặt hoặc đã sửa chữa dùng PATH hệ thống chuẩn (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) thay vì sao chép PATH shell tương tác, nên Volta, asdf, fnm, pnpm và các thư mục trình quản lý phiên bản khác không thay đổi việc các tiến trình con Node được phân giải. Các dịch vụ Linux vẫn giữ các gốc môi trường tường minh (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) và các thư mục user-bin ổn định, nhưng các thư mục dự phòng trình quản lý phiên bản được đoán chỉ được ghi vào PATH dịch vụ khi các thư mục đó tồn tại trên đĩa. + Các LaunchAgent macOS mới cài đặt hoặc đã sửa chữa dùng PATH hệ thống chuẩn (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) thay vì sao chép PATH của shell tương tác, để Volta, asdf, fnm, pnpm và các thư mục trình quản lý phiên bản khác không thay đổi cách các tiến trình con Node được phân giải. Các dịch vụ Linux vẫn giữ các gốc môi trường tường minh (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) và các thư mục user-bin ổn định, nhưng các thư mục dự phòng trình quản lý phiên bản được suy đoán chỉ được ghi vào PATH dịch vụ khi các thư mục đó tồn tại trên đĩa. - - Doctor lưu mọi thay đổi cấu hình và đóng dấu siêu dữ liệu trình hướng dẫn để ghi lại lần chạy doctor. + + Doctor lưu mọi thay đổi cấu hình và đóng dấu metadata wizard để ghi lại lần chạy doctor. - Doctor đề xuất hệ thống bộ nhớ workspace khi bị thiếu và in mẹo sao lưu nếu workspace chưa nằm trong git. + Doctor đề xuất hệ thống bộ nhớ workspace khi thiếu và in mẹo sao lưu nếu workspace chưa nằm trong git. Xem [/concepts/agent-workspace](/vi/concepts/agent-workspace) để biết hướng dẫn đầy đủ về cấu trúc workspace và sao lưu git (khuyến nghị GitHub hoặc GitLab riêng tư). diff --git a/docs/vi/plugins/plugin-inventory.md b/docs/vi/plugins/plugin-inventory.md index eeee78ffa..f775d2adf 100644 --- a/docs/vi/plugins/plugin-inventory.md +++ b/docs/vi/plugins/plugin-inventory.md @@ -1,20 +1,20 @@ --- read_when: - - Bạn đang quyết định liệu một Plugin có được phân phối trong gói npm cốt lõi hay được cài đặt riêng - - Bạn đang cập nhật siêu dữ liệu gói Plugin đi kèm hoặc tự động hóa phát hành - - Bạn cần danh sách chuẩn về Plugin nội bộ và bên ngoài -summary: Bản kiểm kê đã tạo về các Plugin OpenClaw được phân phối trong lõi, được phát hành bên ngoài, hoặc chỉ được giữ dưới dạng mã nguồn + - Bạn đang quyết định liệu một Plugin có được phân phối trong gói npm lõi hay được cài đặt riêng hay không + - Bạn đang cập nhật siêu dữ liệu gói Plugin được đóng gói kèm hoặc tự động hóa phát hành + - Bạn cần danh sách chuẩn về Plugin nội bộ và Plugin bên ngoài +summary: Bản kiểm kê được tạo về các Plugin OpenClaw được phân phối trong lõi, phát hành bên ngoài hoặc chỉ giữ ở dạng mã nguồn title: Danh mục Plugin x-i18n: - generated_at: "2026-05-03T10:39:53Z" + generated_at: "2026-05-04T09:37:19Z" model: gpt-5.5 provider: openai - source_hash: 2099d8a67847f54040db332287708a1f79aa6c08e6e33125425389fe962865cb + source_hash: 64f3d27ae65faacf89deeaad1b456318fa72993fdcf16262f30fb3f48b898024 source_path: plugins/plugin-inventory.md workflow: 16 --- -# Bản kiểm kê Plugin +# Kho Plugin Trang này được tạo từ `extensions/*/package.json`, `openclaw.plugin.json`, và các loại trừ `files` của gói npm gốc. Tạo lại bằng: @@ -25,140 +25,160 @@ pnpm plugins:inventory:gen ## Định nghĩa -- **Gói npm lõi:** được tích hợp vào gói npm `openclaw` và khả dụng mà không cần cài Plugin riêng. -- **Gói bên ngoài chính thức:** Plugin do OpenClaw duy trì, được loại khỏi gói npm lõi, được giữ trong bản kiểm kê chính thức này, và được cài theo nhu cầu thông qua ClawHub và/hoặc npm. -- **Chỉ checkout mã nguồn:** Plugin cục bộ trong repo, được loại khỏi các tạo tác npm đã phát hành và không được quảng bá như một gói có thể cài đặt. +- **Gói npm lõi:** được tích hợp vào gói npm `openclaw` và có sẵn mà không cần cài Plugin riêng. +- **Gói bên ngoài chính thức:** Plugin do OpenClaw duy trì, bị loại khỏi gói npm lõi, được giữ trong kho chính thức này, và được cài đặt theo yêu cầu thông qua ClawHub và/hoặc npm. +- **Chỉ checkout mã nguồn:** Plugin cục bộ trong repo, bị loại khỏi các artifact npm đã phát hành và không được quảng bá như một gói có thể cài đặt. Checkout mã nguồn khác với cài đặt npm: sau `pnpm install`, các -Plugin đi kèm được tải từ `extensions/` để các chỉnh sửa cục bộ và phụ thuộc workspace cục bộ theo gói -có sẵn. +Plugin đi kèm được tải từ `extensions/` để các chỉnh sửa cục bộ và +phụ thuộc workspace cục bộ của gói có sẵn. + +## Cài đặt Plugin + +Dùng cột **Phân phối** để quyết định có cần cài đặt hay không. Các Plugin ghi +`included in OpenClaw` đã có sẵn trong gói lõi. Các gói bên ngoài chính thức +cần cài đặt một lần, sau đó khởi động lại Gateway. + +Ví dụ, Discord là một gói bên ngoài chính thức: + +```bash +openclaw plugins install @openclaw/discord +openclaw gateway restart +openclaw plugins inspect discord --runtime --json +``` + +Thông số gói dạng trần sẽ thử ClawHub trước, rồi fallback sang npm. Để ép dùng +một nguồn, hãy dùng `clawhub:@openclaw/discord` hoặc `npm:@openclaw/discord`. Sau khi cài đặt, hãy làm theo +tài liệu thiết lập của Plugin, chẳng hạn [Discord](/vi/channels/discord), để thêm thông tin xác thực +và cấu hình kênh. Xem [Quản lý Plugin](/vi/plugins/manage-plugins) để biết các lệnh cập nhật, +gỡ cài đặt, và phát hành. ## Gói npm lõi -| Plugin | Mô tả | Phân phối | Bề mặt | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [alibaba](/vi/plugins/reference/alibaba) | Thêm hỗ trợ nhà cung cấp tạo video. | `@openclaw/alibaba-provider`
được bao gồm trong OpenClaw | hợp đồng: videoGenerationProviders | -| [amazon-bedrock](/vi/plugins/reference/amazon-bedrock) | Thêm hỗ trợ nhà cung cấp mô hình Amazon Bedrock cho OpenClaw. | `@openclaw/amazon-bedrock-provider`
được bao gồm trong OpenClaw | nhà cung cấp: amazon-bedrock; hợp đồng: memoryEmbeddingProviders | -| [amazon-bedrock-mantle](/vi/plugins/reference/amazon-bedrock-mantle) | Thêm hỗ trợ nhà cung cấp mô hình Amazon Bedrock Mantle cho OpenClaw. | `@openclaw/amazon-bedrock-mantle-provider`
được bao gồm trong OpenClaw | nhà cung cấp: amazon-bedrock-mantle | -| [anthropic](/vi/plugins/reference/anthropic) | Thêm hỗ trợ nhà cung cấp mô hình Anthropic cho OpenClaw. | `@openclaw/anthropic-provider`
được bao gồm trong OpenClaw | nhà cung cấp: anthropic; hợp đồng: mediaUnderstandingProviders | -| [anthropic-vertex](/vi/plugins/reference/anthropic-vertex) | Thêm hỗ trợ nhà cung cấp mô hình Anthropic Vertex cho OpenClaw. | `@openclaw/anthropic-vertex-provider`
được bao gồm trong OpenClaw | nhà cung cấp: anthropic-vertex | -| [arcee](/vi/plugins/reference/arcee) | Thêm hỗ trợ nhà cung cấp mô hình Arcee cho OpenClaw. | `@openclaw/arcee-provider`
được bao gồm trong OpenClaw | nhà cung cấp: arcee | -| [azure-speech](/vi/plugins/reference/azure-speech) | Azure AI Speech chuyển văn bản thành giọng nói (MP3, ghi chú thoại Ogg/Opus gốc, thoại PCM). | `@openclaw/azure-speech`
được bao gồm trong OpenClaw | hợp đồng: speechProviders | -| [bonjour](/vi/plugins/reference/bonjour) | Quảng bá Gateway OpenClaw cục bộ qua Bonjour/mDNS. | `@openclaw/bonjour`
được bao gồm trong OpenClaw | Plugin | -| [browser](/vi/plugins/reference/browser) | Thêm các công cụ mà agent có thể gọi. | `@openclaw/browser-plugin`
được bao gồm trong OpenClaw | hợp đồng: tools; Skills | -| [byteplus](/vi/plugins/reference/byteplus) | Thêm hỗ trợ nhà cung cấp mô hình BytePlus, BytePlus Plan cho OpenClaw. | `@openclaw/byteplus-provider`
được bao gồm trong OpenClaw | nhà cung cấp: byteplus, byteplus-plan; hợp đồng: videoGenerationProviders | -| [cerebras](/vi/plugins/reference/cerebras) | Thêm hỗ trợ nhà cung cấp mô hình Cerebras cho OpenClaw. | `@openclaw/cerebras-provider`
được bao gồm trong OpenClaw | nhà cung cấp: cerebras | -| [chutes](/vi/plugins/reference/chutes) | Thêm hỗ trợ nhà cung cấp mô hình Chutes cho OpenClaw. | `@openclaw/chutes-provider`
được bao gồm trong OpenClaw | nhà cung cấp: chutes | -| [cloudflare-ai-gateway](/vi/plugins/reference/cloudflare-ai-gateway) | Thêm hỗ trợ nhà cung cấp mô hình Cloudflare AI Gateway cho OpenClaw. | `@openclaw/cloudflare-ai-gateway-provider`
được bao gồm trong OpenClaw | nhà cung cấp: cloudflare-ai-gateway | -| [comfy](/vi/plugins/reference/comfy) | Thêm hỗ trợ nhà cung cấp mô hình ComfyUI cho OpenClaw. | `@openclaw/comfy-provider`
được bao gồm trong OpenClaw | nhà cung cấp: comfy; hợp đồng: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders | -| [copilot-proxy](/vi/plugins/reference/copilot-proxy) | Thêm hỗ trợ nhà cung cấp mô hình Copilot Proxy cho OpenClaw. | `@openclaw/copilot-proxy`
được bao gồm trong OpenClaw | nhà cung cấp: copilot-proxy | -| [deepgram](/vi/plugins/reference/deepgram) | Thêm hỗ trợ nhà cung cấp hiểu phương tiện. Thêm hỗ trợ nhà cung cấp phiên âm thời gian thực. | `@openclaw/deepgram-provider`
được bao gồm trong OpenClaw | hợp đồng: mediaUnderstandingProviders, realtimeTranscriptionProviders | -| [deepinfra](/vi/plugins/reference/deepinfra) | Thêm hỗ trợ nhà cung cấp mô hình DeepInfra cho OpenClaw. | `@openclaw/deepinfra-provider`
được bao gồm trong OpenClaw | nhà cung cấp: deepinfra; hợp đồng: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders | -| [deepseek](/vi/plugins/reference/deepseek) | Thêm hỗ trợ nhà cung cấp mô hình DeepSeek cho OpenClaw. | `@openclaw/deepseek-provider`
được bao gồm trong OpenClaw | nhà cung cấp: deepseek | -| [document-extract](/vi/plugins/reference/document-extract) | Trích xuất văn bản và ảnh trang dự phòng từ các tệp đính kèm tài liệu cục bộ. | `@openclaw/document-extract-plugin`
được bao gồm trong OpenClaw | hợp đồng: documentExtractors | -| [duckduckgo](/vi/plugins/reference/duckduckgo) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/duckduckgo-plugin`
được bao gồm trong OpenClaw | contracts: webSearchProviders | -| [elevenlabs](/vi/plugins/reference/elevenlabs) | Thêm hỗ trợ nhà cung cấp hiểu nội dung đa phương tiện. Thêm hỗ trợ nhà cung cấp phiên âm thời gian thực. Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/elevenlabs-speech`
được bao gồm trong OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders | -| [exa](/vi/plugins/reference/exa) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/exa-plugin`
được bao gồm trong OpenClaw | contracts: webSearchProviders | -| [fal](/vi/plugins/reference/fal) | Thêm hỗ trợ nhà cung cấp mô hình fal cho OpenClaw. | `@openclaw/fal-provider`
được bao gồm trong OpenClaw | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders | -| [file-transfer](/vi/plugins/reference/file-transfer) | Tìm nạp, liệt kê và ghi tệp trên các Node đã ghép đôi thông qua các lệnh Node chuyên dụng. Bỏ qua việc cắt ngắn stdout của bash bằng cách dùng base64 qua node.invoke cho tệp nhị phân lên đến 16 MB. | `@openclaw/file-transfer`
được bao gồm trong OpenClaw | contracts: tools | -| [firecrawl](/vi/plugins/reference/firecrawl) | Thêm các công cụ mà tác tử có thể gọi. Thêm hỗ trợ nhà cung cấp tìm nạp web. Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/firecrawl-plugin`
được bao gồm trong OpenClaw | contracts: tools, webFetchProviders, webSearchProviders | -| [fireworks](/vi/plugins/reference/fireworks) | Thêm hỗ trợ nhà cung cấp mô hình Fireworks cho OpenClaw. | `@openclaw/fireworks-provider`
được bao gồm trong OpenClaw | providers: fireworks | -| [github-copilot](/vi/plugins/reference/github-copilot) | Thêm hỗ trợ nhà cung cấp mô hình GitHub Copilot cho OpenClaw. | `@openclaw/github-copilot-provider`
được bao gồm trong OpenClaw | providers: github-copilot; contracts: memoryEmbeddingProviders | -| [google](/vi/plugins/reference/google) | Thêm hỗ trợ nhà cung cấp mô hình Google, Google Gemini CLI, Google Vertex cho OpenClaw. | `@openclaw/google-plugin`
được bao gồm trong OpenClaw | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders | -| [gradium](/vi/plugins/reference/gradium) | Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/gradium-speech`
được bao gồm trong OpenClaw | contracts: speechProviders | -| [groq](/vi/plugins/reference/groq) | Thêm hỗ trợ nhà cung cấp mô hình Groq cho OpenClaw. | `@openclaw/groq-provider`
được bao gồm trong OpenClaw | providers: groq; contracts: mediaUnderstandingProviders | -| [huggingface](/vi/plugins/reference/huggingface) | Thêm hỗ trợ nhà cung cấp mô hình Hugging Face cho OpenClaw. | `@openclaw/huggingface-provider`
được bao gồm trong OpenClaw | providers: huggingface | -| [imessage](/vi/plugins/reference/imessage) | Thêm giao diện kênh iMessage để gửi và nhận tin nhắn OpenClaw. | `@openclaw/imessage`
được bao gồm trong OpenClaw | channels: imessage | -| [inworld](/vi/plugins/reference/inworld) | Chuyển văn bản thành giọng nói dạng streaming của Inworld (MP3, OGG_OPUS, PCM telephony). | `@openclaw/inworld-speech`
được bao gồm trong OpenClaw | contracts: speechProviders | -| [irc](/vi/plugins/reference/irc) | Thêm giao diện kênh IRC để gửi và nhận tin nhắn OpenClaw. | `@openclaw/irc`
được bao gồm trong OpenClaw | channels: irc | -| [kilocode](/vi/plugins/reference/kilocode) | Thêm hỗ trợ nhà cung cấp mô hình Kilocode cho OpenClaw. | `@openclaw/kilocode-provider`
được bao gồm trong OpenClaw | providers: kilocode | -| [kimi](/vi/plugins/reference/kimi) | Thêm hỗ trợ nhà cung cấp mô hình Kimi, Kimi Coding cho OpenClaw. | `@openclaw/kimi-provider`
được bao gồm trong OpenClaw | providers: kimi, kimi-coding | -| [litellm](/vi/plugins/reference/litellm) | Thêm hỗ trợ nhà cung cấp mô hình LiteLLM cho OpenClaw. | `@openclaw/litellm-provider`
được bao gồm trong OpenClaw | providers: litellm; contracts: imageGenerationProviders | -| [llm-task](/vi/plugins/reference/llm-task) | Công cụ LLM chung chỉ dùng JSON cho các tác vụ có cấu trúc, có thể gọi từ quy trình làm việc. | `@openclaw/llm-task`
được bao gồm trong OpenClaw | contracts: tools | -| [lmstudio](/vi/plugins/reference/lmstudio) | Thêm hỗ trợ nhà cung cấp mô hình LM Studio cho OpenClaw. | `@openclaw/lmstudio-provider`
được bao gồm trong OpenClaw | providers: lmstudio; contracts: memoryEmbeddingProviders | -| [matrix](/vi/plugins/reference/matrix) | Thêm giao diện kênh Matrix để gửi và nhận tin nhắn OpenClaw. | `@openclaw/matrix`
được bao gồm trong OpenClaw | channels: matrix | -| [mattermost](/vi/plugins/reference/mattermost) | Thêm bề mặt kênh Mattermost để gửi và nhận tin nhắn OpenClaw. | `@openclaw/mattermost`
được bao gồm trong OpenClaw | channels: mattermost | -| [memory-core](/vi/plugins/reference/memory-core) | Thêm hỗ trợ nhà cung cấp nhúng bộ nhớ. Thêm các công cụ mà agent có thể gọi. | `@openclaw/memory-core`
được bao gồm trong OpenClaw | contracts: memoryEmbeddingProviders, tools | +| Plugin | Mô tả | Phân phối | Giao diện | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [alibaba](/vi/plugins/reference/alibaba) | Thêm hỗ trợ nhà cung cấp tạo video. | `@openclaw/alibaba-provider`
được bao gồm trong OpenClaw | contracts: videoGenerationProviders | +| [amazon-bedrock](/vi/plugins/reference/amazon-bedrock) | Thêm hỗ trợ nhà cung cấp mô hình Amazon Bedrock cho OpenClaw. | `@openclaw/amazon-bedrock-provider`
được bao gồm trong OpenClaw | providers: amazon-bedrock; contracts: memoryEmbeddingProviders | +| [amazon-bedrock-mantle](/vi/plugins/reference/amazon-bedrock-mantle) | Thêm hỗ trợ nhà cung cấp mô hình Amazon Bedrock Mantle cho OpenClaw. | `@openclaw/amazon-bedrock-mantle-provider`
được bao gồm trong OpenClaw | providers: amazon-bedrock-mantle | +| [anthropic](/vi/plugins/reference/anthropic) | Thêm hỗ trợ nhà cung cấp mô hình Anthropic cho OpenClaw. | `@openclaw/anthropic-provider`
được bao gồm trong OpenClaw | providers: anthropic; contracts: mediaUnderstandingProviders | +| [anthropic-vertex](/vi/plugins/reference/anthropic-vertex) | Thêm hỗ trợ nhà cung cấp mô hình Anthropic Vertex cho OpenClaw. | `@openclaw/anthropic-vertex-provider`
được bao gồm trong OpenClaw | providers: anthropic-vertex | +| [arcee](/vi/plugins/reference/arcee) | Thêm hỗ trợ nhà cung cấp mô hình Arcee cho OpenClaw. | `@openclaw/arcee-provider`
được bao gồm trong OpenClaw | providers: arcee | +| [azure-speech](/vi/plugins/reference/azure-speech) | Chuyển văn bản thành giọng nói bằng Azure AI Speech (MP3, ghi chú thoại Ogg/Opus gốc, thoại PCM). | `@openclaw/azure-speech`
được bao gồm trong OpenClaw | contracts: speechProviders | +| [bonjour](/vi/plugins/reference/bonjour) | Quảng bá Gateway OpenClaw cục bộ qua Bonjour/mDNS. | `@openclaw/bonjour`
được bao gồm trong OpenClaw | plugin | +| [browser](/vi/plugins/reference/browser) | Thêm các công cụ mà tác tử có thể gọi. | `@openclaw/browser-plugin`
được bao gồm trong OpenClaw | contracts: tools; skills | +| [byteplus](/vi/plugins/reference/byteplus) | Thêm hỗ trợ nhà cung cấp mô hình BytePlus, BytePlus Plan cho OpenClaw. | `@openclaw/byteplus-provider`
được bao gồm trong OpenClaw | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders | +| [cerebras](/vi/plugins/reference/cerebras) | Thêm hỗ trợ nhà cung cấp mô hình Cerebras cho OpenClaw. | `@openclaw/cerebras-provider`
được bao gồm trong OpenClaw | providers: cerebras | +| [chutes](/vi/plugins/reference/chutes) | Thêm hỗ trợ nhà cung cấp mô hình Chutes cho OpenClaw. | `@openclaw/chutes-provider`
được bao gồm trong OpenClaw | providers: chutes | +| [cloudflare-ai-gateway](/vi/plugins/reference/cloudflare-ai-gateway) | Thêm hỗ trợ nhà cung cấp mô hình Cloudflare AI Gateway cho OpenClaw. | `@openclaw/cloudflare-ai-gateway-provider`
được bao gồm trong OpenClaw | providers: cloudflare-ai-gateway | +| [comfy](/vi/plugins/reference/comfy) | Thêm hỗ trợ nhà cung cấp mô hình ComfyUI cho OpenClaw. | `@openclaw/comfy-provider`
được bao gồm trong OpenClaw | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders | +| [copilot-proxy](/vi/plugins/reference/copilot-proxy) | Thêm hỗ trợ nhà cung cấp mô hình Copilot Proxy cho OpenClaw. | `@openclaw/copilot-proxy`
được bao gồm trong OpenClaw | providers: copilot-proxy | +| [deepgram](/vi/plugins/reference/deepgram) | Thêm hỗ trợ nhà cung cấp hiểu phương tiện. Thêm hỗ trợ nhà cung cấp phiên âm theo thời gian thực. | `@openclaw/deepgram-provider`
được bao gồm trong OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders | +| [deepinfra](/vi/plugins/reference/deepinfra) | Thêm hỗ trợ nhà cung cấp mô hình DeepInfra cho OpenClaw. | `@openclaw/deepinfra-provider`
được bao gồm trong OpenClaw | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders | +| [deepseek](/vi/plugins/reference/deepseek) | Thêm hỗ trợ nhà cung cấp mô hình DeepSeek cho OpenClaw. | `@openclaw/deepseek-provider`
được bao gồm trong OpenClaw | providers: deepseek | +| [document-extract](/vi/plugins/reference/document-extract) | Trích xuất văn bản và hình ảnh trang dự phòng từ tệp đính kèm tài liệu cục bộ. | `@openclaw/document-extract-plugin`
được bao gồm trong OpenClaw | contracts: documentExtractors | +| [duckduckgo](/vi/plugins/reference/duckduckgo) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/duckduckgo-plugin`
được bao gồm trong OpenClaw | contracts: webSearchProviders | +| [elevenlabs](/vi/plugins/reference/elevenlabs) | Thêm hỗ trợ nhà cung cấp hiểu nội dung media. Thêm hỗ trợ nhà cung cấp phiên âm thời gian thực. Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/elevenlabs-speech`
được bao gồm trong OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders | +| [exa](/vi/plugins/reference/exa) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/exa-plugin`
được bao gồm trong OpenClaw | contracts: webSearchProviders | +| [fal](/vi/plugins/reference/fal) | Thêm hỗ trợ nhà cung cấp mô hình fal cho OpenClaw. | `@openclaw/fal-provider`
được bao gồm trong OpenClaw | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders | +| [file-transfer](/vi/plugins/reference/file-transfer) | Tải, liệt kê và ghi tệp trên các Node đã ghép nối thông qua các lệnh Node chuyên dụng. Bỏ qua việc cắt ngắn stdout của bash bằng cách dùng base64 qua node.invoke cho các tệp nhị phân tối đa 16 MB. | `@openclaw/file-transfer`
được bao gồm trong OpenClaw | contracts: tools | +| [firecrawl](/vi/plugins/reference/firecrawl) | Thêm các công cụ mà agent có thể gọi. Thêm hỗ trợ nhà cung cấp tìm nạp web. Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/firecrawl-plugin`
được bao gồm trong OpenClaw | contracts: tools, webFetchProviders, webSearchProviders | +| [fireworks](/vi/plugins/reference/fireworks) | Thêm hỗ trợ nhà cung cấp mô hình Fireworks cho OpenClaw. | `@openclaw/fireworks-provider`
được bao gồm trong OpenClaw | providers: fireworks | +| [github-copilot](/vi/plugins/reference/github-copilot) | Thêm hỗ trợ nhà cung cấp mô hình GitHub Copilot cho OpenClaw. | `@openclaw/github-copilot-provider`
được bao gồm trong OpenClaw | providers: github-copilot; contracts: memoryEmbeddingProviders | +| [google](/vi/plugins/reference/google) | Thêm hỗ trợ nhà cung cấp mô hình Google, Google Gemini CLI, Google Vertex cho OpenClaw. | `@openclaw/google-plugin`
được bao gồm trong OpenClaw | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders | +| [gradium](/vi/plugins/reference/gradium) | Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/gradium-speech`
được bao gồm trong OpenClaw | contracts: speechProviders | +| [groq](/vi/plugins/reference/groq) | Thêm hỗ trợ nhà cung cấp mô hình Groq cho OpenClaw. | `@openclaw/groq-provider`
được bao gồm trong OpenClaw | providers: groq; contracts: mediaUnderstandingProviders | +| [huggingface](/vi/plugins/reference/huggingface) | Thêm hỗ trợ nhà cung cấp mô hình Hugging Face cho OpenClaw. | `@openclaw/huggingface-provider`
được bao gồm trong OpenClaw | providers: huggingface | +| [imessage](/vi/plugins/reference/imessage) | Thêm bề mặt kênh iMessage để gửi và nhận tin nhắn OpenClaw. | `@openclaw/imessage`
được bao gồm trong OpenClaw | channels: imessage | +| [inworld](/vi/plugins/reference/inworld) | Chuyển văn bản thành giọng nói dạng streaming của Inworld (MP3, OGG_OPUS, PCM telephony). | `@openclaw/inworld-speech`
được bao gồm trong OpenClaw | contracts: speechProviders | +| [irc](/vi/plugins/reference/irc) | Thêm bề mặt kênh IRC để gửi và nhận tin nhắn OpenClaw. | `@openclaw/irc`
được bao gồm trong OpenClaw | channels: irc | +| [kilocode](/vi/plugins/reference/kilocode) | Thêm hỗ trợ nhà cung cấp mô hình Kilocode cho OpenClaw. | `@openclaw/kilocode-provider`
được bao gồm trong OpenClaw | providers: kilocode | +| [kimi](/vi/plugins/reference/kimi) | Thêm hỗ trợ nhà cung cấp mô hình Kimi, Kimi Coding cho OpenClaw. | `@openclaw/kimi-provider`
được bao gồm trong OpenClaw | providers: kimi, kimi-coding | +| [litellm](/vi/plugins/reference/litellm) | Thêm hỗ trợ nhà cung cấp mô hình LiteLLM cho OpenClaw. | `@openclaw/litellm-provider`
được bao gồm trong OpenClaw | providers: litellm; contracts: imageGenerationProviders | +| [llm-task](/vi/plugins/reference/llm-task) | Công cụ LLM chỉ dùng JSON chung cho các tác vụ có cấu trúc, có thể được gọi từ workflow. | `@openclaw/llm-task`
được bao gồm trong OpenClaw | contracts: tools | +| [lmstudio](/vi/plugins/reference/lmstudio) | Thêm hỗ trợ nhà cung cấp mô hình LM Studio cho OpenClaw. | `@openclaw/lmstudio-provider`
được bao gồm trong OpenClaw | providers: lmstudio; contracts: memoryEmbeddingProviders | +| [matrix](/vi/plugins/reference/matrix) | Thêm bề mặt kênh Matrix để gửi và nhận tin nhắn OpenClaw. | `@openclaw/matrix`
được bao gồm trong OpenClaw | channels: matrix | +| [mattermost](/vi/plugins/reference/mattermost) | Thêm giao diện kênh Mattermost để gửi và nhận tin nhắn OpenClaw. | `@openclaw/mattermost`
được bao gồm trong OpenClaw | channels: mattermost | +| [memory-core](/vi/plugins/reference/memory-core) | Thêm hỗ trợ nhà cung cấp embedding bộ nhớ. Thêm các công cụ mà tác tử có thể gọi. | `@openclaw/memory-core`
được bao gồm trong OpenClaw | contracts: memoryEmbeddingProviders, tools | | [memory-wiki](/vi/plugins/reference/memory-wiki) | Trình biên dịch wiki bền vững và kho tri thức thân thiện với Obsidian cho OpenClaw. | `@openclaw/memory-wiki`
được bao gồm trong OpenClaw | contracts: tools; skills | | [microsoft](/vi/plugins/reference/microsoft) | Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/microsoft-speech`
được bao gồm trong OpenClaw | contracts: speechProviders | -| [microsoft-foundry](/vi/plugins/reference/microsoft-foundry) | Thêm hỗ trợ nhà cung cấp mô hình Microsoft Foundry cho OpenClaw. | `@openclaw/microsoft-foundry`
được bao gồm trong OpenClaw | providers: microsoft-foundry | -| [migrate-claude](/vi/plugins/reference/migrate-claude) | Nhập các hướng dẫn Claude Code và Claude Desktop, máy chủ MCP, skills và cấu hình an toàn vào OpenClaw. | `@openclaw/migrate-claude`
được bao gồm trong OpenClaw | contracts: migrationProviders | +| [microsoft-foundry](/vi/plugins/reference/microsoft-foundry) | Thêm hỗ trợ nhà cung cấp mô hình Microsoft Foundry vào OpenClaw. | `@openclaw/microsoft-foundry`
được bao gồm trong OpenClaw | providers: microsoft-foundry | +| [migrate-claude](/vi/plugins/reference/migrate-claude) | Nhập hướng dẫn Claude Code và Claude Desktop, máy chủ MCP, skills và cấu hình an toàn vào OpenClaw. | `@openclaw/migrate-claude`
được bao gồm trong OpenClaw | contracts: migrationProviders | | [migrate-hermes](/vi/plugins/reference/migrate-hermes) | Nhập cấu hình Hermes, bộ nhớ, skills và thông tin xác thực được hỗ trợ vào OpenClaw. | `@openclaw/migrate-hermes`
được bao gồm trong OpenClaw | contracts: migrationProviders | -| [minimax](/vi/plugins/reference/minimax) | Thêm hỗ trợ nhà cung cấp mô hình MiniMax, MiniMax Portal cho OpenClaw. | `@openclaw/minimax-provider`
được bao gồm trong OpenClaw | providers: minimax, minimax-portal; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders, webSearchProviders | -| [mistral](/vi/plugins/reference/mistral) | Thêm hỗ trợ nhà cung cấp mô hình Mistral cho OpenClaw. | `@openclaw/mistral-provider`
được bao gồm trong OpenClaw | providers: mistral; contracts: mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders | -| [moonshot](/vi/plugins/reference/moonshot) | Thêm hỗ trợ nhà cung cấp mô hình Moonshot cho OpenClaw. | `@openclaw/moonshot-provider`
được bao gồm trong OpenClaw | providers: moonshot; contracts: mediaUnderstandingProviders, webSearchProviders | -| [nvidia](/vi/plugins/reference/nvidia) | Thêm hỗ trợ nhà cung cấp mô hình NVIDIA cho OpenClaw. | `@openclaw/nvidia-provider`
được bao gồm trong OpenClaw | providers: nvidia | -| [ollama](/vi/plugins/reference/ollama) | Thêm hỗ trợ nhà cung cấp mô hình Ollama cho OpenClaw. | `@openclaw/ollama-provider`
được bao gồm trong OpenClaw | providers: ollama; contracts: memoryEmbeddingProviders, webSearchProviders | -| [open-prose](/vi/plugins/reference/open-prose) | Gói kỹ năng OpenProse VM với lệnh slash /prose. | `@openclaw/open-prose`
được bao gồm trong OpenClaw | skills | -| [openai](/vi/plugins/reference/openai) | Thêm hỗ trợ nhà cung cấp mô hình OpenAI, OpenAI Codex cho OpenClaw. | `@openclaw/openai-provider`
được bao gồm trong OpenClaw | providers: openai, openai-codex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders | -| [opencode](/vi/plugins/reference/opencode) | Thêm hỗ trợ nhà cung cấp mô hình OpenCode cho OpenClaw. | `@openclaw/opencode-provider`
được bao gồm trong OpenClaw | providers: opencode; contracts: mediaUnderstandingProviders | -| [opencode-go](/vi/plugins/reference/opencode-go) | Thêm hỗ trợ nhà cung cấp mô hình OpenCode Go cho OpenClaw. | `@openclaw/opencode-go-provider`
được bao gồm trong OpenClaw | providers: opencode-go; contracts: mediaUnderstandingProviders | -| [openrouter](/vi/plugins/reference/openrouter) | Thêm hỗ trợ nhà cung cấp mô hình OpenRouter cho OpenClaw. | `@openclaw/openrouter-provider`
được bao gồm trong OpenClaw | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, speechProviders, videoGenerationProviders | -| [openshell](/vi/plugins/reference/openshell) | Backend sandbox do OpenShell vận hành với các workspace cục bộ được phản chiếu và thực thi lệnh dựa trên SSH. | `@openclaw/openshell-sandbox`
được bao gồm trong OpenClaw | plugin | +| [minimax](/vi/plugins/reference/minimax) | Thêm hỗ trợ nhà cung cấp mô hình MiniMax, MiniMax Portal vào OpenClaw. | `@openclaw/minimax-provider`
được bao gồm trong OpenClaw | providers: minimax, minimax-portal; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders, webSearchProviders | +| [mistral](/vi/plugins/reference/mistral) | Thêm hỗ trợ nhà cung cấp mô hình Mistral vào OpenClaw. | `@openclaw/mistral-provider`
được bao gồm trong OpenClaw | providers: mistral; contracts: mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders | +| [moonshot](/vi/plugins/reference/moonshot) | Thêm hỗ trợ nhà cung cấp mô hình Moonshot vào OpenClaw. | `@openclaw/moonshot-provider`
được bao gồm trong OpenClaw | providers: moonshot; contracts: mediaUnderstandingProviders, webSearchProviders | +| [nvidia](/vi/plugins/reference/nvidia) | Thêm hỗ trợ nhà cung cấp mô hình NVIDIA vào OpenClaw. | `@openclaw/nvidia-provider`
được bao gồm trong OpenClaw | providers: nvidia | +| [ollama](/vi/plugins/reference/ollama) | Thêm hỗ trợ nhà cung cấp mô hình Ollama vào OpenClaw. | `@openclaw/ollama-provider`
được bao gồm trong OpenClaw | providers: ollama; contracts: memoryEmbeddingProviders, webSearchProviders | +| [open-prose](/vi/plugins/reference/open-prose) | Gói skill OpenProse VM với lệnh gạch chéo /prose. | `@openclaw/open-prose`
được bao gồm trong OpenClaw | skills | +| [openai](/vi/plugins/reference/openai) | Thêm hỗ trợ nhà cung cấp mô hình OpenAI, OpenAI Codex vào OpenClaw. | `@openclaw/openai-provider`
được bao gồm trong OpenClaw | providers: openai, openai-codex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders | +| [opencode](/vi/plugins/reference/opencode) | Thêm hỗ trợ nhà cung cấp mô hình OpenCode vào OpenClaw. | `@openclaw/opencode-provider`
được bao gồm trong OpenClaw | providers: opencode; contracts: mediaUnderstandingProviders | +| [opencode-go](/vi/plugins/reference/opencode-go) | Thêm hỗ trợ nhà cung cấp mô hình OpenCode Go vào OpenClaw. | `@openclaw/opencode-go-provider`
được bao gồm trong OpenClaw | providers: opencode-go; contracts: mediaUnderstandingProviders | +| [openrouter](/vi/plugins/reference/openrouter) | Thêm hỗ trợ nhà cung cấp mô hình OpenRouter vào OpenClaw. | `@openclaw/openrouter-provider`
được bao gồm trong OpenClaw | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, speechProviders, videoGenerationProviders | +| [openshell](/vi/plugins/reference/openshell) | Backend sandbox do OpenShell cung cấp với không gian làm việc cục bộ được phản chiếu và thực thi lệnh dựa trên SSH. | `@openclaw/openshell-sandbox`
được bao gồm trong OpenClaw | plugin | | [perplexity](/vi/plugins/reference/perplexity) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/perplexity-plugin`
được bao gồm trong OpenClaw | contracts: webSearchProviders | -| [qianfan](/vi/plugins/reference/qianfan) | Thêm hỗ trợ nhà cung cấp mô hình Qianfan cho OpenClaw. | `@openclaw/qianfan-provider`
được bao gồm trong OpenClaw | providers: qianfan | -| [qwen](/vi/plugins/reference/qwen) | Thêm hỗ trợ nhà cung cấp mô hình Qwen, Qwen Cloud, Model Studio, DashScope cho OpenClaw. | `@openclaw/qwen-provider`
được bao gồm trong OpenClaw | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders | -| [runway](/vi/plugins/reference/runway) | Thêm hỗ trợ nhà cung cấp tạo video. | `@openclaw/runway-provider`
đi kèm trong OpenClaw | contracts: videoGenerationProviders | -| [searxng](/vi/plugins/reference/searxng) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/searxng-plugin`
đi kèm trong OpenClaw | contracts: webSearchProviders | -| [senseaudio](/vi/plugins/reference/senseaudio) | Thêm hỗ trợ nhà cung cấp hiểu phương tiện. | `@openclaw/senseaudio-provider`
đi kèm trong OpenClaw | contracts: mediaUnderstandingProviders | -| [sglang](/vi/plugins/reference/sglang) | Thêm hỗ trợ nhà cung cấp mô hình SGLang cho OpenClaw. | `@openclaw/sglang-provider`
đi kèm trong OpenClaw | providers: sglang | -| [signal](/vi/plugins/reference/signal) | Thêm giao diện kênh Signal để gửi và nhận tin nhắn OpenClaw. | `@openclaw/signal`
đi kèm trong OpenClaw | channels: signal | -| [skill-workshop](/vi/plugins/reference/skill-workshop) | Ghi lại các quy trình làm việc có thể lặp lại dưới dạng kỹ năng không gian làm việc, với phần đánh giá đang chờ xử lý, ghi an toàn và làm mới lời nhắc kỹ năng. | `@openclaw/skill-workshop`
đi kèm trong OpenClaw | contracts: tools | -| [slack](/vi/plugins/reference/slack) | Thêm giao diện kênh Slack để gửi và nhận tin nhắn OpenClaw. | `@openclaw/slack`
đi kèm trong OpenClaw | channels: slack | -| [stepfun](/vi/plugins/reference/stepfun) | Thêm hỗ trợ nhà cung cấp mô hình StepFun, StepFun Plan cho OpenClaw. | `@openclaw/stepfun-provider`
đi kèm trong OpenClaw | providers: stepfun, stepfun-plan | -| [synthetic](/vi/plugins/reference/synthetic) | Thêm hỗ trợ nhà cung cấp mô hình Synthetic cho OpenClaw. | `@openclaw/synthetic-provider`
đi kèm trong OpenClaw | providers: synthetic | -| [tavily](/vi/plugins/reference/tavily) | Thêm các công cụ mà tác tử có thể gọi. Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/tavily-plugin`
đi kèm trong OpenClaw | contracts: tools, webSearchProviders; skills | -| [telegram](/vi/plugins/reference/telegram) | Thêm giao diện kênh Telegram để gửi và nhận tin nhắn OpenClaw. | `@openclaw/telegram`
đi kèm trong OpenClaw | channels: telegram | -| [tencent](/vi/plugins/reference/tencent) | Thêm hỗ trợ nhà cung cấp mô hình Tencent TokenHub cho OpenClaw. | `@openclaw/tencent-provider`
đi kèm trong OpenClaw | providers: tencent-tokenhub | -| [together](/vi/plugins/reference/together) | Thêm hỗ trợ nhà cung cấp mô hình Together cho OpenClaw. | `@openclaw/together-provider`
đi kèm trong OpenClaw | providers: together; contracts: videoGenerationProviders | -| [tokenjuice](/vi/plugins/reference/tokenjuice) | Nén kết quả công cụ exec và bash bằng các bộ rút gọn tokenjuice. | `@openclaw/tokenjuice`
đi kèm trong OpenClaw | contracts: agentToolResultMiddleware | -| [tts-local-cli](/vi/plugins/reference/tts-local-cli) | Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/tts-local-cli`
đi kèm trong OpenClaw | contracts: speechProviders | -| [venice](/vi/plugins/reference/venice) | Thêm hỗ trợ nhà cung cấp mô hình Venice cho OpenClaw. | `@openclaw/venice-provider`
đi kèm trong OpenClaw | providers: venice | -| [vercel-ai-gateway](/vi/plugins/reference/vercel-ai-gateway) | Thêm hỗ trợ nhà cung cấp mô hình Vercel AI Gateway cho OpenClaw. | `@openclaw/vercel-ai-gateway-provider`
đi kèm trong OpenClaw | providers: vercel-ai-gateway | -| [vllm](/vi/plugins/reference/vllm) | Thêm hỗ trợ nhà cung cấp mô hình vLLM cho OpenClaw. | `@openclaw/vllm-provider`
đi kèm trong OpenClaw | providers: vllm | -| [volcengine](/vi/plugins/reference/volcengine) | Thêm hỗ trợ nhà cung cấp mô hình Volcengine, Volcengine Plan cho OpenClaw. | `@openclaw/volcengine-provider`
đi kèm trong OpenClaw | providers: volcengine, volcengine-plan; contracts: speechProviders | -| [voyage](/vi/plugins/reference/voyage) | Thêm hỗ trợ nhà cung cấp nhúng bộ nhớ. | `@openclaw/voyage-provider`
đi kèm trong OpenClaw | contracts: memoryEmbeddingProviders | -| [vydra](/vi/plugins/reference/vydra) | Thêm hỗ trợ nhà cung cấp mô hình Vydra cho OpenClaw. | `@openclaw/vydra-provider`
đi kèm trong OpenClaw | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders | +| [qianfan](/vi/plugins/reference/qianfan) | Thêm hỗ trợ nhà cung cấp mô hình Qianfan vào OpenClaw. | `@openclaw/qianfan-provider`
được bao gồm trong OpenClaw | providers: qianfan | +| [qwen](/vi/plugins/reference/qwen) | Thêm hỗ trợ nhà cung cấp mô hình Qwen, Qwen Cloud, Model Studio, DashScope vào OpenClaw. | `@openclaw/qwen-provider`
được bao gồm trong OpenClaw | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders | +| [runway](/vi/plugins/reference/runway) | Thêm hỗ trợ nhà cung cấp tạo video. | `@openclaw/runway-provider`
được bao gồm trong OpenClaw | contracts: videoGenerationProviders | +| [searxng](/vi/plugins/reference/searxng) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/searxng-plugin`
được bao gồm trong OpenClaw | contracts: webSearchProviders | +| [senseaudio](/vi/plugins/reference/senseaudio) | Thêm hỗ trợ nhà cung cấp hiểu phương tiện. | `@openclaw/senseaudio-provider`
được bao gồm trong OpenClaw | contracts: mediaUnderstandingProviders | +| [sglang](/vi/plugins/reference/sglang) | Thêm hỗ trợ nhà cung cấp mô hình SGLang cho OpenClaw. | `@openclaw/sglang-provider`
được bao gồm trong OpenClaw | providers: sglang | +| [signal](/vi/plugins/reference/signal) | Thêm bề mặt kênh Signal để gửi và nhận tin nhắn OpenClaw. | `@openclaw/signal`
được bao gồm trong OpenClaw | channels: signal | +| [skill-workshop](/vi/plugins/reference/skill-workshop) | Ghi lại các quy trình làm việc có thể lặp lại dưới dạng kỹ năng trong workspace, với đánh giá đang chờ, ghi an toàn và làm mới prompt kỹ năng. | `@openclaw/skill-workshop`
được bao gồm trong OpenClaw | contracts: tools | +| [slack](/vi/plugins/reference/slack) | Thêm bề mặt kênh Slack để gửi và nhận tin nhắn OpenClaw. | `@openclaw/slack`
được bao gồm trong OpenClaw | channels: slack | +| [stepfun](/vi/plugins/reference/stepfun) | Thêm hỗ trợ nhà cung cấp mô hình StepFun, StepFun Plan cho OpenClaw. | `@openclaw/stepfun-provider`
được bao gồm trong OpenClaw | providers: stepfun, stepfun-plan | +| [synthetic](/vi/plugins/reference/synthetic) | Thêm hỗ trợ nhà cung cấp mô hình Synthetic cho OpenClaw. | `@openclaw/synthetic-provider`
được bao gồm trong OpenClaw | providers: synthetic | +| [tavily](/vi/plugins/reference/tavily) | Thêm công cụ mà tác nhân có thể gọi. Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/tavily-plugin`
được bao gồm trong OpenClaw | contracts: tools, webSearchProviders; skills | +| [telegram](/vi/plugins/reference/telegram) | Thêm bề mặt kênh Telegram để gửi và nhận tin nhắn OpenClaw. | `@openclaw/telegram`
được bao gồm trong OpenClaw | channels: telegram | +| [tencent](/vi/plugins/reference/tencent) | Thêm hỗ trợ nhà cung cấp mô hình Tencent TokenHub cho OpenClaw. | `@openclaw/tencent-provider`
được bao gồm trong OpenClaw | providers: tencent-tokenhub | +| [together](/vi/plugins/reference/together) | Thêm hỗ trợ nhà cung cấp mô hình Together cho OpenClaw. | `@openclaw/together-provider`
được bao gồm trong OpenClaw | providers: together; contracts: videoGenerationProviders | +| [tokenjuice](/vi/plugins/reference/tokenjuice) | Nén kết quả công cụ exec và bash bằng các bộ rút gọn tokenjuice. | `@openclaw/tokenjuice`
được bao gồm trong OpenClaw | contracts: agentToolResultMiddleware | +| [tts-local-cli](/vi/plugins/reference/tts-local-cli) | Thêm hỗ trợ nhà cung cấp chuyển văn bản thành giọng nói. | `@openclaw/tts-local-cli`
được bao gồm trong OpenClaw | contracts: speechProviders | +| [venice](/vi/plugins/reference/venice) | Thêm hỗ trợ nhà cung cấp mô hình Venice cho OpenClaw. | `@openclaw/venice-provider`
được bao gồm trong OpenClaw | providers: venice | +| [vercel-ai-gateway](/vi/plugins/reference/vercel-ai-gateway) | Thêm hỗ trợ nhà cung cấp mô hình Vercel AI Gateway cho OpenClaw. | `@openclaw/vercel-ai-gateway-provider`
được bao gồm trong OpenClaw | providers: vercel-ai-gateway | +| [vllm](/vi/plugins/reference/vllm) | Thêm hỗ trợ nhà cung cấp mô hình vLLM cho OpenClaw. | `@openclaw/vllm-provider`
được bao gồm trong OpenClaw | providers: vllm | +| [volcengine](/vi/plugins/reference/volcengine) | Thêm hỗ trợ nhà cung cấp mô hình Volcengine, Volcengine Plan cho OpenClaw. | `@openclaw/volcengine-provider`
được bao gồm trong OpenClaw | providers: volcengine, volcengine-plan; contracts: speechProviders | +| [voyage](/vi/plugins/reference/voyage) | Thêm hỗ trợ nhà cung cấp nhúng bộ nhớ. | `@openclaw/voyage-provider`
được bao gồm trong OpenClaw | contracts: memoryEmbeddingProviders | +| [vydra](/vi/plugins/reference/vydra) | Thêm hỗ trợ nhà cung cấp mô hình Vydra cho OpenClaw. | `@openclaw/vydra-provider`
được bao gồm trong OpenClaw | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders | | [web-readability](/vi/plugins/reference/web-readability) | Trích xuất nội dung bài viết dễ đọc từ các phản hồi tìm nạp web HTML cục bộ. | `@openclaw/web-readability-plugin`
được bao gồm trong OpenClaw | contracts: webContentExtractors | -| [webhooks](/vi/plugins/reference/webhooks) | Các webhook đến đã xác thực, liên kết tự động hóa bên ngoài với TaskFlows của OpenClaw. | `@openclaw/webhooks`
được bao gồm trong OpenClaw | plugin | +| [webhooks](/vi/plugins/reference/webhooks) | Webhook đến đã xác thực, liên kết tự động hóa bên ngoài với OpenClaw TaskFlows. | `@openclaw/webhooks`
được bao gồm trong OpenClaw | plugin | | [xai](/vi/plugins/reference/xai) | Thêm hỗ trợ nhà cung cấp mô hình xAI vào OpenClaw. | `@openclaw/xai-plugin`
được bao gồm trong OpenClaw | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders | | [xiaomi](/vi/plugins/reference/xiaomi) | Thêm hỗ trợ nhà cung cấp mô hình Xiaomi vào OpenClaw. | `@openclaw/xiaomi-provider`
được bao gồm trong OpenClaw | providers: xiaomi; contracts: speechProviders | | [zai](/vi/plugins/reference/zai) | Thêm hỗ trợ nhà cung cấp mô hình Z.AI vào OpenClaw. | `@openclaw/zai-provider`
được bao gồm trong OpenClaw | providers: zai; contracts: mediaUnderstandingProviders | ## Các gói bên ngoài chính thức -| Plugin | Mô tả | Phân phối | Bề mặt | -| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -| [acpx](/vi/plugins/reference/acpx) | Backend runtime ACP nhúng với phần quản lý phiên và vận chuyển do plugin sở hữu. | `@openclaw/acpx`
npm; ClawHub | skills | -| [bluebubbles](/vi/plugins/reference/bluebubbles) | Thêm bề mặt kênh BlueBubbles để gửi và nhận tin nhắn OpenClaw. | `@openclaw/bluebubbles`
npm; ClawHub | channels: bluebubbles | -| [brave](/vi/plugins/reference/brave) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/brave-plugin`
npm; ClawHub | contracts: webSearchProviders | -| [codex](/vi/plugins/reference/codex) | Bộ khai thác app-server Codex và danh mục mô hình GPT do Codex quản lý. | `@openclaw/codex`
npm; ClawHub | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders | -| [diagnostics-otel](/vi/plugins/reference/diagnostics-otel) | Trình xuất OpenTelemetry cho chẩn đoán OpenClaw. | `@openclaw/diagnostics-otel`
npm; ClawHub: `clawhub:@openclaw/diagnostics-otel` | plugin | -| [diagnostics-prometheus](/vi/plugins/reference/diagnostics-prometheus) | Trình xuất Prometheus cho chẩn đoán OpenClaw. | `@openclaw/diagnostics-prometheus`
npm; ClawHub: `clawhub:@openclaw/diagnostics-prometheus` | plugin | -| [diffs](/vi/plugins/reference/diffs) | Trình xem diff chỉ đọc và trình kết xuất tệp cho agent. | `@openclaw/diffs`
npm; ClawHub | contracts: tools; skills | -| [discord](/vi/plugins/reference/discord) | Thêm bề mặt kênh Discord để gửi và nhận tin nhắn OpenClaw. | `@openclaw/discord`
npm; ClawHub | channels: discord | -| [feishu](/vi/plugins/reference/feishu) | Thêm bề mặt kênh Feishu để gửi và nhận tin nhắn OpenClaw. | `@openclaw/feishu`
npm; ClawHub | channels: feishu; contracts: tools; skills | -| [google-meet](/vi/plugins/reference/google-meet) | Tham gia cuộc gọi Google Meet thông qua các phương tiện vận chuyển Chrome hoặc Twilio. | `@openclaw/google-meet`
npm; ClawHub | contracts: tools | -| [googlechat](/vi/plugins/reference/googlechat) | Thêm bề mặt kênh Google Chat để gửi và nhận tin nhắn OpenClaw. | `@openclaw/googlechat`
npm; ClawHub | channels: googlechat | -| [line](/vi/plugins/reference/line) | Thêm bề mặt kênh LINE để gửi và nhận tin nhắn OpenClaw. | `@openclaw/line`
npm; ClawHub | channels: line | -| [lobster](/vi/plugins/reference/lobster) | Công cụ quy trình làm việc có kiểu với phê duyệt có thể tiếp tục. | `@openclaw/lobster`
npm; ClawHub | contracts: tools | -| [memory-lancedb](/vi/plugins/reference/memory-lancedb) | Thêm các công cụ mà agent có thể gọi. | `@openclaw/memory-lancedb`
npm; ClawHub | contracts: tools | -| [msteams](/vi/plugins/reference/msteams) | Thêm bề mặt kênh Microsoft Teams để gửi và nhận tin nhắn OpenClaw. | `@openclaw/msteams`
npm; ClawHub | channels: msteams | -| [nextcloud-talk](/vi/plugins/reference/nextcloud-talk) | Thêm bề mặt kênh Nextcloud Talk để gửi và nhận tin nhắn OpenClaw. | `@openclaw/nextcloud-talk`
npm; ClawHub | channels: nextcloud-talk | -| [nostr](/vi/plugins/reference/nostr) | Thêm bề mặt kênh Nostr để gửi và nhận tin nhắn OpenClaw. | `@openclaw/nostr`
npm; ClawHub | channels: nostr | -| [qqbot](/vi/plugins/reference/qqbot) | Thêm bề mặt kênh QQ Bot để gửi và nhận tin nhắn OpenClaw. | `@openclaw/qqbot`
npm; ClawHub | channels: qqbot; contracts: tools; skills | -| [synology-chat](/vi/plugins/reference/synology-chat) | Thêm bề mặt kênh Synology Chat để gửi và nhận tin nhắn OpenClaw. | `@openclaw/synology-chat`
npm; ClawHub | channels: synology-chat | -| [tlon](/vi/plugins/reference/tlon) | Thêm bề mặt kênh Tlon để gửi và nhận tin nhắn OpenClaw. | `@openclaw/tlon`
npm; ClawHub | channels: tlon; contracts: tools; skills | -| [twitch](/vi/plugins/reference/twitch) | Thêm bề mặt kênh Twitch để gửi và nhận tin nhắn OpenClaw. | `@openclaw/twitch`
npm; ClawHub | channels: twitch | -| [voice-call](/vi/plugins/reference/voice-call) | Thêm các công cụ mà agent có thể gọi. | `@openclaw/voice-call`
npm; ClawHub | contracts: tools | -| [whatsapp](/vi/plugins/reference/whatsapp) | Thêm bề mặt kênh WhatsApp để gửi và nhận tin nhắn OpenClaw. | `@openclaw/whatsapp`
npm; ClawHub | channels: whatsapp | -| [zalo](/vi/plugins/reference/zalo) | Thêm bề mặt kênh Zalo để gửi và nhận tin nhắn OpenClaw. | `@openclaw/zalo`
npm; ClawHub | channels: zalo | -| [zalouser](/vi/plugins/reference/zalouser) | Thêm bề mặt kênh Zalo Personal để gửi và nhận tin nhắn OpenClaw. | `@openclaw/zalouser`
npm; ClawHub | channels: zalouser; contracts: tools | +| Plugin | Mô tả | Phân phối | Bề mặt | +| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | +| [acpx](/vi/plugins/reference/acpx) | Phần backend runtime ACP nhúng với quản lý phiên và transport do Plugin sở hữu. | `@openclaw/acpx`
npm; ClawHub | skills | +| [bluebubbles](/vi/plugins/reference/bluebubbles) | Thêm bề mặt kênh BlueBubbles để gửi và nhận tin nhắn OpenClaw. | `@openclaw/bluebubbles`
npm; ClawHub | channels: bluebubbles | +| [brave](/vi/plugins/reference/brave) | Thêm hỗ trợ nhà cung cấp tìm kiếm web. | `@openclaw/brave-plugin`
npm; ClawHub | contracts: webSearchProviders | +| [codex](/vi/plugins/reference/codex) | Bộ harness app-server Codex và danh mục mô hình GPT do Codex quản lý. | `@openclaw/codex`
npm; ClawHub | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders | +| [diagnostics-otel](/vi/plugins/reference/diagnostics-otel) | Trình xuất OpenTelemetry chẩn đoán OpenClaw. | `@openclaw/diagnostics-otel`
npm; ClawHub: `clawhub:@openclaw/diagnostics-otel` | plugin | +| [diagnostics-prometheus](/vi/plugins/reference/diagnostics-prometheus) | Trình xuất Prometheus chẩn đoán OpenClaw. | `@openclaw/diagnostics-prometheus`
npm; ClawHub: `clawhub:@openclaw/diagnostics-prometheus` | plugin | +| [diffs](/vi/plugins/reference/diffs) | Trình xem diff chỉ đọc và trình kết xuất tệp cho các tác nhân. | `@openclaw/diffs`
npm; ClawHub | contracts: tools; skills | +| [discord](/vi/plugins/reference/discord) | Thêm bề mặt kênh Discord để gửi và nhận tin nhắn OpenClaw. | `@openclaw/discord`
npm; ClawHub | channels: discord | +| [feishu](/vi/plugins/reference/feishu) | Thêm bề mặt kênh Feishu để gửi và nhận tin nhắn OpenClaw. | `@openclaw/feishu`
npm; ClawHub | channels: feishu; contracts: tools; skills | +| [google-meet](/vi/plugins/reference/google-meet) | Tham gia cuộc gọi Google Meet thông qua transport Chrome hoặc Twilio. | `@openclaw/google-meet`
npm; ClawHub | contracts: tools | +| [googlechat](/vi/plugins/reference/googlechat) | Thêm bề mặt kênh Google Chat để gửi và nhận tin nhắn OpenClaw. | `@openclaw/googlechat`
npm; ClawHub | channels: googlechat | +| [line](/vi/plugins/reference/line) | Thêm bề mặt kênh LINE để gửi và nhận tin nhắn OpenClaw. | `@openclaw/line`
npm; ClawHub | channels: line | +| [lobster](/vi/plugins/reference/lobster) | Công cụ quy trình làm việc có kiểu với các phê duyệt có thể tiếp tục. | `@openclaw/lobster`
npm; ClawHub | contracts: tools | +| [memory-lancedb](/vi/plugins/reference/memory-lancedb) | Thêm các công cụ mà tác nhân có thể gọi. | `@openclaw/memory-lancedb`
npm; ClawHub | contracts: tools | +| [msteams](/vi/plugins/reference/msteams) | Thêm bề mặt kênh Microsoft Teams để gửi và nhận tin nhắn OpenClaw. | `@openclaw/msteams`
npm; ClawHub | channels: msteams | +| [nextcloud-talk](/vi/plugins/reference/nextcloud-talk) | Thêm bề mặt kênh Nextcloud Talk để gửi và nhận tin nhắn OpenClaw. | `@openclaw/nextcloud-talk`
npm; ClawHub | channels: nextcloud-talk | +| [nostr](/vi/plugins/reference/nostr) | Thêm bề mặt kênh Nostr để gửi và nhận tin nhắn OpenClaw. | `@openclaw/nostr`
npm; ClawHub | channels: nostr | +| [qqbot](/vi/plugins/reference/qqbot) | Thêm bề mặt kênh QQ Bot để gửi và nhận tin nhắn OpenClaw. | `@openclaw/qqbot`
npm; ClawHub | channels: qqbot; contracts: tools; skills | +| [synology-chat](/vi/plugins/reference/synology-chat) | Thêm bề mặt kênh Synology Chat để gửi và nhận tin nhắn OpenClaw. | `@openclaw/synology-chat`
npm; ClawHub | channels: synology-chat | +| [tlon](/vi/plugins/reference/tlon) | Thêm bề mặt kênh Tlon để gửi và nhận tin nhắn OpenClaw. | `@openclaw/tlon`
npm; ClawHub | channels: tlon; contracts: tools; skills | +| [twitch](/vi/plugins/reference/twitch) | Thêm bề mặt kênh Twitch để gửi và nhận tin nhắn OpenClaw. | `@openclaw/twitch`
npm; ClawHub | channels: twitch | +| [voice-call](/vi/plugins/reference/voice-call) | Thêm các công cụ mà tác nhân có thể gọi. | `@openclaw/voice-call`
npm; ClawHub | contracts: tools | +| [whatsapp](/vi/plugins/reference/whatsapp) | Thêm bề mặt kênh WhatsApp để gửi và nhận tin nhắn OpenClaw. | `@openclaw/whatsapp`
npm; ClawHub | channels: whatsapp | +| [zalo](/vi/plugins/reference/zalo) | Thêm bề mặt kênh Zalo để gửi và nhận tin nhắn OpenClaw. | `@openclaw/zalo`
npm; ClawHub | channels: zalo | +| [zalouser](/vi/plugins/reference/zalouser) | Thêm bề mặt kênh Zalo Personal để gửi và nhận tin nhắn OpenClaw. | `@openclaw/zalouser`
npm; ClawHub | channels: zalouser; contracts: tools | ## Chỉ checkout mã nguồn -| Plugin | Mô tả | Phân phối | Bề mặt | -| ------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------ | -------------------- | -| [qa-channel](/vi/plugins/reference/qa-channel) | Thêm bề mặt kênh QA Channel để gửi và nhận tin nhắn OpenClaw. | `@openclaw/qa-channel`
chỉ checkout mã nguồn | channels: qa-channel | -| [qa-lab](/vi/plugins/reference/qa-lab) | Plugin phòng thí nghiệm QA OpenClaw với giao diện debugger riêng và trình chạy kịch bản. | `@openclaw/qa-lab`
chỉ checkout mã nguồn | plugin | -| [qa-matrix](/vi/plugins/reference/qa-matrix) | Trình chạy và nền tảng vận chuyển Matrix QA. | `@openclaw/qa-matrix`
chỉ checkout mã nguồn | plugin | +| Plugin | Mô tả | Phân phối | Bề mặt | +| ------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ | -------------------- | +| [qa-channel](/vi/plugins/reference/qa-channel) | Thêm bề mặt kênh QA Channel để gửi và nhận tin nhắn OpenClaw. | `@openclaw/qa-channel`
chỉ checkout mã nguồn | channels: qa-channel | +| [qa-lab](/vi/plugins/reference/qa-lab) | Plugin phòng thí nghiệm QA của OpenClaw với UI trình gỡ lỗi riêng tư và trình chạy kịch bản. | `@openclaw/qa-lab`
chỉ checkout mã nguồn | plugin | +| [qa-matrix](/vi/plugins/reference/qa-matrix) | Trình chạy và nền tảng transport Matrix QA. | `@openclaw/qa-matrix`
chỉ checkout mã nguồn | plugin | diff --git a/docs/vi/plugins/sdk-runtime.md b/docs/vi/plugins/sdk-runtime.md index f5dab39a1..ccd7d653c 100644 --- a/docs/vi/plugins/sdk-runtime.md +++ b/docs/vi/plugins/sdk-runtime.md @@ -1,21 +1,21 @@ --- read_when: - - Bạn cần gọi các helper lõi từ một Plugin (TTS, STT, tạo hình ảnh, tìm kiếm web, tác nhân phụ, các nút) + - Bạn cần gọi các helper cốt lõi từ một Plugin (TTS, STT, tạo hình ảnh, tìm kiếm web, subagent, Node) - Bạn muốn hiểu api.runtime cung cấp những gì - - Bạn đang truy cập các hàm trợ giúp cấu hình, tác tử hoặc phương tiện từ mã Plugin + - Bạn đang truy cập các hàm trợ giúp về cấu hình, tác tử hoặc phương tiện từ mã Plugin sidebarTitle: Runtime helpers -summary: api.runtime -- các helper runtime được tiêm sẵn có cho các Plugin -title: Trình trợ giúp thời gian chạy của Plugin +summary: api.runtime -- các trình trợ giúp thời gian chạy được chèn có sẵn cho các Plugin +title: Các hàm trợ giúp thời gian chạy của Plugin x-i18n: - generated_at: "2026-05-02T20:57:14Z" + generated_at: "2026-05-04T09:37:15Z" model: gpt-5.5 provider: openai - source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c + source_hash: c968f30052ecba4359bdaa9b1c640c1220268933ce01ccef06bcade225b50b7d source_path: plugins/sdk-runtime.md workflow: 16 --- -Tham chiếu cho đối tượng `api.runtime` được chèn vào mọi Plugin trong quá trình đăng ký. Dùng các helper này thay vì nhập trực tiếp các phần nội bộ của host. +Tham chiếu cho đối tượng `api.runtime` được chèn vào mọi plugin trong quá trình đăng ký. Dùng các helper này thay vì nhập trực tiếp các thành phần nội bộ của host. @@ -32,40 +32,40 @@ register(api) { } ``` -## Tải Và Ghi Cấu Hình +## Tải và ghi cấu hình -Ưu tiên cấu hình đã được truyền vào đường dẫn lệnh gọi đang hoạt động, ví dụ `api.config` trong quá trình đăng ký hoặc đối số `cfg` trên các callback của kênh/nhà cung cấp. Điều này giữ cho một snapshot tiến trình duy nhất đi xuyên suốt công việc thay vì phân tích lại cấu hình trên các đường dẫn nóng. +Ưu tiên cấu hình đã được truyền vào đường dẫn lệnh gọi đang hoạt động, ví dụ `api.config` trong quá trình đăng ký hoặc một đối số `cfg` trên các callback của kênh/nhà cung cấp. Điều này giữ cho một snapshot tiến trình duy nhất đi xuyên suốt công việc thay vì phân tích lại cấu hình trên các đường dẫn nóng. Chỉ dùng `api.runtime.config.current()` khi một handler tồn tại lâu cần snapshot tiến trình hiện tại và không có cấu hình nào được truyền vào hàm đó. Giá trị trả về là chỉ đọc; hãy sao chép hoặc dùng helper đột biến trước khi chỉnh sửa. Các factory công cụ nhận `ctx.runtimeConfig` cùng với `ctx.getRuntimeConfig()`. Dùng getter bên trong callback `execute` của một công cụ tồn tại lâu khi cấu hình có thể thay đổi sau khi định nghĩa công cụ đã được tạo. -Lưu các thay đổi bằng `api.runtime.config.mutateConfigFile(...)` hoặc `api.runtime.config.replaceConfigFile(...)`. Mỗi lần ghi phải chọn một chính sách `afterWrite` rõ ràng: +Lưu thay đổi bằng `api.runtime.config.mutateConfigFile(...)` hoặc `api.runtime.config.replaceConfigFile(...)`. Mỗi lần ghi phải chọn một chính sách `afterWrite` rõ ràng: -- `afterWrite: { mode: "auto" }` để trình quyết định tải lại Gateway xử lý. -- `afterWrite: { mode: "restart", reason: "..." }` buộc khởi động lại sạch khi bên ghi biết tải lại nóng không an toàn. +- `afterWrite: { mode: "auto" }` để bộ quyết định tải lại của Gateway xử lý. +- `afterWrite: { mode: "restart", reason: "..." }` buộc khởi động lại sạch khi trình ghi biết rằng tải lại nóng không an toàn. - `afterWrite: { mode: "none", reason: "..." }` chỉ chặn tự động tải lại/khởi động lại khi bên gọi sở hữu bước tiếp theo. -Các helper đột biến trả về `afterWrite` cùng với bản tóm tắt `followUp` có kiểu để bên gọi có thể ghi log hoặc kiểm thử liệu họ đã yêu cầu khởi động lại hay chưa. Gateway vẫn sở hữu thời điểm việc khởi động lại đó thực sự diễn ra. +Các helper đột biến trả về `afterWrite` cùng với bản tóm tắt `followUp` có kiểu để bên gọi có thể ghi log hoặc kiểm thử xem họ đã yêu cầu khởi động lại hay chưa. Gateway vẫn sở hữu thời điểm việc khởi động lại đó thực sự diễn ra. -`api.runtime.config.loadConfig()` và `api.runtime.config.writeConfigFile(...)` là các helper tương thích đã bị ngừng khuyến nghị dưới `runtime-config-load-write`. Chúng cảnh báo một lần tại runtime và vẫn khả dụng cho các Plugin bên ngoài cũ trong giai đoạn chuyển đổi. Plugin đi kèm không được dùng chúng; các guard ranh giới cấu hình sẽ thất bại nếu mã Plugin gọi chúng hoặc nhập các helper đó từ các subpath SDK Plugin. +`api.runtime.config.loadConfig()` và `api.runtime.config.writeConfigFile(...)` là các helper tương thích đã bị loại bỏ dần dưới `runtime-config-load-write`. Chúng cảnh báo một lần khi chạy và vẫn có sẵn cho các plugin bên ngoài cũ trong giai đoạn chuyển đổi. Các plugin đi kèm không được dùng chúng; các bộ bảo vệ ranh giới cấu hình sẽ thất bại nếu mã plugin gọi chúng hoặc nhập các helper đó từ các đường dẫn con của SDK plugin. -Đối với các lệnh nhập SDK trực tiếp, hãy dùng các subpath cấu hình tập trung thay vì barrel tương thích rộng +Với các import SDK trực tiếp, hãy dùng các đường dẫn con cấu hình tập trung thay vì barrel tương thích rộng `openclaw/plugin-sdk/config-runtime`: `config-types` cho -kiểu, `plugin-config-runtime` cho các xác nhận cấu hình đã tải và tra cứu điểm vào Plugin, -`runtime-config-snapshot` cho snapshot tiến trình hiện tại, và -`config-mutation` cho thao tác ghi. Kiểm thử Plugin đi kèm nên mock trực tiếp các -subpath tập trung này thay vì mock barrel tương thích rộng. +kiểu, `plugin-config-runtime` cho các xác nhận cấu hình đã tải và tra cứu mục +plugin, `runtime-config-snapshot` cho snapshot tiến trình hiện tại, và +`config-mutation` cho thao tác ghi. Kiểm thử plugin đi kèm nên mock trực tiếp các +đường dẫn con tập trung này thay vì mock barrel tương thích rộng. -Mã runtime nội bộ của OpenClaw cũng đi theo cùng hướng: tải cấu hình một lần tại CLI, Gateway hoặc ranh giới tiến trình, rồi truyền giá trị đó xuyên suốt. Các lần ghi đột biến thành công sẽ làm mới snapshot runtime của tiến trình và tăng revision nội bộ của nó; các cache tồn tại lâu nên dùng khóa cache do runtime sở hữu thay vì tuần tự hóa cấu hình cục bộ. Các module runtime tồn tại lâu có scanner không khoan nhượng với các lệnh gọi `loadConfig()` ngầm định; hãy dùng `cfg` được truyền vào, `context.getRuntimeConfig()` của request, hoặc `getRuntimeConfig()` tại một ranh giới tiến trình rõ ràng. +Mã runtime nội bộ của OpenClaw đi theo cùng hướng: tải cấu hình một lần tại ranh giới CLI, Gateway hoặc tiến trình, rồi truyền giá trị đó xuyên suốt. Các lần ghi đột biến thành công sẽ làm mới snapshot runtime của tiến trình và tăng revision nội bộ của nó; các cache tồn tại lâu nên dùng cache key do runtime sở hữu thay vì tự tuần tự hóa cấu hình cục bộ. Các module runtime tồn tại lâu có bộ quét không khoan nhượng đối với các lệnh gọi `loadConfig()` môi trường xung quanh; hãy dùng `cfg` được truyền vào, `context.getRuntimeConfig()` của request, hoặc `getRuntimeConfig()` tại một ranh giới tiến trình rõ ràng. -Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot cấu hình runtime đang hoạt động, không phải snapshot tệp được trả về để đọc lại hoặc chỉnh sửa cấu hình. Snapshot tệp giữ nguyên các giá trị nguồn như marker SecretRef cho UI và thao tác ghi; callback nhà cung cấp cần chế độ xem runtime đã được phân giải. Khi một helper có thể được gọi với snapshot nguồn đang hoạt động hoặc snapshot runtime đang hoạt động, hãy đi qua `selectApplicableRuntimeConfig()` trước khi đọc thông tin xác thực. +Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot cấu hình runtime đang hoạt động, không phải snapshot tệp được trả về để đọc lại hoặc chỉnh sửa cấu hình. Snapshot tệp giữ nguyên các giá trị nguồn như marker SecretRef cho UI và thao tác ghi; callback nhà cung cấp cần góc nhìn runtime đã được phân giải. Khi một helper có thể được gọi bằng snapshot nguồn đang hoạt động hoặc snapshot runtime đang hoạt động, hãy đi qua `selectApplicableRuntimeConfig()` trước khi đọc thông tin xác thực. ## Không gian tên runtime - Danh tính tác nhân, thư mục và quản lý phiên. + Danh tính tác tử, thư mục và quản lý phiên. ```typescript // Resolve the agent's working directory @@ -109,15 +109,15 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot }); ``` - `runEmbeddedAgent(...)` là helper trung lập để bắt đầu một lượt tác nhân OpenClaw bình thường từ mã Plugin. Nó dùng cùng cơ chế phân giải nhà cung cấp/model và lựa chọn agent-harness như các phản hồi được kích hoạt bởi kênh. + `runEmbeddedAgent(...)` là helper trung lập để bắt đầu một lượt tác tử OpenClaw bình thường từ mã plugin. Nó dùng cùng cơ chế phân giải nhà cung cấp/mô hình và chọn agent-harness như các phản hồi được kích hoạt từ kênh. `runEmbeddedPiAgent(...)` vẫn là alias tương thích. - `resolveThinkingPolicy(...)` trả về các mức suy nghĩ được hỗ trợ của nhà cung cấp/model và mặc định tùy chọn. Plugin nhà cung cấp sở hữu hồ sơ riêng cho từng model thông qua các hook thinking của chúng, vì vậy Plugin công cụ nên gọi helper runtime này thay vì nhập hoặc sao chép danh sách nhà cung cấp. + `resolveThinkingPolicy(...)` trả về các mức suy nghĩ được hỗ trợ của nhà cung cấp/mô hình và giá trị mặc định tùy chọn. Plugin nhà cung cấp sở hữu hồ sơ theo mô hình thông qua các hook suy nghĩ của chúng, nên plugin công cụ nên gọi helper runtime này thay vì import hoặc nhân bản danh sách nhà cung cấp. - `normalizeThinkingLevel(...)` chuyển đổi văn bản người dùng như `on`, `x-high` hoặc `extra high` thành mức lưu trữ chuẩn trước khi kiểm tra nó với chính sách đã phân giải. + `normalizeThinkingLevel(...)` chuyển văn bản người dùng như `on`, `x-high`, hoặc `extra high` thành mức lưu trữ chuẩn trước khi kiểm tra nó với chính sách đã phân giải. - **Các helper kho phiên** nằm dưới `api.runtime.agent.session`: + **Các helper kho phiên** nằm trong `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -129,11 +129,11 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId); ``` - Ưu tiên `updateSessionStore(...)` hoặc `updateSessionStoreEntry(...)` cho các thao tác ghi runtime. Chúng đi qua bộ ghi kho phiên do Gateway sở hữu, giữ lại các cập nhật đồng thời và tái sử dụng cache nóng. `saveSessionStore(...)` vẫn khả dụng cho tương thích và các lần ghi lại kiểu bảo trì ngoại tuyến. + Ưu tiên `updateSessionStore(...)` hoặc `updateSessionStoreEntry(...)` cho các thao tác ghi runtime. Chúng đi qua trình ghi kho phiên do Gateway sở hữu, giữ lại các cập nhật đồng thời và tái sử dụng cache nóng. `saveSessionStore(...)` vẫn có sẵn cho tương thích và các lần ghi lại kiểu bảo trì ngoại tuyến. - Hằng số model và nhà cung cấp mặc định: + Hằng số mô hình và nhà cung cấp mặc định: ```typescript const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" @@ -142,7 +142,7 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - Khởi chạy và quản lý các lần chạy subagent nền. + Khởi chạy và quản lý các lượt chạy subagent nền. ```typescript // Start a subagent run @@ -170,14 +170,14 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot ``` - Ghi đè model (`provider`/`model`) yêu cầu operator chọn tham gia qua `plugins.entries..subagent.allowModelOverride: true` trong cấu hình. Plugin không tin cậy vẫn có thể chạy subagent, nhưng các yêu cầu ghi đè sẽ bị từ chối. + Ghi đè mô hình (`provider`/`model`) yêu cầu operator chọn tham gia thông qua `plugins.entries..subagent.allowModelOverride: true` trong cấu hình. Plugin không tin cậy vẫn có thể chạy subagent, nhưng các yêu cầu ghi đè sẽ bị từ chối. - `deleteSession(...)` có thể xóa các phiên được tạo bởi cùng Plugin thông qua `api.runtime.subagent.run(...)`. Xóa phiên tùy ý của người dùng hoặc operator vẫn yêu cầu một request Gateway phạm vi admin. + `deleteSession(...)` có thể xóa các phiên được tạo bởi cùng plugin thông qua `api.runtime.subagent.run(...)`. Việc xóa phiên người dùng hoặc operator tùy ý vẫn yêu cầu request Gateway trong phạm vi admin. - Liệt kê các node đã kết nối và gọi một lệnh do node-host cung cấp từ mã Plugin được Gateway tải hoặc từ các lệnh CLI của Plugin. Dùng điều này khi một Plugin sở hữu công việc cục bộ trên một thiết bị đã ghép đôi, ví dụ cầu nối trình duyệt hoặc âm thanh trên một máy Mac khác. + Liệt kê các node đã kết nối và gọi một lệnh node-host từ mã plugin được Gateway tải hoặc từ các lệnh CLI của plugin. Dùng phần này khi một plugin sở hữu công việc cục bộ trên thiết bị đã ghép đôi, ví dụ cầu nối trình duyệt hoặc âm thanh trên một máy Mac khác. ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -190,13 +190,13 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot }); ``` - Bên trong Gateway, runtime này nằm trong tiến trình. Trong các lệnh CLI của Plugin, nó gọi Gateway đã cấu hình qua RPC, vì vậy các lệnh như `openclaw googlemeet recover-tab` có thể kiểm tra các node đã ghép đôi từ terminal. Các lệnh node vẫn đi qua quá trình ghép đôi node Gateway thông thường, allowlist lệnh, chính sách node-invoke của Plugin và xử lý lệnh cục bộ của node. + Bên trong Gateway, runtime này chạy trong cùng tiến trình. Trong các lệnh CLI plugin, nó gọi Gateway đã cấu hình qua RPC, nên các lệnh như `openclaw googlemeet recover-tab` có thể kiểm tra các node đã ghép đôi từ terminal. Các lệnh node vẫn đi qua quy trình ghép đôi node Gateway thông thường, danh sách cho phép lệnh, chính sách node-invoke của plugin và xử lý lệnh cục bộ trên node. - Plugin phơi bày các lệnh node-host nguy hiểm nên đăng ký một chính sách node-invoke bằng `api.registerNodeInvokePolicy(...)`. Chính sách này chạy trong Gateway sau các bước kiểm tra allowlist lệnh và trước khi lệnh được chuyển tiếp đến node, vì vậy các lệnh gọi `node.invoke` trực tiếp và các công cụ Plugin cấp cao hơn dùng chung cùng đường dẫn thực thi. + Các plugin phơi bày lệnh node-host nguy hiểm nên đăng ký chính sách node-invoke với `api.registerNodeInvokePolicy(...)`. Chính sách chạy trong Gateway sau các bước kiểm tra danh sách cho phép lệnh và trước khi lệnh được chuyển tiếp đến node, vì vậy các lệnh gọi `node.invoke` trực tiếp và công cụ plugin cấp cao hơn dùng chung cùng đường dẫn thực thi. - Ràng buộc runtime Task Flow với một khóa phiên OpenClaw hiện có hoặc ngữ cảnh công cụ tin cậy, rồi tạo và quản lý Task Flow mà không cần truyền owner trong mọi lệnh gọi. + Liên kết runtime luồng tác vụ với một khóa phiên OpenClaw hiện có hoặc ngữ cảnh công cụ đáng tin cậy, rồi tạo và quản lý các luồng tác vụ mà không cần truyền owner trong mọi lệnh gọi. ```typescript const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); @@ -223,7 +223,7 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot }); ``` - Dùng `bindSession({ sessionKey, requesterOrigin })` khi bạn đã có một khóa phiên OpenClaw tin cậy từ lớp ràng buộc của riêng bạn. Không ràng buộc từ đầu vào thô của người dùng. + Dùng `bindSession({ sessionKey, requesterOrigin })` khi bạn đã có khóa phiên OpenClaw đáng tin cậy từ lớp liên kết của riêng mình. Không liên kết từ đầu vào thô của người dùng. @@ -249,7 +249,7 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot }); ``` - Dùng cấu hình `messages.tts` lõi và lựa chọn nhà cung cấp. Trả về bộ đệm âm thanh PCM + tốc độ lấy mẫu. + Dùng cấu hình lõi `messages.tts` và lựa chọn nhà cung cấp. Trả về bộ đệm âm thanh PCM + tốc độ mẫu. @@ -317,7 +317,7 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - Tiện ích media cấp thấp. + Tiện ích phương tiện cấp thấp. ```typescript const webMedia = await api.runtime.media.loadWebMedia(url); @@ -342,8 +342,8 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - Ảnh chụp cấu hình runtime hiện tại và các thao tác ghi cấu hình theo giao dịch. Ưu tiên - cấu hình đã được truyền vào đường dẫn gọi đang hoạt động; chỉ dùng + Ảnh chụp cấu hình runtime hiện tại và thao tác ghi cấu hình theo giao dịch. Ưu tiên + cấu hình đã được truyền vào đường dẫn lệnh gọi đang hoạt động; chỉ dùng `current()` khi handler cần trực tiếp ảnh chụp của tiến trình. ```typescript @@ -356,9 +356,9 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot }); ``` - `mutateConfigFile(...)` và `replaceConfigFile(...)` trả về một giá trị `followUp`, - ví dụ `{ mode: "restart", requiresRestart: true, reason }`, - ghi lại ý định của bên ghi mà không lấy quyền kiểm soát khởi động lại khỏi + `mutateConfigFile(...)` và `replaceConfigFile(...)` trả về một giá trị + `followUp`, ví dụ `{ mode: "restart", requiresRestart: true, reason }`, + ghi lại ý định của bên ghi mà không lấy quyền điều khiển khởi động lại khỏi gateway. @@ -392,7 +392,7 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - Ghi log. + Ghi nhật ký. ```typescript const verbose = api.runtime.logging.shouldLogVerbose(); @@ -413,7 +413,7 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - Phân giải thư mục trạng thái và kho lưu trữ khóa-giá trị dựa trên SQLite. + Phân giải thư mục trạng thái và kho lưu trữ theo khóa dựa trên SQLite. ```typescript const stateDir = api.runtime.state.resolveStateDir(process.env); @@ -424,15 +424,16 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot }); await store.register("key-1", { value: "hello" }); + const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" }); const value = await store.lookup("key-1"); await store.consume("key-1"); await store.clear(); ``` - Kho lưu trữ khóa-giá trị tồn tại qua các lần khởi động lại và được cô lập theo id plugin gắn với runtime. Giới hạn: `maxEntries` cho mỗi namespace, 1.000 hàng đang hoạt động cho mỗi plugin, giá trị JSON dưới 64KB và tùy chọn hết hạn TTL. + Kho lưu trữ theo khóa tồn tại qua các lần khởi động lại và được cô lập theo id Plugin gắn với runtime. Dùng `registerIfAbsent(...)` cho các yêu cầu khử trùng lặp nguyên tử: hàm trả về `true` khi khóa bị thiếu hoặc đã hết hạn và được đăng ký, hoặc `false` khi một giá trị còn hiệu lực đã tồn tại mà không ghi đè giá trị, thời điểm tạo hoặc TTL của nó. Giới hạn: `maxEntries` trên mỗi namespace, 1.000 hàng còn hiệu lực trên mỗi Plugin, giá trị JSON dưới 64KB và tùy chọn hết hạn TTL. - Chỉ dành cho plugin đi kèm trong bản phát hành này. + Chỉ dành cho các Plugin được đóng gói trong bản phát hành này. @@ -447,9 +448,9 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - Helper runtime theo kênh cụ thể (khả dụng khi một plugin kênh được tải). + Helper runtime dành riêng cho kênh (khả dụng khi một Plugin kênh được tải). - `api.runtime.channel.mentions` là bề mặt chính sách nhắc đến đầu vào chung cho các plugin kênh đi kèm dùng runtime injection: + `api.runtime.channel.mentions` là bề mặt chính sách nhắc đến đầu vào dùng chung cho các Plugin kênh được đóng gói có dùng chèn runtime: ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -484,17 +485,17 @@ Các đường dẫn thực thi nhà cung cấp và kênh phải dùng snapshot - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` cố ý không hiển thị các helper tương thích `resolveMentionGating*` cũ hơn. Ưu tiên đường dẫn chuẩn hóa `{ facts, policy }`. + `api.runtime.channel.mentions` cố ý không để lộ các helper tương thích `resolveMentionGating*` cũ hơn. Ưu tiên đường dẫn chuẩn hóa `{ facts, policy }`. ## Lưu trữ tham chiếu runtime -Dùng `createPluginRuntimeStore` để lưu trữ tham chiếu runtime nhằm sử dụng bên ngoài callback `register`: +Dùng `createPluginRuntimeStore` để lưu tham chiếu runtime nhằm sử dụng bên ngoài callback `register`: - + ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; @@ -506,7 +507,7 @@ Dùng `createPluginRuntimeStore` để lưu trữ tham chiếu runtime nhằm s ``` - + ```typescript export default defineChannelPluginEntry({ id: "my-plugin", @@ -517,7 +518,7 @@ Dùng `createPluginRuntimeStore` để lưu trữ tham chiếu runtime nhằm s }); ``` - + ```typescript export function getRuntime() { return store.getRuntime(); // throws if not initialized @@ -532,7 +533,7 @@ Dùng `createPluginRuntimeStore` để lưu trữ tham chiếu runtime nhằm s -Ưu tiên `pluginId` cho danh tính runtime-store. Dạng `key` cấp thấp hơn dành cho các trường hợp không phổ biến khi một plugin cố ý cần nhiều hơn một slot runtime. +Ưu tiên `pluginId` cho định danh runtime-store. Dạng `key` cấp thấp hơn dành cho các trường hợp ít gặp khi một Plugin cố ý cần nhiều hơn một slot runtime. ## Các trường `api` cấp cao khác @@ -540,29 +541,29 @@ Dùng `createPluginRuntimeStore` để lưu trữ tham chiếu runtime nhằm s Ngoài `api.runtime`, đối tượng API cũng cung cấp: - Id plugin. + Id Plugin. - Tên hiển thị của plugin. + Tên hiển thị của Plugin. Ảnh chụp cấu hình hiện tại (ảnh chụp runtime trong bộ nhớ đang hoạt động khi có sẵn). - Cấu hình dành riêng cho plugin từ `plugins.entries..config`. + Cấu hình dành riêng cho Plugin từ `plugins.entries..config`. Logger theo phạm vi (`debug`, `info`, `warn`, `error`). - Chế độ tải hiện tại; `"setup-runtime"` là cửa sổ khởi động/thiết lập nhẹ trước khi vào entry đầy đủ. + Chế độ tải hiện tại; `"setup-runtime"` là cửa sổ khởi động/thiết lập nhẹ trước full-entry. - Phân giải đường dẫn tương đối với gốc plugin. + Phân giải một đường dẫn tương đối với gốc Plugin. ## Liên quan -- [Nội bộ plugin](/vi/plugins/architecture) — mô hình năng lực và registry +- [Nội bộ Plugin](/vi/plugins/architecture) — mô hình năng lực và registry - [Điểm vào SDK](/vi/plugins/sdk-entrypoints) — tùy chọn `definePluginEntry` - [Tổng quan SDK](/vi/plugins/sdk-overview) — tham chiếu subpath diff --git a/docs/vi/tools/trajectory.md b/docs/vi/tools/trajectory.md index 294ee384a..29685579a 100644 --- a/docs/vi/tools/trajectory.md +++ b/docs/vi/tools/trajectory.md @@ -1,37 +1,37 @@ --- read_when: - - Gỡ lỗi lý do một tác nhân đã trả lời, thất bại hoặc gọi công cụ theo một cách nhất định + - Gỡ lỗi lý do tác nhân trả lời, thất bại hoặc gọi công cụ theo một cách nhất định - Xuất gói hỗ trợ cho một phiên OpenClaw - Điều tra ngữ cảnh lời nhắc, lệnh gọi công cụ, lỗi thời gian chạy hoặc siêu dữ liệu sử dụng - - Tắt hoặc di chuyển vị trí ghi lại quỹ đạo -summary: Xuất các gói quỹ đạo đã ẩn thông tin nhạy cảm để gỡ lỗi phiên tác nhân OpenClaw -title: Các gói quỹ đạo + - Tắt hoặc chuyển vị trí lưu bản ghi quỹ đạo +summary: Xuất các gói trajectory đã được che thông tin nhạy cảm để gỡ lỗi phiên tác tử OpenClaw +title: Gói quỹ đạo x-i18n: - generated_at: "2026-04-29T23:22:10Z" + generated_at: "2026-05-04T09:37:12Z" model: gpt-5.5 provider: openai - source_hash: 8dad01b3662d5e75b7626eb7ed3c3ac2dce4e3a7db2ba5952d7086c721151d1f + source_hash: b8b1256e52d27185a48ceddaf7937b4f37ad6d57d075fea0d0b6d3abb871f1d8 source_path: tools/trajectory.md workflow: 16 --- -Ghi lại quỹ đạo là bộ ghi hành trình theo từng phiên của OpenClaw. Nó ghi lại một -dòng thời gian có cấu trúc cho mỗi lượt chạy của agent, sau đó `/export-trajectory` đóng gói -phiên hiện tại thành một gói hỗ trợ đã được biên tập ẩn thông tin nhạy cảm. +Trajectory capture là bộ ghi chuyến bay theo từng phiên của OpenClaw. Nó ghi lại +dòng thời gian có cấu trúc cho mỗi lần chạy tác nhân, sau đó `/export-trajectory` đóng gói +phiên hiện tại thành một gói hỗ trợ đã biên tập. -Dùng tính năng này khi bạn cần trả lời các câu hỏi như: +Sử dụng nó khi bạn cần trả lời các câu hỏi như: - Prompt, system prompt và công cụ nào đã được gửi tới mô hình? -- Những tin nhắn bản ghi hội thoại và lệnh gọi công cụ nào dẫn tới câu trả lời này? -- Lượt chạy có hết thời gian, bị hủy, compact, hay gặp lỗi nhà cung cấp không? -- Mô hình, plugins, Skills và thiết lập runtime nào đang hoạt động? +- Những tin nhắn transcript và lệnh gọi công cụ nào đã dẫn tới câu trả lời này? +- Lần chạy có bị hết thời gian, hủy bỏ, compact hay gặp lỗi nhà cung cấp không? +- Mô hình, plugin, Skills và cài đặt runtime nào đang hoạt động? - Nhà cung cấp đã trả về metadata sử dụng và prompt-cache nào? -Nếu bạn đang gửi một báo cáo hỗ trợ rộng cho sự cố Gateway trực tiếp, hãy bắt đầu với +Nếu bạn đang gửi một báo cáo hỗ trợ phạm vi rộng cho sự cố Gateway trực tiếp, hãy bắt đầu với [`/diagnostics`](/vi/gateway/diagnostics#chat-command). Diagnostics thu thập gói Gateway -đã được làm sạch và, đối với các phiên OpenAI Codex harness, cũng có thể gửi -phản hồi Codex tới máy chủ OpenAI sau khi được phê duyệt. Dùng `/export-trajectory` khi -bạn cần cụ thể dòng thời gian chi tiết theo từng phiên về prompt, công cụ và bản ghi hội thoại. +đã được làm sạch và, đối với các phiên harness OpenAI Codex, cũng có thể gửi +phản hồi Codex tới máy chủ OpenAI sau khi được phê duyệt. Sử dụng `/export-trajectory` khi +bạn cần cụ thể dòng thời gian chi tiết theo từng phiên về prompt, công cụ và transcript. ## Bắt đầu nhanh @@ -47,7 +47,7 @@ Bí danh: /trajectory ``` -OpenClaw ghi gói này bên dưới workspace: +OpenClaw ghi gói dưới workspace: ```text .openclaw/trajectory-exports/openclaw-trajectory--/ @@ -62,15 +62,15 @@ Bạn có thể chọn tên thư mục đầu ra tương đối: Đường dẫn tùy chỉnh được phân giải bên trong `.openclaw/trajectory-exports/`. Đường dẫn tuyệt đối và đường dẫn `~` bị từ chối. -Các gói quỹ đạo có thể chứa prompt, tin nhắn mô hình, schema công cụ, kết quả công cụ, -sự kiện runtime và đường dẫn cục bộ. Vì vậy, lệnh gạch chéo trong chat luôn chạy -qua phê duyệt exec mỗi lần. Hãy phê duyệt export một lần khi bạn định -tạo gói; không dùng allow-all. Trong chat nhóm, OpenClaw gửi -prompt phê duyệt và kết quả export riêng cho chủ sở hữu thay vì đăng -chi tiết quỹ đạo trở lại phòng chung. +Gói trajectory có thể chứa prompt, tin nhắn mô hình, schema công cụ, kết quả +công cụ, sự kiện runtime và đường dẫn cục bộ. Vì vậy lệnh slash trong chat luôn +chạy qua phê duyệt exec. Hãy phê duyệt việc export một lần khi bạn có ý định +tạo gói; không dùng allow-all. Trong chat nhóm, OpenClaw gửi lời nhắc phê duyệt +và kết quả export riêng cho chủ sở hữu thay vì đăng chi tiết trajectory trở lại +phòng chung. -Đối với quy trình kiểm tra cục bộ hoặc hỗ trợ, bạn cũng có thể chạy trực tiếp đường dẫn lệnh -đã được phê duyệt: +Đối với quy trình kiểm tra cục bộ hoặc hỗ trợ, bạn cũng có thể chạy trực tiếp +đường dẫn lệnh đã được phê duyệt: ```bash openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . @@ -78,12 +78,12 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 ## Quyền truy cập -Export quỹ đạo là lệnh dành cho chủ sở hữu. Người gửi phải vượt qua các kiểm tra +Trajectory export là lệnh của chủ sở hữu. Người gửi phải vượt qua các kiểm tra ủy quyền lệnh thông thường và kiểm tra chủ sở hữu cho kênh. ## Nội dung được ghi lại -Ghi lại quỹ đạo được bật mặc định cho các lượt chạy agent của OpenClaw. +Trajectory capture được bật mặc định cho các lần chạy tác nhân OpenClaw. Sự kiện runtime bao gồm: @@ -91,15 +91,15 @@ Sự kiện runtime bao gồm: - `trace.metadata` - `context.compiled` - `prompt.submitted` -- `model.fallback_step`, bao gồm mô hình nguồn, mô hình tiếp theo, lý do/chi tiết lỗi, vị trí trong chuỗi, và fallback đã tiến tiếp, thành công, hay dùng hết chuỗi +- `model.fallback_step`, bao gồm mô hình nguồn, mô hình tiếp theo, lý do/chi tiết lỗi, vị trí trong chuỗi và việc fallback đã tiến lên, thành công hay dùng hết chuỗi - `model.completed` - `trace.artifacts` - `session.ended` -Sự kiện bản ghi hội thoại cũng được tái dựng từ nhánh phiên đang hoạt động: +Sự kiện transcript cũng được tái dựng từ nhánh phiên đang hoạt động: - tin nhắn người dùng -- tin nhắn assistant +- tin nhắn trợ lý - lệnh gọi công cụ - kết quả công cụ - compactions @@ -122,20 +122,20 @@ Một gói đã export có thể chứa: | Tệp | Nội dung | | --------------------- | ---------------------------------------------------------------------------------------------- | | `manifest.json` | Schema gói, tệp nguồn, số lượng sự kiện và danh sách tệp đã tạo | -| `events.jsonl` | Dòng thời gian runtime và bản ghi hội thoại theo thứ tự | -| `session-branch.json` | Nhánh bản ghi hội thoại đang hoạt động và header phiên đã được biên tập ẩn thông tin nhạy cảm | -| `metadata.json` | Phiên bản OpenClaw, OS/runtime, mô hình, snapshot cấu hình, plugins, Skills và metadata prompt | -| `artifacts.json` | Trạng thái cuối, lỗi, mức sử dụng, prompt cache, số lần compaction, văn bản assistant và metadata công cụ | -| `prompts.json` | Prompt đã gửi và chi tiết tạo prompt đã chọn | -| `system-prompt.txt` | System prompt đã biên dịch mới nhất, khi được ghi lại | -| `tools.json` | Định nghĩa công cụ được gửi tới mô hình, khi được ghi lại | +| `events.jsonl` | Dòng thời gian runtime và transcript theo thứ tự | +| `session-branch.json` | Nhánh transcript đang hoạt động và header phiên đã biên tập | +| `metadata.json` | Phiên bản OpenClaw, OS/runtime, mô hình, snapshot cấu hình, plugin, Skills và metadata prompt | +| `artifacts.json` | Trạng thái cuối, lỗi, sử dụng, prompt cache, số lượng compaction, văn bản trợ lý và metadata công cụ | +| `prompts.json` | Prompt đã gửi và chi tiết tạo prompt đã chọn | +| `system-prompt.txt` | System prompt đã biên dịch mới nhất, khi được ghi lại | +| `tools.json` | Định nghĩa công cụ được gửi tới mô hình, khi được ghi lại | `manifest.json` liệt kê các tệp có trong gói đó. Một số tệp bị bỏ qua khi phiên không ghi lại dữ liệu runtime tương ứng. -## Vị trí ghi lại +## Vị trí capture -Theo mặc định, sự kiện quỹ đạo runtime được ghi cạnh tệp phiên: +Theo mặc định, các sự kiện runtime trajectory được ghi cạnh tệp phiên: ```text .trajectory.jsonl @@ -147,7 +147,7 @@ OpenClaw cũng ghi một tệp con trỏ theo best-effort cạnh phiên: .trajectory-path.json ``` -Đặt `OPENCLAW_TRAJECTORY_DIR` để lưu sidecar quỹ đạo runtime trong một +Đặt `OPENCLAW_TRAJECTORY_DIR` để lưu sidecar runtime trajectory trong một thư mục chuyên dụng: ```bash @@ -157,12 +157,12 @@ export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories Khi biến này được đặt, OpenClaw ghi một tệp JSONL cho mỗi id phiên trong thư mục đó. -Bảo trì phiên xóa các sidecar quỹ đạo khi mục phiên sở hữu chúng -bị prune, bị giới hạn, hoặc bị loại bỏ bởi ngân sách đĩa phiên. Các tệp runtime bên ngoài -thư mục phiên chỉ được xóa khi mục tiêu con trỏ vẫn chứng minh rằng nó +Bảo trì phiên xóa các sidecar trajectory khi mục phiên sở hữu chúng bị +cắt tỉa, giới hạn hoặc loại bỏ bởi ngân sách đĩa của phiên. Các tệp runtime bên ngoài +thư mục phiên chỉ bị xóa khi đích con trỏ vẫn chứng minh rằng nó thuộc về phiên đó. -## Tắt ghi lại +## Tắt capture Đặt `OPENCLAW_TRAJECTORY=0` trước khi khởi động OpenClaw: @@ -170,14 +170,14 @@ thuộc về phiên đó. export OPENCLAW_TRAJECTORY=0 ``` -Thao tác này tắt ghi lại quỹ đạo runtime. `/export-trajectory` vẫn có thể export -nhánh bản ghi hội thoại, nhưng các tệp chỉ có runtime như context đã biên dịch, +Điều này tắt runtime trajectory capture. `/export-trajectory` vẫn có thể export +nhánh transcript, nhưng các tệp chỉ có ở runtime như context đã biên dịch, artifact nhà cung cấp và metadata prompt có thể bị thiếu. ## Quyền riêng tư và giới hạn -Các gói quỹ đạo được thiết kế cho hỗ trợ và gỡ lỗi, không phải để đăng công khai. -OpenClaw biên tập ẩn các giá trị nhạy cảm trước khi ghi tệp export: +Gói trajectory được thiết kế cho hỗ trợ và gỡ lỗi, không phải để đăng công khai. +OpenClaw biên tập các giá trị nhạy cảm trước khi ghi tệp export: - thông tin xác thực và các trường payload giống bí mật đã biết - dữ liệu hình ảnh @@ -185,23 +185,23 @@ OpenClaw biên tập ẩn các giá trị nhạy cảm trước khi ghi tệp ex - đường dẫn workspace, được thay bằng `$WORKSPACE_DIR` - đường dẫn thư mục home, khi phát hiện được -Trình export cũng giới hạn kích thước đầu vào: +Exporter cũng giới hạn kích thước đầu vào: -- tệp sidecar runtime: 50 MiB +- tệp sidecar runtime: live capture dừng ở 10 MiB và ghi sự kiện cắt ngắn khi còn dung lượng; export chấp nhận sidecar runtime hiện có tối đa 50 MiB - tệp phiên: 50 MiB -- sự kiện runtime: 200,000 -- tổng sự kiện đã export: 250,000 +- sự kiện runtime: 200.000 +- tổng số sự kiện đã export: 250.000 - từng dòng sự kiện runtime bị cắt ngắn khi vượt quá 256 KiB -Hãy xem lại các gói trước khi chia sẻ chúng ra ngoài nhóm của bạn. Việc biên tập ẩn thông tin nhạy cảm là best-effort -và không thể biết mọi bí mật riêng cho từng ứng dụng. +Hãy xem lại các gói trước khi chia sẻ chúng bên ngoài nhóm của bạn. Việc biên tập là best-effort +và không thể biết mọi bí mật riêng theo từng ứng dụng. ## Khắc phục sự cố -Nếu export không có sự kiện runtime: +Nếu bản export không có sự kiện runtime: - xác nhận OpenClaw đã được khởi động mà không có `OPENCLAW_TRAJECTORY=0` -- kiểm tra liệu `OPENCLAW_TRAJECTORY_DIR` có trỏ tới một thư mục có thể ghi không +- kiểm tra xem `OPENCLAW_TRAJECTORY_DIR` có trỏ tới thư mục có thể ghi không - chạy một tin nhắn khác trong phiên, rồi export lại - kiểm tra `manifest.json` để tìm `runtimeEventCount` @@ -209,7 +209,7 @@ Nếu lệnh từ chối đường dẫn đầu ra: - dùng tên tương đối như `bug-1234` - không truyền `/tmp/...` hoặc `~/...` -- giữ export bên trong `.openclaw/trajectory-exports/` +- giữ bản export bên trong `.openclaw/trajectory-exports/` Nếu export thất bại với lỗi kích thước, phiên hoặc sidecar đã vượt quá giới hạn an toàn export. Hãy bắt đầu một phiên mới hoặc export một bản tái hiện nhỏ hơn. diff --git a/docs/vi/web/control-ui.md b/docs/vi/web/control-ui.md index 9760cac4b..8a9cdffb7 100644 --- a/docs/vi/web/control-ui.md +++ b/docs/vi/web/control-ui.md @@ -3,23 +3,23 @@ read_when: - Bạn muốn vận hành Gateway từ trình duyệt - Bạn muốn truy cập Tailnet mà không cần đường hầm SSH sidebarTitle: Control UI -summary: Giao diện người dùng điều khiển dựa trên trình duyệt cho Gateway (trò chuyện, nút, cấu hình) +summary: Giao diện điều khiển trên trình duyệt cho Gateway (trò chuyện, Node, cấu hình) title: Giao diện điều khiển x-i18n: - generated_at: "2026-05-04T07:06:35Z" + generated_at: "2026-05-04T09:37:56Z" model: gpt-5.5 provider: openai - source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5 + source_hash: 4b68b5203b369de6a3354a7e7442ee38ee790875b2d7054b0c8ec997098fd9de source_path: web/control-ui.md workflow: 16 --- -Control UI là một ứng dụng một trang nhỏ dùng **Vite + Lit**, được Gateway phục vụ: +Control UI là một ứng dụng đơn trang **Vite + Lit** nhỏ được Gateway phục vụ: - mặc định: `http://:18789/` - tiền tố tùy chọn: đặt `gateway.controlUi.basePath` (ví dụ: `/openclaw`) -Ứng dụng giao tiếp **trực tiếp với Gateway WebSocket** trên cùng cổng. +Nó giao tiếp **trực tiếp với Gateway WebSocket** trên cùng một cổng. ## Mở nhanh (cục bộ) @@ -29,18 +29,18 @@ Nếu Gateway đang chạy trên cùng máy tính, hãy mở: Nếu trang không tải được, hãy khởi động Gateway trước: `openclaw gateway`. -Xác thực được cung cấp trong quá trình bắt tay WebSocket thông qua: +Xác thực được cung cấp trong quá trình bắt tay WebSocket qua: - `connect.params.auth.token` - `connect.params.auth.password` -- các header danh tính Tailscale Serve khi `gateway.auth.allowTailscale: true` -- các header danh tính proxy đáng tin cậy khi `gateway.auth.mode: "trusted-proxy"` +- header danh tính Tailscale Serve khi `gateway.auth.allowTailscale: true` +- header danh tính proxy đáng tin cậy khi `gateway.auth.mode: "trusted-proxy"` -Bảng cài đặt dashboard giữ một token cho phiên tab trình duyệt hiện tại và URL gateway đã chọn; mật khẩu không được lưu. Quy trình khởi tạo thường tạo một token gateway cho xác thực shared-secret ở lần kết nối đầu tiên, nhưng xác thực bằng mật khẩu cũng hoạt động khi `gateway.auth.mode` là `"password"`. +Bảng cài đặt của bảng điều khiển giữ token cho phiên tab trình duyệt hiện tại và URL gateway đã chọn; mật khẩu không được lưu lại. Onboarding thường tạo token gateway để xác thực bằng bí mật dùng chung trong lần kết nối đầu tiên, nhưng xác thực bằng mật khẩu cũng hoạt động khi `gateway.auth.mode` là `"password"`. -## Ghép đôi thiết bị (kết nối đầu tiên) +## Ghép đôi thiết bị (lần kết nối đầu tiên) -Khi bạn kết nối tới Control UI từ một trình duyệt hoặc thiết bị mới, Gateway thường yêu cầu **phê duyệt ghép đôi một lần**. Đây là biện pháp bảo mật để ngăn truy cập trái phép. +Khi bạn kết nối với Control UI từ trình duyệt hoặc thiết bị mới, Gateway thường yêu cầu **phê duyệt ghép đôi một lần**. Đây là biện pháp bảo mật để ngăn truy cập trái phép. **Bạn sẽ thấy:** "disconnected (1008): pairing required" @@ -57,96 +57,97 @@ Khi bạn kết nối tới Control UI từ một trình duyệt hoặc thiết -Nếu trình duyệt thử ghép đôi lại với thông tin xác thực đã thay đổi (vai trò/phạm vi/khóa công khai), yêu cầu đang chờ trước đó sẽ bị thay thế và một `requestId` mới được tạo. Chạy lại `openclaw devices list` trước khi phê duyệt. +Nếu trình duyệt thử ghép đôi lại với chi tiết xác thực đã thay đổi (vai trò/phạm vi/khóa công khai), yêu cầu đang chờ trước đó sẽ bị thay thế và một `requestId` mới được tạo. Chạy lại `openclaw devices list` trước khi phê duyệt. -Nếu trình duyệt đã được ghép đôi và bạn đổi từ quyền đọc sang quyền ghi/admin, việc này được xem là nâng cấp phê duyệt, không phải là kết nối lại âm thầm. OpenClaw giữ phê duyệt cũ đang hoạt động, chặn kết nối lại với quyền rộng hơn, và yêu cầu bạn phê duyệt rõ ràng bộ phạm vi mới. +Nếu trình duyệt đã được ghép đôi và bạn đổi từ quyền đọc sang quyền ghi/quản trị, việc này được xử lý như một nâng cấp phê duyệt, không phải kết nối lại âm thầm. OpenClaw giữ phê duyệt cũ hoạt động, chặn lần kết nối lại với phạm vi rộng hơn, và yêu cầu bạn phê duyệt rõ ràng bộ phạm vi mới. -Sau khi được phê duyệt, thiết bị sẽ được ghi nhớ và sẽ không cần phê duyệt lại trừ khi bạn thu hồi bằng `openclaw devices revoke --device --role `. Xem [CLI Thiết bị](/vi/cli/devices) để biết cách xoay vòng và thu hồi token. +Sau khi được phê duyệt, thiết bị sẽ được ghi nhớ và không cần phê duyệt lại trừ khi bạn thu hồi bằng `openclaw devices revoke --device --role `. Xem [CLI thiết bị](/vi/cli/devices) để biết cách xoay vòng và thu hồi token. - Kết nối trình duyệt local loopback trực tiếp (`127.0.0.1` / `localhost`) được tự động phê duyệt. - Tailscale Serve có thể bỏ qua vòng ghép đôi cho các phiên vận hành Control UI khi `gateway.auth.allowTailscale: true`, danh tính Tailscale xác minh thành công, và trình duyệt trình bày danh tính thiết bị của nó. -- Liên kết Tailnet trực tiếp, kết nối trình duyệt LAN, và hồ sơ trình duyệt không có danh tính thiết bị vẫn yêu cầu phê duyệt rõ ràng. -- Mỗi hồ sơ trình duyệt tạo một ID thiết bị duy nhất, vì vậy việc đổi trình duyệt hoặc xóa dữ liệu trình duyệt sẽ yêu cầu ghép đôi lại. +- Liên kết Tailnet trực tiếp, kết nối trình duyệt qua LAN, và hồ sơ trình duyệt không có danh tính thiết bị vẫn yêu cầu phê duyệt rõ ràng. +- Mỗi hồ sơ trình duyệt tạo một ID thiết bị duy nhất, nên việc đổi trình duyệt hoặc xóa dữ liệu trình duyệt sẽ yêu cầu ghép đôi lại. -## Danh tính cá nhân (cục bộ trong trình duyệt) +## Danh tính cá nhân (cục bộ trên trình duyệt) -Control UI hỗ trợ một danh tính cá nhân theo từng trình duyệt (tên hiển thị và avatar) được gắn vào tin nhắn gửi đi để ghi nhận tác giả trong các phiên dùng chung. Danh tính này nằm trong bộ nhớ trình duyệt, được giới hạn trong hồ sơ trình duyệt hiện tại, và không được đồng bộ sang thiết bị khác hoặc lưu phía máy chủ ngoài metadata tác giả transcript thông thường trên các tin nhắn bạn thực sự gửi. Xóa dữ liệu trang hoặc đổi trình duyệt sẽ đặt lại danh tính này về trống. +Control UI hỗ trợ danh tính cá nhân theo từng trình duyệt (tên hiển thị và avatar) được gắn vào tin nhắn gửi đi để quy thuộc trong các phiên dùng chung. Danh tính này nằm trong bộ nhớ trình duyệt, được giới hạn theo hồ sơ trình duyệt hiện tại, và không được đồng bộ sang thiết bị khác hay lưu phía máy chủ ngoài metadata tác giả transcript thông thường trên các tin nhắn bạn thực sự gửi. Xóa dữ liệu trang hoặc đổi trình duyệt sẽ đặt lại về rỗng. -Mẫu cục bộ trong trình duyệt tương tự cũng áp dụng cho phần ghi đè avatar của trợ lý. Avatar trợ lý đã tải lên chỉ phủ lên danh tính do gateway phân giải trong trình duyệt cục bộ và không bao giờ đi vòng qua `config.patch`. Trường cấu hình dùng chung `ui.assistant.avatar` vẫn khả dụng cho các client không phải UI ghi trực tiếp trường này (chẳng hạn gateway theo script hoặc dashboard tùy chỉnh). +Mẫu cục bộ trên trình duyệt tương tự áp dụng cho phần ghi đè avatar trợ lý. Avatar trợ lý đã tải lên chỉ phủ lên danh tính do gateway phân giải trong trình duyệt cục bộ và không bao giờ đi vòng qua `config.patch`. Trường cấu hình dùng chung `ui.assistant.avatar` vẫn khả dụng cho các client không phải UI ghi trực tiếp vào trường này (chẳng hạn gateway theo script hoặc bảng điều khiển tùy chỉnh). ## Endpoint cấu hình runtime -Control UI lấy cài đặt runtime từ `/__openclaw/control-ui-config.json`. Endpoint đó được bảo vệ bởi cùng cơ chế xác thực gateway như phần còn lại của bề mặt HTTP: trình duyệt chưa xác thực không thể lấy dữ liệu, và việc lấy thành công yêu cầu token/mật khẩu gateway đã hợp lệ, danh tính Tailscale Serve, hoặc danh tính proxy đáng tin cậy. +Control UI lấy cài đặt runtime từ `/__openclaw/control-ui-config.json`. Endpoint đó được bảo vệ bằng cùng cơ chế xác thực gateway như phần còn lại của bề mặt HTTP: trình duyệt chưa xác thực không thể lấy dữ liệu, và một lần lấy thành công yêu cầu token/mật khẩu gateway đã hợp lệ, danh tính Tailscale Serve, hoặc danh tính proxy đáng tin cậy. ## Hỗ trợ ngôn ngữ -Control UI có thể tự bản địa hóa trong lần tải đầu tiên dựa trên ngôn ngữ trình duyệt của bạn. Để ghi đè sau đó, mở **Tổng quan -> Truy cập Gateway -> Ngôn ngữ**. Bộ chọn ngôn ngữ nằm trong thẻ Truy cập Gateway, không nằm trong Giao diện. +Control UI có thể tự bản địa hóa trong lần tải đầu tiên dựa trên locale của trình duyệt. Để ghi đè sau đó, mở **Tổng quan -> Truy cập Gateway -> Ngôn ngữ**. Bộ chọn locale nằm trong thẻ Truy cập Gateway, không nằm dưới Giao diện. -- Ngôn ngữ được hỗ trợ: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` -- Các bản dịch không phải tiếng Anh được tải lười trong trình duyệt. -- Ngôn ngữ đã chọn được lưu trong bộ nhớ trình duyệt và dùng lại trong các lần truy cập sau. -- Khóa bản dịch bị thiếu sẽ rơi về tiếng Anh. +- Locale được hỗ trợ: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` +- Bản dịch không phải tiếng Anh được tải lười trong trình duyệt. +- Locale đã chọn được lưu trong bộ nhớ trình duyệt và dùng lại trong các lần truy cập sau. +- Khóa bản dịch bị thiếu sẽ quay về tiếng Anh. -Bản dịch tài liệu được tạo cho cùng bộ ngôn ngữ không phải tiếng Anh, nhưng bộ chọn ngôn ngữ Mintlify tích hợp của trang tài liệu bị giới hạn ở các mã ngôn ngữ mà Mintlify chấp nhận. Tài liệu tiếng Thái (`th`) và tiếng Ba Tư (`fa`) vẫn được tạo trong repo xuất bản; chúng có thể chưa xuất hiện trong bộ chọn đó cho đến khi Mintlify hỗ trợ các mã này. +Bản dịch tài liệu được tạo cho cùng bộ locale không phải tiếng Anh, nhưng bộ chọn ngôn ngữ Mintlify tích hợp của trang tài liệu bị giới hạn ở các mã locale mà Mintlify chấp nhận. Tài liệu tiếng Thái (`th`) và tiếng Ba Tư (`fa`) vẫn được tạo trong repo phát hành; chúng có thể chưa xuất hiện trong bộ chọn đó cho đến khi Mintlify hỗ trợ các mã này. ## Chủ đề giao diện -Bảng Giao diện giữ các chủ đề Claw, Knot và Dash tích hợp sẵn, cùng một vị trí nhập tweakcn cục bộ trong trình duyệt. Để nhập một chủ đề, mở [trình chỉnh sửa tweakcn](https://tweakcn.com/editor/theme), chọn hoặc tạo một chủ đề, bấm **Chia sẻ**, rồi dán liên kết chủ đề đã sao chép vào Giao diện. Trình nhập cũng chấp nhận URL registry `https://tweakcn.com/r/themes/`, URL trình chỉnh sửa như `https://tweakcn.com/editor/theme?theme=amethyst-haze`, đường dẫn tương đối `/themes/`, ID chủ đề thô, và tên chủ đề mặc định như `amethyst-haze`. +Bảng Giao diện giữ các chủ đề tích hợp Claw, Knot và Dash, cộng với một khe nhập tweakcn cục bộ trên trình duyệt. Để nhập chủ đề, mở [trình chỉnh sửa tweakcn](https://tweakcn.com/editor/theme), chọn hoặc tạo một chủ đề, nhấp **Chia sẻ**, rồi dán liên kết chủ đề đã sao chép vào Giao diện. Trình nhập cũng chấp nhận URL registry `https://tweakcn.com/r/themes/`, URL trình chỉnh sửa như `https://tweakcn.com/editor/theme?theme=amethyst-haze`, đường dẫn tương đối `/themes/`, ID chủ đề thô, và tên chủ đề mặc định như `amethyst-haze`. -Các chủ đề đã nhập chỉ được lưu trong hồ sơ trình duyệt hiện tại. Chúng không được ghi vào cấu hình gateway và không đồng bộ giữa các thiết bị. Thay thế chủ đề đã nhập sẽ cập nhật một vị trí cục bộ đó; xóa chủ đề đã nhập sẽ chuyển chủ đề đang hoạt động về Claw nếu chủ đề đã nhập đang được chọn. +Chủ đề đã nhập chỉ được lưu trong hồ sơ trình duyệt hiện tại. Chúng không được ghi vào cấu hình gateway và không đồng bộ giữa các thiết bị. Thay thế chủ đề đã nhập sẽ cập nhật một khe cục bộ đó; xóa nó sẽ chuyển chủ đề đang hoạt động về Claw nếu chủ đề đã nhập đang được chọn. -## Hiện có thể làm gì (hôm nay) +## Những gì nó có thể làm (hiện tại) - - - Trò chuyện với mô hình qua Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Nói chuyện thông qua các phiên thời gian thực của trình duyệt. OpenAI dùng WebRTC trực tiếp, Google Live dùng token trình duyệt dùng một lần có giới hạn qua WebSocket, và các plugin thoại thời gian thực chỉ chạy backend dùng truyền tải chuyển tiếp của Gateway. Bộ chuyển tiếp giữ thông tin xác thực nhà cung cấp trên Gateway trong khi trình duyệt truyền PCM micro qua các RPC `talk.realtime.relay*` và gửi các lệnh gọi công cụ `openclaw_agent_consult` ngược qua `chat.send` cho mô hình OpenClaw lớn hơn đã cấu hình. - - Truyền phát lệnh gọi công cụ + thẻ đầu ra công cụ trực tiếp trong Trò chuyện (sự kiện tác nhân). + + - Trò chuyện với model qua Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). + - Đàm thoại qua các phiên realtime của trình duyệt. OpenAI dùng WebRTC trực tiếp, Google Live dùng token trình duyệt một lần có ràng buộc qua WebSocket, và các plugin giọng nói realtime chỉ backend dùng truyền tải chuyển tiếp của Gateway. Bộ chuyển tiếp giữ thông tin xác thực nhà cung cấp trên Gateway trong khi trình duyệt truyền PCM từ microphone qua RPC `talk.realtime.relay*` và gửi các lệnh gọi công cụ `openclaw_agent_consult` ngược qua `chat.send` cho model OpenClaw lớn hơn đã cấu hình. + - Truyền trực tuyến lệnh gọi công cụ + thẻ kết quả công cụ trực tiếp trong Trò chuyện (sự kiện agent). - - - Kênh: trạng thái kênh tích hợp sẵn cùng các kênh plugin đóng gói/bên ngoài, đăng nhập QR, và cấu hình theo kênh (`channels.status`, `web.login.*`, `config.patch`). - - Phiên bản: danh sách hiện diện + làm mới (`system-presence`). - - Phiên: danh sách + ghi đè theo phiên cho mô hình/suy nghĩ/nhanh/chi tiết/trace/lý luận (`sessions.list`, `sessions.patch`). - - Giấc mơ: trạng thái dreaming, công tắc bật/tắt, và trình đọc Nhật ký Dream (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + + - Kênh: tích hợp sẵn cộng với trạng thái kênh plugin đóng gói/bên ngoài, đăng nhập QR, và cấu hình theo từng kênh (`channels.status`, `web.login.*`, `config.patch`). + - Thực thể: danh sách hiện diện + làm mới (`system-presence`). + - Phiên: danh sách + ghi đè model/thinking/nhanh/chi tiết/trace/reasoning theo từng phiên (`sessions.list`, `sessions.patch`). + - Giấc mơ: trạng thái Dreaming, nút bật/tắt, và trình đọc Nhật ký Dream (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - + - Công việc Cron: liệt kê/thêm/sửa/chạy/bật/tắt + lịch sử chạy (`cron.*`). - Skills: trạng thái, bật/tắt, cài đặt, cập nhật khóa API (`skills.*`). - - Node: liệt kê + giới hạn năng lực (`node.list`). - - Phê duyệt exec: sửa allowlist gateway hoặc node + chính sách hỏi cho `exec host=gateway/node` (`exec.approvals.*`). + - Node: danh sách + khả năng (`node.list`). + - Phê duyệt exec: chỉnh sửa allowlist của gateway hoặc node + chính sách hỏi cho `exec host=gateway/node` (`exec.approvals.*`). - - Xem/sửa `~/.openclaw/openclaw.json` (`config.get`, `config.set`). - - Áp dụng + khởi động lại kèm xác thực (`config.apply`) và đánh thức phiên hoạt động cuối cùng. - - Các lần ghi bao gồm guard base-hash để ngăn ghi đè lên các chỉnh sửa đồng thời. - - Các lần ghi (`config.set`/`config.apply`/`config.patch`) kiểm tra trước việc phân giải SecretRef đang hoạt động cho các ref trong payload cấu hình đã gửi; các ref đang hoạt động đã gửi nhưng không phân giải được sẽ bị từ chối trước khi ghi. - - Schema + kết xuất biểu mẫu (`config.schema` / `config.schema.lookup`, bao gồm `title` / `description` của trường, gợi ý UI khớp, tóm tắt con trực tiếp, metadata tài liệu trên các node đối tượng lồng nhau/wildcard/mảng/composition, cùng schema plugin + kênh khi có); trình chỉnh sửa JSON thô chỉ khả dụng khi snapshot có thể round-trip thô an toàn. - - Nếu snapshot không thể round-trip văn bản thô một cách an toàn, Control UI buộc dùng chế độ Biểu mẫu và tắt chế độ Thô cho snapshot đó. - - Trình chỉnh sửa JSON thô "Đặt lại về bản đã lưu" giữ nguyên hình dạng do tác giả thô tạo ra (định dạng, chú thích, bố cục `$include`) thay vì kết xuất lại một snapshot đã làm phẳng, vì vậy các chỉnh sửa bên ngoài vẫn tồn tại sau khi đặt lại khi snapshot có thể round-trip an toàn. - - Giá trị đối tượng SecretRef có cấu trúc được kết xuất chỉ đọc trong ô nhập văn bản của biểu mẫu để ngăn vô tình làm hỏng đối tượng thành chuỗi. + - Xem/chỉnh sửa `~/.openclaw/openclaw.json` (`config.get`, `config.set`). + - Áp dụng + khởi động lại với xác thực (`config.apply`) và đánh thức phiên hoạt động gần nhất. + - Các lần ghi bao gồm bộ bảo vệ base-hash để tránh ghi đè các chỉnh sửa đồng thời. + - Các lần ghi (`config.set`/`config.apply`/`config.patch`) kiểm tra trước việc phân giải SecretRef đang hoạt động cho các ref trong payload cấu hình đã gửi; các ref đã gửi đang hoạt động nhưng chưa phân giải sẽ bị từ chối trước khi ghi. + - Schema + kết xuất biểu mẫu (`config.schema` / `config.schema.lookup`, bao gồm `title` / `description` của trường, gợi ý UI đã khớp, tóm tắt con trực tiếp, metadata tài liệu trên node object/wildcard/array/composition lồng nhau, cùng schema plugin + kênh khi có); trình chỉnh sửa JSON thô chỉ khả dụng khi snapshot có vòng đi-về thô an toàn. + - Nếu một snapshot không thể đi-về văn bản thô một cách an toàn, Control UI bắt buộc chế độ Biểu mẫu và tắt chế độ Thô cho snapshot đó. + - "Đặt lại về bản đã lưu" trong trình chỉnh sửa JSON thô giữ nguyên hình dạng do tác giả thô tạo (định dạng, chú thích, bố cục `$include`) thay vì kết xuất lại một snapshot đã làm phẳng, để các chỉnh sửa bên ngoài vẫn tồn tại sau khi đặt lại khi snapshot có thể đi-về an toàn. + - Giá trị object SecretRef có cấu trúc được hiển thị chỉ đọc trong input văn bản của biểu mẫu để tránh vô tình làm hỏng object thành chuỗi. - - Gỡ lỗi: snapshot trạng thái/sức khỏe/mô hình + nhật ký sự kiện + lệnh gọi RPC thủ công (`status`, `health`, `models.list`). - - Nhật ký: tail trực tiếp nhật ký tệp gateway với lọc/xuất (`logs.tail`). - - Cập nhật: chạy cập nhật package/git + khởi động lại (`update.run`) với báo cáo khởi động lại, sau đó thăm dò `update.status` sau khi kết nối lại để xác minh phiên bản gateway đang chạy. + - Gỡ lỗi: snapshot trạng thái/sức khỏe/model + nhật ký sự kiện + lệnh gọi RPC thủ công (`status`, `health`, `models.list`). + - Nhật ký sự kiện bao gồm thời gian làm mới/RPC của Control UI cùng các mục về độ phản hồi của trình duyệt cho frame hoạt ảnh dài hoặc tác vụ dài khi trình duyệt cung cấp các kiểu mục PerformanceObserver đó. + - Nhật ký: theo dõi trực tiếp nhật ký tệp gateway với lọc/xuất (`logs.tail`). + - Cập nhật: chạy cập nhật package/git + khởi động lại (`update.run`) với báo cáo khởi động lại, rồi thăm dò `update.status` sau khi kết nối lại để xác minh phiên bản gateway đang chạy. - - Với công việc tách biệt, gửi mặc định là thông báo tóm tắt. Bạn có thể chuyển sang không gửi nếu muốn các lần chạy chỉ dùng nội bộ. - - Các trường kênh/đích xuất hiện khi chọn thông báo. + - Với công việc tách biệt, mặc định gửi là thông báo tóm tắt. Bạn có thể chuyển sang không gửi nếu muốn các lần chạy chỉ nội bộ. + - Các trường kênh/đích xuất hiện khi thông báo được chọn. - Chế độ Webhook dùng `delivery.mode = "webhook"` với `delivery.to` đặt thành URL webhook HTTP(S) hợp lệ. - - Với công việc phiên chính, có thể dùng các chế độ gửi webhook và không gửi. - - Điều khiển sửa nâng cao bao gồm xóa sau khi chạy, xóa ghi đè tác nhân, tùy chọn cron chính xác/rải đều, ghi đè mô hình/suy nghĩ của tác nhân, và công tắc gửi theo nỗ lực tốt nhất. - - Xác thực biểu mẫu hiển thị nội tuyến với lỗi cấp trường; giá trị không hợp lệ sẽ tắt nút lưu cho đến khi được sửa. - - Đặt `cron.webhookToken` để gửi token bearer chuyên dụng; nếu bỏ qua, webhook được gửi mà không có header xác thực. - - Dự phòng đã ngừng khuyến nghị: các công việc cũ đã lưu với `notify: true` vẫn có thể dùng `cron.webhook` cho đến khi được di chuyển. + - Với công việc phiên chính, các chế độ gửi webhook và không gửi đều khả dụng. + - Điều khiển chỉnh sửa nâng cao bao gồm xóa sau khi chạy, xóa ghi đè agent, tùy chọn cron chính xác/rải thời gian, ghi đè model/thinking của agent, và nút bật/tắt gửi theo nỗ lực tốt nhất. + - Xác thực biểu mẫu nằm inline với lỗi ở cấp trường; giá trị không hợp lệ sẽ tắt nút lưu cho đến khi được sửa. + - Đặt `cron.webhookToken` để gửi bearer token riêng; nếu bỏ qua, webhook được gửi mà không có header xác thực. + - Dự phòng không còn được khuyến nghị: các công việc legacy đã lưu với `notify: true` vẫn có thể dùng `cron.webhook` cho đến khi được di chuyển. @@ -154,86 +155,89 @@ Các chủ đề đã nhập chỉ được lưu trong hồ sơ trình duyệt h ## Hành vi trò chuyện - - - `chat.send` là **không chặn**: nó xác nhận ngay với `{ runId, status: "started" }` và phản hồi được truyền qua các sự kiện `chat`. - - Nội dung tải lên trong trò chuyện chấp nhận hình ảnh cùng các tệp không phải video. Hình ảnh giữ đường dẫn ảnh gốc; các tệp khác được lưu dưới dạng phương tiện được quản lý và hiển thị trong lịch sử dưới dạng liên kết tệp đính kèm. + + - `chat.send` là **không chặn**: nó xác nhận ngay bằng `{ runId, status: "started" }` và phản hồi được phát trực tuyến qua các sự kiện `chat`. + - Nội dung tải lên trong chat chấp nhận hình ảnh cùng các tệp không phải video. Hình ảnh giữ đường dẫn hình ảnh gốc; các tệp khác được lưu trữ dưới dạng phương tiện được quản lý và hiển thị trong lịch sử dưới dạng liên kết tệp đính kèm. - Gửi lại với cùng `idempotencyKey` trả về `{ status: "in_flight" }` khi đang chạy, và `{ status: "ok" }` sau khi hoàn tất. - - Phản hồi `chat.history` được giới hạn kích thước để an toàn cho UI. Khi các mục bản ghi quá lớn, Gateway có thể cắt bớt các trường văn bản dài, bỏ qua các khối siêu dữ liệu nặng, và thay thế các tin nhắn quá khổ bằng một placeholder (`[chat.history omitted: message too large]`). - - Hình ảnh do trợ lý/tạo sinh được lưu bền vững dưới dạng tham chiếu phương tiện được quản lý và được phục vụ lại qua URL phương tiện Gateway đã xác thực, nên việc tải lại không phụ thuộc vào payload ảnh base64 thô còn nằm trong phản hồi lịch sử trò chuyện. - - `chat.history` cũng loại bỏ các thẻ chỉ thị nội tuyến chỉ dùng để hiển thị khỏi văn bản trợ lý có thể nhìn thấy (ví dụ `[[reply_to_*]]` và `[[audio_as_voice]]`), payload XML lời gọi công cụ dạng văn bản thuần (bao gồm `...`, `...`, `...`, `...`, và các khối lời gọi công cụ bị cắt ngắn), cũng như các token điều khiển mô hình ASCII/toàn độ rộng bị rò rỉ, và bỏ qua các mục trợ lý mà toàn bộ văn bản hiển thị chỉ là token im lặng chính xác `NO_REPLY` / `no_reply`. - - Trong khi một lượt gửi đang hoạt động và ở lần làm mới lịch sử cuối cùng, khung xem trò chuyện vẫn giữ các tin nhắn người dùng/trợ lý lạc quan cục bộ hiển thị nếu `chat.history` trong chốc lát trả về một ảnh chụp cũ hơn; bản ghi chuẩn sẽ thay thế các tin nhắn cục bộ đó khi lịch sử Gateway bắt kịp. - - Các sự kiện `chat` trực tiếp là trạng thái phân phối, còn `chat.history` được dựng lại từ bản ghi phiên bền vững. Sau các sự kiện hoàn tất công cụ, Control UI tải lại lịch sử và chỉ hợp nhất một phần đuôi lạc quan nhỏ; ranh giới bản ghi được ghi lại trong [WebChat](/vi/web/webchat). - - `chat.inject` thêm một ghi chú trợ lý vào bản ghi phiên và phát một sự kiện `chat` cho các cập nhật chỉ dành cho UI (không chạy agent, không phân phối qua kênh). - - Bộ chọn mô hình và tư duy ở tiêu đề trò chuyện vá phiên đang hoạt động ngay lập tức qua `sessions.patch`; chúng là các ghi đè phiên bền vững, không phải tùy chọn gửi chỉ áp dụng cho một lượt. - - Gõ `/new` trong Control UI sẽ tạo và chuyển sang cùng phiên bảng điều khiển mới như New Chat. Gõ `/reset` giữ cơ chế đặt lại tại chỗ rõ ràng của Gateway cho phiên hiện tại. - - Bộ chọn mô hình trò chuyện yêu cầu khung nhìn mô hình đã cấu hình của Gateway. Nếu có `agents.defaults.models`, danh sách cho phép đó điều khiển bộ chọn. Nếu không, bộ chọn hiển thị các mục `models.providers.*.models` rõ ràng cùng những provider có xác thực dùng được. Catalog đầy đủ vẫn có sẵn qua RPC gỡ lỗi `models.list` với `view: "all"`. - - Khi báo cáo sử dụng phiên Gateway mới cho thấy áp lực ngữ cảnh cao, vùng soạn trò chuyện hiển thị thông báo ngữ cảnh và, ở các mức compaction được khuyến nghị, một nút thu gọn chạy đường dẫn compaction phiên thông thường. Các ảnh chụp token cũ được ẩn cho đến khi Gateway báo cáo mức sử dụng mới trở lại. + - Phản hồi `chat.history` bị giới hạn kích thước để bảo vệ UI. Khi các mục bản ghi cuộc trò chuyện quá lớn, Gateway có thể cắt ngắn các trường văn bản dài, bỏ qua các khối siêu dữ liệu nặng, và thay các tin nhắn quá khổ bằng một placeholder (`[chat.history omitted: message too large]`). + - Hình ảnh do trợ lý/tạo sinh được lưu bền dưới dạng tham chiếu phương tiện được quản lý và được phục vụ lại qua các URL phương tiện Gateway đã xác thực, vì vậy việc tải lại không phụ thuộc vào việc payload hình ảnh base64 thô còn nằm trong phản hồi lịch sử chat. + - `chat.history` cũng loại bỏ các thẻ chỉ thị nội tuyến chỉ dùng để hiển thị khỏi văn bản trợ lý nhìn thấy được (ví dụ `[[reply_to_*]]` và `[[audio_as_voice]]`), payload XML gọi công cụ dạng văn bản thuần (bao gồm `...`, `...`, `...`, `...`, và các khối gọi công cụ bị cắt ngắn), cũng như các token điều khiển mô hình ASCII/full-width bị rò rỉ, và bỏ qua các mục trợ lý có toàn bộ văn bản nhìn thấy được chỉ là token im lặng chính xác `NO_REPLY` / `no_reply`. + - Trong lúc gửi đang hoạt động và lần làm mới lịch sử cuối cùng, khung nhìn chat giữ các tin nhắn người dùng/trợ lý lạc quan cục bộ hiển thị nếu `chat.history` tạm thời trả về một snapshot cũ hơn; bản ghi chuẩn sẽ thay thế các tin nhắn cục bộ đó khi lịch sử Gateway bắt kịp. + - Các sự kiện `chat` trực tiếp là trạng thái phân phối, còn `chat.history` được dựng lại từ bản ghi phiên bền vững. Sau các sự kiện công cụ cuối cùng, Control UI tải lại lịch sử và chỉ hợp nhất một phần đuôi lạc quan nhỏ; ranh giới bản ghi được ghi lại trong [WebChat](/vi/web/webchat). + - `chat.inject` thêm một ghi chú trợ lý vào bản ghi phiên và phát một sự kiện `chat` cho các cập nhật chỉ dành cho UI (không có lượt chạy agent, không phân phối qua kênh). + - Tiêu đề chat hiển thị bộ lọc agent trước bộ chọn phiên, và bộ chọn phiên được giới hạn theo agent đã chọn. Khi chuyển agent, chỉ các phiên gắn với agent đó được hiển thị và sẽ quay về phiên chính của agent đó khi chưa có phiên dashboard nào được lưu. + - Trên chiều rộng desktop, các điều khiển chat nằm trên một hàng gọn và thu gọn khi cuộn xuống bản ghi; cuộn lên, quay lại đầu trang, hoặc chạm đáy sẽ khôi phục các điều khiển. + - Các tin nhắn chỉ có văn bản trùng lặp liên tiếp hiển thị dưới dạng một bong bóng kèm huy hiệu số lượng. Các tin nhắn mang hình ảnh, tệp đính kèm, đầu ra công cụ, hoặc bản xem trước canvas không bị thu gọn. + - Bộ chọn mô hình và thinking trong tiêu đề chat vá phiên đang hoạt động ngay lập tức qua `sessions.patch`; chúng là các ghi đè phiên được lưu bền, không phải tùy chọn gửi chỉ dùng cho một lượt. + - Gõ `/new` trong Control UI sẽ tạo và chuyển sang cùng phiên dashboard mới như New Chat. Gõ `/reset` giữ lại thao tác đặt lại tại chỗ rõ ràng của Gateway cho phiên hiện tại. + - Bộ chọn mô hình chat yêu cầu khung nhìn mô hình đã cấu hình của Gateway. Nếu có `agents.defaults.models`, danh sách cho phép đó điều khiển bộ chọn. Nếu không, bộ chọn hiển thị các mục `models.providers.*.models` rõ ràng cộng với các nhà cung cấp có xác thực khả dụng. Danh mục đầy đủ vẫn có sẵn qua RPC gỡ lỗi `models.list` với `view: "all"`. + - Khi báo cáo sử dụng phiên Gateway mới cho thấy áp lực ngữ cảnh cao, khu vực trình soạn chat hiển thị thông báo ngữ cảnh và, ở các mức Compaction được khuyến nghị, một nút gọn chạy đường dẫn Compaction phiên thông thường. Các snapshot token cũ được ẩn cho đến khi Gateway báo cáo lại mức sử dụng mới. - - Chế độ Talk sử dụng một provider giọng nói thời gian thực đã đăng ký. Cấu hình OpenAI với `talk.provider: "openai"` cộng với `talk.providers.openai.apiKey`, hoặc cấu hình Google với `talk.provider: "google"` cộng với `talk.providers.google.apiKey`; cấu hình provider thời gian thực Voice Call vẫn có thể được tái sử dụng làm dự phòng. Trình duyệt không bao giờ nhận khóa API provider tiêu chuẩn. OpenAI nhận một bí mật client Realtime tạm thời cho WebRTC. Google Live nhận một token xác thực Live API bị ràng buộc, dùng một lần cho phiên WebSocket trình duyệt, với chỉ dẫn và khai báo công cụ được Gateway khóa vào token. Các provider chỉ cung cấp cầu nối thời gian thực backend sẽ chạy qua transport chuyển tiếp Gateway, nên thông tin xác thực và socket nhà cung cấp vẫn ở phía máy chủ trong khi âm thanh trình duyệt đi qua các RPC Gateway đã xác thực. Prompt phiên Realtime được Gateway lắp ráp; `talk.realtime.session` không chấp nhận ghi đè chỉ dẫn do bên gọi cung cấp. + + Chế độ Talk dùng một nhà cung cấp thoại thời gian thực đã đăng ký. Cấu hình OpenAI bằng `talk.provider: "openai"` cộng với `talk.providers.openai.apiKey`, hoặc cấu hình Google bằng `talk.provider: "google"` cộng với `talk.providers.google.apiKey`; cấu hình nhà cung cấp thời gian thực Voice Call vẫn có thể được tái sử dụng làm phương án dự phòng. Trình duyệt không bao giờ nhận khóa API nhà cung cấp chuẩn. OpenAI nhận một secret máy khách Realtime tạm thời cho WebRTC. Google Live nhận một token xác thực Live API bị ràng buộc, dùng một lần cho phiên WebSocket trình duyệt, với chỉ dẫn và khai báo công cụ được Gateway khóa vào token. Các nhà cung cấp chỉ để lộ cầu nối thời gian thực backend chạy qua transport chuyển tiếp Gateway, nên thông tin xác thực và socket nhà cung cấp vẫn ở phía máy chủ trong khi âm thanh trình duyệt đi qua các RPC Gateway đã xác thực. Lời nhắc phiên Realtime được Gateway lắp ráp; `talk.realtime.session` không chấp nhận ghi đè chỉ dẫn do bên gọi cung cấp. - Trong trình soạn Chat, điều khiển Talk là nút sóng nằm cạnh nút nhập chính tả bằng micrô. Khi Talk bắt đầu, hàng trạng thái trình soạn hiển thị `Connecting Talk...`, sau đó là `Talk live` khi âm thanh đã kết nối, hoặc `Asking OpenClaw...` khi một lời gọi công cụ thời gian thực đang tham vấn mô hình lớn hơn đã cấu hình qua `chat.send`. + Trong trình soạn Chat, điều khiển Talk là nút hình sóng cạnh nút đọc chính tả bằng microphone. Khi Talk khởi động, hàng trạng thái trình soạn hiển thị `Connecting Talk...`, sau đó `Talk live` khi âm thanh đã kết nối, hoặc `Asking OpenClaw...` khi một lệnh gọi công cụ thời gian thực đang tham khảo mô hình lớn hơn đã cấu hình qua `chat.send`. - Kiểm thử khói trực tiếp cho maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` xác minh trao đổi SDP WebRTC trình duyệt OpenAI, thiết lập WebSocket trình duyệt bằng token ràng buộc Google Live, và bộ điều hợp trình duyệt chuyển tiếp Gateway với phương tiện micrô giả. Lệnh chỉ in trạng thái provider và không ghi nhật ký bí mật. + Smoke trực tiếp cho maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` xác minh trao đổi SDP WebRTC trình duyệt OpenAI, thiết lập WebSocket trình duyệt bằng token bị ràng buộc của Google Live, và adapter trình duyệt chuyển tiếp Gateway với phương tiện microphone giả. Lệnh chỉ in trạng thái nhà cung cấp và không ghi log secret. - - - Nhấp **Stop** (gọi `chat.abort`). - - Khi một lượt chạy đang hoạt động, các lượt theo dõi thông thường sẽ vào hàng đợi. Nhấp **Steer** trên một tin nhắn trong hàng đợi để chèn lượt theo dõi đó vào lượt đang chạy. - - Gõ `/stop` (hoặc các cụm từ hủy độc lập như `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) để hủy ngoài băng. - - `chat.abort` hỗ trợ `{ sessionKey }` (không có `runId`) để hủy tất cả lượt chạy đang hoạt động cho phiên đó. + + - Nhấp **Dừng** (gọi `chat.abort`). + - Khi một lượt chạy đang hoạt động, các lượt theo sau thông thường sẽ được đưa vào hàng đợi. Nhấp **Điều hướng** trên một tin nhắn đã xếp hàng để chèn lượt theo sau đó vào lượt đang chạy. + - Gõ `/stop` (hoặc các cụm từ hủy bỏ độc lập như `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) để hủy bỏ ngoài băng. + - `chat.abort` hỗ trợ `{ sessionKey }` (không có `runId`) để hủy bỏ mọi lượt chạy đang hoạt động cho phiên đó. - - - Khi một lượt chạy bị hủy, phần văn bản trợ lý chưa hoàn chỉnh vẫn có thể được hiển thị trong UI. - - Gateway lưu bền vững văn bản trợ lý chưa hoàn chỉnh đã hủy vào lịch sử bản ghi khi có đầu ra đã được đệm. - - Các mục được lưu bền vững bao gồm siêu dữ liệu hủy để bên tiêu thụ bản ghi có thể phân biệt phần chưa hoàn chỉnh do hủy với đầu ra hoàn tất thông thường. + + - Khi một lượt chạy bị hủy bỏ, văn bản trợ lý chưa hoàn chỉnh vẫn có thể được hiển thị trong UI. + - Gateway lưu bền văn bản trợ lý chưa hoàn chỉnh bị hủy bỏ vào lịch sử bản ghi khi có đầu ra được đệm. + - Các mục được lưu bền bao gồm siêu dữ liệu hủy bỏ để bên tiêu thụ bản ghi có thể phân biệt phần hủy bỏ chưa hoàn chỉnh với đầu ra hoàn tất thông thường. -## Cài đặt PWA và Web Push +## Cài đặt PWA và web push Control UI đi kèm `manifest.webmanifest` và một service worker, nên các trình duyệt hiện đại có thể cài đặt nó như một PWA độc lập. Web Push cho phép Gateway đánh thức PWA đã cài đặt bằng thông báo ngay cả khi tab hoặc cửa sổ trình duyệt không mở. | Bề mặt | Chức năng | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | Manifest PWA. Trình duyệt đề xuất "Install app" khi nó có thể truy cập được. | -| `ui/public/sw.js` | Service worker xử lý các sự kiện `push` và nhấp vào thông báo. | -| `push/vapid-keys.json` (trong thư mục trạng thái OpenClaw) | Cặp khóa VAPID được tạo tự động dùng để ký payload Web Push. | -| `push/web-push-subscriptions.json` | Các endpoint đăng ký trình duyệt được lưu bền vững. | +| `ui/public/manifest.webmanifest` | Manifest PWA. Trình duyệt đề xuất "Install app" khi nó truy cập được. | +| `ui/public/sw.js` | Service worker xử lý các sự kiện `push` và lượt nhấp thông báo. | +| `push/vapid-keys.json` (trong thư mục trạng thái OpenClaw) | Cặp khóa VAPID tự động tạo dùng để ký payload Web Push. | +| `push/web-push-subscriptions.json` | Các endpoint đăng ký trình duyệt được lưu bền. | -Ghi đè cặp khóa VAPID thông qua biến môi trường trên tiến trình Gateway khi bạn muốn ghim khóa (cho triển khai nhiều host, xoay vòng bí mật, hoặc kiểm thử): +Ghi đè cặp khóa VAPID thông qua biến môi trường trên tiến trình Gateway khi bạn muốn cố định khóa (cho triển khai nhiều host, xoay vòng secret, hoặc kiểm thử): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT` (mặc định là `mailto:openclaw@localhost`) -Control UI sử dụng các phương thức Gateway có phạm vi giới hạn này để đăng ký và kiểm thử đăng ký trình duyệt: +Control UI dùng các phương thức Gateway được giới hạn theo phạm vi này để đăng ký và kiểm thử đăng ký trình duyệt: - `push.web.vapidPublicKey` — lấy khóa công khai VAPID đang hoạt động. -- `push.web.subscribe` — đăng ký một `endpoint` cộng với `keys.p256dh`/`keys.auth`. +- `push.web.subscribe` — đăng ký một `endpoint` cùng `keys.p256dh`/`keys.auth`. - `push.web.unsubscribe` — xóa một endpoint đã đăng ký. -- `push.web.test` — gửi thông báo kiểm thử đến đăng ký của bên gọi. +- `push.web.test` — gửi một thông báo kiểm thử tới đăng ký của bên gọi. -Web Push độc lập với đường dẫn chuyển tiếp APNS iOS (xem [Cấu hình](/vi/gateway/configuration) để biết push được hỗ trợ bởi relay) và phương thức `push.test` hiện có, vốn nhắm đến ghép đôi di động native. +Web Push độc lập với đường dẫn chuyển tiếp APNS iOS (xem [Cấu hình](/vi/gateway/configuration) để biết push có relay hỗ trợ) và phương thức `push.test` hiện có, vốn nhắm tới ghép đôi di động native. -## Nhúng được lưu trữ +## Embed được host -Tin nhắn trợ lý có thể hiển thị nội dung web được lưu trữ trực tiếp bằng shortcode `[embed ...]`. Chính sách sandbox iframe được điều khiển bởi `gateway.controlUi.embedSandbox`: +Tin nhắn trợ lý có thể hiển thị nội dung web được host nội tuyến bằng shortcode `[embed ...]`. Chính sách sandbox iframe được điều khiển bởi `gateway.controlUi.embedSandbox`: - Tắt thực thi script bên trong nội dung nhúng được lưu trữ. + Tắt thực thi script bên trong các embed được host. - - Cho phép nội dung nhúng tương tác trong khi vẫn giữ cách ly origin; đây là mặc định và thường đủ cho các trò chơi/tiện ích trình duyệt độc lập. + + Cho phép embed tương tác trong khi vẫn giữ cô lập origin; đây là mặc định và thường đủ cho các trò chơi/widget trình duyệt tự chứa. - Thêm `allow-same-origin` trên nền `allow-scripts` cho tài liệu cùng site cố ý cần đặc quyền mạnh hơn. + Thêm `allow-same-origin` lên trên `allow-scripts` cho các tài liệu cùng site cố ý cần đặc quyền mạnh hơn. @@ -250,14 +254,14 @@ Ví dụ: ``` -Chỉ dùng `trusted` khi tài liệu nhúng thật sự cần hành vi cùng origin. Với hầu hết trò chơi và canvas tương tác do agent tạo, `scripts` là lựa chọn an toàn hơn. +Chỉ dùng `trusted` khi tài liệu được nhúng thật sự cần hành vi cùng origin. Với hầu hết trò chơi do agent tạo và canvas tương tác, `scripts` là lựa chọn an toàn hơn. -URL nhúng `http(s)` bên ngoài tuyệt đối vẫn bị chặn theo mặc định. Nếu bạn chủ ý muốn `[embed url="https://..."]` tải trang bên thứ ba, hãy đặt `gateway.controlUi.allowExternalEmbedUrls: true`. +Các URL embed `http(s)` bên ngoài tuyệt đối vẫn bị chặn theo mặc định. Nếu bạn cố ý muốn `[embed url="https://..."]` tải trang bên thứ ba, hãy đặt `gateway.controlUi.allowExternalEmbedUrls: true`. -## Chiều rộng tin nhắn trò chuyện +## Chiều rộng tin nhắn chat -Các tin nhắn trò chuyện được nhóm dùng max-width mặc định dễ đọc. Các triển khai màn hình rộng có thể ghi đè mà không cần vá CSS đóng gói bằng cách đặt `gateway.controlUi.chatMessageMaxWidth`: +Các tin nhắn chat được nhóm dùng max-width mặc định dễ đọc. Các triển khai màn hình rộng có thể ghi đè mà không cần vá CSS đi kèm bằng cách đặt `gateway.controlUi.chatMessageMaxWidth`: ```json5 { @@ -269,12 +273,12 @@ Các tin nhắn trò chuyện được nhóm dùng max-width mặc định dễ } ``` -Giá trị được xác thực trước khi tới trình duyệt. Các giá trị được hỗ trợ bao gồm độ dài và phần trăm thuần như `960px` hoặc `82%`, cùng các biểu thức chiều rộng ràng buộc `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, và `fit-content(...)`. +Giá trị được xác thực trước khi tới trình duyệt. Các giá trị được hỗ trợ bao gồm độ dài thuần và phần trăm như `960px` hoặc `82%`, cộng với các biểu thức chiều rộng có ràng buộc `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, và `fit-content(...)`. ## Truy cập tailnet (khuyến nghị) - + Giữ Gateway trên loopback và để Tailscale Serve proxy nó bằng HTTPS: ```bash @@ -285,16 +289,16 @@ Giá trị được xác thực trước khi tới trình duyệt. Các giá tr - `https:///` (hoặc `gateway.controlUi.basePath` đã cấu hình của bạn) - Theo mặc định, các yêu cầu Control UI/WebSocket Serve có thể xác thực qua header danh tính Tailscale (`tailscale-user-login`) khi `gateway.auth.allowTailscale` là `true`. OpenClaw xác minh danh tính bằng cách phân giải địa chỉ `x-forwarded-for` với `tailscale whois` và khớp nó với header, và chỉ chấp nhận các yêu cầu này khi chúng chạm loopback với các header `x-forwarded-*` của Tailscale. Với phiên toán tử Control UI có danh tính thiết bị trình duyệt, đường dẫn Serve đã xác minh này cũng bỏ qua vòng ghép đôi thiết bị; trình duyệt không có thiết bị và kết nối vai trò node vẫn đi theo kiểm tra thiết bị thông thường. Đặt `gateway.auth.allowTailscale: false` nếu bạn muốn yêu cầu thông tin xác thực bí mật dùng chung rõ ràng ngay cả với lưu lượng Serve. Sau đó dùng `gateway.auth.mode: "token"` hoặc `"password"`. + Theo mặc định, các yêu cầu Control UI/WebSocket Serve có thể xác thực qua header danh tính Tailscale (`tailscale-user-login`) khi `gateway.auth.allowTailscale` là `true`. OpenClaw xác minh danh tính bằng cách phân giải địa chỉ `x-forwarded-for` với `tailscale whois` và khớp nó với header, và chỉ chấp nhận các yêu cầu này khi yêu cầu đi vào loopback với các header `x-forwarded-*` của Tailscale. Với các phiên toán tử Control UI có danh tính thiết bị trình duyệt, đường dẫn Serve đã xác minh này cũng bỏ qua vòng ghép đôi thiết bị; trình duyệt không có thiết bị và kết nối vai trò node vẫn theo các kiểm tra thiết bị thông thường. Đặt `gateway.auth.allowTailscale: false` nếu bạn muốn yêu cầu thông tin xác thực shared-secret rõ ràng ngay cả với lưu lượng Serve. Sau đó dùng `gateway.auth.mode: "token"` hoặc `"password"`. - Với đường dẫn danh tính Serve bất đồng bộ đó, các lần xác thực thất bại cho cùng IP client và phạm vi xác thực được tuần tự hóa trước khi ghi giới hạn tốc độ. Vì vậy các lần thử lại sai đồng thời từ cùng trình duyệt có thể hiển thị `retry later` ở yêu cầu thứ hai thay vì hai lần không khớp thuần chạy đua song song. + Với đường dẫn danh tính Serve bất đồng bộ đó, các lần xác thực thất bại cho cùng IP máy khách và phạm vi xác thực được tuần tự hóa trước khi ghi giới hạn tốc độ. Vì vậy các lần thử lại sai đồng thời từ cùng trình duyệt có thể hiển thị `retry later` ở yêu cầu thứ hai thay vì hai lỗi không khớp thuần túy chạy đua song song. - Xác thực Serve không cần token giả định host gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin cậy có thể chạy trên host đó, hãy yêu cầu xác thực token/mật khẩu. + Xác thực Serve không token giả định host gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin cậy có thể chạy trên host đó, hãy yêu cầu xác thực token/password. - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` @@ -310,21 +314,21 @@ Giá trị được xác thực trước khi tới trình duyệt. Các giá tr ## HTTP không an toàn -Nếu bạn mở bảng điều khiển qua HTTP thuần (`http://` hoặc `http://`), trình duyệt chạy trong **ngữ cảnh không an toàn** và chặn WebCrypto. Theo mặc định, OpenClaw **chặn** các kết nối Control UI không có danh tính thiết bị. +Nếu bạn mở dashboard qua HTTP thuần (`http://` hoặc `http://`), trình duyệt chạy trong **ngữ cảnh không an toàn** và chặn WebCrypto. Theo mặc định, OpenClaw **chặn** các kết nối Control UI không có danh tính thiết bị. -Các ngoại lệ đã được ghi lại: +Các ngoại lệ đã được ghi nhận: -- tương thích HTTP không an toàn chỉ localhost với `gateway.controlUi.allowInsecureAuth=true` -- xác thực Control UI toán tử thành công qua `gateway.auth.mode: "trusted-proxy"` -- phương án khẩn cấp `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- khả năng tương thích HTTP không an toàn chỉ dành cho localhost với `gateway.controlUi.allowInsecureAuth=true` +- xác thực Control UI của người vận hành thành công thông qua `gateway.auth.mode: "trusted-proxy"` +- tùy chọn khẩn cấp `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**Cách khắc phục khuyến nghị:** dùng HTTPS (Tailscale Serve) hoặc mở UI cục bộ: +**Cách khắc phục được khuyến nghị:** dùng HTTPS (Tailscale Serve) hoặc mở UI cục bộ: - `https:///` (Serve) - `http://127.0.0.1:18789/` (trên máy chủ Gateway) - + ```json5 { gateway: { @@ -335,14 +339,14 @@ Các ngoại lệ đã được ghi lại: } ``` - `allowInsecureAuth` chỉ là công tắc tương thích cục bộ: + `allowInsecureAuth` chỉ là một tùy chọn tương thích cục bộ: - - Nó cho phép phiên Control UI trên localhost tiếp tục mà không cần danh tính thiết bị trong ngữ cảnh HTTP không bảo mật. - - Nó không bỏ qua kiểm tra ghép nối. + - Nó cho phép các phiên Control UI trên localhost tiếp tục mà không cần danh tính thiết bị trong các ngữ cảnh HTTP không an toàn. + - Nó không bỏ qua các kiểm tra ghép đôi. - Nó không nới lỏng yêu cầu danh tính thiết bị từ xa (không phải localhost). - + ```json5 { gateway: { @@ -354,14 +358,14 @@ Các ngoại lệ đã được ghi lại: ``` - `dangerouslyDisableDeviceAuth` tắt kiểm tra danh tính thiết bị của Control UI và là mức hạ cấp bảo mật nghiêm trọng. Hãy hoàn nguyên nhanh sau khi dùng trong tình huống khẩn cấp. + `dangerouslyDisableDeviceAuth` tắt các kiểm tra danh tính thiết bị của Control UI và là một sự hạ cấp bảo mật nghiêm trọng. Hãy hoàn nguyên nhanh chóng sau khi dùng trong tình huống khẩn cấp. - - Xác thực trusted-proxy thành công có thể cho phép các phiên Control UI của **operator** mà không cần danh tính thiết bị. - - Điều này **không** mở rộng sang các phiên Control UI vai trò node. - - Proxy ngược loopback cùng máy chủ vẫn không đáp ứng xác thực trusted-proxy; xem [Xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth). + - Xác thực trusted-proxy thành công có thể cho phép các phiên Control UI của **người vận hành** không cần danh tính thiết bị. + - Điều này **không** áp dụng cho các phiên Control UI có vai trò node. + - Reverse proxy local loopback trên cùng máy chủ vẫn không đáp ứng xác thực trusted-proxy; xem [Xác thực proxy đáng tin cậy](/vi/gateway/trusted-proxy-auth). @@ -370,40 +374,40 @@ Xem [Tailscale](/vi/gateway/tailscale) để biết hướng dẫn thiết lập ## Chính sách bảo mật nội dung -Control UI đi kèm chính sách `img-src` chặt chẽ: chỉ cho phép tài nguyên **cùng origin**, URL `data:`, và URL `blob:` được tạo cục bộ. URL hình ảnh `http(s)` từ xa và URL hình ảnh tương đối theo giao thức bị trình duyệt từ chối và không tạo yêu cầu mạng. +Control UI đi kèm với chính sách `img-src` chặt chẽ: chỉ cho phép tài nguyên **cùng nguồn gốc**, URL `data:`, và URL `blob:` được tạo cục bộ. Các URL hình ảnh từ xa `http(s)` và URL hình ảnh tương đối theo giao thức bị trình duyệt từ chối và không tạo yêu cầu mạng. -Điều này có nghĩa trong thực tế: +Điều này có ý nghĩa thực tế như sau: -- Avatar và hình ảnh được phục vụ dưới đường dẫn tương đối (ví dụ `/avatars/`) vẫn hiển thị, bao gồm các tuyến avatar đã xác thực mà UI tải về và chuyển đổi thành URL `blob:` cục bộ. -- URL `data:image/...` nội tuyến vẫn hiển thị (hữu ích cho payload trong giao thức). +- Avatar và hình ảnh được phục vụ dưới các đường dẫn tương đối (ví dụ `/avatars/`) vẫn hiển thị, bao gồm các route avatar đã xác thực mà UI tải về và chuyển đổi thành URL `blob:` cục bộ. +- URL nội tuyến `data:image/...` vẫn hiển thị (hữu ích cho payload trong giao thức). - URL `blob:` cục bộ do Control UI tạo vẫn hiển thị. -- URL avatar từ xa do siêu dữ liệu kênh phát ra bị loại bỏ tại các helper avatar của Control UI và được thay bằng logo/huy hiệu tích hợp, vì vậy một kênh bị xâm phạm hoặc độc hại không thể ép trình duyệt của operator tải hình ảnh từ xa tùy ý. +- URL avatar từ xa do siêu dữ liệu kênh phát ra bị loại bỏ tại các helper avatar của Control UI và được thay bằng logo/huy hiệu tích hợp sẵn, nên một kênh bị xâm phạm hoặc độc hại không thể buộc trình duyệt của người vận hành tải hình ảnh từ xa tùy ý. Bạn không cần thay đổi gì để có hành vi này — nó luôn bật và không thể cấu hình. -## Xác thực tuyến avatar +## Xác thực route avatar -Khi xác thực Gateway được cấu hình, endpoint avatar của Control UI yêu cầu cùng token Gateway như phần còn lại của API: +Khi xác thực gateway được cấu hình, endpoint avatar của Control UI yêu cầu cùng token gateway như phần còn lại của API: -- `GET /avatar/` chỉ trả về hình ảnh avatar cho bên gọi đã xác thực. `GET /avatar/?meta=1` trả về siêu dữ liệu avatar theo cùng quy tắc. -- Yêu cầu chưa xác thực tới một trong hai tuyến đều bị từ chối (khớp với tuyến assistant-media ngang cấp). Điều này ngăn tuyến avatar rò rỉ danh tính agent trên các máy chủ vốn được bảo vệ. -- Bản thân Control UI chuyển tiếp token Gateway dưới dạng header bearer khi tải avatar, và dùng URL blob đã xác thực để hình ảnh vẫn hiển thị trong dashboard. +- `GET /avatar/` chỉ trả về ảnh avatar cho caller đã xác thực. `GET /avatar/?meta=1` trả về siêu dữ liệu avatar theo cùng quy tắc. +- Các yêu cầu chưa xác thực tới một trong hai route đều bị từ chối (khớp với route assistant-media cùng cấp). Điều này ngăn route avatar làm rò rỉ danh tính agent trên các máy chủ vốn được bảo vệ. +- Bản thân Control UI chuyển tiếp token gateway dưới dạng bearer header khi tải avatar, và dùng URL blob đã xác thực để hình ảnh vẫn hiển thị trong dashboard. -Nếu bạn tắt xác thực Gateway (không khuyến nghị trên máy chủ dùng chung), tuyến avatar cũng trở thành không xác thực, nhất quán với phần còn lại của gateway. +Nếu bạn tắt xác thực gateway (không được khuyến nghị trên máy chủ dùng chung), route avatar cũng trở thành không cần xác thực, phù hợp với phần còn lại của gateway. -## Xác thực tuyến phương tiện assistant +## Xác thực route phương tiện của assistant -Khi xác thực Gateway được cấu hình, bản xem trước phương tiện cục bộ của assistant dùng tuyến hai bước: +Khi xác thực gateway được cấu hình, bản xem trước phương tiện cục bộ của assistant dùng route hai bước: -- `GET /__openclaw__/assistant-media?meta=1&source=` yêu cầu xác thực operator Control UI bình thường. Trình duyệt gửi token Gateway dưới dạng header bearer khi kiểm tra tính khả dụng. -- Phản hồi siêu dữ liệu thành công bao gồm `mediaTicket` ngắn hạn, bị giới hạn trong đúng đường dẫn nguồn đó. -- URL hình ảnh, âm thanh, video và tài liệu do trình duyệt hiển thị dùng `mediaTicket=` thay vì token hoặc mật khẩu Gateway đang hoạt động. Vé hết hạn nhanh và không thể cấp quyền cho nguồn khác. +- `GET /__openclaw__/assistant-media?meta=1&source=` yêu cầu xác thực người vận hành Control UI thông thường. Trình duyệt gửi token gateway dưới dạng bearer header khi kiểm tra tính khả dụng. +- Phản hồi siêu dữ liệu thành công bao gồm một `mediaTicket` tồn tại ngắn hạn, được giới hạn cho đúng đường dẫn nguồn đó. +- URL hình ảnh, âm thanh, video và tài liệu do trình duyệt hiển thị dùng `mediaTicket=` thay vì token gateway hoặc mật khẩu đang hoạt động. Vé hết hạn nhanh và không thể cấp quyền cho nguồn khác. -Điều này giữ cho việc hiển thị phương tiện bình thường tương thích với các phần tử phương tiện gốc của trình duyệt mà không đưa thông tin xác thực Gateway có thể tái sử dụng vào URL phương tiện hiển thị. +Điều này giữ cho việc hiển thị phương tiện thông thường tương thích với các phần tử phương tiện gốc của trình duyệt mà không đặt thông tin đăng nhập Gateway có thể tái sử dụng trong các URL phương tiện hiển thị. ## Xây dựng UI -Gateway phục vụ tệp tĩnh từ `dist/control-ui`. Xây dựng chúng bằng: +Gateway phục vụ các tệp tĩnh từ `dist/control-ui`. Xây dựng chúng bằng: ```bash pnpm ui:build @@ -425,7 +429,7 @@ Sau đó trỏ UI tới URL WS của Gateway (ví dụ `ws://127.0.0.1:18789`). ## Gỡ lỗi/kiểm thử: máy chủ dev + Gateway từ xa -Control UI là các tệp tĩnh; mục tiêu WebSocket có thể cấu hình và có thể khác với origin HTTP. Điều này hữu ích khi bạn muốn dùng máy chủ dev Vite cục bộ nhưng Gateway chạy ở nơi khác. +Control UI là các tệp tĩnh; mục tiêu WebSocket có thể cấu hình và có thể khác với nguồn gốc HTTP. Điều này hữu ích khi bạn muốn chạy máy chủ dev Vite cục bộ nhưng Gateway chạy ở nơi khác. @@ -450,16 +454,16 @@ Control UI là các tệp tĩnh; mục tiêu WebSocket có thể cấu hình và - `gatewayUrl` được lưu trong localStorage sau khi tải và bị xóa khỏi URL. - - Nếu bạn truyền endpoint `ws://` hoặc `wss://` đầy đủ qua `gatewayUrl`, hãy mã hóa URL giá trị `gatewayUrl` để trình duyệt phân tích chuỗi truy vấn chính xác. - - Nên truyền `token` qua fragment URL (`#token=...`) bất cứ khi nào có thể. Fragment không được gửi tới máy chủ, giúp tránh rò rỉ qua nhật ký yêu cầu và Referer. Tham số truy vấn cũ `?token=` vẫn được nhập một lần để tương thích, nhưng chỉ như phương án dự phòng, và bị loại bỏ ngay sau bootstrap. + - Nếu bạn truyền một endpoint `ws://` hoặc `wss://` đầy đủ qua `gatewayUrl`, hãy mã hóa URL giá trị `gatewayUrl` để trình duyệt phân tích chuỗi truy vấn chính xác. + - `token` nên được truyền qua fragment URL (`#token=...`) bất cứ khi nào có thể. Fragment không được gửi tới máy chủ, nhờ đó tránh rò rỉ qua log yêu cầu và Referer. Tham số truy vấn `?token=` cũ vẫn được nhập một lần để tương thích, nhưng chỉ làm phương án dự phòng, và bị loại bỏ ngay sau khi bootstrap. - `password` chỉ được giữ trong bộ nhớ. - - Khi `gatewayUrl` được đặt, UI không fallback sang thông tin xác thực từ cấu hình hoặc môi trường. Hãy cung cấp rõ ràng `token` (hoặc `password`). Thiếu thông tin xác thực rõ ràng là lỗi. + - Khi `gatewayUrl` được đặt, UI không fallback về thông tin đăng nhập từ cấu hình hoặc môi trường. Hãy cung cấp rõ `token` (hoặc `password`). Thiếu thông tin đăng nhập rõ ràng là lỗi. - Dùng `wss://` khi Gateway nằm sau TLS (Tailscale Serve, proxy HTTPS, v.v.). - `gatewayUrl` chỉ được chấp nhận trong cửa sổ cấp cao nhất (không nhúng) để ngăn clickjacking. - - Các triển khai Control UI không phải loopback phải đặt rõ ràng `gateway.controlUi.allowedOrigins` (origin đầy đủ). Điều này bao gồm các thiết lập dev từ xa. - - Lúc khởi động, Gateway có thể gieo các origin cục bộ như `http://localhost:` và `http://127.0.0.1:` từ bind và cổng runtime hiệu lực, nhưng origin trình duyệt từ xa vẫn cần mục nhập rõ ràng. - - Không dùng `gateway.controlUi.allowedOrigins: ["*"]` ngoại trừ kiểm thử cục bộ được kiểm soát chặt chẽ. Nó có nghĩa là cho phép mọi origin trình duyệt, không phải "khớp với bất kỳ máy chủ nào tôi đang dùng." - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` bật chế độ fallback origin theo header Host, nhưng đây là chế độ bảo mật nguy hiểm. + - Các triển khai Control UI không phải local loopback phải đặt `gateway.controlUi.allowedOrigins` rõ ràng (nguồn gốc đầy đủ). Điều này bao gồm các thiết lập dev từ xa. + - Khi khởi động, Gateway có thể khởi tạo các nguồn gốc cục bộ như `http://localhost:` và `http://127.0.0.1:` từ bind và cổng runtime hiệu lực, nhưng các nguồn gốc trình duyệt từ xa vẫn cần mục nhập rõ ràng. + - Không dùng `gateway.controlUi.allowedOrigins: ["*"]` trừ khi kiểm thử cục bộ được kiểm soát chặt chẽ. Nó có nghĩa là cho phép mọi nguồn gốc trình duyệt, không phải "khớp với bất kỳ máy chủ nào tôi đang dùng." + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` bật chế độ fallback nguồn gốc theo Host header, nhưng đây là một chế độ bảo mật nguy hiểm.