From 36a8586e821fa10933dc57bc9c49acef89442424 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 4 May 2026 02:28:17 +0000 Subject: [PATCH] chore(i18n): refresh vi translations --- docs/vi/channels/bluebubbles.md | 296 +++--- docs/vi/channels/broadcast-groups.md | 150 +-- docs/vi/channels/discord.md | 489 +++++----- docs/vi/channels/googlechat.md | 146 +-- docs/vi/channels/groups.md | 172 ++-- docs/vi/channels/irc.md | 71 +- docs/vi/channels/pairing.md | 113 ++- docs/vi/channels/qqbot.md | 100 +- docs/vi/channels/slack.md | 687 +++++++------- docs/vi/channels/tlon.md | 121 +-- docs/vi/channels/troubleshooting.md | 127 +-- docs/vi/cli/doctor.md | 66 +- docs/vi/concepts/agent.md | 124 +-- docs/vi/concepts/mantis.md | 280 +++--- docs/vi/concepts/progress-drafts.md | 190 ++-- docs/vi/concepts/qa-e2e-automation.md | 406 +++++---- docs/vi/concepts/queue-steering.md | 106 +-- docs/vi/concepts/queue.md | 96 +- docs/vi/concepts/system-prompt.md | 220 ++--- docs/vi/gateway/config-agents.md | 500 +++++----- docs/vi/gateway/config-channels.md | 318 +++---- docs/vi/gateway/configuration-examples.md | 51 +- docs/vi/gateway/opentelemetry.md | 174 ++-- docs/vi/gateway/operator-scopes.md | 109 +-- docs/vi/plugins/building-plugins.md | 223 ++--- docs/vi/plugins/google-meet.md | 1015 ++++++++++++--------- docs/vi/plugins/memory-wiki.md | 289 +++--- docs/vi/providers/openrouter.md | 144 +-- docs/vi/security/network-proxy.md | 143 +-- docs/vi/tools/llm-task.md | 59 +- docs/vi/tools/lobster.md | 126 +-- docs/vi/tools/slash-commands.md | 335 +++---- docs/vi/tools/steer.md | 84 ++ docs/vi/tools/subagents.md | 448 ++++----- docs/vi/tools/thinking.md | 125 +-- docs/vi/tools/web-fetch.md | 92 +- docs/vi/web/control-ui.md | 315 +++---- docs/vi/web/webchat.md | 100 +- 38 files changed, 4496 insertions(+), 4114 deletions(-) create mode 100644 docs/vi/tools/steer.md diff --git a/docs/vi/channels/bluebubbles.md b/docs/vi/channels/bluebubbles.md index 7ee460b09..af723c57f 100644 --- a/docs/vi/channels/bluebubbles.md +++ b/docs/vi/channels/bluebubbles.md @@ -4,45 +4,45 @@ read_when: - Khắc phục sự cố ghép nối Webhook - Cấu hình iMessage trên macOS sidebarTitle: BlueBubbles -summary: iMessage qua máy chủ macOS BlueBubbles (gửi/nhận qua REST, trạng thái đang nhập, phản ứng, ghép nối, thao tác nâng cao). +summary: iMessage qua máy chủ macOS BlueBubbles (gửi/nhận qua REST, trạng thái đang nhập, phản ứng, ghép đôi, hành động nâng cao). title: BlueBubbles x-i18n: - generated_at: "2026-05-01T10:46:14Z" + generated_at: "2026-05-04T02:21:38Z" model: gpt-5.5 provider: openai - source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145 + source_hash: 78a054da0c7c32b161997acd05914896259dd1a050e736a4c9e438a452ab6a51 source_path: channels/bluebubbles.md workflow: 16 --- -Trạng thái: Plugin đi kèm giao tiếp với máy chủ BlueBubbles macOS qua HTTP. **Được khuyến nghị cho tích hợp iMessage** nhờ API phong phú hơn và thiết lập dễ hơn so với kênh imsg cũ. +Status: Plugin được đóng gói sẵn giao tiếp với máy chủ BlueBubbles macOS qua HTTP. **Được khuyến nghị cho tích hợp iMessage** nhờ API phong phú hơn và thiết lập dễ hơn so với kênh imsg cũ. -Các bản phát hành OpenClaw hiện tại có kèm BlueBubbles, nên các bản dựng đóng gói thông thường không cần bước `openclaw plugins install` riêng. +Các bản phát hành OpenClaw hiện tại đóng gói BlueBubbles sẵn, vì vậy các bản dựng đóng gói thông thường không cần bước `openclaw plugins install` riêng. ## Tổng quan - Chạy trên macOS thông qua ứng dụng trợ giúp BlueBubbles ([bluebubbles.app](https://bluebubbles.app)). -- Khuyến nghị/đã kiểm thử: macOS Sequoia (15). macOS Tahoe (26) hoạt động; tính năng chỉnh sửa hiện đang hỏng trên Tahoe, và cập nhật biểu tượng nhóm có thể báo thành công nhưng không đồng bộ. -- OpenClaw giao tiếp với nó thông qua REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). +- Khuyến nghị/đã kiểm thử: macOS Sequoia (15). macOS Tahoe (26) hoạt động; tính năng chỉnh sửa hiện đang lỗi trên Tahoe, và các cập nhật biểu tượng nhóm có thể báo thành công nhưng không đồng bộ. +- OpenClaw giao tiếp với nó qua REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). - Tin nhắn đến được nhận qua Webhook; trả lời đi, chỉ báo đang nhập, biên nhận đã đọc và tapback là các lệnh gọi REST. -- Tệp đính kèm và nhãn dán được nạp dưới dạng phương tiện đến (và được hiển thị cho tác nhân khi có thể). -- Phản hồi Auto-TTS tổng hợp âm thanh MP3 hoặc CAF được gửi dưới dạng bong bóng ghi âm iMessage thay vì tệp đính kèm thông thường. -- Ghép cặp/danh sách cho phép hoạt động giống các kênh khác (`/channels/pairing` v.v.) với `channels.bluebubbles.allowFrom` + mã ghép cặp. -- Phản ứng được hiển thị dưới dạng sự kiện hệ thống giống Slack/Telegram để tác nhân có thể "nhắc đến" chúng trước khi trả lời. +- Tệp đính kèm và nhãn dán được nhập dưới dạng phương tiện đến (và được hiển thị cho agent khi có thể). +- Các trả lời Auto-TTS tổng hợp âm thanh MP3 hoặc CAF được gửi dưới dạng bong bóng ghi âm giọng nói iMessage thay vì tệp đính kèm thông thường. +- Ghép nối/danh sách cho phép hoạt động giống các kênh khác (`/channels/pairing` v.v.) với `channels.bluebubbles.allowFrom` + mã ghép nối. +- Phản ứng được hiển thị dưới dạng sự kiện hệ thống giống Slack/Telegram để agent có thể "nhắc đến" chúng trước khi trả lời. - Tính năng nâng cao: chỉnh sửa, thu hồi gửi, luồng trả lời, hiệu ứng tin nhắn, quản lý nhóm. ## Bắt đầu nhanh - + Cài đặt máy chủ BlueBubbles trên máy Mac của bạn (làm theo hướng dẫn tại [bluebubbles.app/install](https://bluebubbles.app/install)). - + Trong cấu hình BlueBubbles, bật web API và đặt mật khẩu. - + Chạy `openclaw onboard` và chọn BlueBubbles, hoặc cấu hình thủ công: ```json5 @@ -59,11 +59,11 @@ Các bản phát hành OpenClaw hiện tại có kèm BlueBubbles, nên các b ``` - - Trỏ Webhook BlueBubbles tới Gateway của bạn (ví dụ: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). + + Trỏ Webhook của BlueBubbles đến gateway của bạn (ví dụ: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). - - Khởi động Gateway; nó sẽ đăng ký trình xử lý Webhook và bắt đầu ghép cặp. + + Khởi động gateway; nó sẽ đăng ký trình xử lý Webhook và bắt đầu ghép nối. @@ -71,17 +71,17 @@ Các bản phát hành OpenClaw hiện tại có kèm BlueBubbles, nên các b **Bảo mật** - Luôn đặt mật khẩu Webhook. -- Xác thực Webhook luôn là bắt buộc. OpenClaw từ chối các yêu cầu Webhook BlueBubbles trừ khi chúng chứa mật khẩu/guid khớp với `channels.bluebubbles.password` (ví dụ `?password=` hoặc `x-password`), bất kể cấu trúc liên kết local loopback/proxy. -- Xác thực mật khẩu được kiểm tra trước khi đọc/phân tích cú pháp toàn bộ phần thân Webhook. +- Xác thực Webhook luôn bắt buộc. OpenClaw từ chối các yêu cầu Webhook BlueBubbles trừ khi chúng bao gồm mật khẩu/guid khớp với `channels.bluebubbles.password` (ví dụ `?password=` hoặc `x-password`), bất kể cấu trúc mạng loopback/proxy. +- Xác thực mật khẩu được kiểm tra trước khi đọc/phân tích toàn bộ phần thân Webhook. -## Giữ Messages.app hoạt động (thiết lập VM / không có giao diện) +## Giữ Messages.app hoạt động (thiết lập VM / headless) -Một số thiết lập macOS VM / luôn bật có thể khiến Messages.app chuyển sang trạng thái "nhàn rỗi" (sự kiện đến dừng lại cho đến khi ứng dụng được mở/đưa lên nền trước). Cách khắc phục đơn giản là **đánh thức Messages mỗi 5 phút** bằng AppleScript + LaunchAgent. +Một số thiết lập macOS VM / luôn bật có thể khiến Messages.app chuyển sang trạng thái "rảnh" (sự kiện đến dừng cho đến khi ứng dụng được mở/đưa lên foreground). Cách khắc phục đơn giản là **đánh thức Messages mỗi 5 phút** bằng AppleScript + LaunchAgent. - + Lưu nội dung này thành `~/Scripts/poke-messages.scpt`: ```applescript @@ -100,7 +100,7 @@ Một số thiết lập macOS VM / luôn bật có thể khiến Messages.app c ``` - + Lưu nội dung này thành `~/Library/LaunchAgents/com.user.poke-messages.plist`: ```xml @@ -132,10 +132,10 @@ Một số thiết lập macOS VM / luôn bật có thể khiến Messages.app c ``` - Tác vụ này chạy **mỗi 300 giây** và **khi đăng nhập**. Lần chạy đầu tiên có thể kích hoạt lời nhắc **Automation** của macOS (`osascript` → Messages). Hãy phê duyệt chúng trong cùng phiên người dùng chạy LaunchAgent. + Nội dung này chạy **mỗi 300 giây** và **khi đăng nhập**. Lần chạy đầu tiên có thể kích hoạt lời nhắc **Automation** của macOS (`osascript` → Messages). Hãy phê duyệt chúng trong cùng phiên người dùng chạy LaunchAgent. - + ```bash launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist @@ -151,21 +151,21 @@ BlueBubbles có sẵn trong onboarding tương tác: openclaw onboard ``` -Trình hướng dẫn sẽ hỏi: +Trình hướng dẫn nhắc nhập: - + Địa chỉ máy chủ BlueBubbles (ví dụ: `http://192.168.1.100:1234`). - + Mật khẩu API từ cài đặt BlueBubbles Server. - + Đường dẫn endpoint Webhook. - + `pairing`, `allowlist`, `open`, hoặc `disabled`. - + Số điện thoại, email hoặc mục tiêu trò chuyện. @@ -178,30 +178,30 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor ## Kiểm soát truy cập (DM + nhóm) - + - Mặc định: `channels.bluebubbles.dmPolicy = "pairing"`. - - Người gửi không xác định nhận mã ghép cặp; tin nhắn bị bỏ qua cho đến khi được phê duyệt (mã hết hạn sau 1 giờ). + - Người gửi không xác định nhận mã ghép nối; tin nhắn bị bỏ qua cho đến khi được phê duyệt (mã hết hạn sau 1 giờ). - Phê duyệt qua: - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` - - Ghép cặp là cơ chế trao đổi token mặc định. Chi tiết: [Ghép cặp](/vi/channels/pairing) + - Ghép nối là trao đổi token mặc định. Chi tiết: [Ghép nối](/vi/channels/pairing) - + - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (mặc định: `allowlist`). - `channels.bluebubbles.groupAllowFrom` kiểm soát ai có thể kích hoạt trong nhóm khi `allowlist` được đặt. -### Làm giàu tên liên hệ (macOS, tùy chọn) +### Bổ sung tên liên hệ (macOS, tùy chọn) -Webhook nhóm BlueBubbles thường chỉ bao gồm địa chỉ thô của người tham gia. Nếu bạn muốn ngữ cảnh `GroupMembers` hiển thị tên liên hệ cục bộ thay vào đó, bạn có thể chọn bật làm giàu Contacts cục bộ trên macOS: +Webhook nhóm BlueBubbles thường chỉ bao gồm địa chỉ thô của người tham gia. Nếu bạn muốn ngữ cảnh `GroupMembers` hiển thị tên liên hệ cục bộ thay vào đó, bạn có thể chọn bật bổ sung từ Contacts cục bộ trên macOS: - `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` bật tra cứu. Mặc định: `false`. -- Tra cứu chỉ chạy sau khi quyền truy cập nhóm, ủy quyền lệnh và cổng nhắc đến đã cho phép tin nhắn đi qua. -- Chỉ người tham gia bằng số điện thoại chưa có tên được làm giàu. -- Số điện thoại thô vẫn là giá trị dự phòng khi không tìm thấy kết quả khớp cục bộ. +- Tra cứu chỉ chạy sau khi truy cập nhóm, ủy quyền lệnh và kiểm soát nhắc đến đã cho phép tin nhắn đi qua. +- Chỉ những người tham gia bằng số điện thoại chưa có tên mới được bổ sung. +- Số điện thoại thô vẫn là phương án dự phòng khi không tìm thấy khớp cục bộ. ```json5 { @@ -213,13 +213,13 @@ Webhook nhóm BlueBubbles thường chỉ bao gồm địa chỉ thô của ngư } ``` -### Cổng nhắc đến (nhóm) +### Kiểm soát nhắc đến (nhóm) -BlueBubbles hỗ trợ cổng nhắc đến cho trò chuyện nhóm, khớp với hành vi iMessage/WhatsApp: +BlueBubbles hỗ trợ kiểm soát nhắc đến cho trò chuyện nhóm, khớp với hành vi iMessage/WhatsApp: -- Dùng `agents.list[].groupChat.mentionPatterns` (hoặc `messages.groupChat.mentionPatterns`) để phát hiện nhắc đến. -- Khi `requireMention` được bật cho một nhóm, tác nhân chỉ phản hồi khi được nhắc đến. -- Lệnh điều khiển từ người gửi được ủy quyền bỏ qua cổng nhắc đến. +- Sử dụng `agents.list[].groupChat.mentionPatterns` (hoặc `messages.groupChat.mentionPatterns`) để phát hiện nhắc đến. +- Khi `requireMention` được bật cho một nhóm, agent chỉ trả lời khi được nhắc đến. +- Lệnh điều khiển từ người gửi được ủy quyền bỏ qua kiểm soát nhắc đến. Cấu hình theo nhóm: @@ -238,15 +238,15 @@ Cấu hình theo nhóm: } ``` -### Cổng lệnh +### Kiểm soát lệnh - Lệnh điều khiển (ví dụ: `/config`, `/model`) yêu cầu ủy quyền. -- Dùng `allowFrom` và `groupAllowFrom` để xác định ủy quyền lệnh. +- Sử dụng `allowFrom` và `groupAllowFrom` để xác định ủy quyền lệnh. - Người gửi được ủy quyền có thể chạy lệnh điều khiển ngay cả khi không nhắc đến trong nhóm. -### Prompt hệ thống theo nhóm +### System prompt theo nhóm -Mỗi mục trong `channels.bluebubbles.groups.*` chấp nhận chuỗi `systemPrompt` tùy chọn. Giá trị này được chèn vào prompt hệ thống của tác nhân ở mọi lượt xử lý tin nhắn trong nhóm đó, nhờ đó bạn có thể đặt persona hoặc quy tắc hành vi theo nhóm mà không cần chỉnh sửa prompt của tác nhân: +Mỗi mục trong `channels.bluebubbles.groups.*` chấp nhận chuỗi `systemPrompt` tùy chọn. Giá trị này được đưa vào system prompt của agent trong mỗi lượt xử lý tin nhắn trong nhóm đó, vì vậy bạn có thể đặt persona hoặc quy tắc hành vi theo nhóm mà không cần chỉnh sửa prompt của agent: ```json5 { @@ -262,11 +262,11 @@ Mỗi mục trong `channels.bluebubbles.groups.*` chấp nhận chuỗi `systemP } ``` -Khóa khớp với bất kỳ giá trị nào BlueBubbles báo cáo dưới dạng `chatGuid` / `chatIdentifier` / `chatId` dạng số cho nhóm, và mục ký tự đại diện `"*"` cung cấp mặc định cho mọi nhóm không có kết quả khớp chính xác (cùng mẫu được dùng bởi `requireMention` và chính sách công cụ theo nhóm). Kết quả khớp chính xác luôn thắng ký tự đại diện. DM bỏ qua trường này; hãy dùng tùy chỉnh prompt cấp tác nhân hoặc cấp tài khoản thay thế. +Khóa khớp với bất cứ gì BlueBubbles báo cáo là `chatGuid` / `chatIdentifier` / `chatId` dạng số cho nhóm, và mục ký tự đại diện `"*"` cung cấp mặc định cho mọi nhóm không có khớp chính xác (cùng mẫu được dùng bởi `requireMention` và chính sách công cụ theo nhóm). Khớp chính xác luôn được ưu tiên hơn ký tự đại diện. DM bỏ qua trường này; thay vào đó hãy dùng tùy chỉnh prompt cấp agent hoặc cấp tài khoản. -#### Ví dụ hoàn chỉnh: trả lời theo luồng và phản ứng tapback (API riêng tư) +#### Ví dụ thực tế: trả lời theo luồng và phản ứng tapback (Private API) -Khi BlueBubbles Private API được bật, tin nhắn đến có ID tin nhắn ngắn (ví dụ `[[reply_to:5]]`) và tác nhân có thể gọi `action=reply` để trả lời theo luồng vào một tin nhắn cụ thể hoặc `action=react` để thả tapback. `systemPrompt` theo nhóm là cách đáng tin cậy để giữ tác nhân chọn đúng công cụ: +Khi BlueBubbles Private API được bật, tin nhắn đến có ID tin nhắn ngắn (ví dụ `[[reply_to:5]]`) và agent có thể gọi `action=reply` để trả lời theo luồng vào một tin nhắn cụ thể hoặc `action=react` để thả tapback. `systemPrompt` theo nhóm là cách đáng tin cậy để giữ cho agent chọn đúng công cụ: ```json5 { @@ -274,15 +274,7 @@ Khi BlueBubbles Private API được bật, tin nhắn đến có ID tin nhắn bluebubbles: { groups: { "iMessage;+;chat-family": { - systemPrompt: [ - "When replying in this group, always call action=reply with the", - "[[reply_to:N]] messageId from context so your response threads", - "under the triggering message. Never send a new unlinked message.", - "", - "For short acknowledgements ('ok', 'got it', 'on it'), use", - "action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓)", - "instead of sending a text reply.", - ].join(" "), + systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.", }, }, }, @@ -292,18 +284,18 @@ Khi BlueBubbles Private API được bật, tin nhắn đến có ID tin nhắn Cả phản ứng tapback và trả lời theo luồng đều yêu cầu BlueBubbles Private API; xem [Hành động nâng cao](#advanced-actions) và [ID tin nhắn](#message-ids-short-vs-full) để biết cơ chế nền tảng. -## Liên kết cuộc trò chuyện ACP +## Liên kết hội thoại ACP -Trò chuyện BlueBubbles có thể được chuyển thành workspace ACP bền vững mà không cần thay đổi lớp truyền tải. +Các cuộc trò chuyện BlueBubbles có thể được chuyển thành không gian làm việc ACP bền vững mà không thay đổi lớp vận chuyển. -Luồng nhanh cho người vận hành: +Luồng thao tác nhanh: - Chạy `/acp spawn codex --bind here` bên trong DM hoặc trò chuyện nhóm được cho phép. -- Các tin nhắn sau này trong cùng cuộc trò chuyện BlueBubbles đó sẽ được định tuyến tới phiên ACP đã tạo. -- `/new` và `/reset` đặt lại cùng phiên ACP đã liên kết tại chỗ. +- Các tin nhắn sau này trong cùng cuộc hội thoại BlueBubbles đó sẽ được định tuyến đến phiên ACP đã được sinh ra. +- `/new` và `/reset` đặt lại cùng phiên ACP đã liên kết ngay tại chỗ. - `/acp close` đóng phiên ACP và xóa liên kết. -Liên kết bền vững được cấu hình cũng được hỗ trợ thông qua các mục `bindings[]` cấp cao nhất với `type: "acp"` và `match.channel: "bluebubbles"`. +Các liên kết bền vững đã cấu hình cũng được hỗ trợ thông qua các mục `bindings[]` cấp cao nhất với `type: "acp"` và `match.channel: "bluebubbles"`. `match.peer.id` có thể dùng bất kỳ dạng mục tiêu BlueBubbles nào được hỗ trợ: @@ -312,7 +304,7 @@ Liên kết bền vững được cấu hình cũng được hỗ trợ thông q - `chat_guid:` - `chat_identifier:` -Đối với liên kết nhóm ổn định, ưu tiên `chat_id:*` hoặc `chat_identifier:*`. +Để có liên kết nhóm ổn định, nên dùng `chat_id:*` hoặc `chat_identifier:*`. Ví dụ: @@ -344,11 +336,11 @@ Ví dụ: } ``` -Xem [Tác nhân ACP](/vi/tools/acp-agents) để biết hành vi liên kết ACP dùng chung. +Xem [Agent ACP](/vi/tools/acp-agents) để biết hành vi liên kết ACP dùng chung. ## Đang nhập + biên nhận đã đọc -- **Chỉ báo đang nhập**: Được gửi tự động trước và trong quá trình tạo phản hồi. +- **Chỉ báo đang nhập**: Được gửi tự động trước và trong khi tạo phản hồi. - **Biên nhận đã đọc**: Được kiểm soát bởi `channels.bluebubbles.sendReadReceipts` (mặc định: `true`). - **Chỉ báo đang nhập**: OpenClaw gửi sự kiện bắt đầu nhập; BlueBubbles tự động xóa trạng thái đang nhập khi gửi hoặc hết thời gian chờ (dừng thủ công qua DELETE không đáng tin cậy). @@ -389,19 +381,19 @@ BlueBubbles hỗ trợ các hành động tin nhắn nâng cao khi được bậ ``` - - - **react**: Thêm/xóa phản ứng tapback (`messageId`, `emoji`, `remove`). Bộ tapback gốc của iMessage là `love`, `like`, `dislike`, `laugh`, `emphasize` và `question`. Khi một agent chọn emoji nằm ngoài bộ đó (ví dụ `👀`), công cụ phản ứng sẽ chuyển về `love` để tapback vẫn hiển thị thay vì làm hỏng toàn bộ yêu cầu. Các phản ứng xác nhận đã cấu hình vẫn được xác thực nghiêm ngặt và báo lỗi với giá trị không xác định. + + - **react**: Thêm/xóa phản ứng tapback (`messageId`, `emoji`, `remove`). Bộ tapback gốc của iMessage là `love`, `like`, `dislike`, `laugh`, `emphasize` và `question`. Khi một agent chọn emoji ngoài bộ đó (ví dụ `👀`), công cụ phản ứng sẽ chuyển về `love` để tapback vẫn hiển thị thay vì làm hỏng toàn bộ yêu cầu. Các phản ứng ack đã cấu hình vẫn được xác thực nghiêm ngặt và báo lỗi với giá trị không xác định. - **edit**: Chỉnh sửa một tin nhắn đã gửi (`messageId`, `text`). - **unsend**: Thu hồi một tin nhắn (`messageId`). - **reply**: Trả lời một tin nhắn cụ thể (`messageId`, `text`, `to`). - - **sendWithEffect**: Gửi kèm hiệu ứng iMessage (`text`, `to`, `effectId`). + - **sendWithEffect**: Gửi với hiệu ứng iMessage (`text`, `to`, `effectId`). - **renameGroup**: Đổi tên một cuộc trò chuyện nhóm (`chatGuid`, `displayName`). - - **setGroupIcon**: Đặt biểu tượng/ảnh cho cuộc trò chuyện nhóm (`chatGuid`, `media`) — không ổn định trên macOS 26 Tahoe (API có thể trả về thành công nhưng biểu tượng không đồng bộ). - - **addParticipant**: Thêm ai đó vào một nhóm (`chatGuid`, `address`). - - **removeParticipant**: Xóa ai đó khỏi một nhóm (`chatGuid`, `address`). - - **leaveGroup**: Rời khỏi một cuộc trò chuyện nhóm (`chatGuid`). + - **setGroupIcon**: Đặt biểu tượng/ảnh của cuộc trò chuyện nhóm (`chatGuid`, `media`) — không ổn định trên macOS 26 Tahoe (API có thể trả về thành công nhưng biểu tượng không đồng bộ). + - **addParticipant**: Thêm một người vào nhóm (`chatGuid`, `address`). + - **removeParticipant**: Xóa một người khỏi nhóm (`chatGuid`, `address`). + - **leaveGroup**: Rời một cuộc trò chuyện nhóm (`chatGuid`). - **upload-file**: Gửi phương tiện/tệp (`to`, `buffer`, `filename`, `asVoice`). - - Ghi âm thoại: đặt `asVoice: true` với âm thanh **MP3** hoặc **CAF** để gửi dưới dạng tin nhắn thoại iMessage. BlueBubbles chuyển đổi MP3 → CAF khi gửi ghi âm thoại. + - Bản ghi âm thoại: đặt `asVoice: true` với âm thanh **MP3** hoặc **CAF** để gửi dưới dạng tin nhắn thoại iMessage. BlueBubbles chuyển đổi MP3 → CAF khi gửi bản ghi âm thoại. - Bí danh cũ: `sendAttachment` vẫn hoạt động, nhưng `upload-file` là tên hành động chuẩn. @@ -414,43 +406,43 @@ OpenClaw có thể hiển thị ID tin nhắn _ngắn_ (ví dụ: `1`, `2`) đ - `MessageSid` / `ReplyToId` có thể là ID ngắn. - `MessageSidFull` / `ReplyToIdFull` chứa ID đầy đủ của nhà cung cấp. - ID ngắn nằm trong bộ nhớ; chúng có thể hết hạn khi khởi động lại hoặc khi cache bị loại bỏ. -- Hành động chấp nhận `messageId` ngắn hoặc đầy đủ, nhưng ID ngắn sẽ báo lỗi nếu không còn khả dụng. +- Các hành động chấp nhận `messageId` ngắn hoặc đầy đủ, nhưng ID ngắn sẽ báo lỗi nếu không còn khả dụng. Dùng ID đầy đủ cho tự động hóa và lưu trữ bền vững: - Mẫu: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` -- Ngữ cảnh: `MessageSidFull` / `ReplyToIdFull` trong payload gửi đến +- Ngữ cảnh: `MessageSidFull` / `ReplyToIdFull` trong payload đến Xem [Cấu hình](/vi/gateway/configuration) để biết các biến mẫu. -## Gộp các DM gửi tách rời (lệnh + URL trong một lần soạn) +## Gộp DM gửi tách (lệnh + URL trong cùng một lần soạn) -Khi người dùng nhập một lệnh và một URL cùng nhau trong iMessage — ví dụ `Dump https://example.com/article` — Apple tách lần gửi thành **hai lượt chuyển phát webhook riêng biệt**: +Khi người dùng nhập một lệnh và một URL cùng nhau trong iMessage — ví dụ `Dump https://example.com/article` — Apple tách lần gửi thành **hai lần phân phối webhook riêng biệt**: 1. Một tin nhắn văn bản (`"Dump"`). -2. Một bong bóng xem trước URL (`"https://..."`) với các ảnh xem trước OG dưới dạng tệp đính kèm. +2. Một bong bóng xem trước URL (`"https://..."`) có ảnh xem trước OG làm tệp đính kèm. -Hai webhook đến OpenClaw cách nhau khoảng 0,8-2,0 giây trên hầu hết các thiết lập. Nếu không gộp, agent chỉ nhận lệnh ở lượt 1, trả lời (thường là "gửi URL cho tôi"), và chỉ thấy URL ở lượt 2 — lúc đó ngữ cảnh lệnh đã bị mất. +Hai webhook đến OpenClaw cách nhau khoảng 0,8-2,0 giây trên hầu hết thiết lập. Nếu không gộp, agent nhận riêng lệnh ở lượt 1, trả lời (thường là "gửi cho tôi URL"), và chỉ thấy URL ở lượt 2 — lúc đó ngữ cảnh lệnh đã mất. -`channels.bluebubbles.coalesceSameSenderDms` chọn cho một DM gộp các webhook liên tiếp từ cùng một người gửi thành một lượt agent duy nhất. Trò chuyện nhóm vẫn tiếp tục khóa theo từng tin nhắn để giữ nguyên cấu trúc lượt của nhiều người dùng. +`channels.bluebubbles.coalesceSameSenderDms` chọn cho một DM tham gia việc hợp nhất các webhook liên tiếp từ cùng người gửi thành một lượt agent duy nhất. Trò chuyện nhóm tiếp tục khóa theo từng tin nhắn để giữ nguyên cấu trúc lượt nhiều người dùng. - + Bật khi: - - Bạn cung cấp Skills mong đợi `command + payload` trong một tin nhắn (dump, paste, save, queue, v.v.). - - Người dùng của bạn dán URL, hình ảnh hoặc nội dung dài kèm theo lệnh. + - Bạn phát hành skills kỳ vọng `command + payload` trong một tin nhắn (dump, paste, save, queue, v.v.). + - Người dùng của bạn dán URL, hình ảnh hoặc nội dung dài cùng với lệnh. - Bạn có thể chấp nhận độ trễ lượt DM tăng thêm (xem bên dưới). - Giữ tắt khi: + Để tắt khi: - Bạn cần độ trễ lệnh tối thiểu cho các trigger DM một từ. - Tất cả luồng của bạn là lệnh một lần không có payload theo sau. - + ```json5 { channels: { @@ -461,7 +453,7 @@ Hai webhook đến OpenClaw cách nhau khoảng 0,8-2,0 giây trên hầu hết } ``` - Khi bật cờ và không có `messages.inbound.byChannel.bluebubbles` rõ ràng, cửa sổ debounce mở rộng thành **2500 ms** (mặc định khi không gộp là 500 ms). Cửa sổ rộng hơn là bắt buộc — nhịp gửi tách của Apple ở mức 0.8-2.0 giây không phù hợp với mặc định chặt hơn. + Khi bật cờ và không có `messages.inbound.byChannel.bluebubbles` rõ ràng, cửa sổ debounce mở rộng thành **2500 ms** (mặc định cho trường hợp không gộp là 500 ms). Cửa sổ rộng hơn là bắt buộc — nhịp gửi tách 0,8-2,0 giây của Apple không vừa với mặc định chặt hơn. Để tự tinh chỉnh cửa sổ: @@ -480,62 +472,62 @@ Hai webhook đến OpenClaw cách nhau khoảng 0,8-2,0 giây trên hầu hết ``` - - - **Tăng độ trễ cho các lệnh điều khiển DM.** Khi bật cờ, các tin nhắn lệnh điều khiển DM (như `Dump`, `Save`, v.v.) giờ sẽ chờ tối đa bằng cửa sổ debounce trước khi chuyển tiếp, phòng trường hợp một Webhook tải trọng sắp đến. Lệnh trong cuộc trò chuyện nhóm vẫn được chuyển tiếp tức thì. - - **Đầu ra đã gộp có giới hạn** — văn bản đã gộp giới hạn ở 4000 ký tự với dấu `…[truncated]` rõ ràng; tệp đính kèm giới hạn ở 20; mục nguồn giới hạn ở 10 (giữ lại mục đầu tiên và mới nhất nếu vượt quá). Mọi `messageId` nguồn vẫn đi qua khử trùng lặp đầu vào để một lần phát lại MessagePoller sau đó của bất kỳ sự kiện riêng lẻ nào cũng được nhận diện là bản sao. - - **Bật tùy chọn, theo từng kênh.** Các kênh khác (Telegram, WhatsApp, Slack, …) không bị ảnh hưởng. + + - **Tăng độ trễ cho lệnh điều khiển DM.** Khi bật cờ, các tin nhắn lệnh điều khiển DM (như `Dump`, `Save`, v.v.) giờ sẽ chờ tối đa đến cửa sổ debounce trước khi gửi đi, phòng trường hợp webhook payload sắp đến. Lệnh trong trò chuyện nhóm vẫn được gửi ngay. + - **Đầu ra đã gộp có giới hạn** — văn bản đã gộp giới hạn ở 4000 ký tự với dấu `…[truncated]` rõ ràng; tệp đính kèm giới hạn ở 20; mục nguồn giới hạn ở 10 (giữ mục đầu tiên cộng mới nhất khi vượt quá). Mỗi `messageId` nguồn vẫn đi tới inbound-dedupe để một lần phát lại MessagePoller sau này của bất kỳ sự kiện riêng lẻ nào cũng được nhận diện là trùng lặp. + - **Chọn tham gia theo từng kênh.** Các kênh khác (Telegram, WhatsApp, Slack, …) không bị ảnh hưởng. -### Các kịch bản và những gì tác tử thấy +### Các tình huống và những gì agent thấy -| Người dùng soạn | Apple phân phối | Tắt cờ (mặc định) | Bật cờ + cửa sổ 2500 ms | -| ------------------------------------------------------------------ | --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ | -| `Dump https://example.com` (một lần gửi) | 2 Webhook cách nhau ~1 giây | Hai lượt tác tử: chỉ "Dump", rồi đến URL | Một lượt: văn bản đã gộp `Dump https://example.com` | -| `Save this 📎image.jpg caption` (tệp đính kèm + văn bản) | 2 Webhook | Hai lượt | Một lượt: văn bản + hình ảnh | -| `/status` (lệnh độc lập) | 1 Webhook | Chuyển tiếp tức thì | **Chờ tối đa bằng cửa sổ, rồi chuyển tiếp** | -| URL được dán riêng | 1 Webhook | Chuyển tiếp tức thì | Chuyển tiếp tức thì (chỉ một mục trong nhóm) | -| Văn bản + URL được gửi thành hai tin nhắn riêng có chủ ý, cách nhau vài phút | 2 Webhook ngoài cửa sổ | Hai lượt | Hai lượt (cửa sổ hết hạn giữa chúng) | -| Luồng gửi nhanh (>10 DM nhỏ trong cửa sổ) | N Webhook | N lượt | Một lượt, đầu ra có giới hạn (áp dụng giới hạn đầu + mới nhất, văn bản/tệp đính kèm) | +| Người dùng soạn | Apple phân phối | Tắt cờ (mặc định) | Bật cờ + cửa sổ 2500 ms | +| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- | +| `Dump https://example.com` (một lần gửi) | 2 webhook cách nhau ~1 giây | Hai lượt agent: chỉ có "Dump", rồi URL | Một lượt: văn bản đã gộp `Dump https://example.com` | +| `Save this 📎image.jpg caption` (tệp đính kèm + văn bản) | 2 webhook | Hai lượt | Một lượt: văn bản + hình ảnh | +| `/status` (lệnh độc lập) | 1 webhook | Gửi ngay | **Chờ tối đa đến cửa sổ, rồi gửi** | +| Chỉ dán URL | 1 webhook | Gửi ngay | Gửi ngay (chỉ một mục trong bucket) | +| Văn bản + URL được gửi thành hai tin nhắn riêng có chủ ý, cách nhau vài phút | 2 webhook ngoài cửa sổ | Hai lượt | Hai lượt (cửa sổ hết hạn giữa chúng) | +| Dồn nhanh (>10 DM nhỏ trong cửa sổ) | N webhook | N lượt | Một lượt, đầu ra có giới hạn (áp dụng giới hạn mục đầu + mới nhất, văn bản/tệp đính kèm) | -### Khắc phục sự cố gộp lượt gửi tách +### Khắc phục sự cố gộp gửi tách -Nếu cờ đã bật nhưng các lượt gửi tách vẫn đến thành hai lượt, hãy kiểm tra từng lớp: +Nếu cờ đã bật mà các lần gửi tách vẫn đến thành hai lượt, hãy kiểm tra từng lớp: - + ``` grep coalesceSameSenderDms ~/.openclaw/openclaw.json ``` - Sau đó chạy `openclaw gateway restart` — cờ được đọc khi tạo sổ đăng ký debounce. + Sau đó `openclaw gateway restart` — cờ được đọc khi tạo debouncer-registry. - - Xem nhật ký máy chủ BlueBubbles tại `~/Library/Logs/bluebubbles-server/main.log`: + + Xem log máy chủ BlueBubbles trong `~/Library/Logs/bluebubbles-server/main.log`: ``` grep -E "Dispatching event to webhook" main.log | tail -20 ``` - Đo khoảng cách giữa lần chuyển tiếp văn bản kiểu `"Dump"` và lần chuyển tiếp `"https://..."; Attachments:` theo sau. Tăng `messages.inbound.byChannel.bluebubbles` để bao phủ thoải mái khoảng cách đó. + Đo khoảng cách giữa lần phân phối văn bản kiểu `"Dump"` và lần phân phối `"https://..."; Attachments:` theo sau. Tăng `messages.inbound.byChannel.bluebubbles` để bao phủ khoảng cách đó một cách thoải mái. - - Dấu thời gian sự kiện phiên (`~/.openclaw/agents//sessions/*.jsonl`) phản ánh thời điểm Gateway chuyển một tin nhắn cho tác tử, **không phải** thời điểm Webhook đến. Tin nhắn thứ hai trong hàng đợi được gắn nhãn `[Queued messages while agent was busy]` nghĩa là lượt đầu tiên vẫn đang chạy khi Webhook thứ hai đến — nhóm gộp đã được xả trước đó. Hãy tinh chỉnh cửa sổ theo nhật ký máy chủ BB, không theo nhật ký phiên. + + Dấu thời gian sự kiện phiên (`~/.openclaw/agents//sessions/*.jsonl`) phản ánh thời điểm gateway chuyển tin nhắn cho agent, **không phải** thời điểm webhook đến. Tin nhắn thứ hai trong hàng đợi được gắn `[Queued messages while agent was busy]` nghĩa là lượt đầu tiên vẫn đang chạy khi webhook thứ hai đến — bucket gộp đã xả rồi. Tinh chỉnh cửa sổ theo log máy chủ BB, không phải log phiên. - - Trên các máy nhỏ hơn (8 GB), lượt tác tử có thể mất đủ lâu khiến nhóm gộp xả trước khi trả lời hoàn tất, và URL trở thành lượt thứ hai trong hàng đợi. Kiểm tra `memory_pressure` và `ps -o rss -p $(pgrep openclaw-gateway)`; nếu Gateway vượt quá ~500 MB RSS và bộ nén đang hoạt động, hãy đóng các tiến trình nặng khác hoặc chuyển sang máy chủ lớn hơn. + + Trên máy nhỏ hơn (8 GB), các lượt agent có thể kéo dài đủ lâu để bucket gộp xả trước khi trả lời hoàn tất, và URL rơi vào lượt thứ hai trong hàng đợi. Kiểm tra `memory_pressure` và `ps -o rss -p $(pgrep openclaw-gateway)`; nếu gateway vượt ~500 MB RSS và bộ nén đang hoạt động, hãy đóng các tiến trình nặng khác hoặc chuyển sang host lớn hơn. - - Nếu người dùng chạm `Dump` dưới dạng **trả lời** một bong bóng URL hiện có (iMessage hiển thị huy hiệu "1 Reply" trên bong bóng Dump), URL nằm trong `replyToBody`, không nằm trong Webhook thứ hai. Gộp không áp dụng — đó là vấn đề về skill/prompt, không phải vấn đề về debounce. + + Nếu người dùng chạm `Dump` dưới dạng **trả lời** cho một bong bóng URL hiện có (iMessage hiển thị huy hiệu "1 Reply" trên bong bóng Dump), URL nằm trong `replyToBody`, không phải trong webhook thứ hai. Việc gộp không áp dụng — đó là vấn đề skill/prompt, không phải vấn đề debouncer. -## Phát trực tuyến theo khối +## Streaming theo khối -Kiểm soát việc phản hồi được gửi dưới dạng một tin nhắn duy nhất hay được phát trực tuyến theo khối: +Kiểm soát việc phản hồi được gửi dưới dạng một tin nhắn duy nhất hay được streaming theo các khối: ```json5 { @@ -549,49 +541,49 @@ Kiểm soát việc phản hồi được gửi dưới dạng một tin nhắn ## Phương tiện + giới hạn -- Tệp đính kèm đầu vào được tải xuống và lưu trong bộ nhớ đệm phương tiện. -- Giới hạn phương tiện qua `channels.bluebubbles.mediaMaxMb` cho phương tiện đầu vào và đầu ra (mặc định: 8 MB). -- Văn bản đầu ra được chia khúc theo `channels.bluebubbles.textChunkLimit` (mặc định: 4000 ký tự). +- Tệp đính kèm đến được tải xuống và lưu trong cache phương tiện. +- Giới hạn phương tiện qua `channels.bluebubbles.mediaMaxMb` cho phương tiện đến và đi (mặc định: 8 MB). +- Văn bản đi được chia thành các phần theo `channels.bluebubbles.textChunkLimit` (mặc định: 4000 ký tự). ## Tham chiếu cấu hình Cấu hình đầy đủ: [Cấu hình](/vi/gateway/configuration) - + - `channels.bluebubbles.enabled`: Bật/tắt kênh. - - `channels.bluebubbles.serverUrl`: URL cơ sở API REST của BlueBubbles. + - `channels.bluebubbles.serverUrl`: URL cơ sở của REST API BlueBubbles. - `channels.bluebubbles.password`: Mật khẩu API. - `channels.bluebubbles.webhookPath`: Đường dẫn endpoint Webhook (mặc định: `/bluebubbles-webhook`). - + - `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (mặc định: `pairing`). - - `channels.bluebubbles.allowFrom`: Danh sách cho phép DM (định danh, email, số E.164, `chat_id:*`, `chat_guid:*`). + - `channels.bluebubbles.allowFrom`: allowlist DM (handle, email, số E.164, `chat_id:*`, `chat_guid:*`). - `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (mặc định: `allowlist`). - - `channels.bluebubbles.groupAllowFrom`: Danh sách cho phép người gửi nhóm. - - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Trên macOS, tùy chọn bổ sung thông tin người tham gia nhóm chưa đặt tên từ Danh bạ cục bộ sau khi vượt qua kiểm soát truy cập. Mặc định: `false`. + - `channels.bluebubbles.groupAllowFrom`: allowlist người gửi nhóm. + - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Trên macOS, tùy chọn bổ sung thông tin người tham gia nhóm chưa có tên từ Danh bạ cục bộ sau khi vượt qua gating. Mặc định: `false`. - `channels.bluebubbles.groups`: Cấu hình theo từng nhóm (`requireMention`, v.v.). - + - `channels.bluebubbles.sendReadReceipts`: Gửi biên nhận đã đọc (mặc định: `true`). - - `channels.bluebubbles.blockStreaming`: Bật phát trực tuyến theo khối (mặc định: `false`; bắt buộc đối với phản hồi phát trực tuyến). + - `channels.bluebubbles.blockStreaming`: Bật truyền theo khối (mặc định: `false`; bắt buộc cho phản hồi truyền trực tuyến). - `channels.bluebubbles.textChunkLimit`: Kích thước đoạn gửi đi tính bằng ký tự (mặc định: 4000). - - `channels.bluebubbles.sendTimeoutMs`: Thời gian chờ cho mỗi yêu cầu tính bằng ms đối với các lần gửi văn bản đi qua `/api/v1/message/text` (mặc định: 30000). Tăng giá trị này trên các thiết lập macOS 26 nơi các lần gửi iMessage qua Private API có thể bị treo hơn 60 giây bên trong framework iMessage; ví dụ `45000` hoặc `60000`. Các probe, tra cứu cuộc trò chuyện, phản ứng, chỉnh sửa và kiểm tra tình trạng hiện vẫn giữ mặc định ngắn hơn là 10 giây; mở rộng phạm vi sang phản ứng và chỉnh sửa được lên kế hoạch như bước tiếp theo. Ghi đè theo tài khoản: `channels.bluebubbles.accounts..sendTimeoutMs`. - - `channels.bluebubbles.chunkMode`: `length` (mặc định) chỉ tách khi vượt quá `textChunkLimit`; `newline` tách tại các dòng trống (ranh giới đoạn văn) trước khi tách theo độ dài. + - `channels.bluebubbles.sendTimeoutMs`: Thời gian chờ theo từng yêu cầu tính bằng ms cho các lần gửi văn bản đi qua `/api/v1/message/text` (mặc định: 30000). Tăng giá trị này trên các thiết lập macOS 26 nơi các lần gửi Private API iMessage có thể bị treo hơn 60 giây bên trong framework iMessage; ví dụ `45000` hoặc `60000`. Các phép thăm dò, tra cứu cuộc trò chuyện, phản ứng, chỉnh sửa và kiểm tra tình trạng hiện vẫn giữ mặc định ngắn hơn là 10 giây; việc mở rộng phạm vi sang phản ứng và chỉnh sửa được lên kế hoạch làm bước tiếp theo. Ghi đè theo tài khoản: `channels.bluebubbles.accounts..sendTimeoutMs`. + - `channels.bluebubbles.chunkMode`: `length` (mặc định) chỉ tách khi vượt quá `textChunkLimit`; `newline` tách theo dòng trống (ranh giới đoạn văn) trước khi chia đoạn theo độ dài. - + - `channels.bluebubbles.mediaMaxMb`: Giới hạn phương tiện vào/ra tính bằng MB (mặc định: 8). - - `channels.bluebubbles.mediaLocalRoots`: Danh sách cho phép rõ ràng gồm các thư mục cục bộ tuyệt đối được phép dùng cho đường dẫn phương tiện cục bộ gửi đi. Việc gửi đường dẫn cục bộ bị từ chối theo mặc định trừ khi mục này được cấu hình. Ghi đè theo tài khoản: `channels.bluebubbles.accounts..mediaLocalRoots`. - - `channels.bluebubbles.coalesceSameSenderDms`: Gộp các Webhook DM liên tiếp từ cùng một người gửi vào một lượt agent để lần gửi tách văn bản+URL của Apple đến dưới dạng một tin nhắn duy nhất (mặc định: `false`). Xem [Gộp các DM gửi tách](#coalescing-split-send-dms-command--url-in-one-composition) để biết các tình huống, tinh chỉnh cửa sổ và đánh đổi. Mở rộng cửa sổ debounce mặc định cho tin nhắn đến từ 500 ms lên 2500 ms khi bật mà không có `messages.inbound.byChannel.bluebubbles` rõ ràng. - - `channels.bluebubbles.historyLimit`: Số tin nhắn nhóm tối đa cho ngữ cảnh (0 sẽ tắt). + - `channels.bluebubbles.mediaLocalRoots`: Danh sách cho phép rõ ràng gồm các thư mục cục bộ tuyệt đối được phép dùng cho đường dẫn phương tiện cục bộ gửi đi. Các lần gửi đường dẫn cục bộ bị từ chối theo mặc định trừ khi cấu hình mục này. Ghi đè theo tài khoản: `channels.bluebubbles.accounts..mediaLocalRoots`. + - `channels.bluebubbles.coalesceSameSenderDms`: Gộp các Webhook DM liên tiếp từ cùng một người gửi thành một lượt agent để lần gửi tách văn bản+URL của Apple đến dưới dạng một tin nhắn duy nhất (mặc định: `false`). Xem [Gộp các DM gửi tách](#coalescing-split-send-dms-command--url-in-one-composition) để biết các tình huống, điều chỉnh cửa sổ thời gian và đánh đổi. Mở rộng cửa sổ debounce mặc định cho tin nhắn đến từ 500 ms lên 2500 ms khi được bật mà không có `messages.inbound.byChannel.bluebubbles` rõ ràng. + - `channels.bluebubbles.historyLimit`: Số tin nhắn nhóm tối đa cho ngữ cảnh (0 để tắt). - `channels.bluebubbles.dmHistoryLimit`: Giới hạn lịch sử DM. - - `channels.bluebubbles.replyContextApiFallback`: Khi một phản hồi đến không có `replyToBody`/`replyToSender` và bộ nhớ đệm ngữ cảnh phản hồi trong bộ nhớ bị trượt, lấy tin nhắn gốc từ BlueBubbles HTTP API như một phương án dự phòng nỗ lực tối đa (mặc định: `false`). Hữu ích cho các triển khai nhiều phiên bản dùng chung một tài khoản BlueBubbles, sau khi quy trình khởi động lại hoặc sau khi cache TTL/LRU lâu dài bị loại bỏ. Lần lấy này được bảo vệ SSRF bằng cùng chính sách như mọi yêu cầu client BlueBubbles khác, không bao giờ ném lỗi, và điền vào cache để các phản hồi tiếp theo được phân bổ chi phí. Ghi đè theo tài khoản: `channels.bluebubbles.accounts..replyContextApiFallback`. Thiết lập cấp kênh sẽ lan truyền đến các tài khoản bỏ qua cờ này. + - `channels.bluebubbles.replyContextApiFallback`: Khi một phản hồi đến không có `replyToBody`/`replyToSender` và cache ngữ cảnh phản hồi trong bộ nhớ bị trượt, lấy tin nhắn gốc từ BlueBubbles HTTP API như một phương án dự phòng nỗ lực tối đa (mặc định: `false`). Hữu ích cho triển khai nhiều phiên bản dùng chung một tài khoản BlueBubbles, sau khi khởi động lại tiến trình, hoặc sau khi cache TTL/LRU tồn tại lâu bị loại bỏ. Lần lấy này được bảo vệ chống SSRF bằng cùng chính sách như mọi yêu cầu client BlueBubbles khác, không bao giờ ném lỗi, và điền cache để các phản hồi tiếp theo dùng lại hiệu quả. Ghi đè theo tài khoản: `channels.bluebubbles.accounts..replyContextApiFallback`. Một thiết lập cấp kênh sẽ truyền sang các tài khoản không đặt cờ này. - + - `channels.bluebubbles.actions`: Bật/tắt các hành động cụ thể. - `channels.bluebubbles.accounts`: Cấu hình nhiều tài khoản. @@ -603,44 +595,44 @@ Các tùy chọn toàn cục liên quan: - `agents.list[].groupChat.mentionPatterns` (hoặc `messages.groupChat.mentionPatterns`). - `messages.responsePrefix`. -## Định địa chỉ / đích phân phối +## Định địa chỉ / mục tiêu phân phối Ưu tiên `chat_guid` để định tuyến ổn định: - `chat_guid:iMessage;-;+15555550123` (ưu tiên cho nhóm) - `chat_id:123` - `chat_identifier:...` -- Handle trực tiếp: `+15555550123`, `user@example.com` - - Nếu một handle trực tiếp không có cuộc trò chuyện DM hiện có, OpenClaw sẽ tạo một cuộc trò chuyện qua `POST /api/v1/chat/new`. Việc này yêu cầu bật BlueBubbles Private API. +- Định danh trực tiếp: `+15555550123`, `user@example.com` + - Nếu một định danh trực tiếp chưa có cuộc trò chuyện DM hiện có, OpenClaw sẽ tạo một cuộc trò chuyện qua `POST /api/v1/chat/new`. Việc này yêu cầu bật BlueBubbles Private API. ### Định tuyến iMessage so với SMS -Khi cùng một handle có cả cuộc trò chuyện iMessage và SMS trên Mac (ví dụ một số điện thoại đã đăng ký iMessage nhưng cũng đã nhận các phương án dự phòng bong bóng xanh), OpenClaw ưu tiên cuộc trò chuyện iMessage và không bao giờ âm thầm hạ cấp xuống SMS. Để buộc dùng cuộc trò chuyện SMS, hãy dùng tiền tố đích `sms:` rõ ràng (ví dụ `sms:+15555550123`). Các handle không có cuộc trò chuyện iMessage khớp vẫn gửi qua bất kỳ cuộc trò chuyện nào mà BlueBubbles báo cáo. +Khi cùng một định danh có cả cuộc trò chuyện iMessage và SMS trên máy Mac (ví dụ một số điện thoại đã đăng ký iMessage nhưng cũng đã nhận các phương án dự phòng bong bóng xanh), OpenClaw ưu tiên cuộc trò chuyện iMessage và không bao giờ âm thầm hạ cấp xuống SMS. Để bắt buộc dùng cuộc trò chuyện SMS, hãy dùng tiền tố mục tiêu `sms:` rõ ràng (ví dụ `sms:+15555550123`). Các định danh không có cuộc trò chuyện iMessage khớp vẫn gửi qua bất kỳ cuộc trò chuyện nào mà BlueBubbles báo cáo. ## Bảo mật -- Các yêu cầu Webhook được xác thực bằng cách so sánh query param hoặc header `guid`/`password` với `channels.bluebubbles.password`. -- Giữ bí mật mật khẩu API và endpoint Webhook (xử lý chúng như thông tin xác thực). +- Các yêu cầu Webhook được xác thực bằng cách so sánh tham số truy vấn hoặc header `guid`/`password` với `channels.bluebubbles.password`. +- Giữ bí mật mật khẩu API và endpoint Webhook (xem chúng như thông tin xác thực). - Không có cơ chế bỏ qua localhost cho xác thực Webhook của BlueBubbles. Nếu bạn proxy lưu lượng Webhook, hãy giữ mật khẩu BlueBubbles trên yêu cầu từ đầu đến cuối. `gateway.trustedProxies` không thay thế `channels.bluebubbles.password` ở đây. Xem [Bảo mật Gateway](/vi/gateway/security#reverse-proxy-configuration). - Bật HTTPS + quy tắc tường lửa trên máy chủ BlueBubbles nếu công khai nó ra ngoài LAN của bạn. ## Khắc phục sự cố -- Nếu sự kiện đang nhập/đã đọc ngừng hoạt động, hãy kiểm tra log Webhook của BlueBubbles và xác minh đường dẫn Gateway khớp với `channels.bluebubbles.webhookPath`. +- Nếu sự kiện nhập/đọc ngừng hoạt động, hãy kiểm tra nhật ký Webhook của BlueBubbles và xác minh đường dẫn gateway khớp với `channels.bluebubbles.webhookPath`. - Mã ghép nối hết hạn sau một giờ; dùng `openclaw pairing list bluebubbles` và `openclaw pairing approve bluebubbles `. - Phản ứng yêu cầu BlueBubbles private API (`POST /api/v1/message/react`); hãy đảm bảo phiên bản máy chủ cung cấp API này. -- Chỉnh sửa/hủy gửi yêu cầu macOS 13+ và phiên bản máy chủ BlueBubbles tương thích. Trên macOS 26 (Tahoe), chỉnh sửa hiện đang hỏng do các thay đổi Private API. -- Cập nhật biểu tượng nhóm có thể chập chờn trên macOS 26 (Tahoe): API có thể trả về thành công nhưng biểu tượng mới không đồng bộ. +- Chỉnh sửa/thu hồi yêu cầu macOS 13+ và một phiên bản máy chủ BlueBubbles tương thích. Trên macOS 26 (Tahoe), chỉnh sửa hiện bị hỏng do thay đổi trong private API. +- Cập nhật biểu tượng nhóm có thể không ổn định trên macOS 26 (Tahoe): API có thể trả về thành công nhưng biểu tượng mới không đồng bộ. - OpenClaw tự động ẩn các hành động đã biết là hỏng dựa trên phiên bản macOS của máy chủ BlueBubbles. Nếu chỉnh sửa vẫn xuất hiện trên macOS 26 (Tahoe), hãy tắt thủ công bằng `channels.bluebubbles.actions.edit=false`. -- `coalesceSameSenderDms` đã bật nhưng các lần gửi tách (ví dụ `Dump` + URL) vẫn đến dưới dạng hai lượt: xem danh sách kiểm tra [khắc phục sự cố gộp gửi tách](#split-send-coalescing-troubleshooting) — nguyên nhân phổ biến là cửa sổ debounce quá chặt, timestamp log phiên bị đọc nhầm là thời điểm Webhook đến, hoặc một lần gửi trích dẫn phản hồi (dùng `replyToBody`, không phải Webhook thứ hai). -- Để biết thông tin trạng thái/tình trạng: `openclaw status --all` hoặc `openclaw status --deep`. +- Đã bật `coalesceSameSenderDms` nhưng các lần gửi tách (ví dụ `Dump` + URL) vẫn đến dưới dạng hai lượt: xem danh sách kiểm tra [khắc phục sự cố gộp gửi tách](#split-send-coalescing-troubleshooting) — nguyên nhân phổ biến là cửa sổ debounce quá chặt, timestamp nhật ký phiên bị đọc nhầm là thời điểm Webhook đến, hoặc một lần gửi trích dẫn phản hồi (dùng `replyToBody`, không phải Webhook thứ hai). +- Để xem thông tin trạng thái/tình trạng: `openclaw status --all` hoặc `openclaw status --deep`. Để tham khảo quy trình kênh chung, xem [Kênh](/vi/channels) và hướng dẫn [Plugins](/vi/tools/plugin). ## Liên quan - [Định tuyến kênh](/vi/channels/channel-routing) — định tuyến phiên cho tin nhắn -- [Tổng quan về kênh](/vi/channels) — tất cả kênh được hỗ trợ -- [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và cổng kiểm soát nhắc đến +- [Tổng quan về kênh](/vi/channels) — tất cả các kênh được hỗ trợ +- [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và kiểm soát nhắc tên - [Ghép nối](/vi/channels/pairing) — xác thực DM và luồng ghép nối - [Bảo mật](/vi/gateway/security) — mô hình truy cập và gia cố diff --git a/docs/vi/channels/broadcast-groups.md b/docs/vi/channels/broadcast-groups.md index 4623492fb..91986faab 100644 --- a/docs/vi/channels/broadcast-groups.md +++ b/docs/vi/channels/broadcast-groups.md @@ -1,37 +1,37 @@ --- read_when: - - Cấu hình các nhóm phát sóng - - Gỡ lỗi phản hồi đa tác nhân trong WhatsApp + - Cấu hình nhóm phát sóng + - Gỡ lỗi các phản hồi đa tác nhân trong WhatsApp sidebarTitle: Broadcast groups status: experimental -summary: Gửi tin nhắn WhatsApp đồng loạt tới nhiều tác nhân +summary: Phát một tin nhắn WhatsApp tới nhiều tác nhân title: Nhóm phát sóng x-i18n: - generated_at: "2026-04-29T22:24:33Z" + generated_at: "2026-05-04T02:21:33Z" model: gpt-5.5 provider: openai - source_hash: b0de4ccc85bf79e2ceb1dddd60db067309b15b7f876c92e7d591ff0b4b4315ec + source_hash: eab43d3c3ffddb360340469433d74a380fbab98e662b2463a54f62eafc375b55 source_path: channels/broadcast-groups.md workflow: 16 --- -**Trạng thái:** Thử nghiệm. Được thêm vào 2026.1.9. +**Trạng thái:** Thử nghiệm. Đã thêm trong 2026.1.9. ## Tổng quan -Nhóm phát sóng cho phép nhiều tác nhân xử lý và phản hồi cùng một tin nhắn đồng thời. Điều này cho phép bạn tạo các nhóm tác nhân chuyên biệt làm việc cùng nhau trong một nhóm WhatsApp hoặc DM duy nhất — tất cả chỉ dùng một số điện thoại. +Nhóm phát sóng cho phép nhiều tác tử xử lý và phản hồi cùng một tin nhắn đồng thời. Điều này cho phép bạn tạo các nhóm tác tử chuyên biệt cùng làm việc trong một nhóm WhatsApp hoặc DM duy nhất — tất cả đều dùng một số điện thoại. Phạm vi hiện tại: **chỉ WhatsApp** (kênh web). -Nhóm phát sóng được đánh giá sau danh sách cho phép của kênh và các quy tắc kích hoạt nhóm. Trong các nhóm WhatsApp, điều này có nghĩa là phát sóng xảy ra khi OpenClaw thường sẽ phản hồi (ví dụ: khi được nhắc đến, tùy theo cài đặt nhóm của bạn). +Nhóm phát sóng được đánh giá sau danh sách cho phép của kênh và quy tắc kích hoạt nhóm. Trong các nhóm WhatsApp, điều này nghĩa là phát sóng diễn ra khi OpenClaw thường sẽ phản hồi (ví dụ: khi được nhắc đến, tùy thuộc vào cài đặt nhóm của bạn). ## Trường hợp sử dụng - - Triển khai nhiều tác nhân với trách nhiệm nguyên tử, tập trung: + + Triển khai nhiều tác tử với các trách nhiệm nguyên tử, tập trung: ``` Group: "Development Team" @@ -42,7 +42,7 @@ Nhóm phát sóng được đánh giá sau danh sách cho phép của kênh và - TestGenerator (suggests test cases) ``` - Mỗi tác nhân xử lý cùng một tin nhắn và cung cấp góc nhìn chuyên biệt của mình. + Mỗi tác tử xử lý cùng một tin nhắn và đưa ra góc nhìn chuyên biệt của mình. @@ -77,10 +77,10 @@ Nhóm phát sóng được đánh giá sau danh sách cho phép của kênh và ### Thiết lập cơ bản -Thêm một phần `broadcast` cấp cao nhất (bên cạnh `bindings`). Khóa là ID ngang hàng của WhatsApp: +Thêm một phần `broadcast` cấp cao nhất (bên cạnh `bindings`). Các khóa là ID peer của WhatsApp: -- cuộc trò chuyện nhóm: JID nhóm (ví dụ: `120363403215116621@g.us`) -- DM: số điện thoại E.164 (ví dụ: `+15551234567`) +- trò chuyện nhóm: JID nhóm (ví dụ `120363403215116621@g.us`) +- DM: số điện thoại E.164 (ví dụ `+15551234567`) ```json { @@ -90,15 +90,15 @@ Thêm một phần `broadcast` cấp cao nhất (bên cạnh `bindings`). Khóa } ``` -**Kết quả:** Khi OpenClaw sẽ phản hồi trong cuộc trò chuyện này, nó sẽ chạy cả ba tác nhân. +**Kết quả:** Khi OpenClaw sẽ phản hồi trong cuộc trò chuyện này, nó sẽ chạy cả ba tác tử. ### Chiến lược xử lý -Kiểm soát cách tác nhân xử lý tin nhắn: +Kiểm soát cách tác tử xử lý tin nhắn: - Tất cả tác nhân xử lý đồng thời: + Tất cả tác tử xử lý đồng thời: ```json { @@ -111,7 +111,7 @@ Kiểm soát cách tác nhân xử lý tin nhắn: - Tác nhân xử lý theo thứ tự (một tác nhân chờ tác nhân trước hoàn tất): + Tác tử xử lý theo thứ tự (mỗi tác tử chờ tác tử trước hoàn tất): ```json { @@ -169,44 +169,44 @@ Kiểm soát cách tác nhân xử lý tin nhắn: Một tin nhắn nhóm WhatsApp hoặc DM đến. - Hệ thống kiểm tra xem ID ngang hàng có trong `broadcast` hay không. + Hệ thống kiểm tra xem ID peer có trong `broadcast` hay không. - - - Tất cả tác nhân được liệt kê xử lý tin nhắn. - - Mỗi tác nhân có khóa phiên và ngữ cảnh cô lập riêng. - - Tác nhân xử lý song song (mặc định) hoặc tuần tự. + + - Tất cả tác tử được liệt kê xử lý tin nhắn. + - Mỗi tác tử có khóa phiên riêng và ngữ cảnh tách biệt. + - Tác tử xử lý song song (mặc định) hoặc tuần tự. - + Áp dụng định tuyến bình thường (binding khớp đầu tiên). -Nhóm phát sóng không bỏ qua danh sách cho phép của kênh hoặc các quy tắc kích hoạt nhóm (nhắc đến/lệnh/v.v.). Chúng chỉ thay đổi _tác nhân nào chạy_ khi một tin nhắn đủ điều kiện để xử lý. +Nhóm phát sóng không bỏ qua danh sách cho phép của kênh hoặc quy tắc kích hoạt nhóm (lượt nhắc/lệnh/v.v.). Chúng chỉ thay đổi _tác tử nào chạy_ khi một tin nhắn đủ điều kiện để xử lý. -### Cô lập phiên +### Tách biệt phiên -Mỗi tác nhân trong một nhóm phát sóng duy trì hoàn toàn riêng biệt: +Mỗi tác tử trong một nhóm phát sóng duy trì hoàn toàn riêng biệt: - **Khóa phiên** (`agent:alfred:whatsapp:group:120363...` so với `agent:baerbel:whatsapp:group:120363...`) -- **Lịch sử hội thoại** (tác nhân không thấy tin nhắn của các tác nhân khác) +- **Lịch sử hội thoại** (tác tử không thấy tin nhắn của các tác tử khác) - **Workspace** (sandbox riêng nếu được cấu hình) - **Quyền truy cập công cụ** (danh sách cho phép/từ chối khác nhau) -- **Bộ nhớ/ngữ cảnh** (`IDENTITY.md`, `SOUL.md` riêng, v.v.) -- **Bộ đệm ngữ cảnh nhóm** (các tin nhắn nhóm gần đây dùng làm ngữ cảnh) được chia sẻ theo từng ngang hàng, nên tất cả tác nhân phát sóng thấy cùng một ngữ cảnh khi được kích hoạt +- **Bộ nhớ/ngữ cảnh** (IDENTITY.md, SOUL.md, v.v. riêng) +- **Bộ đệm ngữ cảnh nhóm** (các tin nhắn nhóm gần đây dùng làm ngữ cảnh) được chia sẻ theo từng peer, vì vậy tất cả tác tử phát sóng thấy cùng một ngữ cảnh khi được kích hoạt -Điều này cho phép mỗi tác nhân có: +Điều này cho phép mỗi tác tử có: - Tính cách khác nhau - Quyền truy cập công cụ khác nhau (ví dụ: chỉ đọc so với đọc-ghi) - Mô hình khác nhau (ví dụ: opus so với sonnet) -- Các Skills khác nhau đã cài đặt +- Skills khác nhau đã cài đặt -### Ví dụ: phiên cô lập +### Ví dụ: phiên tách biệt -Trong nhóm `120363403215116621@g.us` với các tác nhân `["alfred", "baerbel"]`: +Trong nhóm `120363403215116621@g.us` với các tác tử `["alfred", "baerbel"]`: @@ -227,11 +227,11 @@ Trong nhóm `120363403215116621@g.us` với các tác nhân `["alfred", "baerbel -## Phương pháp hay nhất +## Thực hành tốt nhất - - Thiết kế mỗi tác nhân với một trách nhiệm rõ ràng, duy nhất: + + Thiết kế mỗi tác tử với một trách nhiệm duy nhất, rõ ràng: ```json { @@ -241,11 +241,11 @@ Trong nhóm `120363403215116621@g.us` với các tác nhân `["alfred", "baerbel } ``` - ✅ **Tốt:** Mỗi tác nhân có một nhiệm vụ. ❌ **Không tốt:** Một tác nhân "dev-helper" chung chung. + ✅ **Tốt:** Mỗi tác tử có một nhiệm vụ. ❌ **Không tốt:** Một tác tử "dev-helper" chung chung. - - Làm rõ mỗi tác nhân làm gì: + + Làm rõ mỗi tác tử làm gì: ```json { @@ -259,32 +259,34 @@ Trong nhóm `120363403215116621@g.us` với các tác nhân `["alfred", "baerbel - Chỉ cấp cho tác nhân những công cụ chúng cần: + Chỉ cấp cho tác tử những công cụ chúng cần: ```json { "agents": { "reviewer": { - "tools": { "allow": ["read", "exec"] } // Read-only + "tools": { "allow": ["read", "exec"] } }, "fixer": { - "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write + "tools": { "allow": ["read", "write", "edit", "exec"] } } } } ``` - - - Với nhiều tác nhân, hãy cân nhắc: - - - Dùng `"strategy": "parallel"` (mặc định) để tăng tốc - - Giới hạn nhóm phát sóng ở 5-10 tác nhân - - Dùng mô hình nhanh hơn cho các tác nhân đơn giản hơn + `reviewer` chỉ đọc. `fixer` có thể đọc và ghi. - - Tác nhân lỗi độc lập. Lỗi của một tác nhân không chặn các tác nhân khác: + + Với nhiều tác tử, hãy cân nhắc: + + - Dùng `"strategy": "parallel"` (mặc định) để tăng tốc độ + - Giới hạn nhóm phát sóng ở 5-10 tác tử + - Dùng mô hình nhanh hơn cho các tác tử đơn giản hơn + + + + Tác tử thất bại độc lập. Lỗi của một tác tử không chặn các tác tử khác: ``` Message → [Agent A ✓, Agent B ✗ error, Agent C ✓] @@ -327,18 +329,18 @@ Nhóm phát sóng hoạt động cùng với định tuyến hiện có: - `GROUP_B`: agent1 VÀ agent2 phản hồi (phát sóng). -**Độ ưu tiên:** `broadcast` được ưu tiên hơn `bindings`. +**Thứ tự ưu tiên:** `broadcast` có độ ưu tiên cao hơn `bindings`. ## Khắc phục sự cố - + **Kiểm tra:** - 1. ID tác nhân tồn tại trong `agents.list`. - 2. Định dạng ID ngang hàng chính xác (ví dụ: `120363403215116621@g.us`). - 3. Tác nhân không nằm trong danh sách từ chối. + 1. ID tác tử tồn tại trong `agents.list`. + 2. Định dạng ID peer chính xác (ví dụ `120363403215116621@g.us`). + 3. Tác tử không nằm trong danh sách từ chối. **Gỡ lỗi:** @@ -347,16 +349,16 @@ Nhóm phát sóng hoạt động cùng với định tuyến hiện có: ``` - - **Nguyên nhân:** ID ngang hàng có thể nằm trong `bindings` nhưng không nằm trong `broadcast`. + + **Nguyên nhân:** ID peer có thể nằm trong `bindings` nhưng không nằm trong `broadcast`. - **Cách khắc phục:** Thêm vào cấu hình phát sóng hoặc xóa khỏi bindings. + **Cách sửa:** Thêm vào cấu hình phát sóng hoặc xóa khỏi bindings. - Nếu chậm với nhiều tác nhân: + Nếu chậm với nhiều tác tử: - - Giảm số lượng tác nhân trên mỗi nhóm. + - Giảm số lượng tác tử trên mỗi nhóm. - Dùng mô hình nhẹ hơn (sonnet thay vì opus). - Kiểm tra thời gian khởi động sandbox. @@ -407,7 +409,7 @@ Nhóm phát sóng hoạt động cùng với định tuyến hiện có: - code-formatter: "Đã sửa thụt lề và thêm gợi ý kiểu" - security-scanner: "⚠️ Lỗ hổng SQL injection ở dòng 12" - - test-coverage: "Độ phủ là 45%, thiếu kiểm thử cho các trường hợp lỗi" + - test-coverage: "Độ bao phủ là 45%, thiếu kiểm thử cho các trường hợp lỗi" - docs-checker: "Thiếu docstring cho hàm `process_data`" @@ -446,32 +448,32 @@ interface OpenClawConfig { ### Trường - Cách xử lý tác nhân. `parallel` chạy tất cả tác nhân đồng thời; `sequential` chạy chúng theo thứ tự mảng. + Cách xử lý tác tử. `parallel` chạy tất cả tác tử đồng thời; `sequential` chạy chúng theo thứ tự trong mảng. - JID nhóm WhatsApp, số E.164 hoặc ID ngang hàng khác. Giá trị là mảng ID tác nhân nên xử lý tin nhắn. + JID nhóm WhatsApp, số E.164 hoặc ID peer khác. Giá trị là mảng ID tác tử sẽ xử lý tin nhắn. -## Giới hạn +## Hạn chế -1. **Số tác nhân tối đa:** Không có giới hạn cứng, nhưng hơn 10 tác nhân có thể chậm. -2. **Ngữ cảnh dùng chung:** Tác nhân không thấy phản hồi của nhau (theo thiết kế). +1. **Số tác tử tối đa:** Không có giới hạn cứng, nhưng 10+ tác tử có thể chậm. +2. **Ngữ cảnh chia sẻ:** Tác tử không thấy phản hồi của nhau (theo thiết kế). 3. **Thứ tự tin nhắn:** Phản hồi song song có thể đến theo bất kỳ thứ tự nào. -4. **Giới hạn tốc độ:** Tất cả tác nhân đều được tính vào giới hạn tốc độ của WhatsApp. +4. **Giới hạn tốc độ:** Tất cả tác tử đều tính vào giới hạn tốc độ của WhatsApp. ## Cải tiến trong tương lai Các tính năng đã lên kế hoạch: -- [ ] Chế độ ngữ cảnh dùng chung (tác nhân thấy phản hồi của nhau) -- [ ] Điều phối tác nhân (tác nhân có thể báo hiệu cho nhau) -- [ ] Chọn tác nhân động (chọn tác nhân dựa trên nội dung tin nhắn) -- [ ] Độ ưu tiên của tác nhân (một số tác nhân phản hồi trước các tác nhân khác) +- [ ] Chế độ ngữ cảnh chia sẻ (tác tử thấy phản hồi của nhau) +- [ ] Điều phối tác tử (tác tử có thể gửi tín hiệu cho nhau) +- [ ] Chọn tác tử động (chọn tác tử dựa trên nội dung tin nhắn) +- [ ] Mức ưu tiên tác tử (một số tác tử phản hồi trước các tác tử khác) ## Liên quan - [Định tuyến kênh](/vi/channels/channel-routing) - [Nhóm](/vi/channels/groups) -- [Công cụ môi trường cô lập đa tác nhân](/vi/tools/multi-agent-sandbox-tools) +- [Công cụ môi trường cách ly đa tác nhân](/vi/tools/multi-agent-sandbox-tools) - [Ghép nối](/vi/channels/pairing) - [Quản lý phiên](/vi/concepts/session) diff --git a/docs/vi/channels/discord.md b/docs/vi/channels/discord.md index edba9aea3..60c113ca1 100644 --- a/docs/vi/channels/discord.md +++ b/docs/vi/channels/discord.md @@ -1,40 +1,40 @@ --- read_when: - Làm việc với các tính năng kênh Discord -summary: Trạng thái hỗ trợ, khả năng và cấu hình bot Discord +summary: Trạng thái hỗ trợ, khả năng và cấu hình của bot Discord title: Discord x-i18n: - generated_at: "2026-05-03T21:27:14Z" + generated_at: "2026-05-04T02:21:31Z" model: gpt-5.5 provider: openai - source_hash: 3a38cb3c8e25c1f3d6b7ddfc35a0445dc264be74d74b08d0051528b462b743a3 + source_hash: df4e045e39f8977f779fe409abf41dad0d950c92f1230c51ff356343513df812 source_path: channels/discord.md workflow: 16 --- -Sẵn sàng cho DM và kênh guild thông qua Discord gateway chính thức. +Sẵn sàng cho DM và kênh guild thông qua Gateway Discord chính thức. - DM trên Discord mặc định ở chế độ ghép nối. + DM Discord mặc định ở chế độ ghép nối. Hành vi lệnh gốc và danh mục lệnh. - Chẩn đoán liên kênh và quy trình sửa chữa. + Chẩn đoán liên kênh và luồng sửa chữa. ## Thiết lập nhanh -Bạn sẽ cần tạo một ứng dụng mới với bot, thêm bot vào máy chủ của bạn và ghép nối bot đó với OpenClaw. Chúng tôi khuyên bạn nên thêm bot vào máy chủ riêng của chính mình. Nếu bạn chưa có, hãy [tạo một máy chủ trước](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (chọn **Create My Own > For me and my friends**). +Bạn sẽ cần tạo một ứng dụng mới với bot, thêm bot vào máy chủ của bạn, rồi ghép nối bot với OpenClaw. Chúng tôi khuyên bạn nên thêm bot vào máy chủ riêng tư của chính bạn. Nếu chưa có, hãy [tạo một máy chủ trước](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (chọn **Create My Own > For me and my friends**). - - Vào [Discord Developer Portal](https://discord.com/developers/applications) và nhấp vào **New Application**. Đặt tên như "OpenClaw". + + Đi tới [Discord Developer Portal](https://discord.com/developers/applications) và nhấp vào **New Application**. Đặt tên kiểu như "OpenClaw". - Nhấp vào **Bot** trên thanh bên. Đặt **Username** thành tên bạn gọi tác tử OpenClaw của mình. + Nhấp vào **Bot** trên thanh bên. Đặt **Username** thành bất cứ tên nào bạn gọi agent OpenClaw của mình. @@ -43,30 +43,30 @@ Bạn sẽ cần tạo một ứng dụng mới với bot, thêm bot vào máy c - **Message Content Intent** (bắt buộc) - **Server Members Intent** (khuyến nghị; bắt buộc cho danh sách cho phép theo vai trò và khớp tên với ID) - - **Presence Intent** (không bắt buộc; chỉ cần cho cập nhật trạng thái hiện diện) + - **Presence Intent** (tùy chọn; chỉ cần cho cập nhật trạng thái hiện diện) - Cuộn trở lại phía trên trang **Bot** và nhấp vào **Reset Token**. + Cuộn lại lên đầu trang **Bot** và nhấp vào **Reset Token**. - Dù tên là vậy, thao tác này tạo token đầu tiên của bạn — không có gì đang được "đặt lại". + Dù tên là vậy, thao tác này tạo token đầu tiên của bạn — không có gì đang bị "đặt lại". - Sao chép token và lưu lại ở đâu đó. Đây là **Bot Token** của bạn và bạn sẽ cần đến nó ngay sau đây. + Sao chép token và lưu ở đâu đó. Đây là **Bot Token** của bạn và bạn sẽ cần nó ngay sau đây. - Nhấp vào **OAuth2** trên thanh bên. Bạn sẽ tạo một URL mời với đúng quyền để thêm bot vào máy chủ của mình. + Nhấp vào **OAuth2** trên thanh bên. Bạn sẽ tạo URL mời với đúng quyền để thêm bot vào máy chủ của mình. Cuộn xuống **OAuth2 URL Generator** và bật: - `bot` - `applications.commands` - Một phần **Bot Permissions** sẽ xuất hiện bên dưới. Bật ít nhất: + Một mục **Bot Permissions** sẽ xuất hiện bên dưới. Bật ít nhất: **General Permissions** - View Channels @@ -75,33 +75,33 @@ Bạn sẽ cần tạo một ứng dụng mới với bot, thêm bot vào máy c - Read Message History - Embed Links - Attach Files - - Add Reactions (không bắt buộc) + - Add Reactions (tùy chọn) - Đây là tập cơ sở cho các kênh văn bản thông thường. Nếu bạn định đăng trong các thread Discord, bao gồm quy trình kênh diễn đàn hoặc kênh media tạo hoặc tiếp tục một thread, hãy bật cả **Send Messages in Threads**. - Sao chép URL được tạo ở cuối, dán vào trình duyệt, chọn máy chủ của bạn và nhấp **Continue** để kết nối. Bây giờ bạn sẽ thấy bot của mình trong máy chủ Discord. + Đây là bộ quyền nền tảng cho các kênh văn bản thông thường. Nếu bạn dự định đăng trong các thread Discord, bao gồm quy trình kênh diễn đàn hoặc kênh media tạo hoặc tiếp tục một thread, hãy bật thêm **Send Messages in Threads**. + Sao chép URL được tạo ở cuối trang, dán vào trình duyệt, chọn máy chủ của bạn, rồi nhấp **Continue** để kết nối. Bây giờ bạn sẽ thấy bot của mình trong máy chủ Discord. - Quay lại ứng dụng Discord, bạn cần bật Developer Mode để có thể sao chép các ID nội bộ. + Quay lại ứng dụng Discord, bạn cần bật Developer Mode để có thể sao chép ID nội bộ. - 1. Nhấp **User Settings** (biểu tượng bánh răng bên cạnh ảnh đại diện của bạn) → **Advanced** → bật **Developer Mode** + 1. Nhấp vào **User Settings** (biểu tượng bánh răng cạnh avatar của bạn) → **Advanced** → bật **Developer Mode** 2. Nhấp chuột phải vào **biểu tượng máy chủ** của bạn trong thanh bên → **Copy Server ID** - 3. Nhấp chuột phải vào **ảnh đại diện của chính bạn** → **Copy User ID** + 3. Nhấp chuột phải vào **avatar của chính bạn** → **Copy User ID** Lưu **Server ID** và **User ID** cùng với Bot Token của bạn — bạn sẽ gửi cả ba cho OpenClaw ở bước tiếp theo. - Để ghép nối hoạt động, Discord cần cho phép bot gửi DM cho bạn. Nhấp chuột phải vào **biểu tượng máy chủ** của bạn → **Privacy Settings** → bật **Direct Messages**. + Để ghép nối hoạt động, Discord cần cho phép bot DM cho bạn. Nhấp chuột phải vào **biểu tượng máy chủ** của bạn → **Privacy Settings** → bật **Direct Messages**. Điều này cho phép thành viên máy chủ (bao gồm bot) gửi DM cho bạn. Giữ tùy chọn này bật nếu bạn muốn dùng DM Discord với OpenClaw. Nếu bạn chỉ định dùng kênh guild, bạn có thể tắt DM sau khi ghép nối. - - Token bot Discord của bạn là bí mật (giống như mật khẩu). Đặt token trên máy đang chạy OpenClaw trước khi nhắn tin cho tác tử của bạn. + + Token bot Discord của bạn là bí mật (giống như mật khẩu). Thiết lập nó trên máy đang chạy OpenClaw trước khi nhắn tin cho agent của bạn. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,17 +120,17 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - Nếu OpenClaw đã chạy như một dịch vụ nền, hãy khởi động lại qua ứng dụng OpenClaw Mac hoặc bằng cách dừng rồi khởi động lại tiến trình `openclaw gateway run`. - Với các bản cài đặt dịch vụ được quản lý, chạy `openclaw gateway install` từ một shell có `DISCORD_BOT_TOKEN`, hoặc lưu biến trong `~/.openclaw/.env`, để dịch vụ có thể phân giải env SecretRef sau khi khởi động lại. - Nếu máy chủ của bạn bị Discord chặn hoặc giới hạn tốc độ khi tra cứu ứng dụng lúc khởi động, hãy đặt ID ứng dụng/client Discord từ Developer Portal để quá trình khởi động có thể bỏ qua lệnh gọi REST đó. Dùng `channels.discord.applicationId` cho tài khoản mặc định, hoặc `channels.discord.accounts..applicationId` khi bạn chạy nhiều bot Discord. + Nếu OpenClaw đã chạy dưới dạng dịch vụ nền, hãy khởi động lại qua ứng dụng OpenClaw Mac hoặc bằng cách dừng rồi khởi động lại tiến trình `openclaw gateway run`. + Với cài đặt dịch vụ được quản lý, chạy `openclaw gateway install` từ shell có sẵn `DISCORD_BOT_TOKEN`, hoặc lưu biến trong `~/.openclaw/.env`, để dịch vụ có thể phân giải SecretRef env sau khi khởi động lại. + Nếu host của bạn bị Discord chặn hoặc giới hạn tốc độ khi tra cứu ứng dụng lúc khởi động, hãy đặt ID ứng dụng/client Discord từ Developer Portal để quá trình khởi động có thể bỏ qua lệnh gọi REST đó. Dùng `channels.discord.applicationId` cho tài khoản mặc định, hoặc `channels.discord.accounts..applicationId` khi bạn chạy nhiều bot Discord. - - Trò chuyện với tác tử OpenClaw của bạn trên bất kỳ kênh hiện có nào (ví dụ Telegram) và cho tác tử biết. Nếu Discord là kênh đầu tiên của bạn, hãy dùng tab CLI / cấu hình thay thế. + + Chat với agent OpenClaw của bạn trên bất kỳ kênh hiện có nào (ví dụ Telegram) và nói cho nó biết. Nếu Discord là kênh đầu tiên của bạn, hãy dùng tab CLI / cấu hình thay thế. > "Tôi đã đặt token bot Discord trong cấu hình. Vui lòng hoàn tất thiết lập Discord với User ID `` và Server ID ``." @@ -158,9 +158,9 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - Với thiết lập theo script hoặc từ xa, ghi cùng khối JSON5 bằng `openclaw config patch --file ./discord.patch.json5 --dry-run` rồi chạy lại không có `--dry-run`. Giá trị `token` dạng văn bản thuần được hỗ trợ. Giá trị SecretRef cũng được hỗ trợ cho `channels.discord.token` trên các provider env/file/exec. Xem [Quản lý bí mật](/vi/gateway/secrets). + Với thiết lập bằng script hoặc từ xa, ghi cùng khối JSON5 bằng `openclaw config patch --file ./discord.patch.json5 --dry-run` rồi chạy lại không có `--dry-run`. Giá trị `token` dạng văn bản thuần được hỗ trợ. Giá trị SecretRef cũng được hỗ trợ cho `channels.discord.token` trên các provider env/file/exec. Xem [Quản lý bí mật](/vi/gateway/secrets). - Với nhiều bot Discord, giữ mỗi token bot và ID ứng dụng trong tài khoản của nó. `channels.discord.applicationId` cấp cao nhất được các tài khoản kế thừa, vì vậy chỉ đặt ở đó khi mọi tài khoản nên dùng cùng một ID ứng dụng. + Với nhiều bot Discord, giữ từng token bot và ID ứng dụng dưới tài khoản tương ứng. `channels.discord.applicationId` cấp cao nhất được kế thừa bởi các tài khoản, vì vậy chỉ đặt ở đó khi mọi tài khoản đều nên dùng cùng ID ứng dụng. ```json5 { @@ -188,11 +188,11 @@ DISCORD_BOT_TOKEN=... - Đợi đến khi gateway đang chạy, sau đó gửi DM cho bot của bạn trong Discord. Bot sẽ phản hồi bằng một mã ghép nối. + Chờ đến khi Gateway đang chạy, rồi DM bot của bạn trong Discord. Bot sẽ phản hồi bằng mã ghép nối. - - Gửi mã ghép nối cho tác tử của bạn trên kênh hiện có: + + Gửi mã ghép nối cho agent trên kênh hiện có của bạn: > "Phê duyệt mã ghép nối Discord này: ``" @@ -208,27 +208,27 @@ openclaw pairing approve discord Mã ghép nối hết hạn sau 1 giờ. - Bây giờ bạn có thể trò chuyện với tác tử của mình trong Discord qua DM. + Bây giờ bạn có thể chat với agent của mình trong Discord qua DM. -Việc phân giải token có nhận biết tài khoản. Giá trị token trong cấu hình thắng env fallback. `DISCORD_BOT_TOKEN` chỉ được dùng cho tài khoản mặc định. -Nếu hai tài khoản Discord đã bật phân giải tới cùng một token bot, OpenClaw chỉ khởi động một trình giám sát gateway cho token đó. Token từ cấu hình thắng env fallback mặc định; nếu không, tài khoản đã bật đầu tiên thắng và tài khoản trùng lặp được báo cáo là đã tắt. -Với các lệnh gọi đi nâng cao (công cụ message/hành động kênh), `token` rõ ràng theo từng lệnh gọi được dùng cho lệnh gọi đó. Điều này áp dụng cho các hành động kiểu gửi và đọc/thăm dò (ví dụ read/search/fetch/thread/pins/permissions). Cài đặt chính sách/thử lại của tài khoản vẫn đến từ tài khoản đã chọn trong snapshot runtime đang hoạt động. +Phân giải token có nhận biết tài khoản. Giá trị token trong cấu hình thắng env fallback. `DISCORD_BOT_TOKEN` chỉ được dùng cho tài khoản mặc định. +Nếu hai tài khoản Discord đã bật phân giải thành cùng một token bot, OpenClaw chỉ khởi động một trình giám sát Gateway cho token đó. Token lấy từ cấu hình thắng env fallback mặc định; nếu không, tài khoản đã bật đầu tiên thắng và tài khoản trùng lặp được báo cáo là đã tắt. +Với các lệnh gọi outbound nâng cao (công cụ tin nhắn/hành động kênh), `token` tường minh theo từng lệnh gọi được dùng cho lệnh gọi đó. Điều này áp dụng cho các hành động gửi và đọc/thăm dò (ví dụ read/search/fetch/thread/pins/permissions). Thiết lập chính sách/thử lại của tài khoản vẫn đến từ tài khoản đã chọn trong snapshot runtime đang hoạt động. -## Khuyến nghị: Thiết lập không gian làm việc guild +## Khuyến nghị: Thiết lập workspace guild -Sau khi DM hoạt động, bạn có thể thiết lập máy chủ Discord của mình như một không gian làm việc đầy đủ, nơi mỗi kênh có phiên tác tử riêng với ngữ cảnh riêng. Điều này được khuyến nghị cho các máy chủ riêng chỉ có bạn và bot của bạn. +Khi DM đã hoạt động, bạn có thể thiết lập máy chủ Discord của mình làm một workspace đầy đủ, nơi mỗi kênh có phiên agent riêng với ngữ cảnh riêng. Điều này được khuyến nghị cho máy chủ riêng tư chỉ có bạn và bot của bạn. - Điều này cho phép tác tử của bạn phản hồi trong bất kỳ kênh nào trên máy chủ của bạn, không chỉ DM. + Điều này cho phép agent của bạn phản hồi trong bất kỳ kênh nào trên máy chủ của bạn, không chỉ DM. - + > "Thêm Discord Server ID `` của tôi vào danh sách cho phép guild" @@ -254,14 +254,16 @@ Sau khi DM hoạt động, bạn có thể thiết lập máy chủ Discord củ - - Theo mặc định, tác tử của bạn chỉ phản hồi trong kênh guild khi được @mentioned. Với máy chủ riêng, có thể bạn muốn tác tử phản hồi mọi tin nhắn. + + Theo mặc định, agent của bạn chỉ phản hồi trong kênh guild khi được @mention. Với máy chủ riêng tư, có lẽ bạn muốn nó phản hồi mọi tin nhắn. - Trong kênh guild, các phản hồi cuối thông thường của trợ lý vẫn riêng tư theo mặc định. Đầu ra Discord hiển thị phải được gửi rõ ràng bằng công cụ `message`, để tác tử có thể quan sát mặc định và chỉ đăng khi quyết định rằng phản hồi kênh là hữu ích. + Trong kênh guild, phản hồi cuối thông thường của assistant mặc định vẫn ở chế độ riêng tư. Đầu ra Discord hiển thị phải được gửi tường minh bằng công cụ `message`, để agent có thể âm thầm theo dõi mặc định và chỉ đăng khi nó quyết định phản hồi trong kênh là hữu ích. + + Điều này nghĩa là model được chọn phải gọi công cụ một cách đáng tin cậy. Nếu Discord hiển thị đang nhập và log cho thấy có sử dụng token nhưng không có tin nhắn được đăng, hãy kiểm tra log phiên để tìm văn bản assistant với `didSendViaMessagingTool: false`. Điều đó nghĩa là model đã tạo câu trả lời cuối riêng tư thay vì gọi `message(action=send)`. Chuyển sang model gọi công cụ mạnh hơn, hoặc dùng cấu hình bên dưới để khôi phục phản hồi cuối tự động kiểu cũ. - - > "Cho phép tác tử của tôi phản hồi trên máy chủ này mà không cần được @mentioned" + + > "Cho phép agent của tôi phản hồi trên máy chủ này mà không cần được @mention" Đặt `requireMention: false` trong cấu hình guild của bạn: @@ -280,7 +282,7 @@ Sau khi DM hoạt động, bạn có thể thiết lập máy chủ Discord củ } ``` - Để khôi phục các phản hồi cuối tự động cũ cho phòng nhóm/kênh, đặt `messages.groupChat.visibleReplies: "automatic"`. + Để khôi phục phản hồi cuối tự động kiểu cũ cho phòng nhóm/kênh, đặt `messages.groupChat.visibleReplies: "automatic"`. @@ -291,85 +293,80 @@ Sau khi DM hoạt động, bạn có thể thiết lập máy chủ Discord củ Theo mặc định, bộ nhớ dài hạn (MEMORY.md) chỉ tải trong phiên DM. Kênh guild không tự động tải MEMORY.md. - + > "Khi tôi đặt câu hỏi trong kênh Discord, hãy dùng memory_search hoặc memory_get nếu bạn cần ngữ cảnh dài hạn từ MEMORY.md." - Nếu bạn cần ngữ cảnh dùng chung trong mọi kênh, hãy đặt các hướng dẫn ổn định trong `AGENTS.md` hoặc `USER.md` (chúng được chèn cho mọi phiên). Giữ ghi chú dài hạn trong `MEMORY.md` và truy cập chúng khi cần bằng công cụ bộ nhớ. + Nếu bạn cần ngữ cảnh dùng chung trong mọi kênh, hãy đặt các chỉ dẫn ổn định trong `AGENTS.md` hoặc `USER.md` (chúng được đưa vào mọi phiên). Giữ ghi chú dài hạn trong `MEMORY.md` và truy cập chúng khi cần bằng công cụ bộ nhớ. -Bây giờ hãy tạo một vài kênh trên máy chủ Discord của bạn và bắt đầu trò chuyện. Tác tử của bạn có thể thấy tên kênh, và mỗi kênh có phiên cô lập riêng — vì vậy bạn có thể thiết lập `#coding`, `#home`, `#research`, hoặc bất cứ gì phù hợp với quy trình làm việc của bạn. +Bây giờ hãy tạo một số kênh trên máy chủ Discord của bạn và bắt đầu chat. Agent của bạn có thể thấy tên kênh, và mỗi kênh có phiên tách biệt riêng — vì vậy bạn có thể thiết lập `#coding`, `#home`, `#research`, hoặc bất cứ gì phù hợp với quy trình làm việc của bạn. -## Mô hình runtime +## Model runtime -- Gateway sở hữu kết nối Discord. -- Định tuyến trả lời là xác định: các trả lời đến từ Discord sẽ quay lại Discord. -- Siêu dữ liệu guild/kênh Discord được thêm vào lời nhắc mô hình dưới dạng ngữ cảnh không đáng tin cậy, - không phải tiền tố trả lời hiển thị cho người dùng. Nếu mô hình sao chép phong bì đó - trở lại, OpenClaw sẽ loại bỏ siêu dữ liệu đã sao chép khỏi các trả lời gửi đi và khỏi - ngữ cảnh phát lại trong tương lai. -- Theo mặc định (`session.dmScope=main`), các cuộc trò chuyện trực tiếp dùng chung phiên chính của tác nhân (`agent:main:main`). -- Kênh guild là các khóa phiên cô lập (`agent::discord:channel:`). +- Gateway quản lý kết nối Discord. +- Định tuyến trả lời mang tính xác định: các trả lời đi vào từ Discord sẽ được trả lại Discord. +- Siêu dữ liệu guild/kênh Discord được thêm vào prompt mô hình dưới dạng ngữ cảnh không đáng tin cậy, không phải tiền tố trả lời hiển thị với người dùng. Nếu một mô hình sao chép lại lớp bao này, OpenClaw sẽ loại bỏ siêu dữ liệu đã sao chép khỏi các trả lời gửi đi và khỏi ngữ cảnh phát lại trong tương lai. +- Theo mặc định (`session.dmScope=main`), các cuộc trò chuyện trực tiếp dùng chung phiên chính của tác tử (`agent:main:main`). +- Các kênh guild là các khóa phiên tách biệt (`agent::discord:channel:`). - DM nhóm bị bỏ qua theo mặc định (`channels.discord.dm.groupEnabled=false`). -- Lệnh slash gốc chạy trong các phiên lệnh cô lập (`agent::discord:slash:`), trong khi vẫn mang `CommandTargetSessionKey` đến phiên hội thoại đã định tuyến. -- Việc phân phối thông báo cron/heartbeat chỉ có văn bản đến Discord sử dụng câu trả lời cuối cùng - mà trợ lý nhìn thấy một lần. Tải phương tiện và thành phần có cấu trúc vẫn là - nhiều tin nhắn khi tác nhân phát ra nhiều tải có thể phân phối. +- Các lệnh slash gốc chạy trong các phiên lệnh tách biệt (`agent::discord:slash:`), đồng thời vẫn mang `CommandTargetSessionKey` đến phiên hội thoại đã định tuyến. +- Việc chuyển phát thông báo cron/heartbeat chỉ có văn bản đến Discord sử dụng câu trả lời cuối cùng hiển thị với trợ lý đúng một lần. Các payload phương tiện và thành phần có cấu trúc vẫn là nhiều tin nhắn khi tác tử phát ra nhiều payload có thể chuyển phát. ## Kênh diễn đàn -Các kênh diễn đàn và phương tiện của Discord chỉ chấp nhận bài đăng luồng. OpenClaw hỗ trợ hai cách để tạo chúng: +Các kênh diễn đàn và phương tiện của Discord chỉ chấp nhận bài đăng trong luồng. OpenClaw hỗ trợ hai cách để tạo chúng: -- Gửi tin nhắn đến diễn đàn cha (`channel:`) để tự động tạo luồng. Tiêu đề luồng dùng dòng không trống đầu tiên trong tin nhắn của bạn. -- Dùng `openclaw message thread create` để tạo luồng trực tiếp. Không truyền `--message-id` cho kênh diễn đàn. +- Gửi một tin nhắn đến diễn đàn cha (`channel:`) để tự động tạo một luồng. Tiêu đề luồng dùng dòng không rỗng đầu tiên trong tin nhắn của bạn. +- Dùng `openclaw message thread create` để tạo luồng trực tiếp. Không truyền `--message-id` cho các kênh diễn đàn. -Ví dụ: gửi đến diễn đàn cha để tạo luồng +Ví dụ: gửi đến diễn đàn cha để tạo một luồng ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -Ví dụ: tạo luồng diễn đàn một cách tường minh +Ví dụ: tạo rõ ràng một luồng diễn đàn ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Diễn đàn cha không chấp nhận thành phần Discord. Nếu bạn cần thành phần, hãy gửi đến chính luồng đó (`channel:`). +Diễn đàn cha không chấp nhận các thành phần Discord. Nếu bạn cần thành phần, hãy gửi đến chính luồng đó (`channel:`). ## Thành phần tương tác -OpenClaw hỗ trợ vùng chứa thành phần Discord v2 cho tin nhắn tác nhân. Dùng công cụ tin nhắn với tải `components`. Kết quả tương tác được định tuyến trở lại tác nhân dưới dạng tin nhắn đến thông thường và tuân theo các cài đặt Discord `replyToMode` hiện có. +OpenClaw hỗ trợ vùng chứa thành phần Discord v2 cho tin nhắn tác tử. Dùng công cụ tin nhắn với payload `components`. Kết quả tương tác được định tuyến trở lại tác tử như các tin nhắn đi vào bình thường và tuân theo các cài đặt Discord `replyToMode` hiện có. Các khối được hỗ trợ: - `text`, `section`, `separator`, `actions`, `media-gallery`, `file` - Hàng hành động cho phép tối đa 5 nút hoặc một menu chọn duy nhất -- Kiểu chọn: `string`, `user`, `role`, `mentionable`, `channel` +- Loại chọn: `string`, `user`, `role`, `mentionable`, `channel` -Theo mặc định, thành phần chỉ dùng một lần. Đặt `components.reusable=true` để cho phép nút, lựa chọn và biểu mẫu được dùng nhiều lần cho đến khi hết hạn. +Theo mặc định, các thành phần chỉ dùng một lần. Đặt `components.reusable=true` để cho phép dùng nút, lựa chọn và biểu mẫu nhiều lần cho đến khi chúng hết hạn. -Để hạn chế ai có thể bấm nút, đặt `allowedUsers` trên nút đó (ID người dùng Discord, thẻ hoặc `*`). Khi được cấu hình, người dùng không khớp sẽ nhận một thông báo từ chối tạm thời. +Để giới hạn ai có thể bấm một nút, đặt `allowedUsers` trên nút đó (ID người dùng Discord, thẻ hoặc `*`). Khi được cấu hình, người dùng không khớp sẽ nhận được thông báo từ chối tạm thời. -Các lệnh slash `/model` và `/models` mở bộ chọn mô hình tương tác với danh sách thả xuống nhà cung cấp, mô hình và runtime tương thích, cùng bước Gửi. `/models add` không còn được khuyến nghị và hiện trả về thông báo ngừng sử dụng thay vì đăng ký mô hình từ cuộc trò chuyện. Trả lời của bộ chọn là tạm thời và chỉ người dùng gọi lệnh mới có thể dùng. +Các lệnh slash `/model` và `/models` mở một bộ chọn mô hình tương tác với các danh sách thả xuống nhà cung cấp, mô hình và runtime tương thích, cùng một bước Gửi. `/models add` đã bị ngừng dùng và giờ trả về thông báo ngừng dùng thay vì đăng ký mô hình từ trò chuyện. Trả lời của bộ chọn là tạm thời và chỉ người dùng gọi lệnh mới có thể sử dụng. Tệp đính kèm: -- Khối `file` phải trỏ đến một tham chiếu tệp đính kèm (`attachment://`) +- Các khối `file` phải trỏ đến một tham chiếu đính kèm (`attachment://`) - Cung cấp tệp đính kèm qua `media`/`path`/`filePath` (một tệp); dùng `media-gallery` cho nhiều tệp -- Dùng `filename` để ghi đè tên tải lên khi tên đó cần khớp với tham chiếu tệp đính kèm +- Dùng `filename` để ghi đè tên tải lên khi tên đó phải khớp với tham chiếu đính kèm Biểu mẫu modal: - Thêm `components.modal` với tối đa 5 trường -- Kiểu trường: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` -- OpenClaw tự động thêm nút kích hoạt +- Loại trường: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` +- OpenClaw tự động thêm một nút kích hoạt Ví dụ: @@ -441,25 +438,25 @@ Ví dụ: Thứ tự ưu tiên nhiều tài khoản: - `channels.discord.accounts.default.allowFrom` chỉ áp dụng cho tài khoản `default`. - - Với một tài khoản, `allowFrom` có độ ưu tiên cao hơn `dm.allowFrom` cũ. - - Tài khoản có tên kế thừa `channels.discord.allowFrom` khi `allowFrom` riêng và `dm.allowFrom` cũ của chúng chưa được đặt. + - Với một tài khoản, `allowFrom` được ưu tiên hơn `dm.allowFrom` cũ. + - Tài khoản có tên kế thừa `channels.discord.allowFrom` khi `allowFrom` của chính chúng và `dm.allowFrom` cũ chưa được đặt. - Tài khoản có tên không kế thừa `channels.discord.accounts.default.allowFrom`. `channels.discord.dm.policy` và `channels.discord.dm.allowFrom` cũ vẫn được đọc để tương thích. `openclaw doctor --fix` di chuyển chúng sang `dmPolicy` và `allowFrom` khi có thể làm vậy mà không thay đổi quyền truy cập. - Định dạng đích DM để phân phối: + Định dạng đích DM để chuyển phát: - `user:` - đề cập `<@id>` - ID dạng số trần thường được phân giải thành ID kênh khi một mặc định kênh đang hoạt động, nhưng các ID được liệt kê trong DM `allowFrom` hiệu lực của tài khoản được xem là đích DM người dùng để tương thích. + ID chỉ gồm số thường được phân giải thành ID kênh khi mặc định kênh đang hoạt động, nhưng các ID được liệt kê trong DM `allowFrom` hiệu lực của tài khoản được coi là đích DM người dùng để tương thích. - DM Discord có thể dùng các mục động `accessGroup:` trong `channels.discord.allowFrom`. + DM Discord có thể dùng các mục `accessGroup:` động trong `channels.discord.allowFrom`. - Tên nhóm truy cập được chia sẻ giữa các kênh tin nhắn. Dùng `type: "message.senders"` cho nhóm tĩnh có thành viên được biểu diễn bằng cú pháp `allowFrom` thông thường của từng kênh, hoặc `type: "discord.channelAudience"` khi đối tượng `ViewChannel` hiện tại của một kênh Discord nên xác định tư cách thành viên một cách động. Hành vi nhóm truy cập dùng chung được ghi lại tại đây: [Nhóm truy cập](/vi/channels/access-groups). + Tên nhóm truy cập được dùng chung giữa các kênh tin nhắn. Dùng `type: "message.senders"` cho một nhóm tĩnh có thành viên được biểu diễn bằng cú pháp `allowFrom` bình thường của từng kênh, hoặc `type: "discord.channelAudience"` khi đối tượng `ViewChannel` hiện tại của một kênh Discord nên xác định tư cách thành viên một cách động. Hành vi nhóm truy cập dùng chung được ghi tài liệu tại đây: [Nhóm truy cập](/vi/channels/access-groups). ```json5 { @@ -482,9 +479,9 @@ Ví dụ: } ``` - Một kênh văn bản Discord không có danh sách thành viên riêng. `type: "discord.channelAudience"` mô hình hóa tư cách thành viên như sau: người gửi DM là thành viên của guild đã cấu hình và hiện có quyền `ViewChannel` hiệu lực trên kênh đã cấu hình sau khi vai trò và ghi đè kênh được áp dụng. + Một kênh văn bản Discord không có danh sách thành viên riêng. `type: "discord.channelAudience"` mô hình hóa tư cách thành viên như sau: người gửi DM là thành viên của guild đã cấu hình và hiện có quyền `ViewChannel` hiệu lực trên kênh đã cấu hình sau khi áp dụng vai trò và ghi đè kênh. - Ví dụ: cho phép bất kỳ ai có thể xem `#maintainers` gửi DM cho bot, trong khi vẫn đóng DM với mọi người khác. + Ví dụ: cho phép bất kỳ ai có thể thấy `#maintainers` DM cho bot, trong khi vẫn đóng DM với mọi người khác. ```json5 { @@ -505,7 +502,7 @@ Ví dụ: } ``` - Bạn có thể trộn mục động và tĩnh: + Bạn có thể kết hợp các mục động và tĩnh: ```json5 { @@ -525,29 +522,29 @@ Ví dụ: } ``` - Tra cứu thất bại theo hướng đóng. Nếu Discord trả về `Missing Access`, tra cứu thành viên thất bại, hoặc kênh thuộc guild khác, người gửi DM được xem là không được ủy quyền. + Tra cứu thất bại theo hướng đóng. Nếu Discord trả về `Missing Access`, tra cứu thành viên thất bại, hoặc kênh thuộc một guild khác, người gửi DM được coi là không được ủy quyền. - Bật **Server Members Intent** trong Discord Developer Portal cho bot khi dùng nhóm truy cập theo đối tượng kênh. DM không bao gồm trạng thái thành viên guild, nên OpenClaw phân giải thành viên qua Discord REST tại thời điểm ủy quyền. + Bật **Server Members Intent** trong Discord Developer Portal cho bot khi dùng nhóm truy cập theo đối tượng kênh. DM không bao gồm trạng thái thành viên guild, vì vậy OpenClaw phân giải thành viên qua Discord REST tại thời điểm ủy quyền. - Việc xử lý guild được kiểm soát bởi `channels.discord.groupPolicy`: + Cách xử lý guild được kiểm soát bởi `channels.discord.groupPolicy`: - `open` - `allowlist` - `disabled` - Đường cơ sở bảo mật khi `channels.discord` tồn tại là `allowlist`. + Đường cơ sở an toàn khi `channels.discord` tồn tại là `allowlist`. Hành vi `allowlist`: - guild phải khớp với `channels.discord.guilds` (ưu tiên `id`, chấp nhận slug) - - danh sách cho phép người gửi tùy chọn: `users` (khuyến nghị ID ổn định) và `roles` (chỉ ID vai trò); nếu một trong hai được cấu hình, người gửi được cho phép khi khớp `users` HOẶC `roles` - - khớp trực tiếp theo tên/thẻ bị tắt theo mặc định; chỉ bật `channels.discord.dangerouslyAllowNameMatching: true` như chế độ tương thích phá kính trong trường hợp khẩn cấp - - tên/thẻ được hỗ trợ cho `users`, nhưng ID an toàn hơn; `openclaw security audit` cảnh báo khi mục tên/thẻ được dùng - - nếu guild có `channels` được cấu hình, các kênh không được liệt kê sẽ bị từ chối - - nếu guild không có khối `channels`, tất cả kênh trong guild có trong danh sách cho phép đó đều được cho phép + - danh sách cho phép người gửi tùy chọn: `users` (khuyến nghị ID ổn định) và `roles` (chỉ ID vai trò); nếu một trong hai được cấu hình, người gửi được phép khi họ khớp với `users` HOẶC `roles` + - khớp trực tiếp tên/thẻ bị tắt theo mặc định; chỉ bật `channels.discord.dangerouslyAllowNameMatching: true` dưới dạng chế độ tương thích khẩn cấp + - tên/thẻ được hỗ trợ cho `users`, nhưng ID an toàn hơn; `openclaw security audit` cảnh báo khi dùng các mục tên/thẻ + - nếu một guild có cấu hình `channels`, các kênh không được liệt kê sẽ bị từ chối + - nếu một guild không có khối `channels`, tất cả các kênh trong guild đã được cho phép đó đều được phép Ví dụ: @@ -573,23 +570,23 @@ Ví dụ: } ``` - Nếu bạn chỉ đặt `DISCORD_BOT_TOKEN` và không tạo khối `channels.discord`, phương án dự phòng runtime là `groupPolicy="allowlist"` (có cảnh báo trong nhật ký), ngay cả khi `channels.defaults.groupPolicy` là `open`. + Nếu bạn chỉ đặt `DISCORD_BOT_TOKEN` và không tạo khối `channels.discord`, dự phòng runtime là `groupPolicy="allowlist"` (kèm cảnh báo trong nhật ký), ngay cả khi `channels.defaults.groupPolicy` là `open`. - Tin nhắn guild được kiểm soát bằng đề cập theo mặc định. + Tin nhắn guild mặc định được kiểm soát bằng đề cập. Phát hiện đề cập bao gồm: - đề cập bot rõ ràng - mẫu đề cập đã cấu hình (`agents.list[].groupChat.mentionPatterns`, dự phòng `messages.groupChat.mentionPatterns`) - - hành vi trả lời ngầm đến bot trong các trường hợp được hỗ trợ + - hành vi trả lời ngầm định tới bot trong các trường hợp được hỗ trợ - Khi viết tin nhắn Discord gửi đi, dùng cú pháp đề cập chính tắc: `<@USER_ID>` cho người dùng, `<#CHANNEL_ID>` cho kênh, và `<@&ROLE_ID>` cho vai trò. Không dùng dạng đề cập biệt danh cũ `<@!USER_ID>`. + Khi viết tin nhắn Discord gửi đi, dùng cú pháp đề cập chính tắc: `<@USER_ID>` cho người dùng, `<#CHANNEL_ID>` cho kênh và `<@&ROLE_ID>` cho vai trò. Không dùng dạng đề cập biệt danh cũ `<@!USER_ID>`. `requireMention` được cấu hình theo từng guild/kênh (`channels.discord.guilds...`). - `ignoreOtherMentions` tùy chọn bỏ các tin nhắn đề cập người dùng/vai trò khác nhưng không đề cập bot (ngoại trừ @everyone/@here). + `ignoreOtherMentions` tùy chọn loại bỏ các tin nhắn đề cập người dùng/vai trò khác nhưng không đề cập bot (không tính @everyone/@here). DM nhóm: @@ -599,9 +596,9 @@ Ví dụ: -### Định tuyến tác nhân dựa trên vai trò +### Định tuyến tác tử dựa trên vai trò -Dùng `bindings[].match.roles` để định tuyến thành viên guild Discord đến các tác nhân khác nhau theo ID vai trò. Liên kết dựa trên vai trò chỉ chấp nhận ID vai trò và được đánh giá sau liên kết peer hoặc parent-peer và trước liên kết chỉ theo guild. Nếu một liên kết cũng đặt các trường khớp khác (ví dụ `peer` + `guildId` + `roles`), tất cả trường đã cấu hình phải khớp. +Dùng `bindings[].match.roles` để định tuyến thành viên guild Discord đến các tác tử khác nhau theo ID vai trò. Liên kết dựa trên vai trò chỉ chấp nhận ID vai trò và được đánh giá sau liên kết peer hoặc parent-peer và trước liên kết chỉ guild. Nếu một liên kết cũng đặt các trường khớp khác (ví dụ `peer` + `guildId` + `roles`), tất cả các trường đã cấu hình phải khớp. ```json5 { @@ -629,20 +626,20 @@ Dùng `bindings[].match.roles` để định tuyến thành viên guild Discord - `commands.native` mặc định là `"auto"` và được bật cho Discord. - Ghi đè theo từng kênh: `channels.discord.commands.native`. -- `commands.native=false` bỏ qua việc đăng ký và dọn dẹp slash-command của Discord trong khi khởi động. Các lệnh đã đăng ký trước đó có thể vẫn hiển thị trong Discord cho đến khi bạn xóa chúng khỏi ứng dụng Discord. -- Xác thực lệnh gốc dùng cùng danh sách cho phép/chính sách Discord như xử lý tin nhắn thông thường. -- Các lệnh vẫn có thể hiển thị trong UI Discord đối với những người dùng không được cấp quyền; quá trình thực thi vẫn áp dụng xác thực OpenClaw và trả về "không được cấp quyền". +- `commands.native=false` bỏ qua việc đăng ký và dọn dẹp slash-command của Discord trong quá trình khởi động. Các lệnh đã đăng ký trước đó có thể vẫn hiển thị trong Discord cho đến khi bạn xóa chúng khỏi ứng dụng Discord. +- Xác thực lệnh gốc dùng cùng allowlist/chính sách Discord như xử lý tin nhắn thông thường. +- Lệnh vẫn có thể hiển thị trong UI Discord cho người dùng không được cấp quyền; quá trình thực thi vẫn áp dụng xác thực OpenClaw và trả về "not authorized". Xem [Slash commands](/vi/tools/slash-commands) để biết danh mục lệnh và hành vi. -Cài đặt slash command mặc định: +Thiết lập slash command mặc định: - `ephemeral: true` ## Chi tiết tính năng - + Discord hỗ trợ thẻ trả lời trong đầu ra của agent: - `[[reply_to_current]]` @@ -656,20 +653,20 @@ Cài đặt slash command mặc định: - `batched` Lưu ý: `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. - `first` luôn gắn tham chiếu trả lời gốc ngầm định vào tin nhắn Discord gửi đi đầu tiên của lượt. + `first` luôn gắn tham chiếu trả lời gốc ngầm định vào tin nhắn Discord đầu tiên gửi ra cho lượt đó. `batched` chỉ gắn tham chiếu trả lời gốc ngầm định của Discord khi - lượt đến là một lô đã được debounce gồm nhiều tin nhắn. Điều này hữu ích - khi bạn muốn dùng trả lời gốc chủ yếu cho các cuộc trò chuyện bùng phát dễ mơ hồ, - chứ không phải mọi lượt chỉ có một tin nhắn. + lượt đến là một lô đã debounce gồm nhiều tin nhắn. Điều này hữu ích + khi bạn muốn trả lời gốc chủ yếu cho các cuộc trò chuyện bùng phát dễ mơ hồ, không phải mọi + lượt một tin nhắn. - ID tin nhắn được đưa vào ngữ cảnh/lịch sử để agent có thể nhắm đến các tin nhắn cụ thể. + ID tin nhắn được đưa vào ngữ cảnh/lịch sử để agent có thể nhắm tới các tin nhắn cụ thể. - - OpenClaw có thể stream bản nháp trả lời bằng cách gửi một tin nhắn tạm thời và chỉnh sửa nó khi văn bản đến. `channels.discord.streaming` nhận `off` (mặc định) | `partial` | `block` | `progress`. `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 kết quả cuối cùng; `streamMode` là bí danh cũ và được tự động di chuyển. + + OpenClaw có thể stream bản nháp trả lời bằng cách gửi một tin nhắn tạm thời và chỉnh sửa nó khi văn bản đến. `channels.discord.streaming` nhận `off` (mặc định) | `partial` | `block` | `progress`. `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 kết quả cuối cùng; `streamMode` là alias kế thừa và được tự động di chuyển. - Mặc định vẫn là `off` vì các lần chỉnh sửa bản xem trước Discord nhanh chóng chạm giới hạn tốc độ khi nhiều bot hoặc Gateway dùng chung một tài khoản. + Mặc định vẫn là `off` vì các lần chỉnh sửa bản xem trước của Discord nhanh chóng chạm giới hạn tốc độ khi nhiều bot hoặc Gateway dùng chung một tài khoản. ```json5 { @@ -687,15 +684,15 @@ Cài đặt slash command mặc định: ``` - `partial` chỉnh sửa một tin nhắn xem trước duy nhất khi token đến. - - `block` phát ra các đoạn có kích thước bản nháp (dùng `draftChunk` để tinh chỉnh kích thước và điểm ngắt, bị kẹp theo `textChunkLimit`). - - Kết quả cuối có media, lỗi và trả lời rõ ràng sẽ hủy các chỉnh sửa bản xem trước đang chờ. - - `streaming.preview.toolProgress` (mặc định `true`) kiểm soát liệu các cập nhật công cụ/tiến trình có dùng lại tin nhắn xem trước hay không. + - `block` phát các khối cỡ bản nháp (dùng `draftChunk` để tinh chỉnh kích thước và điểm ngắt, bị chặn tối đa ở `textChunkLimit`). + - Kết quả cuối cùng có media, lỗi và trả lời rõ ràng sẽ hủy các chỉnh sửa bản xem trước đang chờ. + - `streaming.preview.toolProgress` (mặc định `true`) kiểm soát việc cập nhật công cụ/tiến trình có tái dùng tin nhắn xem trước hay không. - Stream bản xem trước chỉ hỗ trợ văn bản; trả lời bằng media sẽ quay về cách gửi thông thường. Khi stream `block` được bật rõ ràng, OpenClaw bỏ qua stream bản xem trước để tránh stream hai lần. + Stream bản xem trước chỉ hỗ trợ văn bản; trả lời media quay về cách gửi thông thường. Khi stream `block` được bật rõ ràng, OpenClaw bỏ qua stream bản xem trước để tránh stream hai lần. - + Ngữ cảnh lịch sử guild: - `channels.discord.historyLimit` mặc định `20` @@ -707,28 +704,28 @@ Cài đặt slash command mặc định: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - Hành vi luồng: + Hành vi thread: - - Các thread Discord được định tuyến như phiên kênh và kế thừa cấu hình kênh cha trừ khi được ghi đè. - - Phiên thread kế thừa lựa chọn `/model` ở cấp phiên của kênh cha làm dự phòng chỉ cho model; các lựa chọn `/model` cục bộ của thread vẫn được ưu tiên và lịch sử transcript của cha không được sao chép trừ khi bật kế thừa transcript. - - `channels.discord.thread.inheritParent` (mặc định `false`) cho phép auto-thread mới khởi tạo từ transcript cha. Ghi đè theo từng tài khoản nằm dưới `channels.discord.accounts..thread.inheritParent`. - - Phản ứng từ công cụ tin nhắn có thể phân giải mục tiêu DM `user:`. + - Thread Discord được định tuyến như phiên kênh và kế thừa cấu hình kênh cha trừ khi bị ghi đè. + - Phiên thread kế thừa lựa chọn `/model` cấp phiên của kênh cha làm dự phòng chỉ cho model; lựa chọn `/model` cục bộ của thread vẫn được ưu tiên và lịch sử transcript cha không được sao chép trừ khi bật kế thừa transcript. + - `channels.discord.thread.inheritParent` (mặc định `false`) cho phép auto-thread mới được gieo dữ liệu từ transcript cha. Ghi đè theo từng tài khoản nằm dưới `channels.discord.accounts..thread.inheritParent`. + - Phản ứng từ message-tool có thể phân giải mục tiêu DM `user:`. - `guilds..channels..requireMention: false` được giữ nguyên trong dự phòng kích hoạt ở giai đoạn trả lời. - Chủ đề kênh được chèn làm ngữ cảnh **không đáng tin cậy**. Danh sách cho phép kiểm soát ai có thể kích hoạt agent, không phải là ranh giới biên tập lại toàn bộ ngữ cảnh bổ sung. + Chủ đề kênh được chèn dưới dạng ngữ cảnh **không đáng tin cậy**. Allowlists kiểm soát ai có thể kích hoạt agent, không phải ranh giới biên tập ngữ cảnh bổ sung đầy đủ. - - Discord có thể gắn một thread vào mục tiêu phiên để các tin nhắn tiếp theo trong thread đó tiếp tục được định tuyến đến cùng phiên (bao gồm cả phiên subagent). + + Discord có thể ràng buộc một thread với mục tiêu phiên để các tin nhắn tiếp theo trong thread đó tiếp tục định tuyến đến cùng phiên (bao gồm phiên subagent). Lệnh: - - `/focus ` gắn thread hiện tại/mới vào mục tiêu subagent/phiên - - `/unfocus` xóa liên kết thread hiện tại - - `/agents` hiển thị các lần chạy đang hoạt động và trạng thái liên kết - - `/session idle ` kiểm tra/cập nhật tự động bỏ focus do không hoạt động cho các liên kết đang focus - - `/session max-age ` kiểm tra/cập nhật tuổi tối đa cứng cho các liên kết đang focus + - `/focus ` ràng buộc thread hiện tại/mới với mục tiêu subagent/phiên + - `/unfocus` xóa ràng buộc thread hiện tại + - `/agents` hiển thị các lượt chạy đang hoạt động và trạng thái ràng buộc + - `/session idle ` kiểm tra/cập nhật tự động bỏ focus do không hoạt động cho các ràng buộc đã focus + - `/session max-age ` kiểm tra/cập nhật tuổi tối đa cứng cho các ràng buộc đã focus Cấu hình: @@ -759,17 +756,17 @@ Cài đặt slash command mặc định: - `session.threadBindings.*` đặt mặc định toàn cục. - `channels.discord.threadBindings.*` ghi đè hành vi Discord. - - `spawnSessions` kiểm soát tự động tạo/gắn thread cho `sessions_spawn({ thread: true })` và các lần spawn thread ACP. Mặc định: `true`. - - `defaultSpawnContext` kiểm soát ngữ cảnh subagent gốc cho các lần spawn gắn với thread. Mặc định: `"fork"`. - - Các khóa `spawnSubagentSessions`/`spawnAcpSessions` đã ngừng dùng được di chuyển bởi `openclaw doctor --fix`. - - Nếu liên kết thread bị tắt cho một tài khoản, `/focus` và các thao tác liên kết thread liên quan sẽ không khả dụng. + - `spawnSessions` kiểm soát việc tự động tạo/ràng buộc thread cho `sessions_spawn({ thread: true })` và các lần spawn thread ACP. Mặc định: `true`. + - `defaultSpawnContext` kiểm soát ngữ cảnh subagent gốc cho các lần spawn ràng buộc thread. Mặc định: `"fork"`. + - Các khóa `spawnSubagentSessions`/`spawnAcpSessions` không dùng nữa được di chuyển bởi `openclaw doctor --fix`. + - Nếu ràng buộc thread bị tắt cho một tài khoản, `/focus` và các thao tác ràng buộc thread liên quan sẽ không khả dụng. Xem [Sub-agents](/vi/tools/subagents), [ACP Agents](/vi/tools/acp-agents), và [Configuration Reference](/vi/gateway/configuration-reference). - - Đối với workspace ACP ổn định "luôn bật", hãy cấu hình liên kết ACP có kiểu ở cấp cao nhất nhắm đến các cuộc trò chuyện Discord. + + Với các không gian làm việc ACP ổn định "always-on", hãy cấu hình các ràng buộc ACP có kiểu ở cấp cao nhất nhắm tới cuộc trò chuyện Discord. Đường dẫn cấu hình: @@ -825,44 +822,44 @@ Cài đặt slash command mặc định: Ghi chú: - - `/acp spawn codex --bind here` gắn kênh hoặc thread hiện tại tại chỗ và giữ các tin nhắn tương lai trên cùng phiên ACP. Tin nhắn trong thread kế thừa liên kết kênh cha. - - Trong kênh hoặc thread đã gắn, `/new` và `/reset` đặt lại cùng phiên ACP tại chỗ. Liên kết thread tạm thời có thể ghi đè phân giải mục tiêu khi đang hoạt động. - - `spawnSessions` kiểm soát việc tạo/gắn thread con qua `--thread auto|here`. + - `/acp spawn codex --bind here` ràng buộc kênh hoặc thread hiện tại tại chỗ và giữ các tin nhắn tương lai trên cùng phiên ACP. Tin nhắn thread kế thừa ràng buộc kênh cha. + - Trong kênh hoặc thread đã ràng buộc, `/new` và `/reset` đặt lại cùng phiên ACP tại chỗ. Ràng buộc thread tạm thời có thể ghi đè phân giải mục tiêu khi đang hoạt động. + - `spawnSessions` kiểm soát việc tạo/ràng buộc thread con thông qua `--thread auto|here`. - Xem [ACP Agents](/vi/tools/acp-agents) để biết chi tiết hành vi liên kết. + Xem [ACP Agents](/vi/tools/acp-agents) để biết chi tiết hành vi ràng buộc. - - Chế độ thông báo phản ứng theo từng guild: + + Chế độ thông báo reaction theo từng guild: - `off` - `own` (mặc định) - `all` - `allowlist` (dùng `guilds..users`) - Sự kiện phản ứng được chuyển thành sự kiện hệ thống và gắn vào phiên Discord đã định tuyến. + Sự kiện reaction được chuyển thành sự kiện hệ thống và gắn vào phiên Discord đã định tuyến. - - `ackReaction` gửi một emoji xác nhận trong khi OpenClaw đang xử lý tin nhắn đến. + + `ackReaction` gửi emoji xác nhận trong khi OpenClaw đang xử lý tin nhắn đến. Thứ tự phân giải: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - dự phòng emoji danh tính agent (`agents.list[].identity.emoji`, nếu không thì "👀") + - dự phòng emoji nhận diện agent (`agents.list[].identity.emoji`, nếu không có thì "👀") Ghi chú: - Discord chấp nhận emoji unicode hoặc tên emoji tùy chỉnh. - - Dùng `""` để tắt phản ứng cho một kênh hoặc tài khoản. + - Dùng `""` để tắt reaction cho một kênh hoặc tài khoản. - + Ghi cấu hình do kênh khởi tạo được bật theo mặc định. Điều này ảnh hưởng đến các luồng `/config set|unset` (khi tính năng lệnh được bật). @@ -881,8 +878,8 @@ Cài đặt slash command mặc định: - - Định tuyến lưu lượng WebSocket Gateway Discord và các tra cứu REST khi khởi động (ID ứng dụng + phân giải danh sách cho phép) qua proxy HTTP(S) bằng `channels.discord.proxy`. + + Định tuyến lưu lượng WebSocket của Gateway Discord và các tra cứu REST khi khởi động (ID ứng dụng + phân giải allowlist) qua proxy HTTP(S) bằng `channels.discord.proxy`. ```json5 { @@ -894,7 +891,7 @@ Cài đặt slash command mặc định: } ``` - Ghi đè theo tài khoản: + Ghi đè theo từng tài khoản: ```json5 { @@ -912,8 +909,8 @@ Cài đặt slash command mặc định: - - Bật phân giải PluralKit để ánh xạ tin nhắn được proxy đến danh tính thành viên hệ thống: + + Bật phân giải PluralKit để ánh xạ tin nhắn được proxy tới danh tính thành viên hệ thống: ```json5 { @@ -930,15 +927,15 @@ Cài đặt slash command mặc định: Ghi chú: - - danh sách cho phép có thể dùng `pk:` + - allowlists có thể dùng `pk:` - tên hiển thị của thành viên chỉ được khớp theo tên/slug khi `channels.discord.dangerouslyAllowNameMatching: true` - tra cứu dùng ID tin nhắn gốc và bị giới hạn theo cửa sổ thời gian - - nếu tra cứu thất bại, tin nhắn được proxy được xử lý như tin nhắn bot và bị bỏ qua trừ khi `allowBots=true` + - nếu tra cứu thất bại, tin nhắn được proxy được coi là tin nhắn bot và bị bỏ qua trừ khi `allowBots=true` - - Dùng `mentionAliases` khi agent cần đề cập gửi đi xác định được cho người dùng Discord đã biết. Khóa là handle không có ký tự `@` ở đầu; giá trị là ID người dùng Discord. Handle không xác định, `@everyone`, `@here`, và đề cập bên trong code span Markdown được giữ nguyên. + + Dùng `mentionAliases` khi agent cần mention gửi ra có tính xác định cho người dùng Discord đã biết. Khóa là handle không có `@` ở đầu; giá trị là ID người dùng Discord. Handle không xác định, `@everyone`, `@here`, và mention bên trong code span Markdown được giữ nguyên. ```json5 { @@ -961,8 +958,8 @@ Cài đặt slash command mặc định: - - Cập nhật hiện diện được áp dụng khi bạn đặt trường trạng thái hoặc hoạt động, hoặc khi bạn bật hiện diện tự động. + + Cập nhật presence được áp dụng khi bạn đặt trường trạng thái hoặc hoạt động, hoặc khi bạn bật auto presence. Ví dụ chỉ trạng thái: @@ -976,7 +973,7 @@ Cài đặt slash command mặc định: } ``` - Ví dụ hoạt động (trạng thái tùy chỉnh là kiểu hoạt động mặc định): + Ví dụ hoạt động (trạng thái tùy chỉnh là loại hoạt động mặc định): ```json5 { @@ -1003,16 +1000,16 @@ Cài đặt slash command mặc định: } ``` - Bản đồ kiểu hoạt động: + Bản đồ loại hoạt động: - - 0: Đang chơi - - 1: Đang stream (yêu cầu `activityUrl`) - - 2: Đang nghe - - 3: Đang xem - - 4: Tùy chỉnh (dùng văn bản hoạt động làm trạng thái; emoji là tùy chọn) - - 5: Đang thi đấu + - 0: Playing + - 1: Streaming (yêu cầu `activityUrl`) + - 2: Listening + - 3: Watching + - 4: Custom (dùng văn bản hoạt động làm trạng thái; emoji là tùy chọn) + - 5: Competing - Ví dụ hiện diện tự động (tín hiệu sức khỏe runtime): + Ví dụ auto presence (tín hiệu sức khỏe runtime): ```json5 { @@ -1029,7 +1026,7 @@ Cài đặt slash command mặc định: } ``` - Hiện diện tự động ánh xạ mức khả dụng runtime sang trạng thái Discord: khỏe mạnh => online, suy giảm hoặc không xác định => idle, cạn kiệt hoặc không khả dụng => dnd. Ghi đè văn bản tùy chọn: + Auto presence ánh xạ mức sẵn sàng của runtime sang trạng thái Discord: healthy => online, degraded hoặc unknown => idle, exhausted hoặc unavailable => dnd. Ghi đè văn bản tùy chọn: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1037,8 +1034,8 @@ Cài đặt slash command mặc định: - - Discord hỗ trợ xử lý phê duyệt bằng nút trong DM và có thể tùy chọn đăng lời nhắc phê duyệt trong kênh khởi nguồn. + + Discord hỗ trợ xử lý phê duyệt bằng nút trong DM và có thể tùy chọn đăng lời nhắc phê duyệt trong kênh phát sinh. Đường dẫn cấu hình: @@ -1047,32 +1044,32 @@ Cài đặt slash command mặc định: - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, mặc định: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord tự động bật phê duyệt thực thi gốc khi `enabled` chưa được đặt hoặc là `"auto"` và có thể phân giải ít nhất một người phê duyệt, từ `execApprovals.approvers` hoặc từ `commands.ownerAllowFrom`. Discord không suy luận người phê duyệt thực thi từ `allowFrom` của kênh, `dm.allowFrom` cũ, hoặc `defaultTo` của tin nhắn trực tiếp. Đặt `enabled: false` để tắt rõ ràng Discord như một máy khách phê duyệt gốc. + Discord tự động bật phê duyệt exec gốc khi `enabled` chưa được đặt hoặc là `"auto"` và có thể phân giải ít nhất một người phê duyệt, từ `execApprovals.approvers` hoặc từ `commands.ownerAllowFrom`. Discord không suy luận người phê duyệt exec từ `allowFrom` của kênh, `dm.allowFrom` cũ, hoặc `defaultTo` của tin nhắn trực tiếp. Đặt `enabled: false` để tắt rõ ràng Discord với vai trò ứng dụng khách phê duyệt gốc. - Với các lệnh nhóm nhạy cảm chỉ dành cho chủ sở hữu như `/diagnostics` và `/export-trajectory`, OpenClaw gửi lời nhắc phê duyệt và kết quả cuối cùng một cách riêng tư. OpenClaw thử Discord DM trước khi chủ sở hữu gọi lệnh có tuyến chủ sở hữu Discord; nếu không có, OpenClaw quay về tuyến chủ sở hữu khả dụng đầu tiên từ `commands.ownerAllowFrom`, chẳng hạn như Telegram. + Với các lệnh nhóm nhạy cảm chỉ dành cho chủ sở hữu như `/diagnostics` và `/export-trajectory`, OpenClaw gửi lời nhắc phê duyệt và kết quả cuối cùng một cách riêng tư. OpenClaw thử DM Discord trước khi chủ sở hữu gọi lệnh có tuyến chủ sở hữu Discord; nếu không có, OpenClaw quay về tuyến chủ sở hữu khả dụng đầu tiên từ `commands.ownerAllowFrom`, chẳng hạn như Telegram. - Khi `target` là `channel` hoặc `both`, lời nhắc phê duyệt hiển thị trong kênh. Chỉ những người phê duyệt đã được phân giải mới có thể dùng các nút; người dùng khác nhận được từ chối tạm thời. Lời nhắc phê duyệt bao gồm văn bản lệnh, vì vậy chỉ bật gửi qua kênh trong các kênh đáng tin cậy. Nếu không thể suy ra ID kênh từ khóa phiên, OpenClaw quay về gửi qua DM. + Khi `target` là `channel` hoặc `both`, lời nhắc phê duyệt sẽ hiển thị trong kênh. Chỉ những người phê duyệt đã được phân giải mới có thể dùng các nút; người dùng khác nhận thông báo từ chối tạm thời. Lời nhắc phê duyệt bao gồm văn bản lệnh, vì vậy chỉ bật gửi qua kênh trong các kênh đáng tin cậy. Nếu không thể suy ra ID kênh từ khóa phiên, OpenClaw quay về gửi bằng DM. - Discord cũng hiển thị các nút phê duyệt dùng chung được các kênh trò chuyện khác sử dụng. Bộ điều hợp Discord gốc chủ yếu thêm định tuyến DM cho người phê duyệt và phát tán qua kênh. - Khi có các nút đó, chúng là UX phê duyệt chính; OpenClaw + Discord cũng hiển thị các nút phê duyệt dùng chung được các kênh trò chuyện khác sử dụng. Bộ chuyển đổi Discord gốc chủ yếu bổ sung định tuyến DM cho người phê duyệt và phát tán tới kênh. + Khi các nút đó xuất hiện, chúng là trải nghiệm phê duyệt chính; OpenClaw chỉ nên bao gồm lệnh `/approve` thủ công khi kết quả công cụ cho biết phê duyệt qua trò chuyện không khả dụng hoặc phê duyệt thủ công là đường dẫn duy nhất. - Nếu runtime phê duyệt gốc của Discord không hoạt động, OpenClaw giữ - lời nhắc `/approve ` xác định cục bộ hiển thị. Nếu - runtime đang hoạt động nhưng không thể gửi thẻ gốc đến bất kỳ đích nào, - OpenClaw gửi thông báo dự phòng trong cùng cuộc trò chuyện với lệnh `/approve` + Nếu runtime phê duyệt gốc của Discord không hoạt động, OpenClaw giữ cho + lời nhắc cục bộ xác định `/approve ` hiển thị. Nếu + runtime đang hoạt động nhưng không thể gửi thẻ gốc tới bất kỳ mục tiêu nào, + OpenClaw gửi thông báo dự phòng trong cùng cuộc trò chuyện kèm lệnh `/approve` chính xác từ phê duyệt đang chờ. - Xác thực Gateway và phân giải phê duyệt tuân theo hợp đồng máy khách Gateway dùng chung (ID `plugin:` phân giải qua `plugin.approval.resolve`; các ID khác qua `exec.approval.resolve`). Phê duyệt mặc định hết hạn sau 30 phút. + Xác thực Gateway và phân giải phê duyệt tuân theo hợp đồng ứng dụng khách Gateway dùng chung (ID `plugin:` phân giải qua `plugin.approval.resolve`; các ID khác qua `exec.approval.resolve`). Theo mặc định, phê duyệt hết hạn sau 30 phút. - Xem [Phê duyệt thực thi](/vi/tools/exec-approvals). + Xem [Phê duyệt exec](/vi/tools/exec-approvals). ## Công cụ và cổng hành động -Hành động tin nhắn Discord bao gồm nhắn tin, quản trị kênh, kiểm duyệt, trạng thái hiện diện, và hành động siêu dữ liệu. +Hành động tin nhắn Discord bao gồm nhắn tin, quản trị kênh, kiểm duyệt, trạng thái hiện diện và hành động siêu dữ liệu. Ví dụ cốt lõi: @@ -1081,7 +1078,7 @@ Ví dụ cốt lõi: - kiểm duyệt: `timeout`, `kick`, `ban` - trạng thái hiện diện: `setPresence` -Hành động `event-create` chấp nhận tham số `image` tùy chọn (URL hoặc đường dẫn tệp cục bộ) để đặt ảnh bìa sự kiện đã lên lịch. +Hành động `event-create` chấp nhận tham số `image` tùy chọn (URL hoặc đường dẫn tệp cục bộ) để đặt ảnh bìa cho sự kiện đã lên lịch. Cổng hành động nằm dưới `channels.discord.actions.*`. @@ -1089,18 +1086,18 @@ Hành vi cổng mặc định: | Nhóm hành động | Mặc định | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | đã bật | -| roles | đã tắt | -| moderation | đã tắt | -| presence | đã tắt | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | bật | +| roles | tắt | +| moderation | tắt | +| presence | tắt | -## UI thành phần v2 +## Giao diện người dùng Components v2 -OpenClaw dùng thành phần Discord v2 cho phê duyệt thực thi và dấu mốc xuyên ngữ cảnh. Hành động tin nhắn Discord cũng có thể nhận `components` cho UI tùy chỉnh (nâng cao; yêu cầu xây dựng payload thành phần qua công cụ discord), trong khi `embeds` cũ vẫn khả dụng nhưng không được khuyến nghị. +OpenClaw dùng components v2 của Discord cho phê duyệt exec và dấu đánh dấu xuyên ngữ cảnh. Hành động tin nhắn Discord cũng có thể chấp nhận `components` cho giao diện người dùng tùy chỉnh (nâng cao; yêu cầu xây dựng payload component qua công cụ discord), trong khi `embeds` cũ vẫn khả dụng nhưng không được khuyến nghị. -- `channels.discord.ui.components.accentColor` đặt màu nhấn dùng bởi vùng chứa thành phần Discord (hex). +- `channels.discord.ui.components.accentColor` đặt màu nhấn dùng bởi các vùng chứa component của Discord (hex). - Đặt theo từng tài khoản bằng `channels.discord.accounts..ui.components.accentColor`. -- `embeds` bị bỏ qua khi có thành phần v2. +- `embeds` bị bỏ qua khi components v2 xuất hiện. Ví dụ: @@ -1124,16 +1121,16 @@ Discord có hai bề mặt giọng nói riêng biệt: **kênh thoại** thời ### Kênh thoại -Danh sách thiết lập: +Danh sách kiểm tra thiết lập: 1. Bật Message Content Intent trong Discord Developer Portal. -2. Bật Server Members Intent khi dùng danh sách cho phép vai trò/người dùng. +2. Bật Server Members Intent khi dùng danh sách cho phép theo vai trò/người dùng. 3. Mời bot với phạm vi `bot` và `applications.commands`. -4. Cấp Connect, Speak, Send Messages, và Read Message History trong kênh thoại đích. +4. Cấp quyền Connect, Speak, Send Messages và Read Message History trong kênh thoại mục tiêu. 5. Bật lệnh gốc (`commands.native` hoặc `channels.discord.commands.native`). 6. Cấu hình `channels.discord.voice`. -Dùng `/vc join|leave|status` để điều khiển phiên. Lệnh dùng tác nhân mặc định của tài khoản và tuân theo cùng quy tắc danh sách cho phép và chính sách nhóm như các lệnh Discord khác. +Dùng `/vc join|leave|status` để điều khiển phiên. Lệnh dùng agent mặc định của tài khoản và tuân theo cùng các quy tắc danh sách cho phép và chính sách nhóm như các lệnh Discord khác. ```bash /vc join channel: @@ -1173,32 +1170,32 @@ Ví dụ tự động tham gia: Ghi chú: - `voice.tts` chỉ ghi đè `messages.tts` cho phát lại giọng nói. -- `voice.model` chỉ ghi đè LLM dùng cho phản hồi kênh thoại Discord. Để trống để kế thừa mô hình tác nhân được định tuyến. +- `voice.model` chỉ ghi đè LLM dùng cho phản hồi trong kênh thoại Discord. Để trống để kế thừa mô hình agent đã định tuyến. - STT dùng `tools.media.audio`; `voice.model` không ảnh hưởng đến phiên âm. -- Ghi đè `systemPrompt` Discord theo kênh áp dụng cho các lượt bản ghi thoại của kênh thoại đó. +- Các ghi đè `systemPrompt` Discord theo kênh áp dụng cho các lượt bản ghi thoại của kênh thoại đó. - Các lượt bản ghi thoại suy ra trạng thái chủ sở hữu từ `allowFrom` của Discord (hoặc `dm.allowFrom`); người nói không phải chủ sở hữu không thể truy cập công cụ chỉ dành cho chủ sở hữu (ví dụ `gateway` và `cron`). -- Giọng nói Discord là tùy chọn cho cấu hình chỉ văn bản; đặt `channels.discord.voice.enabled=true` (hoặc giữ khối `channels.discord.voice` hiện có) để bật lệnh `/vc`, runtime giọng nói, và intent Gateway `GuildVoiceStates`. -- `channels.discord.intents.voiceStates` có thể ghi đè rõ ràng đăng ký intent trạng thái giọng nói. Để trống để intent đi theo trạng thái bật giọng nói hiệu dụng. -- `voice.daveEncryption` và `voice.decryptionFailureTolerance` được truyền qua tùy chọn tham gia `@discordjs/voice`. +- Giọng nói Discord là tùy chọn bật thêm đối với cấu hình chỉ văn bản; đặt `channels.discord.voice.enabled=true` (hoặc giữ một khối `channels.discord.voice` hiện có) để bật lệnh `/vc`, runtime giọng nói và intent Gateway `GuildVoiceStates`. +- `channels.discord.intents.voiceStates` có thể ghi đè rõ ràng đăng ký intent trạng thái thoại. Để trống để intent tuân theo trạng thái bật giọng nói hiệu dụng. +- `voice.daveEncryption` và `voice.decryptionFailureTolerance` được truyền qua các tùy chọn tham gia của `@discordjs/voice`. - Mặc định của `@discordjs/voice` là `daveEncryption=true` và `decryptionFailureTolerance=24` nếu chưa đặt. - `voice.connectTimeoutMs` kiểm soát thời gian chờ Ready ban đầu của `@discordjs/voice` cho `/vc join` và các lần tự động tham gia. Mặc định: `30000`. -- `voice.reconnectGraceMs` kiểm soát thời gian OpenClaw chờ một phiên thoại đã ngắt kết nối bắt đầu kết nối lại trước khi hủy phiên đó. Mặc định: `15000`. -- OpenClaw cũng theo dõi lỗi giải mã khi nhận và tự động phục hồi bằng cách rời/tham gia lại kênh thoại sau khi có lỗi lặp lại trong một khoảng thời gian ngắn. -- Nếu nhật ký nhận liên tục hiển thị `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` sau khi cập nhật, hãy thu thập báo cáo phụ thuộc và nhật ký. Dòng `@discordjs/voice` đi kèm bao gồm bản sửa padding upstream từ discord.js PR #11449, đã đóng discord.js issue #11419. +- `voice.reconnectGraceMs` kiểm soát khoảng thời gian OpenClaw chờ một phiên thoại đã ngắt kết nối bắt đầu kết nối lại trước khi hủy phiên đó. Mặc định: `15000`. +- OpenClaw cũng theo dõi lỗi giải mã khi nhận và tự động khôi phục bằng cách rời/tham gia lại kênh thoại sau nhiều lỗi lặp lại trong một khoảng thời gian ngắn. +- Nếu nhật ký nhận liên tục hiển thị `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` sau khi cập nhật, hãy thu thập báo cáo phụ thuộc và nhật ký. Dòng `@discordjs/voice` được đóng gói bao gồm bản sửa lỗi đệm ngược dòng từ discord.js PR #11449, vốn đã đóng issue discord.js #11419. -Quy trình kênh thoại: +Pipeline kênh thoại: -- Thu PCM từ Discord được chuyển đổi thành tệp WAV tạm thời. +- Bản thu PCM Discord được chuyển đổi thành tệp tạm WAV. - `tools.media.audio` xử lý STT, ví dụ `openai/gpt-4o-mini-transcribe`. -- Bản ghi được gửi qua ingress và định tuyến Discord trong khi LLM phản hồi chạy với chính sách đầu ra giọng nói ẩn công cụ `tts` của tác nhân và yêu cầu trả về văn bản, vì giọng nói Discord sở hữu phát lại TTS cuối cùng. +- Bản ghi được gửi qua luồng vào và định tuyến của Discord trong khi LLM phản hồi chạy với chính sách đầu ra giọng nói ẩn công cụ `tts` của agent và yêu cầu văn bản trả về, vì giọng nói Discord sở hữu phát lại TTS cuối cùng. - `voice.model`, khi được đặt, chỉ ghi đè LLM phản hồi cho lượt kênh thoại này. -- `voice.tts` được hợp nhất lên trên `messages.tts`; âm thanh kết quả được phát trong kênh đã tham gia. +- `voice.tts` được hợp nhất đè lên `messages.tts`; âm thanh kết quả được phát trong kênh đã tham gia. Thông tin xác thực được phân giải theo từng thành phần: xác thực tuyến LLM cho `voice.model`, xác thực STT cho `tools.media.audio`, và xác thực TTS cho `messages.tts`/`voice.tts`. ### Tin nhắn thoại -Tin nhắn thoại Discord hiển thị bản xem trước dạng sóng và yêu cầu âm thanh OGG/Opus. OpenClaw tự động tạo dạng sóng, nhưng cần `ffmpeg` và `ffprobe` trên máy chủ gateway để kiểm tra và chuyển đổi. +Tin nhắn thoại Discord hiển thị bản xem trước dạng sóng và yêu cầu âm thanh OGG/Opus. OpenClaw tự động tạo dạng sóng, nhưng cần `ffmpeg` và `ffprobe` trên máy chủ Gateway để kiểm tra và chuyển đổi. - Cung cấp **đường dẫn tệp cục bộ** (URL bị từ chối). - Bỏ qua nội dung văn bản (Discord từ chối văn bản + tin nhắn thoại trong cùng payload). @@ -1223,7 +1220,7 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - xác minh `groupPolicy` - xác minh danh sách cho phép guild dưới `channels.discord.guilds` - - nếu có bản đồ `channels` của guild, chỉ các kênh được liệt kê mới được phép + - nếu bản đồ `channels` của guild tồn tại, chỉ các kênh được liệt kê mới được phép - xác minh hành vi `requireMention` và mẫu nhắc đến Kiểm tra hữu ích: @@ -1237,7 +1234,7 @@ openclaw logs --follow - Nguyên nhân thường gặp: + Nguyên nhân phổ biến: - `groupPolicy="allowlist"` không có danh sách cho phép guild/kênh khớp - `requireMention` được cấu hình sai vị trí (phải nằm dưới `channels.discord.guilds` hoặc mục kênh) @@ -1247,7 +1244,7 @@ openclaw logs --follow - Nhật ký điển hình: + Nhật ký thường gặp: - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` @@ -1256,9 +1253,9 @@ openclaw logs --follow - một tài khoản: `channels.discord.eventQueue.listenerTimeout` - nhiều tài khoản: `channels.discord.accounts..eventQueue.listenerTimeout` - - mục này chỉ kiểm soát công việc listener Gateway Discord, không kiểm soát thời lượng lượt tác nhân + - tùy chọn này chỉ kiểm soát công việc listener Gateway Discord, không kiểm soát vòng đời lượt agent - Discord không áp dụng thời gian chờ do kênh sở hữu cho các lượt tác nhân trong hàng đợi. Listener tin nhắn bàn giao ngay lập tức, và các lần chạy Discord trong hàng đợi giữ nguyên thứ tự theo phiên cho đến khi vòng đời phiên/công cụ/runtime hoàn tất hoặc hủy công việc. + Discord không áp dụng thời gian chờ do kênh sở hữu cho các lượt agent được xếp hàng. Listener tin nhắn bàn giao ngay lập tức, và các lần chạy Discord được xếp hàng giữ nguyên thứ tự theo phiên cho đến khi vòng đời phiên/công cụ/runtime hoàn tất hoặc hủy công việc. ```json5 { @@ -1278,54 +1275,54 @@ openclaw logs --follow - - OpenClaw lấy siêu dữ liệu `/gateway/bot` của Discord trước khi kết nối. Lỗi tạm thời quay về URL gateway mặc định của Discord và được giới hạn tần suất trong nhật ký. + + OpenClaw lấy siêu dữ liệu `/gateway/bot` của Discord trước khi kết nối. Lỗi tạm thời sẽ quay về URL gateway mặc định của Discord và được giới hạn tần suất trong nhật ký. Núm điều chỉnh thời gian chờ siêu dữ liệu: - một tài khoản: `channels.discord.gatewayInfoTimeoutMs` - nhiều tài khoản: `channels.discord.accounts..gatewayInfoTimeoutMs` - - dự phòng env khi cấu hình chưa đặt: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - dự phòng env khi cấu hình chưa được đặt: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - mặc định: `30000` (30 giây), tối đa: `120000` - OpenClaw chờ sự kiện `READY` của Gateway Discord trong quá trình khởi động và sau các lần kết nối lại khi chạy. Thiết lập nhiều tài khoản có giãn cách khởi động có thể cần cửa sổ READY khi khởi động dài hơn mặc định. + OpenClaw chờ sự kiện `READY` của gateway Discord trong quá trình khởi động và sau các lần kết nối lại khi chạy. Thiết lập nhiều tài khoản có khởi động lệch nhau có thể cần khoảng thời gian chờ READY khi khởi động dài hơn mặc định. - Các nút chỉnh thời gian chờ READY: + Các núm điều chỉnh thời gian chờ READY: - - khởi động một tài khoản: `channels.discord.gatewayReadyTimeoutMs` - - khởi động nhiều tài khoản: `channels.discord.accounts..gatewayReadyTimeoutMs` - - phương án dự phòng bằng env khi chưa đặt cấu hình khởi động: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` + - một tài khoản khi khởi động: `channels.discord.gatewayReadyTimeoutMs` + - nhiều tài khoản khi khởi động: `channels.discord.accounts..gatewayReadyTimeoutMs` + - giá trị dự phòng từ môi trường khi cấu hình chưa đặt: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` - mặc định khi khởi động: `15000` (15 giây), tối đa: `120000` - - thời gian chạy một tài khoản: `channels.discord.gatewayRuntimeReadyTimeoutMs` - - thời gian chạy nhiều tài khoản: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - - phương án dự phòng bằng env khi chưa đặt cấu hình thời gian chạy: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` + - một tài khoản khi chạy: `channels.discord.gatewayRuntimeReadyTimeoutMs` + - nhiều tài khoản khi chạy: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - giá trị dự phòng từ môi trường khi cấu hình chưa đặt: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - mặc định khi chạy: `30000` (30 giây), tối đa: `120000` - + Các kiểm tra quyền của `channels status --probe` chỉ hoạt động với ID kênh dạng số. Nếu bạn dùng khóa slug, việc khớp khi chạy vẫn có thể hoạt động, nhưng probe không thể xác minh đầy đủ quyền. - + - DM bị tắt: `channels.discord.dm.enabled=false` - chính sách DM bị tắt: `channels.discord.dmPolicy="disabled"` (cũ: `channels.discord.dm.policy`) - - đang chờ phê duyệt ghép nối ở chế độ `pairing` + - đang chờ phê duyệt ghép đôi trong chế độ `pairing` - Theo mặc định, tin nhắn do bot tạo sẽ bị bỏ qua. + Theo mặc định, các tin nhắn do bot tạo sẽ bị bỏ qua. - Nếu bạn đặt `channels.discord.allowBots=true`, hãy dùng quy tắc nhắc đến và danh sách cho phép nghiêm ngặt để tránh hành vi lặp. - Ưu tiên `channels.discord.allowBots="mentions"` để chỉ chấp nhận tin nhắn từ bot có nhắc đến bot. + Nếu bạn đặt `channels.discord.allowBots=true`, hãy dùng các quy tắc nhắc đến và danh sách cho phép nghiêm ngặt để tránh hành vi lặp. + Ưu tiên `channels.discord.allowBots="mentions"` để chỉ chấp nhận tin nhắn bot có nhắc đến bot. ```json5 { @@ -1352,9 +1349,9 @@ openclaw logs --follow - + - - giữ OpenClaw ở phiên bản hiện tại (`openclaw update`) để có logic khôi phục nhận thoại Discord + - luôn cập nhật OpenClaw (`openclaw update`) để có logic khôi phục nhận thoại Discord - xác nhận `channels.discord.voice.daveEncryption=true` (mặc định) - bắt đầu từ `channels.discord.voice.decryptionFailureTolerance=24` (mặc định upstream) và chỉ tinh chỉnh nếu cần - theo dõi nhật ký để tìm: @@ -1375,15 +1372,15 @@ Tham chiếu chính: [Tham chiếu cấu hình - Discord](/vi/gateway/config-cha - chính sách: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - lệnh: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - hàng đợi sự kiện: `eventQueue.listenerTimeout` (ngân sách listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- Gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` +- gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` - trả lời/lịch sử: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -- gửi: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` +- phân phối: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` - streaming: `streaming` (bí danh cũ: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- media/thử lại: `mediaMaxMb` (giới hạn tải lên Discord chiều đi, mặc định `100MB`), `retry` +- phương tiện/thử lại: `mediaMaxMb` (giới hạn lượt tải lên Discord đi, mặc định `100MB`), `retry` - hành động: `actions.*` - hiện diện: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` -- tính năng: `threadBindings`, `bindings[]` cấp cao nhất (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` +- tính năng: `threadBindings`, cấp cao nhất `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` @@ -1391,13 +1388,13 @@ Tham chiếu chính: [Tham chiếu cấu hình - Discord](/vi/gateway/config-cha - Xem token bot là bí mật (ưu tiên `DISCORD_BOT_TOKEN` trong môi trường được giám sát). - Cấp quyền Discord theo nguyên tắc đặc quyền tối thiểu. -- Nếu triển khai/trạng thái lệnh đã cũ, hãy khởi động lại Gateway và kiểm tra lại bằng `openclaw channels status --probe`. +- Nếu trạng thái/triển khai lệnh đã cũ, hãy khởi động lại gateway và kiểm tra lại bằng `openclaw channels status --probe`. ## Liên quan - - Ghép nối một người dùng Discord với Gateway. + + Ghép đôi người dùng Discord với gateway. Hành vi trò chuyện nhóm và danh sách cho phép. diff --git a/docs/vi/channels/googlechat.md b/docs/vi/channels/googlechat.md index 5bc17cab7..73232e432 100644 --- a/docs/vi/channels/googlechat.md +++ b/docs/vi/channels/googlechat.md @@ -1,18 +1,18 @@ --- read_when: - - Đang phát triển các tính năng kênh Google Chat + - Đang phát triển các tính năng cho kênh Google Chat summary: Trạng thái hỗ trợ, khả năng và cấu hình của ứng dụng Google Chat title: Google Chat x-i18n: - generated_at: "2026-05-02T10:33:33Z" + generated_at: "2026-05-04T02:21:26Z" model: gpt-5.5 provider: openai - source_hash: fdb8dcf651602e92801d7107646d853871ea6cef188a8733a831695a1243740e + source_hash: afa2ca4d9673396aa24a55ca5855a34ad26a4640c3a1f6928dbf7246e403cb04 source_path: channels/googlechat.md workflow: 16 --- -Trạng thái: Plugin có thể tải xuống cho tin nhắn trực tiếp + không gian qua Webhook của Google Chat API (chỉ HTTP). +Trạng thái: Plugin có thể tải xuống cho DM + không gian qua Google Chat API webhooks (chỉ HTTP). ## Cài đặt @@ -22,7 +22,7 @@ Cài đặt Google Chat trước khi cấu hình kênh: openclaw plugins install @openclaw/googlechat ``` -Bản checkout cục bộ (khi chạy từ repo git): +Bản checkout cục bộ (khi chạy từ một repo git): ```bash openclaw plugins install ./path/to/local/googlechat-plugin @@ -34,61 +34,61 @@ openclaw plugins install ./path/to/local/googlechat-plugin - Truy cập: [Thông tin xác thực Google Chat API](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) - Bật API nếu API chưa được bật. 2. Tạo một **Tài khoản dịch vụ**: - - Nhấn **Create Credentials** > **Service Account**. + - Nhấn **Tạo thông tin xác thực** > **Tài khoản dịch vụ**. - Đặt tên tùy ý (ví dụ: `openclaw-chat`). - - Để trống quyền (nhấn **Continue**). - - Để trống các principal có quyền truy cập (nhấn **Done**). + - Để trống quyền (nhấn **Tiếp tục**). + - Để trống các principal có quyền truy cập (nhấn **Xong**). 3. Tạo và tải xuống **Khóa JSON**: - Trong danh sách tài khoản dịch vụ, nhấp vào tài khoản bạn vừa tạo. - - Chuyển đến thẻ **Keys**. - - Nhấp **Add Key** > **Create new key**. - - Chọn **JSON** và nhấn **Create**. + - Chuyển đến tab **Khóa**. + - Nhấp **Thêm khóa** > **Tạo khóa mới**. + - Chọn **JSON** và nhấn **Tạo**. 4. Lưu tệp JSON đã tải xuống trên máy chủ gateway của bạn (ví dụ: `~/.openclaw/googlechat-service-account.json`). -5. Tạo một ứng dụng Google Chat trong [Cấu hình Chat trên Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): +5. Tạo một ứng dụng Google Chat trong [Cấu hình Chat của Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): - Điền **Thông tin ứng dụng**: - - **Tên ứng dụng**: (ví dụ: `OpenClaw`) - - **URL ảnh đại diện**: (ví dụ: `https://openclaw.ai/logo.png`) - - **Mô tả**: (ví dụ: `Personal AI Assistant`) + - **Tên ứng dụng**: (ví dụ `OpenClaw`) + - **URL ảnh đại diện**: (ví dụ `https://openclaw.ai/logo.png`) + - **Mô tả**: (ví dụ `Personal AI Assistant`) - Bật **Tính năng tương tác**. - Trong **Chức năng**, chọn **Tham gia không gian và cuộc trò chuyện nhóm**. - Trong **Cài đặt kết nối**, chọn **URL điểm cuối HTTP**. - - Trong **Trình kích hoạt**, chọn **Sử dụng một URL điểm cuối HTTP chung cho tất cả trình kích hoạt** và đặt thành URL công khai của gateway, theo sau là `/googlechat`. + - Trong **Kích hoạt**, chọn **Sử dụng một URL điểm cuối HTTP chung cho tất cả kích hoạt** và đặt thành URL công khai của gateway, theo sau là `/googlechat`. - _Mẹo: Chạy `openclaw status` để tìm URL công khai của gateway._ - - Trong **Mức độ hiển thị**, chọn **Cung cấp ứng dụng Chat này cho những người và nhóm cụ thể trong ``**. - - Nhập địa chỉ email của bạn (ví dụ: `user@example.com`) vào hộp văn bản. - - Nhấp **Save** ở cuối trang. + - Trong **Khả năng hiển thị**, chọn **Cho phép ứng dụng Chat này khả dụng với những người và nhóm cụ thể trong ``**. + - Nhập địa chỉ email của bạn (ví dụ `user@example.com`) vào hộp văn bản. + - Nhấp **Lưu** ở cuối trang. 6. **Bật trạng thái ứng dụng**: - Sau khi lưu, **làm mới trang**. - - Tìm phần **Trạng thái ứng dụng** (thường ở gần đầu hoặc cuối trang sau khi lưu). - - Đổi trạng thái thành **Live - available to users**. - - Nhấp **Save** lần nữa. -7. Cấu hình OpenClaw với đường dẫn tài khoản dịch vụ + đối tượng Webhook: + - Tìm phần **Trạng thái ứng dụng** (thường ở gần đầu hoặc cuối sau khi lưu). + - Đổi trạng thái thành **Đang hoạt động - khả dụng với người dùng**. + - Nhấp **Lưu** lần nữa. +7. Cấu hình OpenClaw với đường dẫn tài khoản dịch vụ + đối tượng nhận webhook: - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` - Hoặc cấu hình: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`. -8. Đặt loại + giá trị đối tượng Webhook (khớp với cấu hình ứng dụng Chat của bạn). -9. Khởi động gateway. Google Chat sẽ POST tới đường dẫn Webhook của bạn. +8. Đặt loại + giá trị đối tượng nhận webhook (khớp với cấu hình ứng dụng Chat của bạn). +9. Khởi động gateway. Google Chat sẽ POST tới đường dẫn webhook của bạn. ## Thêm vào Google Chat -Sau khi gateway đang chạy và email của bạn đã được thêm vào danh sách hiển thị: +Khi gateway đang chạy và email của bạn đã được thêm vào danh sách hiển thị: 1. Truy cập [Google Chat](https://chat.google.com/). -2. Nhấp biểu tượng **+** (dấu cộng) bên cạnh **Tin nhắn trực tiếp**. +2. Nhấp vào biểu tượng **+** (dấu cộng) bên cạnh **Tin nhắn trực tiếp**. 3. Trong thanh tìm kiếm (nơi bạn thường thêm người), nhập **Tên ứng dụng** bạn đã cấu hình trong Google Cloud Console. - - **Lưu ý**: Bot sẽ _không_ xuất hiện trong danh sách duyệt "Marketplace" vì đây là ứng dụng riêng tư. Bạn phải tìm kiếm bằng tên. + - **Lưu ý**: Bot sẽ _không_ xuất hiện trong danh sách duyệt "Marketplace" vì đây là ứng dụng riêng tư. Bạn phải tìm kiếm bot theo tên. 4. Chọn bot của bạn từ kết quả. -5. Nhấp **Add** hoặc **Chat** để bắt đầu cuộc trò chuyện 1:1. +5. Nhấp **Thêm** hoặc **Chat** để bắt đầu cuộc trò chuyện 1:1. 6. Gửi "Xin chào" để kích hoạt trợ lý! ## URL công khai (chỉ Webhook) -Webhook của Google Chat yêu cầu một điểm cuối HTTPS công khai. Vì lý do bảo mật, **chỉ để lộ đường dẫn `/googlechat`** ra internet. Giữ bảng điều khiển OpenClaw và các điểm cuối nhạy cảm khác trên mạng riêng của bạn. +Google Chat webhooks yêu cầu một điểm cuối HTTPS công khai. Vì lý do bảo mật, **chỉ để lộ đường dẫn `/googlechat`** ra internet. Giữ bảng điều khiển OpenClaw và các điểm cuối nhạy cảm khác trên mạng riêng của bạn. -### Tùy chọn A: Tailscale Funnel (Được khuyến nghị) +### Tùy chọn A: Tailscale Funnel (Khuyến nghị) -Dùng Tailscale Serve cho bảng điều khiển riêng tư và Funnel cho đường dẫn Webhook công khai. Cách này giữ `/` ở chế độ riêng tư trong khi chỉ để lộ `/googlechat`. +Dùng Tailscale Serve cho bảng điều khiển riêng tư và Funnel cho đường dẫn webhook công khai. Cách này giữ `/` ở trạng thái riêng tư trong khi chỉ để lộ `/googlechat`. -1. **Kiểm tra gateway của bạn đang được bind vào địa chỉ nào:** +1. **Kiểm tra gateway của bạn đang bind vào địa chỉ nào:** ```bash ss -tlnp | grep 18789 @@ -99,25 +99,25 @@ Dùng Tailscale Serve cho bảng điều khiển riêng tư và Funnel cho đư 2. **Chỉ để lộ bảng điều khiển cho tailnet (cổng 8443):** ```bash - # Nếu bind vào localhost (127.0.0.1 hoặc 0.0.0.0): + # If bound to localhost (127.0.0.1 or 0.0.0.0): tailscale serve --bg --https 8443 http://127.0.0.1:18789 - # Nếu chỉ bind vào IP Tailscale (ví dụ: 100.106.161.80): + # If bound to Tailscale IP only (e.g., 100.106.161.80): tailscale serve --bg --https 8443 http://100.106.161.80:18789 ``` -3. **Chỉ để lộ công khai đường dẫn Webhook:** +3. **Chỉ để lộ công khai đường dẫn webhook:** ```bash - # Nếu bind vào localhost (127.0.0.1 hoặc 0.0.0.0): + # If bound to localhost (127.0.0.1 or 0.0.0.0): tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat - # Nếu chỉ bind vào IP Tailscale (ví dụ: 100.106.161.80): + # If bound to Tailscale IP only (e.g., 100.106.161.80): tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat ``` -4. **Ủy quyền Node để truy cập Funnel:** - Nếu được nhắc, hãy truy cập URL ủy quyền hiển thị trong đầu ra để bật Funnel cho Node này trong chính sách tailnet của bạn. +4. **Ủy quyền cho node truy cập Funnel:** + Nếu được nhắc, hãy truy cập URL ủy quyền hiển thị trong đầu ra để bật Funnel cho node này trong chính sách tailnet của bạn. 5. **Xác minh cấu hình:** @@ -126,7 +126,7 @@ Dùng Tailscale Serve cho bảng điều khiển riêng tư và Funnel cho đư tailscale funnel status ``` -URL Webhook công khai của bạn sẽ là: +URL webhook công khai của bạn sẽ là: `https://..ts.net/googlechat` Bảng điều khiển riêng tư của bạn vẫn chỉ dành cho tailnet: @@ -134,7 +134,7 @@ Bảng điều khiển riêng tư của bạn vẫn chỉ dành cho tailnet: Dùng URL công khai (không có `:8443`) trong cấu hình ứng dụng Google Chat. -> Lưu ý: Cấu hình này vẫn tồn tại qua các lần khởi động lại. Để xóa sau này, chạy `tailscale funnel reset` và `tailscale serve reset`. +> Lưu ý: Cấu hình này vẫn tồn tại sau khi khởi động lại. Để gỡ bỏ sau này, chạy `tailscale funnel reset` và `tailscale serve reset`. ### Tùy chọn B: Reverse Proxy (Caddy) @@ -150,36 +150,36 @@ Với cấu hình này, mọi yêu cầu tới `your-domain.com/` sẽ bị bỏ ### Tùy chọn C: Cloudflare Tunnel -Cấu hình các quy tắc ingress của tunnel để chỉ định tuyến đường dẫn Webhook: +Cấu hình quy tắc ingress của tunnel để chỉ định tuyến đường dẫn webhook: - **Đường dẫn**: `/googlechat` -> `http://localhost:18789/googlechat` - **Quy tắc mặc định**: HTTP 404 (Không tìm thấy) ## Cách hoạt động -1. Google Chat gửi các webhook POST tới gateway. Mỗi yêu cầu bao gồm header `Authorization: Bearer `. - - OpenClaw xác minh bearer auth trước khi đọc/phân tích cú pháp toàn bộ body Webhook khi có header. - - Các yêu cầu Google Workspace Add-on mang `authorizationEventObject.systemIdToken` trong body được hỗ trợ qua ngân sách body tiền xác thực nghiêm ngặt hơn. -2. OpenClaw xác minh token theo `audienceType` + `audience` đã cấu hình: - - `audienceType: "app-url"` → audience là URL Webhook HTTPS của bạn. +1. Google Chat gửi webhook POST tới gateway. Mỗi yêu cầu bao gồm header `Authorization: Bearer `. + - OpenClaw xác minh bearer auth trước khi đọc/phân tích toàn bộ body webhook khi header hiện diện. + - Các yêu cầu Google Workspace Add-on mang `authorizationEventObject.systemIdToken` trong body được hỗ trợ thông qua ngân sách body tiền xác thực chặt chẽ hơn. +2. OpenClaw xác minh token với `audienceType` + `audience` đã cấu hình: + - `audienceType: "app-url"` → audience là URL webhook HTTPS của bạn. - `audienceType: "project-number"` → audience là số dự án Cloud. 3. Tin nhắn được định tuyến theo không gian: - - Tin nhắn trực tiếp dùng khóa phiên `agent::googlechat:direct:`. + - DM dùng khóa phiên `agent::googlechat:direct:`. - Không gian dùng khóa phiên `agent::googlechat:group:`. -4. Quyền truy cập tin nhắn trực tiếp mặc định là ghép nối. Người gửi không xác định nhận được mã ghép nối; phê duyệt bằng: +4. Quyền truy cập DM mặc định là ghép nối. Người gửi không xác định sẽ nhận mã ghép nối; phê duyệt bằng: - `openclaw pairing approve googlechat ` 5. Không gian nhóm mặc định yêu cầu @-mention. Dùng `botUser` nếu phát hiện mention cần tên người dùng của ứng dụng. ## Đích -Dùng các định danh này cho việc gửi và danh sách cho phép: +Dùng các định danh này để gửi và tạo danh sách cho phép: -- Tin nhắn trực tiếp: `users/` (được khuyến nghị). +- Tin nhắn trực tiếp: `users/` (khuyến nghị). - Email thô `name@example.com` có thể thay đổi và chỉ được dùng để khớp danh sách cho phép trực tiếp khi `channels.googlechat.dangerouslyAllowNameMatching: true`. -- Không dùng nữa: `users/` được xử lý là id người dùng, không phải danh sách cho phép email. +- Không dùng nữa: `users/` được coi là mã người dùng, không phải danh sách cho phép email. - Không gian: `spaces/`. -## Điểm nổi bật về cấu hình +## Điểm chính về cấu hình ```json5 { @@ -199,7 +199,7 @@ Dùng các định danh này cho việc gửi và danh sách cho phép: groupPolicy: "allowlist", groups: { "spaces/AAAA": { - allow: true, + enabled: true, requireMention: true, users: ["users/1234567890"], systemPrompt: "Short answers only.", @@ -216,15 +216,15 @@ Dùng các định danh này cho việc gửi và danh sách cho phép: Ghi chú: - Thông tin xác thực tài khoản dịch vụ cũng có thể được truyền inline bằng `serviceAccount` (chuỗi JSON). -- `serviceAccountRef` cũng được hỗ trợ (env/file SecretRef), bao gồm các ref theo từng tài khoản trong `channels.googlechat.accounts..serviceAccountRef`. -- Đường dẫn Webhook mặc định là `/googlechat` nếu `webhookPath` chưa được đặt. -- `dangerouslyAllowNameMatching` bật lại tính năng khớp principal email có thể thay đổi cho danh sách cho phép (chế độ tương thích khẩn cấp). -- Phản ứng có sẵn qua công cụ `reactions` và `channels action` khi `actions.reactions` được bật. -- Hành động tin nhắn cung cấp `send` cho văn bản và `upload-file` để gửi tệp đính kèm rõ ràng. `upload-file` chấp nhận `media` / `filePath` / `path` cùng với `message`, `filename`, và đích thread tùy chọn. -- `typingIndicator` hỗ trợ `none`, `message` (mặc định), và `reaction` (reaction yêu cầu OAuth người dùng). -- Tệp đính kèm được tải xuống qua Chat API và lưu trong pipeline media (kích thước bị giới hạn bởi `mediaMaxMb`). +- `serviceAccountRef` cũng được hỗ trợ (env/file SecretRef), bao gồm các ref theo từng tài khoản dưới `channels.googlechat.accounts..serviceAccountRef`. +- Đường dẫn webhook mặc định là `/googlechat` nếu `webhookPath` chưa được đặt. +- `dangerouslyAllowNameMatching` bật lại việc khớp principal email có thể thay đổi cho danh sách cho phép (chế độ tương thích phá kính). +- Reactions khả dụng qua công cụ `reactions` và `channels action` khi `actions.reactions` được bật. +- Hành động tin nhắn cung cấp `send` cho văn bản và `upload-file` cho gửi tệp đính kèm rõ ràng. `upload-file` chấp nhận `media` / `filePath` / `path` cùng với `message`, `filename` và đích thread tùy chọn. +- `typingIndicator` hỗ trợ `none`, `message` (mặc định) và `reaction` (`reaction` yêu cầu OAuth người dùng). +- Tệp đính kèm được tải xuống thông qua Chat API và lưu trong pipeline media (kích thước được giới hạn bởi `mediaMaxMb`). -Chi tiết tham chiếu secrets: [Quản lý secrets](/vi/gateway/secrets). +Chi tiết tham chiếu bí mật: [Quản lý bí mật](/vi/gateway/secrets). ## Khắc phục sự cố @@ -236,7 +236,7 @@ Nếu Google Cloud Logs Explorer hiển thị lỗi như: status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed ``` -Điều này nghĩa là handler Webhook chưa được đăng ký. Nguyên nhân thường gặp: +Điều này có nghĩa là trình xử lý webhook chưa được đăng ký. Nguyên nhân thường gặp: 1. **Kênh chưa được cấu hình**: Phần `channels.googlechat` bị thiếu trong cấu hình của bạn. Xác minh bằng: @@ -244,7 +244,7 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al openclaw config get channels.googlechat ``` - Nếu trả về "Config path not found", hãy thêm cấu hình (xem [Điểm nổi bật về cấu hình](#config-highlights)). + Nếu trả về "Config path not found", hãy thêm cấu hình (xem [Điểm chính về cấu hình](#config-highlights)). 2. **Plugin chưa được bật**: Kiểm tra trạng thái Plugin: @@ -267,23 +267,23 @@ openclaw channels status # Should show: Google Chat default: enabled, configured, ... ``` -### Vấn đề khác +### Sự cố khác -- Kiểm tra `openclaw channels status --probe` để xem lỗi xác thực hoặc cấu hình audience bị thiếu. -- Nếu không có tin nhắn nào đến, xác nhận URL Webhook + đăng ký sự kiện của ứng dụng Chat. -- Nếu cổng mention chặn phản hồi, đặt `botUser` thành tên tài nguyên người dùng của ứng dụng và xác minh `requireMention`. -- Dùng `openclaw logs --follow` trong khi gửi tin nhắn kiểm thử để xem các yêu cầu có đến gateway hay không. +- Kiểm tra `openclaw channels status --probe` để tìm lỗi xác thực hoặc thiếu cấu hình audience. +- Nếu không có tin nhắn nào đến, xác nhận URL webhook + đăng ký sự kiện của ứng dụng Chat. +- Nếu cổng mention chặn trả lời, đặt `botUser` thành tên tài nguyên người dùng của ứng dụng và xác minh `requireMention`. +- Dùng `openclaw logs --follow` trong khi gửi tin nhắn thử nghiệm để xem yêu cầu có đến gateway không. Tài liệu liên quan: - [Cấu hình Gateway](/vi/gateway/configuration) - [Bảo mật](/vi/gateway/security) -- [Phản ứng](/vi/tools/reactions) +- [Reactions](/vi/tools/reactions) ## Liên quan -- [Tổng quan về kênh](/vi/channels) — tất cả các kênh được hỗ trợ -- [Ghép nối](/vi/channels/pairing) — xác thực tin nhắn trực tiếp và luồng ghép nối +- [Tổng quan kênh](/vi/channels) — tất cả kênh được hỗ trợ +- [Ghép nối](/vi/channels/pairing) — xác thực DM và luồng ghép nối - [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và cổng mention - [Định tuyến kênh](/vi/channels/channel-routing) — định tuyến phiên cho tin nhắn - [Bảo mật](/vi/gateway/security) — mô hình truy cập và gia cố diff --git a/docs/vi/channels/groups.md b/docs/vi/channels/groups.md index 339e7463f..973ac2809 100644 --- a/docs/vi/channels/groups.md +++ b/docs/vi/channels/groups.md @@ -1,14 +1,14 @@ --- read_when: - - Thay đổi hành vi trò chuyện nhóm hoặc cơ chế yêu cầu nhắc đến + - Thay đổi hành vi trò chuyện nhóm hoặc cơ chế kiểm soát theo lượt nhắc đến sidebarTitle: Groups summary: Hành vi trò chuyện nhóm trên các nền tảng (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: Nhóm x-i18n: - generated_at: "2026-05-03T10:35:33Z" + generated_at: "2026-05-04T02:21:31Z" model: gpt-5.5 provider: openai - source_hash: 6fd4fcaa8335f1dc4b4b1a719d6654ab0c10530f74284269ed6205dd5f87c116 + source_hash: dea506c011a5d8f6155b2f56aacb236482cb8c5b7457001cb2171fd45932443d source_path: channels/groups.md workflow: 16 --- @@ -17,22 +17,22 @@ OpenClaw xử lý cuộc trò chuyện nhóm nhất quán trên các bề mặt: ## Giới thiệu cho người mới bắt đầu (2 phút) -OpenClaw "sống" trên chính các tài khoản nhắn tin của bạn. Không có người dùng bot WhatsApp riêng biệt. Nếu **bạn** ở trong một nhóm, OpenClaw có thể thấy nhóm đó và phản hồi ở đó. +OpenClaw "sống" trên chính các tài khoản nhắn tin của bạn. Không có người dùng bot WhatsApp riêng biệt. Nếu **bạn** ở trong một nhóm, OpenClaw có thể thấy nhóm đó và phản hồi tại đó. Hành vi mặc định: - Nhóm bị giới hạn (`groupPolicy: "allowlist"`). -- Phản hồi yêu cầu nhắc tên, trừ khi bạn tắt rõ ràng cổng nhắc tên. -- Phản hồi cuối bình thường trong nhóm/kênh mặc định là riêng tư. Kết quả hiển thị trong phòng dùng công cụ `message`. +- Phản hồi yêu cầu nhắc đến trừ khi bạn tắt rõ ràng cơ chế chặn theo nhắc đến. +- Phản hồi cuối thông thường trong nhóm/kênh mặc định là riêng tư. Đầu ra hiển thị trong phòng dùng công cụ `message`. -Diễn giải: người gửi trong danh sách cho phép có thể kích hoạt OpenClaw bằng cách nhắc tên nó. +Diễn giải: người gửi trong danh sách cho phép có thể kích hoạt OpenClaw bằng cách nhắc đến nó. **Tóm tắt** - **Quyền truy cập DM** được kiểm soát bởi `*.allowFrom`. - **Quyền truy cập nhóm** được kiểm soát bởi `*.groupPolicy` + danh sách cho phép (`*.groups`, `*.groupAllowFrom`). -- **Kích hoạt phản hồi** được kiểm soát bởi cổng nhắc tên (`requireMention`, `/activation`). +- **Kích hoạt phản hồi** được kiểm soát bởi cơ chế chặn theo nhắc đến (`requireMention`, `/activation`). @@ -48,16 +48,18 @@ otherwise -> reply ## Phản hồi hiển thị Đối với phòng nhóm/kênh, OpenClaw mặc định dùng `messages.groupChat.visibleReplies: "message_tool"`. -`openclaw doctor --fix` ghi mặc định này vào cấu hình kênh đã cấu hình nhưng còn thiếu nó. -Điều đó có nghĩa là tác tử vẫn xử lý lượt và có thể cập nhật trạng thái bộ nhớ/phiên, nhưng câu trả lời cuối bình thường của nó không tự động được đăng lại vào phòng. Để nói một cách hiển thị, tác tử dùng `message(action=send)`. +`openclaw doctor --fix` ghi giá trị mặc định này vào cấu hình kênh đã cấu hình nếu thiếu nó. +Điều đó nghĩa là agent vẫn xử lý lượt và có thể cập nhật trạng thái bộ nhớ/phiên, nhưng câu trả lời cuối thông thường của nó không tự động được đăng lại vào phòng. Để nói một cách hiển thị, agent dùng `message(action=send)`. -Nếu công cụ message không khả dụng theo chính sách công cụ đang hoạt động, OpenClaw sẽ quay về phản hồi hiển thị tự động thay vì âm thầm chặn phản hồi. `openclaw doctor` cảnh báo về điểm không khớp này. +Mặc định này phụ thuộc vào model/runtime gọi công cụ một cách đáng tin cậy. Nếu nhật ký hiển thị văn bản của assistant nhưng `didSendViaMessagingTool: false`, model đã trả lời riêng tư thay vì gọi công cụ message. Đó không phải là lỗi gửi của Discord/Slack/Telegram. Hãy dùng một model gọi công cụ đáng tin cậy cho phiên nhóm/kênh, hoặc đặt `messages.groupChat.visibleReplies: "automatic"` để khôi phục phản hồi cuối hiển thị kiểu cũ. -Đối với cuộc trò chuyện trực tiếp và bất kỳ lượt nguồn nào khác, dùng `messages.visibleReplies: "message_tool"` để áp dụng cùng hành vi phản hồi hiển thị chỉ qua công cụ trên toàn cục. Các harness cũng có thể chọn đây làm mặc định khi chưa đặt; harness Codex làm điều này cho cuộc trò chuyện trực tiếp ở chế độ Codex. `messages.groupChat.visibleReplies` vẫn là ghi đè cụ thể hơn cho phòng nhóm/kênh. +Nếu công cụ message không khả dụng dưới chính sách công cụ đang hoạt động, OpenClaw quay về phản hồi hiển thị tự động thay vì âm thầm chặn phản hồi. `openclaw doctor` cảnh báo về sự không khớp này. -Điều này thay thế mẫu cũ buộc mô hình trả lời `NO_REPLY` cho hầu hết lượt ở chế độ theo dõi thụ động. Trong chế độ chỉ dùng công cụ, không làm gì hiển thị đơn giản nghĩa là không gọi công cụ message. +Đối với cuộc trò chuyện trực tiếp và mọi lượt nguồn khác, dùng `messages.visibleReplies: "message_tool"` để áp dụng cùng hành vi phản hồi hiển thị chỉ qua công cụ trên toàn cục. Harness cũng có thể chọn giá trị này làm mặc định khi chưa đặt; Codex harness làm như vậy cho cuộc trò chuyện trực tiếp ở chế độ Codex. `messages.groupChat.visibleReplies` vẫn là ghi đè cụ thể hơn cho phòng nhóm/kênh. -Chỉ báo đang nhập vẫn được gửi trong khi tác tử làm việc ở chế độ chỉ dùng công cụ. Chế độ đang nhập mặc định của nhóm được nâng cấp từ "message" lên "instant" cho các lượt này vì có thể sẽ không bao giờ có văn bản tin nhắn trợ lý bình thường trước khi tác tử quyết định có gọi công cụ message hay không. Cấu hình chế độ đang nhập rõ ràng vẫn được ưu tiên. +Điều này thay thế mẫu cũ buộc model trả lời `NO_REPLY` cho hầu hết các lượt ở chế độ theo dõi thụ động. Trong chế độ chỉ qua công cụ, không hiển thị gì đơn giản nghĩa là không gọi công cụ message. + +Chỉ báo đang nhập vẫn được gửi trong khi agent làm việc ở chế độ chỉ qua công cụ. Chế độ đang nhập mặc định của nhóm được nâng từ "message" lên "instant" cho các lượt này vì có thể sẽ không bao giờ có văn bản tin nhắn assistant thông thường trước khi agent quyết định có gọi công cụ message hay không. Cấu hình chế độ đang nhập rõ ràng vẫn được ưu tiên. Để khôi phục phản hồi cuối tự động kiểu cũ cho phòng nhóm/kênh: @@ -71,9 +73,9 @@ Chỉ báo đang nhập vẫn được gửi trong khi tác tử làm việc ở } ``` -Gateway tải nóng cấu hình `messages` sau khi tệp được lưu. Chỉ khởi động lại khi theo dõi tệp hoặc tải lại cấu hình bị tắt trong triển khai. +Gateway tải nóng cấu hình `messages` sau khi tệp được lưu. Chỉ khởi động lại khi tính năng theo dõi tệp hoặc tải lại cấu hình bị tắt trong triển khai. -Để yêu cầu kết quả hiển thị đi qua công cụ message cho mọi cuộc trò chuyện nguồn: +Để yêu cầu đầu ra hiển thị đi qua công cụ message cho mọi cuộc trò chuyện nguồn: ```json5 { @@ -83,29 +85,29 @@ Gateway tải nóng cấu hình `messages` sau khi tệp được lưu. Chỉ kh } ``` -Lệnh gạch chéo gốc (Discord, Telegram và các bề mặt khác có hỗ trợ lệnh gốc) bỏ qua `visibleReplies: "message_tool"` và luôn trả lời hiển thị để UI lệnh gốc của kênh nhận được phản hồi nó mong đợi. Điều này chỉ áp dụng cho các lượt lệnh gốc đã được xác thực; lệnh `/...` được nhập như văn bản và các lượt trò chuyện thông thường vẫn tuân theo mặc định nhóm đã cấu hình. +Lệnh slash gốc (Discord, Telegram và các bề mặt khác có hỗ trợ lệnh gốc) bỏ qua `visibleReplies: "message_tool"` và luôn trả lời hiển thị để UI lệnh gốc của kênh nhận được phản hồi như mong đợi. Điều này chỉ áp dụng cho các lượt lệnh gốc đã được xác thực; lệnh `/...` được gõ dưới dạng văn bản và các lượt trò chuyện thông thường vẫn tuân theo mặc định nhóm đã cấu hình. ## Khả năng hiển thị ngữ cảnh và danh sách cho phép Có hai cơ chế kiểm soát khác nhau liên quan đến an toàn nhóm: -- **Ủy quyền kích hoạt**: ai có thể kích hoạt tác tử (`groupPolicy`, `groups`, `groupAllowFrom`, danh sách cho phép riêng theo kênh). -- **Khả năng hiển thị ngữ cảnh**: ngữ cảnh bổ sung nào được đưa vào mô hình (văn bản trả lời, trích dẫn, lịch sử luồng, siêu dữ liệu chuyển tiếp). +- **Ủy quyền kích hoạt**: ai có thể kích hoạt agent (`groupPolicy`, `groups`, `groupAllowFrom`, danh sách cho phép theo kênh). +- **Khả năng hiển thị ngữ cảnh**: ngữ cảnh bổ sung nào được đưa vào model (văn bản trả lời, trích dẫn, lịch sử luồng, siêu dữ liệu chuyển tiếp). -Theo mặc định, OpenClaw ưu tiên hành vi trò chuyện bình thường và giữ ngữ cảnh phần lớn như đã nhận. Điều này nghĩa là danh sách cho phép chủ yếu quyết định ai có thể kích hoạt hành động, chứ không phải ranh giới biên tập chung cho mọi đoạn trích dẫn hoặc lịch sử. +Theo mặc định, OpenClaw ưu tiên hành vi trò chuyện bình thường và giữ ngữ cảnh gần như đúng như đã nhận. Điều này nghĩa là danh sách cho phép chủ yếu quyết định ai có thể kích hoạt hành động, không phải là ranh giới biên tập phổ quát cho mọi đoạn trích dẫn hoặc đoạn lịch sử. - Một số kênh đã áp dụng lọc theo người gửi cho ngữ cảnh bổ sung trong các đường dẫn cụ thể (ví dụ gieo ngữ cảnh luồng Slack, tra cứu trả lời/luồng Matrix). - - Các kênh khác vẫn truyền ngữ cảnh trích dẫn/trả lời/chuyển tiếp như đã nhận. + - Các kênh khác vẫn truyền ngữ cảnh trích dẫn/trả lời/chuyển tiếp đúng như đã nhận. - + - `contextVisibility: "all"` (mặc định) giữ hành vi hiện tại như đã nhận. - `contextVisibility: "allowlist"` lọc ngữ cảnh bổ sung theo người gửi trong danh sách cho phép. - `contextVisibility: "allowlist_quote"` là `allowlist` cộng thêm một ngoại lệ trích dẫn/trả lời rõ ràng. - Cho đến khi mô hình tăng cường an toàn này được triển khai nhất quán trên các kênh, hãy dự kiến có khác biệt theo bề mặt. + Cho đến khi mô hình tăng cường bảo mật này được triển khai nhất quán trên các kênh, hãy dự kiến có khác biệt theo từng bề mặt. @@ -114,15 +116,15 @@ Theo mặc định, OpenClaw ưu tiên hành vi trò chuyện bình thường v Nếu bạn muốn... -| Mục tiêu | Cần đặt | +| Mục tiêu | Cần đặt | | -------------------------------------------- | ---------------------------------------------------------- | -| Cho phép tất cả nhóm nhưng chỉ trả lời khi có @nhắc tên | `groups: { "*": { requireMention: true } }` | -| Tắt tất cả phản hồi nhóm | `groupPolicy: "disabled"` | -| Chỉ các nhóm cụ thể | `groups: { "": { ... } }` (không có khóa `"*"`) | -| Chỉ bạn có thể kích hoạt trong nhóm | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | -| Tái sử dụng một tập người gửi đáng tin cậy trên nhiều kênh | `groupAllowFrom: ["accessGroup:operators"]` | +| Cho phép mọi nhóm nhưng chỉ trả lời khi @nhắc đến | `groups: { "*": { requireMention: true } }` | +| Tắt mọi phản hồi nhóm | `groupPolicy: "disabled"` | +| Chỉ các nhóm cụ thể | `groups: { "": { ... } }` (không có khóa `"*"` key) | +| Chỉ bạn có thể kích hoạt trong nhóm | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| Tái sử dụng một tập người gửi tin cậy trên nhiều kênh | `groupAllowFrom: ["accessGroup:operators"]` | -Để biết danh sách cho phép người gửi có thể tái sử dụng, xem [Nhóm truy cập](/vi/channels/access-groups). +Để dùng lại danh sách cho phép người gửi, xem [Nhóm truy cập](/vi/channels/access-groups). ## Khóa phiên @@ -133,19 +135,19 @@ Nếu bạn muốn... -## Mẫu: DM cá nhân + nhóm công khai (một tác tử) +## Mẫu: DM cá nhân + nhóm công khai (một agent) Có, cách này hoạt động tốt nếu lưu lượng "cá nhân" của bạn là **DM** và lưu lượng "công khai" của bạn là **nhóm**. -Lý do: trong chế độ một tác tử, DM thường đi vào khóa phiên **chính** (`agent:main:main`), trong khi nhóm luôn dùng khóa phiên **không chính** (`agent:main::group:`). Nếu bạn bật sandboxing với `mode: "non-main"`, các phiên nhóm đó chạy trong backend sandbox đã cấu hình, còn phiên DM chính của bạn vẫn ở trên host. Docker là backend mặc định nếu bạn không chọn backend nào. +Lý do: trong chế độ một agent, DM thường rơi vào khóa phiên **chính** (`agent:main:main`), trong khi nhóm luôn dùng khóa phiên **không chính** (`agent:main::group:`). Nếu bạn bật sandbox bằng `mode: "non-main"`, các phiên nhóm đó chạy trong backend sandbox đã cấu hình trong khi phiên DM chính của bạn vẫn ở trên host. Docker là backend mặc định nếu bạn không chọn backend nào. -Điều này cho bạn một "bộ não" tác tử (không gian làm việc + bộ nhớ dùng chung), nhưng hai tư thế thực thi: +Điều này cho bạn một "bộ não" agent (workspace + bộ nhớ dùng chung), nhưng hai tư thế thực thi: -- **DM**: đầy đủ công cụ (host) +- **DM**: công cụ đầy đủ (host) - **Nhóm**: sandbox + công cụ bị giới hạn -Nếu bạn cần không gian làm việc/chân dung thực sự tách biệt ("cá nhân" và "công khai" tuyệt đối không được trộn lẫn), hãy dùng tác tử thứ hai + bindings. Xem [Định tuyến đa tác tử](/vi/concepts/multi-agent). +Nếu bạn cần workspace/persona thực sự tách biệt ("cá nhân" và "công khai" không bao giờ được trộn lẫn), hãy dùng agent thứ hai + bindings. Xem [Định tuyến đa agent](/vi/concepts/multi-agent). @@ -202,7 +204,7 @@ Nếu bạn cần không gian làm việc/chân dung thực sự tách biệt (" Liên quan: - Khóa cấu hình và mặc định: [Cấu hình Gateway](/vi/gateway/config-agents#agentsdefaultssandbox) -- Gỡ lỗi vì sao công cụ bị chặn: [Sandbox so với Chính sách công cụ so với Đặc quyền nâng cao](/vi/gateway/sandbox-vs-tool-policy-vs-elevated) +- Gỡ lỗi vì sao một công cụ bị chặn: [Sandbox so với Chính sách công cụ so với Nâng quyền](/vi/gateway/sandbox-vs-tool-policy-vs-elevated) - Chi tiết bind mount: [Sandboxing](/vi/gateway/sandboxing#custom-bind-mounts) ## Nhãn hiển thị @@ -259,48 +261,48 @@ Kiểm soát cách xử lý tin nhắn nhóm/phòng theo từng kênh: } ``` -| Chính sách | Hành vi | +| Chính sách | Hành vi | | ------------- | ------------------------------------------------------------ | -| `"open"` | Nhóm bỏ qua danh sách cho phép; cổng nhắc tên vẫn áp dụng. | -| `"disabled"` | Chặn hoàn toàn tất cả tin nhắn nhóm. | +| `"open"` | Nhóm bỏ qua danh sách cho phép; cơ chế chặn theo nhắc đến vẫn áp dụng. | +| `"disabled"` | Chặn hoàn toàn mọi tin nhắn nhóm. | | `"allowlist"` | Chỉ cho phép nhóm/phòng khớp với danh sách cho phép đã cấu hình. | - - - `groupPolicy` tách biệt với cổng nhắc tên (yêu cầu @nhắc tên). + + - `groupPolicy` tách biệt với kiểm soát bằng lượt nhắc (yêu cầu @mentions). - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: dùng `groupAllowFrom` (dự phòng: `allowFrom` rõ ràng). - - Signal: `groupAllowFrom` có thể khớp với id nhóm Signal gửi đến hoặc số điện thoại/UUID của người gửi. - - Phê duyệt ghép cặp DM (mục lưu trữ `*-allowFrom`) chỉ áp dụng cho quyền truy cập DM; ủy quyền người gửi nhóm vẫn phải rõ ràng trong danh sách cho phép nhóm. + - Signal: `groupAllowFrom` có thể khớp với ID nhóm Signal đến hoặc số điện thoại/UUID của người gửi. + - Phê duyệt ghép nối DM (mục lưu trữ `*-allowFrom`) chỉ áp dụng cho quyền truy cập DM; việc cấp quyền cho người gửi trong nhóm vẫn phải được khai báo rõ trong danh sách cho phép của nhóm. - Discord: danh sách cho phép dùng `channels.discord.guilds..channels`. - Slack: danh sách cho phép dùng `channels.slack.channels`. - - Matrix: danh sách cho phép dùng `channels.matrix.groups`. Ưu tiên ID phòng hoặc bí danh; tra cứu tên phòng đã tham gia là nỗ lực tối đa, và tên không phân giải được sẽ bị bỏ qua khi chạy. Dùng `channels.matrix.groupAllowFrom` để giới hạn người gửi; danh sách cho phép `users` theo từng phòng cũng được hỗ trợ. + - Matrix: danh sách cho phép dùng `channels.matrix.groups`. Ưu tiên ID phòng hoặc bí danh; tra cứu tên phòng đã tham gia là nỗ lực tốt nhất, và các tên không phân giải được sẽ bị bỏ qua khi chạy. Dùng `channels.matrix.groupAllowFrom` để giới hạn người gửi; danh sách cho phép `users` theo từng phòng cũng được hỗ trợ. - DM nhóm được kiểm soát riêng (`channels.discord.dm.*`, `channels.slack.dm.*`). - - Danh sách cho phép Telegram có thể khớp với ID người dùng (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) hoặc tên người dùng (`"@alice"` hoặc `"alice"`); tiền tố không phân biệt chữ hoa/thường. + - Danh sách cho phép Telegram có thể khớp ID người dùng (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) hoặc tên người dùng (`"@alice"` hoặc `"alice"`); tiền tố không phân biệt hoa thường. - Mặc định là `groupPolicy: "allowlist"`; nếu danh sách cho phép nhóm của bạn trống, tin nhắn nhóm sẽ bị chặn. - - An toàn khi chạy: khi một khối provider hoàn toàn bị thiếu (không có `channels.`), chính sách nhóm quay về chế độ đóng khi lỗi (thường là `allowlist`) thay vì kế thừa `channels.defaults.groupPolicy`. + - An toàn khi chạy: khi thiếu hoàn toàn khối nhà cung cấp (`channels.` không tồn tại), chính sách nhóm quay về chế độ đóng khi lỗi (thường là `allowlist`) thay vì kế thừa `channels.defaults.groupPolicy`. -Mô hình tư duy nhanh (thứ tự đánh giá cho tin nhắn nhóm): +Mô hình nhanh trong đầu (thứ tự đánh giá cho tin nhắn nhóm): `groupPolicy` (open/disabled/allowlist). - - Danh sách cho phép của nhóm (`*.groups`, `*.groupAllowFrom`, danh sách cho phép theo kênh). + + Danh sách cho phép nhóm (`*.groups`, `*.groupAllowFrom`, danh sách cho phép riêng theo kênh). - - Chặn theo lượt nhắc đến (`requireMention`, `/activation`). + + Kiểm soát bằng lượt nhắc (`requireMention`, `/activation`). -## Chặn theo lượt nhắc đến (mặc định) +## Kiểm soát bằng lượt nhắc (mặc định) -Tin nhắn nhóm yêu cầu một lượt nhắc đến trừ khi được ghi đè theo từng nhóm. Giá trị mặc định nằm theo từng hệ thống con trong `*.groups."*"`. +Tin nhắn nhóm yêu cầu có lượt nhắc trừ khi được ghi đè theo từng nhóm. Giá trị mặc định nằm theo từng hệ thống con dưới `*.groups."*"`. -Trả lời một tin nhắn của bot được tính là một lượt nhắc đến ngầm định khi kênh hỗ trợ siêu dữ liệu trả lời. Trích dẫn một tin nhắn của bot cũng có thể được tính là một lượt nhắc đến ngầm định trên các kênh cung cấp siêu dữ liệu trích dẫn. Các trường hợp tích hợp sẵn hiện tại bao gồm Telegram, WhatsApp, Slack, Discord, Microsoft Teams và ZaloUser. +Trả lời tin nhắn của bot được tính là một lượt nhắc ngầm định khi kênh hỗ trợ siêu dữ liệu trả lời. Trích dẫn tin nhắn của bot cũng có thể được tính là một lượt nhắc ngầm định trên các kênh cung cấp siêu dữ liệu trích dẫn. Các trường hợp tích hợp hiện tại gồm Telegram, WhatsApp, Slack, Discord, Microsoft Teams và ZaloUser. ```json5 { @@ -339,40 +341,40 @@ Trả lời một tin nhắn của bot được tính là một lượt nhắc ``` - - - `mentionPatterns` là các mẫu regex an toàn, không phân biệt chữ hoa chữ thường; các mẫu không hợp lệ và các dạng lặp lồng nhau không an toàn sẽ bị bỏ qua. - - Các bề mặt cung cấp lượt nhắc đến tường minh vẫn được cho qua; các mẫu là phương án dự phòng. + + - `mentionPatterns` là các mẫu regex an toàn, không phân biệt hoa thường; các mẫu không hợp lệ và dạng lặp lồng nhau không an toàn sẽ bị bỏ qua. + - Các bề mặt cung cấp lượt nhắc rõ ràng vẫn được cho qua; mẫu chỉ là cơ chế dự phòng. - Ghi đè theo từng agent: `agents.list[].groupChat.mentionPatterns` (hữu ích khi nhiều agent dùng chung một nhóm). - - Chặn theo lượt nhắc đến chỉ được thực thi khi có thể phát hiện lượt nhắc đến (lượt nhắc đến gốc hoặc `mentionPatterns` đã được cấu hình). - - Đưa một nhóm hoặc người gửi vào danh sách cho phép không tắt chặn theo lượt nhắc đến; đặt `requireMention` của nhóm đó thành `false` khi mọi tin nhắn đều nên kích hoạt. - - Ngữ cảnh lời nhắc cuộc trò chuyện nhóm mang chỉ dẫn trả lời im lặng đã phân giải ở mỗi lượt; các tệp workspace không nên sao chép cơ chế `NO_REPLY`. - - Các nhóm cho phép trả lời im lặng coi các lượt mô hình sạch nhưng trống hoặc chỉ có lập luận là im lặng, tương đương với `NO_REPLY`. Trò chuyện trực tiếp chỉ làm như vậy khi trả lời im lặng trực tiếp được cho phép tường minh; nếu không, câu trả lời trống vẫn là lượt agent thất bại. - - Mặc định của Discord nằm trong `channels.discord.guilds."*"` (có thể ghi đè theo từng guild/channel). - - Ngữ cảnh lịch sử nhóm được bọc thống nhất trên các kênh và là **chỉ đang chờ** (các tin nhắn bị bỏ qua do chặn theo lượt nhắc đến); dùng `messages.groupChat.historyLimit` cho mặc định toàn cục và `channels..historyLimit` (hoặc `channels..accounts.*.historyLimit`) cho các ghi đè. Đặt `0` để tắt. + - Kiểm soát bằng lượt nhắc chỉ được áp dụng khi có thể phát hiện lượt nhắc (lượt nhắc gốc hoặc `mentionPatterns` đã được cấu hình). + - Đưa một nhóm hoặc người gửi vào danh sách cho phép không tắt kiểm soát bằng lượt nhắc; đặt `requireMention` của nhóm đó thành `false` khi tất cả tin nhắn đều nên kích hoạt. + - Ngữ cảnh prompt trò chuyện nhóm mang theo chỉ dẫn trả lời im lặng đã phân giải trong mỗi lượt; các tệp workspace không nên nhân đôi cơ chế `NO_REPLY`. + - Các nhóm cho phép trả lời im lặng sẽ coi lượt mô hình trống sạch hoặc chỉ có reasoning là im lặng, tương đương `NO_REPLY`. Trò chuyện trực tiếp cũng làm như vậy chỉ khi trả lời im lặng trực tiếp được cho phép rõ ràng; nếu không, trả lời trống vẫn là lượt agent thất bại. + - Giá trị mặc định của Discord nằm trong `channels.discord.guilds."*"` (có thể ghi đè theo từng guild/kênh). + - Ngữ cảnh lịch sử nhóm được bọc thống nhất trên các kênh và là **chỉ các mục đang chờ** (tin nhắn bị bỏ qua do kiểm soát bằng lượt nhắc); dùng `messages.groupChat.historyLimit` cho mặc định toàn cục và `channels..historyLimit` (hoặc `channels..accounts.*.historyLimit`) cho các ghi đè. Đặt `0` để tắt. ## Hạn chế công cụ theo nhóm/kênh (tùy chọn) -Một số cấu hình kênh hỗ trợ hạn chế những công cụ nào có sẵn **bên trong một nhóm/phòng/kênh cụ thể**. +Một số cấu hình kênh hỗ trợ giới hạn công cụ nào khả dụng **bên trong một nhóm/phòng/kênh cụ thể**. - `tools`: cho phép/từ chối công cụ cho toàn bộ nhóm. -- `toolsBySender`: ghi đè theo từng người gửi trong nhóm. Dùng các tiền tố khóa tường minh: `id:`, `e164:`, `username:`, `name:`, và ký tự đại diện `"*"`. Các khóa cũ không có tiền tố vẫn được chấp nhận và chỉ được khớp như `id:`. +- `toolsBySender`: ghi đè theo từng người gửi trong nhóm. Dùng tiền tố khóa rõ ràng: `id:`, `e164:`, `username:`, `name:`, và ký tự đại diện `"*"`. Các khóa cũ không có tiền tố vẫn được chấp nhận và chỉ được khớp như `id:`. -Thứ tự phân giải (mục cụ thể nhất thắng): +Thứ tự phân giải (cụ thể nhất thắng): Khớp `toolsBySender` của nhóm/kênh. - + `tools` của nhóm/kênh. Khớp `toolsBySender` mặc định (`"*"`). - + `tools` mặc định (`"*"`). @@ -398,18 +400,18 @@ Ví dụ (Telegram): ``` -Hạn chế công cụ theo nhóm/kênh được áp dụng bổ sung cho chính sách công cụ toàn cục/agent (từ chối vẫn thắng). Một số kênh dùng cấu trúc lồng khác nhau cho phòng/kênh (ví dụ: Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). +Hạn chế công cụ theo nhóm/kênh được áp dụng thêm vào chính sách công cụ toàn cục/agent (từ chối vẫn thắng). Một số kênh dùng cách lồng khác cho phòng/kênh (ví dụ: Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). -## Danh sách cho phép của nhóm +## Danh sách cho phép nhóm -Khi `channels.whatsapp.groups`, `channels.telegram.groups`, hoặc `channels.imessage.groups` được cấu hình, các khóa đóng vai trò là danh sách cho phép của nhóm. Dùng `"*"` để cho phép tất cả nhóm trong khi vẫn đặt hành vi nhắc đến mặc định. +Khi `channels.whatsapp.groups`, `channels.telegram.groups`, hoặc `channels.imessage.groups` được cấu hình, các khóa đóng vai trò là danh sách cho phép nhóm. Dùng `"*"` để cho phép tất cả nhóm trong khi vẫn đặt hành vi nhắc đến mặc định. -Nhầm lẫn phổ biến: phê duyệt ghép cặp DM không giống với ủy quyền nhóm. Đối với các kênh hỗ trợ ghép cặp DM, kho ghép cặp chỉ mở khóa DM. Lệnh nhóm vẫn yêu cầu ủy quyền người gửi nhóm tường minh từ các danh sách cho phép cấu hình như `groupAllowFrom` hoặc phương án dự phòng cấu hình đã được ghi tài liệu cho kênh đó. +Nhầm lẫn phổ biến: phê duyệt ghép nối DM không giống với cấp quyền nhóm. Với các kênh hỗ trợ ghép nối DM, kho ghép nối chỉ mở khóa DM. Lệnh nhóm vẫn yêu cầu cấp quyền người gửi nhóm rõ ràng từ danh sách cho phép cấu hình như `groupAllowFrom` hoặc cơ chế dự phòng cấu hình được ghi trong tài liệu cho kênh đó. -Ý định thường gặp (sao chép/dán): +Ý định phổ biến (sao chép/dán): @@ -419,7 +421,7 @@ Nhầm lẫn phổ biến: phê duyệt ghép cặp DM không giống với ủy } ``` - + ```json5 { channels: { @@ -444,7 +446,7 @@ Nhầm lẫn phổ biến: phê duyệt ghép cặp DM không giống với ủy } ``` - + ```json5 { channels: { @@ -459,7 +461,7 @@ Nhầm lẫn phổ biến: phê duyệt ghép cặp DM không giống với ủy -## Kích hoạt (chỉ chủ sở hữu) +## Kích hoạt (chỉ dành cho chủ sở hữu) Chủ sở hữu nhóm có thể bật/tắt kích hoạt theo từng nhóm: @@ -470,19 +472,19 @@ Chủ sở hữu được xác định bởi `channels.whatsapp.allowFrom` (ho ## Trường ngữ cảnh -Payload đầu vào của nhóm đặt: +Payload đến từ nhóm đặt: - `ChatType=group` - `GroupSubject` (nếu biết) - `GroupMembers` (nếu biết) -- `WasMentioned` (kết quả chặn theo lượt nhắc đến) +- `WasMentioned` (kết quả kiểm soát bằng lượt nhắc) - Chủ đề diễn đàn Telegram cũng bao gồm `MessageThreadId` và `IsForum`. -Ghi chú theo kênh: +Ghi chú riêng theo kênh: -- BlueBubbles có thể tùy chọn làm giàu người tham gia nhóm macOS chưa đặt tên từ cơ sở dữ liệu Contacts cục bộ trước khi điền `GroupMembers`. Tùy chọn này tắt theo mặc định và chỉ chạy sau khi bước chặn nhóm thông thường vượt qua. +- BlueBubbles có thể tùy chọn làm giàu người tham gia nhóm macOS chưa có tên từ cơ sở dữ liệu Danh bạ cục bộ trước khi điền `GroupMembers`. Tính năng này tắt theo mặc định và chỉ chạy sau khi kiểm soát nhóm thông thường đã cho qua. -Lời nhắc hệ thống agent bao gồm phần giới thiệu nhóm ở lượt đầu tiên của một phiên nhóm mới. Nó nhắc mô hình phản hồi như con người, tránh bảng Markdown, giảm thiểu dòng trống và tuân theo khoảng cách trò chuyện thông thường, đồng thời tránh nhập các chuỗi `\n` theo nghĩa đen. Tên nhóm và nhãn người tham gia lấy từ kênh được hiển thị dưới dạng siêu dữ liệu không đáng tin cậy được rào bằng khối mã, không phải chỉ dẫn hệ thống nội dòng. +Prompt hệ thống của agent bao gồm phần giới thiệu nhóm ở lượt đầu tiên của một phiên nhóm mới. Nó nhắc mô hình phản hồi như con người, tránh bảng Markdown, giảm thiểu dòng trống và tuân theo khoảng cách trò chuyện thông thường, đồng thời tránh gõ các chuỗi `\n` nguyên văn. Tên nhóm và nhãn người tham gia có nguồn từ kênh được hiển thị dưới dạng siêu dữ liệu không đáng tin cậy trong khối mã rào, không phải chỉ dẫn hệ thống nội dòng. ## Chi tiết riêng của iMessage @@ -490,17 +492,17 @@ Lời nhắc hệ thống agent bao gồm phần giới thiệu nhóm ở lượ - Liệt kê cuộc trò chuyện: `imsg chats --limit 20`. - Trả lời nhóm luôn quay lại cùng `chat_id`. -## Lời nhắc hệ thống WhatsApp +## Prompt hệ thống WhatsApp -Xem [WhatsApp](/vi/channels/whatsapp#system-prompts) để biết các quy tắc lời nhắc hệ thống WhatsApp chuẩn, bao gồm phân giải lời nhắc nhóm và trực tiếp, hành vi ký tự đại diện, và ngữ nghĩa ghi đè tài khoản. +Xem [WhatsApp](/vi/channels/whatsapp#system-prompts) để biết các quy tắc prompt hệ thống WhatsApp chuẩn, bao gồm phân giải prompt nhóm và trực tiếp, hành vi ký tự đại diện, và ngữ nghĩa ghi đè tài khoản. ## Chi tiết riêng của WhatsApp -Xem [Tin nhắn nhóm](/vi/channels/group-messages) để biết hành vi chỉ dành cho WhatsApp (chèn lịch sử, chi tiết xử lý lượt nhắc đến). +Xem [Tin nhắn nhóm](/vi/channels/group-messages) để biết hành vi chỉ dành cho WhatsApp (chèn lịch sử, chi tiết xử lý lượt nhắc). ## Liên quan - [Nhóm phát sóng](/vi/channels/broadcast-groups) - [Định tuyến kênh](/vi/channels/channel-routing) - [Tin nhắn nhóm](/vi/channels/group-messages) -- [Ghép cặp](/vi/channels/pairing) +- [Ghép nối](/vi/channels/pairing) diff --git a/docs/vi/channels/irc.md b/docs/vi/channels/irc.md index 21913b758..0d1ecaff8 100644 --- a/docs/vi/channels/irc.md +++ b/docs/vi/channels/irc.md @@ -1,25 +1,25 @@ --- read_when: - Bạn muốn kết nối OpenClaw với các kênh IRC hoặc tin nhắn trực tiếp - - Bạn đang cấu hình danh sách cho phép IRC, chính sách nhóm hoặc kiểm soát việc nhắc đến -summary: Thiết lập Plugin IRC, kiểm soát quyền truy cập và khắc phục sự cố + - Bạn đang cấu hình danh sách cho phép IRC, chính sách nhóm hoặc kiểm soát việc đề cập +summary: Thiết lập Plugin IRC, kiểm soát truy cập và khắc phục sự cố title: IRC x-i18n: - generated_at: "2026-04-29T22:25:44Z" + generated_at: "2026-05-04T02:21:31Z" model: gpt-5.5 provider: openai - source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69 + source_hash: 43c3098fe49a5e7405443df73e1bf752a579460dc0b2070c3d07f43b512bb555 source_path: channels/irc.md workflow: 16 --- -Dùng IRC khi bạn muốn OpenClaw trong các kênh cổ điển (`#room`) và tin nhắn trực tiếp. -IRC được cung cấp dưới dạng Plugin đóng gói kèm, nhưng được cấu hình trong cấu hình chính tại `channels.irc`. +Sử dụng IRC khi bạn muốn dùng OpenClaw trong các kênh cổ điển (`#room`) và tin nhắn trực tiếp. +IRC được phát hành dưới dạng Plugin đi kèm, nhưng được cấu hình trong cấu hình chính dưới `channels.irc`. ## Bắt đầu nhanh 1. Bật cấu hình IRC trong `~/.openclaw/openclaw.json`. -2. Thiết lập ít nhất: +2. Đặt ít nhất: ```json5 { @@ -36,9 +36,9 @@ IRC được cung cấp dưới dạng Plugin đóng gói kèm, nhưng được } ``` -Nên dùng máy chủ IRC riêng để phối hợp bot. Nếu bạn chủ ý dùng mạng IRC công khai, các lựa chọn phổ biến gồm Libera.Chat, OFTC và Snoonet. Tránh các kênh công khai dễ đoán cho lưu lượng kênh hậu trường của bot hoặc swarm. +Nên dùng máy chủ IRC riêng cho việc điều phối bot. Nếu bạn chủ ý dùng một mạng IRC công khai, các lựa chọn phổ biến gồm Libera.Chat, OFTC và Snoonet. Tránh các kênh công khai dễ đoán cho lưu lượng backchannel của bot hoặc swarm. -3. Khởi động/khởi động lại gateway: +3. Khởi động/bắt đầu lại gateway: ```bash openclaw gateway run @@ -46,9 +46,10 @@ openclaw gateway run ## Mặc định bảo mật +- IRC sử dụng socket TCP/TLS thô bên ngoài định tuyến proxy chuyển tiếp do người vận hành OpenClaw quản lý. Trong các triển khai yêu cầu toàn bộ lưu lượng đi ra phải đi qua proxy chuyển tiếp đó, hãy đặt `channels.irc.enabled=false` trừ khi lưu lượng IRC đi ra trực tiếp được phê duyệt rõ ràng. - `channels.irc.dmPolicy` mặc định là `"pairing"`. - `channels.irc.groupPolicy` mặc định là `"allowlist"`. -- Với `groupPolicy="allowlist"`, hãy đặt `channels.irc.groups` để định nghĩa các kênh được phép. +- Với `groupPolicy="allowlist"`, đặt `channels.irc.groups` để định nghĩa các kênh được phép. - Dùng TLS (`channels.irc.tls=true`) trừ khi bạn chủ ý chấp nhận truyền tải văn bản thuần. ## Kiểm soát truy cập @@ -58,23 +59,23 @@ Có hai “cổng” riêng cho các kênh IRC: 1. **Truy cập kênh** (`groupPolicy` + `groups`): bot có chấp nhận tin nhắn từ một kênh hay không. 2. **Truy cập người gửi** (`groupAllowFrom` / `groups["#channel"].allowFrom` theo từng kênh): ai được phép kích hoạt bot bên trong kênh đó. -Khóa cấu hình: +Các khóa cấu hình: -- Danh sách cho phép DM (truy cập người gửi DM): `channels.irc.allowFrom` -- Danh sách cho phép người gửi nhóm (truy cập người gửi trong kênh): `channels.irc.groupAllowFrom` -- Điều khiển theo từng kênh (quy tắc kênh + người gửi + nhắc đến): `channels.irc.groups["#channel"]` -- `channels.irc.groupPolicy="open"` cho phép các kênh chưa cấu hình (**theo mặc định vẫn bị chặn bởi yêu cầu nhắc đến**) +- Danh sách cho phép DM (quyền truy cập của người gửi DM): `channels.irc.allowFrom` +- Danh sách cho phép người gửi trong nhóm (quyền truy cập của người gửi trong kênh): `channels.irc.groupAllowFrom` +- Điều khiển theo từng kênh (quy tắc kênh + người gửi + đề cập): `channels.irc.groups["#channel"]` +- `channels.irc.groupPolicy="open"` cho phép các kênh chưa được cấu hình (**mặc định vẫn bị kiểm soát bằng đề cập**) -Các mục danh sách cho phép nên dùng danh tính người gửi ổn định (`nick!user@host`). +Các mục trong danh sách cho phép nên dùng danh tính người gửi ổn định (`nick!user@host`). Khớp nick trần có thể thay đổi và chỉ được bật khi `channels.irc.dangerouslyAllowNameMatching: true`. ### Lỗi thường gặp: `allowFrom` dành cho DM, không phải kênh -Nếu bạn thấy log như: +Nếu bạn thấy nhật ký như: - `irc: drop group sender alice!ident@host (policy=allowlist)` -…điều đó nghĩa là người gửi chưa được phép cho tin nhắn **nhóm/kênh**. Sửa bằng một trong hai cách: +…điều đó nghĩa là người gửi không được phép đối với tin nhắn **nhóm/kênh**. Khắc phục bằng cách: - đặt `channels.irc.groupAllowFrom` (toàn cục cho mọi kênh), hoặc - đặt danh sách cho phép người gửi theo từng kênh: `channels.irc.groups["#channel"].allowFrom` @@ -94,13 +95,13 @@ Ví dụ (cho phép bất kỳ ai trong `#tuirc-dev` nói chuyện với bot): } ``` -## Kích hoạt trả lời (nhắc đến) +## Kích hoạt trả lời (đề cập) -Ngay cả khi một kênh được phép (qua `groupPolicy` + `groups`) và người gửi được phép, OpenClaw mặc định dùng **cổng nhắc đến** trong ngữ cảnh nhóm. +Ngay cả khi một kênh được phép (qua `groupPolicy` + `groups`) và người gửi được phép, OpenClaw mặc định **kiểm soát bằng đề cập** trong ngữ cảnh nhóm. -Điều đó nghĩa là bạn có thể thấy log như `drop channel … (missing-mention)` trừ khi tin nhắn có mẫu nhắc đến khớp với bot. +Điều đó nghĩa là bạn có thể thấy nhật ký như `drop channel … (missing-mention)` trừ khi tin nhắn có mẫu đề cập khớp với bot. -Để bot trả lời trong một kênh IRC **mà không cần nhắc đến**, hãy tắt cổng nhắc đến cho kênh đó: +Để bot trả lời trong một kênh IRC **mà không cần đề cập**, hãy tắt kiểm soát bằng đề cập cho kênh đó: ```json5 { @@ -118,7 +119,7 @@ Ngay cả khi một kênh được phép (qua `groupPolicy` + `groups`) và ngư } ``` -Hoặc để cho phép **tất cả** kênh IRC (không có danh sách cho phép theo từng kênh) và vẫn trả lời không cần nhắc đến: +Hoặc để cho phép **tất cả** các kênh IRC (không có danh sách cho phép theo từng kênh) và vẫn trả lời không cần đề cập: ```json5 { @@ -135,10 +136,10 @@ Hoặc để cho phép **tất cả** kênh IRC (không có danh sách cho phép ## Ghi chú bảo mật (khuyến nghị cho kênh công khai) -Nếu bạn cho phép `allowFrom: ["*"]` trong một kênh công khai, bất kỳ ai cũng có thể nhắc lệnh bot. +Nếu bạn cho phép `allowFrom: ["*"]` trong một kênh công khai, bất kỳ ai cũng có thể prompt bot. Để giảm rủi ro, hãy hạn chế công cụ cho kênh đó. -### Cùng công cụ cho mọi người trong kênh +### Cùng bộ công cụ cho mọi người trong kênh ```json5 { @@ -159,7 +160,7 @@ Nếu bạn cho phép `allowFrom: ["*"]` trong một kênh công khai, bất k ### Công cụ khác nhau theo từng người gửi (chủ sở hữu có nhiều quyền hơn) -Dùng `toolsBySender` để áp dụng chính sách chặt hơn cho `"*"` và chính sách lỏng hơn cho nick của bạn: +Dùng `toolsBySender` để áp dụng chính sách chặt hơn cho `"*"` và chính sách thoáng hơn cho nick của bạn: ```json5 { @@ -188,9 +189,9 @@ Ghi chú: - Các khóa `toolsBySender` nên dùng `id:` cho giá trị danh tính người gửi IRC: `id:eigen` hoặc `id:eigen!~eigen@174.127.248.171` để khớp chặt hơn. - Các khóa cũ không có tiền tố vẫn được chấp nhận và chỉ được khớp như `id:`. -- Chính sách người gửi đầu tiên khớp sẽ thắng; `"*"` là phương án dự phòng ký tự đại diện. +- Chính sách người gửi khớp đầu tiên sẽ thắng; `"*"` là dự phòng ký tự đại diện. -Để biết thêm về truy cập nhóm so với cổng nhắc đến (và cách chúng tương tác), xem: [/channels/groups](/vi/channels/groups). +Để biết thêm về truy cập nhóm so với kiểm soát bằng đề cập (và cách chúng tương tác), xem: [/channels/groups](/vi/channels/groups). ## NickServ @@ -225,7 +226,7 @@ Ghi chú: } ``` -Tắt `register` sau khi nick đã được đăng ký để tránh các lần thử REGISTER lặp lại. +Tắt `register` sau khi nick đã được đăng ký để tránh lặp lại các lần thử REGISTER. ## Biến môi trường @@ -242,18 +243,18 @@ Tài khoản mặc định hỗ trợ: - `IRC_NICKSERV_PASSWORD` - `IRC_NICKSERV_REGISTER_EMAIL` -Không thể đặt `IRC_HOST` từ `.env` của workspace; xem [tệp `.env` của workspace](/vi/gateway/security). +Không thể đặt `IRC_HOST` từ `.env` của workspace; xem [Tệp `.env` của workspace](/vi/gateway/security). ## Khắc phục sự cố -- Nếu bot kết nối nhưng không bao giờ trả lời trong kênh, hãy xác minh `channels.irc.groups` **và** liệu cổng nhắc đến có đang loại bỏ tin nhắn (`missing-mention`) hay không. Nếu bạn muốn bot trả lời mà không cần ping, hãy đặt `requireMention:false` cho kênh. +- Nếu bot kết nối nhưng không bao giờ trả lời trong kênh, hãy xác minh `channels.irc.groups` **và** liệu kiểm soát bằng đề cập có đang loại bỏ tin nhắn hay không (`missing-mention`). Nếu bạn muốn bot trả lời không cần ping, đặt `requireMention:false` cho kênh. - Nếu đăng nhập thất bại, hãy xác minh nick còn khả dụng và mật khẩu máy chủ. - Nếu TLS thất bại trên mạng tùy chỉnh, hãy xác minh host/port và thiết lập chứng chỉ. ## Liên quan -- [Tổng quan kênh](/vi/channels) — tất cả kênh được hỗ trợ -- [Ghép đôi](/vi/channels/pairing) — xác thực DM và luồng ghép đôi -- [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và cổng nhắc đến +- [Tổng quan về kênh](/vi/channels) — tất cả kênh được hỗ trợ +- [Ghép nối](/vi/channels/pairing) — xác thực DM và luồng ghép nối +- [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và kiểm soát bằng đề cập - [Định tuyến kênh](/vi/channels/channel-routing) — định tuyến phiên cho tin nhắn -- [Bảo mật](/vi/gateway/security) — mô hình truy cập và gia cố +- [Bảo mật](/vi/gateway/security) — mô hình truy cập và tăng cường bảo mật diff --git a/docs/vi/channels/pairing.md b/docs/vi/channels/pairing.md index 7fd7a1117..52865ff27 100644 --- a/docs/vi/channels/pairing.md +++ b/docs/vi/channels/pairing.md @@ -1,41 +1,41 @@ --- read_when: - - Thiết lập kiểm soát quyền truy cập DM + - 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á tình trạng bảo mật của OpenClaw -summary: 'Tổng quan ghép nố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á 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' title: Ghép nối x-i18n: - generated_at: "2026-05-02T10:34:35Z" + generated_at: "2026-05-04T02:21:42Z" model: gpt-5.5 provider: openai - source_hash: bb68d87c0e1dfe7c9a6a6d9415f4c63625755fb43a2e22a1d1374ff0a63e49c4 + source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874 source_path: channels/pairing.md workflow: 16 --- -“Ghép nối” là bước phê duyệt quyền truy cập rõ ràng của OpenClaw. +“Ghép đôi” là bước phê duyệt quyền truy cập tường minh của OpenClaw. Nó được dùng ở hai nơi: -1. **Ghép nối DM** (ai được phép trò chuyện với bot) -2. **Ghép nối Node** (thiết bị/nút nào được phép tham gia mạng Gateway) +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) Ngữ cảnh bảo mật: [Bảo mật](/vi/gateway/security) -## 1) Ghép nối DM (quyền truy cập trò chuyện đến) +## 1) Ghép đôi tin nhắn trực tiếp (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 được 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 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. -Các chính sách DM mặc định được ghi trong tài liệu tại: [Bảo mật](/vi/gateway/security) +Các chính sách DM mặc định được ghi lại trong: [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ể, runtime vẫn chỉ cho phép những người gửi đó, và các phê duyệt trong kho ghép nối không mở rộng quyền truy cập `open`. +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`. -Mã ghép nối: +Mã ghép đôi: - 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 nối 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 nố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 sẽ 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 đô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. ### Phê duyệt người gửi @@ -44,17 +44,17 @@ 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 nối 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 exec. Sau khi đã có chủ sở hữu, các phê duyệt ghép nối sau đó chỉ cấp quyền truy cập DM; chúng không thêm chủ sở hữu nữa. +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. -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`. +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 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. -Các nhóm tĩnh dùng `type: "message.senders"` và được tham chiếu bằng +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 @@ -76,9 +76,9 @@ Các nhóm tĩnh dùng `type: "message.senders"` và được tham chiếu bằn } ``` -Nhóm truy cập được ghi tài liệu chi tiết tại đây: [Nhóm truy cập](/vi/channels/access-groups) +Nhóm truy cập được ghi lại chi tiết tại đây: [Nhóm truy cập](/vi/channels/access-groups) -### Trạng thái nằm ở đâu +### Trạng thái được lưu ở đâu Được lưu dưới `~/.openclaw/credentials/`: @@ -87,7 +87,7 @@ Nhóm truy cập được ghi tài liệu chi tiết tại đây: [Nhóm truy c - 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 theo tài khoản: +Hành vi phạm vi 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. @@ -95,46 +95,40 @@ Hành vi phạm vi theo tài khoản: 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 nối dành cho quyền truy cập DM. Ủy quyền nhóm là riêng biệt. -Phê duyệt mã ghép nố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 đô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). -## 2) Ghép nối thiết bị Node (Node iOS/Android/macOS/headless) +## 2) Ghép đôi thiết bị Node (Node iOS/Android/macOS/headless) -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 nối thiết bị cần được phê duyệt. +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. -### Ghép nối qua Telegram (khuyến nghị cho iOS) +### Ghép đôi 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 nố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ể thực hiện ghép đôi thiết bị lần đầu hoàn toàn từ Telegram: -1. Trong Telegram, nhắn cho bot của bạn: `/pair` +1. Trong Telegram, nhắn tin 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 của bạn, mở ứng dụng OpenClaw iOS → Settings → Gateway. +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. 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: - `url`: URL WebSocket của Gateway (`ws://...` hoặc `wss://...`) -- `bootstrapToken`: token bootstrap ngắn hạn cho một thiết bị, dùng cho bắt tay ghép nối ban đầu +- `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 -Token bootstrap đó mang hồ sơ bootstrap ghép nối tích hợp sẵn: +Token khởi tạo đó mang hồ sơ khởi tạo ghép đôi tích hợp sẵn: -- token `node` được bàn giao chính vẫn giữ `scopes: []` -- mọi token `operator` được bàn giao vẫn bị giới hạn trong danh sách cho phép bootstrap: +- 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: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` -- kiểm tra phạm vi bootstrap được thêm 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ỉ đáp ứng 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ò của riêng 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 +- 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 -Hãy xử lý mã thiết lập như mật khẩu trong thời gian nó còn hiệu lực. +Hãy xử lý mã thiết lập như mật khẩu khi nó còn hiệu lực. ### Phê duyệt thiết bị Node @@ -144,16 +138,18 @@ openclaw devices approve openclaw devices reject ``` -Nếu cùng một 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 sẽ được tạo. +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. + +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. -Một thiết bị đã ghép nối không âm thầm nhận quyền truy cập rộng hơn. Nếu thiết bị 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. +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. -### Tùy chọn tự động phê duyệt Node theo CIDR đáng tin cậy +### Tự động phê duyệt Node theo CIDR tin cậy tùy chọn -Ghép nố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 tự động phê duyệt Node lần đầu bằng CIDR rõ ràng hoặc IP chính xác: +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: ```json5 { @@ -167,24 +163,19 @@ bạn có thể chọn tự động phê duyệt Node lần đầu bằng CIDR r } ``` -Điều này chỉ áp dụng cho các yêu cầu ghép nối `role: node` mới không có phạm vi được yêu cầu. -Các client operator, trình duyệt, Control UI và WebChat vẫn yêu cầu phê duyệt thủ công. -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 đô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. -### Lưu trữ trạng thái ghép nối Node +### Lưu trữ trạng thái ghép đôi 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 nối + token) +- `paired.json` (thiết bị đã ghép đôi + token) ### Ghi chú -- API `node.pair.*` cũ (CLI: `openclaw nodes pending|approve|reject|remove|rename`) là một - kho ghép nối riêng do gateway sở hữu. Các Node WS vẫn yêu cầu ghép nối thiết bị. -- Bản ghi ghép nối là nguồn sự thật bền vững cho các vai trò đã phê duyệt. Các - token thiết bị đang hoạt động vẫn bị giới hạn trong tập vai trò đã được 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 đô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. ## Tài liệu liên quan diff --git a/docs/vi/channels/qqbot.md b/docs/vi/channels/qqbot.md index fe812cb14..d1e2e92e9 100644 --- a/docs/vi/channels/qqbot.md +++ b/docs/vi/channels/qqbot.md @@ -1,26 +1,26 @@ --- read_when: - Bạn muốn kết nối OpenClaw với QQ - - Bạn cần thiết lập thông tin xác thực QQ Bot - - Bạn muốn hỗ trợ trò chuyện nhóm hoặc trò chuyện riêng tư với QQ Bot + - Bạn cần thiết lập thông tin xác thực cho QQ Bot + - Bạn muốn hỗ trợ trò chuyện nhóm hoặc trò chuyện riêng tư qua QQ Bot summary: Thiết lập, cấu hình và sử dụng QQ Bot -title: bot QQ +title: Bot QQ x-i18n: - generated_at: "2026-05-03T21:27:28Z" + generated_at: "2026-05-04T02:21:37Z" model: gpt-5.5 provider: openai - source_hash: 471c24110bf0ab8896d22f5bb5932ac4e03ff5169560c99ba6b9d1ca4025d9a8 + source_hash: e17fa0da2f6939ed28cac5f13b3e37e6c63b87a10250ff213f7a86685a6141d6 source_path: channels/qqbot.md workflow: 16 --- -QQ Bot kết nối với OpenClaw qua QQ Bot API chính thức (WebSocket gateway). Plugin hỗ trợ trò chuyện riêng C2C, @tin nhắn trong nhóm và tin nhắn kênh guild với đa phương tiện phong phú (hình ảnh, giọng nói, video, tệp). +QQ Bot kết nối với OpenClaw qua QQ Bot API chính thức (WebSocket gateway). Plugin này hỗ trợ trò chuyện riêng C2C, @tin nhắn trong nhóm và tin nhắn kênh guild với đa phương tiện phong phú (hình ảnh, giọng nói, video, tệp). -Trạng thái: Plugin có thể tải xuống. Tin nhắn trực tiếp, trò chuyện nhóm, kênh guild và phương tiện được hỗ trợ. Phản ứng và luồng không được hỗ trợ. +Trạng thái: plugin có thể tải xuống. Tin nhắn trực tiếp, trò chuyện nhóm, kênh guild và đa phương tiện đều được hỗ trợ. Phản ứng và luồng không được hỗ trợ. ## Cài đặt -Cài đặt QQ Bot trước khi thiết lập: +Cài QQ Bot trước khi thiết lập: ```bash openclaw plugins install @openclaw/qqbot @@ -29,10 +29,10 @@ openclaw plugins install @openclaw/qqbot ## Thiết lập 1. Truy cập [QQ Open Platform](https://q.qq.com/) và quét mã QR bằng QQ trên điện thoại của bạn để đăng ký / đăng nhập. -2. Nhấp **Create Bot** để tạo một QQ bot mới. +2. Bấm **Create Bot** để tạo một QQ bot mới. 3. Tìm **AppID** và **AppSecret** trên trang cài đặt của bot rồi sao chép chúng. -> AppSecret không được lưu ở dạng văn bản thuần túy — nếu bạn rời trang mà không lưu, +> AppSecret không được lưu dưới dạng văn bản thuần — nếu bạn rời khỏi trang mà không lưu, > bạn sẽ phải tạo lại một khóa mới. 4. Thêm kênh: @@ -85,7 +85,7 @@ AppSecret dựa trên tệp: } ``` -AppSecret Env SecretRef: +AppSecret SecretRef từ môi trường: ```json5 { @@ -101,10 +101,10 @@ AppSecret Env SecretRef: Ghi chú: -- Dự phòng env chỉ áp dụng cho tài khoản QQ Bot mặc định. +- Dự phòng từ môi trường chỉ áp dụng cho tài khoản QQ Bot mặc định. - `openclaw channels add --channel qqbot --token-file ...` chỉ cung cấp AppSecret; AppID phải đã được đặt trong cấu hình hoặc `QQBOT_APP_ID`. -- `clientSecret` cũng chấp nhận đầu vào SecretRef, không chỉ chuỗi văn bản thuần túy. -- Chuỗi đánh dấu `secretref:/...` kế thừa không phải là giá trị `clientSecret` hợp lệ; hãy dùng các đối tượng SecretRef có cấu trúc như ví dụ ở trên. +- `clientSecret` cũng chấp nhận đầu vào SecretRef, không chỉ chuỗi văn bản thuần. +- Các chuỗi đánh dấu `secretref:/...` cũ không phải là giá trị `clientSecret` hợp lệ; hãy dùng các đối tượng SecretRef có cấu trúc như ví dụ ở trên. ### Thiết lập nhiều tài khoản @@ -166,27 +166,27 @@ Hỗ trợ trò chuyện nhóm của QQ Bot dùng OpenID nhóm QQ, không dùng } ``` -`groups["*"]` đặt mặc định cho mọi nhóm, và một mục `groups.GROUP_OPENID` cụ thể sẽ ghi đè các mặc định đó cho một nhóm. Cài đặt nhóm bao gồm: +`groups["*"]` đặt mặc định cho mọi nhóm, còn mục `groups.GROUP_OPENID` cụ thể sẽ ghi đè các mặc định đó cho một nhóm. Cài đặt nhóm bao gồm: - `requireMention`: yêu cầu @mention trước khi bot trả lời. Mặc định: `true`. - `ignoreOtherMentions`: bỏ các tin nhắn nhắc đến người khác nhưng không nhắc đến bot. -- `historyLimit`: giữ các tin nhắn nhóm gần đây không nhắc đến bot làm ngữ cảnh cho lượt tiếp theo có nhắc đến. Đặt `0` để tắt. -- `toolPolicy`: `full`, `restricted`, hoặc `none` cho công cụ theo phạm vi nhóm. +- `historyLimit`: giữ các tin nhắn nhóm gần đây không phải lượt nhắc đến làm ngữ cảnh cho lượt được nhắc đến tiếp theo. Đặt `0` để tắt. +- `toolPolicy`: `full`, `restricted` hoặc `none` cho các công cụ theo phạm vi nhóm. - `name`: nhãn thân thiện được dùng trong nhật ký và ngữ cảnh nhóm. -- `prompt`: lời nhắc hành vi theo từng nhóm được nối vào ngữ cảnh tác tử. +- `prompt`: prompt hành vi theo từng nhóm được thêm vào ngữ cảnh agent. -Các chế độ kích hoạt là `mention` và `always`. `requireMention: true` ánh xạ tới `mention`; `requireMention: false` ánh xạ tới `always`. Ghi đè kích hoạt cấp phiên, nếu có, sẽ thắng cấu hình. +Các chế độ kích hoạt là `mention` và `always`. `requireMention: true` ánh xạ tới `mention`; `requireMention: false` ánh xạ tới `always`. Ghi đè kích hoạt ở cấp phiên, khi có, sẽ thắng cấu hình. -Hàng đợi đầu vào là theo từng đối tượng ngang hàng. Đối tượng ngang hàng nhóm có giới hạn hàng đợi lớn hơn, ưu tiên tin nhắn của con người trước nội dung trò chuyện do bot viết khi đầy, và gộp các đợt tin nhắn nhóm bình thường thành một lượt có ghi nhận nguồn. Lệnh slash vẫn chạy lần lượt từng lệnh. +Hàng đợi đầu vào được tách theo từng peer. Peer nhóm có giới hạn hàng đợi lớn hơn, giữ tin nhắn của người dùng trước các trao đổi do bot viết khi đầy, và hợp nhất các đợt tin nhắn nhóm thông thường thành một lượt có gán nguồn. Lệnh slash vẫn chạy lần lượt từng lệnh. ### Giọng nói (STT / TTS) -Hỗ trợ STT và TTS dùng cấu hình hai cấp với dự phòng theo mức ưu tiên: +Hỗ trợ STT và TTS dùng cấu hình hai cấp với dự phòng theo thứ tự ưu tiên: -| Cài đặt | Riêng cho Plugin | Dự phòng framework | -| ------- | -------------------------------------------------------- | ---------------------------- | +| Cài đặt | Riêng cho Plugin | Dự phòng framework | +| ------- | -------------------------------------------------------- | ----------------------------- | | STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | -| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | +| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | ```json5 { @@ -202,7 +202,7 @@ Hỗ trợ STT và TTS dùng cấu hình hai cấp với dự phòng theo mức voice: "your-voice", }, accounts: { - qq-main: { + "qq-main": { tts: { providers: { openai: { voice: "shimmer" }, @@ -216,9 +216,9 @@ Hỗ trợ STT và TTS dùng cấu hình hai cấp với dự phòng theo mức ``` Đặt `enabled: false` trên một trong hai để tắt. -Ghi đè TTS cấp tài khoản dùng cùng cấu trúc với `messages.tts` và được deep-merge lên trên cấu hình TTS cấp kênh/toàn cục. +Các ghi đè TTS ở cấp tài khoản dùng cùng cấu trúc với `messages.tts` và được deep-merge lên trên cấu hình TTS của kênh/toàn cục. -Tệp đính kèm giọng nói QQ đầu vào được hiển thị cho tác tử dưới dạng siêu dữ liệu phương tiện âm thanh, đồng thời giữ các tệp giọng nói thô ngoài `MediaPaths` chung. Phản hồi văn bản thuần túy `[[audio_as_voice]]` sẽ tổng hợp TTS và gửi tin nhắn giọng nói QQ gốc khi TTS được cấu hình. +Tệp đính kèm giọng nói đầu vào của QQ được cung cấp cho agent dưới dạng siêu dữ liệu đa phương tiện âm thanh, đồng thời giữ các tệp giọng nói thô ngoài `MediaPaths` chung. Phản hồi văn bản thuần `[[audio_as_voice]]` sẽ tổng hợp TTS và gửi tin nhắn giọng nói QQ gốc khi TTS được cấu hình. Hành vi tải lên/chuyển mã âm thanh đầu ra cũng có thể được tinh chỉnh bằng `channels.qqbot.audioFormatPolicy`: @@ -228,11 +228,11 @@ Hành vi tải lên/chuyển mã âm thanh đầu ra cũng có thể được ti ## Định dạng đích -| Định dạng | Mô tả | -| -------------------------- | ----------------------- | -| `qqbot:c2c:OPENID` | Trò chuyện riêng (C2C) | -| `qqbot:group:GROUP_OPENID` | Trò chuyện nhóm | -| `qqbot:channel:CHANNEL_ID` | Kênh guild | +| Định dạng | Mô tả | +| -------------------------- | ---------------------- | +| `qqbot:c2c:OPENID` | Trò chuyện riêng (C2C) | +| `qqbot:group:GROUP_OPENID` | Trò chuyện nhóm | +| `qqbot:channel:CHANNEL_ID` | Kênh guild | > Mỗi bot có tập OpenID người dùng riêng. OpenID nhận được bởi Bot A **không thể** > được dùng để gửi tin nhắn qua Bot B. @@ -244,45 +244,45 @@ Các lệnh tích hợp được chặn trước hàng đợi AI: | Lệnh | Mô tả | | -------------- | -------------------------------------------------------------------------------------------------------- | | `/bot-ping` | Kiểm tra độ trễ | -| `/bot-version` | Hiển thị phiên bản framework OpenClaw | +| `/bot-version` | Hiển thị phiên bản framework OpenClaw | | `/bot-help` | Liệt kê tất cả lệnh | | `/bot-me` | Hiển thị ID người dùng QQ của người gửi (openid) để thiết lập `allowFrom`/`groupAllowFrom` | | `/bot-upgrade` | Hiển thị liên kết hướng dẫn nâng cấp QQBot | -| `/bot-logs` | Xuất nhật ký gateway gần đây thành một tệp | +| `/bot-logs` | Xuất nhật ký gateway gần đây thành tệp | | `/bot-approve` | Phê duyệt một hành động QQ Bot đang chờ xử lý (ví dụ: xác nhận tải lên C2C hoặc nhóm) qua luồng gốc. | Thêm `?` vào bất kỳ lệnh nào để xem trợ giúp sử dụng (ví dụ `/bot-upgrade ?`). -Lệnh quản trị (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) chỉ dùng trong tin nhắn trực tiếp và yêu cầu openid của người gửi nằm trong danh sách `allowFrom` không phải ký tự đại diện rõ ràng. Ký tự đại diện `allowFrom: ["*"]` cho phép trò chuyện nhưng không cấp quyền truy cập lệnh quản trị. Tin nhắn nhóm được so khớp với `groupAllowFrom` trước rồi dự phòng về `allowFrom`. Chạy lệnh quản trị trong nhóm sẽ trả về gợi ý thay vì bị bỏ qua im lặng. +Các lệnh quản trị (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) chỉ dùng trong tin nhắn trực tiếp và yêu cầu openid của người gửi nằm trong danh sách `allowFrom` rõ ràng không dùng ký tự đại diện. Ký tự đại diện `allowFrom: ["*"]` cho phép trò chuyện nhưng không cấp quyền truy cập lệnh quản trị. Tin nhắn nhóm được so khớp với `groupAllowFrom` trước rồi dự phòng về `allowFrom`. Chạy lệnh quản trị trong nhóm sẽ trả về gợi ý thay vì âm thầm bỏ qua. ## Kiến trúc engine -QQ Bot được phát hành dưới dạng engine độc lập bên trong Plugin: +QQ Bot được cung cấp dưới dạng engine độc lập bên trong plugin: -- Mỗi tài khoản sở hữu một ngăn xếp tài nguyên cô lập (kết nối WebSocket, API client, bộ nhớ đệm token, gốc lưu trữ phương tiện) được định danh bằng `appId`. Các tài khoản không bao giờ chia sẻ trạng thái đầu vào/đầu ra. -- Bộ ghi nhật ký nhiều tài khoản gắn thẻ các dòng nhật ký bằng tài khoản sở hữu để chẩn đoán vẫn tách biệt khi bạn chạy nhiều bot dưới một Gateway. -- Các đường dẫn đầu vào, đầu ra và cầu nối gateway dùng chung một gốc tải phương tiện dưới `~/.openclaw/media`, vì vậy nội dung tải lên, tải xuống và bộ nhớ đệm chuyển mã nằm trong một thư mục được bảo vệ thay vì cây theo từng hệ con. -- Việc gửi đa phương tiện phong phú đi qua một đường dẫn `sendMedia` cho mục tiêu C2C và nhóm. Tệp cục bộ và bộ đệm vượt ngưỡng tệp lớn dùng các endpoint tải lên theo mảnh của QQ, còn tải nhỏ hơn dùng API phương tiện một lần. +- Mỗi tài khoản sở hữu một ngăn xếp tài nguyên cô lập (kết nối WebSocket, API client, bộ nhớ đệm token, gốc lưu trữ đa phương tiện) được định danh bằng `appId`. Các tài khoản không bao giờ chia sẻ trạng thái đầu vào/đầu ra. +- Logger nhiều tài khoản gắn thẻ các dòng nhật ký với tài khoản sở hữu để chẩn đoán vẫn tách biệt khi bạn chạy nhiều bot dưới một gateway. +- Các đường dẫn đầu vào, đầu ra và cầu nối Gateway dùng chung một gốc payload đa phương tiện dưới `~/.openclaw/media`, vì vậy tải lên, tải xuống và bộ nhớ đệm chuyển mã nằm dưới một thư mục được bảo vệ thay vì cây riêng cho từng hệ con. +- Việc gửi đa phương tiện phong phú đi qua một đường dẫn `sendMedia` duy nhất cho đích C2C và nhóm. Tệp cục bộ và bộ đệm vượt ngưỡng tệp lớn dùng các endpoint tải lên theo từng đoạn của QQ, còn payload nhỏ hơn dùng media API một lần. - Thông tin xác thực có thể được sao lưu và khôi phục như một phần của snapshot thông tin xác thực OpenClaw tiêu chuẩn; engine gắn lại ngăn xếp tài nguyên của từng tài khoản khi khôi phục mà không yêu cầu ghép cặp mã QR mới. ## Onboarding bằng mã QR -Thay cho việc dán `AppID:AppSecret` thủ công, engine hỗ trợ luồng onboarding bằng mã QR để liên kết QQ Bot với OpenClaw: +Thay cho việc dán thủ công `AppID:AppSecret`, engine hỗ trợ luồng onboarding bằng mã QR để liên kết QQ Bot với OpenClaw: 1. Chạy đường dẫn thiết lập QQ Bot (ví dụ `openclaw channels add --channel qqbot`) và chọn luồng mã QR khi được nhắc. -2. Quét mã QR được tạo bằng ứng dụng điện thoại gắn với QQ Bot mục tiêu. -3. Phê duyệt ghép cặp trên điện thoại. OpenClaw lưu thông tin xác thực trả về vào `credentials/` trong phạm vi tài khoản phù hợp. +2. Quét mã QR được tạo bằng ứng dụng điện thoại được liên kết với QQ Bot đích. +3. Phê duyệt ghép cặp trên điện thoại. OpenClaw lưu thông tin xác thực trả về vào `credentials/` dưới phạm vi tài khoản phù hợp. -Lời nhắc phê duyệt do chính bot tạo ra (ví dụ: các luồng "cho phép hành động này?" được QQ Bot API hiển thị) xuất hiện dưới dạng lời nhắc OpenClaw gốc mà bạn có thể chấp nhận bằng `/bot-approve` thay vì trả lời qua QQ client thô. +Các prompt phê duyệt do chính bot tạo ra (ví dụ các luồng "allow this action?" do QQ Bot API cung cấp) xuất hiện dưới dạng prompt OpenClaw gốc mà bạn có thể chấp nhận bằng `/bot-approve` thay vì trả lời qua client QQ thô. ## Khắc phục sự cố -- **Bot trả lời "gone to Mars":** thông tin xác thực chưa được cấu hình hoặc Gateway chưa được khởi động. -- **Không có tin nhắn đầu vào:** xác minh `appId` và `clientSecret` là chính xác, và bot đã được bật trên QQ Open Platform. -- **Tự trả lời lặp lại:** OpenClaw ghi lại chỉ mục tham chiếu đầu ra QQ là do bot viết và bỏ qua các sự kiện đầu vào có `msgIdx` hiện tại khớp với cùng tài khoản bot đó. Điều này ngăn vòng lặp echo của nền tảng trong khi vẫn cho phép người dùng trích dẫn hoặc trả lời các tin nhắn bot trước đó. -- **Thiết lập với `--token-file` vẫn hiển thị chưa cấu hình:** `--token-file` chỉ đặt AppSecret. Bạn vẫn cần `appId` trong cấu hình hoặc `QQBOT_APP_ID`. -- **Tin nhắn chủ động không đến:** QQ có thể chặn tin nhắn do bot khởi tạo nếu người dùng chưa tương tác gần đây. -- **Giọng nói không được phiên âm:** đảm bảo STT được cấu hình và nhà cung cấp có thể truy cập được. +- **Bot trả lời "gone to Mars":** thông tin xác thực chưa được cấu hình hoặc Gateway chưa khởi động. +- **Không có tin nhắn đầu vào:** xác minh `appId` và `clientSecret` là chính xác, đồng thời bot đã được bật trên QQ Open Platform. +- **Tự trả lời lặp lại:** OpenClaw ghi lại chỉ mục ref đầu ra của QQ dưới dạng do bot viết và bỏ qua các sự kiện đầu vào có `msgIdx` hiện tại khớp với cùng tài khoản bot đó. Điều này ngăn vòng lặp vọng lại của nền tảng trong khi vẫn cho phép người dùng trích dẫn hoặc trả lời các tin nhắn bot trước đó. +- **Thiết lập bằng `--token-file` vẫn hiển thị chưa cấu hình:** `--token-file` chỉ đặt AppSecret. Bạn vẫn cần `appId` trong cấu hình hoặc `QQBOT_APP_ID`. +- **Tin nhắn chủ động không đến:** QQ có thể chặn tin nhắn do bot khởi tạo nếu người dùng gần đây chưa tương tác. +- **Giọng nói không được chép lời:** bảo đảm STT đã được cấu hình và nhà cung cấp có thể truy cập được. ## Liên quan diff --git a/docs/vi/channels/slack.md b/docs/vi/channels/slack.md index f21dbf7d9..df397fa1a 100644 --- a/docs/vi/channels/slack.md +++ b/docs/vi/channels/slack.md @@ -1,47 +1,47 @@ --- read_when: - Thiết lập Slack hoặc gỡ lỗi chế độ socket/HTTP của Slack -summary: Thiết lập Slack và hành vi khi chạy (Chế độ Socket + URL yêu cầu HTTP) +summary: Thiết lập Slack và hành vi thời gian chạy (Socket Mode + URL yêu cầu HTTP) title: Slack x-i18n: - generated_at: "2026-05-03T21:27:14Z" + generated_at: "2026-05-04T02:22:12Z" model: gpt-5.5 provider: openai - source_hash: d902fbbad23cee9b3f0ab7d240845b7b229e2d2507c5ea1d1a0fa3baa915d80a + source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b source_path: channels/slack.md workflow: 16 --- -Sẵn sàng cho production cho tin nhắn trực tiếp và kênh thông qua tích hợp ứng dụng Slack. Chế độ mặc định là Chế độ Socket; URL yêu cầu HTTP cũng được hỗ trợ. +Sẵn sàng dùng trong production cho DM và kênh thông qua tích hợp ứng dụng Slack. Chế độ mặc định là Socket Mode; HTTP Request URLs cũng được hỗ trợ. - - Tin nhắn trực tiếp Slack mặc định ở chế độ ghép nối. + + Slack DM mặc định dùng chế độ ghép đôi. - + Hành vi lệnh gốc và danh mục lệnh. - - Chẩn đoán liên kênh và quy trình sửa chữa. + + Chẩn đoán liên kênh và playbook sửa lỗi. ## Thiết lập nhanh - + - - Trong phần cài đặt ứng dụng Slack, nhấn nút **[Tạo ứng dụng mới](https://api.slack.com/apps/new)**: + + Trong phần cài đặt ứng dụng Slack, nhấn nút **[Create New App](https://api.slack.com/apps/new)**: - - chọn **từ manifest** và chọn một không gian làm việc cho ứng dụng của bạn - - dán [manifest ví dụ](#manifest-and-scope-checklist) bên dưới và tiếp tục để tạo - - tạo **Token cấp ứng dụng** (`xapp-...`) với `connections:write` - - cài đặt ứng dụng và sao chép **Token bot** (`xoxb-...`) được hiển thị + - chọn **from a manifest** và chọn một workspace cho ứng dụng của bạn + - dán [manifest mẫu](#manifest-and-scope-checklist) bên dưới và tiếp tục tạo + - tạo **App-Level Token** (`xapp-...`) với `connections:write` + - cài đặt ứng dụng và sao chép **Bot Token** (`xoxb-...`) được hiển thị - + Thiết lập SecretRef được khuyến nghị: @@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - Phương án dự phòng bằng biến môi trường (chỉ tài khoản mặc định): + Phương án dự phòng qua env (chỉ tài khoản mặc định): ```bash SLACK_APP_TOKEN=xapp-... @@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,19 +84,19 @@ openclaw gateway - + - - Trong phần cài đặt ứng dụng Slack, nhấn nút **[Tạo ứng dụng mới](https://api.slack.com/apps/new)**: + + Trong phần cài đặt ứng dụng Slack, nhấn nút **[Create New App](https://api.slack.com/apps/new)**: - - chọn **từ manifest** và chọn một không gian làm việc cho ứng dụng của bạn - - dán [manifest ví dụ](#manifest-and-scope-checklist) và cập nhật URL trước khi tạo - - lưu **Bí mật ký** để xác minh yêu cầu - - cài đặt ứng dụng và sao chép **Token bot** (`xoxb-...`) được hiển thị + - chọn **from a manifest** và chọn một workspace cho ứng dụng của bạn + - dán [manifest mẫu](#manifest-and-scope-checklist) và cập nhật URL trước khi tạo + - lưu **Signing Secret** để xác minh yêu cầu + - cài đặt ứng dụng và sao chép **Bot Token** (`xoxb-...`) được hiển thị - + Thiết lập SecretRef được khuyến nghị: @@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - Sử dụng đường dẫn Webhook riêng cho HTTP nhiều tài khoản + Dùng đường dẫn Webhook duy nhất cho HTTP nhiều tài khoản - Cấp cho mỗi tài khoản một `webhookPath` riêng biệt (mặc định `/slack/events`) để các đăng ký không xung đột. + Cấp cho mỗi tài khoản một `webhookPath` riêng (mặc định `/slack/events`) để các đăng ký không xung đột. - + ```bash openclaw gateway @@ -140,9 +140,9 @@ openclaw gateway -## Tinh chỉnh truyền tải Chế độ Socket +## Tinh chỉnh truyền tải Socket Mode -Với Chế độ Socket, OpenClaw đặt thời gian chờ pong của ứng dụng khách SDK Slack mặc định là 15 giây. Chỉ ghi đè cài đặt truyền tải khi bạn cần tinh chỉnh riêng cho không gian làm việc hoặc máy chủ: +Theo mặc định, OpenClaw đặt thời gian chờ pong của client Slack SDK là 15 giây cho Socket Mode. Chỉ ghi đè cài đặt truyền tải khi bạn cần tinh chỉnh riêng cho workspace hoặc máy chủ: ```json5 { @@ -159,13 +159,13 @@ Với Chế độ Socket, OpenClaw đặt thời gian chờ pong của ứng d } ``` -Chỉ dùng phần này cho các không gian làm việc dùng Chế độ Socket ghi nhận thời gian chờ pong/server-ping của websocket Slack hoặc chạy trên máy chủ có tình trạng thiếu thời gian xử lý vòng lặp sự kiện đã biết. `clientPingTimeout` là thời gian chờ pong sau khi SDK gửi ping từ ứng dụng khách; `serverPingTimeout` là thời gian chờ ping từ máy chủ Slack. Tin nhắn ứng dụng và sự kiện vẫn là trạng thái ứng dụng, không phải tín hiệu kiểm tra trạng thái hoạt động của lớp truyền tải. +Chỉ dùng phần này cho các workspace Socket Mode ghi log timeout pong/server-ping websocket của Slack hoặc chạy trên máy chủ đã biết có tình trạng thiếu tài nguyên vòng lặp sự kiện. `clientPingTimeout` là thời gian chờ pong sau khi SDK gửi client ping; `serverPingTimeout` là thời gian chờ ping từ máy chủ Slack. Tin nhắn và sự kiện ứng dụng vẫn là trạng thái ứng dụng, không phải tín hiệu về trạng thái sống của truyền tải. -## Danh sách kiểm tra manifest và phạm vi +## Danh sách kiểm tra manifest và scope -Manifest ứng dụng Slack cơ sở giống nhau cho Chế độ Socket và URL yêu cầu HTTP. Chỉ khối `settings` (và trường `url` của lệnh gạch chéo) là khác nhau. +Manifest ứng dụng Slack cơ sở giống nhau cho Socket Mode và HTTP Request URLs. Chỉ khối `settings` (và `url` của lệnh slash) là khác. -Manifest cơ sở (mặc định là Chế độ Socket): +Manifest cơ sở (mặc định Socket Mode): ```json { @@ -240,7 +240,7 @@ Manifest cơ sở (mặc định là Chế độ Socket): } ``` -Đối với **chế độ URL yêu cầu HTTP**, hãy thay `settings` bằng biến thể HTTP và thêm `url` vào từng lệnh gạch chéo. Yêu cầu URL công khai: +Đối với **chế độ HTTP Request URLs**, thay `settings` bằng biến thể HTTP và thêm `url` vào từng lệnh slash. Yêu cầu URL công khai: ```json { @@ -258,7 +258,19 @@ Manifest cơ sở (mặc định là Chế độ Socket): "event_subscriptions": { "request_url": "https://gateway-host.example.com/slack/events", "bot_events": [ - /* same as Socket Mode */ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" ] }, "interactivity": { @@ -272,174 +284,179 @@ Manifest cơ sở (mặc định là Chế độ Socket): ### Cài đặt manifest bổ sung -Bật các tính năng khác mở rộng các mặc định ở trên. +Hiển thị các tính năng khác mở rộng những mặc định ở trên. -Manifest mặc định bật tab **Home** của Slack App Home và đăng ký `app_home_opened`. Khi một thành viên không gian làm việc mở tab Home, OpenClaw xuất bản chế độ xem Home mặc định an toàn bằng `views.publish`; không bao gồm payload hội thoại hay cấu hình riêng tư. Tab **Messages** vẫn được bật cho tin nhắn trực tiếp Slack. +Manifest mặc định bật tab **Home** trong Slack App Home và đăng ký `app_home_opened`. Khi một thành viên workspace mở tab Home, OpenClaw xuất bản một chế độ xem Home mặc định an toàn bằng `views.publish`; không bao gồm payload hội thoại hoặc cấu hình riêng tư. Tab **Messages** vẫn được bật cho Slack DM. - + - Có thể dùng nhiều [lệnh gạch chéo gốc](#commands-and-slash-behavior) thay cho một lệnh được cấu hình duy nhất, với vài điểm cần lưu ý: + Có thể dùng nhiều [lệnh slash gốc](#commands-and-slash-behavior) thay cho một lệnh được cấu hình duy nhất, với một số điểm cần lưu ý: - - Dùng `/agentstatus` thay vì `/status` vì lệnh `/status` đã được giữ riêng. - - Không thể cung cấp quá 25 lệnh gạch chéo cùng lúc. + - Dùng `/agentstatus` thay cho `/status` vì lệnh `/status` đã được dành riêng. + - Không thể cung cấp quá 25 lệnh slash cùng lúc. - Thay phần `features.slash_commands` hiện có bằng một tập con của [các lệnh có sẵn](/vi/tools/slash-commands#command-list): + Thay phần `features.slash_commands` hiện có của bạn bằng một tập con của [các lệnh có sẵn](/vi/tools/slash-commands#command-list): - + ```json - "slash_commands": [ - { - "command": "/new", - "description": "Start a new session", - "usage_hint": "[model]" - }, - { - "command": "/reset", - "description": "Reset the current session" - }, - { - "command": "/compact", - "description": "Compact the session context", - "usage_hint": "[instructions]" - }, - { - "command": "/stop", - "description": "Stop the current run" - }, - { - "command": "/session", - "description": "Manage thread-binding expiry", - "usage_hint": "idle or max-age " - }, - { - "command": "/think", - "description": "Set the thinking level", - "usage_hint": "" - }, - { - "command": "/verbose", - "description": "Toggle verbose output", - "usage_hint": "on|off|full" - }, - { - "command": "/fast", - "description": "Show or set fast mode", - "usage_hint": "[status|on|off]" - }, - { - "command": "/reasoning", - "description": "Toggle reasoning visibility", - "usage_hint": "[on|off|stream]" - }, - { - "command": "/elevated", - "description": "Toggle elevated mode", - "usage_hint": "[on|off|ask|full]" - }, - { - "command": "/exec", - "description": "Show or set exec defaults", - "usage_hint": "host= security= ask= node=" - }, - { - "command": "/model", - "description": "Show or set the model", - "usage_hint": "[name|#|status]" - }, - { - "command": "/models", - "description": "List providers/models", - "usage_hint": "[provider] [page] [limit=|size=|all]" - }, - { - "command": "/help", - "description": "Show the short help summary" - }, - { - "command": "/commands", - "description": "Show the generated command catalog" - }, - { - "command": "/tools", - "description": "Show what the current agent can use right now", - "usage_hint": "[compact|verbose]" - }, - { - "command": "/agentstatus", - "description": "Show runtime status, including provider usage/quota when available" - }, - { - "command": "/tasks", - "description": "List active/recent background tasks for the current session" - }, - { - "command": "/context", - "description": "Explain how context is assembled", - "usage_hint": "[list|detail|json]" - }, - { - "command": "/whoami", - "description": "Show your sender identity" - }, - { - "command": "/skill", - "description": "Run a skill by name", - "usage_hint": " [input]" - }, - { - "command": "/btw", - "description": "Ask a side question without changing session context", - "usage_hint": "" - }, - { - "command": "/side", - "description": "Ask a side question without changing session context", - "usage_hint": "" - }, - { - "command": "/usage", - "description": "Control the usage footer or show cost summary", - "usage_hint": "off|tokens|full|cost" - } - ] +{ + "slash_commands": [ + { + "command": "/new", + "description": "Start a new session", + "usage_hint": "[model]" + }, + { + "command": "/reset", + "description": "Reset the current session" + }, + { + "command": "/compact", + "description": "Compact the session context", + "usage_hint": "[instructions]" + }, + { + "command": "/stop", + "description": "Stop the current run" + }, + { + "command": "/session", + "description": "Manage thread-binding expiry", + "usage_hint": "idle or max-age " + }, + { + "command": "/think", + "description": "Set the thinking level", + "usage_hint": "" + }, + { + "command": "/verbose", + "description": "Toggle verbose output", + "usage_hint": "on|off|full" + }, + { + "command": "/fast", + "description": "Show or set fast mode", + "usage_hint": "[status|on|off]" + }, + { + "command": "/reasoning", + "description": "Toggle reasoning visibility", + "usage_hint": "[on|off|stream]" + }, + { + "command": "/elevated", + "description": "Toggle elevated mode", + "usage_hint": "[on|off|ask|full]" + }, + { + "command": "/exec", + "description": "Show or set exec defaults", + "usage_hint": "host= security= ask= node=" + }, + { + "command": "/model", + "description": "Show or set the model", + "usage_hint": "[name|#|status]" + }, + { + "command": "/models", + "description": "List providers/models", + "usage_hint": "[provider] [page] [limit=|size=|all]" + }, + { + "command": "/help", + "description": "Show the short help summary" + }, + { + "command": "/commands", + "description": "Show the generated command catalog" + }, + { + "command": "/tools", + "description": "Show what the current agent can use right now", + "usage_hint": "[compact|verbose]" + }, + { + "command": "/agentstatus", + "description": "Show runtime status, including provider usage/quota when available" + }, + { + "command": "/tasks", + "description": "List active/recent background tasks for the current session" + }, + { + "command": "/context", + "description": "Explain how context is assembled", + "usage_hint": "[list|detail|json]" + }, + { + "command": "/whoami", + "description": "Show your sender identity" + }, + { + "command": "/skill", + "description": "Run a skill by name", + "usage_hint": " [input]" + }, + { + "command": "/btw", + "description": "Ask a side question without changing session context", + "usage_hint": "" + }, + { + "command": "/side", + "description": "Ask a side question without changing session context", + "usage_hint": "" + }, + { + "command": "/usage", + "description": "Control the usage footer or show cost summary", + "usage_hint": "off|tokens|full|cost" + } + ] +} ``` - - Dùng cùng danh sách `slash_commands` như Chế độ Socket ở trên và thêm `"url": "https://gateway-host.example.com/slack/events"` vào mọi mục. Ví dụ: + + Dùng cùng danh sách `slash_commands` như Socket Mode ở trên, rồi thêm `"url": "https://gateway-host.example.com/slack/events"` vào mọi mục. Ví dụ: ```json - "slash_commands": [ - { - "command": "/new", - "description": "Start a new session", - "usage_hint": "[model]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/help", - "description": "Show the short help summary", - "url": "https://gateway-host.example.com/slack/events" - } - // ...repeat for every command with the same `url` value - ] +{ + "slash_commands": [ + { + "command": "/new", + "description": "Start a new session", + "usage_hint": "[model]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/help", + "description": "Show the short help summary", + "url": "https://gateway-host.example.com/slack/events" + } + ] +} ``` + Lặp lại giá trị `url` đó trên mọi lệnh trong danh sách. + - - Thêm phạm vi bot `chat:write.customize` nếu bạn muốn tin nhắn gửi đi sử dụng danh tính tác tử đang hoạt động (tên người dùng và biểu tượng tùy chỉnh) thay vì danh tính ứng dụng Slack mặc định. + + Thêm phạm vi bot `chat:write.customize` nếu bạn muốn tin nhắn gửi đi dùng danh tính agent đang hoạt động (tên người dùng và biểu tượng tùy chỉnh) thay vì danh tính ứng dụng Slack mặc định. Nếu bạn dùng biểu tượng emoji, Slack yêu cầu cú pháp `:emoji_name:`. - - Nếu bạn cấu hình `channels.slack.userToken`, các phạm vi đọc thông thường là: + + Nếu bạn cấu hình `channels.slack.userToken`, các phạm vi đọc điển hình là: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -447,7 +464,7 @@ Manifest mặc định bật tab **Home** của Slack App Home và đăng ký `a - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (nếu bạn phụ thuộc vào thao tác đọc tìm kiếm của Slack) + - `search:read` (nếu bạn phụ thuộc vào lượt đọc tìm kiếm của Slack) @@ -456,9 +473,9 @@ Manifest mặc định bật tab **Home** của Slack App Home và đăng ký `a - `botToken` + `appToken` là bắt buộc cho Socket Mode. - Chế độ HTTP yêu cầu `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` và `userToken` chấp nhận chuỗi văn bản thuần +- `botToken`, `appToken`, `signingSecret`, và `userToken` chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef. -- Token trong cấu hình ghi đè phương án dự phòng từ env. +- Token trong cấu hình ghi đè phương án dự phòng env. - Phương án dự phòng env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` chỉ áp dụng cho tài khoản mặc định. - `userToken` (`xoxp-...`) chỉ cấu hình được trong config (không có phương án dự phòng env) và mặc định có hành vi chỉ đọc (`userTokenReadOnly: true`). @@ -467,36 +484,36 @@ Hành vi ảnh chụp nhanh trạng thái: - Kiểm tra tài khoản Slack theo dõi các trường `*Source` và `*Status` theo từng thông tin xác thực (`botToken`, `appToken`, `signingSecret`, `userToken`). - Trạng thái là `available`, `configured_unavailable`, hoặc `missing`. -- `configured_unavailable` nghĩa là tài khoản được cấu hình thông qua SecretRef - hoặc nguồn bí mật không nội tuyến khác, nhưng đường dẫn lệnh/runtime hiện tại +- `configured_unavailable` nghĩa là tài khoản được cấu hình qua SecretRef + hoặc một nguồn bí mật không nhúng trực tiếp khác, nhưng đường dẫn lệnh/runtime hiện tại không thể phân giải giá trị thực tế. -- Ở chế độ HTTP, `signingSecretStatus` được bao gồm; trong Socket Mode, +- Ở chế độ HTTP, `signingSecretStatus` được bao gồm; ở Socket Mode, cặp bắt buộc là `botTokenStatus` + `appTokenStatus`. -Đối với các action/thao tác đọc thư mục, user token có thể được ưu tiên khi đã cấu hình. Đối với thao tác ghi, bot token vẫn được ưu tiên; thao tác ghi bằng user-token chỉ được phép khi `userTokenReadOnly: false` và bot token không khả dụng. +Đối với thao tác đọc actions/directory, user token có thể được ưu tiên khi đã cấu hình. Đối với thao tác ghi, bot token vẫn được ưu tiên; thao tác ghi bằng user-token chỉ được phép khi `userTokenReadOnly: false` và bot token không khả dụng. -## Action và cổng kiểm soát +## Hành động và cổng kiểm soát -Các action Slack được kiểm soát bởi `channels.slack.actions.*`. +Các hành động Slack được kiểm soát bởi `channels.slack.actions.*`. -Các nhóm action khả dụng trong công cụ Slack hiện tại: +Các nhóm hành động khả dụng trong công cụ Slack hiện tại: | Nhóm | Mặc định | | ---------- | -------- | -| messages | đã bật | -| reactions | đã bật | -| pins | đã bật | -| memberInfo | đã bật | -| emojiList | đã bật | +| messages | bật | +| reactions | bật | +| pins | bật | +| memberInfo | bật | +| emojiList | bật | -Các action tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` và `emoji-list`. `download-file` chấp nhận ID tệp Slack hiển thị trong placeholder tệp đến và trả về bản xem trước ảnh đối với ảnh hoặc siêu dữ liệu tệp cục bộ đối với các loại tệp khác. +Các hành động tin nhắn Slack hiện tại gồm `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, và `emoji-list`. `download-file` chấp nhận ID tệp Slack hiển thị trong placeholder tệp đến và trả về bản xem trước hình ảnh cho ảnh hoặc siêu dữ liệu tệp cục bộ cho các loại tệp khác. ## Kiểm soát truy cập và định tuyến - + `channels.slack.dmPolicy` kiểm soát quyền truy cập DM. `channels.slack.allowFrom` là danh sách cho phép DM chuẩn. - `pairing` (mặc định) @@ -515,34 +532,34 @@ Các action tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `down Thứ tự ưu tiên nhiều tài khoản: - `channels.slack.accounts.default.allowFrom` chỉ áp dụng cho tài khoản `default`. - - Tài khoản có tên kế thừa `channels.slack.allowFrom` khi `allowFrom` riêng của chúng chưa được đặt. - - Tài khoản có tên không kế thừa `channels.slack.accounts.default.allowFrom`. + - Tài khoản được đặt tên kế thừa `channels.slack.allowFrom` khi `allowFrom` riêng của chúng chưa được đặt. + - Tài khoản được đặt tên không kế thừa `channels.slack.accounts.default.allowFrom`. `channels.slack.dm.policy` và `channels.slack.dm.allowFrom` cũ vẫn được đọc để tương thích. `openclaw doctor --fix` di chuyển chúng sang `dmPolicy` và `allowFrom` khi có thể làm vậy mà không thay đổi quyền truy cập. - Ghép đôi trong DM dùng `openclaw pairing approve slack `. + Ghép nối trong DM dùng `openclaw pairing approve slack `. - + `channels.slack.groupPolicy` kiểm soát cách xử lý kênh: - `open` - `allowlist` - `disabled` - Danh sách cho phép kênh nằm trong `channels.slack.channels` và **phải dùng ID kênh Slack ổn định** (ví dụ `C12345678`) làm khóa cấu hình. + Danh sách cho phép kênh nằm dưới `channels.slack.channels` và **phải dùng ID kênh Slack ổn định** (ví dụ `C12345678`) làm khóa config. - Ghi chú runtime: nếu `channels.slack` hoàn toàn bị thiếu (thiết lập chỉ env), runtime dự phòng về `groupPolicy="allowlist"` và ghi cảnh báo (ngay cả khi `channels.defaults.groupPolicy` đã được đặt). + Ghi chú runtime: nếu `channels.slack` hoàn toàn bị thiếu (thiết lập chỉ dùng env), runtime quay về `groupPolicy="allowlist"` và ghi một cảnh báo (ngay cả khi `channels.defaults.groupPolicy` đã được đặt). Phân giải tên/ID: - - các mục danh sách cho phép kênh và danh sách cho phép DM được phân giải khi khởi động khi quyền truy cập token cho phép + - các mục danh sách cho phép kênh và danh sách cho phép DM được phân giải lúc khởi động khi quyền truy cập token cho phép - các mục tên kênh chưa phân giải được giữ nguyên như đã cấu hình nhưng mặc định bị bỏ qua khi định tuyến - - xác thực đầu vào và định tuyến kênh mặc định ưu tiên ID; so khớp trực tiếp theo tên người dùng/slug yêu cầu `channels.slack.dangerouslyAllowNameMatching: true` + - ủy quyền đầu vào và định tuyến kênh mặc định ưu tiên ID; khớp trực tiếp theo tên người dùng/slug yêu cầu `channels.slack.dangerouslyAllowNameMatching: true` - Các khóa dựa trên tên (`#channel-name` hoặc `channel-name`) **không** khớp trong `groupPolicy: "allowlist"`. Tra cứu kênh mặc định ưu tiên ID, nên khóa dựa trên tên sẽ không bao giờ định tuyến thành công và tất cả tin nhắn trong kênh đó sẽ bị chặn âm thầm. Điều này khác với `groupPolicy: "open"`, nơi khóa kênh không bắt buộc để định tuyến và khóa dựa trên tên có vẻ hoạt động. + Khóa dựa trên tên (`#channel-name` hoặc `channel-name`) **không** khớp dưới `groupPolicy: "allowlist"`. Tra cứu kênh mặc định ưu tiên ID, nên khóa dựa trên tên sẽ không bao giờ định tuyến thành công và mọi tin nhắn trong kênh đó sẽ bị chặn âm thầm. Điều này khác với `groupPolicy: "open"`, nơi khóa kênh không bắt buộc cho định tuyến và một khóa dựa trên tên có vẻ hoạt động. Luôn dùng ID kênh Slack làm khóa. Để tìm ID: nhấp chuột phải vào kênh trong Slack → **Copy link** — ID (`C...`) xuất hiện ở cuối URL. @@ -561,7 +578,7 @@ Các action tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `down } ``` - Sai (bị chặn âm thầm trong `groupPolicy: "allowlist"`): + Sai (bị chặn âm thầm dưới `groupPolicy: "allowlist"`): ```json5 { @@ -579,17 +596,17 @@ Các action tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `down - - Tin nhắn kênh mặc định bị cổng mention kiểm soát. + + Tin nhắn kênh mặc định được kiểm soát bằng lượt nhắc đến. - Nguồn mention: + Nguồn lượt nhắc đến: - - mention ứng dụng rõ ràng (`<@botId>`) - - mention nhóm người dùng Slack (``) khi người dùng bot là thành viên của nhóm người dùng đó; yêu cầu `usergroups:read` - - mẫu regex mention (`agents.list[].groupChat.mentionPatterns`, dự phòng `messages.groupChat.mentionPatterns`) - - hành vi luồng trả lời ngầm định tới bot (bị tắt khi `thread.requireExplicitMention` là `true`) + - lượt nhắc đến ứng dụng rõ ràng (`<@botId>`) + - lượt nhắc đến nhóm người dùng Slack (``) khi người dùng bot là thành viên của nhóm người dùng đó; yêu cầu `usergroups:read` + - mẫu regex nhắc đến (`agents.list[].groupChat.mentionPatterns`, dự phòng `messages.groupChat.mentionPatterns`) + - hành vi luồng trả lời ngầm đến bot (bị tắt khi `thread.requireExplicitMention` là `true`) - Điều khiển theo kênh (`channels.slack.channels.`; tên chỉ qua phân giải khi khởi động hoặc `dangerouslyAllowNameMatching`): + Điều khiển theo kênh (`channels.slack.channels.`; tên chỉ thông qua phân giải lúc khởi động hoặc `dangerouslyAllowNameMatching`): - `requireMention` - `users` (danh sách cho phép) @@ -597,10 +614,10 @@ Các action tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `down - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - định dạng khóa `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, hoặc ký tự đại diện `"*"` + - Định dạng khóa `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, hoặc ký tự đại diện `"*"` (khóa cũ không có tiền tố vẫn chỉ ánh xạ tới `id:`) - `allowBots` thận trọng đối với kênh và kênh riêng tư: tin nhắn phòng do bot viết chỉ được chấp nhận khi bot gửi được liệt kê rõ ràng trong danh sách cho phép `users` của phòng đó, hoặc khi ít nhất một ID chủ sở hữu Slack rõ ràng từ `channels.slack.allowFrom` hiện là thành viên phòng. Ký tự đại diện và mục chủ sở hữu theo tên hiển thị không thỏa mãn sự hiện diện của chủ sở hữu. Sự hiện diện của chủ sở hữu dùng `conversations.members` của Slack; hãy đảm bảo ứng dụng có phạm vi đọc khớp với loại phòng (`channels:read` cho kênh công khai, `groups:read` cho kênh riêng tư). Nếu tra cứu thành viên thất bại, OpenClaw loại bỏ tin nhắn phòng do bot viết. + `allowBots` thận trọng đối với kênh và kênh riêng tư: tin nhắn phòng do bot viết chỉ được chấp nhận khi bot gửi được liệt kê rõ ràng trong danh sách cho phép `users` của phòng đó, hoặc khi ít nhất một ID chủ sở hữu Slack rõ ràng từ `channels.slack.allowFrom` hiện là thành viên phòng. Ký tự đại diện và mục chủ sở hữu theo tên hiển thị không thỏa mãn điều kiện hiện diện của chủ sở hữu. Sự hiện diện của chủ sở hữu dùng Slack `conversations.members`; hãy bảo đảm ứng dụng có phạm vi đọc phù hợp cho loại phòng (`channels:read` cho kênh công khai, `groups:read` cho kênh riêng tư). Nếu tra cứu thành viên thất bại, OpenClaw loại bỏ tin nhắn phòng do bot viết. @@ -608,27 +625,27 @@ Các action tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `down ## Luồng, phiên và thẻ trả lời - DM định tuyến là `direct`; kênh là `channel`; MPIM là `group`. -- Ràng buộc tuyến Slack chấp nhận ID peer thô cộng với các dạng mục tiêu Slack như `channel:C12345678`, `user:U12345678` và `<@U12345678>`. -- Với `session.dmScope=main` mặc định, DM Slack được gộp vào phiên chính của tác tử. +- Ràng buộc tuyến Slack chấp nhận ID peer thô cùng các dạng đích Slack như `channel:C12345678`, `user:U12345678`, và `<@U12345678>`. +- Với `session.dmScope=main` mặc định, DM Slack gộp vào phiên chính của agent. - Phiên kênh: `agent::slack:channel:`. - Trả lời trong luồng có thể tạo hậu tố phiên luồng (`:thread:`) khi áp dụng. - `channels.slack.thread.historyScope` mặc định là `thread`; `thread.inheritParent` mặc định là `false`. -- `channels.slack.thread.initialHistoryLimit` kiểm soát số lượng tin nhắn luồng hiện có được tải khi một phiên luồng mới bắt đầu (mặc định `20`; đặt `0` để tắt). -- `channels.slack.thread.requireExplicitMention` (mặc định `false`): khi là `true`, chặn mention luồng ngầm định để bot chỉ phản hồi các mention `@bot` rõ ràng bên trong luồng, ngay cả khi bot đã tham gia luồng. Nếu không có tùy chọn này, các trả lời trong luồng mà bot đã tham gia sẽ bỏ qua cổng `requireMention`. +- `channels.slack.thread.initialHistoryLimit` kiểm soát số lượng tin nhắn luồng hiện có được lấy khi phiên luồng mới bắt đầu (mặc định `20`; đặt `0` để tắt). +- `channels.slack.thread.requireExplicitMention` (mặc định `false`): khi `true`, chặn nhắc đến luồng ngầm để bot chỉ phản hồi các lượt nhắc đến `@bot` rõ ràng bên trong luồng, ngay cả khi bot đã tham gia luồng. Nếu không có tùy chọn này, các câu trả lời trong luồng có bot tham gia sẽ bỏ qua cổng `requireMention`. Điều khiển luồng trả lời: - `channels.slack.replyToMode`: `off|first|all|batched` (mặc định `off`) - `channels.slack.replyToModeByChatType`: theo từng `direct|group|channel` -- dự phòng cũ cho trò chuyện trực tiếp: `channels.slack.dm.replyToMode` +- phương án dự phòng cũ cho chat trực tiếp: `channels.slack.dm.replyToMode` -Thẻ trả lời thủ công được hỗ trợ: +Hỗ trợ thẻ trả lời thủ công: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` tắt **tất cả** luồng trả lời trong Slack, bao gồm các thẻ `[[reply_to_*]]` rõ ràng. Điều này khác với Telegram, nơi các thẻ rõ ràng vẫn được tôn trọng ở chế độ `"off"`. Luồng Slack ẩn tin nhắn khỏi kênh trong khi trả lời Telegram vẫn hiển thị nội tuyến. +`replyToMode="off"` tắt **tất cả** luồng trả lời trong Slack, bao gồm cả thẻ `[[reply_to_*]]` rõ ràng. Điều này khác với Telegram, nơi thẻ rõ ràng vẫn được tôn trọng ở chế độ `"off"`. Luồng Slack ẩn tin nhắn khỏi kênh, còn trả lời Telegram vẫn hiển thị nội tuyến. ## Phản ứng xác nhận @@ -640,33 +657,33 @@ Thứ tự phân giải: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- phương án dự phòng emoji danh tính tác tử (`agents.list[].identity.emoji`, nếu không thì "👀") +- phương án dự phòng emoji danh tính agent (`agents.list[].identity.emoji`, nếu không thì "👀") Ghi chú: - Slack yêu cầu shortcode (ví dụ `"eyes"`). - Dùng `""` để tắt phản ứng cho tài khoản Slack hoặc toàn cục. -## Truyền phát văn bản +## Truyền trực tuyến văn bản `channels.slack.streaming` kiểm soát hành vi xem trước trực tiếp: -- `off`: tắt truyền phát xem trước trực tiếp. -- `partial` (mặc định): thay thế văn bản xem trước bằng đầu ra từng phần mới nhất. -- `block`: thêm các bản cập nhật xem trước theo từng khúc. -- `progress`: hiển thị văn bản trạng thái tiến độ trong khi tạo, rồi gửi văn bản cuối cùng. -- `streaming.preview.toolProgress`: khi bản xem trước nháp đang hoạt động, định tuyến các bản cập nhật công cụ/tiến độ vào cùng tin nhắn xem trước đã chỉnh sửa (mặc định: `true`). Đặt `false` để giữ riêng các tin nhắn công cụ/tiến độ. +- `off`: tắt truyền trực tuyến bản xem trước trực tiếp. +- `partial` (mặc định): thay thế văn bản xem trước bằng đầu ra một phần mới nhất. +- `block`: nối thêm các bản cập nhật xem trước theo khối. +- `progress`: hiển thị văn bản trạng thái tiến trình trong khi tạo, rồi gửi văn bản cuối cùng. +- `streaming.preview.toolProgress`: khi bản xem trước nháp đang hoạt động, định tuyến cập nhật công cụ/tiến trình vào cùng tin nhắn xem trước đã chỉnh sửa (mặc định: `true`). Đặt `false` để giữ riêng các tin nhắn công cụ/tiến trình. -`channels.slack.streaming.nativeTransport` kiểm soát truyền phát văn bản gốc của Slack khi `channels.slack.streaming.mode` là `partial` (mặc định: `true`). +`channels.slack.streaming.nativeTransport` kiểm soát truyền trực tuyến văn bản gốc của Slack khi `channels.slack.streaming.mode` là `partial` (mặc định: `true`). -- Phải có sẵn luồng trả lời để truyền phát văn bản gốc và trạng thái luồng trợ lý Slack xuất hiện. Việc chọn luồng vẫn tuân theo `replyToMode`. -- Kênh, trò chuyện nhóm và gốc DM cấp cao nhất vẫn có thể dùng bản xem trước nháp thông thường khi truyền phát gốc không khả dụng hoặc không tồn tại luồng trả lời. -- DM Slack cấp cao nhất mặc định nằm ngoài luồng, nên chúng không hiển thị bản xem trước truyền phát/trạng thái gốc kiểu luồng của Slack; thay vào đó OpenClaw đăng và chỉnh sửa bản xem trước nháp trong DM. -- Nội dung media và payload không phải văn bản dự phòng về cách gửi thông thường. -- Kết quả cuối media/lỗi hủy các chỉnh sửa xem trước đang chờ; kết quả cuối văn bản/block đủ điều kiện chỉ flush khi có thể chỉnh sửa bản xem trước tại chỗ. -- Nếu truyền phát thất bại giữa chừng trong câu trả lời, OpenClaw dự phòng về cách gửi thông thường cho các payload còn lại. +- Phải có sẵn luồng trả lời để truyền trực tuyến văn bản gốc và trạng thái luồng trợ lý Slack xuất hiện. Việc chọn luồng vẫn theo `replyToMode`. +- Kênh, chat nhóm và gốc DM cấp cao nhất vẫn có thể dùng bản xem trước nháp thông thường khi truyền trực tuyến gốc không khả dụng hoặc không có luồng trả lời. +- DM Slack cấp cao nhất mặc định vẫn ở ngoài luồng, nên chúng không hiển thị bản xem trước luồng/trạng thái gốc kiểu luồng của Slack; thay vào đó OpenClaw đăng và chỉnh sửa bản xem trước nháp trong DM. +- Payload phương tiện và không phải văn bản quay về cách gửi thông thường. +- Kết quả cuối cho phương tiện/lỗi hủy các chỉnh sửa xem trước đang chờ; kết quả cuối văn bản/khối đủ điều kiện chỉ flush khi chúng có thể chỉnh sửa bản xem trước tại chỗ. +- Nếu truyền trực tuyến thất bại giữa phản hồi, OpenClaw quay về cách gửi thông thường cho các payload còn lại. -Dùng bản xem trước nháp thay vì truyền phát văn bản gốc của Slack: +Dùng bản xem trước nháp thay vì truyền trực tuyến văn bản gốc của Slack: ```json5 { @@ -687,9 +704,9 @@ Khóa cũ: - boolean `channels.slack.streaming` được tự động di chuyển sang `channels.slack.streaming.mode` và `channels.slack.streaming.nativeTransport`. - `channels.slack.nativeStreaming` cũ được tự động di chuyển sang `channels.slack.streaming.nativeTransport`. -## Phương án dự phòng phản ứng đang nhập +## Phương án dự phòng phản ứng nhập -`typingReaction` thêm một phản ứng tạm thời vào tin nhắn Slack đến trong khi OpenClaw đang xử lý câu trả lời, rồi xóa phản ứng đó khi lượt chạy kết thúc. Điều này hữu ích nhất bên ngoài trả lời trong luồng, vốn dùng chỉ báo trạng thái "đang nhập..." mặc định. +`typingReaction` thêm một phản ứng tạm thời vào tin nhắn Slack đến trong khi OpenClaw đang xử lý câu trả lời, rồi gỡ phản ứng đó khi lượt chạy kết thúc. Điều này hữu ích nhất bên ngoài trả lời theo luồng, vốn dùng chỉ báo trạng thái "is typing..." mặc định. Thứ tự phân giải: @@ -699,42 +716,42 @@ Thứ tự phân giải: Ghi chú: - Slack yêu cầu shortcode (ví dụ `"hourglass_flowing_sand"`). -- Reaction là nỗ lực tốt nhất và việc dọn dẹp được tự động thử sau khi đường dẫn trả lời hoặc lỗi hoàn tất. +- Reaction được thực hiện theo best-effort và việc dọn dẹp được tự động thử sau khi đường dẫn trả lời hoặc lỗi hoàn tất. -## Phương tiện, chia đoạn và phân phối +## Media, chia nhỏ và gửi - Các tệp đính kèm Slack được tải xuống từ URL riêng do Slack lưu trữ (luồng yêu cầu xác thực bằng token) và được ghi vào kho phương tiện khi tìm nạp thành công và giới hạn kích thước cho phép. Placeholder tệp bao gồm Slack `fileId` để agent có thể tìm nạp tệp gốc bằng `download-file`. + Tệp đính kèm Slack được tải xuống từ URL riêng do Slack lưu trữ (luồng yêu cầu xác thực bằng token) và được ghi vào kho media khi fetch thành công và giới hạn kích thước cho phép. Trình giữ chỗ tệp bao gồm Slack `fileId` để agent có thể fetch tệp gốc bằng `download-file`. - Tải xuống sử dụng timeout nhàn rỗi và tổng thời gian có giới hạn. Nếu việc truy xuất tệp Slack bị treo hoặc thất bại, OpenClaw tiếp tục xử lý tin nhắn và quay về placeholder tệp. + Tải xuống dùng thời gian chờ nhàn rỗi và tổng thời gian có giới hạn. Nếu việc truy xuất tệp Slack bị treo hoặc thất bại, OpenClaw tiếp tục xử lý tin nhắn và dùng lại trình giữ chỗ tệp. - Giới hạn kích thước đến lúc runtime mặc định là `20MB` trừ khi được ghi đè bằng `channels.slack.mediaMaxMb`. + Giới hạn kích thước đến khi chạy mặc định là `20MB` trừ khi được ghi đè bằng `channels.slack.mediaMaxMb`. - - các đoạn văn bản sử dụng `channels.slack.textChunkLimit` (mặc định 4000) + - phần văn bản dùng `channels.slack.textChunkLimit` (mặc định 4000) - `channels.slack.chunkMode="newline"` bật chia tách ưu tiên đoạn văn - - gửi tệp sử dụng API tải lên của Slack và có thể bao gồm trả lời trong luồng (`thread_ts`) - - giới hạn phương tiện gửi đi tuân theo `channels.slack.mediaMaxMb` khi được cấu hình; nếu không, lượt gửi kênh sử dụng mặc định theo loại MIME từ pipeline phương tiện + - gửi tệp dùng API tải lên của Slack và có thể bao gồm trả lời trong thread (`thread_ts`) + - giới hạn media gửi đi tuân theo `channels.slack.mediaMaxMb` khi được cấu hình; nếu không, việc gửi qua kênh dùng các mặc định theo loại MIME từ pipeline media - + Các đích tường minh được ưu tiên: - `user:` cho DM - `channel:` cho kênh - DM Slack chỉ văn bản/block có thể đăng trực tiếp tới ID người dùng; tải tệp lên và gửi trong luồng mở DM qua API hội thoại Slack trước vì các đường dẫn đó yêu cầu một ID hội thoại cụ thể. + DM Slack chỉ có văn bản/block có thể đăng trực tiếp tới ID người dùng; tải tệp lên và gửi theo thread sẽ mở DM qua API hội thoại của Slack trước vì các đường dẫn đó cần ID hội thoại cụ thể. ## Lệnh và hành vi slash -Lệnh slash xuất hiện trong Slack dưới dạng một lệnh được cấu hình duy nhất hoặc nhiều lệnh native. Cấu hình `channels.slack.slashCommand` để thay đổi mặc định lệnh: +Lệnh slash xuất hiện trong Slack dưới dạng một lệnh đã cấu hình duy nhất hoặc nhiều lệnh gốc. Cấu hình `channels.slack.slashCommand` để thay đổi mặc định lệnh: - `enabled: false` - `name: "openclaw"` @@ -745,32 +762,32 @@ Lệnh slash xuất hiện trong Slack dưới dạng một lệnh được cấ /openclaw /help ``` -Lệnh native yêu cầu [cài đặt manifest bổ sung](#additional-manifest-settings) trong ứng dụng Slack của bạn và thay vào đó được bật bằng `channels.slack.commands.native: true` hoặc `commands.native: true` trong cấu hình toàn cục. +Lệnh gốc yêu cầu [cài đặt manifest bổ sung](#additional-manifest-settings) trong ứng dụng Slack của bạn và thay vào đó được bật bằng `channels.slack.commands.native: true` hoặc `commands.native: true` trong cấu hình toàn cục. -- Chế độ tự động của lệnh native được **tắt** cho Slack, nên `commands.native: "auto"` không bật lệnh native Slack. +- Chế độ tự động của lệnh gốc được **tắt** cho Slack nên `commands.native: "auto"` không bật lệnh gốc của Slack. ```txt /help ``` -Menu đối số native sử dụng chiến lược kết xuất thích ứng, hiển thị modal xác nhận trước khi điều phối giá trị tùy chọn đã chọn: +Menu đối số gốc dùng chiến lược kết xuất thích ứng, hiển thị modal xác nhận trước khi dispatch giá trị tùy chọn đã chọn: - tối đa 5 tùy chọn: block nút - 6-100 tùy chọn: menu chọn tĩnh -- hơn 100 tùy chọn: chọn bên ngoài với lọc tùy chọn bất đồng bộ khi có trình xử lý tùy chọn tương tác -- vượt giới hạn Slack: giá trị tùy chọn đã mã hóa quay về nút +- hơn 100 tùy chọn: chọn bên ngoài với lọc tùy chọn bất đồng bộ khi có handler tùy chọn interactivity +- vượt giới hạn Slack: giá trị tùy chọn đã mã hóa fallback về nút ```txt /think ``` -Phiên slash sử dụng các khóa cô lập như `agent::slack:slash:` và vẫn định tuyến thực thi lệnh tới phiên hội thoại đích bằng `CommandTargetSessionKey`. +Phiên slash dùng khóa cô lập như `agent::slack:slash:` và vẫn định tuyến thực thi lệnh tới phiên hội thoại đích bằng `CommandTargetSessionKey`. ## Trả lời tương tác -Slack có thể kết xuất các điều khiển trả lời tương tác do agent tạo, nhưng tính năng này mặc định bị tắt. +Slack có thể kết xuất điều khiển trả lời tương tác do agent tạo, nhưng tính năng này mặc định bị tắt. -Bật trên toàn cục: +Bật toàn cục: ```json5 { @@ -802,42 +819,42 @@ Hoặc chỉ bật cho một tài khoản Slack: } ``` -Khi được bật, agent có thể phát các chỉ thị trả lời chỉ dành cho Slack: +Khi được bật, agent có thể phát ra chỉ thị trả lời chỉ dành cho Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Các chỉ thị này được biên dịch thành Slack Block Kit và định tuyến lượt nhấp hoặc lựa chọn trở lại qua đường dẫn sự kiện tương tác Slack hiện có. +Những chỉ thị này biên dịch thành Slack Block Kit và định tuyến lượt bấm hoặc lựa chọn ngược qua đường dẫn sự kiện tương tác Slack hiện có. Ghi chú: -- Đây là UI riêng của Slack. Các kênh khác không dịch chỉ thị Slack Block Kit sang hệ thống nút riêng của chúng. +- Đây là UI riêng cho Slack. Các kênh khác không dịch chỉ thị Slack Block Kit thành hệ thống nút riêng của chúng. - Giá trị callback tương tác là token mờ do OpenClaw tạo, không phải giá trị thô do agent tạo. -- Nếu các block tương tác được tạo sẽ vượt giới hạn Slack Block Kit, OpenClaw quay về trả lời văn bản gốc thay vì gửi payload block không hợp lệ. +- Nếu block tương tác được tạo vượt giới hạn Slack Block Kit, OpenClaw fallback về trả lời văn bản gốc thay vì gửi payload block không hợp lệ. ## Phê duyệt exec trong Slack -Slack có thể hoạt động như một client phê duyệt native với nút và tương tác, thay vì quay về Web UI hoặc terminal. +Slack có thể hoạt động như một client phê duyệt gốc với nút và tương tác tương tác, thay vì fallback về Web UI hoặc terminal. -- Phê duyệt exec sử dụng `channels.slack.execApprovals.*` cho định tuyến DM/kênh native. -- Phê duyệt Plugin vẫn có thể xử lý qua cùng bề mặt nút native của Slack khi yêu cầu đã đến Slack và loại ID phê duyệt là `plugin:`. -- Ủy quyền người phê duyệt vẫn được thực thi: chỉ người dùng được xác định là người phê duyệt mới có thể phê duyệt hoặc từ chối yêu cầu qua Slack. +- Phê duyệt exec dùng `channels.slack.execApprovals.*` cho định tuyến DM/kênh gốc. +- Phê duyệt Plugin vẫn có thể được xử lý qua cùng bề mặt nút Slack-gốc khi yêu cầu đã đến Slack và loại approval id là `plugin:`. +- Ủy quyền người phê duyệt vẫn được thực thi: chỉ những người dùng được xác định là người phê duyệt mới có thể phê duyệt hoặc từ chối yêu cầu qua Slack. -Việc này sử dụng cùng bề mặt nút phê duyệt dùng chung như các kênh khác. Khi `interactivity` được bật trong cài đặt ứng dụng Slack của bạn, lời nhắc phê duyệt kết xuất trực tiếp trong hội thoại dưới dạng nút Block Kit. -Khi các nút đó hiện diện, chúng là UX phê duyệt chính; OpenClaw -chỉ nên bao gồm lệnh `/approve` thủ công khi kết quả công cụ cho biết phê duyệt -qua chat không khả dụng hoặc phê duyệt thủ công là đường dẫn duy nhất. +Điều này dùng cùng bề mặt nút phê duyệt dùng chung như các kênh khác. Khi `interactivity` được bật trong cài đặt ứng dụng Slack của bạn, lời nhắc phê duyệt được kết xuất dưới dạng nút Block Kit trực tiếp trong cuộc hội thoại. +Khi có các nút đó, chúng là UX phê duyệt chính; OpenClaw +chỉ nên bao gồm lệnh `/approve` thủ công khi kết quả công cụ cho biết phê duyệt qua chat +không khả dụng hoặc phê duyệt thủ công là đường dẫn duy nhất. Đường dẫn cấu hình: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (tùy chọn; quay về `commands.ownerAllowFrom` khi có thể) +- `channels.slack.execApprovals.approvers` (tùy chọn; fallback về `commands.ownerAllowFrom` khi có thể) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, mặc định: `dm`) - `agentFilter`, `sessionFilter` -Slack tự động bật phê duyệt exec native khi `enabled` chưa được đặt hoặc là `"auto"` và ít nhất một -người phê duyệt được phân giải. Đặt `enabled: false` để tắt Slack như một client phê duyệt native một cách tường minh. -Đặt `enabled: true` để buộc bật phê duyệt native khi người phê duyệt được phân giải. +Slack tự động bật phê duyệt exec gốc khi `enabled` chưa được đặt hoặc là `"auto"` và ít nhất một +người phê duyệt được phân giải. Đặt `enabled: false` để tắt rõ ràng Slack với vai trò client phê duyệt gốc. +Đặt `enabled: true` để buộc bật phê duyệt gốc khi người phê duyệt được phân giải. Hành vi mặc định khi không có cấu hình phê duyệt exec Slack tường minh: @@ -849,8 +866,8 @@ Hành vi mặc định khi không có cấu hình phê duyệt exec Slack tườ } ``` -Cấu hình native Slack tường minh chỉ cần thiết khi bạn muốn ghi đè người phê duyệt, thêm bộ lọc, hoặc -chọn phân phối tới chat nguồn: +Cấu hình Slack-gốc tường minh chỉ cần thiết khi bạn muốn ghi đè người phê duyệt, thêm bộ lọc, hoặc +chọn tham gia gửi đến chat nguồn: ```json5 { @@ -867,8 +884,8 @@ chọn phân phối tới chat nguồn: ``` Chuyển tiếp `approvals.exec` dùng chung là riêng biệt. Chỉ dùng nó khi lời nhắc phê duyệt exec cũng phải -định tuyến tới chat khác hoặc đích ngoài băng tường minh. Chuyển tiếp `approvals.plugin` dùng chung cũng -riêng biệt; nút native Slack vẫn có thể xử lý phê duyệt Plugin khi các yêu cầu đó đã đến +định tuyến tới các chat khác hoặc đích ngoài băng tường minh. Chuyển tiếp `approvals.plugin` dùng chung cũng +riêng biệt; nút Slack-gốc vẫn có thể xử lý phê duyệt Plugin khi các yêu cầu đó đã đến Slack. `/approve` cùng chat cũng hoạt động trong các kênh Slack và DM đã hỗ trợ lệnh. Xem [Phê duyệt exec](/vi/tools/exec-approvals) để biết đầy đủ mô hình chuyển tiếp phê duyệt. @@ -876,28 +893,28 @@ Slack. ## Sự kiện và hành vi vận hành - Chỉnh sửa/xóa tin nhắn được ánh xạ thành sự kiện hệ thống. -- Phát sóng luồng (trả lời luồng "Also send to channel") được xử lý như tin nhắn người dùng bình thường. +- Thread broadcast (trả lời thread “Also send to channel”) được xử lý như tin nhắn người dùng bình thường. - Sự kiện thêm/xóa reaction được ánh xạ thành sự kiện hệ thống. - Sự kiện thành viên tham gia/rời đi, kênh được tạo/đổi tên, và thêm/xóa ghim được ánh xạ thành sự kiện hệ thống. - `channel_id_changed` có thể di chuyển khóa cấu hình kênh khi `configWrites` được bật. -- Metadata chủ đề/mục đích của kênh được xem là ngữ cảnh không đáng tin cậy và có thể được tiêm vào ngữ cảnh định tuyến. -- Việc gieo ngữ cảnh người bắt đầu luồng và lịch sử luồng ban đầu được lọc theo allowlist người gửi đã cấu hình khi áp dụng. -- Hành động block và tương tác modal phát sự kiện hệ thống `Slack interaction: ...` có cấu trúc với các trường payload phong phú: - - hành động block: giá trị đã chọn, nhãn, giá trị bộ chọn, và metadata `workflow_*` +- Metadata chủ đề/mục đích kênh được xem là ngữ cảnh không đáng tin cậy và có thể được chèn vào ngữ cảnh định tuyến. +- Bộ khởi tạo thread và việc seed ngữ cảnh lịch sử thread ban đầu được lọc theo allowlist người gửi đã cấu hình khi áp dụng. +- Hành động block và tương tác modal phát ra sự kiện hệ thống `Slack interaction: ...` có cấu trúc với các trường payload phong phú: + - hành động block: giá trị đã chọn, nhãn, giá trị picker, và metadata `workflow_*` - sự kiện modal `view_submission` và `view_closed` với metadata kênh đã định tuyến và đầu vào biểu mẫu ## Tham chiếu cấu hình Tham chiếu chính: [Tham chiếu cấu hình - Slack](/vi/gateway/config-channels#slack). - + -- chế độ/xác thực: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` -- quyền truy cập DM: `dm.enabled`, `dmPolicy`, `allowFrom` (cũ: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` -- công tắc tương thích: `dangerouslyAllowNameMatching` (phá kính khẩn cấp; giữ tắt trừ khi cần) -- quyền truy cập kênh: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- luồng/lịch sử: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -- phân phối: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` +- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` +- truy cập DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` +- công tắc tương thích: `dangerouslyAllowNameMatching` (break-glass; để tắt trừ khi cần) +- truy cập kênh: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` +- threading/lịch sử: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- gửi: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - vận hành/tính năng: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -909,11 +926,11 @@ Tham chiếu chính: [Tham chiếu cấu hình - Slack](/vi/gateway/config-chann Kiểm tra theo thứ tự: - `groupPolicy` - - allowlist kênh (`channels.slack.channels`) — **khóa phải là ID kênh** (`C12345678`), không phải tên (`#channel-name`). Khóa dựa trên tên âm thầm thất bại dưới `groupPolicy: "allowlist"` vì định tuyến kênh mặc định ưu tiên ID. Để tìm ID: nhấp chuột phải vào kênh trong Slack → **Copy link** — giá trị `C...` ở cuối URL là ID kênh. + - allowlist kênh (`channels.slack.channels`) — **khóa phải là ID kênh** (`C12345678`), không phải tên (`#channel-name`). Khóa dựa trên tên sẽ âm thầm thất bại dưới `groupPolicy: "allowlist"` vì định tuyến kênh mặc định ưu tiên ID. Để tìm ID: nhấp chuột phải vào kênh trong Slack → **Copy link** — giá trị `C...` ở cuối URL là ID kênh. - `requireMention` - allowlist `users` theo từng kênh - Các lệnh hữu ích: + Lệnh hữu ích: ```bash openclaw channels status --probe @@ -927,10 +944,10 @@ openclaw doctor Kiểm tra: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (hoặc `channels.slack.dm.policy` cũ) - - phê duyệt ghép đôi / mục allowlist - - Sự kiện DM Slack Assistant: log chi tiết nhắc đến `drop message_changed` - thường có nghĩa là Slack đã gửi sự kiện luồng Assistant đã chỉnh sửa mà không có + - `channels.slack.dmPolicy` (hoặc legacy `channels.slack.dm.policy`) + - phê duyệt ghép nối / mục allowlist + - sự kiện DM Slack Assistant: nhật ký verbose nhắc đến `drop message_changed` + thường có nghĩa Slack đã gửi một sự kiện thread Assistant đã chỉnh sửa mà không có người gửi là con người có thể khôi phục trong metadata tin nhắn ```bash @@ -940,11 +957,11 @@ openclaw pairing list slack - Xác thực bot + token ứng dụng và việc bật Socket Mode trong cài đặt ứng dụng Slack. + Xác thực token bot + app và việc bật Socket Mode trong cài đặt ứng dụng Slack. Nếu `openclaw channels status --probe --json` hiển thị `botTokenStatus` hoặc - `appTokenStatus: "configured_unavailable"`, tài khoản Slack đã được cấu hình - nhưng runtime hiện tại không thể phân giải giá trị dựa trên SecretRef. + `appTokenStatus: "configured_unavailable"`, tài khoản Slack đã được + cấu hình nhưng runtime hiện tại không thể phân giải giá trị dựa trên SecretRef. @@ -962,11 +979,11 @@ openclaw pairing list slack - - Xác minh bạn dự định dùng: + + Xác minh ý định của bạn là: - - chế độ lệnh native (`channels.slack.commands.native: true`) với các lệnh slash khớp đã đăng ký trong Slack - - hoặc chế độ một lệnh slash (`channels.slack.slashCommand.enabled: true`) + - chế độ lệnh gốc (`channels.slack.commands.native: true`) với các lệnh slash khớp được đăng ký trong Slack + - hoặc chế độ lệnh slash đơn (`channels.slack.slashCommand.enabled: true`) Đồng thời kiểm tra `commands.useAccessGroups` và allowlist kênh/người dùng. @@ -975,35 +992,35 @@ openclaw pairing list slack ## Tham chiếu vision cho tệp đính kèm -Slack có thể đính kèm phương tiện đã tải xuống vào lượt agent khi tải tệp Slack xuống thành công và giới hạn kích thước cho phép. Tệp hình ảnh có thể được truyền qua đường dẫn hiểu phương tiện hoặc trực tiếp tới mô hình trả lời có khả năng vision; các tệp khác được giữ lại làm ngữ cảnh tệp có thể tải xuống thay vì được xử lý như đầu vào hình ảnh. +Slack có thể đính kèm media đã tải xuống vào lượt agent khi tải tệp Slack thành công và giới hạn kích thước cho phép. Tệp hình ảnh có thể được chuyển qua đường dẫn hiểu media hoặc trực tiếp tới model trả lời có khả năng vision; các tệp khác được giữ lại làm ngữ cảnh tệp có thể tải xuống thay vì được xử lý như đầu vào hình ảnh. -### Loại phương tiện được hỗ trợ +### Loại media được hỗ trợ -| Loại phương tiện | Nguồn | Hành vi hiện tại | Ghi chú | +| Loại phương tiện | Nguồn | Hành vi hiện tại | Ghi chú | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| Hình ảnh JPEG / PNG / GIF / WebP | URL tệp Slack | Được tải xuống và đính kèm vào lượt để xử lý bằng khả năng thị giác | Giới hạn mỗi tệp: `channels.slack.mediaMaxMb` (mặc định 20 MB) | -| Tệp PDF | URL tệp Slack | Được tải xuống và hiển thị dưới dạng ngữ cảnh tệp cho các công cụ như `download-file` hoặc `pdf` | Slack inbound không tự động chuyển PDF thành đầu vào thị giác hình ảnh | -| Tệp khác | URL tệp Slack | Được tải xuống khi có thể và hiển thị dưới dạng ngữ cảnh tệp | Tệp nhị phân không được xem là đầu vào hình ảnh | -| Trả lời trong luồng | Tệp của tin nhắn khởi tạo luồng | Tệp của tin nhắn gốc có thể được nạp làm ngữ cảnh khi phản hồi không có phương tiện trực tiếp | Tin nhắn khởi tạo chỉ có tệp dùng một phần giữ chỗ tệp đính kèm | -| Tin nhắn nhiều hình ảnh | Nhiều tệp Slack | Mỗi tệp được đánh giá độc lập | Xử lý Slack bị giới hạn ở tám tệp mỗi tin nhắn | +| Hình ảnh JPEG / PNG / GIF / WebP | URL tệp Slack | Được tải xuống và đính kèm vào lượt xử lý để xử lý bằng khả năng thị giác | Giới hạn mỗi tệp: `channels.slack.mediaMaxMb` (mặc định 20 MB) | +| Tệp PDF | URL tệp Slack | Được tải xuống và hiển thị dưới dạng ngữ cảnh tệp cho các công cụ như `download-file` hoặc `pdf` | Dữ liệu vào từ Slack không tự động chuyển đổi PDF thành đầu vào thị giác hình ảnh | +| Tệp khác | URL tệp Slack | Được tải xuống khi có thể và hiển thị dưới dạng ngữ cảnh tệp | Tệp nhị phân không được xem là đầu vào hình ảnh | +| Trả lời trong luồng | Tệp của tin nhắn mở đầu luồng | Các tệp của tin nhắn gốc có thể được nạp làm ngữ cảnh khi câu trả lời không có phương tiện trực tiếp | Tin nhắn mở đầu chỉ có tệp sử dụng trình giữ chỗ tệp đính kèm | +| Tin nhắn nhiều hình ảnh | Nhiều tệp Slack | Mỗi tệp được đánh giá độc lập | Xử lý Slack được giới hạn ở tám tệp mỗi tin nhắn | -### Quy trình inbound +### Quy trình dữ liệu vào Khi một tin nhắn Slack có tệp đính kèm đến: -1. OpenClaw tải tệp xuống từ URL riêng tư của Slack bằng token bot (`xoxb-...`). -2. Tệp được ghi vào kho phương tiện khi thành công. -3. Đường dẫn phương tiện đã tải xuống và loại nội dung được thêm vào ngữ cảnh inbound. -4. Các đường dẫn mô hình/công cụ có khả năng xử lý hình ảnh có thể dùng tệp đính kèm hình ảnh từ ngữ cảnh đó. -5. Tệp không phải hình ảnh vẫn có sẵn dưới dạng siêu dữ liệu tệp hoặc tham chiếu phương tiện cho các công cụ có thể xử lý chúng. +1. OpenClaw tải tệp xuống từ URL riêng tư của Slack bằng bot token (`xoxb-...`). +2. Tệp được ghi vào kho lưu trữ phương tiện khi thành công. +3. Đường dẫn phương tiện đã tải xuống và kiểu nội dung được thêm vào ngữ cảnh dữ liệu vào. +4. Các đường dẫn model/công cụ có khả năng xử lý hình ảnh có thể dùng tệp đính kèm hình ảnh từ ngữ cảnh đó. +5. Tệp không phải hình ảnh vẫn khả dụng dưới dạng siêu dữ liệu tệp hoặc tham chiếu phương tiện cho các công cụ có thể xử lý chúng. ### Kế thừa tệp đính kèm từ gốc luồng Khi một tin nhắn đến trong một luồng (có cha `thread_ts`): -- Nếu chính phản hồi không có phương tiện trực tiếp và tin nhắn gốc được bao gồm có tệp, Slack có thể nạp các tệp gốc làm ngữ cảnh khởi tạo luồng. -- Tệp đính kèm trực tiếp của phản hồi được ưu tiên hơn tệp đính kèm của tin nhắn gốc. -- Một tin nhắn gốc chỉ có tệp và không có văn bản được biểu diễn bằng phần giữ chỗ tệp đính kèm để phương án dự phòng vẫn có thể bao gồm các tệp của nó. +- Nếu chính câu trả lời không có phương tiện trực tiếp và tin nhắn gốc được bao gồm có tệp, Slack có thể nạp các tệp gốc làm ngữ cảnh mở đầu luồng. +- Tệp đính kèm trực tiếp trong câu trả lời được ưu tiên hơn tệp đính kèm của tin nhắn gốc. +- Một tin nhắn gốc chỉ có tệp và không có văn bản được biểu diễn bằng trình giữ chỗ tệp đính kèm để đường fallback vẫn có thể bao gồm các tệp của nó. ### Xử lý nhiều tệp đính kèm @@ -1011,30 +1028,30 @@ Khi một tin nhắn Slack duy nhất chứa nhiều tệp đính kèm: - Mỗi tệp đính kèm được xử lý độc lập qua quy trình phương tiện. - Các tham chiếu phương tiện đã tải xuống được tổng hợp vào ngữ cảnh tin nhắn. -- Thứ tự xử lý tuân theo thứ tự tệp của Slack trong payload sự kiện. +- Thứ tự xử lý theo thứ tự tệp của Slack trong event payload. - Lỗi tải xuống ở một tệp đính kèm không chặn các tệp khác. -### Giới hạn kích thước, tải xuống và mô hình +### Giới hạn kích thước, tải xuống và model - **Giới hạn kích thước**: Mặc định 20 MB mỗi tệp. Có thể cấu hình qua `channels.slack.mediaMaxMb`. -- **Lỗi tải xuống**: Các tệp Slack không thể phục vụ, URL hết hạn, tệp không truy cập được, tệp quá kích thước và phản hồi HTML xác thực/đăng nhập của Slack sẽ bị bỏ qua thay vì được báo cáo là định dạng không được hỗ trợ. -- **Mô hình thị giác**: Phân tích hình ảnh dùng mô hình phản hồi đang hoạt động khi mô hình đó hỗ trợ thị giác, hoặc mô hình hình ảnh được cấu hình tại `agents.defaults.imageModel`. +- **Lỗi tải xuống**: Các tệp mà Slack không thể phục vụ, URL hết hạn, tệp không truy cập được, tệp vượt kích thước và phản hồi HTML xác thực/đăng nhập Slack sẽ bị bỏ qua thay vì được báo cáo là định dạng không được hỗ trợ. +- **Model thị giác**: Phân tích hình ảnh dùng model trả lời đang hoạt động khi model đó hỗ trợ thị giác, hoặc model hình ảnh được cấu hình tại `agents.defaults.imageModel`. ### Giới hạn đã biết -| Tình huống | Hành vi hiện tại | Cách khắc phục | +| Kịch bản | Hành vi hiện tại | Cách xử lý thay thế | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| URL tệp Slack hết hạn | Tệp bị bỏ qua; không hiển thị lỗi | Tải lại tệp lên Slack | -| Chưa cấu hình mô hình thị giác | Tệp đính kèm hình ảnh được lưu dưới dạng tham chiếu phương tiện, nhưng không được phân tích như hình ảnh | Cấu hình `agents.defaults.imageModel` hoặc dùng mô hình phản hồi có khả năng thị giác | -| Hình ảnh rất lớn (> 20 MB theo mặc định) | Bị bỏ qua theo giới hạn kích thước | Tăng `channels.slack.mediaMaxMb` nếu Slack cho phép | -| Tệp đính kèm được chuyển tiếp/chia sẻ | Văn bản và phương tiện hình ảnh/tệp do Slack lưu trữ được xử lý theo nỗ lực tốt nhất | Chia sẻ lại trực tiếp trong luồng OpenClaw | +| URL tệp Slack hết hạn | Tệp bị bỏ qua; không hiển thị lỗi | Tải lại tệp lên Slack | +| Chưa cấu hình model thị giác | Tệp đính kèm hình ảnh được lưu dưới dạng tham chiếu phương tiện, nhưng không được phân tích như hình ảnh | Cấu hình `agents.defaults.imageModel` hoặc dùng model trả lời có khả năng thị giác | +| Hình ảnh rất lớn (> 20 MB theo mặc định) | Bị bỏ qua theo giới hạn kích thước | Tăng `channels.slack.mediaMaxMb` nếu Slack cho phép | +| Tệp đính kèm được chuyển tiếp/chia sẻ | Văn bản và phương tiện hình ảnh/tệp do Slack lưu trữ được xử lý theo best-effort | Chia sẻ lại trực tiếp trong luồng OpenClaw | | Tệp đính kèm PDF | Được lưu dưới dạng ngữ cảnh tệp/phương tiện, không tự động định tuyến qua thị giác hình ảnh | Dùng `download-file` cho siêu dữ liệu tệp hoặc công cụ `pdf` để phân tích PDF | ### Tài liệu liên quan - [Quy trình hiểu phương tiện](/vi/nodes/media-understanding) - [Công cụ PDF](/vi/tools/pdf) -- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — bật thị giác cho tệp đính kèm Slack +- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Bật khả năng thị giác cho tệp đính kèm Slack - Kiểm thử hồi quy: [#51353](https://github.com/openclaw/openclaw/issues/51353) - Xác minh trực tiếp: [#51354](https://github.com/openclaw/openclaw/issues/51354) @@ -1042,13 +1059,13 @@ Khi một tin nhắn Slack duy nhất chứa nhiều tệp đính kèm: - Ghép nối người dùng Slack với Gateway. + Ghép một người dùng Slack với Gateway. Hành vi kênh và DM nhóm. - Định tuyến tin nhắn inbound đến tác nhân. + Định tuyến tin nhắn đến các agent. Mô hình mối đe dọa và gia cố bảo mật. diff --git a/docs/vi/channels/tlon.md b/docs/vi/channels/tlon.md index 7b6523492..34804c634 100644 --- a/docs/vi/channels/tlon.md +++ b/docs/vi/channels/tlon.md @@ -4,27 +4,27 @@ read_when: summary: Trạng thái hỗ trợ, khả năng và cấu hình của Tlon/Urbit title: Tlon x-i18n: - generated_at: "2026-05-02T22:16:29Z" + generated_at: "2026-05-04T02:22:11Z" model: gpt-5.5 provider: openai - source_hash: 30915170786fc1ee8b84fb8be2ea42280262923064cfa9ca7107036096a13add + source_hash: 1718044541b431ff2437508e7e6659c14206f4aa84ab8b207e0d791dea2a48c5 source_path: channels/tlon.md workflow: 16 --- -Tlon là một trình nhắn tin phi tập trung được xây dựng trên Urbit. OpenClaw kết nối với Urbit ship của bạn và có thể +Tlon là trình nhắn tin phi tập trung được xây dựng trên Urbit. OpenClaw kết nối với Urbit ship của bạn và có thể phản hồi DM cũng như tin nhắn trò chuyện nhóm. Theo mặc định, phản hồi trong nhóm yêu cầu nhắc đến bằng @ và có thể -được hạn chế thêm qua allowlist. +được hạn chế thêm qua danh sách cho phép. -Trạng thái: Plugin tích hợp sẵn. DM, nhắc đến trong nhóm, phản hồi theo luồng, định dạng văn bản phong phú và -tải ảnh lên đều được hỗ trợ. Chưa hỗ trợ phản ứng và bình chọn. +Trạng thái: Plugin đi kèm. DM, nhắc đến trong nhóm, phản hồi trong luồng, định dạng văn bản phong phú và +tải ảnh lên đều được hỗ trợ. Phản ứng và cuộc thăm dò chưa được hỗ trợ. -## Plugin tích hợp sẵn +## Plugin đi kèm -Tlon được phát hành dưới dạng Plugin tích hợp sẵn trong các bản phát hành OpenClaw hiện tại, vì vậy các bản dựng +Tlon được phát hành dưới dạng Plugin đi kèm trong các bản phát hành OpenClaw hiện tại, vì vậy các bản dựng đóng gói thông thường không cần cài đặt riêng. -Nếu bạn đang dùng bản dựng cũ hơn hoặc bản cài đặt tùy chỉnh không bao gồm Tlon, hãy cài đặt một +Nếu bạn đang dùng bản dựng cũ hơn hoặc bản cài đặt tùy chỉnh loại trừ Tlon, hãy cài đặt một gói npm hiện tại: Cài đặt qua CLI (npm registry): @@ -33,26 +33,26 @@ Cài đặt qua CLI (npm registry): openclaw plugins install @openclaw/tlon ``` -Dùng gói không kèm phiên bản để theo thẻ phát hành chính thức hiện tại. Chỉ ghim một +Dùng gói không kèm phiên bản để theo dõi thẻ phát hành chính thức hiện tại. Chỉ ghim một phiên bản chính xác khi bạn cần bản cài đặt có thể tái lập. -Checkout cục bộ (khi chạy từ repo git): +Bản checkout cục bộ (khi chạy từ git repo): ```bash openclaw plugins install ./path/to/local/tlon-plugin ``` -Chi tiết: [Plugin](/vi/tools/plugin) +Chi tiết: [Plugins](/vi/tools/plugin) ## Thiết lập -1. Đảm bảo Plugin Tlon khả dụng. - - Các bản phát hành OpenClaw đóng gói hiện tại đã tích hợp sẵn Plugin này. - - Bản cài đặt cũ hơn/tùy chỉnh có thể thêm thủ công bằng các lệnh ở trên. -2. Thu thập URL ship và mã đăng nhập của bạn. +1. Đảm bảo Plugin Tlon có sẵn. + - Các bản phát hành OpenClaw đóng gói hiện tại đã đi kèm Plugin này. + - Các bản cài đặt cũ hơn/tùy chỉnh có thể thêm thủ công bằng các lệnh ở trên. +2. Lấy URL ship và mã đăng nhập của bạn. 3. Cấu hình `channels.tlon`. 4. Khởi động lại Gateway. -5. DM cho bot hoặc nhắc đến bot trong một kênh nhóm. +5. DM bot hoặc nhắc đến bot trong kênh nhóm. Cấu hình tối thiểu (một tài khoản): @@ -72,8 +72,8 @@ Cấu hình tối thiểu (một tài khoản): ## Ship riêng tư/LAN -Theo mặc định, OpenClaw chặn tên máy chủ và dải IP riêng tư/nội bộ để bảo vệ chống SSRF. -Nếu ship của bạn đang chạy trên mạng riêng (localhost, IP LAN hoặc tên máy chủ nội bộ), +Theo mặc định, OpenClaw chặn hostname và dải IP riêng tư/nội bộ để bảo vệ khỏi SSRF. +Nếu ship của bạn đang chạy trên mạng riêng tư (localhost, IP LAN hoặc hostname nội bộ), bạn phải bật rõ ràng: ```json5 @@ -98,7 +98,7 @@ cho các yêu cầu tới URL ship của bạn. ## Kênh nhóm -Tự động phát hiện được bật theo mặc định. Bạn cũng có thể ghim kênh thủ công: +Tự động khám phá được bật theo mặc định. Bạn cũng có thể ghim kênh thủ công: ```json5 { @@ -110,7 +110,7 @@ Tự động phát hiện được bật theo mặc định. Bạn cũng có th } ``` -Tắt tự động phát hiện: +Tắt tự động khám phá: ```json5 { @@ -124,7 +124,7 @@ Tắt tự động phát hiện: ## Kiểm soát truy cập -Allowlist DM (trống = không cho phép DM, dùng `ownerShip` cho luồng phê duyệt): +Danh sách cho phép DM (trống = không cho phép DM, dùng `ownerShip` cho luồng phê duyệt): ```json5 { @@ -136,7 +136,7 @@ Allowlist DM (trống = không cho phép DM, dùng `ownerShip` cho luồng phê } ``` -Ủy quyền nhóm (bị hạn chế theo mặc định): +Ủy quyền nhóm (mặc định bị hạn chế): ```json5 { @@ -174,14 +174,14 @@ Allowlist DM (trống = không cho phép DM, dùng `ownerShip` cho luồng phê ``` Owner ship được **tự động ủy quyền ở mọi nơi** — lời mời DM được tự động chấp nhận và -tin nhắn kênh luôn được cho phép. Bạn không cần thêm owner vào `dmAllowlist` hoặc +tin nhắn kênh luôn được phép. Bạn không cần thêm owner vào `dmAllowlist` hoặc `defaultAuthorizedShips`. Khi được đặt, owner nhận thông báo DM cho: -- Yêu cầu DM từ các ship không có trong allowlist -- Lượt nhắc đến trong các kênh không có ủy quyền -- Yêu cầu lời mời nhóm +- Yêu cầu DM từ các ship không có trong danh sách cho phép +- Lượt nhắc đến trong các kênh chưa được ủy quyền +- Yêu cầu mời nhóm ## Thiết lập tự động chấp nhận @@ -197,55 +197,59 @@ Tự động chấp nhận lời mời DM (cho các ship trong dmAllowlist): } ``` -Tự động chấp nhận lời mời nhóm: +Tự động chấp nhận lời mời nhóm từ các ship đáng tin cậy: ```json5 { channels: { tlon: { autoAcceptGroupInvites: true, + groupInviteAllowlist: ["~zod"], }, }, } ``` -## Đích gửi (CLI/cron) +`autoAcceptGroupInvites` mặc định từ chối an toàn khi `groupInviteAllowlist` trống. Đặt +danh sách cho phép thành các ship có lời mời nhóm cần được tự động chấp nhận. -Dùng các đích này với `openclaw message send` hoặc gửi qua Cron: +## Mục tiêu gửi (CLI/Cron) + +Dùng các mục tiêu này với `openclaw message send` hoặc gửi qua Cron: - DM: `~sampel-palnet` hoặc `dm/~sampel-palnet` - Nhóm: `chat/~host-ship/channel` hoặc `group:~host-ship/channel` -## Skill tích hợp sẵn +## Kỹ năng đi kèm -Plugin Tlon bao gồm một skill tích hợp sẵn ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)) +Plugin Tlon bao gồm một kỹ năng đi kèm ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)) cung cấp quyền truy cập CLI vào các thao tác Tlon: - **Liên hệ**: lấy/cập nhật hồ sơ, liệt kê liên hệ - **Kênh**: liệt kê, tạo, đăng tin nhắn, lấy lịch sử - **Nhóm**: liệt kê, tạo, quản lý thành viên - **DM**: gửi tin nhắn, phản ứng với tin nhắn -- **Phản ứng**: thêm/xóa phản ứng emoji cho bài đăng và DM +- **Phản ứng**: thêm/xóa phản ứng emoji vào bài đăng và DM - **Thiết lập**: quản lý quyền Plugin qua lệnh slash -Skill tự động khả dụng khi Plugin được cài đặt. +Kỹ năng này tự động có sẵn khi Plugin được cài đặt. ## Khả năng -| Tính năng | Trạng thái | +| Tính năng | Trạng thái | | --------------- | --------------------------------------- | -| Tin nhắn trực tiếp | ✅ Được hỗ trợ | -| Nhóm/kênh | ✅ Được hỗ trợ (theo mặc định cần nhắc đến) | -| Luồng | ✅ Được hỗ trợ (tự động phản hồi trong luồng) | -| Văn bản phong phú | ✅ Markdown được chuyển đổi sang định dạng Tlon | -| Hình ảnh | ✅ Được tải lên bộ nhớ Tlon | -| Phản ứng | ✅ Qua [skill tích hợp sẵn](#bundled-skill) | -| Bình chọn | ❌ Chưa được hỗ trợ | -| Lệnh native | ✅ Được hỗ trợ (theo mặc định chỉ owner) | +| Tin nhắn trực tiếp | ✅ Được hỗ trợ | +| Nhóm/kênh | ✅ Được hỗ trợ (mặc định yêu cầu nhắc đến) | +| Luồng | ✅ Được hỗ trợ (tự động phản hồi trong luồng) | +| Văn bản phong phú | ✅ Markdown được chuyển đổi sang định dạng Tlon | +| Hình ảnh | ✅ Được tải lên bộ nhớ Tlon | +| Phản ứng | ✅ Qua [kỹ năng đi kèm](#bundled-skill) | +| Cuộc thăm dò | ❌ Chưa được hỗ trợ | +| Lệnh gốc | ✅ Được hỗ trợ (mặc định chỉ owner) | ## Khắc phục sự cố -Chạy chuỗi lệnh này trước: +Chạy thang kiểm tra này trước: ```bash openclaw status @@ -254,18 +258,18 @@ openclaw logs --follow openclaw doctor ``` -Lỗi thường gặp: +Các lỗi thường gặp: -- **DM bị bỏ qua**: người gửi không có trong `dmAllowlist` và không có `ownerShip` được cấu hình cho luồng phê duyệt. -- **Tin nhắn nhóm bị bỏ qua**: kênh chưa được phát hiện hoặc người gửi chưa được ủy quyền. +- **DM bị bỏ qua**: người gửi không có trong `dmAllowlist` và chưa cấu hình `ownerShip` cho luồng phê duyệt. +- **Tin nhắn nhóm bị bỏ qua**: kênh chưa được khám phá hoặc người gửi chưa được ủy quyền. - **Lỗi kết nối**: kiểm tra URL ship có thể truy cập được; bật `allowPrivateNetwork` cho ship cục bộ. -- **Lỗi xác thực**: xác minh mã đăng nhập còn hiệu lực (mã được xoay vòng). +- **Lỗi xác thực**: xác minh mã đăng nhập còn hiệu lực (mã sẽ luân phiên thay đổi). ## Tham chiếu cấu hình Cấu hình đầy đủ: [Cấu hình](/vi/gateway/configuration) -Tùy chọn provider: +Tùy chọn nhà cung cấp: - `channels.tlon.enabled`: bật/tắt khởi động kênh. - `channels.tlon.ship`: tên Urbit ship của bot (ví dụ `~sampel-palnet`). @@ -274,25 +278,26 @@ Tùy chọn provider: - `channels.tlon.allowPrivateNetwork`: cho phép URL localhost/LAN (bỏ qua SSRF). - `channels.tlon.ownerShip`: owner ship cho hệ thống phê duyệt (luôn được ủy quyền). - `channels.tlon.dmAllowlist`: các ship được phép DM (trống = không có). -- `channels.tlon.autoAcceptDmInvites`: tự động chấp nhận DM từ các ship trong allowlist. -- `channels.tlon.autoAcceptGroupInvites`: tự động chấp nhận mọi lời mời nhóm. -- `channels.tlon.autoDiscoverChannels`: tự động phát hiện kênh nhóm (mặc định: true). +- `channels.tlon.autoAcceptDmInvites`: tự động chấp nhận DM từ các ship trong danh sách cho phép. +- `channels.tlon.autoAcceptGroupInvites`: tự động chấp nhận lời mời nhóm từ các ship trong danh sách cho phép. +- `channels.tlon.groupInviteAllowlist`: các ship có lời mời nhóm có thể được tự động chấp nhận. +- `channels.tlon.autoDiscoverChannels`: tự động khám phá kênh nhóm (mặc định: true). - `channels.tlon.groupChannels`: các nest kênh được ghim thủ công. - `channels.tlon.defaultAuthorizedShips`: các ship được ủy quyền cho mọi kênh. - `channels.tlon.authorization.channelRules`: quy tắc xác thực theo từng kênh. -- `channels.tlon.showModelSignature`: thêm tên model vào tin nhắn. +- `channels.tlon.showModelSignature`: thêm tên mô hình vào tin nhắn. ## Ghi chú -- Phản hồi nhóm yêu cầu một lượt nhắc đến (ví dụ `~your-bot-ship`) để phản hồi. -- Phản hồi theo luồng: nếu tin nhắn đến nằm trong một luồng, OpenClaw phản hồi trong luồng đó. -- Văn bản phong phú: định dạng Markdown (in đậm, in nghiêng, mã, tiêu đề, danh sách) được chuyển đổi sang định dạng native của Tlon. +- Phản hồi nhóm yêu cầu nhắc đến (ví dụ `~your-bot-ship`) để phản hồi. +- Phản hồi trong luồng: nếu tin nhắn đến nằm trong một luồng, OpenClaw phản hồi trong luồng. +- Văn bản phong phú: định dạng Markdown (in đậm, in nghiêng, mã, tiêu đề, danh sách) được chuyển đổi sang định dạng gốc của Tlon. - Hình ảnh: URL được tải lên bộ nhớ Tlon và nhúng dưới dạng khối hình ảnh. ## Liên quan -- [Tổng quan về kênh](/vi/channels) — tất cả các kênh được hỗ trợ +- [Tổng quan về kênh](/vi/channels) — tất cả kênh được hỗ trợ - [Ghép nối](/vi/channels/pairing) — xác thực DM và luồng ghép nối -- [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và kiểm soát bằng nhắc đến +- [Nhóm](/vi/channels/groups) — hành vi trò chuyện nhóm và cơ chế yêu cầu nhắc đến - [Định tuyến kênh](/vi/channels/channel-routing) — định tuyến phiên cho tin nhắn - [Bảo mật](/vi/gateway/security) — mô hình truy cập và gia cố diff --git a/docs/vi/channels/troubleshooting.md b/docs/vi/channels/troubleshooting.md index d19ba4384..395080136 100644 --- a/docs/vi/channels/troubleshooting.md +++ b/docs/vi/channels/troubleshooting.md @@ -1,21 +1,21 @@ --- read_when: - - Kênh truyền tải báo đã kết nối nhưng phản hồi không thành công - - Bạn cần kiểm tra riêng theo kênh trước khi đi sâu vào tài liệu về nhà cung cấp -summary: Khắc phục sự cố nhanh ở cấp kênh với các dấu hiệu lỗi và cách khắc phục theo từng kênh + - Bộ truyền tải kênh báo đã kết nối nhưng không gửi được phản hồi + - Bạn cần các bước kiểm tra riêng theo kênh trước khi đọc tài liệu chuyên sâu về nhà cung cấp +summary: Khắc phục sự cố nhanh ở cấp kênh với dấu hiệu lỗi và cách khắc phục cho từng kênh title: Khắc phục sự cố kênh x-i18n: - generated_at: "2026-04-29T22:28:24Z" + generated_at: "2026-05-04T02:22:31Z" model: gpt-5.5 provider: openai - source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee + source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2 source_path: channels/troubleshooting.md workflow: 16 --- Sử dụng trang này khi một kênh kết nối được nhưng hoạt động không đúng. -## Trình tự lệnh +## Chuỗi lệnh Trước tiên, chạy các lệnh này theo thứ tự: @@ -27,74 +27,75 @@ openclaw doctor openclaw channels status --probe ``` -Mốc tham chiếu khỏe mạnh: +Mốc cơ sở khỏe mạnh: - `Runtime: running` - `Connectivity probe: ok` - `Capability: read-only`, `write-capable`, hoặc `admin-capable` -- Probe kênh cho thấy transport đã kết nối và, nơi được hỗ trợ, `works` hoặc `audit ok` +- Kiểm tra kênh cho thấy transport đã kết nối và, khi được hỗ trợ, `works` hoặc `audit ok` ## WhatsApp -### Chữ ký lỗi WhatsApp +### Dấu hiệu lỗi WhatsApp -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| Đã kết nối nhưng không trả lời DM | `openclaw pairing list whatsapp` | Phê duyệt người gửi hoặc chuyển chính sách/allowlist DM. | -| Tin nhắn nhóm bị bỏ qua | Kiểm tra `requireMention` + mẫu mention trong cấu hình | Mention bot hoặc nới lỏng chính sách mention cho nhóm đó. | -| Đăng nhập QR hết thời gian chờ với 408 | Kiểm tra env `HTTPS_PROXY` / `HTTP_PROXY` của Gateway | Đặt proxy có thể truy cập; chỉ dùng `NO_PROXY` cho các trường hợp bỏ qua. | -| Vòng lặp ngắt kết nối/đăng nhập lại ngẫu nhiên | `openclaw channels status --probe` + nhật ký | Các lần kết nối lại gần đây được đánh dấu ngay cả khi hiện đang kết nối; theo dõi nhật ký, khởi động lại Gateway, rồi liên kết lại nếu tình trạng chập chờn tiếp diễn. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Đã kết nối nhưng không trả lời DM | `openclaw pairing list whatsapp` | Phê duyệt người gửi hoặc chuyển chính sách/allowlist DM. | +| Tin nhắn nhóm bị bỏ qua | Kiểm tra `requireMention` + mẫu mention trong cấu hình | Mention bot hoặc nới lỏng chính sách mention cho nhóm đó. | +| Đăng nhập QR hết thời gian chờ với 408 | Kiểm tra env `HTTPS_PROXY` / `HTTP_PROXY` của Gateway | Đặt một proxy có thể truy cập; chỉ dùng `NO_PROXY` cho các trường hợp bỏ qua. | +| Ngắt kết nối/đăng nhập lại ngẫu nhiên | `openclaw channels status --probe` + nhật ký | Các lần kết nối lại gần đây vẫn được gắn cờ ngay cả khi hiện đang kết nối; theo dõi nhật ký, khởi động lại Gateway, rồi liên kết lại nếu tình trạng chập chờn tiếp diễn. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố WhatsApp](/vi/channels/whatsapp#troubleshooting) ## Telegram -### Chữ ký lỗi Telegram +### Dấu hiệu lỗi Telegram -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `/start` nhưng không có luồng trả lời dùng được | `openclaw pairing list telegram` | Phê duyệt ghép nối hoặc thay đổi chính sách DM. | -| Bot online nhưng nhóm vẫn im lặng | Xác minh yêu cầu mention và chế độ riêng tư của bot | Tắt chế độ riêng tư để nhóm có thể nhìn thấy hoặc mention bot. | -| Gửi thất bại kèm lỗi mạng | Kiểm tra nhật ký để tìm lỗi gọi API Telegram | Sửa định tuyến DNS/IPv6/proxy tới `api.telegram.org`. | -| Khởi động báo cáo `getMe returned 401` | Kiểm tra nguồn token đã cấu hình | Sao chép lại hoặc tạo lại token BotFather và cập nhật `botToken`, `tokenFile`, hoặc `TELEGRAM_BOT_TOKEN` của tài khoản mặc định. | -| Polling bị treo hoặc kết nối lại chậm | `openclaw logs --follow` để xem chẩn đoán polling | Nâng cấp; nếu các lần khởi động lại là dương tính giả, tinh chỉnh `pollingStallThresholdMs`. Treo dai dẳng vẫn trỏ tới proxy/DNS/IPv6. | -| `setMyCommands` bị từ chối khi khởi động | Kiểm tra nhật ký để tìm `BOT_COMMANDS_TOO_MUCH` | Giảm số lệnh Plugin/skill/tùy chỉnh Telegram hoặc tắt menu gốc. | -| Đã nâng cấp và allowlist chặn bạn | `openclaw security audit` và allowlist cấu hình | Chạy `openclaw doctor --fix` hoặc thay `@username` bằng ID người gửi dạng số. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| `/start` nhưng không có luồng trả lời dùng được | `openclaw pairing list telegram` | Phê duyệt ghép nối hoặc thay đổi chính sách DM. | +| Bot trực tuyến nhưng nhóm vẫn im lặng | Xác minh yêu cầu mention và chế độ quyền riêng tư của bot | Tắt chế độ quyền riêng tư để nhóm có thể hiển thị, hoặc mention bot. | +| Gửi thất bại với lỗi mạng | Kiểm tra nhật ký để tìm lỗi gọi Telegram API | Sửa định tuyến DNS/IPv6/proxy tới `api.telegram.org`. | +| Khi khởi động báo cáo `getMe returned 401` | Kiểm tra nguồn token đã cấu hình | Sao chép lại hoặc tạo lại token BotFather và cập nhật `botToken`, `tokenFile`, hoặc `TELEGRAM_BOT_TOKEN` của tài khoản mặc định. | +| Polling bị dừng hoặc kết nối lại chậm | `openclaw logs --follow` để xem chẩn đoán polling | Nâng cấp; nếu các lần khởi động lại là dương tính giả, tinh chỉnh `pollingStallThresholdMs`. Tình trạng dừng kéo dài vẫn chỉ ra proxy/DNS/IPv6. | +| `setMyCommands` bị từ chối khi khởi động | Kiểm tra nhật ký để tìm `BOT_COMMANDS_TOO_MUCH` | Giảm số lệnh Telegram của Plugin/skill/tùy chỉnh hoặc tắt menu gốc. | +| Đã nâng cấp và allowlist chặn bạn | `openclaw security audit` và allowlist cấu hình | Chạy `openclaw doctor --fix` hoặc thay `@username` bằng ID người gửi dạng số. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Telegram](/vi/channels/telegram#troubleshooting) ## Discord -### Chữ ký lỗi Discord +### Dấu hiệu lỗi Discord -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ------------------------------ | ------------------------------------ | ---------------------------------------------------------- | -| Bot online nhưng không trả lời guild | `openclaw channels status --probe` | Cho phép guild/kênh và xác minh message content intent. | -| Tin nhắn nhóm bị bỏ qua | Kiểm tra nhật ký để tìm các lần chặn do mention gating | Mention bot hoặc đặt `requireMention: false` cho guild/kênh. | -| Thiếu trả lời DM | `openclaw pairing list discord` | Phê duyệt ghép nối DM hoặc điều chỉnh chính sách DM. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ---------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bot trực tuyến nhưng không trả lời trong guild | `openclaw channels status --probe` | Cho phép guild/kênh và xác minh message content intent. | +| Tin nhắn nhóm bị bỏ qua | Kiểm tra nhật ký để tìm các lần chặn do cổng mention | Mention bot hoặc đặt `requireMention: false` cho guild/kênh. | +| Có nhập/chỉ dùng token nhưng không có tin nhắn Discord | Nhật ký phiên hiển thị văn bản của trợ lý với `didSendViaMessagingTool: false` | Mô hình đã trả lời riêng thay vì gọi công cụ nhắn tin. Dùng mô hình đáng tin cậy cho tool-call, hoặc đặt `messages.groupChat.visibleReplies: "automatic"` để tự động đăng. | +| Thiếu trả lời DM | `openclaw pairing list discord` | Phê duyệt ghép nối DM hoặc điều chỉnh chính sách DM. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Discord](/vi/channels/discord#troubleshooting) ## Slack -### Chữ ký lỗi Slack +### Dấu hiệu lỗi Slack -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| --------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| Socket mode đã kết nối nhưng không có phản hồi | `openclaw channels status --probe` | Xác minh app token + bot token và các scope bắt buộc; theo dõi `botTokenStatus` / `appTokenStatus = configured_unavailable` trên thiết lập dựa trên SecretRef. | -| DM bị chặn | `openclaw pairing list slack` | Phê duyệt ghép nối hoặc nới lỏng chính sách DM. | -| Tin nhắn kênh bị bỏ qua | Kiểm tra `groupPolicy` và allowlist kênh | Cho phép kênh hoặc chuyển chính sách sang `open`. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ---------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| Chế độ socket đã kết nối nhưng không có phản hồi | `openclaw channels status --probe` | Xác minh app token + bot token và các scope bắt buộc; theo dõi `botTokenStatus` / `appTokenStatus = configured_unavailable` trên các thiết lập dựa trên SecretRef. | +| DM bị chặn | `openclaw pairing list slack` | Phê duyệt ghép nối hoặc nới lỏng chính sách DM. | +| Tin nhắn kênh bị bỏ qua | Kiểm tra `groupPolicy` và allowlist kênh | Cho phép kênh hoặc chuyển chính sách sang `open`. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Slack](/vi/channels/slack#troubleshooting) ## iMessage và BlueBubbles -### Chữ ký lỗi iMessage và BlueBubbles +### Dấu hiệu lỗi iMessage và BlueBubbles -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| -------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------- | -| Không có sự kiện đến | Xác minh khả năng truy cập webhook/server và quyền của ứng dụng | Sửa URL webhook hoặc trạng thái server BlueBubbles. | -| Có thể gửi nhưng không nhận trên macOS | Kiểm tra quyền riêng tư macOS cho tự động hóa Messages | Cấp lại quyền TCC và khởi động lại tiến trình kênh. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| -------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------- | +| Không có sự kiện đến | Xác minh khả năng truy cập webhook/máy chủ và quyền của ứng dụng | Sửa URL webhook hoặc trạng thái máy chủ BlueBubbles. | +| Có thể gửi nhưng không nhận trên macOS | Kiểm tra quyền riêng tư macOS cho tự động hóa Messages | Cấp lại quyền TCC và khởi động lại tiến trình kênh. | | Người gửi DM bị chặn | `openclaw pairing list imessage` hoặc `openclaw pairing list bluebubbles` | Phê duyệt ghép nối hoặc cập nhật allowlist. | Khắc phục sự cố đầy đủ: @@ -104,40 +105,40 @@ Khắc phục sự cố đầy đủ: ## Signal -### Chữ ký lỗi Signal +### Dấu hiệu lỗi Signal -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ------------------------------ | -------------------------------------- | -------------------------------------------------------- | -| Daemon truy cập được nhưng bot im lặng | `openclaw channels status --probe` | Xác minh URL/tài khoản daemon `signal-cli` và chế độ nhận. | -| DM bị chặn | `openclaw pairing list signal` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | -| Trả lời nhóm không kích hoạt | Kiểm tra allowlist nhóm và mẫu mention | Thêm người gửi/nhóm hoặc nới lỏng gating. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------ | +| Daemon có thể truy cập nhưng bot im lặng | `openclaw channels status --probe` | Xác minh URL/tài khoản daemon `signal-cli` và chế độ nhận. | +| DM bị chặn | `openclaw pairing list signal` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | +| Trả lời nhóm không kích hoạt | Kiểm tra allowlist nhóm và mẫu mention | Thêm người gửi/nhóm hoặc nới lỏng cổng kiểm soát. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Signal](/vi/channels/signal#troubleshooting) ## QQ Bot -### Chữ ký lỗi QQ Bot +### Dấu hiệu lỗi QQ Bot -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ---------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- | -| Bot trả lời "đã bay tới sao Hỏa" | Xác minh `appId` và `clientSecret` trong cấu hình | Đặt thông tin xác thực hoặc khởi động lại Gateway. | -| Không có tin nhắn đến | `openclaw channels status --probe` | Xác minh thông tin xác thực trên QQ Open Platform. | -| Giọng nói không được phiên âm | Kiểm tra cấu hình nhà cung cấp STT | Cấu hình `channels.qqbot.stt` hoặc `tools.media.audio`. | -| Tin nhắn chủ động không đến | Kiểm tra yêu cầu tương tác của nền tảng QQ | QQ có thể chặn tin nhắn do bot khởi tạo nếu không có tương tác gần đây. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- | +| Bot trả lời "gone to Mars" | Xác minh `appId` và `clientSecret` trong cấu hình | Đặt thông tin xác thực hoặc khởi động lại Gateway. | +| Không có tin nhắn đến | `openclaw channels status --probe` | Xác minh thông tin xác thực trên QQ Open Platform. | +| Giọng nói không được phiên âm | Kiểm tra cấu hình nhà cung cấp STT | Cấu hình `channels.qqbot.stt` hoặc `tools.media.audio`. | +| Tin nhắn chủ động không đến | Kiểm tra yêu cầu tương tác của nền tảng QQ | QQ có thể chặn tin nhắn do bot khởi tạo nếu không có tương tác gần đây. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố QQ Bot](/vi/channels/qqbot#troubleshooting) ## Matrix -### Chữ ký lỗi Matrix +### Dấu hiệu lỗi Matrix -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ------------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------- | -| Đã đăng nhập nhưng bỏ qua tin nhắn phòng | `openclaw channels status --probe` | Kiểm tra `groupPolicy`, allowlist phòng và mention gating. | -| DM không được xử lý | `openclaw pairing list matrix` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | -| Phòng mã hóa bị lỗi | `openclaw matrix verify status` | Xác minh lại thiết bị, rồi kiểm tra `openclaw matrix verify backup status`. | -| Khôi phục bản sao lưu đang chờ/bị hỏng | `openclaw matrix verify backup status` | Chạy `openclaw matrix verify backup restore` hoặc chạy lại với khóa khôi phục. | -| Cross-signing/bootstrap trông không đúng | `openclaw matrix verify bootstrap` | Sửa secret storage, cross-signing và trạng thái sao lưu trong một lượt. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | +| Đã đăng nhập nhưng bỏ qua tin nhắn phòng | `openclaw channels status --probe` | Kiểm tra `groupPolicy`, allowlist phòng và cổng mention. | +| DM không được xử lý | `openclaw pairing list matrix` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | +| Phòng được mã hóa bị lỗi | `openclaw matrix verify status` | Xác minh lại thiết bị, rồi kiểm tra `openclaw matrix verify backup status`. | +| Khôi phục bản sao lưu đang chờ/bị hỏng | `openclaw matrix verify backup status` | Chạy `openclaw matrix verify backup restore` hoặc chạy lại với khóa khôi phục. | +| Cross-signing/bootstrap trông sai | `openclaw matrix verify bootstrap` | Sửa secret storage, cross-signing và trạng thái sao lưu trong một lượt. | Thiết lập và cấu hình đầy đủ: [Matrix](/vi/channels/matrix) diff --git a/docs/vi/cli/doctor.md b/docs/vi/cli/doctor.md index 4866d90ea..cc3359b21 100644 --- a/docs/vi/cli/doctor.md +++ b/docs/vi/cli/doctor.md @@ -1,26 +1,26 @@ --- read_when: - - Bạn gặp sự cố kết nối/xác thực và muốn được hướng dẫn cách khắc phục + - Bạn gặp sự cố kết nối/xác thực và muốn được hướng dẫn khắc phục - Bạn đã cập nhật và muốn kiểm tra nhanh -summary: Tài liệu tham khảo CLI cho `openclaw doctor` (kiểm tra tình trạng + sửa chữa có hướng dẫn) -title: Chẩn đoán +summary: Tham chiếu CLI cho `openclaw doctor` (kiểm tra tình trạng + sửa chữa có hướng dẫn) +title: Trình chẩn đoán x-i18n: - generated_at: "2026-05-03T21:28:17Z" + generated_at: "2026-05-04T02:22:30Z" model: gpt-5.5 provider: openai - source_hash: d4baab5b0cd4d046d12ae5bd14ccf05224115856d45e630a57e77a2be15e5db0 + source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Kiểm tra sức khỏe + sửa nhanh cho Gateway và các kênh. +Kiểm tra tình trạng + bản sửa nhanh cho Gateway và các kênh. Liên quan: - Khắc phục sự cố: [Khắc phục sự cố](/vi/gateway/troubleshooting) -- Kiểm toán bảo mật: [Bảo mật](/vi/gateway/security) +- Kiểm tra bảo mật: [Bảo mật](/vi/gateway/security) ## Ví dụ @@ -34,41 +34,41 @@ openclaw doctor --generate-gateway-token ## Tùy chọn -- `--no-workspace-suggestions`: tắt gợi ý bộ nhớ/tìm kiếm workspace +- `--no-workspace-suggestions`: tắt gợi ý bộ nhớ/tìm kiếm không gian làm việc - `--yes`: chấp nhận mặc định mà không nhắc -- `--repair`: áp dụng các sửa chữa không liên quan đến dịch vụ được khuyến nghị mà không nhắc; cài đặt và ghi lại dịch vụ Gateway vẫn cần xác nhận tương tác hoặc lệnh Gateway rõ ràng +- `--repair`: áp dụng các sửa chữa được khuyến nghị không liên quan đến dịch vụ mà không nhắc; cài đặt và ghi lại dịch vụ Gateway vẫn cần xác nhận tương tác hoặc lệnh Gateway rõ ràng - `--fix`: bí danh cho `--repair` -- `--force`: áp dụng sửa chữa mạnh, bao gồm ghi đè cấu hình dịch vụ tùy chỉnh khi cần -- `--non-interactive`: chạy không có lời nhắc; chỉ áp dụng di chuyển an toàn và sửa chữa không liên quan đến dịch vụ +- `--force`: áp dụng sửa chữa mạnh tay, bao gồm ghi đè cấu hình dịch vụ tùy chỉnh khi cần +- `--non-interactive`: chạy mà không có lời nhắc; chỉ các di chuyển an toàn và sửa chữa không liên quan đến dịch vụ - `--generate-gateway-token`: tạo và cấu hình token Gateway -- `--deep`: quét các dịch vụ hệ thống để tìm các bản cài đặt Gateway bổ sung +- `--deep`: quét các dịch vụ hệ thống để tìm các bản cài Gateway bổ sung Ghi chú: -- Lời nhắc tương tác (như sửa keychain/OAuth) chỉ chạy khi stdin là TTY và **không** đặt `--non-interactive`. Các lượt chạy không có giao diện (cron, Telegram, không có terminal) sẽ bỏ qua lời nhắc. -- Hiệu năng: các lượt chạy `doctor` không tương tác bỏ qua tải Plugin sớm để các kiểm tra sức khỏe không có giao diện luôn nhanh. Phiên tương tác vẫn tải đầy đủ Plugin khi một kiểm tra cần phần đóng góp của chúng. +- Lời nhắc tương tác (như sửa chuỗi khóa/OAuth) chỉ chạy khi stdin là TTY và **không** đặt `--non-interactive`. Các lần chạy không giao diện (Cron, Telegram, không có terminal) sẽ bỏ qua lời nhắc. +- Hiệu năng: các lần chạy `doctor` không tương tác bỏ qua tải Plugin sớm để kiểm tra tình trạng không giao diện luôn nhanh. Phiên tương tác vẫn tải đầy đủ Plugin khi một kiểm tra cần phần đóng góp của chúng. - `--fix` (bí danh cho `--repair`) ghi bản sao lưu vào `~/.openclaw/openclaw.json.bak` và loại bỏ các khóa cấu hình không xác định, liệt kê từng mục bị xóa. -- `doctor --fix --non-interactive` báo cáo các định nghĩa dịch vụ Gateway bị thiếu hoặc cũ nhưng không cài đặt hay ghi lại chúng bên ngoài chế độ sửa chữa cập nhật. Chạy `openclaw gateway install` cho dịch vụ bị thiếu, hoặc `openclaw gateway install --force` khi bạn chủ ý muốn thay thế trình khởi chạy. -- Kiểm tra tính toàn vẹn trạng thái hiện phát hiện các tệp bản ghi phiên mồ côi trong thư mục phiên. Việc lưu trữ chúng dưới dạng `.deleted.` cần xác nhận tương tác; `--fix`, `--yes`, và các lượt chạy không có giao diện giữ nguyên chúng tại chỗ. -- Doctor cũng quét `~/.openclaw/cron/jobs.json` (hoặc `cron.store`) để tìm các dạng công việc cron cũ và có thể ghi lại chúng tại chỗ trước khi bộ lập lịch phải tự chuẩn hóa chúng khi chạy. -- Trên Linux, doctor cảnh báo khi crontab của người dùng vẫn chạy `~/.openclaw/bin/ensure-whatsapp.sh` cũ; script đó không còn được bảo trì và có thể ghi log sai về sự cố ngừng hoạt động Gateway WhatsApp khi cron thiếu môi trường systemd user-bus. -- Doctor dọn dẹp trạng thái staging phụ thuộc Plugin cũ do các phiên bản OpenClaw cũ tạo ra. Nó cũng sửa các Plugin có thể tải xuống đã cấu hình nhưng bị thiếu khi registry có thể phân giải chúng, và lượt doctor 2026.5.2 tự động cài đặt các Plugin có thể tải xuống mà cấu hình cũ đã sử dụng trước khi đánh dấu cấu hình là đã được chạm cho bản phát hành đó. -- Doctor sửa cấu hình Plugin cũ bằng cách xóa các id Plugin bị thiếu khỏi `plugins.allow`/`plugins.entries`, cùng với cấu hình kênh treo tương ứng, mục tiêu Heartbeat, và ghi đè mô hình kênh khi khám phá Plugin khỏe mạnh. -- Doctor cách ly cấu hình Plugin không hợp lệ bằng cách vô hiệu hóa mục `plugins.entries.` bị ảnh hưởng và xóa payload `config` không hợp lệ của nó. Khởi động Gateway đã chỉ bỏ qua Plugin lỗi đó để các Plugin và kênh khác có thể tiếp tục chạy. -- Đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một supervisor khác sở hữu vòng đời Gateway. Doctor vẫn báo cáo sức khỏe Gateway/dịch vụ và áp dụng 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ụ và dọn dẹp dịch vụ cũ. -- Trên Linux, doctor bỏ qua các unit systemd giống Gateway bổ sung nhưng không hoạt động và không ghi lại metadata lệnh/entrypoint cho một dịch vụ Gateway systemd đang chạy trong quá trình sửa chữa. Dừng dịch vụ trước hoặc dùng `openclaw gateway install --force` khi bạn chủ ý muốn thay thế trình khởi chạy đang hoạt động. -- Doctor tự động di chuyển cấu hình Talk phẳng cũ (`talk.voiceId`, `talk.modelId`, và các mục liên quan) vào `talk.provider` + `talk.providers.`. -- Các lượt chạy `doctor --fix` lặp lại không còn báo cáo/áp dụng chuẩn hóa Talk khi khác biệt duy nhất là thứ tự khóa đối tượng. +- `doctor --fix --non-interactive` báo cáo định nghĩa dịch vụ Gateway bị thiếu hoặc cũ nhưng không cài đặt hoặc ghi lại chúng bên ngoài chế độ sửa chữa cập nhật. Chạy `openclaw gateway install` cho dịch vụ bị thiếu, hoặc `openclaw gateway install --force` khi bạn cố ý muốn thay thế trình khởi chạy. +- Kiểm tra tính toàn vẹn trạng thái hiện phát hiện các tệp bản ghi hội thoại mồ côi trong thư mục phiên. Lưu trữ chúng dưới dạng `.deleted.` cần xác nhận tương tác; `--fix`, `--yes`, và các lần chạy không giao diện giữ nguyên chúng tại chỗ. +- Doctor cũng quét `~/.openclaw/cron/jobs.json` (hoặc `cron.store`) để tìm các dạng tác vụ Cron cũ và có thể ghi lại chúng tại chỗ trước khi bộ lập lịch phải tự động chuẩn hóa chúng lúc chạy. +- Trên Linux, doctor cảnh báo khi crontab của người dùng vẫn chạy `~/.openclaw/bin/ensure-whatsapp.sh` cũ; script đó không còn được bảo trì và có thể ghi log sai về sự cố ngừng hoạt động của WhatsApp Gateway khi Cron thiếu môi trường user-bus của systemd. +- Doctor dọn trạng thái staging phụ thuộc Plugin cũ do các phiên bản OpenClaw cũ tạo ra. Nó cũng sửa các Plugin có thể tải xuống đã cấu hình nhưng bị thiếu khi registry có thể phân giải chúng, và lần chạy doctor 2026.5.2 tự động cài đặt các Plugin có thể tải xuống mà cấu hình cũ đã dùng trước khi đánh dấu cấu hình đã được chạm cho bản phát hành đó. Nếu tải xuống thất bại, doctor báo cáo lỗi cài đặt và giữ nguyên mục Plugin đã cấu hình cho lần sửa tiếp theo. +- Doctor sửa cấu hình Plugin cũ bằng cách xóa các id Plugin bị thiếu khỏi `plugins.allow`/`plugins.entries`, cùng với cấu hình kênh treo tương ứng, mục tiêu Heartbeat và ghi đè mô hình kênh khi phát hiện Plugin hoạt động bình thường. +- Doctor cách ly cấu hình Plugin không hợp lệ bằng cách tắt mục `plugins.entries.` bị ảnh hưởng và xóa payload `config` không hợp lệ của mục đó. Khởi động Gateway đã chỉ bỏ qua Plugin lỗi đó để các Plugin và kênh khác có thể tiếp tục chạy. +- Đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một trình giám sát khác sở hữu vòng đời Gateway. Doctor vẫn báo cáo tình trạng Gateway/dịch vụ và áp dụng 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ụ và dọn dẹp dịch vụ cũ. +- Trên Linux, doctor bỏ qua các unit systemd bổ sung giống Gateway nhưng không hoạt động và không ghi lại metadata lệnh/điểm vào cho một dịch vụ Gateway systemd đang chạy trong quá trình sửa chữa. Dừng dịch vụ trước hoặc dùng `openclaw gateway install --force` khi bạn cố ý muốn thay thế trình khởi chạy đang hoạt động. +- Doctor tự động di chuyển cấu hình Talk dạng phẳng cũ (`talk.voiceId`, `talk.modelId`, và các mục liên quan) vào `talk.provider` + `talk.providers.`. +- Các lần chạy lặp lại `doctor --fix` không còn báo cáo/áp dụng chuẩn hóa Talk khi khác biệt duy nhất là thứ tự khóa đối tượng. - Doctor bao gồm kiểm tra mức sẵn sàng tìm kiếm bộ nhớ và có thể khuyến nghị `openclaw configure --section model` khi thiếu thông tin xác thực embedding. -- Doctor cảnh báo khi chưa cấu hình chủ sở hữu lệnh. Chủ sở hữu lệnh là tài khoản người vận hành được phép chạy các lệnh chỉ dành cho chủ sở hữu và phê duyệt hành động nguy hiểm. Ghép đôi DM chỉ cho phép ai đó nói chuyện với bot; nếu bạn đã phê duyệt một người gửi trước khi bootstrap chủ sở hữu đầu tiên tồn tại, hãy đặt `commands.ownerAllowFrom` rõ ràng. -- Doctor cảnh báo khi tác tử chế độ Codex được cấu hình và tài sản Codex CLI cá nhân tồn tại trong thư mục chính Codex của người vận hành. Các lần khởi chạy máy chủ ứng dụng Codex cục bộ dùng thư mục chính tách biệt theo từng tác tử, vì vậy hãy dùng `openclaw migrate codex --dry-run` để kiểm kê tài sản cần được chủ động nâng cấp. -- Doctor cảnh báo khi Skills được phép cho tác tử mặc định không khả dụng trong môi trường runtime hiện tại vì thiếu bin, biến môi trường, cấu hình, hoặc yêu cầu hệ điều hành. `doctor --fix` có thể vô hiệu hóa các Skills không khả dụng đó với `skills.entries..enabled=false`; thay vào đó hãy cài đặt/cấu hình yêu cầu bị thiếu khi bạn muốn giữ skill hoạt động. +- Doctor cảnh báo khi chưa cấu hình chủ sở hữu lệnh. Chủ sở hữu lệnh là tài khoản người vận hành được phép chạy các lệnh chỉ dành cho chủ sở hữu và phê duyệt hành động nguy hiểm. Ghép cặp DM chỉ cho phép ai đó nói chuyện với bot; nếu bạn đã phê duyệt người gửi trước khi bootstrap chủ sở hữu đầu tiên tồn tại, hãy đặt `commands.ownerAllowFrom` rõ ràng. +- Doctor cảnh báo khi các agent chế độ Codex được cấu hình và tài sản Codex CLI cá nhân tồn tại trong thư mục gốc Codex của người vận hành. Các lần khởi chạy app-server Codex cục bộ dùng thư mục gốc riêng biệt theo từng agent, vì vậy hãy dùng `openclaw migrate codex --dry-run` để kiểm kê tài sản cần được chủ động nâng cấp. +- Doctor cảnh báo khi Skills được cho phép cho agent mặc định không khả dụng trong môi trường runtime hiện tại vì thiếu bin, biến môi trường, cấu hình hoặc yêu cầu hệ điều hành. `doctor --fix` có thể tắt các Skills không khả dụng đó bằng `skills.entries..enabled=false`; thay vào đó hãy cài đặt/cấu hình yêu cầu bị thiếu khi bạn muốn giữ Skill hoạt động. - Nếu chế độ sandbox được bật nhưng Docker không khả dụng, doctor báo cáo cảnh báo tín hiệu cao kèm cách khắc phục (`install Docker` hoặc `openclaw config set agents.defaults.sandbox.mode off`). -- Nếu các tệp registry sandbox cũ (`~/.openclaw/sandbox/containers.json` hoặc `~/.openclaw/sandbox/browsers.json`) hiện diện, doctor báo cáo chúng; `openclaw doctor --fix` di chuyển các mục hợp lệ vào thư mục registry phân mảnh và cách ly các tệp cũ không hợp lệ. -- Nếu `gateway.auth.token`/`gateway.auth.password` do SecretRef quản lý và không khả dụng trong đường dẫn lệnh hiện tại, doctor báo cáo cảnh báo chỉ đọc và không ghi thông tin xác thực dự phòng dạng văn bản thuần. -- Nếu việc kiểm tra SecretRef của kênh thất bại trong đường dẫn sửa lỗi, doctor tiếp tục và báo cáo cảnh báo thay vì thoát sớm. -- Sau các lần di chuyển thư mục trạng thái, doctor cảnh báo khi tài khoản Telegram hoặc Discord mặc định đã bật phụ thuộc vào env fallback và `TELEGRAM_BOT_TOKEN` hoặc `DISCORD_BOT_TOKEN` không khả dụng cho tiến trình doctor. -- Tự động phân giải tên người dùng `allowFrom` của Telegram (`doctor --fix`) cần token Telegram có thể phân giải trong đường dẫn lệnh hiện tại. Nếu kiểm tra token không khả dụng, doctor báo cáo cảnh báo và bỏ qua tự động phân giải cho lượt đó. +- Nếu các tệp registry sandbox cũ (`~/.openclaw/sandbox/containers.json` hoặc `~/.openclaw/sandbox/browsers.json`) tồn tại, doctor báo cáo chúng; `openclaw doctor --fix` di chuyển các mục hợp lệ vào thư mục registry phân mảnh và cách ly các tệp cũ không hợp lệ. +- Nếu `gateway.auth.token`/`gateway.auth.password` được quản lý bằng SecretRef và không khả dụng trong đường dẫn lệnh hiện tại, doctor báo cáo cảnh báo chỉ đọc và không ghi thông tin xác thực plaintext dự phòng. +- Nếu kiểm tra SecretRef của kênh thất bại trong đường dẫn sửa chữa, doctor tiếp tục và báo cáo cảnh báo thay vì thoát sớm. +- Sau các lần di chuyển thư mục trạng thái, doctor cảnh báo khi tài khoản Telegram hoặc Discord mặc định đã bật phụ thuộc vào dự phòng env và `TELEGRAM_BOT_TOKEN` hoặc `DISCORD_BOT_TOKEN` không khả dụng cho tiến trình doctor. +- Tự động phân giải tên người dùng `allowFrom` của Telegram (`doctor --fix`) cần token Telegram có thể phân giải trong đường dẫn lệnh hiện tại. Nếu không thể kiểm tra token, doctor báo cáo cảnh báo và bỏ qua tự động phân giải cho lần chạy đó. ## macOS: ghi đè env `launchctl` diff --git a/docs/vi/concepts/agent.md b/docs/vi/concepts/agent.md index 38de51850..b99e34bde 100644 --- a/docs/vi/concepts/agent.md +++ b/docs/vi/concepts/agent.md @@ -1,32 +1,32 @@ --- read_when: - Thay đổi môi trường chạy của tác tử, quá trình khởi tạo không gian làm việc hoặc hành vi phiên -summary: Môi trường thực thi tác nhân, hợp đồng không gian làm việc và khởi tạo phiên -title: Môi trường chạy của tác tử +summary: Môi trường chạy của tác tử, hợp đồng không gian làm việc và khởi tạo phiên +title: Môi trường chạy của tác nhân x-i18n: - generated_at: "2026-04-30T09:34:42Z" + generated_at: "2026-05-04T02:22:29Z" model: gpt-5.5 provider: openai - source_hash: f4d65ee96cece296251d7d3a0512f12d2dfa900db0e5ffc0f37dcddae7ea55ad + source_hash: 89bbbd05a9bf2054d3a1f24aeed005a05b61152a047b593addfb46817baae05a source_path: concepts/agent.md workflow: 16 --- -OpenClaw chạy một **môi trường chạy tác tử nhúng duy nhất** — một tiến trình tác tử cho mỗi -Gateway, với không gian làm việc, tệp khởi tạo và kho phiên riêng. Trang này -trình bày hợp đồng của môi trường chạy đó: không gian làm việc phải chứa gì, những tệp nào được -chèn vào, và cách các phiên khởi tạo dựa trên nó. +OpenClaw chạy một **môi trường runtime tác nhân nhúng duy nhất** — một tiến trình tác nhân cho mỗi +Gateway, với workspace, tệp khởi tạo và kho phiên riêng. Trang này +trình bày hợp đồng runtime đó: workspace phải chứa gì, những tệp nào được +chèn vào, và cách các phiên khởi tạo dựa trên đó. -## Không gian làm việc (bắt buộc) +## Workspace (bắt buộc) -OpenClaw dùng một thư mục không gian làm việc tác tử duy nhất (`agents.defaults.workspace`) làm thư mục làm việc **duy nhất** (`cwd`) của tác tử cho công cụ và ngữ cảnh. +OpenClaw sử dụng một thư mục workspace tác nhân duy nhất (`agents.defaults.workspace`) làm thư mục làm việc (`cwd`) **duy nhất** của tác nhân cho công cụ và ngữ cảnh. -Khuyến nghị: dùng `openclaw setup` để tạo `~/.openclaw/openclaw.json` nếu chưa có và khởi tạo các tệp không gian làm việc. +Khuyến nghị: dùng `openclaw setup` để tạo `~/.openclaw/openclaw.json` nếu còn thiếu và khởi tạo các tệp workspace. -Bố cục không gian làm việc đầy đủ + hướng dẫn sao lưu: [Không gian làm việc của tác tử](/vi/concepts/agent-workspace) +Bố cục workspace đầy đủ + hướng dẫn sao lưu: [Workspace tác nhân](/vi/concepts/agent-workspace) -Nếu `agents.defaults.sandbox` được bật, các phiên không phải phiên chính có thể ghi đè điều này bằng -không gian làm việc theo từng phiên bên dưới `agents.defaults.sandbox.workspaceRoot` (xem +Nếu `agents.defaults.sandbox` được bật, các phiên không phải main có thể ghi đè điều này bằng +workspace theo từng phiên dưới `agents.defaults.sandbox.workspaceRoot` (xem [Cấu hình Gateway](/vi/gateway/configuration)). ## Tệp khởi tạo (được chèn) @@ -34,21 +34,21 @@ không gian làm việc theo từng phiên bên dưới `agents.defaults.sandbox Bên trong `agents.defaults.workspace`, OpenClaw kỳ vọng các tệp người dùng có thể chỉnh sửa sau: - `AGENTS.md` — hướng dẫn vận hành + “bộ nhớ” -- `SOUL.md` — chân dung, ranh giới, giọng điệu +- `SOUL.md` — persona, ranh giới, giọng điệu - `TOOLS.md` — ghi chú công cụ do người dùng duy trì (ví dụ: `imsg`, `sag`, quy ước) - `BOOTSTRAP.md` — nghi thức chạy lần đầu một lần (bị xóa sau khi hoàn tất) -- `IDENTITY.md` — tên/sắc thái/emoji của tác tử +- `IDENTITY.md` — tên/cảm giác/emoji của tác nhân - `USER.md` — hồ sơ người dùng + cách xưng hô ưu tiên -Ở lượt đầu tiên của một phiên mới, OpenClaw chèn trực tiếp nội dung của các tệp này vào ngữ cảnh tác tử. +Ở lượt đầu tiên của một phiên mới, OpenClaw chèn nội dung của các tệp này vào Project Context của system prompt. -Các tệp trống sẽ bị bỏ qua. Các tệp lớn được rút gọn và cắt bớt kèm một dấu chỉ báo để lời nhắc luôn gọn nhẹ (hãy đọc tệp để xem nội dung đầy đủ). +Các tệp trống được bỏ qua. Các tệp lớn được rút gọn và cắt bớt kèm một marker để prompt luôn gọn (đọc tệp để xem nội dung đầy đủ). -Nếu thiếu một tệp, OpenClaw chèn một dòng dấu chỉ báo “thiếu tệp” duy nhất (và `openclaw setup` sẽ tạo một mẫu mặc định an toàn). +Nếu thiếu tệp, OpenClaw chèn một dòng marker “thiếu tệp” duy nhất (và `openclaw setup` sẽ tạo một mẫu mặc định an toàn). -`BOOTSTRAP.md` chỉ được tạo cho một **không gian làm việc hoàn toàn mới** (không có tệp khởi tạo nào khác). Nếu bạn xóa tệp này sau khi hoàn tất nghi thức, nó không nên được tạo lại trong các lần khởi động lại sau. +`BOOTSTRAP.md` chỉ được tạo cho **workspace hoàn toàn mới** (không có tệp khởi tạo nào khác). Khi tệp này còn đang chờ xử lý, OpenClaw giữ nó trong Project Context và thêm hướng dẫn khởi tạo trong system-prompt cho nghi thức ban đầu thay vì sao chép nó vào tin nhắn người dùng. Nếu bạn xóa nó sau khi hoàn tất nghi thức, nó sẽ không được tạo lại trong các lần khởi động lại sau. -Để tắt hoàn toàn việc tạo tệp khởi tạo (cho các không gian làm việc đã được chuẩn bị sẵn), hãy đặt: +Để tắt hoàn toàn việc tạo tệp khởi tạo (cho các workspace đã được chuẩn bị sẵn), đặt: ```json5 { agents: { defaults: { skipBootstrap: true } } } @@ -56,28 +56,28 @@ Nếu thiếu một tệp, OpenClaw chèn một dòng dấu chỉ báo “thiế ## Công cụ tích hợp sẵn -Các công cụ lõi (read/exec/edit/write và các công cụ hệ thống liên quan) luôn khả dụng, -tùy theo chính sách công cụ. `apply_patch` là tùy chọn và được kiểm soát bởi -`tools.exec.applyPatch`. `TOOLS.md` **không** kiểm soát những công cụ nào tồn tại; đó là +Các công cụ lõi (read/exec/edit/write và các công cụ hệ thống liên quan) luôn có sẵn, +phụ thuộc vào chính sách công cụ. `apply_patch` là tùy chọn và được kiểm soát bởi +`tools.exec.applyPatch`. `TOOLS.md` **không** kiểm soát những công cụ nào tồn tại; nó là hướng dẫn về cách _bạn_ muốn chúng được sử dụng. ## Skills -OpenClaw tải Skills từ các vị trí này (độ ưu tiên cao nhất trước): +OpenClaw tải Skills từ các vị trí sau (độ ưu tiên cao nhất trước): -- Không gian làm việc: `/skills` -- Skills tác tử dự án: `/.agents/skills` -- Skills tác tử cá nhân: `~/.agents/skills` +- Workspace: `/skills` +- Skills tác nhân dự án: `/.agents/skills` +- Skills tác nhân cá nhân: `~/.agents/skills` - Được quản lý/cục bộ: `~/.openclaw/skills` -- Đi kèm (được phân phối cùng bản cài đặt) +- Đóng gói sẵn (đi kèm bản cài đặt) - Thư mục Skills bổ sung: `skills.load.extraDirs` -Skills có thể được kiểm soát bằng cấu hình/biến môi trường (xem `skills` trong [Cấu hình Gateway](/vi/gateway/configuration)). +Skills có thể được kiểm soát bằng config/env (xem `skills` trong [Cấu hình Gateway](/vi/gateway/configuration)). -## Ranh giới môi trường chạy +## Ranh giới runtime -Môi trường chạy tác tử nhúng được xây dựng trên lõi tác tử Pi (mô hình, công cụ và -đường ống lời nhắc). Quản lý phiên, khám phá, nối dây công cụ và phân phối qua kênh +Môi trường runtime tác nhân nhúng được xây dựng trên lõi tác nhân Pi (mô hình, công cụ và +pipeline prompt). Quản lý phiên, khám phá, nối dây công cụ và phân phối qua kênh là các lớp do OpenClaw sở hữu nằm trên lõi đó. ## Phiên @@ -87,49 +87,49 @@ Bản ghi phiên được lưu dưới dạng JSONL tại: - `~/.openclaw/agents//sessions/.jsonl` ID phiên ổn định và do OpenClaw chọn. -Các thư mục phiên cũ từ những công cụ khác không được đọc. +Các thư mục phiên cũ từ công cụ khác không được đọc. -## Điều hướng khi đang truyền phát +## Điều hướng khi đang streaming -Khi chế độ hàng đợi là `steer`, các tin nhắn đến được chèn vào lượt chạy hiện tại. -Điều hướng đã xếp hàng được gửi **sau khi lượt trợ lý hiện tại hoàn tất -việc thực thi các lệnh gọi công cụ**, trước lệnh gọi LLM tiếp theo. Pi rút hết tất cả -tin nhắn điều hướng đang chờ cùng nhau cho `steer`; `queue` kiểu cũ rút một tin nhắn cho mỗi -ranh giới mô hình. Điều hướng không còn bỏ qua các lệnh gọi công cụ còn lại từ tin nhắn -trợ lý hiện tại. +Khi chế độ hàng đợi là `steer`, tin nhắn đến được chèn vào lượt chạy hiện tại. +Điều hướng trong hàng đợi được phân phối **sau khi lượt assistant hiện tại hoàn tất +việc thực thi các lệnh gọi công cụ**, trước lệnh gọi LLM tiếp theo. Pi rút tất cả +tin nhắn điều hướng đang chờ cùng lúc cho `steer`; `queue` cũ rút một tin nhắn ở mỗi +ranh giới mô hình. Điều hướng không còn bỏ qua các lệnh gọi công cụ còn lại từ +tin nhắn assistant hiện tại. -Khi chế độ hàng đợi là `followup` hoặc `collect`, các tin nhắn đến được giữ lại cho đến khi -lượt hiện tại kết thúc, rồi một lượt tác tử mới bắt đầu với các tải đã xếp hàng. Xem -[Hàng đợi](/vi/concepts/queue) và [Hàng đợi điều hướng](/vi/concepts/queue-steering) để biết hành vi -theo chế độ và ranh giới. +Khi chế độ hàng đợi là `followup` hoặc `collect`, tin nhắn đến được giữ lại cho đến khi +lượt hiện tại kết thúc, rồi một lượt tác nhân mới bắt đầu với các payload đã xếp hàng. Xem +[Hàng đợi](/vi/concepts/queue) và [Hàng đợi điều hướng](/vi/concepts/queue-steering) để biết hành vi về chế độ +và ranh giới. -Truyền phát khối gửi các khối trợ lý đã hoàn tất ngay khi chúng kết thúc; tính năng này +Streaming theo khối gửi các khối assistant đã hoàn tất ngay khi chúng kết thúc; tính năng này **tắt theo mặc định** (`agents.defaults.blockStreamingDefault: "off"`). Tinh chỉnh ranh giới qua `agents.defaults.blockStreamingBreak` (`text_end` so với `message_end`; mặc định là text_end). -Kiểm soát việc chia khối mềm bằng `agents.defaults.blockStreamingChunk` (mặc định là -800–1200 ký tự; ưu tiên ngắt đoạn, rồi dòng mới; cuối cùng là câu). -Gộp các mảnh truyền phát bằng `agents.defaults.blockStreamingCoalesce` để giảm -rác một dòng (gộp dựa trên trạng thái nhàn rỗi trước khi gửi). Các kênh không phải Telegram yêu cầu -`*.blockStreaming: true` rõ ràng để bật phản hồi dạng khối. +Điều khiển việc chia khối mềm bằng `agents.defaults.blockStreamingChunk` (mặc định là +800–1200 ký tự; ưu tiên ngắt đoạn, rồi dòng mới; câu là cuối cùng). +Gộp các đoạn được stream bằng `agents.defaults.blockStreamingCoalesce` để giảm +spam một dòng (gộp dựa trên trạng thái nhàn rỗi trước khi gửi). Các kênh không phải Telegram yêu cầu +`*.blockStreaming: true` rõ ràng để bật phản hồi theo khối. Tóm tắt công cụ chi tiết được phát ra khi công cụ bắt đầu (không debounce); Control UI -truyền phát đầu ra công cụ qua sự kiện tác tử khi có sẵn. -Chi tiết thêm: [Truyền phát + chia mảnh](/vi/concepts/streaming). +stream đầu ra công cụ qua sự kiện tác nhân khi có sẵn. +Chi tiết thêm: [Streaming + chia đoạn](/vi/concepts/streaming). ## Tham chiếu mô hình Tham chiếu mô hình trong cấu hình (ví dụ `agents.defaults.model` và `agents.defaults.models`) được phân tích bằng cách tách tại dấu `/` **đầu tiên**. - Dùng `provider/model` khi cấu hình mô hình. -- Nếu chính ID mô hình chứa `/` (kiểu OpenRouter), hãy bao gồm tiền tố nhà cung cấp (ví dụ: `openrouter/moonshotai/kimi-k2`). -- Nếu bạn bỏ qua nhà cung cấp, trước tiên OpenClaw sẽ thử một bí danh, sau đó là một - kết quả khớp nhà cung cấp đã cấu hình duy nhất cho đúng ID mô hình đó, và chỉ sau đó mới quay về - nhà cung cấp mặc định đã cấu hình. Nếu nhà cung cấp đó không còn cung cấp - mô hình mặc định đã cấu hình, OpenClaw sẽ quay về nhà cung cấp/mô hình đã cấu hình đầu tiên - thay vì hiển thị một mặc định nhà cung cấp đã bị xóa và lỗi thời. +- Nếu ID mô hình tự nó chứa `/` (kiểu OpenRouter), hãy bao gồm tiền tố provider (ví dụ: `openrouter/moonshotai/kimi-k2`). +- Nếu bạn bỏ qua provider, OpenClaw thử alias trước, rồi một kết quả khớp provider đã cấu hình duy nhất + cho đúng ID mô hình đó, và chỉ sau đó mới fallback + về provider mặc định đã cấu hình. Nếu provider đó không còn cung cấp + mô hình mặc định đã cấu hình, OpenClaw fallback về provider/model đã cấu hình đầu tiên + thay vì hiển thị một mặc định provider đã bị gỡ bỏ và lỗi thời. ## Cấu hình (tối thiểu) -Tối thiểu, hãy đặt: +Tối thiểu, đặt: - `agents.defaults.workspace` - `channels.whatsapp.allowFrom` (rất khuyến nghị) @@ -140,6 +140,6 @@ _Tiếp theo: [Trò chuyện nhóm](/vi/channels/group-messages)_ 🦞 ## Liên quan -- [Không gian làm việc của tác tử](/vi/concepts/agent-workspace) -- [Định tuyến đa tác tử](/vi/concepts/multi-agent) +- [Workspace tác nhân](/vi/concepts/agent-workspace) +- [Định tuyến đa tác nhân](/vi/concepts/multi-agent) - [Quản lý phiên](/vi/concepts/session) diff --git a/docs/vi/concepts/mantis.md b/docs/vi/concepts/mantis.md index 2dea717e1..78981f564 100644 --- a/docs/vi/concepts/mantis.md +++ b/docs/vi/concepts/mantis.md @@ -1,65 +1,65 @@ --- read_when: - - Xây dựng hoặc chạy kiểm thử trực quan trực tiếp cho các lỗi OpenClaw - - Thêm xác minh trước và sau cho một yêu cầu kéo - - Thêm các kịch bản truyền tải trực tiếp cho Discord, Slack, WhatsApp hoặc dịch vụ khác + - Xây dựng hoặc chạy QA trực quan trực tiếp cho các lỗi OpenClaw + - Thêm bước xác minh trước và sau cho một yêu cầu kéo + - Thêm các kịch bản truyền tải trực tiếp cho Discord, Slack, WhatsApp hoặc các dịch vụ khác - Gỡ lỗi các lần chạy QA cần ảnh chụp màn hình, tự động hóa trình duyệt hoặc quyền truy cập VNC -summary: Mantis là hệ thống xác minh đầu-cuối trực quan để tái hiện lỗi OpenClaw trên các kênh truyền tải trực tiếp, ghi lại bằng chứng trước và sau, và đính kèm hiện vật vào các PR. +summary: Mantis là hệ thống xác minh trực quan từ đầu đến cuối để tái hiện lỗi OpenClaw trên các kênh truyền tải trực tiếp, ghi lại bằng chứng trước và sau, đồng thời đính kèm các tạo tác vào các PR. title: Bọ ngựa x-i18n: - generated_at: "2026-05-03T21:29:46Z" + generated_at: "2026-05-04T02:23:01Z" model: gpt-5.5 provider: openai - source_hash: 3463882b01a7941f6d758c509d6cd70e099aa8352053347fa9c37a80e5b256ce + source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d source_path: concepts/mantis.md workflow: 16 --- -Mantis là hệ thống xác minh đầu-cuối của OpenClaw dành cho các lỗi cần môi trường chạy thật, phương thức truyền tải thật và bằng chứng có thể nhìn thấy. Hệ thống chạy một kịch bản trên một ref được biết là lỗi, thu thập bằng chứng, chạy cùng kịch bản đó trên một ref ứng viên, rồi xuất bản phần so sánh dưới dạng artifact để maintainer có thể kiểm tra từ PR hoặc từ lệnh cục bộ. +Mantis là hệ thống xác minh đầu cuối của OpenClaw dành cho các lỗi cần môi trường chạy thực, kênh truyền thực và bằng chứng hiển thị được. Nó chạy một kịch bản trên một tham chiếu lỗi đã biết, thu thập bằng chứng, chạy cùng kịch bản đó trên một tham chiếu ứng viên, rồi xuất bản phần so sánh dưới dạng hiện vật để maintainer có thể kiểm tra từ PR hoặc từ lệnh cục bộ. -Mantis bắt đầu với Discord vì Discord cho chúng ta một làn đầu tiên có giá trị cao: xác thực bot thật, kênh máy chủ thật, reaction, luồng, lệnh gốc và giao diện trình duyệt nơi con người có thể xác nhận trực quan những gì phương thức truyền tải hiển thị. +Mantis bắt đầu với Discord vì Discord cho chúng ta một làn đầu tiên có giá trị cao: xác thực bot thật, kênh guild thật, phản ứng, luồng, lệnh native và một giao diện trình duyệt nơi con người có thể xác nhận trực quan những gì kênh truyền đã hiển thị. ## Mục tiêu -- Tái hiện lỗi từ một issue hoặc PR trên GitHub với cùng hình dạng phương thức truyền tải mà người dùng thấy. -- Thu thập artifact **trước** trên ref cơ sở trước khi áp dụng bản sửa. -- Thu thập artifact **sau** trên ref ứng viên sau khi áp dụng bản sửa. -- Sử dụng oracle xác định bất cứ khi nào có thể, chẳng hạn như đọc reaction bằng Discord REST hoặc kiểm tra bản ghi kênh. -- Chụp ảnh màn hình khi lỗi có bề mặt giao diện nhìn thấy được. -- Chạy cục bộ từ CLI do tác nhân điều khiển và chạy từ xa từ GitHub. -- Lưu đủ trạng thái máy để cứu hộ bằng VNC khi đăng nhập, tự động hóa trình duyệt hoặc xác thực nhà cung cấp bị kẹt. -- Đăng trạng thái ngắn gọn lên kênh Discord của operator khi lượt chạy bị chặn, cần hỗ trợ VNC thủ công hoặc hoàn tất. +- Tái hiện một lỗi từ issue hoặc PR trên GitHub với cùng dạng kênh truyền mà người dùng thấy. +- Thu thập một hiện vật **trước** trên tham chiếu cơ sở trước khi áp dụng bản sửa. +- Thu thập một hiện vật **sau** trên tham chiếu ứng viên sau khi áp dụng bản sửa. +- Dùng oracle xác định được bất cứ khi nào có thể, chẳng hạn như đọc phản ứng qua Discord REST hoặc kiểm tra bản ghi kênh. +- Chụp ảnh màn hình khi lỗi có bề mặt UI hiển thị được. +- Chạy cục bộ từ CLI do tác tử điều khiển và chạy từ xa qua GitHub. +- Giữ đủ trạng thái máy cho cứu hộ VNC khi đăng nhập, tự động hóa trình duyệt hoặc xác thực nhà cung cấp bị kẹt. +- Đăng trạng thái ngắn gọn lên kênh Discord của vận hành viên khi lượt chạy bị chặn, cần trợ giúp VNC thủ công hoặc hoàn tất. ## Không phải mục tiêu -- Mantis không thay thế kiểm thử đơn vị. Một lượt chạy Mantis thường nên trở thành một kiểm thử hồi quy nhỏ hơn sau khi bản sửa đã được hiểu rõ. -- Mantis không phải cổng CI nhanh thông thường. Nó chậm hơn, dùng thông tin xác thực thật và chỉ dành cho các lỗi mà môi trường thật có ý nghĩa. -- Mantis không nên yêu cầu con người trong vận hành bình thường. VNC thủ công là đường cứu hộ, không phải luồng chính. -- Mantis không lưu secret thô trong artifact, log, ảnh chụp màn hình, báo cáo Markdown hoặc bình luận PR. +- Mantis không thay thế kiểm thử đơn vị. Một lượt chạy Mantis thường nên được chuyển thành một kiểm thử hồi quy nhỏ hơn sau khi đã hiểu rõ bản sửa. +- Mantis không phải cổng CI nhanh thông thường. Nó chậm hơn, dùng thông tin xác thực live và được dành cho các lỗi mà môi trường live có ý nghĩa. +- Mantis không nên cần con người trong vận hành bình thường. VNC thủ công là đường cứu hộ, không phải đường thành công mặc định. +- Mantis không lưu bí mật thô trong hiện vật, log, ảnh chụp màn hình, báo cáo Markdown hoặc bình luận PR. ## Quyền sở hữu Mantis nằm trong ngăn xếp QA của OpenClaw. -- OpenClaw sở hữu môi trường chạy kịch bản, bộ chuyển đổi phương thức truyền tải, lược đồ bằng chứng và CLI cục bộ trong `pnpm openclaw qa mantis`. -- QA Lab sở hữu các phần harness phương thức truyền tải trực tiếp, helper chụp trình duyệt và trình ghi artifact. +- OpenClaw sở hữu môi trường chạy kịch bản, bộ điều hợp kênh truyền, schema bằng chứng và CLI cục bộ dưới `pnpm openclaw qa mantis`. +- QA Lab sở hữu các phần harness kênh truyền live, trình trợ giúp chụp trình duyệt và bộ ghi hiện vật. - Crabbox sở hữu các máy Linux đã được làm nóng khi cần VM từ xa. -- GitHub Actions sở hữu điểm vào workflow từ xa và thời gian lưu giữ artifact. -- ClawSweeper sở hữu định tuyến bình luận GitHub: phân tích lệnh của maintainer, dispatch workflow và đăng bình luận PR cuối cùng. -- Các tác nhân OpenClaw điều khiển Mantis thông qua Codex khi kịch bản cần thiết lập có tính tác nhân, gỡ lỗi hoặc báo cáo trạng thái bị kẹt. +- GitHub Actions sở hữu điểm vào workflow từ xa và thời hạn lưu hiện vật. +- ClawSweeper sở hữu định tuyến bình luận GitHub: phân tích lệnh maintainer, dispatch workflow và đăng bình luận PR cuối cùng. +- Các tác tử OpenClaw điều khiển Mantis thông qua Codex khi một kịch bản cần thiết lập agentic, gỡ lỗi hoặc báo cáo trạng thái bị kẹt. -Ranh giới này giữ kiến thức về phương thức truyền tải trong OpenClaw, lập lịch máy trong Crabbox và phần keo workflow maintainer trong ClawSweeper. +Ranh giới này giữ kiến thức kênh truyền trong OpenClaw, lập lịch máy trong Crabbox và phần gắn kết workflow maintainer trong ClawSweeper. -## Hình dạng lệnh +## Dạng lệnh -Lệnh cục bộ đầu tiên xác minh bot Discord, máy chủ, kênh, gửi tin nhắn, gửi reaction và đường dẫn artifact: +Lệnh cục bộ đầu tiên xác minh bot Discord, guild, kênh, gửi tin nhắn, gửi phản ứng và đường dẫn hiện vật: ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -Trình chạy trước và sau cục bộ chấp nhận hình dạng này: +Trình chạy trước và sau cục bộ chấp nhận dạng này: ```bash pnpm openclaw qa mantis run \ @@ -70,14 +70,31 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -Trình chạy tạo các worktree cơ sở và ứng viên tách rời dưới thư mục đầu ra, cài đặt dependency, build từng ref, chạy kịch bản với `--allow-failures`, rồi ghi `baseline/`, `candidate/`, `comparison.json` và `mantis-report.md`. Với kịch bản Discord đầu tiên, xác minh thành công nghĩa là trạng thái cơ sở là `fail` và trạng thái ứng viên là `pass`. +Trình chạy tạo các worktree cơ sở và ứng viên tách rời trong thư mục đầu ra, cài đặt phụ thuộc, build từng tham chiếu, chạy kịch bản với `--allow-failures`, rồi ghi `baseline/`, `candidate/`, `comparison.json` và `mantis-report.md`. Với kịch bản Discord đầu tiên, xác minh thành công nghĩa là trạng thái cơ sở là `fail` và trạng thái ứng viên là `pass`. -Workflow smoke của GitHub là `Mantis Discord Smoke`. Workflow GitHub trước và sau cho kịch bản thật đầu tiên là `Mantis Discord Status Reactions`. Nó chấp nhận: +Primitive VM/trình duyệt đầu tiên là kiểm tra smoke desktop: -- `baseline_ref`: ref được kỳ vọng tái hiện hành vi chỉ-queued. -- `candidate_ref`: ref được kỳ vọng hiển thị `queued -> thinking -> done`. +```bash +pnpm openclaw qa mantis desktop-browser-smoke \ + --output-dir .artifacts/qa-e2e/mantis/desktop-browser +``` -Nó checkout ref harness workflow, build các worktree cơ sở và ứng viên riêng, chạy `discord-status-reactions-tool-only` trên từng worktree, rồi tải lên `baseline/`, `candidate/`, `comparison.json` và `mantis-report.md` dưới dạng artifact của Actions. +Nó thuê hoặc tái sử dụng một máy desktop Crabbox, khởi động trình duyệt hiển thị được trong phiên VNC, chụp desktop, kéo hiện vật về thư mục đầu ra cục bộ và ghi lệnh kết nối lại vào báo cáo. Lệnh mặc định dùng nhà cung cấp Hetzner vì đây là nhà cung cấp đầu tiên có desktop/VNC hoạt động trong làn Mantis. Ghi đè bằng `--provider`, `--crabbox-bin` hoặc `OPENCLAW_MANTIS_CRABBOX_PROVIDER` khi chạy trên một đội máy Crabbox khác. + +Các cờ smoke desktop hữu ích: + +- `--lease-id ` hoặc `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` tái sử dụng một desktop đã được làm nóng. +- `--browser-url ` thay đổi trang được mở trong trình duyệt hiển thị được. +- `--html-file ` render một hiện vật HTML cục bộ trong repo trong trình duyệt hiển thị được. Mantis dùng điều này để chụp timeline phản ứng trạng thái Discord đã tạo thông qua một desktop Crabbox thật. +- `--keep-lease` hoặc `OPENCLAW_MANTIS_KEEP_VM=1` giữ một lease mới tạo đã pass mở để kiểm tra qua VNC. Các lượt chạy thất bại mặc định giữ lease khi có tạo lease để vận hành viên có thể kết nối lại. +- `--class`, `--idle-timeout` và `--ttl` tinh chỉnh kích thước máy và thời hạn lease. + +Workflow smoke GitHub là `Mantis Discord Smoke`. Workflow GitHub trước và sau cho kịch bản thật đầu tiên là `Mantis Discord Status Reactions`. Nó chấp nhận: + +- `baseline_ref`: tham chiếu được kỳ vọng tái hiện hành vi chỉ queued. +- `candidate_ref`: tham chiếu được kỳ vọng hiển thị `queued -> thinking -> done`. + +Nó checkout tham chiếu harness workflow, build các worktree cơ sở và ứng viên riêng biệt, chạy `discord-status-reactions-tool-only` trên từng worktree và tải `baseline/`, `candidate/`, `comparison.json` cùng `mantis-report.md` lên dưới dạng hiện vật Actions. Nó cũng render HTML timeline của từng làn trong trình duyệt desktop Crabbox và xuất bản các ảnh chụp màn hình VNC đó bên cạnh các PNG timeline xác định được trong bình luận PR. Workflow build Crabbox CLI từ main của `openclaw/crabbox` để có thể dùng các cờ lease desktop/trình duyệt hiện tại trước khi bản phát hành nhị phân Crabbox tiếp theo được cắt. Bạn cũng có thể kích hoạt lượt chạy status-reactions trực tiếp từ bình luận PR: @@ -85,7 +102,7 @@ Bạn cũng có thể kích hoạt lượt chạy status-reactions trực tiếp @Mantis discord status reactions ``` -Bộ kích hoạt bình luận được cố ý giới hạn hẹp. Nó chỉ chạy trên bình luận pull request từ người dùng có quyền write, maintain hoặc admin, và chỉ nhận diện các yêu cầu reaction trạng thái của Discord. Theo mặc định, nó dùng ref cơ sở lỗi đã biết và SHA head của PR hiện tại làm ứng viên. Maintainer có thể ghi đè một trong hai ref: +Trigger qua bình luận được cố ý giới hạn hẹp. Nó chỉ chạy trên bình luận pull request từ người dùng có quyền write, maintain hoặc admin, và chỉ nhận diện các yêu cầu phản ứng trạng thái Discord. Theo mặc định, nó dùng tham chiếu cơ sở lỗi đã biết và SHA head hiện tại của PR làm ứng viên. Maintainer có thể ghi đè một trong hai tham chiếu: ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -98,44 +115,45 @@ Ví dụ lệnh ClawSweeper: @clawsweeper verify e2e discord ``` -Lệnh đầu tiên rõ ràng và tập trung vào kịch bản. Lệnh thứ hai về sau có thể ánh xạ PR hoặc issue tới các kịch bản Mantis được khuyến nghị từ nhãn, tệp đã thay đổi và phát hiện review của ClawSweeper. +Lệnh đầu tiên rõ ràng và tập trung vào kịch bản. Lệnh thứ hai sau này có thể ánh xạ một PR hoặc issue tới các kịch bản Mantis được khuyến nghị từ nhãn, tệp đã thay đổi và phát hiện review của ClawSweeper. -## Vòng đời chạy +## Vòng đời lượt chạy 1. Lấy thông tin xác thực. 2. Cấp phát hoặc tái sử dụng VM. -3. Chuẩn bị checkout sạch cho ref cơ sở. -4. Cài đặt dependency và chỉ build những gì kịch bản cần. -5. Khởi động OpenClaw Gateway con với thư mục trạng thái cô lập. -6. Cấu hình phương thức truyền tải trực tiếp, nhà cung cấp, mô hình và hồ sơ trình duyệt. -7. Chạy kịch bản và thu thập bằng chứng cơ sở. -8. Dừng gateway và giữ lại log. -9. Chuẩn bị ref ứng viên trong cùng VM. -10. Chạy cùng kịch bản và thu thập bằng chứng ứng viên. -11. So sánh kết quả oracle và bằng chứng trực quan. -12. Ghi Markdown, JSON, log, ảnh chụp màn hình và artifact trace tùy chọn. -13. Tải lên artifact GitHub Actions. -14. Đăng thông báo trạng thái ngắn gọn lên PR hoặc Discord. +3. Chuẩn bị hồ sơ desktop/trình duyệt khi kịch bản cần bằng chứng UI. +4. Chuẩn bị một checkout sạch cho tham chiếu cơ sở. +5. Cài đặt phụ thuộc và chỉ build những gì kịch bản cần. +6. Khởi động một OpenClaw Gateway con với thư mục trạng thái cô lập. +7. Cấu hình kênh truyền live, nhà cung cấp, mô hình và hồ sơ trình duyệt. +8. Chạy kịch bản và thu thập bằng chứng cơ sở. +9. Dừng gateway và giữ log. +10. Chuẩn bị tham chiếu ứng viên trong cùng VM. +11. Chạy cùng kịch bản và thu thập bằng chứng ứng viên. +12. So sánh kết quả oracle và bằng chứng trực quan. +13. Ghi Markdown, JSON, log, ảnh chụp màn hình và hiện vật trace tùy chọn. +14. Tải hiện vật GitHub Actions lên. +15. Đăng một thông báo trạng thái PR hoặc Discord ngắn gọn. -Kịch bản nên có khả năng thất bại theo hai cách khác nhau: +Kịch bản nên có thể thất bại theo hai cách khác nhau: -- **Lỗi được tái hiện**: cơ sở thất bại theo cách được kỳ vọng. +- **Đã tái hiện lỗi**: cơ sở thất bại theo cách được kỳ vọng. - **Lỗi harness**: thiết lập môi trường, thông tin xác thực, Discord API, trình duyệt hoặc nhà cung cấp thất bại trước khi oracle lỗi có ý nghĩa. -Báo cáo cuối cùng phải tách riêng các trường hợp này để maintainer không nhầm lẫn môi trường thiếu ổn định với hành vi sản phẩm. +Báo cáo cuối cùng phải tách riêng các trường hợp này để maintainer không nhầm môi trường chập chờn với hành vi sản phẩm. ## MVP Discord -Kịch bản đầu tiên nên nhắm tới reaction trạng thái Discord trong các kênh máy chủ nơi chế độ gửi trả lời nguồn là `message_tool_only`. +Kịch bản đầu tiên nên nhắm tới phản ứng trạng thái Discord trong kênh guild nơi chế độ gửi phản hồi nguồn là `message_tool_only`. Vì sao đây là hạt giống Mantis tốt: -- Nó hiển thị trong Discord dưới dạng reaction trên tin nhắn kích hoạt. -- Nó có oracle REST mạnh thông qua trạng thái reaction của tin nhắn Discord. -- Nó kiểm thử OpenClaw Gateway thật, xác thực bot Discord, điều phối tin nhắn, chế độ gửi trả lời nguồn, trạng thái reaction trạng thái và vòng đời lượt mô hình. +- Nó hiển thị trong Discord dưới dạng phản ứng trên tin nhắn kích hoạt. +- Nó có oracle REST mạnh thông qua trạng thái phản ứng tin nhắn Discord. +- Nó đi qua một OpenClaw Gateway thật, xác thực bot Discord, dispatch tin nhắn, chế độ gửi phản hồi nguồn, trạng thái phản ứng trạng thái và vòng đời lượt mô hình. - Nó đủ hẹp để giữ cho triển khai đầu tiên trung thực. -Hình dạng kịch bản kỳ vọng: +Dạng kịch bản kỳ vọng: ```yaml id: discord-status-reactions-tool-only @@ -166,9 +184,9 @@ evidence: screenshotMessageRow: true ``` -Bằng chứng cơ sở nên cho thấy reaction xác nhận queued nhưng không có chuyển tiếp vòng đời trong chế độ chỉ-tool. Bằng chứng ứng viên nên cho thấy reaction trạng thái vòng đời chạy khi `messages.statusReactions.enabled` được bật rõ ràng. +Bằng chứng cơ sở nên cho thấy phản ứng xác nhận queued nhưng không có chuyển tiếp vòng đời trong chế độ chỉ tool. Bằng chứng ứng viên nên cho thấy phản ứng trạng thái vòng đời chạy khi `messages.statusReactions.enabled` được đặt rõ ràng là true. -Lát cắt thực thi đầu tiên là kịch bản QA trực tiếp Discord dạng opt-in: +Lát cắt thực thi đầu tiên là kịch bản QA live Discord opt-in: ```bash pnpm openclaw qa discord \ @@ -180,24 +198,24 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Nó cấu hình SUT với xử lý máy chủ luôn bật, `visibleReplies: -"message_tool"`, `ackReaction: "👀"` và reaction trạng thái rõ ràng. Oracle thăm dò tin nhắn kích hoạt Discord thật và kỳ vọng chuỗi quan sát được `👀 -> 🤔 -> 👍`. Artifact bao gồm `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` và `discord-status-reactions-tool-only-timeline.png`. +Nó cấu hình SUT với xử lý guild luôn bật, `visibleReplies: +"message_tool"`, `ackReaction: "👀"` và phản ứng trạng thái rõ ràng. Oracle poll tin nhắn kích hoạt Discord thật và kỳ vọng chuỗi quan sát được `👀 -> 🤔 -> 👍`. Hiện vật bao gồm `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` và `discord-status-reactions-tool-only-timeline.png`. ## Các phần QA hiện có -Mantis nên xây dựng trên ngăn xếp QA riêng tư hiện có thay vì bắt đầu từ con số không: +Mantis nên xây dựng dựa trên ngăn xếp QA riêng hiện có thay vì bắt đầu từ số không: -- `pnpm openclaw qa discord` đã chạy một làn Discord trực tiếp với bot driver và SUT. -- Trình chạy phương thức truyền tải trực tiếp đã ghi báo cáo và artifact tin nhắn quan sát được dưới `.artifacts/qa-e2e/`. -- Lease thông tin xác thực Convex đã cung cấp quyền truy cập độc quyền vào thông tin xác thực phương thức truyền tải trực tiếp dùng chung. +- `pnpm openclaw qa discord` đã chạy một làn Discord live với bot driver và SUT. +- Trình chạy kênh truyền live đã ghi báo cáo và hiện vật tin nhắn quan sát được dưới `.artifacts/qa-e2e/`. +- Lease thông tin xác thực Convex đã cung cấp quyền truy cập độc quyền tới thông tin xác thực kênh truyền live dùng chung. - Dịch vụ điều khiển trình duyệt đã hỗ trợ ảnh chụp màn hình, snapshot, hồ sơ được quản lý headless và hồ sơ CDP từ xa. -- QA Lab đã có giao diện gỡ lỗi và bus cho kiểm thử theo hình dạng phương thức truyền tải. +- QA Lab đã có UI trình gỡ lỗi và bus cho kiểm thử có dạng kênh truyền. Triển khai Mantis đầu tiên có thể là một trình chạy trước/sau mỏng trên các phần này, cộng thêm một lớp bằng chứng trực quan. ## Mô hình bằng chứng -Mỗi lượt chạy ghi một thư mục artifact ổn định: +Mỗi lượt chạy ghi một thư mục hiện vật ổn định: ```text .artifacts/qa-e2e/mantis// @@ -217,65 +235,65 @@ Mỗi lượt chạy ghi một thư mục artifact ổn định: run.log ``` -`mantis-summary.json` nên là nguồn sự thật máy đọc được. Báo cáo Markdown dành cho bình luận PR và review của con người. +`mantis-summary.json` nên là nguồn sự thật đọc được bằng máy. Báo cáo Markdown dành cho bình luận PR và review của con người. Tóm tắt phải bao gồm: -- các ref và SHA đã kiểm thử -- phương thức truyền tải và id kịch bản +- các tham chiếu và SHA đã kiểm thử +- kênh truyền và id kịch bản - nhà cung cấp máy và id máy hoặc id lease -- nguồn thông tin xác thực không kèm giá trị secret +- nguồn thông tin xác thực không kèm giá trị bí mật - kết quả cơ sở - kết quả ứng viên - lỗi có được tái hiện trên cơ sở hay không - ứng viên có sửa được lỗi hay không -- đường dẫn artifact -- vấn đề thiết lập hoặc dọn dẹp đã được làm sạch +- đường dẫn hiện vật +- các vấn đề thiết lập hoặc dọn dẹp đã được khử nhạy cảm -Ảnh chụp màn hình là bằng chứng, không phải secret. Chúng vẫn cần kỷ luật biên tập lại: tên kênh riêng tư, tên người dùng hoặc nội dung tin nhắn có thể xuất hiện. Với PR công khai, ưu tiên liên kết artifact GitHub Actions thay vì ảnh nhúng cho tới khi câu chuyện biên tập lại mạnh hơn. +Ảnh chụp màn hình là bằng chứng, không phải bí mật. Tuy vậy vẫn cần kỷ luật biên tập che giấu: tên kênh riêng tư, tên người dùng hoặc nội dung tin nhắn có thể xuất hiện. Với PR công khai, ưu tiên liên kết hiện vật GitHub Actions hơn ảnh nhúng cho đến khi câu chuyện biên tập che giấu mạnh hơn. ## Trình duyệt và VNC Làn trình duyệt có hai chế độ: - **Tự động hóa headless**: mặc định cho CI. Chrome chạy với CDP được bật, và Playwright hoặc điều khiển trình duyệt OpenClaw chụp ảnh màn hình. -- **Cứu hộ VNC**: bật trên cùng VM khi đăng nhập, MFA, chống tự động hóa của Discord hoặc gỡ lỗi trực quan cần con người. +- **Cứu hộ VNC**: được bật trên cùng VM khi đăng nhập, MFA, chống tự động hóa của Discord hoặc gỡ lỗi trực quan cần con người. -Hồ sơ trình duyệt quan sát Discord nên đủ bền để tránh đăng nhập cho mỗi lượt chạy, nhưng được cô lập khỏi trạng thái trình duyệt cá nhân. Một hồ sơ thuộc về nhóm máy Mantis, không thuộc về laptop của nhà phát triển. +Hồ sơ trình duyệt quan sát Discord nên đủ bền vững để tránh phải đăng nhập cho mỗi lần chạy, nhưng phải tách biệt khỏi trạng thái trình duyệt cá nhân. Một hồ sơ thuộc về nhóm máy Mantis, không thuộc về laptop của nhà phát triển. -Khi Mantis bị kẹt, nó đăng thông báo trạng thái Discord với: +Khi Mantis bị kẹt, nó đăng một thông báo trạng thái Discord với: -- id lượt chạy +- id lần chạy - id kịch bản - nhà cung cấp máy - thư mục artifact - hướng dẫn kết nối VNC hoặc noVNC nếu có -- văn bản ngắn về điểm chặn +- văn bản ngắn mô tả điểm chặn -Triển khai riêng tư đầu tiên có thể đăng các thông báo này lên kênh operator hiện có và chuyển sang kênh Mantis chuyên dụng sau. +Triển khai riêng tư đầu tiên có thể đăng các thông báo này lên kênh điều phối hiện có và chuyển sang một kênh Mantis riêng sau. ## Máy -Mantis nên ưu tiên AWS thông qua Crabbox cho triển khai từ xa đầu tiên. Crabbox cho chúng ta máy đã được làm nóng, theo dõi lease, hydrate, log, kết quả và dọn dẹp. Nếu dung lượng AWS quá chậm hoặc không khả dụng, hãy thêm nhà cung cấp Hetzner phía sau cùng giao diện máy. +Mantis nên ưu tiên AWS thông qua Crabbox cho lần triển khai từ xa đầu tiên. Crabbox cung cấp cho chúng ta các máy đã được làm nóng sẵn, theo dõi thuê máy, cấp dữ liệu khởi tạo, nhật ký, kết quả và dọn dẹp. Nếu dung lượng AWS quá chậm hoặc không khả dụng, hãy thêm một nhà cung cấp Hetzner phía sau cùng giao diện máy. Yêu cầu VM tối thiểu: -- Linux có cài đặt Chrome hoặc Chromium hỗ trợ desktop +- Linux có bản cài đặt Chrome hoặc Chromium hỗ trợ desktop - quyền truy cập CDP cho tự động hóa trình duyệt - VNC hoặc noVNC để cứu hộ - Node 22 và pnpm -- checkout OpenClaw và cache dependency +- bản checkout OpenClaw và cache dependency - cache trình duyệt Playwright Chromium khi dùng Playwright -- đủ CPU và bộ nhớ cho một OpenClaw Gateway, một trình duyệt và một lượt chạy mô hình -- quyền truy cập outbound tới Discord, GitHub, nhà cung cấp mô hình và broker thông tin xác thực +- đủ CPU và bộ nhớ cho một OpenClaw Gateway, một trình duyệt và một lần chạy mô hình +- quyền truy cập đi ra tới Discord, GitHub, nhà cung cấp mô hình và broker thông tin xác thực -VM không nên giữ secret thô dài hạn bên ngoài các kho thông tin xác thực hoặc hồ sơ trình duyệt dự kiến. +VM không nên lưu các bí mật thô tồn tại lâu bên ngoài kho thông tin xác thực hoặc kho hồ sơ trình duyệt dự kiến. -## Secret +## Bí mật -Secret nằm trong secret của tổ chức hoặc repository GitHub cho lượt chạy từ xa, và trong tệp secret do operator kiểm soát cục bộ cho lượt chạy cục bộ. +Bí mật nằm trong bí mật GitHub cấp tổ chức hoặc repository cho các lần chạy từ xa, và trong một tệp bí mật cục bộ do operator kiểm soát cho các lần chạy cục bộ. -Tên secret được khuyến nghị: +Tên bí mật được khuyến nghị: - `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` @@ -283,30 +301,32 @@ Tên secret được khuyến nghị: - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` cho các lần tải artifact công khai lên GitHub +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` cho tải lên artifact GitHub công khai - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` +- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` +- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -Về dài hạn, nhóm thông tin đăng nhập Convex nên tiếp tục là nguồn thông thường cho thông tin đăng nhập truyền tải trực tiếp. Secret GitHub khởi tạo broker và các lane dự phòng. +Về lâu dài, pool thông tin xác thực Convex nên tiếp tục là nguồn thông thường cho thông tin xác thực transport trực tiếp. Bí mật GitHub khởi động broker và các lane dự phòng. Workflow phản ứng trạng thái Discord ánh xạ các bí mật Mantis Crabbox trở lại các biến môi trường `CRABBOX_COORDINATOR` và `CRABBOX_COORDINATOR_TOKEN` mà CLI Crabbox mong đợi. Các tên bí mật GitHub dạng `CRABBOX_*` thuần vẫn được chấp nhận như một phương án tương thích dự phòng. -Runner Mantis tuyệt đối không được in: +Runner Mantis không bao giờ được in: -- mã thông báo bot Discord -- khóa API của nhà cung cấp +- token bot Discord +- khóa API nhà cung cấp - cookie trình duyệt - nội dung hồ sơ xác thực - mật khẩu VNC -- payload thông tin đăng nhập thô +- payload thông tin xác thực thô -Các lần tải artifact công khai cũng nên biên tập siêu dữ liệu mục tiêu Discord như id bot, guild, kênh và tin nhắn. Workflow smoke GitHub bật `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` vì lý do này. +Tải lên artifact công khai cũng nên biên tập ẩn siêu dữ liệu mục tiêu Discord như id bot, guild, kênh và tin nhắn. Workflow smoke GitHub bật `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` vì lý do này. -Nếu một mã thông báo vô tình bị dán vào issue, PR, cuộc trò chuyện hoặc log, hãy xoay vòng mã đó sau khi secret mới đã được lưu trữ. +Nếu một token bị dán nhầm vào issue, PR, chat hoặc nhật ký, hãy xoay vòng token đó sau khi bí mật mới đã được lưu. -## Artifact GitHub và bình luận PR +## Artifact GitHub Và Bình Luận PR -Các workflow Mantis nên tải toàn bộ gói bằng chứng lên dưới dạng artifact Actions ngắn hạn. Khi workflow được chạy cho báo cáo lỗi hoặc PR sửa lỗi, workflow cũng nên xuất bản các ảnh chụp màn hình PNG đã biên tập lên nhánh `qa-artifacts` và cập nhật hoặc chèn một bình luận trên lỗi hoặc PR sửa lỗi đó với ảnh chụp màn hình trước/sau nhúng trực tiếp. Không đăng bằng chứng chính chỉ trên một PR tự động hóa QA chung. Log thô, tin nhắn quan sát được và các bằng chứng cồng kềnh khác nằm trong artifact Actions. +Các workflow Mantis nên tải lên toàn bộ gói bằng chứng dưới dạng artifact Actions tồn tại ngắn hạn. Khi workflow được chạy cho một báo cáo lỗi hoặc PR sửa lỗi, nó cũng nên phát hành các ảnh chụp màn hình PNG đã biên tập ẩn lên nhánh `qa-artifacts` và upsert một bình luận trên lỗi hoặc PR sửa lỗi đó với ảnh chụp trước/sau hiển thị trực tiếp. Không đăng bằng chứng chính chỉ trên một PR tự động hóa QA chung. Nhật ký thô, tin nhắn đã quan sát và bằng chứng cồng kềnh khác nằm trong artifact Actions. -Các workflow production nên đăng các bình luận đó bằng GitHub App Mantis, không phải bằng `github-actions[bot]`. Lưu id ứng dụng và khóa riêng tư dưới dạng secret GitHub Actions `MANTIS_GITHUB_APP_ID` và `MANTIS_GITHUB_APP_PRIVATE_KEY`. Workflow sử dụng một marker ẩn làm khóa cập nhật hoặc chèn, cập nhật bình luận đó khi mã thông báo có thể chỉnh sửa bình luận, và tạo một bình luận mới do Mantis sở hữu khi không thể chỉnh sửa marker cũ do bot sở hữu. +Các workflow production nên đăng những bình luận đó bằng Mantis GitHub App, không dùng `github-actions[bot]`. Lưu app id và khóa riêng dưới dạng bí mật GitHub Actions `MANTIS_GITHUB_APP_ID` và `MANTIS_GITHUB_APP_PRIVATE_KEY`. Workflow dùng một marker ẩn làm khóa upsert, cập nhật bình luận đó khi token có thể chỉnh sửa nó, và tạo một bình luận mới thuộc sở hữu của Mantis khi một marker cũ thuộc sở hữu của bot không thể chỉnh sửa được. Bình luận PR nên ngắn gọn và trực quan: @@ -328,60 +348,60 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Khi lần chạy thất bại vì harness thất bại, bình luận phải nói như vậy thay vì ngụ ý rằng ứng viên thất bại. +Khi lần chạy thất bại vì harness thất bại, bình luận phải nói rõ điều đó thay vì ngụ ý rằng candidate thất bại. -## Ghi chú triển khai riêng tư +## Ghi Chú Triển Khai Riêng Tư -Một triển khai riêng tư có thể đã có ứng dụng Discord Mantis. Tái sử dụng ứng dụng đó thay vì tạo ứng dụng khác khi ứng dụng có quyền bot phù hợp và có thể được xoay vòng an toàn. +Một triển khai riêng tư có thể đã có ứng dụng Discord Mantis. Tái sử dụng ứng dụng đó thay vì tạo app khác khi nó có đúng quyền bot và có thể xoay vòng an toàn. -Đặt kênh thông báo người vận hành ban đầu thông qua secret hoặc cấu hình triển khai. Ban đầu kênh đó có thể trỏ tới một kênh maintainer hoặc vận hành hiện có, rồi chuyển sang kênh Mantis chuyên dụng sau khi kênh đó tồn tại. +Đặt kênh thông báo operator ban đầu thông qua bí mật hoặc cấu hình triển khai. Ban đầu nó có thể trỏ tới kênh maintainer hoặc vận hành hiện có, rồi chuyển sang một kênh Mantis riêng khi kênh đó tồn tại. -Không đặt id guild, id kênh, mã thông báo bot, cookie trình duyệt hoặc mật khẩu VNC trong tài liệu này. Lưu chúng trong secret GitHub, broker thông tin đăng nhập hoặc kho secret cục bộ của người vận hành. +Không đưa guild id, channel id, token bot, cookie trình duyệt hoặc mật khẩu VNC vào tài liệu này. Lưu chúng trong bí mật GitHub, broker thông tin xác thực hoặc kho bí mật cục bộ của operator. -## Thêm một kịch bản +## Thêm Một Kịch Bản Một kịch bản Mantis nên khai báo: - id và tiêu đề -- phương thức truyền tải -- thông tin đăng nhập bắt buộc +- transport +- thông tin xác thực bắt buộc - chính sách ref baseline -- chính sách ref ứng viên +- chính sách ref candidate - bản vá cấu hình OpenClaw - các bước thiết lập -- tác nhân kích thích -- oracle baseline kỳ vọng -- oracle ứng viên kỳ vọng -- mục tiêu chụp trực quan -- ngân sách thời gian chờ +- kích thích +- oracle baseline dự kiến +- oracle candidate dự kiến +- mục tiêu chụp hình ảnh +- ngân sách timeout - các bước dọn dẹp -Các kịch bản nên ưu tiên các oracle nhỏ, có kiểu: +Các kịch bản nên ưu tiên oracle nhỏ, có kiểu: -- trạng thái reaction Discord cho lỗi reaction +- trạng thái phản ứng Discord cho lỗi phản ứng - tham chiếu tin nhắn Discord cho lỗi phân luồng -- ts thread Slack và trạng thái API reaction cho lỗi Slack -- id tin nhắn email và header cho lỗi email +- thread ts Slack và trạng thái API phản ứng cho lỗi Slack +- id và header tin nhắn email cho lỗi email - ảnh chụp màn hình trình duyệt khi UI là đối tượng quan sát đáng tin cậy duy nhất -Kiểm tra thị giác nên mang tính bổ sung. Nếu API nền tảng có thể chứng minh lỗi, hãy dùng API làm oracle đạt/không đạt và giữ ảnh chụp màn hình để con người thêm tin tưởng. +Kiểm tra bằng thị giác nên mang tính bổ sung. Nếu API nền tảng có thể chứng minh lỗi, hãy dùng API làm oracle đạt/trượt và giữ ảnh chụp màn hình để tăng độ tin cậy cho con người. -## Mở rộng nhà cung cấp +## Mở Rộng Nhà Cung Cấp Sau Discord, cùng runner đó có thể thêm: -- Slack: reaction, thread, đề cập ứng dụng, modal, tải tệp lên. -- Email: xác thực Gmail và phân luồng tin nhắn bằng `gog` khi connector là chưa đủ. -- WhatsApp: đăng nhập QR, nhận dạng lại, gửi tin nhắn, phương tiện, reaction. -- Telegram: kiểm soát đề cập trong nhóm, lệnh, reaction nơi có sẵn. -- Matrix: phòng mã hóa, quan hệ thread hoặc trả lời, tiếp tục sau khởi động lại. +- Slack: phản ứng, luồng, nhắc đến app, modal, tải tệp lên. +- Email: xác thực Gmail và phân luồng tin nhắn bằng `gog` khi connector chưa đủ. +- WhatsApp: đăng nhập QR, nhận diện lại, gửi tin nhắn, phương tiện, phản ứng. +- Telegram: chặn theo nhắc đến nhóm, lệnh, phản ứng khi có. +- Matrix: phòng mã hóa, quan hệ luồng hoặc trả lời, tiếp tục sau khởi động lại. -Mỗi phương thức truyền tải nên có một kịch bản smoke rẻ và một hoặc nhiều kịch bản theo lớp lỗi. Các kịch bản trực quan tốn kém nên luôn là tùy chọn bật rõ ràng. +Mỗi transport nên có một kịch bản smoke rẻ và một hoặc nhiều kịch bản theo lớp lỗi. Các kịch bản trực quan tốn kém nên giữ ở chế độ chọn bật. -## Câu hỏi mở +## Câu Hỏi Mở - Bot Discord nào nên là driver, và bot nào nên là SUT, khi bot Mantis hiện có được tái sử dụng? - Đăng nhập trình duyệt quan sát nên dùng tài khoản Discord của con người, tài khoản kiểm thử, hay chỉ bằng chứng REST mà bot có thể đọc cho giai đoạn đầu? -- GitHub nên lưu giữ artifact Mantis cho PR trong bao lâu? -- Khi nào ClawSweeper nên tự động khuyến nghị Mantis thay vì chờ lệnh maintainer? -- Ảnh chụp màn hình có nên được biên tập hoặc cắt trước khi tải lên cho các PR công khai không? +- GitHub nên giữ artifact Mantis cho PR trong bao lâu? +- Khi nào ClawSweeper nên tự động đề xuất Mantis thay vì chờ lệnh từ maintainer? +- Ảnh chụp màn hình có nên được biên tập ẩn hoặc cắt trước khi tải lên cho PR công khai không? diff --git a/docs/vi/concepts/progress-drafts.md b/docs/vi/concepts/progress-drafts.md index 4478670f9..a5f976f91 100644 --- a/docs/vi/concepts/progress-drafts.md +++ b/docs/vi/concepts/progress-drafts.md @@ -1,36 +1,36 @@ --- read_when: - - Cấu hình các cập nhật tiến độ hiển thị cho các lượt trò chuyện chạy lâu - - Chọn giữa các chế độ truyền phát từng phần, theo khối và tiến trình - - Giải thích cách OpenClaw cập nhật một tin nhắn kênh trong khi công việc đang được xử lý - - Khắc phục sự cố với bản nháp tiến trình, thông báo tiến trình độc lập hoặc phương án dự phòng khi hoàn tất -summary: 'Bản nháp tiến độ: một thông báo công việc đang tiến hành hiển thị duy nhất được cập nhật trong khi tác tử chạy' -title: Các bản nháp tiến độ + - Cấu hình các bản cập nhật tiến độ hiển thị cho các lượt trò chuyện kéo dài + - Chọn giữa các chế độ truyền phát một phần, theo khối và theo tiến độ + - Giải thích cách OpenClaw cập nhật một tin nhắn kênh trong khi công việc đang diễn ra + - Khắc phục sự cố bản nháp tiến trình, thông báo tiến trình độc lập hoặc phương án dự phòng khi hoàn tất +summary: 'Bản nháp tiến trình: một thông báo công việc đang thực hiện hiển thị rõ và cập nhật trong khi một tác nhân đang chạy' +title: Bản nháp tiến độ x-i18n: - generated_at: "2026-05-03T21:30:28Z" + generated_at: "2026-05-04T02:23:19Z" model: gpt-5.5 provider: openai - source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c + source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe source_path: concepts/progress-drafts.md workflow: 16 --- -Các bản nháp tiến độ giúp các lượt agent chạy lâu tạo cảm giác sống động trong cuộc trò chuyện mà không biến cuộc hội thoại thành một chồng phản hồi trạng thái tạm thời. +Bản nháp tiến trình giúp các lượt tác nhân chạy lâu tạo cảm giác đang diễn ra trong chat mà không biến cuộc hội thoại thành một chồng phản hồi trạng thái tạm thời. -Khi bật bản nháp tiến độ, OpenClaw tạo một thông báo công việc đang xử lý hiển thị được, cập nhật thông báo đó trong khi agent đọc, lập kế hoạch, gọi công cụ hoặc chờ phê duyệt, rồi chuyển bản nháp đó thành câu trả lời cuối cùng khi kênh có thể làm vậy một cách an toàn. +Khi bật bản nháp tiến trình, OpenClaw chỉ tạo một thông báo công việc đang thực hiện hiển thị sau khi lượt xử lý chứng minh rằng nó đang làm việc thật, cập nhật thông báo đó trong lúc tác nhân đọc, lập kế hoạch, gọi công cụ hoặc chờ phê duyệt, rồi chuyển bản nháp đó thành câu trả lời cuối cùng khi kênh có thể làm điều đó một cách an toàn. ```text -Shelling -- reading recent channel context -- checking matching issues -- preparing reply +Shelling... +📖 Read: from docs/concepts/progress-drafts.md +🔎 Web Search: for "discord edit message" +🛠️ Exec: run tests ``` -Dùng bản nháp tiến độ khi bạn muốn một thông báo trạng thái gọn gàng trong lúc thực hiện công việc dùng nhiều công cụ và câu trả lời cuối cùng khi lượt hoàn tất. +Dùng bản nháp tiến trình khi bạn muốn có một thông báo trạng thái gọn gàng trong quá trình làm việc nặng về công cụ và câu trả lời cuối cùng khi lượt xử lý hoàn tất. ## Bắt đầu nhanh -Bật bản nháp tiến độ cho từng kênh bằng `streaming.mode: "progress"`: +Bật bản nháp tiến trình theo từng kênh với `streaming.mode: "progress"`: ```json5 { @@ -44,63 +44,64 @@ Bật bản nháp tiến độ cho từng kênh bằng `streaming.mode: "progres } ``` -Như vậy thường là đủ. OpenClaw sẽ chọn một nhãn một từ tự động, thêm các dòng tiến độ ngắn gọn trong khi có công việc hữu ích diễn ra, và chặn các thông báo tiến độ độc lập bị trùng lặp cho lượt đó. +Thường như vậy là đủ. OpenClaw sẽ chọn một nhãn một từ tự động, chờ đến khi công việc kéo dài ít nhất năm giây hoặc phát ra sự kiện công việc thứ hai, thêm các dòng tiến trình gọn khi có công việc hữu ích diễn ra, và chặn phần tán gẫu tiến trình độc lập bị trùng lặp cho lượt đó. -## Người dùng thấy gì +## Người dùng nhìn thấy gì -Một bản nháp tiến độ có hai phần: +Một bản nháp tiến trình có hai phần: -| Phần | Mục đích | -| -------------- | ----------------------------------------------------------------- | -| Nhãn | Một tiêu đề ngắn như `Thinking` hoặc `Shelling`. | -| Dòng tiến độ | Các cập nhật chạy ngắn gọn như lời gọi công cụ, bước tác vụ hoặc phê duyệt. | +| Phần | Mục đích | +| -------------- | --------------------------------------------------------------------------- | +| Nhãn | Một tiêu đề ngắn như `Thinking...` hoặc `Shelling...`. | +| Dòng tiến trình | Các cập nhật chạy gọn, dùng cùng nhãn công cụ và biểu tượng như đầu ra chi tiết. | -Nhãn xuất hiện ngay khi agent bắt đầu trả lời. Các dòng tiến độ chỉ được thêm khi agent phát ra các cập nhật công việc hữu ích. Câu trả lời cuối cùng thay thế bản nháp khi có thể; nếu không, OpenClaw gửi câu trả lời cuối cùng theo cách thông thường và dọn dẹp hoặc ngừng cập nhật bản nháp tùy theo phương thức vận chuyển của kênh. +Nhãn xuất hiện sau khi tác nhân bắt đầu công việc có ý nghĩa và hoặc vẫn bận trong năm giây, hoặc phát ra sự kiện công việc thứ hai. Các phản hồi chỉ có văn bản thuần không hiển thị bản nháp tiến trình. Dòng tiến trình chỉ được thêm khi tác nhân phát ra các cập nhật công việc hữu ích, ví dụ `🛠️ Exec`, `🔎 Web Search`, hoặc `✍️ Write: to /tmp/file`. Theo mặc định, chúng dùng cùng chế độ giải thích gọn như `/verbose`; đặt `agents.defaults.toolProgressDetail: "raw"` khi gỡ lỗi và bạn cũng muốn nối thêm lệnh/chi tiết thô. +Câu trả lời cuối cùng thay thế bản nháp khi có thể; nếu không, OpenClaw gửi câu trả lời cuối cùng như bình thường và dọn dẹp hoặc dừng cập nhật bản nháp theo cơ chế truyền tải của kênh. -## Chọn chế độ +## Chọn một chế độ -`channels..streaming.mode` kiểm soát hành vi đang xử lý hiển thị được: +`channels..streaming.mode` kiểm soát hành vi đang thực hiện hiển thị: -| Chế độ | Phù hợp nhất cho | Nội dung xuất hiện trong chat | -| ---------- | -------------------------------- | -------------------------------------------------- | -| `off` | Kênh yên tĩnh | Chỉ câu trả lời cuối cùng. | -| `partial` | Theo dõi văn bản câu trả lời xuất hiện | Một bản nháp được chỉnh sửa với văn bản câu trả lời mới nhất. | -| `block` | Các đoạn xem trước câu trả lời lớn hơn | Một bản xem trước được cập nhật hoặc nối thêm theo các đoạn lớn hơn. | -| `progress` | Các lượt dùng nhiều công cụ hoặc chạy lâu | Một bản nháp trạng thái, rồi câu trả lời cuối cùng. | +| Chế độ | Phù hợp nhất cho | Nội dung xuất hiện trong chat | +| ---------- | -------------------------------- | ------------------------------------------------- | +| `off` | Các kênh yên tĩnh | Chỉ có câu trả lời cuối cùng. | +| `partial` | Theo dõi văn bản câu trả lời xuất hiện | Một bản nháp được chỉnh sửa bằng văn bản câu trả lời mới nhất. | +| `block` | Các đoạn xem trước câu trả lời lớn hơn | Một bản xem trước được cập nhật hoặc nối thêm theo các đoạn lớn hơn. | +| `progress` | Các lượt nặng về công cụ hoặc chạy lâu | Một bản nháp trạng thái, rồi đến câu trả lời cuối cùng. | -Chọn `progress` khi người dùng quan tâm nhiều hơn đến “điều gì đang diễn ra” thay vì xem văn bản câu trả lời stream từng token. +Chọn `progress` khi người dùng quan tâm đến "điều gì đang diễn ra" hơn là xem văn bản câu trả lời phát trực tuyến từng token. -Chọn `partial` khi chính câu trả lời là tín hiệu tiến độ. +Chọn `partial` khi bản thân câu trả lời là tín hiệu tiến trình. -Chọn `block` khi bạn muốn cập nhật bản nháp xem trước theo các đoạn văn bản lớn hơn. Trên Discord và Telegram, `streaming.mode: "block"` vẫn là stream xem trước, không phải phân phối block thông thường. Dùng `streaming.block.enabled` hoặc `blockStreaming` cũ khi bạn muốn phản hồi block thông thường. +Chọn `block` khi bạn muốn cập nhật bản xem trước nháp theo các đoạn văn bản lớn hơn. Trên Discord và Telegram, `streaming.mode: "block"` vẫn là phát trực tuyến bản xem trước, không phải phát theo block thông thường. Dùng `streaming.block.enabled` hoặc `blockStreaming` cũ khi bạn muốn phản hồi block thông thường. ## Cấu hình nhãn -Nhãn tiến độ nằm dưới `channels..streaming.progress`. +Nhãn tiến trình nằm trong `channels..streaming.progress`. -Nhãn mặc định là `auto`, chọn từ nhóm nhãn một từ tích hợp sẵn của OpenClaw: +Nhãn mặc định là `auto`, chọn từ nhóm nhãn tích hợp sẵn của OpenClaw dạng một từ kèm dấu ba chấm: ```text -Thinking -Shelling -Scuttling -Clawing -Pinching -Molting -Bubbling -Tiding -Reefing -Cracking -Sifting -Brining -Nautiling -Krilling -Barnacling -Lobstering -Tidepooling -Pearling -Snapping -Surfacing +Thinking... +Shelling... +Scuttling... +Clawing... +Pinching... +Molting... +Bubbling... +Tiding... +Reefing... +Cracking... +Sifting... +Brining... +Nautiling... +Krilling... +Barnacling... +Lobstering... +Tidepooling... +Pearling... +Snapping... +Surfacing... ``` Dùng một nhãn cố định: @@ -138,7 +139,7 @@ Dùng nhóm nhãn tự động của riêng bạn: } ``` -Ẩn nhãn và chỉ hiển thị các dòng tiến độ: +Ẩn nhãn và chỉ hiển thị các dòng tiến trình: ```json5 { @@ -155,9 +156,30 @@ Dùng nhóm nhãn tự động của riêng bạn: } ``` -## Kiểm soát dòng tiến độ +## Kiểm soát dòng tiến trình -Các dòng tiến độ được bật mặc định trong chế độ tiến độ. Chúng đến từ các sự kiện chạy thực: bắt đầu công cụ, cập nhật mục, kế hoạch tác vụ, phê duyệt, đầu ra lệnh, tóm tắt bản vá và hoạt động agent tương tự. +Các dòng tiến trình được bật theo mặc định trong chế độ tiến trình. Chúng đến từ các sự kiện chạy thật: công cụ bắt đầu, cập nhật mục, kế hoạch tác vụ, phê duyệt, đầu ra lệnh, tóm tắt bản vá và hoạt động tương tự của tác nhân. + +OpenClaw dùng cùng bộ định dạng cho bản nháp tiến trình và `/verbose`: + +```json5 +{ + agents: { + defaults: { + toolProgressDetail: "explain", // explain | raw + }, + }, +} +``` + +`"explain"` là mặc định và giữ bản nháp ổn định với các nhãn ngắn gọn như `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` nối thêm lệnh/chi tiết bên dưới khi có, hữu ích khi gỡ lỗi nhưng ồn hơn trong chat. + +Ví dụ, cùng một lệnh sẽ hiển thị khác nhau tùy vào chế độ chi tiết: + +| Chế độ | Dòng tiến trình | +| --------- | -------------------------------------------------------------------- | +| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` | +| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` | Giới hạn số dòng còn hiển thị: @@ -176,7 +198,7 @@ Giới hạn số dòng còn hiển thị: } ``` -Giữ bản nháp tiến độ duy nhất nhưng ẩn các dòng công cụ và tác vụ: +Giữ một bản nháp tiến trình duy nhất nhưng ẩn các dòng công cụ và tác vụ: ```json5 { @@ -193,58 +215,58 @@ Giữ bản nháp tiến độ duy nhất nhưng ẩn các dòng công cụ và } ``` -Với `toolProgress: false`, OpenClaw vẫn chặn các thông báo tiến độ công cụ độc lập cũ hơn cho lượt đó. Kênh vẫn yên tĩnh về mặt hiển thị cho đến câu trả lời cuối cùng, ngoại trừ nhãn nếu có cấu hình. +Với `toolProgress: false`, OpenClaw vẫn chặn các thông báo tiến trình công cụ độc lập cũ hơn cho lượt đó. Kênh vẫn yên tĩnh về mặt hiển thị cho đến câu trả lời cuối cùng, ngoại trừ nhãn nếu có cấu hình. -## Hành vi kênh +## Hành vi theo kênh -Mỗi kênh dùng phương thức vận chuyển sạch nhất mà nó hỗ trợ: +Mỗi kênh dùng cơ chế truyền tải gọn nhất mà nó hỗ trợ: -| Kênh | Phương thức vận chuyển tiến độ | Ghi chú | +| Kênh | Cơ chế truyền tải tiến trình | Ghi chú | | --------------- | -------------------------------------- | --------------------------------------------------------------------- | -| Discord | Gửi một thông báo, rồi chỉnh sửa nó. | Văn bản cuối cùng được chỉnh sửa tại chỗ khi vừa trong một thông báo xem trước an toàn. | -| Matrix | Gửi một sự kiện, rồi chỉnh sửa nó. | Cấu hình streaming cấp tài khoản kiểm soát các bản nháp cấp tài khoản. | -| Microsoft Teams | Stream Teams gốc trong chat cá nhân. | `streaming.mode: "block"` ánh xạ tới phân phối block của Teams. | -| Slack | Stream gốc hoặc bài đăng bản nháp có thể chỉnh sửa. | Tính khả dụng của luồng ảnh hưởng đến việc có thể dùng streaming gốc hay không. | -| Telegram | Gửi một thông báo, rồi chỉnh sửa nó. | Các bản nháp hiển thị cũ hơn có thể được thay thế để dấu thời gian cuối cùng vẫn hữu ích. | -| Mattermost | Bài đăng bản nháp có thể chỉnh sửa. | Hoạt động công cụ được gộp vào cùng bài đăng kiểu bản nháp. | +| Discord | Gửi một thông báo, rồi chỉnh sửa thông báo đó. | Văn bản cuối cùng được chỉnh sửa tại chỗ khi vừa một thông báo xem trước an toàn. | +| Matrix | Gửi một sự kiện, rồi chỉnh sửa sự kiện đó. | Cấu hình phát trực tuyến cấp tài khoản kiểm soát bản nháp cấp tài khoản. | +| Microsoft Teams | Luồng Teams gốc trong chat cá nhân. | `streaming.mode: "block"` ánh xạ tới phát theo block của Teams. | +| Slack | Luồng gốc hoặc bài đăng nháp có thể chỉnh sửa. | Tình trạng có thread ảnh hưởng đến việc có thể dùng phát trực tuyến gốc hay không. | +| Telegram | Gửi một thông báo, rồi chỉnh sửa thông báo đó. | Các bản nháp hiển thị cũ hơn có thể được thay thế để dấu thời gian cuối cùng vẫn hữu ích. | +| Mattermost | Bài đăng nháp có thể chỉnh sửa. | Hoạt động công cụ được gộp vào cùng bài đăng kiểu bản nháp. | -Các kênh không có hỗ trợ chỉnh sửa an toàn thường quay về chỉ báo đang nhập hoặc chỉ phân phối câu trả lời cuối cùng. +Các kênh không có hỗ trợ chỉnh sửa an toàn thường quay về chỉ báo đang nhập hoặc chỉ gửi câu trả lời cuối cùng. ## Hoàn tất -Khi câu trả lời cuối cùng đã sẵn sàng, OpenClaw cố giữ cuộc trò chuyện gọn gàng: +Khi câu trả lời cuối cùng đã sẵn sàng, OpenClaw cố giữ chat gọn gàng: - Nếu bản nháp có thể an toàn trở thành câu trả lời cuối cùng, OpenClaw chỉnh sửa nó tại chỗ. -- Nếu kênh dùng streaming tiến độ gốc, OpenClaw hoàn tất stream đó khi phương thức vận chuyển gốc chấp nhận văn bản cuối cùng. -- Nếu câu trả lời cuối cùng có phương tiện, lời nhắc phê duyệt, mục tiêu trả lời rõ ràng, quá nhiều đoạn, hoặc chỉnh sửa/gửi thất bại, OpenClaw gửi câu trả lời cuối cùng qua đường phân phối kênh thông thường. +- Nếu kênh dùng phát trực tuyến tiến trình gốc, OpenClaw hoàn tất luồng đó khi cơ chế truyền tải gốc chấp nhận văn bản cuối cùng. +- Nếu câu trả lời cuối cùng có phương tiện, lời nhắc phê duyệt, đích trả lời rõ ràng, quá nhiều đoạn, hoặc chỉnh sửa/gửi thất bại, OpenClaw gửi câu trả lời cuối cùng qua đường gửi kênh thông thường. -Đường dự phòng này là có chủ đích. Tốt hơn là gửi một câu trả lời cuối cùng mới thay vì làm mất văn bản, gắn nhầm luồng trả lời, hoặc ghi đè bản nháp bằng một payload mà kênh không thể biểu diễn an toàn. +Đường dự phòng là có chủ đích. Gửi một câu trả lời cuối cùng mới tốt hơn là mất văn bản, đưa phản hồi vào sai thread, hoặc ghi đè bản nháp bằng một tải trọng mà kênh không thể biểu diễn an toàn. ## Khắc phục sự cố **Tôi chỉ thấy câu trả lời cuối cùng.** -Kiểm tra rằng `channels..streaming.mode` được đặt thành `progress` cho tài khoản hoặc kênh đã xử lý thông báo. Một số đường nhóm hoặc trích dẫn-trả lời có thể tắt xem trước bản nháp cho một lượt khi kênh không thể chỉnh sửa đúng thông báo một cách an toàn. +Kiểm tra rằng `channels..streaming.mode` được đặt thành `progress` cho tài khoản hoặc kênh đã xử lý thông báo. Một số đường dẫn nhóm hoặc trả lời trích dẫn có thể tắt xem trước bản nháp cho một lượt khi kênh không thể chỉnh sửa an toàn đúng thông báo. **Tôi thấy nhãn nhưng không có dòng công cụ.** -Kiểm tra `streaming.progress.toolProgress`. Nếu nó là `false`, OpenClaw giữ hành vi một bản nháp duy nhất nhưng ẩn các dòng tiến độ công cụ và tác vụ. +Kiểm tra `streaming.progress.toolProgress`. Nếu là `false`, OpenClaw giữ hành vi một bản nháp duy nhất nhưng ẩn các dòng tiến trình công cụ và tác vụ. -**Tôi thấy một thông báo cuối cùng mới thay vì một bản nháp đã chỉnh sửa.** +**Tôi thấy một thông báo cuối cùng mới thay vì bản nháp được chỉnh sửa.** -Đó là dự phòng an toàn. Điều này có thể xảy ra với phản hồi có phương tiện, câu trả lời dài, mục tiêu trả lời rõ ràng, bản nháp Telegram cũ, thiếu mục tiêu luồng Slack, thông báo xem trước đã bị xóa hoặc hoàn tất stream gốc thất bại. +Đó là cơ chế dự phòng an toàn. Điều này có thể xảy ra với phản hồi có phương tiện, câu trả lời dài, đích trả lời rõ ràng, bản nháp Telegram cũ, thiếu đích thread Slack, thông báo xem trước đã bị xóa, hoặc hoàn tất luồng gốc thất bại. -**Tôi vẫn thấy các thông báo tiến độ độc lập.** +**Tôi vẫn thấy các thông báo tiến trình độc lập.** -Chế độ tiến độ chặn các thông báo tiến độ công cụ độc lập mặc định khi có một bản nháp đang hoạt động. Nếu thông báo độc lập vẫn xuất hiện, hãy xác minh rằng lượt đó thực sự đang dùng chế độ tiến độ chứ không phải `streaming.mode: "off"` hoặc một đường kênh không thể tạo bản nháp cho thông báo đó. +Chế độ tiến trình chặn các thông báo tiến trình công cụ độc lập mặc định khi có bản nháp đang hoạt động. Nếu thông báo độc lập vẫn xuất hiện, hãy xác minh rằng lượt xử lý thực sự đang dùng chế độ tiến trình chứ không phải `streaming.mode: "off"` hoặc một đường dẫn kênh không thể tạo bản nháp cho thông báo đó. **Teams hoạt động khác Discord hoặc Telegram.** -Microsoft Teams dùng stream gốc trong chat cá nhân thay vì phương thức vận chuyển xem trước gửi-và-chỉnh-sửa chung. Teams cũng coi `streaming.mode: "block"` là phân phối block của Teams vì nó không có cùng chế độ block xem trước bản nháp được Discord và Telegram dùng. +Microsoft Teams dùng một luồng gốc trong chat cá nhân thay vì cơ chế truyền tải xem trước gửi-và-chỉnh-sửa chung. Teams cũng xem `streaming.mode: "block"` là phát theo block của Teams vì nó không có cùng chế độ block xem trước nháp được Discord và Telegram dùng. ## Liên quan -- [Streaming và chia đoạn](/vi/concepts/streaming) +- [Phát trực tuyến và chia đoạn](/vi/concepts/streaming) - [Thông báo](/vi/concepts/messages) - [Cấu hình kênh](/vi/gateway/config-channels) - [Discord](/vi/channels/discord) diff --git a/docs/vi/concepts/qa-e2e-automation.md b/docs/vi/concepts/qa-e2e-automation.md index 1e87b2078..82f3ea2b9 100644 --- a/docs/vi/concepts/qa-e2e-automation.md +++ b/docs/vi/concepts/qa-e2e-automation.md @@ -1,67 +1,67 @@ --- read_when: - Hiểu cách ngăn xếp QA phối hợp với nhau - - Mở rộng qa-lab, qa-channel hoặc bộ điều hợp truyền tải - - Thêm các kịch bản đảm bảo chất lượng dựa trên kho lưu trữ - - Xây dựng tự động hóa QA sát thực tế hơn xoay quanh bảng điều khiển Gateway -summary: 'Tổng quan về ngăn xếp QA: qa-lab, qa-channel, các kịch bản dựa trên kho lưu trữ, các luồng truyền tải trực tiếp, bộ điều hợp truyền tải và báo cáo.' + - Mở rộng qa-lab, qa-channel hoặc một bộ điều hợp truyền tải + - Thêm các kịch bản QA dựa trên kho mã nguồn + - Xây dựng tự động hóa QA có độ chân thực cao hơn xoay quanh bảng điều khiển Gateway +summary: 'Tổng quan về ngăn xếp QA: qa-lab, qa-channel, các kịch bản dựa trên kho mã, các làn truyền tải trực tiếp, bộ chuyển đổi truyền tải và báo cáo.' title: Tổng quan về QA x-i18n: - generated_at: "2026-05-03T21:30:28Z" + generated_at: "2026-05-04T02:23:28Z" model: gpt-5.5 provider: openai - source_hash: 6a1446fddb00855634d34662a0a47be1e5054a9e7bfed5bc9ae21185d87094d8 + source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba source_path: concepts/qa-e2e-automation.md workflow: 16 --- -Ngăn xếp QA riêng tư được thiết kế để kiểm thử OpenClaw theo cách thực tế hơn, -mang hình dạng kênh hơn so với một kiểm thử đơn vị đơn lẻ. +Ngăn xếp QA riêng tư nhằm kiểm thử OpenClaw theo cách thực tế hơn, giống hình dạng kênh hơn so với một bài kiểm thử đơn vị đơn lẻ. -Các phần hiện tại: +Các thành phần hiện tại: -- `extensions/qa-channel`: kênh tin nhắn tổng hợp với các bề mặt DM, kênh, luồng, +- `extensions/qa-channel`: kênh tin nhắn tổng hợp với các bề mặt DM, kênh, chuỗi thảo luận, phản ứng, chỉnh sửa và xóa. -- `extensions/qa-lab`: giao diện trình gỡ lỗi và bus QA để quan sát transcript, +- `extensions/qa-lab`: giao diện gỡ lỗi và bus QA để quan sát bản ghi hội thoại, chèn tin nhắn đến và xuất báo cáo Markdown. -- `extensions/qa-matrix`, các Plugin runner trong tương lai: các bộ điều hợp transport trực tiếp - điều khiển một kênh thật bên trong một Gateway QA con. -- `qa/`: tài sản seed do repo hậu thuẫn cho tác vụ khởi động và các kịch bản QA - baseline. +- `extensions/qa-matrix`, các runner Plugin trong tương lai: bộ chuyển đổi truyền tải trực tiếp + điều khiển một kênh thật bên trong Gateway QA con. +- `qa/`: tài sản seed được repo hỗ trợ cho tác vụ khởi động và các kịch bản QA + cơ sở. - [Mantis](/vi/concepts/mantis): xác minh trực tiếp trước và sau cho các lỗi - cần transport thật, ảnh chụp màn hình trình duyệt, trạng thái VM và bằng chứng PR. + cần truyền tải thật, ảnh chụp màn hình trình duyệt, trạng thái VM và bằng chứng PR. ## Bề mặt lệnh -Mọi luồng QA đều chạy dưới `pnpm openclaw qa `. Nhiều lệnh có alias script `pnpm qa:*`; +Mọi luồng QA chạy dưới `pnpm openclaw qa `. Nhiều luồng có bí danh script `pnpm qa:*`; cả hai dạng đều được hỗ trợ. -| Lệnh | Mục đích | -| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | Tự kiểm tra QA đi kèm; ghi báo cáo Markdown. | -| `qa suite` | Chạy các kịch bản do repo hậu thuẫn đối với lane Gateway QA. Alias: `pnpm openclaw qa suite --runner multipass` cho một VM Linux dùng một lần. | -| `qa coverage` | In inventory phạm vi kịch bản dạng markdown (`--json` cho đầu ra máy). | -| `qa parity-report` | So sánh hai tệp `qa-suite-summary.json` và ghi báo cáo parity agentic. | -| `qa character-eval` | Chạy kịch bản QA nhân vật trên nhiều model trực tiếp với báo cáo được chấm. Xem [Báo cáo](#reporting). | -| `qa manual` | Chạy một prompt dùng một lần đối với lane provider/model đã chọn. | -| `qa ui` | Khởi động giao diện trình gỡ lỗi QA và bus QA cục bộ (alias: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | Xây dựng image Docker QA dựng sẵn. | -| `qa docker-scaffold` | Ghi scaffold docker-compose cho dashboard QA + lane Gateway. | -| `qa up` | Xây dựng site QA, khởi động ngăn xếp do Docker hậu thuẫn, in URL (alias: `pnpm qa:lab:up`; biến thể `:fast` thêm `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | -| `qa aimock` | Chỉ khởi động server provider AIMock. | -| `qa mock-openai` | Chỉ khởi động server provider `mock-openai` nhận biết kịch bản. | -| `qa credentials doctor` / `add` / `list` / `remove` | Quản lý pool thông tin xác thực Convex dùng chung. | -| `qa matrix` | Lane transport trực tiếp đối với homeserver Tuwunel dùng một lần. Xem [Matrix QA](/vi/concepts/qa-matrix). | -| `qa telegram` | Lane transport trực tiếp đối với một nhóm Telegram riêng tư thật. | -| `qa discord` | Lane transport trực tiếp đối với một kênh guild Discord riêng tư thật. | -| `qa mantis` | Runner xác minh trước và sau cho lỗi transport trực tiếp, với kịch bản phản ứng trạng thái Discord đầu tiên. Xem [Mantis](/vi/concepts/mantis). | +| Lệnh | Mục đích | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | Tự kiểm tra QA đi kèm; ghi báo cáo Markdown. | +| `qa suite` | Chạy các kịch bản được repo hỗ trợ trên lane Gateway QA. Bí danh: `pnpm openclaw qa suite --runner multipass` cho một VM Linux dùng một lần. | +| `qa coverage` | In kho kiểm kê độ phủ kịch bản dạng markdown (`--json` cho đầu ra máy đọc). | +| `qa parity-report` | So sánh hai tệp `qa-suite-summary.json` và ghi báo cáo tương đồng agentic. | +| `qa character-eval` | Chạy kịch bản QA nhân vật trên nhiều mô hình trực tiếp với báo cáo được chấm. Xem [Báo cáo](#reporting). | +| `qa manual` | Chạy một prompt dùng một lần trên lane provider/mô hình đã chọn. | +| `qa ui` | Khởi động giao diện gỡ lỗi QA và bus QA cục bộ (bí danh: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | Xây dựng ảnh Docker QA được dựng sẵn. | +| `qa docker-scaffold` | Ghi scaffold docker-compose cho bảng điều khiển QA + lane Gateway. | +| `qa up` | Xây dựng trang QA, khởi động ngăn xếp dựa trên Docker, in URL (bí danh: `pnpm qa:lab:up`; biến thể `:fast` thêm `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Chỉ khởi động máy chủ provider AIMock. | +| `qa mock-openai` | Chỉ khởi động máy chủ provider `mock-openai` nhận biết kịch bản. | +| `qa credentials doctor` / `add` / `list` / `remove` | Quản lý nhóm thông tin xác thực Convex dùng chung. | +| `qa matrix` | Lane truyền tải trực tiếp trên một homeserver Tuwunel dùng một lần. Xem [QA Matrix](/vi/concepts/qa-matrix). | +| `qa telegram` | Lane truyền tải trực tiếp trên một nhóm Telegram riêng tư thật. | +| `qa discord` | Lane truyền tải trực tiếp trên một kênh guild Discord riêng tư thật. | +| `qa slack` | Lane truyền tải trực tiếp trên một kênh Slack riêng tư thật. | +| `qa mantis` | Runner xác minh trước và sau cho lỗi truyền tải trực tiếp, với bằng chứng phản ứng trạng thái Discord và smoke Crabbox desktop/trình duyệt. Xem [Mantis](/vi/concepts/mantis). | -## Luồng vận hành +## Luồng người vận hành -Luồng vận hành QA hiện tại là một site QA hai khung: +Luồng người vận hành QA hiện tại là một trang QA hai khung: -- Trái: dashboard Gateway (Control UI) với agent. -- Phải: QA Lab, hiển thị transcript kiểu Slack và kế hoạch kịch bản. +- Trái: bảng điều khiển Gateway (Giao diện điều khiển) với agent. +- Phải: QA Lab, hiển thị bản ghi hội thoại kiểu Slack và kế hoạch kịch bản. Chạy bằng: @@ -69,13 +69,13 @@ Chạy bằng: pnpm qa:lab:up ``` -Lệnh đó xây dựng site QA, khởi động lane Gateway do Docker hậu thuẫn và mở trang -QA Lab nơi một operator hoặc vòng lặp tự động hóa có thể giao cho agent một nhiệm vụ QA, +Lệnh đó xây dựng trang QA, khởi động lane Gateway dựa trên Docker và mở trang +QA Lab nơi người vận hành hoặc vòng lặp tự động hóa có thể giao cho agent một nhiệm vụ QA, quan sát hành vi kênh thật và ghi lại những gì hoạt động, thất bại hoặc vẫn bị chặn. -Để lặp nhanh hơn trên giao diện QA Lab mà không phải xây dựng lại image Docker mỗi lần, -hãy khởi động ngăn xếp với bundle QA Lab được gắn kết bằng bind mount: +Để lặp giao diện QA Lab nhanh hơn mà không cần xây dựng lại ảnh Docker mỗi lần, +hãy khởi động ngăn xếp với gói QA Lab được gắn bind: ```bash pnpm openclaw qa docker-build-image @@ -84,112 +84,114 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` giữ các dịch vụ Docker trên một image dựng sẵn và bind-mount +`qa:lab:up:fast` giữ các dịch vụ Docker trên ảnh được dựng sẵn và gắn bind `extensions/qa-lab/web/dist` vào container `qa-lab`. `qa:lab:watch` -xây dựng lại bundle đó khi có thay đổi, và trình duyệt tự động tải lại khi hash tài sản QA Lab +xây dựng lại gói đó khi có thay đổi, và trình duyệt tự động tải lại khi hash tài sản QA Lab thay đổi. -Để smoke trace OpenTelemetry cục bộ, chạy: +Để chạy một smoke trace OpenTelemetry cục bộ, chạy: ```bash pnpm qa:otel:smoke ``` -Script đó khởi động một receiver trace OTLP/HTTP cục bộ, chạy kịch bản QA +Script đó khởi động một bộ nhận trace OTLP/HTTP cục bộ, chạy kịch bản QA `otel-trace-smoke` với Plugin `diagnostics-otel` được bật, sau đó -giải mã các span protobuf đã xuất và kiểm tra hình dạng quan trọng cho release: +giải mã các span protobuf đã xuất và xác nhận hình dạng trọng yếu cho phát hành: `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, -`openclaw.context.assembled` và `openclaw.message.delivery` phải hiện diện; -các cuộc gọi model không được xuất `StreamAbandoned` trên các lượt thành công; ID chẩn đoán thô và -các thuộc tính `openclaw.content.*` phải nằm ngoài trace. Nó ghi -`otel-smoke-summary.json` cạnh các artifact của QA suite. +`openclaw.context.assembled` và `openclaw.message.delivery` phải có mặt; +lượt gọi mô hình không được xuất `StreamAbandoned` trên các lượt thành công; ID chẩn đoán thô và +thuộc tính `openclaw.content.*` phải nằm ngoài trace. Nó ghi +`otel-smoke-summary.json` bên cạnh các artifact bộ QA. -QA về khả năng quan sát chỉ áp dụng cho checkout mã nguồn. Tarball npm cố ý bỏ qua -QA Lab, nên các lane release Docker package không chạy lệnh `qa`. Sử dụng -`pnpm qa:otel:smoke` từ một checkout mã nguồn đã build khi thay đổi instrumentation +QA khả năng quan sát chỉ ở dạng source-checkout. Tarball npm cố ý bỏ qua +QA Lab, nên các lane phát hành Docker của gói không chạy lệnh `qa`. Dùng +`pnpm qa:otel:smoke` từ một source checkout đã xây dựng khi thay đổi instrumentation chẩn đoán. -Đối với lane smoke Matrix dùng transport thật, chạy: +Để chạy lane smoke Matrix truyền tải thật, chạy: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -Tham chiếu CLI đầy đủ, danh mục profile/kịch bản, biến môi trường và bố cục artifact cho lane này nằm trong [Matrix QA](/vi/concepts/qa-matrix). Nhìn nhanh: nó cấp phát một homeserver Tuwunel dùng một lần trong Docker, đăng ký người dùng driver/SUT/observer tạm thời, chạy Plugin Matrix thật bên trong một Gateway QA con được giới hạn cho transport đó (không có `qa-channel`), rồi ghi báo cáo Markdown, tóm tắt JSON, artifact sự kiện đã quan sát và log đầu ra kết hợp dưới `.artifacts/qa-e2e/matrix-/`. +Tham chiếu CLI đầy đủ, danh mục profile/kịch bản, biến môi trường và bố cục artifact cho lane này nằm trong [QA Matrix](/vi/concepts/qa-matrix). Tóm tắt: nó cấp phát một homeserver Tuwunel dùng một lần trong Docker, đăng ký người dùng driver/SUT/observer tạm thời, chạy Plugin Matrix thật bên trong một Gateway QA con chỉ giới hạn cho truyền tải đó (không có `qa-channel`), rồi ghi báo cáo Markdown, bản tóm tắt JSON, artifact sự kiện quan sát được và log đầu ra kết hợp dưới `.artifacts/qa-e2e/matrix-/`. -Đối với các lane smoke Telegram và Discord dùng transport thật: +Đối với các lane smoke Telegram, Discord và Slack truyền tải thật: ```bash pnpm openclaw qa telegram pnpm openclaw qa discord +pnpm openclaw qa slack ``` -Cả hai nhắm tới một kênh thật đã tồn tại với hai bot (driver + SUT). Các biến môi trường bắt buộc, danh sách kịch bản, artifact đầu ra và pool thông tin xác thực Convex được ghi lại trong [Tham chiếu QA Telegram và Discord](#telegram-and-discord-qa-reference) bên dưới. +Chúng nhắm đến một kênh thật có sẵn với hai bot (driver + SUT). Các biến môi trường bắt buộc, danh sách kịch bản, artifact đầu ra và nhóm thông tin xác thực Convex được ghi lại trong [Tham chiếu QA Telegram, Discord và Slack](#telegram-discord-and-slack-qa-reference) bên dưới. -Trước khi dùng thông tin xác thực trực tiếp trong pool, chạy: +Trước khi dùng thông tin xác thực trực tiếp được gom nhóm, chạy: ```bash pnpm openclaw qa credentials doctor ``` -Doctor kiểm tra env broker Convex, xác thực thiết lập endpoint và xác minh khả năng truy cập admin/list khi có secret maintainer. Nó chỉ báo cáo trạng thái đã đặt/thiếu cho secret. +Doctor kiểm tra env broker Convex, xác thực cài đặt endpoint và xác minh khả năng truy cập admin/list khi có secret maintainer. Nó chỉ báo cáo trạng thái đã đặt/thiếu cho secret. -## Phạm vi transport trực tiếp +## Độ phủ truyền tải trực tiếp -Các lane transport trực tiếp dùng chung một contract thay vì mỗi lane tự phát minh hình dạng danh sách kịch bản riêng. `qa-channel` là bộ kiểm thử hành vi sản phẩm tổng hợp rộng và không thuộc ma trận phạm vi transport trực tiếp. +Các lane truyền tải trực tiếp dùng chung một hợp đồng thay vì mỗi lane tự tạo hình dạng danh sách kịch bản riêng. `qa-channel` là bộ hành vi sản phẩm tổng hợp rộng và không thuộc ma trận độ phủ truyền tải trực tiếp. -| Lane | Canary | Cổng mention | Bot-với-bot | Chặn allowlist | Trả lời cấp cao nhất | Tiếp tục sau restart | Theo dõi luồng | Cô lập luồng | Quan sát phản ứng | Lệnh trợ giúp | Đăng ký lệnh native | -| -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | -| Matrix | x | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | x | | | | | | | x | | -| Discord | x | x | x | | | | | | | | x | +| Lane | Kiểm thử canary | Cổng mention | Bot sang bot | Chặn allowlist | Trả lời cấp cao nhất | Tiếp tục sau khởi động lại | Theo dõi chuỗi thảo luận | Cô lập chuỗi thảo luận | Quan sát phản ứng | Lệnh trợ giúp | Đăng ký lệnh gốc | +| -------- | --------------- | ------------ | ------------ | -------------- | -------------------- | -------------------------- | ------------------------ | ---------------------- | ----------------- | ------------ | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | x | | | | | | | x | | +| Discord | x | x | x | | | | | | | | x | +| Slack | x | x | x | | | | | | | | | -Điều này giữ `qa-channel` làm bộ kiểm thử hành vi sản phẩm rộng trong khi Matrix, -Telegram và các transport trực tiếp trong tương lai dùng chung một checklist contract transport +Điều này giữ `qa-channel` là bộ hành vi sản phẩm rộng trong khi Matrix, +Telegram và các truyền tải trực tiếp tương lai dùng chung một checklist hợp đồng truyền tải rõ ràng. -Đối với lane VM Linux dùng một lần mà không đưa Docker vào đường dẫn QA, chạy: +Để chạy lane VM Linux dùng một lần mà không đưa Docker vào đường dẫn QA, chạy: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Lệnh này khởi động một guest Multipass mới, cài dependency, xây dựng OpenClaw -bên trong guest, chạy `qa suite`, sau đó sao chép báo cáo QA và -tóm tắt thông thường về `.artifacts/qa-e2e/...` trên host. -Nó tái sử dụng cùng hành vi chọn kịch bản như `qa suite` trên host. -Các lần chạy suite trên host và Multipass thực thi nhiều kịch bản đã chọn song song +Lệnh này khởi động một guest Multipass mới, cài đặt phụ thuộc, xây dựng OpenClaw +bên trong guest, chạy `qa suite`, rồi sao chép báo cáo QA và +bản tóm tắt thông thường về `.artifacts/qa-e2e/...` trên host. +Nó dùng lại cùng hành vi chọn kịch bản như `qa suite` trên host. +Các lần chạy bộ trên host và Multipass thực thi song song nhiều kịch bản đã chọn với các worker Gateway cô lập theo mặc định. `qa-channel` mặc định concurrency -4, giới hạn bởi số lượng kịch bản đã chọn. Dùng `--concurrency ` để điều chỉnh -số worker, hoặc `--concurrency 1` để thực thi nối tiếp. -Lệnh thoát khác 0 khi bất kỳ kịch bản nào thất bại. Dùng `--allow-failures` khi +4, bị giới hạn bởi số kịch bản đã chọn. Dùng `--concurrency ` để điều chỉnh +số worker, hoặc `--concurrency 1` để thực thi tuần tự. +Lệnh thoát với mã khác không khi bất kỳ kịch bản nào thất bại. Dùng `--allow-failures` khi bạn muốn có artifact mà không có mã thoát thất bại. -Các lần chạy trực tiếp chuyển tiếp những đầu vào auth QA được hỗ trợ và thực tế cho +Các lần chạy trực tiếp chuyển tiếp các đầu vào auth QA được hỗ trợ và thực tế cho guest: khóa provider dựa trên env, đường dẫn cấu hình provider trực tiếp QA và -`CODEX_HOME` khi có. Giữ `--output-dir` dưới gốc repo để guest -có thể ghi ngược qua workspace được mount. +`CODEX_HOME` khi có. Giữ `--output-dir` dưới thư mục gốc repo để guest +có thể ghi ngược qua workspace đã gắn. -## Tham chiếu QA Telegram và Discord +## Tham chiếu QA Telegram, Discord và Slack -Matrix có một [trang riêng](/vi/concepts/qa-matrix) vì số lượng kịch bản và quá trình cấp phát homeserver do Docker hậu thuẫn. Telegram và Discord nhỏ hơn — mỗi loại chỉ có vài kịch bản, không có hệ thống profile, chạy trên các kênh thật đã tồn tại — nên tham chiếu của chúng nằm ở đây. +Matrix có một [trang riêng](/vi/concepts/qa-matrix) vì số lượng kịch bản và cấp phát homeserver dựa trên Docker của nó. Telegram, Discord và Slack nhỏ hơn — mỗi loại chỉ có một vài kịch bản, không có hệ thống profile, chạy trên các kênh thật có sẵn — nên phần tham chiếu của chúng nằm ở đây. ### Cờ CLI dùng chung -Cả hai lane đều đăng ký qua `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` và chấp nhận cùng các cờ: +Các lane này đăng ký qua `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` và chấp nhận cùng các cờ: -| Cờ | Mặc định | Mô tả | -| ------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | Chỉ chạy kịch bản này. Có thể lặp lại. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord}-` | Nơi ghi báo cáo/tóm tắt/thông điệp đã quan sát và nhật ký đầu ra. Đường dẫn tương đối được phân giải theo `--repo-root`. | -| `--repo-root ` | `process.cwd()` | Gốc kho lưu trữ khi gọi từ một cwd trung lập. | -| `--sut-account ` | `sut` | Id tài khoản tạm thời bên trong cấu hình Gateway QA. | -| `--provider-mode ` | `live-frontier` | `mock-openai` hoặc `live-frontier` (`live-openai` cũ vẫn hoạt động). | -| `--model ` / `--alt-model ` | mặc định của nhà cung cấp | Tham chiếu mô hình chính/thay thế. | -| `--fast` | tắt | Chế độ nhanh của nhà cung cấp khi được hỗ trợ. | -| `--credential-source ` | `env` | Xem [nhóm thông tin xác thực Convex](#convex-credential-pool). | -| `--credential-role ` | `ci` trong CI, nếu không là `maintainer` | Vai trò được dùng khi `--credential-source convex`. | +| Cờ | Mặc định | Mô tả | +| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Chỉ chạy kịch bản này. Có thể lặp lại. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Nơi ghi báo cáo/tóm tắt/tin nhắn đã quan sát và nhật ký đầu ra. Đường dẫn tương đối được phân giải theo `--repo-root`. | +| `--repo-root ` | `process.cwd()` | Gốc kho lưu trữ khi gọi từ một cwd trung lập. | +| `--sut-account ` | `sut` | ID tài khoản tạm thời bên trong cấu hình QA Gateway. | +| `--provider-mode ` | `live-frontier` | `mock-openai` hoặc `live-frontier` (`live-openai` cũ vẫn hoạt động). | +| `--model ` / `--alt-model ` | mặc định của nhà cung cấp | Tham chiếu model chính/thay thế. | +| `--fast` | tắt | Chế độ nhanh của nhà cung cấp khi được hỗ trợ. | +| `--credential-source ` | `env` | Xem [nhóm thông tin xác thực Convex](#convex-credential-pool). | +| `--credential-role ` | `ci` trong CI, nếu không thì `maintainer` | Vai trò được dùng khi `--credential-source convex`. | -Cả hai đều thoát với mã khác không khi có bất kỳ kịch bản nào thất bại. `--allow-failures` ghi tạo tác mà không đặt mã thoát thất bại. +Mỗi lane thoát với mã khác không khi có bất kỳ kịch bản nào thất bại. `--allow-failures` ghi artifact mà không đặt mã thoát thất bại. ### QA Telegram @@ -197,17 +199,17 @@ Cả hai đều thoát với mã khác không khi có bất kỳ kịch bản n pnpm openclaw qa telegram ``` -Nhắm đến một nhóm Telegram riêng tư thật với hai bot riêng biệt (driver + SUT). Bot SUT phải có tên người dùng Telegram; quan sát bot-với-bot hoạt động tốt nhất khi cả hai bot đều bật **Bot-to-Bot Communication Mode** trong `@BotFather`. +Nhắm tới một nhóm Telegram riêng tư thật với hai bot riêng biệt (driver + SUT). Bot SUT phải có tên người dùng Telegram; quan sát bot-với-bot hoạt động tốt nhất khi cả hai bot đều bật **Bot-to-Bot Communication Mode** trong `@BotFather`. Env bắt buộc khi `--credential-source env`: -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — id chat dạng số (chuỗi). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — ID chat dạng số (chuỗi). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` Tùy chọn: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` giữ nội dung thông điệp trong tạo tác thông điệp đã quan sát (mặc định che lại). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` giữ nội dung tin nhắn trong artifact tin nhắn đã quan sát (mặc định biên tập ẩn). Kịch bản (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): @@ -220,11 +222,11 @@ Kịch bản (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runt - `telegram-whoami-command` - `telegram-context-command` -Tạo tác đầu ra: +Artifact đầu ra: - `telegram-qa-report.md` -- `telegram-qa-summary.json` — bao gồm RTT theo từng phản hồi (driver gửi → quan sát phản hồi SUT) bắt đầu bằng canary. -- `telegram-qa-observed-messages.json` — nội dung bị che trừ khi `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. +- `telegram-qa-summary.json` — bao gồm RTT theo từng phản hồi (driver gửi → quan sát phản hồi SUT), bắt đầu với canary. +- `telegram-qa-observed-messages.json` — nội dung bị biên tập ẩn trừ khi `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. ### QA Discord @@ -232,7 +234,7 @@ Tạo tác đầu ra: pnpm openclaw qa discord ``` -Nhắm đến một kênh guild Discord riêng tư thật với hai bot: một bot driver do harness điều khiển và một bot SUT được Gateway OpenClaw con khởi động thông qua Plugin Discord đi kèm. Xác minh xử lý đề cập kênh, rằng bot SUT đã đăng ký lệnh `/help` gốc với Discord, và các kịch bản bằng chứng Mantis theo cơ chế chọn tham gia. +Nhắm tới một kênh guild Discord riêng tư thật với hai bot: bot driver do harness điều khiển và bot SUT được khởi động bởi OpenClaw Gateway con thông qua Plugin Discord đi kèm. Xác minh xử lý nhắc đến kênh, việc bot SUT đã đăng ký lệnh gốc `/help` với Discord, và các kịch bản bằng chứng Mantis chọn tham gia. Env bắt buộc khi `--credential-source env`: @@ -240,20 +242,20 @@ Env bắt buộc khi `--credential-source env`: - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — phải khớp với id người dùng bot SUT do Discord trả về (nếu không lane sẽ thất bại nhanh). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — phải khớp với ID người dùng bot SUT do Discord trả về (nếu không lane sẽ thất bại nhanh). Tùy chọn: -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` giữ nội dung thông điệp trong tạo tác thông điệp đã quan sát. +- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` giữ nội dung tin nhắn trong artifact tin nhắn đã quan sát. Kịch bản (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`): - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — kịch bản Mantis theo cơ chế chọn tham gia. Chạy riêng vì nó chuyển SUT sang phản hồi guild luôn bật, chỉ dùng công cụ với `messages.statusReactions.enabled=true`, rồi ghi lại dòng thời gian reaction REST cùng với một tạo tác trực quan HTML/PNG. +- `discord-status-reactions-tool-only` — kịch bản Mantis chọn tham gia. Tự chạy riêng vì nó chuyển SUT sang phản hồi guild luôn bật, chỉ dùng công cụ với `messages.statusReactions.enabled=true`, sau đó ghi lại dòng thời gian phản ứng REST cùng artifact trực quan HTML/PNG. -Chạy rõ ràng kịch bản status-reaction Mantis: +Chạy rõ ràng kịch bản phản ứng trạng thái Mantis: ```bash pnpm openclaw qa discord \ @@ -264,23 +266,53 @@ pnpm openclaw qa discord \ --fast ``` -Tạo tác đầu ra: +Artifact đầu ra: - `discord-qa-report.md` - `discord-qa-summary.json` -- `discord-qa-observed-messages.json` — nội dung bị che trừ khi `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. -- `discord-qa-reaction-timelines.json` và `discord-status-reactions-tool-only-timeline.png` khi kịch bản status-reaction chạy. +- `discord-qa-observed-messages.json` — nội dung bị biên tập ẩn trừ khi `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. +- `discord-qa-reaction-timelines.json` và `discord-status-reactions-tool-only-timeline.png` khi kịch bản phản ứng trạng thái chạy. + +### QA Slack + +```bash +pnpm openclaw qa slack +``` + +Nhắm tới một kênh Slack riêng tư thật với hai bot riêng biệt: bot driver do harness điều khiển và bot SUT được khởi động bởi OpenClaw Gateway con thông qua Plugin Slack đi kèm. + +Env bắt buộc khi `--credential-source env`: + +- `OPENCLAW_QA_SLACK_CHANNEL_ID` +- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN` + +Tùy chọn: + +- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` giữ nội dung tin nhắn trong artifact tin nhắn đã quan sát. + +Kịch bản (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`): + +- `slack-canary` +- `slack-mention-gating` + +Artifact đầu ra: + +- `slack-qa-report.md` +- `slack-qa-summary.json` +- `slack-qa-observed-messages.json` — nội dung bị biên tập ẩn trừ khi `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. ### Nhóm thông tin xác thực Convex -Cả lane Telegram và Discord đều có thể thuê thông tin xác thực từ một nhóm Convex dùng chung thay vì đọc các biến env ở trên. Truyền `--credential-source convex` (hoặc đặt `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab lấy một lease độc quyền, gửi Heartbeat cho lease đó trong suốt thời gian chạy, và giải phóng lease khi tắt. Các loại nhóm là `"telegram"` và `"discord"`. +Các lane Telegram, Discord và Slack có thể thuê thông tin xác thực từ một nhóm Convex dùng chung thay vì đọc các biến env ở trên. Truyền `--credential-source convex` (hoặc đặt `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab lấy một lease độc quyền, gửi heartbeat cho lease đó trong suốt thời gian chạy, và giải phóng khi tắt. Các loại nhóm là `"telegram"`, `"discord"`, và `"slack"`. Dạng payload mà broker xác thực trên `admin/add`: - Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` phải là chuỗi chat-id dạng số. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. -Các biến env vận hành và hợp đồng endpoint broker Convex nằm trong [Kiểm thử → Thông tin xác thực Telegram dùng chung qua Convex](/vi/help/testing#shared-telegram-credentials-via-convex-v1) (tên phần có trước khi hỗ trợ Discord; ngữ nghĩa broker giống hệt nhau cho cả hai loại). +Các biến env vận hành và hợp đồng endpoint của broker Convex nằm trong [Kiểm thử → Thông tin xác thực Telegram dùng chung qua Convex](/vi/help/testing#shared-telegram-credentials-via-convex-v1) (tên mục có trước hỗ trợ Discord; ngữ nghĩa broker giống hệt nhau cho cả hai loại). ## Seed dựa trên kho lưu trữ @@ -289,29 +321,29 @@ Tài nguyên seed nằm trong `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Các tài nguyên này cố ý được đưa vào git để kế hoạch QA hiển thị với cả con người và agent. +Các tệp này chủ ý được lưu trong git để kế hoạch QA hiển thị cho cả con người và agent. -`qa-lab` nên tiếp tục là một runner markdown chung. Mỗi tệp markdown kịch bản là nguồn sự thật cho một lần chạy kiểm thử và nên định nghĩa: +`qa-lab` nên duy trì là một runner markdown chung. Mỗi tệp markdown kịch bản là nguồn sự thật cho một lần chạy kiểm thử và nên định nghĩa: - siêu dữ liệu kịch bản -- siêu dữ liệu tùy chọn về danh mục, khả năng, lane và rủi ro +- siêu dữ liệu danh mục, capability, lane và rủi ro tùy chọn - tham chiếu tài liệu và mã - yêu cầu Plugin tùy chọn - bản vá cấu hình Gateway tùy chọn - `qa-flow` có thể thực thi -Bề mặt runtime tái sử dụng hỗ trợ `qa-flow` được phép tiếp tục là chung và xuyên suốt. Ví dụ, các kịch bản markdown có thể kết hợp helper phía transport với helper phía trình duyệt điều khiển Control UI nhúng thông qua seam `browser.request` của Gateway mà không cần thêm runner trường hợp đặc biệt. +Bề mặt runtime tái sử dụng hỗ trợ `qa-flow` được phép duy trì chung và xuyên suốt. Ví dụ, kịch bản markdown có thể kết hợp helper phía transport với helper phía trình duyệt để điều khiển Control UI nhúng thông qua đường nối `browser.request` của Gateway mà không thêm runner trường hợp đặc biệt. -Các tệp kịch bản nên được nhóm theo khả năng sản phẩm thay vì thư mục cây nguồn. Giữ ID kịch bản ổn định khi di chuyển tệp; dùng `docsRefs` và `codeRefs` để truy vết triển khai. +Các tệp kịch bản nên được nhóm theo capability sản phẩm thay vì thư mục cây nguồn. Giữ ID kịch bản ổn định khi di chuyển tệp; dùng `docsRefs` và `codeRefs` để truy vết triển khai. Danh sách baseline nên đủ rộng để bao phủ: -- chat DM và kênh -- hành vi thread -- vòng đời hành động thông điệp +- Chat DM và kênh +- hành vi luồng +- vòng đời hành động tin nhắn - callback cron -- gọi lại bộ nhớ -- chuyển đổi mô hình +- truy hồi bộ nhớ +- chuyển đổi model - bàn giao subagent - đọc kho lưu trữ và đọc tài liệu - một tác vụ build nhỏ như Lobster Invaders @@ -320,71 +352,71 @@ Danh sách baseline nên đủ rộng để bao phủ: `qa suite` có hai lane mock nhà cung cấp cục bộ: -- `mock-openai` là mock OpenClaw nhận biết kịch bản. Nó vẫn là lane mock xác định mặc định cho QA dựa trên kho lưu trữ và cổng parity. -- `aimock` khởi động một máy chủ nhà cung cấp dựa trên AIMock cho phạm vi bao phủ giao thức thử nghiệm, fixture, ghi/phát lại và chaos. Nó mang tính bổ sung và không thay thế dispatcher kịch bản `mock-openai`. +- `mock-openai` là mock OpenClaw nhận biết kịch bản. Nó vẫn là lane mock xác định mặc định cho QA dựa trên kho lưu trữ và parity gate. +- `aimock` khởi động server nhà cung cấp dựa trên AIMock cho phạm vi bao phủ protocol, fixture, ghi/phát lại và chaos thử nghiệm. Nó mang tính bổ sung và không thay thế bộ điều phối kịch bản `mock-openai`. -Triển khai lane nhà cung cấp nằm dưới `extensions/qa-lab/src/providers/`. Mỗi nhà cung cấp sở hữu mặc định, khởi động máy chủ cục bộ, cấu hình mô hình Gateway, nhu cầu dàn dựng auth-profile, và cờ khả năng live/mock của nó. Mã suite và Gateway dùng chung nên định tuyến qua registry nhà cung cấp thay vì rẽ nhánh theo tên nhà cung cấp. +Triển khai lane nhà cung cấp nằm dưới `extensions/qa-lab/src/providers/`. Mỗi nhà cung cấp sở hữu mặc định của mình, khởi động server cục bộ, cấu hình model Gateway, nhu cầu dàn dựng auth-profile, và cờ capability live/mock. Mã suite và Gateway dùng chung nên định tuyến qua registry nhà cung cấp thay vì rẽ nhánh theo tên nhà cung cấp. ## Adapter transport -`qa-lab` sở hữu một seam transport chung cho các kịch bản QA markdown. `qa-channel` là adapter đầu tiên trên seam đó, nhưng mục tiêu thiết kế rộng hơn: các kênh thật hoặc tổng hợp trong tương lai nên cắm vào cùng runner suite thay vì thêm một runner QA riêng cho transport. +`qa-lab` sở hữu một đường nối transport chung cho các kịch bản QA markdown. `qa-channel` là adapter đầu tiên trên đường nối đó, nhưng mục tiêu thiết kế rộng hơn: các kênh thật hoặc tổng hợp trong tương lai nên cắm vào cùng runner suite thay vì thêm một runner QA dành riêng cho transport. Ở cấp kiến trúc, phần tách là: -- `qa-lab` sở hữu thực thi kịch bản chung, đồng thời worker, ghi tạo tác và báo cáo. -- Adapter transport sở hữu cấu hình Gateway, trạng thái sẵn sàng, quan sát inbound và outbound, hành động transport, và trạng thái transport đã chuẩn hóa. +- `qa-lab` sở hữu thực thi kịch bản chung, đồng thời worker, ghi artifact và báo cáo. +- Adapter transport sở hữu cấu hình Gateway, trạng thái sẵn sàng, quan sát đầu vào và đầu ra, hành động transport, và trạng thái transport đã chuẩn hóa. - Các tệp kịch bản markdown dưới `qa/scenarios/` định nghĩa lần chạy kiểm thử; `qa-lab` cung cấp bề mặt runtime tái sử dụng để thực thi chúng. -### Thêm một kênh +### Thêm kênh Thêm một kênh vào hệ thống QA markdown yêu cầu đúng hai thứ: 1. Một adapter transport cho kênh. 2. Một gói kịch bản kiểm thử hợp đồng kênh. -Không thêm một root lệnh QA cấp cao mới khi host `qa-lab` dùng chung có thể sở hữu flow. +Không thêm gốc lệnh QA cấp cao mới khi host `qa-lab` dùng chung có thể sở hữu luồng. `qa-lab` sở hữu cơ chế host dùng chung: -- root lệnh `openclaw qa` -- khởi động và tháo dỡ suite +- gốc lệnh `openclaw qa` +- khởi động và dọn dẹp suite - đồng thời worker -- ghi tạo tác +- ghi artifact - tạo báo cáo - thực thi kịch bản - alias tương thích cho các kịch bản `qa-channel` cũ hơn -Các Plugin runner sở hữu hợp đồng transport: +Runner Plugin sở hữu hợp đồng transport: -- cách `openclaw qa ` được mount bên dưới root `qa` dùng chung +- cách `openclaw qa ` được gắn bên dưới gốc `qa` dùng chung - cách Gateway được cấu hình cho transport đó - cách kiểm tra trạng thái sẵn sàng -- cách sự kiện inbound được tiêm vào -- cách quan sát thông điệp outbound -- cách transcript và trạng thái transport đã chuẩn hóa được lộ ra +- cách chèn sự kiện đầu vào +- cách quan sát tin nhắn đầu ra +- cách transcript và trạng thái transport đã chuẩn hóa được hiển thị - cách thực thi hành động dựa trên transport -- cách xử lý reset hoặc dọn dẹp riêng cho transport +- cách xử lý đặt lại hoặc dọn dẹp riêng cho transport -Mức chấp nhận tối thiểu cho một kênh mới: +Ngưỡng chấp nhận tối thiểu cho một kênh mới: -1. Giữ `qa-lab` là chủ sở hữu của root `qa` dùng chung. -2. Triển khai runner transport trên seam host `qa-lab` dùng chung. -3. Giữ cơ chế riêng cho transport bên trong Plugin runner hoặc harness kênh. -4. Mount runner dưới dạng `openclaw qa ` thay vì đăng ký một lệnh root cạnh tranh. Plugin runner nên khai báo `qaRunners` trong `openclaw.plugin.json` và xuất một mảng `qaRunnerCliRegistrations` khớp từ `runtime-api.ts`. Giữ `runtime-api.ts` nhẹ; CLI lazy và thực thi runner nên nằm sau các entrypoint riêng. -5. Tạo hoặc điều chỉnh các kịch bản markdown dưới thư mục `qa/scenarios/` theo chủ đề. -6. Dùng helper kịch bản chung cho các kịch bản mới. -7. Giữ các alias tương thích hiện có hoạt động trừ khi kho lưu trữ đang thực hiện một migration có chủ ý. +1. Giữ `qa-lab` làm chủ sở hữu của gốc `qa` dùng chung. +2. Triển khai transport runner trên seam máy chủ `qa-lab` dùng chung. +3. Giữ các cơ chế dành riêng cho transport bên trong runner plugin hoặc channel harness. +4. Gắn runner dưới dạng `openclaw qa ` thay vì đăng ký một lệnh gốc cạnh tranh. Runner plugins nên khai báo `qaRunners` trong `openclaw.plugin.json` và xuất một mảng `qaRunnerCliRegistrations` khớp từ `runtime-api.ts`. Giữ `runtime-api.ts` nhẹ; CLI lazy và việc thực thi runner nên nằm sau các điểm vào riêng biệt. +5. Tạo hoặc điều chỉnh các kịch bản markdown trong các thư mục `qa/scenarios/` theo chủ đề. +6. Dùng các trình trợ giúp kịch bản chung cho những kịch bản mới. +7. Giữ các alias tương thích hiện có hoạt động trừ khi repo đang thực hiện một cuộc di trú có chủ đích. -Quy tắc quyết định rất chặt chẽ: +Quy tắc quyết định rất nghiêm ngặt: -- Nếu hành vi có thể được biểu đạt một lần trong `qa-lab`, đặt nó trong `qa-lab`. -- Nếu hành vi phụ thuộc vào một transport kênh, giữ nó trong Plugin runner hoặc harness Plugin đó. -- Nếu một kịch bản cần một khả năng mới mà nhiều hơn một kênh có thể dùng, thêm một helper chung thay vì một nhánh riêng cho kênh trong `suite.ts`. -- Nếu một hành vi chỉ có ý nghĩa với một transport, giữ kịch bản riêng cho transport và làm rõ điều đó trong hợp đồng kịch bản. +- Nếu hành vi có thể được biểu đạt một lần trong `qa-lab`, hãy đặt nó trong `qa-lab`. +- Nếu hành vi phụ thuộc vào một channel transport, hãy giữ nó trong runner plugin hoặc plugin harness đó. +- Nếu một kịch bản cần một năng lực mới mà nhiều hơn một channel có thể dùng, hãy thêm một trình trợ giúp chung thay vì một nhánh dành riêng cho channel trong `suite.ts`. +- Nếu một hành vi chỉ có ý nghĩa với một transport, hãy giữ kịch bản đó dành riêng cho transport và nêu rõ điều đó trong hợp đồng kịch bản. -### Tên helper kịch bản +### Tên trình trợ giúp kịch bản -Các helper chung ưu tiên cho kịch bản mới: +Các trình trợ giúp chung được ưu tiên cho kịch bản mới: - `waitForTransportReady` - `waitForChannelReady` @@ -399,22 +431,22 @@ Các helper chung ưu tiên cho kịch bản mới: - `formatTransportTranscript` - `resetTransport` -Các bí danh tương thích vẫn còn khả dụng cho các kịch bản hiện có — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — nhưng việc biên soạn kịch bản mới nên dùng các tên chung. Các bí danh tồn tại để tránh một đợt di chuyển bắt buộc cùng lúc, chứ không phải là mô hình về sau. +Các alias tương thích vẫn còn khả dụng cho kịch bản hiện có — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — nhưng khi tạo kịch bản mới nên dùng các tên chung. Các alias tồn tại để tránh một cuộc di trú đồng loạt, không phải là mô hình cho tương lai. ## Báo cáo -`qa-lab` xuất báo cáo giao thức Markdown từ dòng thời gian bus đã quan sát. +`qa-lab` xuất một báo cáo giao thức Markdown từ timeline bus đã quan sát. Báo cáo nên trả lời: -- Điều gì hoạt động -- Điều gì thất bại +- Điều gì đã hoạt động +- Điều gì đã thất bại - Điều gì vẫn bị chặn -- Những kịch bản theo dõi nào đáng thêm vào +- Những kịch bản theo dõi nào đáng bổ sung -Để xem danh sách các kịch bản khả dụng — hữu ích khi ước lượng công việc theo dõi hoặc nối một transport mới — hãy chạy `pnpm openclaw qa coverage` (thêm `--json` để có đầu ra máy đọc được). +Để xem inventory của các kịch bản có sẵn — hữu ích khi ước lượng công việc theo dõi hoặc nối dây một transport mới — hãy chạy `pnpm openclaw qa coverage` (thêm `--json` để có đầu ra máy đọc được). -Để kiểm tra tính cách và phong cách, hãy chạy cùng một kịch bản trên nhiều tham chiếu model live -và viết báo cáo Markdown đã được chấm: +Đối với kiểm tra ký tự và phong cách, hãy chạy cùng một kịch bản trên nhiều live model +refs và viết một báo cáo Markdown đã được đánh giá: ```bash pnpm openclaw qa character-eval \ @@ -433,42 +465,42 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Lệnh này chạy các tiến trình con của QA gateway cục bộ, không phải Docker. Các kịch bản đánh giá tính cách -nên đặt persona thông qua `SOUL.md`, rồi chạy các lượt người dùng thông thường -như trò chuyện, trợ giúp workspace và các tác vụ tệp nhỏ. Không nên cho model ứng viên -biết rằng nó đang được đánh giá. Lệnh này giữ lại từng transcript đầy đủ, -ghi lại các thống kê chạy cơ bản, rồi yêu cầu các model giám khảo ở chế độ nhanh với -lập luận `xhigh` khi được hỗ trợ để xếp hạng các lần chạy theo độ tự nhiên, sắc thái và sự hài hước. -Dùng `--blind-judge-models` khi so sánh các provider: prompt cho giám khảo vẫn nhận -mọi transcript và trạng thái chạy, nhưng các tham chiếu ứng viên được thay bằng nhãn trung lập -như `candidate-01`; báo cáo ánh xạ thứ hạng trở lại các tham chiếu thật sau khi -phân tích. -Theo mặc định, các lần chạy ứng viên dùng suy nghĩ `high`, với `medium` cho GPT-5.5 và `xhigh` -cho các tham chiếu đánh giá OpenAI cũ hơn có hỗ trợ. Ghi đè một ứng viên cụ thể ngay trong dòng bằng +Lệnh này chạy các tiến trình con QA gateway cục bộ, không phải Docker. Các kịch bản character eval +nên thiết lập persona thông qua `SOUL.md`, rồi chạy các lượt người dùng thông thường +như trò chuyện, hỗ trợ workspace và tác vụ tệp nhỏ. Model ứng viên +không nên được cho biết rằng nó đang được đánh giá. Lệnh này giữ lại từng +transcript đầy đủ, ghi lại thống kê chạy cơ bản, rồi yêu cầu các model giám khảo ở chế độ fast với +lập luận `xhigh` khi được hỗ trợ để xếp hạng các lượt chạy theo độ tự nhiên, vibe và sự hài hước. +Dùng `--blind-judge-models` khi so sánh nhà cung cấp: prompt cho giám khảo vẫn nhận +mọi transcript và trạng thái chạy, nhưng candidate refs được thay bằng các +nhãn trung lập như `candidate-01`; báo cáo ánh xạ thứ hạng trở lại refs thật sau khi +phân tích cú pháp. +Các lượt chạy ứng viên mặc định dùng tư duy `high`, với `medium` cho GPT-5.5 và `xhigh` +cho các OpenAI eval refs cũ hơn có hỗ trợ. Ghi đè một ứng viên cụ thể inline bằng `--model provider/model,thinking=`. `--thinking ` vẫn đặt một -mức dự phòng toàn cục, và dạng cũ hơn `--model-thinking ` được +dự phòng toàn cục, và dạng cũ hơn `--model-thinking ` được giữ lại để tương thích. -Các tham chiếu ứng viên OpenAI mặc định dùng chế độ nhanh để ưu tiên xử lý ở nơi -provider hỗ trợ. Thêm `,fast`, `,no-fast`, hoặc `,fast=false` ngay trong dòng khi một -ứng viên hoặc giám khảo riêng lẻ cần ghi đè. Truyền `--fast` chỉ khi bạn muốn -bật bắt buộc chế độ nhanh cho mọi model ứng viên. Thời lượng của ứng viên và giám khảo được +OpenAI candidate refs mặc định dùng chế độ fast để priority processing được sử dụng khi +nhà cung cấp hỗ trợ. Thêm `,fast`, `,no-fast`, hoặc `,fast=false` inline khi một +ứng viên hoặc giám khảo riêng lẻ cần ghi đè. Chỉ truyền `--fast` khi bạn muốn +ép bật chế độ fast cho mọi model ứng viên. Thời lượng của ứng viên và giám khảo được ghi trong báo cáo để phân tích benchmark, nhưng prompt cho giám khảo nói rõ không xếp hạng theo tốc độ. -Các lần chạy model ứng viên và giám khảo đều mặc định dùng concurrency 16. Hạ -`--concurrency` hoặc `--judge-concurrency` khi giới hạn provider hoặc áp lực Gateway -cục bộ làm lần chạy quá nhiễu. -Khi không truyền `--model` ứng viên, đánh giá tính cách mặc định dùng +Cả lượt chạy model ứng viên và giám khảo đều mặc định dùng concurrency 16. Giảm +`--concurrency` hoặc `--judge-concurrency` khi giới hạn nhà cung cấp hoặc áp lực gateway +cục bộ khiến một lượt chạy quá nhiễu. +Khi không truyền candidate `--model`, character eval mặc định dùng `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5`, và `google/gemini-3.1-pro-preview` khi không truyền `--model`. -Khi không truyền `--judge-model`, các giám khảo mặc định là +Khi không truyền `--judge-model`, giám khảo mặc định là `openai/gpt-5.5,thinking=xhigh,fast` và `anthropic/claude-opus-4-6,thinking=high`. ## Tài liệu liên quan -- [Matrix QA](/vi/concepts/qa-matrix) +- [QA ma trận](/vi/concepts/qa-matrix) - [QA Channel](/vi/channels/qa-channel) - [Kiểm thử](/vi/help/testing) - [Dashboard](/vi/web/dashboard) diff --git a/docs/vi/concepts/queue-steering.md b/docs/vi/concepts/queue-steering.md index 63faafc7d..c5675346c 100644 --- a/docs/vi/concepts/queue-steering.md +++ b/docs/vi/concepts/queue-steering.md @@ -2,96 +2,100 @@ read_when: - Giải thích cách điều hướng hoạt động khi một tác nhân đang sử dụng công cụ - Thay đổi hành vi hàng đợi lượt chạy đang hoạt động hoặc tích hợp điều hướng thời gian chạy - - So sánh các chế độ steer, queue, collect và followup -summary: Cách điều hướng active-run xếp hàng thông điệp tại các ranh giới thời gian chạy -title: Hàng đợi điều hướng + - So sánh các chế độ điều hướng, xếp hàng, thu thập và theo dõi +summary: Cách điều hướng lượt chạy đang hoạt động xếp hàng đợi thông điệp tại các ranh giới thời gian chạy +title: Hàng đợi định hướng x-i18n: - generated_at: "2026-04-30T09:35:51Z" + generated_at: "2026-05-04T02:23:27Z" model: gpt-5.5 provider: openai - source_hash: 560390c8c26bcce95e0137f4336ad6e62bc3e2344cb15fd12ca3cfe4a85a8acc + source_hash: c8df35b127ae0c1e1b3b684a1f63ce33874eb3d0b7bf9d0df7cb9dfce093090a source_path: concepts/queue-steering.md workflow: 16 --- -Khi có thông báo đến trong lúc một lượt chạy phiên đang phát trực tuyến, OpenClaw có thể -gửi thông báo đó vào runtime đang hoạt động thay vì bắt đầu một lượt chạy khác cho -cùng phiên. Các chế độ công khai không phụ thuộc vào runtime; Pi và bộ harness -app-server Codex gốc triển khai chi tiết phân phối theo cách khác nhau. +Khi một tin nhắn đến trong lúc một lượt chạy phiên đang phát trực tuyến, OpenClaw có thể +gửi tin nhắn đó vào runtime đang hoạt động thay vì bắt đầu một lượt chạy khác cho +cùng phiên. Các chế độ công khai trung lập với runtime; Pi và harness app-server +Codex gốc triển khai chi tiết phân phối theo cách khác nhau. ## Ranh giới runtime -Điều hướng không ngắt một lệnh gọi công cụ đang chạy. Pi kiểm tra các thông báo -điều hướng đang chờ tại các ranh giới mô hình: +Điều hướng không ngắt một lệnh gọi công cụ đang chạy. Pi kiểm tra +các tin nhắn điều hướng đã xếp hàng tại các ranh giới mô hình: 1. Trợ lý yêu cầu các lệnh gọi công cụ. -2. Pi thực thi lô lệnh gọi công cụ của thông báo trợ lý hiện tại. +2. Pi thực thi lô lệnh gọi công cụ của tin nhắn trợ lý hiện tại. 3. Pi phát sự kiện kết thúc lượt. -4. Pi rút hết các thông báo điều hướng đang chờ. -5. Pi thêm các thông báo đó dưới dạng thông báo người dùng trước lệnh gọi LLM tiếp theo. +4. Pi xả các tin nhắn điều hướng đã xếp hàng. +5. Pi thêm các tin nhắn đó dưới dạng tin nhắn người dùng trước lệnh gọi LLM tiếp theo. -Điều này giữ cho kết quả công cụ được ghép với thông báo trợ lý đã yêu cầu chúng, -sau đó cho phép lệnh gọi mô hình tiếp theo thấy đầu vào mới nhất của người dùng. +Điều này giữ các kết quả công cụ đi kèm với tin nhắn trợ lý đã yêu cầu chúng, +sau đó cho phép lệnh gọi mô hình tiếp theo thấy dữ liệu nhập mới nhất của người dùng. -Bộ harness app-server Codex gốc cung cấp `turn/steer` thay vì hàng đợi điều hướng +Harness app-server Codex gốc cung cấp `turn/steer` thay vì hàng đợi điều hướng nội bộ của Pi. OpenClaw điều chỉnh cùng các chế độ tại đó: -- `steer` gom lô các thông báo đang chờ trong khoảng lặng đã cấu hình, sau đó gửi - một yêu cầu `turn/steer` duy nhất với toàn bộ đầu vào người dùng đã thu thập theo thứ tự đến. -- `queue` giữ hình dạng tuần tự hóa cũ bằng cách gửi các yêu cầu `turn/steer` +- `steer` gom các tin nhắn đã xếp hàng trong cửa sổ yên lặng đã cấu hình, sau đó gửi một + yêu cầu `turn/steer` duy nhất với toàn bộ dữ liệu nhập của người dùng đã thu thập theo thứ tự đến. +- `queue` giữ dạng tuần tự cũ bằng cách gửi các yêu cầu `turn/steer` riêng biệt. - `followup`, `collect`, `steer-backlog`, và `interrupt` vẫn là hành vi hàng đợi do OpenClaw sở hữu quanh lượt Codex đang hoạt động. Các lượt đánh giá Codex và Compaction thủ công từ chối điều hướng trong cùng lượt. Khi một -runtime không thể chấp nhận điều hướng, OpenClaw quay về hàng đợi tiếp nối khi +runtime không thể chấp nhận điều hướng, OpenClaw quay về hàng đợi theo dõi tiếp nếu chế độ đó cho phép. +Trang này giải thích điều hướng ở chế độ hàng đợi cho các tin nhắn đến thông thường. Đối với +lệnh `/steer ` tường minh, hãy xem [Điều hướng](/vi/tools/steer). + ## Chế độ -| Chế độ | Hành vi khi đang có lượt chạy | Hành vi tiếp nối về sau | -| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `steer` | Chèn tất cả thông báo điều hướng đang chờ cùng lúc tại ranh giới runtime tiếp theo. Đây là mặc định. | Chỉ quay về tiếp nối khi điều hướng không khả dụng. | -| `queue` | Điều hướng lần lượt kiểu cũ. Pi chèn một thông báo đang chờ ở mỗi ranh giới mô hình; Codex gửi các yêu cầu `turn/steer` riêng biệt. | Chỉ quay về tiếp nối khi điều hướng không khả dụng. | -| `steer-backlog` | Cùng hành vi điều hướng khi đang có lượt chạy như `steer`. | Cũng giữ cùng thông báo đó cho một lượt tiếp nối về sau. | -| `followup` | Không điều hướng lượt chạy hiện tại. | Chạy các thông báo đang chờ sau. | -| `collect` | Không điều hướng lượt chạy hiện tại. | Gộp các thông báo đang chờ tương thích thành một lượt về sau sau khoảng debounce. | -| `interrupt` | Hủy lượt chạy đang hoạt động, sau đó bắt đầu thông báo mới nhất. | Không có. | +| Chế độ | Hành vi khi lượt chạy đang hoạt động | Hành vi theo dõi tiếp về sau | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `steer` | Chèn toàn bộ tin nhắn điều hướng đã xếp hàng cùng lúc tại ranh giới runtime tiếp theo. Đây là mặc định. | Chỉ quay về theo dõi tiếp khi điều hướng không khả dụng. | +| `queue` | Điều hướng từng tin nhắn theo kiểu cũ. Pi chèn một tin nhắn đã xếp hàng cho mỗi ranh giới mô hình; Codex gửi các yêu cầu `turn/steer` riêng biệt. | Chỉ quay về theo dõi tiếp khi điều hướng không khả dụng. | +| `steer-backlog` | Cùng hành vi điều hướng khi lượt chạy đang hoạt động như `steer`. | Cũng giữ cùng tin nhắn cho một lượt theo dõi tiếp về sau. | +| `followup` | Không điều hướng lượt chạy hiện tại. | Chạy các tin nhắn đã xếp hàng sau. | +| `collect` | Không điều hướng lượt chạy hiện tại. | Gộp các tin nhắn đã xếp hàng tương thích thành một lượt sau trong cửa sổ debounce. | +| `interrupt` | Hủy lượt chạy đang hoạt động, sau đó bắt đầu tin nhắn mới nhất. | Không có. | -## Ví dụ cụm dồn +## Ví dụ bùng phát -Nếu bốn người dùng gửi thông báo trong lúc agent đang thực thi một lệnh gọi công cụ: +Nếu bốn người dùng gửi tin nhắn trong lúc agent đang thực thi một lệnh gọi công cụ: -- `steer`: runtime đang hoạt động nhận cả bốn thông báo theo thứ tự đến trước - quyết định mô hình tiếp theo. Pi rút chúng tại ranh giới mô hình tiếp theo; Codex - nhận chúng dưới dạng một `turn/steer` được gom lô. -- `queue`: điều hướng tuần tự hóa kiểu cũ. Pi chèn từng thông báo đang chờ một; +- `steer`: runtime đang hoạt động nhận cả bốn tin nhắn theo thứ tự đến trước + quyết định mô hình tiếp theo. Pi xả chúng tại ranh giới mô hình tiếp theo; Codex + nhận chúng dưới dạng một `turn/steer` theo lô. +- `queue`: điều hướng tuần tự kiểu cũ. Pi chèn từng tin nhắn đã xếp hàng một; Codex nhận các yêu cầu `turn/steer` riêng biệt. -- `collect`: OpenClaw chờ đến khi lượt chạy đang hoạt động kết thúc, sau đó tạo một lượt tiếp nối - với các thông báo đang chờ tương thích sau khoảng debounce. +- `collect`: OpenClaw đợi đến khi lượt chạy đang hoạt động kết thúc, sau đó tạo một lượt theo dõi tiếp + với các tin nhắn đã xếp hàng tương thích sau cửa sổ debounce. ## Phạm vi -Điều hướng luôn nhắm tới lượt chạy phiên hiện đang hoạt động. Nó không tạo phiên mới, -không thay đổi chính sách công cụ của lượt chạy đang hoạt động, cũng không tách thông báo theo người gửi. Trong -các kênh nhiều người dùng, prompt đến đã bao gồm ngữ cảnh người gửi và tuyến, vì vậy -lệnh gọi mô hình tiếp theo có thể thấy ai đã gửi từng thông báo. +Điều hướng luôn nhắm đến lượt chạy phiên đang hoạt động hiện tại. Nó không tạo phiên mới, +thay đổi chính sách công cụ của lượt chạy đang hoạt động, hoặc tách tin nhắn theo người gửi. Trong +các kênh nhiều người dùng, prompt đến đã bao gồm ngữ cảnh người gửi và định tuyến, vì vậy +lệnh gọi mô hình tiếp theo có thể thấy ai đã gửi từng tin nhắn. -Dùng `collect` khi bạn muốn OpenClaw xây dựng một lượt tiếp nối về sau có thể -gộp các thông báo tương thích và giữ nguyên chính sách loại bỏ của hàng đợi tiếp nối. Chỉ dùng -`queue` khi bạn cần hành vi điều hướng từng cái một cũ hơn. +Dùng `collect` khi bạn muốn OpenClaw xây dựng một lượt theo dõi tiếp về sau có thể +gộp các tin nhắn tương thích và bảo toàn chính sách loại bỏ của hàng đợi theo dõi tiếp. Chỉ dùng +`queue` khi bạn cần hành vi điều hướng từng tin nhắn kiểu cũ. ## Debounce -`messages.queue.debounceMs` áp dụng cho việc phân phối tiếp nối, bao gồm `collect`, -`followup`, `steer-backlog`, và phương án dự phòng của `steer` khi điều hướng trong lượt chạy đang hoạt động không -khả dụng. Với Pi, bản thân `steer` đang hoạt động không dùng bộ hẹn giờ debounce vì -Pi tự nhiên gom lô thông báo cho đến ranh giới mô hình tiếp theo. Với harness -Codex gốc, OpenClaw dùng cùng giá trị debounce làm khoảng lặng trước khi -gửi `turn/steer` được gom lô. +`messages.queue.debounceMs` áp dụng cho việc phân phối theo dõi tiếp, bao gồm `collect`, +`followup`, `steer-backlog`, và phương án dự phòng của `steer` khi điều hướng trong lượt chạy đang hoạt động +không khả dụng. Với Pi, bản thân `steer` đang hoạt động không dùng bộ đếm thời gian debounce vì +Pi tự nhiên gom các tin nhắn cho đến ranh giới mô hình tiếp theo. Với harness +Codex gốc, OpenClaw dùng cùng giá trị debounce làm cửa sổ yên lặng trước khi +gửi `turn/steer` theo lô. ## Liên quan - [Hàng đợi lệnh](/vi/concepts/queue) -- [Thông báo](/vi/concepts/messages) +- [Điều hướng](/vi/tools/steer) +- [Tin nhắn](/vi/concepts/messages) - [Vòng lặp agent](/vi/concepts/agent-loop) diff --git a/docs/vi/concepts/queue.md b/docs/vi/concepts/queue.md index 2ece7e2ac..ffa5752c3 100644 --- a/docs/vi/concepts/queue.md +++ b/docs/vi/concepts/queue.md @@ -1,36 +1,36 @@ --- read_when: - - Thay đổi việc thực thi hoặc mức đồng thời của trả lời tự động + - Thay đổi cách thực thi hoặc mức đồng thời của tự động trả lời - Giải thích các chế độ /queue hoặc hành vi điều hướng tin nhắn -summary: Chế độ hàng đợi trả lời tự động, giá trị mặc định và ghi đè theo từng phiên +summary: Các chế độ hàng đợi tự động trả lời, giá trị mặc định và ghi đè theo từng phiên title: Hàng đợi lệnh x-i18n: - generated_at: "2026-05-02T10:39:47Z" + generated_at: "2026-05-04T02:23:18Z" model: gpt-5.5 provider: openai - source_hash: c59ea6802d8bf526f4005db3b1baa87d96a23d561c916f91520e8e641fbaf74f + source_hash: 085aebe7059020f027eb08bb382cce2d253ea117eed0ca77d6ffd208f295acb1 source_path: concepts/queue.md workflow: 16 --- -Chúng tôi tuần tự hóa các lần chạy tự động trả lời đầu vào (mọi kênh) qua một hàng đợi nhỏ trong tiến trình để ngăn nhiều lần chạy agent va chạm với nhau, trong khi vẫn cho phép chạy song song an toàn giữa các phiên. +Chúng tôi tuần tự hóa các lần chạy tự động trả lời đến (tất cả các kênh) thông qua một hàng đợi rất nhỏ trong tiến trình để ngăn nhiều lần chạy agent va chạm với nhau, trong khi vẫn cho phép song song hóa an toàn giữa các phiên. -## Vì sao +## Lý do -- Các lần chạy tự động trả lời có thể tốn kém (lời gọi LLM) và có thể va chạm khi nhiều tin nhắn đầu vào đến sát nhau. -- Tuần tự hóa giúp tránh tranh chấp tài nguyên dùng chung (tệp phiên, nhật ký, stdin của CLI) và giảm khả năng gặp giới hạn tốc độ từ thượng nguồn. +- Các lần chạy tự động trả lời có thể tốn kém (lệnh gọi LLM) và có thể va chạm khi nhiều tin nhắn đến gần nhau. +- Tuần tự hóa giúp tránh cạnh tranh tài nguyên dùng chung (tệp phiên, nhật ký, stdin của CLI) và giảm khả năng gặp giới hạn tốc độ từ thượng nguồn. ## Cách hoạt động - Một hàng đợi FIFO nhận biết lane sẽ xả từng lane với giới hạn đồng thời có thể cấu hình (mặc định là 1 cho các lane chưa cấu hình; main mặc định là 4, subagent là 8). - `runEmbeddedPiAgent` đưa vào hàng đợi theo **khóa phiên** (lane `session:`) để đảm bảo mỗi phiên chỉ có một lần chạy đang hoạt động. -- Sau đó mỗi lần chạy phiên được xếp vào một **lane toàn cục** (`main` theo mặc định) để mức song song tổng thể được giới hạn bởi `agents.defaults.maxConcurrent`. -- Khi bật ghi nhật ký chi tiết, các lần chạy trong hàng đợi sẽ phát một thông báo ngắn nếu chúng đã chờ hơn khoảng 2 giây trước khi bắt đầu. -- Chỉ báo đang nhập vẫn kích hoạt ngay khi đưa vào hàng đợi (khi kênh hỗ trợ), nên trải nghiệm người dùng không đổi trong khi chờ đến lượt. +- Mỗi lần chạy phiên sau đó được đưa vào một **lane toàn cục** (`main` theo mặc định) để tổng mức song song hóa được giới hạn bởi `agents.defaults.maxConcurrent`. +- Khi bật ghi nhật ký chi tiết, các lần chạy đang chờ sẽ phát ra một thông báo ngắn nếu chúng đã chờ hơn khoảng 2 giây trước khi bắt đầu. +- Chỉ báo đang nhập vẫn kích hoạt ngay khi đưa vào hàng đợi (khi kênh hỗ trợ), nên trải nghiệm người dùng không thay đổi trong lúc chờ đến lượt. -## Giá trị mặc định +## Mặc định -Khi chưa đặt, tất cả bề mặt kênh đầu vào dùng: +Khi chưa đặt, tất cả bề mặt kênh đến sử dụng: - `mode: "steer"` - `debounceMs: 500` @@ -38,29 +38,30 @@ Khi chưa đặt, tất cả bề mặt kênh đầu vào dùng: - `drop: "summarize"` `steer` là mặc định vì nó giữ lượt mô hình đang hoạt động phản hồi nhanh mà không -khởi động lần chạy phiên thứ hai. Nó xả tất cả tin nhắn điều hướng đã đến +bắt đầu lần chạy phiên thứ hai. Nó xả tất cả tin nhắn điều hướng đã đến trước ranh giới mô hình tiếp theo. Nếu lần chạy hiện tại không thể nhận điều hướng, -OpenClaw sẽ chuyển dự phòng sang một mục hàng đợi followup. +OpenClaw sẽ quay về một mục hàng đợi followup. ## Chế độ hàng đợi -Tin nhắn đầu vào có thể điều hướng lần chạy hiện tại, chờ một lượt followup, hoặc làm cả hai: +Tin nhắn đến có thể điều hướng lần chạy hiện tại, chờ một lượt followup, hoặc làm cả hai: -- `steer`: xếp tin nhắn điều hướng vào runtime đang hoạt động. Pi gửi tất cả tin nhắn điều hướng đang chờ **sau khi lượt assistant hiện tại chạy xong các lời gọi công cụ**, trước lời gọi LLM tiếp theo; Codex app-server nhận một `turn/steer` được gom lô. Nếu lần chạy không đang stream tích cực hoặc không có điều hướng, OpenClaw sẽ chuyển dự phòng sang một mục hàng đợi followup. -- `queue` (cũ): điều hướng từng mục một kiểu cũ. Pi gửi một tin nhắn điều hướng đã xếp hàng tại mỗi ranh giới mô hình; Codex app-server nhận các yêu cầu `turn/steer` riêng biệt. Ưu tiên `steer` trừ khi bạn cần hành vi tuần tự hóa trước đây. -- `followup`: đưa từng tin nhắn vào hàng đợi cho một lượt agent sau khi lần chạy hiện tại kết thúc. -- `collect`: gộp các tin nhắn đã xếp hàng thành **một** lượt followup duy nhất sau khoảng lặng. Nếu tin nhắn nhắm đến các kênh/luồng khác nhau, chúng được xả riêng lẻ để giữ nguyên định tuyến. -- `steer-backlog` (còn gọi là `steer+backlog`): điều hướng ngay **và** giữ lại cùng tin nhắn đó cho một lượt followup. +- `steer`: đưa tin nhắn điều hướng vào runtime đang hoạt động. Pi gửi tất cả tin nhắn điều hướng đang chờ **sau khi lượt assistant hiện tại hoàn tất việc thực thi các lệnh gọi công cụ**, trước lệnh gọi LLM tiếp theo; Codex app-server nhận một `turn/steer` theo lô. Nếu lần chạy không đang stream chủ động hoặc điều hướng không khả dụng, OpenClaw sẽ quay về một mục hàng đợi followup. +- `queue` (cũ): điều hướng cũ từng tin một. Pi gửi một tin nhắn điều hướng đã xếp hàng tại mỗi ranh giới mô hình; Codex app-server nhận các yêu cầu `turn/steer` riêng biệt. Ưu tiên `steer` trừ khi bạn cần hành vi tuần tự hóa trước đó. +- `followup`: đưa từng tin nhắn vào hàng đợi cho một lượt agent sau đó, sau khi lần chạy hiện tại kết thúc. +- `collect`: gộp các tin nhắn đã xếp hàng thành một lượt followup **duy nhất** sau cửa sổ yên lặng. Nếu các tin nhắn nhắm đến các kênh/luồng khác nhau, chúng sẽ được xả riêng lẻ để bảo toàn định tuyến. +- `steer-backlog` (còn gọi là `steer+backlog`): điều hướng ngay **và** giữ nguyên cùng tin nhắn đó cho một lượt followup. - `interrupt` (cũ): hủy lần chạy đang hoạt động cho phiên đó, rồi chạy tin nhắn mới nhất. -Steer-backlog nghĩa là bạn có thể nhận phản hồi followup sau lần chạy đã được điều hướng, nên -các bề mặt streaming có thể trông như bị trùng lặp. Ưu tiên `collect`/`steer` nếu bạn muốn -một phản hồi cho mỗi tin nhắn đầu vào. +Steer-backlog nghĩa là bạn có thể nhận được phản hồi followup sau lần chạy đã được điều hướng, nên +các bề mặt streaming có thể trông giống như bị trùng lặp. Ưu tiên `collect`/`steer` nếu bạn muốn +một phản hồi cho mỗi tin nhắn đến. Để biết thời điểm và hành vi phụ thuộc theo từng runtime, xem -[Hàng đợi điều hướng](/vi/concepts/queue-steering). +[Hàng đợi điều hướng](/vi/concepts/queue-steering). Đối với lệnh rõ ràng `/steer `, +xem [Điều hướng](/vi/tools/steer). -Cấu hình toàn cục hoặc theo từng kênh qua `messages.queue`: +Cấu hình toàn cục hoặc theo kênh qua `messages.queue`: ```json5 { @@ -78,12 +79,12 @@ Cấu hình toàn cục hoặc theo từng kênh qua `messages.queue`: ## Tùy chọn hàng đợi -Các tùy chọn áp dụng cho `followup`, `collect`, và `steer-backlog` (và cho `steer` hoặc `queue` cũ khi điều hướng chuyển dự phòng sang followup): +Các tùy chọn áp dụng cho `followup`, `collect`, và `steer-backlog` (và cho `steer` hoặc `queue` cũ khi điều hướng quay về followup): -- `debounceMs`: khoảng lặng trước khi xả các followup đã xếp hàng. Số trần là mili giây; các đơn vị `ms`, `s`, `m`, `h`, và `d` được tùy chọn `/queue` chấp nhận. -- `cap`: số tin nhắn tối đa trong hàng đợi cho mỗi phiên. Giá trị dưới `1` bị bỏ qua. -- `drop: "summarize"`: mặc định. Loại bỏ các mục cũ nhất trong hàng đợi khi cần, giữ lại bản tóm tắt gọn, và chèn chúng dưới dạng prompt followup tổng hợp. -- `drop: "old"`: loại bỏ các mục cũ nhất trong hàng đợi khi cần, không giữ lại bản tóm tắt. +- `debounceMs`: cửa sổ yên lặng trước khi xả các followup đã xếp hàng. Số trần là mili giây; các đơn vị `ms`, `s`, `m`, `h`, và `d` được tùy chọn `/queue` chấp nhận. +- `cap`: số tin nhắn tối đa đã xếp hàng trên mỗi phiên. Các giá trị dưới `1` bị bỏ qua. +- `drop: "summarize"`: mặc định. Loại bỏ các mục đã xếp hàng cũ nhất khi cần, giữ các bản tóm tắt gọn, và chèn chúng dưới dạng prompt followup tổng hợp. +- `drop: "old"`: loại bỏ các mục đã xếp hàng cũ nhất khi cần, mà không giữ bản tóm tắt. - `drop: "new"`: từ chối tin nhắn mới nhất khi hàng đợi đã đầy. Mặc định: `debounceMs: 500`, `cap: 20`, `drop: summarize`. @@ -95,37 +96,38 @@ Mặc định: `debounceMs: 500`, `cap: 20`, `drop: summarize`. 1. Ghi đè `/queue` nội tuyến hoặc đã lưu theo phiên. 2. `messages.queue.byChannel.`. 3. `messages.queue.mode`. -4. Mặc định `steer`. +4. `steer` mặc định. -Đối với tùy chọn, các tùy chọn `/queue` nội tuyến hoặc đã lưu sẽ thắng cấu hình. Sau đó -debounce theo kênh (`messages.queue.debounceMsByChannel`), mặc định debounce của Plugin, -tùy chọn `messages.queue` toàn cục, và mặc định tích hợp sẵn được -áp dụng. `cap` và `drop` là tùy chọn toàn cục/phiên, không phải khóa cấu hình -theo kênh. +Đối với tùy chọn, các tùy chọn `/queue` nội tuyến hoặc đã lưu thắng cấu hình. Sau đó +debounce theo kênh (`messages.queue.debounceMsByChannel`), mặc định debounce của plugin, +các tùy chọn `messages.queue` toàn cục, và mặc định tích hợp sẵn sẽ được +áp dụng. `cap` và `drop` là các tùy chọn toàn cục/phiên, không phải khóa +cấu hình theo kênh. ## Ghi đè theo phiên -- Gửi `/queue ` như một lệnh độc lập để lưu chế độ cho phiên hiện tại. +- Gửi `/queue ` dưới dạng lệnh độc lập để lưu chế độ cho phiên hiện tại. - Có thể kết hợp các tùy chọn: `/queue collect debounce:0.5s cap:25 drop:summarize` - `/queue default` hoặc `/queue reset` xóa ghi đè phiên. -## Phạm vi và bảo đảm +## Phạm vi và đảm bảo -- Áp dụng cho các lần chạy agent tự động trả lời trên mọi kênh đầu vào dùng pipeline phản hồi Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, v.v.). -- Lane mặc định (`main`) áp dụng toàn tiến trình cho đầu vào + Heartbeat chính; đặt `agents.defaults.maxConcurrent` để cho phép nhiều phiên chạy song song. -- Có thể tồn tại các lane bổ sung (ví dụ `cron`, `cron-nested`, `nested`, `subagent`) để các tác vụ nền có thể chạy song song mà không chặn phản hồi đầu vào. Các lượt agent cron cô lập giữ một slot `cron` trong khi phần thực thi agent bên trong dùng `cron-nested`; cả hai dùng `cron.maxConcurrentRuns`. Các luồng `nested` không phải cron dùng chung giữ hành vi lane riêng. Các lần chạy tách rời này được theo dõi như [tác vụ nền](/vi/automation/tasks). -- Lane theo phiên đảm bảo mỗi lần chỉ một lần chạy agent chạm vào một phiên nhất định. -- Không có phụ thuộc bên ngoài hoặc luồng worker nền; chỉ TypeScript + promise thuần. +- Áp dụng cho các lần chạy agent tự động trả lời trên tất cả các kênh đến dùng pipeline trả lời Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, v.v.). +- Lane mặc định (`main`) có phạm vi toàn tiến trình cho tin nhắn đến + main Heartbeat; đặt `agents.defaults.maxConcurrent` để cho phép nhiều phiên chạy song song. +- Có thể tồn tại các lane bổ sung (ví dụ: `cron`, `cron-nested`, `nested`, `subagent`) để các tác vụ nền có thể chạy song song mà không chặn trả lời đến. Các lượt agent cron cô lập giữ một slot `cron` trong khi phần thực thi agent bên trong dùng `cron-nested`; cả hai dùng `cron.maxConcurrentRuns`. Các luồng `nested` không phải cron dùng chung vẫn giữ hành vi lane riêng. Các lần chạy tách rời này được theo dõi dưới dạng [tác vụ nền](/vi/automation/tasks). +- Các lane theo phiên đảm bảo rằng chỉ một lần chạy agent chạm vào một phiên nhất định tại một thời điểm. +- Không có phụ thuộc bên ngoài hoặc luồng worker nền; thuần TypeScript + promise. ## Khắc phục sự cố -- Nếu các lệnh có vẻ bị kẹt, hãy bật nhật ký chi tiết và tìm các dòng “queued for …ms” để xác nhận hàng đợi đang xả. +- Nếu lệnh có vẻ bị kẹt, hãy bật nhật ký chi tiết và tìm các dòng “queued for …ms” để xác nhận hàng đợi đang xả. - Nếu bạn cần độ sâu hàng đợi, hãy bật nhật ký chi tiết và theo dõi các dòng thời gian hàng đợi. -- Các lần chạy Codex app-server chấp nhận một lượt rồi ngừng phát tiến trình sẽ bị adapter Codex ngắt để lane phiên đang hoạt động có thể nhả ra thay vì chờ hết thời gian chờ của lần chạy bên ngoài. -- Khi bật chẩn đoán, các phiên vẫn ở trạng thái `processing` quá `diagnostics.stuckSessionWarnMs` mà không quan sát thấy phản hồi, công cụ, trạng thái, khối, hoặc tiến trình ACP sẽ được phân loại theo hoạt động hiện tại. Công việc đang hoạt động ghi nhật ký là `session.long_running`; công việc đang hoạt động nhưng không có tiến trình gần đây ghi nhật ký là `session.stalled`; `session.stuck` được dành cho sổ sách phiên đã cũ không có công việc đang hoạt động, và chỉ đường dẫn đó mới có thể nhả lane phiên bị ảnh hưởng để công việc trong hàng đợi được xả. Chẩn đoán `session.stuck` lặp lại sẽ lùi dần trong khi phiên vẫn không đổi. +- Các lần chạy Codex app-server nhận một lượt rồi ngừng phát tiến độ sẽ bị adapter Codex ngắt để lane phiên đang hoạt động có thể được giải phóng thay vì chờ hết thời gian chờ của lần chạy bên ngoài. +- Khi bật chẩn đoán, các phiên vẫn ở trạng thái `processing` quá `diagnostics.stuckSessionWarnMs` mà không quan sát thấy trả lời, công cụ, trạng thái, khối, hoặc tiến độ ACP sẽ được phân loại theo hoạt động hiện tại. Công việc đang hoạt động ghi nhật ký là `session.long_running`; công việc đang hoạt động nhưng không có tiến độ gần đây ghi nhật ký là `session.stalled`; `session.stuck` được dành cho sổ sách phiên cũ không có công việc đang hoạt động, và chỉ đường dẫn đó mới có thể giải phóng lane phiên bị ảnh hưởng để công việc đã xếp hàng được xả. Các chẩn đoán `session.stuck` lặp lại sẽ lùi dần trong khi phiên vẫn không thay đổi. ## Liên quan - [Quản lý phiên](/vi/concepts/session) - [Hàng đợi điều hướng](/vi/concepts/queue-steering) +- [Điều hướng](/vi/tools/steer) - [Chính sách thử lại](/vi/concepts/retry) diff --git a/docs/vi/concepts/system-prompt.md b/docs/vi/concepts/system-prompt.md index 1fe008be8..8ed227f21 100644 --- a/docs/vi/concepts/system-prompt.md +++ b/docs/vi/concepts/system-prompt.md @@ -2,151 +2,152 @@ read_when: - Chỉnh sửa văn bản lời nhắc hệ thống, danh sách công cụ hoặc các phần thời gian/Heartbeat - Thay đổi hành vi khởi tạo không gian làm việc hoặc chèn Skills -summary: Lời nhắc hệ thống của OpenClaw chứa gì và được lắp ráp như thế nào +summary: Lời nhắc hệ thống OpenClaw chứa những gì và được xây dựng như thế nào title: Lời nhắc hệ thống x-i18n: - generated_at: "2026-05-03T21:30:40Z" + generated_at: "2026-05-04T02:23:28Z" model: gpt-5.5 provider: openai - source_hash: 93533ac8090897a7b5fd82b80e542a4ad573670408314b3519c5e317d0408ade + source_hash: 5e6067e760eccf58106f0a646c2656e902d5951580abd750f342d70b0568b81b source_path: concepts/system-prompt.md workflow: 16 --- -OpenClaw xây dựng một system prompt tùy chỉnh cho mỗi lần chạy agent. Prompt này thuộc **sở hữu của OpenClaw** và không dùng prompt mặc định của pi-coding-agent. +OpenClaw tạo một system prompt tùy chỉnh cho mỗi lần chạy agent. Prompt này thuộc **sở hữu của OpenClaw** và không dùng prompt mặc định của pi-coding-agent. -Prompt được OpenClaw lắp ráp và tiêm vào mỗi lần chạy agent. +Prompt được OpenClaw lắp ráp và chèn vào từng lần chạy agent. -Các Plugin nhà cung cấp có thể đóng góp hướng dẫn prompt nhận biết bộ nhớ đệm mà không thay thế +Plugin nhà cung cấp có thể đóng góp hướng dẫn prompt nhận biết cache mà không thay thế toàn bộ prompt thuộc sở hữu của OpenClaw. Runtime của nhà cung cấp có thể: -- thay thế một tập nhỏ các phần lõi có tên (`interaction_style`, +- thay thế một tập nhỏ các phần lõi được đặt tên (`interaction_style`, `tool_call_style`, `execution_bias`) -- tiêm một **tiền tố ổn định** phía trên ranh giới bộ nhớ đệm prompt -- tiêm một **hậu tố động** phía dưới ranh giới bộ nhớ đệm prompt +- chèn một **tiền tố ổn định** phía trên ranh giới prompt cache +- chèn một **hậu tố động** phía dưới ranh giới prompt cache -Dùng các đóng góp do nhà cung cấp sở hữu cho việc tinh chỉnh theo từng họ mô hình. Giữ lại cơ chế đột biến prompt -`before_prompt_build` cũ để tương thích hoặc cho các thay đổi prompt thực sự mang tính toàn cục, +Dùng các đóng góp do nhà cung cấp sở hữu để tinh chỉnh riêng cho từng họ mô hình. Giữ cơ chế thay đổi prompt cũ +`before_prompt_build` cho mục đích tương thích hoặc các thay đổi prompt thực sự mang tính toàn cục, không phải hành vi nhà cung cấp thông thường. -Lớp phủ cho họ OpenAI GPT-5 giữ quy tắc thực thi lõi ở mức nhỏ và thêm -hướng dẫn dành riêng cho mô hình về việc bám persona, đầu ra súc tích, kỷ luật dùng công cụ, -tra cứu song song, bao phủ sản phẩm bàn giao, xác minh, thiếu ngữ cảnh, và +Lớp phủ họ OpenAI GPT-5 giữ quy tắc thực thi lõi nhỏ gọn và bổ sung +hướng dẫn riêng cho mô hình về việc bám persona, đầu ra súc tích, kỷ luật dùng công cụ, +tra cứu song song, bao phủ sản phẩm bàn giao, xác minh, ngữ cảnh thiếu, và vệ sinh công cụ terminal. ## Cấu trúc Prompt được cố ý giữ gọn và dùng các phần cố định: -- **Công cụ**: nhắc nhở về nguồn chân lý cho công cụ có cấu trúc cùng hướng dẫn dùng công cụ ở runtime. -- **Thiên hướng thực thi**: hướng dẫn theo sát gọn nhẹ: hành động ngay trong lượt với - các yêu cầu có thể thực hiện, tiếp tục cho đến khi xong hoặc bị chặn, phục hồi từ kết quả công cụ yếu, +- **Công cụ**: nhắc rằng nguồn sự thật là structured-tool cùng với hướng dẫn dùng công cụ runtime. +- **Thiên hướng thực thi**: hướng dẫn theo đến cùng gọn nhẹ: hành động trong lượt với + các yêu cầu có thể xử lý, tiếp tục cho đến khi xong hoặc bị chặn, phục hồi từ kết quả công cụ yếu, kiểm tra trực tiếp trạng thái có thể thay đổi, và xác minh trước khi hoàn tất. -- **An toàn**: nhắc nhở rào chắn ngắn để tránh hành vi tìm kiếm quyền lực hoặc vượt qua giám sát. -- **Skills** (khi có): cho mô hình biết cách tải hướng dẫn skill theo nhu cầu. -- **OpenClaw tự cập nhật**: cách kiểm tra cấu hình an toàn bằng - `config.schema.lookup`, vá cấu hình bằng `config.patch`, thay thế toàn bộ - cấu hình bằng `config.apply`, và chỉ chạy `update.run` khi người dùng yêu cầu - rõ ràng. Công cụ chỉ dành cho chủ sở hữu `gateway` cũng từ chối viết lại - `tools.exec.ask` / `tools.exec.security`, bao gồm cả các bí danh cũ `tools.bash.*` +- **An toàn**: lời nhắc guardrail ngắn để tránh hành vi tìm kiếm quyền lực hoặc vượt qua giám sát. +- **Skills** (khi có): cho mô hình biết cách tải hướng dẫn skill khi cần. +- **Tự cập nhật OpenClaw**: cách kiểm tra config an toàn bằng + `config.schema.lookup`, vá config bằng `config.patch`, thay thế toàn bộ + config bằng `config.apply`, và chỉ chạy `update.run` khi người dùng + yêu cầu rõ ràng. Công cụ `gateway` chỉ dành cho owner cũng từ chối viết lại + `tools.exec.ask` / `tools.exec.security`, bao gồm các bí danh cũ `tools.bash.*` được chuẩn hóa về các đường dẫn exec được bảo vệ đó. - **Workspace**: thư mục làm việc (`agents.defaults.workspace`). -- **Tài liệu**: đường dẫn cục bộ tới tài liệu OpenClaw (repo hoặc npm package) và khi nào cần đọc. -- **Tệp workspace (được tiêm)**: cho biết các tệp bootstrap được bao gồm bên dưới. -- **Sandbox** (khi bật): cho biết runtime được sandbox, các đường dẫn sandbox, và liệu exec nâng quyền có khả dụng hay không. -- **Ngày & giờ hiện tại**: giờ cục bộ của người dùng, múi giờ, và định dạng thời gian. +- **Tài liệu**: đường dẫn cục bộ tới tài liệu OpenClaw (repo hoặc gói npm) và khi nào cần đọc chúng. +- **Tệp Workspace (được chèn)**: cho biết các tệp bootstrap được bao gồm bên dưới. +- **Sandbox** (khi bật): cho biết runtime sandbox, đường dẫn sandbox, và liệu exec nâng quyền có khả dụng hay không. +- **Ngày & Giờ hiện tại**: giờ cục bộ của người dùng, múi giờ, và định dạng giờ. - **Thẻ trả lời**: cú pháp thẻ trả lời tùy chọn cho các nhà cung cấp được hỗ trợ. -- **Heartbeat**: prompt heartbeat và hành vi xác nhận, khi heartbeat được bật cho agent mặc định. +- **Heartbeats**: prompt heartbeat và hành vi ack, khi heartbeat được bật cho agent mặc định. - **Runtime**: host, OS, node, mô hình, gốc repo (khi phát hiện được), mức suy nghĩ (một dòng). - **Lập luận**: mức hiển thị hiện tại + gợi ý bật/tắt /reasoning. OpenClaw giữ nội dung lớn ổn định, bao gồm **Ngữ cảnh dự án**, phía trên -ranh giới bộ nhớ đệm prompt nội bộ. Các phần kênh/phiên dễ thay đổi như +ranh giới prompt cache nội bộ. Các phần kênh/phiên dễ biến động như hướng dẫn nhúng Control UI, **Nhắn tin**, **Giọng nói**, **Ngữ cảnh chat nhóm**, -**Phản ứng**, **Heartbeat**, và **Runtime** được nối thêm phía dưới ranh giới đó -để các backend cục bộ có bộ nhớ đệm tiền tố có thể tái sử dụng tiền tố workspace ổn định -qua các lượt kênh. Mô tả công cụ cũng nên tránh nhúng tên kênh hiện tại +**Phản ứng**, **Heartbeats**, và **Runtime** được nối thêm phía dưới ranh giới đó +để các backend cục bộ có prefix cache có thể tái sử dụng tiền tố workspace ổn định +qua các lượt kênh. Tương tự, mô tả công cụ nên tránh nhúng tên kênh hiện tại khi schema được chấp nhận đã mang chi tiết runtime đó. -Phần Công cụ cũng bao gồm hướng dẫn runtime cho công việc chạy lâu: +Phần Công cụ cũng bao gồm hướng dẫn runtime cho công việc chạy dài: - dùng cron cho việc theo dõi trong tương lai (`check back later`, lời nhắc, công việc lặp lại) - thay vì các vòng lặp ngủ bằng `exec`, thủ thuật trì hoãn `yieldMs`, hoặc lặp lại việc thăm dò `process` + thay vì vòng lặp ngủ `exec`, mẹo trì hoãn `yieldMs`, hoặc thăm dò `process` + lặp lại - dùng `exec` / `process` chỉ cho các lệnh bắt đầu ngay và tiếp tục chạy - ở nền -- khi bật đánh thức hoàn tất tự động, khởi động lệnh một lần và dựa vào - đường đánh thức dựa trên push khi nó phát ra đầu ra hoặc thất bại -- dùng `process` cho nhật ký, trạng thái, đầu vào, hoặc can thiệp khi bạn cần + trong nền +- khi đánh thức hoàn tất tự động được bật, khởi động lệnh một lần và dựa vào + đường dẫn đánh thức dạng push khi nó phát ra output hoặc thất bại +- dùng `process` cho log, trạng thái, input, hoặc can thiệp khi bạn cần kiểm tra một lệnh đang chạy -- nếu tác vụ lớn hơn, ưu tiên `sessions_spawn`; hoàn tất của sub-agent - dựa trên push và tự động thông báo lại cho người yêu cầu +- nếu tác vụ lớn hơn, ưu tiên `sessions_spawn`; việc hoàn tất sub-agent dựa trên + push và tự động thông báo lại cho người yêu cầu - không thăm dò `subagents list` / `sessions_list` trong vòng lặp chỉ để chờ hoàn tất Khi công cụ thử nghiệm `update_plan` được bật, Công cụ cũng yêu cầu -mô hình chỉ dùng nó cho công việc nhiều bước không tầm thường, giữ đúng một bước +mô hình chỉ dùng nó cho công việc nhiều bước không tầm thường, luôn giữ đúng một bước `in_progress`, và tránh lặp lại toàn bộ kế hoạch sau mỗi lần cập nhật. -Các rào chắn an toàn trong system prompt mang tính khuyến nghị. Chúng định hướng hành vi mô hình nhưng không cưỡng chế chính sách. Dùng chính sách công cụ, phê duyệt exec, sandboxing, và danh sách cho phép kênh để cưỡng chế cứng; các toán tử có thể vô hiệu hóa chúng theo thiết kế. +Các guardrail an toàn trong system prompt mang tính khuyến nghị. Chúng hướng dẫn hành vi mô hình nhưng không thực thi chính sách. Dùng chính sách công cụ, phê duyệt exec, sandboxing, và allowlist kênh để thực thi cứng; operator có thể tắt các cơ chế này theo thiết kế. -Trên các kênh có thẻ/nút phê duyệt gốc, runtime prompt hiện yêu cầu -agent trước hết dựa vào UI phê duyệt gốc đó. Nó chỉ nên bao gồm lệnh +Trên các kênh có thẻ/nút phê duyệt gốc, prompt runtime giờ yêu cầu +agent dựa vào UI phê duyệt gốc đó trước. Nó chỉ nên đưa vào lệnh `/approve` thủ công khi kết quả công cụ cho biết phê duyệt qua chat không khả dụng hoặc -phê duyệt thủ công là đường duy nhất. +phê duyệt thủ công là đường dẫn duy nhất. ## Chế độ prompt -OpenClaw có thể kết xuất system prompt nhỏ hơn cho sub-agent. Runtime đặt một -`promptMode` cho mỗi lần chạy (không phải cấu hình hướng tới người dùng): +OpenClaw có thể render system prompt nhỏ hơn cho sub-agent. Runtime đặt +`promptMode` cho mỗi lần chạy (không phải config hướng người dùng): - `full` (mặc định): bao gồm tất cả các phần ở trên. -- `minimal`: dùng cho sub-agent; bỏ qua **Skills**, **Gọi lại bộ nhớ**, **OpenClaw - tự cập nhật**, **Bí danh mô hình**, **Danh tính người dùng**, **Thẻ trả lời**, - **Nhắn tin**, **Trả lời im lặng**, và **Heartbeat**. Công cụ, **An toàn**, - Workspace, Sandbox, Ngày & giờ hiện tại (khi biết), Runtime, và ngữ cảnh được tiêm +- `minimal`: dùng cho sub-agent; bỏ qua **Skills**, **Memory Recall**, **Tự cập nhật OpenClaw**, + **Bí danh mô hình**, **Danh tính người dùng**, **Thẻ trả lời**, + **Nhắn tin**, **Trả lời im lặng**, và **Heartbeats**. Công cụ, **An toàn**, + Workspace, Sandbox, Ngày & Giờ hiện tại (khi biết), Runtime, và ngữ cảnh được chèn vẫn khả dụng. - `none`: chỉ trả về dòng danh tính cơ sở. -Khi `promptMode=minimal`, các prompt được tiêm thêm được gắn nhãn **Ngữ cảnh subagent** +Khi `promptMode=minimal`, các prompt được chèn thêm được gắn nhãn **Ngữ cảnh Subagent** thay vì **Ngữ cảnh chat nhóm**. -Với các lần chạy tự động trả lời theo kênh, OpenClaw có thể bỏ qua phần **Trả lời im lặng** -chung khi ngữ cảnh chat trực tiếp/nhóm đã bao gồm hành vi `NO_REPLY` -cụ thể theo cuộc trò chuyện đã được phân giải. Điều này tránh lặp lại cơ chế token +Đối với các lần chạy tự động trả lời của kênh, OpenClaw có thể bỏ qua phần **Trả lời im lặng** +chung khi ngữ cảnh chat trực tiếp/nhóm đã bao gồm hành vi +`NO_REPLY` riêng cho cuộc trò chuyện đã được phân giải. Điều này tránh lặp lại cơ chế token trong cả system prompt toàn cục và ngữ cảnh kênh. -## Ảnh chụp prompt +## Snapshot prompt -OpenClaw giữ các ảnh chụp prompt đã commit cho đường chạy thành công của runtime Codex dưới -`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Chúng kết xuất -các tham số thread/turn app-server được chọn cùng một ngăn xếp lớp prompt gắn với mô hình được tái dựng -cho các lượt Telegram trực tiếp, Discord nhóm, và heartbeat. Ngăn xếp đó -bao gồm một fixture prompt mô hình Codex `gpt-5.5` được ghim, tạo từ hình dạng -catalog/bộ nhớ đệm mô hình của Codex, văn bản developer quyền hạn đường chạy thành công của Codex, +OpenClaw giữ các snapshot prompt đã commit cho đường chạy ổn định của runtime Codex dưới +`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Chúng render +các tham số thread/turn app-server được chọn cùng với stack lớp prompt ràng buộc mô hình được tái dựng +cho các lượt Telegram trực tiếp, nhóm Discord, và heartbeat. Stack đó +bao gồm fixture prompt mô hình Codex `gpt-5.5` được ghim, tạo từ hình dạng catalog/cache mô hình của Codex, +văn bản developer quyền đường chạy ổn định của Codex, hướng dẫn developer OpenClaw, hướng dẫn chế độ cộng tác theo phạm vi lượt -khi OpenClaw cung cấp chúng, đầu vào lượt người dùng, và tham chiếu tới các đặc tả công cụ động. +khi OpenClaw cung cấp chúng, input lượt người dùng, và tham chiếu tới các spec công cụ động. Làm mới fixture prompt mô hình Codex được ghim bằng `pnpm prompt:snapshots:sync-codex-model`. Theo mặc định, script tìm -bộ nhớ đệm runtime của Codex tại `$CODEX_HOME/models_cache.json`, rồi -`~/.codex/models_cache.json`, và chỉ sau đó mới fallback về quy ước checkout Codex -của maintainer tại `~/code/codex/codex-rs/models-manager/models.json`. Nếu -không có nguồn nào trong số đó tồn tại, lệnh thoát mà không thay đổi -fixture đã commit. Truyền `--catalog ` để làm mới từ một tệp `models_cache.json` +cache runtime của Codex tại `$CODEX_HOME/models_cache.json`, rồi +`~/.codex/models_cache.json`, và chỉ sau đó mới fallback về quy ước checkout Codex của maintainer +tại `~/code/codex/codex-rs/models-manager/models.json`. Nếu +không nguồn nào tồn tại, lệnh thoát mà không thay đổi fixture đã commit. +Truyền `--catalog ` để làm mới từ một tệp `models_cache.json` hoặc `models.json` cụ thể. -Các ảnh chụp này vẫn không phải bản chụp yêu cầu OpenAI thô khớp từng byte. Codex -có thể thêm ngữ cảnh workspace thuộc sở hữu runtime như `AGENTS.md`, ngữ cảnh -môi trường, bộ nhớ, hướng dẫn app/plugin, và hướng dẫn chế độ cộng tác Default +Các snapshot này vẫn không phải bản chụp request OpenAI thô khớp từng byte. Codex +có thể thêm ngữ cảnh workspace do runtime sở hữu như `AGENTS.md`, ngữ cảnh môi trường, +memory, hướng dẫn app/plugin, và hướng dẫn chế độ cộng tác Default tích hợp bên trong runtime Codex sau khi OpenClaw gửi tham số thread và turn. Tạo lại chúng bằng `pnpm prompt:snapshots:gen` và xác minh drift bằng `pnpm prompt:snapshots:check`. CI chạy kiểm tra drift trong shard ranh giới -bổ sung để các thay đổi prompt và cập nhật ảnh chụp luôn gắn với cùng +bổ sung để các thay đổi prompt và cập nhật snapshot vẫn gắn với cùng một PR. -## Tiêm bootstrap workspace +## Chèn bootstrap workspace Các tệp bootstrap được cắt gọn và nối thêm dưới **Ngữ cảnh dự án** để mô hình thấy ngữ cảnh danh tính và hồ sơ mà không cần đọc rõ ràng: @@ -159,74 +160,75 @@ Các tệp bootstrap được cắt gọn và nối thêm dưới **Ngữ cảnh - `BOOTSTRAP.md` (chỉ trên workspace hoàn toàn mới) - `MEMORY.md` khi có -Tất cả các tệp này được **tiêm vào cửa sổ ngữ cảnh** ở mỗi lượt trừ khi -áp dụng cổng riêng theo tệp. `HEARTBEAT.md` bị bỏ qua trong các lần chạy bình thường khi +Tất cả các tệp này được **chèn vào cửa sổ ngữ cảnh** trên mỗi lượt trừ khi +có gate riêng cho tệp được áp dụng. `HEARTBEAT.md` bị bỏ qua trong các lần chạy thông thường khi heartbeat bị tắt cho agent mặc định hoặc -`agents.defaults.heartbeat.includeSystemPromptSection` là false. Giữ các tệp được tiêm -ngắn gọn — đặc biệt là `MEMORY.md`, vốn có thể tăng theo thời gian và dẫn tới +`agents.defaults.heartbeat.includeSystemPromptSection` là false. Giữ các tệp được chèn +súc tích — đặc biệt là `MEMORY.md`, vốn có thể tăng theo thời gian và dẫn đến mức sử dụng ngữ cảnh cao bất ngờ và Compaction thường xuyên hơn. Khi một phiên chạy trên harness Codex gốc, Codex tải `AGENTS.md` thông qua cơ chế khám phá tài liệu dự án riêng. OpenClaw vẫn phân giải các -tệp bootstrap còn lại và chuyển tiếp chúng dưới dạng hướng dẫn cấu hình Codex, vì vậy `SOUL.md`, +tệp bootstrap còn lại và chuyển tiếp chúng như hướng dẫn config Codex, nên `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, và `MEMORY.md` giữ cùng vai trò ngữ cảnh workspace mà không nhân đôi `AGENTS.md`. -Các tệp hằng ngày `memory/*.md` **không** phải một phần của Ngữ cảnh dự án bootstrap thông thường. Ở các lượt bình thường, chúng được truy cập theo nhu cầu qua các công cụ `memory_search` và `memory_get`, vì vậy chúng không tính vào cửa sổ ngữ cảnh trừ khi mô hình đọc chúng một cách rõ ràng. Các lượt `/new` và `/reset` trần là ngoại lệ: runtime có thể thêm trước bộ nhớ hằng ngày gần đây như một khối ngữ cảnh khởi động dùng một lần cho lượt đầu tiên đó. +Các tệp hằng ngày `memory/*.md` **không** phải là một phần của Ngữ cảnh dự án bootstrap thông thường. Trong các lượt bình thường, chúng được truy cập theo nhu cầu qua các công cụ `memory_search` và `memory_get`, nên chúng không tính vào cửa sổ ngữ cảnh trừ khi mô hình đọc chúng rõ ràng. Các lượt `/new` và `/reset` trống là ngoại lệ: runtime có thể thêm trước memory hằng ngày gần đây dưới dạng một khối ngữ cảnh khởi động dùng một lần cho lượt đầu tiên đó. -Các tệp lớn bị cắt ngắn kèm một marker. Kích thước tối đa mỗi tệp được kiểm soát bởi -`agents.defaults.bootstrapMaxChars` (mặc định: 12000). Tổng nội dung bootstrap được tiêm +Các tệp lớn bị cắt ngắn kèm một marker. Kích thước tối đa trên mỗi tệp được kiểm soát bởi +`agents.defaults.bootstrapMaxChars` (mặc định: 12000). Tổng nội dung bootstrap được chèn trên các tệp bị giới hạn bởi `agents.defaults.bootstrapTotalMaxChars` -(mặc định: 60000). Tệp bị thiếu tiêm một marker tệp thiếu ngắn. Khi xảy ra cắt ngắn, -OpenClaw có thể tiêm một khối cảnh báo trong Ngữ cảnh dự án; kiểm soát điều này bằng +(mặc định: 60000). Tệp thiếu sẽ chèn một marker thiếu tệp ngắn. Khi việc cắt ngắn +xảy ra, OpenClaw có thể chèn một thông báo cảnh báo system-prompt súc tích; kiểm soát điều này bằng `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; -mặc định: `once`). +mặc định: `once`). Số đếm raw/được chèn chi tiết vẫn nằm trong chẩn đoán như +`/context`, `/status`, doctor, và log. -Các phiên sub-agent chỉ tiêm `AGENTS.md` và `TOOLS.md` (các tệp bootstrap khác +Các phiên sub-agent chỉ chèn `AGENTS.md` và `TOOLS.md` (các tệp bootstrap khác được lọc ra để giữ ngữ cảnh sub-agent nhỏ). -Các hook nội bộ có thể chặn bước này qua `agent:bootstrap` để đột biến hoặc thay thế -các tệp bootstrap được tiêm (ví dụ thay `SOUL.md` bằng một persona thay thế). +Hook nội bộ có thể chặn bước này qua `agent:bootstrap` để thay đổi hoặc thay thế +các tệp bootstrap được chèn (ví dụ đổi `SOUL.md` sang một persona thay thế). -Nếu bạn muốn làm agent nghe bớt chung chung, hãy bắt đầu với +Nếu bạn muốn làm agent nghe bớt chung chung hơn, hãy bắt đầu với [Hướng dẫn tính cách SOUL.md](/vi/concepts/soul). -Để kiểm tra mỗi tệp được tiêm đóng góp bao nhiêu (thô so với được tiêm, cắt ngắn, cộng thêm phần vượt mức schema công cụ), dùng `/context list` hoặc `/context detail`. Xem [Ngữ cảnh](/vi/concepts/context). +Để kiểm tra mỗi tệp được chèn đóng góp bao nhiêu (raw so với được chèn, cắt ngắn, cộng với overhead schema công cụ), dùng `/context list` hoặc `/context detail`. Xem [Ngữ cảnh](/vi/concepts/context). ## Xử lý thời gian -System prompt bao gồm phần **Ngày & giờ hiện tại** riêng khi biết -múi giờ của người dùng. Để giữ prompt ổn định với bộ nhớ đệm, hiện nó chỉ bao gồm -**múi giờ** (không có đồng hồ động hoặc định dạng thời gian). +System prompt bao gồm một phần **Ngày & Giờ hiện tại** riêng khi +múi giờ của người dùng được biết. Để giữ prompt ổn định với cache, giờ nó chỉ bao gồm +**múi giờ** (không có đồng hồ động hoặc định dạng giờ). Dùng `session_status` khi agent cần thời gian hiện tại; thẻ trạng thái -bao gồm một dòng timestamp. Cùng công cụ đó có thể tùy chọn đặt ghi đè mô hình theo phiên -(`model=default` xóa nó). +bao gồm một dòng timestamp. Cùng công cụ đó có thể tùy chọn đặt override mô hình theo phiên +(`model=default` sẽ xóa nó). Cấu hình bằng: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Xem [Ngày & giờ](/vi/date-time) để biết đầy đủ chi tiết hành vi. +Xem [Ngày & Giờ](/vi/date-time) để biết đầy đủ chi tiết hành vi. ## Skills -Khi tồn tại các skill đủ điều kiện, OpenClaw tiêm một **danh sách skills khả dụng** -gọn nhẹ (`formatSkillsForPrompt`) bao gồm **đường dẫn tệp** cho mỗi skill. Prompt +Khi có skill đủ điều kiện, OpenClaw chèn một **danh sách skills khả dụng** gọn +(`formatSkillsForPrompt`) bao gồm **đường dẫn tệp** cho mỗi skill. Prompt hướng dẫn mô hình dùng `read` để tải SKILL.md tại vị trí được liệt kê (workspace, managed, hoặc bundled). Nếu không có skill nào đủ điều kiện, phần Skills bị bỏ qua. -Tính đủ điều kiện bao gồm các cổng metadata skill, kiểm tra môi trường/cấu hình runtime, -và danh sách cho phép skill hiệu lực của agent khi `agents.defaults.skills` hoặc +Điều kiện đủ bao gồm các gate metadata skill, kiểm tra môi trường/config runtime, +và allowlist skill hiệu dụng của agent khi `agents.defaults.skills` hoặc `agents.list[].skills` được cấu hình. -Skills được đóng gói cùng Plugin chỉ đủ điều kiện khi Plugin sở hữu chúng được bật. -Điều này cho phép các Plugin công cụ phơi bày hướng dẫn vận hành sâu hơn mà không nhúng tất cả +Skills được bundled theo Plugin chỉ đủ điều kiện khi Plugin sở hữu chúng được bật. +Điều này cho phép Plugin công cụ phơi bày các hướng dẫn vận hành sâu hơn mà không nhúng toàn bộ hướng dẫn đó trực tiếp vào mọi mô tả công cụ. ``` @@ -241,26 +243,26 @@ hướng dẫn đó trực tiếp vào mọi mô tả công cụ. Điều này giữ prompt cơ sở nhỏ trong khi vẫn cho phép dùng skill có mục tiêu. -Ngân sách danh sách skills thuộc sở hữu của phân hệ skills: +Ngân sách danh sách skills thuộc sở hữu của hệ thống con skills: - Mặc định toàn cục: `skills.limits.maxSkillsPromptChars` -- Ghi đè theo agent: `agents.list[].skillsLimits.maxSkillsPromptChars` +- Ghi đè theo từng tác tử: `agents.list[].skillsLimits.maxSkillsPromptChars` -Các đoạn trích thời gian chạy có giới hạn chung dùng một bề mặt khác: +Các trích đoạn thời gian chạy giới hạn chung dùng một bề mặt khác: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Sự phân tách đó giữ kích thước Skills tách biệt với kích thước đọc/chèn thời gian chạy như `memory_get`, kết quả công cụ trực tiếp, và các lần làm mới AGENTS.md sau Compaction. +Sự tách biệt đó giữ việc định cỡ Skills riêng với việc định cỡ đọc/chèn thời gian chạy, chẳng hạn như `memory_get`, kết quả công cụ trực tiếp, và các lần làm mới AGENTS.md sau Compaction. ## Tài liệu -Lời nhắc hệ thống bao gồm một phần **Tài liệu**. Khi có tài liệu cục bộ, phần này trỏ đến thư mục tài liệu OpenClaw cục bộ (`docs/` trong Git checkout hoặc tài liệu gói npm đi kèm). Nếu không có tài liệu cục bộ, nó sẽ dùng dự phòng [https://docs.openclaw.ai](https://docs.openclaw.ai). +Prompt hệ thống bao gồm một phần **Tài liệu**. Khi có tài liệu cục bộ, phần này trỏ đến thư mục tài liệu OpenClaw cục bộ (`docs/` trong một bản checkout Git hoặc tài liệu gói npm đi kèm). Nếu không có tài liệu cục bộ, nó quay về [https://docs.openclaw.ai](https://docs.openclaw.ai). -Cùng phần đó cũng bao gồm vị trí mã nguồn OpenClaw. Git checkout cung cấp thư mục gốc mã nguồn cục bộ để tác tử có thể kiểm tra mã trực tiếp. Các bản cài đặt gói bao gồm URL mã nguồn GitHub và yêu cầu tác tử xem lại mã nguồn ở đó bất cứ khi nào tài liệu chưa đầy đủ hoặc đã lỗi thời. Lời nhắc cũng ghi chú mirror tài liệu công khai, Discord cộng đồng, và ClawHub ([https://clawhub.ai](https://clawhub.ai)) để khám phá Skills. Nó yêu cầu mô hình tham khảo tài liệu trước tiên về hành vi, lệnh, cấu hình, hoặc kiến trúc của OpenClaw, và tự chạy `openclaw status` khi có thể (chỉ hỏi người dùng khi không có quyền truy cập). Riêng đối với cấu hình, nó trỏ tác tử đến hành động công cụ `gateway` `config.schema.lookup` để xem tài liệu và ràng buộc chính xác ở cấp trường, sau đó đến `docs/gateway/configuration.md` và `docs/gateway/configuration-reference.md` để được hướng dẫn rộng hơn. +Phần này cũng bao gồm vị trí mã nguồn OpenClaw. Các bản checkout Git hiển thị gốc nguồn cục bộ để tác tử có thể kiểm tra mã trực tiếp. Các bản cài đặt gói bao gồm URL nguồn GitHub và yêu cầu tác tử xem lại nguồn ở đó bất cứ khi nào tài liệu chưa đầy đủ hoặc đã lỗi thời. Prompt cũng ghi chú bản sao công khai của tài liệu, Discord cộng đồng, và ClawHub ([https://clawhub.ai](https://clawhub.ai)) để khám phá Skills. Nó yêu cầu mô hình tham khảo tài liệu trước đối với hành vi, lệnh, cấu hình, hoặc kiến trúc của OpenClaw, và tự chạy `openclaw status` khi có thể (chỉ hỏi người dùng khi nó không có quyền truy cập). Riêng với cấu hình, nó trỏ tác tử đến hành động công cụ `gateway` `config.schema.lookup` để có tài liệu và ràng buộc chính xác ở cấp trường, sau đó đến `docs/gateway/configuration.md` và `docs/gateway/configuration-reference.md` để có hướng dẫn rộng hơn. ## Liên quan -- [Thời gian chạy tác tử](/vi/concepts/agent) +- [Runtime tác tử](/vi/concepts/agent) - [Không gian làm việc của tác tử](/vi/concepts/agent-workspace) - [Công cụ ngữ cảnh](/vi/concepts/context-engine) diff --git a/docs/vi/gateway/config-agents.md b/docs/vi/gateway/config-agents.md index a98dabdb7..b7cf4f61c 100644 --- a/docs/vi/gateway/config-agents.md +++ b/docs/vi/gateway/config-agents.md @@ -1,24 +1,24 @@ --- read_when: - - Điều chỉnh các giá trị mặc định của tác tử (mô hình, suy luận, không gian làm việc, Heartbeat, phương tiện, Skills) - - Cấu hình định tuyến và liên kết đa tác nhân - - Điều chỉnh phiên, việc gửi tin nhắn và hành vi của chế độ trò chuyện -summary: Mặc định của tác tử, định tuyến đa tác tử, phiên, tin nhắn và cấu hình talk + - Điều chỉnh giá trị mặc định của tác nhân (mô hình, suy nghĩ, không gian làm việc, Heartbeat, phương tiện, Skills) + - Định cấu hình định tuyến đa tác nhân và liên kết + - Điều chỉnh hành vi phiên, gửi tin nhắn và chế độ trò chuyện +summary: Mặc định của tác nhân, định tuyến đa tác nhân, phiên, tin nhắn và cấu hình trò chuyện title: Cấu hình — tác tử x-i18n: - generated_at: "2026-05-03T10:36:29Z" + generated_at: "2026-05-04T02:24:26Z" model: gpt-5.5 provider: openai - source_hash: b25371c34b9f8b0cacce021879e43e6a65b86d626dc87d5bfa05dcae80ac32e4 + source_hash: 9d339b82b8b3b82e55820ca6568b3ed569fe64135e698515fa7f316c3afbbfd9 source_path: gateway/config-agents.md workflow: 16 --- -Các khóa cấu hình theo phạm vi tác tử trong `agents.*`, `multiAgent.*`, `session.*`, -`messages.*` và `talk.*`. Đối với kênh, công cụ, thời gian chạy Gateway và các khóa -cấp cao khác, hãy xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference). +Các khóa cấu hình theo phạm vi tác nhân trong `agents.*`, `multiAgent.*`, `session.*`, +`messages.*` và `talk.*`. Đối với kênh, công cụ, thời gian chạy Gateway và các +khóa cấp cao nhất khác, xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference). -## Mặc định của tác tử +## Mặc định của tác nhân ### `agents.defaults.workspace` @@ -32,7 +32,7 @@ Mặc định: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Gốc kho lưu trữ tùy chọn hiển thị trong dòng Runtime của lời nhắc hệ thống. Nếu không đặt, OpenClaw tự động phát hiện bằng cách đi ngược lên từ không gian làm việc. +Gốc kho lưu trữ tùy chọn được hiển thị trong dòng Runtime của system prompt. Nếu chưa đặt, OpenClaw tự động phát hiện bằng cách đi ngược lên từ workspace. ```json5 { @@ -42,7 +42,7 @@ Gốc kho lưu trữ tùy chọn hiển thị trong dòng Runtime của lời nh ### `agents.defaults.skills` -Danh sách cho phép Skills mặc định tùy chọn cho các tác tử không đặt +Danh sách cho phép Skills mặc định tùy chọn cho các tác nhân không đặt `agents.list[].skills`. ```json5 @@ -61,12 +61,12 @@ Danh sách cho phép Skills mặc định tùy chọn cho các tác tử không - Bỏ qua `agents.defaults.skills` để mặc định không hạn chế Skills. - Bỏ qua `agents.list[].skills` để kế thừa các giá trị mặc định. - Đặt `agents.list[].skills: []` để không có Skills. -- Danh sách `agents.list[].skills` không rỗng là tập cuối cùng cho tác tử đó; nó - không hợp nhất với các giá trị mặc định. +- Danh sách `agents.list[].skills` không rỗng là tập cuối cùng cho tác nhân đó; nó + không hợp nhất với giá trị mặc định. ### `agents.defaults.skipBootstrap` -Tắt tự động tạo các tệp khởi tạo không gian làm việc (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Tắt việc tự động tạo các tệp bootstrap workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -76,7 +76,7 @@ Tắt tự động tạo các tệp khởi tạo không gian làm việc (`AGENT ### `agents.defaults.skipOptionalBootstrapFiles` -Bỏ qua việc tạo các tệp không gian làm việc tùy chọn đã chọn trong khi vẫn ghi các tệp khởi tạo bắt buộc. Giá trị hợp lệ: `SOUL.md`, `USER.md`, `HEARTBEAT.md` và `IDENTITY.md`. +Bỏ qua việc tạo các tệp workspace tùy chọn đã chọn trong khi vẫn ghi các tệp bootstrap bắt buộc. Giá trị hợp lệ: `SOUL.md`, `USER.md`, `HEARTBEAT.md` và `IDENTITY.md`. ```json5 { @@ -90,10 +90,10 @@ Bỏ qua việc tạo các tệp không gian làm việc tùy chọn đã chọn ### `agents.defaults.contextInjection` -Kiểm soát thời điểm các tệp khởi tạo không gian làm việc được chèn vào lời nhắc hệ thống. Mặc định: `"always"`. +Kiểm soát thời điểm các tệp bootstrap workspace được chèn vào system prompt. Mặc định: `"always"`. -- `"continuation-skip"`: các lượt tiếp tục an toàn (sau phản hồi hoàn tất của trợ lý) bỏ qua việc chèn lại khởi tạo không gian làm việc, giảm kích thước lời nhắc. Các lần chạy Heartbeat và các lần thử lại sau Compaction vẫn dựng lại ngữ cảnh. -- `"never"`: tắt khởi tạo không gian làm việc và chèn tệp ngữ cảnh ở mọi lượt. Chỉ dùng tùy chọn này cho các tác tử hoàn toàn tự sở hữu vòng đời lời nhắc của mình (công cụ ngữ cảnh tùy chỉnh, thời gian chạy gốc tự xây dựng ngữ cảnh, hoặc quy trình chuyên biệt không cần khởi tạo). Các lượt Heartbeat và khôi phục sau Compaction cũng bỏ qua chèn. +- `"continuation-skip"`: các lượt tiếp tục an toàn (sau một phản hồi trợ lý đã hoàn tất) bỏ qua việc chèn lại bootstrap workspace, giảm kích thước prompt. Các lần chạy Heartbeat và lần thử lại sau Compaction vẫn dựng lại ngữ cảnh. +- `"never"`: tắt bootstrap workspace và chèn tệp ngữ cảnh ở mọi lượt. Chỉ dùng tùy chọn này cho các tác nhân tự sở hữu hoàn toàn vòng đời prompt của chúng (công cụ ngữ cảnh tùy chỉnh, thời gian chạy gốc tự dựng ngữ cảnh riêng, hoặc quy trình chuyên biệt không cần bootstrap). Các lượt Heartbeat và khôi phục sau Compaction cũng bỏ qua việc chèn. ```json5 { @@ -103,7 +103,7 @@ Kiểm soát thời điểm các tệp khởi tạo không gian làm việc đư ### `agents.defaults.bootstrapMaxChars` -Số ký tự tối đa cho mỗi tệp khởi tạo không gian làm việc trước khi cắt ngắn. Mặc định: `12000`. +Số ký tự tối đa cho mỗi tệp bootstrap workspace trước khi cắt ngắn. Mặc định: `12000`. ```json5 { @@ -113,7 +113,7 @@ Số ký tự tối đa cho mỗi tệp khởi tạo không gian làm việc tr ### `agents.defaults.bootstrapTotalMaxChars` -Tổng số ký tự tối đa được chèn trên tất cả các tệp khởi tạo không gian làm việc. Mặc định: `60000`. +Tổng số ký tự tối đa được chèn trên tất cả các tệp bootstrap workspace. Mặc định: `60000`. ```json5 { @@ -123,12 +123,16 @@ Tổng số ký tự tối đa được chèn trên tất cả các tệp khởi ### `agents.defaults.bootstrapPromptTruncationWarning` -Kiểm soát văn bản cảnh báo hiển thị cho tác tử khi ngữ cảnh khởi tạo bị cắt ngắn. +Kiểm soát thông báo system prompt mà tác nhân nhìn thấy khi ngữ cảnh bootstrap bị cắt ngắn. Mặc định: `"once"`. -- `"off"`: không bao giờ chèn văn bản cảnh báo vào lời nhắc hệ thống. -- `"once"`: chèn cảnh báo một lần cho mỗi chữ ký cắt ngắn duy nhất (khuyến nghị). -- `"always"`: chèn cảnh báo ở mọi lần chạy khi có cắt ngắn. +- `"off"`: không bao giờ chèn văn bản thông báo cắt ngắn vào system prompt. +- `"once"`: chèn thông báo ngắn gọn một lần cho mỗi chữ ký cắt ngắn duy nhất (khuyến nghị). +- `"always"`: chèn thông báo ngắn gọn ở mọi lần chạy khi có cắt ngắn. + +Số đếm thô/đã chèn chi tiết và các trường tinh chỉnh cấu hình vẫn nằm trong chẩn đoán như +báo cáo và nhật ký context/status; ngữ cảnh người dùng/thời gian chạy WebChat thường lệ chỉ +nhận thông báo khôi phục ngắn gọn. ```json5 { @@ -138,33 +142,33 @@ Mặc định: `"once"`. ### Bản đồ sở hữu ngân sách ngữ cảnh -OpenClaw có nhiều ngân sách lời nhắc/ngữ cảnh dung lượng lớn, và chúng được -cố ý tách theo phân hệ thay vì tất cả đi qua một núm điều khiển chung. +OpenClaw có nhiều ngân sách prompt/ngữ cảnh dung lượng lớn, và chúng được +cố ý tách theo phân hệ thay vì cùng đi qua một núm điều khiển chung. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - chèn khởi tạo không gian làm việc thông thường. + chèn bootstrap workspace thông thường. - `agents.defaults.startupContext.*`: - phần mở đầu một lần cho lần chạy mô hình khi đặt lại/khởi động, bao gồm các tệp - `memory/*.md` hằng ngày gần đây. Các lệnh chat trần `/new` và `/reset` được + phần mở đầu chạy mô hình khi reset/khởi động một lần, bao gồm các tệp + `memory/*.md` hằng ngày gần đây. Các lệnh chat thuần `/new` và `/reset` được xác nhận mà không gọi mô hình. - `skills.limits.*`: - danh sách Skills rút gọn được chèn vào lời nhắc hệ thống. + danh sách Skills rút gọn được chèn vào system prompt. - `agents.defaults.contextLimits.*`: các đoạn trích thời gian chạy có giới hạn và các khối do thời gian chạy sở hữu được chèn. - `memory.qmd.limits.*`: kích thước đoạn trích tìm kiếm bộ nhớ đã lập chỉ mục và kích thước chèn. -Chỉ dùng ghi đè theo tác tử tương ứng khi một tác tử cần ngân sách khác: +Chỉ dùng ghi đè theo tác nhân tương ứng khi một tác nhân cần ngân sách khác: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -Kiểm soát phần mở đầu khởi động ở lượt đầu được chèn vào các lần chạy mô hình khi đặt lại/khởi động. -Các lệnh chat trần `/new` và `/reset` xác nhận việc đặt lại mà không gọi -mô hình, nên chúng không tải phần mở đầu này. +Kiểm soát phần mở đầu khởi động ở lượt đầu tiên được chèn vào các lần chạy mô hình reset/khởi động. +Các lệnh chat thuần `/new` và `/reset` xác nhận việc reset mà không gọi +mô hình, vì vậy chúng không tải phần mở đầu này. ```json5 { @@ -185,7 +189,7 @@ mô hình, nên chúng không tải phần mở đầu này. #### `agents.defaults.contextLimits` -Các giá trị mặc định dùng chung cho bề mặt ngữ cảnh thời gian chạy có giới hạn. +Giá trị mặc định dùng chung cho các bề mặt ngữ cảnh thời gian chạy có giới hạn. ```json5 { @@ -205,14 +209,14 @@ Các giá trị mặc định dùng chung cho bề mặt ngữ cảnh thời gia - `memoryGetMaxChars`: giới hạn đoạn trích `memory_get` mặc định trước khi thêm siêu dữ liệu cắt ngắn và thông báo tiếp tục. - `memoryGetDefaultLines`: cửa sổ dòng `memory_get` mặc định khi bỏ qua `lines`. -- `toolResultMaxChars`: giới hạn kết quả công cụ trực tiếp dùng cho kết quả được lưu bền và +- `toolResultMaxChars`: giới hạn kết quả công cụ trực tiếp dùng cho kết quả được lưu giữ và khôi phục khi tràn. -- `postCompactionMaxChars`: giới hạn đoạn trích AGENTS.md dùng trong quá trình chèn - làm mới sau Compaction. +- `postCompactionMaxChars`: giới hạn đoạn trích AGENTS.md dùng trong quá trình chèn làm mới + sau Compaction. #### `agents.list[].contextLimits` -Ghi đè theo tác tử cho các núm `contextLimits` dùng chung. Các trường bị bỏ qua kế thừa +Ghi đè theo tác nhân cho các núm `contextLimits` dùng chung. Các trường bị bỏ qua kế thừa từ `agents.defaults.contextLimits`. ```json5 @@ -239,8 +243,8 @@ từ `agents.defaults.contextLimits`. #### `skills.limits.maxSkillsPromptChars` -Giới hạn toàn cục cho danh sách Skills rút gọn được chèn vào lời nhắc hệ thống. Điều này -không ảnh hưởng đến việc đọc tệp `SKILL.md` theo yêu cầu. +Giới hạn toàn cục cho danh sách Skills rút gọn được chèn vào system prompt. Điều này +không ảnh hưởng đến việc đọc các tệp `SKILL.md` theo yêu cầu. ```json5 { @@ -254,7 +258,7 @@ không ảnh hưởng đến việc đọc tệp `SKILL.md` theo yêu cầu. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Ghi đè theo tác tử cho ngân sách lời nhắc Skills. +Ghi đè theo tác nhân cho ngân sách prompt Skills. ```json5 { @@ -273,11 +277,11 @@ Ghi đè theo tác tử cho ngân sách lời nhắc Skills. ### `agents.defaults.imageMaxDimensionPx` -Kích thước pixel tối đa cho cạnh dài nhất của ảnh trong các khối ảnh transcript/công cụ trước khi gọi nhà cung cấp. +Kích thước pixel tối đa cho cạnh dài nhất của ảnh trong các khối ảnh transcript/công cụ trước khi gọi provider. Mặc định: `1200`. -Giá trị thấp hơn thường giảm mức dùng token thị giác và kích thước tải trọng yêu cầu cho các lần chạy nhiều ảnh chụp màn hình. -Giá trị cao hơn giữ lại nhiều chi tiết thị giác hơn. +Giá trị thấp hơn thường giảm mức dùng vision-token và kích thước payload yêu cầu cho các lần chạy nhiều ảnh chụp màn hình. +Giá trị cao hơn giữ lại nhiều chi tiết hình ảnh hơn. ```json5 { @@ -287,7 +291,7 @@ Giá trị cao hơn giữ lại nhiều chi tiết thị giác hơn. ### `agents.defaults.userTimezone` -Múi giờ cho ngữ cảnh lời nhắc hệ thống (không phải dấu thời gian tin nhắn). Dự phòng về múi giờ của máy chủ. +Múi giờ cho ngữ cảnh system prompt (không phải dấu thời gian tin nhắn). Dự phòng về múi giờ máy chủ. ```json5 { @@ -297,7 +301,7 @@ Múi giờ cho ngữ cảnh lời nhắc hệ thống (không phải dấu thờ ### `agents.defaults.timeFormat` -Định dạng thời gian trong lời nhắc hệ thống. Mặc định: `auto` (tùy chọn hệ điều hành). +Định dạng thời gian trong system prompt. Mặc định: `auto` (tùy chọn hệ điều hành). ```json5 { @@ -343,6 +347,7 @@ Múi giờ cho ngữ cảnh lời nhắc hệ thống (không phải dấu thờ pdfMaxPages: 20, thinkingDefault: "low", verboseDefault: "off", + toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", timeoutSeconds: 600, @@ -358,55 +363,56 @@ Múi giờ cho ngữ cảnh lời nhắc hệ thống (không phải dấu thờ - Dạng chuỗi chỉ đặt mô hình chính. - Dạng đối tượng đặt mô hình chính cùng các mô hình chuyển đổi dự phòng có thứ tự. - `imageModel`: chấp nhận một chuỗi (`"provider/model"`) hoặc một đối tượng (`{ primary, fallbacks }`). - - Được dùng bởi đường dẫn công cụ `image` làm cấu hình mô hình thị giác của công cụ đó. + - Được đường dẫn công cụ `image` dùng làm cấu hình mô hình thị giác. - Cũng được dùng làm định tuyến dự phòng khi mô hình đã chọn/mặc định không thể nhận đầu vào hình ảnh. - - Ưu tiên các tham chiếu `provider/model` rõ ràng. ID trần được chấp nhận để tương thích; nếu một ID trần khớp duy nhất với một mục có khả năng xử lý hình ảnh đã cấu hình trong `models.providers.*.models`, OpenClaw sẽ gán ID đó cho nhà cung cấp tương ứng. Các kết quả khớp đã cấu hình nhưng không rõ ràng yêu cầu tiền tố nhà cung cấp rõ ràng. + - Ưu tiên các tham chiếu `provider/model` tường minh. ID trần được chấp nhận để tương thích; nếu một ID trần khớp duy nhất với một mục đã cấu hình có khả năng xử lý hình ảnh trong `models.providers.*.models`, OpenClaw sẽ gán nó cho provider đó. Các kết quả khớp đã cấu hình nhưng không rõ ràng cần tiền tố provider tường minh. - `imageGenerationModel`: chấp nhận một chuỗi (`"provider/model"`) hoặc một đối tượng (`{ primary, fallbacks }`). - - Được dùng bởi khả năng tạo hình ảnh dùng chung và mọi bề mặt công cụ/plugin trong tương lai tạo hình ảnh. - - Giá trị điển hình: `google/gemini-3.1-flash-image-preview` cho tạo hình ảnh Gemini gốc, `fal/fal-ai/flux/dev` cho fal, `openai/gpt-image-2` cho OpenAI Images, hoặc `openai/gpt-image-1.5` cho đầu ra PNG/WebP OpenAI nền trong suốt. - - Nếu bạn chọn trực tiếp một nhà cung cấp/mô hình, hãy cấu hình cả xác thực nhà cung cấp tương ứng (ví dụ `GEMINI_API_KEY` hoặc `GOOGLE_API_KEY` cho `google/*`, `OPENAI_API_KEY` hoặc OpenAI Codex OAuth cho `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` cho `fal/*`). - - Nếu bỏ qua, `image_generate` vẫn có thể suy luận mặc định nhà cung cấp có xác thực hỗ trợ. Nó thử nhà cung cấp mặc định hiện tại trước, rồi đến các nhà cung cấp tạo hình ảnh đã đăng ký còn lại theo thứ tự ID nhà cung cấp. + - Được năng lực tạo hình ảnh dùng chung và mọi bề mặt công cụ/Plugin trong tương lai có tạo hình ảnh sử dụng. + - Giá trị thường dùng: `google/gemini-3.1-flash-image-preview` cho tạo hình ảnh Gemini gốc, `fal/fal-ai/flux/dev` cho fal, `openai/gpt-image-2` cho OpenAI Images, hoặc `openai/gpt-image-1.5` cho đầu ra PNG/WebP OpenAI có nền trong suốt. + - Nếu bạn chọn trực tiếp một provider/model, hãy cấu hình cả xác thực provider tương ứng (ví dụ `GEMINI_API_KEY` hoặc `GOOGLE_API_KEY` cho `google/*`, `OPENAI_API_KEY` hoặc OpenAI Codex OAuth cho `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` cho `fal/*`). + - Nếu bị bỏ qua, `image_generate` vẫn có thể suy ra mặc định provider dựa trên xác thực. Nó thử provider mặc định hiện tại trước, rồi đến các provider tạo hình ảnh đã đăng ký còn lại theo thứ tự provider-id. - `musicGenerationModel`: chấp nhận một chuỗi (`"provider/model"`) hoặc một đối tượng (`{ primary, fallbacks }`). - - Được dùng bởi khả năng tạo nhạc dùng chung và công cụ tích hợp sẵn `music_generate`. - - Giá trị điển hình: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, hoặc `minimax/music-2.6`. - - Nếu bỏ qua, `music_generate` vẫn có thể suy luận mặc định nhà cung cấp có xác thực hỗ trợ. Nó thử nhà cung cấp mặc định hiện tại trước, rồi đến các nhà cung cấp tạo nhạc đã đăng ký còn lại theo thứ tự ID nhà cung cấp. - - Nếu bạn chọn trực tiếp một nhà cung cấp/mô hình, hãy cấu hình cả xác thực/khóa API của nhà cung cấp tương ứng. + - Được năng lực tạo nhạc dùng chung và công cụ tích hợp `music_generate` sử dụng. + - Giá trị thường dùng: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, hoặc `minimax/music-2.6`. + - Nếu bị bỏ qua, `music_generate` vẫn có thể suy ra mặc định provider dựa trên xác thực. Nó thử provider mặc định hiện tại trước, rồi đến các provider tạo nhạc đã đăng ký còn lại theo thứ tự provider-id. + - Nếu bạn chọn trực tiếp một provider/model, hãy cấu hình cả xác thực provider/khóa API tương ứng. - `videoGenerationModel`: chấp nhận một chuỗi (`"provider/model"`) hoặc một đối tượng (`{ primary, fallbacks }`). - - Được dùng bởi khả năng tạo video dùng chung và công cụ tích hợp sẵn `video_generate`. - - Giá trị điển hình: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, hoặc `qwen/wan2.7-r2v`. - - Nếu bỏ qua, `video_generate` vẫn có thể suy luận mặc định nhà cung cấp có xác thực hỗ trợ. Nó thử nhà cung cấp mặc định hiện tại trước, rồi đến các nhà cung cấp tạo video đã đăng ký còn lại theo thứ tự ID nhà cung cấp. - - Nếu bạn chọn trực tiếp một nhà cung cấp/mô hình, hãy cấu hình cả xác thực/khóa API của nhà cung cấp tương ứng. - - Nhà cung cấp tạo video Qwen đi kèm hỗ trợ tối đa 1 video đầu ra, 1 hình ảnh đầu vào, 4 video đầu vào, thời lượng 10 giây, và các tùy chọn cấp nhà cung cấp `size`, `aspectRatio`, `resolution`, `audio`, và `watermark`. + - Được năng lực tạo video dùng chung và công cụ tích hợp `video_generate` sử dụng. + - Giá trị thường dùng: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, hoặc `qwen/wan2.7-r2v`. + - Nếu bị bỏ qua, `video_generate` vẫn có thể suy ra mặc định provider dựa trên xác thực. Nó thử provider mặc định hiện tại trước, rồi đến các provider tạo video đã đăng ký còn lại theo thứ tự provider-id. + - Nếu bạn chọn trực tiếp một provider/model, hãy cấu hình cả xác thực provider/khóa API tương ứng. + - Provider tạo video Qwen đi kèm hỗ trợ tối đa 1 video đầu ra, 1 hình ảnh đầu vào, 4 video đầu vào, thời lượng 10 giây, và các tùy chọn cấp provider `size`, `aspectRatio`, `resolution`, `audio`, và `watermark`. - `pdfModel`: chấp nhận một chuỗi (`"provider/model"`) hoặc một đối tượng (`{ primary, fallbacks }`). - - Được dùng bởi công cụ `pdf` để định tuyến mô hình. - - Nếu bỏ qua, công cụ PDF sẽ dự phòng về `imageModel`, rồi đến mô hình phiên/mặc định đã phân giải. + - Được công cụ `pdf` dùng để định tuyến mô hình. + - Nếu bị bỏ qua, công cụ PDF dự phòng về `imageModel`, rồi đến mô hình đã phân giải của phiên/mặc định. - `pdfMaxBytesMb`: giới hạn kích thước PDF mặc định cho công cụ `pdf` khi `maxBytesMb` không được truyền tại thời điểm gọi. - `pdfMaxPages`: số trang tối đa mặc định được xét bởi chế độ dự phòng trích xuất trong công cụ `pdf`. -- `verboseDefault`: mức chi tiết mặc định cho tác nhân. Giá trị: `"off"`, `"on"`, `"full"`. Mặc định: `"off"`. -- `reasoningDefault`: khả năng hiển thị reasoning mặc định cho tác nhân. Giá trị: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` theo từng tác nhân ghi đè mặc định này. Các mặc định reasoning đã cấu hình chỉ được áp dụng cho chủ sở hữu, người gửi được ủy quyền, hoặc ngữ cảnh Gateway quản trị vận hành khi không có ghi đè reasoning theo tin nhắn hoặc theo phiên. -- `elevatedDefault`: mức đầu ra nâng cao mặc định cho tác nhân. Giá trị: `"off"`, `"on"`, `"ask"`, `"full"`. Mặc định: `"on"`. -- `model.primary`: định dạng `provider/model` (ví dụ `openai/gpt-5.5` cho truy cập bằng khóa API hoặc `openai-codex/gpt-5.5` cho Codex OAuth). Nếu bạn bỏ qua nhà cung cấp, OpenClaw sẽ thử alias trước, rồi đến một kết quả khớp duy nhất từ nhà cung cấp đã cấu hình cho đúng ID mô hình đó, và chỉ sau đó mới dự phòng về nhà cung cấp mặc định đã cấu hình (hành vi tương thích đã lỗi thời, nên hãy ưu tiên `provider/model` rõ ràng). Nếu nhà cung cấp đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw sẽ dự phòng về nhà cung cấp/mô hình đã cấu hình đầu tiên thay vì hiển thị mặc định nhà cung cấp đã bị gỡ cũ. -- `models`: danh mục mô hình đã cấu hình và danh sách cho phép cho `/model`. Mỗi mục có thể bao gồm `alias` (lối tắt) và `params` (theo nhà cung cấp, ví dụ `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`). - - Chỉnh sửa an toàn: dùng `openclaw config set agents.defaults.models '' --strict-json --merge` để thêm mục. `config set` từ chối các thay thế sẽ xóa các mục danh sách cho phép hiện có trừ khi bạn truyền `--replace`. - - Các luồng cấu hình/onboarding theo phạm vi nhà cung cấp hợp nhất các mô hình nhà cung cấp đã chọn vào bản đồ này và giữ nguyên các nhà cung cấp không liên quan đã được cấu hình. - - Đối với các mô hình OpenAI Responses trực tiếp, Compaction phía máy chủ được bật tự động. Dùng `params.responsesServerCompaction: false` để dừng chèn `context_management`, hoặc `params.responsesCompactThreshold` để ghi đè ngưỡng. Xem [Compaction phía máy chủ OpenAI](/vi/providers/openai#server-side-compaction-responses-api). -- `params`: tham số nhà cung cấp mặc định toàn cục được áp dụng cho tất cả mô hình. Đặt tại `agents.defaults.params` (ví dụ `{ cacheRetention: "long" }`). -- Thứ tự ưu tiên hợp nhất `params` (cấu hình): `agents.defaults.params` (nền toàn cục) bị ghi đè bởi `agents.defaults.models["provider/model"].params` (theo mô hình), rồi `agents.list[].params` (khớp ID tác nhân) ghi đè theo khóa. Xem [Bộ nhớ đệm prompt](/vi/reference/prompt-caching) để biết chi tiết. -- `params.extra_body`/`params.extraBody`: JSON truyền xuyên qua nâng cao được hợp nhất vào phần thân yêu cầu `api: "openai-completions"` cho các proxy tương thích OpenAI. Nếu nó xung đột với các khóa yêu cầu được tạo, phần thân bổ sung sẽ thắng; các tuyến completions không gốc vẫn loại bỏ `store` chỉ dành cho OpenAI sau đó. -- `params.chat_template_kwargs`: đối số mẫu trò chuyện tương thích vLLM/OpenAI được hợp nhất vào phần thân yêu cầu `api: "openai-completions"` cấp cao nhất. Với `vllm/nemotron-3-*` khi thinking tắt, plugin vLLM đi kèm tự động gửi `enable_thinking: false` và `force_nonempty_content: true`; `chat_template_kwargs` rõ ràng ghi đè mặc định được tạo, và `extra_body.chat_template_kwargs` vẫn có ưu tiên cuối cùng. Đối với điều khiển thinking Qwen trên vLLM, đặt `params.qwenThinkingFormat` thành `"chat-template"` hoặc `"top-level"` trên mục mô hình đó. -- `compat.supportedReasoningEfforts`: danh sách nỗ lực reasoning tương thích OpenAI theo từng mô hình. Bao gồm `"xhigh"` cho các endpoint tùy chỉnh thực sự chấp nhận nó; khi đó OpenClaw hiển thị `/think xhigh` trong menu lệnh, hàng phiên Gateway, xác thực bản vá phiên, xác thực CLI tác nhân, và xác thực `llm-task` cho nhà cung cấp/mô hình đã cấu hình đó. Dùng `compat.reasoningEffortMap` khi backend muốn một giá trị theo nhà cung cấp cho một cấp chuẩn. +- `verboseDefault`: mức verbose mặc định cho agent. Giá trị: `"off"`, `"on"`, `"full"`. Mặc định: `"off"`. +- `toolProgressDetail`: chế độ chi tiết cho tóm tắt công cụ `/verbose` và các dòng công cụ trong bản nháp tiến trình. Giá trị: `"explain"` (mặc định, nhãn ngắn gọn cho người đọc) hoặc `"raw"` (thêm lệnh/chi tiết thô khi có). `agents.list[].toolProgressDetail` theo từng agent sẽ ghi đè mặc định này. +- `reasoningDefault`: khả năng hiển thị reasoning mặc định cho agent. Giá trị: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` theo từng agent sẽ ghi đè mặc định này. Mặc định reasoning đã cấu hình chỉ được áp dụng cho chủ sở hữu, người gửi được ủy quyền, hoặc ngữ cảnh gateway operator-admin khi không đặt ghi đè reasoning theo tin nhắn hoặc theo phiên. +- `elevatedDefault`: mức đầu ra nâng cao mặc định cho agent. Giá trị: `"off"`, `"on"`, `"ask"`, `"full"`. Mặc định: `"on"`. +- `model.primary`: định dạng `provider/model` (ví dụ `openai/gpt-5.5` cho truy cập bằng khóa API hoặc `openai-codex/gpt-5.5` cho Codex OAuth). Nếu bạn bỏ qua provider, OpenClaw sẽ thử alias trước, rồi đến kết quả khớp provider đã cấu hình duy nhất cho đúng model id đó, và chỉ sau đó mới dự phòng về provider mặc định đã cấu hình (hành vi tương thích không còn khuyến nghị, vì vậy nên ưu tiên `provider/model` tường minh). Nếu provider đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw dự phòng về provider/model đã cấu hình đầu tiên thay vì hiển thị một mặc định provider đã bị xóa và lỗi thời. +- `models`: danh mục mô hình đã cấu hình và allowlist cho `/model`. Mỗi mục có thể bao gồm `alias` (lối tắt) và `params` (theo provider, ví dụ `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`). + - Chỉnh sửa an toàn: dùng `openclaw config set agents.defaults.models '' --strict-json --merge` để thêm mục. `config set` từ chối các thay thế sẽ xóa mục allowlist hiện có trừ khi bạn truyền `--replace`. + - Các luồng cấu hình/onboarding theo phạm vi provider sẽ hợp nhất các mô hình provider đã chọn vào map này và giữ nguyên các provider không liên quan đã cấu hình. + - Với các mô hình OpenAI Responses trực tiếp, Compaction phía máy chủ được bật tự động. Dùng `params.responsesServerCompaction: false` để ngừng chèn `context_management`, hoặc `params.responsesCompactThreshold` để ghi đè ngưỡng. Xem [Compaction phía máy chủ OpenAI](/vi/providers/openai#server-side-compaction-responses-api). +- `params`: tham số provider mặc định toàn cục được áp dụng cho mọi mô hình. Đặt tại `agents.defaults.params` (ví dụ `{ cacheRetention: "long" }`). +- Thứ tự ưu tiên hợp nhất `params` (cấu hình): `agents.defaults.params` (nền tảng toàn cục) bị ghi đè bởi `agents.defaults.models["provider/model"].params` (theo mô hình), sau đó `agents.list[].params` (khớp agent id) ghi đè theo khóa. Xem [Lưu bộ nhớ đệm prompt](/vi/reference/prompt-caching) để biết chi tiết. +- `params.extra_body`/`params.extraBody`: JSON truyền xuyên nâng cao được hợp nhất vào thân yêu cầu `api: "openai-completions"` cho các proxy tương thích với OpenAI. Nếu nó trùng với các khóa yêu cầu được tạo, phần thân bổ sung sẽ thắng; các tuyến completions không gốc vẫn loại bỏ `store` chỉ dành cho OpenAI sau đó. +- `params.chat_template_kwargs`: đối số chat-template tương thích với vLLM/OpenAI được hợp nhất vào thân yêu cầu cấp cao nhất `api: "openai-completions"`. Với `vllm/nemotron-3-*` khi tắt thinking, Plugin vLLM đi kèm tự động gửi `enable_thinking: false` và `force_nonempty_content: true`; `chat_template_kwargs` tường minh ghi đè mặc định được tạo, và `extra_body.chat_template_kwargs` vẫn có ưu tiên cuối cùng. Với điều khiển thinking của vLLM Qwen, đặt `params.qwenThinkingFormat` thành `"chat-template"` hoặc `"top-level"` trên mục mô hình đó. +- `compat.supportedReasoningEfforts`: danh sách reasoning effort tương thích với OpenAI theo từng mô hình. Bao gồm `"xhigh"` cho endpoint tùy chỉnh thật sự chấp nhận giá trị đó; khi đó OpenClaw hiển thị `/think xhigh` trong menu lệnh, hàng phiên Gateway, xác thực bản vá phiên, xác thực CLI agent, và xác thực `llm-task` cho provider/model đã cấu hình đó. Dùng `compat.reasoningEffortMap` khi backend muốn một giá trị theo provider cho một mức chuẩn. - `params.preserveThinking`: tùy chọn chỉ dành cho Z.AI để giữ lại thinking. Khi bật và thinking đang bật, OpenClaw gửi `thinking.clear_thinking: false` và phát lại `reasoning_content` trước đó; xem [thinking và thinking được giữ lại của Z.AI](/vi/providers/zai#thinking-and-preserved-thinking). -- `agentRuntime`: chính sách runtime tác nhân cấp thấp mặc định. ID bị bỏ qua mặc định là OpenClaw Pi. Dùng `id: "pi"` để buộc harness PI tích hợp sẵn, `id: "auto"` để cho phép các harness plugin đã đăng ký nhận các mô hình được hỗ trợ và dùng PI khi không có kết quả khớp, một ID harness đã đăng ký như `id: "codex"` để yêu cầu harness đó, hoặc một alias backend CLI được hỗ trợ như `id: "claude-cli"`. Các runtime plugin rõ ràng sẽ đóng thất bại khi harness không khả dụng hoặc thất bại. Giữ tham chiếu mô hình chuẩn là `provider/model`; chọn Codex, Claude CLI, Gemini CLI, và các backend thực thi khác thông qua cấu hình runtime thay vì tiền tố nhà cung cấp runtime cũ. Xem [Runtime tác nhân](/vi/concepts/agent-runtimes) để biết phần này khác với lựa chọn nhà cung cấp/mô hình như thế nào. -- Trình ghi cấu hình làm thay đổi các trường này (ví dụ `/models set`, `/models set-image`, và các lệnh thêm/xóa dự phòng) lưu dạng đối tượng chuẩn và giữ nguyên danh sách dự phòng hiện có khi có thể. -- `maxConcurrent`: số lượt chạy tác nhân song song tối đa trên các phiên (mỗi phiên vẫn được tuần tự hóa). Mặc định: 4. +- `agentRuntime`: chính sách runtime agent cấp thấp mặc định. id bị bỏ qua mặc định là OpenClaw Pi. Dùng `id: "pi"` để buộc dùng harness PI tích hợp, `id: "auto"` để cho các harness Plugin đã đăng ký nhận các mô hình được hỗ trợ và dùng PI khi không có mô hình nào khớp, một harness id đã đăng ký như `id: "codex"` để yêu cầu harness đó, hoặc một alias backend CLI được hỗ trợ như `id: "claude-cli"`. Runtime Plugin tường minh sẽ fail closed khi harness không khả dụng hoặc thất bại. Giữ tham chiếu mô hình ở dạng chuẩn `provider/model`; chọn Codex, Claude CLI, Gemini CLI và các backend thực thi khác qua cấu hình runtime thay vì các tiền tố provider runtime cũ. Xem [Runtime agent](/vi/concepts/agent-runtimes) để biết cách nội dung này khác với lựa chọn provider/model. +- Trình ghi cấu hình thay đổi các trường này (ví dụ `/models set`, `/models set-image`, và các lệnh thêm/xóa dự phòng) lưu dạng đối tượng chuẩn và giữ lại danh sách dự phòng hiện có khi có thể. +- `maxConcurrent`: số lượt chạy agent song song tối đa trên các phiên (mỗi phiên vẫn được tuần tự hóa). Mặc định: 4. ### `agents.defaults.agentRuntime` -`agentRuntime` kiểm soát executor cấp thấp nào chạy các lượt tác nhân. Hầu hết -triển khai nên giữ runtime OpenClaw Pi mặc định. Dùng nó khi một plugin đáng tin cậy -cung cấp harness gốc, chẳng hạn harness máy chủ ứng dụng Codex đi kèm, -hoặc khi bạn muốn một backend CLI được hỗ trợ như Claude CLI. Để có mô hình -tư duy, xem [Runtime tác nhân](/vi/concepts/agent-runtimes). +`agentRuntime` kiểm soát executor cấp thấp nào chạy các lượt agent. Hầu hết +triển khai nên giữ runtime OpenClaw Pi mặc định. Dùng nó khi một Plugin đáng tin cậy +cung cấp harness gốc, chẳng hạn harness app-server Codex đi kèm, +hoặc khi bạn muốn một backend CLI được hỗ trợ như Claude CLI. Để hiểu mô hình tư duy, +xem [Runtime agent](/vi/concepts/agent-runtimes). ```json5 { @@ -421,37 +427,37 @@ tư duy, xem [Runtime tác nhân](/vi/concepts/agent-runtimes). } ``` -- `id`: `"auto"`, `"pi"`, một ID harness plugin đã đăng ký, hoặc một alias backend CLI được hỗ trợ. Plugin Codex đi kèm đăng ký `codex`; plugin Anthropic đi kèm cung cấp backend CLI `claude-cli`. -- `id: "auto"` cho phép các harness plugin đã đăng ký nhận các lượt được hỗ trợ và dùng PI khi không có harness nào khớp. Một runtime plugin rõ ràng như `id: "codex"` yêu cầu harness đó và đóng thất bại nếu nó không khả dụng hoặc thất bại. +- `id`: `"auto"`, `"pi"`, một harness id Plugin đã đăng ký, hoặc một alias backend CLI được hỗ trợ. Plugin Codex đi kèm đăng ký `codex`; Plugin Anthropic đi kèm cung cấp backend CLI `claude-cli`. +- `id: "auto"` cho phép các harness Plugin đã đăng ký nhận các lượt được hỗ trợ và dùng PI khi không có harness nào khớp. Một runtime Plugin tường minh như `id: "codex"` yêu cầu harness đó và fail closed nếu nó không khả dụng hoặc thất bại. - Ghi đè môi trường: `OPENCLAW_AGENT_RUNTIME=` ghi đè `id` cho tiến trình đó. -- Đối với triển khai chỉ dùng Codex, đặt `model: "openai/gpt-5.5"` và `agentRuntime.id: "codex"`. -- Đối với triển khai Claude CLI, ưu tiên `model: "anthropic/claude-opus-4-7"` cộng với `agentRuntime.id: "claude-cli"`. Tham chiếu mô hình cũ `claude-cli/claude-opus-4-7` vẫn hoạt động để tương thích, nhưng cấu hình mới nên giữ lựa chọn nhà cung cấp/mô hình ở dạng chuẩn và đặt backend thực thi trong `agentRuntime.id`. +- Với các triển khai chỉ dùng Codex, đặt `model: "openai/gpt-5.5"` và `agentRuntime.id: "codex"`. +- Với các triển khai Claude CLI, ưu tiên `model: "anthropic/claude-opus-4-7"` cộng với `agentRuntime.id: "claude-cli"`. Tham chiếu mô hình cũ `claude-cli/claude-opus-4-7` vẫn hoạt động để tương thích, nhưng cấu hình mới nên giữ lựa chọn provider/model ở dạng chuẩn và đặt backend thực thi trong `agentRuntime.id`. - Các khóa chính sách runtime cũ hơn được `openclaw doctor --fix` viết lại thành `agentRuntime`. -- Lựa chọn harness được ghim theo ID phiên sau lần chạy nhúng đầu tiên. Thay đổi cấu hình/env ảnh hưởng đến phiên mới hoặc phiên đã đặt lại, không ảnh hưởng đến transcript hiện có. Các phiên cũ có lịch sử transcript nhưng không có pin đã ghi được xử lý như đã ghim PI. `/status` báo cáo runtime hiệu dụng, ví dụ `Runtime: OpenClaw Pi Default` hoặc `Runtime: OpenAI Codex`. -- Điều này chỉ kiểm soát thực thi lượt tác nhân dạng văn bản. Tạo media, thị giác, PDF, nhạc, video, và TTS vẫn dùng các cài đặt nhà cung cấp/mô hình riêng. +- Lựa chọn harness được ghim theo session id sau lượt chạy nhúng đầu tiên. Thay đổi cấu hình/env ảnh hưởng đến phiên mới hoặc phiên đã đặt lại, không ảnh hưởng đến transcript hiện có. Các phiên cũ có lịch sử transcript nhưng không có pin được ghi nhận sẽ được xem là đã ghim PI. `/status` báo cáo runtime hiệu lực, ví dụ `Runtime: OpenClaw Pi Default` hoặc `Runtime: OpenAI Codex`. +- Điều này chỉ kiểm soát thực thi lượt agent dạng văn bản. Tạo media, thị giác, PDF, nhạc, video và TTS vẫn dùng thiết lập provider/model của chúng. -**Lối tắt alias tích hợp sẵn** (chỉ áp dụng khi mô hình nằm trong `agents.defaults.models`): +**Các dạng viết tắt alias tích hợp sẵn** (chỉ áp dụng khi mô hình nằm trong `agents.defaults.models`): | Alias | Mô hình | | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.5` hoặc `openai-codex/gpt-5.5` | +| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Các alias đã cấu hình của bạn luôn thắng mặc định. +Các alias bạn cấu hình luôn được ưu tiên hơn mặc định. Các mô hình Z.AI GLM-4.x tự động bật chế độ suy nghĩ trừ khi bạn đặt `--thinking off` hoặc tự định nghĩa `agents.defaults.models["zai/"].params.thinking`. -Các mô hình Z.AI bật `tool_stream` theo mặc định để phát trực tuyến lệnh gọi công cụ. Đặt `agents.defaults.models["zai/"].params.tool_stream` thành `false` để tắt tính năng này. +Các mô hình Z.AI bật `tool_stream` theo mặc định để truyền phát lệnh gọi công cụ. Đặt `agents.defaults.models["zai/"].params.tool_stream` thành `false` để tắt tính năng này. Các mô hình Anthropic Claude 4.6 mặc định dùng suy nghĩ `adaptive` khi không đặt mức suy nghĩ rõ ràng. ### `agents.defaults.cliBackends` -Các backend CLI tùy chọn cho các lượt chạy dự phòng chỉ văn bản (không có lệnh gọi công cụ). Hữu ích làm phương án dự phòng khi nhà cung cấp API gặp lỗi. +Các backend CLI tùy chọn cho những lần chạy dự phòng chỉ văn bản (không có lệnh gọi công cụ). Hữu ích làm phương án dự phòng khi nhà cung cấp API gặp lỗi. ```json5 { @@ -481,7 +487,7 @@ Các backend CLI tùy chọn cho các lượt chạy dự phòng chỉ văn bả ``` - Các backend CLI ưu tiên văn bản; công cụ luôn bị tắt. -- Hỗ trợ phiên khi đặt `sessionArg`. +- Hỗ trợ phiên khi `sessionArg` được đặt. - Hỗ trợ chuyển tiếp hình ảnh khi `imageArg` chấp nhận đường dẫn tệp. ### `agents.defaults.systemPromptOverride` @@ -500,7 +506,7 @@ Thay thế toàn bộ system prompt do OpenClaw lắp ráp bằng một chuỗi ### `agents.defaults.promptOverlays` -Các lớp phủ prompt độc lập với nhà cung cấp, được áp dụng theo họ mô hình. ID mô hình thuộc họ GPT-5 nhận hợp đồng hành vi dùng chung trên các nhà cung cấp; `personality` chỉ kiểm soát lớp phong cách tương tác thân thiện. +Các lớp phủ prompt độc lập với nhà cung cấp, được áp dụng theo họ mô hình. ID mô hình thuộc họ GPT-5 nhận hợp đồng hành vi dùng chung giữa các nhà cung cấp; `personality` chỉ kiểm soát lớp phong cách tương tác thân thiện. ```json5 { @@ -517,12 +523,12 @@ Các lớp phủ prompt độc lập với nhà cung cấp, được áp dụng ``` - `"friendly"` (mặc định) và `"on"` bật lớp phong cách tương tác thân thiện. -- `"off"` chỉ tắt lớp thân thiện; hợp đồng hành vi GPT-5 được gắn nhãn vẫn được bật. -- `plugins.entries.openai.config.personality` cũ vẫn được đọc khi thiết lập dùng chung này chưa được đặt. +- `"off"` chỉ tắt lớp thân thiện; hợp đồng hành vi GPT-5 được gắn thẻ vẫn được bật. +- `plugins.entries.openai.config.personality` cũ vẫn được đọc khi cài đặt dùng chung này chưa được đặt. ### `agents.defaults.heartbeat` -Các lượt chạy Heartbeat định kỳ. +Các lần chạy Heartbeat định kỳ. ```json5 { @@ -551,15 +557,15 @@ Các lượt chạy Heartbeat định kỳ. ``` - `every`: chuỗi thời lượng (ms/s/m/h). Mặc định: `30m` (xác thực bằng khóa API) hoặc `1h` (xác thực OAuth). Đặt thành `0m` để tắt. -- `includeSystemPromptSection`: khi là false, bỏ qua phần Heartbeat khỏi system prompt và bỏ qua việc chèn `HEARTBEAT.md` vào ngữ cảnh khởi động. Mặc định: `true`. -- `suppressToolErrorWarnings`: khi là true, ẩn payload cảnh báo lỗi công cụ trong các lượt chạy Heartbeat. -- `timeoutSeconds`: thời gian tối đa tính bằng giây cho phép một lượt agent Heartbeat chạy trước khi bị hủy. Để trống để dùng `agents.defaults.timeoutSeconds`. -- `directPolicy`: chính sách gửi trực tiếp/DM. `allow` (mặc định) cho phép gửi đến đích trực tiếp. `block` chặn gửi đến đích trực tiếp và phát ra `reason=dm-blocked`. -- `lightContext`: khi là true, các lượt chạy Heartbeat dùng ngữ cảnh khởi động nhẹ và chỉ giữ `HEARTBEAT.md` trong các tệp khởi động workspace. -- `isolatedSession`: khi là true, mỗi Heartbeat chạy trong một phiên mới không có lịch sử hội thoại trước đó. Cùng mẫu cô lập như Cron `sessionTarget: "isolated"`. Giảm chi phí token cho mỗi Heartbeat từ khoảng 100K xuống khoảng 2-5K token. -- `skipWhenBusy`: khi là true, các lượt chạy Heartbeat sẽ trì hoãn trên các làn bận bổ sung: công việc subagent hoặc lệnh lồng nhau. Các làn Cron luôn trì hoãn Heartbeat, ngay cả khi không có cờ này. +- `includeSystemPromptSection`: khi là false, bỏ qua phần Heartbeat khỏi system prompt và bỏ qua việc chèn `HEARTBEAT.md` vào ngữ cảnh khởi tạo. Mặc định: `true`. +- `suppressToolErrorWarnings`: khi là true, chặn các payload cảnh báo lỗi công cụ trong các lần chạy Heartbeat. +- `timeoutSeconds`: thời gian tối đa tính bằng giây được phép cho một lượt agent Heartbeat trước khi bị hủy. Để trống để dùng `agents.defaults.timeoutSeconds`. +- `directPolicy`: chính sách gửi trực tiếp/DM. `allow` (mặc định) cho phép gửi tới mục tiêu trực tiếp. `block` chặn gửi tới mục tiêu trực tiếp và phát ra `reason=dm-blocked`. +- `lightContext`: khi là true, các lần chạy Heartbeat dùng ngữ cảnh khởi tạo nhẹ và chỉ giữ `HEARTBEAT.md` từ các tệp khởi tạo workspace. +- `isolatedSession`: khi là true, mỗi Heartbeat chạy trong một phiên mới, không có lịch sử hội thoại trước đó. Cùng mẫu cô lập như Cron `sessionTarget: "isolated"`. Giảm chi phí token cho mỗi Heartbeat từ khoảng 100K xuống khoảng 2-5K token. +- `skipWhenBusy`: khi là true, các lần chạy Heartbeat sẽ trì hoãn trên các làn bận bổ sung: công việc subagent hoặc lệnh lồng nhau. Các làn Cron luôn trì hoãn Heartbeat, ngay cả khi không có cờ này. - Theo agent: đặt `agents.list[].heartbeat`. Khi bất kỳ agent nào định nghĩa `heartbeat`, **chỉ các agent đó** chạy Heartbeat. -- Heartbeat chạy các lượt agent đầy đủ — khoảng thời gian ngắn hơn tiêu tốn nhiều token hơn. +- Heartbeat chạy đầy đủ các lượt agent — khoảng thời gian ngắn hơn sẽ tiêu tốn nhiều token hơn. ### `agents.defaults.compaction` @@ -596,22 +602,22 @@ Các lượt chạy Heartbeat định kỳ. ``` - `mode`: `default` hoặc `safeguard` (tóm tắt theo khối cho lịch sử dài). Xem [Compaction](/vi/concepts/compaction). -- `provider`: ID của một Plugin nhà cung cấp Compaction đã đăng ký. Khi được đặt, `summarize()` của nhà cung cấp được gọi thay vì cơ chế tóm tắt LLM tích hợp. Rơi về cơ chế tích hợp khi lỗi. Đặt nhà cung cấp sẽ buộc `mode: "safeguard"`. Xem [Compaction](/vi/concepts/compaction). -- `timeoutSeconds`: số giây tối đa cho phép một thao tác Compaction đơn lẻ trước khi OpenClaw hủy thao tác đó. Mặc định: `900`. -- `keepRecentTokens`: ngân sách điểm cắt Pi để giữ nguyên văn phần đuôi transcript gần đây nhất. `/compact` thủ công tôn trọng giá trị này khi được đặt rõ ràng; nếu không, Compaction thủ công là một checkpoint cứng. -- `identifierPolicy`: `strict` (mặc định), `off`, hoặc `custom`. `strict` thêm hướng dẫn tích hợp về giữ lại định danh mờ vào đầu trong quá trình tóm tắt Compaction. -- `identifierInstructions`: văn bản tùy chỉnh tùy chọn về bảo toàn định danh, dùng khi `identifierPolicy=custom`. -- `qualityGuard`: kiểm tra thử lại khi đầu ra sai định dạng cho các bản tóm tắt safeguard. Được bật theo mặc định trong chế độ safeguard; đặt `enabled: false` để bỏ qua kiểm toán. -- `midTurnPrecheck`: kiểm tra áp lực vòng lặp công cụ Pi tùy chọn. Khi `enabled: true`, OpenClaw kiểm tra áp lực ngữ cảnh sau khi kết quả công cụ được nối thêm và trước lệnh gọi mô hình tiếp theo. Nếu ngữ cảnh không còn vừa, OpenClaw hủy lần thử hiện tại trước khi gửi prompt và dùng lại đường khôi phục precheck hiện có để cắt ngắn kết quả công cụ hoặc Compaction rồi thử lại. Hoạt động với cả hai chế độ Compaction `default` và `safeguard`. Mặc định: tắt. -- `postCompactionSections`: tên phần H2/H3 tùy chọn trong AGENTS.md để chèn lại sau Compaction. Mặc định là `["Session Startup", "Red Lines"]`; đặt `[]` để tắt chèn lại. Khi chưa đặt hoặc được đặt rõ ràng thành cặp mặc định đó, các tiêu đề cũ `Every Session`/`Safety` cũng được chấp nhận làm phương án dự phòng kế thừa. -- `model`: ghi đè `provider/model-id` tùy chọn chỉ cho tóm tắt Compaction. Dùng tùy chọn này khi phiên chính cần giữ một mô hình nhưng tóm tắt Compaction cần chạy trên mô hình khác; khi chưa đặt, Compaction dùng mô hình chính của phiên. -- `maxActiveTranscriptBytes`: ngưỡng byte tùy chọn (`number` hoặc chuỗi như `"20mb"`) kích hoạt Compaction cục bộ bình thường trước một lượt chạy khi JSONL đang hoạt động vượt quá ngưỡng. Yêu cầu `truncateAfterCompaction` để Compaction thành công có thể xoay sang transcript kế nhiệm nhỏ hơn. Bị tắt khi chưa đặt hoặc bằng `0`. -- `notifyUser`: khi là `true`, gửi thông báo ngắn cho người dùng khi Compaction bắt đầu và khi hoàn tất (ví dụ: "Compacting context..." và "Compaction complete"). Bị tắt theo mặc định để Compaction diễn ra im lặng. -- `memoryFlush`: lượt agent im lặng trước auto-compaction để lưu ký ức bền vững. Đặt `model` thành một nhà cung cấp/mô hình chính xác như `ollama/qwen3:8b` khi lượt dọn dẹp này nên ở lại trên mô hình cục bộ; ghi đè này không kế thừa chuỗi dự phòng của phiên đang hoạt động. Bị bỏ qua khi workspace chỉ đọc. +- `provider`: ID của Plugin nhà cung cấp Compaction đã đăng ký. Khi được đặt, `summarize()` của nhà cung cấp được gọi thay vì tóm tắt LLM tích hợp sẵn. Quay về tích hợp sẵn khi thất bại. Việc đặt nhà cung cấp buộc `mode: "safeguard"`. Xem [Compaction](/vi/concepts/compaction). +- `timeoutSeconds`: số giây tối đa được phép cho một thao tác Compaction trước khi OpenClaw hủy thao tác đó. Mặc định: `900`. +- `keepRecentTokens`: ngân sách điểm cắt Pi để giữ nguyên văn phần đuôi transcript gần nhất. `/compact` thủ công tôn trọng giá trị này khi được đặt rõ ràng; nếu không, Compaction thủ công là một checkpoint cứng. +- `identifierPolicy`: `strict` (mặc định), `off`, hoặc `custom`. `strict` thêm trước hướng dẫn tích hợp sẵn về giữ lại mã định danh mờ trong quá trình tóm tắt Compaction. +- `identifierInstructions`: văn bản tùy chỉnh tùy chọn để bảo toàn mã định danh, được dùng khi `identifierPolicy=custom`. +- `qualityGuard`: kiểm tra thử lại khi đầu ra sai định dạng cho các bản tóm tắt safeguard. Bật theo mặc định ở chế độ safeguard; đặt `enabled: false` để bỏ qua kiểm tra. +- `midTurnPrecheck`: kiểm tra áp lực vòng lặp công cụ Pi tùy chọn. Khi `enabled: true`, OpenClaw kiểm tra áp lực ngữ cảnh sau khi kết quả công cụ được thêm vào và trước lệnh gọi mô hình tiếp theo. Nếu ngữ cảnh không còn vừa, OpenClaw hủy lần thử hiện tại trước khi gửi prompt và tái sử dụng đường dẫn khôi phục precheck hiện có để cắt ngắn kết quả công cụ hoặc Compaction rồi thử lại. Hoạt động với cả hai chế độ Compaction `default` và `safeguard`. Mặc định: tắt. +- `postCompactionSections`: tên phần H2/H3 trong AGENTS.md tùy chọn để chèn lại sau Compaction. Mặc định là `["Session Startup", "Red Lines"]`; đặt `[]` để tắt chèn lại. Khi chưa đặt hoặc được đặt rõ ràng thành cặp mặc định đó, các tiêu đề cũ hơn `Every Session`/`Safety` cũng được chấp nhận làm phương án dự phòng kế thừa. +- `model`: tùy chọn ghi đè `provider/model-id` chỉ dành cho tóm tắt Compaction. Dùng khi phiên chính nên giữ một mô hình nhưng bản tóm tắt Compaction nên chạy trên mô hình khác; khi chưa đặt, Compaction dùng mô hình chính của phiên. +- `maxActiveTranscriptBytes`: ngưỡng byte tùy chọn (`number` hoặc chuỗi như `"20mb"`) kích hoạt Compaction cục bộ thông thường trước một lần chạy khi JSONL đang hoạt động vượt quá ngưỡng. Yêu cầu `truncateAfterCompaction` để Compaction thành công có thể xoay sang transcript kế tiếp nhỏ hơn. Tắt khi chưa đặt hoặc bằng `0`. +- `notifyUser`: khi là `true`, gửi thông báo ngắn cho người dùng khi Compaction bắt đầu và khi hoàn tất (ví dụ: "Đang nén ngữ cảnh..." và "Compaction hoàn tất"). Tắt theo mặc định để giữ Compaction im lặng. +- `memoryFlush`: lượt agentic im lặng trước auto-compaction để lưu ký ức bền vững. Đặt `model` thành nhà cung cấp/mô hình chính xác như `ollama/qwen3:8b` khi lượt dọn dẹp này nên ở trên mô hình cục bộ; ghi đè này không kế thừa chuỗi dự phòng của phiên đang hoạt động. Bị bỏ qua khi workspace chỉ đọc. ### `agents.defaults.contextPruning` -Cắt tỉa **kết quả công cụ cũ** khỏi ngữ cảnh trong bộ nhớ trước khi gửi đến LLM. **Không** sửa đổi lịch sử phiên trên đĩa. +Cắt tỉa **kết quả công cụ cũ** khỏi ngữ cảnh trong bộ nhớ trước khi gửi tới LLM. **Không** sửa đổi lịch sử phiên trên đĩa. ```json5 { @@ -633,27 +639,27 @@ Cắt tỉa **kết quả công cụ cũ** khỏi ngữ cảnh trong bộ nhớ } ``` - + - `mode: "cache-ttl"` bật các lượt cắt tỉa. - `ttl` kiểm soát tần suất cắt tỉa có thể chạy lại (sau lần chạm cache gần nhất). -- Cắt tỉa sẽ soft-trim các kết quả công cụ quá lớn trước, rồi hard-clear các kết quả công cụ cũ hơn nếu cần. +- Cắt tỉa trước tiên soft-trim các kết quả công cụ quá lớn, rồi hard-clear các kết quả công cụ cũ hơn nếu cần. -**Soft-trim** giữ phần đầu + phần cuối và chèn `...` ở giữa. +**Soft-trim** giữ phần đầu + phần cuối và chèn `...` vào giữa. **Hard-clear** thay thế toàn bộ kết quả công cụ bằng placeholder. Ghi chú: -- Các khối hình ảnh không bao giờ bị cắt ngắn/xóa. +- Các khối hình ảnh không bao giờ bị cắt bớt/xóa. - Tỷ lệ dựa trên ký tự (xấp xỉ), không phải số token chính xác. -- Nếu có ít hơn `keepLastAssistants` tin nhắn assistant, cắt tỉa sẽ bị bỏ qua. +- Nếu có ít hơn `keepLastAssistants` tin nhắn assistant, việc cắt tỉa sẽ bị bỏ qua. -Xem [Cắt Tỉa Phiên](/vi/concepts/session-pruning) để biết chi tiết hành vi. +Xem [Cắt tỉa phiên](/vi/concepts/session-pruning) để biết chi tiết hành vi. -### Phát trực tuyến theo khối +### Truyền phát theo khối ```json5 { @@ -669,11 +675,11 @@ Xem [Cắt Tỉa Phiên](/vi/concepts/session-pruning) để biết chi tiết h } ``` -- Các kênh không phải Telegram cần đặt rõ `*.blockStreaming: true` để bật phản hồi theo khối. +- Các kênh không phải Telegram yêu cầu đặt rõ ràng `*.blockStreaming: true` để bật phản hồi theo khối. - Ghi đè theo kênh: `channels..blockStreamingCoalesce` (và các biến thể theo tài khoản). Signal/Slack/Discord/Google Chat mặc định `minChars: 1500`. - `humanDelay`: khoảng tạm dừng ngẫu nhiên giữa các phản hồi theo khối. `natural` = 800–2500ms. Ghi đè theo agent: `agents.list[].humanDelay`. -Xem [Phát Trực Tuyến](/vi/concepts/streaming) để biết chi tiết về hành vi + chia khối. +Xem [Truyền phát](/vi/concepts/streaming) để biết chi tiết hành vi + chia khối. ### Chỉ báo đang nhập @@ -688,7 +694,7 @@ Xem [Phát Trực Tuyến](/vi/concepts/streaming) để biết chi tiết về } ``` -- Mặc định: `instant` cho cuộc trò chuyện trực tiếp/lượt nhắc, `message` cho cuộc trò chuyện nhóm không nhắc đến. +- Mặc định: `instant` cho trò chuyện trực tiếp/lượt nhắc đến, `message` cho trò chuyện nhóm không nhắc đến. - Ghi đè theo phiên: `session.typingMode`, `session.typingIntervalSeconds`. Xem [Chỉ báo đang nhập](/vi/concepts/typing-indicators). @@ -697,7 +703,7 @@ Xem [Chỉ báo đang nhập](/vi/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing tùy chọn cho tác tử nhúng. Xem [Sandboxing](/vi/gateway/sandboxing) để đọc hướng dẫn đầy đủ. +Tạo sandbox tùy chọn cho tác tử nhúng. Xem [Tạo sandbox](/vi/gateway/sandboxing) để đọc hướng dẫn đầy đủ. ```json5 { @@ -800,17 +806,17 @@ Sandboxing tùy chọn cho tác tử nhúng. Xem [Sandboxing](/vi/gateway/sandbo - `ssh`: runtime từ xa chung dựa trên SSH - `openshell`: runtime OpenShell -Khi chọn `backend: "openshell"`, các cài đặt dành riêng cho runtime chuyển sang +Khi chọn `backend: "openshell"`, các thiết lập dành riêng cho runtime chuyển sang `plugins.entries.openshell.config`. **Cấu hình backend SSH:** - `target`: đích SSH ở dạng `user@host[:port]` - `command`: lệnh máy khách SSH (mặc định: `ssh`) -- `workspaceRoot`: gốc từ xa tuyệt đối dùng cho các không gian làm việc theo phạm vi +- `workspaceRoot`: gốc từ xa tuyệt đối dùng cho workspace theo từng phạm vi - `identityFile` / `certificateFile` / `knownHostsFile`: các tệp cục bộ hiện có được truyền cho OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: nội dung inline hoặc SecretRefs mà OpenClaw hiện thực hóa thành tệp tạm khi chạy -- `strictHostKeyChecking` / `updateHostKeys`: các núm điều chỉnh chính sách khóa máy chủ OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: nội dung nội tuyến hoặc SecretRefs mà OpenClaw hiện thực hóa thành tệp tạm thời khi chạy +- `strictHostKeyChecking` / `updateHostKeys`: các nút điều chỉnh chính sách khóa máy chủ OpenSSH **Thứ tự ưu tiên xác thực SSH:** @@ -821,23 +827,23 @@ Khi chọn `backend: "openshell"`, các cài đặt dành riêng cho runtime chu **Hành vi backend SSH:** -- khởi tạo không gian làm việc từ xa một lần sau khi tạo hoặc tạo lại -- sau đó giữ không gian làm việc SSH từ xa làm chuẩn +- khởi tạo workspace từ xa một lần sau khi tạo hoặc tạo lại +- sau đó giữ workspace SSH từ xa làm chuẩn - định tuyến `exec`, công cụ tệp và đường dẫn phương tiện qua SSH -- không tự động đồng bộ các thay đổi từ xa trở lại máy chủ +- không tự động đồng bộ thay đổi từ xa ngược về máy chủ - không hỗ trợ container trình duyệt sandbox -**Quyền truy cập không gian làm việc:** +**Quyền truy cập workspace:** -- `none`: không gian làm việc sandbox theo phạm vi dưới `~/.openclaw/sandboxes` -- `ro`: không gian làm việc sandbox tại `/workspace`, không gian làm việc tác tử được gắn chỉ đọc tại `/agent` -- `rw`: không gian làm việc tác tử được gắn đọc/ghi tại `/workspace` +- `none`: workspace sandbox theo từng phạm vi dưới `~/.openclaw/sandboxes` +- `ro`: workspace sandbox tại `/workspace`, workspace tác tử được gắn chỉ đọc tại `/agent` +- `rw`: workspace tác tử được gắn đọc/ghi tại `/workspace` **Phạm vi:** -- `session`: container + không gian làm việc theo phiên -- `agent`: một container + không gian làm việc cho mỗi tác tử (mặc định) -- `shared`: container và không gian làm việc dùng chung (không cách ly giữa các phiên) +- `session`: container + workspace theo từng phiên +- `agent`: một container + workspace cho mỗi tác tử (mặc định) +- `shared`: container và workspace dùng chung (không cô lập giữa các phiên) **Cấu hình Plugin OpenShell:** @@ -867,30 +873,30 @@ Khi chọn `backend: "openshell"`, các cài đặt dành riêng cho runtime chu **Chế độ OpenShell:** -- `mirror`: khởi tạo từ xa từ cục bộ trước khi exec, đồng bộ lại sau khi exec; không gian làm việc cục bộ vẫn là chuẩn -- `remote`: khởi tạo từ xa một lần khi sandbox được tạo, sau đó giữ không gian làm việc từ xa làm chuẩn +- `mirror`: khởi tạo từ xa từ cục bộ trước khi exec, đồng bộ ngược sau khi exec; workspace cục bộ vẫn là chuẩn +- `remote`: khởi tạo từ xa một lần khi sandbox được tạo, sau đó giữ workspace từ xa làm chuẩn -Ở chế độ `remote`, các chỉnh sửa cục bộ trên máy chủ được thực hiện bên ngoài OpenClaw sẽ không được tự động đồng bộ vào sandbox sau bước khởi tạo. +Ở chế độ `remote`, các chỉnh sửa cục bộ trên máy chủ được thực hiện ngoài OpenClaw sẽ không tự động được đồng bộ vào sandbox sau bước khởi tạo. Transport là SSH vào sandbox OpenShell, nhưng Plugin sở hữu vòng đời sandbox và đồng bộ mirror tùy chọn. -**`setupCommand`** chạy một lần sau khi tạo container (qua `sh -lc`). Cần đường ra mạng, root có thể ghi, người dùng root. +**`setupCommand`** chạy một lần sau khi tạo container (qua `sh -lc`). Cần lưu lượng mạng ra ngoài, gốc có thể ghi và người dùng root. -**Container mặc định là `network: "none"`** — đặt thành `"bridge"` (hoặc mạng bridge tùy chỉnh) nếu tác tử cần truy cập ra ngoài. -`"host"` bị chặn. `"container:"` bị chặn theo mặc định trừ khi bạn đặt rõ ràng +**Container mặc định dùng `network: "none"`** — đặt thành `"bridge"` (hoặc một mạng bridge tùy chỉnh) nếu tác tử cần truy cập ra ngoài. +`"host"` bị chặn. `"container:"` mặc định bị chặn trừ khi bạn đặt rõ ràng `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (phá kính khẩn cấp). -**Tệp đính kèm đến** được đưa vào `media/inbound/*` trong không gian làm việc đang hoạt động. +**Tệp đính kèm đến** được đưa vào `media/inbound/*` trong workspace đang hoạt động. -**`docker.binds`** gắn thêm các thư mục máy chủ; các bind toàn cục và theo tác tử được hợp nhất. +**`docker.binds`** gắn các thư mục máy chủ bổ sung; các bind toàn cục và theo tác tử được hợp nhất. -**Trình duyệt sandbox** (`sandbox.browser.enabled`): Chromium + CDP trong container. URL noVNC được chèn vào prompt hệ thống. Không yêu cầu `browser.enabled` trong `openclaw.json`. -Quyền truy cập quan sát noVNC dùng xác thực VNC theo mặc định và OpenClaw phát ra URL token ngắn hạn (thay vì lộ mật khẩu trong URL dùng chung). +**Trình duyệt sandbox** (`sandbox.browser.enabled`): Chromium + CDP trong một container. URL noVNC được chèn vào lời nhắc hệ thống. Không yêu cầu `browser.enabled` trong `openclaw.json`. +Quyền truy cập quan sát noVNC mặc định dùng xác thực VNC và OpenClaw phát ra một URL token ngắn hạn (thay vì để lộ mật khẩu trong URL dùng chung). -- `allowHostControl: false` (mặc định) chặn các phiên sandbox nhắm tới trình duyệt máy chủ. +- `allowHostControl: false` (mặc định) chặn các phiên sandbox nhắm vào trình duyệt máy chủ. - `network` mặc định là `openclaw-sandbox-browser` (mạng bridge chuyên dụng). Chỉ đặt thành `bridge` khi bạn rõ ràng muốn kết nối bridge toàn cục. -- `cdpSourceRange` tùy chọn giới hạn ingress CDP tại rìa container vào một dải CIDR (ví dụ `172.21.0.1/32`). -- `sandbox.browser.binds` chỉ gắn thêm các thư mục máy chủ vào container trình duyệt sandbox. Khi được đặt (bao gồm `[]`), nó thay thế `docker.binds` cho container trình duyệt. -- Mặc định khởi chạy được định nghĩa trong `scripts/sandbox-browser-entrypoint.sh` và tinh chỉnh cho máy chủ container: +- `cdpSourceRange` tùy chọn giới hạn lưu lượng CDP đi vào tại biên container theo một dải CIDR (ví dụ `172.21.0.1/32`). +- `sandbox.browser.binds` chỉ gắn các thư mục máy chủ bổ sung vào container trình duyệt sandbox. Khi được đặt (bao gồm `[]`), nó thay thế `docker.binds` cho container trình duyệt. +- Các mặc định khi khởi chạy được định nghĩa trong `scripts/sandbox-browser-entrypoint.sh` và tinh chỉnh cho máy chủ container: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -907,39 +913,39 @@ Quyền truy cập quan sát noVNC dùng xác thực VNC theo mặc định và - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (bật theo mặc định) - - `--disable-3d-apis`, `--disable-software-rasterizer` và `--disable-gpu` được - bật theo mặc định và có thể tắt bằng - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` nếu cần dùng WebGL/3D. + - `--disable-extensions` (mặc định bật) + - `--disable-3d-apis`, `--disable-software-rasterizer`, và `--disable-gpu` được + bật mặc định và có thể tắt bằng + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` nếu việc sử dụng WebGL/3D yêu cầu. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` bật lại tiện ích mở rộng nếu quy trình làm việc của bạn phụ thuộc vào chúng. - - `--renderer-process-limit=2` có thể thay đổi bằng + - `--renderer-process-limit=2` có thể được thay đổi bằng `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; đặt `0` để dùng giới hạn tiến trình mặc định của Chromium. - cộng thêm `--no-sandbox` khi `noSandbox` được bật. - - Mặc định là baseline của ảnh container; dùng ảnh trình duyệt tùy chỉnh với - entrypoint tùy chỉnh để thay đổi mặc định container. + - Các mặc định là đường cơ sở của image container; dùng image trình duyệt tùy chỉnh với entrypoint tùy chỉnh + để thay đổi mặc định của container. -Sandbox trình duyệt và `sandbox.docker.binds` chỉ dành cho Docker. +Tạo sandbox cho trình duyệt và `sandbox.docker.binds` chỉ dành cho Docker. -Xây dựng ảnh (từ checkout mã nguồn): +Xây dựng image (từ checkout mã nguồn): ```bash scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` -Đối với cài đặt npm không có checkout mã nguồn, xem [Sandboxing § Ảnh và thiết lập](/vi/gateway/sandboxing#images-and-setup) để biết các lệnh `docker build` inline. +Với các bản cài đặt npm không có checkout mã nguồn, xem [Tạo sandbox § Image và thiết lập](/vi/gateway/sandboxing#images-and-setup) để biết các lệnh `docker build` nội tuyến. -### `agents.list` (ghi đè theo tác tử) +### `agents.list` (ghi đè theo từng tác tử) Dùng `agents.list[].tts` để cấp cho tác tử nhà cung cấp TTS, giọng nói, mô hình, -kiểu hoặc chế độ tự động TTS riêng. Khối tác tử được deep-merge trên -`messages.tts` toàn cục, để thông tin xác thực dùng chung có thể ở một nơi trong khi từng +kiểu hoặc chế độ TTS tự động riêng. Khối tác tử được deep-merge lên trên +`messages.tts` toàn cục, nên thông tin xác thực dùng chung có thể nằm ở một nơi trong khi từng tác tử chỉ ghi đè các trường giọng nói hoặc nhà cung cấp mà chúng cần. Ghi đè của tác tử -đang hoạt động áp dụng cho trả lời nói tự động, `/tts audio`, `/tts status` và +đang hoạt động áp dụng cho trả lời nói tự động, `/tts audio`, `/tts status`, và công cụ tác tử `tts`. Xem [Chuyển văn bản thành giọng nói](/vi/tools/tts#per-agent-voice-overrides) để biết ví dụ nhà cung cấp và thứ tự ưu tiên. @@ -995,28 +1001,28 @@ công cụ tác tử `tts`. Xem [Chuyển văn bản thành giọng nói](/vi/to } ``` -- `id`: id tác tử ổn định (bắt buộc). -- `default`: khi đặt nhiều mục, mục đầu tiên được áp dụng (ghi cảnh báo). Nếu không đặt mục nào, mục đầu tiên trong danh sách là mặc định. -- `model`: dạng chuỗi đặt một mô hình chính nghiêm ngặt theo từng tác tử mà không có mô hình dự phòng; dạng đối tượng `{ primary }` cũng nghiêm ngặt trừ khi bạn thêm `fallbacks`. Dùng `{ primary, fallbacks: [...] }` để cho tác tử đó dùng dự phòng, hoặc `{ primary, fallbacks: [] }` để làm rõ hành vi nghiêm ngặt. Các tác vụ Cron chỉ ghi đè `primary` vẫn kế thừa các dự phòng mặc định trừ khi bạn đặt `fallbacks: []`. -- `params`: tham số luồng theo từng tác tử được hợp nhất đè lên mục mô hình đã chọn trong `agents.defaults.models`. Dùng mục này cho các ghi đè riêng của tác tử như `cacheRetention`, `temperature`, hoặc `maxTokens` mà không cần sao chép toàn bộ danh mục mô hình. -- `tts`: các ghi đè chuyển văn bản thành giọng nói tùy chọn theo từng tác tử. Khối này hợp nhất sâu đè lên `messages.tts`, vì vậy hãy giữ thông tin xác thực nhà cung cấp dùng chung và chính sách dự phòng trong `messages.tts`, rồi chỉ đặt các giá trị riêng theo persona như nhà cung cấp, giọng, mô hình, kiểu, hoặc chế độ tự động tại đây. -- `skills`: danh sách cho phép Skills tùy chọn theo từng tác tử. Nếu bỏ qua, tác tử kế thừa `agents.defaults.skills` khi được đặt; danh sách tường minh sẽ thay thế mặc định thay vì hợp nhất, và `[]` nghĩa là không có Skills. -- `thinkingDefault`: mức suy nghĩ mặc định tùy chọn theo từng tác tử (`off | minimal | low | medium | high | xhigh | adaptive | max`). Ghi đè `agents.defaults.thinkingDefault` cho tác tử này khi không đặt ghi đè theo từng tin nhắn hoặc phiên. Hồ sơ nhà cung cấp/mô hình đã chọn kiểm soát giá trị nào hợp lệ; với Google Gemini, `adaptive` giữ suy nghĩ động do nhà cung cấp sở hữu (`thinkingLevel` bị bỏ qua trên Gemini 3/3.1, `thinkingBudget: -1` trên Gemini 2.5). -- `reasoningDefault`: khả năng hiển thị suy luận mặc định tùy chọn theo từng tác tử (`on | off | stream`). Ghi đè `agents.defaults.reasoningDefault` cho tác tử này khi không đặt ghi đè suy luận theo từng tin nhắn hoặc phiên. -- `fastModeDefault`: mặc định tùy chọn theo từng tác tử cho chế độ nhanh (`true | false`). Áp dụng khi không đặt ghi đè chế độ nhanh theo từng tin nhắn hoặc phiên. -- `agentRuntime`: ghi đè chính sách runtime cấp thấp tùy chọn theo từng tác tử. Dùng `{ id: "codex" }` để biến một tác tử thành chỉ dùng Codex trong khi các tác tử khác giữ dự phòng PI mặc định ở chế độ `auto`. -- `runtime`: bộ mô tả runtime tùy chọn theo từng tác tử. Dùng `type: "acp"` với các mặc định `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) khi tác tử nên mặc định dùng các phiên harness ACP. +- `id`: id tác nhân ổn định (bắt buộc). +- `default`: khi đặt nhiều mục, mục đầu tiên thắng (ghi cảnh báo). Nếu không đặt mục nào, mục đầu tiên trong danh sách là mặc định. +- `model`: dạng chuỗi đặt primary nghiêm ngặt theo từng tác nhân, không có dự phòng mô hình; dạng đối tượng `{ primary }` cũng nghiêm ngặt trừ khi bạn thêm `fallbacks`. Dùng `{ primary, fallbacks: [...] }` để cho tác nhân đó dùng dự phòng, hoặc `{ primary, fallbacks: [] }` để làm rõ hành vi nghiêm ngặt. Các tác vụ Cron chỉ ghi đè `primary` vẫn kế thừa dự phòng mặc định trừ khi bạn đặt `fallbacks: []`. +- `params`: tham số luồng theo từng tác nhân được hợp nhất lên mục mô hình đã chọn trong `agents.defaults.models`. Dùng mục này cho các ghi đè riêng theo tác nhân như `cacheRetention`, `temperature`, hoặc `maxTokens` mà không cần sao chép toàn bộ catalog mô hình. +- `tts`: ghi đè chuyển văn bản thành giọng nói tùy chọn theo từng tác nhân. Khối này hợp nhất sâu lên `messages.tts`, vì vậy hãy giữ thông tin xác thực provider dùng chung và chính sách dự phòng trong `messages.tts`, rồi chỉ đặt các giá trị riêng theo persona như provider, voice, model, style, hoặc chế độ tự động tại đây. +- `skills`: danh sách cho phép Skills tùy chọn theo từng tác nhân. Nếu bỏ qua, tác nhân kế thừa `agents.defaults.skills` khi được đặt; danh sách tường minh sẽ thay thế mặc định thay vì hợp nhất, và `[]` nghĩa là không có Skills. +- `thinkingDefault`: mức suy nghĩ mặc định tùy chọn theo từng tác nhân (`off | minimal | low | medium | high | xhigh | adaptive | max`). Ghi đè `agents.defaults.thinkingDefault` cho tác nhân này khi không đặt ghi đè theo từng tin nhắn hoặc phiên. Hồ sơ provider/mô hình đã chọn kiểm soát giá trị nào hợp lệ; với Google Gemini, `adaptive` giữ suy nghĩ động do provider sở hữu (`thinkingLevel` bị bỏ qua trên Gemini 3/3.1, `thinkingBudget: -1` trên Gemini 2.5). +- `reasoningDefault`: khả năng hiển thị suy luận mặc định tùy chọn theo từng tác nhân (`on | off | stream`). Ghi đè `agents.defaults.reasoningDefault` cho tác nhân này khi không đặt ghi đè suy luận theo từng tin nhắn hoặc phiên. +- `fastModeDefault`: mặc định tùy chọn theo từng tác nhân cho chế độ nhanh (`true | false`). Áp dụng khi không đặt ghi đè chế độ nhanh theo từng tin nhắn hoặc phiên. +- `agentRuntime`: ghi đè chính sách runtime cấp thấp tùy chọn theo từng tác nhân. Dùng `{ id: "codex" }` để biến một tác nhân thành chỉ dùng Codex, trong khi các tác nhân khác giữ dự phòng PI mặc định ở chế độ `auto`. +- `runtime`: bộ mô tả runtime tùy chọn theo từng tác nhân. Dùng `type: "acp"` với các mặc định `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) khi tác nhân nên mặc định dùng các phiên harness ACP. - `identity.avatar`: đường dẫn tương đối theo workspace, URL `http(s)`, hoặc URI `data:`. - `identity` suy ra các mặc định: `ackReaction` từ `emoji`, `mentionPatterns` từ `name`/`emoji`. -- `subagents.allowAgents`: danh sách cho phép các id tác tử cho mục tiêu `sessions_spawn.agentId` tường minh (`["*"]` = bất kỳ; mặc định: chỉ cùng tác tử). Bao gồm id của bên yêu cầu khi các lệnh gọi `agentId` tự nhắm mục tiêu nên được cho phép. -- Chốt bảo vệ kế thừa sandbox: nếu phiên của bên yêu cầu đang trong sandbox, `sessions_spawn` từ chối các mục tiêu sẽ chạy không có sandbox. -- `subagents.requireAgentId`: khi true, chặn các lệnh gọi `sessions_spawn` bỏ qua `agentId` (buộc chọn hồ sơ tường minh; mặc định: false). +- `subagents.allowAgents`: danh sách cho phép id tác nhân cho các mục tiêu `sessions_spawn.agentId` tường minh (`["*"]` = bất kỳ; mặc định: chỉ cùng tác nhân). Bao gồm id của bên yêu cầu khi cần cho phép các lệnh gọi `agentId` tự nhắm đến chính nó. +- Bộ bảo vệ kế thừa sandbox: nếu phiên của bên yêu cầu được sandbox, `sessions_spawn` từ chối các mục tiêu sẽ chạy không sandbox. +- `subagents.requireAgentId`: khi là true, chặn các lệnh gọi `sessions_spawn` bỏ qua `agentId` (buộc chọn hồ sơ tường minh; mặc định: false). --- -## Định tuyến đa tác tử +## Định tuyến đa tác nhân -Chạy nhiều tác tử cô lập bên trong một Gateway. Xem [Đa tác tử](/vi/concepts/multi-agent). +Chạy nhiều tác nhân tách biệt bên trong một Gateway. Xem [Đa tác nhân](/vi/concepts/multi-agent). ```json5 { @@ -1033,31 +1039,31 @@ Chạy nhiều tác tử cô lập bên trong một Gateway. Xem [Đa tác tử] } ``` -### Trường khớp ràng buộc +### Trường khớp binding -- `type` (tùy chọn): `route` cho định tuyến thông thường (thiếu type sẽ mặc định là route), `acp` cho các ràng buộc cuộc trò chuyện ACP bền vững. +- `type` (tùy chọn): `route` cho định tuyến thông thường (thiếu type thì mặc định là route), `acp` cho các binding hội thoại ACP liên tục. - `match.channel` (bắt buộc) - `match.accountId` (tùy chọn; `*` = bất kỳ tài khoản nào; bỏ qua = tài khoản mặc định) - `match.peer` (tùy chọn; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (tùy chọn; theo từng kênh) -- `acp` (tùy chọn; chỉ dành cho `type: "acp"`): `{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId` (tùy chọn; riêng theo kênh) +- `acp` (tùy chọn; chỉ cho `type: "acp"`): `{ mode, label, cwd, backend }` -**Thứ tự khớp xác định:** +**Thứ tự khớp tất định:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (chính xác, không có peer/guild/team) 5. `match.accountId: "*"` (toàn kênh) -6. Tác tử mặc định +6. Tác nhân mặc định -Trong mỗi tầng, mục `bindings` khớp đầu tiên được áp dụng. +Trong mỗi tầng, mục `bindings` khớp đầu tiên sẽ thắng. -Với các mục `type: "acp"`, OpenClaw phân giải theo danh tính cuộc trò chuyện chính xác (`match.channel` + tài khoản + `match.peer.id`) và không dùng thứ tự tầng ràng buộc route ở trên. +Với các mục `type: "acp"`, OpenClaw phân giải theo danh tính hội thoại chính xác (`match.channel` + tài khoản + `match.peer.id`) và không dùng thứ tự tầng binding tuyến ở trên. -### Hồ sơ truy cập theo từng tác tử +### Hồ sơ truy cập theo từng tác nhân - + ```json5 { @@ -1075,7 +1081,7 @@ Với các mục `type: "acp"`, OpenClaw phân giải theo danh tính cuộc tr - + ```json5 { @@ -1150,7 +1156,7 @@ Với các mục `type: "acp"`, OpenClaw phân giải theo danh tính cuộc tr -Xem [Hộp cát và công cụ đa tác tử](/vi/tools/multi-agent-sandbox-tools) để biết chi tiết về thứ tự ưu tiên. +Xem [Hộp cát & công cụ đa tác nhân](/vi/tools/multi-agent-sandbox-tools) để biết chi tiết về thứ tự ưu tiên. --- @@ -1203,32 +1209,32 @@ Xem [Hộp cát và công cụ đa tác tử](/vi/tools/multi-agent-sandbox-tool - **`scope`**: chiến lược nhóm phiên cơ sở cho ngữ cảnh trò chuyện nhóm. - `per-sender` (mặc định): mỗi người gửi có một phiên cô lập trong một ngữ cảnh kênh. - - `global`: tất cả người tham gia trong một ngữ cảnh kênh dùng chung một phiên duy nhất (chỉ dùng khi chủ định có ngữ cảnh dùng chung). + - `global`: tất cả người tham gia trong một ngữ cảnh kênh dùng chung một phiên duy nhất (chỉ dùng khi chủ đích là chia sẻ ngữ cảnh). - **`dmScope`**: cách nhóm DM. - `main`: tất cả DM dùng chung phiên chính. - `per-peer`: cô lập theo id người gửi trên các kênh. - `per-channel-peer`: cô lập theo từng kênh + người gửi (khuyến nghị cho hộp thư đến nhiều người dùng). - `per-account-channel-peer`: cô lập theo từng tài khoản + kênh + người gửi (khuyến nghị cho nhiều tài khoản). -- **`identityLinks`**: ánh xạ các id chuẩn sang peer có tiền tố nhà cung cấp để chia sẻ phiên liên kênh. Các lệnh dock như `/dock_discord` dùng cùng ánh xạ để chuyển tuyến trả lời của phiên đang hoạt động sang một peer kênh liên kết khác; xem [Docking kênh](/vi/concepts/channel-docking). -- **`reset`**: chính sách đặt lại chính. `daily` đặt lại vào giờ địa phương `atHour`; `idle` đặt lại sau `idleMinutes`. Khi cấu hình cả hai, chính sách nào hết hạn trước sẽ thắng. Độ mới của đặt lại hằng ngày dùng `sessionStartedAt` của hàng phiên; độ mới của đặt lại do không hoạt động dùng `lastInteractionAt`. Các lần ghi nền/sự kiện hệ thống như Heartbeat, đánh thức Cron, thông báo exec, và ghi sổ Gateway có thể cập nhật `updatedAt`, nhưng chúng không giữ cho các phiên hằng ngày/không hoạt động luôn mới. +- **`identityLinks`**: ánh xạ id chuẩn sang peer có tiền tố nhà cung cấp để chia sẻ phiên liên kênh. Các lệnh neo như `/dock_discord` dùng cùng ánh xạ để chuyển tuyến trả lời của phiên đang hoạt động sang một peer kênh đã liên kết khác; xem [Neo kênh](/vi/concepts/channel-docking). +- **`reset`**: chính sách đặt lại chính. `daily` đặt lại vào giờ địa phương `atHour`; `idle` đặt lại sau `idleMinutes`. Khi cấu hình cả hai, chính sách nào hết hạn trước sẽ được áp dụng. Độ mới của đặt lại hằng ngày dùng `sessionStartedAt` của hàng phiên; độ mới của đặt lại do nhàn rỗi dùng `lastInteractionAt`. Các lần ghi nền/sự kiện hệ thống như Heartbeat, đánh thức Cron, thông báo exec và ghi sổ Gateway có thể cập nhật `updatedAt`, nhưng chúng không giữ cho phiên hằng ngày/nhàn rỗi còn mới. - **`resetByType`**: ghi đè theo từng loại (`direct`, `group`, `thread`). `dm` cũ được chấp nhận làm bí danh cho `direct`. - **`mainKey`**: trường cũ. Runtime luôn dùng `"main"` cho bucket trò chuyện trực tiếp chính. -- **`agentToAgent.maxPingPongTurns`**: số lượt trả lời qua lại tối đa giữa các agent trong trao đổi agent-to-agent (số nguyên, phạm vi: `0`–`5`). `0` tắt chuỗi ping-pong. -- **`sendPolicy`**: khớp theo `channel`, `chatType` (`direct|group|channel`, với bí danh cũ `dm`), `keyPrefix`, hoặc `rawKeyPrefix`. Lệnh từ chối đầu tiên sẽ thắng. -- **`maintenance`**: các điều khiển dọn dẹp + lưu giữ kho phiên. +- **`agentToAgent.maxPingPongTurns`**: số lượt trả lời qua lại tối đa giữa các tác nhân trong trao đổi tác nhân-với-tác nhân (số nguyên, phạm vi: `0`–`5`). `0` tắt chuỗi ping-pong. +- **`sendPolicy`**: khớp theo `channel`, `chatType` (`direct|group|channel`, với bí danh cũ `dm`), `keyPrefix`, hoặc `rawKeyPrefix`. Quy tắc từ chối đầu tiên thắng. +- **`maintenance`**: điều khiển dọn dẹp + lưu giữ kho phiên. - `mode`: `warn` chỉ phát cảnh báo; `enforce` áp dụng dọn dẹp. - `pruneAfter`: ngưỡng tuổi cho các mục cũ (mặc định `30d`). - - `maxEntries`: số mục tối đa trong `sessions.json` (mặc định `500`). Runtime ghi dọn dẹp theo lô với một bộ đệm mực nước cao nhỏ cho các giới hạn kích cỡ sản xuất; `openclaw sessions cleanup --enforce` áp dụng giới hạn ngay lập tức. - - `rotateBytes`: đã ngừng dùng và bị bỏ qua; `openclaw doctor --fix` xóa nó khỏi các cấu hình cũ hơn. - - `resetArchiveRetention`: thời gian lưu giữ cho kho lưu trữ bản chép lời `*.reset.`. Mặc định là `pruneAfter`; đặt `false` để tắt. - - `maxDiskBytes`: ngân sách đĩa tùy chọn cho thư mục phiên. Ở chế độ `warn`, nó ghi cảnh báo; ở chế độ `enforce`, nó xóa các artifact/phiên cũ nhất trước. + - `maxEntries`: số mục tối đa trong `sessions.json` (mặc định `500`). Runtime ghi dọn dẹp hàng loạt với một bộ đệm ngưỡng cao nhỏ cho các giới hạn cỡ sản xuất; `openclaw sessions cleanup --enforce` áp dụng giới hạn ngay lập tức. + - `rotateBytes`: đã ngừng dùng và bị bỏ qua; `openclaw doctor --fix` xóa trường này khỏi các cấu hình cũ. + - `resetArchiveRetention`: thời gian lưu giữ cho kho lưu trữ bản ghi `*.reset.`. Mặc định là `pruneAfter`; đặt `false` để tắt. + - `maxDiskBytes`: ngân sách đĩa tùy chọn cho thư mục phiên. Ở chế độ `warn`, nó ghi cảnh báo; ở chế độ `enforce`, nó xóa hiện vật/phiên cũ nhất trước. - `highWaterBytes`: mục tiêu tùy chọn sau khi dọn dẹp theo ngân sách. Mặc định là `80%` của `maxDiskBytes`. - **`threadBindings`**: mặc định toàn cục cho các tính năng phiên gắn với luồng. - `enabled`: công tắc mặc định chính (nhà cung cấp có thể ghi đè; Discord dùng `channels.discord.threadBindings.enabled`) - - `idleHours`: tự động bỏ tập trung do không hoạt động mặc định theo giờ (`0` tắt; nhà cung cấp có thể ghi đè) - - `maxAgeHours`: tuổi tối đa cứng mặc định theo giờ (`0` tắt; nhà cung cấp có thể ghi đè) - - `spawnSessions`: cổng mặc định để tạo phiên làm việc gắn với luồng từ `sessions_spawn` và các lần sinh luồng ACP. Mặc định là `true` khi liên kết luồng được bật; nhà cung cấp/tài khoản có thể ghi đè. - - `defaultSpawnContext`: ngữ cảnh subagent gốc mặc định cho các lần sinh gắn với luồng (`"fork"` hoặc `"isolated"`). Mặc định là `"fork"`. + - `idleHours`: tự động bỏ tập trung do không hoạt động mặc định tính bằng giờ (`0` tắt; nhà cung cấp có thể ghi đè) + - `maxAgeHours`: tuổi tối đa cứng mặc định tính bằng giờ (`0` tắt; nhà cung cấp có thể ghi đè) + - `spawnSessions`: cổng mặc định để tạo phiên làm việc gắn với luồng từ `sessions_spawn` và các lần tạo luồng ACP. Mặc định là `true` khi ràng buộc luồng được bật; nhà cung cấp/tài khoản có thể ghi đè. + - `defaultSpawnContext`: ngữ cảnh tác nhân con gốc mặc định cho các lần tạo gắn với luồng (`"fork"` hoặc `"isolated"`). Mặc định là `"fork"`. @@ -1268,34 +1274,34 @@ Xem [Hộp cát và công cụ đa tác tử](/vi/tools/multi-agent-sandbox-tool Ghi đè theo kênh/tài khoản: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Cách phân giải (mục cụ thể nhất thắng): tài khoản → kênh → toàn cục. `""` tắt và dừng chuỗi kế thừa. `"auto"` suy ra `[{identity.name}]`. +Cách phân giải (mục cụ thể nhất thắng): tài khoản → kênh → toàn cục. `""` sẽ tắt và dừng chuỗi kế thừa. `"auto"` suy ra `[{identity.name}]`. **Biến mẫu:** | Biến | Mô tả | Ví dụ | | ----------------- | ------------------------ | --------------------------- | -| `{model}` | Tên model ngắn | `claude-opus-4-6` | -| `{modelFull}` | Mã định danh model đầy đủ | `anthropic/claude-opus-4-6` | +| `{model}` | Tên mô hình rút gọn | `claude-opus-4-6` | +| `{modelFull}` | Mã định danh mô hình đầy đủ | `anthropic/claude-opus-4-6` | | `{provider}` | Tên nhà cung cấp | `anthropic` | -| `{thinkingLevel}` | Mức suy luận hiện tại | `high`, `low`, `off` | -| `{identity.name}` | Tên định danh tác tử | (giống như `"auto"`) | +| `{thinkingLevel}` | Mức suy nghĩ hiện tại | `high`, `low`, `off` | +| `{identity.name}` | Tên danh tính tác nhân | (giống như `"auto"`) | -Biến không phân biệt chữ hoa/thường. `{think}` là bí danh của `{thinkingLevel}`. +Biến không phân biệt chữ hoa chữ thường. `{think}` là bí danh của `{thinkingLevel}`. ### Phản ứng xác nhận -- Mặc định là `identity.emoji` của tác tử đang hoạt động, nếu không thì là `"👀"`. Đặt `""` để tắt. +- Mặc định dùng `identity.emoji` của tác nhân đang hoạt động, nếu không thì dùng `"👀"`. Đặt `""` để tắt. - Ghi đè theo kênh: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Thứ tự phân giải: tài khoản → kênh → `messages.ackReaction` → phương án dự phòng từ định danh. +- Thứ tự phân giải: tài khoản → kênh → `messages.ackReaction` → dự phòng theo danh tính. - Phạm vi: `group-mentions` (mặc định), `group-all`, `direct`, `all`. - `removeAckAfterReply`: xóa xác nhận sau khi trả lời trên các kênh hỗ trợ phản ứng như Slack, Discord, Telegram, WhatsApp và BlueBubbles. - `messages.statusReactions.enabled`: bật phản ứng trạng thái vòng đời trên Slack, Discord và Telegram. - Trên Slack và Discord, khi không đặt thì phản ứng trạng thái vẫn được bật khi phản ứng xác nhận đang hoạt động. - Trên Telegram, đặt rõ thành `true` để bật phản ứng trạng thái vòng đời. + Trên Slack và Discord, nếu chưa đặt thì phản ứng trạng thái vẫn được bật khi phản ứng xác nhận đang hoạt động. + Trên Telegram, hãy đặt rõ thành `true` để bật phản ứng trạng thái vòng đời. -### Debounce đầu vào +### Gộp chờ tin nhắn đến -Gộp các tin nhắn chỉ chứa văn bản được gửi nhanh từ cùng một người gửi thành một lượt tác tử duy nhất. Media/tệp đính kèm sẽ đẩy ngay lập tức. Lệnh điều khiển bỏ qua debounce. +Gộp các tin nhắn chỉ có văn bản được gửi nhanh liên tiếp từ cùng một người gửi thành một lượt tác nhân duy nhất. Phương tiện/tệp đính kèm sẽ xả ngay lập tức. Lệnh điều khiển bỏ qua cơ chế gộp chờ. ### TTS (văn bản thành giọng nói) @@ -1345,19 +1351,19 @@ Gộp các tin nhắn chỉ chứa văn bản được gửi nhanh từ cùng m } ``` -- `auto` kiểm soát chế độ auto-TTS mặc định: `off`, `always`, `inbound` hoặc `tagged`. `/tts on|off` có thể ghi đè tùy chọn cục bộ, và `/tts status` hiển thị trạng thái có hiệu lực. -- `summaryModel` ghi đè `agents.defaults.model.primary` cho bản tóm tắt tự động. -- `modelOverrides` được bật theo mặc định; `modelOverrides.allowProvider` mặc định là `false` (cần chọn bật). +- `auto` điều khiển chế độ tự động TTS mặc định: `off`, `always`, `inbound` hoặc `tagged`. `/tts on|off` có thể ghi đè tùy chọn cục bộ, và `/tts status` hiển thị trạng thái hiệu lực. +- `summaryModel` ghi đè `agents.defaults.model.primary` cho phần tóm tắt tự động. +- `modelOverrides` được bật theo mặc định; `modelOverrides.allowProvider` mặc định là `false` (phải chọn bật). - Khóa API dự phòng về `ELEVENLABS_API_KEY`/`XI_API_KEY` và `OPENAI_API_KEY`. -- Các nhà cung cấp giọng nói đi kèm thuộc sở hữu Plugin. Nếu `plugins.allow` được đặt, hãy bao gồm từng Plugin nhà cung cấp TTS mà bạn muốn dùng, ví dụ `microsoft` cho Edge TTS. ID nhà cung cấp cũ `edge` được chấp nhận làm bí danh cho `microsoft`. -- `providers.openai.baseUrl` ghi đè điểm cuối OpenAI TTS. Thứ tự phân giải là cấu hình, rồi `OPENAI_TTS_BASE_URL`, rồi `https://api.openai.com/v1`. -- Khi `providers.openai.baseUrl` trỏ đến một điểm cuối không phải OpenAI, OpenClaw coi đó là máy chủ TTS tương thích với OpenAI và nới lỏng kiểm tra hợp lệ model/giọng nói. +- Các nhà cung cấp giọng nói đi kèm thuộc sở hữu của Plugin. Nếu đã đặt `plugins.allow`, hãy bao gồm từng Plugin nhà cung cấp TTS mà bạn muốn dùng, ví dụ `microsoft` cho Edge TTS. Mã định danh nhà cung cấp cũ `edge` được chấp nhận làm bí danh cho `microsoft`. +- `providers.openai.baseUrl` ghi đè điểm cuối OpenAI TTS. Thứ tự phân giải là cấu hình, sau đó `OPENAI_TTS_BASE_URL`, rồi `https://api.openai.com/v1`. +- Khi `providers.openai.baseUrl` trỏ đến một điểm cuối không phải OpenAI, OpenClaw coi đó là máy chủ TTS tương thích OpenAI và nới lỏng việc xác thực mô hình/giọng nói. --- -## Trò chuyện +## Talk -Mặc định cho chế độ Trò chuyện (macOS/iOS/Android). +Giá trị mặc định cho chế độ Talk (macOS/iOS/Android). ```json5 { @@ -1386,16 +1392,16 @@ Mặc định cho chế độ Trò chuyện (macOS/iOS/Android). } ``` -- `talk.provider` phải khớp với một khóa trong `talk.providers` khi nhiều nhà cung cấp Trò chuyện được cấu hình. -- Các khóa Trò chuyện phẳng cũ (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) chỉ dành cho tương thích và được tự động di chuyển vào `talk.providers.`. -- ID giọng nói dự phòng về `ELEVENLABS_VOICE_ID` hoặc `SAG_VOICE_ID`. +- `talk.provider` phải khớp với một khóa trong `talk.providers` khi cấu hình nhiều nhà cung cấp Talk. +- Các khóa Talk phẳng cũ (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) chỉ dành cho tương thích và được tự động di chuyển vào `talk.providers.`. +- Mã định danh giọng nói dự phòng về `ELEVENLABS_VOICE_ID` hoặc `SAG_VOICE_ID`. - `providers.*.apiKey` chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef. -- Phương án dự phòng `ELEVENLABS_API_KEY` chỉ áp dụng khi không có khóa API Trò chuyện nào được cấu hình. -- `providers.*.voiceAliases` cho phép chỉ thị Trò chuyện dùng tên thân thiện. -- `providers.mlx.modelId` chọn repo Hugging Face được trình trợ giúp MLX cục bộ trên macOS sử dụng. Nếu bỏ qua, macOS dùng `mlx-community/Soprano-80M-bf16`. -- Phát lại MLX trên macOS chạy qua trình trợ giúp `openclaw-mlx-tts` đi kèm khi có, hoặc một tệp thực thi trên `PATH`; `OPENCLAW_MLX_TTS_BIN` ghi đè đường dẫn trình trợ giúp cho mục đích phát triển. -- `speechLocale` đặt ID locale BCP 47 được tính năng nhận dạng giọng nói Trò chuyện trên iOS/macOS sử dụng. Để trống để dùng mặc định của thiết bị. -- `silenceTimeoutMs` kiểm soát khoảng thời gian chế độ Trò chuyện chờ sau khi người dùng im lặng trước khi gửi bản chép lời. Không đặt thì giữ khoảng tạm dừng mặc định của nền tảng (`700 ms trên macOS và Android, 900 ms trên iOS`). +- Dự phòng `ELEVENLABS_API_KEY` chỉ áp dụng khi không cấu hình khóa API Talk. +- `providers.*.voiceAliases` cho phép chỉ thị Talk dùng tên thân thiện. +- `providers.mlx.modelId` chọn kho Hugging Face được trình trợ giúp MLX cục bộ trên macOS sử dụng. Nếu bỏ qua, macOS dùng `mlx-community/Soprano-80M-bf16`. +- Phát lại MLX trên macOS chạy qua trình trợ giúp `openclaw-mlx-tts` đi kèm khi có, hoặc một tệp thực thi trên `PATH`; `OPENCLAW_MLX_TTS_BIN` ghi đè đường dẫn trình trợ giúp cho phát triển. +- `speechLocale` đặt mã ngôn ngữ BCP 47 được nhận dạng giọng nói Talk trên iOS/macOS sử dụng. Để trống để dùng mặc định của thiết bị. +- `silenceTimeoutMs` điều khiển thời gian chế độ Talk chờ sau khi người dùng im lặng trước khi gửi bản chép lời. Nếu chưa đặt, cửa sổ tạm dừng mặc định của nền tảng được giữ nguyên (`700 ms trên macOS và Android, 900 ms trên iOS`). --- diff --git a/docs/vi/gateway/config-channels.md b/docs/vi/gateway/config-channels.md index 400d56be3..fa737eb57 100644 --- a/docs/vi/gateway/config-channels.md +++ b/docs/vi/gateway/config-channels.md @@ -1,24 +1,24 @@ --- read_when: - - Cấu hình Plugin kênh (xác thực, kiểm soát truy cập, đa tài khoản) + - Cấu hình Plugin kênh (xác thực, kiểm soát quyền truy cập, đa tài khoản) - Khắc phục sự cố các khóa cấu hình theo từng kênh - - Kiểm tra chính sách DM, chính sách nhóm hoặc cơ chế kiểm soát nhắc đến -summary: 'Cấu hình kênh: kiểm soát truy cập, ghép nối, khóa theo từng kênh trên Slack, Discord, Telegram, WhatsApp, Matrix, iMessage và nhiều nền tảng khác' + - Kiểm tra chính sách tin nhắn trực tiếp, chính sách nhóm hoặc cơ chế kiểm soát lượt nhắc đến +summary: 'Cấu hình kênh: kiểm soát truy cập, ghép nối, khóa theo từng kênh trên Slack, Discord, Telegram, WhatsApp, Matrix, iMessage và nhiều kênh khác' title: Cấu hình — kênh x-i18n: - generated_at: "2026-05-03T21:30:54Z" + generated_at: "2026-05-04T02:24:17Z" model: gpt-5.5 provider: openai - source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c + source_hash: 57dcc0b5148324ea6fdee51b7b6e97ec7bd7dc3ca89518ab0816fe4172feefbc source_path: gateway/config-channels.md workflow: 16 --- -Các khóa cấu hình theo kênh dưới `channels.*`. Bao gồm quyền truy cập DM và nhóm, -thiết lập nhiều tài khoản, cổng kiểm soát bằng lượt nhắc, và các khóa theo kênh cho Slack, Discord, -Telegram, WhatsApp, Matrix, iMessage, và các Plugin kênh đi kèm khác. +Cấu hình theo từng kênh đặt dưới các khóa `channels.*`. Bao gồm quyền truy cập DM và nhóm, +thiết lập nhiều tài khoản, kiểm soát bằng nhắc đến, và các khóa theo từng kênh cho Slack, Discord, +Telegram, WhatsApp, Matrix, iMessage, cùng các Plugin kênh đi kèm khác. -Đối với agent, công cụ, thời gian chạy Gateway, và các khóa cấp cao nhất khác, xem +Đối với agent, công cụ, thời gian chạy Gateway và các khóa cấp cao khác, xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference). ## Kênh @@ -27,30 +27,30 @@ Mỗi kênh tự động khởi động khi phần cấu hình của kênh đó ### Quyền truy cập DM và nhóm -Tất cả kênh đều hỗ trợ chính sách DM và chính sách nhóm: +Tất cả các kênh đều hỗ trợ chính sách DM và chính sách nhóm: | Chính sách DM | Hành vi | | ------------------- | --------------------------------------------------------------- | -| `pairing` (mặc định) | Người gửi chưa biết nhận mã ghép nối dùng một lần; chủ sở hữu phải phê duyệt | -| `allowlist` | Chỉ người gửi trong `allowFrom` (hoặc kho cho phép đã ghép nối) | -| `open` | Cho phép tất cả DM gửi đến (yêu cầu `allowFrom: ["*"]`) | -| `disabled` | Bỏ qua tất cả DM gửi đến | +| `pairing` (mặc định) | Người gửi không xác định nhận mã ghép đôi một lần; chủ sở hữu phải phê duyệt | +| `allowlist` | Chỉ người gửi trong `allowFrom` (hoặc kho cho phép đã ghép đôi) | +| `open` | Cho phép tất cả DM đến (yêu cầu `allowFrom: ["*"]`) | +| `disabled` | Bỏ qua tất cả DM đến | | Chính sách nhóm | Hành vi | | --------------------- | ------------------------------------------------------ | -| `allowlist` (mặc định) | Chỉ các nhóm khớp với danh sách cho phép đã cấu hình | -| `open` | Bỏ qua danh sách cho phép của nhóm (cổng kiểm soát bằng lượt nhắc vẫn áp dụng) | -| `disabled` | Chặn tất cả tin nhắn nhóm/phòng | +| `allowlist` (mặc định) | Chỉ các nhóm khớp với danh sách cho phép đã cấu hình | +| `open` | Bỏ qua danh sách cho phép của nhóm (kiểm soát nhắc đến vẫn áp dụng) | +| `disabled` | Chặn tất cả tin nhắn nhóm/phòng | -`channels.defaults.groupPolicy` đặt mặc định khi `groupPolicy` của nhà cung cấp chưa được đặt. -Mã ghép nối hết hạn sau 1 giờ. Các yêu cầu ghép nối DM đang chờ được giới hạn ở **3 yêu cầu mỗi kênh**. -Nếu toàn bộ khối nhà cung cấp bị thiếu (`channels.` không có), chính sách nhóm thời gian chạy quay về `allowlist` (đóng khi lỗi) kèm cảnh báo khi khởi động. +`channels.defaults.groupPolicy` đặt giá trị mặc định khi `groupPolicy` của nhà cung cấp chưa được đặt. +Mã ghép đôi hết hạn sau 1 giờ. Các yêu cầu ghép đôi DM đang chờ được giới hạn ở **3 yêu cầu mỗi kênh**. +Nếu thiếu hoàn toàn một khối nhà cung cấp (`channels.` không có), chính sách nhóm khi chạy sẽ quay về `allowlist` (đóng khi lỗi) kèm cảnh báo lúc khởi động. ### Ghi đè mô hình theo kênh -Dùng `channels.modelByChannel` để ghim các ID kênh cụ thể vào một mô hình. Giá trị chấp nhận `provider/model` hoặc bí danh mô hình đã cấu hình. Ánh xạ kênh áp dụng khi một phiên chưa có ghi đè mô hình (ví dụ: được đặt qua `/model`). +Dùng `channels.modelByChannel` để ghim ID kênh cụ thể vào một mô hình. Giá trị chấp nhận `provider/model` hoặc bí danh mô hình đã cấu hình. Ánh xạ kênh áp dụng khi một phiên chưa có ghi đè mô hình (ví dụ, được đặt qua `/model`). ```json5 { @@ -92,14 +92,14 @@ Dùng `channels.defaults` cho hành vi chính sách nhóm và Heartbeat dùng ch ``` - `channels.defaults.groupPolicy`: chính sách nhóm dự phòng khi `groupPolicy` cấp nhà cung cấp chưa được đặt. -- `channels.defaults.contextVisibility`: chế độ hiển thị ngữ cảnh bổ sung mặc định cho tất cả kênh. Giá trị: `all` (mặc định, bao gồm toàn bộ ngữ cảnh trích dẫn/luồng/lịch sử), `allowlist` (chỉ bao gồm ngữ cảnh từ người gửi trong danh sách cho phép), `allowlist_quote` (giống allowlist nhưng giữ ngữ cảnh trích dẫn/trả lời rõ ràng). Ghi đè theo kênh: `channels..contextVisibility`. +- `channels.defaults.contextVisibility`: chế độ hiển thị ngữ cảnh bổ sung mặc định cho tất cả các kênh. Giá trị: `all` (mặc định, bao gồm toàn bộ ngữ cảnh trích dẫn/luồng/lịch sử), `allowlist` (chỉ bao gồm ngữ cảnh từ người gửi trong danh sách cho phép), `allowlist_quote` (giống allowlist nhưng giữ ngữ cảnh trích dẫn/trả lời rõ ràng). Ghi đè theo kênh: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: bao gồm trạng thái kênh khỏe mạnh trong đầu ra Heartbeat. - `channels.defaults.heartbeat.showAlerts`: bao gồm trạng thái suy giảm/lỗi trong đầu ra Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: hiển thị đầu ra Heartbeat kiểu chỉ báo nhỏ gọn. +- `channels.defaults.heartbeat.useIndicator`: hiển thị đầu ra Heartbeat dạng chỉ báo gọn. ### WhatsApp -WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự động khởi động khi có một phiên đã liên kết. +WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự động khởi động khi có phiên đã liên kết. ```json5 { @@ -137,7 +137,7 @@ WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự độ } ``` - + ```json5 { @@ -155,9 +155,9 @@ WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự độ } ``` -- Các lệnh gửi đi mặc định dùng tài khoản `default` nếu có; nếu không thì dùng id tài khoản được cấu hình đầu tiên (đã sắp xếp). -- `channels.whatsapp.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định dự phòng đó khi khớp với một id tài khoản đã cấu hình. -- Thư mục xác thực Baileys một tài khoản cũ được `openclaw doctor` di chuyển vào `whatsapp/default`. +- Lệnh gửi ra mặc định dùng tài khoản `default` nếu có; nếu không thì dùng ID tài khoản được cấu hình đầu tiên (đã sắp xếp). +- `channels.whatsapp.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định dự phòng đó khi khớp với một ID tài khoản đã cấu hình. +- Thư mục xác thực Baileys một tài khoản kiểu cũ được `openclaw doctor` di chuyển vào `whatsapp/default`. - Ghi đè theo tài khoản: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -217,13 +217,13 @@ WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự độ } ``` -- Token bot: `channels.telegram.botToken` hoặc `channels.telegram.tokenFile` (chỉ tệp thông thường; symlink bị từ chối), với `TELEGRAM_BOT_TOKEN` làm phương án dự phòng cho tài khoản mặc định. -- `apiRoot` chỉ là gốc Telegram Bot API. Dùng `https://api.telegram.org` hoặc gốc tự lưu trữ/proxy của bạn, không dùng `https://api.telegram.org/bot`; `openclaw doctor --fix` xóa hậu tố `/bot` vô tình ở cuối. -- `channels.telegram.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. -- Trong thiết lập nhiều tài khoản (2+ id tài khoản), hãy đặt mặc định rõ ràng (`channels.telegram.defaultAccount` hoặc `channels.telegram.accounts.default`) để tránh định tuyến dự phòng; `openclaw doctor` cảnh báo khi mục này bị thiếu hoặc không hợp lệ. +- Token bot: `channels.telegram.botToken` hoặc `channels.telegram.tokenFile` (chỉ tệp thông thường; symlink bị từ chối), với `TELEGRAM_BOT_TOKEN` làm dự phòng cho tài khoản mặc định. +- `apiRoot` chỉ là gốc Telegram Bot API. Dùng `https://api.telegram.org` hoặc gốc tự lưu trữ/proxy của bạn, không dùng `https://api.telegram.org/bot`; `openclaw doctor --fix` loại bỏ hậu tố `/bot` vô tình ở cuối. +- `channels.telegram.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một ID tài khoản đã cấu hình. +- Trong thiết lập nhiều tài khoản (từ 2 ID tài khoản trở lên), đặt mặc định rõ ràng (`channels.telegram.defaultAccount` hoặc `channels.telegram.accounts.default`) để tránh định tuyến dự phòng; `openclaw doctor` cảnh báo khi mục này thiếu hoặc không hợp lệ. - `configWrites: false` chặn các thao tác ghi cấu hình do Telegram khởi tạo (di chuyển ID siêu nhóm, `/config set|unset`). -- Các mục `bindings[]` cấp cao nhất với `type: "acp"` cấu hình các liên kết ACP bền vững cho chủ đề diễn đàn (dùng `chatId:topic:topicId` chuẩn trong `match.peer.id`). Ngữ nghĩa trường được chia sẻ trong [Agent ACP](/vi/tools/acp-agents#persistent-channel-bindings). -- Bản xem trước luồng Telegram dùng `sendMessage` + `editMessageText` (hoạt động trong trò chuyện trực tiếp và nhóm). +- Các mục `bindings[]` cấp cao nhất với `type: "acp"` cấu hình liên kết ACP cố định cho chủ đề diễn đàn (dùng `chatId:topic:topicId` chuẩn trong `match.peer.id`). Ngữ nghĩa trường được dùng chung trong [Agent ACP](/vi/tools/acp-agents#persistent-channel-bindings). +- Bản xem trước luồng Telegram dùng `sendMessage` + `editMessageText` (hoạt động trong trò chuyện trực tiếp và trò chuyện nhóm). - Chính sách thử lại: xem [Chính sách thử lại](/vi/concepts/retry). ### Discord @@ -329,41 +329,41 @@ WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự độ } ``` -- Token: `channels.discord.token`, với `DISCORD_BOT_TOKEN` làm phương án dự phòng cho tài khoản mặc định. -- Các lệnh gọi đi trực tiếp cung cấp Discord `token` rõ ràng sẽ dùng token đó cho lệnh gọi; thiết lập thử lại/chính sách của tài khoản vẫn lấy từ tài khoản đã chọn trong snapshot runtime đang hoạt động. -- `channels.discord.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với id tài khoản đã cấu hình. -- Dùng `user:` (DM) hoặc `channel:` (kênh guild) cho mục tiêu gửi; ID dạng số trần bị từ chối. -- Slug guild dùng chữ thường và thay khoảng trắng bằng `-`; khóa kênh dùng tên đã tạo slug (không có `#`). Ưu tiên ID guild. -- Tin nhắn do bot viết bị bỏ qua theo mặc định. `allowBots: true` bật chúng; dùng `allowBots: "mentions"` để chỉ chấp nhận tin nhắn bot có nhắc đến bot (tin nhắn của chính nó vẫn bị lọc). -- `channels.discord.guilds..ignoreOtherMentions` (và các ghi đè kênh) loại bỏ tin nhắn nhắc đến người dùng hoặc vai trò khác nhưng không nhắc đến bot (trừ @everyone/@here). +- Token: `channels.discord.token`, với `DISCORD_BOT_TOKEN` làm dự phòng cho tài khoản mặc định. +- Các lệnh gọi trực tiếp ra ngoài cung cấp Discord `token` tường minh sẽ dùng token đó cho lệnh gọi; các cài đặt thử lại/chính sách của tài khoản vẫn đến từ tài khoản đã chọn trong snapshot runtime đang hoạt động. +- `channels.discord.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. +- Dùng `user:` (DM) hoặc `channel:` (kênh guild) cho mục tiêu gửi; ID số trần sẽ bị từ chối. +- Slug guild là chữ thường với khoảng trắng được thay bằng `-`; khóa kênh dùng tên đã tạo slug (không có `#`). Ưu tiên dùng ID guild. +- Tin nhắn do bot tạo mặc định bị bỏ qua. `allowBots: true` bật chúng; dùng `allowBots: "mentions"` để chỉ chấp nhận tin nhắn bot có nhắc đến bot (tin nhắn của chính bot vẫn bị lọc). +- `channels.discord.guilds..ignoreOtherMentions` (và ghi đè kênh) loại bỏ tin nhắn nhắc đến người dùng hoặc vai trò khác nhưng không nhắc đến bot (loại trừ @everyone/@here). - `channels.discord.mentionAliases` ánh xạ văn bản `@handle` gửi đi ổn định sang ID người dùng Discord trước khi gửi, để các đồng đội đã biết có thể được nhắc đến một cách xác định ngay cả khi bộ nhớ đệm thư mục tạm thời trống. Ghi đè theo tài khoản nằm dưới `channels.discord.accounts..mentionAliases`. - `maxLinesPerMessage` (mặc định 17) chia các tin nhắn cao ngay cả khi dưới 2000 ký tự. -- `channels.discord.threadBindings` kiểm soát định tuyến gắn với luồng Discord: - - `enabled`: ghi đè Discord cho các tính năng phiên gắn với luồng (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, và gửi/định tuyến đã gắn) - - `idleHours`: ghi đè Discord cho tự động bỏ tập trung khi không hoạt động, tính bằng giờ (`0` vô hiệu hóa) - - `maxAgeHours`: ghi đè Discord cho tuổi tối đa cứng, tính bằng giờ (`0` vô hiệu hóa) - - `spawnSessions`: công tắc cho `sessions_spawn({ thread: true })` và tự động tạo/gắn luồng khi ACP sinh luồng (mặc định: `true`) - - `defaultSpawnContext`: ngữ cảnh subagent gốc cho các lần sinh gắn với luồng (`"fork"` theo mặc định) -- Các mục `bindings[]` cấp cao nhất với `type: "acp"` cấu hình liên kết ACP bền vững cho kênh và luồng (dùng id kênh/luồng trong `match.peer.id`). Ngữ nghĩa trường được dùng chung trong [Tác nhân ACP](/vi/tools/acp-agents#persistent-channel-bindings). +- `channels.discord.threadBindings` kiểm soát định tuyến ràng buộc theo luồng Discord: + - `enabled`: ghi đè Discord cho các tính năng phiên ràng buộc theo luồng (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, và gửi/định tuyến có ràng buộc) + - `idleHours`: ghi đè Discord cho tự động bỏ focus do không hoạt động, tính bằng giờ (`0` tắt) + - `maxAgeHours`: ghi đè Discord cho tuổi tối đa cứng, tính bằng giờ (`0` tắt) + - `spawnSessions`: công tắc cho `sessions_spawn({ thread: true })` và việc tự động tạo/ràng buộc luồng ACP khi sinh luồng (`true` theo mặc định) + - `defaultSpawnContext`: ngữ cảnh subagent gốc cho các lần sinh ràng buộc theo luồng (`"fork"` theo mặc định) +- Các mục `bindings[]` cấp cao nhất với `type: "acp"` cấu hình ràng buộc ACP bền vững cho kênh và luồng (dùng id kênh/luồng trong `match.peer.id`). Ngữ nghĩa trường được chia sẻ trong [Tác nhân ACP](/vi/tools/acp-agents#persistent-channel-bindings). - `channels.discord.ui.components.accentColor` đặt màu nhấn cho container thành phần Discord v2. -- `channels.discord.voice` bật hội thoại kênh thoại Discord và các ghi đè tùy chọn về tự động tham gia + LLM + TTS. Cấu hình Discord chỉ văn bản mặc định tắt thoại; đặt `channels.discord.voice.enabled=true` để chọn tham gia. +- `channels.discord.voice` bật cuộc hội thoại kênh thoại Discord và các ghi đè tự động tham gia + LLM + TTS tùy chọn. Cấu hình Discord chỉ văn bản mặc định tắt thoại; đặt `channels.discord.voice.enabled=true` để bật. - `channels.discord.voice.model` tùy chọn ghi đè mô hình LLM dùng cho phản hồi kênh thoại Discord. -- `channels.discord.voice.daveEncryption` và `channels.discord.voice.decryptionFailureTolerance` truyền thẳng đến tùy chọn DAVE của `@discordjs/voice` (`true` và `24` theo mặc định). +- `channels.discord.voice.daveEncryption` và `channels.discord.voice.decryptionFailureTolerance` được truyền qua các tùy chọn DAVE của `@discordjs/voice` (`true` và `24` theo mặc định). - `channels.discord.voice.connectTimeoutMs` kiểm soát thời gian chờ Ready ban đầu của `@discordjs/voice` cho `/vc join` và các lần tự động tham gia (`30000` theo mặc định). -- `channels.discord.voice.reconnectGraceMs` kiểm soát thời gian một phiên thoại đã ngắt kết nối có thể dùng để bước vào tín hiệu kết nối lại trước khi OpenClaw hủy phiên đó (`15000` theo mặc định). -- OpenClaw cũng thử khôi phục nhận thoại bằng cách rời/tham gia lại phiên thoại sau nhiều lần giải mã thất bại. -- `channels.discord.streaming` là khóa chế độ stream chuẩn. Các giá trị cũ `streamMode` và boolean `streaming` được tự động di chuyển. -- `channels.discord.autoPresence` ánh xạ trạng thái sẵn sàng của runtime sang trạng thái hiện diện của bot (healthy => online, degraded => idle, exhausted => dnd) và cho phép ghi đè văn bản trạng thái tùy chọn. +- `channels.discord.voice.reconnectGraceMs` kiểm soát thời lượng một phiên thoại bị ngắt kết nối có thể dùng để vào tín hiệu kết nối lại trước khi OpenClaw hủy phiên đó (`15000` theo mặc định). +- OpenClaw cũng thử khôi phục nhận thoại bằng cách rời/tham gia lại một phiên thoại sau nhiều lỗi giải mã lặp lại. +- `channels.discord.streaming` là khóa chế độ stream chuẩn. Các giá trị cũ `streamMode` và boolean `streaming` được tự động di trú. +- `channels.discord.autoPresence` ánh xạ tính khả dụng runtime sang trạng thái hiện diện của bot (healthy => online, degraded => idle, exhausted => dnd) và cho phép ghi đè văn bản trạng thái tùy chọn. - `channels.discord.dangerouslyAllowNameMatching` bật lại so khớp tên/thẻ có thể thay đổi (chế độ tương thích phá kính). - `channels.discord.execApprovals`: gửi phê duyệt exec gốc Discord và ủy quyền người phê duyệt. - - `enabled`: `true`, `false`, hoặc `"auto"` (mặc định). Ở chế độ tự động, phê duyệt exec được kích hoạt khi có thể phân giải người phê duyệt từ `approvers` hoặc `commands.ownerAllowFrom`. + - `enabled`: `true`, `false`, hoặc `"auto"` (mặc định). Ở chế độ tự động, phê duyệt exec kích hoạt khi có thể phân giải người phê duyệt từ `approvers` hoặc `commands.ownerAllowFrom`. - `approvers`: ID người dùng Discord được phép phê duyệt yêu cầu exec. Dự phòng về `commands.ownerAllowFrom` khi bị bỏ qua. - - `agentFilter`: danh sách cho phép ID tác nhân tùy chọn. Bỏ qua để chuyển tiếp phê duyệt cho mọi tác nhân. - - `sessionFilter`: mẫu khóa phiên tùy chọn (chuỗi con hoặc regex). - - `target`: nơi gửi lời nhắc phê duyệt. `"dm"` (mặc định) gửi đến DM của người phê duyệt, `"channel"` gửi đến kênh khởi tạo, `"both"` gửi đến cả hai. Khi target bao gồm `"channel"`, chỉ những người phê duyệt đã phân giải mới dùng được nút. + - `agentFilter`: danh sách cho phép ID tác nhân tùy chọn. Bỏ qua để chuyển tiếp phê duyệt cho tất cả tác nhân. + - `sessionFilter`: các mẫu khóa phiên tùy chọn (chuỗi con hoặc regex). + - `target`: nơi gửi lời nhắc phê duyệt. `"dm"` (mặc định) gửi đến DM của người phê duyệt, `"channel"` gửi đến kênh nguồn, `"both"` gửi đến cả hai. Khi mục tiêu bao gồm `"channel"`, nút chỉ dùng được bởi người phê duyệt đã phân giải. - `cleanupAfterResolve`: khi `true`, xóa DM phê duyệt sau khi phê duyệt, từ chối hoặc hết thời gian chờ. -**Chế độ thông báo phản ứng:** `off` (không có), `own` (tin nhắn của bot, mặc định), `all` (mọi tin nhắn), `allowlist` (từ `guilds..users` trên mọi tin nhắn). +**Chế độ thông báo phản ứng:** `off` (không có), `own` (tin nhắn của bot, mặc định), `all` (tất cả tin nhắn), `allowlist` (từ `guilds..users` trên tất cả tin nhắn). ### Google Chat @@ -396,7 +396,7 @@ WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự độ - JSON tài khoản dịch vụ: nội tuyến (`serviceAccount`) hoặc dựa trên tệp (`serviceAccountFile`). - SecretRef tài khoản dịch vụ cũng được hỗ trợ (`serviceAccountRef`). -- Phương án dự phòng env: `GOOGLE_CHAT_SERVICE_ACCOUNT` hoặc `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Dự phòng env: `GOOGLE_CHAT_SERVICE_ACCOUNT` hoặc `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Dùng `spaces/` hoặc `users/` cho mục tiêu gửi. - `channels.googlechat.dangerouslyAllowNameMatching` bật lại so khớp principal email có thể thay đổi (chế độ tương thích phá kính). @@ -470,41 +470,41 @@ WhatsApp chạy qua kênh web của Gateway (Baileys Web). Kênh này tự độ } ``` -- **Chế độ socket** yêu cầu cả `botToken` và `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` cho phương án dự phòng env của tài khoản mặc định). -- **Chế độ HTTP** yêu cầu `botToken` cộng với `signingSecret` (ở gốc hoặc theo tài khoản). -- `socketMode` truyền tinh chỉnh vận chuyển Socket Mode của Slack SDK đến API receiver Bolt công khai. Chỉ dùng nó khi điều tra thời gian chờ ping/pong hoặc hành vi websocket cũ. +- **Chế độ socket** yêu cầu cả `botToken` và `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` cho dự phòng env tài khoản mặc định). +- **Chế độ HTTP** yêu cầu `botToken` cùng với `signingSecret` (ở gốc hoặc theo tài khoản). +- `socketMode` truyền tinh chỉnh truyền tải Slack SDK Socket Mode qua API Bolt receiver công khai. Chỉ dùng khi điều tra thời gian chờ ping/pong hoặc hành vi websocket cũ. - `botToken`, `appToken`, `signingSecret`, và `userToken` chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef. -- Snapshot tài khoản Slack hiển thị các trường nguồn/trạng thái theo từng thông tin xác thực, chẳng hạn như - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, và, trong chế độ HTTP, +- Snapshot tài khoản Slack hiển thị các trường nguồn/trạng thái theo thông tin xác thực như + `botTokenSource`, `botTokenStatus`, `appTokenStatus`, và, ở chế độ HTTP, `signingSecretStatus`. `configured_unavailable` nghĩa là tài khoản được - cấu hình thông qua SecretRef nhưng đường dẫn lệnh/runtime hiện tại không thể + cấu hình qua SecretRef nhưng đường dẫn lệnh/runtime hiện tại không thể phân giải giá trị bí mật. -- `configWrites: false` chặn các thao tác ghi cấu hình do Slack khởi tạo. -- `channels.slack.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với id tài khoản đã cấu hình. -- `channels.slack.streaming.mode` là khóa chế độ stream Slack chuẩn. `channels.slack.streaming.nativeTransport` kiểm soát vận chuyển stream gốc của Slack. Các giá trị cũ `streamMode`, boolean `streaming`, và `nativeStreaming` được tự động di chuyển. +- `configWrites: false` chặn các lần ghi cấu hình khởi tạo từ Slack. +- `channels.slack.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. +- `channels.slack.streaming.mode` là khóa chế độ stream Slack chuẩn. `channels.slack.streaming.nativeTransport` kiểm soát truyền tải stream gốc của Slack. Các giá trị cũ `streamMode`, boolean `streaming`, và `nativeStreaming` được tự động di trú. - Dùng `user:` (DM) hoặc `channel:` cho mục tiêu gửi. **Chế độ thông báo phản ứng:** `off`, `own` (mặc định), `all`, `allowlist` (từ `reactionAllowlist`). -**Cô lập phiên luồng:** `thread.historyScope` là theo luồng (mặc định) hoặc dùng chung trên kênh. `thread.inheritParent` sao chép transcript kênh cha sang luồng mới. +**Cô lập phiên luồng:** `thread.historyScope` là theo luồng (mặc định) hoặc dùng chung trên kênh. `thread.inheritParent` sao chép transcript kênh cha sang các luồng mới. -- Stream gốc Slack cùng trạng thái luồng "is typing..." kiểu trợ lý Slack yêu cầu mục tiêu luồng trả lời. DM cấp cao nhất mặc định vẫn không nằm trong luồng, nên chúng vẫn có thể stream qua bản xem trước bài nháp đăng-và-sửa của Slack thay vì hiển thị bản xem trước stream/trạng thái gốc kiểu luồng. -- `typingReaction` thêm phản ứng tạm thời vào tin nhắn Slack đầu vào trong khi phản hồi đang chạy, rồi xóa khi hoàn tất. Dùng shortcode emoji Slack như `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: gửi phê duyệt exec gốc Slack và ủy quyền người phê duyệt. Cùng schema như Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID người dùng Slack), `agentFilter`, `sessionFilter`, và `target` (`"dm"`, `"channel"`, hoặc `"both"`). +- Stream gốc Slack cùng với trạng thái luồng kiểu trợ lý Slack "is typing..." yêu cầu mục tiêu luồng trả lời. DM cấp cao nhất mặc định vẫn nằm ngoài luồng, nên chúng vẫn có thể stream qua bản xem trước đăng nháp-và-chỉnh sửa của Slack thay vì hiển thị bản xem trước stream/trạng thái gốc kiểu luồng. +- `typingReaction` thêm một phản ứng tạm thời vào tin nhắn Slack đến trong khi phản hồi đang chạy, rồi xóa khi hoàn tất. Dùng shortcode emoji Slack như `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: gửi phê duyệt exec gốc Slack và ủy quyền người phê duyệt. Cùng schema với Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID người dùng Slack), `agentFilter`, `sessionFilter`, và `target` (`"dm"`, `"channel"`, hoặc `"both"`). -| Nhóm hành động | Mặc định | Ghi chú | -| -------------- | -------- | -------------------------- | -| reactions | bật | Phản ứng + liệt kê phản ứng | -| messages | bật | Đọc/gửi/sửa/xóa | -| pins | bật | Ghim/bỏ ghim/liệt kê | -| memberInfo | bật | Thông tin thành viên | -| emojiList | bật | Danh sách emoji tùy chỉnh | +| Nhóm hành động | Mặc định | Ghi chú | +| ------------ | ------- | ---------------------- | +| reactions | bật | Phản ứng + liệt kê phản ứng | +| messages | bật | Đọc/gửi/chỉnh sửa/xóa | +| pins | bật | Ghim/bỏ ghim/liệt kê | +| memberInfo | bật | Thông tin thành viên | +| emojiList | bật | Danh sách emoji tùy chỉnh | ### Mattermost -Mattermost được phát hành như một Plugin đi kèm trong các bản phát hành OpenClaw hiện tại. Các bản build cũ hơn hoặc -tùy chỉnh có thể cài đặt gói npm hiện tại bằng +Mattermost được phát hành dưới dạng Plugin tích hợp trong các bản phát hành OpenClaw hiện tại. Các bản dựng cũ hơn hoặc +tùy chỉnh có thể cài một gói npm hiện tại bằng `openclaw plugins install @openclaw/mattermost`. Kiểm tra [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) để biết các dist-tag hiện tại trước khi ghim phiên bản. @@ -537,18 +537,18 @@ tùy chỉnh có thể cài đặt gói npm hiện tại bằng } ``` -Chế độ trò chuyện: `oncall` (phản hồi khi được @-nhắc đến, mặc định), `onmessage` (mọi tin nhắn), `onchar` (tin nhắn bắt đầu bằng tiền tố kích hoạt). +Chế độ chat: `oncall` (phản hồi khi được @-mention, mặc định), `onmessage` (mọi tin nhắn), `onchar` (tin nhắn bắt đầu bằng tiền tố kích hoạt). Khi lệnh gốc Mattermost được bật: - `commands.callbackPath` phải là một đường dẫn (ví dụ `/api/channels/mattermost/command`), không phải URL đầy đủ. -- `commands.callbackUrl` phải phân giải tới điểm cuối Gateway của OpenClaw và có thể truy cập được từ máy chủ Mattermost. -- Callback slash gốc được xác thực bằng mã thông báo theo từng lệnh do Mattermost trả về trong quá trình đăng ký slash command. Nếu đăng ký thất bại hoặc không có lệnh nào được kích hoạt, OpenClaw sẽ từ chối callback với `Unauthorized: invalid command token.` +- `commands.callbackUrl` phải phân giải đến endpoint Gateway của OpenClaw và có thể truy cập được từ máy chủ Mattermost. +- Các callback slash gốc được xác thực bằng token theo từng lệnh do Mattermost trả về trong quá trình đăng ký slash command. Nếu đăng ký thất bại hoặc không có lệnh nào được kích hoạt, OpenClaw sẽ từ chối callback với `Unauthorized: invalid command token.` - Với các máy chủ callback riêng tư/tailnet/nội bộ, Mattermost có thể yêu cầu `ServiceSettings.AllowedUntrustedInternalConnections` bao gồm máy chủ/miền callback. Dùng giá trị máy chủ/miền, không dùng URL đầy đủ. -- `channels.mattermost.configWrites`: cho phép hoặc từ chối các lần ghi cấu hình do Mattermost khởi tạo. +- `channels.mattermost.configWrites`: cho phép hoặc từ chối các thao tác ghi cấu hình do Mattermost khởi tạo. - `channels.mattermost.requireMention`: yêu cầu `@mention` trước khi trả lời trong kênh. -- `channels.mattermost.groups..requireMention`: ghi đè cổng đề cập theo từng kênh (`"*"` cho mặc định). -- `channels.mattermost.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. +- `channels.mattermost.groups..requireMention`: ghi đè kiểm soát theo lượt nhắc trên từng kênh (`"*"` cho mặc định). +- `channels.mattermost.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một ID tài khoản đã cấu hình. ### Signal @@ -572,12 +572,12 @@ Khi lệnh gốc Mattermost được bật: **Chế độ thông báo phản ứng:** `off`, `own` (mặc định), `all`, `allowlist` (từ `reactionAllowlist`). - `channels.signal.account`: ghim quá trình khởi động kênh vào một danh tính tài khoản Signal cụ thể. -- `channels.signal.configWrites`: cho phép hoặc từ chối các lần ghi cấu hình do Signal khởi tạo. -- `channels.signal.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. +- `channels.signal.configWrites`: cho phép hoặc từ chối các thao tác ghi cấu hình do Signal khởi tạo. +- `channels.signal.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một ID tài khoản đã cấu hình. ### BlueBubbles -BlueBubbles là đường dẫn iMessage được khuyến nghị (do Plugin hỗ trợ, được cấu hình trong `channels.bluebubbles`). +BlueBubbles là đường dẫn iMessage được khuyến nghị (được hỗ trợ bởi Plugin, cấu hình trong `channels.bluebubbles`). ```json5 { @@ -592,10 +592,10 @@ BlueBubbles là đường dẫn iMessage được khuyến nghị (do Plugin h } ``` -- Các đường dẫn khóa cốt lõi được đề cập ở đây: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. -- Các mục `bindings[]` cấp cao nhất với `type: "acp"` có thể liên kết các cuộc trò chuyện BlueBubbles với các phiên ACP bền vững. Dùng một handle BlueBubbles hoặc chuỗi đích (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) trong `match.peer.id`. Ngữ nghĩa trường dùng chung: [ACP Agents](/vi/tools/acp-agents#persistent-channel-bindings). -- Cấu hình kênh BlueBubbles đầy đủ được ghi trong [BlueBubbles](/vi/channels/bluebubbles). +- Các đường dẫn khóa lõi được đề cập ở đây: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một ID tài khoản đã cấu hình. +- Các mục `bindings[]` cấp cao nhất với `type: "acp"` có thể liên kết cuộc trò chuyện BlueBubbles với các phiên ACP bền vững. Dùng handle BlueBubbles hoặc chuỗi mục tiêu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) trong `match.peer.id`. Ngữ nghĩa trường dùng chung: [Tác tử ACP](/vi/tools/acp-agents#persistent-channel-bindings). +- Cấu hình kênh BlueBubbles đầy đủ được ghi lại trong [BlueBubbles](/vi/channels/bluebubbles). ### iMessage @@ -623,17 +623,17 @@ OpenClaw sinh `imsg rpc` (JSON-RPC qua stdio). Không cần daemon hoặc cổng } ``` -- `channels.imessage.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. +- `channels.imessage.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một ID tài khoản đã cấu hình. -- Yêu cầu Full Disk Access tới Messages DB. -- Ưu tiên các đích `chat_id:`. Dùng `imsg chats --limit 20` để liệt kê các cuộc trò chuyện. -- `cliPath` có thể trỏ tới một SSH wrapper; đặt `remoteHost` (`host` hoặc `user@host`) để lấy tệp đính kèm bằng SCP. -- `attachmentRoots` và `remoteAttachmentRoots` giới hạn đường dẫn tệp đính kèm đến (mặc định: `/Users/*/Library/Messages/Attachments`). -- SCP dùng kiểm tra khóa máy chủ nghiêm ngặt, vì vậy hãy đảm bảo khóa máy chủ chuyển tiếp đã tồn tại trong `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: cho phép hoặc từ chối các lần ghi cấu hình do iMessage khởi tạo. -- Các mục `bindings[]` cấp cao nhất với `type: "acp"` có thể liên kết các cuộc trò chuyện iMessage với các phiên ACP bền vững. Dùng một handle đã chuẩn hóa hoặc đích trò chuyện rõ ràng (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) trong `match.peer.id`. Ngữ nghĩa trường dùng chung: [ACP Agents](/vi/tools/acp-agents#persistent-channel-bindings). +- Yêu cầu Full Disk Access vào Messages DB. +- Ưu tiên mục tiêu `chat_id:`. Dùng `imsg chats --limit 20` để liệt kê các cuộc trò chuyện. +- `cliPath` có thể trỏ đến một wrapper SSH; đặt `remoteHost` (`host` hoặc `user@host`) để lấy tệp đính kèm qua SCP. +- `attachmentRoots` và `remoteAttachmentRoots` giới hạn đường dẫn tệp đính kèm đi vào (mặc định: `/Users/*/Library/Messages/Attachments`). +- SCP dùng kiểm tra host-key nghiêm ngặt, vì vậy hãy bảo đảm khóa máy chủ relay đã tồn tại trong `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: cho phép hoặc từ chối các thao tác ghi cấu hình do iMessage khởi tạo. +- Các mục `bindings[]` cấp cao nhất với `type: "acp"` có thể liên kết cuộc trò chuyện iMessage với các phiên ACP bền vững. Dùng handle đã chuẩn hóa hoặc mục tiêu trò chuyện rõ ràng (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) trong `match.peer.id`. Ngữ nghĩa trường dùng chung: [Tác tử ACP](/vi/tools/acp-agents#persistent-channel-bindings). - + ```bash #!/usr/bin/env bash @@ -644,7 +644,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix do Plugin hỗ trợ và được cấu hình trong `channels.matrix`. +Matrix được hỗ trợ bởi Plugin và cấu hình trong `channels.matrix`. ```json5 { @@ -674,25 +674,25 @@ Matrix do Plugin hỗ trợ và được cấu hình trong `channels.matrix`. } ``` -- Xác thực bằng mã thông báo dùng `accessToken`; xác thực bằng mật khẩu dùng `userId` + `password`. -- `channels.matrix.proxy` định tuyến lưu lượng HTTP của Matrix qua một proxy HTTP(S) rõ ràng. Tài khoản được đặt tên có thể ghi đè bằng `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` cho phép homeserver riêng tư/nội bộ. `proxy` và tùy chọn tham gia mạng này là các điều khiển độc lập. +- Xác thực bằng token dùng `accessToken`; xác thực bằng mật khẩu dùng `userId` + `password`. +- `channels.matrix.proxy` định tuyến lưu lượng HTTP của Matrix qua một proxy HTTP(S) rõ ràng. Các tài khoản có tên có thể ghi đè bằng `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` cho phép homeserver riêng tư/nội bộ. `proxy` và tùy chọn tham gia mạng này là các cơ chế kiểm soát độc lập. - `channels.matrix.defaultAccount` chọn tài khoản ưu tiên trong các thiết lập nhiều tài khoản. -- `channels.matrix.autoJoin` mặc định là `off`, nên các phòng được mời và lời mời kiểu DM mới sẽ bị bỏ qua cho đến khi bạn đặt `autoJoin: "allowlist"` với `autoJoinAllowlist` hoặc `autoJoin: "always"`. +- `channels.matrix.autoJoin` mặc định là `off`, vì vậy các phòng được mời và lời mời mới kiểu DM sẽ bị bỏ qua cho đến khi bạn đặt `autoJoin: "allowlist"` với `autoJoinAllowlist` hoặc `autoJoin: "always"`. - `channels.matrix.execApprovals`: phân phối phê duyệt exec gốc Matrix và ủy quyền người phê duyệt. - `enabled`: `true`, `false`, hoặc `"auto"` (mặc định). Ở chế độ tự động, phê duyệt exec kích hoạt khi có thể phân giải người phê duyệt từ `approvers` hoặc `commands.ownerAllowFrom`. - `approvers`: ID người dùng Matrix (ví dụ `@owner:example.org`) được phép phê duyệt yêu cầu exec. - - `agentFilter`: danh sách cho phép ID agent tùy chọn. Bỏ qua để chuyển tiếp phê duyệt cho tất cả agent. + - `agentFilter`: allowlist ID tác tử tùy chọn. Bỏ qua để chuyển tiếp phê duyệt cho tất cả tác tử. - `sessionFilter`: mẫu khóa phiên tùy chọn (chuỗi con hoặc regex). - - `target`: nơi gửi lời nhắc phê duyệt. `"dm"` (mặc định), `"channel"` (phòng gốc), hoặc `"both"`. - - Ghi đè theo từng tài khoản: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` kiểm soát cách DM Matrix nhóm vào phiên: `per-user` (mặc định) chia sẻ theo peer được định tuyến, còn `per-room` cô lập từng phòng DM. -- Các phép thăm dò trạng thái Matrix và tra cứu thư mục trực tiếp dùng cùng chính sách proxy như lưu lượng runtime. -- Cấu hình Matrix đầy đủ, quy tắc nhắm mục tiêu và ví dụ thiết lập được ghi trong [Matrix](/vi/channels/matrix). + - `target`: nơi gửi lời nhắc phê duyệt. `"dm"` (mặc định), `"channel"` (phòng khởi nguồn), hoặc `"both"`. + - Ghi đè theo tài khoản: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` kiểm soát cách DM của Matrix được nhóm vào phiên: `per-user` (mặc định) chia sẻ theo peer được định tuyến, còn `per-room` cô lập từng phòng DM. +- Các phép thăm dò trạng thái Matrix và tra cứu thư mục trực tiếp dùng cùng chính sách proxy như lưu lượng khi chạy. +- Cấu hình Matrix đầy đủ, quy tắc nhắm mục tiêu và ví dụ thiết lập được ghi lại trong [Matrix](/vi/channels/matrix). ### Microsoft Teams -Microsoft Teams do Plugin hỗ trợ và được cấu hình trong `channels.msteams`. +Microsoft Teams được hỗ trợ bởi Plugin và cấu hình trong `channels.msteams`. ```json5 { @@ -707,12 +707,12 @@ Microsoft Teams do Plugin hỗ trợ và được cấu hình trong `channels.ms } ``` -- Các đường dẫn khóa cốt lõi được đề cập ở đây: `channels.msteams`, `channels.msteams.configWrites`. -- Cấu hình Teams đầy đủ (thông tin xác thực, Webhook, chính sách DM/nhóm, ghi đè theo từng team/từng kênh) được ghi trong [Microsoft Teams](/vi/channels/msteams). +- Các đường dẫn khóa lõi được đề cập ở đây: `channels.msteams`, `channels.msteams.configWrites`. +- Cấu hình Teams đầy đủ (thông tin xác thực, Webhook, chính sách DM/nhóm, ghi đè theo team/theo kênh) được ghi lại trong [Microsoft Teams](/vi/channels/msteams). ### IRC -IRC do Plugin hỗ trợ và được cấu hình trong `channels.irc`. +IRC được hỗ trợ bởi Plugin và cấu hình trong `channels.irc`. ```json5 { @@ -733,11 +733,11 @@ IRC do Plugin hỗ trợ và được cấu hình trong `channels.irc`. } ``` -- Các đường dẫn khóa cốt lõi được đề cập ở đây: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình. -- Cấu hình kênh IRC đầy đủ (host/cổng/TLS/kênh/danh sách cho phép/cổng đề cập) được ghi trong [IRC](/vi/channels/irc). +- Các đường dẫn khóa lõi được đề cập ở đây: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một ID tài khoản đã cấu hình. +- Cấu hình kênh IRC đầy đủ (máy chủ/cổng/TLS/kênh/allowlist/kiểm soát theo lượt nhắc) được ghi lại trong [IRC](/vi/channels/irc). -### Nhiều tài khoản (tất cả kênh) +### Đa tài khoản (tất cả kênh) Chạy nhiều tài khoản trên mỗi kênh (mỗi tài khoản có `accountId` riêng): @@ -760,34 +760,36 @@ Chạy nhiều tài khoản trên mỗi kênh (mỗi tài khoản có `accountId } ``` -- `default` được dùng khi bỏ qua `accountId` (CLI + định tuyến). -- Mã thông báo env chỉ áp dụng cho tài khoản **mặc định**. -- Thiết lập kênh cơ sở áp dụng cho tất cả tài khoản trừ khi được ghi đè theo từng tài khoản. -- Dùng `bindings[].match.accountId` để định tuyến mỗi tài khoản tới một agent khác nhau. -- Nếu bạn thêm một tài khoản không phải mặc định qua `openclaw channels add` (hoặc onboarding kênh) khi vẫn đang dùng cấu hình kênh cấp cao nhất một tài khoản, OpenClaw trước tiên sẽ nâng cấp các giá trị một tài khoản cấp cao nhất có phạm vi tài khoản vào bản đồ tài khoản kênh để tài khoản ban đầu tiếp tục hoạt động. Hầu hết kênh chuyển chúng vào `channels..accounts.default`; Matrix có thể giữ nguyên một đích được đặt tên/mặc định hiện có khớp thay vào đó. -- Các liên kết chỉ theo kênh hiện có (không có `accountId`) tiếp tục khớp với tài khoản mặc định; liên kết có phạm vi tài khoản vẫn là tùy chọn. -- `openclaw doctor --fix` cũng sửa các dạng trộn bằng cách di chuyển các giá trị một tài khoản cấp cao nhất có phạm vi tài khoản vào tài khoản đã nâng cấp được chọn cho kênh đó. Hầu hết kênh dùng `accounts.default`; Matrix có thể giữ nguyên một đích được đặt tên/mặc định hiện có khớp thay vào đó. +- `default` được dùng khi `accountId` bị bỏ qua (CLI + định tuyến). +- Token môi trường chỉ áp dụng cho tài khoản **mặc định**. +- Thiết lập kênh cơ sở áp dụng cho mọi tài khoản trừ khi được ghi đè theo tài khoản. +- Dùng `bindings[].match.accountId` để định tuyến từng tài khoản đến một tác tử khác. +- Nếu bạn thêm một tài khoản không mặc định bằng `openclaw channels add` (hoặc onboarding kênh) khi vẫn đang dùng cấu hình kênh cấp cao nhất một tài khoản, OpenClaw trước tiên sẽ nâng cấp các giá trị một tài khoản cấp cao nhất có phạm vi tài khoản vào bản đồ tài khoản của kênh để tài khoản gốc tiếp tục hoạt động. Hầu hết kênh sẽ chuyển chúng vào `channels..accounts.default`; Matrix có thể giữ lại một mục tiêu có tên/mặc định hiện có khớp thay vào đó. +- Các binding chỉ theo kênh hiện có (không có `accountId`) tiếp tục khớp tài khoản mặc định; binding có phạm vi tài khoản vẫn là tùy chọn. +- `openclaw doctor --fix` cũng sửa các hình dạng hỗn hợp bằng cách di chuyển các giá trị một tài khoản cấp cao nhất có phạm vi tài khoản vào tài khoản đã nâng cấp được chọn cho kênh đó. Hầu hết kênh dùng `accounts.default`; Matrix có thể giữ lại một mục tiêu có tên/mặc định hiện có khớp thay vào đó. ### Các kênh Plugin khác -Nhiều kênh Plugin được cấu hình dưới dạng `channels.` và được ghi trong các trang kênh chuyên dụng của chúng (ví dụ Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat và Twitch). +Nhiều kênh Plugin được cấu hình dưới dạng `channels.` và được ghi lại trong các trang kênh chuyên dụng của chúng (ví dụ Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat và Twitch). Xem chỉ mục kênh đầy đủ: [Kênh](/vi/channels). -### Cổng đề cập trong trò chuyện nhóm +### Kiểm soát theo lượt nhắc trong trò chuyện nhóm -Tin nhắn nhóm mặc định là **yêu cầu đề cập** (đề cập metadata hoặc mẫu regex an toàn). Áp dụng cho WhatsApp, Telegram, Discord, Google Chat và trò chuyện nhóm iMessage. +Tin nhắn nhóm mặc định là **yêu cầu nhắc đến** (nhắc đến qua siêu dữ liệu hoặc các mẫu regex an toàn). Áp dụng cho WhatsApp, Telegram, Discord, Google Chat và trò chuyện nhóm iMessage. -Trả lời hiển thị được kiểm soát riêng. Phòng nhóm/kênh mặc định là `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw vẫn xử lý lượt, nhưng trả lời cuối thông thường vẫn ở chế độ riêng tư và đầu ra phòng hiển thị yêu cầu `message(action=send)`. Chỉ đặt `"automatic"` khi bạn muốn hành vi cũ, trong đó trả lời thông thường được đăng lại vào phòng. Để áp dụng cùng hành vi trả lời hiển thị chỉ qua công cụ cho cả trò chuyện trực tiếp, đặt `messages.visibleReplies: "message_tool"`; harness Codex cũng dùng hành vi chỉ qua công cụ đó làm mặc định trò chuyện trực tiếp khi chưa đặt. +Phản hồi hiển thị được kiểm soát riêng. Phòng nhóm/kênh mặc định là `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw vẫn xử lý lượt, nhưng phản hồi cuối thông thường vẫn ở chế độ riêng tư và đầu ra phòng hiển thị yêu cầu `message(action=send)`. Chỉ đặt `"automatic"` khi bạn muốn hành vi cũ, trong đó phản hồi thông thường được đăng lại vào phòng. Để áp dụng cùng hành vi phản hồi hiển thị chỉ qua công cụ cho cả trò chuyện trực tiếp, đặt `messages.visibleReplies: "message_tool"`; harness Codex cũng dùng hành vi chỉ qua công cụ đó làm mặc định trò chuyện trực tiếp khi chưa đặt. -Nếu công cụ tin nhắn không khả dụng theo chính sách công cụ đang hoạt động, OpenClaw sẽ quay về trả lời hiển thị tự động thay vì âm thầm chặn phản hồi. `openclaw doctor` cảnh báo về điểm không khớp này. +Phản hồi hiển thị chỉ qua công cụ yêu cầu model/runtime gọi công cụ một cách đáng tin cậy. Nếu nhật ký phiên hiển thị văn bản assistant với `didSendViaMessagingTool: false`, model đã tạo câu trả lời cuối riêng tư thay vì gọi công cụ nhắn tin. Chuyển sang model gọi công cụ mạnh hơn cho kênh đó, hoặc đặt `messages.groupChat.visibleReplies: "automatic"` để khôi phục phản hồi cuối hiển thị kiểu cũ. + +Nếu công cụ nhắn tin không khả dụng theo chính sách công cụ đang hoạt động, OpenClaw sẽ quay về phản hồi hiển thị tự động thay vì âm thầm chặn phản hồi. `openclaw doctor` cảnh báo về sự không khớp này. Gateway tải nóng cấu hình `messages` sau khi tệp được lưu. Chỉ khởi động lại khi theo dõi tệp hoặc tải lại cấu hình bị tắt trong triển khai. -**Loại đề cập:** +**Kiểu nhắc đến:** -- **Đề cập metadata**: @-mention gốc của nền tảng. Bị bỏ qua trong chế độ tự trò chuyện WhatsApp. -- **Mẫu văn bản**: Mẫu regex an toàn trong `agents.list[].groupChat.mentionPatterns`. Mẫu không hợp lệ và lặp lồng nhau không an toàn sẽ bị bỏ qua. -- Cổng đề cập chỉ được thực thi khi có thể phát hiện (đề cập gốc hoặc ít nhất một mẫu). +- **Đề cập siêu dữ liệu**: @-mention nền tảng gốc. Bị bỏ qua trong chế độ tự trò chuyện WhatsApp. +- **Mẫu văn bản**: Các mẫu regex an toàn trong `agents.list[].groupChat.mentionPatterns`. Các mẫu không hợp lệ và phép lặp lồng nhau không an toàn sẽ bị bỏ qua. +- Cổng kiểm soát đề cập chỉ được thực thi khi có thể phát hiện (đề cập gốc hoặc ít nhất một mẫu). ```json5 { @@ -806,7 +808,7 @@ Gateway tải nóng cấu hình `messages` sau khi tệp được lưu. Chỉ kh `messages.groupChat.historyLimit` đặt giá trị mặc định toàn cục. Các kênh có thể ghi đè bằng `channels..historyLimit` (hoặc theo từng tài khoản). Đặt `0` để tắt. -`messages.visibleReplies` là giá trị mặc định toàn cục cho lượt nguồn; `messages.groupChat.visibleReplies` ghi đè giá trị đó cho các lượt nguồn nhóm/kênh. Khi `messages.visibleReplies` chưa được đặt, harness có thể cung cấp mặc định trực tiếp/nguồn riêng; harness Codex mặc định là `message_tool`. Danh sách cho phép của kênh và cổng kiểm soát lượt nhắc đến vẫn quyết định một lượt có được xử lý hay không. +`messages.visibleReplies` là mặc định toàn cục cho lượt nguồn; `messages.groupChat.visibleReplies` ghi đè giá trị đó cho các lượt nguồn trong nhóm/kênh. Khi `messages.visibleReplies` chưa được đặt, một harness có thể cung cấp mặc định trực tiếp/nguồn riêng; harness Codex mặc định là `message_tool`. Danh sách cho phép của kênh và cổng kiểm soát đề cập vẫn quyết định một lượt có được xử lý hay không. #### Giới hạn lịch sử DM @@ -829,7 +831,7 @@ Cách phân giải: ghi đè theo từng DM → mặc định của nhà cung c #### Chế độ tự trò chuyện -Thêm số của chính bạn vào `allowFrom` để bật chế độ tự trò chuyện (bỏ qua @-mentions gốc, chỉ phản hồi các mẫu văn bản): +Thêm số của bạn vào `allowFrom` để bật chế độ tự trò chuyện (bỏ qua @-mention gốc, chỉ phản hồi các mẫu văn bản): ```json5 { @@ -850,7 +852,7 @@ Thêm số của chính bạn vào `allowFrom` để bật chế độ tự trò } ``` -### Lệnh (xử lý lệnh trong trò chuyện) +### Lệnh (xử lý lệnh trò chuyện) ```json5 { @@ -877,34 +879,34 @@ Thêm số của chính bạn vào `allowFrom` để bật chế độ tự trò } ``` - + -- Khối này cấu hình các bề mặt lệnh. Để xem danh mục lệnh tích hợp hiện tại và lệnh đi kèm, xem [Lệnh gạch chéo](/vi/tools/slash-commands). -- Trang này là **tham chiếu khóa cấu hình**, không phải danh mục lệnh đầy đủ. Các lệnh do kênh/Plugin sở hữu như QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, ghép đôi thiết bị `/pair`, bộ nhớ `/dreaming`, điều khiển điện thoại `/phone`, và Talk `/voice` được ghi lại trong các trang kênh/Plugin tương ứng cùng với [Lệnh gạch chéo](/vi/tools/slash-commands). +- Khối này cấu hình các bề mặt lệnh. Để xem danh mục lệnh tích hợp sẵn + đi kèm hiện tại, xem [Lệnh slash](/vi/tools/slash-commands). +- Trang này là **tham chiếu khóa cấu hình**, không phải danh mục lệnh đầy đủ. Các lệnh do kênh/Plugin sở hữu như QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, ghép cặp thiết bị `/pair`, bộ nhớ `/dreaming`, điều khiển điện thoại `/phone`, và Talk `/voice` được ghi lại trong các trang kênh/Plugin tương ứng cùng với [Lệnh slash](/vi/tools/slash-commands). - Lệnh văn bản phải là tin nhắn **độc lập** bắt đầu bằng `/`. -- `native: "auto"` bật lệnh gốc cho Discord/Telegram, giữ Slack tắt. -- `nativeSkills: "auto"` bật lệnh Skills gốc cho Discord/Telegram, giữ Slack tắt. -- Ghi đè theo từng kênh: `channels.discord.commands.native` (bool hoặc `"auto"`). Với Discord, `false` bỏ qua việc đăng ký và dọn dẹp lệnh gốc khi khởi động. +- `native: "auto"` bật lệnh gốc cho Discord/Telegram, để Slack tắt. +- `nativeSkills: "auto"` bật lệnh Skills gốc cho Discord/Telegram, để Slack tắt. +- Ghi đè theo từng kênh: `channels.discord.commands.native` (bool hoặc `"auto"`). Với Discord, `false` bỏ qua đăng ký và dọn dẹp lệnh gốc khi khởi động. - Ghi đè đăng ký Skills gốc theo từng kênh bằng `channels..commands.nativeSkills`. - `channels.telegram.customCommands` thêm các mục menu bot Telegram bổ sung. - `bash: true` bật `! ` cho shell máy chủ. Yêu cầu `tools.elevated.enabled` và người gửi nằm trong `tools.elevated.allowFrom.`. -- `config: true` bật `/config` (đọc/ghi `openclaw.json`). Với các máy khách Gateway `chat.send`, các lần ghi `/config set|unset` bền vững cũng yêu cầu `operator.admin`; `/config show` chỉ đọc vẫn khả dụng cho các máy khách operator thông thường có phạm vi ghi. -- `mcp: true` bật `/mcp` cho cấu hình máy chủ MCP do OpenClaw quản lý trong `mcp.servers`. +- `config: true` bật `/config` (đọc/ghi `openclaw.json`). Với các client `chat.send` của Gateway, ghi `/config set|unset` bền vững cũng yêu cầu `operator.admin`; `/config show` chỉ đọc vẫn khả dụng cho các client operator phạm vi ghi thông thường. +- `mcp: true` bật `/mcp` cho cấu hình máy chủ MCP do OpenClaw quản lý dưới `mcp.servers`. - `plugins: true` bật `/plugins` cho khám phá, cài đặt và điều khiển bật/tắt Plugin. -- `channels..configWrites` kiểm soát các thay đổi cấu hình theo từng kênh (mặc định: true). -- Với các kênh nhiều tài khoản, `channels..accounts..configWrites` cũng kiểm soát các lần ghi nhắm tới tài khoản đó (ví dụ `/allowlist --config --account ` hoặc `/config set channels..accounts....`). +- `channels..configWrites` kiểm soát thay đổi cấu hình theo từng kênh (mặc định: true). +- Với các kênh nhiều tài khoản, `channels..accounts..configWrites` cũng kiểm soát các lần ghi nhắm vào tài khoản đó (ví dụ `/allowlist --config --account ` hoặc `/config set channels..accounts....`). - `restart: false` tắt `/restart` và các hành động công cụ khởi động lại Gateway. Mặc định: `true`. - `ownerAllowFrom` là danh sách cho phép chủ sở hữu rõ ràng cho các lệnh/công cụ chỉ dành cho chủ sở hữu. Nó tách biệt với `allowFrom`. -- `ownerDisplay: "hash"` băm id chủ sở hữu trong lời nhắc hệ thống. Đặt `ownerDisplaySecret` để kiểm soát việc băm. -- `allowFrom` áp dụng theo từng nhà cung cấp. Khi được đặt, nó là nguồn ủy quyền **duy nhất** (danh sách cho phép/ghép đôi của kênh và `useAccessGroups` bị bỏ qua). +- `ownerDisplay: "hash"` băm id chủ sở hữu trong prompt hệ thống. Đặt `ownerDisplaySecret` để kiểm soát việc băm. +- `allowFrom` áp dụng theo từng nhà cung cấp. Khi được đặt, nó là nguồn ủy quyền **duy nhất** (danh sách cho phép/ghép cặp của kênh và `useAccessGroups` bị bỏ qua). - `useAccessGroups: false` cho phép lệnh bỏ qua chính sách nhóm truy cập khi `allowFrom` chưa được đặt. - Bản đồ tài liệu lệnh: - - danh mục tích hợp và đi kèm: [Lệnh gạch chéo](/vi/tools/slash-commands) + - danh mục tích hợp sẵn + đi kèm: [Lệnh slash](/vi/tools/slash-commands) - bề mặt lệnh theo kênh: [Kênh](/vi/channels) - lệnh QQ Bot: [QQ Bot](/vi/channels/qqbot) - - lệnh ghép đôi: [Ghép đôi](/vi/channels/pairing) + - lệnh ghép cặp: [Ghép cặp](/vi/channels/pairing) - lệnh thẻ LINE: [LINE](/vi/channels/line) - - Dreaming của bộ nhớ: [Dreaming](/vi/concepts/dreaming) + - Dreaming bộ nhớ: [Dreaming](/vi/concepts/dreaming) @@ -912,6 +914,6 @@ Thêm số của chính bạn vào `allowFrom` để bật chế độ tự trò ## Liên quan -- [Tham chiếu cấu hình](/vi/gateway/configuration-reference) — các khóa cấp cao nhất +- [Tham chiếu cấu hình](/vi/gateway/configuration-reference) — khóa cấp cao nhất - [Cấu hình — agent](/vi/gateway/config-agents) - [Tổng quan về kênh](/vi/channels) diff --git a/docs/vi/gateway/configuration-examples.md b/docs/vi/gateway/configuration-examples.md index 85f6f4d31..7b9531de0 100644 --- a/docs/vi/gateway/configuration-examples.md +++ b/docs/vi/gateway/configuration-examples.md @@ -1,20 +1,20 @@ --- read_when: - Tìm hiểu cách cấu hình OpenClaw - - Tìm ví dụ cấu hình - - Thiết lập OpenClaw lần đầu -summary: Các ví dụ cấu hình đúng theo lược đồ cho các thiết lập OpenClaw phổ biến + - Đang tìm ví dụ cấu hình + - Thiết lập OpenClaw lần đầu tiên +summary: Các ví dụ cấu hình đúng theo lược đồ cho những thiết lập OpenClaw phổ biến title: Ví dụ cấu hình x-i18n: - generated_at: "2026-04-29T22:41:55Z" + generated_at: "2026-05-04T02:24:12Z" model: gpt-5.5 provider: openai - source_hash: 8bc1f8877bc635d6e3aafd911852d61e71fa08de9144751209542fd67c70f0ba + source_hash: 60c8c2d731f8dce93c4d14657041d72043bc36e3d71ab6cb13c02993ba90dbe3 source_path: gateway/configuration-examples.md workflow: 16 --- -Các ví dụ bên dưới được căn chỉnh theo schema cấu hình hiện tại. Để xem tài liệu tham chiếu đầy đủ và ghi chú theo từng trường, hãy xem [Cấu hình](/vi/gateway/configuration). +Các ví dụ dưới đây phù hợp với schema cấu hình hiện tại. Để xem tài liệu tham khảo đầy đủ và ghi chú cho từng trường, hãy xem [Cấu hình](/vi/gateway/configuration). ## Bắt đầu nhanh @@ -27,7 +27,7 @@ Các ví dụ bên dưới được căn chỉnh theo schema cấu hình hiện } ``` -Lưu vào `~/.openclaw/openclaw.json` và bạn có thể nhắn tin trực tiếp cho bot từ số đó. +Lưu vào `~/.openclaw/openclaw.json` và bạn có thể nhắn tin riêng cho bot từ số đó. ### Cấu hình khởi đầu được khuyến nghị @@ -256,6 +256,7 @@ Lưu vào `~/.openclaw/openclaw.json` và bạn có thể nhắn tin trực ti skills: ["github", "weather"], // inherited by agents that omit list[].skills thinkingDefault: "low", verboseDefault: "off", + toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", blockStreamingDefault: "off", @@ -470,9 +471,9 @@ Lưu vào `~/.openclaw/openclaw.json` và bạn có thể nhắn tin trực ti } ``` -## Các mẫu thường gặp +## Các mẫu phổ biến -### Nền tảng skill dùng chung với một ghi đè +### Đường cơ sở skill dùng chung với một ghi đè ```json5 { @@ -490,8 +491,8 @@ Lưu vào `~/.openclaw/openclaw.json` và bạn có thể nhắn tin trực ti ``` - `agents.defaults.skills` là đường cơ sở dùng chung. -- `agents.list[].skills` thay thế đường cơ sở đó cho một tác nhân. -- Dùng `skills: []` khi một tác nhân không nên thấy Skills nào. +- `agents.list[].skills` thay thế đường cơ sở đó cho một agent. +- Dùng `skills: []` khi một agent không nên thấy Skills nào. ### Thiết lập đa nền tảng @@ -514,11 +515,11 @@ Lưu vào `~/.openclaw/openclaw.json` và bạn có thể nhắn tin trực ti } ``` -### Tự động phê duyệt mạng nút tin cậy +### Tự động phê duyệt mạng Node đáng tin cậy -Giữ việc ghép đôi thiết bị ở chế độ thủ công trừ khi bạn kiểm soát đường đi mạng. Với một -phòng thí nghiệm chuyên dụng hoặc mạng con tailnet, bạn có thể chọn tự động phê duyệt -thiết bị nút lần đầu bằng CIDR hoặc IP chính xác: +Giữ việc ghép đôi thiết bị ở chế độ thủ công trừ khi bạn kiểm soát đường mạng. Với một +phòng thí nghiệm chuyên dụng hoặc subnet tailnet, bạn có thể chọn bật tự động phê duyệt +thiết bị Node lần đầu bằng CIDR hoặc IP chính xác: ```json5 { @@ -532,13 +533,13 @@ thiết bị nút lần đầu bằng CIDR hoặc IP chính xác: } ``` -Tùy chọn này vẫn tắt khi chưa đặt. Nó chỉ áp dụng cho ghép đôi `role: node` mới -không có phạm vi được yêu cầu. Máy khách toán tử/trình duyệt và các nâng cấp vai trò, -phạm vi, siêu dữ liệu hoặc khóa công khai vẫn cần phê duyệt thủ công. +Tính năng này vẫn tắt khi chưa được đặt. Nó chỉ áp dụng cho ghép đôi `role: node` mới +không có phạm vi được yêu cầu. Máy khách operator/trình duyệt và các lần nâng cấp vai trò, phạm vi, siêu dữ liệu hoặc +khóa công khai vẫn cần phê duyệt thủ công. ### Chế độ DM bảo mật (hộp thư đến dùng chung / DM nhiều người dùng) -Nếu nhiều hơn một người có thể DM bot của bạn (nhiều mục trong `allowFrom`, phê duyệt ghép đôi cho nhiều người, hoặc `dmPolicy: "open"`), hãy bật **chế độ DM bảo mật** để DM từ các người gửi khác nhau mặc định không dùng chung một ngữ cảnh: +Nếu nhiều hơn một người có thể DM bot của bạn (nhiều mục trong `allowFrom`, phê duyệt ghép đôi cho nhiều người, hoặc `dmPolicy: "open"`), hãy bật **chế độ DM bảo mật** để DM từ những người gửi khác nhau mặc định không dùng chung một ngữ cảnh: ```json5 { @@ -562,8 +563,8 @@ Nếu nhiều hơn một người có thể DM bot của bạn (nhiều mục tr } ``` -Với Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC, mặc định việc ủy quyền người gửi ưu tiên ID. -Chỉ bật so khớp tên/email/biệt danh có thể thay đổi trực tiếp bằng `dangerouslyAllowNameMatching: true` của từng kênh nếu bạn chấp nhận rõ ràng rủi ro đó. +Với Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC, việc cấp quyền người gửi mặc định ưu tiên ID. +Chỉ bật so khớp trực tiếp theo tên/email/biệt danh có thể thay đổi bằng `dangerouslyAllowNameMatching: true` của từng kênh nếu bạn chấp nhận rõ ràng rủi ro đó. ### Khóa API Anthropic + dự phòng MiniMax @@ -599,7 +600,7 @@ Chỉ bật so khớp tên/email/biệt danh có thể thay đổi trực tiếp } ``` -### Bot công việc (quyền truy cập hạn chế) +### Bot công việc (quyền truy cập bị hạn chế) ```json5 { @@ -624,7 +625,7 @@ Chỉ bật so khớp tên/email/biệt danh có thể thay đổi trực tiếp } ``` -### Chỉ mô hình cục bộ +### Chỉ dùng mô hình cục bộ ```json5 { @@ -660,8 +661,8 @@ Chỉ bật so khớp tên/email/biệt danh có thể thay đổi trực tiếp - Nếu bạn đặt `dmPolicy: "open"`, danh sách `allowFrom` tương ứng phải bao gồm `"*"`. - ID của nhà cung cấp khác nhau (số điện thoại, ID người dùng, ID kênh). Dùng tài liệu của nhà cung cấp để xác nhận định dạng. -- Các phần tùy chọn để thêm sau: `web`, `browser`, `ui`, `discovery`, `canvasHost`, `talk`, `signal`, `imessage`. -- Xem [Nhà cung cấp](/vi/providers) và [Khắc phục sự cố](/vi/gateway/troubleshooting) để biết ghi chú thiết lập sâu hơn. +- Các phần tùy chọn có thể thêm sau: `web`, `browser`, `ui`, `discovery`, `canvasHost`, `talk`, `signal`, `imessage`. +- Xem [Nhà cung cấp](/vi/providers) và [Khắc phục sự cố](/vi/gateway/troubleshooting) để biết thêm ghi chú thiết lập chuyên sâu. ## Liên quan diff --git a/docs/vi/gateway/opentelemetry.md b/docs/vi/gateway/opentelemetry.md index aea7ccbce..e0171b88d 100644 --- a/docs/vi/gateway/opentelemetry.md +++ b/docs/vi/gateway/opentelemetry.md @@ -1,40 +1,40 @@ --- read_when: - - Bạn muốn gửi mức sử dụng mô hình OpenClaw, luồng tin nhắn hoặc số liệu phiên đến một bộ thu OpenTelemetry - - Bạn đang kết nối dấu vết, chỉ số hoặc nhật ký vào Grafana, Datadog, Honeycomb, New Relic, Tempo hoặc một phần phụ trợ OTLP khác - - Bạn cần tên chỉ số, tên khoảng đo hoặc cấu trúc thuộc tính chính xác để xây dựng bảng điều khiển hoặc cảnh báo -summary: Xuất dữ liệu chẩn đoán OpenClaw sang bất kỳ bộ thu thập OpenTelemetry nào thông qua Plugin diagnostics-otel (OTLP/HTTP) + - Bạn muốn gửi mức sử dụng mô hình OpenClaw, luồng thông điệp hoặc chỉ số phiên đến bộ thu thập OpenTelemetry + - Bạn đang tích hợp dấu vết, chỉ số hoặc nhật ký vào Grafana, Datadog, Honeycomb, New Relic, Tempo hoặc một phần phụ trợ OTLP khác + - Bạn cần tên chỉ số, tên span hoặc cấu trúc thuộc tính chính xác để xây dựng bảng điều khiển hoặc cảnh báo +summary: Xuất chẩn đoán OpenClaw sang bất kỳ bộ thu thập OpenTelemetry nào thông qua Plugin diagnostics-otel (OTLP/HTTP) title: Xuất OpenTelemetry x-i18n: - generated_at: "2026-05-03T21:32:17Z" + generated_at: "2026-05-04T02:24:28Z" model: gpt-5.5 provider: openai - source_hash: c8091aa633a3e10593681f94913a858587a5dc69d9947e0c0d4132f6e897b00b + source_hash: d0b5be99b29fe5f13132b03cfeaf3ce978ee16f29e307aa76769bc414b5ca35f source_path: gateway/opentelemetry.md workflow: 16 --- -OpenClaw xuất chẩn đoán thông qua Plugin `diagnostics-otel` chính thức -bằng **OTLP/HTTP (protobuf)**. Mọi collector hoặc backend chấp nhận OTLP/HTTP -đều hoạt động mà không cần thay đổi mã. Đối với nhật ký tệp cục bộ và cách đọc chúng, xem -[Ghi nhật ký](/vi/logging). +OpenClaw xuất chẩn đoán thông qua plugin `diagnostics-otel` chính thức +bằng **OTLP/HTTP (protobuf)**. Bất kỳ collector hoặc backend nào chấp nhận OTLP/HTTP +đều hoạt động mà không cần thay đổi mã. Để xem log tệp cục bộ và cách đọc chúng, xem +[Logging](/vi/logging). -## Cách các thành phần phối hợp với nhau +## Cách các phần khớp với nhau - **Sự kiện chẩn đoán** là các bản ghi có cấu trúc, trong tiến trình, được phát ra bởi - Gateway và các Plugin đi kèm cho các lượt chạy mô hình, luồng tin nhắn, phiên, hàng đợi, + Gateway và các plugin đi kèm cho các lần chạy mô hình, luồng tin nhắn, phiên, hàng đợi, và exec. - **Plugin `diagnostics-otel`** đăng ký nhận các sự kiện đó và xuất chúng dưới dạng - OpenTelemetry **metric**, **trace**, và **log** qua OTLP/HTTP. + **metrics**, **traces**, và **logs** của OpenTelemetry qua OTLP/HTTP. - **Lệnh gọi provider** nhận header W3C `traceparent` từ ngữ cảnh span lệnh gọi mô hình đáng tin cậy của OpenClaw khi transport của provider chấp nhận header tùy chỉnh. - Ngữ cảnh trace do Plugin phát ra không được truyền tiếp. -- Exporter chỉ được gắn khi cả bề mặt chẩn đoán và Plugin đều - được bật, nên chi phí trong tiến trình mặc định vẫn gần như bằng không. + Ngữ cảnh trace do plugin phát ra không được lan truyền. +- Exporter chỉ được gắn khi cả bề mặt chẩn đoán và plugin đều + được bật, vì vậy chi phí trong tiến trình mặc định gần như bằng không. ## Bắt đầu nhanh -Đối với bản cài đặt đóng gói, trước tiên hãy cài Plugin: +Đối với bản cài đặt đóng gói, trước tiên hãy cài plugin: ```bash openclaw plugins install clawhub:@openclaw/diagnostics-otel @@ -65,7 +65,7 @@ openclaw plugins install clawhub:@openclaw/diagnostics-otel } ``` -Bạn cũng có thể bật Plugin từ CLI: +Bạn cũng có thể bật plugin từ CLI: ```bash openclaw plugins enable diagnostics-otel @@ -77,13 +77,13 @@ openclaw plugins enable diagnostics-otel ## Tín hiệu được xuất -| Tín hiệu | Nội dung bên trong | +| Tín hiệu | Nội dung trong đó | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **Metrics** | Bộ đếm và histogram cho mức sử dụng token, chi phí, thời lượng chạy, luồng tin nhắn, làn hàng đợi, trạng thái phiên, exec, và áp lực bộ nhớ. | +| **Metrics** | Counter và histogram cho mức sử dụng token, chi phí, thời lượng chạy, luồng tin nhắn, làn hàng đợi, trạng thái phiên, exec, và áp lực bộ nhớ. | | **Traces** | Span cho việc sử dụng mô hình, lệnh gọi mô hình, vòng đời harness, thực thi công cụ, exec, xử lý webhook/tin nhắn, lắp ráp ngữ cảnh, và vòng lặp công cụ. | -| **Logs** | Bản ghi `logging.file` có cấu trúc được xuất qua OTLP khi `diagnostics.otel.logs` được bật. | +| **Logs** | Bản ghi `logging.file` có cấu trúc được xuất qua OTLP khi `diagnostics.otel.logs` được bật. | -Bật/tắt `traces`, `metrics`, và `logs` độc lập. Cả ba đều mặc định bật +Bật tắt `traces`, `metrics`, và `logs` độc lập. Cả ba mặc định bật khi `diagnostics.otel.enabled` là true. ## Tham chiếu cấu hình @@ -122,57 +122,57 @@ khi `diagnostics.otel.enabled` là true. ### Biến môi trường | Biến | Mục đích | -| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Ghi đè `diagnostics.otel.endpoint`. Nếu giá trị đã chứa `/v1/traces`, `/v1/metrics`, hoặc `/v1/logs`, nó được dùng nguyên trạng. | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Ghi đè endpoint theo từng tín hiệu, được dùng khi khóa cấu hình `diagnostics.otel.*Endpoint` tương ứng chưa được đặt. Cấu hình theo tín hiệu thắng env theo tín hiệu, rồi mới đến endpoint dùng chung. | -| `OTEL_SERVICE_NAME` | Ghi đè `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | Ghi đè giao thức truyền tải (hiện nay chỉ `http/protobuf` được tôn trọng). | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Đặt thành `gen_ai_latest_experimental` để phát thuộc tính span GenAI thử nghiệm mới nhất (`gen_ai.provider.name`) thay vì `gen_ai.system` cũ. Metric GenAI luôn dùng các thuộc tính ngữ nghĩa có giới hạn, ít cardinality trong mọi trường hợp. | -| `OPENCLAW_OTEL_PRELOADED` | Đặt thành `1` khi preload khác hoặc tiến trình host đã đăng ký OpenTelemetry SDK toàn cục. Khi đó Plugin bỏ qua vòng đời NodeSDK riêng nhưng vẫn nối listener chẩn đoán và tôn trọng `traces`/`metrics`/`logs`. | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Ghi đè `diagnostics.otel.endpoint`. Nếu giá trị đã chứa `/v1/traces`, `/v1/metrics`, hoặc `/v1/logs`, giá trị đó được dùng nguyên trạng. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Các ghi đè endpoint theo tín hiệu được dùng khi khóa cấu hình `diagnostics.otel.*Endpoint` tương ứng chưa được đặt. Cấu hình theo tín hiệu ưu tiên hơn env theo tín hiệu, và env theo tín hiệu ưu tiên hơn endpoint dùng chung. | +| `OTEL_SERVICE_NAME` | Ghi đè `diagnostics.otel.serviceName`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Ghi đè giao thức truyền tải (hiện nay chỉ `http/protobuf` được tuân theo). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Đặt thành `gen_ai_latest_experimental` để phát thuộc tính span GenAI thử nghiệm mới nhất (`gen_ai.provider.name`) thay vì `gen_ai.system` cũ. Metrics GenAI luôn dùng các thuộc tính ngữ nghĩa có giới hạn, cardinality thấp. | +| `OPENCLAW_OTEL_PRELOADED` | Đặt thành `1` khi một preload khác hoặc tiến trình host đã đăng ký OpenTelemetry SDK toàn cục. Khi đó plugin bỏ qua vòng đời NodeSDK của riêng nó nhưng vẫn nối listener chẩn đoán và tuân theo `traces`/`metrics`/`logs`. | ## Quyền riêng tư và thu thập nội dung Nội dung thô của mô hình/công cụ **không** được xuất theo mặc định. Span mang các -định danh có giới hạn (kênh, provider, mô hình, danh mục lỗi, id yêu cầu chỉ dạng băm) +định danh có giới hạn (kênh, provider, mô hình, loại lỗi, id yêu cầu chỉ dạng hash) và không bao giờ bao gồm văn bản prompt, văn bản phản hồi, đầu vào công cụ, đầu ra công cụ, hoặc khóa phiên. Yêu cầu mô hình đi ra có thể bao gồm header W3C `traceparent`. Header đó chỉ được -tạo từ ngữ cảnh trace chẩn đoán thuộc sở hữu OpenClaw cho lệnh gọi mô hình đang hoạt động. -Header `traceparent` do bên gọi cung cấp sẵn sẽ bị thay thế, nên Plugin hoặc -tùy chọn provider tùy chỉnh không thể giả mạo quan hệ trace ancestry giữa các dịch vụ. +tạo từ ngữ cảnh trace chẩn đoán do OpenClaw sở hữu cho lệnh gọi mô hình đang hoạt động. +Các header `traceparent` do caller cung cấp sẵn sẽ được thay thế, vì vậy plugin hoặc +tùy chọn provider tùy chỉnh không thể giả mạo quan hệ tổ tiên trace liên dịch vụ. Chỉ đặt `diagnostics.otel.captureContent.*` thành `true` khi collector và chính sách lưu giữ của bạn đã được phê duyệt cho văn bản prompt, phản hồi, công cụ, hoặc system-prompt. -Mỗi khóa con được bật riêng: +Mỗi khóa con được chọn bật độc lập: - `inputMessages` — nội dung prompt của người dùng. - `outputMessages` — nội dung phản hồi của mô hình. - `toolInputs` — payload đối số công cụ. - `toolOutputs` — payload kết quả công cụ. -- `systemPrompt` — prompt hệ thống/nhà phát triển đã lắp ráp. +- `systemPrompt` — prompt hệ thống/developer đã lắp ráp. Khi bất kỳ khóa con nào được bật, span mô hình và công cụ nhận các thuộc tính -`openclaw.content.*` có giới hạn, đã biên tập lại chỉ cho lớp đó. +`openclaw.content.*` có giới hạn, đã biên tập cho riêng lớp đó. -## Lấy mẫu và flush +## Sampling và flush - **Traces:** `diagnostics.otel.sampleRate` (chỉ root-span, `0.0` loại bỏ tất cả, `1.0` giữ tất cả). - **Metrics:** `diagnostics.otel.flushIntervalMs` (tối thiểu `1000`). -- **Logs:** Log OTLP tôn trọng `logging.level` (cấp độ log tệp). Chúng dùng - đường dẫn biên tập lại bản ghi log chẩn đoán, không phải định dạng console. Các bản cài đặt - khối lượng lớn nên ưu tiên lấy mẫu/lọc bằng OTLP collector hơn lấy mẫu cục bộ. +- **Logs:** Log OTLP tuân theo `logging.level` (mức log tệp). Chúng dùng đường dẫn + biên tập bản ghi log chẩn đoán, không dùng định dạng console. Bản cài đặt khối lượng lớn + nên ưu tiên sampling/filtering trong OTLP collector thay vì sampling cục bộ. - **Tương quan log tệp:** Log tệp JSONL bao gồm `traceId`, - `spanId`, `parentSpanId`, và `traceFlags` ở cấp cao nhất khi lệnh gọi log mang ngữ cảnh + `spanId`, `parentSpanId`, và `traceFlags` cấp cao nhất khi lệnh gọi log mang ngữ cảnh trace chẩn đoán hợp lệ, cho phép bộ xử lý log nối các dòng log cục bộ với span đã xuất. -- **Tương quan yêu cầu:** Yêu cầu HTTP Gateway và khung WebSocket tạo một +- **Tương quan yêu cầu:** Yêu cầu HTTP của Gateway và khung WebSocket tạo một phạm vi trace yêu cầu nội bộ. Log và sự kiện chẩn đoán bên trong phạm vi đó - mặc định kế thừa trace yêu cầu, trong khi span lượt chạy agent và lệnh gọi mô hình được - tạo làm con để header `traceparent` của provider vẫn nằm trên cùng trace. + mặc định kế thừa trace yêu cầu, trong khi span chạy agent và lệnh gọi mô hình + được tạo làm con để header `traceparent` của provider vẫn nằm trên cùng trace. -## Metric được xuất +## Metrics đã xuất ### Sử dụng mô hình @@ -180,12 +180,12 @@ Khi bất kỳ khóa con nào được bật, span mô hình và công cụ nh - `openclaw.cost.usd` (counter, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) - `openclaw.run.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) - `openclaw.context.tokens` (histogram, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `gen_ai.client.token.usage` (histogram, metric quy ước ngữ nghĩa GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) -- `gen_ai.client.operation.duration` (histogram, giây, metric quy ước ngữ nghĩa GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, tùy chọn `error.type`) -- `openclaw.model_call.duration_ms` (histogram, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, cộng thêm `openclaw.errorCategory` và `openclaw.failureKind` trên lỗi đã phân loại) +- `gen_ai.client.token.usage` (histogram, metrics quy ước ngữ nghĩa GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) +- `gen_ai.client.operation.duration` (histogram, giây, metrics quy ước ngữ nghĩa GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, tùy chọn `error.type`) +- `openclaw.model_call.duration_ms` (histogram, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, cùng với `openclaw.errorCategory` và `openclaw.failureKind` trên các lỗi đã phân loại) - `openclaw.model_call.request_bytes` (histogram, kích thước byte UTF-8 của payload yêu cầu mô hình cuối cùng; không có nội dung payload thô) -- `openclaw.model_call.response_bytes` (histogram, kích thước byte UTF-8 của sự kiện phản hồi mô hình được stream; không có nội dung phản hồi thô) -- `openclaw.model_call.time_to_first_byte_ms` (histogram, thời gian đã trôi qua trước sự kiện phản hồi được stream đầu tiên) +- `openclaw.model_call.response_bytes` (histogram, kích thước byte UTF-8 của sự kiện phản hồi mô hình dạng stream; không có nội dung phản hồi thô) +- `openclaw.model_call.time_to_first_byte_ms` (histogram, thời gian đã trôi qua trước sự kiện phản hồi dạng stream đầu tiên) ### Luồng tin nhắn @@ -205,91 +205,91 @@ Khi bất kỳ khóa con nào được bật, span mô hình và công cụ nh - `openclaw.queue.depth` (histogram, attrs: `openclaw.lane` hoặc `openclaw.channel=heartbeat`) - `openclaw.queue.wait_ms` (histogram, attrs: `openclaw.lane`) - `openclaw.session.state` (counter, attrs: `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (counter, attrs: `openclaw.state`; chỉ được phát cho bookkeeping phiên cũ không có công việc đang hoạt động) -- `openclaw.session.stuck_age_ms` (histogram, attrs: `openclaw.state`; chỉ được phát cho bookkeeping phiên cũ không có công việc đang hoạt động) +- `openclaw.session.stuck` (counter, attrs: `openclaw.state`; chỉ phát ra cho sổ sách phiên cũ không có công việc đang hoạt động) +- `openclaw.session.stuck_age_ms` (histogram, attrs: `openclaw.state`; chỉ phát ra cho sổ sách phiên cũ không có công việc đang hoạt động) - `openclaw.run.attempt` (counter, attrs: `openclaw.attempt`) -### Đo từ xa mức sống của phiên +### Telemetry độ sống của phiên `diagnostics.stuckSessionWarnMs` là ngưỡng tuổi không có tiến triển cho chẩn đoán -mức sống của phiên. Một phiên `processing` không tăng tuổi đến ngưỡng này -khi OpenClaw quan sát thấy tiến triển runtime về phản hồi, công cụ, trạng thái, block, hoặc ACP. -Typing keepalive không được tính là tiến triển, nên mô hình hoặc harness im lặng vẫn có thể -được phát hiện. +độ sống của phiên. Một phiên `processing` không tăng tuổi tới ngưỡng này +trong khi OpenClaw quan sát thấy tiến triển runtime về phản hồi, công cụ, trạng thái, khối, hoặc ACP. +Typing keepalive không được tính là tiến triển, vì vậy mô hình hoặc harness im lặng +vẫn có thể được phát hiện. OpenClaw phân loại phiên theo công việc mà nó vẫn có thể quan sát: - `session.long_running`: công việc nhúng đang hoạt động, lệnh gọi mô hình, hoặc lệnh gọi công cụ vẫn đang tiến triển. -- `session.stalled`: có công việc đang hoạt động, nhưng lượt chạy đang hoạt động chưa báo cáo tiến trình gần đây. Các lượt chạy nhúng bị đình trệ ban đầu vẫn chỉ ở chế độ quan sát, sau đó hủy-xả sau ít nhất 10 phút và 5x `diagnostics.stuckSessionWarnMs` mà không có tiến trình để các lượt trong hàng đợi phía sau lane có thể tiếp tục. -- `session.stuck`: sổ sách phiên đã cũ và không có công việc đang hoạt động. Trạng thái này giải phóng lane phiên bị ảnh hưởng ngay lập tức. +- `session.stalled`: có công việc đang hoạt động, nhưng lượt chạy đang hoạt động chưa báo cáo tiến độ gần đây. Các lượt chạy nhúng bị đình trệ ban đầu vẫn chỉ ở chế độ quan sát, sau đó hủy và xả sau ít nhất 10 phút và 5x `diagnostics.stuckSessionWarnMs` mà không có tiến độ để các lượt được xếp hàng phía sau lane có thể tiếp tục. +- `session.stuck`: sổ sách phiên đã cũ và không có công việc đang hoạt động. Trạng thái này giải phóng ngay lane phiên bị ảnh hưởng. -Chỉ `session.stuck` phát counter `openclaw.session.stuck`, histogram `openclaw.session.stuck_age_ms`, và span `openclaw.session.stuck`. Các chẩn đoán `session.stuck` lặp lại sẽ lùi tần suất khi phiên vẫn không thay đổi, vì vậy dashboard nên cảnh báo theo mức tăng kéo dài thay vì từng nhịp Heartbeat. Để xem núm cấu hình và giá trị mặc định, hãy xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference#diagnostics). +Chỉ `session.stuck` phát ra bộ đếm `openclaw.session.stuck`, histogram `openclaw.session.stuck_age_ms`, và span `openclaw.session.stuck`. Các chẩn đoán `session.stuck` lặp lại sẽ back off trong khi phiên không đổi, vì vậy dashboard nên cảnh báo khi có mức tăng kéo dài thay vì theo từng nhịp Heartbeat. Để xem nút cấu hình và giá trị mặc định, hãy xem [Tài liệu tham chiếu cấu hình](/vi/gateway/configuration-reference#diagnostics). ### Vòng đời harness -- `openclaw.harness.duration_ms` (histogram, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` khi có lỗi) +- `openclaw.harness.duration_ms` (histogram, thuộc tính: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` khi có lỗi) ### Exec -- `openclaw.exec.duration_ms` (histogram, attrs: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) +- `openclaw.exec.duration_ms` (histogram, thuộc tính: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) ### Nội bộ chẩn đoán (bộ nhớ và vòng lặp công cụ) -- `openclaw.memory.heap_used_bytes` (histogram, attrs: `openclaw.memory.kind`) +- `openclaw.memory.heap_used_bytes` (histogram, thuộc tính: `openclaw.memory.kind`) - `openclaw.memory.rss_bytes` (histogram) -- `openclaw.memory.pressure` (counter, attrs: `openclaw.memory.level`) -- `openclaw.tool.loop.iterations` (counter, attrs: `openclaw.toolName`, `openclaw.outcome`) -- `openclaw.tool.loop.duration_ms` (histogram, attrs: `openclaw.toolName`, `openclaw.outcome`) +- `openclaw.memory.pressure` (bộ đếm, thuộc tính: `openclaw.memory.level`) +- `openclaw.tool.loop.iterations` (bộ đếm, thuộc tính: `openclaw.toolName`, `openclaw.outcome`) +- `openclaw.tool.loop.duration_ms` (histogram, thuộc tính: `openclaw.toolName`, `openclaw.outcome`) -## Các span đã xuất +## Các span được xuất - `openclaw.model.usage` - `openclaw.channel`, `openclaw.provider`, `openclaw.model` - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) - - `gen_ai.system` theo mặc định, hoặc `gen_ai.provider.name` khi bật các quy ước ngữ nghĩa GenAI mới nhất + - `gen_ai.system` theo mặc định, hoặc `gen_ai.provider.name` khi các quy ước ngữ nghĩa GenAI mới nhất được chọn dùng - `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*` - `openclaw.run` - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory` - `openclaw.model.call` - - `gen_ai.system` theo mặc định, hoặc `gen_ai.provider.name` khi bật các quy ước ngữ nghĩa GenAI mới nhất + - `gen_ai.system` theo mặc định, hoặc `gen_ai.provider.name` khi các quy ước ngữ nghĩa GenAI mới nhất được chọn dùng - `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` - `openclaw.errorCategory` và `openclaw.failureKind` tùy chọn khi có lỗi - `openclaw.model_call.request_bytes`, `openclaw.model_call.response_bytes`, `openclaw.model_call.time_to_first_byte_ms` - - `openclaw.provider.request_id_hash` (hàm băm có giới hạn dựa trên SHA của id yêu cầu nhà cung cấp upstream; id thô không được xuất) + - `openclaw.provider.request_id_hash` (hash giới hạn dựa trên SHA của id yêu cầu nhà cung cấp upstream; id thô không được xuất) - `openclaw.harness.run` - `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.provider`, `openclaw.model`, `openclaw.channel` - Khi hoàn tất: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active` - - Khi lỗi: `openclaw.harness.phase`, `openclaw.errorCategory`, `openclaw.harness.cleanup_failed` tùy chọn + - Khi có lỗi: `openclaw.harness.phase`, `openclaw.errorCategory`, `openclaw.harness.cleanup_failed` tùy chọn - `openclaw.tool.execution` - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` - `openclaw.exec` - `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`, `openclaw.exec.command_length`, `openclaw.exec.exit_code`, `openclaw.exec.timed_out` - `openclaw.webhook.processed` - - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId` + - `openclaw.channel`, `openclaw.webhook` - `openclaw.webhook.error` - - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId`, `openclaw.error` + - `openclaw.channel`, `openclaw.webhook`, `openclaw.error` - `openclaw.message.processed` - - `openclaw.channel`, `openclaw.outcome`, `openclaw.chatId`, `openclaw.messageId`, `openclaw.reason` + - `openclaw.channel`, `openclaw.outcome`, `openclaw.reason` - `openclaw.message.delivery` - `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`, `openclaw.delivery.result_count` - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (không có nội dung lời nhắc, lịch sử, phản hồi, hoặc khóa phiên) + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (không có nội dung prompt, lịch sử, phản hồi, hoặc khóa phiên) - `openclaw.tool.loop` - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (không có thông điệp vòng lặp, tham số, hoặc đầu ra công cụ) - `openclaw.memory.pressure` - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` -Khi bật rõ ràng tính năng ghi lại nội dung, span mô hình và công cụ cũng có thể bao gồm các thuộc tính `openclaw.content.*` có giới hạn và đã biên tập cho những lớp nội dung cụ thể mà bạn đã chọn tham gia. +Khi ghi lại nội dung được bật rõ ràng, các span mô hình và công cụ cũng có thể bao gồm các thuộc tính `openclaw.content.*` có giới hạn và đã được biên tập lại cho những lớp nội dung cụ thể mà bạn đã chọn dùng. ## Danh mục sự kiện chẩn đoán -Các sự kiện bên dưới hỗ trợ các metric và span ở trên. Plugin cũng có thể đăng ký trực tiếp các sự kiện này mà không cần xuất OTLP. +Các sự kiện bên dưới hỗ trợ các metric và span ở trên. Các Plugin cũng có thể đăng ký trực tiếp với chúng mà không cần xuất OTLP. **Mức sử dụng mô hình** -- `model.usage` — token, chi phí, thời lượng, ngữ cảnh, nhà cung cấp/mô hình/kênh, id phiên. `usage` là kế toán theo nhà cung cấp/lượt cho chi phí và telemetry; `context.used` là ảnh chụp lời nhắc/ngữ cảnh hiện tại và có thể thấp hơn `usage.total` của nhà cung cấp khi có input được lưu cache hoặc các lệnh gọi vòng lặp công cụ. +- `model.usage` — token, chi phí, thời lượng, ngữ cảnh, nhà cung cấp/mô hình/kênh, id phiên. `usage` là kế toán nhà cung cấp/lượt cho chi phí và telemetry; `context.used` là ảnh chụp nhanh prompt/ngữ cảnh hiện tại và có thể thấp hơn `usage.total` của nhà cung cấp khi có đầu vào được lưu cache hoặc lệnh gọi vòng lặp công cụ. **Luồng thông điệp** @@ -302,11 +302,11 @@ Các sự kiện bên dưới hỗ trợ các metric và span ở trên. Plugin - `queue.lane.enqueue` / `queue.lane.dequeue` - `session.state` / `session.long_running` / `session.stalled` / `session.stuck` - `run.attempt` / `run.progress` -- `diagnostic.heartbeat` (counter tổng hợp: webhook/hàng đợi/phiên) +- `diagnostic.heartbeat` (bộ đếm tổng hợp: webhook/hàng đợi/phiên) **Vòng đời harness** -- `harness.run.started` / `harness.run.completed` / `harness.run.error` — vòng đời theo từng lượt chạy cho agent harness. Bao gồm `harnessId`, `pluginId` tùy chọn, nhà cung cấp/mô hình/kênh, và id lượt chạy. Khi hoàn tất, thêm `durationMs`, `outcome`, `resultClassification` tùy chọn, `yieldDetected`, và số đếm `itemLifecycle`. Khi lỗi, thêm `phase` (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory`, và `cleanupFailed` tùy chọn. +- `harness.run.started` / `harness.run.completed` / `harness.run.error` — vòng đời theo từng lượt chạy cho harness tác nhân. Bao gồm `harnessId`, `pluginId` tùy chọn, nhà cung cấp/mô hình/kênh, và id lượt chạy. Khi hoàn tất, thêm `durationMs`, `outcome`, `resultClassification` tùy chọn, `yieldDetected`, và số lượng `itemLifecycle`. Lỗi thêm `phase` (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory`, và `cleanupFailed` tùy chọn. **Exec** @@ -314,7 +314,7 @@ Các sự kiện bên dưới hỗ trợ các metric và span ở trên. Plugin ## Không có exporter -Bạn có thể giữ các sự kiện chẩn đoán khả dụng cho Plugin hoặc sink tùy chỉnh mà không chạy `diagnostics-otel`: +Bạn có thể giữ cho các sự kiện chẩn đoán khả dụng với Plugin hoặc sink tùy chỉnh mà không cần chạy `diagnostics-otel`: ```json5 { @@ -322,7 +322,7 @@ Bạn có thể giữ các sự kiện chẩn đoán khả dụng cho Plugin ho } ``` -Để xuất gỡ lỗi có mục tiêu mà không tăng `logging.level`, hãy dùng cờ chẩn đoán. Cờ không phân biệt chữ hoa chữ thường và hỗ trợ ký tự đại diện (ví dụ `telegram.*` hoặc `*`): +Để có đầu ra gỡ lỗi có mục tiêu mà không tăng `logging.level`, hãy dùng cờ chẩn đoán. Cờ không phân biệt chữ hoa chữ thường và hỗ trợ ký tự đại diện (ví dụ `telegram.*` hoặc `*`): ```json5 { @@ -330,13 +330,13 @@ Bạn có thể giữ các sự kiện chẩn đoán khả dụng cho Plugin ho } ``` -Hoặc dưới dạng ghi đè env dùng một lần: +Hoặc dưới dạng ghi đè env một lần: ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -Đầu ra cờ đi vào tệp log tiêu chuẩn (`logging.file`) và vẫn được biên tập bởi `logging.redactSensitive`. Hướng dẫn đầy đủ: [Cờ chẩn đoán](/vi/diagnostics/flags). +Đầu ra của cờ đi tới tệp log tiêu chuẩn (`logging.file`) và vẫn được biên tập lại bởi `logging.redactSensitive`. Hướng dẫn đầy đủ: [Cờ chẩn đoán](/vi/diagnostics/flags). ## Tắt @@ -350,8 +350,8 @@ Bạn cũng có thể bỏ `diagnostics-otel` khỏi `plugins.allow`, hoặc ch ## Liên quan -- [Ghi log](/vi/logging) — log tệp, đầu ra console, theo dõi đuôi bằng CLI, và tab Logs của Control UI +- [Ghi log](/vi/logging) — log tệp, đầu ra console, theo dõi CLI, và thẻ Logs của Control UI - [Nội bộ ghi log Gateway](/vi/gateway/logging) — kiểu log WS, tiền tố hệ thống con, và ghi lại console - [Cờ chẩn đoán](/vi/diagnostics/flags) — cờ log gỡ lỗi có mục tiêu -- [Xuất chẩn đoán](/vi/gateway/diagnostics) — công cụ support-bundle cho operator (tách biệt với xuất OTEL) -- [Tham chiếu cấu hình](/vi/gateway/configuration-reference#diagnostics) — tham chiếu đầy đủ cho trường `diagnostics.*` +- [Xuất chẩn đoán](/vi/gateway/diagnostics) — công cụ gói hỗ trợ cho người vận hành (tách biệt với xuất OTEL) +- [Tài liệu tham chiếu cấu hình](/vi/gateway/configuration-reference#diagnostics) — tài liệu tham chiếu đầy đủ cho trường `diagnostics.*` diff --git a/docs/vi/gateway/operator-scopes.md b/docs/vi/gateway/operator-scopes.md index 7e1977715..867edc8fc 100644 --- a/docs/vi/gateway/operator-scopes.md +++ b/docs/vi/gateway/operator-scopes.md @@ -1,23 +1,23 @@ --- read_when: - - Gỡ lỗi các lỗi thiếu phạm vi người vận hành + - Gỡ lỗi các lỗi thiếu phạm vi của người vận hành - Xem xét các phê duyệt ghép nối thiết bị hoặc Node - Thêm hoặc phân loại các phương thức RPC của Gateway -summary: Vai trò người vận hành, phạm vi và kiểm tra tại thời điểm phê duyệt cho các máy khách Gateway +summary: Vai trò, phạm vi và kiểm tra tại thời điểm phê duyệt của người vận hành cho các ứng dụng khách Gateway title: Phạm vi của người vận hành x-i18n: - generated_at: "2026-05-03T10:37:03Z" + generated_at: "2026-05-04T02:24:30Z" model: gpt-5.5 provider: openai - source_hash: 48f59f96b41333af9124ad4083ac5442eedb2d6cebdfff74e3ba256f06d36add + source_hash: f05d6bdbf9bdad2aef1c9664bb7ebb4b6241334b8aefac7993104e9977e40450 source_path: gateway/operator-scopes.md workflow: 16 --- -Phạm vi operator xác định một client Gateway có thể làm gì sau khi xác thực. -Chúng là một hàng rào bảo vệ mặt phẳng điều khiển bên trong một miền người vận hành Gateway đáng tin cậy, -không phải cách ly đa đối tượng thuê trong môi trường đối địch. Nếu bạn cần tách biệt mạnh giữa -người dùng, nhóm hoặc máy, hãy chạy các Gateway riêng biệt dưới các người dùng hệ điều hành hoặc +Các phạm vi của người vận hành xác định những gì một máy khách Gateway có thể làm sau khi xác thực. +Chúng là rào chắn control-plane bên trong một miền người vận hành Gateway đáng tin cậy, +không phải cơ chế cô lập đa bên thuê thù địch. Nếu bạn cần tách biệt mạnh giữa +người dùng, nhóm hoặc máy, hãy chạy các Gateway riêng biệt dưới các người dùng OS hoặc máy chủ riêng biệt. Liên quan: [Bảo mật](/vi/gateway/security), [Giao thức Gateway](/vi/gateway/protocol), @@ -25,93 +25,94 @@ Liên quan: [Bảo mật](/vi/gateway/security), [Giao thức Gateway](/vi/gatew ## Vai trò -Client WebSocket Gateway kết nối với một vai trò: +Máy khách WebSocket của Gateway kết nối bằng một vai trò: -- `operator`: client mặt phẳng điều khiển như CLI, Control UI, tự động hóa và +- `operator`: các máy khách control-plane như CLI, Giao diện điều khiển, tự động hóa và các tiến trình trợ giúp đáng tin cậy. -- `node`: máy chủ năng lực như macOS, iOS, Android hoặc Node không giao diện +- `node`: máy chủ năng lực như macOS, iOS, Android hoặc các node không giao diện, vốn cung cấp lệnh thông qua `node.invoke`. -Các phương thức RPC operator yêu cầu vai trò `operator`. Các phương thức bắt nguồn từ Node +Các phương thức RPC của người vận hành yêu cầu vai trò `operator`. Các phương thức bắt nguồn từ node yêu cầu vai trò `node`. -## Cấp độ phạm vi +## Cấp phạm vi -| Phạm vi | Ý nghĩa | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `operator.read` | Trạng thái chỉ đọc, danh sách, catalog, nhật ký, đọc phiên và các lệnh gọi mặt phẳng điều khiển không thay đổi dữ liệu khác. | -| `operator.write` | Các hành động operator thay đổi dữ liệu thông thường như gửi tin nhắn, gọi công cụ, cập nhật cài đặt nói/giọng nói và chuyển tiếp lệnh Node. Cũng đáp ứng `operator.read`. | -| `operator.admin` | Quyền truy cập quản trị mặt phẳng điều khiển. Đáp ứng mọi phạm vi `operator.*`. Bắt buộc để thay đổi cấu hình, cập nhật, hook native, namespace dành riêng nhạy cảm và phê duyệt rủi ro cao. | -| `operator.pairing` | Quản lý ghép nối thiết bị và Node, bao gồm liệt kê, phê duyệt, từ chối, gỡ bỏ, xoay vòng và thu hồi bản ghi ghép nối hoặc token thiết bị. | -| `operator.approvals` | API phê duyệt exec và Plugin. | -| `operator.talk.secrets` | Đọc cấu hình Talk với secret được bao gồm. | +| Phạm vi | Ý nghĩa | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `operator.read` | Trạng thái chỉ đọc, danh sách, danh mục, nhật ký, đọc phiên và các lệnh gọi control-plane không làm thay đổi khác. | +| `operator.write` | Các hành động người vận hành có thay đổi thông thường như gửi tin nhắn, gọi công cụ, cập nhật cài đặt nói/giọng nói và chuyển tiếp lệnh node. Cũng thỏa mãn `operator.read`. | +| `operator.admin` | Quyền truy cập control-plane quản trị. Thỏa mãn mọi phạm vi `operator.*`. Bắt buộc để thay đổi cấu hình, cập nhật, hook native, namespace dành riêng nhạy cảm và phê duyệt rủi ro cao. | +| `operator.pairing` | Quản lý ghép nối thiết bị và node, bao gồm liệt kê, phê duyệt, từ chối, xóa, xoay vòng và thu hồi bản ghi ghép nối hoặc token thiết bị. | +| `operator.approvals` | API phê duyệt exec và plugin. | +| `operator.talk.secrets` | Đọc cấu hình Talk kèm theo bí mật. | Các phạm vi `operator.*` tương lai chưa biết yêu cầu khớp chính xác trừ khi bên gọi có `operator.admin`. ## Phạm vi phương thức chỉ là cổng đầu tiên -Mỗi RPC Gateway có một phạm vi phương thức theo nguyên tắc đặc quyền tối thiểu. Phạm vi phương thức đó quyết định -liệu yêu cầu có thể đến handler hay không. Sau đó, một số handler áp dụng các kiểm tra -nghiêm ngặt hơn tại thời điểm phê duyệt dựa trên đối tượng cụ thể đang được phê duyệt hoặc thay đổi. +Mỗi RPC Gateway có một phạm vi phương thức đặc quyền tối thiểu. Phạm vi phương thức đó quyết định +liệu yêu cầu có thể tới handler hay không. Sau đó, một số handler áp dụng các kiểm tra nghiêm ngặt hơn +tại thời điểm phê duyệt dựa trên thứ cụ thể đang được phê duyệt hoặc thay đổi. Ví dụ: -- `device.pair.approve` có thể truy cập với `operator.pairing`, nhưng việc phê duyệt một - thiết bị operator chỉ có thể tạo hoặc giữ lại các phạm vi mà bên gọi đã có. -- `node.pair.approve` có thể truy cập với `operator.pairing`, sau đó suy ra các - phạm vi phê duyệt bổ sung từ danh sách lệnh Node đang chờ. -- `chat.send` thông thường là phương thức trong phạm vi ghi, nhưng `/config set` - và `/config unset` có tính bền vững yêu cầu `operator.admin` ở cấp lệnh. +- `device.pair.approve` có thể truy cập bằng `operator.pairing`, nhưng việc phê duyệt một + thiết bị người vận hành chỉ có thể cấp hoặc giữ lại các phạm vi mà bên gọi đã có. +- `node.pair.approve` có thể truy cập bằng `operator.pairing`, sau đó suy ra các + phạm vi phê duyệt bổ sung từ danh sách lệnh node đang chờ. +- `chat.send` thường là phương thức có phạm vi ghi, nhưng `/config set` và `/config unset` + bền vững yêu cầu `operator.admin` ở cấp lệnh. -Điều này cho phép operator có phạm vi thấp hơn thực hiện các hành động ghép nối rủi ro thấp mà không biến -mọi phê duyệt ghép nối thành chỉ dành cho admin. +Điều này cho phép người vận hành có phạm vi thấp hơn thực hiện các hành động ghép nối rủi ro thấp mà không biến +mọi phê duyệt ghép nối thành chỉ dành cho quản trị viên. ## Phê duyệt ghép nối thiết bị -Bản ghi ghép nối thiết bị là nguồn bền vững cho các vai trò và phạm vi đã được phê duyệt. -Thiết bị đã ghép nối không nhận quyền truy cập rộng hơn một cách âm thầm: các lần kết nối lại yêu cầu +Bản ghi ghép nối thiết bị là nguồn bền vững của các vai trò và phạm vi đã được phê duyệt. +Các thiết bị đã ghép nối không âm thầm nhận quyền truy cập rộng hơn: các lần kết nối lại yêu cầu vai trò rộng hơn hoặc phạm vi rộng hơn sẽ tạo một yêu cầu nâng cấp mới đang chờ. Khi phê duyệt yêu cầu thiết bị: -- Yêu cầu không có vai trò operator không cần phê duyệt phạm vi token operator. +- Yêu cầu không có vai trò người vận hành không cần phê duyệt phạm vi token người vận hành. - Yêu cầu cho `operator.read`, `operator.write`, `operator.approvals`, - `operator.pairing` hoặc `operator.talk.secrets` yêu cầu bên gọi có + `operator.pairing` hoặc `operator.talk.secrets` yêu cầu bên gọi phải có các phạm vi đó, hoặc `operator.admin`. - Yêu cầu cho `operator.admin` yêu cầu `operator.admin`. -- Yêu cầu sửa chữa không có phạm vi tường minh có thể kế thừa các phạm vi token operator - hiện có. Nếu token hiện có đó có phạm vi admin, việc phê duyệt vẫn yêu cầu +- Yêu cầu sửa chữa không có phạm vi rõ ràng có thể kế thừa các phạm vi token người vận hành + hiện có. Nếu token hiện có đó có phạm vi quản trị, việc phê duyệt vẫn yêu cầu `operator.admin`. -Đối với phiên token thiết bị đã ghép nối, việc quản lý được tự giới hạn phạm vi trừ khi bên gọi -cũng có `operator.admin`: bên gọi không phải admin chỉ có thể xoay vòng, thu hồi hoặc gỡ bỏ -mục thiết bị của chính họ. +Đối với các phiên token thiết bị đã ghép nối, việc quản lý được tự giới hạn phạm vi trừ khi bên gọi +cũng có `operator.admin`: bên gọi không phải quản trị viên chỉ thấy các mục ghép nối của chính họ, +chỉ có thể phê duyệt hoặc từ chối yêu cầu đang chờ của chính họ, và chỉ có thể xoay vòng, thu hồi hoặc +xóa mục thiết bị của chính họ. -## Phê duyệt ghép nối Node +## Phê duyệt ghép nối node -`node.pair.*` cũ sử dụng một kho ghép nối Node riêng do Gateway sở hữu. Node WS -sử dụng ghép nối thiết bị với `role: node`, nhưng cùng bộ từ vựng cấp phê duyệt -được áp dụng. +`node.pair.*` cũ dùng một kho ghép nối node riêng do Gateway sở hữu. Các node WS +dùng ghép nối thiết bị với `role: node`, nhưng cùng bộ thuật ngữ cấp phê duyệt +vẫn được áp dụng. -`node.pair.approve` sử dụng danh sách lệnh của yêu cầu đang chờ để suy ra các +`node.pair.approve` dùng danh sách lệnh của yêu cầu đang chờ để suy ra các phạm vi bắt buộc bổ sung: - Yêu cầu không có lệnh: `operator.pairing` -- Lệnh Node không phải exec: `operator.pairing` + `operator.write` +- Lệnh node không phải exec: `operator.pairing` + `operator.write` - `system.run`, `system.run.prepare` hoặc `system.which`: `operator.pairing` + `operator.admin` -Ghép nối Node thiết lập danh tính và độ tin cậy. Nó không thay thế chính sách phê duyệt exec -`system.run` riêng của Node. +Ghép nối node thiết lập danh tính và độ tin cậy. Nó không thay thế chính sách +phê duyệt exec `system.run` riêng của node. -## Xác thực bằng secret dùng chung +## Xác thực bằng bí mật dùng chung -Xác thực bằng token/mật khẩu gateway dùng chung được xem là quyền truy cập operator đáng tin cậy cho +Xác thực bằng token/mật khẩu gateway dùng chung được xem là quyền truy cập người vận hành đáng tin cậy cho Gateway đó. Các bề mặt HTTP tương thích OpenAI và `/tools/invoke` khôi phục -bộ phạm vi mặc định đầy đủ thông thường của operator cho xác thực bearer bằng secret dùng chung, ngay cả khi +tập phạm vi mặc định đầy đủ bình thường của người vận hành cho xác thực bearer bằng bí mật dùng chung, ngay cả khi bên gọi gửi các phạm vi khai báo hẹp hơn. -Các chế độ mang danh tính, chẳng hạn như xác thực proxy đáng tin cậy hoặc `none` cho ingress riêng, -vẫn có thể tôn trọng các phạm vi khai báo tường minh. Hãy dùng các Gateway riêng biệt để tách biệt +Các chế độ mang danh tính, chẳng hạn như xác thực proxy đáng tin cậy hoặc `none` qua private ingress, +vẫn có thể tôn trọng các phạm vi khai báo rõ ràng. Hãy dùng các Gateway riêng biệt để tách biệt ranh giới tin cậy thực sự. diff --git a/docs/vi/plugins/building-plugins.md b/docs/vi/plugins/building-plugins.md index 25aa5b94b..88bf111da 100644 --- a/docs/vi/plugins/building-plugins.md +++ b/docs/vi/plugins/building-plugins.md @@ -7,29 +7,29 @@ sidebarTitle: Getting Started summary: Tạo Plugin OpenClaw đầu tiên của bạn trong vài phút title: Xây dựng Plugin x-i18n: - generated_at: "2026-05-02T20:46:14Z" + generated_at: "2026-05-04T02:24:37Z" model: gpt-5.5 provider: openai - source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1 + source_hash: 3e6c55c551629da54b3f150ce6299694186fe4434cfd7978a2d43d175d33a5d9 source_path: plugins/building-plugins.md workflow: 16 --- -Plugin mở rộng OpenClaw với các khả năng mới: kênh, nhà cung cấp mô hình, -giọng nói, phiên âm thời gian thực, thoại thời gian thực, hiểu phương tiện, tạo -ảnh, tạo video, web fetch, web search, công cụ agent, hoặc bất kỳ tổ hợp nào. +Các Plugin mở rộng OpenClaw với các khả năng mới: kênh, nhà cung cấp mô hình, +giọng nói, phiên âm theo thời gian thực, thoại theo thời gian thực, hiểu nội dung đa phương tiện, tạo hình ảnh, tạo video, tìm nạp web, tìm kiếm web, công cụ agent, hoặc bất kỳ +kết hợp nào. -Bạn không cần thêm Plugin của mình vào kho OpenClaw. Xuất bản lên +Bạn không cần thêm Plugin của mình vào kho lưu trữ OpenClaw. Xuất bản lên [ClawHub](/vi/tools/clawhub) và người dùng cài đặt bằng -`openclaw plugins install clawhub:`. Các thông số gói trần vẫn -cài đặt từ npm trong giai đoạn chuyển đổi khởi chạy. +`openclaw plugins install clawhub:`. Các đặc tả gói trần vẫn +cài đặt từ npm trong giai đoạn chuyển đổi khi ra mắt. ## Điều kiện tiên quyết - Node >= 22 và một trình quản lý gói (npm hoặc pnpm) - Quen thuộc với TypeScript (ESM) -- Với Plugin trong repo: đã clone kho và chạy xong `pnpm install`. Phát triển - Plugin từ source checkout chỉ hỗ trợ pnpm vì OpenClaw tải các Plugin đi kèm +- Đối với Plugin trong repo: đã clone kho lưu trữ và chạy xong `pnpm install`. Phát triển Plugin từ + checkout mã nguồn chỉ hỗ trợ pnpm vì OpenClaw tải các Plugin được đóng gói kèm từ các gói workspace `extensions/*`. ## Loại Plugin nào? @@ -46,16 +46,16 @@ cài đặt từ npm trong giai đoạn chuyển đổi khởi chạy. -Đối với một Plugin kênh không được bảo đảm đã cài đặt khi quy trình -onboarding/thiết lập chạy, hãy dùng `createOptionalChannelSetupSurface(...)` từ -`openclaw/plugin-sdk/channel-setup`. Hàm này tạo một cặp adapter thiết lập + -wizard, thông báo yêu cầu cài đặt và từ chối an toàn các thao tác ghi cấu hình -thật cho đến khi Plugin được cài đặt. +Đối với một Plugin kênh không được bảo đảm sẽ được cài đặt khi onboarding/thiết lập +chạy, hãy dùng `createOptionalChannelSetupSurface(...)` từ +`openclaw/plugin-sdk/channel-setup`. Hàm này tạo một cặp adapter thiết lập + wizard +để thông báo yêu cầu cài đặt và đóng an toàn khi ghi cấu hình thật +cho đến khi Plugin được cài đặt. ## Bắt đầu nhanh: Plugin công cụ -Hướng dẫn này tạo một Plugin tối thiểu để đăng ký một công cụ agent. Plugin -kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên kết ở trên. +Hướng dẫn này tạo một Plugin tối thiểu để đăng ký một công cụ agent. Plugin kênh +và Plugin nhà cung cấp có các hướng dẫn riêng được liên kết ở trên. @@ -98,13 +98,12 @@ kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên k ``` - Mỗi Plugin cần một manifest, ngay cả khi không có cấu hình. Các công cụ - được đăng ký lúc chạy phải được liệt kê trong `contracts.tools` để OpenClaw - có thể khám phá Plugin sở hữu mà không cần tải mọi runtime Plugin. Plugin - cũng nên khai báo `activation.onStartup` một cách có chủ ý. Ví dụ này đặt - giá trị đó là `true`. Xem [Manifest](/vi/plugins/manifest) để biết schema đầy - đủ. Các đoạn trích xuất bản ClawHub chuẩn nằm trong - `docs/snippets/plugin-publish/`. + Mọi Plugin đều cần một manifest, ngay cả khi không có cấu hình. Các công cụ + được đăng ký ở runtime phải được liệt kê trong `contracts.tools` để OpenClaw có thể phát hiện Plugin sở hữu + mà không cần tải mọi runtime Plugin. Các Plugin cũng nên khai báo + `activation.onStartup` một cách có chủ đích. Ví dụ này đặt giá trị đó là `true`. Xem + [Manifest](/vi/plugins/manifest) để biết schema đầy đủ. Các đoạn lệnh xuất bản ClawHub chuẩn + nằm trong `docs/snippets/plugin-publish/`. @@ -132,7 +131,7 @@ kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên k }); ``` - `definePluginEntry` dành cho Plugin không phải kênh. Với kênh, hãy dùng + `definePluginEntry` dùng cho các Plugin không phải kênh. Đối với kênh, hãy dùng `defineChannelPluginEntry` — xem [Plugin kênh](/vi/plugins/sdk-channel-plugins). Để biết đầy đủ tùy chọn entry point, xem [Entry Points](/vi/plugins/sdk-entrypoints). @@ -140,7 +139,7 @@ kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên k - **Plugin bên ngoài:** xác thực và xuất bản bằng ClawHub, rồi cài đặt: + **Plugin bên ngoài:** xác thực và xuất bản bằng ClawHub, sau đó cài đặt: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -148,10 +147,10 @@ kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên k openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - Các thông số gói trần như `@myorg/openclaw-my-plugin` cài đặt từ npm trong - giai đoạn chuyển đổi khởi chạy. Dùng `clawhub:` khi bạn muốn phân giải qua ClawHub. + Các đặc tả gói trần như `@myorg/openclaw-my-plugin` cài đặt từ npm trong + giai đoạn chuyển đổi khi ra mắt. Dùng `clawhub:` khi bạn muốn phân giải qua ClawHub. - **Plugin trong repo:** đặt dưới cây workspace Plugin đi kèm — sẽ được tự động khám phá. + **Plugin trong repo:** đặt dưới cây workspace Plugin được đóng gói kèm — sẽ được tự động phát hiện. ```bash pnpm test -- /my-plugin/ @@ -164,61 +163,61 @@ kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên k Một Plugin có thể đăng ký bất kỳ số lượng khả năng nào thông qua đối tượng `api`: -| Khả năng | Phương thức đăng ký | Hướng dẫn chi tiết | -| ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | -| Suy luận văn bản (LLM) | `api.registerProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins) | -| Backend suy luận CLI | `api.registerCliBackend(...)` | [Backend CLI](/vi/gateway/cli-backends) | -| Kênh / nhắn tin | `api.registerChannel(...)` | [Plugin kênh](/vi/plugins/sdk-channel-plugins) | +| Khả năng | Phương thức đăng ký | Hướng dẫn chi tiết | +| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | +| Suy luận văn bản (LLM) | `api.registerProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins) | +| Backend suy luận CLI | `api.registerCliBackend(...)` | [Backend CLI](/vi/gateway/cli-backends) | +| Kênh / nhắn tin | `api.registerChannel(...)` | [Plugin kênh](/vi/plugins/sdk-channel-plugins) | | Giọng nói (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Phiên âm thời gian thực | `api.registerRealtimeTranscriptionProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Thoại thời gian thực | `api.registerRealtimeVoiceProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Hiểu phương tiện | `api.registerMediaUnderstandingProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Tạo ảnh | `api.registerImageGenerationProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Hiểu nội dung đa phương tiện | `api.registerMediaUnderstandingProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Tạo hình ảnh | `api.registerImageGenerationProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Tạo nhạc | `api.registerMusicGenerationProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | Tạo video | `api.registerVideoGenerationProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web fetch | `api.registerWebFetchProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web search | `api.registerWebSearchProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Middleware kết quả công cụ | `api.registerAgentToolResultMiddleware(...)` | [Tổng quan SDK](/vi/plugins/sdk-overview#registration-api) | -| Công cụ agent | `api.registerTool(...)` | Bên dưới | -| Lệnh tùy chỉnh | `api.registerCommand(...)` | [Entry Points](/vi/plugins/sdk-entrypoints) | -| Hook Plugin | `api.on(...)` | [Hook Plugin](/vi/plugins/hooks) | -| Hook sự kiện nội bộ | `api.registerHook(...)` | [Entry Points](/vi/plugins/sdk-entrypoints) | -| Route HTTP | `api.registerHttpRoute(...)` | [Nội bộ](/vi/plugins/architecture-internals#gateway-http-routes) | -| Lệnh con CLI | `api.registerCli(...)` | [Entry Points](/vi/plugins/sdk-entrypoints) | +| Tìm nạp web | `api.registerWebFetchProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Tìm kiếm web | `api.registerWebSearchProvider(...)` | [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Middleware kết quả công cụ | `api.registerAgentToolResultMiddleware(...)` | [Tổng quan SDK](/vi/plugins/sdk-overview#registration-api) | +| Công cụ agent | `api.registerTool(...)` | Bên dưới | +| Lệnh tùy chỉnh | `api.registerCommand(...)` | [Entry Points](/vi/plugins/sdk-entrypoints) | +| Hook Plugin | `api.on(...)` | [Hook Plugin](/vi/plugins/hooks) | +| Hook sự kiện nội bộ | `api.registerHook(...)` | [Entry Points](/vi/plugins/sdk-entrypoints) | +| Tuyến HTTP | `api.registerHttpRoute(...)` | [Nội bộ](/vi/plugins/architecture-internals#gateway-http-routes) | +| Lệnh con CLI | `api.registerCli(...)` | [Entry Points](/vi/plugins/sdk-entrypoints) | Để biết API đăng ký đầy đủ, xem [Tổng quan SDK](/vi/plugins/sdk-overview#registration-api). -Plugin đi kèm có thể dùng `api.registerAgentToolResultMiddleware(...)` khi chúng -cần viết lại bất đồng bộ kết quả công cụ trước khi mô hình thấy đầu ra. Khai báo -các runtime được nhắm mục tiêu trong `contracts.agentToolResultMiddleware`, ví dụ -`["pi", "codex"]`. Đây là một điểm mở rộng đáng tin cậy dành cho Plugin đi kèm; -Plugin bên ngoài nên ưu tiên các hook Plugin OpenClaw thông thường, trừ khi -OpenClaw phát triển một chính sách tin cậy rõ ràng cho khả năng này. +Các Plugin được đóng gói kèm có thể dùng `api.registerAgentToolResultMiddleware(...)` khi chúng +cần viết lại kết quả công cụ bất đồng bộ trước khi mô hình thấy đầu ra. Khai báo các +runtime được nhắm tới trong `contracts.agentToolResultMiddleware`, ví dụ +`["pi", "codex"]`. Đây là một seam đáng tin cậy dành cho Plugin được đóng gói kèm; các +Plugin bên ngoài nên ưu tiên hook Plugin OpenClaw thông thường trừ khi OpenClaw phát triển một +chính sách tin cậy rõ ràng cho khả năng này. -Nếu Plugin của bạn đăng ký các phương thức RPC gateway tùy chỉnh, hãy giữ chúng -trên một tiền tố riêng của Plugin. Các namespace quản trị lõi (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) vẫn được giữ riêng và luôn phân giải -thành `operator.admin`, ngay cả khi một Plugin yêu cầu phạm vi hẹp hơn. +Nếu Plugin của bạn đăng ký các phương thức RPC Gateway tùy chỉnh, hãy giữ chúng dưới một +tiền tố riêng cho Plugin. Các namespace quản trị lõi (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) vẫn được dành riêng và luôn phân giải thành +`operator.admin`, ngay cả khi một Plugin yêu cầu phạm vi hẹp hơn. -Các ngữ nghĩa bảo vệ hook cần ghi nhớ: +Ngữ nghĩa guard của hook cần ghi nhớ: -- `before_tool_call`: `{ block: true }` là quyết định cuối cùng và dừng các handler có độ ưu tiên thấp hơn. +- `before_tool_call`: `{ block: true }` là kết thúc và dừng các handler có độ ưu tiên thấp hơn. - `before_tool_call`: `{ block: false }` được xem như không có quyết định. - `before_tool_call`: `{ requireApproval: true }` tạm dừng thực thi agent và nhắc người dùng phê duyệt qua lớp phủ phê duyệt exec, nút Telegram, tương tác Discord, hoặc lệnh `/approve` trên bất kỳ kênh nào. -- `before_install`: `{ block: true }` là quyết định cuối cùng và dừng các handler có độ ưu tiên thấp hơn. +- `before_install`: `{ block: true }` là kết thúc và dừng các handler có độ ưu tiên thấp hơn. - `before_install`: `{ block: false }` được xem như không có quyết định. -- `message_sending`: `{ cancel: true }` là quyết định cuối cùng và dừng các handler có độ ưu tiên thấp hơn. +- `message_sending`: `{ cancel: true }` là kết thúc và dừng các handler có độ ưu tiên thấp hơn. - `message_sending`: `{ cancel: false }` được xem như không có quyết định. -- `message_received`: ưu tiên trường có kiểu `threadId` khi bạn cần định tuyến thread/chủ đề đến. Giữ `metadata` cho các phần bổ sung riêng theo kênh. -- `message_sending`: ưu tiên các trường định tuyến có kiểu `replyToId` / `threadId` hơn các khóa metadata riêng theo kênh. +- `message_received`: ưu tiên trường có kiểu `threadId` khi bạn cần định tuyến luồng/chủ đề đầu vào. Giữ `metadata` cho các phần bổ sung riêng của kênh. +- `message_sending`: ưu tiên các trường định tuyến có kiểu `replyToId` / `threadId` thay vì các khóa metadata riêng của kênh. -Lệnh `/approve` xử lý cả phê duyệt exec và Plugin với cơ chế dự phòng có giới hạn: khi không tìm thấy id phê duyệt exec, OpenClaw thử lại cùng id đó qua phê duyệt Plugin. Có thể cấu hình độc lập việc chuyển tiếp phê duyệt Plugin qua `approvals.plugin` trong cấu hình. +Lệnh `/approve` xử lý cả phê duyệt exec và phê duyệt Plugin với fallback có giới hạn: khi không tìm thấy id phê duyệt exec, OpenClaw thử lại cùng id đó qua phê duyệt Plugin. Có thể cấu hình chuyển tiếp phê duyệt Plugin độc lập qua `approvals.plugin` trong cấu hình. -Nếu hệ thống phê duyệt tùy chỉnh cần phát hiện cùng trường hợp dự phòng có giới -hạn đó, hãy ưu tiên `isApprovalNotFoundError` từ -`openclaw/plugin-sdk/error-runtime` thay vì tự khớp chuỗi hết hạn phê duyệt. +Nếu hệ thống phê duyệt tùy chỉnh cần phát hiện cùng trường hợp fallback có giới hạn đó, +hãy ưu tiên `isApprovalNotFoundError` từ `openclaw/plugin-sdk/error-runtime` +thay vì tự khớp chuỗi hết hạn phê duyệt thủ công. -Xem [Hook Plugin](/vi/plugins/hooks) để biết ví dụ và tham chiếu hook. +Xem [Hook Plugin](/vi/plugins/hooks) để biết ví dụ và tài liệu tham chiếu hook. ## Đăng ký công cụ agent @@ -252,23 +251,31 @@ register(api) { } ``` -Mọi công cụ được đăng ký bằng `api.registerTool(...)` cũng phải được khai báo -trong manifest Plugin: +Mọi công cụ được đăng ký bằng `api.registerTool(...)` cũng phải được khai báo trong +manifest Plugin: ```json { "contracts": { "tools": ["my_tool", "workflow_tool"] + }, + "toolMetadata": { + "workflow_tool": { + "optional": true + } } } ``` -OpenClaw thu thập và lưu cache descriptor đã xác thực từ công cụ đã đăng ký, vì -vậy Plugin không lặp lại `description` hoặc dữ liệu schema trong manifest. -Contract manifest chỉ khai báo quyền sở hữu và khả năng khám phá; việc thực thi -vẫn gọi implementation công cụ đã đăng ký đang hoạt động. +OpenClaw thu thập và lưu vào bộ nhớ đệm descriptor đã được xác thực từ công cụ đã đăng ký, +vì vậy các plugin không cần lặp lại dữ liệu `description` hoặc schema trong manifest. Hợp đồng +manifest chỉ khai báo quyền sở hữu và khả năng khám phá; việc thực thi vẫn gọi +phần triển khai công cụ đã đăng ký đang hoạt động. +Đặt `toolMetadata..optional: true` cho các công cụ được đăng ký bằng +`api.registerTool(..., { optional: true })` để OpenClaw có thể tránh tải +plugin runtime đó cho đến khi công cụ được đưa vào danh sách cho phép một cách rõ ràng. -Người dùng bật công cụ tùy chọn trong cấu hình: +Người dùng bật các công cụ tùy chọn trong config: ```json5 { @@ -276,16 +283,16 @@ Người dùng bật công cụ tùy chọn trong cấu hình: } ``` -- Tên công cụ không được xung đột với các công cụ lõi (các xung đột sẽ bị bỏ qua) -- Các công cụ có đối tượng đăng ký sai định dạng, bao gồm thiếu `parameters`, sẽ bị bỏ qua và được báo cáo trong chẩn đoán Plugin thay vì làm hỏng các lần chạy agent -- Dùng `optional: true` cho các công cụ có tác dụng phụ hoặc yêu cầu thêm binary -- Người dùng có thể bật tất cả công cụ từ một Plugin bằng cách thêm id Plugin vào `tools.allow` +- Tên công cụ không được xung đột với các công cụ lõi (xung đột sẽ bị bỏ qua) +- Các công cụ có đối tượng đăng ký không đúng định dạng, bao gồm thiếu `parameters`, sẽ bị bỏ qua và được báo cáo trong chẩn đoán plugin thay vì làm hỏng các lần chạy agent +- Dùng `optional: true` cho các công cụ có tác dụng phụ hoặc yêu cầu binary bổ sung +- Người dùng có thể bật tất cả công cụ từ một plugin bằng cách thêm plugin id vào `tools.allow` ## Đăng ký lệnh CLI Plugin có thể thêm các nhóm lệnh `openclaw` gốc bằng `api.registerCli`. Cung cấp `descriptors` cho mọi gốc lệnh cấp cao nhất để OpenClaw có thể hiển thị và định tuyến -lệnh mà không cần tải sẵn mọi runtime Plugin. +lệnh mà không cần tải sẵn mọi plugin runtime. ```typescript register(api) { @@ -315,7 +322,7 @@ register(api) { } ``` -Sau khi cài đặt, hãy xác minh đăng ký runtime và thực thi lệnh: +Sau khi cài đặt, xác minh đăng ký runtime và thực thi lệnh: ```bash openclaw plugins inspect demo-plugin --runtime --json @@ -336,55 +343,55 @@ import { ... } from "openclaw/plugin-sdk"; Để xem tham chiếu subpath đầy đủ, hãy xem [Tổng quan SDK](/vi/plugins/sdk-overview). -Trong Plugin của bạn, dùng các tệp barrel cục bộ (`api.ts`, `runtime-api.ts`) cho -import nội bộ — không bao giờ import chính Plugin của bạn thông qua đường dẫn SDK của nó. +Trong plugin của bạn, hãy dùng các tệp barrel cục bộ (`api.ts`, `runtime-api.ts`) cho +các import nội bộ — không bao giờ import chính plugin của bạn thông qua đường dẫn SDK của nó. -Đối với Plugin nhà cung cấp, hãy giữ các helper dành riêng cho nhà cung cấp trong các -barrel gốc package đó trừ khi seam thật sự mang tính chung. Các ví dụ bundled hiện tại: +Đối với provider plugin, giữ các helper dành riêng cho provider trong các barrel +gốc package đó trừ khi seam thực sự có tính tổng quát. Các ví dụ được đóng gói hiện tại: -- Anthropic: wrapper luồng Claude và helper `service_tier` / beta -- OpenAI: builder nhà cung cấp, helper model mặc định, nhà cung cấp realtime -- OpenRouter: builder nhà cung cấp cùng helper onboarding/cấu hình +- Anthropic: wrapper stream Claude và các helper `service_tier` / beta +- OpenAI: provider builder, helper mô hình mặc định, provider realtime +- OpenRouter: provider builder cùng helper onboarding/config -Nếu một helper chỉ hữu ích bên trong một package nhà cung cấp bundled, hãy giữ nó trên +Nếu một helper chỉ hữu ích bên trong một package provider được đóng gói, hãy giữ nó trên seam gốc package đó thay vì đưa nó vào `openclaw/plugin-sdk/*`. Một số seam helper `openclaw/plugin-sdk/` được tạo vẫn tồn tại cho -bảo trì bundled-Plugin khi chúng có theo dõi việc sử dụng của owner. Hãy xem chúng là -bề mặt được dành riêng, không phải mẫu mặc định cho Plugin bên thứ ba mới. +việc bảo trì bundled-plugin khi chúng có mức sử dụng từ owner được theo dõi. Hãy xem đó là +các bề mặt dành riêng, không phải mẫu mặc định cho plugin bên thứ ba mới. -## Checklist trước khi gửi +## Danh sách kiểm tra trước khi gửi **package.json** có metadata `openclaw` chính xác Manifest **openclaw.plugin.json** hiện diện và hợp lệ Entry point dùng `defineChannelPluginEntry` hoặc `definePluginEntry` -Tất cả import dùng đường dẫn `plugin-sdk/` tập trung +Tất cả import dùng các đường dẫn `plugin-sdk/` tập trung Import nội bộ dùng module cục bộ, không tự import qua SDK -Test pass (`pnpm test -- /my-plugin/`) -`pnpm check` pass (Plugin trong repo) +Test vượt qua (`pnpm test -- /my-plugin/`) +`pnpm check` vượt qua (plugin trong repo) ## Kiểm thử bản phát hành beta -1. Theo dõi các tag phát hành GitHub trên [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) và đăng ký qua `Watch` > `Releases`. Tag beta có dạng `v2026.3.N-beta.1`. Bạn cũng có thể bật thông báo cho tài khoản X chính thức của OpenClaw [@openclaw](https://x.com/openclaw) để nhận thông báo phát hành. -2. Kiểm thử Plugin của bạn với tag beta ngay khi nó xuất hiện. Khoảng thời gian trước bản stable thường chỉ vài giờ. -3. Đăng trong thread của Plugin của bạn ở kênh Discord `plugin-forum` sau khi kiểm thử, với `all good` hoặc nội dung đã bị hỏng. Nếu bạn chưa có thread, hãy tạo một thread. -4. Nếu có thứ gì đó bị hỏng, hãy mở hoặc cập nhật một issue có tiêu đề `Beta blocker: - ` và áp dụng nhãn `beta-blocker`. Đặt liên kết issue trong thread của bạn. -5. Mở một PR tới `main` có tiêu đề `fix(): beta blocker - ` và liên kết issue trong cả PR lẫn thread Discord của bạn. Contributor không thể gắn nhãn PR, nên tiêu đề là tín hiệu phía PR cho maintainer và tự động hóa. Blocker có PR sẽ được merge; blocker không có PR có thể vẫn được phát hành. Maintainer theo dõi các thread này trong khi kiểm thử beta. -6. Im lặng nghĩa là xanh. Nếu bạn bỏ lỡ khoảng thời gian này, bản sửa của bạn nhiều khả năng sẽ vào chu kỳ tiếp theo. +1. Theo dõi các thẻ phát hành GitHub trên [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) và đăng ký qua `Watch` > `Releases`. Thẻ beta có dạng `v2026.3.N-beta.1`. Bạn cũng có thể bật thông báo cho tài khoản X chính thức của OpenClaw [@openclaw](https://x.com/openclaw) để nhận thông báo phát hành. +2. Kiểm thử plugin của bạn với thẻ beta ngay khi thẻ xuất hiện. Khoảng thời gian trước bản stable thường chỉ là vài giờ. +3. Đăng trong thread của plugin của bạn trong kênh Discord `plugin-forum` sau khi kiểm thử, với `all good` hoặc nội dung bị hỏng. Nếu bạn chưa có thread, hãy tạo một thread. +4. Nếu có thứ bị hỏng, hãy mở hoặc cập nhật một issue có tiêu đề `Beta blocker: - ` và áp dụng nhãn `beta-blocker`. Đặt liên kết issue trong thread của bạn. +5. Mở một PR tới `main` có tiêu đề `fix(): beta blocker - ` và liên kết issue trong cả PR lẫn thread Discord của bạn. Contributor không thể gắn nhãn PR, nên tiêu đề là tín hiệu phía PR cho maintainer và tự động hóa. Blocker có PR sẽ được merge; blocker không có PR vẫn có thể được phát hành. Maintainer theo dõi các thread này trong quá trình kiểm thử beta. +6. Im lặng nghĩa là xanh. Nếu bạn bỏ lỡ khoảng thời gian này, bản sửa của bạn có khả năng sẽ vào chu kỳ tiếp theo. ## Bước tiếp theo - - Xây dựng Plugin kênh nhắn tin + + Xây dựng plugin kênh nhắn tin - - Xây dựng Plugin nhà cung cấp model + + Xây dựng plugin provider mô hình Tham chiếu import map và API đăng ký - + TTS, tìm kiếm, subagent qua api.runtime @@ -398,7 +405,7 @@ bề mặt được dành riêng, không phải mẫu mặc định cho Plugin b ## Liên quan - [Kiến trúc Plugin](/vi/plugins/architecture) — phân tích sâu kiến trúc nội bộ -- [Tổng quan SDK](/vi/plugins/sdk-overview) — tham chiếu SDK Plugin -- [Manifest](/vi/plugins/manifest) — định dạng manifest Plugin -- [Channel Plugins](/vi/plugins/sdk-channel-plugins) — xây dựng Plugin kênh -- [Provider Plugins](/vi/plugins/sdk-provider-plugins) — xây dựng Plugin nhà cung cấp +- [Tổng quan SDK](/vi/plugins/sdk-overview) — tham chiếu Plugin SDK +- [Manifest](/vi/plugins/manifest) — định dạng manifest plugin +- [Channel Plugin](/vi/plugins/sdk-channel-plugins) — xây dựng channel plugin +- [Provider Plugin](/vi/plugins/sdk-provider-plugins) — xây dựng provider plugin diff --git a/docs/vi/plugins/google-meet.md b/docs/vi/plugins/google-meet.md index 85fb7372c..66a25b637 100644 --- a/docs/vi/plugins/google-meet.md +++ b/docs/vi/plugins/google-meet.md @@ -1,43 +1,43 @@ --- read_when: - - Bạn muốn một tác tử OpenClaw tham gia cuộc gọi Google Meet + - Bạn muốn một tác nhân OpenClaw tham gia cuộc gọi Google Meet - Bạn muốn một tác nhân OpenClaw tạo một cuộc gọi Google Meet mới - - Bạn đang cấu hình Chrome, nút Chrome hoặc Twilio làm phương thức truyền tải cho Google Meet -summary: 'Plugin Google Meet: tham gia các URL Meet tường minh qua Chrome hoặc Twilio với các mặc định thoại thời gian thực' + - Bạn đang cấu hình Chrome, Chrome node hoặc Twilio làm phương thức truyền tải cho Google Meet +summary: 'Plugin Google Meet: tham gia các URL Meet được chỉ định rõ qua Chrome hoặc Twilio với thiết lập thoại thời gian thực mặc định' title: Plugin Google Meet x-i18n: - generated_at: "2026-05-02T10:48:20Z" + generated_at: "2026-05-04T02:24:58Z" model: gpt-5.5 provider: openai - source_hash: 0dc515382d2cc7beacaf18a50b75cb0f4eda3038cfd8efe73ea3ce7b5007bc43 + source_hash: 77ab70d27d47bcc037144c7c6cfad6f93f307355b6ebcf3ee75c85b96a24af2f source_path: plugins/google-meet.md workflow: 16 --- -Hỗ trợ người tham gia Google Meet cho OpenClaw — Plugin được thiết kế theo cách tường minh: +Hỗ trợ người tham gia Google Meet cho OpenClaw — Plugin này chủ ý được thiết kế rõ ràng: -- Nó chỉ tham gia một URL `https://meet.google.com/...` tường minh. -- Nó có thể tạo một không gian Meet mới thông qua Google Meet API, rồi tham gia +- Plugin chỉ tham gia một URL `https://meet.google.com/...` rõ ràng. +- Plugin có thể tạo một không gian Meet mới thông qua Google Meet API, rồi tham gia URL được trả về. - Giọng nói `realtime` là chế độ mặc định. -- Giọng nói realtime có thể gọi ngược vào tác nhân OpenClaw đầy đủ khi cần suy - luận sâu hơn hoặc cần công cụ. +- Giọng nói thời gian thực có thể gọi ngược vào tác nhân OpenClaw đầy đủ khi cần + suy luận sâu hơn hoặc công cụ. - Tác nhân chọn hành vi tham gia bằng `mode`: dùng `realtime` để nghe/nói phản hồi - trực tiếp, hoặc `transcribe` để tham gia/điều khiển trình duyệt mà không dùng - cầu nối giọng nói realtime. -- Xác thực bắt đầu bằng Google OAuth cá nhân hoặc một hồ sơ Chrome đã đăng nhập. + trực tiếp, hoặc `transcribe` để tham gia/điều khiển trình duyệt mà không có cầu nối + giọng nói thời gian thực. +- Xác thực khởi đầu bằng Google OAuth cá nhân hoặc một hồ sơ Chrome đã đăng nhập. - Không có thông báo đồng ý tự động. - Backend âm thanh Chrome mặc định là `BlackHole 2ch`. -- Chrome có thể chạy cục bộ hoặc trên một node host đã ghép đôi. -- Twilio chấp nhận số gọi vào cùng PIN hoặc chuỗi DTMF tùy chọn; nó không thể - gọi trực tiếp một URL Meet. -- Lệnh CLI là `googlemeet`; `meet` được dành riêng cho các quy trình hội nghị từ xa - rộng hơn của tác nhân. +- Chrome có thể chạy cục bộ hoặc trên máy chủ Node đã ghép đôi. +- Twilio chấp nhận số gọi vào cùng PIN hoặc chuỗi DTMF tùy chọn; Twilio + không thể quay trực tiếp tới URL Meet. +- Lệnh CLI là `googlemeet`; `meet` được dành cho các quy trình họp từ xa rộng hơn + của tác nhân. ## Bắt đầu nhanh Cài đặt các phụ thuộc âm thanh cục bộ và cấu hình một nhà cung cấp giọng nói -realtime backend. OpenAI là mặc định; Google Gemini Live cũng hoạt động với +thời gian thực backend. OpenAI là mặc định; Google Gemini Live cũng hoạt động với `realtime.provider: "google"`: ```bash @@ -47,14 +47,14 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` cài đặt thiết bị âm thanh ảo `BlackHole 2ch`. Trình cài đặt của Homebrew -yêu cầu khởi động lại trước khi macOS hiển thị thiết bị: +`blackhole-2ch` cài đặt thiết bị âm thanh ảo `BlackHole 2ch`. Trình cài đặt của +Homebrew yêu cầu khởi động lại trước khi macOS hiển thị thiết bị: ```bash sudo reboot ``` -Sau khi khởi động lại, xác minh cả hai phần: +Sau khi khởi động lại, xác minh cả hai thành phần: ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -83,33 +83,34 @@ openclaw googlemeet setup ``` Đầu ra thiết lập được thiết kế để tác nhân có thể đọc và nhận biết chế độ. Nó -báo cáo hồ sơ Chrome, ghim node, và, với các lượt tham gia Chrome realtime, cầu -nối âm thanh BlackHole/SoX cùng các kiểm tra phần giới thiệu realtime bị trì -hoãn. Với các lượt tham gia chỉ quan sát, kiểm tra cùng transport bằng -`--mode transcribe`; chế độ đó bỏ qua các điều kiện tiên quyết về âm thanh -realtime vì nó không nghe qua hoặc nói qua cầu nối: +báo cáo hồ sơ Chrome, ghim Node, và, với các lượt tham gia Chrome thời gian thực, +các kiểm tra cầu nối âm thanh BlackHole/SoX và phần giới thiệu thời gian thực bị +trễ. Với lượt tham gia chỉ quan sát, kiểm tra cùng phương thức truyền bằng +`--mode transcribe`; chế độ đó bỏ qua các điều kiện tiên quyết về âm thanh thời +gian thực vì nó không nghe qua hoặc nói qua cầu nối: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` Khi ủy quyền Twilio được cấu hình, thiết lập cũng báo cáo liệu Plugin -`voice-call`, thông tin xác thực Twilio, và phơi bày Webhook công khai đã sẵn -sàng hay chưa. Xem mọi kiểm tra `ok: false` là yếu tố chặn đối với transport và -chế độ được kiểm tra trước khi yêu cầu tác nhân tham gia. Dùng +`voice-call`, thông tin xác thực Twilio và khả năng hiển thị Webhook công khai +đã sẵn sàng hay chưa. Xem mọi kiểm tra `ok: false` là yếu tố chặn đối với phương +thức truyền và chế độ được kiểm tra trước khi yêu cầu tác nhân tham gia. Dùng `openclaw googlemeet setup --json` cho script hoặc đầu ra máy đọc được. Dùng `--transport chrome`, `--transport chrome-node`, hoặc `--transport twilio` để -kiểm tra trước một transport cụ thể trước khi tác nhân thử dùng. +kiểm tra trước một phương thức truyền cụ thể trước khi tác nhân thử dùng. -Với Twilio, luôn kiểm tra trước transport một cách tường minh khi transport mặc -định là Chrome: +Với Twilio, luôn kiểm tra trước phương thức truyền một cách rõ ràng khi phương +thức truyền mặc định là Chrome: ```bash openclaw googlemeet setup --transport twilio ``` -Việc đó phát hiện thiếu kết nối `voice-call`, thông tin xác thực Twilio, hoặc -phơi bày Webhook không truy cập được trước khi tác nhân thử gọi vào cuộc họp. +Việc đó phát hiện thiếu nối dây `voice-call`, thông tin xác thực Twilio, hoặc +khả năng hiển thị Webhook không truy cập được trước khi tác nhân thử gọi vào +cuộc họp. Tham gia một cuộc họp: @@ -124,16 +125,16 @@ Hoặc để tác nhân tham gia thông qua công cụ `google_meet`: "action": "join", "url": "https://meet.google.com/abc-defg-hij", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` -Công cụ `google_meet` dành cho tác nhân vẫn khả dụng trên host không phải macOS -cho các luồng artifact, lịch, thiết lập, phiên âm, Twilio, và `chrome-node`. Các -hành động realtime Chrome cục bộ bị chặn ở đó vì đường dẫn âm thanh realtime -Chrome đi kèm hiện phụ thuộc vào `BlackHole 2ch` trên macOS. Trên Linux, dùng -`mode: "transcribe"`, gọi vào bằng Twilio, hoặc một host `chrome-node` macOS để -tham gia Chrome realtime. +Công cụ `google_meet` dành cho tác nhân vẫn khả dụng trên các máy chủ không phải +macOS cho các luồng hiện vật, lịch, thiết lập, phiên âm, Twilio và `chrome-node`. +Các hành động nói phản hồi bằng Chrome cục bộ bị chặn ở đó vì đường dẫn âm thanh +Chrome đóng gói kèm hiện phụ thuộc vào `BlackHole 2ch` của macOS. Trên Linux, +dùng `mode: "transcribe"`, gọi vào bằng Twilio, hoặc một máy chủ `chrome-node` +macOS để tham gia nói phản hồi bằng Chrome. Tạo một cuộc họp mới và tham gia: @@ -141,20 +142,20 @@ Tạo một cuộc họp mới và tham gia: openclaw googlemeet create --transport chrome-node --mode realtime ``` -Với các phòng được tạo bằng API, dùng Google Meet `SpaceConfig.accessType` khi -bạn muốn chính sách không cần xin vào phòng được tường minh thay vì kế thừa từ -mặc định của tài khoản Google: +Với phòng được tạo bằng API, dùng Google Meet `SpaceConfig.accessType` khi bạn +muốn chính sách không cần gõ cửa của phòng được chỉ định rõ ràng thay vì kế thừa +từ mặc định của tài khoản Google: ```bash openclaw googlemeet create --access-type OPEN --transport chrome-node --mode realtime ``` -`OPEN` cho phép bất kỳ ai có URL Meet tham gia mà không cần xin vào. `TRUSTED` -cho phép người dùng đáng tin cậy của tổ chức host, người dùng bên ngoài được mời, -và người dùng gọi vào tham gia mà không cần xin vào. `RESTRICTED` giới hạn quyền -vào không cần xin cho người được mời. Các thiết lập này chỉ áp dụng cho đường dẫn -tạo bằng Google Meet API chính thức, vì vậy phải cấu hình thông tin xác thực -OAuth. +`OPEN` cho phép bất kỳ ai có URL Meet tham gia mà không cần gõ cửa. `TRUSTED` +cho phép người dùng đáng tin cậy của tổ chức chủ trì, người dùng bên ngoài được +mời và người dùng gọi vào tham gia mà không cần gõ cửa. `RESTRICTED` giới hạn +quyền vào không cần gõ cửa cho người được mời. Các cài đặt này chỉ áp dụng cho +đường dẫn tạo chính thức của Google Meet API, nên thông tin xác thực OAuth phải +được cấu hình. Nếu bạn đã xác thực Google Meet trước khi tùy chọn này có sẵn, hãy chạy lại `openclaw googlemeet auth login --json` sau khi thêm phạm vi @@ -168,28 +169,26 @@ openclaw googlemeet create --no-join `googlemeet create` có hai đường dẫn: -- Tạo bằng API: được dùng khi thông tin xác thực Google Meet OAuth đã được cấu - hình. Đây là đường dẫn xác định nhất và không phụ thuộc vào trạng thái UI trình - duyệt. -- Dự phòng trình duyệt: được dùng khi không có thông tin xác thực OAuth. OpenClaw - dùng node Chrome đã ghim, mở `https://meet.google.com/new`, chờ Google chuyển - hướng đến một URL mã cuộc họp thật, rồi trả về URL đó. Đường dẫn này yêu cầu - hồ sơ Chrome OpenClaw trên node đã đăng nhập Google. - Tự động hóa trình duyệt xử lý lời nhắc microphone lần đầu của chính Meet; lời - nhắc đó không được xem là lỗi đăng nhập Google. - Các luồng tham gia và tạo cũng cố gắng tái sử dụng một tab Meet hiện có trước - khi mở tab mới. Việc khớp bỏ qua các chuỗi truy vấn URL vô hại như `authuser`, - nên lần thử lại của tác nhân sẽ tập trung vào cuộc họp đang mở thay vì tạo một - tab Chrome thứ hai. +- Tạo bằng API: được dùng khi thông tin xác thực Google Meet OAuth được cấu hình. Đây là + đường dẫn xác định nhất và không phụ thuộc vào trạng thái giao diện người dùng trình duyệt. +- Dự phòng trình duyệt: được dùng khi không có thông tin xác thực OAuth. OpenClaw dùng + Node Chrome đã ghim, mở `https://meet.google.com/new`, đợi Google + chuyển hướng tới một URL mã cuộc họp thật, rồi trả về URL đó. Đường dẫn này yêu cầu + hồ sơ Chrome OpenClaw trên Node đã đăng nhập Google. + Tự động hóa trình duyệt xử lý lời nhắc micrô lần đầu của Meet; lời nhắc đó + không được coi là lỗi đăng nhập Google. + Các luồng tham gia và tạo cũng cố gắng tái sử dụng một tab Meet hiện có trước khi mở + tab mới. Việc khớp bỏ qua các chuỗi truy vấn URL vô hại như `authuser`, nên một lần + thử lại của tác nhân sẽ tập trung vào cuộc họp đã mở thay vì tạo tab Chrome thứ hai. Đầu ra lệnh/công cụ bao gồm trường `source` (`api` hoặc `browser`) để tác nhân -có thể giải thích đường dẫn nào đã được dùng. `create` mặc định tham gia cuộc họp -mới và trả về `joined: true` cùng phiên tham gia. Để chỉ tạo URL, dùng +có thể giải thích đường dẫn nào đã được dùng. `create` tham gia cuộc họp mới +theo mặc định và trả về `joined: true` cùng phiên tham gia. Để chỉ tạo URL, dùng `create --no-join` trên CLI hoặc truyền `"join": false` cho công cụ. -Hoặc nói với tác nhân: "Tạo một Google Meet, tham gia bằng giọng nói realtime, và gửi -cho tôi liên kết." Tác nhân nên gọi `google_meet` với `action: "create"` rồi chia -sẻ `meetingUri` được trả về. +Hoặc nói với tác nhân: "Tạo một Google Meet, tham gia bằng giọng nói thời gian +thực, và gửi cho tôi liên kết." Tác nhân nên gọi `google_meet` với +`action: "create"` rồi chia sẻ `meetingUri` được trả về. ```json { @@ -199,56 +198,54 @@ sẻ `meetingUri` được trả về. } ``` -Với lượt tham gia chỉ quan sát/điều khiển trình duyệt, đặt `"mode": "transcribe"`. -Chế độ đó không khởi động cầu nối mô hình realtime song công, không yêu cầu -BlackHole hoặc SoX, và sẽ không nói phản hồi vào cuộc họp. Các lượt tham gia -Chrome ở chế độ này cũng tránh cấp quyền microphone/camera của OpenClaw và tránh -đường dẫn **Use microphone** của Meet. Nếu Meet hiển thị màn hình chọn âm thanh, -tự động hóa sẽ thử đường dẫn không dùng microphone và nếu không được thì báo cáo -một hành động thủ công thay vì mở microphone cục bộ. Ở chế độ transcribe, các -transport Chrome được quản lý cũng cài đặt một trình quan sát phụ đề Meet theo -khả năng tốt nhất. `googlemeet status --json` và `googlemeet doctor` hiển thị -`captioning`, `captionsEnabledAttempted`, `transcriptLines`, `lastCaptionAt`, -`lastCaptionSpeaker`, `lastCaptionText`, và một phần đuôi `recentTranscript` -ngắn để người vận hành biết liệu trình duyệt đã tham gia cuộc gọi hay chưa và -liệu phụ đề Meet có tạo văn bản hay không. +Với lượt tham gia chỉ quan sát/điều khiển trình duyệt, đặt `"mode": "transcribe"`. Điều đó +không khởi động cầu nối giọng nói thời gian thực song công, không yêu cầu BlackHole hoặc SoX, +và sẽ không nói phản hồi vào cuộc họp. Các lượt tham gia Chrome ở chế độ này cũng tránh +cấp quyền micrô/camera của OpenClaw và tránh đường dẫn **Dùng +micrô** của Meet. Nếu Meet hiển thị màn hình chọn âm thanh xen giữa, tự động hóa sẽ thử +đường dẫn không dùng micrô và nếu không được thì báo cáo một hành động thủ công thay vì mở +micrô cục bộ. Trong chế độ phiên âm, các phương thức truyền Chrome được quản lý cũng cài đặt +một trình quan sát phụ đề Meet theo khả năng tốt nhất. `googlemeet status --json` và +`googlemeet doctor` hiển thị `captioning`, `captionsEnabledAttempted`, +`transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText`, +và phần đuôi `recentTranscript` ngắn để người vận hành có thể biết liệu trình duyệt +đã tham gia cuộc gọi hay chưa và liệu phụ đề Meet có đang tạo văn bản hay không. Dùng `openclaw googlemeet test-listen --transport chrome-node` khi -bạn cần một phép dò có/không: nó tham gia ở chế độ transcribe, chờ phụ đề mới -hoặc chuyển động transcript mới, rồi trả về `listenVerified`, `listenTimedOut`, -các trường hành động thủ công, và tình trạng phụ đề mới nhất. +bạn cần một phép kiểm tra có/không: nó tham gia ở chế độ phiên âm, đợi phụ đề mới hoặc +chuyển động bản phiên âm mới, rồi trả về `listenVerified`, `listenTimedOut`, các trường +hành động thủ công và tình trạng phụ đề mới nhất. -Trong các phiên realtime, trạng thái `google_meet` bao gồm tình trạng trình duyệt -và cầu nối âm thanh như `inCall`, `manualActionRequired`, `providerConnected`, -`realtimeReady`, `audioInputActive`, `audioOutputActive`, dấu thời gian đầu -vào/đầu ra gần nhất, bộ đếm byte, và trạng thái cầu nối đã đóng. Nếu một lời nhắc -trang Meet an toàn xuất hiện, tự động hóa trình duyệt sẽ xử lý khi có thể. Lời -nhắc đăng nhập, chấp nhận của host, và quyền trình duyệt/HĐH được báo cáo là -hành động thủ công với lý do và thông điệp để tác nhân chuyển tiếp. Các phiên -Chrome được quản lý chỉ phát phần giới thiệu hoặc cụm từ kiểm thử sau khi tình -trạng trình duyệt báo cáo `inCall: true`; nếu không, trạng thái báo cáo -`speechReady: false` và nỗ lực phát lời nói bị chặn thay vì giả vờ rằng tác nhân -đã nói vào cuộc họp. +Trong các phiên thời gian thực, trạng thái `google_meet` bao gồm tình trạng trình duyệt và cầu nối âm thanh +như `inCall`, `manualActionRequired`, `providerConnected`, +`realtimeReady`, `audioInputActive`, `audioOutputActive`, dấu thời gian đầu vào/đầu ra +gần nhất, bộ đếm byte và trạng thái cầu nối đã đóng. Nếu một lời nhắc trang Meet an toàn +xuất hiện, tự động hóa trình duyệt sẽ xử lý khi có thể. Lời nhắc đăng nhập, chấp nhận của chủ trì và +quyền trình duyệt/HĐH được báo cáo là hành động thủ công kèm lý do và +thông báo để tác nhân chuyển tiếp. Các phiên Chrome được quản lý chỉ phát phần giới thiệu hoặc +cụm kiểm thử sau khi tình trạng trình duyệt báo cáo `inCall: true`; nếu không, trạng thái báo cáo +`speechReady: false` và lần thử nói bị chặn thay vì giả vờ rằng +tác nhân đã nói vào cuộc họp. -Các lượt tham gia Chrome cục bộ đi qua hồ sơ trình duyệt OpenClaw đã đăng nhập. -Chế độ realtime yêu cầu `BlackHole 2ch` cho đường dẫn microphone/loa mà OpenClaw -sử dụng. Để có âm thanh song công sạch, dùng các thiết bị ảo riêng biệt hoặc một -đồ thị kiểu Loopback; một thiết bị BlackHole duy nhất là đủ cho lần smoke test -đầu tiên nhưng có thể tạo tiếng vọng. +Các lượt tham gia Chrome cục bộ đi qua hồ sơ trình duyệt OpenClaw đã đăng nhập. Chế độ thời gian thực +yêu cầu `BlackHole 2ch` cho đường dẫn micrô/loa mà OpenClaw sử dụng. Để có +âm thanh song công sạch, dùng các thiết bị ảo riêng biệt hoặc đồ thị kiểu Loopback; một +thiết bị BlackHole duy nhất là đủ cho một bài kiểm thử khói đầu tiên nhưng có thể vọng âm. -### Gateway cục bộ + Parallels Chrome +### Gateway cục bộ + Chrome Parallels -Bạn **không** cần một OpenClaw Gateway đầy đủ hoặc khóa API mô hình bên trong VM -macOS chỉ để VM sở hữu Chrome. Chạy Gateway và tác nhân cục bộ, rồi chạy một node -host trong VM. Bật Plugin đi kèm trên VM một lần để node quảng bá lệnh Chrome: +Bạn **không** cần một OpenClaw Gateway đầy đủ hoặc khóa API mô hình bên trong VM macOS +chỉ để VM sở hữu Chrome. Chạy Gateway và tác nhân cục bộ, rồi chạy một +máy chủ Node trong VM. Bật Plugin đóng gói kèm trên VM một lần để Node +quảng bá lệnh Chrome: -Những gì chạy ở đâu: +Thành phần chạy ở đâu: -- Host Gateway: OpenClaw Gateway, workspace tác nhân, khóa model/API, nhà cung - cấp realtime, và cấu hình Plugin Google Meet. -- VM macOS Parallels: OpenClaw CLI/node host, Google Chrome, SoX, BlackHole 2ch, +- Máy chủ Gateway: OpenClaw Gateway, workspace tác nhân, khóa mô hình/API, nhà cung cấp thời gian thực, + và cấu hình Plugin Google Meet. +- VM macOS Parallels: OpenClaw CLI/máy chủ Node, Google Chrome, SoX, BlackHole 2ch, và một hồ sơ Chrome đã đăng nhập Google. -- Không cần trong VM: dịch vụ Gateway, cấu hình tác nhân, khóa OpenAI/GPT, hoặc - thiết lập nhà cung cấp mô hình. +- Không cần trong VM: dịch vụ Gateway, cấu hình tác nhân, khóa OpenAI/GPT, hoặc thiết lập + nhà cung cấp mô hình. Cài đặt các phụ thuộc VM: @@ -256,7 +253,7 @@ Cài đặt các phụ thuộc VM: brew install blackhole-2ch sox ``` -Khởi động lại VM sau khi cài BlackHole để macOS hiển thị `BlackHole 2ch`: +Khởi động lại VM sau khi cài đặt BlackHole để macOS hiển thị `BlackHole 2ch`: ```bash sudo reboot @@ -269,27 +266,27 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Cài đặt hoặc cập nhật OpenClaw trong VM, rồi bật Plugin đi kèm ở đó: +Cài đặt hoặc cập nhật OpenClaw trong VM, rồi bật Plugin đóng gói kèm tại đó: ```bash openclaw plugins enable google-meet ``` -Khởi động node host trong VM: +Khởi động máy chủ Node trong VM: ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -Nếu `` là IP LAN và bạn không dùng TLS, node sẽ từ chối WebSocket -plaintext trừ khi bạn chọn cho phép mạng riêng đáng tin cậy đó: +Nếu `` là IP LAN và bạn không dùng TLS, Node sẽ từ chối +WebSocket văn bản thuần trừ khi bạn chọn tham gia cho mạng riêng tin cậy đó: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Dùng cùng biến môi trường khi cài đặt node làm LaunchAgent: +Dùng cùng biến môi trường khi cài đặt Node làm LaunchAgent: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -297,25 +294,25 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` là môi trường tiến trình, không phải một -thiết lập `openclaw.json`. `openclaw node install` lưu nó trong môi trường +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` là môi trường tiến trình, không phải +cài đặt `openclaw.json`. `openclaw node install` lưu nó trong môi trường LaunchAgent khi nó hiện diện trên lệnh cài đặt. -Phê duyệt node từ host Gateway: +Phê duyệt Node từ máy chủ Gateway: ```bash openclaw devices list openclaw devices approve ``` -Xác nhận Gateway thấy node và node quảng bá cả `googlemeet.chrome` lẫn capability -trình duyệt/`browser.proxy`: +Xác nhận Gateway thấy Node và Node quảng bá cả `googlemeet.chrome` +lẫn năng lực trình duyệt/`browser.proxy`: ```bash openclaw nodes status ``` -Định tuyến Meet qua node đó trên host Gateway: +Định tuyến Meet qua Node đó trên máy chủ Gateway: ```json5 { @@ -345,7 +342,7 @@ openclaw nodes status } ``` -Bây giờ tham gia bình thường từ host Gateway: +Bây giờ tham gia bình thường từ máy chủ Gateway: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -353,105 +350,105 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij hoặc yêu cầu tác nhân dùng công cụ `google_meet` với `transport: "chrome-node"`. -Để smoke test bằng một lệnh nhằm tạo hoặc tái sử dụng một phiên, nói một cụm từ -đã biết, và in tình trạng phiên: +Để kiểm thử khói bằng một lệnh, tạo hoặc tái sử dụng một phiên, nói một +cụm từ đã biết và in tình trạng phiên: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Trong khi tham gia thời gian thực, tự động hóa trình duyệt OpenClaw điền tên khách, nhấp vào -Tham gia/Yêu cầu tham gia, và chấp nhận lựa chọn "Use microphone" trong lần chạy đầu của Meet khi -lời nhắc đó xuất hiện. Trong khi tham gia chỉ quan sát hoặc tạo cuộc họp chỉ bằng trình duyệt, nó -tiếp tục qua cùng lời nhắc đó mà không dùng micrô khi lựa chọn đó có sẵn. +Trong quá trình tham gia theo thời gian thực, tự động hóa trình duyệt của OpenClaw điền tên khách, nhấp +Join/Ask to join, và chấp nhận lựa chọn "Use microphone" trong lần chạy đầu tiên của Meet khi +lời nhắc đó xuất hiện. Trong quá trình tham gia chỉ quan sát hoặc tạo cuộc họp chỉ bằng trình duyệt, nó +tiếp tục vượt qua cùng lời nhắc đó mà không dùng micro khi lựa chọn đó có sẵn. Nếu hồ sơ trình duyệt chưa đăng nhập, Meet đang chờ chủ trì chấp nhận, -Chrome cần quyền micrô/camera để tham gia thời gian thực, hoặc Meet bị kẹt -ở một lời nhắc mà tự động hóa không thể xử lý, kết quả join/test-speech sẽ báo cáo +Chrome cần quyền micro/camera để tham gia theo thời gian thực, hoặc Meet bị kẹt +ở một lời nhắc mà tự động hóa không thể xử lý, kết quả tham gia/test-speech sẽ báo cáo `manualActionRequired: true` cùng với `manualActionReason` và -`manualActionMessage`. Agents nên ngừng thử tham gia lại, báo cáo đúng thông báo đó -kèm `browserUrl`/`browserTitle` hiện tại, và chỉ thử lại sau khi -thao tác thủ công trong trình duyệt đã hoàn tất. +`manualActionMessage`. Các tác nhân nên dừng thử lại việc tham gia, báo cáo chính xác +thông báo đó cùng với `browserUrl`/`browserTitle` hiện tại, và chỉ thử lại sau khi +thao tác thủ công trên trình duyệt đã hoàn tất. Nếu bỏ qua `chromeNode.node`, OpenClaw chỉ tự động chọn khi đúng một -Node đã kết nối quảng bá cả `googlemeet.chrome` và điều khiển trình duyệt. Nếu -nhiều Node có khả năng được kết nối, hãy đặt `chromeNode.node` thành id Node, +node đã kết nối quảng bá cả `googlemeet.chrome` lẫn điều khiển trình duyệt. Nếu +có nhiều node đủ khả năng đang kết nối, hãy đặt `chromeNode.node` thành id node, tên hiển thị, hoặc IP từ xa. Các kiểm tra lỗi thường gặp: -- `Configured Google Meet node ... is not usable: offline`: Node đã ghim được - Gateway biết đến nhưng không khả dụng. Agents nên xem Node đó là - trạng thái chẩn đoán, không phải Chrome host có thể dùng, và báo cáo yếu tố chặn - thiết lập thay vì chuyển sang transport khác, trừ khi người dùng yêu cầu như vậy. +- `Configured Google Meet node ... is not usable: offline`: node được ghim đã + được Gateway biết đến nhưng không khả dụng. Các tác nhân nên xem node đó là + trạng thái chẩn đoán, không phải máy chủ Chrome khả dụng, và báo cáo điểm chặn + thiết lập thay vì chuyển sang phương thức truyền tải khác trừ khi người dùng yêu cầu việc đó. - `No connected Google Meet-capable node`: khởi động `openclaw node run` trong VM, - chấp thuận ghép nối, và bảo đảm `openclaw plugins enable google-meet` và + chấp thuận ghép nối, và đảm bảo `openclaw plugins enable google-meet` và `openclaw plugins enable browser` đã được chạy trong VM. Đồng thời xác nhận - Gateway host cho phép cả hai lệnh Node bằng + máy chủ Gateway cho phép cả hai lệnh node bằng `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. -- `BlackHole 2ch audio device not found`: cài đặt `blackhole-2ch` trên host +- `BlackHole 2ch audio device not found`: cài đặt `blackhole-2ch` trên máy chủ đang được kiểm tra và khởi động lại trước khi dùng âm thanh Chrome cục bộ. - `BlackHole 2ch audio device not found on the node`: cài đặt `blackhole-2ch` trong VM và khởi động lại VM. - Chrome mở nhưng không thể tham gia: đăng nhập vào hồ sơ trình duyệt bên trong VM, hoặc giữ `chrome.guestName` được đặt để tham gia với tư cách khách. Tự động tham gia với tư cách khách dùng - tự động hóa trình duyệt OpenClaw qua proxy trình duyệt của Node; bảo đảm cấu hình - trình duyệt của Node trỏ đến hồ sơ bạn muốn, ví dụ - `browser.defaultProfile: "user"` hoặc một hồ sơ phiên hiện có có tên. -- Các tab Meet trùng lặp: giữ bật `chrome.reuseExistingTab: true`. OpenClaw - kích hoạt tab hiện có cho cùng URL Meet trước khi mở tab mới, và - việc tạo cuộc họp bằng trình duyệt tái sử dụng tab `https://meet.google.com/new` - hoặc tab lời nhắc tài khoản Google đang xử lý trước khi mở tab khác. -- Không có âm thanh: trong Meet, định tuyến micrô/loa qua đường dẫn thiết bị âm thanh ảo - mà OpenClaw dùng; dùng các thiết bị ảo riêng biệt hoặc định tuyến kiểu Loopback - để có âm thanh song công sạch. + tự động hóa trình duyệt OpenClaw thông qua proxy trình duyệt của node; hãy đảm bảo cấu hình + trình duyệt node trỏ tới hồ sơ bạn muốn, ví dụ + `browser.defaultProfile: "user"` hoặc một hồ sơ phiên hiện có được đặt tên. +- Các tab Meet trùng lặp: giữ `chrome.reuseExistingTab: true` được bật. OpenClaw + kích hoạt một tab hiện có cho cùng URL Meet trước khi mở tab mới, và + việc tạo cuộc họp bằng trình duyệt tái sử dụng một tab `https://meet.google.com/new` + đang xử lý hoặc tab lời nhắc tài khoản Google trước khi mở tab khác. +- Không có âm thanh: trong Meet, định tuyến micro/loa qua đường dẫn thiết bị âm thanh ảo + được OpenClaw sử dụng; dùng các thiết bị ảo riêng biệt hoặc định tuyến kiểu Loopback + để có âm thanh hai chiều sạch. ## Ghi chú cài đặt -Mặc định thời gian thực của Chrome dùng hai công cụ bên ngoài: +Mặc định phản hồi âm thanh của Chrome dùng hai công cụ bên ngoài: - `sox`: tiện ích âm thanh dòng lệnh. Plugin dùng các lệnh thiết bị CoreAudio - tường minh cho cầu nối âm thanh PCM16 24 kHz mặc định. + tường minh cho cầu âm thanh PCM16 24 kHz mặc định. - `blackhole-2ch`: trình điều khiển âm thanh ảo macOS. Nó tạo thiết bị âm thanh `BlackHole 2ch` mà Chrome/Meet có thể định tuyến qua. -OpenClaw không đóng gói hoặc phân phối lại bất kỳ gói nào trong hai gói này. Tài liệu yêu cầu người dùng -cài đặt chúng dưới dạng phụ thuộc host thông qua Homebrew. SoX được cấp phép theo +OpenClaw không đóng gói hoặc phân phối lại bất kỳ gói nào trong hai gói đó. Tài liệu yêu cầu người dùng +cài đặt chúng làm phụ thuộc máy chủ thông qua Homebrew. SoX được cấp phép theo `LGPL-2.0-only AND GPL-2.0-only`; BlackHole là GPL-3.0. Nếu bạn xây dựng -trình cài đặt hoặc appliance đóng gói BlackHole cùng OpenClaw, hãy xem lại các điều khoản -cấp phép thượng nguồn của BlackHole hoặc lấy giấy phép riêng từ Existential Audio. +trình cài đặt hoặc appliance đóng gói BlackHole cùng với OpenClaw, hãy xem lại các điều khoản +cấp phép upstream của BlackHole hoặc lấy giấy phép riêng từ Existential Audio. -## Transports +## Phương thức truyền tải ### Chrome -Chrome transport mở URL Meet thông qua điều khiển trình duyệt OpenClaw và tham gia +Phương thức truyền tải Chrome mở URL Meet thông qua điều khiển trình duyệt OpenClaw và tham gia bằng hồ sơ trình duyệt OpenClaw đã đăng nhập. Trên macOS, Plugin kiểm tra -`BlackHole 2ch` trước khi khởi chạy. Nếu được cấu hình, nó cũng chạy lệnh -kiểm tra sức khỏe cầu nối âm thanh và lệnh khởi động trước khi mở Chrome. Dùng `chrome` khi -Chrome/âm thanh nằm trên Gateway host; dùng `chrome-node` khi Chrome/âm thanh nằm -trên một Node đã ghép nối, chẳng hạn VM Parallels macOS. Với Chrome cục bộ, chọn +`BlackHole 2ch` trước khi khởi chạy. Nếu được cấu hình, nó cũng chạy một lệnh +kiểm tra sức khỏe cầu âm thanh và lệnh khởi động trước khi mở Chrome. Dùng `chrome` khi +Chrome/âm thanh nằm trên máy chủ Gateway; dùng `chrome-node` khi Chrome/âm thanh nằm +trên một node đã ghép nối như VM macOS Parallels. Với Chrome cục bộ, chọn hồ sơ bằng `browser.defaultProfile`; `chrome.browserProfile` được truyền cho -các host `chrome-node`. +máy chủ `chrome-node`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Định tuyến âm thanh micrô và loa Chrome qua cầu nối âm thanh OpenClaw cục bộ. -Nếu `BlackHole 2ch` chưa được cài đặt, thao tác tham gia thất bại với lỗi thiết lập +Định tuyến âm thanh micro và loa Chrome qua cầu âm thanh OpenClaw cục bộ. +Nếu `BlackHole 2ch` chưa được cài đặt, việc tham gia sẽ thất bại với lỗi thiết lập thay vì âm thầm tham gia mà không có đường dẫn âm thanh. ### Twilio -Twilio transport là một kế hoạch quay số nghiêm ngặt được ủy quyền cho Plugin Voice Call. Nó -không phân tích trang Meet để tìm số điện thoại. +Phương thức truyền tải Twilio là một kế hoạch gọi nghiêm ngặt được ủy quyền cho Plugin Voice Call. Nó +không phân tích các trang Meet để tìm số điện thoại. -Dùng cách này khi không thể tham gia bằng Chrome hoặc bạn muốn một phương án dự phòng -gọi điện vào. Google Meet phải cung cấp số gọi điện vào và PIN cho +Dùng phương thức này khi không thể tham gia bằng Chrome hoặc bạn muốn phương án dự phòng +quay số điện thoại. Google Meet phải hiển thị số điện thoại quay vào và PIN cho cuộc họp; OpenClaw không phát hiện những thông tin đó từ trang Meet. -Bật Plugin Voice Call trên Gateway host, không phải trên Chrome Node: +Bật Plugin Voice Call trên máy chủ Gateway, không phải trên node Chrome: ```json5 { @@ -476,8 +473,8 @@ Bật Plugin Voice Call trên Gateway host, không phải trên Chrome Node: } ``` -Cung cấp thông tin xác thực Twilio thông qua môi trường hoặc cấu hình. Môi trường giúp -giữ bí mật khỏi `openclaw.json`: +Cung cấp thông tin xác thực Twilio qua môi trường hoặc cấu hình. Môi trường giữ +bí mật nằm ngoài `openclaw.json`: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -486,7 +483,7 @@ export TWILIO_FROM_NUMBER=+15550001234 ``` Khởi động lại hoặc tải lại Gateway sau khi bật `voice-call`; các thay đổi cấu hình Plugin -không xuất hiện trong tiến trình Gateway đang chạy cho đến khi nó tải lại. +không xuất hiện trong một tiến trình Gateway đã chạy cho tới khi nó tải lại. Sau đó xác minh: @@ -516,34 +513,33 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth và preflight +## OAuth và kiểm tra trước -OAuth là tùy chọn khi tạo liên kết Meet vì `googlemeet create` có thể dùng -tự động hóa trình duyệt làm phương án dự phòng. Cấu hình OAuth khi bạn muốn tạo bằng API chính thức, -phân giải space, hoặc kiểm tra preflight Meet Media API. +OAuth là tùy chọn khi tạo liên kết Meet vì `googlemeet create` có thể dự phòng +sang tự động hóa trình duyệt. Cấu hình OAuth khi bạn muốn tạo bằng API chính thức, +phân giải space, hoặc kiểm tra trước Meet Media API. Quyền truy cập Google Meet API dùng OAuth người dùng: tạo một Google Cloud OAuth client, -yêu cầu các scope cần thiết, cấp quyền cho một tài khoản Google, rồi lưu +yêu cầu các phạm vi cần thiết, ủy quyền một tài khoản Google, rồi lưu refresh token thu được trong cấu hình Plugin Google Meet hoặc cung cấp các biến môi trường `OPENCLAW_GOOGLE_MEET_*`. -OAuth không thay thế đường dẫn tham gia bằng Chrome. Chrome và Chrome-node transports -vẫn tham gia thông qua một hồ sơ Chrome đã đăng nhập, BlackHole/SoX, và một -Node đã kết nối khi bạn dùng tham gia bằng trình duyệt. OAuth chỉ dành cho đường dẫn -Google Meet API chính thức: tạo meeting spaces, phân giải spaces, và chạy các kiểm tra -preflight Meet Media API. +OAuth không thay thế đường dẫn tham gia bằng Chrome. Các phương thức truyền tải Chrome và Chrome-node +vẫn tham gia thông qua hồ sơ Chrome đã đăng nhập, BlackHole/SoX, và một node đã kết nối +khi bạn dùng tham gia bằng trình duyệt. OAuth chỉ dành cho đường dẫn Google Meet API +chính thức: tạo các space cuộc họp, phân giải space, và chạy kiểm tra trước Meet Media API. ### Tạo thông tin xác thực Google Trong Google Cloud Console: -1. Tạo hoặc chọn một Google Cloud project. -2. Bật **Google Meet REST API** cho project đó. +1. Tạo hoặc chọn một dự án Google Cloud. +2. Bật **Google Meet REST API** cho dự án đó. 3. Cấu hình màn hình đồng ý OAuth. - **Internal** là đơn giản nhất cho một tổ chức Google Workspace. - - **External** hoạt động cho thiết lập cá nhân/thử nghiệm; khi ứng dụng ở trạng thái Testing, - hãy thêm từng tài khoản Google sẽ cấp quyền cho ứng dụng làm người dùng thử nghiệm. -4. Thêm các scope OpenClaw yêu cầu: + - **External** hoạt động cho các thiết lập cá nhân/thử nghiệm; khi ứng dụng đang ở Testing, + thêm từng tài khoản Google sẽ ủy quyền ứng dụng làm người dùng thử nghiệm. +4. Thêm các phạm vi OpenClaw yêu cầu: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.space.settings` @@ -559,24 +555,24 @@ Trong Google Cloud Console: 6. Sao chép client ID và client secret. `meetings.space.created` là bắt buộc đối với Google Meet `spaces.create`. -`meetings.space.readonly` cho phép OpenClaw phân giải URL/mã Meet thành spaces. +`meetings.space.readonly` cho phép OpenClaw phân giải URL/mã Meet thành space. `meetings.space.settings` cho phép OpenClaw truyền các thiết lập `SpaceConfig` như `accessType` trong quá trình tạo phòng bằng API. -`meetings.conference.media.readonly` dành cho preflight Meet Media API và công việc +`meetings.conference.media.readonly` dành cho kiểm tra trước Meet Media API và công việc media; Google có thể yêu cầu đăng ký Developer Preview để sử dụng Media API thực tế. -Nếu bạn chỉ cần tham gia Chrome dựa trên trình duyệt, hãy bỏ qua OAuth hoàn toàn. +Nếu bạn chỉ cần tham gia bằng Chrome dựa trên trình duyệt, hãy bỏ qua OAuth hoàn toàn. ### Tạo refresh token -Cấu hình `oauth.clientId` và tùy chọn `oauth.clientSecret`, hoặc truyền chúng dưới dạng +Cấu hình `oauth.clientId` và tùy chọn `oauth.clientSecret`, hoặc truyền chúng làm biến môi trường, rồi chạy: ```bash openclaw googlemeet auth login --json ``` -Lệnh in ra một khối cấu hình `oauth` với refresh token. Nó dùng PKCE, -callback localhost tại `http://localhost:8085/oauth2callback`, và luồng +Lệnh in ra một khối cấu hình `oauth` có refresh token. Nó dùng PKCE, +callback localhost tại `http://localhost:8085/oauth2callback`, và một luồng sao chép/dán thủ công với `--manual`. Ví dụ: @@ -587,7 +583,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -Dùng chế độ thủ công khi trình duyệt không thể truy cập callback cục bộ: +Dùng chế độ thủ công khi trình duyệt không thể tới callback cục bộ: ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -633,24 +629,24 @@ Lưu đối tượng `oauth` dưới cấu hình Plugin Google Meet: Ưu tiên biến môi trường khi bạn không muốn refresh token nằm trong cấu hình. Nếu cả giá trị cấu hình và môi trường đều có mặt, Plugin phân giải cấu hình -trước rồi mới dùng môi trường làm dự phòng. +trước rồi mới dự phòng sang môi trường. -Sự đồng ý OAuth bao gồm tạo Meet space, quyền đọc Meet space, và quyền đọc -media hội nghị Meet. Nếu bạn đã xác thực trước khi có hỗ trợ tạo cuộc họp, -hãy chạy lại `openclaw googlemeet auth login --json` để refresh token có -scope `meetings.space.created`. +Đồng ý OAuth bao gồm tạo space Meet, quyền đọc space Meet, và quyền đọc media +hội nghị Meet. Nếu bạn đã xác thực trước khi hỗ trợ tạo cuộc họp +tồn tại, hãy chạy lại `openclaw googlemeet auth login --json` để refresh +token có phạm vi `meetings.space.created`. ### Xác minh OAuth bằng doctor -Chạy OAuth doctor khi bạn muốn một kiểm tra sức khỏe nhanh, không lộ bí mật: +Chạy doctor OAuth khi bạn muốn một kiểm tra sức khỏe nhanh, không chứa bí mật: ```bash openclaw googlemeet doctor --oauth --json ``` -Lệnh này không tải Chrome runtime hoặc yêu cầu Chrome Node đã kết nối. Nó -kiểm tra cấu hình OAuth tồn tại và refresh token có thể tạo access token. -Báo cáo JSON chỉ bao gồm các trường trạng thái như `ok`, `configured`, +Việc này không tải runtime Chrome hoặc yêu cầu một node Chrome đã kết nối. Nó +kiểm tra rằng cấu hình OAuth tồn tại và refresh token có thể tạo access +token. Báo cáo JSON chỉ bao gồm các trường trạng thái như `ok`, `configured`, `tokenSource`, `expiresAt`, và thông báo kiểm tra; nó không in access token, refresh token, hoặc client secret. @@ -658,12 +654,12 @@ Kết quả thường gặp: | Kiểm tra | Ý nghĩa | | -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | Có `oauth.clientId` cộng với `oauth.refreshToken`, hoặc access token đã lưu cache. | -| `oauth-token` | Access token đã lưu cache vẫn hợp lệ, hoặc refresh token đã tạo access token mới. | -| `meet-spaces-get` | Kiểm tra tùy chọn `--meeting` đã phân giải một Meet space hiện có. | -| `meet-spaces-create` | Kiểm tra tùy chọn `--create-space` đã tạo một Meet space mới. | +| `oauth-config` | Có `oauth.clientId` cộng với `oauth.refreshToken`, hoặc một access token được lưu đệm. | +| `oauth-token` | Access token được lưu đệm vẫn hợp lệ, hoặc refresh token đã tạo một access token mới. | +| `meet-spaces-get` | Kiểm tra `--meeting` tùy chọn đã phân giải một space Meet hiện có. | +| `meet-spaces-create` | Kiểm tra `--create-space` tùy chọn đã tạo một space Meet mới. | -Để chứng minh cả việc bật Google Meet API và scope `spaces.create`, hãy chạy +Để chứng minh cả việc bật Google Meet API và phạm vi `spaces.create`, hãy chạy kiểm tra tạo có tác dụng phụ: ```bash @@ -671,29 +667,29 @@ openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` tạo một URL Meet dùng một lần. Dùng nó khi bạn cần xác nhận +`--create-space` tạo một URL Meet tạm thời. Dùng nó khi bạn cần xác nhận rằng dự án Google Cloud đã bật Meet API và tài khoản được ủy quyền có phạm vi `meetings.space.created`. -Để chứng minh quyền đọc cho một không gian họp hiện có: +Để chứng minh quyền đọc cho một không gian cuộc họp hiện có: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` và `resolve-space` chứng minh quyền đọc với một +`doctor --oauth --meeting` và `resolve-space` chứng minh quyền đọc đối với một không gian hiện có mà tài khoản Google được ủy quyền có thể truy cập. Lỗi `403` -từ các kiểm tra này thường nghĩa là Google Meet REST API bị tắt, refresh token -đã đồng ý thiếu phạm vi bắt buộc, hoặc tài khoản Google không thể truy cập -không gian Meet đó. Lỗi refresh-token nghĩa là chạy lại `openclaw googlemeet auth login +từ các bước kiểm tra này thường có nghĩa là Google Meet REST API bị tắt, refresh +token đã chấp thuận thiếu phạm vi bắt buộc, hoặc tài khoản Google không thể truy +cập không gian Meet đó. Lỗi refresh token có nghĩa là chạy lại `openclaw googlemeet auth login --json` và lưu khối `oauth` mới. -Không cần thông tin xác thực OAuth cho phương án dự phòng trình duyệt. Ở chế độ -đó, xác thực Google đến từ hồ sơ Chrome đã đăng nhập trên node đã chọn, không -phải từ cấu hình OpenClaw. +Không cần thông tin xác thực OAuth cho phương án dự phòng bằng trình duyệt. Ở +chế độ đó, xác thực Google đến từ hồ sơ Chrome đã đăng nhập trên node đã chọn, +không phải từ cấu hình OpenClaw. -Các biến môi trường này được chấp nhận làm phương án dự phòng: +Các biến môi trường này được chấp nhận làm giá trị dự phòng: - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` hoặc `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` hoặc `GOOGLE_MEET_CLIENT_SECRET` @@ -710,13 +706,13 @@ Phân giải một URL Meet, mã, hoặc `spaces/{id}` thông qua `spaces.get`: openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -Chạy kiểm tra trước trước khi làm việc với phương tiện: +Chạy kiểm tra trước khi làm việc với phương tiện: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Liệt kê hiện vật cuộc họp và điểm danh sau khi Meet đã tạo bản ghi hội nghị: +Liệt kê các tạo tác cuộc họp và điểm danh sau khi Meet đã tạo bản ghi hội nghị: ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -724,12 +720,12 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -Với `--meeting`, `artifacts` và `attendance` dùng bản ghi hội nghị mới nhất theo -mặc định. Truyền `--all-conference-records` khi bạn muốn mọi bản ghi còn được -lưu giữ cho cuộc họp đó. +Với `--meeting`, `artifacts` và `attendance` mặc định dùng bản ghi hội nghị mới +nhất. Truyền `--all-conference-records` khi bạn muốn mọi bản ghi còn được lưu +giữ cho cuộc họp đó. -Tra cứu lịch có thể phân giải URL cuộc họp từ Google Calendar trước khi đọc -hiện vật Meet: +Tra cứu Calendar có thể phân giải URL cuộc họp từ Google Calendar trước khi đọc +các tạo tác Meet: ```bash openclaw googlemeet latest --today @@ -738,14 +734,14 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` tìm kiếm lịch `primary` của hôm nay để tìm một sự kiện Calendar có -liên kết Google Meet. Dùng `--event ` để tìm kiếm văn bản sự kiện khớp, và -`--calendar ` cho lịch không phải lịch chính. Tra cứu lịch yêu cầu đăng nhập -OAuth mới có bao gồm phạm vi chỉ đọc sự kiện Calendar. +`--today` tìm trong lịch `primary` của hôm nay một sự kiện Calendar có liên kết +Google Meet. Dùng `--event ` để tìm văn bản sự kiện khớp, và +`--calendar ` cho lịch không phải lịch chính. Tra cứu Calendar yêu cầu đăng +nhập OAuth mới có bao gồm phạm vi chỉ đọc sự kiện Calendar. `calendar-events` xem trước các sự kiện Meet khớp và đánh dấu sự kiện mà `latest`, `artifacts`, `attendance`, hoặc `export` sẽ chọn. -Nếu bạn đã biết id bản ghi hội nghị, hãy chỉ định trực tiếp: +Nếu bạn đã biết id bản ghi hội nghị, hãy truy cập trực tiếp: ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -760,16 +756,16 @@ phòng sau cuộc gọi: openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -Lệnh này gọi Google Meet `spaces.endActiveConference` và yêu cầu OAuth với phạm vi -`meetings.space.created` cho một không gian mà tài khoản được ủy quyền có thể -quản lý. OpenClaw chấp nhận đầu vào là URL Meet, mã cuộc họp, hoặc `spaces/{id}` -và phân giải nó thành tài nguyên không gian API trước khi kết thúc hội nghị đang +Lệnh này gọi Google Meet `spaces.endActiveConference` và yêu cầu OAuth với phạm +vi `meetings.space.created` cho một không gian mà tài khoản được ủy quyền có thể +quản lý. OpenClaw chấp nhận URL Meet, mã cuộc họp, hoặc đầu vào `spaces/{id}` và +phân giải nó thành tài nguyên không gian API trước khi kết thúc hội nghị đang hoạt động. Nó tách biệt với `googlemeet leave`: `leave` dừng việc tham gia cục bộ/phiên của OpenClaw, còn `end-active-conference` yêu cầu Google Meet kết thúc hội nghị đang hoạt động cho không gian. -Ghi một báo cáo dễ đọc: +Viết một báo cáo dễ đọc: ```bash openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \ @@ -784,9 +780,9 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -`artifacts` trả về siêu dữ liệu bản ghi hội nghị cùng siêu dữ liệu tài nguyên về -người tham gia, bản ghi, bản chép lời, mục bản chép lời có cấu trúc và ghi chú -thông minh khi Google cung cấp chúng cho cuộc họp. Dùng `--no-transcript-entries` +`artifacts` trả về siêu dữ liệu bản ghi hội nghị cùng siêu dữ liệu tài nguyên +người tham gia, bản ghi âm, bản chép lời, mục bản chép lời có cấu trúc, và ghi +chú thông minh khi Google cung cấp cho cuộc họp. Dùng `--no-transcript-entries` để bỏ qua tra cứu mục cho các cuộc họp lớn. `attendance` mở rộng người tham gia thành các hàng phiên người tham gia với thời điểm thấy lần đầu/lần cuối, tổng thời lượng phiên, cờ đến muộn/rời sớm, và các tài nguyên người tham gia trùng @@ -795,23 +791,23 @@ lặp được hợp nhất theo người dùng đã đăng nhập hoặc tên h `--late-after-minutes` để điều chỉnh phát hiện đến muộn, và `--early-before-minutes` để điều chỉnh phát hiện rời sớm. -`export` ghi một thư mục chứa `summary.md`, `attendance.csv`, `transcript.md`, -`artifacts.json`, `attendance.json`, và `manifest.json`. -`manifest.json` ghi lại đầu vào đã chọn, tùy chọn xuất, bản ghi hội nghị, tệp đầu -ra, số lượng, nguồn token, sự kiện Calendar khi có dùng, và mọi cảnh báo truy -xuất một phần. Truyền `--zip` để cũng ghi một kho lưu trữ di động bên cạnh thư -mục. Truyền `--include-doc-bodies` để xuất văn bản Google Docs của bản chép lời -và ghi chú thông minh được liên kết thông qua Google Drive `files.export`; việc -này yêu cầu đăng nhập OAuth mới có bao gồm phạm vi chỉ đọc Drive Meet. Không có -`--include-doc-bodies`, các bản xuất chỉ bao gồm siêu dữ liệu Meet và các mục bản -chép lời có cấu trúc. Nếu Google trả về lỗi hiện vật một phần, chẳng hạn lỗi liệt -kê ghi chú thông minh, mục bản chép lời, hoặc thân tài liệu Drive, phần tóm tắt -và manifest giữ cảnh báo thay vì làm hỏng toàn bộ bản xuất. -Dùng `--dry-run` để lấy cùng dữ liệu hiện vật/điểm danh và in JSON manifest mà +`export` ghi một thư mục chứa `summary.md`, `attendance.csv`, +`transcript.md`, `artifacts.json`, `attendance.json`, và `manifest.json`. +`manifest.json` ghi lại đầu vào đã chọn, tùy chọn xuất, bản ghi hội nghị, +tệp đầu ra, số lượng, nguồn token, sự kiện Calendar khi có sử dụng, và mọi cảnh +báo truy xuất một phần. Truyền `--zip` để cũng ghi một kho lưu trữ di động cạnh +thư mục. Truyền `--include-doc-bodies` để xuất văn bản Google Docs của bản chép +lời và ghi chú thông minh được liên kết thông qua Google Drive `files.export`; +việc này yêu cầu đăng nhập OAuth mới có bao gồm phạm vi chỉ đọc Drive Meet. +Không có `--include-doc-bodies`, bản xuất chỉ bao gồm siêu dữ liệu Meet và các +mục bản chép lời có cấu trúc. Nếu Google trả về lỗi tạo tác một phần, chẳng hạn +lỗi liệt kê ghi chú thông minh, mục bản chép lời, hoặc nội dung tài liệu Drive, +phần tóm tắt và manifest giữ lại cảnh báo thay vì làm hỏng toàn bộ bản xuất. +Dùng `--dry-run` để lấy cùng dữ liệu tạo tác/điểm danh và in JSON manifest mà không tạo thư mục hoặc ZIP. Điều đó hữu ích trước khi ghi một bản xuất lớn hoặc -khi một tác nhân chỉ cần số lượng, bản ghi đã chọn và cảnh báo. +khi một agent chỉ cần số lượng, bản ghi đã chọn, và cảnh báo. -Tác nhân cũng có thể tạo cùng gói thông qua công cụ `google_meet`: +Agent cũng có thể tạo cùng gói thông qua công cụ `google_meet`: ```json { @@ -825,7 +821,7 @@ Tác nhân cũng có thể tạo cùng gói thông qua công cụ `google_meet`: Đặt `"dryRun": true` để chỉ trả về manifest xuất và bỏ qua ghi tệp. -Tác nhân cũng có thể tạo một phòng được API hỗ trợ với chính sách truy cập rõ ràng: +Agent cũng có thể tạo một phòng được API hỗ trợ với chính sách truy cập rõ ràng: ```json { @@ -845,8 +841,8 @@ Và chúng có thể kết thúc hội nghị đang hoạt động cho một ph } ``` -Để xác thực nghe trước, tác nhân nên dùng `test_listen` trước khi tuyên bố cuộc -họp hữu ích: +Để xác thực nghe trước, agent nên dùng `test_listen` trước khi tuyên bố cuộc họp +là hữu ích: ```json { @@ -857,7 +853,7 @@ họp hữu ích: } ``` -Chạy kiểm tra khói trực tiếp có bảo vệ với một cuộc họp thật còn được lưu giữ: +Chạy smoke trực tiếp có bảo vệ với một cuộc họp thật còn được lưu giữ: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -865,33 +861,33 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Chạy phép thăm dò trình duyệt nghe trước trực tiếp với một cuộc họp nơi có người -sẽ nói và phụ đề Meet khả dụng: +Chạy thăm dò trình duyệt nghe trước trực tiếp với một cuộc họp nơi có người sẽ +nói và phụ đề Meet có sẵn: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -Môi trường kiểm tra khói trực tiếp: +Môi trường smoke trực tiếp: -- `OPENCLAW_LIVE_TEST=1` bật các kiểm thử trực tiếp có bảo vệ. -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` trỏ đến URL Meet, mã, hoặc +- `OPENCLAW_LIVE_TEST=1` bật các bài kiểm thử trực tiếp có bảo vệ. +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` trỏ đến một URL Meet, mã, hoặc `spaces/{id}` còn được lưu giữ. -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` hoặc `GOOGLE_MEET_CLIENT_ID` cung cấp id ứng - dụng OAuth. +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` hoặc `GOOGLE_MEET_CLIENT_ID` cung cấp id máy + khách OAuth. - `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` hoặc `GOOGLE_MEET_REFRESH_TOKEN` cung cấp refresh token. - Tùy chọn: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`, `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN`, và - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` dùng cùng tên dự phòng + `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` dùng các tên dự phòng tương tự không có tiền tố `OPENCLAW_`. -Kiểm tra khói trực tiếp hiện vật/điểm danh cơ sở cần +Smoke trực tiếp tạo tác/điểm danh cơ bản cần `https://www.googleapis.com/auth/meetings.space.readonly` và `https://www.googleapis.com/auth/meetings.conference.media.readonly`. Tra cứu Calendar cần `https://www.googleapis.com/auth/calendar.events.readonly`. Xuất -thân tài liệu Drive cần +nội dung tài liệu Drive cần `https://www.googleapis.com/auth/drive.meet.readonly`. Tạo một không gian Meet mới: @@ -900,13 +896,13 @@ Tạo một không gian Meet mới: openclaw googlemeet create ``` -Lệnh in ra `meeting uri` mới, nguồn và phiên tham gia. Với thông tin xác thực -OAuth, nó dùng Google Meet API chính thức. Không có thông tin xác thực OAuth, nó -dùng hồ sơ trình duyệt đã đăng nhập của node Chrome được ghim làm phương án dự -phòng. Tác nhân có thể dùng công cụ `google_meet` với `action: "create"` để tạo +Lệnh in `meeting uri` mới, nguồn, và phiên tham gia. Với thông tin xác thực +OAuth, lệnh dùng Google Meet API chính thức. Không có thông tin xác thực OAuth, +lệnh dùng hồ sơ trình duyệt đã đăng nhập của node Chrome được ghim làm phương án +dự phòng. Agent có thể dùng công cụ `google_meet` với `action: "create"` để tạo và tham gia trong một bước. Để chỉ tạo URL, truyền `"join": false`. -Ví dụ đầu ra JSON từ phương án dự phòng trình duyệt: +Ví dụ đầu ra JSON từ phương án dự phòng bằng trình duyệt: ```json { @@ -926,9 +922,9 @@ Ví dụ đầu ra JSON từ phương án dự phòng trình duyệt: } ``` -Nếu phương án dự phòng trình duyệt gặp đăng nhập Google hoặc chặn quyền Meet -trước khi có thể tạo URL, phương thức Gateway trả về phản hồi thất bại và công -cụ `google_meet` trả về chi tiết có cấu trúc thay vì một chuỗi thuần: +Nếu phương án dự phòng bằng trình duyệt gặp chặn đăng nhập Google hoặc quyền +Meet trước khi có thể tạo URL, phương thức Gateway trả về phản hồi thất bại và +công cụ `google_meet` trả về chi tiết có cấu trúc thay vì một chuỗi thuần: ```json { @@ -946,11 +942,11 @@ cụ `google_meet` trả về chi tiết có cấu trúc thay vì một chuỗi } ``` -Khi một tác nhân thấy `manualActionRequired: true`, nó nên báo cáo -`manualActionMessage` cùng ngữ cảnh node/tab trình duyệt và dừng mở tab Meet mới -cho đến khi người vận hành hoàn tất bước trên trình duyệt. +Khi agent thấy `manualActionRequired: true`, nó nên báo cáo +`manualActionMessage` cùng ngữ cảnh node/tab trình duyệt và ngừng mở tab Meet mới +cho đến khi người vận hành hoàn tất bước trong trình duyệt. -Ví dụ đầu ra JSON từ tạo bằng API: +Ví dụ đầu ra JSON từ tạo qua API: ```json { @@ -971,21 +967,22 @@ Ví dụ đầu ra JSON từ tạo bằng API: } ``` -Tạo Meet sẽ tham gia theo mặc định. Phương thức vận chuyển Chrome hoặc Chrome-node -vẫn cần một hồ sơ Google Chrome đã đăng nhập để tham gia qua trình duyệt. Nếu hồ -sơ đã đăng xuất, OpenClaw báo cáo `manualActionRequired: true` hoặc lỗi phương án -dự phòng trình duyệt và yêu cầu người vận hành hoàn tất đăng nhập Google trước -khi thử lại. +Theo mặc định, tạo một Meet sẽ tham gia. Transport Chrome hoặc Chrome-node vẫn +cần một hồ sơ Google Chrome đã đăng nhập để tham gia qua trình duyệt. Nếu hồ sơ +đã đăng xuất, OpenClaw báo cáo `manualActionRequired: true` hoặc một lỗi phương +án dự phòng bằng trình duyệt và yêu cầu người vận hành hoàn tất đăng nhập Google +trước khi thử lại. Chỉ đặt `preview.enrollmentAcknowledged: true` sau khi xác nhận dự án Cloud, -OAuth principal, và người tham gia cuộc họp của bạn đã ghi danh vào Google -Workspace Developer Preview Program cho Meet media APIs. +chủ thể OAuth, và người tham gia cuộc họp của bạn đã đăng ký Google Workspace +Developer Preview Program cho Meet media APIs. ## Cấu hình -Đường dẫn Chrome realtime phổ biến chỉ cần bật Plugin, BlackHole, SoX, và khóa -nhà cung cấp giọng nói realtime phía sau. OpenAI là mặc định; đặt -`realtime.provider: "google"` để dùng Google Gemini Live: +Đường dẫn agent Chrome phổ biến chỉ cần Plugin được bật, BlackHole, SoX, khóa +nhà cung cấp chép lời thời gian thực, và một nhà cung cấp OpenClaw TTS đã cấu +hình. OpenAI là nhà cung cấp chép lời mặc định; đặt `realtime.provider: "google"` +để dùng Google Gemini Live cho chế độ `bidi`: ```bash brew install blackhole-2ch sox @@ -994,7 +991,7 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -Đặt cấu hình Plugin dưới `plugins.entries.google-meet.config`: +Đặt cấu hình Plugin trong `plugins.entries.google-meet.config`: ```json5 { @@ -1012,27 +1009,53 @@ export GEMINI_API_KEY=... Mặc định: - `defaultTransport: "chrome"` -- `defaultMode: "realtime"` +- `defaultMode: "agent"` (`"realtime"` được chấp nhận làm bí danh tương thích cho + `"agent"`) - `chromeNode.node`: id/tên/IP Node tùy chọn cho `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: tên được dùng trên màn hình khách Meet chưa đăng nhập -- `chrome.autoJoin: true`: cố gắng tự động điền tên khách và nhấp Join Now thông qua tự động hóa trình duyệt OpenClaw trên `chrome-node` -- `chrome.reuseExistingTab: true`: kích hoạt một thẻ Meet hiện có thay vì mở các thẻ trùng lặp -- `chrome.waitForInCallMs: 20000`: chờ thẻ Meet báo đang trong cuộc gọi trước khi kích hoạt lời giới thiệu realtime -- `chrome.audioFormat: "pcm16-24khz"`: định dạng âm thanh cặp lệnh. Chỉ dùng `"g711-ulaw-8khz"` cho các cặp lệnh cũ/tùy chỉnh vẫn phát âm thanh điện thoại. -- `chrome.audioInputCommand`: lệnh SoX đọc từ CoreAudio `BlackHole 2ch` và ghi âm thanh theo `chrome.audioFormat` -- `chrome.audioOutputCommand`: lệnh SoX đọc âm thanh theo `chrome.audioFormat` và ghi vào CoreAudio `BlackHole 2ch` -- `chrome.bargeInInputCommand`: lệnh micro cục bộ tùy chọn ghi PCM mono little-endian 16-bit có dấu để phát hiện người dùng chen lời trong khi phát âm thanh của trợ lý. Hiện tại mục này áp dụng cho cầu nối cặp lệnh `chrome` do Gateway lưu trữ. -- `chrome.bargeInRmsThreshold: 650`: mức RMS được tính là một lần ngắt lời của người dùng trên `chrome.bargeInInputCommand` -- `chrome.bargeInPeakThreshold: 2500`: mức đỉnh được tính là một lần ngắt lời của người dùng trên `chrome.bargeInInputCommand` -- `chrome.bargeInCooldownMs: 900`: độ trễ tối thiểu giữa các lần xóa ngắt lời lặp lại của người dùng -- `realtime.provider: "openai"` +- `chrome.guestName: "OpenClaw Agent"`: tên dùng trên màn hình khách Meet khi chưa đăng nhập +- `chrome.autoJoin: true`: điền tên khách và nhấp Tham gia ngay ở mức cố gắng tối đa + thông qua tự động hóa trình duyệt OpenClaw trên `chrome-node` +- `chrome.reuseExistingTab: true`: kích hoạt thẻ Meet hiện có thay vì + mở các thẻ trùng lặp +- `chrome.waitForInCallMs: 20000`: chờ thẻ Meet báo đang trong cuộc gọi + trước khi phần giới thiệu realtime được kích hoạt +- `chrome.audioFormat: "pcm16-24khz"`: định dạng âm thanh cặp lệnh. Chỉ dùng + `"g711-ulaw-8khz"` cho các cặp lệnh cũ/tùy chỉnh vẫn phát + âm thanh điện thoại. +- `chrome.audioInputCommand`: lệnh SoX đọc từ CoreAudio `BlackHole 2ch` + và ghi âm thanh ở `chrome.audioFormat` +- `chrome.audioOutputCommand`: lệnh SoX đọc âm thanh ở `chrome.audioFormat` + và ghi vào CoreAudio `BlackHole 2ch` +- `chrome.bargeInInputCommand`: lệnh micrô cục bộ tùy chọn ghi + PCM mono signed 16-bit little-endian để phát hiện người chen lời trong khi + phần phát lại của trợ lý đang hoạt động. Hiện tại mục này áp dụng cho cầu nối + cặp lệnh `chrome` do Gateway lưu trữ. +- `chrome.bargeInRmsThreshold: 650`: mức RMS được tính là một lần + chen lời của người trên `chrome.bargeInInputCommand` +- `chrome.bargeInPeakThreshold: 2500`: mức đỉnh được tính là một lần + chen lời của người trên `chrome.bargeInInputCommand` +- `chrome.bargeInCooldownMs: 900`: độ trễ tối thiểu giữa các lần xóa + chen lời của người lặp lại +- `mode: "agent"`: chế độ trả lời mặc định. Lời nói của người tham gia được phiên âm bởi + nhà cung cấp phiên âm realtime đã cấu hình, gửi tới tác tử + OpenClaw đã cấu hình trong một phiên tác tử phụ cho từng cuộc họp, rồi được nói lại qua + runtime TTS OpenClaw thông thường. +- `mode: "bidi"`: chế độ mô hình realtime hai chiều trực tiếp dự phòng. Nhà cung cấp + giọng nói realtime trả lời trực tiếp lời nói của người tham gia và có thể gọi + `openclaw_agent_consult` để có câu trả lời sâu hơn/có công cụ hỗ trợ. +- `mode: "transcribe"`: chế độ chỉ quan sát, không có cầu nối trả lời. +- `realtime.provider: "openai"`: id nhà cung cấp được chế độ `agent` dùng cho phiên âm + realtime và chế độ `bidi` dùng cho giọng nói realtime. - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`: câu trả lời nói ngắn gọn, với `openclaw_agent_consult` cho câu trả lời sâu hơn -- `realtime.introMessage`: kiểm tra trạng thái sẵn sàng bằng lời nói ngắn khi cầu nối realtime kết nối; đặt thành `""` để tham gia im lặng -- `realtime.agentId`: id agent OpenClaw tùy chọn cho `openclaw_agent_consult`; mặc định là `main` +- `realtime.instructions`: câu trả lời nói ngắn gọn, dùng + `openclaw_agent_consult` cho câu trả lời sâu hơn +- `realtime.introMessage`: kiểm tra sẵn sàng bằng lời nói ngắn khi cầu nối realtime + kết nối; đặt thành `""` để tham gia im lặng +- `realtime.agentId`: id tác tử OpenClaw tùy chọn cho + `openclaw_agent_consult`; mặc định là `main` -Ghi đè tùy chọn: +Các ghi đè tùy chọn: ```json5 { @@ -1067,6 +1090,7 @@ Ghi đè tùy chọn: chromeNode: { node: "parallels-macos", }, + defaultMode: "agent", realtime: { provider: "google", agentId: "jay", @@ -1097,34 +1121,63 @@ Cấu hình chỉ dành cho Twilio: } ``` -`voiceCall.enabled` mặc định là `true`; với transport Twilio, nó ủy quyền cuộc gọi PSTN thực tế, DTMF và lời chào mở đầu cho Plugin Voice Call. Voice Call phát chuỗi DTMF trước khi mở luồng phương tiện realtime, rồi dùng văn bản giới thiệu đã lưu làm lời chào realtime ban đầu. Nếu `voice-call` không được bật, Google Meet vẫn có thể xác thực và ghi lại kế hoạch quay số, nhưng không thể thực hiện cuộc gọi Twilio. +`voiceCall.enabled` mặc định là `true`; với transport Twilio, nó ủy quyền +cuộc gọi PSTN, DTMF và lời chào giới thiệu thực tế cho Plugin Voice Call. Voice Call +phát chuỗi DTMF trước khi mở luồng phương tiện realtime, rồi dùng +văn bản giới thiệu đã lưu làm lời chào realtime ban đầu. Nếu `voice-call` không +được bật, Google Meet vẫn có thể xác thực và ghi lại kế hoạch quay số, nhưng không thể +thực hiện cuộc gọi Twilio. ## Công cụ -Agent có thể dùng công cụ `google_meet`: +Các tác tử có thể dùng công cụ `google_meet`: ```json { "action": "join", "url": "https://meet.google.com/abc-defg-hij", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` -Dùng `transport: "chrome"` khi Chrome chạy trên máy chủ Gateway. Dùng `transport: "chrome-node"` khi Chrome chạy trên một Node đã ghép cặp, chẳng hạn như VM Parallels. Trong cả hai trường hợp, mô hình realtime và `openclaw_agent_consult` chạy trên máy chủ Gateway, vì vậy thông tin xác thực mô hình vẫn nằm ở đó. +Dùng `transport: "chrome"` khi Chrome chạy trên máy chủ Gateway. Dùng +`transport: "chrome-node"` khi Chrome chạy trên một Node đã ghép đôi, chẳng hạn như VM Parallels. +Trong cả hai trường hợp, các nhà cung cấp mô hình và `openclaw_agent_consult` chạy trên +máy chủ Gateway, nên thông tin xác thực mô hình vẫn ở đó. Với `mode: "agent"` mặc định, +nhà cung cấp phiên âm realtime xử lý việc lắng nghe, tác tử OpenClaw +đã cấu hình tạo câu trả lời, và TTS OpenClaw thông thường nói câu đó vào Meet. Dùng +`mode: "bidi"` khi bạn muốn mô hình giọng nói realtime trả lời trực tiếp. +`mode: "realtime"` vẫn được chấp nhận làm bí danh tương thích cho +`mode: "agent"`. -Dùng `action: "status"` để liệt kê các phiên đang hoạt động hoặc kiểm tra một ID phiên. Dùng `action: "speak"` với `sessionId` và `message` để khiến agent realtime nói ngay lập tức. Dùng `action: "test_speech"` để tạo hoặc tái sử dụng phiên, kích hoạt một cụm từ đã biết, và trả về tình trạng `inCall` khi máy chủ Chrome có thể báo cáo. `test_speech` luôn buộc `mode: "realtime"` và thất bại nếu được yêu cầu chạy trong `mode: "transcribe"` vì các phiên chỉ quan sát cố ý không thể phát lời nói. Kết quả `speechOutputVerified` của nó dựa trên việc số byte đầu ra âm thanh realtime tăng trong lần gọi kiểm thử này, nên một phiên được tái sử dụng với âm thanh cũ hơn không được tính là kiểm tra lời nói thành công mới. Dùng `action: "leave"` để đánh dấu một phiên đã kết thúc. +Dùng `action: "status"` để liệt kê các phiên đang hoạt động hoặc kiểm tra một ID phiên. Dùng +`action: "speak"` với `sessionId` và `message` để khiến tác tử realtime +nói ngay lập tức. Dùng `action: "test_speech"` để tạo hoặc tái sử dụng phiên, +kích hoạt một cụm từ đã biết và trả về tình trạng `inCall` khi máy chủ Chrome có thể +báo cáo điều đó. `test_speech` luôn ép `mode: "agent"` và thất bại nếu được yêu cầu +chạy trong `mode: "transcribe"` vì các phiên chỉ quan sát cố ý không thể +phát lời nói. Kết quả `speechOutputVerified` của nó dựa trên việc byte đầu ra âm thanh realtime +tăng lên trong cuộc gọi kiểm thử này, nên một phiên được tái sử dụng có âm thanh cũ hơn +không được tính là một lần kiểm tra lời nói mới thành công. Dùng `action: "leave"` để đánh dấu +một phiên đã kết thúc. `status` bao gồm tình trạng Chrome khi có sẵn: - `inCall`: Chrome có vẻ đang ở trong cuộc gọi Meet -- `micMuted`: trạng thái micro Meet theo nỗ lực tốt nhất -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: hồ sơ trình duyệt cần đăng nhập thủ công, chủ phòng Meet cho phép vào, cấp quyền, hoặc sửa điều khiển trình duyệt trước khi lời nói có thể hoạt động -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: liệu lời nói Chrome được quản lý hiện có được phép hay không. `speechReady: false` nghĩa là OpenClaw chưa gửi cụm từ giới thiệu/kiểm thử vào cầu nối âm thanh. +- `micMuted`: trạng thái micrô Meet ở mức cố gắng tối đa +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: hồ sơ + trình duyệt cần đăng nhập thủ công, được chủ phòng Meet cho vào, cấp quyền, hoặc + sửa điều khiển trình duyệt trước khi lời nói có thể hoạt động +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: liệu + lời nói Chrome được quản lý hiện có được phép hay không. `speechReady: false` nghĩa là OpenClaw đã + không gửi cụm từ giới thiệu/kiểm thử vào cầu nối âm thanh. - `providerConnected` / `realtimeReady`: trạng thái cầu nối giọng nói realtime -- `lastInputAt` / `lastOutputAt`: âm thanh cuối cùng được thấy từ hoặc gửi đến cầu nối -- `lastSuppressedInputAt` / `suppressedInputBytes`: đầu vào local loopback bị bỏ qua trong khi phát âm thanh của trợ lý +- `lastInputAt` / `lastOutputAt`: âm thanh cuối cùng được thấy từ hoặc gửi tới cầu nối +- `audioOutputRouted` / `audioOutputDeviceLabel`: liệu đầu ra phương tiện của thẻ Meet + đã được định tuyến chủ động tới thiết bị BlackHole mà cầu nối dùng hay chưa +- `lastSuppressedInputAt` / `suppressedInputBytes`: đầu vào local loopback bị bỏ qua trong khi + phần phát lại của trợ lý đang hoạt động ```json { @@ -1134,29 +1187,60 @@ Dùng `action: "status"` để liệt kê các phiên đang hoạt động hoặ } ``` -## Tham vấn agent realtime +## Chế độ tác tử và Bidi -Chế độ realtime của Chrome được tối ưu hóa cho vòng lặp giọng nói trực tiếp. Nhà cung cấp giọng nói realtime nghe âm thanh cuộc họp và nói qua cầu nối âm thanh đã cấu hình. Khi mô hình realtime cần suy luận sâu hơn, thông tin hiện tại, hoặc các công cụ OpenClaw thông thường, nó có thể gọi `openclaw_agent_consult`. +Chế độ `agent` của Chrome được tối ưu cho hành vi "tác tử của tôi đang ở trong cuộc họp". Nhà cung cấp +phiên âm realtime nghe âm thanh cuộc họp, các bản phiên âm cuối cùng của người tham gia +được định tuyến qua tác tử OpenClaw đã cấu hình, và câu trả lời được +nói qua runtime TTS OpenClaw thông thường. Đặt `mode: "bidi"` khi bạn muốn +mô hình giọng nói realtime trả lời trực tiếp. +Các đoạn bản phiên âm cuối gần nhau được gộp lại trước khi consult để một lượt nói +không tạo ra nhiều câu trả lời từng phần đã cũ. Đầu vào realtime cũng +bị chặn trong khi âm thanh trợ lý đã xếp hàng vẫn đang phát, +và các tiếng vọng bản phiên âm giống trợ lý gần đây bị bỏ qua trước khi consult tác tử +để local loopback BlackHole không khiến tác tử trả lời chính lời nói của nó. -Công cụ tham vấn chạy agent OpenClaw thông thường ở hậu trường với ngữ cảnh bản ghi cuộc họp gần đây và trả về một câu trả lời nói ngắn gọn cho phiên giọng nói realtime. Sau đó mô hình giọng nói có thể nói câu trả lời đó trở lại cuộc họp. Nó dùng cùng công cụ tham vấn realtime dùng chung như Voice Call. +| Chế độ | Ai quyết định câu trả lời | Đường dẫn đầu ra lời nói | Dùng khi | +| ------- | ----------------------------- | ------------------------------------- | ------------------------------------------------------ | +| `agent` | Tác tử OpenClaw đã cấu hình | Runtime TTS OpenClaw thông thường | Bạn muốn hành vi "tác tử của tôi đang ở trong cuộc họp" | +| `bidi` | Mô hình giọng nói realtime | Phản hồi âm thanh của nhà cung cấp giọng nói realtime | Bạn muốn vòng hội thoại bằng giọng nói có độ trễ thấp nhất | -Theo mặc định, các lần tham vấn chạy với agent `main`. Đặt `realtime.agentId` khi một luồng Meet nên tham vấn một không gian làm việc agent OpenClaw chuyên dụng, mặc định mô hình, chính sách công cụ, bộ nhớ, và lịch sử phiên riêng. +Ở chế độ `bidi`, khi mô hình realtime cần suy luận sâu hơn, thông tin hiện tại, +hoặc các công cụ OpenClaw thông thường, nó có thể gọi `openclaw_agent_consult`. -`realtime.toolPolicy` kiểm soát lượt chạy tham vấn: +Công cụ consult chạy tác tử OpenClaw thông thường phía sau với ngữ cảnh bản phiên âm +cuộc họp gần đây và trả về một câu trả lời nói ngắn gọn. Ở chế độ `agent`, +OpenClaw gửi câu trả lời đó trực tiếp tới runtime TTS; ở chế độ `bidi`, mô hình +giọng nói realtime có thể nói kết quả consult trở lại cuộc họp. Nó dùng +cùng cơ chế consult dùng chung như Voice Call. -- `safe-read-only`: hiển thị công cụ tham vấn và giới hạn agent thông thường ở `read`, `web_search`, `web_fetch`, `x_search`, `memory_search`, và `memory_get`. -- `owner`: hiển thị công cụ tham vấn và cho phép agent thông thường dùng chính sách công cụ agent bình thường. -- `none`: không hiển thị công cụ tham vấn cho mô hình giọng nói realtime. +Theo mặc định, các consult chạy với tác tử `main`. Đặt `realtime.agentId` khi một +luồng Meet nên consult một không gian làm việc tác tử OpenClaw chuyên dụng, mặc định mô hình, +chính sách công cụ, bộ nhớ và lịch sử phiên riêng. -Khóa phiên tham vấn được giới hạn theo từng phiên Meet, vì vậy các lệnh gọi tham vấn tiếp theo có thể tái sử dụng ngữ cảnh tham vấn trước đó trong cùng cuộc họp. +Consult ở chế độ tác tử dùng khóa phiên `agent::subagent:google-meet:` +cho từng cuộc họp để các câu hỏi tiếp theo giữ ngữ cảnh cuộc họp trong khi kế thừa chính sách +tác tử thông thường từ tác tử đã cấu hình. -Để buộc kiểm tra trạng thái sẵn sàng bằng lời nói sau khi Chrome đã tham gia đầy đủ cuộc gọi: +`realtime.toolPolicy` kiểm soát lần chạy consult: + +- `safe-read-only`: hiển thị công cụ consult và giới hạn tác tử thông thường ở + `read`, `web_search`, `web_fetch`, `x_search`, `memory_search`, và + `memory_get`. +- `owner`: hiển thị công cụ consult và để tác tử thông thường dùng chính sách + công cụ tác tử thông thường. +- `none`: không hiển thị công cụ consult cho mô hình giọng nói realtime. + +Khóa phiên consult được giới hạn theo từng phiên Meet, nên các lệnh gọi consult tiếp theo +có thể tái sử dụng ngữ cảnh consult trước đó trong cùng cuộc họp. + +Để ép kiểm tra sẵn sàng bằng lời nói sau khi Chrome đã tham gia hoàn toàn cuộc gọi: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Cho smoke tham gia và nói đầy đủ: +Cho smoke tham gia-và-nói đầy đủ: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1166,7 +1250,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## Danh sách kiểm tra kiểm thử live -Dùng trình tự này trước khi giao cuộc họp cho một agent không có người giám sát: +Dùng trình tự này trước khi giao cuộc họp cho một tác tử không có người giám sát: ```bash openclaw googlemeet setup @@ -1178,13 +1262,16 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ Trạng thái Chrome-node mong đợi: -- `googlemeet setup` đều xanh. -- `googlemeet setup` bao gồm `chrome-node-connected` khi Chrome-node là transport mặc định hoặc một Node được ghim. +- `googlemeet setup` toàn bộ màu xanh. +- `googlemeet setup` bao gồm `chrome-node-connected` khi Chrome-node là + transport mặc định hoặc một Node được ghim. - `nodes status` hiển thị Node đã chọn đang kết nối. - Node đã chọn quảng bá cả `googlemeet.chrome` và `browser.proxy`. -- Thẻ Meet tham gia cuộc gọi và `test-speech` trả về tình trạng Chrome với `inCall: true`. +- Thẻ Meet tham gia cuộc gọi và `test-speech` trả về tình trạng Chrome với + `inCall: true`. -Đối với một máy chủ Chrome từ xa như VM macOS Parallels, đây là kiểm tra an toàn ngắn nhất sau khi cập nhật Gateway hoặc VM: +Đối với máy chủ Chrome từ xa như VM macOS Parallels, đây là kiểm tra an toàn +ngắn nhất sau khi cập nhật Gateway hoặc VM: ```bash openclaw googlemeet setup @@ -1195,9 +1282,11 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Điều đó chứng minh Plugin Gateway đã được tải, Node VM được kết nối với token hiện tại, và cầu nối âm thanh Meet có sẵn trước khi một agent mở thẻ cuộc họp thật. +Điều đó chứng minh Plugin Gateway đã được tải, Node VM được kết nối với +token hiện tại, và cầu nối âm thanh Meet sẵn sàng trước khi một tác tử mở +thẻ cuộc họp thật. -Đối với smoke Twilio, dùng một cuộc họp có thông tin quay số điện thoại vào: +Cho smoke Twilio, dùng một cuộc họp có chi tiết gọi vào qua điện thoại: ```bash openclaw googlemeet setup @@ -1209,15 +1298,17 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Trạng thái Twilio mong đợi: -- `googlemeet setup` bao gồm các kiểm tra xanh `twilio-voice-call-plugin`, `twilio-voice-call-credentials`, và `twilio-voice-call-webhook`. +- `googlemeet setup` bao gồm các kiểm tra màu xanh cho `twilio-voice-call-plugin`, + `twilio-voice-call-credentials` và `twilio-voice-call-webhook`. - `voicecall` có sẵn trong CLI sau khi Gateway tải lại. - Phiên được trả về có `transport: "twilio"` và một `twilio.voiceCallId`. -- `openclaw logs --follow` hiển thị DTMF TwiML được phục vụ trước TwiML realtime, rồi một cầu nối realtime với lời chào ban đầu đã được đưa vào hàng đợi. -- `googlemeet leave ` ngắt cuộc gọi thoại đã ủy quyền. +- `openclaw logs --follow` hiển thị DTMF TwiML được phục vụ trước realtime TwiML, rồi một + cầu nối realtime với lời chào ban đầu được xếp hàng. +- `googlemeet leave ` ngắt cuộc gọi thoại được ủy quyền. ## Khắc phục sự cố -### Agent không thấy công cụ Google Meet +### Tác nhân không thấy công cụ Google Meet Xác nhận Plugin đã được bật trong cấu hình Gateway và tải lại Gateway: @@ -1226,11 +1317,17 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -Nếu bạn vừa chỉnh sửa `plugins.entries.google-meet`, hãy khởi động lại hoặc tải lại Gateway. Agent đang chạy chỉ thấy các công cụ Plugin được đăng ký bởi tiến trình Gateway hiện tại. +Nếu bạn vừa chỉnh sửa `plugins.entries.google-meet`, hãy khởi động lại hoặc tải lại Gateway. +Tác nhân đang chạy chỉ thấy các công cụ Plugin được đăng ký bởi tiến trình Gateway +hiện tại. -Trên các máy chủ Gateway không phải macOS, công cụ hướng tới agent `google_meet` vẫn hiển thị, nhưng các hành động realtime Chrome cục bộ bị chặn trước khi chạm tới cầu nối âm thanh. Âm thanh realtime Chrome cục bộ hiện phụ thuộc vào `BlackHole 2ch` của macOS, vì vậy agent Linux nên dùng `mode: "transcribe"`, quay số vào Twilio, hoặc máy chủ `chrome-node` macOS thay vì đường dẫn realtime Chrome cục bộ mặc định. +Trên các máy chủ Gateway không phải macOS, công cụ `google_meet` hướng tới tác nhân vẫn hiển thị, +nhưng các hành động phản hồi bằng giọng nói của Chrome cục bộ bị chặn trước khi đến cầu nối âm thanh. +Âm thanh phản hồi bằng giọng nói của Chrome cục bộ hiện phụ thuộc vào `BlackHole 2ch` trên macOS, vì vậy +các tác nhân Linux nên dùng `mode: "transcribe"`, quay số vào bằng Twilio, hoặc máy chủ +`chrome-node` trên macOS thay vì đường dẫn tác nhân Chrome cục bộ mặc định. -### Không có Node hỗ trợ Google Meet nào được kết nối +### Không có Node có khả năng Google Meet nào được kết nối Trên máy chủ Node, chạy: @@ -1249,7 +1346,8 @@ openclaw devices approve openclaw nodes status ``` -Node phải được kết nối và liệt kê `googlemeet.chrome` cùng `browser.proxy`. Cấu hình Gateway phải cho phép các lệnh Node đó: +Node phải được kết nối và liệt kê `googlemeet.chrome` cùng với `browser.proxy`. +Cấu hình Gateway phải cho phép các lệnh Node đó: ```json5 { @@ -1261,7 +1359,9 @@ Node phải được kết nối và liệt kê `googlemeet.chrome` cùng `brows } ``` -Nếu `googlemeet setup` thất bại ở `chrome-node-connected` hoặc nhật ký Gateway báo `gateway token mismatch`, hãy cài đặt lại hoặc khởi động lại Node với token Gateway hiện tại. Đối với Gateway LAN, điều này thường có nghĩa là: +Nếu `googlemeet setup` không đạt `chrome-node-connected` hoặc nhật ký Gateway báo cáo +`gateway token mismatch`, hãy cài đặt lại hoặc khởi động lại Node với token Gateway +hiện tại. Với Gateway LAN, điều này thường có nghĩa là: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1279,45 +1379,58 @@ openclaw googlemeet setup openclaw nodes status --connected ``` -### Trình duyệt mở nhưng agent không thể tham gia +### Trình duyệt mở nhưng tác nhân không thể tham gia -Chạy `googlemeet test-listen` cho các lần tham gia chỉ quan sát hoặc `googlemeet test-speech` cho các lần tham gia realtime, rồi kiểm tra tình trạng Chrome được trả về. Nếu một trong hai phép dò báo `manualActionRequired: true`, hãy hiển thị `manualActionMessage` cho người vận hành và dừng thử lại cho đến khi hành động trên trình duyệt hoàn tất. +Chạy `googlemeet test-listen` cho các lần tham gia chỉ quan sát hoặc `googlemeet test-speech` +cho các lần tham gia realtime, rồi kiểm tra tình trạng Chrome được trả về. Nếu một trong hai phép dò +báo cáo `manualActionRequired: true`, hãy hiển thị `manualActionMessage` cho người vận hành +và dừng thử lại cho đến khi hành động trình duyệt hoàn tất. -Các hành động thủ công thường gặp: +Các hành động thủ công phổ biến: - Đăng nhập vào hồ sơ Chrome. -- Cho phép khách vào từ tài khoản chủ phòng Meet. -- Cấp quyền micro/camera Chrome khi lời nhắc quyền gốc của Chrome xuất hiện. +- Chấp nhận khách từ tài khoản máy chủ Meet. +- Cấp quyền micrô/camera cho Chrome khi lời nhắc quyền gốc của Chrome + xuất hiện. - Đóng hoặc sửa hộp thoại quyền Meet bị kẹt. -Không báo cáo là "chưa đăng nhập" chỉ vì Meet hiển thị "Bạn có muốn mọi người nghe thấy bạn trong cuộc họp không?" Đó là màn hình trung gian chọn âm thanh của Meet; OpenClaw nhấp **Sử dụng micrô** thông qua tự động hóa trình duyệt khi có sẵn và tiếp tục chờ trạng thái cuộc họp thực. Với phương án dự phòng trình duyệt chỉ để tạo, OpenClaw có thể nhấp **Tiếp tục không dùng micrô** vì việc tạo URL không cần đường dẫn âm thanh realtime. +Đừng báo cáo "chưa đăng nhập" chỉ vì Meet hiển thị "Do you want people to +hear you in the meeting?" Đó là màn xen kẽ chọn âm thanh của Meet; OpenClaw +nhấp **Use microphone** thông qua tự động hóa trình duyệt khi có sẵn và tiếp tục +chờ trạng thái cuộc họp thực. Với phương án dự phòng trình duyệt chỉ tạo, OpenClaw +có thể nhấp **Continue without microphone** vì việc tạo URL không cần +đường dẫn âm thanh realtime. -### Tạo cuộc họp không thành công +### Tạo cuộc họp thất bại -`googlemeet create` trước tiên dùng endpoint `spaces.create` của Google Meet API khi thông tin xác thực OAuth được cấu hình. Khi không có thông tin xác thực OAuth, lệnh sẽ chuyển sang trình duyệt Chrome node đã ghim. Hãy xác nhận: +`googlemeet create` trước tiên dùng điểm cuối `spaces.create` của Google Meet API +khi thông tin xác thực OAuth được cấu hình. Không có thông tin xác thực OAuth, nó chuyển dự phòng +sang trình duyệt Node Chrome đã ghim. Xác nhận: -- Với tạo bằng API: `oauth.clientId` và `oauth.refreshToken` đã được cấu hình, - hoặc có các biến môi trường `OPENCLAW_GOOGLE_MEET_*` khớp. -- Với tạo bằng API: refresh token được cấp sau khi hỗ trợ tạo được thêm vào. Token cũ hơn có thể thiếu scope `meetings.space.created`; chạy lại - `openclaw googlemeet auth login --json` và cập nhật cấu hình plugin. -- Với phương án dự phòng bằng trình duyệt: `defaultTransport: "chrome-node"` và - `chromeNode.node` trỏ đến một node đã kết nối có `browser.proxy` và +- Đối với tạo bằng API: `oauth.clientId` và `oauth.refreshToken` được cấu hình, + hoặc có các biến môi trường `OPENCLAW_GOOGLE_MEET_*` tương ứng. +- Đối với tạo bằng API: token làm mới được tạo sau khi hỗ trợ tạo + được thêm vào. Các token cũ hơn có thể thiếu phạm vi `meetings.space.created`; chạy lại + `openclaw googlemeet auth login --json` và cập nhật cấu hình Plugin. +- Đối với phương án dự phòng trình duyệt: `defaultTransport: "chrome-node"` và + `chromeNode.node` trỏ tới một Node đã kết nối có `browser.proxy` và `googlemeet.chrome`. -- Với phương án dự phòng bằng trình duyệt: hồ sơ Chrome của OpenClaw trên node đó đã đăng nhập +- Đối với phương án dự phòng trình duyệt: hồ sơ Chrome của OpenClaw trên Node đó đã đăng nhập vào Google và có thể mở `https://meet.google.com/new`. -- Với phương án dự phòng bằng trình duyệt: các lần thử lại tái sử dụng tab `https://meet.google.com/new` - hiện có hoặc tab lời nhắc tài khoản Google trước khi mở tab mới. Nếu agent hết thời gian chờ, - hãy thử lại lời gọi công cụ thay vì mở thủ công một tab Meet khác. -- Với phương án dự phòng bằng trình duyệt: nếu công cụ trả về `manualActionRequired: true`, hãy dùng +- Đối với phương án dự phòng trình duyệt: các lần thử lại dùng lại một tab `https://meet.google.com/new` + hoặc tab lời nhắc tài khoản Google hiện có trước khi mở tab mới. Nếu tác nhân hết thời gian chờ, + hãy thử lại lệnh gọi công cụ thay vì tự mở một tab Meet khác. +- Đối với phương án dự phòng trình duyệt: nếu công cụ trả về `manualActionRequired: true`, hãy dùng `browser.nodeId`, `browser.targetId`, `browserUrl` và - `manualActionMessage` được trả về để hướng dẫn người vận hành. Không thử lại trong vòng lặp cho đến khi + `manualActionMessage` được trả về để hướng dẫn người vận hành. Đừng thử lại trong vòng lặp cho đến khi hành động đó hoàn tất. -- Với phương án dự phòng bằng trình duyệt: nếu Meet hiển thị "Bạn có muốn mọi người nghe thấy bạn trong - cuộc họp không?", hãy để tab mở. OpenClaw nên nhấp **Sử dụng micrô** hoặc, với - phương án dự phòng chỉ để tạo, **Tiếp tục không dùng micrô** thông qua tự động hóa trình duyệt - và tiếp tục chờ URL Meet được tạo. Nếu không thể, lỗi nên nhắc đến `meet-audio-choice-required`, không phải `google-login-required`. +- Đối với phương án dự phòng trình duyệt: nếu Meet hiển thị "Do you want people to hear you in the + meeting?", hãy để tab mở. OpenClaw nên nhấp **Use microphone** hoặc, đối với + phương án dự phòng chỉ tạo, **Continue without microphone** thông qua tự động hóa trình duyệt + và tiếp tục chờ URL Meet được tạo. Nếu không thể, lỗi + nên nhắc tới `meet-audio-choice-required`, không phải `google-login-required`. -### Agent tham gia nhưng không nói +### Tác nhân tham gia nhưng không nói Kiểm tra đường dẫn realtime: @@ -1326,38 +1439,39 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -Dùng `mode: "realtime"` cho nghe/nói phản hồi. `mode: "transcribe"` cố ý -không khởi động cầu nối giọng nói realtime song công. Để gỡ lỗi chỉ quan sát, +Dùng `mode: "agent"` cho đường dẫn phản hồi bằng giọng nói STT -> tác nhân OpenClaw -> TTS thông thường, +hoặc `mode: "bidi"` cho phương án dự phòng giọng nói realtime trực tiếp. `mode: "transcribe"` +cố ý không khởi động cầu nối phản hồi bằng giọng nói. Để gỡ lỗi chỉ quan sát, chạy `openclaw googlemeet status --json ` sau khi người tham gia nói và kiểm tra `captioning`, `transcriptLines` và `lastCaptionText`. Nếu `inCall` là true nhưng `transcriptLines` vẫn ở `0`, phụ đề Meet có thể bị tắt, chưa có ai -nói kể từ khi trình quan sát được cài đặt, UI Meet đã thay đổi, hoặc phụ đề trực tiếp -không khả dụng cho ngôn ngữ/tài khoản của cuộc họp. +nói kể từ khi trình quan sát được cài đặt, giao diện Meet đã thay đổi, hoặc phụ đề trực tiếp +không khả dụng cho ngôn ngữ/tài khoản cuộc họp. `googlemeet test-speech` luôn kiểm tra đường dẫn realtime và báo cáo liệu -có quan sát được byte đầu ra cầu nối cho lần gọi đó hay không. Nếu `speechOutputVerified` là false và +có quan sát thấy byte đầu ra cầu nối cho lần gọi đó hay không. Nếu `speechOutputVerified` là false và `speechOutputTimedOut` là true, nhà cung cấp realtime có thể đã chấp nhận -câu nói nhưng OpenClaw không thấy byte đầu ra mới đến cầu nối âm thanh Chrome. +phát ngôn nhưng OpenClaw không thấy byte đầu ra mới đến cầu nối âm thanh Chrome. -Cũng hãy xác minh: +Cũng xác minh: - Khóa nhà cung cấp realtime có sẵn trên máy chủ Gateway, chẳng hạn như `OPENAI_API_KEY` hoặc `GEMINI_API_KEY`. - `BlackHole 2ch` hiển thị trên máy chủ Chrome. - `sox` tồn tại trên máy chủ Chrome. - Micrô và loa Meet được định tuyến qua đường dẫn âm thanh ảo mà - OpenClaw dùng. + OpenClaw sử dụng. `doctor` nên hiển thị `meet output routed: yes` cho các lần tham gia realtime bằng Chrome cục bộ. -`googlemeet doctor [session-id]` in phiên, node, trạng thái trong cuộc gọi, -lý do cần thao tác thủ công, kết nối nhà cung cấp realtime, `realtimeReady`, hoạt động -đầu vào/đầu ra âm thanh, dấu thời gian âm thanh gần nhất, bộ đếm byte và URL trình duyệt. +`googlemeet doctor [session-id]` in phiên, Node, trạng thái trong cuộc gọi, +lý do hành động thủ công, kết nối nhà cung cấp realtime, `realtimeReady`, hoạt động +đầu vào/đầu ra âm thanh, dấu thời gian âm thanh cuối cùng, bộ đếm byte và URL trình duyệt. Dùng `googlemeet status [session-id] --json` khi bạn cần JSON thô. Dùng -`googlemeet doctor --oauth` khi bạn cần xác minh refresh Google Meet OAuth +`googlemeet doctor --oauth` khi bạn cần xác minh làm mới OAuth của Google Meet mà không để lộ token; thêm `--meeting` hoặc `--create-space` khi bạn cũng cần bằng chứng Google Meet API. -Nếu agent hết thời gian chờ và bạn thấy một tab Meet đã mở, hãy kiểm tra tab đó -mà không mở tab khác: +Nếu tác nhân hết thời gian chờ và bạn có thể thấy một tab Meet đã mở, hãy kiểm tra tab đó +mà không mở thêm tab khác: ```bash openclaw googlemeet recover-tab @@ -1365,20 +1479,21 @@ openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` Hành động công cụ tương đương là `recover_current_tab`. Nó tập trung và kiểm tra một -tab Meet hiện có cho transport đã chọn. Với `chrome`, nó dùng điều khiển trình duyệt cục bộ -thông qua Gateway; với `chrome-node`, nó dùng Chrome node đã cấu hình. Nó không mở tab mới -hoặc tạo phiên mới; nó báo cáo điểm chặn hiện tại, chẳng hạn như đăng nhập, chấp nhận vào phòng, -quyền, hoặc trạng thái chọn âm thanh. Lệnh CLI nói chuyện với Gateway đã cấu hình, nên Gateway -phải đang chạy; `chrome-node` cũng yêu cầu Chrome node đã được kết nối. +tab Meet hiện có cho phương thức vận chuyển đã chọn. Với `chrome`, nó dùng điều khiển +trình duyệt cục bộ thông qua Gateway; với `chrome-node`, nó dùng Node Chrome đã cấu hình. +Nó không mở tab mới hoặc tạo phiên mới; nó báo cáo chướng ngại hiện tại, +chẳng hạn như trạng thái đăng nhập, chấp nhận, quyền hoặc chọn âm thanh. +Lệnh CLI giao tiếp với Gateway đã cấu hình, vì vậy Gateway phải đang chạy; +`chrome-node` cũng yêu cầu Node Chrome được kết nối. -### Kiểm tra thiết lập Twilio không thành công +### Kiểm tra thiết lập Twilio thất bại -`twilio-voice-call-plugin` thất bại khi `voice-call` không được cho phép hoặc chưa được bật. -Thêm nó vào `plugins.allow`, bật `plugins.entries.voice-call`, và tải lại +`twilio-voice-call-plugin` thất bại khi `voice-call` không được phép hoặc chưa được bật. +Thêm nó vào `plugins.allow`, bật `plugins.entries.voice-call` và tải lại Gateway. -`twilio-voice-call-credentials` thất bại khi backend Twilio thiếu account -SID, auth token, hoặc số gọi đi. Đặt các giá trị này trên máy chủ Gateway: +`twilio-voice-call-credentials` thất bại khi backend Twilio thiếu SID tài khoản, +token xác thực hoặc số gọi đi. Đặt các giá trị này trên máy chủ Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1386,16 +1501,16 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`twilio-voice-call-webhook` thất bại khi `voice-call` không có webhook công khai -hoặc khi `publicUrl` trỏ đến local loopback hoặc không gian mạng riêng. +`twilio-voice-call-webhook` thất bại khi `voice-call` không có khả năng hiển thị Webhook +công khai, hoặc khi `publicUrl` trỏ tới local loopback hoặc không gian mạng riêng. Đặt `plugins.entries.voice-call.config.publicUrl` thành URL nhà cung cấp công khai hoặc -cấu hình một tunnel/Tailscale exposure cho `voice-call`. +cấu hình một đường hầm/Tailscale cho `voice-call`. -URL loopback và URL riêng không hợp lệ cho callback của nhà mạng. Không dùng +URL loopback và riêng tư không hợp lệ cho callback của nhà mạng. Đừng dùng `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, -`192.168.x`, `169.254.x`, `fc00::/7`, hoặc `fd00::/8` làm `publicUrl`. +`192.168.x`, `169.254.x`, `fc00::/7` hoặc `fd00::/8` làm `publicUrl`. -Để có URL công khai ổn định: +Đối với URL công khai ổn định: ```json5 { @@ -1414,8 +1529,8 @@ URL loopback và URL riêng không hợp lệ cho callback của nhà mạng. Kh } ``` -Để phát triển cục bộ, hãy dùng tunnel hoặc Tailscale exposure thay vì URL -máy chủ riêng: +Đối với phát triển cục bộ, dùng đường hầm hoặc khả năng hiển thị qua Tailscale thay vì URL +máy chủ riêng tư: ```json5 { @@ -1441,13 +1556,13 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` mặc định chỉ kiểm tra mức sẵn sàng. Để chạy thử khô với một số cụ thể: +`voicecall smoke` mặc định chỉ kiểm tra mức độ sẵn sàng. Để chạy thử với một số cụ thể: ```bash openclaw voicecall smoke --to "+15555550123" ``` -Chỉ thêm `--yes` khi bạn chủ ý muốn thực hiện một cuộc gọi thông báo đi trực tiếp: +Chỉ thêm `--yes` khi bạn cố ý muốn thực hiện một cuộc gọi thông báo đi trực tiếp: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -1455,8 +1570,8 @@ openclaw voicecall smoke --to "+15555550123" --yes ### Cuộc gọi Twilio bắt đầu nhưng không bao giờ vào cuộc họp -Xác nhận sự kiện Meet cung cấp chi tiết gọi điện vào. Truyền chính xác -số gọi vào và PIN hoặc một chuỗi DTMF tùy chỉnh: +Xác nhận sự kiện Meet có cung cấp chi tiết quay số vào bằng điện thoại. Truyền đúng số quay số vào +và PIN hoặc chuỗi DTMF tùy chỉnh: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1469,71 +1584,73 @@ Dùng `w` ở đầu hoặc dấu phẩy trong `--dtmf-sequence` nếu nhà cung trước khi nhập PIN. Nếu cuộc gọi điện thoại được tạo nhưng danh sách người tham gia Meet không bao giờ hiển thị -người tham gia gọi vào: +người tham gia quay số vào: - Chạy `openclaw googlemeet doctor ` để xác nhận ID cuộc gọi Twilio - được ủy quyền, DTMF đã được đưa vào hàng đợi hay chưa, và lời chào mở đầu đã được yêu cầu hay chưa. + được ủy quyền, DTMF đã được xếp hàng hay chưa, và lời chào mở đầu đã được yêu cầu hay chưa. - Chạy `openclaw voicecall status --call-id ` và xác nhận cuộc gọi vẫn đang hoạt động. -- Chạy `openclaw voicecall tail` và kiểm tra các webhook Twilio có đang đến - Gateway hay không. +- Chạy `openclaw voicecall tail` và kiểm tra rằng các Webhook Twilio đang đến + Gateway. - Chạy `openclaw logs --follow` và tìm chuỗi Twilio Meet: Google - Meet ủy quyền việc tham gia, Voice Call bắt đầu nhánh điện thoại, Google Meet chờ + Meet ủy quyền tham gia, Voice Call bắt đầu nhánh điện thoại, Google Meet chờ `voiceCall.dtmfDelayMs`, gửi DTMF bằng `voicecall.dtmf`, chờ - `voiceCall.postDtmfSpeechDelayMs`, rồi yêu cầu lời chào mở đầu bằng + `voiceCall.postDtmfSpeechDelayMs`, rồi yêu cầu lời nói mở đầu bằng `voicecall.speak`. -- Chạy lại `openclaw googlemeet setup --transport twilio`; kiểm tra thiết lập xanh là +- Chạy lại `openclaw googlemeet setup --transport twilio`; kiểm tra thiết lập màu xanh là bắt buộc nhưng không chứng minh chuỗi PIN cuộc họp là đúng. -- Xác nhận số gọi vào thuộc cùng lời mời Meet và khu vực với +- Xác nhận số quay số vào thuộc cùng lời mời Meet và cùng khu vực với PIN. -- Tăng `voiceCall.dtmfDelayMs` nếu Meet trả lời chậm hoặc bản ghi cuộc gọi +- Tăng `voiceCall.dtmfDelayMs` nếu Meet trả lời chậm hoặc bản chép lời cuộc gọi vẫn hiển thị lời nhắc yêu cầu PIN sau khi DTMF đã được gửi. -- Nếu người tham gia vào được nhưng bạn không nghe lời chào, hãy kiểm tra +- Nếu người tham gia đã vào nhưng bạn không nghe lời chào, hãy kiểm tra `openclaw logs --follow` để tìm yêu cầu `voicecall.speak` sau DTMF và - phát TTS media-stream hoặc phương án dự phòng Twilio ``. Nếu bản ghi cuộc gọi - vẫn chứa "nhập PIN cuộc họp", nhánh điện thoại chưa vào phòng Meet, - vì vậy người tham gia cuộc họp sẽ không nghe thấy lời nói. + phát lại TTS qua luồng phương tiện hoặc phương án dự phòng `` của Twilio. Nếu bản chép lời cuộc gọi + vẫn chứa "enter the meeting PIN", nhánh điện thoại chưa tham gia + phòng Meet, vì vậy người tham gia cuộc họp sẽ không nghe thấy lời nói. -Nếu webhook không đến, hãy gỡ lỗi Plugin Voice Call trước: nhà cung cấp phải +Nếu các Webhook không đến, hãy gỡ lỗi Plugin Voice Call trước: nhà cung cấp phải truy cập được `plugins.entries.voice-call.config.publicUrl` hoặc tunnel đã cấu hình. -Xem [Khắc phục sự cố cuộc gọi thoại](/vi/plugins/voice-call#troubleshooting). +Xem [Khắc phục sự cố Voice Call](/vi/plugins/voice-call#troubleshooting). ## Ghi chú -Google Meet's official media API is receive-oriented, so speaking into a Meet -call still needs a participant path. Plugin này giữ ranh giới đó hiển thị: +API phương tiện chính thức của Google Meet thiên về nhận dữ liệu, nên việc nói vào một cuộc gọi Meet +vẫn cần một đường tham gia. Plugin này giữ ranh giới đó rõ ràng: Chrome xử lý việc tham gia bằng trình duyệt và định tuyến âm thanh cục bộ; Twilio xử lý -việc tham gia gọi điện vào. +việc tham gia bằng quay số điện thoại. -Chế độ realtime của Chrome cần `BlackHole 2ch` cộng với một trong các lựa chọn sau: +Các chế độ phản hồi bằng giọng nói của Chrome cần `BlackHole 2ch` cùng với một trong hai: - `chrome.audioInputCommand` cộng với `chrome.audioOutputCommand`: OpenClaw sở hữu - cầu nối mô hình realtime và dẫn âm thanh trong `chrome.audioFormat` giữa các - lệnh đó và nhà cung cấp giọng nói realtime đã chọn. Đường dẫn Chrome mặc định là - PCM16 24 kHz; G.711 mu-law 8 kHz vẫn khả dụng cho các cặp lệnh cũ. -- `chrome.audioBridgeCommand`: một lệnh cầu nối bên ngoài sở hữu toàn bộ - đường dẫn âm thanh cục bộ và phải thoát sau khi khởi động hoặc xác thực daemon của nó. + cầu nối và truyền âm thanh ở `chrome.audioFormat` giữa các lệnh đó và + nhà cung cấp đã chọn. Chế độ tác nhân dùng phiên âm thời gian thực cộng với TTS thông thường; + chế độ bidi dùng nhà cung cấp giọng nói thời gian thực. Đường Chrome mặc định là PCM16 + 24 kHz; G.711 mu-law 8 kHz vẫn có sẵn cho các cặp lệnh cũ. +- `chrome.audioBridgeCommand`: một lệnh cầu nối bên ngoài sở hữu toàn bộ đường + âm thanh cục bộ và phải thoát sau khi khởi động hoặc xác thực daemon của nó. Điều này chỉ + hợp lệ cho `bidi` vì chế độ `agent` cần quyền truy cập trực tiếp vào cặp lệnh cho TTS. -Để có âm thanh song công sạch, hãy định tuyến đầu ra Meet và micrô Meet qua các +Để có âm thanh song công sạch, hãy định tuyến đầu ra Meet và micro Meet qua các thiết bị ảo riêng biệt hoặc một đồ thị thiết bị ảo kiểu Loopback. Một thiết bị -BlackHole dùng chung duy nhất có thể vọng lại người tham gia khác vào cuộc gọi. +BlackHole dùng chung duy nhất có thể vọng âm của người tham gia khác trở lại cuộc gọi. -Với cầu nối Chrome dạng cặp lệnh, `chrome.bargeInInputCommand` có thể lắng nghe một -micrô cục bộ riêng và xóa phát lại của trợ lý khi con người bắt đầu -nói. Điều này giữ lời nói của con người đi trước đầu ra của trợ lý ngay cả khi đầu vào -local loopback BlackHole dùng chung tạm thời bị chặn trong lúc trợ lý phát lại. +Với cầu nối Chrome theo cặp lệnh, `chrome.bargeInInputCommand` có thể nghe một +micro cục bộ riêng và xóa phát lại của trợ lý khi người dùng bắt đầu +nói. Điều này giữ lời nói của người dùng đi trước đầu ra của trợ lý ngay cả khi đầu vào +local loopback BlackHole dùng chung tạm thời bị chặn trong lúc phát lại của trợ lý. Giống như `chrome.audioInputCommand` và `chrome.audioOutputCommand`, đây là một -lệnh cục bộ do người vận hành cấu hình. Dùng đường dẫn lệnh hoặc danh sách đối số tin cậy -rõ ràng, và không trỏ nó đến script từ các vị trí không đáng tin cậy. +lệnh cục bộ do người vận hành cấu hình. Hãy dùng một đường dẫn lệnh đáng tin cậy rõ ràng hoặc +danh sách đối số, và không trỏ nó tới các script từ vị trí không đáng tin cậy. -`googlemeet speak` kích hoạt cầu nối âm thanh realtime đang hoạt động cho một phiên -Chrome. `googlemeet leave` dừng cầu nối đó. Với các phiên Twilio được ủy quyền -thông qua Plugin Voice Call, `leave` cũng ngắt cuộc gọi thoại bên dưới. +`googlemeet speak` kích hoạt cầu nối âm thanh phản hồi bằng giọng nói đang hoạt động cho một phiên +Chrome. `googlemeet leave` dừng cầu nối đó. Đối với các phiên Twilio được ủy quyền +qua Plugin Voice Call, `leave` cũng ngắt cuộc gọi thoại bên dưới. Dùng `googlemeet end-active-conference` khi bạn cũng muốn đóng hội nghị -Google Meet đang hoạt động cho một space do API quản lý. +Google Meet đang hoạt động cho một không gian do API quản lý. ## Liên quan -- [Plugin cuộc gọi thoại](/vi/plugins/voice-call) -- [Chế độ nói chuyện](/vi/nodes/talk) -- [Xây dựng plugin](/vi/plugins/building-plugins) +- [Plugin Voice Call](/vi/plugins/voice-call) +- [Chế độ nói](/vi/nodes/talk) +- [Xây dựng Plugin](/vi/plugins/building-plugins) diff --git a/docs/vi/plugins/memory-wiki.md b/docs/vi/plugins/memory-wiki.md index f9bab2f24..4ee5fa660 100644 --- a/docs/vi/plugins/memory-wiki.md +++ b/docs/vi/plugins/memory-wiki.md @@ -1,120 +1,119 @@ --- read_when: - - Bạn muốn kiến thức lâu dài vượt ngoài các ghi chú MEMORY.md đơn thuần - - Bạn đang cấu hình plugin memory-wiki đi kèm - - Bạn muốn tìm hiểu về wiki_search, wiki_get hoặc chế độ cầu nối -summary: 'memory-wiki: kho tri thức tổng hợp với nguồn gốc, các khẳng định, bảng điều khiển và chế độ cầu nối' + - Bạn muốn có kiến thức được lưu giữ lâu dài ngoài các ghi chú MEMORY.md thuần túy + - Bạn đang cấu hình Plugin memory-wiki đi kèm + - Bạn muốn hiểu về wiki_search, wiki_get hoặc chế độ cầu nối +summary: 'memory-wiki: kho tri thức đã biên soạn với thông tin nguồn gốc, các tuyên bố, bảng điều khiển và chế độ cầu nối' title: Wiki bộ nhớ x-i18n: - generated_at: "2026-04-29T23:00:45Z" + generated_at: "2026-05-04T02:25:14Z" model: gpt-5.5 provider: openai - source_hash: 744d569f8b0c9b668ea54dc057f808544359eaae87d5557de2e6acd1b31acd89 + source_hash: b070177b7c1217e9102bc57680b4009265e3584ede7ad6dc3ba7b6393260fefe source_path: plugins/memory-wiki.md workflow: 16 --- -`memory-wiki` là một Plugin đi kèm, biến bộ nhớ bền vững thành một -kho tri thức đã biên dịch. +`memory-wiki` là một Plugin đi kèm giúp biến bộ nhớ bền vững thành một kho tri thức đã biên dịch. Nó **không** thay thế Plugin Active Memory. Plugin Active Memory vẫn -sở hữu việc truy hồi, thăng hạng, lập chỉ mục và Dreaming. `memory-wiki` nằm bên cạnh nó +sở hữu việc truy hồi, thăng cấp, lập chỉ mục và Dreaming. `memory-wiki` nằm cạnh nó và biên dịch tri thức bền vững thành một wiki có thể điều hướng với các trang xác định, -claim có cấu trúc, provenance, bảng điều khiển và digest máy có thể đọc. +nhận định có cấu trúc, nguồn gốc, bảng điều khiển và bản tóm lược đọc được bằng máy. -Dùng nó khi bạn muốn bộ nhớ hoạt động giống một lớp tri thức được bảo trì hơn và +Dùng nó khi bạn muốn bộ nhớ hoạt động giống một lớp tri thức được duy trì hơn và ít giống một đống tệp Markdown hơn. -## Nó bổ sung gì +## Những gì nó bổ sung - Một kho wiki chuyên dụng với bố cục trang xác định -- Siêu dữ liệu claim và bằng chứng có cấu trúc, không chỉ là văn xuôi -- Provenance, độ tin cậy, mâu thuẫn và câu hỏi mở ở cấp trang -- Digest đã biên dịch cho agent/runtime sử dụng -- Công cụ tìm kiếm/lấy/áp dụng/lint nguyên sinh của wiki -- Chế độ bridge tùy chọn để nhập artifact công khai từ Plugin Active Memory -- Chế độ render thân thiện với Obsidian và tích hợp CLI tùy chọn +- Siêu dữ liệu nhận định và bằng chứng có cấu trúc, không chỉ là văn xuôi +- Nguồn gốc, độ tin cậy, mâu thuẫn và câu hỏi mở ở cấp trang +- Bản tóm lược đã biên dịch cho tác nhân/người dùng runtime +- Công cụ tìm kiếm/lấy/áp dụng/lint dành riêng cho wiki +- Chế độ cầu nối tùy chọn để nhập hiện vật công khai từ Plugin Active Memory +- Chế độ kết xuất thân thiện với Obsidian và tích hợp CLI tùy chọn -## Cách nó khớp với memory +## Cách nó phù hợp với bộ nhớ -Hãy hình dung phần tách lớp như sau: +Hãy hình dung sự phân tách như sau: | Lớp | Sở hữu | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| Plugin Active Memory (`memory-core`, QMD, Honcho, v.v.) | Truy hồi, tìm kiếm ngữ nghĩa, thăng hạng, Dreaming, runtime bộ nhớ | -| `memory-wiki` | Trang wiki đã biên dịch, bản tổng hợp giàu provenance, bảng điều khiển, tìm kiếm/lấy/áp dụng riêng của wiki | +| Plugin Active Memory (`memory-core`, QMD, Honcho, v.v.) | Truy hồi, tìm kiếm ngữ nghĩa, thăng cấp, Dreaming, runtime bộ nhớ | +| `memory-wiki` | Trang wiki đã biên dịch, tổng hợp giàu nguồn gốc, bảng điều khiển, tìm kiếm/lấy/áp dụng riêng cho wiki | -Nếu Plugin Active Memory cung cấp artifact truy hồi dùng chung, OpenClaw có thể tìm kiếm +Nếu Plugin Active Memory hiển thị các hiện vật truy hồi dùng chung, OpenClaw có thể tìm kiếm cả hai lớp trong một lượt với `memory_search corpus=all`. -Khi bạn cần xếp hạng riêng của wiki, provenance hoặc truy cập trang trực tiếp, hãy dùng -các công cụ nguyên sinh của wiki thay thế. +Khi bạn cần xếp hạng dành riêng cho wiki, nguồn gốc hoặc truy cập trang trực tiếp, hãy dùng +các công cụ riêng của wiki thay thế. -## Mẫu hybrid được khuyến nghị +## Mẫu kết hợp được khuyến nghị -Mặc định mạnh cho các thiết lập ưu tiên cục bộ là: +Một mặc định mạnh cho các thiết lập ưu tiên cục bộ là: - QMD làm backend Active Memory cho truy hồi và tìm kiếm ngữ nghĩa rộng -- `memory-wiki` ở chế độ `bridge` cho các trang tri thức tổng hợp bền vững +- `memory-wiki` ở chế độ `bridge` cho các trang tri thức đã tổng hợp bền vững -Phần tách đó hoạt động tốt vì mỗi lớp giữ đúng trọng tâm: +Sự phân tách đó hoạt động tốt vì mỗi lớp vẫn tập trung: -- QMD giữ cho ghi chú thô, bản xuất phiên và các collection bổ sung có thể tìm kiếm -- `memory-wiki` biên dịch entity ổn định, claim, bảng điều khiển và trang nguồn +- QMD giữ cho ghi chú thô, bản xuất phiên và các bộ sưu tập bổ sung có thể tìm kiếm được +- `memory-wiki` biên dịch các thực thể ổn định, nhận định, bảng điều khiển và trang nguồn Quy tắc thực tế: -- dùng `memory_search` khi bạn muốn một lượt truy hồi rộng trên bộ nhớ -- dùng `wiki_search` và `wiki_get` khi bạn muốn kết quả wiki có nhận thức provenance +- dùng `memory_search` khi bạn muốn một lượt truy hồi rộng trên toàn bộ bộ nhớ +- dùng `wiki_search` và `wiki_get` khi bạn muốn kết quả wiki có nhận biết nguồn gốc - dùng `memory_search corpus=all` khi bạn muốn tìm kiếm dùng chung bao phủ cả hai lớp -Nếu chế độ bridge báo cáo không có artifact đã xuất nào, Plugin Active Memory hiện -chưa cung cấp đầu vào bridge công khai. Trước tiên chạy `openclaw wiki doctor`, -sau đó xác nhận Plugin Active Memory hỗ trợ artifact công khai. +Nếu chế độ cầu nối báo cáo không có hiện vật đã xuất nào, Plugin Active Memory hiện +chưa hiển thị đầu vào cầu nối công khai. Chạy `openclaw wiki doctor` trước, +sau đó xác nhận Plugin Active Memory hỗ trợ hiện vật công khai. -Khi chế độ bridge hoạt động và `bridge.readMemoryArtifacts` được bật, +Khi chế độ cầu nối đang hoạt động và `bridge.readMemoryArtifacts` được bật, `openclaw wiki status`, `openclaw wiki doctor` và `openclaw wiki bridge -import` đọc thông qua Gateway đang chạy. Điều đó giữ các kiểm tra bridge của CLI đồng bộ -với ngữ cảnh Plugin memory runtime. Nếu bridge bị tắt hoặc đọc artifact -bị tắt, các lệnh đó giữ hành vi cục bộ/ngoại tuyến. +import` đọc thông qua Gateway đang chạy. Điều đó giữ cho các kiểm tra cầu nối CLI khớp +với ngữ cảnh Plugin bộ nhớ runtime. Nếu cầu nối bị tắt hoặc việc đọc hiện vật +bị tắt, các lệnh đó giữ nguyên hành vi cục bộ/ngoại tuyến. -## Chế độ vault +## Chế độ kho -`memory-wiki` hỗ trợ ba chế độ vault: +`memory-wiki` hỗ trợ ba chế độ kho: ### `isolated` -Vault riêng, nguồn riêng, không phụ thuộc vào `memory-core`. +Kho riêng, nguồn riêng, không phụ thuộc vào `memory-core`. Dùng chế độ này khi bạn muốn wiki là kho tri thức được tuyển chọn riêng. ### `bridge` -Đọc artifact memory công khai và sự kiện memory từ Plugin Active Memory +Đọc hiện vật bộ nhớ công khai và sự kiện bộ nhớ từ Plugin Active Memory thông qua các seam công khai của Plugin SDK. -Dùng chế độ này khi bạn muốn wiki biên dịch và tổ chức các artifact đã xuất -của Plugin memory mà không chạm vào nội bộ Plugin riêng tư. +Dùng chế độ này khi bạn muốn wiki biên dịch và tổ chức các hiện vật đã xuất +của Plugin bộ nhớ mà không truy cập vào phần nội bộ riêng tư của Plugin. -Chế độ bridge có thể lập chỉ mục: +Chế độ cầu nối có thể lập chỉ mục: -- artifact memory đã xuất -- báo cáo dream +- hiện vật bộ nhớ đã xuất +- báo cáo Dreaming - ghi chú hằng ngày -- tệp gốc memory -- nhật ký sự kiện memory +- tệp gốc bộ nhớ +- nhật ký sự kiện bộ nhớ ### `unsafe-local` -Lối thoát rõ ràng trên cùng máy cho đường dẫn cục bộ riêng tư. +Lối thoát rõ ràng trên cùng máy cho các đường dẫn riêng tư cục bộ. -Chế độ này có chủ đích là thử nghiệm và không di động. Chỉ dùng khi bạn -hiểu ranh giới tin cậy và thật sự cần quyền truy cập hệ thống tệp cục bộ mà -chế độ bridge không cung cấp được. +Chế độ này có chủ ý là thử nghiệm và không di động. Chỉ dùng khi bạn +hiểu ranh giới tin cậy và cụ thể cần truy cập hệ thống tệp cục bộ mà +chế độ cầu nối không thể cung cấp. -## Bố cục vault +## Bố cục kho -Plugin khởi tạo một vault như sau: +Plugin khởi tạo một kho như sau: ```text / @@ -136,17 +135,17 @@ Nội dung được quản lý nằm trong các khối đã tạo. Các khối g Các nhóm trang chính là: -- `sources/` cho tư liệu thô đã nhập và các trang được bridge hỗ trợ +- `sources/` cho tài liệu thô đã nhập và các trang dựa trên cầu nối - `entities/` cho những thứ, con người, hệ thống, dự án và đối tượng bền vững -- `concepts/` cho ý tưởng, trừu tượng, mẫu hình và chính sách -- `syntheses/` cho tóm tắt đã biên dịch và rollup được bảo trì +- `concepts/` cho ý tưởng, trừu tượng, mẫu và chính sách +- `syntheses/` cho tóm tắt đã biên dịch và bản tổng hợp được duy trì - `reports/` cho bảng điều khiển đã tạo -## Claim và bằng chứng có cấu trúc +## Nhận định và bằng chứng có cấu trúc -Trang có thể mang frontmatter `claims` có cấu trúc, không chỉ văn bản tự do. +Các trang có thể mang frontmatter `claims` có cấu trúc, không chỉ văn bản tự do. -Mỗi claim có thể bao gồm: +Mỗi nhận định có thể bao gồm: - `id` - `text` @@ -167,31 +166,31 @@ Mục bằng chứng có thể bao gồm: - `note` - `updatedAt` -Đây là điều khiến wiki hoạt động giống một lớp niềm tin hơn là một nơi -đổ ghi chú thụ động. Claim có thể được theo dõi, chấm điểm, phản biện và truy ngược về nguồn. +Đây là điều khiến wiki hoạt động giống một lớp niềm tin hơn là một nơi đổ ghi chú +thụ động. Nhận định có thể được theo dõi, chấm điểm, phản biện và phân giải ngược về nguồn. -## Siêu dữ liệu entity hướng tới agent +## Siêu dữ liệu thực thể hướng tới tác nhân -Trang entity cũng có thể mang siêu dữ liệu định tuyến cho agent sử dụng. Đây là -frontmatter chung, nên nó hoạt động cho con người, nhóm, hệ thống, dự án hoặc bất kỳ -kiểu entity nào khác. +Trang thực thể cũng có thể mang siêu dữ liệu định tuyến để tác nhân sử dụng. Đây là +frontmatter chung, nên nó hoạt động cho người, nhóm, hệ thống, dự án hoặc bất kỳ +kiểu thực thể nào khác. -Các trường thường gặp gồm: +Các trường phổ biến bao gồm: - `entityType`: ví dụ `person`, `team`, `system` hoặc `project` -- `canonicalId`: khóa danh tính ổn định dùng trên alias và lượt nhập +- `canonicalId`: khóa danh tính ổn định được dùng trên các bí danh và bản nhập - `aliases`: tên, handle hoặc nhãn nên phân giải về cùng một trang - `privacyTier`: `public`, `local-private`, `sensitive` hoặc `confirm-before-use` -- `bestUsedFor` / `notEnoughFor`: gợi ý định tuyến ngắn gọn -- `lastRefreshedAt`: dấu thời gian làm mới nguồn tách biệt với thời gian sửa trang -- `personCard`: thẻ định tuyến tùy chọn riêng cho người, với handle, mạng xã hội, - email, múi giờ, lane, ask-for, avoid-asking-for, độ tin cậy và quyền riêng tư +- `bestUsedFor` / `notEnoughFor`: gợi ý định tuyến gọn +- `lastRefreshedAt`: dấu thời gian làm mới nguồn tách biệt với thời gian chỉnh sửa trang +- `personCard`: thẻ định tuyến tùy chọn dành riêng cho người với handle, mạng xã hội, + email, múi giờ, lane, nên hỏi, tránh hỏi, độ tin cậy và quyền riêng tư - `relationships`: cạnh có kiểu tới các trang liên quan với đích, loại, trọng số, - độ tin cậy, loại bằng chứng, tầng quyền riêng tư và ghi chú + độ tin cậy, loại bằng chứng, bậc quyền riêng tư và ghi chú -Với wiki về con người, agent thường nên bắt đầu từ -`reports/person-agent-directory.md`, sau đó mở trang người đó bằng `wiki_get` -trước khi dùng thông tin liên hệ hoặc dữ kiện suy luận. +Với wiki về con người, tác nhân thường nên bắt đầu từ +`reports/person-agent-directory.md`, sau đó mở trang người bằng `wiki_get` +trước khi dùng chi tiết liên hệ hoặc sự kiện suy luận. Ví dụ: @@ -243,27 +242,28 @@ claims: ## Pipeline biên dịch -Bước biên dịch đọc các trang wiki, chuẩn hóa tóm tắt và phát ra các artifact ổn định +Bước biên dịch đọc các trang wiki, chuẩn hóa tóm tắt và phát ra các hiện vật ổn định hướng tới máy dưới: - `.openclaw-wiki/cache/agent-digest.json` - `.openclaw-wiki/cache/claims.jsonl` -Các digest này tồn tại để agent và mã runtime không phải scrape trang Markdown. +Các bản tóm lược này tồn tại để tác nhân và mã runtime không phải thu thập dữ liệu từ +các trang Markdown. -Đầu ra đã biên dịch cũng cung cấp năng lực cho: +Đầu ra đã biên dịch cũng hỗ trợ: - lập chỉ mục wiki lượt đầu cho luồng tìm kiếm/lấy - tra cứu claim-id ngược về trang sở hữu -- phần bổ sung prompt nhỏ gọn +- phần bổ sung prompt gọn - tạo báo cáo/bảng điều khiển ## Bảng điều khiển và báo cáo sức khỏe -Khi `render.createDashboards` được bật, compile duy trì bảng điều khiển trong +Khi `render.createDashboards` được bật, bước biên dịch duy trì bảng điều khiển dưới `reports/`. -Báo cáo tích hợp gồm: +Các báo cáo tích hợp sẵn bao gồm: - `reports/open-questions.md` - `reports/contradictions.md` @@ -278,24 +278,24 @@ Báo cáo tích hợp gồm: Các báo cáo này theo dõi những thứ như: - cụm ghi chú mâu thuẫn -- cụm claim cạnh tranh -- claim thiếu bằng chứng có cấu trúc -- trang và claim có độ tin cậy thấp -- độ mới cũ hoặc không rõ +- cụm nhận định cạnh tranh +- nhận định thiếu bằng chứng có cấu trúc +- trang và nhận định có độ tin cậy thấp +- độ mới đã cũ hoặc không xác định - trang có câu hỏi chưa giải quyết -- thẻ định tuyến person/entity +- thẻ định tuyến người/thực thể - cạnh quan hệ có cấu trúc -- độ phủ lớp bằng chứng -- tầng quyền riêng tư không công khai cần xem xét trước khi dùng +- mức bao phủ lớp bằng chứng +- bậc quyền riêng tư không công khai cần xem xét trước khi dùng -## Tìm kiếm và truy hồi +## Tìm kiếm và truy xuất `memory-wiki` hỗ trợ hai backend tìm kiếm: -- `shared`: dùng luồng tìm kiếm memory dùng chung khi có sẵn +- `shared`: dùng luồng tìm kiếm bộ nhớ dùng chung khi có sẵn - `local`: tìm kiếm wiki cục bộ -Nó cũng hỗ trợ ba corpus: +Nó cũng hỗ trợ ba ngữ liệu: - `wiki` - `memory` @@ -303,36 +303,36 @@ Nó cũng hỗ trợ ba corpus: Hành vi quan trọng: -- `wiki_search` và `wiki_get` dùng digest đã biên dịch làm lượt đầu khi có thể -- id claim có thể phân giải ngược về trang sở hữu -- claim bị phản biện/cũ/mới ảnh hưởng tới xếp hạng -- nhãn provenance có thể được giữ trong kết quả -- chế độ tìm kiếm có thể thiên vị xếp hạng cho tra cứu người, định tuyến câu hỏi, bằng chứng - nguồn hoặc claim thô +- `wiki_search` và `wiki_get` dùng các bản tóm lược đã biên dịch làm lượt đầu khi có thể +- id nhận định có thể phân giải ngược về trang sở hữu +- nhận định bị tranh chấp/đã cũ/mới ảnh hưởng đến xếp hạng +- nhãn nguồn gốc có thể tồn tại trong kết quả +- chế độ tìm kiếm có thể thiên lệch xếp hạng cho tra cứu người, định tuyến câu hỏi, bằng chứng + nguồn hoặc nhận định thô Quy tắc thực tế: - dùng `memory_search corpus=all` cho một lượt truy hồi rộng -- dùng `wiki_search` + `wiki_get` khi bạn quan tâm tới xếp hạng riêng của wiki, - provenance hoặc cấu trúc niềm tin cấp trang +- dùng `wiki_search` + `wiki_get` khi bạn quan tâm đến xếp hạng riêng của wiki, + nguồn gốc hoặc cấu trúc niềm tin cấp trang Chế độ tìm kiếm: - `auto`: mặc định cân bằng -- `find-person`: tăng điểm các entity giống người, alias, handle, mạng xã hội và - ID canonical -- `route-question`: tăng điểm thẻ agent, gợi ý ask-for, gợi ý best-used-for và +- `find-person`: tăng hạng thực thể giống người, bí danh, handle, mạng xã hội và + ID chính tắc +- `route-question`: tăng hạng thẻ tác nhân, gợi ý nên hỏi, gợi ý phù hợp nhất và ngữ cảnh quan hệ -- `source-evidence`: tăng điểm trang nguồn và siêu dữ liệu bằng chứng có cấu trúc -- `raw-claim`: tăng điểm claim có cấu trúc khớp và trả về siêu dữ liệu claim/bằng chứng - trong kết quả +- `source-evidence`: tăng hạng trang nguồn và siêu dữ liệu bằng chứng có cấu trúc +- `raw-claim`: tăng hạng nhận định có cấu trúc khớp và trả về siêu dữ liệu + nhận định/bằng chứng trong kết quả -Khi một kết quả khớp với claim có cấu trúc, `wiki_search` có thể trả về +Khi một kết quả khớp với một nhận định có cấu trúc, `wiki_search` có thể trả về `matchedClaimId`, `matchedClaimStatus`, `matchedClaimConfidence`, `evidenceKinds` và `evidenceSourceIds` trong payload chi tiết của nó. Đầu ra văn bản -cũng bao gồm các dòng `Claim:` và `Evidence:` nhỏ gọn khi có. +cũng bao gồm các dòng `Claim:` và `Evidence:` gọn khi có sẵn. -## Công cụ agent +## Công cụ tác nhân Plugin đăng ký các công cụ này: @@ -344,33 +344,33 @@ Plugin đăng ký các công cụ này: Chúng làm gì: -- `wiki_status`: chế độ vault hiện tại, sức khỏe, khả năng có sẵn của CLI Obsidian -- `wiki_search`: tìm kiếm trang wiki và, khi được cấu hình, corpus memory dùng chung; +- `wiki_status`: chế độ kho hiện tại, sức khỏe, tính khả dụng của CLI Obsidian +- `wiki_search`: tìm kiếm trang wiki và, khi được cấu hình, ngữ liệu bộ nhớ dùng chung; chấp nhận `mode` cho tra cứu người, định tuyến câu hỏi, bằng chứng nguồn hoặc đào sâu - claim thô -- `wiki_get`: đọc trang wiki theo id/path hoặc fallback về corpus memory dùng chung + nhận định thô +- `wiki_get`: đọc trang wiki theo id/đường dẫn hoặc fallback sang ngữ liệu bộ nhớ dùng chung - `wiki_apply`: đột biến tổng hợp/siêu dữ liệu hẹp mà không phẫu thuật trang tự do -- `wiki_lint`: kiểm tra cấu trúc, khoảng trống provenance, mâu thuẫn, câu hỏi mở +- `wiki_lint`: kiểm tra cấu trúc, thiếu hụt nguồn gốc, mâu thuẫn, câu hỏi mở -Plugin cũng đăng ký phần bổ sung corpus memory không độc quyền, để -`memory_search` và `memory_get` dùng chung có thể chạm tới wiki khi Plugin Active Memory -hỗ trợ chọn corpus. +Plugin cũng đăng ký một phần bổ sung ngữ liệu bộ nhớ không độc quyền, để +`memory_search` và `memory_get` dùng chung có thể truy cập wiki khi Plugin Active Memory +hỗ trợ chọn ngữ liệu. -## Hành vi prompt và context +## Hành vi prompt và ngữ cảnh -Khi `context.includeCompiledDigestPrompt` được bật, các phần prompt memory -thêm một snapshot đã biên dịch nhỏ gọn từ `agent-digest.json`. +Khi `context.includeCompiledDigestPrompt` được bật, các phần prompt bộ nhớ +nối thêm một ảnh chụp đã biên dịch gọn từ `agent-digest.json`. -Snapshot đó được chủ đích giữ nhỏ và giàu tín hiệu: +Ảnh chụp đó có chủ ý nhỏ và nhiều tín hiệu: - chỉ các trang hàng đầu -- chỉ các claim hàng đầu +- chỉ các nhận định hàng đầu - số lượng mâu thuẫn - số lượng câu hỏi -- định tính độ tin cậy/độ mới +- bộ định tính độ tin cậy/độ mới -Đây là tùy chọn vì nó thay đổi hình dạng prompt và chủ yếu hữu ích cho engine context -hoặc lắp ráp prompt legacy tiêu thụ rõ ràng các phần bổ sung memory. +Đây là tùy chọn vì nó thay đổi hình dạng prompt và chủ yếu hữu ích cho các +công cụ ngữ cảnh hoặc quá trình lắp ráp prompt cũ tiêu thụ rõ ràng phần bổ sung bộ nhớ. ## Cấu hình @@ -426,26 +426,30 @@ hoặc lắp ráp prompt legacy tiêu thụ rõ ràng các phần bổ sung memo } ``` -Các tùy chọn bật/tắt chính: +Các nút bật/tắt chính: - `vaultMode`: `isolated`, `bridge`, `unsafe-local` - `vault.renderMode`: `native` hoặc `obsidian` - `bridge.readMemoryArtifacts`: nhập các artifact công khai của Plugin Active Memory -- `bridge.followMemoryEvents`: bao gồm nhật ký sự kiện ở chế độ bridge +- `bridge.followMemoryEvents`: bao gồm nhật ký sự kiện trong chế độ bridge - `search.backend`: `shared` hoặc `local` - `search.corpus`: `wiki`, `memory`, hoặc `all` -- `context.includeCompiledDigestPrompt`: thêm ảnh chụp digest nhỏ gọn vào các phần lời nhắc bộ nhớ -- `render.createBacklinks`: tạo các khối liên quan xác định -- `render.createDashboards`: tạo các trang bảng điều khiển +- `context.includeCompiledDigestPrompt`: thêm snapshot tóm tắt gọn vào các phần lời nhắc bộ nhớ +- `render.createBacklinks`: tạo các khối liên quan có tính xác định +- `render.createDashboards`: tạo các trang dashboard ### Ví dụ: QMD + chế độ bridge -Dùng cấu hình này khi bạn muốn QMD để truy hồi và `memory-wiki` làm một lớp tri thức được duy trì: +Dùng cấu hình này khi bạn muốn QMD để truy hồi và `memory-wiki` cho một lớp +tri thức được duy trì: ```json5 { memory: { backend: "qmd", + }, + plugins: { + entries: { "memory-wiki": { enabled: true, config: { @@ -475,8 +479,8 @@ Dùng cấu hình này khi bạn muốn QMD để truy hồi và `memory-wiki` l Cấu hình này giữ: - QMD phụ trách truy hồi Active Memory -- `memory-wiki` tập trung vào các trang đã biên dịch và bảng điều khiển -- hình dạng lời nhắc không đổi cho đến khi bạn chủ động bật lời nhắc digest đã biên dịch +- `memory-wiki` tập trung vào các trang đã biên dịch và dashboard +- hình dạng lời nhắc không đổi cho đến khi bạn chủ động bật lời nhắc tóm tắt đã biên dịch ## CLI @@ -500,7 +504,8 @@ Xem [CLI: wiki](/vi/cli/wiki) để biết tài liệu tham chiếu lệnh đầ ## Hỗ trợ Obsidian -Khi `vault.renderMode` là `obsidian`, Plugin ghi Markdown thân thiện với Obsidian và có thể tùy chọn dùng CLI `obsidian` chính thức. +Khi `vault.renderMode` là `obsidian`, Plugin ghi Markdown thân thiện với Obsidian +và có thể tùy chọn dùng CLI `obsidian` chính thức. Các quy trình được hỗ trợ bao gồm: @@ -508,7 +513,7 @@ Các quy trình được hỗ trợ bao gồm: - tìm kiếm vault - mở một trang - gọi một lệnh Obsidian -- chuyển đến ghi chú hằng ngày +- chuyển tới ghi chú hằng ngày Tính năng này là tùy chọn. Wiki vẫn hoạt động ở chế độ native mà không cần Obsidian. @@ -517,14 +522,14 @@ Tính năng này là tùy chọn. Wiki vẫn hoạt động ở chế độ nati 1. Giữ Plugin Active Memory của bạn cho truy hồi/quảng bá/Dreaming. 2. Bật `memory-wiki`. 3. Bắt đầu với chế độ `isolated` trừ khi bạn rõ ràng muốn chế độ bridge. -4. Dùng `wiki_search` / `wiki_get` khi nguồn gốc quan trọng. -5. Dùng `wiki_apply` cho các tổng hợp hẹp hoặc cập nhật siêu dữ liệu. +4. Dùng `wiki_search` / `wiki_get` khi nguồn gốc dữ liệu là quan trọng. +5. Dùng `wiki_apply` cho các bản tổng hợp hẹp hoặc cập nhật siêu dữ liệu. 6. Chạy `wiki_lint` sau các thay đổi đáng kể. -7. Bật bảng điều khiển nếu bạn muốn hiển thị nội dung lỗi thời/mâu thuẫn. +7. Bật dashboard nếu bạn muốn khả năng hiển thị dữ liệu cũ/mâu thuẫn. ## Tài liệu liên quan -- [Tổng quan về Memory](/vi/concepts/memory) +- [Tổng quan về bộ nhớ](/vi/concepts/memory) - [CLI: memory](/vi/cli/memory) - [CLI: wiki](/vi/cli/wiki) - [Tổng quan Plugin SDK](/vi/plugins/sdk-overview) diff --git a/docs/vi/providers/openrouter.md b/docs/vi/providers/openrouter.md index 5cc322389..062ae88a6 100644 --- a/docs/vi/providers/openrouter.md +++ b/docs/vi/providers/openrouter.md @@ -2,21 +2,21 @@ read_when: - Bạn muốn một khóa API duy nhất cho nhiều LLM - Bạn muốn chạy các mô hình thông qua OpenRouter trong OpenClaw - - Bạn muốn dùng OpenRouter để tạo hình ảnh + - Bạn muốn sử dụng OpenRouter để tạo hình ảnh - Bạn muốn sử dụng OpenRouter để tạo video summary: Sử dụng API hợp nhất của OpenRouter để truy cập nhiều mô hình trong OpenClaw title: OpenRouter x-i18n: - generated_at: "2026-05-02T10:51:28Z" + generated_at: "2026-05-04T02:25:22Z" model: gpt-5.5 provider: openai - source_hash: e98b8b540265b6d11681390c02cb68312f33625bf223823a2dbca17e877c0422 + source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc source_path: providers/openrouter.md workflow: 16 --- -OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu tới nhiều mô hình phía sau một -điểm cuối và khóa API duy nhất. API này tương thích với OpenAI, nên hầu hết SDK OpenAI hoạt động bằng cách chuyển URL cơ sở. +OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu đến nhiều mô hình phía sau một +điểm cuối và khóa API duy nhất. API này tương thích với OpenAI, vì vậy hầu hết SDK OpenAI hoạt động bằng cách chuyển URL cơ sở. ## Bắt đầu @@ -24,13 +24,13 @@ OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu tớ Tạo khóa API tại [openrouter.ai/keys](https://openrouter.ai/keys). - + ```bash openclaw onboard --auth-choice openrouter-api-key ``` - Quy trình thiết lập ban đầu mặc định dùng `openrouter/auto`. Chọn một mô hình cụ thể sau: + Onboarding mặc định là `openrouter/auto`. Chọn một mô hình cụ thể sau: ```bash openclaw models set openrouter// @@ -56,19 +56,19 @@ OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu tớ Tham chiếu mô hình tuân theo mẫu `openrouter//`. Để xem danh sách đầy đủ -các nhà cung cấp và mô hình có sẵn, xem [/concepts/model-providers](/vi/concepts/model-providers). +các nhà cung cấp và mô hình khả dụng, hãy xem [/concepts/model-providers](/vi/concepts/model-providers). Ví dụ dự phòng đi kèm: -| Tham chiếu mô hình | Ghi chú | +| Tham chiếu mô hình | Ghi chú | | --------------------------------- | ---------------------------- | -| `openrouter/auto` | Định tuyến tự động của OpenRouter | +| `openrouter/auto` | Định tuyến tự động OpenRouter | | `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 qua MoonshotAI | ## Tạo hình ảnh -OpenRouter cũng có thể hỗ trợ công cụ `image_generate`. Dùng một mô hình hình ảnh OpenRouter trong `agents.defaults.imageGenerationModel`: +OpenRouter cũng có thể hỗ trợ công cụ `image_generate`. Dùng mô hình hình ảnh OpenRouter trong `agents.defaults.imageGenerationModel`: ```json5 { @@ -84,11 +84,11 @@ OpenRouter cũng có thể hỗ trợ công cụ `image_generate`. Dùng một m } ``` -OpenClaw gửi yêu cầu hình ảnh tới API hình ảnh chat completions của OpenRouter với `modalities: ["image", "text"]`. Các mô hình hình ảnh Gemini nhận các gợi ý `aspectRatio` và `resolution` được hỗ trợ thông qua `image_config` của OpenRouter. Dùng `agents.defaults.imageGenerationModel.timeoutMs` cho các mô hình hình ảnh OpenRouter chậm hơn; tham số `timeoutMs` theo từng lệnh gọi của công cụ `image_generate` vẫn được ưu tiên. +OpenClaw gửi yêu cầu hình ảnh đến API hình ảnh chat completions của OpenRouter với `modalities: ["image", "text"]`. Các mô hình hình ảnh Gemini nhận gợi ý `aspectRatio` và `resolution` được hỗ trợ thông qua `image_config` của OpenRouter. Dùng `agents.defaults.imageGenerationModel.timeoutMs` cho các mô hình hình ảnh OpenRouter chậm hơn; tham số `timeoutMs` theo từng lần gọi của công cụ `image_generate` vẫn được ưu tiên. ## Tạo video -OpenRouter cũng có thể hỗ trợ công cụ `video_generate` thông qua API `/videos` bất đồng bộ của nó. Dùng một mô hình video OpenRouter trong `agents.defaults.videoGenerationModel`: +OpenRouter cũng có thể hỗ trợ công cụ `video_generate` thông qua API `/videos` bất đồng bộ của nó. Dùng mô hình video OpenRouter trong `agents.defaults.videoGenerationModel`: ```json5 { @@ -103,17 +103,17 @@ OpenRouter cũng có thể hỗ trợ công cụ `video_generate` thông qua API } ``` -OpenClaw gửi các tác vụ văn bản thành video và hình ảnh thành video tới OpenRouter, thăm dò -`polling_url` được trả về, rồi tải xuống video đã hoàn tất từ +OpenClaw gửi tác vụ text-to-video và image-to-video đến OpenRouter, thăm dò +`polling_url` được trả về, rồi tải video hoàn tất từ `unsigned_urls` của OpenRouter hoặc điểm cuối nội dung tác vụ được tài liệu hóa. -Theo mặc định, ảnh tham chiếu được gửi dưới dạng ảnh khung đầu/cuối; ảnh -được gắn thẻ `reference_image` được gửi dưới dạng tham chiếu đầu vào OpenRouter. Giá trị mặc định +Theo mặc định, hình ảnh tham chiếu được gửi dưới dạng hình ảnh khung đầu/cuối; hình ảnh +được gắn thẻ `reference_image` được gửi dưới dạng tham chiếu đầu vào OpenRouter. Mặc định `google/veo-3.1-fast` đi kèm công bố các thời lượng 4/6/8 giây hiện được hỗ trợ, độ phân giải `720P`/`1080P`, và tỷ lệ khung hình -`16:9`/`9:16`. Video thành video không được đăng ký cho OpenRouter vì API -tạo video thượng nguồn hiện chỉ chấp nhận tham chiếu văn bản và hình ảnh. +`16:9`/`9:16`. Video-to-video không được đăng ký cho OpenRouter vì API +tạo video thượng nguồn hiện chấp nhận văn bản và tham chiếu hình ảnh. -## Văn bản thành giọng nói +## Text-to-speech OpenRouter cũng có thể được dùng làm nhà cung cấp TTS thông qua điểm cuối `/audio/speech` tương thích với OpenAI. @@ -136,73 +136,105 @@ OpenRouter cũng có thể được dùng làm nhà cung cấp TTS thông qua đ } ``` -Nếu bỏ qua `messages.tts.providers.openrouter.apiKey`, TTS sẽ dùng lại +Nếu bỏ qua `messages.tts.providers.openrouter.apiKey`, TTS sẽ tái sử dụng `models.providers.openrouter.apiKey`, rồi đến `OPENROUTER_API_KEY`. ## Xác thực và header -OpenRouter dùng token Bearer với khóa API của bạn ở bên dưới. +OpenRouter dùng token Bearer với khóa API của bạn bên dưới. Trên các yêu cầu OpenRouter thật (`https://openrouter.ai/api/v1`), OpenClaw cũng thêm -các header gán nguồn ứng dụng được OpenRouter tài liệu hóa: +các header ghi nhận ứng dụng được OpenRouter tài liệu hóa: -| Header | Giá trị | -| ------------------------- | --------------------- | -| `HTTP-Referer` | `https://openclaw.ai` | -| `X-OpenRouter-Title` | `OpenClaw` | -| `X-OpenRouter-Categories` | `cli-agent` | +| Header | Giá trị | +| ------------------------- | ------------------------------------------------------------------------------------------------------ | +| `HTTP-Referer` | `https://openclaw.ai` | +| `X-OpenRouter-Title` | `OpenClaw` | +| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` | -Nếu bạn trỏ lại nhà cung cấp OpenRouter tới một proxy hoặc URL cơ sở khác, OpenClaw -**không** chèn các header dành riêng cho OpenRouter đó hoặc các dấu mốc bộ nhớ đệm Anthropic. +Nếu bạn trỏ lại nhà cung cấp OpenRouter đến một proxy hoặc URL cơ sở khác, OpenClaw +**không** chèn các header riêng cho OpenRouter đó hoặc marker cache của Anthropic. ## Cấu hình nâng cao - + + Bộ nhớ đệm phản hồi OpenRouter là tùy chọn bật rõ ràng. Bật theo từng mô hình OpenRouter bằng + tham số mô hình: + + ```json5 + { + agents: { + defaults: { + models: { + "openrouter/auto": { + params: { + responseCache: true, + responseCacheTtlSeconds: 300, + }, + }, + }, + }, + }, + } + ``` + + OpenClaw gửi `X-OpenRouter-Cache: true` và, khi được cấu hình, + `X-OpenRouter-Cache-TTL`. `responseCacheClear: true` buộc làm mới cho + yêu cầu hiện tại và lưu phản hồi thay thế. Các bí danh snake_case + (`response_cache`, `response_cache_ttl_seconds`, và + `response_cache_clear`) cũng được chấp nhận. + + Cơ chế này tách biệt với bộ nhớ đệm prompt của nhà cung cấp và với các marker + `cache_control` Anthropic của OpenRouter. Nó chỉ được áp dụng trên các tuyến + `openrouter.ai` đã xác minh, không phải URL cơ sở proxy tùy chỉnh. + + + + Trên các tuyến OpenRouter đã xác minh, tham chiếu mô hình Anthropic giữ lại - các dấu mốc `cache_control` Anthropic dành riêng cho OpenRouter mà OpenClaw dùng để - tái sử dụng bộ nhớ đệm prompt tốt hơn trên các khối prompt hệ thống/nhà phát triển. + các marker `cache_control` Anthropic riêng cho OpenRouter mà OpenClaw dùng để + tái sử dụng prompt-cache tốt hơn trên các khối prompt hệ thống/nhà phát triển. - - Trên các tuyến OpenRouter đã xác minh, tham chiếu mô hình Anthropic có bật suy luận - sẽ loại bỏ các lượt điền sẵn assistant ở cuối trước khi yêu cầu tới OpenRouter, - khớp với yêu cầu của Anthropic rằng hội thoại suy luận phải kết thúc bằng một lượt - người dùng. + + Trên các tuyến OpenRouter đã xác minh, tham chiếu mô hình Anthropic có bật reasoning + sẽ bỏ các lượt điền trước assistant ở cuối trước khi yêu cầu đến OpenRouter, + khớp với yêu cầu của Anthropic rằng hội thoại reasoning phải kết thúc bằng lượt của người dùng. - - Trên các tuyến không phải `auto` được hỗ trợ, OpenClaw ánh xạ mức tư duy đã chọn tới - payload suy luận proxy của OpenRouter. Các gợi ý mô hình không được hỗ trợ và - `openrouter/auto` bỏ qua bước chèn suy luận đó. Hunter Alpha cũng bỏ qua - suy luận proxy cho các tham chiếu mô hình đã cấu hình nhưng lỗi thời vì OpenRouter có thể - trả về văn bản câu trả lời cuối trong các trường suy luận cho tuyến đã ngừng dùng đó. + + Trên các tuyến không phải `auto` được hỗ trợ, OpenClaw ánh xạ cấp thinking đã chọn sang + payload reasoning proxy của OpenRouter. Gợi ý mô hình không được hỗ trợ và + `openrouter/auto` bỏ qua việc chèn reasoning đó. Hunter Alpha cũng bỏ qua + reasoning proxy cho các tham chiếu mô hình đã cấu hình nhưng lỗi thời vì OpenRouter có thể + trả về văn bản câu trả lời cuối cùng trong trường reasoning cho tuyến đã ngừng đó. - + Trên các tuyến OpenRouter đã xác minh, `openrouter/deepseek/deepseek-v4-flash` và `openrouter/deepseek/deepseek-v4-pro` điền `reasoning_content` còn thiếu trên - các lượt assistant được phát lại để hội thoại tư duy/công cụ giữ đúng hình dạng + các lượt assistant được phát lại để hội thoại thinking/tool giữ đúng hình dạng theo dõi bắt buộc của DeepSeek V4. - - OpenRouter vẫn chạy qua đường dẫn tương thích OpenAI kiểu proxy, vì vậy - việc định hình yêu cầu chỉ dành cho OpenAI gốc như `serviceTier`, Responses `store`, - payload tương thích suy luận OpenAI, và gợi ý bộ nhớ đệm prompt không được chuyển tiếp. + + OpenRouter vẫn chạy qua đường dẫn tương thích OpenAI kiểu proxy, nên + các định dạng yêu cầu chỉ dành riêng cho OpenAI gốc như `serviceTier`, Responses `store`, + payload tương thích OpenAI reasoning, và gợi ý prompt-cache không được chuyển tiếp. - - Tham chiếu OpenRouter dựa trên Gemini vẫn nằm trên đường dẫn proxy-Gemini: OpenClaw giữ - việc làm sạch chữ ký tư duy Gemini ở đó, nhưng không bật xác thực phát lại Gemini gốc - hoặc viết lại bootstrap. + + Tham chiếu OpenRouter dùng Gemini vẫn ở trên đường dẫn proxy-Gemini: OpenClaw giữ + việc làm sạch thought-signature của Gemini ở đó, nhưng không bật xác thực phát lại Gemini + gốc hoặc viết lại bootstrap. Nếu bạn truyền định tuyến nhà cung cấp OpenRouter trong tham số mô hình, OpenClaw chuyển tiếp - nó dưới dạng siêu dữ liệu định tuyến OpenRouter trước khi các trình bao stream dùng chung chạy. + nó dưới dạng siêu dữ liệu định tuyến OpenRouter trước khi các wrapper stream dùng chung chạy. @@ -210,7 +242,7 @@ Nếu bạn trỏ lại nhà cung cấp OpenRouter tới một proxy hoặc URL - Chọn nhà cung cấp, tham chiếu mô hình, và hành vi chuyển đổi dự phòng. + Chọn nhà cung cấp, tham chiếu mô hình, và hành vi failover. Tham chiếu cấu hình đầy đủ cho agent, mô hình, và nhà cung cấp. diff --git a/docs/vi/security/network-proxy.md b/docs/vi/security/network-proxy.md index 1377e0cc0..3773e1bc4 100644 --- a/docs/vi/security/network-proxy.md +++ b/docs/vi/security/network-proxy.md @@ -1,58 +1,58 @@ --- read_when: - - Bạn muốn phòng thủ theo chiều sâu chống lại các cuộc tấn công SSRF và DNS rebinding + - Bạn muốn phòng thủ theo chiều sâu trước các cuộc tấn công SSRF và tái ràng buộc DNS - Cấu hình proxy chuyển tiếp bên ngoài cho lưu lượng thời gian chạy của OpenClaw -summary: Cách định tuyến lưu lượng HTTP và WebSocket thời gian chạy của OpenClaw qua proxy lọc do người vận hành quản lý +summary: Cách định tuyến lưu lượng HTTP và WebSocket của môi trường chạy OpenClaw qua proxy lọc do người vận hành quản lý title: Proxy mạng x-i18n: - generated_at: "2026-05-01T10:53:02Z" + generated_at: "2026-05-04T02:25:21Z" model: gpt-5.5 provider: openai - source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3 + source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9 source_path: security/network-proxy.md workflow: 16 --- # Proxy mạng -OpenClaw có thể định tuyến lưu lượng HTTP và WebSocket khi chạy qua một proxy chuyển tiếp do người vận hành quản lý. Đây là lớp phòng thủ chiều sâu tùy chọn cho các triển khai muốn kiểm soát lưu lượng ra tập trung, bảo vệ SSRF mạnh hơn và khả năng kiểm toán mạng tốt hơn. +OpenClaw có thể định tuyến lưu lượng HTTP và WebSocket thời gian chạy qua proxy chuyển tiếp do người vận hành quản lý. Đây là lớp phòng thủ chiều sâu tùy chọn cho các triển khai muốn kiểm soát đầu ra tập trung, bảo vệ SSRF mạnh hơn và khả năng kiểm toán mạng tốt hơn. -OpenClaw không cung cấp, tải xuống, khởi động, cấu hình hoặc chứng nhận proxy. Bạn chạy công nghệ proxy phù hợp với môi trường của mình, và OpenClaw định tuyến các client HTTP và WebSocket cục bộ theo tiến trình thông thường qua proxy đó. +OpenClaw không cung cấp, tải xuống, khởi động, cấu hình hoặc chứng nhận proxy. Bạn chạy công nghệ proxy phù hợp với môi trường của mình, và OpenClaw định tuyến các máy khách HTTP và WebSocket cục bộ theo tiến trình thông thường qua proxy đó. ## Vì sao dùng proxy? Proxy cung cấp cho người vận hành một điểm kiểm soát mạng duy nhất cho lưu lượng HTTP và WebSocket đi ra. Điều đó có thể hữu ích ngay cả ngoài việc gia cố chống SSRF: -- Chính sách tập trung: duy trì một chính sách lưu lượng ra thay vì dựa vào từng điểm gọi HTTP của ứng dụng để áp dụng đúng quy tắc mạng. -- Kiểm tra tại thời điểm kết nối: đánh giá đích sau khi phân giải DNS và ngay trước khi proxy mở kết nối ngược dòng. -- Phòng vệ DNS rebinding: giảm khoảng trống giữa kiểm tra DNS ở cấp ứng dụng và kết nối đi ra thực tế. -- Bao phủ JavaScript rộng hơn: định tuyến các client thông thường như `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch và các client tương tự qua cùng một đường dẫn. -- Khả năng kiểm toán: ghi nhật ký các đích được cho phép và bị từ chối tại ranh giới lưu lượng ra. -- Kiểm soát vận hành: thực thi quy tắc đích, phân đoạn mạng, giới hạn tốc độ hoặc danh sách cho phép lưu lượng ra mà không cần dựng lại OpenClaw. +- Chính sách tập trung: duy trì một chính sách đầu ra thay vì dựa vào từng vị trí gọi HTTP của ứng dụng để áp dụng đúng quy tắc mạng. +- Kiểm tra khi kết nối: đánh giá đích sau khi phân giải DNS và ngay trước khi proxy mở kết nối ngược dòng. +- Phòng thủ chống DNS rebinding: giảm khoảng cách giữa kiểm tra DNS ở cấp ứng dụng và kết nối đi ra thực tế. +- Bao phủ JavaScript rộng hơn: định tuyến các máy khách thông thường như `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch và tương tự qua cùng một đường đi. +- Khả năng kiểm toán: ghi lại các đích được cho phép và bị từ chối tại ranh giới đầu ra. +- Kiểm soát vận hành: thực thi quy tắc đích, phân đoạn mạng, giới hạn tốc độ hoặc danh sách cho phép đầu ra mà không cần xây dựng lại OpenClaw. -Định tuyến proxy là hàng rào bảo vệ cấp tiến trình cho lưu lượng HTTP và WebSocket đi ra thông thường. Nó cung cấp cho người vận hành một đường dẫn fail-closed để định tuyến các client HTTP JavaScript được hỗ trợ qua proxy lọc của riêng họ, nhưng đây không phải là sandbox mạng cấp hệ điều hành và không khiến OpenClaw chứng nhận chính sách đích của proxy. +Định tuyến proxy là rào chắn ở cấp tiến trình cho đầu ra HTTP và WebSocket thông thường. Nó cung cấp cho người vận hành một đường fail-closed để định tuyến các máy khách HTTP JavaScript được hỗ trợ qua proxy lọc của riêng họ, nhưng đây không phải là sandbox mạng ở cấp hệ điều hành và không khiến OpenClaw chứng nhận chính sách đích của proxy. ## Cách OpenClaw định tuyến lưu lượng -Khi `proxy.enabled=true` và URL proxy được cấu hình, các tiến trình runtime được bảo vệ như `openclaw gateway run`, `openclaw node run` và `openclaw agent --local` định tuyến lưu lượng HTTP và WebSocket đi ra thông thường qua proxy đã cấu hình: +Khi `proxy.enabled=true` và một URL proxy được cấu hình, các tiến trình thời gian chạy được bảo vệ như `openclaw gateway run`, `openclaw node run` và `openclaw agent --local` định tuyến đầu ra HTTP và WebSocket thông thường qua proxy đã cấu hình: ```text -Tiến trình OpenClaw - fetch -> proxy lọc do người vận hành quản lý -> internet công cộng - node:http và https -> proxy lọc do người vận hành quản lý -> internet công cộng - Client WebSocket -> proxy lọc do người vận hành quản lý -> internet công cộng +OpenClaw process + fetch -> operator-managed filtering proxy -> public internet + node:http and https -> operator-managed filtering proxy -> public internet + WebSocket clients -> operator-managed filtering proxy -> public internet ``` -Hợp đồng công khai là hành vi định tuyến, không phải các hook nội bộ của Node được dùng để triển khai nó. Các client WebSocket mặt phẳng điều khiển của OpenClaw Gateway dùng một đường dẫn trực tiếp hẹp cho lưu lượng RPC Gateway qua local loopback khi URL Gateway dùng `localhost` hoặc một IP loopback dạng literal như `127.0.0.1` hoặc `[::1]`. Đường dẫn mặt phẳng điều khiển đó phải có thể truy cập các Gateway loopback ngay cả khi proxy của người vận hành chặn các đích loopback. Các yêu cầu HTTP và WebSocket runtime thông thường vẫn dùng proxy đã cấu hình. +Hợp đồng công khai là hành vi định tuyến, không phải các hook Node nội bộ dùng để triển khai hành vi đó. Các máy khách WebSocket mặt phẳng điều khiển của OpenClaw Gateway dùng một đường trực tiếp hẹp cho lưu lượng RPC Gateway qua local loopback khi URL Gateway dùng `localhost` hoặc một IP loopback dạng literal như `127.0.0.1` hoặc `[::1]`. Đường mặt phẳng điều khiển đó phải có thể truy cập các Gateway loopback ngay cả khi proxy của người vận hành chặn các đích loopback. Các yêu cầu HTTP và WebSocket thời gian chạy thông thường vẫn dùng proxy đã cấu hình. -Bên trong, OpenClaw dùng hai hook định tuyến cấp tiến trình cho tính năng này: +Bên trong, OpenClaw dùng hai hook định tuyến ở cấp tiến trình cho tính năng này: -- Định tuyến dispatcher của Undici bao phủ `fetch`, các client dựa trên undici và các transport cung cấp dispatcher undici riêng. -- Định tuyến `global-agent` bao phủ các bên gọi Node core `node:http` và `node:https`, bao gồm nhiều thư viện xây trên `http.request`, `https.request`, `http.get` và `https.get`. Chế độ proxy được quản lý ép dùng agent toàn cục đó để các agent HTTP Node tường minh không vô tình bỏ qua proxy của người vận hành. +- Định tuyến dispatcher Undici bao phủ `fetch`, các máy khách dựa trên undici và các transport tự cung cấp dispatcher undici. +- Định tuyến `global-agent` bao phủ các bên gọi Node lõi `node:http` và `node:https`, bao gồm nhiều thư viện xếp lớp trên `http.request`, `https.request`, `http.get` và `https.get`. Chế độ proxy được quản lý ép dùng global agent đó để các agent HTTP Node rõ ràng không vô tình bỏ qua proxy của người vận hành. -Một số Plugin sở hữu transport tùy chỉnh cần nối proxy tường minh ngay cả khi đã có định tuyến cấp tiến trình. Ví dụ, transport Bot API của Telegram dùng dispatcher undici HTTP/1 riêng và vì vậy tôn trọng env proxy của tiến trình cộng với phương án dự phòng `OPENCLAW_PROXY_URL` được quản lý trong đường dẫn transport riêng của chủ sở hữu đó. +Một số plugin sở hữu transport tùy chỉnh cần đấu nối proxy rõ ràng ngay cả khi đã có định tuyến ở cấp tiến trình. Ví dụ, transport Bot API của Telegram dùng dispatcher undici HTTP/1 riêng và do đó tôn trọng env proxy của tiến trình cùng với phương án dự phòng `OPENCLAW_PROXY_URL` được quản lý trong đường transport thuộc chủ sở hữu cụ thể đó. -Bản thân URL proxy phải dùng `http://`. Các đích HTTPS vẫn được hỗ trợ qua proxy bằng HTTP `CONNECT`; điều này chỉ có nghĩa là OpenClaw kỳ vọng một listener proxy chuyển tiếp HTTP thuần như `http://127.0.0.1:3128`. +Chính URL proxy phải dùng `http://`. Các đích HTTPS vẫn được hỗ trợ qua proxy bằng HTTP `CONNECT`; điều này chỉ có nghĩa là OpenClaw kỳ vọng một trình nghe proxy chuyển tiếp HTTP thuần như `http://127.0.0.1:3128`. Trong khi proxy đang hoạt động, OpenClaw xóa `no_proxy`, `NO_PROXY` và `GLOBAL_AGENT_NO_PROXY`. Các danh sách bỏ qua đó dựa trên đích, nên nếu để `localhost` hoặc `127.0.0.1` trong đó thì các mục tiêu SSRF rủi ro cao có thể bỏ qua proxy lọc. @@ -60,10 +60,10 @@ Khi tắt, OpenClaw khôi phục môi trường proxy trước đó và đặt l ## Các thuật ngữ proxy liên quan -- `proxy.enabled` / `proxy.proxyUrl`: định tuyến proxy chuyển tiếp đi ra cho lưu lượng runtime của OpenClaw. Trang này ghi lại tính năng đó. -- `gateway.auth.mode: "trusted-proxy"`: xác thực reverse proxy nhận biết danh tính đi vào cho quyền truy cập Gateway. Xem [xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth). -- `openclaw proxy`: proxy gỡ lỗi cục bộ và trình kiểm tra ghi nhận cho phát triển và hỗ trợ. Xem [openclaw proxy](/vi/cli/proxy). -- Thiết lập proxy riêng theo kênh hoặc nhà cung cấp: các ghi đè riêng của chủ sở hữu cho một transport cụ thể. Ưu tiên proxy mạng được quản lý khi mục tiêu là kiểm soát lưu lượng ra tập trung trên toàn runtime. +- `proxy.enabled` / `proxy.proxyUrl`: định tuyến proxy chuyển tiếp đi ra cho đầu ra thời gian chạy của OpenClaw. Trang này tài liệu hóa tính năng đó. +- `gateway.auth.mode: "trusted-proxy"`: xác thực proxy ngược nhận biết danh tính đi vào cho quyền truy cập Gateway. Xem [Xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth). +- `openclaw proxy`: proxy gỡ lỗi cục bộ và trình kiểm tra bắt lưu lượng cho phát triển và hỗ trợ. Xem [openclaw proxy](/vi/cli/proxy). +- Cài đặt proxy dành riêng cho kênh hoặc nhà cung cấp: các ghi đè thuộc chủ sở hữu cụ thể cho một transport nhất định. Ưu tiên proxy mạng được quản lý khi mục tiêu là kiểm soát đầu ra tập trung trên toàn thời gian chạy. ## Cấu hình @@ -81,9 +81,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run `proxy.proxyUrl` được ưu tiên hơn `OPENCLAW_PROXY_URL`. -Nếu `enabled=true` nhưng không có URL proxy hợp lệ nào được cấu hình, các lệnh được bảo vệ sẽ không khởi động thay vì quay về truy cập mạng trực tiếp. +Nếu `enabled=true` nhưng không có URL proxy hợp lệ được cấu hình, các lệnh được bảo vệ sẽ thất bại khi khởi động thay vì quay về truy cập mạng trực tiếp. -Đối với các dịch vụ gateway được quản lý khởi động bằng `openclaw gateway start`, nên lưu URL trong cấu hình: +Đối với các dịch vụ Gateway được quản lý khởi động bằng `openclaw gateway start`, nên lưu URL trong cấu hình: ```bash openclaw config set proxy.enabled true @@ -92,63 +92,63 @@ openclaw gateway install --force openclaw gateway start ``` -Phương án dự phòng bằng môi trường phù hợp nhất cho các lần chạy tiền cảnh. Nếu bạn dùng nó với một dịch vụ đã cài đặt, hãy đặt `OPENCLAW_PROXY_URL` trong môi trường bền vững của dịch vụ, chẳng hạn `$OPENCLAW_STATE_DIR/.env` hoặc `~/.openclaw/.env`, rồi cài đặt lại dịch vụ để launchd, systemd hoặc Scheduled Tasks khởi động gateway với giá trị đó. +Phương án dự phòng qua môi trường phù hợp nhất cho các lần chạy tiền cảnh. Nếu bạn dùng nó với một dịch vụ đã cài đặt, hãy đặt `OPENCLAW_PROXY_URL` trong môi trường bền vững của dịch vụ, chẳng hạn `$OPENCLAW_STATE_DIR/.env` hoặc `~/.openclaw/.env`, rồi cài đặt lại dịch vụ để launchd, systemd hoặc Scheduled Tasks khởi động Gateway với giá trị đó. -Đối với các lệnh `openclaw --container ...`, OpenClaw chuyển tiếp `OPENCLAW_PROXY_URL` vào CLI con nhắm tới container khi biến này được đặt. URL phải truy cập được từ bên trong container; `127.0.0.1` trỏ tới chính container, không phải host. OpenClaw từ chối các URL proxy loopback cho lệnh nhắm tới container trừ khi bạn ghi đè rõ ràng kiểm tra an toàn đó. +Đối với các lệnh `openclaw --container ...`, OpenClaw chuyển tiếp `OPENCLAW_PROXY_URL` vào CLI con nhắm tới container khi biến này được đặt. URL phải truy cập được từ bên trong container; `127.0.0.1` trỏ tới chính container, không phải máy chủ. OpenClaw từ chối URL proxy loopback cho các lệnh nhắm tới container trừ khi bạn ghi đè rõ ràng kiểm tra an toàn đó. ## Yêu cầu đối với proxy -Chính sách proxy là ranh giới bảo mật. OpenClaw không thể xác minh rằng proxy chặn đúng các mục tiêu. +Chính sách proxy là ranh giới bảo mật. OpenClaw không thể xác minh rằng proxy chặn đúng mục tiêu. Cấu hình proxy để: -- Chỉ bind vào loopback hoặc giao diện riêng đáng tin cậy. -- Hạn chế truy cập để chỉ tiến trình, host, container hoặc tài khoản dịch vụ của OpenClaw có thể dùng nó. +- Chỉ bind vào loopback hoặc một giao diện riêng tư đáng tin cậy. +- Hạn chế quyền truy cập để chỉ tiến trình, máy chủ, container hoặc tài khoản dịch vụ OpenClaw có thể dùng nó. - Tự phân giải đích và chặn IP đích sau khi phân giải DNS. - Áp dụng chính sách tại thời điểm kết nối cho cả yêu cầu HTTP thuần và tunnel HTTPS `CONNECT`. -- Từ chối các cơ chế bỏ qua dựa trên đích đối với loopback, private, link-local, metadata, multicast, reserved hoặc các dải tài liệu. -- Tránh danh sách cho phép hostname trừ khi bạn hoàn toàn tin cậy đường dẫn phân giải DNS. -- Ghi nhật ký đích, quyết định, trạng thái và lý do mà không ghi thân yêu cầu, header ủy quyền, cookie hoặc các bí mật khác. -- Đưa chính sách proxy vào kiểm soát phiên bản và review thay đổi như cấu hình nhạy cảm về bảo mật. +- Từ chối các đường bỏ qua dựa trên đích cho loopback, private, link-local, metadata, multicast, reserved hoặc documentation ranges. +- Tránh danh sách cho phép hostname trừ khi bạn hoàn toàn tin tưởng đường phân giải DNS. +- Ghi lại đích, quyết định, trạng thái và lý do mà không ghi thân yêu cầu, header ủy quyền, cookie hoặc bí mật khác. +- Đặt chính sách proxy dưới kiểm soát phiên bản và rà soát thay đổi như cấu hình nhạy cảm về bảo mật. ## Các đích nên chặn -Dùng danh sách chặn này làm điểm khởi đầu cho bất kỳ proxy chuyển tiếp, tường lửa hoặc chính sách lưu lượng ra nào. +Dùng danh sách từ chối này làm điểm khởi đầu cho mọi proxy chuyển tiếp, tường lửa hoặc chính sách đầu ra. -Logic phân loại cấp ứng dụng của OpenClaw nằm trong `src/infra/net/ssrf.ts` và `src/shared/net/ip.ts`. Các hook tương thích liên quan là `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` và xử lý sentinel IPv4 nhúng cho NAT64, 6to4, Teredo, ISATAP và các dạng IPv4-mapped. Các tệp đó là tài liệu tham khảo hữu ích khi duy trì chính sách proxy bên ngoài, nhưng OpenClaw không tự động xuất hoặc thực thi các quy tắc đó trong proxy của bạn. +Logic phân loại ở cấp ứng dụng của OpenClaw nằm trong `src/infra/net/ssrf.ts` và `src/shared/net/ip.ts`. Các hook tương ứng liên quan là `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` và xử lý sentinel IPv4 nhúng cho NAT64, 6to4, Teredo, ISATAP và các dạng IPv4-mapped. Những tệp đó là tham chiếu hữu ích khi duy trì chính sách proxy bên ngoài, nhưng OpenClaw không tự động xuất hoặc thực thi các quy tắc đó trong proxy của bạn. -| Dải hoặc host | Lý do chặn | -| ------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 | -| `::1/128` | Loopback IPv6 | -| `0.0.0.0/8`, `::/128` | Địa chỉ không xác định và địa chỉ this-network | -| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Mạng riêng RFC1918 | -| `169.254.0.0/16`, `fe80::/10` | Địa chỉ link-local và các đường dẫn metadata đám mây phổ biến | -| `169.254.169.254`, `metadata.google.internal` | Dịch vụ metadata đám mây | -| `100.64.0.0/10` | Không gian địa chỉ chia sẻ NAT cấp nhà mạng | -| `198.18.0.0/15`, `2001:2::/48` | Dải benchmark | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Dải special-use và tài liệu | -| `224.0.0.0/4`, `ff00::/8` | Multicast | -| `240.0.0.0/4` | IPv4 dự trữ | -| `fc00::/7`, `fec0::/10` | Dải IPv6 cục bộ/riêng | -| `100::/64`, `2001:20::/28` | Dải IPv6 discard và ORCHIDv2 | -| `64:ff9b::/96`, `64:ff9b:1::/48` | Tiền tố NAT64 với IPv4 nhúng | -| `2002::/16`, `2001::/32` | 6to4 và Teredo với IPv4 nhúng | -| `::/96`, `::ffff:0:0/96` | IPv6 tương thích IPv4 và IPv6 IPv4-mapped | +| Dải hoặc máy chủ | Vì sao chặn | +| ------------------------------------------------------------------------------------ | ---------------------------------------------------- | +| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 | +| `::1/128` | Loopback IPv6 | +| `0.0.0.0/8`, `::/128` | Địa chỉ không xác định và địa chỉ mạng này | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Mạng riêng RFC1918 | +| `169.254.0.0/16`, `fe80::/10` | Địa chỉ link-local và các đường metadata đám mây phổ biến | +| `169.254.169.254`, `metadata.google.internal` | Dịch vụ metadata đám mây | +| `100.64.0.0/10` | Không gian địa chỉ dùng chung của NAT cấp nhà mạng | +| `198.18.0.0/15`, `2001:2::/48` | Dải benchmark | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Dải dùng đặc biệt và tài liệu | +| `224.0.0.0/4`, `ff00::/8` | Multicast | +| `240.0.0.0/4` | IPv4 dành riêng | +| `fc00::/7`, `fec0::/10` | Dải IPv6 cục bộ/riêng | +| `100::/64`, `2001:20::/28` | Dải discard IPv6 và ORCHIDv2 | +| `64:ff9b::/96`, `64:ff9b:1::/48` | Tiền tố NAT64 với IPv4 nhúng | +| `2002::/16`, `2001::/32` | 6to4 và Teredo với IPv4 nhúng | +| `::/96`, `::ffff:0:0/96` | IPv6 tương thích IPv4 và IPv6 ánh xạ IPv4 | -Nếu nhà cung cấp đám mây hoặc nền tảng mạng của bạn ghi lại thêm các host metadata hoặc dải dự trữ, hãy thêm cả chúng. +Nếu nhà cung cấp đám mây hoặc nền tảng mạng của bạn tài liệu hóa thêm các máy chủ metadata hoặc dải dành riêng, hãy thêm cả những mục đó. ## Xác thực -Xác thực proxy từ cùng host, container hoặc tài khoản dịch vụ chạy OpenClaw: +Xác thực proxy từ cùng máy chủ, container hoặc tài khoản dịch vụ chạy OpenClaw: ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -Theo mặc định, khi không cung cấp đích tùy chỉnh, lệnh kiểm tra rằng `https://example.com/` thành công và khởi động một canary loopback tạm thời mà proxy không được phép truy cập. Kiểm tra bị từ chối mặc định đạt khi proxy trả về phản hồi từ chối không phải 2xx hoặc chặn canary bằng lỗi transport; kiểm tra thất bại nếu một phản hồi thành công tới được canary. Nếu không có proxy nào được bật và cấu hình, quá trình xác thực báo cáo sự cố cấu hình; dùng `--proxy-url` cho một lần kiểm tra trước trước khi thay đổi cấu hình. Dùng `--allowed-url` và `--denied-url` để kiểm thử các kỳ vọng riêng của triển khai. Các đích bị từ chối tùy chỉnh là fail-closed: bất kỳ phản hồi HTTP nào đều có nghĩa là đích có thể truy cập được qua proxy, và bất kỳ lỗi transport nào đều được báo cáo là không kết luận được vì OpenClaw không thể chứng minh proxy đã chặn một origin có thể truy cập. Khi xác thực thất bại, lệnh thoát với mã 1. +Theo mặc định, khi không cung cấp đích tùy chỉnh, lệnh kiểm tra rằng `https://example.com/` thành công và khởi động một canary loopback tạm thời mà proxy không được truy cập. Kiểm tra bị từ chối mặc định đạt khi proxy trả về phản hồi từ chối không phải 2xx hoặc chặn canary bằng lỗi transport; kiểm tra thất bại nếu một phản hồi thành công tới được canary. Nếu không có proxy nào được bật và cấu hình, xác thực báo cáo vấn đề cấu hình; dùng `--proxy-url` cho một lần kiểm tra trước trước khi thay đổi cấu hình. Dùng `--allowed-url` và `--denied-url` để kiểm tra các kỳ vọng dành riêng cho triển khai. Các đích bị từ chối tùy chỉnh là fail-closed: bất kỳ phản hồi HTTP nào cũng có nghĩa là đích truy cập được qua proxy, và mọi lỗi transport được báo cáo là không kết luận được vì OpenClaw không thể chứng minh proxy đã chặn một origin truy cập được. Khi xác thực thất bại, lệnh thoát với mã 1. -Dùng `--json` cho tự động hóa. Đầu ra JSON chứa kết quả tổng thể, nguồn cấu hình proxy hiệu lực, mọi lỗi cấu hình và từng kiểm tra đích. Thông tin xác thực URL proxy được biên tập trong đầu ra văn bản và JSON: +Dùng `--json` cho tự động hóa. Đầu ra JSON chứa kết quả tổng thể, nguồn cấu hình proxy hiệu lực, mọi lỗi cấu hình và từng kiểm tra đích. Thông tin xác thực trong URL proxy được che trong đầu ra văn bản và JSON: ```json { @@ -178,9 +178,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -Yêu cầu công khai sẽ thành công. Các yêu cầu loopback và metadata sẽ bị proxy chặn. Đối với `openclaw proxy validate`, canary loopback tích hợp sẵn có thể phân biệt việc proxy từ chối với một origin có thể truy cập. Các kiểm tra `--denied-url` tùy chỉnh không có canary đó, vì vậy hãy xem cả phản hồi HTTP lẫn lỗi truyền tải mơ hồ là lỗi xác thực, trừ khi proxy của bạn cung cấp một tín hiệu từ chối dành riêng cho triển khai mà bạn có thể xác minh riêng. +Yêu cầu công khai sẽ thành công. Các yêu cầu loopback và metadata sẽ bị proxy chặn. Với `openclaw proxy validate`, canary loopback tích hợp sẵn có thể phân biệt việc proxy từ chối với một origin có thể truy cập. Các kiểm tra `--denied-url` tùy chỉnh không có canary đó, vì vậy hãy xem cả phản hồi HTTP lẫn lỗi vận chuyển mơ hồ là lỗi xác thực, trừ khi proxy của bạn cung cấp tín hiệu từ chối riêng cho triển khai mà bạn có thể xác minh riêng. -Sau đó bật định tuyến proxy của OpenClaw: +Sau đó bật định tuyến proxy OpenClaw: ```bash openclaw config set proxy.enabled true @@ -198,9 +198,10 @@ proxy: ## Giới hạn -- Proxy cải thiện phạm vi bao phủ cho các client HTTP và WebSocket JavaScript cục bộ trong tiến trình, nhưng không phải là sandbox mạng cấp hệ điều hành. -- Các socket `net`, `tls` và `http2` thô, addon native và tiến trình con có thể bỏ qua định tuyến proxy cấp Node, trừ khi chúng kế thừa và tuân thủ các biến môi trường proxy. -- WebUI cục bộ của người dùng và máy chủ mô hình cục bộ nên được đưa vào danh sách cho phép trong chính sách proxy của người vận hành khi cần; OpenClaw không cung cấp cơ chế bỏ qua mạng cục bộ chung cho chúng. -- Việc bỏ qua proxy cho control-plane của Gateway được cố ý giới hạn ở `localhost` và URL IP loopback dạng literal. Dùng `ws://127.0.0.1:18789`, `ws://[::1]:18789`, hoặc `ws://localhost:18789` cho các kết nối control-plane Gateway trực tiếp cục bộ; các tên máy chủ khác được định tuyến như lưu lượng dựa trên tên máy chủ thông thường. -- OpenClaw không kiểm tra, thử nghiệm hoặc chứng nhận chính sách proxy của bạn. -- Hãy xem các thay đổi chính sách proxy là các thay đổi vận hành nhạy cảm về bảo mật. +- Proxy cải thiện độ bao phủ cho các client HTTP và WebSocket JavaScript cục bộ trong tiến trình, nhưng đó không phải là sandbox mạng ở cấp hệ điều hành. +- Các socket `net`, `tls`, và `http2` thô, addon native, và tiến trình con có thể bỏ qua định tuyến proxy cấp Node trừ khi chúng kế thừa và tôn trọng các biến môi trường proxy. +- IRC là một kênh TCP/TLS thô nằm ngoài định tuyến proxy chuyển tiếp do operator quản lý. Trong các triển khai yêu cầu mọi lưu lượng đi ra phải đi qua proxy chuyển tiếp đó, hãy đặt `channels.irc.enabled=false` trừ khi lưu lượng IRC đi ra trực tiếp được phê duyệt rõ ràng. +- WebUI cục bộ của người dùng và máy chủ mô hình cục bộ nên được đưa vào danh sách cho phép trong chính sách proxy của operator khi cần; OpenClaw không cung cấp cơ chế bỏ qua mạng cục bộ tổng quát cho chúng. +- Cơ chế bỏ qua proxy cho mặt phẳng điều khiển Gateway được giới hạn có chủ đích ở `localhost` và các URL IP loopback dạng literal. Hãy dùng `ws://127.0.0.1:18789`, `ws://[::1]:18789`, hoặc `ws://localhost:18789` cho các kết nối mặt phẳng điều khiển Gateway trực tiếp cục bộ; các hostname khác được định tuyến như lưu lượng dựa trên hostname thông thường. +- OpenClaw không kiểm tra, thử nghiệm, hay chứng nhận chính sách proxy của bạn. +- Hãy xem các thay đổi chính sách proxy là những thay đổi vận hành nhạy cảm về bảo mật. diff --git a/docs/vi/tools/llm-task.md b/docs/vi/tools/llm-task.md index 7155a2742..a0c2c4c3c 100644 --- a/docs/vi/tools/llm-task.md +++ b/docs/vi/tools/llm-task.md @@ -1,23 +1,23 @@ --- read_when: - - Bạn muốn một bước LLM chỉ xuất JSON bên trong các quy trình công việc - - Bạn cần đầu ra LLM được xác thực theo schema để tự động hóa + - Bạn muốn một bước LLM chỉ xuất JSON trong các quy trình công việc + - Bạn cần đầu ra LLM được xác thực theo lược đồ để tự động hóa summary: Tác vụ LLM chỉ dùng JSON cho quy trình làm việc (công cụ Plugin tùy chọn) -title: Tác vụ LLM +title: tác vụ LLM x-i18n: - generated_at: "2026-04-29T23:19:39Z" + generated_at: "2026-05-04T02:25:44Z" model: gpt-5.5 provider: openai - source_hash: 613aefd1bac5b9675821a118c11130c8bfaefb1673d0266f14ff4e91b47fed8b + source_hash: 9cdc5d4feef17fb6d6d90d819d4c92d26a4ec43e4f5364c6acbaad1934a89269 source_path: tools/llm-task.md workflow: 16 --- -`llm-task` là một **công cụ Plugin tùy chọn** chạy tác vụ LLM chỉ dùng JSON và +`llm-task` là một **công cụ Plugin tùy chọn** chạy một tác vụ LLM chỉ dùng JSON và trả về đầu ra có cấu trúc (tùy chọn xác thực theo JSON Schema). -Điều này lý tưởng cho các engine quy trình làm việc như Lobster: bạn có thể thêm một bước LLM duy nhất -mà không cần viết mã OpenClaw tùy chỉnh cho từng quy trình làm việc. +Điều này lý tưởng cho các công cụ workflow như Lobster: bạn có thể thêm một bước LLM duy nhất +mà không cần viết mã OpenClaw tùy chỉnh cho từng workflow. ## Bật Plugin @@ -33,21 +33,18 @@ mà không cần viết mã OpenClaw tùy chỉnh cho từng quy trình làm vi } ``` -2. Đưa công cụ vào danh sách cho phép (công cụ được đăng ký với `optional: true`): +2. Cho phép công cụ tùy chọn: ```json { - "agents": { - "list": [ - { - "id": "main", - "tools": { "allow": ["llm-task"] } - } - ] + "tools": { + "alsoAllow": ["llm-task"] } } ``` +Chỉ dùng `tools.allow` khi bạn muốn chế độ danh sách cho phép hạn chế. + ## Cấu hình (tùy chọn) ```json @@ -75,16 +72,16 @@ nằm ngoài danh sách sẽ bị từ chối. ## Tham số công cụ -- `prompt` (chuỗi, bắt buộc) -- `input` (bất kỳ, tùy chọn) -- `schema` (đối tượng, JSON Schema tùy chọn) -- `provider` (chuỗi, tùy chọn) -- `model` (chuỗi, tùy chọn) -- `thinking` (chuỗi, tùy chọn) -- `authProfileId` (chuỗi, tùy chọn) -- `temperature` (số, tùy chọn) -- `maxTokens` (số, tùy chọn) -- `timeoutMs` (số, tùy chọn) +- `prompt` (string, bắt buộc) +- `input` (any, tùy chọn) +- `schema` (object, JSON Schema tùy chọn) +- `provider` (string, tùy chọn) +- `model` (string, tùy chọn) +- `thinking` (string, tùy chọn) +- `authProfileId` (string, tùy chọn) +- `temperature` (number, tùy chọn) +- `maxTokens` (number, tùy chọn) +- `timeoutMs` (number, tùy chọn) `thinking` chấp nhận các preset suy luận tiêu chuẩn của OpenClaw, chẳng hạn như `low` hoặc `medium`. @@ -93,7 +90,7 @@ nằm ngoài danh sách sẽ bị từ chối. Trả về `details.json` chứa JSON đã phân tích cú pháp (và xác thực theo `schema` khi được cung cấp). -## Ví dụ: bước quy trình làm việc Lobster +## Ví dụ: bước workflow Lobster ```lobster openclaw.invoke --tool llm-task --action json --args-json '{ @@ -118,13 +115,13 @@ openclaw.invoke --tool llm-task --action json --args-json '{ ## Ghi chú an toàn - Công cụ này **chỉ dùng JSON** và hướng dẫn mô hình chỉ xuất JSON (không có - code fences, không có bình luận). -- Không có công cụ nào được cung cấp cho mô hình trong lần chạy này. + code fence, không có bình luận). +- Không công cụ nào được cung cấp cho mô hình trong lần chạy này. - Xem đầu ra là không đáng tin cậy trừ khi bạn xác thực bằng `schema`. -- Đặt phê duyệt trước mọi bước có tác dụng phụ (send, post, exec). +- Đặt phê duyệt trước bất kỳ bước nào có tác động phụ (gửi, đăng, thực thi). ## Liên quan - [Mức thinking](/vi/tools/thinking) -- [Sub-agent](/vi/tools/subagents) +- [Sub-agents](/vi/tools/subagents) - [Lệnh slash](/vi/tools/slash-commands) diff --git a/docs/vi/tools/lobster.md b/docs/vi/tools/lobster.md index c526e15f7..22230aa18 100644 --- a/docs/vi/tools/lobster.md +++ b/docs/vi/tools/lobster.md @@ -1,52 +1,52 @@ --- read_when: - - Bạn muốn các quy trình công việc nhiều bước có tính xác định với các phê duyệt rõ ràng + - Bạn muốn các quy trình làm việc nhiều bước có tính xác định với các phê duyệt rõ ràng - Bạn cần tiếp tục một quy trình làm việc mà không chạy lại các bước trước đó -summary: Runtime quy trình công việc có kiểu cho OpenClaw với các cổng phê duyệt có thể tiếp tục. +summary: Môi trường chạy quy trình làm việc có kiểu cho OpenClaw với các cổng phê duyệt có thể tiếp tục. title: Tôm hùm x-i18n: - generated_at: "2026-04-29T23:19:37Z" + generated_at: "2026-05-04T02:25:49Z" model: gpt-5.5 provider: openai - source_hash: 1700bcfdbcf4558cb908935834e9059221d0d26ad78ed6f9e2158f7e0b83edbd + source_hash: 67f5145b11f2d6e07e9d78a44a389ae5f236c85ec8c287ab0f217a18b622ece0 source_path: tools/lobster.md workflow: 16 --- -Lobster là một workflow shell cho phép OpenClaw chạy các chuỗi công cụ nhiều bước như một thao tác đơn lẻ, xác định, với các điểm kiểm tra phê duyệt rõ ràng. +Lobster là một shell quy trình làm việc cho phép OpenClaw chạy các chuỗi công cụ nhiều bước như một thao tác đơn lẻ, xác định, với các điểm kiểm duyệt phê duyệt rõ ràng. -Lobster là một lớp soạn thảo phía trên công việc nền tách rời. Để điều phối luồng phía trên các tác vụ riêng lẻ, xem [Task Flow](/vi/automation/taskflow) (`openclaw tasks flow`). Để xem sổ cái hoạt động tác vụ, xem [`openclaw tasks`](/vi/automation/tasks). +Lobster là một lớp biên soạn nằm trên công việc nền tách rời. Để điều phối luồng ở trên các tác vụ riêng lẻ, xem [Task Flow](/vi/automation/taskflow) (`openclaw tasks flow`). Để xem sổ cái hoạt động tác vụ, xem [`openclaw tasks`](/vi/automation/tasks). -## Hook +## Móc -Trợ lý của bạn có thể xây dựng các công cụ tự quản lý chính nó. Hãy yêu cầu một workflow, và 30 phút sau bạn có một CLI cùng các pipeline chạy trong một lệnh gọi duy nhất. Lobster là mảnh ghép còn thiếu: các pipeline xác định, phê duyệt rõ ràng, và trạng thái có thể tiếp tục. +Trợ lý của bạn có thể xây dựng các công cụ tự quản lý chính nó. Yêu cầu một quy trình làm việc, và 30 phút sau bạn có một CLI cùng các pipeline chạy như một lệnh gọi duy nhất. Lobster là mảnh ghép còn thiếu: pipeline xác định, phê duyệt rõ ràng và trạng thái có thể tiếp tục. -## Vì sao +## Tại sao -Hiện nay, các workflow phức tạp cần nhiều lượt gọi công cụ qua lại. Mỗi lệnh gọi tốn token, và LLM phải điều phối từng bước. Lobster chuyển phần điều phối đó vào một runtime có kiểu: +Hiện nay, các quy trình làm việc phức tạp đòi hỏi nhiều lượt gọi công cụ qua lại. Mỗi lệnh gọi tốn token, và LLM phải điều phối từng bước. Lobster chuyển phần điều phối đó vào một runtime có kiểu: - **Một lệnh gọi thay vì nhiều lệnh gọi**: OpenClaw chạy một lệnh gọi công cụ Lobster và nhận kết quả có cấu trúc. -- **Phê duyệt tích hợp sẵn**: Các hiệu ứng phụ (gửi email, đăng bình luận) sẽ tạm dừng workflow cho đến khi được phê duyệt rõ ràng. -- **Có thể tiếp tục**: Các workflow bị tạm dừng trả về một token; phê duyệt và tiếp tục mà không cần chạy lại mọi thứ. +- **Tích hợp sẵn phê duyệt**: Tác dụng phụ (gửi email, đăng bình luận) tạm dừng quy trình làm việc cho đến khi được phê duyệt rõ ràng. +- **Có thể tiếp tục**: Quy trình làm việc bị tạm dừng trả về một token; phê duyệt và tiếp tục mà không chạy lại mọi thứ. -## Vì sao dùng DSL thay vì chương trình thông thường? +## Tại sao dùng DSL thay vì chương trình thông thường? -Lobster được cố ý thiết kế nhỏ gọn. Mục tiêu không phải là "một ngôn ngữ mới", mà là một đặc tả pipeline dễ dự đoán, thân thiện với AI, có phê duyệt hạng nhất và token tiếp tục. +Lobster được cố ý giữ nhỏ. Mục tiêu không phải là "một ngôn ngữ mới", mà là một đặc tả pipeline dễ dự đoán, thân thiện với AI, có phê duyệt và token tiếp tục như thành phần hạng nhất. - **Phê duyệt/tiếp tục được tích hợp sẵn**: Một chương trình bình thường có thể nhắc con người, nhưng không thể _tạm dừng và tiếp tục_ bằng một token bền vững nếu bạn không tự phát minh runtime đó. -- **Tính xác định + khả năng kiểm toán**: Pipeline là dữ liệu, nên dễ ghi log, so sánh diff, phát lại và rà soát. -- **Bề mặt bị giới hạn cho AI**: Một ngữ pháp nhỏ + JSON piping giảm các đường đi mã “sáng tạo” và giúp việc xác thực trở nên thực tế. -- **Chính sách an toàn được tích hợp**: Thời gian chờ, giới hạn đầu ra, kiểm tra sandbox, và allowlist được runtime thực thi, không phải từng script. +- **Tính xác định + khả năng kiểm toán**: Pipeline là dữ liệu, nên dễ ghi log, so sánh khác biệt, phát lại và rà soát. +- **Bề mặt bị giới hạn cho AI**: Một ngữ pháp nhỏ + truyền JSON giảm các nhánh mã “sáng tạo” và giúp việc xác thực thực tế hơn. +- **Chính sách an toàn được nhúng sẵn**: Timeout, giới hạn đầu ra, kiểm tra sandbox và allowlist được runtime thực thi, không phải từng script. - **Vẫn lập trình được**: Mỗi bước có thể gọi bất kỳ CLI hoặc script nào. Nếu bạn muốn JS/TS, hãy sinh các tệp `.lobster` từ mã. ## Cách hoạt động -OpenClaw chạy các workflow Lobster **trong tiến trình** bằng một runner nhúng. Không có subprocess CLI bên ngoài nào được sinh ra; engine workflow thực thi bên trong tiến trình gateway và trả về trực tiếp một phong bì JSON. -Nếu pipeline tạm dừng để phê duyệt, công cụ trả về một `resumeToken` để bạn có thể tiếp tục sau. +OpenClaw chạy các quy trình làm việc Lobster **trong tiến trình** bằng một runner nhúng. Không sinh tiến trình con CLI bên ngoài; engine quy trình làm việc thực thi bên trong tiến trình Gateway và trả trực tiếp một phong bì JSON. +Nếu pipeline tạm dừng để chờ phê duyệt, công cụ trả về một `resumeToken` để bạn có thể tiếp tục sau. -## Mẫu: CLI nhỏ + JSON pipe + phê duyệt +## Mẫu: CLI nhỏ + ống JSON + phê duyệt -Xây dựng các lệnh nhỏ giao tiếp bằng JSON, rồi nối chúng thành một lệnh gọi Lobster duy nhất. (Các tên lệnh ví dụ bên dưới — thay bằng tên của bạn.) +Xây dựng các lệnh nhỏ giao tiếp bằng JSON, rồi nối chúng thành một lệnh gọi Lobster duy nhất. (Tên lệnh ví dụ bên dưới — thay bằng tên của bạn.) ```bash inbox list --json @@ -62,7 +62,7 @@ inbox apply --json } ``` -Nếu pipeline yêu cầu phê duyệt, hãy tiếp tục bằng token: +Nếu pipeline yêu cầu phê duyệt, tiếp tục bằng token: ```json { @@ -72,20 +72,20 @@ Nếu pipeline yêu cầu phê duyệt, hãy tiếp tục bằng token: } ``` -AI kích hoạt workflow; Lobster thực thi các bước. Các cổng phê duyệt giữ cho hiệu ứng phụ rõ ràng và có thể kiểm toán. +AI kích hoạt quy trình làm việc; Lobster thực thi các bước. Cổng phê duyệt giữ cho tác dụng phụ rõ ràng và có thể kiểm toán. -Ví dụ: ánh xạ các mục đầu vào thành các lệnh gọi công cụ: +Ví dụ: ánh xạ các mục đầu vào thành lệnh gọi công cụ: ```bash gog.gmail.search --query 'newer_than:1d' \ | openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}' ``` -## Các bước LLM chỉ dùng JSON (llm-task) +## Bước LLM chỉ dùng JSON (llm-task) -Đối với các workflow cần một **bước LLM có cấu trúc**, hãy bật công cụ plugin tùy chọn -`llm-task` và gọi nó từ Lobster. Cách này giữ workflow -xác định trong khi vẫn cho phép bạn phân loại/tóm tắt/soạn nháp bằng mô hình. +Đối với các quy trình làm việc cần một **bước LLM có cấu trúc**, hãy bật công cụ Plugin tùy chọn +`llm-task` và gọi nó từ Lobster. Cách này giữ cho quy trình làm việc +xác định, đồng thời vẫn cho phép bạn phân loại/tóm tắt/soạn thảo bằng mô hình. Bật công cụ: @@ -100,14 +100,14 @@ Bật công cụ: "list": [ { "id": "main", - "tools": { "allow": ["llm-task"] } + "tools": { "alsoAllow": ["llm-task"] } } ] } } ``` -Dùng nó trong một pipeline: +Dùng trong một pipeline: ```lobster openclaw.invoke --tool llm-task --action json --args-json '{ @@ -126,11 +126,11 @@ openclaw.invoke --tool llm-task --action json --args-json '{ }' ``` -Xem [LLM Task](/vi/tools/llm-task) để biết chi tiết và các tùy chọn cấu hình. +Xem [LLM Task](/vi/tools/llm-task) để biết chi tiết và tùy chọn cấu hình. -## Tệp workflow (.lobster) +## Tệp quy trình làm việc (.lobster) -Lobster có thể chạy các tệp workflow YAML/JSON với các trường `name`, `args`, `steps`, `env`, `condition`, và `approval`. Trong các lệnh gọi công cụ OpenClaw, đặt `pipeline` thành đường dẫn tệp. +Lobster có thể chạy các tệp quy trình làm việc YAML/JSON với các trường `name`, `args`, `steps`, `env`, `condition` và `approval`. Trong lệnh gọi công cụ OpenClaw, đặt `pipeline` thành đường dẫn tệp. ```yaml name: inbox-triage @@ -156,17 +156,17 @@ steps: Ghi chú: - `stdin: $step.stdout` và `stdin: $step.json` truyền đầu ra của một bước trước đó. -- `condition` (hoặc `when`) có thể chặn/mở các bước dựa trên `$step.approved`. +- `condition` (hoặc `when`) có thể chặn/mở bước dựa trên `$step.approved`. ## Cài đặt Lobster -Các workflow Lobster đi kèm chạy trong tiến trình; không cần binary `lobster` riêng. Runner nhúng được phát hành cùng plugin Lobster. +Các quy trình làm việc Lobster đi kèm chạy trong tiến trình; không cần binary `lobster` riêng. Runner nhúng được phân phối cùng Plugin Lobster. -Nếu bạn cần CLI Lobster độc lập để phát triển hoặc chạy pipeline bên ngoài, hãy cài đặt từ [repo Lobster](https://github.com/openclaw/lobster) và đảm bảo `lobster` nằm trong `PATH`. +Nếu bạn cần CLI Lobster độc lập để phát triển hoặc cho pipeline bên ngoài, hãy cài đặt từ [repo Lobster](https://github.com/openclaw/lobster) và đảm bảo `lobster` nằm trên `PATH`. ## Bật công cụ -Lobster là một công cụ plugin **tùy chọn** (không được bật mặc định). +Lobster là một công cụ Plugin **tùy chọn** (không được bật mặc định). Khuyến nghị (bổ sung, an toàn): @@ -195,10 +195,10 @@ Hoặc theo từng agent: } ``` -Tránh dùng `tools.allow: ["lobster"]` trừ khi bạn có ý định chạy ở chế độ allowlist hạn chế. +Tránh dùng `tools.allow: ["lobster"]` trừ khi bạn định chạy ở chế độ allowlist hạn chế. -Allowlist là cơ chế chọn bật cho các plugin tùy chọn. Nếu allowlist của bạn chỉ nêu tên các công cụ plugin (như `lobster`), OpenClaw vẫn giữ các công cụ lõi được bật. Để hạn chế các công cụ lõi, hãy đưa cả các công cụ lõi hoặc nhóm công cụ bạn muốn vào allowlist. +Allowlist là cơ chế tùy chọn cho các Plugin tùy chọn. `alsoAllow` chỉ bật các công cụ Plugin tùy chọn được nêu tên trong khi vẫn giữ bộ công cụ lõi thông thường. Để giới hạn công cụ lõi, hãy dùng `tools.allow` với các công cụ hoặc nhóm lõi bạn muốn. ## Ví dụ: Phân loại email @@ -252,7 +252,7 @@ Người dùng phê duyệt → tiếp tục: } ``` -Một workflow. Xác định. An toàn. +Một quy trình làm việc. Xác định. An toàn. ## Tham số công cụ @@ -270,7 +270,7 @@ Chạy một pipeline ở chế độ công cụ. } ``` -Chạy một tệp workflow với args: +Chạy tệp quy trình làm việc với đối số: ```json { @@ -282,7 +282,7 @@ Chạy một tệp workflow với args: ### `resume` -Tiếp tục một workflow đã tạm dừng sau khi phê duyệt. +Tiếp tục một quy trình làm việc bị tạm dừng sau khi phê duyệt. ```json { @@ -294,10 +294,10 @@ Tiếp tục một workflow đã tạm dừng sau khi phê duyệt. ### Đầu vào tùy chọn -- `cwd`: Thư mục làm việc tương đối cho pipeline (phải nằm trong thư mục làm việc của gateway). -- `timeoutMs`: Hủy workflow nếu vượt quá khoảng thời gian này (mặc định: 20000). -- `maxStdoutBytes`: Hủy workflow nếu đầu ra vượt quá kích thước này (mặc định: 512000). -- `argsJson`: Chuỗi JSON được truyền cho `lobster run --args-json` (chỉ với tệp workflow). +- `cwd`: Thư mục làm việc tương đối cho pipeline (phải nằm trong thư mục làm việc của Gateway). +- `timeoutMs`: Hủy quy trình làm việc nếu vượt quá thời lượng này (mặc định: 20000). +- `maxStdoutBytes`: Hủy quy trình làm việc nếu đầu ra vượt quá kích thước này (mặc định: 512000). +- `argsJson`: Chuỗi JSON được truyền cho `lobster run --args-json` (chỉ với tệp quy trình làm việc). ## Phong bì đầu ra @@ -307,49 +307,49 @@ Lobster trả về một phong bì JSON với một trong ba trạng thái: - `needs_approval` → đã tạm dừng; cần `requiresApproval.resumeToken` để tiếp tục - `cancelled` → bị từ chối hoặc hủy rõ ràng -Công cụ hiển thị phong bì trong cả `content` (JSON được trình bày đẹp) và `details` (đối tượng thô). +Công cụ hiển thị phong bì trong cả `content` (JSON được định dạng đẹp) và `details` (đối tượng thô). ## Phê duyệt -Nếu có `requiresApproval`, hãy xem prompt và quyết định: +Nếu có `requiresApproval`, hãy xem lời nhắc và quyết định: -- `approve: true` → tiếp tục và thực hiện các hiệu ứng phụ -- `approve: false` → hủy và hoàn tất workflow +- `approve: true` → tiếp tục và thực hiện tiếp tác dụng phụ +- `approve: false` → hủy và hoàn tất quy trình làm việc -Dùng `approve --preview-from-stdin --limit N` để đính kèm bản xem trước JSON vào các yêu cầu phê duyệt mà không cần keo nối jq/heredoc tùy chỉnh. Token tiếp tục hiện đã gọn: Lobster lưu trạng thái tiếp tục workflow trong thư mục trạng thái của nó và trả lại một khóa token nhỏ. +Dùng `approve --preview-from-stdin --limit N` để đính kèm bản xem trước JSON vào yêu cầu phê duyệt mà không cần keo nối jq/heredoc tùy chỉnh. Token tiếp tục hiện đã gọn: Lobster lưu trạng thái tiếp tục quy trình làm việc trong thư mục trạng thái của nó và trả về một khóa token nhỏ. ## OpenProse -OpenProse kết hợp tốt với Lobster: dùng `/prose` để điều phối phần chuẩn bị đa agent, rồi chạy một pipeline Lobster cho các phê duyệt xác định. Nếu một chương trình Prose cần Lobster, hãy cho phép công cụ `lobster` cho các sub-agent qua `tools.subagents.tools`. Xem [OpenProse](/vi/prose). +OpenProse kết hợp tốt với Lobster: dùng `/prose` để điều phối bước chuẩn bị nhiều agent, rồi chạy một pipeline Lobster để phê duyệt xác định. Nếu một chương trình Prose cần Lobster, hãy cho phép công cụ `lobster` cho các sub-agent qua `tools.subagents.tools`. Xem [OpenProse](/vi/prose). ## An toàn -- **Chỉ cục bộ trong tiến trình** — workflow thực thi bên trong tiến trình gateway; bản thân plugin không thực hiện lệnh gọi mạng. -- **Không chứa bí mật** — Lobster không quản lý OAuth; nó gọi các công cụ OpenClaw làm việc đó. -- **Nhận biết sandbox** — bị tắt khi ngữ cảnh công cụ đang ở trong sandbox. -- **Được gia cố** — thời gian chờ và giới hạn đầu ra được runner nhúng thực thi. +- **Chỉ trong tiến trình cục bộ** — quy trình làm việc thực thi bên trong tiến trình Gateway; bản thân Plugin không thực hiện lệnh gọi mạng. +- **Không có bí mật** — Lobster không quản lý OAuth; nó gọi các công cụ OpenClaw làm việc đó. +- **Nhận biết sandbox** — bị tắt khi ngữ cảnh công cụ ở trong sandbox. +- **Được gia cố** — timeout và giới hạn đầu ra được runner nhúng thực thi. ## Khắc phục sự cố - **`lobster timed out`** → tăng `timeoutMs`, hoặc tách một pipeline dài. - **`lobster output exceeded maxStdoutBytes`** → tăng `maxStdoutBytes` hoặc giảm kích thước đầu ra. - **`lobster returned invalid JSON`** → đảm bảo pipeline chạy ở chế độ công cụ và chỉ in JSON. -- **`lobster failed`** → kiểm tra log gateway để xem chi tiết lỗi của runner nhúng. +- **`lobster failed`** → kiểm tra log Gateway để biết chi tiết lỗi của runner nhúng. ## Tìm hiểu thêm - [Plugins](/vi/tools/plugin) -- [Soạn thảo công cụ plugin](/vi/plugins/building-plugins#registering-agent-tools) +- [Biên soạn công cụ Plugin](/vi/plugins/building-plugins#registering-agent-tools) -## Nghiên cứu tình huống: workflow cộng đồng +## Nghiên cứu tình huống: quy trình làm việc cộng đồng -Một ví dụ công khai: một CLI “second brain” + các pipeline Lobster quản lý ba kho Markdown (cá nhân, đối tác, dùng chung). CLI phát JSON cho thống kê, danh sách inbox, và quét nội dung cũ; Lobster nối các lệnh đó thành các workflow như `weekly-review`, `inbox-triage`, `memory-consolidation`, và `shared-task-sync`, mỗi workflow đều có cổng phê duyệt. AI xử lý phán đoán (phân loại) khi có sẵn và rơi về các quy tắc xác định khi không có. +Một ví dụ công khai: một CLI “bộ não thứ hai” + các pipeline Lobster quản lý ba kho Markdown (cá nhân, đối tác, dùng chung). CLI phát JSON cho thống kê, danh sách hộp thư đến và quét nội dung cũ; Lobster nối các lệnh đó thành các quy trình làm việc như `weekly-review`, `inbox-triage`, `memory-consolidation` và `shared-task-sync`, mỗi quy trình có cổng phê duyệt. AI xử lý phần phán đoán (phân loại) khi có sẵn và quay về các quy tắc xác định khi không có. - Chủ đề: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033) - Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli) ## Liên quan -- [Tự động hóa & Tác vụ](/vi/automation) — lên lịch các workflow Lobster -- [Tổng quan Tự động hóa](/vi/automation) — tất cả cơ chế tự động hóa -- [Tổng quan Công cụ](/vi/tools) — tất cả công cụ agent có sẵn +- [Tự động hóa & Tác vụ](/vi/automation) — lên lịch quy trình làm việc Lobster +- [Tổng quan tự động hóa](/vi/automation) — tất cả cơ chế tự động hóa +- [Tổng quan công cụ](/vi/tools) — tất cả công cụ agent có sẵn diff --git a/docs/vi/tools/slash-commands.md b/docs/vi/tools/slash-commands.md index 6dcc2a411..557a3e556 100644 --- a/docs/vi/tools/slash-commands.md +++ b/docs/vi/tools/slash-commands.md @@ -3,20 +3,20 @@ read_when: - Sử dụng hoặc cấu hình các lệnh trò chuyện - Gỡ lỗi định tuyến lệnh hoặc quyền sidebarTitle: Slash commands -summary: 'Lệnh dấu gạch chéo: dạng văn bản so với dạng gốc, cấu hình và các lệnh được hỗ trợ' +summary: 'Lệnh dấu gạch chéo: văn bản so với lệnh gốc, cấu hình và các lệnh được hỗ trợ' title: Lệnh dấu gạch chéo x-i18n: - generated_at: "2026-05-03T21:37:30Z" + generated_at: "2026-05-04T02:26:07Z" model: gpt-5.5 provider: openai - source_hash: 9fbdd76ccd43159cabfbc3f15f7bddd2a7ada07fcd6eea2e169d2d88df18f28c + source_hash: 49eb41674c8d0a01dbd28a2df783eb9aba3dde18d8425951a266cede825e9a84 source_path: tools/slash-commands.md workflow: 16 --- -Các lệnh được Gateway xử lý. Hầu hết các lệnh phải được gửi dưới dạng một tin nhắn **độc lập** bắt đầu bằng `/`. Lệnh trò chuyện bash chỉ dành cho máy chủ dùng `! ` (với `/bash ` làm bí danh). +Các lệnh được xử lý bởi Gateway. Hầu hết lệnh phải được gửi dưới dạng một tin nhắn **độc lập** bắt đầu bằng `/`. Lệnh trò chuyện bash chỉ dành cho máy chủ dùng `! ` (với `/bash ` là bí danh). -Khi một cuộc trò chuyện hoặc luồng được gắn với một phiên ACP, văn bản theo dõi thông thường sẽ được định tuyến đến harness ACP đó. Các lệnh quản lý Gateway vẫn ở cục bộ: `/acp ...` luôn đến trình xử lý lệnh ACP của OpenClaw, và `/status` cùng `/unfocus` vẫn ở cục bộ bất cứ khi nào xử lý lệnh được bật cho bề mặt đó. +Khi một cuộc trò chuyện hoặc luồng được liên kết với một phiên ACP, văn bản theo dõi thông thường sẽ được định tuyến tới harness ACP đó. Các lệnh quản lý Gateway vẫn giữ cục bộ: `/acp ...` luôn đến trình xử lý lệnh ACP của OpenClaw, còn `/status` cùng `/unfocus` vẫn giữ cục bộ bất cứ khi nào xử lý lệnh được bật cho bề mặt đó. Có hai hệ thống liên quan: @@ -27,16 +27,16 @@ Có hai hệ thống liên quan: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - - Chỉ thị được loại khỏi tin nhắn trước khi mô hình nhìn thấy. - - Trong các tin nhắn trò chuyện thông thường (không phải chỉ có chỉ thị), chúng được xử lý như "gợi ý nội tuyến" và **không** duy trì thiết lập phiên. - - Trong các tin nhắn chỉ có chỉ thị (tin nhắn chỉ chứa chỉ thị), chúng được duy trì vào phiên và trả lời bằng một xác nhận. - - Chỉ thị chỉ được áp dụng cho **người gửi được ủy quyền**. Nếu `commands.allowFrom` được đặt, đó là danh sách cho phép duy nhất được dùng; nếu không, ủy quyền đến từ danh sách cho phép/ghép đôi của kênh cộng với `commands.useAccessGroups`. Người gửi không được ủy quyền sẽ thấy chỉ thị được xử lý như văn bản thuần. + - Chỉ thị được loại bỏ khỏi tin nhắn trước khi mô hình nhìn thấy. + - Trong tin nhắn trò chuyện thông thường (không chỉ gồm chỉ thị), chúng được xem là "gợi ý nội tuyến" và **không** duy trì cài đặt phiên. + - Trong tin nhắn chỉ gồm chỉ thị (tin nhắn chỉ chứa chỉ thị), chúng được duy trì vào phiên và trả lời bằng một xác nhận. + - Chỉ thị chỉ được áp dụng cho **người gửi được ủy quyền**. Nếu `commands.allowFrom` được đặt, đó là danh sách cho phép duy nhất được dùng; nếu không, quyền ủy quyền đến từ danh sách cho phép/ghép nối kênh cộng với `commands.useAccessGroups`. Người gửi không được ủy quyền sẽ thấy chỉ thị được xử lý như văn bản thuần. Chỉ dành cho người gửi trong danh sách cho phép/được ủy quyền: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - Chúng chạy ngay lập tức, được loại bỏ trước khi mô hình nhìn thấy tin nhắn, và phần văn bản còn lại tiếp tục qua luồng thông thường. + Chúng chạy ngay lập tức, được loại bỏ trước khi mô hình nhìn thấy tin nhắn, và phần văn bản còn lại tiếp tục đi qua luồng thông thường. @@ -69,41 +69,41 @@ Có hai hệ thống liên quan: ``` - Bật phân tích `/...` trong tin nhắn trò chuyện. Trên các bề mặt không có lệnh gốc (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), lệnh văn bản vẫn hoạt động ngay cả khi bạn đặt giá trị này là `false`. + Bật phân tích cú pháp `/...` trong tin nhắn trò chuyện. Trên các bề mặt không có lệnh gốc (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), lệnh văn bản vẫn hoạt động ngay cả khi bạn đặt giá trị này thành `false`. - Đăng ký lệnh gốc. Tự động: bật cho Discord/Telegram; tắt cho Slack (cho đến khi bạn thêm slash commands); bị bỏ qua với nhà cung cấp không hỗ trợ gốc. Đặt `channels.discord.commands.native`, `channels.telegram.commands.native`, hoặc `channels.slack.commands.native` để ghi đè theo từng nhà cung cấp (bool hoặc `"auto"`). Trên Discord, `false` bỏ qua việc đăng ký slash-command và dọn dẹp trong lúc khởi động; các lệnh đã đăng ký trước đó có thể vẫn hiển thị cho đến khi bạn xóa chúng khỏi ứng dụng Discord. Các lệnh Slack được quản lý trong ứng dụng Slack và không bị xóa tự động. + Đăng ký lệnh gốc. Tự động: bật cho Discord/Telegram; tắt cho Slack (cho đến khi bạn thêm lệnh slash); bị bỏ qua với các nhà cung cấp không hỗ trợ gốc. Đặt `channels.discord.commands.native`, `channels.telegram.commands.native`, hoặc `channels.slack.commands.native` để ghi đè theo từng nhà cung cấp (bool hoặc `"auto"`). Trên Discord, `false` bỏ qua việc đăng ký và dọn dẹp lệnh slash trong lúc khởi động; các lệnh đã đăng ký trước đó có thể vẫn hiển thị cho đến khi bạn xóa chúng khỏi ứng dụng Discord. Lệnh Slack được quản lý trong ứng dụng Slack và không bị xóa tự động. -Trên Discord, đặc tả lệnh gốc có thể bao gồm `descriptionLocalizations`, mà OpenClaw xuất bản dưới dạng `description_localizations` của Discord và đưa vào các phép so sánh đối chiếu. +Trên Discord, đặc tả lệnh gốc có thể bao gồm `descriptionLocalizations`, được OpenClaw xuất bản dưới dạng Discord `description_localizations` và đưa vào so sánh đối chiếu. - Đăng ký lệnh **skill** theo cơ chế gốc khi được hỗ trợ. Tự động: bật cho Discord/Telegram; tắt cho Slack (Slack yêu cầu tạo một slash command cho từng skill). Đặt `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, hoặc `channels.slack.commands.nativeSkills` để ghi đè theo từng nhà cung cấp (bool hoặc `"auto"`). + Đăng ký lệnh **skill** theo cách gốc khi được hỗ trợ. Tự động: bật cho Discord/Telegram; tắt cho Slack (Slack yêu cầu tạo một lệnh slash cho mỗi skill). Đặt `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, hoặc `channels.slack.commands.nativeSkills` để ghi đè theo từng nhà cung cấp (bool hoặc `"auto"`). Bật `! ` để chạy lệnh shell trên máy chủ (`/bash ` là bí danh; yêu cầu danh sách cho phép `tools.elevated`). - Kiểm soát thời gian bash chờ trước khi chuyển sang chế độ nền (`0` đưa vào nền ngay lập tức). + Kiểm soát thời gian bash chờ trước khi chuyển sang chế độ nền (`0` đưa xuống nền ngay lập tức). Bật `/config` (đọc/ghi `openclaw.json`). - Bật `/mcp` (đọc/ghi cấu hình MCP do OpenClaw quản lý trong `mcp.servers`). + Bật `/mcp` (đọc/ghi cấu hình MCP do OpenClaw quản lý dưới `mcp.servers`). - Bật `/plugins` (khám phá/trạng thái plugin cùng các điều khiển cài đặt và bật/tắt). + Bật `/plugins` (khám phá/trạng thái Plugin cùng các điều khiển cài đặt + bật/tắt). - Bật `/debug` (các ghi đè chỉ trong thời gian chạy). + Bật `/debug` (ghi đè chỉ trong thời gian chạy). - Bật `/restart` cùng các hành động công cụ khởi động lại gateway. + Bật `/restart` cộng với các hành động công cụ khởi động lại Gateway. - Đặt danh sách cho phép chủ sở hữu rõ ràng cho các bề mặt lệnh/công cụ chỉ dành cho chủ sở hữu. Đây là tài khoản người vận hành là con người có thể phê duyệt các hành động nguy hiểm và chạy các lệnh như `/diagnostics`, `/export-trajectory`, và `/config`. Nó tách biệt với `commands.allowFrom` và với quyền truy cập ghép đôi DM. + Đặt danh sách cho phép chủ sở hữu rõ ràng cho các bề mặt lệnh/công cụ chỉ dành cho chủ sở hữu. Đây là tài khoản người vận hành có thể phê duyệt hành động nguy hiểm và chạy các lệnh như `/diagnostics`, `/export-trajectory`, và `/config`. Nó tách biệt với `commands.allowFrom` và với quyền truy cập ghép nối DM. - Theo từng kênh: khiến các lệnh chỉ dành cho chủ sở hữu yêu cầu **danh tính chủ sở hữu** để chạy trên bề mặt đó. Khi là `true`, người gửi phải khớp với một ứng viên chủ sở hữu đã được phân giải (ví dụ một mục trong `commands.ownerAllowFrom` hoặc siêu dữ liệu chủ sở hữu gốc của nhà cung cấp) hoặc có phạm vi nội bộ `operator.admin` trên một kênh tin nhắn nội bộ. Một mục ký tự đại diện trong `allowFrom` của kênh, hoặc danh sách ứng viên chủ sở hữu trống/chưa được phân giải, là **không** đủ — các lệnh chỉ dành cho chủ sở hữu sẽ đóng khi lỗi trên kênh đó. Tắt tùy chọn này nếu bạn muốn các lệnh chỉ dành cho chủ sở hữu chỉ được chặn bởi `ownerAllowFrom` và các danh sách cho phép lệnh tiêu chuẩn. + Theo kênh: khiến các lệnh chỉ dành cho chủ sở hữu yêu cầu **danh tính chủ sở hữu** để chạy trên bề mặt đó. Khi `true`, người gửi phải khớp với một ứng viên chủ sở hữu đã được phân giải (ví dụ một mục trong `commands.ownerAllowFrom` hoặc siêu dữ liệu chủ sở hữu gốc của nhà cung cấp) hoặc có phạm vi nội bộ `operator.admin` trên một kênh tin nhắn nội bộ. Một mục ký tự đại diện trong `allowFrom` của kênh, hoặc danh sách ứng viên chủ sở hữu trống/chưa phân giải, là **không** đủ — các lệnh chỉ dành cho chủ sở hữu sẽ đóng theo hướng an toàn trên kênh đó. Hãy để tùy chọn này tắt nếu bạn muốn các lệnh chỉ dành cho chủ sở hữu chỉ bị kiểm soát bởi `ownerAllowFrom` và các danh sách cho phép lệnh tiêu chuẩn. Kiểm soát cách id chủ sở hữu xuất hiện trong system prompt. @@ -112,57 +112,58 @@ Trên Discord, đặc tả lệnh gốc có thể bao gồm `descriptionLocaliza Tùy chọn đặt bí mật HMAC được dùng khi `commands.ownerDisplay="hash"`. - Danh sách cho phép theo từng nhà cung cấp để ủy quyền lệnh. Khi được cấu hình, đây là nguồn ủy quyền duy nhất cho lệnh và chỉ thị (danh sách cho phép/ghép đôi của kênh và `commands.useAccessGroups` bị bỏ qua). Dùng `"*"` làm mặc định toàn cục; các khóa dành riêng cho nhà cung cấp sẽ ghi đè nó. + Danh sách cho phép theo từng nhà cung cấp để ủy quyền lệnh. Khi được cấu hình, đây là nguồn ủy quyền duy nhất cho lệnh và chỉ thị (danh sách cho phép/ghép nối kênh và `commands.useAccessGroups` bị bỏ qua). Dùng `"*"` cho mặc định toàn cục; các khóa theo nhà cung cấp sẽ ghi đè nó. - Áp dụng danh sách cho phép/chính sách cho lệnh khi `commands.allowFrom` chưa được đặt. + Thực thi danh sách cho phép/chính sách cho lệnh khi `commands.allowFrom` chưa được đặt. ## Danh sách lệnh Nguồn sự thật hiện tại: -- các lệnh tích hợp lõi đến từ `src/auto-reply/commands-registry.shared.ts` -- các lệnh dock được tạo đến từ `src/auto-reply/commands-registry.data.ts` -- các lệnh plugin đến từ các lời gọi `registerCommand()` của plugin -- khả năng dùng thực tế trên gateway của bạn vẫn phụ thuộc vào cờ cấu hình, bề mặt kênh, và các plugin đã cài đặt/bật +- lệnh tích hợp lõi đến từ `src/auto-reply/commands-registry.shared.ts` +- lệnh dock được tạo đến từ `src/auto-reply/commands-registry.data.ts` +- lệnh Plugin đến từ các lệnh gọi `registerCommand()` của Plugin +- tính khả dụng thực tế trên gateway của bạn vẫn phụ thuộc vào cờ cấu hình, bề mặt kênh, và các Plugin đã cài đặt/bật -### Các lệnh tích hợp lõi +### Lệnh tích hợp lõi - `/new [model]` bắt đầu một phiên mới; `/reset` là bí danh đặt lại. - - Control UI chặn `/new` được nhập để tạo và chuyển sang một phiên dashboard mới; `/reset` được nhập vẫn chạy thao tác đặt lại tại chỗ của Gateway. - - `/reset soft [message]` giữ transcript hiện tại, loại bỏ các id phiên backend CLI đã dùng lại, và chạy lại việc tải startup/system-prompt tại chỗ. + - Control UI chặn `/new` được nhập để tạo và chuyển sang một phiên bảng điều khiển mới; `/reset` được nhập vẫn chạy thao tác đặt lại tại chỗ của Gateway. + - `/reset soft [message]` giữ bản ghi hiện tại, loại bỏ các id phiên backend CLI được tái sử dụng, và chạy lại việc tải khởi động/system-prompt tại chỗ. - `/compact [instructions]` nén ngữ cảnh phiên. Xem [Compaction](/vi/concepts/compaction). - `/stop` hủy lượt chạy hiện tại. - - `/session idle ` và `/session max-age ` quản lý hết hạn gắn kết luồng. + - `/session idle ` và `/session max-age ` quản lý thời hạn liên kết luồng. - `/export-session [path]` xuất phiên hiện tại sang HTML. Bí danh: `/export`. - - `/export-trajectory [path]` yêu cầu phê duyệt exec, rồi xuất một [gói trajectory](/vi/tools/trajectory) JSONL cho phiên hiện tại. Dùng nó khi bạn cần dòng thời gian prompt, công cụ, và transcript cho một phiên OpenClaw. Trong trò chuyện nhóm, prompt phê duyệt và kết quả xuất được gửi riêng cho chủ sở hữu. Bí danh: `/trajectory`. + - `/export-trajectory [path]` yêu cầu phê duyệt exec, rồi xuất một [gói trajectory](/vi/tools/trajectory) JSONL cho phiên hiện tại. Dùng nó khi bạn cần dòng thời gian prompt, công cụ, và bản ghi cho một phiên OpenClaw. Trong trò chuyện nhóm, prompt phê duyệt và kết quả xuất được gửi riêng cho chủ sở hữu. Bí danh: `/trajectory`. - - - `/think ` đặt mức suy nghĩ. Tùy chọn đến từ hồ sơ nhà cung cấp của mô hình đang hoạt động; các mức phổ biến là `off`, `minimal`, `low`, `medium`, và `high`, với các mức tùy chỉnh như `xhigh`, `adaptive`, `max`, hoặc nhị phân `on` chỉ ở nơi được hỗ trợ. Bí danh: `/thinking`, `/t`. + + - `/think ` đặt mức suy nghĩ. Các tùy chọn đến từ hồ sơ nhà cung cấp của mô hình đang hoạt động; các mức phổ biến là `off`, `minimal`, `low`, `medium`, và `high`, với các mức tùy chỉnh như `xhigh`, `adaptive`, `max`, hoặc nhị phân `on` chỉ ở nơi được hỗ trợ. Bí danh: `/thinking`, `/t`. - `/verbose on|off|full` bật/tắt đầu ra chi tiết. Bí danh: `/v`. - - `/trace on|off` bật/tắt đầu ra trace plugin cho phiên hiện tại. + - `/trace on|off` bật/tắt đầu ra trace của Plugin cho phiên hiện tại. - `/fast [status|on|off]` hiển thị hoặc đặt chế độ nhanh. - `/reasoning [on|off|stream]` bật/tắt khả năng hiển thị reasoning. Bí danh: `/reason`. - - `/elevated [on|off|ask|full]` bật/tắt chế độ elevated. Bí danh: `/elev`. + - `/elevated [on|off|ask|full]` bật/tắt chế độ nâng quyền. Bí danh: `/elev`. - `/exec host= security= ask= node=` hiển thị hoặc đặt mặc định exec. - `/model [name|#|status]` hiển thị hoặc đặt mô hình. - - `/models [provider] [page] [limit=|size=|all]` liệt kê các nhà cung cấp hoặc mô hình đã cấu hình/có auth khả dụng cho một nhà cung cấp; thêm `all` để duyệt toàn bộ catalog của nhà cung cấp đó. - - `/queue ` quản lý hành vi hàng đợi (`steer`, `queue` cũ, `followup`, `collect`, `steer-backlog`, `interrupt`) cùng các tùy chọn như `debounce:0.5s cap:25 drop:summarize`; `/queue default` hoặc `/queue reset` xóa ghi đè phiên. Xem [Hàng đợi lệnh](/vi/concepts/queue) và [Hàng đợi steering](/vi/concepts/queue-steering). + - `/models [provider] [page] [limit=|size=|all]` liệt kê các nhà cung cấp hoặc mô hình đã cấu hình/có xác thực khả dụng cho một nhà cung cấp; thêm `all` để duyệt toàn bộ danh mục của nhà cung cấp đó. + - `/queue ` quản lý hành vi hàng đợi (`steer`, `queue` cũ, `followup`, `collect`, `steer-backlog`, `interrupt`) cùng các tùy chọn như `debounce:0.5s cap:25 drop:summarize`; `/queue default` hoặc `/queue reset` xóa ghi đè phiên. Xem [Hàng đợi lệnh](/vi/concepts/queue) và [Hàng đợi điều hướng](/vi/concepts/queue-steering). + - `/steer ` chèn hướng dẫn vào lượt chạy đang hoạt động cho phiên hiện tại, độc lập với chế độ `/queue`. Nó không bắt đầu lượt chạy mới khi phiên đang nhàn rỗi. Bí danh: `/tell`. Xem [Điều hướng](/vi/tools/steer). - `/help` hiển thị tóm tắt trợ giúp ngắn. - - `/commands` hiển thị catalog lệnh được tạo. + - `/commands` hiển thị danh mục lệnh đã tạo. - `/tools [compact|verbose]` hiển thị những gì tác tử hiện tại có thể dùng ngay bây giờ. - - `/status` hiển thị trạng thái thực thi/thời gian chạy, bao gồm các nhãn `Execution`/`Runtime` và mức sử dụng/hạn mức nhà cung cấp khi có. - - `/diagnostics [note]` là luồng báo cáo hỗ trợ chỉ dành cho chủ sở hữu cho lỗi Gateway và các lượt chạy harness Codex. Nó yêu cầu phê duyệt exec rõ ràng mỗi lần trước khi chạy `openclaw gateway diagnostics export --json`; không phê duyệt chẩn đoán bằng quy tắc cho phép tất cả. Sau khi được phê duyệt, nó gửi một báo cáo có thể dán với đường dẫn gói cục bộ, tóm tắt manifest, ghi chú quyền riêng tư, và các id phiên liên quan. Trong trò chuyện nhóm, prompt phê duyệt và báo cáo được gửi riêng cho chủ sở hữu. Khi phiên hoạt động dùng harness OpenAI Codex, cùng phê duyệt đó cũng gửi phản hồi Codex liên quan đến máy chủ OpenAI và phản hồi hoàn tất liệt kê các id phiên OpenClaw, id luồng Codex, và lệnh `codex resume `. Xem [Xuất chẩn đoán](/vi/gateway/diagnostics). + - `/status` hiển thị trạng thái thực thi/thời gian chạy, bao gồm nhãn `Execution`/`Runtime` và mức sử dụng/hạn mức nhà cung cấp khi có. + - `/diagnostics [note]` là luồng báo cáo hỗ trợ chỉ dành cho chủ sở hữu đối với lỗi Gateway và các lượt chạy harness Codex. Nó yêu cầu phê duyệt exec rõ ràng mỗi lần trước khi chạy `openclaw gateway diagnostics export --json`; không phê duyệt chẩn đoán bằng quy tắc cho phép tất cả. Sau khi được phê duyệt, nó gửi một báo cáo có thể dán với đường dẫn gói cục bộ, tóm tắt manifest, ghi chú quyền riêng tư, và các id phiên liên quan. Trong trò chuyện nhóm, prompt phê duyệt và báo cáo được gửi riêng cho chủ sở hữu. Khi phiên đang hoạt động dùng harness OpenAI Codex, cùng phê duyệt đó cũng gửi phản hồi Codex liên quan đến máy chủ OpenAI và câu trả lời hoàn tất liệt kê các id phiên OpenClaw, id luồng Codex, và lệnh `codex resume `. Xem [Xuất chẩn đoán](/vi/gateway/diagnostics). - `/crestodian ` chạy trình trợ giúp thiết lập và sửa chữa Crestodian từ DM của chủ sở hữu. - `/tasks` liệt kê các tác vụ nền đang hoạt động/gần đây cho phiên hiện tại. - - `/context [list|detail|json]` giải thích cách ngữ cảnh được lắp ghép. + - `/context [list|detail|json]` giải thích cách ngữ cảnh được lắp ráp. - `/whoami` hiển thị id người gửi của bạn. Bí danh: `/id`. - `/usage off|tokens|full|cost` kiểm soát chân trang mức sử dụng theo từng phản hồi hoặc in tóm tắt chi phí cục bộ. @@ -171,160 +172,162 @@ Nguồn sự thật hiện tại: - `/skill [input]` chạy một skill theo tên. - `/allowlist [list|add|remove] ...` quản lý các mục danh sách cho phép. Chỉ văn bản. - `/approve ` giải quyết prompt phê duyệt exec. - - `/btw ` hỏi một câu hỏi phụ mà không thay đổi ngữ cảnh phiên trong tương lai. Bí danh: `/side`. Xem [BTW](/vi/tools/btw). + - `/btw ` hỏi một câu hỏi phụ mà không thay đổi ngữ cảnh phiên tương lai. Bí danh: `/side`. Xem [BTW](/vi/tools/btw). - - - `/subagents list|kill|log|info|send|steer|spawn` quản lý các lượt chạy tác nhân con cho phiên hiện tại. - - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` quản lý các phiên ACP và tùy chọn runtime. + + - `/subagents list|kill|log|info|send|steer|spawn` quản lý các lần chạy tác tử con cho phiên hiện tại. + - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` quản lý các phiên ACP và tùy chọn thời gian chạy. - `/focus ` liên kết luồng Discord hiện tại hoặc chủ đề/cuộc trò chuyện Telegram với một đích phiên. - - `/unfocus` gỡ liên kết hiện tại. - - `/agents` liệt kê các tác nhân gắn với luồng cho phiên hiện tại. - - `/kill ` hủy một hoặc tất cả tác nhân con đang chạy. - - `/steer ` gửi chỉ dẫn đến một tác nhân con đang chạy. Bí danh: `/tell`. + - `/unfocus` gỡ bỏ liên kết hiện tại. + - `/agents` liệt kê các tác tử được ràng buộc với luồng cho phiên hiện tại. + - `/kill ` hủy một hoặc tất cả tác tử con đang chạy. + - `/subagents steer ` gửi chỉ đạo đến một tác tử con đang chạy. Xem [Chỉ đạo](/vi/tools/steer). - - - `/config show|get|set|unset` đọc hoặc ghi `openclaw.json`. Chỉ chủ sở hữu. Yêu cầu `commands.config: true`. - - `/mcp show|get|set|unset` đọc hoặc ghi cấu hình máy chủ MCP do OpenClaw quản lý trong `mcp.servers`. Chỉ chủ sở hữu. Yêu cầu `commands.mcp: true`. - - `/plugins list|inspect|show|get|install|enable|disable` kiểm tra hoặc thay đổi trạng thái plugin. `/plugin` là bí danh. Việc ghi chỉ dành cho chủ sở hữu. Yêu cầu `commands.plugins: true`. - - `/debug show|set|unset|reset` quản lý các ghi đè cấu hình chỉ dành cho runtime. Chỉ chủ sở hữu. Yêu cầu `commands.debug: true`. + + - `/config show|get|set|unset` đọc hoặc ghi `openclaw.json`. Chỉ dành cho chủ sở hữu. Yêu cầu `commands.config: true`. + - `/mcp show|get|set|unset` đọc hoặc ghi cấu hình máy chủ MCP do OpenClaw quản lý trong `mcp.servers`. Chỉ dành cho chủ sở hữu. Yêu cầu `commands.mcp: true`. + - `/plugins list|inspect|show|get|install|enable|disable` kiểm tra hoặc thay đổi trạng thái Plugin. `/plugin` là bí danh. Các thao tác ghi chỉ dành cho chủ sở hữu. Yêu cầu `commands.plugins: true`. + - `/debug show|set|unset|reset` quản lý các ghi đè cấu hình chỉ trong thời gian chạy. Chỉ dành cho chủ sở hữu. Yêu cầu `commands.debug: true`. - `/restart` khởi động lại OpenClaw khi được bật. Mặc định: bật; đặt `commands.restart: false` để tắt. - - `/send on|off|inherit` đặt chính sách gửi. Chỉ chủ sở hữu. + - `/send on|off|inherit` đặt chính sách gửi. Chỉ dành cho chủ sở hữu. - + - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` điều khiển TTS. Xem [TTS](/vi/tools/tts). - `/activation mention|always` đặt chế độ kích hoạt nhóm. - - `/bash ` chạy một lệnh shell trên máy chủ. Chỉ văn bản. Bí danh: `! `. Yêu cầu `commands.bash: true` cùng danh sách cho phép `tools.elevated`. - - `!poll [sessionId]` kiểm tra một tác vụ bash chạy nền. - - `!stop [sessionId]` dừng một tác vụ bash chạy nền. + - `/bash ` chạy một lệnh shell trên máy chủ. Chỉ văn bản. Bí danh: `! `. Yêu cầu `commands.bash: true` cộng với danh sách cho phép `tools.elevated`. + - `!poll [sessionId]` kiểm tra một tác vụ bash nền. + - `!stop [sessionId]` dừng một tác vụ bash nền. -### Các lệnh dock được tạo +### Lệnh dock được tạo -Các lệnh dock chuyển tuyến trả lời của phiên hiện tại sang một kênh đã liên kết khác. Xem [Gắn kênh](/vi/concepts/channel-docking) để biết cách thiết lập, ví dụ và khắc phục sự cố. +Lệnh dock chuyển tuyến trả lời của phiên hiện tại sang một kênh được liên kết +khác. Xem [Docking kênh](/vi/concepts/channel-docking) để biết cách thiết lập, +ví dụ và khắc phục sự cố. -Các lệnh dock được tạo từ plugin kênh có hỗ trợ lệnh native. Bộ tích hợp hiện tại: +Lệnh dock được tạo từ Plugin kênh có hỗ trợ lệnh gốc. Bộ đi kèm hiện tại: - `/dock-discord` (bí danh: `/dock_discord`) - `/dock-mattermost` (bí danh: `/dock_mattermost`) - `/dock-slack` (bí danh: `/dock_slack`) - `/dock-telegram` (bí danh: `/dock_telegram`) -Dùng lệnh dock từ một cuộc trò chuyện trực tiếp để chuyển tuyến trả lời của phiên hiện tại sang một kênh đã liên kết khác. Tác nhân giữ nguyên ngữ cảnh phiên, nhưng các phản hồi sau này cho phiên đó sẽ được gửi đến peer kênh đã chọn. +Dùng lệnh dock từ cuộc trò chuyện trực tiếp để chuyển tuyến trả lời của phiên hiện tại sang một kênh được liên kết khác. Tác tử giữ nguyên ngữ cảnh phiên, nhưng các phản hồi sau này cho phiên đó sẽ được gửi đến peer kênh đã chọn. -Các lệnh dock yêu cầu `session.identityLinks`. Người gửi nguồn và peer đích phải nằm trong cùng một nhóm định danh, ví dụ `["telegram:123", "discord:456"]`. Nếu người dùng Telegram có id `123` gửi `/dock_discord`, OpenClaw lưu `lastChannel: "discord"` và `lastTo: "456"` trên phiên đang hoạt động. Nếu người gửi chưa được liên kết với một peer Discord, lệnh sẽ trả lời bằng gợi ý thiết lập thay vì chuyển tiếp sang trò chuyện thông thường. +Lệnh dock yêu cầu `session.identityLinks`. Người gửi nguồn và peer đích phải nằm trong cùng một nhóm danh tính, ví dụ `["telegram:123", "discord:456"]`. Nếu người dùng Telegram có id `123` gửi `/dock_discord`, OpenClaw lưu `lastChannel: "discord"` và `lastTo: "456"` trên phiên đang hoạt động. Nếu người gửi không được liên kết với peer Discord, lệnh sẽ trả lời bằng gợi ý thiết lập thay vì chuyển tiếp sang trò chuyện bình thường. -Docking chỉ thay đổi tuyến phiên đang hoạt động. Nó không tạo tài khoản kênh, cấp quyền truy cập, bỏ qua danh sách cho phép của kênh, hoặc chuyển lịch sử transcript sang phiên khác. Dùng `/dock-telegram`, `/dock-slack`, `/dock-mattermost`, hoặc một lệnh dock được tạo khác để chuyển tuyến lần nữa. +Docking chỉ thay đổi tuyến phiên đang hoạt động. Nó không tạo tài khoản kênh, cấp quyền truy cập, bỏ qua danh sách cho phép của kênh, hoặc di chuyển lịch sử bản ghi sang phiên khác. Dùng `/dock-telegram`, `/dock-slack`, `/dock-mattermost`, hoặc một lệnh dock được tạo khác để chuyển tuyến lại. -### Các lệnh plugin tích hợp +### Lệnh Plugin đi kèm -Plugin tích hợp có thể thêm nhiều lệnh slash hơn. Các lệnh tích hợp hiện tại trong repo này: +Plugin đi kèm có thể thêm nhiều lệnh gạch chéo hơn. Các lệnh đi kèm hiện tại trong repo này: - `/dreaming [on|off|status|help]` bật/tắt Dreaming bộ nhớ. Xem [Dreaming](/vi/concepts/dreaming). - `/pair [qr|status|pending|approve|cleanup|notify]` quản lý luồng ghép nối/thiết lập thiết bị. Xem [Ghép nối](/vi/channels/pairing). -- `/phone status|arm [duration]|disarm` tạm thời kích hoạt các lệnh node điện thoại rủi ro cao. -- `/voice status|list [limit]|set ` quản lý cấu hình giọng nói Talk. Trên Discord, tên lệnh native là `/talkvoice`. -- `/card ...` gửi các preset thẻ giàu nội dung của LINE. Xem [LINE](/vi/channels/line). -- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` kiểm tra và điều khiển bộ khung app-server Codex tích hợp. Xem [bộ khung Codex](/vi/plugins/codex-harness). -- Các lệnh chỉ dành cho QQBot: +- `/phone status|arm [duration]|disarm` tạm thời kích hoạt các lệnh nút điện thoại rủi ro cao. +- `/voice status|list [limit]|set ` quản lý cấu hình giọng nói Talk. Trên Discord, tên lệnh gốc là `/talkvoice`. +- `/card ...` gửi các preset thẻ phong phú LINE. Xem [LINE](/vi/channels/line). +- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` kiểm tra và điều khiển harness máy chủ ứng dụng Codex đi kèm. Xem [Harness Codex](/vi/plugins/codex-harness). +- Lệnh chỉ dành cho QQBot: - `/bot-ping` - `/bot-version` - `/bot-help` - `/bot-upgrade` - `/bot-logs` -### Các lệnh Skills động +### Lệnh Skills động -Skills mà người dùng có thể gọi cũng được hiển thị dưới dạng lệnh slash: +Skills người dùng có thể gọi cũng được hiển thị dưới dạng lệnh gạch chéo: -- `/skill [input]` luôn hoạt động như entrypoint chung. -- Skills cũng có thể xuất hiện dưới dạng lệnh trực tiếp như `/prose` khi skill/plugin đăng ký chúng. -- việc đăng ký lệnh skill native được điều khiển bởi `commands.nativeSkills` và `channels..commands.nativeSkills`. -- thông số kỹ thuật của lệnh có thể cung cấp `descriptionLocalizations` cho các bề mặt native hỗ trợ mô tả đã bản địa hóa, bao gồm Discord. +- `/skill [input]` luôn hoạt động như điểm vào chung. +- Skills cũng có thể xuất hiện dưới dạng lệnh trực tiếp như `/prose` khi Skill/Plugin đăng ký chúng. +- việc đăng ký lệnh Skills gốc được điều khiển bởi `commands.nativeSkills` và `channels..commands.nativeSkills`. +- thông số lệnh có thể cung cấp `descriptionLocalizations` cho các bề mặt gốc hỗ trợ mô tả bản địa hóa, bao gồm Discord. - + - Lệnh chấp nhận dấu `:` tùy chọn giữa lệnh và đối số (ví dụ `/think: high`, `/send: on`, `/help:`). - - `/new ` chấp nhận bí danh model, `provider/model`, hoặc tên provider (khớp mờ); nếu không khớp, văn bản được xem là phần thân tin nhắn. - - Để xem phân tích đầy đủ về mức dùng provider, dùng `openclaw status --usage`. - - `/allowlist add|remove` yêu cầu `commands.config=true` và tuân thủ `configWrites` của kênh. - - Trong các kênh nhiều tài khoản, `/allowlist --account ` nhắm vào cấu hình và `/config set channels..accounts....` cũng tuân thủ `configWrites` của tài khoản đích. - - `/usage` điều khiển chân trang mức dùng theo từng phản hồi; `/usage cost` in bản tóm tắt chi phí cục bộ từ nhật ký phiên OpenClaw. + - `/new ` chấp nhận bí danh mô hình, `provider/model`, hoặc tên provider (khớp mờ); nếu không khớp, văn bản được xử lý như phần thân tin nhắn. + - Để xem phân tích đầy đủ về mức sử dụng provider, dùng `openclaw status --usage`. + - `/allowlist add|remove` yêu cầu `commands.config=true` và tuân theo `configWrites` của kênh. + - Trong các kênh nhiều tài khoản, `/allowlist --account ` nhắm tới cấu hình và `/config set channels..accounts....` cũng tuân theo `configWrites` của tài khoản đích. + - `/usage` điều khiển chân trang mức sử dụng theo từng phản hồi; `/usage cost` in tóm tắt chi phí cục bộ từ nhật ký phiên OpenClaw. - `/restart` được bật theo mặc định; đặt `commands.restart: false` để tắt. - - `/plugins install ` chấp nhận cùng thông số plugin như `openclaw plugins install`: đường dẫn/kho lưu trữ cục bộ, gói npm, `git:`, hoặc `clawhub:`, rồi yêu cầu khởi động lại Gateway vì các module nguồn plugin đã thay đổi. - - `/plugins enable|disable` cập nhật cấu hình plugin và kích hoạt tải lại plugin Gateway cho các lượt tác nhân mới. + - `/plugins install ` chấp nhận cùng thông số Plugin như `openclaw plugins install`: đường dẫn/kho lưu trữ cục bộ, gói npm, `git:`, hoặc `clawhub:`, rồi yêu cầu khởi động lại Gateway vì các mô-đun nguồn Plugin đã thay đổi. + - `/plugins enable|disable` cập nhật cấu hình Plugin và kích hoạt tải lại Plugin của Gateway cho các lượt tác tử mới. - - - Lệnh native chỉ dành cho Discord: `/vc join|leave|status` điều khiển kênh thoại (không khả dụng dưới dạng văn bản). `join` yêu cầu một guild và kênh thoại/stage đã chọn. Yêu cầu `channels.discord.voice` và lệnh native. - - Các lệnh gắn luồng Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) yêu cầu liên kết luồng hiệu dụng được bật (`session.threadBindings.enabled` và/hoặc `channels.discord.threadBindings.enabled`). - - Tham chiếu lệnh ACP và hành vi runtime: [tác nhân ACP](/vi/tools/acp-agents). + + - Lệnh gốc chỉ dành cho Discord: `/vc join|leave|status` điều khiển kênh thoại (không có dưới dạng văn bản). `join` yêu cầu guild và kênh thoại/sân khấu đã chọn. Yêu cầu `channels.discord.voice` và lệnh gốc. + - Các lệnh ràng buộc luồng Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) yêu cầu ràng buộc luồng hiệu lực được bật (`session.threadBindings.enabled` và/hoặc `channels.discord.threadBindings.enabled`). + - Tham chiếu lệnh ACP và hành vi thời gian chạy: [Tác tử ACP](/vi/tools/acp-agents). - - - `/verbose` dành cho gỡ lỗi và tăng khả năng quan sát; hãy để **tắt** trong sử dụng thông thường. - - `/trace` hẹp hơn `/verbose`: nó chỉ tiết lộ các dòng trace/gỡ lỗi do plugin sở hữu và giữ phần trao đổi công cụ verbose thông thường ở trạng thái tắt. - - `/fast on|off` lưu một ghi đè phiên. Dùng tùy chọn `inherit` trong UI Sessions để xóa nó và quay về mặc định cấu hình. - - `/fast` phụ thuộc vào provider: OpenAI/OpenAI Codex ánh xạ nó thành `service_tier=priority` trên các endpoint Responses native, trong khi các yêu cầu Anthropic công khai trực tiếp, bao gồm lưu lượng được xác thực bằng OAuth gửi đến `api.anthropic.com`, ánh xạ nó thành `service_tier=auto` hoặc `standard_only`. Xem [OpenAI](/vi/providers/openai) và [Anthropic](/vi/providers/anthropic). + + - `/verbose` dành cho gỡ lỗi và tăng khả năng quan sát; hãy giữ nó **tắt** khi sử dụng bình thường. + - `/trace` hẹp hơn `/verbose`: nó chỉ tiết lộ các dòng trace/gỡ lỗi thuộc sở hữu Plugin và giữ tắt phần nhiễu công cụ verbose thông thường. + - `/fast on|off` lưu một ghi đè phiên. Dùng tùy chọn `inherit` trong giao diện Sessions để xóa nó và quay về mặc định cấu hình. + - `/fast` phụ thuộc vào provider: OpenAI/OpenAI Codex ánh xạ nó tới `service_tier=priority` trên endpoint Responses gốc, còn các yêu cầu Anthropic công khai trực tiếp, bao gồm lưu lượng được xác thực OAuth gửi tới `api.anthropic.com`, ánh xạ nó tới `service_tier=auto` hoặc `standard_only`. Xem [OpenAI](/vi/providers/openai) và [Anthropic](/vi/providers/anthropic). - Tóm tắt lỗi công cụ vẫn được hiển thị khi có liên quan, nhưng văn bản lỗi chi tiết chỉ được đưa vào khi `/verbose` là `on` hoặc `full`. - - `/reasoning`, `/verbose`, và `/trace` có rủi ro trong bối cảnh nhóm: chúng có thể tiết lộ reasoning nội bộ, đầu ra công cụ, hoặc chẩn đoán plugin mà bạn không định công khai. Nên để chúng tắt, đặc biệt trong trò chuyện nhóm. + - `/reasoning`, `/verbose`, và `/trace` có rủi ro trong bối cảnh nhóm: chúng có thể tiết lộ suy luận nội bộ, đầu ra công cụ, hoặc chẩn đoán Plugin mà bạn không định công khai. Nên để chúng tắt, đặc biệt trong trò chuyện nhóm. - - - `/model` lưu model phiên mới ngay lập tức. - - Nếu tác nhân đang rảnh, lượt chạy tiếp theo dùng nó ngay. - - Nếu một lượt chạy đã hoạt động, OpenClaw đánh dấu việc chuyển live là đang chờ và chỉ khởi động lại vào model mới tại một điểm retry sạch. - - Nếu hoạt động công cụ hoặc đầu ra phản hồi đã bắt đầu, chuyển đổi đang chờ có thể tiếp tục xếp hàng đến một cơ hội retry sau hoặc lượt người dùng kế tiếp. - - Trong TUI cục bộ, `/crestodian [request]` quay lại từ TUI tác nhân thông thường về Crestodian. Điều này tách biệt với chế độ cứu hộ kênh tin nhắn và không cấp quyền cấu hình từ xa. + + - `/model` lưu mô hình phiên mới ngay lập tức. + - Nếu tác tử đang rảnh, lần chạy tiếp theo dùng nó ngay. + - Nếu một lần chạy đã hoạt động, OpenClaw đánh dấu chuyển đổi trực tiếp là đang chờ và chỉ khởi động lại vào mô hình mới tại một điểm thử lại sạch. + - Nếu hoạt động công cụ hoặc đầu ra trả lời đã bắt đầu, chuyển đổi đang chờ có thể tiếp tục nằm trong hàng đợi cho đến cơ hội thử lại sau hoặc lượt người dùng tiếp theo. + - Trong TUI cục bộ, `/crestodian [request]` quay từ TUI tác tử bình thường về Crestodian. Điều này tách biệt với chế độ cứu hộ kênh tin nhắn và không cấp quyền cấu hình từ xa. - - - **Đường nhanh:** các tin nhắn chỉ gồm lệnh từ người gửi trong danh sách cho phép được xử lý ngay lập tức (bỏ qua hàng đợi + model). - - **Cổng yêu cầu nhắc đến trong nhóm:** các tin nhắn chỉ gồm lệnh từ người gửi trong danh sách cho phép bỏ qua yêu cầu nhắc đến. - - **Lối tắt inline (chỉ người gửi trong danh sách cho phép):** một số lệnh cũng hoạt động khi được nhúng trong tin nhắn thông thường và được loại bỏ trước khi model thấy phần văn bản còn lại. - - Ví dụ: `hey /status` kích hoạt phản hồi trạng thái, và phần văn bản còn lại tiếp tục đi qua luồng thông thường. + + - **Đường nhanh:** tin nhắn chỉ chứa lệnh từ người gửi trong danh sách cho phép được xử lý ngay (bỏ qua hàng đợi + mô hình). + - **Cổng nhắc đến nhóm:** tin nhắn chỉ chứa lệnh từ người gửi trong danh sách cho phép bỏ qua yêu cầu nhắc đến. + - **Lối tắt nội tuyến (chỉ người gửi trong danh sách cho phép):** một số lệnh cũng hoạt động khi được nhúng trong tin nhắn bình thường và bị loại bỏ trước khi mô hình thấy phần văn bản còn lại. + - Ví dụ: `hey /status` kích hoạt phản hồi trạng thái, và phần văn bản còn lại tiếp tục qua luồng bình thường. - Hiện tại: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - - Các tin nhắn chỉ gồm lệnh không được ủy quyền sẽ bị bỏ qua im lặng, và token `/...` inline được xử lý như văn bản thuần. + - Tin nhắn chỉ chứa lệnh không được phép sẽ bị bỏ qua âm thầm, và các token `/...` nội tuyến được xử lý như văn bản thường. - - - **Lệnh Skill:** Skills `user-invocable` được hiển thị dưới dạng lệnh slash. Tên được chuẩn hóa thành `a-z0-9_` (tối đa 32 ký tự); xung đột nhận hậu tố số (ví dụ `_2`). - - `/skill [input]` chạy một skill theo tên (hữu ích khi giới hạn lệnh native ngăn tạo lệnh riêng cho từng skill). - - Theo mặc định, các lệnh skill được chuyển tiếp đến model như một yêu cầu thông thường. - - Skills có thể tùy chọn khai báo `command-dispatch: tool` để định tuyến lệnh trực tiếp đến một công cụ (xác định, không dùng model). - - Ví dụ: `/prose` (plugin OpenProse) — xem [OpenProse](/vi/prose). - - **Đối số lệnh native:** Discord dùng tự động hoàn thành cho tùy chọn động (và menu nút khi bạn bỏ qua đối số bắt buộc). Telegram và Slack hiển thị menu nút khi một lệnh hỗ trợ lựa chọn và bạn bỏ qua đối số. Các lựa chọn động được phân giải theo model phiên đích, nên các tùy chọn theo model như cấp độ `/think` tuân theo ghi đè `/model` của phiên đó. + + - **Lệnh Skills:** Skills `user-invocable` được hiển thị dưới dạng lệnh gạch chéo. Tên được chuẩn hóa thành `a-z0-9_` (tối đa 32 ký tự); xung đột nhận hậu tố số (ví dụ `_2`). + - `/skill [input]` chạy Skill theo tên (hữu ích khi giới hạn lệnh gốc ngăn tạo lệnh riêng cho từng Skill). + - Theo mặc định, lệnh Skill được chuyển tiếp tới mô hình như một yêu cầu bình thường. + - Skills có thể tùy chọn khai báo `command-dispatch: tool` để định tuyến lệnh trực tiếp tới một công cụ (xác định, không qua mô hình). + - Ví dụ: `/prose` (Plugin OpenProse) — xem [OpenProse](/vi/prose). + - **Đối số lệnh gốc:** Discord dùng tự động hoàn thành cho tùy chọn động (và menu nút khi bạn bỏ qua đối số bắt buộc). Telegram và Slack hiển thị menu nút khi lệnh hỗ trợ lựa chọn và bạn bỏ qua đối số. Lựa chọn động được phân giải theo mô hình phiên đích, nên các tùy chọn theo mô hình như mức `/think` tuân theo ghi đè `/model` của phiên đó. ## `/tools` -`/tools` trả lời một câu hỏi runtime, không phải câu hỏi cấu hình: **tác nhân này có thể dùng gì ngay bây giờ trong cuộc trò chuyện này**. +`/tools` trả lời một câu hỏi về thời gian chạy, không phải câu hỏi cấu hình: **tác tử này có thể dùng gì ngay bây giờ trong cuộc trò chuyện này**. -- `/tools` mặc định ngắn gọn và được tối ưu để quét nhanh. +- `/tools` mặc định gọn và được tối ưu để quét nhanh. - `/tools verbose` thêm mô tả ngắn. -- Các bề mặt lệnh native hỗ trợ đối số hiển thị cùng công tắc chế độ như `compact|verbose`. -- Kết quả có phạm vi theo phiên, nên việc thay đổi tác nhân, kênh, luồng, ủy quyền người gửi, hoặc model có thể thay đổi đầu ra. -- `/tools` bao gồm các công cụ thật sự có thể truy cập ở runtime, bao gồm công cụ lõi, công cụ plugin đã kết nối, và công cụ do kênh sở hữu. +- Các bề mặt lệnh gốc hỗ trợ đối số hiển thị cùng công tắc chế độ như `compact|verbose`. +- Kết quả được giới hạn theo phiên, nên việc đổi tác tử, kênh, luồng, quyền người gửi, hoặc mô hình có thể thay đổi đầu ra. +- `/tools` bao gồm các công cụ thực sự có thể truy cập trong thời gian chạy, bao gồm công cụ lõi, công cụ Plugin đã kết nối, và công cụ thuộc sở hữu kênh. -Để chỉnh sửa hồ sơ và ghi đè, dùng bảng Tools của Control UI hoặc các bề mặt cấu hình/catalog thay vì xem `/tools` như một catalog tĩnh. +Để chỉnh sửa hồ sơ và ghi đè, dùng bảng Công cụ trong Control UI hoặc các bề mặt cấu hình/catalog thay vì xem `/tools` như một catalog tĩnh. -## Các bề mặt mức dùng (hiển thị ở đâu) +## Bề mặt mức sử dụng (hiển thị ở đâu) -- **Mức dùng/hạn mức của nhà cung cấp** (ví dụ: "Claude còn 80%") hiển thị trong `/status` cho nhà cung cấp mô hình hiện tại khi bật theo dõi mức dùng. OpenClaw chuẩn hóa các cửa sổ của nhà cung cấp thành `% còn lại`; với MiniMax, các trường phần trăm chỉ-báo-còn-lại được đảo trước khi hiển thị, và phản hồi `model_remains` ưu tiên mục mô hình trò chuyện kèm nhãn gói được gắn thẻ mô hình. -- **Các dòng token/bộ nhớ đệm** trong `/status` có thể dự phòng về mục mức dùng transcript mới nhất khi snapshot phiên trực tiếp còn thưa. Các giá trị trực tiếp khác 0 hiện có vẫn được ưu tiên, và dự phòng transcript cũng có thể khôi phục nhãn mô hình runtime đang hoạt động cùng tổng lớn hơn thiên về prompt khi tổng đã lưu bị thiếu hoặc nhỏ hơn. -- **Thực thi so với runtime:** `/status` báo cáo `Execution` cho đường dẫn sandbox hiệu lực và `Runtime` cho bên đang thực sự chạy phiên: `OpenClaw Pi Default`, `OpenAI Codex`, một backend CLI, hoặc một backend ACP. -- **Token/chi phí theo từng phản hồi** được điều khiển bằng `/usage off|tokens|full` (được thêm vào các phản hồi bình thường). -- `/model status` nói về **mô hình/xác thực/endpoint**, không phải mức dùng. +- **Mức sử dụng/hạn mức nhà cung cấp** (ví dụ: "Claude còn 80%") hiển thị trong `/status` cho nhà cung cấp mô hình hiện tại khi bật theo dõi mức sử dụng. OpenClaw chuẩn hóa các cửa sổ của nhà cung cấp thành `% còn lại`; với MiniMax, các trường phần trăm chỉ thể hiện phần còn lại được đảo trước khi hiển thị, và các phản hồi `model_remains` ưu tiên mục mô hình chat cộng với nhãn gói có gắn thẻ mô hình. +- **Dòng token/cache** trong `/status` có thể dùng mục mức sử dụng transcript mới nhất làm phương án dự phòng khi snapshot phiên trực tiếp còn thưa. Các giá trị trực tiếp khác 0 hiện có vẫn được ưu tiên, và phương án dự phòng từ transcript cũng có thể khôi phục nhãn mô hình runtime đang hoạt động cộng với tổng lớn hơn theo hướng prompt khi các tổng đã lưu bị thiếu hoặc nhỏ hơn. +- **Thực thi so với runtime:** `/status` báo cáo `Execution` cho đường dẫn sandbox hiệu dụng và `Runtime` cho bên thực sự đang chạy phiên: `OpenClaw Pi Default`, `OpenAI Codex`, một backend CLI, hoặc một backend ACP. +- **Token/chi phí theo từng phản hồi** được kiểm soát bằng `/usage off|tokens|full` (được thêm vào các phản hồi bình thường). +- `/model status` nói về **mô hình/xác thực/endpoint**, không phải mức sử dụng. ## Chọn mô hình (`/model`) -`/model` được triển khai như một chỉ thị. +`/model` được triển khai như một directive. Ví dụ: @@ -339,14 +342,14 @@ Ví dụ: Ghi chú: -- `/model` và `/model list` hiển thị một bộ chọn nhỏ gọn, có đánh số (họ mô hình + các nhà cung cấp có sẵn). -- Trên Discord, `/model` và `/models` mở một bộ chọn tương tác với menu thả xuống nhà cung cấp và mô hình, kèm bước Gửi. +- `/model` và `/model list` hiển thị bộ chọn nhỏ gọn, có đánh số (họ mô hình + các nhà cung cấp khả dụng). +- Trên Discord, `/model` và `/models` mở một bộ chọn tương tác với các danh sách thả xuống cho nhà cung cấp và mô hình, kèm bước Submit. - `/model <#>` chọn từ bộ chọn đó (và ưu tiên nhà cung cấp hiện tại khi có thể). -- `/model status` hiển thị chế độ xem chi tiết, bao gồm endpoint nhà cung cấp đã cấu hình (`baseUrl`) và chế độ API (`api`) khi có sẵn. +- `/model status` hiển thị chế độ xem chi tiết, bao gồm endpoint nhà cung cấp đã cấu hình (`baseUrl`) và chế độ API (`api`) khi có. ## Ghi đè gỡ lỗi -`/debug` cho phép bạn đặt các ghi đè cấu hình **chỉ runtime** (bộ nhớ, không phải đĩa). Chỉ chủ sở hữu. Tắt theo mặc định; bật bằng `commands.debug: true`. +`/debug` cho phép bạn đặt các ghi đè cấu hình **chỉ trong runtime** (bộ nhớ, không phải ổ đĩa). Chỉ chủ sở hữu. Tắt theo mặc định; bật bằng `commands.debug: true`. Ví dụ: @@ -359,12 +362,12 @@ Ví dụ: ``` -Ghi đè áp dụng ngay cho các lần đọc cấu hình mới, nhưng **không** ghi vào `openclaw.json`. Dùng `/debug reset` để xóa tất cả ghi đè và trở về cấu hình trên đĩa. +Các ghi đè áp dụng ngay cho các lần đọc cấu hình mới, nhưng **không** ghi vào `openclaw.json`. Dùng `/debug reset` để xóa tất cả ghi đè và quay lại cấu hình trên ổ đĩa. -## Đầu ra trace Plugin +## Đầu ra truy vết Plugin -`/trace` cho phép bạn bật/tắt **các dòng trace/gỡ lỗi Plugin theo phạm vi phiên** mà không cần bật toàn bộ chế độ verbose. +`/trace` cho phép bạn bật/tắt **các dòng truy vết/gỡ lỗi Plugin trong phạm vi phiên** mà không bật toàn bộ chế độ chi tiết. Ví dụ: @@ -376,16 +379,16 @@ Ví dụ: Ghi chú: -- `/trace` không có đối số sẽ hiển thị trạng thái trace phiên hiện tại. -- `/trace on` bật các dòng trace Plugin cho phiên hiện tại. -- `/trace off` tắt lại chúng. -- Các dòng trace Plugin có thể xuất hiện trong `/status` và dưới dạng một tin nhắn chẩn đoán tiếp theo sau phản hồi trợ lý bình thường. -- `/trace` không thay thế `/debug`; `/debug` vẫn quản lý các ghi đè cấu hình chỉ runtime. -- `/trace` không thay thế `/verbose`; đầu ra công cụ/trạng thái verbose bình thường vẫn thuộc về `/verbose`. +- `/trace` không có đối số sẽ hiển thị trạng thái truy vết của phiên hiện tại. +- `/trace on` bật các dòng truy vết Plugin cho phiên hiện tại. +- `/trace off` tắt chúng lại. +- Các dòng truy vết Plugin có thể xuất hiện trong `/status` và dưới dạng một thông báo chẩn đoán tiếp theo sau phản hồi trợ lý bình thường. +- `/trace` không thay thế `/debug`; `/debug` vẫn quản lý các ghi đè cấu hình chỉ trong runtime. +- `/trace` không thay thế `/verbose`; đầu ra công cụ/trạng thái chi tiết bình thường vẫn thuộc về `/verbose`. ## Cập nhật cấu hình -`/config` ghi vào cấu hình trên đĩa của bạn (`openclaw.json`). Chỉ chủ sở hữu. Tắt theo mặc định; bật bằng `commands.config: true`. +`/config` ghi vào cấu hình trên ổ đĩa của bạn (`openclaw.json`). Chỉ chủ sở hữu. Tắt theo mặc định; bật bằng `commands.config: true`. Ví dụ: @@ -398,7 +401,7 @@ Ví dụ: ``` -Cấu hình được xác thực trước khi ghi; các thay đổi không hợp lệ sẽ bị từ chối. Các cập nhật `/config` được duy trì qua các lần khởi động lại. +Cấu hình được xác thực trước khi ghi; các thay đổi không hợp lệ sẽ bị từ chối. Các cập nhật `/config` được giữ lại qua các lần khởi động lại. ## Cập nhật MCP @@ -415,12 +418,12 @@ Ví dụ: ``` -`/mcp` lưu cấu hình trong cấu hình OpenClaw, không phải thiết lập dự án do Pi sở hữu. Các bộ điều hợp runtime quyết định transport nào thực sự có thể thực thi. +`/mcp` lưu cấu hình trong cấu hình OpenClaw, không phải thiết lập dự án do Pi sở hữu. Các adapter runtime quyết định transport nào thực sự có thể thực thi. ## Cập nhật Plugin -`/plugins` cho phép người vận hành kiểm tra các Plugin đã phát hiện và bật/tắt chúng trong cấu hình. Các luồng chỉ đọc có thể dùng `/plugin` làm bí danh. Tắt theo mặc định; bật bằng `commands.plugins: true`. +`/plugins` cho phép người vận hành kiểm tra các Plugin đã phát hiện và bật/tắt trạng thái kích hoạt trong cấu hình. Các luồng chỉ đọc có thể dùng `/plugin` làm bí danh. Tắt theo mặc định; bật bằng `commands.plugins: true`. Ví dụ: @@ -433,46 +436,46 @@ Ví dụ: ``` -- `/plugins list` và `/plugins show` dùng cơ chế phát hiện Plugin thật trên workspace hiện tại cộng với cấu hình trên đĩa. +- `/plugins list` và `/plugins show` dùng quá trình phát hiện Plugin thực tế trên workspace hiện tại cộng với cấu hình trên ổ đĩa. - `/plugins install` cài đặt từ ClawHub, npm, git, thư mục cục bộ và archive. -- `/plugins enable|disable` chỉ cập nhật cấu hình Plugin; nó không cài đặt hoặc gỡ cài đặt Plugin. -- Các thay đổi bật và tắt sẽ hot-reload các bề mặt runtime Plugin của Gateway cho các lượt agent mới; cài đặt yêu cầu khởi động lại Gateway vì các mô-đun nguồn Plugin đã thay đổi. +- `/plugins enable|disable` chỉ cập nhật cấu hình Plugin; lệnh này không cài đặt hoặc gỡ cài đặt Plugin. +- Các thay đổi bật và tắt sẽ hot-reload các bề mặt runtime Plugin của Gateway cho các lượt agent mới; cài đặt yêu cầu khởi động lại Gateway vì các module nguồn Plugin đã thay đổi. -## Ghi chú bề mặt +## Ghi chú theo bề mặt - - **Lệnh văn bản** chạy trong phiên trò chuyện bình thường (DM chia sẻ `main`, nhóm có phiên riêng). - - **Lệnh gốc** dùng các phiên tách biệt: + - **Lệnh văn bản** chạy trong phiên chat bình thường (DM dùng chung `main`, nhóm có phiên riêng). + - **Lệnh native** dùng các phiên cô lập: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (tiền tố có thể cấu hình qua `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (nhắm tới phiên trò chuyện qua `CommandTargetSessionKey`) - - **`/stop`** nhắm tới phiên trò chuyện đang hoạt động để có thể hủy lượt chạy hiện tại. + - Telegram: `telegram:slash:` (nhắm tới phiên chat qua `CommandTargetSessionKey`) + - **`/stop`** nhắm tới phiên chat đang hoạt động để có thể hủy lượt chạy hiện tại. - `channels.slack.slashCommand` vẫn được hỗ trợ cho một lệnh kiểu `/openclaw` duy nhất. Nếu bạn bật `commands.native`, bạn phải tạo một lệnh slash Slack cho mỗi lệnh tích hợp sẵn (cùng tên như `/help`). Menu đối số lệnh cho Slack được gửi dưới dạng các nút Block Kit tạm thời. + `channels.slack.slashCommand` vẫn được hỗ trợ cho một lệnh kiểu `/openclaw` duy nhất. Nếu bạn bật `commands.native`, bạn phải tạo một lệnh slash Slack cho mỗi lệnh tích hợp sẵn (cùng tên như trong `/help`). Menu đối số lệnh cho Slack được gửi dưới dạng các nút Block Kit tạm thời. - Ngoại lệ gốc của Slack: đăng ký `/agentstatus` (không phải `/status`) vì Slack giữ riêng `/status`. Văn bản `/status` vẫn hoạt động trong tin nhắn Slack. + Ngoại lệ native của Slack: đăng ký `/agentstatus` (không phải `/status`) vì Slack giữ riêng `/status`. Văn bản `/status` vẫn hoạt động trong tin nhắn Slack. ## Câu hỏi phụ BTW -`/btw` là một **câu hỏi phụ** nhanh về phiên hiện tại. `/side` là bí danh. +`/btw` là một **câu hỏi phụ** nhanh về phiên hiện tại. `/side` là một bí danh. -Khác với trò chuyện bình thường: +Khác với chat bình thường: -- nó dùng phiên hiện tại làm ngữ cảnh nền, -- nó chạy như một lệnh gọi một lần **không dùng công cụ** riêng biệt, -- nó không thay đổi ngữ cảnh phiên trong tương lai, -- nó không được ghi vào lịch sử transcript, -- nó được gửi như một kết quả phụ trực tiếp thay vì một tin nhắn trợ lý bình thường. +- lệnh dùng phiên hiện tại làm ngữ cảnh nền, +- lệnh chạy như một lần gọi one-shot **không có công cụ** riêng biệt, +- lệnh không thay đổi ngữ cảnh phiên trong tương lai, +- lệnh không được ghi vào lịch sử transcript, +- lệnh được gửi dưới dạng kết quả phụ trực tiếp thay vì một tin nhắn trợ lý bình thường. -Điều đó khiến `/btw` hữu ích khi bạn muốn một phần làm rõ tạm thời trong lúc tác vụ chính tiếp tục chạy. +Điều đó làm cho `/btw` hữu ích khi bạn muốn làm rõ tạm thời trong lúc tác vụ chính vẫn tiếp tục. Ví dụ: @@ -481,10 +484,10 @@ Ví dụ: /side what changed while the main run continued? ``` -Xem [Câu hỏi phụ BTW](/vi/tools/btw) để biết đầy đủ hành vi và chi tiết UX của máy khách. +Xem [Câu hỏi phụ BTW](/vi/tools/btw) để biết đầy đủ hành vi và chi tiết UX của client. ## Liên quan -- [Tạo Skills](/vi/tools/creating-skills) +- [Tạo skills](/vi/tools/creating-skills) - [Skills](/vi/tools/skills) - [Cấu hình Skills](/vi/tools/skills-config) diff --git a/docs/vi/tools/steer.md b/docs/vi/tools/steer.md new file mode 100644 index 000000000..ab6682741 --- /dev/null +++ b/docs/vi/tools/steer.md @@ -0,0 +1,84 @@ +--- +read_when: + - Sử dụng /steer hoặc /tell khi một tác nhân đang chạy + - So sánh /steer với /queue steer + - Quyết định nên điều hướng lần chạy hiện tại, một tác nhân phụ hay một phiên ACP +sidebarTitle: Steer +summary: Điều hướng một lượt chạy đang hoạt động mà không thay đổi chế độ hàng đợi +title: Điều hướng +x-i18n: + generated_at: "2026-05-04T02:26:29Z" + model: gpt-5.5 + provider: openai + source_hash: 71e1c80c0eea86d5c3c29513d3ed0675c04779fc9c6ee3b8a76c4bedaa264d22 + source_path: tools/steer.md + workflow: 16 +--- + +`/steer` gửi hướng dẫn đến một lượt chạy đang hoạt động. Lệnh này dành cho những thời điểm "điều chỉnh lượt chạy này +trong khi nó vẫn đang hoạt động", không phải để bắt đầu một lượt mới. + +## Phiên hiện tại + +Dùng `/steer` cấp cao nhất để nhắm đến lượt chạy đang hoạt động cho phiên hiện tại: + +```text +/steer prefer the smaller patch and keep the tests focused +/tell summarize before making the next tool call +``` + +Hành vi: + +- Chỉ nhắm đến lượt chạy đang hoạt động của phiên hiện tại. +- Hoạt động độc lập với chế độ `/queue` của phiên. +- Không bắt đầu một lượt chạy mới khi phiên đang rảnh. +- Trả lời bằng cảnh báo khi không có lượt chạy đang hoạt động để điều hướng. +- Dùng đường dẫn điều hướng của runtime đang hoạt động, vì vậy mô hình sẽ thấy hướng dẫn tại + ranh giới runtime được hỗ trợ tiếp theo. + +## Steer so với queue + +`/queue steer` thay đổi cách các tin nhắn đến thông thường hoạt động khi chúng đến +trong lúc một lượt chạy đang hoạt động. `/steer ` là một lệnh tường minh cố gắng +chèn tin nhắn của lệnh đó vào lượt chạy đang hoạt động tại ranh giới runtime +được hỗ trợ tiếp theo, bất kể thiết lập `/queue` đã lưu. + +Dùng: + +- `/steer ` khi bạn muốn hướng dẫn lượt chạy đang hoạt động ngay bây giờ. +- `/queue steer` khi bạn muốn các tin nhắn thông thường trong tương lai mặc định điều hướng các lượt chạy đang hoạt động. +- `/queue collect` hoặc `/queue followup` khi tin nhắn mới nên chờ một + lượt sau thay vì điều hướng lượt chạy đang hoạt động. + +Để biết các chế độ hàng đợi và hành vi dự phòng, xem [Hàng đợi lệnh](/vi/concepts/queue) và +[Hàng đợi điều hướng](/vi/concepts/queue-steering). + +## Sub-agent + +Dùng `/subagents steer` khi mục tiêu là một lượt chạy con: + +```text +/subagents steer 2 focus only on the API surface +``` + +`/steer` cấp cao nhất không chọn sub-agent theo id hoặc chỉ mục danh sách. Nó luôn +nhắm đến lượt chạy đang hoạt động của phiên hiện tại. Xem [Sub-agent](/vi/tools/subagents) để biết +id, nhãn và lệnh điều khiển của sub-agent. + +## Phiên ACP + +Dùng `/acp steer` khi mục tiêu là một phiên harness ACP: + +```text +/acp steer --session agent:main:acp:codex tighten the repro +``` + +Xem [Agent ACP](/vi/tools/acp-agents) để biết cách chọn phiên ACP và hành vi +runtime. + +## Liên quan + +- [Lệnh slash](/vi/tools/slash-commands) +- [Hàng đợi lệnh](/vi/concepts/queue) +- [Hàng đợi điều hướng](/vi/concepts/queue-steering) +- [Sub-agent](/vi/tools/subagents) diff --git a/docs/vi/tools/subagents.md b/docs/vi/tools/subagents.md index ecd3d6a4f..199fe54fc 100644 --- a/docs/vi/tools/subagents.md +++ b/docs/vi/tools/subagents.md @@ -1,47 +1,48 @@ --- read_when: - - Bạn muốn thực hiện công việc chạy nền hoặc song song thông qua tác nhân - - Bạn đang thay đổi chính sách công cụ `sessions_spawn` hoặc tác tử phụ - - Bạn đang triển khai hoặc khắc phục sự cố các phiên tác nhân phụ gắn với luồng + - Bạn muốn chạy công việc nền hoặc công việc song song thông qua tác nhân + - Bạn đang thay đổi chính sách công cụ sessions_spawn hoặc tác tử con + - Bạn đang triển khai hoặc khắc phục sự cố các phiên subagent ràng buộc với luồng sidebarTitle: Sub-agents -summary: Khởi tạo các phiên chạy tác tử nền cô lập thông báo kết quả về cuộc trò chuyện của người yêu cầu +summary: Khởi tạo các lượt chạy agent nền biệt lập thông báo kết quả trở lại cuộc trò chuyện của người yêu cầu title: Tác nhân phụ x-i18n: - generated_at: "2026-05-02T10:56:02Z" + generated_at: "2026-05-04T02:26:35Z" model: gpt-5.5 provider: openai - source_hash: 0e964df543bd19435daf94f2c85a34b9d32e07662405d2eac7635935f1e7bf64 + source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37 source_path: tools/subagents.md workflow: 16 --- -Tác tử con là các lượt chạy tác tử nền được tạo ra từ một lượt chạy tác tử hiện có. -Chúng chạy trong phiên riêng (`agent::subagent:`) và, -khi hoàn tất, **thông báo** kết quả trở lại kênh trò chuyện của bên yêu cầu. -Mỗi lượt chạy tác tử con được theo dõi như một +Các tác tử con là các lần chạy tác tử nền được sinh ra từ một lần chạy tác tử hiện có. +Chúng chạy trong phiên riêng của mình (`agent::subagent:`) và, +khi hoàn tất, **thông báo** kết quả của chúng trở lại kênh trò chuyện +của bên yêu cầu. Mỗi lần chạy tác tử con được theo dõi như một [tác vụ nền](/vi/automation/tasks). Mục tiêu chính: -- Song song hóa công việc "nghiên cứu / tác vụ dài / công cụ chậm" mà không chặn lượt chạy chính. -- Giữ tác tử con tách biệt theo mặc định (tách phiên + sandbox tùy chọn). -- Giữ bề mặt công cụ khó bị dùng sai: tác tử con không nhận công cụ phiên theo mặc định. -- Hỗ trợ độ sâu lồng nhau có thể cấu hình cho các mẫu điều phối. +- Song song hóa công việc "nghiên cứu / tác vụ dài / công cụ chậm" mà không chặn lần chạy chính. +- Giữ tác tử con mặc định được cô lập (tách phiên + sandbox tùy chọn). +- Giữ bề mặt công cụ khó bị dùng sai: tác tử con mặc định **không** nhận công cụ phiên. +- Hỗ trợ độ sâu lồng nhau có thể cấu hình cho các mẫu bộ điều phối. -**Ghi chú chi phí:** mỗi tác tử con có ngữ cảnh và mức sử dụng token riêng theo -mặc định. Với các tác vụ nặng hoặc lặp lại, hãy đặt một mô hình rẻ hơn cho tác tử con +**Lưu ý chi phí:** mỗi tác tử con mặc định có ngữ cảnh và mức sử dụng token +riêng. Với các tác vụ nặng hoặc lặp lại, hãy đặt mô hình rẻ hơn cho tác tử con và giữ tác tử chính trên mô hình chất lượng cao hơn. Cấu hình qua `agents.defaults.subagents.model` hoặc ghi đè theo từng tác tử. Khi một tác tử con thực sự cần transcript hiện tại của bên yêu cầu, tác tử có thể yêu cầu - `context: "fork"` trên lần tạo đó. Các phiên subagent gắn với thread mặc định - là `context: "fork"` vì chúng phân nhánh cuộc hội thoại hiện tại thành một - thread theo dõi tiếp. + `context: "fork"` trên lần sinh đó. Các phiên tác tử con gắn với luồng mặc định + dùng `context: "fork"` vì chúng rẽ nhánh cuộc trò chuyện hiện tại sang một + luồng theo dõi. -## Lệnh slash +## Lệnh gạch chéo -Dùng `/subagents` để kiểm tra hoặc điều khiển các lượt chạy tác tử con cho **phiên hiện tại**: +Dùng `/subagents` để kiểm tra hoặc điều khiển các lần chạy tác tử con cho **phiên +hiện tại**: ```text /subagents list @@ -53,15 +54,16 @@ Dùng `/subagents` để kiểm tra hoặc điều khiển các lượt chạy t /subagents spawn [--model ] [--thinking ] ``` -`/subagents info` hiển thị siêu dữ liệu lượt chạy (trạng thái, dấu thời gian, id phiên, -đường dẫn transcript, dọn dẹp). Dùng `sessions_history` để xem lại có giới hạn, -đã lọc an toàn; kiểm tra đường dẫn transcript trên đĩa khi bạn -cần transcript thô đầy đủ. +Dùng [`/steer `](/vi/tools/steer) cấp cao nhất để điều hướng lần chạy đang hoạt động của phiên bên yêu cầu hiện tại. Dùng `/subagents steer ` khi mục tiêu là một lần chạy con. -### Điều khiển gắn thread +`/subagents info` hiển thị siêu dữ liệu lần chạy (trạng thái, dấu thời gian, id phiên, +đường dẫn transcript, dọn dẹp). Dùng `sessions_history` để có chế độ xem nhớ lại có giới hạn, +được lọc an toàn; kiểm tra đường dẫn transcript trên đĩa khi bạn cần transcript đầy đủ thô. -Các lệnh này hoạt động trên những kênh hỗ trợ liên kết thread bền vững. -Xem [Các kênh hỗ trợ thread](#thread-supporting-channels) bên dưới. +### Điều khiển gắn luồng + +Các lệnh này hoạt động trên các kênh hỗ trợ gắn luồng bền vững. +Xem [Kênh hỗ trợ luồng](#thread-supporting-channels) bên dưới. ```text /focus @@ -71,79 +73,79 @@ Xem [Các kênh hỗ trợ thread](#thread-supporting-channels) bên dưới. /session max-age ``` -### Hành vi tạo +### Hành vi sinh `/subagents spawn` khởi động một tác tử con nền dưới dạng lệnh người dùng (không phải -chuyển tiếp nội bộ) và gửi một bản cập nhật hoàn tất cuối cùng trở lại -cuộc trò chuyện của bên yêu cầu khi lượt chạy kết thúc. +chuyển tiếp nội bộ) và gửi một cập nhật hoàn tất cuối cùng trở lại cuộc trò chuyện +của bên yêu cầu khi lần chạy kết thúc. - - - Lệnh tạo không chặn; nó trả về id lượt chạy ngay lập tức. + + - Lệnh sinh không chặn; nó trả về id lần chạy ngay lập tức. - Khi hoàn tất, tác tử con thông báo một thông điệp tóm tắt/kết quả trở lại kênh trò chuyện của bên yêu cầu. - - Việc hoàn tất dựa trên đẩy. Sau khi đã tạo, đừng thăm dò `/subagents list`, `sessions_list`, hoặc `sessions_history` trong vòng lặp chỉ để chờ nó kết thúc; chỉ kiểm tra trạng thái theo nhu cầu để gỡ lỗi hoặc can thiệp. - - Khi hoàn tất, OpenClaw cố gắng hết sức đóng các tab trình duyệt/quy trình được theo dõi mà phiên tác tử con đó đã mở trước khi luồng dọn dẹp thông báo tiếp tục. + - Việc hoàn tất dựa trên cơ chế đẩy. Sau khi đã sinh, **không** thăm dò `/subagents list`, `sessions_list`, hoặc `sessions_history` trong vòng lặp chỉ để chờ nó kết thúc; chỉ kiểm tra trạng thái theo nhu cầu để gỡ lỗi hoặc can thiệp. + - Khi hoàn tất, OpenClaw cố gắng đóng các tab trình duyệt/tiến trình được theo dõi mà phiên tác tử con đó đã mở trước khi luồng dọn dẹp thông báo tiếp tục. - - - OpenClaw thử gửi trực tiếp qua `agent` trước với khóa idempotency ổn định. - - Nếu gửi trực tiếp thất bại, nó chuyển sang định tuyến hàng đợi dự phòng. - - Nếu định tuyến hàng đợi vẫn chưa khả dụng, thông báo được thử lại với backoff lũy thừa ngắn trước khi bỏ cuộc cuối cùng. - - Việc gửi hoàn tất giữ tuyến bên yêu cầu đã phân giải: các tuyến hoàn tất gắn với thread hoặc gắn với cuộc hội thoại được ưu tiên khi khả dụng; nếu nguồn hoàn tất chỉ cung cấp một kênh, OpenClaw điền target/account còn thiếu từ tuyến đã phân giải của phiên bên yêu cầu (`lastChannel` / `lastTo` / `lastAccountId`) để gửi trực tiếp vẫn hoạt động. + + - OpenClaw thử chuyển phát trực tiếp qua `agent` trước với khóa idempotency ổn định. + - Nếu chuyển phát trực tiếp thất bại, nó chuyển sang định tuyến hàng đợi. + - Nếu định tuyến hàng đợi vẫn không khả dụng, thông báo sẽ được thử lại với backoff lũy thừa ngắn trước khi bỏ cuộc cuối cùng. + - Việc chuyển phát hoàn tất giữ tuyến bên yêu cầu đã phân giải: các tuyến hoàn tất gắn với luồng hoặc gắn với cuộc trò chuyện sẽ thắng khi khả dụng; nếu nguồn hoàn tất chỉ cung cấp một kênh, OpenClaw điền mục tiêu/tài khoản còn thiếu từ tuyến đã phân giải của phiên bên yêu cầu (`lastChannel` / `lastTo` / `lastAccountId`) để chuyển phát trực tiếp vẫn hoạt động. - - Bàn giao hoàn tất cho phiên bên yêu cầu là ngữ cảnh nội bộ do runtime tạo + + Bàn giao hoàn tất cho phiên bên yêu cầu là ngữ cảnh nội bộ được runtime tạo (không phải văn bản do người dùng viết) và bao gồm: - - `Result` — văn bản trả lời `assistant` hiển thị mới nhất, nếu không có thì là văn bản tool/toolResult mới nhất đã được làm sạch. Các lượt chạy thất bại ở trạng thái cuối không tái sử dụng văn bản trả lời đã thu được. + - `Result` — văn bản phản hồi `assistant` hiển thị mới nhất, nếu không thì văn bản tool/toolResult mới nhất đã được làm sạch. Các lần chạy kết thúc thất bại không tái sử dụng văn bản phản hồi đã ghi lại. - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`. - - Thống kê runtime/token rút gọn. - - Một chỉ dẫn gửi yêu cầu tác tử bên yêu cầu viết lại bằng giọng trợ lý bình thường (không chuyển tiếp siêu dữ liệu nội bộ thô). + - Thống kê runtime/token gọn. + - Một chỉ dẫn chuyển phát yêu cầu tác tử bên yêu cầu viết lại bằng giọng trợ lý bình thường (không chuyển tiếp siêu dữ liệu nội bộ thô). - - - `--model` và `--thinking` ghi đè mặc định cho lượt chạy cụ thể đó. + + - `--model` và `--thinking` ghi đè mặc định cho riêng lần chạy đó. - Dùng `info`/`log` để kiểm tra chi tiết và đầu ra sau khi hoàn tất. - - `/subagents spawn` là chế độ một lần (`mode: "run"`). Với các phiên gắn thread bền vững, dùng `sessions_spawn` với `thread: true` và `mode: "session"`. - - Với các phiên harness ACP (Claude Code, Gemini CLI, OpenCode, hoặc Codex ACP/acpx rõ ràng), dùng `sessions_spawn` với `runtime: "acp"` khi công cụ quảng bá runtime đó. Xem [mô hình gửi ACP](/vi/tools/acp-agents#delivery-model) khi gỡ lỗi việc hoàn tất hoặc các vòng lặp tác tử-với-tác tử. Khi Plugin `codex` được bật, điều khiển chat/thread của Codex nên ưu tiên `/codex ...` thay vì ACP trừ khi người dùng yêu cầu rõ ACP/acpx. - - OpenClaw ẩn `runtime: "acp"` cho đến khi ACP được bật, bên yêu cầu không bị sandbox, và một Plugin backend như `acpx` đã được tải. `runtime: "acp"` kỳ vọng một id harness ACP bên ngoài, hoặc một mục `agents.list[]` với `runtime.type="acp"`; dùng runtime tác tử con mặc định cho các tác tử cấu hình OpenClaw bình thường từ `agents_list`. + - `/subagents spawn` là chế độ một lần (`mode: "run"`). Với các phiên bền vững gắn với luồng, dùng `sessions_spawn` với `thread: true` và `mode: "session"`. + - Với các phiên bộ kiểm thử ACP (Claude Code, Gemini CLI, OpenCode, hoặc Codex ACP/acpx tường minh), dùng `sessions_spawn` với `runtime: "acp"` khi công cụ quảng bá runtime đó. Xem [mô hình chuyển phát ACP](/vi/tools/acp-agents#delivery-model) khi gỡ lỗi hoàn tất hoặc vòng lặp tác tử-đến-tác tử. Khi Plugin `codex` được bật, điều khiển trò chuyện/luồng Codex nên ưu tiên `/codex ...` thay vì ACP trừ khi người dùng yêu cầu ACP/acpx tường minh. + - OpenClaw ẩn `runtime: "acp"` cho đến khi ACP được bật, bên yêu cầu không bị sandbox, và một Plugin backend như `acpx` đã được tải. `runtime: "acp"` mong đợi một id bộ kiểm thử ACP bên ngoài, hoặc một mục `agents.list[]` với `runtime.type="acp"`; dùng runtime tác tử con mặc định cho các tác tử cấu hình OpenClaw thông thường từ `agents_list`. ## Chế độ ngữ cảnh -Tác tử con native khởi đầu tách biệt trừ khi bên gọi yêu cầu rõ ràng phân nhánh +Tác tử con gốc khởi động cô lập trừ khi bên gọi yêu cầu rõ ràng việc rẽ nhánh transcript hiện tại. -| Chế độ | Khi nào dùng | Hành vi | +| Chế độ | Khi nào dùng | Hành vi | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | Nghiên cứu mới, triển khai độc lập, công việc công cụ chậm, hoặc bất cứ việc gì có thể được tóm lược trong văn bản tác vụ | Tạo một transcript con sạch. Đây là mặc định và giúp giảm mức sử dụng token. | -| `fork` | Công việc phụ thuộc vào cuộc hội thoại hiện tại, kết quả công cụ trước đó, hoặc chỉ dẫn tinh tế đã có trong transcript của bên yêu cầu | Phân nhánh transcript của bên yêu cầu vào phiên con trước khi tác tử con bắt đầu. | +| `isolated` | Nghiên cứu mới, triển khai độc lập, công việc công cụ chậm, hoặc bất cứ điều gì có thể được tóm tắt trong văn bản tác vụ | Tạo transcript con sạch. Đây là mặc định và giúp mức sử dụng token thấp hơn. | +| `fork` | Công việc phụ thuộc vào cuộc trò chuyện hiện tại, kết quả công cụ trước đó, hoặc các chỉ dẫn tinh tế đã có trong transcript của bên yêu cầu | Rẽ nhánh transcript của bên yêu cầu vào phiên con trước khi tác tử con bắt đầu. | -Dùng `fork` một cách tiết kiệm. Nó dành cho ủy quyền nhạy theo ngữ cảnh, không phải -thay thế cho việc viết một prompt tác vụ rõ ràng. +Dùng `fork` một cách tiết chế. Nó dành cho ủy quyền nhạy với ngữ cảnh, không phải +thay thế cho việc viết lời nhắc tác vụ rõ ràng. ## Công cụ: `sessions_spawn` -Khởi động một lượt chạy tác tử con với `deliver: false` trên làn `subagent` toàn cục, -sau đó chạy một bước thông báo và đăng trả lời thông báo vào kênh trò chuyện +Khởi động một lần chạy tác tử con với `deliver: false` trên làn `subagent` toàn cục, +sau đó chạy một bước thông báo và đăng phản hồi thông báo vào kênh trò chuyện của bên yêu cầu. Tính khả dụng phụ thuộc vào chính sách công cụ hiệu lực của bên gọi. Các hồ sơ `coding` và -`full` hiển thị `sessions_spawn` theo mặc định. Hồ sơ `messaging` +`full` mặc định hiển thị `sessions_spawn`. Hồ sơ `messaging` thì không; thêm `tools.alsoAllow: ["sessions_spawn", "sessions_yield", -"subagents"]` hoặc dùng `tools.profile: "coding"` cho các tác tử cần ủy quyền -công việc. Các chính sách cho kênh/nhóm, nhà cung cấp, sandbox và allow/deny theo từng tác tử +"subagents"]` hoặc dùng `tools.profile: "coding"` cho các tác tử nên ủy quyền +công việc. Chính sách cho phép/từ chối theo kênh/nhóm, nhà cung cấp, sandbox và từng tác tử vẫn có thể loại bỏ công cụ sau giai đoạn hồ sơ. Dùng `/tools` từ cùng phiên để xác nhận danh sách công cụ hiệu lực. **Mặc định:** -- **Mô hình:** kế thừa bên gọi trừ khi bạn đặt `agents.defaults.subagents.model` (hoặc `agents.list[].subagents.model` theo từng tác tử); `sessions_spawn.model` rõ ràng vẫn được ưu tiên. -- **Thinking:** kế thừa bên gọi trừ khi bạn đặt `agents.defaults.subagents.thinking` (hoặc `agents.list[].subagents.thinking` theo từng tác tử); `sessions_spawn.thinking` rõ ràng vẫn được ưu tiên. -- **Thời hạn lượt chạy:** nếu bỏ qua `sessions_spawn.runTimeoutSeconds`, OpenClaw dùng `agents.defaults.subagents.runTimeoutSeconds` khi được đặt; nếu không thì quay về `0` (không có thời hạn). +- **Mô hình:** kế thừa bên gọi trừ khi bạn đặt `agents.defaults.subagents.model` (hoặc `agents.list[].subagents.model` theo từng tác tử); `sessions_spawn.model` tường minh vẫn thắng. +- **Thinking:** kế thừa bên gọi trừ khi bạn đặt `agents.defaults.subagents.thinking` (hoặc `agents.list[].subagents.thinking` theo từng tác tử); `sessions_spawn.thinking` tường minh vẫn thắng. +- **Thời gian chờ lần chạy:** nếu bỏ qua `sessions_spawn.runTimeoutSeconds`, OpenClaw dùng `agents.defaults.subagents.runTimeoutSeconds` khi được đặt; nếu không thì quay về `0` (không có thời gian chờ). ### Tham số công cụ @@ -154,60 +156,60 @@ phiên để xác nhận danh sách công cụ hiệu lực. Nhãn tùy chọn, dễ đọc cho con người. - Tạo dưới id tác tử khác khi được `subagents.allowAgents` cho phép. + Sinh dưới một id tác tử khác khi được `subagents.allowAgents` cho phép. - `acp` chỉ dành cho các harness ACP bên ngoài (`claude`, `droid`, `gemini`, `opencode`, hoặc Codex ACP/acpx được yêu cầu rõ ràng) và cho các mục `agents.list[]` có `runtime.type` là `acp`. + `acp` chỉ dành cho các bộ kiểm thử ACP bên ngoài (`claude`, `droid`, `gemini`, `opencode`, hoặc Codex ACP/acpx được yêu cầu tường minh) và cho các mục `agents.list[]` có `runtime.type` là `acp`. - Chỉ ACP. Tiếp tục một phiên harness ACP hiện có khi `runtime: "acp"`; bị bỏ qua với lượt tạo tác tử con native. + Chỉ ACP. Tiếp tục một phiên bộ kiểm thử ACP hiện có khi `runtime: "acp"`; bị bỏ qua với các lần sinh tác tử con gốc. - Chỉ ACP. Stream đầu ra lượt chạy ACP tới phiên cha khi `runtime: "acp"`; bỏ qua với lượt tạo tác tử con native. + Chỉ ACP. Truyền đầu ra lần chạy ACP tới phiên cha khi `runtime: "acp"`; bỏ qua với các lần sinh tác tử con gốc. - Ghi đè mô hình tác tử con. Giá trị không hợp lệ sẽ bị bỏ qua và tác tử con chạy trên mô hình mặc định với cảnh báo trong kết quả công cụ. + Ghi đè mô hình tác tử con. Giá trị không hợp lệ bị bỏ qua và tác tử con chạy trên mô hình mặc định kèm cảnh báo trong kết quả công cụ. - Ghi đè mức thinking cho lượt chạy tác tử con. + Ghi đè mức thinking cho lần chạy tác tử con. - Mặc định là `agents.defaults.subagents.runTimeoutSeconds` khi được đặt, nếu không là `0`. Khi được đặt, lượt chạy tác tử con bị hủy sau N giây. + Mặc định là `agents.defaults.subagents.runTimeoutSeconds` khi được đặt, nếu không thì `0`. Khi được đặt, lần chạy tác tử con bị hủy sau N giây. - Khi `true`, yêu cầu gắn thread kênh cho phiên tác tử con này. + Khi `true`, yêu cầu gắn luồng kênh cho phiên tác tử con này. Nếu `thread: true` và bỏ qua `mode`, mặc định trở thành `session`. `mode: "session"` yêu cầu `thread: true`. - `"delete"` lưu trữ ngay sau khi thông báo (vẫn giữ transcript bằng cách đổi tên). + `"delete"` lưu trữ ngay sau khi thông báo (vẫn giữ transcript qua đổi tên). - `require` từ chối tạo trừ khi runtime con đích được sandbox. + `require` từ chối sinh trừ khi runtime con mục tiêu được sandbox. - `fork` phân nhánh transcript hiện tại của bên yêu cầu vào phiên con. Chỉ dành cho tác tử con native. Các lượt tạo gắn thread mặc định là `fork`; các lượt tạo không gắn thread mặc định là `isolated`. + `fork` rẽ nhánh transcript hiện tại của bên yêu cầu vào phiên con. Chỉ dành cho tác tử con gốc. Các lần sinh gắn với luồng mặc định dùng `fork`; các lần sinh không theo luồng mặc định dùng `isolated`. -`sessions_spawn` không chấp nhận tham số gửi qua kênh (`target`, -`channel`, `to`, `threadId`, `replyTo`, `transport`). Để gửi, dùng -`message`/`sessions_send` từ lượt chạy đã tạo. +`sessions_spawn` **không** chấp nhận tham số chuyển phát kênh (`target`, +`channel`, `to`, `threadId`, `replyTo`, `transport`). Để chuyển phát, dùng +`message`/`sessions_send` từ lần chạy đã sinh. -## Phiên gắn thread +## Phiên gắn với luồng -Khi liên kết thread được bật cho một kênh, tác tử con có thể tiếp tục gắn với -một thread để các tin nhắn người dùng theo dõi tiếp trong thread đó tiếp tục định tuyến tới +Khi gắn luồng được bật cho một kênh, một tác tử con có thể tiếp tục gắn +với một luồng để các tin nhắn theo dõi của người dùng trong luồng đó tiếp tục định tuyến tới cùng phiên tác tử con. -### Các kênh hỗ trợ thread +### Kênh hỗ trợ luồng **Discord** hiện là kênh duy nhất được hỗ trợ. Kênh này hỗ trợ -các phiên subagent gắn thread bền vững (`sessions_spawn` với -`thread: true`), điều khiển thread thủ công (`/focus`, `/unfocus`, `/agents`, -`/session idle`, `/session max-age`), và các khóa adapter +các phiên tác tử con gắn luồng bền vững (`sessions_spawn` với +`thread: true`), điều khiển luồng thủ công (`/focus`, `/unfocus`, `/agents`, +`/session idle`, `/session max-age`), và các khóa bộ điều hợp `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`, và @@ -216,80 +218,80 @@ các phiên subagent gắn thread bền vững (`sessions_spawn` với ### Luồng nhanh - + `sessions_spawn` với `thread: true` (và tùy chọn `mode: "session"`). - - OpenClaw tạo hoặc gắn một thread vào target phiên đó trong kênh đang hoạt động. + + OpenClaw tạo hoặc gắn một luồng với mục tiêu phiên đó trong kênh đang hoạt động. - - Các trả lời và tin nhắn theo dõi tiếp trong thread đó định tuyến tới phiên đã gắn. + + Các phản hồi và tin nhắn theo dõi trong luồng đó được định tuyến tới phiên đã gắn. - - Dùng `/session idle` để kiểm tra/cập nhật tự động unfocus khi không hoạt động và - `/session max-age` để điều khiển giới hạn cứng. + + Dùng `/session idle` để kiểm tra/cập nhật tự động bỏ tập trung khi không hoạt động và + `/session max-age` để kiểm soát giới hạn cứng. - + Dùng `/unfocus` để tách thủ công. ### Điều khiển thủ công -| Lệnh | Tác dụng | -| ------------------ | --------------------------------------------------------------------- | -| `/focus ` | Ràng buộc luồng hiện tại (hoặc tạo một luồng) với mục tiêu tác nhân phụ/phiên | -| `/unfocus` | Xóa ràng buộc cho luồng hiện đang được ràng buộc | -| `/agents` | Liệt kê các lần chạy đang hoạt động và trạng thái ràng buộc (`thread:` hoặc `unbound`) | -| `/session idle` | Kiểm tra/cập nhật tự động hủy tập trung khi nhàn rỗi (chỉ các luồng được ràng buộc đang được tập trung) | -| `/session max-age` | Kiểm tra/cập nhật giới hạn cứng (chỉ các luồng được ràng buộc đang được tập trung) | +| Lệnh | Tác dụng | +| ----------------- | --------------------------------------------------------------------- | +| `/focus ` | Liên kết luồng hiện tại (hoặc tạo một luồng) với mục tiêu tác nhân phụ/phiên | +| `/unfocus` | Xóa liên kết cho luồng hiện đang được liên kết | +| `/agents` | Liệt kê các lượt chạy đang hoạt động và trạng thái liên kết (`thread:` hoặc `unbound`) | +| `/session idle` | Kiểm tra/cập nhật tự động bỏ tập trung khi nhàn rỗi (chỉ các luồng đã liên kết đang được tập trung) | +| `/session max-age` | Kiểm tra/cập nhật giới hạn cứng (chỉ các luồng đã liên kết đang được tập trung) | ### Công tắc cấu hình - **Mặc định toàn cục:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. -- **Khóa ghi đè kênh và tự động ràng buộc khi sinh** là đặc thù theo bộ chuyển đổi. Xem [Kênh hỗ trợ luồng](#thread-supporting-channels) ở trên. +- **Ghi đè theo kênh và khóa tự động liên kết khi sinh phiên** phụ thuộc vào adapter. Xem [Các kênh hỗ trợ luồng](#thread-supporting-channels) ở trên. Xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference) và -[Lệnh gạch chéo](/vi/tools/slash-commands) để biết chi tiết bộ chuyển đổi hiện tại. +[Lệnh slash](/vi/tools/slash-commands) để biết chi tiết adapter hiện tại. ### Danh sách cho phép - Danh sách ID tác nhân có thể được nhắm mục tiêu qua `agentId` rõ ràng (`["*"]` cho phép bất kỳ). Mặc định: chỉ tác nhân yêu cầu. Nếu bạn đặt một danh sách và vẫn muốn tác nhân yêu cầu tự sinh chính nó bằng `agentId`, hãy đưa ID của tác nhân yêu cầu vào danh sách. + Danh sách id tác nhân có thể được nhắm mục tiêu qua `agentId` tường minh (`["*"]` cho phép bất kỳ tác nhân nào). Mặc định: chỉ tác nhân yêu cầu. Nếu bạn đặt một danh sách và vẫn muốn tác nhân yêu cầu tự sinh chính nó bằng `agentId`, hãy đưa id của tác nhân yêu cầu vào danh sách. - Danh sách cho phép tác nhân mục tiêu mặc định được dùng khi tác nhân yêu cầu không đặt `subagents.allowAgents` riêng. + Danh sách cho phép tác nhân đích mặc định được dùng khi tác nhân yêu cầu không đặt `subagents.allowAgents` riêng. - Chặn các lệnh gọi `sessions_spawn` bỏ qua `agentId` (buộc chọn hồ sơ rõ ràng). Ghi đè theo từng tác nhân: `agents.list[].subagents.requireAgentId`. + Chặn các lệnh gọi `sessions_spawn` bỏ qua `agentId` (buộc chọn hồ sơ tường minh). Ghi đè theo từng tác nhân: `agents.list[].subagents.requireAgentId`. -Nếu phiên yêu cầu được sandbox, `sessions_spawn` sẽ từ chối các mục tiêu -sẽ chạy không trong sandbox. +Nếu phiên yêu cầu bị sandbox, `sessions_spawn` sẽ từ chối các mục tiêu +có thể chạy không trong sandbox. ### Khám phá -Dùng `agents_list` để xem những ID tác nhân nào hiện được phép cho -`sessions_spawn`. Phản hồi bao gồm mô hình hiệu dụng của từng tác nhân được liệt kê -và siêu dữ liệu runtime nhúng để bên gọi có thể phân biệt PI, máy chủ ứng dụng Codex -và các runtime gốc khác đã cấu hình. +Dùng `agents_list` để xem các id tác nhân nào hiện được phép cho +`sessions_spawn`. Phản hồi bao gồm model hiệu lực của từng tác nhân được liệt kê +và metadata runtime được nhúng để bên gọi có thể phân biệt PI, máy chủ ứng dụng Codex +và các runtime native đã cấu hình khác. ### Tự động lưu trữ -- Các phiên tác nhân phụ được tự động lưu trữ sau `agents.defaults.subagents.archiveAfterMinutes` (mặc định `60`). -- Lưu trữ dùng `sessions.delete` và đổi tên bản ghi hội thoại thành `*.deleted.` (cùng thư mục). -- `cleanup: "delete"` lưu trữ ngay sau khi thông báo (vẫn giữ bản ghi hội thoại bằng cách đổi tên). +- Phiên tác nhân phụ được tự động lưu trữ sau `agents.defaults.subagents.archiveAfterMinutes` (mặc định `60`). +- Lưu trữ dùng `sessions.delete` và đổi tên bản ghi transcript thành `*.deleted.` (cùng thư mục). +- `cleanup: "delete"` lưu trữ ngay sau khi thông báo (vẫn giữ transcript qua đổi tên). - Tự động lưu trữ là nỗ lực tối đa; các bộ hẹn giờ đang chờ sẽ mất nếu Gateway khởi động lại. -- `runTimeoutSeconds` **không** tự động lưu trữ; nó chỉ dừng lần chạy. Phiên vẫn còn cho đến khi tự động lưu trữ. +- `runTimeoutSeconds` **không** tự động lưu trữ; nó chỉ dừng lượt chạy. Phiên vẫn tồn tại cho đến khi tự động lưu trữ. - Tự động lưu trữ áp dụng như nhau cho các phiên độ sâu 1 và độ sâu 2. -- Dọn dẹp trình duyệt tách biệt với dọn dẹp lưu trữ: các tab/tiến trình trình duyệt được theo dõi sẽ được đóng theo nỗ lực tối đa khi lần chạy kết thúc, ngay cả khi bản ghi hội thoại/bản ghi phiên được giữ lại. +- Dọn dẹp trình duyệt tách biệt với dọn dẹp lưu trữ: các tab/tiến trình trình duyệt được theo dõi sẽ được đóng theo cơ chế nỗ lực tối đa khi lượt chạy kết thúc, ngay cả khi bản ghi transcript/phiên được giữ lại. ## Tác nhân phụ lồng nhau Theo mặc định, tác nhân phụ không thể sinh tác nhân phụ của riêng chúng (`maxSpawnDepth: 1`). Đặt `maxSpawnDepth: 2` để bật một cấp -lồng nhau — **mẫu điều phối**: chính → tác nhân phụ điều phối → -các tác nhân phụ con làm việc. +lồng nhau — **mẫu bộ điều phối**: chính → tác nhân phụ điều phối → +các tác nhân phụ cấp con làm worker. ```json5 { @@ -308,31 +310,31 @@ các tác nhân phụ con làm việc. ### Cấp độ sâu -| Độ sâu | Dạng khóa phiên | Vai trò | Có thể sinh? | -| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | Tác nhân chính | Luôn luôn | -| 1 | `agent::subagent:` | Tác nhân phụ (điều phối khi cho phép độ sâu 2) | Chỉ khi `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | Tác nhân phụ con (worker lá) | Không bao giờ | +| Độ sâu | Dạng khóa phiên | Vai trò | Có thể sinh? | +| ------ | -------------------------------------------- | -------------------------------------------- | ---------------------------- | +| 0 | `agent::main` | Tác nhân chính | Luôn luôn | +| 1 | `agent::subagent:` | Tác nhân phụ (bộ điều phối khi cho phép độ sâu 2) | Chỉ khi `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | Tác nhân phụ cấp con (worker lá) | Không bao giờ | ### Chuỗi thông báo -Kết quả chảy ngược lên chuỗi: +Kết quả chảy ngược lên theo chuỗi: -1. Worker độ sâu 2 hoàn tất → thông báo cho cha của nó (điều phối viên độ sâu 1). -2. Điều phối viên độ sâu 1 nhận thông báo, tổng hợp kết quả, hoàn tất → thông báo cho chính. -3. Tác nhân chính nhận thông báo và gửi cho người dùng. +1. Worker độ sâu 2 hoàn tất → thông báo cho cha của nó (bộ điều phối độ sâu 1). +2. Bộ điều phối độ sâu 1 nhận thông báo, tổng hợp kết quả, hoàn tất → thông báo cho tác nhân chính. +3. Tác nhân chính nhận thông báo và chuyển đến người dùng. -Mỗi cấp chỉ thấy thông báo từ con trực tiếp của nó. +Mỗi cấp chỉ thấy thông báo từ các con trực tiếp của nó. -**Hướng dẫn vận hành:** bắt đầu công việc con một lần và chờ sự kiện hoàn tất -thay vì xây dựng vòng lặp thăm dò quanh `sessions_list`, -`sessions_history`, `/subagents list`, hoặc lệnh ngủ `exec`. +**Hướng dẫn vận hành:** bắt đầu công việc con một lần và chờ sự kiện +hoàn tất thay vì xây các vòng lặp thăm dò quanh `sessions_list`, +`sessions_history`, `/subagents list`, hoặc các lệnh ngủ `exec`. `sessions_list` và `/subagents list` giữ các quan hệ phiên con -tập trung vào công việc đang hoạt động — con đang hoạt động vẫn được gắn, con đã kết thúc vẫn -hiển thị trong một cửa sổ gần đây ngắn, và các liên kết con chỉ còn trong kho đã cũ -bị bỏ qua sau cửa sổ độ mới của chúng. Điều này ngăn siêu dữ liệu `spawnedBy` / -`parentSessionKey` cũ hồi sinh các con ảo sau khi +tập trung vào công việc đang chạy — con đang chạy vẫn được gắn, con đã kết thúc vẫn +hiển thị trong một cửa sổ gần đây ngắn, và các liên kết con chỉ còn trong kho lưu trữ đã cũ +sẽ bị bỏ qua sau cửa sổ độ mới của chúng. Điều này ngăn metadata `spawnedBy` / +`parentSessionKey` cũ làm sống lại các con ma sau khi khởi động lại. Nếu một sự kiện hoàn tất của con đến sau khi bạn đã gửi câu trả lời cuối cùng, phản hồi tiếp theo đúng là token im lặng chính xác `NO_REPLY` / `no_reply`. @@ -340,78 +342,78 @@ câu trả lời cuối cùng, phản hồi tiếp theo đúng là token im lặ ### Chính sách công cụ theo độ sâu -- Vai trò và phạm vi điều khiển được ghi vào siêu dữ liệu phiên tại thời điểm sinh. Điều đó giúp các khóa phiên phẳng hoặc được khôi phục không vô tình lấy lại đặc quyền điều phối. -- **Độ sâu 1 (điều phối viên, khi `maxSpawnDepth >= 2`):** nhận `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` để có thể quản lý con của nó. Các công cụ phiên/hệ thống khác vẫn bị từ chối. +- Vai trò và phạm vi điều khiển được ghi vào metadata phiên tại thời điểm sinh. Điều đó giữ cho các khóa phiên phẳng hoặc đã khôi phục không vô tình lấy lại đặc quyền bộ điều phối. +- **Độ sâu 1 (bộ điều phối, khi `maxSpawnDepth >= 2`):** nhận `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` để có thể quản lý các con. Các công cụ phiên/hệ thống khác vẫn bị từ chối. - **Độ sâu 1 (lá, khi `maxSpawnDepth == 1`):** không có công cụ phiên (hành vi mặc định hiện tại). - **Độ sâu 2 (worker lá):** không có công cụ phiên — `sessions_spawn` luôn bị từ chối ở độ sâu 2. Không thể sinh thêm con. ### Giới hạn sinh theo từng tác nhân Mỗi phiên tác nhân (ở bất kỳ độ sâu nào) có thể có tối đa `maxChildrenPerAgent` -(mặc định `5`) con đang hoạt động tại một thời điểm. Điều này ngăn một điều phối viên đơn lẻ -phân nhánh mất kiểm soát. +(mặc định `5`) con đang hoạt động cùng lúc. Điều này ngăn một bộ điều phối duy nhất +fan-out mất kiểm soát. ### Dừng dây chuyền -Dừng một điều phối viên độ sâu 1 sẽ tự động dừng tất cả con độ sâu 2 +Dừng một bộ điều phối độ sâu 1 sẽ tự động dừng tất cả các con độ sâu 2 của nó: -- `/stop` trong cuộc trò chuyện chính dừng tất cả tác nhân độ sâu 1 và dây chuyền đến con độ sâu 2 của chúng. -- `/subagents kill ` dừng một tác nhân phụ cụ thể và dây chuyền đến con của nó. -- `/subagents kill all` dừng tất cả tác nhân phụ cho bên yêu cầu và dây chuyền. +- `/stop` trong cuộc trò chuyện chính dừng tất cả tác nhân độ sâu 1 và dừng dây chuyền đến các con độ sâu 2 của chúng. +- `/subagents kill ` dừng một tác nhân phụ cụ thể và dừng dây chuyền đến các con của nó. +- `/subagents kill all` dừng tất cả tác nhân phụ cho bên yêu cầu và dừng dây chuyền. ## Xác thực -Xác thực tác nhân phụ được phân giải theo **ID tác nhân**, không theo loại phiên: +Xác thực tác nhân phụ được phân giải theo **id tác nhân**, không theo loại phiên: - Khóa phiên tác nhân phụ là `agent::subagent:`. - Kho xác thực được tải từ `agentDir` của tác nhân đó. -- Hồ sơ xác thực của tác nhân chính được hợp nhất vào làm **dự phòng**; hồ sơ tác nhân ghi đè hồ sơ chính khi có xung đột. +- Các hồ sơ xác thực của tác nhân chính được hợp nhất làm **dự phòng**; hồ sơ tác nhân ghi đè hồ sơ chính khi có xung đột. -Việc hợp nhất là bổ sung, nên hồ sơ chính luôn có sẵn làm -dự phòng. Xác thực hoàn toàn cô lập theo từng tác nhân chưa được hỗ trợ. +Việc hợp nhất là cộng thêm, vì vậy hồ sơ chính luôn có sẵn làm +dự phòng. Xác thực cô lập hoàn toàn theo từng tác nhân hiện chưa được hỗ trợ. ## Thông báo Tác nhân phụ báo cáo lại qua một bước thông báo: - Bước thông báo chạy bên trong phiên tác nhân phụ (không phải phiên yêu cầu). -- Nếu tác nhân phụ trả lời chính xác `ANNOUNCE_SKIP`, không có gì được đăng. -- Nếu văn bản trợ lý mới nhất là token im lặng chính xác `NO_REPLY` / `no_reply`, đầu ra thông báo bị chặn ngay cả khi trước đó có tiến trình hiển thị. +- Nếu tác nhân phụ trả lời chính xác `ANNOUNCE_SKIP`, sẽ không có gì được đăng. +- Nếu văn bản assistant mới nhất là token im lặng chính xác `NO_REPLY` / `no_reply`, đầu ra thông báo bị chặn ngay cả khi trước đó đã có tiến trình hiển thị. -Việc gửi phụ thuộc vào độ sâu của bên yêu cầu: +Cách chuyển phụ thuộc vào độ sâu của bên yêu cầu: -- Các phiên yêu cầu cấp cao nhất dùng một lệnh gọi `agent` tiếp theo với gửi bên ngoài (`deliver=true`). -- Các phiên tác nhân phụ yêu cầu lồng nhau nhận một phần chèn tiếp theo nội bộ (`deliver=false`) để điều phối viên có thể tổng hợp kết quả con trong phiên. -- Nếu một phiên tác nhân phụ yêu cầu lồng nhau không còn, OpenClaw quay về bên yêu cầu của phiên đó khi có sẵn. +- Phiên yêu cầu cấp cao nhất dùng một lệnh gọi `agent` tiếp theo với chuyển phát bên ngoài (`deliver=true`). +- Phiên tác nhân phụ yêu cầu lồng nhau nhận một lần chèn theo dõi nội bộ (`deliver=false`) để bộ điều phối có thể tổng hợp kết quả con trong phiên. +- Nếu một phiên tác nhân phụ yêu cầu lồng nhau đã biến mất, OpenClaw sẽ quay về bên yêu cầu của phiên đó khi có sẵn. -Đối với các phiên yêu cầu cấp cao nhất, gửi trực tiếp ở chế độ hoàn tất trước tiên -phân giải bất kỳ tuyến hội thoại/luồng được ràng buộc nào và ghi đè hook, sau đó điền +Đối với các phiên yêu cầu cấp cao nhất, chuyển phát trực tiếp ở chế độ hoàn tất trước tiên +phân giải mọi tuyến cuộc trò chuyện/luồng đã liên kết và ghi đè hook, rồi điền các trường mục tiêu kênh còn thiếu từ tuyến đã lưu của phiên yêu cầu. -Điều này giữ các hoàn tất ở đúng cuộc trò chuyện/chủ đề ngay cả khi nguồn gốc hoàn tất +Điều đó giữ các lần hoàn tất ở đúng cuộc trò chuyện/chủ đề ngay cả khi nguồn gốc hoàn tất chỉ xác định kênh. -Việc tổng hợp hoàn tất của con được giới hạn trong lần chạy yêu cầu hiện tại khi -xây dựng các phát hiện hoàn tất lồng nhau, ngăn đầu ra con từ lần chạy trước đã cũ +Tổng hợp hoàn tất của con được giới hạn trong lượt chạy yêu cầu hiện tại khi +xây dựng các phát hiện hoàn tất lồng nhau, ngăn đầu ra con từ lượt chạy trước đã cũ rò rỉ vào thông báo hiện tại. Phản hồi thông báo giữ nguyên -định tuyến luồng/chủ đề khi có sẵn trên bộ chuyển đổi kênh. +định tuyến luồng/chủ đề khi adapter kênh có sẵn. ### Ngữ cảnh thông báo Ngữ cảnh thông báo được chuẩn hóa thành một khối sự kiện nội bộ ổn định: -| Trường | Nguồn | -| -------------- | ------------------------------------------------------------------------------------------------------------- | -| Nguồn | `subagent` hoặc `cron` | -| ID phiên | Khóa/ID phiên con | -| Loại | Loại thông báo + nhãn tác vụ | -| Trạng thái | Suy ra từ kết quả runtime (`success`, `error`, `timeout`, hoặc `unknown`) — **không** suy luận từ văn bản mô hình | -| Nội dung kết quả | Văn bản trợ lý hiển thị mới nhất, nếu không thì văn bản công cụ/toolResult mới nhất đã được làm sạch | -| Tiếp theo | Chỉ dẫn mô tả khi nào nên trả lời so với giữ im lặng | +| Trường | Nguồn | +| ---------------- | ------------------------------------------------------------------------------------------------------------- | +| Nguồn | `subagent` hoặc `cron` | +| Id phiên | Khóa/id phiên con | +| Loại | Loại thông báo + nhãn tác vụ | +| Trạng thái | Suy ra từ kết quả runtime (`success`, `error`, `timeout`, hoặc `unknown`) — **không** suy ra từ văn bản model | +| Nội dung kết quả | Văn bản assistant hiển thị mới nhất, nếu không thì văn bản tool/toolResult mới nhất đã được làm sạch | +| Theo dõi | Chỉ dẫn mô tả khi nào nên trả lời so với giữ im lặng | -Các lần chạy kết thúc thất bại báo cáo trạng thái thất bại mà không phát lại +Các lượt chạy kết thúc bằng lỗi báo cáo trạng thái lỗi mà không phát lại văn bản trả lời đã ghi lại. Khi hết thời gian, nếu con chỉ đi qua các lệnh gọi công cụ, -thông báo có thể thu gọn lịch sử đó thành một bản tóm tắt tiến trình một phần ngắn +thông báo có thể thu gọn lịch sử đó thành một tóm tắt tiến trình một phần ngắn thay vì phát lại đầu ra công cụ thô. ### Dòng thống kê @@ -420,29 +422,28 @@ Payload thông báo bao gồm một dòng thống kê ở cuối (ngay cả khi - Runtime (ví dụ `runtime 5m12s`). - Mức sử dụng token (đầu vào/đầu ra/tổng). -- Chi phí ước tính khi giá mô hình được cấu hình (`models.providers.*.models[].cost`). -- `sessionKey`, `sessionId`, và đường dẫn bản ghi hội thoại để tác nhân chính có thể lấy lịch sử qua `sessions_history` hoặc kiểm tra tệp trên đĩa. +- Chi phí ước tính khi giá model được cấu hình (`models.providers.*.models[].cost`). +- `sessionKey`, `sessionId`, và đường dẫn transcript để tác nhân chính có thể lấy lịch sử qua `sessions_history` hoặc kiểm tra tệp trên đĩa. -Siêu dữ liệu nội bộ chỉ dùng cho điều phối; các phản hồi hướng tới người dùng -nên được viết lại bằng giọng trợ lý bình thường. +Metadata nội bộ chỉ dành cho điều phối; các phản hồi hướng tới người dùng +nên được viết lại bằng giọng assistant bình thường. ### Vì sao nên ưu tiên `sessions_history` -`sessions_history` là đường điều phối an toàn hơn: +`sessions_history` là đường dẫn điều phối an toàn hơn: -- Việc nhớ lại của trợ lý được chuẩn hóa trước: loại bỏ thẻ suy nghĩ; loại bỏ khung `` / ``; loại bỏ các khối payload XML lệnh gọi công cụ dạng văn bản thuần (``, ``, ``, ``), bao gồm cả payload bị cắt cụt chưa bao giờ đóng sạch; loại bỏ khung lệnh gọi/kết quả công cụ bị hạ cấp và dấu mốc ngữ cảnh lịch sử; loại bỏ token điều khiển mô hình bị rò rỉ (`<|assistant|>`, các ASCII `<|...|>` khác, dạng toàn chiều rộng `<｜...｜>`); loại bỏ XML lệnh gọi công cụ MiniMax sai định dạng. -- Văn bản giống thông tin xác thực/token được biên tập. +- Trí nhớ lại của assistant được chuẩn hóa trước: loại bỏ thẻ suy nghĩ; loại bỏ khung `` / ``; loại bỏ các khối payload XML lời gọi công cụ dạng văn bản thuần (``, ``, ``, ``), bao gồm các payload bị cắt cụt không bao giờ đóng sạch; loại bỏ khung lời gọi/kết quả công cụ bị hạ cấp và các marker ngữ cảnh lịch sử; loại bỏ token điều khiển model bị rò rỉ (`<|assistant|>`, các ASCII `<|...|>` khác, dạng toàn độ rộng `<｜...｜>`); loại bỏ XML lời gọi công cụ MiniMax sai định dạng. +- Văn bản giống thông tin xác thực/token được biên tập lại. - Các khối dài có thể bị cắt ngắn. -- Lịch sử rất lớn có thể bỏ các hàng cũ hơn hoặc thay một hàng quá khổ bằng `[sessions_history omitted: message too large]`. -- Kiểm tra bản ghi hội thoại thô trên đĩa là phương án dự phòng khi bạn cần bản ghi đầy đủ từng byte một. +- Lịch sử rất lớn có thể bỏ các hàng cũ hơn hoặc thay một hàng quá lớn bằng `[sessions_history omitted: message too large]`. +- Kiểm tra transcript thô trên đĩa là phương án dự phòng khi bạn cần transcript đầy đủ từng byte. ## Chính sách công cụ -Tác nhân phụ trước tiên dùng cùng hồ sơ và pipeline chính sách công cụ như tác nhân cha hoặc -tác nhân mục tiêu. Sau đó, OpenClaw áp dụng lớp hạn chế -tác nhân phụ. +Tác nhân phụ dùng cùng hồ sơ và pipeline chính sách công cụ như tác nhân cha hoặc +tác nhân đích trước. Sau đó, OpenClaw áp dụng lớp hạn chế tác nhân phụ. -Khi không có `tools.profile` hạn chế, tác nhân phụ nhận **tất cả công cụ ngoại trừ +Khi không có `tools.profile` hạn chế, tác nhân phụ nhận **tất cả công cụ trừ công cụ phiên** và công cụ hệ thống: - `sessions_list` @@ -450,12 +451,12 @@ công cụ phiên** và công cụ hệ thống: - `sessions_send` - `sessions_spawn` -`sessions_history` vẫn là một chế độ xem nhớ lại có giới hạn, đã làm sạch ở đây nữa — nó -không phải là bản dump bản ghi hội thoại thô. +`sessions_history` vẫn là một chế độ xem nhớ lại có giới hạn và đã làm sạch ở đây nữa — nó +không phải bản dump transcript thô. -Khi `maxSpawnDepth >= 2`, các tác nhân phụ điều phối độ sâu 1 còn +Khi `maxSpawnDepth >= 2`, các tác nhân phụ bộ điều phối độ sâu 1 còn nhận `sessions_spawn`, `subagents`, `sessions_list`, và -`sessions_history` để có thể quản lý con của chúng. +`sessions_history` để có thể quản lý các con của chúng. ### Ghi đè qua cấu hình @@ -485,8 +486,8 @@ nhận `sessions_spawn`, `subagents`, `sessions_list`, và tập công cụ đã được phân giải, nhưng không thể **thêm lại** một công cụ đã bị xóa bởi `tools.profile`. Ví dụ, `tools.profile: "coding"` bao gồm `web_search`/`web_fetch` nhưng không bao gồm công cụ `browser`. Để cho phép -các sub-agent dùng coding-profile sử dụng tự động hóa trình duyệt, hãy thêm browser ở -giai đoạn profile: +các tác nhân phụ dùng hồ sơ coding sử dụng tự động hóa trình duyệt, hãy thêm browser ở +giai đoạn hồ sơ: ```json5 { @@ -497,65 +498,64 @@ giai đoạn profile: } ``` -Dùng `agents.list[].tools.alsoAllow: ["browser"]` theo từng agent khi chỉ một -agent cần có tự động hóa trình duyệt. +Dùng `agents.list[].tools.alsoAllow: ["browser"]` cho từng tác nhân khi chỉ một +tác nhân nên có tự động hóa trình duyệt. ## Đồng thời -Sub-agent sử dụng một lane hàng đợi chuyên dụng trong tiến trình: +Các tác nhân phụ dùng một làn hàng đợi chuyên dụng trong cùng tiến trình: -- **Tên lane:** `subagent` -- **Độ đồng thời:** `agents.defaults.subagents.maxConcurrent` (mặc định `8`) +- **Tên làn:** `subagent` +- **Đồng thời:** `agents.defaults.subagents.maxConcurrent` (mặc định `8`) -## Tính sống và khôi phục +## Khả năng hoạt động và khôi phục OpenClaw không xem việc thiếu `endedAt` là bằng chứng vĩnh viễn rằng một -sub-agent vẫn còn sống. Các lần chạy chưa kết thúc cũ hơn cửa sổ stale-run -sẽ không còn được tính là active/pending trong `/subagents list`, bản tóm tắt trạng thái, -cổng hoàn tất descendant, và kiểm tra độ đồng thời theo từng phiên. +tác nhân phụ vẫn còn hoạt động. Các lượt chạy chưa kết thúc cũ hơn cửa sổ lượt chạy lỗi thời +sẽ không còn được tính là đang hoạt động/đang chờ trong `/subagents list`, tóm tắt trạng thái, +cổng hoàn tất hậu duệ, và kiểm tra đồng thời theo phiên. -Sau khi Gateway khởi động lại, các lần chạy đã khôi phục nhưng chưa kết thúc và đã stale sẽ bị loại bỏ, trừ khi +Sau khi Gateway khởi động lại, các lượt chạy được khôi phục nhưng chưa kết thúc và đã lỗi thời sẽ bị cắt bỏ trừ khi phiên con của chúng được đánh dấu `abortedLastRun: true`. Những -phiên con bị hủy do khởi động lại này vẫn có thể khôi phục qua luồng khôi phục orphan của sub-agent, -luồng này gửi một thông điệp resume tổng hợp trước khi +phiên con bị hủy do khởi động lại này vẫn có thể khôi phục qua luồng khôi phục tác nhân phụ mồ côi, +luồng này gửi một thông báo tiếp tục tổng hợp trước khi xóa dấu hủy. Khôi phục tự động sau khởi động lại được giới hạn theo từng phiên con. Nếu cùng một -sub-agent con được chấp nhận để khôi phục orphan lặp lại bên trong -cửa sổ rapid re-wedge, OpenClaw lưu một tombstone khôi phục trên -phiên đó và dừng tự động resume nó trong các lần khởi động lại sau. Chạy -`openclaw tasks maintenance --apply` để đối chiếu bản ghi tác vụ, hoặc -`openclaw doctor --fix` để xóa các cờ khôi phục đã hủy stale trên -các phiên đã tombstone. +phiên con tác nhân phụ được chấp nhận để khôi phục mồ côi nhiều lần trong +cửa sổ kẹt lại nhanh, OpenClaw sẽ lưu một dấu mộ khôi phục trên +phiên đó và dừng tự động tiếp tục phiên đó ở các lần khởi động lại sau. Chạy +`openclaw tasks maintenance --apply` để đối soát bản ghi tác vụ, hoặc +`openclaw doctor --fix` để xóa các cờ khôi phục đã hủy lỗi thời trên +các phiên có dấu mộ. -Nếu việc spawn sub-agent thất bại với Gateway `PAIRING_REQUIRED` / -`scope-upgrade`, hãy kiểm tra bên gọi RPC trước khi chỉnh sửa trạng thái ghép nối. +Nếu việc khởi tạo tác nhân phụ thất bại với Gateway `PAIRING_REQUIRED` / +`scope-upgrade`, hãy kiểm tra bên gọi RPC trước khi chỉnh sửa trạng thái ghép đôi. Điều phối `sessions_spawn` nội bộ nên kết nối dưới dạng -`client.id: "gateway-client"` với `client.mode: "backend"` qua xác thực -shared-token/password local loopback trực tiếp; đường dẫn đó không phụ thuộc vào -baseline phạm vi thiết bị đã ghép nối của CLI. Các bên gọi từ xa, -`deviceIdentity` tường minh, đường dẫn device-token tường minh, và client trình duyệt/node -vẫn cần phê duyệt thiết bị thông thường cho các nâng cấp phạm vi. +`client.id: "gateway-client"` với `client.mode: "backend"` qua xác thực shared-token/password +local loopback trực tiếp; đường dẫn đó không phụ thuộc vào đường cơ sở phạm vi thiết bị đã ghép đôi của +CLI. Các bên gọi từ xa, `deviceIdentity` rõ ràng, đường dẫn device-token rõ ràng, và trình khách browser/node +vẫn cần phê duyệt thiết bị bình thường cho nâng cấp phạm vi. ## Dừng -- Gửi `/stop` trong cuộc trò chuyện của requester sẽ hủy phiên requester và dừng mọi lần chạy sub-agent đang active được spawn từ phiên đó, lan truyền đến các con lồng nhau. -- `/subagents kill ` dừng một sub-agent cụ thể và lan truyền đến các con của nó. +- Gửi `/stop` trong cuộc trò chuyện của bên yêu cầu sẽ hủy phiên của bên yêu cầu và dừng mọi lượt chạy tác nhân phụ đang hoạt động được khởi tạo từ đó, lan truyền đến các phiên con lồng nhau. +- `/subagents kill ` dừng một tác nhân phụ cụ thể và lan truyền đến các phiên con của nó. ## Giới hạn -- Thông báo của sub-agent là **best-effort**. Nếu Gateway khởi động lại, công việc "announce back" đang chờ sẽ bị mất. -- Sub-agent vẫn chia sẻ cùng tài nguyên tiến trình Gateway; hãy xem `maxConcurrent` là một van an toàn. +- Thông báo tác nhân phụ là **nỗ lực tối đa**. Nếu Gateway khởi động lại, công việc "announce back" đang chờ sẽ bị mất. +- Các tác nhân phụ vẫn chia sẻ cùng tài nguyên tiến trình Gateway; hãy xem `maxConcurrent` như một van an toàn. - `sessions_spawn` luôn không chặn: nó trả về `{ status: "accepted", runId, childSessionKey }` ngay lập tức. -- Ngữ cảnh sub-agent chỉ chèn `AGENTS.md` + `TOOLS.md` (không có `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, hoặc `BOOTSTRAP.md`). -- Độ sâu lồng nhau tối đa là 5 (phạm vi `maxSpawnDepth`: 1–5). Khuyến nghị dùng độ sâu 2 cho hầu hết trường hợp sử dụng. -- `maxChildrenPerAgent` giới hạn số con active trên mỗi phiên (mặc định `5`, phạm vi `1–20`). +- Ngữ cảnh tác nhân phụ chỉ chèn `AGENTS.md` + `TOOLS.md` (không có `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, hoặc `BOOTSTRAP.md`). +- Độ sâu lồng nhau tối đa là 5 (phạm vi `maxSpawnDepth`: 1–5). Độ sâu 2 được khuyến nghị cho hầu hết trường hợp sử dụng. +- `maxChildrenPerAgent` giới hạn số phiên con đang hoạt động trên mỗi phiên (mặc định `5`, phạm vi `1–20`). ## Liên quan -- [ACP agents](/vi/tools/acp-agents) -- [Agent send](/vi/tools/agent-send) +- [Tác nhân ACP](/vi/tools/acp-agents) +- [Gửi tác nhân](/vi/tools/agent-send) - [Tác vụ nền](/vi/automation/tasks) -- [Công cụ sandbox đa agent](/vi/tools/multi-agent-sandbox-tools) +- [Công cụ sandbox đa tác nhân](/vi/tools/multi-agent-sandbox-tools) diff --git a/docs/vi/tools/thinking.md b/docs/vi/tools/thinking.md index 93804342a..c159a7b9e 100644 --- a/docs/vi/tools/thinking.md +++ b/docs/vi/tools/thinking.md @@ -1,61 +1,61 @@ --- read_when: - - Điều chỉnh việc phân tích cú pháp hoặc giá trị mặc định của các chỉ thị thinking, fast-mode hoặc verbose + - Điều chỉnh cách phân tích hoặc mặc định cho các chỉ thị thinking, fast-mode hoặc verbose summary: Cú pháp chỉ thị cho /think, /fast, /verbose, /trace và khả năng hiển thị suy luận title: Các mức độ suy nghĩ x-i18n: - generated_at: "2026-04-30T16:30:52Z" + generated_at: "2026-05-04T02:26:31Z" model: gpt-5.5 provider: openai - source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7 + source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f source_path: tools/thinking.md workflow: 16 --- -## Tác dụng +## Chức năng -- Chỉ thị nội tuyến trong mọi nội dung nhận vào: `/t `, `/think:`, hoặc `/thinking `. +- Chỉ thị nội tuyến trong bất kỳ nội dung đến nào: `/t `, `/think:`, hoặc `/thinking `. - Mức (bí danh): `off | minimal | low | medium | high | xhigh | adaptive | max` - minimal → “think” - low → “think hard” - medium → “think harder” - high → “ultrathink” (ngân sách tối đa) - - xhigh → “ultrathink+” (mô hình GPT-5.2+ và Codex, cộng với effort Anthropic Claude Opus 4.7) - - adaptive → suy nghĩ thích ứng do nhà cung cấp quản lý (được hỗ trợ cho Claude 4.6 trên Anthropic/Bedrock, Anthropic Claude Opus 4.7, và suy nghĩ động Google Gemini) + - xhigh → “ultrathink+” (các mô hình GPT-5.2+ và Codex, cùng với effort Anthropic Claude Opus 4.7) + - adaptive → suy nghĩ thích ứng do nhà cung cấp quản lý (được hỗ trợ cho Claude 4.6 trên Anthropic/Bedrock, Anthropic Claude Opus 4.7, và suy nghĩ động của Google Gemini) - max → suy luận tối đa của nhà cung cấp (Anthropic Claude Opus 4.7; Ollama ánh xạ mức này tới effort `think` gốc cao nhất của nó) - `x-high`, `x_high`, `extra-high`, `extra high`, và `extra_high` ánh xạ tới `xhigh`. - `highest` ánh xạ tới `high`. - Ghi chú về nhà cung cấp: - - Menu và bộ chọn suy nghĩ được điều khiển bởi hồ sơ nhà cung cấp. Plugin nhà cung cấp khai báo chính xác tập mức cho mô hình đã chọn, bao gồm các nhãn như `on` nhị phân. - - `adaptive`, `xhigh`, và `max` chỉ được quảng bá cho các hồ sơ nhà cung cấp/mô hình hỗ trợ chúng. Các chỉ thị được nhập cho mức không được hỗ trợ sẽ bị từ chối kèm các tùy chọn hợp lệ của mô hình đó. + - Menu và bộ chọn suy nghĩ được điều khiển bởi hồ sơ nhà cung cấp. Provider plugins khai báo chính xác tập mức cho mô hình được chọn, bao gồm các nhãn như `on` nhị phân. + - `adaptive`, `xhigh`, và `max` chỉ được hiển thị cho các hồ sơ nhà cung cấp/mô hình hỗ trợ chúng. Chỉ thị được nhập cho các mức không được hỗ trợ sẽ bị từ chối kèm các tùy chọn hợp lệ của mô hình đó. - Các mức không được hỗ trợ đã lưu hiện có được ánh xạ lại theo thứ hạng hồ sơ nhà cung cấp. `adaptive` quay về `medium` trên các mô hình không thích ứng, trong khi `xhigh` và `max` quay về mức không phải `off` lớn nhất được hỗ trợ cho mô hình đã chọn. - - Các mô hình Anthropic Claude 4.6 mặc định là `adaptive` khi không đặt mức suy nghĩ rõ ràng. - - Anthropic Claude Opus 4.7 không mặc định dùng suy nghĩ thích ứng. Mặc định effort API của nó vẫn thuộc quyền nhà cung cấp trừ khi bạn đặt rõ ràng một mức suy nghĩ. - - Anthropic Claude Opus 4.7 ánh xạ `/think xhigh` tới suy nghĩ thích ứng cộng với `output_config.effort: "xhigh"`, vì `/think` là chỉ thị suy nghĩ và `xhigh` là thiết lập effort của Opus 4.7. - - Anthropic Claude Opus 4.7 cũng cung cấp `/think max`; nó ánh xạ tới cùng đường dẫn effort tối đa thuộc quyền nhà cung cấp. - - Các mô hình DeepSeek V4 cung cấp `/think xhigh|max`; cả hai ánh xạ tới DeepSeek `reasoning_effort: "max"` trong khi các mức không phải `off` thấp hơn ánh xạ tới `high`. + - Các mô hình Anthropic Claude 4.6 mặc định là `adaptive` khi chưa đặt mức suy nghĩ rõ ràng. + - Anthropic Claude Opus 4.7 không mặc định dùng suy nghĩ thích ứng. Mặc định effort API của nó vẫn thuộc quyền sở hữu của nhà cung cấp trừ khi bạn đặt rõ ràng một mức suy nghĩ. + - Anthropic Claude Opus 4.7 ánh xạ `/think xhigh` tới suy nghĩ thích ứng cùng với `output_config.effort: "xhigh"`, vì `/think` là chỉ thị suy nghĩ và `xhigh` là cài đặt effort của Opus 4.7. + - Anthropic Claude Opus 4.7 cũng cung cấp `/think max`; nó ánh xạ tới cùng đường dẫn effort tối đa thuộc quyền sở hữu của nhà cung cấp. + - Các mô hình DeepSeek V4 cung cấp `/think xhigh|max`; cả hai ánh xạ tới DeepSeek `reasoning_effort: "max"` trong khi các mức thấp hơn không phải `off` ánh xạ tới `high`. - Các mô hình Ollama có khả năng suy nghĩ cung cấp `/think low|medium|high|max`; `max` ánh xạ tới `think: "high"` gốc vì API gốc của Ollama chấp nhận các chuỗi effort `low`, `medium`, và `high`. - - Các mô hình OpenAI GPT ánh xạ `/think` thông qua hỗ trợ effort của Responses API theo từng mô hình. `/think off` chỉ gửi `reasoning.effort: "none"` khi mô hình đích hỗ trợ; nếu không, OpenClaw bỏ qua payload suy luận đã tắt thay vì gửi một giá trị không được hỗ trợ. - - Các mục catalog tương thích OpenAI tùy chỉnh có thể bật `/think xhigh` bằng cách đặt `models.providers..models[].compat.supportedReasoningEfforts` để bao gồm `"xhigh"`. Việc này dùng cùng metadata tương thích ánh xạ payload effort suy luận OpenAI gửi đi, nên menu, xác thực phiên, CLI tác tử, và `llm-task` khớp với hành vi truyền tải. - - Các tham chiếu OpenRouter Hunter Alpha đã cấu hình lỗi thời bỏ qua việc chèn suy luận proxy vì tuyến đã ngừng đó có thể trả về văn bản câu trả lời cuối cùng qua các trường suy luận. - - Google Gemini ánh xạ `/think adaptive` tới suy nghĩ động thuộc quyền nhà cung cấp của Gemini. Yêu cầu Gemini 3 bỏ qua `thinkingLevel` cố định, trong khi yêu cầu Gemini 2.5 gửi `thinkingBudget: -1`; các mức cố định vẫn ánh xạ tới `thinkingLevel` hoặc ngân sách Gemini gần nhất cho họ mô hình đó. - - MiniMax (`minimax/*`) trên đường dẫn streaming tương thích Anthropic mặc định là `thinking: { type: "disabled" }` trừ khi bạn đặt rõ ràng suy nghĩ trong tham số mô hình hoặc tham số yêu cầu. Việc này tránh rò rỉ delta `reasoning_content` từ định dạng stream Anthropic không gốc của MiniMax. - - Z.AI (`zai/*`) chỉ hỗ trợ suy nghĩ nhị phân (`on`/`off`). Bất kỳ mức nào không phải `off` đều được coi là `on` (ánh xạ tới `low`). - - Moonshot (`moonshot/*`) ánh xạ `/think off` tới `thinking: { type: "disabled" }` và mọi mức không phải `off` tới `thinking: { type: "enabled" }`. Khi bật suy nghĩ, Moonshot chỉ chấp nhận `tool_choice` `auto|none`; OpenClaw chuẩn hóa các giá trị không tương thích thành `auto`. + - Các mô hình OpenAI GPT ánh xạ `/think` qua hỗ trợ effort theo mô hình cụ thể của Responses API. `/think off` chỉ gửi `reasoning.effort: "none"` khi mô hình đích hỗ trợ; nếu không, OpenClaw bỏ qua payload suy luận đã tắt thay vì gửi một giá trị không được hỗ trợ. + - Các mục danh mục tùy chỉnh tương thích OpenAI có thể chọn tham gia `/think xhigh` bằng cách đặt `models.providers..models[].compat.supportedReasoningEfforts` để bao gồm `"xhigh"`. Cách này dùng cùng metadata tương thích ánh xạ các payload effort suy luận OpenAI gửi đi, nên menu, xác thực phiên, CLI tác tử, và `llm-task` khớp với hành vi truyền tải. + - Các ref OpenRouter Hunter Alpha đã cấu hình nhưng lỗi thời bỏ qua việc chèn suy luận qua proxy vì tuyến đã ngừng đó có thể trả về văn bản câu trả lời cuối cùng qua các trường suy luận. + - Google Gemini ánh xạ `/think adaptive` tới suy nghĩ động thuộc quyền sở hữu của nhà cung cấp của Gemini. Yêu cầu Gemini 3 bỏ qua `thinkingLevel` cố định, trong khi yêu cầu Gemini 2.5 gửi `thinkingBudget: -1`; các mức cố định vẫn ánh xạ tới `thinkingLevel` hoặc ngân sách Gemini gần nhất cho họ mô hình đó. + - MiniMax (`minimax/*`) trên đường dẫn streaming tương thích Anthropic mặc định là `thinking: { type: "disabled" }` trừ khi bạn đặt rõ ràng suy nghĩ trong tham số mô hình hoặc tham số yêu cầu. Điều này tránh rò rỉ delta `reasoning_content` từ định dạng stream Anthropic không gốc của MiniMax. + - Z.AI (`zai/*`) chỉ hỗ trợ suy nghĩ nhị phân (`on`/`off`). Bất kỳ mức nào không phải `off` đều được xem là `on` (ánh xạ tới `low`). + - Moonshot (`moonshot/*`) ánh xạ `/think off` tới `thinking: { type: "disabled" }` và bất kỳ mức nào không phải `off` tới `thinking: { type: "enabled" }`. Khi suy nghĩ được bật, Moonshot chỉ chấp nhận `tool_choice` `auto|none`; OpenClaw chuẩn hóa các giá trị không tương thích thành `auto`. ## Thứ tự phân giải 1. Chỉ thị nội tuyến trên tin nhắn (chỉ áp dụng cho tin nhắn đó). -2. Ghi đè phiên (được đặt bằng cách gửi tin nhắn chỉ có chỉ thị). +2. Ghi đè phiên (được đặt bằng cách gửi tin nhắn chỉ gồm chỉ thị). 3. Mặc định theo tác tử (`agents.list[].thinkingDefault` trong cấu hình). 4. Mặc định toàn cục (`agents.defaults.thinkingDefault` trong cấu hình). -5. Dự phòng: mặc định do nhà cung cấp khai báo khi có; nếu không, các mô hình có khả năng suy luận phân giải thành `medium` hoặc mức không phải `off` được hỗ trợ gần nhất cho mô hình đó, và các mô hình không suy luận giữ nguyên `off`. +5. Dự phòng: mặc định do nhà cung cấp khai báo khi có; nếu không, các mô hình có khả năng suy luận phân giải thành `medium` hoặc mức không phải `off` gần nhất được hỗ trợ cho mô hình đó, và các mô hình không suy luận giữ nguyên `off`. ## Đặt mặc định phiên -- Gửi một tin nhắn **chỉ** có chỉ thị (cho phép khoảng trắng), ví dụ `/think:medium` hoặc `/t high`. -- Thiết lập đó được giữ cho phiên hiện tại (mặc định theo người gửi); được xóa bằng `/think:off` hoặc đặt lại khi phiên nhàn rỗi. -- Phản hồi xác nhận được gửi (`Thinking level set to high.` / `Thinking disabled.`). Nếu mức không hợp lệ (ví dụ `/thinking big`), lệnh bị từ chối kèm gợi ý và trạng thái phiên giữ nguyên. +- Gửi một tin nhắn **chỉ** gồm chỉ thị (cho phép khoảng trắng), ví dụ `/think:medium` hoặc `/t high`. +- Thiết lập đó được giữ cho phiên hiện tại (mặc định theo người gửi); bị xóa bởi `/think:off` hoặc đặt lại khi phiên nhàn rỗi. +- Phản hồi xác nhận được gửi (`Thinking level set to high.` / `Thinking disabled.`). Nếu mức không hợp lệ (ví dụ `/thinking big`), lệnh bị từ chối kèm gợi ý và trạng thái phiên không đổi. - Gửi `/think` (hoặc `/think:`) không có đối số để xem mức suy nghĩ hiện tại. ## Áp dụng theo tác tử @@ -65,52 +65,55 @@ x-i18n: ## Chế độ nhanh (/fast) - Mức: `on|off`. -- Tin nhắn chỉ có chỉ thị bật/tắt ghi đè chế độ nhanh của phiên và trả lời `Fast mode enabled.` / `Fast mode disabled.`. +- Tin nhắn chỉ gồm chỉ thị bật/tắt ghi đè chế độ nhanh của phiên và trả lời `Fast mode enabled.` / `Fast mode disabled.`. - Gửi `/fast` (hoặc `/fast status`) không có chế độ để xem trạng thái chế độ nhanh hiệu lực hiện tại. - OpenClaw phân giải chế độ nhanh theo thứ tự này: - 1. Nội tuyến/chỉ thị thuần `/fast on|off` + 1. Nội tuyến/chỉ thị riêng `/fast on|off` 2. Ghi đè phiên 3. Mặc định theo tác tử (`agents.list[].fastModeDefault`) 4. Cấu hình theo mô hình: `agents.defaults.models["/"].params.fastMode` 5. Dự phòng: `off` - Với `openai/*`, chế độ nhanh ánh xạ tới xử lý ưu tiên của OpenAI bằng cách gửi `service_tier=priority` trên các yêu cầu Responses được hỗ trợ. -- Với `openai-codex/*`, chế độ nhanh gửi cùng cờ `service_tier=priority` trên Codex Responses. OpenClaw giữ một công tắc `/fast` dùng chung trên cả hai đường dẫn xác thực. -- Với các yêu cầu `anthropic/*` công khai trực tiếp, bao gồm lưu lượng xác thực OAuth gửi tới `api.anthropic.com`, chế độ nhanh ánh xạ tới các tầng dịch vụ Anthropic: `/fast on` đặt `service_tier=auto`, `/fast off` đặt `service_tier=standard_only`. -- Với `minimax/*` trên đường dẫn tương thích Anthropic, `/fast on` (hoặc `params.fastMode: true`) viết lại `MiniMax-M2.7` thành `MiniMax-M2.7-highspeed`. -- Tham số mô hình Anthropic `serviceTier` / `service_tier` rõ ràng ghi đè mặc định chế độ nhanh khi cả hai được đặt. OpenClaw vẫn bỏ qua việc chèn tầng dịch vụ Anthropic cho URL cơ sở proxy không phải Anthropic. +- Với `openai-codex/*`, chế độ nhanh gửi cùng cờ `service_tier=priority` trên Codex Responses. OpenClaw giữ một nút bật/tắt `/fast` dùng chung trên cả hai đường dẫn xác thực. +- Với các yêu cầu công khai trực tiếp `anthropic/*`, bao gồm lưu lượng xác thực OAuth gửi tới `api.anthropic.com`, chế độ nhanh ánh xạ tới các tầng dịch vụ Anthropic: `/fast on` đặt `service_tier=auto`, `/fast off` đặt `service_tier=standard_only`. +- Với `minimax/*` trên đường dẫn tương thích Anthropic, `/fast on` (hoặc `params.fastMode: true`) ghi lại `MiniMax-M2.7` thành `MiniMax-M2.7-highspeed`. +- Tham số mô hình Anthropic `serviceTier` / `service_tier` rõ ràng ghi đè mặc định chế độ nhanh khi cả hai được đặt. OpenClaw vẫn bỏ qua việc chèn tầng dịch vụ Anthropic cho các URL cơ sở proxy không phải Anthropic. - `/status` chỉ hiển thị `Fast` khi chế độ nhanh được bật. ## Chỉ thị chi tiết (/verbose hoặc /v) - Mức: `on` (tối thiểu) | `full` | `off` (mặc định). -- Tin nhắn chỉ có chỉ thị bật/tắt chi tiết phiên và trả lời `Verbose logging enabled.` / `Verbose logging disabled.`; mức không hợp lệ trả về gợi ý mà không thay đổi trạng thái. -- `/verbose off` lưu một ghi đè phiên rõ ràng; xóa nó qua UI Sessions bằng cách chọn `inherit`. +- Tin nhắn chỉ gồm chỉ thị bật/tắt chi tiết phiên và trả lời `Verbose logging enabled.` / `Verbose logging disabled.`; mức không hợp lệ trả về gợi ý mà không thay đổi trạng thái. +- `/verbose off` lưu một ghi đè phiên rõ ràng; xóa qua UI Sessions bằng cách chọn `inherit`. - Chỉ thị nội tuyến chỉ ảnh hưởng tới tin nhắn đó; nếu không, mặc định phiên/toàn cục sẽ áp dụng. - Gửi `/verbose` (hoặc `/verbose:`) không có đối số để xem mức chi tiết hiện tại. -- Khi bật chi tiết, các tác tử phát kết quả công cụ có cấu trúc (Pi, các tác tử JSON khác) gửi từng lệnh gọi công cụ trở lại dưới dạng tin nhắn riêng chỉ có metadata, có tiền tố ` : ` khi có (đường dẫn/lệnh). Các tóm tắt công cụ này được gửi ngay khi từng công cụ bắt đầu (bong bóng riêng), không phải dưới dạng delta streaming. -- Tóm tắt lỗi công cụ vẫn hiển thị trong chế độ bình thường, nhưng các hậu tố chi tiết lỗi thô bị ẩn trừ khi chi tiết là `on` hoặc `full`. -- Khi chi tiết là `full`, đầu ra công cụ cũng được chuyển tiếp sau khi hoàn tất (bong bóng riêng, được cắt ngắn tới độ dài an toàn). Nếu bạn bật/tắt `/verbose on|full|off` trong khi một lượt chạy đang diễn ra, các bong bóng công cụ tiếp theo tuân theo thiết lập mới. +- Khi bật chi tiết, các tác tử phát ra kết quả công cụ có cấu trúc (Pi, các tác tử JSON khác) gửi từng lệnh gọi công cụ trở lại dưới dạng tin nhắn chỉ metadata riêng, có tiền tố ` : ` khi có. Các tóm tắt công cụ này được gửi ngay khi mỗi công cụ bắt đầu (các bong bóng riêng), không phải dưới dạng delta streaming. +- Tóm tắt lỗi công cụ vẫn hiển thị ở chế độ bình thường, nhưng hậu tố chi tiết lỗi thô bị ẩn trừ khi chi tiết là `on` hoặc `full`. +- Khi chi tiết là `full`, đầu ra công cụ cũng được chuyển tiếp sau khi hoàn tất (bong bóng riêng, được cắt ngắn tới độ dài an toàn). Nếu bạn bật/tắt `/verbose on|full|off` khi một lượt chạy đang diễn ra, các bong bóng công cụ tiếp theo tuân theo cài đặt mới. +- `agents.defaults.toolProgressDetail` kiểm soát hình dạng tóm tắt công cụ `/verbose` và các dòng công cụ bản nháp tiến trình. Dùng `"explain"` (mặc định) cho các nhãn ngắn gọn dễ đọc như `🛠️ Exec: checking JS syntax`; dùng `"raw"` khi bạn cũng muốn thêm lệnh/chi tiết thô để gỡ lỗi. `agents.list[].toolProgressDetail` theo tác tử ghi đè mặc định. + - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js` + - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` -## Chỉ thị trace Plugin (/trace) +## Chỉ thị truy vết Plugin (/trace) - Mức: `on` | `off` (mặc định). -- Tin nhắn chỉ có chỉ thị bật/tắt đầu ra trace Plugin của phiên và trả lời `Plugin trace enabled.` / `Plugin trace disabled.`. +- Tin nhắn chỉ gồm chỉ thị bật/tắt đầu ra truy vết Plugin của phiên và trả lời `Plugin trace enabled.` / `Plugin trace disabled.`. - Chỉ thị nội tuyến chỉ ảnh hưởng tới tin nhắn đó; nếu không, mặc định phiên/toàn cục sẽ áp dụng. -- Gửi `/trace` (hoặc `/trace:`) không có đối số để xem mức trace hiện tại. -- `/trace` hẹp hơn `/verbose`: nó chỉ phơi bày các dòng trace/gỡ lỗi thuộc sở hữu Plugin, chẳng hạn tóm tắt gỡ lỗi Active Memory. -- Các dòng trace có thể xuất hiện trong `/status` và dưới dạng tin nhắn chẩn đoán theo sau sau phản hồi trợ lý bình thường. +- Gửi `/trace` (hoặc `/trace:`) không có đối số để xem mức truy vết hiện tại. +- `/trace` hẹp hơn `/verbose`: nó chỉ hiển thị các dòng truy vết/gỡ lỗi thuộc sở hữu Plugin, chẳng hạn như tóm tắt gỡ lỗi Active Memory. +- Dòng truy vết có thể xuất hiện trong `/status` và dưới dạng tin nhắn chẩn đoán tiếp theo sau phản hồi trợ lý bình thường. -## Khả năng hiển thị suy luận (/reasoning) +## Hiển thị suy luận (/reasoning) - Mức: `on|off|stream`. -- Tin nhắn chỉ có chỉ thị bật/tắt việc hiển thị các khối suy nghĩ trong phản hồi. +- Tin nhắn chỉ gồm chỉ thị bật/tắt việc hiển thị các khối suy nghĩ trong phản hồi. - Khi được bật, suy luận được gửi dưới dạng **tin nhắn riêng** có tiền tố `Reasoning:`. -- `stream` (chỉ Telegram): streaming suy luận vào bong bóng nháp Telegram trong khi phản hồi đang được tạo, rồi gửi câu trả lời cuối cùng không có suy luận. +- `stream` (chỉ Telegram): stream suy luận vào bong bóng bản nháp Telegram trong khi phản hồi đang được tạo, sau đó gửi câu trả lời cuối cùng không kèm suy luận. - Bí danh: `/reason`. - Gửi `/reasoning` (hoặc `/reasoning:`) không có đối số để xem mức suy luận hiện tại. - Thứ tự phân giải: chỉ thị nội tuyến, rồi ghi đè phiên, rồi mặc định theo tác tử (`agents.list[].reasoningDefault`), rồi dự phòng (`off`). -Các thẻ suy luận mô hình cục bộ sai định dạng được xử lý thận trọng. Các khối `...` đã đóng vẫn bị ẩn trên phản hồi bình thường, và suy luận chưa đóng sau văn bản đã hiển thị cũng bị ẩn. Nếu một phản hồi được bọc hoàn toàn trong một thẻ mở chưa đóng duy nhất và nếu không sẽ được gửi dưới dạng văn bản rỗng, OpenClaw xóa thẻ mở sai định dạng và gửi phần văn bản còn lại. +Các thẻ suy luận mô hình cục bộ sai định dạng được xử lý thận trọng. Các khối `...` đã đóng vẫn bị ẩn trong phản hồi bình thường, và suy luận chưa đóng sau văn bản đã hiển thị cũng bị ẩn. Nếu phản hồi được bao bọc hoàn toàn trong một thẻ mở chưa đóng duy nhất và nếu không sẽ được gửi dưới dạng văn bản rỗng, OpenClaw loại bỏ thẻ mở sai định dạng và gửi phần văn bản còn lại. ## Liên quan @@ -118,23 +121,23 @@ Các thẻ suy luận mô hình cục bộ sai định dạng được xử lý ## Heartbeat -- Nội dung probe Heartbeat là prompt heartbeat đã cấu hình (mặc định: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Chỉ thị nội tuyến trong tin nhắn heartbeat áp dụng như bình thường (nhưng tránh thay đổi mặc định phiên từ heartbeat). -- Phân phối Heartbeat mặc định chỉ gửi payload cuối cùng. Để cũng gửi tin nhắn `Reasoning:` riêng (khi có), đặt `agents.defaults.heartbeat.includeReasoning: true` hoặc theo tác tử `agents.list[].heartbeat.includeReasoning: true`. +- Nội dung probe Heartbeat là prompt Heartbeat đã cấu hình (mặc định: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Chỉ thị nội tuyến trong tin nhắn Heartbeat áp dụng như bình thường (nhưng tránh thay đổi mặc định phiên từ Heartbeat). +- Gửi Heartbeat mặc định chỉ gửi payload cuối cùng. Để cũng gửi tin nhắn `Reasoning:` riêng (khi có), đặt `agents.defaults.heartbeat.includeReasoning: true` hoặc `agents.list[].heartbeat.includeReasoning: true` theo tác tử. -## UI chat web +## UI trò chuyện web -- Bộ chọn suy nghĩ của chat web phản chiếu mức đã lưu của phiên từ kho phiên nhận vào/cấu hình khi trang tải. -- Chọn mức khác ghi ghi đè phiên ngay lập tức qua `sessions.patch`; nó không chờ lần gửi tiếp theo và không phải ghi đè dùng một lần `thinkingOnce`. -- Tùy chọn đầu tiên luôn là `Default ()`, trong đó mặc định đã phân giải đến từ hồ sơ suy nghĩ của nhà cung cấp mô hình phiên đang hoạt động cộng với cùng logic dự phòng mà `/status` và `session_status` dùng. -- Bộ chọn dùng `thinkingLevels` được trả về bởi hàng/mặc định phiên Gateway, với `thinkingOptions` được giữ làm danh sách nhãn kế thừa. UI trình duyệt không giữ danh sách regex nhà cung cấp riêng; Plugin sở hữu các tập mức theo từng mô hình. -- `/think:` vẫn hoạt động và cập nhật cùng mức phiên đã lưu, nên chỉ thị chat và bộ chọn luôn đồng bộ. +- Bộ chọn suy nghĩ của trò chuyện web phản ánh mức đã lưu của phiên từ kho phiên đến/cấu hình khi trang tải. +- Việc chọn mức khác ghi ghi đè phiên ngay lập tức qua `sessions.patch`; nó không chờ lần gửi tiếp theo và không phải ghi đè một lần `thinkingOnce`. +- Tùy chọn đầu tiên luôn là `Default ()`, trong đó mặc định đã phân giải đến từ hồ sơ suy nghĩ của nhà cung cấp cho mô hình phiên đang hoạt động cộng với cùng logic dự phòng mà `/status` và `session_status` sử dụng. +- Bộ chọn dùng `thinkingLevels` được trả về bởi hàng phiên Gateway/mặc định, với `thinkingOptions` được giữ làm danh sách nhãn kế thừa. UI trình duyệt không giữ danh sách regex nhà cung cấp riêng; plugins sở hữu các tập mức theo mô hình cụ thể. +- `/think:` vẫn hoạt động và cập nhật cùng mức phiên đã lưu, nên các chỉ thị trò chuyện và bộ chọn luôn đồng bộ. ## Hồ sơ nhà cung cấp -- Các Plugin nhà cung cấp có thể cung cấp `resolveThinkingProfile(ctx)` để xác định các mức được hỗ trợ và giá trị mặc định của mô hình. -- Các Plugin nhà cung cấp làm proxy cho mô hình Claude nên tái sử dụng `resolveClaudeThinkingProfile(modelId)` từ `openclaw/plugin-sdk/provider-model-shared` để danh mục Anthropic trực tiếp và danh mục proxy luôn đồng bộ. -- Mỗi mức hồ sơ có một `id` chuẩn được lưu trữ (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, hoặc `max`) và có thể bao gồm `label` hiển thị. Nhà cung cấp nhị phân dùng `{ id: "low", label: "on" }`. -- Các Plugin công cụ cần xác thực một ghi đè suy luận rõ ràng nên dùng `api.runtime.agent.resolveThinkingPolicy({ provider, model })` cùng với `api.runtime.agent.normalizeThinkingLevel(...)`; chúng không nên duy trì danh sách mức nhà cung cấp/mô hình riêng. -- Các Plugin công cụ có quyền truy cập vào siêu dữ liệu mô hình tùy chỉnh đã cấu hình có thể truyền `catalog` vào `resolveThinkingPolicy` để các lựa chọn tham gia `compat.supportedReasoningEfforts` được phản ánh trong xác thực phía Plugin. -- Các hook kế thừa đã phát hành (`supportsXHighThinking`, `isBinaryThinking`, và `resolveDefaultThinkingLevel`) vẫn là các adapter tương thích, nhưng các tập mức tùy chỉnh mới nên dùng `resolveThinkingProfile`. -- Các hàng/giá trị mặc định của Gateway cung cấp `thinkingLevels`, `thinkingOptions`, và `thinkingDefault` để các client ACP/chat hiển thị cùng các id và nhãn hồ sơ mà xác thực thời gian chạy sử dụng. +- Provider plugins có thể expose `resolveThinkingProfile(ctx)` để định nghĩa các mức được hỗ trợ và mặc định của model. +- Provider plugins proxy các model Claude nên tái sử dụng `resolveClaudeThinkingProfile(modelId)` từ `openclaw/plugin-sdk/provider-model-shared` để các catalog Anthropic trực tiếp và proxy luôn đồng bộ. +- Mỗi mức profile có một `id` chuẩn được lưu trữ (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, hoặc `max`) và có thể bao gồm một `label` hiển thị. Các provider nhị phân dùng `{ id: "low", label: "on" }`. +- Tool plugins cần xác thực một ghi đè thinking rõ ràng nên dùng `api.runtime.agent.resolveThinkingPolicy({ provider, model })` cùng với `api.runtime.agent.normalizeThinkingLevel(...)`; chúng không nên giữ danh sách mức provider/model riêng. +- Tool plugins có quyền truy cập vào metadata model tùy chỉnh đã cấu hình có thể truyền `catalog` vào `resolveThinkingPolicy` để các opt-in `compat.supportedReasoningEfforts` được phản ánh trong xác thực phía plugin. +- Các hook legacy đã phát hành (`supportsXHighThinking`, `isBinaryThinking`, và `resolveDefaultThinkingLevel`) vẫn là các adapter tương thích, nhưng các tập mức tùy chỉnh mới nên dùng `resolveThinkingProfile`. +- Các hàng/mặc định của Gateway expose `thinkingLevels`, `thinkingOptions`, và `thinkingDefault` để các client ACP/chat render cùng các id và nhãn profile mà xác thực runtime sử dụng. diff --git a/docs/vi/tools/web-fetch.md b/docs/vi/tools/web-fetch.md index cd2e11cf6..959b6ba85 100644 --- a/docs/vi/tools/web-fetch.md +++ b/docs/vi/tools/web-fetch.md @@ -4,27 +4,27 @@ read_when: - Bạn cần cấu hình web_fetch hoặc phương án dự phòng Firecrawl của nó - Bạn muốn hiểu các giới hạn và cơ chế lưu vào bộ nhớ đệm của web_fetch sidebarTitle: Web Fetch -summary: công cụ web_fetch -- tìm nạp HTTP với trích xuất nội dung dễ đọc +summary: công cụ web_fetch -- tìm nạp HTTP với khả năng trích xuất nội dung dễ đọc title: Tìm nạp web x-i18n: - generated_at: "2026-05-02T10:56:40Z" + generated_at: "2026-05-04T02:26:37Z" model: gpt-5.5 provider: openai - source_hash: f455da77c20049f0ed0246fa53e9f49d3cf2004e65bd64a0bf871861c6e93229 + source_hash: c8c3efbf4a640b2fd69cc9532dcb06a873a6830a2e8a85ab7510ab38207c8670 source_path: tools/web-fetch.md workflow: 16 --- -Công cụ `web_fetch` thực hiện HTTP GET thuần túy và trích xuất nội dung dễ đọc -(HTML sang markdown hoặc văn bản). Công cụ này **không** thực thi JavaScript. +Công cụ `web_fetch` thực hiện HTTP GET thuần túy và trích xuất nội dung có thể đọc được +(HTML thành markdown hoặc văn bản). Công cụ này **không** thực thi JavaScript. -Đối với các trang phụ thuộc nhiều vào JS hoặc các trang được bảo vệ bằng đăng nhập, hãy dùng +Đối với các trang dùng nhiều JS hoặc các trang được bảo vệ bằng đăng nhập, hãy dùng [Trình duyệt Web](/vi/tools/browser) thay thế. ## Bắt đầu nhanh `web_fetch` được **bật theo mặc định** -- không cần cấu hình. Agent có thể -gọi công cụ này ngay: +gọi công cụ này ngay lập tức: ```javascript await web_fetch({ url: "https://example.com/article" }); @@ -33,7 +33,7 @@ await web_fetch({ url: "https://example.com/article" }); ## Tham số công cụ -URL cần fetch. Chỉ hỗ trợ `http(s)`. +URL cần tải. Chỉ `http(s)`. @@ -56,11 +56,11 @@ Cắt ngắn đầu ra xuống số ký tự này. Nếu Readability thất bại và Firecrawl đã được cấu hình, thử lại thông qua - API Firecrawl với chế độ vượt qua bot. + API Firecrawl với chế độ né tránh bot. - Kết quả được lưu vào bộ nhớ đệm trong 15 phút (có thể cấu hình) để giảm các - lần fetch lặp lại cùng một URL. + Kết quả được lưu vào bộ nhớ đệm trong 15 phút (có thể cấu hình) để giảm số lần + tải lặp lại cùng một URL. @@ -79,6 +79,7 @@ Cắt ngắn đầu ra xuống số ký tự này. timeoutSeconds: 30, cacheTtlMinutes: 15, maxRedirects: 3, + useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS readability: true, // use Readability extraction userAgent: "Mozilla/5.0 ...", // override User-Agent ssrfPolicy: { @@ -93,8 +94,8 @@ Cắt ngắn đầu ra xuống số ký tự này. ## Dự phòng Firecrawl -Nếu trích xuất Readability thất bại, `web_fetch` có thể chuyển dự phòng sang -[Firecrawl](/vi/tools/firecrawl) để vượt qua bot và trích xuất tốt hơn: +Nếu trích xuất Readability thất bại, `web_fetch` có thể chuyển sang dự phòng bằng +[Firecrawl](/vi/tools/firecrawl) để né tránh bot và trích xuất tốt hơn: ```json5 { @@ -125,42 +126,61 @@ Nếu trích xuất Readability thất bại, `web_fetch` có thể chuyển d ``` `plugins.entries.firecrawl.config.webFetch.apiKey` hỗ trợ các đối tượng SecretRef. -Cấu hình `tools.web.fetch.firecrawl.*` cũ được `openclaw doctor --fix` tự động di chuyển. +Cấu hình cũ `tools.web.fetch.firecrawl.*` được `openclaw doctor --fix` tự động di chuyển. - Nếu Firecrawl được bật và SecretRef của nó chưa được phân giải mà không có - dự phòng env `FIRECRAWL_API_KEY`, quá trình khởi động gateway sẽ thất bại nhanh. + Nếu Firecrawl được bật và SecretRef của nó không được phân giải, đồng thời không có dự phòng env + `FIRECRAWL_API_KEY`, Gateway sẽ khởi động thất bại nhanh. Các ghi đè `baseUrl` của Firecrawl bị khóa chặt: lưu lượng được lưu trữ dùng - `https://api.firecrawl.dev`; các ghi đè tự lưu trữ phải trỏ đến endpoint riêng tư hoặc - nội bộ, và `http://` chỉ được chấp nhận cho các đích riêng tư đó. + `https://api.firecrawl.dev`; ghi đè tự lưu trữ phải nhắm tới endpoint riêng tư hoặc + nội bộ, và `http://` chỉ được chấp nhận cho các mục tiêu riêng tư đó. Hành vi runtime hiện tại: -- `tools.web.fetch.provider` chọn rõ ràng nhà cung cấp dự phòng fetch. -- Nếu bỏ qua `provider`, OpenClaw tự động phát hiện nhà cung cấp web-fetch sẵn sàng - đầu tiên từ thông tin xác thực có sẵn. `web_fetch` không sandbox có thể dùng - các Plugin đã cài đặt khai báo `contracts.webFetchProviders` và đăng ký một - nhà cung cấp khớp tại runtime. Hiện nay nhà cung cấp đi kèm là Firecrawl. -- Các lệnh gọi `web_fetch` trong sandbox vẫn chỉ giới hạn ở các nhà cung cấp đi kèm. -- Nếu Readability bị tắt, `web_fetch` bỏ qua thẳng đến dự phòng nhà cung cấp đã chọn. - Nếu không có nhà cung cấp nào khả dụng, công cụ sẽ thất bại ở trạng thái đóng. +- `tools.web.fetch.provider` chọn rõ ràng nhà cung cấp dự phòng cho việc tải. +- Nếu bỏ qua `provider`, OpenClaw tự động phát hiện nhà cung cấp web-fetch sẵn sàng đầu tiên + từ các thông tin xác thực có sẵn. `web_fetch` không sandbox có thể dùng + Plugin đã cài đặt khai báo `contracts.webFetchProviders` và đăng ký một + nhà cung cấp khớp tại runtime. Hiện tại nhà cung cấp được đóng gói là Firecrawl. +- Các lệnh gọi `web_fetch` được sandbox vẫn bị giới hạn ở những nhà cung cấp được đóng gói. +- Nếu Readability bị tắt, `web_fetch` bỏ qua trực tiếp tới dự phòng + nhà cung cấp đã chọn. Nếu không có nhà cung cấp nào khả dụng, công cụ sẽ thất bại theo hướng đóng. + +## Proxy Env Tin cậy + +Nếu bản triển khai của bạn yêu cầu `web_fetch` đi qua một proxy đi ra +HTTP(S) đáng tin cậy, hãy đặt `tools.web.fetch.useTrustedEnvProxy: true`. + +Ở chế độ này, OpenClaw vẫn áp dụng kiểm tra SSRF dựa trên tên máy chủ trước khi gửi +yêu cầu, nhưng để proxy phân giải DNS thay vì thực hiện ghim DNS cục bộ. +Chỉ bật tùy chọn này khi proxy do người vận hành kiểm soát và thực thi +chính sách đi ra sau khi phân giải DNS. + + + Nếu không có biến env proxy HTTP(S) nào được cấu hình, hoặc máy chủ đích bị loại trừ bởi + `NO_PROXY`, `web_fetch` sẽ quay về đường dẫn nghiêm ngặt thông thường với ghim DNS + cục bộ. + ## Giới hạn và an toàn -- `maxChars` được giới hạn theo `tools.web.fetch.maxCharsCap` -- Phần thân phản hồi bị giới hạn ở `maxResponseBytes` trước khi phân tích; các +- `maxChars` bị giới hạn ở `tools.web.fetch.maxCharsCap` +- Phần thân phản hồi bị giới hạn ở `maxResponseBytes` trước khi phân tích cú pháp; các phản hồi quá lớn sẽ bị cắt ngắn kèm cảnh báo - Tên máy chủ riêng tư/nội bộ bị chặn - `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` và - `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` là các lựa chọn tham gia hẹp - dành cho các stack proxy fake-IP đáng tin cậy; hãy để chúng chưa đặt trừ khi proxy của bạn sở hữu - các dải tổng hợp đó và thực thi chính sách đích riêng -- Các chuyển hướng được kiểm tra và giới hạn bởi `maxRedirects` -- `web_fetch` hoạt động theo nỗ lực tốt nhất -- một số trang cần [Trình duyệt Web](/vi/tools/browser) + `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` là các tùy chọn bật hẹp + cho các ngăn xếp proxy IP giả đáng tin cậy; để chúng chưa đặt trừ khi proxy của bạn sở hữu + các dải tổng hợp đó và thực thi chính sách đích riêng của nó +- Chuyển hướng được kiểm tra và giới hạn bởi `maxRedirects` +- `useTrustedEnvProxy` là một tùy chọn bật rõ ràng và chỉ nên được bật cho + các proxy do người vận hành kiểm soát vẫn thực thi chính sách đi ra sau khi + phân giải DNS +- `web_fetch` hoạt động theo nỗ lực tối đa -- một số trang cần [Trình duyệt Web](/vi/tools/browser) ## Hồ sơ công cụ @@ -177,6 +197,6 @@ Nếu bạn dùng hồ sơ công cụ hoặc danh sách cho phép, hãy thêm `w ## Liên quan -- [Tìm kiếm Web](/vi/tools/web) -- tìm kiếm web với nhiều nhà cung cấp -- [Trình duyệt Web](/vi/tools/browser) -- tự động hóa trình duyệt đầy đủ cho các trang phụ thuộc nhiều vào JS -- [Firecrawl](/vi/tools/firecrawl) -- công cụ tìm kiếm và scrape Firecrawl +- [Tìm kiếm Web](/vi/tools/web) -- tìm kiếm trên web với nhiều nhà cung cấp +- [Trình duyệt Web](/vi/tools/browser) -- tự động hóa trình duyệt đầy đủ cho các trang dùng nhiều JS +- [Firecrawl](/vi/tools/firecrawl) -- công cụ tìm kiếm và thu thập Firecrawl diff --git a/docs/vi/web/control-ui.md b/docs/vi/web/control-ui.md index 43519c429..a1a8b279c 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 điều khiển dựa trên trình duyệt cho Gateway (trò chuyện, các Node, cấu hình) +summary: Giao diện điều khiển trên trình duyệt cho Gateway (trò chuyện, nút, cấu hình) title: Giao diện điều khiển x-i18n: - generated_at: "2026-05-03T10:43:27Z" + generated_at: "2026-05-04T02:26:42Z" model: gpt-5.5 provider: openai - source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c + source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e source_path: web/control-ui.md workflow: 16 --- -Giao diện điều khiển là một ứng dụng một trang nhỏ bằng **Vite + Lit** được phục vụ bởi Gateway: +Control UI là một ứng dụng một 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`) -Nó giao tiếp **trực tiếp với Gateway WebSocket** trên cùng một cổng. +Ứng dụng giao tiếp **trực tiếp với Gateway WebSocket** trên cùng cổng. ## Mở nhanh (cục bộ) @@ -33,206 +33,207 @@ 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` -- tiêu đề định danh Tailscale Serve khi `gateway.auth.allowTailscale: true` -- tiêu đề định danh proxy tin cậy khi `gateway.auth.mode: "trusted-proxy"` +- các tiêu đề định danh Tailscale Serve khi `gateway.auth.allowTailscale: true` +- các tiêu đề định danh proxy tin cậy khi `gateway.auth.mode: "trusted-proxy"` -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. Quy trình thiết lập ban đầu thường tạo token gateway cho xác thực 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"`. +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 lâu dài. Onboarding thường tạo một token Gateway cho xác thực 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 nối thiết bị (kết nối đầu tiên) -Khi bạn kết nối với Giao diện điều khiển từ trình duyệt hoặc thiết bị mới, Gateway thường yêu cầu **phê duyệt ghép nố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 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 nố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:** "đã ngắt kết nối (1008): yêu cầu ghép nối" +**Bạn sẽ thấy:** "disconnected (1008): pairing required" - + ```bash openclaw devices list ``` - + ```bash openclaw devices approve ``` -Nếu trình duyệt thử lại ghép nố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 nố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 sẽ đượ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 nố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ũ còn hiệu lực, chặ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 tập phạm vi mới. +Nếu trình duyệt đã được ghép nố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 một lần 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 quyền rộng hơn, và yêu cầu bạn phê duyệt rõ ràng tập phạm vi mới. -Sau khi được phê duyệt, thiết bị sẽ được ghi nhớ và sẽ không yêu cầu phê duyệt lại trừ khi bạn thu hồi thiết bị 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à 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 về 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 lượt ghép nối cho các phiên vận hành Giao diện điều khiển khi `gateway.auth.allowTailscale: true`, định danh Tailscale xác minh thành công và trình duyệt trình bày định danh thiết bị của nó. -- Các bind Tailnet trực tiếp, kết nối trình duyệt LAN và hồ sơ trình duyệt không có định danh 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 nối lại. +- Tailscale Serve có thể bỏ qua vòng ghép nối cho các phiên vận hành Control UI khi `gateway.auth.allowTailscale: true`, định danh Tailscale được xác minh, và trình duyệt trình bày định danh thiết bị của nó. +- Các bind Tailnet trực tiếp, kết nối trình duyệt LAN, và hồ sơ trình duyệt không có định danh thiết bị vẫn cần 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 đổi trình duyệt hoặc xóa dữ liệu trình duyệt sẽ yêu cầu ghép nối lại. -## Danh tính cá nhân (cục bộ trong trình duyệt) +## Định danh cá nhân (cục bộ trong trình duyệt) -Giao diện điều khiển hỗ trợ danh tính cá nhân theo từng trình duyệt (tên hiển thị và ảnh đại diện) được gắn vào tin nhắn gửi đi để quy trách nhiệm trong các phiên dùng chung. Danh tính này nằm trong bộ nhớ trình duyệt, bị 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 hay lưu phía máy chủ ngoài siêu dữ liệu tác giả bản ghi 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ề trống. +Control UI hỗ trợ định danh cá nhân theo từng trình duyệt (tên hiển thị và ảnh đại diện) được gắn vào tin nhắn gửi đi để quy trách nhiệm trong các phiên dùng chung. Định danh 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 hoặc lưu lâu dài phía máy chủ ngoài siêu dữ liệu 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 thành trống. -Mẫu cục bộ trong trình duyệt tương tự áp dụng cho ghi đè ảnh đại diện trợ lý. Ảnh đại diện 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 có sẵn 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 bảng điều khiển tùy chỉnh). +Mẫu cục bộ trong trình duyệt tương tự áp dụng cho ghi đè ảnh đại diện trợ lý. Ảnh đại diện trợ lý đã tải lên chỉ phủ lên định danh 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 máy khách không phải UI ghi trực tiếp vào trường này (chẳng hạn các Gateway được script hóa hoặc dashboard tùy chỉnh). -## Điểm cuối cấu hình thời gian chạy +## Endpoint cấu hình runtime -Giao diện điều khiển lấy cài đặt thời gian chạy từ `/__openclaw/control-ui-config.json`. Điểm cuối đó đượ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 nó, và một lần lấy thành công yêu cầu token/mật khẩu gateway đã hợp lệ, định danh Tailscale Serve hoặc định danh proxy 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 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 nó, và một lần lấy thành công cần có token/mật khẩu Gateway đã hợp lệ, định danh Tailscale Serve, hoặc định danh proxy tin cậy. ## Hỗ trợ ngôn ngữ -Giao diện điều khiển 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 dưới Giao diện. +Control UI có thể bản địa hóa chính nó 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 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` -- 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ẽ dự phòng 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` +- Các 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 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 tập 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 tập 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 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. ## Chủ đề giao diện -Bảng Giao diện giữ các chủ đề tích hợp Claw, Knot và Dash, cộng với một vị trí nhập tweakcn cục bộ trong trình duyệt. Để nhập một chủ đề, mở [chủ đề tweakcn](https://tweakcn.com/themes), 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`. +Bảng Giao diện giữ các chủ đề Claw, Knot, và Dash tích hợp, cộng với một khe nhập tweakcn cục bộ trong trình duyệt. Để nhập một chủ đề, mở [chủ đề tweakcn](https://tweakcn.com/themes), 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 editor 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`. -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ủ đề đó 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. -## Nó có thể làm gì (hiện nay) +## Có thể làm gì (hiện nay) - + - Trò chuyện với mô hình qua Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Nói chuyện qua các phiên thời gian thực trong 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 bị ràng buộc qua WebSocket, và các plugin giọng nói thời gian thực chỉ phía backend dùng truyền tải chuyển tiếp Gateway. Truyền tải chuyển tiếp giữ thông tin xác thực của nhà cung cấp trên Gateway trong khi trình duyệt phát PCM từ micro qua RPC `talk.realtime.relay*` và gửi 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. - - Phát trực tuyến 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 tử). + - Nói chuyện 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 một lần bị ràng buộc qua WebSocket, và các Plugin thoại thời gian thực chỉ ở backend dùng transport chuyển tiếp của Gateway. 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 stream PCM microphone qua các RPC `talk.realtime.relay*` và gửi lệnh gọi công cụ `openclaw_agent_consult` trở lại qua `chat.send` cho mô hình OpenClaw lớn hơn đã cấu hình. + - Stream lệnh gọi công cụ + thẻ đầu ra công cụ trực tiếp trong Chat (sự kiện agent). - - - Kênh: trạng thái kênh tích hợp cộng vớ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`). + + - Kênh: trạng thái kênh tích hợp cộng với kênh Plugin đi kèm/bên ngoài, đăng nhập QR, và cấu hình theo từng 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 đè mô hình/suy nghĩ/nhanh/chi tiết/dấu vết/lập luận 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ý giấc mơ (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + - Phiên: danh sách + ghi đè mô hình/suy nghĩ/nhanh/dài dòng/trace/reasoning theo từng phiê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 Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - - Công việc Cron: liệt kê/thêm/chỉnh sửa/chạy/bật/tắt + lịch sử chạy (`cron.*`). + + - Tác vụ 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.*`). - - Nút: danh sách + khả năng (`node.list`). - - Phê duyệt exec: chỉnh sửa danh sách cho phép của gateway hoặc nút + chính sách hỏi cho `exec host=gateway/node` (`exec.approvals.*`). + - Node: danh sách + năng lực (`node.list`). + - Phê duyệt exec: sửa danh sách cho phép Gateway hoặc Node + chính sách hỏi cho `exec host=gateway/node` (`exec.approvals.*`). - - - Xem/chỉnh sửa `~/.openclaw/openclaw.json` (`config.get`, `config.set`). - - Áp dụng + khởi động lại có xác thực (`config.apply`) và đánh thức phiên hoạt động cuối cùng. - - Ghi bao gồm cơ chế bảo vệ băm cơ sở để ngăn ghi đè các chỉnh sửa đồng thời. - - 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; ref đang hoạt động đã gửi nhưng chưa phân giải sẽ bị từ chối trước khi ghi. - - Kết xuất schema + 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, siêu dữ liệu tài liệu trên các nút đối tượng lồng nhau/ký tự đại diện/mảng/thành phần, cộng với schema plugin + kênh khi có); trình chỉnh sửa Raw JSON chỉ khả dụng khi snapshot có thể khứ hồi thô an toàn. - - Nếu một snapshot không thể khứ hồi văn bản thô an toàn, Giao diện điều khiển buộc dùng chế độ Biểu mẫu và tắt chế độ Thô cho snapshot đó. - - "Đặt lại về đã lưu" trong trình chỉnh sửa Raw JSON giữ nguyên hình dạng do nội dung thô tạo ra (định dạng, nhận xét, bố cục `$include`) thay vì kết xuất lại 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ể khứ hồi 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 biểu mẫu để ngăn lỗi vô tình làm hỏng đối tượng thành chuỗi. + + - 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 gần nhất. + - Các lần ghi bao gồm bảo vệ base-hash để ngăn 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 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, siêu dữ liệu tài liệu trên các nút object/wildcard/array/composition lồng nhau, cộng với schema Plugin + kênh khi có); trình chỉnh sửa JSON thô chỉ khả dụng khi snapshot có vòng khứ hồi thô an toàn. + - Nếu một snapshot không thể thực hiện vòng khứ hồi văn bản thô an toàn, Control UI buộc chế độ Biểu mẫu và tắt chế độ Thô cho snapshot đó. + - Trình chỉnh sửa JSON thô "Đặt lại về đã lưu" giữ nguyên hình dạng do người dùng soạn thô (định dạng, nhận xét, 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 sống sót sau khi đặt lại khi snapshot có thể thực hiện vòng khứ hồi an toàn. + - Giá trị object SecretRef có cấu trúc được kết xuất chỉ đọc trong ô nhập văn bản 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/tình trạng/mô hình + nhật ký sự kiện + lệnh gọi RPC thủ công (`status`, `health`, `models.list`). - - Nhật ký: theo dõi trực tiếp phần cuối 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. + + - 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`) kèm 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. - - - Với công việc cô lập, mặc định phân phối là thông báo tóm tắt. Bạn có thể chuyển sang không có nếu muốn các lần chạy chỉ dùng nội bộ. - - Trường kênh/mục tiêu xuất hiện khi thông báo được chọn. - - Chế độ Webhook dùng `delivery.mode = "webhook"` với `delivery.to` được đặt thành URL webhook HTTP(S) hợp lệ. - - Với công việc phiên chính, có sẵn chế độ phân phối webhook và không có. - - Điều khiển chỉnh sửa nâng cao bao gồm xóa sau khi chạy, xóa ghi đè tác tử, tùy chọn cron chính xác/phân tán, ghi đè mô hình/suy nghĩ của tác tử và nút bật/tắt phân phối nỗ lực tối đa. - - 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ẽ vô hiệu hóa nút lưu cho đến khi được sửa. - - Đặt `cron.webhookToken` để gửi bearer token chuyên dụng; nếu bỏ qua, webhook sẽ được gửi không có tiêu đề xác thực. - - Dự phòng không dùng nữa: 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 tác vụ cô lập, cách 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ộ. + - 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` được đặt thành một URL Webhook HTTP(S) hợp lệ. + - Với tác vụ phiên chính, chế độ gửi Webhook và không gửi đều khả dụng. + - Điều khiển 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/so le, ghi đè mô hình/suy nghĩ của agent, và công tắc gửi nỗ lực tối đa. + - 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 một bearer token riêng; nếu bỏ qua, Webhook được gửi mà không có tiêu đề xác thực. + - Dự phòng không còn khuyến nghị: các tác vụ cũ đã lưu với `notify: true` vẫn có thể dùng `cron.webhook` cho đến khi được di chuyển. -## Hành vi trò chuyện +## Hành vi Chat - - `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`. - - 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 hình ả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 với `{ runId, status: "started" }` và phản hồi truyền luồng qua các sự kiện `chat`. + - Các lượt 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. - 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 để đảm bảo an toàn cho giao diện. Khi các mục bản ghi hội thoại 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 thế những tin nhắn quá khổ bằng một placeholder (`[chat.history omitted: message too large]`). - - Hình ảnh do trợ lý tạo ra đượ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 các 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 việc payload hình ả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ý nhìn thấy được (ví dụ `[[reply_to_*]]` và `[[audio_as_voice]]`), các 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 các token điều khiển mô hình ASCII/toàn chiều 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ần gửi đang hoạt động và khi làm mới lịch sử cuối cùng, khung trò chuyện vẫn giữ các tin nhắn người dùng/trợ lý cục bộ được hiển thị trước nếu `chat.history` tạm thời trả về snapshot cũ hơn; bản ghi hội thoại chuẩn thay thế các tin nhắn cục bộ đó khi lịch sử Gateway bắt kịp. - - `chat.inject` thêm một ghi chú của trợ lý vào bản ghi hội thoại của phiên và phát một sự kiện `chat` cho các cập nhật chỉ dành cho giao diện (không có lượt chạy tác tử, không gửi qua kênh). - - Bộ chọn mô hình và suy luận ở tiêu đề trò chuyện vá phiên đang hoạt động ngay lập tức thông 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. - - Nhập `/new` trong Giao diện điều khiển sẽ tạo và chuyển sang cùng một phiên bảng điều khiển mới như Trò chuyện mới. Nhập `/reset` giữ nguyên 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 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 các nhà cung cấp có xác thực dùng được. Danh mục đầy đủ vẫn có sẵn qua RPC gỡ lỗi `models.list` với `view: "all"`. - - Khi các 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 Compaction chạy đường dẫn Compaction phiên thông thường. Các snapshot token lỗi thời bị ẩn cho đến khi Gateway báo cáo lại mức sử dụng mới. + - 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 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 thế các tin nhắn quá lớn bằng một phần giữ chỗ (`[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 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 việc tải trọng hình ả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ỉ để hiển thị khỏi văn bản trợ lý nhìn thấy được (ví dụ `[[reply_to_*]]` và `[[audio_as_voice]]`), tải trọng 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 các token điều khiển mô hình ASCII/toàn chiều 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 khi đang gửi hoạt động và ở lần làm mới lịch sử cuối cùng, chế độ 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` tạm thời 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 công cụ cuối cùng, Giao diện điều khiển 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 sóng một sự kiện `chat` cho các cập nhật chỉ dành cho UI (không chạy tác nhân, không phân phối kênh). + - Các bộ chọn mô hình và tư duy trong 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ỉ cho một lượt. + - Gõ `/new` trong Giao diện điều khiển 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ữ 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 trò chuyện yêu cầu chế độ xem 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 các nhà cung cấp có xác thực dùng được. 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 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 lại. - - Chế độ Talk dùng một nhà cung cấp giọng nói thời gian thực đã đăng ký. Cấu hình OpenAI với `talk.provider: "openai"` cùng `talk.providers.openai.apiKey`, hoặc cấu hình Google với `talk.provider: "google"` cùng `talk.providers.google.apiKey`; cấu hình nhà cung cấp thời gian thực cho cuộc gọi thoại vẫn có thể được dùng lại làm dự phòng. Trình duyệt không bao giờ nhận khóa API tiêu chuẩn của nhà cung cấp. 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 dùng một lần và bị ràng buộc cho phiên WebSocket trên 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ỉ cung cấp cầu nối thời gian thực phía backend chạy qua lớp truyền relay của 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ế độ nói sử dụng một nhà cung cấp giọng nói thời gian thực đã đăng ký. Cấu hình OpenAI với `talk.provider: "openai"` cùng `talk.providers.openai.apiKey`, hoặc cấu hình Google với `talk.provider: "google"` cùng `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 bí mật máy khách Realtime tạm thời cho WebRTC. Google Live nhận một token xác thực Live API dùng một lần và bị ràng buộc cho phiên WebSocket trên trình duyệt, với hướng dẫn và khai báo công cụ được Gateway khóa vào token. Các nhà cung cấp chỉ phơi bày cầu nối thời gian thực phía backend sẽ chạy qua transport chuyển tiếp Gateway, để thông tin xác thực và socket của nhà cung cấp nằm ở phía máy chủ trong khi âm thanh trình duyệt di chuyển qua các RPC Gateway đã xác thực. Lời nhắc phiên Realtime được Gateway lắp ghép; `talk.realtime.session` không chấp nhận ghi đè hướng dẫn do bên gọi cung cấp. - Trong trình soạn Trò chuyện, điều khiển Talk là nút sóng nằm cạnh nút ghi âm chính tả bằng micrô. Khi Talk khởi động, hàng trạng thái của 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ờ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 thông qua `chat.send`. + Trong trình soạn Trò chuyện, điều khiển Nói là nút sóng nằm cạnh nút đọc chính tả qua microphone. Khi Nói bắt đầu, hàng trạng thái của 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 vấn mô hình lớn hơn đã cấu hình qua `chat.send`. - Smoke live 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ên trình duyệt của OpenAI, thiết lập WebSocket trình duyệt bằng token ràng buộc của Google Live, và bộ điều hợp trình duyệt relay Gateway với phương tiện micrô giả. Lệnh chỉ in trạng thái nhà cung cấp và không ghi secret vào log. + 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ên trình duyệt của OpenAI, thiết lập WebSocket trình duyệt bằng token ràng buộc của Google Live, và bộ chuyển đổi 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 nhật ký bí mật. - + - Nhấp **Dừng** (gọi `chat.abort`). - - Khi một lượt chạy đang hoạt động, các lượt tiếp theo thông thường sẽ được xếp hàng. Nhấp **Dẫn hướng** trên một tin nhắn đã xếp hàng để đưa lượt tiếp theo đó vào lượt đang chạy. - - Nhập `/stop` (hoặc các cụm hủy bỏ độc lập như `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) để hủy bỏ ngoài luồng. - - `chat.abort` hỗ trợ `{ sessionKey }` (không có `runId`) để hủy bỏ tất cả lượt chạy đang hoạt động cho phiên đó. + - Khi một lượt chạy đang hoạt động, các phản hồi tiếp theo thông thường sẽ được xếp hàng. Nhấp **Điều hướng** trên một tin nhắn đã xếp hàng để chèn phản hồi tiếp theo đó vào lượt đang chạy. + - Gõ `/stop` (hoặc các cụm 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 đó. - - - Khi một lượt chạy bị hủy bỏ, văn bản trợ lý một phần vẫn có thể được hiển thị trong giao diện. - - Gateway lưu bền vững văn bản trợ lý một phần đã bị hủy bỏ vào lịch sử bản ghi hội thoại khi có đầu ra đã được đệm. - - Các mục đã lưu bao gồm siêu dữ liệu hủy bỏ để bên tiêu thụ bản ghi hội thoại có thể phân biệt phần nội dung do hủy bỏ với đầu ra hoàn tất thông thường. + + - Khi một lượt chạy bị hủy, văn bản trợ lý một phần vẫn có thể được hiển thị trong UI. + - Gateway lưu bền văn bản trợ lý một phần đã 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 bao gồm siêu dữ liệu hủy để bên tiêu thụ bản ghi có thể phân biệt các phần hủy một phần 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 -Giao diện điều khiển cung cấp `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ở. +Giao diện điều khiển đ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` | Tệp kê khai PWA. Trình duyệt cung cấp tùy chọn "Cài đặt ứng dụng" khi có thể 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 được 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 vững. | +| Bề mặt | Chức năng | +| ----------------------------------------------------- | ------------------------------------------------------------------- | +| `ui/public/manifest.webmanifest` | Manifest PWA. Trình duyệt đề xuất "Cài đặt ứng dụng" khi 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 tự động tạo dùng để ký tải trọng 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 cố định khóa (cho triển khai nhiều máy chủ, xoay vòng secret, hoặc kiểm thử): +Ghi đè cặp khóa VAPID 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 máy chủ, xoay vòng bí mật, hoặc kiểm thử): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT` (mặc định là `mailto:openclaw@localhost`) -Giao diện điều khiển 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: +Giao diện điều khiển sử 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 `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ử tới đăng ký của bên gọi. +- `push.web.test` — gửi thông báo kiểm thử đến đăng ký của bên gọi. -Web Push độc lập với đường dẫn relay APNS của iOS (xem [Cấu hình](/vi/gateway/configuration) cho push dựa trên relay) và phương thức `push.test` hiện có, vốn nhắm tới ghép nối di động gốc. +Web Push độc lập với đường dẫn chuyển tiếp APNS của iOS (xem [Cấu hình](/vi/gateway/configuration) cho push dựa trên chuyển tiếp) và phương thức `push.test` hiện có, vốn nhắm tới ghép nối di động native. -## Nội dung nhúng được lưu trữ +## Nhúng được lưu trữ -Tin nhắn trợ lý có thể kết xuất nội dung web được lưu trữ nội tuyến bằng shortcode `[embed ...]`. Chính sách sandbox iframe được kiểm soát bởi `gateway.controlUi.embedSandbox`: +Tin nhắn trợ lý có thể kết xuất nội dung web được lưu trữ 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 nội dung nhúng được lưu trữ. - Cho phép nội dung nhúng 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/tiện ích trình duyệt tự chứa. + Cho phép nội dung nhúng 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` bê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. + Thêm `allow-same-origin` phía trên `allow-scripts` cho các tài liệu cùng site cố ý cần đặc quyền mạnh hơn. @@ -249,14 +250,14 @@ Ví dụ: ``` -Chỉ dùng `trusted` khi tài liệu được nhúng thực 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 tác tử tạo ra, `scripts` là lựa chọn an toàn hơn. +Chỉ dùng `trusted` khi tài liệu được nhúng thực 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 tác nhân tạo, `scripts` là lựa chọn an toàn hơn. -Các URL nhúng `http(s)` bên ngoài dạng tuyệt đối vẫn bị chặn theo mặc định. Nếu bạn chủ ý muốn `[embed url="https://..."]` tải các trang bên thứ ba, hãy đặt `gateway.controlUi.allowExternalEmbedUrls: true`. +Các 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`. -## Chiều rộng tin nhắn trò chuyện +## Độ rộng tin nhắn trò chuyện -Các tin nhắn trò chuyện được nhóm dùng chiều rộng tối đa mặc định dễ đọc. Các triển khai trên 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`: +Các tin nhắn trò chuyện được nhóm dùng độ rộng tối đa 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`: ```json5 { @@ -268,13 +269,13 @@ Các tin nhắn trò chuyện được nhóm dùng chiều rộng tối đa mặ } ``` -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 có 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ợ gồm độ dài và phần trăm đơn giản như `960px` hoặc `82%`, cùng các biểu thức độ 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: + Giữ Gateway trên loopback và để Tailscale Serve proxy nó qua HTTPS: ```bash openclaw gateway --tailscale serve @@ -282,27 +283,27 @@ Giá trị được xác thực trước khi tới trình duyệt. Các giá tr Mở: - - `https:///` (hoặc `gateway.controlUi.basePath` bạn đã cấu hình) + - `https:///` (hoặc `gateway.controlUi.basePath` đã cấu hình của bạn) - Theo mặc định, các yêu cầu Serve của Giao diện điều khiển/WebSocket 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 địa chỉ đó với header, đồng thời chỉ chấp nhận những 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 vận hành Giao diện điều khiển 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 nố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 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 bí mật chia sẻ 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 Serve của Giao diện điều khiển/WebSocket 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 người vận hành Giao diện điều khiển có danh tính thiết bị trình duyệt, đường dẫn Serve đã xác minh này cũng bỏ qua lượt ghép nố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 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"`. - 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 đơn 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ần không khớp đơn thuần chạy đua song song. - Xác thực Serve không dùng token giả định máy chủ Gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin cậy có thể chạy trên máy chủ đó, hãy yêu cầu xác thực bằng token/mật khẩu. + Xác thực Serve không token giả định máy chủ gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin cậy có thể chạy trên máy chủ đó, hãy yêu cầu xác thực token/mật khẩu. - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` Sau đó mở: - - `http://:18789/` (hoặc `gateway.controlUi.basePath` bạn đã cấu hình) + - `http://:18789/` (hoặc `gateway.controlUi.basePath` đã cấu hình của bạn) - Dán bí mật chia sẻ khớp vào cài đặt giao diện (được gửi dưới dạng `connect.params.auth.token` hoặc `connect.params.auth.password`). + Dán bí mật dùng chung tương ứng vào phần cài đặt UI (được gửi dưới dạng `connect.params.auth.token` hoặc `connect.params.auth.password`). @@ -311,19 +312,19 @@ Giá trị được xác thực trước khi tới trình duyệt. Các giá tr 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 Giao diện điều khiển không có danh tính thiết bị. -Các ngoại lệ được ghi nhận: +Các ngoại lệ đã ghi lại: - 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 Giao diện điều khiển của người vận hành thành công thông qua `gateway.auth.mode: "trusted-proxy"` -- ngoại lệ khẩn cấp `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- xác thực Giao diện điều khiển của người vận hành thành công qua `gateway.auth.mode: "trusted-proxy"` +- phương á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ở giao diện cục bộ: - `https:///` (Serve) -- `http://127.0.0.1:18789/` (trên máy chủ Gateway) +- `http://127.0.0.1:18789/` (trên máy chủ gateway) - + ```json5 { gateway: { @@ -334,14 +335,14 @@ Các ngoại lệ được ghi nhận: } ``` - `allowInsecureAuth` chỉ là nút bật/tắt tương thích cục bộ: + `allowInsecureAuth` chỉ là công tắc tương thích cục bộ: - - 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 ngữ cảnh HTTP không bảo mật. - - Nó không bỏ qua các kiểm tra ghép nối. + - Nó cho phép các phiên Giao diện điều khiể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 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: { @@ -353,14 +354,14 @@ Các ngoại lệ được ghi nhận: ``` - `dangerouslyDisableDeviceAuth` vô hiệu hóa 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 sử dụng khẩn cấp. + `dangerouslyDisableDeviceAuth` tắt các kiểm tra danh tính thiết bị của Giao diện điều khiển và là một mức hạ cấp bảo mật nghiêm trọng. Hoàn nguyên nhanh sau khi dùng trong tình huống khẩn cấp. - - - Xác thực proxy tin cậy thành công có thể cho phép các phiên Control UI của **người vận hành** mà 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. - - Proxy ngược local loopback cùng máy chủ vẫn không đáp ứng xác thực proxy tin cậy; 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 Giao diện điều khiển **operator** không có danh tính thiết bị. + - Điều này **không** áp dụng cho các phiên Giao diện điều khiển vai trò node. + - Các 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). @@ -369,28 +370,28 @@ 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 được phân phối với 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 sẽ bị trình duyệt từ chối và không tạo lượt fetch mạng. +Giao diện điều khiển đi kèm 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ộ. 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 phát sinh lượt tải qua mạng. Điều này có nghĩa là trong thực tế: -- 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 tuyến avatar đã xác thực mà UI fetch và chuyển đổi thành URL `blob:` cục bộ. +- Avatar và hình ảnh được phục vụ theo đườ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à giao diện tìm nạp 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). -- 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 sẽ 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, 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 fetch hình ảnh từ xa tùy ý. +- URL `blob:` cục bộ do Giao diện điều khiển 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 trình trợ giúp avatar của Giao diện điều khiển và được thay bằng logo/huy hiệu tích hợp sẵn, vì vậy 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 operator 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 -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 Giao diện điều khiển 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 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 đến một trong hai tuyến đều bị từ chối (khớp với tuyến assistant-media cùng cấp). Điều này ngăn tuyến avatar làm lộ 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 fetch 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ề 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 cùng cấp). Điều này ngăn tuyến 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 Giao diện điều khiển chuyển tiếp token gateway dưới dạng header bearer khi tìm nạp avatar, và dùng URL blob đã xác thực để hình ảnh vẫn hiển thị trong dashboard. -Nếu bạn vô hiệu hóa 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 chưa xác thực, phù hợp với phần còn lại của Gateway. +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 chưa xác thực, nhất quán với phần còn lại của gateway. -## Xây dựng UI +## Xây dựng giao diện Gateway phục vụ các tệp tĩnh từ `dist/control-ui`. Xây dựng chúng bằng: @@ -410,19 +411,19 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build pnpm ui:dev ``` -Sau đó trỏ UI tới URL WS của Gateway (ví dụ `ws://127.0.0.1:18789`). +Sau đó trỏ giao diện tới URL Gateway WS của bạn (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; đích 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. +Giao diện điều khiển là các tệp tĩnh; đích WebSocket có thể cấu hình và có thể khác với nguồn gốc HTTP. Điều này tiện khi bạn muốn dùng máy chủ dev Vite cục bộ nhưng Gateway chạy ở nơi khác. - + ```bash pnpm ui:dev ``` - + ```text http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` @@ -440,15 +441,15 @@ Control UI là các tệp tĩnh; đích WebSocket có thể cấu hình và có - `gatewayUrl` được lưu trong localStorage sau khi tải và bị xóa khỏi URL. - 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ủ, giúp 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à phương án dự phòng, và bị xóa ngay sau khi bootstrap. + - Nên truyền `token` qua mảnh URL (`#token=...`) bất cứ khi nào có thể. Mảnh 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 `?token=` cũ 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. - `password` chỉ được giữ trong bộ nhớ. - - Khi `gatewayUrl` được đặt, UI không fallback về 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. - - Dùng `wss://` khi Gateway nằm sau TLS (Tailscale Serve, proxy HTTPS, v.v.). + - Khi `gatewayUrl` được đặt, giao diện không dùng dự phòng thông tin xác thực từ cấu hình hoặc môi trường. 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. + - Dùng `wss://` khi Gateway đứng 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. - - Khi khởi động, Gateway có thể seed 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 các 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 bất kỳ origin trình duyệt nào, 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 Giao diện điều khiển không phải loopback phải đặt rõ ràng `gateway.controlUi.allowedOrigins` (nguồn gốc đầy đủ). Điều này bao gồm các thiết lập dev từ xa. + - Quá trình khởi động Gateway có thể seed 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 nguồn gốc trình duyệt từ xa vẫn cần các mục 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 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ế độ dự phòng nguồn gốc theo header Host, nhưng đây là một chế độ bảo mật nguy hiểm. @@ -469,7 +470,7 @@ Chi tiết thiết lập truy cập từ xa: [Truy cập từ xa](/vi/gateway/re ## Liên quan -- [Dashboard](/vi/web/dashboard) — dashboard Gateway -- [Kiểm tra sức khỏe](/vi/gateway/health) — giám sát sức khỏe Gateway +- [Dashboard](/vi/web/dashboard) — dashboard gateway +- [Kiểm tra tình trạng](/vi/gateway/health) — giám sát tình trạng gateway - [TUI](/vi/web/tui) — giao diện người dùng terminal -- [WebChat](/vi/web/webchat) — giao diện chat trên trình duyệt +- [WebChat](/vi/web/webchat) — giao diện trò chuyện dựa trên trình duyệt diff --git a/docs/vi/web/webchat.md b/docs/vi/web/webchat.md index 3e8c7ab8b..bde07ccd3 100644 --- a/docs/vi/web/webchat.md +++ b/docs/vi/web/webchat.md @@ -1,71 +1,83 @@ --- read_when: - Gỡ lỗi hoặc cấu hình quyền truy cập WebChat -summary: Máy chủ tĩnh Loopback WebChat và cách sử dụng WS của Gateway cho giao diện trò chuyện -title: Trò chuyện web +summary: Host tĩnh Loopback WebChat và cách sử dụng Gateway WS cho giao diện chat +title: WebChat x-i18n: - generated_at: "2026-05-03T10:43:27Z" + generated_at: "2026-05-04T02:26:57Z" model: gpt-5.5 provider: openai - source_hash: 48024e58259901c6feb67168c5c1ce32f46b8ad9b6f4511e56d2000478a3ed60 + source_hash: bf435585a13a1cde5885714837017109eeeb61ffa5e33a400017706f676f57ea source_path: web/webchat.md workflow: 16 --- -Trạng thái: giao diện chat SwiftUI macOS/iOS giao tiếp trực tiếp với Gateway WebSocket. +Trạng thái: giao diện chat SwiftUI trên macOS/iOS giao tiếp trực tiếp với Gateway WebSocket. -## Nó là gì +## Đây là gì -- Giao diện chat native cho gateway (không có trình duyệt nhúng và không có máy chủ tĩnh cục bộ). +- Một giao diện chat gốc cho Gateway (không có trình duyệt nhúng và không có máy chủ tĩnh cục bộ). - Sử dụng cùng phiên và quy tắc định tuyến như các kênh khác. -- Định tuyến xác định: phản hồi luôn quay lại WebChat. +- Định tuyến xác định: câu trả lời luôn quay lại WebChat. ## Bắt đầu nhanh -1. Khởi động gateway. -2. Mở giao diện WebChat (ứng dụng macOS/iOS) hoặc thẻ chat Control UI. -3. Đảm bảo đã cấu hình đường dẫn xác thực gateway hợp lệ (mặc định là shared-secret, - ngay cả trên loopback). +1. Khởi động Gateway. +2. Mở giao diện WebChat (ứng dụng macOS/iOS) hoặc tab chat của Control UI. +3. Đảm bảo đã cấu hình đường dẫn xác thực Gateway hợp lệ (mặc định là shared-secret, + kể cả trên local loopback). ## Cách hoạt động (hành vi) -- Giao diện kết nối với Gateway WebSocket và dùng `chat.history`, `chat.send`, và `chat.inject`. -- `chat.history` được giới hạn để ổn định: Gateway có thể cắt ngắn các trường văn bản dài, bỏ qua metadata nặng, và thay thế các mục quá lớn bằng `[chat.history omitted: message too large]`. -- `chat.history` đi theo nhánh transcript đang hoạt động đối với các tệp phiên append-only hiện đại, vì vậy các nhánh rewrite bị bỏ và các bản sao prompt đã bị thay thế sẽ không được hiển thị trong WebChat. -- Các mục Compaction hiển thị như một vạch phân cách lịch sử đã compact rõ ràng. Vạch phân cách giải thích rằng các lượt trước đó được giữ trong một checkpoint và liên kết tới các điều khiển checkpoint của Sessions, nơi người vận hành có thể tạo nhánh hoặc khôi phục chế độ xem trước Compaction khi quyền của họ cho phép. -- Control UI ghi nhớ Gateway `sessionId` nền do `chat.history` trả về và đưa nó vào các lệnh gọi `chat.send` tiếp theo, vì vậy các lần kết nối lại và làm mới trang tiếp tục cùng cuộc trò chuyện đã lưu trữ trừ khi người dùng bắt đầu hoặc đặt lại một phiên. -- Control UI gộp các lần gửi đang xử lý trùng lặp cho cùng phiên, tin nhắn, và tệp đính kèm trước khi tạo một id lần chạy `chat.send` mới; Gateway vẫn khử trùng lặp các yêu cầu lặp lại dùng lại cùng khóa idempotency. -- `chat.history` cũng được chuẩn hóa để hiển thị: ngữ cảnh OpenClaw chỉ dùng lúc runtime, - các wrapper envelope inbound, các thẻ chỉ thị phân phối inline - như `[[reply_to_*]]` và `[[audio_as_voice]]`, các payload XML gọi công cụ dạng văn bản thuần +- Giao diện kết nối tới Gateway WebSocket và dùng `chat.history`, `chat.send` và `chat.inject`. +- `chat.history` được giới hạn để ổn định: Gateway có thể cắt ngắn các trường văn bản dài, bỏ qua siêu dữ liệu nặng và thay thế các mục quá lớn bằng `[chat.history omitted: message too large]`. +- `chat.history` đi theo nhánh bản ghi hội thoại đang hoạt động đối với các tệp phiên append-only hiện đại, vì vậy các nhánh viết lại đã bị bỏ và các bản sao lời nhắc đã bị thay thế sẽ không được hiển thị trong WebChat. +- Các mục Compaction hiển thị dưới dạng một dải phân cách lịch sử đã được nén rõ ràng. Dải phân cách giải thích rằng các lượt trước đó được giữ trong một checkpoint và liên kết tới các điều khiển checkpoint của Sessions, nơi người vận hành có thể tạo nhánh hoặc khôi phục chế độ xem trước Compaction khi quyền của họ cho phép. +- Control UI ghi nhớ `sessionId` Gateway nền do `chat.history` trả về và đưa nó vào các lệnh gọi `chat.send` tiếp theo, vì vậy việc kết nối lại và làm mới trang tiếp tục cùng cuộc hội thoại đã lưu trừ khi người dùng bắt đầu hoặc đặt lại phiên. +- Control UI gộp các lượt gửi đang chạy trùng lặp cho cùng phiên, thông điệp và tệp đính kèm trước khi tạo id chạy `chat.send` mới; Gateway vẫn khử trùng lặp các yêu cầu lặp lại dùng lại cùng khóa idempotency. +- Các tệp khởi động workspace và chỉ dẫn `BOOTSTRAP.md` đang chờ được cung cấp qua Project Context trong lời nhắc hệ thống của agent, không được sao chép vào thông điệp người dùng WebChat. Việc cắt ngắn bootstrap chỉ thêm một thông báo khôi phục ngắn gọn trong lời nhắc hệ thống; số lượng chi tiết và các núm cấu hình vẫn nằm trên các bề mặt chẩn đoán. +- `chat.history` cũng được chuẩn hóa hiển thị: ngữ cảnh OpenClaw chỉ dùng lúc chạy, + các lớp bọc phong bì đầu vào, thẻ chỉ thị giao hàng nội tuyến + như `[[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), và - các token điều khiển mô hình ASCII/full-width bị rò rỉ đều bị loại khỏi văn bản hiển thị, + `...`, và các khối gọi công cụ bị cắt ngắn), cùng + các token điều khiển mô hình ASCII/toàn chiều bị rò rỉ đều bị loại khỏi văn bản hiển thị, và các mục assistant 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` sẽ bị bỏ qua. -- Các payload phản hồi được gắn cờ reasoning (`isReasoning: true`) bị loại khỏi nội dung assistant của WebChat, văn bản phát lại transcript, và các khối nội dung âm thanh, vì vậy các payload chỉ suy nghĩ không xuất hiện dưới dạng tin nhắn assistant hiển thị hoặc âm thanh có thể phát. -- `chat.inject` thêm trực tiếp một ghi chú assistant vào transcript và phát nó tới giao diện (không chạy agent). -- Các lần chạy bị hủy có thể giữ đầu ra assistant một phần hiển thị trong giao diện. -- Gateway lưu văn bản assistant một phần đã bị hủy vào lịch sử transcript khi có đầu ra đã đệm, và đánh dấu các mục đó bằng metadata hủy. -- Lịch sử luôn được lấy từ gateway (không theo dõi tệp cục bộ). -- Nếu không thể truy cập gateway, WebChat ở chế độ chỉ đọc. +- Các payload trả lời được gắn cờ suy luận (`isReasoning: true`) bị loại khỏi nội dung assistant của WebChat, văn bản phát lại bản ghi hội thoại và các khối nội dung âm thanh, vì vậy payload chỉ dùng cho suy nghĩ không xuất hiện dưới dạng thông điệp assistant hiển thị hoặc âm thanh có thể phát. +- `chat.inject` thêm trực tiếp một ghi chú assistant vào bản ghi hội thoại và phát nó tới giao diện (không chạy agent). +- Các lượt chạy bị hủy có thể giữ đầu ra assistant một phần hiển thị trong giao diện. +- Gateway lưu văn bản assistant một phần đã bị hủy vào lịch sử bản ghi hội thoại khi có đầu ra đã đệm, và đánh dấu các mục đó bằng siêu dữ liệu hủy. +- Lịch sử luôn được lấy từ Gateway (không theo dõi tệp cục bộ). +- Nếu không truy cập được Gateway, WebChat ở chế độ chỉ đọc. + +### Bản ghi hội thoại và mô hình giao hàng + +WebChat có hai đường dữ liệu riêng biệt: + +- Tệp JSONL của phiên là bản ghi hội thoại bền vững cho mô hình/runtime. Đối với các lượt chạy agent thông thường, Pi lưu các thông điệp `user`, `assistant` và `toolResult` mà mô hình nhìn thấy thông qua trình quản lý phiên của nó. WebChat không ghi tùy tiện văn bản giao hàng, trạng thái hoặc trợ giúp vào bản ghi hội thoại đó. +- Các sự kiện `ReplyPayload` của Gateway là phép chiếu giao hàng trực tiếp. Chúng có thể được chuẩn hóa cho hiển thị WebChat/kênh, block streaming, thẻ chỉ thị, nhúng media, cờ TTS/âm thanh và hành vi dự phòng của giao diện. Bản thân chúng không phải là nhật ký phiên chính quy. +- WebChat chỉ chèn các mục bản ghi hội thoại assistant khi Gateway sở hữu một thông điệp đã hiển thị ngoài một lượt assistant Pi thông thường: `chat.inject`, câu trả lời lệnh không phải agent, đầu ra một phần đã bị hủy và phần bổ sung bản ghi hội thoại media do WebChat quản lý. +- `chat.history` đọc bản ghi hội thoại phiên đã lưu và áp dụng phép chiếu hiển thị WebChat. Nếu văn bản assistant trực tiếp xuất hiện trong một lượt chạy nhưng biến mất sau khi tải lại lịch sử, trước tiên hãy kiểm tra JSONL thô có chứa văn bản assistant hay không, sau đó kiểm tra phép chiếu `chat.history` có loại bỏ nó hay không, rồi kiểm tra phần gộp đuôi lạc quan của Control UI có thay thế trạng thái giao hàng cục bộ bằng snapshot đã lưu hay không. + +Câu trả lời cuối cùng của lượt chạy agent thông thường phải bền vững vì Pi ghi `message_end` của assistant. Bất kỳ cơ chế dự phòng nào phản chiếu một payload cuối cùng đã giao vào bản ghi hội thoại trước hết phải tránh nhân đôi một lượt assistant mà Pi đã ghi. ## Bảng công cụ agent của Control UI -- Bảng Công cụ `/agents` của Control UI có hai chế độ xem riêng: +- Bảng Tools của Control UI `/agents` có hai chế độ xem riêng: - **Có sẵn ngay bây giờ** dùng `tools.effective(sessionKey=...)` và hiển thị những gì phiên hiện tại - thực sự có thể dùng lúc runtime, bao gồm các công cụ thuộc core, Plugin, và kênh. - - **Cấu hình công cụ** dùng `tools.catalog` và tập trung vào hồ sơ, override, và - ngữ nghĩa catalog. -- Tính khả dụng lúc runtime được giới hạn theo phiên. Chuyển phiên trên cùng agent có thể thay đổi - danh sách **Có sẵn ngay bây giờ**. -- Trình chỉnh sửa cấu hình không ngụ ý tính khả dụng lúc runtime; quyền truy cập hiệu lực vẫn tuân theo thứ tự ưu tiên của chính sách - (`allow`/`deny`, override theo agent và provider/kênh). + thực sự có thể dùng lúc chạy, bao gồm các công cụ thuộc lõi, Plugin và kênh. + - **Cấu hình công cụ** dùng `tools.catalog` và tiếp tục tập trung vào hồ sơ, ghi đè và + ngữ nghĩa danh mục. +- Khả năng sử dụng lúc chạy được giới hạn theo phiên. Việc chuyển phiên trên cùng agent có thể thay đổi danh sách + **Có sẵn ngay bây giờ**. +- Trình chỉnh sửa cấu hình không hàm ý khả năng sử dụng lúc chạy; quyền truy cập hiệu lực vẫn tuân theo thứ tự ưu tiên chính sách + (`allow`/`deny`, ghi đè theo agent và provider/kênh). ## Sử dụng từ xa -- Chế độ từ xa tạo tunnel Gateway WebSocket qua SSH/Tailscale. +- Chế độ từ xa tạo đường hầm Gateway WebSocket qua SSH/Tailscale. - Bạn không cần chạy một máy chủ WebChat riêng. ## Tham chiếu cấu hình (WebChat) @@ -74,20 +86,20 @@ Cấu hình đầy đủ: [Cấu hình](/vi/gateway/configuration) Tùy chọn WebChat: -- `gateway.webchat.chatHistoryMaxChars`: số ký tự tối đa cho các trường văn bản trong phản hồi `chat.history`. Khi một mục transcript vượt quá giới hạn này, Gateway cắt ngắn các trường văn bản dài và có thể thay thế các tin nhắn quá lớn bằng placeholder. Client cũng có thể gửi `maxChars` theo từng yêu cầu để ghi đè mặc định này cho một lệnh gọi `chat.history` duy nhất. +- `gateway.webchat.chatHistoryMaxChars`: số ký tự tối đa cho các trường văn bản trong phản hồi `chat.history`. Khi một mục bản ghi hội thoại vượt quá giới hạn này, Gateway cắt ngắn các trường văn bản dài và có thể thay thế thông điệp quá lớn bằng một placeholder. Client cũng có thể gửi `maxChars` theo từng yêu cầu để ghi đè mặc định này cho một lệnh gọi `chat.history` duy nhất. Tùy chọn toàn cục liên quan: - `gateway.port`, `gateway.bind`: máy chủ/cổng WebSocket. - `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`: xác thực WebSocket shared-secret. -- `gateway.auth.allowTailscale`: thẻ chat Control UI trong trình duyệt có thể dùng các header định danh Tailscale +- `gateway.auth.allowTailscale`: tab chat Control UI trên trình duyệt có thể dùng header danh tính Tailscale Serve khi được bật. -- `gateway.auth.mode: "trusted-proxy"`: xác thực reverse-proxy cho client trình duyệt phía sau nguồn proxy **không phải loopback** nhận biết danh tính (xem [Xác thực Trusted Proxy](/vi/gateway/trusted-proxy-auth)). -- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: mục tiêu gateway từ xa. -- `session.*`: lưu trữ phiên và các mặc định khóa chính. +- `gateway.auth.mode: "trusted-proxy"`: xác thực reverse-proxy cho client trình duyệt phía sau nguồn proxy **không phải loopback** có nhận biết danh tính (xem [Xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth)). +- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: mục tiêu Gateway từ xa. +- `session.*`: lưu trữ phiên và mặc định khóa chính. ## Liên quan - [Control UI](/vi/web/control-ui) -- [Dashboard](/vi/web/dashboard) +- [Bảng điều khiển](/vi/web/dashboard)