chore(i18n): refresh vi translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
daf239367e
commit
36a8586e82
@ -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ũ.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
<Steps>
|
||||
<Step title="Cài đặt BlueBubbles">
|
||||
<Step title="Install BlueBubbles">
|
||||
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)).
|
||||
</Step>
|
||||
<Step title="Bật web API">
|
||||
<Step title="Enable the web API">
|
||||
Trong cấu hình BlueBubbles, bật web API và đặt mật khẩu.
|
||||
</Step>
|
||||
<Step title="Cấu hình OpenClaw">
|
||||
<Step title="Configure OpenClaw">
|
||||
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
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Trỏ Webhook tới Gateway">
|
||||
Trỏ Webhook BlueBubbles tới Gateway của bạn (ví dụ: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
<Step title="Point webhooks at the gateway">
|
||||
Trỏ Webhook của BlueBubbles đến gateway của bạn (ví dụ: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
</Step>
|
||||
<Step title="Khởi động Gateway">
|
||||
Khởi động Gateway; nó sẽ đăng ký trình xử lý Webhook và bắt đầu ghép cặp.
|
||||
<Step title="Start the gateway">
|
||||
Khởi động gateway; nó sẽ đăng ký trình xử lý Webhook và bắt đầu ghép nối.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -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=<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=<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.
|
||||
|
||||
</Warning>
|
||||
|
||||
## 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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Lưu AppleScript">
|
||||
<Step title="Save the AppleScript">
|
||||
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
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Cài đặt LaunchAgent">
|
||||
<Step title="Install a LaunchAgent">
|
||||
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
|
||||
</plist>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
</Step>
|
||||
<Step title="Tải nó">
|
||||
<Step title="Load it">
|
||||
```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:
|
||||
|
||||
<ParamField path="URL máy chủ" type="string" required>
|
||||
<ParamField path="Server URL" type="string" required>
|
||||
Địa chỉ máy chủ BlueBubbles (ví dụ: `http://192.168.1.100:1234`).
|
||||
</ParamField>
|
||||
<ParamField path="Mật khẩu" type="string" required>
|
||||
<ParamField path="Password" type="string" required>
|
||||
Mật khẩu API từ cài đặt BlueBubbles Server.
|
||||
</ParamField>
|
||||
<ParamField path="Đường dẫn Webhook" type="string" default="/bluebubbles-webhook">
|
||||
<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
|
||||
Đường dẫn endpoint Webhook.
|
||||
</ParamField>
|
||||
<ParamField path="Chính sách DM" type="string">
|
||||
<ParamField path="DM policy" type="string">
|
||||
`pairing`, `allowlist`, `open`, hoặc `disabled`.
|
||||
</ParamField>
|
||||
<ParamField path="Danh sách cho phép" type="string[]">
|
||||
<ParamField path="Allow list" type="string[]">
|
||||
Số điện thoại, email hoặc mục tiêu trò chuyện.
|
||||
</ParamField>
|
||||
|
||||
@ -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)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM">
|
||||
<Tab title="DMs">
|
||||
- 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 <CODE>`
|
||||
- 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)
|
||||
|
||||
</Tab>
|
||||
<Tab title="Nhóm">
|
||||
<Tab title="Groups">
|
||||
- `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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 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:<guid>`
|
||||
- `chat_identifier:<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ậ
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Available actions">
|
||||
- **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.
|
||||
<Accordion title="Hành động có sẵn">
|
||||
- **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.
|
||||
|
||||
</Accordion>
|
||||
@ -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.
|
||||
|
||||
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
|
||||
|
||||
## 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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="When to enable">
|
||||
<Tab title="Khi nào bật">
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Enabling">
|
||||
<Tab title="Bật">
|
||||
```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
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Trade-offs">
|
||||
- **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.
|
||||
<Tab title="Đánh đổi">
|
||||
- **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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 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:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Config actually loaded">
|
||||
<Accordion title="Cấu hình thực sự đã được tải">
|
||||
```
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Debounce window wide enough for your setup">
|
||||
Xem nhật ký máy chủ BlueBubbles tại `~/Library/Logs/bluebubbles-server/main.log`:
|
||||
<Accordion title="Cửa sổ debounce đủ rộng cho thiết lập của bạn">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Session JSONL timestamps ≠ webhook arrival">
|
||||
Dấu thời gian sự kiện phiên (`~/.openclaw/agents/<id>/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.
|
||||
<Accordion title="Dấu thời gian JSONL phiên ≠ thời điểm webhook đến">
|
||||
Dấu thời gian sự kiện phiên (`~/.openclaw/agents/<id>/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.
|
||||
</Accordion>
|
||||
<Accordion title="Memory pressure slowing reply dispatch">
|
||||
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.
|
||||
<Accordion title="Áp lực bộ nhớ làm chậm việc gửi trả lời">
|
||||
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.
|
||||
</Accordion>
|
||||
<Accordion title="Reply-quote sends are a different path">
|
||||
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.
|
||||
<Accordion title="Gửi trích dẫn trả lời là một đường xử lý khác">
|
||||
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.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Connection and webhook">
|
||||
<Accordion title="Kết nối và webhook">
|
||||
- `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`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Access policy">
|
||||
<Accordion title="Chính sách truy cập">
|
||||
- `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.).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Delivery and chunking">
|
||||
<Accordion title="Phân phối và chia đoạn">
|
||||
- `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.<accountId>.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.<accountId>.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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Media and history">
|
||||
<Accordion title="Phương tiện và lịch sử">
|
||||
- `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.<accountId>.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.<accountId>.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.<accountId>.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.<accountId>.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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Actions and accounts">
|
||||
<Accordion title="Hành động và tài khoản">
|
||||
- `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 <code>`.
|
||||
- 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ố
|
||||
|
||||
@ -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
|
||||
---
|
||||
|
||||
<Note>
|
||||
**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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. Nhóm tác nhân chuyên biệt">
|
||||
Triển khai nhiều tác nhân với trách nhiệm nguyên tử, tập trung:
|
||||
<Accordion title="1. Nhóm tác tử chuyên biệt">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Hỗ trợ đa ngôn ngữ">
|
||||
@ -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:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="parallel (mặc định)">
|
||||
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:
|
||||
|
||||
</Tab>
|
||||
<Tab title="sequential">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Kiểm tra phát sóng">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Nếu nằm trong danh sách phát só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ự.
|
||||
<Step title="Nếu có trong danh sách phát sóng">
|
||||
- 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ự.
|
||||
|
||||
</Step>
|
||||
<Step title="Nếu không nằm trong danh sách phát sóng">
|
||||
<Step title="Nếu không có trong danh sách phát sóng">
|
||||
Áp dụng định tuyến bình thường (binding khớp đầu tiên).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
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ý.
|
||||
</Note>
|
||||
|
||||
### 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"]`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ngữ cảnh của Alfred">
|
||||
@ -227,11 +227,11 @@ Trong nhóm `120363403215116621@g.us` với các tác nhân `["alfred", "baerbel
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Phương pháp hay nhất
|
||||
## Thực hành tốt nhất
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. Giữ tác nhân tập trung">
|
||||
Thiết kế mỗi tác nhân với một trách nhiệm rõ ràng, duy nhất:
|
||||
<Accordion title="1. Giữ tác tử tập trung">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Dùng tên mô tả rõ ràng">
|
||||
Làm rõ mỗi tác nhân làm gì:
|
||||
<Accordion title="2. Dùng tên mô tả rõ">
|
||||
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
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Cấu hình quyền truy cập công cụ khác nhau">
|
||||
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"] }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="4. Theo dõi hiệu năng">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Xử lý lỗi một cách nhẹ nhàng">
|
||||
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:
|
||||
<Accordion title="4. Giám sát hiệu năng">
|
||||
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
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Xử lý lỗi một cách mềm dẻo">
|
||||
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).
|
||||
|
||||
<Note>
|
||||
**Độ ư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`.
|
||||
</Note>
|
||||
|
||||
## Khắc phục sự cố
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Tác nhân không phản hồi">
|
||||
<Accordion title="Tác tử không phản hồi">
|
||||
**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ó:
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Chỉ một tác nhân phản hồi">
|
||||
**Nguyên nhân:** ID ngang hàng có thể nằm trong `bindings` nhưng không nằm trong `broadcast`.
|
||||
<Accordion title="Chỉ một tác tử phản hồi">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Vấn đề hiệu năng">
|
||||
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`"
|
||||
|
||||
</Accordion>
|
||||
@ -446,32 +448,32 @@ interface OpenClawConfig {
|
||||
### Trường
|
||||
|
||||
<ParamField path="strategy" type='"parallel" | "sequential"' default='"parallel"'>
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="[peerId]" type="string[]">
|
||||
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.
|
||||
</ParamField>
|
||||
|
||||
## 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)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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 `<Your Domain>`**.
|
||||
- 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 `<Your Domain>`**.
|
||||
- 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://<node-name>.<tailnet>.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 <token>`.
|
||||
- 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 <token>`.
|
||||
- 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:<agentId>:googlechat:direct:<spaceId>`.
|
||||
- DM dùng khóa phiên `agent:<agentId>:googlechat:direct:<spaceId>`.
|
||||
- Không gian dùng khóa phiên `agent:<agentId>:googlechat:group:<spaceId>`.
|
||||
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 <code>`
|
||||
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/<userId>` (được khuyến nghị).
|
||||
- Tin nhắn trực tiếp: `users/<userId>` (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/<email>` đượ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/<email>` được coi là mã người dùng, không phải danh sách cho phép email.
|
||||
- Không gian: `spaces/<spaceId>`.
|
||||
|
||||
## Đ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.<id>.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.<id>.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ố
|
||||
|
||||
@ -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ó.
|
||||
|
||||
<Note>
|
||||
**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`).
|
||||
|
||||
</Note>
|
||||
|
||||
@ -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ử.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Hành vi hiện tại phụ thuộc vào kênh">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hướng tăng cường an toàn (đã lên kế hoạch)">
|
||||
<Accordion title="Hướng tăng cường bảo mật (đã lên kế hoạch)">
|
||||
- `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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -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: { "<group-id>": { ... } }` (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: { "<group-id>": { ... } }` (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...
|
||||
|
||||
<a id="pattern-personal-dms-public-groups-single-agent"></a>
|
||||
|
||||
## 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:<channel>:group:<id>`). 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:<channel>:group:<id>`). 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
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
<Tabs>
|
||||
@ -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. |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ghi chú theo kênh">
|
||||
- `groupPolicy` tách biệt với cổng nhắc tên (yêu cầu @nhắc tên).
|
||||
<Accordion title="Ghi chú theo từng kênh">
|
||||
- `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.<id>.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.<provider>`), 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.<provider>` 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`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
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):
|
||||
|
||||
<Steps>
|
||||
<Step title="groupPolicy">
|
||||
`groupPolicy` (open/disabled/allowlist).
|
||||
</Step>
|
||||
<Step title="Danh sách cho phép của nhóm">
|
||||
Danh sách cho phép của nhóm (`*.groups`, `*.groupAllowFrom`, danh sách cho phép theo kênh).
|
||||
<Step title="Danh sách cho phép nhóm">
|
||||
Danh sách cho phép nhóm (`*.groups`, `*.groupAllowFrom`, danh sách cho phép riêng theo kênh).
|
||||
</Step>
|
||||
<Step title="Chặn theo lượt nhắc đến">
|
||||
Chặn theo lượt nhắc đến (`requireMention`, `/activation`).
|
||||
<Step title="Kiểm soát bằng lượt nhắc">
|
||||
Kiểm soát bằng lượt nhắc (`requireMention`, `/activation`).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ghi chú về chặn theo lượt nhắc đến">
|
||||
- `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.
|
||||
<Accordion title="Ghi chú về kiểm soát bằng lượt nhắc">
|
||||
- `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.<channel>.historyLimit` (hoặc `channels.<channel>.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.<channel>.historyLimit` (hoặc `channels.<channel>.accounts.*.historyLimit`) cho các ghi đè. Đặt `0` để tắt.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, 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:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, 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):
|
||||
|
||||
<Steps>
|
||||
<Step title="toolsBySender của nhóm">
|
||||
Khớp `toolsBySender` của nhóm/kênh.
|
||||
</Step>
|
||||
<Step title="Công cụ của nhóm">
|
||||
<Step title="tools của nhóm">
|
||||
`tools` của nhóm/kênh.
|
||||
</Step>
|
||||
<Step title="toolsBySender mặc định">
|
||||
Khớp `toolsBySender` mặc định (`"*"`).
|
||||
</Step>
|
||||
<Step title="Công cụ mặc định">
|
||||
<Step title="tools mặc định">
|
||||
`tools` mặc định (`"*"`).
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -398,18 +400,18 @@ Ví dụ (Telegram):
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.*`).
|
||||
</Note>
|
||||
|
||||
## 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.
|
||||
|
||||
<Warning>
|
||||
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 đó.
|
||||
</Warning>
|
||||
|
||||
Ý định thường gặp (sao chép/dán):
|
||||
Ý định phổ biến (sao chép/dán):
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tắt tất cả trả lời nhóm">
|
||||
@ -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
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Chỉ cho phép các nhóm cụ thể (WhatsApp)">
|
||||
<Tab title="Chỉ cho phép nhóm cụ thể (WhatsApp)">
|
||||
```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
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Chỉ chủ sở hữu kích hoạt (WhatsApp)">
|
||||
<Tab title="Kích hoạt chỉ dành cho chủ sở hữu (WhatsApp)">
|
||||
```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
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 <CODE>
|
||||
```
|
||||
|
||||
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:<name>` 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: `<channel>-allowFrom.json`
|
||||
- Tài khoản không mặc định: `<channel>-<accountId>-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).
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
## 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 <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
@ -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.<id>.tts` | `messages.tts` |
|
||||
| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts.<id>.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
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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ố
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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.<timestamp>` 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.<id>` 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.<provider>`.
|
||||
- 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.<timestamp>` 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.<id>` 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.<provider>`.
|
||||
- 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.<skill>.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.<skill>.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`
|
||||
|
||||
|
||||
@ -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: `<workspace>/skills`
|
||||
- Skills tác tử dự án: `<workspace>/.agents/skills`
|
||||
- Skills tác tử cá nhân: `~/.agents/skills`
|
||||
- Workspace: `<workspace>/skills`
|
||||
- Skills tác nhân dự án: `<workspace>/.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/<agentId>/sessions/<SessionId>.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)
|
||||
|
||||
@ -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 <cbx_...>` hoặc `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` tái sử dụng một desktop đã được làm nóng.
|
||||
- `--browser-url <url>` thay đổi trang được mở trong trình duyệt hiển thị được.
|
||||
- `--html-file <path>` 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/<run-id>/
|
||||
@ -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.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
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?
|
||||
|
||||
@ -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.<channel>.streaming.mode` kiểm soát hành vi đang xử lý hiển thị được:
|
||||
`channels.<channel>.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.<channel>.streaming.progress`.
|
||||
Nhãn tiến trình nằm trong `channels.<channel>.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.<channel>.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.<channel>.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)
|
||||
|
||||
@ -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 <subcommand>`. Nhiều lệnh có alias script `pnpm qa:*`;
|
||||
Mọi luồng QA chạy dưới `pnpm openclaw qa <subcommand>`. 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-<timestamp>/`.
|
||||
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-<timestamp>/`.
|
||||
|
||||
Đố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 <count>` để đ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 <count>` để đ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 <id>` | — | Chỉ chạy kịch bản này. Có thể lặp lại. |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord}-<timestamp>` | 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 <path>` | `process.cwd()` | Gốc kho lưu trữ khi gọi từ một cwd trung lập. |
|
||||
| `--sut-account <id>` | `sut` | Id tài khoản tạm thời bên trong cấu hình Gateway QA. |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` hoặc `live-frontier` (`live-openai` cũ vẫn hoạt động). |
|
||||
| `--model <ref>` / `--alt-model <ref>` | 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\|convex>` | `env` | Xem [nhóm thông tin xác thực Convex](#convex-credential-pool). |
|
||||
| `--credential-role <maintainer\|ci>` | `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 <id>` | — | Chỉ chạy kịch bản này. Có thể lặp lại. |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 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 <path>` | `process.cwd()` | Gốc kho lưu trữ khi gọi từ một cwd trung lập. |
|
||||
| `--sut-account <id>` | `sut` | ID tài khoản tạm thời bên trong cấu hình QA Gateway. |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` hoặc `live-frontier` (`live-openai` cũ vẫn hoạt động). |
|
||||
| `--model <ref>` / `--alt-model <ref>` | 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\|convex>` | `env` | Xem [nhóm thông tin xác thực Convex](#convex-credential-pool). |
|
||||
| `--credential-role <maintainer\|ci>` | `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/<theme>/*.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 <runner>` được mount bên dưới root `qa` dùng chung
|
||||
- cách `openclaw qa <runner>` đượ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 <runner>` 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 <runner>` 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=<level>`. `--thinking <level>` vẫn đặt một
|
||||
mức dự phòng toàn cục, và dạng cũ hơn `--model-thinking <provider/model=level>` được
|
||||
dự phòng toàn cục, và dạng cũ hơn `--model-thinking <provider/model=level>` đượ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)
|
||||
|
||||
@ -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 <message>` 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)
|
||||
|
||||
@ -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:<key>`) để đả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 <message>`,
|
||||
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.<channel>`.
|
||||
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 <mode>` như một lệnh độc lập để lưu chế độ cho phiên hiện tại.
|
||||
- Gửi `/queue <mode>` 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)
|
||||
|
||||
@ -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 <path>` để 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 <path>` để 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`.
|
||||
|
||||
<Note>
|
||||
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 đó.
|
||||
</Note>
|
||||
|
||||
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)
|
||||
|
||||
@ -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 '<json>' --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 '<json>' --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=<id|auto|pi>` 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/<model>"].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/<model>"].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/<model>"].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ớ
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="hành vi chế độ cache-ttl">
|
||||
<Accordion title="Hành vi chế độ cache-ttl">
|
||||
|
||||
- `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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
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.<channel>.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:<id>"` 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:<id>"` 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=<derived from OPENCLAW_BROWSER_CDP_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=<N>`; đặ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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
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
|
||||
|
||||
<Accordion title="Toàn quyền truy cập (không có sandbox)">
|
||||
<Accordion title="Full access (no sandbox)">
|
||||
|
||||
```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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Công cụ chỉ đọc + workspace">
|
||||
<Accordion title="Read-only tools + workspace">
|
||||
|
||||
```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
|
||||
|
||||
</Accordion>
|
||||
|
||||
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.<timestamp>`. 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.<timestamp>`. 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"`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -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.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.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.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.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.<provider>`.
|
||||
- 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.<provider>`.
|
||||
- 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`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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 |
|
||||
|
||||
<Note>
|
||||
`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.<provider>` 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.<provider>` 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.
|
||||
</Note>
|
||||
|
||||
### 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.<channel>.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.<channel>.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ự độ
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Multi-account WhatsApp">
|
||||
<Accordion title="WhatsApp nhiều tài khoản">
|
||||
|
||||
```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.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
|
||||
|
||||
</Accordion>
|
||||
@ -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<TOKEN>`; `openclaw doctor --fix` xóa hậu tố `/bot<TOKEN>` 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<TOKEN>`; `openclaw doctor --fix` loại bỏ hậu tố `/bot<TOKEN>` 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:<id>` (DM) hoặc `channel:<id>` (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.<id>.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:<id>` (DM) hoặc `channel:<id>` (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.<id>.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.<accountId>.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.<id>.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.<id>.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/<spaceId>` hoặc `users/<userId>` 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:<id>` (DM) hoặc `channel:<id>` 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.<channelId>.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.<channelId>.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:<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:<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).
|
||||
|
||||
<Accordion title="Ví dụ iMessage SSH wrapper">
|
||||
<Accordion title="Ví dụ wrapper SSH cho iMessage">
|
||||
|
||||
```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.<id>.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.<id>.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.<id>.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.<id>.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.<channel>.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.<channel>.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.<id>` 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.<id>` 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.<channel>.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ò
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Command details">
|
||||
<Accordion title="Chi tiết lệnh">
|
||||
|
||||
- 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.<provider>.commands.nativeSkills`.
|
||||
- `channels.telegram.customCommands` thêm các mục menu bot Telegram bổ sung.
|
||||
- `bash: true` bật `! <cmd>` cho shell máy chủ. Yêu cầu `tools.elevated.enabled` và người gửi nằm trong `tools.elevated.allowFrom.<channel>`.
|
||||
- `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.<provider>.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.<provider>.accounts.<id>.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 <id>` hoặc `/config set channels.<provider>.accounts.<id>...`).
|
||||
- `channels.<provider>.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.<provider>.accounts.<id>.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 <id>` hoặc `/config set channels.<provider>.accounts.<id>...`).
|
||||
- `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)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.*`
|
||||
|
||||
@ -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ự.
|
||||
|
||||
@ -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:<package-name>`. 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:<package-name>`. 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.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Đố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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Tạo gói và manifest">
|
||||
@ -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
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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/`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -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
|
||||
|
||||
<Step title="Kiểm thử và xuất bản">
|
||||
|
||||
**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 -- <bundled-plugin-root>/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.<tool>.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/<bundled-id>` đượ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
|
||||
|
||||
<Check>**package.json** có metadata `openclaw` chính xác</Check>
|
||||
<Check>Manifest **openclaw.plugin.json** hiện diện và hợp lệ</Check>
|
||||
<Check>Entry point dùng `defineChannelPluginEntry` hoặc `definePluginEntry`</Check>
|
||||
<Check>Tất cả import dùng đường dẫn `plugin-sdk/<subpath>` tập trung</Check>
|
||||
<Check>Tất cả import dùng các đường dẫn `plugin-sdk/<subpath>` tập trung</Check>
|
||||
<Check>Import nội bộ dùng module cục bộ, không tự import qua SDK</Check>
|
||||
<Check>Test pass (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>`pnpm check` pass (Plugin trong repo)</Check>
|
||||
<Check>Test vượt qua (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>`pnpm check` vượt qua (plugin trong repo)</Check>
|
||||
|
||||
## 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: <plugin-name> - <summary>` 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(<plugin-id>): beta blocker - <summary>` 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: <plugin-name> - <summary>` 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(<plugin-id>): beta blocker - <summary>` 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
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Channel Plugins" icon="messages-square" href="/vi/plugins/sdk-channel-plugins">
|
||||
Xây dựng Plugin kênh nhắn tin
|
||||
<Card title="Channel Plugin" icon="messages-square" href="/vi/plugins/sdk-channel-plugins">
|
||||
Xây dựng plugin kênh nhắn tin
|
||||
</Card>
|
||||
<Card title="Provider Plugins" icon="cpu" href="/vi/plugins/sdk-provider-plugins">
|
||||
Xây dựng Plugin nhà cung cấp model
|
||||
<Card title="Provider Plugin" icon="cpu" href="/vi/plugins/sdk-provider-plugins">
|
||||
Xây dựng plugin provider mô hình
|
||||
</Card>
|
||||
<Card title="Tổng quan SDK" icon="book-open" href="/vi/plugins/sdk-overview">
|
||||
Tham chiếu import map và API đăng ký
|
||||
</Card>
|
||||
<Card title="Helper runtime" icon="settings" href="/vi/plugins/sdk-runtime">
|
||||
<Card title="Helper Runtime" icon="settings" href="/vi/plugins/sdk-runtime">
|
||||
TTS, tìm kiếm, subagent qua api.runtime
|
||||
</Card>
|
||||
<Card title="Kiểm thử" icon="test-tubes" href="/vi/plugins/sdk-testing">
|
||||
@ -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
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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
|
||||
<vault>/
|
||||
@ -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)
|
||||
|
||||
@ -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ớ
|
||||
<Step title="Lấy khóa API của bạn">
|
||||
Tạo khóa API tại [openrouter.ai/keys](https://openrouter.ai/keys).
|
||||
</Step>
|
||||
<Step title="Chạy quy trình thiết lập ban đầu">
|
||||
<Step title="Chạy onboarding">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openrouter-api-key
|
||||
```
|
||||
</Step>
|
||||
<Step title="(Tùy chọn) Chuyển sang một mô hình cụ thể">
|
||||
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/<provider>/<model>
|
||||
@ -56,19 +56,19 @@ OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu tớ
|
||||
|
||||
<Note>
|
||||
Tham chiếu mô hình tuân theo mẫu `openrouter/<provider>/<model>`. Để 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).
|
||||
</Note>
|
||||
|
||||
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` |
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
## Cấu hình nâng cao
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Dấu mốc bộ nhớ đệm Anthropic">
|
||||
<Accordion title="Bộ nhớ đệm phản hồi">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Marker cache Anthropic">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Điền sẵn suy luận Anthropic">
|
||||
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.
|
||||
<Accordion title="Điền trước reasoning Anthropic">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Chèn tư duy / suy luận">
|
||||
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 đó.
|
||||
<Accordion title="Chèn thinking / reasoning">
|
||||
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 đó.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Phát lại suy luận DeepSeek V4">
|
||||
<Accordion title="Phát lại reasoning DeepSeek V4">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Định hình yêu cầu chỉ dành cho OpenAI">
|
||||
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.
|
||||
<Accordion title="Định dạng yêu cầu chỉ dành cho OpenAI">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tuyến dựa trên Gemini">
|
||||
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.
|
||||
<Accordion title="Tuyến dùng Gemini">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Siêu dữ liệu định tuyến nhà cung cấp">
|
||||
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.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -210,7 +242,7 @@ Nếu bạn trỏ lại nhà cung cấp OpenRouter tới một proxy hoặc URL
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Chọn mô hình" href="/vi/concepts/model-providers" icon="layers">
|
||||
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.
|
||||
</Card>
|
||||
<Card title="Tham chiếu cấu hình" href="/vi/gateway/configuration-reference" icon="gear">
|
||||
Tham chiếu cấu hình đầy đủ cho agent, mô hình, và nhà cung cấp.
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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ế.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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 `! <cmd>` (với `/bash <cmd>` 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 `! <cmd>` (với `/bash <cmd>` 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:
|
||||
<Accordion title="Chỉ thị">
|
||||
`/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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Lối tắt nội tuyế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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -69,41 +69,41 @@ Có hai hệ thống liên quan:
|
||||
```
|
||||
|
||||
<ParamField path="commands.text" type="boolean" default="true">
|
||||
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`.
|
||||
</ParamField>
|
||||
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
|
||||
Đă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.
|
||||
</ParamField>
|
||||
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.
|
||||
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"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 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"`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.bash" type="boolean" default="false">
|
||||
Bật `! <cmd>` để chạy lệnh shell trên máy chủ (`/bash <cmd>` là bí danh; yêu cầu danh sách cho phép `tools.elevated`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
|
||||
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).
|
||||
</ParamField>
|
||||
<ParamField path="commands.config" type="boolean" default="false">
|
||||
Bật `/config` (đọc/ghi `openclaw.json`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.mcp" type="boolean" default="false">
|
||||
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`).
|
||||
</ParamField>
|
||||
<ParamField path="commands.plugins" type="boolean" default="false">
|
||||
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).
|
||||
</ParamField>
|
||||
<ParamField path="commands.debug" type="boolean" default="false">
|
||||
Bật `/debug` (các ghi đè chỉ trong thời gian chạy).
|
||||
Bật `/debug` (ghi đè chỉ trong thời gian chạy).
|
||||
</ParamField>
|
||||
<ParamField path="commands.restart" type="boolean" default="true">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerAllowFrom" type="string[]">
|
||||
Đặ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.
|
||||
</ParamField>
|
||||
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
|
||||
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"`.
|
||||
</ParamField>
|
||||
<ParamField path="commands.allowFrom" type="object">
|
||||
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ó.
|
||||
</ParamField>
|
||||
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
|
||||
Á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.
|
||||
</ParamField>
|
||||
|
||||
## 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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Phiên và lượt chạy">
|
||||
- `/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 <duration|off>` và `/session max-age <duration|off>` quản lý hết hạn gắn kết luồng.
|
||||
- `/session idle <duration|off>` và `/session max-age <duration|off>` 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`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Điều khiển mô hình và lượt chạy">
|
||||
- `/think <level>` đặ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`.
|
||||
<Accordion title="Mô hình và điều khiển lượt chạy">
|
||||
- `/think <level>` đặ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=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 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=<n>|size=<n>|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 <mode>` 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=<n>|size=<n>|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 <mode>` 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 <message>` 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).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Khám phá và trạng thái">
|
||||
- `/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 <thread-id>`. 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 <thread-id>`. Xem [Xuất chẩn đoán](/vi/gateway/diagnostics).
|
||||
- `/crestodian <request>` 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 <name> [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 <id> <decision>` giải quyết prompt phê duyệt exec.
|
||||
- `/btw <question>` 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 <question>` 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).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Subagents and ACP">
|
||||
- `/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.
|
||||
<Accordion title="Tác tử con và ACP">
|
||||
- `/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 <target>` 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 <id|#|all>` hủy một hoặc tất cả tác nhân con đang chạy.
|
||||
- `/steer <id|#> <message>` 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 <id|#|all>` hủy một hoặc tất cả tác tử con đang chạy.
|
||||
- `/subagents steer <id|#> <message>` gửi chỉ đạo đến một tác tử con đang chạy. Xem [Chỉ đạo](/vi/tools/steer).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Owner-only writes and admin">
|
||||
- `/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`.
|
||||
<Accordion title="Ghi chỉ dành cho chủ sở hữu và quản trị">
|
||||
- `/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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Voice, TTS, channel control">
|
||||
<Accordion title="Giọng nói, TTS, điều khiển kênh">
|
||||
- `/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 <command>` chạy một lệnh shell trên máy chủ. Chỉ văn bản. Bí danh: `! <command>`. 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 <command>` chạy một lệnh shell trên máy chủ. Chỉ văn bản. Bí danh: `! <command>`. 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 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 <camera|screen|writes|all> [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 <voiceId|name>` 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 <camera|screen|writes|all> [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 <voiceId|name>` 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 <name> [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.<provider>.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 <name> [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.<provider>.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.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Argument and parser notes">
|
||||
<Accordion title="Ghi chú về đối số và trình phân tích cú pháp">
|
||||
- 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 <model>` 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 <id>` nhắm vào cấu hình và `/config set channels.<provider>.accounts.<id>...` 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 <model>` 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 <id>` nhắm tới cấu hình và `/config set channels.<provider>.accounts.<id>...` 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 <spec>` 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:<repo>`, hoặc `clawhub:<pkg>`, 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 <spec>` 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:<repo>`, hoặc `clawhub:<pkg>`, 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Channel-specific behavior">
|
||||
- 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).
|
||||
<Accordion title="Hành vi theo kênh">
|
||||
- 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).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Verbose / trace / fast / reasoning safety">
|
||||
- `/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).
|
||||
<Accordion title="An toàn verbose / trace / fast / reasoning">
|
||||
- `/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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Model switching">
|
||||
- `/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.
|
||||
<Accordion title="Chuyển mô hình">
|
||||
- `/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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Fast path and inline shortcuts">
|
||||
- **Đườ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.
|
||||
<Accordion title="Đường nhanh và lối tắt nội tuyến">
|
||||
- **Đườ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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skill commands and native arguments">
|
||||
- **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 <name> [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 đó.
|
||||
<Accordion title="Lệnh Skills và đối số gốc">
|
||||
- **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 <name> [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 đó.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## `/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ụ:
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Đầ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ụ:
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Cập nhật MCP
|
||||
@ -415,12 +418,12 @@ Ví dụ:
|
||||
```
|
||||
|
||||
<Note>
|
||||
`/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.
|
||||
</Note>
|
||||
|
||||
## 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ụ:
|
||||
```
|
||||
|
||||
<Note>
|
||||
- `/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.
|
||||
|
||||
</Note>
|
||||
|
||||
## Ghi chú bề mặt
|
||||
## Ghi chú theo bề mặt
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Phiên theo từng 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:<agentId>:discord:slash:<userId>`
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (tiền tố có thể cấu hình qua `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Telegram: `telegram:slash:<userId>` (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:<userId>` (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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Chi tiết riêng của Slack">
|
||||
`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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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)
|
||||
|
||||
84
docs/vi/tools/steer.md
Normal file
84
docs/vi/tools/steer.md
Normal file
@ -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 <message>` 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 <message>` 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)
|
||||
@ -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:<agentId>:subagent:<uuid>`) 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:<agentId>:subagent:<uuid>`) 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.
|
||||
|
||||
<Note>
|
||||
**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.
|
||||
</Note>
|
||||
|
||||
## 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 <agentId> <task> [--model <model>] [--thinking <level>]
|
||||
```
|
||||
|
||||
`/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 <message>`](/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 <id|#> <message>` 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 <subagent-label|session-key|session-id|session-label>
|
||||
@ -71,79 +73,79 @@ Xem [Các kênh hỗ trợ thread](#thread-supporting-channels) bên dưới.
|
||||
/session max-age <duration|off>
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Hoàn tất không chặn, dựa trên đẩy">
|
||||
- Lệnh tạo không chặn; nó trả về id lượt chạy ngay lập tức.
|
||||
<Accordion title="Non-blocking, push-based completion">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Độ bền gửi khi tạo thủ công">
|
||||
- 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.
|
||||
<Accordion title="Manual-spawn delivery resilience">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Siêu dữ liệu bàn giao hoàn tất">
|
||||
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
|
||||
<Accordion title="Completion handoff metadata">
|
||||
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ô).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Chế độ và runtime ACP">
|
||||
- `--model` và `--thinking` ghi đè mặc định cho lượt chạy cụ thể đó.
|
||||
<Accordion title="Modes and ACP runtime">
|
||||
- `--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`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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.
|
||||
</ParamField>
|
||||
<ParamField path="agentId" type="string">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
|
||||
`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`.
|
||||
</ParamField>
|
||||
<ParamField path="resumeSessionId" type="string">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="streamTo" type='"parent"'>
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">
|
||||
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ụ.
|
||||
</ParamField>
|
||||
<ParamField path="thinking" type="string">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="runTimeoutSeconds" type="number">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="thread" type="boolean" default="false">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="mode" type='"run" | "session"' default="run">
|
||||
Nếu `thread: true` và bỏ qua `mode`, mặc định trở thành `session`. `mode: "session"` yêu cầu `thread: true`.
|
||||
</ParamField>
|
||||
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
|
||||
`"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).
|
||||
</ParamField>
|
||||
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
|
||||
`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.
|
||||
</ParamField>
|
||||
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
|
||||
`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`.
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
`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.
|
||||
</Warning>
|
||||
|
||||
## 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
|
||||
|
||||
<Steps>
|
||||
<Step title="Tạo">
|
||||
<Step title="Spawn">
|
||||
`sessions_spawn` với `thread: true` (và tùy chọn `mode: "session"`).
|
||||
</Step>
|
||||
<Step title="Gắn">
|
||||
OpenClaw tạo hoặc gắn một thread vào target phiên đó trong kênh đang hoạt động.
|
||||
<Step title="Bind">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Định tuyến theo dõi tiếp">
|
||||
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.
|
||||
<Step title="Route follow-ups">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Kiểm tra thời hạ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.
|
||||
<Step title="Inspect timeouts">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Tách">
|
||||
<Step title="Detach">
|
||||
Dùng `/unfocus` để tách thủ công.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Điều khiển thủ công
|
||||
|
||||
| Lệnh | Tác dụng |
|
||||
| ------------------ | --------------------------------------------------------------------- |
|
||||
| `/focus <target>` | 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:<id>` 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 <target>` | 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:<id>` 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
|
||||
|
||||
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
|
||||
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.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
|
||||
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`.
|
||||
</ParamField>
|
||||
|
||||
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.<timestamp>` (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.<timestamp>` (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:<id>:main` | Tác nhân chính | Luôn luôn |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Tác nhân phụ (điều phối khi cho phép độ sâu 2) | Chỉ khi `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 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:<id>:main` | Tác nhân chính | Luôn luôn |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Tác nhân phụ (bộ điều phối khi cho phép độ sâu 2) | Chỉ khi `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 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ó.
|
||||
|
||||
<Note>
|
||||
**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 <id>` 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 <id>` 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:<agentId>:subagent:<uuid>`.
|
||||
- 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 `<relevant-memories>` / `<relevant_memories>`; loại bỏ các khối payload XML lệnh gọi công cụ dạng văn bản thuần (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`), 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 `<relevant-memories>` / `<relevant_memories>`; loại bỏ các khối payload XML lời gọi công cụ dạng văn bản thuần (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`), 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ộ.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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 <id>` 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 <id>` 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)
|
||||
|
||||
@ -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 <level>`, `/think:<level>`, hoặc `/thinking <level>`.
|
||||
- Chỉ thị nội tuyến trong bất kỳ nội dung đến nào: `/t <level>`, `/think:<level>`, hoặc `/thinking <level>`.
|
||||
- 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.<provider>.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.<provider>.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["<provider>/<model>"].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ố `<emoji> <tool-name>: <arg>` 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ố `<emoji> <tool-name>: <arg>` 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 `<think>...</think>` đã đó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 `<think>...</think>` đã đó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 (<resolved level>)`, 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:<level>` 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 (<resolved level>)`, 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:<level>` 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.
|
||||
|
||||
@ -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ụ
|
||||
|
||||
<ParamField path="url" type="string" required>
|
||||
URL cần fetch. Chỉ hỗ trợ `http(s)`.
|
||||
URL cần tải. Chỉ `http(s)`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="extractMode" type="'markdown' | 'text'" default="markdown">
|
||||
@ -56,11 +56,11 @@ Cắt ngắn đầu ra xuống số ký tự này.
|
||||
</Step>
|
||||
<Step title="Fallback (optional)">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Cache">
|
||||
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.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
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ư đó.
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<Note>
|
||||
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ộ.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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://<host>: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"
|
||||
|
||||
<Steps>
|
||||
<Step title="Liệt kê yêu cầu đang chờ">
|
||||
<Step title="List pending requests">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Phê duyệt bằng ID yêu cầu">
|
||||
<Step title="Approve by request ID">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
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 <id> --role <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 <id> --role <role>`. Xem [CLI Thiết bị](/vi/cli/devices) để biết về xoay vòng và thu hồi token.
|
||||
|
||||
<Note>
|
||||
- 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.
|
||||
|
||||
</Note>
|
||||
|
||||
## 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/<id>`, URL trình chỉnh sửa như `https://tweakcn.com/editor/theme?theme=amethyst-haze`, đường dẫn tương đối `/themes/<id>`, 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/<id>`, URL editor như `https://tweakcn.com/editor/theme?theme=amethyst-haze`, đường dẫn tương đối `/themes/<id>`, 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)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Trò chuyện và nói chuyện">
|
||||
<Accordion title="Chat and Talk">
|
||||
- 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).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kênh, phiên bản, phiên, giấc mơ">
|
||||
- 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`).
|
||||
<Accordion title="Channels, instances, sessions, dreams">
|
||||
- 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`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, Skills, nút, phê duyệt exec">
|
||||
- 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.*`).
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- 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.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cấu hình">
|
||||
- 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.
|
||||
<Accordion title="Config">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gỡ lỗi, nhật ký, cập nhật">
|
||||
- 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.
|
||||
<Accordion title="Debug, logs, update">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ghi chú bảng công việc Cron">
|
||||
- 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.
|
||||
<Accordion title="Cron jobs panel notes">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Hành vi trò chuyện
|
||||
## Hành vi Chat
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ngữ nghĩa gửi và lịch sử">
|
||||
- `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 `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, 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 `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Chế độ Talk (thời gian thực trên trình duyệt)">
|
||||
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.
|
||||
<Accordion title="Chế độ nói (thời gian thực trên trình duyệt)">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Dừng và hủy bỏ">
|
||||
<Accordion title="Dừng và hủy">
|
||||
- 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 đó.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Giữ lại nội dung một phần khi hủy bỏ">
|
||||
- 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.
|
||||
<Accordion title="Giữ lại phần hủy một phần">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
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ữ.
|
||||
</Tab>
|
||||
<Tab title="scripts (mặc định)">
|
||||
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.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
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.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -249,14 +250,14 @@ Ví dụ:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
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ị)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve tích hợp (ưu tiên)">
|
||||
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://<magicdns>/` (hoặc `gateway.controlUi.basePath` bạn đã cấu hình)
|
||||
- `https://<magicdns>/` (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.
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Lắng nghe trên tailnet + token">
|
||||
<Tab title="Bind tới tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
Sau đó mở:
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (hoặc `gateway.controlUi.basePath` bạn đã cấu hình)
|
||||
- `http://<tailscale-ip>: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`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -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://<lan-ip>` hoặc `http://<tailscale-ip>`), 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://<magicdns>/` (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)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Hành vi nút bật/tắt xác thực không an toàn">
|
||||
<Accordion title="Hành vi công tắc insecure-auth">
|
||||
```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).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Chỉ dùng khi khẩn cấp">
|
||||
<Accordion title="Chỉ dùng trong tình huống khẩn cấp">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -353,14 +354,14 @@ Các ngoại lệ được ghi nhận:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`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.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ghi chú về proxy tin cậy">
|
||||
- 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).
|
||||
<Accordion title="Ghi chú về trusted-proxy">
|
||||
- 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).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -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/<id>`) 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/<id>`) 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/<agentId>` chỉ trả về hình ảnh avatar cho caller đã xác thực. `GET /avatar/<agentId>?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/<agentId>` chỉ trả về hình ảnh avatar cho bên gọi đã xác thực. `GET /avatar/<agentId>?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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Khởi động máy chủ dev UI">
|
||||
<Step title="Khởi động máy chủ dev của giao diện">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
</Step>
|
||||
<Step title="Mở bằng gatewayUrl">
|
||||
<Step title="Mở với gatewayUrl">
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
@ -440,15 +441,15 @@ Control UI là các tệp tĩnh; đích WebSocket có thể cấu hình và có
|
||||
<Accordion title="Ghi chú">
|
||||
- `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:<port>` và `http://127.0.0.1:<port>` 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:<port>` và `http://127.0.0.1:<port>` 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -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
|
||||
|
||||
@ -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 `<tool_call>...</tool_call>`,
|
||||
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
|
||||
`<function_calls>...</function_calls>`, 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ị,
|
||||
`<function_calls>...</function_calls>`, 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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user