openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh vi translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 01:53:26 +00:00
parent ecb2129adc
commit ed67e1b55f
43 changed files with 6094 additions and 5463 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
docs/vi/automation/tasks.md
View File

@ -1,44 +1,44 @@
---
read_when:
- Kiểm tra công việc nền đang diễn ra hoặc đã hoàn tất gần đây
- Gỡ lỗi các lỗi gửi trong các phiên chạy tác tử tách rời
- Tìm hiểu cách các lượt chạy nền liên quan đến phiên, Cron và Heartbeat
- Kiểm tra công việc nền đang diễn ra hoặc vừa hoàn tất
- Gỡ lỗi sự cố gửi trong các lần chạy tác tử tách rời
- Hiểu cách các lần chạy nền liên quan đến phiên, Cron và Heartbeat
sidebarTitle: Background tasks
summary: Theo dõi tác vụ nền cho các lượt chạy ACP, tác nhân phụ, tác vụ Cron biệt lập và thao tác CLI
summary: Theo dõi tác vụ nền cho các lượt chạy ACP, tác nhân con, công việc Cron tách biệt và thao tác CLI
title: Tác vụ nền
x-i18n:
generated_at: "2026-05-01T10:46:21Z"
generated_at: "2026-05-05T01:44:27Z"
model: gpt-5.5
provider: openai
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991
source_path: automation/tasks.md
workflow: 16
---
<Note>
Bạn đang tìm tính năng lập lịch? Xem [Tự động hóa và tác vụ](/vi/automation) để chọn cơ chế phù hợp. Trang này là sổ cái hoạt động cho công việc nền, không phải bộ lập lịch.
Bạn đang tìm phần lập lịch? Xem [Tự động hóa và tác vụ](/vi/automation) để chọn cơ chế phù hợp. Trang này là sổ cái hoạt động cho công việc nền, không phải bộ lập lịch.
</Note>
Tác vụ nền theo dõi công việc chạy **bên ngoài phiên hội thoại chính của bạn**: các lần chạy ACP, sinh subagent, thực thi cron job cô lập, và các thao tác khởi tạo từ CLI.
Tác vụ nền theo dõi công việc chạy **bên ngoài phiên trò chuyện chính của bạn**: các lượt chạy ACP, sinh tác nhân con, thực thi công việc Cron cô lập, và các thao tác do CLI khởi tạo.
Tác vụ **không** thay thế phiên, cron job, hay heartbeat — chúng là **sổ cái hoạt động** ghi lại công việc tách rời nào đã diễn ra, khi nào, và có thành công hay không.
Tác vụ **không** thay thế phiên, công việc Cron, hay Heartbeat — chúng là **sổ cái hoạt động** ghi lại công việc tách rời nào đã xảy ra, khi nào, và có thành công hay không.
<Note>
Không phải mọi lần chạy agent đều tạo tác vụ. Các lượt Heartbeat và trò chuyện tương tác thông thường thì không. Tất cả các lần thực thi cron, sinh ACP, sinh subagent, và lệnh agent CLI thì có.
Không phải mọi lượt chạy tác nhân đều tạo tác vụ. Các lượt Heartbeat và trò chuyện tương tác thông thường thì không. Tất cả lượt thực thi Cron, lượt sinh ACP, lượt sinh tác nhân con, và lệnh tác nhân CLI đều có.
</Note>
## TL;DR
## Tóm tắt
- Tác vụ là **bản ghi**, không phải bộ lập lịch — cron và heartbeat quyết định công việc chạy _khi nào_, tác vụ theo dõi _điều đã xảy ra_.
- ACP, subagent, tất cả cron job, và thao tác CLI tạo tác vụ. Các lượt Heartbeat thì không.
- Tác vụ là **bản ghi**, không phải bộ lập lịch — Cron và Heartbeat quyết định _khi nào_ công việc chạy, tác vụ theo dõi _điều đã xảy ra_.
- ACP, tác nhân con, tất cả công việc Cron, và thao tác CLI tạo tác vụ. Các lượt Heartbeat thì không.
- Mỗi tác vụ đi qua `queued → running → terminal` (succeeded, failed, timed_out, cancelled, hoặc lost).
- Tác vụ cron vẫn hoạt động khi cron runtime vẫn sở hữu job; nếu trạng thái runtime trong bộ nhớ đã mất, bảo trì tác vụ trước tiên kiểm tra lịch sử chạy cron bền vững trước khi đánh dấu tác vụ là lost.
- Hoàn tất được điều khiển bằng đẩy: công việc tách rời có thể thông báo trực tiếp hoặc đánh thức phiên/heartbeat của người yêu cầu khi kết thúc, vì vậy các vòng lặp thăm dò trạng thái thường không phải là cách phù hợp.
- Các lần chạy cron cô lập và hoàn tất subagent cố gắng dọn dẹp các tab/trình duyệt/quy trình được theo dõi cho phiên con trước khi ghi sổ dọn dẹp cuối cùng.
- Phân phối cron cô lập chặn các phản hồi cha tạm thời đã cũ trong khi công việc subagent hậu duệ vẫn đang xả hết, và ưu tiên đầu ra hậu duệ cuối cùng nếu đầu ra đó đến trước khi phân phối.
- Thông báo hoàn tất được gửi trực tiếp đến một kênh hoặc xếp hàng cho heartbeat tiếp theo.
- `openclaw tasks list` hiển thị tất cả tác vụ; `openclaw tasks audit` nêu ra các vấn đề.
- Bản ghi terminal được giữ trong 7 ngày, rồi tự động bị cắt tỉa.
- Tác vụ Cron vẫn hoạt động khi runtime Cron vẫn sở hữu công việc; nếu trạng thái runtime trong bộ nhớ đã mất, bảo trì tác vụ trước tiên kiểm tra lịch sử lượt chạy Cron bền vững trước khi đánh dấu một tác vụ là lost.
- Hoàn tất được thúc đẩy bằng cơ chế đẩy: công việc tách rời có thể thông báo trực tiếp hoặc đánh thức phiên/Heartbeat của bên yêu cầu khi hoàn tất, vì vậy các vòng lặp thăm dò trạng thái thường không phải hình dạng phù hợp.
- Lượt chạy Cron cô lập và các lần hoàn tất tác nhân con sẽ nỗ lực tối đa dọn dẹp các tab/quy trình trình duyệt được theo dõi cho phiên con của chúng trước bước ghi sổ dọn dẹp cuối cùng.
- Việc gửi Cron cô lập chặn các phản hồi cha tạm thời đã cũ trong khi công việc tác nhân con hậu duệ vẫn đang xả nốt, và ưu tiên đầu ra cuối cùng của hậu duệ khi đầu ra đó đến trước lúc gửi.
- Thông báo hoàn tất được gửi trực tiếp tới một kênh hoặc xếp hàng cho Heartbeat tiếp theo.
- `openclaw tasks list` hiển thị tất cả tác vụ; `openclaw tasks audit` đưa vấn đề lên bề mặt.
- Bản ghi terminal được giữ trong 7 ngày, rồi tự động được cắt tỉa.
## Bắt đầu nhanh
@ -95,21 +95,21 @@ Không phải mọi lần chạy agent đều tạo tác vụ. Các lượt Hear
| Nguồn | Loại runtime | Khi bản ghi tác vụ được tạo | Chính sách thông báo mặc định |
| ---------------------- | ------------ | ------------------------------------------------------ | ----------------------------- |
| Các lần chạy nền ACP | `acp` | Sinh một phiên ACP con | `done_only` |
| Điều phối subagent | `subagent` | Sinh subagent qua `sessions_spawn` | `done_only` |
| Cron job (mọi loại) | `cron` | Mỗi lần thực thi cron (phiên chính và cô lập) | `silent` |
| Thao tác CLI | `cli` | Các lệnh `openclaw agent` chạy qua gateway | `silent` |
| Job phương tiện agent | `cli` | Các lần chạy `music_generate`/`video_generate` có phiên hỗ trợ | `silent` |
| Lượt chạy nền ACP | `acp` | Sinh một phiên ACP con | `done_only` |
| Điều phối tác nhân con | `subagent` | Sinh một tác nhân con qua `sessions_spawn` | `done_only` |
| Công việc Cron (mọi loại) | `cron` | Mỗi lượt thực thi Cron (phiên chính và cô lập) | `silent` |
| Thao tác CLI | `cli` | Lệnh `openclaw agent` chạy qua Gateway | `silent` |
| Công việc phương tiện của tác nhân | `cli` | Lượt chạy `music_generate`/`video_generate` dựa trên phiên | `silent` |
<AccordionGroup>
<Accordion title="Mặc định thông báo cho cron và phương tiện">
Tác vụ cron phiên chính dùng chính sách thông báo `silent` theo mặc định — chúng tạo bản ghi để theo dõi nhưng không tạo thông báo. Tác vụ cron cô lập cũng mặc định là `silent` nhưng dễ thấy hơn vì chúng chạy trong phiên riêng.
<Accordion title="Mặc định thông báo cho Cron và phương tiện">
Tác vụ Cron phiên chính dùng chính sách thông báo `silent` theo mặc định — chúng tạo bản ghi để theo dõi nhưng không tạo thông báo. Tác vụ Cron cô lập cũng mặc định là `silent` nhưng dễ thấy hơn vì chúng chạy trong phiên riêng.
Các lần chạy `music_generate` và `video_generate` có phiên hỗ trợ cũng dùng chính sách thông báo `silent`. Chúng vẫn tạo bản ghi tác vụ, nhưng việc hoàn tất được chuyển lại cho phiên agent ban đầu dưới dạng đánh thức nội bộ để agent có thể tự viết tin nhắn tiếp theo và đính kèm phương tiện đã hoàn tất. Nếu bạn chọn dùng `tools.media.asyncCompletion.directSend`, các lần hoàn tất `video_generate` bất đồng bộ có thể thử phân phối trực tiếp đến kênh trước; các lần hoàn tất `music_generate` bất đồng bộ vẫn đi theo đường đánh thức phiên của người yêu cầu.
Lượt chạy `music_generate` và `video_generate` dựa trên phiên cũng dùng chính sách thông báo `silent`. Chúng vẫn tạo bản ghi tác vụ, nhưng việc hoàn tất được trả lại cho phiên tác nhân gốc dưới dạng đánh thức nội bộ để tác nhân có thể tự viết thông điệp tiếp theo và đính kèm phương tiện đã hoàn tất. Các lần hoàn tất nhóm/kênh tuân theo chính sách trả lời hiển thị thông thường, nên tác nhân dùng công cụ thông điệp khi việc gửi từ nguồn yêu cầu điều đó.
</Accordion>
<Accordion title="Lan can an toàn video_generate đồng thời">
Khi tác vụ `video_generate` có phiên hỗ trợ vẫn đang hoạt động, công cụ cũng đóng vai trò lan can an toàn: các lệnh gọi `video_generate` lặp lại trong cùng phiên đó trả về trạng thái tác vụ đang hoạt động thay vì bắt đầu lần tạo đồng thời thứ hai. Dùng `action: "status"` khi bạn muốn tra cứu tiến độ/trạng thái rõ ràng từ phía agent.
<Accordion title="Lan can bảo vệ video_generate đồng thời">
Khi một tác vụ `video_generate` dựa trên phiên vẫn đang hoạt động, công cụ cũng đóng vai trò như một lan can bảo vệ: các lệnh gọi `video_generate` lặp lại trong cùng phiên đó trả về trạng thái tác vụ đang hoạt động thay vì bắt đầu một lượt tạo đồng thời thứ hai. Dùng `action: "status"` khi bạn muốn tra cứu tiến độ/trạng thái rõ ràng từ phía tác nhân.
</Accordion>
<Accordion title="Điều gì không tạo tác vụ">
- Các lượt Heartbeat — phiên chính; xem [Heartbeat](/vi/gateway/heartbeat)
@ -135,50 +135,50 @@ stateDiagram-v2
| Trạng thái | Ý nghĩa |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Đã tạo, đang chờ agent bắt đầu |
| `running` | Lượt agent đang thực thi tích cực |
| `succeeded` | Hoàn tất thành công |
| `failed` | Hoàn tất với lỗi |
| `timed_out` | Vượt quá thời gian chờ đã cấu hình |
| `cancelled` | Bị người vận hành dừng qua `openclaw tasks cancel` |
| `lost` | Runtime mất trạng thái chống lưng có thẩm quyền sau thời gian ân hạn 5 phút |
| `queued` | Đã tạo, đang chờ tác nhân bắt đầu |
| `running` | Lượt tác nhân đang chủ động thực thi |
| `succeeded` | Đã hoàn tất thành công |
| `failed` | Đã hoàn tất với lỗi |
| `timed_out` | Đã vượt quá thời gian chờ đã cấu hình |
| `cancelled` | Bị toán tử dừng qua `openclaw tasks cancel` |
| `lost` | Runtime mất trạng thái hậu thuẫn có thẩm quyền sau thời gian gia hạn 5 phút |
Chuyển đổi diễn ra tự động — khi lần chạy agent liên kết kết thúc, trạng thái tác vụ cập nhật để khớp.
Chuyển tiếp diễn ra tự động — khi lượt chạy tác nhân liên quan kết thúc, trạng thái tác vụ được cập nhật để khớp.
Hoàn tất lần chạy agent là nguồn có thẩm quyền cho các bản ghi tác vụ đang hoạt động. Một lần chạy tách rời thành công kết thúc là `succeeded`, lỗi chạy thông thường kết thúc là `failed`, và kết quả hết thời gian chờ hoặc hủy bỏ kết thúc là `timed_out`. Nếu người vận hành đã hủy tác vụ, hoặc runtime đã ghi nhận trạng thái terminal mạnh hơn như `failed`, `timed_out`, hoặc `lost`, tín hiệu thành công đến sau không hạ cấp trạng thái terminal đó.
Việc hoàn tất lượt chạy tác nhân là có thẩm quyền đối với các bản ghi tác vụ đang hoạt động. Một lượt chạy tách rời thành công kết thúc là `succeeded`, lỗi lượt chạy thông thường kết thúc là `failed`, và kết quả hết thời gian chờ hoặc hủy bỏ kết thúc là `timed_out`. Nếu toán tử đã hủy tác vụ, hoặc runtime đã ghi nhận một trạng thái terminal mạnh hơn như `failed`, `timed_out`, hoặc `lost`, tín hiệu thành công đến sau sẽ không hạ cấp trạng thái terminal đó.
`lost` có nhận biết runtime:
`lost` nhận biết runtime:
- Tác vụ ACP: siêu dữ liệu phiên ACP con chống lưng đã biến mất.
- Tác vụ subagent: phiên con chống lưng đã biến mất khỏi kho agent đích.
- Tác vụ cron: cron runtime không còn theo dõi job là đang hoạt động và lịch sử chạy cron bền vững không hiển thị kết quả terminal cho lần chạy đó. Kiểm tra CLI ngoại tuyến không xem trạng thái cron runtime trong tiến trình trống của chính nó là có thẩm quyền.
- Tác vụ CLI: tác vụ phiên con cô lập dùng phiên con; tác vụ CLI có chat hỗ trợ dùng ngữ cảnh chạy trực tiếp thay vào đó, vì vậy các hàng phiên kênh/nhóm/trực tiếp còn sót lại không giữ chúng sống. Các lần chạy `openclaw agent` có Gateway hỗ trợ cũng kết thúc từ kết quả chạy của chúng, nên các lần chạy đã hoàn tất không nằm ở trạng thái hoạt động cho đến khi sweeper đánh dấu chúng là `lost`.
- Tác vụ ACP: siêu dữ liệu phiên con ACP hậu thuẫn đã biến mất.
- Tác vụ tác nhân con: phiên con hậu thuẫn đã biến mất khỏi kho tác nhân đích.
- Tác vụ Cron: runtime Cron không còn theo dõi công việc là đang hoạt động và lịch sử lượt chạy Cron bền vững không hiển thị kết quả terminal cho lượt chạy đó. Kiểm tra CLI ngoại tuyến không coi trạng thái runtime Cron trong tiến trình rỗng của chính nó là có thẩm quyền.
- Tác vụ CLI: tác vụ phiên con cô lập dùng phiên con; tác vụ CLI dựa trên trò chuyện dùng ngữ cảnh lượt chạy trực tiếp thay vào đó, nên các hàng phiên kênh/nhóm/trực tiếp còn tồn đọng không giữ chúng sống. Lượt chạy `openclaw agent` dựa trên Gateway cũng kết thúc từ kết quả lượt chạy của chúng, nên các lượt chạy đã hoàn tất không nằm ở trạng thái hoạt động cho đến khi bộ quét đánh dấu chúng là `lost`.
## Phân phối và thông báo
## Gửi và thông báo
Khi tác vụ đạt trạng thái terminal, OpenClaw thông báo cho bạn. Có hai đường phân phối:
Khi một tác vụ đạt trạng thái terminal, OpenClaw thông báo cho bạn. Có hai đường gửi:
**Phân phối trực tiếp** — nếu tác vụ có đích kênh (`requesterOrigin`), tin nhắn hoàn tất đi thẳng đến kênh đó (Telegram, Discord, Slack, v.v.). Với các lần hoàn tất subagent, OpenClaw cũng giữ định tuyến luồng/chủ đề đã liên kết khi có và có thể điền `to` / tài khoản bị thiếu từ tuyến đã lưu của phiên người yêu cầu (`lastChannel` / `lastTo` / `lastAccountId`) trước khi từ bỏ phân phối trực tiếp.
**Gửi trực tiếp** — nếu tác vụ có đích kênh (`requesterOrigin`), thông điệp hoàn tất đi thẳng tới kênh đó (Telegram, Discord, Slack, v.v.). Với các lần hoàn tất tác nhân con, OpenClaw cũng bảo toàn định tuyến luồng/chủ đề đã liên kết khi có sẵn và có thể điền `to` / tài khoản bị thiếu từ tuyến đã lưu của phiên bên yêu cầu (`lastChannel` / `lastTo` / `lastAccountId`) trước khi từ bỏ gửi trực tiếp.
**Phân phối xếp hàng theo phiên** — nếu phân phối trực tiếp thất bại hoặc không đặt origin, bản cập nhật được xếp hàng làm sự kiện hệ thống trong phiên của người yêu cầu và xuất hiện ở heartbeat tiếp theo.
**Gửi xếp hàng theo phiên** — nếu gửi trực tiếp thất bại hoặc không đặt origin, cập nhật được xếp hàng như một sự kiện hệ thống trong phiên của bên yêu cầu và xuất hiện trong Heartbeat tiếp theo.
<Tip>
Hoàn tất tác vụ kích hoạt đánh thức heartbeat ngay lập tức để bạn thấy kết quả nhanh chóng — bạn không phải đợi nhịp heartbeat đã lập lịch tiếp theo.
Hoàn tất tác vụ kích hoạt đánh thức Heartbeat ngay lập tức để bạn thấy kết quả nhanh chóng — bạn không phải chờ nhịp Heartbeat đã lập lịch tiếp theo.
</Tip>
Điều đó nghĩa là quy trình thông thường dựa trên đẩy: bắt đầu công việc tách rời một lần, rồi để runtime đánh thức hoặc thông báo cho bạn khi hoàn tất. Chỉ thăm dò trạng thái tác vụ khi bạn cần gỡ lỗi, can thiệp, hoặc kiểm tra rõ ràng.
Điều đó có nghĩa quy trình thông thường dựa trên cơ chế đẩy: khởi động công việc tách rời một lần, rồi để runtime đánh thức hoặc thông báo cho bạn khi hoàn tất. Chỉ thăm dò trạng thái tác vụ khi bạn cần gỡ lỗi, can thiệp, hoặc kiểm tra rõ ràng.
### Chính sách thông báo
Kiểm soát mức độ bạn nghe về từng tác vụ:
| Chính sách | Nội dung được phân phối |
| --------------------- | ------------------------------------------------------------------------- |
| Chính sách | Nội dung được gửi |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (mặc định) | Chỉ trạng thái terminal (succeeded, failed, v.v.) — **đây là mặc định** |
| `state_changes` | Mọi chuyển đổi trạng thái và cập nhật tiến độ |
| `silent` | Không có gì cả |
| `state_changes` | Mọi chuyển tiếp trạng thái và cập nhật tiến độ |
| `silent` | Hoàn toàn không có gì |
Thay đổi chính sách khi tác vụ đang chạy:
Thay đổi chính sách trong khi một tác vụ đang chạy:
```bash
openclaw tasks notify <lookup> state_changes
@ -192,7 +192,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
Cột đầu ra: ID tác vụ, Loại, Trạng thái, Phân phối, ID lần chạy, Phiên con, Tóm tắt.
Cột đầu ra: ID tác vụ, Loại, Trạng thái, Gửi, ID lượt chạy, Phiên con, Tóm tắt.
</Accordion>
<Accordion title="tasks show">
@ -200,7 +200,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
Mã tra cứu chấp nhận ID tác vụ, ID lần chạy, hoặc khóa phiên. Hiển thị bản ghi đầy đủ bao gồm thời gian, trạng thái phân phối, lỗi, và tóm tắt terminal.
Mã tra cứu chấp nhận ID tác vụ, ID lượt chạy, hoặc khóa phiên. Hiển thị bản ghi đầy đủ bao gồm thời gian, trạng thái gửi, lỗi, và tóm tắt terminal.
</Accordion>
<Accordion title="tasks cancel">
@ -208,7 +208,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Với tác vụ ACP và subagent, thao tác này giết phiên con. Với tác vụ được CLI theo dõi, việc hủy được ghi trong sổ đăng ký tác vụ (không có handle runtime con riêng). Trạng thái chuyển sang `cancelled` và thông báo phân phối được gửi khi áp dụng.
Với tác vụ ACP và tác nhân con, lệnh này giết phiên con. Với tác vụ do CLI theo dõi, việc hủy được ghi trong sổ đăng ký tác vụ (không có handle runtime con riêng). Trạng thái chuyển sang `cancelled` và thông báo gửi đi được gửi khi áp dụng.
</Accordion>
<Accordion title="tasks notify">
@ -221,16 +221,16 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks audit [--json]
```
Nêu ra các vấn đề vận hành. Các phát hiện cũng xuất hiện trong `openclaw status` khi phát hiện vấn đề.
Đưa các vấn đề vận hành lên bề mặt. Phát hiện cũng xuất hiện trong `openclaw status` khi phát hiện vấn đề.
| Phát hiện | Mức độ | Điều kiện kích hoạt |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | warn | Đã được xếp hàng hơn 10 phút |
| `stale_running` | error | Đang chạy hơn 30 phút |
| `lost` | warn/error | Quyền sở hữu tác vụ được runtime hậu thuẫn đã biến mất; các tác vụ bị mất được giữ lại sẽ cảnh báo cho đến `cleanupAfter`, rồi trở thành lỗi |
| `delivery_failed` | warn | Gửi thất bại và chính sách thông báo không phải là `silent` |
| `missing_cleanup` | warn | Tác vụ kết thúc không có dấu thời gian dọn dẹp |
| `inconsistent_timestamps` | warn | Vi phạm dòng thời gian (ví dụ kết thúc trước khi bắt đầu) |
| Phát hiện | Mức độ nghiêm trọng | Điều kiện kích hoạt |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | warn | Đã xếp hàng hơn 10 phút |
| `stale_running` | error | Đang chạy hơn 30 phút |
| `lost` | warn/error | Quyền sở hữu tác vụ dựa trên môi trường chạy đã biến mất; các tác vụ bị mất được giữ lại sẽ cảnh báo cho đến `cleanupAfter`, rồi trở thành lỗi |
| `delivery_failed` | warn | Gửi thất bại và chính sách thông báo không phải là `silent` |
| `missing_cleanup` | warn | Tác vụ ở trạng thái kết thúc không có dấu thời gian dọn dẹp |
| `inconsistent_timestamps` | warn | Vi phạm dòng thời gian (ví dụ kết thúc trước khi bắt đầu) |
</Accordion>
<Accordion title="tasks maintenance">
@ -239,21 +239,21 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks maintenance --apply [--json]
```
Dùng lệnh này để xem trước hoặc áp dụng việc đối chiếu, đóng dấu dọn dẹp và cắt tỉa cho tác vụ và trạng thái Task Flow.
Sử dụng lệnh này để xem trước hoặc áp dụng đối soát, gán mốc dọn dẹp và xóa tỉa cho tác vụ và trạng thái Luồng tác vụ.
Việc đối chiếu có nhận biết runtime:
Quá trình đối soát có nhận thức về môi trường chạy:
- Các tác vụ ACP/subagent kiểm tra phiên con hậu thuẫn của chúng.
- Các tác vụ subagent có phiên con chứa bia mộ khôi phục sau khởi động lại sẽ được đánh dấu là mất thay vì được xem là các phiên hậu thuẫn có thể khôi phục.
- Các tác vụ Cron kiểm tra xem runtime cron có còn sở hữu công việc hay không, rồi khôi phục trạng thái kết thúc từ nhật ký chạy cron/trạng thái công việc đã lưu trước khi chuyển sang `lost`. Chỉ tiến trình Gateway mới là nguồn có thẩm quyền cho tập công việc cron đang hoạt động trong bộ nhớ; kiểm tra CLI ngoại tuyến dùng lịch sử bền vững nhưng không đánh dấu tác vụ cron là mất chỉ vì Set cục bộ đó trống.
- Các tác vụ CLI được chat hậu thuẫn kiểm tra ngữ cảnh lượt chạy trực tiếp sở hữu, không chỉ hàng phiên chat.
- Các tác vụ ACP/tác nhân con kiểm tra phiên con hỗ trợ chúng.
- Các tác vụ tác nhân con có phiên con chứa bản ghi đánh dấu khôi phục sau khởi động lại sẽ được đánh dấu là bị mất thay vì được xem là phiên hỗ trợ có thể khôi phục.
- Các tác vụ Cron kiểm tra xem môi trường chạy cron còn sở hữu công việc hay không, sau đó khôi phục trạng thái kết thúc từ nhật ký lượt chạy cron/trạng thái công việc đã lưu bền vững trước khi dùng dự phòng `lost`. Chỉ tiến trình Gateway mới có thẩm quyền đối với tập hợp công việc cron đang hoạt động trong bộ nhớ; kiểm tra CLI ngoại tuyến sử dụng lịch sử bền vững nhưng không đánh dấu một tác vụ cron là bị mất chỉ vì tập hợp cục bộ đó trống.
- Các tác vụ CLI dựa trên trò chuyện kiểm tra ngữ cảnh lượt chạy đang hoạt động sở hữu, không chỉ hàng phiên trò chuyện.
Dọn dẹp khi hoàn tất cũng có nhận biết runtime:
Dọn dẹp khi hoàn tất cũng có nhận thức về môi trường chạy:
- Hoàn tất subagent cố gắng đóng các thẻ trình duyệt/tiến trình được theo dõi cho phiên con trước khi tiếp tục dọn dẹp thông báo.
- Hoàn tất cron cô lập cố gắng đóng các thẻ trình duyệt/tiến trình được theo dõi cho phiên cron trước khi lượt chạy được tháo dỡ hoàn toàn.
- Gửi cron cô lập chờ phần theo dõi subagent hậu duệ khi cần và chặn văn bản xác nhận cha đã cũ thay vì thông báo văn bản đó.
- Gửi khi hoàn tất subagent ưu tiên văn bản trợ lý hiển thị mới nhất; nếu rỗng, nó dự phòng về văn bản tool/toolResult mới nhất đã được làm sạch, và các lượt chạy gọi công cụ chỉ hết thời gian chờ có thể thu gọn thành một tóm tắt tiến độ một phần ngắn. Các lượt chạy kết thúc thất bại thông báo trạng thái thất bại mà không phát lại văn bản trả lời đã ghi lại.
- Khi tác nhân con hoàn tất, hệ thống cố gắng đóng các tab trình duyệt/quy trình được theo dõi cho phiên con trước khi tiếp tục dọn dẹp phần thông báo.
- Khi cron biệt lập hoàn tất, hệ thống cố gắng đóng các tab trình duyệt/quy trình được theo dõi cho phiên cron trước khi lượt chạy được tháo dỡ hoàn toàn.
- Việc gửi kết quả cron biệt lập đợi phần tiếp nối từ tác nhân con hậu duệ khi cần và chặn văn bản xác nhận lỗi thời của tác vụ cha thay vì thông báo nó.
- Việc gửi kết quả hoàn tất của tác nhân con ưu tiên văn bản trợ lý hiển thị mới nhất; nếu văn bản đó trống, nó dùng dự phòng văn bản tool/toolResult mới nhất đã được làm sạch, và các lượt chạy gọi công cụ chỉ hết thời gian chờ có thể được rút gọn thành một tóm tắt tiến độ một phần ngắn. Các lượt chạy thất bại ở trạng thái kết thúc thông báo trạng thái thất bại mà không phát lại văn bản trả lời đã thu nhận.
- Lỗi dọn dẹp không che khuất kết quả thật của tác vụ.
</Accordion>
@ -264,22 +264,22 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks flow cancel <lookup>
```
Dùng các lệnh này khi Task Flow điều phối là thứ bạn quan tâm thay vì một bản ghi tác vụ nền riêng lẻ.
Sử dụng các lệnh này khi bạn quan tâm đến Luồng tác vụ điều phối, thay vì một bản ghi tác vụ nền riêng lẻ.
</Accordion>
</AccordionGroup>
## Bảng tác vụ chat (`/tasks`)
## Bảng tác vụ trò chuyện (`/tasks`)
Dùng `/tasks` trong bất kỳ phiên chat nào để xem các tác vụ nền được liên kết với phiên đó. Bảng hiển thị các tác vụ đang hoạt động và mới hoàn tất gần đây cùng runtime, trạng thái, thời gian, tiến độ hoặc chi tiết lỗi.
Sử dụng `/tasks` trong bất kỳ phiên trò chuyện nào để xem các tác vụ nền được liên kết với phiên đó. Bảng hiển thị các tác vụ đang hoạt động và mới hoàn tất gần đây cùng với môi trường chạy, trạng thái, thời gian và chi tiết tiến độ hoặc lỗi.
Khi phiên hiện tại không có tác vụ liên kết hiển thị, `/tasks` sẽ dự phòng về số lượng tác vụ cục bộ của agent để bạn vẫn có được tổng quan mà không rò rỉ chi tiết của phiên khác.
Khi phiên hiện tại không có tác vụ liên kết nào hiển thị, `/tasks` dùng dự phòng số lượng tác vụ cục bộ của tác nhân, để bạn vẫn có cái nhìn tổng quan mà không làm lộ chi tiết của phiên khác.
Để xem sổ cái đầy đủ cho người vận hành, hãy dùng CLI: `openclaw tasks list`.
Để xem sổ ghi vận hành đầy đủ, hãy dùng CLI: `openclaw tasks list`.
## Tích hợp trạng thái (áp lực tác vụ)
## Tích hợp trạng thái (tải tác vụ)
`openclaw status` bao gồm tóm tắt tác vụ nhìn nhanh:
`openclaw status` bao gồm tóm tắt nhanh về tác vụ:
```
Tasks: 3 queued · 2 running · 1 issues
@ -289,9 +289,9 @@ Tóm tắt báo cáo:
- **active** — số lượng `queued` + `running`
- **failures** — số lượng `failed` + `timed_out` + `lost`
- **byRuntime** — phân rã theo `acp`, `subagent`, `cron`, `cli`
- **byRuntime** — phân tách theo `acp`, `subagent`, `cron`, `cli`
Cả `/status` và công cụ `session_status` đều dùng ảnh chụp tác vụ có nhận biết dọn dẹp: ưu tiên các tác vụ đang hoạt động, ẩn các hàng đã hoàn tất bị cũ và chỉ hiển thị các lỗi gần đây khi không còn công việc đang hoạt động. Điều này giữ thẻ trạng thái tập trung vào những gì quan trọng ngay lúc này.
Cả `/status` và công cụ `session_status` đều sử dụng bản chụp tác vụ có nhận thức về dọn dẹp: ưu tiên các tác vụ đang hoạt động, ẩn các hàng đã hoàn tất nhưng lỗi thời, và chỉ hiển thị lỗi gần đây khi không còn công việc đang hoạt động. Điều này giữ cho thẻ trạng thái tập trung vào những gì quan trọng ngay lúc này.
## Lưu trữ và bảo trì
@ -303,66 +303,65 @@ Bản ghi tác vụ được lưu bền vững trong SQLite tại:
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Registry tải vào bộ nhớ khi gateway khởi động và đồng bộ các lần ghi vào SQLite để bền vững qua các lần khởi động lại.
Gateway giữ nhật ký ghi trước của SQLite trong giới hạn bằng cách dùng ngưỡng
autocheckpoint mặc định của SQLite cùng các checkpoint `TRUNCATE` định kỳ và khi tắt.
Sổ đăng ký được nạp vào bộ nhớ khi Gateway khởi động và đồng bộ các lần ghi vào SQLite để đảm bảo độ bền qua các lần khởi động lại.
Gateway giữ nhật ký ghi trước của SQLite trong giới hạn bằng cách dùng ngưỡng tự tạo điểm kiểm tra mặc định của SQLite cùng với các điểm kiểm tra `TRUNCATE` định kỳ và khi tắt.
### Bảo trì tự động
Một trình quét chạy mỗi **60 giây** và xử lý bốn việc:
Một trình quét dọn chạy mỗi **60 giây** và xử lý bốn việc:
<Steps>
<Step title="Reconciliation">
Kiểm tra xem các tác vụ đang hoạt động có còn hậu thuẫn runtime có thẩm quyền hay không. Các tác vụ ACP/subagent dùng trạng thái phiên con, tác vụ cron dùng quyền sở hữu công việc đang hoạt động, và tác vụ CLI được chat hậu thuẫn dùng ngữ cảnh lượt chạy sở hữu. Nếu trạng thái hậu thuẫn đó biến mất hơn 5 phút, tác vụ được đánh dấu là `lost`.
<Step title="Đối soát">
Kiểm tra xem các tác vụ đang hoạt động còn có phần hỗ trợ có thẩm quyền từ môi trường chạy hay không. Tác vụ ACP/tác nhân con dùng trạng thái phiên con, tác vụ cron dùng quyền sở hữu công việc đang hoạt động, và tác vụ CLI dựa trên trò chuyện dùng ngữ cảnh lượt chạy sở hữu. Nếu trạng thái hỗ trợ đó biến mất hơn 5 phút, tác vụ được đánh dấu `lost`.
</Step>
<Step title="ACP session repair">
Đóng các phiên ACP một lần do cha sở hữu đã kết thúc hoặc mồ côi, và chỉ đóng các phiên ACP bền vững đã kết thúc bị cũ hoặc mồ côi khi không còn liên kết hội thoại đang hoạt động.
<Step title="Sửa chữa phiên ACP">
Đóng các phiên ACP một lần do phiên cha sở hữu đã kết thúc hoặc mồ côi, và chỉ đóng các phiên ACP bền bỉ đã kết thúc nhưng lỗi thời hoặc mồ côi khi không còn liên kết hội thoại đang hoạt động.
</Step>
<Step title="Cleanup stamping">
Đặt dấu thời gian `cleanupAfter` trên các tác vụ kết thúc (endedAt + 7 ngày). Trong thời gian giữ lại, tác vụ bị mất vẫn xuất hiện trong kiểm tra dưới dạng cảnh báo; sau khi `cleanupAfter` hết hạn hoặc khi thiếu siêu dữ liệu dọn dẹp, chúng là lỗi.
<Step title="Gán mốc dọn dẹp">
Đặt dấu thời gian `cleanupAfter` trên các tác vụ ở trạng thái kết thúc (endedAt + 7 ngày). Trong thời gian lưu giữ, tác vụ bị mất vẫn xuất hiện trong kiểm tra dưới dạng cảnh báo; sau khi `cleanupAfter` hết hạn hoặc khi thiếu siêu dữ liệu dọn dẹp, chúng là lỗi.
</Step>
<Step title="Pruning">
Xóa các bản ghi đã quá ngày `cleanupAfter`.
<Step title="Xóa tỉa">
Xóa các bản ghi đã qua ngày `cleanupAfter`.
</Step>
</Steps>
<Note>
**Giữ lại:** bản ghi tác vụ đã kết thúc được giữ trong **7 ngày**, rồi tự động được cắt tỉa. Không cần cấu hình.
**Lưu giữ:** bản ghi tác vụ ở trạng thái kết thúc được giữ trong **7 ngày**, rồi tự động bị xóa tỉa. Không cần cấu hình.
</Note>
## Cách tác vụ liên quan đến các hệ thống khác
## Tác vụ liên quan đến các hệ thống khác như thế nào
<AccordionGroup>
<Accordion title="Tasks and Task Flow">
[Task Flow](/vi/automation/taskflow) là lớp điều phối luồng phía trên các tác vụ nền. Một luồng đơn có thể điều phối nhiều tác vụ trong suốt vòng đời của nó bằng các chế độ đồng bộ được quản lý hoặc phản chiếu. Dùng `openclaw tasks` để kiểm tra từng bản ghi tác vụ và `openclaw tasks flow` để kiểm tra luồng điều phối.
<Accordion title="Tác vụ và Luồng tác vụ">
[Luồng tác vụ](/vi/automation/taskflow) là lớp điều phối luồng nằm bên trên các tác vụ nền. Một luồng đơn lẻ có thể điều phối nhiều tác vụ trong suốt vòng đời của nó bằng các chế độ đồng bộ được quản lý hoặc phản chiếu. Dùng `openclaw tasks` để kiểm tra các bản ghi tác vụ riêng lẻ và `openclaw tasks flow` để kiểm tra luồng điều phối.
Xem [Task Flow](/vi/automation/taskflow) để biết chi tiết.
Xem [Luồng tác vụ](/vi/automation/taskflow) để biết chi tiết.
</Accordion>
<Accordion title="Tasks and cron">
Một **định nghĩa** công việc cron nằm trong `~/.openclaw/cron/jobs.json`; trạng thái thực thi runtime nằm cạnh nó trong `~/.openclaw/cron/jobs-state.json`. **Mọi** lần thực thi cron đều tạo một bản ghi tác vụ — cả phiên chính và phiên cô lập. Các tác vụ cron phiên chính mặc định dùng chính sách thông báo `silent` để chúng theo dõi mà không tạo thông báo.
<Accordion title="Tác vụ và cron">
Một **định nghĩa** công việc cron nằm trong `~/.openclaw/cron/jobs.json`; trạng thái thực thi trong môi trường chạy nằm bên cạnh nó trong `~/.openclaw/cron/jobs-state.json`. **Mỗi** lần thực thi cron đều tạo một bản ghi tác vụ — cả phiên chính và biệt lập. Các tác vụ cron trong phiên chính mặc định dùng chính sách thông báo `silent` để chúng được theo dõi mà không tạo thông báo.
Xem [Cron Jobs](/vi/automation/cron-jobs).
Xem [Công việc Cron](/vi/automation/cron-jobs).
</Accordion>
<Accordion title="Tasks and heartbeat">
Các lượt chạy Heartbeat là các lượt phiên chính — chúng không tạo bản ghi tác vụ. Khi một tác vụ hoàn tất, nó có thể kích hoạt đánh thức Heartbeat để bạn thấy kết quả kịp thời.
<Accordion title="Tác vụ và Heartbeat">
Các lượt chạy Heartbeat là lượt trong phiên chính — chúng không tạo bản ghi tác vụ. Khi một tác vụ hoàn tất, nó có thể kích hoạt đánh thức Heartbeat để bạn thấy kết quả kịp thời.
Xem [Heartbeat](/vi/gateway/heartbeat).
</Accordion>
<Accordion title="Tasks and sessions">
Một tác vụ có thể tham chiếu `childSessionKey` (nơi công việc chạy) và `requesterSessionKey` (người đã bắt đầu nó). Phiên là ngữ cảnh hội thoại; tác vụ là lớp theo dõi hoạt động phía trên ngữ cảnh đó.
<Accordion title="Tác vụ và phiên">
Một tác vụ có thể tham chiếu `childSessionKey` (nơi công việc chạy) và `requesterSessionKey` (người đã bắt đầu nó). Phiên là ngữ cảnh hội thoại; tác vụ là lớp theo dõi hoạt động bên trên đó.
</Accordion>
<Accordion title="Tasks and agent runs">
`runId` của tác vụ liên kết đến lượt chạy agent đang thực hiện công việc. Các sự kiện vòng đời agent (bắt đầu, kết thúc, lỗi) tự động cập nhật trạng thái tác vụ — bạn không cần quản lý vòng đời theo cách thủ công.
<Accordion title="Tác vụ và lượt chạy tác nhân">
`runId` của tác vụ liên kết đến lượt chạy tác nhân đang thực hiện công việc. Các sự kiện vòng đời tác nhân (bắt đầu, kết thúc, lỗi) tự động cập nhật trạng thái tác vụ — bạn không cần quản lý vòng đời thủ công.
</Accordion>
</AccordionGroup>
## Liên quan
- [Tự động hóa & Tác vụ](/vi/automation) — toàn bộ cơ chế tự động hóa trong nháy mắt
- [CLI: Tác vụ](/vi/cli/tasks) — tài liệu tham chiếu lệnh CLI
- [Heartbeat](/vi/gateway/heartbeat) — các lượt phiên chính định kỳ
- [Tác vụ đã lên lịch](/vi/automation/cron-jobs) — lên lịch công việc nền
- [Task Flow](/vi/automation/taskflow) — điều phối luồng phía trên tác vụ
- [Tự động hóa & Tác vụ](/vi/automation) — tất cả cơ chế tự động hóa trong một cái nhìn tổng quan
- [CLI: Tác vụ](/vi/cli/tasks) — tài liệu tham khảo lệnh CLI
- [Heartbeat](/vi/gateway/heartbeat) — các lượt định kỳ trong phiên chính
- [Tác vụ theo lịch](/vi/automation/cron-jobs) — lên lịch công việc nền
- [Luồng tác vụ](/vi/automation/taskflow) — điều phối luồng bên trên tác vụ

712
docs/vi/channels/slack.md
View File

File diff suppressed because it is too large Load Diff

90
docs/vi/channels/zalouser.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Thiết lập Zalo cá nhân cho OpenClaw
- Gỡ lỗi luồng đăng nhập hoặc nhắn tin của Zalo Personal
summary: Hỗ trợ tài khoản cá nhân Zalo qua zca-js gốc (đăng nhập bằng QR), khả năng và cấu hình
- Thiết lập Zalo Personal cho OpenClaw
- Gỡ lỗi đăng nhập hoặc luồng tin nhắn Zalo Personal
summary: Hỗ trợ tài khoản cá nhân Zalo thông qua zca-js gốc (đăng nhập bằng QR), khả năng và cấu hình
title: Zalo cá nhân
x-i18n:
generated_at: "2026-05-02T22:17:08Z"
generated_at: "2026-05-05T01:44:16Z"
model: gpt-5.5
provider: openai
source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f
source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5
source_path: channels/zalouser.md
workflow: 16
---
@ -16,7 +16,7 @@ x-i18n:
Trạng thái: thử nghiệm. Tích hợp này tự động hóa **tài khoản Zalo cá nhân** thông qua `zca-js` gốc bên trong OpenClaw.
<Warning>
Đây là tích hợp không chính thức và có thể khiến tài khoản bị tạm ngưng hoặc cấm. Bạn tự chịu rủi ro khi sử dụng.
Đây là một tích hợp không chính thức và có thể khiến tài khoản bị tạm ngưng hoặc cấm. Bạn tự chịu rủi ro khi sử dụng.
</Warning>
## Plugin đi kèm
@ -24,20 +24,20 @@ Trạng thái: thử nghiệm. Tích hợp này tự động hóa **tài khoản
Zalo Personal đượ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 loại trừ Zalo Personal,
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 Zalo Personal,
hãy cài trực tiếp gói npm:
- Cài đặt qua CLI: `openclaw plugins install @openclaw/zalouser`
- Phiên bản cố định: `openclaw plugins install @openclaw/zalouser@2026.5.2`
- Hoặc từ một checkout mã nguồn: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Chi tiết: [Plugins](/vi/tools/plugin)
- Cài qua CLI: `openclaw plugins install @openclaw/zalouser`
- Phiên bản được ghim: `openclaw plugins install @openclaw/zalouser@2026.5.2`
- Hoặc từ checkout mã nguồn: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Chi tiết: [Plugin](/vi/tools/plugin)
Không cần binary CLI `zca`/`openzca` bên ngoài.
## Thiết lập nhanh (người mới bắt đầu)
1. Đảm bảo Plugin Zalo Personal có sẵn.
- Các bản phát hành OpenClaw được đóng gói hiện tại đã đi kèm Plugin này.
- Các bản phát hành OpenClaw đóng gói hiện tại đã bao gồ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. Đăng nhập (QR, trên máy Gateway):
- `openclaw channels login --channel zalouser`
@ -56,22 +56,22 @@ Không cần binary CLI `zca`/`openzca` bên ngoài.
```
4. Khởi động lại Gateway (hoặc hoàn tất thiết lập).
5. Quyền truy cập DM mặc định là ghép đôi; phê duyệt mã ghép đôi ở lần liên hệ đầu tiên.
5. Quyền truy cập DM mặc định dùng ghép nối; phê duyệt mã ghép nối ở lần liên hệ đầu tiên.
## Đây là gì
- Chạy hoàn toàn trong tiến trình thông qua `zca-js`.
- Dùng trình nghe sự kiện gốc để nhận tin nhắn đến.
- Gửi phản hồi trực tiếp qua JS API (văn bản/phương tiện/liên kết).
- Dùng trình lắng nghe sự kiện gốc để nhận tin nhắn đến.
- Gửi phản hồi trực tiếp qua API JS (văn bản/phương tiện/liên kết).
- Được thiết kế cho các trường hợp dùng “tài khoản cá nhân” khi Zalo Bot API không khả dụng.
## Đặt tên
ID kênh là `zalouser` để thể hiện rõ rằng kênh này tự động hóa **tài khoản người dùng Zalo cá nhân** (không chính thức). Chúng tôi giữ `zalo` cho một tích hợp Zalo API chính thức có thể có trong tương lai.
ID kênh là `zalouser` để thể hiện rõ rằng kênh này tự động hóa **tài khoản người dùng Zalo cá nhân** (không chính thức). Chúng tôi giữ `zalo` cho một tích hợp Zalo API chính thức tiềm năng trong tương lai.
## Tìm ID (thư mục)
Dùng CLI thư mục để khám phá người ngang hàng/nhóm và ID của họ:
Dùng CLI thư mục để khám phá peer/nhóm và ID của họ:
```bash
openclaw directory self --channel zalouser
@ -81,14 +81,16 @@ openclaw directory groups list --channel zalouser --query "work"
## Giới hạn
- Văn bản gửi đi được chia thành các đoạn khoảng ~2000 ký tự (giới hạn của ứng dụng Zalo).
- Truyền phát bị chặn theo mặc định.
- Văn bản gửi đi được chia thành các đoạn khoảng ~2000 ký tự (giới hạn của client Zalo).
- Streaming bị chặn theo mặc định.
## Kiểm soát truy cập (DM)
`channels.zalouser.dmPolicy` hỗ trợ: `pairing | allowlist | open | disabled` (mặc định: `pairing`).
`channels.zalouser.allowFrom` chấp nhận ID hoặc tên người dùng. Trong quá trình thiết lập, tên được phân giải thành ID bằng tra cứu liên hệ trong tiến trình của Plugin.
`channels.zalouser.allowFrom` nên dùng ID người dùng Zalo ổn định. Trong quá trình thiết lập tương tác, tên được nhập có thể được phân giải thành ID bằng tra cứu liên hệ trong tiến trình của Plugin.
Nếu tên thô vẫn còn trong cấu hình, khi khởi động chỉ phân giải tên đó khi bật `channels.zalouser.dangerouslyAllowNameMatching: true`. Nếu không chọn bật tùy chọn đó, kiểm tra người gửi lúc chạy chỉ dựa trên ID và tên thô bị bỏ qua khi cấp quyền.
Phê duyệt qua:
@ -100,14 +102,14 @@ Phê duyệt qua:
- Mặc định: `channels.zalouser.groupPolicy = "open"` (cho phép nhóm). Dùng `channels.defaults.groupPolicy` để ghi đè mặc định khi chưa đặt.
- Giới hạn vào danh sách cho phép bằng:
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups` (khóa nên là ID nhóm ổn định; tên được phân giải thành ID khi khởi động nếu có thể)
- `channels.zalouser.groupAllowFrom` (kiểm soát người gửi nào trong các nhóm được phép có thể kích hoạt bot)
- `channels.zalouser.groups` (khóa nên là ID nhóm ổn định; tên chỉ được phân giải thành ID khi khởi động nếu bật `channels.zalouser.dangerouslyAllowNameMatching: true`)
- `channels.zalouser.groupAllowFrom` (kiểm soát người gửi nào trong các nhóm được cho phép có thể kích hoạt bot)
- Chặn tất cả nhóm: `channels.zalouser.groupPolicy = "disabled"`.
- Trình hướng dẫn cấu hình có thể nhắc nhập danh sách cho phép nhóm.
- Khi khởi động, OpenClaw phân giải tên nhóm/người dùng trong danh sách cho phép thành ID và ghi log ánh xạ.
- Đối sánh danh sách cho phép nhóm mặc định chỉ dùng ID. Tên chưa phân giải bị bỏ qua khi xác thực trừ khi bật `channels.zalouser.dangerouslyAllowNameMatching: true`.
- `channels.zalouser.dangerouslyAllowNameMatching: true` là chế độ tương thích phá kính khẩn cấp, bật lại đối sánh tên nhóm có thể thay đổi.
- Nếu chưa đặt `groupAllowFrom`, runtime sẽ dùng `allowFrom` làm phương án dự phòng cho kiểm tra người gửi trong nhóm.
- Trình hướng dẫn cấu hình có thể hỏi danh sách nhóm được phép.
- Khi khởi động, OpenClaw phân giải tên nhóm/người dùng trong danh sách cho phép thành ID và chỉ ghi log ánh xạ khi bật `channels.zalouser.dangerouslyAllowNameMatching: true`.
- Theo mặc định, so khớp danh sách nhóm được phép chỉ dựa trên ID. Tên chưa phân giải bị bỏ qua khi xác thực trừ khi bật `channels.zalouser.dangerouslyAllowNameMatching: true`.
- `channels.zalouser.dangerouslyAllowNameMatching: true` là chế độ tương thích phá kính, bật lại phân giải tên có thể thay đổi khi khởi động và so khớp tên nhóm lúc chạy.
- Nếu chưa đặt `groupAllowFrom`, runtime dùng dự phòng `allowFrom` cho kiểm tra người gửi trong nhóm.
- Kiểm tra người gửi áp dụng cho cả tin nhắn nhóm thông thường và lệnh điều khiển (ví dụ `/new`, `/reset`).
Ví dụ:
@ -127,14 +129,14 @@ Ví dụ:
}
```
### Cổng kiểm soát nhắc đến trong nhóm
### Chặn theo đề cập trong nhóm
- `channels.zalouser.groups.<group>.requireMention` kiểm soát việc phản hồi trong nhóm có yêu cầu nhắc đến hay không.
- `channels.zalouser.groups.<group>.requireMention` kiểm soát việc phản hồi trong nhóm có yêu cầu đề cập hay không.
- Thứ tự phân giải: ID/tên nhóm chính xác -> slug nhóm đã chuẩn hóa -> `*` -> mặc định (`true`).
- Điều này áp dụng cho cả nhóm trong danh sách cho phép và chế độ nhóm mở.
- Trích dẫn tin nhắn của bot được tính là một lượt nhắc đến ngầm định để kích hoạt nhóm.
- Các lệnh điều khiển đã được ủy quyền (ví dụ `/new`) có thể bỏ qua cổng kiểm soát nhắc đến.
- Khi một tin nhắn nhóm bị bỏ qua vì yêu cầu nhắc đến, OpenClaw lưu tin đó làm lịch sử nhóm đang chờ và đưa vào tin nhắn nhóm được xử lý tiếp theo.
- Trích dẫn tin nhắn của bot được tính là một đề cập ngầm để kích hoạt nhóm.
- Lệnh điều khiển đã được cấp quyền (ví dụ `/new`) có thể bỏ qua chặn theo đề cập.
- Khi một tin nhắn nhóm bị bỏ qua vì yêu cầu đề cập, OpenClaw lưu tin đó làm lịch sử nhóm đang chờ và đưa vào tin nhắn nhóm được xử lý tiếp theo.
- Giới hạn lịch sử nhóm mặc định là `messages.groupChat.historyLimit` (dự phòng `50`). Bạn có thể ghi đè theo từng tài khoản bằng `channels.zalouser.historyLimit`.
Ví dụ:
@ -155,7 +157,7 @@ Ví dụ:
## Nhiều tài khoản
Tài khoản ánh xạ tới các hồ sơ `zalouser` trong trạng thái OpenClaw. Ví dụ:
Tài khoản ánh xạ tới hồ sơ `zalouser` trong trạng thái OpenClaw. Ví dụ:
```json5
{
@ -171,34 +173,34 @@ Tài khoản ánh xạ tới các hồ sơ `zalouser` trong trạng thái OpenCl
}
```
## Đang nhập, phản ứng và xác nhận giao nhận
## Đang nhập, phản ứng và xác nhận giao hàng
- OpenClaw gửi một sự kiện đang nhập trước khi gửi phản hồi (nỗ lực tối đa).
- Hành động phản ứng tin nhắn `react` được hỗ trợ cho `zalouser` trong các hành động kênh.
- OpenClaw gửi sự kiện đang nhập trước khi gửi phản hồi (nỗ lực tốt nhất).
- Hành động phản ứng tin nhắn `react` được hỗ trợ cho `zalouser` trong hành động kênh.
- Dùng `remove: true` để xóa một emoji phản ứng cụ thể khỏi tin nhắn.
- Ngữ nghĩa phản ứng: [Phản ứng](/vi/tools/reactions)
- Với các tin nhắn đến có siêu dữ liệu sự kiện, OpenClaw gửi xác nhận đã giao + đã xem (nỗ lực tối đa).
- Với tin nhắn đến có metadata sự kiện, OpenClaw gửi xác nhận đã giao + đã xem (nỗ lực tốt nhất).
## Khắc phục sự cố
**Đăng nhập không được giữ lại:**
**Đăng nhập không được lưu:**
- `openclaw channels status --probe`
- Đăng nhập lại: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
**Danh sách cho phép/tên nhóm không phân giải được:**
**Tên trong danh sách cho phép/nhóm không phân giải được:**
- Dùng ID dạng số trong `allowFrom`/`groupAllowFrom`/`groups`, hoặc tên bạn bè/nhóm chính xác.
- Dùng ID số trong `allowFrom`/`groupAllowFrom` và ID nhóm ổn định trong `groups`. Nếu bạn chủ ý cần tên bạn bè/nhóm chính xác, hãy bật `channels.zalouser.dangerouslyAllowNameMatching: true`.
**Đã nâng cấp từ thiết lập cũ dựa trên CLI:**
- Gỡ bỏ mọi giả định cũ về tiến trình `zca` bên ngoài.
- Xóa mọi giả định cũ về tiến trình `zca` bên ngoài.
- Kênh hiện chạy hoàn toàn trong OpenClaw mà không cần binary CLI bên ngoài.
## Liên quan
- [Tổng quan về 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 kiểm soát nhắc đến
- [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à chặn theo đề 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à tăng cường bảo mật
- [Bảo mật](/vi/gateway/security) — mô hình truy cập và gia cố

442
docs/vi/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- Bạn cần hiểu lý do một tác vụ CI đã chạy hay không chạy
- Bạn đang gỡ lỗi một bước kiểm tra GitHub Actions bị lỗi
- Bạn cần hiểu vì sao một công việc CI đã chạy hoặc không chạy
- Bạn đang gỡ lỗi một kiểm tra GitHub Actions không thành công
- Bạn đang điều phối một lần chạy hoặc chạy lại quy trình xác thực bản phát hành
- Bạn đang thay đổi việc điều phối ClawSweeper hoặc chuyển tiếp hoạt động GitHub
summary: Đồ thị tác vụ CI, cổng kiểm tra theo phạm vi, các nhóm bao quát phát hành và lệnh cục bộ tương đương
summary: Đồ thị tác vụ CI, các cổng theo phạm vi, các nhóm bao trùm phát hành và các lệnh cục bộ tương đương
title: Quy trình CI
x-i18n:
generated_at: "2026-05-04T07:03:15Z"
generated_at: "2026-05-05T01:44:35Z"
model: gpt-5.5
provider: openai
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66
source_path: ci.md
workflow: 16
---
OpenClaw CI chạy trên mọi lần push lên `main` và mọi pull request. Job `preflight` phân loại diff và tắt các lane tốn kém khi chỉ có các khu vực không liên quan thay đổi. Các lần chạy `workflow_dispatch` thủ công cố ý bỏ qua phạm vi thông minh và mở rộng toàn bộ đồ thị cho release candidate và kiểm thử diện rộng. Các lane Android vẫn là tùy chọn qua `include_android`. Phạm vi kiểm thử Plugin chỉ dành cho phát hành nằm trong workflow [`Plugin Prerelease`](#plugin-prerelease) riêng và chỉ chạy từ [`Full Release Validation`](#full-release-validation) hoặc một dispatch thủ công rõ ràng.
OpenClaw CI chạy trên mọi lần push vào `main` và mọi pull request. Job `preflight` phân loại diff và tắt các lane tốn kém khi chỉ các khu vực không liên quan thay đổi. Các lần chạy `workflow_dispatch` thủ công cố ý bỏ qua phạm vi thông minh và mở rộng toàn bộ đồ thị cho release candidate và xác thực diện rộng. Các lane Android vẫn là tùy chọn thông qua `include_android`. Phạm vi kiểm thử Plugin chỉ dành cho bản phát hành nằm trong workflow [`Plugin Prerelease`](#plugin-prerelease) riêng và chỉ chạy từ [`Full Release Validation`](#full-release-validation) hoặc một lần dispatch thủ công rõ ràng.
## Tổng quan pipeline
| Job | Mục đích | Khi chạy |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | Phát hiện thay đổi chỉ liên quan đến tài liệu, phạm vi đã thay đổi, extension đã thay đổi, và dựng manifest CI | Luôn chạy trên các push và PR không phải draft |
| `security-scm-fast` | Phát hiện khóa riêng tư và audit workflow qua `zizmor` | Luôn chạy trên các push và PR không phải draft |
| `security-dependency-audit` | Audit lockfile production không cần dependency dựa trên advisory của npm | Luôn chạy trên các push và PR không phải draft |
| `security-fast` | Tổng hợp bắt buộc cho các job bảo mật nhanh | Luôn chạy trên các push và PR không phải draft |
| `check-dependencies` | Lượt kiểm tra Knip production chỉ cho dependency cộng với guard allowlist tệp không dùng | Thay đổi liên quan đến Node |
| `build-artifacts` | Dựng `dist/`, Control UI, kiểm tra artifact đã dựng, và artifact downstream có thể tái sử dụng | Thay đổi liên quan đến Node |
| `checks-fast-core` | Các lane kiểm tra đúng đắn nhanh trên Linux như kiểm tra bundled/plugin-contract/protocol | Thay đổi liên quan đến Node |
| `checks-fast-contracts-channels` | Kiểm tra contract kênh theo shard với kết quả kiểm tra tổng hợp ổn định | Thay đổi liên quan đến Node |
| `checks-node-core-test` | Các shard kiểm thử Node lõi, không bao gồm lane channel, bundled, contract, và extension | Thay đổi liên quan đến Node |
| `check` | Tương đương gate cục bộ chính theo shard: kiểu production, lint, guard, kiểu test, và smoke nghiêm ngặt | Thay đổi liên quan đến Node |
| `check-additional` | Kiến trúc, drift boundary/prompt theo shard, guard extension, boundary package, và gateway watch | Thay đổi liên quan đến Node |
| `build-smoke` | Smoke test CLI đã dựng và smoke startup-memory | Thay đổi liên quan đến Node |
| `checks` | Bộ xác minh cho kiểm thử kênh của artifact đã dựng | Thay đổi liên quan đến Node |
| `checks-node-compat-node22` | Lane dựng và smoke tương thích Node 22 | Dispatch CI thủ công cho bản phát hành |
| `check-docs` | Kiểm tra định dạng tài liệu, lint, và liên kết hỏng | Tài liệu thay đổi |
| `skills-python` | Ruff + pytest cho skills dựa trên Python | Thay đổi liên quan đến skill Python |
| `checks-windows` | Kiểm thử process/path dành riêng cho Windows cộng với hồi quy import specifier runtime dùng chung | Thay đổi liên quan đến Windows |
| `macos-node` | Lane kiểm thử TypeScript trên macOS dùng artifact đã dựng dùng chung | Thay đổi liên quan đến macOS |
| `macos-swift` | Swift lint, build, và test cho ứng dụng macOS | Thay đổi liên quan đến macOS |
| `android` | Unit test Android cho cả hai flavor cộng với một bản dựng debug APK | Thay đổi liên quan đến Android |
| `test-performance-agent` | Tối ưu hóa test chậm Codex hằng ngày sau hoạt động đáng tin cậy | CI trên main thành công hoặc dispatch thủ công |
| `openclaw-performance` | Báo cáo hiệu năng runtime Kova hằng ngày/theo yêu cầu với các lane mock-provider, deep-profile, và live GPT 5.4 | Theo lịch và dispatch thủ công |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | Phát hiện thay đổi chỉ ở tài liệu, phạm vi đã thay đổi, extension đã thay đổi, và xây dựng manifest CI | Luôn chạy trên push và PR không phải draft |
| `security-scm-fast` | Phát hiện khóa riêng tư và kiểm tra workflow qua `zizmor` | Luôn chạy trên push và PR không phải draft |
| `security-dependency-audit` | Kiểm tra lockfile production không cần dependency đối chiếu với advisory npm | Luôn chạy trên push và PR không phải draft |
| `security-fast` | Kết quả tổng hợp bắt buộc cho các job bảo mật nhanh | Luôn chạy trên push và PR không phải draft |
| `check-dependencies` | Lượt kiểm tra chỉ dependency production bằng Knip cùng guard allowlist tệp không dùng | Thay đổi liên quan đến Node |
| `build-artifacts` | Xây dựng `dist/`, Control UI, kiểm tra artifact đã build, và artifact downstream có thể tái sử dụng | Thay đổi liên quan đến Node |
| `checks-fast-core` | Các lane tính đúng đắn nhanh trên Linux như kiểm tra bundled/plugin-contract/protocol | Thay đổi liên quan đến Node |
| `checks-fast-contracts-channels` | Kiểm tra channel contract được chia shard với kết quả kiểm tra tổng hợp ổn định | Thay đổi liên quan đến Node |
| `checks-node-core-test` | Các shard kiểm thử Node lõi, loại trừ lane channel, bundled, contract, và extension | Thay đổi liên quan đến Node |
| `check` | Tương đương cổng local chính được chia shard: kiểu production, lint, guard, kiểu kiểm thử, và smoke nghiêm ngặt | Thay đổi liên quan đến Node |
| `check-additional` | Kiến trúc, drift boundary/prompt được chia shard, guard extension, ranh giới package, và gateway watch | Thay đổi liên quan đến Node |
| `build-smoke` | Kiểm thử smoke CLI đã build và smoke bộ nhớ khởi động | Thay đổi liên quan đến Node |
| `checks` | Trình xác minh cho kiểm thử channel bằng artifact đã build | Thay đổi liên quan đến Node |
| `checks-node-compat-node22` | Lane build và smoke tương thích Node 22 | Dispatch CI thủ công cho bản phát hành |
| `check-docs` | Kiểm tra định dạng tài liệu, lint, và liên kết hỏng | Tài liệu thay đổi |
| `skills-python` | Ruff + pytest cho Skills có backend Python | Thay đổi liên quan đến Skill Python |
| `checks-windows` | Kiểm thử process/path dành riêng cho Windows cùng hồi quy import specifier runtime dùng chung | Thay đổi liên quan đến Windows |
| `macos-node` | Lane kiểm thử TypeScript trên macOS dùng artifact đã build chung | Thay đổi liên quan đến macOS |
| `macos-swift` | Swift lint, build, và kiểm thử cho ứng dụng macOS | Thay đổi liên quan đến macOS |
| `android` | Kiểm thử unit Android cho cả hai flavor cùng một lần build APK debug | Thay đổi liên quan đến Android |
| `test-performance-agent` | Tối ưu hóa kiểm thử chậm hằng ngày bằng Codex sau hoạt động đáng tin cậy | CI main thành công hoặc dispatch thủ công |
| `openclaw-performance` | Báo cáo hiệu năng runtime Kova hằng ngày/theo yêu cầu với lane mock-provider, deep-profile, và GPT 5.4 live | Theo lịch và dispatch thủ công |
## Thứ tự fail-fast
1. `preflight` quyết định lane nào thực sự tồn tại. Logic `docs-scope` và `changed-scope` là các bước bên trong job này, không phải job độc lập.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, và `skills-python` thất bại nhanh mà không chờ các job artifact và ma trận nền tảng nặng hơn.
3. `build-artifacts` chồng lấp với các lane Linux nhanh để các consumer downstream có thể bắt đầu ngay khi bản dựng dùng chung sẵn sàng.
3. `build-artifacts` chạy chồng lên các lane Linux nhanh để downstream consumer có thể bắt đầu ngay khi bản build dùng chung sẵn sàng.
4. Các lane nền tảng và runtime nặng hơn mở rộng sau đó: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, và `android`.
GitHub có thể đánh dấu các job bị thay thế là `cancelled` khi một push mới hơn được đưa lên cùng PR hoặc ref `main`. Hãy coi đó là nhiễu CI trừ khi lần chạy mới nhất cho cùng ref cũng đang thất bại. Các kiểm tra shard tổng hợp dùng `!cancelled() && always()` nên chúng vẫn báo lỗi shard bình thường nhưng không xếp hàng sau khi toàn bộ workflow đã bị thay thế. Khóa concurrency CI tự động được đánh phiên bản (`CI-v7-*`) để một zombie phía GitHub trong nhóm hàng đợi cũ không thể chặn vô hạn các lần chạy main mới hơn. Các lần chạy full-suite thủ công dùng `CI-manual-v1-*` và không hủy các lần chạy đang diễn ra.
GitHub có thể đánh dấu các job bị thay thế là `cancelled` khi một push mới hơn xuất hiện trên cùng PR hoặc ref `main`. Hãy xem đó là nhiễu CI trừ khi lần chạy mới nhất cho cùng ref cũng đang thất bại. Các kiểm tra shard tổng hợp dùng `!cancelled() && always()` nên chúng vẫn báo cáo lỗi shard bình thường nhưng không xếp hàng sau khi toàn bộ workflow đã bị thay thế. Khóa concurrency CI tự động được đánh phiên bản (`CI-v7-*`) để một zombie phía GitHub trong nhóm hàng đợi cũ không thể chặn vô thời hạn các lần chạy main mới hơn. Các lần chạy full-suite thủ công dùng `CI-manual-v1-*` và không hủy các lần chạy đang tiến hành.
## Phạm vi và định tuyến
Logic phạm vi nằm trong `scripts/ci-changed-scope.mjs` và được bao phủ bởi unit test trong `src/scripts/ci-changed-scope.test.ts`. Dispatch thủ công bỏ qua phát hiện changed-scope và khiến manifest preflight hoạt động như thể mọi khu vực có phạm vi đều đã thay đổi.
Logic phạm vi nằm trong `scripts/ci-changed-scope.mjs` và được bao phủ bởi kiểm thử unit trong `src/scripts/ci-changed-scope.test.ts`. Dispatch thủ công bỏ qua phát hiện changed-scope và khiến manifest preflight hoạt động như thể mọi khu vực có phạm vi đều đã thay đổi.
- **Chỉnh sửa workflow CI** xác thực đồ thị CI Node cộng với linting workflow, nhưng không tự ép các bản dựng native Windows, Android, hoặc macOS; các lane nền tảng đó vẫn được giới hạn theo thay đổi nguồn của nền tảng.
- **Chỉnh sửa chỉ liên quan đến định tuyến CI, một số chỉnh sửa fixture core-test rẻ, và chỉnh sửa helper/test-routing contract Plugin hẹp** dùng đường dẫn manifest nhanh chỉ Node: `preflight`, security, và một tác vụ `checks-fast-core` duy nhất. Đường dẫn đó bỏ qua artifact dựng, tương thích Node 22, contract kênh, toàn bộ shard lõi, shard bundled-plugin, và các ma trận guard bổ sung khi thay đổi chỉ giới hạn trong các bề mặt định tuyến hoặc helper mà tác vụ nhanh trực tiếp thực thi.
- **Kiểm tra Node trên Windows** được giới hạn ở wrapper process/path dành riêng cho Windows, helper runner npm/pnpm/UI, cấu hình trình quản lý package, và các bề mặt workflow CI thực thi lane đó; các thay đổi source, Plugin, install-smoke, và chỉ test không liên quan vẫn ở trên các lane Node Linux.
- **Chỉnh sửa workflow CI** xác thực đồ thị CI Node cùng lint workflow, nhưng bản thân chúng không ép buộc build native Windows, Android, hoặc macOS; các lane nền tảng đó vẫn chỉ được kích hoạt theo thay đổi nguồn nền tảng.
- **Chỉnh sửa chỉ định tuyến CI, chỉnh sửa fixture core-test rẻ đã chọn, và chỉnh sửa helper/test-routing plugin contract hẹp** dùng đường manifest nhanh chỉ Node: `preflight`, bảo mật, và một tác vụ `checks-fast-core` duy nhất. Đường này bỏ qua artifact build, tương thích Node 22, channel contract, toàn bộ shard core, shard bundled-plugin, và các ma trận guard bổ sung khi thay đổi chỉ giới hạn ở các bề mặt định tuyến hoặc helper mà tác vụ nhanh trực tiếp kiểm tra.
- **Kiểm tra Node trên Windows** được giới hạn ở wrapper process/path dành riêng cho Windows, helper runner npm/pnpm/UI, cấu hình trình quản lý package, và các bề mặt workflow CI thực thi lane đó; thay đổi nguồn, Plugin, install-smoke, và chỉ kiểm thử không liên quan vẫn chạy trên các lane Node Linux.
Các họ test Node chậm nhất được tách hoặc cân bằng để mỗi job vẫn nhỏ mà không giữ runner quá mức: contract kênh chạy thành ba shard có trọng số, lane core unit fast/support chạy riêng, hạ tầng runtime lõi được tách giữa các shard state và process/config, auto-reply chạy như các worker cân bằng (với cây con reply tách thành các shard agent-runner, dispatch, và commands/state-routing), và cấu hình gateway/server dạng agentic được tách qua các lane chat/auth/model/http-plugin/runtime/startup thay vì chờ artifact đã dựng. Các test browser, QA, media, và Plugin hỗn hợp diện rộng dùng cấu hình Vitest chuyên dụng thay vì catch-all Plugin dùng chung. Các shard include-pattern ghi mục timing bằng tên shard CI, nên `.artifacts/vitest-shard-timings.json` có thể phân biệt toàn bộ config với một shard đã lọc. `check-additional` giữ công việc compile/canary package-boundary cùng nhau và tách kiến trúc topology runtime khỏi phạm vi gateway watch; danh sách guard boundary được chia sọc trên bốn shard ma trận, mỗi shard chạy đồng thời các guard độc lập đã chọn và in timing theo từng kiểm tra, bao gồm `pnpm prompt:snapshots:check` để drift prompt happy-path của runtime Codex được ghim vào PR đã gây ra nó. Gateway watch, test kênh, và shard core support-boundary chạy đồng thời bên trong `build-artifacts` sau khi `dist/` và `dist-runtime/` đã được dựng.
Các nhóm kiểm thử Node chậm nhất được tách hoặc cân bằng để mỗi job vẫn nhỏ mà không giữ runner quá mức: channel contract chạy dưới dạng ba shard có trọng số, lane core unit fast/support chạy riêng, hạ tầng runtime core được tách giữa shard state và process/config, auto-reply chạy dưới dạng worker cân bằng (với subtree reply tách thành shard agent-runner, dispatch, và commands/state-routing), và cấu hình gateway/server agentic được tách qua các lane chat/auth/model/http-plugin/runtime/startup thay vì chờ artifact đã build. Các kiểm thử trình duyệt, QA, media, và Plugin miscellaneous diện rộng dùng cấu hình Vitest chuyên dụng thay vì catch-all Plugin dùng chung. Các shard include-pattern ghi mục thời gian bằng tên shard CI, nên `.artifacts/vitest-shard-timings.json` có thể phân biệt một cấu hình nguyên vẹn với một shard đã lọc. `check-additional` giữ công việc compile/canary ranh giới package cùng nhau và tách kiến trúc topology runtime khỏi phạm vi gateway watch; danh sách guard boundary được chia sọc qua bốn shard ma trận, mỗi shard chạy đồng thời các guard độc lập đã chọn và in thời gian từng kiểm tra, bao gồm `pnpm prompt:snapshots:check` để drift prompt đường tốt runtime Codex được ghim vào PR đã gây ra nó. Gateway watch, kiểm thử channel, và shard support-boundary core chạy đồng thời bên trong `build-artifacts` sau khi `dist/` và `dist-runtime/` đã được build.
Android CI chạy cả `testPlayDebugUnitTest` và `testThirdPartyDebugUnitTest`, rồi dựng Play debug APK. Flavor third-party không có source set hoặc manifest riêng; lane unit-test của nó vẫn compile flavor với các cờ BuildConfig SMS/call-log, đồng thời tránh một job đóng gói debug APK trùng lặp trên mọi push liên quan đến Android.
Android CI chạy cả `testPlayDebugUnitTest` và `testThirdPartyDebugUnitTest`, sau đó build APK debug Play. Flavor third-party không có source set hoặc manifest riêng; lane kiểm thử unit của nó vẫn biên dịch flavor với các cờ BuildConfig SMS/call-log, đồng thời tránh một job đóng gói APK debug trùng lặp trên mọi push liên quan đến Android.
Shard `check-dependencies` chạy `pnpm deadcode:dependencies` (một lượt Knip production chỉ cho dependency được ghim vào phiên bản Knip mới nhất, với độ tuổi phát hành tối thiểu của pnpm bị tắt cho cài đặt `dlx`) và `pnpm deadcode:unused-files`, so sánh các phát hiện tệp production không dùng của Knip với `scripts/deadcode-unused-files.allowlist.mjs`. Guard tệp không dùng thất bại khi một PR thêm tệp không dùng mới chưa được review hoặc để lại mục allowlist cũ, đồng thời giữ lại các bề mặt Plugin động, generated, build, live-test, và package bridge có chủ đích mà Knip không thể phân giải tĩnh.
Shard `check-dependencies` chạy `pnpm deadcode:dependencies` (một lượt kiểm tra chỉ dependency production bằng Knip được ghim với phiên bản Knip mới nhất, với tuổi phát hành tối thiểu của pnpm bị tắt cho cài đặt `dlx`) và `pnpm deadcode:unused-files`, thao tác này so sánh phát hiện tệp production không dùng của Knip với `scripts/deadcode-unused-files.allowlist.mjs`. Guard tệp không dùng thất bại khi PR thêm một tệp không dùng mới chưa được rà soát hoặc để lại một mục allowlist lỗi thời, trong khi vẫn giữ các bề mặt Plugin động, generated, build, live-test, và package bridge có chủ ý mà Knip không thể phân giải tĩnh.
## Chuyển tiếp hoạt động ClawSweeper
`.github/workflows/clawsweeper-dispatch.yml` là cầu nối phía đích từ hoạt động repository OpenClaw vào ClawSweeper. Nó không checkout hoặc thực thi mã pull request không đáng tin cậy. Workflow tạo token GitHub App từ `CLAWSWEEPER_APP_PRIVATE_KEY`, rồi dispatch các payload `repository_dispatch` nhỏ gọn đến `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` là cầu nối phía mục tiêu từ hoạt động repository OpenClaw vào ClawSweeper. Nó không checkout hoặc thực thi mã pull request không đáng tin cậy. Workflow tạo token GitHub App từ `CLAWSWEEPER_APP_PRIVATE_KEY`, rồi dispatch các payload `repository_dispatch` gọn tới `openclaw/clawsweeper`.
Workflow có bốn lane:
- `clawsweeper_item` cho các yêu cầu review chính xác với issue và pull request;
- `clawsweeper_comment` cho các lệnh ClawSweeper rõ ràng trong comment issue;
- `clawsweeper_commit_review` cho các yêu cầu review ở cấp commit trên các push `main`;
- `clawsweeper_item` cho yêu cầu review issue và pull request chính xác;
- `clawsweeper_comment` cho lệnh ClawSweeper rõ ràng trong bình luận issue;
- `clawsweeper_commit_review` cho yêu cầu review cấp commit trên các push vào `main`;
- `github_activity` cho hoạt động GitHub chung mà agent ClawSweeper có thể kiểm tra.
Lane `github_activity` chỉ chuyển tiếp metadata đã chuẩn hóa: loại event, action, actor, repository, số item, URL, title, state, và đoạn trích ngắn cho comment hoặc review khi có. Nó cố ý tránh chuyển tiếp toàn bộ body Webhook. Workflow nhận trong `openclaw/clawsweeper` là `.github/workflows/github-activity.yml`, đăng event đã chuẩn hóa đến hook OpenClaw Gateway cho agent ClawSweeper.
Lane `github_activity` chỉ chuyển tiếp metadata đã chuẩn hóa: loại sự kiện, hành động, actor, repository, số mục, URL, tiêu đề, trạng thái, và đoạn trích ngắn cho bình luận hoặc review khi có. Nó cố ý tránh chuyển tiếp toàn bộ webhook body. Workflow nhận trong `openclaw/clawsweeper` là `.github/workflows/github-activity.yml`, workflow này đăng sự kiện đã chuẩn hóa tới hook OpenClaw Gateway cho agent ClawSweeper.
Hoạt động chung là quan sát, không phải mặc định phân phối. Agent ClawSweeper nhận đích Discord trong prompt của nó và chỉ nên đăng vào `#clawsweeper` khi event gây bất ngờ, có thể hành động, rủi ro, hoặc hữu ích về vận hành. Các lượt mở, chỉnh sửa, biến động bot, nhiễu Webhook trùng lặp, và lưu lượng review bình thường nên trả về `NO_REPLY`.
Hoạt động chung là quan sát, không phải mặc định chuyển giao. Agent ClawSweeper nhận đích Discord trong prompt của nó và chỉ nên đăng tới `#clawsweeper` khi sự kiện bất ngờ, có thể hành động, rủi ro, hoặc hữu ích về vận hành. Các thao tác mở, chỉnh sửa, nhiễu bot, nhiễu webhook trùng lặp, và lưu lượng review bình thường nên trả về `NO_REPLY`.
Xem title, comment, body, văn bản review, tên nhánh, và commit message trên GitHub là dữ liệu không đáng tin cậy xuyên suốt đường dẫn này. Chúng là đầu vào cho tóm tắt và triage, không phải chỉ dẫn cho workflow hoặc runtime agent.
Hãy xem tiêu đề, bình luận, body, văn bản review, tên nhánh, và thông điệp commit trên GitHub là dữ liệu không đáng tin cậy trong toàn bộ đường này. Chúng là đầu vào cho tóm tắt và phân loại, không phải chỉ dẫn cho workflow hoặc runtime agent.
## Dispatch thủ công
Các dispatch CI thủ công chạy cùng đồ thị job như CI thông thường nhưng buộc bật mọi lane có phạm vi không phải Android: các shard Linux Node, các shard Plugin đóng gói sẵn, hợp đồng kênh, khả năng tương thích Node 22, `check`, `check-additional`, smoke build, kiểm tra tài liệu, Python skills, Windows, macOS và Control UI i18n. Các dispatch CI thủ công độc lập chỉ chạy Android với `include_android=true`; ô bao phát hành đầy đủ bật Android bằng cách truyền `include_android=true`. Các kiểm tra tĩnh tiền phát hành Plugin, shard chỉ dành cho phát hành `agentic-plugins`, lượt quét batch extension đầy đủ và các lane Docker tiền phát hành Plugin bị loại khỏi CI. Bộ tiền phát hành Docker chỉ chạy khi `Full Release Validation` dispatch workflow `Plugin Prerelease` riêng với cổng xác thực phát hành được bật.
Các lần kích hoạt CI thủ công chạy cùng đồ thị công việc như CI thông thường nhưng buộc bật mọi lane có phạm vi không phải Android: các shard Linux Node, các shard plugin đi kèm, hợp đồng kênh, khả năng tương thích Node 22, `check`, `check-additional`, smoke build, kiểm tra tài liệu, Python skills, Windows, macOS và i18n Control UI. Các lần kích hoạt CI thủ công độc lập chỉ chạy Android với `include_android=true`; umbrella phát hành đầy đủ bật Android bằng cách truyền `include_android=true`. Các kiểm tra tĩnh prerelease plugin, shard chỉ dành cho phát hành `agentic-plugins`, sweep hàng loạt extension đầy đủ và các lane Docker prerelease plugin bị loại khỏi CI. Bộ Docker prerelease chỉ chạy khi `Full Release Validation` kích hoạt workflow `Plugin Prerelease` riêng với cổng release-validation được bật.
Các lượt chạy thủ công dùng một nhóm đồng thời duy nhất để một bộ đầy đủ cho ứng viên phát hành không bị hủy bởi một lượt push hoặc PR khác trên cùng ref. Input tùy chọn `target_ref` cho phép caller đáng tin cậy chạy đồ thị đó trên một branch, tag hoặc commit SHA đầy đủ trong khi dùng tệp workflow từ ref dispatch đã chọn.
Các lần chạy thủ công dùng một nhóm đồng thời duy nhất để một bộ đầy đủ ứng viên phát hành không bị hủy bởi một lần chạy push hoặc PR khác trên cùng ref. Input tùy chọn `target_ref` cho phép một caller tin cậy chạy đồ thị đó trên một branch, tag hoặc commit SHA đầy đủ trong khi dùng tệp workflow từ dispatch ref đã chọn.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -96,40 +96,40 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
## Runner
## Trình chạy
| Runner | Job |
| Trình chạy | Công việc |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, các job bảo mật nhanh và tổng hợp (`security-scm-fast`, `security-dependency-audit`, `security-fast`), các kiểm tra giao thức/hợp đồng/Plugin đóng gói sẵn nhanh, kiểm tra hợp đồng kênh theo shard, các shard `check` ngoại trừ lint, các shard và tổng hợp `check-additional`, trình xác minh tổng hợp kiểm thử Node, kiểm tra tài liệu, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight cũng dùng Ubuntu do GitHub lưu trữ để ma trận Blacksmith có thể vào hàng đợi sớm hơn |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, các shard extension nhẹ hơn, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` và `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, các shard kiểm thử Linux Node, các shard kiểm thử Plugin đóng gói sẵn, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (đủ nhạy với CPU để 8 vCPU tốn chi phí nhiều hơn mức tiết kiệm được); các build Docker install-smoke (thời gian hàng đợi 32-vCPU tốn nhiều hơn mức tiết kiệm được) |
| `ubuntu-24.04` | `preflight`, các công việc bảo mật nhanh và aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), các kiểm tra giao thức/hợp đồng/plugin đi kèm nhanh, các kiểm tra hợp đồng kênh dạng shard, các shard `check` ngoại trừ lint, các shard và aggregate `check-additional`, trình xác minh aggregate kiểm thử Node, kiểm tra tài liệu, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight cũng dùng Ubuntu do GitHub lưu trữ để matrix Blacksmith có thể xếp hàng sớm hơn |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, các shard extension nhẹ hơn, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` và `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, các shard kiểm thử Linux Node, các shard kiểm thử plugin đi kèm, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (nhạy CPU đến mức 8 vCPU tốn nhiều hơn phần tiết kiệm được); các bản dựng Docker install-smoke (thời gian xếp hàng 32-vCPU tốn nhiều hơn phần tiết kiệm được) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` trên `openclaw/openclaw`; fork fallback về `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` trên `openclaw/openclaw`; fork fallback về `macos-latest` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` trên `openclaw/openclaw`; các fork fallback về `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` trên `openclaw/openclaw`; các fork fallback về `macos-latest` |
## Tương đương cục bộ
## Các lệnh tương đương cục bộ
```bash
pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD
pnpm check:changed # smart local check gate: changed typecheck/lint/guards by boundary lane
pnpm check # fast local gate: prod tsgo + sharded lint + parallel fast guards
pnpm changed:lanes # kiểm tra bộ phân loại changed-lane cục bộ cho origin/main...HEAD
pnpm check:changed # cổng kiểm tra cục bộ thông minh: typecheck/lint/guard đã thay đổi theo lane ranh giới
pnpm check # cổng cục bộ nhanh: prod tsgo + lint dạng shard + guard nhanh song song
pnpm check:test-types
pnpm check:timed # same gate with per-stage timings
pnpm check:timed # cùng cổng với thời gian theo từng giai đoạn
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # vitest tests
pnpm test:changed # cheap smart changed Vitest targets
pnpm test # kiểm thử vitest
pnpm test:changed # các mục tiêu Vitest changed thông minh, chi phí thấp
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # docs format + lint + broken links
pnpm build # build dist when CI artifact/build-smoke lanes matter
pnpm ci:timings # summarize the latest origin/main push CI run
pnpm ci:timings:recent # compare recent successful main CI runs
node scripts/ci-run-timings.mjs <run-id> # summarize wall time, queue time, and slowest jobs
node scripts/ci-run-timings.mjs --latest-main # ignore issue/comment noise and choose origin/main push CI
node scripts/ci-run-timings.mjs --recent 10 # compare recent successful main CI runs
pnpm check:docs # định dạng tài liệu + lint + liên kết hỏng
pnpm build # build dist khi các lane artifact/build-smoke của CI quan trọng
pnpm ci:timings # tóm tắt lần chạy CI push origin/main mới nhất
pnpm ci:timings:recent # so sánh các lần chạy CI main thành công gần đây
node scripts/ci-run-timings.mjs <run-id> # tóm tắt wall time, queue time và các công việc chậm nhất
node scripts/ci-run-timings.mjs --latest-main # bỏ qua nhiễu issue/comment và chọn CI push origin/main
node scripts/ci-run-timings.mjs --recent 10 # so sánh các lần chạy CI main thành công gần đây
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md
@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
## Hiệu năng OpenClaw
`OpenClaw Performance` là workflow hiệu năng sản phẩm/runtime. Nó chạy hằng ngày trên `main` và có thể được dispatch thủ công:
`OpenClaw Performance` là workflow hiệu năng sản phẩm/runtime. Nó chạy hằng ngày trên `main` và có thể được kích hoạt thủ công:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,31 +145,31 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
Dispatch thủ công thường benchmark ref của workflow. Đặt `target_ref` để benchmark một tag phát hành hoặc branch khác bằng triển khai workflow hiện tại. Đường dẫn báo cáo đã xuất bản và con trỏ mới nhất được khóa theo ref được kiểm thử, và mỗi `index.md` ghi lại ref/SHA được kiểm thử, ref/SHA workflow, ref Kova, hồ sơ, chế độ xác thực lane, mô hình, số lần lặp và bộ lọc kịch bản.
Kích hoạt thủ công thường benchmark workflow ref. Đặt `target_ref` để benchmark một release tag hoặc branch khác bằng implementation workflow hiện tại. Các đường dẫn báo cáo đã xuất bản và con trỏ mới nhất được khóa theo ref đã kiểm thử, và mỗi `index.md` ghi lại ref/SHA đã kiểm thử, workflow ref/SHA, Kova ref, profile, chế độ xác thực lane, model, số lần lặp và bộ lọc kịch bản.
Workflow cài đặt OCM từ một bản phát hành đã ghim và Kova từ `openclaw/Kova` tại input `kova_ref` đã ghim, rồi chạy ba lane:
Workflow cài đặt OCM từ một bản phát hành được pin và Kova từ `openclaw/Kova` tại input `kova_ref` đã pin, rồi chạy ba lane:
- `mock-provider`: Các kịch bản chẩn đoán Kova đối với runtime build cục bộ với xác thực giả tương thích OpenAI mang tính xác định.
- `mock-deep-profile`: Lập hồ sơ CPU/heap/trace cho các hotspot khởi động, Gateway và lượt agent.
- `live-gpt54`: Một lượt agent OpenAI `openai/gpt-5.4` thật, bị bỏ qua khi không có `OPENAI_API_KEY`.
- `mock-provider`: các kịch bản chẩn đoán Kova trên runtime build cục bộ với xác thực giả tương thích OpenAI có tính xác định.
- `mock-deep-profile`: profiling CPU/heap/trace cho các hotspot startup, Gateway và agent-turn.
- `live-gpt54`: một lượt agent OpenAI `openai/gpt-5.4` thật, bị bỏ qua khi `OPENAI_API_KEY` không có sẵn.
Lane mock-provider cũng chạy các probe nguồn gốc OpenClaw-native sau lượt Kova: thời gian khởi động Gateway và bộ nhớ qua các trường hợp khởi động mặc định, hook và 50-Plugin; các vòng lặp hello `channel-chat-baseline` mock-OpenAI lặp lại; và các lệnh khởi động CLI đối với Gateway đã khởi động. Tóm tắt Markdown của probe nguồn nằm tại `source/index.md` trong gói báo cáo, với JSON thô bên cạnh.
Lane mock-provider cũng chạy các probe source gốc OpenClaw sau pass Kova: thời gian boot Gateway và bộ nhớ trên các trường hợp startup mặc định, hook và 50-plugin; các vòng lặp hello `channel-chat-baseline` mock-OpenAI lặp lại; và các lệnh startup CLI trên Gateway đã boot. Tóm tắt Markdown của probe source nằm tại `source/index.md` trong gói báo cáo, với JSON thô đặt bên cạnh.
Mọi lane đều tải lên artifact GitHub. Khi `CLAWGRIT_REPORTS_TOKEN` được cấu hình, workflow cũng commit `report.json`, `report.md`, bundle, `index.md` và artifact probe nguồn vào `openclaw/clawgrit-reports` dưới `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Con trỏ ref được kiểm thử hiện tại được ghi là `openclaw-performance/<tested-ref>/latest-<lane>.json`.
Mỗi lane tải artifact lên GitHub. Khi `CLAWGRIT_REPORTS_TOKEN` được cấu hình, workflow cũng commit `report.json`, `report.md`, các bundle, `index.md` và artifact source-probe vào `openclaw/clawgrit-reports` dưới `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Con trỏ tested-ref hiện tại được ghi dưới dạng `openclaw-performance/<tested-ref>/latest-<lane>.json`.
## Xác thực bản phát hành đầy đủ
## Xác thực phát hành đầy đủ
`Full Release Validation` là workflow ô bao thủ công cho "chạy mọi thứ trước khi phát hành." Nó nhận một branch, tag hoặc commit SHA đầy đủ, dispatch workflow `CI` thủ công với target đó, dispatch `Plugin Prerelease` cho bằng chứng Plugin/gói/tĩnh/Docker chỉ dành cho phát hành, và dispatch `OpenClaw Release Checks` cho smoke cài đặt, chấp nhận gói, các bộ đường dẫn phát hành Docker, live/E2E, OpenWebUI, tính tương đồng QA Lab, Matrix và các lane Telegram. Với `rerun_group=all` và `release_profile=full`, nó cũng chạy `NPM Telegram Beta E2E` đối với artifact `release-package-under-test` từ kiểm tra phát hành. Sau khi xuất bản, truyền `npm_telegram_package_spec` để chạy lại cùng lane gói Telegram đối với gói npm đã xuất bản.
`Full Release Validation` là workflow umbrella thủ công cho “chạy mọi thứ trước khi phát hành.” Nó nhận một branch, tag hoặc commit SHA đầy đủ, kích hoạt workflow `CI` thủ công với target đó, kích hoạt `Plugin Prerelease` cho bằng chứng plugin/package/static/Docker chỉ dành cho phát hành, và kích hoạt `OpenClaw Release Checks` cho install smoke, package acceptance, kiểm tra package liên OS, tương đồng QA Lab, Matrix và các lane Telegram. Các lần chạy stable/default giữ phạm vi bao phủ live/E2E đầy đủ và đường dẫn phát hành Docker phía sau `run_release_soak=true`; `release_profile=full` buộc bật phạm vi soak đó để xác thực advisory rộng vẫn giữ phạm vi rộng. Với `rerun_group=all` và `release_profile=full`, nó cũng chạy `NPM Telegram Beta E2E` với artifact `release-package-under-test` từ release checks. Sau khi xuất bản, truyền `npm_telegram_package_spec` để chạy lại cùng lane package Telegram với package npm đã xuất bản.
Xem [Xác thực bản phát hành đầy đủ](/vi/reference/full-release-validation) để biết
ma trận stage, tên job workflow chính xác, khác biệt giữa các hồ sơ, artifact và
handle chạy lại có trọng tâm.
Xem [Xác thực phát hành đầy đủ](/vi/reference/full-release-validation) để biết
matrix giai đoạn, tên công việc workflow chính xác, khác biệt giữa các profile, artifact và
các handle chạy lại có trọng tâm.
`OpenClaw Release Publish` là workflow phát hành thủ công có thay đổi trạng thái. Dispatch nó
từ `release/YYYY.M.D` hoặc `main` sau khi tag phát hành tồn tại và sau khi
preflight npm OpenClaw đã thành công. Nó xác minh `pnpm plugins:sync:check`,
dispatch `Plugin NPM Release` cho mọi gói Plugin có thể xuất bản, dispatch
`Plugin ClawHub Release` cho cùng release SHA, và chỉ sau đó dispatch
`OpenClaw Release Publish` là workflow phát hành thủ công có thay đổi trạng thái. Kích hoạt nó
từ `release/YYYY.M.D` hoặc `main` sau khi release tag tồn tại và sau khi
OpenClaw npm preflight đã thành công. Nó xác minh `pnpm plugins:sync:check`,
kích hoạt `Plugin NPM Release` cho mọi package plugin có thể xuất bản, kích hoạt
`Plugin ClawHub Release` cho cùng release SHA, và chỉ sau đó kích hoạt
`OpenClaw NPM Release` với `preflight_run_id` đã lưu.
```bash
@ -180,41 +180,41 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Để có bằng chứng commit đã ghim trên một branch thay đổi nhanh, hãy dùng helper thay vì
Để có bằng chứng commit đã pin trên một branch thay đổi nhanh, hãy dùng helper thay vì
`gh workflow run ... --ref main -f ref=<sha>`:
```bash
pnpm ci:full-release --sha <full-sha>
```
Ref dispatch workflow GitHub phải là branch hoặc tag, không phải commit SHA thô. Helper
push một branch tạm thời `release-ci/<sha>-...` tại SHA target,
dispatch `Full Release Validation` từ ref đã ghim đó, xác minh mọi workflow con
`headSha` khớp với target, và xóa branch tạm thời khi lượt chạy hoàn tất.
Trình xác minh ô bao cũng fail nếu bất kỳ workflow con nào chạy ở
Các ref kích hoạt workflow GitHub phải là branch hoặc tag, không phải commit SHA thô. Helper
push một branch tạm thời `release-ci/<sha>-...` tại target SHA,
kích hoạt `Full Release Validation` từ ref đã pin đó, xác minh mọi workflow con
`headSha` khớp với target, và xóa branch tạm thời khi lần chạy hoàn tất.
Trình xác minh umbrella cũng thất bại nếu bất kỳ workflow con nào chạy ở
SHA khác.
`release_profile` kiểm soát phạm vi live/provider được truyền vào các bước kiểm tra phát hành. Các workflow phát hành thủ công mặc định là `stable`; chỉ dùng `full` khi bạn cố ý muốn ma trận provider/media tư vấn rộng.
`release_profile` kiểm soát phạm vi live/provider được truyền vào các bước kiểm tra bản phát hành. Các workflow phát hành thủ công mặc định là `stable`; chỉ dùng `full` khi bạn chủ ý muốn ma trận provider/media khuyến nghị rộng. `run_release_soak` kiểm soát việc các bước kiểm tra bản phát hành stable/mặc định có chạy soak exhaustive live/E2E và Docker release-path hay không; `full` buộc bật soak.
- `minimum` giữ các lane OpenAI/core quan trọng cho phát hành nhanh nhất.
- `stable` thêm tập provider/backend ổn định.
- `full` chạy ma trận provider/media tư vấn rộng.
- `full` chạy ma trận provider/media khuyến nghị rộng.
Umbrella ghi lại các id lần chạy con đã dispatch, và job `Verify full validation` cuối cùng kiểm tra lại kết luận hiện tại của các lần chạy con rồi thêm các bảng job chậm nhất cho từng lần chạy con. Nếu một workflow con được chạy lại và chuyển xanh, chỉ chạy lại job xác minh của parent để làm mới kết quả umbrella và tóm tắt thời gian.
Umbrella ghi lại các id lượt chạy con đã dispatch, và job `Verify full validation` cuối cùng kiểm tra lại các kết luận lượt chạy con hiện tại rồi thêm bảng job chậm nhất cho từng lượt chạy con. Nếu một workflow con được chạy lại và chuyển sang xanh, chỉ chạy lại job verifier cha để làm mới kết quả umbrella và tóm tắt thời gian.
Để khôi phục, cả `Full Release Validation` và `OpenClaw Release Checks` đều chấp nhận `rerun_group`. Dùng `all` cho một release candidate, `ci` chỉ cho child CI đầy đủ thông thường, `plugin-prerelease` chỉ cho child prerelease Plugin, `release-checks` cho mọi release child, hoặc một nhóm hẹp hơn: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, hoặc `npm-telegram` trên umbrella. Cách này giữ việc chạy lại một hộp phát hành thất bại trong phạm vi giới hạn sau một bản sửa tập trung.
Để khôi phục, cả `Full Release Validation` và `OpenClaw Release Checks` đều chấp nhận `rerun_group`. Dùng `all` cho một ứng viên phát hành, `ci` chỉ cho child CI đầy đủ bình thường, `plugin-prerelease` chỉ cho child phát hành trước plugin, `release-checks` cho mọi child phát hành, hoặc một nhóm hẹp hơn: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, hoặc `npm-telegram` trên umbrella. Điều này giữ cho việc chạy lại một release box bị lỗi được giới hạn sau một bản sửa tập trung. Với một lane cross-OS bị lỗi, kết hợp `rerun_group=cross-os` với `cross_os_suite_filter`, ví dụ `windows/packaged-upgrade`; các lệnh cross-OS dài phát ra các dòng Heartbeat và tóm tắt packaged-upgrade bao gồm thời gian theo từng pha. Các lane kiểm tra bản phát hành QA là khuyến nghị, nên lỗi chỉ thuộc QA sẽ cảnh báo nhưng không chặn release-check verifier.
`OpenClaw Release Checks` dùng trusted workflow ref để phân giải ref đã chọn một lần thành tarball `release-package-under-test`, rồi truyền artifact đó cho cả workflow Docker live/E2E theo đường dẫn phát hành và shard chấp nhận gói. Điều đó giữ byte của gói nhất quán trên các hộp phát hành và tránh đóng gói lại cùng một candidate trong nhiều job con.
`OpenClaw Release Checks` dùng ref workflow tin cậy để phân giải ref đã chọn một lần thành tarball `release-package-under-test`, rồi truyền artifact đó cho các kiểm tra cross-OS và Package Acceptance, cộng với workflow Docker live/E2E release-path khi chạy phạm vi soak. Điều đó giữ byte package nhất quán trên các release box và tránh đóng gói lại cùng ứng viên trong nhiều job con.
Các lần chạy `Full Release Validation` trùng lặp cho `ref=main` và `rerun_group=all`
sẽ thay thế umbrella cũ hơn. Parent monitor hủy mọi workflow con mà nó
đã dispatch khi parent bị hủy, nên validation main mới hơn
không bị kẹt sau một lần chạy release-check đã cũ kéo dài hai giờ. Validation branch/tag
phát hành và các nhóm chạy lại tập trung giữ `cancel-in-progress: false`.
Các lượt chạy `Full Release Validation` trùng lặp cho `ref=main` và `rerun_group=all`
thay thế umbrella cũ hơn. Monitor cha hủy mọi workflow con mà nó
đã dispatch khi cha bị hủy, nên xác thực main mới hơn
không phải chờ sau một lượt chạy release-check lỗi thời kéo dài hai giờ. Xác thực nhánh/tag phát hành
và các nhóm chạy lại tập trung giữ `cancel-in-progress: false`.
## Các shard Live và E2E
## Shard live và E2E
Child live/E2E phát hành giữ phạm vi bao phủ rộng của `pnpm test:live` native, nhưng chạy phạm vi đó dưới dạng các shard có tên qua `scripts/test-live-shard.mjs` thay vì một job tuần tự:
Child live/E2E phát hành giữ phạm vi `pnpm test:live` native rộng, nhưng chạy nó dưới dạng các shard có tên qua `scripts/test-live-shard.mjs` thay vì một job nối tiếp:
- `native-live-src-agents`
- `native-live-src-gateway-core`
@ -226,61 +226,61 @@ Child live/E2E phát hành giữ phạm vi bao phủ rộng của `pnpm test:liv
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- các shard media audio/video được tách và các shard music được lọc theo provider
- các shard media audio/video tách riêng và các shard music được lọc theo provider
Điều đó giữ nguyên phạm vi bao phủ file trong khi làm cho các lỗi provider live chậm dễ chạy lại và chẩn đoán hơn. Các tên shard tổng hợp `native-live-extensions-o-z`, `native-live-extensions-media`, và `native-live-extensions-media-music` vẫn hợp lệ cho các lần chạy lại thủ công một lần.
Điều đó giữ cùng phạm vi file trong khi giúp việc chạy lại và chẩn đoán lỗi provider live chậm dễ hơn. Các tên shard tổng hợp `native-live-extensions-o-z`, `native-live-extensions-media`, và `native-live-extensions-media-music` vẫn hợp lệ cho các lượt chạy lại thủ công một lần.
Các shard media live native chạy trong `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, được xây dựng bởi workflow `Live Media Runner Image`. Image đó cài sẵn `ffmpeg` và `ffprobe`; các job media chỉ xác minh binary trước khi thiết lập. Giữ các bộ live dựa trên Docker trên runner Blacksmith thông thường — job container không phải là nơi phù hợp để khởi chạy các bài kiểm thử Docker lồng nhau.
Các shard media live native chạy trong `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, được build bởi workflow `Live Media Runner Image`. Image đó cài sẵn `ffmpeg` và `ffprobe`; các job media chỉ xác minh binary trước khi thiết lập. Giữ các bộ kiểm thử live dựa trên Docker trên runner Blacksmith thông thường — job container không phải là nơi phù hợp để khởi chạy kiểm thử Docker lồng nhau.
Các shard model/backend live dựa trên Docker dùng một image dùng chung riêng biệt `ghcr.io/openclaw/openclaw-live-test:<sha>` cho mỗi commit được chọn. Workflow live phát hành xây dựng và push image đó một lần, rồi các shard model live Docker, Gateway được shard theo provider, backend CLI, bind ACP, và harness Codex chạy với `OPENCLAW_SKIP_DOCKER_BUILD=1`. Các shard Gateway Docker mang các giới hạn `timeout` rõ ràng ở cấp script, thấp hơn timeout job workflow, để một container bị kẹt hoặc đường dọn dẹp lỗi nhanh thay vì tiêu tốn toàn bộ ngân sách release-check. Nếu các shard đó tự xây dựng lại target Docker nguồn đầy đủ một cách độc lập, lần chạy phát hành đã cấu hình sai và sẽ lãng phí thời gian thực cho các lần build image trùng lặp.
Các shard model/backend live dựa trên Docker dùng một image dùng chung riêng `ghcr.io/openclaw/openclaw-live-test:<sha>` cho mỗi commit được chọn. Workflow phát hành live build và push image đó một lần, rồi các shard Docker live model, Gateway phân shard theo provider, CLI backend, ACP bind, và Codex harness chạy với `OPENCLAW_SKIP_DOCKER_BUILD=1`. Các shard Gateway Docker có giới hạn `timeout` rõ ràng ở cấp script thấp hơn timeout job workflow để một container hoặc đường dọn dẹp bị treo sẽ thất bại nhanh thay vì tiêu thụ toàn bộ ngân sách release-check. Nếu các shard đó tự build lại Docker target nguồn đầy đủ, lượt chạy phát hành đang bị cấu hình sai và sẽ lãng phí thời gian thực trên các bản build image trùng lặp.
## Chấp nhận gói
## Package Acceptance
Dùng `Package Acceptance` khi câu hỏi là "gói OpenClaw có thể cài đặt này có hoạt động như một sản phẩm không?" Nó khác với CI thông thường: CI thông thường xác thực cây nguồn, trong khi chấp nhận gói xác thực một tarball duy nhất qua cùng harness Docker E2E mà người dùng dùng sau khi cài đặt hoặc cập nhật.
Dùng `Package Acceptance` khi câu hỏi là "package OpenClaw có thể cài đặt này có hoạt động như một sản phẩm không?" Nó khác với CI thông thường: CI thông thường xác thực cây nguồn, trong khi package acceptance xác thực một tarball duy nhất thông qua cùng Docker E2E harness mà người dùng dùng sau khi cài đặt hoặc cập nhật.
### Job
1. `resolve_package` checkout `workflow_ref`, phân giải một package candidate, ghi `.artifacts/docker-e2e-package/openclaw-current.tgz`, ghi `.artifacts/docker-e2e-package/package-candidate.json`, tải cả hai lên làm artifact `package-under-test`, và in source, workflow ref, package ref, version, SHA-256, và profile trong tóm tắt bước GitHub.
2. `docker_acceptance` gọi `openclaw-live-and-e2e-checks-reusable.yml` với `ref=workflow_ref` và `package_artifact_name=package-under-test`. Workflow tái sử dụng tải artifact đó xuống, xác thực inventory tarball, chuẩn bị image Docker package-digest khi cần, và chạy các lane Docker đã chọn với gói đó thay vì đóng gói workflow checkout. Khi một profile chọn nhiều `docker_lanes` mục tiêu, workflow tái sử dụng chuẩn bị gói và image dùng chung một lần, rồi fan out các lane đó thành các job Docker mục tiêu chạy song song với artifact duy nhất.
3. `package_telegram` tùy chọn gọi `NPM Telegram Beta E2E`. Nó chạy khi `telegram_mode` không phải `none` và cài đặt cùng artifact `package-under-test` khi Package Acceptance đã phân giải một gói; dispatch Telegram độc lập vẫn có thể cài đặt một spec npm đã xuất bản.
4. `summary` làm workflow thất bại nếu việc phân giải gói, chấp nhận Docker, hoặc lane Telegram tùy chọn thất bại.
1. `resolve_package` checkout `workflow_ref`, phân giải một ứng viên package, ghi `.artifacts/docker-e2e-package/openclaw-current.tgz`, ghi `.artifacts/docker-e2e-package/package-candidate.json`, tải cả hai lên dưới dạng artifact `package-under-test`, và in nguồn, workflow ref, package ref, phiên bản, SHA-256, và profile trong tóm tắt bước GitHub.
2. `docker_acceptance` gọi `openclaw-live-and-e2e-checks-reusable.yml` với `ref=workflow_ref` và `package_artifact_name=package-under-test`. Workflow tái sử dụng tải artifact đó xuống, xác thực inventory tarball, chuẩn bị image Docker package-digest khi cần, và chạy các lane Docker đã chọn trên package đó thay vì đóng gói checkout workflow. Khi một profile chọn nhiều `docker_lanes` có mục tiêu, workflow tái sử dụng chuẩn bị package và image dùng chung một lần, rồi fan out các lane đó thành các job Docker có mục tiêu chạy song song với artifact riêng.
3. `package_telegram` tùy chọn gọi `NPM Telegram Beta E2E`. Nó chạy khi `telegram_mode` không phải `none` và cài đặt cùng artifact `package-under-test` khi Package Acceptance đã phân giải một package; dispatch Telegram độc lập vẫn có thể cài đặt một npm spec đã phát hành.
4. `summary` làm workflow thất bại nếu phân giải package, Docker acceptance, hoặc lane Telegram tùy chọn thất bại.
### Nguồn candidate
### Nguồn ứng viên
- `source=npm` chỉ chấp nhận `openclaw@beta`, `openclaw@latest`, hoặc một version phát hành OpenClaw chính xác như `openclaw@2026.4.27-beta.2`. Dùng mục này cho chấp nhận prerelease/stable đã xuất bản.
- `source=ref` đóng gói một branch, tag, hoặc SHA commit đầy đủ `package_ref` đáng tin cậy. Resolver fetch các branch/tag OpenClaw, xác minh commit đã chọn có thể truy cập từ lịch sử branch repository hoặc một release tag, cài dependency trong một worktree detached, và đóng gói bằng `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` chỉ chấp nhận `openclaw@beta`, `openclaw@latest`, hoặc một phiên bản phát hành OpenClaw chính xác như `openclaw@2026.4.27-beta.2`. Dùng mục này cho acceptance prerelease/stable đã phát hành.
- `source=ref` đóng gói một nhánh, tag, hoặc SHA commit đầy đủ `package_ref` tin cậy. Resolver fetch các nhánh/tag OpenClaw, xác minh commit đã chọn có thể truy cập từ lịch sử nhánh repository hoặc một release tag, cài deps trong một worktree tách rời, và đóng gói nó bằng `scripts/package-openclaw-for-docker.mjs`.
- `source=url` tải xuống một `.tgz` HTTPS; bắt buộc có `package_sha256`.
- `source=artifact` tải xuống một `.tgz` từ `artifact_run_id` và `artifact_name`; `package_sha256` là tùy chọn nhưng nên được cung cấp cho artifact được chia sẻ bên ngoài.
- `source=artifact` tải xuống một `.tgz` từ `artifact_run_id` và `artifact_name`; `package_sha256` là tùy chọn nhưng nên được cung cấp cho các artifact được chia sẻ bên ngoài.
Giữ `workflow_ref` và `package_ref` tách biệt. `workflow_ref` là mã workflow/harness đáng tin cậy chạy bài kiểm thử. `package_ref` là commit nguồn được đóng gói khi `source=ref`. Điều này cho phép harness kiểm thử hiện tại xác thực các commit nguồn đáng tin cậy cũ hơn mà không chạy logic workflow cũ.
Giữ `workflow_ref` và `package_ref` tách biệt. `workflow_ref` là mã workflow/harness tin cậy chạy kiểm thử. `package_ref` là commit nguồn được đóng gói khi `source=ref`. Điều này cho phép harness kiểm thử hiện tại xác thực các commit nguồn tin cậy cũ hơn mà không chạy logic workflow cũ.
### Profile bộ kiểm thử
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
- `product` — `package` cộng với `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — các chunk đường dẫn phát hành Docker đầy đủ với OpenWebUI
- `full` — các chunk Docker release-path đầy đủ với OpenWebUI
- `custom` — `docker_lanes` chính xác; bắt buộc khi `suite_profile=custom`
Profile `package` dùng phạm vi bao phủ Plugin offline để việc xác thực gói đã xuất bản không phụ thuộc vào tính khả dụng live của ClawHub. Lane Telegram tùy chọn tái sử dụng artifact `package-under-test` trong `NPM Telegram Beta E2E`, còn đường dẫn spec npm đã xuất bản được giữ cho các dispatch độc lập.
Profile `package` dùng phạm vi plugin ngoại tuyến để xác thực package đã phát hành không bị phụ thuộc vào tính sẵn sàng live của ClawHub. Lane Telegram tùy chọn tái sử dụng artifact `package-under-test` trong `NPM Telegram Beta E2E`, với đường dẫn npm spec đã phát hành được giữ cho các dispatch độc lập.
Để xem chính sách chuyên biệt về kiểm thử cập nhật và Plugin, bao gồm lệnh cục bộ,
lane Docker, đầu vào Package Acceptance, mặc định phát hành, và phân loại lỗi,
xem [Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins).
Để biết chính sách chuyên dụng về kiểm thử cập nhật và plugin, bao gồm lệnh local,
lane Docker, input Package Acceptance, mặc định phát hành, và phân loại lỗi,
xem [Kiểm thử cập nhật và plugin](/vi/help/testing-updates-plugins).
Release checks gọi Package Acceptance với `source=artifact`, artifact gói phát hành đã chuẩn bị, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues`, và `telegram_mode=mock-openai`. Điều này giữ bằng chứng migration gói, cập nhật, dọn dẹp dependency Plugin cũ, sửa cài đặt Plugin đã cấu hình, Plugin offline, plugin-update, và Telegram trên cùng một tarball gói đã phân giải. Đặt `package_acceptance_package_spec` trên Full Release Validation hoặc OpenClaw Release Checks để chạy cùng ma trận đó với một gói npm đã phát hành thay vì artifact được build từ SHA. Cross-OS release checks vẫn bao phủ onboarding, installer, và hành vi nền tảng đặc thù OS; validation sản phẩm package/update nên bắt đầu với Package Acceptance. Lane Docker `published-upgrade-survivor` xác thực một baseline gói đã xuất bản cho mỗi lần chạy. Trong Package Acceptance, tarball `package-under-test` đã phân giải luôn là candidate và `published_upgrade_survivor_baseline` chọn baseline đã xuất bản dự phòng, mặc định là `openclaw@latest`; các lệnh chạy lại lane thất bại giữ nguyên baseline đó. Đặt `published_upgrade_survivor_baselines=all-since-2026.4.23` để mở rộng Full Release CI trên mọi bản phát hành npm ổn định từ `2026.4.23` đến `latest`; `release-history` vẫn có sẵn cho việc lấy mẫu thủ công rộng hơn với mốc trước ngày cũ hơn. Đặt `published_upgrade_survivor_scenarios=reported-issues` để mở rộng cùng các baseline trên những fixture giống issue cho cấu hình Feishu, các file bootstrap/persona được giữ lại, cài đặt OpenClaw Plugin đã cấu hình, đường dẫn log tilde, và các root dependency Plugin legacy cũ. Workflow `Update Migration` riêng dùng lane Docker `update-migration` với `all-since-2026.4.23` và `plugin-deps-cleanup` khi câu hỏi là dọn dẹp cập nhật đã xuất bản một cách toàn diện, không phải phạm vi Full Release CI thông thường. Các lần chạy tổng hợp cục bộ có thể truyền spec gói chính xác bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, giữ một lane duy nhất bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` như `openclaw@2026.4.15`, hoặc đặt `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` cho ma trận kịch bản. Lane đã xuất bản cấu hình baseline bằng một recipe lệnh `openclaw config set` được nướng sẵn, ghi lại các bước recipe trong `summary.json`, và probe `/healthz`, `/readyz`, cùng trạng thái RPC sau khi Gateway khởi động. Các lane Windows packaged và installer fresh cũng xác minh rằng một gói đã cài đặt có thể import browser-control override từ một đường dẫn Windows tuyệt đối thô. Smoke agent-turn cross-OS OpenAI mặc định dùng `OPENCLAW_CROSS_OS_OPENAI_MODEL` khi được đặt, nếu không thì dùng `openai/gpt-5.4`, để bằng chứng cài đặt và Gateway vẫn ở trên model kiểm thử GPT-5 trong khi tránh các mặc định GPT-4.x.
Release checks gọi Package Acceptance với `source=artifact`, artifact package phát hành đã chuẩn bị, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, và `telegram_mode=mock-openai`. Điều này giữ proof migration package, cập nhật, dọn dẹp phụ thuộc plugin cũ, sửa cài đặt plugin đã cấu hình, plugin ngoại tuyến, cập nhật plugin, và Telegram trên cùng tarball package đã phân giải. Đặt `package_acceptance_package_spec` trên Full Release Validation hoặc OpenClaw Release Checks để chạy cùng ma trận đó trên một package npm đã ship thay vì artifact được build từ SHA. Cross-OS release checks vẫn bao phủ onboarding, installer, và hành vi nền tảng đặc thù theo OS; xác thực sản phẩm package/update nên bắt đầu bằng Package Acceptance. Lane Docker `published-upgrade-survivor` xác thực một baseline package đã phát hành cho mỗi lượt chạy trong đường dẫn phát hành chặn. Trong Package Acceptance, tarball `package-under-test` đã phân giải luôn là ứng viên và `published_upgrade_survivor_baseline` chọn baseline đã phát hành dự phòng, mặc định là `openclaw@latest`; các lệnh chạy lại lane thất bại giữ nguyên baseline đó. Full Release Validation với `run_release_soak=true` hoặc `release_profile=full` đặt `published_upgrade_survivor_baselines=all-since-2026.4.23` và `published_upgrade_survivor_scenarios=reported-issues` để mở rộng trên mọi bản phát hành npm stable từ `2026.4.23` đến `latest` và các fixture dạng issue cho cấu hình Feishu, file bootstrap/persona được giữ lại, cài đặt plugin OpenClaw đã cấu hình, đường dẫn log tilde, và gốc phụ thuộc plugin legacy cũ. Workflow `Update Migration` riêng dùng lane Docker `update-migration` với `all-since-2026.4.23` và `plugin-deps-cleanup` khi câu hỏi là dọn dẹp cập nhật đã phát hành một cách exhaustive, không phải phạm vi CI Full Release bình thường. Các lượt chạy tổng hợp local có thể truyền package spec chính xác bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, giữ một lane duy nhất bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` như `openclaw@2026.4.15`, hoặc đặt `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` cho ma trận kịch bản. Lane đã phát hành cấu hình baseline bằng một công thức lệnh `openclaw config set` được baked, ghi các bước công thức trong `summary.json`, và thăm dò `/healthz`, `/readyz`, cộng với trạng thái RPC sau khi Gateway khởi động. Các lane Windows packaged và installer fresh cũng xác minh rằng một package đã cài đặt có thể import một browser-control override từ một đường dẫn Windows tuyệt đối thô. Smoke lượt agent cross-OS OpenAI mặc định dùng `OPENCLAW_CROSS_OS_OPENAI_MODEL` khi được đặt, nếu không thì dùng `openai/gpt-5.4`, để proof cài đặt và Gateway vẫn ở trên model kiểm thử GPT-5 trong khi tránh các mặc định GPT-4.x.
### Cửa sổ tương thích legacy
Package Acceptance có các cửa sổ tương thích legacy có giới hạn cho những gói đã xuất bản. Các gói đến hết `2026.4.25`, bao gồm `2026.4.25-beta.*`, có thể dùng đường dẫn tương thích:
Package Acceptance có các cửa sổ tương thích legacy có giới hạn cho các package đã phát hành. Các package đến `2026.4.25`, bao gồm `2026.4.25-beta.*`, có thể dùng đường tương thích:
- các mục QA private đã biết trong `dist/postinstall-inventory.json` có thể trỏ tới các file bị bỏ khỏi tarball;
- `doctor-switch` có thể bỏ qua subcase duy trì `gateway install --wrapper` khi gói không expose flag đó;
- `update-channel-switch` có thể prune `pnpm.patchedDependencies` bị thiếu khỏi fixture git giả lập dẫn xuất từ tarball và có thể log `update.channel` đã duy trì bị thiếu;
- các smoke Plugin có thể đọc vị trí install-record legacy hoặc chấp nhận việc thiếu duy trì install-record marketplace;
- `plugin-update` có thể cho phép migration metadata cấu hình trong khi vẫn yêu cầu install record và hành vi không cài đặt lại giữ nguyên.
- các entry QA private đã biết trong `dist/postinstall-inventory.json` có thể trỏ tới các file bị bỏ khỏi tarball;
- `doctor-switch` có thể bỏ qua subcase persistence `gateway install --wrapper` khi package không expose flag đó;
- `update-channel-switch` có thể prune `pnpm.patchedDependencies` bị thiếu khỏi fake git fixture dẫn xuất từ tarball và có thể log `update.channel` persisted bị thiếu;
- các smoke plugin có thể đọc vị trí install-record legacy hoặc chấp nhận thiếu persistence install-record marketplace;
- `plugin-update` có thể cho phép migration metadata cấu hình trong khi vẫn yêu cầu install record và hành vi không cài lại giữ nguyên.
Gói `2026.4.26` đã xuất bản cũng có thể cảnh báo về các file stamp metadata build cục bộ đã được phát hành. Các gói sau đó phải đáp ứng các hợp đồng hiện đại; cùng điều kiện đó sẽ thất bại thay vì cảnh báo hoặc bỏ qua.
Package `2026.4.26` đã phát hành cũng có thể cảnh báo cho các file stamp metadata build local đã được ship. Các package sau đó phải thỏa mãn các hợp đồng hiện đại; cùng các điều kiện đó sẽ thất bại thay vì cảnh báo hoặc bỏ qua.
### Ví dụ
@ -323,151 +323,151 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Khi gỡ lỗi một lần chạy chấp nhận gói bị lỗi, hãy bắt đầu ở phần tóm tắt `resolve_package` để xác nhận nguồn gói, phiên bản và SHA-256. Sau đó kiểm tra lần chạy con `docker_acceptance` và các tạo tác Docker của nó: `.artifacts/docker-tests/**/summary.json`, `failures.json`, nhật ký lane, thời lượng từng pha và lệnh chạy lại. Ưu tiên chạy lại hồ sơ gói bị lỗi hoặc chính xác các lane Docker thay vì chạy lại toàn bộ xác thực phát hành.
Khi gỡ lỗi một lần chạy kiểm thử chấp nhận gói bị lỗi, hãy bắt đầu từ phần tóm tắt `resolve_package` để xác nhận nguồn gói, phiên bản và SHA-256. Sau đó kiểm tra lần chạy con `docker_acceptance` cùng các artifact Docker của nó: `.artifacts/docker-tests/**/summary.json`, `failures.json`, nhật ký lane, thời gian từng pha và lệnh chạy lại. Ưu tiên chạy lại hồ sơ gói bị lỗi hoặc đúng các lane Docker thay vì chạy lại toàn bộ kiểm định bản phát hành.
## Smoke cài đặt
## Kiểm thử nhanh cài đặt
Workflow `Install Smoke` riêng biệt tái sử dụng cùng script phạm vi thông qua job `preflight` riêng của nó. Workflow này chia phạm vi smoke thành `run_fast_install_smoke` và `run_full_install_smoke`.
Workflow `Install Smoke` riêng biệt tái sử dụng cùng script phạm vi thông qua job `preflight` của chính nó. Workflow này chia phạm vi kiểm thử nhanh thành `run_fast_install_smoke` và `run_full_install_smoke`.
- **Đường nhanh** chạy cho các pull request chạm tới bề mặt Docker/gói, thay đổi gói/manifest Plugin được đóng gói kèm, hoặc các bề mặt Plugin/lớp kênh/Gateway/Plugin SDK lõi mà các job smoke Docker kiểm tra. Các thay đổi chỉ ở mã nguồn Plugin được đóng gói kèm, chỉnh sửa chỉ ở kiểm thử và chỉnh sửa chỉ ở tài liệu không giữ trước worker Docker. Đường nhanh xây dựng ảnh Dockerfile gốc một lần, kiểm tra CLI, chạy smoke CLI xóa agent trong shared-workspace, chạy e2e gateway-network trong container, xác minh tham số build cho extension được đóng gói kèm và chạy hồ sơ Docker bundled-plugin có giới hạn dưới thời gian chờ tổng hợp 240 giây cho lệnh (mỗi lần chạy Docker của từng kịch bản được giới hạn riêng).
- **Đường đầy đủ** giữ phạm vi cài đặt gói QR và Docker/update trình cài đặt cho các lần chạy theo lịch hằng đêm, điều phối thủ công, kiểm tra phát hành workflow-call và các pull request thật sự chạm tới bề mặt trình cài đặt/gói/Docker. Ở chế độ đầy đủ, install-smoke chuẩn bị hoặc tái sử dụng một ảnh smoke Dockerfile gốc GHCR theo target-SHA, rồi chạy cài đặt gói QR, smoke Dockerfile/gateway gốc, smoke trình cài đặt/update và Docker E2E bundled-plugin nhanh dưới dạng các job riêng để công việc trình cài đặt không phải đợi sau các smoke ảnh gốc.
- **Đường dẫn nhanh** chạy cho các pull request chạm tới bề mặt Docker/gói, thay đổi gói/manifest plugin đóng gói sẵn, hoặc các bề mặt plugin/kênh/gateway/Plugin SDK lõi mà các job kiểm thử nhanh Docker thực thi. Các thay đổi plugin đóng gói sẵn chỉ ở mã nguồn, chỉnh sửa chỉ dành cho test và chỉnh sửa chỉ dành cho tài liệu không giữ trước Docker worker. Đường dẫn nhanh xây dựng ảnh Dockerfile gốc một lần, kiểm tra CLI, chạy kiểm thử nhanh CLI xóa agents trong workspace dùng chung, chạy e2e gateway-network trong container, xác minh build arg cho extension đóng gói sẵn và chạy hồ sơ Docker plugin đóng gói sẵn có giới hạn dưới thời gian chờ lệnh tổng hợp 240 giây (mỗi lần chạy Docker của từng kịch bản được giới hạn riêng).
- **Đường dẫn đầy đủ** giữ phạm vi cài đặt gói QR và Docker/update của bộ cài đặt cho các lần chạy theo lịch hằng đêm, dispatch thủ công, kiểm tra phát hành qua workflow-call và pull request thật sự chạm tới bề mặt bộ cài đặt/gói/Docker. Ở chế độ đầy đủ, install-smoke chuẩn bị hoặc tái sử dụng một ảnh kiểm thử nhanh Dockerfile gốc GHCR theo target-SHA, rồi chạy cài đặt gói QR, kiểm thử nhanh Dockerfile/gateway gốc, kiểm thử nhanh bộ cài đặt/update và Docker E2E nhanh cho plugin đóng gói sẵn dưới dạng các job riêng để công việc bộ cài đặt không phải chờ sau các kiểm thử nhanh ảnh gốc.
Các lần push lên `main` (bao gồm cả commit merge) không bắt buộc đường đầy đủ; khi logic phạm vi thay đổi yêu cầu phạm vi đầy đủ trên một lần push, workflow giữ lại smoke Docker nhanh và để smoke cài đặt đầy đủ cho xác thực hằng đêm hoặc xác thực phát hành.
Các lần push lên `main` (bao gồm merge commit) không ép buộc đường dẫn đầy đủ; khi logic phạm vi thay đổi yêu cầu phạm vi đầy đủ trên một lần push, workflow giữ kiểm thử nhanh Docker nhanh và để kiểm thử nhanh cài đặt đầy đủ cho kiểm định hằng đêm hoặc kiểm định bản phát hành.
Smoke image-provider cài đặt toàn cục Bun chậm được kiểm soát riêng bằng `run_bun_global_install_smoke`. Nó chạy theo lịch hằng đêm và từ workflow kiểm tra phát hành, và các lần điều phối thủ công `Install Smoke` có thể chọn tham gia, nhưng pull request và các lần push lên `main` thì không. Các kiểm thử Docker QR và trình cài đặt giữ Dockerfile tập trung vào cài đặt riêng của chúng.
Kiểm thử nhanh image-provider cài đặt Bun toàn cục chậm được kiểm soát riêng bằng `run_bun_global_install_smoke`. Nó chạy theo lịch hằng đêm và từ workflow kiểm tra phát hành; các dispatch `Install Smoke` thủ công có thể chọn tham gia, nhưng pull request và các lần push lên `main` thì không. Các test Docker QR và bộ cài đặt giữ Dockerfile tập trung vào cài đặt của riêng chúng.
## Docker E2E cục bộ
`pnpm test:docker:all` dựng trước một ảnh live-test dùng chung, đóng gói OpenClaw một lần thành tarball npm và dựng hai ảnh `scripts/e2e/Dockerfile` dùng chung:
`pnpm test:docker:all` dựng trước một ảnh live-test dùng chung, đóng gói OpenClaw một lần dưới dạng tarball npm và xây dựng hai ảnh `scripts/e2e/Dockerfile` dùng chung:
- một runner Node/Git tối giản cho các lane trình cài đặt/update/plugin-dependency;
- một runner Node/Git tối giản cho các lane bộ cài đặt/update/phụ thuộc plugin;
- một ảnh chức năng cài đặt cùng tarball đó vào `/app` cho các lane chức năng thông thường.
Định nghĩa lane Docker nằm trong `scripts/lib/docker-e2e-scenarios.mjs`, logic lập kế hoạch nằm trong `scripts/lib/docker-e2e-plan.mjs`, và runner chỉ thực thi kế hoạch đã chọn. Bộ lập lịch chọn ảnh theo từng lane bằng `OPENCLAW_DOCKER_E2E_BARE_IMAGE` và `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, rồi chạy các lane với `OPENCLAW_SKIP_DOCKER_BUILD=1`.
Định nghĩa lane Docker nằm trong `scripts/lib/docker-e2e-scenarios.mjs`, logic lập kế hoạch nằm trong `scripts/lib/docker-e2e-plan.mjs` và runner chỉ thực thi kế hoạch đã chọn. Bộ lập lịch chọn ảnh theo lane bằng `OPENCLAW_DOCKER_E2E_BARE_IMAGE` và `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, rồi chạy các lane với `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Tùy chỉnh
### Tham số tinh chỉnh
| Biến | Mặc định | Mục đích |
| -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Số slot của pool chính cho các lane thông thường. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Số slot của tail-pool nhạy với provider. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Giới hạn lane live đồng thời để provider không bị throttling. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Số slot nhóm chính cho các lane thông thường. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Số slot nhóm đuôi nhạy với provider. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Giới hạn lane live đồng thời để provider không bị điều tiết. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Giới hạn lane cài đặt npm đồng thời. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Giới hạn lane nhiều dịch vụ đồng thời. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Độ giãn cách giữa các lần bắt đầu lane để tránh dồn tạo Docker daemon; đặt `0` để không giãn. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Thời gian chờ dự phòng cho mỗi lane (120 phút); một số lane live/tail dùng giới hạn chặt hơn. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` in kế hoạch bộ lập lịch mà không chạy lane. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Danh sách lane chính xác, phân tách bằng dấu phẩy; bỏ qua smoke dọn dẹp để agent có thể tái hiện một lane lỗi. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Độ trễ giữa các lần khởi động lane để tránh bão tạo từ Docker daemon; đặt `0` để không trễ. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Thời gian chờ dự phòng cho từng lane (120 phút); các lane live/đuôi được chọn dùng giới hạn chặt hơn. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` in kế hoạch của bộ lập lịch mà không chạy lane. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Danh sách lane chính xác, phân tách bằng dấu phẩy; bỏ qua kiểm thử nhanh dọn dẹp để agents có thể tái hiện một lane bị lỗi. |
Một lane nặng hơn giới hạn hiệu lực của nó vẫn có thể bắt đầu từ một pool trống, rồi chạy một mình cho đến khi giải phóng dung lượng. Preflight tổng hợp cục bộ kiểm tra Docker, xóa các container OpenClaw E2E cũ, phát trạng thái lane đang hoạt động, lưu thời lượng lane để sắp xếp dài nhất trước và mặc định dừng lập lịch các lane trong pool mới sau lỗi đầu tiên.
Một lane nặng hơn giới hạn hiệu lực của nó vẫn có thể bắt đầu từ một nhóm trống, rồi chạy một mình cho đến khi giải phóng dung lượng. Các preflight tổng hợp cục bộ kiểm tra Docker, xóa các container OpenClaw E2E cũ, phát trạng thái lane đang hoạt động, lưu thời gian lane để sắp xếp dài nhất trước và theo mặc định dừng lập lịch các lane trong nhóm mới sau lỗi đầu tiên.
### Workflow live/E2E tái sử dụng
Workflow live/E2E tái sử dụng hỏi `scripts/test-docker-all.mjs --plan-json` để biết gói, loại ảnh, ảnh live, lane và phạm vi thông tin xác thực nào là bắt buộc. Sau đó `scripts/docker-e2e.mjs` chuyển kế hoạch đó thành output và tóm tắt GitHub. Nó đóng gói OpenClaw thông qua `scripts/package-openclaw-for-docker.mjs`, tải xuống tạo tác gói của lần chạy hiện tại, hoặc tải xuống tạo tác gói từ `package_artifact_run_id`; xác thực inventory tarball; dựng và push các ảnh Docker E2E bare/functional GHCR được gắn tag theo digest gói thông qua bộ nhớ đệm lớp Docker của Blacksmith khi kế hoạch cần các lane đã cài gói; và tái sử dụng các input `docker_e2e_bare_image`/`docker_e2e_functional_image` đã cung cấp hoặc các ảnh package-digest hiện có thay vì dựng lại. Các lần pull ảnh Docker được thử lại với thời gian chờ có giới hạn 180 giây cho mỗi lần thử để luồng registry/cache bị kẹt được thử lại nhanh thay vì tiêu tốn phần lớn đường găng CI.
Workflow live/E2E tái sử dụng hỏi `scripts/test-docker-all.mjs --plan-json` về gói, loại ảnh, ảnh live, lane và phạm vi thông tin xác thực cần thiết. `scripts/docker-e2e.mjs` sau đó chuyển kế hoạch đó thành output và phần tóm tắt của GitHub. Nó đóng gói OpenClaw thông qua `scripts/package-openclaw-for-docker.mjs`, tải xuống artifact gói của lần chạy hiện tại hoặc tải xuống artifact gói từ `package_artifact_run_id`; xác thực inventory tarball; xây dựng và đẩy các ảnh Docker E2E GHCR tối giản/chức năng được gắn tag theo digest gói thông qua cache lớp Docker của Blacksmith khi kế hoạch cần các lane đã cài đặt gói; và tái sử dụng input `docker_e2e_bare_image`/`docker_e2e_functional_image` đã cung cấp hoặc ảnh theo digest gói hiện có thay vì xây dựng lại. Các lần kéo ảnh Docker được thử lại với thời gian chờ giới hạn 180 giây cho mỗi lần thử để một luồng registry/cache bị kẹt được thử lại nhanh thay vì tiêu tốn phần lớn đường dẫn trọng yếu của CI.
### Phân đoạn đường phát hành
### Chunk đường dẫn phát hành
Phạm vi Docker phát hành chạy các job nhỏ được chia đoạn với `OPENCLAW_SKIP_DOCKER_BUILD=1` để mỗi đoạn chỉ pull loại ảnh cần thiết và thực thi nhiều lane thông qua cùng bộ lập lịch có trọng số:
Phạm vi Docker phát hành chạy các job nhỏ hơn được chia chunk với `OPENCLAW_SKIP_DOCKER_BUILD=1` để mỗi chunk chỉ kéo loại ảnh nó cần và thực thi nhiều lane thông qua cùng bộ lập lịch có trọng số:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
Các đoạn Docker phát hành hiện tại là `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` và `plugins-runtime-install-a` đến `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` và `plugins-integrations` vẫn là các bí danh tổng hợp plugin/runtime. Bí danh lane `install-e2e` vẫn là bí danh chạy lại thủ công tổng hợp cho cả hai lane trình cài đặt provider.
Các chunk Docker phát hành hiện tại là `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` và từ `plugins-runtime-install-a` đến `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` và `plugins-integrations` vẫn là các alias tổng hợp cho plugin/runtime. Alias lane `install-e2e` vẫn là alias chạy lại thủ công tổng hợp cho cả hai lane bộ cài đặt provider.
OpenWebUI được gộp vào `plugins-runtime-services` khi phạm vi release-path đầy đủ yêu cầu nó, và chỉ giữ một đoạn `openwebui` độc lập cho các điều phối chỉ dành cho OpenWebUI. Các lane cập nhật kênh được đóng gói kèm thử lại một lần cho lỗi mạng npm nhất thời.
OpenWebUI được gộp vào `plugins-runtime-services` khi phạm vi release-path đầy đủ yêu cầu, và chỉ giữ chunk độc lập `openwebui` cho các dispatch chỉ dành cho OpenWebUI. Các lane cập nhật kênh đóng gói sẵn thử lại một lần đối với lỗi mạng npm tạm thời.
Mỗi đoạn tải lên `.artifacts/docker-tests/` với nhật ký lane, thời lượng, `summary.json`, `failures.json`, thời lượng pha, JSON kế hoạch bộ lập lịch, bảng lane chậm và lệnh chạy lại cho từng lane. Input `docker_lanes` của workflow chạy các lane đã chọn dựa trên các ảnh đã chuẩn bị thay vì các job đoạn, nhờ đó việc gỡ lỗi lane thất bại được giới hạn trong một job Docker mục tiêu và chuẩn bị, tải xuống hoặc tái sử dụng tạo tác gói cho lần chạy đó; nếu một lane đã chọn là lane Docker live, job mục tiêu sẽ dựng ảnh live-test cục bộ cho lần chạy lại đó. Các lệnh chạy lại GitHub được tạo cho từng lane bao gồm `package_artifact_run_id`, `package_artifact_name` và input ảnh đã chuẩn bị khi các giá trị đó tồn tại, để một lane thất bại có thể tái sử dụng chính xác gói và ảnh từ lần chạy thất bại.
Mỗi chunk tải lên `.artifacts/docker-tests/` với nhật ký lane, thời gian, `summary.json`, `failures.json`, thời gian từng pha, JSON kế hoạch của bộ lập lịch, bảng lane chậm và lệnh chạy lại theo từng lane. Input `docker_lanes` của workflow chạy các lane đã chọn trên các ảnh đã chuẩn bị thay vì các job chunk, giúp việc gỡ lỗi lane hỏng được giới hạn trong một job Docker có mục tiêu và chuẩn bị, tải xuống hoặc tái sử dụng artifact gói cho lần chạy đó; nếu một lane đã chọn là lane Docker live, job mục tiêu xây dựng ảnh live-test cục bộ cho lần chạy lại đó. Các lệnh GitHub chạy lại được tạo theo từng lane bao gồm `package_artifact_run_id`, `package_artifact_name` và input ảnh đã chuẩn bị khi các giá trị đó tồn tại, để một lane bị lỗi có thể tái sử dụng đúng gói và ảnh từ lần chạy lỗi.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
Workflow live/E2E theo lịch chạy toàn bộ bộ kiểm thử Docker release-path hằng ngày.
Workflow live/E2E theo lịch chạy toàn bộ bộ Docker release-path hằng ngày.
## Tiền phát hành Plugin
## Bản phát hành trước của Plugin
`Plugin Prerelease` là phạm vi sản phẩm/gói tốn kém hơn, nên nó là một workflow riêng do `Full Release Validation` hoặc một operator rõ ràng điều phối. Pull request thông thường, các lần push lên `main` và các lần điều phối CI thủ công độc lập không bật bộ kiểm thử đó. Nó cân bằng các kiểm thử Plugin được đóng gói kèm trên tám worker extension; các job shard extension đó chạy tối đa hai nhóm cấu hình Plugin cùng lúc, với một worker Vitest cho mỗi nhóm và heap Node lớn hơn để các lô Plugin nặng import không tạo thêm job CI. Đường Docker prerelease chỉ dành cho phát hành gom các lane Docker mục tiêu thành nhóm nhỏ để tránh giữ hàng chục runner cho các job kéo dài một đến ba phút.
`Plugin Prerelease` là phạm vi sản phẩm/gói tốn kém hơn, nên nó là một workflow riêng được dispatch bởi `Full Release Validation` hoặc bởi một người vận hành rõ ràng. Các pull request thông thường, lần push lên `main` và dispatch CI thủ công độc lập không chạy bộ này. Nó cân bằng các test plugin đóng gói sẵn trên tám worker extension; các job shard extension đó chạy tối đa hai nhóm cấu hình plugin cùng lúc với một Vitest worker cho mỗi nhóm và heap Node lớn hơn để các lô plugin nặng về import không tạo thêm job CI. Đường dẫn Docker prerelease chỉ dành cho phát hành gom nhóm các lane Docker có mục tiêu thành các nhóm nhỏ để tránh giữ trước hàng chục runner cho các job dài một đến ba phút.
## Phòng thí nghiệm QA
## QA Lab
Phòng thí nghiệm QA có các lane CI chuyên dụng bên ngoài workflow chính được định phạm vi thông minh. Parity agentic được lồng dưới các bộ kiểm thử QA rộng và phát hành, không phải workflow PR độc lập. Dùng `Full Release Validation` với `rerun_group=qa-parity` khi parity cần đi cùng một lần chạy xác thực rộng.
QA Lab có các lane CI chuyên dụng nằm ngoài workflow chính có phạm vi thông minh. Agentic parity được lồng dưới các harness QA và phát hành rộng, không phải một workflow PR độc lập. Dùng `Full Release Validation` với `rerun_group=qa-parity` khi parity cần đi cùng một lần chạy kiểm định rộng.
- Workflow `QA-Lab - All Lanes` chạy hằng đêm trên `main` và khi điều phối thủ công; nó tỏa ra lane parity mock, lane Matrix live, và các lane Telegram và Discord live dưới dạng các job song song. Các job live dùng môi trường `qa-live-shared`, còn Telegram/Discord dùng lease Convex.
- Workflow `QA-Lab - All Lanes` chạy hằng đêm trên `main` và khi dispatch thủ công; nó mở rộng lane mock parity, lane Matrix live và các lane Telegram và Discord live thành các job song song. Các job live dùng môi trường `qa-live-shared`, còn Telegram/Discord dùng lease Convex.
Các kiểm tra phát hành chạy các lane vận chuyển live Matrix và Telegram với provider mock xác định và các model đủ điều kiện mock (`mock-openai/gpt-5.5` và `mock-openai/gpt-5.5-alt`) để hợp đồng kênh được cô lập khỏi độ trễ model live và khởi động provider-plugin thông thường. Gateway vận chuyển live tắt tìm kiếm bộ nhớ vì parity QA kiểm tra hành vi bộ nhớ riêng; kết nối provider được bao phủ bởi các bộ kiểm thử model live, provider native và provider Docker riêng biệt.
Các kiểm tra phát hành chạy các lane truyền tải Matrix và Telegram live với provider giả lập xác định và các model đủ điều kiện mock (`mock-openai/gpt-5.5` và `mock-openai/gpt-5.5-alt`) để hợp đồng kênh được tách biệt khỏi độ trễ model live và khởi động provider-plugin thông thường. Gateway truyền tải live tắt tìm kiếm bộ nhớ vì QA parity kiểm tra hành vi bộ nhớ riêng; kết nối provider được bao phủ bởi các bộ test provider live model, native provider và Docker provider riêng.
Matrix dùng `--profile fast` cho các cổng theo lịch và phát hành, chỉ thêm `--fail-fast` khi CLI đã checkout hỗ trợ nó. Mặc định CLI và input workflow thủ công vẫn là `all`; điều phối thủ công `matrix_profile=all` luôn chia shard phạm vi Matrix đầy đủ thành các job `transport`, `media`, `e2ee-smoke`, `e2ee-deep` và `e2ee-cli`.
Matrix dùng `--profile fast` cho các gate theo lịch và phát hành, chỉ thêm `--fail-fast` khi CLI đã checkout hỗ trợ. Mặc định CLI và input workflow thủ công vẫn là `all`; dispatch thủ công `matrix_profile=all` luôn chia shard phạm vi Matrix đầy đủ thành các job `transport`, `media`, `e2ee-smoke`, `e2ee-deep` và `e2ee-cli`.
`OpenClaw Release Checks` cũng chạy các lane Phòng thí nghiệm QA quan trọng cho phát hành trước khi phê duyệt phát hành; cổng parity QA của nó chạy các gói candidate và baseline dưới dạng các job lane song song, rồi tải cả hai tạo tác xuống một job báo cáo nhỏ cho bước so sánh parity cuối cùng.
`OpenClaw Release Checks` cũng chạy các lane QA Lab trọng yếu cho phát hành trước khi phê duyệt phát hành; gate QA parity của nó chạy các gói candidate và baseline dưới dạng các job lane song song, rồi tải cả hai artifact vào một job báo cáo nhỏ cho so sánh parity cuối cùng.
Với các PR thông thường, hãy theo bằng chứng CI/kiểm tra theo phạm vi thay vì xem parity là một trạng thái bắt buộc.
Đối với PR thông thường, hãy dựa vào bằng chứng CI/check theo phạm vi thay vì coi parity là một trạng thái bắt buộc.
## CodeQL
Quy trình `CodeQL` cố ý là trình quét bảo mật lượt đầu có phạm vi hẹp, không phải lượt quét toàn bộ kho lưu trữ. Hằng ngày, thủ công, và các lần chạy bảo vệ pull request không phải bản nháp sẽ quét mã workflow Actions cùng các bề mặt JavaScript/TypeScript rủi ro cao nhất bằng các truy vấn bảo mật có độ tin cậy cao, được lọc theo `security-severity` cao/nghiêm trọng.
Quy trình làm việc `CodeQL` được chủ ý thiết kế như một trình quét bảo mật vòng đầu hẹp, không phải lượt quét toàn bộ kho lưu trữ. Các lượt chạy bảo vệ hằng ngày, thủ công và pull request không ở trạng thái nháp quét mã workflow của Actions cùng các bề mặt JavaScript/TypeScript có rủi ro cao nhất, bằng các truy vấn bảo mật độ tin cậy cao được lọc theo `security-severity` cao/nghiêm trọng.
Bộ bảo vệ pull request vẫn nhẹ: nó chỉ khởi động với các thay đổi trong `.github/actions`, `.github/codeql`, `.github/workflows`, `packages`, hoặc `src`, và chạy cùng ma trận bảo mật có độ tin cậy cao như workflow theo lịch. Android và macOS CodeQL không nằm trong mặc định PR.
Bộ bảo vệ pull request vẫn nhẹ: nó chỉ khởi động với các thay đổi trong `.github/actions`, `.github/codeql`, `.github/workflows`, `packages`, hoặc `src`, và chạy cùng ma trận bảo mật độ tin cậy cao như workflow theo lịch. Android và macOS CodeQL không nằm trong mặc định của PR.
### Danh mục bảo mật
| Danh mục | Bề mặt |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Xác thực, bí mật, sandbox, Cron, và đường cơ sở Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Các hợp đồng triển khai kênh lõi cùng runtime Plugin kênh, Gateway, Plugin SDK, bí mật, điểm chạm kiểm toán |
| `/codeql-security-high/network-ssrf-boundary` | Các bề mặt chính sách SSRF lõi, phân tích cú pháp IP, bảo vệ mạng, tìm nạp web, và SSRF của Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Máy chủ MCP, trình trợ giúp thực thi tiến trình, phân phối đi, và cổng thực thi công cụ của agent |
| `/codeql-security-high/plugin-trust-boundary` | Các bề mặt tin cậy của cài đặt Plugin, trình tải, manifest, registry, cài đặt trình quản lý gói, tải nguồn, và hợp đồng gói Plugin SDK |
| `/codeql-security-high/core-auth-secrets` | Xác thực, bí mật, sandbox, cron, và đường cơ sở Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Hợp đồng triển khai kênh lõi cộng với runtime Plugin kênh, Gateway, Plugin SDK, bí mật, điểm chạm kiểm toán |
| `/codeql-security-high/network-ssrf-boundary` | Bề mặt chính sách SSRF lõi, phân tích IP, bảo vệ mạng, web-fetch, và SSRF của Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Máy chủ MCP, trình trợ giúp thực thi tiến trình, phân phối outbound, và cổng thực thi công cụ của agent |
| `/codeql-security-high/plugin-trust-boundary` | Bề mặt tin cậy của cài đặt Plugin, loader, manifest, registry, cài đặt package-manager, tải nguồn, và hợp đồng gói Plugin SDK |
### Các phân đoạn bảo mật riêng theo nền tảng
### Mảnh bảo mật theo nền tảng
- `CodeQL Android Critical Security` — phân đoạn bảo mật Android theo lịch. Xây dựng ứng dụng Android thủ công cho CodeQL trên runner Blacksmith Linux nhỏ nhất được workflow sanity chấp nhận. Tải lên dưới `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — phân đoạn bảo mật macOS hằng tuần/thủ công. Xây dựng ứng dụng macOS thủ công cho CodeQL trên Blacksmith macOS, lọc kết quả build phụ thuộc khỏi SARIF được tải lên, và tải lên dưới `/codeql-critical-security/macos`. Được giữ ngoài mặc định hằng ngày vì build macOS chi phối thời gian chạy ngay cả khi sạch.
- `CodeQL Android Critical Security` — mảnh bảo mật Android theo lịch. Build ứng dụng Android thủ công cho CodeQL trên runner Blacksmith Linux nhỏ nhất được workflow sanity chấp nhận. Tải lên dưới `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — mảnh bảo mật macOS hằng tuần/thủ công. Build ứng dụng macOS thủ công cho CodeQL trên Blacksmith macOS, lọc kết quả build phụ thuộc ra khỏi SARIF đã tải lên, và tải lên dưới `/codeql-critical-security/macos`. Được giữ ngoài mặc định hằng ngày vì build macOS chiếm phần lớn thời gian runtime ngay cả khi sạch.
### Danh mục chất lượng nghiêm trọng
`CodeQL Critical Quality` là phân đoạn không bảo mật tương ứng. Nó chỉ chạy các truy vấn chất lượng JavaScript/TypeScript không bảo mật ở mức nghiêm trọng lỗi trên các bề mặt giá trị cao có phạm vi hẹp trên runner Blacksmith Linux nhỏ hơn. Bộ bảo vệ pull request của nó cố ý nhỏ hơn hồ sơ theo lịch: PR không phải bản nháp chỉ chạy các phân đoạn `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract`, và `plugin-sdk-reply-runtime` tương ứng cho mã thực thi lệnh/mô hình/công cụ của agent và điều phối trả lời, mã lược đồ/cấu hình/di trú/IO, mã xác thực/bí mật/sandbox/bảo mật, runtime Plugin kênh lõi và kênh đóng gói, phương thức máy chủ/giao thức Gateway, runtime bộ nhớ/keo SDK, MCP/tiến trình/phân phối đi, runtime nhà cung cấp/danh mục mô hình, chẩn đoán phiên/hàng đợi phân phối, trình tải Plugin, Plugin SDK/hợp đồng gói, hoặc các thay đổi runtime trả lời của Plugin SDK. Các thay đổi cấu hình CodeQL và workflow chất lượng chạy cả mười hai phân đoạn chất lượng PR.
`CodeQL Critical Quality` là mảnh không bảo mật tương ứng. Nó chỉ chạy các truy vấn chất lượng JavaScript/TypeScript mức lỗi, không liên quan đến bảo mật, trên các bề mặt hẹp có giá trị cao trên runner Blacksmith Linux nhỏ hơn. Bộ bảo vệ pull request của nó được chủ ý thu nhỏ hơn profile theo lịch: PR không ở trạng thái nháp chỉ chạy các mảnh `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract`, và `plugin-sdk-reply-runtime` tương ứng cho các thay đổi trong mã thực thi lệnh/mô hình/công cụ của agent và điều phối trả lời, mã schema/migration/IO cấu hình, mã xác thực/bí mật/sandbox/bảo mật, runtime kênh lõi và Plugin kênh được đóng gói, phương thức máy chủ/giao thức Gateway, runtime bộ nhớ/SDK glue, MCP/tiến trình/phân phối outbound, runtime nhà cung cấp/danh mục mô hình, chẩn đoán phiên/hàng đợi phân phối, loader Plugin, Plugin SDK/hợp đồng gói, hoặc runtime trả lời Plugin SDK. Các thay đổi cấu hình CodeQL và workflow chất lượng chạy tất cả mười hai mảnh chất lượng PR.
Điều phối thủ công chấp nhận:
Dispatch thủ công chấp nhận:
```
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Các hồ sơ hẹp là các điểm móc hướng dẫn/lặp để chạy riêng một phân đoạn chất lượng.
Các profile hẹp là hook hướng dẫn/lặp lại để chạy riêng một mảnh chất lượng.
| Danh mục | Bề mặt |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Mã ranh giới bảo mật cho xác thực, bí mật, sandbox, Cron, và Gateway |
| `/codeql-critical-quality/config-boundary` | Lược đồ cấu hình, di trú, chuẩn hóa, và hợp đồng IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Lược đồ giao thức Gateway và hợp đồng phương thức máy chủ |
| `/codeql-critical-quality/channel-runtime-boundary` | Hợp đồng triển khai Plugin kênh lõi và kênh đóng gói |
| `/codeql-critical-quality/agent-runtime-boundary` | Thực thi lệnh, điều phối mô hình/nhà cung cấp, điều phối và hàng đợi tự động trả lời, và hợp đồng runtime mặt phẳng điều khiển ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Máy chủ MCP và cầu nối công cụ, trình trợ giúp giám sát tiến trình, và hợp đồng phân phối đi |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK máy chủ bộ nhớ, facade runtime bộ nhớ, bí danh Plugin SDK bộ nhớ, keo kích hoạt runtime bộ nhớ, và lệnh doctor bộ nhớ |
| `/codeql-critical-quality/session-diagnostics-boundary` | Nội bộ hàng đợi trả lời, hàng đợi phân phối phiên, trình trợ giúp liên kết/phân phối phiên đi, bề mặt gói sự kiện/nhật ký chẩn đoán, và hợp đồng CLI doctor phiên |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Điều phối trả lời đến của Plugin SDK, trình trợ giúp payload/phân đoạn/runtime trả lời, tùy chọn trả lời kênh, hàng đợi phân phối, và trình trợ giúp liên kết phiên/luồng |
| `/codeql-critical-quality/provider-runtime-boundary` | Chuẩn hóa danh mục mô hình, xác thực và khám phá nhà cung cấp, đăng ký runtime nhà cung cấp, mặc định/danh mục nhà cung cấp, và registry web/tìm kiếm/tìm nạp/nhúng |
| `/codeql-critical-quality/ui-control-plane` | Khởi động Control UI, lưu trữ cục bộ, luồng điều khiển Gateway, và hợp đồng runtime mặt phẳng điều khiển tác vụ |
| `/codeql-critical-quality/web-media-runtime-boundary` | Hợp đồng runtime tìm nạp/tìm kiếm web lõi, IO phương tiện, hiểu phương tiện, tạo hình ảnh, và tạo phương tiện |
| `/codeql-critical-quality/plugin-boundary` | Hợp đồng trình tải, registry, bề mặt công khai, và điểm vào Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Nguồn Plugin SDK phía gói đã phát hành và trình trợ giúp hợp đồng gói plugin |
| `/codeql-critical-quality/core-auth-secrets` | Mã ranh giới bảo mật xác thực, bí mật, sandbox, cron, và Gateway |
| `/codeql-critical-quality/config-boundary` | Schema cấu hình, migration, chuẩn hóa, và hợp đồng IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schema giao thức Gateway và hợp đồng phương thức máy chủ |
| `/codeql-critical-quality/channel-runtime-boundary` | Hợp đồng triển khai kênh lõi và Plugin kênh được đóng gói |
| `/codeql-critical-quality/agent-runtime-boundary` | Thực thi lệnh, điều phối mô hình/nhà cung cấp, điều phối và hàng đợi tự động trả lời, và hợp đồng runtime control-plane ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Máy chủ MCP và cầu nối công cụ, trình trợ giúp giám sát tiến trình, và hợp đồng phân phối outbound |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK host bộ nhớ, facade runtime bộ nhớ, alias Plugin SDK bộ nhớ, glue kích hoạt runtime bộ nhớ, và lệnh doctor bộ nhớ |
| `/codeql-critical-quality/session-diagnostics-boundary` | Nội bộ hàng đợi trả lời, hàng đợi phân phối phiên, trình trợ giúp binding/phân phối phiên outbound, bề mặt gói sự kiện/log chẩn đoán, và hợp đồng CLI doctor phiên |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Điều phối trả lời inbound Plugin SDK, trình trợ giúp payload/chunking/runtime trả lời, tùy chọn trả lời kênh, hàng đợi phân phối, và trình trợ giúp binding phiên/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Chuẩn hóa danh mục mô hình, xác thực và khám phá nhà cung cấp, đăng ký runtime nhà cung cấp, mặc định/danh mục nhà cung cấp, và registry web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap UI điều khiển, lưu trữ cục bộ, luồng điều khiển Gateway, và hợp đồng runtime control-plane tác vụ |
| `/codeql-critical-quality/web-media-runtime-boundary` | Hợp đồng runtime fetch/search web lõi, IO media, hiểu media, tạo hình ảnh, và tạo media |
| `/codeql-critical-quality/plugin-boundary` | Hợp đồng loader, registry, bề mặt công khai, và điểm vào Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Nguồn Plugin SDK phía gói đã phát hành và trình trợ giúp hợp đồng gói Plugin |
Chất lượng được tách khỏi bảo mật để các phát hiện chất lượng có thể được lên lịch, đo lường, vô hiệu hóa, hoặc mở rộng mà không che khuất tín hiệu bảo mật. Việc mở rộng CodeQL cho Swift, Python, và plugin đóng gói chỉ nên được thêm lại dưới dạng công việc tiếp theo có phạm vi hoặc phân đoạn sau khi các hồ sơ hẹp có thời gian chạy và tín hiệu ổn định.
Chất lượng được tách khỏi bảo mật để các phát hiện chất lượng có thể được lên lịch, đo lường, vô hiệu hóa, hoặc mở rộng mà không che khuất tín hiệu bảo mật. Việc mở rộng CodeQL cho Swift, Python, và Plugin được đóng gói chỉ nên được thêm lại dưới dạng công việc tiếp theo có phạm vi hoặc được chia mảnh sau khi các profile hẹp có runtime và tín hiệu ổn định.
## Workflow bảo trì
### Docs Agent
Workflow `Docs Agent` là một làn bảo trì Codex điều khiển theo sự kiện để giữ tài liệu hiện có đồng bộ với các thay đổi mới được tích hợp. Nó không có lịch thuần túy: một lần chạy CI push không phải bot thành công trên `main` có thể kích hoạt nó, và điều phối thủ công có thể chạy nó trực tiếp. Các lệnh gọi workflow-run sẽ bỏ qua khi `main` đã tiến lên hoặc khi một lần chạy Docs Agent không bị bỏ qua khác đã được tạo trong giờ trước. Khi chạy, nó xem xét phạm vi commit từ SHA nguồn Docs Agent không bị bỏ qua trước đó đến `main` hiện tại, nên một lần chạy mỗi giờ có thể bao phủ mọi thay đổi main được tích lũy kể từ lượt xử lý tài liệu gần nhất.
Workflow `Docs Agent` là một làn bảo trì Codex theo sự kiện để giữ tài liệu hiện có đồng bộ với các thay đổi vừa được merge. Nó không có lịch thuần túy: một lượt chạy CI push không phải bot thành công trên `main` có thể kích hoạt nó, và dispatch thủ công có thể chạy trực tiếp. Các lần gọi workflow-run bỏ qua khi `main` đã tiến lên hoặc khi một lượt chạy Docs Agent không bị bỏ qua khác đã được tạo trong giờ trước. Khi chạy, nó xem xét dải commit từ SHA nguồn Docs Agent không bị bỏ qua trước đó đến `main` hiện tại, nên một lượt chạy hằng giờ có thể bao phủ tất cả thay đổi main tích lũy kể từ lượt tài liệu gần nhất.
### Test Performance Agent
Workflow `Test Performance Agent` là một làn bảo trì Codex điều khiển theo sự kiện dành cho các bài kiểm thử chậm. Nó không có lịch thuần túy: một lần chạy CI push không phải bot thành công trên `main` có thể kích hoạt nó, nhưng nó sẽ bỏ qua nếu một lệnh gọi workflow-run khác đã chạy hoặc đang chạy trong ngày UTC đó. Điều phối thủ công bỏ qua cổng hoạt động hằng ngày đó. Làn này xây dựng báo cáo hiệu năng Vitest được nhóm cho toàn bộ bộ kiểm thử, cho phép Codex chỉ thực hiện các sửa lỗi nhỏ về hiệu năng kiểm thử mà vẫn giữ nguyên độ phủ thay vì tái cấu trúc rộng, sau đó chạy lại báo cáo toàn bộ bộ kiểm thử và từ chối các thay đổi làm giảm số lượng bài kiểm thử đường cơ sở đang vượt qua. Nếu đường cơ sở có bài kiểm thử thất bại, Codex chỉ được sửa các lỗi hiển nhiên và báo cáo toàn bộ bộ kiểm thử sau agent phải vượt qua trước khi bất kỳ thứ gì được commit. Khi `main` tiến lên trước khi push của bot được tích hợp, làn này rebase bản vá đã xác thực, chạy lại `pnpm check:changed`, và thử lại push; các bản vá cũ bị xung đột sẽ bị bỏ qua. Nó dùng Ubuntu do GitHub lưu trữ để action Codex có thể giữ cùng tư thế an toàn drop-sudo như docs agent.
Workflow `Test Performance Agent` là một làn bảo trì Codex theo sự kiện cho các bài test chậm. Nó không có lịch thuần túy: một lượt chạy CI push không phải bot thành công trên `main` có thể kích hoạt nó, nhưng nó bỏ qua nếu một lần gọi workflow-run khác đã chạy hoặc đang chạy trong ngày UTC đó. Dispatch thủ công bỏ qua cổng hoạt động hằng ngày đó. Làn này build một báo cáo hiệu năng Vitest toàn bộ suite được nhóm, cho phép Codex chỉ thực hiện các bản sửa hiệu năng test nhỏ vẫn giữ nguyên coverage thay vì refactor rộng, sau đó chạy lại báo cáo toàn bộ suite và từ chối các thay đổi làm giảm số lượng test baseline đang pass. Nếu baseline có test lỗi, Codex chỉ có thể sửa các lỗi hiển nhiên và báo cáo toàn bộ suite sau agent phải pass trước khi bất kỳ thứ gì được commit. Khi `main` tiến lên trước khi bot push được đưa vào, làn này rebase bản vá đã xác thực, chạy lại `pnpm check:changed`, và thử push lại; các bản vá cũ bị xung đột sẽ bị bỏ qua. Nó dùng Ubuntu do GitHub host để action Codex có thể giữ cùng tư thế an toàn drop-sudo như docs agent.
### Duplicate PRs After Merge
### PR trùng lặp sau merge
Workflow `Duplicate PRs After Merge` là workflow thủ công của maintainer để dọn dẹp bản trùng lặp sau khi tích hợp. Mặc định là dry-run và chỉ đóng các PR được liệt kê rõ ràng khi `apply=true`. Trước khi thay đổi GitHub, nó xác minh rằng PR đã tích hợp đã được merge và mỗi bản trùng lặp có issue được tham chiếu chung hoặc các hunk thay đổi chồng lấp.
Workflow `Duplicate PRs After Merge` là một workflow maintainer thủ công để dọn dẹp bản trùng lặp sau khi land. Mặc định là dry-run và chỉ đóng các PR được liệt kê rõ ràng khi `apply=true`. Trước khi thay đổi GitHub, nó xác minh rằng PR đã land đã được merge và mỗi bản trùng lặp có vấn đề được tham chiếu chung hoặc có các hunk thay đổi chồng lấn.
```bash
gh workflow run duplicate-after-merge.yml \
@ -478,37 +478,37 @@ gh workflow run duplicate-after-merge.yml \
## Cổng kiểm tra cục bộ và định tuyến thay đổi
Logic làn thay đổi cục bộ nằm trong `scripts/changed-lanes.mjs` và được thực thi bởi `scripts/check-changed.mjs`. Cổng kiểm tra cục bộ đó nghiêm ngặt hơn về ranh giới kiến trúc so với phạm vi nền tảng CI rộng:
Logic changed-lane cục bộ nằm trong `scripts/changed-lanes.mjs` và được thực thi bởi `scripts/check-changed.mjs`. Cổng kiểm tra cục bộ đó nghiêm ngặt hơn về ranh giới kiến trúc so với phạm vi nền tảng CI rộng:
- thay đổi sản xuất lõi chạy typecheck prod lõi và kiểm thử lõi cùng lint/bảo vệ lõi;
- thay đổi chỉ kiểm thử lõi chỉ chạy typecheck kiểm thử lõi cùng lint lõi;
- thay đổi sản xuất extension chạy typecheck prod extension và kiểm thử extension cùng lint extension;
- thay đổi chỉ kiểm thử extension chạy typecheck kiểm thử extension cùng lint extension;
- các thay đổi Plugin SDK công khai hoặc hợp đồng plugin mở rộng sang typecheck extension vì extension phụ thuộc vào các hợp đồng lõi đó (các lượt quét extension Vitest vẫn là công việc kiểm thử rõ ràng);
- các lần tăng phiên bản chỉ metadata phát hành chạy các kiểm tra phiên bản/cấu hình/phụ thuộc gốc có mục tiêu;
- thay đổi root/cấu hình không xác định fail safe sang tất cả các làn kiểm tra.
- thay đổi production lõi chạy typecheck core prod và core test cộng với lint/guard lõi;
- thay đổi chỉ liên quan đến test lõi chỉ chạy typecheck core test cộng với lint lõi;
- thay đổi production của extension chạy typecheck extension prod và extension test cộng với lint extension;
- thay đổi chỉ liên quan đến test của extension chạy typecheck extension test cộng với lint extension;
- thay đổi Plugin SDK công khai hoặc hợp đồng Plugin mở rộng sang typecheck extension vì extension phụ thuộc vào các hợp đồng lõi đó (các lượt quét extension Vitest vẫn là công việc test rõ ràng);
- bump phiên bản chỉ metadata phát hành chạy các kiểm tra phiên bản/cấu hình/phụ thuộc root được nhắm mục tiêu;
- thay đổi root/cấu hình không xác định sẽ fail an toàn sang tất cả làn kiểm tra.
Định tuyến kiểm thử thay đổi cục bộ nằm trong `scripts/test-projects.test-support.mjs` và cố ý rẻ hơn `check:changed`: chỉnh sửa kiểm thử trực tiếp sẽ tự chạy chính nó, chỉnh sửa nguồn ưu tiên ánh xạ rõ ràng, sau đó là kiểm thử anh em và phần phụ thuộc đồ thị import. Cấu hình phân phối group-room dùng chung là một trong các ánh xạ rõ ràng: thay đổi đối với cấu hình trả lời hiển thị theo nhóm, chế độ phân phối trả lời nguồn, hoặc prompt hệ thống của công cụ nhắn tin sẽ đi qua kiểm thử trả lời lõi cùng các hồi quy phân phối Discord và Slack để một thay đổi mặc định dùng chung thất bại trước lần push PR đầu tiên. Chỉ dùng `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` khi thay đổi đủ rộng ở cấp harness khiến tập được ánh xạ rẻ không còn là proxy đáng tin cậy.
Định tuyến changed-test cục bộ nằm trong `scripts/test-projects.test-support.mjs` và được chủ ý làm rẻ hơn `check:changed`: chỉnh sửa test trực tiếp tự chạy chính chúng, chỉnh sửa nguồn ưu tiên mapping rõ ràng, rồi đến các test cùng cấp và phần phụ thuộc import-graph. Cấu hình phân phối group-room dùng chung là một trong các mapping rõ ràng: thay đổi đối với cấu hình trả lời hiển thị trong nhóm, chế độ phân phối trả lời nguồn, hoặc prompt hệ thống message-tool được định tuyến qua các test trả lời lõi cộng với regression phân phối Discord và Slack để thay đổi mặc định dùng chung fail trước lần push PR đầu tiên. Chỉ dùng `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` khi thay đổi đủ rộng trên toàn harness khiến tập được map rẻ không còn là proxy đáng tin cậy.
## Xác thực Testbox
Chạy Testbox từ gốc repo và ưu tiên một box mới đã được khởi động sẵn cho bằng chứng diện rộng. Trước khi dành một gate chậm cho một box đã được tái sử dụng, đã hết hạn, hoặc vừa báo cáo một lần đồng bộ lớn bất ngờ, hãy chạy `pnpm testbox:sanity` bên trong box trước.
Chạy Testbox từ gốc kho lưu trữ và ưu tiên một box mới đã được khởi động sẵn cho bằng chứng diện rộng. Trước khi tốn một cổng kiểm tra chậm trên một box đã được tái sử dụng, đã hết hạn hoặc vừa báo cáo một lượt đồng bộ lớn bất ngờ, hãy chạy `pnpm testbox:sanity` bên trong box trước.
Kiểm tra sanity sẽ thất bại nhanh khi các tệp gốc bắt buộc như `pnpm-lock.yaml` biến mất hoặc khi `git status --short` hiển thị ít nhất 200 lượt xóa có theo dõi. Điều đó thường có nghĩa là trạng thái đồng bộ từ xa không phải là bản sao đáng tin cậy của PR; hãy dừng box đó và khởi động sẵn một box mới thay vì gỡ lỗi lỗi kiểm thử sản phẩm. Với các PR cố ý xóa số lượng lớn, đặt `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` cho lần chạy sanity đó.
Kiểm tra sanity sẽ thất bại nhanh khi các tệp gốc bắt buộc như `pnpm-lock.yaml` biến mất hoặc khi `git status --short` hiển thị ít nhất 200 tệp được theo dõi đã bị xóa. Điều đó thường có nghĩa là trạng thái đồng bộ từ xa không phải là bản sao đáng tin cậy của PR; hãy dừng box đó và khởi động sẵn một box mới thay vì gỡ lỗi lỗi kiểm thử sản phẩm. Với các PR cố ý xóa số lượng lớn, đặt `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` cho lần chạy sanity đó.
`pnpm testbox:run` cũng kết thúc một lệnh gọi Blacksmith CLI cục bộ nếu lệnh đó ở lại pha đồng bộ hơn năm phút mà không có đầu ra sau đồng bộ. Đặt `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` để tắt cơ chế bảo vệ đó, hoặc dùng một giá trị mili giây lớn hơn cho các diff cục bộ lớn bất thường.
`pnpm testbox:run` cũng chấm dứt một lệnh gọi Blacksmith CLI cục bộ nếu lệnh đó ở trong giai đoạn đồng bộ hơn năm phút mà không có đầu ra sau đồng bộ. Đặt `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` để tắt cơ chế bảo vệ đó, hoặc dùng một giá trị mili giây lớn hơn cho các diff cục bộ lớn bất thường.
Crabbox là wrapper remote-box do repo sở hữu để cung cấp bằng chứng Linux cho maintainer. Dùng nó khi một kiểm tra quá rộng cho local edit loop, khi tính tương đồng với CI là quan trọng, hoặc khi bằng chứng cần secret, Docker, package lane, box có thể tái sử dụng, hoặc log từ xa. Backend OpenClaw thông thường là `blacksmith-testbox`; năng lực AWS/Hetzner sở hữu là phương án dự phòng khi Blacksmith ngừng hoạt động, gặp vấn đề quota, hoặc khi cần kiểm thử rõ ràng trên năng lực sở hữu.
Crabbox là trình bao bọc box từ xa do kho lưu trữ sở hữu cho bằng chứng Linux của maintainer. Dùng nó khi một kiểm tra quá rộng cho vòng lặp chỉnh sửa cục bộ, khi tính tương đồng với CI là quan trọng, hoặc khi bằng chứng cần secret, Docker, các lane gói, box tái sử dụng được, hoặc log từ xa. Backend OpenClaw thông thường là `blacksmith-testbox`; dung lượng AWS/Hetzner sở hữu là phương án dự phòng cho sự cố Blacksmith, vấn đề hạn ngạch, hoặc kiểm thử dung lượng sở hữu một cách rõ ràng.
Trước lần chạy đầu tiên, kiểm tra wrapper từ gốc repo:
Trước lần chạy đầu tiên, kiểm tra trình bao bọc từ gốc kho lưu trữ:
```bash
pnpm crabbox:run -- --help | sed -n '1,120p'
```
Wrapper của repo từ chối binary Crabbox cũ không quảng bá `blacksmith-testbox`. Truyền provider một cách tường minh dù `.crabbox.yaml` có mặc định owned-cloud.
Trình bao bọc của kho lưu trữ từ chối binary Crabbox cũ không quảng bá `blacksmith-testbox`. Truyền provider một cách tường minh dù `.crabbox.yaml` có các mặc định owned-cloud.
Changed gate:
Cổng kiểm tra thay đổi:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
@ -538,7 +538,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
```
Bộ đầy đủ:
Toàn bộ bộ kiểm thử:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
@ -553,14 +553,14 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
Đọc tóm tắt JSON cuối cùng. Các trường hữu ích là `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs`, và `totalMs`. Các lần chạy Crabbox một lượt được Blacksmith hỗ trợ sẽ tự động dừng Testbox; nếu một lần chạy bị gián đoạn hoặc việc dọn dẹp không rõ ràng, hãy kiểm tra các box đang hoạt động và chỉ dừng các box bạn đã tạo:
Đọc bản tóm tắt JSON cuối cùng. Các trường hữu ích là `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs`, và `totalMs`. Các lần chạy Crabbox một lần dùng Blacksmith làm backend nên tự động dừng Testbox; nếu một lần chạy bị ngắt hoặc việc dọn dẹp chưa rõ ràng, hãy kiểm tra các box đang hoạt động và chỉ dừng các box bạn đã tạo:
```bash
blacksmith testbox list
blacksmith testbox stop --id <tbx_id>
```
Chỉ dùng tái sử dụng khi bạn cố ý cần nhiều lệnh trên cùng một box đã hydrate:
Chỉ dùng tái sử dụng khi bạn chủ đích cần nhiều lệnh trên cùng một box đã được hydrate:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
@ -575,7 +575,7 @@ blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_id>
```
Chỉ nâng cấp sang năng lực Crabbox sở hữu khi Blacksmith ngừng hoạt động, bị giới hạn quota, thiếu môi trường cần thiết, hoặc năng lực sở hữu là mục tiêu rõ ràng:
Chỉ nâng cấp sang dung lượng Crabbox sở hữu khi Blacksmith ngừng hoạt động, bị giới hạn hạn ngạch, thiếu môi trường cần thiết, hoặc dung lượng sở hữu là mục tiêu rõ ràng:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
@ -584,7 +584,7 @@ pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` sở hữu các mặc định provider, đồng bộ, và hydrate GitHub Actions cho các lane owned-cloud. Nó loại trừ `.git` cục bộ để checkout Actions đã hydrate giữ metadata Git từ xa riêng thay vì đồng bộ các remote và object store cục bộ của maintainer, và nó loại trừ các artifact runtime/build cục bộ không bao giờ nên được truyền đi. `.github/workflows/crabbox-hydrate.yml` sở hữu checkout, thiết lập Node/pnpm, fetch `origin/main`, và bàn giao môi trường không chứa secret cho các lệnh owned-cloud `crabbox run --id <cbx_id>`.
`.crabbox.yaml` sở hữu các mặc định provider, đồng bộ, và hydrate GitHub Actions cho các lane owned-cloud. Nó loại trừ `.git` cục bộ để checkout Actions đã được hydrate giữ metadata Git từ xa riêng thay vì đồng bộ các remote và kho đối tượng cục bộ của maintainer, và nó loại trừ các artifact runtime/build cục bộ không bao giờ nên được truyền đi. `.github/workflows/crabbox-hydrate.yml` sở hữu checkout, thiết lập Node/pnpm, fetch `origin/main`, và bàn giao môi trường không phải secret cho các lệnh owned-cloud `crabbox run --id <cbx_id>`.
## Liên quan

19
docs/vi/cli/dashboard.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Bạn muốn mở giao diện điều khiển bằng token hiện tại của mình
- Bạn muốn mở giao diện điều khiển bằng mã thông báo hiện tại của mình
- Bạn muốn in URL mà không khởi chạy trình duyệt
summary: Tài liệu tham khảo CLI cho `openclaw dashboard` (mở Giao diện điều khiển)
title: Bảng điều khiển
x-i18n:
generated_at: "2026-04-29T22:31:16Z"
generated_at: "2026-05-05T01:44:20Z"
model: gpt-5.5
provider: openai
source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c
source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f
source_path: cli/dashboard.md
workflow: 16
---
@ -25,12 +25,15 @@ openclaw dashboard --no-open
Ghi chú:
- `dashboard` phân giải các SecretRefs `gateway.auth.token` đã cấu hình khi có thể.
- `dashboard` tuân theo `gateway.tls.enabled`: các Gateway bật TLS in/mở URL giao diện điều khiển
`https://` và kết nối qua `wss://`.
- Với các token do SecretRef quản lý (đã phân giải hoặc chưa phân giải), `dashboard` in/sao chép/mở URL không chứa token để tránh làm lộ bí mật bên ngoài trong đầu ra terminal, lịch sử clipboard hoặc đối số khởi chạy trình duyệt.
- Nếu `gateway.auth.token` do SecretRef quản lý nhưng chưa được phân giải trong đường dẫn lệnh này, lệnh sẽ in URL không chứa token và hướng dẫn khắc phục rõ ràng thay vì nhúng phần giữ chỗ token không hợp lệ.
- `dashboard` tuân theo `gateway.tls.enabled`: các gateway đã bật TLS sẽ in/mở
URL giao diện điều khiển dạng `https://` và kết nối qua `wss://`.
- Nếu việc gửi URL dashboard đã xác thực bằng mã thông báo qua clipboard/trình duyệt thất bại,
`dashboard` ghi nhật ký một gợi ý xác thực thủ công an toàn, nêu tên `OPENCLAW_GATEWAY_TOKEN`,
`gateway.auth.token`, và khóa fragment `token` mà không in giá trị mã thông báo.
- Đối với các mã thông báo do SecretRef quản lý (đã phân giải hoặc chưa phân giải), `dashboard` in/sao chép/mở một URL không chứa mã thông báo để tránh làm lộ bí mật bên ngoài trong đầu ra terminal, lịch sử clipboard hoặc đối số khởi chạy trình duyệt.
- Nếu `gateway.auth.token` do SecretRef quản lý nhưng chưa được phân giải trong đường dẫn lệnh này, lệnh sẽ in một URL không chứa mã thông báo và hướng dẫn khắc phục rõ ràng thay vì nhúng một placeholder mã thông báo không hợp lệ.
## Liên quan
- [Tham chiếu CLI](/vi/cli)
- [Bảng điều khiển](/vi/web/dashboard)
- [Dashboard](/vi/web/dashboard)

62
docs/vi/cli/doctor.md
View File

@ -2,20 +2,20 @@
read_when:
- 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: 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
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
x-i18n:
generated_at: "2026-05-04T02:22:30Z"
generated_at: "2026-05-05T01:44:14Z"
model: gpt-5.5
provider: openai
source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5
source_path: cli/doctor.md
workflow: 16
---
# `openclaw doctor`
Kiểm tra tình trạng + bản sửa nhanh cho Gateway và các kênh.
Kiểm tra sức khỏe + sửa nhanh cho Gateway và các kênh.
Liên quan:
@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token
## Tùy chọn
- `--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 đượ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
- `--no-workspace-suggestions`: tắt gợi ý bộ nhớ/tìm kiếm workspace
- `--yes`: chấp nhận mặc định mà không hỏi
- `--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 hỏi; 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 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ụ
- `--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ụ
- `--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 Gateway bổ sung
- `--deep`: quét các dịch vụ hệ thống để tìm các bản cài đặt Gateway bổ sung
Ghi chú:
- 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 đị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>`.
- 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ầ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 việc tải Plugin sớm để kiểm tra sức khỏe không giao diện vẫ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ị loại bỏ.
- `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 transcript 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ần chạy không giao diện giữ nguyên chúng.
- Doctor cũng quét `~/.openclaw/cron/jobs.json` (hoặc `cron.store`) để tìm 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ự 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 nhật ký sai về sự cố Gateway WhatsApp 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 bị thiếu được tham chiếu bởi cấu hình, chẳng hạn như `plugins.entries`, các kênh đã cấu hình, thiết lập provider/search đã cấu hình, hoặc runtime agent đã cấu hình. Trong quá trình cập nhật gói, doctor bỏ qua sửa chữa Plugin của trình quản lý gói cho đến khi hoán đổi gói hoàn tất; chạy lại `openclaw doctor --fix` sau đó nếu một Plugin đã cấu hình vẫn cần khôi phục. Nếu tải xuống thất bại, doctor báo cáo lỗi cài đặt và giữ mục Plugin đã cấu hình cho lần sửa chữ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, mục tiêu Heartbeat, và ghi đè mô hình kênh tương ứng khi việc 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 nó. Khởi động Gateway vốn đã 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ịch vụ cũ.
- Trên Linux, doctor bỏ qua các systemd unit không hoạt động nhưng giống Gateway bổ sung và không ghi lại metadata lệnh/entrypoint cho 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ầ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 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.
- 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 rõ `commands.ownerAllowFrom`.
- Doctor cảnh báo khi 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 home 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 home riêng biệt cho từng agent, vì vậy dùng `openclaw migrate codex --dry-run` để kiểm kê tài sản nên được chủ ý nâng cấp.
- Doctor cảnh báo khi Skills được 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 còn 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`) 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 có các tệp registry sandbox cũ (`~/.openclaw/sandbox/containers.json` hoặc `~/.openclaw/sandbox/browsers.json`), 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 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 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 đó.
- Sau các 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 với tiến trình doctor.
- Tự động phân giải username `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`
Nếu trước đây bạn đã chạy `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (hoặc `...PASSWORD`), giá trị đó ghi đè tệp cấu hình của bạn và có thể gây lỗi “không được ủy quyền” kéo dài.
Nếu trước đây bạn đã chạy `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (hoặc `...PASSWORD`), giá trị đó ghi đè tệp cấu hình của bạn và có thể gây lỗi “unauthorized” dai dẳng.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN

293
docs/vi/cli/gateway.md
View File

@ -1,28 +1,28 @@
---
read_when:
- Chạy Gateway từ CLI (môi trường phát triển hoặc máy chủ)
- Gỡ lỗi xác thực Gateway, các chế độ liên kết và kết nối
- Khám phá Gateway qua Bonjour (cục bộ + DNS-SD diện rộng)
- Gỡ lỗi xác thực Gateway, chế độ ràng buộc và khả năng kết nối
- Khám phá các Gateway qua Bonjour (DNS-SD cục bộ + diện rộng)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — chạy, truy vấn và phát hiện các Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — chạy, truy vấn và khám phá các Gateway
title: Gateway
x-i18n:
generated_at: "2026-05-02T22:17:25Z"
generated_at: "2026-05-05T01:44:30Z"
model: gpt-5.5
provider: openai
source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242
source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
source_path: cli/gateway.md
workflow: 16
---
Gateway là máy chủ WebSocket của OpenClaw (kênh, nút, phiên, hook). Các lệnh con trên trang này nằm dưới `openclaw gateway …`.
Gateway là máy chủ WebSocket của OpenClaw (kênh, nút, phiên, hook). Các lệnh con trong trang này nằm dưới `openclaw gateway …`.
<CardGroup cols={3}>
<Card title="Khám phá Bonjour" href="/vi/gateway/bonjour">
Thiết lập mDNS cục bộ + DNS-SD diện rộng.
</Card>
<Card title="Tổng quan khám phá" href="/vi/gateway/discovery">
Cách OpenClaw quảng bá và tìm Gateway.
<Card title="Tổng quan về khám phá" href="/vi/gateway/discovery">
Cách OpenClaw quảng bá và tìm gateway.
</Card>
<Card title="Cấu hình" href="/vi/gateway/configuration">
Các khóa cấu hình gateway cấp cao nhất.
@ -37,7 +37,7 @@ Chạy một tiến trình Gateway cục bộ:
openclaw gateway
```
Bí danh chạy tiền cảnh:
Bí danh chạy ở foreground:
```bash
openclaw gateway run
@ -46,11 +46,11 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="Hành vi khởi động">
- Theo mặc định, Gateway từ chối khởi động trừ khi `gateway.mode=local` được đặt trong `~/.openclaw/openclaw.json`. Dùng `--allow-unconfigured` cho các lần chạy ad-hoc/dev.
- `openclaw onboard --mode local` và `openclaw setup` được kỳ vọng sẽ ghi `gateway.mode=local`. Nếu tệp tồn tại nhưng thiếu `gateway.mode`, hãy xem đó là cấu hình bị hỏng hoặc bị ghi đè và sửa nó thay vì ngầm giả định chế độ cục bộ.
- Nếu tệp tồn tại và thiếu `gateway.mode`, Gateway xem đó là hư hại cấu hình đáng ngờ và từ chối "đoán local" thay bạn.
- Việc bind ra ngoài loopback mà không có xác thực sẽ bị chặn (lan can an toàn).
- `SIGUSR1` kích hoạt khởi động lại trong tiến trình khi được cho phép (`commands.restart` được bật theo mặc định; đặt `commands.restart: false` để chặn khởi động lại thủ công, trong khi công cụ/cấu hình gateway áp dụng/cập nhật vẫn được cho phép).
- Trình xử lý `SIGINT`/`SIGTERM` dừng tiến trình gateway, nhưng không khôi phục bất kỳ trạng thái terminal tùy chỉnh nào. Nếu bạn bọc CLI bằng TUI hoặc đầu vào raw-mode, hãy khôi phục terminal trước khi thoát.
- `openclaw onboard --mode local` và `openclaw setup` được kỳ vọng sẽ ghi `gateway.mode=local`. Nếu tệp tồn tại nhưng thiếu `gateway.mode`, hãy coi đó là cấu hình bị hỏng hoặc bị ghi đè và sửa nó thay vì ngầm giả định chế độ cục bộ.
- Nếu tệp tồn tại và thiếu `gateway.mode`, Gateway coi đó là hư hỏng cấu hình đáng ngờ và từ chối "đoán local" thay bạn.
- Việc bind vượt ra ngoài loopback mà không có xác thực sẽ bị chặn (rào chắn an toàn).
- `SIGUSR1` kích hoạt khởi động lại trong tiến trình khi được cho phép (`commands.restart` được bật theo mặc định; đặt `commands.restart: false` để chặn khởi động lại thủ công, trong khi công cụ/cấu hình gateway apply/update vẫn được phép).
- Các handler `SIGINT`/`SIGTERM` dừng tiến trình gateway, nhưng không khôi phục bất kỳ trạng thái terminal tùy chỉnh nào. Nếu bạn bọc CLI bằng TUI hoặc đầu vào raw-mode, hãy khôi phục terminal trước khi thoát.
</Accordion>
</AccordionGroup>
@ -58,10 +58,10 @@ openclaw gateway run
### Tùy chọn
<ParamField path="--port <port>" type="number">
Cổng WebSocket (mặc định lấy từ cấu hình/env; thường là `18789`).
Cổng WebSocket (mặc định đến từ cấu hình/env; thường là `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
Chế độ bind listener.
Chế độ bind của listener.
</ParamField>
<ParamField path="--auth <token|password>" type="string">
Ghi đè chế độ xác thực.
@ -82,16 +82,16 @@ openclaw gateway run
Đặt lại cấu hình Tailscale serve/funnel khi tắt.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
Cho phép khởi động gateway khi không có `gateway.mode=local` trong cấu hình. Chỉ bỏ qua cơ chế bảo vệ khởi động cho bootstrap ad-hoc/dev; không ghi hoặc sửa tệp cấu hình.
Cho phép gateway khởi động mà không có `gateway.mode=local` trong cấu hình. Chỉ bỏ qua guard khởi động cho bootstrap ad-hoc/dev; không ghi hoặc sửa tệp cấu hình.
</ParamField>
<ParamField path="--dev" type="boolean">
Tạo cấu hình dev + workspace nếu còn thiếu (bỏ qua BOOTSTRAP.md).
Tạo cấu hình dev + workspace nếu thiếu (bỏ qua BOOTSTRAP.md).
</ParamField>
<ParamField path="--reset" type="boolean">
Đặt lại cấu hình dev + thông tin xác thực + phiên + workspace (yêu cầu `--dev`).
</ParamField>
<ParamField path="--force" type="boolean">
Dừng mọi listener hiện có trên cổng đã chọn trước khi khởi động.
Kill mọi listener hiện có trên cổng đã chọn trước khi khởi động.
</ParamField>
<ParamField path="--verbose" type="boolean">
Nhật ký chi tiết.
@ -100,51 +100,61 @@ openclaw gateway run
Chỉ hiển thị nhật ký backend CLI trong console (và bật stdout/stderr).
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
Kiểu nhật ký WebSocket.
Kiểu nhật ký Websocket.
</ParamField>
<ParamField path="--compact" type="boolean">
Bí danh cho `--ws-log compact`.
</ParamField>
<ParamField path="--raw-stream" type="boolean">
Ghi sự kiện luồng mô hình thô vào jsonl.
Ghi nhật ký các sự kiện luồng mô hình thô vào jsonl.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
Đường dẫn jsonl của luồng thô.
</ParamField>
## Khởi động lại Gateway
```bash
openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` yêu cầu Gateway đang chạy preflight công việc OpenClaw đang hoạt động trước khi khởi động lại. Nếu các thao tác trong hàng đợi, phân phối phản hồi, lượt chạy nhúng, hoặc lượt chạy tác vụ đang hoạt động, Gateway báo cáo các blocker, gộp các yêu cầu khởi động lại an toàn bị trùng lặp, và khởi động lại sau khi công việc đang hoạt động được rút hết. `restart` thông thường giữ hành vi service-manager hiện có để tương thích. Chỉ dùng `--force` khi bạn rõ ràng muốn đường dẫn ghi đè ngay lập tức.
<Warning>
`--password` nội tuyến có thể bị lộ trong danh sách tiến trình cục bộ. Nên dùng `--password-file`, env, hoặc `gateway.auth.password` được hỗ trợ bởi SecretRef.
`--password` inline có thể bị lộ trong danh sách tiến trình cục bộ. Ưu tiên `--password-file`, env, hoặc `gateway.auth.password` được hỗ trợ bởi SecretRef.
</Warning>
### Profiling khởi động
- Đặt `OPENCLAW_GATEWAY_STARTUP_TRACE=1` để ghi thời gian từng pha trong quá trình khởi động Gateway, bao gồm độ trễ `eventLoopMax` theo từng pha và thời gian bảng tra cứu Plugin cho installed-index, manifest registry, lập kế hoạch khởi động và công việc owner-map.
- Đặt `OPENCLAW_DIAGNOSTICS=timeline` cùng `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` để ghi một timeline chẩn đoán khởi động JSONL theo best-effort cho các bộ kiểm thử QA bên ngoài. Bạn cũng có thể bật cờ bằng `diagnostics.flags: ["timeline"]` trong cấu hình; đường dẫn vẫn được cung cấp qua env. Thêm `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` để bao gồm các mẫu event-loop.
- Chạy `pnpm test:startup:gateway -- --runs 5 --warmup 1` để benchmark khởi động Gateway. Benchmark ghi lại đầu ra tiến trình đầu tiên, `/healthz`, `/readyz`, thời gian trace khởi động, độ trễ event-loop và chi tiết thời gian bảng tra cứu Plugin.
- Đặt `OPENCLAW_GATEWAY_STARTUP_TRACE=1` để ghi nhật ký thời gian từng pha trong khi Gateway khởi động, bao gồm độ trễ `eventLoopMax` theo từng pha và thời gian bảng tra cứu plugin cho installed-index, manifest registry, startup planning, và owner-map.
- Đặt `OPENCLAW_DIAGNOSTICS=timeline` cùng `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` để ghi timeline chẩn đoán khởi động JSONL theo best-effort cho các bộ kiểm thử QA bên ngoài. Bạn cũng có thể bật cờ bằng `diagnostics.flags: ["timeline"]` trong cấu hình; đường dẫn vẫn được cung cấp qua env. Thêm `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` để bao gồm các mẫu event-loop.
- Chạy `pnpm test:startup:gateway -- --runs 5 --warmup 1` để benchmark khởi động Gateway. Benchmark ghi lại đầu ra đầu tiên của tiến trình, `/healthz`, `/readyz`, thời gian startup trace, độ trễ event-loop, và chi tiết thời gian bảng tra cứu plugin.
## Truy vấn một Gateway đang chạy
## Truy vấn Gateway đang chạy
Tất cả lệnh truy vấn đều dùng WebSocket RPC.
<Tabs>
<Tab title="Chế độ đầu ra">
- Mặc định: dễ đọc cho người dùng (có màu trong TTY).
- `--json`: JSON để máy đọc (không styling/spinner).
- `--no-color` (hoặc `NO_COLOR=1`): tắt ANSI trong khi vẫn giữ bố cục cho người đọc.
- `--json`: JSON dễ đọc cho máy (không styling/spinner).
- `--no-color` (hoặc `NO_COLOR=1`): tắt ANSI trong khi vẫn giữ bố cục cho người dùng.
</Tab>
<Tab title="Tùy chọn dùng chung">
- `--url <url>`: URL WebSocket của Gateway.
- `--token <token>`: token Gateway.
- `--password <password>`: mật khẩu Gateway.
- `--timeout <ms>`: timeout/ngân sách thời gian (khác nhau theo lệnh).
- `--timeout <ms>`: timeout/ngân sách (khác nhau theo lệnh).
- `--expect-final`: chờ phản hồi "final" (lệnh gọi agent).
</Tab>
</Tabs>
<Note>
Khi bạn đặt `--url`, CLI không fallback về thông tin xác thực trong cấu hình hoặc môi trường. Truyền `--token` hoặc `--password` một cách tường minh. Thiếu thông tin xác thực tường minh là lỗi.
Khi bạn đặt `--url`, CLI không fallback về thông tin xác thực trong cấu hình hoặc môi trường. Truyền rõ ràng `--token` hoặc `--password`. Thiếu thông tin xác thực rõ ràng là lỗi.
</Note>
### `gateway health`
@ -153,11 +163,11 @@ Khi bạn đặt `--url`, CLI không fallback về thông tin xác thực trong
openclaw gateway health --url ws://127.0.0.1:18789
```
Endpoint HTTP `/healthz` là probe liveness: nó trả về khi máy chủ có thể trả lời HTTP. Endpoint HTTP `/readyz` nghiêm ngặt hơn và vẫn ở trạng thái đỏ khi sidecar Plugin khởi động, kênh hoặc hook đã cấu hình vẫn đang ổn định. Phản hồi readiness chi tiết cục bộ hoặc đã xác thực bao gồm khối chẩn đoán `eventLoop` với độ trễ event-loop, mức sử dụng event-loop, tỷ lệ lõi CPU và cờ `degraded`.
Endpoint HTTP `/healthz` là probe liveness: nó trả về khi máy chủ có thể trả lời HTTP. Endpoint HTTP `/readyz` nghiêm ngặt hơn và vẫn đỏ trong khi startup plugin sidecar, kênh, hoặc hook đã cấu hình vẫn đang ổn định. Phản hồi readiness chi tiết cục bộ hoặc đã xác thực bao gồm khối chẩn đoán `eventLoop` với độ trễ event-loop, mức sử dụng event-loop, tỷ lệ lõi CPU, và cờ `degraded`.
### `gateway usage-cost`
Lấy tóm tắt usage-cost từ nhật ký phiên.
Lấy tóm tắt chi phí sử dụng từ nhật ký phiên.
```bash
openclaw gateway usage-cost
@ -171,7 +181,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
Lấy bộ ghi ổn định chẩn đoán gần đây từ một Gateway đang chạy.
Lấy trình ghi ổn định chẩn đoán gần đây từ Gateway đang chạy.
```bash
openclaw gateway stability
@ -188,29 +198,29 @@ openclaw gateway stability --json
Lọc theo loại sự kiện chẩn đoán, chẳng hạn như `payload.large` hoặc `diagnostic.memory.pressure`.
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
Chỉ bao gồm sự kiện sau một số thứ tự chẩn đoán.
Chỉ bao gồm các sự kiện sau một số thứ tự chẩn đoán.
</ParamField>
<ParamField path="--bundle [path]" type="string">
Đọc một gói ổn định đã lưu thay vì gọi Gateway đang chạy. Dùng `--bundle latest` (hoặc chỉ `--bundle`) cho gói mới nhất trong thư mục trạng thái, hoặc truyền trực tiếp đường dẫn JSON của gói.
Đọc bundle ổn định đã lưu thay vì gọi Gateway đang chạy. Dùng `--bundle latest` (hoặc chỉ `--bundle`) cho bundle mới nhất trong thư mục trạng thái, hoặc truyền trực tiếp đường dẫn JSON của bundle.
</ParamField>
<ParamField path="--export" type="boolean">
Ghi một tệp zip chẩn đoán hỗ trợ có thể chia sẻ thay vì in chi tiết ổn định.
Ghi một zip chẩn đoán hỗ trợ có thể chia sẻ thay vì in chi tiết ổn định.
</ParamField>
<ParamField path="--output <path>" type="string">
Đường dẫn đầu ra cho `--export`.
</ParamField>
<AccordionGroup>
<Accordion title="Quyền riêng tư và hành vi gói">
- Bản ghi giữ siêu dữ liệu vận hành: tên sự kiện, số đếm, kích thước byte, số đọc bộ nhớ, trạng thái hàng đợi/phiên, tên kênh/Plugin và tóm tắt phiên đã biên tập. Chúng không giữ văn bản chat, nội dung webhook, đầu ra công cụ, nội dung yêu cầu hoặc phản hồi thô, token, cookie, giá trị bí mật, hostname hoặc id phiên thô. Đặt `diagnostics.enabled: false` để tắt hoàn toàn bộ ghi.
- Khi Gateway thoát do lỗi nghiêm trọng, timeout khi tắt và lỗi khởi động sau khi restart, OpenClaw ghi cùng snapshot chẩn đoán vào `~/.openclaw/logs/stability/openclaw-stability-*.json` khi bộ ghi có sự kiện. Kiểm tra gói mới nhất bằng `openclaw gateway stability --bundle latest`; `--limit`, `--type` và `--since-seq` cũng áp dụng cho đầu ra gói.
<Accordion title="Quyền riêng tư và hành vi bundle">
- Bản ghi giữ siêu dữ liệu vận hành: tên sự kiện, số lượng, kích thước byte, số đo bộ nhớ, trạng thái hàng đợi/phiên, tên kênh/plugin, và tóm tắt phiên đã biên tập. Chúng không giữ văn bản chat, nội dung webhook, đầu ra công cụ, nội dung yêu cầu hoặc phản hồi thô, token, cookie, giá trị bí mật, hostname, hoặc id phiên thô. Đặt `diagnostics.enabled: false` để tắt hoàn toàn trình ghi.
- Khi Gateway thoát nghiêm trọng, hết thời gian tắt, và khởi động lại thất bại khi startup, OpenClaw ghi cùng ảnh chụp chẩn đoán vào `~/.openclaw/logs/stability/openclaw-stability-*.json` khi trình ghi có sự kiện. Kiểm tra bundle mới nhất bằng `openclaw gateway stability --bundle latest`; `--limit`, `--type`, và `--since-seq` cũng áp dụng cho đầu ra bundle.
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
Ghi một tệp zip chẩn đoán cục bộ được thiết kế để đính kèm vào báo cáo lỗi. Để biết mô hình quyền riêng tư và nội dung gói, xem [Xuất chẩn đoán](/vi/gateway/diagnostics).
Ghi một zip chẩn đoán cục bộ được thiết kế để đính kèm vào báo cáo lỗi. Để biết mô hình quyền riêng tư và nội dung bundle, xem [Xuất chẩn đoán](/vi/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@ -219,7 +229,7 @@ openclaw gateway diagnostics export --json
```
<ParamField path="--output <path>" type="string">
Đường dẫn zip đầu ra. Mặc định là bản xuất hỗ trợ trong thư mục trạng thái.
Đường dẫn zip đầu ra. Mặc định là một bản xuất hỗ trợ trong thư mục trạng thái.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
Số dòng nhật ký đã làm sạch tối đa cần bao gồm.
@ -228,27 +238,27 @@ openclaw gateway diagnostics export --json
Số byte nhật ký tối đa cần kiểm tra.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket của Gateway cho snapshot health.
URL WebSocket của Gateway cho ảnh chụp health.
</ParamField>
<ParamField path="--token <token>" type="string">
Token Gateway cho snapshot health.
Token Gateway cho ảnh chụp health.
</ParamField>
<ParamField path="--password <password>" type="string">
Mật khẩu Gateway cho snapshot health.
Mật khẩu Gateway cho ảnh chụp health.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
Timeout snapshot trạng thái/health.
Timeout cho ảnh chụp trạng thái/health.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
Bỏ qua tra cứu gói ổn định đã lưu.
Bỏ qua tra cứu bundle ổn định đã lưu.
</ParamField>
<ParamField path="--json" type="boolean">
In đường dẫn đã ghi, kích thước và manifest dưới dạng JSON.
In đường dẫn đã ghi, kích thước, và manifest dưới dạng JSON.
</ParamField>
Bản xuất chứa một manifest, bản tóm tắt Markdown, hình dạng cấu hình, chi tiết cấu hình đã làm sạch, tóm tắt nhật ký đã làm sạch, snapshot trạng thái/health Gateway đã làm sạch và gói ổn định mới nhất nếu có.
Bản xuất chứa một manifest, tóm tắt Markdown, hình dạng cấu hình, chi tiết cấu hình đã làm sạch, tóm tắt nhật ký đã làm sạch, ảnh chụp trạng thái/health của Gateway đã làm sạch, và bundle ổn định mới nhất khi có.
Nó được thiết kế để chia sẻ. Nó giữ các chi tiết vận hành giúp gỡ lỗi, chẳng hạn như các trường nhật ký OpenClaw an toàn, tên hệ thống con, mã trạng thái, thời lượng, chế độ đã cấu hình, cổng, id Plugin, id provider, thiết lập tính năng không bí mật và thông điệp nhật ký vận hành đã biên tập. Nó bỏ qua hoặc biên tập văn bản chat, nội dung webhook, đầu ra công cụ, thông tin xác thực, cookie, mã định danh tài khoản/tin nhắn, văn bản prompt/hướng dẫn, hostname và giá trị bí mật. Khi một thông điệp kiểu LogTape trông giống văn bản payload người dùng/chat/công cụ, bản xuất chỉ giữ việc một thông điệp đã bị bỏ qua cùng số byte của nó.
Nó được thiết kế để chia sẻ. Nó giữ các chi tiết vận hành giúp gỡ lỗi, chẳng hạn như trường nhật ký OpenClaw an toàn, tên subsystem, mã trạng thái, thời lượng, chế độ đã cấu hình, cổng, id plugin, id provider, cài đặt tính năng không bí mật, và thông điệp nhật ký vận hành đã biên tập. Nó bỏ qua hoặc biên tập văn bản chat, nội dung webhook, đầu ra công cụ, thông tin xác thực, cookie, định danh tài khoản/tin nhắn, văn bản prompt/hướng dẫn, hostname, và giá trị bí mật. Khi một thông điệp kiểu LogTape trông giống văn bản payload người dùng/chat/công cụ, bản xuất chỉ giữ lại việc một thông điệp đã bị bỏ qua cùng số byte của nó.
### `gateway status`
@ -261,63 +271,63 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Thêm một mục tiêu probe tường minh. Remote đã cấu hình + localhost vẫn được probe.
Thêm một mục tiêu dò tìm rõ ràng. Remote đã cấu hình + localhost vẫn được dò tìm.
</ParamField>
<ParamField path="--token <token>" type="string">
Xác thực token cho probe.
Xác thực bằng token cho lần dò tìm.
</ParamField>
<ParamField path="--password <password>" type="string">
Xác thực mật khẩu cho probe.
Xác thực bằng mật khẩu cho lần dò tìm.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
Timeout probe.
Thời gian chờ dò tìm.
</ParamField>
<ParamField path="--no-probe" type="boolean">
Bỏ qua probe kết nối (chế độ xem chỉ dịch vụ).
Bỏ qua dò tìm kết nối (chỉ xem dịch vụ).
</ParamField>
<ParamField path="--deep" type="boolean">
Quét cả các dịch vụ cấp hệ thống.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Nâng cấp probe kết nối mặc định thành probe đọc và thoát khác không khi probe đọc đó thất bại. Không thể kết hợp với `--no-probe`.
Nâng cấp lần dò tìm kết nối mặc định thành dò tìm đọc và thoát với mã khác 0 khi lần dò tìm đọc đó thất bại. Không thể kết hợp với `--no-probe`.
</ParamField>
<AccordionGroup>
<Accordion title="Ngữ nghĩa trạng thái">
- `gateway status` vẫn khả dụng cho chẩn đoán ngay cả khi cấu hình CLI cục bộ bị thiếu hoặc không hợp lệ.
- Theo mặc định, `gateway status` xác minh trạng thái dịch vụ, kết nối WebSocket và khả năng xác thực hiển thị tại thời điểm handshake. Nó không xác minh các thao tác đọc/ghi/quản trị.
- Các phép dò chẩn đoán không gây thay đổi đối với xác thực thiết bị lần đầu: chúng tái sử dụng token thiết bị đã được lưu trong bộ nhớ đệm nếu có, nhưng không tạo danh tính thiết bị CLI mới hoặc bản ghi ghép đôi thiết bị chỉ đọc mới chỉ để kiểm tra trạng thái.
- `gateway status` phân giải các SecretRef xác thực đã cấu hình cho xác thực phép dò khi có thể.
- Nếu SecretRef xác thực bắt buộc không được phân giải trong luồng lệnh này, `gateway status --json` báo cáo `rpc.authWarning` khi kết nối/xác thực của phép dò thất bại; hãy truyền rõ ràng `--token`/`--password` hoặc phân giải nguồn bí mật trước.
- Nếu phép dò thành công, cảnh báo tham chiếu xác thực chưa phân giải sẽ bị ẩn để tránh cảnh báo sai.
- Dùng `--require-rpc` trong script và tự động hóa khi chỉ có dịch vụ đang lắng nghe là chưa đủ và bạn cũng cần các lệnh gọi RPC phạm vi đọc ở trạng thái khỏe mạnh.
- `--deep` thêm một lần quét best-effort để tìm các bản cài đặt launchd/systemd/schtasks bổ sung. Khi phát hiện nhiều dịch vụ giống Gateway, đầu ra dành cho người đọc in gợi ý dọn dẹp và cảnh báo rằng hầu hết thiết lập chỉ nên chạy một Gateway trên mỗi máy.
- Đầu ra dành cho người đọc bao gồm đường dẫn log tệp đã phân giải cùng ảnh chụp nhanh đường dẫn/tính hợp lệ của cấu hình CLI so với dịch vụ để giúp chẩn đoán drift profile hoặc state-dir.
<Accordion title="Status semantics">
- `gateway status` vẫn khả dụng để chẩn đoán ngay cả khi cấu hình CLI cục bộ bị thiếu hoặc không hợp lệ.
- `gateway status` mặc định xác minh trạng thái dịch vụ, kết nối WebSocket và khả năng xác thực nhìn thấy được tại thời điểm bắt tay. Nó không xác minh các thao tác đọc/ghi/quản trị.
- Các lần dò tìm chẩn đoán không gây thay đổi đối với xác thực thiết bị lần đầu: chúng dùng lại token thiết bị đã lưu trong bộ nhớ đệm hiện có khi có, nhưng không tạo danh tính thiết bị CLI mới hoặc bản ghi ghép đôi thiết bị chỉ đọc chỉ để kiểm tra trạng thái.
- `gateway status` phân giải các SecretRefs xác thực đã cấu hình cho xác thực dò tìm khi có thể.
- Nếu SecretRef xác thực bắt buộc chưa được phân giải trong đường dẫn lệnh này, `gateway status --json` báo cáo `rpc.authWarning` khi kết nối/xác thực dò tìm thất bại; truyền rõ `--token`/`--password` hoặc phân giải nguồn secret trước.
- Nếu lần dò tìm thành công, cảnh báo auth-ref chưa phân giải sẽ bị ẩn để tránh báo sai.
- Dùng `--require-rpc` trong script và tự động hóa khi chỉ có dịch vụ đang lắng nghe là chưa đủ và bạn cũng cần các lệnh gọi RPC phạm vi đọc hoạt động tốt.
- `--deep` thêm một lần quét nỗ lực tối đa cho các bản cài đặt launchd/systemd/schtasks bổ sung. Khi phát hiện nhiều dịch vụ giống Gateway, đầu ra cho người dùng in gợi ý dọn dẹp và cảnh báo rằng hầu hết thiết lập nên chạy một Gateway trên mỗi máy.
- Đầu ra cho người dùng bao gồm đường dẫn log tệp đã phân giải cộng với ảnh chụp nhanh đường dẫn/tính hợp lệ cấu hình CLI so với dịch vụ để giúp chẩn đoán sai lệch profile hoặc thư mục trạng thái.
</Accordion>
<Accordion title="Kiểm tra drift xác thực Linux systemd">
- Trên các bản cài đặt Linux systemd, kiểm tra drift xác thực dịch vụ đọc cả giá trị `Environment=` và `EnvironmentFile=` từ unit (bao gồm `%h`, đường dẫn được trích dẫn, nhiều tệp và các tệp `-` tùy chọn).
- Kiểm tra drift phân giải SecretRef `gateway.auth.token` bằng môi trường runtime đã hợp nhất (môi trường lệnh dịch vụ trước, rồi fallback về môi trường tiến trình).
- Nếu xác thực bằng token không thực sự hoạt động (`gateway.auth.mode` được đặt rõ là `password`/`none`/`trusted-proxy`, hoặc mode chưa đặt trong đó password có thể được chọn và không ứng viên token nào có thể được chọn), kiểm tra drift token sẽ bỏ qua phân giải token cấu hình.
<Accordion title="Linux systemd auth-drift checks">
- Trên các bản cài đặt Linux systemd, kiểm tra sai lệch xác thực dịch vụ đọc cả giá trị `Environment=` và `EnvironmentFile=` từ unit (bao gồm `%h`, đường dẫn có dấu ngoặc kép, nhiều tệp và các tệp tùy chọn có tiền tố `-`).
- Kiểm tra sai lệch phân giải SecretRefs `gateway.auth.token` bằng env runtime đã hợp nhất (env lệnh dịch vụ trước, sau đó dự phòng bằng env tiến trình).
- Nếu xác thực token thực tế không hoạt động (`gateway.auth.mode` rõ ràng là `password`/`none`/`trusted-proxy`, hoặc mode chưa đặt trong đó mật khẩu có thể thắng và không ứng viên token nào có thể thắng), kiểm tra sai lệch token bỏ qua phân giải token cấu hình.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` là lệnh "gỡ lỗi mọi thứ". Nó luôn dò:
`gateway probe` là lệnh "gỡ lỗi mọi thứ". Nó luôn dò tìm:
- Gateway từ xa đã cấu hình của bạn (nếu có), và
- Gateway remote đã cấu hình của bạn (nếu đã đặt), và
- localhost (loopback) **ngay cả khi remote đã được cấu hình**.
Nếu bạn truyền `--url`, đích rõ ràng đó được thêm trước cả hai. Đầu ra dành cho người đọc gắn nhãn các đích là:
Nếu bạn truyền `--url`, mục tiêu rõ ràng đó được thêm vào trước cả hai. Đầu ra cho người dùng gắn nhãn các mục tiêu là:
- `URL (explicit)`
- `Remote (configured)` hoặc `Remote (configured, inactive)`
- `Local loopback`
<Note>
Nếu có thể truy cập nhiều Gateway, lệnh sẽ in tất cả. Nhiều Gateway được hỗ trợ khi bạn dùng các hồ sơ/cổng tách biệt (ví dụ: một bot cứu hộ), nhưng hầu hết bản cài đặt vẫn chạy một Gateway duy nhất.
Nếu nhiều Gateway có thể truy cập được, lệnh sẽ in tất cả. Nhiều Gateway được hỗ trợ khi bạn dùng profile/cổng tách biệt (ví dụ: bot cứu hộ), nhưng hầu hết bản cài đặt vẫn chạy một Gateway duy nhất.
</Note>
```bash
@ -326,54 +336,54 @@ openclaw gateway probe --json
```
<AccordionGroup>
<Accordion title="Diễn giải">
- `Reachable: yes` nghĩa là ít nhất một đích đã chấp nhận kết nối WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` báo cáo điều mà phép dò có thể xác minh về xác thực. Nó tách biệt với khả năng truy cập.
- `Read probe: ok` nghĩa là các lệnh gọi RPC chi tiết thuộc phạm vi đọc (`health`/`status`/`system-presence`/`config.get`) cũng thành công.
- `Read probe: limited - missing scope: operator.read` nghĩa là kết nối thành công nhưng RPC phạm vi đọc bị giới hạn. Điều này được báo cáo là khả năng truy cập **suy giảm**, không phải thất bại hoàn toàn.
<Accordion title="Interpretation">
- `Reachable: yes` nghĩa là ít nhất một mục tiêu đã chấp nhận kết nối WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` báo cáo những gì lần dò tìm có thể xác minh về xác thực. Nó tách biệt với khả năng truy cập.
- `Read probe: ok` nghĩa là các lệnh gọi RPC chi tiết phạm vi đọc (`health`/`status`/`system-presence`/`config.get`) cũng thành công.
- `Read probe: limited - missing scope: operator.read` nghĩa là kết nối thành công nhưng RPC phạm vi đọc bị giới hạn. Trạng thái này được báo cáo là khả năng truy cập **suy giảm**, không phải thất bại hoàn toàn.
- `Read probe: failed` sau `Connect: ok` nghĩa là Gateway đã chấp nhận kết nối WebSocket, nhưng chẩn đoán đọc tiếp theo đã hết thời gian chờ hoặc thất bại. Đây cũng là khả năng truy cập **suy giảm**, không phải Gateway không thể truy cập.
- Giống `gateway status`, phép dò tái sử dụng xác thực thiết bị đã lưu trong bộ nhớ đệm nhưng không tạo danh tính thiết bị lần đầu hoặc trạng thái ghép đôi.
- Mã thoát chỉ khác 0 khi không có đích nào được dò có thể truy cập.
- Giống `gateway status`, probe dùng lại xác thực thiết bị đã lưu trong bộ nhớ đệm hiện có nhưng không tạo danh tính thiết bị lần đầu hoặc trạng thái ghép đôi.
- Mã thoát khác 0 chỉ khi không có mục tiêu được dò tìm nào có thể truy cập.
</Accordion>
<Accordion title="Đầu ra JSON">
Cấp trên cùng:
<Accordion title="JSON output">
Cấp cao nhất:
- `ok`: ít nhất một đích có thể truy cập.
- `degraded`: ít nhất một đích đã chấp nhận kết nối nhưng không hoàn tất chẩn đoán RPC chi tiết đầy đủ.
- `capability`: khả năng tốt nhất thấy được trên các đích có thể truy cập (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, hoặc `unknown`).
- `primaryTargetId`: đích tốt nhất để xem là đích thắng đang hoạt động theo thứ tự này: URL rõ ràng, đường hầm SSH, remote đã cấu hình, rồi local loopback.
- `warnings[]`: bản ghi cảnh báo best-effort với `code`, `message` và `targetIds` tùy chọn.
- `network`: gợi ý URL local loopback/tailnet được suy ra từ cấu hình hiện tại và mạng của host.
- `discovery.timeoutMs` và `discovery.count`: ngân sách khám phá/số lượng kết quả thực tế được dùng cho lượt dò này.
- `ok`: ít nhất một mục tiêu có thể truy cập.
- `degraded`: ít nhất một mục tiêu đã chấp nhận kết nối nhưng không hoàn tất chẩn đoán RPC chi tiết đầy đủ.
- `capability`: khả năng tốt nhất nhìn thấy trên các mục tiêu có thể truy cập (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, hoặc `unknown`).
- `primaryTargetId`: mục tiêu tốt nhất để coi là mục tiêu thắng đang hoạt động theo thứ tự này: URL rõ ràng, đường hầm SSH, remote đã cấu hình, rồi local loopback.
- `warnings[]`: bản ghi cảnh báo nỗ lực tối đa với `code`, `message` và `targetIds` tùy chọn.
- `network`: gợi ý URL local loopback/tailnet bắt nguồn từ cấu hình hiện tại và mạng của host.
- `discovery.timeoutMs` và `discovery.count`: ngân sách/kết quả đếm khám phá thực tế được dùng cho lượt dò tìm này.
Theo từng đích (`targets[].connect`):
Theo từng mục tiêu (`targets[].connect`):
- `ok`: khả năng truy cập sau kết nối + phân loại suy giảm.
- `rpcOk`: RPC chi tiết đầy đủ thành công.
- `scopeLimited`: RPC chi tiết thất bại do thiếu phạm vi operator.
Theo từng đích (`targets[].auth`):
Theo từng mục tiêu (`targets[].auth`):
- `role`: vai trò xác thực được báo cáo trong `hello-ok` khi có.
- `scopes`: các phạm vi được cấp được báo cáo trong `hello-ok` khi có.
- `capability`: phân loại khả năng xác thực được hiển thị cho đích đó.
- `capability`: phân loại khả năng xác thực được hiển thị cho mục tiêu đó.
</Accordion>
<Accordion title="Mã cảnh báo thường gặp">
- `ssh_tunnel_failed`: thiết lập đường hầm SSH thất bại; lệnh đã fallback về các phép dò trực tiếp.
- `multiple_gateways`: có thể truy cập nhiều hơn một đích; điều này bất thường trừ khi bạn cố ý chạy các hồ sơ tách biệt, chẳng hạn như bot cứu hộ.
- `auth_secretref_unresolved`: không thể phân giải SecretRef xác thực đã cấu hình cho một đích thất bại.
- `probe_scope_limited`: kết nối WebSocket thành công, nhưng phép dò đọc bị giới hạn do thiếu `operator.read`.
<Accordion title="Common warning codes">
- `ssh_tunnel_failed`: thiết lập đường hầm SSH thất bại; lệnh đã chuyển về dò tìm trực tiếp.
- `multiple_gateways`: có thể truy cập nhiều hơn một mục tiêu; điều này không bình thường trừ khi bạn cố ý chạy các profile tách biệt, chẳng hạn như bot cứu hộ.
- `auth_secretref_unresolved`: không thể phân giải SecretRef xác thực đã cấu hình cho một mục tiêu thất bại.
- `probe_scope_limited`: kết nối WebSocket thành công, nhưng dò tìm đọc bị giới hạn do thiếu `operator.read`.
</Accordion>
</AccordionGroup>
#### Từ xa qua SSH (tương đương với ứng dụng Mac)
#### Remote qua SSH (ngang bằng ứng dụng Mac)
Chế độ "Từ xa qua SSH" của ứng dụng macOS dùng một chuyển tiếp cổng cục bộ để Gateway từ xa (có thể chỉ lắng nghe trên loopback) có thể truy cập tại `ws://127.0.0.1:<port>`.
Chế độ "Remote over SSH" của ứng dụng macOS dùng chuyển tiếp cổng cục bộ để Gateway remote (có thể chỉ được bind với loopback) có thể truy cập tại `ws://127.0.0.1:<port>`.
Tương đương trên CLI:
Tương đương trong CLI:
```bash
openclaw gateway probe --ssh user@gateway-host
@ -383,10 +393,10 @@ openclaw gateway probe --ssh user@gateway-host
`user@host` hoặc `user@host:port` (cổng mặc định là `22`).
</ParamField>
<ParamField path="--ssh-identity <path>" type="string">
Tệp định danh.
Tệp danh tính.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Chọn host Gateway đầu tiên được phát hiện làm đích SSH từ endpoint khám phá đã phân giải (`local.` cộng với miền diện rộng đã cấu hình, nếu có). Các gợi ý chỉ có TXT bị bỏ qua.
Chọn host Gateway đầu tiên được phát hiện làm mục tiêu SSH từ endpoint khám phá đã phân giải (`local.` cộng với miền diện rộng đã cấu hình, nếu có). Các gợi ý chỉ TXT bị bỏ qua.
</ParamField>
Cấu hình (tùy chọn, dùng làm mặc định):
@ -396,7 +406,7 @@ Cấu hình (tùy chọn, dùng làm mặc định):
### `gateway call <method>`
Trợ giúp RPC cấp thấp.
Trình trợ giúp RPC cấp thấp.
```bash
openclaw gateway call status
@ -410,7 +420,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
URL WebSocket của Gateway.
</ParamField>
<ParamField path="--token <token>" type="string">
Token của Gateway.
Token Gateway.
</ParamField>
<ParamField path="--password <password>" type="string">
Mật khẩu Gateway.
@ -419,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Ngân sách thời gian chờ.
</ParamField>
<ParamField path="--expect-final" type="boolean">
Chủ yếu dành cho các RPC kiểu tác tử truyền phát các sự kiện trung gian trước phần dữ liệu cuối cùng.
Chủ yếu dành cho RPC kiểu agent phát luồng sự kiện trung gian trước payload cuối cùng.
</ParamField>
<ParamField path="--json" type="boolean">
Đầu ra JSON máy có thể đọc.
Đầu ra JSON cho máy đọc.
</ParamField>
<Note>
@ -439,11 +449,9 @@ openclaw gateway restart
openclaw gateway uninstall
```
### Cài đặt với trình bao bọc
### Cài đặt với wrapper
Dùng `--wrapper` khi dịch vụ được quản lý phải khởi động thông qua một tệp thực thi khác, ví dụ một
shim của trình quản lý bí mật hoặc trợ giúp chạy với tư cách khác. Trình bao bọc nhận các đối số Gateway bình thường và
chịu trách nhiệm cuối cùng gọi exec `openclaw` hoặc Node với các đối số đó.
Dùng `--wrapper` khi dịch vụ được quản lý phải khởi động thông qua một executable khác, ví dụ như shim trình quản lý secret hoặc trình trợ giúp run-as. Wrapper nhận các đối số Gateway bình thường và chịu trách nhiệm cuối cùng exec `openclaw` hoặc Node với các đối số đó.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -457,16 +465,14 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
Bạn cũng có thể đặt trình bao bọc thông qua môi trường. `gateway install` xác thực rằng đường dẫn là
một tệp thực thi, ghi trình bao bọc vào `ProgramArguments` của dịch vụ và lưu bền vững
`OPENCLAW_WRAPPER` trong môi trường dịch vụ cho các lần cài đặt lại bắt buộc, cập nhật và sửa chữa bằng doctor sau này.
Bạn cũng có thể đặt wrapper thông qua môi trường. `gateway install` xác thực rằng đường dẫn là một tệp executable, ghi wrapper vào `ProgramArguments` của dịch vụ và lưu `OPENCLAW_WRAPPER` trong môi trường dịch vụ cho các lần cài đặt lại bắt buộc, cập nhật và sửa chữa doctor sau này.
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
```
Để xóa trình bao bọc đã lưu bền vững, hãy xóa `OPENCLAW_WRAPPER` trong khi cài đặt lại:
Để xóa wrapper đã lưu, hãy xóa `OPENCLAW_WRAPPER` trong khi cài đặt lại:
```bash
OPENCLAW_WRAPPER= openclaw gateway install --force
@ -474,48 +480,49 @@ openclaw gateway restart
```
<AccordionGroup>
<Accordion title="Tùy chọn lệnh">
<Accordion title="Command options">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
- `gateway restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="Hành vi vòng đời">
- Dùng `gateway restart` để khởi động lại dịch vụ được quản lý. Không nối chuỗi `gateway stop` và `gateway start` để thay thế cho restart; trên macOS, `gateway stop` cố ý vô hiệu hóa LaunchAgent trước khi dừng nó.
- `gateway restart --wait 30s` ghi đè ngân sách drain khởi động lại đã cấu hình cho lần khởi động lại đó. Số không kèm đơn vị là mili giây; các đơn vị như `s`, `m` và `h` được chấp nhận. `--wait 0` chờ vô thời hạn.
- `gateway restart --force` bỏ qua drain công việc đang hoạt động và khởi động lại ngay lập tức. Dùng tùy chọn này khi một operator đã kiểm tra các tác vụ chặn được liệt kê và muốn đưa Gateway trở lại ngay.
<Accordion title="Lifecycle behavior">
- Dùng `gateway restart` để khởi động lại dịch vụ được quản lý. Đừng nối chuỗi `gateway stop` và `gateway start` để thay thế restart; trên macOS, `gateway stop` cố ý tắt LaunchAgent trước khi dừng nó.
- `gateway restart --safe` yêu cầu Gateway đang chạy preflight công việc OpenClaw đang hoạt động và trì hoãn restart cho đến khi việc gửi trả lời, các lần chạy nhúng và các lần chạy tác vụ rút hết. `--safe` không thể kết hợp với `--force` hoặc `--wait`.
- `gateway restart --wait 30s` ghi đè ngân sách drain restart đã cấu hình cho lần restart đó. Số không kèm đơn vị là mili giây; các đơn vị như `s`, `m` và `h` được chấp nhận. `--wait 0` chờ vô thời hạn.
- `gateway restart --force` bỏ qua drain công việc đang hoạt động và restart ngay lập tức. Dùng tùy chọn này khi operator đã kiểm tra các bộ chặn tác vụ được liệt kê và muốn Gateway hoạt động trở lại ngay.
- Các lệnh vòng đời chấp nhận `--json` để viết script.
</Accordion>
<Accordion title="Xác thực và SecretRef tại thời điểm cài đặt">
- Khi xác thực bằng token yêu cầu token và `gateway.auth.token` do SecretRef quản lý, `gateway install` xác thực rằng SecretRef có thể phân giải nhưng không lưu bền vững token đã phân giải vào siêu dữ liệu môi trường dịch vụ.
- Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình không được phân giải, quá trình cài đặt sẽ thất bại theo hướng an toàn thay vì lưu bền vững plaintext fallback.
- Với xác thực bằng mật khẩu trên `gateway run`, hãy ưu tiên `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` hoặc `gateway.auth.password` dựa trên SecretRef thay vì `--password` trực tiếp trên dòng lệnh.
- Trong chế độ xác thực suy luận, `OPENCLAW_GATEWAY_PASSWORD` chỉ đặt trong shell không nới lỏng yêu cầu token khi cài đặt; hãy dùng cấu hình bền vững (`gateway.auth.password` hoặc cấu hình `env`) khi cài đặt dịch vụ được quản lý.
- Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, quá trình cài đặt bị chặn cho đến khi mode được đặt rõ ràng.
<Accordion title="Auth and SecretRefs at install time">
- Khi xác thực bằng token yêu cầu token và `gateway.auth.token` được quản lý bằng SecretRef, `gateway install` xác thực rằng SecretRef có thể phân giải được nhưng không lưu token đã phân giải vào siêu dữ liệu môi trường dịch vụ.
- Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, quá trình cài đặt sẽ thất bại theo hướng an toàn thay vì lưu văn bản thuần dự phòng.
- Với xác thực bằng mật khẩu trên `gateway run`, hãy ưu tiên `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, hoặc `gateway.auth.password` dựa trên SecretRef thay vì `--password` nội tuyến.
- Ở chế độ xác thực suy luận, `OPENCLAW_GATEWAY_PASSWORD` chỉ có trong shell không nới lỏng yêu cầu token khi cài đặt; hãy dùng cấu hình bền vững (`gateway.auth.password` hoặc `env` trong cấu hình) khi cài đặt một dịch vụ được quản lý.
- Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, quá trình cài đặt sẽ bị chặn cho đến khi chế độ được đặt rõ ràng.
</Accordion>
</AccordionGroup>
## Khám phá các Gateway (Bonjour)
## Khám phá gateway (Bonjour)
`gateway discover` quét tìm tín hiệu quảng bá Gateway (`_openclaw-gw._tcp`).
`gateway discover` quét các beacon Gateway (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Bonjour diện rộng): chọn một miền (ví dụ: `openclaw.internal.`) và thiết lập split DNS + máy chủ DNS; xem [Bonjour](/vi/gateway/bonjour).
- DNS-SD multicast: `local.`
- DNS-SD unicast (Bonjour diện rộng): chọn một miền (ví dụ: `openclaw.internal.`) và thiết lập DNS phân tách + một máy chủ DNS; xem [Bonjour](/vi/gateway/bonjour).
Chỉ các Gateway bật khám phá Bonjour (mặc định) mới quảng bá tín hiệu này.
Chỉ những gateway đã bật khám phá Bonjour (mặc định) mới quảng bá beacon.
Các bản ghi khám phá diện rộng bao gồm (TXT):
Bản ghi khám phá diện rộng bao gồm (TXT):
- `role` (gợi ý vai trò Gateway)
- `transport` (gợi ý phương thức vận chuyển, ví dụ `gateway`)
- `role` (gợi ý vai trò gateway)
- `transport` (gợi ý transport, ví dụ `gateway`)
- `gatewayPort` (cổng WebSocket, thường là `18789`)
- `sshPort` (tùy chọn; client mặc định đích SSH là `22` khi không có)
- `tailnetDns` (hostname MagicDNS, khi có)
- `gatewayTls` / `gatewayTlsSha256` (TLS đã bật + dấu vân tay chứng chỉ)
- `cliPath` (gợi ý cài đặt từ xa được ghi vào zone diện rộng)
- `sshPort` (tùy chọn; client mặc định mục tiêu SSH là `22` khi mục này vắng mặt)
- `tailnetDns` (tên máy chủ MagicDNS, khi có)
- `gatewayTls` / `gatewayTlsSha256` (TLS đã bật + vân tay chứng chỉ)
- `cliPath` (gợi ý cài đặt từ xa được ghi vào vùng diện rộng)
### `gateway discover`
@ -524,10 +531,10 @@ openclaw gateway discover
```
<ParamField path="--timeout <ms>" type="number" default="2000">
Thời gian chờ cho mỗi lệnh (duyệt/phân giải).
Thời gian chờ cho mỗi lệnh (browse/resolve).
</ParamField>
<ParamField path="--json" type="boolean">
Đầu ra máy có thể đọc được (cũng tắt định kiểu/chỉ báo xoay).
Đầu ra máy đọc được (đồng thời tắt styling/spinner).
</ParamField>
Ví dụ:
@ -538,9 +545,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- CLI quét `local.` cùng với miền diện rộng đã cấu hình khi miền đó được bật.
- `wsUrl` trong đầu ra JSON được suy ra từ điểm cuối dịch vụ đã phân giải, không phải từ các gợi ý chỉ TXT như `lanHost` hoặc `tailnetDns`.
- Trên mDNS `local.`, `sshPort` và `cliPath` chỉ được quảng bá khi `discovery.mdns.mode` là `full`. DNS-SD diện rộng vẫn ghi `cliPath`; `sshPort` cũng vẫn là tùy chọn ở đó.
- CLI quét `local.` cùng với miền diện rộng đã cấu hình khi có miền được bật.
- `wsUrl` trong đầu ra JSON được suy ra từ điểm cuối dịch vụ đã phân giải, không phải từ các gợi ý chỉ có trong TXT như `lanHost` hoặc `tailnetDns`.
- Trên mDNS `local.`, `sshPort` và `cliPath` chỉ được phát khi `discovery.mdns.mode` là `full`. DNS-SD diện rộng vẫn ghi `cliPath`; `sshPort` cũng vẫn là tùy chọn ở đó.
</Note>

221
docs/vi/cli/plugins.md
View File

@ -1,36 +1,36 @@
---
read_when:
- Bạn muốn cài đặt hoặc quản lý các Plugin Gateway hoặc các gói tương thích
- Bạn muốn gỡ lỗi các lỗi tải Plugin
- Bạn muốn gỡ lỗi các sự cố tải Plugin
sidebarTitle: Plugins
summary: Tài liệu tham khảo CLI cho `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: Plugin
x-i18n:
generated_at: "2026-05-04T09:37:04Z"
generated_at: "2026-05-05T01:44:20Z"
model: gpt-5.5
provider: openai
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a
source_path: cli/plugins.md
workflow: 16
---
Quản lý các Plugin Gateway, gói hook và bundle tương thích.
Quản lý Plugin Gateway, gói hook và các bundle tương thích.
<CardGroup cols={2}>
<Card title="Hệ thống Plugin" href="/vi/tools/plugin">
Hướng dẫn cho người dùng cuối về cài đặt, bật và khắc phục sự cố plugin.
Hướng dẫn dành cho người dùng cuối về cách cài đặt, bật và khắc phục sự cố plugin.
</Card>
<Card title="Quản lý plugin" href="/vi/plugins/manage-plugins">
Ví dụ nhanh cho cài đặt, liệt kê, cập nhật, gỡ cài đặt và xuất bản.
Ví dụ nhanh cho cài đặt, liệt kê, cập nhật, gỡ cài đặt và phát hành.
</Card>
<Card title="Bundle Plugin" href="/vi/plugins/bundles">
Mô hình tương thích của bundle.
Mô hình tương thích bundle.
</Card>
<Card title="Manifest Plugin" href="/vi/plugins/manifest">
Các trường manifest và schema cấu hình.
</Card>
<Card title="Bảo mật" href="/vi/gateway/security">
Tăng cường bảo mật cho các bản cài đặt plugin.
Gia cố bảo mật cho các lượt cài đặt plugin.
</Card>
</CardGroup>
@ -62,16 +62,14 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Để điều tra thao tác cài đặt, kiểm tra, gỡ cài đặt hoặc làm mới registry bị chậm, hãy chạy
lệnh với `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace ghi thời lượng từng pha
vào stderr và vẫn giữ đầu ra JSON có thể phân tích cú pháp. Xem [Gỡ lỗi](/vi/help/debugging#plugin-lifecycle-trace).
Để điều tra các thao tác cài đặt, kiểm tra, gỡ cài đặt hoặc làm mới registry bị chậm, hãy chạy lệnh với `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace ghi thời lượng từng pha vào stderr và giữ cho đầu ra JSON vẫn có thể phân tích cú pháp. Xem [Gỡ lỗi](/vi/help/debugging#plugin-lifecycle-trace).
<Note>
Plugin đi kèm được phân phối cùng OpenClaw. Một số được bật theo mặc định (ví dụ: nhà cung cấp mô hình đi kèm, nhà cung cấp giọng nói đi kèm và plugin trình duyệt đi kèm); các plugin khác yêu cầu `plugins enable`.
Plugin được đóng gói sẵn đi kèm OpenClaw. Một số được bật theo mặc định (ví dụ các nhà cung cấp mô hình đóng gói sẵn, nhà cung cấp giọng nói đóng gói sẵn và plugin trình duyệt đóng gói sẵn); những plugin khác yêu cầu `plugins enable`.
Plugin OpenClaw gốc phải phân phối `openclaw.plugin.json` với JSON Schema nội tuyến (`configSchema`, ngay cả khi rỗng). Các bundle tương thích dùng manifest bundle riêng của chúng.
Plugin OpenClaw native phải đi kèm `openclaw.plugin.json` với JSON Schema inline (`configSchema`, ngay cả khi trống). Các bundle tương thích dùng manifest bundle riêng của chúng.
`plugins list` hiển thị `Format: openclaw` hoặc `Format: bundle`. Đầu ra list/info dạng verbose cũng hiển thị subtype của bundle (`codex`, `claude` hoặc `cursor`) cùng các capability bundle được phát hiện.
`plugins list` hiển thị `Format: openclaw` hoặc `Format: bundle`. Đầu ra list/info chi tiết cũng hiển thị kiểu phụ của bundle (`codex`, `claude` hoặc `cursor`) cùng các năng lực bundle được phát hiện.
</Note>
### Cài đặt
@ -93,108 +91,100 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
Tên package trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi khi ra mắt. Dùng `clawhub:<package>` cho ClawHub. Hãy coi việc cài đặt plugin như chạy mã. Ưu tiên các phiên bản đã ghim.
Tên package trần sẽ cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi ra mắt. Dùng `clawhub:<package>` cho ClawHub. Hãy xem việc cài đặt plugin như chạy mã. Ưu tiên các phiên bản đã ghim.
</Warning>
`plugins search` truy vấn ClawHub để tìm các package plugin có thể cài đặt và in ra
tên package sẵn sàng cài đặt. Lệnh này tìm kiếm package code-plugin và bundle-plugin,
không phải Skills. Dùng `openclaw skills search` cho Skills trên ClawHub.
`plugins search` truy vấn ClawHub để tìm các package plugin có thể cài đặt và in ra tên package sẵn sàng cài đặt. Lệnh này tìm kiếm các package code-plugin và bundle-plugin, không tìm skills. Dùng `openclaw skills search` cho ClawHub skills.
<Note>
ClawHub là bề mặt phân phối và khám phá chính cho hầu hết plugin. Npm
vẫn là đường dẫn dự phòng và cài đặt trực tiếp được hỗ trợ. Các package plugin
`@openclaw/*` do OpenClaw sở hữu đã được xuất bản lại trên npm; xem danh sách hiện tại
trên [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) hoặc
[kho plugin](/vi/plugins/plugin-inventory). Bản cài đặt ổn định dùng `latest`.
Bản cài đặt và cập nhật kênh beta ưu tiên dist-tag `beta` của npm khi tag đó
có sẵn, rồi quay về `latest`.
ClawHub là bề mặt phân phối và khám phá chính cho hầu hết plugin. Npm vẫn là đường dẫn dự phòng được hỗ trợ và đường dẫn cài đặt trực tiếp. Các package plugin `@openclaw/*` do OpenClaw sở hữu đã được phát hành lại trên npm; xem danh sách hiện tại trên [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) hoặc [kho plugin](/vi/plugins/plugin-inventory). Cài đặt ổn định dùng `latest`. Các lượt cài đặt và cập nhật kênh beta ưu tiên dist-tag npm `beta` khi tag đó có sẵn, rồi quay về `latest`.
</Note>
<AccordionGroup>
<Accordion title="Config include và sửa cấu hình không hợp lệ">
Nếu phần `plugins` của bạn được hỗ trợ bởi một `$include` một tệp, `plugins install/update/enable/disable/uninstall` sẽ ghi xuyên tới tệp được include đó và giữ nguyên `openclaw.json`. Include gốc, mảng include và include có override cùng cấp sẽ fail closed thay vì làm phẳng. Xem [Config include](/vi/gateway/configuration) để biết các dạng được hỗ trợ.
<Accordion title="Config includes và sửa cấu hình không hợp lệ">
Nếu phần `plugins` của bạn được hỗ trợ bởi `$include` một tệp duy nhất, `plugins install/update/enable/disable/uninstall` sẽ ghi xuyên qua tệp được include đó và giữ nguyên `openclaw.json`. Include gốc, mảng include và include có ghi đè cùng cấp sẽ fail closed thay vì bị làm phẳng. Xem [Config includes](/vi/gateway/configuration) để biết các dạng được hỗ trợ.
Nếu cấu hình không hợp lệ trong khi cài đặt, `plugins install` thường fail closed và yêu cầu bạn chạy `openclaw doctor --fix` trước. Trong quá trình khởi động Gateway và hot reload, cấu hình plugin không hợp lệ fail closed như mọi cấu hình không hợp lệ khác; `openclaw doctor --fix` có thể cách ly mục plugin không hợp lệ. Ngoại lệ duy nhất được ghi nhận ở thời điểm cài đặt là đường dẫn phục hồi hẹp cho plugin đi kèm chủ động chọn tham gia `openclaw.install.allowInvalidConfigRecovery`.
Nếu cấu hình không hợp lệ trong lúc cài đặt, `plugins install` thường fail closed và yêu cầu bạn chạy `openclaw doctor --fix` trước. Trong lúc Gateway khởi động và hot reload, cấu hình plugin không hợp lệ fail closed như mọi cấu hình không hợp lệ khác; `openclaw doctor --fix` có thể cách ly mục plugin không hợp lệ. Ngoại lệ duy nhất được tài liệu hóa tại thời điểm cài đặt là đường dẫn khôi phục hẹp cho plugin đóng gói sẵn, áp dụng cho các plugin chủ động chọn tham gia `openclaw.install.allowInvalidConfigRecovery`.
</Accordion>
<Accordion title="--force và cài đặt lại so với cập nhật">
`--force` tái sử dụng mục tiêu cài đặt hiện có và ghi đè trực tiếp một plugin hoặc gói hook đã được cài đặt. Dùng tùy chọn này khi bạn chủ ý cài đặt lại cùng một id từ đường dẫn cục bộ, archive, package ClawHub hoặc artifact npm mới. Với nâng cấp thường lệ cho một plugin npm đã được theo dõi, hãy ưu tiên `openclaw plugins update <id-or-npm-spec>`.
`--force` tái sử dụng mục tiêu cài đặt hiện có và ghi đè plugin hoặc gói hook đã được cài đặt ngay tại chỗ. Dùng tùy chọn này khi bạn chủ ý cài đặt lại cùng một id từ đường dẫn cục bộ mới, archive, package ClawHub hoặc artifact npm mới. Với các nâng cấp định kỳ của một plugin npm đã được theo dõi, hãy ưu tiên `openclaw plugins update <id-or-npm-spec>`.
Nếu bạn chạy `plugins install` cho một id plugin đã được cài đặt, OpenClaw sẽ dừng và chỉ bạn tới `plugins update <id-or-npm-spec>` để nâng cấp thông thường, hoặc tới `plugins install <package> --force` khi bạn thực sự muốn ghi đè bản cài đặt hiện tại từ một nguồn khác.
Nếu bạn chạy `plugins install` cho một id plugin đã được cài đặt, OpenClaw sẽ dừng lại và trỏ bạn tới `plugins update <id-or-npm-spec>` cho nâng cấp thông thường, hoặc tới `plugins install <package> --force` khi bạn thực sự muốn ghi đè cài đặt hiện tại từ một nguồn khác.
</Accordion>
<Accordion title="Phạm vi --pin">
`--pin` chỉ áp dụng cho cài đặt npm. Tùy chọn này không được hỗ trợ với cài đặt `git:`; hãy dùng git ref rõ ràng như `git:github.com/acme/plugin@v1.2.3` khi bạn muốn một nguồn đã ghim. Tùy chọn này không được hỗ trợ với `--marketplace`, vì cài đặt marketplace lưu metadata nguồn marketplace thay vì spec npm.
`--pin` chỉ áp dụng cho các lượt cài đặt npm. Tùy chọn này không được hỗ trợ với cài đặt `git:`; hãy dùng ref git rõ ràng như `git:github.com/acme/plugin@v1.2.3` khi bạn muốn nguồn đã ghim. Tùy chọn này không được hỗ trợ với `--marketplace`, vì cài đặt marketplace lưu metadata nguồn marketplace thay vì spec npm.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` là tùy chọn khẩn cấp cho lỗi dương tính giả trong trình quét mã nguy hiểm tích hợp. Tùy chọn này cho phép tiếp tục cài đặt ngay cả khi trình quét tích hợp báo cáo phát hiện `critical`, nhưng **không** bỏ qua các chặn chính sách hook `before_install` của plugin và **không** bỏ qua lỗi quét.
`--dangerously-force-unsafe-install` là tùy chọn khẩn cấp cho các kết quả dương tính giả trong bộ quét mã nguy hiểm tích hợp. Tùy chọn này cho phép tiếp tục cài đặt ngay cả khi bộ quét tích hợp báo cáo phát hiện `critical`, nhưng **không** bỏ qua các chặn chính sách hook `before_install` của plugin và **không** bỏ qua lỗi quét.
Cờ CLI này áp dụng cho luồng cài đặt/cập nhật plugin. Các bản cài đặt phụ thuộc skill do Gateway hỗ trợ dùng override yêu cầu tương ứng `dangerouslyForceUnsafeInstall`, trong khi `openclaw skills install` vẫn là luồng tải xuống/cài đặt Skills ClawHub riêng.
Cờ CLI này áp dụng cho luồng cài đặt/cập nhật plugin. Các lượt cài đặt dependency kỹ năng do Gateway hỗ trợ dùng override yêu cầu tương ứng `dangerouslyForceUnsafeInstall`, còn `openclaw skills install` vẫn là luồng tải xuống/cài đặt kỹ năng ClawHub riêng biệt.
Nếu một plugin bạn đã xuất bản trên ClawHub bị chặn bởi quét registry, hãy dùng các bước dành cho nhà xuất bản trong [ClawHub](/vi/tools/clawhub).
Nếu một plugin bạn đã phát hành trên ClawHub bị chặn bởi một lượt quét registry, hãy dùng các bước dành cho nhà phát hành trong [ClawHub](/vi/tools/clawhub).
</Accordion>
<Accordion title="Gói hook và spec npm">
`plugins install` cũng là bề mặt cài đặt cho các gói hook expose `openclaw.hooks` trong `package.json`. Dùng `openclaw hooks` để xem hook đã lọc và bật từng hook, không phải để cài đặt package.
`plugins install` cũng là bề mặt cài đặt cho các gói hook phơi bày `openclaw.hooks` trong `package.json`. Dùng `openclaw hooks` để xem hook có lọc và bật từng hook, không dùng cho cài đặt package.
Spec npm là **chỉ registry** (tên package + **phiên bản chính xác** hoặc **dist-tag** tùy chọn). Spec Git/URL/file và dải semver bị từ chối. Cài đặt phụ thuộc chạy cục bộ theo dự án với `--ignore-scripts` để an toàn, ngay cả khi shell của bạn có thiết lập cài đặt npm toàn cục.
Spec npm là **chỉ registry** (tên package + **phiên bản chính xác** hoặc **dist-tag** tùy chọn). Spec Git/URL/file và dải semver bị từ chối. Cài đặt dependency chạy cục bộ theo dự án với `--ignore-scripts` để an toàn, ngay cả khi shell của bạn có thiết lập cài đặt npm toàn cục.
Dùng `npm:<package>` khi bạn muốn làm rõ quá trình phân giải npm. Spec package trần cũng cài đặt trực tiếp từ npm trong giai đoạn chuyển đổi khi ra mắt.
Dùng `npm:<package>` khi bạn muốn làm rõ việc phân giải npm. Spec package trần cũng cài đặt trực tiếp từ npm trong giai đoạn chuyển đổi ra mắt.
Spec trần và `@latest` ở lại track ổn định. Các phiên bản sửa lỗi có dấu ngày của OpenClaw như `2026.5.3-1` là bản phát hành ổn định cho kiểm tra này. Nếu npm phân giải một trong các spec đó thành bản prerelease, OpenClaw sẽ dừng và yêu cầu bạn chọn tham gia rõ ràng bằng tag prerelease như `@beta`/`@rc` hoặc phiên bản prerelease chính xác như `@1.2.3-beta.4`.
Spec trần và `@latest` ở lại nhánh ổn định. Các phiên bản sửa lỗi có đóng dấu ngày của OpenClaw như `2026.5.3-1` là bản phát hành ổn định cho kiểm tra này. Nếu npm phân giải một trong hai loại đó thành prerelease, OpenClaw sẽ dừng lại và yêu cầu bạn chọn tham gia rõ ràng bằng tag prerelease như `@beta`/`@rc` hoặc một phiên bản prerelease chính xác như `@1.2.3-beta.4`.
Nếu một spec cài đặt trần khớp với id plugin chính thức (ví dụ `diffs`), OpenClaw sẽ cài đặt trực tiếp mục catalog. Để cài đặt một package npm cùng tên, hãy dùng spec có scope rõ ràng (ví dụ `@scope/diffs`).
Nếu một spec cài đặt trần khớp với id plugin chính thức (ví dụ `diffs`), OpenClaw sẽ cài đặt trực tiếp mục catalog. Để cài đặt một package npm cùng tên, hãy dùng spec scoped rõ ràng (ví dụ `@scope/diffs`).
</Accordion>
<Accordion title="Kho Git">
Dùng `git:<repo>` để cài đặt trực tiếp từ kho git. Các dạng được hỗ trợ gồm `git:github.com/owner/repo`, `git:owner/repo`, URL clone đầy đủ `https://`, `ssh://`, `git://`, `file://` và `git@host:owner/repo.git`. Thêm `@<ref>` hoặc `#<ref>` để checkout branch, tag hoặc commit trước khi cài đặt.
Dùng `git:<repo>` để cài đặt trực tiếp từ một kho git. Các dạng được hỗ trợ gồm `git:github.com/owner/repo`, `git:owner/repo`, URL clone đầy đủ `https://`, `ssh://`, `git://`, `file://` và `git@host:owner/repo.git`. Thêm `@<ref>` hoặc `#<ref>` để checkout một branch, tag hoặc commit trước khi cài đặt.
Cài đặt Git clone vào thư mục tạm, checkout ref được yêu cầu nếu có, rồi dùng trình cài đặt thư mục plugin thông thường. Điều đó có nghĩa là xác thực manifest, quét mã nguy hiểm, công việc cài đặt package-manager và bản ghi cài đặt hoạt động như cài đặt npm. Bản ghi cài đặt git bao gồm URL/ref nguồn cùng commit đã phân giải để `openclaw plugins update` có thể phân giải lại nguồn sau này.
Cài đặt Git clone vào một thư mục tạm, checkout ref được yêu cầu khi có, rồi dùng trình cài đặt thư mục plugin thông thường. Điều đó nghĩa là xác thực manifest, quét mã nguy hiểm, công việc cài đặt của trình quản lý package và bản ghi cài đặt hoạt động như cài đặt npm. Các cài đặt git được ghi lại bao gồm URL/ref nguồn cùng commit đã phân giải để `openclaw plugins update` có thể phân giải lại nguồn sau này.
Sau khi cài đặt từ git, dùng `openclaw plugins inspect <id> --runtime --json` để xác minh các đăng ký runtime như phương thức gateway và lệnh CLI. Nếu plugin đã đăng ký một CLI root với `api.registerCli`, hãy thực thi lệnh đó trực tiếp qua CLI root của OpenClaw, ví dụ `openclaw demo-plugin ping`.
Sau khi cài đặt từ git, dùng `openclaw plugins inspect <id> --runtime --json` để xác minh các đăng ký runtime như phương thức gateway và lệnh CLI. Nếu plugin đã đăng ký một gốc CLI với `api.registerCli`, hãy thực thi lệnh đó trực tiếp qua CLI gốc OpenClaw, ví dụ `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Archive">
Archive được hỗ trợ: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archive plugin OpenClaw gốc phải chứa `openclaw.plugin.json` hợp lệ tại root plugin đã giải nén; archive chỉ chứa `package.json` bị từ chối trước khi OpenClaw ghi bản ghi cài đặt.
Archive được hỗ trợ: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Archive plugin OpenClaw native phải chứa một `openclaw.plugin.json` hợp lệ tại gốc plugin đã giải nén; archive chỉ chứa `package.json` sẽ bị từ chối trước khi OpenClaw ghi bản ghi cài đặt.
Cài đặt marketplace Claude cũng được hỗ trợ.
</Accordion>
</AccordionGroup>
Cài đặt ClawHub dùng locator rõ ràng `clawhub:<package>`:
Cài đặt ClawHub dùng locator `clawhub:<package>` rõ ràng:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Spec plugin an toàn với npm dạng trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi khi ra mắt:
Spec plugin an toàn cho npm dạng trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi ra mắt:
```bash
openclaw plugins install openclaw-codex-app-server
```
Dùng `npm:` để làm rõ quá trình phân giải chỉ npm:
Dùng `npm:` để làm rõ phân giải chỉ npm:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw kiểm tra khả năng tương thích plugin API / gateway tối thiểu được quảng bá trước khi cài đặt. Khi phiên bản ClawHub đã chọn xuất bản artifact ClawPack, OpenClaw tải xuống npm-pack `.tgz` có phiên bản, xác minh header digest ClawHub và digest artifact, rồi cài đặt qua đường dẫn archive thông thường. Các phiên bản ClawHub cũ hơn không có metadata ClawPack vẫn cài đặt qua đường dẫn xác minh archive package cũ. Bản ghi cài đặt giữ metadata nguồn ClawHub, loại artifact, integrity npm, shasum npm, tên tarball và thông tin digest ClawPack để dùng cho các lần cập nhật sau.
Cài đặt ClawHub không có phiên bản giữ spec đã ghi không có phiên bản để `openclaw plugins update` có thể theo các bản phát hành ClawHub mới hơn; bộ chọn phiên bản hoặc tag rõ ràng như `clawhub:pkg@1.2.3` và `clawhub:pkg@beta` vẫn được ghim vào bộ chọn đó.
OpenClaw kiểm tra khả năng tương thích API plugin / gateway tối thiểu được quảng bá trước khi cài đặt. Khi phiên bản ClawHub được chọn phát hành một artifact ClawPack, OpenClaw tải xuống `.tgz` npm-pack có phiên bản, xác minh header digest ClawHub và digest artifact, rồi cài đặt thông qua đường dẫn archive thông thường. Các phiên bản ClawHub cũ hơn không có metadata ClawPack vẫn cài đặt qua đường dẫn xác minh archive package cũ. Các cài đặt được ghi lại giữ metadata nguồn ClawHub, loại artifact, tính toàn vẹn npm, shasum npm, tên tarball và các thông tin digest ClawPack cho các cập nhật sau.
Cài đặt ClawHub không có phiên bản giữ một spec được ghi lại không có phiên bản để `openclaw plugins update` có thể theo các bản phát hành ClawHub mới hơn; selector phiên bản hoặc tag rõ ràng như `clawhub:pkg@1.2.3` và `clawhub:pkg@beta` vẫn được ghim vào selector đó.
#### Cú pháp rút gọn marketplace
#### Viết tắt marketplace
Dùng cú pháp rút gọn `plugin@marketplace` khi tên marketplace tồn tại trong cache registry cục bộ của Claude tại `~/.claude/plugins/known_marketplaces.json`:
Dùng viết tắt `plugin@marketplace` khi tên marketplace tồn tại trong cache registry cục bộ của Claude tại `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
Dùng `--marketplace` khi bạn muốn truyền nguồn marketplace rõ ràng:
Dùng `--marketplace` khi bạn muốn truyền nguồn marketplace một cách rõ ràng:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -204,28 +194,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="Marketplace sources">
- tên marketplace đã biết của Claude từ `~/.claude/plugins/known_marketplaces.json`
<Tab title="Nguồn marketplace">
- tên marketplace Claude đã biết từ `~/.claude/plugins/known_marketplaces.json`
- gốc marketplace cục bộ hoặc đường dẫn `marketplace.json`
- cách viết tắt kho GitHub như `owner/repo`
- URL kho GitHub như `https://github.com/owner/repo`
- dạng viết tắt repo GitHub như `owner/repo`
- URL repo GitHub như `https://github.com/owner/repo`
- URL git
</Tab>
<Tab title="Remote marketplace rules">
Với marketplace từ xa được tải từ GitHub hoặc git, các mục plugin phải nằm bên trong kho marketplace đã clone. OpenClaw chấp nhận nguồn đường dẫn tương đối từ kho đó và từ chối HTTP(S), đường dẫn tuyệt đối, git, GitHub, và các nguồn plugin không phải đường dẫn khác từ manifest từ xa.
<Tab title="Quy tắc marketplace từ xa">
Với các marketplace từ xa được tải từ GitHub hoặc git, các mục Plugin phải nằm trong repo marketplace đã được clone. OpenClaw chấp nhận các nguồn đường dẫn tương đối từ repo đó và từ chối HTTP(S), đường dẫn tuyệt đối, git, GitHub, và các nguồn Plugin không phải đường dẫn khác từ manifest từ xa.
</Tab>
</Tabs>
Với đường dẫn cục bộ và tệp lưu trữ, OpenClaw tự động phát hiện:
Với đường dẫn cục bộ và archive, OpenClaw tự động phát hiện:
- plugin OpenClaw gốc (`openclaw.plugin.json`)
- gói tương thích với Codex (`.codex-plugin/plugin.json`)
- gói tương thích với Claude (`.claude-plugin/plugin.json` hoặc bố cục thành phần Claude mặc định)
- gói tương thích với Cursor (`.cursor-plugin/plugin.json`)
- Plugin OpenClaw gốc (`openclaw.plugin.json`)
- bundle tương thích với Codex (`.codex-plugin/plugin.json`)
- bundle tương thích với Claude (`.claude-plugin/plugin.json` hoặc bố cục thành phần Claude mặc định)
- bundle tương thích với Cursor (`.cursor-plugin/plugin.json`)
<Note>
Các gói tương thích được cài đặt vào gốc plugin thông thường và tham gia cùng luồng liệt kê/thông tin/bật/tắt. Hiện tại, bundle skills, command-skills của Claude, giá trị mặc định `settings.json` của Claude, giá trị mặc định `.lsp.json` của Claude / `lspServers` được khai báo trong manifest, command-skills của Cursor, và các thư mục hook Codex tương thích được hỗ trợ; các khả năng gói khác được phát hiện sẽ hiển thị trong chẩn đoán/thông tin nhưng chưa được nối vào thực thi runtime.
Các bundle tương thích được cài vào gốc Plugin thông thường và tham gia cùng luồng list/info/enable/disable. Hiện tại, bundle skills, command-skills của Claude, mặc định `settings.json` của Claude, mặc định `.lsp.json` / `lspServers` được khai báo trong manifest của Claude, command-skills của Cursor, và các thư mục hook Codex tương thích được hỗ trợ; các khả năng bundle khác được phát hiện sẽ hiển thị trong chẩn đoán/info nhưng chưa được nối vào thực thi runtime.
</Note>
### Liệt kê
@ -241,48 +231,59 @@ openclaw plugins search <query> --json
```
<ParamField path="--enabled" type="boolean">
Chỉ hiển thị các plugin đã bật.
Chỉ hiển thị các Plugin đã bật.
</ParamField>
<ParamField path="--verbose" type="boolean">
Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng plugin với siêu dữ liệu nguồn/xuất xứ/phiên bản/kích hoạt.
Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng Plugin với siêu dữ liệu nguồn/xuất xứ/phiên bản/kích hoạt.
</ParamField>
<ParamField path="--json" type="boolean">
Bản kiểm kê máy đọc được cùng chẩn đoán registry và trạng thái cài đặt phụ thuộc của package.
Inventory đọc được bằng máy kèm chẩn đoán registry và trạng thái cài đặt dependency của package.
</ParamField>
<Note>
`plugins list` đọc registry plugin cục bộ đã lưu trước, với phương án dự phòng suy ra chỉ từ manifest khi registry bị thiếu hoặc không hợp lệ. Lệnh này hữu ích để kiểm tra liệu một plugin đã được cài đặt, bật và hiển thị cho việc lập kế hoạch khởi động lạnh hay chưa, nhưng không phải là phép dò runtime trực tiếp của một tiến trình Gateway đang chạy. Sau khi thay đổi mã plugin, trạng thái bật, chính sách hook, hoặc `plugins.load.paths`, hãy khởi động lại Gateway phục vụ kênh trước khi kỳ vọng mã `register(api)` mới hoặc hook chạy. Với triển khai từ xa/container, hãy xác minh bạn đang khởi động lại đúng tiến trình con `openclaw gateway run`, không chỉ một tiến trình wrapper.
`plugins list` đọc registry Plugin cục bộ đã lưu trước, với phương án dự phòng chỉ dựa trên manifest khi registry bị thiếu hoặc không hợp lệ. Lệnh này hữu ích để kiểm tra một Plugin đã được cài, bật và hiển thị cho kế hoạch khởi động lạnh hay chưa, nhưng không phải phép dò runtime trực tiếp của một tiến trình Gateway đang chạy. Sau khi thay đổi mã Plugin, trạng thái bật, chính sách hook, hoặc `plugins.load.paths`, hãy khởi động lại Gateway phục vụ kênh trước khi kỳ vọng mã `register(api)` mới hoặc các hook chạy. Với triển khai từ xa/container, hãy xác minh bạn đang khởi động lại đúng tiến trình con `openclaw gateway run`, không chỉ một tiến trình wrapper.
`plugins list --json` bao gồm `dependencyStatus` của từng plugin từ `dependencies` và `optionalDependencies` trong `package.json`. OpenClaw kiểm tra liệu các tên package đó có hiện diện dọc theo đường dẫn tra cứu `node_modules` thông thường của Node cho plugin hay không; nó không import mã runtime của plugin, chạy trình quản lý package, hoặc sửa các phụ thuộc bị thiếu.
`plugins list --json` bao gồm `dependencyStatus` của từng Plugin từ `package.json`
`dependencies` và `optionalDependencies`. OpenClaw kiểm tra xem các tên package đó
có hiện diện dọc theo đường dẫn tra cứu Node `node_modules` thông thường của Plugin hay không; nó
không import mã runtime của Plugin, chạy trình quản lý package, hoặc sửa chữa
dependency bị thiếu.
</Note>
`plugins search` là tra cứu danh mục ClawHub từ xa. Nó không kiểm tra trạng thái cục bộ, thay đổi cấu hình, cài đặt package, hoặc tải mã runtime của plugin. Kết quả tìm kiếm bao gồm tên package ClawHub, họ, kênh, phiên bản, tóm tắt, và gợi ý cài đặt như `openclaw plugins install clawhub:<package>`.
`plugins search` là tra cứu catalog ClawHub từ xa. Nó không kiểm tra trạng thái
cục bộ, thay đổi config, cài package, hoặc tải mã runtime của Plugin. Kết quả
tìm kiếm bao gồm tên package ClawHub, family, channel, phiên bản, tóm tắt, và
gợi ý cài đặt như `openclaw plugins install clawhub:<package>`.
Với công việc plugin đi kèm bên trong ảnh Docker đã đóng gói, hãy bind-mount thư mục nguồn plugin lên đường dẫn nguồn đã đóng gói tương ứng, chẳng hạn `/app/extensions/synology-chat`. OpenClaw sẽ phát hiện lớp phủ nguồn đã mount đó trước `/app/dist/extensions/synology-chat`; một thư mục nguồn được sao chép thông thường sẽ không hoạt động để các bản cài đặt đóng gói bình thường vẫn dùng dist đã biên dịch.
Với công việc trên Plugin được bundle bên trong image Docker đã đóng gói, bind-mount thư mục
nguồn Plugin đè lên đường dẫn nguồn đã đóng gói tương ứng, chẳng hạn
`/app/extensions/synology-chat`. OpenClaw sẽ phát hiện overlay nguồn đã mount đó
trước `/app/dist/extensions/synology-chat`; một thư mục nguồn chỉ được sao chép
vẫn bất hoạt để các bản cài đặt đã đóng gói thông thường tiếp tục dùng dist đã biên dịch.
Để gỡ lỗi hook runtime:
- `openclaw plugins inspect <id> --runtime --json` hiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra đã tải module. Kiểm tra runtime không bao giờ cài đặt phụ thuộc; dùng `openclaw doctor --fix` để dọn trạng thái phụ thuộc legacy hoặc cài các plugin tải xuống đã cấu hình bị thiếu.
- `openclaw gateway status --deep --require-rpc` xác nhận Gateway có thể truy cập, gợi ý service/tiến trình, đường dẫn cấu hình, và sức khỏe RPC.
- Hook hội thoại không đi kèm (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) yêu cầu `plugins.entries.<id>.hooks.allowConversationAccess=true`.
- `openclaw plugins inspect <id> --runtime --json` hiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra có tải module. Kiểm tra runtime không bao giờ cài dependency; dùng `openclaw doctor --fix` để dọn trạng thái dependency legacy hoặc khôi phục các Plugin có thể tải xuống bị thiếu đang được tham chiếu bởi config.
- `openclaw gateway status --deep --require-rpc` xác nhận Gateway có thể truy cập, gợi ý service/process, đường dẫn config, và sức khỏe RPC.
- Hook hội thoại không được bundle (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) yêu cầu `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Dùng `--link` để tránh sao chép thư mục cục bộ (thêm vào `plugins.load.paths`):
Dùng `--link` để tránh sao chép một thư mục cục bộ (thêm vào `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` không được hỗ trợ cùng `--link` vì cài đặt liên kết tái sử dụng đường dẫn nguồn thay vì sao chép đè lên mục tiêu cài đặt do hệ thống quản lý.
`--force` không được hỗ trợ với `--link` vì bản cài liên kết tái sử dụng đường dẫn nguồn thay vì sao chép đè lên mục tiêu cài đặt được quản lý.
Dùng `--pin` trên các bản cài đặt npm để lưu spec chính xác đã phân giải (`name@version`) trong chỉ mục plugin được quản lý, đồng thời giữ hành vi mặc định là không ghim.
Dùng `--pin` trên bản cài npm để lưu spec chính xác đã phân giải (`name@version`) trong index Plugin được quản lý, đồng thời giữ hành vi mặc định không ghim.
</Note>
### Chỉ mục Plugin
### Index Plugin
Siêu dữ liệu cài đặt Plugin là trạng thái do máy quản lý, không phải cấu hình người dùng. Các lần cài đặt và cập nhật ghi nó vào `plugins/installs.json` trong thư mục trạng thái OpenClaw đang hoạt động. Bản đồ `installRecords` cấp cao nhất là nguồn bền vững của siêu dữ liệu cài đặt, bao gồm các bản ghi cho manifest plugin bị hỏng hoặc bị thiếu. Mảng `plugins` là bộ nhớ đệm registry lạnh suy ra từ manifest. Tệp này bao gồm cảnh báo không chỉnh sửa và được dùng bởi `openclaw plugins update`, gỡ cài đặt, chẩn đoán, và registry plugin lạnh.
Siêu dữ liệu cài đặt Plugin là trạng thái do máy quản lý, không phải config người dùng. Các lượt cài đặt và cập nhật ghi nó vào `plugins/installs.json` trong thư mục trạng thái OpenClaw đang hoạt động. Map cấp cao nhất `installRecords` là nguồn bền vững của siêu dữ liệu cài đặt, bao gồm bản ghi cho manifest Plugin bị hỏng hoặc bị thiếu. Mảng `plugins` là cache registry lạnh được suy ra từ manifest. Tệp bao gồm cảnh báo không chỉnh sửa và được dùng bởi `openclaw plugins update`, gỡ cài đặt, chẩn đoán, và registry Plugin lạnh.
Khi OpenClaw thấy các bản ghi legacy `plugins.installs` được phát hành trong cấu hình, nó chuyển chúng vào chỉ mục plugin và xóa khóa cấu hình; nếu một trong hai thao tác ghi thất bại, các bản ghi cấu hình được giữ lại để siêu dữ liệu cài đặt không bị mất.
Khi OpenClaw thấy các bản ghi `plugins.installs` legacy đã phát hành trong config, nó chuyển chúng vào index Plugin và xóa khóa config; nếu một trong hai lượt ghi thất bại, các bản ghi config được giữ lại để siêu dữ liệu cài đặt không bị mất.
### Gỡ cài đặt
@ -292,10 +293,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` xóa bản ghi plugin khỏi `plugins.entries`, chỉ mục plugin đã lưu, các mục danh sách cho phép/từ chối plugin, và các mục `plugins.load.paths` đã liên kết khi áp dụng. Trừ khi đặt `--keep-files`, gỡ cài đặt cũng xóa thư mục cài đặt do hệ thống quản lý đã theo dõi khi nó nằm bên trong gốc tiện ích mở rộng plugin của OpenClaw. Với plugin active memory, slot bộ nhớ đặt lại thành `memory-core`.
`uninstall` xóa bản ghi Plugin khỏi `plugins.entries`, index Plugin đã lưu, các mục trong danh sách cho phép/từ chối Plugin, và các mục `plugins.load.paths` được liên kết khi áp dụng. Trừ khi đặt `--keep-files`, gỡ cài đặt cũng xóa thư mục cài đặt được quản lý đang được theo dõi khi nó nằm trong gốc extensions Plugin của OpenClaw. Với Plugin active memory, slot bộ nhớ đặt lại về `memory-core`.
<Note>
`--keep-config` được hỗ trợ như alias đã lỗi thời cho `--keep-files`.
`--keep-config` được hỗ trợ như alias đã ngừng khuyến nghị cho `--keep-files`.
</Note>
### Cập nhật
@ -308,29 +309,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Cập nhật áp dụng cho các bản cài đặt plugin được theo dõi trong chỉ mục plugin được quản lý và các bản cài đặt hook-pack được theo dõi trong `hooks.internal.installs`.
Cập nhật áp dụng cho các bản cài Plugin được theo dõi trong index Plugin được quản lý và các bản cài hook-pack được theo dõi trong `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Resolving plugin id vs npm spec">
Khi bạn truyền một plugin id, OpenClaw tái sử dụng spec cài đặt đã ghi cho plugin đó. Điều đó có nghĩa là các dist-tag đã lưu trước đó như `@beta` và các phiên bản ghim chính xác tiếp tục được dùng trong những lần chạy `update <id>` sau này.
<Accordion title="Phân giải id Plugin so với spec npm">
Khi bạn truyền một id Plugin, OpenClaw tái sử dụng spec cài đặt đã ghi cho Plugin đó. Điều đó có nghĩa là các dist-tag đã lưu trước đó như `@beta` và các phiên bản ghim chính xác tiếp tục được dùng trong các lần chạy `update <id>` sau này.
Với bản cài đặt npm, bạn cũng có thể truyền một spec package npm rõ ràng với dist-tag hoặc phiên bản chính xác. OpenClaw phân giải tên package đó trở lại bản ghi plugin được theo dõi, cập nhật plugin đã cài đó, và ghi lại spec npm mới cho các lần cập nhật dựa trên id trong tương lai.
Với bản cài npm, bạn cũng có thể truyền một spec package npm rõ ràng với dist-tag hoặc phiên bản chính xác. OpenClaw phân giải tên package đó ngược về bản ghi Plugin được theo dõi, cập nhật Plugin đã cài đó, và ghi spec npm mới cho các lần cập nhật dựa trên id trong tương lai.
Truyền tên package npm không kèm phiên bản hoặc tag cũng phân giải trở lại bản ghi plugin được theo dõi. Dùng cách này khi một plugin đã được ghim vào phiên bản chính xác và bạn muốn chuyển nó trở lại dòng phát hành mặc định của registry.
Truyền tên package npm không kèm phiên bản hoặc tag cũng phân giải ngược về bản ghi Plugin được theo dõi. Dùng cách này khi một Plugin đã được ghim vào phiên bản chính xác và bạn muốn chuyển nó trở lại dòng phát hành mặc định của registry.
</Accordion>
<Accordion title="Beta channel updates">
`openclaw plugins update` tái sử dụng spec plugin được theo dõi trừ khi bạn truyền spec mới. `openclaw update` còn biết kênh cập nhật OpenClaw đang hoạt động: trên kênh beta, các bản ghi plugin npm và ClawHub thuộc dòng mặc định sẽ thử `@beta` trước, rồi quay lại spec mặc định/latest đã ghi nếu không có bản phát hành beta của plugin. Phiên bản chính xác và tag rõ ràng vẫn được ghim vào bộ chọn đó.
<Accordion title="Cập nhật kênh beta">
`openclaw plugins update` tái sử dụng spec Plugin được theo dõi trừ khi bạn truyền spec mới. `openclaw update` còn biết kênh cập nhật OpenClaw đang hoạt động: trên kênh beta, các bản ghi Plugin npm và ClawHub thuộc dòng mặc định sẽ thử `@beta` trước, rồi quay lại spec default/latest đã ghi nếu không có bản phát hành beta của Plugin. Phiên bản chính xác và tag rõ ràng vẫn được ghim vào selector đó.
</Accordion>
<Accordion title="Version checks and integrity drift">
Trước một bản cập nhật npm trực tiếp, OpenClaw kiểm tra phiên bản package đã cài so với siêu dữ liệu npm registry. Nếu phiên bản đã cài và danh tính artifact đã ghi đã khớp với mục tiêu đã phân giải, bản cập nhật được bỏ qua mà không tải xuống, cài đặt lại, hoặc ghi lại `openclaw.json`.
<Accordion title="Kiểm tra phiên bản và trôi dạt tính toàn vẹn">
Trước một lượt cập nhật npm trực tiếp, OpenClaw kiểm tra phiên bản package đã cài so với siêu dữ liệu registry npm. Nếu phiên bản đã cài và định danh artifact đã ghi đã khớp với mục tiêu được phân giải, bản cập nhật được bỏ qua mà không tải xuống, cài lại, hoặc ghi lại `openclaw.json`.
Khi có hash integrity đã lưu và hash artifact đã fetch thay đổi, OpenClaw coi đó là drift artifact npm. Lệnh tương tác `openclaw plugins update` in hash kỳ vọng và hash thực tế, rồi hỏi xác nhận trước khi tiếp tục. Các helper cập nhật không tương tác sẽ fail closed trừ khi bên gọi cung cấp chính sách tiếp tục rõ ràng.
Khi có hash tính toàn vẹn đã lưu và hash artifact được fetch thay đổi, OpenClaw xem đó là trôi dạt artifact npm. Lệnh tương tác `openclaw plugins update` in hash kỳ vọng và thực tế rồi yêu cầu xác nhận trước khi tiếp tục. Các helper cập nhật không tương tác sẽ fail closed trừ khi caller cung cấp chính sách tiếp tục rõ ràng.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install on update">
`--dangerously-force-unsafe-install` cũng có sẵn trên `plugins update` như một override khẩn cấp cho các kết quả dương tính giả của quét dangerous-code tích hợp trong khi cập nhật plugin. Nó vẫn không bỏ qua các chặn chính sách `before_install` của plugin hoặc chặn do lỗi quét, và chỉ áp dụng cho cập nhật plugin, không áp dụng cho cập nhật hook-pack.
<Accordion title="--dangerously-force-unsafe-install khi cập nhật">
`--dangerously-force-unsafe-install` cũng có sẵn trên `plugins update` như một override khẩn cấp cho dương tính giả của quét dangerous-code tích hợp trong quá trình cập nhật Plugin. Nó vẫn không bỏ qua các chặn chính sách `before_install` của Plugin hoặc chặn do lỗi quét, và chỉ áp dụng cho cập nhật Plugin, không áp dụng cho cập nhật hook-pack.
</Accordion>
</AccordionGroup>
@ -342,21 +343,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect hiển thị danh tính, trạng thái tải, nguồn, khả năng manifest, cờ chính sách, chẩn đoán, siêu dữ liệu cài đặt, khả năng gói, và mọi hỗ trợ máy chủ MCP hoặc LSP được phát hiện mà mặc định không import runtime plugin. Thêm `--runtime` để tải module plugin và bao gồm các hook, công cụ, lệnh, service, phương thức gateway, và tuyến HTTP đã đăng ký. Kiểm tra runtime báo cáo trực tiếp các phụ thuộc plugin bị thiếu; việc cài đặt và sửa chữa nằm trong `openclaw plugins install`, `openclaw plugins update`, và `openclaw doctor --fix`.
Inspect hiển thị định danh, trạng thái tải, nguồn, khả năng manifest, cờ chính sách, chẩn đoán, siêu dữ liệu cài đặt, khả năng bundle, và mọi hỗ trợ MCP hoặc server LSP được phát hiện mà mặc định không import runtime Plugin. Thêm `--runtime` để tải module Plugin và bao gồm các hook, tool, lệnh, service, phương thức gateway, và route HTTP đã đăng ký. Kiểm tra runtime báo trực tiếp dependency Plugin bị thiếu; việc cài đặt và sửa chữa nằm trong `openclaw plugins install`, `openclaw plugins update`, và `openclaw doctor --fix`.
Các lệnh CLI do plugin sở hữu được cài đặt dưới dạng nhóm lệnh `openclaw` gốc. Sau khi `inspect --runtime` hiển thị một lệnh dưới `cliCommands`, hãy chạy nó dưới dạng `openclaw <command> ...`; ví dụ một plugin đăng ký `demo-git` có thể được xác minh bằng `openclaw demo-git ping`.
Các lệnh CLI do Plugin sở hữu được cài làm nhóm lệnh `openclaw` gốc. Sau khi `inspect --runtime` hiển thị một lệnh dưới `cliCommands`, hãy chạy nó dưới dạng `openclaw <command> ...`; ví dụ một Plugin đăng ký `demo-git` có thể được xác minh bằng `openclaw demo-git ping`.
Mỗi plugin được phân loại theo những gì nó thực sự đăng ký tại runtime:
Mỗi Plugin được phân loại theo những gì nó thực sự đăng ký ở runtime:
- **plain-capability** — một loại khả năng (ví dụ: plugin chỉ dành cho provider)
- **plain-capability** — một loại khả năng (ví dụ: Plugin chỉ có provider)
- **hybrid-capability** — nhiều loại khả năng (ví dụ: văn bản + giọng nói + hình ảnh)
- **hook-only** — chỉ hook, không có khả năng hoặc bề mặt
- **non-capability** — công cụ/lệnh/service nhưng không có khả năng
- **hook-only** — chỉ có hook, không có khả năng hoặc surface
- **non-capability** — tool/lệnh/service nhưng không có khả năng
Xem [Kiểu Plugin](/vi/plugins/architecture#plugin-shapes) để biết thêm về mô hình khả năng.
Xem [Hình dạng Plugin](/vi/plugins/architecture#plugin-shapes) để biết thêm về mô hình khả năng.
<Note>
Cờ `--json` xuất một báo cáo máy đọc được phù hợp cho script và kiểm toán. `inspect --all` hiển thị bảng toàn bộ đội hình với các cột kiểu, loại khả năng, thông báo tương thích, khả năng gói, và tóm tắt hook. `info` là alias cho `inspect`.
Cờ `--json` xuất báo cáo đọc được bằng máy, phù hợp cho scripting và kiểm toán. `inspect --all` render bảng toàn đội với các cột shape, loại khả năng, thông báo tương thích, khả năng bundle, và tóm tắt hook. `info` là alias của `inspect`.
</Note>
### Doctor
@ -365,11 +366,11 @@ Cờ `--json` xuất một báo cáo máy đọc được phù hợp cho script
openclaw plugins doctor
```
`doctor` báo cáo lỗi tải plugin, chẩn đoán manifest/discovery, và thông báo tương thích. Khi mọi thứ sạch, nó in `No plugin issues detected.`
`doctor` báo lỗi tải Plugin, chẩn đoán manifest/discovery, và thông báo tương thích. Khi mọi thứ sạch, nó in `No plugin issues detected.`
Nếu một plugin đã cấu hình hiện diện trên đĩa nhưng bị chặn bởi kiểm tra an toàn đường dẫn của loader, xác thực cấu hình giữ mục plugin và báo cáo nó là `present but blocked`. Hãy sửa chẩn đoán plugin bị chặn ở trước đó, chẳng hạn quyền sở hữu đường dẫn hoặc quyền ghi của mọi người, thay vì xóa cấu hình `plugins.entries.<id>` hoặc `plugins.allow`.
Nếu một Plugin đã cấu hình hiện diện trên đĩa nhưng bị chặn bởi các kiểm tra an toàn đường dẫn của loader, validation config giữ lại mục Plugin và báo là `present but blocked`. Sửa chẩn đoán Plugin bị chặn trước đó, chẳng hạn quyền sở hữu đường dẫn hoặc quyền world-writable, thay vì xóa config `plugins.entries.<id>` hoặc `plugins.allow`.
Với lỗi hình dạng module như thiếu export `register`/`activate`, chạy lại với `OPENCLAW_PLUGIN_LOAD_DEBUG=1` để bao gồm tóm tắt hình dạng export gọn trong đầu ra chẩn đoán.
Với lỗi hình dạng module như thiếu export `register`/`activate`, chạy lại với `OPENCLAW_PLUGIN_LOAD_DEBUG=1` để bao gồm tóm tắt hình dạng export ngắn gọn trong đầu ra chẩn đoán.
### Registry
@ -379,14 +380,14 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
Registry plugin cục bộ là mô hình đọc lạnh đã lưu của OpenClaw cho danh tính plugin đã cài, trạng thái bật, siêu dữ liệu nguồn, và quyền sở hữu đóng góp. Khởi động bình thường, tra cứu chủ sở hữu provider, phân loại thiết lập kênh, và kiểm kê plugin có thể đọc nó mà không cần import các module runtime plugin.
Registry Plugin cục bộ là mô hình đọc lạnh đã lưu của OpenClaw cho định danh Plugin đã cài, trạng thái bật, siêu dữ liệu nguồn, và quyền sở hữu đóng góp. Khởi động thông thường, tra cứu chủ sở hữu provider, phân loại thiết lập kênh, và inventory Plugin có thể đọc nó mà không cần import các module runtime Plugin.
Sử dụng `plugins registry` để kiểm tra registry đã lưu có hiện diện, hiện hành hay đã cũ. Sử dụng `--refresh` để xây dựng lại registry từ chỉ mục plugin đã lưu, chính sách cấu hình và siêu dữ liệu manifest/package. Đây là đường dẫn sửa chữa, không phải đường dẫn kích hoạt khi chạy.
Dùng `plugins registry` để kiểm tra registry đã lưu có hiện diện, hiện hành hay lỗi thời hay không. Dùng `--refresh` để dựng lại registry từ chỉ mục Plugin đã lưu, chính sách cấu hình và siêu dữ liệu manifest/package. Đây là đường dẫn sửa chữa, không phải đường dẫn kích hoạt runtime.
`openclaw doctor --fix` cũng sửa lỗi lệch npm được quản lý liền kề registry: nếu một package `@openclaw/*` mồ côi hoặc được khôi phục dưới gốc npm plugin được quản lý che khuất một plugin được đóng gói sẵn, doctor sẽ xóa package cũ đó và xây dựng lại registry để quá trình khởi động xác thực theo manifest được đóng gói sẵn.
`openclaw doctor --fix` cũng sửa lỗi sai lệch npm được quản lý liên quan đến registry: nếu một gói `@openclaw/*` mồ côi hoặc đã được khôi phục trong thư mục gốc npm của Plugin được quản lý che khuất một Plugin đi kèm, doctor sẽ xóa gói lỗi thời đó và dựng lại registry để quá trình khởi động xác thực theo manifest đi kèm.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` là công tắc tương thích khẩn cấp đã lỗi thời cho các lỗi đọc registry. Ưu tiên `plugins registry --refresh` hoặc `openclaw doctor --fix`; fallback bằng env chỉ dành cho khôi phục khởi động khẩn cấp trong khi quá trình di chuyển đang được triển khai.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` là công tắc tương thích khẩn cấp đã ngừng khuyến nghị dùng cho lỗi đọc registry. Ưu tiên `plugins registry --refresh` hoặc `openclaw doctor --fix`; cơ chế dự phòng qua env chỉ dành cho khôi phục khởi động khẩn cấp trong khi quá trình migration được triển khai.
</Warning>
### Marketplace
@ -396,10 +397,10 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Danh sách Marketplace chấp nhận đường dẫn marketplace cục bộ, đường dẫn `marketplace.json`, cách viết tắt GitHub như `owner/repo`, URL repo GitHub hoặc URL git. `--json` in nhãn nguồn đã phân giải cùng với manifest marketplace đã phân tích cú pháp và các mục plugin.
Danh sách marketplace chấp nhận đường dẫn marketplace cục bộ, đường dẫn `marketplace.json`, dạng rút gọn GitHub như `owner/repo`, URL repo GitHub hoặc URL git. `--json` in nhãn nguồn đã phân giải cùng với manifest marketplace đã phân tích và các mục Plugin.
## Liên quan
- [Xây dựng plugin](/vi/plugins/building-plugins)
- [Xây dựng Plugin](/vi/plugins/building-plugins)
- [Tham chiếu CLI](/vi/cli)
- [Plugin cộng đồng](/vi/plugins/community)

63
docs/vi/cli/proxy.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Bạn cần kiểm tra xác nhận việc định tuyến qua máy chủ trung gian do người vận hành quản lý trước khi triển khai
- Bạn cần ghi lại lưu lượng truyền tải của OpenClaw cục bộ để gỡ lỗi
- Bạn muốn kiểm tra các phiên trung gian gỡ lỗi, khối dữ liệu hoặc mẫu truy vấn tích hợp sẵn
summary: Tài liệu tham chiếu CLI cho `openclaw proxy`, bao gồm xác thực proxy do người vận hành quản lý và trình kiểm tra bản ghi thu thập proxy gỡ lỗi cục bộ
title: Máy chủ trung gian
- Bạn cần xác minh định tuyến proxy do người vận hành quản lý trước khi triển khai
- Bạn cần ghi lại lưu lượng truyền tải OpenClaw cục bộ để gỡ lỗi
- Bạn muốn kiểm tra các phiên proxy gỡ lỗi, blob hoặc các mẫu truy vấn tích hợp sẵn
summary: Tham chiếu CLI cho `openclaw proxy`, bao gồm kiểm tra hợp lệ proxy do người vận hành quản lý và trình kiểm tra bản thu proxy gỡ lỗi cục bộ
title: Máy chủ proxy
x-i18n:
generated_at: "2026-05-04T07:03:08Z"
generated_at: "2026-05-05T01:45:04Z"
model: gpt-5.5
provider: openai
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5
source_path: cli/proxy.md
workflow: 16
---
@ -19,18 +19,18 @@ x-i18n:
Xác thực định tuyến proxy do người vận hành quản lý, hoặc chạy proxy gỡ lỗi tường minh cục bộ
và kiểm tra lưu lượng đã ghi lại.
Dùng `validate` để kiểm tra trước một forward proxy do người vận hành quản lý trước khi bật
Dùng `validate` để kiểm tra sơ bộ proxy chuyển tiếp do người vận hành quản lý trước khi bật
định tuyến proxy của OpenClaw. Các lệnh khác là công cụ gỡ lỗi để
điều tra ở cấp truyền tải: chúng có thể khởi động proxy cục bộ, chạy một lệnh con
với tính năng ghi lại được bật, liệt kê các phiên ghi lại, truy vấn các mẫu lưu lượng phổ biến, đọc
các blob đã ghi lại, và xóa dữ liệu ghi lại cục bộ.
điều tra ở cấp truyền tải: chúng có thể khởi động proxy cục bộ, chạy lệnh con
khi đã bật ghi lại, liệt kê các phiên ghi lại, truy vấn các mẫu lưu lượng phổ biến, đọc
các blob đã ghi lại, và xóa sạch dữ liệu ghi lại cục bộ.
## Lệnh
```bash
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
@ -40,27 +40,32 @@ openclaw proxy purge
## Xác thực
`openclaw proxy validate` kiểm tra URL proxy hiệu dụng do người vận hành quản lý từ
`--proxy-url`, cấu hình, hoặc `OPENCLAW_PROXY_URL`. Lệnh này báo cáo vấn đề cấu hình khi
không có proxy nào được bật và cấu hình; dùng `--proxy-url` để kiểm tra trước một lần
`openclaw proxy validate` kiểm tra URL proxy do người vận hành quản lý có hiệu lực từ
`--proxy-url`, cấu hình, hoặc `OPENCLAW_PROXY_URL`. Lệnh này báo cáo sự cố cấu hình khi
không có proxy nào được bật và cấu hình; dùng `--proxy-url` để kiểm tra sơ bộ một lần
trước khi thay đổi cấu hình. Theo mặc định, lệnh xác minh rằng một đích công khai thành công
thông qua proxy và proxy không thể truy cập một canary loopback tạm thời.
Các đích bị từ chối tùy chỉnh sẽ fail-closed: phản hồi HTTP và lỗi truyền tải
mơ hồ đều thất bại trừ khi bạn có thể xác minh riêng một tín hiệu từ chối
theo từng triển khai.
qua proxy và proxy không thể truy cập một canary loopback tạm thời.
Các đích bị từ chối tùy chỉnh dùng cơ chế đóng khi lỗi: phản hồi HTTP và lỗi
truyền tải mơ hồ đều thất bại trừ khi bạn có thể xác minh riêng một tín hiệu từ chối
theo từng triển khai. Thêm `--apns-reachable` để cũng mở một đường hầm CONNECT HTTP/2 của APNs
qua proxy và xác nhận APNs sandbox phản hồi; phép thăm dò dùng một
provider token cố ý không hợp lệ, vì vậy phản hồi APNs `403 InvalidProviderToken`
là tín hiệu khả năng truy cập thành công.
Tùy chọn:
- `--json`: in JSON máy có thể đọc.
- `--proxy-url <url>`: xác thực URL proxy này thay vì cấu hình hoặc biến môi trường.
- `--allowed-url <url>`: thêm một đích được kỳ vọng sẽ thành công thông qua proxy. Lặp lại để kiểm tra nhiều đích.
- `--json`: in JSON đọc được bởi máy.
- `--proxy-url <url>`: xác thực URL proxy này thay vì cấu hình hoặc env.
- `--allowed-url <url>`: thêm một đích được kỳ vọng sẽ thành công qua proxy. Lặp lại để kiểm tra nhiều đích.
- `--denied-url <url>`: thêm một đích được kỳ vọng sẽ bị proxy chặn. Lặp lại để kiểm tra nhiều đích.
- `--timeout-ms <ms>`: thời gian chờ cho mỗi yêu cầu, tính bằng mili giây.
- `--apns-reachable`: cũng xác minh HTTP/2 APNs sandbox có thể truy cập được qua proxy.
- `--apns-authority <url>`: authority APNs để thăm dò với `--apns-reachable` (mặc định là `https://api.sandbox.push.apple.com`; production là `https://api.push.apple.com`).
- `--timeout-ms <ms>`: thời gian chờ cho mỗi yêu cầu tính bằng mili giây.
Xem [Network Proxy](/vi/security/network-proxy) để biết hướng dẫn triển khai và ngữ nghĩa
từ chối.
Xem [Proxy mạng](/vi/security/network-proxy) để biết hướng dẫn triển khai và
ngữ nghĩa từ chối.
## Preset truy vấn
## Các preset truy vấn
`openclaw proxy query --preset <name>` chấp nhận:
@ -75,12 +80,12 @@ từ chối.
- `start` mặc định là `127.0.0.1` trừ khi đặt `--host`.
- `run` khởi động một proxy gỡ lỗi cục bộ rồi chạy lệnh sau `--`.
- Chuyển tiếp trực tiếp lên upstream của proxy gỡ lỗi mở các socket upstream để chẩn đoán. Khi chế độ proxy do OpenClaw quản lý đang hoạt động, chuyển tiếp trực tiếp cho các yêu cầu proxy và đường hầm CONNECT bị tắt theo mặc định; chỉ đặt `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` cho chẩn đoán cục bộ đã được phê duyệt.
- Cơ chế chuyển tiếp upstream trực tiếp của proxy gỡ lỗi mở các socket upstream để chẩn đoán. Khi chế độ proxy do OpenClaw quản lý đang hoạt động, chuyển tiếp trực tiếp cho các yêu cầu proxy và đường hầm CONNECT bị tắt theo mặc định; chỉ đặt `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` cho chẩn đoán cục bộ đã được phê duyệt.
- `validate` thoát với mã 1 khi cấu hình proxy hoặc kiểm tra đích thất bại.
- Các bản ghi là dữ liệu gỡ lỗi cục bộ; dùng `openclaw proxy purge` khi hoàn tất.
- Các bản ghi lại là dữ liệu gỡ lỗi cục bộ; dùng `openclaw proxy purge` khi hoàn tất.
## Liên quan
- [Tham chiếu CLI](/vi/cli)
- [Network Proxy](/vi/security/network-proxy)
- [Proxy mạng](/vi/security/network-proxy)
- [Xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth)

47
docs/vi/cli/sessions.md
View File

@ -2,51 +2,53 @@
read_when:
- Bạn muốn liệt kê các phiên đã lưu và xem hoạt động gần đây
summary: Tài liệu tham chiếu CLI cho `openclaw sessions` (liệt kê các phiên đã lưu + cách sử dụng)
title: Phiên
title: Phiên làm việc
x-i18n:
generated_at: "2026-05-04T07:02:50Z"
generated_at: "2026-05-05T01:44:53Z"
model: gpt-5.5
provider: openai
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7
source_path: cli/sessions.md
workflow: 16
---
# `openclaw sessions`
Liệt kê các phiên hội thoại đã lưu trữ.
Liệt kê các phiên hội thoại đã lưu.
Danh sách phiên không phải là kiểm tra trạng thái hoạt động của kênh/nhà cung cấp. Chúng hiển thị các hàng hội thoại đã được lưu bền vững từ kho phiên. Một Discord, Slack, Telegram hoặc kênh khác đang yên lặng có thể kết nối lại thành công mà không tạo hàng phiên mới cho đến khi một tin nhắn được xử lý. Dùng `openclaw channels status --probe`, `openclaw status --deep` hoặc `openclaw health --verbose` khi bạn cần kiểm tra kết nối kênh trực tiếp.
Danh sách phiên không phải là kiểm tra khả năng hoạt động của kênh/nhà cung cấp. Chúng hiển thị các hàng hội thoại đã được lưu bền vững từ kho phiên. Một kênh Discord, Slack, Telegram hoặc kênh khác đang im lặng có thể kết nối lại thành công mà không tạo hàng phiên mới cho đến khi một tin nhắn được xử lý. Dùng `openclaw channels status --probe`, `openclaw status --deep`, hoặc `openclaw health --verbose` khi bạn cần kết nối kênh trực tiếp.
Phản hồi Gateway `sessions.list` được giới hạn theo mặc định để các kho lớn tồn tại lâu không thể độc chiếm vòng lặp sự kiện Gateway. Truyền một `limit` dương rõ ràng từ các máy khách RPC khi cần một cửa sổ kết quả khác; phản hồi bao gồm `totalCount`, `limitApplied` và `hasMore` khi bên gọi cần hiển thị rằng vẫn còn nhiều hàng hơn.
Phản hồi của `openclaw sessions` và Gateway `sessions.list` được giới hạn theo mặc định để các kho lớn tồn tại lâu không thể chiếm độc quyền tiến trình CLI hoặc vòng lặp sự kiện Gateway. CLI trả về 100 phiên mới nhất theo mặc định; truyền `--limit <n>` để dùng cửa sổ nhỏ hơn/lớn hơn hoặc `--limit all` khi bạn thực sự cần toàn bộ kho. Phản hồi JSON bao gồm `totalCount`, `limitApplied`, và `hasMore` khi bên gọi cần hiển thị rằng còn nhiều hàng hơn.
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --verbose
openclaw sessions --json
```
Chọn phạm vi:
- mặc định: kho tác nhân mặc định đã cấu hình
- `--verbose`: ghi nhật ký chi tiết
- `--agent <id>`: một kho tác nhân đã cấu hình
- `--all-agents`: tổng hợp tất cả kho tác nhân đã cấu hình
- mặc định: kho agent mặc định đã cấu hình
- `--verbose`: ghi log chi tiết
- `--agent <id>`: một kho agent đã cấu hình
- `--all-agents`: tổng hợp tất cả kho agent đã cấu hình
- `--store <path>`: đường dẫn kho rõ ràng (không thể kết hợp với `--agent` hoặc `--all-agents`)
- `--limit <n|all>`: số hàng tối đa để xuất (mặc định `100`; `all` khôi phục đầu ra đầy đủ)
Xuất một gói quỹ đạo cho phiên đã lưu trữ:
Xuất một gói quỹ đạo cho một phiên đã lưu:
```bash
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
Đây là đường dẫn lệnh được lệnh gạch chéo `/export-trajectory` sử dụng sau khi chủ sở hữu phê duyệt yêu cầu exec. Thư mục đầu ra luôn được phân giải bên trong `.openclaw/trajectory-exports/` dưới workspace đã chọn.
Đây là đường dẫn lệnh được lệnh slash `/export-trajectory` sử dụng sau khi chủ sở hữu phê duyệt yêu cầu exec. Thư mục đầu ra luôn được phân giải bên trong `.openclaw/trajectory-exports/` trong workspace đã chọn.
`openclaw sessions --all-agents` đọc các kho tác nhân đã cấu hình. Khám phá phiên Gateway và ACP rộng hơn: chúng cũng bao gồm các kho chỉ có trên đĩa được tìm thấy dưới gốc `agents/` mặc định hoặc gốc `session.store` theo mẫu. Các kho được phát hiện đó phải phân giải thành các tệp `sessions.json` thông thường bên trong gốc tác nhân; symlink và các đường dẫn nằm ngoài gốc sẽ bị bỏ qua.
`openclaw sessions --all-agents` đọc các kho agent đã cấu hình. Cơ chế khám phá phiên của Gateway và ACP rộng hơn: chúng cũng bao gồm các kho chỉ có trên đĩa được tìm thấy dưới gốc `agents/` mặc định hoặc gốc `session.store` theo mẫu. Các kho được khám phá đó phải phân giải thành các tệp `sessions.json` thông thường bên trong gốc agent; symlink và đường dẫn ngoài gốc sẽ bị bỏ qua.
Ví dụ JSON:
@ -61,6 +63,9 @@ Ví dụ JSON:
],
"allAgents": true,
"count": 2,
"totalCount": 2,
"limitApplied": 100,
"hasMore": false,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
@ -82,21 +87,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123
openclaw sessions cleanup --json
```
`openclaw sessions cleanup` dùng cài đặt `session.maintenance` từ cấu hình:
`openclaw sessions cleanup` sử dụng cài đặt `session.maintenance` từ cấu hình:
- Ghi chú phạm vi: `openclaw sessions cleanup` bảo trì kho phiên, bản ghi hội thoại và sidecar quỹ đạo. Lệnh này không cắt tỉa nhật ký chạy cron (`cron/runs/<jobId>.jsonl`), vốn được quản lý bởi `cron.runLog.maxBytes` và `cron.runLog.keepLines` trong [cấu hình Cron](/vi/automation/cron-jobs#configuration) và được giải thích trong [bảo trì Cron](/vi/automation/cron-jobs#maintenance).
- Ghi chú phạm vi: `openclaw sessions cleanup` bảo trì kho phiên, bản ghi hội thoại, và sidecar quỹ đạo. Nó không cắt tỉa log lần chạy cron (`cron/runs/<jobId>.jsonl`), vốn được quản lý bởi `cron.runLog.maxBytes` và `cron.runLog.keepLines` trong [Cấu hình Cron](/vi/automation/cron-jobs#configuration) và được giải thích trong [Bảo trì Cron](/vi/automation/cron-jobs#maintenance).
- `--dry-run`: xem trước có bao nhiêu mục sẽ bị cắt tỉa/giới hạn mà không ghi.
- Ở chế độ văn bản, dry-run in một bảng hành động theo từng phiên (`Action`, `Key`, `Age`, `Model`, `Flags`) để bạn có thể thấy mục nào sẽ được giữ lại và mục nào sẽ bị xóa.
- Ở chế độ văn bản, dry-run in một bảng hành động theo từng phiên (`Action`, `Key`, `Age`, `Model`, `Flags`) để bạn có thể thấy mục nào sẽ được giữ lại so với bị xóa.
- `--enforce`: áp dụng bảo trì ngay cả khi `session.maintenance.mode` là `warn`.
- `--fix-missing`: xóa các mục có tệp bản ghi hội thoại bị thiếu, ngay cả khi chúng thường chưa bị loại theo tuổi/số lượng.
- `--active-key <key>`: bảo vệ một khóa đang hoạt động cụ thể khỏi bị loại do ngân sách đĩa. Các con trỏ hội thoại bên ngoài bền vững, chẳng hạn như phiên nhóm và phiên trò chuyện theo phạm vi luồng, cũng được giữ lại bởi bảo trì theo tuổi/số lượng/ngân sách đĩa.
- `--agent <id>`: chạy dọn dẹp cho một kho tác nhân đã cấu hình.
- `--all-agents`: chạy dọn dẹp cho tất cả kho tác nhân đã cấu hình.
- `--fix-missing`: xóa các mục có tệp bản ghi hội thoại bị thiếu, ngay cả khi thông thường chúng chưa bị loại theo tuổi/số lượng.
- `--active-key <key>`: bảo vệ một khóa đang hoạt động cụ thể khỏi việc bị loại do ngân sách đĩa. Các con trỏ hội thoại bên ngoài bền vững, chẳng hạn như phiên nhóm và phiên trò chuyện theo phạm vi luồng, cũng được giữ lại bởi bảo trì theo tuổi/số lượng/ngân sách đĩa.
- `--agent <id>`: chạy dọn dẹp cho một kho agent đã cấu hình.
- `--all-agents`: chạy dọn dẹp cho tất cả kho agent đã cấu hình.
- `--store <path>`: chạy trên một tệp `sessions.json` cụ thể.
- `--json`: in tóm tắt JSON. Với `--all-agents`, đầu ra bao gồm một tóm tắt cho mỗi kho.
Khi có thể truy cập Gateway, dọn dẹp không phải dry-run cho các kho tác nhân đã cấu hình sẽ được gửi qua Gateway để dùng chung trình ghi kho phiên với lưu lượng runtime. Dùng `--store <path>` để sửa chữa ngoại tuyến rõ ràng một tệp kho.
Khi có thể truy cập Gateway, thao tác dọn dẹp không phải dry-run cho các kho agent đã cấu hình sẽ được gửi qua Gateway để nó dùng chung trình ghi kho phiên với lưu lượng runtime. Dùng `--store <path>` để sửa chữa ngoại tuyến rõ ràng một tệp kho.
`openclaw sessions cleanup --all-agents --dry-run --json`:

138
docs/vi/cli/update.md
View File

@ -2,25 +2,26 @@
read_when:
- Bạn muốn cập nhật một bản checkout mã nguồn một cách an toàn
- Bạn đang gỡ lỗi đầu ra hoặc tùy chọn của `openclaw update`
- Bạn cần hiểu cách hoạt động dạng viết tắt của `--update`
summary: Tài liệu tham khảo CLI cho `openclaw update` (cập nhật nguồn tương đối an toàn + tự động khởi động lại Gateway)
- Bạn cần hiểu cách hoạt động của cú pháp viết tắt `--update`
summary: Tài liệu tham khảo CLI cho `openclaw update` (cập nhật mã nguồn tương đối an toàn + tự động khởi động lại Gateway)
title: Cập nhật
x-i18n:
generated_at: "2026-05-03T21:29:11Z"
generated_at: "2026-05-05T01:45:13Z"
model: gpt-5.5
provider: openai
source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8
source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f
source_path: cli/update.md
workflow: 16
---
# `openclaw update`
Cập nhật OpenClaw an toàn và chuyển đổi giữa các kênh ổn định/beta/dev.
Cập nhật OpenClaw an toàn và chuyển đổi giữa các kênh stable/beta/dev.
Nếu bạn đã cài đặt qua **npm/pnpm/bun** (cài đặt toàn cục, không có siêu dữ liệu git), các bản cập nhật diễn ra qua luồng trình quản lý gói trong [Cập nhật](/vi/install/updating).
Nếu bạn đã cài đặt qua **npm/pnpm/bun** (cài đặt toàn cục, không có siêu dữ liệu git),
quá trình cập nhật diễn ra qua luồng trình quản lý gói trong [Cập nhật](/vi/install/updating).
## Cách sử dụng
## Cách dùng
```bash
openclaw update
@ -39,23 +40,23 @@ openclaw --update
## Tùy chọn
- `--no-restart`: bỏ qua việc khởi động lại dịch vụ Gateway sau khi cập nhật thành công. Các bản cập nhật bằng trình quản lý gói có khởi động lại Gateway sẽ xác minh rằng dịch vụ đã khởi động lại báo cáo phiên bản đã cập nhật như mong đợi trước khi lệnh thành công.
- `--no-restart`: bỏ qua việc khởi động lại dịch vụ Gateway sau khi cập nhật thành công. Các bản cập nhật qua trình quản lý gói có khởi động lại Gateway sẽ xác minh rằng dịch vụ đã khởi động lại báo cáo đúng phiên bản đã cập nhật dự kiến trước khi lệnh thành công.
- `--channel <stable|beta|dev>`: đặt kênh cập nhật (git + npm; được lưu trong cấu hình).
- `--tag <dist-tag|version|spec>`: ghi đè mục tiêu gói chỉ cho lần cập nhật này. Với các bản cài đặt bằng gói, `main` ánh xạ tới `github:openclaw/openclaw#main`.
- `--dry-run`: xem trước các hành động cập nhật dự kiến (luồng kênh/tag/mục tiêu/khởi động lại) mà không ghi cấu hình, cài đặt, đồng bộ Plugin hoặc khởi động lại.
- `--json`: in JSON `UpdateRunResult` máy có thể đọc, bao gồm
`postUpdate.plugins.integrityDrifts` khi phát hiện sai lệch artifact Plugin npm
- `--tag <dist-tag|version|spec>`: ghi đè mục tiêu gói chỉ cho lần cập nhật này. Với các bản cài đặt gói, `main` ánh xạ tới `github:openclaw/openclaw#main`.
- `--dry-run`: xem trước các hành động cập nhật dự kiến (luồng channel/tag/target/restart) mà không ghi cấu hình, cài đặt, đồng bộ Plugin, hoặc khởi động lại.
- `--json`: in JSON `UpdateRunResult` cho máy đọc được, bao gồm
`postUpdate.plugins.integrityDrifts` khi phát hiện lệch tạo tác Plugin npm
trong quá trình đồng bộ Plugin sau cập nhật.
- `--timeout <seconds>`: thời gian chờ cho mỗi bước (mặc định là 1800s).
- `--timeout <seconds>`: thời gian chờ cho mỗi bước (mặc định là 1800 giây).
- `--yes`: bỏ qua lời nhắc xác nhận (ví dụ xác nhận hạ cấp).
`openclaw update` không có cờ `--verbose`. Dùng `--dry-run` để xem trước
các hành động kênh/tag/cài đặt/khởi động lại đã lên kế hoạch, `--json` để nhận
kết quả máy có thể đọc, và `openclaw update status --json` khi bạn chỉ cần thông tin
các hành động channel/tag/install/restart dự kiến, `--json` để nhận kết quả
cho máy đọc được, và `openclaw update status --json` khi bạn chỉ cần thông tin
về kênh và tính khả dụng. Nếu bạn đang gỡ lỗi nhật ký Gateway quanh một lần cập nhật,
độ chi tiết trên console và cấp độ nhật ký tệp là riêng biệt: Gateway `--verbose` ảnh hưởng
đến đầu ra terminal/WebSocket, còn nhật ký tệp yêu cầu `logging.level: "debug"` hoặc
`"trace"` trong cấu hình. Xem [Ghi nhật ký Gateway](/vi/gateway/logging).
tới đầu ra terminal/WebSocket, trong khi nhật ký tệp yêu cầu `logging.level: "debug"` hoặc
`"trace"` trong cấu hình. Xem [ghi nhật ký Gateway](/vi/gateway/logging).
<Warning>
Hạ cấp yêu cầu xác nhận vì các phiên bản cũ hơn có thể làm hỏng cấu hình.
@ -63,7 +64,7 @@ Hạ cấp yêu cầu xác nhận vì các phiên bản cũ hơn có thể làm
## `update status`
Hiển thị kênh cập nhật đang hoạt động + tag/nhánh/SHA git (đối với checkout từ nguồn), cùng với tính khả dụng của bản cập nhật.
Hiển thị kênh cập nhật đang hoạt động + thẻ/nhánh/SHA git (đối với checkout từ mã nguồn), cùng tính khả dụng của bản cập nhật.
```bash
openclaw update status
@ -73,8 +74,8 @@ openclaw update status --timeout 10
Tùy chọn:
- `--json`: in JSON trạng thái máy có thể đọc.
- `--timeout <seconds>`: thời gian chờ cho các kiểm tra (mặc định là 3s).
- `--json`: in JSON trạng thái cho máy đọc được.
- `--timeout <seconds>`: thời gian chờ cho các bước kiểm tra (mặc định là 3 giây).
## `update wizard`
@ -88,56 +89,56 @@ Tùy chọn:
## Lệnh này làm gì
Khi bạn chuyển kênh rõ ràng (`--channel ...`), OpenClaw cũng giữ phương thức
cài đặt được căn chỉnh:
Khi bạn chuyển kênh một cách rõ ràng (`--channel ...`), OpenClaw cũng giữ cho
phương thức cài đặt được đồng bộ:
- `dev` → đảm bảo có một checkout git (mặc định: `~/openclaw`, ghi đè bằng `OPENCLAW_GIT_DIR`),
cập nhật checkout đó và cài đặt CLI toàn cục từ checkout đó.
- `dev` → đảm bảo có checkout git (mặc định: `~/openclaw`, ghi đè bằng `OPENCLAW_GIT_DIR`),
cập nhật checkout đó, và cài đặt CLI toàn cục từ checkout đó.
- `stable` → cài đặt từ npm bằng `latest`.
- `beta` → ưu tiên dist-tag npm `beta`, nhưng quay về `latest` khi beta
bị thiếu hoặc cũ hơn bản phát hành ổn định hiện tại.
- `beta` → ưu tiên dist-tag npm `beta`, nhưng quay lại `latest` khi beta
bị thiếu hoặc cũ hơn bản phát hành stable hiện tại.
Trình tự động cập nhật lõi Gateway (khi được bật qua cấu hình) khởi chạy đường dẫn cập nhật CLI
bên ngoài trình xử lý yêu cầu Gateway đang chạy. Các bản cập nhật trình quản lý gói `update.run`
trên control-plane buộc một lần khởi động lại cập nhật không trì hoãn, không thời gian chờ sau khi thay gói,
vì tiến trình Gateway cũ có thể vẫn còn các phần trong bộ nhớ trỏ tới
Trình tự cập nhật tự động của lõi Gateway (khi được bật qua cấu hình) khởi chạy đường dẫn cập nhật CLI
bên ngoài trình xử lý yêu cầu Gateway đang chạy. Các bản cập nhật qua trình quản lý gói `update.run`
của mặt phẳng điều khiển buộc một lần khởi động lại cập nhật không trì hoãn, không có thời gian chờ hồi,
sau khi hoán đổi gói, vì tiến trình Gateway cũ vẫn có thể có các đoạn trong bộ nhớ trỏ tới
các tệp đã bị gói mới xóa.
Đối với các bản cài đặt bằng trình quản lý gói, `openclaw update` phân giải phiên bản gói
mục tiêu trước khi gọi trình quản lý gói. Các bản cài đặt npm toàn cục dùng cơ chế cài đặt theo giai đoạn:
OpenClaw cài gói mới vào một tiền tố npm tạm thời, xác minh inventory `dist`
được đóng gói tại đó, rồi thay cây gói sạch đó vào tiền tố toàn cục thật.
Nếu xác minh thất bại, doctor sau cập nhật, đồng bộ Plugin và công việc khởi động lại
sẽ không chạy từ cây đáng ngờ đó. Ngay cả khi phiên bản đã cài đặt đã
khớp với mục tiêu, lệnh vẫn làm mới bản cài đặt gói toàn cục,
sau đó chạy đồng bộ Plugin, làm mới hoàn tất lệnh lõi, và công việc khởi động lại. Điều này
giữ các sidecar đã đóng gói và bản ghi Plugin do kênh sở hữu được căn chỉnh với
bản dựng OpenClaw đã cài đặt, đồng thời để việc dựng lại hoàn tất lệnh Plugin đầy đủ cho
Với các bản cài đặt qua trình quản lý gói, `openclaw update` phân giải phiên bản gói
mục tiêu trước khi gọi trình quản lý gói. Các bản cài đặt npm toàn cục dùng cài đặt theo giai đoạn:
OpenClaw cài gói mới vào một tiền tố npm tạm thời, xác minh
kiểm kê `dist` đã đóng gói ở đó, rồi hoán đổi cây gói sạch đó vào
tiền tố toàn cục thật. Nếu xác minh thất bại, doctor sau cập nhật, đồng bộ Plugin, và
công việc khởi động lại sẽ không chạy từ cây đáng nghi đó. Ngay cả khi phiên bản đã cài đặt
đã khớp với mục tiêu, lệnh vẫn làm mới bản cài đặt gói toàn cục,
sau đó chạy đồng bộ Plugin, làm mới hoàn thành lệnh lõi, và công việc khởi động lại. Điều này
giữ cho các sidecar đã đóng gói và bản ghi Plugin do kênh sở hữu được đồng bộ với
bản build OpenClaw đã cài đặt, đồng thời để các lần dựng lại hoàn thành lệnh Plugin đầy đủ cho
các lần chạy `openclaw completion --write-state` rõ ràng.
Khi dịch vụ Gateway được quản lý cục bộ đã được cài đặt và khởi động lại được bật,
các bản cập nhật bằng trình quản lý gói sẽ dừng dịch vụ đang chạy trước khi thay thế cây gói,
các bản cập nhật qua trình quản lý gói sẽ dừng dịch vụ đang chạy trước khi thay thế cây gói,
sau đó làm mới siêu dữ liệu dịch vụ từ bản cài đặt đã cập nhật, khởi động lại
dịch vụ, và xác minh Gateway đã khởi động lại báo cáo phiên bản mong đợi trước khi
báo thành công. Trên macOS, kiểm tra sau cập nhật cũng xác minh LaunchAgent
đã được tải/đang chạy cho hồ sơ đang hoạt động và cổng loopback đã cấu hình đang
dịch vụ, và xác minh Gateway đã khởi động lại báo cáo đúng phiên bản dự kiến trước khi
báo cáo thành công. Trên macOS, bước kiểm tra sau cập nhật cũng xác minh LaunchAgent
đã được tải/đang chạy cho hồ sơ hoạt động và cổng local loopback đã cấu hình
khỏe mạnh. Nếu plist đã được cài đặt nhưng launchd không giám sát nó, OpenClaw
tự động bootstrap lại LaunchAgent, rồi chạy lại các kiểm tra
tự động bootstrap lại LaunchAgent, rồi chạy lại các bước kiểm tra
sẵn sàng về sức khỏe/phiên bản/kênh. Một lần bootstrap mới tải trực tiếp job RunAtLoad,
vì vậy quá trình phục hồi cập nhật không lập tức `kickstart -k` Gateway
mới được sinh ra. Nếu Gateway vẫn không trở nên khỏe mạnh, lệnh thoát
khác không và in đường dẫn nhật ký khởi động lại cùng hướng dẫn khởi động lại, cài đặt lại và
rollback gói rõ ràng. Với `--no-restart`,
vì vậy quá trình khôi phục cập nhật không lập tức `kickstart -k` Gateway
vừa được sinh ra. Nếu Gateway vẫn không trở nên khỏe mạnh, lệnh thoát
khác không và in đường dẫn nhật ký khởi động lại cùng các hướng dẫn rõ ràng về khởi động lại, cài đặt lại, và
rollback gói. Với `--no-restart`,
việc thay thế gói vẫn chạy nhưng dịch vụ được quản lý không bị dừng hoặc
khởi động lại, nên Gateway đang chạy có thể tiếp tục dùng mã cũ cho đến khi bạn khởi động lại
khởi động lại, vì vậy Gateway đang chạy có thể tiếp tục dùng mã cũ cho đến khi bạn khởi động lại
thủ công.
## Luồng checkout git
### Chọn kênh
- `stable`: checkout tag không phải beta mới nhất, rồi build và doctor.
- `beta`: ưu tiên tag `-beta` mới nhất, nhưng quay về tag ổn định mới nhất khi beta bị thiếu hoặc cũ hơn.
- `stable`: checkout thẻ không phải beta mới nhất, rồi build và chạy doctor.
- `beta`: ưu tiên thẻ `-beta` mới nhất, nhưng quay lại thẻ stable mới nhất khi beta bị thiếu hoặc cũ hơn.
- `dev`: checkout `main`, rồi fetch và rebase.
### Các bước cập nhật
@ -147,49 +148,50 @@ thủ công.
Yêu cầu không có thay đổi chưa commit.
</Step>
<Step title="Chuyển kênh">
Chuyển sang kênh đã chọn (tag hoặc nhánh).
Chuyển sang kênh đã chọn (thẻ hoặc nhánh).
</Step>
<Step title="Fetch upstream">
Chỉ dev.
Chỉ dành cho dev.
</Step>
<Step title="Build preflight (chỉ dev)">
Chạy lint và build TypeScript trong một worktree tạm. Nếu tip thất bại, lùi tối đa 10 commit để tìm bản build sạch mới nhất.
Chạy lint và build TypeScript trong một worktree tạm. Nếu tip thất bại, lùi lại tối đa 10 commit để tìm bản build sạch mới nhất.
</Step>
<Step title="Rebase">
Rebase lên commit đã chọn (chỉ dev).
</Step>
<Step title="Cài đặt phụ thuộc">
Dùng trình quản lý gói của repo. Với các checkout pnpm, trình cập nhật bootstrap `pnpm` theo nhu cầu (qua `corepack` trước, rồi fallback `npm install pnpm@10` tạm thời) thay vì chạy `npm run build` bên trong một workspace pnpm.
Dùng trình quản lý gói của repo. Với các checkout pnpm, trình cập nhật bootstrap `pnpm` theo nhu cầu (qua `corepack` trước, rồi fallback tạm thời `npm install pnpm@10`) thay vì chạy `npm run build` bên trong một workspace pnpm.
</Step>
<Step title="Build Control UI">
Build gateway và Control UI.
<Step title="Build giao diện điều khiển">
Build gateway và giao diện điều khiển.
</Step>
<Step title="Chạy doctor">
`openclaw doctor` chạy như kiểm tra cập nhật an toàn cuối cùng.
`openclaw doctor` chạy làm bước kiểm tra cập nhật an toàn cuối cùng.
</Step>
<Step title="Đồng bộ Plugin">
Đồng bộ Plugin với kênh đang hoạt động. Dev dùng Plugin đi kèm; stable và beta dùng npm. Cập nhật các bản cài đặt Plugin được theo dõi.
Đồng bộ Plugin với kênh đang hoạt động. Dev dùng các Plugin đi kèm; stable và beta dùng npm. Cập nhật các bản cài đặt Plugin được theo dõi.
</Step>
</Steps>
Trên kênh cập nhật beta, các bản cài đặt Plugin npm và ClawHub được theo dõi theo
dòng mặc định/latest sẽ thử bản phát hành Plugin `@beta` trước. Nếu Plugin không có
bản phát hành beta, OpenClaw quay về spec mặc định/latest đã ghi lại. Các
phiên bản chính xác và tag rõ ràng không bị viết lại.
Trên kênh cập nhật beta, các bản cài đặt Plugin npm và ClawHub được theo dõi đi theo
dòng default/latest sẽ thử bản phát hành Plugin `@beta` trước. Nếu Plugin không có
bản phát hành beta, OpenClaw quay lại spec default/latest đã ghi nhận. Với các Plugin
npm, OpenClaw cũng quay lại khi gói beta tồn tại nhưng không vượt qua
xác thực cài đặt. Các phiên bản chính xác và thẻ rõ ràng không bị viết lại.
<Warning>
Nếu một bản cập nhật Plugin npm được ghim chính xác phân giải thành một artifact có integrity khác với bản ghi cài đặt đã lưu, `openclaw update` sẽ hủy bản cập nhật artifact Plugin đó thay vì cài đặt nó. Chỉ cài đặt lại hoặc cập nhật Plugin một cách rõ ràng sau khi xác minh rằng bạn tin tưởng artifact mới.
Nếu một bản cập nhật Plugin npm được ghim chính xác phân giải thành một tạo tác có tính toàn vẹn khác với bản ghi cài đặt đã lưu, `openclaw update` hủy bản cập nhật tạo tác Plugin đó thay vì cài đặt nó. Chỉ cài đặt lại hoặc cập nhật Plugin một cách rõ ràng sau khi xác minh rằng bạn tin tưởng tạo tác mới.
</Warning>
<Note>
Lỗi đồng bộ Plugin sau cập nhật khiến kết quả cập nhật thất bại và dừng công việc khởi động lại tiếp theo. Sửa lỗi cài đặt hoặc cập nhật Plugin, rồi chạy lại `openclaw update`.
Lỗi đồng bộ Plugin sau cập nhật làm kết quả cập nhật thất bại và dừng công việc khởi động lại tiếp theo. Sửa lỗi cài đặt hoặc cập nhật Plugin, rồi chạy lại `openclaw update`.
Khi Gateway đã cập nhật khởi động, việc tải Plugin chỉ xác minh: khởi động không chạy trình quản lý gói hoặc thay đổi cây phụ thuộc. Các lần khởi động lại `update.run` bằng trình quản lý gói bỏ qua cơ chế trì hoãn khi nhàn rỗi thông thường và thời gian chờ khởi động lại sau khi cây gói đã được thay, để tiến trình cũ không thể tiếp tục tải lười các phần đã bị xóa.
Khi Gateway đã cập nhật khởi động, việc tải Plugin chỉ là xác minh: khởi động không chạy trình quản lý gói hoặc thay đổi cây phụ thuộc. Các lần khởi động lại `update.run` qua trình quản lý gói bỏ qua cơ chế trì hoãn lúc nhàn rỗi thông thường và thời gian chờ hồi khởi động lại sau khi cây gói đã được hoán đổi, để tiến trình cũ không thể tiếp tục lazy-load các đoạn đã bị xóa.
Nếu bootstrap pnpm vẫn thất bại, trình cập nhật dừng sớm với lỗi dành riêng cho trình quản lý gói thay vì thử `npm run build` bên trong checkout.
</Note>
## Viết tắt `--update`
## Cách viết tắt `--update`
`openclaw --update` được viết lại thành `openclaw update` (hữu ích cho shell và script launcher).

165
docs/vi/concepts/models.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Thêm hoặc sửa đổi CLI models (models list/set/scan/aliases/fallbacks)
- Thay đổi hành vi dự phòng của mô hình hoặc trải nghiệm người dùng khi lựa chọn
- Cập nhật đầu dò quét mô hình (công cụ/hình ảnh)
- Thêm hoặc sửa đổi CLI cho mô hình (models list/set/scan/aliases/fallbacks)
- Thay đổi hành vi dự phòng của mô hình hoặc trải nghiệm lựa chọn
- Cập nhật các đầu dò quét mô hình (công cụ/hình ảnh)
sidebarTitle: Models CLI
summary: 'CLI mô hình: liệt kê, thiết lập, bí danh, phương án dự phòng, quét, trạng thái'
title: CLI cho mô hình
summary: 'CLI mô hình: liệt kê, đặt, bí danh, dự phòng, quét, trạng thái'
title: CLI mô hình
x-i18n:
generated_at: "2026-05-02T10:39:39Z"
generated_at: "2026-05-05T01:45:46Z"
model: gpt-5.5
provider: openai
source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f
source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f
source_path: concepts/models.md
workflow: 16
---
<CardGroup cols={2}>
<Card title="Chuyển dự phòng mô hình" href="/vi/concepts/model-failover">
Xoay vòng hồ sơ xác thực, thời gian chờ, và cách chúng tương tác với các phương án dự phòng.
<Card title="Chuyển đổi dự phòng mô hình" href="/vi/concepts/model-failover">
Xoay vòng hồ sơ xác thực, thời gian chờ phục hồi, và cách chúng tương tác với các phương án dự phòng.
</Card>
<Card title="Nhà cung cấp mô hình" href="/vi/concepts/model-providers">
Tổng quan nhanh về nhà cung cấp và ví dụ.
</Card>
<Card title="Môi trường chạy tác tử" href="/vi/concepts/agent-runtimes">
Pi, Codex, và các môi trường chạy vòng lặp tác tử khác.
<Card title="Môi trường chạy agent" href="/vi/concepts/agent-runtimes">
PI, Codex, và các môi trường chạy vòng lặp agent khác.
</Card>
<Card title="Tham chiếu cấu hình" href="/vi/gateway/config-agents#agent-defaults">
Các khóa cấu hình mô hình.
</Card>
</CardGroup>
Tham chiếu mô hình chọn một nhà cung cấp và mô hình. Chúng thường không chọn môi trường chạy tác tử cấp thấp. Ví dụ, `openai/gpt-5.5` có thể chạy qua đường dẫn nhà cung cấp OpenAI thông thường hoặc qua môi trường chạy máy chủ ứng dụng Codex, tùy thuộc vào `agents.defaults.agentRuntime.id`. Ở chế độ môi trường chạy Codex, tham chiếu `openai/gpt-*` không ngụ ý thanh toán bằng khóa API; xác thực có thể đến từ tài khoản Codex hoặc hồ sơ xác thực `openai-codex`. Xem [Môi trường chạy tác tử](/vi/concepts/agent-runtimes).
Tham chiếu mô hình chọn nhà cung cấp và mô hình. Chúng thường không chọn môi trường chạy agent cấp thấp. Ví dụ, `openai/gpt-5.5` có thể chạy qua đường dẫn nhà cung cấp OpenAI thông thường hoặc qua môi trường chạy máy chủ ứng dụng Codex, tùy thuộc vào `agents.defaults.agentRuntime.id`. Ở chế độ môi trường chạy Codex, tham chiếu `openai/gpt-*` không ngụ ý thanh toán bằng khóa API; xác thực có thể đến từ tài khoản Codex hoặc hồ sơ xác thực `openai-codex`. Xem [Môi trường chạy agent](/vi/concepts/agent-runtimes).
## Cách hoạt động của việc chọn mô hình
OpenClaw chọn mô hình theo thứ tự sau:
OpenClaw chọn mô hình theo thứ tự này:
<Steps>
<Step title="Mô hình chính">
@ -43,44 +43,44 @@ OpenClaw chọn mô hình theo thứ tự sau:
<Step title="Dự phòng">
`agents.defaults.model.fallbacks` (theo thứ tự).
</Step>
<Step title="Chuyển dự phòng xác thực nhà cung cấp">
Chuyển dự phòng xác thực diễn ra bên trong một nhà cung cấp trước khi chuyển sang mô hình tiếp theo.
<Step title="Chuyển đổi dự phòng xác thực nhà cung cấp">
Chuyển đổi dự phòng xác thực diễn ra bên trong một nhà cung cấp trước khi chuyển sang mô hình tiếp theo.
</Step>
</Steps>
<AccordionGroup>
<Accordion title="Các bề mặt mô hình liên quan">
- `agents.defaults.models` là danh sách cho phép/danh mục các mô hình OpenClaw có thể dùng (cộng với bí danh).
- `agents.defaults.imageModel` được dùng **chỉ khi** mô hình chính không thể nhận hình ảnh.
- `agents.defaults.pdfModel` được dùng bởi công cụ `pdf`. Nếu bỏ qua, công cụ sẽ quay về `agents.defaults.imageModel`, rồi mô hình phiên/mặc định đã phân giải.
- `agents.defaults.imageGenerationModel` được dùng bởi năng lực tạo hình ảnh dùng chung. Nếu bỏ qua, `image_generate` vẫn có thể suy ra 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 các nhà cung cấp tạo hình ảnh đã đăng ký còn lại theo thứ tự mã nhà cung cấp. Nếu bạn đặt một nhà cung cấp/mô hình cụ thể, hãy cấu hình cả xác thực/khóa API của nhà cung cấp đó.
- `agents.defaults.musicGenerationModel` được dùng bởi năng lực tạo nhạc dùng chung. Nếu bỏ qua, `music_generate` vẫn có thể suy ra 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 các nhà cung cấp tạo nhạc đã đăng ký còn lại theo thứ tự mã nhà cung cấp. Nếu bạn đặt một nhà cung cấp/mô hình cụ thể, hãy cấu hình cả xác thực/khóa API của nhà cung cấp đó.
- `agents.defaults.videoGenerationModel` được dùng bởi năng lực tạo video dùng chung. Nếu bỏ qua, `video_generate` vẫn có thể suy ra 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 các nhà cung cấp tạo video đã đăng ký còn lại theo thứ tự mã nhà cung cấp. Nếu bạn đặt một nhà cung cấp/mô hình cụ thể, hãy cấu hình cả xác thực/khóa API của nhà cung cấp đó.
- Mặc định theo từng tác tử có thể ghi đè `agents.defaults.model` qua `agents.list[].model` cộng với các liên kết (xem [Định tuyến đa tác tử](/vi/concepts/multi-agent)).
- `agents.defaults.imageModel` chỉ được dùng **khi** mô hình chính không thể nhận hình ảnh.
- `agents.defaults.pdfModel` được công cụ `pdf` dùng. Nếu bỏ qua, công cụ sẽ dự phòng về `agents.defaults.imageModel`, rồi đến mô hình phiên/mặc định đã phân giải.
- `agents.defaults.imageGenerationModel` được năng lực tạo hình ảnh dùng chung sử dụng. Nếu bỏ qua, `image_generate` vẫn có thể suy ra 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 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. Nếu bạn đặt nhà cung cấp/mô hình cụ thể, cũng hãy cấu hình xác thực/khóa API của nhà cung cấp đó.
- `agents.defaults.musicGenerationModel` được năng lực tạo nhạc dùng chung sử dụng. Nếu bỏ qua, `music_generate` vẫn có thể suy ra 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 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 đặt nhà cung cấp/mô hình cụ thể, cũng hãy cấu hình xác thực/khóa API của nhà cung cấp đó.
- `agents.defaults.videoGenerationModel` được năng lực tạo video dùng chung sử dụng. Nếu bỏ qua, `video_generate` vẫn có thể suy ra 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 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 đặt nhà cung cấp/mô hình cụ thể, cũng hãy cấu hình xác thực/khóa API của nhà cung cấp đó.
- Mặc định theo từng agent có thể ghi đè `agents.defaults.model` thông qua `agents.list[].model` cùng với các liên kết (xem [Định tuyến đa agent](/vi/concepts/multi-agent)).
</Accordion>
</AccordionGroup>
## Nguồn chọn và hành vi dự phòng
## Nguồn lựa chọn và hành vi dự phòng
Cùng một `provider/model` có thể mang ý nghĩa khác nhau tùy thuộc vào nơi nó đến từ:
Cùng một `provider/model` có thể có ý nghĩa khác nhau tùy vào nguồn gốc của nó:
- Mặc định đã cấu hình (`agents.defaults.model.primary` và mô hình chính theo từng tác tử) là điểm bắt đầu thông thường và dùng `agents.defaults.model.fallbacks`.
- Lựa chọn dự phòng tự động là trạng thái khôi phục tạm thời. Chúng được lưu với `modelOverrideSource: "auto"` để các lượt sau có thể tiếp tục dùng chuỗi dự phòng mà không phải thăm dò một mô hình chính đã biết là lỗi trước.
- Lựa chọn phiên của người dùng là chính xác. `/model`, bộ chọn mô hình, `session_status(model=...)`, và `sessions.patch` lưu `modelOverrideSource: "user"`; nếu nhà cung cấp/mô hình được chọn đó không truy cập được, OpenClaw báo lỗi rõ ràng thay vì rơi xuống một mô hình đã cấu hình khác.
- Cron `--model` / payload `model` là mô hình chính theo từng công việc. Nó vẫn dùng các phương án dự phòng đã cấu hình trừ khi công việc cung cấp payload `fallbacks` rõ ràng (dùng `fallbacks: []` cho một lần chạy cron nghiêm ngặt).
- CLI chọn mô hình mặc định và danh sách cho phép tôn trọng `models.mode: "replace"` bằng cách liệt kê `models.providers.*.models` rõ ràng thay vì tải toàn bộ danh mục tích hợp sẵn.
- Bộ chọn mô hình của giao diện điều khiển hỏi Gateway về chế độ xem mô hình đã cấu hình: `agents.defaults.models` khi có, nếu không thì `models.providers.*.models` rõ ràng cộng với các nhà cung cấp có xác thực dùng được. Toàn bộ danh mục tích hợp sẵn được dành cho các chế độ xem duyệt rõ ràng như `models.list` với `view: "all"` hoặc `openclaw models list --all`.
- Mặc định đã cấu hình (`agents.defaults.model.primary` và các mô hình chính riêng cho agent) là điểm bắt đầu thông thường và dùng `agents.defaults.model.fallbacks`.
- Các lựa chọn dự phòng tự động là trạng thái khôi phục tạm thời. Chúng được lưu với `modelOverrideSource: "auto"` để các lượt sau có thể tiếp tục dùng chuỗi dự phòng mà không cần thăm dò trước một mô hình chính đã biết là lỗi.
- Lựa chọn phiên của người dùng là chính xác. `/model`, bộ chọn mô hình, `session_status(model=...)`, và `sessions.patch` lưu `modelOverrideSource: "user"`; nếu nhà cung cấp/mô hình đã chọn đó không thể truy cập, OpenClaw sẽ lỗi hiển thị rõ thay vì rơi xuống một mô hình đã cấu hình khác.
- Cron `--model` / payload `model` là mô hình chính theo từng công việc. Nó vẫn dùng các dự phòng đã cấu hình trừ khi công việc cung cấp payload `fallbacks` rõ ràng (dùng `fallbacks: []` cho một lần chạy cron nghiêm ngặt).
- Các bộ chọn mô hình mặc định và danh sách cho phép của CLI tôn trọng `models.mode: "replace"` bằng cách liệt kê `models.providers.*.models` rõ ràng thay vì tải toàn bộ danh mục tích hợp sẵn.
- Bộ chọn mô hình Control UI hỏi Gateway về chế độ xem mô hình đã cấu hình: `agents.defaults.models` khi có, nếu không thì `models.providers.*.models` rõ ràng cộng với các nhà cung cấp có xác thực dùng được. Toàn bộ danh mục tích hợp sẵn chỉ dành cho các chế độ xem duyệt rõ ràng như `models.list` với `view: "all"` hoặc `openclaw models list --all`.
## Chính sách mô hình nhanh
- Đặt mô hình chính của bạn là mô hình thế hệ mới nhất mạnh nhất mà bạn có thể dùng.
- Dùng dự phòng cho các tác vụ nhạy cảm với chi phí/độ trễ và trò chuyện ít rủi ro hơn.
- Với tác tử có bật công cụ hoặc đầu vào không đáng tin cậy, tránh các tầng mô hình cũ/yếu hơn.
- Dùng dự phòng cho các tác vụ nhạy cảm về chi phí/độ trễ và trò chuyện ít rủi ro hơn.
- Với agent có bật công cụ hoặc đầu vào không đáng tin cậy, tránh các tầng mô hình cũ/yếu hơn.
## Thiết lập ban đầu (khuyến nghị)
## Onboarding (khuyến nghị)
Nếu bạn không muốn chỉnh sửa cấu hình thủ công, hãy chạy thiết lập ban đầu:
Nếu bạn không muốn chỉnh cấu hình thủ công, hãy chạy onboarding:
```bash
openclaw onboard
@ -99,38 +99,39 @@ Nó có thể thiết lập mô hình + xác thực cho các nhà cung cấp ph
- `models.providers` (nhà cung cấp tùy chỉnh được ghi vào `models.json`)
<Note>
Tham chiếu mô hình được chuẩn hóa thành chữ thường. Bí danh nhà cung cấp như `z.ai/*` chuẩn hóa thành `zai/*`.
Tham chiếu mô hình được chuẩn hóa thành chữ thường. Bí danh nhà cung cấp như `z.ai/*` được chuẩn hóa thành `zai/*`.
Ví dụ cấu hình nhà cung cấp (bao gồm OpenCode) nằm trong [OpenCode](/vi/providers/opencode).
</Note>
### Chỉnh sửa danh sách cho phép an toàn
Dùng thao tác ghi bổ sung khi cập nhật `agents.defaults.models` thủ công:
Dùng ghi bổ sung khi cập nhật thủ công `agents.defaults.models`:
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
```
<AccordionGroup>
<Accordion title="Quy tắc bảo vệ chống ghi đè">
`openclaw config set` bảo vệ các bản đồ mô hình/nhà cung cấp khỏi bị ghi đè ngoài ý muốn. Một phép gán đối tượng thuần vào `agents.defaults.models`, `models.providers`, hoặc `models.providers.<id>.models` sẽ bị từ chối khi nó sẽ xóa các mục hiện có. Dùng `--merge` cho các thay đổi bổ sung; chỉ dùng `--replace` khi giá trị được cung cấp nên trở thành toàn bộ giá trị đích.
<Accordion title="Quy tắc bảo vệ khỏi ghi đè">
`openclaw config set` bảo vệ các bản đồ mô hình/nhà cung cấp khỏi việc ghi đè ngoài ý muốn. Một phép gán đối tượng thuần cho `agents.defaults.models`, `models.providers`, hoặc `models.providers.<id>.models` sẽ bị từ chối khi nó sẽ xóa các mục hiện có. Dùng `--merge` cho thay đổi bổ sung; chỉ dùng `--replace` khi giá trị được cung cấp nên trở thành toàn bộ giá trị đích.
Thiết lập nhà cung cấp tương tác và `openclaw configure --section model` cũng hợp nhất các lựa chọn theo phạm vi nhà cung cấp vào danh sách cho phép hiện có, vì vậy việc thêm Codex, Ollama, hoặc một nhà cung cấp khác sẽ không làm mất các mục mô hình không liên quan. Cấu hình giữ nguyên `agents.defaults.model.primary` hiện có khi xác thực nhà cung cấp được áp dụng lại. Các lệnh đặt mặc định rõ ràng như `openclaw models auth login --provider <id> --set-default` và `openclaw models set <model>` vẫn thay thế `agents.defaults.model.primary`.
Thiết lập nhà cung cấp tương tác và `openclaw configure --section model` cũng hợp nhất các lựa chọn theo phạm vi nhà cung cấp vào danh sách cho phép hiện có, vì vậy việc thêm Codex, Ollama, hoặc một nhà cung cấp khác sẽ không làm mất các mục mô hình không liên quan. Configure giữ nguyên `agents.defaults.model.primary` hiện có khi xác thực nhà cung cấp được áp dụng lại. Các lệnh đặt mặc định rõ ràng như `openclaw models auth login --provider <id> --set-default` và `openclaw models set <model>` vẫn thay thế `agents.defaults.model.primary`.
</Accordion>
</AccordionGroup>
## "Mô hình không được phép" (và vì sao phản hồi dừng)
Nếu `agents.defaults.models` được đặt, nó trở thành **danh sách cho phép** cho `/model` và cho ghi đè phiên. Khi người dùng chọn một mô hình không có trong danh sách cho phép đó, OpenClaw trả về:
Nếu `agents.defaults.models` được đặt, nó trở thành **danh sách cho phép** cho `/model` và cho các ghi đè phiên. Khi người dùng chọn một mô hình không có trong danh sách cho phép đó, OpenClaw trả về:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
<Warning>
Điều này xảy ra **trước khi** một phản hồi bình thường được tạo, nên tin nhắn có thể tạo cảm giác như nó "không phản hồi." Cách sửa là:
Điều này xảy ra **trước khi** phản hồi thông thường được tạo, nên thông báo có thể khiến người dùng cảm thấy như nó "không phản hồi." Cách khắc phục là một trong các cách sau:
- Thêm mô hình vào `agents.defaults.models`, hoặc
- Xóa danh sách cho phép (xóa `agents.defaults.models`), hoặc
@ -138,10 +139,12 @@ Model "provider/model" is not allowed. Use /model to list available models.
</Warning>
Với các mô hình local/GGUF, hãy lưu tham chiếu đầy đủ có tiền tố nhà cung cấp trong danh sách cho phép,
Khi lệnh bị từ chối bao gồm ghi đè môi trường chạy như `/model openai/gpt-5.5 --runtime codex`, hãy sửa danh sách cho phép trước, rồi thử lại cùng lệnh `/model ... --runtime ...`. Với thực thi Codex gốc, mô hình đã chọn vẫn là `openai/gpt-5.5`; môi trường chạy `codex` chọn harness và dùng xác thực Codex riêng.
Với các mô hình cục bộ/GGUF, hãy lưu tham chiếu đầy đủ có tiền tố nhà cung cấp trong danh sách cho phép,
ví dụ `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf`, hoặc
nhà cung cấp/mô hình chính xác được hiển thị bởi `openclaw models list --provider <provider>`.
Chỉ tên tệp local hoặc tên hiển thị không đủ khi danh sách cho phép đang
provider/model chính xác do `openclaw models list --provider <provider>` hiển thị.
Tên tệp cục bộ trần hoặc tên hiển thị là chưa đủ khi danh sách cho phép đang
hoạt động.
Ví dụ cấu hình danh sách cho phép:
@ -158,9 +161,9 @@ Ví dụ cấu hình danh sách cho phép:
}
```
## Chuyển mô hình trong cuộc trò chuyện (`/model`)
## Chuyển đổi mô hình trong trò chuyện (`/model`)
Bạn có thể chuyển mô hình cho phiên hiện tại mà không cần khởi động lại:
Bạn có thể chuyển đổi mô hình cho phiên hiện tại mà không cần khởi động lại:
```
/model
@ -172,29 +175,29 @@ Bạn có thể chuyển mô hình cho phiên hiện tại mà không cần kh
<AccordionGroup>
<Accordion title="Hành vi của bộ chọn">
- `/model` (và `/model list`) là một bộ chọn nhỏ gọn, đánh số (họ mô hình + 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 danh sách thả xuống nhà cung cấp và mô hình, cộng với bước Gửi.
- Trên Telegram, các lựa chọn trong bộ chọn `/models` có phạm vi phiên; chúng không thay đổi mặc định bền vững của tác tử trong `openclaw.json`.
- `/models add` đã lỗi thời và hiện trả về thông báo lỗi thời thay vì đăng ký mô hình từ cuộc trò chuyện.
- `/model` (và `/model list`) là bộ chọn gọn, được đánh số (họ mô hình + 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 danh sách thả xuống nhà cung cấp và mô hình cùng bước Submit.
- Trên Telegram, các lựa chọn của bộ chọn `/models` có phạm vi phiên; chúng không thay đổi mặc định bền vững của agent trong `openclaw.json`.
- `/models add` đã lỗi thời và hiện trả về thông báo lỗi thời thay vì đăng ký mô hình từ trò chuyện.
- `/model <#>` chọn từ bộ chọn đó.
</Accordion>
<Accordion title="Lưu giữ và chuyển đổi trực tiếp">
- `/model` lưu lựa chọn 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 mô hình mới ngay.
- Nếu một lần chạy đang hoạt động, OpenClaw đánh dấu một 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 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 thử lại sau hoặc lượt người dùng tiếp theo.
- Một tham chiếu `/model` do người dùng chọn là nghiêm ngặt cho phiên đó: nếu nhà cung cấp/mô hình được chọn không truy cập được, phản hồi báo lỗi rõ ràng thay vì âm thầm trả lời từ `agents.defaults.model.fallbacks`. Điều này khác với mặc định đã cấu hình và mô hình chính của công việc cron, vốn vẫn có thể dùng chuỗi dự phòng.
- `/model status` là chế độ xem chi tiết (ứng viên xác thực và, khi được cấu hình, endpoint `baseUrl` của nhà cung cấp + chế độ `api`).
- Nếu agent đang rảnh, lần chạy tiếp theo dùng mô hình mới ngay.
- Nếu một lần chạy đã hoạt động, OpenClaw đánh dấu một 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 phản hồi đã bắt đầu, chuyển đổi đang chờ có thể tiếp tục được xếp hàng cho đến cơ hội thử lại sau đó hoặc lượt người dùng tiếp theo.
- Một tham chiếu `/model` do người dùng chọn là nghiêm ngặt cho phiên đó: nếu nhà cung cấp/mô hình đã chọn không thể truy cập, phản hồi sẽ lỗi hiển thị rõ thay vì âm thầm trả lời từ `agents.defaults.model.fallbacks`. Điều này khác với các mặc định đã cấu hình và mô hình chính của công việc cron, vốn vẫn có thể dùng chuỗi dự phòng.
- `/model status` là chế độ xem chi tiết (ứng viên xác thực và, khi đã cấu hình, `baseUrl` endpoint nhà cung cấp + chế độ `api`).
</Accordion>
<Accordion title="Phân tích tham chiếu">
- Tham chiếu mô hình được phân tích bằng cách tách theo dấu `/` **đầu tiên**. Dùng `provider/model` khi nhập `/model <ref>`.
- Nếu chính mã mô hình chứa `/` (kiểu OpenRouter), bạn phải bao gồm tiền tố nhà cung cấp (ví dụ: `/model openrouter/moonshotai/kimi-k2`).
- Tham chiếu mô hình được phân tích bằng cách tách tại dấu `/` **đầu tiên**. Dùng `provider/model` khi nhập `/model <ref>`.
- Nếu chính ID mô hình chứa `/` (kiểu OpenRouter), bạn phải bao gồm tiền tố nhà cung cấp (ví dụ: `/model openrouter/moonshotai/kimi-k2`).
- Nếu bạn bỏ qua nhà cung cấp, OpenClaw phân giải đầu vào theo thứ tự này:
1. khớp bí danh
2. khớp nhà cung cấp đã cấu hình duy nhất cho mã mô hình không có tiền tố chính xác đó
3. dự phòng lỗi thời 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 thay vào đó quay về nhà cung cấp/mô hình đã cấu hình đầu tiên để tránh hiển thị một mặc định nhà cung cấp đã xóa bị lỗi thời.
2. khớp nhà cung cấp đã cấu hình duy nhất cho đúng ID mô hình không có tiền tố đó
3. dự phòng lỗi thời 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 thay vào đó dự phòng về nhà cung cấp/mô hình đã cấu hình đầu tiên để tránh hiển thị một mặc định nhà cung cấp đã bị xóa và lỗi thời.
</Accordion>
</AccordionGroup>
@ -227,41 +230,41 @@ openclaw models image-fallbacks clear
### `models list`
Hiển thị các mô hình đã cấu hình/có xác thực khả dụng theo mặc định. Các cờ hữu ích:
Hiển thị các mô hình đã cấu hình/có xác thực theo mặc định. Các cờ hữu ích:
<ParamField path="--all" type="boolean">
Danh mục đầy đủ. Bao gồm các hàng danh mục tĩnh đi kèm thuộc sở hữu của nhà cung cấp trước khi xác thực được cấu hình, để các chế độ xem chỉ khám phá có thể hiển thị các mô hình chưa khả dụng cho đến khi bạn thêm thông tin xác thực nhà cung cấp tương ứng.
Danh mục đầy đủ. Bao gồm các hàng danh mục tĩnh đi kèm do nhà cung cấp sở hữu trước khi xác thực được cấu hình, để các chế độ xem chỉ dùng cho khám phá có thể hiển thị các mô hình chưa khả dụng cho đến khi bạn thêm thông tin xác thực nhà cung cấp tương ứng.
</ParamField>
<ParamField path="--local" type="boolean">
Chỉ các nhà cung cấp cục bộ.
</ParamField>
<ParamField path="--provider <id>" type="string">
Lọc theo id nhà cung cấp, ví dụ `moonshot`. Nhãn hiển thị từ bộ chọn tương tác không được chấp nhận.
Lọc theo id nhà cung cấp, ví dụ `moonshot`. Không chấp nhận nhãn hiển thị từ các bộ chọn tương tác.
</ParamField>
<ParamField path="--plain" type="boolean">
Mỗi dòng một mô hình.
</ParamField>
<ParamField path="--json" type="boolean">
Đầu ra máy có thể đọc được.
Đầu ra máy có thể đọc.
</ParamField>
### `models status`
Hiển thị mô hình chính đã phân giải, các phương án dự phòng, mô hình hình ảnh và tổng quan xác thực của các nhà cung cấp đã cấu hình. Lệnh này cũng hiển thị trạng thái hết hạn OAuth cho các hồ sơ tìm thấy trong kho xác thực (mặc định cảnh báo trong vòng 24 giờ). `--plain` chỉ in mô hình chính đã phân giải.
Hiển thị mô hình chính đã phân giải, các mô hình dự phòng, mô hình hình ảnh và tổng quan xác thực của các nhà cung cấp đã cấu hình. Lệnh này cũng hiển thị trạng thái hết hạn OAuth cho các hồ sơ tìm thấy trong kho xác thực (mặc định cảnh báo trong vòng 24 giờ). `--plain` chỉ in mô hình chính đã phân giải.
<AccordionGroup>
<Accordion title="Hành vi xác thực và thăm dò">
- Trạng thái OAuth luôn được hiển thị (và được bao gồm trong đầu ra `--json`). Nếu một nhà cung cấp đã cấu hình không có thông tin xác thực, `models status` sẽ in phần **Thiếu xác thực**.
- JSON bao gồm `auth.oauth` (khung thời gian cảnh báo + hồ sơ) và `auth.providers` (xác thực hiệu lực theo từng nhà cung cấp, bao gồm thông tin xác thực dựa trên env). `auth.oauth` chỉ là tình trạng hồ sơ trong kho xác thực; các nhà cung cấp chỉ dùng env không xuất hiện ở đó.
- Trạng thái OAuth luôn được hiển thị (và được đưa vào đầu ra `--json`). Nếu một nhà cung cấp đã cấu hình không có thông tin xác thực, `models status` sẽ in phần **Thiếu xác thực**.
- JSON bao gồm `auth.oauth` (khoảng cảnh báo + hồ sơ) và `auth.providers` (xác thực có hiệu lực theo từng nhà cung cấp, bao gồm thông tin xác thực từ env). `auth.oauth` chỉ là tình trạng hồ sơ trong kho xác thực; các nhà cung cấp chỉ dùng env không xuất hiện ở đó.
- Dùng `--check` cho tự động hóa (thoát `1` khi thiếu/hết hạn, `2` khi sắp hết hạn).
- Dùng `--probe` cho kiểm tra xác thực trực tiếp; các hàng thăm dò có thể đến từ hồ sơ xác thực, thông tin xác thực env hoặc `models.json`.
- Nếu `auth.order.<provider>` rõ ràng bỏ qua một hồ sơ đã lưu, thăm dò sẽ báo cáo `excluded_by_auth_order` thay vì thử hồ sơ đó. Nếu có xác thực nhưng không phân giải được mô hình nào có thể thăm dò cho nhà cung cấp đó, thăm dò sẽ báo cáo `status: no_model`.
- Dùng `--probe` cho các kiểm tra xác thực trực tiếp; các hàng thăm dò có thể đến từ hồ sơ xác thực, thông tin xác thực env hoặc `models.json`.
- Nếu `auth.order.<provider>` tường minh bỏ qua một hồ sơ đã lưu, thăm dò sẽ báo `excluded_by_auth_order` thay vì thử hồ sơ đó. Nếu có xác thực nhưng không thể phân giải mô hình có thể thăm dò cho nhà cung cấp đó, thăm dò sẽ báo `status: no_model`.
</Accordion>
</AccordionGroup>
<Note>
Lựa chọn xác thực phụ thuộc vào nhà cung cấp/tài khoản. Với các máy chủ Gateway luôn bật, khóa API thường dễ dự đoán nhất; việc dùng lại Claude CLI và các hồ sơ Anthropic OAuth/token hiện có cũng được hỗ trợ.
Lựa chọn xác thực phụ thuộc vào nhà cung cấp/tài khoản. Với các máy chủ Gateway luôn bật, API key thường là lựa chọn dễ dự đoán nhất; cũng hỗ trợ dùng lại Claude CLI và các hồ sơ Anthropic OAuth/token hiện có.
</Note>
Ví dụ (Claude CLI):
@ -298,7 +301,7 @@ openclaw models status
</ParamField>
<Note>
Danh mục `/models` của OpenRouter là công khai, nên các lượt quét chỉ siêu dữ liệu có thể liệt kê ứng viên miễn phí mà không cần khóa. Việc thăm dò và suy luận vẫn yêu cầu khóa API OpenRouter (từ hồ sơ xác thực hoặc `OPENROUTER_API_KEY`). Nếu không có khóa, `openclaw models scan` sẽ quay về đầu ra chỉ siêu dữ liệu và giữ nguyên cấu hình. Dùng `--no-probe` để yêu cầu rõ chế độ chỉ siêu dữ liệu.
Danh mục `/models` của OpenRouter là công khai, nên các lần quét chỉ siêu dữ liệu có thể liệt kê ứng viên miễn phí mà không cần khóa. Việc thăm dò và suy luận vẫn yêu cầu OpenRouter API key (từ hồ sơ xác thực hoặc `OPENROUTER_API_KEY`). Nếu không có khóa, `openclaw models scan` sẽ chuyển về đầu ra chỉ siêu dữ liệu và giữ nguyên cấu hình. Dùng `--no-probe` để yêu cầu rõ chế độ chỉ siêu dữ liệu.
</Note>
Kết quả quét được xếp hạng theo:
@ -311,37 +314,37 @@ Kết quả quét được xếp hạng theo:
Đầu vào:
- Danh sách `/models` của OpenRouter (bộ lọc `:free`)
- Thăm dò trực tiếp yêu cầu khóa API OpenRouter từ hồ sơ xác thực hoặc `OPENROUTER_API_KEY` (xem [Biến môi trường](/vi/help/environment))
- Thăm dò trực tiếp yêu cầu OpenRouter API key từ hồ sơ xác thực hoặc `OPENROUTER_API_KEY` (xem [Biến môi trường](/vi/help/environment))
- Bộ lọc tùy chọn: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
- Điều khiển yêu cầu/thăm dò: `--timeout`, `--concurrency`
Khi thăm dò trực tiếp chạy trong TTY, bạn có thể chọn các phương án dự phòng theo cách tương tác. Ở chế độ không tương tác, truyền `--yes` để chấp nhận mặc định. Kết quả chỉ siêu dữ liệu chỉ có tính thông tin; `--set-default` và `--set-image` yêu cầu thăm dò trực tiếp để OpenClaw không cấu hình một mô hình OpenRouter không dùng được vì không có khóa.
Khi thăm dò trực tiếp chạy trong TTY, bạn có thể chọn dự phòng một cách tương tác. Ở chế độ không tương tác, truyền `--yes` để chấp nhận mặc định. Kết quả chỉ siêu dữ liệu chỉ mang tính thông tin; `--set-default` và `--set-image` yêu cầu thăm dò trực tiếp để OpenClaw không cấu hình một mô hình OpenRouter không có khóa và không dùng được.
## Sổ đăng ký mô hình (`models.json`)
Các nhà cung cấp tùy chỉnh trong `models.providers` được ghi vào `models.json` dưới thư mục tác nhân (mặc định `~/.openclaw/agents/<agentId>/agent/models.json`). Tệp này được hợp nhất theo mặc định trừ khi `models.mode` được đặt thành `replace`.
Các nhà cung cấp tùy chỉnh trong `models.providers` được ghi vào `models.json` trong thư mục tác tử (mặc định `~/.openclaw/agents/<agentId>/agent/models.json`). Theo mặc định, tệp này được hợp nhất trừ khi `models.mode` được đặt thành `replace`.
<AccordionGroup>
<Accordion title="Thứ tự ưu tiên của chế độ hợp nhất">
Thứ tự ưu tiên của chế độ hợp nhất cho các ID nhà cung cấp khớp nhau:
Thứ tự ưu tiên của chế độ hợp nhất cho các ID nhà cung cấp khớp:
- `baseUrl` không rỗng đã có trong `models.json` của tác nhân sẽ được ưu tiên.
- `apiKey` không rỗng trong `models.json` của tác nhân chỉ được ưu tiên khi nhà cung cấp đó không do SecretRef quản lý trong ngữ cảnh cấu hình/hồ sơ xác thực hiện tại.
- Giá trị `apiKey` của nhà cung cấp do SecretRef quản lý được làm mới từ dấu nguồn (`ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec) thay vì lưu giữ bí mật đã phân giải.
- Giá trị header của nhà cung cấp do SecretRef quản lý được làm mới từ dấu nguồn (`secretref-env:ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec).
- `apiKey`/`baseUrl` rỗng hoặc bị thiếu của tác nhân sẽ quay về `models.providers` trong cấu hình.
- `baseUrl` không rỗng đã có trong `models.json` của tác tử sẽ thắng.
- `apiKey` không rỗng trong `models.json` của tác tử chỉ thắng khi nhà cung cấp đó không được SecretRef quản lý trong ngữ cảnh cấu hình/hồ sơ xác thực hiện tại.
- Giá trị `apiKey` của nhà cung cấp do SecretRef quản lý được làm mới từ các dấu nguồn (`ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec) thay vì lưu giữ bí mật đã phân giải.
- Giá trị header của nhà cung cấp do SecretRef quản lý được làm mới từ các dấu nguồn (`secretref-env:ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec).
- `apiKey`/`baseUrl` của tác tử bị rỗng hoặc thiếu sẽ dùng dự phòng từ `models.providers` trong cấu hình.
- Các trường nhà cung cấp khác được làm mới từ cấu hình và dữ liệu danh mục đã chuẩn hóa.
</Accordion>
</AccordionGroup>
<Note>
Việc lưu giữ dấu lấy nguồn làm thẩm quyền: OpenClaw ghi các dấu từ ảnh chụp nhanh cấu hình nguồn đang hoạt động (trước phân giải), không phải từ các giá trị bí mật runtime đã phân giải. Điều này áp dụng bất cứ khi nào OpenClaw tạo lại `models.json`, bao gồm các đường dẫn do lệnh điều khiển như `openclaw agent`.
Việc lưu giữ dấu lấy nguồn làm thẩm quyền: OpenClaw ghi các dấu từ ảnh chụp nhanh cấu hình nguồn đang hoạt động (trước phân giải), không phải từ các giá trị bí mật runtime đã phân giải. Điều này áp dụng mỗi khi OpenClaw tạo lại `models.json`, bao gồm các đường dẫn do lệnh điều khiển như `openclaw agent`.
</Note>
## Liên quan
- [Runtime tác nhân](/vi/concepts/agent-runtimes) — PI, Codex và các runtime vòng lặp tác nhân khác
- [Runtime tác tử](/vi/concepts/agent-runtimes) — Pi, Codex và các runtime vòng lặp tác tử khác
- [Tham chiếu cấu hình](/vi/gateway/config-agents#agent-defaults) — các khóa cấu hình mô hình
- [Tạo hình ảnh](/vi/tools/image-generation) — cấu hình mô hình hình ảnh
- [Chuyển đổi dự phòng mô hình](/vi/concepts/model-failover) — chuỗi dự phòng

621
docs/vi/concepts/qa-e2e-automation.md
View File

@ -1,67 +1,68 @@
---
read_when:
- Hiểu cách các thành phần trong ngăn xếp QA phối hợp với nhau
- 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 cho 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 vận chuyển trực tiếp, bộ điều hợp vận chuyển và báo cáo.'
- Thêm các kịch bản QA dựa trên repo
- Xây dựng tự động hóa đảm bảo chất lượng với độ chân thực cao hơn cho bảng điều khiển Gateway
summary: 'Tổng quan về stack QA: qa-lab, qa-channel, các kịch bản dựa trên kho mã, các lane truyền tải trực tiếp, bộ điều hợp truyền tải và báo cáo.'
title: Tổng quan về QA
x-i18n:
generated_at: "2026-05-04T07:04:51Z"
generated_at: "2026-05-05T01:45:56Z"
model: gpt-5.5
provider: openai
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
Stack QA riêng nhằm kiểm thử OpenClaw theo cách thực tế hơn, có hình dạng giống channel hơn so với một unit test đơn lẻ.
Ngăn xếp QA riêng tư nhằm kiểm thử OpenClaw theo cách thực tế hơn,
gần với hình dạng kênh hơn so với một kiểm thử đơn vị riêng lẻ.
Các phần hiện tại:
- `extensions/qa-channel`: channel thông điệp tổng hợp với các bề mặt DM, channel, thread,
reaction, edit và delete.
- `extensions/qa-lab`: UI gỡ lỗi và bus QA để quan sát transcript,
chèn thông điệp đến và xuất báo cáo Markdown.
- `extensions/qa-matrix`, các Plugin runner trong tương lai: adapter transport trực tiếp
điều khiển một channel thật bên trong 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-channel`: kênh tin nhắn tổng hợp với các bề mặt DM, kênh, luồng,
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 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: bộ chuyển đổi truyền tải trực tiếp
điều khiển một kênh thực bên trong một QA gateway con.
- `qa/`: tài sản seed dựa trên repo cho tác vụ khởi động và các kịch bản QA
đường 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ực, ảnh chụp màn hình trình duyệt, trạng thái VM và bằng chứng PR.
## Giao diện lệnh
## Bề mặt lệnh
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 trên lane Gateway QA. Bí danh: `pnpm openclaw qa suite --runner multipass` cho một Linux VM dùng một lần. |
| `qa coverage` | In inventory phạm vi bao phủ 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 kiểu 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 một lần trên lane provider/model đã chọn. |
| `qa ui` | Khởi động UI gỡ lỗi QA và bus QA cục bộ (bí danh: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Build image 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` | Build site QA, khởi động stack do Docker hậu thuẫn, 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 server provider AIMock. |
| `qa mock-openai` | Chỉ khởi động server provider `mock-openai` có nhận biết kịch bản. |
| `qa credentials doctor` / `add` / `list` / `remove` | Quản lý pool credential Convex dùng chung. |
| `qa matrix` | Lane transport trực tiếp trên homeserver Tuwunel dùng một lần. Xem [Matrix QA](/vi/concepts/qa-matrix). |
| `qa telegram` | Lane transport trực tiếp trên một nhóm Telegram riêng tư thật. |
| `qa discord` | Lane transport trực tiếp trên một channel guild Discord riêng tư thật. |
| `qa slack` | Lane transport trực tiếp trên một channel Slack 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 bằng chứng reaction trạng thái Discord, smoke desktop/trình duyệt Crabbox và smoke Slack trong VNC. Xem [Mantis](/vi/concepts/mantis). |
| `qa run` | Tự kiểm tra QA đóng gói; ghi báo cáo Markdown. |
| `qa suite` | Chạy các kịch bản dựa trên repo đối với làn QA gateway. Bí danh: `pnpm openclaw qa suite --runner multipass` cho một VM Linux dùng một lần. |
| `qa coverage` | In kiểm kê 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 tác tử. |
| `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 một báo cáo được chấm. Xem [Báo cáo](#reporting). |
| `qa manual` | Chạy một prompt một lần đối với làn nhà cung cấp/mô hình đã chọn. |
| `qa ui` | Khởi động giao diện trình gỡ lỗi QA và bus QA cục bộ (bí danh: `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 bảng điều khiển QA + làn 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ủ nhà cung cấp AIMock. |
| `qa mock-openai` | Chỉ khởi động máy chủ nhà cung cấp `mock-openai` có 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` | Làn truyền tải trực tiếp đối với một homeserver Tuwunel dùng một lần. Xem [Matrix QA](/vi/concepts/qa-matrix). |
| `qa telegram` | Làn truyền tải trực tiếp đối với một nhóm Telegram riêng tư thực. |
| `qa discord` | Làn truyền tải trực tiếp đối với một kênh guild Discord riêng tư thực. |
| `qa slack` | Làn truyền tải trực tiếp đối với một kênh Slack riêng tư thực. |
| `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, smoke desktop/trình duyệt Crabbox và smoke Slack-in-VNC. Xem [Mantis](/vi/concepts/mantis). |
## Luồng vận hành
Luồng vận hành QA hiện tại là một site QA hai khung:
Luồng vận hành QA hiện tại là một trang QA hai khung:
- Trái: bảng điều khiển 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 tác tử.
- 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 +70,13 @@ Chạy bằng:
pnpm qa:lab:up
```
Lệnh đó build site QA, khởi động lane Gateway do Docker hậu thuẫn, và mở trang
QA Lab nơi operator 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 channel thật, và ghi lại những gì hoạt động, thất bại hoặc
Lệnh đó xây dựng trang QA, khởi động làn Gateway dựa trên Docker và hiển thị
trang QA Lab, nơi một người vận hành hoặc vòng lặp tự động hóa có thể giao cho tác tử một
nhiệm vụ QA, quan sát hành vi kênh thực và ghi lại điều gì đã hoạt động, thất bại hoặc
vẫn bị chặn.
Để lặp UI QA Lab cục bộ nhanh hơn mà không rebuild image Docker mỗi lần,
hãy khởi động stack với bundle QA Lab được bind mount:
Để lặp giao diện QA Lab cục bộ nhanh hơn mà không cần xây dựng lại image Docker mỗi lần,
hãy khởi động ngăn xếp với gói QA Lab được bind-mount:
```bash
pnpm openclaw qa docker-build-image
@ -84,9 +85,9 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` giữ các dịch vụ Docker trên image đã dựng sẵn và bind-mount
`qa:lab:up:fast` giữ các dịch vụ Docker trên một image dựng sẵn và bind-mount
`extensions/qa-lab/web/dist` vào container `qa-lab`. `qa:lab:watch`
rebuild 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.
Để chạy smoke trace OpenTelemetry cục bộ, chạy:
@ -95,29 +96,29 @@ thay đổi.
pnpm qa:otel:smoke
```
Script đó khởi động một receiver trace OTLP/HTTP cục bộ, chạy kịch bản QA
`otel-trace-smoke` với Plugin `diagnostics-otel` được bật, rồi
giải mã các span protobuf đã xuất và assert hình dạng trọng yếu cho release:
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à khẳng định hình dạng quan trọng cho phát hành:
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
`openclaw.context.assembled` và `openclaw.message.delivery` phải có mặt;
các lần 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à
thuộc tính `openclaw.content.*` phải không xuất hiện trong trace. Script ghi
`otel-smoke-summary.json` cạnh các artifact của bộ QA.
các lệnh gọi mô hình không được xuất `StreamAbandoned` trong 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 của bộ QA.
QA quan sát được chỉ ở source checkout. Tarball npm cố ý bỏ qua
QA Lab, nên các lane release Docker package không chạy lệnh `qa`. Dùng
`pnpm qa:otel:smoke` từ một source checkout đã build khi thay đổi instrumentation
QA khả năng quan sát chỉ áp dụng cho checkout mã nguồn. Tarball npm cố ý bỏ qua
QA Lab, vì vậy các làn 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 checkout mã nguồn đã 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 làn smoke Matrix với truyền tải thực, chạy:
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
Tài liệu tham khảo CLI đầy đủ, catalog 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ó provision 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 giới hạn trong 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 được và log đầu ra kết hợp dưới `.artifacts/qa-e2e/matrix-<timestamp>/`.
Tham chiếu CLI đầy đủ, danh mục hồ sơ/kịch bản, biến môi trường và bố cục artifact cho làn này nằm trong [Matrix QA](/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ực bên trong một QA gateway con được giới hạn cho truyền tải đó (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 được và nhật ký đầu ra kết hợp dưới `.artifacts/qa-e2e/matrix-<timestamp>/`.
Đối với các lane smoke Telegram, Discord và Slack dùng transport thật:
Để chạy các làn smoke Telegram, Discord và Slack với truyền tải thực:
```bash
pnpm openclaw qa telegram
@ -125,9 +126,9 @@ pnpm openclaw qa discord
pnpm openclaw qa slack
```
Chúng nhắm tới một channel 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 credential Convex được ghi trong [Tài liệu tham khảo QA cho Telegram, Discord và Slack](#telegram-discord-and-slack-qa-reference) bên dưới.
Chúng nhắm đến một kênh thực đã 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à nhóm thông tin xác thực Convex được ghi tài liệu trong [Tham chiếu QA Telegram, Discord và Slack](#telegram-discord-and-slack-qa-reference) bên dưới.
Để chạy VM desktop Slack đầy đủ với cứu hộ VNC, chạy:
Để chạy đầy đủ VM desktop Slack với VNC cứu hộ, chạy:
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
@ -136,15 +137,15 @@ pnpm openclaw qa mantis slack-desktop-smoke \
--keep-lease
```
Lệnh đó thuê một máy desktop/trình duyệt Crabbox, chạy lane Slack trực tiếp
Lệnh đó thuê một máy desktop/trình duyệt Crabbox, chạy làn Slack trực tiếp
bên trong VM, mở Slack Web trong trình duyệt VNC, chụp desktop và
sao chép `slack-qa/` cùng `slack-desktop-smoke.png` về thư mục artifact
Mantis. Dùng lại `--lease-id <cbx_...>` sau khi đăng nhập thủ công vào Slack Web
qua VNC. Với `--gateway-setup`, Mantis để lại một Gateway Slack OpenClaw
liên tục chạy bên trong VM trên cổng `38973`; nếu không có, lệnh chạy
lane QA Slack bot-to-bot bình thường và thoát sau khi chụp artifact.
sao chép `slack-qa/` cùng `slack-desktop-smoke.png` về thư mục artifact Mantis.
Tái sử dụng `--lease-id <cbx_...>` sau khi đăng nhập vào Slack Web thủ công
thông qua VNC. Với `--gateway-setup`, Mantis để lại một Gateway Slack OpenClaw
bền vững đang chạy bên trong VM trên cổng `38973`; nếu không có tùy chọn đó, lệnh chạy
làn QA Slack bot-đến-bot bình thường và thoát sau khi chụp artifact.
Trước khi dùng credential trực tiếp trong pool, chạy:
Trước khi dùng thông tin xác thực trực tiếp trong nhóm, chạy:
```bash
pnpm openclaw qa credentials doctor
@ -152,63 +153,63 @@ 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.
## Phạm vi bao phủ transport trực tiếp
## Phạm vi 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 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 phải là một phần của ma trận phạm vi bao phủ transport trực tiếp.
Các làn truyền tải trực tiếp dùng chung một hợp đồng thay vì mỗi làn tự phát minh 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ạm vi truyền tải trực tiếp.
| Lane | Canary | Chặn bằng mention | Bot-to-bot | Chặn allowlist | Phản hồi cấp cao nhất | Tiếp tục sau restart | Follow-up trong thread | Cô lập thread | Quan sát reaction | 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 |
| Slack | x | x | x | | | | | | | | |
| Làn | Canary | Chặn theo mention | Bot-đến-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 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 |
| Slack | x | x | x | | | | | | | | |
Đ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 transport trực tiếp tương lai dùng chung một checklist
contract transport rõ ràng.
Đ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 trong tương lai dùng chung một checklist
hợp đồng truyền tải rõ ràng.
Để chạy lane Linux VM dùng một lần mà không đưa Docker vào đường dẫn QA, chạy:
Để chạy làn 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
```
Thao tác này khởi động một guest Multipass mới, cài đặt các dependency, build OpenClaw
Thao tác này khởi động một guest Multipass mới, cài đặt các phụ thuộc, build OpenClaw
bên trong guest, chạy `qa suite`, rồi sao chép báo cáo QA thông thường và
bản tóm tắt về `.artifacts/qa-e2e/...` trên host.
Nó tái sử dụng cùng hành vi chọn scenario như `qa suite` trên host.
Các lần chạy suite trên host và Multipass thực thi nhiều scenario đã chọn song song
với các worker gateway cô lập theo mặc định. `qa-channel` mặc định dùng concurrency
4, giới hạn bởi số lượng scenario đã chọn. Dùng `--concurrency <count>` để điều chỉnh
bản tóm tắt trở lại `.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 bộ kiểm thử trên host và Multipass thực thi song song nhiều kịch bản đã chọn
với các worker Gateway tách biệt theo mặc định. `qa-channel` mặc định concurrency
4, bị giới hạn bởi số lượng kịch bản đã chọn. Dùng `--concurrency <count>` để tinh chỉnh
số lượng worker, hoặc `--concurrency 1` để thực thi tuần tự.
Lệnh thoát với mã khác 0 khi bất kỳ scenario nào thất bại. Dùng `--allow-failures` khi
bạn muốn có artifact mà không có mã thoát báo lỗi.
Các lần chạy live chuyển tiếp những input xác thực QA được hỗ trợ và phù hợp thực tế cho
guest: khóa nhà cung cấp dựa trên env, đường dẫn cấu hình QA live provider, và
`CODEX_HOME` khi có. Giữ `--output-dir` dưới repo root để guest
Lệnh thoát với mã khác 0 khi bất kỳ kịch bản nào thất bại. Dùng `--allow-failures` khi
bạn muốn có hiện vật mà không có mã thoát thất bại.
Các lần chạy live chuyển tiếp các đầu vào xác thực 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 live QA, và
`CODEX_HOME` khi có. Giữ `--output-dir` dưới thư mục gốc repo để guest
có thể ghi ngược lại qua workspace đã mount.
## Tham chiếu QA cho Telegram, Discord và Slack
Matrix có một [trang riêng](/vi/concepts/qa-matrix) vì số lượng scenario và việc provisioning homeserver dựa trên Docker. Telegram, Discord và Slack nhỏ hơn — mỗi loại chỉ có vài scenario, không có hệ thống profile, chạy với các kênh thật đã tồn tại — nên phầ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à việc cấp phát homeserver dựa trên Docker. Telegram, Discord và Slack nhỏ hơn — mỗi kênh chỉ có một vài kịch bản, không có hệ thống hồ sơ, chạy với các kênh thực đã tồn tại — nên phần tham chiếu của chúng nằm ở đây.
### Các cờ CLI dùng chung
### Cờ CLI dùng chung
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 scenario 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/bản tóm tắt/thông điệp đã quan sát và log đầu ra. Đường dẫn tương đối được phân giải theo `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Repo root 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 | Ref 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 credential Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` trong CI, nếu không thì `maintainer` | Role đượ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 được và log đầu ra. Đường dẫn tương đối được resolve theo `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Thư mục gốc repository 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 provider | Tham chiếu model chính/phụ. |
| `--fast` | tắt | Chế độ nhanh của provider khi được hỗ trợ. |
| `--credential-source <env\|convex>` | `env` | Xem [pool thông tin đăng nhập 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`. |
Mỗi lane thoát với mã khác 0 khi có bất kỳ scenario nào thất bại. `--allow-failures` ghi artifact mà không đặt mã thoát báo lỗi.
Mỗi lane thoát với mã khác 0 khi có bất kỳ kịch bản nào thất bại. `--allow-failures` ghi hiện vật mà không đặt mã thoát thất bại.
### QA Telegram
@ -216,7 +217,7 @@ Mỗi lane thoát với mã khác 0 khi có bất kỳ scenario nào thất bạ
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ó username Telegram; quan sát bot-to-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ực với hai bot riêng biệt (driver + SUT). Bot SUT phải có username Telegram; việc 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`:
@ -226,9 +227,9 @@ Env bắt buộc khi `--credential-source env`:
Tùy chọn:
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` giữ nội dung thông điệp trong artifact thông điệp đã quan sát (mặc định biên tập lại).
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` giữ phần thân tin nhắn trong các hiện vật tin nhắn quan sát được (mặc định biên tập lại).
Scenario (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
Kịch bản (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
- `telegram-canary`
- `telegram-mention-gating`
@ -239,11 +240,11 @@ Scenario (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.
- `telegram-whoami-command`
- `telegram-context-command`
Artifact đầu ra:
Hiện vật đầu ra:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — bao gồm RTT theo từng reply (driver gửi → quan sát reply của SUT), bắt đầu từ canary.
- `telegram-qa-observed-messages.json` — phần thân được biên tập lại 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 được phản hồi SUT) bắt đầu từ canary.
- `telegram-qa-observed-messages.json` — phần thân bị biên tập lại trừ khi `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
### QA Discord
@ -251,7 +252,7 @@ Artifact đầ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 khởi động bởi OpenClaw gateway con thông qua Plugin Discord được đóng gói kèm. Xác minh cách xử lý mention trong kênh, rằng bot SUT đã đăng ký lệnh native `/help` với Discord, và các scenario bằng chứng Mantis dạng opt-in.
Nhắm tới một kênh guild Discord riêng tư thực với hai bot: bot driver do harness điều khiển và bot SUT được khởi động bởi Gateway OpenClaw con thông qua Plugin Discord đi kèm. Xác minh xử lý mention trong kênh, rằng bot SUT đã đăng ký lệnh gốc `/help` với Discord, và các kịch bản bằng chứng Mantis opt-in.
Env bắt buộc khi `--credential-source env`:
@ -259,20 +260,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 sớm).
- `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 artifact thông điệp đã quan sát.
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` giữ phần thân tin nhắn trong các hiện vật tin nhắn quan sát được.
Scenario (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`):
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` — scenario Mantis dạng opt-in. Chạy riêng vì nó chuyển SUT sang reply trong guild luôn bật, chỉ dùng công cụ với `messages.statusReactions.enabled=true`, rồi chụp timeline reaction REST cùng một artifact trực quan HTML/PNG.
- `discord-status-reactions-tool-only` — kịch bản Mantis opt-in. Tự chạy riêng vì nó chuyển SUT sang chế độ luôn bật, chỉ dùng công cụ để trả lời trong guild với `messages.statusReactions.enabled=true`, rồi ghi lại timeline reaction REST cùng một hiện vật trực quan HTML/PNG.
Chạy rõ ràng scenario status-reaction của Mantis:
Chạy kịch bản reaction trạng thái Mantis một cách tường minh:
```bash
pnpm openclaw qa discord \
@ -283,12 +284,12 @@ pnpm openclaw qa discord \
--fast
```
Artifact đầu ra:
Hiện vật đầu ra:
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — phần thân được biên tập lại trừ khi `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
- `discord-qa-reaction-timelines.json` và `discord-status-reactions-tool-only-timeline.png` khi scenario status-reaction chạy.
- `discord-qa-observed-messages.json` — phần thân bị biên tập lại 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 reaction trạng thái chạy.
### QA Slack
@ -296,7 +297,7 @@ Artifact đầu ra:
pnpm openclaw qa slack
```
Nhắm đến một kênh Slack riêng tư thật với hai bot riêng biệt: một bot driver do harness điều khiển và một bot SUT được khởi động bởi OpenClaw gateway con thông qua Plugin Slack được đóng gói kèm.
Nhắm tới một kênh Slack riêng tư thực 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 Gateway OpenClaw con thông qua Plugin Slack đi kèm.
Env bắt buộc khi `--credential-source env`:
@ -307,147 +308,322 @@ Env bắt buộc khi `--credential-source env`:
Tùy chọn:
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` giữ nội dung thông điệp trong artifact thông điệp đã quan sát.
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` giữ phần thân tin nhắn trong các hiện vật tin nhắn quan sát được.
Scenario (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`):
Kịch bản (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`):
- `slack-canary`
- `slack-mention-gating`
Artifact đầu ra:
Hiện vật đầu ra:
- `slack-qa-report.md`
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — phần thân được biên tập lại trừ khi `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
- `slack-qa-observed-messages.json` — phần thân bị biên tập lại trừ khi `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
### Nhóm credential Convex
#### Thiết lập workspace Slack
Các lane Telegram, Discord và Slack có thể lease credential từ một nhóm Convex dùng chung thay vì đọc các env var ở 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, Heartbeat nó trong suốt thời gian chạy, và giải phóng nó khi shutdown. Các loại pool là `"telegram"`, `"discord"` và `"slack"`.
Lane cần hai app Slack riêng biệt trong một workspace, cùng với một kênh mà cả hai bot đều là thành viên:
Dạng payload mà broker xác thực trên `admin/add`:
- `channelId` — id `Cxxxxxxxxxx` của kênh mà cả hai bot đã được mời vào. Dùng một kênh chuyên dụng; lane sẽ đăng bài ở mỗi lần chạy.
- `driverBotToken` — token bot (`xoxb-...`) của app **Driver**.
- `sutBotToken` — token bot (`xoxb-...`) của app **SUT**, phải là một app Slack riêng với driver để id người dùng bot của nó là riêng biệt.
- `sutAppToken` — token cấp app (`xapp-...`) của app SUT với `connections:write`, được Socket Mode dùng để app SUT có thể nhận sự kiện.
Ưu tiên một workspace Slack dành riêng cho QA hơn là tái sử dụng workspace production.
Manifest SUT bên dưới phản ánh bản cài production của Plugin Slack đi kèm (`extensions/slack/src/setup-shared.ts:10`). Để xem thiết lập kênh production như người dùng thấy, xem [thiết lập nhanh kênh Slack](/vi/channels/slack#quick-setup); cặp Driver/SUT QA được tách riêng có chủ ý vì lane cần hai id người dùng bot riêng biệt trong một workspace.
**1. Tạo app Driver**
Đi tới [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → chọn workspace QA, dán manifest sau, rồi _Install to Workspace_:
```json
{
"display_information": {
"name": "OpenClaw QA Driver",
"description": "Test driver bot for OpenClaw QA Slack live lane"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA Driver",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write", "channels:history", "groups:history", "users:read"]
}
},
"settings": {
"socket_mode_enabled": false
}
}
```
Sao chép _Bot User OAuth Token_ (`xoxb-...`) — token đó trở thành `driverBotToken`. Driver chỉ cần đăng tin nhắn và tự định danh; không cần sự kiện, không cần Socket Mode.
**2. Tạo app SUT**
Lặp lại _Create New App → From a manifest_ trong cùng workspace. Bộ scope phản ánh bản cài production của Plugin Slack đi kèm (`extensions/slack/src/setup-shared.ts:10`):
```json
{
"display_information": {
"name": "OpenClaw QA SUT",
"description": "OpenClaw QA SUT connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA SUT",
"always_online": true
},
"app_home": {
"home_tab_enabled": true,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
}
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"usergroups:read",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_home_opened",
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
Sau khi Slack tạo app, thực hiện hai việc trên trang cài đặt của app:
- _Install to Workspace_ → sao chép _Bot User OAuth Token_ → token đó trở thành `sutBotToken`.
- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → thêm scope `connections:write` → lưu → sao chép giá trị `xapp-...` → giá trị đó trở thành `sutAppToken`.
Xác minh hai bot có id người dùng riêng biệt bằng cách gọi `auth.test` trên từng token. Runtime phân biệt driver và SUT theo id người dùng; dùng lại một app cho cả hai sẽ khiến mention-gating thất bại ngay lập tức.
**3. Tạo kênh**
Trong workspace QA, tạo một kênh (ví dụ `#openclaw-qa`) và mời cả hai bot từ bên trong kênh:
```
/invite @OpenClaw QA Driver
/invite @OpenClaw QA SUT
```
Sao chép id `Cxxxxxxxxxx` từ _channel info → About → Channel ID_ — id đó trở thành `channelId`. Kênh công khai dùng được; nếu bạn dùng kênh riêng tư thì cả hai app đã có `groups:history`, nên các lần đọc lịch sử của harness vẫn sẽ thành công.
**4. Đăng ký thông tin xác thực**
Có hai tùy chọn. Dùng biến môi trường để gỡ lỗi trên một máy (đặt bốn biến `OPENCLAW_QA_SLACK_*` và truyền `--credential-source env`), hoặc seed pool Convex dùng chung để CI và các maintainer khác có thể thuê chúng.
Đối với pool Convex, ghi bốn trường vào một tệp JSON:
```json
{
"channelId": "Cxxxxxxxxxx",
"driverBotToken": "xoxb-...",
"sutBotToken": "xoxb-...",
"sutAppToken": "xapp-..."
}
```
Với `OPENCLAW_QA_CONVEX_SITE_URL` và `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` được export trong shell của bạn, đăng ký và xác minh:
```bash
pnpm openclaw qa credentials add \
--kind slack \
--payload-file slack-creds.json \
--note "QA Slack pool seed"
pnpm openclaw qa credentials list --kind slack --status all --json
```
Kỳ vọng `count: 1`, `status: "active"`, không có trường `lease`.
**5. Xác minh end to end**
Chạy lane cục bộ để xác nhận cả hai bot có thể nói chuyện với nhau qua broker:
```bash
pnpm openclaw qa slack \
--credential-source convex \
--credential-role maintainer \
--output-dir .artifacts/qa-e2e/slack-local
```
Một lần chạy xanh hoàn tất trong chưa đến 30 giây và `slack-qa-report.md` hiển thị cả `slack-canary` và `slack-mention-gating` ở trạng thái `pass`. Nếu lane treo khoảng 90 giây rồi thoát với `Convex credential pool exhausted for kind "slack"`, thì pool đang trống hoặc mọi hàng đều đã được thuê — `qa credentials list --kind slack --status all --json` sẽ cho bạn biết trường hợp nào.
### Pool thông tin xác thực Convex
Các lane Telegram, Discord và Slack có thể thuê thông tin xác thực từ pool Convex dùng chung thay vì đọc các biến môi trường ở 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, heartbeat lease đó trong suốt thời gian chạy, và giải phóng khi tắt. Các loại pool là `"telegram"`, `"discord"` và `"slack"`.
Các 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 }`.
- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` phải khớp `^[A-Z][A-Z0-9]+$` (một id Slack như `Cxxxxxxxxxx`). Xem [Thiết lập workspace Slack](#setting-up-the-slack-workspace) để cấp phát app và scope.
Các env var vận hành và contract endpoint của broker Convex nằm trong [Kiểm thử → Credential Telegram dùng chung qua Convex](/vi/help/testing#shared-telegram-credentials-via-convex-v1) (tên section có trước hỗ trợ Discord; ngữ nghĩa broker giống hệt cho cả hai loại).
Các biến môi trường 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 phần có trước khi hỗ trợ Discord; ngữ nghĩa broker giống hệt cho cả hai loại).
## Seed dựa trên repo
## Seed được repo hậu thuẫn
Asset seed nằm trong `qa/`:
Tài sản seed nằm trong `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
Chúng được đưa vào git có chủ ý để kế hoạch QA hiển thị cho cả con người và
Chúng được đưa vào git có chủ ý để kế hoạch QA hiển thị với cả con người lẫn
agent.
`qa-lab` nên tiếp tục là một runner markdown tổng quát. Mỗi file markdown scenario là
nguồn sự thật cho một lần chạy test và nên định nghĩa:
`qa-lab` nên tiếp tục là một runner markdown chung. Mỗi tệp markdown scenario là
nguồn sự thật cho một lần chạy kiểm thử và nên định nghĩa:
- metadata scenario
- metadata tùy chọn về category, capability, lane và risk
- ref docs và code
- yêu cầu Plugin tùy chọn
- patch cấu hình gateway tùy chọn
- metadata 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à tổng quát
và cắt ngang nhiều phần. Ví dụ, các scenario markdown có thể kết hợp helper phía transport
với helper phía browser điều khiển Control UI nhúng thông qua
seam Gateway `browser.request` mà không cần thêm runner xử lý riêng.
Bề mặt runtime tái sử dụng đứng sau `qa-flow` được phép tiếp tục là chung
và xuyên suốt. Ví dụ, các scenario 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 qua đường nối
Gateway `browser.request` mà không thêm runner theo trường hợp đặc biệt.
Các file scenario nên được nhóm theo capability sản phẩm thay vì thư mục source tree.
Giữ ID scenario ổn định khi di chuyển file; dùng `docsRefs` và `codeRefs`
để truy vết implementation.
Các tệp scenario nên được nhóm theo capability sản phẩm thay vì thư mục
cây nguồn. Giữ ổn định ID scenario 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 message action
- vòng đời hành động tin nhắn
- callback cron
- truy hồi memory
- truy hồi bộ nhớ
- chuyển đổi model
- bàn giao subagent
- đọc repo và đọc docs
- đọc repo và đọc tài liệu
- một tác vụ build nhỏ như Lobster Invaders
## Lane provider mock
## Lane mock provider
`qa suite` có hai lane provider mock cục bộ:
`qa suite` có hai lane mock provider cục bộ:
- `mock-openai` là mock OpenClaw nhận biết scenario. Nó tiếp tục là lane mock
xác định mặc định cho QA dựa trên repo và các gate parity.
- `aimock` khởi động một provider server dựa trên AIMock cho coverage giao thức,
- `mock-openai` là mock OpenClaw nhận biết scenario. Nó vẫn là lane mock
xác định mặc định cho QA dựa trên repo và parity gate.
- `aimock` khởi động một provider server dựa trên AIMock cho phạm vi protocol,
fixture, record/replay và chaos thử nghiệm. Nó là phần bổ sung và không
thay thế dispatcher scenario `mock-openai`.
thay thế bộ điều phối scenario `mock-openai`.
Implementation lane provider nằm dưới `extensions/qa-lab/src/providers/`.
Mỗi provider sở hữu mặc định, khởi động server cục bộ, cấu hình model gateway,
nhu cầu staging auth-profile, và cờ capability live/mock của nó. Code suite và
gateway dùng chung nên định tuyến qua provider registry thay vì rẽ nhánh theo
Triển khai provider-lane nằm dưới `extensions/qa-lab/src/providers/`.
Mỗi provider 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 staging auth-profile, và cờ capability live/mock. Mã suite và
gateway dùng chung nên định tuyến qua registry provider thay vì rẽ nhánh theo
tên provider.
## Adapter transport
## Bộ điều hợp transport
`qa-lab` sở hữu một seam transport tổng quát cho các scenario 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 synthetic trong tương lai nên cắm vào cùng suite runner thay vì thêm runner QA riêng cho từng transport.
`qa-lab` sở hữu một seam transport chung cho các scenario QA markdown. `qa-channel` là bộ điều hợp đầ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 suite runner thay vì thêm một QA runner riêng cho transport.
Ở cấp kiến trúc, phần tách như sau:
Ở cấp kiến trúc, phần tách là:
- `qa-lab` sở hữu thực thi scenario tổng quát, concurrency worker, ghi artifact và báo cáo.
- Adapter transport sở hữu cấu hình gateway, readiness, quan sát inbound và outbound, action transport, và trạng thái transport đã chuẩn hóa.
- Các file scenario markdown dưới `qa/scenarios/` định nghĩa lần chạy test; `qa-lab` cung cấp bề mặt runtime tái sử dụng để thực thi chúng.
- `qa-lab` sở hữu thực thi scenario chung, concurrency của worker, ghi artifact và báo cáo.
- Bộ điều hợp transport sở hữu cấu hình gateway, readiness, quan sát inbound và outbound, hành động transport, và trạng thái transport đã chuẩn hóa.
- Các tệp scenario 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 một kênh vào hệ thống QA markdown cần đúng hai thứ:
Thêm một kênh vào hệ thống QA markdown yêu cầu đúng hai việc:
1. Một adapter transport cho kênh.
2. Một gói scenario kiểm tra contract của kênh.
1. Một bộ điều hợp transport cho kênh.
2. Một gói scenario kiểm tra hợp đồng của kênh.
Không thêm 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 một root lệnh QA cấp cao mới khi host `qa-lab` dùng chung có thể sở hữu flow.
`qa-lab` sở hữu các cơ chế máy chủ dùng chung:
`qa-lab` sở hữu cơ chế host dùng chung:
- gốc lệnh `openclaw qa`
- khởi động và dọn dẹp bộ kiểm thử
- mức đồng thời của worker
- root lệnh `openclaw qa`
- khởi động và teardown suite
- concurrency của worker
- 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
- thực thi scenario
- alias tương thích cho các scenario `qa-channel` cũ hơn
Các Plugin trình chạy sở hữu hợp đồng truyền tải:
Runner plugin sở hữu hợp đồng transport:
- 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 truyền tải đó
- cách kiểm tra trạng thái sẵn sàng
- cách chèn sự kiện đi vào
- cách quan sát tin nhắn đi ra
- cách hiển thị bản ghi hội thoại và trạng thái truyền tải đã chuẩn hóa
- cách thực thi các hành động dựa trên truyền tải
- cách xử lý đặt lại hoặc dọn dẹp riêng cho truyền tải
- cách `openclaw qa <runner>` được mount bên dưới root `qa` dùng chung
- cách gateway được cấu hình cho transport đó
- cách readiness được kiểm tra
- cách sự kiện inbound được inject
- cách tin nhắn outbound được quan sát
- cách transcript và trạng thái transport đã chuẩn hóa được hiển thị
- cách các hành động dựa trên transport được thực thi
- cách reset hoặc dọn dẹp riêng cho transport được xử lý
Mức tối thiểu để áp dụng một kênh mới:
Mức tối thiểu để tiếp nhận một kênh mới:
1. Giữ `qa-lab` làm chủ sở hữu của gốc `qa` dùng chung.
2. Triển khai trình chạy truyền tải trên seam máy chủ `qa-lab` dùng chung.
3. Giữ các cơ chế riêng cho truyền tải bên trong Plugin trình chạy hoặc harness kênh.
4. Gắn trình chạy dưới dạng `openclaw qa <runner>` thay vì đăng ký một lệnh gốc cạnh tranh. Các Plugin trình chạy 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 lười tải và thực thi trình chạy nên nằm sau các entrypoint riêng.
5. Viết 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 helper kịch bản chung cho 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 đợt di trú có chủ ý.
1. Giữ `qa-lab` là chủ sở hữu root `qa` dùng chung.
2. Triển khai transport runner trên seam host `qa-lab` dùng chung.
3. Giữ cơ chế riêng cho transport bên trong runner plugin hoặc channel harness.
4. Mount runner dưới dạng `openclaw qa <runner>` thay vì đăng ký một root command cạnh tranh. Runner plugin nên khai báo `qaRunners` trong `openclaw.plugin.json` và export mảng `qaRunnerCliRegistrations` tương ứng 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 scenario markdown dưới các thư mục theo chủ đề `qa/scenarios/`.
6. Dùng helper scenario chung cho các scenario 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 migration có 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`, hãy đặt nó trong `qa-lab`.
- Nếu hành vi phụ thuộc vào một truyền tải kênh, hãy giữ nó trong Plugin trình chạy 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, hãy 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 truyền tải, hãy giữ kịch bản đó là riêng cho truyền tải và thể hiện rõ điều đó trong hợp đồng kịch bản.
- Nếu hành vi có thể được biểu diễn 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 runner plugin hoặc plugin harness đó.
- Nếu một scenario cần capability mới mà nhiều hơn một kênh có thể dùng, thêm helper chung thay vì 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ữ scenario riêng cho transport và nêu rõ điều đó trong hợp đồng scenario.
### Tên helper kịch bản
### Tên helper scenario
Các helper chung được ưu tiên cho kịch bản mới:
Các helper chung được ưu tiên cho scenario mới:
- `waitForTransportReady`
- `waitForChannelReady`
@ -462,22 +638,22 @@ Các helper chung được ưu tiên cho kịch bản mới:
- `formatTransportTranscript`
- `resetTransport`
Các alias tương thích vẫn có sẵn cho kịch bản hiện có — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — nhưng khi viết 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 đợt di trú đồng loạt, không phải là mô hình về sau.
Các alias tương thích vẫn có sẵn cho scenario hiện có — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — nhưng khi viết scenario mới nên dùng các tên chung. Các alias tồn tại để tránh một migration flag-day, không phải là mô hình về sau.
## Báo cáo
`qa-lab` xuất một báo cáo giao thức Markdown từ dòng thời gian bus đã quan sát.
`qa-lab` export một báo cáo protocol Markdown từ timeline bus được quan sát.
Báo cáo nên trả lời:
- Những gì đã hoạt động
- Những gì đã thất bại
- Những gì vẫn bị chặn
- Những kịch bản tiếp theo đáng thêm vào
- Điều gì đã hoạt động
- Điều gì đã thất bại
- Điều gì vẫn bị chặn
- Những scenario follow-up nào đáng thêm vào
Để xem danh mục các kịch bản có sẵn — hữu ích khi ước lượng công việc tiếp theo hoặc nối dây một truyền tải mới — hãy chạy `pnpm openclaw qa coverage` (thêm `--json` để có đầu ra máy đọc được).
Để xem inventory các scenario có sẵn — hữu ích khi ước lượng follow-up work hoặc nối dây một transport mới — chạy `pnpm openclaw qa coverage` (thêm `--json` để có đầu ra máy đọc được).
Để kiểm tra nhân vật và phong cách, chạy cùng một kịch bản trên nhiều ref mô hình live
và ghi một báo cáo Markdown đã được chấm:
Để kiểm tra nhân vật và phong cách, chạy cùng scenario trên nhiều ref model live
và ghi một báo cáo Markdown đã được đánh giá:
```bash
pnpm openclaw qa character-eval \
@ -496,36 +672,17 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
Lệnh này chạy các tiến trình con gateway QA cục bộ, không phải Docker. Các kịch bản đánh giá nhân vật
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à tác vụ tệp nhỏ. Không nên cho mô hình ứng viên
biết rằng nó đang được đánh giá. Lệnh giữ lại từng bản ghi hội thoại đầy đủ,
ghi lại các thống kê chạy cơ bản, rồi yêu cầu các mô hình chấm ở chế độ nhanh với
suy luận `xhigh` khi được hỗ trợ để xếp hạng các lượt chạy theo độ tự nhiên, vibe và tính hài hước.
Dùng `--blind-judge-models` khi so sánh các nhà cung cấp: prompt chấm vẫn nhận
mọi bản ghi hội thoại và trạng thái chạy, nhưng các ref ứng viên được thay bằng các
nhãn trung tính như `candidate-01`; báo cáo ánh xạ xếp hạng trở lại các ref 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 thinking `high`, với `medium` cho GPT-5.5 và `xhigh`
cho các ref đánh giá OpenAI cũ hơn có hỗ trợ. Ghi đè một ứng viên cụ thể trực tiếp bằng
`--model provider/model,thinking=<level>`. `--thinking <level>` vẫn đặt một
fallback toàn cục, và dạng cũ hơn `--model-thinking <provider/model=level>` được
giữ để tương thích.
Các ref ứng viên OpenAI mặc định dùng chế độ nhanh để dùng xử lý ưu tiên ở nơi
nhà cung cấp hỗ trợ. Thêm trực tiếp `,fast`, `,no-fast`, hoặc `,fast=false` khi một
ứng viên hoặc mô hình chấm riêng lẻ cần ghi đè. Chỉ truyền `--fast` khi bạn muốn
bắt buộc bật chế độ nhanh cho mọi mô hình ứng viên. Thời lượng của ứng viên và mô hình chấm
được ghi trong báo cáo để phân tích benchmark, nhưng prompt chấm nêu rõ
không xếp hạng theo tốc độ.
Các lượt chạy mô hình ứng viên và mô hình chấm đều mặc định có mức đồng thời 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 `--model` ứng viên, đánh giá nhân vật mặc định dùng
Lệnh này chạy các tiến trình con Gateway QA cục bộ, không phải Docker. Các kịch bản đánh giá nhân vật 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 mô hình ứng viên biết rằng nó đang được đánh giá. Lệnh này giữ lại từng bản ghi cuộc hội thoại đầy đủ, ghi lại số liệu chạy cơ bản, rồi yêu cầu các mô hình giám khảo ở chế độ nhanh với suy luận `xhigh` khi được hỗ trợ để xếp hạng các lần chạy theo độ tự nhiên, vibe và tính hài hước.
Dùng `--blind-judge-models` khi so sánh các nhà cung cấp: prompt giám khảo vẫn nhận mọi bản ghi cuộc hội thoại và trạng thái chạy, nhưng 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 tham chiếu thật sau khi phân tích cú pháp.
Các lần chạy ứng viên mặc định dùng mức 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ể trực tiếp bằng `--model provider/model,thinking=<level>`. `--thinking <level>` vẫn đặt giá trị dự phòng toàn cục, và dạng cũ hơn `--model-thinking <provider/model=level>` được giữ để tương thích.
Tham chiếu ứng viên OpenAI mặc định dùng chế độ nhanh để sử dụng xử lý ưu tiên khi nhà cung cấp hỗ trợ. Thêm trực tiếp `,fast`, `,no-fast` hoặc `,fast=false` 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 buộc bật chế độ nhanh cho mọi mô hình ứng viên. Thời lượng của ứng viên và giám khảo đều được ghi trong báo cáo để phân tích benchmark, nhưng prompt giám khảo nêu rõ không xếp hạng theo tốc độ.
Các lần chạy mô hình ứng viên và giám khảo đều mặc định có concurrency 16. Giảm `--concurrency` hoặc `--judge-concurrency` khi giới hạn của nhà cung cấp hoặc áp lực lên Gateway cục bộ khiến lần chạy quá nhiễu.
Khi không truyền ứng viên `--model`, đánh giá nhân vật 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à
`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 mô hình chấm mặc định là
Khi không truyền `--judge-model`, các giám khảo mặc định dùng
`openai/gpt-5.5,thinking=xhigh,fast` và
`anthropic/claude-opus-4-6,thinking=high`.
@ -534,4 +691,4 @@ Khi không truyền `--judge-model`, các mô hình chấm mặc định là
- [QA ma trận](/vi/concepts/qa-matrix)
- [Kênh QA](/vi/channels/qa-channel)
- [Kiểm thử](/vi/help/testing)
- [Dashboard](/vi/web/dashboard)
- [Bảng điều khiển](/vi/web/dashboard)

218
docs/vi/gateway/cli-backends.md
View File

@ -1,36 +1,36 @@
---
read_when:
- Bạn muốn có một phương án dự phòng đáng tin cậy khi các nhà cung cấp API gặp lỗi
- Bạn đang chạy Codex CLI hoặc các CLI trí tuệ nhân tạo cục bộ khác và muốn tái sử dụng chúng
- Bạn muốn hiểu cầu nối vòng lặp ngược MCP để truy cập công cụ của phần phụ trợ CLI
- Bạn đang chạy Codex CLI hoặc các CLI AI cục bộ khác và muốn tái sử dụng chúng
- Bạn muốn tìm hiểu cầu nối loopback MCP để truy cập công cụ backend của CLI
summary: 'Các phần phụ trợ CLI: phương án dự phòng CLI AI cục bộ với cầu nối công cụ MCP tùy chọn'
title: Các phần phụ trợ CLI
x-i18n:
generated_at: "2026-05-02T10:40:38Z"
generated_at: "2026-05-05T01:46:05Z"
model: gpt-5.5
provider: openai
source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16
source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1
source_path: gateway/cli-backends.md
workflow: 16
---
OpenClaw có thể chạy **CLI AI cục bộ** như một **phương án dự phòng chỉ văn bản** khi các nhà cung cấp API bị ngừng hoạt động,
bị giới hạn tốc độ, hoặc tạm thời hoạt động không đúng. Điều này được thiết kế có chủ ý theo hướng thận trọng:
OpenClaw có thể chạy **CLI AI cục bộ** như một **phương án dự phòng chỉ văn bản** khi các nhà cung cấp API ngừng hoạt động,
bị giới hạn tốc độ, hoặc tạm thời hoạt động bất thường. Thiết kế này có chủ ý thận trọng:
- **Các công cụ OpenClaw không được chèn trực tiếp**, nhưng các backend có `bundleMcp: true`
có thể nhận công cụ gateway qua một cầu nối MCP loopback.
- **Streaming JSONL** cho các CLI hỗ trợ.
- **Có hỗ trợ phiên** (để các lượt tiếp theo vẫn mạch lạc).
- **Có thể truyền hình ảnh qua** nếu CLI chấp nhận đường dẫn hình ảnh.
có thể nhận công cụ Gateway qua một cầu nối MCP loopback.
- **Phát trực tuyến JSONL** cho các CLI hỗ trợ tính năng này.
- **Hỗ trợ phiên** (để các lượt tiếp theo vẫn mạch lạc).
- **Có thể truyền hình ảnh xuyên suốt** nếu CLI chấp nhận đường dẫn hình ảnh.
Thiết kế này là một **lưới an toàn** hơn là một đường dẫn chính. Dùng nó khi bạn
Thiết kế này là một **lưới an toàn** hơn là đường dẫn chính. Hãy dùng nó khi bạn
muốn phản hồi văn bản “luôn hoạt động” mà không phụ thuộc vào API bên ngoài.
Nếu bạn muốn một runtime harness đầy đủ với điều khiển phiên ACP, tác vụ nền,
liên kết luồng/cuộc trò chuyện, và các phiên lập trình bên ngoài bền vững, hãy dùng
[ACP Agents](/vi/tools/acp-agents) thay thế. Các backend CLI không phải là ACP.
liên kết chuỗi/cuộc hội thoại, và các phiên lập trình bên ngoài bền vững, hãy dùng
[ACP Agents](/vi/tools/acp-agents) thay thế. Backend CLI không phải là ACP.
## Bắt đầu nhanh thân thiện với người mới
## Khởi động nhanh thân thiện với người mới
Bạn có thể dùng Codex CLI **mà không cần cấu hình nào** (Plugin OpenAI đi kèm
đăng ký một backend mặc định):
@ -39,7 +39,7 @@ Bạn có thể dùng Codex CLI **mà không cần cấu hình nào** (Plugin Op
openclaw agent --message "hi" --model codex-cli/gpt-5.5
```
Nếu gateway của bạn chạy dưới launchd/systemd và PATH tối giản, chỉ cần thêm
Nếu gateway của bạn chạy dưới launchd/systemd và PATH là tối thiểu, chỉ cần thêm
đường dẫn lệnh:
```json5
@ -58,9 +58,9 @@ Nếu gateway của bạn chạy dưới launchd/systemd và PATH tối giản,
Chỉ vậy thôi. Không cần khóa, không cần cấu hình xác thực bổ sung ngoài chính CLI.
Nếu bạn dùng một backend CLI đi kèm làm **nhà cung cấp thông điệp chính** trên
Nếu bạn dùng một backend CLI đi kèm làm **nhà cung cấp tin nhắn chính** trên một
máy chủ gateway, OpenClaw hiện tự động tải Plugin đi kèm sở hữu backend đó khi cấu hình của bạn
tham chiếu rõ ràng đến backend đó trong một model ref hoặc dưới
tham chiếu rõ ràng đến backend đó trong tham chiếu mô hình hoặc dưới
`agents.defaults.cliBackends`.
## Dùng làm phương án dự phòng
@ -86,7 +86,7 @@ Thêm một backend CLI vào danh sách dự phòng để nó chỉ chạy khi c
Ghi chú:
- Nếu bạn dùng `agents.defaults.models` (danh sách cho phép), bạn cũng phải bao gồm các mô hình backend CLI của mình ở đó.
- Nếu bạn dùng `agents.defaults.models` (danh sách cho phép), bạn cũng phải đưa các mô hình backend CLI của mình vào đó.
- Nếu nhà cung cấp chính thất bại (xác thực, giới hạn tốc độ, hết thời gian chờ), OpenClaw sẽ
thử backend CLI tiếp theo.
@ -98,8 +98,8 @@ Tất cả backend CLI nằm dưới:
agents.defaults.cliBackends
```
Mỗi mục được khóa bằng một **provider id** (ví dụ: `codex-cli`, `my-cli`).
Provider id trở thành phía bên trái của model ref:
Mỗi mục được khóa bằng một **id nhà cung cấp** (ví dụ `codex-cli`, `my-cli`).
id nhà cung cấp trở thành vế trái của tham chiếu mô hình của bạn:
```
<provider>/<model>
@ -148,43 +148,49 @@ Provider id trở thành phía bên trái của model ref:
## Cách hoạt động
1. **Chọn một backend** dựa trên tiền tố nhà cung cấp (`codex-cli/...`).
2. **Xây dựng system prompt** bằng cùng prompt OpenClaw + ngữ cảnh workspace.
3. **Thực thi CLI** với session id (nếu được hỗ trợ) để lịch sử vẫn nhất quán.
Backend `claude-cli` đi kèm giữ một tiến trình Claude stdio hoạt động cho mỗi
2. **Tạo system prompt** bằng cùng prompt OpenClaw + ngữ cảnh workspace.
3. **Thực thi CLI** với id phiên (nếu được hỗ trợ) để lịch sử luôn nhất quán.
Backend `claude-cli` đi kèm giữ một tiến trình Claude stdio còn sống cho mỗi
phiên OpenClaw và gửi các lượt tiếp theo qua stream-json stdin.
4. **Phân tích đầu ra** (JSON hoặc văn bản thuần) và trả về văn bản cuối cùng.
5. **Lưu giữ session id** theo backend, để các lượt tiếp theo tái sử dụng cùng phiên CLI.
5. **Lưu bền vững id phiên** theo từng backend, để các lượt tiếp theo tái sử dụng cùng phiên CLI.
<Note>
Backend Anthropic `claude-cli` đi kèm đã được hỗ trợ trở lại. Nhân viên Anthropic
đã cho chúng tôi biết rằng cách dùng Claude CLI kiểu OpenClaw lại được phép, vì vậy OpenClaw coi
Backend Anthropic `claude-cli` đi kèm đã được hỗ trợ lại. Nhân viên Anthropic
cho chúng tôi biết việc sử dụng Claude CLI theo kiểu OpenClaw đã được cho phép trở lại, vì vậy OpenClaw xem
việc dùng `claude -p` là được chấp thuận cho tích hợp này trừ khi Anthropic công bố
chính sách mới.
một chính sách mới.
</Note>
Backend OpenAI `codex-cli` đi kèm truyền system prompt của OpenClaw qua
ghi đè cấu hình `model_instructions_file` của Codex (`-c
model_instructions_file="..."`). Codex không cung cấp cờ kiểu Claude
`--append-system-prompt`, nên OpenClaw ghi prompt đã lắp ráp vào một
`--append-system-prompt`, vì vậy OpenClaw ghi prompt đã lắp ráp vào một
tệp tạm thời cho mỗi phiên Codex CLI mới.
Backend Anthropic `claude-cli` đi kèm nhận ảnh chụp nhanh Skills của OpenClaw
theo hai cách: danh mục Skills OpenClaw gọn trong system prompt được nối thêm, và
Backend Anthropic `claude-cli` đi kèm nhận snapshot skills của OpenClaw
theo hai cách: catalog skills OpenClaw nhỏ gọn trong system prompt được nối thêm, và
một Plugin Claude Code tạm thời được truyền bằng `--plugin-dir`. Plugin chỉ chứa
các Skills đủ điều kiện cho agent/phiên đó, nên bộ phân giải skill gốc của Claude Code
thấy cùng tập đã lọc mà nếu không OpenClaw sẽ quảng bá trong prompt.
Các ghi đè env/API key của skill vẫn được OpenClaw áp dụng cho
môi trường tiến trình con của lần chạy.
các skills đủ điều kiện cho agent/phiên đó, vì vậy bộ phân giải skill gốc của Claude Code
thấy cùng tập đã lọc mà OpenClaw nếu không sẽ quảng bá trong
prompt. Các ghi đè env/khóa API của skill vẫn được OpenClaw áp dụng vào
môi trường tiến trình con cho lần chạy.
Claude CLI cũng có chế độ quyền không tương tác riêng. OpenClaw ánh xạ chế độ đó
vào chính sách exec hiện có thay vì thêm cấu hình riêng cho Claude: khi
chính sách exec được yêu cầu hiệu lực là YOLO (`tools.exec.security: "full"` và
chính sách exec hiệu lực được yêu cầu là YOLO (`tools.exec.security: "full"` và
`tools.exec.ask: "off"`), OpenClaw thêm `--permission-mode bypassPermissions`.
Thiết lập `agents.list[].tools.exec` theo agent ghi đè `tools.exec` toàn cục cho
agent đó. Để ép một chế độ Claude khác, đặt các đối số backend thô rõ ràng
Thiết lập `agents.list[].tools.exec` theo từng agent ghi đè `tools.exec` toàn cục cho
agent đó. Để buộc một chế độ Claude khác, hãy đặt đối số backend thô rõ ràng
như `--permission-mode default` hoặc `--permission-mode acceptEdits` dưới
`agents.defaults.cliBackends.claude-cli.args` và `resumeArgs` tương ứng.
Backend Anthropic `claude-cli` đi kèm cũng ánh xạ các mức OpenClaw `/think`
sang cờ gốc `--effort` của Claude Code cho các mức không phải off. `minimal` và
`low` ánh xạ sang `low`, `adaptive` và `medium` ánh xạ sang `medium`, còn `high`,
`xhigh`, và `max` ánh xạ trực tiếp. Các backend CLI khác cần Plugin sở hữu của chúng
khai báo một bộ ánh xạ argv tương đương trước khi `/think` có thể ảnh hưởng đến CLI được sinh ra.
Trước khi OpenClaw có thể dùng backend `claude-cli` đi kèm, bản thân Claude Code
phải đã đăng nhập trên cùng máy chủ:
@ -206,59 +212,59 @@ chưa có sẵn trên `PATH`.
`resumeArgs` (thay thế `args` khi tiếp tục) và tùy chọn `resumeOutput`
(cho các lần tiếp tục không phải JSON).
- `sessionMode`:
- `always`: luôn gửi session id (UUID mới nếu chưa lưu).
- `existing`: chỉ gửi session id nếu trước đó đã lưu.
- `none`: không bao giờ gửi session id.
- `always`: luôn gửi id phiên (UUID mới nếu chưa có lưu trữ).
- `existing`: chỉ gửi id phiên nếu trước đó đã có lưu trữ.
- `none`: không bao giờ gửi id phiên.
- `claude-cli` mặc định là `liveSession: "claude-stdio"`, `output: "jsonl"`,
và `input: "stdin"` để các lượt tiếp theo tái sử dụng tiến trình Claude đang hoạt động khi
nó còn hoạt động. Stdio ấm hiện là mặc định, bao gồm cả cấu hình tùy chỉnh
và `input: "stdin"` để các lượt tiếp theo tái sử dụng tiến trình Claude đang chạy khi
nó còn hoạt động. Stdio ấm hiện là mặc định, kể cả với các cấu hình tùy chỉnh
bỏ qua các trường transport. Nếu Gateway khởi động lại hoặc tiến trình nhàn rỗi
thoát, OpenClaw tiếp tục từ session id Claude đã lưu. Các session
id đã lưu được xác minh với một transcript dự án hiện có có thể đọc trước khi
thoát, OpenClaw tiếp tục từ id phiên Claude đã lưu. Các id phiên đã lưu
được xác minh với transcript dự án có thể đọc hiện có trước khi
tiếp tục, nên các liên kết ảo bị xóa với `reason=transcript-missing`
thay vì âm thầm khởi động một phiên Claude CLI mới dưới `--resume`.
- Phiên Claude live giữ các giới hạn đầu ra JSONL có chặn. Mặc định cho phép tối đa
thay vì âm thầm bắt đầu một phiên Claude CLI mới dưới `--resume`.
- Các phiên Claude trực tiếp giữ các bộ bảo vệ đầu ra JSONL có giới hạn. Mặc định cho phép tối đa
8 MiB và 20.000 dòng JSONL thô mỗi lượt. Các lượt Claude dùng nhiều công cụ có thể tăng
chúng theo backend với
chúng theo từng backend bằng
`agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
và `maxTurnLines`; OpenClaw giới hạn các thiết lập đó ở 64 MiB và 100.000
và `maxTurnLines`; OpenClaw kẹp các thiết lập đó ở 64 MiB và 100.000
dòng.
- Các phiên CLI đã lưu là tính liên tục do nhà cung cấp sở hữu. Việc đặt lại phiên hằng ngày ngầm định
không cắt chúng; `/reset` và các chính sách `session.reset` rõ ràng vẫn
có hiệu lực.
Ghi chú về tuần tự hóa:
Ghi chú tuần tự hóa:
- `serialize: true` giữ các lần chạy cùng lane theo thứ tự.
- `serialize: true` giữ các lần chạy cùng lane theo đúng thứ tự.
- Hầu hết CLI tuần tự hóa trên một lane nhà cung cấp.
- OpenClaw bỏ tái sử dụng phiên CLI đã lưu khi danh tính xác thực được chọn thay đổi,
bao gồm auth profile id, API key tĩnh, token tĩnh, hoặc danh tính tài khoản OAuth
đã thay đổi khi CLI cung cấp. Việc xoay vòng access token và refresh token OAuth
- OpenClaw bỏ tái sử dụng phiên CLI đã lưu khi danh tính xác thực đã chọn thay đổi,
bao gồm id hồ sơ xác thực đã thay đổi, khóa API tĩnh, token tĩnh, hoặc
danh tính tài khoản OAuth khi CLI cung cấp danh tính đó. Việc xoay vòng token truy cập và làm mới OAuth
không cắt phiên CLI đã lưu. Nếu một CLI không cung cấp
OAuth account id ổn định, OpenClaw để CLI đó thực thi quyền tiếp tục.
id tài khoản OAuth ổn định, OpenClaw để CLI đó thực thi quyền tiếp tục.
## Prelude dự phòng từ các phiên claude-cli
Khi một lần thử `claude-cli` chuyển dự phòng sang một ứng viên không phải CLI trong
[`agents.defaults.model.fallbacks`](/vi/concepts/model-failover), OpenClaw gieo
lần thử tiếp theo bằng một prelude ngữ cảnh thu thập từ transcript JSONL cục bộ của Claude Code
Khi một lần thử `claude-cli` chuyển lỗi sang một ứng viên không phải CLI trong
[`agents.defaults.model.fallbacks`](/vi/concepts/model-failover), OpenClaw gieo ngữ cảnh ban đầu
cho lần thử tiếp theo bằng một prelude được thu thập từ transcript JSONL cục bộ của Claude Code
tại `~/.claude/projects/`. Nếu không có seed này, nhà cung cấp dự phòng
sẽ bắt đầu lạnh vì transcript phiên riêng của OpenClaw trống
cho các lần chạy `claude-cli`.
- Prelude ưu tiên bản tóm tắt `/compact` mới nhất hoặc dấu mốc `compact_boundary`,
rồi nối các lượt sau ranh giới gần nhất đến giới hạn ký tự.
- Prelude ưu tiên bản tóm tắt `/compact` mới nhất hoặc marker `compact_boundary`,
rồi nối thêm các lượt mới nhất sau ranh giới đến hết ngân sách ký tự.
Các lượt trước ranh giới bị bỏ vì bản tóm tắt đã đại diện cho
chúng.
- Các khối công cụ được gộp thành gợi ý gọn `(tool call: name)` và
- Các khối công cụ được gộp thành gợi ý nhỏ gọn `(tool call: name)` và
`(tool result: …)` để giữ ngân sách prompt trung thực. Bản tóm tắt được
gắn nhãn `(truncated)` nếu bị tràn.
gắn nhãn `(truncated)` nếu vượt quá giới hạn.
- Các dự phòng cùng nhà cung cấp từ `claude-cli` sang `claude-cli` dựa vào
`--resume` riêng của Claude và bỏ qua prelude.
- Seed tái sử dụng xác thực đường dẫn tệp phiên Claude hiện có, nên
- Seed tái sử dụng kiểm tra xác thực đường dẫn tệp phiên Claude hiện có, nên
không thể đọc các đường dẫn tùy ý.
## Hình ảnh (truyền qua)
## Hình ảnh (truyền xuyên suốt)
Nếu CLI của bạn chấp nhận đường dẫn hình ảnh, đặt `imageArg`:
@ -267,19 +273,19 @@ imageArg: "--image",
imageMode: "repeat"
```
OpenClaw sẽ ghi hình ảnh base64 vào tệp tạm. Nếu `imageArg` được đặt, các
đường dẫn đó được truyền làm đối số CLI. Nếu thiếu `imageArg`, OpenClaw nối
đường dẫn tệp vào prompt (chèn đường dẫn), điều này đủ cho các CLI tự động
OpenClaw sẽ ghi hình ảnh base64 vào các tệp tạm. Nếu `imageArg` được đặt, các
đường dẫn đó được truyền làm đối số CLI. Nếu thiếu `imageArg`, OpenClaw nối thêm
đường dẫn tệp vào prompt (path injection), điều này đủ cho các CLI tự động
tải tệp cục bộ từ đường dẫn thuần.
## Đầu vào / đầu ra
- `output: "json"` (mặc định) cố phân tích JSON và trích xuất văn bản + session id.
- `output: "json"` (mặc định) cố phân tích JSON và trích xuất văn bản + id phiên.
- Với đầu ra JSON của Gemini CLI, OpenClaw đọc văn bản trả lời từ `response` và
usage từ `stats` khi `usage` bị thiếu hoặc trống.
- `output: "jsonl"` phân tích các luồng JSONL (ví dụ Codex CLI `--json`) và trích xuất thông điệp agent cuối cùng cùng với các định danh phiên
mức sử dụng từ `stats` khi `usage` bị thiếu hoặc trống.
- `output: "jsonl"` phân tích các luồng JSONL (ví dụ Codex CLI `--json`) và trích xuất thông điệp agent cuối cùng cùng các định danh phiên
khi có.
- `output: "text"` coi stdout là phản hồi cuối cùng.
- `output: "text"` xem stdout là phản hồi cuối cùng.
Chế độ đầu vào:
@ -289,7 +295,7 @@ Chế độ đầu vào:
## Mặc định (do Plugin sở hữu)
Plugin OpenAI đi kèm cũng đăng ký mặc định cho `codex-cli`:
Plugin OpenAI đi kèm cũng đăng ký một mặc định cho `codex-cli`:
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -300,7 +306,7 @@ Plugin OpenAI đi kèm cũng đăng ký mặc định cho `codex-cli`:
- `imageArg: "--image"`
- `sessionMode: "existing"`
Plugin Google đi kèm cũng đăng ký mặc định cho `google-gemini-cli`:
Plugin Google đi kèm cũng đăng ký một mặc định cho `google-gemini-cli`:
- `command: "gemini"`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -318,7 +324,7 @@ Plugin Google đi kèm cũng đăng ký mặc định cho `google-gemini-cli`:
Ghi chú JSON của Gemini CLI:
- Văn bản trả lời được đọc từ trường JSON `response`.
- Usage dùng dự phòng từ `stats` khi `usage` vắng mặt hoặc trống.
- Usage dự phòng về `stats` khi `usage` vắng mặt hoặc trống.
- `stats.cached` được chuẩn hóa thành `cacheRead` của OpenClaw.
- Nếu thiếu `stats.input`, OpenClaw suy ra token đầu vào từ
`stats.input_tokens - stats.cached`.
@ -330,13 +336,13 @@ Chỉ ghi đè nếu cần (thường gặp: đường dẫn `command` tuyệt
Các mặc định backend CLI hiện là một phần của bề mặt Plugin:
- Các Plugin đăng ký chúng bằng `api.registerCliBackend(...)`.
- Backend `id` trở thành tiền tố nhà cung cấp trong các tham chiếu mô hình.
- `id` của backend trở thành tiền tố provider trong tham chiếu model.
- Cấu hình người dùng trong `agents.defaults.cliBackends.<id>` vẫn ghi đè mặc định của Plugin.
- Việc dọn dẹp cấu hình riêng cho backend vẫn do Plugin sở hữu thông qua hook
- Dọn dẹp cấu hình dành riêng cho backend vẫn do Plugin sở hữu thông qua hook
`normalizeConfig` tùy chọn.
Các Plugin cần các shim tương thích prompt/tin nhắn rất nhỏ có thể khai báo
các phép biến đổi văn bản hai chiều mà không cần thay thế nhà cung cấp hoặc backend CLI:
Các Plugin cần shim tương thích prompt/tin nhắn nhỏ có thể khai báo
các phép biến đổi văn bản hai chiều mà không cần thay thế provider hoặc backend CLI:
```typescript
api.registerTextTransforms({
@ -354,64 +360,64 @@ api.registerTextTransforms({
```
`input` viết lại system prompt và user prompt được truyền cho CLI. `output`
viết lại các delta assistant được stream và văn bản cuối cùng đã phân tích cú pháp trước khi OpenClaw xử lý
các marker điều khiển riêng và phân phối kênh.
viết lại các delta assistant được stream và văn bản cuối cùng đã phân tích trước khi OpenClaw xử lý
các marker điều khiển và việc gửi kênh của riêng nó.
Đối với các CLI phát ra JSONL tương thích stream-json của Claude Code, đặt
`jsonlDialect: "claude-stream-json"` trên cấu hình của backend đó.
Đối với các CLI phát ra JSONL tương thích với Claude Code stream-json, đặt
`jsonlDialect: "claude-stream-json"` trong cấu hình của backend đó.
## Lớp phủ MCP gói kèm
## Lớp phủ MCP bundle
Các backend CLI **không** nhận lệnh gọi công cụ OpenClaw trực tiếp, nhưng một backend có thể
chọn dùng lớp phủ cấu hình MCP được tạo bằng `bundleMcp: true`.
Các backend CLI **không** nhận trực tiếp lệnh gọi công cụ OpenClaw, nhưng một backend có thể
chọn dùng lớp phủ cấu hình MCP được tạo với `bundleMcp: true`.
Hành vi gói kèm hiện tại:
Hành vi được bundle hiện tại:
- `claude-cli`: tệp cấu hình MCP nghiêm ngặt được tạo
- `codex-cli`: ghi đè cấu hình inline cho `mcp_servers`; máy chủ
local loopback OpenClaw được tạo được đánh dấu bằng chế độ phê duyệt công cụ theo từng máy chủ của Codex
để các lệnh gọi MCP không thể bị dừng vì prompt phê duyệt cục bộ
- `codex-cli`: ghi đè cấu hình inline cho `mcp_servers`; máy chủ loopback
OpenClaw được tạo được đánh dấu bằng chế độ phê duyệt công cụ theo từng máy chủ của Codex
để các lệnh gọi MCP không thể bị kẹt ở lời nhắc phê duyệt cục bộ
- `google-gemini-cli`: tệp thiết lập hệ thống Gemini được tạo
Khi MCP gói kèm được bật, OpenClaw:
Khi bundle MCP được bật, OpenClaw:
- sinh một máy chủ MCP HTTP loopback để cung cấp công cụ Gateway cho tiến trình CLI
- khởi chạy một máy chủ MCP HTTP loopback để cung cấp công cụ Gateway cho tiến trình CLI
- xác thực cầu nối bằng token theo từng phiên (`OPENCLAW_MCP_TOKEN`)
- giới hạn quyền truy cập công cụ theo phiên, tài khoản và ngữ cảnh kênh hiện tại
- giới hạn quyền truy cập công cụ trong phạm vi phiên, tài khoản và ngữ cảnh kênh hiện tại
- tải các máy chủ bundle-MCP đã bật cho workspace hiện tại
- hợp nhất chúng với mọi dạng cấu hình/thiết lập MCP hiện có của backend
- hợp nhất chúng với mọi dạng cấu hình/thiết lập MCP backend hiện có
- viết lại cấu hình khởi chạy bằng chế độ tích hợp do backend sở hữu từ extension sở hữu
Nếu không có máy chủ MCP nào được bật, OpenClaw vẫn tiêm một cấu hình nghiêm ngặt khi một
backend chọn dùng MCP gói kèm để các lần chạy nền vẫn được cô lập.
Nếu không có máy chủ MCP nào được bật, OpenClaw vẫn tiêm cấu hình nghiêm ngặt khi một
backend chọn dùng bundle MCP để các lượt chạy nền vẫn được cô lập.
Các runtime MCP gói kèm theo phạm vi phiên được lưu vào bộ nhớ đệm để tái sử dụng trong một phiên, rồi
được thu hồi sau `mcp.sessionIdleTtlMs` mili giây không hoạt động (mặc định 10
phút; đặt `0` để tắt). Các lần chạy nhúng một lần như thăm dò xác thực,
tạo slug và yêu cầu gọi lại Active Memory sẽ dọn dẹp khi kết thúc lần chạy để các tiến trình con stdio
và stream Streamable HTTP/SSE không tồn tại lâu hơn lần chạy.
Runtime MCP được bundle theo phạm vi phiên được lưu vào cache để tái sử dụng trong một phiên, sau đó
được thu dọn sau `mcp.sessionIdleTtlMs` mili giây nhàn rỗi (mặc định 10
phút; đặt `0` để tắt). Các lượt chạy nhúng một lần như dò auth,
tạo slug và truy xuất Active Memory yêu cầu dọn dẹp khi lượt chạy kết thúc để các tiến trình con
stdio và luồng Streamable HTTP/SSE không tồn tại lâu hơn lượt chạy.
## Giới hạn
## Hạn chế
- **Không có lệnh gọi công cụ OpenClaw trực tiếp.** OpenClaw không tiêm lệnh gọi công cụ vào
giao thức backend CLI. Backend chỉ thấy công cụ Gateway khi chúng chọn dùng
giao thức backend CLI. Backend chỉ thấy công cụ Gateway khi chọn dùng
`bundleMcp: true`.
- **Streaming phụ thuộc vào backend.** Một số backend stream JSONL; các backend khác đệm
cho đến khi thoát.
- **Đầu ra có cấu trúc** phụ thuộc vào định dạng JSON của CLI.
- **Phiên Codex CLI** tiếp tục qua đầu ra văn bản (không có JSONL), vốn kém
cấu trúc hơn lần chạy `--json` ban đầu. Các phiên OpenClaw vẫn hoạt động
- **Phiên Codex CLI** tiếp tục qua đầu ra văn bản (không có JSONL), kém
cấu trúc hơn lượt chạy `--json` ban đầu. Các phiên OpenClaw vẫn hoạt động
bình thường.
## Khắc phục sự cố
- **Không tìm thấy CLI**: đặt `command` thành đường dẫn đầy đủ.
- **Sai tên mô hình**: dùng `modelAliases` để ánh xạ `provider/model` → mô hình CLI.
- **Không có tính liên tục phiên**: đảm bảo `sessionArg` được đặt và `sessionMode` không phải
- **Sai tên model**: dùng `modelAliases` để ánh xạ `provider/model` → model CLI.
- **Không có tính liên tục của phiên**: đảm bảo `sessionArg` được đặt và `sessionMode` không phải là
`none` (Codex CLI hiện chưa thể tiếp tục với đầu ra JSON).
- **Hình ảnh bị bỏ qua**: đặt `imageArg` (và xác minh CLI hỗ trợ đường dẫn tệp).
## Liên quan
- [Runbook Gateway](/vi/gateway)
- [Mô hình cục bộ](/vi/gateway/local-models)
- [Model cục bộ](/vi/gateway/local-models)

190
docs/vi/gateway/config-tools.md
View File

@ -1,44 +1,44 @@
---
read_when:
- Định cấu hình chính sách `tools.*`, danh sách cho phép hoặc các tính năng thử nghiệm
- Đăng ký nhà cung cấp tùy chỉnh hoặc ghi đè các URL cơ sở
- Cấu hình chính sách `tools.*`, danh sách cho phép hoặc các tính năng thử nghiệm
- Đăng ký nhà cung cấp tùy chỉnh hoặc ghi đè URL cơ sở
- Thiết lập các điểm cuối tự lưu trữ tương thích với OpenAI
sidebarTitle: Tools and custom providers
summary: Cấu hình công cụ (chính sách, công tắc thử nghiệm, công cụ được nhà cung cấp hỗ trợ) và thiết lập nhà cung cấp/URL cơ sở tùy chỉnh
summary: Cấu hình công cụ (chính sách, nút bật/tắt thử nghiệm, công cụ do nhà cung cấp hỗ trợ) và thiết lập nhà cung cấp/base-URL tùy chỉnh
title: Cấu hình — công cụ và nhà cung cấp tùy chỉnh
x-i18n:
generated_at: "2026-05-03T21:31:10Z"
generated_at: "2026-05-05T01:46:15Z"
model: gpt-5.5
provider: openai
source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da
source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883
source_path: gateway/config-tools.md
workflow: 16
---
`tools.*` khóa cấu hình và thiết lập nhà cung cấp / base-URL tùy chỉnh. Đối với agents, kênh và các khóa cấu hình cấp cao nhất khác, xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference).
Các khóa cấu hình `tools.*` và thiết lập nhà cung cấp tùy chỉnh / base-URL. Với agent, kênh và các khóa cấu hình cấp cao khác, xem [Tham chiếu cấu hình](/vi/gateway/configuration-reference).
## Công cụ
### Hồ sơ công cụ
`tools.profile` đặt danh sách cho phép cơ sở trước `tools.allow`/`tools.deny`:
`tools.profile` đặt allowlist cơ sở trước `tools.allow`/`tools.deny`:
<Note>
Quy trình onboarding cục bộ mặc định các cấu hình cục bộ mới thành `tools.profile: "coding"` khi chưa đặt (các hồ sơ tường minh hiện có được giữ nguyên).
Quy trình onboarding cục bộ mặc định cấu hình cục bộ mới thành `tools.profile: "coding"` khi chưa đặt (các hồ sơ tường minh hiện có được giữ nguyên).
</Note>
| Hồ sơ | Bao gồm |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | Chỉ `session_status` |
| `minimal` | chỉ `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | Không hạn chế (giống như chưa đặt) |
| `full` | Không giới hạn (giống như chưa đặt) |
### Nhóm công cụ
| Nhóm | Công cụ |
| Nhóm | Công cụ |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` được chấp nhận làm bí danh cho `exec`) |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` được chấp nhận làm bí danh cho `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
@ -49,11 +49,11 @@ Quy trình onboarding cục bộ mặc định các cấu hình cục bộ mới
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | Tất cả công cụ tích hợp sẵn (không bao gồm Plugin nhà cung cấp) |
| `group:openclaw` | Tất cả công cụ tích hợp sẵn (không bao gồm Plugin nhà cung cấp) |
### `tools.allow` / `tools.deny`
Chính sách cho phép/từ chối công cụ toàn cục (từ chối được ưu tiên). Không phân biệt chữ hoa chữ thường, hỗ trợ ký tự đại diện `*`. Được áp dụng ngay cả khi Docker sandbox tắt.
Chính sách cho phép/từ chối công cụ toàn cục (từ chối được ưu tiên). Không phân biệt chữ hoa chữ thường, hỗ trợ ký tự đại diện `*`. Được áp dụng ngay cả khi sandbox Docker tắt.
```json5
{
@ -61,7 +61,7 @@ Chính sách cho phép/từ chối công cụ toàn cục (từ chối được
}
```
`write` và `apply_patch` là các id công cụ riêng biệt. `allow: ["write"]` cũng bật `apply_patch` cho các mô hình tương thích, nhưng `deny: ["write"]` không từ chối `apply_patch`. Để chặn mọi thay đổi tệp, hãy từ chối `group:fs` hoặc liệt kê rõ từng công cụ có khả năng thay đổi:
`write` và `apply_patch` là các id công cụ riêng biệt. `allow: ["write"]` cũng bật `apply_patch` cho các mô hình tương thích, nhưng `deny: ["write"]` không từ chối `apply_patch`. Để chặn mọi thay đổi tệp, hãy từ chối `group:fs` hoặc liệt kê tường minh từng công cụ có thể thay đổi:
```json5
{
@ -71,7 +71,7 @@ Chính sách cho phép/từ chối công cụ toàn cục (từ chối được
### `tools.byProvider`
Hạn chế thêm công cụ cho các nhà cung cấp hoặc mô hình cụ thể. Thứ tự: hồ sơ cơ sở → hồ sơ nhà cung cấp → cho phép/từ chối.
Hạn chế thêm công cụ cho nhà cung cấp hoặc mô hình cụ thể. Thứ tự: hồ sơ cơ sở → hồ sơ nhà cung cấp → cho phép/từ chối.
```json5
{
@ -87,7 +87,7 @@ Hạn chế thêm công cụ cho các nhà cung cấp hoặc mô hình cụ th
### `tools.elevated`
Kiểm soát quyền truy cập exec nâng cao bên ngoài sandbox:
Kiểm soát quyền truy cập exec nâng quyền bên ngoài sandbox:
```json5
{
@ -103,9 +103,9 @@ Kiểm soát quyền truy cập exec nâng cao bên ngoài sandbox:
}
```
- Ghi đè theo agent (`agents.list[].tools.elevated`) chỉ có thể hạn chế thêm.
- `/elevated on|off|ask|full` lưu trạng thái theo từng phiên; chỉ thị nội tuyến áp dụng cho một tin nhắn.
- `exec` nâng cao bỏ qua sandboxing và dùng đường dẫn thoát đã cấu hình (`gateway` theo mặc định, hoặc `node` khi đích exec là `node`).
- Ghi đè theo từng agent (`agents.list[].tools.elevated`) chỉ có thể hạn chế thêm.
- `/elevated on|off|ask|full` lưu trạng thái theo phiên; chỉ thị inline áp dụng cho một tin nhắn.
- `exec` nâng quyền bỏ qua sandboxing và dùng đường dẫn thoát đã cấu hình (mặc định là `gateway`, hoặc `node` khi mục tiêu exec là `node`).
### `tools.exec`
@ -129,7 +129,7 @@ Kiểm soát quyền truy cập exec nâng cao bên ngoài sandbox:
### `tools.loopDetection`
Các kiểm tra an toàn vòng lặp công cụ **bị tắt theo mặc định**. Đặt `enabled: true` để kích hoạt phát hiện. Có thể định nghĩa thiết lập ở cấp toàn cục trong `tools.loopDetection` và ghi đè theo từng agent tại `agents.list[].tools.loopDetection`.
Các kiểm tra an toàn vòng lặp công cụ **bị tắt theo mặc định**. Đặt `enabled: true` để kích hoạt phát hiện. Có thể định nghĩa cài đặt toàn cục trong `tools.loopDetection` và ghi đè theo từng agent tại `agents.list[].tools.loopDetection`.
```json5
{
@ -151,7 +151,7 @@ Các kiểm tra an toàn vòng lặp công cụ **bị tắt theo mặc định*
```
<ParamField path="historySize" type="number">
Lịch sử lệnh gọi công cụ tối đa được giữ lại để phân tích vòng lặp.
Lịch sử gọi công cụ tối đa được giữ lại để phân tích vòng lặp.
</ParamField>
<ParamField path="warningThreshold" type="number">
Ngưỡng mẫu lặp lại không có tiến triển để cảnh báo.
@ -163,17 +163,17 @@ Các kiểm tra an toàn vòng lặp công cụ **bị tắt theo mặc định*
Ngưỡng dừng cứng cho mọi lượt chạy không có tiến triển.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
Cảnh báo khi lặp lại các lệnh gọi cùng công cụ/cùng đối số.
Cảnh báo khi lặp lại lệnh gọi cùng công cụ/cùng đối số.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
Cảnh báo/chặn trên các công cụ thăm dò đã biết (`process.poll`, `command_status`, v.v.).
Cảnh báo/chặn trên các công cụ poll đã biết (`process.poll`, `command_status`, v.v.).
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
Cảnh báo/chặn trên các mẫu cặp luân phiên không có tiến triển.
</ParamField>
<Warning>
Nếu `warningThreshold >= criticalThreshold` hoặc `criticalThreshold >= globalCircuitBreakerThreshold`, quá trình xác thực sẽ thất bại.
Nếu `warningThreshold >= criticalThreshold` hoặc `criticalThreshold >= globalCircuitBreakerThreshold`, việc xác thực không thành công.
</Warning>
### `tools.web`
@ -208,7 +208,7 @@ Nếu `warningThreshold >= criticalThreshold` hoặc `criticalThreshold >= globa
### `tools.media`
Cấu hình khả năng hiểu phương tiện đầu vào (hình ảnh/âm thanh/video):
Cấu hình khả năng hiểu media gửi đến (hình ảnh/âm thanh/video):
```json5
{
@ -216,7 +216,7 @@ Cấu hình khả năng hiểu phương tiện đầu vào (hình ảnh/âm than
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async video directly to the channel
directSend: false, // deprecated: completions stay agent-mediated
},
audio: {
enabled: true,
@ -246,8 +246,8 @@ Cấu hình khả năng hiểu phương tiện đầu vào (hình ảnh/âm than
```
<AccordionGroup>
<Accordion title="Các trường mục nhập mô hình phương tiện">
**Mục nhập nhà cung cấp** (`type: "provider"` hoặc bị bỏ qua):
<Accordion title="Các trường trong mục nhập mô hình media">
**Mục nhập nhà cung cấp** (`type: "provider"` hoặc bỏ qua):
- `provider`: id nhà cung cấp API (`openai`, `anthropic`, `google`/`gemini`, `groq`, v.v.)
- `model`: ghi đè id mô hình
@ -255,21 +255,21 @@ Cấu hình khả năng hiểu phương tiện đầu vào (hình ảnh/âm than
**Mục nhập CLI** (`type: "cli"`):
- `command`: tệp thực thi để chạy
- `args`: đối số theo mẫu (hỗ trợ `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, v.v.; `openclaw doctor --fix` di chuyển các placeholder `{input}` đã lỗi thời sang `{{MediaPath}}`)
- `command`: tệp thực thi cần chạy
- `args`: đối số theo mẫu (hỗ trợ `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, v.v.; `openclaw doctor --fix` di chuyển các placeholder `{input}` không còn dùng sang `{{MediaPath}}`)
**Các trường chung:**
- `capabilities`: danh sách tùy chọn (`image`, `audio`, `video`). Mặc định: `openai`/`anthropic`/`minimax` → hình ảnh, `google` → hình ảnh+âm thanh+video, `groq` → âm thanh.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: ghi đè theo từng mục nhập.
- `tools.media.image.timeoutSeconds` và các mục `timeoutSeconds` của mô hình hình ảnh tương ứng cũng áp dụng khi agent gọi công cụ `image` rõ ràng.
- `tools.media.image.timeoutSeconds` và các mục nhập `timeoutSeconds` của mô hình hình ảnh tương ứng cũng áp dụng khi agent gọi công cụ `image` rõ ràng.
- Lỗi sẽ chuyển dự phòng sang mục nhập tiếp theo.
Xác thực nhà cung cấp tuân theo thứ tự tiêu chuẩn: `auth-profiles.json` → biến môi trường → `models.providers.*.apiKey`.
Xác thực nhà cung cấp tuân theo thứ tự chuẩn: `auth-profiles.json` → biến môi trường → `models.providers.*.apiKey`.
**Các trường hoàn tất bất đồng bộ:**
- `asyncCompletion.directSend`: khi là `true`, các tác vụ phương tiện bất đồng bộ đã hoàn tất có hỗ trợ gửi hoàn tất trực tiếp sẽ thử gửi trực tiếp qua kênh trước. Mặc định: `false` (đường dẫn đánh thức phiên người yêu cầu/gửi qua mô hình). Hiện tại điều này áp dụng cho `video_generate` bất đồng bộ; các lần hoàn tất `music_generate` bất đồng bộ vẫn được trung gian qua phiên người yêu cầu ngay cả khi tùy chọn này được bật.
- `asyncCompletion.directSend`: cờ tương thích không còn dùng. Các tác vụ media bất đồng bộ đã hoàn tất vẫn được điều phối qua phiên của bên yêu cầu để agent nhận kết quả, quyết định cách báo cho người dùng và dùng công cụ tin nhắn khi việc chuyển phát từ nguồn yêu cầu.
</Accordion>
</AccordionGroup>
@ -289,7 +289,7 @@ Cấu hình khả năng hiểu phương tiện đầu vào (hình ảnh/âm than
### `tools.sessions`
Kiểm soát những phiên nào có thể được nhắm mục tiêu bởi các công cụ phiên (`sessions_list`, `sessions_history`, `sessions_send`).
Kiểm soát những phiên có thể được nhắm mục tiêu bởi các công cụ phiên (`sessions_list`, `sessions_history`, `sessions_send`).
Mặc định: `tree` (phiên hiện tại + các phiên do nó tạo ra, chẳng hạn như subagent).
@ -308,9 +308,9 @@ Mặc định: `tree` (phiên hiện tại + các phiên do nó tạo ra, chẳn
<Accordion title="Phạm vi hiển thị">
- `self`: chỉ khóa phiên hiện tại.
- `tree`: phiên hiện tại + các phiên do phiên hiện tại tạo ra (subagent).
- `agent`: bất kỳ phiên nào thuộc về id agent hiện tại (có thể bao gồm người dùng khác nếu bạn chạy phiên theo từng người gửi dưới cùng một id agent).
- `all`: bất kỳ phiên nào. Việc nhắm mục tiêu liên agent vẫn yêu cầu `tools.agentToAgent`.
- Kẹp sandbox: khi phiên hiện tại nằm trong sandbox và `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, khả năng hiển thị bị buộc thành `tree` ngay cả khi `tools.sessions.visibility="all"`.
- `agent`: bất kỳ phiên nào thuộc về id agent hiện tại (có thể bao gồm người dùng khác nếu bạn chạy các phiên theo từng người gửi dưới cùng một id agent).
- `all`: bất kỳ phiên nào. Việc nhắm mục tiêu xuyên agent vẫn yêu cầu `tools.agentToAgent`.
- Giới hạn sandbox: khi phiên hiện tại đang trong sandbox và `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, phạm vi hiển thị bị buộc thành `tree` ngay cả khi `tools.sessions.visibility="all"`.
</Accordion>
</AccordionGroup>
@ -337,12 +337,12 @@ Kiểm soát hỗ trợ tệp đính kèm nội tuyến cho `sessions_spawn`.
<AccordionGroup>
<Accordion title="Ghi chú về tệp đính kèm">
- Tệp đính kèm chỉ được hỗ trợ cho `runtime: "subagent"`. Runtime ACP sẽ từ chối chúng.
- Các tệp được hiện thực hóa vào workspace con tại `.openclaw/attachments/<uuid>/` cùng với một `.manifest.json`.
- Nội dung tệp đính kèm được tự động biên tập khỏi phần lưu giữ bản ghi hội thoại.
- Đầu vào Base64 được xác thực bằng các kiểm tra nghiêm ngặt về bảng ký tự/phần đệm và một chốt chặn kích thước trước khi giải mã.
- Tệp đính kèm chỉ được hỗ trợ cho `runtime: "subagent"`. Runtime ACP từ chối chúng.
- Các tệp được hiện thực hóa vào không gian làm việc con tại `.openclaw/attachments/<uuid>/` với một `.manifest.json`.
- Nội dung tệp đính kèm được tự động biên tập khỏi phần lưu trữ bản ghi.
- Đầu vào Base64 được xác thực bằng kiểm tra bảng chữ cái/phần đệm nghiêm ngặt và cơ chế bảo vệ kích thước trước khi giải mã.
- Quyền tệp là `0700` cho thư mục và `0600` cho tệp.
- Việc dọn dẹp tuân theo chính sách `cleanup`: `delete` luôn xóa tệp đính kèm; `keep` chỉ giữ lại chúng khi `retainOnSessionKeep: true`.
- Việc dọn dẹp tuân theo chính sách `cleanup`: `delete` luôn xóa tệp đính kèm; `keep` chỉ giữ chúng khi `retainOnSessionKeep: true`.
</Accordion>
</AccordionGroup>
@ -351,7 +351,7 @@ Kiểm soát hỗ trợ tệp đính kèm nội tuyến cho `sessions_spawn`.
### `tools.experimental`
Các cờ công cụ tích hợp thử nghiệm. Mặc định tắt trừ khi áp dụng quy tắc tự động bật GPT-5 strict-agentic.
Cờ công cụ tích hợp thử nghiệm. Mặc định tắt trừ khi áp dụng quy tắc tự động bật GPT-5 strict-agentic.
```json5
{
@ -364,8 +364,8 @@ Các cờ công cụ tích hợp thử nghiệm. Mặc định tắt trừ khi
```
- `planTool`: bật công cụ `update_plan` có cấu trúc để theo dõi công việc nhiều bước không tầm thường.
- Mặc định: `false` trừ khi `agents.defaults.embeddedPi.executionContract` (hoặc ghi đè theo từng agent) được đặt thành `"strict-agentic"` cho một lượt chạy OpenAI hoặc OpenAI Codex thuộc họ GPT-5. Đặt `true` để buộc bật công cụ ngoài phạm vi đó, hoặc `false` để giữ công cụ tắt ngay cả với các lượt chạy GPT-5 strict-agentic.
- Khi được bật, system prompt cũng thêm hướng dẫn sử dụng để mô hình chỉ dùng công cụ này cho công việc đáng kể và giữ tối đa một bước `in_progress`.
- Mặc định: `false` trừ khi `agents.defaults.embeddedPi.executionContract` (hoặc ghi đè theo từng agent) được đặt thành `"strict-agentic"` cho một lần chạy thuộc họ GPT-5 của OpenAI hoặc OpenAI Codex. Đặt `true` để buộc bật công cụ ngoài phạm vi đó, hoặc `false` để giữ tắt ngay cả với các lần chạy GPT-5 strict-agentic.
- Khi được bật, lời nhắc hệ thống cũng thêm hướng dẫn sử dụng để mô hình chỉ dùng công cụ này cho công việc đáng kể và giữ tối đa một bước `in_progress`.
### `agents.defaults.subagents`
@ -386,15 +386,15 @@ Các cờ công cụ tích hợp thử nghiệm. Mặc định tắt trừ khi
```
- `model`: mô hình mặc định cho các sub-agent được tạo. Nếu bỏ qua, sub-agent kế thừa mô hình của bên gọi.
- `allowAgents`: danh sách cho phép mặc định gồm các id agent đích cho `sessions_spawn` khi agent yêu cầu không tự đặt `subagents.allowAgents` của nó (`["*"]` = bất kỳ; mặc định: chỉ cùng agent).
- `allowAgents`: danh sách cho phép mặc định gồm các id agent đích cho `sessions_spawn` khi agent yêu cầu không đặt `subagents.allowAgents` riêng (`["*"]` = bất kỳ; mặc định: chỉ cùng agent).
- `runTimeoutSeconds`: thời gian chờ mặc định (giây) cho `sessions_spawn` khi lệnh gọi công cụ bỏ qua `runTimeoutSeconds`. `0` nghĩa là không có thời gian chờ.
- Chính sách công cụ theo từng subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
- Chính sách công cụ theo từng sub-agent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
## Nhà cung cấp tùy chỉnh và URL cơ sở
OpenClaw dùng catalog mô hình tích hợp. Thêm nhà cung cấp tùy chỉnh qua `models.providers` trong cấu hình hoặc `~/.openclaw/agents/<agentId>/agent/models.json`.
OpenClaw sử dụng danh mục mô hình tích hợp. Thêm nhà cung cấp tùy chỉnh qua `models.providers` trong cấu hình hoặc `~/.openclaw/agents/<agentId>/agent/models.json`.
```json5
{
@ -424,19 +424,19 @@ OpenClaw dùng catalog mô hình tích hợp. Thêm nhà cung cấp tùy chỉnh
```
<AccordionGroup>
<Accordion title="Xác thực và thứ tự ưu tiên hợp nhất">
- Dùng `authHeader: true` + `headers` cho các nhu cầu xác thực tùy chỉnh.
- Ghi đè gốc cấu hình agent bằng `OPENCLAW_AGENT_DIR` (hoặc `PI_CODING_AGENT_DIR`, một alias biến môi trường kế thừa).
<Accordion title="Xác thực và thứ tự ưu tiên khi hợp nhất">
- Dùng `authHeader: true` + `headers` cho nhu cầu xác thực tùy chỉnh.
- Ghi đè gốc cấu hình agent bằng `OPENCLAW_AGENT_DIR` (hoặc `PI_CODING_AGENT_DIR`, một bí danh biến môi trường kế thừa).
- Thứ tự ưu tiên hợp nhất cho các ID nhà cung cấp khớp nhau:
- Giá trị `baseUrl` không rỗng trong `models.json` của agent thắng.
- Giá trị `apiKey` không rỗng trong agent chỉ thắng khi nhà cung cấp đó không được SecretRef quản lý trong ngữ cảnh cấu hình/auth-profile hiện tại.
- Giá trị `apiKey` của nhà cung cấp do SecretRef quản lý được làm mới từ marker nguồn (`ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec) thay vì lưu giữ secret đã phân giải.
- Giá trị header của nhà cung cấp do SecretRef quản lý được làm mới từ marker nguồn (`secretref-env:ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec).
- `apiKey`/`baseUrl` của agent rỗng hoặc thiếu sẽ quay về `models.providers` trong cấu hình.
- `contextWindow`/`maxTokens` của mô hình khớp dùng giá trị cao hơn giữa cấu hình tường minh và giá trị catalog ngầm định.
- Giá trị `apiKey` không rỗng trong agent chỉ thắng khi nhà cung cấp đó không được SecretRef quản lý trong ngữ cảnh cấu hình/hồ sơ xác thực hiện tại.
- Giá trị `apiKey` của nhà cung cấp do SecretRef quản lý được làm mới từ dấu nguồn (`ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec) thay vì lưu bí mật đã phân giải.
- Giá trị header của nhà cung cấp do SecretRef quản lý được làm mới từ dấu nguồn (`secretref-env:ENV_VAR_NAME` cho tham chiếu env, `secretref-managed` cho tham chiếu file/exec).
- `apiKey`/`baseUrl` rỗng hoặc thiếu trong agent sẽ quay về `models.providers` trong cấu hình.
- `contextWindow`/`maxTokens` của mô hình khớp dùng giá trị cao hơn giữa cấu hình tường minh và giá trị danh mục ngầm định.
- `contextTokens` của mô hình khớp giữ nguyên giới hạn runtime tường minh khi có; dùng nó để giới hạn ngữ cảnh hiệu dụng mà không thay đổi siêu dữ liệu mô hình gốc.
- Dùng `models.mode: "replace"` khi bạn muốn cấu hình ghi lại hoàn toàn `models.json`.
- Việc lưu giữ marker lấy nguồn làm thẩm quyền: marker được ghi từ snapshot cấu hình nguồn đang hoạt động (trước phân giải), không phải từ giá trị secret runtime đã phân giải.
- Việc lưu dấu lấy nguồn làm thẩm quyền: dấu được ghi từ ảnh chụp cấu hình nguồn đang hoạt động (trước phân giải), không phải từ giá trị bí mật runtime đã phân giải.
</Accordion>
</AccordionGroup>
@ -444,49 +444,49 @@ OpenClaw dùng catalog mô hình tích hợp. Thêm nhà cung cấp tùy chỉnh
### Chi tiết trường nhà cung cấp
<AccordionGroup>
<Accordion title="Catalog cấp cao nhất">
- `models.mode`: hành vi catalog nhà cung cấp (`merge` hoặc `replace`).
<Accordion title="Danh mục cấp cao nhất">
- `models.mode`: hành vi danh mục nhà cung cấp (`merge` hoặc `replace`).
- `models.providers`: bản đồ nhà cung cấp tùy chỉnh được khóa theo id nhà cung cấp.
- Chỉnh sửa an toàn: dùng `openclaw config set models.providers.<id> '<json>' --strict-json --merge` hoặc `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` cho các cập nhật bổ sung. `config set` từ chối thay thế phá hủy trừ khi bạn truyền `--replace`.
- Chỉnh sửa an toàn: dùng `openclaw config set models.providers.<id> '<json>' --strict-json --merge` hoặc `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` để cập nhật bổ sung. `config set` từ chối thay thế phá hủy trừ khi bạn truyền `--replace`.
</Accordion>
<Accordion title="Kết nối và xác thực nhà cung cấp">
- `models.providers.*.api`: adapter yêu cầu (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, v.v.). Với các backend `/v1/chat/completions` tự host như MLX, vLLM, SGLang và hầu hết máy chủ cục bộ tương thích OpenAI, dùng `openai-completions`. Một nhà cung cấp tùy chỉnh có `baseUrl` nhưng không có `api` mặc định là `openai-completions`; chỉ đặt `openai-responses` khi backend hỗ trợ `/v1/responses`.
- `models.providers.*.api`: adapter yêu cầu (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, v.v.). Với backend `/v1/chat/completions` tự lưu trữ như MLX, vLLM, SGLang và hầu hết máy chủ cục bộ tương thích OpenAI, dùng `openai-completions`. Nhà cung cấp tùy chỉnh có `baseUrl` nhưng không có `api` mặc định là `openai-completions`; chỉ đặt `openai-responses` khi backend hỗ trợ `/v1/responses`.
- `models.providers.*.apiKey`: thông tin xác thực nhà cung cấp (ưu tiên SecretRef/thay thế env).
- `models.providers.*.auth`: chiến lược xác thực (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.contextWindow`: cửa sổ ngữ cảnh gốc mặc định cho các mô hình thuộc nhà cung cấp này khi mục mô hình không đặt `contextWindow`.
- `models.providers.*.contextTokens`: giới hạn ngữ cảnh runtime hiệu dụng mặc định cho các mô hình thuộc nhà cung cấp này khi mục mô hình không đặt `contextTokens`.
- `models.providers.*.maxTokens`: giới hạn token đầu ra mặc định cho các mô hình thuộc nhà cung cấp này khi mục mô hình không đặt `maxTokens`.
- `models.providers.*.timeoutSeconds`: thời gian chờ tùy chọn theo từng nhà cung cấp cho yêu cầu HTTP mô hình, tính bằng giây, bao gồm kết nối, header, body và xử lý hủy toàn bộ yêu cầu.
- `models.providers.*.contextWindow`: cửa sổ ngữ cảnh gốc mặc định cho các mô hình dưới nhà cung cấp này khi mục mô hình không đặt `contextWindow`.
- `models.providers.*.contextTokens`: giới hạn ngữ cảnh runtime hiệu dụng mặc định cho các mô hình dưới nhà cung cấp này khi mục mô hình không đặt `contextTokens`.
- `models.providers.*.maxTokens`: giới hạn token đầu ra mặc định cho các mô hình dưới nhà cung cấp này khi mục mô hình không đặt `maxTokens`.
- `models.providers.*.timeoutSeconds`: thời gian chờ tùy chọn theo từng nhà cung cấp cho yêu cầu HTTP mô hình, tính bằng giây, bao gồm kết nối, header, body và xử lý hủy tổng yêu cầu.
- `models.providers.*.injectNumCtxForOpenAICompat`: với Ollama + `openai-completions`, chèn `options.num_ctx` vào yêu cầu (mặc định: `true`).
- `models.providers.*.authHeader`: buộc vận chuyển thông tin xác thực trong header `Authorization` khi cần.
- `models.providers.*.baseUrl`: URL cơ sở API upstream.
- `models.providers.*.authHeader`: buộc truyền thông tin xác thực trong header `Authorization` khi cần.
- `models.providers.*.baseUrl`: URL cơ sở của API upstream.
- `models.providers.*.headers`: header tĩnh bổ sung cho định tuyến proxy/tenant.
</Accordion>
<Accordion title="Ghi đè truyền tải yêu cầu">
`models.providers.*.request`: ghi đè truyền tải cho yêu cầu HTTP tới nhà cung cấp mô hình.
`models.providers.*.request`: ghi đè truyền tải cho yêu cầu HTTP của nhà cung cấp mô hình.
- `request.headers`: header bổ sung (được hợp nhất với mặc định của nhà cung cấp). Giá trị chấp nhận SecretRef.
- `request.auth`: ghi đè chiến lược xác thực. Chế độ: `"provider-default"` (dùng xác thực tích hợp của nhà cung cấp), `"authorization-bearer"` (với `token`), `"header"` (với `headerName`, `value`, `prefix` tùy chọn).
- `request.proxy`: ghi đè HTTP proxy. Chế độ: `"env-proxy"` (dùng biến môi trường `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (với `url`). Cả hai chế độ chấp nhận một đối tượng con `tls` tùy chọn.
- `request.tls`: ghi đè TLS cho kết nối trực tiếp. Các trường: `ca`, `cert`, `key`, `passphrase` (tất cả chấp nhận SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: khi `true`, cho phép HTTPS tới `baseUrl` khi DNS phân giải tới dải riêng tư, CGNAT hoặc tương tự, thông qua chốt chặn fetch HTTP của nhà cung cấp (operator chủ động bật cho các endpoint tương thích OpenAI tự host đáng tin cậy). URL stream của nhà cung cấp mô hình dạng loopback như `localhost`, `127.0.0.1` và `[::1]` được tự động cho phép trừ khi giá trị này được đặt tường minh thành `false`; host LAN, tailnet và DNS riêng vẫn cần chủ động bật. WebSocket dùng cùng `request` cho header/TLS nhưng không dùng cổng SSRF fetch đó. Mặc định `false`.
- `request.proxy`: ghi đè proxy HTTP. Chế độ: `"env-proxy"` (dùng biến env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (với `url`). Cả hai chế độ chấp nhận một đối tượng con `tls` tùy chọn.
- `request.tls`: ghi đè TLS cho kết nối trực tiếp. Trường: `ca`, `cert`, `key`, `passphrase` (tất cả chấp nhận SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: khi `true`, cho phép HTTPS tới `baseUrl` khi DNS phân giải tới dải riêng tư, CGNAT hoặc tương tự, thông qua cơ chế bảo vệ fetch HTTP của nhà cung cấp (toán tử chủ động bật cho các endpoint tự lưu trữ tương thích OpenAI đáng tin cậy). URL stream nhà cung cấp mô hình local loopback như `localhost`, `127.0.0.1` và `[::1]` được cho phép tự động trừ khi mục này được đặt rõ ràng thành `false`; máy chủ LAN, tailnet và DNS riêng vẫn yêu cầu chủ động bật. WebSocket dùng cùng `request` cho header/TLS nhưng không dùng cổng SSRF fetch đó. Mặc định `false`.
</Accordion>
<Accordion title="Mục catalog mô hình">
- `models.providers.*.models`: các mục catalog mô hình tường minh của nhà cung cấp.
- `models.providers.*.models.*.input`: phương thức đầu vào của mô hình. Dùng `["text"]` cho mô hình chỉ văn bản và `["text", "image"]` cho mô hình image/vision gốc. Tệp đính kèm hình ảnh chỉ được chèn vào lượt agent khi mô hình được chọn được đánh dấu là có khả năng xử lý hình ảnh.
<Accordion title="Mục danh mục mô hình">
- `models.providers.*.models`: mục danh mục mô hình tường minh của nhà cung cấp.
- `models.providers.*.models.*.input`: phương thức đầu vào của mô hình. Dùng `["text"]` cho mô hình chỉ văn bản và `["text", "image"]` cho mô hình ảnh/thị giác gốc. Tệp đính kèm ảnh chỉ được chèn vào lượt agent khi mô hình đã chọn được đánh dấu là hỗ trợ ảnh.
- `models.providers.*.models.*.contextWindow`: siêu dữ liệu cửa sổ ngữ cảnh gốc của mô hình. Giá trị này ghi đè `contextWindow` cấp nhà cung cấp cho mô hình đó.
- `models.providers.*.models.*.contextTokens`: giới hạn ngữ cảnh runtime tùy chọn. Giá trị này ghi đè `contextTokens` cấp nhà cung cấp; dùng nó khi bạn muốn ngân sách ngữ cảnh hiệu dụng nhỏ hơn `contextWindow` gốc của mô hình; `openclaw models list` hiển thị cả hai giá trị khi chúng khác nhau.
- `models.providers.*.models.*.contextTokens`: giới hạn ngữ cảnh runtime tùy chọn. Giá trị này ghi đè `contextTokens` cấp nhà cung cấp; dùng khi bạn muốn ngân sách ngữ cảnh hiệu dụng nhỏ hơn `contextWindow` gốc của mô hình; `openclaw models list` hiển thị cả hai giá trị khi chúng khác nhau.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: gợi ý tương thích tùy chọn. Với `api: "openai-completions"` có `baseUrl` không rỗng và không phải gốc (host không phải `api.openai.com`), OpenClaw buộc giá trị này thành `false` tại runtime. `baseUrl` rỗng/bị bỏ qua giữ hành vi OpenAI mặc định.
- `models.providers.*.models.*.compat.requiresStringContent`: gợi ý tương thích tùy chọn cho các endpoint chat tương thích OpenAI chỉ hỗ trợ chuỗi. Khi `true`, OpenClaw làm phẳng các mảng `messages[].content` chỉ gồm văn bản thuần thành chuỗi đơn giản trước khi gửi yêu cầu.
- `models.providers.*.models.*.compat.requiresStringContent`: gợi ý tương thích tùy chọn cho endpoint chat tương thích OpenAI chỉ nhận chuỗi. Khi `true`, OpenClaw làm phẳng các mảng `messages[].content` văn bản thuần thành chuỗi thường trước khi gửi yêu cầu.
</Accordion>
<Accordion title="Khám phá Amazon Bedrock">
- `plugins.entries.amazon-bedrock.config.discovery`: gốc thiết lập tự động khám phá Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery`: gốc cài đặt tự động khám phá Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: bật/tắt khám phá ngầm định.
- `plugins.entries.amazon-bedrock.config.discovery.region`: vùng AWS để khám phá.
- `plugins.entries.amazon-bedrock.config.discovery.region`: vùng AWS cho khám phá.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: bộ lọc id nhà cung cấp tùy chọn cho khám phá có mục tiêu.
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: khoảng thăm dò để làm mới khám phá.
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: cửa sổ ngữ cảnh dự phòng cho các mô hình được khám phá.
@ -495,13 +495,13 @@ OpenClaw dùng catalog mô hình tích hợp. Thêm nhà cung cấp tùy chỉnh
</Accordion>
</AccordionGroup>
Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hình ảnh cho các ID mô hình vision phổ biến như GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V và GLM-4V, đồng thời bỏ qua câu hỏi bổ sung cho các họ chỉ văn bản đã biết. ID mô hình không xác định vẫn nhắc hỏi về hỗ trợ hình ảnh. Onboarding không tương tác dùng cùng suy luận; truyền `--custom-image-input` để buộc siêu dữ liệu có khả năng xử lý hình ảnh hoặc `--custom-text-input` để buộc siêu dữ liệu chỉ văn bản.
Quy trình thiết lập nhà cung cấp tùy chỉnh tương tác suy luận đầu vào ảnh cho các ID mô hình thị giác phổ biến như GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V và GLM-4V, đồng thời bỏ qua câu hỏi bổ sung cho các họ đã biết là chỉ văn bản. ID mô hình không xác định vẫn nhắc về hỗ trợ ảnh. Quy trình thiết lập không tương tác dùng cùng suy luận; truyền `--custom-image-input` để buộc siêu dữ liệu hỗ trợ ảnh hoặc `--custom-text-input` để buộc siêu dữ liệu chỉ văn bản.
### Ví dụ về nhà cung cấp
<AccordionGroup>
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
Plugin nhà cung cấp `cerebras` đi kèm có thể cấu hình phần này qua `openclaw onboard --auth-choice cerebras-api-key`. Chỉ dùng cấu hình nhà cung cấp tường minh khi ghi đè mặc định.
Plugin nhà cung cấp `cerebras` được đóng gói có thể cấu hình mục này qua `openclaw onboard --auth-choice cerebras-api-key`. Chỉ dùng cấu hình nhà cung cấp tường minh khi ghi đè mặc định.
```json5
{
@ -535,10 +535,10 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
}
```
Sử dụng `cerebras/zai-glm-4.7` cho Cerebras; `zai/glm-4.7` cho Z.AI trực tiếp.
Dùng `cerebras/zai-glm-4.7` cho Cerebras; `zai/glm-4.7` cho Z.AI trực tiếp.
</Accordion>
<Accordion title="Kimi Coding">
<Accordion title="Lập trình Kimi">
```json5
{
env: { KIMI_API_KEY: "sk-..." },
@ -551,11 +551,11 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
}
```
Tương thích với Anthropic, nhà cung cấp tích hợp sẵn. Lối tắt: `openclaw onboard --auth-choice kimi-code-api-key`.
Tương thích Anthropic, provider tích hợp sẵn. Lối tắt: `openclaw onboard --auth-choice kimi-code-api-key`.
</Accordion>
<Accordion title="Mô hình cục bộ (LM Studio)">
Xem [Mô hình cục bộ](/vi/gateway/local-models). Tóm tắt: chạy một mô hình cục bộ lớn qua LM Studio Responses API trên phần cứng mạnh; giữ các mô hình được lưu trữ đã hợp nhất để dự phòng.
Xem [Mô hình cục bộ](/vi/gateway/local-models). Tóm tắt: chạy một mô hình cục bộ lớn qua LM Studio Responses API trên phần cứng mạnh; giữ các mô hình được lưu trữ đã gộp để dự phòng.
</Accordion>
<Accordion title="MiniMax M2.7 (trực tiếp)">
```json5
@ -592,7 +592,7 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
}
```
Đặt `MINIMAX_API_KEY`. Lối tắt: `openclaw onboard --auth-choice minimax-global-api` hoặc `openclaw onboard --auth-choice minimax-cn-api`. Danh mục mô hình mặc định chỉ có M2.7. Trên đường dẫn phát trực tuyến tương thích Anthropic, OpenClaw tắt khả năng suy nghĩ của MiniMax theo mặc định trừ khi bạn tự đặt rõ `thinking`. `/fast on` hoặc `params.fastMode: true` viết lại `MiniMax-M2.7` thành `MiniMax-M2.7-highspeed`.
Đặt `MINIMAX_API_KEY`. Lối tắt: `openclaw onboard --auth-choice minimax-global-api` hoặc `openclaw onboard --auth-choice minimax-cn-api`. Danh mục mô hình mặc định chỉ dùng M2.7. Trên đường dẫn streaming tương thích Anthropic, OpenClaw tắt chế độ suy nghĩ của MiniMax theo mặc định trừ khi bạn tự đặt rõ `thinking`. `/fast on` hoặc `params.fastMode: true` viết lại `MiniMax-M2.7` thành `MiniMax-M2.7-highspeed`.
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -629,9 +629,9 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
}
```
Đối với endpoint Trung Quốc: `baseUrl: "https://api.moonshot.cn/v1"` hoặc `openclaw onboard --auth-choice moonshot-api-key-cn`.
Với endpoint Trung Quốc: `baseUrl: "https://api.moonshot.cn/v1"` hoặc `openclaw onboard --auth-choice moonshot-api-key-cn`.
Các endpoint Moonshot gốc công bố khả năng tương thích mức sử dụng phát trực tuyến trên phương thức vận chuyển `openai-completions` dùng chung, và OpenClaw xác định điều đó dựa trên năng lực của endpoint thay vì chỉ dựa vào id nhà cung cấp tích hợp sẵn.
Các endpoint Moonshot native quảng bá khả năng tương thích cách dùng streaming trên transport `openai-completions` dùng chung, và OpenClaw dựa vào năng lực endpoint thay vì chỉ dựa vào id provider tích hợp sẵn.
</Accordion>
<Accordion title="OpenCode">
@ -646,7 +646,7 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
}
```
Đặt `OPENCODE_API_KEY` (hoặc `OPENCODE_ZEN_API_KEY`). Dùng tham chiếu `opencode/...` cho danh mục Zen hoặc tham chiếu `opencode-go/...` cho danh mục Go. Lối tắt: `openclaw onboard --auth-choice opencode-zen` hoặc `openclaw onboard --auth-choice opencode-go`.
Đặt `OPENCODE_API_KEY` (hoặc `OPENCODE_ZEN_API_KEY`). Dùng các ref `opencode/...` cho danh mục Zen hoặc các ref `opencode-go/...` cho danh mục Go. Lối tắt: `openclaw onboard --auth-choice opencode-zen` hoặc `openclaw onboard --auth-choice opencode-go`.
</Accordion>
<Accordion title="Synthetic (tương thích Anthropic)">
@ -683,7 +683,7 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
}
```
URL cơ sở nên bỏ `/v1` (máy khách Anthropic sẽ thêm phần này). Lối tắt: `openclaw onboard --auth-choice synthetic-api-key`.
URL cơ sở nên bỏ `/v1` (client Anthropic sẽ thêm phần đó). Lối tắt: `openclaw onboard --auth-choice synthetic-api-key`.
</Accordion>
<Accordion title="Z.AI (GLM-4.7)">
@ -700,9 +700,9 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
Đặt `ZAI_API_KEY`. `z.ai/*` và `z-ai/*` được chấp nhận làm bí danh. Lối tắt: `openclaw onboard --auth-choice zai-api-key`.
- Endpoint chung: `https://api.z.ai/api/paas/v4`
- Endpoint tổng quát: `https://api.z.ai/api/paas/v4`
- Endpoint lập trình (mặc định): `https://api.z.ai/api/coding/paas/v4`
- Đối với endpoint chung, hãy định nghĩa một nhà cung cấp tùy chỉnh với phần ghi đè URL cơ sở.
- Với endpoint tổng quát, hãy định nghĩa một provider tùy chỉnh với ghi đè URL cơ sở.
</Accordion>
</AccordionGroup>
@ -711,7 +711,7 @@ Onboarding nhà cung cấp tùy chỉnh tương tác suy luận đầu vào hìn
## Liên quan
- [Cấu hình — agents](/vi/gateway/config-agents)
- [Cấu hình — channels](/vi/gateway/config-channels)
- [Cấu hình — agent](/vi/gateway/config-agents)
- [Cấu hình — kênh](/vi/gateway/config-channels)
- [Tham chiếu cấu hình](/vi/gateway/configuration-reference) — các khóa cấp cao nhất khác
- [Công cụ và plugins](/vi/tools)
- [Công cụ và plugin](/vi/tools)

624
docs/vi/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

82
docs/vi/gateway/diagnostics.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Chuẩn bị báo cáo lỗi hoặc yêu cầu hỗ trợ
- Gỡ lỗi sự cố Gateway bị sập, khởi động lại, áp lực bộ nhớ hoặc tải dữ liệu quá lớn
- Xem xét dữ liệu chẩn đoán nào được ghi lại hoặc được che giấu
- Gỡ lỗi Gateway bị sập, khởi động lại, áp lực bộ nhớ hoặc payload quá lớn
- Xem lại dữ liệu chẩn đoán nào được ghi lại hoặc được ẩn bớt
summary: Tạo các gói chẩn đoán Gateway có thể chia sẻ cho báo cáo lỗi
title: Xuất thông tin chẩn đoán
x-i18n:
generated_at: "2026-05-03T21:31:44Z"
generated_at: "2026-05-05T01:47:00Z"
model: gpt-5.5
provider: openai
source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b
source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382
source_path: gateway/diagnostics.md
workflow: 16
---
OpenClaw có thể tạo một tệp zip chẩn đoán cục bộ cho báo cáo lỗi. Tệp này kết hợp trạng thái Gateway đã được làm sạch, tình trạng, nhật ký, hình dạng cấu hình và các sự kiện ổn định gần đây không chứa payload.
OpenClaw có thể tạo một tệp zip chẩn đoán cục bộ cho báo cáo lỗi. Tệp này kết hợp trạng thái Gateway đã được làm sạch, sức khỏe, nhật ký, hình dạng cấu hình và các sự kiện ổn định gần đây không chứa payload.
Hãy xử lý các gói chẩn đoán như bí mật cho đến khi bạn đã xem xét chúng. Chúng được thiết kế để bỏ qua hoặc biên tập payload và thông tin xác thực, nhưng vẫn tóm tắt nhật ký Gateway cục bộ và trạng thái runtime cấp máy chủ.
Hãy xử lý các gói chẩn đoán như bí mật cho đến khi bạn đã xem xét chúng. Chúng được thiết kế để bỏ qua hoặc biên tập payload và thông tin xác thực, nhưng vẫn tóm tắt nhật ký Gateway cục bộ và trạng thái runtime ở cấp máy chủ.
## Bắt đầu nhanh
@ -24,7 +24,7 @@ Hãy xử lý các gói chẩn đoán như bí mật cho đến khi bạn đã x
openclaw gateway diagnostics export
```
Lệnh này in ra đường dẫn zip đã ghi. Để chọn một đường dẫn:
Lệnh sẽ in đường dẫn tệp zip đã ghi. Để chọn đường dẫn:
```bash
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
@ -38,57 +38,57 @@ openclaw gateway diagnostics export --json
## Lệnh chat
Chủ sở hữu có thể dùng `/diagnostics [note]` trong chat để yêu cầu xuất Gateway cục bộ.
Dùng lệnh này khi lỗi xảy ra trong một cuộc trò chuyện thật và bạn muốn có một báo cáo có thể sao chép-dán cho bộ phận hỗ trợ:
Chủ sở hữu có thể dùng `/diagnostics [note]` trong chat để yêu cầu xuất Gateway cục bộ. Dùng lệnh này khi lỗi xảy ra trong một cuộc trò chuyện thật và bạn muốn một báo cáo có thể sao chép-dán cho bộ phận hỗ trợ:
1. Gửi `/diagnostics` trong cuộc trò chuyện nơi bạn nhận thấy vấn đề. Thêm một ghi chú ngắn nếu hữu ích, ví dụ `/diagnostics bad tool choice`.
2. OpenClaw gửi phần mở đầu chẩn đoán và yêu cầu một phê duyệt exec rõ ràng. Phê duyệt này chạy `openclaw gateway diagnostics export --json`.
Không phê duyệt chẩn đoán thông qua quy tắc cho phép tất cả.
3. Sau khi phê duyệt, OpenClaw trả lời bằng một báo cáo có thể dán, chứa đườ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.
2. OpenClaw gửi phần mở đầu chẩn đoán và yêu cầu một phê duyệt exec rõ ràng. Phê duyệt này chạy `openclaw gateway diagnostics export --json`. Không phê duyệt chẩn đoán qua quy tắc cho phép tất cả.
3. Sau khi phê duyệt, OpenClaw trả lời bằng một báo cáo có thể dán, chứa đườ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 chat nhóm, chủ sở hữu vẫn có thể chạy `/diagnostics`, nhưng OpenClaw không đăng chi tiết chẩn đoán trở lại chat chung. Nó gửi phần mở đầu, lời nhắc phê duyệt, kết quả xuất Gateway và phân tích phiên/luồng Codex cho chủ sở hữu thông qua tuyến phê duyệt riêng tư. Nhóm chỉ nhận được một thông báo ngắn rằng quy trình chẩn đoán đã được gửi riêng. Nếu OpenClaw không tìm thấy tuyến riêng tư đến chủ sở hữu, lệnh sẽ đóng an toàn và yêu cầu chủ sở hữu chạy lệnh từ DM.
Trong chat nhóm, chủ sở hữu vẫn có thể chạy `/diagnostics`, nhưng OpenClaw không đăng chi tiết chẩn đoán trở lại chat chung. Nó gửi phần mở đầu, lời nhắc phê duyệt, kết quả xuất Gateway và phân tích phiên/luồng Codex cho chủ sở hữu qua tuyến phê duyệt riêng tư. Nhóm chỉ nhận được một thông báo ngắn rằng luồng chẩn đoán đã được gửi riêng tư. Nếu OpenClaw không tìm thấy tuyến riêng tư tới chủ sở hữu, lệnh sẽ thất bại đóng và yêu cầu chủ sở hữu chạy lệnh từ DM.
Khi phiên OpenClaw đang hoạt động sử dụng harness OpenAI Codex gốc, cùng phê duyệt exec đó cũng bao gồm một lượt tải phản hồi OpenAI lên cho các luồng runtime Codex mà OpenClaw biết. Lượt tải lên đó tách biệt với tệp zip Gateway cục bộ và chỉ xuất hiện cho các phiên harness Codex. Trước khi phê duyệt, lời nhắc giải thích rằng việc phê duyệt chẩn đoán cũng sẽ gửi phản hồi Codex, nhưng không liệt kê ID phiên hoặc luồng Codex. Sau khi phê duyệt, phản hồi chat liệt kê các kênh, ID phiên OpenClaw, ID luồng Codex và lệnh resume cục bộ cho các luồng đã được gửi đến máy chủ OpenAI. Nếu bạn từ chối hoặc bỏ qua phê duyệt, OpenClaw không chạy xuất, không gửi phản hồi Codex và không in các ID Codex.
Khi phiên OpenClaw đang hoạt động dùng harness OpenAI Codex gốc, cùng phê duyệt exec đó cũng bao gồm việc tải phản hồi OpenAI lên cho các luồng runtime Codex mà OpenClaw biết. Việc tải lên đó tách biệt với tệp zip Gateway cục bộ và chỉ xuất hiện cho các phiên harness Codex. Trước khi phê duyệt, lời nhắc giải thích rằng phê duyệt chẩn đoán cũng sẽ gửi phản hồi Codex, nhưng không liệt kê id phiên hoặc luồng Codex. Sau khi phê duyệt, phản hồi trong chat liệt kê các kênh, id phiên OpenClaw, id luồng Codex và các lệnh tiếp tục cục bộ cho những luồng đã được gửi tới máy chủ OpenAI. Nếu bạn từ chối hoặc bỏ qua phê duyệt, OpenClaw không chạy xuất, không gửi phản hồi Codex và không in các id Codex.
Điều đó làm cho vòng lặp gỡ lỗi Codex phổ biến trở nên ngắn gọn: nhận thấy hành vi sai trong Telegram, Discord hoặc một kênh khác, chạy `/diagnostics`, phê duyệt một lần, chia sẻ báo cáo với bộ phận hỗ trợ, rồi chạy lệnh `codex resume <thread-id>` đã in ở cục bộ nếu bạn muốn tự kiểm tra luồng Codex gốc. Xem [harness Codex](/vi/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) để biết quy trình kiểm tra đó.
Điều đó làm cho vòng lặp gỡ lỗi Codex phổ biến trở nên ngắn gọn: nhận thấy hành vi sai trong Telegram, Discord hoặc kênh khác, chạy `/diagnostics`, phê duyệt một lần, chia sẻ báo cáo với bộ phận hỗ trợ, rồi chạy lệnh `codex resume <thread-id>` đã in ở cục bộ nếu bạn muốn tự kiểm tra luồng Codex gốc. Xem [harness Codex](/vi/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) để biết quy trình kiểm tra đó.
## Nội dung bản xuất
## Nội dung bản xuất chứa
Tệp zip bao gồm:
- `summary.md`: tổng quan dễ đọc cho bộ phận hỗ trợ.
- `diagnostics.json`: tóm tắt đọc được bằng máy về cấu hình, nhật ký, trạng thái, tình trạng và dữ liệu ổn định.
- `summary.md`: tổng quan dễ đọc cho con người dành cho bộ phận hỗ trợ.
- `diagnostics.json`: tóm tắt máy có thể đọc về cấu hình, nhật ký, trạng thái, sức khỏe và dữ liệu ổn định.
- `manifest.json`: siêu dữ liệu xuất và danh sách tệp.
- Hình dạng cấu hình đã được làm sạch và chi tiết cấu hình không bí mật.
- Tóm tắt nhật ký đã được làm sạch và các dòng nhật ký gần đây đã được biên tập.
- Ảnh chụp nhanh trạng thái và tình trạng Gateway theo nỗ lực tốt nhất.
- `stability/latest.json`: gói ổn định mới nhất đã được lưu, khi có.
- Ảnh chụp nhanh trạng thái và sức khỏe Gateway theo nỗ lực tốt nhất.
- `stability/latest.json`: gói ổn định mới nhất đã được lưu, khi có sẵn.
Bản xuất vẫn hữu ích ngay cả khi Gateway không khỏe. Nếu Gateway không thể trả lời yêu cầu trạng thái hoặc tình trạng, nhật ký cục bộ, hình dạng cấu hình và gói ổn định mới nhất vẫn được thu thập khi có.
Bản xuất vẫn hữu ích ngay cả khi Gateway không khỏe. Nếu Gateway không thể trả lời các yêu cầu trạng thái hoặc sức khỏe, nhật ký cục bộ, hình dạng cấu hình và gói ổn định mới nhất vẫn được thu thập khi có sẵn.
## Mô hình quyền riêng tư
Chẩn đoán được thiết kế để có thể chia sẻ. Bản xuất giữ lại dữ liệu vận hành giúp gỡ lỗi, chẳng hạn như:
Chẩn đoán được thiết kế để có thể chia sẻ. Bản xuất giữ dữ liệu vận hành hỗ trợ gỡ lỗi, chẳng hạn như:
- tên phân hệ, ID Plugin, ID nhà cung cấp, ID kênh và các chế độ đã cấu hình
- tên hệ thống con, id plugin, id provider, id kênh và các chế độ đã cấu hình
- mã trạng thái, thời lượng, số byte, trạng thái hàng đợi và chỉ số bộ nhớ
- siêu dữ liệu nhật ký đã được làm sạch và thông điệp vận hành đã được biên tập
- siêu dữ liệu nhật ký đã được làm sạch và thông báo vận hành đã được biên tập
- hình dạng cấu hình và thiết lập tính năng không bí mật
Bản xuất bỏ qua hoặc biên tập:
- văn bản chat, prompt, chỉ dẫn, phần thân Webhook và đầu ra công cụ
- văn bản chat, prompt, chỉ dẫn, thân Webhook và đầu ra công cụ
- thông tin xác thực, khóa API, token, cookie và giá trị bí mật
- phần thân yêu cầu hoặc phản hồi thô
- ID tài khoản, ID tin nhắn, ID phiên thô, tên máy chủ và tên người dùng cục bộ
- thân yêu cầu hoặc phản hồi thô
- id tài khoản, id tin nhắn, id phiên thô, tên máy chủ và tên người dùng cục bộ
Khi một thông điệp nhật ký trông giống văn bản payload của người dùng, chat, prompt hoặc công cụ, bản xuất chỉ giữ lại thông tin rằng một thông điệp đã bị bỏ qua và số byte.
Khi một thông báo nhật ký trông giống văn bản người dùng, chat, prompt hoặc payload công cụ, bản xuất chỉ giữ lại rằng một thông báo đã bị bỏ qua và số byte.
## Bộ ghi ổn định
Gateway mặc định ghi lại một luồng ổn định có giới hạn, không chứa payload khi chẩn đoán được bật. Luồng này dành cho các sự kiện vận hành, không dành cho nội dung.
Gateway ghi một luồng ổn định có giới hạn, không chứa payload theo mặc định khi chẩn đoán được bật. Luồng này dành cho các sự kiện vận hành, không phải nội dung.
Cùng Heartbeat chẩn đoán đó ghi lại mẫu liveness khi Gateway vẫn tiếp tục chạy nhưng vòng lặp sự kiện Node.js hoặc CPU có vẻ bị bão hòa. Các sự kiện `diagnostic.liveness.warning` này bao gồm độ trễ vòng lặp sự kiện, mức sử dụng vòng lặp sự kiện, tỷ lệ lõi CPU và số lượng phiên đang hoạt động/đang chờ/đã xếp hàng. Các mẫu nhàn rỗi ở lại trong telemetry ở mức `info`. Mẫu liveness chỉ trở thành cảnh báo Gateway khi có công việc đang chờ hoặc đã xếp hàng, hoặc khi công việc đang hoạt động trùng với độ trễ vòng lặp sự kiện kéo dài. Các đột biến độ trễ tối đa thoáng qua trong lúc công việc nền vẫn khỏe mạnh sẽ ở lại trong nhật ký debug. Chúng không tự khởi động lại Gateway.
Cùng Heartbeat chẩn đoán đó ghi các mẫu liveness khi Gateway tiếp tục chạy nhưng vòng lặp sự kiện Node.js hoặc CPU có vẻ bão hòa. Các sự kiện `diagnostic.liveness.warning` này bao gồm độ trễ vòng lặp sự kiện, mức sử dụng vòng lặp sự kiện, tỷ lệ lõi CPU, số phiên đang hoạt động/đang chờ/đang xếp hàng, giai đoạn khởi động/runtime hiện tại khi biết, các khoảng giai đoạn gần đây và nhãn công việc đang hoạt động/đang xếp hàng có giới hạn. Các mẫu rảnh vẫn ở trong telemetry ở cấp `info`. Các mẫu liveness chỉ trở thành cảnh báo Gateway khi có công việc đang chờ hoặc đang xếp hàng, hoặc khi công việc đang hoạt động trùng với độ trễ vòng lặp sự kiện kéo dài. Các đột biến độ trễ tối đa thoáng qua trong lúc công việc nền vẫn khỏe mạnh sẽ ở trong nhật ký gỡ lỗi. Chúng không tự khởi động lại Gateway.
Các giai đoạn khởi động cũng phát sự kiện `diagnostic.phase.completed` với thời gian đồng hồ và thời gian CPU. Chẩn đoán embedded-run bị kẹt đánh dấu `terminalProgressStale=true` khi tiến trình bridge cuối cùng trông như đã kết thúc, chẳng hạn một mục phản hồi thô hoặc sự kiện hoàn tất phản hồi, nhưng Gateway vẫn xem lần chạy nhúng là đang hoạt động.
Kiểm tra bộ ghi trực tiếp:
@ -98,19 +98,19 @@ openclaw gateway stability --type payload.large
openclaw gateway stability --json
```
Kiểm tra gói ổn định mới nhất đã được lưu sau một lần thoát nghiêm trọng, timeout khi tắt hoặc lỗi khởi động sau restart:
Kiểm tra gói ổn định mới nhất đã được lưu sau khi thoát nghiêm trọng, hết thời gian chờ tắt hoặc lỗi khởi động lại:
```bash
openclaw gateway stability --bundle latest
```
Tạo tệp zip chẩn đoán từ gói đã lưu mới nhất:
Tạo tệp zip chẩn đoán từ gói mới nhất đã được lưu:
```bash
openclaw gateway stability --bundle latest --export
```
Các gói đã lưu nằm dưới `~/.openclaw/logs/stability/` khi có sự kiện.
Các gói đã lưu nằm trong `~/.openclaw/logs/stability/` khi có sự kiện.
## Tùy chọn hữu ích
@ -122,14 +122,14 @@ openclaw gateway diagnostics export \
```
- `--output <path>`: ghi vào một đường dẫn zip cụ thể.
- `--log-lines <count>`: số dòng nhật ký đã làm sạch tối đa cần đưa vào.
- `--log-lines <count>`: số dòng nhật ký đã được làm sạch tối đa cần đưa vào.
- `--log-bytes <bytes>`: số byte nhật ký tối đa cần kiểm tra.
- `--url <url>`: URL WebSocket Gateway cho ảnh chụp nhanh trạng thái và tình trạng.
- `--token <token>`: token Gateway cho ảnh chụp nhanh trạng thái và tình trạng.
- `--password <password>`: mật khẩu Gateway cho ảnh chụp nhanh trạng thái và tình trạng.
- `--timeout <ms>`: timeout ảnh chụp nhanh trạng thái và tình trạng.
- `--url <url>`: URL WebSocket Gateway cho ảnh chụp nhanh trạng thái và sức khỏe.
- `--token <token>`: token Gateway cho ảnh chụp nhanh trạng thái và sức khỏe.
- `--password <password>`: mật khẩu Gateway cho ảnh chụp nhanh trạng thái và sức khỏe.
- `--timeout <ms>`: thời gian chờ ảnh chụp nhanh trạng thái và sức khỏe.
- `--no-stability-bundle`: bỏ qua tra cứu gói ổn định đã lưu.
- `--json`: in siêu dữ liệu xuất đọc được bằng máy.
- `--json`: in siêu dữ liệu xuất máy có thể đọc.
## Tắt chẩn đoán
@ -147,8 +147,8 @@ Tắt chẩn đoán làm giảm chi tiết báo cáo lỗi. Việc này không
## Liên quan
- [Kiểm tra tình trạng](/vi/gateway/health)
- [Kiểm tra sức khỏe](/vi/gateway/health)
- [CLI Gateway](/vi/cli/gateway#gateway-diagnostics-export)
- [Giao thức Gateway](/vi/gateway/protocol#system-and-identity)
- [Ghi nhật ký](/vi/logging)
- [Xuất OpenTelemetry](/vi/gateway/opentelemetry) — quy trình riêng để truyền trực tuyến chẩn đoán đến một bộ thu
- [Xuất OpenTelemetry](/vi/gateway/opentelemetry) — luồng riêng để truyền chẩn đoán tới collector

366
docs/vi/gateway/doctor.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Thêm hoặc sửa đổi các chuyển đổi của doctor
- Đưa vào các thay đổi cấu hình phá vỡ tương thích
- Giới thiệu các thay đổi cấu hình phá vỡ tương thích
sidebarTitle: Doctor
summary: 'Lệnh doctor: kiểm tra tình trạng, di chuyển cấu hình và các bước sửa chữa'
title: Trình chẩn đoán
summary: 'Lệnh doctor: kiểm tra tình trạng, chuyển đổi cấu hình và các bước sửa chữa'
title: Chẩn đoán
x-i18n:
generated_at: "2026-05-04T09:37:05Z"
generated_at: "2026-05-05T01:47:06Z"
model: gpt-5.5
provider: openai
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` là công cụ sửa chữa + di trú cho OpenClaw. Công cụ này sửa cấu hình/trạng thái cũ, kiểm tra tình trạng, và cung cấp các bước sửa chữa có thể thực hiện.
`openclaw doctor` là công cụ sửa chữa + di trú cho OpenClaw. Công cụ này sửa cấu hình/trạng thái cũ, kiểm tra tình trạng hoạt động và cung cấp các bước sửa chữa có thể thực hiện.
## Bắt đầu nhanh
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Chấp nhận mặc định mà không hỏi (bao gồm các bước sửa chữa khởi động lại/dịch vụ/sandbox khi áp dụng).
Chấp nhận mặc định mà không nhắc hỏi (bao gồm các bước sửa chữa khởi động lại/dịch vụ/sandbox khi áp dụng).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Áp dụng các sửa chữa được khuyến nghị mà không hỏi (sửa chữa + khởi động lại ở nơi an toàn).
Áp dụng các sửa chữa được khuyến nghị mà không nhắc hỏi (sửa chữa + khởi động lại khi an toàn).
</Tab>
<Tab title="--repair --force">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Chạy không có lời nhắc và chỉ áp dụng các di trú an toàn (chuẩn hóa cấu hình + di chuyển trạng thái trên đĩa). Bỏ qua các hành động khởi động lại/dịch vụ/sandbox cần xác nhận của người dùng. Các di trú trạng thái cũ tự động chạy khi được phát hiện.
Chạy không có lời nhắc và chỉ áp dụng các di trú an toàn (chuẩn hóa cấu hình + di chuyển trạng thái trên đĩa). Bỏ qua các hành động khởi động lại/dịch vụ/sandbox cần xác nhận của con người. Các di trú trạng thái cũ sẽ tự động chạy khi được phát hiện.
</Tab>
<Tab title="--deep">
@ -62,25 +62,25 @@ openclaw doctor
openclaw doctor --deep
```
Quét các dịch vụ hệ thống để tìm thêm các bản cài đặt gateway (launchd/systemd/schtasks).
Quét các dịch vụ hệ thống để tìm các bản cài đặt Gateway bổ sung (launchd/systemd/schtasks).
</Tab>
</Tabs>
Nếu bạn muốn xem lại thay đổi trước khi ghi, hãy mở tệp cấu hình trước:
Nếu bạn muốn xem lại các thay đổi trước khi ghi, hãy mở tệp cấu hình trước:
```bash
cat ~/.openclaw/openclaw.json
```
## Công cụ này làm gì (tóm tắt)
## Chức năng (tóm tắt)
<AccordionGroup>
<Accordion title="Tình trạng, UI và cập nhật">
- Cập nhật trước khi chạy tùy chọn cho các bản cài đặt git (chỉ tương tác).
<Accordion title="Sức khỏe, UI và cập nhật">
- Cập nhật trước khi chạy tùy chọn cho các bản cài đặt git (chỉ khi tương tác).
- Kiểm tra độ mới của giao thức UI (xây dựng lại Control UI khi schema giao thức mới hơn).
- Kiểm tra tình trạng + lời nhắc khởi động lại.
- Tóm tắt trạng thái Skills (đủ điều kiện/thiếu/bị chặn) và trạng thái Plugin.
- Kiểm tra sức khỏe + lời nhắc khởi động lại.
- Tóm tắt trạng thái Skills (đủ điều kiện/thiếu/bị chặn) và trạng thái plugin.
</Accordion>
<Accordion title="Cấu hình và di trú">
@ -90,104 +90,107 @@ cat ~/.openclaw/openclaw.json
- Cảnh báo ghi đè provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Cảnh báo che khuất OAuth Codex (`models.providers.openai-codex`).
- Kiểm tra điều kiện tiên quyết TLS OAuth cho hồ sơ OAuth OpenAI Codex.
- Cảnh báo danh sách cho phép Plugin/công cụ khi `plugins.allow` bị giới hạn nhưng chính sách công cụ vẫn yêu cầu ký tự đại diện hoặc công cụ thuộc sở hữu Plugin.
- Cảnh báo danh sách cho phép plugin/công cụ khi `plugins.allow` bị giới hạn nhưng chính sách công cụ vẫn yêu cầu wildcard hoặc công cụ do plugin sở hữu.
- Di trú trạng thái cũ trên đĩa (sessions/thư mục agent/xác thực WhatsApp).
- Di trú khóa hợp đồng manifest Plugin cũ (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Di trú kho cron cũ (`jobId`, `schedule.cron`, các trường delivery/payload cấp cao nhất, payload `provider`, các job dự phòng webhook `notify: true` đơn giản).
- Di trú khóa hợp đồng manifest plugin cũ (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Di trú kho Cron cũ (`jobId`, `schedule.cron`, các trường delivery/payload cấp cao nhất, payload `provider`, các job dự phòng webhook `notify: true` đơn giản).
- Di trú chính sách runtime agent cũ sang `agents.defaults.agentRuntime` và `agents.list[].agentRuntime`.
- Dọn dẹp cấu hình Plugin cũ khi Plugin được bật; khi `plugins.enabled=false`, các tham chiếu Plugin cũ được xem là cấu hình cô lập không hoạt động và được giữ nguyên.
- Dọn dẹp cấu hình plugin lỗi thời khi plugin được bật; khi `plugins.enabled=false`, các tham chiếu plugin lỗi thời được xem là cấu hình khoanh vùng bất hoạt và được giữ nguyên.
</Accordion>
<Accordion title="Trạng thái và tính toàn vẹn">
- Kiểm tra tệp khóa phiên và dọn dẹp khóa cũ.
- Kiểm tra tệp khóa phiên và dọn dẹp khóa lỗi thời.
- Sửa chữa bản ghi phiên cho các nhánh viết lại prompt bị trùng lặp do các bản dựng 2026.4.24 bị ảnh hưởng tạo ra.
- Phát hiện tombstone phục hồi-khởi động lại của subagent bị kẹt, có hỗ trợ `--fix` để xóa cờ phục hồi bị hủy đã cũ để lúc khởi động không tiếp tục xem child là đã bị hủy khởi động lại.
- Phát hiện tombstone phục hồi khởi động lại subagent bị kẹt, có hỗ trợ `--fix` để xóa cờ phục hồi đã hủy lỗi thời để quá trình khởi động không tiếp tục xem tiến trình con là đã bị hủy khởi động lại.
- Kiểm tra tính toàn vẹn trạng thái và quyền (sessions, transcripts, thư mục trạng thái).
- Kiểm tra quyền tệp cấu hình (chmod 600) khi chạy cục bộ.
- Tình trạng xác thực mô hình: kiểm tra OAuth hết hạn, có thể làm mới token sắp hết hạn, và báo cáo trạng thái cooldown/bị vô hiệu hóa của hồ sơ xác thực.
- Phát hiện thư mục workspace thừa (`~/openclaw`).
- Sức khỏe xác thực mô hình: kiểm tra hết hạn OAuth, có thể làm mới token sắp hết hạn và báo cáo trạng thái cooldown/bị tắt của auth-profile.
- Phát hiện thư mục workspace bổ sung (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, dịch vụ và supervisor">
- Sửa chữa image sandbox khi sandboxing được bật.
- Di trú dịch vụ cũ và phát hiện gateway thừa.
- Di trú dịch vụ cũ và phát hiện Gateway bổ sung.
- Di trú trạng thái cũ của kênh Matrix (ở chế độ `--fix` / `--repair`).
- Kiểm tra runtime Gateway (dịch vụ đã cài nhưng không chạy; nhãn launchd được lưu cache).
- Cảnh báo trạng thái kênh (được thăm dò từ gateway đang chạy).
- Cảnh báo trạng thái kênh (được dò từ Gateway đang chạy).
- Kiểm tra cấu hình supervisor (launchd/systemd/schtasks) với sửa chữa tùy chọn.
- Dọn dẹp môi trường proxy nhúng cho các dịch vụ gateway đã thu thập giá trị shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` trong quá trình cài đặt hoặc cập nhật.
- Dọn dẹp môi trường proxy nhúng cho các dịch vụ Gateway đã thu thập giá trị shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` trong lúc cài đặt hoặc cập nhật.
- Kiểm tra thực hành tốt nhất cho runtime Gateway (Node so với Bun, đường dẫn trình quản lý phiên bản).
- Chẩn đoán xung đột cổng Gateway (mặc định `18789`).
</Accordion>
<Accordion title="Xác thực, bảo mật và ghép nối">
<Accordion title="Xác thực, bảo mật và ghép đôi">
- Cảnh báo bảo mật cho chính sách DM mở.
- Kiểm tra xác thực Gateway cho chế độ token cục bộ (đề xuất tạo token khi không có nguồn token; không ghi đè cấu hình token SecretRef).
- Phát hiện sự cố ghép nối thiết bị (yêu cầu ghép nối lần đầu đang chờ, nâng cấp vai trò/phạm vi đang chờ, lệch cache token thiết bị cục bộ đã cũ, và lệch xác thực bản ghi đã ghép nối).
- Phát hiện sự cố ghép đôi thiết bị (yêu cầu ghép đôi lần đầu đang chờ, nâng cấp vai trò/phạm vi đang chờ, sai lệch cache device-token cục bộ lỗi thời và sai lệch xác thực bản ghi đã ghép đôi).
</Accordion>
<Accordion title="Workspace và shell">
- Kiểm tra systemd linger trên Linux.
- Kiểm tra kích thước tệp bootstrap workspace (cảnh báo bị cắt/gần giới hạn cho tệp ngữ cảnh).
- Kiểm tra mức sẵn sàng Skills cho agent mặc định; báo cáo các skill được phép nhưng thiếu bin, env, config hoặc yêu cầu OS, và `--fix` có thể vô hiệu hóa các skill không khả dụng trong `skills.entries`.
- Kiểm tra trạng thái hoàn thành shell và tự động cài đặt/nâng cấp.
- Kiểm tra kích thước tệp bootstrap workspace (cảnh báo bị cắt/gần giới hạn cho các tệp ngữ cảnh).
- Kiểm tra mức sẵn sàng Skills cho agent mặc định; báo cáo các skill được phép nhưng thiếu binary, env, cấu hình hoặc yêu cầu OS, và `--fix` có thể tắt các skill không khả dụng trong `skills.entries`.
- Kiểm tra trạng thái shell completion và tự động cài đặt/nâng cấp.
- Kiểm tra mức sẵn sàng provider embedding tìm kiếm bộ nhớ (mô hình cục bộ, khóa API từ xa hoặc binary QMD).
- Kiểm tra bản cài đặt từ mã nguồn (pnpm workspace không khớp, thiếu asset UI, thiếu binary tsx).
- Kiểm tra cài đặt từ nguồn (pnpm workspace không khớp, thiếu tài nguyên UI, thiếu binary tsx).
- Ghi cấu hình đã cập nhật + metadata wizard.
</Accordion>
</AccordionGroup>
## Điền ngược và đặt lại Dreams UI
## Điền bù và đặt lại UI Dreams
Cảnh Dreams trong Control UI bao gồm các hành động **Backfill**, **Reset** và **Clear Grounded** cho quy trình grounded dreaming. Các hành động này dùng phương thức RPC kiểu gateway doctor, nhưng chúng **không** phải là một phần của sửa chữa/di trú CLI `openclaw doctor`.
Cảnh Dreams của Control UI bao gồm các hành động **Backfill**, **Reset** và **Clear Grounded** cho quy trình grounded dreaming. Các hành động này dùng các phương thức RPC kiểu gateway doctor, nhưng chúng **không** phải là một phần của sửa chữa/di trú CLI `openclaw doctor`.
Các hành động này làm gì:
Những việc chúng làm:
- **Backfill** quét các tệp `memory/YYYY-MM-DD.md` lịch sử trong workspace đang hoạt động, chạy lượt nhật ký REM grounded, và ghi các mục điền ngược có thể đảo ngược vào `DREAMS.md`.
- **Reset** chỉ xóa các mục nhật ký điền ngược đã được đánh dấu đó khỏi `DREAMS.md`.
- **Clear Grounded** chỉ xóa các mục ngắn hạn chỉ-grounded đã được staging đến từ phát lại lịch sử và chưa tích lũy recall trực tiếp hoặc hỗ trợ hằng ngày.
- **Backfill** quét các tệp `memory/YYYY-MM-DD.md` lịch sử trong workspace đang hoạt động, chạy lượt nhật ký REM grounded và ghi các mục điền bù có thể hoàn tác vào `DREAMS.md`.
- **Reset** chỉ xóa các mục nhật ký điền bù đã được đánh dấu đó khỏi `DREAMS.md`.
- **Clear Grounded** chỉ xóa các mục ngắn hạn chỉ-grounded đã được đưa vào hàng chờ đến từ phát lại lịch sử và chưa tích lũy recall trực tiếp hoặc hỗ trợ hằng ngày.
Bản thân các hành động này **không** làm gì:
Những việc chúng **không** tự làm:
- chúng không chỉnh sửa `MEMORY.md`
- chúng không chạy toàn bộ di trú doctor
- chúng không tự động staging các ứng viên grounded vào kho thăng cấp ngắn hạn trực tiếp trừ khi bạn chạy rõ ràng đường dẫn CLI đã staging trước
- chúng không tự động đưa các ứng viên grounded vào kho promotion ngắn hạn trực tiếp trừ khi bạn chạy rõ ràng đường dẫn CLI đã đưa vào hàng chờ trước
Nếu bạn muốn phát lại lịch sử grounded ảnh hưởng đến lane thăng cấp sâu thông thường, hãy dùng luồng CLI thay thế:
Nếu bạn muốn phát lại lịch sử grounded ảnh hưởng đến làn promotion sâu thông thường, hãy dùng luồng CLI thay thế:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Lệnh đó staging các ứng viên bền vững grounded vào kho Dreaming ngắn hạn trong khi vẫn giữ `DREAMS.md` làm bề mặt xem xét.
Lệnh đó đưa các ứng viên durable grounded vào kho dreaming ngắn hạn trong khi vẫn giữ `DREAMS.md` làm bề mặt xem xét.
## Hành vi chi tiết và lý do
<AccordionGroup>
<Accordion title="0. Cập nhật tùy chọn (bản cài đặt git)">
Nếu đây là checkout git và doctor đang chạy tương tác, công cụ sẽ đề xuất cập nhật (fetch/rebase/build) trước khi chạy doctor.
Nếu đây là một git checkout và doctor đang chạy tương tác, công cụ sẽ đề xuất cập nhật (fetch/rebase/build) trước khi chạy doctor.
</Accordion>
<Accordion title="1. Chuẩn hóa cấu hình">
Nếu cấu hình chứa các dạng giá trị cũ (ví dụ `messages.ackReaction` không có ghi đè riêng theo kênh), doctor chuẩn hóa chúng vào schema hiện tại.
Nếu cấu hình chứa các dạng giá trị cũ (ví dụ `messages.ackReaction` không có ghi đè riêng theo kênh), doctor sẽ chuẩn hóa chúng vào schema hiện tại.
Điều đó bao gồm các trường phẳng Talk cũ. Cấu hình Talk công khai hiện tại là `talk.provider` + `talk.providers.<provider>`. Doctor viết lại các dạng `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` cũ vào map provider.
Điều đó bao gồm các trường phẳng Talk cũ. Cấu hình Talk công khai hiện tại là `talk.provider` + `talk.providers.<provider>`. Doctor viết lại các dạng `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` cũ vào bản đồ provider.
Doctor cũng cảnh báo khi `plugins.allow` không rỗng và chính sách công cụ dùng
ký tự đại diện hoặc các mục công cụ thuộc sở hữu Plugin. `tools.allow: ["*"]` chỉ khớp các công cụ
từ Plugin thật sự được tải; nó không bỏ qua danh sách cho phép Plugin độc quyền.
các mục công cụ wildcard hoặc do plugin sở hữu. `tools.allow: ["*"]` chỉ khớp các công cụ
từ những plugin thật sự được tải; nó không bỏ qua danh sách cho phép plugin độc quyền.
Doctor ghi `plugins.bundledDiscovery: "compat"` cho các cấu hình danh sách cho phép cũ đã di trú
để giữ nguyên hành vi provider đi kèm hiện có, rồi
trỏ tới thiết lập `"allowlist"` nghiêm ngặt hơn.
</Accordion>
<Accordion title="2. Di trú khóa cấu hình cũ">
Khi cấu hình chứa các khóa không còn dùng, các lệnh khác sẽ từ chối chạy và yêu cầu bạn chạy `openclaw doctor`.
Khi cấu hình chứa các khóa đã ngừng dùng, các lệnh khác sẽ từ chối chạy và yêu cầu bạn chạy `openclaw doctor`.
Doctor sẽ:
- Giải thích những khóa cũ nào được tìm thấy.
- Giải thích những khóa cũ nào đã được tìm thấy.
- Hiển thị di trú đã áp dụng.
- Viết lại `~/.openclaw/openclaw.json` bằng schema đã cập nhật.
- Ghi lại `~/.openclaw/openclaw.json` với schema đã cập nhật.
Gateway cũng tự động chạy di trú doctor khi khởi động nếu phát hiện định dạng cấu hình cũ, vì vậy cấu hình lỗi thời được sửa mà không cần can thiệp thủ công. Di trú kho job Cron được xử lý bởi `openclaw doctor --fix`.
Gateway cũng tự động chạy các di trú doctor khi khởi động nếu phát hiện định dạng cấu hình cũ, vì vậy các cấu hình lỗi thời được sửa chữa mà không cần can thiệp thủ công. Di trú kho job Cron được xử lý bởi `openclaw doctor --fix`.
Các di trú hiện tại:
@ -195,7 +198,8 @@ Lệnh đó staging các ứng viên bền vững grounded vào kho Dreaming ng
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- cấu hình kênh đã cấu hình thiếu chính sách trả lời hiển thị → `messages.groupChat.visibleReplies: "message_tool"`
- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
- cấu hình configured-channel thiếu chính sách phản hồi hiển thị → `messages.groupChat.visibleReplies: "message_tool"`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` cấp cao nhất
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
@ -213,70 +217,76 @@ Lệnh đó staging các ứng viên bền vững grounded vào kho Dreaming ng
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Với các kênh có `accounts` được đặt tên nhưng vẫn còn các giá trị kênh cấp cao nhất cho một tài khoản đơn, hãy di chuyển các giá trị thuộc phạm vi tài khoản đó vào tài khoản được nâng cấp đã chọn cho kênh đó (`accounts.default` cho hầu hết các kênh; Matrix có thể giữ nguyên một đích được đặt tên/mặc định hiện có khớp)
- Với các kênh có `accounts` được đặt tên nhưng vẫn còn các giá trị kênh cấp cao nhất cho tài khoản đơn lẻ, hãy chuyển các giá trị theo phạm vi tài khoản đó vào tài khoản được nâng cấp đã chọn cho kênh đó (`accounts.default` cho hầu hết các kênh; Matrix có thể giữ một đích được đặt tên/mặc định hiện có nếu khớp)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- xóa `agents.defaults.llm`; dùng `models.providers.<id>.timeoutSeconds` cho thời gian chờ provider/model chậm
- xóa `agents.defaults.llm`; dùng `models.providers.<id>.timeoutSeconds` cho thời gian chờ nhà cung cấp/mô hình chậm
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- xóa `browser.relayBindHost` (thiết lập chuyển tiếp extension cũ)
- `models.providers.*.api: "openai"` cũ → `"openai-completions"` (Gateway khi khởi động cũng bỏ qua các provider có `api` được đặt thành giá trị enum trong tương lai hoặc không xác định thay vì đóng lỗi)
- xóa `browser.relayBindHost` (thiết lập relay extension cũ)
- `models.providers.*.api: "openai"` cũ → `"openai-completions"` (Gateway khi khởi động cũng bỏ qua các nhà cung cấp có `api` được đặt thành giá trị enum tương lai hoặc không xác định thay vì thất bại đóng)
Cảnh báo của doctor cũng bao gồm hướng dẫn tài khoản mặc định cho các kênh đa tài khoản:
Cảnh báo của doctor cũng bao gồm hướng dẫn mặc định tài khoản cho các kênh nhiều tài khoản:
- Nếu hai mục `channels.<channel>.accounts` trở lên được cấu hình mà không có `channels.<channel>.defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản không mong muốn.
- Nếu `channels.<channel>.defaultAccount` được đặt thành ID tài khoản không xác định, doctor cảnh báo và liệt kê các ID tài khoản đã cấu hình.
- Nếu có từ hai mục `channels.<channel>.accounts` trở lên được cấu hình mà không có `channels.<channel>.defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản không mong muốn.
- Nếu `channels.<channel>.defaultAccount` được đặt thành một ID tài khoản không xác định, doctor cảnh báo và liệt kê các ID tài khoản đã cấu hình.
</Accordion>
<Accordion title="2b. Ghi đè provider OpenCode">
Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, nó sẽ ghi đè catalog OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể ép các model dùng sai API hoặc đưa chi phí về 0. Doctor cảnh báo để bạn có thể xóa phần ghi đè và khôi phục định tuyến API + chi phí theo từng model.
<Accordion title="2b. Ghi đè nhà cung cấp OpenCode">
Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, cấu hình đó sẽ ghi đè danh mục OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể buộc mô hình dùng sai API hoặc đưa chi phí về 0. Doctor cảnh báo để bạn có thể xóa ghi đè và khôi phục định tuyến API + chi phí theo từng mô hình.
</Accordion>
<Accordion title="2c. Di chuyển trình duyệt và trạng thái sẵn sàng của Chrome MCP">
Nếu cấu hình trình duyệt của bạn vẫn trỏ tới đường dẫn Chrome extension đã bị xóa, doctor sẽ chuẩn hóa nó sang mô hình gắn Chrome MCP host-local hiện tại:
<Accordion title="2c. Di chuyển trình duyệt và trạng thái sẵn sàng Chrome MCP">
Nếu cấu hình trình duyệt của bạn vẫn trỏ tới đường dẫn extension Chrome đã bị xóa, doctor chuẩn hóa nó sang mô hình gắn Chrome MCP cục bộ trên host hiện tại:
- `browser.profiles.*.driver: "extension"` trở thành `"existing-session"`
- `browser.relayBindHost` bị xóa
Doctor cũng kiểm tra đường dẫn Chrome MCP host-local khi bạn dùng `defaultProfile: "user"` hoặc một hồ sơ `existing-session` đã cấu hình:
Doctor cũng kiểm tra đường dẫn Chrome MCP cục bộ trên host khi bạn dùng `defaultProfile: "user"` hoặc một hồ sơ `existing-session` đã cấu hình:
- kiểm tra Google Chrome có được cài trên cùng host cho các hồ sơ tự động kết nối mặc định hay không
- kiểm tra phiên bản Chrome phát hiện được và cảnh báo khi thấp hơn Chrome 144
- nhắc bạn bật gỡ lỗi từ xa trong trang kiểm tra của trình duyệt (ví dụ `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, hoặc `edge://inspect/#remote-debugging`)
- kiểm tra phiên bản Chrome được phát hiện và cảnh báo khi phiên bản thấp hơn Chrome 144
- nhắc bạn bật gỡ lỗi từ xa trong trang inspect của trình duyệt (ví dụ `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, hoặc `edge://inspect/#remote-debugging`)
Doctor không thể bật thiết lập phía Chrome cho bạn. Chrome MCP host-local vẫn yêu cầu:
Doctor không thể bật thiết lập phía Chrome thay bạn. Chrome MCP cục bộ trên host vẫn yêu cầu:
- trình duyệt dựa trên Chromium phiên bản 144+ trên host gateway/node
- một trình duyệt dựa trên Chromium 144+ trên host gateway/node
- trình duyệt đang chạy cục bộ
- gỡ lỗi từ xa được bật trong trình duyệt đó
- chấp thuận lời nhắc đồng ý gắn lần đầu trong trình duyệt
- phê duyệt lời nhắc đồng ý gắn lần đầu trong trình duyệt
Trạng thái sẵn sàng ở đây chỉ liên quan đến điều kiện tiên quyết để gắn cục bộ. Existing-session giữ các giới hạn tuyến Chrome MCP hiện tại; các tuyến nâng cao như `responsebody`, xuất PDF, chặn tải xuống và hành động hàng loạt vẫn yêu cầu trình duyệt được quản lý hoặc hồ sơ CDP thô.
Trạng thái sẵn sàng ở đây chỉ liên quan đến các điều kiện tiên quyết để gắn cục bộ. Existing-session giữ các giới hạn tuyến Chrome MCP hiện tại; các tuyến nâng cao như `responsebody`, xuất PDF, chặn tải xuống, và hành động theo lô vẫn yêu cầu trình duyệt được quản lý hoặc hồ sơ CDP thô.
Kiểm tra này **không** áp dụng cho Docker, sandbox, remote-browser hoặc các luồng headless khác. Các luồng đó tiếp tục dùng CDP thô.
Kiểm tra này **không** áp dụng cho Docker, sandbox, remote-browser, hoặc các luồng headless khác. Những luồng đó tiếp tục dùng CDP thô.
</Accordion>
<Accordion title="2d. Điều kiện tiên quyết OAuth TLS">
Khi một hồ sơ OpenAI Codex OAuth được cấu hình, doctor thăm dò endpoint ủy quyền OpenAI để xác minh rằng ngăn xếp TLS Node/OpenSSL cục bộ có thể xác thực chuỗi chứng chỉ. Nếu thăm dò thất bại với lỗi chứng chỉ (ví dụ `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, chứng chỉ hết hạn hoặc chứng chỉ tự ký), doctor in hướng dẫn sửa theo từng nền tảng. Trên macOS với Homebrew Node, cách sửa thường là `brew postinstall ca-certificates`. Với `--deep`, thăm dò sẽ chạy ngay cả khi gateway khỏe mạnh.
Khi một hồ sơ OpenAI Codex OAuth được cấu hình, doctor thăm dò điểm cuối ủy quyền OpenAI để xác minh rằng ngăn xếp TLS Node/OpenSSL cục bộ có thể xác thực chuỗi chứng chỉ. Nếu thăm dò thất bại với lỗi chứng chỉ (ví dụ `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, chứng chỉ hết hạn, hoặc chứng chỉ tự ký), doctor in hướng dẫn khắc phục theo từng nền tảng. Trên macOS với Node từ Homebrew, cách khắc phục thường là `brew postinstall ca-certificates`. Với `--deep`, thăm dò chạy ngay cả khi gateway khỏe mạnh.
</Accordion>
<Accordion title="2e. Ghi đè provider Codex OAuth">
Nếu trước đây bạn đã thêm các thiết lập truyền tải OpenAI cũ dưới `models.providers.openai-codex`, chúng có thể che khuất đường dẫn provider Codex OAuth tích hợp mà các bản phát hành mới hơn tự động sử dụng. Doctor cảnh báo khi thấy các thiết lập truyền tải cũ đó cùng với Codex OAuth để bạn có thể xóa hoặc viết lại phần ghi đè truyền tải lỗi thời và lấy lại hành vi định tuyến/dự phòng tích hợp. Proxy tùy chỉnh và ghi đè chỉ-header vẫn được hỗ trợ và không kích hoạt cảnh báo này.
<Accordion title="2e. Ghi đè nhà cung cấp Codex OAuth">
Nếu trước đây bạn đã thêm thiết lập truyền tải OpenAI cũ dưới `models.providers.openai-codex`, chúng có thể che khuất đường dẫn nhà cung cấp Codex OAuth tích hợp mà các bản phát hành mới hơn dùng tự động. Doctor cảnh báo khi thấy các thiết lập truyền tải cũ đó đi cùng Codex OAuth để bạn có thể xóa hoặc viết lại ghi đè truyền tải lỗi thời và lấy lại hành vi định tuyến/dự phòng tích hợp. Proxy tùy chỉnh và ghi đè chỉ header vẫn được hỗ trợ và không kích hoạt cảnh báo này.
</Accordion>
<Accordion title="2f. Cảnh báo tuyến Plugin Codex">
Khi Plugin Codex đi kèm được bật, doctor cũng kiểm tra liệu các tham chiếu model chính `openai-codex/*` có còn phân giải qua trình chạy PI mặc định hay không. Tổ hợp đó hợp lệ khi bạn muốn xác thực Codex OAuth/đăng ký qua PI, nhưng rất dễ nhầm với bộ chạy app-server Codex gốc. Doctor cảnh báo và trỏ tới dạng app-server rõ ràng: `openai/*` cộng với `agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex`.
Khi Plugin Codex đi kèm được bật, doctor cũng kiểm tra liệu các tham chiếu mô hình chính `openai-codex/*` vẫn phân giải qua trình chạy PI mặc định hay không. Tổ hợp đó hợp lệ khi bạn muốn xác thực Codex OAuth/gói đăng ký thông qua PI, nhưng dễ bị nhầm với harness app-server Codex gốc. Doctor cảnh báo và trỏ tới dạng app-server rõ ràng: `openai/*` cộng với `agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex`.
Doctor không tự động sửa lỗi này vì cả hai tuyến đều hợp lệ:
Doctor không tự động sửa điều này vì cả hai tuyến đều hợp lệ:
- `openai-codex/*` + PI nghĩa là "dùng xác thực Codex OAuth/đăng ký qua trình chạy OpenClaw thông thường."
- `openai/*` + `agentRuntime.id: "codex"` nghĩa là "chạy lượt nhúng qua app-server Codex gốc."
- `openai-codex/*` + PI nghĩa là "dùng xác thực Codex OAuth/gói đăng ký thông qua trình chạy OpenClaw thông thường."
- `openai/*` + `agentRuntime.id: "codex"` nghĩa là "chạy lượt nhúng thông qua app-server Codex gốc."
- `/codex ...` nghĩa là "điều khiển hoặc liên kết một cuộc trò chuyện Codex gốc từ chat."
- `/acp ...` hoặc `runtime: "acp"` nghĩa là "dùng bộ điều hợp ACP/acpx bên ngoài."
Nếu cảnh báo xuất hiện, hãy chọn tuyến bạn định dùng và chỉnh sửa cấu hình thủ công. Giữ nguyên cảnh báo khi PI Codex OAuth là chủ ý.
Nếu cảnh báo xuất hiện, hãy chọn tuyến bạn dự định dùng và sửa cấu hình thủ công. Giữ nguyên cảnh báo khi PI Codex OAuth là có chủ đích.
</Accordion>
<Accordion title="3. Di chuyển trạng thái cũ (bố cục đĩa)">
Doctor có thể di chuyển các bố cục cũ trên đĩa sang cấu trúc hiện tại:
<Accordion title="2g. Dọn dẹp tuyến phiên">
Doctor cũng quét kho phiên hoạt động để tìm trạng thái tuyến tự tạo đã lỗi thời sau khi bạn chuyển mô hình hoặc runtime mặc định/dự phòng đã cấu hình khỏi một tuyến do Plugin sở hữu, chẳng hạn như Codex.
`openclaw doctor --fix` có thể xóa trạng thái lỗi thời tự tạo như ghim mô hình `modelOverrideSource: "auto"`, metadata mô hình runtime, ID harness đã ghim, liên kết phiên CLI, và ghi đè hồ sơ xác thực tự động khi tuyến sở hữu chúng không còn được cấu hình. Các lựa chọn mô hình phiên rõ ràng của người dùng hoặc phiên cũ được báo cáo để xem xét thủ công và giữ nguyên; chuyển chúng bằng `/model ...`, `/new`, hoặc đặt lại phiên khi tuyến đó không còn là ý định sử dụng.
</Accordion>
<Accordion title="3. Di chuyển trạng thái cũ (bố cục ổ đĩa)">
Doctor có thể di chuyển các bố cục cũ trên ổ đĩa vào cấu trúc hiện tại:
- Kho phiên + bản ghi:
- từ `~/.openclaw/sessions/` sang `~/.openclaw/agents/<agentId>/sessions/`
@ -284,213 +294,213 @@ Lệnh đó staging các ứng viên bền vững grounded vào kho Dreaming ng
- từ `~/.openclaw/agent/` sang `~/.openclaw/agents/<agentId>/agent/`
- Trạng thái xác thực WhatsApp (Baileys):
- từ `~/.openclaw/credentials/*.json` cũ (ngoại trừ `oauth.json`)
- sang `~/.openclaw/credentials/whatsapp/<accountId>/...` (id tài khoản mặc định: `default`)
- sang `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID tài khoản mặc định: `default`)
Những lần di chuyển này là nỗ lực tối đa và có tính lặp lại an toàn; doctor sẽ phát cảnh báo khi để lại bất kỳ thư mục cũ nào làm bản sao lưu. Gateway/CLI cũng tự động di chuyển kho phiên cũ + thư mục agent khi khởi động để lịch sử/xác thực/model nằm trong đường dẫn theo từng agent mà không cần chạy doctor thủ công. Xác thực WhatsApp được cố ý chỉ di chuyển qua `openclaw doctor`. Việc chuẩn hóa provider/bản đồ provider của Talk hiện so sánh bằng bình đẳng cấu trúc, nên các khác biệt chỉ do thứ tự khóa không còn kích hoạt lại các thay đổi `doctor --fix` không tác dụng.
Các lần di chuyển này là nỗ lực tốt nhất và có tính lặp lại an toàn; doctor sẽ phát cảnh báo khi để lại bất kỳ thư mục cũ nào làm bản sao lưu. Gateway/CLI cũng tự động di chuyển phiên cũ + thư mục agent khi khởi động để lịch sử/xác thực/mô hình nằm trong đường dẫn theo từng agent mà không cần chạy doctor thủ công. Chuẩn hóa nhà cung cấp talk/bản đồ nhà cung cấp hiện so sánh bằng bình đẳng cấu trúc, nên các khác biệt chỉ do thứ tự khóa không còn kích hoạt lặp lại các thay đổi `doctor --fix` không có tác dụng.
</Accordion>
<Accordion title="3a. Di chuyển manifest Plugin cũ">
Doctor quét tất cả manifest Plugin đã cài đặt để tìm các khóa capability cấp cao nhất đã lỗi thời (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Khi tìm thấy, nó đề xuất di chuyển chúng vào đối tượng `contracts` và ghi lại file manifest tại chỗ. Việc di chuyển này có tính lặp lại an toàn; nếu khóa `contracts` đã có cùng các giá trị, khóa cũ sẽ bị xóa mà không nhân đôi dữ liệu.
Doctor quét tất cả manifest Plugin đã cài đặt để tìm các khóa capability cấp cao nhất không còn dùng (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Khi tìm thấy, nó đề nghị chuyển chúng vào đối tượng `contracts` và viết lại tệp manifest tại chỗ. Quá trình di chuyển này có tính lặp lại an toàn; nếu khóa `contracts` đã có cùng các giá trị, khóa cũ sẽ bị xóa mà không nhân đôi dữ liệu.
</Accordion>
<Accordion title="3b. Di chuyển kho Cron cũ">
Doctor cũng kiểm tra kho công việc Cron (`~/.openclaw/cron/jobs.json` theo mặc định, hoặc `cron.store` khi được ghi đè) để tìm các dạng công việc cũ mà bộ lập lịch vẫn chấp nhận để tương thích.
Doctor cũng kiểm tra kho công việc cron (`~/.openclaw/cron/jobs.json` theo mặc định, hoặc `cron.store` khi bị ghi đè) để tìm các dạng công việc cũ mà bộ lập lịch vẫn chấp nhận để tương thích.
Các dọn dẹp Cron hiện tại bao gồm:
Các dọn dẹp cron hiện tại bao gồm:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- các trường payload cấp cao nhất (`message`, `model`, `thinking`, ...) → `payload`
- các trường delivery cấp cao nhất (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- bí danh delivery `provider` trong payload → `delivery.channel` rõ ràng
- các công việc dự phòng webhook `notify: true` đơn giản cũ → `delivery.mode="webhook"` rõ ràng với `delivery.to=cron.webhook`
- các công việc webhook dự phòng `notify: true` cũ đơn giản → `delivery.mode="webhook"` rõ ràng với `delivery.to=cron.webhook`
Doctor chỉ tự động di chuyển các công việc `notify: true` khi có thể làm vậy mà không thay đổi hành vi. Nếu một công việc kết hợp dự phòng notify cũ với một chế độ delivery hiện có không phải webhook, doctor cảnh báo và để công việc đó cho bạn xem xét thủ công.
Doctor chỉ tự động di chuyển các công việc `notify: true` khi có thể làm vậy mà không thay đổi hành vi. Nếu một công việc kết hợp dự phòng notify cũ với một chế độ delivery không phải webhook hiện có, doctor cảnh báo và để công việc đó lại để xem xét thủ công.
Trên Linux, doctor cũng cảnh báo khi crontab của người dùng vẫn gọi `~/.openclaw/bin/ensure-whatsapp.sh` cũ. Script host-local đó không được OpenClaw hiện tại bảo trì và có thể ghi các thông báo `Gateway inactive` sai vào `~/.openclaw/logs/whatsapp-health.log` khi cron không thể truy cập bus người dùng systemd. Xóa mục crontab lỗi thời bằng `crontab -e`; dùng `openclaw channels status --probe`, `openclaw doctor`, và `openclaw gateway status` cho các kiểm tra sức khỏe hiện tại.
Trên Linux, doctor cũng cảnh báo khi crontab của người dùng vẫn gọi `~/.openclaw/bin/ensure-whatsapp.sh` cũ. Tập lệnh cục bộ trên máy chủ đó không được OpenClaw hiện tại duy trì và có thể ghi các thông báo `Gateway inactive` sai vào `~/.openclaw/logs/whatsapp-health.log` khi cron không thể truy cập systemd user bus. Xóa mục crontab đã lỗi thời bằng `crontab -e`; dùng `openclaw channels status --probe`, `openclaw doctor`, và `openclaw gateway status` cho các lần kiểm tra tình trạng hiện tại.
</Accordion>
<Accordion title="3c. Dọn dẹp khóa phiên">
Doctor quét mọi thư mục phiên tác tử để tìm các tệp khóa ghi cũ — các tệp bị bỏ lại khi một phiên thoát bất thường. Với mỗi tệp khóa tìm thấy, công cụ báo cáo: đường dẫn, PID, liệu PID còn hoạt động hay không, tuổi khóa, và liệu khóa có được xem là cũ hay không (PID đã chết hoặc cũ hơn 30 phút). Ở chế độ `--fix` / `--repair`, công cụ tự động xóa các tệp khóa cũ; nếu không, công cụ in ghi chú và hướng dẫn bạn chạy lại với `--fix`.
Doctor quét mọi thư mục phiên tác nhân để tìm các tệp khóa ghi lỗi thời — các tệp còn sót lại khi một phiên thoát bất thường. Với mỗi tệp khóa tìm thấy, nó báo cáo: đường dẫn, PID, liệu PID còn đang chạy hay không, tuổi của khóa, và liệu khóa có được xem là lỗi thời hay không (PID đã chết hoặc cũ hơn 30 phút). Ở chế độ `--fix` / `--repair`, nó tự động xóa các tệp khóa lỗi thời; nếu không, nó in một ghi chú và hướng dẫn bạn chạy lại với `--fix`.
</Accordion>
<Accordion title="3d. Sửa nhánh bản ghi phiên">
Doctor quét các tệp JSONL phiên tác tử để tìm cấu trúc nhánh bị nhân đôi do lỗi viết lại bản ghi lời nhắc 2026.4.24 tạo ra: một lượt người dùng bị bỏ lại với ngữ cảnh runtime nội bộ của OpenClaw cùng một nhánh ngang hàng đang hoạt động chứa cùng lời nhắc người dùng hiển thị. Ở chế độ `--fix` / `--repair`, doctor sao lưu từng tệp bị ảnh hưởng bên cạnh tệp gốc và viết lại bản ghi sang nhánh đang hoạt động để lịch sử gateway và các trình đọc bộ nhớ không còn thấy các lượt bị trùng lặp.
Doctor quét các tệp JSONL phiên tác nhân để tìm cấu trúc nhánh bị nhân đôi do lỗi viết lại bản ghi prompt ngày 2026.4.24 tạo ra: một lượt người dùng bị bỏ rơi có ngữ cảnh runtime nội bộ của OpenClaw cùng với một nhánh anh em đang hoạt động chứa cùng prompt người dùng hiển thị. Ở chế độ `--fix` / `--repair`, doctor sao lưu từng tệp bị ảnh hưởng bên cạnh tệp gốc và viết lại bản ghi về nhánh đang hoạt động để lịch sử gateway và các bộ đọc bộ nhớ không còn thấy các lượt trùng lặp.
</Accordion>
<Accordion title="4. Kiểm tra tính toàn vẹn trạng thái (duy trì phiên, định tuyến và an toàn)">
Thư mục trạng thái là trung khu vận hành. Nếu thư mục này biến mất, bạn sẽ mất phiên, thông tin xác thực, nhật ký và cấu hình (trừ khi bạn có bản sao lưu ở nơi khác).
<Accordion title="4. Kiểm tra tính toàn vẹn trạng thái (lưu phiên, định tuyến và an toàn)">
Thư mục trạng thái là trung khu vận hành. Nếu nó biến mất, bạn sẽ mất phiên, thông tin xác thực, nhật ký và cấu hình (trừ khi bạn có bản sao lưu ở nơi khác).
Doctor kiểm tra:
- **Thiếu thư mục trạng thái**: cảnh báo về mất trạng thái nghiêm trọng, nhắc tạo lại thư mục, và nhắc rằng công cụ không thể khôi phục dữ liệu đã mất.
- **Quyền thư mục trạng thái**: xác minh khả năng ghi; đề xuất sửa quyền (và phát gợi ý `chown` khi phát hiện chủ sở hữu/nhóm không khớp).
- **Thư mục trạng thái được đồng bộ đám mây trên macOS**: cảnh báo khi trạng thái phân giải dưới iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) hoặc `~/Library/CloudStorage/...` vì các đường dẫn có đồng bộ hỗ trợ có thể gây I/O chậm hơn và các cuộc đua khóa/đồng bộ.
- **Thư mục trạng thái trên SD hoặc eMMC của Linux**: cảnh báo khi trạng thái phân giải tới nguồn gắn kết `mmcblk*`, vì I/O ngẫu nhiên dựa trên SD hoặc eMMC có thể chậm hơn và hao mòn nhanh hơn khi ghi phiên và thông tin xác thực.
- **Thiếu thư mục phiên**: `sessions/` và thư mục lưu trữ phiên là bắt buộc để duy trì lịch sử và tránh lỗi sập `ENOENT`.
- **Thiếu thư mục trạng thái**: cảnh báo về mất trạng thái nghiêm trọng, nhắc tạo lại thư mục, và nhắc bạn rằng nó không thể khôi phục dữ liệu bị thiếu.
- **Quyền thư mục trạng thái**: xác minh khả năng ghi; đề nghị sửa quyền (và phát ra gợi ý `chown` khi phát hiện chủ sở hữu/nhóm không khớp).
- **Thư mục trạng thái được đồng bộ đám mây trên macOS**: cảnh báo khi trạng thái phân giải dưới iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) hoặc `~/Library/CloudStorage/...` vì các đường dẫn được đồng bộ có thể gây I/O chậm hơn và tranh chấp khóa/đồng bộ.
- **Thư mục trạng thái SD hoặc eMMC trên Linux**: cảnh báo khi trạng thái phân giải tới nguồn gắn kết `mmcblk*`, vì I/O ngẫu nhiên dựa trên SD hoặc eMMC có thể chậm hơn và hao mòn nhanh hơn khi ghi phiên và thông tin xác thực.
- **Thiếu thư mục phiên**: `sessions/` và thư mục lưu phiên là bắt buộc để lưu lịch sử và tránh sự cố `ENOENT`.
- **Bản ghi không khớp**: cảnh báo khi các mục phiên gần đây thiếu tệp bản ghi.
- **Phiên chính "JSONL 1 dòng"**: gắn cờ khi bản ghi chính chỉ có một dòng (lịch sử không được tích lũy).
- **Nhiều thư mục trạng thái**: cảnh báo khi nhiều thư mục `~/.openclaw` tồn tại trên các thư mục home hoặc khi `OPENCLAW_STATE_DIR` trỏ tới nơi khác (lịch sử có thể bị chia tách giữa các bản cài đặt).
- **Nhắc nhở chế độ từ xa**: nếu `gateway.mode=remote`, doctor nhắc bạn chạy công cụ trên máy chủ từ xa (trạng thái nằm ở đó).
- **Quyền tệp cấu hình**: cảnh báo nếu `~/.openclaw/openclaw.json` có thể đọc bởi nhóm/toàn bộ người dùng và đề xuất siết chặt thành `600`.
- **Phiên chính "JSONL 1 dòng"**: đánh dấu khi bản ghi chính chỉ có một dòng (lịch sử không được tích lũy).
- **Nhiều thư mục trạng thái**: cảnh báo khi nhiều thư mục `~/.openclaw` tồn tại trên các thư mục home hoặc khi `OPENCLAW_STATE_DIR` trỏ đến nơi khác (lịch sử có thể bị chia tách giữa các bản cài đặt).
- **Nhắc nhở chế độ từ xa**: nếu `gateway.mode=remote`, doctor nhắc bạn chạy nó trên máy chủ từ xa (trạng thái nằm ở đó).
- **Quyền tệp cấu hình**: cảnh báo nếu `~/.openclaw/openclaw.json` có thể đọc bởi nhóm/mọi người và đề nghị siết chặt thành `600`.
</Accordion>
<Accordion title="5. Sức khỏe xác thực mô hình (OAuth hết hạn)">
Doctor kiểm tra các hồ sơ OAuth trong kho xác thực, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể làm mới chúng khi an toàn. Nếu hồ sơ OAuth/token Anthropic đã cũ, công cụ đề xuất khóa API Anthropic hoặc đường dẫn setup-token Anthropic. Lời nhắc làm mới chỉ xuất hiện khi chạy tương tác (TTY); `--non-interactive` bỏ qua các lần thử làm mới.
<Accordion title="5. Tình trạng xác thực mô hình (OAuth hết hạn)">
Doctor kiểm tra các hồ sơ OAuth trong kho xác thực, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể làm mới chúng khi an toàn. Nếu hồ sơ OAuth/token Anthropic đã lỗi thời, nó gợi ý khóa API Anthropic hoặc đường dẫn setup-token Anthropic. Lời nhắc làm mới chỉ xuất hiện khi chạy tương tác (TTY); `--non-interactive` bỏ qua các lần thử làm mới.
Khi làm mới OAuth thất bại vĩnh viễn (ví dụ `refresh_token_reused`, `invalid_grant`, hoặc nhà cung cấp yêu cầu bạn đăng nhập lại), doctor báo rằng cần xác thực lại và in chính xác lệnh `openclaw models auth login --provider ...` cần chạy.
Khi làm mới OAuth thất bại vĩnh viễn (ví dụ `refresh_token_reused`, `invalid_grant`, hoặc nhà cung cấp yêu cầu bạn đăng nhập lại), doctor báo rằng cần xác thực lại và in đúng lệnh `openclaw models auth login --provider ...` cần chạy.
Doctor cũng báo cáo các hồ sơ xác thực tạm thời không dùng được do:
- thời gian chờ ngắn (giới hạn tốc độ/hết thời gian chờ/lỗi xác thực)
- vô hiệu hóa lâu hơn (lỗi thanh toán/tín dụng)
- vô hiệu hóa dài hơn (lỗi thanh toán/tín dụng)
</Accordion>
<Accordion title="6. Xác thực mô hình hook">
Nếu `hooks.gmail.model` được đặt, doctor xác thực tham chiếu mô hình với catalog và allowlist, đồng thời cảnh báo khi tham chiếu không phân giải được hoặc không được cho phép.
<Accordion title="6. Xác thực mô hình hooks">
Nếu `hooks.gmail.model` được đặt, doctor xác thực tham chiếu mô hình với catalog và danh sách cho phép, đồng thời cảnh báo khi nó không phân giải được hoặc không được cho phép.
</Accordion>
<Accordion title="7. Sửa ảnh sandbox">
Khi sandboxing được bật, doctor kiểm tra ảnh Docker và đề xuất build hoặc chuyển sang tên cũ nếu ảnh hiện tại bị thiếu.
Khi sandboxing được bật, doctor kiểm tra Docker images và đề nghị xây dựng hoặc chuyển sang tên cũ nếu ảnh hiện tại bị thiếu.
</Accordion>
<Accordion title="7b. Dọn dẹp cài đặt Plugin">
Doctor xóa trạng thái staging phụ thuộc Plugin cũ do OpenClaw tạo ở chế độ `openclaw doctor --fix` / `openclaw doctor --repair`. Việc này bao gồm các gốc phụ thuộc được tạo đã cũ, thư mục giai đoạn cài đặt cũ, mảnh vụn cục bộ theo gói từ mã sửa phụ thuộc Plugin đóng gói trước đây, và các bản sao npm được quản lý của Plugin `@openclaw/*` đóng gói bị mồ côi hoặc được khôi phục có thể che khuất manifest đóng gói hiện tại.
Doctor xóa trạng thái staging dependency plugin cũ do OpenClaw tạo ở chế độ `openclaw doctor --fix` / `openclaw doctor --repair`. Việc này bao gồm các gốc dependency được tạo đã lỗi thời, thư mục install-stage cũ, mảnh vụn cục bộ trong package từ mã sửa dependency bundled-plugin trước đây, và các bản sao npm được quản lý của các plugin `@openclaw/*` bundled bị mồ côi hoặc được khôi phục có thể che khuất manifest bundled hiện tại.
Doctor cũng có thể cài đặt lại các Plugin có thể tải xuống đã cấu hình khi cấu hình tham chiếu chúng nhưng registry Plugin cục bộ không tìm thấy. Với việc tách Plugin đóng gói ra ngoài trong 2026.5.2, doctor tự động cài đặt các Plugin có thể tải xuống mà cấu hình hiện có đã dùng, rồi dựa vào `meta.lastTouchedVersion` để chỉ chạy lượt phát hành đó một lần. Khởi động Gateway và tải lại cấu hình không chạy trình quản lý gói; cài đặt Plugin vẫn là công việc rõ ràng của doctor/install/update.
Doctor cũng có thể cài đặt lại các plugin có thể tải xuống bị thiếu khi cấu hình tham chiếu đến chúng nhưng registry plugin cục bộ không tìm thấy. Ví dụ gồm `plugins.entries` thực tế, thiết lập channel/provider/search đã cấu hình, và runtime tác nhân đã cấu hình. Trong quá trình cập nhật package, doctor tránh chạy sửa plugin bằng package-manager khi package lõi đang được thay thế; chạy lại `openclaw doctor --fix` sau khi cập nhật nếu một plugin đã cấu hình vẫn cần khôi phục. Khởi động Gateway và tải lại cấu hình không chạy package managers; cài đặt plugin vẫn là công việc doctor/install/update rõ ràng.
</Accordion>
<Accordion title="8. Di trú dịch vụ Gateway và gợi ý dọn dẹp">
Doctor phát hiện các dịch vụ gateway cũ (launchd/systemd/schtasks) và đề xuất xóa chúng rồi cài đặt dịch vụ OpenClaw bằng cổng Gateway hiện tại. Công cụ cũng có thể quét các dịch vụ giống gateway bổ sung và in gợi ý dọn dẹp. Các dịch vụ Gateway OpenClaw có tên theo hồ sơ được xem là hạng nhất và không bị gắn cờ là "bổ sung."
<Accordion title="8. Di chuyển dịch vụ Gateway và gợi ý dọn dẹp">
Doctor phát hiện các dịch vụ gateway cũ (launchd/systemd/schtasks) và đề nghị xóa chúng rồi cài đặt dịch vụ OpenClaw bằng cổng gateway hiện tại. Nó cũng có thể quét các dịch vụ giống gateway bổ sung và in gợi ý dọn dẹp. Các dịch vụ gateway OpenClaw được đặt tên theo hồ sơ được xem là hạng nhất và không bị đánh dấu là "bổ sung."
Trên Linux, nếu dịch vụ Gateway cấp người dùng bị thiếu nhưng một dịch vụ Gateway OpenClaw cấp hệ thống tồn tại, doctor không tự động cài đặt dịch vụ cấp người dùng thứ hai. Kiểm tra bằng `openclaw gateway status --deep` hoặc `openclaw doctor --deep`, rồi xóa bản trùng lặp hoặc đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một supervisor hệ thống sở hữu vòng đời Gateway.
Trên Linux, nếu dịch vụ gateway cấp người dùng bị thiếu nhưng có dịch vụ gateway OpenClaw cấp hệ thống, doctor không tự động cài đặt dịch vụ cấp người dùng thứ hai. Kiểm tra bằng `openclaw gateway status --deep` hoặc `openclaw doctor --deep`, sau đó xóa bản trùng lặp hoặc đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một trình giám sát hệ thống sở hữu vòng đời gateway.
</Accordion>
<Accordion title="8b. Di trú Startup Matrix">
Khi tài khoản kênh Matrix có di trú trạng thái cũ đang chờ hoặc có thể thực hiện, doctor (ở chế độ `--fix` / `--repair`) tạo ảnh chụp trước di trú rồi chạy các bước di trú nỗ lực tối đa: di trú trạng thái Matrix cũ và chuẩn bị trạng thái mã hóa cũ. Cả hai bước đều không gây lỗi nghiêm trọng; lỗi được ghi nhật ký và quá trình khởi động tiếp tục. Ở chế độ chỉ đọc (`openclaw doctor` không có `--fix`), kiểm tra này bị bỏ qua hoàn toàn.
<Accordion title="8b. Di chuyển Startup Matrix">
Khi một tài khoản channel Matrix có quá trình di chuyển trạng thái cũ đang chờ hoặc có thể hành động, doctor (ở chế độ `--fix` / `--repair`) tạo snapshot trước di chuyển rồi chạy các bước di chuyển best-effort: di chuyển trạng thái Matrix cũ và chuẩn bị trạng thái mã hóa cũ. Cả hai bước đều không gây lỗi nghiêm trọng; lỗi được ghi nhật ký và quá trình khởi động tiếp tục. Ở chế độ chỉ đọc (`openclaw doctor` không có `--fix`), kiểm tra này bị bỏ qua hoàn toàn.
</Accordion>
<Accordion title="8c. Ghép nối thiết bị và lệch xác thực">
Doctor hiện kiểm tra trạng thái ghép nối thiết bị như một phần của lượt kiểm tra sức khỏe thông thường.
Doctor hiện kiểm tra trạng thái ghép nối thiết bị như một phần của lượt kiểm tra tình trạng bình thường.
Nội dung được báo cáo:
Nội dung nó báo cáo:
- yêu cầu ghép nối lần đầu đang chờ
- nâng cấp vai trò đang chờ cho thiết bị đã ghép nối
- nâng cấp phạm vi đang chờ cho thiết bị đã ghép nối
- sửa lỗi khóa công khai không khớp khi id thiết bị vẫn khớp nhưng danh tính thiết bị không còn khớp với bản ghi đã phê duyệt
- bản ghi đã ghép nối thiếu token đang hoạt động cho vai trò đã phê duyệt
- sửa lỗi public-key không khớp khi device id vẫn khớp nhưng danh tính thiết bị không còn khớp với bản ghi đã phê duyệt
- bản ghi đã ghép nối thiếu token hoạt động cho một vai trò đã phê duyệt
- token đã ghép nối có phạm vi lệch khỏi baseline ghép nối đã phê duyệt
- mục token thiết bị được lưu đệm cục bộ cho máy hiện tại có trước lần xoay vòng token phía gateway hoặc mang metadata phạm vi đã cũ
- mục device-token được cache cục bộ cho máy hiện tại có trước lần xoay token phía gateway hoặc mang metadata phạm vi lỗi thời
Doctor không tự động phê duyệt yêu cầu ghép nối hoặc tự động xoay vòng token thiết bị. Công cụ in chính xác các bước tiếp theo thay vào đó:
Doctor không tự động phê duyệt yêu cầu ghép nối hoặc tự động xoay token thiết bị. Thay vào đó, nó in đúng các bước tiếp theo:
- kiểm tra yêu cầu đang chờ bằng `openclaw devices list`
- phê duyệt yêu cầu chính xác bằng `openclaw devices approve <requestId>`
- xoay vòng token mới bằng `openclaw devices rotate --device <deviceId> --role <role>`
- xóa và phê duyệt lại bản ghi cũ bằng `openclaw devices remove <deviceId>`
- phê duyệt đúng yêu cầu bằng `openclaw devices approve <requestId>`
- xoay token mới bằng `openclaw devices rotate --device <deviceId> --role <role>`
- xóa và phê duyệt lại bản ghi lỗi thời bằng `openclaw devices remove <deviceId>`
Việc này khép lại lỗ hổng phổ biến "đã ghép nối nhưng vẫn bị yêu cầu ghép nối": doctor hiện phân biệt ghép nối lần đầu với nâng cấp vai trò/phạm vi đang chờ và với lệch token/danh tính thiết bị đã cũ.
Việc này đóng lỗ hổng phổ biến "đã ghép nối nhưng vẫn nhận yêu cầu ghép nối": doctor hiện phân biệt ghép nối lần đầu với nâng cấp vai trò/phạm vi đang chờ và với lệch token/danh tính thiết bị lỗi thời.
</Accordion>
<Accordion title="9. Cảnh báo bảo mật">
Doctor phát cảnh báo khi một nhà cung cấp mở DM mà không có allowlist, hoặc khi một chính sách được cấu hình theo cách nguy hiểm.
Doctor phát cảnh báo khi một provider mở cho DM mà không có danh sách cho phép, hoặc khi một chính sách được cấu hình theo cách nguy hiểm.
</Accordion>
<Accordion title="10. systemd linger (Linux)">
Nếu đang chạy dưới dạng dịch vụ người dùng systemd, doctor đảm bảo linger được bật để gateway vẫn hoạt động sau khi đăng xuất.
Nếu đang chạy dưới dạng dịch vụ người dùng systemd, doctor đảm bảo lingering được bật để gateway vẫn hoạt động sau khi đăng xuất.
</Accordion>
<Accordion title="11. Trạng thái workspace (Skills, Plugin và thư mục cũ)">
Doctor in bản tóm tắt trạng thái workspace cho tác tử mặc định:
<Accordion title="11. Trạng thái workspace (skills, plugins và thư mục cũ)">
Doctor in tóm tắt trạng thái workspace cho tác nhân mặc định:
- **Trạng thái Skills**: đếm các skill đủ điều kiện, thiếu yêu cầu và bị allowlist chặn.
- **Trạng thái Skills**: đếm Skills đủ điều kiện, thiếu-yêu-cầu và bị danh sách-cho-phép chặn.
- **Thư mục workspace cũ**: cảnh báo khi `~/openclaw` hoặc các thư mục workspace cũ khác tồn tại bên cạnh workspace hiện tại.
- **Trạng thái Plugin**: đếm Plugin đã bật/đã tắt/có lỗi; liệt kê ID Plugin cho mọi lỗi; báo cáo khả năng của Plugin đóng gói.
- **Cảnh báo tương thích Plugin**: gắn cờ các Plugin có vấn đề tương thích với runtime hiện tại.
- **Chẩn đoán Plugin**: hiển thị mọi cảnh báo hoặc lỗi tại thời điểm tải do registry Plugin phát ra.
- **Trạng thái Plugin**: đếm plugins đã bật/đã tắt/bị lỗi; liệt kê ID plugin cho mọi lỗi; báo cáo khả năng bundle plugin.
- **Cảnh báo tương thích Plugin**: đánh dấu plugins có vấn đề tương thích với runtime hiện tại.
- **Chẩn đoán Plugin**: hiển thị mọi cảnh báo hoặc lỗi tại thời điểm tải do registry plugin phát ra.
</Accordion>
<Accordion title="11b. Kích thước tệp bootstrap">
Doctor kiểm tra xem các tệp bootstrap workspace (ví dụ `AGENTS.md`, `CLAUDE.md`, hoặc các tệp ngữ cảnh được chèn khác) có gần hoặc vượt ngân sách ký tự đã cấu hình hay không. Công cụ báo cáo số ký tự thô so với đã chèn theo từng tệp, phần trăm cắt bớt, nguyên nhân cắt bớt (`max/file` hoặc `max/total`), và tổng ký tự đã chèn như một phần của tổng ngân sách. Khi tệp bị cắt bớt hoặc gần giới hạn, doctor in mẹo để tinh chỉnh `agents.defaults.bootstrapMaxChars` và `agents.defaults.bootstrapTotalMaxChars`.
Doctor kiểm tra liệu các tệp bootstrap workspace (ví dụ `AGENTS.md`, `CLAUDE.md`, hoặc các tệp ngữ cảnh được chèn khác) có gần hoặc vượt ngân sách ký tự đã cấu hình hay không. Nó báo cáo số ký tự thô so với đã chèn theo từng tệp, phần trăm cắt ngắn, nguyên nhân cắt ngắn (`max/file` hoặc `max/total`), và tổng số ký tự đã chèn dưới dạng tỷ lệ của tổng ngân sách. Khi các tệp bị cắt ngắn hoặc gần giới hạn, doctor in mẹo để tinh chỉnh `agents.defaults.bootstrapMaxChars` và `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Dọn dẹp Plugin kênh đã cũ">
Khi `openclaw doctor --fix` xóa một Plugin kênh bị thiếu, công cụ cũng xóa cấu hình theo phạm vi kênh bị treo đã tham chiếu Plugin đó: mục `channels.<id>`, mục tiêu Heartbeat đã đặt tên kênh, và các ghi đè `agents.*.models["<channel>/*"]`. Việc này ngăn vòng lặp khởi động Gateway khi runtime kênh đã mất nhưng cấu hình vẫn yêu cầu gateway liên kết với nó.
<Accordion title="11d. Dọn dẹp plugin channel lỗi thời">
Khi `openclaw doctor --fix` xóa một plugin channel bị thiếu, nó cũng xóa cấu hình treo theo phạm vi channel đã tham chiếu đến plugin đó: các mục `channels.<id>`, mục tiêu Heartbeat đã nêu tên channel, và ghi đè `agents.*.models["<channel>/*"]`. Điều này ngăn các vòng lặp khởi động Gateway khi runtime channel đã biến mất nhưng cấu hình vẫn yêu cầu gateway liên kết với nó.
</Accordion>
<Accordion title="11c. Hoàn tất shell">
Doctor kiểm tra xem tính năng hoàn tất bằng phím Tab đã được cài đặt cho shell hiện tại hay chưa (zsh, bash, fish hoặc PowerShell):
Doctor kiểm tra liệu tab completion có được cài đặt cho shell hiện tại (zsh, bash, fish, hoặc PowerShell) hay không:
- Nếu hồ sơ shell dùng mẫu hoàn tất động chậm (`source <(openclaw completion ...)`), doctor nâng cấp nó lên biến thể tệp lưu đệm nhanh hơn.
- Nếu hoàn tất được cấu hình trong hồ sơ nhưng tệp cache bị thiếu, doctor tự động tạo lại cache.
- Nếu hoàn toàn chưa cấu hình hoàn tất, doctor nhắc cài đặt (chỉ ở chế độ tương tác; bị bỏ qua với `--non-interactive`).
- Nếu hồ sơ shell dùng mẫu completion động chậm (`source <(openclaw completion ...)`), doctor nâng cấp nó lên biến thể tệp cache nhanh hơn.
- Nếu completion được cấu hình trong hồ sơ nhưng tệp cache bị thiếu, doctor tự động tạo lại cache.
- Nếu chưa có completion nào được cấu hình, doctor nhắc cài đặt nó (chỉ chế độ tương tác; bỏ qua với `--non-interactive`).
Chạy `openclaw completion --write-state` để tạo lại cache thủ công.
</Accordion>
<Accordion title="12. Kiểm tra xác thực Gateway (token cục bộ)">
Doctor kiểm tra mức sẵn sàng xác thực token Gateway cục bộ.
Doctor kiểm tra mức sẵn sàng xác thực token gateway cục bộ.
- Nếu chế độ token cần token và không có nguồn token nào tồn tại, doctor đề xuất tạo một token.
- Nếu `gateway.auth.token` do SecretRef quản lý nhưng không khả dụng, doctor cảnh báo và không ghi đè bằng văn bản thuần.
- `openclaw doctor --generate-gateway-token` chỉ ép tạo khi không cấu hình SecretRef token nào.
- Nếu chế độ token cần token và không có nguồn token nào tồn tại, doctor đề nghị tạo một token.
- Nếu `gateway.auth.token` do SecretRef quản lý nhưng không khả dụng, doctor cảnh báo và không ghi đè nó bằng plaintext.
- `openclaw doctor --generate-gateway-token` chỉ buộc tạo khi không có SecretRef token nào được cấu hình.
</Accordion>
<Accordion title="12b. Sửa chữa chỉ đọc có nhận biết SecretRef">
<Accordion title="12b. Sửa chữa chỉ đọc nhận biết SecretRef">
Một số luồng sửa chữa cần kiểm tra thông tin xác thực đã cấu hình mà không làm suy yếu hành vi fail-fast của runtime.
- `openclaw doctor --fix` hiện dùng cùng mô hình tóm tắt SecretRef chỉ đọc như các lệnh họ trạng thái cho những sửa chữa cấu hình có mục tiêu.
- Ví dụ: sửa Telegram `allowFrom` / `groupAllowFrom` `@username` cố gắng dùng thông tin xác thực bot đã cấu hình khi có.
- Nếu token bot Telegram được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại, doctor báo rằng thông tin xác thực đã được cấu hình-nhưng-không-khả dụng và bỏ qua tự động phân giải thay vì bị sập hoặc báo sai rằng token bị thiếu.
- `openclaw doctor --fix` hiện dùng cùng mô hình tóm tắt SecretRef chỉ đọc như các lệnh thuộc nhóm trạng thái cho các sửa chữa cấu hình có mục tiêu.
- Ví dụ: sửa chữa Telegram `allowFrom` / `groupAllowFrom` `@username` cố gắng dùng thông tin đăng nhập bot đã cấu hình khi có sẵn.
- Nếu token bot Telegram được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại, doctor báo cáo rằng thông tin đăng nhập đã được cấu hình-nhưng-không-khả-dụng và bỏ qua tự động phân giải thay vì gặp lỗi hoặc báo sai rằng token bị thiếu.
</Accordion>
<Accordion title="13. Kiểm tra tình trạng Gateway + khởi động lại">
Lệnh doctor chạy kiểm tra tình trạng và đề xuất khởi động lại gateway khi có vẻ không khỏe.
<Accordion title="13. Kiểm tra sức khỏe Gateway + khởi động lại">
Doctor chạy kiểm tra sức khỏe và đề xuất khởi động lại gateway khi có vẻ không khỏe.
</Accordion>
<Accordion title="13b. Mức sẵn sàng của tìm kiếm bộ nhớ">
Lệnh doctor kiểm tra xem nhà cung cấp embedding tìm kiếm bộ nhớ đã cấu hình có sẵn sàng cho agent mặc định hay không. Hành vi phụ thuộc vào backend và nhà cung cấp đã cấu hình:
<Accordion title="13b. Mức sẵn sàng tìm kiếm bộ nhớ">
Doctor kiểm tra xem nhà cung cấp embedding tìm kiếm bộ nhớ đã cấu hình có sẵn sàng cho tác tử mặc định hay không. Hành vi phụ thuộc vào backend và nhà cung cấp đã cấu hình:
- **Backend QMD**: thăm dò xem binary `qmd` có sẵn và có thể khởi động hay không. Nếu không, in hướng dẫn khắc phục bao gồm gói npm và tùy chọn đường dẫn binary thủ công.
- **Nhà cung cấp cục bộ tường minh**: kiểm tra tệp mô hình cục bộ hoặc một URL mô hình từ xa/có thể tải xuống được nhận diện. Nếu thiếu, đề xuất chuyển sang nhà cung cấp từ xa.
- **Nhà cung cấp từ xa tường minh** (`openai`, `voyage`, v.v.): xác minh có khóa API trong môi trường hoặc kho xác thực. In gợi ý khắc phục có thể thực hiện nếu thiếu.
- **Nhà cung cấp tự động**: kiểm tra tính sẵn có của mô hình cục bộ trước, sau đó thử từng nhà cung cấp từ xa theo thứ tự tự động chọn.
- **Backend QMD**: thăm dò xem binary `qmd` có khả dụng và có thể khởi động hay không. Nếu không, in hướng dẫn sửa lỗi bao gồm gói npm và tùy chọn đường dẫn binary thủ công.
- **Nhà cung cấp cục bộ tường minh**: kiểm tra tệp mô hình cục bộ hoặc URL mô hình từ xa/có thể tải xuống được nhận diện. Nếu thiếu, đề xuất chuyển sang nhà cung cấp từ xa.
- **Nhà cung cấp từ xa tường minh** (`openai`, `voyage`, v.v.): xác minh khóa API có trong môi trường hoặc kho xác thực. In gợi ý sửa lỗi có thể hành động nếu thiếu.
- **Nhà cung cấp tự động**: kiểm tra tính khả dụng của mô hình cục bộ trước, rồi thử từng nhà cung cấp từ xa theo thứ tự tự động chọn.
Khi có kết quả thăm dò gateway được lưu trong bộ nhớ đệm (gateway khỏe tại thời điểm kiểm tra), doctor đối chiếu chéo kết quả đó với cấu hình nhìn thấy từ CLI và ghi chú mọi điểm không khớp. Doctor không bắt đầu ping embedding mới trên đường dẫn mặc định; hãy dùng lệnh trạng thái bộ nhớ sâu khi bạn muốn kiểm tra nhà cung cấp trực tiếp.
Khi có kết quả thăm dò gateway được lưu trong bộ nhớ đệm (gateway khỏe tại thời điểm kiểm tra), doctor đối chiếu kết quả đó với cấu hình CLI có thể thấy và ghi chú mọi điểm không khớp. Doctor không khởi động ping embedding mới trên đường dẫn mặc định; dùng lệnh trạng thái bộ nhớ sâu khi bạn muốn kiểm tra nhà cung cấp trực tiếp.
Dùng `openclaw memory status --deep` để xác minh mức sẵn sàng của embedding khi chạy.
</Accordion>
<Accordion title="14. Cảnh báo trạng thái kênh">
Nếu gateway khỏe, doctor chạy thăm dò trạng thái kênh và báo cáo cảnh báo kèm các cách khắc phục được đề xuất.
Nếu gateway khỏe, doctor chạy thăm dò trạng thái kênh và báo cáo cảnh báo kèm các sửa lỗi được đề xuất.
</Accordion>
<Accordion title="15. Kiểm tra cấu hình supervisor + sửa chữa">
Doctor kiểm tra cấu hình supervisor đã cài đặt (launchd/systemd/schtasks) để tìm các mặc định bị thiếu hoặc lỗi thời (ví dụ: phụ thuộc network-online của systemd và độ trễ khởi động lại). Khi tìm thấy điểm không khớp, nó đề xuất cập nhật và có thể ghi lại tệp service/task theo các mặc định hiện tại.
Doctor kiểm tra cấu hình supervisor đã cài đặt (launchd/systemd/schtasks) để tìm các mặc định bị thiếu hoặc đã lỗi thời (ví dụ: phụ thuộc systemd network-online và độ trễ khởi động lại). Khi tìm thấy điểm không khớp, nó đề xuất cập nhật và có thể ghi lại tệp dịch vụ/tác vụ theo các mặc định hiện tại.
Ghi chú:
- `openclaw doctor` hỏi trước khi ghi lại cấu hình supervisor.
- `openclaw doctor` nhắc trước khi ghi lại cấu hình supervisor.
- `openclaw doctor --yes` chấp nhận các lời nhắc sửa chữa mặc định.
- `openclaw doctor --repair` áp dụng các cách khắc phục được đề xuất mà không hỏi.
- `openclaw doctor --repair --force` ghi đè các cấu hình supervisor tùy chỉnh.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` giữ doctor ở chế độ chỉ đọc đối với vòng đời dịch vụ gateway. Nó vẫn báo cáo tình trạng dịch vụ và chạy các sửa chữa không thuộc dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ, ghi lại cấu hình supervisor, và dọn dẹp dịch vụ cũ vì một supervisor bên ngoài sở hữu vòng đời đó.
- Trên Linux, doctor không ghi lại metadata lệnh/entrypoint trong khi unit gateway systemd khớp đang hoạt động. Nó cũng bỏ qua các unit bổ sung giống gateway nhưng không hoạt động và không phải legacy trong quá trình quét dịch vụ trùng lặp để các tệp dịch vụ đi kèm không tạo nhiễu dọn dẹp.
- Nếu xác thực bằng token yêu cầu token và `gateway.auth.token` do SecretRef quản lý, thao tác cài đặt/sửa chữa dịch vụ của doctor xác thực SecretRef nhưng không lưu các giá trị token plaintext đã phân giải vào metadata môi trường dịch vụ supervisor.
- Doctor phát hiện các giá trị môi trường dịch vụ được quản lý bằng `.env`/SecretRef mà các bản cài đặt LaunchAgent, systemd hoặc Windows Scheduled Task cũ đã nhúng inline và ghi lại metadata dịch vụ để các giá trị đó tải từ nguồn runtime thay vì định nghĩa supervisor.
- `openclaw doctor --repair` áp dụng các sửa lỗi được đề xuất mà không cần lời nhắc.
- `openclaw doctor --repair --force` ghi đè cấu hình supervisor tùy chỉnh.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` giữ doctor ở chế độ chỉ đọc cho vòng đời dịch vụ gateway. Nó vẫn báo cáo sức khỏe dịch vụ và chạy các sửa chữa không thuộc dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ, ghi lại cấu hình supervisor, và dọn dẹp dịch vụ cũ vì một supervisor bên ngoài sở hữu vòng đời đó.
- Trên Linux, doctor không ghi lại metadata lệnh/entrypoint khi unit gateway systemd tương ứng đang hoạt động. Nó cũng bỏ qua các unit giống gateway bổ sung không hoạt động và không phải legacy trong quá trình quét dịch vụ trùng lặp để các tệp dịch vụ đồng hành không tạo nhiễu dọn dẹp.
- Nếu xác thực bằng token yêu cầu token và `gateway.auth.token` được quản lý bằng SecretRef, quá trình cài đặt/sửa chữa dịch vụ của doctor xác thực SecretRef nhưng không lưu giá trị token văn bản thuần đã phân giải vào metadata môi trường dịch vụ supervisor.
- Doctor phát hiện các giá trị môi trường dịch vụ được quản lý bằng `.env`/SecretRef mà các bản cài LaunchAgent, systemd, hoặc Windows Scheduled Task cũ đã nhúng inline và ghi lại metadata dịch vụ để các giá trị đó tải từ nguồn runtime thay vì định nghĩa supervisor.
- Doctor phát hiện khi lệnh dịch vụ vẫn ghim `--port` cũ sau khi `gateway.port` thay đổi và ghi lại metadata dịch vụ sang cổng hiện tại.
- Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, doctor chặn đường dẫn cài đặt/sửa chữa kèm hướng dẫn có thể thực hiện.
- Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, doctor chặn đường dẫn cài đặt/sửa chữa kèm hướng dẫn có thể hành động.
- Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, doctor chặn cài đặt/sửa chữa cho đến khi mode được đặt tường minh.
- Với các unit user-systemd trên Linux, kiểm tra drift token của doctor hiện bao gồm cả nguồn `Environment=` và `EnvironmentFile=` khi so sánh metadata xác thực dịch vụ.
- Các sửa chữa dịch vụ của doctor từ chối ghi lại, dừng hoặc khởi động lại dịch vụ gateway từ binary OpenClaw cũ hơn khi cấu hình được ghi lần cuối bởi phiên bản mới hơn. Xem [khắc phục sự cố Gateway](/vi/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Bạn luôn có thể buộc ghi lại toàn bộ bằng `openclaw gateway install --force`.
- Đối với các unit user-systemd trên Linux, kiểm tra trôi lệch token của doctor giờ bao gồm cả nguồn `Environment=` và `EnvironmentFile=` khi so sánh metadata xác thực dịch vụ.
- Sửa chữa dịch vụ của doctor từ chối ghi lại, dừng, hoặc khởi động lại dịch vụ gateway từ binary OpenClaw cũ hơn khi cấu hình được ghi lần cuối bởi phiên bản mới hơn. Xem [Khắc phục sự cố Gateway](/vi/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Bạn luôn có thể buộc ghi lại toàn bộ qua `openclaw gateway install --force`.
</Accordion>
<Accordion title="16. Chẩn đoán runtime Gateway + cổng">
Doctor kiểm tra runtime dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã được cài đặt nhưng thực tế không chạy. Nó cũng kiểm tra xung đột cổng trên cổng gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng xảy ra (gateway đã chạy, đường hầm SSH).
<Accordion title="16. Runtime Gateway + chẩn đoán cổng">
Doctor kiểm tra runtime dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã cài đặt nhưng thực tế không chạy. Nó cũng kiểm tra xung đột cổng trên cổng gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng (gateway đã chạy, đường hầm SSH).
</Accordion>
<Accordion title="17. Thực hành tốt nhất cho runtime Gateway">
Doctor cảnh báo khi dịch vụ gateway chạy trên Bun hoặc đường dẫn Node do trình quản lý phiên bản quản lý (`nvm`, `fnm`, `volta`, `asdf`, v.v.). Các kênh WhatsApp + Telegram yêu cầu Node, và đường dẫn trình quản lý phiên bản có thể hỏng sau khi nâng cấp vì dịch vụ không tải init shell của bạn. Doctor đề xuất chuyển sang bản cài đặt Node hệ thống khi có sẵn (Homebrew/apt/choco).
Doctor cảnh báo khi dịch vụ gateway chạy trên Bun hoặc đường dẫn Node do trình quản lý phiên bản quản lý (`nvm`, `fnm`, `volta`, `asdf`, v.v.). Các kênh WhatsApp + Telegram yêu cầu Node, và đường dẫn trình quản lý phiên bản có thể hỏng sau khi nâng cấp vì dịch vụ không tải init shell của bạn. Doctor đề xuất di chuyển sang bản cài Node hệ thống khi có sẵn (Homebrew/apt/choco).
Các LaunchAgent macOS mới cài đặt hoặc đã sửa chữa dùng PATH hệ thống chuẩn (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) thay vì sao chép PATH của shell tương tác, để Volta, asdf, fnm, pnpm và các thư mục trình quản lý phiên bản khác không thay đổi cách các tiến trình con Node được phân giải. Các dịch vụ Linux vẫn giữ các gốc môi trường tường minh (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) và các thư mục user-bin ổn định, nhưng các thư mục dự phòng trình quản lý phiên bản được suy đoán chỉ được ghi vào PATH dịch vụ khi các thư mục đó tồn tại trên đĩa.
Các macOS LaunchAgent mới được cài đặt hoặc sửa chữa dùng PATH hệ thống chuẩn (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) thay vì sao chép PATH shell tương tác, nên Volta, asdf, fnm, pnpm, và các thư mục trình quản lý phiên bản khác không thay đổi Node mà tiến trình con phân giải. Dịch vụ Linux vẫn giữ các root môi trường tường minh (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) và các thư mục user-bin ổn định, nhưng các thư mục dự phòng trình quản lý phiên bản được đoán chỉ được ghi vào PATH dịch vụ khi các thư mục đó tồn tại trên đĩa.
</Accordion>
<Accordion title="18. Ghi cấu hình + metadata wizard">
Doctor lưu mọi thay đổi cấu hình và đóng dấu metadata wizard để ghi lại lần chạy doctor.
</Accordion>
<Accordion title="19. Mẹo workspace (sao lưu + hệ thống bộ nhớ)">
Doctor đề xuất hệ thống bộ nhớ workspace khi thiếu và in mẹo sao lưu nếu workspace chưa nằm trong git.
Doctor đề xuất một hệ thống bộ nhớ workspace khi thiếu và in mẹo sao lưu nếu workspace chưa nằm trong git.
Xem [/concepts/agent-workspace](/vi/concepts/agent-workspace) để biết hướng dẫn đầy đủ về cấu trúc workspace và sao lưu git (khuyến nghị GitHub hoặc GitLab riêng tư).
Xem [/concepts/agent-workspace](/vi/concepts/agent-workspace) để có hướng dẫn đầy đủ về cấu trúc workspace và sao lưu git (khuyến nghị GitHub hoặc GitLab riêng tư).
</Accordion>
</AccordionGroup>

117
docs/vi/gateway/logging.md
View File

@ -1,103 +1,114 @@
---
read_when:
- Thay đổi đầu ra hoặc định dạng ghi log
- Thay đổi đầu ra hoặc định dạng ghi nhật ký
- Gỡ lỗi đầu ra CLI hoặc Gateway
summary: Các bề mặt ghi nhật ký, nhật ký tệp, kiểu nhật ký WS và định dạng bảng điều khiển
title: Ghi nhật ký Gateway
x-i18n:
generated_at: "2026-05-02T10:42:04Z"
generated_at: "2026-05-05T01:47:02Z"
model: gpt-5.5
provider: openai
source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13
source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246
source_path: gateway/logging.md
workflow: 16
---
# Ghi nhật ký
# Ghi log
Để xem tổng quan hướng tới người dùng (CLI + Giao diện điều khiển + cấu hình), hãy xem [/logging](/vi/logging).
Để xem tổng quan hướng tới người dùng (CLI + Control UI + cấu hình), xem [/logging](/vi/logging).
OpenClaw có hai “bề mặt” nhật ký:
OpenClaw có hai “bề mặt” ghi log:
- **Đầu ra console** (những gì bạn thấy trong terminal / Giao diện gỡ lỗi).
- **Nhật ký tệp** (các dòng JSON) do trình ghi nhật ký Gateway ghi.
- **Đầu ra console** (những gì bạn thấy trong terminal / Debug UI).
- **Nhật ký tệp** (các dòng JSON) do bộ ghi log Gateway ghi lại.
## Trình ghi nhật ký dựa trên tệp
Khi khởi động, Gateway ghi log mô hình agent mặc định đã phân giải cùng với các
mặc định chế độ ảnh hưởng đến phiên mới, ví dụ:
- Tệp nhật ký xoay vòng mặc định nằm dưới `/tmp/openclaw/` (mỗi ngày một tệp): `openclaw-YYYY-MM-DD.log`
- Ngày sử dụng múi giờ cục bộ của máy chủ Gateway.
```text
agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
```
`thinking` đến từ agent mặc định, tham số mô hình, hoặc mặc định agent toàn cục;
khi chưa được đặt, tóm tắt khởi động hiển thị `medium`. `fast` đến từ agent mặc
định hoặc tham số `fastMode` của mô hình.
## Bộ ghi log dựa trên tệp
- Tệp nhật ký xoay vòng mặc định nằm dưới `/tmp/openclaw/` (một tệp mỗi ngày): `openclaw-YYYY-MM-DD.log`
- Ngày dùng múi giờ cục bộ của máy chủ Gateway.
- Các tệp nhật ký đang hoạt động xoay vòng tại `logging.maxFileBytes` (mặc định: 100 MB), giữ
tối đa năm bản lưu trữ được đánh số và tiếp tục ghi vào một tệp hoạt động mới.
- Đường dẫn và cấp độ của tệp nhật ký có thể được cấu hình qua `~/.openclaw/openclaw.json`:
tối đa năm bản lưu trữ được đánh số và tiếp tục ghi một tệp đang hoạt động mới.
- Đường dẫn và mức nhật ký của tệp có thể được cấu hình qua `~/.openclaw/openclaw.json`:
- `logging.file`
- `logging.level`
Định dạng tệp là mỗi dòng một đối tượng JSON.
Thẻ Nhật ký trong Giao diện điều khiển theo dõi tệp này qua Gateway (`logs.tail`).
Thẻ Logs của Control UI tail tệp này qua Gateway (`logs.tail`).
CLI cũng có thể làm tương tự:
```bash
openclaw logs --follow
```
**Chi tiết so với cấp độ nhật ký**
**Chi tiết so với mức nhật ký**
- **Nhật ký tệp** được kiểm soát hoàn toàn bởi `logging.level`.
- `--verbose` chỉ ảnh hưởng đến **độ chi tiết của console** (và kiểu nhật ký WS); nó **không**
nâng cấp độ nhật ký tệp.
- Để ghi các chi tiết chỉ có ở chế độ chi tiết vào nhật ký tệp, hãy đặt `logging.level` thành `debug` hoặc
- **Nhật ký tệp** được kiểm soát riêng bởi `logging.level`.
- `--verbose` chỉ ảnh hưởng đến **độ chi tiết console** (và kiểu log WS); nó **không**
nâng mức nhật ký tệp.
- Để ghi lại các chi tiết chỉ có ở chế độ chi tiết trong nhật ký tệp, đặt `logging.level` thành `debug` hoặc
`trace`.
- Ghi nhật ký trace cũng bao gồm các tóm tắt thời gian chẩn đoán cho một số đường dẫn nóng được chọn,
- Ghi log trace cũng bao gồm các tóm tắt thời gian chẩn đoán cho một số đường dẫn nóng được chọn,
chẳng hạn như chuẩn bị factory công cụ Plugin. Xem
[/tools/plugin#slow-plugin-tool-setup](/vi/tools/plugin#slow-plugin-tool-setup).
## Ghi lại console
## Thu thập console
CLI ghi lại `console.log/info/warn/error/debug/trace` và ghi chúng vào nhật ký tệp,
CLI thu thập `console.log/info/warn/error/debug/trace` và ghi chúng vào nhật ký tệp,
đồng thời vẫn in ra stdout/stderr.
Bạn có thể điều chỉnh độ chi tiết của console một cách độc lập qua:
Bạn có thể điều chỉnh độ chi tiết console độc lập qua:
- `logging.consoleLevel` (mặc định `info`)
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
## Biên tập ẩn
## Biên tập che giấu
OpenClaw có thể che các token nhạy cảm trước khi đầu ra nhật ký hoặc bản ghi phiên rời khỏi
tiến trình. Chính sách biên tập ẩn nhật ký này được áp dụng tại các đích nhận văn bản console,
nhật ký tệp, bản ghi nhật ký OTLP và bản ghi phiên, vì vậy các giá trị bí mật khớp mẫu sẽ được
che trước khi các dòng JSONL hoặc thông điệp được ghi ra đĩa.
OpenClaw có thể che các token nhạy cảm trước khi đầu ra log hoặc transcript rời khỏi
tiến trình. Chính sách biên tập che giấu khi ghi log này được áp dụng tại các đầu nhận văn bản
console, nhật ký tệp, bản ghi log OTLP và transcript phiên, vì vậy các giá trị bí mật khớp
sẽ được che trước khi các dòng JSONL hoặc thông điệp được ghi ra đĩa.
- `logging.redactSensitive`: `off` | `tools` (mặc định: `tools`)
- `logging.redactPatterns`: mảng chuỗi regex (ghi đè mặc định)
- `logging.redactPatterns`: mảng các chuỗi regex (ghi đè mặc định)
- Dùng chuỗi regex thô (tự động `gi`), hoặc `/pattern/flags` nếu bạn cần cờ tùy chỉnh.
- Các phần khớp được che bằng cách giữ 6 ký tự đầu + 4 ký tự cuối (độ dài >= 18), nếu không thì `***`.
- Mặc định bao phủ các phép gán khóa phổ biến, cờ CLI, trường JSON, header bearer, khối PEM, tiền tố token phổ biến, và tên trường thông tin thanh toán như số thẻ, CVC/CVV, token thanh toán dùng chung và thông tin xác thực thanh toán.
- Các kết quả khớp được che bằng cách giữ 6 ký tự đầu + 4 ký tự cuối (độ dài >= 18), nếu không thì `***`.
- Mặc định bao phủ các phép gán khóa phổ biến, cờ CLI, trường JSON, header bearer, khối PEM, tiền tố token phổ biến, và tên trường thông tin thanh toán như số thẻ, CVC/CVV, token thanh toán dùng chung, và thông tin xác thực thanh toán.
Một số ranh giới an toàn luôn biên tập ẩn bất kể `logging.redactSensitive`.
Điều đó bao gồm các sự kiện gọi công cụ của Giao diện điều khiển, đầu ra công cụ
`sessions_history`, bản xuất hỗ trợ chẩn đoán, quan sát lỗi provider, hiển thị lệnh
phê duyệt exec và nhật ký giao thức WebSocket của Gateway. Các bề mặt này vẫn có thể dùng
Một số ranh giới an toàn luôn biên tập che giấu bất kể `logging.redactSensitive`.
Điều đó bao gồm sự kiện gọi công cụ của Control UI, đầu ra công cụ `sessions_history`,
bản xuất hỗ trợ chẩn đoán, quan sát lỗi nhà cung cấp, hiển thị lệnh phê duyệt exec,
và log giao thức WebSocket của Gateway. Các bề mặt này vẫn có thể dùng
`logging.redactPatterns` làm mẫu bổ sung, nhưng `redactSensitive: "off"`
không khiến chúng phát ra bí mật thô.
## Nhật ký WebSocket của Gateway
## Log WebSocket của Gateway
Gateway in nhật ký giao thức WebSocket theo hai chế độ:
Gateway in log giao thức WebSocket ở hai chế độ:
- **Chế độ bình thường (không có `--verbose`)**: chỉ in các kết quả RPC “đáng chú ý”:
- **Chế độ bình thường (không có `--verbose`)**: chỉ các kết quả RPC “đáng chú ý” được in:
- lỗi (`ok=false`)
- lời gọi chậm (ngưỡng mặc định: `>= 50ms`)
- lệnh gọi chậm (ngưỡng mặc định: `>= 50ms`)
- lỗi phân tích cú pháp
- **Chế độ chi tiết (`--verbose`)**: in toàn bộ lưu lượng yêu cầu/phản hồi WS.
### Kiểu nhật ký WS
### Kiểu log WS
`openclaw gateway` hỗ trợ một công tắc kiểu cho từng Gateway:
- `--ws-log auto` (mặc định): chế độ bình thường được tối ưu hóa; chế độ chi tiết dùng đầu ra gọn
- `--ws-log compact`: đầu ra gọn (cặp yêu cầu/phản hồi) khi chi tiết
- `--ws-log auto` (mặc định): chế độ bình thường được tối ưu; chế độ chi tiết dùng đầu ra compact
- `--ws-log compact`: đầu ra compact (yêu cầu/phản hồi theo cặp) khi chi tiết
- `--ws-log full`: đầu ra đầy đủ theo từng frame khi chi tiết
- `--compact`: bí danh cho `--ws-log compact`
@ -114,27 +125,27 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Định dạng console (ghi nhật ký hệ con)
## Định dạng console (ghi log hệ thống con)
Bộ định dạng console **nhận biết TTY** và in các dòng nhất quán, có tiền tố.
Các trình ghi nhật ký hệ con giữ đầu ra được nhóm lại và dễ quét.
Bộ ghi log hệ thống con giữ đầu ra được nhóm và dễ quét.
Hành vi:
- **Tiền tố hệ con** trên mỗi dòng (ví dụ: `[gateway]`, `[canvas]`, `[tailscale]`)
- **Màu hệ con** (ổn định cho từng hệ con) cùng với tô màu theo cấp độ
- **Có màu khi đầu ra là TTY hoặc môi trường trông giống terminal phong phú** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), tôn trọng `NO_COLOR`
- **Tiền tố hệ con rút gọn**: bỏ `gateway/` + `channels/` ở đầu, giữ 2 phân đoạn cuối (ví dụ: `whatsapp/outbound`)
- **Trình ghi nhật ký con theo hệ con** (tự động thêm tiền tố + trường có cấu trúc `{ subsystem }`)
- **Tiền tố hệ thống con** trên mỗi dòng (ví dụ `[gateway]`, `[canvas]`, `[tailscale]`)
- **Màu hệ thống con** (ổn định theo từng hệ thống con) cộng với tô màu theo mức
- **Màu khi đầu ra là TTY hoặc môi trường trông giống terminal giàu tính năng** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), tôn trọng `NO_COLOR`
- **Tiền tố hệ thống con rút gọn**: bỏ `gateway/` + `channels/` ở đầu, giữ 2 phân đoạn cuối (ví dụ `whatsapp/outbound`)
- **Bộ ghi log con theo hệ thống con** (tự động tiền tố + trường có cấu trúc `{ subsystem }`)
- **`logRaw()`** cho đầu ra QR/UX (không tiền tố, không định dạng)
- **Kiểu console** (ví dụ: `pretty | compact | json`)
- **Cấp độ nhật ký console** tách biệt với cấp độ nhật ký tệp (tệp giữ đầy đủ chi tiết khi `logging.level` được đặt thành `debug`/`trace`)
- **Nội dung thông điệp WhatsApp** được ghi ở `debug` (dùng `--verbose` để xem)
- **Kiểu console** (ví dụ `pretty | compact | json`)
- **Mức nhật ký console** tách biệt với mức nhật ký tệp (tệp giữ đầy đủ chi tiết khi `logging.level` được đặt thành `debug`/`trace`)
- **Nội dung thân thông điệp WhatsApp** được ghi log ở `debug` (dùng `--verbose` để xem)
Điều này giữ nhật ký tệp hiện có ổn định đồng thời làm cho đầu ra tương tác dễ quét.
## Liên quan
- [Ghi nhật ký](/vi/logging)
- [Ghi log](/vi/logging)
- [Xuất OpenTelemetry](/vi/gateway/opentelemetry)
- [Xuất chẩn đoán](/vi/gateway/diagnostics)

172
docs/vi/help/debugging.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Bạn cần kiểm tra đầu ra thô của mô hình để phát hiện rò rỉ nội dung lập luận
- Bạn muốn chạy Gateway ở chế độ theo dõi trong quá trình phát triển lặp lại
- Bạn cần kiểm tra đầu ra thô của mô hình để phát hiện rò rỉ nội dung suy luận
- Bạn muốn chạy Gateway ở chế độ theo dõi trong khi liên tục chỉnh sửa
- Bạn cần một quy trình gỡ lỗi có thể lặp lại
summary: 'Công cụ gỡ lỗi: chế độ theo dõi, luồng thô từ mô hình và truy vết rò rỉ lập luận'
summary: 'Công cụ gỡ lỗi: chế độ theo dõi, luồng mô hình thô và truy vết rò rỉ suy luận'
title: Gỡ lỗi
x-i18n:
generated_at: "2026-05-03T21:33:06Z"
generated_at: "2026-05-05T01:47:40Z"
model: gpt-5.5
provider: openai
source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc
source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec
source_path: help/debugging.md
workflow: 16
---
Trình trợ giúp gỡ lỗi cho đầu ra phát trực tuyến, đặc biệt khi một nhà cung cấp trộn phần lập luận vào văn bản thông thường.
Các trình trợ giúp gỡ lỗi cho đầu ra phát trực tuyến, đặc biệt khi một nhà cung cấp trộn phần suy luận vào văn bản thông thường.
## Ghi đè gỡ lỗi thời gian chạy
## Ghi đè gỡ lỗi runtime
Dùng `/debug` trong chat để đặt các ghi đè cấu hình **chỉ trong thời gian chạy** (trong bộ nhớ, không ghi ra đĩa).
Dùng `/debug` trong cuộc trò chuyện để đặt ghi đè cấu hình **chỉ runtime** (bộ nhớ, không ghi ra ổ đĩa).
`/debug` bị tắt theo mặc định; bật bằng `commands.debug: true`.
Điều này hữu ích khi bạn cần bật/tắt các thiết lập khó thấy mà không chỉnh sửa `openclaw.json`.
Điều này hữu ích khi bạn cần bật/tắt các thiết lập ít gặp mà không chỉnh sửa `openclaw.json`.
Ví dụ:
@ -31,12 +31,12 @@ Ví dụ:
/debug reset
```
`/debug reset` xóa toàn bộ ghi đè và quay lại cấu hình trên đĩa.
`/debug reset` xóa tất cả ghi đè và quay lại cấu hình trên ổ đĩa.
## Đầu ra trace phiên
Dùng `/trace` khi bạn muốn xem các dòng trace/gỡ lỗi do Plugin sở hữu trong một phiên
mà không bật toàn bộ chế độ verbose.
mà không bật toàn bộ chế độ chi tiết.
Ví dụ:
@ -46,16 +46,16 @@ Ví dụ:
/trace off
```
Dùng `/trace` cho chẩn đoán Plugin, chẳng hạn như tóm tắt gỡ lỗi Active Memory.
Tiếp tục dùng `/verbose` cho đầu ra trạng thái/công cụ verbose thông thường, và tiếp tục dùng
`/debug` cho ghi đè cấu hình chỉ trong thời gian chạy.
Dùng `/trace` cho chẩn đoán Plugin, chẳng hạn như bản tóm tắt gỡ lỗi Active Memory.
Tiếp tục dùng `/verbose` cho đầu ra trạng thái/công cụ chi tiết thông thường, và tiếp tục dùng
`/debug` cho ghi đè cấu hình chỉ runtime.
## Trace vòng đời Plugin
Dùng `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` khi các lệnh vòng đời Plugin có vẻ chậm
và bạn cần phần phân tích pha tích hợp sẵn cho siêu dữ liệu Plugin, khám phá, registry,
runtime mirror, thay đổi cấu hình, và công việc làm mới. Trace là tùy chọn bật và ghi
vào stderr, nên đầu ra lệnh JSON vẫn có thể phân tích được.
và bạn cần phân tích giai đoạn tích hợp sẵn cho siêu dữ liệu Plugin, khám phá, registry,
runtime mirror, biến đổi cấu hình, và công việc làm mới. Trace là tùy chọn bật và ghi
vào stderr, vì vậy đầu ra lệnh JSON vẫn phân tích được.
Ví dụ:
@ -71,14 +71,14 @@ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
```
Dùng mục này để điều tra vòng đời Plugin trước khi dùng tới trình phân tích CPU.
Nếu lệnh đang chạy từ một checkout mã nguồn, nên đo runtime đã build
Dùng phần này để điều tra vòng đời Plugin trước khi dùng đến trình định hình CPU.
Nếu lệnh đang chạy từ một checkout mã nguồn, hãy ưu tiên đo runtime đã build
bằng `node dist/entry.js ...` sau `pnpm build`; `pnpm openclaw ...`
cũng đo cả chi phí phụ của trình chạy mã nguồn.
cũng đo cả chi phí của source-runner.
## Khởi động CLI và lập hồ sơ lệnh
## Khởi động CLI và định hình lệnh
Dùng benchmark khởi động đã được đưa vào kho khi một lệnh có vẻ chậm:
Dùng benchmark khởi động đã được đưa vào repo khi một lệnh có vẻ chậm:
```bash
pnpm test:startup:bench:smoke
@ -86,15 +86,25 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
```
Để lập hồ sơ một lần thông qua trình chạy mã nguồn thông thường, đặt
Để định hình một lần qua source runner thông thường, đặt
`OPENCLAW_RUN_NODE_CPU_PROF_DIR`:
```bash
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```
Trình chạy mã nguồn thêm các cờ hồ sơ CPU của Node và ghi một `.cpuprofile` cho
lệnh. Dùng cách này trước khi thêm công cụ đo tạm thời vào mã lệnh.
Source runner thêm các cờ hồ sơ CPU của Node và ghi một `.cpuprofile` cho
lệnh. Dùng cách này trước khi thêm instrumentation tạm thời vào mã lệnh.
Với các điểm nghẽn khởi động trông giống công việc hệ thống tệp đồng bộ hoặc module-loader,
hãy thêm cờ trace I/O đồng bộ của Node thông qua source runner:
```bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```
`pnpm gateway:watch` bật cờ này theo mặc định cho tiến trình Gateway con được theo dõi.
Đặt `OPENCLAW_TRACE_SYNC_IO=0` để chặn đầu ra trace I/O đồng bộ của Node ở chế độ watch.
## Chế độ watch của Gateway
@ -104,17 +114,17 @@ lệnh. Dùng cách này trước khi thêm công cụ đo tạm thời vào mã
pnpm gateway:watch
```
Theo mặc định, lệnh này khởi động hoặc khởi động lại một phiên tmux tên là
`openclaw-gateway-watch-main` (hoặc một biến thể theo hồ sơ/cổng như
`openclaw-gateway-watch-dev-19001`) và tự động attach từ terminal tương tác.
Shell không tương tác, CI, và các lệnh thực thi của agent sẽ tiếp tục tách rời và in
hướng dẫn attach thay thế. Attach thủ công khi cần:
Theo mặc định, lệnh này khởi động hoặc khởi động lại một phiên tmux có tên
`openclaw-gateway-watch-main` (hoặc một biến thể theo profile/cổng cụ thể như
`openclaw-gateway-watch-dev-19001`) và tự động đính kèm từ terminal tương tác.
Shell không tương tác, CI, và các lệnh exec của agent vẫn tách rời và in hướng dẫn
đính kèm thay thế. Đính kèm thủ công khi cần:
```bash
tmux attach -t openclaw-gateway-watch-main
```
Pane tmux chạy trình watch thô:
Pane tmux chạy watcher thô:
```bash
node scripts/watch-node.mjs gateway --force
@ -124,24 +134,24 @@ Dùng chế độ foreground khi không muốn dùng tmux:
```bash
pnpm gateway:watch:raw
# or
# hoặc
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```
Tắt auto-attach trong khi vẫn giữ quản lý tmux:
Tắt tự động đính kèm trong khi vẫn giữ quản lý tmux:
```bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```
Lập hồ sơ thời gian CPU của Gateway được watch khi gỡ lỗi các điểm nóng khởi động/runtime:
Định hình thời gian CPU của Gateway được watch khi gỡ lỗi các điểm nóng khởi động/runtime:
```bash
pnpm gateway:watch --benchmark
```
Wrapper watch tiêu thụ `--benchmark` trước khi gọi Gateway và ghi
một `.cpuprofile` V8 cho mỗi lần tiến trình con Gateway thoát dưới
Watch wrapper tiêu thụ `--benchmark` trước khi gọi Gateway và ghi
một `.cpuprofile` V8 cho mỗi lần tiến trình Gateway con thoát dưới
`.artifacts/gateway-watch-profiles/`. Dừng hoặc khởi động lại gateway được watch để
flush hồ sơ hiện tại, rồi mở bằng Chrome DevTools hoặc Speedscope:
@ -150,42 +160,48 @@ npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```
Dùng `--benchmark-dir <path>` khi bạn muốn đặt hồ sơ ở nơi khác.
Dùng `--benchmark-no-force` khi bạn muốn tiến trình con được benchmark bỏ qua thao tác dọn cổng `--force` mặc định và thất bại nhanh nếu cổng Gateway đã được dùng.
Dùng `--benchmark-no-force` khi bạn muốn tiến trình con được benchmark bỏ qua bước
dọn dẹp cổng `--force` mặc định và lỗi nhanh nếu cổng Gateway đã được sử dụng.
Chế độ benchmark chặn nhiễu trace sync-I/O theo mặc định. Đặt
`OPENCLAW_TRACE_SYNC_IO=1` cùng `--benchmark` khi bạn chủ động muốn cả hồ sơ CPU
và stack trace sync-I/O của Node. Ở chế độ benchmark, các khối trace đó
được ghi vào `gateway-watch-output.log` trong thư mục benchmark và
được lọc khỏi pane terminal; nhật ký Gateway thông thường vẫn hiển thị.
Wrapper tmux mang các bộ chọn runtime phổ biến không phải bí mật như
Tmux wrapper mang các bộ chọn runtime không bí mật phổ biến như
`OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`,
`OPENCLAW_GATEWAY_PORT`, và `OPENCLAW_SKIP_CHANNELS` vào pane. Đặt
thông tin xác thực nhà cung cấp trong hồ sơ/cấu hình thông thường của bạn, hoặc dùng chế độ foreground thô
cho bí mật tạm thời dùng một lần.
Nếu Gateway được watch thoát trong khi khởi động, trình watch chạy
`openclaw doctor --fix --non-interactive` một lần và khởi động lại tiến trình con Gateway.
thông tin xác thực nhà cung cấp trong profile/cấu hình thông thường của bạn, hoặc dùng chế độ foreground thô
cho các bí mật tạm thời dùng một lần.
Nếu Gateway được watch thoát trong lúc khởi động, watcher chạy
`openclaw doctor --fix --non-interactive` một lần và khởi động lại tiến trình Gateway con.
Dùng `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` khi bạn muốn lỗi khởi động ban đầu
mà không có lượt sửa chữa chỉ dành cho dev.
Pane tmux được quản lý cũng mặc định dùng log Gateway có màu để dễ đọc;
mà không có lượt sửa chỉ dành cho dev.
Pane tmux được quản lý cũng mặc định dùng nhật ký Gateway có màu để dễ đọc;
đặt `FORCE_COLOR=0` khi khởi động `pnpm gateway:watch` để tắt đầu ra ANSI.
Trình watch khởi động lại khi có các tệp liên quan đến build trong `src/`, tệp nguồn phần mở rộng,
siêu dữ liệu `package.json` và `openclaw.plugin.json` của phần mở rộng, `tsconfig.json`,
`package.json`, và `tsdown.config.ts`. Thay đổi siêu dữ liệu phần mở rộng khởi động lại
gateway mà không buộc rebuild `tsdown`; thay đổi nguồn và cấu hình vẫn
Watcher khởi động lại khi có thay đổi ở các tệp liên quan đến build trong `src/`, tệp mã nguồn extension,
siêu dữ liệu `package.json` và `openclaw.plugin.json` của extension, `tsconfig.json`,
`package.json`, và `tsdown.config.ts`. Thay đổi siêu dữ liệu extension khởi động lại
gateway mà không ép rebuild `tsdown`; thay đổi mã nguồn và cấu hình vẫn
rebuild `dist` trước.
Thêm bất kỳ cờ CLI gateway nào sau `gateway:watch` và chúng sẽ được truyền tiếp trong
Thêm bất kỳ cờ CLI gateway nào sau `gateway:watch` và chúng sẽ được truyền qua trong
mỗi lần khởi động lại. Chạy lại cùng lệnh watch sẽ respawn pane tmux đã đặt tên, và
trình watch thô vẫn giữ khóa một trình watch duy nhất nên các tiến trình cha watch trùng lặp
sẽ được thay thế thay vì chồng chất.
watcher thô vẫn giữ khóa một watcher duy nhất để các watcher parent trùng lặp
được thay thế thay vì tích tụ.
## Hồ sơ dev + gateway dev (--dev)
## Profile dev + gateway dev (--dev)
Dùng hồ sơ dev để cô lập trạng thái và dựng một thiết lập an toàn, dùng xong bỏ để
Dùng profile dev để cô lập trạng thái và khởi động một thiết lập an toàn, dùng xong bỏ để
gỡ lỗi. Có **hai** cờ `--dev`:
- **`--dev` toàn cục (hồ sơ):** cô lập trạng thái dưới `~/.openclaw-dev` và
đặt cổng gateway mặc định là `19001` (các cổng dẫn xuất dịch chuyển theo).
- **`gateway --dev`: báo cho Gateway tự tạo cấu hình mặc định +
- **`--dev` toàn cục (profile):** cô lập trạng thái dưới `~/.openclaw-dev` và
mặc định cổng gateway là `19001` (các cổng dẫn xuất dịch chuyển theo).
- **`gateway --dev`: yêu cầu Gateway tự động tạo cấu hình mặc định +
workspace** khi thiếu (và bỏ qua BOOTSTRAP.md).
Luồng khuyến nghị (hồ sơ dev + bootstrap dev):
Luồng khuyến nghị (profile dev + bootstrap dev):
```bash
pnpm gateway:dev
@ -194,31 +210,31 @@ OPENCLAW_PROFILE=dev openclaw tui
Nếu bạn chưa có bản cài đặt toàn cục, chạy CLI qua `pnpm openclaw ...`.
Việc này thực hiện:
Những gì thao tác này thực hiện:
1. **Cô lập hồ sơ** (`--dev` toàn cục)
1. **Cô lập profile** (`--dev` toàn cục)
- `OPENCLAW_PROFILE=dev`
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001` (trình duyệt/canvas dịch chuyển tương ứng)
- `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas dịch chuyển tương ứng)
2. **Bootstrap dev** (`gateway --dev`)
- Ghi một cấu hình tối thiểu nếu thiếu (`gateway.mode=local`, bind loopback).
- Ghi cấu hình tối thiểu nếu thiếu (`gateway.mode=local`, bind loopback).
- Đặt `agent.workspace` thành workspace dev.
- Đặt `agent.skipBootstrap=true` (không có BOOTSTRAP.md).
- Seed các tệp workspace nếu thiếu:
`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`.
- Danh tính mặc định: **C3‑PO** (droid giao thức).
- Bỏ qua nhà cung cấp kênh trong chế độ dev (`OPENCLAW_SKIP_CHANNELS=1`).
- Danh tính mặc định: **C3‑PO** (protocol droid).
- Bỏ qua các nhà cung cấp kênh ở chế độ dev (`OPENCLAW_SKIP_CHANNELS=1`).
Luồng đặt lại (bắt đầu mới):
Luồng reset (khởi đầu mới):
```bash
pnpm gateway:dev:reset
```
<Note>
`--dev` là cờ hồ sơ **toàn cục** và bị một số trình chạy tiêu thụ. Nếu bạn cần viết rõ ra, dùng dạng biến môi trường:
`--dev` là cờ profile **toàn cục** và bị một số runner tiêu thụ. Nếu bạn cần viết rõ ra, hãy dùng dạng biến môi trường:
```bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
@ -227,10 +243,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
</Note>
`--reset` xóa cấu hình, thông tin xác thực, phiên, và workspace dev (dùng
`trash`, không dùng `rm`), rồi tạo lại thiết lập dev mặc định.
`trash`, không phải `rm`), rồi tạo lại thiết lập dev mặc định.
<Tip>
Nếu một gateway không phải dev đã chạy (launchd hoặc systemd), hãy dừng nó trước:
Nếu một gateway không phải dev đang chạy (launchd hoặc systemd), hãy dừng nó trước:
```bash
openclaw gateway stop
@ -238,11 +254,11 @@ openclaw gateway stop
</Tip>
## Ghi log luồng thô (OpenClaw)
## Ghi nhật ký raw stream (OpenClaw)
OpenClaw có thể ghi log **luồng assistant thô** trước mọi bước lọc/định dạng.
Đây là cách tốt nhất để xem liệu phần lập luận có đang đến dưới dạng delta văn bản thuần
(hay dưới dạng các khối suy nghĩ riêng biệt) hay không.
OpenClaw có thể ghi nhật ký **raw assistant stream** trước mọi bước lọc/định dạng.
Đây là cách tốt nhất để xem liệu phần suy luận đang đến dưới dạng plain text deltas
(hay dưới dạng các thinking block riêng).
Bật qua CLI:
@ -256,7 +272,7 @@ Ghi đè đường dẫn tùy chọn:
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```
Biến môi trường tương đương:
Các biến môi trường tương đương:
```bash
OPENCLAW_RAW_STREAM=1
@ -267,9 +283,9 @@ Tệp mặc định:
`~/.openclaw/logs/raw-stream.jsonl`
## Ghi log chunk thô (pi-mono)
## Ghi nhật ký raw chunk (pi-mono)
Để thu thập **chunk tương thích OpenAI thô** trước khi chúng được phân tích thành khối,
Để ghi lại **raw OpenAI-compat chunks** trước khi chúng được phân tích thành các khối,
pi-mono cung cấp một logger riêng:
```bash
@ -286,14 +302,14 @@ Tệp mặc định:
`~/.pi-mono/logs/raw-openai-completions.jsonl`
> Lưu ý: mục này chỉ được phát ra bởi các tiến trình dùng nhà cung cấp
> Lưu ý: phần này chỉ được phát ra bởi các tiến trình dùng nhà cung cấp
> `openai-completions` của pi-mono.
## Ghi chú an toàn
- Log luồng thô có thể bao gồm toàn bộ prompt, đầu ra công cụ, và dữ liệu người dùng.
- Giữ log ở máy cục bộ và xóa chúng sau khi gỡ lỗi.
- Nếu bạn chia sẻ log, hãy xóa bí mật và PII trước.
- Nhật ký raw stream có thể bao gồm toàn bộ prompt, đầu ra công cụ, và dữ liệu người dùng.
- Giữ nhật ký cục bộ và xóa chúng sau khi gỡ lỗi.
- Nếu bạn chia sẻ nhật ký, hãy loại bỏ bí mật và PII trước.
## Liên quan

287
docs/vi/help/faq-models.md
View File

@ -1,58 +1,58 @@
---
read_when:
- Chọn hoặc chuyển đổi mô hình, cấu hình bí danh
- Gỡ lỗi chuyển đổi dự phòng mô hình / "Tất cả mô hình đều thất bại"
- Tìm hiểu hồ sơ xác thực và cách quản lý chúng
- Gỡ lỗi chuyển đổi dự phòng mô hình / "Tất cả mô hình đều không thành công"
- Hiểu về hồ sơ xác thực và cách quản lý chúng
sidebarTitle: Models FAQ
summary: 'Câu hỏi thường gặp: giá trị mặc định của mô hình, lựa chọn, bí danh, chuyển đổi, chuyển đổi dự phòng và hồ sơ xác thực'
title: 'Câu hỏi thường gặp: mô hình và xác thực'
x-i18n:
generated_at: "2026-05-02T10:44:06Z"
generated_at: "2026-05-05T01:47:49Z"
model: gpt-5.5
provider: openai
source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54
source_path: help/faq-models.md
workflow: 16
---
Hỏi đáp về mô hình và hồ sơ xác thực. Để thiết lập, phiên, Gateway, kênh và
khắc phục sự cố, xem [Câu hỏi thường gặp](/vi/help/faq) chính.
Câu hỏi thường gặp về mô hình và hồ sơ xác thực. Để biết cách thiết lập, phiên, gateway, kênh và
khắc phục sự cố, hãy xem [FAQ](/vi/help/faq) chính.
## Mô hình: mặc định, lựa chọn, bí danh, chuyển đổi
## Mô hình: mặc định, lựa chọn, alias, chuyển đổi
<AccordionGroup>
<Accordion title='“Mô hình mặc định” là gì?'>
Mô hình mặc định của OpenClaw là bất kỳ mô hình nào bạn đặt làm:
<Accordion title='“mô hình mặc định” là gì?'>
Mô hình mặc định của OpenClaw là bất cứ giá trị nào bạn đặt tại:
```
agents.defaults.model.primary
```
Mô hình được tham chiếu dưới dạng `provider/model` (ví dụ: `openai/gpt-5.5` hoặc `openai-codex/gpt-5.5`). Nếu bạn bỏ qua nhà cung cấp, OpenClaw trước tiên sẽ thử một bí danh, sau đó là một kết quả khớp duy nhất với nhà cung cấp đã cấu hình cho đúng id mô hình đó, và chỉ sau đó mới quay về nhà cung cấp mặc định đã cấu hình như một đường dẫn tương thích đã lỗi thời. 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 cấu hình đầu tiên thay vì hiển thị một mặc định nhà cung cấp đã bị loại bỏ và không còn hợp lệ. Bạn vẫn nên đặt `provider/model` một cách **rõ ràng**.
Mô hình được tham chiếu dưới dạng `provider/model` (ví dụ: `openai/gpt-5.5` hoặc `openai-codex/gpt-5.5`). Nếu bạn bỏ qua provider, OpenClaw trước tiên sẽ thử một alias, sau đó là một kết quả khớp provider đã cấu hình duy nhất cho đúng model id đó, và chỉ sau đó mới dùng provider mặc định đã cấu hình làm đường tương thích đã lỗi thời. Nếu provider đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw sẽ chuyển sang provider/mô hình đã cấu hình đầu tiên thay vì hiển thị một mặc định provider cũ đã bị loại bỏ. Bạn vẫn nên đặt `provider/model` **một cách rõ ràng**.
</Accordion>
<Accordion title="Bạn đề xuất mô hình nào?">
**Mặc định được đề xuất:** dùng mô hình thế hệ mới nhất mạnh nhất có trong ngăn xếp nhà cung cấp của bạn.
**Với tác nhân có bật công cụ hoặc đầu vào không đáng tin cậy:** ưu tiên sức mạnh mô hình hơn chi phí.
**Với trò chuyện thường lệ/rủi ro thấp:** dùng các mô hình dự phòng rẻ hơn và định tuyến theo vai trò tác nhân.
<Accordion title="Bạn khuyến nghị mô hình nào?">
**Mặc định khuyến nghị:** dùng mô hình thế hệ mới nhất mạnh nhất có sẵn trong bộ provider của bạn.
**Với agent có bật công cụ hoặc nhận đầu vào không đáng tin cậy:** ưu tiên sức mạnh mô hình hơn chi phí.
**Với trò chuyện thường nhật/rủi ro thấp:** dùng các mô hình dự phòng rẻ hơn và định tuyến theo vai trò agent.
MiniMax có tài liệu riêng: [MiniMax](/vi/providers/minimax) và
[Mô hình cục bộ](/vi/gateway/local-models).
Quy tắc kinh nghiệm: dùng **mô hình tốt nhất bạn có thể chi trả** cho công việc quan trọng, và một mô hình rẻ hơn
cho trò chuyện thường lệ hoặc tóm tắt. Bạn có thể định tuyến mô hình theo từng tác nhân và dùng tác nhân phụ để
song song hóa các tác vụ dài (mỗi tác nhân phụ tiêu thụ token). Xem [Mô hình](/vi/concepts/models) và
[Tác nhân phụ](/vi/tools/subagents).
Quy tắc kinh nghiệm: dùng **mô hình tốt nhất bạn có thể chi trả** cho công việc rủi ro cao, và một mô hình rẻ hơn
cho trò chuyện thường nhật hoặc tóm tắt. Bạn có thể định tuyến mô hình theo từng agent và dùng sub-agent để
song song hóa các tác vụ dài (mỗi sub-agent tiêu thụ token). Xem [Mô hình](/vi/concepts/models) và
[Sub-agent](/vi/tools/subagents).
Cảnh báo mạnh: các mô hình yếu hơn/bị lượng tử hóa quá mức dễ bị prompt
Cảnh báo nghiêm túc: các mô hình yếu hơn/bị lượng tử hóa quá mức dễ bị prompt
injection và hành vi không an toàn hơn. Xem [Bảo mật](/vi/gateway/security).
Bối cảnh thêm: [Mô hình](/vi/concepts/models).
Ngữ cảnh bổ sung: [Mô hình](/vi/concepts/models).
</Accordion>
<Accordion title="Làm sao để chuyển mô hình mà không xóa sạch cấu hình?">
<Accordion title="Làm thế nào để chuyển mô hình mà không xóa cấu hình?">
Dùng **lệnh mô hình** hoặc chỉ chỉnh sửa các trường **model**. Tránh thay thế toàn bộ cấu hình.
Các lựa chọn an toàn:
@ -63,7 +63,7 @@ x-i18n:
- chỉnh sửa `agents.defaults.model` trong `~/.openclaw/openclaw.json`
Tránh dùng `config.apply` với một đối tượng một phần trừ khi bạn có ý định thay thế toàn bộ cấu hình.
Với chỉnh sửa RPC, trước tiên hãy kiểm tra bằng `config.schema.lookup` và ưu tiên `config.patch`. Payload tra cứu cung cấp cho bạn đường dẫn đã chuẩn hóa, tài liệu/ràng buộc schema nông, và tóm tắt con trực tiếp.
Với chỉnh sửa RPC, trước tiên hãy kiểm tra bằng `config.schema.lookup` và ưu tiên `config.patch`. Payload tra cứu cung cấp cho bạn đường dẫn đã chuẩn hóa, tài liệu/ràng buộc schema nông, và tóm tắt các con trực tiếp.
cho các cập nhật một phần.
Nếu bạn đã ghi đè cấu hình, hãy khôi phục từ bản sao lưu hoặc chạy lại `openclaw doctor` để sửa chữa.
@ -71,41 +71,41 @@ x-i18n:
</Accordion>
<Accordion title="Tôi có thể dùng mô hình tự lưu trữ (llama.cpp, vLLM, Ollama) không?">
Có. Ollama là đường dẫn dễ nhất cho mô hình cục bộ.
<Accordion title="Tôi có thể dùng mô hình tự host (llama.cpp, vLLM, Ollama) không?">
Có. Ollama là cách dễ nhất cho mô hình cục bộ.
Thiết lập nhanh nhất:
1. Cài Ollama từ `https://ollama.com/download`
2. Kéo một mô hình cục bộ như `ollama pull gemma4`
3. Nếu bạn cũng muốn dùng mô hình đám mây, chạy `ollama signin`
1. Cài đặt Ollama từ `https://ollama.com/download`
2. Tải một mô hình cục bộ như `ollama pull gemma4`
3. Nếu bạn cũng muốn dùng mô hình cloud, chạy `ollama signin`
4. Chạy `openclaw onboard` và chọn `Ollama`
5. Chọn `Local` hoặc `Cloud + Local`
Ghi chú:
- `Cloud + Local` cho bạn mô hình đám mây cùng với các mô hình Ollama cục bộ của bạn
- các mô hình đám mây như `kimi-k2.5:cloud` không cần kéo cục bộ
- `Cloud + Local` cung cấp cho bạn mô hình cloud cùng các mô hình Ollama cục bộ
- các mô hình cloud như `kimi-k2.5:cloud` không cần tải cục bộ
- để chuyển thủ công, dùng `openclaw models list` và `openclaw models set ollama/<model>`
Ghi chú bảo mật: mô hình nhỏ hơn hoặc bị lượng tử hóa nặng dễ bị prompt
injection hơn. Chúng tôi đặc biệt khuyến nghị **mô hình lớn** cho bất kỳ bot nào có thể dùng công cụ.
Nếu bạn vẫn muốn dùng mô hình nhỏ, hãy bật sandboxing và danh sách cho phép công cụ nghiêm ngặt.
Ghi chú bảo mật: các mô hình nhỏ hơn hoặc bị lượng tử hóa mạnh dễ bị prompt
injection hơn. Chúng tôi khuyến nghị mạnh mẽ dùng **mô hình lớn** cho mọi bot có thể dùng công cụ.
Nếu bạn vẫn muốn dùng mô hình nhỏ, hãy bật sandboxing và allowlist công cụ nghiêm ngặt.
Tài liệu: [Ollama](/vi/providers/ollama), [Mô hình cục bộ](/vi/gateway/local-models),
[Nhà cung cấp mô hình](/vi/concepts/model-providers), [Bảo mật](/vi/gateway/security),
[Provider mô hình](/vi/concepts/model-providers), [Bảo mật](/vi/gateway/security),
[Sandboxing](/vi/gateway/sandboxing).
</Accordion>
<Accordion title="OpenClaw, Flawd và Krill dùng mô hình nào?">
- Các triển khai này có thể khác nhau và có thể thay đổi theo thời gian; không có đề xuất nhà cung cấp cố định.
- Các triển khai này có thể khác nhau và có thể thay đổi theo thời gian; không có khuyến nghị provider cố định.
- Kiểm tra thiết lập runtime hiện tại trên từng gateway bằng `openclaw models status`.
- Với tác nhân nhạy cảm về bảo mật/có bật công cụ, hãy dùng mô hình thế hệ mới nhất mạnh nhất có sẵn.
- Với agent nhạy cảm về bảo mật/có bật công cụ, hãy dùng mô hình thế hệ mới nhất mạnh nhất có sẵn.
</Accordion>
<Accordion title="Làm sao để chuyển mô hình tức thì (không cần khởi động lại)?">
<Accordion title="Làm thế nào để chuyển mô hình ngay lập tức (không cần khởi động lại)?">
Dùng lệnh `/model` như một tin nhắn độc lập:
```
@ -118,56 +118,56 @@ x-i18n:
/model gemini-flash-lite
```
Đây là các bí danh tích hợp. Có thể thêm bí danh tùy chỉnh qua `agents.defaults.models`.
Đây là các alias tích hợp sẵn. Có thể thêm alias tùy chỉnh qua `agents.defaults.models`.
Bạn có thể liệt kê các mô hình khả dụng bằng `/model`, `/model list`, hoặc `/model status`.
Bạn có thể liệt kê các mô hình có sẵn bằng `/model`, `/model list`, hoặc `/model status`.
`/model` (và `/model list`) hiển thị một bộ chọn ngắn gọn, có đánh số. Chọn theo số:
`/model` (và `/model list`) hiển thị bộ chọn ngắn gọn, có đánh số. Chọn theo số:
```
/model 3
```
Bạn cũng có thể buộc dùng một hồ sơ xác thực cụ thể cho nhà cung cấp (theo từng phiên):
Bạn cũng có thể ép một hồ sơ xác thực cụ thể cho provider (theo từng phiên):
```
/model opus@anthropic:default
/model opus@anthropic:work
```
Mẹo: `/model status` hiển thị tác nhân nào đang hoạt động, tệp `auth-profiles.json` nào đang được dùng, và hồ sơ xác thực nào sẽ được thử tiếp theo.
Nó cũng hiển thị endpoint nhà cung cấp đã cấu hình (`baseUrl`) và chế độ API (`api`) khi có.
Mẹo: `/model status` hiển thị agent nào đang hoạt động, tệp `auth-profiles.json` nào đang được dùng, và hồ sơ xác thực nào sẽ được thử tiếp theo.
Nó cũng hiển thị endpoint provider đã cấu hình (`baseUrl`) và chế độ API (`api`) khi có sẵn.
**Làm sao để bỏ ghim một hồ sơ tôi đã đặt bằng @profile?**
**Làm thế nào để bỏ ghim một hồ sơ tôi đã đặt bằng @profile?**
Chạy lại `/model` **không có** hậu tố `@profile`:
Chạy lại `/model` **không kèm** hậu tố `@profile`:
```
/model anthropic/claude-opus-4-6
```
Nếu bạn muốn quay về mặc định, hãy chọn nó từ `/model` (hoặc gửi `/model <default provider/model>`).
Nếu bạn muốn quay lại mặc định, hãy chọn nó từ `/model` (hoặc gửi `/model <default provider/model>`).
Dùng `/model status` để xác nhận hồ sơ xác thực nào đang hoạt động.
</Accordion>
<Accordion title="Tôi có thể dùng GPT 5.5 cho tác vụ hằng ngày và Codex 5.5 cho lập trình không?">
Có. Hãy xem lựa chọn mô hình và lựa chọn runtime là hai việc riêng biệt:
Có. Hãy xử lý lựa chọn mô hình và lựa chọn runtime riêng biệt:
- **Tác nhân lập trình Codex gốc:** đặt `agents.defaults.model.primary` thành `openai/gpt-5.5` và `agents.defaults.agentRuntime.id` thành `"codex"`. Đăng nhập bằng `openclaw models auth login --provider openai-codex` khi bạn muốn xác thực thuê bao ChatGPT/Codex.
- **Tác vụ OpenAI API trực tiếp thông qua PI:** dùng `/model openai/gpt-5.5` mà không ghi đè runtime Codex và cấu hình `OPENAI_API_KEY`.
- **Codex OAuth thông qua PI:** chỉ dùng `/model openai-codex/gpt-5.5` khi bạn cố ý muốn trình chạy PI thông thường với Codex OAuth.
- **Tác nhân phụ:** định tuyến tác vụ lập trình đến một tác nhân chỉ dùng Codex với mô hình riêng và mặc định `agentRuntime` riêng.
- **Agent lập trình Codex gốc:** đặt `agents.defaults.model.primary` thành `openai/gpt-5.5` và `agents.defaults.agentRuntime.id` thành `"codex"`. Đăng nhập bằng `openclaw models auth login --provider openai-codex` khi bạn muốn xác thực bằng gói đăng ký ChatGPT/Codex.
- **Tác vụ OpenAI API trực tiếp qua PI:** dùng `/model openai/gpt-5.5` mà không ghi đè runtime Codex và cấu hình `OPENAI_API_KEY`.
- **Codex OAuth qua PI:** chỉ dùng `/model openai-codex/gpt-5.5` khi bạn cố ý muốn runner PI bình thường với Codex OAuth.
- **Sub-agent:** định tuyến tác vụ lập trình tới một agent chỉ dùng Codex với mô hình riêng và mặc định `agentRuntime`.
Xem [Mô hình](/vi/concepts/models) và [Lệnh gạch chéo](/vi/tools/slash-commands).
Xem [Mô hình](/vi/concepts/models) và [Lệnh slash](/vi/tools/slash-commands).
</Accordion>
<Accordion title="Làm sao để cấu hình chế độ nhanh cho GPT 5.5?">
Dùng công tắc phiên hoặc mặc định cấu hình:
<Accordion title="Làm thế nào để cấu hình chế độ nhanh cho GPT 5.5?">
Dùng một công tắc phiên hoặc một mặc định cấu hình:
- **Theo phiên:** gửi `/fast on` khi phiên đang dùng `openai/gpt-5.5` hoặc `openai-codex/gpt-5.5`.
- **Mặc định theo mô hình:** đặt `agents.defaults.models["openai/gpt-5.5"].params.fastMode` hoặc `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` thành `true`.
- **Theo từng phiên:** gửi `/fast on` khi phiên đang dùng `openai/gpt-5.5` hoặc `openai-codex/gpt-5.5`.
- **Mặc định theo từng mô hình:** đặt `agents.defaults.models["openai/gpt-5.5"].params.fastMode` hoặc `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` thành `true`.
Ví dụ:
@ -187,39 +187,42 @@ x-i18n:
}
```
Với OpenAI, chế độ nhanh ánh xạ tới `service_tier = "priority"` trên các yêu cầu Responses gốc được hỗ trợ. Ghi đè `/fast` trong phiên được ưu tiên hơn mặc định cấu hình.
Với OpenAI, chế độ nhanh ánh xạ tới `service_tier = "priority"` trên các yêu cầu Responses gốc được hỗ trợ. `/fast` theo phiên sẽ ghi đè mặc định cấu hình.
Xem [Suy nghĩ và chế độ nhanh](/vi/tools/thinking) và [Chế độ nhanh OpenAI](/vi/providers/openai#fast-mode).
Xem [Thinking và chế độ nhanh](/vi/tools/thinking) và [Chế độ nhanh của OpenAI](/vi/providers/openai#fast-mode).
</Accordion>
<Accordion title='Tại sao tôi thấy "Model ... is not allowed" rồi sau đó không có phản hồi?'>
Nếu `agents.defaults.models` được đặt, nó trở thành **danh sách cho phép** cho `/model` và mọi
<Accordion title='Tại sao tôi thấy "Model ... is not allowed" rồi không có phản hồi?'>
Nếu `agents.defaults.models` được đặt, nó trở thành **allowlist** cho `/model` và mọi
ghi đè phiên. Chọn một mô hình không có trong danh sách đó sẽ trả về:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
Lỗi đó được trả về **thay vì** một phản hồi bình thường. Cách sửa: thêm mô hình vào
`agents.defaults.models`, xóa danh sách cho phép, hoặc chọn một mô hình từ `/model list`.
Lỗi đó được trả về **thay vì** phản hồi bình thường. Cách sửa: thêm mô hình vào
`agents.defaults.models`, xóa allowlist, hoặc chọn một mô hình từ `/model list`.
Nếu lệnh cũng bao gồm `--runtime codex`, hãy thêm mô hình trước rồi thử lại
cùng lệnh `/model provider/model --runtime codex`.
</Accordion>
<Accordion title='Tại sao tôi thấy "Unknown model: minimax/MiniMax-M2.7"?'>
Điều này nghĩa là **nhà cung cấp chưa được cấu hình** (không tìm thấy cấu hình nhà cung cấp MiniMax hoặc hồ sơ xác thực
nào), nên không thể phân giải mô hình.
Điều này có nghĩa là **provider chưa được cấu hình** (không tìm thấy cấu hình provider MiniMax hoặc hồ sơ xác thực),
nên không thể phân giải mô hình.
Danh sách kiểm tra để sửa:
1. Nâng cấp lên bản phát hành OpenClaw hiện tại (hoặc chạy từ source `main`), rồi khởi động lại gateway.
2. Đảm bảo MiniMax đã được cấu hình (trình hướng dẫn hoặc JSON), hoặc xác thực MiniMax
tồn tại trong env/hồ sơ xác thực để nhà cung cấp khớp có thể được tiêm vào
2. Đảm bảo MiniMax đã được cấu hình (wizard hoặc JSON), hoặc xác thực MiniMax
tồn tại trong env/hồ sơ xác thực để provider khớp có thể được tiêm vào
(`MINIMAX_API_KEY` cho `minimax`, `MINIMAX_OAUTH_TOKEN` hoặc MiniMax
OAuth đã lưu cho `minimax-portal`).
3. Dùng đúng id mô hình chính xác (phân biệt chữ hoa/thường) cho đường dẫn xác thực của bạn:
3. Dùng đúng model id chính xác (phân biệt chữ hoa/chữ thường) cho đường xác thực của bạn:
`minimax/MiniMax-M2.7` hoặc `minimax/MiniMax-M2.7-highspeed` cho thiết lập
khóa API, hoặc `minimax-portal/MiniMax-M2.7` /
API key, hoặc `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` cho thiết lập OAuth.
4. Chạy:
@ -235,9 +238,9 @@ x-i18n:
<Accordion title="Tôi có thể dùng MiniMax làm mặc định và OpenAI cho tác vụ phức tạp không?">
Có. Dùng **MiniMax làm mặc định** và chuyển mô hình **theo từng phiên** khi cần.
Dự phòng dành cho **lỗi**, không phải "tác vụ khó", nên hãy dùng `/model` hoặc một tác nhân riêng.
Fallback dành cho **lỗi**, không phải "tác vụ khó", vì vậy hãy dùng `/model` hoặc một agent riêng.
**Tùy chọn A: chuyển theo phiên**
**Tùy chọn A: chuyển theo từng phiên**
```json5
{
@ -260,34 +263,34 @@ x-i18n:
/model gpt
```
**Tùy chọn B: tác nhân riêng**
**Tùy chọn B: agent riêng biệt**
- Mặc định tác nhân A: MiniMax
- Mặc định tác nhân B: OpenAI
- Định tuyến theo tác nhân hoặc dùng `/agent` để chuyển
- Mặc định của Agent A: MiniMax
- Mặc định của Agent B: OpenAI
- Định tuyến theo agent hoặc dùng `/agent` để chuyển
Tài liệu: [Mô hình](/vi/concepts/models), [Định tuyến đa tác nhân](/vi/concepts/multi-agent), [MiniMax](/vi/providers/minimax), [OpenAI](/vi/providers/openai).
</Accordion>
<Accordion title="opus / sonnet / gpt có phải phím tắt tích hợp không?">
Có. OpenClaw cung cấp một vài cách viết tắt mặc định (chỉ áp dụng khi mô hình tồn tại trong `agents.defaults.models`):
<Accordion title="opus / sonnet / gpt có phải là lối tắt tích hợp sẵn không?">
Có. OpenClaw cung cấp một vài lối viết tắt mặc định (chỉ áp dụng khi mô hình tồn tại trong `agents.defaults.models`):
- `opus` → `anthropic/claude-opus-4-6`
- `sonnet` → `anthropic/claude-sonnet-4-6`
- `gpt` → `openai/gpt-5.5` cho thiết lập khóa API, hoặc `openai-codex/gpt-5.5` khi được cấu hình cho Codex OAuth
- `gpt` → `openai/gpt-5.5` cho thiết lập API key, hoặc `openai-codex/gpt-5.5` khi được cấu hình cho Codex OAuth
- `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`
Nếu bạn đặt bí danh riêng với cùng tên, giá trị của bạn sẽ được ưu tiên.
Nếu bạn đặt alias riêng cùng tên, giá trị của bạn sẽ được ưu tiên.
</Accordion>
<Accordion title="Làm sao để định nghĩa/ghi đè phím tắt mô hình (bí danh)?">
Bí danh đến từ `agents.defaults.models.<modelId>.alias`. Ví dụ:
<Accordion title="Làm thế nào để định nghĩa/ghi đè lối tắt mô hình (alias)?">
Alias đến từ `agents.defaults.models.<modelId>.alias`. Ví dụ:
```json5
{
@ -304,12 +307,12 @@ x-i18n:
}
```
Sau đó `/model sonnet` (hoặc `/<alias>` khi được hỗ trợ) phân giải thành ID mô hình đó.
Sau đó `/model sonnet` (hoặc `/<alias>` khi được hỗ trợ) sẽ phân giải thành ID mô hình đó.
</Accordion>
<Accordion title="Làm sao để thêm mô hình từ nhà cung cấp khác như OpenRouter hoặc Z.AI?">
OpenRouter (trả tiền theo token; nhiều mô hình):
<Accordion title="Làm thế nào để thêm mô hình từ các provider khác như OpenRouter hoặc Z.AI?">
OpenRouter (trả theo token; nhiều mô hình):
```json5
{
@ -323,7 +326,7 @@ x-i18n:
}
```
Z.AI (mô hình GLM):
Z.AI (các mô hình GLM):
```json5
{
@ -339,7 +342,7 @@ x-i18n:
Nếu bạn tham chiếu một nhà cung cấp/mô hình nhưng thiếu khóa nhà cung cấp bắt buộc, bạn sẽ gặp lỗi xác thực lúc chạy (ví dụ: `No API key found for provider "zai"`).
**Không tìm thấy khóa API cho nhà cung cấp sau khi thêm một agent mới**
**Không tìm thấy khóa API cho nhà cung cấp sau khi thêm agent mới**
Điều này thường có nghĩa là **agent mới** có kho xác thực trống. Xác thực là theo từng agent và
được lưu trong:
@ -352,9 +355,9 @@ x-i18n:
- Chạy `openclaw agents add <id>` và cấu hình xác thực trong trình hướng dẫn.
- Hoặc chỉ sao chép các hồ sơ `api_key` / `token` tĩnh có thể di chuyển từ kho xác thực của agent chính vào kho xác thực của agent mới.
- Với hồ sơ OAuth, đăng nhập từ agent mới khi agent đó cần tài khoản riêng; nếu không, OpenClaw có thể đọc xuyên qua agent mặc định/chính mà không cần sao chép token làm mới.
- Với hồ sơ OAuth, hãy đăng nhập từ agent mới khi agent đó cần tài khoản riêng; nếu không, OpenClaw có thể đọc xuyên tới agent mặc định/chính mà không cần sao chép token làm mới.
Không **được** dùng lại `agentDir` giữa các agent; việc đó gây xung đột xác thực/phiên.
**Không** dùng lại `agentDir` giữa các agent; việc này gây xung đột xác thực/phiên.
</Accordion>
</AccordionGroup>
@ -362,98 +365,98 @@ x-i18n:
## Chuyển đổi dự phòng mô hình và "Tất cả mô hình đều thất bại"
<AccordionGroup>
<Accordion title="Chuyển đổi dự phòng hoạt động như thế nào?">
<Accordion title="How does failover work?">
Chuyển đổi dự phòng diễn ra theo hai giai đoạn:
1. **Luân chuyển hồ sơ xác thực** trong cùng một nhà cung cấp.
1. **Luân phiên hồ sơ xác thực** trong cùng một nhà cung cấp.
2. **Dự phòng mô hình** sang mô hình tiếp theo trong `agents.defaults.model.fallbacks`.
Thời gian chờ áp dụng cho các hồ sơ bị lỗi (backoff lũy thừa), vì vậy OpenClaw vẫn có thể tiếp tục phản hồi ngay cả khi một nhà cung cấp bị giới hạn tốc độ hoặc tạm thời gặp lỗi.
Thời gian chờ áp dụng cho các hồ sơ gặp lỗi (backoff lũy thừa), nên OpenClaw có thể tiếp tục phản hồi ngay cả khi một nhà cung cấp bị giới hạn tốc độ hoặc tạm thời gặp lỗi.
Nhóm giới hạn tốc độ bao gồm nhiều trường hợp hơn các phản hồi `429` đơn thuần. OpenClaw
cũng xem các thông báo như `Too many concurrent requests`,
`ThrottlingException`, `concurrency limit reached`,
`workers_ai ... quota limit exceeded`, `resource exhausted`, và các giới hạn
theo cửa sổ sử dụng định kỳ (`weekly/monthly limit reached`) là các giới hạn tốc độ
cửa sổ sử dụng định kỳ (`weekly/monthly limit reached`) là giới hạn tốc độ
đáng để chuyển đổi dự phòng.
Một số phản hồi trông giống lỗi thanh toán không phải là `402`, và một số phản hồi HTTP `402`
Một số phản hồi trông như lỗi thanh toán không phải là `402`, và một số phản hồi HTTP `402`
cũng vẫn nằm trong nhóm tạm thời đó. Nếu một nhà cung cấp trả về
văn bản thanh toán rõ ràng trên `401` hoặc `403`, OpenClaw vẫn có thể giữ phản hồi đó trong
luồng thanh toán, nhưng các bộ khớp văn bản riêng theo nhà cung cấp vẫn được giới hạn trong
văn bản thanh toán rõ ràng trên `401` hoặc `403`, OpenClaw vẫn có thể giữ điều đó trong
luồng thanh toán, nhưng các bộ khớp văn bản theo từng nhà cung cấp vẫn chỉ nằm trong phạm vi
nhà cung cấp sở hữu chúng (ví dụ OpenRouter `Key limit exceeded`). Nếu một thông báo `402`
thay vào đó trông giống một cửa sổ sử dụng có thể thử lại hoặc
thay vào đó trông giống giới hạn cửa sổ sử dụng có thể thử lại hoặc
giới hạn chi tiêu của tổ chức/không gian làm việc (`daily limit reached, resets tomorrow`,
`organization spending limit exceeded`), OpenClaw xem nó là
`organization spending limit exceeded`), OpenClaw xử lý nó là
`rate_limit`, không phải vô hiệu hóa thanh toán dài hạn.
Lỗi tràn ngữ cảnh thì khác: các dấu hiệu như
`request_too_large`, `input exceeds the maximum number of tokens`,
`input token count exceeds the maximum number of input tokens`,
`input is too long for the model`, hoặc `ollama error: context length
exceeded` vẫn đi theo đường Compaction/thử lại thay vì kích hoạt dự phòng
mô hình.
exceeded` vẫn đi theo đường Compaction/thử lại thay vì chuyển sang
dự phòng mô hình.
Văn bản lỗi máy chủ chung được cố ý thu hẹp hơn so với "bất cứ thứ gì có
unknown/error trong đó". OpenClaw có xem các dạng tạm thời theo phạm vi nhà cung cấp
như Anthropic dạng trần `An unknown error occurred`, OpenRouter dạng trần
Văn bản lỗi máy chủ chung được cố ý thu hẹp hơn so với "bất kỳ thứ gì có
unknown/error trong đó". OpenClaw có xử lý các dạng tạm thời theo phạm vi nhà cung cấp
như Anthropic chỉ trả về `An unknown error occurred`, OpenRouter chỉ trả về
`Provider returned error`, lỗi lý do dừng như `Unhandled stop reason:
error`, payload JSON `api_error` với văn bản máy chủ tạm thời
error`, payload JSON `api_error` có văn bản máy chủ tạm thời
(`internal server error`, `unknown error, 520`, `upstream error`, `backend
error`), và lỗi nhà cung cấp đang bận như `ModelNotReadyException` là
các tín hiệu hết thời gian/quá tải đáng để chuyển đổi dự phòng khi ngữ cảnh nhà cung cấp
error`), và lỗi nhà cung cấp bận như `ModelNotReadyException` là
tín hiệu hết thời gian/quá tải đáng để chuyển đổi dự phòng khi ngữ cảnh nhà cung cấp
khớp.
Văn bản dự phòng nội bộ chung như `LLM request failed with an unknown
error.` vẫn được xử lý thận trọng và tự nó không kích hoạt dự phòng mô hình.
</Accordion>
<Accordion title='Thông báo "No credentials found for profile anthropic:default" có nghĩa là gì?'>
<Accordion title='What does "No credentials found for profile anthropic:default" mean?'>
Điều đó có nghĩa là hệ thống đã cố dùng ID hồ sơ xác thực `anthropic:default`, nhưng không tìm thấy thông tin xác thực cho hồ sơ đó trong kho xác thực dự kiến.
**Danh sách kiểm tra để khắc phục:**
**Danh sách kiểm tra khắc phục:**
- **Xác nhận nơi lưu hồ sơ xác thực** (đường dẫn mới so với cũ)
- **Xác nhận nơi lưu hồ sơ xác thực** (đường dẫn mới so với kế thừa)
- Hiện tại: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- Cũ: `~/.openclaw/agent/*` (được di chuyển bởi `openclaw doctor`)
- Kế thừa: `~/.openclaw/agent/*` (được di chuyển bởi `openclaw doctor`)
- **Xác nhận biến môi trường của bạn được Gateway tải**
- Nếu bạn đặt `ANTHROPIC_API_KEY` trong shell nhưng chạy Gateway qua systemd/launchd, Gateway có thể không kế thừa biến đó. Đặt biến trong `~/.openclaw/.env` hoặc bật `env.shellEnv`.
- Nếu bạn đặt `ANTHROPIC_API_KEY` trong shell nhưng chạy Gateway qua systemd/launchd, Gateway có thể không kế thừa biến đó. Hãy đặt biến trong `~/.openclaw/.env` hoặc bật `env.shellEnv`.
- **Đảm bảo bạn đang chỉnh sửa đúng agent**
- Thiết lập nhiều agent nghĩa là có thể có nhiều tệp `auth-profiles.json`.
- **Kiểm tra nhanh trạng thái mô hình/xác thực**
- Dùng `openclaw models status` để xem các mô hình đã cấu hình và liệu các nhà cung cấp đã được xác thực hay chưa.
- Dùng `openclaw models status` để xem các mô hình đã cấu hình và nhà cung cấp đã được xác thực hay chưa.
**Danh sách kiểm tra để khắc phục cho "No credentials found for profile anthropic"**
**Danh sách kiểm tra khắc phục cho "No credentials found for profile anthropic"**
Điều này nghĩa là lượt chạy được ghim vào một hồ sơ xác thực Anthropic, nhưng Gateway
không thể tìm thấy hồ sơ đó trong kho xác thực của nó.
Điều này có nghĩa là lượt chạy được ghim vào một hồ sơ xác thực Anthropic, nhưng Gateway
không tìm thấy hồ sơ đó trong kho xác thực của nó.
- **Dùng Claude CLI**
- Chạy `openclaw models auth login --provider anthropic --method cli --set-default` trên máy chủ gateway.
- Chạy `openclaw models auth login --provider anthropic --method cli --set-default` trên máy chủ Gateway.
- **Nếu bạn muốn dùng khóa API thay thế**
- Đặt `ANTHROPIC_API_KEY` trong `~/.openclaw/.env` trên **máy chủ gateway**.
- Đặt `ANTHROPIC_API_KEY` trong `~/.openclaw/.env` trên **máy chủ Gateway**.
- Xóa mọi thứ tự đã ghim buộc dùng một hồ sơ bị thiếu:
```bash
openclaw models auth order clear --provider anthropic
```
- **Xác nhận bạn đang chạy lệnh trên máy chủ gateway**
- Ở chế độ từ xa, hồ sơ xác thực nằm trên máy gateway, không phải laptop của bạn.
- **Xác nhận bạn đang chạy lệnh trên máy chủ Gateway**
- Ở chế độ từ xa, hồ sơ xác thực nằm trên máy Gateway, không phải máy tính xách tay của bạn.
</Accordion>
<Accordion title="Tại sao nó cũng thử Google Gemini và thất bại?">
Nếu cấu hình mô hình của bạn bao gồm Google Gemini làm dự phòng (hoặc bạn đã chuyển sang một cách viết tắt của Gemini), OpenClaw sẽ thử nó trong quá trình dự phòng mô hình. Nếu bạn chưa cấu hình thông tin xác thực Google, bạn sẽ thấy `No API key found for provider "google"`.
<Accordion title="Why did it also try Google Gemini and fail?">
Nếu cấu hình mô hình của bạn bao gồm Google Gemini làm phương án dự phòng (hoặc bạn đã chuyển sang một cách viết tắt Gemini), OpenClaw sẽ thử nó trong quá trình dự phòng mô hình. Nếu bạn chưa cấu hình thông tin xác thực Google, bạn sẽ thấy `No API key found for provider "google"`.
Cách khắc phục: cung cấp xác thực Google, hoặc xóa/tránh các mô hình Google trong `agents.defaults.model.fallbacks` / alias để dự phòng không định tuyến đến đó.
Khắc phục: hoặc cung cấp xác thực Google, hoặc xóa/tránh các mô hình Google trong `agents.defaults.model.fallbacks` / alias để dự phòng không định tuyến tới đó.
**Yêu cầu LLM bị từ chối: yêu cầu chữ ký thinking (Google Antigravity)**
**Yêu cầu LLM bị từ chối: bắt buộc có chữ ký thinking (Google Antigravity)**
Nguyên nhân: lịch sử phiên chứa **các khối thinking không có chữ ký** (thường do
Nguyên nhân: lịch sử phiên chứa **các khối thinking không có chữ ký** (thường từ
một luồng bị hủy/dở dang). Google Antigravity yêu cầu chữ ký cho các khối thinking.
Cách khắc phục: OpenClaw hiện loại bỏ các khối thinking chưa ký cho Google Antigravity Claude. Nếu lỗi vẫn xuất hiện, hãy bắt đầu một **phiên mới** hoặc đặt `/thinking off` cho agent đó.
Khắc phục: OpenClaw hiện loại bỏ các khối thinking chưa ký cho Google Antigravity Claude. Nếu lỗi vẫn xuất hiện, hãy bắt đầu một **phiên mới** hoặc đặt `/thinking off` cho agent đó.
</Accordion>
</AccordionGroup>
@ -463,34 +466,36 @@ x-i18n:
Liên quan: [/concepts/oauth](/vi/concepts/oauth) (luồng OAuth, lưu trữ token, mẫu nhiều tài khoản)
<AccordionGroup>
<Accordion title="Hồ sơ xác thực là gì?">
<Accordion title="What is an auth profile?">
Hồ sơ xác thực là một bản ghi thông tin xác thực có tên (OAuth hoặc khóa API) gắn với một nhà cung cấp. Hồ sơ nằm trong:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
Để kiểm tra các hồ sơ đã lưu mà không in ra bí mật, hãy chạy `openclaw models auth list` (tùy chọn `--provider <id>` hoặc `--json`). Xem [Models CLI](/vi/cli/models#openclaw-models-auth-list) để biết chi tiết.
</Accordion>
<Accordion title="Các ID hồ sơ thường gặp là gì?">
OpenClaw dùng các ID có tiền tố nhà cung cấp như:
<Accordion title="What are typical profile IDs?">
OpenClaw dùng ID có tiền tố nhà cung cấp như:
- `anthropic:default` (phổ biến khi không có danh tính email)
- `anthropic:<email>` cho danh tính OAuth
- `anthropic:default` (phổ biến khi không có định danh email)
- `anthropic:<email>` cho định danh OAuth
- ID tùy chỉnh bạn chọn (ví dụ: `anthropic:work`)
</Accordion>
<Accordion title="Tôi có thể kiểm soát hồ sơ xác thực nào được thử trước không?">
Có. Cấu hình hỗ trợ metadata tùy chọn cho hồ sơ và thứ tự theo từng nhà cung cấp (`auth.order.<provider>`). Điều này **không** lưu bí mật; nó ánh xạ ID tới nhà cung cấp/chế độ và đặt thứ tự luân chuyển.
<Accordion title="Can I control which auth profile is tried first?">
Có. Cấu hình hỗ trợ siêu dữ liệu tùy chọn cho hồ sơ và thứ tự theo từng nhà cung cấp (`auth.order.<provider>`). Điều này **không** lưu bí mật; nó ánh xạ ID tới nhà cung cấp/chế độ và đặt thứ tự luân phiên.
OpenClaw có thể tạm thời bỏ qua một hồ sơ nếu hồ sơ đó đang trong **thời gian chờ** ngắn (giới hạn tốc độ/hết thời gian/lỗi xác thực) hoặc trạng thái **bị vô hiệu hóa** dài hơn (thanh toán/không đủ tín dụng). Để kiểm tra điều này, chạy `openclaw models status --json` và xem `auth.unusableProfiles`. Tinh chỉnh: `auth.cooldowns.billingBackoffHours*`.
Thời gian chờ do giới hạn tốc độ có thể theo phạm vi mô hình. Một hồ sơ đang trong thời gian chờ
Thời gian chờ do giới hạn tốc độ có thể được giới hạn theo mô hình. Một hồ sơ đang trong thời gian chờ
cho một mô hình vẫn có thể dùng được cho một mô hình cùng nhóm trên cùng nhà cung cấp,
trong khi các cửa sổ thanh toán/bị vô hiệu hóa vẫn chặn toàn bộ hồ sơ.
Bạn cũng có thể đặt ghi đè thứ tự **theo từng agent** (được lưu trong `auth-state.json` của agent đó) qua CLI:
Bạn cũng có thể đặt ghi đè thứ tự **theo từng agent** (lưu trong `auth-state.json` của agent đó) qua CLI:
```bash
# Defaults to the configured default agent (omit --agent)
@ -512,31 +517,31 @@ Liên quan: [/concepts/oauth](/vi/concepts/oauth) (luồng OAuth, lưu trữ tok
openclaw models auth order set --provider anthropic --agent main anthropic:default
```
Để xác minh thứ sẽ thực sự được thử, dùng:
Để xác minh những gì thực sự sẽ được thử, dùng:
```bash
openclaw models status --probe
```
Nếu một hồ sơ đã lưu bị bỏ khỏi thứ tự rõ ràng, probe sẽ báo
Nếu một hồ sơ đã lưu bị bỏ khỏi thứ tự rõ ràng, probe báo cáo
`excluded_by_auth_order` cho hồ sơ đó thay vì âm thầm thử nó.
</Accordion>
<Accordion title="OAuth so với khóa API - khác nhau ở điểm nào?">
<Accordion title="OAuth vs API key - what is the difference?">
OpenClaw hỗ trợ cả hai:
- **OAuth** thường tận dụng quyền truy cập theo gói đăng ký (nếu áp dụng).
- **Khóa API** dùng hình thức tính phí theo token.
- **OAuth** thường tận dụng quyền truy cập thuê bao (khi áp dụng).
- **Khóa API** dùng thanh toán theo token.
Trình hướng dẫn hỗ trợ rõ ràng Anthropic Claude CLI, OAuth OpenAI Codex, và khóa API.
Trình hướng dẫn hỗ trợ rõ ràng Anthropic Claude CLI, OpenAI Codex OAuth và khóa API.
</Accordion>
</AccordionGroup>
## Liên quan
- [Câu hỏi thường gặp](/vi/help/faq) — phần Câu hỏi thường gặp chính
- [Câu hỏi thường gặp — bắt đầu nhanh và thiết lập lần chạy đầu tiên](/vi/help/faq-first-run)
- [FAQ](/vi/help/faq) — FAQ chính
- [FAQ — bắt đầu nhanh và thiết lập lần chạy đầu tiên](/vi/help/faq-first-run)
- [Chọn mô hình](/vi/concepts/model-providers)
- [Chuyển đổi dự phòng mô hình](/vi/concepts/model-failover)
- [Dự phòng mô hình](/vi/concepts/model-failover)

389
docs/vi/help/testing-live.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Chạy ma trận mô hình trực tiếp / phần xử lý nền CLI / ACP / kiểm thử khói media-provider
- Gỡ lỗi quá trình phân giải thông tin xác thực cho kiểm thử trực tiếp
- Thêm một kiểm thử trực tiếp mới dành riêng cho nhà cung cấp
- Chạy các bài kiểm thử khói cho ma trận mô hình trực tiếp / phần phụ trợ CLI / ACP / media-provider
- Gỡ lỗi việc phân giải thông tin xác thực cho kiểm thử trực tiếp
- Thêm một bài kiểm thử trực tiếp mới dành riêng cho nhà cung cấp
sidebarTitle: Live tests
summary: 'Kiểm thử trực tiếp (có truy cập mạng): ma trận mô hình, các phần phụ trợ CLI, ACP, nhà cung cấp phương tiện, thông tin xác thực'
title: 'Kiểm thử: các bộ kiểm thử trực tiếp'
summary: 'Kiểm thử trực tiếp (có tương tác mạng): ma trận mô hình, các backend CLI, ACP, nhà cung cấp phương tiện, thông tin xác thực'
title: 'Kiểm thử: bộ kiểm thử trực tiếp'
x-i18n:
generated_at: "2026-05-03T10:37:55Z"
generated_at: "2026-05-05T01:48:04Z"
model: gpt-5.5
provider: openai
source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016
source_path: help/testing-live.md
workflow: 16
---
Để bắt đầu nhanh, trình chạy QA, bộ kiểm thử đơn vị/tích hợp và luồng Docker, hãy xem
[Kiểm thử](/vi/help/testing). Trang này trình bày các bộ kiểm thử **trực tiếp** (có chạm mạng):
[Kiểm thử](/vi/help/testing). Trang này bao quát các bộ kiểm thử **trực tiếp** (có chạm mạng):
ma trận mô hình, backend CLI, ACP và kiểm thử trực tiếp nhà cung cấp phương tiện, cùng với
cách xử lý thông tin xác thực.
## Trực tiếp: lệnh kiểm tra nhanh hồ sơ cục bộ
## Trực tiếp: lệnh smoke profile cục bộ
Nạp `~/.profile` trước các kiểm tra trực tiếp tùy biến để khóa nhà cung cấp và đường dẫn
công cụ cục bộ khớp với shell của bạn:
Source `~/.profile` trước các kiểm tra trực tiếp ad hoc để khóa nhà cung cấp và đường dẫn công cụ
cục bộ khớp với shell của bạn:
```bash
source ~/.profile
```
Kiểm tra nhanh phương tiện an toàn:
Smoke phương tiện an toàn:
```bash
pnpm openclaw infer tts convert --local --json \
@ -37,7 +37,7 @@ pnpm openclaw infer tts convert --local --json \
--output /tmp/openclaw-live-smoke.mp3
```
Kiểm tra nhanh mức sẵn sàng cuộc gọi thoại an toàn:
Smoke an toàn về trạng thái sẵn sàng của cuộc gọi thoại:
```bash
pnpm openclaw voicecall setup --json
@ -46,96 +46,96 @@ pnpm openclaw voicecall smoke --to "+15555550123"
`voicecall smoke` là chạy thử khô trừ khi cũng có `--yes`. Chỉ dùng `--yes`
khi bạn cố ý muốn thực hiện một cuộc gọi thông báo thật. Với Twilio, Telnyx và
Plivo, kiểm tra mức sẵn sàng thành công cần một URL Webhook công khai; các
phương án dự phòng local loopback/chỉ cục bộ/riêng tư bị từ chối theo thiết kế.
Plivo, kiểm tra sẵn sàng thành công yêu cầu URL Webhook công khai; các phương án dự phòng
chỉ local loopback/cục bộ riêng tư bị từ chối theo thiết kế.
## Trực tiếp: quét năng lực Node Android
## Trực tiếp: quét năng lực node Android
- Kiểm thử: `src/gateway/android-node.capabilities.live.test.ts`
- Script: `pnpm android:test:integration`
- Mục tiêu: gọi **mọi lệnh hiện đang được quảng bá** bởi một Node Android đã kết nối và xác nhận hành vi hợp đồng lệnh.
- Mục tiêu: gọi **mọi lệnh hiện đang được quảng bá** bởi một node Android đã kết nối và xác nhận hành vi hợp đồng lệnh.
- Phạm vi:
- Thiết lập thủ công/có điều kiện trước (bộ kiểm thử không cài đặt/chạy/ghép đôi ứng dụng).
- Xác thực `node.invoke` theo từng lệnh qua Gateway cho Node Android đã chọn.
- Xác thực Gateway `node.invoke` theo từng lệnh cho node Android đã chọn.
- Thiết lập trước bắt buộc:
- Ứng dụng Android đã kết nối + ghép đôi với Gateway.
- Ứng dụng được giữ ở tiền cảnh.
- Quyền/sự đồng ý ghi lại đã được cấp cho các năng lực bạn kỳ vọng sẽ vượt qua.
- Quyền/đồng ý ghi nhận đã được cấp cho các năng lực bạn kỳ vọng sẽ đạt.
- Ghi đè mục tiêu tùy chọn:
- `OPENCLAW_ANDROID_NODE_ID` hoặc `OPENCLAW_ANDROID_NODE_NAME`.
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
- Chi tiết thiết lập Android đầy đủ: [Ứng dụng Android](/vi/platforms/android)
## Trực tiếp: kiểm tra nhanh mô hình (khóa hồ sơ)
## Trực tiếp: smoke mô hình (khóa profile)
Các kiểm thử trực tiếp được tách thành hai lớp để chúng ta có thể cô lập lỗi:
Kiểm thử trực tiếp được chia thành hai lớp để chúng ta có thể cô lập lỗi:
- “Mô hình trực tiếp” cho biết nhà cung cấp/mô hình có thể trả lời với khóa đã cho hay không.
- “Kiểm tra nhanh Gateway” cho biết toàn bộ pipeline gateway+tác nhân có hoạt động với mô hình đó hay không (phiên, lịch sử, công cụ, chính sách sandbox, v.v.).
- “Smoke Gateway” cho biết toàn bộ pipeline gateway+tác nhân có hoạt động cho mô hình đó hay không (phiên, lịch sử, công cụ, chính sách sandbox, v.v.).
### Lớp 1: Hoàn tất mô hình trực tiếp (không có Gateway)
- Kiểm thử: `src/agents/models.profiles.live.test.ts`
- Mục tiêu:
- Liệt kê các mô hình đã phát hiện
- Liệt kê các mô hình được phát hiện
- Dùng `getApiKeyForModel` để chọn các mô hình bạn có thông tin xác thực
- Chạy một lần hoàn tất nhỏ cho mỗi mô hình (và các hồi quy có mục tiêu khi cần)
- Chạy một completion nhỏ cho từng mô hình (và các hồi quy có mục tiêu khi cần)
- Cách bật:
- `pnpm test:live` (hoặc `OPENCLAW_LIVE_TEST=1` nếu gọi Vitest trực tiếp)
- Đặt `OPENCLAW_LIVE_MODELS=modern` (hoặc `all`, bí danh cho modern) để thật sự chạy bộ này; nếu không, nó sẽ bỏ qua để giữ `pnpm test:live` tập trung vào kiểm tra nhanh Gateway
- Đặt `OPENCLAW_LIVE_MODELS=modern` (hoặc `all`, bí danh cho modern) để thật sự chạy bộ kiểm thử này; nếu không, nó sẽ bỏ qua để giữ `pnpm test:live` tập trung vào smoke Gateway
- Cách chọn mô hình:
- `OPENCLAW_LIVE_MODELS=modern` để chạy danh sách cho phép hiện đại (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_MODELS=all` là bí danh cho danh sách cho phép hiện đại
- hoặc `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (danh sách cho phép phân tách bằng dấu phẩy)
- Các lượt quét modern/all mặc định dùng một giới hạn tín hiệu cao được tuyển chọn; đặt `OPENCLAW_LIVE_MAX_MODELS=0` để quét modern đầy đủ hoặc một số dương để đặt giới hạn nhỏ hơn.
- Lượt quét đầy đủ dùng `OPENCLAW_LIVE_TEST_TIMEOUT_MS` làm thời gian chờ cho toàn bộ kiểm thử mô hình trực tiếp. Mặc định: 60 phút.
- Các thăm dò mô hình trực tiếp mặc định chạy song song 20 luồng; đặt `OPENCLAW_LIVE_MODEL_CONCURRENCY` để ghi đè.
- `OPENCLAW_LIVE_MODELS=modern` để chạy allowlist hiện đại (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_MODELS=all` là bí danh cho allowlist hiện đại
- hoặc `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist phân tách bằng dấu phẩy)
- Các lượt quét modern/all mặc định dùng một giới hạn được tuyển chọn có tín hiệu cao; đặt `OPENCLAW_LIVE_MAX_MODELS=0` để quét hiện đại toàn diện hoặc một số dương để dùng giới hạn nhỏ hơn.
- Các lượt quét toàn diện dùng `OPENCLAW_LIVE_TEST_TIMEOUT_MS` cho timeout của toàn bộ kiểm thử mô hình trực tiếp. Mặc định: 60 phút.
- Probe mô hình trực tiếp chạy với song song 20 luồng theo mặc định; đặt `OPENCLAW_LIVE_MODEL_CONCURRENCY` để ghi đè.
- Cách chọn nhà cung cấp:
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (danh sách cho phép phân tách bằng dấu phẩy)
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist phân tách bằng dấu phẩy)
- Khóa đến từ đâu:
- Mặc định: kho hồ sơ và phương án dự phòng env
- Đặt `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để chỉ bắt buộc **kho hồ sơ**
- Theo mặc định: kho profile và các phương án dự phòng env
- Đặt `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để chỉ bắt buộc dùng **kho profile**
- Lý do tồn tại:
- Tách “API nhà cung cấp bị hỏng / khóa không hợp lệ” khỏi “pipeline tác nhân Gateway bị hỏng”
- Chứa các hồi quy nhỏ, cô lập (ví dụ: luồng phát lại reasoning + tool-call của OpenAI Responses/Codex Responses)
- Chứa các hồi quy nhỏ, cô lập (ví dụ: phát lại reasoning của OpenAI Responses/Codex Responses + luồng gọi công cụ)
### Lớp 2: Gateway + kiểm tra nhanh tác nhân dev (điều "@openclaw" thật sự làm)
### Lớp 2: Smoke Gateway + tác nhân dev (những gì "@openclaw" thật sự làm)
- Kiểm thử: `src/gateway/gateway-models.profiles.live.test.ts`
- Mục tiêu:
- Khởi chạy một Gateway trong tiến trình
- Tạo/vá một phiên `agent:dev:*` (ghi đè mô hình theo từng lần chạy)
- Khởi động Gateway trong tiến trình
- Tạo/vá một phiên `agent:dev:*` (ghi đè mô hình theo từng lượt chạy)
- Lặp qua các mô hình có khóa và xác nhận:
- phản hồi “có ý nghĩa” (không có công cụ)
- một lần gọi công cụ thật hoạt động (thăm dò đọc)
- các thăm dò công cụ bổ sung tùy chọn (thăm dò thực thi+đọc)
- các đường dẫn hồi quy OpenAI (chỉ tool-call → theo dõi tiếp) tiếp tục hoạt động
- Chi tiết thăm dò (để bạn có thể giải thích lỗi nhanh):
- Thăm dò `read`: kiểm thử ghi một tệp nonce trong workspace và yêu cầu tác nhân `read` nó rồi lặp lại nonce.
- Thăm dò `exec+read`: kiểm thử yêu cầu tác nhân dùng `exec` để ghi một nonce vào tệp tạm, rồi `read` lại.
- Thăm dò hình ảnh: kiểm thử đính kèm một PNG được tạo (mèo + mã ngẫu nhiên) và kỳ vọng mô hình trả về `cat <CODE>`.
- phản hồi “có ý nghĩa” (không công cụ)
- một lượt gọi công cụ thật hoạt động (probe đọc)
- các probe công cụ bổ sung tùy chọn (probe exec+đọc)
- các đường dẫn hồi quy OpenAI (chỉ gọi công cụ → tiếp nối) tiếp tục hoạt động
- Chi tiết probe (để bạn có thể giải thích lỗi nhanh):
- Probe `read`: kiểm thử ghi một tệp nonce trong workspace và yêu cầu tác nhân `read` tệp đó rồi echo nonce trở lại.
- Probe `exec+read`: kiểm thử yêu cầu tác nhân dùng `exec` ghi một nonce vào tệp tạm, rồi `read` lại nó.
- Probe hình ảnh: kiểm thử đính kèm một PNG được tạo (mèo + mã ngẫu nhiên) và kỳ vọng mô hình trả về `cat <CODE>`.
- Tham chiếu triển khai: `src/gateway/gateway-models.profiles.live.test.ts` và `src/gateway/live-image-probe.ts`.
- Cách bật:
- `pnpm test:live` (hoặc `OPENCLAW_LIVE_TEST=1` nếu gọi Vitest trực tiếp)
- Cách chọn mô hình:
- Mặc định: danh sách cho phép hiện đại (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` là bí danh cho danh sách cho phép hiện đại
- Mặc định: allowlist hiện đại (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` là bí danh cho allowlist hiện đại
- Hoặc đặt `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (hoặc danh sách phân tách bằng dấu phẩy) để thu hẹp
- Các lượt quét Gateway modern/all mặc định dùng một giới hạn tín hiệu cao được tuyển chọn; đặt `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` để quét modern đầy đủ hoặc một số dương để đặt giới hạn nhỏ hơn.
- Các lượt quét Gateway modern/all mặc định dùng một giới hạn được tuyển chọn có tín hiệu cao; đặt `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` để quét hiện đại toàn diện hoặc một số dương để dùng giới hạn nhỏ hơn.
- Cách chọn nhà cung cấp (tránh “mọi thứ OpenRouter”):
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (danh sách cho phép phân tách bằng dấu phẩy)
- Thăm dò công cụ + hình ảnh luôn bật trong kiểm thử trực tiếp này:
- Thăm dò `read` + thăm dò `exec+read` (tạo áp lực cho công cụ)
- Thăm dò hình ảnh chạy khi mô hình quảng bá hỗ trợ đầu vào hình ảnh
- Luồng (mức cao):
- Kiểm thử tạo một PNG nhỏ có “CAT” + mã ngẫu nhiên (`src/gateway/live-image-probe.ts`)
- Gửi qua `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]`
- Gateway phân tích đính kèm thành `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- Tác nhân nhúng chuyển tiếp một tin nhắn người dùng đa phương thức đến mô hình
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist phân tách bằng dấu phẩy)
- Probe công cụ + hình ảnh luôn bật trong kiểm thử trực tiếp này:
- Probe `read` + probe `exec+read` (tạo áp lực công cụ)
- Probe hình ảnh chạy khi mô hình quảng bá hỗ trợ đầu vào hình ảnh
- Luồng (cấp cao):
- Kiểm thử tạo một PNG nhỏ với “CAT” + mã ngẫu nhiên (`src/gateway/live-image-probe.ts`)
- Gửi nó qua `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]`
- Gateway phân tích tệp đính kèm thành `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- Tác nhân nhúng chuyển tiếp một thông điệp người dùng đa phương thức tới mô hình
- Xác nhận: phản hồi chứa `cat` + mã (dung sai OCR: cho phép lỗi nhỏ)
<Tip>
Để xem bạn có thể kiểm thử gì trên máy của mình (và các id `provider/model` chính xác), hãy chạy:
Để xem bạn có thể kiểm thử gì trên máy của mình (và các id `provider/model` chính xác), chạy:
```bash
openclaw models list
@ -144,11 +144,11 @@ openclaw models list --json
</Tip>
## Trực tiếp: kiểm tra nhanh backend CLI (Claude, Codex, Gemini hoặc CLI cục bộ khác)
## Trực tiếp: smoke backend CLI (Claude, Codex, Gemini hoặc CLI cục bộ khác)
- Kiểm thử: `src/gateway/gateway-cli-backend.live.test.ts`
- Mục tiêu: xác thực pipeline Gateway + tác nhân bằng một backend CLI cục bộ mà không chạm vào cấu hình mặc định của bạn.
- Các mặc định kiểm tra nhanh theo từng backend nằm cùng định nghĩa `cli-backend.ts` của Plugin sở hữu.
- Mục tiêu: xác thực pipeline Gateway + tác nhân bằng backend CLI cục bộ, mà không chạm vào cấu hình mặc định của bạn.
- Mặc định smoke theo từng backend nằm cùng định nghĩa `cli-backend.ts` của Plugin sở hữu.
- Bật:
- `pnpm test:live` (hoặc `OPENCLAW_LIVE_TEST=1` nếu gọi Vitest trực tiếp)
- `OPENCLAW_LIVE_CLI_BACKEND=1`
@ -159,12 +159,12 @@ openclaw models list --json
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` để gửi một đính kèm hình ảnh thật (đường dẫn được chèn vào prompt). Công thức Docker mặc định tắt phần này trừ khi được yêu cầu rõ ràng.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` để gửi một tệp đính kèm hình ảnh thật (đường dẫn được chèn vào prompt). Công thức Docker mặc định tắt tùy chọn này trừ khi được yêu cầu rõ ràng.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` để truyền đường dẫn tệp hình ảnh dưới dạng đối số CLI thay vì chèn vào prompt.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (hoặc `"list"`) để kiểm soát cách truyền đối số hình ảnh khi `IMAGE_ARG` được đặt.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (hoặc `"list"`) để kiểm soát cách đối số hình ảnh được truyền khi đã đặt `IMAGE_ARG`.
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` để gửi lượt thứ hai và xác thực luồng tiếp tục.
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` để chọn tham gia thăm dò tính liên tục cùng phiên Claude Sonnet -> Opus khi mô hình đã chọn hỗ trợ đích chuyển đổi. Công thức Docker mặc định tắt phần này để tăng độ tin cậy tổng hợp.
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` để chọn tham gia thăm dò vòng lặp MCP/công cụ. Công thức Docker mặc định tắt phần này trừ khi được yêu cầu rõ ràng.
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` để chọn tham gia probe liên tục cùng phiên Claude Sonnet -> Opus khi mô hình đã chọn hỗ trợ mục tiêu chuyển đổi. Công thức Docker mặc định tắt tùy chọn này để tăng độ tin cậy tổng hợp.
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` để chọn tham gia probe MCP/công cụ loopback. Công thức Docker mặc định tắt tùy chọn này trừ khi được yêu cầu rõ ràng.
Ví dụ:
@ -174,16 +174,16 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
```
Kiểm tra nhanh cấu hình MCP Gemini giá rẻ:
Smoke cấu hình Gemini MCP rẻ:
```bash
OPENCLAW_LIVE_TEST=1 \
pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
```
Việc này không yêu cầu Gemini tạo phản hồi. Nó ghi cùng các thiết lập hệ thống
mà OpenClaw cung cấp cho Gemini, rồi chạy `gemini --debug mcp list` để chứng minh một
máy chủ đã lưu `transport: "streamable-http"` được chuẩn hóa thành dạng HTTP MCP
Kiểm thử này không yêu cầu Gemini tạo phản hồi. Nó ghi cùng các thiết lập hệ thống
mà OpenClaw đưa cho Gemini, rồi chạy `gemini --debug mcp list` để chứng minh một
máy chủ `transport: "streamable-http"` đã lưu được chuẩn hóa thành hình dạng HTTP MCP
của Gemini và có thể kết nối tới một máy chủ MCP streamable-HTTP cục bộ.
Công thức Docker:
@ -204,27 +204,36 @@ pnpm test:docker:live-cli-backend:gemini
Ghi chú:
- Trình chạy Docker nằm tại `scripts/test-live-cli-backend-docker.sh`.
- Nó chạy kiểm tra nhanh backend CLI trực tiếp bên trong image Docker của repo với người dùng không phải root `node`.
- Nó phân giải metadata kiểm tra nhanh CLI từ extension sở hữu, rồi cài đặt gói CLI Linux tương ứng (`@anthropic-ai/claude-code`, `@openai/codex` hoặc `@google/gemini-cli`) vào tiền tố có thể ghi được lưu cache tại `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (mặc định: `~/.cache/openclaw/docker-cli-tools`).
- `pnpm test:docker:live-cli-backend:claude-subscription` yêu cầu OAuth đăng ký Claude Code di động thông qua `~/.claude/.credentials.json` với `claudeAiOauth.subscriptionType` hoặc `CLAUDE_CODE_OAUTH_TOKEN` từ `claude setup-token`. Trước tiên nó chứng minh `claude -p` trực tiếp trong Docker, rồi chạy hai lượt backend CLI Gateway mà không giữ lại các biến env khóa API Anthropic. Lane đăng ký này mặc định tắt các thăm dò MCP/công cụ và hình ảnh của Claude vì Claude hiện định tuyến việc sử dụng ứng dụng bên thứ ba qua thanh toán mức sử dụng bổ sung thay vì giới hạn gói đăng ký thông thường.
- Kiểm tra nhanh backend CLI trực tiếp hiện thực thi cùng luồng đầu cuối cho Claude, Codex và Gemini: lượt văn bản, lượt phân loại hình ảnh, rồi lệnh gọi công cụ MCP `cron` được xác minh qua Gateway CLI.
- Kiểm tra nhanh mặc định của Claude cũng vá phiên từ Sonnet sang Opus và xác minh phiên được tiếp tục vẫn nhớ một ghi chú trước đó.
- Nó chạy smoke backend CLI trực tiếp bên trong image Docker của repo dưới người dùng `node` không phải root.
- Nó phân giải metadata smoke CLI từ Plugin sở hữu, rồi cài gói CLI Linux khớp (`@anthropic-ai/claude-code`, `@openai/codex` hoặc `@google/gemini-cli`) vào prefix có thể ghi được cache tại `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (mặc định: `~/.cache/openclaw/docker-cli-tools`).
- `pnpm test:docker:live-cli-backend:claude-subscription` yêu cầu OAuth đăng ký Claude Code di động thông qua `~/.claude/.credentials.json` với `claudeAiOauth.subscriptionType` hoặc `CLAUDE_CODE_OAUTH_TOKEN` từ `claude setup-token`. Trước tiên nó chứng minh `claude -p` trực tiếp trong Docker, rồi chạy hai lượt backend CLI Gateway mà không giữ lại biến env khóa API Anthropic. Lane đăng ký này mặc định tắt probe Claude MCP/công cụ và hình ảnh vì Claude hiện định tuyến việc sử dụng ứng dụng bên thứ ba qua tính phí sử dụng bổ sung thay vì giới hạn gói đăng ký thông thường.
- Smoke backend CLI trực tiếp hiện thực thi cùng luồng đầu cuối cho Claude, Codex và Gemini: lượt văn bản, lượt phân loại hình ảnh, rồi lệnh gọi công cụ `cron` MCP được xác minh qua CLI Gateway.
- Smoke mặc định của Claude cũng vá phiên từ Sonnet sang Opus và xác minh phiên đã tiếp tục vẫn nhớ một ghi chú trước đó.
## Trực tiếp: kiểm tra nhanh bind ACP (`/acp spawn ... --bind here`)
## Trực tiếp: khả năng truy cập proxy APNs HTTP/2
- Kiểm thử: `src/infra/push-apns-http2.live.test.ts`
- Mục tiêu: đi đường hầm qua một proxy HTTP CONNECT cục bộ tới endpoint APNs sandbox của Apple, gửi yêu cầu xác thực APNs HTTP/2 và xác nhận phản hồi thật `403 InvalidProviderToken` của Apple quay lại qua đường dẫn proxy.
- Bật:
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
- Timeout tùy chọn:
- `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`
## Trực tiếp: smoke bind ACP (`/acp spawn ... --bind here`)
- Kiểm thử: `src/gateway/gateway-acp-bind.live.test.ts`
- Mục tiêu: xác thực luồng bind cuộc trò chuyện ACP thực với một tác tử ACP live:
- Mục tiêu: xác thực luồng bind hội thoại ACP thực với một tác tử ACP trực tiếp:
- gửi `/acp spawn <agent> --bind here`
- bind một cuộc trò chuyện kênh tin nhắn tổng hợp tại chỗ
- gửi một lượt tiếp theo bình thường trên cùng cuộc trò chuyện đó
- xác minh lượt tiếp theo đi vào transcript của phiên ACP đã bind
- bind tại chỗ một hội thoại kênh tin nhắn tổng hợp
- gửi một phản hồi tiếp theo thông thường trên cùng hội thoại đó
- xác minh phản hồi tiếp theo đi vào transcript của phiên ACP đã bind
- Bật:
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- Mặc định:
- Tác tử ACP trong Docker: `claude,codex,gemini`
- Tác tử ACP cho `pnpm test:live ...` trực tiếp: `claude`
- Kênh tổng hợp: ngữ cảnh cuộc trò chuyện kiểu Slack DM
- Tác tử ACP cho lệnh trực tiếp `pnpm test:live ...`: `claude`
- Kênh tổng hợp: ngữ cảnh hội thoại kiểu Slack DM
- Backend ACP: `acpx`
- Ghi đè:
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@ -240,9 +249,9 @@ Ghi chú:
- `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
- Ghi chú:
- Lane này dùng bề mặt `chat.send` của gateway với các trường originating-route tổng hợp chỉ dành cho admin để kiểm thử có thể gắn ngữ cảnh kênh tin nhắn mà không giả vờ phân phối ra bên ngoài.
- Khi `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` không được đặt, kiểm thử dùng registry tác tử tích hợp của Plugin `acpx` nhúng cho tác tử harness ACP đã chọn.
- Việc tạo MCP cron cho phiên đã bind mặc định là best-effort vì các harness ACP bên ngoài có thể hủy lệnh gọi MCP sau khi bằng chứng bind/image đã đạt; đặt `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` để làm cho probe cron sau bind trở nên nghiêm ngặt.
- Lane này dùng bề mặt `chat.send` của gateway với các trường tuyến xuất phát tổng hợp chỉ dành cho quản trị viên để kiểm thử có thể gắn ngữ cảnh kênh tin nhắn mà không giả vờ phân phối ra bên ngoài.
- Khi chưa đặt `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`, kiểm thử dùng sổ đăng ký tác tử tích hợp sẵn của Plugin `acpx` được nhúng cho tác tử harness ACP đã chọn.
- Việc tạo MCP Cron cho phiên đã bind mặc định là best-effort vì các harness ACP bên ngoài có thể hủy lệnh gọi MCP sau khi bằng chứng bind/hình ảnh đã đạt; đặt `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` để làm cho phép dò Cron sau bind đó trở nên nghiêm ngặt.
Ví dụ:
@ -270,38 +279,38 @@ pnpm test:docker:live-acp-bind:opencode
Ghi chú Docker:
- Runner Docker nằm tại `scripts/test-live-acp-bind-docker.sh`.
- Theo mặc định, runner này chạy smoke bind ACP lần lượt với các tác tử CLI live tổng hợp: `claude`, `codex`, rồi `gemini`.
- Trình chạy Docker nằm tại `scripts/test-live-acp-bind-docker.sh`.
- Theo mặc định, nó chạy smoke bind ACP lần lượt trên các tác tử CLI trực tiếp tổng hợp: `claude`, `codex`, rồi `gemini`.
- Dùng `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, hoặc `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` để thu hẹp ma trận.
- Runner nạp `~/.profile`, đưa vật liệu xác thực CLI tương ứng vào container, rồi cài CLI live được yêu cầu (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid qua `https://app.factory.ai/cli`, `@google/gemini-cli`, hoặc `opencode-ai`) nếu còn thiếu. Bản thân backend ACP là package `acpx/runtime` nhúng từ Plugin `acpx` chính thức.
- Biến thể Docker Droid đưa `~/.factory` cho cài đặt, chuyển tiếp `FACTORY_API_KEY`, và yêu cầu API key đó vì xác thực OAuth/keyring Factory cục bộ không thể mang vào container. Nó dùng mục registry `droid exec --output-format acp` tích hợp của ACPX.
- Biến thể Docker OpenCode là một lane hồi quy một tác tử nghiêm ngặt. Nó ghi model mặc định `OPENCODE_CONFIG_CONTENT` tạm thời từ `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (mặc định `opencode/kimi-k2.6`) sau khi nạp `~/.profile`, và `pnpm test:docker:live-acp-bind:opencode` yêu cầu transcript assistant đã bind thay vì chấp nhận bỏ qua sau bind chung.
- Các lệnh gọi CLI `acpx` trực tiếp chỉ là đường dẫn thủ công/giải pháp tạm thời để so sánh hành vi bên ngoài Gateway. Smoke bind ACP Docker kiểm thử backend runtime `acpx` nhúng của OpenClaw.
- Nó source `~/.profile`, stage vật liệu xác thực CLI tương ứng vào container, rồi cài đặt CLI trực tiếp được yêu cầu (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid qua `https://app.factory.ai/cli`, `@google/gemini-cli`, hoặc `opencode-ai`) nếu còn thiếu. Bản thân backend ACP là gói `acpx/runtime` được nhúng từ Plugin `acpx` chính thức.
- Biến thể Docker của Droid stage `~/.factory` cho phần cài đặt, chuyển tiếp `FACTORY_API_KEY`, và yêu cầu khóa API đó vì xác thực OAuth/keyring cục bộ của Factory không thể chuyển nguyên trạng vào container. Nó dùng mục sổ đăng ký tích hợp sẵn `droid exec --output-format acp` của ACPX.
- Biến thể Docker của OpenCode là một lane hồi quy nghiêm ngặt cho một tác tử. Nó ghi mô hình mặc định `OPENCODE_CONFIG_CONTENT` tạm thời từ `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (mặc định `opencode/kimi-k2.6`) sau khi source `~/.profile`, và `pnpm test:docker:live-acp-bind:opencode` yêu cầu transcript trợ lý đã bind thay vì chấp nhận bỏ qua sau bind chung.
- Các lệnh gọi CLI `acpx` trực tiếp chỉ là đường dẫn thủ công/giải pháp vòng để so sánh hành vi bên ngoài Gateway. Smoke bind ACP Docker kiểm tra backend runtime `acpx` được nhúng của OpenClaw.
## Live: smoke harness app-server Codex
## Trực tiếp: smoke harness app-server Codex
- Mục tiêu: xác thực harness Codex do Plugin sở hữu qua phương thức gateway
- Mục tiêu: xác thực harness Codex do Plugin sở hữu thông qua phương thức gateway
`agent` thông thường:
- tải Plugin `codex` được đóng gói
- tải Plugin `codex` đi kèm
- chọn `OPENCLAW_AGENT_RUNTIME=codex`
- gửi lượt tác tử gateway đầu tiên tới `openai/gpt-5.5` với harness Codex được ép dùng
- gửi lượt tác tử gateway đầu tiên tới `openai/gpt-5.5` với harness Codex bị ép dùng
- gửi lượt thứ hai tới cùng phiên OpenClaw và xác minh thread app-server
có thể tiếp tục
- chạy `/codex status` và `/codex models` qua cùng đường dẫn lệnh gateway
- tùy chọn chạy hai probe shell nâng quyền đã được Guardian đánh giá: một
lệnh lành tính nên được phê duyệt và một lượt tải lên secret giả nên bị
- tùy chọn chạy hai phép dò shell nâng quyền đã được Guardian xem xét: một lệnh lành tính
nên được phê duyệt và một lượt tải lên khóa bí mật giả nên bị
từ chối để tác tử hỏi lại
- Kiểm thử: `src/gateway/gateway-codex-harness.live.test.ts`
- Bật: `OPENCLAW_LIVE_CODEX_HARNESS=1`
- Model mặc định: `openai/gpt-5.5`
- Probe hình ảnh tùy chọn: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- Probe MCP/công cụ tùy chọn: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- Probe Guardian tùy chọn: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- Smoke dùng `agentRuntime.id: "codex"` để một harness Codex hỏng không thể
vượt qua bằng cách âm thầm fallback sang PI.
- Xác thực: xác thực app-server Codex từ đăng nhập đăng ký Codex cục bộ. Các
smoke Docker cũng có thể cung cấp `OPENAI_API_KEY` cho các probe không phải Codex khi áp dụng,
cùng với `~/.codex/auth.json` và `~/.codex/config.toml` được sao chép tùy chọn.
- Mô hình mặc định: `openai/gpt-5.5`
- Phép dò hình ảnh tùy chọn: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- Phép dò MCP/công cụ tùy chọn: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- Phép dò Guardian tùy chọn: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- Smoke dùng `agentRuntime.id: "codex"` để một harness Codex bị hỏng không thể
vượt qua bằng cách âm thầm fallback về PI.
- Xác thực: xác thực app-server Codex từ đăng nhập thuê bao Codex cục bộ. Các
smoke Docker cũng có thể cung cấp `OPENAI_API_KEY` cho các phép dò không phải Codex khi áp dụng,
cùng với tùy chọn sao chép `~/.codex/auth.json` và `~/.codex/config.toml`.
Công thức cục bộ:
@ -324,61 +333,61 @@ pnpm test:docker:live-codex-harness
Ghi chú Docker:
- Runner Docker nằm tại `scripts/test-live-codex-harness-docker.sh`.
- Runner nạp `~/.profile` đã mount, truyền `OPENAI_API_KEY`, sao chép các tệp xác thực CLI Codex
khi có, cài `@openai/codex` vào một prefix npm đã mount có thể ghi,
chuẩn bị cây mã nguồn, rồi chỉ chạy kiểm thử live Codex-harness.
- Docker bật các probe hình ảnh, MCP/công cụ, và Guardian theo mặc định. Đặt
- Trình chạy Docker nằm tại `scripts/test-live-codex-harness-docker.sh`.
- Nó source `~/.profile` đã mount, truyền `OPENAI_API_KEY`, sao chép các tệp xác thực CLI Codex
khi có, cài đặt `@openai/codex` vào một prefix npm đã mount có thể ghi,
stage cây mã nguồn, rồi chỉ chạy kiểm thử trực tiếp harness Codex.
- Docker bật mặc định các phép dò hình ảnh, MCP/công cụ và Guardian. Đặt
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` hoặc
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` hoặc
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` khi bạn cần một lượt chạy debug
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` khi bạn cần một lượt chạy gỡ lỗi
hẹp hơn.
- Docker dùng cùng cấu hình runtime Codex tường minh, nên alias cũ hoặc fallback PI
không thể che giấu một hồi quy harness Codex.
- Docker dùng cùng cấu hình runtime Codex tường minh, nên các bí danh cũ hoặc fallback PI
không thể che khuất hồi quy harness Codex.
### Công thức live được khuyến nghị
### Công thức trực tiếp được khuyến nghị
Allowlist hẹp, tường minh là nhanh nhất và ít flaky nhất:
- Một model, trực tiếp (không qua gateway):
- Một mô hình, trực tiếp (không qua gateway):
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`
- Một model, smoke gateway:
- Một mô hình, smoke gateway:
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Gọi công cụ trên nhiều nhà cung cấp:
- Gọi công cụ trên nhiều provider:
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Tập trung Google (Gemini API key + Antigravity):
- Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Tập trung vào Google (khóa API Gemini + Antigravity):
- Gemini (khóa API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Smoke tư duy thích ứng Google:
- Nếu khóa cục bộ nằm trong hồ sơ shell: `source ~/.profile`
- Gemini 3 mặc định động: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Smoke adaptive thinking của Google:
- Nếu khóa cục bộ nằm trong shell profile: `source ~/.profile`
- Mặc định động Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Ngân sách động Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
Ghi chú:
- `google/...` dùng Gemini API (API key).
- `google/...` dùng Gemini API (khóa API).
- `google-antigravity/...` dùng cầu nối OAuth Antigravity (endpoint tác tử kiểu Cloud Code Assist).
- `google-gemini-cli/...` dùng CLI Gemini cục bộ trên máy của bạn (xác thực riêng + các đặc thù công cụ).
- `google-gemini-cli/...` dùng CLI Gemini cục bộ trên máy của bạn (xác thực riêng + đặc thù công cụ riêng).
- Gemini API so với Gemini CLI:
- API: OpenClaw gọi Gemini API được Google lưu trữ qua HTTP (API key / xác thực hồ sơ); đây là điều hầu hết người dùng muốn nói khi nhắc đến “Gemini”.
- CLI: OpenClaw gọi ra một binary `gemini` cục bộ; nó có xác thực riêng và có thể hành xử khác (hỗ trợ streaming/công cụ/độ lệch phiên bản).
- API: OpenClaw gọi Gemini API được Google lưu trữ qua HTTP (khóa API / xác thực hồ sơ); đây là điều hầu hết người dùng muốn nói khi nói “Gemini”.
- CLI: OpenClaw shell out tới binary `gemini` cục bộ; nó có xác thực riêng và có thể hành xử khác (hỗ trợ streaming/công cụ/lệch phiên bản).
## Live: ma trận model (phạm vi bao phủ)
## Trực tiếp: ma trận mô hình (những gì chúng ta bao phủ)
Không có “danh sách model CI” cố định (live là opt-in), nhưng đây là các model **được khuyến nghị** để bao phủ thường xuyên trên máy phát triển có khóa.
Không có “danh sách mô hình CI” cố định (trực tiếp là opt-in), nhưng đây là các mô hình **được khuyến nghị** để bao phủ thường xuyên trên máy phát triển có khóa.
### Bộ smoke hiện đại (gọi công cụ + hình ảnh)
Đây là lượt chạy “model phổ biến” mà chúng tôi kỳ vọng tiếp tục hoạt động:
Đây là lượt chạy “mô hình phổ biến” mà chúng ta kỳ vọng duy trì hoạt động:
- OpenAI (không phải Codex): `openai/gpt-5.5`
- OpenAI Codex OAuth: `openai-codex/gpt-5.5`
- Anthropic: `anthropic/claude-opus-4-6` (hoặc `anthropic/claude-sonnet-4-6`)
- Google (Gemini API): `google/gemini-3.1-pro-preview` và `google/gemini-3-flash-preview` (tránh các model Gemini 2.x cũ hơn)
- Google (Gemini API): `google/gemini-3.1-pro-preview` và `google/gemini-3-flash-preview` (tránh các mô hình Gemini 2.x cũ hơn)
- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` và `google-antigravity/gemini-3-flash`
- DeepSeek: `deepseek/deepseek-v4-flash` và `deepseek/deepseek-v4-pro`
- Z.AI (GLM): `zai/glm-5.1`
@ -387,9 +396,9 @@ Không có “danh sách model CI” cố định (live là opt-in), nhưng đâ
Chạy smoke gateway với công cụ + hình ảnh:
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
### Baseline: gọi công cụ (Read + Exec tùy chọn)
### Đường cơ sở: gọi công cụ (Read + Exec tùy chọn)
Chọn ít nhất một model cho mỗi nhóm nhà cung cấp:
Chọn ít nhất một cho mỗi họ provider:
- OpenAI: `openai/gpt-5.5`
- Anthropic: `anthropic/claude-opus-4-6` (hoặc `anthropic/claude-sonnet-4-6`)
@ -398,76 +407,76 @@ Chọn ít nhất một model cho mỗi nhóm nhà cung cấp:
- Z.AI (GLM): `zai/glm-5.1`
- MiniMax: `minimax/MiniMax-M2.7`
Phạm vi bổ sung tùy chọn (nên có):
Phạm vi bao phủ bổ sung tùy chọn (nên có):
- xAI: `xai/grok-4.3` (hoặc bản mới nhất có sẵn)
- Mistral: `mistral/`… (chọn một model có khả năng “tools” mà bạn đã bật)
- Mistral: `mistral/`… (chọn một mô hình có khả năng “công cụ” mà bạn đã bật)
- Cerebras: `cerebras/`… (nếu bạn có quyền truy cập)
- LM Studio: `lmstudio/`… (cục bộ; gọi công cụ phụ thuộc vào chế độ API)
### Vision: gửi hình ảnh (tệp đính kèm → tin nhắn đa phương thức)
### Thị giác: gửi hình ảnh (tệp đính kèm → tin nhắn đa phương thức)
Bao gồm ít nhất một model có khả năng xử lý hình ảnh trong `OPENCLAW_LIVE_GATEWAY_MODELS` (các biến thể Claude/Gemini/OpenAI có khả năng vision, v.v.) để kiểm thử probe hình ảnh.
Bao gồm ít nhất một mô hình có khả năng xử lý hình ảnh trong `OPENCLAW_LIVE_GATEWAY_MODELS` (các biến thể có thị giác của Claude/Gemini/OpenAI, v.v.) để kiểm tra phép dò hình ảnh.
### Bộ tổng hợp / gateway thay thế
### Aggregator / gateway thay thế
Nếu bạn đã bật khóa, chúng tôi cũng hỗ trợ kiểm thử qua:
Nếu bạn đã bật khóa, chúng ta cũng hỗ trợ kiểm thử qua:
- OpenRouter: `openrouter/...` (hàng trăm model; dùng `openclaw models scan` để tìm ứng viên có khả năng công cụ+hình ảnh)
- OpenRouter: `openrouter/...` (hàng trăm mô hình; dùng `openclaw models scan` để tìm các ứng viên có khả năng công cụ+hình ảnh)
- OpenCode: `opencode/...` cho Zen và `opencode-go/...` cho Go (xác thực qua `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
Các nhà cung cấp khác bạn có thể đưa vào ma trận live (nếu có thông tin xác thực/cấu hình):
Thêm các provider bạn có thể đưa vào ma trận trực tiếp (nếu bạn có thông tin xác thực/cấu hình):
- Tích hợp sẵn: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
- Qua `models.providers` (endpoint tùy chỉnh): `minimax` (cloud/API), cùng bất kỳ proxy tương thích OpenAI/Anthropic nào (LM Studio, vLLM, LiteLLM, v.v.)
- Qua `models.providers` (endpoint tùy chỉnh): `minimax` (cloud/API), cộng với bất kỳ proxy tương thích OpenAI/Anthropic nào (LM Studio, vLLM, LiteLLM, v.v.)
<Tip>
Không hardcode "all models" trong tài liệu. Danh sách có thẩm quyền là bất kỳ thứ gì `discoverModels(...)` trả về trên máy của bạn cộng với các khóa hiện có.
Đừng mã hóa cứng "tất cả mô hình" trong tài liệu. Danh sách có thẩm quyền là bất cứ thứ gì `discoverModels(...)` trả về trên máy của bạn cộng với các khóa có sẵn.
</Tip>
## Thông tin xác thực (không bao giờ commit)
Các kiểm thử live phát hiện thông tin xác thực theo cùng cách CLI làm. Hệ quả thực tế:
Kiểm thử trực tiếp phát hiện thông tin xác thực theo cùng cách CLI làm. Hệ quả thực tế:
- Nếu CLI hoạt động, các kiểm thử trực tiếp sẽ tìm thấy cùng các khóa.
- Nếu một kiểm thử trực tiếp báo “không có thông tin xác thực”, hãy gỡ lỗi theo cùng cách bạn gỡ lỗi `openclaw models list` / lựa chọn mô hình.
- Nếu một kiểm thử trực tiếp báo “no creds”, hãy debug theo cùng cách bạn debug `openclaw models list` / lựa chọn mô hình.
- Hồ sơ xác thực theo từng tác nhân: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (đây là ý nghĩa của “khóa hồ sơ” trong các kiểm thử trực tiếp)
- Hồ sơ xác thực theo từng agent: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (đây là ý nghĩa của “profile keys” trong các kiểm thử trực tiếp)
- Cấu hình: `~/.openclaw/openclaw.json` (hoặc `OPENCLAW_CONFIG_PATH`)
- Thư mục trạng thái cũ: `~/.openclaw/credentials/` (được sao chép vào thư mục home trực tiếp dàn dựng khi có, nhưng không phải kho khóa hồ sơ chính)
- Các lần chạy trực tiếp cục bộ mặc định sao chép cấu hình đang hoạt động, các tệp `auth-profiles.json` theo từng tác nhân, `credentials/` cũ, và các thư mục xác thực CLI bên ngoài được hỗ trợ vào một thư mục home kiểm thử tạm; các thư mục home trực tiếp dàn dựng bỏ qua `workspace/` và `sandboxes/`, đồng thời các ghi đè đường dẫn `agents.*.workspace` / `agentDir` bị loại bỏ để các phép dò không chạm vào không gian làm việc máy chủ thật của bạn.
- Thư mục trạng thái legacy: `~/.openclaw/credentials/` (được sao chép vào live home tạm khi có, nhưng không phải kho lưu trữ profile-key chính)
- Các lần chạy trực tiếp cục bộ mặc định sao chép cấu hình đang hoạt động, các tệp `auth-profiles.json` theo từng agent, `credentials/` legacy, và các thư mục xác thực CLI bên ngoài được hỗ trợ vào một test home tạm; các live home đã staging bỏ qua `workspace/` và `sandboxes/`, đồng thời các ghi đè đường dẫn `agents.*.workspace` / `agentDir` bị loại bỏ để các phép probe không chạm vào workspace thật trên máy chủ của bạn.
Nếu bạn muốn dựa vào khóa môi trường (ví dụ được xuất trong `~/.profile` của bạn), hãy chạy kiểm thử cục bộ sau khi `source ~/.profile`, hoặc dùng các trình chạy Docker bên dưới (chúng có thể gắn `~/.profile` vào container).
Nếu bạn muốn dựa vào các khóa env (ví dụ được export trong `~/.profile`), hãy chạy kiểm thử cục bộ sau `source ~/.profile`, hoặc dùng các Docker runner bên dưới (chúng có thể mount `~/.profile` vào container).
## Deepgram trực tiếp (phiên âm âm thanh)
- Kiểm thử: `extensions/deepgram/audio.live.test.ts`
- Bật: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
## Kế hoạch mã hóa BytePlus trực tiếp
## BytePlus trực tiếp cho kế hoạch coding
- Kiểm thử: `extensions/byteplus/live.test.ts`
- Bật: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
- Ghi đè mô hình tùy chọn: `BYTEPLUS_CODING_MODEL=ark-code-latest`
## Media quy trình làm việc ComfyUI trực tiếp
## ComfyUI trực tiếp cho phương tiện workflow
- Kiểm thử: `extensions/comfy/comfy.live.test.ts`
- Bật: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- Phạm vi:
- Thực thi các đường dẫn hình ảnh, video và `music_generate` comfy đi kèm
- Kiểm tra các đường dẫn image, video và `music_generate` của comfy đi kèm
- Bỏ qua từng năng lực trừ khi `plugins.entries.comfy.config.<capability>` được cấu hình
- Hữu ích sau khi thay đổi việc gửi quy trình làm việc comfy, thăm dò, tải xuống hoặc đăng ký Plugin
- Hữu ích sau khi thay đổi thao tác gửi workflow comfy, polling, tải xuống, hoặc đăng ký Plugin
## Tạo hình ảnh trực tiếp
- Kiểm thử: `test/image-generation.runtime.live.test.ts`
- Lệnh: `pnpm test:live test/image-generation.runtime.live.test.ts`
- Bộ kiểm thử: `pnpm test:live:media image`
- Harness: `pnpm test:live:media image`
- Phạm vi:
- Liệt kê mọi Plugin nhà cung cấp tạo hình ảnh đã đăng ký
- Tải các biến môi trường nhà cung cấp còn thiếu từ shell đăng nhập của bạn (`~/.profile`) trước khi dò
- Mặc định dùng các khóa API trực tiếp/môi trường trước các hồ sơ xác thực đã lưu, để các khóa kiểm thử cũ trong `auth-profiles.json` không che khuất thông tin xác thực shell thật
- Tải các biến env còn thiếu của nhà cung cấp từ login shell của bạn (`~/.profile`) trước khi probe
- Mặc định dùng khóa API trực tiếp/env trước các hồ sơ xác thực đã lưu, để các khóa kiểm thử cũ trong `auth-profiles.json` không che khuất thông tin đăng nhập shell thật
- Bỏ qua các nhà cung cấp không có xác thực/hồ sơ/mô hình dùng được
- Chạy từng nhà cung cấp đã cấu hình qua runtime tạo hình ảnh dùng chung:
- `<provider>:generate`
@ -487,9 +496,9 @@ Nếu bạn muốn dựa vào khóa môi trường (ví dụ được xuất tro
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
- Hành vi xác thực tùy chọn:
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để buộc xác thực kho hồ sơ và bỏ qua các ghi đè chỉ dùng môi trường
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để buộc xác thực bằng kho hồ sơ và bỏ qua các ghi đè chỉ có env
Đối với đường dẫn CLI đã phát hành, hãy thêm một kiểm thử khói `infer` sau khi kiểm thử trực tiếp nhà cung cấp/runtime đạt:
Đối với đường dẫn CLI đã phát hành, hãy thêm một smoke `infer` sau khi kiểm thử trực tiếp nhà cung cấp/runtime vượt qua:
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@ -501,25 +510,25 @@ openclaw infer image generate \
--json
```
Việc này bao phủ phân tích đối số CLI, phân giải cấu hình/tác nhân mặc định, kích hoạt
Plugin đi kèm, runtime tạo hình ảnh dùng chung và yêu cầu nhà cung cấp trực tiếp.
Các phụ thuộc Plugin được kỳ vọng có sẵn trước khi tải runtime.
Phần này bao phủ phân tích đối số CLI, phân giải cấu hình/default-agent, kích hoạt
Plugin đi kèm, runtime tạo hình ảnh dùng chung, và yêu cầu trực tiếp tới nhà cung cấp.
Các dependency của Plugin được kỳ vọng đã có trước khi tải runtime.
## Tạo nhạc trực tiếp
- Kiểm thử: `extensions/music-generation-providers.live.test.ts`
- Bật: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- Bộ kiểm thử: `pnpm test:live:media music`
- Harness: `pnpm test:live:media music`
- Phạm vi:
- Thực thi đường dẫn nhà cung cấp tạo nhạc đi kèm dùng chung
- Kiểm tra đường dẫn nhà cung cấp tạo nhạc đi kèm dùng chung
- Hiện bao phủ Google và MiniMax
- Tải các biến môi trường nhà cung cấp từ shell đăng nhập của bạn (`~/.profile`) trước khi dò
- Mặc định dùng các khóa API trực tiếp/môi trường trước các hồ sơ xác thực đã lưu, để các khóa kiểm thử cũ trong `auth-profiles.json` không che khuất thông tin xác thực shell thật
- Tải các biến env của nhà cung cấp từ login shell của bạn (`~/.profile`) trước khi probe
- Mặc định dùng khóa API trực tiếp/env trước các hồ sơ xác thực đã lưu, để các khóa kiểm thử cũ trong `auth-profiles.json` không che khuất thông tin đăng nhập shell thật
- Bỏ qua các nhà cung cấp không có xác thực/hồ sơ/mô hình dùng được
- Chạy cả hai chế độ runtime đã khai báo khi có:
- `generate` với đầu vào chỉ có lời nhắc
- `generate` với đầu vào chỉ có prompt
- `edit` khi nhà cung cấp khai báo `capabilities.edit.enabled`
- Phạm vi bao phủ làn dùng chung hiện tại:
- Phạm vi bao phủ lane dùng chung hiện tại:
- `google`: `generate`, `edit`
- `minimax`: `generate`
- `comfy`: tệp trực tiếp Comfy riêng, không thuộc lượt quét dùng chung này
@ -527,51 +536,51 @@ Các phụ thuộc Plugin được kỳ vọng có sẵn trước khi tải runt
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
- Hành vi xác thực tùy chọn:
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để buộc xác thực kho hồ sơ và bỏ qua các ghi đè chỉ dùng môi trường
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để buộc xác thực bằng kho hồ sơ và bỏ qua các ghi đè chỉ có env
## Tạo video trực tiếp
- Kiểm thử: `extensions/video-generation-providers.live.test.ts`
- Bật: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- Bộ kiểm thử: `pnpm test:live:media video`
- Harness: `pnpm test:live:media video`
- Phạm vi:
- Thực thi đường dẫn nhà cung cấp tạo video đi kèm dùng chung
- Mặc định dùng đường dẫn kiểm thử khói an toàn cho phát hành: các nhà cung cấp không phải FAL, một yêu cầu văn bản-thành-video cho mỗi nhà cung cấp, lời nhắc tôm hùm một giây, và giới hạn thao tác theo từng nhà cung cấp từ `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (mặc định `180000`)
- Kiểm tra đường dẫn nhà cung cấp tạo video đi kèm dùng chung
- Mặc định dùng đường dẫn smoke an toàn cho phát hành: các nhà cung cấp không phải FAL, một yêu cầu text-to-video cho mỗi nhà cung cấp, prompt lobster dài một giây, và giới hạn thao tác theo từng nhà cung cấp từ `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (mặc định là `180000`)
- Mặc định bỏ qua FAL vì độ trễ hàng đợi phía nhà cung cấp có thể chiếm phần lớn thời gian phát hành; truyền `--video-providers fal` hoặc `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` để chạy rõ ràng
- Tải các biến môi trường nhà cung cấp từ shell đăng nhập của bạn (`~/.profile`) trước khi dò
- Mặc định dùng các khóa API trực tiếp/môi trường trước các hồ sơ xác thực đã lưu, để các khóa kiểm thử cũ trong `auth-profiles.json` không che khuất thông tin xác thực shell thật
- Tải các biến env của nhà cung cấp từ login shell của bạn (`~/.profile`) trước khi probe
- Mặc định dùng khóa API trực tiếp/env trước các hồ sơ xác thực đã lưu, để các khóa kiểm thử cũ trong `auth-profiles.json` không che khuất thông tin đăng nhập shell thật
- Bỏ qua các nhà cung cấp không có xác thực/hồ sơ/mô hình dùng được
- Mặc định chỉ chạy `generate`
- Đặt `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` để cũng chạy các chế độ chuyển đổi đã khai báo khi có:
- `imageToVideo` khi nhà cung cấp khai báo `capabilities.imageToVideo.enabled` và nhà cung cấp/mô hình đã chọn chấp nhận đầu vào hình ảnh cục bộ dựa trên bộ đệm trong lượt quét dùng chung
- `videoToVideo` khi nhà cung cấp khai báo `capabilities.videoToVideo.enabled` và nhà cung cấp/mô hình đã chọn chấp nhận đầu vào video cục bộ dựa trên bộ đệm trong lượt quét dùng chung
- `imageToVideo` khi nhà cung cấp khai báo `capabilities.imageToVideo.enabled` và nhà cung cấp/mô hình được chọn chấp nhận đầu vào hình ảnh cục bộ dựa trên buffer trong lượt quét dùng chung
- `videoToVideo` khi nhà cung cấp khai báo `capabilities.videoToVideo.enabled` và nhà cung cấp/mô hình được chọn chấp nhận đầu vào video cục bộ dựa trên buffer trong lượt quét dùng chung
- Các nhà cung cấp `imageToVideo` đã khai báo nhưng bị bỏ qua hiện tại trong lượt quét dùng chung:
- `vydra` vì `veo3` đi kèm chỉ hỗ trợ văn bản và `kling` đi kèm yêu cầu URL hình ảnh từ xa
- Phạm vi bao phủ Vydra theo nhà cung cấp:
- `vydra` vì `veo3` đi kèm chỉ hỗ trợ text và `kling` đi kèm yêu cầu URL hình ảnh từ xa
- Phạm vi bao phủ riêng cho Vydra:
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- tệp đó chạy văn bản-thành-video `veo3` cùng một làn `kling` mặc định dùng fixture URL hình ảnh từ xa
- tệp đó chạy `veo3` text-to-video cùng một lane `kling` mặc định dùng fixture URL hình ảnh từ xa
- Phạm vi bao phủ trực tiếp `videoToVideo` hiện tại:
- chỉ `runway` khi mô hình đã chọn là `runway/gen4_aleph`
- chỉ `runway` khi mô hình được chọn là `runway/gen4_aleph`
- Các nhà cung cấp `videoToVideo` đã khai báo nhưng bị bỏ qua hiện tại trong lượt quét dùng chung:
- `alibaba`, `qwen`, `xai` vì các đường dẫn đó hiện yêu cầu URL tham chiếu `http(s)` / MP4 từ xa
- `google` vì làn Gemini/Veo dùng chung hiện tại dùng đầu vào cục bộ dựa trên bộ đệm và đường dẫn đó không được chấp nhận trong lượt quét dùng chung
- `openai` vì làn dùng chung hiện tại thiếu bảo đảm truy cập inpaint/remix video theo tổ chức
- `google` vì lane Gemini/Veo dùng chung hiện tại dùng đầu vào cục bộ dựa trên buffer và đường dẫn đó không được chấp nhận trong lượt quét dùng chung
- `openai` vì lane dùng chung hiện tại thiếu bảo đảm quyền truy cập inpaint/remix video theo từng org
- Thu hẹp tùy chọn:
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` để đưa mọi nhà cung cấp vào lượt quét mặc định, bao gồm FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` để giảm giới hạn mỗi thao tác của nhà cung cấp cho một lượt kiểm thử khói quyết liệt
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` để bao gồm mọi nhà cung cấp trong lượt quét mặc định, gồm cả FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` để giảm giới hạn từng thao tác của nhà cung cấp cho một lượt smoke quyết liệt
- Hành vi xác thực tùy chọn:
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để buộc xác thực kho hồ sơ và bỏ qua các ghi đè chỉ dùng môi trường
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để buộc xác thực bằng kho hồ sơ và bỏ qua các ghi đè chỉ có env
## Bộ kiểm thử media trực tiếp
## Harness trực tiếp cho phương tiện
- Lệnh: `pnpm test:live:media`
- Mục đích:
- Chạy các bộ kiểm thử trực tiếp hình ảnh, nhạc và video dùng chung qua một điểm vào gốc repo
- Tự động tải các biến môi trường nhà cung cấp còn thiếu từ `~/.profile`
- Mặc định tự động thu hẹp từng bộ kiểm thử còn các nhà cung cấp hiện có xác thực dùng được
- Tái sử dụng `scripts/test-live.mjs`, để hành vi Heartbeat và chế độ yên lặng luôn nhất quán
- Chạy các bộ kiểm thử trực tiếp dùng chung cho image, music và video qua một entrypoint gốc của repo
- Tự động tải các biến env còn thiếu của nhà cung cấp từ `~/.profile`
- Mặc định tự động thu hẹp từng bộ kiểm thử tới các nhà cung cấp hiện có xác thực dùng được
- Tái sử dụng `scripts/test-live.mjs`, để hành vi Heartbeat và chế độ quiet luôn nhất quán
- Ví dụ:
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`
@ -580,4 +589,4 @@ Các phụ thuộc Plugin được kỳ vọng có sẵn trước khi tải runt
## Liên quan
- [Kiểm thử](/vi/help/testing) — các bộ kiểm thử đơn vị, tích hợp, QA và Docker
- [Kiểm thử](/vi/help/testing) — các bộ unit, integration, QA và Docker

203
docs/vi/help/testing-updates-plugins.md
View File

@ -1,34 +1,48 @@
---
read_when:
- Thay đổi hành vi cập nhật OpenClaw, doctor, chấp nhận gói hoặc cài đặt Plugin
- Chuẩn bị hoặc phê duyệt một ứng viên phát hành
- Gỡ lỗi các hồi quy về cập nhật gói, dọn dẹp phụ thuộc Plugin hoặc cài đặt Plugin
- Chuẩn bị hoặc phê duyệt bản phát hành ứng viên
- Gỡ lỗi cập nhật gói, dọn dẹp phụ thuộc Plugin hoặc lỗi hồi quy cài đặt Plugin
sidebarTitle: Update and plugin tests
summary: Cách OpenClaw kiểm chứng các lộ trình cập nhật, quá trình di chuyển gói và hành vi cài đặt/cập nhật Plugin
summary: Cách OpenClaw xác thực các đường dẫn cập nhật, quá trình di chuyển gói và hành vi cài đặt/cập nhật Plugin
title: 'Kiểm thử: bản cập nhật và Plugin'
x-i18n:
generated_at: "2026-05-03T10:38:00Z"
generated_at: "2026-05-05T01:48:09Z"
model: gpt-5.5
provider: openai
source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd
source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286
source_path: help/testing-updates-plugins.md
workflow: 16
---
Đây là danh sách kiểm tra chuyên dụng cho xác thực cập nhật và Plugin. Mục tiêu rất đơn giản: chứng minh gói có thể cài đặt có thể cập nhật trạng thái người dùng thực, sửa chữa trạng thái kế thừa đã cũ thông qua `doctor`, và vẫn cài đặt, tải, cập nhật, và gỡ cài đặt Plugin từ các nguồn được hỗ trợ.
Đây là danh sách kiểm tra chuyên biệt cho việc xác thực cập nhật và Plugin. Mục tiêu
đơn giản: chứng minh gói có thể cài đặt có thể cập nhật trạng thái người dùng thực,
sửa trạng thái kế thừa đã cũ thông qua `doctor`, và vẫn cài đặt, tải, cập nhật,
cũng như gỡ cài đặt Plugin từ các nguồn được hỗ trợ.
Để xem bản đồ trình chạy kiểm thử rộng hơn, hãy xem [Kiểm thử](/vi/help/testing). Đối với khóa nhà cung cấp trực tiếp và các bộ kiểm thử chạm mạng, hãy xem [Kiểm thử trực tiếp](/vi/help/testing-live).
Để xem bản đồ bộ chạy kiểm thử rộng hơn, hãy xem [Kiểm thử](/vi/help/testing). Để biết
các khóa nhà cung cấp trực tiếp và các bộ kiểm thử chạm tới mạng, hãy xem
[Kiểm thử trực tiếp](/vi/help/testing-live).
## Những gì chúng ta bảo vệ
Các kiểm thử cập nhật và Plugin bảo vệ các hợp đồng này:
Các kiểm thử cập nhật và Plugin bảo vệ những hợp đồng này:
- Một tarball gói phải đầy đủ, có `dist/postinstall-inventory.json` hợp lệ, và không phụ thuộc vào các tệp repo chưa được đóng gói.
- Người dùng có thể chuyển từ một gói đã phát hành cũ hơn sang gói ứng viên mà không mất cấu hình, tác tử, phiên, workspace, danh sách cho phép Plugin, hoặc cấu hình kênh.
- `openclaw doctor --fix --non-interactive` sở hữu các đường dẫn dọn dẹp và sửa chữa kế thừa. Khởi động không nên phát triển các migration tương thích ẩn cho trạng thái Plugin đã cũ.
- Cài đặt Plugin hoạt động từ thư mục cục bộ, repo git, gói npm, và đường dẫn registry ClawHub.
- Các phụ thuộc npm của Plugin được cài đặt trong gốc npm được quản lý, được quét trước khi tin cậy, và được loại bỏ thông qua npm trong quá trình gỡ cài đặt để các phụ thuộc được hoist không còn sót lại.
- Cập nhật Plugin ổn định khi không có gì thay đổi: bản ghi cài đặt, nguồn đã phân giải, bố cục phụ thuộc đã cài đặt, và trạng thái bật vẫn nguyên vẹn.
- Tarball của gói là đầy đủ, có `dist/postinstall-inventory.json` hợp lệ,
và không phụ thuộc vào các tệp repo chưa được đóng gói.
- Người dùng có thể chuyển từ một gói đã phát hành cũ hơn sang gói ứng viên
mà không mất cấu hình, agent, phiên, workspace, danh sách cho phép Plugin,
hoặc cấu hình kênh.
- `openclaw doctor --fix --non-interactive` sở hữu các đường dẫn dọn dẹp và sửa chữa
kế thừa. Khởi động không nên phát sinh các migration tương thích ẩn cho trạng thái
Plugin đã cũ.
- Cài đặt Plugin hoạt động từ thư mục cục bộ, repo git, gói npm, và đường dẫn
registry ClawHub.
- Các phụ thuộc npm của Plugin được cài đặt trong npm root được quản lý, được quét
trước khi tin cậy, và được gỡ bỏ thông qua npm trong quá trình gỡ cài đặt để
các phụ thuộc đã hoist không còn sót lại.
- Cập nhật Plugin ổn định khi không có gì thay đổi: bản ghi cài đặt, nguồn đã
phân giải, bố cục phụ thuộc đã cài đặt, và trạng thái bật vẫn nguyên vẹn.
## Bằng chứng cục bộ trong quá trình phát triển
@ -40,25 +54,30 @@ pnpm check:changed
pnpm test:changed
```
Đối với thay đổi về cài đặt, gỡ cài đặt, phụ thuộc, hoặc kiểm kê gói của Plugin, cũng chạy các kiểm thử tập trung bao phủ ranh giới đã chỉnh sửa:
Đối với các thay đổi về cài đặt, gỡ cài đặt, phụ thuộc, hoặc inventory gói của
Plugin, cũng chạy các kiểm thử tập trung bao phủ ranh giới đã chỉnh sửa:
```bash
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
```
Trước khi bất kỳ lane Docker gói nào tiêu thụ một tarball, hãy chứng minh artifact gói:
Trước khi bất kỳ lane Docker gói nào tiêu thụ tarball, hãy chứng minh artifact gói:
```bash
pnpm release:check
```
`release:check` chạy các kiểm tra drift cấu hình/tài liệu/API, ghi kiểm kê dist của gói, chạy `npm pack --dry-run`, từ chối các tệp bị cấm trong gói, cài đặt tarball vào một tiền tố tạm, chạy postinstall, và kiểm tra khói các entrypoint kênh đi kèm.
`release:check` chạy các kiểm tra độ lệch cấu hình/tài liệu/API, ghi inventory dist
của gói, chạy `npm pack --dry-run`, từ chối các tệp bị cấm đã được đóng gói, cài đặt
tarball vào một prefix tạm, chạy postinstall, và smoke các entrypoint kênh được bundle.
## Các lane Docker
Các lane Docker là bằng chứng ở cấp sản phẩm. Chúng cài đặt hoặc cập nhật một gói thực bên trong container Linux và xác nhận hành vi thông qua lệnh CLI, khởi động Gateway, probe HTTP, trạng thái RPC, và trạng thái hệ thống tệp.
Các lane Docker là bằng chứng ở cấp sản phẩm. Chúng cài đặt hoặc cập nhật một gói thực
bên trong container Linux và xác nhận hành vi thông qua các lệnh CLI, khởi động Gateway,
probe HTTP, trạng thái RPC, và trạng thái hệ thống tệp.
Dùng các lane tập trung khi lặp:
Dùng các lane tập trung trong khi lặp:
```bash
pnpm test:docker:plugins
@ -71,14 +90,33 @@ pnpm test:docker:update-migration
Các lane quan trọng:
- `test:docker:plugins` xác thực kiểm tra khói cài đặt Plugin, cài đặt thư mục cục bộ, hành vi bỏ qua cập nhật thư mục cục bộ, thư mục cục bộ có phụ thuộc được cài đặt sẵn, cài đặt gói `file:`, cài đặt git có thực thi CLI, cập nhật git moving-ref, cài đặt registry npm với phụ thuộc bắc cầu được hoist, no-op cập nhật npm, cài đặt fixture ClawHub cục bộ và no-op cập nhật, hành vi cập nhật marketplace, và bật/kiểm tra Claude-bundle. Đặt `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` để giữ khối ClawHub khép kín/ngoại tuyến.
- `test:docker:plugin-lifecycle-matrix` cài đặt gói ứng viên trong một container trống, chạy một Plugin npm qua cài đặt, kiểm tra, tắt, bật, nâng cấp rõ ràng, hạ cấp rõ ràng, và gỡ cài đặt sau khi xóa mã Plugin. Nó ghi log chỉ số RSS và CPU cho từng pha.
- `test:docker:plugin-update` xác thực rằng một Plugin đã cài đặt không đổi sẽ không cài đặt lại hoặc mất metadata cài đặt trong `openclaw plugins update`.
- `test:docker:upgrade-survivor` cài đặt tarball ứng viên lên trên fixture người dùng cũ bẩn, chạy cập nhật gói cộng với doctor không tương tác, sau đó khởi động Gateway local loopback và kiểm tra bảo toàn trạng thái.
- `test:docker:published-upgrade-survivor` trước tiên cài đặt một baseline đã phát hành, cấu hình nó thông qua một công thức `openclaw config set` được bake sẵn, cập nhật nó lên tarball ứng viên, chạy doctor, kiểm tra dọn dẹp kế thừa, khởi động Gateway, và probe `/healthz`, `/readyz`, và trạng thái RPC.
- `test:docker:update-migration` là lane cập nhật đã phát hành nặng về dọn dẹp. Nó bắt đầu từ trạng thái người dùng kiểu Discord/Telegram đã cấu hình, chạy doctor baseline để các phụ thuộc Plugin đã cấu hình có cơ hội hiện thực hóa, seed phần dư phụ thuộc Plugin kế thừa cho một Plugin đóng gói đã cấu hình, cập nhật lên tarball ứng viên, và yêu cầu doctor sau cập nhật loại bỏ các gốc phụ thuộc kế thừa.
- `test:docker:plugins` xác thực smoke cài đặt Plugin, cài đặt thư mục cục bộ,
hành vi bỏ qua cập nhật của thư mục cục bộ, thư mục cục bộ có phụ thuộc được
cài sẵn, cài đặt gói `file:`, cài đặt git với thực thi CLI, cập nhật tham chiếu
git đang di chuyển, cài đặt registry npm với các phụ thuộc bắc cầu đã hoist,
npm update không thao tác, cài đặt fixture ClawHub cục bộ và update không thao tác,
hành vi cập nhật marketplace, và bật/kiểm tra Claude-bundle. Đặt
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0` để giữ khối ClawHub hermetic/offline.
- `test:docker:plugin-lifecycle-matrix` cài đặt gói ứng viên trong một container trống,
chạy một Plugin npm qua các bước cài đặt, kiểm tra, tắt, bật, nâng cấp rõ ràng,
hạ cấp rõ ràng, và gỡ cài đặt sau khi xóa mã Plugin. Nó ghi log các chỉ số RSS và CPU
cho từng pha.
- `test:docker:plugin-update` xác thực rằng một Plugin đã cài đặt không đổi sẽ không
được cài lại hoặc mất metadata cài đặt trong `openclaw plugins update`.
- `test:docker:upgrade-survivor` cài đặt tarball ứng viên đè lên một fixture người dùng
cũ bẩn, chạy cập nhật gói cùng doctor không tương tác, sau đó khởi động một Gateway
local loopback và kiểm tra việc bảo toàn trạng thái.
- `test:docker:published-upgrade-survivor` trước tiên cài đặt một baseline đã phát hành,
cấu hình nó thông qua một công thức `openclaw config set` đã bake, cập nhật nó lên
tarball ứng viên, chạy doctor, kiểm tra dọn dẹp kế thừa, khởi động Gateway, và probe
`/healthz`, `/readyz`, cùng trạng thái RPC.
- `test:docker:update-migration` là lane cập nhật đã phát hành tập trung nhiều vào dọn dẹp.
Nó bắt đầu từ trạng thái người dùng kiểu Discord/Telegram đã cấu hình, chạy doctor
baseline để các phụ thuộc Plugin đã cấu hình có cơ hội materialize, seed rác phụ thuộc
Plugin kế thừa cho một Plugin đóng gói đã cấu hình, cập nhật lên tarball ứng viên,
và yêu cầu doctor sau cập nhật gỡ bỏ các root phụ thuộc kế thừa.
Các biến thể published-upgrade survivor hữu ích:
Các biến thể upgrade survivor đã phát hành hữu ích:
```bash
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
@ -90,9 +128,16 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor
```
Các kịch bản khả dụng là `base`, `feishu-channel`, `bootstrap-persona`, `plugin-deps-cleanup`, `configured-plugin-installs`, `tilde-log-path`, và `versioned-runtime-deps`. Trong các lần chạy tổng hợp, `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` mở rộng thành tất cả các kịch bản có hình dạng sự cố đã báo cáo, bao gồm migration cài đặt Plugin đã cấu hình.
Các kịch bản khả dụng là `base`, `feishu-channel`, `bootstrap-persona`,
`plugin-deps-cleanup`, `configured-plugin-installs`,
`stale-source-plugin-shadow`, `tilde-log-path`, và `versioned-runtime-deps`. Trong các lượt chạy tổng hợp,
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` mở rộng thành tất cả kịch bản
có dạng vấn đề đã báo cáo, bao gồm migration cài đặt Plugin đã cấu hình.
Migration cập nhật đầy đủ được tách riêng có chủ ý khỏi Full Release CI. Dùng workflow thủ công `Update Migration` khi câu hỏi phát hành là "mọi bản phát hành stable đã công bố từ 2026.4.23 trở đi có thể cập nhật lên ứng viên này và dọn sạch phần dư phụ thuộc Plugin không?":
Migration cập nhật đầy đủ được tách riêng có chủ ý khỏi CI phát hành đầy đủ. Dùng
workflow thủ công `Update Migration` khi câu hỏi phát hành là "mọi bản phát hành
ổn định đã phát hành từ 2026.4.23 trở đi có thể cập nhật lên ứng viên này và dọn
rác phụ thuộc Plugin không?":
```bash
gh workflow run update-migration.yml \
@ -103,20 +148,28 @@ gh workflow run update-migration.yml \
-f scenarios=plugin-deps-cleanup
```
## Package Acceptance
## Chấp nhận gói
Package Acceptance là cổng gói gốc GitHub. Nó phân giải một gói ứng viên thành tarball `package-under-test`, ghi lại phiên bản và SHA-256, sau đó chạy các lane Docker E2E có thể tái sử dụng trên đúng tarball đó. Ref của harness workflow tách biệt với ref nguồn gói, vì vậy logic kiểm thử hiện tại có thể xác thực các bản phát hành tin cậy cũ hơn.
Chấp nhận gói là cổng gói native của GitHub. Nó phân giải một gói ứng viên thành
tarball `package-under-test`, ghi lại phiên bản và SHA-256, rồi chạy các lane Docker E2E
tái sử dụng đối với đúng tarball đó. Ref harness workflow tách biệt với ref nguồn gói,
nên logic kiểm thử hiện tại có thể xác thực các bản phát hành đáng tin cậy cũ hơn.
Nguồn ứng viên:
- `source=npm`: xác thực `openclaw@beta`, `openclaw@latest`, hoặc một phiên bản đã phát hành chính xác.
- `source=ref`: đóng gói một nhánh, tag, hoặc commit tin cậy với harness hiện tại đã chọn.
- `source=npm`: xác thực `openclaw@beta`, `openclaw@latest`, hoặc một phiên bản đã
phát hành chính xác.
- `source=ref`: đóng gói một nhánh, tag, hoặc commit đáng tin cậy với harness hiện tại
đã chọn.
- `source=url`: xác thực một tarball HTTPS với `package_sha256` bắt buộc.
- `source=artifact`: tái sử dụng tarball được tải lên bởi một lần chạy Actions khác.
- `source=artifact`: tái sử dụng tarball do một lượt chạy Actions khác tải lên.
Full Release Validation dùng `source=artifact` theo mặc định, được dựng từ release SHA đã phân giải. Để chứng minh sau phát hành, truyền `package_acceptance_package_spec=openclaw@YYYY.M.D` để cùng ma trận nâng cấp nhắm tới gói npm đã ship.
Xác thực phát hành đầy đủ dùng `source=artifact` theo mặc định, được build từ SHA
phát hành đã phân giải. Để chứng minh sau phát hành, truyền
`package_acceptance_package_spec=openclaw@YYYY.M.D` để cùng ma trận nâng cấp
nhắm tới gói npm đã được phát hành.
Các kiểm tra phát hành gọi Package Acceptance với bộ package/update/Plugin:
Các kiểm tra phát hành gọi Chấp nhận gói với bộ gói/cập nhật/Plugin:
```text
doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update
@ -130,11 +183,16 @@ published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai
```
Điều này giữ migration gói, chuyển kênh cập nhật, dọn dẹp phụ thuộc Plugin đã cũ, độ bao phủ Plugin ngoại tuyến, hành vi cập nhật Plugin, và QA gói Telegram trên cùng artifact đã phân giải.
Điều này giữ migration gói, chuyển kênh cập nhật, dọn dẹp phụ thuộc Plugin đã cũ,
bao phủ Plugin offline, hành vi cập nhật Plugin, và QA gói Telegram trên cùng một
artifact đã phân giải.
`all-since-2026.4.23` là mẫu nâng cấp Full Release CI: mọi bản phát hành stable đã công bố trên npm từ `2026.4.23` đến `latest`. Để có độ bao phủ migration cập nhật đã phát hành đầy đủ, hãy dùng `all-since-2026.4.23` trong workflow Update Migration riêng thay vì Full Release CI. `release-history` vẫn khả dụng cho việc lấy mẫu rộng hơn thủ công khi bạn cũng muốn anchor kế thừa trước ngày đó.
`all-since-2026.4.23` là mẫu nâng cấp của CI phát hành đầy đủ: mọi bản phát hành ổn định đã phát hành lên npm từ `2026.4.23` đến `latest`. Để bao phủ migration
cập nhật đã phát hành một cách toàn diện, dùng `all-since-2026.4.23` trong workflow
Update Migration riêng thay vì CI phát hành đầy đủ. `release-history` vẫn khả dụng
cho việc lấy mẫu rộng hơn thủ công khi bạn cũng muốn neo ngày trước kế thừa.
Chạy thủ công một hồ sơ gói khi xác thực ứng viên trước phát hành:
Chạy hồ sơ gói thủ công khi xác thực ứng viên trước phát hành:
```bash
gh workflow run package-acceptance.yml \
@ -148,49 +206,68 @@ gh workflow run package-acceptance.yml \
-f telegram_mode=mock-openai
```
Dùng `suite_profile=product` khi câu hỏi phát hành bao gồm kênh MCP, dọn dẹp cron/subagent, tìm kiếm web OpenAI, hoặc OpenWebUI. Chỉ dùng `suite_profile=full` khi bạn cần độ bao phủ đầy đủ đường dẫn phát hành Docker.
Dùng `suite_profile=product` khi câu hỏi phát hành bao gồm các kênh MCP, dọn dẹp
cron/subagent, tìm kiếm web OpenAI, hoặc OpenWebUI. Chỉ dùng `suite_profile=full`
khi bạn cần bao phủ đầy đủ đường dẫn phát hành Docker.
## Mặc định phát hành
Đối với ứng viên phát hành, stack bằng chứng mặc định là:
Đối với ứng viên phát hành, ngăn xếp bằng chứng mặc định là:
1. `pnpm check:changed` và `pnpm test:changed` cho hồi quy cấp nguồn.
1. `pnpm check:changed` và `pnpm test:changed` cho các hồi quy ở cấp nguồn.
2. `pnpm release:check` cho tính toàn vẹn artifact gói.
3. Hồ sơ Package Acceptance `package` hoặc các lane gói tùy chỉnh release-check cho hợp đồng cài đặt/cập nhật/Plugin.
4. Kiểm tra phát hành đa hệ điều hành cho trình cài đặt, onboarding, và hành vi nền tảng theo hệ điều hành.
5. Bộ kiểm thử trực tiếp chỉ khi bề mặt thay đổi chạm vào hành vi nhà cung cấp hoặc dịch vụ được lưu trữ.
3. Hồ sơ `package` của Chấp nhận gói hoặc các lane gói tùy chỉnh của kiểm tra phát hành
cho hợp đồng cài đặt/cập nhật/Plugin.
4. Kiểm tra phát hành đa hệ điều hành cho hành vi installer, onboarding, và nền tảng
đặc thù theo OS.
5. Các bộ trực tiếp chỉ khi bề mặt đã thay đổi chạm tới hành vi nhà cung cấp hoặc
dịch vụ được host.
Trên máy maintainer, các cổng rộng và bằng chứng sản phẩm Docker/gói nên chạy trong Testbox trừ khi rõ ràng đang làm bằng chứng cục bộ.
Trên máy maintainer, các cổng rộng và bằng chứng sản phẩm Docker/gói nên chạy
trong Testbox trừ khi đang thực hiện bằng chứng cục bộ một cách rõ ràng.
## Tương thích kế thừa
Độ khoan dung tương thích hẹp và có giới hạn thời gian:
Mức khoan dung tương thích hẹp và có giới hạn thời gian:
- Các gói đến `2026.4.25`, bao gồm `2026.4.25-beta.*`, có thể chấp nhận các khoảng trống metadata gói đã ship trong Package Acceptance.
- Gói `2026.4.26` đã phát hành có thể cảnh báo về các tệp dấu metadata build cục bộ đã ship.
- Các gói sau đó phải đáp ứng các hợp đồng hiện đại. Cùng các khoảng trống đó sẽ thất bại thay vì cảnh báo hoặc bỏ qua.
- Các gói đến `2026.4.25`, bao gồm `2026.4.25-beta.*`, có thể dung thứ các khoảng trống
metadata gói đã được phát hành trong Chấp nhận gói.
- Gói `2026.4.26` đã phát hành có thể cảnh báo về các tệp stamp metadata build cục bộ
đã được phát hành.
- Các gói sau đó phải đáp ứng hợp đồng hiện đại. Cùng các khoảng trống đó sẽ thất bại
thay vì cảnh báo hoặc bỏ qua.
Không thêm migration khởi động mới cho các hình dạng cũ này. Thêm hoặc mở rộng một sửa chữa doctor, rồi chứng minh bằng `upgrade-survivor` hoặc `published-upgrade-survivor`.
Không thêm migration khởi động mới cho các dạng cũ này. Thêm hoặc mở rộng một sửa chữa
doctor, rồi chứng minh bằng `upgrade-survivor` hoặc `published-upgrade-survivor`.
## Thêm độ bao phủ
## Thêm phạm vi bao phủ
Khi thay đổi hành vi cập nhật hoặc Plugin, hãy thêm độ bao phủ ở lớp thấp nhất có thể thất bại vì đúng lý do:
Khi thay đổi hành vi cập nhật hoặc Plugin, hãy thêm phạm vi bao phủ ở tầng thấp nhất
có thể thất bại vì đúng lý do:
- Logic đường dẫn hoặc metadata thuần túy: kiểm thử đơn vị cạnh nguồn.
- Hành vi kiểm kê gói hoặc tệp được đóng gói: kiểm thử `package-dist-inventory` hoặc trình kiểm tra tarball.
- Hành vi cài đặt/cập nhật CLI: assertion hoặc fixture lane Docker.
- Hành vi migration bản phát hành đã công bố: kịch bản `published-upgrade-survivor`.
- Hành vi nguồn registry/gói: fixture `test:docker:plugins` hoặc máy chủ fixture ClawHub.
- Hành vi bố cục hoặc dọn dẹp phụ thuộc: xác nhận cả thực thi runtime và ranh giới hệ thống tệp. Phụ thuộc npm có thể được hoist dưới gốc npm được quản lý, vì vậy kiểm thử nên chứng minh gốc được quét/dọn thay vì giả định cây `node_modules` cục bộ của gói.
- Logic đường dẫn thuần hoặc metadata: kiểm thử đơn vị bên cạnh nguồn.
- Hành vi inventory gói hoặc tệp đã đóng gói: `package-dist-inventory` hoặc kiểm thử
trình kiểm tra tarball.
- Hành vi cài đặt/cập nhật CLI: assertion hoặc fixture trong lane Docker.
- Hành vi migration bản phát hành đã phát hành: kịch bản `published-upgrade-survivor`.
- Hành vi registry/nguồn gói: fixture `test:docker:plugins` hoặc server fixture ClawHub.
- Hành vi bố cục hoặc dọn dẹp phụ thuộc: xác nhận cả thực thi runtime và ranh giới
hệ thống tệp. Phụ thuộc npm có thể được hoist dưới npm root được quản lý, nên kiểm thử
cần chứng minh root được quét/dọn thay vì giả định một cây `node_modules` cục bộ của gói.
Giữ các fixture Docker mới khép kín theo mặc định. Dùng registry fixture cục bộ và gói giả trừ khi mục tiêu của kiểm thử là hành vi registry trực tiếp.
Giữ các fixture Docker mới hermetic theo mặc định. Dùng registry fixture cục bộ và
gói giả trừ khi mục tiêu của kiểm thử là hành vi registry trực tiếp.
## Phân loại lỗi
Bắt đầu với định danh artifact:
- Tóm tắt `resolve_package` của Package Acceptance: nguồn, phiên bản, SHA-256, và tên artifact.
- Artifact Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, log lane, và lệnh chạy lại.
- Tóm tắt upgrade survivor: `.artifacts/upgrade-survivor/summary.json`, bao gồm phiên bản baseline, phiên bản ứng viên, kịch bản, thời gian pha, và các bước công thức.
- Tóm tắt `resolve_package` của Chấp nhận gói: nguồn, phiên bản, SHA-256, và tên artifact.
- Artifact Docker: `.artifacts/docker-tests/**/summary.json`,
`failures.json`, log lane, và các lệnh chạy lại.
- Tóm tắt upgrade survivor: `.artifacts/upgrade-survivor/summary.json`,
bao gồm phiên bản baseline, phiên bản ứng viên, kịch bản, thời gian pha, và
các bước công thức.
Ưu tiên chạy lại đúng lane đã thất bại với cùng artifact gói hơn là chạy lại toàn bộ ô phát hành.
Ưu tiên chạy lại đúng lane đã lỗi với cùng artifact gói hơn là chạy lại toàn bộ
ô phát hành.

857
docs/vi/help/testing.md
View File

File diff suppressed because it is too large Load Diff

170
docs/vi/plugins/bundles.md
View File

@ -1,41 +1,41 @@
---
read_when:
- Bạn muốn cài đặt một gói tương thích với Codex, Claude hoặc Cursor
- Bạn cần hiểu cách OpenClaw ánh xạ nội dung gói thành các tính năng gốc
- Bạn đang gỡ lỗi việc phát hiện gói hoặc các khả năng bị thiếu
- Bạn cần hiểu cách OpenClaw ánh xạ nội dung gói thành các tính năng gốc.
- Bạn đang gỡ lỗi việc phát hiện gói hoặc các năng lực bị thiếu
summary: Cài đặt và sử dụng các gói Codex, Claude và Cursor dưới dạng Plugin OpenClaw
title: Gói Plugin
title: Các gói Plugin
x-i18n:
generated_at: "2026-05-02T10:47:08Z"
generated_at: "2026-05-05T01:48:14Z"
model: gpt-5.5
provider: openai
source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4
source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157
source_path: plugins/bundles.md
workflow: 16
---
OpenClaw có thể cài đặt Plugin từ ba hệ sinh thái bên ngoài: **Codex**, **Claude**,
và **Cursor**. Chúng được gọi là **gói** — các gói nội dung và siêu dữ liệu mà
OpenClaw ánh xạ thành các tính năng gốc như Skills, hook và công cụ MCP.
OpenClaw ánh xạ vào các tính năng gốc như Skills, móc nối và công cụ MCP.
<Info>
Gói **không** giống Plugin OpenClaw gốc. Plugin gốc chạy
trong tiến trình và có thể đăng ký bất kỳ năng lực nào. Gói là các gói nội dung với
ánh xạ tính năng có chọn lọc và ranh giới tin cậy hẹp hơn.
Gói **không** giống với Plugin OpenClaw gốc. Plugin gốc chạy
trong cùng tiến trình và có thể đăng ký bất kỳ năng lực nào. Gói là các gói nội dung có
ánh xạ tính năng chọn lọc và ranh giới tin cậy hẹp hơn.
</Info>
## Vì sao có gói
Nhiều Plugin hữu ích được phát hành theo định dạng Codex, Claude hoặc Cursor. Thay vì
Nhiều Plugin hữu ích được phát hành ở định dạng Codex, Claude hoặc Cursor. Thay vì
yêu cầu tác giả viết lại chúng thành Plugin OpenClaw gốc, OpenClaw
phát hiện các định dạng này và ánh xạ nội dung được hỗ trợ của chúng vào bộ tính năng
gốc. Điều này có nghĩa là bạn có thể cài đặt một gói lệnh Claude hoặc một gói Skills Codex
gốc. Điều này nghĩa là bạn có thể cài đặt một gói lệnh Claude hoặc một gói kỹ năng Codex
và dùng ngay.
## Cài đặt một gói
<Steps>
<Step title="Cài đặt từ thư mục, tệp lưu trữ hoặc chợ ứng dụng">
<Step title="Cài đặt từ một thư mục, kho lưu trữ hoặc chợ Plugin">
```bash
# Local directory
openclaw plugins install ./my-bundle
@ -56,7 +56,7 @@ và dùng ngay.
openclaw plugins inspect <id>
```
Các gói hiển thị là `Format: bundle` với kiểu con là `codex`, `claude` hoặc `cursor`.
Gói hiển thị là `Format: bundle` với kiểu con là `codex`, `claude` hoặc `cursor`.
</Step>
@ -65,40 +65,40 @@ và dùng ngay.
openclaw gateway restart
```
Các tính năng được ánh xạ (Skills, hook, công cụ MCP, mặc định LSP) có sẵn trong phiên tiếp theo.
Các tính năng đã ánh xạ (Skills, móc nối, công cụ MCP, mặc định LSP) sẽ có sẵn trong phiên tiếp theo.
</Step>
</Steps>
## OpenClaw ánh xạ gì từ các gói
Không phải mọi tính năng của gói đều chạy trong OpenClaw hiện nay. Dưới đây là những gì hoạt động và những gì
Không phải mọi tính năng của gói đều chạy trong OpenClaw hiện nay. Đây là những gì hoạt động và những gì
được phát hiện nhưng chưa được nối dây.
### Hiện đã hỗ trợ
| Tính năng | Cách ánh xạ | Áp dụng cho |
| Tính năng | Cách ánh xạ | Áp dụng cho |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Nội dung Skills | Gốc Skills của gói tải như Skills OpenClaw bình thường | Mọi định dạng |
| Lệnh | `commands/` và `.cursor/commands/` được xem là gốc Skills | Claude, Cursor |
| Gói hook | Bố cục kiểu OpenClaw `HOOK.md` + `handler.ts` | Codex |
| Công cụ MCP | Cấu hình MCP của gói được hợp nhất vào cài đặt Pi nhúng; máy chủ stdio và HTTP được hỗ trợ sẽ được tải | Mọi định dạng |
| Máy chủ LSP | `.lsp.json` của Claude và `lspServers` khai báo trong manifest được hợp nhất vào mặc định LSP của Pi nhúng | Claude |
| Cài đặt | `settings.json` của Claude được nhập làm mặc định Pi nhúng | Claude |
| Nội dung Skills | Các gốc Skills của gói tải như Skills OpenClaw bình thường | Mọi định dạng |
| Lệnh | `commands/` và `.cursor/commands/` được xem là các gốc Skills | Claude, Cursor |
| Gói móc nối | Bố cục kiểu OpenClaw `HOOK.md` + `handler.ts` | Codex |
| Công cụ MCP | Cấu hình MCP của gói được hợp nhất vào cài đặt Pi nhúng; máy chủ stdio và HTTP được hỗ trợ sẽ được tải | Mọi định dạng |
| Máy chủ LSP | `.lsp.json` của Claude và `lspServers` khai báo trong manifest được hợp nhất vào mặc định LSP của Pi nhúng | Claude |
| Cài đặt | `settings.json` của Claude được nhập làm mặc định Pi nhúng | Claude |
#### Nội dung Skills
- gốc Skills của gói tải như gốc Skills OpenClaw bình thường
- gốc `commands` của Claude được xem là gốc Skills bổ sung
- gốc `.cursor/commands` của Cursor được xem là gốc Skills bổ sung
- các gốc Skills của gói tải như các gốc Skills OpenClaw bình thường
- các gốc `commands` của Claude được xem là các gốc Skills bổ sung
- các gốc `.cursor/commands` của Cursor được xem là các gốc Skills bổ sung
Điều này có nghĩa là các tệp lệnh markdown của Claude hoạt động thông qua trình tải Skills
OpenClaw bình thường. Markdown lệnh của Cursor hoạt động qua cùng đường dẫn.
Điều này nghĩa là các tệp lệnh markdown của Claude hoạt động thông qua trình tải Skills
bình thường của OpenClaw. Markdown lệnh của Cursor hoạt động qua cùng đường dẫn.
#### Gói hook
#### Gói móc nối
- gốc hook của gói hoạt động **chỉ** khi chúng dùng bố cục gói hook OpenClaw
bình thường. Hiện nay đây chủ yếu là trường hợp tương thích với Codex:
- các gốc móc nối của gói hoạt động **chỉ** khi chúng dùng bố cục gói móc nối
OpenClaw bình thường. Hiện nay đây chủ yếu là trường hợp tương thích với Codex:
- `HOOK.md`
- `handler.ts` hoặc `handler.js`
@ -109,16 +109,16 @@ OpenClaw bình thường. Markdown lệnh của Cursor hoạt động qua cùng
`mcpServers`
- OpenClaw hiển thị các công cụ MCP được hỗ trợ của gói trong lượt tác nhân Pi nhúng bằng cách
khởi chạy máy chủ stdio hoặc kết nối tới máy chủ HTTP
- hồ sơ công cụ `coding` và `messaging` mặc định bao gồm công cụ MCP của gói;
dùng `tools.deny: ["bundle-mcp"]` để loại trừ cho một tác nhân hoặc Gateway
- cài đặt Pi cục bộ theo dự án vẫn áp dụng sau mặc định của gói, vì vậy cài đặt
workspace có thể ghi đè mục MCP của gói khi cần
- danh mục công cụ MCP của gói được sắp xếp xác định trước khi đăng ký, vì vậy
thay đổi thứ tự `listTools()` từ thượng nguồn không làm dao động các khối công cụ trong bộ nhớ đệm prompt
- hồ sơ công cụ `coding` và `messaging` bao gồm công cụ MCP của gói theo
mặc định; dùng `tools.deny: ["bundle-mcp"]` để từ chối cho một tác nhân hoặc gateway
- cài đặt Pi cục bộ theo dự án vẫn áp dụng sau mặc định của gói, nên cài đặt
không gian làm việc có thể ghi đè các mục MCP của gói khi cần
- danh mục công cụ MCP của gói được sắp xếp xác định trước khi đăng ký, nên
thay đổi thứ tự `listTools()` từ thượng nguồn không làm xáo trộn các khối công cụ trong bộ nhớ đệm lời nhắc
##### Giao thức truyền
##### Phương thức truyền
Máy chủ MCP có thể dùng giao thức truyền stdio hoặc HTTP:
Máy chủ MCP có thể dùng phương thức truyền stdio hoặc HTTP:
**Stdio** khởi chạy một tiến trình con:
@ -136,7 +136,7 @@ Máy chủ MCP có thể dùng giao thức truyền stdio hoặc HTTP:
}
```
**HTTP** mặc định kết nối tới máy chủ MCP đang chạy qua `sse`, hoặc `streamable-http` khi được yêu cầu:
**HTTP** kết nối tới một máy chủ MCP đang chạy qua `sse` theo mặc định, hoặc `streamable-http` khi được yêu cầu:
```json
{
@ -160,33 +160,33 @@ Máy chủ MCP có thể dùng giao thức truyền stdio hoặc HTTP:
- chỉ cho phép lược đồ URL `http:` và `https:`
- giá trị `headers` hỗ trợ nội suy `${ENV_VAR}`
- mục máy chủ có cả `command` và `url` sẽ bị từ chối
- thông tin xác thực URL (userinfo và tham số truy vấn) được biên tập khỏi phần
- thông tin xác thực trong URL (userinfo và tham số truy vấn) được biên tập khỏi phần
mô tả công cụ và nhật ký
- `connectionTimeoutMs` ghi đè thời gian chờ kết nối mặc định 30 giây cho
cả giao thức truyền stdio và HTTP
cả phương thức truyền stdio và HTTP
##### Đặt tên công cụ
OpenClaw đăng ký công cụ MCP của gói với tên an toàn cho nhà cung cấp theo dạng
`serverName__toolName`. Ví dụ, một máy chủ có khóa `"vigil-harbor"` hiển thị công cụ
`memory_search` sẽ được đăng ký là `vigil-harbor__memory_search`.
OpenClaw đăng ký công cụ MCP của gói bằng tên an toàn cho nhà cung cấp ở dạng
`serverName__toolName`. Ví dụ, một máy chủ có khóa `"vigil-harbor"` hiển thị một
công cụ `memory_search` sẽ được đăng ký là `vigil-harbor__memory_search`.
- các ký tự ngoài `A-Za-z0-9_-` được thay bằng `-`
- tiền tố máy chủ bị giới hạn ở 30 ký tự
- tên công cụ đầy đủ bị giới hạn ở 64 ký tự
- tên máy chủ trống sẽ dùng dự phòng `mcp`
- tên máy chủ rỗng dùng dự phòng `mcp`
- tên đã làm sạch bị trùng được phân biệt bằng hậu tố số
- thứ tự công cụ cuối cùng được hiển thị là xác định theo tên an toàn để giữ các lượt Pi
lặp lại ổn định với bộ nhớ đệm
- thứ tự công cụ hiển thị cuối cùng mang tính xác định theo tên an toàn để giữ các lượt Pi lặp lại
ổn định với bộ nhớ đệm
- lọc hồ sơ xem mọi công cụ từ một máy chủ MCP của gói là thuộc sở hữu Plugin
bởi `bundle-mcp`, vì vậy allowlist và danh sách từ chối của hồ sơ có thể bao gồm
tên công cụ được hiển thị riêng lẻ hoặc khóa Plugin `bundle-mcp`
bởi `bundle-mcp`, nên danh sách cho phép và danh sách từ chối của hồ sơ có thể bao gồm
tên công cụ hiển thị riêng lẻ hoặc khóa Plugin `bundle-mcp`
#### Cài đặt Pi nhúng
- `settings.json` của Claude được nhập làm cài đặt Pi nhúng mặc định khi
gói được bật
- OpenClaw làm sạch khóa ghi đè shell trước khi áp dụng chúng
- OpenClaw làm sạch các khóa ghi đè shell trước khi áp dụng chúng
Khóa đã làm sạch:
@ -197,17 +197,17 @@ Khóa đã làm sạch:
- các gói Claude đã bật có thể đóng góp cấu hình máy chủ LSP
- OpenClaw tải `.lsp.json` cùng mọi đường dẫn `lspServers` khai báo trong manifest
- cấu hình LSP của gói được hợp nhất vào mặc định LSP của Pi nhúng hiệu lực
- hiện nay chỉ các máy chủ LSP dựa trên stdio được hỗ trợ mới có thể chạy; giao thức truyền
- cấu hình LSP của gói được hợp nhất vào mặc định LSP Pi nhúng hiệu lực
- hiện nay chỉ máy chủ LSP dựa trên stdio được hỗ trợ mới có thể chạy; các phương thức truyền
không được hỗ trợ vẫn hiển thị trong `openclaw plugins inspect <id>`
### Được phát hiện nhưng không thực thi
### Đã phát hiện nhưng không thực thi
Những mục này được nhận diện và hiển thị trong chẩn đoán, nhưng OpenClaw không chạy chúng:
- `agents`, tự động hóa `hooks.json`, `outputStyles` của Claude
- `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` của Cursor
- siêu dữ liệu inline/app của Codex ngoài báo cáo năng lực
- siêu dữ liệu nội tuyến/ứng dụng Codex ngoài báo cáo năng lực
## Định dạng gói
@ -217,8 +217,8 @@ Những mục này được nhận diện và hiển thị trong chẩn đoán,
Nội dung tùy chọn: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
Gói Codex phù hợp với OpenClaw nhất khi chúng dùng gốc Skills và thư mục
gói hook kiểu OpenClaw (`HOOK.md` + `handler.ts`).
Gói Codex phù hợp với OpenClaw nhất khi chúng dùng các gốc Skills và thư mục
gói móc nối kiểu OpenClaw (`HOOK.md` + `handler.ts`).
</Accordion>
@ -228,12 +228,12 @@ Những mục này được nhận diện và hiển thị trong chẩn đoán,
- **Dựa trên manifest:** `.claude-plugin/plugin.json`
- **Không có manifest:** bố cục Claude mặc định (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)
Hành vi dành riêng cho Claude:
Hành vi riêng của Claude:
- `commands/` được xem là nội dung Skills
- `settings.json` được nhập vào cài đặt Pi nhúng (khóa ghi đè shell được làm sạch)
- `settings.json` được nhập vào cài đặt Pi nhúng (các khóa ghi đè shell được làm sạch)
- `.mcp.json` hiển thị các công cụ stdio được hỗ trợ cho Pi nhúng
- `.lsp.json` cùng các đường dẫn `lspServers` khai báo trong manifest tải vào mặc định LSP của Pi nhúng
- `.lsp.json` cùng các đường dẫn `lspServers` khai báo trong manifest được tải vào mặc định LSP Pi nhúng
- `hooks/hooks.json` được phát hiện nhưng không thực thi
- Đường dẫn thành phần tùy chỉnh trong manifest là bổ sung (chúng mở rộng mặc định, không thay thế)
@ -245,7 +245,7 @@ Những mục này được nhận diện và hiển thị trong chẩn đoán,
Nội dung tùy chọn: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
- `.cursor/commands/` được xem là nội dung Skills
- `.cursor/rules/`, `.cursor/agents/`, và `.cursor/hooks.json` chỉ được phát hiện
- `.cursor/rules/`, `.cursor/agents/` và `.cursor/hooks.json` chỉ được phát hiện
</Accordion>
</AccordionGroup>
@ -254,62 +254,62 @@ Những mục này được nhận diện và hiển thị trong chẩn đoán,
OpenClaw kiểm tra định dạng Plugin gốc trước:
1. `openclaw.plugin.json` hoặc `package.json` hợp lệ với `openclaw.extensions` — được xem là **Plugin gốc**
1. `openclaw.plugin.json` hoặc `package.json` hợp lệ có `openclaw.extensions` — được xem là **Plugin gốc**
2. Dấu hiệu gói (`.codex-plugin/`, `.claude-plugin/`, hoặc bố cục Claude/Cursor mặc định) — được xem là **gói**
Nếu một thư mục chứa cả hai, OpenClaw dùng đường dẫn gốc. Điều này ngăn các gói
hai định dạng bị cài đặt một phần dưới dạng gói.
Nếu một thư mục chứa cả hai, OpenClaw dùng đường dẫn gốc. Điều này ngăn
các gói hai định dạng bị cài đặt một phần dưới dạng gói.
## Phụ thuộc runtime và dọn dẹp
- Gói tương thích của bên thứ ba không nhận sửa chữa `npm install` khi khởi động. Chúng
nên được cài đặt qua `openclaw plugins install` và đóng gói mọi thứ
- Các gói tương thích bên thứ ba không nhận sửa chữa `npm install` khi khởi động. Chúng
nên được cài đặt thông qua `openclaw plugins install` và cung cấp mọi thứ
chúng cần trong thư mục Plugin đã cài đặt.
- Plugin đóng gói do OpenClaw sở hữu hoặc được phát hành nhẹ trong lõi hoặc
có thể tải xuống qua trình cài đặt Plugin. Gateway khi khởi động không bao giờ chạy
trình quản lý gói cho chúng.
- `openclaw doctor --fix` xóa các thư mục phụ thuộc staged cũ và có thể
cài đặt các Plugin có thể tải xuống đã cấu hình nhưng thiếu trong chỉ mục
Plugin cục bộ.
- Các Plugin đóng gói thuộc sở hữu OpenClaw hoặc được đưa kèm nhẹ trong lõi hoặc
có thể tải xuống thông qua trình cài đặt Plugin. Gateway không bao giờ chạy
trình quản lý gói cho chúng khi khởi động.
- `openclaw doctor --fix` xóa các thư mục phụ thuộc được staged kiểu cũ và có thể
khôi phục các Plugin có thể tải xuống bị thiếu khỏi chỉ mục Plugin cục bộ khi
cấu hình tham chiếu chúng.
## Bảo mật
Gói có ranh giới tin cậy hẹp hơn Plugin gốc:
- OpenClaw **không** tải mô-đun runtime tùy ý của gói trong tiến trình
- Đường dẫn Skills và gói hook phải nằm trong gốc Plugin (được kiểm tra ranh giới)
- OpenClaw **không** tải các mô-đun runtime tùy ý của gói trong cùng tiến trình
- Đường dẫn Skills và gói móc nối phải nằm trong gốc Plugin (được kiểm tra ranh giới)
- Tệp cài đặt được đọc với cùng các kiểm tra ranh giới
- Máy chủ MCP stdio được hỗ trợ có thể được khởi chạy dưới dạng tiến trình con
- Máy chủ MCP stdio được hỗ trợ có thể được khởi chạy như tiến trình con
Điều này khiến gói an toàn hơn theo mặc định, nhưng bạn vẫn nên xem gói bên thứ ba
là nội dung đáng tin cậy đối với các tính năng mà chúng hiển thị.
Điều này làm cho gói an toàn hơn theo mặc định, nhưng bạn vẫn nên xem các gói
bên thứ ba là nội dung tin cậy đối với những tính năng mà chúng hiển thị.
## Khắc phục sự cố
<AccordionGroup>
<Accordion title="Gói được phát hiện nhưng năng lực không chạy">
Chạy `openclaw plugins inspect <id>`. Nếu một năng lực được liệt kê nhưng được đánh dấu là
chưa nối dây, đó là giới hạn sản phẩm — không phải cài đặt bị hỏng.
chưa nối dây, đó là giới hạn của sản phẩm — không phải cài đặt bị hỏng.
</Accordion>
<Accordion title="Tệp lệnh Claude không xuất hiện">
Hãy đảm bảo gói đã được bật và các tệp markdown nằm trong gốc
Đảm bảo gói đã được bật và các tệp markdown nằm trong một gốc
`commands/` hoặc `skills/` được phát hiện.
</Accordion>
<Accordion title="Cài đặt Claude không áp dụng">
Chỉ hỗ trợ cài đặt Pi nhúng từ `settings.json`. OpenClaw không
xem cài đặt gói là bản vá cấu hình thô.
Chỉ cài đặt Pi nhúng từ `settings.json` được hỗ trợ. OpenClaw không
xem cài đặt của gói là bản vá cấu hình thô.
</Accordion>
<Accordion title="Hook Claude không thực thi">
`hooks/hooks.json` chỉ được phát hiện. Nếu bạn cần hook có thể chạy, hãy dùng
bố cục gói hook OpenClaw hoặc phát hành Plugin gốc.
<Accordion title="Móc nối Claude không thực thi">
`hooks/hooks.json` chỉ được phát hiện. Nếu bạn cần móc nối có thể chạy, hãy dùng
bố cục gói móc nối OpenClaw hoặc phát hành một Plugin gốc.
</Accordion>
</AccordionGroup>
## Liên quan
- [Cài đặt và cấu hình Plugin](/vi/tools/plugin)
- [Xây dựng Plugin](/vi/plugins/building-plugins) — tạo Plugin gốc
- [Manifest Plugin](/vi/plugins/manifest) — schema manifest gốc
- [Xây dựng Plugin](/vi/plugins/building-plugins) — tạo một Plugin gốc
- [Manifest Plugin](/vi/plugins/manifest) — lược đồ manifest gốc

897
docs/vi/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

124
docs/vi/plugins/dependency-resolution.md
View File

@ -1,50 +1,51 @@
---
read_when:
- Bạn đang gỡ lỗi quá trình cài đặt gói Plugin
- Bạn đang thay đổi hành vi khởi động Plugin, doctor hoặc cài đặt qua trình quản lý gói
- Bạn đang bảo trì các bản cài đặt OpenClaw dạng gói hoặc các tệp kê khai Plugin đi kèm
- Bạn đang gỡ lỗi việc cài đặt gói Plugin
- Bạn đang thay đổi hành vi khởi động Plugin, doctor hoặc cài đặt bằng trình quản lý gói
- Bạn đang bảo trì các bản cài đặt OpenClaw đóng gói hoặc các tệp kê khai Plugin đi kèm
sidebarTitle: Dependencies
summary: Cách OpenClaw cài đặt các gói Plugin và phân giải các phần phụ thuộc của Plugin
title: Phân giải phụ thuộc của Plugin
title: Phân giải phụ thuộc Plugin
x-i18n:
generated_at: "2026-05-03T21:34:42Z"
generated_at: "2026-05-05T01:49:08Z"
model: gpt-5.5
provider: openai
source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d
source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20
source_path: plugins/dependency-resolution.md
workflow: 16
---
# Giải quyết phụ thuộc của Plugin
# Phân giải phần phụ thuộc của Plugin
OpenClaw giữ việc xử lý phụ thuộc của Plugin ở thời điểm cài đặt/cập nhật. Quá trình tải lúc chạy
không chạy trình quản lý gói, sửa cây phụ thuộc, hoặc thay đổi thư mục gói
OpenClaw giữ công việc xử lý phần phụ thuộc của plugin ở thời điểm cài đặt/cập nhật. Việc tải lúc runtime
không chạy trình quản lý gói, sửa cây phần phụ thuộc, hoặc thay đổi thư mục gói
OpenClaw.
## Phân chia trách nhiệm
Các gói Plugin sở hữu đồ thị phụ thuộc của chúng:
Các gói plugin sở hữu đồ thị phần phụ thuộc của chúng:
- phụ thuộc lúc chạy nằm trong `dependencies` hoặc `optionalDependencies` của gói Plugin
- các import SDK/lõi là peer hoặc các import do OpenClaw cung cấp
- Plugin phát triển cục bộ tự mang theo các phụ thuộc đã được cài đặt sẵn
- Plugin npm và git được cài đặt vào các gốc gói do OpenClaw sở hữu
- phần phụ thuộc runtime nằm trong `dependencies` hoặc
`optionalDependencies` của gói plugin
- các import SDK/core là peer hoặc import do OpenClaw cung cấp
- plugin phát triển cục bộ mang theo các phần phụ thuộc đã được cài đặt sẵn của riêng chúng
- plugin npm và git được cài đặt vào các gốc gói do OpenClaw sở hữu
OpenClaw chỉ sở hữu vòng đời Plugin:
OpenClaw chỉ sở hữu vòng đời plugin:
- phát hiện nguồn Plugin
- phát hiện nguồn plugin
- cài đặt hoặc cập nhật gói khi được yêu cầu rõ ràng
- ghi lại siêu dữ liệu cài đặt
- tải điểm vào của Plugin
- thất bại với lỗi có thể hành động khi thiếu phụ thuộc
- tải entrypoint của plugin
- thất bại kèm lỗi có thể hành động khi thiếu phần phụ thuộc
## Gốc cài đặt
OpenClaw dùng các gốc ổn định theo từng nguồn:
- gói npm cài dưới `~/.openclaw/npm`
- gói npm cài đặt dưới `~/.openclaw/npm`
- gói git clone dưới `~/.openclaw/git`
- cài đặt cục bộ/đường dẫn/kho lưu trữ được sao chép hoặc tham chiếu mà không sửa phụ thuộc
- cài đặt cục bộ/đường dẫn/kho lưu trữ được sao chép hoặc tham chiếu mà không sửa phần phụ thuộc
Cài đặt npm chạy trong gốc npm với:
@ -52,10 +53,10 @@ Cài đặt npm chạy trong gốc npm với:
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
```
npm có thể hoist các phụ thuộc bắc cầu lên `~/.openclaw/npm/node_modules` bên cạnh
gói Plugin. OpenClaw quét gốc npm được quản lý trước khi tin cậy bản
cài đặt và dùng npm để gỡ các gói do npm quản lý trong lúc gỡ cài đặt, vì vậy các
phụ thuộc lúc chạy đã hoist vẫn nằm trong ranh giới dọn dẹp được quản lý.
npm có thể hoist các phần phụ thuộc bắc cầu sang `~/.openclaw/npm/node_modules` bên cạnh
gói plugin. OpenClaw quét gốc npm được quản lý trước khi tin cậy bản
cài đặt và dùng npm để gỡ các gói do npm quản lý trong khi gỡ cài đặt, nên các
phần phụ thuộc runtime đã hoist vẫn nằm trong ranh giới dọn dẹp được quản lý.
Cài đặt git clone hoặc làm mới kho lưu trữ, rồi chạy:
@ -64,24 +65,26 @@ npm install --omit=dev --ignore-scripts --no-audit --no-fund
```
Plugin đã cài đặt sau đó tải từ thư mục gói đó, nên việc phân giải `node_modules`
cục bộ theo gói và từ cha hoạt động giống như với một gói Node bình thường.
cục bộ theo gói và cấp cha hoạt động giống như với một gói
Node thông thường.
## Plugin cục bộ
Plugin cục bộ được xem là các thư mục do nhà phát triển kiểm soát. OpenClaw không
chạy `npm install`, `pnpm install`, hoặc sửa phụ thuộc cho chúng. Nếu một Plugin
cục bộ có phụ thuộc, hãy cài đặt chúng trong Plugin đó trước khi tải.
chạy `npm install`, `pnpm install`, hoặc sửa phần phụ thuộc cho chúng. Nếu một
plugin cục bộ có phần phụ thuộc, hãy cài đặt chúng trong plugin đó trước khi tải.
Plugin TypeScript cục bộ của bên thứ ba có thể dùng đường dẫn Jiti khẩn cấp. Plugin
JavaScript đã đóng gói và Plugin nội bộ đi kèm tải qua import/require gốc thay vì Jiti.
Plugin cục bộ TypeScript của bên thứ ba có thể dùng đường dẫn Jiti khẩn cấp. Plugin
JavaScript đã đóng gói và plugin nội bộ đi kèm tải qua
import/require native thay vì Jiti.
## Khởi động và tải lại
Khởi động Gateway và tải lại cấu hình không bao giờ cài đặt phụ thuộc Plugin. Chúng đọc
các bản ghi cài đặt Plugin, tính toán điểm vào, và tải nó.
Khởi động Gateway và tải lại cấu hình không bao giờ cài đặt phần phụ thuộc của plugin. Chúng đọc
bản ghi cài đặt plugin, tính entrypoint, và tải plugin.
Nếu thiếu phụ thuộc ở thời gian chạy, Plugin sẽ không tải được và lỗi
nên chỉ cho người vận hành một cách sửa rõ ràng:
Nếu thiếu phần phụ thuộc ở runtime, plugin sẽ không tải được và lỗi
nên chỉ người vận hành đến một cách sửa rõ ràng:
```bash
openclaw plugins update <id>
@ -89,44 +92,45 @@ openclaw plugins install <source>
openclaw doctor --fix
```
`doctor --fix` có thể dọn dẹp trạng thái phụ thuộc cũ do OpenClaw tạo ra và cài đặt
các Plugin có thể tải xuống đã được cấu hình nhưng còn thiếu khỏi bản ghi cài đặt cục bộ.
Nó không sửa phụ thuộc cho một Plugin cục bộ đã được cài đặt.
`doctor --fix` có thể dọn trạng thái phần phụ thuộc cũ do OpenClaw tạo và khôi phục
các plugin có thể tải xuống bị thiếu khỏi bản ghi cài đặt cục bộ khi cấu hình
tham chiếu đến chúng. Doctor không sửa phần phụ thuộc cho một plugin cục bộ
đã cài đặt.
## Plugin đi kèm
Plugin nhẹ và quan trọng với lõi được phát hành như một phần của OpenClaw.
Chúng nên hoặc không có cây phụ thuộc lúc chạy nặng, hoặc được chuyển ra thành
Chúng nên không có cây phần phụ thuộc runtime nặng hoặc được chuyển ra thành một
gói có thể tải xuống trên ClawHub/npm.
Để xem danh sách hiện được tạo của các Plugin được phát hành trong gói lõi, được cài đặt
bên ngoài, hoặc chỉ tồn tại ở dạng nguồn, hãy xem [Kho Plugin](/vi/plugins/plugin-inventory).
Để xem danh sách hiện được tạo của các plugin được phát hành trong gói lõi, cài đặt
bên ngoài, hoặc chỉ tồn tại dưới dạng nguồn, xem [Danh mục plugin](/vi/plugins/plugin-inventory).
Manifest của Plugin đi kèm không được yêu cầu staging phụ thuộc. Chức năng Plugin lớn hoặc tùy chọn
nên được đóng gói như một Plugin bình thường và được cài đặt qua cùng đường dẫn
npm/git/ClawHub như Plugin bên thứ ba.
Manifest của plugin đi kèm không được yêu cầu staging phần phụ thuộc. Chức năng plugin
lớn hoặc tùy chọn nên được đóng gói như một plugin thông thường và cài đặt qua
cùng đường dẫn npm/git/ClawHub như plugin của bên thứ ba.
Trong checkout nguồn, OpenClaw xem kho lưu trữ là một monorepo pnpm. Sau
`pnpm install`, Plugin đi kèm tải từ `extensions/<id>` để các phụ thuộc workspace
cục bộ theo gói sẵn dùng và các chỉnh sửa được nhận trực tiếp. Phát triển bằng
checkout nguồn chỉ hỗ trợ pnpm; `npm install` thuần ở gốc kho lưu trữ
không phải là cách được hỗ trợ để chuẩn bị phụ thuộc Plugin đi kèm.
`pnpm install`, plugin đi kèm tải từ `extensions/<id>` để các phần phụ thuộc
workspace cục bộ theo gói có sẵn và các chỉnh sửa được nhận trực tiếp. Phát triển trên
checkout nguồn chỉ hỗ trợ pnpm; `npm install` thuần ở gốc kho lưu trữ không phải
là cách được hỗ trợ để chuẩn bị phần phụ thuộc của plugin đi kèm.
| Hình thức cài đặt | Vị trí Plugin đi kèm | Chủ sở hữu phụ thuộc |
| Hình dạng cài đặt | Vị trí plugin đi kèm | Chủ sở hữu phần phụ thuộc |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | Cây runtime đã build bên trong gói | Gói OpenClaw và các luồng cài đặt/cập nhật/doctor Plugin rõ ràng |
| Checkout Git cùng `pnpm install` | Các gói workspace `extensions/<id>` | Workspace pnpm, bao gồm phụ thuộc riêng của từng gói Plugin |
| `openclaw plugins install ...` | Gốc Plugin npm/git/ClawHub được quản lý | Luồng cài đặt/cập nhật Plugin |
| `npm install -g openclaw` | Cây runtime đã build bên trong gói | Gói OpenClaw và các luồng cài đặt/cập nhật/doctor plugin rõ ràng |
| Git checkout cộng `pnpm install` | Các gói workspace `extensions/<id>` | Workspace pnpm, bao gồm phần phụ thuộc riêng của từng gói plugin |
| `openclaw plugins install ...` | Gốc plugin npm/git/ClawHub được quản lý | Luồng cài đặt/cập nhật plugin |
## Dọn dẹp cũ
## Dọn dẹp di sản
Các phiên bản OpenClaw cũ hơn tạo gốc phụ thuộc Plugin đi kèm lúc khởi động hoặc
trong quá trình doctor repair. Dọn dẹp doctor hiện tại xóa các thư mục và
symlink cũ đó khi dùng `--fix`, bao gồm các gốc `plugin-runtime-deps` cũ, các
symlink gói tiền tố Node toàn cục trỏ tới mục tiêu `plugin-runtime-deps` đã bị lược bỏ,
manifest `.openclaw-runtime-deps*`, `node_modules` Plugin được tạo,
thư mục giai đoạn cài đặt, và store pnpm cục bộ theo gói. Postinstall đã đóng gói cũng
xóa các symlink toàn cục đó trước khi lược bỏ các gốc mục tiêu cũ để các bản nâng cấp
không để lại import gói ESM treo.
Các phiên bản OpenClaw cũ hơn đã tạo các gốc phần phụ thuộc của plugin đi kèm khi khởi động hoặc
trong lúc doctor sửa chữa. Việc dọn dẹp doctor hiện tại xóa các thư mục và
symlink cũ đó khi dùng `--fix`, bao gồm các gốc `plugin-runtime-deps` cũ, symlink
gói tiền tố Node toàn cục trỏ đến các đích `plugin-runtime-deps` đã bị lược bỏ,
manifest `.openclaw-runtime-deps*`, `node_modules` plugin được tạo, thư mục
stage cài đặt, và store pnpm cục bộ theo gói. Postinstall của gói cũng
xóa các symlink toàn cục đó trước khi lược bỏ các gốc đích di sản để các bản nâng cấp
không để lại import gói ESM bị treo.
Những đường dẫn này chỉ là mảnh còn sót lại cũ. Các bản cài đặt mới không nên tạo chúng.
Các đường dẫn này chỉ là rác di sản. Cài đặt mới không nên tạo chúng.

306
docs/vi/plugins/hooks.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Bạn đang xây dựng một Plugin cần before_tool_call, before_agent_reply, các hook tin nhắn hoặc các hook vòng đời
- Bạn cần chặn, viết lại hoặc yêu cầu phê duyệt đối với các lệnh gọi công cụ từ một Plugin
- Bạn đang lựa chọn giữa hook nội bộ và hook Plugin
summary: 'Các hook Plugin: chặn bắt các sự kiện vòng đời của tác tử, công cụ, tin nhắn, phiên và Gateway'
title: Các móc nối của Plugin
- Bạn đang xây dựng một plugin cần before_tool_call, before_agent_reply, hook tin nhắn hoặc hook vòng đời
- Bạn cần chặn, viết lại hoặc yêu cầu phê duyệt các lệnh gọi công cụ từ một Plugin
- Bạn đang quyết định giữa hook nội bộ và hook Plugin
summary: 'Móc nối của Plugin: chặn bắt các sự kiện vòng đời của tác tử, công cụ, tin nhắn, phiên và Gateway'
title: Các móc nối Plugin
x-i18n:
generated_at: "2026-05-03T21:34:46Z"
generated_at: "2026-05-05T01:49:18Z"
model: gpt-5.5
provider: openai
source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591
source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b
source_path: plugins/hooks.md
workflow: 16
---
Các điểm móc Plugin là các điểm mở rộng trong tiến trình cho Plugin OpenClaw. Dùng chúng
khi một Plugin cần kiểm tra hoặc thay đổi các lần chạy agent, lệnh gọi công cụ, luồng tin nhắn,
vòng đời phiên, định tuyến subagent, cài đặt, hoặc khởi động Gateway.
Các hook của Plugin là các điểm mở rộng trong tiến trình cho Plugin OpenClaw. Sử dụng chúng
khi một Plugin cần kiểm tra hoặc thay đổi lượt chạy agent, lệnh gọi công cụ, luồng tin nhắn,
vòng đời phiên, định tuyến subagent, cài đặt, hoặc quá trình khởi động Gateway.
Thay vào đó, dùng [điểm móc nội bộ](/vi/automation/hooks) khi bạn muốn một tập lệnh
`HOOK.md` nhỏ do toán tử cài đặt cho các sự kiện lệnh và Gateway như
Thay vào đó, hãy dùng [hook nội bộ](/vi/automation/hooks) khi bạn muốn một script
`HOOK.md` nhỏ do operator cài đặt cho các sự kiện lệnh và Gateway như
`/new`, `/reset`, `/stop`, `agent:bootstrap`, hoặc `gateway:startup`.
## Bắt đầu nhanh
Đăng ký các điểm móc Plugin có kiểu với `api.on(...)` từ entry Plugin của bạn:
Đăng ký các hook Plugin có kiểu với `api.on(...)` từ entry Plugin của bạn:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -56,19 +56,19 @@ export default definePluginEntry({
});
```
Trình xử lý điểm móc chạy tuần tự theo `priority` giảm dần. Các điểm móc cùng mức ưu tiên
Các handler hook chạy tuần tự theo `priority` giảm dần. Các hook cùng priority
giữ nguyên thứ tự đăng ký.
`api.on(name, handler, opts?)` chấp nhận:
- `priority` — thứ tự trình xử lý (cao hơn chạy trước).
- `timeoutMs` — ngân sách tùy chọn cho từng điểm móc. Khi được đặt, trình chạy điểm móc sẽ hủy bỏ
trình xử lý đó sau khi ngân sách hết hạn và tiếp tục với trình xử lý kế tiếp, thay vì
để quá trình thiết lập chậm hoặc công việc truy hồi tiêu tốn thời gian chờ mô hình đã cấu hình
của bên gọi. Bỏ qua để dùng thời gian chờ quan sát/quyết định mặc định mà
trình chạy điểm móc áp dụng chung.
- `priority` — thứ tự handler (giá trị cao hơn chạy trước).
- `timeoutMs` — ngân sách tùy chọn cho từng hook. Khi được đặt, trình chạy hook sẽ hủy
handler đó sau khi ngân sách trôi qua và tiếp tục với handler tiếp theo, thay vì
để phần thiết lập chậm hoặc công việc recall tiêu tốn timeout mô hình đã cấu hình
của bên gọi. Bỏ qua để dùng timeout quan sát/quyết định mặc định mà
trình chạy hook áp dụng chung.
Toán tử cũng có thể đặt ngân sách điểm móc mà không cần vá mã Plugin:
Operator cũng có thể đặt ngân sách hook mà không cần vá mã Plugin:
```json
{
@ -88,71 +88,71 @@ Toán tử cũng có thể đặt ngân sách điểm móc mà không cần vá
}
```
`hooks.timeouts.<hookName>` ghi đè `hooks.timeoutMs`, và giá trị này ghi đè
giá trị `api.on(..., { timeoutMs })` do tác giả Plugin đặt. Mỗi giá trị được cấu hình phải
là số nguyên dương không lớn hơn 600000 mili giây. Ưu tiên ghi đè theo từng điểm móc
cho các điểm móc đã biết là chậm để một Plugin không nhận ngân sách dài hơn
`hooks.timeouts.<hookName>` ghi đè `hooks.timeoutMs`, giá trị này ghi đè giá trị
`api.on(..., { timeoutMs })` do tác giả Plugin đặt. Mỗi giá trị được cấu hình phải
là số nguyên dương không lớn hơn 600000 mili giây. Ưu tiên ghi đè theo từng hook
cho các hook được biết là chậm để một Plugin không nhận ngân sách dài hơn
ở mọi nơi.
Mỗi điểm móc nhận `event.context.pluginConfig`, tức cấu hình đã phân giải cho
Plugin đã đăng ký trình xử lý đó. Dùng nó cho các quyết định điểm móc cần
tùy chọn Plugin hiện tại; OpenClaw tiêm nó cho từng trình xử lý mà không biến đổi
Mỗi hook nhận `event.context.pluginConfig`, cấu hình đã phân giải cho
Plugin đã đăng ký handler đó. Dùng nó cho các quyết định hook cần
tùy chọn Plugin hiện tại; OpenClaw chèn cấu hình này theo từng handler mà không làm thay đổi
đối tượng sự kiện dùng chung mà các Plugin khác nhìn thấy.
## Danh mục điểm móc
## Danh mục hook
Các điểm móc được nhóm theo bề mặt mà chúng mở rộng. Các tên in **đậm** chấp nhận
kết quả quyết định (chặn, hủy, ghi đè, hoặc yêu cầu phê duyệt); tất cả tên còn lại
Các hook được nhóm theo bề mặt mà chúng mở rộng. Tên in **đậm** chấp nhận
kết quả quyết định (chặn, hủy, ghi đè, hoặc yêu cầu phê duyệt); tất cả các hook khác
chỉ dùng để quan sát.
**Lượt agent**
- `before_model_resolve` — ghi đè nhà cung cấp hoặc mô hình trước khi tải tin nhắn phiên
- `agent_turn_prepare` — tiêu thụ các phần tiêm lượt Plugin đã xếp hàng và thêm ngữ cảnh cùng lượt trước các điểm móc prompt
- `before_model_resolve` — ghi đè provider hoặc mô hình trước khi tải tin nhắn phiên
- `agent_turn_prepare` — tiêu thụ các phần chèn lượt Plugin đã xếp hàng và thêm ngữ cảnh cùng lượt trước các hook prompt
- `before_prompt_build` — thêm ngữ cảnh động hoặc văn bản system prompt trước lệnh gọi mô hình
- `before_agent_start` — pha kết hợp chỉ để tương thích; ưu tiên hai điểm móc phía trên
- **`before_agent_reply`** — rút ngắn lượt mô hình bằng một phản hồi tổng hợp hoặc im lặng
- **`before_agent_finalize`** — kiểm tra câu trả lời cuối tự nhiên và yêu cầu thêm một lượt mô hình nữa
- `agent_end` — quan sát tin nhắn cuối, trạng thái thành công, và thời lượng chạy
- `heartbeat_prompt_contribution` — thêm ngữ cảnh chỉ dành cho Heartbeat cho các Plugin giám sát nền và vòng đời
- `before_agent_start` — pha kết hợp chỉ để tương thích; ưu tiên hai hook ở trên
- **`before_agent_reply`** — đi tắt lượt mô hình bằng phản hồi tổng hợp hoặc im lặng
- **`before_agent_finalize`** — kiểm tra câu trả lời cuối tự nhiên và yêu cầu thêm một lượt mô hình
- `agent_end` — quan sát tin nhắn cuối, trạng thái thành công và thời lượng chạy
- `heartbeat_prompt_contribution` — thêm ngữ cảnh chỉ dành cho Heartbeat cho Plugin giám sát nền và vòng đời
**Quan sát hội thoại**
- `model_call_started` / `model_call_ended` — quan sát siêu dữ liệu lệnh gọi nhà cung cấp/mô hình đã được làm sạch, thời gian, kết quả, và các hash mã yêu cầu có giới hạn mà không có nội dung prompt hoặc phản hồi
- `llm_input` — quan sát đầu vào nhà cung cấp (system prompt, prompt, lịch sử)
- `llm_output` — quan sát đầu ra nhà cung cấp
- `model_call_started` / `model_call_ended` — quan sát metadata lệnh gọi provider/mô hình đã được làm sạch, thời gian, kết quả và hash request-id có giới hạn mà không có nội dung prompt hoặc phản hồi
- `llm_input` — quan sát đầu vào provider (system prompt, prompt, lịch sử)
- `llm_output` — quan sát đầu ra provider
**Công cụ**
- **`before_tool_call`** — viết lại tham số công cụ, chặn thực thi, hoặc yêu cầu phê duyệt
- `after_tool_call` — quan sát kết quả công cụ, lỗi, và thời lượng
- `after_tool_call` — quan sát kết quả công cụ, lỗi và thời lượng
- **`tool_result_persist`** — viết lại tin nhắn assistant được tạo từ kết quả công cụ
- **`before_message_write`** — kiểm tra hoặc chặn một thao tác ghi tin nhắn đang diễn ra (hiếm gặp)
**Tin nhắn và phân phối**
- **`inbound_claim`** — nhận xử lý một tin nhắn đến trước khi định tuyến agent (phản hồi tổng hợp)
- `message_received` — quan sát nội dung đến, người gửi, luồng, và siêu dữ liệu
- **`message_sending`** — viết lại nội dung đi hoặc hủy phân phối
- `message_sent` — quan sát phân phối đi thành công hoặc thất bại
- **`before_dispatch`** — kiểm tra hoặc viết lại một dispatch đi trước khi bàn giao kênh
- **`reply_dispatch`** — tham gia vào pipeline dispatch phản hồi cuối
- `message_received` — quan sát nội dung đến, người gửi, luồng và metadata
- **`message_sending`** — viết lại nội dung gửi đi hoặc hủy phân phối
- `message_sent` — quan sát phân phối gửi đi thành công hoặc thất bại
- **`before_dispatch`** — kiểm tra hoặc viết lại một dispatch gửi đi trước khi bàn giao cho kênh
- **`reply_dispatch`** — tham gia pipeline dispatch phản hồi cuối
**Phiên và Compaction**
- `session_start` / `session_end` — theo dõi ranh giới vòng đời phiên
- `before_compaction` / `after_compaction` — quan sát hoặc chú thích các chu kỳ Compaction
- `before_reset` — quan sát các sự kiện đặt lại phiên (`/reset`, đặt lại bằng chương trình)
- `before_reset` — quan sát sự kiện đặt lại phiên (`/reset`, đặt lại theo chương trình)
**Subagent**
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — điều phối định tuyến subagent và phân phối hoàn tất
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — phối hợp định tuyến subagent và phân phối hoàn tất
**Vòng đời**
- `gateway_start` / `gateway_stop` — khởi động hoặc dừng các dịch vụ do Plugin sở hữu cùng với Gateway
- `gateway_start` / `gateway_stop` — khởi động hoặc dừng các dịch vụ do Plugin sở hữu cùng Gateway
- `cron_changed` — quan sát các thay đổi vòng đời Cron do Gateway sở hữu (đã thêm, đã cập nhật, đã xóa, đã bắt đầu, đã hoàn tất, đã lên lịch)
- **`before_install`** — kiểm tra các lần quét cài đặt skill hoặc Plugin và tùy chọn chặn
- **`before_install`** — kiểm tra các lần quét cài đặt Skills hoặc Plugin và tùy chọn chặn
## Chính sách lệnh gọi công cụ
@ -163,7 +163,7 @@ chỉ dùng để quan sát.
- `event.runId` tùy chọn
- `event.toolCallId` tùy chọn
- các trường ngữ cảnh như `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`,
`ctx.runId`, `ctx.jobId` (được đặt trên các lần chạy do Cron điều khiển), và `ctx.trace` chẩn đoán
`ctx.runId`, `ctx.jobId` (được đặt trên các lượt chạy do Cron điều khiển), và `ctx.trace` chẩn đoán
Nó có thể trả về:
@ -188,46 +188,46 @@ type BeforeToolCallResult = {
Quy tắc:
- `block: true` là quyết định cuối cùng và bỏ qua các trình xử lý có độ ưu tiên thấp hơn.
- `block: true` là quyết định kết thúc và bỏ qua các handler có priority thấp hơn.
- `block: false` được xem như không có quyết định.
- `params` viết lại tham số công cụ để thực thi.
- `requireApproval` tạm dừng lần chạy agent và hỏi người dùng thông qua phê duyệt Plugin.
Lệnh `/approve` có thể phê duyệt cả exec và phê duyệt Plugin.
- Một `block: true` có độ ưu tiên thấp hơn vẫn có thể chặn sau khi một điểm móc có độ ưu tiên cao hơn
- `requireApproval` tạm dừng lượt chạy agent và hỏi người dùng thông qua các phê duyệt Plugin.
Lệnh `/approve` có thể phê duyệt cả phê duyệt exec và Plugin.
- Một `block: true` có priority thấp hơn vẫn có thể chặn sau khi một hook có priority cao hơn
đã yêu cầu phê duyệt.
- `onResolution` nhận quyết định phê duyệt đã phân giải — `allow-once`,
`allow-always`, `deny`, `timeout`, hoặc `cancelled`.
Các Plugin đi kèm cần chính sách cấp host có thể đăng ký chính sách công cụ đáng tin cậy
bằng `api.registerTrustedToolPolicy(...)`. Các chính sách này chạy trước các điểm móc
Các Plugin đi kèm cần chính sách cấp host có thể đăng ký chính sách công cụ tin cậy
với `api.registerTrustedToolPolicy(...)`. Các chính sách này chạy trước các hook
`before_tool_call` thông thường và trước quyết định của Plugin bên ngoài. Chỉ dùng chúng
cho các cổng kiểm soát được host tin cậy như chính sách workspace, thực thi ngân sách, hoặc
an toàn quy trình làm việc được dành riêng. Plugin bên ngoài nên dùng các điểm móc `before_tool_call`
bình thường.
cho các cổng được host tin cậy như chính sách workspace, thực thi ngân sách, hoặc
an toàn workflow dành riêng. Plugin bên ngoài nên dùng các hook `before_tool_call`
thông thường.
### Lưu giữ kết quả công cụ
Kết quả công cụ có thể bao gồm `details` có cấu trúc để hiển thị UI, chẩn đoán,
định tuyến phương tiện, hoặc siêu dữ liệu do Plugin sở hữu. Xem `details` là siêu dữ liệu runtime,
định tuyến media, hoặc metadata do Plugin sở hữu. Xem `details` là metadata runtime,
không phải nội dung prompt:
- OpenClaw loại bỏ `toolResult.details` trước khi phát lại nhà cung cấp và đầu vào Compaction
để siêu dữ liệu không trở thành ngữ cảnh mô hình.
- Các mục phiên đã lưu giữ chỉ giữ `details` có giới hạn. Chi tiết quá lớn được
thay bằng một bản tóm tắt gọn và `persistedDetailsTruncated: true`.
- OpenClaw loại bỏ `toolResult.details` trước khi phát lại provider và đầu vào Compaction
để metadata không trở thành ngữ cảnh mô hình.
- Các mục phiên được lưu giữ chỉ giữ `details` có giới hạn. Details quá lớn được
thay thế bằng bản tóm tắt gọn và `persistedDetailsTruncated: true`.
- `tool_result_persist` và `before_message_write` chạy trước giới hạn lưu giữ cuối cùng.
Các điểm móc vẫn nên giữ `details` trả về nhỏ gọn và tránh
đặt văn bản liên quan đến prompt chỉ trong `details`; đặt đầu ra công cụ mà mô hình thấy được
Hook vẫn nên giữ `details` trả về ở kích thước nhỏ và tránh
đặt văn bản liên quan đến prompt chỉ trong `details`; đặt đầu ra công cụ mà mô hình có thể thấy
trong `content`.
## Điểm móc prompt và mô hình
## Hook prompt và mô hình
Dùng các điểm móc theo pha cụ thể cho Plugin mới:
Dùng các hook theo pha cụ thể cho Plugin mới:
- `before_model_resolve`: chỉ nhận prompt hiện tại và siêu dữ liệu tệp đính kèm.
- `before_model_resolve`: chỉ nhận prompt hiện tại và metadata tệp đính kèm.
Trả về `providerOverride` hoặc `modelOverride`.
- `agent_turn_prepare`: nhận prompt hiện tại, tin nhắn phiên đã chuẩn bị,
và mọi phần tiêm đúng-một-lần đã xếp hàng được rút cho phiên này. Trả về
và mọi phần chèn đã xếp hàng đúng-một-lần được rút cho phiên này. Trả về
`prependContext` hoặc `appendContext`.
- `before_prompt_build`: nhận prompt hiện tại và tin nhắn phiên.
Trả về `prependContext`, `appendContext`, `systemPrompt`,
@ -236,41 +236,57 @@ Dùng các điểm móc theo pha cụ thể cho Plugin mới:
`prependContext` hoặc `appendContext`. Nó dành cho các trình giám sát nền
cần tóm tắt trạng thái hiện tại mà không thay đổi các lượt do người dùng khởi tạo.
`before_agent_start` vẫn được giữ để tương thích. Ưu tiên các điểm móc tường minh phía trên
`before_agent_start` vẫn được giữ để tương thích. Ưu tiên các hook rõ ràng ở trên
để Plugin của bạn không phụ thuộc vào một pha kết hợp cũ.
`before_agent_start` và `agent_end` bao gồm `event.runId` khi OpenClaw có thể
xác định lần chạy đang hoạt động. Cùng giá trị đó cũng có trên `ctx.runId`.
Các lần chạy do Cron điều khiển cũng cung cấp `ctx.jobId` (mã công việc Cron khởi nguồn) để
điểm móc Plugin có thể giới hạn chỉ số, tác dụng phụ, hoặc trạng thái vào một công việc
đã lên lịch cụ thể.
xác định lượt chạy đang hoạt động. Cùng giá trị đó cũng có sẵn trên `ctx.runId`.
Các lượt chạy do Cron điều khiển cũng hiển thị `ctx.jobId` (id job Cron nguồn) để
hook Plugin có thể giới hạn metrics, tác dụng phụ hoặc trạng thái theo một job đã lên lịch
cụ thể.
Đối với các lần chạy bắt nguồn từ kênh, `ctx.messageProvider` là bề mặt nhà cung cấp như
`discord` hoặc `telegram`, trong khi `ctx.channelId` là định danh đích hội thoại
khi OpenClaw có thể suy ra từ khóa phiên hoặc siêu dữ liệu phân phối.
Đối với các lượt chạy bắt nguồn từ kênh, `ctx.messageProvider` là bề mặt provider như
`discord` hoặc `telegram`, còn `ctx.channelId` là mã định danh đích hội thoại
khi OpenClaw có thể suy ra từ khóa phiên hoặc metadata phân phối.
`agent_end` là điểm móc quan sát và chạy theo kiểu fire-and-forget sau lượt. Trình
chạy điểm móc áp dụng thời gian chờ 30 giây để một Plugin bị kẹt hoặc endpoint
embedding không thể khiến promise của điểm móc treo mãi. Hết thời gian chờ được ghi log và
`agent_end` là hook quan sát và chạy fire-and-forget sau lượt. Trình chạy
hook áp dụng timeout 30 giây để một Plugin hoặc endpoint embedding bị kẹt
không thể khiến promise hook chờ mãi. Timeout được ghi log và
OpenClaw tiếp tục; nó không hủy công việc mạng do Plugin sở hữu trừ khi
Plugin cũng dùng tín hiệu hủy riêng.
Plugin cũng dùng abort signal riêng.
Dùng `model_call_started` và `model_call_ended` cho telemetry lệnh gọi nhà cung cấp
không nên nhận prompt thô, lịch sử, phản hồi, header, thân yêu cầu, hoặc mã yêu cầu
nhà cung cấp. Các điểm móc này bao gồm siêu dữ liệu ổn định như
Dùng `model_call_started` và `model_call_ended` cho telemetry lệnh gọi provider
không nên nhận prompt thô, lịch sử, phản hồi, header, request body,
hoặc request ID của provider. Các hook này bao gồm metadata ổn định như
`runId`, `callId`, `provider`, `model`, `api`/`transport` tùy chọn,
`durationMs`/`outcome` kết thúc, và `upstreamRequestIdHash` khi OpenClaw có thể suy ra
hash mã yêu cầu nhà cung cấp có giới hạn.
hash request-id provider có giới hạn.
`before_agent_finalize` chỉ chạy khi một harness sắp chấp nhận câu trả lời assistant cuối
tự nhiên. Nó không phải đường dẫn hủy `/stop` và không
`before_agent_finalize` chỉ chạy khi harness sắp chấp nhận một
câu trả lời cuối tự nhiên của assistant. Nó không phải đường dẫn hủy `/stop` và không
chạy khi người dùng hủy một lượt. Trả về `{ action: "revise", reason }` để yêu cầu
harness chạy thêm một lượt mô hình trước khi hoàn tất, `{ action:
harness thực hiện thêm một lượt mô hình trước khi hoàn tất, `{ action:
"finalize", reason? }` để buộc hoàn tất, hoặc bỏ qua kết quả để tiếp tục.
Các điểm móc `Stop` gốc của Codex được chuyển tiếp vào điểm móc này dưới dạng quyết định
Các hook `Stop` gốc của Codex được chuyển tiếp vào hook này dưới dạng quyết định
`before_agent_finalize` của OpenClaw.
Các Plugin không đi kèm cần `llm_input`, `llm_output`,
Khi trả về `action: "revise"`, Plugin có thể bao gồm metadata `retry` để làm cho
lượt mô hình bổ sung có giới hạn và an toàn khi phát lại:
```typescript
type BeforeAgentFinalizeRetry = {
instruction: string;
idempotencyKey?: string;
maxAttempts?: number;
};
```
`instruction` được nối vào lý do chỉnh sửa gửi tới harness.
`idempotencyKey` cho phép host đếm số lần thử lại cho cùng một yêu cầu Plugin trên
các quyết định finalize tương đương, và `maxAttempts` giới hạn số lượt bổ sung mà
host sẽ cho phép trước khi tiếp tục với câu trả lời cuối tự nhiên.
Plugin không đi kèm cần `llm_input`, `llm_output`,
`before_agent_finalize`, hoặc `agent_end` phải đặt:
```json
@ -287,114 +303,64 @@ Các Plugin không đi kèm cần `llm_input`, `llm_output`,
}
```
Các điểm móc biến đổi prompt và phần tiêm bền vững cho lượt kế tiếp có thể bị tắt theo từng Plugin
bằng `plugins.entries.<id>.hooks.allowPromptInjection=false`.
Các hook làm thay đổi prompt và phần chèn lượt tiếp theo bền vững có thể bị tắt theo từng Plugin
với `plugins.entries.<id>.hooks.allowPromptInjection=false`.
### Phần mở rộng phiên và phần tiêm lượt kế tiếp
### Tiện ích mở rộng phiên và phần chèn lượt tiếp theo
Plugin quy trình làm việc có thể lưu giữ trạng thái phiên nhỏ tương thích JSON bằng
`api.registerSessionExtension(...)` và cập nhật nó thông qua phương thức
`sessions.pluginPatch` của Gateway. Các hàng phiên chiếu trạng thái phần mở rộng đã đăng ký
qua `pluginExtensions`, cho phép Control UI và các client khác hiển thị
trạng thái do Plugin sở hữu mà không cần biết nội bộ Plugin.
Plugin quy trình làm việc có thể lưu giữ trạng thái phiên nhỏ tương thích với JSON bằng `api.registerSessionExtension(...)` và cập nhật trạng thái đó thông qua phương thức `sessions.pluginPatch` của Gateway. Các hàng phiên chiếu trạng thái tiện ích mở rộng đã đăng ký thông qua `pluginExtensions`, cho phép Control UI và các máy khách khác hiển thị trạng thái do Plugin sở hữu mà không cần biết nội bộ Plugin.
Dùng `api.enqueueNextTurnInjection(...)` khi một Plugin cần ngữ cảnh bền vững để
đến lượt mô hình tiếp theo đúng một lần. OpenClaw xử lý hết các injection đang
được xếp hàng trước prompt hook, loại bỏ các injection đã hết hạn, và khử trùng lặp theo `idempotencyKey`
cho từng Plugin. Đây là ranh giới phù hợp cho việc tiếp tục sau phê duyệt, tóm tắt chính sách,
các delta từ trình giám sát nền, và phần tiếp nối lệnh cần hiển thị với
mô hình ở lượt tiếp theo nhưng không nên trở thành văn bản system prompt vĩnh viễn.
Dùng `api.enqueueNextTurnInjection(...)` khi một Plugin cần ngữ cảnh bền vững được đưa đến lượt mô hình tiếp theo đúng một lần. OpenClaw xả các nội dung chèn đã xếp hàng trước các hook prompt, bỏ các nội dung chèn đã hết hạn, và khử trùng lặp theo `idempotencyKey` cho từng Plugin. Đây là ranh giới phù hợp cho việc tiếp tục phê duyệt, tóm tắt chính sách, phần chênh lệch từ trình giám sát nền, và phần tiếp nối lệnh cần hiển thị với mô hình ở lượt tiếp theo nhưng không nên trở thành văn bản prompt hệ thống vĩnh viễn.
Ngữ nghĩa dọn dẹp là một phần của hợp đồng. Callback dọn dẹp phần mở rộng phiên và
vòng đời runtime nhận `reset`, `delete`, `disable`, hoặc
`restart`. Host xóa trạng thái phần mở rộng phiên bền vững của Plugin sở hữu
và các injection lượt kế tiếp đang chờ cho reset/delete/disable; restart giữ
trạng thái phiên bền vững trong khi callback dọn dẹp cho phép Plugin giải phóng các job
bộ lập lịch, ngữ cảnh chạy, và các tài nguyên ngoài băng khác cho thế hệ runtime
cũ.
Ngữ nghĩa dọn dẹp là một phần của hợp đồng. Callback dọn dẹp tiện ích mở rộng phiên và dọn dẹp vòng đời runtime nhận `reset`, `delete`, `disable`, hoặc `restart`. Máy chủ xóa trạng thái tiện ích mở rộng phiên bền vững và các nội dung chèn lượt tiếp theo đang chờ của Plugin sở hữu đối với reset/delete/disable; restart giữ trạng thái phiên bền vững trong khi các callback dọn dẹp cho phép Plugin giải phóng tác vụ bộ lập lịch, ngữ cảnh chạy, và các tài nguyên ngoài băng khác cho thế hệ runtime cũ.
## Hook thông điệp
## Hook tin nhắn
Dùng hook thông điệp cho định tuyến cấp kênh và chính sách phân phối:
Dùng hook tin nhắn cho định tuyến cấp kênh và chính sách gửi:
- `message_received`: quan sát nội dung đầu vào, người gửi, `threadId`, `messageId`,
`senderId`, tương quan run/session tùy chọn, và metadata.
- `message_received`: quan sát nội dung đến, người gửi, `threadId`, `messageId`, `senderId`, tương quan run/session tùy chọn, và siêu dữ liệu.
- `message_sending`: viết lại `content` hoặc trả về `{ cancel: true }`.
- `message_sent`: quan sát thành công hoặc thất bại cuối cùng.
- `message_sent`: quan sát kết quả thành công hoặc thất bại cuối cùng.
Với phản hồi TTS chỉ có âm thanh, `content` có thể chứa bản chép lời nói bị ẩn
ngay cả khi payload của kênh không có văn bản/chú thích hiển thị. Việc viết lại
`content` chỉ cập nhật bản chép lời hiển thị với hook; nội dung đó không được render thành
chú thích phương tiện.
Đối với phản hồi TTS chỉ có âm thanh, `content` có thể chứa bản chép lời nói ẩn ngay cả khi tải trọng kênh không có văn bản/chú thích hiển thị. Việc viết lại `content` đó chỉ cập nhật bản chép lời mà hook thấy được; nó không được kết xuất dưới dạng chú thích phương tiện.
Ngữ cảnh hook thông điệp cung cấp các trường tương quan ổn định khi có sẵn:
`ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`,
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId`, và `ctx.callDepth`. Ưu tiên
các trường hạng nhất này trước khi đọc metadata cũ.
Ngữ cảnh hook tin nhắn cung cấp các trường tương quan ổn định khi có sẵn: `ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`, `ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId`, và `ctx.callDepth`. Ưu tiên các trường hạng nhất này trước khi đọc siêu dữ liệu kế thừa.
Ưu tiên các trường có kiểu `threadId` và `replyToId` trước khi dùng metadata
riêng của từng kênh.
Ưu tiên các trường `threadId` và `replyToId` có kiểu trước khi dùng siêu dữ liệu riêng theo kênh.
Quy tắc quyết định:
- `message_sending` với `cancel: true` là quyết định cuối cùng.
- `message_sending` với `cancel: true` là quyết định kết thúc.
- `message_sending` với `cancel: false` được xem là không có quyết định.
- `content` đã được viết lại tiếp tục đi tới các hook có độ ưu tiên thấp hơn, trừ khi một hook sau đó
hủy phân phối.
- `content` đã được viết lại tiếp tục đến các hook có độ ưu tiên thấp hơn trừ khi một hook sau đó hủy việc gửi.
## Hook cài đặt
`before_install` chạy sau bước quét tích hợp sẵn cho các lượt cài đặt Skills và Plugin.
Trả về các phát hiện bổ sung hoặc `{ block: true, blockReason }` để dừng
cài đặt.
`before_install` chạy sau quá trình quét tích hợp sẵn cho các lượt cài đặt Skills và Plugin. Trả về các phát hiện bổ sung hoặc `{ block: true, blockReason }` để dừng cài đặt.
`block: true` là quyết định cuối cùng. `block: false` được xem là không có quyết định.
`block: true` là quyết định kết thúc. `block: false` được xem là không có quyết định.
## Vòng đời Gateway
Dùng `gateway_start` cho các dịch vụ Plugin cần trạng thái do Gateway sở hữu. Ngữ cảnh
cung cấp `ctx.config`, `ctx.workspaceDir`, và `ctx.getCron?.()` để
kiểm tra và cập nhật cron. Dùng `gateway_stop` để dọn dẹp các tài nguyên
chạy lâu.
Dùng `gateway_start` cho các dịch vụ Plugin cần trạng thái do Gateway sở hữu. Ngữ cảnh cung cấp `ctx.config`, `ctx.workspaceDir`, và `ctx.getCron?.()` để kiểm tra và cập nhật cron. Dùng `gateway_stop` để dọn dẹp tài nguyên chạy dài hạn.
Không dựa vào hook nội bộ `gateway:startup` cho các dịch vụ runtime
do Plugin sở hữu.
Không dựa vào hook nội bộ `gateway:startup` cho các dịch vụ runtime do Plugin sở hữu.
`cron_changed` kích hoạt cho các sự kiện vòng đời cron do gateway sở hữu với payload
sự kiện có kiểu, bao gồm các lý do `added`, `updated`, `removed`, `started`, `finished`,
và `scheduled`. Sự kiện mang một snapshot `PluginHookGatewayCronJob`
(bao gồm `state.nextRunAtMs`, `state.lastRunStatus`, và
`state.lastError` khi có) cùng với `PluginHookGatewayCronDeliveryStatus`
là `not-requested` | `delivered` | `not-delivered` | `unknown`. Các sự kiện removed
vẫn mang snapshot job đã xóa để bộ lập lịch bên ngoài có thể
đối soát trạng thái. Dùng `ctx.getCron?.()` và `ctx.config` từ ngữ cảnh
runtime khi đồng bộ các bộ lập lịch đánh thức bên ngoài, và giữ OpenClaw làm
nguồn sự thật cho việc kiểm tra đến hạn và thực thi.
`cron_changed` kích hoạt cho các sự kiện vòng đời cron do gateway sở hữu với tải trọng sự kiện có kiểu bao gồm các lý do `added`, `updated`, `removed`, `started`, `finished`, và `scheduled`. Sự kiện mang một bản chụp `PluginHookGatewayCronJob` (bao gồm `state.nextRunAtMs`, `state.lastRunStatus`, và `state.lastError` khi có) cùng với `PluginHookGatewayCronDeliveryStatus` là `not-requested` | `delivered` | `not-delivered` | `unknown`. Sự kiện đã xóa vẫn mang bản chụp tác vụ đã xóa để các bộ lập lịch bên ngoài có thể đối soát trạng thái. Dùng `ctx.getCron?.()` và `ctx.config` từ ngữ cảnh runtime khi đồng bộ bộ lập lịch đánh thức bên ngoài, và giữ OpenClaw làm nguồn sự thật cho các lần kiểm tra đến hạn và thực thi.
## Các phần sắp ngừng hỗ trợ
## Các ngừng hỗ trợ sắp tới
Một vài bề mặt liền kề hook đã bị ngừng hỗ trợ nhưng vẫn được hỗ trợ. Hãy di chuyển
trước bản phát hành major tiếp theo:
Một vài bề mặt liền kề hook đã ngừng hỗ trợ nhưng vẫn còn được hỗ trợ. Hãy di chuyển trước bản phát hành lớn tiếp theo:
- **Phong bì kênh dạng văn bản thuần** trong trình xử lý `inbound_claim` và `message_received`.
Đọc `BodyForAgent` và các khối ngữ cảnh người dùng có cấu trúc
thay vì phân tích văn bản phong bì phẳng. Xem
[Phong bì kênh dạng văn bản thuần → BodyForAgent](/vi/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** vẫn còn để tương thích. Plugin mới nên dùng
`before_model_resolve` và `before_prompt_build` thay vì pha
kết hợp.
- **`onResolution` trong `before_tool_call`** hiện dùng union có kiểu
`PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` /
`timeout` / `cancelled`) thay vì một `string` tự do.
- **Phong bì kênh văn bản thuần** trong các trình xử lý `inbound_claim` và `message_received`. Đọc `BodyForAgent` và các khối ngữ cảnh người dùng có cấu trúc thay vì phân tích văn bản phong bì phẳng. Xem [Phong bì kênh văn bản thuần → BodyForAgent](/vi/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** vẫn tồn tại để tương thích. Plugin mới nên dùng `before_model_resolve` và `before_prompt_build` thay vì pha kết hợp.
- **`onResolution` trong `before_tool_call`** hiện dùng union `PluginApprovalResolution` có kiểu (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) thay vì `string` dạng tự do.
Để xem danh sách đầy đủ — đăng ký capability bộ nhớ, profile suy luận của provider,
nhà cung cấp xác thực bên ngoài, kiểu khám phá provider, accessor runtime tác vụ,
và đổi tên `command-auth` → `command-status` — xem
[Di chuyển Plugin SDK → Các phần đang ngừng hỗ trợ](/vi/plugins/sdk-migration#active-deprecations).
Để xem danh sách đầy đủ — đăng ký khả năng bộ nhớ, hồ sơ suy nghĩ của nhà cung cấp, nhà cung cấp xác thực bên ngoài, kiểu khám phá nhà cung cấp, bộ truy cập runtime tác vụ, và đổi tên `command-auth` → `command-status` — xem [Di chuyển Plugin SDK → Các ngừng hỗ trợ đang hoạt động](/vi/plugins/sdk-migration#active-deprecations).
## Liên quan
- [Di chuyển Plugin SDK](/vi/plugins/sdk-migration) — các phần đang ngừng hỗ trợ và mốc thời gian loại bỏ
- [Di chuyển Plugin SDK](/vi/plugins/sdk-migration) — các ngừng hỗ trợ đang hoạt động và mốc thời gian gỡ bỏ
- [Xây dựng Plugin](/vi/plugins/building-plugins)
- [Tổng quan Plugin SDK](/vi/plugins/sdk-overview)
- [Điểm vào Plugin](/vi/plugins/sdk-entrypoints)

82
docs/vi/plugins/manage-plugins.md
View File

@ -1,22 +1,21 @@
---
read_when:
- Bạn muốn các ví dụ nhanh để cài đặt, liệt kê, cập nhật hoặc gỡ cài đặt Plugin
- Bạn muốn các ví dụ nhanh về cách cài đặt, liệt kê, cập nhật hoặc gỡ cài đặt Plugin
- Bạn muốn chọn giữa ClawHub và phân phối Plugin qua npm
- Bạn đang xuất bản một gói Plugin
sidebarTitle: Manage plugins
summary: Ví dụ nhanh về cách cài đặt, liệt kê, gỡ cài đặt, cập nhật và phát hành các Plugin OpenClaw
summary: Ví dụ nhanh về cài đặt, liệt kê, gỡ cài đặt, cập nhật và phát hành các Plugin OpenClaw
title: Quản lý Plugin
x-i18n:
generated_at: "2026-05-02T22:19:55Z"
generated_at: "2026-05-05T01:49:29Z"
model: gpt-5.5
provider: openai
source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320
source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c
source_path: plugins/manage-plugins.md
workflow: 16
---
Hầu hết quy trình Plugin chỉ gồm vài lệnh: tìm kiếm, cài đặt, khởi động lại Gateway,
xác minh, và gỡ cài đặt khi bạn không còn cần Plugin nữa.
Hầu hết quy trình làm việc với Plugin chỉ gồm vài lệnh: tìm kiếm, cài đặt, khởi động lại Gateway, xác minh, và gỡ cài đặt khi bạn không còn cần Plugin đó nữa.
## Liệt kê Plugin
@ -27,18 +26,14 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
Dùng `--json` cho script. Nó bao gồm chẩn đoán registry và `dependencyStatus`
tĩnh của từng Plugin khi gói Plugin khai báo `dependencies` hoặc
`optionalDependencies`.
Dùng `--json` cho script. Tùy chọn này bao gồm chẩn đoán registry và `dependencyStatus` tĩnh của từng Plugin khi gói Plugin khai báo `dependencies` hoặc `optionalDependencies`.
```bash
openclaw plugins list --json \
| jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
```
`plugins list` là một kiểm tra kho lạnh. Nó hiển thị những gì OpenClaw có thể
phát hiện từ cấu hình, manifest và registry Plugin; nó không chứng minh rằng một
tiến trình Gateway đang chạy đã nhập runtime của Plugin.
`plugins list` là một lượt kiểm tra kho dữ liệu nguội. Nó hiển thị những gì OpenClaw có thể phát hiện từ cấu hình, manifest và registry Plugin; nó không chứng minh rằng một tiến trình Gateway đang chạy đã import runtime của Plugin.
## Cài đặt Plugin
@ -72,9 +67,7 @@ openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
```
Dùng `inspect --runtime` khi bạn cần bằng chứng rằng Plugin đã đăng ký các bề
mặt runtime như công cụ, hook, dịch vụ, phương thức Gateway hoặc lệnh CLI do
Plugin sở hữu.
Dùng `inspect --runtime` khi bạn cần bằng chứng rằng Plugin đã đăng ký các bề mặt runtime như công cụ, hook, dịch vụ, phương thức Gateway hoặc lệnh CLI do Plugin sở hữu.
## Cập nhật Plugin
@ -84,23 +77,16 @@ openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
Nếu một Plugin được cài đặt từ một dist-tag npm như `@beta`, các lần gọi
`update <plugin-id>` sau này sẽ dùng lại tag đã ghi đó. Truyền một spec npm tường
minh sẽ chuyển cài đặt được theo dõi sang spec đó cho các lần cập nhật trong
tương lai.
Nếu một Plugin được cài đặt từ một dist-tag npm như `@beta`, các lệnh `update <plugin-id>` sau đó sẽ dùng lại tag đã được ghi nhận đó. Truyền một spec npm rõ ràng sẽ chuyển bản cài đặt được theo dõi sang spec đó cho các lần cập nhật trong tương lai.
```bash
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
```
Lệnh thứ hai đưa một Plugin trở lại dòng phát hành mặc định của registry khi nó
trước đó đã được ghim vào một phiên bản hoặc tag chính xác.
Lệnh thứ hai đưa một Plugin trở lại dòng phát hành mặc định của registry khi trước đó nó đã được ghim vào một phiên bản hoặc tag chính xác.
Khi `openclaw update` chạy trên kênh beta, các bản ghi Plugin npm và ClawHub ở
dòng mặc định sẽ thử bản phát hành Plugin `@beta` tương ứng trước. Nếu bản phát
hành beta đó không tồn tại, OpenClaw sẽ quay về spec mặc định/mới nhất đã ghi.
Các phiên bản chính xác và tag tường minh như `@rc` hoặc `@beta` được giữ nguyên.
Khi `openclaw update` chạy trên kênh beta, các bản ghi Plugin npm và ClawHub thuộc dòng mặc định sẽ thử bản phát hành Plugin `@beta` tương ứng trước. Nếu bản phát hành beta đó không tồn tại, OpenClaw sẽ quay về spec mặc định/mới nhất đã ghi nhận. Với Plugin npm, OpenClaw cũng quay về khi gói beta tồn tại nhưng không vượt qua bước xác thực cài đặt. Các phiên bản chính xác và tag rõ ràng như `@rc` hoặc `@beta` được giữ nguyên.
## Gỡ cài đặt Plugin
@ -111,20 +97,15 @@ openclaw plugins uninstall <plugin-id> --keep-files
openclaw gateway restart
```
Gỡ cài đặt sẽ xóa mục cấu hình của Plugin, bản ghi chỉ mục Plugin, các mục trong
danh sách cho phép/từ chối và các đường dẫn tải đã liên kết khi áp dụng. Các thư
mục cài đặt được quản lý sẽ bị xóa trừ khi bạn truyền `--keep-files`.
Gỡ cài đặt sẽ xóa mục cấu hình của Plugin, bản ghi chỉ mục Plugin, các mục danh sách cho phép/từ chối, và đường dẫn tải được liên kết khi áp dụng. Các thư mục cài đặt được quản lý sẽ bị xóa trừ khi bạn truyền `--keep-files`.
## Xuất bản Plugin
## Phát hành Plugin
Bạn có thể xuất bản Plugin bên ngoài lên [ClawHub](https://clawhub.ai),
npmjs.com, hoặc cả hai.
Bạn có thể phát hành Plugin bên ngoài lên [ClawHub](https://clawhub.ai), npmjs.com hoặc cả hai.
### Xuất bản lên ClawHub
### Phát hành lên ClawHub
ClawHub là bề mặt khám phá công khai chính cho Plugin OpenClaw. Nó cung cấp cho
người dùng siêu dữ liệu có thể tìm kiếm, lịch sử phiên bản và kết quả quét
registry trước khi cài đặt.
ClawHub là bề mặt khám phá công khai chính cho Plugin OpenClaw. Nó cung cấp cho người dùng metadata có thể tìm kiếm, lịch sử phiên bản và kết quả quét registry trước khi cài đặt.
```bash
npm i -g clawhub
@ -143,10 +124,9 @@ openclaw plugins install <package>
Dạng không tiền tố vẫn kiểm tra ClawHub trước.
### Xuất bản lên npmjs.com
### Phát hành lên npmjs.com
Plugin npm gốc phải bao gồm manifest Plugin và siêu dữ liệu entrypoint OpenClaw
trong `package.json`.
Plugin npm gốc phải bao gồm manifest Plugin và metadata entrypoint OpenClaw trong `package.json`.
```json package.json
{
@ -163,7 +143,7 @@ trong `package.json`.
npm publish --access public
```
Người dùng cài đặt chỉ từ npm bằng:
Người dùng chỉ cài đặt từ npm bằng:
```bash
openclaw plugins install npm:@acme/openclaw-plugin
@ -171,23 +151,19 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
```
Nếu cùng gói đó cũng có trên ClawHub, `npm:` sẽ bỏ qua tra cứu ClawHub và ép phân
giải bằng npm.
Nếu cùng gói đó cũng có trên ClawHub, `npm:` sẽ bỏ qua bước tra cứu ClawHub và buộc phân giải bằng npm.
## Lựa chọn nguồn
## Chọn nguồn
- **ClawHub**: dùng khi bạn muốn khám phá gốc OpenClaw, tóm tắt quét, phiên bản
và gợi ý cài đặt.
- **npmjs.com**: dùng khi bạn đã phân phối các gói JavaScript hoặc cần quy trình
dist-tag npm/registry riêng tư.
- **Git**: dùng khi bạn muốn cài đặt trực tiếp từ một nhánh, tag hoặc commit.
- **Đường dẫn cục bộ**: dùng khi bạn đang phát triển hoặc kiểm thử một Plugin
trên cùng máy.
- **ClawHub**: dùng khi bạn muốn khám phá kiểu gốc OpenClaw, tóm tắt quét, phiên bản và gợi ý cài đặt.
- **npmjs.com**: dùng khi bạn đã phát hành các gói JavaScript hoặc cần quy trình dist-tag/registry riêng của npm.
- **Git**: dùng khi bạn muốn cài đặt trực tiếp từ một branch, tag hoặc commit.
- **Đường dẫn cục bộ**: dùng khi bạn đang phát triển hoặc kiểm thử một Plugin trên cùng máy.
## Liên quan
- [Plugin](/vi/tools/plugin) - tổng quan và khắc phục sự cố
- [`openclaw plugins`](/vi/cli/plugins) - tham chiếu CLI đầy đủ
- [ClawHub](/vi/tools/clawhub) - thao tác xuất bản và registry
- [Plugins](/vi/tools/plugin) - tổng quan và khắc phục sự cố
- [`openclaw plugins`](/vi/cli/plugins) - tài liệu tham chiếu CLI đầy đủ
- [ClawHub](/vi/tools/clawhub) - phát hành và thao tác registry
- [Xây dựng Plugin](/vi/plugins/building-plugins) - tạo một gói Plugin
- [Manifest Plugin](/vi/plugins/manifest) - manifest và siêu dữ liệu gói
- [Manifest Plugin](/vi/plugins/manifest) - manifest và metadata gói

332
docs/vi/plugins/sdk-overview.md
View File

@ -1,32 +1,33 @@
---
read_when:
- Bạn cần biết nên import từ đường dẫn con nào của SDK
- Bạn muốn tài liệu tham khảo về tất cả các phương thức đăng ký trên OpenClawPluginApi
- Bạn đang tra cứu một export SDK cụ thể
- Bạn cần biết nên nhập từ đường dẫn con nào của SDK
- Bạn muốn một tài liệu tham khảo cho tất cả các phương thức đăng ký trên OpenClawPluginApi
- Bạn đang tra cứu một mục xuất cụ thể của SDK
sidebarTitle: Plugin SDK overview
summary: Bản đồ import, tài liệu tham chiếu API đăng ký và kiến trúc SDK
title: Tổng quan về Plugin SDK
x-i18n:
generated_at: "2026-05-02T10:49:47Z"
generated_at: "2026-05-05T01:49:41Z"
model: gpt-5.5
provider: openai
source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127
source_path: plugins/sdk-overview.md
workflow: 16
---
Plugin SDK là hợp đồng có kiểu giữa Plugin và lõi. Trang này là tài liệu tham chiếu cho **những gì cần import** và **những gì bạn có thể đăng ký**.
Plugin SDK là hợp đồng được định kiểu giữa các Plugin và phần lõi. Trang này là
tài liệu tham chiếu cho **những gì cần import** và **những gì bạn có thể đăng ký**.
<Note>
Trang này dành cho tác giả Plugin dùng `openclaw/plugin-sdk/*` bên trong
OpenClaw. Với ứng dụng bên ngoài, script, dashboard, tác vụ CI và phần mở rộng IDE
Trang này dành cho tác giả Plugin sử dụng `openclaw/plugin-sdk/*` bên trong
OpenClaw. Với ứng dụng ngoài, script, dashboard, tác vụ CI và tiện ích mở rộng IDE
muốn chạy agent thông qua Gateway, hãy dùng
[OpenClaw App SDK](/vi/concepts/openclaw-sdk) và gói `@openclaw/sdk`
thay thế.
</Note>
<Tip>
Bạn đang tìm hướng dẫn thực hành? Bắt đầu với [Xây dựng Plugin](/vi/plugins/building-plugins), dùng [Plugin kênh](/vi/plugins/sdk-channel-plugins) cho Plugin kênh, [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins) cho Plugin nhà cung cấp, và [hook Plugin](/vi/plugins/hooks) cho Plugin hook công cụ hoặc vòng đời.
Bạn đang tìm hướng dẫn thực hiện? Hãy bắt đầu với [Xây dựng Plugin](/vi/plugins/building-plugins), dùng [Plugin kênh](/vi/plugins/sdk-channel-plugins) cho Plugin kênh, [Plugin nhà cung cấp](/vi/plugins/sdk-provider-plugins) cho Plugin nhà cung cấp, và [Hook Plugin](/vi/plugins/hooks) cho Plugin hook công cụ hoặc vòng đời.
</Tip>
## Quy ước import
@ -38,80 +39,80 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Mỗi đường dẫn con là một mô-đun nhỏ, độc lập. Điều này giúp khởi động nhanh và
ngăn các vấn đề phụ thuộc vòng. Với các helper điểm vào/xây dựng dành riêng cho kênh,
Mỗi đường dẫn con là một mô-đun nhỏ, độc lập. Điều này giữ cho quá trình khởi động nhanh và
ngăn các vấn đề phụ thuộc vòng. Với helper mục nhập/xây dựng dành riêng cho kênh,
ưu tiên `openclaw/plugin-sdk/channel-core`; giữ `openclaw/plugin-sdk/core` cho
bề mặt bao quát rộng hơn và các helper dùng chung như
`buildChannelConfigSchema`.
Với cấu hình kênh, hãy phát hành JSON Schema do kênh sở hữu thông qua
Với cấu hình kênh, hãy xuất bản JSON Schema do kênh sở hữu thông qua
`openclaw.plugin.json#channelConfigs`. Đường dẫn con `plugin-sdk/channel-config-schema`
dành cho các primitive schema dùng chung và bộ dựng chung. Các Plugin đi kèm của OpenClaw
dành cho các primitive schema dùng chung và trình dựng chung. Các Plugin đi kèm của OpenClaw
dùng `plugin-sdk/bundled-channel-config-schema` cho các schema kênh đi kèm được giữ lại.
Các export tương thích đã lỗi thời vẫn nằm trên
`plugin-sdk/channel-config-schema-legacy`; không đường dẫn con schema đi kèm nào là
khuôn mẫu cho Plugin mới.
mẫu cho Plugin mới.
<Warning>
Không import các seam tiện ích mang nhãn nhà cung cấp hoặc kênh (ví dụ
Không import các seam tiện ích mang thương hiệu nhà cung cấp hoặc kênh (ví dụ
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
Các Plugin đi kèm kết hợp những đường dẫn con SDK chung bên trong barrel `api.ts` /
Các Plugin đi kèm kết hợp những đường dẫn con SDK chung bên trong các barrel `api.ts` /
`runtime-api.ts` của riêng chúng; người dùng lõi nên dùng các barrel cục bộ theo Plugin đó
hoặc thêm một hợp đồng SDK chung hẹp khi nhu cầu thật sự
xuyên kênh.
Một tập nhỏ các seam helper của Plugin đi kèm vẫn xuất hiện trong bản đồ export được tạo
khi chúng có mức sử dụng của chủ sở hữu đã được theo dõi. Chúng chỉ tồn tại để bảo trì
khi chúng có mức sử dụng của chủ sở hữu được theo dõi. Chúng chỉ tồn tại để bảo trì
Plugin đi kèm và không được khuyến nghị làm đường dẫn import cho Plugin bên thứ ba mới.
`openclaw/plugin-sdk/discord` và `openclaw/plugin-sdk/telegram-account` cũng
được giữ lại dưới dạng facade tương thích đã lỗi thời cho mức sử dụng của chủ sở hữu đã theo dõi. Không
sao chép các đường dẫn import đó vào Plugin mới; thay vào đó hãy dùng các helper runtime được tiêm và
`openclaw/plugin-sdk/discord` và `openclaw/plugin-sdk/telegram-account` cũng được
giữ lại dưới dạng facade tương thích đã lỗi thời cho mức sử dụng của chủ sở hữu được theo dõi. Không
sao chép các đường dẫn import đó vào Plugin mới; thay vào đó hãy dùng helper runtime được tiêm vào và
các đường dẫn con SDK kênh chung.
</Warning>
## Tham chiếu đường dẫn con
Plugin SDK được cung cấp dưới dạng một tập các đường dẫn con hẹp được nhóm theo khu vực (điểm vào
Plugin, kênh, nhà cung cấp, xác thực, runtime, khả năng, bộ nhớ, và các helper
Plugin đi kèm được dành riêng). Để xem toàn bộ danh mục — được nhóm và liên kết — hãy xem
[Các đường dẫn con Plugin SDK](/vi/plugins/sdk-subpaths).
Plugin SDK được cung cấp dưới dạng một tập các đường dẫn con hẹp được nhóm theo khu vực (mục nhập Plugin,
kênh, nhà cung cấp, xác thực, runtime, năng lực, bộ nhớ và các helper
Plugin đi kèm được dành riêng). Để xem danh mục đầy đủ — đã được nhóm và liên kết — hãy xem
[Các đường dẫn con của Plugin SDK](/vi/plugins/sdk-subpaths).
Danh sách được tạo gồm hơn 200 đường dẫn con nằm trong `scripts/lib/plugin-sdk-entrypoints.json`.
Danh sách hơn 200 đường dẫn con được tạo nằm trong `scripts/lib/plugin-sdk-entrypoints.json`.
## API đăng ký
Callback `register(api)` nhận một đối tượng `OpenClawPluginApi` với các
phương thức sau:
### Đăng ký khả năng
### Đăng ký năng lực
| Phương thức | Nội dung đăng ký |
| ------------------------------------------------ | ---------------------------------------- |
| `api.registerProvider(...)` | Suy luận văn bản (LLM) |
| `api.registerAgentHarness(...)` | Bộ thực thi agent cấp thấp thử nghiệm |
| `api.registerCliBackend(...)` | Backend suy luận CLI cục bộ |
| `api.registerChannel(...)` | Kênh nhắn tin |
| `api.registerSpeechProvider(...)` | Tổng hợp chuyển văn bản thành giọng nói / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Phiên âm thời gian thực dạng streaming |
| `api.registerRealtimeVoiceProvider(...)` | Phiên giọng nói thời gian thực hai chiều |
| `api.registerMediaUnderstandingProvider(...)` | Phân tích hình ảnh/âm thanh/video |
| `api.registerImageGenerationProvider(...)` | Tạo hình ảnh |
| `api.registerMusicGenerationProvider(...)` | Tạo nhạc |
| `api.registerVideoGenerationProvider(...)` | Tạo video |
| `api.registerWebFetchProvider(...)` | Nhà cung cấp fetch / scrape web |
| `api.registerWebSearchProvider(...)` | Tìm kiếm web |
| Phương thức | Nội dung đăng ký |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Suy luận văn bản (LLM) |
| `api.registerAgentHarness(...)` | Bộ thực thi agent cấp thấp thử nghiệm |
| `api.registerCliBackend(...)` | Backend suy luận CLI cục bộ |
| `api.registerChannel(...)` | Kênh nhắn tin |
| `api.registerSpeechProvider(...)` | Chuyển văn bản thành giọng nói / tổng hợp STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Phiên âm thời gian thực dạng streaming |
| `api.registerRealtimeVoiceProvider(...)` | Phiên thoại thời gian thực song công |
| `api.registerMediaUnderstandingProvider(...)` | Phân tích hình ảnh/âm thanh/video |
| `api.registerImageGenerationProvider(...)` | Tạo hình ảnh |
| `api.registerMusicGenerationProvider(...)` | Tạo nhạc |
| `api.registerVideoGenerationProvider(...)` | Tạo video |
| `api.registerWebFetchProvider(...)` | Nhà cung cấp tìm nạp / scrape web |
| `api.registerWebSearchProvider(...)` | Tìm kiếm web |
### Công cụ và lệnh
| Phương thức | Nội dung đăng ký |
| ------------------------------- | --------------------------------------------- |
| Phương thức | Nội dung đăng ký |
| ------------------------------- | ------------------------------------------------- |
| `api.registerTool(tool, opts?)` | Công cụ agent (bắt buộc hoặc `{ optional: true }`) |
| `api.registerCommand(def)` | Lệnh tùy chỉnh (bỏ qua LLM) |
| `api.registerCommand(def)` | Lệnh tùy chỉnh (bỏ qua LLM) |
Lệnh Plugin có thể đặt `agentPromptGuidance` khi agent cần một gợi ý định tuyến ngắn
do lệnh sở hữu. Giữ phần văn bản đó nói về chính lệnh; không thêm
chính sách dành riêng cho nhà cung cấp hoặc Plugin vào các bộ dựng prompt lõi.
chính sách dành riêng cho nhà cung cấp hoặc Plugin vào các trình dựng prompt lõi.
### Hạ tầng
@ -124,80 +125,76 @@ chính sách dành riêng cho nhà cung cấp hoặc Plugin vào các bộ dựn
| `api.registerCli(registrar, opts?)` | Lệnh con CLI |
| `api.registerService(service)` | Dịch vụ nền |
| `api.registerInteractiveHandler(registration)` | Handler tương tác |
| `api.registerAgentToolResultMiddleware(...)` | Middleware kết quả công cụ runtime |
| `api.registerMemoryPromptSupplement(builder)` | Phần prompt bổ sung gần bộ nhớ |
| `api.registerMemoryCorpusSupplement(adapter)` | Kho ngữ liệu tìm kiếm/đọc bộ nhớ bổ sung |
| `api.registerAgentToolResultMiddleware(...)` | Middleware kết quả công cụ ở runtime |
| `api.registerMemoryPromptSupplement(builder)` | Phần prompt bổ sung liền kề bộ nhớ |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus tìm kiếm/đọc bộ nhớ bổ sung |
### Host hook cho Plugin quy trình làm việc
### Hook host cho Plugin workflow
Host hook là các seam SDK cho Plugin cần tham gia vào vòng đời host
thay vì chỉ thêm nhà cung cấp, kênh hoặc công cụ. Chúng là
các hợp đồng chung; Plan Mode có thể dùng chúng, nhưng quy trình phê duyệt,
cổng chính sách workspace, trình giám sát nền, trình hướng dẫn thiết lập và Plugin đồng hành UI
Hook host là các seam SDK cho Plugin cần tham gia vào vòng đời host
thay vì chỉ thêm nhà cung cấp, kênh hoặc công cụ. Chúng là các
hợp đồng chung; Plan Mode có thể dùng chúng, nhưng workflow phê duyệt,
cổng chính sách workspace, bộ giám sát nền, trình hướng dẫn thiết lập và Plugin đồng hành UI
cũng có thể dùng.
| Phương thức | Hợp đồng mà nó sở hữu |
| Phương thức | Hợp đồng mà nó sở hữu |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerSessionExtension(...)` | Trạng thái phiên do Plugin sở hữu, tương thích JSON, được chiếu qua các phiên Gateway |
| `api.enqueueNextTurnInjection(...)` | Ngữ cảnh bền vững đúng một lần được tiêm vào lượt agent tiếp theo cho một phiên |
| `api.registerTrustedToolPolicy(...)` | Chính sách công cụ trước Plugin đi kèm/đáng tin cậy có thể chặn hoặc viết lại tham số công cụ |
| `api.registerToolMetadata(...)` | Metadata hiển thị danh mục công cụ mà không thay đổi phần triển khai công cụ |
| `api.registerToolMetadata(...)` | Siêu dữ liệu hiển thị danh mục công cụ mà không thay đổi phần triển khai công cụ |
| `api.registerCommand(...)` | Lệnh Plugin có phạm vi; kết quả lệnh có thể đặt `continueAgent: true`; lệnh gốc Discord hỗ trợ `descriptionLocalizations` |
| `api.registerControlUiDescriptor(...)` | Descriptor đóng góp Control UI cho các bề mặt phiên, công cụ, lần chạy hoặc cài đặt |
| `api.registerRuntimeLifecycle(...)` | Callback dọn dẹp cho tài nguyên runtime do Plugin sở hữu trên các đường dẫn reset/xóa/tải lại |
| `api.registerAgentEventSubscription(...)` | Đăng ký sự kiện đã được làm sạch cho trạng thái quy trình làm việc và trình giám sát |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Trạng thái nháp của Plugin theo từng lần chạy, được xóa ở vòng đời lần chạy kết thúc |
| `api.registerSessionSchedulerJob(...)` | Bản ghi tác vụ lập lịch phiên do Plugin sở hữu với dọn dẹp xác định |
| `api.registerControlUiDescriptor(...)` | Descriptor đóng góp Control UI cho các bề mặt phiên, công cụ, lần chạy hoặc cài đặt |
| `api.registerRuntimeLifecycle(...)` | Callback dọn dẹp cho tài nguyên runtime do Plugin sở hữu trên các đường dẫn đặt lại/xóa/tải lại |
| `api.registerAgentEventSubscription(...)` | Đăng ký sự kiện đã được làm sạch cho trạng thái workflow và bộ giám sát |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Trạng thái nháp Plugin theo từng lần chạy được xóa ở vòng đời lần chạy kết thúc |
| `api.registerSessionSchedulerJob(...)` | Bản ghi tác vụ bộ lập lịch phiên do Plugin sở hữu với dọn dẹp xác định |
Các hợp đồng cố ý tách quyền hạn:
Các hợp đồng cố ý tách riêng quyền hạn:
- Plugin bên ngoài có thể sở hữu phần mở rộng phiên, descriptor UI, lệnh, metadata công cụ,
lần tiêm lượt tiếp theo và hook thông thường.
- Plugin bên ngoài có thể sở hữu phần mở rộng phiên, descriptor UI, lệnh, siêu dữ liệu công cụ,
tiêm lượt kế tiếp và hook thông thường.
- Chính sách công cụ đáng tin cậy chạy trước các hook `before_tool_call` thông thường và chỉ dành cho
Plugin đi kèm vì chúng tham gia vào chính sách an toàn của host.
- Quyền sở hữu lệnh dành riêng chỉ dành cho Plugin đi kèm. Plugin bên ngoài nên dùng
tên lệnh hoặc alias của riêng chúng.
- `allowPromptInjection=false` vô hiệu hóa các hook làm thay đổi prompt, bao gồm
tên lệnh hoặc bí danh của riêng mình.
- `allowPromptInjection=false` vô hiệu hóa các hook thay đổi prompt bao gồm
`agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`,
các trường prompt từ `before_agent_start` cũ, và
`enqueueNextTurnInjection`.
Ví dụ về người dùng không thuộc Plan:
| Mẫu hình Plugin | Hook được dùng |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Quy trình phê duyệt | Phần mở rộng phiên, tiếp tục lệnh, tiêm lượt tiếp theo, descriptor UI |
| Cổng chính sách ngân sách/workspace | Chính sách công cụ đáng tin cậy, metadata công cụ, chiếu phiên |
| Trình giám sát vòng đời nền | Dọn dẹp vòng đời runtime, đăng ký sự kiện agent, quyền sở hữu/dọn dẹp bộ lập lịch phiên, đóng góp prompt heartbeat, descriptor UI |
| Trình hướng dẫn thiết lập hoặc onboarding | Phần mở rộng phiên, lệnh có phạm vi, descriptor Control UI |
| Kiểu Plugin mẫu | Hook được dùng |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Workflow phê duyệt | Phần mở rộng phiên, tiếp tục lệnh, tiêm lượt kế tiếp, descriptor UI |
| Cổng chính sách ngân sách/workspace | Chính sách công cụ đáng tin cậy, siêu dữ liệu công cụ, chiếu phiên |
| Bộ giám sát vòng đời nền | Dọn dẹp vòng đời runtime, đăng ký sự kiện agent, sở hữu/dọn dẹp bộ lập lịch phiên, đóng góp prompt heartbeat, descriptor UI |
| Trình hướng dẫn thiết lập hoặc onboarding | Phần mở rộng phiên, lệnh có phạm vi, descriptor Control UI |
<Note>
Các namespace quản trị lõi được dành riêng (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) luôn giữ `operator.admin`, ngay cả khi Plugin cố gắng gán một
phạm vi phương thức gateway hẹp hơn. Ưu tiên tiền tố dành riêng cho Plugin đối với
Các namespace quản trị lõi dành riêng (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) luôn giữ `operator.admin`, ngay cả khi một Plugin cố gán một
phạm vi phương thức gateway hẹp hơn. Hãy ưu tiên tiền tố dành riêng cho Plugin đối với
các phương thức do Plugin sở hữu.
</Note>
<Accordion title="Khi nào dùng middleware kết quả công cụ">
Plugin đi kèm có thể dùng `api.registerAgentToolResultMiddleware(...)` khi
chúng cần viết lại kết quả công cụ sau khi thực thi và trước khi runtime
đưa kết quả đó trở lại mô hình. Đây là seam trung lập runtime đáng tin cậy
đưa kết quả đó trở lại mô hình. Đây là seam đáng tin cậy, trung lập runtime
cho các bộ giảm đầu ra bất đồng bộ như tokenjuice.
Plugin đi kèm phải khai báo `contracts.agentToolResultMiddleware` cho từng
runtime mục tiêu, ví dụ `["pi", "codex"]`. Plugin bên ngoài
không thể đăng ký middleware này; giữ các hook Plugin OpenClaw thông thường cho công việc
không cần thời điểm kết quả công cụ trước mô hình. Đường dẫn đăng ký factory phần mở rộng nhúng
chỉ dành cho Pi cũ đã bị loại bỏ.
runtime được nhắm mục tiêu, ví dụ `["pi", "codex"]`. Plugin bên ngoài
không thể đăng ký middleware này; hãy giữ các hook Plugin OpenClaw thông thường cho công việc
không cần thời điểm kết quả công cụ trước mô hình. Đường dẫn đăng ký factory tiện ích mở rộng nhúng
cũ chỉ dành cho Pi đã bị xóa.
</Accordion>
### Đăng ký khám phá Gateway
`api.registerGatewayDiscoveryService(...)` cho phép plugin quảng bá Gateway đang hoạt động
trên một phương tiện khám phá cục bộ như mDNS/Bonjour. OpenClaw gọi
dịch vụ trong lúc khởi động Gateway khi khám phá cục bộ được bật, truyền các
cổng Gateway hiện tại và dữ liệu gợi ý TXT không bí mật, rồi gọi trình xử lý
`stop` được trả về trong lúc tắt Gateway.
`api.registerGatewayDiscoveryService(...)` cho phép một Plugin quảng bá Gateway đang hoạt động trên một cơ chế truyền tải khám phá cục bộ như mDNS/Bonjour. OpenClaw gọi dịch vụ này trong quá trình khởi động Gateway khi khám phá cục bộ được bật, truyền các cổng Gateway hiện tại và dữ liệu gợi ý TXT không bí mật, rồi gọi trình xử lý `stop` được trả về trong quá trình tắt Gateway.
```typescript
api.registerGatewayDiscoveryService({
@ -213,21 +210,17 @@ api.registerGatewayDiscoveryService({
});
```
Các plugin khám phá Gateway không được xem các giá trị TXT được quảng bá là bí mật hoặc
xác thực. Khám phá là gợi ý định tuyến; xác thực Gateway và ghim TLS vẫn
chịu trách nhiệm về niềm tin.
Các Plugin khám phá Gateway không được xem các giá trị TXT được quảng bá là bí mật hoặc cơ chế xác thực. Khám phá chỉ là gợi ý định tuyến; xác thực Gateway và ghim TLS vẫn chịu trách nhiệm về độ tin cậy.
### Siêu dữ liệu đăng ký CLI
`api.registerCli(registrar, opts?)` chấp nhận hai loại siêu dữ liệu cấp cao nhất:
- `commands`: các gốc lệnh tường minh do registrar sở hữu
- `descriptors`: các bộ mô tả lệnh tại thời điểm phân tích cú pháp dùng cho trợ giúp CLI gốc,
định tuyến, và đăng ký CLI plugin lazy
- `commands`: các gốc lệnh rõ ràng do registrar sở hữu
- `descriptors`: các bộ mô tả lệnh tại thời điểm phân tích cú pháp, dùng cho trợ giúp CLI gốc,
định tuyến và đăng ký CLI Plugin theo kiểu tải lười
Nếu bạn muốn một lệnh plugin tiếp tục được tải lazy trong đường dẫn CLI gốc thông thường,
hãy cung cấp `descriptors` bao phủ mọi gốc lệnh cấp cao nhất mà registrar đó
công bố.
Nếu bạn muốn một lệnh Plugin tiếp tục được tải lười trong đường dẫn CLI gốc thông thường, hãy cung cấp `descriptors` bao phủ mọi gốc lệnh cấp cao nhất mà registrar đó hiển thị.
```typescript
api.registerCli(
@ -247,50 +240,48 @@ api.registerCli(
);
```
Chỉ dùng riêng `commands` khi bạn không cần đăng ký CLI gốc lazy.
Đường dẫn tương thích eager đó vẫn được hỗ trợ, nhưng nó không cài đặt
các placeholder dựa trên descriptor để tải lazy tại thời điểm phân tích cú pháp.
Chỉ dùng riêng `commands` khi bạn không cần đăng ký CLI gốc theo kiểu tải lười. Đường dẫn tương thích tải sớm đó vẫn được hỗ trợ, nhưng nó không cài đặt các placeholder dựa trên bộ mô tả để tải lười tại thời điểm phân tích cú pháp.
### Đăng ký backend CLI
`api.registerCliBackend(...)` cho phép plugin sở hữu cấu hình mặc định cho một
backend CLI AI cục bộ như `codex-cli`.
`api.registerCliBackend(...)` cho phép một Plugin sở hữu cấu hình mặc định cho một backend CLI AI cục bộ như `codex-cli`.
- `id` của backend trở thành tiền tố provider trong tham chiếu model như `codex-cli/gpt-5`.
- `id` của backend trở thành tiền tố provider trong các tham chiếu model như `codex-cli/gpt-5`.
- `config` của backend dùng cùng hình dạng với `agents.defaults.cliBackends.<id>`.
- Cấu hình người dùng vẫn thắng. OpenClaw hợp nhất `agents.defaults.cliBackends.<id>` lên trên
mặc định của plugin trước khi chạy CLI.
- Dùng `normalizeConfig` khi backend cần viết lại tương thích sau khi hợp nhất
(ví dụ chuẩn hóa các dạng flag cũ).
- Cấu hình của người dùng vẫn được ưu tiên. OpenClaw hợp nhất `agents.defaults.cliBackends.<id>` lên trên mặc định của Plugin trước khi chạy CLI.
- Dùng `normalizeConfig` khi backend cần các phép viết lại tương thích sau khi hợp nhất
(ví dụ: chuẩn hóa các hình dạng flag cũ).
- Dùng `resolveExecutionArgs` cho các phép viết lại argv theo phạm vi yêu cầu thuộc về
phương ngữ CLI, chẳng hạn ánh xạ các mức thinking của OpenClaw sang một flag effort gốc.
### Slot độc quyền
| Phương thức | Nội dung được đăng ký |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Công cụ ngữ cảnh (mỗi lần chỉ một công cụ hoạt động). Callback `assemble()` nhận `availableTools` và `citationsMode` để công cụ có thể điều chỉnh phần bổ sung prompt. |
| `api.registerMemoryCapability(capability)` | Khả năng bộ nhớ thống nhất |
| `api.registerMemoryPromptSection(builder)` | Bộ dựng phần prompt bộ nhớ |
| `api.registerMemoryFlushPlan(resolver)` | Bộ phân giải kế hoạch flush bộ nhớ |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime bộ nhớ |
| Phương thức | Nội dung đăng ký |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context engine (mỗi lần chỉ một cái hoạt động). Callback `assemble()` nhận `availableTools` và `citationsMode` để engine có thể điều chỉnh phần thêm vào prompt. |
| `api.registerMemoryCapability(capability)` | Capability bộ nhớ hợp nhất |
| `api.registerMemoryPromptSection(builder)` | Bộ dựng phần prompt bộ nhớ |
| `api.registerMemoryFlushPlan(resolver)` | Bộ phân giải kế hoạch flush bộ nhớ |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime bộ nhớ |
### Adapter embedding bộ nhớ
| Phương thức | Nội dung được đăng ký |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding bộ nhớ cho plugin đang hoạt động |
| Phương thức | Nội dung đăng ký |
| --------------------------------------------- | -------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding bộ nhớ cho Plugin đang hoạt động |
- `registerMemoryCapability` là API plugin bộ nhớ độc quyền được ưu tiên.
- `registerMemoryCapability` cũng có thể công bố `publicArtifacts.listArtifacts(...)`
để các plugin đồng hành có thể dùng các artifact bộ nhớ đã xuất thông qua
- `registerMemoryCapability` là API Plugin bộ nhớ độc quyền được ưu tiên.
- `registerMemoryCapability` cũng có thể hiển thị `publicArtifacts.listArtifacts(...)`
để các Plugin đồng hành có thể dùng các artifact bộ nhớ đã xuất thông qua
`openclaw/plugin-sdk/memory-host-core` thay vì truy cập vào bố cục riêng của một
plugin bộ nhớ cụ thể.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, và
`registerMemoryRuntime` là các API plugin bộ nhớ độc quyền tương thích với legacy.
- `MemoryFlushPlan.model` có thể ghim lượt flush vào đúng tham chiếu `provider/model`
như `ollama/qwen3:8b`, mà không kế thừa chuỗi fallback đang hoạt động.
- `registerMemoryEmbeddingProvider` cho phép plugin bộ nhớ đang hoạt động đăng ký một
Plugin bộ nhớ cụ thể.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` và
`registerMemoryRuntime` là các API Plugin bộ nhớ độc quyền tương thích với legacy.
- `MemoryFlushPlan.model` có thể ghim lượt flush vào một tham chiếu `provider/model`
chính xác, chẳng hạn `ollama/qwen3:8b`, mà không kế thừa chuỗi fallback đang hoạt động.
- `registerMemoryEmbeddingProvider` cho phép Plugin bộ nhớ đang hoạt động đăng ký một
hoặc nhiều id adapter embedding (ví dụ `openai`, `gemini`, hoặc một id tùy chỉnh
do plugin định nghĩa).
do Plugin định nghĩa).
- Cấu hình người dùng như `agents.defaults.memorySearch.provider` và
`agents.defaults.memorySearch.fallback` được phân giải dựa trên các id adapter
đã đăng ký đó.
@ -298,46 +289,46 @@ backend CLI AI cục bộ như `codex-cli`.
### Sự kiện và vòng đời
| Phương thức | Chức năng |
| -------------------------------------------- | ----------------------------- |
| ------------------------------------------- | ------------------------------ |
| `api.on(hookName, handler, opts?)` | Hook vòng đời có kiểu |
| `api.onConversationBindingResolved(handler)` | Callback liên kết hội thoại |
| `api.onConversationBindingResolved(handler)` | Callback ràng buộc hội thoại |
Xem [Hook Plugin](/vi/plugins/hooks) để biết ví dụ, tên hook phổ biến, và ngữ nghĩa guard.
Xem [hook Plugin](/vi/plugins/hooks) để biết ví dụ, tên hook phổ biến và ngữ nghĩa guard.
### Ngữ nghĩa quyết định hook
### Ngữ nghĩa quyết định của hook
- `before_tool_call`: trả về `{ block: true }` là kết thúc. Khi bất kỳ handler nào đặt giá trị này, các handler có độ ưu tiên thấp hơn sẽ bị bỏ qua.
- `before_tool_call`: trả về `{ block: true }` là kết thúc. Khi bất kỳ handler nào đặt nó, các handler có mức ưu tiên thấp hơn sẽ bị bỏ qua.
- `before_tool_call`: trả về `{ block: false }` được xem là không có quyết định (giống như bỏ qua `block`), không phải là ghi đè.
- `before_install`: trả về `{ block: true }` là kết thúc. Khi bất kỳ handler nào đặt giá trị này, các handler có độ ưu tiên thấp hơn sẽ bị bỏ qua.
- `before_install`: trả về `{ block: true }` là kết thúc. Khi bất kỳ handler nào đặt nó, các handler có mức ưu tiên thấp hơn sẽ bị bỏ qua.
- `before_install`: trả về `{ block: false }` được xem là không có quyết định (giống như bỏ qua `block`), không phải là ghi đè.
- `reply_dispatch`: trả về `{ handled: true, ... }` là kết thúc. Khi bất kỳ handler nào nhận xử lý dispatch, các handler có độ ưu tiên thấp hơn và đường dẫn dispatch model mặc định sẽ bị bỏ qua.
- `message_sending`: trả về `{ cancel: true }` là kết thúc. Khi bất kỳ handler nào đặt giá trị này, các handler có độ ưu tiên thấp hơn sẽ bị bỏ qua.
- `reply_dispatch`: trả về `{ handled: true, ... }` là kết thúc. Khi bất kỳ handler nào nhận xử lý dispatch, các handler có mức ưu tiên thấp hơn và đường dẫn dispatch model mặc định sẽ bị bỏ qua.
- `message_sending`: trả về `{ cancel: true }` là kết thúc. Khi bất kỳ handler nào đặt nó, các handler có mức ưu tiên thấp hơn sẽ bị bỏ qua.
- `message_sending`: trả về `{ cancel: false }` được xem là không có quyết định (giống như bỏ qua `cancel`), không phải là ghi đè.
- `message_received`: dùng trường có kiểu `threadId` khi bạn cần định tuyến thread/topic đến. Giữ `metadata` cho các phần bổ sung riêng theo kênh.
- `message_sending`: dùng các trường định tuyến có kiểu `replyToId` / `threadId` trước khi fallback sang `metadata` riêng theo kênh.
- `gateway_start`: dùng `ctx.config`, `ctx.workspaceDir`, và `ctx.getCron?.()` cho trạng thái khởi động do gateway sở hữu thay vì dựa vào các hook nội bộ `gateway:startup`.
- `cron_changed`: quan sát các thay đổi vòng đời cron do gateway sở hữu. Dùng `event.job?.state?.nextRunAtMs` và `ctx.getCron?.()` khi đồng bộ các bộ lập lịch đánh thức bên ngoài, và giữ OpenClaw làm nguồn sự thật cho việc kiểm tra đến hạn và thực thi.
- `message_sending`: dùng các trường định tuyến có kiểu `replyToId` / `threadId` trước khi fallback về `metadata` riêng theo kênh.
- `gateway_start`: dùng `ctx.config`, `ctx.workspaceDir` và `ctx.getCron?.()` cho trạng thái khởi động do gateway sở hữu thay vì dựa vào các hook nội bộ `gateway:startup`.
- `cron_changed`: quan sát các thay đổi vòng đời cron do gateway sở hữu. Dùng `event.job?.state?.nextRunAtMs` và `ctx.getCron?.()` khi đồng bộ các bộ lập lịch đánh thức bên ngoài, và giữ OpenClaw làm nguồn sự thật cho kiểm tra hạn chạy và thực thi.
### Trường đối tượng API
### Trường của đối tượng API
| Trường | Kiểu | Mô tả |
| Trường | Kiểu | Mô tả |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Id plugin |
| `api.id` | `string` | id Plugin |
| `api.name` | `string` | Tên hiển thị |
| `api.version` | `string?` | Phiên bản plugin (tùy chọn) |
| `api.description` | `string?` | Mô tả plugin (tùy chọn) |
| `api.source` | `string` | Đường dẫn nguồn plugin |
| `api.rootDir` | `string?` | Thư mục gốc plugin (tùy chọn) |
| `api.version` | `string?` | Phiên bản Plugin (tùy chọn) |
| `api.description` | `string?` | Mô tả Plugin (tùy chọn) |
| `api.source` | `string` | Đường dẫn nguồn Plugin |
| `api.rootDir` | `string?` | Thư mục gốc Plugin (tùy chọn) |
| `api.config` | `OpenClawConfig` | Snapshot cấu hình hiện tại (snapshot runtime trong bộ nhớ đang hoạt động khi có sẵn) |
| `api.pluginConfig` | `Record<string, unknown>` | Cấu hình riêng của plugin từ `plugins.entries.<id>.config` |
| `api.pluginConfig` | `Record<string, unknown>` | Cấu hình riêng của Plugin từ `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Trình trợ giúp runtime](/vi/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger theo phạm vi (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Chế độ tải hiện tại; `"setup-runtime"` là cửa sổ khởi động/thiết lập nhẹ trước full-entry |
| `api.resolvePath(input)` | `(string) => string` | Phân giải đường dẫn tương đối với gốc plugin |
| `api.registrationMode` | `PluginRegistrationMode` | Chế độ tải hiện tại; `"setup-runtime"` là cửa sổ khởi động/thiết lập nhẹ trước full-entry |
| `api.resolvePath(input)` | `(string) => string` | Phân giải đường dẫn tương đối với gốc Plugin |
## Quy ước module nội bộ
Trong plugin của bạn, dùng các tệp barrel cục bộ cho import nội bộ:
Trong Plugin của bạn, hãy dùng các tệp barrel cục bộ cho import nội bộ:
```
my-plugin/
@ -348,56 +339,55 @@ my-plugin/
```
<Warning>
Không bao giờ import chính plugin của bạn thông qua `openclaw/plugin-sdk/<your-plugin>`
từ mã production. Định tuyến import nội bộ qua `./api.ts` hoặc
Không bao giờ import chính Plugin của bạn thông qua `openclaw/plugin-sdk/<your-plugin>`
từ mã production. Định tuyến các import nội bộ qua `./api.ts` hoặc
`./runtime-api.ts`. Đường dẫn SDK chỉ là hợp đồng bên ngoài.
</Warning>
Các bề mặt công khai của plugin bundled được tải qua facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, và các tệp entry công khai tương tự) ưu tiên
snapshot cấu hình runtime đang hoạt động khi OpenClaw đã chạy. Nếu chưa có
snapshot runtime, chúng fallback về tệp cấu hình đã phân giải trên đĩa.
Các facade plugin bundled đã đóng gói nên được tải thông qua các trình tải facade plugin
của OpenClaw; import trực tiếp từ `dist/extensions/...` bỏ qua manifest
và các kiểm tra sidecar runtime mà bản cài đặt đóng gói dùng cho mã do plugin sở hữu.
Các bề mặt công khai của Plugin bundled được tải qua facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` và các tệp entry công khai tương tự) ưu tiên snapshot
cấu hình runtime đang hoạt động khi OpenClaw đã chạy. Nếu chưa có snapshot runtime,
chúng fallback về tệp cấu hình đã phân giải trên đĩa. Các facade Plugin bundled
đóng gói nên được tải thông qua các loader facade Plugin của OpenClaw; import trực tiếp
từ `dist/extensions/...` bỏ qua manifest và các kiểm tra sidecar runtime mà bản cài đặt
đóng gói dùng cho mã do Plugin sở hữu.
Plugin provider có thể công bố một barrel hợp đồng hẹp, cục bộ trong plugin khi một
trình trợ giúp cố ý là riêng cho provider và chưa thuộc về một subpath SDK chung.
Ví dụ bundled:
Các Plugin provider có thể hiển thị một barrel hợp đồng hẹp cục bộ của Plugin khi một
trình trợ giúp cố ý riêng cho provider và chưa thuộc về một subpath SDK chung. Ví dụ bundled:
- **Anthropic**: seam công khai `api.ts` / `contract-api.ts` cho các trình trợ giúp stream
beta-header Claude và `service_tier`.
- **Anthropic**: seam công khai `api.ts` / `contract-api.ts` cho Claude
beta-header và trình trợ giúp stream `service_tier`.
- **`@openclaw/openai-provider`**: `api.ts` xuất các bộ dựng provider,
trình trợ giúp model mặc định, và bộ dựng provider realtime.
trình trợ giúp default-model và bộ dựng provider realtime.
- **`@openclaw/openrouter-provider`**: `api.ts` xuất bộ dựng provider
cùng trình trợ giúp onboarding/cấu hình.
cùng các trình trợ giúp onboarding/cấu hình.
<Warning>
Mã production extension cũng nên tránh import `openclaw/plugin-sdk/<other-plugin>`.
Nếu một trình trợ giúp thực sự dùng chung, hãy đưa nó lên một subpath SDK trung lập
như `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, hoặc một
bề mặt khác hướng theo khả năng thay vì ghép chặt hai plugin với nhau.
Mã production của extension cũng nên tránh import `openclaw/plugin-sdk/<other-plugin>`.
Nếu một trình trợ giúp thật sự được chia sẻ, hãy nâng nó lên một subpath SDK trung lập
như `openclaw/plugin-sdk/speech`, `.../provider-model-shared` hoặc một bề mặt khác
theo hướng capability thay vì ghép nối hai Plugin với nhau.
</Warning>
## Liên quan
<CardGroup cols={2}>
<Card title="Điểm vào" icon="door-open" href="/vi/plugins/sdk-entrypoints">
Tùy chọn `definePluginEntry` và `defineChannelPluginEntry`.
Các tùy chọn `definePluginEntry` và `defineChannelPluginEntry`.
</Card>
<Card title="Trình trợ giúp runtime" icon="gears" href="/vi/plugins/sdk-runtime">
Tài liệu tham chiếu đầy đủ cho không gian tên `api.runtime`.
<Card title="Trình trợ giúp thời gian chạy" icon="gears" href="/vi/plugins/sdk-runtime">
Tài liệu tham chiếu đầy đủ cho namespace `api.runtime`.
</Card>
<Card title="Thiết lập và cấu hình" icon="sliders" href="/vi/plugins/sdk-setup">
Đóng gói, manifest và schema cấu hình.
Đóng gói, manifest và lược đồ cấu hình.
</Card>
<Card title="Kiểm thử" icon="vial" href="/vi/plugins/sdk-testing">
Tiện ích kiểm thử và quy tắc lint.
</Card>
<Card title="Di chuyển SDK" icon="arrows-turn-right" href="/vi/plugins/sdk-migration">
Di chuyển từ các giao diện đã bị ngừng khuyến nghị.
Di chuyển khỏi các bề mặt đã ngừng khuyến nghị.
</Card>
<Card title="Nội bộ Plugin" icon="diagram-project" href="/vi/plugins/architecture">
Kiến trúc chuyên sâu và mô hình khả năng.
Kiến trúc chuyên sâu và mô hình năng lực.
</Card>
</CardGroup>

104
docs/vi/providers/openrouter.md
View File

@ -1,27 +1,27 @@
---
read_when:
- Bạn muốn một khóa API duy nhất cho nhiều LLM
- Bạn muốn dùng 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 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-04T02:25:22Z"
generated_at: "2026-05-05T01:49:37Z"
model: gpt-5.5
provider: openai
source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244
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 đế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ở.
endpoint 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 base URL.
## Bắt đầu
<Steps>
<Step title="Lấy khóa API của bạn">
<Step title="Nhận 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 onboarding">
@ -56,19 +56,19 @@ OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu đ
<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 khả dụng, hãy xem [/concepts/model-providers](/vi/concepts/model-providers).
các nhà cung cấp và mô hình hiện có, 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 OpenRouter |
| `openrouter/auto` | Định tuyến tự động của 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ô 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ột 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ô hì
}
```
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.
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ệnh 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ô 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ột mô hình video OpenRouter trong `agents.defaults.videoGenerationModel`:
```json5
{
@ -104,18 +104,18 @@ OpenRouter cũng có thể hỗ trợ công cụ `video_generate` thông qua API
```
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.
`polling_url` được trả về, rồi tải xuống video hoàn tất từ
`unsigned_urls` của OpenRouter hoặc endpoint nội dung tác vụ được tài liệu hóa.
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
được gắn thẻ `reference_image` được gửi dưới dạng tham chiếu đầu vào của 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-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.
tạo video upstream hiện chấp nhận tham chiếu văn bản và hình ảnh.
## 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
OpenRouter cũng có thể được dùng làm nhà cung cấp TTS thông qua endpoint
`/audio/speech` tương thích với OpenAI.
```json5
@ -141,9 +141,9 @@ Nếu bỏ qua `messages.tts.providers.openrouter.apiKey`, TTS sẽ tái sử d
## 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 sử dụng Bearer token 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
Trên các yêu cầu OpenRouter thực (`https://openrouter.ai/api/v1`), OpenClaw cũng thêm
các header ghi nhận ứng dụng được OpenRouter tài liệu hóa:
| Header | Giá trị |
@ -153,15 +153,15 @@ các header ghi nhận ứng dụng được OpenRouter tài liệu hóa:
| `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 đế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.
Nếu bạn trỏ lại nhà cung cấp OpenRouter đến một proxy hoặc base URL khác, OpenClaw
**không** chèn các header dành riêng cho OpenRouter đó hoặc marker bộ nhớ đệm Anthropic.
</Warning>
## Cấu hình nâng cao
<AccordionGroup>
<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
Bộ nhớ đệm phản hồi của 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
@ -187,49 +187,51 @@ Nếu bạn trỏ lại nhà cung cấp OpenRouter đến một proxy hoặc URL
(`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.
Điều này tách biệt với bộ nhớ đệm prompt của nhà cung cấp và các marker
`cache_control` Anthropic của OpenRouter. Nó chỉ được áp dụng trên các route
`openrouter.ai` đã xác minh, không áp dụng cho base URL 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 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 title="Marker bộ nhớ đệm Anthropic">
Trên các route OpenRouter đã xác minh, tham chiếu mô hình Anthropic giữ các
marker `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.
</Accordion>
<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 title="Nạp trước suy luận Anthropic">
Trên các route 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 nạp trước trợ lý ở 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 suy luận phải kết thúc bằng một lượt
người dùng.
</Accordion>
<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 đó.
Trên các route không phải `auto` được hỗ trợ, OpenClaw ánh xạ mức thinking đã chọn sang
payload suy luận proxy OpenRouter. Gợi ý mô hình không được hỗ trợ và
`openrouter/auto` bỏ qua việ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 cấu hình đã cũ vì OpenRouter có thể
trả về văn bản câu trả lời cuối cùng trong các trường suy luận cho route đã ngừng dùng đó.
</Accordion>
<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 thinking/tool giữ đúng hình dạng
theo dõi bắt buộc của DeepSeek V4.
<Accordion title="Phát lại suy luận DeepSeek V4">
Trên các route OpenRouter đã xác minh, `openrouter/deepseek/deepseek-v4-flash` và
`openrouter/deepseek/deepseek-v4-pro` điền `reasoning_content` bị thiếu trên
các lượt trợ lý được phát lại để hội thoại thinking/công cụ giữ đúng dạng theo dõi bắt buộc của DeepSeek V4. OpenClaw gửi các giá trị
`reasoning_effort` được OpenRouter hỗ trợ cho các route này; `xhigh` là mức được công bố
cao nhất, và các ghi đè `max` đã cũ được ánh xạ sang `xhigh`.
</Accordion>
<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.
OpenRouter vẫn chạy qua đường dẫn tương thích OpenAI theo kiểu proxy, nên
đị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 suy luận OpenAI, và gợi ý bộ nhớ đệm prompt không được chuyển tiếp.
</Accordion>
<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 title="Route dùng Gemini phía sau">
Tham chiếu OpenRouter dùng Gemini phía sau vẫn nằm trên đường dẫn proxy-Gemini: OpenClaw giữ
quá trình làm sạch chữ ký suy nghĩ Gemini tại đó, 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">
@ -242,9 +244,9 @@ Nếu bạn trỏ lại nhà cung cấp OpenRouter đến 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 failover.
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.
Tham chiếu cấu hình đầy đủ cho agent, mô hình và nhà cung cấp.
</Card>
</CardGroup>

759
docs/vi/reference/RELEASING.md
View File

File diff suppressed because it is too large Load Diff

203
docs/vi/reference/full-release-validation.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Chạy hoặc chạy lại quy trình xác thực bản phát hành đầy đủ
- So sánh các hồ sơ xác thực bản phát hành ổn định và đầy đủ
- Gỡ lỗi các lỗi ở giai đoạn xác thực bản phát hành
summary: Các giai đoạn xác thực phát hành đầy đủ, workflow con, hồ sơ phát hành, định danh chạy lại và bằng chứng
title: Xác thực bản phát hành đầy đủ
- So sánh các hồ sơ kiểm chứng bản phát hành ổn định và đầy đủ
- Gỡ lỗi các lỗi trong giai đoạn xác thực bản phát hành
summary: Các giai đoạn Xác thực phát hành đầy đủ, quy trình làm việc con, hồ sơ phát hành, mã định danh chạy lại và bằng chứng
title: Xác thực đầy đủ bản phát hành
x-i18n:
generated_at: "2026-05-03T21:35:30Z"
generated_at: "2026-05-05T01:50:06Z"
model: gpt-5.5
provider: openai
source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7
source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` là ô kiểm chứng phát hành tổng quát. Đây là điểm vào thủ công duy nhất cho bằng chứng trước phát hành, nhưng phần lớn công việc diễn ra trong các workflow con để có thể chạy lại một box bị lỗi mà không phải khởi động lại toàn bộ bản phát hành.
`Full Release Validation` là workflow bao trùm cho phát hành. Đây là điểm vào thủ công duy nhất cho bằng chứng tiền phát hành, nhưng phần lớn công việc diễn ra trong các workflow con để một mục thất bại có thể được chạy lại mà không phải khởi động lại toàn bộ bản phát hành.
Chạy nó từ một workflow ref đáng tin cậy, thường là `main`, và truyền nhánh phát hành, tag, hoặc commit SHA đầy đủ làm `ref`:
Chạy nó từ một ref workflow đáng tin cậy, thường là `main`, và truyền nhánh phát hành, tag hoặc SHA commit đầy đủ làm `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -27,118 +27,153 @@ gh workflow run full-release-validation.yml \
-f release_profile=stable
```
Các workflow con dùng workflow ref đáng tin cậy cho harness và dùng đầu vào `ref` cho ứng viên đang được kiểm thử. Điều đó giúp logic kiểm chứng mới luôn sẵn có khi kiểm chứng một nhánh phát hành hoặc tag cũ hơn.
Các workflow con dùng ref workflow đáng tin cậy cho harness và `ref` đầu vào cho ứng viên đang được kiểm thử. Điều đó giúp logic xác thực mới vẫn khả dụng khi xác thực một nhánh phát hành hoặc tag cũ hơn.
Package Acceptance thường xây dựng tarball ứng viên từ `ref` đã phân giải, bao gồm các lần chạy full-SHA được dispatch bằng `pnpm ci:full-release`. Sau khi publish, truyền `package_acceptance_package_spec=openclaw@YYYY.M.D` (hoặc `openclaw@beta`/`openclaw@latest`) để chạy cùng ma trận package/update đối với package npm đã được phát hành thay thế.
Theo mặc định, `release_profile=stable` chạy các lane chặn phát hành và bỏ qua phần soak live/Docker toàn diện. Truyền `run_release_soak=true` để bao gồm các lane soak trong một lần chạy ổn định. `release_profile=full` luôn bật các lane soak để hồ sơ tư vấn rộng không âm thầm mất phạm vi bao phủ.
Package Acceptance thường xây dựng tarball ứng viên từ `ref` đã phân giải, bao gồm các lần chạy SHA đầy đủ được điều phối bằng `pnpm ci:full-release`. Sau khi publish, truyền `package_acceptance_package_spec=openclaw@YYYY.M.D` (hoặc `openclaw@beta`/`openclaw@latest`) để chạy cùng ma trận package/update với package npm đã được phát hành thay thế.
## Các giai đoạn cấp cao nhất
| Giai đoạn | Chi tiết |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Phân giải mục tiêu | **Job:** `Resolve target ref`<br />**Workflow con:** không có<br />**Chứng minh:** phân giải nhánh phát hành, tag, hoặc commit SHA đầy đủ và ghi lại các đầu vào đã chọn.<br />**Chạy lại:** chạy lại ô tổng quát nếu bước này lỗi. |
| Vitest và CI thông thường | **Job:** `Run normal full CI`<br />**Workflow con:** `CI`<br />**Chứng minh:** đồ thị CI đầy đủ thủ công trên target ref, bao gồm các lane Linux Node, shard Plugin đi kèm, hợp đồng kênh, khả năng tương thích Node 22, `check`, `check-additional`, build smoke, kiểm tra tài liệu, Python skills, Windows, macOS, Control UI i18n, và Android thông qua ô tổng quát.<br />**Chạy lại:** `rerun_group=ci`. |
| Plugin trước phát hành | **Job:** `Run plugin prerelease validation`<br />**Workflow con:** `Plugin Prerelease`<br />**Chứng minh:** các kiểm tra tĩnh Plugin chỉ dành cho phát hành, độ phủ Plugin agentic, toàn bộ shard batch Plugin, và các lane Docker trước phát hành Plugin.<br />**Chạy lại:** `rerun_group=plugin-prerelease`. |
| Kiểm tra phát hành | **Job:** `Run release/live/Docker/QA validation`<br />**Workflow con:** `OpenClaw Release Checks`<br />**Chứng minh:** install smoke, kiểm tra package đa OS, bộ live/E2E, các chunk đường dẫn phát hành Docker, Package Acceptance, tương đương QA Lab, Matrix live, và Telegram live.<br />**Chạy lại:** `rerun_group=release-checks` hoặc một handle release-checks hẹp hơn. |
| Artifact package | **Job:** `Prepare release package artifact`<br />**Workflow con:** không có<br />**Chứng minh:** tạo tarball cha `release-package-under-test` đủ sớm cho các kiểm tra hướng package không cần chờ `OpenClaw Release Checks`.<br />**Chạy lại:** chạy lại ô tổng quát hoặc cung cấp `npm_telegram_package_spec` cho `rerun_group=npm-telegram`. |
| Package Telegram | **Job:** `Run package Telegram E2E`<br />**Workflow con:** `NPM Telegram Beta E2E`<br />**Chứng minh:** bằng chứng package Telegram dựa trên artifact cha cho `rerun_group=all` với `release_profile=full`, hoặc bằng chứng Telegram package đã publish khi `npm_telegram_package_spec` được đặt.<br />**Chạy lại:** `rerun_group=npm-telegram` với `npm_telegram_package_spec`. |
| Bộ xác minh ô tổng quát | **Job:** `Verify full validation`<br />**Workflow con:** không có<br />**Chứng minh:** kiểm tra lại kết luận của các lần chạy workflow con đã ghi lại và thêm bảng job chậm nhất từ các workflow con.<br />**Chạy lại:** chỉ chạy lại job này sau khi chạy lại workflow con bị lỗi đến trạng thái xanh. |
| Giai đoạn | Chi tiết |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Phân giải mục tiêu | **Công việc:** `Resolve target ref`<br />**Workflow con:** không có<br />**Chứng minh:** phân giải nhánh phát hành, tag hoặc SHA commit đầy đủ và ghi lại các đầu vào đã chọn.<br />**Chạy lại:** chạy lại workflow bao trùm nếu bước này thất bại. |
| Vitest và CI thường | **Công việc:** `Run normal full CI`<br />**Workflow con:** `CI`<br />**Chứng minh:** đồ thị CI đầy đủ thủ công trên ref mục tiêu, bao gồm các lane Linux Node, shard Plugin được đóng gói, hợp đồng kênh, khả năng tương thích Node 22, `check`, `check-additional`, smoke build, kiểm tra tài liệu, Python skills, Windows, macOS, Control UI i18n và Android thông qua workflow bao trùm.<br />**Chạy lại:** `rerun_group=ci`. |
| Tiền phát hành Plugin | **Công việc:** `Run plugin prerelease validation`<br />**Workflow con:** `Plugin Prerelease`<br />**Chứng minh:** các kiểm tra tĩnh Plugin chỉ dành cho phát hành, phạm vi bao phủ Plugin agentic, các shard batch extension đầy đủ và các lane Docker tiền phát hành Plugin.<br />**Chạy lại:** `rerun_group=plugin-prerelease`. |
| Kiểm tra phát hành | **Công việc:** `Run release/live/Docker/QA validation`<br />**Workflow con:** `OpenClaw Release Checks`<br />**Chứng minh:** smoke cài đặt, kiểm tra package đa hệ điều hành, Package Acceptance, tương đồng QA Lab, live Matrix và live Telegram. Với `run_release_soak=true` hoặc `release_profile=full`, cũng chạy các bộ live/E2E toàn diện và các đoạn đường dẫn phát hành Docker.<br />**Chạy lại:** `rerun_group=release-checks` hoặc một handle release-checks hẹp hơn. |
| Hiện vật package | **Công việc:** `Prepare release package artifact`<br />**Workflow con:** không có<br />**Chứng minh:** tạo tarball cha `release-package-under-test` đủ sớm cho các kiểm tra hướng package không cần chờ `OpenClaw Release Checks`.<br />**Chạy lại:** chạy lại workflow bao trùm hoặc cung cấp `npm_telegram_package_spec` cho `rerun_group=npm-telegram`. |
| Package Telegram | **Công việc:** `Run package Telegram E2E`<br />**Workflow con:** `NPM Telegram Beta E2E`<br />**Chứng minh:** bằng chứng package Telegram dựa trên hiện vật cha cho `rerun_group=all` với `release_profile=full`, hoặc bằng chứng Telegram của package đã publish khi `npm_telegram_package_spec` được đặt.<br />**Chạy lại:** `rerun_group=npm-telegram` với `npm_telegram_package_spec`. |
| Bộ xác minh bao trùm | **Công việc:** `Verify full validation`<br />**Workflow con:** không có<br />**Chứng minh:** kiểm tra lại kết luận của các lần chạy con đã ghi lại và thêm bảng các job chậm nhất từ các workflow con.<br />**Chạy lại:** chỉ chạy lại job này sau khi chạy lại một workflow con thất bại đến khi xanh. |
Với `ref=main` và `rerun_group=all`, một ô tổng quát mới hơn sẽ thay thế ô cũ hơn. Khi parent bị hủy, monitor của nó hủy mọi workflow con mà nó đã dispatch. Các lần kiểm chứng nhánh phát hành và tag mặc định không hủy lẫn nhau.
Với `ref=main` và `rerun_group=all`, một workflow bao trùm mới hơn sẽ thay thế workflow cũ hơn. Khi parent bị hủy, trình giám sát của nó hủy mọi workflow con mà nó đã điều phối. Các lần chạy xác thực nhánh phát hành và tag mặc định không hủy lẫn nhau.
## Các giai đoạn kiểm tra phát hành
`OpenClaw Release Checks` là workflow con lớn nhất. Nó phân giải mục tiêu một lần và chuẩn bị artifact `release-package-under-test` dùng chung khi các giai đoạn hướng package hoặc Docker cần artifact đó.
`OpenClaw Release Checks` là workflow con lớn nhất. Nó phân giải mục tiêu một lần và chuẩn bị một hiện vật `release-package-under-test` dùng chung khi các giai đoạn hướng package hoặc Docker cần đến.
| Giai đoạn | Chi tiết |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mục tiêu phát hành | **Job:** `Resolve target ref`<br />**Workflow nền:** không có<br />**Kiểm thử:** ref đã chọn, SHA mong đợi tùy chọn, profile, nhóm chạy lại, và bộ lọc bộ live tập trung.<br />**Chạy lại:** `rerun_group=release-checks`. |
| Artifact package | **Job:** `Prepare release package artifact`<br />**Workflow nền:** không có<br />**Kiểm thử:** đóng gói hoặc phân giải một tarball ứng viên và upload `release-package-under-test` cho các kiểm tra hướng package downstream.<br />**Chạy lại:** nhóm package, đa OS, hoặc live/E2E bị ảnh hưởng. |
| Install smoke | **Job:** `Run install smoke`<br />**Workflow nền:** `Install Smoke`<br />**Kiểm thử:** đường dẫn cài đặt đầy đủ với việc tái sử dụng image smoke Dockerfile gốc, cài đặt package QR, smoke Docker root và Gateway, kiểm thử Docker installer, smoke Bun global install image-provider, và E2E cài đặt/gỡ cài đặt Plugin đi kèm nhanh.<br />**Chạy lại:** `rerun_group=install-smoke`. |
| Đa OS | **Job:** `cross_os_release_checks`<br />**Workflow nền:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Kiểm thử:** các lane cài mới và nâng cấp trên Linux, Windows, và macOS cho provider và mode đã chọn, dùng tarball ứng viên cộng với package baseline.<br />**Chạy lại:** `rerun_group=cross-os`. |
| Repo và live E2E | **Job:** `Run repo/live E2E validation`<br />**Workflow nền:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Kiểm thử:** E2E repository, cache live, streaming websocket OpenAI, các shard provider live native và Plugin, và các harness live model/backend/Gateway dựa trên Docker được chọn bởi `release_profile`.<br />**Chạy lại:** `rerun_group=live-e2e`, tùy chọn với `live_suite_filter`. |
| Đường dẫn phát hành Docker | **Job:** `Run Docker release-path validation`<br />**Workflow nền:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Kiểm thử:** các chunk Docker đường dẫn phát hành trên artifact package dùng chung.<br />**Chạy lại:** `rerun_group=live-e2e`. |
| Package Acceptance | **Job:** `Run package acceptance`<br />**Workflow nền:** `Package Acceptance`<br />**Kiểm thử:** fixture package Plugin offline, cập nhật Plugin, chấp nhận package Telegram mock-OpenAI, và kiểm tra survivor khi nâng cấp từ mọi bản phát hành npm stable tại hoặc sau `2026.4.23` trên cùng tarball.<br />**Chạy lại:** `rerun_group=package`. |
| Tương đương QA | **Job:** `Run QA Lab parity lane` và `Run QA Lab parity report`<br />**Workflow nền:** job trực tiếp<br />**Kiểm thử:** các pack tương đương agentic ứng viên và baseline, sau đó là báo cáo tương đương.<br />**Chạy lại:** `rerun_group=qa-parity` hoặc `rerun_group=qa`. |
| QA live Matrix | **Job:** `Run QA Lab live Matrix lane`<br />**Workflow nền:** job trực tiếp<br />**Kiểm thử:** profile QA Matrix live nhanh trong môi trường `qa-live-shared`.<br />**Chạy lại:** `rerun_group=qa-live` hoặc `rerun_group=qa`. |
| QA live Telegram | **Job:** `Run QA Lab live Telegram lane`<br />**Workflow nền:** job trực tiếp<br />**Kiểm thử:** QA Telegram live với các lease thông tin đăng nhập Convex CI.<br />**Chạy lại:** `rerun_group=qa-live` hoặc `rerun_group=qa`. |
| Bộ xác minh phát hành | **Job:** `Verify release checks`<br />**Workflow nền:** không có<br />**Kiểm thử:** các job release-check bắt buộc cho nhóm chạy lại đã chọn.<br />**Chạy lại:** chạy lại sau khi các job con tập trung đã pass. |
| Giai đoạn | Chi tiết |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Mục tiêu phát hành | **Công việc:** `Resolve target ref`<br />**Quy trình công việc nền:** không có<br />**Kiểm thử:** ref đã chọn, SHA kỳ vọng tùy chọn, hồ sơ, nhóm chạy lại, và bộ lọc bộ kiểm thử trực tiếp có trọng tâm.<br />**Chạy lại:** `rerun_group=release-checks`. |
| Tạo phẩm gói | **Công việc:** `Prepare release package artifact`<br />**Quy trình công việc nền:** không có<br />**Kiểm thử:** đóng gói hoặc phân giải một tarball ứng viên và tải lên `release-package-under-test` cho các kiểm tra hướng đến gói ở hạ nguồn.<br />**Chạy lại:** gói bị ảnh hưởng, nhóm đa hệ điều hành, hoặc nhóm trực tiếp/E2E. |
| Kiểm tra cài đặt | **Công việc:** `Run install smoke`<br />**Quy trình công việc nền:** `Install Smoke`<br />**Kiểm thử:** đường dẫn cài đặt đầy đủ với việc tái sử dụng ảnh smoke Dockerfile gốc, cài đặt gói QR, smoke Docker gốc và Gateway, kiểm thử Docker của trình cài đặt, smoke provider ảnh cài đặt toàn cục Bun, và E2E cài đặt/gỡ cài đặt Plugin đi kèm nhanh.<br />**Chạy lại:** `rerun_group=install-smoke`. |
| Đa hệ điều hành | **Công việc:** `cross_os_release_checks`<br />**Quy trình công việc nền:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Kiểm thử:** các luồng cài mới và nâng cấp trên Linux, Windows, và macOS cho provider và chế độ đã chọn, dùng tarball ứng viên cộng với gói baseline.<br />**Chạy lại:** `rerun_group=cross-os`. |
| Repo và E2E trực tiếp | **Công việc:** `Run repo/live E2E validation`<br />**Quy trình công việc nền:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Kiểm thử:** E2E kho mã, cache trực tiếp, phát trực tuyến websocket OpenAI, các shard provider và Plugin trực tiếp bản địa, cùng các harness model/backend/Gateway trực tiếp dựa trên Docker được chọn bởi `release_profile`.<br />**Chạy:** `run_release_soak=true`, `release_profile=full`, hoặc `rerun_group=live-e2e` có trọng tâm.<br />**Chạy lại:** `rerun_group=live-e2e`, tùy chọn với `live_suite_filter`. |
| Đường dẫn phát hành Docker | **Công việc:** `Run Docker release-path validation`<br />**Quy trình công việc nền:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Kiểm thử:** các phần Docker theo đường dẫn phát hành chạy với tạo phẩm gói dùng chung.<br />**Chạy:** `run_release_soak=true`, `release_profile=full`, hoặc `rerun_group=live-e2e` có trọng tâm.<br />**Chạy lại:** `rerun_group=live-e2e`. |
| Chấp nhận gói | **Công việc:** `Run package acceptance`<br />**Quy trình công việc nền:** `Package Acceptance`<br />**Kiểm thử:** fixture gói Plugin ngoại tuyến, cập nhật Plugin, chấp nhận gói Telegram mock-OpenAI, và kiểm tra sống sót sau nâng cấp đã phát hành với cùng tarball. Các kiểm tra phát hành chặn dùng baseline đã phát hành mới nhất theo mặc định; kiểm tra soak mở rộng sang mọi bản phát hành npm ổn định từ `2026.4.23` trở đi cộng với fixture vấn đề đã báo cáo.<br />**Chạy lại:** `rerun_group=package`. |
| Tương đồng QA | **Công việc:** `Run QA Lab parity lane` và `Run QA Lab parity report`<br />**Quy trình công việc nền:** các công việc trực tiếp<br />**Kiểm thử:** các gói tương đồng agentic của ứng viên và baseline, sau đó là báo cáo tương đồng.<br />**Chạy lại:** `rerun_group=qa-parity` hoặc `rerun_group=qa`. |
| Matrix trực tiếp QA | **Công việc:** `Run QA Lab live Matrix lane`<br />**Quy trình công việc nền:** công việc trực tiếp<br />**Kiểm thử:** hồ sơ QA Matrix trực tiếp nhanh trong môi trường `qa-live-shared`.<br />**Chạy lại:** `rerun_group=qa-live` hoặc `rerun_group=qa`. |
| Telegram trực tiếp QA | **Công việc:** `Run QA Lab live Telegram lane`<br />**Quy trình công việc nền:** công việc trực tiếp<br />**Kiểm thử:** QA Telegram trực tiếp với các lease thông tin xác thực Convex CI.<br />**Chạy lại:** `rerun_group=qa-live` hoặc `rerun_group=qa`. |
| Trình xác minh phát hành | **Công việc:** `Verify release checks`<br />**Quy trình công việc nền:** không có<br />**Kiểm thử:** các công việc kiểm tra phát hành bắt buộc cho nhóm chạy lại đã chọn.<br />**Chạy lại:** chạy lại sau khi các công việc con có trọng tâm đã đạt. |
## Các chunk đường dẫn phát hành Docker
## Các phần đường dẫn phát hành Docker
Giai đoạn đường dẫn phát hành Docker chạy các chunk này khi `live_suite_filter` trống:
Giai đoạn đường dẫn phát hành Docker chạy các phần này khi `live_suite_filter`
trống:
| Chunk | Độ phủ |
| Phần | Phạm vi bao phủ |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `core` | Các lane smoke đường dẫn phát hành Docker lõi. |
| `package-update-openai` | Hành vi cài đặt và cập nhật package OpenAI. |
| `package-update-anthropic` | Hành vi cài đặt và cập nhật package Anthropic. |
| `package-update-core` | Hành vi package và cập nhật không phụ thuộc provider. |
| `plugins-runtime-plugins` | Các lane runtime Plugin thực thi hành vi Plugin. |
| `plugins-runtime-services` | Các lane runtime Plugin dựa trên service; bao gồm OpenWebUI khi được yêu cầu. |
| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Các batch cài đặt/runtime Plugin được chia để kiểm chứng phát hành song song. |
| `core` | Các luồng smoke đường dẫn phát hành Docker lõi. |
| `package-update-openai` | Hành vi cài đặt và cập nhật gói OpenAI. |
| `package-update-anthropic` | Hành vi cài đặt và cập nhật gói Anthropic. |
| `package-update-core` | Hành vi gói và cập nhật trung lập với provider. |
| `plugins-runtime-plugins` | Các luồng runtime Plugin kiểm tra hành vi Plugin. |
| `plugins-runtime-services` | Các luồng runtime Plugin dựa trên dịch vụ; bao gồm OpenWebUI khi được yêu cầu. |
| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Các batch cài đặt/runtime Plugin được tách để xác thực phát hành song song. |
Sử dụng `docker_lanes=<lane[,lane]>` có mục tiêu trên quy trình live/E2E tái sử dụng được khi chỉ một luồng Docker thất bại. Artifact phát hành bao gồm các lệnh chạy lại theo từng luồng với các đầu vào tái sử dụng artifact gói và hình ảnh khi có sẵn.
Dùng `docker_lanes=<lane[,lane]>` có mục tiêu trên quy trình công việc trực tiếp/E2E tái sử dụng khi
chỉ một luồng Docker thất bại. Các tạo phẩm phát hành bao gồm lệnh chạy lại theo từng luồng
với đầu vào tạo phẩm gói và tái sử dụng ảnh khi có sẵn.
## Hồ sơ phát hành
`release_profile` chủ yếu kiểm soát phạm vi live/provider bên trong các kiểm tra phát hành. Nó không loại bỏ CI đầy đủ thông thường, Plugin Prerelease, install smoke, package acceptance, QA Lab, hoặc các phần Docker release-path. `full` cũng khiến lần chạy bao quát thực thi Telegram E2E cho gói dựa trên artifact gói phát hành cha khi `rerun_group=all`, để một ứng viên tiền xuất bản đầy đủ không âm thầm bỏ qua luồng gói Telegram đó.
`release_profile` chủ yếu điều khiển độ rộng trực tiếp/provider bên trong các kiểm tra phát hành.
Nó không loại bỏ CI đầy đủ thông thường, Plugin Prerelease, smoke cài đặt, chấp nhận gói,
hoặc QA Lab. Với `stable`, E2E repo/trực tiếp toàn diện và các phần đường dẫn phát hành
Docker là phạm vi soak và chạy khi `run_release_soak=true`.
`full` buộc bật phạm vi soak và cũng khiến lần chạy bao trùm chạy E2E Telegram gói
với tạo phẩm gói phát hành cha khi `rerun_group=all`, để một ứng viên đầy đủ
trước khi phát hành không âm thầm bỏ qua luồng gói Telegram đó.
| Hồ sơ | Mục đích sử dụng | Phạm vi live/provider được bao gồm |
| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Smoke phát hành quan trọng nhanh nhất. | Đường dẫn live OpenAI/core, mô hình live Docker cho OpenAI, lõi gateway native, hồ sơ gateway OpenAI native, plugin OpenAI native, và gateway live Docker OpenAI. |
| `stable` | Hồ sơ phê duyệt phát hành mặc định. | `minimum` cộng với smoke Anthropic, Google, MiniMax, backend, bộ kiểm thử live native, backend CLI live Docker, bind ACP Docker, bộ kiểm thử Codex Docker, và một shard smoke OpenCode Go. |
| `full` | Quét tư vấn rộng. | `stable` cộng với các provider tư vấn, shard live Plugin, và shard live media. |
| Hồ sơ | Mục đích sử dụng | Phạm vi trực tiếp/provider được bao gồm |
| -------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Smoke phát hành quan trọng nhanh nhất. | Đường dẫn trực tiếp OpenAI/lõi, model trực tiếp Docker cho OpenAI, lõi Gateway bản địa, hồ sơ Gateway OpenAI bản địa, Plugin OpenAI bản địa, và Gateway OpenAI trực tiếp Docker. |
| `stable` | Hồ sơ phê duyệt phát hành mặc định. | `minimum` cộng với smoke Anthropic, Google, MiniMax, backend, harness kiểm thử trực tiếp bản địa, backend CLI trực tiếp Docker, bind ACP Docker, harness Codex Docker, và một shard smoke OpenCode Go. |
| `full` | Quét tư vấn diện rộng. | `stable` cộng với các provider tư vấn, shard trực tiếp Plugin, và shard trực tiếp media. |
## Bổ sung chỉ có trong full
## Các bổ sung chỉ dành cho full
Các bộ kiểm thử này bị `stable` bỏ qua và được `full` bao gồm:
Các bộ này bị `stable` bỏ qua và được `full` bao gồm:
| Khu vực | Phạm vi chỉ có trong full |
| Khu vực | Phạm vi chỉ dành cho full |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Mô hình live Docker | OpenCode Go, OpenRouter, xAI, Z.ai, và Fireworks. |
| Gateway live Docker | Provider tư vấn được chia thành các shard DeepSeek/Fireworks, OpenCode Go/OpenRouter, và xAI/Z.ai. |
| Hồ sơ provider gateway native | Các shard Anthropic Opus đầy đủ và Sonnet/Haiku, Fireworks, DeepSeek, các shard mô hình OpenCode Go đầy đủ, OpenRouter, xAI, và Z.ai. |
| Shard live Plugin native | Plugins A-K, L-N, O-Z khác, Moonshot, và xAI. |
| Shard live media native | Nhóm âm thanh, nhạc Google, nhạc MiniMax, và video A-D. |
| Model trực tiếp Docker | OpenCode Go, OpenRouter, xAI, Z.ai, và Fireworks. |
| Gateway trực tiếp Docker | Các provider tư vấn được tách thành shard DeepSeek/Fireworks, OpenCode Go/OpenRouter, và xAI/Z.ai. |
| Hồ sơ provider Gateway bản địa | Các shard Anthropic Opus và Sonnet/Haiku đầy đủ, Fireworks, DeepSeek, shard model OpenCode Go đầy đủ, OpenRouter, xAI, và Z.ai. |
| Shard trực tiếp Plugin bản địa | Plugins A-K, L-N, O-Z khác, Moonshot, và xAI. |
| Shard trực tiếp media bản địa | Audio, Google music, MiniMax music, và các nhóm video A-D. |
`stable` bao gồm `native-live-src-gateway-profiles-anthropic-smoke` và `native-live-src-gateway-profiles-opencode-go-smoke`; `full` dùng các shard mô hình Anthropic và OpenCode Go rộng hơn thay thế. Các lần chạy lại tập trung vẫn có thể dùng các handle tổng hợp `native-live-src-gateway-profiles-anthropic` hoặc `native-live-src-gateway-profiles-opencode-go`.
`stable` bao gồm `native-live-src-gateway-profiles-anthropic-smoke` và
`native-live-src-gateway-profiles-opencode-go-smoke`; `full` dùng các shard
model Anthropic và OpenCode Go rộng hơn thay vào đó. Các lần chạy lại có trọng tâm vẫn có thể dùng
handle tổng hợp `native-live-src-gateway-profiles-anthropic` hoặc
`native-live-src-gateway-profiles-opencode-go`.
## Chạy lại tập trung
## Chạy lại có trọng tâm
Dùng `rerun_group` để tránh lặp lại các hộp phát hành không liên quan:
| Handle | Phạm vi |
| Bộ xử lý | Phạm vi |
| ------------------- | --------------------------------------------------------------------- |
| `all` | Tất cả các giai đoạn Full Release Validation. |
| `ci` | Chỉ child CI đầy đủ thủ công. |
| `plugin-prerelease` | Chỉ child Plugin Prerelease. |
| `release-checks` | Tất cả các giai đoạn OpenClaw Release Checks. |
| `install-smoke` | Install Smoke thông qua kiểm tra phát hành. |
| `cross-os` | Kiểm tra phát hành Cross-OS. |
| `live-e2e` | Xác thực E2E repo/live và Docker release-path. |
| `package` | Package Acceptance. |
| `qa` | QA parity cộng với các luồng QA live. |
| `qa-parity` | Chỉ các luồng QA parity và báo cáo. |
| `qa-live` | Chỉ QA live Matrix và Telegram. |
| `npm-telegram` | Telegram E2E cho gói đã xuất bản; yêu cầu `npm_telegram_package_spec`. |
| `all` | Tất cả các giai đoạn Xác thực phát hành đầy đủ. |
| `ci` | Chỉ CI đầy đủ thủ công dạng con. |
| `plugin-prerelease` | Chỉ quy trình con tiền phát hành Plugin. |
| `release-checks` | Tất cả các giai đoạn kiểm tra phát hành OpenClaw. |
| `install-smoke` | Kiểm thử khói cài đặt thông qua kiểm tra phát hành. |
| `cross-os` | Kiểm tra phát hành Cross-OS. |
| `live-e2e` | Xác thực E2E repo/live và đường dẫn phát hành Docker. |
| `package` | Chấp nhận gói. |
| `qa` | Tương đồng QA cộng với các lane QA trực tiếp. |
| `qa-parity` | Chỉ các lane tương đồng QA và báo cáo. |
| `qa-live` | Chỉ Matrix QA trực tiếp và Telegram. |
| `npm-telegram` | E2E Telegram cho gói đã phát hành; yêu cầu `npm_telegram_package_spec`. |
Dùng `live_suite_filter` với `rerun_group=live-e2e` khi một bộ kiểm thử live thất bại. Các id bộ lọc hợp lệ được định nghĩa trong quy trình live/E2E tái sử dụng được, bao gồm `docker-live-models`, `live-gateway-docker`, `live-gateway-anthropic-docker`, `live-gateway-google-docker`, `live-gateway-minimax-docker`, `live-gateway-advisory-docker`, `live-cli-backend-docker`, `live-acp-bind-docker`, và `live-codex-harness-docker`.
Dùng `live_suite_filter` với `rerun_group=live-e2e` khi một bộ kiểm thử trực tiếp thất bại.
Các id bộ lọc hợp lệ được định nghĩa trong workflow live/E2E có thể tái sử dụng, bao gồm
`docker-live-models`, `live-gateway-docker`,
`live-gateway-anthropic-docker`, `live-gateway-google-docker`,
`live-gateway-minimax-docker`, `live-gateway-advisory-docker`,
`live-cli-backend-docker`, `live-acp-bind-docker`, và
`live-codex-harness-docker`.
Handle `live-gateway-advisory-docker` là handle chạy lại tổng hợp cho ba shard provider của nó, nên nó vẫn tỏa ra tất cả các job gateway Docker tư vấn.
Bộ xử lý `live-gateway-advisory-docker` là bộ xử lý chạy lại tổng hợp cho
ba shard nhà cung cấp của nó, nên nó vẫn phân nhánh ra tất cả các job Gateway Docker advisory.
## Bằng chứng cần giữ lại
Dùng `cross_os_suite_filter` với `rerun_group=cross-os` khi một lane Cross-OS
thất bại. Bộ lọc chấp nhận một id hệ điều hành, một id bộ kiểm thử, hoặc một cặp hệ điều hành/bộ kiểm thử, ví dụ
`windows/packaged-upgrade`, `windows`, hoặc `packaged-fresh`. Các bản tóm tắt Cross-OS
bao gồm thời gian theo từng pha cho các lane nâng cấp dạng đóng gói, và các
lệnh chạy lâu in ra các dòng Heartbeat để một bản cập nhật Windows bị kẹt có thể được thấy trước khi
job hết thời gian chờ.
Giữ phần tóm tắt `Full Release Validation` làm chỉ mục cấp phát hành. Nó liên kết các id lần chạy child và bao gồm các bảng job chậm nhất. Đối với lỗi, trước tiên hãy kiểm tra quy trình child, sau đó chạy lại handle phù hợp nhỏ nhất ở trên.
Các lane kiểm tra phát hành QA mang tính advisory. Lỗi chỉ thuộc QA được báo cáo dưới dạng cảnh báo
và không chặn trình xác minh kiểm tra phát hành; chạy lại `rerun_group=qa`,
`qa-parity`, hoặc `qa-live` khi bạn cần bằng chứng QA mới.
## Bằng chứng cần giữ
Giữ bản tóm tắt `Full Release Validation` làm chỉ mục cấp phát hành. Nó liên kết
các id lượt chạy con và bao gồm bảng các job chậm nhất. Khi có lỗi, kiểm tra workflow con trước,
rồi chạy lại bộ xử lý phù hợp nhỏ nhất ở trên.
Artifact hữu ích:
- `release-package-under-test` từ parent Full Release Validation và `OpenClaw Release Checks`
- Artifact Docker release-path trong `.artifacts/docker-tests/`
- `package-under-test` của Package Acceptance và các artifact Docker acceptance
- Artifact kiểm tra phát hành Cross-OS cho từng OS và bộ kiểm thử
- Artifact QA parity, Matrix, và Telegram
- `release-package-under-test` từ cha Xác thực phát hành đầy đủ và `OpenClaw Release Checks`
- Artifact đường dẫn phát hành Docker trong `.artifacts/docker-tests/`
- `package-under-test` của Chấp nhận gói và artifact chấp nhận Docker
- Artifact kiểm tra phát hành Cross-OS cho từng hệ điều hành và bộ kiểm thử
- Artifact tương đồng QA, Matrix, và Telegram
## Tệp quy trình
## Tệp workflow
- `.github/workflows/full-release-validation.yml`
- `.github/workflows/openclaw-release-checks.yml`

108
docs/vi/reference/test.md
View File

@ -1,63 +1,63 @@
---
read_when:
- Chạy hoặc sửa các bài kiểm thử
summary: Cách chạy kiểm thử cục bộ (vitest) và khi nào nên dùng các chế độ ép buộc/bao phủ
- Chạy hoặc sửa lỗi kiểm thử
summary: Cách chạy kiểm thử cục bộ (vitest) và thời điểm sử dụng các chế độ force/coverage
title: Kiểm thử
x-i18n:
generated_at: "2026-05-02T20:57:17Z"
generated_at: "2026-05-05T01:50:03Z"
model: gpt-5.5
provider: openai
source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f
source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605
source_path: reference/test.md
workflow: 16
---
- Bộ công cụ kiểm thử đầy đủ (bộ kiểm thử, trực tiếp, Docker): [Kiểm thử](/vi/help/testing)
- Xác thực cập nhật và gói plugin: [Kiểm thử cập nhật và plugin](/vi/help/testing-updates-plugins)
- Bộ kiểm thử đầy đủ (bộ kiểm thử, trực tiếp, Docker): [Kiểm thử](/vi/help/testing)
- Xác thực bản cập nhật và gói Plugin: [Kiểm thử bản cập nhật và Plugin](/vi/help/testing-updates-plugins)
- `pnpm test:force`: Dừng mọi tiến trình Gateway còn sót lại đang giữ cổng điều khiển mặc định, rồi chạy toàn bộ bộ Vitest với một cổng Gateway cô lập để các kiểm thử máy chủ không xung đột với một phiên bản đang chạy. Dùng lệnh này khi một lần chạy Gateway trước đó đã để cổng 18789 bị chiếm.
- `pnpm test:coverage`: Chạy bộ kiểm thử đơn vị với độ bao phủ V8 (qua `vitest.unit.config.ts`). Đây là cổng kiểm tra độ bao phủ đơn vị theo tệp đã tải, không phải độ bao phủ toàn bộ tệp trên toàn repo. Ngưỡng là 70% dòng/hàm/câu lệnh và 55% nhánh. Vì `coverage.all` là false, cổng này đo các tệp được bộ độ bao phủ đơn vị tải thay vì xem mọi tệp nguồn trong các lane đã tách là chưa được bao phủ.
- `pnpm test:coverage:changed`: Chạy độ bao phủ đơn vị chỉ cho các tệp đã thay đổi kể từ `origin/main`.
- `pnpm test:changed`: lượt chạy kiểm thử thông minh giá rẻ cho thay đổi. Nó chạy các mục tiêu chính xác từ các chỉnh sửa kiểm thử trực tiếp, các tệp `*.test.ts` cùng cấp, ánh xạ nguồn tường minh và đồ thị import cục bộ. Các thay đổi rộng/cấu hình/gói bị bỏ qua trừ khi chúng ánh xạ tới các kiểm thử chính xác.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: lượt chạy kiểm thử thay đổi rộng tường minh. Dùng khi một chỉnh sửa harness kiểm thử/cấu hình/gói nên quay về hành vi kiểm thử thay đổi rộng hơn của Vitest.
- `pnpm changed:lanes`: hiển thị các lane kiến trúc được kích hoạt bởi diff so với `origin/main`.
- `pnpm check:changed`: chạy cổng kiểm tra thông minh cho diff so với `origin/main`. Nó chạy typecheck, lint và các lệnh guard cho những lane kiến trúc bị ảnh hưởng, nhưng không chạy kiểm thử Vitest. Dùng `pnpm test:changed` hoặc `pnpm test <target>` tường minh để có bằng chứng kiểm thử.
- `pnpm test`: định tuyến các mục tiêu tệp/thư mục tường minh qua các lane Vitest có phạm vi. Các lượt chạy không có mục tiêu dùng các nhóm shard cố định và mở rộng thành cấu hình lá để thực thi song song cục bộ; nhóm phần mở rộng luôn mở rộng thành các cấu hình shard theo từng phần mở rộng thay vì một tiến trình dự án gốc khổng lồ.
- Các lượt chạy wrapper kiểm thử kết thúc bằng một tóm tắt ngắn `[test] passed|failed|skipped ... in ...`. Dòng thời lượng riêng của Vitest vẫn là chi tiết theo từng shard.
- Trạng thái kiểm thử OpenClaw dùng chung: dùng `src/test-utils/openclaw-test-state.ts` từ Vitest khi một kiểm thử cần `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture cấu hình, workspace, thư mục agent hoặc kho auth-profile được cô lập.
- Trình trợ giúp E2E tiến trình: dùng `test/helpers/openclaw-test-instance.ts` khi một kiểm thử E2E cấp tiến trình Vitest cần một Gateway đang chạy, môi trường CLI, thu thập log và dọn dẹp ở cùng một chỗ.
- Trình trợ giúp E2E Docker/Bash: các lane source `scripts/lib/docker-e2e-image.sh` có thể truyền `docker_e2e_test_state_shell_b64 <label> <scenario>` vào container và giải mã bằng `scripts/lib/openclaw-e2e-instance.sh`; các script nhiều home có thể truyền `docker_e2e_test_state_function_b64` và gọi `openclaw_test_state_create <label> <scenario>` trong từng flow. Các caller cấp thấp hơn có thể dùng `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` cho một đoạn shell trong container, hoặc `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` cho một tệp env host có thể source. Dấu `--` trước `create` ngăn các runtime Node mới hơn xem `--env-file` là một cờ Node. Các lane Docker/Bash khởi chạy Gateway có thể source `scripts/lib/openclaw-e2e-instance.sh` bên trong container để phân giải entrypoint, khởi động OpenAI giả lập, khởi chạy Gateway foreground/background, probe sẵn sàng, xuất env trạng thái, dump log và dọn dẹp tiến trình.
- Các lượt chạy shard đầy đủ, phần mở rộng và include-pattern cập nhật dữ liệu thời gian cục bộ trong `.artifacts/vitest-shard-timings.json`; các lượt chạy toàn cấu hình sau đó dùng những thời gian này để cân bằng shard chậm và nhanh. Các shard CI include-pattern thêm tên shard vào khóa thời gian, giúp thời gian shard đã lọc vẫn hiển thị mà không thay thế dữ liệu thời gian toàn cấu hình. Đặt `OPENCLAW_TEST_PROJECTS_TIMINGS=0` để bỏ qua artifact thời gian cục bộ.
- Các tệp kiểm thử `plugin-sdk` và `commands` được chọn giờ định tuyến qua các lane nhẹ chuyên dụng chỉ giữ `test/setup.ts`, để các trường hợp nặng runtime ở lại các lane hiện có của chúng.
- `pnpm test:force`: Kết thúc mọi tiến trình Gateway còn sót lại đang giữ cổng điều khiển mặc định, rồi chạy toàn bộ bộ Vitest với một cổng Gateway biệt lập để các kiểm thử máy chủ không xung đột với một phiên bản đang chạy. Dùng lệnh này khi một lần chạy Gateway trước đó để lại cổng 18789 đang bị chiếm dụng.
- `pnpm test:coverage`: Chạy bộ kiểm thử đơn vị với độ bao phủ V8 (thông qua `vitest.unit.config.ts`). Đây là cổng kiểm tra độ bao phủ đơn vị cho các tệp đã được nạp, không phải độ bao phủ toàn bộ tệp trên toàn repo. Ngưỡng là 70% cho dòng/hàm/câu lệnh và 55% cho nhánh. Vì `coverage.all` là false, cổng này đo các tệp được bộ độ bao phủ đơn vị nạp thay vì xem mọi tệp nguồn thuộc làn tách riêng là chưa được bao phủ.
- `pnpm test:coverage:changed`: Chỉ chạy độ bao phủ đơn vị cho các tệp đã thay đổi kể từ `origin/main`.
- `pnpm test:changed`: lần chạy kiểm thử thay đổi thông minh giá rẻ. Nó chạy các mục tiêu chính xác từ các chỉnh sửa kiểm thử trực tiếp, các tệp `*.test.ts` cùng cấp, ánh xạ nguồn rõ ràng và đồ thị import cục bộ. Các thay đổi rộng về cấu hình/gói bị bỏ qua trừ khi chúng ánh xạ tới các kiểm thử chính xác.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: lần chạy kiểm thử thay đổi rộng rõ ràng. Dùng khi chỉnh sửa bộ khung/cấu hình/gói kiểm thử nên quay về hành vi kiểm thử thay đổi rộng hơn của Vitest.
- `pnpm changed:lanes`: hiển thị các làn kiến trúc được kích hoạt bởi diff so với `origin/main`.
- `pnpm check:changed`: chạy cổng kiểm tra thay đổi thông minh cho diff so với `origin/main`. Nó chạy typecheck, lint và các lệnh bảo vệ cho các làn kiến trúc bị ảnh hưởng, nhưng không chạy kiểm thử Vitest. Dùng `pnpm test:changed` hoặc `pnpm test <target>` rõ ràng để có bằng chứng kiểm thử.
- `pnpm test`: định tuyến các mục tiêu tệp/thư mục rõ ràng qua các làn Vitest có phạm vi. Các lần chạy không có mục tiêu dùng nhóm shard cố định và mở rộng thành các cấu hình lá để thực thi song song cục bộ; nhóm plugin luôn mở rộng thành các cấu hình shard theo từng plugin thay vì một tiến trình dự án gốc khổng lồ.
- Các lần chạy trình bọc kiểm thử kết thúc bằng một tóm tắt ngắn `[test] passed|failed|skipped ... in ...`. Dòng thời lượng riêng của Vitest vẫn là chi tiết theo từng shard.
- Trạng thái kiểm thử OpenClaw dùng chung: dùng `src/test-utils/openclaw-test-state.ts` từ Vitest khi một kiểm thử cần `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture cấu hình, workspace, thư mục agent hoặc kho auth-profile biệt lập.
- Helper E2E tiến trình: dùng `test/helpers/openclaw-test-instance.ts` khi một kiểm thử E2E cấp tiến trình Vitest cần Gateway đang chạy, env CLI, ghi log và dọn dẹp ở một nơi.
- Helper E2E Docker/Bash: các làn source `scripts/lib/docker-e2e-image.sh` có thể truyền `docker_e2e_test_state_shell_b64 <label> <scenario>` vào container và giải mã bằng `scripts/lib/openclaw-e2e-instance.sh`; các script nhiều home có thể truyền `docker_e2e_test_state_function_b64` và gọi `openclaw_test_state_create <label> <scenario>` trong từng luồng. Các bên gọi cấp thấp hơn có thể dùng `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` cho một đoạn shell trong container, hoặc `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` cho một tệp env máy chủ có thể source. Dấu `--` trước `create` ngăn các runtime Node mới hơn xem `--env-file` là cờ Node. Các làn Docker/Bash khởi chạy Gateway có thể source `scripts/lib/openclaw-e2e-instance.sh` bên trong container để phân giải entrypoint, khởi động OpenAI giả lập, khởi chạy Gateway foreground/background, probe độ sẵn sàng, export env trạng thái, dump log và dọn dẹp tiến trình.
- Các lần chạy shard đầy đủ, plugin và include-pattern cập nhật dữ liệu thời gian cục bộ trong `.artifacts/vitest-shard-timings.json`; các lần chạy toàn cấu hình sau đó dùng các thời gian đó để cân bằng shard chậm và nhanh. Các shard CI include-pattern thêm tên shard vào khóa thời gian, giúp thời gian shard đã lọc vẫn hiển thị mà không thay thế dữ liệu thời gian toàn cấu hình. Đặt `OPENCLAW_TEST_PROJECTS_TIMINGS=0` để bỏ qua artifact thời gian cục bộ.
- Các tệp kiểm thử `plugin-sdk` và `commands` được chọn giờ định tuyến qua các làn nhẹ chuyên dụng chỉ giữ `test/setup.ts`, để các trường hợp nặng runtime ở lại làn hiện có của chúng.
- Các tệp nguồn có kiểm thử cùng cấp ánh xạ tới kiểm thử cùng cấp đó trước khi quay về các glob thư mục rộng hơn. Các chỉnh sửa helper dưới `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` và `src/plugins/contracts` dùng đồ thị import cục bộ để chạy các kiểm thử đang import thay vì chạy rộng mọi shard khi đường dẫn phụ thuộc là chính xác.
- `auto-reply` giờ cũng tách thành ba cấu hình chuyên dụng (`core`, `top-level`, `reply`) để harness reply không lấn át các kiểm thử trạng thái/token/helper cấp cao nhẹ hơn.
- Cấu hình Vitest cơ sở giờ mặc định là `pool: "threads"` và `isolate: false`, với runner không cô lập dùng chung được bật trên toàn bộ cấu hình repo.
- `auto-reply` giờ cũng tách thành ba cấu hình chuyên dụng (`core`, `top-level`, `reply`) để bộ khung reply không lấn át các kiểm thử trạng thái/token/helper top-level nhẹ hơn.
- Cấu hình Vitest cơ sở giờ mặc định là `pool: "threads"` và `isolate: false`, với runner không biệt lập dùng chung được bật trên các cấu hình repo.
- `pnpm test:channels` chạy `vitest.channels.config.ts`.
- `pnpm test:extensions` và `pnpm test extensions` chạy tất cả shard phần mở rộng/Plugin. Các Plugin kênh nặng, Plugin trình duyệt và OpenAI chạy dưới dạng shard chuyên dụng; các nhóm Plugin khác vẫn được gom lô. Dùng `pnpm test extensions/<id>` cho một lane Plugin được đóng gói.
- `pnpm test:perf:imports`: bật báo cáo thời lượng import + phân tích import của Vitest, đồng thời vẫn dùng định tuyến lane có phạm vi cho các mục tiêu tệp/thư mục tường minh.
- `pnpm test:perf:imports:changed`: cùng profiling import, nhưng chỉ cho các tệp đã thay đổi kể từ `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmark đường dẫn chế độ changed đã định tuyến so với lượt chạy dự án gốc native cho cùng một diff git đã commit.
- `pnpm test:extensions` và `pnpm test extensions` chạy tất cả shard extension/plugin. Các plugin kênh nặng, plugin trình duyệt và OpenAI chạy dưới dạng shard chuyên dụng; các nhóm plugin khác vẫn được gom lô. Dùng `pnpm test extensions/<id>` cho một làn plugin đóng gói.
- `pnpm test:perf:imports`: bật báo cáo thời lượng import + phân rã import của Vitest, trong khi vẫn dùng định tuyến làn có phạm vi cho các mục tiêu tệp/thư mục rõ ràng.
- `pnpm test:perf:imports:changed`: cùng cơ chế profiling import, nhưng chỉ cho các tệp đã thay đổi kể từ `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmark đường dẫn chế độ thay đổi đã định tuyến so với lần chạy dự án gốc native cho cùng diff git đã commit.
- `pnpm test:perf:changed:bench -- --worktree` benchmark tập thay đổi worktree hiện tại mà không cần commit trước.
- `pnpm test:perf:profile:main`: ghi một CPU profile cho thread chính của Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:main`: ghi một CPU profile cho luồng chính Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: ghi CPU + heap profile cho runner đơn vị (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: chạy tuần tự mọi cấu hình lá Vitest của bộ đầy đủ và ghi dữ liệu thời lượng đã nhóm cùng artifact JSON/log theo từng cấu hình. Test Performance Agent dùng dữ liệu này làm baseline trước khi thử sửa kiểm thử chậm.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: so sánh các báo cáo đã nhóm sau một thay đổi tập trung vào hiệu năng.
- Tích hợp Gateway: bật tùy chọn qua `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` hoặc `pnpm test:gateway`.
- `pnpm test:e2e`: Chạy các kiểm thử smoke end-to-end Gateway (ghép cặp nhiều phiên bản WS/HTTP/node). Mặc định là `threads` + `isolate: false` với worker thích ứng trong `vitest.e2e.config.ts`; tinh chỉnh bằng `OPENCLAW_E2E_WORKERS=<n>` và đặt `OPENCLAW_E2E_VERBOSE=1` để có log chi tiết.
- `pnpm test:live`: Chạy kiểm thử live của provider (minimax/zai). Cần API key và `LIVE=1` (hoặc `*_LIVE_TEST=1` theo từng provider) để bỏ skip.
- `pnpm test:docker:all`: Build image live-test dùng chung, đóng gói OpenClaw một lần dưới dạng tarball npm, build/tái sử dụng image runner Node/Git trống cùng một image chức năng cài tarball đó vào `/app`, rồi chạy các lane smoke Docker với `OPENCLAW_SKIP_DOCKER_BUILD=1` qua scheduler có trọng số. Image trống (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) được dùng cho các lane installer/update/phụ thuộc Plugin; các lane đó mount tarball đã build sẵn thay vì dùng nguồn repo đã sao chép. Image chức năng (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) được dùng cho các lane chức năng ứng dụng đã build thông thường. `scripts/package-openclaw-for-docker.mjs` là trình đóng gói package cục bộ/CI duy nhất và xác thực tarball cùng `dist/postinstall-inventory.json` trước khi Docker sử dụng. Định nghĩa lane Docker nằm trong `scripts/lib/docker-e2e-scenarios.mjs`; logic planner nằm trong `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` thực thi plan đã chọn. `node scripts/test-docker-all.mjs --plan-json` phát ra plan CI do scheduler sở hữu cho các lane, loại image, nhu cầu package/live-image, kịch bản trạng thái và kiểm tra thông tin xác thực đã chọn mà không build hoặc chạy Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` kiểm soát slot tiến trình và mặc định là 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` kiểm soát pool tail nhạy với provider và mặc định là 10. Giới hạn lane nặng mặc định là `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` và `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; giới hạn provider mặc định là một lane nặng cho mỗi provider qua `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` và `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Dùng `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` hoặc `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` cho host lớn hơn. Nếu một lane vượt giới hạn trọng số hoặc tài nguyên hiệu dụng trên host có mức song song thấp, nó vẫn có thể bắt đầu từ một pool rỗng và sẽ chạy một mình cho đến khi giải phóng dung lượng. Các lane bắt đầu cách nhau mặc định 2 giây để tránh các đợt tạo container dồn dập trên Docker daemon cục bộ; ghi đè bằng `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner mặc định preflight Docker, dọn các container E2E OpenClaw cũ, phát trạng thái lane đang hoạt động mỗi 30 giây, chia sẻ cache công cụ CLI provider giữa các lane tương thích, mặc định thử lại lỗi provider live thoáng qua một lần (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) và lưu thời gian lane trong `.artifacts/docker-tests/lane-timings.json` để sắp xếp dài nhất trước trong các lần chạy sau. Dùng `OPENCLAW_DOCKER_ALL_DRY_RUN=1` để in manifest lane mà không chạy Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` để tinh chỉnh đầu ra trạng thái hoặc `OPENCLAW_DOCKER_ALL_TIMINGS=0` để tắt tái sử dụng thời gian. Dùng `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` chỉ cho các lane xác định/cục bộ hoặc `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` chỉ cho các lane provider live; alias package là `pnpm test:docker:local:all` và `pnpm test:docker:live:all`. Chế độ chỉ live hợp nhất các lane live chính và tail vào một pool dài nhất trước để các bucket provider có thể đóng gói công việc Claude, Codex và Gemini cùng nhau. Runner dừng lên lịch lane pooled mới sau lỗi đầu tiên trừ khi đặt `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, và mỗi lane có timeout dự phòng 120 phút có thể ghi đè bằng `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; các lane live/tail được chọn dùng giới hạn chặt hơn theo từng lane. Các lệnh thiết lập Docker backend CLI có timeout riêng qua `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (mặc định 180). Log theo từng lane, `summary.json`, `failures.json` và thời gian theo pha được ghi dưới `.artifacts/docker-tests/<run-id>/`; dùng `pnpm test:docker:timings <summary.json>` để kiểm tra các lane chậm và `pnpm test:docker:rerun <run-id|summary.json|failures.json>` để in các lệnh chạy lại có mục tiêu, chi phí thấp.
- `pnpm test:docker:browser-cdp-snapshot`: Build container E2E nguồn dựa trên Chromium, khởi động CDP thô cùng một Gateway cô lập, chạy `browser doctor --deep` và xác minh snapshot vai trò CDP bao gồm URL liên kết, phần tử có thể nhấp được nâng cấp từ con trỏ, tham chiếu iframe và metadata frame.
- Probe Docker live backend CLI có thể được chạy dưới dạng các lane tập trung, ví dụ `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` hoặc `pnpm test:docker:live-cli-backend:codex:mcp`. Claude và Gemini có các alias `:resume` và `:mcp` tương ứng.
- `pnpm test:docker:openwebui`: Khởi động OpenClaw + Open WebUI trong Docker, đăng nhập qua Open WebUI, kiểm tra `/api/models`, rồi chạy một cuộc trò chuyện thật được proxy qua `/api/chat/completions`. Cần một khóa mô hình live có thể dùng được (ví dụ OpenAI trong `~/.profile`), kéo một image Open WebUI bên ngoài và không được kỳ vọng ổn định trên CI như các bộ đơn vị/e2e thông thường.
- `pnpm test:docker:mcp-channels`: Khởi động một container Gateway đã seed và một container client thứ hai sinh `openclaw mcp serve`, rồi xác minh phát hiện hội thoại đã định tuyến, đọc transcript, metadata tệp đính kèm, hành vi hàng đợi sự kiện live, định tuyến gửi ra ngoài và thông báo kênh + quyền kiểu Claude qua bridge stdio thật. Assertion thông báo Claude đọc trực tiếp các frame MCP stdio thô để smoke phản ánh đúng những gì bridge thực sự phát ra.
- `pnpm test:docker:upgrade-survivor`: Cài đặt tarball OpenClaw đã đóng gói lên một fixture người dùng cũ bị bẩn, chạy cập nhật package cùng doctor không tương tác mà không có khóa provider hoặc kênh trực tiếp, sau đó khởi động một Gateway loopback và kiểm tra rằng agents, cấu hình kênh, allowlist plugin, tệp workspace/session, trạng thái phụ thuộc plugin cũ lỗi thời, quá trình khởi động và trạng thái RPC vẫn tồn tại.
- `pnpm test:docker:published-upgrade-survivor`: Mặc định cài đặt `openclaw@latest`, gieo các tệp người dùng hiện có thực tế mà không có khóa provider hoặc kênh trực tiếp, cấu hình baseline đó bằng một công thức lệnh `openclaw config set` được tích hợp sẵn, cập nhật bản cài đặt đã phát hành đó lên tarball OpenClaw đã đóng gói, chạy doctor không tương tác, ghi `.artifacts/upgrade-survivor/summary.json`, sau đó khởi động một Gateway loopback và kiểm tra rằng các intent đã cấu hình, tệp workspace/session, cấu hình plugin lỗi thời và trạng thái phụ thuộc cũ, quá trình khởi động, `/healthz`, `/readyz` và trạng thái RPC vẫn tồn tại hoặc được sửa chữa sạch sẽ. Ghi đè một baseline bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, mở rộng một ma trận chính xác bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` chẳng hạn như `all-since-2026.4.23`, hoặc thêm fixture kịch bản bằng `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; tập reported-issues bao gồm `configured-plugin-installs` để xác minh rằng các plugin OpenClaw bên ngoài đã cấu hình được cài đặt tự động trong quá trình nâng cấp. Package Acceptance hiển thị các mục đó dưới dạng `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` và `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration`: Chạy harness published-upgrade survivor trong kịch bản `plugin-deps-cleanup` thiên về dọn dẹp, mặc định bắt đầu từ `openclaw@2026.4.23`. Workflow `Update Migration` riêng mở rộng lane này với `baselines=all-since-2026.4.23` để mọi package ổn định đã phát hành từ `.23` trở đi đều cập nhật lên candidate và chứng minh việc dọn dẹp phụ thuộc plugin đã cấu hình bên ngoài Full Release CI.
- `pnpm test:docker:plugins`: Chạy smoke cài đặt/cập nhật cho đường dẫn cục bộ, `file:`, các package npm registry có phụ thuộc được hoist, refs git động, fixture ClawHub, cập nhật marketplace và bật/kiểm tra bundle Claude.
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: chạy tuần tự mọi cấu hình lá Vitest của bộ đầy đủ và ghi dữ liệu thời lượng theo nhóm cùng các artifact JSON/log theo từng cấu hình. Test Performance Agent dùng dữ liệu này làm baseline trước khi thử sửa các kiểm thử chậm.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: so sánh các báo cáo theo nhóm sau một thay đổi tập trung vào hiệu năng.
- Tích hợp Gateway: bật có chủ đích qua `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` hoặc `pnpm test:gateway`.
- `pnpm test:e2e`: Chạy các kiểm thử smoke end-to-end của Gateway (ghép cặp WS/HTTP/node nhiều phiên bản). Mặc định dùng `threads` + `isolate: false` với worker thích ứng trong `vitest.e2e.config.ts`; tinh chỉnh bằng `OPENCLAW_E2E_WORKERS=<n>` và đặt `OPENCLAW_E2E_VERBOSE=1` để có log chi tiết.
- `pnpm test:live`: Chạy kiểm thử live của provider (minimax/zai). Yêu cầu API key và `LIVE=1` (hoặc `*_LIVE_TEST=1` riêng theo provider) để bỏ skip.
- `pnpm test:docker:all`: Xây dựng image live-test dùng chung, đóng gói OpenClaw một lần dưới dạng tarball npm, xây dựng/tái sử dụng một image runner Node/Git trần cùng một image chức năng cài tarball đó vào `/app`, rồi chạy các làn smoke Docker với `OPENCLAW_SKIP_DOCKER_BUILD=1` thông qua scheduler có trọng số. Image trần (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) được dùng cho các làn installer/update/plugin-dependency; các làn đó mount tarball đã dựng sẵn thay vì dùng nguồn repo được sao chép. Image chức năng (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) được dùng cho các làn chức năng ứng dụng đã build bình thường. `scripts/package-openclaw-for-docker.mjs` là trình đóng gói package cục bộ/CI duy nhất và xác thực tarball cùng `dist/postinstall-inventory.json` trước khi Docker sử dụng. Định nghĩa làn Docker nằm trong `scripts/lib/docker-e2e-scenarios.mjs`; logic planner nằm trong `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` thực thi plan đã chọn. `node scripts/test-docker-all.mjs --plan-json` xuất plan CI do scheduler sở hữu cho các làn đã chọn, loại image, nhu cầu package/live-image, kịch bản trạng thái và kiểm tra thông tin xác thực mà không build hoặc chạy Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` kiểm soát slot tiến trình và mặc định là 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` kiểm soát pool đuôi nhạy với provider và mặc định là 10. Giới hạn làn nặng mặc định là `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` và `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; giới hạn provider mặc định là một làn nặng cho mỗi provider qua `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` và `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Dùng `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` hoặc `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` cho máy chủ lớn hơn. Nếu một làn vượt quá trọng số hiệu dụng hoặc giới hạn tài nguyên trên máy chủ có độ song song thấp, nó vẫn có thể bắt đầu từ một pool trống và sẽ chạy một mình cho đến khi giải phóng dung lượng. Mặc định các lần bắt đầu làn được giãn cách 2 giây để tránh bão tạo container của daemon Docker cục bộ; ghi đè bằng `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner mặc định preflight Docker, dọn các container E2E OpenClaw cũ, phát trạng thái làn đang hoạt động mỗi 30 giây, chia sẻ cache công cụ CLI provider giữa các làn tương thích, thử lại lỗi live-provider tạm thời một lần theo mặc định (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) và lưu thời gian làn trong `.artifacts/docker-tests/lane-timings.json` để sắp xếp dài nhất trước ở các lần chạy sau. Dùng `OPENCLAW_DOCKER_ALL_DRY_RUN=1` để in manifest làn mà không chạy Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` để tinh chỉnh đầu ra trạng thái, hoặc `OPENCLAW_DOCKER_ALL_TIMINGS=0` để tắt tái sử dụng thời gian. Dùng `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` để chỉ chạy các làn xác định/cục bộ hoặc `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` để chỉ chạy các làn live-provider; các alias package là `pnpm test:docker:local:all` và `pnpm test:docker:live:all`. Chế độ chỉ live hợp nhất các làn live chính và đuôi thành một pool dài nhất trước để các bucket provider có thể đóng gói công việc Claude, Codex và Gemini cùng nhau. Runner dừng lên lịch các làn pooled mới sau lỗi đầu tiên trừ khi đặt `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, và mỗi làn có timeout dự phòng 120 phút có thể ghi đè bằng `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; các làn live/đuôi được chọn dùng giới hạn theo làn chặt hơn. Các lệnh thiết lập Docker backend CLI có timeout riêng qua `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (mặc định 180). Log theo làn, `summary.json`, `failures.json` và thời gian theo pha được ghi dưới `.artifacts/docker-tests/<run-id>/`; dùng `pnpm test:docker:timings <summary.json>` để kiểm tra các làn chậm và `pnpm test:docker:rerun <run-id|summary.json|failures.json>` để in các lệnh chạy lại có mục tiêu giá rẻ.
- `pnpm test:docker:browser-cdp-snapshot`: Xây dựng một container E2E nguồn dựa trên Chromium, khởi động CDP thô cùng một Gateway biệt lập, chạy `browser doctor --deep` và xác minh snapshot vai trò CDP bao gồm URL liên kết, các phần tử có thể nhấp được thăng cấp theo con trỏ, tham chiếu iframe và siêu dữ liệu frame.
- Các probe Docker live backend CLI có thể được chạy dưới dạng các làn tập trung, ví dụ `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` hoặc `pnpm test:docker:live-cli-backend:codex:mcp`. Claude và Gemini có các alias `:resume` và `:mcp` tương ứng.
- `pnpm test:docker:openwebui`: Khởi động OpenClaw + Open WebUI trong Docker, đăng nhập qua Open WebUI, kiểm tra `/api/models`, rồi chạy một cuộc trò chuyện thật qua proxy thông qua `/api/chat/completions`. Yêu cầu một key mô hình live dùng được (ví dụ OpenAI trong `~/.profile`), kéo một image Open WebUI bên ngoài và không được kỳ vọng ổn định trên CI như các bộ unit/e2e bình thường.
- `pnpm test:docker:mcp-channels`: Khởi động một container Gateway đã seed và một container client thứ hai sinh `openclaw mcp serve`, rồi xác minh khám phá hội thoại đã định tuyến, đọc transcript, siêu dữ liệu tệp đính kèm, hành vi hàng đợi sự kiện live, định tuyến gửi đi và thông báo kênh + quyền kiểu Claude qua cầu stdio thật. Assertion thông báo Claude đọc trực tiếp các frame MCP stdio thô để smoke phản ánh đúng những gì cầu thực sự phát ra.
- `pnpm test:docker:upgrade-survivor`: Cài đặt tarball OpenClaw đã đóng gói lên một fixture người dùng cũ bẩn, chạy cập nhật gói cùng doctor không tương tác mà không có khóa nhà cung cấp hoặc kênh live, sau đó khởi động một Gateway loopback và kiểm tra rằng agent, cấu hình kênh, danh sách cho phép plugin, tệp workspace/session, trạng thái phụ thuộc plugin legacy lỗi thời, quá trình khởi động và trạng thái RPC vẫn được giữ nguyên.
- `pnpm test:docker:published-upgrade-survivor`: Cài đặt `openclaw@latest` theo mặc định, gieo các tệp người dùng hiện có thực tế mà không có khóa nhà cung cấp hoặc kênh live, cấu hình baseline đó bằng một công thức lệnh `openclaw config set` được nhúng sẵn, cập nhật bản cài đặt đã phát hành đó lên tarball OpenClaw đã đóng gói, chạy doctor không tương tác, ghi `.artifacts/upgrade-survivor/summary.json`, sau đó khởi động một Gateway loopback và kiểm tra rằng các intent đã cấu hình, tệp workspace/session, cấu hình plugin lỗi thời và trạng thái phụ thuộc legacy, quá trình khởi động, `/healthz`, `/readyz` và trạng thái RPC vẫn được giữ nguyên hoặc được sửa chữa sạch sẽ. Ghi đè một baseline bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, mở rộng một ma trận chính xác bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` như `all-since-2026.4.23`, hoặc thêm fixture kịch bản bằng `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; tập reported-issues bao gồm `configured-plugin-installs` để xác minh các Plugin OpenClaw bên ngoài đã cấu hình được cài đặt tự động trong quá trình nâng cấp và `stale-source-plugin-shadow` để tránh các bóng plugin chỉ có source làm hỏng quá trình khởi động. Package Acceptance hiển thị các tùy chọn đó dưới dạng `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` và `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration`: Chạy harness published-upgrade survivor trong kịch bản `plugin-deps-cleanup` nặng về dọn dẹp, bắt đầu từ `openclaw@2026.4.23` theo mặc định. Workflow `Update Migration` riêng mở rộng lane này với `baselines=all-since-2026.4.23` để mọi gói stable đã phát hành từ `.23` trở đi đều cập nhật lên bản ứng viên và chứng minh việc dọn dẹp phụ thuộc configured-plugin bên ngoài Full Release CI.
- `pnpm test:docker:plugins`: Chạy smoke cài đặt/cập nhật cho đường dẫn cục bộ, `file:`, các gói npm registry có phụ thuộc được hoist, ref git chuyển động, fixture ClawHub, cập nhật marketplace và bật/kiểm tra Claude-bundle.
## Cổng PR cục bộ
Đối với các bước kiểm tra land/gate PR cục bộ, chạy:
Đối với các kiểm tra land/gate PR cục bộ, hãy chạy:
- `pnpm check:changed`
- `pnpm check`
@ -66,12 +66,12 @@ x-i18n:
- `pnpm test`
- `pnpm check:docs`
Nếu `pnpm test` chập chờn trên một máy chủ đang tải nặng, hãy chạy lại một lần trước khi xem đó là hồi quy, rồi cô lập bằng `pnpm test <path/to/test>`. Đối với máy chủ bị giới hạn bộ nhớ, dùng:
Nếu `pnpm test` bị lỗi không ổn định trên một máy chủ đang tải nặng, hãy chạy lại một lần trước khi xem đó là hồi quy, rồi cô lập bằng `pnpm test <path/to/test>`. Với các máy chủ bị giới hạn bộ nhớ, hãy dùng:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Bench độ trễ mô hình (khóa cục bộ)
## Đo độ trễ mô hình (khóa cục bộ)
Script: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
@ -79,14 +79,14 @@ Cách dùng:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Env tùy chọn: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt mặc định: “Trả lời bằng một từ duy nhất: ok. Không dấu câu hoặc văn bản bổ sung.”
- Prompt mặc định: “Trả lời bằng một từ duy nhất: ok. Không có dấu câu hoặc văn bản bổ sung.”
Lần chạy gần nhất (2025-12-31, 20 lần chạy):
- minimax trung vị 1279ms (tối thiểu 1114, tối đa 2431)
- opus trung vị 2454ms (tối thiểu 1224, tối đa 3170)
## Bench khởi động CLI
## Đo thời gian khởi động CLI
Script: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -114,12 +114,12 @@ Preset:
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: cả hai preset
Đầu ra bao gồm `sampleCount`, trung bình, p50, p95, tối thiểu/tối đa, phân phối mã thoát/tín hiệu, và tóm tắt RSS tối đa cho từng lệnh. `--cpu-prof-dir` / `--heap-prof-dir` tùy chọn sẽ ghi hồ sơ V8 cho từng lần chạy để thời gian đo và việc thu thập hồ sơ dùng cùng một harness.
Đầu ra bao gồm `sampleCount`, trung bình, p50, p95, tối thiểu/tối đa, phân bố mã thoát/tín hiệu và tóm tắt RSS tối đa cho từng lệnh. `--cpu-prof-dir` / `--heap-prof-dir` tùy chọn ghi hồ sơ V8 cho mỗi lần chạy để việc đo thời gian và thu thập hồ sơ dùng cùng một harness.
Quy ước đầu ra đã lưu:
- `pnpm test:startup:bench:smoke` ghi artifact smoke có mục tiêu tại `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` ghi artifact bộ đầy đủ tại `.artifacts/cli-startup-bench-all.json` bằng `runs=5` và `warmup=1`
- `pnpm test:startup:bench:smoke` ghi artifact smoke được nhắm mục tiêu tại `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` ghi artifact bộ kiểm thử đầy đủ tại `.artifacts/cli-startup-bench-all.json` bằng `runs=5` và `warmup=1`
- `pnpm test:startup:bench:update` làm mới fixture baseline đã commit tại `test/fixtures/cli-startup-bench.json` bằng `runs=5` và `warmup=1`
Fixture đã commit:
@ -130,7 +130,7 @@ Fixture đã commit:
## Onboarding E2E (Docker)
Docker là tùy chọn; phần này chỉ cần cho các bài smoke test onboarding được container hóa.
Docker là tùy chọn; phần này chỉ cần cho các kiểm thử smoke onboarding trong container.
Luồng khởi động lạnh đầy đủ trong một container Linux sạch:
@ -138,11 +138,11 @@ Luồng khởi động lạnh đầy đủ trong một container Linux sạch:
scripts/e2e/onboard-docker.sh
```
Script này điều khiển wizard tương tác qua pseudo-tty, xác minh các tệp cấu hình/workspace/session, sau đó khởi động Gateway và chạy `openclaw health`.
Script này điều khiển wizard tương tác qua pseudo-tty, xác minh các tệp cấu hình/không gian làm việc/phiên, sau đó khởi động Gateway và chạy `openclaw health`.
## Smoke nhập QR (Docker)
Đảm bảo helper runtime QR được duy trì tải được trong các runtime Docker Node được hỗ trợ (Node 24 mặc định, Node 22 tương thích):
Đảm bảo helper runtime QR được duy trì tải được dưới các runtime Docker Node được hỗ trợ (Node 24 mặc định, Node 22 tương thích):
```bash
pnpm test:docker:qr
@ -151,5 +151,5 @@ pnpm test:docker:qr
## Liên quan
- [Kiểm thử](/vi/help/testing)
- [Kiểm thử live](/vi/help/testing-live)
- [Kiểm thử bản cập nhật và Plugin](/vi/help/testing-updates-plugins)
- [Kiểm thử trực tiếp](/vi/help/testing-live)
- [Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins)

177
docs/vi/reference/transcript-hygiene.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Bạn đang gỡ lỗi các lỗi từ chối yêu cầu của nhà cung cấp liên quan đến cấu trúc bản ghi hội thoại
- Bạn đang gỡ lỗi các trường hợp nhà cung cấp từ chối yêu cầu liên quan đến cấu trúc bản ghi hội thoại
- Bạn đang thay đổi logic làm sạch bản ghi hội thoại hoặc sửa chữa lệnh gọi công cụ
- Bạn đang điều tra các điểm không khớp về mã định danh lệnh gọi công cụ giữa các nhà cung cấp
summary: 'Tham khảo: các quy tắc làm sạch và sửa chữa bản ghi dành riêng cho nhà cung cấp'
- Bạn đang điều tra các trường hợp ID lệnh gọi công cụ không khớp giữa các nhà cung cấp
summary: 'Tham chiếu: các quy tắc làm sạch và sửa chữa bản ghi dành riêng cho từng nhà cung cấp'
title: Vệ sinh bản ghi hội thoại
x-i18n:
generated_at: "2026-05-03T10:43:33Z"
generated_at: "2026-05-05T01:50:30Z"
model: gpt-5.5
provider: openai
source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
source_path: reference/transcript-hygiene.md
workflow: 16
---
OpenClaw áp dụng **các bản sửa lỗi dành riêng cho nhà cung cấp** cho bản ghi hội thoại trước một lần chạy (xây dựng ngữ cảnh mô hình). Hầu hết các điều chỉnh này là điều chỉnh **trong bộ nhớ** dùng để đáp ứng các yêu cầu nghiêm ngặt của nhà cung cấp. Một lượt sửa chữa tệp phiên riêng biệt cũng có thể ghi lại JSONL đã lưu trữ trước khi phiên được tải, nhưng chỉ đối với các dòng sai định dạng hoặc các lượt đã lưu không phải là bản ghi bền hợp lệ. Các phản hồi trợ lý đã được gửi được giữ nguyên trên đĩa; việc loại bỏ phần điền sẵn dành riêng cho nhà cung cấp của trợ lý chỉ diễn ra khi xây dựng payload gửi đi. Khi có sửa chữa, tệp gốc được sao lưu cạnh tệp phiên.
OpenClaw áp dụng **các bản sửa dành riêng cho nhà cung cấp** cho bản ghi hội thoại trước khi chạy (xây dựng ngữ cảnh mô hình). Hầu hết đây là các điều chỉnh **trong bộ nhớ** dùng để đáp ứng các yêu cầu nghiêm ngặt của nhà cung cấp. Một lượt sửa chữa tệp phiên riêng biệt cũng có thể ghi lại JSONL đã lưu trước khi phiên được tải, nhưng chỉ đối với các dòng sai định dạng hoặc các lượt đã lưu không phải là bản ghi bền hợp lệ. Các phản hồi assistant đã được chuyển phát được giữ nguyên trên đĩa; việc loại bỏ assistant-prefill dành riêng cho nhà cung cấp chỉ diễn ra khi xây dựng payload gửi đi. Khi có sửa chữa, tệp gốc được sao lưu bên cạnh tệp phiên.
Phạm vi bao gồm:
- Ngữ cảnh lời nhắc chỉ dùng lúc chạy không xuất hiện trong các lượt bản ghi hội thoại hiển thị với người dùng
- Ngữ cảnh prompt chỉ dùng khi chạy không xuất hiện trong các lượt bản ghi hội thoại người dùng có thể thấy
- Làm sạch id lệnh gọi công cụ
- Xác thực đầu vào lệnh gọi công cụ
- Sửa chữa ghép cặp kết quả công cụ
@ -26,38 +26,38 @@ Phạm vi bao gồm:
- Dọn dẹp chữ ký suy nghĩ
- Dọn dẹp chữ ký thinking
- Làm sạch payload hình ảnh
- Dọn dẹp khối văn bản trống trước khi phát lại cho nhà cung cấp
- Gắn thẻ nguồn gốc đầu vào của người dùng (cho lời nhắc được định tuyến liên phiên)
- Sửa chữa lượt lỗi trợ lý trống cho phát lại Bedrock Converse
- Dọn dẹp khối văn bản trống trước khi phát lại qua nhà cung cấp
- Gắn thẻ nguồn gốc đầu vào người dùng (cho prompt được định tuyến giữa các phiên)
- Sửa chữa lượt lỗi assistant trống cho phát lại Bedrock Converse
Nếu bạn cần chi tiết về lưu trữ bản ghi hội thoại, xem:
Nếu bạn cần chi tiết lưu trữ bản ghi hội thoại, xem:
- [Phân tích chuyên sâu về quản lý phiên](/vi/reference/session-management-compaction)
- [Phân tích sâu về quản lý phiên](/vi/reference/session-management-compaction)
---
## Quy tắc toàn cục: ngữ cảnh lúc chạy không phải là bản ghi hội thoại của người dùng
## Quy tắc toàn cục: ngữ cảnh khi chạy không phải là bản ghi hội thoại người dùng
Ngữ cảnh lúc chạy/hệ thống có thể được thêm vào lời nhắc mô hình cho một lượt, nhưng đó
không phải là nội dung do người dùng cuối soạn. OpenClaw giữ một phần thân lời nhắc
riêng hướng tới bản ghi hội thoại cho các phản hồi Gateway, followup được xếp hàng, ACP, CLI và các lần chạy Pi
nhúng. Các lượt người dùng hiển thị đã lưu dùng phần thân bản ghi hội thoại đó thay vì
lời nhắc được làm giàu bằng ngữ cảnh lúc chạy.
Ngữ cảnh runtime/system có thể được thêm vào prompt mô hình cho một lượt, nhưng đó
không phải là nội dung do người dùng cuối soạn. OpenClaw giữ một phần thân prompt
riêng hướng tới bản ghi hội thoại cho phản hồi Gateway, các followup xếp hàng, ACP, CLI, và các lần chạy Pi
được nhúng. Các lượt người dùng hiển thị đã lưu dùng phần thân bản ghi hội thoại đó thay vì
prompt đã được bổ sung ngữ cảnh khi chạy.
Đối với các phiên cũ đã lưu các wrapper lúc chạy, các bề mặt lịch sử Gateway
áp dụng một phép chiếu hiển thị trước khi trả về thông báo cho WebChat,
TUI, REST hoặc máy khách SSE.
Đối với các phiên cũ đã lưu các lớp bọc runtime, các bề mặt lịch sử Gateway
áp dụng một phép chiếu hiển thị trước khi trả về thông điệp cho WebChat,
TUI, REST, hoặc máy khách SSE.
---
## Nơi cơ chế này chạy
## Nơi phần này chạy
Toàn bộ vệ sinh bản ghi hội thoại được tập trung trong runner nhúng:
- Chọn chính sách: `src/agents/transcript-policy.ts`
- Áp dụng làm sạch/sửa chữa: `sanitizeSessionHistory` trong `src/agents/pi-embedded-runner/replay-history.ts`
Chính sách dùng `provider`, `modelApi` và `modelId` để quyết định áp dụng những gì.
Chính sách dùng `provider`, `modelApi`, và `modelId` để quyết định cần áp dụng gì.
Tách biệt với vệ sinh bản ghi hội thoại, các tệp phiên được sửa chữa (nếu cần) trước khi tải:
@ -68,27 +68,27 @@ Tách biệt với vệ sinh bản ghi hội thoại, các tệp phiên được
## Quy tắc toàn cục: làm sạch hình ảnh
Payload hình ảnh luôn được làm sạch để ngăn việc bị nhà cung cấp từ chối do giới hạn
kích thước (giảm tỷ lệ/nén lại hình ảnh base64 quá lớn).
Payload hình ảnh luôn được làm sạch để ngăn nhà cung cấp từ chối do giới hạn
kích thước (thu nhỏ/nén lại ảnh base64 quá lớn).
Điều này cũng giúp kiểm soát áp lực token do hình ảnh gây ra cho các mô hình hỗ trợ thị giác.
Kích thước tối đa thấp hơn thường giảm mức dùng token; kích thước cao hơn giữ lại chi tiết.
Điều này cũng giúp kiểm soát áp lực token do hình ảnh gây ra cho các mô hình hỗ trợ vision.
Kích thước tối đa thấp hơn thường giảm mức sử dụng token; kích thước cao hơn giữ được chi tiết.
Triển khai:
- `sanitizeSessionMessagesImages` trong `src/agents/pi-embedded-helpers/images.ts`
- `sanitizeContentBlocksImages` trong `src/agents/tool-images.ts`
- Cạnh tối đa của hình ảnh có thể cấu hình qua `agents.defaults.imageMaxDimensionPx` (mặc định: `1200`).
- Các khối văn bản trống bị xóa khi lượt này duyệt nội dung phát lại. Các lượt trợ lý
trở nên trống sẽ bị loại khỏi bản sao phát lại; các lượt người dùng và kết quả công cụ
trở nên trống sẽ nhận một placeholder nội dung bị bỏ qua không rỗng.
- Cạnh ảnh tối đa có thể cấu hình qua `agents.defaults.imageMaxDimensionPx` (mặc định: `1200`).
- Các khối văn bản trống bị xóa trong khi lượt này duyệt nội dung phát lại. Các lượt assistant
trở thành trống sẽ bị loại khỏi bản sao phát lại; các lượt người dùng và kết quả công cụ
trở thành trống nhận một placeholder nội dung bị lược bỏ không trống.
---
## Quy tắc toàn cục: lệnh gọi công cụ sai định dạng
Các khối lệnh gọi công cụ của trợ lý thiếu cả `input` lẫn `arguments` sẽ bị loại bỏ
trước khi ngữ cảnh mô hình được xây dựng. Điều này ngăn việc nhà cung cấp từ chối do các
Các khối lệnh gọi công cụ của assistant thiếu cả `input` và `arguments` sẽ bị loại bỏ
trước khi ngữ cảnh mô hình được xây dựng. Điều này ngăn việc nhà cung cấp từ chối từ các
lệnh gọi công cụ được lưu một phần (ví dụ, sau lỗi giới hạn tốc độ).
Triển khai:
@ -98,22 +98,22 @@ Triển khai:
---
## Quy tắc toàn cục: nguồn gốc đầu vào liên phiên
## Quy tắc toàn cục: nguồn gốc đầu vào giữa các phiên
Khi một tác nhân gửi lời nhắc vào một phiên khác qua `sessions_send` (bao gồm
các bước trả lời/thông báo giữa các tác nhân), OpenClaw lưu lượt người dùng được tạo với:
Khi một agent gửi prompt vào một phiên khác qua `sessions_send` (bao gồm
các bước trả lời/thông báo từ agent tới agent), OpenClaw lưu lượt người dùng đã tạo với:
- `message.provenance.kind = "inter_session"`
OpenClaw cũng thêm một marker cùng lượt `[Inter-session message ... isUser=false]`
trước văn bản lời nhắc được định tuyến để lệnh gọi mô hình đang hoạt động có thể phân biệt
đầu ra từ phiên bên ngoài với chỉ dẫn của người dùng cuối bên ngoài. Marker này bao gồm
phiên nguồn, kênh và công cụ khi có. Bản ghi hội thoại vẫn dùng
`role: "user"` để tương thích với nhà cung cấp, nhưng cả văn bản hiển thị và siêu dữ liệu
nguồn gốc đều đánh dấu lượt đó là dữ liệu liên phiên.
OpenClaw cũng thêm vào đầu cùng lượt một marker `[Inter-session message ... isUser=false]`
trước văn bản prompt được định tuyến để lời gọi mô hình đang hoạt động có thể phân biệt
đầu ra phiên bên ngoài với chỉ dẫn người dùng cuối bên ngoài. Marker này bao gồm
phiên nguồn, kênh, và công cụ khi có. Bản ghi hội thoại vẫn dùng
`role: "user"` để tương thích với nhà cung cấp, nhưng văn bản hiển thị và siêu dữ liệu nguồn gốc
đều đánh dấu lượt này là dữ liệu giữa các phiên.
Trong quá trình dựng lại ngữ cảnh, OpenClaw áp dụng cùng marker cho các lượt người dùng
liên phiên đã lưu cũ hơn chỉ có siêu dữ liệu nguồn gốc.
Trong quá trình xây dựng lại ngữ cảnh, OpenClaw áp dụng cùng marker cho các lượt người dùng
giữa các phiên đã lưu cũ hơn chỉ có siêu dữ liệu nguồn gốc.
---
@ -122,19 +122,20 @@ liên phiên đã lưu cũ hơn chỉ có siêu dữ liệu nguồn gốc.
**OpenAI / OpenAI Codex**
- Chỉ làm sạch hình ảnh.
- Loại bỏ các chữ ký reasoning mồ côi (mục reasoning độc lập không có khối nội dung theo sau) cho bản ghi hội thoại OpenAI Responses/Codex, và loại bỏ reasoning OpenAI có thể phát lại sau khi chuyển tuyến mô hình.
- Giữ lại các payload mục reasoning của OpenAI Responses có thể phát lại, bao gồm các mục tóm tắt trống đã mã hóa, để phát lại thủ công/WebSocket giữ trạng thái `rs_*` bắt buộc được ghép với các mục đầu ra của trợ lý.
- Loại bỏ các chữ ký reasoning mồ côi (các mục reasoning độc lập không có khối nội dung theo sau) cho bản ghi hội thoại OpenAI Responses/Codex, và loại bỏ OpenAI reasoning có thể phát lại sau khi chuyển tuyến mô hình.
- Giữ nguyên payload mục reasoning của OpenAI Responses có thể phát lại, bao gồm các mục tóm tắt trống đã mã hóa, để phát lại thủ công/WebSocket giữ trạng thái `rs_*` bắt buộc được ghép với các mục đầu ra assistant.
- Native ChatGPT Codex Responses tuân theo tính tương đương dây Codex bằng cách phát lại payload reasoning/message/function Responses trước đó mà không có ID mục trước đó trong khi vẫn giữ `prompt_cache_key` của phiên.
- Không làm sạch id lệnh gọi công cụ.
- Sửa chữa ghép cặp kết quả công cụ có thể di chuyển các đầu ra thực đã khớp và tổng hợp các đầu ra `aborted` kiểu Codex cho các lệnh gọi công cụ bị thiếu.
- Sửa chữa ghép cặp kết quả công cụ có thể di chuyển các đầu ra khớp thật và tổng hợp đầu ra `aborted` kiểu Codex cho các lệnh gọi công cụ bị thiếu.
- Không xác thực hoặc sắp xếp lại lượt.
- Các đầu ra công cụ thuộc họ OpenAI Responses bị thiếu được tổng hợp thành `aborted` để khớp với chuẩn hóa phát lại Codex.
- Đầu ra công cụ bị thiếu thuộc họ OpenAI Responses được tổng hợp thành `aborted` để khớp với chuẩn hóa phát lại Codex.
- Không loại bỏ chữ ký suy nghĩ.
**Gemma 4 tương thích OpenAI**
- Các khối thinking/reasoning lịch sử của trợ lý bị loại bỏ trước khi phát lại để máy chủ Gemma 4
cục bộ tương thích OpenAI không nhận nội dung reasoning của lượt trước.
- Các phần tiếp nối lệnh gọi công cụ cùng lượt hiện tại giữ khối reasoning của trợ lý
- Các khối thinking/reasoning lịch sử của assistant bị loại bỏ trước khi phát lại để máy chủ
Gemma 4 cục bộ tương thích OpenAI không nhận nội dung reasoning của lượt trước.
- Các phần tiếp nối lệnh gọi công cụ cùng lượt hiện tại giữ khối reasoning của assistant
gắn với lệnh gọi công cụ cho đến khi kết quả công cụ đã được phát lại.
**Google (Generative AI / Gemini CLI / Antigravity)**
@ -142,51 +143,51 @@ liên phiên đã lưu cũ hơn chỉ có siêu dữ liệu nguồn gốc.
- Làm sạch id lệnh gọi công cụ: chữ và số nghiêm ngặt.
- Sửa chữa ghép cặp kết quả công cụ và kết quả công cụ tổng hợp.
- Xác thực lượt (luân phiên lượt kiểu Gemini).
- Sửa thứ tự lượt Google (thêm một bootstrap người dùng rất nhỏ ở đầu nếu lịch sử bắt đầu bằng trợ lý).
- Sửa thứ tự lượt Google (thêm một bootstrap người dùng rất nhỏ ở đầu nếu lịch sử bắt đầu bằng assistant).
- Antigravity Claude: chuẩn hóa chữ ký thinking; loại bỏ các khối thinking không có chữ ký.
**Anthropic / Minimax (tương thích Anthropic)**
- Sửa chữa ghép cặp kết quả công cụ và kết quả công cụ tổng hợp.
- Xác thực lượt (gộp các lượt người dùng liên tiếp để đáp ứng luân phiên nghiêm ngặt).
- Các lượt điền sẵn trợ lý ở cuối bị loại khỏi payload Anthropic Messages
gửi đi khi thinking được bật, bao gồm các tuyến Cloudflare AI Gateway.
- Các khối thinking thiếu, rỗng hoặc có chữ ký phát lại trống bị loại bỏ
trước khi chuyển đổi nhà cung cấp. Nếu điều đó làm một lượt trợ lý rỗng, OpenClaw giữ
hình dạng lượt với văn bản reasoning bị bỏ qua không rỗng.
- Các lượt trợ lý cũ chỉ có thinking phải bị loại bỏ được thay bằng
văn bản reasoning bị bỏ qua không rỗng để adapter nhà cung cấp không loại bỏ lượt
- Các lượt assistant prefill ở cuối bị loại khỏi payload Anthropic Messages gửi đi
khi thinking được bật, bao gồm các tuyến Cloudflare AI Gateway.
- Các khối thinking bị thiếu, trống, hoặc có chữ ký phát lại chỉ gồm khoảng trắng sẽ bị loại bỏ
trước khi chuyển đổi nhà cung cấp. Nếu việc đó làm trống một lượt assistant, OpenClaw giữ
hình dạng lượt với văn bản reasoning bị lược bỏ không trống.
- Các lượt assistant chỉ có thinking cũ hơn phải bị loại bỏ được thay bằng
văn bản reasoning bị lược bỏ không trống để adapter nhà cung cấp không loại lượt
phát lại.
**Amazon Bedrock (Converse API)**
- Các lượt lỗi luồng trợ lý trống được sửa thành một khối văn bản dự phòng không rỗng
trước khi phát lại. Bedrock Converse từ chối thông điệp trợ lý có `content: []`, vì vậy
các lượt trợ lý đã lưu với `stopReason: "error"` và nội dung trống cũng được
sửa trên đĩa trước khi tải.
- Các lượt lỗi luồng trợ lý chỉ chứa khối văn bản trống bị loại khỏi
bản sao phát lại trong bộ nhớ thay vì phát lại một khối trống không hợp lệ.
- Các khối thinking Claude thiếu, rỗng hoặc có chữ ký phát lại trống bị
loại bỏ trước khi phát lại Converse. Nếu điều đó làm một lượt trợ lý rỗng, OpenClaw
giữ hình dạng lượt với văn bản reasoning bị bỏ qua không rỗng.
- Các lượt trợ lý cũ chỉ có thinking phải bị loại bỏ được thay bằng
văn bản reasoning bị bỏ qua không rỗng để phát lại Converse giữ hình dạng lượt nghiêm ngặt.
- Phát lại lọc các lượt trợ lý phản chiếu gửi của OpenClaw và do gateway chèn.
- Làm sạch hình ảnh được áp dụng thông qua quy tắc toàn cục.
- Các lượt lỗi luồng assistant trống được sửa thành một khối văn bản fallback không trống
trước khi phát lại. Bedrock Converse từ chối thông điệp assistant với `content: []`, vì vậy
các lượt assistant đã lưu có `stopReason: "error"` và nội dung trống cũng
được sửa trên đĩa trước khi tải.
- Các lượt lỗi luồng assistant chỉ chứa các khối văn bản trống sẽ bị loại
khỏi bản sao phát lại trong bộ nhớ thay vì phát lại một khối trống không hợp lệ.
- Các khối thinking Claude bị thiếu, trống, hoặc có chữ ký phát lại chỉ gồm khoảng trắng sẽ
bị loại bỏ trước khi phát lại Converse. Nếu việc đó làm trống một lượt assistant, OpenClaw
giữ hình dạng lượt với văn bản reasoning bị lược bỏ không trống.
- Các lượt assistant chỉ có thinking cũ hơn phải bị loại bỏ được thay bằng
văn bản reasoning bị lược bỏ không trống để phát lại Converse giữ hình dạng lượt nghiêm ngặt.
- Phát lại lọc các lượt assistant delivery-mirror và do gateway chèn của OpenClaw.
- Làm sạch hình ảnh áp dụng qua quy tắc toàn cục.
**Mistral (bao gồm phát hiện dựa trên model-id)**
- Làm sạch id lệnh gọi công cụ: strict9 (chữ và số dài 9).
- Làm sạch id lệnh gọi công cụ: strict9 (chữ và số độ dài 9).
**OpenRouter Gemini**
- Dọn dẹp chữ ký suy nghĩ: loại bỏ các giá trị `thought_signature` không phải base64 (giữ lại base64).
- Dọn dẹp chữ ký suy nghĩ: loại bỏ các giá trị `thought_signature` không phải base64 (giữ base64).
**OpenRouter Anthropic**
- Các lượt điền sẵn trợ lý ở cuối bị loại khỏi payload mô hình Anthropic
tương thích OpenAI của OpenRouter đã được xác minh khi reasoning được bật, khớp với
hành vi phát lại Anthropic trực tiếp và Cloudflare Anthropic.
- Các lượt assistant prefill ở cuối bị loại khỏi payload mô hình Anthropic tương thích OpenAI
đã xác minh của OpenRouter khi reasoning được bật, khớp với hành vi phát lại
Anthropic trực tiếp và Cloudflare Anthropic.
**Mọi thứ khác**
@ -198,18 +199,18 @@ liên phiên đã lưu cũ hơn chỉ có siêu dữ liệu nguồn gốc.
Trước bản phát hành 2026.1.22, OpenClaw áp dụng nhiều lớp vệ sinh bản ghi hội thoại:
- Một **transcript-sanitize extension** chạy trên mỗi lần xây dựng ngữ cảnh và có thể:
- Sửa chữa ghép cặp dùng công cụ/kết quả.
- Làm sạch id lệnh gọi công cụ (bao gồm một chế độ không nghiêm ngặt giữ lại `_`/`-`).
- Runner cũng thực hiện làm sạch dành riêng cho nhà cung cấp, gây trùng lặp công việc.
- Các đột biến bổ sung xảy ra ngoài chính sách nhà cung cấp, bao gồm:
- Loại bỏ thẻ `<final>` khỏi văn bản trợ lý trước khi lưu.
- Loại bỏ các lượt lỗi trợ lý trống.
- Cắt bớt nội dung trợ lý sau lệnh gọi công cụ.
- Một **transcript-sanitize extension** chạy trên mọi lần xây dựng ngữ cảnh và có thể:
- Sửa chữa ghép cặp sử dụng/kết quả công cụ.
- Làm sạch id lệnh gọi công cụ (bao gồm chế độ không nghiêm ngặt giữ lại `_`/`-`).
- Runner cũng thực hiện làm sạch dành riêng cho nhà cung cấp, dẫn đến trùng lặp công việc.
- Các đột biến bổ sung xảy ra bên ngoài chính sách nhà cung cấp, bao gồm:
- Loại bỏ thẻ `<final>` khỏi văn bản assistant trước khi lưu.
- Loại bỏ các lượt lỗi assistant trống.
- Cắt bớt nội dung assistant sau các lệnh gọi công cụ.
Sự phức tạp này đã gây ra hồi quy xuyên nhà cung cấp (đáng chú ý là ghép cặp `openai-responses`
`call_id|fc_id`). Lần dọn dẹp 2026.1.22 đã loại bỏ extension, tập trung hóa
logic trong runner và khiến OpenAI **không chạm tới** ngoài việc làm sạch hình ảnh.
Độ phức tạp này gây ra hồi quy giữa các nhà cung cấp (đáng chú ý là ghép cặp `call_id|fc_id`
của `openai-responses`). Đợt dọn dẹp 2026.1.22 đã loại bỏ extension, tập trung hóa
logic trong runner, và khiến OpenAI **không bị chạm tới** ngoài việc làm sạch hình ảnh.
## Liên quan

149
docs/vi/security/network-proxy.md
View File

@ -1,69 +1,70 @@
---
read_when:
- Bạn muốn phòng thủ theo chiều sâu trước các cuộc tấn công SSRF và DNS rebinding
- 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 của môi trường chạy OpenClaw qua proxy lọc do người vận hành quản lý
- Cấu hình proxy chuyển tiếp bên ngoài cho lưu lượng khi chạy của OpenClaw
summary: Cách định tuyến lưu lượng HTTP và WebSocket của runtime 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-04T07:06:23Z"
generated_at: "2026-05-05T01:50:35Z"
model: gpt-5.5
provider: openai
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
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 operator quản lý. Đây là lớp phòng thủ bổ sung tùy chọn cho các triển khai muốn kiểm soát egress 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 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ủ bổ sung 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 đóng gói, 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 quy trình thông thường qua proxy đó.
## Vì sao nên dùng proxy?
Proxy cung cấp cho operator 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 tăng cường chống SSRF:
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ố SSRF:
- Chính sách tập trung: duy trì một chính sách egress thay vì phụ thuộc 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 upstream.
- Phòng thủ 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ế.
- Phạm vi 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 đi.
- 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 egress.
- 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 allowlist outbound mà không cần build 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 đ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 lên thượng nguồn.
- Phòng thủ DNS rebinding: giảm khoảng cách giữa bước kiểm tra DNS ở cấp ứng dụng và kết nối đi ra thực tế.
- Phạm vi 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à các máy khách 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 đầ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à một rào chắn cấp tiến trình cho egress HTTP và WebSocket thông thường. Nó cung cấp cho operator một đường đi đóng khi lỗi để đị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 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à một lan can bảo vệ ở cấp quy 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 đóng khi lỗi để định tuyến các máy khách HTTP JavaScript được hỗ trợ qua proxy lọc riêng của họ, nhưng nó 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à một 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 egress HTTP và WebSocket thông thường qua proxy đã cấu hình:
Khi `proxy.enabled=true` và URL proxy đã được cấu hình, các quy trình runtime được bảo vệ như `openclaw gateway run`, `openclaw node run` và `openclaw agent --local` sẽ định tuyến lưu lượng HTTP và WebSocket đi ra thông thường qua proxy đã cấu hình:
```text
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
Quy trình OpenClaw
fetch -> proxy lọc do người vận hành quản lý -> internet công cộng
node:http and https -> proxy lọc do người vận hành quản lý -> internet công cộng
WebSocket clients -> proxy lọc do người vận hành quản lý -> internet công cộng
```
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 của mặt phẳng điều khiển 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 IP loopback dạng chữ 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 operator 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 OpenClaw Gateway dùng một đường dẫn trực tiếp hẹp cho lưu lượng RPC Gateway local loopback khi URL Gateway dùng `localhost` hoặc 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ó khả năng tiếp cận 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.
Ở bên trong, OpenClaw dùng hai hook định tuyến cấp tiến trình cho tính năng này:
Nội bộ, OpenClaw dùng hai hook định tuyến ở cấp quy 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 caller Node core `node:http` và `node:https`, bao gồm nhiều thư viện được xây 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 operator.
- Định tuyến dispatcher của Undici bao phủ `fetch`, các máy khách 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 caller Node core `node:http` và `node:https`, bao gồm nhiều thư viện được xếp lớp trên `http.request`, `https.request`, `http.get` và `https.get`. Chế độ proxy được quản lý bắt buộc dùng global agent đó để các Node HTTP agent 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 dây 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à vì vậy tôn trọng env proxy của tiến trình cùng fallback `OPENCLAW_PROXY_URL` được quản lý trong đường transport dành riêng cho chủ sở hữu đó.
Một số plugin sở hữu transport tùy chỉnh cần nối proxy rõ ràng ngay cả khi đã có định tuyến ở cấp quy trình. Ví dụ: transport Bot API của Telegram dùng dispatcher HTTP/1 undici riêng và do đó tôn trọng env proxy của quy trình cộng với fallback `OPENCLAW_PROXY_URL` được quản lý trong đường dẫn transport thuộc 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`.
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, vì vậy để `localhost` hoặc `127.0.0.1` trong đó sẽ cho phép các mục tiêu SSRF rủi ro cao bỏ qua proxy lọc.
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` ở đó thì các mục tiêu SSRF rủi ro cao có thể bỏ qua proxy lọc.
Khi tắt, OpenClaw khôi phục môi trường proxy trước đó và đặt lại trạng thái định tuyến tiến trình đã lưu cache.
Khi tắt, OpenClaw khôi phục môi trường proxy trước đó và đặt lại trạng thái định tuyến quy trình đã lưu trong bộ nhớ đệm.
## Các thuật ngữ proxy liên quan
## Thuật ngữ proxy liên quan
- `proxy.enabled` / `proxy.proxyUrl`: định tuyến proxy chuyển tiếp outbound cho egress 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 inbound cho quyền truy cập Gateway. Xem [Xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth).
- `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 proxy ngược nhận biết danh tính 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 capture cho phát triển và hỗ trợ. Xem [openclaw proxy](/vi/cli/proxy).
- Cài đặt proxy dành riêng cho channel hoặc provider: các override dành riêng cho chủ sở hữu đối với 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 egress tập trung trên toàn runtime.
- `tools.web.fetch.useTrustedEnvProxy`: tùy chọn bật cho `web_fetch` để cho phép proxy env HTTP(S) do người vận hành kiểm soát phân giải DNS trong khi vẫn giữ ghim DNS nghiêm ngặt mặc định và chính sách hostname. Xem [Web fetch](/vi/tools/web-fetch#trusted-env-proxy).
- Cài đặt proxy riêng theo kênh hoặc nhà cung cấp: các ghi đè thuộc sở hữu cụ thể 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 đầu ra tập trung trên toàn runtime.
## Cấu hình
@ -81,7 +82,7 @@ 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ẽ không 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:
@ -92,51 +93,51 @@ openclaw gateway install --force
openclaw gateway start
```
Fallback môi trường phù hợp nhất cho các lần chạy foreground. 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 như `$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ị đó.
Fallback môi trường phù hợp nhất cho các lần chạy foreground. 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 override 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 có thể truy cập từ bên trong container; `127.0.0.1` trỏ tới chính container, không phải host. 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 bước kiểm tra an toàn đó.
## Yêu cầu 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 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 các mục tiêu cần chặn.
Cấu hình proxy để:
- Chỉ bind vào loopback hoặc một interface riêng tư đá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ụ 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ỉ quy trình, host, 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 bypass dựa trên đích cho loopback, private, link-local, metadata, multicast, reserved hoặc các dải documentation.
- Tránh allowlist hostname trừ khi bạn hoàn toàn tin tưởng đường 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 bí mật khác.
- Đưa chính sách proxy vào quản lý phiên bản và review các 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 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 body yêu cầu, header ủy quyền, cookie hoặc các bí mật khác.
- Giữ chính sách proxy trong hệ thống quản lý 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 bị chặn được khuyến nghị
Dùng denylist này làm điểm bắt đầu cho bất kỳ proxy chuyển tiếp, tường lửa hoặc chính sách egress nào.
Dùng denylist 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 đầu ra nào.
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. Các tệp đó là tham chiếu hữu ích khi bảo 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 thích liên quan là `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX`, và phần xử lý sentinel IPv4 nhúng cho NAT64, 6to4, Teredo, ISATAP và các dạng ánh xạ IPv4. 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.
| Dải hoặc host | Lý do chặn |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
| `::1/128` | IPv6 loopback |
| `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à đường metadata cloud phổ biến |
| `169.254.169.254`, `metadata.google.internal` | Dịch vụ metadata cloud |
| `100.64.0.0/10` | Không gian địa chỉ dùng chung của carrier-grade NAT |
| `198.18.0.0/15`, `2001:2::/48` | Dải benchmarking |
| `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à documentation |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reserved |
| `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 host | Lý do chặn |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
| `::1/128` | IPv6 loopback |
| `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 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 benchmarking |
| `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 reserved |
| `fc00::/7`, `fec0::/10` | Dải IPv6 cục bộ/riêng tư |
| `100::/64`, `2001:20::/28` | Dải IPv6 discard và ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Tiền tố NAT64 có IPv4 nhúng |
| `2002::/16`, `2001::/32` | 6to4 và Teredo có 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 cloud hoặc nền tảng mạng của bạn ghi lại thêm host metadata hoặc dải reserved, hãy thêm cả các mục đó.
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 reserved, hãy thêm cả những mục đó.
## Xác thực
@ -146,9 +147,9 @@ Xác thực proxy từ cùng host, container hoặc tài khoản dịch vụ ch
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, xác thực báo cáo vấn đề cấu hình; dùng `--proxy-url` cho một preflight một lần 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 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 tiếp cận. Kiểm tra bị từ chối mặc định sẽ đạ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; nó thất bại nếu 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 sự cố cấu hình; dùng `--proxy-url` để preflight một lần trước khi thay đổi cấu hình. Dùng `--allowed-url` và `--denied-url` để kiểm tra các kỳ vọng riêng của triển khai. Thêm `--apns-reachable` để cũng xác minh việc gửi APNs HTTP/2 trực tiếp có thể mở tunnel CONNECT qua proxy và nhận phản hồi sandbox APNs; probe dùng token nhà cung cấp cố ý không hợp lệ, nên `403 InvalidProviderToken` là kết quả được kỳ vọng và được tính là có thể tiếp cận. Các đích bị từ chối tùy chỉnh là đóng khi lỗi: bất kỳ phản hồi HTTP nào cũng có nghĩa là đích có thể tiếp cận qua proxy, và bất kỳ lỗi transport nào cũng đượ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ể tiếp cận. 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 đăng nhập trong 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 có 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 biên tập ẩn trong đầu ra dạng văn bản và JSON:
```json
{
@ -165,6 +166,12 @@ Dùng `--json` cho tự động hóa. Đầu ra JSON chứa kết quả tổng t
"url": "https://example.com/",
"ok": true,
"status": 200
},
{
"kind": "apns",
"url": "https://api.sandbox.push.apple.com",
"ok": true,
"status": 403
}
]
}
@ -178,9 +185,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. Với `openclaw proxy validate`, canary loopback tích hợp 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 không rõ ràng 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 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 vòng lặp và metadata sẽ bị proxy chặn. Với `openclaw proxy validate`, canary vòng lặp tích hợp sẵn có thể phân biệt việc proxy từ chối với một nguồn có thể truy cập được. 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 và các 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 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.
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,11 +205,11 @@ 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 đây 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.
- IRC là kênh TCP/TLS thô nằm ngoài định tuyến forward proxy do operator quản lý. Trong các triển khai yêu cầu mọi lưu lượng đi ra đều đi qua forward proxy đó, 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.
- Proxy gỡ lỗi cục bộ là công cụ chẩn đoán, và việc chuyển tiếp upstream trực tiếp của nó cho các yêu cầu proxy và đường hầm CONNECT bị tắt theo mặc định khi chế độ proxy được quản lý đang hoạt động; chỉ bật chuyển tiếp trực tiếp cho các chẩn đoán cục bộ đã được phê duyệt.
- 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 allowlist 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ộ chung cho chúng.
- Việc bỏ qua proxy cho mặt phẳng điều khiển Gateway được chủ ý giới hạn ở `localhost` và các URL IP loopback dạng literal. Sử 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 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.
- Proxy cải thiện phạm vi bao phủ cho các ứng dụng khách HTTP JavaScript và WebSocket 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.
- IRC là một kênh TCP/TLS thô nằm ngoài định tuyến proxy chuyển tiếp do người vận hành 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.
- Proxy gỡ lỗi cục bộ là công cụ chẩn đoán và tính năng chuyển tiếp trực tiếp upstream cho các yêu cầu proxy và đường hầm CONNECT bị tắt theo mặc định khi chế độ proxy được quản lý đang hoạt động; chỉ bật chuyển tiếp trực tiếp cho các chẩn đoán cục bộ đã được phê duyệt.
- 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ộ tổng quát cho chúng.
- Việc bỏ qua proxy cho mặt phẳng điều khiển của Gateway được cố ý giới hạn ở `localhost` và các URL IP vòng lặp 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 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 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à thay đổi vận hành nhạy cảm về bảo mật.

73
docs/vi/tools/loop-detection.md
View File

@ -1,33 +1,33 @@
---
read_when:
- Người dùng báo cáo các tác nhân bị kẹt khi lặp lại các lệnh gọi công cụ
- Người dùng báo cáo rằng các tác tử bị kẹt khi lặp lại các lệnh gọi công cụ
- Bạn cần tinh chỉnh cơ chế bảo vệ chống lệnh gọi lặp lại
- Bạn đang chỉnh sửa chính sách công cụ/thời gian chạy của tác nhân
summary: Cách bật và tinh chỉnh các cơ chế bảo vệ phát hiện vòng lặp gọi công cụ lặp đi lặp lại
- Bạn đang chỉnh sửa các chính sách công cụ/thời gian chạy của tác nhân
summary: Cách bật và tinh chỉnh cơ chế bảo vệ phát hiện các vòng lặp gọi công cụ lặp lại
title: Phát hiện vòng lặp công cụ
x-i18n:
generated_at: "2026-05-03T21:37:18Z"
generated_at: "2026-05-05T01:51:17Z"
model: gpt-5.5
provider: openai
source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
source_path: tools/loop-detection.md
workflow: 16
---
OpenClaw có thể ngăn các tác tử bị kẹt trong các mẫu gọi công cụ lặp lại.
OpenClaw có thể ngăn tác tử bị kẹt trong các mẫu lệnh gọi công cụ lặp lại.
Cơ chế bảo vệ này **bị tắt theo mặc định**.
Chỉ bật ở nơi cần thiết, vì với thiết lập nghiêm ngặt, cơ chế này có thể chặn các lệnh gọi lặp lại hợp lệ.
## Vì sao cơ chế này tồn tại
- Phát hiện các chuỗi lặp lại không tạo tiến triển.
- Phát hiện các vòng lặp tần suất cao không có kết quả (cùng công cụ, cùng đầu vào, lỗi lặp lại).
- Phát hiện các mẫu gọi lặp lại cụ thể cho các công cụ thăm dò đã biết.
- Phát hiện các chuỗi lặp lại không tạo ra tiến triển.
- Phát hiện vòng lặp tần suất cao không có kết quả (cùng công cụ, cùng đầu vào, lỗi lặp lại).
- Phát hiện các mẫu lệnh gọi lặp lại cụ thể cho các công cụ thăm dò đã biết.
## Khối cấu hình
Mặc định toàn cục:
Giá trị mặc định toàn cục:
```json5
{
@ -48,7 +48,7 @@ Mặc định toàn cục:
}
```
Ghi đè theo từng tác tử (tùy chọn):
Ghi đè theo từng tác tử (không bắt buộc):
```json5
{
@ -78,37 +78,60 @@ Ghi đè theo từng tác tử (tùy chọn):
- `globalCircuitBreakerThreshold`: ngưỡng ngắt mạch toàn cục khi không có tiến triển.
- `detectors.genericRepeat`: phát hiện các mẫu lặp lại cùng công cụ + cùng tham số.
- `detectors.knownPollNoProgress`: phát hiện các mẫu giống thăm dò đã biết mà không có thay đổi trạng thái.
- `detectors.pingPong`: phát hiện các mẫu ping-pong xen kẽ.
- `detectors.pingPong`: phát hiện các mẫu ping-pong luân phiên.
Đối với `exec`, các kiểm tra không có tiến triển so sánh kết quả lệnh ổn định và bỏ qua siêu dữ liệu thời gian chạy dễ biến động như thời lượng, PID, ID phiên và thư mục làm việc.
Khi có id lần chạy, lịch sử gọi công cụ gần đây chỉ được đánh giá trong lần chạy đó, để các chu kỳ Heartbeat đã lên lịch và các lần chạy mới không kế thừa số lần đếm vòng lặp cũ từ những lần chạy trước.
Đối với `exec`, kiểm tra không có tiến triển so sánh các kết quả lệnh ổn định và bỏ qua siêu dữ liệu thời gian chạy dễ biến động như thời lượng, PID, ID phiên và thư mục làm việc.
Khi có ID lượt chạy, lịch sử lệnh gọi công cụ gần đây chỉ được đánh giá trong lượt chạy đó, để các chu kỳ Heartbeat theo lịch và các lượt chạy mới không thừa hưởng bộ đếm vòng lặp cũ từ các lượt chạy trước.
## Thiết lập khuyến nghị
- Với các mô hình nhỏ hơn, hãy bắt đầu bằng `enabled: true`, giữ nguyên các giá trị mặc định. Các mô hình hàng đầu hiếm khi cần phát hiện vòng lặp và có thể để tắt.
- Giữ thứ tự ngưỡng là `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Với các mô hình nhỏ hơn, bắt đầu bằng `enabled: true`, giữ nguyên giá trị mặc định. Các mô hình hàng đầu hiếm khi cần phát hiện vòng lặp và có thể để tắt.
- Giữ các ngưỡng theo thứ tự `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Nếu xảy ra dương tính giả:
- tăng `warningThreshold` và/hoặc `criticalThreshold`
- (tùy chọn) tăng `globalCircuitBreakerThreshold`
- (không bắt buộc) tăng `globalCircuitBreakerThreshold`
- chỉ tắt bộ phát hiện gây ra vấn đề
- giảm `historySize` để bớt nghiêm ngặt về ngữ cảnh lịch sử
- giảm `historySize` để dùng ngữ cảnh lịch sử ít nghiêm ngặt hơn
## Nhật ký và hành vi dự kiến
## Cơ chế bảo vệ sau Compaction
Khi phát hiện vòng lặp, OpenClaw báo cáo một sự kiện vòng lặp và chặn hoặc làm dịu chu kỳ công cụ tiếp theo tùy theo mức độ nghiêm trọng.
Điều này bảo vệ người dùng khỏi chi phí token mất kiểm soát và tình trạng khóa cứng, đồng thời vẫn duy trì quyền truy cập công cụ bình thường.
Khi trình chạy hoàn tất một lần tự động thử lại sau Compaction (sau khi tràn ngữ cảnh), nó kích hoạt một cơ chế bảo vệ trong cửa sổ ngắn để theo dõi vài lệnh gọi công cụ tiếp theo. Nếu tác tử phát ra bộ ba `(toolName, args, result)` _giống nhau_ nhiều lần trong cửa sổ đó, cơ chế bảo vệ kết luận rằng Compaction không phá vỡ được vòng lặp và hủy lượt chạy với lỗi `compaction_loop_persisted`.
- Ưu tiên cảnh báo và tạm thời kìm hãm trước.
- Chỉ nâng mức khi bằng chứng lặp lại tích lũy.
Đây là một đường mã riêng với các bộ phát hiện `tools.loopDetection` toàn cục. Nó có thể được cấu hình độc lập:
```json5
{
tools: {
loopDetection: {
enabled: true, // existing master switch; set false to disable loop guards
postCompactionGuard: {
windowSize: 3, // default: 3
},
},
},
}
```
- `windowSize`: số lệnh gọi công cụ sau Compaction mà cơ chế bảo vệ vẫn được kích hoạt _và_ số bộ ba (công cụ, đối số, kết quả) giống hệt nhau sẽ kích hoạt hủy.
Cơ chế bảo vệ không bao giờ hủy khi kết quả đang thay đổi, chỉ hủy khi kết quả giống hệt từng byte trong toàn bộ cửa sổ. Cơ chế này được cố ý giới hạn hẹp: nó chỉ kích hoạt ngay sau một lần thử lại Compaction.
## Nhật ký và hành vi mong đợi
Khi phát hiện vòng lặp, OpenClaw báo cáo một sự kiện vòng lặp và chặn hoặc giảm cường độ chu kỳ công cụ tiếp theo tùy theo mức độ nghiêm trọng.
Điều này bảo vệ người dùng khỏi tiêu tốn token mất kiểm soát và treo hệ thống, đồng thời vẫn duy trì quyền truy cập công cụ bình thường.
- Ưu tiên cảnh báo và tạm thời chặn trước.
- Chỉ leo thang khi bằng chứng lặp lại tích lũy.
## Ghi chú
- `tools.loopDetection` được hợp nhất với các ghi đè cấp tác tử.
- `tools.loopDetection` được hợp nhất với các ghi đè ở cấp tác tử.
- Cấu hình theo từng tác tử ghi đè hoàn toàn hoặc mở rộng các giá trị toàn cục.
- Nếu không có cấu hình, các cơ chế bảo vệ vẫn tắt.
## Liên quan
- [Phê duyệt exec](/vi/tools/exec-approvals)
- [Mức độ suy nghĩ](/vi/tools/thinking)
- [Mức suy nghĩ](/vi/tools/thinking)
- [Tác tử phụ](/vi/tools/subagents)

125
docs/vi/tools/media-overview.md
View File

@ -1,58 +1,58 @@
---
read_when:
- Tìm kiếm thông tin tổng quan về các khả năng đa phương tiện của OpenClaw
- Tìm tổng quan về các khả năng xử lý phương tiện của OpenClaw
- Quyết định nhà cung cấp phương tiện nào cần cấu hình
- Tìm hiểu cách hoạt động của việc tạo nội dung đa phương tiện bất đồng bộ
- Tìm hiểu cách hoạt động của quá trình tạo nội dung đa phương tiện bất đồng bộ
sidebarTitle: Media overview
summary: Tổng quan về các khả năng xử lý hình ảnh, video, âm nhạc, giọng nói và hiểu nội dung đa phương tiện
title: Tổng quan về đa phương tiện
summary: Tổng quan về các khả năng hình ảnh, video, âm nhạc, giọng nói và hiểu nội dung đa phương tiện
title: Tổng quan về nội dung đa phương tiện
x-i18n:
generated_at: "2026-04-29T23:19:50Z"
generated_at: "2026-05-05T01:51:35Z"
model: gpt-5.5
provider: openai
source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_path: tools/media-overview.md
workflow: 16
---
OpenClaw tạo hình ảnh, video và nhạc, hiểu phương tiện đến
OpenClaw tạo hình ảnh, video và nhạc, hiểu nội dung đa phương tiện nhận vào
(hình ảnh, âm thanh, video), và đọc to câu trả lời bằng chuyển văn bản thành giọng nói. Tất cả
năng lực phương tiện đều được điều khiển bằng công cụ: agent quyết định khi nào dùng chúng dựa
khả năng về nội dung đa phương tiện đều được điều khiển bằng công cụ: tác nhân quyết định khi nào dùng chúng dựa
trên cuộc trò chuyện, và mỗi công cụ chỉ xuất hiện khi có ít nhất một
nhà cung cấp nền được cấu hình.
nhà cung cấp hỗ trợ được cấu hình.
## Năng lực
## Khả năng
<CardGroup cols={2}>
<Card title="Image generation" href="/vi/tools/image-generation" icon="image">
Tạo và chỉnh sửa hình ảnh từ lời nhắc văn bản hoặc hình ảnh tham chiếu qua
`image_generate`. Đồng bộ — hoàn tất nội tuyến cùng câu trả lời.
<Card title="Tạo hình ảnh" href="/vi/tools/image-generation" icon="image">
Tạo và chỉnh sửa hình ảnh từ prompt văn bản hoặc hình ảnh tham chiếu qua
`image_generate`. Đồng bộ — hoàn tất ngay trong câu trả lời.
</Card>
<Card title="Video generation" href="/vi/tools/video-generation" icon="video">
Văn bản sang video, hình ảnh sang video và video sang video qua `video_generate`.
<Card title="Tạo video" href="/vi/tools/video-generation" icon="video">
Văn bản thành video, hình ảnh thành video và video thành video qua `video_generate`.
Bất đồng bộ — chạy trong nền và đăng kết quả khi sẵn sàng.
</Card>
<Card title="Music generation" href="/vi/tools/music-generation" icon="music">
Tạo nhạc hoặc bản âm thanh qua `music_generate`. Bất đồng bộ trên các nhà cung cấp
dùng chung; đường dẫn quy trình ComfyUI chạy đồng bộ.
<Card title="Tạo nhạc" href="/vi/tools/music-generation" icon="music">
Tạo nhạc hoặc bản âm thanh qua `music_generate`. Bất đồng bộ trên các
nhà cung cấp dùng chung; đường dẫn quy trình ComfyUI chạy đồng bộ.
</Card>
<Card title="Text-to-speech" href="/vi/tools/tts" icon="microphone">
Chuyển câu trả lời gửi đi thành âm thanh nói qua công cụ `tts` cộng với
<Card title="Chuyển văn bản thành giọng nói" href="/vi/tools/tts" icon="microphone">
Chuyển câu trả lời gửi ra thành âm thanh lời nói qua công cụ `tts` cùng
cấu hình `messages.tts`. Đồng bộ.
</Card>
<Card title="Media understanding" href="/vi/nodes/media-understanding" icon="eye">
Tóm tắt hình ảnh, âm thanh và video đến bằng các nhà cung cấp mô hình
có khả năng thị giác và các plugin hiểu phương tiện chuyên dụng.
<Card title="Hiểu nội dung đa phương tiện" href="/vi/nodes/media-understanding" icon="eye">
Tóm tắt hình ảnh, âm thanh và video nhận vào bằng các nhà cung cấp mô hình
có khả năng thị giác và các Plugin chuyên dụng để hiểu nội dung đa phương tiện.
</Card>
<Card title="Speech-to-text" href="/vi/nodes/audio" icon="ear-listen">
Chép lời tin nhắn thoại đến thông qua các nhà cung cấp STT theo lô hoặc
STT truyền phát Cuộc gọi thoại.
<Card title="Chuyển lời nói thành văn bản" href="/vi/nodes/audio" icon="ear-listen">
Phiên âm tin nhắn thoại nhận vào thông qua nhà cung cấp STT theo lô hoặc
STT truyền phát cho Cuộc gọi thoại.
</Card>
</CardGroup>
## Ma trận năng lực của nhà cung cấp
## Ma trận khả năng của nhà cung cấp
| Nhà cung cấp | Hình ảnh | Video | Nhạc | TTS | STT | Giọng nói thời gian thực | Hiểu phương tiện |
| Nhà cung cấp | Hình ảnh | Video | Nhạc | TTS | STT | Giọng nói thời gian thực | Hiểu nội dung đa phương tiện |
| ----------- | :---: | :---: | :---: | :-: | :-: | :------------: | :-----------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
@ -63,7 +63,7 @@ nhà cung cấp nền được cấu hình.
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| Local CLI | | | | ✓ | | | |
| CLI cục bộ | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
@ -78,63 +78,64 @@ nhà cung cấp nền được cấu hình.
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
Hiểu phương tiện dùng bất kỳ mô hình có khả năng thị giác hoặc âm thanh nào được đăng ký
trong cấu hình nhà cung cấp của bạn. Ma trận trên liệt kê các nhà cung cấp có hỗ trợ
hiểu phương tiện chuyên dụng; hầu hết nhà cung cấp LLM đa phương thức (Anthropic, Google,
OpenAI, v.v.) cũng có thể hiểu phương tiện đến khi được cấu hình làm mô hình
trả lời đang hoạt động.
Hiểu nội dung đa phương tiện dùng bất kỳ mô hình có khả năng thị giác hoặc âm thanh nào được đăng ký
trong cấu hình nhà cung cấp của bạn. Ma trận ở trên liệt kê các nhà cung cấp có hỗ trợ
hiểu nội dung đa phương tiện chuyên dụng; hầu hết nhà cung cấp LLM đa phương thức (Anthropic, Google,
OpenAI, v.v.) cũng có thể hiểu nội dung đa phương tiện nhận vào khi được cấu hình làm
mô hình trả lời đang hoạt động.
</Note>
## Bất đồng bộ so với đồng bộ
| Năng lực | Chế độ | Lý do |
| Khả năng | Chế độ | Lý do |
| --------------- | ------------ | ------------------------------------------------------------------ |
| Hình ảnh | Đồng bộ | Phản hồi của nhà cung cấp trả về trong vài giây; hoàn tất nội tuyến cùng câu trả lời. |
| Chuyển văn bản thành giọng nói | Đồng bộ | Phản hồi của nhà cung cấp trả về trong vài giây; được đính kèm vào âm thanh câu trả lời. |
| Video | Bất đồng bộ | Quá trình xử lý của nhà cung cấp mất 30 giây đến vài phút. |
| Nhạc (dùng chung) | Bất đồng bộ | Cùng đặc tính xử lý phía nhà cung cấp như video. |
| Nhạc (ComfyUI) | Đồng bộ | Quy trình cục bộ chạy nội tuyến với máy chủ ComfyUI đã cấu hình. |
| Hình ảnh | Đồng bộ | Phản hồi của nhà cung cấp trả về trong vài giây; hoàn tất ngay trong câu trả lời. |
| Chuyển văn bản thành giọng nói | Đồng bộ | Phản hồi của nhà cung cấp trả về trong vài giây; được đính kèm vào âm thanh câu trả lời. |
| Video | Bất đồng bộ | Quá trình xử lý của nhà cung cấp mất từ 30 giây đến vài phút. |
| Nhạc (dùng chung) | Bất đồng bộ | Có cùng đặc điểm xử lý phía nhà cung cấp như video. |
| Nhạc (ComfyUI) | Đồng bộ | Quy trình cục bộ chạy ngay với máy chủ ComfyUI đã cấu hình. |
Đối với công cụ bất đồng bộ, OpenClaw gửi yêu cầu đến nhà cung cấp, trả về mã tác vụ
ngay lập tức và theo dõi công việc trong sổ cái tác vụ. Agent tiếp tục
Đối với công cụ bất đồng bộ, OpenClaw gửi yêu cầu đến nhà cung cấp, trả về id tác vụ
ngay lập tức, và theo dõi công việc trong sổ cái tác vụ. Tác nhân tiếp tục
phản hồi các tin nhắn khác trong khi công việc chạy. Khi nhà cung cấp hoàn tất,
OpenClaw đánh thức agent để có thể đăng phương tiện đã hoàn thành trở lại
kênh ban đầu.
OpenClaw đánh thức tác nhân với các đường dẫn nội dung đa phương tiện đã tạo để nó có thể báo cho
người dùng và, khi chính sách phân phối nguồn yêu cầu, chuyển tiếp kết quả qua
công cụ nhắn tin.
## Chuyển giọng nói thành văn bản và Cuộc gọi thoại
## Chuyển lời nói thành văn bản và Cuộc gọi thoại
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio và xAI đều có thể chép lời
âm thanh đến thông qua đường dẫn `tools.media.audio` theo lô khi được cấu hình.
Các plugin kênh kiểm tra trước một ghi chú thoại để cổng nhắc đến hoặc phân tích
lệnh sẽ đánh dấu tệp đính kèm đã chép lời trên ngữ cảnh đến, để lượt
hiểu phương tiện dùng chung tái sử dụng bản chép lời đó thay vì thực hiện cuộc gọi
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio và xAI đều có thể phiên âm
âm thanh nhận vào qua đường dẫn `tools.media.audio` theo lô khi được cấu hình.
Các Plugin kênh kiểm tra trước ghi chú thoại để gác cổng lượt nhắc đến hoặc phân tích cú pháp
lệnh sẽ đánh dấu tệp đính kèm đã phiên âm trên ngữ cảnh nhận vào, để lượt
hiểu nội dung đa phương tiện dùng chung tái sử dụng bản phiên âm đó thay vì thực hiện lệnh gọi
STT thứ hai cho cùng âm thanh.
Deepgram, ElevenLabs, Mistral, OpenAI và xAI cũng đăng ký các nhà cung cấp
STT truyền phát Cuộc gọi thoại, để âm thanh điện thoại trực tiếp có thể được chuyển tiếp đến
STT truyền phát cho Cuộc gọi thoại, để âm thanh điện thoại trực tiếp có thể được chuyển tiếp đến
nhà cung cấp đã chọn mà không cần chờ bản ghi hoàn tất.
## Ánh xạ nhà cung cấp (cách nhà cung cấp phân chia giữa các bề mặt)
## Ánh xạ nhà cung cấp (cách các nhà cung cấp tách theo bề mặt)
<AccordionGroup>
<Accordion title="Google">
Các bề mặt hình ảnh, video, nhạc, TTS theo lô, giọng nói thời gian thực phía backend và
hiểu phương tiện.
Các bề mặt hình ảnh, video, nhạc, TTS theo lô, giọng nói thời gian thực ở backend và
hiểu nội dung đa phương tiện.
</Accordion>
<Accordion title="OpenAI">
Các bề mặt hình ảnh, video, TTS theo lô, STT theo lô, STT truyền phát Cuộc gọi thoại, giọng nói
thời gian thực phía backend và nhúng bộ nhớ.
Các bề mặt hình ảnh, video, TTS theo lô, STT theo lô, STT truyền phát cho Cuộc gọi thoại, giọng nói
thời gian thực ở backend và embedding bộ nhớ.
</Accordion>
<Accordion title="DeepInfra">
Các bề mặt định tuyến trò chuyện/mô hình, tạo/chỉnh sửa hình ảnh, văn bản sang video, TTS theo lô,
STT theo lô, hiểu phương tiện hình ảnh và nhúng bộ nhớ.
Các mô hình xếp hạng lại/phân loại/phát hiện đối tượng gốc DeepInfra không được
Các bề mặt định tuyến chat/mô hình, tạo/chỉnh sửa hình ảnh, văn bản thành video, TTS theo lô,
STT theo lô, hiểu nội dung hình ảnh và embedding bộ nhớ.
Các mô hình rerank/phân loại/phát hiện đối tượng gốc của DeepInfra chưa được
đăng ký cho đến khi OpenClaw có hợp đồng nhà cung cấp chuyên dụng cho các
danh mục đó.
</Accordion>
<Accordion title="xAI">
Hình ảnh, video, tìm kiếm, thực thi mã, TTS theo lô, STT theo lô và STT truyền phát
Cuộc gọi thoại. Giọng nói thời gian thực xAI là một năng lực phía upstream nhưng
Hình ảnh, video, tìm kiếm, thực thi mã, TTS theo lô, STT theo lô và STT truyền phát cho Cuộc gọi
thoại. Giọng nói thời gian thực của xAI là một khả năng thượng nguồn nhưng
chưa được đăng ký trong OpenClaw cho đến khi hợp đồng giọng nói thời gian thực dùng chung có thể
biểu diễn nó.
</Accordion>
@ -146,5 +147,5 @@ nhà cung cấp đã chọn mà không cần chờ bản ghi hoàn tất.
- [Tạo video](/vi/tools/video-generation)
- [Tạo nhạc](/vi/tools/music-generation)
- [Chuyển văn bản thành giọng nói](/vi/tools/tts)
- [Hiểu phương tiện](/vi/nodes/media-understanding)
- [Hiểu nội dung đa phương tiện](/vi/nodes/media-understanding)
- [Nút âm thanh](/vi/nodes/audio)

191
docs/vi/tools/music-generation.md
View File

@ -1,46 +1,47 @@
---
read_when:
- Tạo nhạc hoặc âm thanh thông qua tác nhân
- Cấu hình các nhà cung cấp và mô hình tạo nhạc
- Tạo nhạc hoặc âm thanh thông qua tác tử
- Cấu hình nhà cung cấp và mô hình tạo nhạc
- Tìm hiểu các tham số của công cụ music_generate
sidebarTitle: Music generation
summary: Tạo nhạc thông qua music_generate trên các quy trình làm việc Google Lyria, MiniMax và ComfyUI
summary: Tạo nhạc qua music_generate trong các quy trình làm việc của Google Lyria, MiniMax và ComfyUI
title: Tạo nhạc
x-i18n:
generated_at: "2026-05-02T10:55:44Z"
generated_at: "2026-05-05T01:51:34Z"
model: gpt-5.5
provider: openai
source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_path: tools/music-generation.md
workflow: 16
---
Công cụ `music_generate` cho phép agent tạo nhạc hoặc âm thanh thông qua
năng lực tạo nhạc dùng chung với các nhà cung cấp đã cấu hình — Google,
MiniMax và ComfyUI được cấu hình bằng workflow hiện nay.
Công cụ `music_generate` cho phép tác tử tạo nhạc hoặc âm thanh thông qua
năng lực tạo nhạc dùng chung với các nhà cung cấp đã cấu hình — hiện nay là
Google, MiniMax và ComfyUI được cấu hình bằng workflow.
Đối với các lần chạy agent có session hỗ trợ, OpenClaw bắt đầu tạo nhạc dưới dạng
tác vụ nền, theo dõi tác vụ đó trong sổ cái tác vụ, rồi đánh thức agent lần nữa
khi bản nhạc đã sẵn sàng để agent có thể đăng âm thanh hoàn tất trở lại
kênh ban đầu.
Đối với các lượt chạy tác tử có phiên hậu thuẫn, OpenClaw bắt đầu tạo nhạc như một
tác vụ nền, theo dõi tác vụ đó trong sổ cái tác vụ, rồi đánh thức tác tử lần nữa
khi bản nhạc đã sẵn sàng để tác tử có thể báo cho người dùng và đính kèm âm thanh
hoàn chỉnh. Trong các cuộc trò chuyện nhóm/kênh dùng cách gửi hiển thị chỉ qua công cụ tin nhắn,
tác tử chuyển tiếp kết quả thông qua công cụ tin nhắn.
<Note>
Công cụ dùng chung tích hợp sẵn chỉ xuất hiện khi có ít nhất một nhà cung cấp
tạo nhạc khả dụng. Nếu bạn không thấy `music_generate` trong các công cụ của
agent, hãy cấu hình `agents.defaults.musicGenerationModel` hoặc thiết lập
tác tử, hãy cấu hình `agents.defaults.musicGenerationModel` hoặc thiết lập một
khóa API của nhà cung cấp.
</Note>
## Bắt đầu nhanh
<Tabs>
<Tab title="Dựa trên nhà cung cấp dùng chung">
<Tab title="Shared provider-backed">
<Steps>
<Step title="Cấu hình xác thực">
<Step title="Configure auth">
Đặt khóa API cho ít nhất một nhà cung cấp — ví dụ
`GEMINI_API_KEY` hoặc `MINIMAX_API_KEY`.
</Step>
<Step title="Chọn mô hình mặc định (tùy chọn)">
<Step title="Pick a default model (optional)">
```json5
{
agents: {
@ -53,30 +54,30 @@ khóa API của nhà cung cấp.
}
```
</Step>
<Step title="Yêu cầu agent">
_"Tạo một bản nhạc synthpop sôi động về chuyến lái xe ban đêm qua
một thành phố neon."_
<Step title="Ask the agent">
_"Tạo một bản synthpop sôi động về chuyến lái xe ban đêm qua một
thành phố neon."_
Agent tự động gọi `music_generate`. Không cần thêm công cụ vào
danh sách cho phép.
Tác tử tự động gọi `music_generate`. Không cần danh sách cho phép
công cụ.
</Step>
</Steps>
Đối với các ngữ cảnh đồng bộ trực tiếp không có lần chạy agent có session
hỗ trợ, công cụ tích hợp sẵn vẫn chuyển về tạo nội tuyến và trả về
Đối với các ngữ cảnh đồng bộ trực tiếp không có lượt chạy tác tử có phiên hậu thuẫn,
công cụ tích hợp sẵn vẫn dùng phương án dự phòng tạo nội tuyến và trả về
đường dẫn phương tiện cuối cùng trong kết quả công cụ.
</Tab>
<Tab title="Workflow ComfyUI">
<Tab title="ComfyUI workflow">
<Steps>
<Step title="Cấu hình workflow">
Cấu hình `plugins.entries.comfy.config.music` với workflow
JSON và các nút prompt/output.
<Step title="Configure the workflow">
Cấu hình `plugins.entries.comfy.config.music` bằng workflow
JSON và các nút prompt/đầu ra.
</Step>
<Step title="Xác thực đám mây (tùy chọn)">
<Step title="Cloud auth (optional)">
Với Comfy Cloud, đặt `COMFY_API_KEY` hoặc `COMFY_CLOUD_API_KEY`.
</Step>
<Step title="Gọi công cụ">
<Step title="Call the tool">
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
@ -97,31 +98,31 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## Nhà cung cấp được hỗ trợ
| Nhà cung cấp | Mô hình mặc định | Đầu vào tham chiếu | Điều khiển được hỗ trợ | Xác thực |
| ------------ | ---------------------- | ------------------ | ------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Tối đa 1 hình ảnh | Nhạc hoặc âm thanh do workflow định nghĩa | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Tối đa 10 hình ảnh | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Không có | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` hoặc MiniMax OAuth |
| Nhà cung cấp | Mô hình mặc định | Đầu vào tham chiếu | Điều khiển được hỗ trợ | Xác thực |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Tối đa 1 hình ảnh | Nhạc hoặc âm thanh do workflow định nghĩa | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Tối đa 10 hình ảnh | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Không có | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` hoặc MiniMax OAuth |
### Ma trận năng lực
Hợp đồng chế độ tường minh được dùng bởi `music_generate`, kiểm thử hợp đồng và
đợt quét trực tiếp dùng chung:
Hợp đồng chế độ tường minh được `music_generate`, các kiểm thử hợp đồng và
đợt quét trực tiếp dùng chung sử dụng:
| Nhà cung cấp | `generate` | `edit` | Giới hạn chỉnh sửa | Làn kiểm thử trực tiếp dùng chung |
| ------------ | :--------: | :----: | ------------------ | ---------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 hình ảnh | Không nằm trong đợt quét dùng chung; được bao phủ bởi `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 hình ảnh | `generate`, `edit` |
| MiniMax | ✓ | — | Không có | `generate` |
| Nhà cung cấp | `generate` | `edit` | Giới hạn chỉnh sửa | Làn trực tiếp dùng chung |
| -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 hình ảnh | Không nằm trong đợt quét dùng chung; được bao phủ bởi `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 hình ảnh | `generate`, `edit` |
| MiniMax | ✓ | — | Không có | `generate` |
Dùng `action: "list"` để kiểm tra các nhà cung cấp và mô hình dùng chung
khả dụng tại thời gian chạy:
Dùng `action: "list"` để kiểm tra các nhà cung cấp và mô hình dùng chung khả dụng
tại thời điểm chạy:
```text
/tool music_generate action=list
```
Dùng `action: "status"` để kiểm tra tác vụ nhạc có session hỗ trợ đang hoạt động:
Dùng `action: "status"` để kiểm tra tác vụ nhạc có phiên hậu thuẫn đang hoạt động:
```text
/tool music_generate action=status
@ -136,10 +137,10 @@ Ví dụ tạo trực tiếp:
## Tham số công cụ
<ParamField path="prompt" type="string" required>
Prompt tạo nhạc. Bắt buộc đối với `action: "generate"`.
Prompt tạo nhạc. Bắt buộc với `action: "generate"`.
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` trả về tác vụ session hiện tại; `"list"` kiểm tra các nhà cung cấp.
`"status"` trả về tác vụ phiên hiện tại; `"list"` kiểm tra các nhà cung cấp.
</ParamField>
<ParamField path="model" type="string">
Ghi đè nhà cung cấp/mô hình (ví dụ `google/lyria-3-pro-preview`,
@ -149,7 +150,7 @@ Ví dụ tạo trực tiếp:
Lời bài hát tùy chọn khi nhà cung cấp hỗ trợ đầu vào lời bài hát tường minh.
</ParamField>
<ParamField path="instrumental" type="boolean">
Yêu cầu đầu ra chỉ có nhạc cụ khi nhà cung cấp hỗ trợ.
Yêu cầu đầu ra chỉ có nhạc không lời khi nhà cung cấp hỗ trợ.
</ParamField>
<ParamField path="image" type="string">
Đường dẫn hoặc URL của một hình ảnh tham chiếu.
@ -167,43 +168,43 @@ Ví dụ tạo trực tiếp:
<ParamField path="timeoutMs" type="number">Thời gian chờ yêu cầu nhà cung cấp tùy chọn tính bằng mili giây. Các giá trị dưới 10000ms được nâng lên 10000ms và được báo cáo trong kết quả công cụ.</ParamField>
<Note>
Không phải nhà cung cấp nào cũng hỗ trợ mọi tham số. OpenClaw vẫn xác thực các
giới hạn cứng như số lượng đầu vào trước khi gửi. Khi một nhà cung cấp hỗ trợ
Không phải tất cả nhà cung cấp đều hỗ trợ mọi tham số. OpenClaw vẫn xác thực
các giới hạn cứng như số lượng đầu vào trước khi gửi. Khi một nhà cung cấp hỗ trợ
thời lượng nhưng dùng mức tối đa ngắn hơn giá trị được yêu cầu, OpenClaw
giới hạn về thời lượng được hỗ trợ gần nhất. Các gợi ý tùy chọn thực sự không
được hỗ trợ sẽ bị bỏ qua kèm cảnh báo khi nhà cung cấp hoặc mô hình được chọn
không thể đáp ứng chúng. Kết quả công cụ báo cáo các thiết lập đã áp dụng;
`details.normalization` ghi lại mọi ánh xạ từ yêu cầu sang áp dụng.
giới hạn về thời lượng được hỗ trợ gần nhất. Các gợi ý tùy chọn thật sự không được hỗ trợ
sẽ bị bỏ qua kèm cảnh báo khi nhà cung cấp hoặc mô hình đã chọn không thể đáp ứng
chúng. Kết quả công cụ báo cáo các cài đặt đã áp dụng; `details.normalization`
ghi lại mọi ánh xạ từ giá trị được yêu cầu sang giá trị đã áp dụng.
</Note>
## Hành vi bất đồng bộ
Tạo nhạc có session hỗ trợ chạy dưới dạng tác vụ nền:
Tạo nhạc có phiên hậu thuẫn chạy dưới dạng tác vụ nền:
- **Tác vụ nền:** `music_generate` tạo một tác vụ nền, trả về phản hồi
đã bắt đầu/tác vụ ngay lập tức và đăng bản nhạc hoàn tất sau đó trong
một tin nhắn agent tiếp theo.
- **Ngăn trùng lặp:** trong khi một tác vụ là `queued` hoặc `running`, các lần gọi
`music_generate` sau đó trong cùng session trả về trạng thái tác vụ thay vì
bắt đầu một lượt tạo khác. Dùng `action: "status"` để kiểm tra rõ ràng.
đã bắt đầu/tác vụ ngay lập tức, và đăng bản nhạc hoàn chỉnh sau đó trong
một tin nhắn tác tử tiếp theo.
- **Ngăn trùng lặp:** khi một tác vụ đang `queued` hoặc `running`, các lệnh gọi
`music_generate` sau đó trong cùng phiên sẽ trả về trạng thái tác vụ thay vì
bắt đầu một lượt tạo khác. Dùng `action: "status"` để kiểm tra tường minh.
- **Tra cứu trạng thái:** `openclaw tasks list` hoặc `openclaw tasks show <taskId>`
kiểm tra trạng thái đang xếp hàng, đang chạy và trạng thái kết thúc.
kiểm tra trạng thái đang chờ, đang chạy và trạng thái kết thúc.
- **Đánh thức khi hoàn tất:** OpenClaw chèn một sự kiện hoàn tất nội bộ trở lại
cùng session để mô hình có thể tự viết phản hồi tiếp theo hướng tới người dùng.
- **Gợi ý prompt:** các lượt người dùng/thủ công sau đó trong cùng session nhận được
một gợi ý thời gian chạy nhỏ khi một tác vụ nhạc đang diễn ra, để mô hình
không gọi lại `music_generate` một cách mù quáng.
- **Dự phòng không có session:** các ngữ cảnh trực tiếp/cục bộ không có session
agent thực sự sẽ chạy nội tuyến và trả về kết quả âm thanh cuối cùng trong cùng lượt.
cùng phiên để mô hình có thể tự viết phản hồi tiếp theo hướng tới người dùng.
- **Gợi ý prompt:** các lượt người dùng/thủ công sau đó trong cùng phiên nhận được
một gợi ý nhỏ lúc chạy khi một tác vụ nhạc đã đang thực thi, để mô hình
không gọi mù quáng `music_generate` lần nữa.
- **Dự phòng không có phiên:** các ngữ cảnh trực tiếp/cục bộ không có phiên tác tử
thật sẽ chạy nội tuyến và trả về kết quả âm thanh cuối cùng trong cùng lượt.
### Vòng đời tác vụ
| Trạng thái | Ý nghĩa |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | Tác vụ đã tạo, đang chờ nhà cung cấp chấp nhận. |
| `running` | Nhà cung cấp đang xử lý (thường từ 30 giây đến 3 phút tùy nhà cung cấp và thời lượng). |
| `succeeded` | Bản nhạc đã sẵn sàng; agent thức dậy và đăng vào cuộc trò chuyện. |
| `failed` | Lỗi nhà cung cấp hoặc hết thời gian chờ; agent thức dậy với chi tiết lỗi. |
| Trạng thái | Ý nghĩa |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | Tác vụ đã được tạo, đang chờ nhà cung cấp chấp nhận. |
| `running` | Nhà cung cấp đang xử lý (thường từ 30 giây đến 3 phút tùy nhà cung cấp và thời lượng). |
| `succeeded` | Bản nhạc đã sẵn sàng; tác tử được đánh thức và đăng nó vào cuộc trò chuyện. |
| `failed` | Lỗi nhà cung cấp hoặc hết thời gian chờ; tác tử được đánh thức cùng chi tiết lỗi. |
Kiểm tra trạng thái từ CLI:
@ -234,12 +235,12 @@ openclaw tasks cancel <taskId>
OpenClaw thử các nhà cung cấp theo thứ tự này:
1. Tham số `model` từ lệnh gọi công cụ (nếu agent chỉ định).
1. Tham số `model` từ lệnh gọi công cụ (nếu tác tử chỉ định).
2. `musicGenerationModel.primary` từ cấu hình.
3. `musicGenerationModel.fallbacks` theo thứ tự.
4. Tự động phát hiện chỉ bằng các mặc định nhà cung cấp có xác thực hỗ trợ:
4. Tự động phát hiện chỉ bằng các mặc định nhà cung cấp có xác thực hậu thuẫn:
- nhà cung cấp mặc định hiện tại trước;
- các nhà cung cấp tạo nhạc đã đăng ký còn lại theo thứ tự provider-id.
- các nhà cung cấp tạo nhạc đã đăng ký còn lại theo thứ tự mã định danh nhà cung cấp.
Nếu một nhà cung cấp thất bại, ứng viên tiếp theo sẽ được thử tự động. Nếu tất cả
đều thất bại, lỗi sẽ bao gồm chi tiết từ từng lần thử.
@ -251,30 +252,30 @@ các mục `model`, `primary` và `fallbacks` tường minh.
<AccordionGroup>
<Accordion title="ComfyUI">
Được điều khiển bởi workflow và phụ thuộc vào graph đã cấu hình cùng ánh xạ nút
cho các trường prompt/output. Plugin `comfy` đi kèm kết nối vào
Được dẫn dắt bởi workflow và phụ thuộc vào đồ thị đã cấu hình cùng ánh xạ nút
cho các trường prompt/đầu ra. Plugin `comfy` đi kèm cắm vào
công cụ `music_generate` dùng chung thông qua registry nhà cung cấp
tạo nhạc.
</Accordion>
<Accordion title="Google (Lyria 3)">
Dùng tạo hàng loạt Lyria 3. Luồng đi kèm hiện tại hỗ trợ
Sử dụng tạo theo lô Lyria 3. Luồng đi kèm hiện tại hỗ trợ
prompt, văn bản lời bài hát tùy chọn và hình ảnh tham chiếu tùy chọn.
</Accordion>
<Accordion title="MiniMax">
Dùng endpoint `music_generation` hàng loạt. Hỗ trợ prompt, lời bài hát
tùy chọn, chế độ nhạc cụ, điều hướng thời lượng và đầu ra mp3 thông qua
Sử dụng endpoint `music_generation` theo lô. Hỗ trợ prompt, lời bài hát
tùy chọn, chế độ nhạc không lời, điều hướng thời lượng và đầu ra mp3 thông qua
xác thực khóa API `minimax` hoặc OAuth `minimax-portal`.
</Accordion>
</AccordionGroup>
## Chọn đường đi phù hợp
## Chọn hướng đi phù hợp
- **Dựa trên nhà cung cấp dùng chung** khi bạn muốn chọn mô hình, chuyển đổi dự phòng
- **Dùng chung có nhà cung cấp hậu thuẫn** khi bạn muốn chọn mô hình, chuyển đổi dự phòng
nhà cung cấp và luồng tác vụ/trạng thái bất đồng bộ tích hợp sẵn.
- **Đường dẫn Plugin (ComfyUI)** khi bạn cần graph workflow tùy chỉnh hoặc một
- **Đường dẫn Plugin (ComfyUI)** khi bạn cần đồ thị workflow tùy chỉnh hoặc một
nhà cung cấp không thuộc năng lực nhạc dùng chung đi kèm.
Nếu bạn đang gỡ lỗi hành vi dành riêng cho ComfyUI, xem
Nếu bạn đang gỡ lỗi hành vi riêng của ComfyUI, xem
[ComfyUI](/vi/providers/comfy). Nếu bạn đang gỡ lỗi hành vi nhà cung cấp dùng chung,
hãy bắt đầu với [Google (Gemini)](/vi/providers/google) hoặc
[MiniMax](/vi/providers/minimax).
@ -283,7 +284,7 @@ hãy bắt đầu với [Google (Gemini)](/vi/providers/google) hoặc
Hợp đồng tạo nhạc dùng chung hỗ trợ khai báo chế độ tường minh:
- `generate` cho tạo chỉ từ prompt.
- `generate` cho tạo chỉ bằng prompt.
- `edit` khi yêu cầu bao gồm một hoặc nhiều hình ảnh tham chiếu.
Các triển khai nhà cung cấp mới nên ưu tiên các khối chế độ tường minh:
@ -305,14 +306,14 @@ capabilities: {
```
Các trường phẳng cũ như `maxInputImages`, `supportsLyrics` và
`supportsFormat` là **không** đủ để quảng bá hỗ trợ chỉnh sửa. Nhà cung cấp
nên khai báo `generate` và `edit` rõ ràng để kiểm thử trực tiếp, kiểm thử hợp đồng
`supportsFormat` **không** đủ để quảng bá hỗ trợ chỉnh sửa. Nhà cung cấp
nên khai báo `generate` và `edit` tường minh để kiểm thử trực tiếp, kiểm thử hợp đồng
và công cụ `music_generate` dùng chung có thể xác thực hỗ trợ chế độ
một cách xác định.
một cách tất định.
## Kiểm thử trực tiếp
Bao phủ trực tiếp chọn tham gia cho các nhà cung cấp đi kèm dùng chung:
Phạm vi kiểm thử trực tiếp tự chọn cho các nhà cung cấp dùng chung đi kèm:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -325,21 +326,21 @@ pnpm test:live:media music
```
Tệp trực tiếp này tải các biến môi trường nhà cung cấp còn thiếu từ `~/.profile`, ưu tiên
khóa API live/env trước các hồ sơ xác thực đã lưu theo mặc định, và chạy cả
bao phủ `generate` lẫn `edit` đã khai báo khi nhà cung cấp bật chế độ chỉnh sửa.
Bao phủ hiện nay:
khóa API trực tiếp/môi trường hơn hồ sơ xác thực đã lưu theo mặc định, và chạy cả
phạm vi `generate` lẫn `edit` đã khai báo khi nhà cung cấp bật chế độ chỉnh sửa.
Phạm vi hiện nay:
- `google`: `generate` cộng với `edit`
- `minimax`: chỉ `generate`
- `comfy`: bao phủ trực tiếp Comfy riêng, không thuộc đợt quét nhà cung cấp dùng chung
- `comfy`: phạm vi trực tiếp Comfy riêng, không nằm trong đợt quét nhà cung cấp dùng chung
Bao phủ trực tiếp chọn tham gia cho đường dẫn nhạc ComfyUI đi kèm:
Phạm vi kiểm thử trực tiếp tự chọn cho đường dẫn nhạc ComfyUI đi kèm:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Tệp live Comfy cũng bao gồm các quy trình làm việc hình ảnh và video Comfy khi các
Tệp live của Comfy cũng bao phủ các quy trình xử lý hình ảnh và video của comfy khi các
phần đó được cấu hình.
## Liên quan

580
docs/vi/tools/plugin.md
View File

@ -1,35 +1,36 @@
---
read_when:
- Cài đặt hoặc cấu hình các Plugin
- Tìm hiểu các quy tắc phát hiện và tải Plugin
- Cài đặt hoặc cấu hình Plugin
- Tìm hiểu quy tắc phát hiện và tải Plugin
- Làm việc với các gói Plugin tương thích với Codex/Claude
sidebarTitle: Install and Configure
summary: Cài đặt, cấu hình và quản lý các Plugin OpenClaw
title: Plugin
x-i18n:
generated_at: "2026-05-03T21:37:29Z"
generated_at: "2026-05-05T01:51:42Z"
model: gpt-5.5
provider: openai
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
source_path: tools/plugin.md
workflow: 16
---
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,
bộ khung agent, công cụ, Skills, giọng nói, phiên âm thời gian thực, giọng nói
thời gian thực, hiểu nội dung phương tiện, tạo hình ảnh, tạo video, truy xuất web,
tìm kiếm web, và nhiều hơn nữa. Một số Plugin là **lõi** (được phân phối cùng OpenClaw),
các Plugin khác là **bên ngoài**. Hầu hết Plugin bên ngoài được xuất bản và khám phá thông qua
[ClawHub](/vi/tools/clawhub). Npm vẫn được hỗ trợ cho cài đặt trực tiếp và cho một
tập hợp tạm thời các gói Plugin do OpenClaw sở hữu trong khi quá trình di chuyển đó hoàn tất.
Các Plugin mở rộng OpenClaw bằng những khả năng mới: kênh, nhà cung cấp mô hình,
bộ khung agent, công cụ, Skills, 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, tìm nạp web, tìm kiếm web, và
nhiều khả năng khác. Một số Plugin là **lõi** (được phát hành cùng OpenClaw),
những Plugin khác là **bên ngoài**. Hầu hết Plugin bên ngoài được phát hành và
khám phá thông qua [ClawHub](/vi/tools/clawhub). Npm vẫn được hỗ trợ cho cài đặt
trực tiếp và cho một tập tạm thời các gói Plugin do OpenClaw sở hữu trong khi
quá trình di chuyển đó hoàn tất.
## Bắt đầu nhanh
Để xem các ví dụ cài đặt, liệt kê, gỡ cài đặt, cập nhật và xuất bản có thể sao chép-dán, hãy xem
[Quản lý Plugin](/vi/plugins/manage-plugins).
Để xem các ví dụ có thể sao chép-dán về cài đặt, liệt kê, gỡ cài đặt, cập nhật
và phát hành, xem [Quản lý Plugin](/vi/plugins/manage-plugins).
<Steps>
<Step title="Xem nội dung đã được tải">
<Step title="Xem những gì đã được tải">
```bash
openclaw plugins list
```
@ -61,17 +62,18 @@ tập hợp tạm thời các gói Plugin do OpenClaw sở hữu trong khi quá
openclaw gateway restart
```
Sau đó cấu hình dưới `plugins.entries.\<id\>.config` trong tệp cấu hình của bạn.
Sau đó cấu hình trong `plugins.entries.\<id\>.config` trong tệp cấu hình của bạn.
</Step>
<Step title="Quản lý ngay trong trò chuyện">
Trong một Gateway đang chạy, `/plugins enable` và `/plugins disable` chỉ dành cho chủ sở hữu
sẽ kích hoạt trình tải lại cấu hình Gateway. Gateway tải lại các bề mặt runtime của Plugin
ngay trong tiến trình, và các lượt agent mới sẽ xây dựng lại danh sách công cụ của chúng từ
registry đã được làm mới. `/plugins install` thay đổi mã nguồn Plugin, vì vậy
Gateway yêu cầu khởi động lại thay vì giả vờ rằng tiến trình hiện tại có thể
tải lại an toàn các mô-đun đã được import.
<Step title="Quản lý trực tiếp trong chat">
Trong một Gateway đang chạy, `/plugins enable` và `/plugins disable` chỉ dành
cho chủ sở hữu sẽ kích hoạt trình tải lại cấu hình Gateway. Gateway tải lại
các bề mặt runtime của Plugin ngay trong tiến trình, và các lượt agent mới
xây dựng lại danh sách công cụ của chúng từ registry đã được làm mới.
`/plugins install` thay đổi mã nguồn Plugin, vì vậy Gateway yêu cầu khởi
động lại thay vì giả vờ rằng tiến trình hiện tại có thể tải lại an toàn các
module đã được nhập.
</Step>
@ -83,14 +85,15 @@ tập hợp tạm thời các gói Plugin do OpenClaw sở hữu trong khi quá
openclaw <plugin-command> --help
```
Dùng `--runtime` khi bạn cần chứng minh các công cụ, dịch vụ, phương thức gateway,
hook hoặc lệnh CLI do Plugin sở hữu đã được đăng ký. `inspect` thông thường là một
kiểm tra manifest/registry lạnh và cố ý tránh import runtime của Plugin.
Dùng `--runtime` khi bạn cần chứng minh các công cụ, dịch vụ, phương thức
gateway, hook, hoặc lệnh CLI do Plugin sở hữu đã được đăng ký. `inspect`
thông thường là kiểm tra manifest/registry lạnh và cố ý tránh nhập runtime
của Plugin.
</Step>
</Steps>
Nếu bạn muốn điều khiển ngay trong trò chuyện, hãy bật `commands.plugins: true` và dùng:
Nếu bạn thích điều khiển trực tiếp trong chat, bật `commands.plugins: true` và dùng:
```text
/plugin install clawhub:<package>
@ -98,62 +101,66 @@ Nếu bạn muốn điều khiển ngay trong trò chuyện, hãy bật `command
/plugin enable <plugin-id>
```
Đường dẫn cài đặt dùng cùng resolver như CLI: đường dẫn/kho lưu trữ cục bộ, `clawhub:<pkg>` rõ ràng,
`npm:<pkg>` rõ ràng, `git:<repo>` rõ ràng, hoặc đặc tả gói trần qua npm.
Đường dẫn cài đặt dùng cùng bộ phân giải như CLI: đường dẫn/kho lưu trữ cục bộ,
`clawhub:<pkg>` tường minh, `npm:<pkg>` tường minh, `git:<repo>` tường minh,
hoặc đặc tả gói trần thông qua npm.
Nếu cấu hình không hợp lệ, cài đặt thường sẽ đóng an toàn và chỉ bạn đến
`openclaw doctor --fix`. Ngoại lệ khôi phục duy nhất là đường dẫn cài đặt lại
Plugin đi kèm có phạm vi hẹp cho các Plugin chọn tham gia
Nếu cấu hình không hợp lệ, cài đặt thường sẽ fail closed và chỉ bạn đến
`openclaw doctor --fix`. Ngoại lệ khôi phục duy nhất là một đường dẫn cài đặt
lại hẹp cho Plugin được đóng gói sẵn đối với các Plugin chọn tham gia
`openclaw.install.allowInvalidConfigRecovery`.
Trong khi Gateway khởi động, cấu hình Plugin không hợp lệ sẽ đóng an toàn như mọi cấu hình
không hợp lệ khác. Chạy `openclaw doctor --fix` để cách ly cấu hình Plugin lỗi bằng cách
tắt mục Plugin đó và xóa payload cấu hình không hợp lệ của nó; bản sao lưu cấu hình thông thường
giữ lại các giá trị trước đó.
Khi một cấu hình kênh tham chiếu đến một Plugin không còn có thể khám phá nhưng cùng id Plugin cũ
vẫn còn trong cấu hình Plugin hoặc bản ghi cài đặt, Gateway startup ghi cảnh báo và bỏ qua kênh đó
thay vì chặn mọi kênh khác.
Chạy `openclaw doctor --fix` để xóa các mục kênh/Plugin cũ; các khóa kênh không xác định
không có bằng chứng Plugin cũ vẫn sẽ không vượt qua xác thực để lỗi gõ vẫn hiển thị.
Nếu đặt `plugins.enabled: false`, các tham chiếu Plugin cũ được coi là bất hoạt:
Gateway startup bỏ qua công việc khám phá/tải Plugin và `openclaw doctor` giữ nguyên
cấu hình Plugin đã tắt thay vì tự động xóa nó. Bật lại Plugin trước khi
chạy dọn dẹp doctor nếu bạn muốn xóa các id Plugin cũ.
Trong quá trình khởi động Gateway, cấu hình Plugin không hợp lệ fail closed như
mọi cấu hình không hợp lệ khác. Chạy `openclaw doctor --fix` để cách ly cấu hình
Plugin lỗi bằng cách vô hiệu hóa mục Plugin đó và loại bỏ payload cấu hình không
hợp lệ của nó; bản sao lưu cấu hình thông thường giữ lại các giá trị trước đó.
Khi cấu hình kênh tham chiếu một Plugin không còn có thể khám phá nhưng cùng id
Plugin cũ vẫn còn trong cấu hình Plugin hoặc bản ghi cài đặt, quá trình khởi động
Gateway ghi cảnh báo và bỏ qua kênh đó thay vì chặn mọi kênh khác. Chạy
`openclaw doctor --fix` để loại bỏ các mục kênh/Plugin cũ; các khóa kênh không
xác định không có bằng chứng Plugin cũ vẫn fail validation để lỗi gõ sai vẫn hiển
thị.
Nếu đặt `plugins.enabled: false`, các tham chiếu Plugin cũ được xem là bất hoạt:
quá trình khởi động Gateway bỏ qua công việc khám phá/tải Plugin và
`openclaw doctor` giữ nguyên cấu hình Plugin đã tắt thay vì tự động loại bỏ nó.
Bật lại Plugin trước khi chạy dọn dẹp bằng doctor nếu bạn muốn loại bỏ các id
Plugin cũ.
Việc cài đặt phụ thuộc của Plugin chỉ diễn ra trong các luồng cài đặt/cập nhật rõ ràng hoặc
sửa chữa bằng doctor. Gateway startup, tải lại cấu hình và kiểm tra runtime không
chạy trình quản lý gói hoặc sửa cây phụ thuộc. Plugin cục bộ phải đã có
các phụ thuộc được cài đặt, trong khi các Plugin npm, git và ClawHub được
cài dưới các gốc Plugin do OpenClaw quản lý. Các phụ thuộc npm có thể được hoist
trong gốc npm do OpenClaw quản lý; cài đặt/cập nhật quét gốc được quản lý đó trước khi
tin cậy và gỡ cài đặt sẽ xóa các gói do npm quản lý thông qua npm. Plugin bên ngoài
và đường dẫn tải tùy chỉnh vẫn phải được cài thông qua `openclaw plugins install`.
Dùng `openclaw plugins list --json` để xem `dependencyStatus` tĩnh cho từng
Plugin hiển thị mà không import mã runtime hoặc sửa phụ thuộc.
Xem [Phân giải phụ thuộc Plugin](/vi/plugins/dependency-resolution) để biết vòng đời tại thời điểm cài đặt.
Việc cài đặt phần phụ thuộc của Plugin chỉ diễn ra trong các luồng cài đặt/cập
nhật tường minh hoặc sửa chữa bằng doctor. Khởi động Gateway, tải lại cấu hình
và kiểm tra runtime không chạy trình quản lý gói hay sửa cây phụ thuộc. Plugin
cục bộ phải đã có phần phụ thuộc được cài đặt, trong khi Plugin npm, git và
ClawHub được cài đặt dưới các gốc Plugin do OpenClaw quản lý. Phần phụ thuộc npm
có thể được hoist trong gốc npm do OpenClaw quản lý; cài đặt/cập nhật quét gốc
được quản lý đó trước khi tin cậy và gỡ cài đặt sẽ loại bỏ các gói do npm quản
lý thông qua npm. Plugin bên ngoài và đường dẫn tải tùy chỉnh vẫn phải được cài
đặt thông qua `openclaw plugins install`. Dùng `openclaw plugins list --json` để
xem `dependencyStatus` tĩnh cho từng Plugin hiển thị mà không nhập mã runtime hay
sửa phần phụ thuộc. Xem [Phân giải phần phụ thuộc Plugin](/vi/plugins/dependency-resolution)
để biết vòng đời tại thời điểm cài đặt.
Đối với cài đặt npm, các selector có thể thay đổi như `latest` hoặc dist-tag được phân giải
trước khi cài đặt rồi được ghim vào đúng phiên bản đã xác minh trong gốc npm
do OpenClaw quản lý. Sau khi npm hoàn tất, OpenClaw xác minh mục
`package-lock.json` đã cài vẫn khớp với phiên bản đã phân giải và integrity. Nếu
npm ghi metadata gói khác, quá trình cài đặt thất bại và gói được quản lý
được rollback thay vì chấp nhận một artifact Plugin khác.
Với cài đặt npm, các selector có thể thay đổi như `latest` hoặc dist-tag được
phân giải trước khi cài đặt và sau đó được ghim vào đúng phiên bản đã xác minh
trong gốc npm do OpenClaw quản lý. Sau khi npm hoàn tất, OpenClaw xác minh mục
`package-lock.json` đã cài đặt vẫn khớp với phiên bản đã phân giải và integrity.
Nếu npm ghi siêu dữ liệu gói khác, quá trình cài đặt thất bại và gói được quản
lý sẽ được rollback thay vì chấp nhận một artifact Plugin khác.
Các checkout nguồn là pnpm workspaces. Nếu bạn clone OpenClaw để chỉnh sửa các
Plugin đi kèm, hãy chạy `pnpm install`; sau đó OpenClaw tải các Plugin đi kèm từ
`extensions/<id>` để các chỉnh sửa và phụ thuộc cục bộ của gói được dùng trực tiếp.
Cài đặt gốc npm thông thường dành cho OpenClaw đã đóng gói, không dành cho
phát triển từ checkout nguồn.
Các checkout nguồn là pnpm workspace. Nếu bạn clone OpenClaw để chỉnh sửa các
Plugin được đóng gói sẵn, chạy `pnpm install`; sau đó OpenClaw tải các Plugin
được đóng gói sẵn từ `extensions/<id>` để các chỉnh sửa và phần phụ thuộc cục bộ
của gói được dùng trực tiếp. Cài đặt gốc npm thông thường dành cho OpenClaw đã
đóng gói, không dành cho phát triển checkout nguồn.
## Các loại Plugin
## Loại Plugin
OpenClaw nhận diện hai định dạng Plugin:
| Định dạng | Cách hoạt động | Ví dụ |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + mô-đun runtime; thực thi trong tiến trình | Plugin chính thức, gói npm cộng đồng |
| **Bundle** | Bố cục tương thích Codex/Claude/Cursor; được ánh xạ sang các tính năng OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + module runtime; thực thi trong tiến trình | Plugin chính thức, gói npm cộng đồng |
| **Bundle** | Bố cục tương thích Codex/Claude/Cursor; được ánh xạ sang tính năng OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Cả hai đều xuất hiện trong `openclaw plugins list`. Xem [Plugin Bundles](/vi/plugins/bundles) để biết chi tiết về bundle.
Cả hai đều xuất hiện trong `openclaw plugins list`. Xem [Plugin Bundle](/vi/plugins/bundles) để biết chi tiết về bundle.
Nếu bạn đang viết một Plugin native, hãy bắt đầu với [Xây dựng Plugin](/vi/plugins/building-plugins)
và [Tổng quan Plugin SDK](/vi/plugins/sdk-overview).
@ -161,18 +168,18 @@ và [Tổng quan Plugin SDK](/vi/plugins/sdk-overview).
## Entry point của gói
Các gói npm Plugin native phải khai báo `openclaw.extensions` trong `package.json`.
Mỗi entry phải nằm trong thư mục gói và phân giải tới một tệp runtime có thể đọc,
hoặc tới một tệp nguồn TypeScript có peer JavaScript đã build được suy luận
như `src/index.ts` tới `dist/index.js`.
Các bản cài đặt đã đóng gói phải phân phối đầu ra runtime JavaScript đó. Fallback
nguồn TypeScript dành cho checkout nguồn và đường dẫn phát triển cục bộ, không dành cho
gói npm được cài vào gốc Plugin do OpenClaw quản lý.
Mỗi mục phải ở trong thư mục gói và phân giải đến một tệp runtime đọc được, hoặc
đến một tệp nguồn TypeScript với một peer JavaScript đã build được suy luận như
`src/index.ts` đến `dist/index.js`.
Cài đặt đã đóng gói phải phát hành output runtime JavaScript đó. Fallback nguồn
TypeScript dành cho checkout nguồn và đường dẫn phát triển cục bộ, không dành
cho các gói npm được cài vào gốc Plugin do OpenClaw quản lý.
Dùng `openclaw.runtimeExtensions` khi các tệp runtime đã xuất bản không nằm tại
cùng đường dẫn với các entry nguồn. Khi có mặt, `runtimeExtensions` phải chứa
đúng một entry cho mỗi entry `extensions`. Danh sách không khớp khiến cài đặt và
khám phá Plugin thất bại thay vì âm thầm fallback về đường dẫn nguồn. Nếu bạn cũng
xuất bản `openclaw.setupEntry`, hãy dùng `openclaw.runtimeSetupEntry` cho peer
Dùng `openclaw.runtimeExtensions` khi các tệp runtime đã phát hành không nằm ở
cùng đường dẫn với các mục nguồn. Khi có mặt, `runtimeExtensions` phải chứa đúng
một mục cho mỗi mục `extensions`. Danh sách không khớp sẽ làm cài đặt và khám phá
Plugin thất bại thay vì âm thầm fallback về đường dẫn nguồn. Nếu bạn cũng phát
hành `openclaw.setupEntry`, hãy dùng `openclaw.runtimeSetupEntry` cho peer
JavaScript đã build của nó; tệp đó là bắt buộc khi được khai báo.
```json
@ -187,38 +194,39 @@ JavaScript đã build của nó; tệp đó là bắt buộc khi được khai b
## Plugin chính thức
### Gói npm do OpenClaw sở hữu trong quá trình di chuyển
### Các gói npm do OpenClaw sở hữu trong quá trình di chuyển
ClawHub là đường dẫn phân phối chính cho hầu hết Plugin. Các bản phát hành OpenClaw
đã đóng gói hiện tại đã kèm sẵn nhiều Plugin chính thức, vì vậy chúng không cần
cài đặt npm riêng trong các thiết lập thông thường. Cho đến khi mọi Plugin do OpenClaw sở hữu
đã chuyển sang ClawHub, OpenClaw vẫn phân phối một số gói Plugin `@openclaw/*` trên
npm cho các bản cài đặt cũ/tùy chỉnh và luồng làm việc npm trực tiếp.
ClawHub là đường dẫn phân phối chính cho hầu hết Plugin. Các bản phát hành
OpenClaw đã đóng gói hiện tại đã bundle nhiều Plugin chính thức, nên các Plugin
đó không cần cài đặt npm riêng trong thiết lập thông thường. Cho đến khi mọi
Plugin do OpenClaw sở hữu đã di chuyển sang ClawHub, OpenClaw vẫn phát hành một
số gói Plugin `@openclaw/*` trên npm cho cài đặt cũ/tùy chỉnh và quy trình npm
trực tiếp.
Nếu npm báo một gói Plugin `@openclaw/*` là deprecated, phiên bản gói đó
đến từ một chuỗi gói bên ngoài cũ hơn. Hãy dùng Plugin đi kèm từ
OpenClaw hiện tại hoặc một checkout cục bộ cho đến khi gói npm mới hơn được xuất bản.
Nếu npm báo một gói Plugin `@openclaw/*` là deprecated, phiên bản gói đó đến từ
một tuyến gói bên ngoài cũ hơn. Dùng Plugin được bundle từ OpenClaw hiện tại
hoặc checkout cục bộ cho đến khi một gói npm mới hơn được phát hành.
| Plugin | Gói | Tài liệu |
| Plugin | Gói | Tài liệu |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/vi/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/vi/channels/discord) |
| Feishu | `@openclaw/feishu` | [Feishu](/vi/channels/feishu) |
| Matrix | `@openclaw/matrix` | [Matrix](/vi/channels/matrix) |
| Mattermost | `@openclaw/mattermost` | [Mattermost](/vi/channels/mattermost) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/vi/channels/msteams) |
| Nextcloud Talk | `@openclaw/nextcloud-talk` | [Nextcloud Talk](/vi/channels/nextcloud-talk) |
| Nostr | `@openclaw/nostr` | [Nostr](/vi/channels/nostr) |
| Synology Chat | `@openclaw/synology-chat` | [Synology Chat](/vi/channels/synology-chat) |
| Tlon | `@openclaw/tlon` | [Tlon](/vi/channels/tlon) |
| WhatsApp | `@openclaw/whatsapp` | [WhatsApp](/vi/channels/whatsapp) |
| Zalo | `@openclaw/zalo` | [Zalo](/vi/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/vi/plugins/zalouser) |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/vi/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/vi/channels/discord) |
| Feishu | `@openclaw/feishu` | [Feishu](/vi/channels/feishu) |
| Matrix | `@openclaw/matrix` | [Matrix](/vi/channels/matrix) |
| Mattermost | `@openclaw/mattermost` | [Mattermost](/vi/channels/mattermost) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/vi/channels/msteams) |
| Nextcloud Talk | `@openclaw/nextcloud-talk` | [Nextcloud Talk](/vi/channels/nextcloud-talk) |
| Nostr | `@openclaw/nostr` | [Nostr](/vi/channels/nostr) |
| Synology Chat | `@openclaw/synology-chat` | [Synology Chat](/vi/channels/synology-chat) |
| Tlon | `@openclaw/tlon` | [Tlon](/vi/channels/tlon) |
| WhatsApp | `@openclaw/whatsapp` | [WhatsApp](/vi/channels/whatsapp) |
| Zalo | `@openclaw/zalo` | [Zalo](/vi/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/vi/plugins/zalouser) |
### Lõi (phân phối cùng OpenClaw)
### Lõi (được phát hành cùng OpenClaw)
<AccordionGroup>
<Accordion title="Nhà cung cấp mô hình (được bật theo mặc định)">
<Accordion title="Nhà cung cấp mô hình (bật theo mặc định)">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@ -227,26 +235,26 @@ OpenClaw hiện tại hoặc một checkout cục bộ cho đến khi gói npm m
</Accordion>
<Accordion title="Plugin bộ nhớ">
- `memory-core` — tìm kiếm bộ nhớ đi kèm (mặc định qua `plugins.slots.memory`)
- `memory-lancedb` — bộ nhớ dài hạn dựa trên LanceDB với tự động nhớ lại/thu thập (đặt `plugins.slots.memory = "memory-lancedb"`)
- `memory-core` — tìm kiếm bộ nhớ được bundle (mặc định qua `plugins.slots.memory`)
- `memory-lancedb` — bộ nhớ dài hạn dựa trên LanceDB với tự động recall/capture (đặt `plugins.slots.memory = "memory-lancedb"`)
Xem [Memory LanceDB](/vi/plugins/memory-lancedb) để biết thiết lập embedding tương thích OpenAI,
ví dụ Ollama, giới hạn nhớ lại và xử lý sự cố.
Xem [Memory LanceDB](/vi/plugins/memory-lancedb) để biết thiết lập embedding
tương thích OpenAI, ví dụ Ollama, giới hạn recall và khắc phục sự cố.
</Accordion>
<Accordion title="Nhà cung cấp giọng nói (được bật theo mặc định)">
<Accordion title="Nhà cung cấp giọng nói (bật theo mặc định)">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="Khác">
- `browser` — Plugin trình duyệt đi kèm cho công cụ trình duyệt, CLI `openclaw browser`, phương thức gateway `browser.request`, runtime trình duyệt và dịch vụ điều khiển trình duyệt mặc định (được bật theo mặc định; tắt trước khi thay thế)
- `copilot-proxy` — cầu nối VS Code Copilot Proxy (bị tắt theo mặc định)
- `browser` — Plugin trình duyệt được bundle cho công cụ trình duyệt, CLI `openclaw browser`, phương thức gateway `browser.request`, runtime trình duyệt và dịch vụ điều khiển trình duyệt mặc định (bật theo mặc định; tắt trước khi thay thế)
- `copilot-proxy` — cầu nối VS Code Copilot Proxy (tắt theo mặc định)
</Accordion>
</AccordionGroup>
Đang tìm Plugin của bên thứ ba? Xem [Plugin cộng đồng](/vi/plugins/community).
Bạn đang tìm Plugin bên thứ ba? Xem [Plugin cộng đồng](/vi/plugins/community).
## Cấu hình
@ -264,51 +272,59 @@ OpenClaw hiện tại hoặc một checkout cục bộ cho đến khi gói npm m
}
```
| Trường | Mô tả |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Công tắc chính (mặc định: `true`) |
| `allow` | Danh sách cho phép Plugin (tùy chọn) |
| `deny` | Danh sách từ chối Plugin (tùy chọn; từ chối được ưu tiên) |
| `load.paths` | Tệp/thư mục Plugin bổ sung |
| `slots` | Bộ chọn vị trí độc quyền (ví dụ: `memory`, `contextEngine`) |
| `entries.\<id\>` | Công tắc bật/tắt + cấu hình theo từng Plugin |
| Trường | Mô tả |
| ------------------ | --------------------------------------------------------- |
| `enabled` | Công tắc chính (mặc định: `true`) |
| `allow` | Danh sách cho phép Plugin (không bắt buộc) |
| `bundledDiscovery` | Chế độ phát hiện Plugin đóng gói sẵn (mặc định là `allowlist`) |
| `deny` | Danh sách chặn Plugin (không bắt buộc; chặn được ưu tiên) |
| `load.paths` | Tệp/thư mục Plugin bổ sung |
| `slots` | Bộ chọn vị trí độc quyền (ví dụ: `memory`, `contextEngine`) |
| `entries.\<id\>` | Công tắc + cấu hình theo từng Plugin |
`plugins.allow` là độc quyền. Khi không rỗng, chỉ các Plugin được liệt kê mới có thể tải
hoặc cung cấp công cụ, ngay cả khi `tools.allow` chứa `"*"` hoặc tên công cụ cụ thể
thuộc sở hữu Plugin. Nếu danh sách cho phép công cụ tham chiếu đến công cụ Plugin, hãy thêm id Plugin sở hữu
hoặc hiển thị công cụ, ngay cả khi `tools.allow` chứa `"*"` hoặc một tên công cụ cụ thể
do Plugin sở hữu. Nếu danh sách cho phép công cụ tham chiếu các công cụ Plugin, hãy thêm id Plugin sở hữu
vào `plugins.allow` hoặc xóa `plugins.allow`; `openclaw doctor` sẽ cảnh báo về
dạng cấu hình này.
`plugins.bundledDiscovery` mặc định là `"allowlist"` đối với cấu hình mới, vì vậy một
kho `plugins.allow` hạn chế cũng chặn các Plugin nhà cung cấp đóng gói sẵn bị bỏ qua,
bao gồm cả phát hiện nhà cung cấp tìm kiếm web trong runtime. Doctor đóng dấu các cấu hình
danh sách cho phép hạn chế cũ bằng `"compat"` trong quá trình di chuyển để các bản nâng cấp giữ
hành vi nhà cung cấp đóng gói sẵn kế thừa cho đến khi người vận hành chọn chế độ nghiêm ngặt hơn.
`plugins.allow` rỗng vẫn được coi là chưa đặt/mở.
Các thay đổi cấu hình được thực hiện qua `/plugins enable` hoặc `/plugins disable` sẽ kích hoạt
việc tải lại Plugin trong tiến trình Gateway. Các lượt agent mới xây dựng lại danh sách công cụ từ
registry Plugin đã được làm mới. Các thao tác thay đổi nguồn như cài đặt,
tải lại Plugin Gateway trong cùng tiến trình. Các lượt agent mới dựng lại danh sách công cụ từ
sổ đăng ký Plugin đã làm mới. Các thao tác thay đổi nguồn như cài đặt,
cập nhật và gỡ cài đặt vẫn khởi động lại tiến trình Gateway vì các mô-đun Plugin đã được nhập
không thể được thay thế an toàn tại chỗ.
`openclaw plugins list` là snapshot cục bộ của registry/cấu hình Plugin. Một Plugin
`enabled` ở đó có nghĩa là registry đã lưu và cấu hình hiện tại cho phép
`openclaw plugins list` là ảnh chụp nhanh sổ đăng ký/cấu hình Plugin cục bộ. Một Plugin
`enabled` ở đó nghĩa là sổ đăng ký đã lưu và cấu hình hiện tại cho phép
Plugin tham gia. Điều đó không chứng minh rằng một Gateway từ xa đang chạy
đã tải lại hoặc khởi động lại vào cùng mã Plugin. Trên các thiết lập VPS/container
có tiến trình wrapper, hãy gửi lệnh khởi động lại hoặc các lần ghi kích hoạt tải lại đến đúng tiến trình
`openclaw gateway run`, hoặc dùng `openclaw gateway restart` với
Gateway đang chạy khi báo cáo tải lại cho biết có lỗi.
đã tải lại hoặc khởi động lại vào cùng mã Plugin. Trên thiết lập VPS/container
có các tiến trình wrapper, hãy gửi lệnh khởi động lại hoặc các thao tác ghi kích hoạt tải lại đến đúng
tiến trình `openclaw gateway run`, hoặc dùng `openclaw gateway restart` đối với
Gateway đang chạy khi báo cáo tải lại thất bại.
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **Đã tắt**: Plugin tồn tại nhưng các quy tắc bật/tắt đã tắt nó. Cấu hình được giữ nguyên.
- **Thiếu**: cấu hình tham chiếu đến một id Plugin mà quá trình khám phá không tìm thấy.
- **Không hợp lệ**: Plugin tồn tại nhưng cấu hình của nó không khớp với schema đã khai báo. Khi khởi động, Gateway chỉ bỏ qua Plugin đó; `openclaw doctor --fix` có thể cách ly mục nhập không hợp lệ bằng cách tắt nó và xóa payload cấu hình của nó.
- **Đã tắt**: Plugin tồn tại nhưng các quy tắc bật đã tắt nó. Cấu hình được giữ nguyên.
- **Thiếu**: cấu hình tham chiếu một id Plugin mà quá trình phát hiện không tìm thấy.
- **Không hợp lệ**: Plugin tồn tại nhưng cấu hình của nó không khớp với schema đã khai báo. Khởi động Gateway chỉ bỏ qua Plugin đó; `openclaw doctor --fix` có thể cách ly mục không hợp lệ bằng cách tắt nó và xóa payload cấu hình của nó.
</Accordion>
## Khám phá và độ ưu tiên
## Phát hiện và thứ tự ưu tiên
OpenClaw quét Plugin theo thứ tự sau (kết quả khớp đầu tiên được ưu tiên):
OpenClaw quét Plugin theo thứ tự này (kết quả khớp đầu tiên được ưu tiên):
<Steps>
<Step title="Config paths">
`plugins.load.paths` — đường dẫn tệp hoặc thư mục tường minh. Các đường dẫn trỏ
ngược về những thư mục Plugin đóng gói đi kèm của chính OpenClaw sẽ bị bỏ qua;
chạy `openclaw doctor --fix` để xóa các alias cũ đó.
`plugins.load.paths` — đường dẫn tệp hoặc thư mục rõ ràng. Các đường dẫn trỏ
ngược về các thư mục Plugin đóng gói sẵn của chính OpenClaw sẽ bị bỏ qua;
chạy `openclaw doctor --fix` để xóa các bí danh cũ đó.
</Step>
<Step title="Workspace plugins">
@ -320,63 +336,63 @@ OpenClaw quét Plugin theo thứ tự sau (kết quả khớp đầu tiên đư
</Step>
<Step title="Bundled plugins">
Được phát hành cùng OpenClaw. Nhiều Plugin được bật theo mặc định (nhà cung cấp mô hình, giọng nói).
Các Plugin khác cần được bật tường minh.
Được phát hành cùng OpenClaw. Nhiều Plugin được bật mặc định (nhà cung cấp mô hình, giọng nói).
Các Plugin khác cần được bật rõ ràng.
</Step>
</Steps>
Các bản cài đóng gói và image Docker thường phân giải Plugin đóng gói đi kèm từ
cây `dist/extensions` đã biên dịch. Nếu một thư mục nguồn Plugin đóng gói đi kèm được
Các bản cài đặt đóng gói và ảnh Docker thường phân giải Plugin đóng gói sẵn từ
cây `dist/extensions` đã biên dịch. Nếu một thư mục nguồn Plugin đóng gói sẵn được
bind-mount đè lên đường dẫn nguồn đóng gói tương ứng, ví dụ
`/app/extensions/synology-chat`, OpenClaw sẽ xem thư mục nguồn đã mount đó
là overlay nguồn đóng gói đi kèm và khám phá nó trước bundle
`/app/dist/extensions/synology-chat` đã đóng gói. Điều này giữ cho các vòng lặp container
của maintainer hoạt động mà không cần chuyển mọi Plugin đóng gói đi kèm trở lại nguồn TypeScript.
Đặt `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` để buộc dùng các bundle dist đã đóng gói
ngay cả khi có mount overlay nguồn.
`/app/extensions/synology-chat`, OpenClaw coi thư mục nguồn đã mount đó
là lớp phủ nguồn đóng gói sẵn và phát hiện nó trước gói
`/app/dist/extensions/synology-chat` đã đóng gói. Điều này giúp các vòng lặp container
của maintainer hoạt động mà không cần chuyển mọi Plugin đóng gói sẵn về nguồn TypeScript.
Đặt `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` để buộc dùng các gói dist đã đóng gói
ngay cả khi có mount lớp phủ nguồn.
### Quy tắc bật/tắt
### Quy tắc bật
- `plugins.enabled: false` tắt tất cả Plugin và bỏ qua công việc khám phá/tải Plugin
- `plugins.deny` luôn được ưu tiên hơn allow
- `plugins.enabled: false` tắt tất cả Plugin và bỏ qua việc phát hiện/tải Plugin
- `plugins.deny` luôn thắng `allow`
- `plugins.entries.\<id\>.enabled: false` tắt Plugin đó
- Plugin có nguồn gốc từ workspace **bị tắt theo mặc định** (phải được bật tường minh)
- Plugin đóng gói đi kèm tuân theo tập mặc định bật sẵn tích hợp, trừ khi bị ghi đè
- Các vị trí độc quyền có thể buộc bật Plugin được chọn cho vị trí đó
- Một số Plugin đóng gói đi kèm dạng opt-in được bật tự động khi cấu hình nêu tên một
bề mặt thuộc sở hữu Plugin, chẳng hạn như tham chiếu mô hình nhà cung cấp, cấu hình kênh hoặc runtime
- Plugin có nguồn gốc từ workspace **mặc định bị tắt** (phải được bật rõ ràng)
- Plugin đóng gói sẵn tuân theo tập bật mặc định tích hợp trừ khi bị ghi đè
- Các vị trí độc quyền có thể buộc bật Plugin đã chọn cho vị trí đó
- Một số Plugin đóng gói sẵn dạng chọn tham gia được bật tự động khi cấu hình nêu tên một
bề mặt do Plugin sở hữu, chẳng hạn ref mô hình nhà cung cấp, cấu hình kênh hoặc runtime
harness
- Cấu hình Plugin cũ được giữ nguyên khi `plugins.enabled: false` đang hoạt động;
hãy bật lại Plugin trước khi chạy dọn dẹp bằng doctor nếu bạn muốn xóa các id cũ
bật lại Plugin trước khi chạy dọn dẹp doctor nếu bạn muốn xóa các id cũ
- Các tuyến Codex thuộc họ OpenAI giữ ranh giới Plugin riêng:
`openai-codex/*` thuộc về Plugin OpenAI, còn Plugin app-server Codex đóng gói đi kèm
được chọn bằng `agentRuntime.id: "codex"` hoặc các tham chiếu mô hình
`codex/*` cũ
`openai-codex/*` thuộc về Plugin OpenAI, trong khi Plugin app-server Codex đóng gói sẵn
được chọn bằng `agentRuntime.id: "codex"` hoặc các ref mô hình
`codex/*` kế thừa
## Khắc phục sự cố hook runtime
Nếu một Plugin xuất hiện trong `plugins list` nhưng hiệu ứng phụ hoặc hook của `register(api)`
không chạy trong lưu lượng chat trực tiếp, hãy kiểm tra các điểm này trước:
Nếu một Plugin xuất hiện trong `plugins list` nhưng hiệu ứng phụ hoặc hook
`register(api)` không chạy trong lưu lượng trò chuyện trực tiếp, hãy kiểm tra các điểm này trước:
- Chạy `openclaw gateway status --deep --require-rpc` và xác nhận URL
Gateway đang hoạt động, profile, đường dẫn cấu hình và tiến trình đúng là những thứ bạn đang chỉnh sửa.
- Khởi động lại Gateway trực tiếp sau khi thay đổi cài đặt/cấu hình/mã Plugin. Trong các container
wrapper, PID 1 có thể chỉ là supervisor; hãy khởi động lại hoặc gửi tín hiệu cho tiến trình con
Gateway đang hoạt động, profile, đường dẫn cấu hình và tiến trình là những mục bạn đang chỉnh sửa.
- Khởi động lại Gateway trực tiếp sau khi thay đổi cài đặt/cấu hình/mã Plugin. Trong container
wrapper, PID 1 có thể chỉ là supervisor; hãy khởi động lại hoặc gửi tín hiệu tới tiến trình con
`openclaw gateway run`.
- Dùng `openclaw plugins inspect <id> --runtime --json` để xác nhận đăng ký hook và
chẩn đoán. Các hook hội thoại không đóng gói đi kèm như `llm_input`,
`llm_output`, `before_agent_finalize` và `agent_end` cần
chẩn đoán. Các hook hội thoại không đóng gói sẵn như `llm_input`,
`llm_output`, `before_agent_finalize`, và `agent_end` cần
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Với chuyển đổi mô hình, ưu tiên `before_model_resolve`. Nó chạy trước quá trình phân giải mô hình
- Để chuyển đổi mô hình, ưu tiên `before_model_resolve`. Nó chạy trước khi phân giải mô hình
cho các lượt agent; `llm_output` chỉ chạy sau khi một lần thử mô hình
tạo ra đầu ra assistant.
- Để chứng minh mô hình phiên hiệu lực, dùng `openclaw sessions` hoặc các bề mặt
phiên/trạng thái Gateway và, khi debug payload nhà cung cấp, khởi động
- Để chứng minh mô hình phiên hiệu dụng, dùng `openclaw sessions` hoặc các bề mặt
phiên/trạng thái Gateway và, khi gỡ lỗi payload nhà cung cấp, khởi động
Gateway với `--raw-stream --raw-stream-path <path>`.
### Thiết lập công cụ Plugin chậm
Nếu các lượt agent có vẻ bị treo khi chuẩn bị công cụ, hãy bật ghi log trace và
Nếu các lượt agent có vẻ bị khựng khi chuẩn bị công cụ, hãy bật ghi log trace và
kiểm tra các dòng thời gian factory công cụ Plugin:
```bash
@ -390,16 +406,16 @@ Tìm:
[trace:plugin-tools] factory timings ...
```
Bản tóm tắt liệt kê tổng thời gian factory và các factory công cụ Plugin chậm nhất,
bao gồm id Plugin, tên công cụ đã khai báo, dạng kết quả và liệu công cụ có
tùy chọn hay không. Các dòng chậm được nâng thành cảnh báo khi một factory đơn lẻ mất
Phần tóm tắt liệt kê tổng thời gian factory và các factory công cụ Plugin chậm nhất,
bao gồm id Plugin, tên công cụ đã khai báo, dạng kết quả và công cụ đó có
không bắt buộc hay không. Các dòng chậm được nâng thành cảnh báo khi một factory riêng lẻ mất
ít nhất 1 giây hoặc tổng thời gian chuẩn bị factory công cụ Plugin mất ít nhất 5 giây.
OpenClaw lưu cache các kết quả factory công cụ Plugin thành công cho các lần phân giải lặp lại
với cùng ngữ cảnh yêu cầu hiệu lực. Khóa cache bao gồm cấu hình runtime hiệu lực,
workspace, id agent/phiên, chính sách sandbox, thiết lập trình duyệt,
ngữ cảnh gửi, danh tính requester và trạng thái sở hữu, nên các factory
phụ thuộc vào các trường đáng tin cậy đó sẽ được chạy lại khi ngữ cảnh thay đổi.
với cùng ngữ cảnh yêu cầu hiệu dụng. Khóa cache bao gồm cấu hình
runtime hiệu dụng, workspace, id agent/phiên, chính sách sandbox, cài đặt trình duyệt,
ngữ cảnh phân phối, danh tính người yêu cầu và trạng thái sở hữu, vì vậy các factory
phụ thuộc vào các trường tin cậy đó sẽ được chạy lại khi ngữ cảnh thay đổi.
Nếu một Plugin chiếm phần lớn thời gian, hãy kiểm tra các đăng ký runtime của nó:
@ -408,7 +424,7 @@ openclaw plugins inspect <plugin-id> --runtime --json
```
Sau đó cập nhật, cài đặt lại hoặc tắt Plugin đó. Tác giả Plugin nên chuyển
việc tải phụ thuộc tốn kém ra sau đường dẫn thực thi công cụ thay vì thực hiện
việc tải phụ thuộc tốn kém vào sau đường dẫn thực thi công cụ thay vì làm việc đó
bên trong factory công cụ.
### Trùng quyền sở hữu kênh hoặc công cụ
@ -419,35 +435,35 @@ Triệu chứng:
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Những thông báo này có nghĩa là nhiều hơn một Plugin đã bật đang cố sở hữu cùng một kênh,
Những thông báo này nghĩa là có hơn một Plugin đã bật đang cố sở hữu cùng một kênh,
luồng thiết lập hoặc tên công cụ. Nguyên nhân phổ biến nhất là một Plugin kênh bên ngoài
được cài đặt bên cạnh một Plugin đóng gói đi kèm hiện cung cấp cùng id kênh.
được cài cạnh một Plugin đóng gói sẵn hiện cung cấp cùng id kênh.
Các bước debug:
Các bước gỡ lỗi:
- Chạy `openclaw plugins list --enabled --verbose` để xem mọi Plugin đã bật
và nguồn gốc.
- Chạy `openclaw plugins inspect <id> --runtime --json` cho từng Plugin nghi ngờ và
so sánh `channels`, `channelConfigs`, `tools` và chẩn đoán.
so sánh `channels`, `channelConfigs`, `tools`, và chẩn đoán.
- Chạy `openclaw plugins registry --refresh` sau khi cài đặt hoặc xóa
các package Plugin để metadata đã lưu phản ánh bản cài hiện tại.
- Khởi động lại Gateway sau khi thay đổi cài đặt, registry hoặc cấu hình.
gói Plugin để siêu dữ liệu đã lưu phản ánh bản cài đặt hiện tại.
- Khởi động lại Gateway sau các thay đổi cài đặt, sổ đăng ký hoặc cấu hình.
Các lựa chọn khắc phục:
Các tùy chọn sửa:
- Nếu một Plugin cố ý thay thế Plugin khác cho cùng id kênh, Plugin
được ưu tiên nên khai báo `channelConfigs.<channel-id>.preferOver` với
id Plugin có độ ưu tiên thấp hơn. Xem [/plugins/manifest#replacing-another-channel-plugin](/vi/plugins/manifest#replacing-another-channel-plugin).
- Nếu trùng lặp là vô tình, hãy tắt một bên bằng
`plugins.entries.<plugin-id>.enabled: false` hoặc xóa bản cài Plugin
id Plugin có mức ưu tiên thấp hơn. Xem [/plugins/manifest#replacing-another-channel-plugin](/vi/plugins/manifest#replacing-another-channel-plugin).
- Nếu trùng lặp là ngoài ý muốn, hãy tắt một bên bằng
`plugins.entries.<plugin-id>.enabled: false` hoặc xóa bản cài đặt Plugin
cũ.
- Nếu bạn đã bật tường minh cả hai Plugin, OpenClaw sẽ giữ yêu cầu đó và
báo cáo xung đột. Chọn một chủ sở hữu cho kênh hoặc đổi tên các công cụ thuộc sở hữu Plugin
để bề mặt runtime không mơ hồ.
- Nếu bạn đã bật rõ ràng cả hai Plugin, OpenClaw giữ yêu cầu đó và
báo cáo xung đột. Hãy chọn một chủ sở hữu cho kênh hoặc đổi tên các công cụ
do Plugin sở hữu để bề mặt runtime không mơ hồ.
## Vị trí Plugin (danh mục độc quyền)
Một số danh mục là độc quyền (mỗi lần chỉ có một danh mục hoạt động):
Một số danh mục là độc quyền (mỗi lần chỉ có một mục hoạt động):
```json5
{
@ -460,10 +476,10 @@ Một số danh mục là độc quyền (mỗi lần chỉ có một danh mục
}
```
| Vị trí | Điều nó kiểm soát | Mặc định |
| Vị trí | Nội dung kiểm soát | Mặc định |
| --------------- | --------------------- | ------------------- |
| `memory` | Plugin bộ nhớ chủ động | `memory-core` |
| `contextEngine` | Công cụ ngữ cảnh chủ động | `legacy` (tích hợp) |
| `memory` | Plugin Active Memory | `memory-core` |
| `contextEngine` | Công cụ ngữ cảnh đang hoạt động | `legacy` (tích hợp sẵn) |
## Tham chiếu CLI
@ -513,82 +529,35 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Các plugin đi kèm được phát hành cùng OpenClaw. Nhiều plugin được bật theo mặc định (ví dụ
các nhà cung cấp mô hình đi kèm, các nhà cung cấp giọng nói đi kèm và plugin trình duyệt
đi kèm). Các plugin đi kèm khác vẫn cần `openclaw plugins enable <id>`.
Các Plugin đi kèm được phân phối cùng OpenClaw. Nhiều Plugin được bật theo mặc định (ví dụ: các nhà cung cấp mô hình đi kèm, các nhà cung cấp giọng nói đi kèm và Plugin trình duyệt đi kèm). Các Plugin đi kèm khác vẫn cần `openclaw plugins enable <id>`.
`--force` ghi đè một plugin hoặc gói hook đã cài đặt hiện có ngay tại chỗ. Dùng
`openclaw plugins update <id-or-npm-spec>` cho các lần nâng cấp thường kỳ của các plugin npm
được theo dõi. Tùy chọn này không được hỗ trợ với `--link`, vốn tái sử dụng đường dẫn nguồn thay vì
sao chép đè lên một đích cài đặt được quản lý.
`--force` ghi đè một Plugin đã cài đặt hoặc gói hook hiện có tại chỗ. Dùng `openclaw plugins update <id-or-npm-spec>` để nâng cấp định kỳ các Plugin npm đang được theo dõi. Tùy chọn này không được hỗ trợ cùng `--link`, vốn tái sử dụng đường dẫn nguồn thay vì sao chép lên một đích cài đặt được quản lý.
Khi `plugins.allow` đã được đặt, `openclaw plugins install` thêm id plugin
đã cài đặt vào danh sách cho phép đó trước khi bật plugin. Nếu cùng id plugin đó
có trong `plugins.deny`, quá trình cài đặt sẽ xóa mục chặn cũ đó để
lần cài đặt rõ ràng có thể được tải ngay sau khi khởi động lại.
Khi `plugins.allow` đã được đặt, `openclaw plugins install` thêm id Plugin đã cài đặt vào danh sách cho phép đó trước khi bật Plugin. Nếu cùng id Plugin đó có trong `plugins.deny`, lệnh cài đặt sẽ xóa mục từ chối cũ đó để lần cài đặt rõ ràng có thể được tải ngay sau khi khởi động lại.
OpenClaw giữ một registry plugin cục bộ được lưu bền vững làm mô hình đọc lạnh cho
kho plugin, quyền sở hữu đóng góp và lập kế hoạch khởi động. Các luồng cài đặt, cập nhật,
gỡ cài đặt, bật và tắt sẽ làm mới registry đó sau khi thay đổi trạng thái plugin. Cùng tệp `plugins/installs.json` lưu metadata cài đặt bền vững trong
`installRecords` cấp cao nhất và metadata manifest có thể dựng lại trong `plugins`. Nếu
registry bị thiếu, cũ hoặc không hợp lệ, `openclaw plugins registry
--refresh` dựng lại góc nhìn manifest của nó từ bản ghi cài đặt, chính sách cấu hình và
metadata manifest/package mà không tải các module runtime của plugin.
`openclaw plugins update <id-or-npm-spec>` áp dụng cho các bản cài đặt được theo dõi. Khi truyền
một spec package npm với dist-tag hoặc phiên bản chính xác, lệnh sẽ phân giải tên package
ngược lại bản ghi plugin được theo dõi và ghi lại spec mới cho các lần cập nhật sau.
Truyền tên package không kèm phiên bản sẽ đưa một bản cài đặt được ghim chính xác trở lại
dòng phát hành mặc định của registry. Nếu plugin npm đã cài đặt đã khớp
phiên bản được phân giải và danh tính artifact đã ghi, OpenClaw bỏ qua cập nhật
mà không tải xuống, cài đặt lại hoặc ghi lại cấu hình.
Khi `openclaw update` chạy trên kênh beta, các bản ghi plugin npm và ClawHub
thuộc dòng mặc định sẽ thử `@beta` trước và quay về default/latest khi không có bản phát hành
beta cho plugin. Các phiên bản chính xác và tag rõ ràng vẫn được ghim.
OpenClaw duy trì một registry Plugin cục bộ bền vững làm mô hình đọc nguội cho kiểm kê Plugin, quyền sở hữu đóng góp và lập kế hoạch khởi động. Các luồng cài đặt, cập nhật, gỡ cài đặt, bật và tắt sẽ làm mới registry đó sau khi thay đổi trạng thái Plugin. Cùng tệp `plugins/installs.json` lưu siêu dữ liệu cài đặt bền vững trong `installRecords` cấp cao nhất và siêu dữ liệu manifest có thể dựng lại trong `plugins`. Nếu registry bị thiếu, lỗi thời hoặc không hợp lệ, `openclaw plugins registry --refresh` sẽ dựng lại chế độ xem manifest từ bản ghi cài đặt, chính sách cấu hình và siêu dữ liệu manifest/package mà không tải các mô-đun runtime của Plugin.
`openclaw plugins update <id-or-npm-spec>` áp dụng cho các bản cài đặt đang được theo dõi. Truyền một đặc tả package npm có dist-tag hoặc phiên bản chính xác sẽ phân giải tên package ngược về bản ghi Plugin được theo dõi và ghi lại đặc tả mới cho các lần cập nhật sau. Truyền tên package không kèm phiên bản sẽ chuyển một bản cài đặt được ghim chính xác về dòng phát hành mặc định của registry. Nếu Plugin npm đã cài đặt đã khớp với phiên bản đã phân giải và danh tính artifact đã ghi, OpenClaw bỏ qua bản cập nhật mà không tải xuống, cài đặt lại hoặc ghi lại cấu hình.
Khi `openclaw update` chạy trên kênh beta, các bản ghi Plugin npm và ClawHub ở dòng mặc định sẽ thử `@beta` trước và quay lại mặc định/mới nhất khi không có bản phát hành beta của Plugin. Các phiên bản chính xác và tag rõ ràng vẫn được ghim.
`--pin` chỉ dành cho npm. Tùy chọn này không được hỗ trợ với `--marketplace`, vì
các bản cài đặt marketplace lưu metadata nguồn marketplace thay vì một spec npm.
`--pin` chỉ dành cho npm. Tùy chọn này không được hỗ trợ cùng `--marketplace`, vì các bản cài đặt marketplace lưu siêu dữ liệu nguồn marketplace thay vì một đặc tả npm.
`--dangerously-force-unsafe-install` là ghi đè khẩn cấp cho các cảnh báo dương tính giả
từ trình quét mã nguy hiểm tích hợp. Nó cho phép các lượt cài đặt plugin
và cập nhật plugin tiếp tục vượt qua các phát hiện `critical` tích hợp, nhưng vẫn
không bỏ qua các chặn chính sách `before_install` của plugin hoặc chặn do lỗi quét.
Các lượt quét cài đặt bỏ qua các tệp và thư mục kiểm thử phổ biến như `tests/`,
`__tests__/`, `*.test.*` và `*.spec.*` để tránh chặn các mock kiểm thử được đóng gói;
các entrypoint runtime đã khai báo của plugin vẫn được quét ngay cả khi chúng dùng một trong
những tên đó.
`--dangerously-force-unsafe-install` là tùy chọn phá kính khẩn cấp cho các cảnh báo dương tính giả từ trình quét mã nguy hiểm tích hợp. Tùy chọn này cho phép cài đặt Plugin và cập nhật Plugin tiếp tục vượt qua các phát hiện `critical` tích hợp, nhưng vẫn không bỏ qua các chặn chính sách `before_install` của Plugin hoặc chặn do lỗi quét. Quá trình quét cài đặt bỏ qua các tệp và thư mục kiểm thử phổ biến như `tests/`, `__tests__/`, `*.test.*` và `*.spec.*` để tránh chặn các mock kiểm thử đã đóng gói; các entrypoint runtime đã khai báo của Plugin vẫn được quét ngay cả khi chúng dùng một trong các tên đó.
Cờ CLI này chỉ áp dụng cho các luồng cài đặt/cập nhật plugin. Các lượt cài đặt
phụ thuộc skill dựa trên Gateway dùng ghi đè yêu cầu `dangerouslyForceUnsafeInstall`
tương ứng, trong khi `openclaw skills install` vẫn là luồng tải xuống/cài đặt
skill ClawHub riêng biệt.
Cờ CLI này chỉ áp dụng cho các luồng cài đặt/cập nhật Plugin. Các bản cài đặt dependency của Skills được Gateway hỗ trợ dùng override yêu cầu `dangerouslyForceUnsafeInstall` tương ứng, trong khi `openclaw skills install` vẫn là luồng tải xuống/cài đặt Skills ClawHub riêng biệt.
Nếu một plugin bạn đã xuất bản trên ClawHub bị ẩn hoặc bị chặn bởi một lượt quét, hãy mở
bảng điều khiển ClawHub hoặc chạy `clawhub package rescan <name>` để yêu cầu ClawHub kiểm tra
lại. `--dangerously-force-unsafe-install` chỉ ảnh hưởng đến các lượt cài đặt trên máy của bạn;
nó không yêu cầu ClawHub quét lại plugin hoặc công khai một bản phát hành bị chặn.
Nếu một Plugin bạn đã xuất bản trên ClawHub bị ẩn hoặc bị chặn bởi một lần quét, hãy mở bảng điều khiển ClawHub hoặc chạy `clawhub package rescan <name>` để yêu cầu ClawHub kiểm tra lại. `--dangerously-force-unsafe-install` chỉ ảnh hưởng đến các bản cài đặt trên máy của bạn; nó không yêu cầu ClawHub quét lại Plugin hoặc công khai một bản phát hành bị chặn.
Các bundle tương thích tham gia cùng luồng liệt kê/kiểm tra/bật/tắt plugin.
Hỗ trợ runtime hiện tại bao gồm Skills trong bundle, command-skills của Claude,
mặc định `settings.json` của Claude, mặc định `lspServers` được khai báo trong
`.lsp.json` và manifest của Claude, command-skills của Cursor và các thư mục hook
Codex tương thích.
Các bundle tương thích tham gia cùng luồng liệt kê/kiểm tra/bật/tắt Plugin. Hỗ trợ runtime hiện tại bao gồm Skills trong bundle, command-skills của Claude, mặc định `settings.json` của Claude, mặc định `.lsp.json` của Claude và `lspServers` do manifest khai báo, command-skills của Cursor và các thư mục hook Codex tương thích.
`openclaw plugins inspect <id>` cũng báo cáo các khả năng bundle được phát hiện cùng
các mục máy chủ MCP và LSP được hỗ trợ hoặc không được hỗ trợ cho các plugin dựa trên bundle.
`openclaw plugins inspect <id>` cũng báo cáo các khả năng bundle đã phát hiện cùng các mục máy chủ MCP và LSP được hỗ trợ hoặc không được hỗ trợ cho các Plugin dựa trên bundle.
Nguồn marketplace có thể là tên marketplace đã biết của Claude từ
`~/.claude/plugins/known_marketplaces.json`, root marketplace cục bộ hoặc đường dẫn
`marketplace.json`, cách viết tắt GitHub như `owner/repo`, URL repo GitHub,
hoặc URL git. Với marketplace từ xa, các mục plugin phải nằm bên trong repo
marketplace đã clone và chỉ dùng nguồn đường dẫn tương đối.
Nguồn marketplace có thể là tên marketplace đã biết của Claude từ `~/.claude/plugins/known_marketplaces.json`, một gốc marketplace cục bộ hoặc đường dẫn `marketplace.json`, một cách viết tắt GitHub như `owner/repo`, URL repo GitHub hoặc URL git. Với marketplace từ xa, các mục Plugin phải nằm bên trong repo marketplace đã clone và chỉ dùng nguồn đường dẫn tương đối.
Xem [tham chiếu CLI `openclaw plugins`](/vi/cli/plugins) để biết đầy đủ chi tiết.
## Tổng quan API Plugin
## Tổng quan Plugin API
Các plugin native xuất một đối tượng entry cung cấp `register(api)`. Các
plugin cũ hơn vẫn có thể dùng `activate(api)` làm alias kế thừa, nhưng các plugin mới nên
dùng `register`.
Các Plugin native xuất một đối tượng entry cung cấp `register(api)`. Các Plugin cũ hơn vẫn có thể dùng `activate(api)` làm alias kế thừa, nhưng Plugin mới nên dùng `register`.
```typescript
export default definePluginEntry({
@ -608,75 +577,60 @@ export default definePluginEntry({
});
```
OpenClaw tải đối tượng entry và gọi `register(api)` trong quá trình kích hoạt plugin.
Loader vẫn quay về `activate(api)` cho các plugin cũ hơn,
nhưng các plugin đi kèm và plugin bên ngoài mới nên xem `register` là
hợp đồng công khai.
OpenClaw tải đối tượng entry và gọi `register(api)` trong quá trình kích hoạt Plugin. Loader vẫn fallback về `activate(api)` cho các Plugin cũ hơn, nhưng các Plugin đi kèm và Plugin bên ngoài mới nên xem `register` là hợp đồng công khai.
`api.registrationMode` cho plugin biết lý do entry của nó đang được tải:
`api.registrationMode` cho Plugin biết vì sao entry của nó đang được tải:
| Chế độ | Ý nghĩa |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Kích hoạt runtime. Đăng ký công cụ, hook, dịch vụ, lệnh, route và các hiệu ứng phụ sống khác. |
| `discovery` | Khám phá khả năng chỉ đọc. Đăng ký nhà cung cấp và metadata; mã entry plugin đáng tin cậy có thể tải, nhưng bỏ qua các hiệu ứng phụ sống. |
| `setup-only` | Tải metadata thiết lập kênh thông qua một entry thiết lập nhẹ. |
| `full` | Kích hoạt runtime. Đăng ký công cụ, hook, dịch vụ, lệnh, route và các hiệu ứng phụ đang chạy khác. |
| `discovery` | Khám phá khả năng chỉ đọc. Đăng ký nhà cung cấp và siêu dữ liệu; mã entry Plugin đáng tin cậy có thể tải, nhưng bỏ qua hiệu ứng phụ đang chạy. |
| `setup-only` | Tải siêu dữ liệu thiết lập kênh thông qua một entry thiết lập nhẹ. |
| `setup-runtime` | Tải thiết lập kênh cũng cần entry runtime. |
| `cli-metadata` | Chỉ thu thập metadata lệnh CLI. |
| `cli-metadata` | Chỉ thu thập siêu dữ liệu lệnh CLI. |
Các entry plugin mở socket, cơ sở dữ liệu, worker nền hoặc client sống lâu
nên bảo vệ các hiệu ứng phụ đó bằng `api.registrationMode === "full"`.
Các lượt tải khám phá được lưu cache riêng với các lượt tải kích hoạt và không thay thế
registry Gateway đang chạy. Khám phá là không kích hoạt, không phải không import:
OpenClaw có thể đánh giá entry plugin đáng tin cậy hoặc module plugin kênh để xây dựng
snapshot. Giữ phần cấp cao nhất của module nhẹ và không có hiệu ứng phụ, đồng thời chuyển
client mạng, tiến trình con, listener, lượt đọc credential và khởi động dịch vụ
ra sau các đường dẫn full-runtime.
Các entry Plugin mở socket, cơ sở dữ liệu, worker nền hoặc client sống lâu nên bảo vệ các hiệu ứng phụ đó bằng `api.registrationMode === "full"`. Các lần tải khám phá được cache riêng với các lần tải kích hoạt và không thay thế registry Gateway đang chạy. Khám phá là không kích hoạt, không phải không import: OpenClaw có thể đánh giá entry Plugin đáng tin cậy hoặc mô-đun Plugin kênh để xây dựng snapshot. Giữ cấp cao nhất của mô-đun nhẹ và không có hiệu ứng phụ, đồng thời chuyển client mạng, tiến trình con, listener, đọc thông tin xác thực và khởi động dịch vụ vào sau các đường dẫn full-runtime.
Các phương thức đăng ký phổ biến:
| Phương thức | Nội dung đăng ký |
| --------------------------------------- | ----------------------------- |
| `registerProvider` | Nhà cung cấp mô hình (LLM) |
| `registerChannel` | Kênh chat |
| `registerTool` | Công cụ agent |
| `registerHook` / `on(...)` | Hook vòng đời |
| Phương thức | Nội dung đăng ký |
| --------------------------------------- | ---------------------------- |
| `registerProvider` | Nhà cung cấp mô hình (LLM) |
| `registerChannel` | Kênh trò chuyện |
| `registerTool` | Công cụ agent |
| `registerHook` / `on(...)` | Hook vòng đời |
| `registerSpeechProvider` | Chuyển văn bản thành giọng nói / STT |
| `registerRealtimeTranscriptionProvider` | STT truyền phát |
| `registerRealtimeVoiceProvider` | Giọng nói realtime song công |
| `registerMediaUnderstandingProvider` | Phân tích hình ảnh/âm thanh |
| `registerImageGenerationProvider` | Tạo hình ảnh |
| `registerMusicGenerationProvider` | Tạo nhạc |
| `registerVideoGenerationProvider` | Tạo video |
| `registerWebFetchProvider` | Nhà cung cấp web fetch / scrape |
| `registerWebSearchProvider` | Tìm kiếm web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Lệnh CLI |
| `registerContextEngine` | Engine ngữ cảnh |
| `registerService` | Dịch vụ nền |
| `registerRealtimeTranscriptionProvider` | STT truyền phát |
| `registerRealtimeVoiceProvider` | Giọng nói realtime hai chiều |
| `registerMediaUnderstandingProvider` | Phân tích hình ảnh/âm thanh |
| `registerImageGenerationProvider` | Tạo hình ảnh |
| `registerMusicGenerationProvider` | Tạo nhạc |
| `registerVideoGenerationProvider` | Tạo video |
| `registerWebFetchProvider` | Nhà cung cấp fetch / scrape web |
| `registerWebSearchProvider` | Tìm kiếm web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Lệnh CLI |
| `registerContextEngine` | Context engine |
| `registerService` | Dịch vụ nền |
Hành vi guard hook cho các hook vòng đời có kiểu:
- `before_tool_call`: `{ block: true }` là kết thúc; các handler có độ ưu tiên thấp hơn bị bỏ qua.
- `before_tool_call`: `{ block: false }` là không thao tác và không xóa một chặn trước đó.
- `before_install`: `{ block: true }` là kết thúc; các handler có độ ưu tiên thấp hơn bị bỏ qua.
- `before_install`: `{ block: false }` là không thao tác và không xóa một chặn trước đó.
- `message_sending`: `{ cancel: true }` là kết thúc; các handler có độ ưu tiên thấp hơn bị bỏ qua.
- `message_sending`: `{ cancel: false }` là không thao tác và không xóa một hủy trước đó.
- `before_tool_call`: `{ block: true }` là điểm kết thúc; các handler có mức ưu tiên thấp hơn bị bỏ qua.
- `before_tool_call`: `{ block: false }` là no-op và không xóa một chặn trước đó.
- `before_install`: `{ block: true }` là điểm kết thúc; các handler có mức ưu tiên thấp hơn bị bỏ qua.
- `before_install`: `{ block: false }` là no-op và không xóa một chặn trước đó.
- `message_sending`: `{ cancel: true }` là điểm kết thúc; các handler có mức ưu tiên thấp hơn bị bỏ qua.
- `message_sending`: `{ cancel: false }` là no-op và không xóa một hủy trước đó.
App-server Codex native nối ngược các sự kiện công cụ Codex-native vào
bề mặt hook này. Plugin có thể chặn các công cụ Codex native thông qua `before_tool_call`,
quan sát kết quả thông qua `after_tool_call` và tham gia phê duyệt
`PermissionRequest` của Codex. Cầu nối chưa ghi lại các đối số công cụ Codex-native.
Ranh giới hỗ trợ runtime Codex chính xác nằm trong
[hợp đồng hỗ trợ Codex harness v1](/vi/plugins/codex-harness#v1-support-contract).
App-server Codex native nối cầu các sự kiện công cụ Codex-native trở lại bề mặt hook này. Plugin có thể chặn các công cụ Codex native thông qua `before_tool_call`, quan sát kết quả thông qua `after_tool_call` và tham gia phê duyệt `PermissionRequest` của Codex. Cầu nối chưa ghi lại đối số công cụ Codex-native. Ranh giới hỗ trợ runtime Codex chính xác nằm trong [hợp đồng hỗ trợ Codex harness v1](/vi/plugins/codex-harness#v1-support-contract).
Để biết đầy đủ hành vi hook có kiểu, xem [tổng quan SDK](/vi/plugins/sdk-overview#hook-decision-semantics).
Để xem đầy đủ hành vi hook có kiểu, xem [tổng quan SDK](/vi/plugins/sdk-overview#hook-decision-semantics).
## Liên quan
- [Xây dựng plugin](/vi/plugins/building-plugins) — tạo plugin của riêng bạn
- [Bundle plugin](/vi/plugins/bundles) — khả năng tương thích bundle Codex/Claude/Cursor
- [Manifest plugin](/vi/plugins/manifest) — schema manifest
- [Đăng ký công cụ](/vi/plugins/building-plugins#registering-agent-tools) — thêm công cụ agent trong một plugin
- [Nội bộ plugin](/vi/plugins/architecture) — mô hình khả năng và pipeline tải
- [Xây dựng Plugin](/vi/plugins/building-plugins) — tạo Plugin của riêng bạn
- [Gói Plugin](/vi/plugins/bundles) — khả năng tương thích gói Codex/Claude/Cursor
- [Bản kê khai Plugin](/vi/plugins/manifest) — lược đồ bản kê khai
- [Đăng ký công cụ](/vi/plugins/building-plugins#registering-agent-tools) — thêm công cụ agent trong Plugin
- [Nội bộ Plugin](/vi/plugins/architecture) — mô hình capability và pipeline tải
- [Plugin cộng đồng](/vi/plugins/community) — danh sách của bên thứ ba

144
docs/vi/tools/thinking.md
View File

@ -1,96 +1,98 @@
---
read_when:
- Đ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ĩ
- Điều chỉnh việc phân tích cú pháp hoặc các giá trị mặc định cho suy luận, chế độ nhanh hoặc chỉ thị chi tiết
summary: Cú pháp chỉ thị cho /think, /fast, /verbose, /trace và mức hiển thị lập luận
title: Mức độ suy nghĩ
x-i18n:
generated_at: "2026-05-04T02:26:31Z"
generated_at: "2026-05-05T01:51:29Z"
model: gpt-5.5
provider: openai
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
## Chức năng
- Chỉ thị nội tuyến trong bất kỳ nội dung đến nào: `/t <level>`, `/think:<level>`, hoặc `/thinking <level>`.
- Chỉ thị nội tuyến trong bất kỳ nội dung gửi vào 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+” (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)
- xhigh → “ultrathink+” (các mô hình GPT-5.2+ và Codex, cộng với mức effort của Anthropic Claude Opus 4.7)
- adaptive → suy luận 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 luận độ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. 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 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` 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`.
- Menu và bộ chọn suy luận được điều khiển bởi hồ sơ nhà cung cấp. Plugin của nhà cung cấp khai báo tập mức chính xác cho mô hình đã chọn, bao gồm các nhãn như `on` dạng 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. Chỉ thị 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` lùi về `medium` trên các mô hình không thích ứng, còn `xhigh` và `max` lùi về mức khác `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 dùng `adaptive` khi không đặt mức suy luận rõ ràng.
- Anthropic Claude Opus 4.7 không mặc định dùng suy luận thích ứng. Mặc định effort API của nó vẫn do nhà cung cấp sở hữu trừ khi bạn đặt rõ một mức suy luận.
- Anthropic Claude Opus 4.7 ánh xạ `/think xhigh` tới suy luận thích ứng cộng với `output_config.effort: "xhigh"`, vì `/think` là chỉ thị suy luận 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 do nhà cung cấp sở hữu.
- Các mô hình DeepSeek V4 trực tiếp cung cấp `/think xhigh|max`; cả hai ánh xạ tới `reasoning_effort: "max"` của DeepSeek, trong khi các mức khác `off` thấp hơn ánh xạ tới `high`.
- Các mô hình DeepSeek V4 định tuyến qua OpenRouter cung cấp `/think xhigh` và gửi các giá trị `reasoning_effort` được OpenRouter hỗ trợ. Các ghi đè `max` đã lưu sẽ lùi về `xhigh`.
- Các mô hình Ollama có khả năng suy luận 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 GPT của OpenAI ánh xạ `/think` qua hỗ trợ effort theo từng mô hình 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 bị tắt thay vì gửi một giá trị không được hỗ trợ.
- Các mục danh mục 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"`. Cơ chế này dùng cùng metadata tương thích ánh xạ payload effort suy luận OpenAI gửi ra, để menu, xác thực phiên, CLI tác nhân, và `llm-task` thống nhất với hành vi truyền tải.
- Các tham chiếu OpenRouter Hunter Alpha đã cấu hình nhưng lỗi thời sẽ bỏ qua chèn suy luận proxy vì tuyến đã ngừng dùng đó có thể trả 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 luận động do nhà cung cấp sở hữu của Gemini. Yêu cầu Gemini 3 bỏ qua `thinkingLevel` cố định, còn 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 dùng `thinking: { type: "disabled" }` trừ khi bạn đặt rõ suy luận trong tham số mô hình hoặc tham số yêu cầu. Điều này tránh rò rỉ các delta `reasoning_content` từ định dạng stream Anthropic không gốc của MiniMax.
- Z.AI (`zai/*`) chỉ hỗ trợ suy luận nhị phân (`on`/`off`). Mọi mức khác `off` được xem là `on` (ánh xạ tới `low`).
- Moonshot (`moonshot/*`) ánh xạ `/think off` tới `thinking: { type: "disabled" }` và mọi mức khác `off` tới `thinking: { type: "enabled" }`. Khi suy luận đượ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ỉ gồm chỉ thị).
3. Mặc định theo tác tử (`agents.list[].thinkingDefault` trong cấu hình).
3. Mặc định theo từng tác nhân (`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` 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`.
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ác `off` được hỗ trợ gần nhất cho mô hình đó, còn các mô hình không suy luận giữ `off`.
## Đặt mặc định phiê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.
- Thiết lập đó được giữ cho phiên hiện tại (mặc định theo từng người gửi); được xóa bằng `/think:off` hoặc khi phiên đặt lại do 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.
- Gửi `/think` (hoặc `/think:`) không kèm đối số để xem mức suy luận hiện tại.
## Áp dụng theo tác tử
## Áp dụng theo tác nhân
- **Pi nhúng**: mức đã phân giải được truyền tới runtime tác tử Pi trong tiến trình.
- **Pi nhúng**: mức đã phân giải được truyền tới runtime tác nhân Pi trong tiến trình.
- **Backend Claude CLI**: các mức khác off được truyền tới Claude Code dưới dạng `--effort` khi dùng `claude-cli`; xem [backend CLI](/vi/gateway/cli-backends).
## Chế độ nhanh (/fast)
- Mức: `on|off`.
- 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.
- Gửi `/fast` (hoặc `/fast status`) không kèm 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ị 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`
3. Mặc định theo từng tác nhân (`agents.list[].fastModeDefault`)
4. Cấu hình theo từng 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 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.
- 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 chèn tầng dịch vụ Anthropic cho các URL gốc 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ỉ 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 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.
- Tin nhắn chỉ gồm chỉ thị bật/tắt chi tiết cho 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 giao diện 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, áp dụng mặc định phiên/toàn cục.
- Gửi `/verbose` (hoặc `/verbose:`) không kèm đối số để xem mức chi tiết hiện tại.
- Khi bật chi tiết, các tác nhân phát kết quả công cụ có cấu trúc (Pi, các tác nhân 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ỉ chứa metadata, 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 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ị ở chế độ 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 thiết lập mới.
- `agents.defaults.toolProgressDetail` điều khiển hình dạng tóm tắt công cụ `/verbose` và các dòng công cụ trong bản nháp tiến độ. Dùng `"explain"` (mặc định) cho nhãn ngắn gọn dành cho người dùng 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ừng tác nhân 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`
@ -98,46 +100,46 @@ x-i18n:
- Mức: `on` | `off` (mặc định).
- 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 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.
- Chỉ thị nội tuyến chỉ ảnh hưởng tới tin nhắn đó; nếu không, áp dụng mặc định phiên/toàn cục.
- Gửi `/trace` (hoặc `/trace:`) không kèm đố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 do Plugin sở hữu, chẳng hạn tóm tắt gỡ lỗi Active Memory.
- Các 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ý thông thường.
## Hiển thị suy luận (/reasoning)
- Mức: `on|off|stream`.
- 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): 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.
- Tin nhắn chỉ gồm chỉ thị bật/tắt việc hiển thị các khối suy luận trong phản hồi.
- Khi 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): stream suy luận vào bong bóng 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`).
- Gửi `/reasoning` (hoặc `/reasoning:`) không kèm đố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ừng tác nhân (`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 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.
Các thẻ suy luận của mô hình cục bộ 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 thông thường, và phần 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ẽ gửi dưới dạng văn bản trống, OpenClaw xóa thẻ mở sai định dạng đó và gửi phần văn bản còn lại.
## Liên quan
- Tài liệu chế độ nâng cao nằm trong [Chế độ nâng cao](/vi/tools/elevated).
- Tài liệu chế độ nâng quyền nằm trong [Chế độ nâng quyền](/vi/tools/elevated).
## 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).
- 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ử.
- Nội dung thăm dò 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.`). Các 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).
- Việc 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ừng tác nhân.
## UI trò chuyện web
## Giao diện trò chuyện web
- 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ộ.
- Bộ chọn suy luận của trò chuyện web phản chiếu mức đã lưu của phiên từ kho phiên/cấu hình gửi vào khi trang tải.
- Chọn mức khác sẽ 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 là ghi đè `thinkingOnce` dùng một lần.
- 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 luận 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` dùng.
- Bộ chọn dùng `thinkingLevels` do hàng phiên Gateway/mặc định trả về, với `thinkingOptions` được giữ làm danh sách nhãn kế thừa. Giao diện 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ị trò chuyện và bộ chọn luôn đồng bộ.
## Hồ sơ nhà cung cấp
- 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.
- Các plugin nhà cung cấp có thể cung cấp `resolveThinkingProfile(ctx)` để xác định các mức được mô hình hỗ trợ và mức mặc định.
- Các plugin nhà cung cấp proxy mô hình 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 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 một `label` hiển thị. Các 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 tự 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 cũ đã phát hành (`supportsXHighThinking`, `isBinaryThinking`, và `resolveDefaultThinkingLevel`) vẫn được giữ làm bộ chuyển đổi 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 hiển thị `thinkingLevels`, `thinkingOptions`, và `thinkingDefault` để các client ACP/chat hiển thị cùng các id hồ sơ và nhãn mà quá trình xác thực runtime sử dụng.

297
docs/vi/tools/video-generation.md
View File

@ -1,38 +1,44 @@
---
read_when:
- Tạo video thông qua tác tử
- Cấu hình nhà cung cấp và mô hình tạo video
- Cấu hình các nhà cung cấp và mô hình tạo video
- Tìm hiểu các tham số của công cụ video_generate
sidebarTitle: Video generation
summary: Tạo video qua video_generate từ các tham chiếu văn bản, hình ảnh hoặc video trên 16 hệ thống phụ trợ của nhà cung cấp
summary: Tạo video qua video_generate từ các tham chiếu văn bản, hình ảnh hoặc video trên 16 phần phụ trợ của nhà cung cấp
title: Tạo video
x-i18n:
generated_at: "2026-04-29T23:22:26Z"
generated_at: "2026-05-05T01:51:48Z"
model: gpt-5.5
provider: openai
source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_path: tools/video-generation.md
workflow: 16
---
Các agent OpenClaw có thể tạo video từ prompt văn bản, hình ảnh tham chiếu hoặc video hiện có. Mười sáu backend nhà cung cấp được hỗ trợ, mỗi backend có các tùy chọn mô hình, chế độ đầu vào và bộ tính năng khác nhau. Agent tự động chọn nhà cung cấp phù hợp dựa trên cấu hình và các khóa API có sẵn của bạn.
Các tác tử OpenClaw có thể tạo video từ lời nhắc văn bản, hình ảnh tham chiếu hoặc
video hiện có. Mười sáu phần phụ trợ nhà cung cấp được hỗ trợ, mỗi phần có
các tùy chọn mô hình, chế độ đầu vào và bộ tính năng khác nhau. Tác tử tự động chọn
nhà cung cấp phù hợp dựa trên cấu hình của bạn và các khóa API có sẵn.
<Note>
Công cụ `video_generate` chỉ xuất hiện khi có ít nhất một nhà cung cấp tạo video khả dụng. Nếu bạn không thấy công cụ này trong các công cụ của agent, hãy đặt khóa API của nhà cung cấp hoặc cấu hình `agents.defaults.videoGenerationModel`.
Công cụ `video_generate` chỉ xuất hiện khi có ít nhất một nhà cung cấp tạo video
khả dụng. Nếu bạn không thấy công cụ này trong các công cụ của tác tử, hãy đặt
khóa API của nhà cung cấp hoặc cấu hình `agents.defaults.videoGenerationModel`.
</Note>
OpenClaw xử lý tạo video theo ba chế độ runtime:
OpenClaw xem tạo video là ba chế độ runtime:
- `generate` — yêu cầu chuyển văn bản thành video không có phương tiện tham chiếu.
- `generate` — yêu cầu văn bản thành video không có phương tiện tham chiếu.
- `imageToVideo` — yêu cầu bao gồm một hoặc nhiều hình ảnh tham chiếu.
- `videoToVideo` — yêu cầu bao gồm một hoặc nhiều video tham chiếu.
Nhà cung cấp có thể hỗ trợ bất kỳ tập con nào của các chế độ đó. Công cụ xác thực chế độ đang hoạt động trước khi gửi và báo cáo các chế độ được hỗ trợ trong `action=list`.
Nhà cung cấp có thể hỗ trợ bất kỳ tập con nào của các chế độ đó. Công cụ xác thực
chế độ đang hoạt động trước khi gửi và báo cáo các chế độ được hỗ trợ trong `action=list`.
## Bắt đầu nhanh
<Steps>
<Step title="Cấu hình xác thực">
<Step title="Configure auth">
Đặt khóa API cho bất kỳ nhà cung cấp nào được hỗ trợ:
```bash
@ -40,42 +46,54 @@ Nhà cung cấp có thể hỗ trợ bất kỳ tập con nào của các chế
```
</Step>
<Step title="Chọn mô hình mặc định (tùy chọn)">
<Step title="Pick a default model (optional)">
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
</Step>
<Step title="Yêu cầu agent">
> Tạo một video điện ảnh dài 5 giây về một con tôm hùm thân thiện đang lướt sóng lúc hoàng hôn.
<Step title="Ask the agent">
> Tạo một video điện ảnh dài 5 giây về một chú tôm hùm thân thiện đang lướt sóng lúc hoàng hôn.
Agent tự động gọi `video_generate`. Không cần đưa công cụ vào danh sách cho phép.
Tác tử tự động gọi `video_generate`. Không cần đưa công cụ vào danh sách cho phép.
</Step>
</Steps>
## Cách tạo bất đồng bộ hoạt động
Tạo video là bất đồng bộ. Khi agent gọi `video_generate` trong một phiên:
Tạo video là bất đồng bộ. Khi tác tử gọi `video_generate` trong một
phiên:
1. OpenClaw gửi yêu cầu đến nhà cung cấp và ngay lập tức trả về một id tác vụ.
2. Nhà cung cấp xử lý công việc ở chế độ nền (thường từ 30 giây đến 5 phút tùy theo nhà cung cấp và độ phân giải).
1. OpenClaw gửi yêu cầu đến nhà cung cấp và ngay lập tức trả về id tác vụ.
2. Nhà cung cấp xử lý công việc trong nền (thường từ 30 giây đến 5 phút tùy theo nhà cung cấp và độ phân giải).
3. Khi video đã sẵn sàng, OpenClaw đánh thức cùng phiên đó bằng một sự kiện hoàn tất nội bộ.
4. Agent đăng video đã hoàn tất trở lại cuộc trò chuyện ban đầu.
4. Tác tử thông báo cho người dùng và đính kèm video hoàn tất. Trong các cuộc trò chuyện nhóm/kênh
dùng phương thức chuyển phát hiển thị chỉ qua công cụ tin nhắn, tác tử chuyển tiếp
kết quả qua công cụ tin nhắn thay vì để OpenClaw đăng trực tiếp.
Trong khi một công việc đang chạy, các lệnh gọi `video_generate` trùng lặp trong cùng phiên sẽ trả về trạng thái tác vụ hiện tại thay vì bắt đầu một lần tạo khác. Dùng `openclaw tasks list` hoặc `openclaw tasks show <taskId>` để kiểm tra tiến trình từ CLI.
Khi một công việc đang chạy, các lệnh gọi `video_generate` trùng lặp trong cùng
phiên sẽ trả về trạng thái tác vụ hiện tại thay vì bắt đầu một lần tạo khác.
Dùng `openclaw tasks list` hoặc `openclaw tasks show <taskId>` để kiểm tra tiến độ từ CLI.
Bên ngoài các lần chạy agent có phiên hỗ trợ (ví dụ: gọi công cụ trực tiếp), công cụ sẽ chuyển sang tạo nội tuyến và trả về đường dẫn phương tiện cuối cùng trong cùng lượt.
Bên ngoài các lần chạy tác tử có phiên hỗ trợ (ví dụ: gọi công cụ trực tiếp),
công cụ sẽ chuyển sang tạo nội tuyến và trả về đường dẫn phương tiện cuối cùng
trong cùng lượt.
Các tệp video được tạo sẽ được lưu trong kho lưu trữ phương tiện do OpenClaw quản lý khi nhà cung cấp trả về byte. Giới hạn lưu video được tạo mặc định tuân theo giới hạn phương tiện video, và `agents.defaults.mediaMaxMb` tăng giới hạn này cho các bản dựng lớn hơn. Khi nhà cung cấp cũng trả về URL đầu ra được lưu trữ, OpenClaw có thể gửi URL đó thay vì làm tác vụ thất bại nếu lưu cục bộ từ chối một tệp quá lớn.
Các tệp video được tạo sẽ được lưu trong bộ lưu trữ phương tiện do OpenClaw quản lý khi
nhà cung cấp trả về byte. Giới hạn lưu video được tạo mặc định tuân theo
giới hạn phương tiện video, và `agents.defaults.mediaMaxMb` tăng giới hạn đó cho
các kết xuất lớn hơn. Khi nhà cung cấp cũng trả về URL đầu ra được lưu trữ, OpenClaw
có thể chuyển phát URL đó thay vì làm tác vụ thất bại nếu quá trình lưu cục bộ
từ chối một tệp quá lớn.
### Vòng đời tác vụ
| Trạng thái | Ý nghĩa |
| Trạng thái | Ý nghĩa |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | Tác vụ đã được tạo, đang chờ nhà cung cấp chấp nhận. |
| `running` | Nhà cung cấp đang xử lý (thường từ 30 giây đến 5 phút tùy theo nhà cung cấp và độ phân giải). |
| `succeeded` | Video đã sẵn sàng; agent thức dậy và đăng video vào cuộc trò chuyện. |
| `failed` | Lỗi hoặc hết thời gian chờ từ nhà cung cấp; agent thức dậy với chi tiết lỗi. |
| `succeeded` | Video đã sẵn sàng; tác tử thức dậy và đăng video vào cuộc trò chuyện. |
| `failed` | Lỗi hoặc hết thời gian chờ từ nhà cung cấp; tác tử thức dậy với chi tiết lỗi. |
Kiểm tra trạng thái từ CLI:
@ -85,53 +103,59 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
Nếu một tác vụ video đã ở trạng thái `queued` hoặc `running` cho phiên hiện tại, `video_generate` trả về trạng thái tác vụ hiện có thay vì bắt đầu tác vụ mới. Dùng `action: "status"` để kiểm tra rõ ràng mà không kích hoạt lần tạo mới.
Nếu một tác vụ video đã ở trạng thái `queued` hoặc `running` cho phiên hiện tại,
`video_generate` sẽ trả về trạng thái tác vụ hiện có thay vì bắt đầu một tác vụ
mới. Dùng `action: "status"` để kiểm tra rõ ràng mà không kích hoạt một lần
tạo mới.
## Nhà cung cấp được hỗ trợ
| Nhà cung cấp | Mô hình mặc định | Văn bản | Tham chiếu hình ảnh | Tham chiếu video | Xác thực |
| Nhà cung cấp | Mô hình mặc định | Văn bản | Tham chiếu ảnh | Tham chiếu video | Xác thực |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Có (URL từ xa) | Có (URL từ xa) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Tối đa 2 hình ảnh (chỉ mô hình I2V; khung đầu + cuối) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Tối đa 2 hình ảnh (khung đầu + cuối qua vai trò) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Tối đa 9 hình ảnh tham chiếu | Tối đa 3 video | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 hình ảnh | — | `COMFY_API_KEY` hoặc `COMFY_CLOUD_API_KEY` |
| Alibaba | `wan2.6-t2v` | ✓ | Có (URL từ xa) | Có (URL từ xa) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Tối đa 2 ảnh (chỉ mô hình I2V; khung đầu + khung cuối) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Tối đa 2 ảnh (khung đầu + khung cuối qua vai trò) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Tối đa 9 hình ảnh tham chiếu | Tối đa 3 video | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 ảnh | — | `COMFY_API_KEY` hoặc `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 hình ảnh; tối đa 9 với Seedance reference-to-video | Tối đa 3 video với Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 hình ảnh | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 hình ảnh | — | `MINIMAX_API_KEY` hoặc MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 hình ảnh | 1 video | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Tối đa 4 hình ảnh (khung đầu/cuối hoặc tham chiếu) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Có (URL từ xa) | Có (URL từ xa) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 hình ảnh | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 hình ảnh | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 hình ảnh (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 hình ảnh khung đầu hoặc tối đa 7 `reference_image` | 1 video | `XAI_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 ảnh; tối đa 9 với Seedance reference-to-video | Tối đa 3 video với Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 ảnh | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 ảnh | — | `MINIMAX_API_KEY` hoặc MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 ảnh | 1 video | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Tối đa 4 ảnh (khung đầu/cuối hoặc tham chiếu) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Có (URL từ xa) | Có (URL từ xa) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 ảnh | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 ảnh | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 ảnh (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 ảnh khung đầu hoặc tối đa 7 `reference_image` | 1 video | `XAI_API_KEY` |
Một số nhà cung cấp chấp nhận thêm hoặc thay thế các biến môi trường khóa API. Xem từng [trang nhà cung cấp](#related) để biết chi tiết.
Một số nhà cung cấp chấp nhận thêm hoặc thay thế bằng các biến môi trường khóa API khác. Xem
từng [trang nhà cung cấp](#related) để biết chi tiết.
Chạy `video_generate action=list` để kiểm tra các nhà cung cấp, mô hình và chế độ runtime khả dụng tại thời điểm chạy.
Chạy `video_generate action=list` để kiểm tra các nhà cung cấp, mô hình và
chế độ runtime khả dụng tại runtime.
### Ma trận khả năng
### Ma trận năng lực
Hợp đồng chế độ tường minh được dùng bởi `video_generate`, các kiểm thử hợp đồng và lượt quét live dùng chung:
Hợp đồng chế độ rõ ràng được dùng bởi `video_generate`, kiểm thử hợp đồng và
lượt quét live dùng chung:
| Nhà cung cấp | `generate` | `imageToVideo` | `videoToVideo` | Các làn live dùng chung hiện nay |
| Nhà cung cấp | `generate` | `imageToVideo` | `videoToVideo` | Làn live dùng chung hôm nay |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` vì nhà cung cấp này cần URL video `http(s)` từ xa |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` vì nhà cung cấp này cần URL video `http(s)` từ xa |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Không nằm trong lượt quét dùng chung; phạm vi kiểm thử dành riêng cho workflow nằm trong các kiểm thử Comfy |
| DeepInfra | ✓ | — | — | `generate`; các schema video DeepInfra gốc là chuyển văn bản thành video trong hợp đồng đi kèm |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` chỉ khi dùng Seedance reference-to-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` dùng chung vì lượt quét Gemini/Veo dựa trên bộ đệm hiện tại không chấp nhận đầu vào đó |
| ComfyUI | ✓ | ✓ | — | Không nằm trong lượt quét dùng chung; phạm vi kiểm thử theo workflow nằm trong các kiểm thử Comfy |
| DeepInfra | ✓ | — | — | `generate`; các schema video DeepInfra gốc là văn bản thành video trong hợp đồng đi kèm |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` chỉ khi dùng Seedance reference-to-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` dùng chung vì lượt quét Gemini/Veo hiện tại dựa trên buffer không chấp nhận đầu vào đó |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` dùng chung vì đường dẫn tổ chức/đầu vào này hiện cần quyền truy cập inpaint/remix phía nhà cung cấp |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` vì nhà cung cấp này cần URL video `http(s)` từ xa |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` chỉ chạy khi mô hình được chọn là `runway/gen4_aleph` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` vì nhà cung cấp này cần URL video `http(s)` từ xa |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` chỉ chạy khi mô hình được chọn là `runway/gen4_aleph` |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`; bỏ qua `imageToVideo` dùng chung vì `veo3` đi kèm chỉ hỗ trợ văn bản và `kling` đi kèm yêu cầu URL hình ảnh từ xa |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` vì nhà cung cấp này hiện cần URL MP4 từ xa |
| Vydra | ✓ | ✓ | — | `generate`; bỏ qua `imageToVideo` dùng chung vì `veo3` đi kèm chỉ hỗ trợ văn bản và `kling` đi kèm yêu cầu URL ảnh từ xa |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; bỏ qua `videoToVideo` vì nhà cung cấp này hiện cần URL MP4 từ xa |
## Tham số công cụ
@ -146,32 +170,32 @@ Hợp đồng chế độ tường minh được dùng bởi `video_generate`, c
<ParamField path="image" type="string">Một hình ảnh tham chiếu (đường dẫn hoặc URL).</ParamField>
<ParamField path="images" type="string[]">Nhiều hình ảnh tham chiếu (tối đa 9).</ParamField>
<ParamField path="imageRoles" type="string[]">
Các gợi ý vai trò tùy chọn theo từng vị trí, song song với danh sách hình ảnh đã kết hợp.
Các giá trị chuẩn: `first_frame`, `last_frame`, `reference_image`.
Gợi ý vai trò tùy chọn theo từng vị trí, song song với danh sách hình ảnh đã kết hợp.
Giá trị chuẩn: `first_frame`, `last_frame`, `reference_image`.
</ParamField>
<ParamField path="video" type="string">Một video tham chiếu (đường dẫn hoặc URL).</ParamField>
<ParamField path="videos" type="string[]">Nhiều video tham chiếu (tối đa 4).</ParamField>
<ParamField path="videoRoles" type="string[]">
Các gợi ý vai trò tùy chọn theo từng vị trí, song song với danh sách video đã kết hợp.
Gợi ý vai trò tùy chọn theo từng vị trí, song song với danh sách video đã kết hợp.
Giá trị chuẩn: `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
Một âm thanh tham chiếu (đường dẫn hoặc URL). Dùng cho nhạc nền hoặc tham chiếu giọng nói
khi nhà cung cấp hỗ trợ đầu vào âm thanh.
Một âm thanh tham chiếu (đường dẫn hoặc URL). Dùng cho nhạc nền hoặc tham chiếu
giọng nói khi nhà cung cấp hỗ trợ đầu vào âm thanh.
</ParamField>
<ParamField path="audioRefs" type="string[]">Nhiều âm thanh tham chiếu (tối đa 3).</ParamField>
<ParamField path="audioRoles" type="string[]">
Các gợi ý vai trò tùy chọn theo từng vị trí, song song với danh sách âm thanh đã kết hợp.
Gợi ý vai trò tùy chọn theo từng vị trí, song song với danh sách âm thanh đã kết hợp.
Giá trị chuẩn: `reference_audio`.
</ParamField>
<Note>
Các gợi ý vai trò được chuyển tiếp nguyên trạng đến nhà cung cấp. Các giá trị chuẩn đến từ
Gợi ý vai trò được chuyển tiếp nguyên trạng đến nhà cung cấp. Các giá trị chuẩn đến từ
union `VideoGenerationAssetRole` nhưng nhà cung cấp có thể chấp nhận thêm
chuỗi vai trò khác. Mảng `*Roles` không được có nhiều mục hơn
danh sách tham chiếu tương ứng; lỗi lệch một đơn vị sẽ thất bại với thông báo lỗi rõ ràng.
chuỗi vai trò khác. Mảng `*Roles` không được có nhiều mục hơn danh sách
tham chiếu tương ứng; lỗi lệch một mục sẽ thất bại với thông báo lỗi rõ ràng.
Dùng chuỗi rỗng để bỏ đặt một vị trí. Với xAI, đặt mọi vai trò hình ảnh thành
`reference_image` để dùng chế độ tạo `reference_images` của nó; bỏ qua
`reference_image` để dùng chế độ tạo `reference_images`; bỏ qua
vai trò hoặc dùng `first_frame` cho chuyển hình ảnh đơn thành video.
</Note>
@ -191,36 +215,36 @@ vai trò hoặc dùng `first_frame` cho chuyển hình ảnh đơn thành video.
<ParamField path="watermark" type="boolean">Bật/tắt watermark của nhà cung cấp khi được hỗ trợ.</ParamField>
`adaptive` là một sentinel dành riêng cho nhà cung cấp: nó được chuyển tiếp nguyên trạng đến
các nhà cung cấp khai báo `adaptive` trong năng lực của họ (ví dụ BytePlus
những nhà cung cấp khai báo `adaptive` trong năng lực của họ (ví dụ BytePlus
Seedance dùng nó để tự động phát hiện tỷ lệ từ kích thước hình ảnh đầu vào).
Các nhà cung cấp không khai báo nó sẽ hiển thị giá trị qua
`details.ignoredOverrides` trong kết quả công cụ để có thể thấy phần bị bỏ qua.
Những nhà cung cấp không khai báo giá trị này sẽ hiển thị giá trị qua
`details.ignoredOverrides` trong kết quả công cụ để việc bỏ qua có thể nhìn thấy.
### Nâng cao
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` trả về tác vụ phiên hiện tại; `"list"` kiểm tra các nhà cung cấp.
`"status"` trả về tác vụ phiên hiện tại; `"list"` kiểm tra nhà cung cấp.
</ParamField>
<ParamField path="model" type="string">Ghi đè nhà cung cấp/mô hình (ví dụ `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">Gợi ý tên tệp đầu ra.</ParamField>
<ParamField path="timeoutMs" type="number">Thời gian chờ yêu cầu nhà cung cấp tùy chọn tính bằng mili giây.</ParamField>
<ParamField path="timeoutMs" type="number">Thời gian chờ yêu cầu nhà cung cấp tùy chọn, tính bằng mili giây.</ParamField>
<ParamField path="providerOptions" type="object">
Các tùy chọn dành riêng cho nhà cung cấp dưới dạng đối tượng JSON (ví dụ `{"seed": 42, "draft": true}`).
Các nhà cung cấp khai báo schema có kiểu sẽ xác thực khóa và kiểu; khóa không xác định
hoặc không khớp sẽ bỏ qua ứng viên trong quá trình fallback. Các nhà cung cấp không có
schema đã khai báo sẽ nhận nguyên trạng các tùy chọn. Chạy `video_generate action=list`
Tùy chọn dành riêng cho nhà cung cấp dưới dạng đối tượng JSON (ví dụ `{"seed": 42, "draft": true}`).
Nhà cung cấp khai báo schema có kiểu sẽ xác thực khóa và kiểu; khóa không xác định
hoặc không khớp sẽ bỏ qua ứng viên trong quá trình fallback. Nhà cung cấp không có
schema đã khai báo sẽ nhận tùy chọn nguyên trạng. Chạy `video_generate action=list`
để xem từng nhà cung cấp chấp nhận những gì.
</ParamField>
<Note>
Không phải mọi nhà cung cấp đều hỗ trợ mọi tham số. OpenClaw chuẩn hóa thời lượng thành
giá trị gần nhất mà nhà cung cấp hỗ trợ, và ánh xạ lại các gợi ý hình học đã chuyển đổi
như kích thước sang tỷ lệ khung hình khi một nhà cung cấp fallback cung cấp bề mặt điều khiển khác.
Các ghi đè thực sự không được hỗ trợ sẽ bị bỏ qua theo cách nỗ lực tối đa
và được báo cáo dưới dạng cảnh báo trong kết quả công cụ. Các giới hạn năng lực cứng
(chẳng hạn quá nhiều đầu vào tham chiếu) sẽ thất bại trước khi gửi. Kết quả công cụ
báo cáo các cài đặt đã áp dụng; `details.normalization` ghi lại mọi
chuyển đổi từ yêu cầu sang áp dụng.
Không phải nhà cung cấp nào cũng hỗ trợ mọi tham số. OpenClaw chuẩn hóa thời lượng thành
giá trị gần nhất mà nhà cung cấp hỗ trợ, và ánh xạ lại các gợi ý hình học đã dịch
như kích thước-thành-tỷ lệ-khung hình khi nhà cung cấp fallback hiển thị một
bề mặt điều khiển khác. Các ghi đè thật sự không được hỗ trợ được bỏ qua theo
cơ chế nỗ lực tối đa và được báo cáo dưới dạng cảnh báo trong kết quả công cụ.
Giới hạn năng lực cứng (chẳng hạn quá nhiều đầu vào tham chiếu) sẽ thất bại trước khi gửi.
Kết quả công cụ báo cáo các cài đặt đã áp dụng; `details.normalization` ghi lại mọi
chuyển đổi từ yêu cầu sang đã áp dụng.
</Note>
Đầu vào tham chiếu chọn chế độ runtime:
@ -229,56 +253,56 @@ chuyển đổi từ yêu cầu sang áp dụng.
- Bất kỳ tham chiếu hình ảnh nào → `imageToVideo`
- Bất kỳ tham chiếu video nào → `videoToVideo`
- Đầu vào âm thanh tham chiếu **không** thay đổi chế độ đã phân giải; chúng áp dụng
bên trên bất kỳ chế độ nào mà tham chiếu hình ảnh/video chọn, và chỉ hoạt động
trên chế độ mà tham chiếu hình ảnh/video chọn, và chỉ hoạt động
với các nhà cung cấp khai báo `maxInputAudios`.
Kết hợp tham chiếu hình ảnh và video không phải là một bề mặt năng lực dùng chung ổn định.
Trộn tham chiếu hình ảnh và video không phải là một bề mặt năng lực dùng chung ổn định.
Nên dùng một loại tham chiếu cho mỗi yêu cầu.
#### Fallback và tùy chọn có kiểu
Một số kiểm tra năng lực được áp dụng ở lớp fallback thay vì
ranh giới công cụ, vì vậy yêu cầu vượt quá giới hạn của nhà cung cấp chính vẫn có thể
chạy trên một fallback đủ năng lực:
ranh giới công cụ, vì vậy một yêu cầu vượt quá giới hạn của nhà cung cấp chính vẫn có thể
chạy trên một fallback có năng lực:
- Ứng viên đang hoạt động không khai báo `maxInputAudios` (hoặc `0`) sẽ bị bỏ qua khi
yêu cầu chứa tham chiếu âm thanh; ứng viên tiếp theo được thử.
- `maxDurationSeconds` của ứng viên đang hoạt động thấp hơn `durationSeconds` đã yêu cầu
và không có danh sách `supportedDurationSeconds` đã khai báo → bị bỏ qua.
- `maxDurationSeconds` của ứng viên đang hoạt động thấp hơn `durationSeconds` được yêu cầu
mà không có danh sách `supportedDurationSeconds` đã khai báo → bị bỏ qua.
- Yêu cầu chứa `providerOptions` và ứng viên đang hoạt động khai báo rõ ràng
schema `providerOptions` có kiểu → bị bỏ qua nếu các khóa được cung cấp
không nằm trong schema hoặc kiểu giá trị không khớp. Các nhà cung cấp không có
schema đã khai báo nhận nguyên trạng tùy chọn (truyền qua tương thích ngược).
Một nhà cung cấp có thể từ chối toàn bộ tùy chọn nhà cung cấp bằng cách
khai báo một schema rỗng (`capabilities.providerOptions: {}`), điều này
gây ra cùng kiểu bỏ qua như lỗi không khớp kiểu.
schema `providerOptions` có kiểu → bị bỏ qua nếu khóa được cung cấp không nằm
trong schema hoặc kiểu giá trị không khớp. Nhà cung cấp không có
schema đã khai báo sẽ nhận tùy chọn nguyên trạng (truyền qua tương thích ngược).
Một nhà cung cấp có thể chọn không nhận tất cả tùy chọn nhà cung cấp bằng cách
khai báo schema rỗng (`capabilities.providerOptions: {}`), điều này
gây ra cùng kiểu bỏ qua như khi kiểu không khớp.
Lý do bỏ qua đầu tiên trong một yêu cầu được ghi log ở mức `warn` để người vận hành thấy khi
nhà cung cấp chính của họ bị bỏ qua; các lần bỏ qua tiếp theo ghi log ở mức `debug` để
giữ cho các chuỗi fallback dài không quá ồn. Nếu mọi ứng viên đều bị bỏ qua, lỗi tổng hợp
sẽ bao gồm lý do bỏ qua cho từng ứng viên.
giữ các chuỗi fallback dài yên tĩnh. Nếu mọi ứng viên đều bị bỏ qua, lỗi
tổng hợp sẽ bao gồm lý do bỏ qua cho từng ứng viên.
## Hành động
| Hành động | Chức năng |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | Mặc định. Tạo video từ prompt đã cho và các đầu vào tham chiếu tùy chọn. |
| `status` | Kiểm tra trạng thái của tác vụ video đang chạy cho phiên hiện tại mà không bắt đầu một lần tạo khác. |
| `list` | Hiển thị các nhà cung cấp, mô hình và năng lực hiện có. |
| Hành động | Chức năng |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| `generate` | Mặc định. Tạo video từ prompt đã cho và các đầu vào tham chiếu tùy chọn. |
| `status` | Kiểm tra trạng thái của tác vụ video đang chạy cho phiên hiện tại mà không bắt đầu lần tạo khác. |
| `list` | Hiển thị các nhà cung cấp, mô hình và năng lực hiện có của họ. |
## Chọn mô hình
OpenClaw phân giải mô hình theo thứ tự này:
1. **Tham số công cụ `model`** — nếu tác tử chỉ định một mô hình trong lệnh gọi.
1. **Tham số công cụ `model`** — nếu agent chỉ định một mô hình trong lời gọi.
2. **`videoGenerationModel.primary`** từ cấu hình.
3. **`videoGenerationModel.fallbacks`** theo thứ tự.
4. **Tự động phát hiện** — các nhà cung cấp có xác thực hợp lệ, bắt đầu với
nhà cung cấp mặc định hiện tại, rồi các nhà cung cấp còn lại theo thứ tự
bảng chữ cái.
chữ cái.
Nếu một nhà cung cấp thất bại, ứng viên tiếp theo sẽ được thử tự động. Nếu tất cả
ứng viên đều thất bại, lỗi sẽ bao gồm chi tiết từ từng lần thử.
Nếu một nhà cung cấp thất bại, ứng viên tiếp theo được thử tự động. Nếu tất cả
ứng viên thất bại, lỗi sẽ bao gồm chi tiết từ từng lần thử.
Đặt `agents.defaults.mediaGenerationAutoProviderFallback: false` để chỉ dùng
các mục `model`, `primary` và `fallbacks` rõ ràng.
@ -311,12 +335,12 @@ các mục `model`, `primary` và `fallbacks` rõ ràng.
`seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`.
Mô hình T2V (`*-t2v-*`) không chấp nhận đầu vào hình ảnh; mô hình I2V và
mô hình `*-pro-*` tổng quát hỗ trợ một hình ảnh tham chiếu (khung hình đầu tiên).
Truyền hình ảnh theo vị trí hoặc đặt `role: "first_frame"`.
mô hình `*-pro-*` chung hỗ trợ một hình ảnh tham chiếu duy nhất (khung hình
đầu tiên). Truyền hình ảnh theo vị trí hoặc đặt `role: "first_frame"`.
ID mô hình T2V được tự động chuyển sang biến thể I2V tương ứng
khi có hình ảnh được cung cấp.
Các khóa `providerOptions` được hỗ trợ: `seed` (số), `draft` (boolean —
Khóa `providerOptions` được hỗ trợ: `seed` (number), `draft` (boolean —
buộc 480p), `camera_fixed` (boolean).
</Accordion>
@ -332,7 +356,7 @@ các mục `model`, `primary` và `fallbacks` rõ ràng.
`aspectRatio: "adaptive"` tự động phát hiện tỷ lệ từ hình ảnh đầu vào.
`audio: true` ánh xạ sang `generate_audio`. `providerOptions.seed`
(số) được chuyển tiếp.
(number) được chuyển tiếp.
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
@ -343,27 +367,27 @@ các mục `model`, `primary` và `fallbacks` rõ ràng.
Dùng API `content[]` hợp nhất. Hỗ trợ tối đa 9 hình ảnh tham chiếu,
3 video tham chiếu và 3 âm thanh tham chiếu. Mọi đầu vào phải là URL
`https://` từ xa. Đặt `role` trên từng tài sản — các giá trị được hỗ trợ:
`https://` từ xa. Đặt `role` trên từng asset — giá trị được hỗ trợ:
`"first_frame"`, `"last_frame"`, `"reference_image"`,
`"reference_video"`, `"reference_audio"`.
`aspectRatio: "adaptive"` tự động phát hiện tỷ lệ từ hình ảnh đầu vào.
`audio: true` ánh xạ sang `generate_audio`. `providerOptions.seed`
(số) được chuyển tiếp.
(number) được chuyển tiếp.
</Accordion>
<Accordion title="ComfyUI">
Thực thi cục bộ hoặc trên cloud theo workflow. Hỗ trợ chuyển văn bản thành video và
hình ảnh thành video thông qua đồ thị đã cấu hình.
Thực thi cục bộ hoặc trên đám mây theo workflow. Hỗ trợ chuyển văn bản thành video và
chuyển hình ảnh thành video thông qua graph đã cấu hình.
</Accordion>
<Accordion title="fal">
Dùng luồng có hàng đợi hỗ trợ cho các tác vụ chạy lâu. Hầu hết mô hình video fal
chấp nhận một tham chiếu hình ảnh duy nhất. Các mô hình tham chiếu thành video
Dùng luồng dựa trên hàng đợi cho các tác vụ chạy lâu. Hầu hết mô hình video fal
chấp nhận một tham chiếu hình ảnh duy nhất. Mô hình chuyển tham chiếu thành video
Seedance 2.0 chấp nhận tối đa 9 hình ảnh, 3 video và 3 tham chiếu âm thanh, với
tổng cộng tối đa 12 tệp tham chiếu.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
Hỗ trợ một tham chiếu hình ảnh hoặc một tham chiếu video.
Hỗ trợ một hình ảnh hoặc một video tham chiếu.
</Accordion>
<Accordion title="MiniMax">
Chỉ một tham chiếu hình ảnh duy nhất.
@ -376,7 +400,7 @@ các mục `model`, `primary` và `fallbacks` rõ ràng.
<Accordion title="OpenRouter">
Dùng API `/videos` bất đồng bộ của OpenRouter. OpenClaw gửi
tác vụ, thăm dò `polling_url`, và tải xuống `unsigned_urls` hoặc
endpoint nội dung tác vụ đã được tài liệu hóa. Mặc định `google/veo-3.1-fast` được đóng gói
endpoint nội dung tác vụ đã được ghi trong tài liệu. Giá trị mặc định `google/veo-3.1-fast` đi kèm
quảng bá thời lượng 4/6/8 giây, độ phân giải `720P`/`1080P`, và
tỷ lệ khung hình `16:9`/`9:16`.
</Accordion>
@ -385,30 +409,29 @@ các mục `model`, `primary` và `fallbacks` rõ ràng.
`http(s)` từ xa; tệp cục bộ bị từ chối ngay từ đầu.
</Accordion>
<Accordion title="Runway">
Hỗ trợ tệp cục bộ qua URI dữ liệu. Chuyển video thành video yêu cầu
`runway/gen4_aleph`. Các lần chạy chỉ văn bản cung cấp tỷ lệ khung hình
`16:9` và `9:16`.
Hỗ trợ tệp cục bộ qua data URI. Chuyển video thành video yêu cầu
`runway/gen4_aleph`. Chạy chỉ văn bản hiển thị tỷ lệ khung hình `16:9` và `9:16`.
</Accordion>
<Accordion title="Together">
Chỉ một tham chiếu hình ảnh duy nhất.
</Accordion>
<Accordion title="Vydra">
Dùng trực tiếp `https://www.vydra.ai/api/v1` để tránh các chuyển hướng
làm rơi xác thực. `veo3` được đóng gói chỉ cho chuyển văn bản thành video; `kling` yêu cầu
làm mất xác thực. `veo3` được tích hợp sẵn chỉ dưới dạng chuyển văn bản thành video; `kling` yêu cầu
URL hình ảnh từ xa.
</Accordion>
<Accordion title="xAI">
Hỗ trợ chuyển văn bản thành video, chuyển hình ảnh khung đầu tiên đơn thành video, tối đa 7
Hỗ trợ chuyển văn bản thành video, chuyển hình ảnh khung đầu tiên duy nhất thành video, tối đa 7
đầu vào `reference_image` thông qua `reference_images` của xAI, và các luồng
chỉnh sửa/mở rộng video từ xa.
</Accordion>
</AccordionGroup>
## Chế độ năng lực của nhà cung cấp
## Chế độ năng lực nhà cung cấp
Hợp đồng tạo video dùng chung hỗ trợ các khả năng theo từng chế độ
Hợp đồng tạo video dùng chung hỗ trợ các năng lực theo từng chế độ
thay vì chỉ các giới hạn tổng hợp phẳng. Các triển khai nhà cung cấp mới
nên ưu tiên các khối chế độ rõ ràng:
nên ưu tiên các khối chế độ tường minh:
```typescript
capabilities: {
@ -434,18 +457,18 @@ capabilities: {
```
Các trường tổng hợp phẳng như `maxInputImages` và `maxInputVideos`
**không** đủ để quảng bá hỗ trợ chế độ chuyển đổi. Nhà cung cấp nên
khai báo rõ ràng `generate`, `imageToVideo` và `videoToVideo` để các
kiểm thử trực tiếp, kiểm thử hợp đồng và công cụ dùng chung `video_generate`
**không** đủ để công bố hỗ trợ chế độ chuyển đổi. Nhà cung cấp nên
khai báo `generate`, `imageToVideo` và `videoToVideo` một cách tường minh
để kiểm thử live, kiểm thử hợp đồng và công cụ `video_generate` dùng chung
có thể xác thực hỗ trợ chế độ một cách xác định.
Khi một mô hình trong một nhà cung cấp hỗ trợ đầu vào tham chiếu rộng hơn
phần còn lại, hãy dùng `maxInputImagesByModel`, `maxInputVideosByModel` hoặc
Khi một mô hình trong một nhà cung cấp có hỗ trợ đầu vào tham chiếu rộng hơn
các mô hình còn lại, hãy dùng `maxInputImagesByModel`, `maxInputVideosByModel` hoặc
`maxInputAudiosByModel` thay vì tăng giới hạn trên toàn chế độ.
## Kiểm thử trực tiếp
## Kiểm thử live
Phạm vi kiểm thử trực tiếp dạng chọn tham gia cho các nhà cung cấp đi kèm dùng chung:
Bật tùy chọn kiểm thử live cho các nhà cung cấp đi kèm dùng chung:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -457,8 +480,8 @@ Trình bao bọc repo:
pnpm test:live:media video
```
Tệp kiểm thử trực tiếp này tải các biến môi trường nhà cung cấp còn thiếu từ `~/.profile`, mặc định ưu tiên
khóa API trực tiếp/từ môi trường hơn hồ sơ xác thực đã lưu, và mặc định chạy một
Tệp live này tải các biến môi trường nhà cung cấp còn thiếu từ `~/.profile`, mặc định ưu tiên
khóa API live/env trước các hồ sơ xác thực đã lưu, và mặc định chạy một
smoke an toàn cho phát hành:
- `generate` cho mọi nhà cung cấp không phải FAL trong lượt quét.
@ -466,7 +489,7 @@ smoke an toàn cho phát hành:
- Giới hạn thao tác theo từng nhà cung cấp từ
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (mặc định là `180000`).
FAL là chọn tham gia vì độ trễ hàng đợi phía nhà cung cấp có thể chiếm phần lớn
FAL là tùy chọn bật vì độ trễ hàng đợi phía nhà cung cấp có thể chiếm phần lớn
thời gian phát hành:
```bash
@ -480,7 +503,7 @@ chế độ chuyển đổi đã khai báo mà lượt quét dùng chung có th
- `videoToVideo` khi `capabilities.videoToVideo.enabled` và
nhà cung cấp/mô hình chấp nhận đầu vào video cục bộ dựa trên buffer trong lượt quét dùng chung.
Hiện tại làn trực tiếp `videoToVideo` dùng chung chỉ bao phủ `runway` khi bạn
Hiện tại, làn live `videoToVideo` dùng chung chỉ bao phủ `runway` khi bạn
chọn `runway/gen4_aleph`.
## Cấu hình
@ -521,6 +544,6 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
- [Qwen](/vi/providers/qwen)
- [Runway](/vi/providers/runway)
- [Together AI](/vi/providers/together)
- [Tổng quan về công cụ](/vi/tools)
- [Tổng quan công cụ](/vi/tools)
- [Vydra](/vi/providers/vydra)
- [xAI](/vi/providers/xai)

123
docs/vi/web/dashboard.md
View File

@ -1,18 +1,18 @@
---
read_when:
- Thay đổi chế độ xác thực hoặc chế độ công khai của bảng điều khiển
- Thay đổi xác thực bảng điều khiển hoặc chế độ hiển thị công khai
summary: Quyền truy cập và xác thực cho bảng điều khiển Gateway (Control UI)
title: Bảng điều khiển
x-i18n:
generated_at: "2026-04-29T23:23:08Z"
generated_at: "2026-05-05T01:51:43Z"
model: gpt-5.5
provider: openai
source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a
source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1
source_path: web/dashboard.md
workflow: 16
---
Gateway dashboard là giao diện điều khiển trên trình duyệt được phục vụ tại `/` theo mặc định
Bảng điều khiển Gateway là Giao diện điều khiển trên trình duyệt, mặc định được phục vụ tại `/`
(ghi đè bằng `gateway.controlUi.basePath`).
Mở nhanh (Gateway cục bộ):
@ -23,84 +23,89 @@ Mở nhanh (Gateway cục bộ):
Tài liệu tham khảo chính:
- [Giao diện điều khiển](/vi/web/control-ui) về cách sử dụng và khả năng của giao diện.
- [Tailscale](/vi/gateway/tailscale) về tự động hóa Serve/Funnel.
- [Bề mặt web](/vi/web) về chế độ bind và ghi chú bảo mật.
- [Giao diện điều khiển](/vi/web/control-ui) để biết cách sử dụng và khả năng của UI.
- [Tailscale](/vi/gateway/tailscale) cho tự động hóa Serve/Funnel.
- [Các bề mặt web](/vi/web) cho chế độ bind và ghi chú bảo mật.
Xác thực được thực thi tại bước bắt tay WebSocket thông qua đường dẫn xác thực Gateway
đã cấu hình:
Xác thực được áp dụng tại bước bắt tay WebSocket thông qua đường dẫn xác thực
gateway đã cấu hình:
- `connect.params.auth.token`
- `connect.params.auth.password`
- header định danh Tailscale Serve khi `gateway.auth.allowTailscale: true`
- header định danh trusted-proxy khi `gateway.auth.mode: "trusted-proxy"`
- header danh tính Tailscale Serve khi `gateway.auth.allowTailscale: true`
- header danh tính trusted-proxy khi `gateway.auth.mode: "trusted-proxy"`
Xem `gateway.auth` trong [Cấu hình Gateway](/vi/gateway/configuration).
Ghi chú bảo mật: giao diện điều khiển là **bề mặt quản trị** (chat, cấu hình, phê duyệt exec).
Không công khai nó ra internet. Giao diện lưu token trong URL dashboard vào sessionStorage
cho phiên tab trình duyệt hiện tại và URL Gateway đã chọn, rồi xóa chúng khỏi URL sau khi tải.
Ưu tiên localhost, Tailscale Serve, hoặc đường hầm SSH.
Ghi chú bảo mật: Giao diện điều khiển là một **bề mặt quản trị** (chat, cấu hình, phê duyệt exec).
Không công khai nó ra Internet. UI giữ token URL của bảng điều khiển trong sessionStorage
cho phiên tab trình duyệt hiện tại và URL gateway đã chọn, rồi xóa chúng khỏi URL sau khi tải.
Ưu tiên localhost, Tailscale Serve hoặc đường hầm SSH.
## Lộ trình nhanh (khuyến nghị)
## Đường nhanh (khuyến nghị)
- Sau khi onboarding, CLI tự động mở dashboard và in một liên kết sạch (không có token).
- Mở lại bất cứ lúc nào: `openclaw dashboard` (sao chép liên kết, mở trình duyệt nếu có thể, hiển thị gợi ý SSH nếu không có giao diện đồ họa).
- Nếu giao diện nhắc xác thực bằng shared-secret, hãy dán token hoặc
mật khẩu đã cấu hình vào phần cài đặt giao diện điều khiển.
- Sau khi onboarding, CLI tự động mở bảng điều khiển và in một liên kết sạch (không chứa token).
- Mở lại bất cứ lúc nào: `openclaw dashboard` (sao chép liên kết, mở trình duyệt nếu có thể, hiển thị gợi ý SSH nếu headless).
- Nếu không thể đưa qua clipboard và trình duyệt, `openclaw dashboard` vẫn in
URL sạch và cho bạn biết hãy dùng token từ `OPENCLAW_GATEWAY_TOKEN` hoặc
`gateway.auth.token` làm khóa phân mảnh URL `token`; lệnh không in giá trị
token trong log.
- Nếu UI yêu cầu xác thực bằng bí mật dùng chung, hãy dán token hoặc
mật khẩu đã cấu hình vào phần cài đặt Giao diện điều khiển.
## Kiến thức xác thực cơ bản (cục bộ so với từ xa)
## Cơ bản về xác thực (cục bộ và từ xa)
- **Localhost**: mở `http://127.0.0.1:18789/`.
- **Gateway TLS**: khi `gateway.tls.enabled: true`, liên kết dashboard/trạng thái dùng
`https://` và liên kết WebSocket của giao diện điều khiển dùng `wss://`.
- **Nguồn token shared-secret**: `gateway.auth.token` (hoặc
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` có thể truyền token qua fragment URL
để bootstrap một lần, và giao diện điều khiển giữ token trong sessionStorage cho
phiên tab trình duyệt hiện tại và URL Gateway đã chọn thay vì localStorage.
- Nếu `gateway.auth.token` do SecretRef quản lý, `openclaw dashboard`
sẽ in/sao chép/mở một URL không có token theo thiết kế. Việc này tránh làm lộ
token được quản lý bên ngoài trong log shell, lịch sử clipboard, hoặc tham số
- **Gateway TLS**: khi `gateway.tls.enabled: true`, liên kết bảng điều khiển/trạng thái dùng
`https://` và liên kết WebSocket của Giao diện điều khiển dùng `wss://`.
- **Nguồn token bí mật dùng chung**: `gateway.auth.token` (hoặc
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` có thể truyền token qua phân mảnh URL
để bootstrap một lần, và Giao diện điều khiển giữ token trong sessionStorage cho
phiên tab trình duyệt hiện tại và URL gateway đã chọn thay vì localStorage.
- Nếu `gateway.auth.token` được quản lý bằng SecretRef, theo thiết kế `openclaw dashboard`
sẽ in/sao chép/mở một URL không chứa token. Điều này tránh để lộ
token được quản lý bên ngoài trong log shell, lịch sử clipboard hoặc đối số
khởi chạy trình duyệt.
- Nếu `gateway.auth.token` được cấu hình là SecretRef và chưa được phân giải trong
shell hiện tại của bạn, `openclaw dashboard` vẫn in một URL không có token cùng
- Nếu `gateway.auth.token` được cấu hình dưới dạng SecretRef và chưa được resolve trong
shell hiện tại của bạn, `openclaw dashboard` vẫn in một URL không chứa token cùng
hướng dẫn thiết lập xác thực có thể thực hiện.
- **Mật khẩu shared-secret**: dùng `gateway.auth.password` đã cấu hình (hoặc
`OPENCLAW_GATEWAY_PASSWORD`). Dashboard không lưu mật khẩu qua các lần tải lại.
- **Chế độ mang định danh**: Tailscale Serve có thể đáp ứng xác thực giao diện điều khiển/WebSocket
qua header định danh khi `gateway.auth.allowTailscale: true`, và một reverse proxy
không phải loopback, nhận biết định danh có thể đáp ứng
`gateway.auth.mode: "trusted-proxy"`. Trong các chế độ đó, dashboard không
cần shared secret được dán cho WebSocket.
- **Không phải localhost**: dùng Tailscale Serve, một bind shared-secret không phải loopback, một
reverse proxy không phải loopback, nhận biết định danh với
`gateway.auth.mode: "trusted-proxy"`, hoặc một đường hầm SSH. API HTTP vẫn dùng
xác thực shared-secret trừ khi bạn chủ ý chạy ingress riêng
`gateway.auth.mode: "none"` hoặc xác thực HTTP trusted-proxy. Xem
[Bề mặt web](/vi/web).
- **Mật khẩu bí mật dùng chung**: dùng `gateway.auth.password` đã cấu hình (hoặc
`OPENCLAW_GATEWAY_PASSWORD`). Bảng điều khiển không lưu mật khẩu qua các lần
tải lại.
- **Chế độ mang danh tính**: Tailscale Serve có thể đáp ứng xác thực Giao diện điều khiển/WebSocket
bằng header danh tính khi `gateway.auth.allowTailscale: true`, và một
reverse proxy không phải loopback, nhận biết danh tính có thể đáp ứng
`gateway.auth.mode: "trusted-proxy"`. Trong các chế độ đó, bảng điều khiển không
cần dán bí mật dùng chung cho WebSocket.
- **Không phải localhost**: dùng Tailscale Serve, bind bí mật dùng chung không phải loopback, một
reverse proxy không phải loopback, nhận biết danh tính với
`gateway.auth.mode: "trusted-proxy"`, hoặc đường hầm SSH. HTTP API vẫn dùng
xác thực bằng bí mật dùng chung trừ khi bạn chủ ý chạy
`gateway.auth.mode: "none"` cho private-ingress hoặc xác thực HTTP trusted-proxy. Xem
[Các bề mặt web](/vi/web).
<a id="if-you-see-unauthorized-1008"></a>
## Nếu bạn thấy "unauthorized" / 1008
- Đảm bảo Gateway có thể truy cập được (cục bộ: `openclaw status`; từ xa: đường hầm SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` rồi mở `http://127.0.0.1:18789/`).
- Với `AUTH_TOKEN_MISMATCH`, client có thể thử lại một lần đáng tin cậy bằng token thiết bị đã lưu đệm khi Gateway trả về gợi ý thử lại. Lần thử lại bằng token đã lưu đệm đó tái sử dụng các phạm vi đã phê duyệt được lưu đệm của token; bên gọi dùng `deviceToken` rõ ràng / `scopes` rõ ràng giữ nguyên tập phạm vi đã yêu cầu. Nếu xác thực vẫn thất bại sau lần thử lại đó, hãy tự xử lý sai lệch token.
- Ngoài đường dẫn thử lại đó, thứ tự ưu tiên xác thực kết nối là token/mật khẩu dùng chung rõ ràng trước, sau đó `deviceToken` rõ ràng, rồi token thiết bị đã lưu, rồi token bootstrap.
- Trên đường dẫn giao diện điều khiển Tailscale Serve bất đồng bộ, các lần thử thất bại cho cùng
`{scope, ip}` được tuần tự hóa trước khi bộ giới hạn xác thực thất bại ghi nhận chúng, vì vậy
lần thử lại sai đồng thời thứ hai có thể đã hiển thị `retry later`.
- Để biết các bước sửa sai lệch token, hãy làm theo [Danh sách kiểm tra khôi phục sai lệch token](/vi/cli/devices#token-drift-recovery-checklist).
- Lấy hoặc cung cấp shared secret từ máy chủ Gateway:
- Đảm bảo gateway có thể truy cập được (cục bộ: `openclaw status`; từ xa: đường hầm SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` rồi mở `http://127.0.0.1:18789/`).
- Với `AUTH_TOKEN_MISMATCH`, client có thể thực hiện một lần thử lại đáng tin cậy bằng token thiết bị đã lưu trong cache khi gateway trả về gợi ý thử lại. Lần thử lại bằng token đã lưu cache đó tái sử dụng các phạm vi đã phê duyệt được lưu cache của token; caller dùng `deviceToken` tường minh / `scopes` tường minh sẽ giữ tập phạm vi đã yêu cầu. Nếu xác thực vẫn thất bại sau lần thử lại đó, hãy xử lý drift token thủ công.
- Bên ngoài đường dẫn thử lại đó, thứ tự ưu tiên xác thực khi kết nối là token/mật khẩu dùng chung tường minh trước, rồi `deviceToken` tường minh, rồi token thiết bị đã lưu, rồi token bootstrap.
- Trên đường dẫn Giao diện điều khiển Tailscale Serve bất đồng bộ, các lần thử thất bại cho cùng
`{scope, ip}` được tuần tự hóa trước khi bộ giới hạn xác thực thất bại ghi nhận chúng, nên
lần thử lại xấu đồng thời thứ hai có thể đã hiển thị `retry later`.
- Để biết các bước sửa drift token, hãy làm theo [Danh sách kiểm tra khôi phục drift token](/vi/cli/devices#token-drift-recovery-checklist).
- Lấy hoặc cung cấp bí mật dùng chung từ máy chủ gateway:
- Token: `openclaw config get gateway.auth.token`
- Mật khẩu: phân giải `gateway.auth.password` đã cấu hình hoặc
- Mật khẩu: resolve `gateway.auth.password` đã cấu hình hoặc
`OPENCLAW_GATEWAY_PASSWORD`
- Token do SecretRef quản lý: phân giải nhà cung cấp secret bên ngoài hoặc export
- Token do SecretRef quản lý: resolve nhà cung cấp bí mật bên ngoài hoặc export
`OPENCLAW_GATEWAY_TOKEN` trong shell này, rồi chạy lại `openclaw dashboard`
- Chưa cấu hình shared secret: `openclaw doctor --generate-gateway-token`
- Trong phần cài đặt dashboard, dán token hoặc mật khẩu vào trường xác thực,
- Chưa cấu hình bí mật dùng chung: `openclaw doctor --generate-gateway-token`
- Trong phần cài đặt bảng điều khiển, dán token hoặc mật khẩu vào trường xác thực,
rồi kết nối.
- Bộ chọn ngôn ngữ của giao diện nằm trong **Tổng quan -> Truy cập Gateway -> Ngôn ngữ**.
Nó là một phần của thẻ truy cập, không phải phần Giao diện.
- Bộ chọn ngôn ngữ UI nằm trong **Tổng quan -> Quyền truy cập Gateway -> Ngôn ngữ**.
Nó là một phần của thẻ truy cập, không phải mục Giao diện.
## Liên quan