diff --git a/docs/vi/automation/tasks.md b/docs/vi/automation/tasks.md index 5697ca30c..53c632a83 100644 --- a/docs/vi/automation/tasks.md +++ b/docs/vi/automation/tasks.md @@ -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 --- -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. -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. -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ó. -## 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` | - - 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. + + 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 đó. - - 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. + + 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. - 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. -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. -Đ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 state_changes @@ -192,7 +192,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--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. @@ -200,7 +200,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - 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. @@ -208,7 +208,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - 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. @@ -221,16 +221,16 @@ openclaw tasks notify 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) | @@ -239,21 +239,21 @@ openclaw tasks notify 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ụ. @@ -264,22 +264,22 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - 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ẻ. -## 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: - - 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`. + + 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`. - - Đó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. + + Đó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. - - Đặ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. + + Đặ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. - - Xóa các bản ghi đã quá ngày `cleanupAfter`. + + Xóa các bản ghi đã qua ngày `cleanupAfter`. -**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. -## 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 - - [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. + + [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. - - 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. + + 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). - - 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. + + 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). - - 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 đó. + + 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 đó. - - `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. + + `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. ## 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ụ diff --git a/docs/vi/channels/slack.md b/docs/vi/channels/slack.md index 94b21f434..a17986a34 100644 --- a/docs/vi/channels/slack.md +++ b/docs/vi/channels/slack.md @@ -1,47 +1,204 @@ --- read_when: - Thiết lập Slack hoặc gỡ lỗi chế độ socket/HTTP của Slack -summary: Thiết lập Slack và hành vi thời gian chạy (Socket Mode + URL yêu cầu HTTP) +summary: Thiết lập Slack và hành vi khi chạy (Chế độ Socket + URL yêu cầu HTTP) title: Slack x-i18n: - generated_at: "2026-05-04T07:02:45Z" + generated_at: "2026-05-05T01:44:04Z" model: gpt-5.5 provider: openai - source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 + source_hash: 9a8e1cbfd3d99bfc24d79b56ee762d1ab399402391b241ff40698249b0828008 source_path: channels/slack.md workflow: 16 --- -Sẵn sàng cho môi trường sản xuất cho DM và kênh thông qua tích hợp ứng dụng Slack. Chế độ mặc định là Chế độ Socket; URL Yêu cầu HTTP cũng được hỗ trợ. +Sẵn sàng cho môi trường production cho tin nhắn trực tiếp và kênh thông qua tích hợp ứng dụng Slack. Chế độ mặc định là Socket Mode; HTTP Request URLs cũng được hỗ trợ. - - DM Slack mặc định dùng chế độ ghép nối. + + Tin nhắn trực tiếp Slack mặc định dùng chế độ ghép nối. - + Hành vi lệnh gốc và danh mục lệnh. - - Chẩn đoán liên kênh và playbook sửa chữa. + + Chẩn đoán liên kênh và sổ tay sửa chữa. +## Chọn Socket Mode hoặc HTTP Request URLs + +Cả hai phương thức truyền đều sẵn sàng cho môi trường production và đạt ngang bằng tính năng cho nhắn tin, lệnh gạch chéo, App Home và tính tương tác. Chọn theo mô hình triển khai, không phải theo tính năng. + +| Mối quan tâm | Socket Mode (mặc định) | HTTP Request URLs | +| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| URL Gateway công khai | Không bắt buộc | Bắt buộc (DNS, TLS, reverse proxy hoặc tunnel) | +| Mạng outbound | WSS outbound tới `wss-primary.slack.com` phải truy cập được | Không có WS outbound; chỉ HTTPS inbound | +| Token cần thiết | Bot token (`xoxb-...`) + App-Level Token (`xapp-...`) với `connections:write` | Bot token (`xoxb-...`) + Signing Secret | +| Laptop dev / sau tường lửa | Hoạt động nguyên trạng | Cần tunnel công khai (ngrok, Cloudflare Tunnel, Tailscale Funnel) hoặc Gateway staging | +| Mở rộng ngang | Một phiên Socket Mode cho mỗi ứng dụng trên mỗi host; nhiều Gateway cần ứng dụng Slack riêng | Trình xử lý POST không trạng thái; nhiều bản sao Gateway có thể dùng chung một ứng dụng sau load balancer | +| Nhiều tài khoản trên một Gateway | Được hỗ trợ; mỗi tài khoản mở WS riêng | Được hỗ trợ; mỗi tài khoản cần một `webhookPath` duy nhất (mặc định `/slack/events`) để đăng ký không xung đột | +| Phương thức truyền lệnh gạch chéo | Được gửi qua kết nối WS; `slash_commands[].url` bị bỏ qua | Slack POST tới `slash_commands[].url`; trường này là bắt buộc để lệnh được dispatch | +| Ký request | Không dùng (xác thực là App-Level Token) | Slack ký mọi request; OpenClaw xác minh bằng `signingSecret` | +| Khôi phục khi rớt kết nối | Slack SDK tự động kết nối lại; cấu hình transport pong-timeout của gateway được áp dụng | Không có kết nối liên tục để bị rớt; retry theo từng request từ Slack | + + + **Chọn Socket Mode** cho host một Gateway, laptop dev và mạng on-prem có thể truy cập outbound tới `*.slack.com` nhưng không thể nhận HTTPS inbound. + +**Chọn HTTP Request URLs** khi chạy nhiều bản sao Gateway sau load balancer, khi WSS outbound bị chặn nhưng HTTPS inbound được phép, hoặc khi bạn đã terminate Slack webhook tại reverse proxy. + + ## Thiết lập nhanh - + - - Trong phần cài đặt ứng dụng Slack, nhấn nút **[Tạo ứng dụng mới](https://api.slack.com/apps/new)**: + + Mở [api.slack.com/apps](https://api.slack.com/apps/new) → **Create New App** → **From a manifest** → chọn workspace của bạn → dán một trong các manifest bên dưới → **Next** → **Create**. - - chọn **từ manifest** và chọn một workspace cho ứng dụng của bạn - - dán [manifest ví dụ](#manifest-and-scope-checklist) bên dưới rồi tiếp tục tạo - - tạo **App-Level Token** (`xapp-...`) với `connections:write` - - cài đặt ứng dụng và sao chép **Bot Token** (`xoxb-...`) được hiển thị + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": 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" + ] + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + } + } +} +``` + + + + + **Recommended** khớp với bộ tính năng đầy đủ của Slack Plugin đi kèm: App Home, lệnh gạch chéo, tệp, phản ứng, ghim, tin nhắn trực tiếp nhóm và quyền đọc emoji/usergroup. Chọn **Minimal** khi chính sách workspace giới hạn scope — nó bao phủ tin nhắn trực tiếp, lịch sử kênh/nhóm, lượt nhắc và lệnh gạch chéo nhưng bỏ tệp, phản ứng, ghim, group-DM (`mpim:*`), `emoji:read` và `usergroups:read`. Xem [Danh sách kiểm tra manifest và scope](#manifest-and-scope-checklist) để biết lý do cho từng scope và các tùy chọn bổ sung như lệnh gạch chéo thêm. + + + Sau khi Slack tạo ứng dụng: + + - **Basic Information → App-Level Tokens → Generate Token and Scopes**: thêm `connections:write`, lưu, sao chép giá trị `xapp-...`. + - **Install App → Install to Workspace**: sao chép `xoxb-...` Bot User OAuth Token. - + Thiết lập SecretRef được khuyến nghị: @@ -64,7 +221,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - Phương án dự phòng bằng env (chỉ tài khoản mặc định): + Phương án dự phòng env (chỉ tài khoản mặc định): ```bash SLACK_APP_TOKEN=xapp-... @@ -73,7 +230,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,19 +241,170 @@ openclaw gateway - + - - Trong phần cài đặt ứng dụng Slack, nhấn nút **[Tạo ứng dụng mới](https://api.slack.com/apps/new)**: + + Mở [api.slack.com/apps](https://api.slack.com/apps/new) → **Create New App** → **From a manifest** → chọn workspace của bạn → dán một trong các manifest bên dưới → thay `https://gateway-host.example.com/slack/events` bằng URL Gateway công khai của bạn → **Next** → **Create**. - - chọn **từ manifest** và chọn một workspace cho ứng dụng của bạn - - dán [manifest ví dụ](#manifest-and-scope-checklist) và cập nhật các URL trước khi tạo - - lưu **Signing Secret** để xác minh yêu cầu - - cài đặt ứng dụng và sao chép **Bot Token** (`xoxb-...`) được hiển thị + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "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": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "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" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + **Được khuyến nghị** khớp với toàn bộ bộ tính năng của Slack Plugin đi kèm; **Tối thiểu** loại bỏ tệp, phản ứng, ghim, nhóm DM (`mpim:*`), `emoji:read` và `usergroups:read` cho các workspace hạn chế. Xem [Danh sách kiểm tra manifest và phạm vi](#manifest-and-scope-checklist) để biết lý do cho từng phạm vi. + + + + Ba trường URL (`slash_commands[].url`, `event_subscriptions.request_url` và `interactivity.request_url` / `message_menu_options_url`) đều trỏ đến cùng một endpoint OpenClaw. Lược đồ manifest của Slack yêu cầu chúng được đặt tên riêng, nhưng OpenClaw định tuyến theo loại payload nên chỉ cần một `webhookPath` duy nhất (mặc định `/slack/events`) là đủ. Slash command không có `slash_commands[].url` sẽ âm thầm không làm gì trong chế độ HTTP. + + + Sau khi Slack tạo ứng dụng: + + - **Basic Information → App Credentials**: sao chép **Signing Secret** để xác minh yêu cầu. + - **Install App → Install to Workspace**: sao chép Bot User OAuth Token `xoxb-...`. - + Thiết lập SecretRef được khuyến nghị: @@ -121,14 +429,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - Dùng đường dẫn webhook duy nhất cho HTTP nhiều tài khoản + Dùng đường dẫn Webhook riêng cho HTTP nhiều tài khoản - Cấp cho mỗi tài khoản một `webhookPath` riêng biệt (mặc định `/slack/events`) để các đăng ký không xung đột. + Cấp cho mỗi tài khoản một `webhookPath` riêng biệt (mặc định `/slack/events`) để các đăng ký không va chạm. - + ```bash openclaw gateway @@ -142,7 +450,7 @@ openclaw gateway ## Tinh chỉnh truyền tải Socket Mode -OpenClaw đặt thời gian chờ pong của máy khách Slack SDK mặc định là 15 giây cho Socket Mode. Chỉ ghi đè cài đặt truyền tải khi bạn cần tinh chỉnh riêng cho workspace hoặc máy chủ: +Theo mặc định, OpenClaw đặt thời gian chờ pong của client Slack SDK là 15 giây cho Socket Mode. Chỉ ghi đè cài đặt truyền tải khi bạn cần tinh chỉnh theo workspace hoặc host cụ thể: ```json5 { @@ -159,11 +467,11 @@ OpenClaw đặt thời gian chờ pong của máy khách Slack SDK mặc định } ``` -Chỉ dùng tùy chọn này cho các workspace Socket Mode ghi log thời gian chờ pong/server-ping của websocket Slack hoặc chạy trên các máy chủ đã biết có tình trạng vòng lặp sự kiện bị đói tài nguyên. `clientPingTimeout` là thời gian chờ pong sau khi SDK gửi ping từ máy khách; `serverPingTimeout` là thời gian chờ ping từ máy chủ Slack. Tin nhắn và sự kiện của ứng dụng vẫn là trạng thái ứng dụng, không phải tín hiệu về trạng thái sống của truyền tải. +Chỉ dùng tùy chọn này cho các workspace Socket Mode ghi log lỗi hết thời gian chờ pong/server-ping của websocket Slack hoặc chạy trên các host đã biết là bị nghẽn event loop. `clientPingTimeout` là thời gian chờ pong sau khi SDK gửi client ping; `serverPingTimeout` là thời gian chờ ping từ máy chủ Slack. Tin nhắn và sự kiện của ứng dụng vẫn là trạng thái ứng dụng, không phải tín hiệu về độ hoạt động của truyền tải. ## Danh sách kiểm tra manifest và phạm vi -Manifest cơ sở của ứng dụng Slack giống nhau cho Socket Mode và HTTP Request URLs. Chỉ khối `settings` (và `url` của lệnh slash) khác nhau. +Manifest ứng dụng Slack cơ sở giống nhau cho Socket Mode và HTTP Request URLs. Chỉ khối `settings` (và `url` của slash command) là khác. Manifest cơ sở (mặc định Socket Mode): @@ -240,7 +548,7 @@ Manifest cơ sở (mặc định Socket Mode): } ``` -Đối với **chế độ HTTP Request URLs**, hãy thay `settings` bằng biến thể HTTP và thêm `url` vào từng lệnh slash. Bắt buộc phải có URL công khai: +Đối với **chế độ HTTP Request URLs**, thay `settings` bằng biến thể HTTP và thêm `url` vào từng slash command. Cần có URL công khai: ```json { @@ -284,17 +592,17 @@ Manifest cơ sở (mặc định Socket Mode): ### Cài đặt manifest bổ sung -Hiển thị các tính năng khác nhau mở rộng các mặc định ở trên. +Hiển thị các tính năng khác mở rộng các mặc định ở trên. -Manifest mặc định bật thẻ **Home** trong Slack App Home và đăng ký `app_home_opened`. Khi một thành viên workspace mở thẻ Home, OpenClaw xuất bản một chế độ xem Home mặc định an toàn bằng `views.publish`; không bao gồm payload hội thoại hoặc cấu hình riêng tư. Thẻ **Messages** vẫn được bật cho DM Slack. +Manifest mặc định bật tab **Home** của Slack App Home và đăng ký `app_home_opened`. Khi một thành viên workspace mở tab Home, OpenClaw xuất bản một chế độ xem Home mặc định an toàn bằng `views.publish`; không bao gồm payload cuộc trò chuyện hay cấu hình riêng tư. Tab **Messages** vẫn được bật cho Slack DM. - Có thể dùng nhiều [lệnh slash gốc](#commands-and-slash-behavior) thay cho một lệnh được cấu hình duy nhất, với vài điểm cần lưu ý: + Có thể dùng nhiều [slash command gốc](#commands-and-slash-behavior) thay cho một lệnh được cấu hình duy nhất, với một số điểm cần lưu ý: - Dùng `/agentstatus` thay vì `/status` vì lệnh `/status` đã được dành riêng. - - Không thể cung cấp hơn 25 lệnh slash cùng lúc. + - Không thể cung cấp hơn 25 slash command cùng lúc. Thay phần `features.slash_commands` hiện có của bạn bằng một tập con của [các lệnh có sẵn](/vi/tools/slash-commands#command-list): @@ -423,7 +731,7 @@ Manifest mặc định bật thẻ **Home** trong Slack App Home và đăng ký - Dùng cùng danh sách `slash_commands` như Socket Mode ở trên và thêm `"url": "https://gateway-host.example.com/slack/events"` vào mọi mục. Ví dụ: + Dùng cùng danh sách `slash_commands` như Socket Mode ở trên, và thêm `"url": "https://gateway-host.example.com/slack/events"` vào mọi mục. Ví dụ: ```json { @@ -449,13 +757,13 @@ Manifest mặc định bật thẻ **Home** trong Slack App Home và đăng ký - - Thêm phạm vi bot `chat:write.customize` nếu bạn muốn tin nhắn gửi đi sử dụng danh tính tác nhân đang hoạt động (tên người dùng và biểu tượng tùy chỉnh) thay vì danh tính ứng dụng Slack mặc định. + + Thêm phạm vi bot `chat:write.customize` nếu bạn muốn tin nhắn gửi đi dùng danh tính tác nhân đang hoạt động (tên người dùng và biểu tượng tùy chỉnh) thay vì danh tính ứng dụng Slack mặc định. Nếu bạn dùng biểu tượng emoji, Slack yêu cầu cú pháp `:emoji_name:`. - + Nếu bạn cấu hình `channels.slack.userToken`, các phạm vi đọc điển hình là: - `channels:history`, `groups:history`, `im:history`, `mpim:history` @@ -464,7 +772,7 @@ Manifest mặc định bật thẻ **Home** trong Slack App Home và đăng ký - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (nếu bạn phụ thuộc vào lượt đọc tìm kiếm Slack) + - `search:read` (nếu bạn phụ thuộc vào việc đọc tìm kiếm Slack) @@ -475,30 +783,30 @@ Manifest mặc định bật thẻ **Home** trong Slack App Home và đăng ký - Chế độ HTTP yêu cầu `botToken` + `signingSecret`. - `botToken`, `appToken`, `signingSecret` và `userToken` chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef. -- Token cấu hình ghi đè dự phòng env. -- Dự phòng env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` chỉ áp dụng cho tài khoản mặc định. -- `userToken` (`xoxp-...`) chỉ dùng trong cấu hình (không có dự phòng env) và mặc định có hành vi chỉ đọc (`userTokenReadOnly: true`). +- Token trong cấu hình ghi đè phương án dự phòng env. +- Phương án dự phòng env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` chỉ áp dụng cho tài khoản mặc định. +- `userToken` (`xoxp-...`) chỉ có trong cấu hình (không có phương án dự phòng env) và mặc định có hành vi chỉ đọc (`userTokenReadOnly: true`). -Hành vi ảnh chụp nhanh trạng thái: +Hành vi ảnh chụp trạng thái: - Việc kiểm tra tài khoản Slack theo dõi các trường `*Source` và `*Status` theo từng thông tin xác thực (`botToken`, `appToken`, `signingSecret`, `userToken`). - Trạng thái là `available`, `configured_unavailable` hoặc `missing`. - `configured_unavailable` nghĩa là tài khoản được cấu hình qua SecretRef - hoặc một nguồn bí mật không nội tuyến khác, nhưng đường dẫn lệnh/runtime hiện tại - không thể phân giải giá trị thực. + hoặc một nguồn bí mật không nội tuyến khác, nhưng lệnh/đường dẫn runtime hiện tại + không thể phân giải giá trị thực tế. - Trong chế độ HTTP, `signingSecretStatus` được bao gồm; trong Socket Mode, cặp bắt buộc là `botTokenStatus` + `appTokenStatus`. -Đối với thao tác/lượt đọc thư mục, user token có thể được ưu tiên khi đã cấu hình. Đối với ghi, bot token vẫn được ưu tiên; ghi bằng user-token chỉ được cho phép khi `userTokenReadOnly: false` và bot token không khả dụng. +Đối với hành động/đọc thư mục, token người dùng có thể được ưu tiên khi đã cấu hình. Đối với thao tác ghi, token bot vẫn được ưu tiên; thao tác ghi bằng token người dùng chỉ được phép khi `userTokenReadOnly: false` và token bot không khả dụng. -## Thao tác và cổng kiểm soát +## Hành động và cổng kiểm soát -Các thao tác Slack được kiểm soát bởi `channels.slack.actions.*`. +Hành động Slack được kiểm soát bằng `channels.slack.actions.*`. -Các nhóm thao tác có sẵn trong công cụ Slack hiện tại: +Các nhóm hành động có sẵn trong công cụ Slack hiện tại: | Nhóm | Mặc định | | ---------- | -------- | @@ -508,13 +816,13 @@ Các nhóm thao tác có sẵn trong công cụ Slack hiện tại: | memberInfo | bật | | emojiList | bật | -Các thao tác tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` và `emoji-list`. `download-file` chấp nhận ID tệp Slack được hiển thị trong placeholder tệp đến và trả về bản xem trước ảnh cho hình ảnh hoặc metadata tệp cục bộ cho các loại tệp khác. +Các hành động tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` và `emoji-list`. `download-file` chấp nhận ID tệp Slack hiển thị trong placeholder tệp đến và trả về bản xem trước ảnh cho hình ảnh hoặc siêu dữ liệu tệp cục bộ cho các loại tệp khác. ## Kiểm soát truy cập và định tuyến - - `channels.slack.dmPolicy` kiểm soát quyền truy cập DM. `channels.slack.allowFrom` là allowlist DM chính thức. + + `channels.slack.dmPolicy` kiểm soát quyền truy cập DM. `channels.slack.allowFrom` là danh sách cho phép DM chuẩn. - `pairing` (mặc định) - `allowlist` @@ -527,12 +835,12 @@ Các thao tác tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `d - `channels.slack.allowFrom` - `dm.allowFrom` (cũ) - `dm.groupEnabled` (DM nhóm mặc định false) - - `dm.groupChannels` (allowlist MPIM tùy chọn) + - `dm.groupChannels` (danh sách cho phép MPIM tùy chọn) - Thứ tự ưu tiên nhiều tài khoản: + Thứ tự ưu tiên đa tài khoản: - `channels.slack.accounts.default.allowFrom` chỉ áp dụng cho tài khoản `default`. - - Tài khoản có tên kế thừa `channels.slack.allowFrom` khi `allowFrom` riêng của chúng chưa được đặt. + - Tài khoản có tên kế thừa `channels.slack.allowFrom` khi `allowFrom` riêng chưa được đặt. - Tài khoản có tên không kế thừa `channels.slack.accounts.default.allowFrom`. `channels.slack.dm.policy` và `channels.slack.dm.allowFrom` cũ vẫn được đọc để tương thích. `openclaw doctor --fix` di chuyển chúng sang `dmPolicy` và `allowFrom` khi có thể làm vậy mà không thay đổi quyền truy cập. @@ -541,25 +849,25 @@ Các thao tác tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `d - + `channels.slack.groupPolicy` kiểm soát cách xử lý kênh: - `open` - `allowlist` - `disabled` - Allowlist kênh nằm trong `channels.slack.channels` và **phải dùng ID kênh Slack ổn định** (ví dụ `C12345678`) làm khóa cấu hình. + Danh sách cho phép kênh nằm dưới `channels.slack.channels` và **phải dùng ID kênh Slack ổn định** (ví dụ `C12345678`) làm khóa cấu hình. - Ghi chú runtime: nếu `channels.slack` hoàn toàn bị thiếu (thiết lập chỉ dùng env), runtime sẽ dự phòng về `groupPolicy="allowlist"` và ghi cảnh báo (ngay cả khi `channels.defaults.groupPolicy` được đặt). + Ghi chú runtime: nếu `channels.slack` hoàn toàn thiếu (thiết lập chỉ dùng env), runtime quay về `groupPolicy="allowlist"` và ghi cảnh báo (ngay cả khi `channels.defaults.groupPolicy` đã được đặt). Phân giải tên/ID: - - các mục allowlist kênh và mục allowlist DM được phân giải lúc khởi động khi quyền truy cập token cho phép - - các mục tên kênh chưa phân giải được giữ nguyên như đã cấu hình nhưng mặc định bị bỏ qua khi định tuyến - - xác thực đến và định tuyến kênh mặc định ưu tiên ID; khớp trực tiếp theo tên người dùng/slug yêu cầu `channels.slack.dangerouslyAllowNameMatching: true` + - mục danh sách cho phép kênh và mục danh sách cho phép DM được phân giải khi khởi động nếu quyền truy cập token cho phép + - mục tên kênh chưa phân giải được giữ nguyên như đã cấu hình nhưng mặc định bị bỏ qua khi định tuyến + - ủy quyền chiều đến và định tuyến kênh mặc định ưu tiên ID; khớp trực tiếp theo tên người dùng/slug yêu cầu `channels.slack.dangerouslyAllowNameMatching: true` - Các khóa dựa trên tên (`#channel-name` hoặc `channel-name`) **không** khớp trong `groupPolicy: "allowlist"`. Tra cứu kênh mặc định ưu tiên ID, nên một khóa dựa trên tên sẽ không bao giờ định tuyến thành công và mọi tin nhắn trong kênh đó sẽ bị chặn âm thầm. Điều này khác với `groupPolicy: "open"`, nơi khóa kênh không bắt buộc để định tuyến và khóa dựa trên tên có vẻ hoạt động. + Khóa dựa trên tên (`#channel-name` hoặc `channel-name`) **không** khớp trong `groupPolicy: "allowlist"`. Tra cứu kênh mặc định ưu tiên ID, nên khóa dựa trên tên sẽ không bao giờ định tuyến thành công và mọi tin nhắn trong kênh đó sẽ bị chặn âm thầm. Điều này khác với `groupPolicy: "open"`, nơi khóa kênh không bắt buộc để định tuyến và khóa dựa trên tên có vẻ hoạt động. Luôn dùng ID kênh Slack làm khóa. Để tìm ID: nhấp chuột phải vào kênh trong Slack → **Copy link** — ID (`C...`) xuất hiện ở cuối URL. @@ -578,7 +886,7 @@ Các thao tác tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `d } ``` - Incorrect (bị chặn âm thầm dưới `groupPolicy: "allowlist"`): + Không đúng (bị chặn im lặng dưới `groupPolicy: "allowlist"`): ```json5 { @@ -597,16 +905,16 @@ Các thao tác tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `d - Theo mặc định, tin nhắn kênh được kiểm soát bằng lượt nhắc đến. + Tin nhắn trong kênh mặc định được kiểm soát bằng lượt nhắc. - Nguồn nhắc đến: + Nguồn lượt nhắc: - - lượt nhắc đến ứng dụng rõ ràng (`<@botId>`) - - lượt nhắc đến nhóm người dùng Slack (``) khi người dùng bot là thành viên của nhóm người dùng đó; yêu cầu `usergroups:read` - - mẫu regex nhắc đến (`agents.list[].groupChat.mentionPatterns`, dự phòng `messages.groupChat.mentionPatterns`) - - hành vi luồng trả lời ngầm định tới bot (bị tắt khi `thread.requireExplicitMention` là `true`) + - lượt nhắc ứng dụng rõ ràng (`<@botId>`) + - lượt nhắc nhóm người dùng Slack (``) khi người dùng bot là thành viên của nhóm người dùng đó; yêu cầu `usergroups:read` + - mẫu regex lượt nhắc (`agents.list[].groupChat.mentionPatterns`, dự phòng `messages.groupChat.mentionPatterns`) + - hành vi luồng trả lời-ngược-lại-bot ngầm định (bị tắt khi `thread.requireExplicitMention` là `true`) - Điều khiển theo kênh (`channels.slack.channels.`; tên chỉ qua phân giải khi khởi động hoặc `dangerouslyAllowNameMatching`): + Điều khiển theo kênh (`channels.slack.channels.`; tên chỉ thông qua phân giải khi khởi động hoặc `dangerouslyAllowNameMatching`): - `requireMention` - `users` (danh sách cho phép) @@ -614,30 +922,30 @@ Các thao tác tin nhắn Slack hiện tại bao gồm `send`, `upload-file`, `d - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - định dạng khóa `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, hoặc ký tự đại diện `"*"` + - định dạng khóa `toolsBySender`: ký tự đại diện `id:`, `e164:`, `username:`, `name:`, hoặc `"*"` (các khóa cũ không có tiền tố vẫn chỉ ánh xạ tới `id:`) - `allowBots` thận trọng đối với kênh và kênh riêng tư: tin nhắn phòng do bot tạo chỉ được chấp nhận khi bot gửi được liệt kê rõ ràng trong danh sách cho phép `users` của phòng đó, hoặc khi ít nhất một ID chủ sở hữu Slack rõ ràng từ `channels.slack.allowFrom` hiện là thành viên phòng. Ký tự đại diện và mục chủ sở hữu theo tên hiển thị không đáp ứng yêu cầu hiện diện của chủ sở hữu. Sự hiện diện của chủ sở hữu dùng Slack `conversations.members`; hãy bảo đảm ứng dụng có phạm vi đọc phù hợp với loại phòng (`channels:read` cho kênh công khai, `groups:read` cho kênh riêng tư). Nếu tra cứu thành viên thất bại, OpenClaw bỏ tin nhắn phòng do bot tạo. + `allowBots` mang tính thận trọng đối với kênh và kênh riêng tư: tin nhắn phòng do bot tạo chỉ được chấp nhận khi bot gửi được liệt kê rõ ràng trong danh sách cho phép `users` của phòng đó, hoặc khi ít nhất một ID chủ sở hữu Slack rõ ràng từ `channels.slack.allowFrom` hiện là thành viên phòng. Ký tự đại diện và mục chủ sở hữu theo tên hiển thị không đáp ứng điều kiện hiện diện của chủ sở hữu. Sự hiện diện của chủ sở hữu dùng Slack `conversations.members`; hãy bảo đảm ứng dụng có phạm vi đọc tương ứng cho loại phòng (`channels:read` cho kênh công khai, `groups:read` cho kênh riêng tư). Nếu tra cứu thành viên thất bại, OpenClaw bỏ tin nhắn phòng do bot tạo. ## Luồng, phiên và thẻ trả lời -- DM định tuyến là `direct`; kênh là `channel`; MPIM là `group`. -- Liên kết tuyến Slack chấp nhận ID đối tác thô cùng các dạng đích Slack như `channel:C12345678`, `user:U12345678` và `<@U12345678>`. -- Với mặc định `session.dmScope=main`, DM Slack được gộp vào phiên chính của agent. +- DM được định tuyến là `direct`; kênh là `channel`; MPIM là `group`. +- Liên kết định tuyến Slack chấp nhận ID đối tượng ngang hàng thô cùng các dạng đích Slack như `channel:C12345678`, `user:U12345678`, và `<@U12345678>`. +- Với `session.dmScope=main` mặc định, DM Slack được gộp vào phiên chính của agent. - Phiên kênh: `agent::slack:channel:`. -- Trả lời trong luồng có thể tạo hậu tố phiên luồng (`:thread:`) khi áp dụng. -- Mặc định của `channels.slack.thread.historyScope` là `thread`; mặc định của `thread.inheritParent` là `false`. -- `channels.slack.thread.initialHistoryLimit` kiểm soát số tin nhắn luồng hiện có được lấy khi một phiên luồng mới bắt đầu (mặc định `20`; đặt `0` để tắt). -- `channels.slack.thread.requireExplicitMention` (mặc định `false`): khi là `true`, chặn lượt nhắc đến luồng ngầm định để bot chỉ phản hồi các lượt nhắc đến `@bot` rõ ràng bên trong luồng, ngay cả khi bot đã tham gia luồng đó. Nếu không có tùy chọn này, các câu trả lời trong luồng mà bot đã tham gia sẽ bỏ qua cơ chế kiểm soát `requireMention`. +- Trả lời trong luồng có thể tạo hậu tố phiên luồng (`:thread:`) khi phù hợp. +- `channels.slack.thread.historyScope` mặc định là `thread`; `thread.inheritParent` mặc định là `false`. +- `channels.slack.thread.initialHistoryLimit` điều khiển số lượng tin nhắn luồng hiện có được lấy khi phiên luồng mới bắt đầu (mặc định `20`; đặt `0` để tắt). +- `channels.slack.thread.requireExplicitMention` (mặc định `false`): khi là `true`, chặn các lượt nhắc luồng ngầm định để bot chỉ phản hồi các lượt nhắc `@bot` rõ ràng bên trong luồng, ngay cả khi bot đã tham gia luồng. Nếu không có tùy chọn này, các câu trả lời trong một luồng mà bot đã tham gia sẽ bỏ qua cổng `requireMention`. Điều khiển luồng trả lời: - `channels.slack.replyToMode`: `off|first|all|batched` (mặc định `off`) - `channels.slack.replyToModeByChatType`: theo từng `direct|group|channel` -- dự phòng cũ cho cuộc trò chuyện trực tiếp: `channels.slack.dm.replyToMode` +- dự phòng cũ cho trò chuyện trực tiếp: `channels.slack.dm.replyToMode` Hỗ trợ thẻ trả lời thủ công: @@ -645,37 +953,37 @@ Hỗ trợ thẻ trả lời thủ công: - `[[reply_to:]]` -`replyToMode="off"` tắt **toàn bộ** luồng trả lời trong Slack, bao gồm các thẻ `[[reply_to_*]]` rõ ràng. Điều này khác với Telegram, nơi các thẻ rõ ràng vẫn được tôn trọng ở chế độ `"off"`. Luồng Slack ẩn tin nhắn khỏi kênh, trong khi trả lời Telegram vẫn hiển thị trực tiếp trong dòng. +`replyToMode="off"` tắt **tất cả** luồng trả lời trong Slack, bao gồm cả thẻ `[[reply_to_*]]` rõ ràng. Điều này khác với Telegram, nơi các thẻ rõ ràng vẫn được tôn trọng ở chế độ `"off"`. Luồng Slack ẩn tin nhắn khỏi kênh, còn trả lời Telegram vẫn hiển thị nội dòng. ## Phản ứng xác nhận -`ackReaction` gửi emoji xác nhận trong khi OpenClaw đang xử lý một tin nhắn đến. +`ackReaction` gửi một emoji xác nhận trong khi OpenClaw đang xử lý tin nhắn đến. Thứ tự phân giải: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- dự phòng emoji định danh agent (`agents.list[].identity.emoji`, nếu không thì "👀") +- dự phòng emoji nhận diện agent (`agents.list[].identity.emoji`, nếu không thì "👀") Ghi chú: -- Slack yêu cầu shortcode (ví dụ `"eyes"`). +- Slack mong đợi shortcode (ví dụ `"eyes"`). - Dùng `""` để tắt phản ứng cho tài khoản Slack hoặc toàn cục. -## Truyền trực tuyến văn bản +## Truyền trực tiếp văn bản -`channels.slack.streaming` kiểm soát hành vi xem trước trực tiếp: +`channels.slack.streaming` điều khiển hành vi xem trước trực tiếp: -- `off`: tắt truyền trực tuyến bản xem trước trực tiếp. +- `off`: tắt truyền trực tiếp bản xem trước. - `partial` (mặc định): thay thế văn bản xem trước bằng đầu ra từng phần mới nhất. -- `block`: nối thêm các cập nhật xem trước theo từng đoạn. -- `progress`: hiển thị văn bản trạng thái tiến độ trong khi tạo, rồi gửi văn bản cuối cùng. -- `streaming.preview.toolProgress`: khi bản nháp xem trước đang hoạt động, định tuyến cập nhật công cụ/tiến độ vào cùng tin nhắn xem trước đã chỉnh sửa (mặc định: `true`). Đặt `false` để giữ các tin nhắn công cụ/tiến độ riêng. -- `streaming.preview.commandText` / `streaming.progress.commandText`: đặt thành `status` để giữ các dòng tiến độ công cụ ngắn gọn trong khi ẩn văn bản lệnh/thực thi thô (mặc định: `raw`). +- `block`: nối thêm các bản cập nhật xem trước theo từng đoạn. +- `progress`: hiển thị văn bản trạng thái tiến độ trong khi tạo, sau đó gửi văn bản cuối cùng. +- `streaming.preview.toolProgress`: khi bản xem trước nháp đang hoạt động, định tuyến các bản cập nhật công cụ/tiến độ vào cùng tin nhắn xem trước đã chỉnh sửa (mặc định: `true`). Đặt `false` để giữ các tin nhắn công cụ/tiến độ riêng. +- `streaming.preview.commandText` / `streaming.progress.commandText`: đặt thành `status` để giữ các dòng tiến độ công cụ gọn nhẹ trong khi ẩn văn bản lệnh/thực thi thô (mặc định: `raw`). -Ẩn văn bản lệnh/thực thi thô trong khi giữ các dòng tiến độ ngắn gọn: +Ẩn văn bản lệnh/thực thi thô trong khi giữ các dòng tiến độ gọn nhẹ: ```json { @@ -693,16 +1001,16 @@ Ghi chú: } ``` -`channels.slack.streaming.nativeTransport` kiểm soát truyền trực tuyến văn bản gốc của Slack khi `channels.slack.streaming.mode` là `partial` (mặc định: `true`). +`channels.slack.streaming.nativeTransport` điều khiển truyền trực tiếp văn bản gốc của Slack khi `channels.slack.streaming.mode` là `partial` (mặc định: `true`). -- Phải có luồng trả lời để truyền trực tuyến văn bản gốc và trạng thái luồng trợ lý Slack xuất hiện. Việc chọn luồng vẫn tuân theo `replyToMode`. -- Gốc kênh, trò chuyện nhóm và DM cấp cao nhất vẫn có thể dùng bản nháp xem trước thông thường khi truyền trực tuyến gốc không khả dụng hoặc không có luồng trả lời. -- Theo mặc định, DM Slack cấp cao nhất vẫn ở ngoài luồng, nên chúng không hiển thị bản xem trước luồng/trạng thái gốc kiểu luồng của Slack; thay vào đó OpenClaw đăng và chỉnh sửa bản nháp xem trước trong DM. +- Phải có sẵn luồng trả lời để truyền trực tiếp văn bản gốc và để trạng thái luồng trợ lý Slack xuất hiện. Việc chọn luồng vẫn tuân theo `replyToMode`. +- Kênh, trò chuyện nhóm và gốc DM cấp cao nhất vẫn có thể dùng bản xem trước nháp thông thường khi không có truyền trực tiếp gốc hoặc không tồn tại luồng trả lời. +- DM Slack cấp cao nhất mặc định ở ngoài luồng, vì vậy chúng không hiển thị bản xem trước luồng/trạng thái gốc kiểu luồng của Slack; thay vào đó OpenClaw đăng và chỉnh sửa một bản xem trước nháp trong DM. - Phương tiện và payload không phải văn bản quay về cơ chế gửi thông thường. -- Kết quả cuối cùng dạng phương tiện/lỗi hủy các chỉnh sửa xem trước đang chờ; kết quả cuối cùng dạng văn bản/block đủ điều kiện chỉ được xả khi có thể chỉnh sửa trực tiếp bản xem trước. -- Nếu truyền trực tuyến thất bại giữa chừng khi trả lời, OpenClaw quay về cơ chế gửi thông thường cho các payload còn lại. +- Kết quả cuối phương tiện/lỗi hủy các chỉnh sửa xem trước đang chờ; kết quả cuối văn bản/khối đủ điều kiện chỉ được xả khi có thể chỉnh sửa trực tiếp bản xem trước tại chỗ. +- Nếu truyền trực tiếp thất bại giữa chừng trong một câu trả lời, OpenClaw quay về cơ chế gửi thông thường cho các payload còn lại. -Dùng bản nháp xem trước thay vì truyền trực tuyến văn bản gốc của Slack: +Dùng bản xem trước nháp thay vì truyền trực tiếp văn bản gốc của Slack: ```json5 { @@ -725,7 +1033,7 @@ Khóa cũ: ## Dự phòng phản ứng đang nhập -`typingReaction` thêm một reaction tạm thời vào tin nhắn Slack gửi đến trong khi OpenClaw đang xử lý phản hồi, rồi gỡ nó khi lượt chạy kết thúc. Điều này hữu ích nhất bên ngoài các phản hồi trong thread, vốn dùng chỉ báo trạng thái "is typing..." mặc định. +`typingReaction` thêm một reaction tạm thời vào tin nhắn Slack gửi đến trong khi OpenClaw đang xử lý phản hồi, rồi xóa reaction đó khi lượt chạy kết thúc. Tính năng này hữu ích nhất bên ngoài phản hồi theo thread, vốn dùng chỉ báo trạng thái mặc định "đang nhập...". Thứ tự phân giải: @@ -735,25 +1043,25 @@ Thứ tự phân giải: Ghi chú: - Slack yêu cầu shortcode (ví dụ `"hourglass_flowing_sand"`). -- Reaction là nỗ lực tối đa và việc dọn dẹp được thử tự động sau khi phản hồi hoặc đường dẫn lỗi hoàn tất. +- Reaction được thực hiện theo best-effort và quá trình dọn dẹp được tự động thử sau khi phản hồi hoặc đường dẫn lỗi hoàn tất. -## Phương tiện, chia đoạn và phân phối +## Phương tiện, chia nhỏ và phân phối - Tệp đính kèm Slack được tải xuống từ URL riêng do Slack lưu trữ (luồng yêu cầu xác thực bằng token) và được ghi vào kho phương tiện khi việc fetch thành công và giới hạn kích thước cho phép. Placeholder của tệp bao gồm `fileId` của Slack để agent có thể fetch tệp gốc bằng `download-file`. + Tệp đính kèm Slack được tải xuống từ URL riêng tư do Slack lưu trữ (luồng yêu cầu xác thực bằng token) và được ghi vào kho phương tiện khi tải thành công và giới hạn kích thước cho phép. Placeholder tệp bao gồm `fileId` của Slack để agent có thể tải tệp gốc bằng `download-file`. - Các lượt tải xuống dùng thời gian chờ nhàn rỗi và tổng thời gian chờ có giới hạn. Nếu việc truy xuất tệp Slack bị treo hoặc thất bại, OpenClaw vẫn tiếp tục xử lý tin nhắn và quay về dùng placeholder của tệp. + Tải xuống dùng thời gian chờ idle và tổng thời gian có giới hạn. Nếu việc truy xuất tệp Slack bị treo hoặc thất bại, OpenClaw tiếp tục xử lý tin nhắn và fallback về placeholder tệp. - Giới hạn kích thước gửi đến lúc runtime mặc định là `20MB` trừ khi được ghi đè bằng `channels.slack.mediaMaxMb`. + Giới hạn kích thước inbound trong runtime mặc định là `20MB` trừ khi được ghi đè bằng `channels.slack.mediaMaxMb`. - các đoạn văn bản dùng `channels.slack.textChunkLimit` (mặc định 4000) - - `channels.slack.chunkMode="newline"` bật chia theo đoạn văn trước - - việc gửi tệp dùng API tải lên của Slack và có thể bao gồm phản hồi trong thread (`thread_ts`) - - giới hạn phương tiện gửi đi tuân theo `channels.slack.mediaMaxMb` khi được cấu hình; nếu không, lượt gửi qua kênh dùng mặc định theo loại MIME từ pipeline phương tiện + - `channels.slack.chunkMode="newline"` bật tách ưu tiên đoạn văn + - gửi tệp dùng API tải lên của Slack và có thể bao gồm phản hồi theo thread (`thread_ts`) + - giới hạn phương tiện outbound theo `channels.slack.mediaMaxMb` khi được cấu hình; nếu không, lượt gửi qua kênh dùng mặc định theo loại MIME từ pipeline phương tiện @@ -763,14 +1071,14 @@ Ghi chú: - `user:` cho DM - `channel:` cho kênh - DM Slack chỉ có văn bản/block có thể đăng trực tiếp tới ID người dùng; tải tệp lên và gửi trong thread trước tiên mở DM thông qua API cuộc trò chuyện của Slack vì các đường dẫn đó yêu cầu ID cuộc trò chuyện cụ thể. + DM Slack chỉ có văn bản/block có thể đăng trực tiếp tới ID người dùng; tải tệp lên và gửi theo thread sẽ mở DM qua API hội thoại Slack trước vì các đường dẫn đó yêu cầu ID hội thoại cụ thể. ## Lệnh và hành vi slash -Lệnh slash xuất hiện trong Slack dưới dạng một lệnh đã cấu hình duy nhất hoặc nhiều lệnh gốc. Cấu hình `channels.slack.slashCommand` để thay đổi mặc định của lệnh: +Lệnh slash xuất hiện trong Slack dưới dạng một lệnh đã cấu hình duy nhất hoặc nhiều lệnh native. Cấu hình `channels.slack.slashCommand` để thay đổi mặc định lệnh: - `enabled: false` - `name: "openclaw"` @@ -781,32 +1089,32 @@ Lệnh slash xuất hiện trong Slack dưới dạng một lệnh đã cấu h /openclaw /help ``` -Thay vào đó, lệnh gốc yêu cầu [cài đặt manifest bổ sung](#additional-manifest-settings) trong ứng dụng Slack của bạn và được bật bằng `channels.slack.commands.native: true` hoặc `commands.native: true` trong cấu hình toàn cục. +Lệnh native yêu cầu [cài đặt manifest bổ sung](#additional-manifest-settings) trong ứng dụng Slack của bạn và được bật bằng `channels.slack.commands.native: true` hoặc `commands.native: true` trong cấu hình toàn cục. -- Chế độ tự động cho lệnh gốc là **tắt** đối với Slack, nên `commands.native: "auto"` không bật lệnh gốc Slack. +- Chế độ tự động của lệnh native được **tắt** cho Slack, nên `commands.native: "auto"` không bật lệnh native của Slack. ```txt /help ``` -Menu đối số gốc dùng chiến lược render thích ứng, hiển thị một modal xác nhận trước khi dispatch giá trị tùy chọn đã chọn: +Menu đối số native dùng chiến lược hiển thị thích ứng, hiển thị modal xác nhận trước khi gửi giá trị tùy chọn đã chọn: - tối đa 5 tùy chọn: block nút - 6-100 tùy chọn: menu chọn tĩnh -- hơn 100 tùy chọn: chọn bên ngoài với lọc tùy chọn bất đồng bộ khi có handler tùy chọn tương tác -- vượt giới hạn Slack: giá trị tùy chọn đã mã hóa quay về dùng nút +- hơn 100 tùy chọn: chọn bên ngoài với lọc tùy chọn bất đồng bộ khi có trình xử lý tùy chọn interactivity +- vượt quá giới hạn Slack: giá trị tùy chọn được mã hóa fallback về nút ```txt /think ``` -Phiên slash dùng khóa tách biệt như `agent::slack:slash:` và vẫn định tuyến việc thực thi lệnh tới phiên cuộc trò chuyện đích bằng `CommandTargetSessionKey`. +Phiên slash dùng khóa cô lập như `agent::slack:slash:` và vẫn định tuyến lượt thực thi lệnh tới phiên hội thoại đích bằng `CommandTargetSessionKey`. ## Phản hồi tương tác -Slack có thể render các điều khiển phản hồi tương tác do agent tạo, nhưng tính năng này bị tắt theo mặc định. +Slack có thể hiển thị điều khiển phản hồi tương tác do agent tạo, nhưng tính năng này bị tắt theo mặc định. -Bật toàn cục: +Bật tính năng này toàn cục: ```json5 { @@ -838,42 +1146,42 @@ Hoặc chỉ bật cho một tài khoản Slack: } ``` -Khi được bật, agent có thể phát ra chỉ thị phản hồi chỉ dành cho Slack: +Khi được bật, agent có thể phát directive phản hồi chỉ dành cho Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Các chỉ thị này được biên dịch thành Slack Block Kit và định tuyến lượt nhấp hoặc lựa chọn trở lại qua đường dẫn sự kiện tương tác Slack hiện có. +Các directive này được biên dịch thành Slack Block Kit và định tuyến lượt nhấp hoặc lựa chọn trở lại qua đường dẫn sự kiện tương tác Slack hiện có. Ghi chú: -- Đây là UI riêng của Slack. Các kênh khác không dịch chỉ thị Slack Block Kit thành hệ thống nút riêng của chúng. -- Giá trị callback tương tác là token mờ do OpenClaw tạo, không phải giá trị thô do agent tạo. -- Nếu các block tương tác được tạo sẽ vượt giới hạn Slack Block Kit, OpenClaw quay về dùng phản hồi văn bản gốc thay vì gửi payload block không hợp lệ. +- Đây là UI riêng cho Slack. Các kênh khác không chuyển directive Slack Block Kit thành hệ thống nút riêng của chúng. +- Giá trị callback tương tác là token opaque do OpenClaw tạo, không phải giá trị thô do agent tạo. +- Nếu các block tương tác được tạo vượt quá giới hạn Slack Block Kit, OpenClaw fallback về phản hồi văn bản gốc thay vì gửi payload block không hợp lệ. ## Phê duyệt exec trong Slack -Slack có thể hoạt động như một client phê duyệt gốc với nút và tương tác, thay vì quay về Web UI hoặc terminal. +Slack có thể hoạt động như một client phê duyệt native với nút và tương tác, thay vì fallback về Web UI hoặc terminal. -- Phê duyệt exec dùng `channels.slack.execApprovals.*` cho định tuyến DM/kênh gốc. -- Phê duyệt Plugin vẫn có thể phân giải qua cùng bề mặt nút gốc của Slack khi yêu cầu đã đến Slack và loại approval id là `plugin:`. -- Ủy quyền người phê duyệt vẫn được thực thi: chỉ người dùng được nhận diện là người phê duyệt mới có thể phê duyệt hoặc từ chối yêu cầu qua Slack. +- Phê duyệt exec dùng `channels.slack.execApprovals.*` để định tuyến DM/kênh native. +- Phê duyệt Plugin vẫn có thể được phân giải qua cùng bề mặt nút native của Slack khi yêu cầu đã đến Slack và loại approval id là `plugin:`. +- Việc ủy quyền người phê duyệt vẫn được thực thi: chỉ người dùng được xác định là người phê duyệt mới có thể phê duyệt hoặc từ chối yêu cầu qua Slack. -Tính năng này dùng cùng bề mặt nút phê duyệt dùng chung như các kênh khác. Khi `interactivity` được bật trong cài đặt ứng dụng Slack của bạn, lời nhắc phê duyệt render dưới dạng nút Block Kit trực tiếp trong cuộc trò chuyện. -Khi các nút đó có mặt, chúng là UX phê duyệt chính; OpenClaw -chỉ nên bao gồm lệnh `/approve` thủ công khi kết quả công cụ cho biết phê duyệt qua chat -không khả dụng hoặc phê duyệt thủ công là đường dẫn duy nhất. +Tính năng này dùng cùng bề mặt nút phê duyệt dùng chung như các kênh khác. Khi `interactivity` được bật trong cài đặt ứng dụng Slack của bạn, lời nhắc phê duyệt hiển thị trực tiếp trong hội thoại dưới dạng nút Block Kit. +Khi có các nút đó, chúng là UX phê duyệt chính; OpenClaw +chỉ nên bao gồm lệnh `/approve` thủ công khi kết quả công cụ cho biết phê duyệt +qua chat không khả dụng hoặc phê duyệt thủ công là đường dẫn duy nhất. Đường dẫn cấu hình: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (tùy chọn; quay về `commands.ownerAllowFrom` khi có thể) +- `channels.slack.execApprovals.approvers` (tùy chọn; fallback về `commands.ownerAllowFrom` khi có thể) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, mặc định: `dm`) - `agentFilter`, `sessionFilter` -Slack tự động bật phê duyệt exec gốc khi `enabled` chưa đặt hoặc là `"auto"` và phân giải được ít nhất một -người phê duyệt. Đặt `enabled: false` để tắt Slack một cách rõ ràng với vai trò client phê duyệt gốc. -Đặt `enabled: true` để buộc bật phê duyệt gốc khi phân giải được người phê duyệt. +Slack tự động bật phê duyệt exec native khi `enabled` chưa được đặt hoặc là `"auto"` và phân giải được ít nhất một +người phê duyệt. Đặt `enabled: false` để tắt Slack một cách rõ ràng với vai trò client phê duyệt native. +Đặt `enabled: true` để buộc bật phê duyệt native khi phân giải được người phê duyệt. Hành vi mặc định khi không có cấu hình phê duyệt exec Slack rõ ràng: @@ -885,7 +1193,7 @@ Hành vi mặc định khi không có cấu hình phê duyệt exec Slack rõ r } ``` -Cấu hình gốc Slack rõ ràng chỉ cần thiết khi bạn muốn ghi đè người phê duyệt, thêm bộ lọc, hoặc +Cấu hình native cho Slack chỉ cần thiết khi bạn muốn ghi đè người phê duyệt, thêm bộ lọc, hoặc chọn phân phối tới chat gốc: ```json5 @@ -903,24 +1211,24 @@ chọn phân phối tới chat gốc: ``` Chuyển tiếp `approvals.exec` dùng chung là riêng biệt. Chỉ dùng nó khi lời nhắc phê duyệt exec cũng phải -định tuyến tới các chat khác hoặc đích ngoài băng rõ ràng. Chuyển tiếp `approvals.plugin` dùng chung cũng -riêng biệt; nút gốc Slack vẫn có thể phân giải phê duyệt Plugin khi các yêu cầu đó đã đến +định tuyến tới các chat khác hoặc các đích ngoài băng tần rõ ràng. Chuyển tiếp `approvals.plugin` dùng chung cũng +riêng biệt; nút native của Slack vẫn có thể phân giải phê duyệt Plugin khi các yêu cầu đó đã đến Slack. -`/approve` cùng chat cũng hoạt động trong kênh Slack và DM đã hỗ trợ lệnh. Xem [Phê duyệt exec](/vi/tools/exec-approvals) để biết đầy đủ mô hình chuyển tiếp phê duyệt. +`/approve` trong cùng chat cũng hoạt động trong kênh Slack và DM đã hỗ trợ lệnh. Xem [Phê duyệt exec](/vi/tools/exec-approvals) để biết đầy đủ mô hình chuyển tiếp phê duyệt. ## Sự kiện và hành vi vận hành - Chỉnh sửa/xóa tin nhắn được ánh xạ thành sự kiện hệ thống. -- Broadcast thread (phản hồi thread "Also send to channel") được xử lý như tin nhắn người dùng bình thường. -- Sự kiện thêm/gỡ reaction được ánh xạ thành sự kiện hệ thống. -- Sự kiện thành viên tham gia/rời, kênh được tạo/đổi tên, và thêm/gỡ ghim được ánh xạ thành sự kiện hệ thống. +- Thread broadcast ("Cũng gửi tới kênh" trong phản hồi thread) được xử lý như tin nhắn người dùng bình thường. +- Sự kiện thêm/xóa reaction được ánh xạ thành sự kiện hệ thống. +- Sự kiện thành viên tham gia/rời, kênh được tạo/đổi tên, và thêm/xóa ghim được ánh xạ thành sự kiện hệ thống. - `channel_id_changed` có thể di chuyển khóa cấu hình kênh khi `configWrites` được bật. -- Metadata chủ đề/mục đích của kênh được coi là ngữ cảnh không đáng tin cậy và có thể được chèn vào ngữ cảnh định tuyến. -- Việc gieo ngữ cảnh người bắt đầu thread và lịch sử thread ban đầu được lọc theo allowlist người gửi đã cấu hình khi áp dụng. -- Hành động block và tương tác modal phát ra sự kiện hệ thống `Slack interaction: ...` có cấu trúc với các trường payload phong phú: - - hành động block: giá trị đã chọn, nhãn, giá trị bộ chọn, và metadata `workflow_*` - - sự kiện modal `view_submission` và `view_closed` với metadata kênh đã định tuyến và đầu vào biểu mẫu +- Metadata chủ đề/mục đích của kênh được coi là ngữ cảnh không đáng tin cậy và có thể được đưa vào ngữ cảnh định tuyến. +- Ngữ cảnh seed từ thread starter và lịch sử thread ban đầu được lọc theo allowlist người gửi đã cấu hình khi áp dụng. +- Block action và tương tác modal phát sự kiện hệ thống `Slack interaction: ...` có cấu trúc với các trường payload phong phú: + - block action: giá trị đã chọn, nhãn, giá trị picker, và metadata `workflow_*` + - sự kiện modal `view_submission` và `view_closed` với metadata kênh đã định tuyến và input biểu mẫu ## Tham chiếu cấu hình @@ -928,11 +1236,11 @@ Tham chiếu chính: [Tham chiếu cấu hình - Slack](/vi/gateway/config-chann -- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` +- chế độ/xác thực: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - quyền truy cập DM: `dm.enabled`, `dmPolicy`, `allowFrom` (cũ: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` -- nút bật/tắt tương thích: `dangerouslyAllowNameMatching` (break-glass; giữ tắt trừ khi cần) +- công tắc tương thích: `dangerouslyAllowNameMatching` (break-glass; giữ tắt trừ khi cần) - quyền truy cập kênh: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- threading/lịch sử: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- thread/lịch sử: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - phân phối: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - vận hành/tính năng: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -963,9 +1271,9 @@ openclaw doctor Kiểm tra: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (hoặc cấu hình cũ `channels.slack.dm.policy`) - - phê duyệt ghép nối / mục allowlist - - Sự kiện DM Slack Assistant: log chi tiết nhắc đến `drop message_changed` + - `channels.slack.dmPolicy` (hoặc bản cũ `channels.slack.dm.policy`) + - phê duyệt ghép cặp / mục allowlist + - Sự kiện DM của Slack Assistant: log chi tiết nhắc đến `drop message_changed` thường có nghĩa là Slack đã gửi một sự kiện Assistant-thread đã chỉnh sửa mà không có người gửi là con người có thể khôi phục trong metadata tin nhắn @@ -976,11 +1284,11 @@ openclaw pairing list slack - Xác thực token bot + app và việc bật Socket Mode trong cài đặt ứng dụng Slack. + Xác thực bot + app token và việc bật Socket Mode trong cài đặt ứng dụng Slack. Nếu `openclaw channels status --probe --json` hiển thị `botTokenStatus` hoặc `appTokenStatus: "configured_unavailable"`, tài khoản Slack đã được - cấu hình nhưng runtime hiện tại không thể phân giải giá trị dựa trên SecretRef. + cấu hình nhưng runtime hiện tại không phân giải được giá trị được hỗ trợ bởi SecretRef. @@ -989,19 +1297,19 @@ openclaw pairing list slack - signing secret - đường dẫn Webhook - - URL yêu cầu Slack (Events + Interactivity + Slash Commands) + - Slack Request URLs (Events + Interactivity + Slash Commands) - `webhookPath` duy nhất cho mỗi tài khoản HTTP Nếu `signingSecretStatus: "configured_unavailable"` xuất hiện trong snapshot - tài khoản, tài khoản HTTP đã được cấu hình nhưng runtime hiện tại không thể - phân giải signing secret dựa trên SecretRef. + tài khoản, tài khoản HTTP đã được cấu hình nhưng runtime hiện tại không + phân giải được signing secret được hỗ trợ bởi SecretRef. Xác minh bạn đã định dùng: - - chế độ lệnh gốc (`channels.slack.commands.native: true`) với các lệnh slash tương ứng đã đăng ký trong Slack + - chế độ lệnh native (`channels.slack.commands.native: true`) với các lệnh slash tương ứng đã đăng ký trong Slack - hoặc chế độ một lệnh slash (`channels.slack.slashCommand.enabled: true`) Đồng thời kiểm tra `commands.useAccessGroups` và allowlist kênh/người dùng. @@ -1011,88 +1319,88 @@ openclaw pairing list slack ## Tham chiếu vision cho tệp đính kèm -Slack có thể đính kèm phương tiện đã tải xuống vào lượt agent khi tải tệp Slack xuống thành công và giới hạn kích thước cho phép. Tệp hình ảnh có thể được truyền qua đường dẫn hiểu phương tiện hoặc trực tiếp tới mô hình phản hồi có khả năng vision; các tệp khác được giữ lại dưới dạng ngữ cảnh tệp có thể tải xuống thay vì được coi là đầu vào hình ảnh. +Slack có thể đính kèm phương tiện đã tải xuống vào lượt agent khi tải tệp Slack thành công và giới hạn kích thước cho phép. Tệp hình ảnh có thể được truyền qua đường dẫn hiểu phương tiện hoặc trực tiếp tới mô hình phản hồi hỗ trợ vision; các tệp khác được giữ lại làm ngữ cảnh tệp có thể tải xuống thay vì được xem là input hình ảnh. ### Loại phương tiện được hỗ trợ -| Loại phương tiện | Nguồn | Hành vi hiện tại | Ghi chú | -| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| Hình ảnh JPEG / PNG / GIF / WebP | URL tệp Slack | Được tải xuống và đính kèm vào lượt để xử lý bằng khả năng thị giác | Giới hạn mỗi tệp: `channels.slack.mediaMaxMb` (mặc định 20 MB) | -| Tệp PDF | URL tệp Slack | Được tải xuống và hiển thị dưới dạng ngữ cảnh tệp cho các công cụ như `download-file` hoặc `pdf` | Slack inbound không tự động chuyển đổi PDF thành đầu vào thị giác hình ảnh | -| Tệp khác | URL tệp Slack | Được tải xuống khi có thể và hiển thị dưới dạng ngữ cảnh tệp | Tệp nhị phân không được xem là đầu vào hình ảnh | -| Phản hồi trong luồng | Tệp của tin nhắn bắt đầu luồng | Tệp của tin nhắn gốc có thể được nạp làm ngữ cảnh khi phản hồi không có phương tiện trực tiếp | Tin nhắn bắt đầu chỉ có tệp dùng một placeholder tệp đính kèm | -| Tin nhắn nhiều hình ảnh | Nhiều tệp Slack | Mỗi tệp được đánh giá độc lập | Quá trình xử lý Slack bị giới hạn ở tám tệp mỗi tin nhắn | +| Loại phương tiện | Nguồn | Hành vi hiện tại | Ghi chú | +| --------------------------- | ----------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| Ảnh JPEG / PNG / GIF / WebP | URL tệp Slack | Được tải xuống và đính kèm vào lượt xử lý để các khả năng hỗ trợ thị giác xử lý | Giới hạn mỗi tệp: `channels.slack.mediaMaxMb` (mặc định 20 MB) | +| Tệp PDF | URL tệp Slack | Được tải xuống và hiển thị dưới dạng ngữ cảnh tệp cho các công cụ như `download-file` hoặc `pdf` | Luồng vào Slack không tự động chuyển đổi PDF thành đầu vào thị giác ảnh | +| Tệp khác | URL tệp Slack | Được tải xuống khi có thể và hiển thị dưới dạng ngữ cảnh tệp | Tệp nhị phân không được xử lý như đầu vào hình ảnh | +| Trả lời trong luồng | Tệp của tin nhắn mở luồng | Tệp của tin nhắn gốc có thể được nạp làm ngữ cảnh khi phản hồi không có phương tiện trực tiếp | Tin nhắn mở luồng chỉ có tệp sử dụng một phần giữ chỗ cho tệp đính kèm | +| Tin nhắn nhiều ảnh | Nhiều tệp Slack | Mỗi tệp được đánh giá độc lập | Quá trình xử lý Slack bị giới hạn ở tám tệp mỗi tin nhắn | -### Quy trình inbound +### Luồng xử lý vào Khi một tin nhắn Slack có tệp đính kèm đến: -1. OpenClaw tải tệp xuống từ URL riêng tư của Slack bằng token bot (`xoxb-...`). -2. Tệp được ghi vào kho phương tiện khi thành công. -3. Đường dẫn phương tiện đã tải xuống và kiểu nội dung được thêm vào ngữ cảnh inbound. -4. Các đường dẫn model/công cụ hỗ trợ hình ảnh có thể dùng tệp đính kèm hình ảnh từ ngữ cảnh đó. -5. Các tệp không phải hình ảnh vẫn khả dụng dưới dạng siêu dữ liệu tệp hoặc tham chiếu phương tiện cho các công cụ có thể xử lý chúng. +1. OpenClaw tải tệp xuống từ URL riêng tư của Slack bằng mã thông báo bot (`xoxb-...`). +2. Tệp được ghi vào kho lưu trữ phương tiện khi thành công. +3. Đường dẫn phương tiện đã tải xuống và loại nội dung được thêm vào ngữ cảnh đầu vào. +4. Các đường dẫn mô hình/công cụ có khả năng xử lý ảnh có thể dùng tệp đính kèm ảnh từ ngữ cảnh đó. +5. Các tệp không phải ảnh vẫn có sẵn dưới dạng siêu dữ liệu tệp hoặc tham chiếu phương tiện cho các công cụ có thể xử lý chúng. ### Kế thừa tệp đính kèm từ gốc luồng Khi một tin nhắn đến trong một luồng (có cha `thread_ts`): -- Nếu chính phản hồi không có phương tiện trực tiếp và tin nhắn gốc được bao gồm có tệp, Slack có thể nạp các tệp gốc làm ngữ cảnh bắt đầu luồng. +- Nếu chính phản hồi không có phương tiện trực tiếp và tin nhắn gốc được đưa vào có tệp, Slack có thể nạp các tệp gốc làm ngữ cảnh mở luồng. - Tệp đính kèm trực tiếp của phản hồi được ưu tiên hơn tệp đính kèm của tin nhắn gốc. -- Tin nhắn gốc chỉ có tệp và không có văn bản được biểu diễn bằng một placeholder tệp đính kèm để phương án dự phòng vẫn có thể bao gồm các tệp của nó. +- Một tin nhắn gốc chỉ có tệp và không có văn bản được biểu diễn bằng một phần giữ chỗ cho tệp đính kèm để cơ chế dự phòng vẫn có thể bao gồm các tệp của nó. ### Xử lý nhiều tệp đính kèm Khi một tin nhắn Slack duy nhất chứa nhiều tệp đính kèm: -- Mỗi tệp đính kèm được xử lý độc lập qua quy trình phương tiện. +- Mỗi tệp đính kèm được xử lý độc lập qua luồng phương tiện. - Các tham chiếu phương tiện đã tải xuống được tổng hợp vào ngữ cảnh tin nhắn. -- Thứ tự xử lý theo thứ tự tệp của Slack trong payload sự kiện. -- Lỗi khi tải xuống một tệp đính kèm không chặn các tệp khác. +- Thứ tự xử lý theo thứ tự tệp của Slack trong tải trọng sự kiện. +- Lỗi tải xuống của một tệp đính kèm không chặn các tệp khác. -### Giới hạn kích thước, tải xuống và model +### Giới hạn kích thước, tải xuống và mô hình - **Giới hạn kích thước**: Mặc định 20 MB mỗi tệp. Có thể cấu hình qua `channels.slack.mediaMaxMb`. -- **Lỗi tải xuống**: Các tệp mà Slack không thể phục vụ, URL đã hết hạn, tệp không truy cập được, tệp quá lớn và phản hồi HTML xác thực/đăng nhập Slack sẽ bị bỏ qua thay vì được báo là định dạng không được hỗ trợ. -- **Model thị giác**: Phân tích hình ảnh dùng model phản hồi đang hoạt động khi model đó hỗ trợ thị giác, hoặc model hình ảnh được cấu hình tại `agents.defaults.imageModel`. +- **Lỗi tải xuống**: Các tệp mà Slack không thể phục vụ, URL hết hạn, tệp không truy cập được, tệp quá kích thước và phản hồi HTML xác thực/đăng nhập Slack sẽ bị bỏ qua thay vì được báo là định dạng không được hỗ trợ. +- **Mô hình thị giác**: Phân tích ảnh dùng mô hình phản hồi đang hoạt động khi mô hình đó hỗ trợ thị giác, hoặc mô hình ảnh được cấu hình tại `agents.defaults.imageModel`. ### Giới hạn đã biết -| Tình huống | Hành vi hiện tại | Cách xử lý | -| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| URL tệp Slack đã hết hạn | Tệp bị bỏ qua; không hiển thị lỗi | Tải lại tệp lên Slack | -| Chưa cấu hình model thị giác | Tệp đính kèm hình ảnh được lưu dưới dạng tham chiếu phương tiện, nhưng không được phân tích như hình ảnh | Cấu hình `agents.defaults.imageModel` hoặc dùng model phản hồi hỗ trợ thị giác | -| Hình ảnh rất lớn (> 20 MB theo mặc định) | Bị bỏ qua theo giới hạn kích thước | Tăng `channels.slack.mediaMaxMb` nếu Slack cho phép | -| Tệp đính kèm được chuyển tiếp/chia sẻ | Văn bản và phương tiện hình ảnh/tệp do Slack lưu trữ được xử lý theo nỗ lực tốt nhất | Chia sẻ lại trực tiếp trong luồng OpenClaw | -| Tệp đính kèm PDF | Được lưu dưới dạng ngữ cảnh tệp/phương tiện, không tự động được định tuyến qua thị giác hình ảnh | Dùng `download-file` cho siêu dữ liệu tệp hoặc công cụ `pdf` để phân tích PDF | +| Kịch bản | Hành vi hiện tại | Cách khắc phục | +| ------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| URL tệp Slack hết hạn | Tệp bị bỏ qua; không hiển thị lỗi | Tải lại tệp lên Slack | +| Chưa cấu hình mô hình thị giác | Tệp đính kèm ảnh được lưu dưới dạng tham chiếu phương tiện, nhưng không được phân tích như ảnh | Cấu hình `agents.defaults.imageModel` hoặc dùng mô hình phản hồi có khả năng thị giác | +| Ảnh rất lớn (> 20 MB theo mặc định) | Bị bỏ qua theo giới hạn kích thước | Tăng `channels.slack.mediaMaxMb` nếu Slack cho phép | +| Tệp đính kèm được chuyển tiếp/chia sẻ | Văn bản và phương tiện ảnh/tệp do Slack lưu trữ được xử lý theo khả năng tốt nhất | Chia sẻ lại trực tiếp trong luồng OpenClaw | +| Tệp đính kèm PDF | Được lưu dưới dạng ngữ cảnh tệp/phương tiện, không tự động định tuyến qua thị giác ảnh | Dùng `download-file` cho siêu dữ liệu tệp hoặc công cụ `pdf` để phân tích PDF | ### Tài liệu liên quan -- [Quy trình hiểu phương tiện](/vi/nodes/media-understanding) +- [Luồng hiểu phương tiện](/vi/nodes/media-understanding) - [Công cụ PDF](/vi/tools/pdf) -- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — bật thị giác cho tệp đính kèm Slack +- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Bật khả năng thị giác cho tệp đính kèm Slack - Kiểm thử hồi quy: [#51353](https://github.com/openclaw/openclaw/issues/51353) - Xác minh trực tiếp: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## Liên quan - + Ghép nối người dùng Slack với Gateway. - - Hành vi của kênh và DM nhóm. + + Hành vi kênh và DM nhóm. - - Định tuyến tin nhắn inbound đến agent. + + Định tuyến tin nhắn đầu vào đến các tác tử. - + Mô hình mối đe dọa và gia cố bảo mật. - + Bố cục cấu hình và thứ tự ưu tiên. - + Danh mục lệnh và hành vi. diff --git a/docs/vi/channels/zalouser.md b/docs/vi/channels/zalouser.md index 8fd0bb0a5..e3eca39e4 100644 --- a/docs/vi/channels/zalouser.md +++ b/docs/vi/channels/zalouser.md @@ -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. -Đâ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. ## 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..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..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ố diff --git a/docs/vi/ci.md b/docs/vi/ci.md index f5e23f1b4..ea6a5bdd4 100644 --- a/docs/vi/ci.md +++ b/docs/vi/ci.md @@ -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= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## 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 # 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 # 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//-//`. Con trỏ ref được kiểm thử hiện tại được ghi là `openclaw-performance//latest-.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//-//`. Con trỏ tested-ref hiện tại được ghi dưới dạng `openclaw-performance//latest-.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=`: ```bash pnpm ci:full-release --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/-...` 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/-...` 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:` 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:` 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 # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # 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 " ``` -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 ``` -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 --no-sync --timing-json --shell -- "pnpm test " @@ -575,7 +575,7 @@ blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size blacksmith testbox stop --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 --timing-json --shell -- "env NODE_OPT pnpm crabbox:stop -- ``` -`.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 `. +`.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 `. ## Liên quan diff --git a/docs/vi/cli/dashboard.md b/docs/vi/cli/dashboard.md index 6e0b4effe..b1a6a0afd 100644 --- a/docs/vi/cli/dashboard.md +++ b/docs/vi/cli/dashboard.md @@ -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) diff --git a/docs/vi/cli/doctor.md b/docs/vi/cli/doctor.md index cc3359b21..abef17f56 100644 --- a/docs/vi/cli/doctor.md +++ b/docs/vi/cli/doctor.md @@ -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.` cần xác nhận tương tác; `--fix`, `--yes`, và các lần chạy không giao diện giữ nguyên chúng tại chỗ. -- Doctor cũng quét `~/.openclaw/cron/jobs.json` (hoặc `cron.store`) để tìm các dạng tác vụ Cron cũ và có thể ghi lại chúng tại chỗ trước khi bộ lập lịch phải tự động chuẩn hóa chúng lúc chạy. -- Trên Linux, doctor cảnh báo khi crontab của người dùng vẫn chạy `~/.openclaw/bin/ensure-whatsapp.sh` cũ; script đó không còn được bảo trì và có thể ghi log sai về sự cố ngừng hoạt động của WhatsApp Gateway khi Cron thiếu môi trường user-bus của systemd. -- Doctor dọn trạng thái staging phụ thuộc Plugin cũ do các phiên bản OpenClaw cũ tạo ra. Nó cũng sửa các Plugin có thể tải xuống đã cấu hình nhưng bị thiếu khi registry có thể phân giải chúng, và lần chạy doctor 2026.5.2 tự động cài đặt các Plugin có thể tải xuống mà cấu hình cũ đã dùng trước khi đánh dấu cấu hình đã được chạm cho bản phát hành đó. Nếu tải xuống thất bại, doctor báo cáo lỗi cài đặt và giữ nguyên mục Plugin đã cấu hình cho lần sửa tiếp theo. -- Doctor sửa cấu hình Plugin cũ bằng cách xóa các id Plugin bị thiếu khỏi `plugins.allow`/`plugins.entries`, cùng với cấu hình kênh treo tương ứng, mục tiêu Heartbeat và ghi đè mô hình kênh khi phát hiện Plugin hoạt động bình thường. -- Doctor cách ly cấu hình Plugin không hợp lệ bằng cách tắt mục `plugins.entries.` bị ảnh hưởng và xóa payload `config` không hợp lệ của mục đó. Khởi động Gateway đã chỉ bỏ qua Plugin lỗi đó để các Plugin và kênh khác có thể tiếp tục chạy. -- Đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một trình giám sát khác sở hữu vòng đời Gateway. Doctor vẫn báo cáo tình trạng Gateway/dịch vụ và áp dụng các sửa chữa không liên quan đến dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ và dọn dẹp dịch vụ cũ. -- Trên Linux, doctor bỏ qua các unit systemd bổ sung giống Gateway nhưng không hoạt động và không ghi lại metadata lệnh/điểm vào cho một dịch vụ Gateway systemd đang chạy trong quá trình sửa chữa. Dừng dịch vụ trước hoặc dùng `openclaw gateway install --force` khi bạn cố ý muốn thay thế trình khởi chạy đang hoạt động. -- Doctor tự động di chuyển cấu hình Talk dạng phẳng cũ (`talk.voiceId`, `talk.modelId`, và các mục liên quan) vào `talk.provider` + `talk.providers.`. +- 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.` 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.` 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.`. - 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..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..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 diff --git a/docs/vi/cli/gateway.md b/docs/vi/cli/gateway.md index 7bfa7c7ea..2ef9f0bb5 100644 --- a/docs/vi/cli/gateway.md +++ b/docs/vi/cli/gateway.md @@ -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 …`. Thiết lập mDNS cục bộ + DNS-SD diện rộng. - - Cách OpenClaw quảng bá và tìm Gateway. + + Cách OpenClaw quảng bá và tìm gateway. 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 - 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. @@ -58,10 +58,10 @@ openclaw gateway run ### Tùy chọn - 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`). - Chế độ bind listener. + Chế độ bind của listener. 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. - 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. - 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). Đặt lại cấu hình dev + thông tin xác thực + phiên + workspace (yêu cầu `--dev`). - 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. 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). - Kiểu nhật ký WebSocket. + Kiểu nhật ký Websocket. Bí danh cho `--ws-log compact`. - 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. Đường dẫn jsonl của luồng thô. +## 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. + -`--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. ### 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=` để 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=` để 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. - 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. - `--url `: URL WebSocket của Gateway. - `--token `: token Gateway. - `--password `: mật khẩu Gateway. - - `--timeout `: timeout/ngân sách thời gian (khác nhau theo lệnh). + - `--timeout `: timeout/ngân sách (khác nhau theo lệnh). - `--expect-final`: chờ phản hồi "final" (lệnh gọi agent). -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. ### `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`. - 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. - Đọ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. - 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. Đường dẫn đầu ra cho `--export`. - - - 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. + + - 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. ### `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 ``` - Đườ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. 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. - URL WebSocket của Gateway cho snapshot health. + URL WebSocket của Gateway cho ảnh chụp health. - Token Gateway cho snapshot health. + Token Gateway cho ảnh chụp health. - Mật khẩu Gateway cho snapshot health. + Mật khẩu Gateway cho ảnh chụp health. - Timeout snapshot trạng thái/health. + Timeout cho ảnh chụp trạng thái/health. - Bỏ qua tra cứu gói ổn định đã lưu. + Bỏ qua tra cứu bundle ổn định đã lưu. - 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. -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 ``` - 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. - Xác thực token cho probe. + Xác thực bằng token cho lần dò tìm. - 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. - Timeout probe. + Thời gian chờ dò tìm. - 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ụ). Quét cả các dịch vụ cấp hệ thống. - 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`. - - - `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. + + - `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. - - - 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. + + - 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. ### `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` -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. ```bash @@ -326,54 +336,54 @@ openclaw gateway probe --json ``` - - - `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. + + - `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. - - Cấp trên cùng: + + 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 đó. - - - `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`. + + - `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`. -#### 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:`. +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:`. -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`). - Tệp định danh. + Tệp danh tính. - 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. 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 ` -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. - Token của Gateway. + Token Gateway. 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ờ. - 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. - Đầu ra JSON máy có thể đọc. + Đầu ra JSON cho máy đọc. @@ -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 ``` - + - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` - `gateway install`: `--port`, `--runtime `, `--token`, `--wrapper `, `--force`, `--json` - - `gateway restart`: `--force`, `--wait `, `--json` + - `gateway restart`: `--safe`, `--force`, `--wait `, `--json` - `gateway uninstall|start|stop`: `--json` - - - 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. + + - 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. - - - 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. + + - 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. -## 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 ``` - 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). - Đầ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). Ví dụ: @@ -538,9 +545,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- 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 ở đó. diff --git a/docs/vi/cli/plugins.md b/docs/vi/cli/plugins.md index de7eddae6..2e64bae3c 100644 --- a/docs/vi/cli/plugins.md +++ b/docs/vi/cli/plugins.md @@ -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. - 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. - 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. - Mô hình tương thích của bundle. + Mô hình tương thích bundle. Các trường manifest và schema cấu hình. - 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. @@ -62,16 +62,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --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). -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. ### Cài đặt @@ -93,108 +91,100 @@ openclaw plugins install --marketplace https://github.com// -Tên package trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi khi ra mắt. Dùng `clawhub:` cho ClawHub. Hãy coi việc cài đặt plugin như chạy mã. Ưu tiên các phiên bản đã ghim. +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:` 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. -`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. -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`. - - Nếu phần `plugins` của bạn được hỗ trợ bởi một `$include` một tệp, `plugins install/update/enable/disable/uninstall` sẽ ghi xuyên tới tệp được include đó và giữ nguyên `openclaw.json`. Include gốc, mảng include và include có override cùng cấp sẽ fail closed thay vì làm phẳng. Xem [Config include](/vi/gateway/configuration) để biết các dạng được hỗ trợ. + + Nếu 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`. - `--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 `. + `--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 `. - Nếu bạn chạy `plugins install` cho một id plugin đã được cài đặt, OpenClaw sẽ dừng và chỉ bạn tới `plugins update ` để nâng cấp thông thường, hoặc tới `plugins install --force` khi bạn thực sự muốn ghi đè bản cài đặt hiện tại từ một nguồn khác. + 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 ` cho nâng cấp thông thường, hoặc tới `plugins install --force` khi bạn thực sự muốn ghi đè cài đặt hiện tại từ một nguồn khác. - `--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. - `--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). - `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:` 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:` 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`). - Dùng `git:` để cài đặt trực tiếp từ kho git. Các dạng được hỗ trợ gồm `git:github.com/owner/repo`, `git:owner/repo`, URL clone đầy đủ `https://`, `ssh://`, `git://`, `file://` và `git@host:owner/repo.git`. Thêm `@` hoặc `#` để checkout branch, tag hoặc commit trước khi cài đặt. + Dùng `git:` để cài đặt trực tiếp từ một kho git. Các dạng được hỗ trợ gồm `git:github.com/owner/repo`, `git:owner/repo`, URL clone đầy đủ `https://`, `ssh://`, `git://`, `file://` và `git@host:owner/repo.git`. Thêm `@` hoặc `#` để checkout một branch, tag hoặc commit trước khi cài đặt. - 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 --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 --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`. - 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ợ. -Cài đặt ClawHub dùng locator rõ ràng `clawhub:`: +Cài đặt ClawHub dùng locator `clawhub:` 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 openclaw plugins install @ ``` -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 --marketplace @@ -204,28 +194,28 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - tên marketplace đã biết của Claude từ `~/.claude/plugins/known_marketplaces.json` + + - 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 - - 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. + + 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. -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`) -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. ### Liệt kê @@ -241,48 +231,59 @@ openclaw plugins search --json ``` - Chỉ hiển thị các plugin đã bật. + Chỉ hiển thị các Plugin đã bật. - Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng plugin với siêu dữ liệu nguồn/xuất xứ/phiên bản/kích hoạt. + Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng Plugin với siêu dữ liệu nguồn/xuất xứ/phiên bản/kích hoạt. - 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. -`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. -`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:`. +`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:`. -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 --runtime --json` hiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra đã tải module. Kiểm tra runtime không bao giờ cài đặt phụ thuộc; dùng `openclaw doctor --fix` để dọn trạng thái phụ thuộc legacy hoặc cài các plugin tải xuống đã cấu hình bị thiếu. -- `openclaw gateway status --deep --require-rpc` xác nhận Gateway có thể truy cập, gợi ý service/tiến trình, đường dẫn cấu hình, và sức khỏe RPC. -- Hook hội thoại không đi kèm (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) yêu cầu `plugins.entries..hooks.allowConversationAccess=true`. +- `openclaw plugins inspect --runtime --json` hiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra 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..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 ``` -`--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. -### 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 --dry-run openclaw plugins uninstall --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`. -`--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`. ### 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`. - - Khi bạn truyền một plugin id, OpenClaw tái sử dụng spec cài đặt đã ghi cho plugin đó. Điều đó có nghĩa là các dist-tag đã lưu trước đó như `@beta` và các phiên bản ghim chính xác tiếp tục được dùng trong những lần chạy `update ` sau này. + + 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 ` 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. - - `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 đó. + + `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 đó. - - 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`. + + 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. - - `--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. + + `--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. @@ -342,21 +343,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --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 ...`; 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 ...`; 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. -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`. ### 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.` 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.` 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. -`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. ### Marketplace @@ -396,10 +397,10 @@ openclaw plugins marketplace list openclaw plugins marketplace list --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) diff --git a/docs/vi/cli/proxy.md b/docs/vi/cli/proxy.md index 483df0a83..1e873a58e 100644 --- a/docs/vi/cli/proxy.md +++ b/docs/vi/cli/proxy.md @@ -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 ] [--port ] openclaw proxy run [--host ] [--port ] -- -openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--timeout-ms ] +openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--apns-reachable] [--apns-authority ] [--timeout-ms ] openclaw proxy coverage openclaw proxy sessions [--limit ] openclaw proxy query --preset [--session ] @@ -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 `: xác thực URL proxy này thay vì cấu hình hoặc biến môi trường. -- `--allowed-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 `: xác thực URL proxy này thay vì cấu hình hoặc env. +- `--allowed-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 `: 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 `: 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 `: 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 `: 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 ` 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) diff --git a/docs/vi/cli/sessions.md b/docs/vi/cli/sessions.md index 032175377..454f5851e 100644 --- a/docs/vi/cli/sessions.md +++ b/docs/vi/cli/sessions.md @@ -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 ` để 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 `: 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 `: một kho agent đã cấu hình +- `--all-agents`: tổng hợp tất cả kho agent đã cấu hình - `--store `: đường dẫn kho rõ ràng (không thể kết hợp với `--agent` hoặc `--all-agents`) +- `--limit `: 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/.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/.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 `: 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 `: 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 `: 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 `: 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 `: 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 ` để 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 ` để sửa chữa ngoại tuyến rõ ràng một tệp kho. `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/vi/cli/update.md b/docs/vi/cli/update.md index 646267f71..de26421bf 100644 --- a/docs/vi/cli/update.md +++ b/docs/vi/cli/update.md @@ -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 `: đặt kênh cập nhật (git + npm; được lưu trong cấu hình). -- `--tag `: 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 `: 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 `: thời gian chờ cho mỗi bước (mặc định là 1800s). +- `--timeout `: 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). 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 `: 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 `: 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. - Chuyển sang kênh đã chọn (tag hoặc nhánh). + Chuyển sang kênh đã chọn (thẻ hoặc nhánh). - Chỉ dev. + Chỉ dành cho 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. Rebase lên commit đã chọn (chỉ dev). - 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. - - Build gateway và Control UI. + + Build gateway và giao diện điều khiển. - `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. - Đồ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. -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. -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. -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. -## 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). diff --git a/docs/vi/concepts/models.md b/docs/vi/concepts/models.md index 0ffac5a7e..fb40681b7 100644 --- a/docs/vi/concepts/models.md +++ b/docs/vi/concepts/models.md @@ -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 --- - - 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. + + 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. Tổng quan nhanh về nhà cung cấp và ví dụ. - - Pi, Codex, và các môi trường chạy vòng lặp tác tử khác. + + PI, Codex, và các môi trường chạy vòng lặp agent khác. Các khóa cấu hình mô hình. -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: @@ -43,44 +43,44 @@ OpenClaw chọn mô hình theo thứ tự sau: `agents.defaults.model.fallbacks` (theo thứ tự). - - 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. + + 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. - `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)). -## 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`) -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). ### 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 ``` - - `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..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. + + `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..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 --set-default` và `openclaw models set ` 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 --set-default` và `openclaw models set ` vẫn thay thế `agents.defaults.model.primary`. ## "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 to list models. +Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` -Đ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. -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 `. -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 ` 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 - - `/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 đó. - `/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`). - - 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 `. - - 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 `. + - 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. @@ -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: - 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. Chỉ các nhà cung cấp cục bộ. - 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. Mỗi dòng một mô hình. - Đầu ra máy có thể đọc được. + Đầu ra máy có thể đọc. ### `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. - - 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.` 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.` 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`. -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ó. Ví dụ (Claude CLI): @@ -298,7 +301,7 @@ openclaw models status -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. 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//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//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`. - 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. -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`. ## 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 diff --git a/docs/vi/concepts/qa-e2e-automation.md b/docs/vi/concepts/qa-e2e-automation.md index 09290989e..97ff474be 100644 --- a/docs/vi/concepts/qa-e2e-automation.md +++ b/docs/vi/concepts/qa-e2e-automation.md @@ -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 `. 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-/`. +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-/`. -Đố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 ` 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 ` 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 ` để đ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 ` để 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 ` | — | Chỉ chạy scenario này. Có thể lặp lại. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | 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 ` | `process.cwd()` | Repo root khi gọi từ một cwd trung lập. | -| `--sut-account ` | `sut` | Id tài khoản tạm thời bên trong cấu hình QA gateway. | -| `--provider-mode ` | `live-frontier` | `mock-openai` hoặc `live-frontier` (`live-openai` cũ vẫn hoạt động). | -| `--model ` / `--alt-model ` | mặc định của nhà cung cấp | Ref model chính/thay thế. | -| `--fast` | tắt | Chế độ nhanh của nhà cung cấp khi được hỗ trợ. | -| `--credential-source ` | `env` | Xem [nhóm credential Convex](#convex-credential-pool). | -| `--credential-role ` | `ci` trong CI, nếu không thì `maintainer` | Role được dùng khi `--credential-source convex`. | +| Cờ | Mặc định | Mô tả | +| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Chỉ chạy kịch bản này. Có thể lặp lại. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Nơi ghi báo cáo/tóm tắt/tin nhắn quan sát được và log đầu ra. Đường dẫn tương đối được resolve theo `--repo-root`. | +| `--repo-root ` | `process.cwd()` | Thư mục gốc repository khi gọi từ một cwd trung lập. | +| `--sut-account ` | `sut` | Id tài khoản tạm thời bên trong cấu hình Gateway QA. | +| `--provider-mode ` | `live-frontier` | `mock-openai` hoặc `live-frontier` (`live-openai` cũ vẫn hoạt động). | +| `--model ` / `--alt-model ` | mặc định của provider | Tham chiếu model chính/phụ. | +| `--fast` | tắt | Chế độ nhanh của provider khi được hỗ trợ. | +| `--credential-source ` | `env` | Xem [pool thông tin đăng nhập Convex](#convex-credential-pool). | +| `--credential-role ` | `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//*.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 ` đượ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 ` đượ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 ` 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 ` 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=`. `--thinking ` vẫn đặt một -fallback toàn cục, và dạng cũ hơn `--model-thinking ` đượ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=`. `--thinking ` vẫn đặt giá trị dự phòng toàn cục, và dạng cũ hơn `--model-thinking ` đượ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) diff --git a/docs/vi/gateway/cli-backends.md b/docs/vi/gateway/cli-backends.md index c4e2d0bca..5b3efd84f 100644 --- a/docs/vi/gateway/cli-backends.md +++ b/docs/vi/gateway/cli-backends.md @@ -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: ``` / @@ -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. -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. 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.` 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) diff --git a/docs/vi/gateway/config-tools.md b/docs/vi/gateway/config-tools.md index fdc2d771b..0b6d7744d 100644 --- a/docs/vi/gateway/config-tools.md +++ b/docs/vi/gateway/config-tools.md @@ -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`: -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). | 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* ``` - 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. 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. - 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ố. - 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.). 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. -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. ### `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 ``` - - **Mục nhập nhà cung cấp** (`type: "provider"` hoặc bị bỏ qua): + + **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. @@ -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 - `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"`. @@ -337,12 +337,12 @@ Kiểm soát hỗ trợ tệp đính kèm nội tuyến cho `sessions_spawn`. - - 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//` 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//` 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`. @@ -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//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//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 ``` - - - 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). + + - 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. @@ -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 - - - `models.mode`: hành vi catalog nhà cung cấp (`merge` hoặc `replace`). + + - `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. '' --strict-json --merge` hoặc `openclaw config set models.providers..models '' --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. '' --strict-json --merge` hoặc `openclaw config set models.providers..models '' --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`. - - `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. - `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`. - - - `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. + + - `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. - - `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 -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 - 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. - + ```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`. - 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. ```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`. @@ -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. @@ -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`. @@ -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`. @@ -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ở. @@ -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) diff --git a/docs/vi/gateway/configuration-reference.md b/docs/vi/gateway/configuration-reference.md index bd05e83ac..bce7f63ae 100644 --- a/docs/vi/gateway/configuration-reference.md +++ b/docs/vi/gateway/configuration-reference.md @@ -2,73 +2,73 @@ read_when: - Bạn cần ngữ nghĩa cấu hình chính xác ở cấp trường hoặc các giá trị mặc định - Bạn đang xác thực các khối cấu hình kênh, mô hình, Gateway hoặc công cụ -summary: Tài liệu tham chiếu cấu hình Gateway cho các khóa OpenClaw cốt lõi, giá trị mặc định và liên kết đến các tài liệu tham chiếu riêng cho từng hệ thống con +summary: Tài liệu tham chiếu cấu hình Gateway cho các khóa OpenClaw cốt lõi, giá trị mặc định và liên kết đến tài liệu tham chiếu hệ thống con chuyên biệt title: Tham chiếu cấu hình x-i18n: - generated_at: "2026-05-03T21:31:17Z" + generated_at: "2026-05-05T01:46:07Z" model: gpt-5.5 provider: openai - source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9 + source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 source_path: gateway/configuration-reference.md workflow: 16 --- -Tham chiếu cấu hình lõi cho `~/.openclaw/openclaw.json`. Để xem tổng quan theo hướng tác vụ, xem [Cấu hình](/vi/gateway/configuration). +Tài liệu tham chiếu cấu hình lõi cho `~/.openclaw/openclaw.json`. Để xem tổng quan theo tác vụ, hãy xem [Cấu hình](/vi/gateway/configuration). -Bao quát các bề mặt cấu hình OpenClaw chính và liên kết ra ngoài khi một hệ thống con có tham chiếu chuyên sâu riêng. Các danh mục lệnh do kênh và Plugin sở hữu cùng các núm chỉnh bộ nhớ sâu/QMD nằm trên các trang riêng thay vì trên trang này. +Bao quát các bề mặt cấu hình chính của OpenClaw và liên kết ra ngoài khi một hệ thống con có tài liệu tham chiếu sâu hơn riêng. Catalog lệnh do kênh và plugin sở hữu cùng các núm chỉnh bộ nhớ sâu/QMD nằm trên các trang riêng thay vì trên trang này. -Sự thật từ mã: +Nguồn sự thật trong mã: -- `openclaw config schema` in JSON Schema trực tiếp được dùng để xác thực và Control UI, với siêu dữ liệu gói kèm/Plugin/kênh được hợp nhất khi có sẵn -- `config.schema.lookup` trả về một nút schema theo phạm vi đường dẫn cho công cụ đi sâu -- `pnpm config:docs:check` / `pnpm config:docs:gen` xác thực hash đường cơ sở tài liệu cấu hình so với bề mặt schema hiện tại +- `openclaw config schema` in JSON Schema đang dùng để xác thực và Control UI, với siêu dữ liệu bundled/plugin/kênh được hợp nhất khi có +- `config.schema.lookup` trả về một nút schema theo phạm vi đường dẫn cho công cụ đào sâu +- `pnpm config:docs:check` / `pnpm config:docs:gen` xác thực hash baseline tài liệu cấu hình so với bề mặt schema hiện tại -Đường dẫn tra cứu agent: dùng thao tác công cụ `gateway` `config.schema.lookup` để -xem tài liệu và ràng buộc chính xác ở cấp trường trước khi chỉnh sửa. Dùng -[Cấu hình](/vi/gateway/configuration) để có hướng dẫn theo hướng tác vụ và trang này -để xem bản đồ trường rộng hơn, mặc định, và liên kết tới tham chiếu hệ thống con. +Đường dẫn tra cứu agent: dùng hành động công cụ `gateway` `config.schema.lookup` để +lấy tài liệu và ràng buộc chính xác ở cấp trường trước khi chỉnh sửa. Dùng +[Cấu hình](/vi/gateway/configuration) để được hướng dẫn theo tác vụ và dùng trang này +cho bản đồ trường rộng hơn, giá trị mặc định, và liên kết tới tài liệu tham chiếu hệ thống con. -Các tham chiếu chuyên sâu riêng: +Tài liệu tham chiếu sâu chuyên dụng: -- [Tham chiếu cấu hình bộ nhớ](/vi/reference/memory-config) cho `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, và cấu hình dreaming dưới `plugins.entries.memory-core.config.dreaming` -- [Lệnh slash](/vi/tools/slash-commands) cho danh mục lệnh tích hợp + gói kèm hiện tại -- các trang kênh/Plugin sở hữu cho các bề mặt lệnh dành riêng cho kênh +- [Tài liệu tham chiếu cấu hình bộ nhớ](/vi/reference/memory-config) cho `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, và cấu hình dreaming trong `plugins.entries.memory-core.config.dreaming` +- [Lệnh slash](/vi/tools/slash-commands) cho catalog lệnh tích hợp sẵn + bundled hiện tại +- các trang kênh/plugin sở hữu cho bề mặt lệnh dành riêng cho kênh -Định dạng cấu hình là **JSON5** (cho phép chú thích + dấu phẩy cuối). Tất cả các trường đều là tùy chọn — OpenClaw dùng mặc định an toàn khi bị bỏ qua. +Định dạng cấu hình là **JSON5** (cho phép chú thích + dấu phẩy cuối). Tất cả trường đều là tùy chọn — OpenClaw dùng giá trị mặc định an toàn khi bị bỏ qua. --- ## Kênh -Các khóa cấu hình theo kênh đã chuyển sang một trang riêng — xem +Các khóa cấu hình theo từng kênh đã được chuyển sang một trang riêng — xem [Cấu hình — kênh](/vi/gateway/config-channels) cho `channels.*`, bao gồm Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, và các kênh -gói kèm khác (xác thực, kiểm soát truy cập, nhiều tài khoản, cổng nhắc đến). +bundled khác (xác thực, kiểm soát truy cập, đa tài khoản, chặn theo mention). -## Mặc định agent, đa agent, phiên, và tin nhắn +## Giá trị mặc định của agent, đa agent, phiên, và tin nhắn Đã chuyển sang một trang riêng — xem [Cấu hình — agent](/vi/gateway/config-agents) cho: - `agents.defaults.*` (workspace, model, thinking, heartbeat, bộ nhớ, media, skills, sandbox) -- `multiAgent.*` (định tuyến và liên kết đa agent) +- `multiAgent.*` (định tuyến và binding đa agent) - `session.*` (vòng đời phiên, compaction, cắt tỉa) -- `messages.*` (gửi tin nhắn, TTS, hiển thị markdown) +- `messages.*` (phân phối tin nhắn, TTS, kết xuất markdown) - `talk.*` (chế độ Talk) - `talk.speechLocale`: id locale BCP 47 tùy chọn cho nhận dạng giọng nói Talk trên iOS/macOS - - `talk.silenceTimeoutMs`: khi chưa đặt, Talk giữ cửa sổ tạm dừng mặc định của nền tảng trước khi gửi bản ghi (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.silenceTimeoutMs`: khi chưa đặt, Talk giữ cửa sổ tạm dừng mặc định của nền tảng trước khi gửi bản chép lời (`700 ms trên macOS và Android, 900 ms trên iOS`) -## Công cụ và nhà cung cấp tùy chỉnh +## Công cụ và provider tùy chỉnh -Chính sách công cụ, công tắc thử nghiệm, cấu hình công cụ dựa trên nhà cung cấp, và thiết lập -nhà cung cấp / base-URL tùy chỉnh đã chuyển sang một trang riêng — xem -[Cấu hình — công cụ và nhà cung cấp tùy chỉnh](/vi/gateway/config-tools). +Chính sách công cụ, công tắc thử nghiệm, cấu hình công cụ dựa trên provider, và thiết lập +provider / base-URL tùy chỉnh đã chuyển sang một trang riêng — xem +[Cấu hình — công cụ và provider tùy chỉnh](/vi/gateway/config-tools). ## Model -Định nghĩa nhà cung cấp, danh sách cho phép model, và thiết lập nhà cung cấp tùy chỉnh nằm trong -[Cấu hình — công cụ và nhà cung cấp tùy chỉnh](/vi/gateway/config-tools#custom-providers-and-base-urls). -Gốc `models` cũng sở hữu hành vi danh mục model toàn cục. +Định nghĩa provider, allowlist model, và thiết lập provider tùy chỉnh nằm trong +[Cấu hình — công cụ và provider tùy chỉnh](/vi/gateway/config-tools#custom-providers-and-base-urls). +Gốc `models` cũng sở hữu hành vi catalog model toàn cục. ```json5 { @@ -79,19 +79,19 @@ Gốc `models` cũng sở hữu hành vi danh mục model toàn cục. } ``` -- `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. -- `models.pricing.enabled`: kiểm soát bootstrap giá chạy nền bắt đầu - sau khi sidecar và kênh đi tới đường dẫn Gateway sẵn sàng. Khi `false`, - Gateway bỏ qua các lần fetch danh mục giá OpenRouter và LiteLLM; các giá trị +- `models.mode`: hành vi catalog provider (`merge` hoặc `replace`). +- `models.providers`: bản đồ provider tùy chỉnh được khóa theo id provider. +- `models.pricing.enabled`: kiểm soát bootstrap giá nền + bắt đầu sau khi sidecar và kênh đi tới đường dẫn Gateway sẵn sàng. Khi là `false`, + Gateway bỏ qua việc lấy catalog giá OpenRouter và LiteLLM; các giá trị `models.providers.*.models[].cost` đã cấu hình vẫn hoạt động cho ước tính chi phí cục bộ. ## MCP -Các định nghĩa máy chủ MCP do OpenClaw quản lý nằm dưới `mcp.servers` và được -Pi nhúng cùng các bộ điều hợp runtime khác sử dụng. Các lệnh `openclaw mcp list`, +Định nghĩa MCP server do OpenClaw quản lý nằm trong `mcp.servers` và được +Pi nhúng cùng các runtime adapter khác sử dụng. Các lệnh `openclaw mcp list`, `show`, `set`, và `unset` quản lý khối này mà không kết nối tới -máy chủ đích trong lúc chỉnh sửa cấu hình. +server đích trong khi chỉnh sửa cấu hình. ```json5 { @@ -115,17 +115,17 @@ máy chủ đích trong lúc chỉnh sửa cấu hình. } ``` -- `mcp.servers`: các định nghĩa máy chủ MCP stdio hoặc từ xa có tên cho các runtime +- `mcp.servers`: định nghĩa MCP server stdio hoặc từ xa có tên cho các runtime phơi bày công cụ MCP đã cấu hình. Mục từ xa dùng `transport: "streamable-http"` hoặc `transport: "sse"`; - `type: "http"` là bí danh gốc CLI mà `openclaw mcp set` và - `openclaw doctor --fix` chuẩn hóa thành trường `transport` chính tắc. -- `mcp.sessionIdleTtlMs`: TTL nhàn rỗi cho các runtime MCP gói kèm theo phạm vi phiên. - Các lần chạy nhúng một lần yêu cầu dọn dẹp khi kết thúc chạy; TTL này là chốt chặn cho + `type: "http"` là alias gốc CLI mà `openclaw mcp set` và + `openclaw doctor --fix` chuẩn hóa vào trường canonical `transport`. +- `mcp.sessionIdleTtlMs`: TTL nhàn rỗi cho runtime MCP bundled theo phạm vi phiên. + Các lượt chạy nhúng một lần yêu cầu dọn dẹp khi kết thúc lượt chạy; TTL này là chốt chặn cho các phiên sống lâu và caller tương lai. -- Các thay đổi dưới `mcp.*` áp dụng nóng bằng cách hủy bỏ các runtime MCP phiên đã cache. - Lần khám phá/sử dụng công cụ tiếp theo tạo lại chúng từ cấu hình mới, nên các mục - `mcp.servers` đã xóa được thu hồi ngay thay vì chờ TTL nhàn rỗi. +- Thay đổi dưới `mcp.*` được áp dụng nóng bằng cách hủy runtime MCP phiên đã cache. + Lần phát hiện/dùng công cụ tiếp theo sẽ tạo lại chúng từ cấu hình mới, nên các mục + `mcp.servers` đã bị xóa được thu dọn ngay thay vì chờ TTL nhàn rỗi. Xem [MCP](/vi/cli/mcp#openclaw-as-an-mcp-client-registry) và [Backend CLI](/vi/gateway/cli-backends#bundle-mcp-overlays) để biết hành vi runtime. @@ -155,13 +155,13 @@ Xem [MCP](/vi/cli/mcp#openclaw-as-an-mcp-client-registry) và } ``` -- `allowBundled`: danh sách cho phép tùy chọn chỉ dành cho Skills gói kèm (Skills được quản lý/workspace không bị ảnh hưởng). +- `allowBundled`: allowlist tùy chọn chỉ cho Skills bundled (không ảnh hưởng Skills được quản lý/workspace). - `load.extraDirs`: các gốc skill dùng chung bổ sung (độ ưu tiên thấp nhất). - `install.preferBrew`: khi true, ưu tiên trình cài đặt Homebrew khi `brew` có - sẵn trước khi quay lại các loại trình cài đặt khác. -- `install.nodeManager`: ưu tiên trình cài đặt node cho đặc tả `metadata.openclaw.install` + sẵn trước khi fallback sang các loại trình cài đặt khác. +- `install.nodeManager`: tùy chọn trình cài đặt node cho spec `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` tắt một skill ngay cả khi được gói kèm/đã cài. +- `entries..enabled: false` tắt một skill ngay cả khi bundled/đã cài đặt. - `entries..apiKey`: tiện ích cho Skills khai báo biến env chính (chuỗi plaintext hoặc đối tượng SecretRef). --- @@ -173,6 +173,7 @@ Xem [MCP](/vi/cli/mcp#openclaw-as-an-mcp-client-registry) và plugins: { enabled: true, allow: ["voice-call"], + bundledDiscovery: "allowlist", deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], @@ -191,40 +192,42 @@ Xem [MCP](/vi/cli/mcp#openclaw-as-an-mcp-client-registry) và ``` - Được tải từ `~/.openclaw/extensions`, `/.openclaw/extensions`, cộng với `plugins.load.paths`. -- Khám phá chấp nhận Plugin OpenClaw gốc cùng các bundle Codex tương thích và bundle Claude, bao gồm các bundle bố cục mặc định Claude không có manifest. +- Discovery chấp nhận plugin OpenClaw native cộng với bundle Codex tương thích và bundle Claude, bao gồm bundle bố cục mặc định Claude không có manifest. - **Thay đổi cấu hình yêu cầu khởi động lại gateway.** -- `allow`: danh sách cho phép tùy chọn (chỉ các Plugin được liệt kê được tải). `deny` thắng. -- `plugins.entries..apiKey`: trường tiện ích khóa API cấp Plugin (khi Plugin hỗ trợ). -- `plugins.entries..env`: bản đồ biến env theo phạm vi Plugin. -- `plugins.entries..hooks.allowPromptInjection`: khi `false`, lõi chặn `before_prompt_build` và bỏ qua các trường thay đổi prompt từ `before_agent_start` cũ, trong khi vẫn giữ `modelOverride` và `providerOverride` cũ. Áp dụng cho hook Plugin gốc và các thư mục hook do bundle cung cấp được hỗ trợ. -- `plugins.entries..hooks.allowConversationAccess`: khi `true`, Plugin không gói kèm đáng tin cậy có thể đọc nội dung hội thoại thô từ các hook có kiểu như `llm_input`, `llm_output`, `before_agent_finalize`, và `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: tin cậy rõ ràng Plugin này để yêu cầu ghi đè `provider` và `model` theo từng lần chạy cho các lần chạy subagent nền. -- `plugins.entries..subagent.allowedModels`: danh sách cho phép tùy chọn các đích `provider/model` chính tắc cho ghi đè subagent đáng tin cậy. Chỉ dùng `"*"` khi bạn cố ý muốn cho phép bất kỳ model nào. -- `plugins.entries..config`: đối tượng cấu hình do Plugin định nghĩa (được schema Plugin OpenClaw gốc xác thực khi có sẵn). -- Thiết lập tài khoản/runtime của Plugin kênh nằm dưới `channels.` và nên được mô tả bằng siêu dữ liệu `channelConfigs` trong manifest của Plugin sở hữu, không phải bằng registry tùy chọn OpenClaw trung tâm. -- `plugins.entries.firecrawl.config.webFetch`: thiết lập nhà cung cấp web-fetch Firecrawl. - - `apiKey`: khóa API Firecrawl (chấp nhận SecretRef). Quay lại `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` cũ, hoặc biến env `FIRECRAWL_API_KEY`. - - `baseUrl`: URL cơ sở API Firecrawl (mặc định: `https://api.firecrawl.dev`; ghi đè self-hosted phải nhắm tới endpoint riêng/nội bộ). +- `allow`: allowlist tùy chọn (chỉ plugin được liệt kê mới tải). `deny` thắng. +- `bundledDiscovery`: mặc định là `"allowlist"` cho cấu hình mới, nên một + `plugins.allow` không rỗng cũng chặn các plugin provider bundled, bao gồm provider runtime web-search. Doctor ghi `"compat"` cho cấu hình allowlist legacy đã migrate để giữ nguyên hành vi provider bundled hiện có cho tới khi bạn chọn tham gia. +- `plugins.entries..apiKey`: trường tiện ích khóa API cấp plugin (khi plugin hỗ trợ). +- `plugins.entries..env`: bản đồ biến env theo phạm vi plugin. +- `plugins.entries..hooks.allowPromptInjection`: khi là `false`, core chặn `before_prompt_build` và bỏ qua các trường sửa đổi prompt từ `before_agent_start` legacy, đồng thời giữ nguyên `modelOverride` và `providerOverride` legacy. Áp dụng cho hook plugin native và thư mục hook do bundle cung cấp được hỗ trợ. +- `plugins.entries..hooks.allowConversationAccess`: khi là `true`, plugin không bundled được tin cậy có thể đọc nội dung hội thoại thô từ các hook typed như `llm_input`, `llm_output`, `before_agent_finalize`, và `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: tin cậy rõ ràng plugin này để yêu cầu ghi đè `provider` và `model` theo từng lượt chạy cho các lượt chạy subagent nền. +- `plugins.entries..subagent.allowedModels`: allowlist tùy chọn của các đích `provider/model` canonical cho ghi đè subagent được tin cậy. Chỉ dùng `"*"` khi bạn chủ đích muốn cho phép bất kỳ model nào. +- `plugins.entries..config`: đối tượng cấu hình do plugin định nghĩa (được xác thực bởi schema plugin OpenClaw native khi có). +- Cài đặt tài khoản/runtime của plugin kênh nằm dưới `channels.` và nên được mô tả bởi siêu dữ liệu `channelConfigs` trong manifest của plugin sở hữu, không phải bởi một registry tùy chọn OpenClaw trung tâm. +- `plugins.entries.firecrawl.config.webFetch`: cài đặt provider web-fetch Firecrawl. + - `apiKey`: khóa API Firecrawl (chấp nhận SecretRef). Fallback sang `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` legacy, hoặc biến env `FIRECRAWL_API_KEY`. + - `baseUrl`: URL cơ sở API Firecrawl (mặc định: `https://api.firecrawl.dev`; ghi đè self-hosted phải nhắm tới endpoint riêng tư/nội bộ). - `onlyMainContent`: chỉ trích xuất nội dung chính từ trang (mặc định: `true`). - `maxAgeMs`: tuổi cache tối đa tính bằng mili giây (mặc định: `172800000` / 2 ngày). - `timeoutSeconds`: thời gian chờ yêu cầu scrape tính bằng giây (mặc định: `60`). -- `plugins.entries.xai.config.xSearch`: thiết lập xAI X Search (tìm kiếm web Grok). - - `enabled`: bật nhà cung cấp X Search. +- `plugins.entries.xai.config.xSearch`: cài đặt xAI X Search (tìm kiếm web Grok). + - `enabled`: bật provider X Search. - `model`: model Grok dùng cho tìm kiếm (ví dụ: `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: thiết lập memory dreaming. Xem [Dreaming](/vi/concepts/dreaming) để biết các pha và ngưỡng. +- `plugins.entries.memory-core.config.dreaming`: cài đặt memory dreaming. Xem [Dreaming](/vi/concepts/dreaming) để biết các pha và ngưỡng. - `enabled`: công tắc dreaming chính (mặc định `false`). - - `frequency`: nhịp cron cho mỗi lần quét dreaming đầy đủ (`"0 3 * * *"` theo mặc định). - - `model`: ghi đè model subagent Dream Diary tùy chọn. Yêu cầu `plugins.entries.memory-core.subagent.allowModelOverride: true`; ghép với `allowedModels` để hạn chế đích. Lỗi model không khả dụng thử lại một lần bằng model mặc định của phiên; lỗi tin cậy hoặc danh sách cho phép không âm thầm quay lại. - - chính sách pha và ngưỡng là chi tiết triển khai (không phải khóa cấu hình hướng tới người dùng). -- Cấu hình bộ nhớ đầy đủ nằm trong [Tham chiếu cấu hình bộ nhớ](/vi/reference/memory-config): + - `frequency`: nhịp Cron cho mỗi lượt quét dreaming đầy đủ (`"0 3 * * *"` theo mặc định). + - `model`: ghi đè model subagent Dream Diary tùy chọn. Yêu cầu `plugins.entries.memory-core.subagent.allowModelOverride: true`; ghép với `allowedModels` để giới hạn đích. Lỗi model không khả dụng thử lại một lần với model mặc định của phiên; lỗi tin cậy hoặc allowlist không fallback âm thầm. + - chính sách pha và ngưỡng là chi tiết triển khai (không phải khóa cấu hình dành cho người dùng). +- Cấu hình bộ nhớ đầy đủ nằm trong [Tài liệu tham chiếu cấu hình bộ nhớ](/vi/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Plugin bundle Claude đã bật cũng có thể đóng góp mặc định Pi nhúng từ `settings.json`; OpenClaw áp dụng chúng như thiết lập agent đã làm sạch, không phải bản vá cấu hình OpenClaw thô. -- `plugins.slots.memory`: chọn id Plugin bộ nhớ đang hoạt động, hoặc `"none"` để tắt Plugin bộ nhớ. -- `plugins.slots.contextEngine`: chọn id Plugin context engine đang hoạt động; mặc định là `"legacy"` trừ khi bạn cài đặt và chọn engine khác. +- Plugin bundle Claude đã bật cũng có thể đóng góp giá trị mặc định Pi nhúng từ `settings.json`; OpenClaw áp dụng chúng dưới dạng cài đặt agent đã làm sạch, không phải bản vá cấu hình OpenClaw thô. +- `plugins.slots.memory`: chọn id plugin bộ nhớ đang hoạt động, hoặc `"none"` để tắt plugin bộ nhớ. +- `plugins.slots.contextEngine`: chọn id plugin context engine đang hoạt động; mặc định là `"legacy"` trừ khi bạn cài đặt và chọn engine khác. Xem [Plugin](/vi/tools/plugin). @@ -232,10 +235,10 @@ Xem [Plugin](/vi/tools/plugin). ## Cam kết -`commitments` kiểm soát bộ nhớ theo dõi suy luận: OpenClaw có thể phát hiện lượt check-in từ các lượt hội thoại và gửi chúng qua các lần chạy heartbeat. +`commitments` kiểm soát bộ nhớ theo dõi suy luận: OpenClaw có thể phát hiện check-in từ các lượt hội thoại và phân phối chúng qua các lượt heartbeat. -- `commitments.enabled`: bật trích xuất LLM ẩn, lưu trữ, và gửi heartbeat cho các cam kết theo dõi suy luận. Mặc định: `false`. -- `commitments.maxPerDay`: số cam kết theo dõi suy luận tối đa được gửi cho mỗi phiên agent trong một ngày cuốn chiếu. Mặc định: `3`. +- `commitments.enabled`: bật trích xuất LLM ẩn, lưu trữ, và phân phối heartbeat cho các cam kết theo dõi suy luận. Mặc định: `false`. +- `commitments.maxPerDay`: số cam kết theo dõi suy luận tối đa được phân phối cho mỗi phiên agent trong một ngày cuốn. Mặc định: `3`. Xem [Cam kết suy luận](/vi/concepts/commitments). @@ -288,47 +291,31 @@ Xem [Cam kết suy luận](/vi/concepts/commitments). ``` - `evaluateEnabled: false` vô hiệu hóa `act:evaluate` và `wait --fn`. -- `tabCleanup` thu hồi các tab agent chính được theo dõi sau thời gian nhàn rỗi hoặc khi một phiên vượt quá giới hạn. Đặt `idleMinutes: 0` hoặc `maxTabsPerSession: 0` để vô hiệu hóa từng chế độ dọn dẹp riêng lẻ đó. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` bị vô hiệu hóa khi chưa được đặt, nên điều hướng trình duyệt vẫn nghiêm ngặt theo mặc định. -- Chỉ đặt `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` khi bạn chủ động tin tưởng điều hướng trình duyệt trên mạng riêng. -- Ở chế độ nghiêm ngặt, các endpoint hồ sơ CDP từ xa (`profiles.*.cdpUrl`) chịu cùng cơ chế chặn mạng riêng trong quá trình kiểm tra khả năng truy cập/khám phá. +- `tabCleanup` thu hồi các thẻ tác nhân chính được theo dõi sau thời gian nhàn rỗi hoặc khi một phiên vượt quá giới hạn của nó. Đặt `idleMinutes: 0` hoặc `maxTabsPerSession: 0` để vô hiệu hóa từng chế độ dọn dẹp riêng lẻ đó. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` bị vô hiệu hóa khi chưa được đặt, nên điều hướng trình duyệt mặc định vẫn nghiêm ngặt. +- Chỉ đặt `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` khi bạn chủ ý tin cậy điều hướng trình duyệt qua mạng riêng. +- Ở chế độ nghiêm ngặt, các điểm cuối hồ sơ CDP từ xa (`profiles.*.cdpUrl`) chịu cùng cơ chế chặn mạng riêng trong các kiểm tra khả năng truy cập/khám phá. - `ssrfPolicy.allowPrivateNetwork` vẫn được hỗ trợ như một bí danh cũ. -- Ở chế độ nghiêm ngặt, hãy dùng `ssrfPolicy.hostnameAllowlist` và `ssrfPolicy.allowedHostnames` cho các ngoại lệ tường minh. -- Hồ sơ từ xa chỉ cho phép đính kèm (vô hiệu hóa start/stop/reset). +- Ở chế độ nghiêm ngặt, dùng `ssrfPolicy.hostnameAllowlist` và `ssrfPolicy.allowedHostnames` cho các ngoại lệ tường minh. +- Hồ sơ từ xa là chỉ đính kèm (vô hiệu hóa khởi động/dừng/đặt lại). - `profiles.*.cdpUrl` chấp nhận `http://`, `https://`, `ws://` và `wss://`. Dùng HTTP(S) khi bạn muốn OpenClaw khám phá `/json/version`; dùng WS(S) - khi nhà cung cấp của bạn cung cấp URL DevTools WebSocket trực tiếp. -- `remoteCdpTimeoutMs` và `remoteCdpHandshakeTimeoutMs` áp dụng cho khả năng truy cập CDP từ xa và - `attachOnly`, cùng với các yêu cầu mở tab. Các hồ sơ loopback được quản lý - giữ nguyên giá trị mặc định CDP cục bộ. -- Nếu một dịch vụ CDP được quản lý bên ngoài có thể truy cập qua loopback, hãy đặt - `attachOnly: true` cho hồ sơ đó; nếu không, OpenClaw xem cổng loopback là một - hồ sơ trình duyệt được quản lý cục bộ và có thể báo lỗi quyền sở hữu cổng cục bộ. -- Hồ sơ `existing-session` dùng Chrome MCP thay vì CDP và có thể đính kèm trên - máy chủ đã chọn hoặc thông qua một nút trình duyệt đã kết nối. -- Hồ sơ `existing-session` có thể đặt `userDataDir` để nhắm tới một - hồ sơ trình duyệt dựa trên Chromium cụ thể như Brave hoặc Edge. -- Hồ sơ `existing-session` giữ các giới hạn tuyến Chrome MCP hiện tại: - hành động dựa trên snapshot/ref thay vì nhắm mục tiêu bằng CSS-selector, hook tải lên một tệp, - không ghi đè thời gian chờ hộp thoại, không có `wait --load networkidle`, và không có - `responsebody`, xuất PDF, chặn tải xuống, hoặc hành động hàng loạt. -- Hồ sơ `openclaw` được quản lý cục bộ tự động gán `cdpPort` và `cdpUrl`; chỉ - đặt `cdpUrl` rõ ràng cho CDP từ xa. -- Hồ sơ được quản lý cục bộ có thể đặt `executablePath` để ghi đè - `browser.executablePath` toàn cục cho hồ sơ đó. Dùng cách này để chạy một hồ sơ trong - Chrome và một hồ sơ khác trong Brave. -- Hồ sơ được quản lý cục bộ dùng `browser.localLaunchTimeoutMs` cho quá trình khám phá HTTP Chrome CDP - sau khi tiến trình khởi động và `browser.localCdpReadyTimeoutMs` cho - trạng thái sẵn sàng websocket CDP sau khi khởi chạy. Tăng các giá trị này trên máy chủ chậm hơn, nơi Chrome - khởi động thành công nhưng kiểm tra trạng thái sẵn sàng chạy đua với quá trình khởi động. Cả hai giá trị phải là - số nguyên dương tối đa `120000` ms; các giá trị cấu hình không hợp lệ sẽ bị từ chối. -- Thứ tự tự phát hiện: trình duyệt mặc định nếu dựa trên Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` và `browser.profiles..executablePath` đều - chấp nhận `~` và `~/...` cho thư mục home của hệ điều hành trước khi khởi chạy Chromium. - `userDataDir` theo từng hồ sơ trên các hồ sơ `existing-session` cũng được mở rộng dấu ngã. + khi nhà cung cấp của bạn cấp cho bạn URL DevTools WebSocket trực tiếp. +- `remoteCdpTimeoutMs` và `remoteCdpHandshakeTimeoutMs` áp dụng cho khả năng truy cập CDP từ xa và `attachOnly`, cùng các yêu cầu mở thẻ. Hồ sơ local loopback được quản lý vẫn giữ các giá trị mặc định CDP cục bộ. +- Nếu một dịch vụ CDP được quản lý bên ngoài có thể truy cập qua loopback, hãy đặt `attachOnly: true` cho hồ sơ đó; nếu không OpenClaw sẽ xem cổng loopback là hồ sơ trình duyệt được quản lý cục bộ và có thể báo lỗi quyền sở hữu cổng cục bộ. +- Hồ sơ `existing-session` dùng Chrome MCP thay vì CDP và có thể đính kèm trên máy chủ đã chọn hoặc qua một nút trình duyệt đã kết nối. +- Hồ sơ `existing-session` có thể đặt `userDataDir` để nhắm tới một hồ sơ trình duyệt dựa trên Chromium cụ thể như Brave hoặc Edge. +- Hồ sơ `existing-session` giữ các giới hạn định tuyến Chrome MCP hiện tại: + hành động dựa trên snapshot/ref thay vì nhắm mục tiêu bằng bộ chọn CSS, hook tải lên một tệp, không ghi đè thời gian chờ hộp thoại, không có `wait --load networkidle`, và không có `responsebody`, xuất PDF, chặn tải xuống hoặc hành động hàng loạt. +- Hồ sơ `openclaw` được quản lý cục bộ tự động gán `cdpPort` và `cdpUrl`; chỉ đặt `cdpUrl` tường minh cho CDP từ xa. +- Hồ sơ được quản lý cục bộ có thể đặt `executablePath` để ghi đè `browser.executablePath` toàn cục cho hồ sơ đó. Dùng tùy chọn này để chạy một hồ sơ trong Chrome và hồ sơ khác trong Brave. +- Hồ sơ được quản lý cục bộ dùng `browser.localLaunchTimeoutMs` cho việc khám phá Chrome CDP HTTP sau khi tiến trình khởi động và `browser.localCdpReadyTimeoutMs` cho trạng thái sẵn sàng websocket CDP sau khi khởi chạy. Tăng các giá trị này trên máy chủ chậm hơn, nơi Chrome khởi động thành công nhưng các kiểm tra sẵn sàng chạy đua với quá trình khởi động. Cả hai giá trị phải là số nguyên dương tối đa `120000` ms; giá trị cấu hình không hợp lệ sẽ bị từ chối. +- Thứ tự tự động phát hiện: trình duyệt mặc định nếu dựa trên Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Cả `browser.executablePath` và `browser.profiles..executablePath` + đều chấp nhận `~` và `~/...` cho thư mục chính của hệ điều hành trước khi khởi chạy Chromium. + `userDataDir` theo từng hồ sơ trên hồ sơ `existing-session` cũng được mở rộng dấu ngã. - Dịch vụ điều khiển: chỉ loopback (cổng được suy ra từ `gateway.port`, mặc định `18791`). -- `extraArgs` thêm các cờ khởi chạy bổ sung vào quá trình khởi động Chromium cục bộ (ví dụ - `--disable-gpu`, kích thước cửa sổ, hoặc cờ gỡ lỗi). +- `extraArgs` thêm các cờ khởi chạy bổ sung vào lúc khởi động Chromium cục bộ (ví dụ `--disable-gpu`, kích thước cửa sổ hoặc cờ gỡ lỗi). --- @@ -346,8 +333,8 @@ Xem [Cam kết suy luận](/vi/concepts/commitments). } ``` -- `seamColor`: màu nhấn cho chrome UI ứng dụng gốc (sắc màu bong bóng Talk Mode, v.v.). -- `assistant`: ghi đè danh tính Control UI. Dùng danh tính agent đang hoạt động làm dự phòng. +- `seamColor`: màu nhấn cho khung UI ứng dụng gốc (sắc màu bong bóng Talk Mode, v.v.). +- `assistant`: ghi đè danh tính Control UI. Dự phòng về danh tính tác nhân đang hoạt động. --- @@ -426,71 +413,70 @@ Xem [Cam kết suy luận](/vi/concepts/commitments). - `mode`: `local` (chạy gateway) hoặc `remote` (kết nối tới gateway từ xa). Gateway từ chối khởi động trừ khi là `local`. -- `port`: một cổng ghép kênh duy nhất cho WS + HTTP. Thứ tự ưu tiên: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `port`: cổng ghép kênh duy nhất cho WS + HTTP. Thứ tự ưu tiên: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (mặc định), `lan` (`0.0.0.0`), `tailnet` (chỉ IP Tailscale), hoặc `custom`. - **Bí danh bind cũ**: dùng các giá trị chế độ bind trong `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), không dùng bí danh host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Ghi chú Docker**: bind `loopback` mặc định lắng nghe trên `127.0.0.1` bên trong container. Với mạng Docker bridge (`-p 18789:18789`), lưu lượng đến trên `eth0`, nên gateway không truy cập được. Dùng `--network host`, hoặc đặt `bind: "lan"` (hoặc `bind: "custom"` với `customBindHost: "0.0.0.0"`) để lắng nghe trên tất cả giao diện mạng. -- **Xác thực**: được yêu cầu theo mặc định. Các bind không phải loopback yêu cầu xác thực gateway. Trên thực tế, điều đó nghĩa là một token/mật khẩu dùng chung hoặc reverse proxy nhận biết danh tính với `gateway.auth.mode: "trusted-proxy"`. Trình hướng dẫn onboarding tạo token theo mặc định. -- Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình (bao gồm SecretRefs), hãy đặt `gateway.auth.mode` rõ ràng thành `token` hoặc `password`. Luồng khởi động và cài đặt/sửa chữa dịch vụ sẽ thất bại khi cả hai đều được cấu hình mà mode chưa được đặt. -- `gateway.auth.mode: "none"`: chế độ không xác thực rõ ràng. Chỉ dùng cho thiết lập local loopback đáng tin cậy; chế độ này cố ý không được đưa ra trong lời nhắc onboarding. -- `gateway.auth.mode: "trusted-proxy"`: ủy quyền xác thực trình duyệt/người dùng cho reverse proxy nhận biết danh tính và tin cậy các header danh tính từ `gateway.trustedProxies` (xem [Xác thực proxy đáng tin cậy](/vi/gateway/trusted-proxy-auth)). Chế độ này mặc định kỳ vọng nguồn proxy **không phải loopback**; reverse proxy loopback cùng host yêu cầu đặt rõ `gateway.auth.trustedProxy.allowLoopback = true`. Các caller nội bộ cùng host có thể dùng `gateway.auth.password` làm phương án dự phòng trực tiếp cục bộ; `gateway.auth.token` vẫn loại trừ lẫn nhau với chế độ trusted-proxy. -- `gateway.auth.allowTailscale`: khi là `true`, header danh tính Tailscale Serve có thể đáp ứng xác thực Control UI/WebSocket (được xác minh qua `tailscale whois`). Các điểm cuối HTTP API **không** dùng xác thực header Tailscale đó; thay vào đó chúng tuân theo chế độ xác thực HTTP bình thường của gateway. Luồng không cần token này giả định host gateway là đáng tin cậy. Mặc định là `true` khi `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: bộ giới hạn xác thực thất bại tùy chọn. Áp dụng theo từng IP máy khách và từng phạm vi xác thực (shared-secret và device-token được theo dõi độc lập). Các lần thử bị chặn trả về `429` + `Retry-After`. - - Trên đường dẫn Control UI Tailscale Serve bất đồng bộ, các lần thử thất bại cho cùng `{scope, clientIp}` được tuần tự hóa trước khi ghi lỗi. Vì vậy, các lần thử sai đồng thời từ cùng một máy khách có thể kích hoạt bộ giới hạn ở yêu cầu thứ hai thay vì cả hai cùng chạy qua như các lần không khớp thông thường. - - `gateway.auth.rateLimit.exemptLoopback` mặc định là `true`; đặt `false` khi bạn cố ý muốn lưu lượng localhost cũng bị giới hạn tốc độ (cho thiết lập kiểm thử hoặc triển khai proxy nghiêm ngặt). -- Các lần thử xác thực WS có nguồn gốc từ trình duyệt luôn bị điều tiết với miễn trừ loopback bị tắt (phòng thủ nhiều lớp chống brute force localhost dựa trên trình duyệt). -- Trên loopback, các khóa do nguồn gốc trình duyệt đó được cô lập theo từng giá trị `Origin` - đã chuẩn hóa, nên các lỗi lặp lại từ một origin localhost sẽ không tự động +- **Ghi chú Docker**: bind `loopback` mặc định lắng nghe trên `127.0.0.1` bên trong container. Với mạng Docker bridge (`-p 18789:18789`), lưu lượng đến trên `eth0`, nên gateway không thể truy cập được. Dùng `--network host`, hoặc đặt `bind: "lan"` (hoặc `bind: "custom"` với `customBindHost: "0.0.0.0"`) để lắng nghe trên tất cả giao diện mạng. +- **Auth**: bắt buộc theo mặc định. Các bind không phải loopback yêu cầu xác thực gateway. Trong thực tế, điều đó nghĩa là token/mật khẩu dùng chung hoặc reverse proxy có nhận biết danh tính với `gateway.auth.mode: "trusted-proxy"`. Trình hướng dẫn onboarding tạo token theo mặc định. +- Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình (bao gồm SecretRefs), hãy đặt `gateway.auth.mode` rõ ràng thành `token` hoặc `password`. Các luồng khởi động và cài đặt/sửa chữa dịch vụ sẽ thất bại khi cả hai đều được cấu hình và mode chưa được đặt. +- `gateway.auth.mode: "none"`: chế độ không xác thực rõ ràng. Chỉ dùng cho các thiết lập local loopback đáng tin cậy; chế độ này cố ý không được cung cấp trong các lời nhắc onboarding. +- `gateway.auth.mode: "trusted-proxy"`: ủy quyền xác thực trình duyệt/người dùng cho một reverse proxy có nhận biết danh tính và tin cậy các header danh tính từ `gateway.trustedProxies` (xem [Trusted Proxy Auth](/vi/gateway/trusted-proxy-auth)). Chế độ này mặc định kỳ vọng nguồn proxy **không phải loopback**; reverse proxy loopback cùng host yêu cầu đặt rõ `gateway.auth.trustedProxy.allowLoopback = true`. Các caller nội bộ cùng host có thể dùng `gateway.auth.password` làm fallback trực tiếp cục bộ; `gateway.auth.token` vẫn loại trừ lẫn nhau với chế độ trusted-proxy. +- `gateway.auth.allowTailscale`: khi là `true`, các header danh tính Tailscale Serve có thể đáp ứng auth Control UI/WebSocket (được xác minh qua `tailscale whois`). Các điểm cuối HTTP API **không** dùng auth header Tailscale đó; thay vào đó chúng tuân theo chế độ auth HTTP bình thường của gateway. Luồng không token này giả định host gateway là đáng tin cậy. Mặc định là `true` khi `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: bộ giới hạn xác thực thất bại tùy chọn. Áp dụng theo từng IP client và từng phạm vi auth (shared-secret và device-token được theo dõi độc lập). Các lần thử bị chặn trả về `429` + `Retry-After`. + - Trên đường dẫn Control UI Tailscale Serve bất đồng bộ, các lần thử thất bại cho cùng `{scope, clientIp}` được tuần tự hóa trước khi ghi lỗi. Vì vậy, các lần thử sai đồng thời từ cùng client có thể kích hoạt bộ giới hạn ở yêu cầu thứ hai thay vì cả hai cùng chạy qua như các lần không khớp thông thường. + - `gateway.auth.rateLimit.exemptLoopback` mặc định là `true`; đặt `false` khi bạn cố ý muốn lưu lượng localhost cũng bị giới hạn tần suất (cho thiết lập kiểm thử hoặc triển khai proxy nghiêm ngặt). +- Các lần thử auth WS có nguồn gốc từ trình duyệt luôn bị điều tiết với miễn trừ loopback bị tắt (phòng thủ nhiều lớp chống brute force localhost dựa trên trình duyệt). +- Trên loopback, các khóa tạm thời có nguồn gốc từ trình duyệt đó được cô lập theo từng giá trị `Origin` + đã chuẩn hóa, nên các lỗi lặp lại từ một origin localhost không tự động khóa một origin khác. -- `tailscale.mode`: `serve` (chỉ tailnet, bind loopback) hoặc `funnel` (công khai, yêu cầu xác thực). -- `controlUi.allowedOrigins`: danh sách cho phép origin trình duyệt rõ ràng cho kết nối Gateway WebSocket. Bắt buộc khi dự kiến có máy khách trình duyệt từ các origin không phải loopback. -- `controlUi.chatMessageMaxWidth`: max-width tùy chọn cho các tin nhắn trò chuyện Control UI được nhóm. Chấp nhận các giá trị chiều rộng CSS có ràng buộc như `960px`, `82%`, `min(1280px, 82%)`, và `calc(100% - 2rem)`. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: chế độ nguy hiểm bật phương án dự phòng origin từ header Host cho các triển khai cố ý dựa vào chính sách origin theo header Host. +- `tailscale.mode`: `serve` (chỉ tailnet, bind loopback) hoặc `funnel` (công khai, yêu cầu auth). +- `controlUi.allowedOrigins`: danh sách cho phép rõ ràng các browser-origin cho kết nối WebSocket Gateway. Bắt buộc khi kỳ vọng client trình duyệt đến từ origin không phải loopback. +- `controlUi.chatMessageMaxWidth`: max-width tùy chọn cho các tin nhắn chat Control UI được gom nhóm. Chấp nhận các giá trị chiều rộng CSS có ràng buộc như `960px`, `82%`, `min(1280px, 82%)`, và `calc(100% - 2rem)`. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: chế độ nguy hiểm bật fallback origin theo header Host cho các triển khai cố ý dựa vào chính sách origin theo header Host. - `remote.transport`: `ssh` (mặc định) hoặc `direct` (ws/wss). Với `direct`, `remote.url` phải là `ws://` hoặc `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override khẩn cấp bằng biến môi trường tiến trình phía máy khách - cho phép `ws://` dạng plaintext tới các IP mạng riêng đáng tin cậy; mặc định vẫn chỉ cho phép plaintext trên loopback. Không có cấu hình tương đương trong `openclaw.json`, - và cấu hình mạng riêng của trình duyệt như - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` không ảnh hưởng tới máy khách - Gateway WebSocket. -- `gateway.remote.token` / `.password` là các trường thông tin xác thực máy khách từ xa. Tự bản thân chúng không cấu hình xác thực gateway. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS cơ sở cho relay APNs bên ngoài được các bản dựng iOS chính thức/TestFlight dùng sau khi chúng công bố đăng ký dựa trên relay tới gateway. URL này phải khớp với URL relay được biên dịch vào bản dựng iOS. -- `gateway.push.apns.relay.timeoutMs`: thời gian chờ gửi từ gateway tới relay tính bằng mili giây. Mặc định là `10000`. -- Các đăng ký dựa trên relay được ủy quyền cho một danh tính gateway cụ thể. Ứng dụng iOS đã ghép đôi lấy `gateway.identity.get`, đưa danh tính đó vào đăng ký relay, và chuyển tiếp quyền gửi có phạm vi theo đăng ký tới gateway. Gateway khác không thể tái sử dụng đăng ký đã lưu đó. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env tạm thời cho cấu hình relay ở trên. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: lối thoát chỉ dành cho phát triển cho URL relay HTTP loopback. URL relay production nên tiếp tục dùng HTTPS. -- `gateway.handshakeTimeoutMs`: thời gian chờ bắt tay Gateway WebSocket trước xác thực tính bằng mili giây. Mặc định: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` có ưu tiên khi được đặt. Tăng giá trị này trên các host tải cao hoặc công suất thấp, nơi máy khách cục bộ có thể kết nối trong khi quá trình làm nóng khởi động vẫn đang ổn định. -- `gateway.channelHealthCheckMinutes`: khoảng thời gian health-monitor kênh tính bằng phút. Đặt `0` để tắt khởi động lại bằng health-monitor trên toàn cục. Mặc định: `5`. -- `gateway.channelStaleEventThresholdMinutes`: ngưỡng socket cũ tính bằng phút. Giữ giá trị này lớn hơn hoặc bằng `gateway.channelHealthCheckMinutes`. Mặc định: `30`. -- `gateway.channelMaxRestartsPerHour`: số lần khởi động lại tối đa bởi health-monitor cho mỗi kênh/tài khoản trong một giờ trượt. Mặc định: `10`. -- `channels..healthMonitor.enabled`: tùy chọn tắt khởi động lại bằng health-monitor theo từng kênh trong khi vẫn giữ monitor toàn cục bật. -- `channels..accounts..healthMonitor.enabled`: override theo từng tài khoản cho các kênh nhiều tài khoản. Khi được đặt, nó có ưu tiên hơn override cấp kênh. -- Các đường dẫn gọi gateway cục bộ chỉ có thể dùng `gateway.remote.*` làm phương án dự phòng khi `gateway.auth.*` chưa được đặt. -- Nếu `gateway.auth.token` / `gateway.auth.password` được cấu hình rõ ràng qua SecretRef và chưa được phân giải, quá trình phân giải sẽ fail-closed (không bị phương án dự phòng từ xa che lấp). -- `trustedProxies`: IP reverse proxy kết thúc TLS hoặc chèn header forwarded-client. Chỉ liệt kê các proxy bạn kiểm soát. Các mục loopback vẫn hợp lệ cho thiết lập proxy/phát hiện cục bộ cùng host (ví dụ Tailscale Serve hoặc reverse proxy cục bộ), nhưng chúng **không** làm cho yêu cầu loopback đủ điều kiện dùng `gateway.auth.mode: "trusted-proxy"`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: ghi đè break-glass phía client qua biến môi trường tiến trình + cho phép plaintext `ws://` tới các IP private-network đáng tin cậy; mặc định vẫn chỉ cho phép plaintext trên loopback. Không có cấu hình tương đương trong `openclaw.json`, + và cấu hình private-network của trình duyệt như + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` không ảnh hưởng đến các client WebSocket Gateway. +- `gateway.remote.token` / `.password` là các trường thông tin xác thực remote-client. Bản thân chúng không cấu hình auth gateway. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS cơ sở cho relay APNs bên ngoài được các bản dựng iOS chính thức/TestFlight sử dụng sau khi chúng phát hành các đăng ký có relay hậu thuẫn tới gateway. URL này phải khớp với URL relay được biên dịch vào bản dựng iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout gửi từ gateway tới relay tính bằng mili giây. Mặc định là `10000`. +- Các đăng ký có relay hậu thuẫn được ủy quyền cho một danh tính gateway cụ thể. Ứng dụng iOS đã ghép cặp gọi `gateway.identity.get`, đưa danh tính đó vào đăng ký relay, và chuyển tiếp một cấp quyền gửi theo phạm vi đăng ký tới gateway. Gateway khác không thể tái sử dụng đăng ký đã lưu đó. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: ghi đè env tạm thời cho cấu hình relay ở trên. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: cửa thoát chỉ dành cho phát triển cho các URL relay HTTP loopback. URL relay production nên giữ trên HTTPS. +- `gateway.handshakeTimeoutMs`: timeout bắt tay WebSocket Gateway trước auth tính bằng mili giây. Mặc định: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` được ưu tiên khi được đặt. Tăng giá trị này trên các host tải cao hoặc công suất thấp, nơi client cục bộ có thể kết nối trong khi warmup khởi động vẫn đang ổn định. +- `gateway.channelHealthCheckMinutes`: khoảng thời gian của bộ theo dõi sức khỏe kênh tính bằng phút. Đặt `0` để tắt toàn cục các lần khởi động lại do bộ theo dõi sức khỏe. Mặc định: `5`. +- `gateway.channelStaleEventThresholdMinutes`: ngưỡng stale-socket tính bằng phút. Giữ giá trị này lớn hơn hoặc bằng `gateway.channelHealthCheckMinutes`. Mặc định: `30`. +- `gateway.channelMaxRestartsPerHour`: số lần khởi động lại tối đa do bộ theo dõi sức khỏe cho mỗi kênh/tài khoản trong một giờ trượt. Mặc định: `10`. +- `channels..healthMonitor.enabled`: tắt riêng cho từng kênh đối với các lần khởi động lại do bộ theo dõi sức khỏe trong khi vẫn bật bộ theo dõi toàn cục. +- `channels..accounts..healthMonitor.enabled`: ghi đè theo từng tài khoản cho kênh nhiều tài khoản. Khi được đặt, nó được ưu tiên hơn ghi đè cấp kênh. +- Các đường dẫn gọi gateway cục bộ chỉ có thể dùng `gateway.remote.*` làm fallback khi `gateway.auth.*` chưa được đặt. +- Nếu `gateway.auth.token` / `gateway.auth.password` được cấu hình rõ ràng qua SecretRef và chưa được phân giải, quá trình phân giải sẽ thất bại đóng (không bị che bởi remote fallback). +- `trustedProxies`: các IP reverse proxy kết thúc TLS hoặc chèn header forwarded-client. Chỉ liệt kê các proxy bạn kiểm soát. Mục loopback vẫn hợp lệ cho thiết lập proxy/phát hiện cục bộ cùng host (ví dụ Tailscale Serve hoặc reverse proxy cục bộ), nhưng chúng **không** làm cho yêu cầu loopback đủ điều kiện cho `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: khi là `true`, gateway chấp nhận `X-Real-IP` nếu thiếu `X-Forwarded-For`. Mặc định là `false` để có hành vi fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs`: danh sách cho phép CIDR/IP tùy chọn để tự động phê duyệt ghép đôi thiết bị node lần đầu mà không có phạm vi được yêu cầu. Bị tắt khi chưa đặt. Thiết lập này không tự động phê duyệt ghép đôi operator/trình duyệt/Control UI/WebChat, và không tự động phê duyệt nâng cấp vai trò, phạm vi, metadata, hoặc khóa công khai. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: định hình cho phép/từ chối toàn cục cho các lệnh node đã khai báo sau khi ghép đôi và đánh giá danh sách cho phép nền tảng. Dùng `allowCommands` để chọn tham gia các lệnh node nguy hiểm như `camera.snap`, `camera.clip`, và `screen.record`; `denyCommands` loại bỏ một lệnh ngay cả khi mặc định nền tảng hoặc cho phép rõ ràng nếu không thì sẽ bao gồm lệnh đó. Sau khi một node thay đổi danh sách lệnh đã khai báo, hãy từ chối và phê duyệt lại ghép đôi thiết bị đó để gateway lưu snapshot lệnh đã cập nhật. -- `gateway.tools.deny`: tên công cụ bổ sung bị chặn cho HTTP `POST /tools/invoke` (mở rộng danh sách từ chối mặc định). -- `gateway.tools.allow`: loại bỏ tên công cụ khỏi danh sách từ chối HTTP mặc định. +- `gateway.nodes.pairing.autoApproveCidrs`: danh sách cho phép CIDR/IP tùy chọn để tự động phê duyệt ghép cặp thiết bị node lần đầu khi không có phạm vi được yêu cầu. Bị tắt khi chưa đặt. Điều này không tự động phê duyệt ghép cặp operator/trình duyệt/Control UI/WebChat, và không tự động phê duyệt nâng cấp vai trò, phạm vi, metadata hoặc public-key. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: định hình allow/deny toàn cục cho các lệnh node đã khai báo sau khi ghép cặp và đánh giá danh sách cho phép nền tảng. Dùng `allowCommands` để chọn tham gia các lệnh node nguy hiểm như `camera.snap`, `camera.clip`, và `screen.record`; `denyCommands` loại bỏ một lệnh ngay cả khi mặc định nền tảng hoặc allow rõ ràng lẽ ra sẽ bao gồm lệnh đó. Sau khi node thay đổi danh sách lệnh đã khai báo, hãy từ chối và phê duyệt lại ghép cặp thiết bị đó để gateway lưu snapshot lệnh đã cập nhật. +- `gateway.tools.deny`: tên công cụ bổ sung bị chặn cho HTTP `POST /tools/invoke` (mở rộng danh sách deny mặc định). +- `gateway.tools.allow`: loại bỏ tên công cụ khỏi danh sách deny HTTP mặc định. -### Điểm cuối tương thích với OpenAI +### Các điểm cuối tương thích với OpenAI -- Chat Completions: bị tắt theo mặc định. Bật bằng `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: tắt theo mặc định. Bật bằng `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Gia cố URL-input cho Responses: +- Gia cố đầu vào URL của Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Danh sách cho phép rỗng được coi như chưa đặt; dùng `gateway.http.endpoints.responses.files.allowUrl=false` + Danh sách cho phép rỗng được xem như chưa đặt; dùng `gateway.http.endpoints.responses.files.allowUrl=false` và/hoặc `gateway.http.endpoints.responses.images.allowUrl=false` để tắt tìm nạp URL. - Header gia cố phản hồi tùy chọn: - - `gateway.http.securityHeaders.strictTransportSecurity` (chỉ đặt cho các origin HTTPS bạn kiểm soát; xem [Xác thực proxy đáng tin cậy](/vi/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (chỉ đặt cho các origin HTTPS bạn kiểm soát; xem [Trusted Proxy Auth](/vi/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Cô lập nhiều phiên bản +### Cô lập nhiều instance -Chạy nhiều gateway trên một host với cổng và thư mục trạng thái riêng: +Chạy nhiều gateway trên một host với các cổng và thư mục trạng thái riêng: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -498,9 +484,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Cờ tiện ích: `--dev` (dùng `~/.openclaw-dev` + cổng `19001`), `--profile ` (dùng `~/.openclaw-`). +Các cờ tiện dụng: `--dev` (dùng `~/.openclaw-dev` + cổng `19001`), `--profile ` (dùng `~/.openclaw-`). -Xem [Nhiều Gateway](/vi/gateway/multiple-gateways). +Xem [Multiple Gateways](/vi/gateway/multiple-gateways). ### `gateway.tls` @@ -519,10 +505,10 @@ Xem [Nhiều Gateway](/vi/gateway/multiple-gateways). ``` - `enabled`: bật kết thúc TLS tại listener gateway (HTTPS/WSS) (mặc định: `false`). -- `autoGenerate`: tự động tạo cặp chứng chỉ/khóa tự ký cục bộ khi các tệp rõ ràng chưa được cấu hình; chỉ dùng cho local/dev. +- `autoGenerate`: tự động tạo cặp cert/key tự ký cục bộ khi không cấu hình tệp rõ ràng; chỉ dùng cho local/dev. - `certPath`: đường dẫn hệ thống tệp tới tệp chứng chỉ TLS. -- `keyPath`: đường dẫn hệ thống tệp tới tệp khóa riêng TLS; giữ hạn chế quyền truy cập. -- `caPath`: đường dẫn bundle CA tùy chọn để xác minh máy khách hoặc chuỗi tin cậy tùy chỉnh. +- `keyPath`: đường dẫn hệ thống tệp tới tệp khóa riêng TLS; giữ quyền truy cập bị hạn chế. +- `caPath`: đường dẫn gói CA tùy chọn cho xác minh client hoặc chuỗi tin cậy tùy chỉnh. ### `gateway.reload` @@ -538,17 +524,17 @@ Xem [Nhiều Gateway](/vi/gateway/multiple-gateways). } ``` -- `mode`: kiểm soát cách áp dụng chỉnh sửa cấu hình lúc runtime. +- `mode`: kiểm soát cách các chỉnh sửa cấu hình được áp dụng khi chạy. - `"off"`: bỏ qua chỉnh sửa trực tiếp; thay đổi yêu cầu khởi động lại rõ ràng. - `"restart"`: luôn khởi động lại tiến trình gateway khi cấu hình thay đổi. - `"hot"`: áp dụng thay đổi trong tiến trình mà không khởi động lại. - - `"hybrid"` (mặc định): thử hot reload trước; quay về khởi động lại nếu cần. -- `debounceMs`: cửa sổ debounce tính bằng ms trước khi áp dụng thay đổi cấu hình (số nguyên không âm). -- `deferralTimeoutMs`: thời gian tối đa tùy chọn tính bằng ms để chờ các thao tác đang diễn ra trước khi buộc khởi động lại. Bỏ qua để dùng thời gian chờ có giới hạn mặc định (`300000`); đặt `0` để chờ vô thời hạn và ghi log cảnh báo vẫn còn chờ theo chu kỳ. + - `"hybrid"` (mặc định): thử hot reload trước; fallback sang khởi động lại nếu cần. +- `debounceMs`: cửa sổ debounce tính bằng ms trước khi thay đổi cấu hình được áp dụng (số nguyên không âm). +- `deferralTimeoutMs`: thời gian tối đa tùy chọn tính bằng ms để chờ các thao tác đang chạy trước khi buộc khởi động lại. Bỏ qua để dùng thời gian chờ có giới hạn mặc định (`300000`); đặt `0` để chờ vô thời hạn và ghi log các cảnh báo vẫn đang chờ theo chu kỳ. --- -## Hook +## Hooks ```json5 { @@ -582,47 +568,47 @@ Xem [Nhiều Gateway](/vi/gateway/multiple-gateways). ``` Xác thực: `Authorization: Bearer ` hoặc `x-openclaw-token: `. -Token hook trong chuỗi truy vấn bị từ chối. +Token hook trong chuỗi truy vấn sẽ bị từ chối. Ghi chú về xác thực và an toàn: - `hooks.enabled=true` yêu cầu `hooks.token` không rỗng. - `hooks.token` phải **khác** với `gateway.auth.token`; việc dùng lại token Gateway sẽ bị từ chối. -- `hooks.path` không thể là `/`; hãy dùng một đường dẫn con chuyên dụng như `/hooks`. +- `hooks.path` không được là `/`; hãy dùng một đường dẫn con chuyên dụng như `/hooks`. - Nếu `hooks.allowRequestSessionKey=true`, hãy giới hạn `hooks.allowedSessionKeyPrefixes` (ví dụ `["hook:"]`). -- Nếu một mapping hoặc preset dùng `sessionKey` theo mẫu, hãy đặt `hooks.allowedSessionKeyPrefixes` và `hooks.allowRequestSessionKey=true`. Các khóa mapping tĩnh không yêu cầu tùy chọn tham gia đó. +- Nếu một ánh xạ hoặc preset dùng `sessionKey` theo mẫu, hãy đặt `hooks.allowedSessionKeyPrefixes` và `hooks.allowRequestSessionKey=true`. Khóa ánh xạ tĩnh không yêu cầu bật tùy chọn đó. -**Các endpoint:** +**Điểm cuối:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` từ payload yêu cầu chỉ được chấp nhận khi `hooks.allowRequestSessionKey=true` (mặc định: `false`). - `POST /hooks/` → được phân giải qua `hooks.mappings` - - Giá trị `sessionKey` của mapping được render từ mẫu được xem là do bên ngoài cung cấp và cũng yêu cầu `hooks.allowRequestSessionKey=true`. + - Các giá trị `sessionKey` của ánh xạ được render từ mẫu được xem là do bên ngoài cung cấp và cũng yêu cầu `hooks.allowRequestSessionKey=true`. - + - `match.path` khớp với đường dẫn con sau `/hooks` (ví dụ `/hooks/gmail` → `gmail`). - `match.source` khớp với một trường payload cho các đường dẫn chung. - Các mẫu như `{{messages[0].subject}}` đọc từ payload. -- `transform` có thể trỏ đến một module JS/TS trả về một hành động hook. - - `transform.module` phải là đường dẫn tương đối và nằm trong `hooks.transformsDir` (đường dẫn tuyệt đối và traversal bị từ chối). - - Giữ `hooks.transformsDir` trong `~/.openclaw/hooks/transforms`; các thư mục workspace skill bị từ chối. Nếu `openclaw doctor` báo đường dẫn này không hợp lệ, hãy chuyển module transform vào thư mục hooks transforms hoặc xóa `hooks.transformsDir`. -- `agentId` định tuyến đến một agent cụ thể; ID không xác định sẽ quay về mặc định. +- `transform` có thể trỏ tới một mô-đun JS/TS trả về một hành động hook. + - `transform.module` phải là đường dẫn tương đối và nằm trong `hooks.transformsDir` (đường dẫn tuyệt đối và duyệt ngược thư mục sẽ bị từ chối). + - Giữ `hooks.transformsDir` trong `~/.openclaw/hooks/transforms`; thư mục Skills trong workspace sẽ bị từ chối. Nếu `openclaw doctor` báo đường dẫn này không hợp lệ, hãy chuyển mô-đun transform vào thư mục transforms của hooks hoặc xóa `hooks.transformsDir`. +- `agentId` định tuyến tới một agent cụ thể; ID không xác định sẽ quay về mặc định. - `allowedAgentIds`: giới hạn định tuyến tường minh (`*` hoặc bỏ qua = cho phép tất cả, `[]` = từ chối tất cả). -- `defaultSessionKey`: khóa phiên cố định tùy chọn cho các lần chạy hook agent không có `sessionKey` tường minh. -- `allowRequestSessionKey`: cho phép caller của `/hooks/agent` và khóa phiên mapping dựa trên mẫu đặt `sessionKey` (mặc định: `false`). -- `allowedSessionKeyPrefixes`: danh sách cho phép tiền tố tùy chọn cho các giá trị `sessionKey` tường minh (yêu cầu + mapping), ví dụ `["hook:"]`. Nó trở thành bắt buộc khi bất kỳ mapping hoặc preset nào dùng `sessionKey` theo mẫu. -- `deliver: true` gửi phản hồi cuối cùng đến một kênh; `channel` mặc định là `last`. -- `model` ghi đè LLM cho lần chạy hook này (phải được cho phép nếu danh mục model được đặt). +- `defaultSessionKey`: khóa phiên cố định tùy chọn cho các lần chạy agent hook không có `sessionKey` tường minh. +- `allowRequestSessionKey`: cho phép bên gọi `/hooks/agent` và khóa phiên ánh xạ dựa trên mẫu đặt `sessionKey` (mặc định: `false`). +- `allowedSessionKeyPrefixes`: danh sách cho phép tiền tố tùy chọn cho các giá trị `sessionKey` tường minh (yêu cầu + ánh xạ), ví dụ `["hook:"]`. Nó trở thành bắt buộc khi bất kỳ ánh xạ hoặc preset nào dùng `sessionKey` theo mẫu. +- `deliver: true` gửi phản hồi cuối cùng tới một kênh; `channel` mặc định là `last`. +- `model` ghi đè LLM cho lần chạy hook này (phải được cho phép nếu catalog mô hình được đặt). ### Tích hợp Gmail - Preset Gmail tích hợp sẵn dùng `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Nếu giữ định tuyến theo từng tin nhắn đó, hãy đặt `hooks.allowRequestSessionKey: true` và giới hạn `hooks.allowedSessionKeyPrefixes` để khớp với namespace Gmail, ví dụ `["hook:", "hook:gmail:"]`. -- Nếu cần `hooks.allowRequestSessionKey: false`, hãy ghi đè preset bằng một `sessionKey` tĩnh thay vì mặc định theo mẫu. +- Nếu bạn giữ định tuyến theo từng tin nhắn đó, hãy đặt `hooks.allowRequestSessionKey: true` và giới hạn `hooks.allowedSessionKeyPrefixes` để khớp với không gian tên Gmail, ví dụ `["hook:", "hook:gmail:"]`. +- Nếu bạn cần `hooks.allowRequestSessionKey: false`, hãy ghi đè preset bằng một `sessionKey` tĩnh thay vì mặc định theo mẫu. ```json5 { @@ -645,8 +631,8 @@ Ghi chú về xác thực và an toàn: } ``` -- Gateway tự động khởi động `gog gmail watch serve` khi boot nếu được cấu hình. Đặt `OPENCLAW_SKIP_GMAIL_WATCHER=1` để tắt. -- Đừng chạy riêng một `gog gmail watch serve` song song với Gateway. +- Gateway tự động khởi động `gog gmail watch serve` khi khởi động nếu đã được cấu hình. Đặt `OPENCLAW_SKIP_GMAIL_WATCHER=1` để tắt. +- Đừng chạy một `gog gmail watch serve` riêng song song với Gateway. --- @@ -662,18 +648,18 @@ Ghi chú về xác thực và an toàn: } ``` -- Phục vụ HTML/CSS/JS mà agent có thể chỉnh sửa và A2UI qua HTTP dưới cổng Gateway: +- Phục vụ HTML/CSS/JS có thể chỉnh sửa bởi agent và A2UI qua HTTP dưới cổng Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Chỉ cục bộ: giữ `gateway.bind: "loopback"` (mặc định). -- Bind không phải loopback: các route canvas yêu cầu xác thực Gateway (token/mật khẩu/trusted-proxy), giống như các bề mặt HTTP Gateway khác. -- Node WebView thường không gửi header xác thực; sau khi một Node được ghép đôi và kết nối, Gateway quảng bá các URL capability theo phạm vi Node để truy cập canvas/A2UI. -- URL capability được ràng buộc với phiên WS Node đang hoạt động và hết hạn nhanh. Fallback dựa trên IP không được dùng. -- Chèn client live-reload vào HTML được phục vụ. +- Bind không phải loopback: các tuyến canvas yêu cầu xác thực Gateway (token/mật khẩu/proxy tin cậy), giống như các bề mặt HTTP Gateway khác. +- Node WebViews thường không gửi header xác thực; sau khi một node được ghép đôi và kết nối, Gateway quảng bá các URL năng lực theo phạm vi node để truy cập canvas/A2UI. +- URL năng lực được ràng buộc với phiên WS node đang hoạt động và hết hạn nhanh. Không dùng fallback dựa trên IP. +- Chèn client tải lại trực tiếp vào HTML được phục vụ. - Tự động tạo `index.html` khởi đầu khi trống. - Cũng phục vụ A2UI tại `/__openclaw__/a2ui/`. - Các thay đổi yêu cầu khởi động lại gateway. -- Tắt live reload cho thư mục lớn hoặc lỗi `EMFILE`. +- Tắt tải lại trực tiếp cho các thư mục lớn hoặc lỗi `EMFILE`. --- @@ -691,11 +677,11 @@ Ghi chú về xác thực và an toàn: } ``` -- `minimal` (mặc định khi Plugin `bonjour` được đóng gói kèm được bật): bỏ qua `cliPath` + `sshPort` khỏi bản ghi TXT. -- `full`: bao gồm `cliPath` + `sshPort`; quảng bá multicast LAN vẫn yêu cầu Plugin `bonjour` được đóng gói kèm được bật. -- `off`: tắt quảng bá multicast LAN mà không thay đổi việc bật Plugin. -- Plugin `bonjour` được đóng gói kèm tự động khởi động trên host macOS và là tùy chọn tham gia trên Linux, Windows, và các triển khai Gateway trong container. -- Tên host mặc định là tên host hệ thống khi đó là nhãn DNS hợp lệ, nếu không sẽ dùng `openclaw`. Ghi đè bằng `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (mặc định khi plugin `bonjour` đi kèm được bật): bỏ qua `cliPath` + `sshPort` khỏi bản ghi TXT. +- `full`: bao gồm `cliPath` + `sshPort`; quảng bá multicast LAN vẫn yêu cầu plugin `bonjour` đi kèm được bật. +- `off`: chặn quảng bá multicast LAN mà không thay đổi việc bật plugin. +- Plugin `bonjour` đi kèm tự động khởi động trên máy chủ macOS và là tùy chọn bật trên Linux, Windows và các triển khai Gateway trong container. +- Tên máy chủ mặc định là hostname hệ thống khi đó là một nhãn DNS hợp lệ, nếu không thì dùng `openclaw`. Ghi đè bằng `OPENCLAW_MDNS_HOSTNAME`. ### Diện rộng (DNS-SD) @@ -707,7 +693,7 @@ Ghi chú về xác thực và an toàn: } ``` -Ghi một zone DNS-SD unicast dưới `~/.openclaw/dns/`. Để khám phá xuyên mạng, ghép với máy chủ DNS (khuyến nghị CoreDNS) + Tailscale split DNS. +Ghi một vùng DNS-SD unicast dưới `~/.openclaw/dns/`. Để khám phá liên mạng, hãy kết hợp với một máy chủ DNS (khuyến nghị CoreDNS) + DNS phân tách Tailscale. Thiết lập: `openclaw dns setup --apply`. @@ -732,8 +718,8 @@ Thiết lập: `openclaw dns setup --apply`. } ``` -- Biến môi trường nội tuyến chỉ được áp dụng nếu biến môi trường của tiến trình đang thiếu khóa đó. -- Tệp `.env`: `.env` trong CWD + `~/.openclaw/.env` (không tệp nào ghi đè các biến hiện có). +- Biến môi trường nội tuyến chỉ được áp dụng nếu môi trường tiến trình thiếu khóa đó. +- Tệp `.env`: `.env` trong CWD + `~/.openclaw/.env` (không tệp nào ghi đè biến hiện có). - `shellEnv`: nhập các khóa dự kiến còn thiếu từ hồ sơ shell đăng nhập của bạn. - Xem [Môi trường](/vi/help/environment) để biết đầy đủ thứ tự ưu tiên. @@ -750,15 +736,15 @@ Tham chiếu biến môi trường trong bất kỳ chuỗi cấu hình nào b ``` - Chỉ khớp tên viết hoa: `[A-Z_][A-Z0-9_]*`. -- Biến thiếu/trống sẽ gây lỗi khi tải cấu hình. -- Thoát bằng `$${VAR}` để có giá trị chữ `${VAR}`. +- Biến bị thiếu/trống sẽ gây lỗi khi tải cấu hình. +- Thoát bằng `$${VAR}` để có `${VAR}` nguyên văn. - Hoạt động với `$include`. --- ## Bí mật -Tham chiếu bí mật có tính bổ sung: giá trị văn bản thuần vẫn hoạt động. +Tham chiếu bí mật có tính cộng thêm: giá trị văn bản thuần vẫn hoạt động. ### `SecretRef` @@ -771,18 +757,18 @@ Dùng một dạng đối tượng: Xác thực: - Mẫu `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- Mẫu id của `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- id của `source: "file"`: con trỏ JSON tuyệt đối (ví dụ `"/providers/openai/apiKey"`) -- Mẫu id của `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id của `source: "exec"` không được chứa các đoạn đường dẫn phân tách bằng dấu gạch chéo là `.` hoặc `..` (ví dụ `a/../b` bị từ chối) +- Mẫu id `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- id `source: "file"`: con trỏ JSON tuyệt đối (ví dụ `"/providers/openai/apiKey"`) +- Mẫu id `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- id `source: "exec"` không được chứa các đoạn đường dẫn được phân tách bằng dấu gạch chéo là `.` hoặc `..` (ví dụ `a/../b` bị từ chối) ### Bề mặt thông tin xác thực được hỗ trợ - Ma trận chuẩn: [Bề mặt thông tin xác thực SecretRef](/vi/reference/secretref-credential-surface) -- `secrets apply` nhắm đến các đường dẫn thông tin xác thực `openclaw.json` được hỗ trợ. -- Tham chiếu `auth-profiles.json` được đưa vào phạm vi phân giải khi chạy và phạm vi kiểm toán. +- Mục tiêu `secrets apply` hỗ trợ các đường dẫn thông tin xác thực `openclaw.json`. +- Tham chiếu `auth-profiles.json` được bao gồm trong phân giải runtime và phạm vi kiểm toán. -### Cấu hình trình cung cấp bí mật +### Cấu hình nhà cung cấp bí mật ```json5 { @@ -812,14 +798,14 @@ Xác thực: Ghi chú: -- Trình cung cấp `file` hỗ trợ `mode: "json"` và `mode: "singleValue"` (`id` phải là `"value"` trong chế độ singleValue). -- Đường dẫn của trình cung cấp tệp và exec sẽ đóng an toàn khi không thể xác minh ACL của Windows. Chỉ đặt `allowInsecurePath: true` cho các đường dẫn đáng tin cậy nhưng không thể xác minh. -- Trình cung cấp `exec` yêu cầu đường dẫn `command` tuyệt đối và dùng payload giao thức trên stdin/stdout. +- Nhà cung cấp `file` hỗ trợ `mode: "json"` và `mode: "singleValue"` (`id` phải là `"value"` trong chế độ singleValue). +- Đường dẫn nhà cung cấp file và exec sẽ đóng an toàn khi không thể xác minh ACL Windows. Chỉ đặt `allowInsecurePath: true` cho các đường dẫn đáng tin cậy nhưng không thể xác minh. +- Nhà cung cấp `exec` yêu cầu đường dẫn `command` tuyệt đối và dùng payload giao thức trên stdin/stdout. - Theo mặc định, đường dẫn lệnh symlink bị từ chối. Đặt `allowSymlinkCommand: true` để cho phép đường dẫn symlink trong khi vẫn xác thực đường dẫn đích đã phân giải. -- Nếu `trustedDirs` được cấu hình, kiểm tra thư mục tin cậy áp dụng cho đường dẫn đích đã phân giải. -- Môi trường tiến trình con `exec` mặc định là tối thiểu; truyền rõ các biến bắt buộc bằng `passEnv`. -- Tham chiếu bí mật được phân giải tại thời điểm kích hoạt thành một ảnh chụp trong bộ nhớ, sau đó các đường dẫn yêu cầu chỉ đọc ảnh chụp đó. -- Lọc bề mặt hoạt động áp dụng trong quá trình kích hoạt: tham chiếu chưa phân giải trên các bề mặt đã bật làm quá trình khởi động/tải lại thất bại, còn các bề mặt không hoạt động được bỏ qua kèm chẩn đoán. +- Nếu `trustedDirs` được cấu hình, kiểm tra thư mục tin cậy sẽ áp dụng cho đường dẫn đích đã phân giải. +- Môi trường tiến trình con của `exec` mặc định là tối thiểu; truyền rõ ràng các biến bắt buộc bằng `passEnv`. +- Tham chiếu bí mật được phân giải tại thời điểm kích hoạt thành một snapshot trong bộ nhớ, sau đó các đường dẫn yêu cầu chỉ đọc snapshot đó. +- Lọc bề mặt đang hoạt động áp dụng trong khi kích hoạt: tham chiếu chưa phân giải trên các bề mặt đã bật sẽ làm khởi động/tải lại thất bại, còn bề mặt không hoạt động được bỏ qua kèm chẩn đoán. --- @@ -841,14 +827,14 @@ Ghi chú: } ``` -- Hồ sơ theo từng tác nhân được lưu tại `/auth-profiles.json`. -- `auth-profiles.json` hỗ trợ tham chiếu cấp giá trị (`keyRef` cho `api_key`, `tokenRef` cho `token`) đối với các chế độ thông tin xác thực tĩnh. -- Các ánh xạ phẳng `auth-profiles.json` kế thừa như `{ "provider": { "apiKey": "..." } }` không phải là định dạng khi chạy; `openclaw doctor --fix` ghi lại chúng thành các hồ sơ khóa API `provider:default` chuẩn với bản sao lưu `.legacy-flat.*.bak`. +- Hồ sơ theo agent được lưu tại `/auth-profiles.json`. +- `auth-profiles.json` hỗ trợ tham chiếu cấp giá trị (`keyRef` cho `api_key`, `tokenRef` cho `token`) cho các chế độ thông tin xác thực tĩnh. +- Ánh xạ `auth-profiles.json` phẳng kiểu cũ như `{ "provider": { "apiKey": "..." } }` không phải là định dạng runtime; `openclaw doctor --fix` ghi lại chúng thành hồ sơ khóa API `provider:default` chuẩn với bản sao lưu `.legacy-flat.*.bak`. - Hồ sơ chế độ OAuth (`auth.profiles..mode = "oauth"`) không hỗ trợ thông tin xác thực hồ sơ xác thực dựa trên SecretRef. -- Thông tin xác thực tĩnh khi chạy đến từ các ảnh chụp đã phân giải trong bộ nhớ; các mục `auth.json` tĩnh kế thừa sẽ bị xóa sạch khi được phát hiện. -- Nhập OAuth kế thừa từ `~/.openclaw/credentials/oauth.json`. +- Thông tin xác thực runtime tĩnh đến từ các snapshot đã phân giải trong bộ nhớ; mục `auth.json` tĩnh kiểu cũ sẽ được làm sạch khi phát hiện. +- Nhập OAuth kiểu cũ từ `~/.openclaw/credentials/oauth.json`. - Xem [OAuth](/vi/concepts/oauth). -- Hành vi khi chạy của bí mật và công cụ `audit/configure/apply`: [Quản lý bí mật](/vi/gateway/secrets). +- Hành vi runtime của bí mật và công cụ `audit/configure/apply`: [Quản lý bí mật](/vi/gateway/secrets). ### `auth.cooldowns` @@ -870,15 +856,15 @@ Ghi chú: } ``` -- `billingBackoffHours`: thời gian chờ lùi cơ sở tính bằng giờ khi một hồ sơ thất bại do lỗi lập hóa đơn/hết tín dụng thực sự (mặc định: `5`). Văn bản lập hóa đơn rõ ràng vẫn có thể vào đây ngay cả trên phản hồi `401`/`403`, nhưng các bộ khớp văn bản dành riêng cho nhà cung cấp vẫn được giới hạn trong nhà cung cấp sở hữu chúng (ví dụ OpenRouter `Key limit exceeded`). Các thông báo HTTP `402` có thể thử lại về khung thời gian sử dụng hoặc giới hạn chi tiêu của tổ chức/workspace vẫn đi theo đường dẫn `rate_limit`. -- `billingBackoffHoursByProvider`: các ghi đè tùy chọn theo từng nhà cung cấp cho số giờ chờ lùi lập hóa đơn. -- `billingMaxHours`: giới hạn tính bằng giờ cho tăng trưởng hàm mũ của chờ lùi lập hóa đơn (mặc định: `24`). -- `authPermanentBackoffMinutes`: thời gian chờ lùi cơ sở tính bằng phút cho các lỗi `auth_permanent` có độ tin cậy cao (mặc định: `10`). -- `authPermanentMaxMinutes`: giới hạn tính bằng phút cho tăng trưởng chờ lùi `auth_permanent` (mặc định: `60`). -- `failureWindowHours`: cửa sổ cuốn tính bằng giờ dùng cho bộ đếm chờ lùi (mặc định: `24`). -- `overloadedProfileRotations`: số lần xoay vòng hồ sơ xác thực tối đa trong cùng nhà cung cấp đối với lỗi quá tải trước khi chuyển sang dự phòng mô hình (mặc định: `1`). Các dạng nhà cung cấp bận như `ModelNotReadyException` đi vào đây. -- `overloadedBackoffMs`: độ trễ cố định trước khi thử lại một lần xoay vòng nhà cung cấp/hồ sơ quá tải (mặc định: `0`). -- `rateLimitedProfileRotations`: số lần xoay vòng hồ sơ xác thực tối đa trong cùng nhà cung cấp đối với lỗi giới hạn tốc độ trước khi chuyển sang dự phòng mô hình (mặc định: `1`). Nhóm giới hạn tốc độ đó bao gồm văn bản theo dạng nhà cung cấp như `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` và `resource exhausted`. +- `billingBackoffHours`: thời gian backoff cơ sở tính bằng giờ khi một hồ sơ thất bại do lỗi billing/thiếu tín dụng thật sự (mặc định: `5`). Văn bản billing rõ ràng vẫn có thể đi vào đây ngay cả trên phản hồi `401`/`403`, nhưng các bộ khớp văn bản riêng theo 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`). Các thông báo HTTP `402` có thể thử lại về cửa sổ sử dụng hoặc giới hạn chi tiêu của tổ chức/workspace vẫn đi theo đường dẫn `rate_limit`. +- `billingBackoffHoursByProvider`: các ghi đè tùy chọn theo từng nhà cung cấp cho số giờ backoff billing. +- `billingMaxHours`: giới hạn tính bằng giờ cho mức tăng theo hàm mũ của backoff billing (mặc định: `24`). +- `authPermanentBackoffMinutes`: backoff cơ sở tính bằng phút cho các lỗi `auth_permanent` có độ tin cậy cao (mặc định: `10`). +- `authPermanentMaxMinutes`: giới hạn tính bằng phút cho mức tăng backoff `auth_permanent` (mặc định: `60`). +- `failureWindowHours`: cửa sổ trượt tính bằng giờ dùng cho bộ đếm backoff (mặc định: `24`). +- `overloadedProfileRotations`: số lần xoay vòng hồ sơ xác thực cùng nhà cung cấp tối đa cho lỗi quá tải trước khi chuyển sang fallback mô hình (mặc định: `1`). Các dạng nhà cung cấp bận như `ModelNotReadyException` đi vào đây. +- `overloadedBackoffMs`: độ trễ cố định trước khi thử lại xoay vòng nhà cung cấp/hồ sơ bị quá tải (mặc định: `0`). +- `rateLimitedProfileRotations`: số lần xoay vòng hồ sơ xác thực cùng nhà cung cấp tối đa cho lỗi giới hạn tốc độ trước khi chuyển sang fallback mô hình (mặc định: `1`). Nhóm giới hạn tốc độ đó bao gồm văn bản theo dạng nhà cung cấp như `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, và `resource exhausted`. --- @@ -898,10 +884,10 @@ Ghi chú: ``` - Tệp nhật ký mặc định: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Đặt `logging.file` để có đường dẫn ổn định. -- `consoleLevel` tăng lên `debug` khi có `--verbose`. -- `maxFileBytes`: kích thước tệp nhật ký đang hoạt động tối đa tính bằng byte trước khi xoay vòng (số nguyên dương; mặc định: `104857600` = 100 MB). OpenClaw giữ tối đa năm bản lưu trữ được đánh số bên cạnh tệp đang hoạt động. -- `redactSensitive` / `redactPatterns`: che giấu theo nỗ lực tối đa cho đầu ra console, nhật ký tệp, bản ghi nhật ký OTLP và văn bản bản ghi phiên được lưu giữ. `redactSensitive: "off"` chỉ tắt chính sách nhật ký/bản ghi chung này; các bề mặt an toàn UI/công cụ/chẩn đoán vẫn biên tập bí mật trước khi phát ra. +- Đặt `logging.file` cho một đường dẫn ổn định. +- `consoleLevel` tăng lên `debug` khi dùng `--verbose`. +- `maxFileBytes`: kích thước tối đa của tệp nhật ký đang hoạt động tính bằng byte trước khi xoay vòng (số nguyên dương; mặc định: `104857600` = 100 MB). OpenClaw giữ tối đa năm bản lưu trữ được đánh số bên cạnh tệp đang hoạt động. +- `redactSensitive` / `redactPatterns`: che giấu theo best-effort cho đầu ra console, nhật ký tệp, bản ghi nhật ký OTLP, và văn bản bản ghi phiên được lưu trữ. `redactSensitive: "off"` chỉ tắt chính sách nhật ký/bản ghi chung này; các bề mặt an toàn UI/công cụ/chẩn đoán vẫn biên tập bí mật trước khi phát ra. --- @@ -949,25 +935,25 @@ Ghi chú: } ``` -- `enabled`: công tắc chính cho đầu ra đo đạc (mặc định: `true`). -- `flags`: mảng chuỗi cờ bật đầu ra nhật ký có mục tiêu (hỗ trợ ký tự đại diện như `"telegram.*"` hoặc `"*"`). -- `stuckSessionWarnMs`: ngưỡng tuổi không có tiến triển tính bằng ms để phân loại các phiên xử lý chạy lâu là `session.long_running`, `session.stalled` hoặc `session.stuck`. Phản hồi, công cụ, trạng thái, khối và tiến trình ACP đặt lại bộ hẹn giờ; các chẩn đoán `session.stuck` lặp lại sẽ lùi dần khi không thay đổi. -- `otel.enabled`: bật pipeline xuất OpenTelemetry (mặc định: `false`). Để xem cấu hình đầy đủ, danh mục tín hiệu và mô hình quyền riêng tư, xem [xuất OpenTelemetry](/vi/gateway/opentelemetry). +- `enabled`: công tắc chính cho đầu ra instrumentation (mặc định: `true`). +- `flags`: mảng chuỗi cờ bật đầu ra nhật ký có mục tiêu (hỗ trợ wildcard như `"telegram.*"` hoặc `"*"`). +- `stuckSessionWarnMs`: ngưỡng tuổi không có tiến triển tính bằng ms để phân loại các phiên xử lý chạy lâu là `session.long_running`, `session.stalled`, hoặc `session.stuck`. Phản hồi, công cụ, trạng thái, khối, và tiến trình ACP đặt lại bộ đếm thời gian; các chẩn đoán `session.stuck` lặp lại sẽ back off khi không thay đổi. +- `otel.enabled`: bật pipeline xuất OpenTelemetry (mặc định: `false`). Để xem cấu hình đầy đủ, danh mục tín hiệu, và mô hình quyền riêng tư, xem [xuất OpenTelemetry](/vi/gateway/opentelemetry). - `otel.endpoint`: URL collector cho xuất OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: các endpoint OTLP tùy chọn dành riêng cho tín hiệu. Khi được đặt, chúng ghi đè `otel.endpoint` chỉ cho tín hiệu đó. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: các endpoint OTLP tùy chọn riêng theo tín hiệu. Khi được đặt, chúng ghi đè `otel.endpoint` chỉ cho tín hiệu đó. - `otel.protocol`: `"http/protobuf"` (mặc định) hoặc `"grpc"`. -- `otel.headers`: các header metadata HTTP/gRPC bổ sung được gửi cùng yêu cầu xuất OTel. +- `otel.headers`: header metadata HTTP/gRPC bổ sung được gửi cùng các yêu cầu xuất OTel. - `otel.serviceName`: tên dịch vụ cho thuộc tính tài nguyên. -- `otel.traces` / `otel.metrics` / `otel.logs`: bật xuất trace, metric hoặc nhật ký. +- `otel.traces` / `otel.metrics` / `otel.logs`: bật xuất trace, metrics, hoặc log. - `otel.sampleRate`: tỷ lệ lấy mẫu trace `0`–`1`. -- `otel.flushIntervalMs`: khoảng thời gian xả telemetry định kỳ tính bằng ms. -- `otel.captureContent`: chọn tham gia thu thập nội dung thô cho thuộc tính span OTEL. Mặc định là tắt. Boolean `true` thu thập nội dung thông điệp/công cụ không thuộc hệ thống; dạng đối tượng cho phép bạn bật rõ ràng `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` và `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: công tắc môi trường cho các thuộc tính nhà cung cấp span GenAI thử nghiệm mới nhất. Theo mặc định, span giữ thuộc tính `gen_ai.system` cũ để tương thích; metric GenAI dùng các thuộc tính ngữ nghĩa có giới hạn. -- `OPENCLAW_OTEL_PRELOADED=1`: công tắc môi trường cho host đã đăng ký SDK OpenTelemetry toàn cục. Khi đó OpenClaw bỏ qua khởi động/tắt SDK do Plugin sở hữu trong khi vẫn giữ listener chẩn đoán hoạt động. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` và `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: biến môi trường endpoint dành riêng cho tín hiệu được dùng khi khóa cấu hình tương ứng chưa được đặt. -- `cacheTrace.enabled`: ghi nhật ký snapshot trace bộ nhớ đệm cho các lần chạy nhúng (mặc định: `false`). -- `cacheTrace.filePath`: đường dẫn đầu ra cho JSONL trace bộ nhớ đệm (mặc định: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: kiểm soát những gì được bao gồm trong đầu ra trace bộ nhớ đệm (tất cả mặc định: `true`). +- `otel.flushIntervalMs`: khoảng thời gian flush telemetry định kỳ tính bằng ms. +- `otel.captureContent`: chọn tham gia thu thập nội dung thô cho thuộc tính span OTEL. Mặc định là tắt. Boolean `true` thu thập nội dung tin nhắn/công cụ không thuộc hệ thống; dạng đối tượng cho phép bạn bật rõ ràng `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs`, và `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: công tắc môi trường cho các thuộc tính nhà cung cấp span GenAI thử nghiệm mới nhất. Theo mặc định, span giữ thuộc tính `gen_ai.system` cũ để tương thích; metrics GenAI dùng các thuộc tính ngữ nghĩa có giới hạn. +- `OPENCLAW_OTEL_PRELOADED=1`: công tắc môi trường cho host đã đăng ký sẵn một OpenTelemetry SDK toàn cục. Khi đó OpenClaw bỏ qua khởi động/tắt SDK thuộc sở hữu Plugin trong khi vẫn giữ các listener chẩn đoán hoạt động. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, và `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: biến môi trường endpoint riêng theo tín hiệu được dùng khi khóa cấu hình tương ứng chưa được đặt. +- `cacheTrace.enabled`: ghi nhật ký snapshot trace cache cho các lần chạy nhúng (mặc định: `false`). +- `cacheTrace.filePath`: đường dẫn đầu ra cho JSONL trace cache (mặc định: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: kiểm soát nội dung được đưa vào đầu ra trace cache (tất cả mặc định: `true`). --- @@ -989,11 +975,11 @@ Ghi chú: } ``` -- `channel`: kênh phát hành cho bản cài đặt npm/git — `"stable"`, `"beta"` hoặc `"dev"`. -- `checkOnStart`: kiểm tra cập nhật npm khi gateway khởi động (mặc định: `true`). -- `auto.enabled`: bật tự động cập nhật nền cho bản cài đặt gói (mặc định: `false`). +- `channel`: kênh phát hành cho bản cài đặt npm/git — `"stable"`, `"beta"`, hoặc `"dev"`. +- `checkOnStart`: kiểm tra bản cập nhật npm khi gateway khởi động (mặc định: `true`). +- `auto.enabled`: bật tự động cập nhật nền cho bản cài đặt package (mặc định: `false`). - `auto.stableDelayHours`: độ trễ tối thiểu tính bằng giờ trước khi tự động áp dụng kênh ổn định (mặc định: `6`; tối đa: `168`). -- `auto.stableJitterHours`: cửa sổ phân tán triển khai bổ sung cho kênh ổn định tính bằng giờ (mặc định: `12`; tối đa: `168`). +- `auto.stableJitterHours`: cửa sổ phân bổ rollout bổ sung cho kênh ổn định tính bằng giờ (mặc định: `12`; tối đa: `168`). - `auto.betaCheckIntervalHours`: tần suất chạy kiểm tra kênh beta tính bằng giờ (mặc định: `1`; tối đa: `24`). --- @@ -1027,23 +1013,23 @@ Ghi chú: } ``` -- `enabled`: cổng tính năng ACP toàn cục (mặc định: `true`; đặt `false` để ẩn điều phối ACP và các khả năng spawn). +- `enabled`: cổng tính năng ACP toàn cục (mặc định: `true`; đặt `false` để ẩn điều phối ACP và các affordance spawn). - `dispatch.enabled`: cổng độc lập cho điều phối lượt phiên ACP (mặc định: `true`). Đặt `false` để giữ lệnh ACP khả dụng trong khi chặn thực thi. - `backend`: id backend runtime ACP mặc định (phải khớp với một Plugin runtime ACP đã đăng ký). Cài đặt Plugin backend trước, và nếu `plugins.allow` được đặt, hãy bao gồm id Plugin backend (ví dụ `acpx`) nếu không backend ACP sẽ không tải. -- `defaultAgent`: id agent mục tiêu ACP dự phòng khi spawn không chỉ định mục tiêu rõ ràng. -- `allowedAgents`: danh sách cho phép các id agent được phép dùng cho phiên runtime ACP; rỗng nghĩa là không có hạn chế bổ sung. +- `defaultAgent`: id agent mục tiêu ACP fallback khi spawn không chỉ định mục tiêu rõ ràng. +- `allowedAgents`: allowlist các id agent được phép cho phiên runtime ACP; rỗng nghĩa là không có hạn chế bổ sung. - `maxConcurrentSessions`: số phiên ACP hoạt động đồng thời tối đa. -- `stream.coalesceIdleMs`: cửa sổ xả khi rảnh tính bằng ms cho văn bản được stream. -- `stream.maxChunkChars`: kích thước chunk tối đa trước khi tách phép chiếu khối được stream. -- `stream.repeatSuppression`: chặn các dòng trạng thái/công cụ lặp lại trong mỗi lượt (mặc định: `true`). -- `stream.deliveryMode`: `"live"` stream tăng dần; `"final_only"` đệm cho đến các sự kiện kết thúc lượt. +- `stream.coalesceIdleMs`: cửa sổ flush khi rảnh tính bằng ms cho văn bản streamed. +- `stream.maxChunkChars`: kích thước chunk tối đa trước khi tách projection khối streamed. +- `stream.repeatSuppression`: chặn các dòng trạng thái/công cụ lặp lại theo từng lượt (mặc định: `true`). +- `stream.deliveryMode`: `"live"` stream tăng dần; `"final_only"` buffer cho đến các sự kiện kết thúc lượt. - `stream.hiddenBoundarySeparator`: dấu phân tách trước văn bản hiển thị sau các sự kiện công cụ ẩn (mặc định: `"paragraph"`). -- `stream.maxOutputChars`: số ký tự đầu ra assistant tối đa được chiếu trên mỗi lượt ACP. +- `stream.maxOutputChars`: số ký tự đầu ra assistant tối đa được chiếu cho mỗi lượt ACP. - `stream.maxSessionUpdateChars`: số ký tự tối đa cho các dòng trạng thái/cập nhật ACP được chiếu. -- `stream.tagVisibility`: bản ghi tên thẻ thành các ghi đè khả năng hiển thị boolean cho sự kiện được stream. -- `runtime.ttlMinutes`: TTL khi rảnh tính bằng phút cho worker phiên ACP trước khi đủ điều kiện dọn dẹp. -- `runtime.installCommand`: lệnh cài đặt tùy chọn để chạy khi khởi tạo môi trường runtime ACP. +- `stream.tagVisibility`: bản ghi tên tag tới ghi đè khả năng hiển thị boolean cho các sự kiện streamed. +- `runtime.ttlMinutes`: TTL nhàn rỗi tính bằng phút cho worker phiên ACP trước khi đủ điều kiện dọn dẹp. +- `runtime.installCommand`: lệnh cài đặt tùy chọn để chạy khi bootstrapping môi trường runtime ACP. --- @@ -1060,9 +1046,9 @@ Ghi chú: ``` - `cli.banner.taglineMode` kiểm soát kiểu tagline của banner: - - `"random"` (mặc định): các tagline hài hước/theo mùa xoay vòng. - - `"default"`: tagline trung tính cố định (`All your chats, one OpenClaw.`). - - `"off"`: không có văn bản tagline (tiêu đề/phiên bản banner vẫn hiển thị). + - `"random"` (mặc định): tagline vui/hợp mùa xoay vòng. + - `"default"`: tagline trung lập cố định (`All your chats, one OpenClaw.`). + - `"off"`: không có văn bản tagline (vẫn hiển thị tiêu đề/phiên bản banner). - Để ẩn toàn bộ banner (không chỉ tagline), đặt env `OPENCLAW_HIDE_BANNER=1`. --- @@ -1087,15 +1073,15 @@ Metadata được ghi bởi các luồng thiết lập có hướng dẫn của ## Danh tính -Xem các trường danh tính `agents.list` trong [mặc định Agent](/vi/gateway/config-agents#agent-defaults). +Xem các trường danh tính `agents.list` trong [mặc định agent](/vi/gateway/config-agents#agent-defaults). --- ## Cầu nối (cũ, đã gỡ bỏ) -Các bản build hiện tại không còn bao gồm cầu nối TCP. Node kết nối qua WebSocket Gateway. Các khóa `bridge.*` không còn là một phần của schema cấu hình (xác thực thất bại cho đến khi bị xóa; `openclaw doctor --fix` có thể loại bỏ khóa không xác định). +Các bản dựng hiện tại không còn bao gồm cầu nối TCP. Node kết nối qua Gateway WebSocket. Các khóa `bridge.*` không còn là một phần của schema cấu hình (xác thực thất bại cho đến khi được gỡ bỏ; `openclaw doctor --fix` có thể loại bỏ khóa không xác định). - + ```json { @@ -1134,10 +1120,10 @@ Các bản build hiện tại không còn bao gồm cầu nối TCP. Node kết ``` - `sessionRetention`: thời gian giữ các phiên chạy cron cô lập đã hoàn tất trước khi cắt tỉa khỏi `sessions.json`. Cũng kiểm soát việc dọn dẹp các bản ghi cron đã xóa được lưu trữ. Mặc định: `24h`; đặt `false` để tắt. -- `runLog.maxBytes`: kích thước tối đa trên mỗi tệp nhật ký lần chạy (`cron/runs/.jsonl`) trước khi cắt tỉa. Mặc định: `2_000_000` byte. -- `runLog.keepLines`: các dòng mới nhất được giữ lại khi kích hoạt cắt tỉa nhật ký lần chạy. Mặc định: `2000`. -- `webhookToken`: bearer token dùng cho giao hàng POST Webhook cron (`delivery.mode = "webhook"`), nếu bỏ qua thì không gửi header xác thực. -- `webhook`: URL Webhook dự phòng cũ đã ngừng dùng (http/https), chỉ dùng cho các job đã lưu vẫn có `notify: true`. +- `runLog.maxBytes`: kích thước tối đa cho mỗi tệp nhật ký chạy (`cron/runs/.jsonl`) trước khi cắt tỉa. Mặc định: `2_000_000` byte. +- `runLog.keepLines`: các dòng mới nhất được giữ lại khi kích hoạt cắt tỉa nhật ký chạy. Mặc định: `2000`. +- `webhookToken`: bearer token dùng cho phân phối POST Webhook cron (`delivery.mode = "webhook"`), nếu bỏ qua thì không gửi header xác thực. +- `webhook`: URL Webhook fallback cũ đã ngừng dùng (http/https) chỉ dùng cho các job đã lưu vẫn có `notify: true`. ### `cron.retry` @@ -1153,11 +1139,11 @@ Các bản build hiện tại không còn bao gồm cầu nối TCP. Node kết } ``` -- `maxAttempts`: số lần thử lại tối đa cho các tác vụ chạy một lần khi gặp lỗi tạm thời (mặc định: `3`; phạm vi: `0`–`10`). -- `backoffMs`: mảng độ trễ backoff tính bằng ms cho mỗi lần thử lại (mặc định: `[30000, 60000, 300000]`; 1–10 mục). +- `maxAttempts`: số lần thử lại tối đa cho các công việc chạy một lần khi gặp lỗi tạm thời (mặc định: `3`; phạm vi: `0`–`10`). +- `backoffMs`: mảng độ trễ backoff tính bằng ms cho từng lần thử lại (mặc định: `[30000, 60000, 300000]`; 1–10 mục). - `retryOn`: các loại lỗi kích hoạt thử lại — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Bỏ qua để thử lại tất cả các loại tạm thời. -Chỉ áp dụng cho các tác vụ Cron chạy một lần. Tác vụ định kỳ dùng cơ chế xử lý lỗi riêng. +Chỉ áp dụng cho các công việc Cron chạy một lần. Công việc lặp lại dùng cơ chế xử lý lỗi riêng. ### `cron.failureAlert` @@ -1176,11 +1162,11 @@ Chỉ áp dụng cho các tác vụ Cron chạy một lần. Tác vụ định k } ``` -- `enabled`: bật cảnh báo lỗi cho các tác vụ Cron (mặc định: `false`). -- `after`: số lần lỗi liên tiếp trước khi cảnh báo được kích hoạt (số nguyên dương, tối thiểu: `1`). -- `cooldownMs`: số mili giây tối thiểu giữa các cảnh báo lặp lại cho cùng một tác vụ (số nguyên không âm). -- `includeSkipped`: tính các lần chạy bị bỏ qua liên tiếp vào ngưỡng cảnh báo (mặc định: `false`). Các lần chạy bị bỏ qua được theo dõi riêng và không ảnh hưởng đến backoff cho lỗi thực thi. -- `mode`: chế độ gửi — `"announce"` gửi qua tin nhắn kênh; `"webhook"` đăng lên webhook đã cấu hình. +- `enabled`: bật cảnh báo lỗi cho công việc Cron (mặc định: `false`). +- `after`: số lỗi liên tiếp trước khi cảnh báo được kích hoạt (số nguyên dương, tối thiểu: `1`). +- `cooldownMs`: số mili giây tối thiểu giữa các cảnh báo lặp lại cho cùng một công việc (số nguyên không âm). +- `includeSkipped`: tính các lần chạy bị bỏ qua liên tiếp vào ngưỡng cảnh báo (mặc định: `false`). Các lần chạy bị bỏ qua được theo dõi riêng và không ảnh hưởng đến backoff lỗi thực thi. +- `mode`: chế độ gửi — `"announce"` gửi qua tin nhắn kênh; `"webhook"` đăng lên Webhook đã cấu hình. - `accountId`: tài khoản hoặc id kênh tùy chọn để giới hạn phạm vi gửi cảnh báo. ### `cron.failureDestination` @@ -1198,49 +1184,49 @@ Chỉ áp dụng cho các tác vụ Cron chạy một lần. Tác vụ định k } ``` -- Đích mặc định cho thông báo lỗi Cron trên tất cả tác vụ. -- `mode`: `"announce"` hoặc `"webhook"`; mặc định là `"announce"` khi có đủ dữ liệu mục tiêu. +- Đích mặc định cho thông báo lỗi Cron trên tất cả công việc. +- `mode`: `"announce"` hoặc `"webhook"`; mặc định là `"announce"` khi có đủ dữ liệu đích. - `channel`: ghi đè kênh cho việc gửi announce. `"last"` dùng lại kênh gửi đã biết gần nhất. -- `to`: mục tiêu announce hoặc URL webhook rõ ràng. Bắt buộc với chế độ webhook. +- `to`: đích announce rõ ràng hoặc URL Webhook. Bắt buộc đối với chế độ Webhook. - `accountId`: ghi đè tài khoản tùy chọn cho việc gửi. -- `delivery.failureDestination` theo từng tác vụ ghi đè mặc định toàn cục này. -- Khi không đặt đích lỗi toàn cục hoặc theo từng tác vụ, các tác vụ vốn đã gửi qua `announce` sẽ quay về mục tiêu announce chính đó khi gặp lỗi. -- `delivery.failureDestination` chỉ được hỗ trợ cho các tác vụ `sessionTarget="isolated"` trừ khi `delivery.mode` chính của tác vụ là `"webhook"`. +- `delivery.failureDestination` theo từng công việc ghi đè mặc định toàn cục này. +- Khi không đặt đích lỗi toàn cục hay theo từng công việc, các công việc đã gửi qua `announce` sẽ quay về đích announce chính đó khi lỗi. +- `delivery.failureDestination` chỉ được hỗ trợ cho các công việc `sessionTarget="isolated"` trừ khi `delivery.mode` chính của công việc là `"webhook"`. -Xem [Tác vụ Cron](/vi/automation/cron-jobs). Các lần thực thi Cron cô lập được theo dõi dưới dạng [tác vụ nền](/vi/automation/tasks). +Xem [Công việc Cron](/vi/automation/cron-jobs). Các lần thực thi Cron biệt lập được theo dõi dưới dạng [tác vụ nền](/vi/automation/tasks). --- ## Biến mẫu mô hình phương tiện -Các placeholder mẫu được mở rộng trong `tools.media.models[].args`: +Placeholder mẫu được mở rộng trong `tools.media.models[].args`: | Biến | Mô tả | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | Nội dung đầy đủ của tin nhắn đến | -| `{{RawBody}}` | Nội dung thô (không có lớp bọc lịch sử/người gửi) | -| `{{BodyStripped}}` | Nội dung đã loại bỏ nhắc đến nhóm | +| `{{Body}}` | Toàn bộ nội dung tin nhắn đến | +| `{{RawBody}}` | Nội dung thô (không có wrapper lịch sử/người gửi) | +| `{{BodyStripped}}` | Nội dung đã loại bỏ các lượt nhắc nhóm | | `{{From}}` | Định danh người gửi | | `{{To}}` | Định danh đích | -| `{{MessageSid}}` | id tin nhắn kênh | +| `{{MessageSid}}` | Id tin nhắn kênh | | `{{SessionId}}` | UUID phiên hiện tại | | `{{IsNewSession}}` | `"true"` khi phiên mới được tạo | -| `{{MediaUrl}}` | pseudo-URL phương tiện đến | +| `{{MediaUrl}}` | Pseudo-URL phương tiện đến | | `{{MediaPath}}` | Đường dẫn phương tiện cục bộ | | `{{MediaType}}` | Loại phương tiện (hình ảnh/âm thanh/tài liệu/…) | | `{{Transcript}}` | Bản chép lời âm thanh | -| `{{Prompt}}` | Prompt phương tiện đã phân giải cho các mục CLI | -| `{{MaxChars}}` | Số ký tự đầu ra tối đa đã phân giải cho các mục CLI | +| `{{Prompt}}` | Prompt phương tiện đã phân giải cho mục CLI | +| `{{MaxChars}}` | Số ký tự đầu ra tối đa đã phân giải cho mục CLI | | `{{ChatType}}` | `"direct"` hoặc `"group"` | -| `{{GroupSubject}}` | Chủ đề nhóm (cố gắng tốt nhất) | -| `{{GroupMembers}}` | Bản xem trước thành viên nhóm (cố gắng tốt nhất) | -| `{{SenderName}}` | Tên hiển thị của người gửi (cố gắng tốt nhất) | -| `{{SenderE164}}` | Số điện thoại người gửi (cố gắng tốt nhất) | -| `{{Provider}}` | Gợi ý nhà cung cấp (whatsapp, telegram, discord, v.v.) | +| `{{GroupSubject}}` | Chủ đề nhóm (nỗ lực tốt nhất) | +| `{{GroupMembers}}` | Bản xem trước thành viên nhóm (nỗ lực tốt nhất) | +| `{{SenderName}}` | Tên hiển thị của người gửi (nỗ lực tốt nhất) | +| `{{SenderE164}}` | Số điện thoại của người gửi (nỗ lực tốt nhất) | +| `{{Provider}}` | Gợi ý nhà cung cấp (WhatsApp, Telegram, Discord, v.v.) | --- -## Bao gồm cấu hình (`$include`) +## Include cấu hình (`$include`) Tách cấu hình thành nhiều tệp: @@ -1257,14 +1243,14 @@ Tách cấu hình thành nhiều tệp: **Hành vi hợp nhất:** -- Một tệp: thay thế đối tượng chứa nó. -- Mảng tệp: được hợp nhất sâu theo thứ tự (tệp sau ghi đè tệp trước). -- Khóa cùng cấp: được hợp nhất sau các include (ghi đè các giá trị đã include). +- Một tệp: thay thế đối tượng chứa. +- Mảng tệp: deep-merge theo thứ tự (mục sau ghi đè mục trước). +- Khóa cùng cấp: được hợp nhất sau các include (ghi đè giá trị đã include). - Include lồng nhau: sâu tối đa 10 cấp. -- Đường dẫn: được phân giải tương đối với tệp đang include, nhưng phải nằm trong thư mục cấu hình cấp cao nhất (`dirname` của `openclaw.json`). Dạng tuyệt đối/`../` chỉ được phép khi chúng vẫn phân giải bên trong ranh giới đó. -- Các thao tác ghi do OpenClaw sở hữu chỉ thay đổi một mục cấp cao nhất được hỗ trợ bởi một include một tệp sẽ ghi xuyên qua vào tệp được include đó. Ví dụ: `plugins install` cập nhật `plugins: { $include: "./plugins.json5" }` trong `plugins.json5` và giữ nguyên `openclaw.json`. -- Include gốc, mảng include, và include có ghi đè cùng cấp là chỉ đọc đối với các thao tác ghi do OpenClaw sở hữu; các thao tác ghi đó sẽ fail closed thay vì làm phẳng cấu hình. -- Lỗi: thông báo rõ ràng cho tệp bị thiếu, lỗi phân tích cú pháp, và include vòng. +- Đường dẫn: được phân giải tương đối với tệp đang include, nhưng phải nằm trong thư mục cấu hình cấp cao nhất (`dirname` của `openclaw.json`). Các dạng tuyệt đối/`../` chỉ được phép khi chúng vẫn phân giải bên trong ranh giới đó. +- Các lượt ghi do OpenClaw sở hữu chỉ thay đổi một phần cấp cao nhất được hậu thuẫn bởi include một tệp sẽ ghi xuyên qua tệp được include đó. Ví dụ, `plugins install` cập nhật `plugins: { $include: "./plugins.json5" }` trong `plugins.json5` và giữ nguyên `openclaw.json`. +- Include gốc, mảng include, và include có ghi đè cùng cấp là chỉ đọc đối với các lượt ghi do OpenClaw sở hữu; các lượt ghi đó sẽ fail closed thay vì làm phẳng cấu hình. +- Lỗi: thông báo rõ ràng cho tệp bị thiếu, lỗi phân tích cú pháp, và include vòng tròn. --- diff --git a/docs/vi/gateway/diagnostics.md b/docs/vi/gateway/diagnostics.md index b0255c805..35aabb902 100644 --- a/docs/vi/gateway/diagnostics.md +++ b/docs/vi/gateway/diagnostics.md @@ -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 ` đã 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 ` đã 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 `: ghi vào một đường dẫn zip cụ thể. -- `--log-lines `: số dòng nhật ký đã làm sạch tối đa cần đưa vào. +- `--log-lines `: số dòng nhật ký đã được làm sạch tối đa cần đưa vào. - `--log-bytes `: số byte nhật ký tối đa cần kiểm tra. -- `--url `: URL WebSocket Gateway cho ảnh chụp nhanh trạng thái và tình trạng. -- `--token `: token Gateway cho ảnh chụp nhanh trạng thái và tình trạng. -- `--password `: mật khẩu Gateway cho ảnh chụp nhanh trạng thái và tình trạng. -- `--timeout `: timeout ảnh chụp nhanh trạng thái và tình trạng. +- `--url `: URL WebSocket Gateway cho ảnh chụp nhanh trạng thái và sức khỏe. +- `--token `: token Gateway cho ảnh chụp nhanh trạng thái và sức khỏe. +- `--password `: mật khẩu Gateway cho ảnh chụp nhanh trạng thái và sức khỏe. +- `--timeout `: 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 diff --git a/docs/vi/gateway/doctor.md b/docs/vi/gateway/doctor.md index 203db140f..e30c288e3 100644 --- a/docs/vi/gateway/doctor.md +++ b/docs/vi/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - Thêm hoặc sửa đổi các 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). @@ -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). @@ -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. @@ -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). -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) - - - 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). + + - 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. @@ -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. - - 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`). - 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`). - + - 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). - 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. -## Đ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 - 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. - 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.`. 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.`. 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. - 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..timeoutSeconds` cho thời gian chờ provider/model chậm + - xóa `agents.defaults.llm`; dùng `models.providers..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..accounts` trở lên được cấu hình mà không có `channels..defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản không mong muốn. - - Nếu `channels..defaultAccount` được đặt thành ID tài khoản không xác định, doctor cảnh báo và liệt kê các ID tài khoản đã cấu hình. + - Nếu có từ hai mục `channels..accounts` trở lên được cấu hình mà không có `channels..defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản không mong muốn. + - Nếu `channels..defaultAccount` được đặt thành 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. - - Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, nó sẽ ghi đè catalog OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể ép các model dùng sai API hoặc đưa chi phí về 0. Doctor cảnh báo để bạn có thể xóa phần ghi đè và khôi phục định tuyến API + chi phí theo từng model. + + Nếu 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. - - 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: + + 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ô. - 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. - - 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. + + 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. - 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. - - Doctor có thể di chuyển các bố cục cũ trên đĩa sang cấu trúc hiện tại: + + 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. + + + + 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//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//agent/` - Trạng thái xác thực WhatsApp (Baileys): - từ `~/.openclaw/credentials/*.json` cũ (ngoại trừ `oauth.json`) - - sang `~/.openclaw/credentials/whatsapp//...` (id tài khoản mặc định: `default`) + - sang `~/.openclaw/credentials/whatsapp//...` (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. - 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. - 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. - 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`. - 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. - - 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). + + 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`. - - 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. + + 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) - - 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. + + 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. - 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. - 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. - - 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." + + 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. - - 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. + + 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. - 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 ` - - xoay vòng token mới bằng `openclaw devices rotate --device --role ` - - xóa và phê duyệt lại bản ghi cũ bằng `openclaw devices remove ` + - phê duyệt đúng yêu cầu bằng `openclaw devices approve ` + - xoay token mới bằng `openclaw devices rotate --device --role ` + - xóa và phê duyệt lại bản ghi lỗi thời bằng `openclaw devices remove ` - 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. - 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. - 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. - - Doctor in bản tóm tắt trạng thái workspace cho tác tử mặc định: + + 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. - 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`. - - Khi `openclaw doctor --fix` xóa một Plugin kênh bị thiếu, công cụ cũng xóa cấu hình theo phạm vi kênh bị treo đã tham chiếu Plugin đó: mục `channels.`, mục tiêu Heartbeat đã đặt tên kênh, và các ghi đè `agents.*.models["/*"]`. Việc này ngăn vòng lặp khởi động Gateway khi runtime kênh đã mất nhưng cấu hình vẫn yêu cầu gateway liên kết với nó. + + 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.`, mục tiêu Heartbeat đã nêu tên channel, và ghi đè `agents.*.models["/*"]`. Đ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ó. - 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. - 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. - + 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. - - Lệnh doctor chạy kiểm tra tình trạng và đề xuất khởi động lại gateway khi có vẻ không khỏe. + + Doctor 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. - - 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: + + 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. - 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. - 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`. - - Doctor kiểm tra runtime dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã được cài đặt nhưng thực tế không chạy. Nó cũng kiểm tra xung đột cổng trên cổng gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng xảy ra (gateway đã chạy, đường hầm SSH). + + Doctor 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). - 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. Doctor lưu mọi thay đổi cấu hình và đóng dấu metadata wizard để ghi lại lần chạy doctor. - Doctor đề xuất hệ thống bộ nhớ workspace khi 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ư). diff --git a/docs/vi/gateway/logging.md b/docs/vi/gateway/logging.md index d9a58ffd3..5a9a34c39 100644 --- a/docs/vi/gateway/logging.md +++ b/docs/vi/gateway/logging.md @@ -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) diff --git a/docs/vi/help/debugging.md b/docs/vi/help/debugging.md index a134b0a65..52bb29f79 100644 --- a/docs/vi/help/debugging.md +++ b/docs/vi/help/debugging.md @@ -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 ` 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 ``` -`--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 `--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. -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 -## 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 diff --git a/docs/vi/help/faq-models.md b/docs/vi/help/faq-models.md index c52c25996..62a0e924e 100644 --- a/docs/vi/help/faq-models.md +++ b/docs/vi/help/faq-models.md @@ -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 - - Mô hình mặc định của OpenClaw là bất kỳ mô hình nào bạn đặt làm: + + 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**. - - **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. + + **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). - + 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: - - Có. Ollama là đường dẫn dễ nhất cho mô hình cục bộ. + + 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/` - 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). - - 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. - + 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 `). + Nếu bạn muốn quay lại mặc định, hãy chọn nó từ `/model` (hoặc gửi `/model `). Dùng `/model status` để xác nhận hồ sơ xác thực nào đang hoạt độ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). - - Dùng công tắc phiên hoặc mặc định cấu hình: + + 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). - - Nếu `agents.defaults.models` được đặt, nó trở thành **danh sách cho phép** cho `/model` và mọ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 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`. - Đ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: 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). - - 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`): + + 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. - - Bí danh đến từ `agents.defaults.models..alias`. Ví dụ: + + Alias đến từ `agents.defaults.models..alias`. Ví dụ: ```json5 { @@ -304,12 +307,12 @@ x-i18n: } ``` - Sau đó `/model sonnet` (hoặc `/` khi được hỗ trợ) phân giải thành ID mô hình đó. + Sau đó `/model sonnet` (hoặc `/` khi được hỗ trợ) sẽ phân giải thành ID mô hình đó. - - OpenRouter (trả tiền theo token; nhiều mô hình): + + 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 ` 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. @@ -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" - + 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. - + Đ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//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. - - 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"`. + + 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 đó. @@ -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) - + 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//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 ` hoặc `--json`). Xem [Models CLI](/vi/cli/models#openclaw-models-auth-list) để biết chi tiết. + - - OpenClaw dùng các ID có tiền tố nhà cung cấp như: + + 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:` cho danh tính OAuth + - `anthropic:default` (phổ biến khi không có định danh email) + - `anthropic:` cho định danh OAuth - ID tùy chỉnh bạn chọn (ví dụ: `anthropic:work`) - - 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.`). Đ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. + + 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.`). Đ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ó. - + 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. ## 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) diff --git a/docs/vi/help/testing-live.md b/docs/vi/help/testing-live.md index 55ce689d8..1bf9f682b 100644 --- a/docs/vi/help/testing-live.md +++ b/docs/vi/help/testing-live.md @@ -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 `. + - 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 `. - 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: "" }]` - - 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: "" }]` + - 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ỏ) -Để 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 -## 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 --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.) -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. ## 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//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//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.` đượ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: - `: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 diff --git a/docs/vi/help/testing-updates-plugins.md b/docs/vi/help/testing-updates-plugins.md index 59ab7e559..83c41d002 100644 --- a/docs/vi/help/testing-updates-plugins.md +++ b/docs/vi/help/testing-updates-plugins.md @@ -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. diff --git a/docs/vi/help/testing.md b/docs/vi/help/testing.md index f294abee8..850d82eb5 100644 --- a/docs/vi/help/testing.md +++ b/docs/vi/help/testing.md @@ -1,218 +1,230 @@ --- read_when: - Chạy kiểm thử cục bộ hoặc trong CI - - Thêm kiểm thử hồi quy cho lỗi mô hình/nhà cung cấp - - Gỡ lỗi hành vi của Gateway + tác tử -summary: 'Bộ công cụ kiểm thử: các bộ kiểm thử unit/e2e/live, trình chạy Docker và phạm vi kiểm thử của từng bài kiểm thử' + - Thêm các kiểm thử hồi quy cho lỗi mô hình/nhà cung cấp + - Gỡ lỗi hành vi của Gateway + tác nhân +summary: 'Bộ công cụ kiểm thử: bộ kiểm thử đơn vị/e2e/trực tiếp, trình chạy Docker và phạm vi kiểm thử của từng bài kiểm thử' title: Kiểm thử x-i18n: - generated_at: "2026-05-04T07:05:02Z" + generated_at: "2026-05-05T01:48:11Z" model: gpt-5.5 provider: openai - source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 + source_hash: 8d051bf6a01f6caf7755ad1d7107f21ae2d440b55a65bb7f18ee4a81f5f0e3b2 source_path: help/testing.md workflow: 16 --- -OpenClaw có ba bộ kiểm thử Vitest (unit/integration, e2e, live) và một tập nhỏ các runner Docker. Tài liệu này là hướng dẫn "cách chúng ta kiểm thử": +OpenClaw có ba bộ kiểm thử Vitest (unit/integration, e2e, live) và một nhóm nhỏ +các trình chạy Docker. Tài liệu này là hướng dẫn "cách chúng ta kiểm thử": -- Mỗi bộ kiểm thử bao phủ những gì (và những gì nó cố ý _không_ bao phủ). -- Các lệnh cần chạy cho các workflow phổ biến (cục bộ, trước khi push, gỡ lỗi). -- Cách kiểm thử live phát hiện thông tin xác thực và chọn mô hình/nhà cung cấp. -- Cách thêm hồi quy cho các sự cố mô hình/nhà cung cấp trong thực tế. +- Mỗi bộ kiểm thử bao phủ những gì (và những gì cố ý _không_ bao phủ). +- Những lệnh cần chạy cho các luồng công việc phổ biến (cục bộ, trước khi push, gỡ lỗi). +- Cách các kiểm thử live phát hiện thông tin xác thực và chọn model/provider. +- Cách thêm kiểm thử hồi quy cho các vấn đề model/provider trong thực tế. -**Ngăn xếp QA (qa-lab, qa-channel, các lane truyền tải live)** được ghi lại riêng: +**Ngăn xếp QA (qa-lab, qa-channel, các làn truyền tải live)** được ghi tài liệu riêng: -- [Tổng quan QA](/vi/concepts/qa-e2e-automation) — kiến trúc, bề mặt lệnh, cách viết kịch bản. -- [QA ma trận](/vi/concepts/qa-matrix) — tham chiếu cho `pnpm openclaw qa matrix`. +- [Tổng quan QA](/vi/concepts/qa-e2e-automation) — kiến trúc, bề mặt lệnh, biên soạn kịch bản. +- [Matrix QA](/vi/concepts/qa-matrix) — tài liệu tham chiếu cho `pnpm openclaw qa matrix`. - [Kênh QA](/vi/channels/qa-channel) — Plugin truyền tải tổng hợp được dùng bởi các kịch bản dựa trên repo. -Trang này bao quát việc chạy các bộ kiểm thử thông thường và runner Docker/Parallels. Phần runner dành riêng cho QA bên dưới ([Runner dành riêng cho QA](#qa-specific-runners)) liệt kê các lời gọi `qa` cụ thể và trỏ lại các tài liệu tham chiếu ở trên. +Trang này bao phủ việc chạy các bộ kiểm thử thông thường và các trình chạy Docker/Parallels. Phần trình chạy dành riêng cho QA bên dưới ([Trình chạy dành riêng cho QA](#qa-specific-runners)) liệt kê các lệnh gọi `qa` cụ thể và trỏ lại các tài liệu tham chiếu ở trên. ## Bắt đầu nhanh Hầu hết các ngày: -- Cổng kiểm tra đầy đủ (kỳ vọng trước khi push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Chạy bộ đầy đủ nhanh hơn trên máy nhiều tài nguyên: `pnpm test:max` -- Vòng lặp watch trực tiếp của Vitest: `pnpm test:watch` -- Nhắm mục tiêu tệp trực tiếp giờ cũng định tuyến các đường dẫn extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Ưu tiên các lần chạy có mục tiêu trước khi bạn đang lặp trên một lỗi đơn lẻ. +- Cổng kiểm tra đầy đủ (được kỳ vọng trước khi push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Chạy toàn bộ bộ kiểm thử cục bộ nhanh hơn trên máy có nhiều tài nguyên: `pnpm test:max` +- Vòng lặp theo dõi Vitest trực tiếp: `pnpm test:watch` +- Nhắm trực tiếp vào tệp hiện cũng định tuyến các đường dẫn extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Ưu tiên các lần chạy nhắm mục tiêu trước khi bạn đang lặp trên một lỗi đơn lẻ. - Trang QA dựa trên Docker: `pnpm qa:lab:up` -- Lane QA dựa trên máy ảo Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Làn QA dựa trên VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Khi bạn chạm vào kiểm thử hoặc muốn thêm độ tin cậy: -- Cổng coverage: `pnpm test:coverage` -- Bộ E2E: `pnpm test:e2e` +- Cổng kiểm tra độ phủ: `pnpm test:coverage` +- Bộ kiểm thử E2E: `pnpm test:e2e` -Khi gỡ lỗi các nhà cung cấp/mô hình thực (yêu cầu thông tin xác thực thật): +Khi gỡ lỗi provider/model thật (yêu cầu thông tin xác thực thật): -- Bộ live (mô hình + probe công cụ/hình ảnh Gateway): `pnpm test:live` -- Nhắm mục tiêu một tệp live ở chế độ yên lặng: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Bộ kiểm thử live (model + probe công cụ/hình ảnh Gateway): `pnpm test:live` +- Nhắm vào một tệp live trong chế độ yên lặng: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Báo cáo hiệu năng runtime: dispatch `OpenClaw Performance` với - `live_gpt54=true` cho một lượt tác tử `openai/gpt-5.4` thật hoặc + `live_gpt54=true` cho một lượt agent `openai/gpt-5.4` thật hoặc `deep_profile=true` cho artifact CPU/heap/trace của Kova. Các lần chạy theo lịch hằng ngày - publish artifact lane mock-provider, deep-profile và GPT 5.4 lên + xuất bản artifact của làn mock-provider, deep-profile và GPT 5.4 lên `openclaw/clawgrit-reports` khi `CLAWGRIT_REPORTS_TOKEN` được cấu hình. Báo cáo - mock-provider cũng bao gồm số liệu gateway boot cấp nguồn, bộ nhớ, - plugin-pressure, hello-loop fake-model lặp lại và khởi động CLI. -- Quét mô hình live Docker: `pnpm test:docker:live-models` - - Mỗi mô hình được chọn giờ chạy một lượt văn bản cộng với một probe nhỏ kiểu đọc tệp. - Các mô hình có metadata quảng cáo đầu vào `image` cũng chạy một lượt hình ảnh nhỏ. + mock-provider cũng bao gồm các số liệu ở cấp mã nguồn về khởi động gateway, bộ nhớ, + áp lực Plugin, vòng lặp chào fake-model lặp lại, và khởi động CLI. +- Quét model live bằng Docker: `pnpm test:docker:live-models` + - Mỗi model được chọn hiện chạy một lượt văn bản cộng với một probe nhỏ kiểu đọc tệp. + Các model có metadata quảng bá đầu vào `image` cũng chạy một lượt hình ảnh nhỏ. Tắt các probe bổ sung bằng `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` hoặc - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` khi cô lập lỗi nhà cung cấp. - - Coverage CI: `OpenClaw Scheduled Live And E2E Checks` hằng ngày và - `OpenClaw Release Checks` thủ công đều gọi workflow live/E2E có thể tái sử dụng với - `include_live_suites: true`, bao gồm các job ma trận mô hình live Docker riêng - được shard theo nhà cung cấp. - - Với các lần chạy lại CI tập trung, dispatch `OpenClaw Live And E2E Checks (Reusable)` + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` khi cô lập lỗi provider. + - Độ phủ CI: `OpenClaw Scheduled Live And E2E Checks` hằng ngày và + `OpenClaw Release Checks` thủ công đều gọi workflow live/E2E tái sử dụng với + `include_live_suites: true`, trong đó bao gồm các job ma trận model live Docker + riêng được phân mảnh theo provider. + - Để chạy lại CI có trọng tâm, dispatch `OpenClaw Live And E2E Checks (Reusable)` với `include_live_suites: true` và `live_models_only: true`. - - Thêm secret nhà cung cấp có tín hiệu cao mới vào `scripts/ci-hydrate-live-auth.sh` - cùng `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` và các caller - theo lịch/release của nó. -- Smoke bound-chat Codex native: `pnpm test:docker:live-codex-bind` - - Chạy một lane live Docker trên đường dẫn Codex app-server, bind một Slack DM tổng hợp - với `/codex bind`, thực thi `/codex fast` và - `/codex permissions`, rồi xác minh một phản hồi thường và một tệp đính kèm hình ảnh - định tuyến qua binding Plugin native thay vì ACP. -- Smoke harness Codex app-server: `pnpm test:docker:live-codex-harness` - - Chạy các lượt tác tử Gateway qua harness Codex app-server do Plugin sở hữu, - xác minh `/codex status` và `/codex models`, và mặc định thực thi các probe hình ảnh, + - Thêm secret provider tín hiệu cao mới vào `scripts/ci-hydrate-live-auth.sh` + cùng với `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` và các caller + theo lịch/phát hành của nó. +- Smoke bound-chat Codex gốc: `pnpm test:docker:live-codex-bind` + - Chạy một làn live Docker qua đường dẫn app-server Codex, bind một + Slack DM tổng hợp bằng `/codex bind`, thực thi `/codex fast` và + `/codex permissions`, rồi xác minh một phản hồi thuần và một tệp đính kèm hình ảnh + định tuyến qua binding Plugin gốc thay vì ACP. +- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` + - Chạy các lượt agent gateway qua harness app-server Codex do Plugin sở hữu, + xác minh `/codex status` và `/codex models`, và theo mặc định thực thi các probe hình ảnh, cron MCP, sub-agent và Guardian. Tắt probe sub-agent bằng - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` khi cô lập các lỗi Codex - app-server khác. Với kiểm tra sub-agent tập trung, tắt các probe khác: + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` khi cô lập các lỗi app-server Codex khác. + Để kiểm tra sub-agent có trọng tâm, tắt các probe khác: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. Lệnh này thoát sau probe sub-agent trừ khi `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` được đặt. -- Smoke lệnh rescue Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Kiểm tra belt-and-suspenders dạng opt-in cho bề mặt lệnh rescue message-channel. - Nó thực thi `/crestodian status`, xếp hàng một thay đổi mô hình bền vững, +- Smoke lệnh cứu hộ Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Kiểm tra tùy chọn cẩn trọng bổ sung cho bề mặt lệnh cứu hộ kênh tin nhắn. + Nó thực thi `/crestodian status`, xếp hàng một thay đổi model bền vững, trả lời `/crestodian yes`, và xác minh đường dẫn ghi audit/config. - Smoke Docker planner Crestodian: `pnpm test:docker:crestodian-planner` - - Chạy Crestodian trong container không có config với Claude CLI giả trên `PATH` - và xác minh fallback planner fuzzy được dịch thành một lần ghi config có kiểu và được audit. + - Chạy Crestodian trong container không có cấu hình với một Claude CLI giả trên `PATH` + và xác minh phương án dự phòng fuzzy planner được dịch thành một lần ghi cấu hình có kiểu đã được audit. - Smoke Docker lần chạy đầu tiên của Crestodian: `pnpm test:docker:crestodian-first-run` - - Bắt đầu từ thư mục trạng thái OpenClaw trống, định tuyến `openclaw` trần tới - Crestodian, áp dụng setup/model/agent/Discord Plugin + ghi SecretRef, - xác thực config và xác minh các entry audit. Cùng đường dẫn thiết lập Ring 0 này - cũng được bao phủ trong QA Lab bởi + - Bắt đầu từ thư mục trạng thái OpenClaw trống, định tuyến `openclaw` thuần đến + Crestodian, áp dụng các lần ghi setup/model/agent/Plugin Discord + SecretRef, + xác thực cấu hình, và xác minh các mục audit. Cùng đường dẫn thiết lập Ring 0 này cũng + được bao phủ trong QA Lab bởi `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. - Smoke chi phí Moonshot/Kimi: với `MOONSHOT_API_KEY` được đặt, chạy - `openclaw models list --provider moonshot --json`, rồi chạy một + `openclaw models list --provider moonshot --json`, rồi chạy một lượt độc lập `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - biệt lập trên `moonshot/kimi-k2.6`. Xác minh JSON báo cáo Moonshot/K2.6 và - transcript của assistant lưu `usage.cost` đã chuẩn hóa. + trên `moonshot/kimi-k2.6`. Xác minh JSON báo cáo Moonshot/K2.6 và bản ghi trợ lý + lưu `usage.cost` đã chuẩn hóa. -Khi bạn chỉ cần một ca lỗi, hãy ưu tiên thu hẹp kiểm thử live bằng các biến môi trường allowlist được mô tả bên dưới. +Khi bạn chỉ cần một trường hợp lỗi, ưu tiên thu hẹp kiểm thử live bằng các biến môi trường allowlist được mô tả bên dưới. -## Runner dành riêng cho QA +## Trình chạy dành riêng cho QA Các lệnh này nằm cạnh các bộ kiểm thử chính khi bạn cần tính thực tế của QA-lab: -CI chạy QA Lab trong các workflow chuyên dụng. Agentic parity được lồng dưới -`QA-Lab - All Lanes` và xác thực release, không phải một workflow PR độc lập. +CI chạy QA Lab trong các workflow chuyên dụng. Tính tương đương agentic được lồng dưới +`QA-Lab - All Lanes` và xác thực phát hành, không phải một workflow PR độc lập. Xác thực rộng nên dùng `Full Release Validation` với -`rerun_group=qa-parity` hoặc nhóm QA của release-checks. `QA-Lab - All Lanes` -chạy hằng đêm trên `main` và từ manual dispatch với lane mock parity, lane -Matrix live, lane Telegram live do Convex quản lý và lane Discord live do Convex -quản lý dưới dạng các job song song. QA theo lịch và release check truyền Matrix -`--profile fast` một cách tường minh, trong khi CLI Matrix và đầu vào workflow thủ công -mặc định vẫn là `all`; manual dispatch có thể shard `all` thành các job `transport`, -`media`, `e2ee-smoke`, `e2ee-deep` và `e2ee-cli`. `OpenClaw Release -Checks` chạy parity cộng với các lane Matrix nhanh và Telegram trước khi phê duyệt -release, dùng `mock-openai/gpt-5.5` cho các kiểm tra truyền tải release để chúng vẫn -xác định và tránh khởi động Plugin nhà cung cấp thông thường. Các Gateway truyền tải live -này tắt tìm kiếm bộ nhớ; hành vi bộ nhớ vẫn được bao phủ bởi các bộ QA parity. +`rerun_group=qa-parity` hoặc nhóm QA của release-checks. Các kiểm tra phát hành stable/default +giữ soak live/Docker toàn diện phía sau `run_release_soak=true`; profile +`full` bắt buộc bật soak. `QA-Lab - All Lanes` +chạy hằng đêm trên `main` và từ dispatch thủ công với làn mock parity, làn Matrix live, +làn Telegram live do Convex quản lý, và làn Discord live do Convex quản lý +dưới dạng các job song song. QA theo lịch và release checks truyền Matrix +`--profile fast` một cách tường minh, trong khi mặc định của Matrix CLI và đầu vào workflow thủ công +vẫn là `all`; dispatch thủ công có thể phân mảnh `all` thành các job `transport`, +`media`, `e2ee-smoke`, `e2ee-deep`, và `e2ee-cli`. `OpenClaw Release +Checks` chạy parity cộng với các làn Matrix fast và Telegram trước phê duyệt phát hành, +dùng `mock-openai/gpt-5.5` cho các kiểm tra truyền tải phát hành để chúng luôn +xác định và tránh khởi động provider-plugin thông thường. Các gateway truyền tải live này +tắt tìm kiếm bộ nhớ; hành vi bộ nhớ vẫn được bao phủ bởi các bộ QA parity. -Các shard live media của full release dùng +Các shard media live của bản phát hành đầy đủ dùng `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, vốn đã có -`ffmpeg` và `ffprobe`. Các shard mô hình/backend live Docker dùng image dùng chung +`ffmpeg` và `ffprobe`. Các shard model/backend live Docker dùng image dùng chung `ghcr.io/openclaw/openclaw-live-test:` được build một lần cho mỗi commit được chọn, -rồi pull image đó với `OPENCLAW_SKIP_DOCKER_BUILD=1` thay vì build lại -bên trong từng shard. +sau đó kéo image đó bằng `OPENCLAW_SKIP_DOCKER_BUILD=1` thay vì build lại +trong từng shard. - `pnpm openclaw qa suite` - - Chạy các kịch bản QA dựa trên repo trực tiếp trên máy chủ. - - Mặc định chạy song song nhiều kịch bản đã chọn bằng các worker Gateway - được cô lập. `qa-channel` mặc định có concurrency 4 (bị giới hạn bởi số - kịch bản đã chọn). Dùng `--concurrency ` để điều chỉnh số worker, - hoặc `--concurrency 1` cho lane nối tiếp cũ hơn. + - Chạy trực tiếp các kịch bản QA dựa trên repo trên máy chủ. + - Theo mặc định, chạy song song nhiều kịch bản đã chọn với các worker + gateway biệt lập. `qa-channel` mặc định có concurrency 4 (giới hạn bởi + số lượng kịch bản đã chọn). Dùng `--concurrency ` để điều chỉnh số + worker, hoặc `--concurrency 1` cho lane nối tiếp cũ hơn. - Thoát 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ó artifact mà không có exit code thất bại. + muốn có artifact mà không có mã thoát thất bại. - Hỗ trợ các chế độ provider `live-frontier`, `mock-openai`, và `aimock`. - `aimock` khởi động một server provider cục bộ dựa trên AIMock để bao phủ - fixture thử nghiệm và mock giao thức mà không thay thế lane `mock-openai` - nhận biết kịch bản. + `aimock` khởi động một máy chủ provider cục bộ dựa trên AIMock cho phạm vi + fixture thử nghiệm và mô phỏng giao thức mà không thay thế lane + `mock-openai` có nhận biết kịch bản. +- `pnpm test:plugins:kitchen-sink-live` + - Chạy gauntlet Plugin Kitchen Sink OpenAI trực tiếp qua QA Lab. Nó + cài đặt gói Kitchen Sink bên ngoài, xác minh inventory bề mặt SDK Plugin, + dò `/healthz` và `/readyz`, ghi lại bằng chứng CPU/RSS của Gateway, + chạy một lượt OpenAI trực tiếp, và kiểm tra chẩn đoán đối kháng. + Yêu cầu xác thực OpenAI trực tiếp như `OPENAI_API_KEY`. Trong các phiên Testbox + đã hydrate, nó tự động nạp profile xác thực trực tiếp Testbox khi có helper + `openclaw-testbox-env`. - `pnpm test:gateway:cpu-scenarios` - - Chạy bench khởi động Gateway cùng một gói nhỏ kịch bản QA Lab giả lập + - Chạy bench khởi động Gateway cùng một gói nhỏ kịch bản QA Lab mô phỏng (`channel-chat-baseline`, `memory-failure-fallback`, - `gateway-restart-inflight-run`) và ghi một bản tóm tắt quan sát CPU tổng hợp - dưới `.artifacts/gateway-cpu-scenarios/`. - - Mặc định chỉ gắn cờ các quan sát CPU nóng kéo dài (`--cpu-core-warn` - cộng với `--hot-wall-warn-ms`), nên các đợt tăng ngắn lúc khởi động được ghi - làm metric mà không trông giống hồi quy Gateway bị ghim CPU kéo dài nhiều phút. - - Dùng artifact `dist` đã build; hãy chạy build trước khi checkout chưa có - output runtime mới. + `gateway-restart-inflight-run`) và ghi một bản tóm tắt quan sát CPU kết hợp + trong `.artifacts/gateway-cpu-scenarios/`. + - Theo mặc định chỉ gắn cờ các quan sát CPU nóng kéo dài (`--cpu-core-warn` + cùng `--hot-wall-warn-ms`), vì vậy các đợt tăng ngắn lúc khởi động được ghi + dưới dạng metric mà không trông giống hồi quy Gateway bị ghim CPU kéo dài nhiều phút. + - Dùng các artifact `dist` đã build; hãy chạy build trước khi checkout chưa + có đầu ra runtime mới. - `pnpm openclaw qa suite --runner multipass` - - Chạy cùng bộ QA suite trong một VM Linux Multipass dùng một lần. - - Giữ nguyên hành vi chọn kịch bản như `qa suite` trên máy chủ. - - Tái sử dụng cùng các flag chọn provider/model như `qa suite`. - - Các lần chạy live chuyển tiếp những input xác thực QA được hỗ trợ và thực tế cho guest: - khóa provider qua env, đường dẫn cấu hình provider live của QA, và `CODEX_HOME` + - Chạy cùng bộ QA trong một VM Linux Multipass dùng một lần. + - Giữ cùng hành vi chọn kịch bản như `qa suite` trên máy chủ. + - Tái sử dụng cùng các cờ chọn provider/model như `qa suite`. + - Các lần chạy trực tiếp chuyển tiếp những đầ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 QA trực tiếp, và `CODEX_HOME` khi có. - - Thư mục output phải nằm dưới gốc repo để guest có thể ghi ngược lại qua + - Thư mục đầu ra phải nằm dưới gốc repo để guest có thể ghi ngược qua workspace được mount. - - Ghi báo cáo QA + tóm tắt bình thường cùng log Multipass dưới + - Ghi báo cáo QA và tóm tắt thông thường cùng log Multipass trong `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Khởi động site QA dựa trên Docker cho công việc QA kiểu operator. - `pnpm test:docker:npm-onboard-channel-agent` - Build một tarball npm từ checkout hiện tại, cài đặt toàn cục trong - Docker, chạy onboarding khóa API OpenAI không tương tác, mặc định cấu hình Telegram, - xác minh runtime Plugin đóng gói tải được mà không cần sửa dependency lúc khởi động, - chạy doctor, và chạy một lượt agent cục bộ với endpoint OpenAI được mock. - - Dùng `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` để chạy cùng lane cài đặt đóng gói + Docker, chạy onboarding khóa API OpenAI không tương tác, cấu hình Telegram + theo mặc định, xác minh runtime Plugin đã đóng gói tải được mà không cần + sửa chữa dependency lúc khởi động, chạy doctor, và chạy một lượt agent cục bộ + với endpoint OpenAI được mô phỏng. + - Dùng `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` để chạy cùng lane cài đặt gói với Discord. - `pnpm test:docker:session-runtime-context` - - Chạy một smoke Docker ứng dụng đã build có tính xác định cho transcript ngữ cảnh runtime nhúng. - Nó xác minh ngữ cảnh runtime OpenClaw ẩn được lưu bền vững dưới dạng một - custom message không hiển thị thay vì rò rỉ vào lượt người dùng hiển thị, + - Chạy một smoke Docker app đã build có tính quyết định cho transcript ngữ cảnh runtime + nhúng. Nó xác minh ngữ cảnh runtime OpenClaw ẩn được lưu dưới dạng thông điệp + tùy chỉnh không hiển thị thay vì rò rỉ vào lượt người dùng hiển thị, sau đó seed một JSONL phiên bị hỏng bị ảnh hưởng và xác minh - `openclaw doctor --fix` ghi lại nó sang nhánh hoạt động kèm bản sao lưu. + `openclaw doctor --fix` ghi lại nó về nhánh active cùng một bản sao lưu. - `pnpm test:docker:npm-telegram-live` - - Cài đặt một ứng viên package OpenClaw trong Docker, chạy onboarding package đã cài, - cấu hình Telegram qua CLI đã cài, rồi tái sử dụng lane QA Telegram live với - package đã cài đó làm Gateway SUT. + - Cài đặt một ứng viên gói OpenClaw trong Docker, chạy onboarding gói đã cài, + cấu hình Telegram qua CLI đã cài, rồi tái sử dụng lane QA Telegram trực tiếp + với gói đã cài đó làm Gateway SUT. - Mặc định là `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; đặt `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` hoặc `OPENCLAW_CURRENT_PACKAGE_TGZ` để kiểm thử một tarball cục bộ đã resolve thay vì - cài từ registry. - - Dùng cùng credentials env Telegram hoặc nguồn credential Convex như - `pnpm openclaw qa telegram`. Với tự động hóa CI/phát hành, đặt - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` cộng với - `OPENCLAW_QA_CONVEX_SITE_URL` và secret của role. Nếu - `OPENCLAW_QA_CONVEX_SITE_URL` và một secret role Convex có trong CI, + cài đặt từ registry. + - Dùng cùng thông tin xác thực env Telegram hoặc nguồn thông tin xác thực Convex như + `pnpm openclaw qa telegram`. Với tự động hóa CI/release, đặt + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` cùng + `OPENCLAW_QA_CONVEX_SITE_URL` và secret vai trò. Nếu + `OPENCLAW_QA_CONVEX_SITE_URL` và một secret vai trò Convex có mặt trong CI, wrapper Docker tự động chọn Convex. - - Wrapper xác thực env credential Telegram hoặc Convex trên máy chủ trước khi - làm việc build/cài đặt Docker. Chỉ đặt `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` - khi chủ đích debug thiết lập trước credential. + - Wrapper xác thực env thông tin xác thực Telegram hoặc Convex trên máy chủ trước + công việc build/cài đặt Docker. Chỉ đặt `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` + khi cố ý debug thiết lập trước thông tin xác thực. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` ghi đè `OPENCLAW_QA_CREDENTIAL_ROLE` dùng chung chỉ cho lane này. - GitHub Actions hiển thị lane này dưới dạng workflow maintainer thủ công `NPM Telegram Beta E2E`. Nó không chạy khi merge. Workflow dùng môi trường - `qa-live-shared` và lease credential CI Convex. -- GitHub Actions cũng hiển thị `Package Acceptance` để chạy bên cạnh làm bằng chứng sản phẩm - với một package ứng viên. Nó chấp nhận một ref đáng tin cậy, spec npm đã publish, - URL tarball HTTPS cộng SHA-256, hoặc artifact tarball từ một lần chạy khác, upload - `openclaw-current.tgz` đã chuẩn hóa làm `package-under-test`, rồi chạy - bộ lập lịch Docker E2E hiện có với các profile lane smoke, package, product, full, - hoặc tùy chỉnh. Đặt `telegram_mode=mock-openai` hoặc `live-frontier` để chạy - workflow QA Telegram với cùng artifact `package-under-test`. + `qa-live-shared` và lease thông tin xác thực CI Convex. +- GitHub Actions cũng hiển thị `Package Acceptance` cho bằng chứng sản phẩm chạy bên + cạnh với một gói ứng viên. Nó chấp nhận một ref đáng tin cậy, spec npm đã publish, + URL tarball HTTPS kèm SHA-256, hoặc artifact tarball từ một lần chạy khác, tải lên + `openclaw-current.tgz` đã chuẩn hóa dưới tên `package-under-test`, rồi chạy + scheduler Docker E2E hiện có với các profile lane smoke, package, product, full, hoặc custom. + Đặt `telegram_mode=mock-openai` hoặc `live-frontier` để chạy workflow QA Telegram + với cùng artifact `package-under-test`. - Bằng chứng sản phẩm beta mới nhất: ```bash @@ -223,7 +235,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Bằng chứng URL tarball chính xác yêu cầu một digest: +- Bằng chứng URL tarball chính xác yêu cầu digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -244,27 +256,27 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - Đóng gói và cài đặt build OpenClaw hiện tại trong Docker, khởi động Gateway - với OpenAI đã cấu hình, rồi bật các channel/Plugin đi kèm qua chỉnh sửa config. - - Xác minh quá trình khám phá thiết lập để các Plugin có thể tải xuống nhưng chưa cấu hình vắng mặt, - lần sửa doctor được cấu hình đầu tiên cài đặt rõ ràng từng Plugin có thể tải xuống - còn thiếu, và lần khởi động lại thứ hai không chạy sửa dependency ẩn. + - Đóng gói và cài đặt bản build OpenClaw hiện tại trong Docker, khởi động Gateway + với OpenAI đã cấu hình, rồi bật các kênh/Plugin được đóng gói qua chỉnh sửa cấu hình. + - Xác minh khám phá thiết lập để các Plugin có thể tải xuống nhưng chưa cấu hình vắng mặt, + lần sửa chữa doctor đã cấu hình đầu tiên cài đặt rõ ràng từng Plugin có thể tải xuống + bị thiếu, và lần khởi động lại thứ hai không chạy sửa chữa dependency ẩn. - Cũng cài đặt một baseline npm cũ đã biết, bật Telegram trước khi chạy `openclaw update --tag `, và xác minh doctor sau cập nhật của ứng viên - dọn sạch mảnh vụn dependency Plugin cũ mà không cần sửa postinstall phía harness. + dọn sạch mảnh vụn dependency Plugin legacy mà không cần sửa chữa postinstall phía harness. - `pnpm test:parallels:npm-update` - - Chạy smoke cập nhật cài đặt đóng gói native trên các guest Parallels. Mỗi - nền tảng được chọn trước tiên cài package baseline được yêu cầu, sau đó chạy + - Chạy smoke cập nhật cài đặt gói native trên các guest Parallels. Mỗi + nền tảng được chọn trước tiên cài đặt gói baseline được yêu cầu, rồi chạy lệnh `openclaw update` đã cài trong cùng guest và xác minh phiên bản đã cài, - trạng thái cập nhật, độ sẵn sàng của Gateway, và một lượt agent cục bộ. + trạng thái cập nhật, độ sẵn sàng Gateway, và một lượt agent cục bộ. - Dùng `--platform macos`, `--platform windows`, hoặc `--platform linux` khi - lặp trên một guest. Dùng `--json` cho đường dẫn artifact tóm tắt và trạng thái - từng lane. - - Lane OpenAI mặc định dùng `openai/gpt-5.5` cho bằng chứng lượt agent live. - Truyền `--model ` hoặc đặt - `OPENCLAW_PARALLELS_OPENAI_MODEL` khi chủ đích xác thực một model OpenAI khác. - - Bọc các lần chạy cục bộ dài trong timeout máy chủ để các lần kẹt transport Parallels không thể - dùng hết phần còn lại của khoảng thời gian kiểm thử: + lặp trên một guest. Dùng `--json` cho đường dẫn artifact tóm tắt và + trạng thái từng lane. + - Lane OpenAI dùng `openai/gpt-5.5` cho bằng chứng lượt agent trực tiếp theo + mặc định. Truyền `--model ` hoặc đặt + `OPENCLAW_PARALLELS_OPENAI_MODEL` khi cố ý xác thực một model OpenAI khác. + - Bọc các lần chạy cục bộ dài trong timeout máy chủ để các lần treo transport Parallels không thể + tiêu tốn phần còn lại của cửa sổ kiểm thử: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json @@ -273,56 +285,56 @@ gh workflow run package-acceptance.yml --ref main \ - Script ghi log lane lồng nhau dưới `/tmp/openclaw-parallels-npm-update.*`. Kiểm tra `windows-update.log`, `macos-update.log`, hoặc `linux-update.log` - trước khi giả định wrapper bên ngoài bị treo. + trước khi cho rằng wrapper bên ngoài bị treo. - Cập nhật Windows có thể mất 10 đến 15 phút trong doctor sau cập nhật và công việc - cập nhật package trên một guest lạnh; điều đó vẫn khỏe mạnh khi log debug npm - lồng nhau đang tiến triển. + cập nhật gói trên guest lạnh; điều đó vẫn bình thường khi log debug npm lồng nhau + đang tiến triển. - Không chạy wrapper tổng hợp này song song với các lane smoke Parallels macOS, Windows, hoặc Linux riêng lẻ. Chúng dùng chung trạng thái VM và có thể va chạm khi - khôi phục snapshot, phục vụ package, hoặc trạng thái Gateway của guest. - - Bằng chứng sau cập nhật chạy bề mặt Plugin đi kèm bình thường vì + khôi phục snapshot, phục vụ gói, hoặc trạng thái Gateway guest. + - Bằng chứng sau cập nhật chạy bề mặt Plugin được đóng gói thông thường vì các facade capability như speech, tạo ảnh, và hiểu media - được tải qua API runtime đi kèm ngay cả khi chính lượt agent + được tải qua API runtime đóng gói ngay cả khi lượt agent chỉ kiểm tra một phản hồi văn bản đơn giản. - `pnpm openclaw qa aimock` - - Chỉ khởi động server provider AIMock cục bộ để kiểm thử smoke giao thức trực tiếp. + - Chỉ khởi động máy chủ provider AIMock cục bộ cho kiểm thử smoke giao thức trực tiếp. - `pnpm openclaw qa matrix` - - Chạy lane QA live Matrix với một homeserver Tuwunel dùng một lần dựa trên Docker. Chỉ checkout nguồn — cài đặt đóng gói không ship `qa-lab`. - - CLI đầy đủ, catalog profile/kịch bản, biến env, và bố cục artifact: [QA Matrix](/vi/concepts/qa-matrix). + - Chạy lane QA Matrix trực tiếp với homeserver Tuwunel dùng một lần dựa trên Docker. Chỉ source-checkout — các bản cài đặt đóng gói không ship `qa-lab`. + - CLI đầy đủ, catalog profile/kịch bản, env vars, và bố cục artifact: [QA Matrix](/vi/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Chạy lane QA live Telegram với một nhóm riêng tư thật bằng token driver và bot SUT từ env. + - Chạy lane QA Telegram trực tiếp với một nhóm riêng tư thật bằng token bot driver và SUT từ env. - Yêu cầu `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, và `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Id nhóm phải là id chat Telegram dạng số. - - Hỗ trợ `--credential-source convex` cho credentials gom chung được chia sẻ. Mặc định dùng chế độ env, hoặc đặt `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` để chọn dùng lease gom chung. + - Hỗ trợ `--credential-source convex` cho thông tin xác thực pooled dùng chung. Dùng chế độ env theo mặc định, hoặc đặt `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` để chọn dùng pooled leases. - Thoát 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ó artifact mà không có exit code thất bại. + muốn có artifact mà không có mã thoát thất bại. - Yêu cầu hai bot riêng biệt trong cùng nhóm riêng tư, với bot SUT hiển thị username Telegram. - Để quan sát bot-với-bot ổn định, bật Bot-to-Bot Communication Mode trong `@BotFather` cho cả hai bot và đảm bảo bot driver có thể quan sát lưu lượng bot trong nhóm. - - Ghi báo cáo QA Telegram, tóm tắt, và artifact tin nhắn đã quan sát dưới `.artifacts/qa-e2e/...`. Các kịch bản trả lời bao gồm RTT từ yêu cầu gửi của driver đến phản hồi SUT đã quan sát. + - Ghi báo cáo QA Telegram, tóm tắt, và artifact thông điệp đã quan sát trong `.artifacts/qa-e2e/...`. Các kịch bản trả lời bao gồm RTT từ yêu cầu gửi của driver đến phản hồi SUT đã quan sát. -Các lane transport live chia sẻ một contract chuẩn để transport mới không lệch; ma trận bao phủ từng lane nằm trong [Tổng quan QA → Bao phủ transport live](/vi/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` là bộ synthetic suite rộng và không thuộc ma trận đó. +Các lane transport trực tiếp dùng chung một contract tiêu chuẩn để transport mới không bị lệch; ma trận phạm vi từng lane nằm trong [Tổng quan QA → Phạm vi transport trực tiếp](/vi/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` là bộ synthetic rộng và không thuộc ma trận đó. -### Credentials Telegram dùng chung qua Convex (v1) +### Thông tin xác thực Telegram dùng chung qua Convex (v1) Khi bật `--credential-source convex` (hoặc `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) cho `openclaw qa telegram`, QA lab lấy một lease độc quyền từ pool dựa trên Convex, heartbeat -lease đó khi lane đang chạy, và giải phóng lease khi tắt. +lease đó trong khi lane đang chạy, và giải phóng lease khi tắt. -Scaffold dự án Convex tham khảo: +Scaffold dự án Convex tham chiếu: - `qa/convex-credential-broker/` -Biến env bắt buộc: +Env vars bắt buộc: - `OPENCLAW_QA_CONVEX_SITE_URL` (ví dụ `https://your-deployment.convex.site`) -- Một secret cho role đã chọn: +- Một secret cho vai trò đã chọn: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` cho `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` cho `ci` -- Chọn role credential: +- Chọn vai trò thông tin xác thực: - CLI: `--credential-role maintainer|ci` - - Mặc định env: `OPENCLAW_QA_CREDENTIAL_ROLE` (mặc định là `ci` trong CI, nếu không là `maintainer`) + - Mặc định env: `OPENCLAW_QA_CREDENTIAL_ROLE` (mặc định là `ci` trong CI, nếu không thì `maintainer`) -Biến env tùy chọn: +Env vars tùy chọn: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (mặc định `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (mặc định `30000`) @@ -332,12 +344,12 @@ Biến env tùy chọn: - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (trace id tùy chọn) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` cho phép URL Convex `http://` loopback cho phát triển chỉ cục bộ. -`OPENCLAW_QA_CONVEX_SITE_URL` nên dùng `https://` trong vận hành bình thường. +`OPENCLAW_QA_CONVEX_SITE_URL` nên sử dụng `https://` trong hoạt động bình thường. -Các lệnh admin của maintainer (pool add/remove/list) yêu cầu riêng +Các lệnh quản trị dành cho maintainer (pool add/remove/list) yêu cầu riêng `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Trình hỗ trợ CLI cho maintainer: +Các trình hỗ trợ CLI cho maintainer: ```bash pnpm openclaw qa credentials doctor @@ -346,107 +358,107 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Dùng `doctor` trước các lần chạy live để kiểm tra URL site Convex, secret broker, -tiền tố endpoint, thời gian chờ HTTP, và khả năng truy cập admin/list mà không in -giá trị secret. Dùng `--json` để có đầu ra máy đọc được trong script và tiện ích CI. +Sử dụng `doctor` trước các lần chạy live để kiểm tra URL site Convex, bí mật broker, +tiền tố endpoint, thời gian chờ HTTP và khả năng truy cập admin/list mà không in +giá trị bí mật. Sử dụng `--json` để có đầu ra máy đọc được trong script và tiện ích CI. Hợp đồng endpoint mặc định (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Yêu cầu: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Thành công: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Hết tài nguyên/có thể thử lại: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Cạn kiệt/có thể thử lại: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Yêu cầu: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Thành công: `{ status: "ok" }` (hoặc `2xx` rỗng) - `POST /release` - Yêu cầu: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Thành công: `{ status: "ok" }` (hoặc `2xx` rỗng) -- `POST /admin/add` (chỉ secret của maintainer) +- `POST /admin/add` (chỉ bí mật maintainer) - Yêu cầu: `{ kind, actorId, payload, note?, status? }` - Thành công: `{ status: "ok", credential }` -- `POST /admin/remove` (chỉ secret của maintainer) +- `POST /admin/remove` (chỉ bí mật maintainer) - Yêu cầu: `{ credentialId, actorId }` - Thành công: `{ status: "ok", changed, credential }` - - Chặn khi lease đang hoạt động: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (chỉ secret của maintainer) + - Chốt bảo vệ lease đang hoạt động: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (chỉ bí mật maintainer) - Yêu cầu: `{ kind?, status?, includePayload?, limit? }` - Thành công: `{ status: "ok", credentials, count }` Dạng payload cho loại Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` phải là chuỗi id chat Telegram dạng số. +- `groupId` phải là chuỗi id cuộc trò chuyện Telegram dạng số. - `admin/add` xác thực dạng này cho `kind: "telegram"` và từ chối payload sai định dạng. -### Thêm kênh vào QA +### Thêm một kênh vào QA -Kiến trúc và tên scenario-helper cho adapter kênh mới nằm trong [Tổng quan QA → Thêm kênh](/vi/concepts/qa-e2e-automation#adding-a-channel). Mức tối thiểu: triển khai transport runner trên seam host `qa-lab` dùng chung, khai báo `qaRunners` trong manifest plugin, mount dưới dạng `openclaw qa `, và viết scenario trong `qa/scenarios/`. +Kiến trúc và tên trình hỗ trợ kịch bản cho bộ chuyển đổi kênh mới nằm trong [Tổng quan QA → Thêm một kênh](/vi/concepts/qa-e2e-automation#adding-a-channel). Mức tối thiểu: triển khai transport runner trên seam host `qa-lab` dùng chung, khai báo `qaRunners` trong manifest Plugin, mount dưới dạng `openclaw qa `, và viết kịch bản trong `qa/scenarios/`. ## Bộ kiểm thử (chạy ở đâu) -Hãy xem các bộ này là “mức độ chân thực tăng dần” (đồng thời độ chập chờn/chi phí cũng tăng): +Hãy xem các bộ kiểm thử là “mức độ thực tế tăng dần” (đồng thời độ chập chờn/chi phí cũng tăng): -### Unit / integration (mặc định) +### Unit / tích hợp (mặc định) - Lệnh: `pnpm test` -- Cấu hình: các lần chạy không chỉ định mục tiêu dùng tập shard `vitest.full-*.config.ts` và có thể mở rộng shard nhiều project thành cấu hình theo từng project để lập lịch song song -- Tệp: inventory core/unit trong `src/**/*.test.ts`, `packages/**/*.test.ts`, và `test/**/*.test.ts`; kiểm thử unit UI chạy trong shard `unit-ui` chuyên dụng +- Cấu hình: các lần chạy không nhắm mục tiêu dùng bộ shard `vitest.full-*.config.ts` và có thể mở rộng shard đa dự án thành cấu hình theo từng dự án để lập lịch song song +- Tệp: inventory core/unit trong `src/**/*.test.ts`, `packages/**/*.test.ts` và `test/**/*.test.ts`; kiểm thử unit UI chạy trong shard chuyên dụng `unit-ui` - Phạm vi: - - Kiểm thử unit thuần - - Kiểm thử integration trong tiến trình (xác thực gateway, định tuyến, tooling, parsing, cấu hình) - - Regression xác định cho các lỗi đã biết + - Kiểm thử unit thuần túy + - Kiểm thử tích hợp trong tiến trình (xác thực Gateway, định tuyến, tooling, phân tích cú pháp, cấu hình) + - Hồi quy xác định cho lỗi đã biết - Kỳ vọng: - Chạy trong CI - - Không cần key thật + - Không cần khóa thật - Nên nhanh và ổn định - - Kiểm thử resolver và public-surface loader phải chứng minh hành vi fallback rộng của `api.js` và - `runtime-api.js` bằng fixture plugin nhỏ được tạo sinh, không dùng - API nguồn của plugin bundled thật. Việc tải API plugin thật thuộc về - các bộ contract/integration do plugin sở hữu. + - Kiểm thử resolver và bộ nạp bề mặt công khai phải chứng minh hành vi fallback rộng của `api.js` và + `runtime-api.js` bằng fixture Plugin nhỏ được tạo ra, không dùng + API mã nguồn Plugin được đóng gói thật. Việc tải API Plugin thật thuộc về + các bộ hợp đồng/tích hợp do Plugin sở hữu. - + - - `pnpm test` không chỉ định mục tiêu chạy mười hai cấu hình shard nhỏ hơn (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) thay vì một tiến trình root-project native khổng lồ. Điều này giảm RSS đỉnh trên máy tải cao và tránh việc auto-reply/extension làm đói các bộ không liên quan. - - `pnpm test --watch` vẫn dùng đồ thị project `vitest.config.ts` root native, vì vòng lặp watch nhiều shard là không thực tế. - - `pnpm test`, `pnpm test:watch`, và `pnpm test:perf:imports` định tuyến các mục tiêu tệp/thư mục rõ ràng qua các lane theo phạm vi trước, nên `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` tránh phải trả chi phí khởi động toàn bộ root project. - - `pnpm test:changed` mặc định mở rộng các đường dẫn git đã thay đổi thành các lane theo phạm vi rẻ: chỉnh sửa trực tiếp test, tệp `*.test.ts` anh em, ánh xạ nguồn rõ ràng, và dependent trong import-graph cục bộ. Chỉnh sửa config/setup/package không chạy test rộng trừ khi bạn dùng rõ ràng `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` là cổng kiểm tra cục bộ thông minh bình thường cho công việc hẹp. Nó phân loại diff thành core, test core, extensions, test extension, apps, docs, metadata release, tooling Docker live, và tooling, rồi chạy các lệnh typecheck, lint, và guard tương ứng. Nó không chạy kiểm thử Vitest; gọi `pnpm test:changed` hoặc `pnpm test ` rõ ràng để có bằng chứng kiểm thử. Các lần bump phiên bản chỉ metadata release chạy kiểm tra phiên bản/cấu hình/root-dependency có mục tiêu, kèm guard từ chối thay đổi package ngoài trường phiên bản cấp cao nhất. - - Chỉnh sửa harness Docker ACP live chạy kiểm tra tập trung: cú pháp shell cho các script xác thực Docker live và dry-run scheduler Docker live. Thay đổi `package.json` chỉ được bao gồm khi diff giới hạn ở `scripts["test:docker:live-*"]`; chỉnh sửa dependency, export, version, và bề mặt package khác vẫn dùng các guard rộng hơn. - - Kiểm thử unit nhẹ về import từ agents, commands, plugins, helper auto-reply, `plugin-sdk`, và các vùng tiện ích thuần tương tự được định tuyến qua lane `unit-fast`, lane này bỏ qua `test/setup-openclaw-runtime.ts`; các tệp nặng về trạng thái/runtime vẫn ở các lane hiện có. - - Một số tệp nguồn helper `plugin-sdk` và `commands` được chọn cũng ánh xạ các lần chạy changed-mode tới các test anh em rõ ràng trong các lane nhẹ đó, nên chỉnh sửa helper tránh chạy lại toàn bộ bộ nặng cho thư mục đó. - - `auto-reply` có các bucket chuyên dụng cho helper core cấp cao nhất, kiểm thử integration `reply.*` cấp cao nhất, và cây con `src/auto-reply/reply/**`. CI còn chia cây con reply thành các shard agent-runner, dispatch, và commands/state-routing để một bucket nặng về import không sở hữu toàn bộ phần đuôi Node. - - CI PR/main bình thường cố ý bỏ qua sweep batch extension và shard chỉ dành cho release `agentic-plugins`. Full Release Validation dispatch workflow con `Plugin Prerelease` riêng cho các bộ nặng về plugin/extension đó trên release candidate. + - `pnpm test` không nhắm mục tiêu chạy mười hai cấu hình shard nhỏ hơn (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) thay vì một tiến trình dự án gốc native khổng lồ. Cách này giảm RSS đỉnh trên máy nhiều tải và tránh để công việc auto-reply/extension làm thiếu tài nguyên các bộ không liên quan. + - `pnpm test --watch` vẫn dùng đồ thị dự án gốc native `vitest.config.ts`, vì vòng lặp watch đa shard không thực tế. + - `pnpm test`, `pnpm test:watch` và `pnpm test:perf:imports` định tuyến mục tiêu tệp/thư mục rõ ràng qua các lane theo phạm vi trước, nên `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` tránh phải trả chi phí khởi động toàn bộ dự án gốc. + - `pnpm test:changed` mặc định mở rộng các đường dẫn git đã thay đổi thành lane theo phạm vi rẻ: chỉnh sửa kiểm thử trực tiếp, tệp `*.test.ts` cùng cấp, ánh xạ nguồn rõ ràng và phần phụ thuộc đồ thị import cục bộ. Chỉnh sửa config/setup/package không chạy kiểm thử rộng trừ khi bạn dùng rõ ràng `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` là gate kiểm tra cục bộ thông minh bình thường cho công việc hẹp. Nó phân loại diff thành core, kiểm thử core, extensions, kiểm thử extension, ứng dụng, tài liệu, metadata phát hành, tooling Docker live và tooling, sau đó chạy các lệnh typecheck, lint và guard tương ứng. Nó không chạy kiểm thử Vitest; gọi `pnpm test:changed` hoặc `pnpm test ` rõ ràng để có bằng chứng kiểm thử. Các lần bump phiên bản chỉ metadata phát hành chạy kiểm tra phiên bản/cấu hình/phụ thuộc gốc có mục tiêu, với guard từ chối thay đổi package ngoài trường phiên bản cấp cao nhất. + - Chỉnh sửa harness ACP Docker live chạy các kiểm tra tập trung: cú pháp shell cho script xác thực Docker live và dry-run bộ lập lịch Docker live. Thay đổi `package.json` chỉ được bao gồm khi diff giới hạn ở `scripts["test:docker:live-*"]`; các chỉnh sửa phụ thuộc, export, phiên bản và bề mặt package khác vẫn dùng guard rộng hơn. + - Kiểm thử unit import nhẹ từ agents, commands, plugins, trình hỗ trợ auto-reply, `plugin-sdk` và các vùng tiện ích thuần túy tương tự được định tuyến qua lane `unit-fast`, bỏ qua `test/setup-openclaw-runtime.ts`; các tệp có trạng thái/nặng runtime vẫn ở lane hiện có. + - Một số tệp nguồn trình hỗ trợ `plugin-sdk` và `commands` được chọn cũng ánh xạ các lần chạy chế độ changed sang kiểm thử cùng cấp rõ ràng trong các lane nhẹ đó, nên chỉnh sửa helper tránh chạy lại toàn bộ bộ nặng cho thư mục đó. + - `auto-reply` có bucket chuyên dụng cho helper core cấp cao nhất, kiểm thử tích hợp `reply.*` cấp cao nhất và cây con `src/auto-reply/reply/**`. CI còn tách cây con reply thành các shard agent-runner, dispatch và commands/state-routing để một bucket nặng import không sở hữu toàn bộ phần đuôi Node. + - CI PR/main bình thường cố ý bỏ qua sweep batch extension và shard `agentic-plugins` chỉ dành cho phát hành. Full Release Validation dispatch workflow con `Plugin Prerelease` riêng cho các bộ nặng Plugin/extension đó trên ứng viên phát hành. - + - - Khi bạn thay đổi input khám phá message-tool hoặc ngữ cảnh runtime - compaction, hãy giữ cả hai tầng coverage. - - Thêm regression helper tập trung cho các ranh giới định tuyến và chuẩn hóa - thuần. - - Giữ các bộ integration runner nhúng khỏe mạnh: + - Khi bạn thay đổi đầu vào khám phá message-tool hoặc ngữ cảnh runtime compaction, + hãy giữ cả hai mức bao phủ. + - Thêm hồi quy helper tập trung cho các biên định tuyến và chuẩn hóa + thuần túy. + - Giữ các bộ tích hợp embedded runner khỏe mạnh: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, và + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` và `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Các bộ đó xác minh rằng scoped id và hành vi compaction vẫn đi qua - các đường dẫn `run.ts` / `compact.ts` thật; kiểm thử chỉ helper - không đủ thay thế cho các đường dẫn integration đó. + - Các bộ này xác minh rằng scoped id và hành vi compaction vẫn đi + qua các đường dẫn `run.ts` / `compact.ts` thật; kiểm thử chỉ helper + không đủ thay thế cho các đường dẫn tích hợp đó. - + - Cấu hình Vitest cơ sở mặc định là `threads`. - - Cấu hình Vitest dùng chung cố định `isolate: false` và dùng - runner không cô lập trên các root project, e2e, và cấu hình live. - - Lane UI root giữ setup `jsdom` và optimizer của nó, nhưng cũng chạy trên - runner không cô lập dùng chung. + - Cấu hình Vitest dùng chung cố định `isolate: false` và dùng runner + không cô lập trên các dự án gốc, e2e và cấu hình live. + - Lane UI gốc giữ thiết lập `jsdom` và optimizer của nó, nhưng cũng chạy trên + runner dùng chung không cô lập. - Mỗi shard `pnpm test` kế thừa cùng mặc định `threads` + `isolate: false` từ cấu hình Vitest dùng chung. - - `scripts/run-vitest.mjs` mặc định thêm `--no-maglev` cho các tiến trình Node + - `scripts/run-vitest.mjs` mặc định thêm `--no-maglev` cho tiến trình Node con của Vitest để giảm churn biên dịch V8 trong các lần chạy cục bộ lớn. Đặt `OPENCLAW_VITEST_ENABLE_MAGLEV=1` để so sánh với hành vi V8 nguyên bản. @@ -455,25 +467,25 @@ Hãy xem các bộ này là “mức độ chân thực tăng dần” (đồng - - `pnpm changed:lanes` hiển thị diff kích hoạt các lane kiến trúc nào. + - `pnpm changed:lanes` hiển thị diff kích hoạt những lane kiến trúc nào. - Hook pre-commit chỉ định dạng. Nó stage lại các tệp đã định dạng và - không chạy lint, typecheck, hay test. - - Chạy `pnpm check:changed` rõ ràng trước khi bàn giao hoặc push khi bạn - cần cổng kiểm tra cục bộ thông minh. + không chạy lint, typecheck hay kiểm thử. + - Chạy rõ ràng `pnpm check:changed` trước khi bàn giao hoặc push khi bạn + cần gate kiểm tra cục bộ thông minh. - `pnpm test:changed` mặc định định tuyến qua các lane theo phạm vi rẻ. Chỉ dùng `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` khi agent - quyết định một chỉnh sửa harness, config, package, hoặc contract thật sự cần - coverage Vitest rộng hơn. - - `pnpm test:max` và `pnpm test:changed:max` giữ nguyên hành vi định tuyến, + quyết định một chỉnh sửa harness, config, package hoặc hợp đồng thực sự cần + phạm vi Vitest rộng hơn. + - `pnpm test:max` và `pnpm test:changed:max` giữ cùng hành vi định tuyến, chỉ với giới hạn worker cao hơn. - - Tự động điều chỉnh worker cục bộ cố ý thận trọng và giảm tải - khi load average của host đã cao, nên mặc định nhiều lần chạy - Vitest đồng thời gây ít thiệt hại hơn. - - Cấu hình Vitest cơ sở đánh dấu các project/tệp cấu hình là - `forceRerunTriggers` để rerun changed-mode vẫn đúng khi dây nối test - thay đổi. - - Cấu hình giữ `OPENCLAW_VITEST_FS_MODULE_CACHE` bật trên các host được hỗ trợ; - đặt `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` nếu bạn muốn + - Tự động co giãn worker cục bộ cố ý thận trọng và giảm xuống + khi load average của host đã cao, nên nhiều lần chạy Vitest đồng thời + mặc định gây ít thiệt hại hơn. + - Cấu hình Vitest cơ sở đánh dấu các dự án/tệp cấu hình là + `forceRerunTriggers` để các lần chạy lại chế độ changed vẫn đúng khi + wiring kiểm thử thay đổi. + - Cấu hình giữ `OPENCLAW_VITEST_FS_MODULE_CACHE` bật trên các + host được hỗ trợ; đặt `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` nếu bạn muốn một vị trí cache rõ ràng cho profiling trực tiếp. @@ -482,26 +494,26 @@ Hãy xem các bộ này là “mức độ chân thực tăng dần” (đồng - `pnpm test:perf:imports` bật báo cáo thời lượng import của Vitest cùng đầu ra phân rã import. - - `pnpm test:perf:imports:changed` giới hạn cùng góc nhìn profiling đó vào + - `pnpm test:perf:imports:changed` giới hạn cùng góc nhìn profiling vào các tệp đã thay đổi kể từ `origin/main`. - Dữ liệu thời gian shard được ghi vào `.artifacts/vitest-shard-timings.json`. - Các lần chạy toàn cấu hình dùng đường dẫn cấu hình làm key; shard CI - theo include-pattern nối thêm tên shard để shard đã lọc có thể được theo dõi + Các lần chạy toàn bộ cấu hình dùng đường dẫn cấu hình làm khóa; shard CI theo include-pattern + nối thêm tên shard để các shard đã lọc có thể được theo dõi riêng. - - Khi một hot test vẫn tốn phần lớn thời gian ở import khởi động, - hãy giữ dependency nặng sau seam cục bộ hẹp `*.runtime.ts` và + - Khi một kiểm thử nóng vẫn dành phần lớn thời gian cho import khởi động, + giữ phụ thuộc nặng phía sau một seam `*.runtime.ts` cục bộ hẹp và mock trực tiếp seam đó thay vì deep-import helper runtime chỉ để truyền chúng qua `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` so sánh - `test:changed` đã định tuyến với đường dẫn root-project native cho diff - đã commit đó và in wall time cùng RSS tối đa trên macOS. - - `pnpm test:perf:changed:bench -- --worktree` benchmark cây hiện tại - đang bẩn bằng cách định tuyến danh sách tệp đã thay đổi qua - `scripts/test-projects.mjs` và cấu hình Vitest root. + `test:changed` đã định tuyến với đường dẫn dự án gốc native cho diff đã commit đó + và in thời gian thực cùng RSS tối đa trên macOS. + - `pnpm test:perf:changed:bench -- --worktree` benchmark cây dirty hiện tại + bằng cách định tuyến danh sách tệp đã thay đổi qua + `scripts/test-projects.mjs` và cấu hình Vitest gốc. - `pnpm test:perf:profile:main` ghi profile CPU main-thread cho - overhead khởi động và transform của Vitest/Vite. - - `pnpm test:perf:profile:runner` ghi profile CPU+heap của runner cho - bộ unit với parallelism theo tệp bị tắt. + chi phí khởi động và transform của Vitest/Vite. + - `pnpm test:perf:profile:runner` ghi profile CPU+heap runner cho + bộ unit khi tắt song song hóa theo tệp. @@ -509,258 +521,253 @@ Hãy xem các bộ này là “mức độ chân thực tăng dần” (đồng ### Stability (gateway) - Lệnh: `pnpm test:stability:gateway` -- Cấu hình: `vitest.gateway.config.ts`, bị ép dùng một worker +- Cấu hình: `vitest.gateway.config.ts`, ép dùng một worker - Phạm vi: - - Khởi động một Gateway loopback thật với diagnostics mặc định được bật - - Đẩy churn message gateway, memory, và large-payload tổng hợp qua đường dẫn sự kiện diagnostic + - Khởi động một Gateway loopback thật với chẩn đoán được bật mặc định + - Đẩy churn thông điệp gateway, bộ nhớ và payload lớn tổng hợp qua đường dẫn sự kiện chẩn đoán - Truy vấn `diagnostics.stability` qua Gateway WS RPC - - Bao phủ helper lưu bền bundle ổn định diagnostic - - Khẳng định recorder vẫn được giới hạn, mẫu RSS tổng hợp nằm dưới ngân sách áp lực, và độ sâu hàng đợi theo phiên thoát về 0 + - Bao phủ các helper lưu bền bundle stability chẩn đoán + - Khẳng định recorder vẫn có giới hạn, mẫu RSS tổng hợp nằm dưới ngân sách áp lực và độ sâu hàng đợi theo phiên thoát về 0 - Kỳ vọng: - - An toàn cho CI và không cần key - - Lane hẹp cho theo dõi stability-regression, không phải thay thế cho toàn bộ bộ Gateway + - An toàn cho CI và không cần khóa + - Lane hẹp để theo dõi hồi quy stability, không thay thế cho toàn bộ bộ Gateway ### E2E (gateway smoke) - Lệnh: `pnpm test:e2e` - Cấu hình: `vitest.e2e.config.ts` -- Tệp: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`, và các kiểm thử E2E Plugin đóng gói kèm trong `extensions/` -- Mặc định lúc chạy: - - Dùng Vitest `threads` với `isolate: false`, khớp với phần còn lại của repo. - - Dùng worker thích ứng (CI: tối đa 2, cục bộ: mặc định 1). - - Mặc định chạy ở chế độ im lặng để giảm chi phí I/O trên console. +- Tệp: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`, và các kiểm thử E2E của Plugin đi kèm trong `extensions/` +- Mặc định thời gian chạy: + - Sử dụng Vitest `threads` với `isolate: false`, khớp với phần còn lại của repo. + - Sử dụng worker thích ứng (CI: tối đa 2, cục bộ: mặc định 1). + - Chạy ở chế độ im lặng theo mặc định để giảm chi phí I/O console. - Ghi đè hữu ích: - `OPENCLAW_E2E_WORKERS=` để ép số lượng worker (giới hạn tối đa 16). - `OPENCLAW_E2E_VERBOSE=1` để bật lại đầu ra console chi tiết. - Phạm vi: - - Hành vi end-to-end của gateway nhiều instance - - Các bề mặt WebSocket/HTTP, ghép đôi node, và mạng nặng hơn + - Hành vi Gateway đầu-cuối nhiều phiên bản + - Bề mặt WebSocket/HTTP, ghép cặp node và mạng nặng hơn - Kỳ vọng: - Chạy trong CI (khi được bật trong pipeline) - - Không cần khóa thật - - Nhiều phần chuyển động hơn kiểm thử đơn vị (có thể chậm hơn) + - Không yêu cầu khóa thật + - Nhiều thành phần chuyển động hơn kiểm thử đơn vị (có thể chậm hơn) -### E2E: kiểm thử smoke backend OpenShell +### E2E: kiểm thử khói backend OpenShell - Lệnh: `pnpm test:e2e:openshell` - Tệp: `extensions/openshell/src/backend.e2e.test.ts` - Phạm vi: - - Khởi động một gateway OpenShell cô lập trên host qua Docker - - Tạo sandbox từ một Dockerfile cục bộ tạm thời - - Thực thi backend OpenShell của OpenClaw qua `sandbox ssh-config` thật + exec SSH - - Xác minh hành vi hệ thống tệp remote-canonical thông qua cầu nối fs của sandbox + - Khởi động một Gateway OpenShell cô lập trên host qua Docker + - Tạo một sandbox từ Dockerfile cục bộ tạm thời + - Kiểm tra backend OpenShell của OpenClaw qua `sandbox ssh-config` thật + thực thi SSH + - Xác minh hành vi hệ thống tệp chuẩn hóa theo remote thông qua cầu nối sandbox fs - Kỳ vọng: - - Chỉ chạy khi chủ động bật; không thuộc lượt chạy `pnpm test:e2e` mặc định - - Cần CLI `openshell` cục bộ cùng một Docker daemon hoạt động - - Dùng `HOME` / `XDG_CONFIG_HOME` cô lập, rồi hủy gateway kiểm thử và sandbox + - Chỉ chạy khi chọn tham gia; không thuộc lần chạy `pnpm test:e2e` mặc định + - Yêu cầu CLI `openshell` cục bộ cộng với daemon Docker hoạt động + - Sử dụng `HOME` / `XDG_CONFIG_HOME` cô lập, sau đó hủy Gateway kiểm thử và sandbox - Ghi đè hữu ích: - `OPENCLAW_E2E_OPENSHELL=1` để bật kiểm thử khi chạy thủ công bộ e2e rộng hơn - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` để trỏ tới binary CLI hoặc script wrapper không mặc định + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` để trỏ tới binary CLI không mặc định hoặc script wrapper ### Live (provider thật + model thật) - Lệnh: `pnpm test:live` - Cấu hình: `vitest.live.config.ts` -- Tệp: `src/**/*.live.test.ts`, `test/**/*.live.test.ts`, và các kiểm thử live Plugin đóng gói kèm trong `extensions/` -- Mặc định: được `pnpm test:live` **bật** (đặt `OPENCLAW_LIVE_TEST=1`) +- Tệp: `src/**/*.live.test.ts`, `test/**/*.live.test.ts`, và các kiểm thử live của Plugin đi kèm trong `extensions/` +- Mặc định: **được bật** bởi `pnpm test:live` (đặt `OPENCLAW_LIVE_TEST=1`) - Phạm vi: - “Provider/model này có thực sự hoạt động _hôm nay_ với thông tin xác thực thật không?” - - Bắt các thay đổi định dạng provider, điểm lạ khi gọi tool, vấn đề xác thực, và hành vi giới hạn tốc độ + - Phát hiện thay đổi định dạng provider, đặc thù gọi công cụ, vấn đề xác thực và hành vi giới hạn tốc độ - Kỳ vọng: - - Theo thiết kế không ổn định cho CI (mạng thật, chính sách provider thật, hạn ngạch, sự cố) + - Theo thiết kế không ổn định trong CI (mạng thật, chính sách provider thật, hạn ngạch, sự cố ngừng dịch vụ) - Tốn tiền / dùng giới hạn tốc độ - Ưu tiên chạy các tập con đã thu hẹp thay vì “mọi thứ” -- Các lượt chạy live source `~/.profile` để lấy các khóa API còn thiếu. -- Theo mặc định, các lượt chạy live vẫn cô lập `HOME` và sao chép vật liệu cấu hình/xác thực vào home kiểm thử tạm thời để fixture đơn vị không thể sửa `~/.openclaw` thật của bạn. +- Các lần chạy live nạp `~/.profile` để lấy các API key bị thiếu. +- Theo mặc định, các lần chạy live vẫn cô lập `HOME` và sao chép vật liệu cấu hình/xác thực vào home kiểm thử tạm thời để fixture đơn vị không thể sửa đổi `~/.openclaw` thật của bạn. - Chỉ đặt `OPENCLAW_LIVE_USE_REAL_HOME=1` khi bạn chủ ý cần kiểm thử live dùng thư mục home thật của mình. -- `pnpm test:live` hiện mặc định sang chế độ yên tĩnh hơn: giữ đầu ra tiến trình `[live] ...`, nhưng chặn thông báo `~/.profile` bổ sung và tắt log bootstrap gateway/tiếng ồn Bonjour. Đặt `OPENCLAW_LIVE_TEST_QUIET=0` nếu bạn muốn lấy lại toàn bộ log khởi động. -- Xoay vòng khóa API (theo provider): đặt `*_API_KEYS` với định dạng dấu phẩy/chấm phẩy hoặc `*_API_KEY_1`, `*_API_KEY_2` (ví dụ `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) hoặc ghi đè theo từng live qua `OPENCLAW_LIVE_*_KEY`; kiểm thử sẽ thử lại khi có phản hồi giới hạn tốc độ. -- Đầu ra tiến trình/Heartbeat: - - Các bộ live hiện phát dòng tiến trình ra stderr để các lệnh gọi provider dài vẫn hiển thị là đang hoạt động ngay cả khi Vitest console capture yên tĩnh. - - `vitest.live.config.ts` tắt chặn console của Vitest để các dòng tiến trình provider/gateway được stream ngay trong lúc chạy live. +- `pnpm test:live` hiện mặc định dùng chế độ yên tĩnh hơn: giữ đầu ra tiến độ `[live] ...`, nhưng ẩn thông báo `~/.profile` bổ sung và tắt log bootstrap Gateway/Bonjour chatter. Đặt `OPENCLAW_LIVE_TEST_QUIET=0` nếu bạn muốn bật lại toàn bộ log khởi động. +- Xoay vòng API key (theo provider): đặt `*_API_KEYS` với định dạng dấu phẩy/dấu chấm phẩy hoặc `*_API_KEY_1`, `*_API_KEY_2` (ví dụ `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) hoặc ghi đè theo live qua `OPENCLAW_LIVE_*_KEY`; kiểm thử sẽ thử lại khi có phản hồi giới hạn tốc độ. +- Đầu ra tiến độ/heartbeat: + - Các bộ live hiện phát dòng tiến độ tới stderr để những lệnh gọi provider dài vẫn hiển thị đang hoạt động ngay cả khi Vitest console capture im lặng. + - `vitest.live.config.ts` tắt chặn console của Vitest để các dòng tiến độ provider/Gateway được stream ngay trong các lần chạy live. - Điều chỉnh heartbeat model trực tiếp bằng `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Điều chỉnh heartbeat gateway/probe bằng `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Điều chỉnh heartbeat Gateway/probe bằng `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Tôi nên chạy bộ nào? Dùng bảng quyết định này: -- Sửa logic/kiểm thử: chạy `pnpm test` (và `pnpm test:coverage` nếu bạn đã thay đổi nhiều) -- Chạm tới mạng gateway / giao thức WS / ghép đôi: thêm `pnpm test:e2e` -- Gỡ lỗi “bot của tôi đang down” / lỗi theo provider / gọi tool: chạy `pnpm test:live` đã thu hẹp +- Chỉnh sửa logic/kiểm thử: chạy `pnpm test` (và `pnpm test:coverage` nếu bạn thay đổi nhiều) +- Chạm tới mạng Gateway / giao thức WS / ghép cặp: thêm `pnpm test:e2e` +- Gỡ lỗi “bot của tôi bị down” / lỗi riêng theo provider / gọi công cụ: chạy một `pnpm test:live` đã thu hẹp ## Kiểm thử live (chạm mạng) -Đối với ma trận model live, smoke backend CLI, smoke ACP, harness app-server -Codex, và tất cả kiểm thử live của media-provider (Deepgram, BytePlus, ComfyUI, hình ảnh, -nhạc, video, media harness) — cùng xử lý thông tin xác thực cho các lượt chạy live — xem -[Kiểm thử các bộ live](/vi/help/testing-live). Đối với danh sách kiểm tra chuyên biệt cho cập nhật và -xác thực Plugin, xem -[Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins). +Đối với ma trận model live, kiểm thử khói backend CLI, kiểm thử khói ACP, harness máy chủ ứng dụng Codex, và tất cả kiểm thử live media-provider (Deepgram, BytePlus, ComfyUI, hình ảnh, âm nhạc, video, media harness) — cùng với xử lý thông tin xác thực cho các lần chạy live — xem [Kiểm thử các bộ live](/vi/help/testing-live). Đối với danh sách kiểm tra cập nhật và xác thực Plugin chuyên dụng, xem [Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins). -## Runner Docker (kiểm tra tùy chọn "hoạt động trên Linux") +## Runner Docker (kiểm tra "hoạt động trên Linux" tùy chọn) Các runner Docker này chia thành hai nhóm: -- Runner model live: `test:docker:live-models` và `test:docker:live-gateway` chỉ chạy tệp live profile-key tương ứng trong image Docker của repo (`src/agents/models.profiles.live.test.ts` và `src/gateway/gateway-models.profiles.live.test.ts`), mount thư mục cấu hình cục bộ và workspace của bạn (và source `~/.profile` nếu đã mount). Các entrypoint cục bộ tương ứng là `test:live:models-profiles` và `test:live:gateway-profiles`. -- Runner live Docker mặc định dùng giới hạn smoke nhỏ hơn để một lượt quét Docker đầy đủ vẫn thực tế: +- Runner model live: `test:docker:live-models` và `test:docker:live-gateway` chỉ chạy tệp live profile-key tương ứng trong image Docker của repo (`src/agents/models.profiles.live.test.ts` và `src/gateway/gateway-models.profiles.live.test.ts`), mount thư mục cấu hình cục bộ và workspace của bạn (và source `~/.profile` nếu được mount). Các entrypoint cục bộ tương ứng là `test:live:models-profiles` và `test:live:gateway-profiles`. +- Runner Docker live mặc định dùng giới hạn smoke nhỏ hơn để một lượt quét Docker đầy đủ vẫn thực tế: `test:docker:live-models` mặc định là `OPENCLAW_LIVE_MAX_MODELS=12`, và `test:docker:live-gateway` mặc định là `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, và - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Ghi đè các biến môi trường đó khi bạn - chủ ý muốn lượt quét lớn hơn, toàn diện hơn. -- `test:docker:all` build image Docker live một lần qua `test:docker:live-build`, đóng gói OpenClaw một lần dưới dạng tarball npm thông qua `scripts/package-openclaw-for-docker.mjs`, rồi build/tái sử dụng hai image `scripts/e2e/Dockerfile`. Image trần chỉ là runner Node/Git cho các lane cài đặt/cập nhật/phụ thuộc Plugin; các lane đó mount tarball đã build sẵn. Image chức năng cài cùng tarball đó vào `/app` cho các lane chức năng ứng dụng đã build. Đị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`; `scripts/test-docker-all.mjs` thực thi kế hoạch đã chọn. Phần tổng hợp dùng bộ lập lịch cục bộ có trọng số: `OPENCLAW_DOCKER_ALL_PARALLELISM` kiểm soát slot tiến trình, trong khi các giới hạn tài nguyên ngăn lane live nặng, npm-install, và nhiều dịch vụ cùng khởi động một lúc. Nếu một lane đơn lẻ nặng hơn các giới hạn đang hoạt động, bộ lập lịch vẫn có thể khởi động lane đó khi pool trống rồi giữ lane chạy một mình cho đến khi có lại dung lượng. Mặc định là 10 slot, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, và `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; chỉ tinh chỉnh `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` hoặc `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` khi host Docker có thêm dư địa. Runner mặc định thực hiện preflight Docker, xóa container OpenClaw E2E cũ, in trạng thái mỗi 30 giây, lưu thời lượng lane thành công trong `.artifacts/docker-tests/lane-timings.json`, và dùng các thời lượng đó để bắt đầu lane dài hơn trước trong các lượt chạy sau. Dùng `OPENCLAW_DOCKER_ALL_DRY_RUN=1` để in manifest lane có trọng số mà không build hoặc chạy Docker, hoặc `node scripts/test-docker-all.mjs --plan-json` để in kế hoạch CI cho các lane đã chọn, nhu cầu package/image, và thông tin xác thực. -- `Package Acceptance` là gate package gốc GitHub cho câu hỏi "tarball có thể cài đặt này có hoạt động như một sản phẩm không?" Nó phân giải một package ứng viên từ `source=npm`, `source=ref`, `source=url`, hoặc `source=artifact`, tải lên dưới tên `package-under-test`, rồi chạy các lane Docker E2E tái sử dụng với đúng tarball đó thay vì đóng gói lại ref đã chọn. Profile được sắp theo độ rộng: `smoke`, `package`, `product`, và `full`. Xem [Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins) để biết hợp đồng package/cập nhật/Plugin, ma trận sống sót sau nâng cấp đã phát hành, mặc định phát hành, và phân loại lỗi. -- Kiểm tra build và phát hành chạy `scripts/check-cli-bootstrap-imports.mjs` sau tsdown. Guard duyệt đồ thị build tĩnh từ `dist/entry.js` và `dist/cli/run-main.js` và thất bại nếu phần khởi động trước dispatch import các phụ thuộc package như Commander, prompt UI, undici, hoặc logging trước khi dispatch lệnh; nó cũng giữ chunk chạy gateway đóng gói dưới ngân sách và từ chối static import của các đường dẫn gateway nguội đã biết. Smoke CLI đã đóng gói cũng bao phủ root help, onboard help, doctor help, status, schema cấu hình, và một lệnh liệt kê model. -- Tương thích legacy của Package Acceptance bị giới hạn ở `2026.4.25` (bao gồm `2026.4.25-beta.*`). Qua mốc đó, harness chỉ dung thứ các khoảng trống metadata package đã phát hành: các mục kho QA private bị lược bỏ, thiếu `gateway install --wrapper`, thiếu tệp patch trong fixture git sinh từ tarball, thiếu `update.channel` đã lưu, vị trí install-record Plugin legacy, thiếu lưu install-record marketplace, và di trú metadata cấu hình trong lúc `plugins update`. Với package sau `2026.4.25`, các đường dẫn đó là lỗi nghiêm ngặt. -- Runner smoke container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix`, và `test:docker:config-reload` khởi động một hoặc nhiều container thật và xác minh các đường dẫn tích hợp cấp cao hơn. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Ghi đè các env var đó khi bạn + chủ ý muốn quét toàn diện lớn hơn. +- `test:docker:all` xây dựng image Docker live một lần qua `test:docker:live-build`, đóng gói OpenClaw một lần thành tarball npm thông qua `scripts/package-openclaw-for-docker.mjs`, rồi xây dựng/tái sử dụng hai image `scripts/e2e/Dockerfile`. Image bare chỉ là runner Node/Git cho các lane cài đặt/cập nhật/phụ thuộc Plugin; các lane đó mount tarball đã dựng sẵn. Image functional cài cùng tarball vào `/app` cho các lane chức năng ứng dụng đã build. Đị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`; `scripts/test-docker-all.mjs` thực thi kế hoạch đã chọn. Tổng hợp sử dụng bộ lập lịch cục bộ có trọng số: `OPENCLAW_DOCKER_ALL_PARALLELISM` điều khiển slot tiến trình, còn giới hạn tài nguyên ngăn các lane live nặng, npm-install và multi-service cùng khởi động một lúc. Nếu một lane đơn lẻ nặng hơn giới hạn đang hoạt động, bộ lập lịch vẫn có thể khởi động lane đó khi pool trống rồi giữ nó chạy một mình cho đến khi lại có dung lượng. Mặc định là 10 slot, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, và `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; chỉ điều chỉnh `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` hoặc `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` khi host Docker có thêm dư địa. Runner thực hiện preflight Docker theo mặc định, xóa các container OpenClaw E2E cũ, in trạng thái mỗi 30 giây, lưu thời gian lane thành công trong `.artifacts/docker-tests/lane-timings.json`, và dùng các thời gian đó để khởi động những lane dài hơn trước trong các lần chạy sau. Dùng `OPENCLAW_DOCKER_ALL_DRY_RUN=1` để in manifest lane có trọng số mà không build hoặc chạy Docker, hoặc `node scripts/test-docker-all.mjs --plan-json` để in kế hoạch CI cho các lane đã chọn, nhu cầu package/image và thông tin xác thực. +- `Package Acceptance` là cổng package gốc GitHub cho "tarball cài đặt được này có hoạt động như một sản phẩm không?" Nó phân giải một package ứng viên từ `source=npm`, `source=ref`, `source=url`, hoặc `source=artifact`, tải nó lên dưới dạng `package-under-test`, rồi chạy các lane Docker E2E tái sử dụng với đúng tarball đó thay vì đóng gói lại ref đã chọn. Profile được sắp theo độ rộng: `smoke`, `package`, `product`, và `full`. Xem [Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins) để biết hợp đồng package/cập nhật/Plugin, ma trận sống sót sau nâng cấp đã phát hành, mặc định phát hành và phân loại lỗi. +- Kiểm tra build và phát hành chạy `scripts/check-cli-bootstrap-imports.mjs` sau tsdown. Guard duyệt đồ thị build tĩnh từ `dist/entry.js` và `dist/cli/run-main.js` và thất bại nếu khởi động trước dispatch import các phụ thuộc package như Commander, prompt UI, undici hoặc logging trước khi dispatch lệnh; nó cũng giữ chunk chạy Gateway đi kèm trong ngân sách và từ chối import tĩnh của các đường dẫn Gateway lạnh đã biết. Kiểm thử khói CLI đã đóng gói cũng bao phủ root help, onboard help, doctor help, status, config schema và một lệnh liệt kê model. +- Tương thích kế thừa của Package Acceptance được giới hạn ở `2026.4.25` (bao gồm `2026.4.25-beta.*`). Qua mốc đó, harness chỉ dung thứ các khoảng trống metadata của package đã phát hành: mục QA inventory riêng tư bị bỏ qua, thiếu `gateway install --wrapper`, thiếu tệp patch trong fixture git lấy từ tarball, thiếu `update.channel` được lưu giữ, vị trí install-record Plugin kế thừa, thiếu lưu giữ install-record marketplace và di chuyển metadata cấu hình trong `plugins update`. Với các package sau `2026.4.25`, các đường dẫn đó là lỗi nghiêm ngặt. +- Runner kiểm thử khói container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix`, và `test:docker:config-reload` khởi động một hoặc nhiều container thật và xác minh các đường dẫn tích hợp cấp cao hơn. -Các runner Docker model live cũng chỉ bind-mount các home xác thực CLI cần thiết (hoặc tất cả các home được hỗ trợ khi lượt chạy không được thu hẹp), rồi sao chép chúng vào home container trước khi chạy để OAuth của CLI bên ngoài có thể làm mới token mà không sửa kho xác thực trên host: +Các runner Docker model live cũng chỉ bind-mount các CLI auth home cần thiết (hoặc tất cả các home được hỗ trợ khi lần chạy không bị thu hẹp), rồi sao chép chúng vào home container trước khi chạy để OAuth CLI bên ngoài có thể làm mới token mà không sửa đổi kho auth của host: -- Mô hình trực tiếp: `pnpm test:docker:live-models` (tập lệnh: `scripts/test-live-models-docker.sh`) -- Kiểm thử smoke liên kết ACP: `pnpm test:docker:live-acp-bind` (tập lệnh: `scripts/test-live-acp-bind-docker.sh`; mặc định bao phủ Claude, Codex và Gemini, với phạm vi bao phủ Droid/OpenCode nghiêm ngặt qua `pnpm test:docker:live-acp-bind:droid` và `pnpm test:docker:live-acp-bind:opencode`) -- Kiểm thử smoke backend CLI: `pnpm test:docker:live-cli-backend` (tập lệnh: `scripts/test-live-cli-backend-docker.sh`) -- Kiểm thử smoke bộ khai thác app-server Codex: `pnpm test:docker:live-codex-harness` (tập lệnh: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + tác nhân dev: `pnpm test:docker:live-gateway` (tập lệnh: `scripts/test-live-gateway-models-docker.sh`) -- Kiểm thử smoke khả năng quan sát: `pnpm qa:otel:smoke` là một làn kiểm tra source-checkout QA riêng tư. Làn này cố ý không thuộc các làn phát hành Docker của gói vì tarball npm bỏ qua QA Lab. -- Kiểm thử smoke trực tiếp Open WebUI: `pnpm test:docker:openwebui` (tập lệnh: `scripts/e2e/openwebui-docker.sh`) -- Trình hướng dẫn onboarding (TTY, scaffolding đầy đủ): `pnpm test:docker:onboard` (tập lệnh: `scripts/e2e/onboard-docker.sh`) -- Kiểm thử smoke onboarding/kênh/tác nhân bằng tarball Npm: `pnpm test:docker:npm-onboard-channel-agent` cài đặt tarball OpenClaw đã đóng gói ở phạm vi toàn cục trong Docker, cấu hình OpenAI qua onboarding env-ref cộng với Telegram theo mặc định, chạy doctor, rồi chạy một lượt tác nhân OpenAI được mô phỏng. Tái sử dụng tarball dựng sẵn bằng `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, bỏ qua bản dựng host bằng `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, hoặc chuyển kênh bằng `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Kiểm thử smoke chuyển kênh cập nhật: `pnpm test:docker:update-channel-switch` cài đặt tarball OpenClaw đã đóng gói ở phạm vi toàn cục trong Docker, chuyển từ gói `stable` sang git `dev`, xác minh kênh đã lưu và plugin sau cập nhật hoạt động, rồi chuyển lại về gói `stable` và kiểm tra trạng thái cập nhật. -- Kiểm thử smoke khả năng sống sót sau nâng cấp: `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 có tác nhân, cấu hình kênh, danh sách cho phép plugin, trạng thái phụ thuộc plugin cũ, và các tệp workspace/session hiện có. Lệnh chạy cập nhật gói cộng với doctor không tương tác mà không cần khóa provider hoặc kênh trực tiếp, sau đó khởi động Gateway loopback và kiểm tra việc giữ nguyên cấu hình/trạng thái cùng ngân sách khởi động/trạng thái. -- Kiểm thử smoke khả năng sống sót sau nâng cấp bản đã phát hành: `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ế, cấu hình baseline đó bằng công thức lệnh được nhúng sẵn, xác thực cấu hình thu được, cập nhật bản cài đặt đã phát hành đó lên tarball ứng viên, chạy doctor không tương tác, ghi `.artifacts/upgrade-survivor/summary.json`, rồi khởi động Gateway loopback và kiểm tra các intent đã cấu hình, việc giữ nguyên trạng thái, khởi động, `/healthz`, `/readyz`, và ngân sách trạng thái RPC. Ghi đè một baseline bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, yêu cầu bộ lập lịch tổng hợp mở rộng các baseline chính xác bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` như `all-since-2026.4.23`, và mở rộng các fixture dạng issue bằng `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` như `reported-issues`; tập reported-issues bao gồm `configured-plugin-installs` để tự động sửa cài đặt Plugin OpenClaw bên ngoài. 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`. -- Kiểm thử smoke ngữ cảnh runtime session: `pnpm test:docker:session-runtime-context` xác minh việc lưu bền transcript ngữ cảnh runtime ẩn cùng với sửa chữa doctor cho các nhánh prompt-rewrite bị trùng lặp bị ảnh hưởng. -- Kiểm thử smoke cài đặt toàn cục Bun: `bash scripts/e2e/bun-global-install-smoke.sh` đóng gói cây hiện tại, cài đặt bằng `bun install -g` trong một home cô lập, và xác minh `openclaw infer image providers --json` trả về các provider hình ảnh đi kèm thay vì treo. Tái sử dụng tarball dựng sẵn bằng `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, bỏ qua bản dựng host bằng `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, hoặc sao chép `dist/` từ một image Docker đã dựng bằng `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Kiểm thử smoke Docker trình cài đặt: `bash scripts/test-install-sh-docker.sh` chia sẻ một cache npm giữa các container root, update và direct-npm của nó. Kiểm thử smoke cập nhật mặc định dùng npm `latest` làm baseline stable trước khi nâng cấp lên tarball ứng viên. Ghi đè bằng `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` khi chạy cục bộ, hoặc bằng input `update_baseline_version` của workflow Install Smoke trên GitHub. Các kiểm tra trình cài đặt không phải root giữ một cache npm cô lập để các mục cache do root sở hữu không che khuất hành vi cài đặt cục bộ của người dùng. Đặt `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` để tái sử dụng cache root/update/direct-npm giữa các lần chạy lại cục bộ. -- Install Smoke CI bỏ qua cập nhật toàn cục direct-npm trùng lặp bằng `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; chạy tập lệnh cục bộ không có env đó khi cần phạm vi bao phủ `npm install -g` trực tiếp. -- Kiểm thử smoke CLI xóa workspace dùng chung của tác nhân: `pnpm test:docker:agents-delete-shared-workspace` (tập lệnh: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) mặc định dựng image Dockerfile gốc, gieo hai tác nhân với một workspace trong home container cô lập, chạy `agents delete --json`, và xác minh JSON hợp lệ cùng hành vi giữ lại workspace. Tái sử dụng image install-smoke bằng `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Mạng Gateway (hai container, xác thực WS + health): `pnpm test:docker:gateway-network` (tập lệnh: `scripts/e2e/gateway-network-docker.sh`) -- Kiểm thử smoke snapshot CDP trình duyệt: `pnpm test:docker:browser-cdp-snapshot` (tập lệnh: `scripts/e2e/browser-cdp-snapshot-docker.sh`) dựng image E2E nguồn cộng với một lớp Chromium, khởi động Chromium với CDP thô, chạy `browser doctor --deep`, và xác minh snapshot vai trò CDP bao phủ URL liên kết, phần tử có thể nhấp được nâng cấp theo con trỏ, tham chiếu iframe và metadata khung. -- Hồi quy reasoning tối thiểu cho OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (tập lệnh: `scripts/e2e/openai-web-search-minimal-docker.sh`) chạy một máy chủ OpenAI được mô phỏng qua Gateway, xác minh `web_search` nâng `reasoning.effort` từ `minimal` lên `low`, rồi buộc schema provider từ chối và kiểm tra chi tiết thô xuất hiện trong nhật ký Gateway. -- Cầu nối kênh MCP (Gateway đã gieo + cầu nối stdio + kiểm thử smoke notification-frame Claude thô): `pnpm test:docker:mcp-channels` (tập lệnh: `scripts/e2e/mcp-channels-docker.sh`) -- Công cụ MCP gói Pi (máy chủ MCP stdio thật + kiểm thử smoke allow/deny hồ sơ Pi nhúng): `pnpm test:docker:pi-bundle-mcp-tools` (tập lệnh: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Dọn dẹp MCP Cron/subagent (Gateway thật + tháo dỡ tiến trình con MCP stdio sau các lượt chạy cron cô lập và subagent một lần): `pnpm test:docker:cron-mcp-cleanup` (tập lệnh: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (kiểm thử smoke cài đặt/cập nhật cho đường dẫn cục bộ, `file:`, registry npm với phụ thuộc được hoist, ref git di chuyển, ClawHub kitchen-sink, cập nhật marketplace, và bật/kiểm tra gói Claude): `pnpm test:docker:plugins` (tập lệnh: `scripts/e2e/plugins-docker.sh`) - Đặt `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` để bỏ qua khối ClawHub, hoặc ghi đè cặp gói/runtime kitchen-sink mặc định bằng `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` và `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Khi không có `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, kiểm thử dùng máy chủ fixture ClawHub cục bộ khép kín. -- Kiểm thử smoke cập nhật Plugin không đổi: `pnpm test:docker:plugin-update` (tập lệnh: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Kiểm thử smoke ma trận vòng đời Plugin: `pnpm test:docker:plugin-lifecycle-matrix` cài đặt tarball OpenClaw đã đóng gói trong một container trống, cài đặt một plugin npm, bật/tắt enable/disable, nâng cấp và hạ cấp plugin đó qua registry npm cục bộ, xóa mã đã cài đặt, rồi xác minh uninstall vẫn xóa trạng thái cũ trong khi ghi nhật ký chỉ số RSS/CPU cho từng pha vòng đời. -- Kiểm thử smoke metadata tải lại cấu hình: `pnpm test:docker:config-reload` (tập lệnh: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` bao phủ kiểm thử smoke cài đặt/cập nhật cho đường dẫn cục bộ, `file:`, registry npm với phụ thuộc được hoist, ref git di chuyển, fixture ClawHub, cập nhật marketplace, và bật/kiểm tra gói Claude. `pnpm test:docker:plugin-update` bao phủ hành vi cập nhật không đổi cho plugins đã cài đặt. `pnpm test:docker:plugin-lifecycle-matrix` bao phủ cài đặt, bật, tắt, nâng cấp, hạ cấp, và uninstall khi thiếu mã cho plugin npm có theo dõi tài nguyên. +- Mô hình trực tiếp: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) +- Kiểm thử smoke bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`; mặc định bao phủ Claude, Codex và Gemini, với phạm vi bao phủ Droid/OpenCode nghiêm ngặt qua `pnpm test:docker:live-acp-bind:droid` và `pnpm test:docker:live-acp-bind:opencode`) +- Kiểm thử smoke backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Kiểm thử smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + tác nhân dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) +- Kiểm thử smoke observability: `pnpm qa:otel:smoke` là một lane kiểm tra mã nguồn QA riêng tư. Nó cố ý không thuộc các lane phát hành Docker của package vì npm tarball bỏ qua QA Lab. +- Kiểm thử smoke live Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) +- Trình hướng dẫn onboarding (TTY, dựng khung đầy đủ): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) +- Kiểm thử smoke onboarding/kênh/tác nhân bằng npm tarball: `pnpm test:docker:npm-onboard-channel-agent` cài đặt OpenClaw tarball đã đóng gói ở phạm vi toàn cục trong Docker, cấu hình OpenAI qua onboarding tham chiếu env cùng với Telegram theo mặc định, chạy doctor và chạy một lượt tác nhân OpenAI được mô phỏng. Dùng lại tarball dựng sẵn với `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, bỏ qua bước dựng lại trên host với `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, hoặc đổi kênh bằng `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` hoặc `OPENCLAW_NPM_ONBOARD_CHANNEL=slack`. +- Kiểm thử smoke chuyển kênh cập nhật: `pnpm test:docker:update-channel-switch` cài đặt OpenClaw tarball đã đóng gói ở phạm vi toàn cục trong Docker, chuyển từ package `stable` sang git `dev`, xác minh kênh đã lưu và hoạt động sau cập nhật của Plugin, rồi chuyển lại package `stable` và kiểm tra trạng thái cập nhật. +- Kiểm thử smoke survivor nâng cấp: `pnpm test:docker:upgrade-survivor` cài đặt OpenClaw tarball đã đóng gói đè lên một fixture người dùng cũ không sạch với tác nhân, cấu hình kênh, danh sách cho phép Plugin, trạng thái phụ thuộc Plugin đã cũ và các tệp workspace/session hiện có. Nó chạy cập nhật package cùng với doctor không tương tác mà không cần provider live hoặc khóa kênh, rồi khởi động một Gateway loopback và kiểm tra việc bảo toàn cấu hình/trạng thái cùng các ngân sách khởi động/trạng thái. +- Kiểm thử smoke survivor nâng cấp đã phát hành: `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ế, cấu hình baseline đó bằng một công thức lệnh được nhúng sẵn, xác thực cấu hình kết quả, cập nhật bản cài đặt đã phát hành đó lên tarball ứng viên, chạy doctor không tương tác, ghi `.artifacts/upgrade-survivor/summary.json`, rồi khởi động một Gateway loopback và kiểm tra các intent đã cấu hình, bảo toàn trạng thái, khởi động, `/healthz`, `/readyz` và ngân sách trạng thái RPC. Ghi đè một baseline bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, yêu cầu bộ lập lịch tổng hợp mở rộng các baseline chính xác bằng `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` như `all-since-2026.4.23`, và mở rộng các fixture theo dạng issue bằng `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` như `reported-issues`; tập reported-issues bao gồm `configured-plugin-installs` để tự động sửa cài đặt Plugin OpenClaw bên ngoài. 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`; Full Release Validation dùng baseline latest mặc định trong đường chặn và chỉ mở rộng sang all-since/reported-issues khi `run_release_soak=true` hoặc `release_profile=full`. +- Kiểm thử smoke ngữ cảnh runtime session: `pnpm test:docker:session-runtime-context` xác minh việc lưu transcript ngữ cảnh runtime ẩn cùng với sửa chữa bằng doctor cho các nhánh viết lại prompt bị trùng lặp chịu ảnh hưởng. +- Kiểm thử smoke cài đặt toàn cục Bun: `bash scripts/e2e/bun-global-install-smoke.sh` đóng gói cây hiện tại, cài đặt bằng `bun install -g` trong một home cô lập, và xác minh `openclaw infer image providers --json` trả về các provider hình ảnh được đóng gói thay vì bị treo. Dùng lại tarball dựng sẵn với `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, bỏ qua bước dựng trên host với `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, hoặc sao chép `dist/` từ một image Docker đã dựng bằng `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Kiểm thử smoke Docker của trình cài đặt: `bash scripts/test-install-sh-docker.sh` chia sẻ một bộ nhớ đệm npm giữa các container root, update và direct-npm của nó. Kiểm thử smoke cập nhật mặc định dùng npm `latest` làm baseline ổn định trước khi nâng cấp lên tarball ứng viên. Ghi đè cục bộ bằng `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`, hoặc bằng input `update_baseline_version` của workflow Install Smoke trên GitHub. Các kiểm tra trình cài đặt không phải root giữ bộ nhớ đệm npm cô lập để các mục bộ nhớ đệm do root sở hữu không che khuất hành vi cài đặt cục bộ của người dùng. Đặt `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` để dùng lại bộ nhớ đệm root/update/direct-npm qua các lần chạy lại cục bộ. +- Install Smoke CI bỏ qua cập nhật toàn cục direct-npm trùng lặp bằng `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; chạy script cục bộ mà không có env đó khi cần phạm vi bao phủ `npm install -g` trực tiếp. +- Kiểm thử smoke CLI xóa workspace dùng chung của tác nhân: `pnpm test:docker:agents-delete-shared-workspace` (script: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) mặc định dựng image Dockerfile gốc, gieo hai tác nhân với một workspace trong home container cô lập, chạy `agents delete --json`, và xác minh JSON hợp lệ cùng hành vi giữ lại workspace. Dùng lại image install-smoke với `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Mạng Gateway (hai container, xác thực WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Kiểm thử smoke snapshot CDP trình duyệt: `pnpm test:docker:browser-cdp-snapshot` (script: `scripts/e2e/browser-cdp-snapshot-docker.sh`) dựng image E2E nguồn cùng một lớp Chromium, khởi động Chromium với CDP thô, chạy `browser doctor --deep`, và xác minh snapshot vai trò CDP bao phủ 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. +- Hồi quy reasoning tối thiểu của OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) chạy một máy chủ OpenAI được mô phỏng qua Gateway, xác minh `web_search` nâng `reasoning.effort` từ `minimal` lên `low`, sau đó buộc schema của provider từ chối và kiểm tra chi tiết thô xuất hiện trong log Gateway. +- Cầu nối kênh MCP (Gateway đã gieo + cầu nối stdio + kiểm thử smoke notification-frame Claude thô): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Công cụ MCP trong gói Pi (máy chủ MCP stdio thực + kiểm thử smoke allow/deny của hồ sơ Pi nhúng): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Dọn dẹp MCP Cron/subagent (Gateway thực + tháo dỡ MCP child stdio sau các lần chạy cron cô lập và subagent một lần): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (kiểm thử smoke cài đặt/cập nhật cho đường dẫn cục bộ, `file:`, npm registry với phụ thuộc được hoist, ref git di chuyển, ClawHub kitchen-sink, cập nhật marketplace và bật/kiểm tra Claude-bundle): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) + Đặt `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` để bỏ qua khối ClawHub, hoặc ghi đè cặp package/runtime kitchen-sink mặc định bằng `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` và `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Khi không có `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, bài kiểm thử dùng một máy chủ fixture ClawHub cục bộ khép kín. +- Kiểm thử smoke cập nhật Plugin không thay đổi: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Kiểm thử smoke ma trận vòng đời Plugin: `pnpm test:docker:plugin-lifecycle-matrix` cài đặt OpenClaw tarball đã đóng gói trong một container trống, cài đặt một npm Plugin, bật/tắt, nâng cấp và hạ cấp nó qua một npm registry cục bộ, xóa mã đã cài đặt, rồi xác minh gỡ cài đặt vẫn xóa trạng thái đã cũ trong khi ghi log chỉ số RSS/CPU cho từng pha vòng đời. +- Kiểm thử smoke metadata tải lại cấu hình: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) +- Plugins: `pnpm test:docker:plugins` bao phủ kiểm thử smoke cài đặt/cập nhật cho đường dẫn cục bộ, `file:`, npm registry với phụ thuộc được hoist, ref git di chuyển, fixture ClawHub, cập nhật marketplace và bật/kiểm tra Claude-bundle. `pnpm test:docker:plugin-update` bao phủ hành vi cập nhật không thay đổi cho các Plugins đã cài đặt. `pnpm test:docker:plugin-lifecycle-matrix` bao phủ cài đặt, bật, tắt, nâng cấp, hạ cấp và gỡ cài đặt khi thiếu mã của npm Plugin có theo dõi tài nguyên. -Để dựng sẵn và tái sử dụng image chức năng dùng chung theo cách thủ công: +Để dựng trước và dùng lại image chức năng dùng chung theo cách thủ công: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Các ghi đè image theo từng bộ kiểm thử như `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` vẫn được ưu tiên khi được đặt. Khi `OPENCLAW_SKIP_DOCKER_BUILD=1` trỏ tới một image dùng chung từ xa, các tập lệnh sẽ pull image đó nếu nó chưa có cục bộ. Các kiểm thử Docker QR và trình cài đặt giữ Dockerfile riêng vì chúng xác thực hành vi gói/cài đặt thay vì runtime ứng dụng đã dựng dùng chung. +Các ghi đè image theo bộ kiểm thử như `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` vẫn được ưu tiên khi được đặt. Khi `OPENCLAW_SKIP_DOCKER_BUILD=1` trỏ tới một image dùng chung từ xa, các script sẽ pull nó nếu nó chưa có cục bộ. Các bài kiểm thử Docker QR và trình cài đặt giữ Dockerfile riêng vì chúng xác thực hành vi package/cài đặt thay vì runtime ứng dụng đã dựng dùng chung. -Các trình chạy Docker live-model cũng bind-mount checkout hiện tại ở chế độ chỉ đọc và -đưa nó vào một workdir tạm thời bên trong container. Việc này giữ cho image runtime -gọn nhẹ trong khi vẫn chạy Vitest trên đúng nguồn/cấu hình cục bộ của bạn. +Các trình chạy Docker với mô hình live cũng bind-mount checkout hiện tại ở chế độ chỉ đọc và +stage nó vào một workdir tạm thời bên trong container. Điều này giữ cho image runtime +gọn nhẹ trong khi vẫn chạy Vitest trên đúng mã nguồn/cấu hình cục bộ của bạn. Bước staging bỏ qua các cache lớn chỉ dùng cục bộ và đầu ra build ứng dụng như `.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, và các thư mục đầu ra `.build` cục bộ của ứng dụng hoặc -Gradle để các lượt chạy Docker live không mất nhiều phút sao chép +Gradle để các lần chạy live bằng Docker không mất nhiều phút sao chép artifact đặc thù của máy. -Chúng cũng đặt `OPENCLAW_SKIP_CHANNELS=1` để các probe live của Gateway không khởi động -worker kênh Telegram/Discord/v.v. thật bên trong container. -`test:docker:live-models` vẫn chạy `pnpm test:live`, vì vậy hãy truyền cả -`OPENCLAW_LIVE_GATEWAY_*` khi bạn cần thu hẹp hoặc loại trừ phạm vi live của Gateway +Chúng cũng đặt `OPENCLAW_SKIP_CHANNELS=1` để các live probe của gateway không khởi động +các worker kênh Telegram/Discord/v.v. thật bên trong container. +`test:docker:live-models` vẫn chạy `pnpm test:live`, vì vậy hãy truyền tiếp +`OPENCLAW_LIVE_GATEWAY_*` khi bạn cần thu hẹp hoặc loại trừ phạm vi kiểm thử live của gateway khỏi lane Docker đó. -`test:docker:openwebui` là một smoke tương thích cấp cao hơn: nó khởi động một -container Gateway OpenClaw với các endpoint HTTP tương thích OpenAI được bật, -khởi động một container Open WebUI đã ghim phiên bản trỏ tới Gateway đó, đăng nhập qua +`test:docker:openwebui` là một smoke kiểm tra tương thích cấp cao hơn: nó khởi động một +container gateway OpenClaw với các endpoint HTTP tương thích OpenAI được bật, +khởi động một container Open WebUI đã ghim phiên bản trỏ tới gateway đó, đăng nhập qua Open WebUI, xác minh `/api/models` hiển thị `openclaw/default`, rồi gửi một yêu cầu chat thật qua proxy `/api/chat/completions` của Open WebUI. -Lượt chạy đầu tiên có thể chậm hơn đáng kể vì Docker có thể cần kéo image +Lần chạy đầu tiên có thể chậm hơn đáng kể vì Docker có thể cần pull image Open WebUI và Open WebUI có thể cần hoàn tất thiết lập cold-start riêng. -Lane này cần một khóa live model dùng được, và `OPENCLAW_PROFILE_FILE` -(mặc định là `~/.profile`) là cách chính để cung cấp khóa đó trong các lượt chạy Docker hóa. -Các lượt chạy thành công in ra một payload JSON nhỏ như `{ "ok": true, "model": +Lane này cần một khóa mô hình live dùng được, và `OPENCLAW_PROFILE_FILE` +(mặc định là `~/.profile`) là cách chính để cung cấp khóa đó trong các lần chạy Docker hóa. +Các lần chạy thành công in ra một payload JSON nhỏ như `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` được thiết kế có tính xác định và không cần tài khoản -Telegram, Discord hoặc iMessage thật. Nó khởi động một container Gateway đã seed, -khởi động container thứ hai sinh ra `openclaw mcp serve`, rồi -xác minh việc 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 outbound, và thông báo kiểu Claude về kênh + -quyền qua cầu MCP stdio thật. Kiểm tra thông báo -kiểm tra trực tiếp các frame MCP stdio thô để smoke xác thực những gì -cầu thực sự phát ra, không chỉ những gì một SDK client cụ thể tình cờ hiển thị. -`test:docker:pi-bundle-mcp-tools` có tính xác định và không cần khóa live -model. Nó build image Docker của repo, khởi động một server probe MCP stdio thật -bên trong container, materialize server đó qua runtime MCP của Pi bundle được nhúng, -thực thi tool, rồi xác minh `coding` và `messaging` giữ -tool `bundle-mcp` trong khi `minimal` và `tools.deny: ["bundle-mcp"]` lọc chúng. -`test:docker:cron-mcp-cleanup` có tính xác định và không cần khóa live model. -Nó khởi động một Gateway đã seed với một server probe MCP stdio thật, chạy một -lượt cron cô lập và một lượt con one-shot `/subagents spawn`, rồi xác minh -tiến trình con MCP thoát sau mỗi lượt chạy. +Telegram, Discord, hoặc iMessage thật. Nó khởi động một container Gateway +đã seed dữ liệu, khởi động container thứ hai spawn `openclaw mcp serve`, rồi +xác minh discovery hội thoại đã định tuyến, đọc transcript, metadata attachment, +hành vi hàng đợi sự kiện live, định tuyến gửi outbound, và thông báo kênh kiểu Claude + +quyền qua cầu nối MCP stdio thật. Kiểm tra thông báo +kiểm tra trực tiếp các frame MCP stdio thô để smoke xác thực thứ +cầu nối thật sự phát ra, không chỉ những gì một SDK client cụ thể tình cờ hiển thị. +`test:docker:pi-bundle-mcp-tools` có tính xác định và không cần khóa mô hình live. +Nó build image Docker của repo, khởi động một server probe MCP stdio thật +bên trong container, hiện thực hóa server đó qua runtime MCP của gói Pi +được nhúng, thực thi công cụ, rồi xác minh `coding` và `messaging` giữ lại +công cụ `bundle-mcp` trong khi `minimal` và `tools.deny: ["bundle-mcp"]` lọc chúng. +`test:docker:cron-mcp-cleanup` có tính xác định và không cần khóa mô hình live. +Nó khởi động một Gateway đã seed dữ liệu với một server probe MCP stdio thật, chạy một +turn cron cô lập và một turn con one-shot `/subagents spawn`, rồi xác minh +tiến trình con MCP thoát sau mỗi lần chạy. -Smoke thủ công cho thread ACP bằng ngôn ngữ tự nhiên (không phải CI): +Smoke thủ công cho thread ACP bằng ngôn ngữ tự nhiên (không thuộc CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Giữ script này cho các workflow hồi quy/debug. Nó có thể cần lại cho xác thực định tuyến thread ACP, vì vậy đừng xóa nó. +- Giữ script này cho các quy trình hồi quy/debug. Có thể cần lại để xác thực định tuyến thread ACP, vì vậy đừng xóa nó. Các biến môi trường hữu ích: - `OPENCLAW_CONFIG_DIR=...` (mặc định: `~/.openclaw`) được mount vào `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (mặc định: `~/.openclaw/workspace`) được mount vào `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (mặc định: `~/.profile`) được mount vào `/home/node/.profile` và được source trước khi chạy test -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` để chỉ xác minh các biến môi trường được source từ `OPENCLAW_PROFILE_FILE`, dùng các thư mục cấu hình/workspace tạm thời và không mount auth CLI bên ngoài -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (mặc định: `~/.cache/openclaw/docker-cli-tools`) được mount vào `/home/node/.npm-global` cho các cài đặt CLI được cache bên trong Docker -- Các thư mục/tệp auth CLI bên ngoài dưới `$HOME` được mount chỉ đọc dưới `/host-auth...`, rồi được sao chép vào `/home/node/...` trước khi test bắt đầu +- `OPENCLAW_PROFILE_FILE=...` (mặc định: `~/.profile`) được mount vào `/home/node/.profile` và được source trước khi chạy kiểm thử +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` để chỉ xác minh các biến môi trường được source từ `OPENCLAW_PROFILE_FILE`, dùng thư mục cấu hình/workspace tạm thời và không mount xác thực CLI bên ngoài +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (mặc định: `~/.cache/openclaw/docker-cli-tools`) được mount vào `/home/node/.npm-global` cho các bản cài CLI được cache bên trong Docker +- Các thư mục/tệp xác thực CLI bên ngoài dưới `$HOME` được mount chỉ đọc dưới `/host-auth...`, rồi được sao chép vào `/home/node/...` trước khi kiểm thử bắt đầu - Thư mục mặc định: `.minimax` - Tệp mặc định: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Các lượt chạy provider đã thu hẹp chỉ mount những thư mục/tệp cần thiết được suy ra từ `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Các lần chạy provider đã thu hẹp chỉ mount những thư mục/tệp cần thiết được suy ra từ `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Ghi đè thủ công bằng `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, hoặc danh sách phân tách bằng dấu phẩy như `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` để thu hẹp lượt chạy +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` để thu hẹp lần chạy - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` để lọc provider trong container -- `OPENCLAW_SKIP_DOCKER_BUILD=1` để tái sử dụng image `openclaw:local-live` hiện có cho các lượt chạy lại không cần rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để đảm bảo credential đến từ kho hồ sơ (không phải env) -- `OPENCLAW_OPENWEBUI_MODEL=...` để chọn model do gateway hiển thị cho smoke Open WebUI +- `OPENCLAW_SKIP_DOCKER_BUILD=1` để dùng lại image `openclaw:local-live` hiện có cho các lần chạy lại không cần rebuild +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` để đảm bảo thông tin xác thực đến từ profile store (không phải env) +- `OPENCLAW_OPENWEBUI_MODEL=...` để chọn mô hình do gateway hiển thị cho smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...` để ghi đè prompt kiểm tra nonce dùng bởi smoke Open WebUI - `OPENWEBUI_IMAGE=...` để ghi đè tag image Open WebUI đã ghim -## Kiểm tra tính hợp lệ của tài liệu +## Kiểm tra hợp lý tài liệu Chạy kiểm tra tài liệu sau khi chỉnh sửa tài liệu: `pnpm check:docs`. Chạy xác thực anchor Mintlify đầy đủ khi bạn cũng cần kiểm tra heading trong trang: `pnpm docs:check-links:anchors`. ## Hồi quy offline (an toàn cho CI) -Đây là các hồi quy “pipeline thật” không dùng provider thật: +Đây là các hồi quy “pipeline thật” không có provider thật: -- Gọi tool qua Gateway (mock OpenAI, Gateway thật + vòng lặp agent): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Wizard Gateway (WS `wizard.start`/`wizard.next`, ghi cấu hình + bắt buộc auth): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") +- Gọi công cụ Gateway (mock OpenAI, gateway thật + vòng lặp agent): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Trình wizard Gateway (WS `wizard.start`/`wizard.next`, ghi cấu hình + bắt buộc xác thực): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") -## Eval độ tin cậy agent (Skills) +## Eval độ tin cậy của agent (skills) -Chúng ta đã có một vài test an toàn cho CI hoạt động giống “eval độ tin cậy agent”: +Chúng ta đã có một vài kiểm thử an toàn cho CI hoạt động như “eval độ tin cậy của agent”: -- Gọi tool mock qua Gateway thật + vòng lặp agent (`src/gateway/gateway.test.ts`). -- Các flow wizard end-to-end xác thực nối dây phiên và hiệu lực cấu hình (`src/gateway/gateway.test.ts`). +- Gọi công cụ mock qua gateway thật + vòng lặp agent (`src/gateway/gateway.test.ts`). +- Các luồng wizard end-to-end xác thực nối dây session và hiệu ứng cấu hình (`src/gateway/gateway.test.ts`). -Những gì vẫn còn thiếu cho Skills (xem [Skills](/vi/tools/skills)): +Những gì vẫn còn thiếu cho skills (xem [Skills](/vi/tools/skills)): -- **Ra quyết định:** khi Skills được liệt kê trong prompt, agent có chọn đúng skill (hoặc tránh các skill không liên quan) không? +- **Ra quyết định:** khi skills được liệt kê trong prompt, agent có chọn đúng skill (hoặc tránh những skill không liên quan) không? - **Tuân thủ:** agent có đọc `SKILL.md` trước khi dùng và làm theo các bước/đối số bắt buộc không? -- **Hợp đồng workflow:** các kịch bản nhiều lượt khẳng định thứ tự tool, truyền tiếp lịch sử phiên, và ranh giới sandbox. +- **Hợp đồng workflow:** các kịch bản nhiều turn xác nhận thứ tự công cụ, carryover lịch sử session, và ranh giới sandbox. -Các eval trong tương lai trước hết nên giữ tính xác định: +Các eval tương lai nên ưu tiên tính xác định trước: -- Một trình chạy kịch bản dùng provider mock để khẳng định các lệnh gọi tool + thứ tự, việc đọc tệp skill, và nối dây phiên. +- Một trình chạy kịch bản dùng provider mock để xác nhận lời gọi công cụ + thứ tự, đọc tệp skill, và nối dây session. - Một bộ nhỏ các kịch bản tập trung vào skill (dùng so với tránh, gating, prompt injection). -- Eval live tùy chọn (opt-in, được bảo vệ bằng env) chỉ sau khi bộ an toàn cho CI đã sẵn sàng. +- Eval live tùy chọn (opt-in, gated bằng env) chỉ sau khi bộ an toàn cho CI đã sẵn sàng. -## Test hợp đồng (hình dạng Plugin và kênh) +## Kiểm thử hợp đồng (hình dạng Plugin và kênh) -Test hợp đồng xác minh rằng mọi Plugin và kênh đã đăng ký đều tuân thủ -hợp đồng giao diện của nó. Chúng lặp qua tất cả Plugin được phát hiện và chạy một bộ +Kiểm thử hợp đồng xác minh rằng mọi Plugin và kênh đã đăng ký đều tuân thủ +hợp đồng interface của nó. Chúng lặp qua tất cả Plugin được phát hiện và chạy một bộ assertion về hình dạng và hành vi. Lane unit `pnpm test` mặc định cố ý -bỏ qua các tệp smoke và điểm nối dùng chung này; hãy chạy rõ ràng các lệnh hợp đồng -khi bạn chạm vào bề mặt kênh hoặc provider dùng chung. +bỏ qua các tệp smoke và shared seam này; hãy chạy các lệnh hợp đồng một cách tường minh +khi bạn chạm vào các surface kênh hoặc provider dùng chung. ### Lệnh @@ -773,13 +780,13 @@ khi bạn chạm vào bề mặt kênh hoặc provider dùng chung. Nằm trong `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Hình dạng Plugin cơ bản (id, tên, capability) -- **setup** - Hợp đồng wizard thiết lập -- **session-binding** - Hành vi liên kết phiên +- **setup** - Hợp đồng trình wizard thiết lập +- **session-binding** - Hành vi binding session - **outbound-payload** - Cấu trúc payload tin nhắn - **inbound** - Xử lý tin nhắn inbound -- **actions** - Handler hành động kênh +- **actions** - Handler action của kênh - **threading** - Xử lý ID thread -- **directory** - API thư mục/roster +- **directory** - API directory/roster - **group-policy** - Thực thi chính sách nhóm ### Hợp đồng trạng thái provider @@ -793,38 +800,38 @@ Nằm trong `src/plugins/contracts/*.contract.test.ts`. Nằm trong `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Hợp đồng flow auth -- **auth-choice** - Lựa chọn/chọn auth -- **catalog** - API catalog model -- **discovery** - Phát hiện Plugin +- **auth** - Hợp đồng luồng xác thực +- **auth-choice** - Lựa chọn/chọn xác thực +- **catalog** - API danh mục mô hình +- **discovery** - Discovery Plugin - **loader** - Tải Plugin - **runtime** - Runtime provider -- **shape** - Hình dạng/giao diện Plugin -- **wizard** - Wizard thiết lập +- **shape** - Hình dạng/interface Plugin +- **wizard** - Trình wizard thiết lập ### Khi nào chạy - Sau khi thay đổi export hoặc subpath của plugin-sdk - Sau khi thêm hoặc sửa đổi một Plugin kênh hoặc provider -- Sau khi refactor đăng ký hoặc phát hiện Plugin +- Sau khi refactor đăng ký hoặc discovery Plugin -Test hợp đồng chạy trong CI và không yêu cầu khóa API thật. +Kiểm thử hợp đồng chạy trong CI và không yêu cầu khóa API thật. ## Thêm hồi quy (hướng dẫn) -Khi bạn sửa một vấn đề provider/model được phát hiện trong live: +Khi bạn sửa một vấn đề provider/mô hình được phát hiện trong live: -- Thêm hồi quy an toàn cho CI nếu có thể (provider mock/stub, hoặc capture phép biến đổi chính xác của request-shape) -- Nếu bản chất của nó chỉ có thể live (rate limit, chính sách auth), giữ test live hẹp và opt-in qua biến môi trường -- Ưu tiên nhắm tới lớp nhỏ nhất bắt được bug: - - bug chuyển đổi/phát lại yêu cầu provider → test models trực tiếp - - bug pipeline phiên/lịch sử/tool của Gateway → smoke live Gateway hoặc test mock Gateway an toàn cho CI +- Thêm một hồi quy an toàn cho CI nếu có thể (provider mock/stub, hoặc capture chính xác phép biến đổi hình dạng yêu cầu) +- Nếu nó vốn chỉ có thể kiểm thử live (rate limit, chính sách xác thực), hãy giữ kiểm thử live hẹp và opt-in qua biến môi trường +- Ưu tiên nhắm vào lớp nhỏ nhất bắt được lỗi: + - lỗi chuyển đổi/phát lại yêu cầu provider → kiểm thử models trực tiếp + - lỗi pipeline gateway session/history/tool → smoke gateway live hoặc kiểm thử mock gateway an toàn cho CI - Guardrail duyệt SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` suy ra một target được lấy mẫu cho mỗi lớp SecretRef từ metadata registry (`listSecretTargetRegistryEntries()`), rồi khẳng định các exec id có segment duyệt bị từ chối. - - Nếu bạn thêm một họ target SecretRef `includeInPlan` mới trong `src/secrets/target-registry-data.ts`, hãy cập nhật `classifyTargetClass` trong test đó. Test cố ý thất bại trên các target id chưa phân loại để các lớp mới không thể bị bỏ qua âm thầm. + - `src/secrets/exec-secret-ref-id-parity.test.ts` lấy một target mẫu cho mỗi lớp SecretRef từ metadata registry (`listSecretTargetRegistryEntries()`), rồi assert exec id có phân đoạn duyệt bị từ chối. + - Nếu bạn thêm một họ target SecretRef `includeInPlan` mới trong `src/secrets/target-registry-data.ts`, hãy cập nhật `classifyTargetClass` trong kiểm thử đó. Kiểm thử cố ý fail với target id chưa được phân loại để các lớp mới không thể bị bỏ qua âm thầm. ## Liên quan -- [Testing live](/vi/help/testing-live) -- [Testing updates and plugins](/vi/help/testing-updates-plugins) +- [Kiểm thử live](/vi/help/testing-live) +- [Kiểm thử cập nhật và Plugin](/vi/help/testing-updates-plugins) - [CI](/vi/ci) diff --git a/docs/vi/plugins/bundles.md b/docs/vi/plugins/bundles.md index 6b4d017fd..bf06f83cb 100644 --- a/docs/vi/plugins/bundles.md +++ b/docs/vi/plugins/bundles.md @@ -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. - 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. ## 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 - + ```bash # Local directory openclaw plugins install ./my-bundle @@ -56,7 +56,7 @@ và dùng ngay. openclaw plugins inspect ``` - 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`. @@ -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. ## 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 ` -### Đượ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`). @@ -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 @@ -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ố Chạy `openclaw plugins inspect `. 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. - 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. - 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ô. - - `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. + + `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. ## 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 diff --git a/docs/vi/plugins/codex-harness.md b/docs/vi/plugins/codex-harness.md index 65b767c00..1aa20a1af 100644 --- a/docs/vi/plugins/codex-harness.md +++ b/docs/vi/plugins/codex-harness.md @@ -1,57 +1,57 @@ --- read_when: - - Bạn muốn sử dụng bộ harness app-server đi kèm của Codex - - Bạn cần các ví dụ về cấu hình bộ khung Codex + - Bạn muốn sử dụng bộ khung app-server Codex đi kèm + - Bạn cần các ví dụ cấu hình bộ chạy Codex - Bạn muốn các triển khai chỉ dùng Codex thất bại thay vì chuyển dự phòng sang PI -summary: Chạy các lượt tác nhân nhúng OpenClaw thông qua bộ khung app-server Codex đi kèm +summary: Chạy các lượt tác nhân nhúng của OpenClaw qua bộ khung app-server Codex đi kèm title: Bộ khung Codex x-i18n: - generated_at: "2026-05-03T21:34:45Z" + generated_at: "2026-05-05T01:48:46Z" model: gpt-5.5 provider: openai - source_hash: f5187e54e2dc94e511c0243227f741d3486669f595c2b15cf239b1c03ea466c8 + source_hash: 76302351e7e162e858dd6e3cffca84b3fd54497dd060104da9f90fe4c1a33f9b source_path: plugins/codex-harness.md workflow: 16 --- -Plugin `codex` đi kèm cho phép OpenClaw chạy các lượt agent nhúng thông qua +Plugin `codex` đi kèm cho phép OpenClaw chạy các lượt tác nhân nhúng thông qua Codex app-server thay vì harness PI tích hợp sẵn. -Dùng tùy chọn này khi bạn muốn Codex sở hữu phiên agent cấp thấp: khám phá mô -hình, tiếp tục luồng gốc, compaction gốc và thực thi app-server. OpenClaw vẫn sở -hữu các kênh chat, tệp phiên, lựa chọn mô hình, công cụ, phê duyệt, phân phối -phương tiện và bản sao transcript hiển thị. +Dùng tùy chọn này khi bạn muốn Codex sở hữu phiên tác nhân cấp thấp: khám phá +mô hình, tiếp tục luồng gốc, compaction gốc và thực thi app-server. +OpenClaw vẫn sở hữu các kênh chat, tệp phiên, lựa chọn mô hình, công cụ, +phê duyệt, gửi phương tiện và bản sao transcript hiển thị. Khi một lượt chat nguồn chạy qua harness Codex, các phản hồi hiển thị mặc định -dùng công cụ `message` của OpenClaw nếu bản triển khai chưa cấu hình rõ -`messages.visibleReplies`. Agent vẫn có thể hoàn tất lượt Codex của nó một cách -riêng tư; nó chỉ đăng lên kênh khi gọi `message(action="send")`. Đặt -`messages.visibleReplies: "automatic"` để giữ các phản hồi cuối trong chat trực -tiếp trên đường dẫn phân phối tự động cũ. +dùng công cụ OpenClaw `message` nếu bản triển khai chưa cấu hình rõ +`messages.visibleReplies`. Tác nhân vẫn có thể hoàn tất lượt Codex của nó một +cách riêng tư; nó chỉ đăng lên kênh khi gọi `message(action="send")`. Đặt +`messages.visibleReplies: "automatic"` để giữ phản hồi cuối của chat trực tiếp +trên đường gửi tự động cũ. -Các lượt heartbeat của Codex cũng mặc định có công cụ `heartbeat_respond`, để -agent có thể ghi lại liệu lần đánh thức nên giữ im lặng hay thông báo mà không -mã hóa luồng điều khiển đó trong văn bản cuối. +Các lượt Codex heartbeat cũng nhận công cụ `heartbeat_respond` theo mặc định, để +tác nhân có thể ghi lại việc lần đánh thức nên giữ im lặng hay thông báo mà +không mã hóa luồng điều khiển đó trong văn bản cuối. -Hướng dẫn chủ động dành riêng cho Heartbeat được gửi dưới dạng chỉ thị dành cho -nhà phát triển ở chế độ cộng tác của Codex trên chính lượt heartbeat đó. Các -lượt chat thông thường khôi phục chế độ mặc định của Codex thay vì mang triết lý -heartbeat trong prompt runtime thông thường. +Hướng dẫn chủ động dành riêng cho Heartbeat được gửi dưới dạng chỉ dẫn developer +ở chế độ cộng tác Codex trên chính lượt heartbeat đó. Các lượt chat thông thường +khôi phục chế độ Codex Default thay vì mang triết lý heartbeat trong prompt +runtime bình thường của chúng. Nếu bạn đang cố định hướng, hãy bắt đầu với -[Runtime agent](/vi/concepts/agent-runtimes). Phiên bản ngắn gọn là: -`openai/gpt-5.5` là tham chiếu mô hình, `codex` là runtime, và Telegram, -Discord, Slack hoặc một kênh khác vẫn là bề mặt giao tiếp. +[Runtime tác nhân](/vi/concepts/agent-runtimes). Bản ngắn gọn là: +`openai/gpt-5.5` là tham chiếu mô hình, `codex` là runtime, còn Telegram, +Discord, Slack hoặc kênh khác vẫn là bề mặt giao tiếp. ## Cấu hình nhanh Hầu hết người dùng muốn "Codex trong OpenClaw" sẽ muốn tuyến này: đăng nhập bằng -gói đăng ký ChatGPT/Codex, rồi chạy các lượt agent nhúng thông qua runtime Codex -app-server gốc. Tham chiếu mô hình vẫn giữ dạng chuẩn là `openai/gpt-*`; xác thực -gói đăng ký đến từ tài khoản/hồ sơ Codex, không phải từ tiền tố mô hình -`openai-codex/*`. +gói đăng ký ChatGPT/Codex, rồi chạy các lượt tác nhân nhúng thông qua runtime +Codex app-server gốc. Tham chiếu mô hình vẫn giữ chuẩn là +`openai/gpt-*`; xác thực gói đăng ký đến từ tài khoản/hồ sơ Codex, không đến từ +tiền tố mô hình `openai-codex/*`. -Trước tiên đăng nhập bằng Codex OAuth nếu bạn chưa đăng nhập: +Trước tiên đăng nhập bằng Codex OAuth nếu bạn chưa làm: ```bash openclaw models auth login --provider openai-codex @@ -79,7 +79,7 @@ Sau đó bật Plugin `codex` đi kèm và ép dùng runtime Codex: } ``` -Nếu cấu hình của bạn dùng `plugins.allow`, cũng hãy thêm `codex` vào đó: +Nếu cấu hình của bạn dùng `plugins.allow`, hãy thêm cả `codex` vào đó: ```json5 { @@ -94,212 +94,212 @@ Nếu cấu hình của bạn dùng `plugins.allow`, cũng hãy thêm `codex` v } ``` -Không dùng `openai-codex/gpt-*` khi bạn muốn runtime Codex gốc. Tiền tố đó là -tuyến rõ ràng "Codex OAuth thông qua PI". Thay đổi cấu hình áp dụng cho các -phiên mới hoặc đã đặt lại; các phiên hiện có giữ runtime đã được ghi lại. +Đừng dùng `openai-codex/gpt-*` khi ý bạn là runtime Codex gốc. Tiền tố đó là +tuyến "Codex OAuth thông qua PI" rõ ràng. Thay đổi cấu hình áp dụng cho phiên +mới hoặc phiên được đặt lại; các phiên hiện có giữ runtime đã ghi nhận của chúng. ## Plugin này thay đổi gì -Plugin `codex` đi kèm đóng góp một số khả năng riêng biệt: +Plugin `codex` đi kèm đóng góp một số năng lực riêng biệt: -| Khả năng | Cách bạn dùng | Tác dụng | -| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- | -| Runtime nhúng gốc | `agentRuntime.id: "codex"` | Chạy các lượt agent nhúng của OpenClaw thông qua Codex app-server. | +| Năng lực | Cách bạn dùng | Việc nó làm | +| --------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------ | +| Runtime nhúng gốc | `agentRuntime.id: "codex"` | Chạy các lượt tác nhân nhúng OpenClaw thông qua Codex app-server. | | Lệnh điều khiển chat gốc | `/codex bind`, `/codex resume`, `/codex steer`, ... | Liên kết và điều khiển các luồng Codex app-server từ một cuộc trò chuyện nhắn tin. | -| Nhà cung cấp/danh mục Codex app-server | nội bộ `codex`, được hiển thị qua harness | Cho phép runtime khám phá và xác thực các mô hình app-server. | -| Đường dẫn hiểu phương tiện Codex | đường dẫn tương thích mô hình ảnh `codex/*` | Chạy các lượt Codex app-server có giới hạn cho các mô hình hiểu ảnh được hỗ trợ. | -| Relay hook gốc | Hook Plugin quanh các sự kiện Codex gốc | Cho phép OpenClaw quan sát/chặn các sự kiện công cụ/hoàn tất Codex gốc được hỗ trợ. | +| Nhà cung cấp/danh mục Codex app-server | nội bộ `codex`, được bộc lộ qua harness | Cho phép runtime khám phá và xác thực các mô hình app-server. | +| Đường hiểu phương tiện Codex | đường tương thích mô hình hình ảnh `codex/*` | Chạy các lượt Codex app-server có giới hạn cho mô hình hiểu hình ảnh được hỗ trợ. | +| Chuyển tiếp hook gốc | Hook Plugin quanh các sự kiện Codex gốc | Cho phép OpenClaw quan sát/chặn các sự kiện công cụ/hoàn tất gốc của Codex được hỗ trợ. | -Bật Plugin sẽ làm các khả năng đó khả dụng. Nó **không**: +Bật Plugin sẽ làm các năng lực đó khả dụng. Nó **không**: - bắt đầu dùng Codex cho mọi mô hình OpenAI -- chuyển đổi các tham chiếu mô hình `openai-codex/*` thành runtime gốc -- đặt ACP/acpx làm đường dẫn Codex mặc định -- chuyển nóng các phiên hiện có đã ghi nhận runtime PI -- thay thế phân phối kênh, tệp phiên, lưu trữ hồ sơ xác thực hoặc định tuyến tin - nhắn của OpenClaw +- chuyển đổi tham chiếu mô hình `openai-codex/*` thành runtime gốc +- đặt ACP/acpx làm đường Codex mặc định +- hot-switch các phiên hiện có vốn đã ghi nhận runtime PI +- thay thế việc gửi kênh OpenClaw, tệp phiên, lưu trữ hồ sơ xác thực hoặc + định tuyến tin nhắn -Cùng Plugin này cũng sở hữu bề mặt lệnh điều khiển chat `/codex` gốc. Nếu Plugin -được bật và người dùng yêu cầu liên kết, tiếp tục, điều hướng, dừng hoặc kiểm tra -các luồng Codex từ chat, agent nên ưu tiên `/codex ...` thay vì ACP. ACP vẫn là -phương án dự phòng rõ ràng khi người dùng yêu cầu ACP/acpx hoặc đang kiểm thử bộ -chuyển đổi Codex ACP. +Cùng Plugin này cũng sở hữu bề mặt lệnh điều khiển chat `/codex` gốc. Nếu +Plugin được bật và người dùng yêu cầu liên kết, tiếp tục, điều hướng, dừng hoặc +kiểm tra các luồng Codex từ chat, tác nhân nên ưu tiên `/codex ...` thay vì ACP. +ACP vẫn là phương án dự phòng rõ ràng khi người dùng yêu cầu ACP/acpx hoặc đang +kiểm thử bộ chuyển đổi ACP Codex. -Các lượt Codex gốc giữ các hook Plugin của OpenClaw làm lớp tương thích công -khai. Đây là các hook OpenClaw trong tiến trình, không phải hook lệnh -`hooks.json` của Codex: +Các lượt Codex gốc giữ hook Plugin OpenClaw làm lớp tương thích công khai. +Đây là các hook OpenClaw trong tiến trình, không phải hook lệnh `hooks.json` của Codex: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` cho các bản ghi transcript được phản chiếu -- `before_agent_finalize` thông qua relay `Stop` của Codex +- `before_message_write` cho bản ghi transcript được phản chiếu +- `before_agent_finalize` thông qua chuyển tiếp Codex `Stop` - `agent_end` -Các Plugin cũng có thể đăng ký middleware kết quả công cụ trung lập runtime để +Plugin cũng có thể đăng ký middleware kết quả công cụ trung lập với runtime để viết lại kết quả công cụ động của OpenClaw sau khi OpenClaw thực thi công cụ và -trước khi kết quả được trả về Codex. Điều này tách biệt với hook Plugin công -khai `tool_result_persist`, vốn biến đổi các lần ghi kết quả công cụ trong -transcript do OpenClaw sở hữu. +trước khi kết quả được trả về Codex. Điều này tách biệt với hook Plugin công khai +`tool_result_persist`, vốn biến đổi các lần ghi kết quả công cụ trong transcript +do OpenClaw sở hữu. -Về chính ngữ nghĩa hook Plugin, xem [Hook Plugin](/vi/plugins/hooks) -và [Hành vi bảo vệ Plugin](/vi/tools/plugin). +Để biết chính ngữ nghĩa hook Plugin, xem [hook Plugin](/vi/plugins/hooks) +và [hành vi bảo vệ Plugin](/vi/tools/plugin). -Harness mặc định tắt. Cấu hình mới nên giữ tham chiếu mô hình OpenAI ở dạng -chuẩn là `openai/gpt-*` và ép rõ -`agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex` khi muốn thực thi -app-server gốc. Các tham chiếu mô hình cũ `codex/*` vẫn tự động chọn harness để -tương thích, nhưng các tiền tố nhà cung cấp cũ có runtime phía sau không được -hiển thị như lựa chọn mô hình/nhà cung cấp thông thường. +Harness bị tắt theo mặc định. Cấu hình mới nên giữ tham chiếu mô hình OpenAI +theo chuẩn là `openai/gpt-*` và ép rõ +`agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex` khi muốn +thực thi app-server gốc. Tham chiếu mô hình cũ `codex/*` vẫn tự động chọn +harness để tương thích, nhưng các tiền tố nhà cung cấp cũ được runtime hậu thuẫn +không được hiển thị như lựa chọn mô hình/nhà cung cấp bình thường. Nếu Plugin `codex` được bật nhưng mô hình chính vẫn là `openai-codex/*`, `openclaw doctor` sẽ cảnh báo thay vì thay đổi tuyến. Điều đó -là chủ ý: `openai-codex/*` vẫn là đường dẫn Codex OAuth/gói đăng ký qua PI, và -thực thi app-server gốc vẫn là lựa chọn runtime rõ ràng. +là có chủ ý: `openai-codex/*` vẫn là đường PI Codex OAuth/gói đăng ký, còn thực +thi app-server gốc vẫn là một lựa chọn runtime rõ ràng. ## Bản đồ tuyến Dùng bảng này trước khi thay đổi cấu hình: -| Hành vi mong muốn | Tham chiếu mô hình | Cấu hình runtime | Tuyến xác thực/hồ sơ | Nhãn trạng thái mong đợi | -| -------------------------------------------------- | ------------------------ | -------------------------------------- | ---------------------------- | ------------------------------ | -| Gói đăng ký ChatGPT/Codex với runtime Codex gốc | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth hoặc tài khoản Codex | `Runtime: OpenAI Codex` | -| OpenAI API thông qua runner OpenClaw thông thường | `openai/gpt-*` | bỏ qua hoặc `runtime: "pi"` | Khóa OpenAI API | `Runtime: OpenClaw Pi Default` | -| Gói đăng ký ChatGPT/Codex thông qua PI | `openai-codex/gpt-*` | bỏ qua hoặc `runtime: "pi"` | Nhà cung cấp OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | -| Nhiều nhà cung cấp với chế độ tự động thận trọng | tham chiếu riêng theo nhà cung cấp | `agentRuntime.id: "auto"` | Theo nhà cung cấp đã chọn | Tùy runtime đã chọn | -| Phiên bộ chuyển đổi Codex ACP rõ ràng | phụ thuộc prompt/mô hình ACP | `sessions_spawn` với `runtime: "acp"` | Xác thực backend ACP | Trạng thái tác vụ/phiên ACP | +| Hành vi mong muốn | Tham chiếu mô hình | Cấu hình runtime | Tuyến xác thực/hồ sơ | Nhãn trạng thái kỳ vọng | +| -------------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | +| Gói đăng ký ChatGPT/Codex với runtime Codex gốc | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth hoặc tài khoản Codex | `Runtime: OpenAI Codex` | +| OpenAI API thông qua runner OpenClaw bình thường | `openai/gpt-*` | bỏ qua hoặc `runtime: "pi"` | Khóa OpenAI API | `Runtime: OpenClaw Pi Default` | +| Gói đăng ký ChatGPT/Codex thông qua PI | `openai-codex/gpt-*` | bỏ qua hoặc `runtime: "pi"` | Nhà cung cấp OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | +| Nhiều nhà cung cấp với chế độ tự động thận trọng | tham chiếu theo nhà cung cấp | `agentRuntime.id: "auto"` | Theo nhà cung cấp được chọn | Phụ thuộc runtime được chọn | +| Phiên bộ chuyển đổi Codex ACP rõ ràng | phụ thuộc prompt/mô hình ACP | `sessions_spawn` với `runtime: "acp"` | Xác thực backend ACP | Trạng thái tác vụ/phiên ACP | -Phần phân tách quan trọng là nhà cung cấp so với runtime: +Điểm tách quan trọng là nhà cung cấp so với runtime: - `openai-codex/*` trả lời "PI nên dùng tuyến nhà cung cấp/xác thực nào?" - `agentRuntime.id: "codex"` trả lời "vòng lặp nào nên thực thi lượt nhúng này?" -- `/codex ...` trả lời "cuộc trò chuyện Codex gốc nào mà chat này nên liên kết +- `/codex ...` trả lời "cuộc trò chuyện Codex gốc nào nên được chat này liên kết hoặc điều khiển?" -- ACP trả lời "acpx nên khởi chạy tiến trình harness bên ngoài nào?" +- ACP trả lời "tiến trình harness bên ngoài nào nên được acpx khởi chạy?" ## Chọn đúng tiền tố mô hình -Các tuyến thuộc họ OpenAI phụ thuộc vào tiền tố. Với thiết lập phổ biến là gói -đăng ký cộng với runtime Codex gốc, dùng `openai/*` với -`agentRuntime.id: "codex"`. Chỉ dùng `openai-codex/*` khi bạn chủ ý muốn Codex -OAuth thông qua PI: +Các tuyến họ OpenAI phụ thuộc vào tiền tố. Với thiết lập phổ biến gồm gói đăng +ký cộng với runtime Codex gốc, dùng `openai/*` với `agentRuntime.id: "codex"`. +Chỉ dùng `openai-codex/*` khi bạn cố ý muốn Codex OAuth thông qua PI: -| Tham chiếu mô hình | Đường dẫn runtime | Dùng khi | -| ------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Nhà cung cấp OpenAI qua hệ thống OpenClaw/PI | Bạn muốn truy cập OpenAI Platform API trực tiếp hiện tại với `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth qua OpenClaw/PI | Bạn muốn xác thực gói đăng ký ChatGPT/Codex với runner PI mặc định. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness Codex app-server | Bạn muốn xác thực gói đăng ký ChatGPT/Codex với thực thi Codex gốc. | +| Tham chiếu mô hình | Đường runtime | Dùng khi | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Nhà cung cấp OpenAI qua hệ thống OpenClaw/PI | Bạn muốn truy cập OpenAI Platform API trực tiếp hiện tại bằng `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth qua OpenClaw/PI | Bạn muốn xác thực gói đăng ký ChatGPT/Codex với runner PI mặc định. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness Codex app-server | Bạn muốn xác thực gói đăng ký ChatGPT/Codex với thực thi Codex gốc. | GPT-5.5 có thể xuất hiện trên cả tuyến khóa API OpenAI trực tiếp và tuyến gói -đăng ký Codex khi tài khoản của bạn cung cấp chúng. Dùng `openai/gpt-5.5` với +đăng ký Codex khi tài khoản của bạn bộc lộ chúng. Dùng `openai/gpt-5.5` với harness Codex app-server cho runtime Codex gốc, `openai-codex/gpt-5.5` cho PI -OAuth, hoặc `openai/gpt-5.5` không có ghi đè runtime Codex cho lưu lượng dùng -khóa API trực tiếp. +OAuth, hoặc `openai/gpt-5.5` không có ghi đè runtime Codex cho lưu lượng khóa API +trực tiếp. -Các tham chiếu cũ `codex/gpt-*` vẫn được chấp nhận làm bí danh tương thích. Di -chuyển tương thích của doctor viết lại các tham chiếu runtime chính cũ thành -tham chiếu mô hình chuẩn và ghi chính sách runtime riêng, trong khi các tham -chiếu cũ chỉ dùng làm dự phòng được giữ nguyên vì runtime được cấu hình cho toàn -bộ vùng chứa agent. Cấu hình PI Codex OAuth mới nên dùng `openai-codex/gpt-*`; -cấu hình harness app-server gốc mới nên dùng `openai/gpt-*` cộng với +Tham chiếu cũ `codex/gpt-*` vẫn được chấp nhận làm bí danh tương thích. Di trú +tương thích của Doctor viết lại tham chiếu runtime chính cũ thành tham chiếu mô +hình chuẩn và ghi chính sách runtime riêng, còn các tham chiếu cũ chỉ dùng dự +phòng được giữ nguyên vì runtime được cấu hình cho toàn bộ container tác nhân. +Cấu hình PI Codex OAuth mới nên dùng `openai-codex/gpt-*`; cấu hình harness +app-server gốc mới nên dùng `openai/gpt-*` cộng với `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` tuân theo cùng phân tách tiền tố. Dùng -`openai-codex/gpt-*` khi hiểu ảnh nên chạy qua đường dẫn nhà cung cấp OpenAI -Codex OAuth. Dùng `codex/gpt-*` khi hiểu ảnh nên chạy qua một lượt Codex -app-server có giới hạn. Mô hình Codex app-server phải công bố hỗ trợ đầu vào +`agents.defaults.imageModel` tuân theo cùng cách tách tiền tố. Dùng +`openai-codex/gpt-*` khi hiểu hình ảnh nên chạy qua đường nhà cung cấp OpenAI +Codex OAuth. Dùng `codex/gpt-*` khi hiểu hình ảnh nên chạy qua một lượt Codex +app-server có giới hạn. Mô hình Codex app-server phải quảng bá hỗ trợ đầu vào hình ảnh; các mô hình Codex chỉ văn bản sẽ thất bại trước khi lượt phương tiện bắt đầu. -Dùng `/status` để xác nhận harness hiệu lực cho phiên hiện tại. Nếu lựa chọn -gây bất ngờ, hãy bật ghi log debug cho phân hệ `agents/harness` và kiểm tra bản -ghi có cấu trúc `agent harness selected` của gateway. Bản ghi đó bao gồm id -harness đã chọn, lý do lựa chọn, chính sách runtime/dự phòng và, ở chế độ +Dùng `/status` để xác nhận harness hiệu lực cho phiên hiện tại. Nếu lựa chọn gây +ngạc nhiên, hãy bật ghi nhật ký debug cho phân hệ `agents/harness` và kiểm tra +bản ghi có cấu trúc `agent harness selected` của Gateway. Bản ghi này bao gồm id +harness được chọn, lý do chọn, chính sách runtime/dự phòng và, trong chế độ `auto`, kết quả hỗ trợ của từng ứng viên Plugin. -### Cảnh báo doctor nghĩa là gì +### Cảnh báo doctor có nghĩa là gì -`openclaw doctor` cảnh báo khi tất cả các điều kiện sau đều đúng: +`openclaw doctor` cảnh báo khi tất cả điều sau đều đúng: -- Plugin `codex` đi kèm được bật hoặc được phép -- mô hình chính của một agent là `openai-codex/*` -- runtime hiệu lực của agent đó không phải `codex` +- Plugin `codex` đi kèm được bật hoặc được cho phép +- mô hình chính của một tác nhân là `openai-codex/*` +- runtime hiệu lực của tác nhân đó không phải `codex` -Cảnh báo đó tồn tại vì người dùng thường kỳ vọng "Plugin Codex đã bật" đồng -nghĩa với "runtime Codex app-server gốc." OpenClaw không tự suy diễn như vậy. -Cảnh báo có nghĩa là: +Cảnh báo đó tồn tại vì người dùng thường kỳ vọng "Plugin Codex được bật" hàm ý +"runtime Codex app-server gốc." OpenClaw không tự thực hiện bước nhảy đó. Cảnh +báo có nghĩa là: -- **Không cần thay đổi** nếu bạn chủ ý dùng ChatGPT/Codex OAuth thông qua PI. +- **Không cần thay đổi** nếu bạn định dùng ChatGPT/Codex OAuth thông qua PI. - Đổi mô hình thành `openai/` và đặt - `agentRuntime.id: "codex"` nếu bạn chủ ý muốn thực thi app-server gốc. -- Các phiên hiện có vẫn cần `/new` hoặc `/reset` sau khi thay đổi runtime, + `agentRuntime.id: "codex"` nếu bạn định dùng thực thi app-server + gốc. +- Các phiên hiện có vẫn cần `/new` hoặc `/reset` sau một thay đổi runtime, vì ghim runtime của phiên có tính bám dính. -Lựa chọn harness không phải là điều khiển phiên trực tiếp. Khi một lượt nhúng -chạy, OpenClaw ghi id harness đã chọn trên phiên đó và tiếp tục dùng nó cho các -lượt sau trong cùng id phiên. Thay đổi cấu hình `agentRuntime` hoặc -`OPENCLAW_AGENT_RUNTIME` khi bạn muốn các phiên trong tương lai dùng harness -khác; dùng `/new` hoặc `/reset` để bắt đầu một phiên mới trước khi chuyển một -cuộc trò chuyện hiện có giữa PI và Codex. Điều này tránh phát lại một transcript -qua hai hệ thống phiên gốc không tương thích. +Chọn harness không phải là điều khiển phiên trực tiếp. Khi một lượt nhúng chạy, +OpenClaw ghi id harness được chọn trên phiên đó và tiếp tục dùng nó cho các lượt +sau trong cùng id phiên. Thay đổi cấu hình `agentRuntime` hoặc +`OPENCLAW_AGENT_RUNTIME` khi bạn muốn các phiên tương lai dùng harness khác; +dùng `/new` hoặc `/reset` để bắt đầu một phiên mới trước khi chuyển một cuộc trò +chuyện hiện có giữa PI và Codex. Điều này tránh phát lại một transcript qua hai +hệ thống phiên gốc không tương thích. -Các phiên kế thừa được tạo trước khi ghim harness được xem là đã ghim PI sau khi -chúng có lịch sử transcript. Dùng `/new` hoặc `/reset` để đưa cuộc trò chuyện đó -vào Codex sau khi đổi cấu hình. +Các phiên cũ được tạo trước khi có ghim harness được xem là đã ghim theo PI sau khi +có lịch sử bản ghi. Dùng `/new` hoặc `/reset` để chọn đưa cuộc trò chuyện đó vào +Codex sau khi thay đổi cấu hình. -`/status` hiển thị runtime mô hình hiệu lực. Harness PI mặc định xuất hiện dưới dạng -`Runtime: OpenClaw Pi Default`, và harness app-server Codex xuất hiện dưới dạng +`/status` hiển thị runtime mô hình hiệu lực. Harness PI mặc định xuất hiện là +`Runtime: OpenClaw Pi Default`, và harness app-server Codex xuất hiện là `Runtime: OpenAI Codex`. ## Yêu cầu - OpenClaw có sẵn Plugin `codex` đi kèm. -- App-server Codex `0.125.0` hoặc mới hơn. Plugin đi kèm mặc định quản lý một - binary app-server Codex tương thích, nên các lệnh `codex` cục bộ trên `PATH` - không ảnh hưởng đến việc khởi động harness thông thường. -- Xác thực Codex khả dụng cho tiến trình app-server hoặc cho cầu nối xác thực - Codex của OpenClaw. Các lần khởi chạy app-server cục bộ dùng một home Codex do - OpenClaw quản lý cho từng agent và một `HOME` con biệt lập, nên mặc định chúng - không đọc tài khoản, skills, plugins, cấu hình, trạng thái thread cá nhân trong - `~/.codex`, hoặc `$HOME/.agents/skills` gốc của bạn. +- Codex app-server `0.125.0` trở lên. Theo mặc định, Plugin đi kèm quản lý một + binary Codex app-server tương thích, nên các lệnh `codex` cục bộ trên `PATH` sẽ + không ảnh hưởng đến quá trình khởi động harness thông thường. +- Xác thực Codex có sẵn cho tiến trình app-server hoặc cho cầu nối xác thực + Codex của OpenClaw. Các lần khởi chạy app-server cục bộ dùng một thư mục home + Codex do OpenClaw quản lý cho từng agent và một `HOME` con cô lập, vì vậy theo + mặc định chúng không đọc tài khoản, skills, Plugin, cấu hình, trạng thái thread + cá nhân trong `~/.codex` của bạn, hoặc `$HOME/.agents/skills` gốc. -Plugin chặn các lần bắt tay app-server cũ hơn hoặc không có phiên bản. Điều đó giữ +Plugin chặn các handshake app-server cũ hơn hoặc không có phiên bản. Điều đó giữ OpenClaw trên bề mặt giao thức đã được kiểm thử. -Đối với kiểm thử smoke trực tiếp và Docker, xác thực thường đến từ tài khoản Codex CLI +Đối với các kiểm thử smoke live và Docker, xác thực thường đến từ tài khoản Codex CLI hoặc một hồ sơ xác thực `openai-codex` của OpenClaw. Các lần khởi chạy app-server -stdio cục bộ cũng có thể dự phòng về `CODEX_API_KEY` / `OPENAI_API_KEY` khi không -có tài khoản nào hiện diện. +stdio cục bộ cũng có thể fallback sang `CODEX_API_KEY` / `OPENAI_API_KEY` khi +không có tài khoản nào. -## Tệp khởi động workspace +## Tệp bootstrap workspace Codex tự xử lý `AGENTS.md` thông qua cơ chế khám phá tài liệu dự án gốc. OpenClaw -không ghi các tệp tài liệu dự án Codex tổng hợp hoặc phụ thuộc vào tên tệp dự phòng -của Codex cho tệp persona, vì các dự phòng Codex chỉ áp dụng khi thiếu -`AGENTS.md`. +không ghi các tệp tài liệu dự án Codex tổng hợp hoặc phụ thuộc vào tên tệp +fallback của Codex cho các tệp persona, vì fallback của Codex chỉ áp dụng khi +thiếu `AGENTS.md`. -Để giữ tương đương workspace trong OpenClaw, harness Codex phân giải các tệp khởi động -khác (`SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, +Để giữ parity workspace OpenClaw, harness Codex phân giải các tệp bootstrap khác +(`SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, và `MEMORY.md` khi có) và chuyển tiếp chúng qua chỉ dẫn cấu hình -Codex trên `thread/start` và `thread/resume`. Việc này giữ cho `SOUL.md` và ngữ cảnh -persona/hồ sơ workspace liên quan hiển thị mà không nhân bản `AGENTS.md`. +Codex trên `thread/start` và `thread/resume`. Điều này giữ cho `SOUL.md` và ngữ +cảnh persona/hồ sơ workspace liên quan vẫn hiển thị mà không nhân bản +`AGENTS.md`. ## Thêm Codex cùng với các mô hình khác -Đừng đặt `agentRuntime.id: "codex"` toàn cục nếu cùng một agent cần tự do chuyển đổi -giữa Codex và các mô hình nhà cung cấp không phải Codex. Runtime bị ép buộc áp dụng -cho mọi lượt nhúng của agent hoặc phiên đó. Nếu bạn chọn một mô hình Anthropic trong -khi runtime đó bị ép buộc, OpenClaw vẫn thử harness Codex và đóng lỗi thay vì âm thầm -định tuyến lượt đó qua PI. +Không đặt `agentRuntime.id: "codex"` toàn cục nếu cùng agent đó cần tự do chuyển +đổi giữa Codex và các mô hình provider không phải Codex. Một runtime bị ép buộc +áp dụng cho mọi lượt nhúng của agent hoặc phiên đó. Nếu bạn chọn một mô hình +Anthropic trong khi runtime đó đang bị ép buộc, OpenClaw vẫn thử harness Codex và +đóng thất bại thay vì âm thầm định tuyến lượt đó qua PI. -Thay vào đó, dùng một trong các dạng sau: +Thay vào đó, hãy dùng một trong các dạng sau: - Đặt Codex trên một agent chuyên dụng với `agentRuntime.id: "codex"`. -- Giữ agent mặc định trên `agentRuntime.id: "auto"` và dự phòng PI cho cách dùng - nhà cung cấp hỗn hợp thông thường. -- Chỉ dùng các tham chiếu `codex/*` kế thừa để tương thích. Cấu hình mới nên ưu tiên - `openai/*` cùng một chính sách runtime Codex rõ ràng. +- Giữ agent mặc định trên `agentRuntime.id: "auto"` và PI fallback cho việc sử + dụng provider hỗn hợp thông thường. +- Chỉ dùng các ref cũ `codex/*` để tương thích. Cấu hình mới nên ưu tiên + `openai/*` cùng với một chính sách runtime Codex rõ ràng. Ví dụ, cấu hình này giữ agent mặc định trên lựa chọn tự động thông thường và thêm một agent Codex riêng: @@ -340,36 +340,36 @@ thêm một agent Codex riêng: Với dạng này: -- Agent `main` mặc định dùng đường dẫn nhà cung cấp thông thường và dự phòng tương thích PI. +- Agent `main` mặc định dùng đường dẫn provider thông thường và fallback tương thích PI. - Agent `codex` dùng harness app-server Codex. -- Nếu Codex bị thiếu hoặc không được hỗ trợ cho agent `codex`, lượt sẽ thất bại +- Nếu Codex bị thiếu hoặc không được hỗ trợ cho agent `codex`, lượt đó thất bại thay vì lặng lẽ dùng PI. ## Định tuyến lệnh agent -Agent nên định tuyến yêu cầu người dùng theo ý định, không chỉ theo riêng từ "Codex": +Agent nên định tuyến yêu cầu của người dùng theo ý định, không chỉ theo riêng từ "Codex": | Người dùng yêu cầu... | Agent nên dùng... | | ------------------------------------------------------ | ------------------------------------------------ | | "Gắn chat này với Codex" | `/codex bind` | -| "Tiếp tục thread Codex `` tại đây" | `/codex resume ` | +| "Tiếp tục thread Codex `` ở đây" | `/codex resume ` | | "Hiển thị các thread Codex" | `/codex threads` | | "Gửi báo cáo hỗ trợ cho một lần chạy Codex lỗi" | `/diagnostics [note]` | | "Chỉ gửi phản hồi Codex cho thread đính kèm này" | `/codex diagnostics [note]` | -| "Dùng gói đăng ký ChatGPT/Codex của tôi với runtime Codex" | `openai/*` cộng với `agentRuntime.id: "codex"` | -| "Dùng gói đăng ký ChatGPT/Codex của tôi qua PI" | tham chiếu mô hình `openai-codex/*` | +| "Dùng đăng ký ChatGPT/Codex của tôi với runtime Codex" | `openai/*` plus `agentRuntime.id: "codex"` | +| "Dùng đăng ký ChatGPT/Codex của tôi qua PI" | `openai-codex/*` model refs | | "Chạy Codex qua ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Khởi động Claude Code/Gemini/OpenCode/Cursor trong một thread" | ACP/acpx, không phải `/codex` và không phải sub-agent gốc | +| "Khởi động Claude Code/Gemini/OpenCode/Cursor trong thread" | ACP/acpx, không phải `/codex` và không phải sub-agent gốc | -OpenClaw chỉ quảng bá hướng dẫn spawn ACP cho agent khi ACP được bật, -có thể dispatch, và được hỗ trợ bởi một runtime backend đã tải. Nếu ACP không khả dụng, -system prompt và plugin skills không nên dạy agent về định tuyến ACP. +OpenClaw chỉ quảng bá hướng dẫn spawn ACP cho agent khi ACP được bật, có thể +dispatch, và được hỗ trợ bởi một backend runtime đã tải. Nếu ACP không khả dụng, +system prompt và Plugin skills không nên dạy agent về định tuyến ACP. ## Triển khai chỉ dùng Codex -Ép dùng harness Codex khi bạn cần chứng minh rằng mọi lượt agent nhúng đều -dùng Codex. Runtime Plugin rõ ràng đóng lỗi và không bao giờ được âm thầm thử lại -qua PI: +Ép dùng harness Codex khi bạn cần chứng minh rằng mọi lượt agent nhúng đều dùng +Codex. Runtime Plugin rõ ràng sẽ đóng thất bại và không bao giờ được âm thầm thử +lại qua PI: ```json5 { @@ -384,19 +384,19 @@ qua PI: } ``` -Ghi đè môi trường: +Ghi đè bằng môi trường: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Khi Codex bị ép buộc, OpenClaw thất bại sớm nếu Plugin Codex bị tắt, app-server -quá cũ, hoặc app-server không thể khởi động. +Khi Codex bị ép buộc, OpenClaw thất bại sớm nếu Plugin Codex bị tắt, +app-server quá cũ, hoặc app-server không thể khởi động. ## Codex theo từng agent -Bạn có thể biến một agent thành chỉ dùng Codex trong khi agent mặc định giữ -tự động chọn thông thường: +Bạn có thể làm cho một agent chỉ dùng Codex trong khi agent mặc định vẫn giữ +cơ chế tự chọn thông thường: ```json5 { @@ -425,21 +425,21 @@ tự động chọn thông thường: } ``` -Dùng các lệnh phiên thông thường để chuyển agent và mô hình. `/new` tạo một phiên -OpenClaw mới và harness Codex tạo hoặc tiếp tục thread app-server sidecar của nó -khi cần. `/reset` xóa ràng buộc phiên OpenClaw cho thread đó và cho phép lượt tiếp theo -phân giải harness lại từ cấu hình hiện tại. +Dùng các lệnh phiên thông thường để chuyển agent và mô hình. `/new` tạo một +phiên OpenClaw mới và harness Codex tạo hoặc tiếp tục thread app-server sidecar +của nó khi cần. `/reset` xóa binding phiên OpenClaw cho thread đó và cho phép +lượt tiếp theo phân giải harness từ cấu hình hiện tại lần nữa. ## Khám phá mô hình -Theo mặc định, Plugin Codex hỏi app-server về các mô hình khả dụng. Nếu việc khám phá -thất bại hoặc hết thời gian, nó dùng danh mục dự phòng đi kèm cho: +Theo mặc định, Plugin Codex hỏi app-server về các mô hình khả dụng. Nếu khám phá +thất bại hoặc hết thời gian, nó dùng catalog fallback đi kèm cho: - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -Bạn có thể tinh chỉnh khám phá dưới `plugins.entries.codex.config.discovery`: +Bạn có thể điều chỉnh khám phá trong `plugins.entries.codex.config.discovery`: ```json5 { @@ -459,8 +459,8 @@ Bạn có thể tinh chỉnh khám phá dưới `plugins.entries.codex.config.di } ``` -Tắt khám phá khi bạn muốn khởi động tránh thăm dò Codex và bám theo danh mục -dự phòng: +Tắt khám phá khi bạn muốn quá trình khởi động tránh thăm dò Codex và chỉ dùng +catalog fallback: ```json5 { @@ -487,17 +487,18 @@ Theo mặc định, Plugin khởi động binary Codex do OpenClaw quản lý c codex app-server --listen stdio:// ``` -Binary được quản lý được phát hành cùng gói Plugin `codex`. Điều này giữ phiên bản -app-server gắn với Plugin đi kèm thay vì bất kỳ Codex CLI riêng nào tình cờ được -cài cục bộ. Chỉ đặt `appServer.command` khi bạn chủ ý muốn chạy một executable khác. +Binary được quản lý được đóng gói cùng gói Plugin `codex`. Điều này giữ phiên +bản app-server gắn với Plugin đi kèm thay vì bất kỳ Codex CLI riêng nào tình cờ +được cài đặt cục bộ. Chỉ đặt `appServer.command` khi bạn cố ý muốn chạy một tệp +thực thi khác. Theo mặc định, OpenClaw khởi động các phiên harness Codex cục bộ ở chế độ YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"`, và -`sandbox: "danger-full-access"`. Đây là tư thế vận hành cục bộ đáng tin cậy dùng -cho Heartbeat tự trị: Codex có thể dùng công cụ shell và mạng mà không dừng lại ở -các lời nhắc phê duyệt gốc khi không có ai ở đó để trả lời. +`sandbox: "danger-full-access"`. Đây là tư thế vận hành cục bộ đáng tin cậy được +dùng cho Heartbeat tự động: Codex có thể dùng shell và công cụ mạng mà không +dừng ở các prompt phê duyệt gốc khi không có ai ở đó để trả lời. -Để chọn dùng phê duyệt do guardian của Codex xét duyệt, đặt `appServer.mode: +Để chọn dùng phê duyệt do guardian của Codex rà soát, đặt `appServer.mode: "guardian"`: ```json5 @@ -518,20 +519,21 @@ các lời nhắc phê duyệt gốc khi không có ai ở đó để trả lờ } ``` -Chế độ Guardian dùng đường dẫn phê duyệt tự động xét duyệt gốc của Codex. Khi Codex yêu cầu -rời sandbox, ghi ra ngoài workspace, hoặc thêm quyền như truy cập mạng, Codex định tuyến -yêu cầu phê duyệt đó đến reviewer gốc thay vì lời nhắc cho con người. Reviewer áp dụng -khung rủi ro của Codex và phê duyệt hoặc từ chối yêu cầu cụ thể. Dùng Guardian khi bạn -muốn nhiều hàng rào bảo vệ hơn chế độ YOLO nhưng vẫn cần agent không người giám sát -tiếp tục tiến triển. +Chế độ Guardian dùng đường dẫn phê duyệt auto-review gốc của Codex. Khi Codex +yêu cầu rời sandbox, ghi bên ngoài workspace, hoặc thêm quyền như truy cập mạng, +Codex định tuyến yêu cầu phê duyệt đó tới reviewer gốc thay vì prompt cho con +người. Reviewer áp dụng khung rủi ro của Codex và phê duyệt hoặc từ chối yêu cầu +cụ thể. Dùng Guardian khi bạn muốn nhiều rào chắn hơn chế độ YOLO nhưng vẫn cần +agent không có người giám sát tiếp tục tiến triển. Preset `guardian` mở rộng thành `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"`, và `sandbox: "workspace-write"`. -Các trường chính sách riêng lẻ vẫn ghi đè `mode`, nên triển khai nâng cao có thể kết hợp -preset với lựa chọn rõ ràng. Giá trị reviewer cũ hơn `guardian_subagent` vẫn được chấp nhận -như một bí danh tương thích, nhưng cấu hình mới nên dùng `auto_review`. +Các trường chính sách riêng lẻ vẫn ghi đè `mode`, vì vậy các triển khai nâng cao +có thể kết hợp preset với lựa chọn rõ ràng. Giá trị reviewer cũ +`guardian_subagent` vẫn được chấp nhận như một alias tương thích, nhưng cấu hình +mới nên dùng `auto_review`. -Đối với app-server đang chạy sẵn, dùng transport WebSocket: +Đối với app-server đã chạy, dùng transport WebSocket: ```json5 { @@ -553,18 +555,19 @@ như một bí danh tương thích, nhưng cấu hình mới nên dùng `auto_re } ``` -Các lần khởi chạy app-server stdio mặc định kế thừa môi trường tiến trình của OpenClaw, -nhưng OpenClaw sở hữu cầu nối tài khoản app-server Codex và đặt cả -`CODEX_HOME` lẫn `HOME` thành thư mục theo từng agent dưới trạng thái OpenClaw của agent đó. -Bộ nạp skill riêng của Codex đọc `$CODEX_HOME/skills` và -`$HOME/.agents/skills`, nên cả hai giá trị đều được biệt lập cho các lần khởi chạy -app-server cục bộ. Điều đó giữ skills gốc của Codex, plugins, cấu hình, tài khoản và -trạng thái thread nằm trong phạm vi agent OpenClaw thay vì rò rỉ từ home Codex CLI -cá nhân của người vận hành. +Các lần khởi chạy app-server stdio kế thừa môi trường tiến trình của OpenClaw +theo mặc định, nhưng OpenClaw sở hữu cầu nối tài khoản Codex app-server và đặt cả +`CODEX_HOME` lẫn `HOME` thành các thư mục theo từng agent dưới trạng thái +OpenClaw của agent đó. Trình tải skill riêng của Codex đọc `$CODEX_HOME/skills` +và `$HOME/.agents/skills`, nên cả hai giá trị đều được cô lập cho các lần khởi +chạy app-server cục bộ. Điều đó giữ skills, Plugin, cấu hình, tài khoản và trạng +thái thread gốc của Codex trong phạm vi agent OpenClaw thay vì rò rỉ từ home +Codex CLI cá nhân của operator. -OpenClaw plugins và snapshot skill OpenClaw vẫn đi qua registry Plugin và bộ nạp skill -riêng của OpenClaw. Tài sản Codex CLI cá nhân thì không. Nếu bạn có skills hoặc plugins -Codex CLI hữu ích cần trở thành một phần của agent OpenClaw, hãy kiểm kê chúng rõ ràng: +Các Plugin OpenClaw và snapshot skill OpenClaw vẫn đi qua registry Plugin và +trình tải skill riêng của OpenClaw. Tài sản Codex CLI cá nhân thì không. Nếu bạn +có skills hoặc Plugin Codex CLI hữu ích nên trở thành một phần của agent +OpenClaw, hãy kiểm kê chúng rõ ràng: ```bash openclaw migrate codex --dry-run @@ -572,28 +575,28 @@ openclaw migrate apply codex --yes ``` Provider di trú Codex sao chép skills vào workspace agent OpenClaw hiện tại. -Plugins gốc của Codex, hooks và tệp cấu hình được báo cáo hoặc lưu trữ để xem xét thủ công -thay vì được kích hoạt tự động, vì chúng có thể thực thi lệnh, phơi bày máy chủ MCP, -hoặc mang thông tin xác thực. +Plugin gốc của Codex, hook và tệp cấu hình được báo cáo hoặc lưu trữ để rà soát +thủ công thay vì được kích hoạt tự động, vì chúng có thể thực thi lệnh, phơi bày +máy chủ MCP, hoặc mang thông tin xác thực. Xác thực được chọn theo thứ tự này: -1. Một hồ sơ xác thực Codex OpenClaw rõ ràng cho agent. +1. Một hồ sơ xác thực OpenClaw Codex rõ ràng cho agent. 2. Tài khoản hiện có của app-server trong home Codex của agent đó. -3. Chỉ với các lần khởi chạy app-server stdio cục bộ, `CODEX_API_KEY`, rồi - `OPENAI_API_KEY`, khi không có tài khoản app-server nào hiện diện và xác thực OpenAI - vẫn bắt buộc. +3. Chỉ đối với các lần khởi chạy app-server stdio cục bộ, `CODEX_API_KEY`, rồi + `OPENAI_API_KEY`, khi không có tài khoản app-server và xác thực OpenAI vẫn + được yêu cầu. -Khi OpenClaw thấy một hồ sơ xác thực Codex kiểu gói đăng ký ChatGPT, nó loại bỏ -`CODEX_API_KEY` và `OPENAI_API_KEY` khỏi tiến trình con Codex được spawn. Điều đó giữ -các khóa API cấp Gateway khả dụng cho embeddings hoặc mô hình OpenAI trực tiếp -mà không vô tình khiến các lượt app-server Codex gốc bị tính phí qua API. -Hồ sơ khóa API Codex rõ ràng và dự phòng env-key stdio cục bộ dùng đăng nhập app-server -thay vì env tiến trình con kế thừa. Các kết nối app-server WebSocket không nhận dự phòng -khóa API env của Gateway; hãy dùng một hồ sơ xác thực rõ ràng hoặc tài khoản riêng của -app-server từ xa. +Khi OpenClaw thấy một hồ sơ xác thực Codex kiểu đăng ký ChatGPT, nó loại bỏ +`CODEX_API_KEY` và `OPENAI_API_KEY` khỏi tiến trình con Codex được spawn. Điều đó +giữ các khóa API cấp Gateway khả dụng cho embeddings hoặc mô hình OpenAI trực +tiếp mà không vô tình khiến các lượt app-server Codex gốc tính phí qua API. Hồ +sơ khóa API Codex rõ ràng và fallback env-key stdio cục bộ dùng đăng nhập +app-server thay vì env tiến trình con được kế thừa. Kết nối app-server WebSocket +không nhận fallback khóa API env của Gateway; hãy dùng một hồ sơ xác thực rõ ràng +hoặc tài khoản riêng của app-server từ xa. -Nếu một triển khai cần cô lập môi trường bổ sung, thêm các biến đó vào +Nếu một triển khai cần cô lập môi trường bổ sung, hãy thêm các biến đó vào `appServer.clearEnv`: ```json5 @@ -613,52 +616,51 @@ Nếu một triển khai cần cô lập môi trường bổ sung, thêm các bi } ``` -`appServer.clearEnv` chỉ ảnh hưởng đến tiến trình con app-server Codex được tạo ra. +`appServer.clearEnv` chỉ ảnh hưởng đến tiến trình con app-server Codex được sinh ra. Các công cụ động của Codex mặc định dùng hồ sơ `native-first`. Ở chế độ đó, -OpenClaw không hiển thị các công cụ động trùng lặp với các thao tác workspace -gốc của Codex: `read`, `write`, `edit`, `apply_patch`, `exec`, `process` và +OpenClaw không hiển thị các công cụ động trùng lặp với các thao tác không gian làm việc +gốc của Codex: `read`, `write`, `edit`, `apply_patch`, `exec`, `process`, và `update_plan`. Các công cụ tích hợp OpenClaw như nhắn tin, phiên, phương tiện, -cron, trình duyệt, node, gateway, `heartbeat_respond` và `web_search` vẫn +cron, trình duyệt, nút, Gateway, `heartbeat_respond`, và `web_search` vẫn khả dụng. Các trường Plugin Codex cấp cao nhất được hỗ trợ: -| Trường | Mặc định | Ý nghĩa | -| -------------------------- | ---------------- | --------------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | Dùng `"openclaw-compat"` để hiển thị toàn bộ bộ công cụ động OpenClaw cho app-server Codex. | -| `codexDynamicToolsExclude` | `[]` | Tên các công cụ động OpenClaw bổ sung cần bỏ qua trong các lượt app-server Codex. | +| Trường | Mặc định | Ý nghĩa | +| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- | +| `codexDynamicToolsProfile` | `"native-first"` | Dùng `"openclaw-compat"` để hiển thị toàn bộ bộ công cụ động OpenClaw cho app-server Codex. | +| `codexDynamicToolsExclude` | `[]` | Tên công cụ động OpenClaw bổ sung cần bỏ qua trong các lượt của app-server Codex. | Các trường `appServer` được hỗ trợ: -| Trường | Mặc định | Ý nghĩa | -| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` tạo Codex; `"websocket"` kết nối tới `url`. | -| `command` | tệp nhị phân Codex được quản lý | Tệp thực thi cho transport stdio. Để trống để dùng tệp nhị phân được quản lý; chỉ đặt trường này khi cần ghi đè rõ ràng. | -| `args` | `["app-server", "--listen", "stdio://"]` | Đối số cho transport stdio. | -| `url` | chưa đặt | URL app-server WebSocket. | -| `authToken` | chưa đặt | Bearer token cho transport WebSocket. | -| `headers` | `{}` | Header WebSocket bổ sung. | -| `clearEnv` | `[]` | Tên biến môi trường bổ sung bị xóa khỏi tiến trình app-server stdio được tạo sau khi OpenClaw xây dựng môi trường kế thừa. `CODEX_HOME` và `HOME` được dành riêng cho cô lập Codex theo từng agent của OpenClaw khi khởi chạy cục bộ. | -| `requestTimeoutMs` | `60000` | Thời gian chờ cho các lệnh gọi control plane app-server. | -| `mode` | `"yolo"` | Cấu hình sẵn cho thực thi YOLO hoặc được guardian duyệt. | -| `approvalPolicy` | `"never"` | Chính sách phê duyệt Codex gốc được gửi tới lúc bắt đầu/tiếp tục/lượt của luồng. | -| `sandbox` | `"danger-full-access"` | Chế độ sandbox Codex gốc được gửi tới lúc bắt đầu/tiếp tục luồng. | -| `approvalsReviewer` | `"user"` | Dùng `"auto_review"` để cho Codex xem xét các lời nhắc phê duyệt gốc. `guardian_subagent` vẫn là bí danh cũ. | -| `serviceTier` | chưa đặt | Tầng dịch vụ app-server Codex tùy chọn: `"fast"`, `"flex"` hoặc `null`. Các giá trị cũ không hợp lệ sẽ bị bỏ qua. | +| Trường | Mặc định | Ý nghĩa | +| ------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` sinh ra Codex; `"websocket"` kết nối đến `url`. | +| `command` | tệp nhị phân Codex được quản lý | Tệp thực thi cho transport stdio. Để trống để dùng tệp nhị phân được quản lý; chỉ đặt trường này khi cần ghi đè rõ ràng. | +| `args` | `["app-server", "--listen", "stdio://"]` | Đối số cho transport stdio. | +| `url` | chưa đặt | URL app-server WebSocket. | +| `authToken` | chưa đặt | Mã Bearer token cho transport WebSocket. | +| `headers` | `{}` | Header WebSocket bổ sung. | +| `clearEnv` | `[]` | Tên biến môi trường bổ sung được xóa khỏi tiến trình app-server stdio được sinh ra sau khi OpenClaw dựng môi trường kế thừa. `CODEX_HOME` và `HOME` được dành riêng cho cơ chế cô lập Codex theo từng tác nhân của OpenClaw khi khởi chạy cục bộ. | +| `requestTimeoutMs` | `60000` | Thời gian chờ cho các lệnh gọi control-plane của app-server. | +| `mode` | `"yolo"` | Thiết lập sẵn cho thực thi YOLO hoặc thực thi được guardian đánh giá. | +| `approvalPolicy` | `"never"` | Chính sách phê duyệt Codex gốc được gửi đến thao tác bắt đầu/tiếp tục/lượt của luồng. | +| `sandbox` | `"danger-full-access"` | Chế độ sandbox Codex gốc được gửi đến thao tác bắt đầu/tiếp tục luồng. | +| `approvalsReviewer` | `"user"` | Dùng `"auto_review"` để cho Codex đánh giá các lời nhắc phê duyệt gốc. `guardian_subagent` vẫn là bí danh cũ. | +| `serviceTier` | chưa đặt | Tầng dịch vụ app-server Codex tùy chọn: `"fast"`, `"flex"`, hoặc `null`. Các giá trị cũ không hợp lệ sẽ bị bỏ qua. | Các lệnh gọi công cụ động do OpenClaw sở hữu được giới hạn độc lập với -`appServer.requestTimeoutMs`: mỗi yêu cầu `item/tool/call` của Codex phải nhận -phản hồi OpenClaw trong vòng 30 giây. Khi hết thời gian chờ, OpenClaw hủy tín -hiệu công cụ ở nơi được hỗ trợ và trả về phản hồi công cụ động thất bại cho -Codex để lượt có thể tiếp tục thay vì để phiên ở trạng thái `processing`. +`appServer.requestTimeoutMs`: mỗi yêu cầu Codex `item/tool/call` phải nhận được +phản hồi OpenClaw trong vòng 30 giây. Khi hết thời gian chờ, OpenClaw hủy tín hiệu +công cụ ở nơi được hỗ trợ và trả về phản hồi công cụ động thất bại cho Codex để +lượt có thể tiếp tục thay vì để phiên ở trạng thái `processing`. -Sau khi OpenClaw phản hồi một yêu cầu app-server theo phạm vi lượt của Codex, -harness cũng kỳ vọng Codex kết thúc lượt gốc bằng `turn/completed`. Nếu -app-server im lặng trong 60 giây sau phản hồi đó, OpenClaw sẽ cố gắng hết mức -để ngắt lượt Codex, ghi lại chẩn đoán hết thời gian chờ và giải phóng làn phiên -OpenClaw để các tin nhắn trò chuyện tiếp theo không bị xếp hàng sau một lượt -gốc đã cũ. +Sau khi OpenClaw phản hồi một yêu cầu app-server theo phạm vi lượt của Codex, harness +cũng kỳ vọng Codex hoàn tất lượt gốc bằng `turn/completed`. Nếu app-server im lặng +trong 60 giây sau phản hồi đó, OpenClaw cố gắng ngắt lượt Codex, ghi lại chẩn đoán +hết thời gian chờ, và giải phóng làn phiên OpenClaw để các tin nhắn trò chuyện tiếp theo +không bị xếp hàng sau một lượt gốc đã cũ. Các ghi đè môi trường vẫn khả dụng cho kiểm thử cục bộ: @@ -671,26 +673,26 @@ Các ghi đè môi trường vẫn khả dụng cho kiểm thử cục bộ: `OPENCLAW_CODEX_APP_SERVER_BIN` bỏ qua tệp nhị phân được quản lý khi `appServer.command` chưa được đặt. -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` đã bị xóa. Thay vào đó, hãy dùng +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` đã bị xóa. Thay vào đó hãy dùng `plugins.entries.codex.config.appServer.mode: "guardian"`, hoặc `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` cho kiểm thử cục bộ một lần. Cấu hình được ưu tiên cho các triển khai có thể lặp lại vì nó giữ hành vi Plugin trong -cùng tệp đã được duyệt như phần còn lại của thiết lập harness Codex. +cùng tệp đã được đánh giá với phần còn lại của thiết lập harness Codex. ## Sử dụng máy tính -Sử dụng máy tính được trình bày trong hướng dẫn thiết lập riêng: -[Codex sử dụng máy tính](/vi/plugins/codex-computer-use). +Computer Use được trình bày trong hướng dẫn thiết lập riêng: +[Codex Computer Use](/vi/plugins/codex-computer-use). -Bản ngắn gọn: OpenClaw không đóng gói ứng dụng điều khiển desktop hoặc tự thực -thi các hành động desktop. OpenClaw chuẩn bị app-server Codex, xác minh rằng -MCP server `computer-use` khả dụng, rồi để Codex xử lý các lệnh gọi công cụ MCP +Tóm tắt: OpenClaw không vendor ứng dụng điều khiển máy tính để bàn hoặc tự thực thi +các hành động trên máy tính để bàn. Nó chuẩn bị app-server Codex, xác minh rằng +máy chủ MCP `computer-use` khả dụng, rồi để Codex xử lý các lệnh gọi công cụ MCP gốc trong các lượt chế độ Codex. -Để truy cập trực tiếp driver TryCua bên ngoài luồng marketplace Codex, hãy đăng -ký `cua-driver mcp` bằng `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Xem [Codex sử dụng máy tính](/vi/plugins/codex-computer-use) để biết sự khác biệt -giữa Sử dụng máy tính do Codex sở hữu và đăng ký MCP trực tiếp. +Để truy cập trực tiếp driver TryCua bên ngoài luồng marketplace Codex, hãy đăng ký +`cua-driver mcp` bằng `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Xem [Codex Computer Use](/vi/plugins/codex-computer-use) để biết sự khác biệt +giữa Computer Use do Codex sở hữu và đăng ký MCP trực tiếp. Cấu hình tối thiểu: @@ -726,20 +728,19 @@ Có thể kiểm tra hoặc cài đặt thiết lập từ bề mặt lệnh: - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Sử dụng máy tính chỉ dành cho macOS và có thể cần quyền hệ điều hành cục bộ -trước khi MCP server Codex có thể điều khiển ứng dụng. Nếu `computerUse.enabled` -là true và MCP server không khả dụng, các lượt chế độ Codex sẽ thất bại trước -khi luồng bắt đầu thay vì âm thầm chạy mà không có các công cụ Sử dụng máy tính -gốc. Xem [Codex sử dụng máy tính](/vi/plugins/codex-computer-use) để biết các lựa -chọn marketplace, giới hạn catalog từ xa, lý do trạng thái và cách khắc phục sự -cố. +Computer Use dành riêng cho macOS và có thể yêu cầu quyền hệ điều hành cục bộ trước khi +máy chủ MCP Codex có thể điều khiển ứng dụng. Nếu `computerUse.enabled` là true và máy chủ MCP +không khả dụng, các lượt chế độ Codex sẽ thất bại trước khi luồng bắt đầu thay vì +âm thầm chạy mà không có các công cụ Computer Use gốc. Xem +[Codex Computer Use](/vi/plugins/codex-computer-use) để biết các lựa chọn marketplace, +giới hạn danh mục từ xa, lý do trạng thái, và cách khắc phục sự cố. Khi `computerUse.autoInstall` là true, OpenClaw có thể đăng ký marketplace -Codex Desktop chuẩn được đóng gói từ +Codex Desktop đóng gói tiêu chuẩn từ `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` nếu Codex chưa phát hiện marketplace cục bộ. Dùng `/new` hoặc `/reset` sau khi thay đổi -cấu hình runtime hoặc Sử dụng máy tính để các phiên hiện có không giữ ràng buộc -PI hoặc luồng Codex cũ. +cấu hình runtime hoặc Computer Use để các phiên hiện có không giữ liên kết PI +hoặc luồng Codex cũ. ## Công thức phổ biến @@ -757,7 +758,7 @@ Codex cục bộ với transport stdio mặc định: } ``` -Xác thực harness chỉ Codex: +Xác thực harness chỉ dành cho Codex: ```json5 { @@ -779,7 +780,7 @@ Xác thực harness chỉ Codex: } ``` -Phê duyệt Codex được guardian duyệt: +Phê duyệt Codex được guardian đánh giá: ```json5 { @@ -824,113 +825,113 @@ App-server từ xa với header rõ ràng: } ``` -Việc chuyển đổi mô hình vẫn do OpenClaw kiểm soát. Khi một phiên OpenClaw được -gắn với một luồng Codex hiện có, lượt tiếp theo gửi lại mô hình OpenAI, nhà -cung cấp, chính sách phê duyệt, sandbox và tầng dịch vụ hiện được chọn tới -app-server. Chuyển từ `openai/gpt-5.5` sang `openai/gpt-5.2` giữ ràng buộc -luồng nhưng yêu cầu Codex tiếp tục với mô hình mới được chọn. +Chuyển đổi mô hình vẫn do OpenClaw kiểm soát. Khi một phiên OpenClaw được gắn +vào một luồng Codex hiện có, lượt tiếp theo sẽ gửi lại mô hình OpenAI, nhà cung cấp, +chính sách phê duyệt, sandbox, và tầng dịch vụ hiện được chọn đến app-server. +Chuyển từ `openai/gpt-5.5` sang `openai/gpt-5.2` giữ liên kết luồng nhưng yêu cầu +Codex tiếp tục với mô hình mới được chọn. ## Lệnh Codex -Plugin được đóng gói đăng ký `/codex` làm lệnh gạch chéo được ủy quyền. Lệnh -này mang tính chung và hoạt động trên bất kỳ kênh nào hỗ trợ lệnh văn bản -OpenClaw. +Plugin đóng gói đăng ký `/codex` làm lệnh gạch chéo được ủy quyền. Lệnh này có +tính tổng quát và hoạt động trên mọi kênh hỗ trợ lệnh văn bản OpenClaw. Các dạng phổ biến: -- `/codex status` hiển thị kết nối máy chủ ứng dụng trực tiếp, mô hình, tài khoản, giới hạn tốc độ, máy chủ MCP và skills. +- `/codex status` hiển thị kết nối máy chủ ứng dụng trực tiếp, mô hình, tài khoản, giới hạn tốc độ, máy chủ MCP và Skills. - `/codex models` liệt kê các mô hình máy chủ ứng dụng Codex trực tiếp. - `/codex threads [filter]` liệt kê các luồng Codex gần đây. - `/codex resume ` gắn phiên OpenClaw hiện tại vào một luồng Codex hiện có. - `/codex compact` yêu cầu máy chủ ứng dụng Codex compact luồng đã gắn. -- `/codex review` bắt đầu đánh giá gốc của Codex cho luồng đã gắn. +- `/codex review` bắt đầu quy trình đánh giá gốc của Codex cho luồng đã gắn. - `/codex diagnostics [note]` hỏi trước khi gửi phản hồi chẩn đoán Codex cho luồng đã gắn. -- `/codex computer-use status` kiểm tra Plugin Computer Use đã cấu hình và máy chủ MCP. +- `/codex computer-use status` kiểm tra Plugin Computer Use và máy chủ MCP đã cấu hình. - `/codex computer-use install` cài đặt Plugin Computer Use đã cấu hình và tải lại các máy chủ MCP. - `/codex account` hiển thị trạng thái tài khoản và giới hạn tốc độ. - `/codex mcp` liệt kê trạng thái máy chủ MCP của máy chủ ứng dụng Codex. -- `/codex skills` liệt kê skills của máy chủ ứng dụng Codex. +- `/codex skills` liệt kê Skills của máy chủ ứng dụng Codex. + +Khi Codex báo lỗi giới hạn mức sử dụng, OpenClaw sẽ bao gồm thời điểm đặt lại +tiếp theo của máy chủ ứng dụng nếu Codex cung cấp. Dùng `/codex account` trong cùng +cuộc trò chuyện để kiểm tra tài khoản hiện tại và các khoảng giới hạn tốc độ. ### Quy trình gỡ lỗi phổ biến -Khi một agent dựa trên Codex làm điều gì đó bất ngờ trong Telegram, Discord, Slack, -hoặc một kênh khác, hãy bắt đầu với cuộc hội thoại nơi sự cố xảy ra: +Khi một agent dùng Codex làm điều gì đó bất ngờ trong Telegram, Discord, Slack, +hoặc một kênh khác, hãy bắt đầu từ cuộc trò chuyện nơi sự cố xảy ra: 1. Chạy `/diagnostics bad tool choice after image upload` hoặc một ghi chú ngắn khác mô tả điều bạn đã thấy. -2. Phê duyệt yêu cầu chẩn đoán một lần. Việc phê duyệt tạo tệp zip chẩn đoán Gateway - cục bộ và, vì phiên đang dùng harness Codex, cũng - gửi gói phản hồi Codex liên quan đến máy chủ OpenAI. +2. Phê duyệt yêu cầu chẩn đoán một lần. Việc phê duyệt sẽ tạo tệp zip chẩn đoán + Gateway cục bộ và, vì phiên đang dùng harness Codex, cũng gửi gói phản hồi + Codex liên quan đến máy chủ OpenAI. 3. Sao chép phản hồi chẩn đoán đã hoàn tất vào báo cáo lỗi hoặc luồng hỗ trợ. Phản hồi này bao gồm đường dẫn gói cục bộ, tóm tắt quyền riêng tư, id phiên OpenClaw, id luồng Codex và một dòng `Inspect locally` cho mỗi luồng Codex. -4. Nếu bạn muốn tự gỡ lỗi lần chạy, hãy chạy lệnh `Inspect locally` được in ra - trong terminal. Lệnh trông giống `codex resume ` và mở - luồng Codex gốc để bạn có thể kiểm tra cuộc hội thoại, tiếp tục cục bộ, +4. Nếu bạn muốn tự gỡ lỗi lượt chạy, hãy chạy lệnh `Inspect locally` được in ra + trong terminal. Lệnh trông giống `codex resume ` và mở luồng Codex + gốc để bạn có thể kiểm tra cuộc trò chuyện, tiếp tục nó cục bộ, hoặc hỏi Codex vì sao nó chọn một công cụ hoặc kế hoạch cụ thể. Chỉ dùng `/codex diagnostics [note]` khi bạn đặc biệt muốn tải phản hồi Codex -lên cho luồng hiện đang gắn mà không có toàn bộ gói chẩn đoán OpenClaw -Gateway. Với hầu hết báo cáo hỗ trợ, `/diagnostics [note]` là -điểm bắt đầu tốt hơn vì nó liên kết trạng thái Gateway cục bộ và id luồng Codex -trong cùng một phản hồi. Xem [Xuất chẩn đoán](/vi/gateway/diagnostics) -để biết đầy đủ mô hình quyền riêng tư và hành vi trong nhóm chat. +lên cho luồng hiện đang gắn mà không có toàn bộ gói chẩn đoán Gateway của OpenClaw. +Với hầu hết báo cáo hỗ trợ, `/diagnostics [note]` là điểm bắt đầu tốt hơn vì nó +gắn trạng thái Gateway cục bộ và id luồng Codex với nhau trong một phản hồi. Xem +[Xuất chẩn đoán](/vi/gateway/diagnostics) để biết đầy đủ mô hình quyền riêng tư và +hành vi trong nhóm trò chuyện. -OpenClaw lõi cũng cung cấp `/diagnostics [note]` chỉ dành cho chủ sở hữu làm lệnh chẩn đoán -Gateway chung. Lời nhắc phê duyệt của lệnh hiển thị phần mở đầu về dữ liệu nhạy cảm, -liên kết đến [Xuất Chẩn Đoán](/vi/gateway/diagnostics), và yêu cầu +Phần lõi OpenClaw cũng cung cấp `/diagnostics [note]` chỉ dành cho chủ sở hữu như +lệnh chẩn đoán Gateway chung. Lời nhắc phê duyệt của lệnh hiển thị phần mở đầu về +dữ liệu nhạy cảm, liên kết đến [Xuất chẩn đoán](/vi/gateway/diagnostics), và yêu cầu `openclaw gateway diagnostics export --json` thông qua phê duyệt thực thi rõ ràng mỗi lần. Không phê duyệt chẩn đoán bằng quy tắc cho phép tất cả. Sau khi phê duyệt, -OpenClaw gửi một báo cáo có thể dán với đường dẫn gói cục bộ và tóm tắt -manifest. Khi phiên OpenClaw đang hoạt động dùng harness Codex, cùng -phê duyệt đó cũng cho phép gửi các gói phản hồi Codex liên quan đến -máy chủ OpenAI. Lời nhắc phê duyệt nói rằng phản hồi Codex sẽ được gửi, nhưng -không liệt kê id phiên hoặc luồng Codex trước khi phê duyệt. +OpenClaw gửi một báo cáo có thể dán lại với đường dẫn gói cục bộ và tóm tắt manifest. +Khi phiên OpenClaw đang hoạt động dùng harness Codex, cùng phê duyệt đó cũng cho phép +gửi các gói phản hồi Codex liên quan đến máy chủ OpenAI. Lời nhắc phê duyệt nói rằng +phản hồi Codex sẽ được gửi, nhưng không liệt kê id phiên hoặc luồng Codex trước khi +phê duyệt. -Nếu `/diagnostics` được một chủ sở hữu gọi trong nhóm chat, OpenClaw giữ cho -kênh chung gọn gàng: nhóm chỉ nhận một thông báo ngắn, trong khi -phần mở đầu chẩn đoán, lời nhắc phê duyệt, và id phiên/luồng Codex được gửi đến -chủ sở hữu qua tuyến phê duyệt riêng tư. Nếu không có tuyến riêng tư đến chủ sở hữu, -OpenClaw từ chối yêu cầu trong nhóm và yêu cầu chủ sở hữu chạy lệnh từ DM. +Nếu `/diagnostics` được một chủ sở hữu gọi trong nhóm trò chuyện, OpenClaw giữ kênh +chung gọn gàng: nhóm chỉ nhận một thông báo ngắn, còn phần mở đầu chẩn đoán, lời nhắc +phê duyệt và id phiên/luồng Codex được gửi cho chủ sở hữu qua tuyến phê duyệt riêng. +Nếu không có tuyến riêng cho chủ sở hữu, OpenClaw từ chối yêu cầu trong nhóm và yêu cầu +chủ sở hữu chạy lệnh đó từ DM. -Lần tải Codex đã được phê duyệt gọi `feedback/upload` của máy chủ ứng dụng Codex và yêu cầu -máy chủ ứng dụng bao gồm nhật ký cho từng luồng được liệt kê và các luồng con Codex đã sinh -khi có. Lần tải đi qua đường dẫn phản hồi bình thường của Codex đến máy chủ OpenAI; -nếu phản hồi Codex bị tắt trong máy chủ ứng dụng đó, lệnh trả về -lỗi máy chủ ứng dụng. Phản hồi chẩn đoán đã hoàn tất liệt kê các kênh, -id phiên OpenClaw, id luồng Codex, và các lệnh `codex resume ` -cục bộ cho các luồng đã được gửi. Nếu bạn từ chối hoặc bỏ qua phê duyệt, -OpenClaw không in các id Codex đó. Lần tải này không thay thế bản xuất chẩn đoán -Gateway cục bộ. +Lần tải Codex đã phê duyệt sẽ gọi `feedback/upload` của máy chủ ứng dụng Codex và yêu cầu +máy chủ ứng dụng đưa vào nhật ký cho từng luồng được liệt kê và các luồng con Codex đã tạo +khi có sẵn. Việc tải lên đi qua đường phản hồi bình thường của Codex đến máy chủ OpenAI; +nếu phản hồi Codex bị tắt trong máy chủ ứng dụng đó, lệnh trả về lỗi máy chủ ứng dụng. +Phản hồi chẩn đoán đã hoàn tất liệt kê các kênh, id phiên OpenClaw, id luồng Codex và +các lệnh `codex resume ` cục bộ cho những luồng đã được gửi. Nếu bạn từ chối +hoặc bỏ qua phê duyệt, OpenClaw không in các id Codex đó. Việc tải lên này không thay thế +bản xuất chẩn đoán Gateway cục bộ. -`/codex resume` ghi cùng tệp liên kết sidecar mà harness dùng cho -các lượt bình thường. Ở tin nhắn tiếp theo, OpenClaw tiếp tục luồng Codex đó, truyền -mô hình OpenClaw hiện được chọn vào máy chủ ứng dụng, và giữ lịch sử mở rộng -được bật. +`/codex resume` ghi cùng tệp liên kết sidecar mà harness dùng cho các lượt bình thường. +Ở tin nhắn tiếp theo, OpenClaw tiếp tục luồng Codex đó, truyền mô hình OpenClaw hiện được chọn +vào máy chủ ứng dụng, và giữ lịch sử mở rộng được bật. ### Kiểm tra một luồng Codex từ CLI -Cách nhanh nhất để hiểu một lần chạy Codex lỗi thường là mở trực tiếp luồng Codex -gốc: +Cách nhanh nhất để hiểu một lượt chạy Codex lỗi thường là mở trực tiếp luồng Codex gốc: ```sh codex resume ``` -Dùng cách này khi bạn nhận thấy lỗi trong một cuộc hội thoại kênh và muốn kiểm tra -phiên Codex có vấn đề, tiếp tục phiên đó cục bộ, hoặc hỏi Codex vì sao nó đưa ra -một lựa chọn công cụ hoặc suy luận cụ thể. Đường đi dễ nhất thường là chạy -`/diagnostics [note]` trước: sau khi bạn phê duyệt, báo cáo đã hoàn tất liệt kê -từng luồng Codex và in một lệnh `Inspect locally`, ví dụ -`codex resume `. Bạn có thể sao chép trực tiếp lệnh đó vào terminal. +Dùng cách này khi bạn nhận thấy lỗi trong một cuộc trò chuyện kênh và muốn kiểm tra +phiên Codex có vấn đề, tiếp tục nó cục bộ, hoặc hỏi Codex vì sao nó đưa ra một lựa chọn +công cụ hoặc suy luận cụ thể. Đường đi dễ nhất thường là chạy `/diagnostics [note]` trước: +sau khi bạn phê duyệt, báo cáo hoàn tất sẽ liệt kê từng luồng Codex và in một lệnh +`Inspect locally`, ví dụ `codex resume `. Bạn có thể sao chép trực tiếp lệnh đó +vào terminal. -Bạn cũng có thể lấy id luồng từ `/codex binding` cho chat hiện tại hoặc -`/codex threads [filter]` cho các luồng máy chủ ứng dụng Codex gần đây, rồi chạy cùng -lệnh `codex resume` trong shell của bạn. +Bạn cũng có thể lấy id luồng từ `/codex binding` cho cuộc trò chuyện hiện tại hoặc +`/codex threads [filter]` cho các luồng máy chủ ứng dụng Codex gần đây, rồi chạy cùng lệnh +`codex resume` trong shell của bạn. -Bề mặt lệnh yêu cầu máy chủ ứng dụng Codex `0.125.0` hoặc mới hơn. Từng -phương thức điều khiển được báo cáo là `unsupported by this Codex app-server` nếu một -máy chủ ứng dụng tương lai hoặc tùy chỉnh không cung cấp phương thức JSON-RPC đó. +Bề mặt lệnh yêu cầu máy chủ ứng dụng Codex `0.125.0` trở lên. Các phương thức điều khiển +riêng lẻ được báo cáo là `unsupported by this Codex app-server` nếu một máy chủ ứng dụng +tùy chỉnh hoặc trong tương lai không cung cấp phương thức JSON-RPC đó. ## Ranh giới hook @@ -938,159 +939,157 @@ Harness Codex có ba lớp hook: | Lớp | Chủ sở hữu | Mục đích | | ------------------------------------ | ------------------------ | ------------------------------------------------------------------- | -| Hook Plugin OpenClaw | OpenClaw | Khả năng tương thích sản phẩm/Plugin trên các harness PI và Codex. | -| Middleware tiện ích mở rộng máy chủ ứng dụng Codex | Plugin đi kèm OpenClaw | Hành vi adapter theo từng lượt quanh các công cụ động OpenClaw. | +| Hook Plugin OpenClaw | OpenClaw | Tương thích sản phẩm/Plugin trên các harness PI và Codex. | +| Middleware phần mở rộng máy chủ ứng dụng Codex | Plugin đi kèm OpenClaw | Hành vi bộ chuyển đổi theo lượt quanh công cụ động OpenClaw. | | Hook gốc Codex | Codex | Vòng đời Codex cấp thấp và chính sách công cụ gốc từ cấu hình Codex. | -OpenClaw không dùng các tệp `hooks.json` Codex cấp dự án hoặc toàn cục để định tuyến -hành vi Plugin OpenClaw. Với cầu nối công cụ gốc và quyền được hỗ trợ, -OpenClaw tiêm cấu hình Codex theo từng luồng cho `PreToolUse`, `PostToolUse`, -`PermissionRequest`, và `Stop`. Các hook Codex khác như `SessionStart` và -`UserPromptSubmit` vẫn là điều khiển cấp Codex; chúng không được cung cấp như -hook Plugin OpenClaw trong hợp đồng v1. +OpenClaw không dùng các tệp `hooks.json` của dự án hoặc toàn cục Codex để định tuyến +hành vi Plugin OpenClaw. Với cầu nối công cụ gốc và quyền được hỗ trợ, OpenClaw tiêm +cấu hình Codex theo luồng cho `PreToolUse`, `PostToolUse`, `PermissionRequest`, và `Stop`. +Các hook Codex khác như `SessionStart` và `UserPromptSubmit` vẫn là điều khiển cấp Codex; +chúng không được cung cấp dưới dạng hook Plugin OpenClaw trong hợp đồng v1. -Với các công cụ động OpenClaw, OpenClaw thực thi công cụ sau khi Codex yêu cầu -lệnh gọi, nên OpenClaw kích hoạt hành vi Plugin và middleware mà nó sở hữu trong -adapter harness. Với các công cụ gốc của Codex, Codex sở hữu bản ghi công cụ chuẩn. -OpenClaw có thể phản chiếu một số sự kiện được chọn, nhưng không thể ghi lại luồng Codex -gốc trừ khi Codex cung cấp thao tác đó qua máy chủ ứng dụng hoặc callback hook gốc. +Với công cụ động OpenClaw, OpenClaw thực thi công cụ sau khi Codex yêu cầu lệnh gọi, +vì vậy OpenClaw kích hoạt hành vi Plugin và middleware mà nó sở hữu trong bộ chuyển đổi +harness. Với công cụ gốc Codex, Codex sở hữu bản ghi công cụ chuẩn. OpenClaw có thể phản chiếu +một số sự kiện được chọn, nhưng không thể viết lại luồng Codex gốc trừ khi Codex cung cấp +thao tác đó qua máy chủ ứng dụng hoặc callback hook gốc. -Các phép chiếu vòng đời Compaction và LLM đến từ thông báo máy chủ ứng dụng Codex -và trạng thái adapter OpenClaw, không phải từ lệnh hook Codex gốc. -Các sự kiện `before_compaction`, `after_compaction`, `llm_input`, và -`llm_output` của OpenClaw là quan sát cấp adapter, không phải bản ghi từng byte -của yêu cầu nội bộ hoặc payload Compaction của Codex. +Các phép chiếu Compaction và vòng đời LLM đến từ thông báo của máy chủ ứng dụng Codex +và trạng thái bộ chuyển đổi OpenClaw, không phải lệnh hook Codex gốc. Các sự kiện +`before_compaction`, `after_compaction`, `llm_input`, và `llm_output` của OpenClaw là +quan sát ở cấp bộ chuyển đổi, không phải bản chụp từng byte của yêu cầu nội bộ hoặc +payload Compaction của Codex. -Thông báo máy chủ ứng dụng `hook/started` và `hook/completed` gốc của Codex -được chiếu thành sự kiện agent `codex_app_server.hook` để phục vụ quỹ đạo và gỡ lỗi. -Chúng không gọi hook Plugin OpenClaw. +Thông báo máy chủ ứng dụng `hook/started` và `hook/completed` gốc Codex được chiếu thành +sự kiện agent `codex_app_server.hook` để phục vụ quỹ đạo và gỡ lỗi. Chúng không gọi +hook Plugin OpenClaw. ## Hợp đồng hỗ trợ V1 -Chế độ Codex không phải là PI với một lệnh gọi mô hình khác bên dưới. Codex sở hữu nhiều hơn -vòng lặp mô hình gốc, và OpenClaw điều chỉnh các bề mặt Plugin và phiên của mình -quanh ranh giới đó. +Chế độ Codex không phải là PI với một lệnh gọi mô hình khác nằm bên dưới. Codex sở hữu nhiều hơn +vòng lặp mô hình gốc, và OpenClaw điều chỉnh các bề mặt Plugin và phiên của mình quanh ranh giới đó. Được hỗ trợ trong runtime Codex v1: | Bề mặt | Hỗ trợ | Lý do | | -------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Vòng lặp mô hình OpenAI qua Codex | Được hỗ trợ | Máy chủ ứng dụng Codex sở hữu lượt OpenAI, tiếp tục luồng gốc, và tiếp tục công cụ gốc. | -| Định tuyến và phân phối kênh OpenClaw | Được hỗ trợ | Telegram, Discord, Slack, WhatsApp, iMessage, và các kênh khác nằm ngoài runtime mô hình. | -| Công cụ động OpenClaw | Được hỗ trợ | Codex yêu cầu OpenClaw thực thi các công cụ này, nên OpenClaw vẫn nằm trong đường dẫn thực thi. | -| Plugin prompt và ngữ cảnh | Được hỗ trợ | OpenClaw xây dựng các lớp phủ prompt và chiếu ngữ cảnh vào lượt Codex trước khi bắt đầu hoặc tiếp tục luồng. | -| Vòng đời công cụ ngữ cảnh | Được hỗ trợ | Tập hợp, nạp hoặc bảo trì sau lượt, và phối hợp Compaction của công cụ ngữ cảnh chạy cho các lượt Codex. | +| Vòng lặp mô hình OpenAI qua Codex | Được hỗ trợ | Máy chủ ứng dụng Codex sở hữu lượt OpenAI, tiếp tục luồng gốc và tiếp tục công cụ gốc. | +| Định tuyến và phân phối kênh OpenClaw | Được hỗ trợ | Telegram, Discord, Slack, WhatsApp, iMessage và các kênh khác vẫn nằm ngoài runtime mô hình. | +| Công cụ động OpenClaw | Được hỗ trợ | Codex yêu cầu OpenClaw thực thi các công cụ này, nên OpenClaw vẫn nằm trong đường thực thi. | +| Plugin nhắc lệnh và ngữ cảnh | Được hỗ trợ | OpenClaw xây dựng các lớp phủ nhắc lệnh và chiếu ngữ cảnh vào lượt Codex trước khi bắt đầu hoặc tiếp tục luồng. | +| Vòng đời công cụ ngữ cảnh | Được hỗ trợ | Lắp ráp, nạp hoặc bảo trì sau lượt, và phối hợp Compaction của công cụ ngữ cảnh chạy cho các lượt Codex. | | Hook công cụ động | Được hỗ trợ | `before_tool_call`, `after_tool_call`, và middleware kết quả công cụ chạy quanh các công cụ động do OpenClaw sở hữu. | -| Hook vòng đời | Được hỗ trợ dưới dạng quan sát adapter | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, và `after_compaction` kích hoạt với payload trung thực ở chế độ Codex. | -| Cổng chỉnh sửa câu trả lời cuối | Được hỗ trợ qua relay hook gốc | `Stop` của Codex được relay đến `before_agent_finalize`; `revise` yêu cầu Codex thực hiện thêm một lượt mô hình trước khi hoàn tất. | -| Chặn hoặc quan sát shell, patch và MCP gốc | Được hỗ trợ qua relay hook gốc | `PreToolUse` và `PostToolUse` của Codex được relay cho các bề mặt công cụ gốc đã cam kết, bao gồm payload MCP trên máy chủ ứng dụng Codex `0.125.0` hoặc mới hơn. Hỗ trợ chặn; không hỗ trợ ghi lại đối số. | -| Chính sách quyền gốc | Được hỗ trợ qua relay hook gốc | `PermissionRequest` của Codex có thể được định tuyến qua chính sách OpenClaw khi runtime cung cấp nó. Nếu OpenClaw không trả về quyết định nào, Codex tiếp tục qua guardian bình thường hoặc đường dẫn phê duyệt của người dùng. | -| Thu thập quỹ đạo máy chủ ứng dụng | Được hỗ trợ | OpenClaw ghi lại yêu cầu nó đã gửi đến máy chủ ứng dụng và các thông báo máy chủ ứng dụng mà nó nhận được. | +| Hook vòng đời | Được hỗ trợ dưới dạng quan sát bộ chuyển đổi | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, và `after_compaction` kích hoạt với payload trung thực của chế độ Codex. | +| Cổng sửa câu trả lời cuối | Được hỗ trợ qua relay hook gốc | `Stop` của Codex được relay đến `before_agent_finalize`; `revise` yêu cầu Codex thêm một lượt mô hình nữa trước khi hoàn tất. | +| Chặn hoặc quan sát shell, bản vá và MCP gốc | Được hỗ trợ qua relay hook gốc | `PreToolUse` và `PostToolUse` của Codex được relay cho các bề mặt công cụ gốc đã cam kết, bao gồm payload MCP trên máy chủ ứng dụng Codex `0.125.0` trở lên. Hỗ trợ chặn; không hỗ trợ viết lại đối số. | +| Chính sách quyền gốc | Được hỗ trợ qua relay hook gốc | `PermissionRequest` của Codex có thể được định tuyến qua chính sách OpenClaw nơi runtime cung cấp. Nếu OpenClaw không trả về quyết định, Codex tiếp tục qua đường guardian bình thường hoặc phê duyệt của người dùng. | +| Ghi lại quỹ đạo máy chủ ứng dụng | Được hỗ trợ | OpenClaw ghi lại yêu cầu đã gửi đến máy chủ ứng dụng và các thông báo máy chủ ứng dụng nhận được. | Không được hỗ trợ trong runtime Codex v1: -| Bề mặt | Ranh giới V1 | Hướng đi tương lai | +| Bề mặt | Ranh giới V1 | Lộ trình tương lai | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Đột biến đối số công cụ gốc | Các hook trước công cụ gốc của Codex có thể chặn, nhưng OpenClaw không viết lại đối số công cụ gốc của Codex. | Cần hỗ trợ hook/schema của Codex cho đầu vào công cụ thay thế. | -| Lịch sử bản ghi luồng gốc của Codex có thể chỉnh sửa | Codex sở hữu lịch sử luồng gốc chuẩn. OpenClaw sở hữu một bản phản chiếu và có thể chiếu ngữ cảnh tương lai, nhưng không nên thay đổi nội bộ không được hỗ trợ. | Thêm API máy chủ ứng dụng Codex rõ ràng nếu cần phẫu thuật luồng gốc. | -| `tool_result_persist` cho bản ghi công cụ gốc của Codex | Hook đó biến đổi các lần ghi bản ghi do OpenClaw sở hữu, không phải bản ghi công cụ gốc của Codex. | Có thể phản chiếu các bản ghi đã biến đổi, nhưng việc viết lại chuẩn cần hỗ trợ từ Codex. | -| Siêu dữ liệu Compaction gốc phong phú | OpenClaw quan sát thời điểm bắt đầu và hoàn tất Compaction, nhưng không nhận được danh sách giữ/lược bỏ ổn định, delta token, hoặc payload tóm tắt. | Cần sự kiện Compaction phong phú hơn từ Codex. | -| Can thiệp Compaction | Các hook Compaction hiện tại của OpenClaw ở mức thông báo trong chế độ Codex. | Thêm hook trước/sau Compaction của Codex nếu Plugin cần phủ quyết hoặc viết lại Compaction gốc. | -| Ghi lại yêu cầu API mô hình chính xác từng byte | OpenClaw có thể ghi lại các yêu cầu và thông báo của máy chủ ứng dụng, nhưng lõi Codex tự xây dựng yêu cầu API OpenAI cuối cùng ở bên trong. | Cần sự kiện truy vết yêu cầu mô hình của Codex hoặc API gỡ lỗi. | +| Biến đổi đối số công cụ native | Hook trước công cụ native của Codex có thể chặn, nhưng OpenClaw không viết lại đối số công cụ native của Codex. | Cần Codex hỗ trợ hook/schema để thay thế đầu vào công cụ. | +| Lịch sử transcript native của Codex có thể chỉnh sửa | Codex sở hữu lịch sử thread native chính tắc. OpenClaw sở hữu một bản sao phản chiếu và có thể chiếu ngữ cảnh trong tương lai, nhưng không nên biến đổi các phần nội bộ không được hỗ trợ. | Thêm API app-server rõ ràng của Codex nếu cần can thiệp thread native. | +| `tool_result_persist` cho bản ghi công cụ native của Codex | Hook đó biến đổi các lần ghi transcript do OpenClaw sở hữu, không phải bản ghi công cụ native của Codex. | Có thể phản chiếu các bản ghi đã biến đổi, nhưng việc viết lại chính tắc cần Codex hỗ trợ. | +| Siêu dữ liệu Compaction native phong phú | OpenClaw quan sát thời điểm Compaction bắt đầu và hoàn tất, nhưng không nhận được danh sách giữ lại/loại bỏ ổn định, chênh lệch token, hoặc payload tóm tắt. | Cần các sự kiện Compaction phong phú hơn từ Codex. | +| Can thiệp Compaction | Các hook Compaction hiện tại của OpenClaw ở cấp thông báo trong chế độ Codex. | Thêm hook trước/sau Compaction của Codex nếu Plugin cần phủ quyết hoặc viết lại Compaction native. | +| Ghi lại yêu cầu API mô hình chính xác từng byte | OpenClaw có thể ghi lại yêu cầu và thông báo của app-server, nhưng lõi Codex tự xây dựng yêu cầu API OpenAI cuối cùng ở nội bộ. | Cần sự kiện truy vết yêu cầu mô hình của Codex hoặc API gỡ lỗi. | -## Công cụ, phương tiện và Compaction +## Công cụ, media và Compaction -Harness Codex chỉ thay đổi executor tác nhân nhúng cấp thấp. +Harness Codex chỉ thay đổi executor agent nhúng cấp thấp. OpenClaw vẫn xây dựng danh sách công cụ và nhận kết quả công cụ động từ harness. Văn bản, hình ảnh, video, nhạc, TTS, phê duyệt và đầu ra công cụ nhắn tin -tiếp tục đi qua đường dẫn phân phối OpenClaw bình thường. +tiếp tục đi qua đường dẫn phân phối OpenClaw thông thường. -Relay hook gốc được cố ý thiết kế tổng quát, nhưng hợp đồng hỗ trợ v1 -chỉ giới hạn ở các đường dẫn công cụ gốc của Codex và quyền mà OpenClaw kiểm thử. Trong +Relay hook native được chủ ý thiết kế tổng quát, nhưng hợp đồng hỗ trợ v1 +chỉ giới hạn ở các đường dẫn công cụ và quyền native của Codex mà OpenClaw kiểm thử. Trong runtime Codex, điều đó bao gồm các payload shell, patch và MCP `PreToolUse`, -`PostToolUse`, và `PermissionRequest`. Đừng giả định mọi sự kiện hook Codex trong tương lai -là một bề mặt Plugin OpenClaw cho đến khi hợp đồng runtime nêu tên +`PostToolUse` và `PermissionRequest`. Đừng giả định mọi sự kiện hook Codex trong tương lai +đều là bề mặt Plugin của OpenClaw cho đến khi hợp đồng runtime nêu tên nó. Đối với `PermissionRequest`, OpenClaw chỉ trả về quyết định cho phép hoặc từ chối rõ ràng -khi chính sách quyết định. Kết quả không có quyết định không phải là cho phép. Codex xem đó là không có -quyết định hook và rơi xuống đường dẫn guardian hoặc phê duyệt người dùng của chính nó. +khi chính sách quyết định. Kết quả không có quyết định không phải là cho phép. Codex xử lý nó như không có +quyết định hook và chuyển tiếp sang đường dẫn guardian hoặc phê duyệt người dùng của chính nó. -Các yêu cầu phê duyệt công cụ Codex MCP được định tuyến qua luồng phê duyệt Plugin -của OpenClaw khi Codex đánh dấu `_meta.codex_approval_kind` là -`"mcp_tool_call"`. Các prompt `request_user_input` của Codex được gửi lại tới -cuộc trò chuyện gốc, và tin nhắn theo dõi tiếp theo trong hàng đợi trả lời yêu cầu máy chủ -gốc đó thay vì được điều hướng như ngữ cảnh bổ sung. Các yêu cầu elicitation MCP khác -vẫn thất bại theo hướng đóng. +Các yêu cầu phê duyệt công cụ MCP của Codex được định tuyến qua luồng phê duyệt +Plugin của OpenClaw khi Codex đánh dấu `_meta.codex_approval_kind` là +`"mcp_tool_call"`. Prompt `request_user_input` của Codex được gửi lại về +cuộc trò chuyện gốc, và tin nhắn tiếp theo trong hàng đợi sẽ trả lời yêu cầu native server đó +thay vì được điều hướng làm ngữ cảnh bổ sung. Các yêu cầu gợi mở MCP khác +vẫn đóng khi thất bại. -Điều hướng hàng đợi lượt đang hoạt động ánh xạ vào `turn/steer` của máy chủ ứng dụng Codex. Với -mặc định `messages.queue.mode: "steer"`, OpenClaw gom các tin nhắn trò chuyện đã xếp hàng -trong khoảng lặng được cấu hình và gửi chúng thành một yêu cầu `turn/steer` duy nhất theo +Điều hướng hàng đợi khi lượt đang hoạt động ánh xạ vào `turn/steer` của app-server Codex. Với +mặc định `messages.queue.mode: "steer"`, OpenClaw gom các tin nhắn trò chuyện trong hàng đợi +trong khoảng thời gian yên lặng đã cấu hình và gửi chúng thành một yêu cầu `turn/steer` theo thứ tự đến. Chế độ `queue` cũ gửi các yêu cầu `turn/steer` riêng biệt. Các lượt -review và Compaction thủ công của Codex có thể từ chối điều hướng trong cùng lượt, trong trường hợp đó -OpenClaw dùng hàng đợi theo dõi khi chế độ đã chọn cho phép fallback. Xem +review và Compaction thủ công của Codex có thể từ chối điều hướng cùng lượt, trong trường hợp đó +OpenClaw dùng hàng đợi followup khi chế độ đã chọn cho phép fallback. Xem [Hàng đợi điều hướng](/vi/concepts/queue-steering). -Khi mô hình đã chọn dùng harness Codex, Compaction luồng gốc được -ủy quyền cho máy chủ ứng dụng Codex. OpenClaw giữ một bản phản chiếu bản ghi cho lịch sử -kênh, tìm kiếm, `/new`, `/reset`, và việc chuyển đổi mô hình hoặc harness trong tương lai. Bản -phản chiếu bao gồm prompt của người dùng, văn bản trợ lý cuối cùng, và các bản ghi lập luận hoặc kế hoạch -nhẹ của Codex khi máy chủ ứng dụng phát ra chúng. Hiện tại, OpenClaw chỉ -ghi lại tín hiệu bắt đầu và hoàn tất Compaction gốc. Nó chưa hiển thị +Khi mô hình đã chọn dùng harness Codex, Compaction thread native được +ủy quyền cho app-server Codex. OpenClaw giữ một bản sao transcript cho lịch sử +kênh, tìm kiếm, `/new`, `/reset` và việc chuyển đổi mô hình hoặc harness trong tương lai. Bản sao +bao gồm prompt của người dùng, văn bản assistant cuối cùng và các bản ghi reasoning hoặc plan nhẹ của Codex +khi app-server phát ra chúng. Hiện nay, OpenClaw chỉ +ghi lại tín hiệu bắt đầu và hoàn tất Compaction native. Nó chưa cung cấp bản tóm tắt Compaction dễ đọc cho con người hoặc danh sách có thể kiểm toán về những mục Codex -giữ lại sau Compaction. +đã giữ lại sau Compaction. -Vì Codex sở hữu luồng gốc chuẩn, `tool_result_persist` hiện không -viết lại các bản ghi kết quả công cụ gốc của Codex. Nó chỉ áp dụng khi -OpenClaw đang ghi kết quả công cụ vào bản ghi phiên do OpenClaw sở hữu. +Vì Codex sở hữu thread native chính tắc, `tool_result_persist` hiện không +viết lại các bản ghi kết quả công cụ native của Codex. Nó chỉ áp dụng khi +OpenClaw đang ghi kết quả công cụ transcript phiên do OpenClaw sở hữu. -Tạo phương tiện không yêu cầu PI. Hình ảnh, video, nhạc, PDF, TTS, và khả năng -hiểu phương tiện tiếp tục dùng các thiết lập provider/mô hình tương ứng như -`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, và +Tạo media không yêu cầu PI. Hình ảnh, video, nhạc, PDF, TTS và +hiểu media tiếp tục dùng các thiết lập provider/mô hình tương ứng như +`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` và `messages.tts`. ## Khắc phục sự cố -**Codex không xuất hiện như một provider `/model` bình thường:** điều đó là dự kiến với +**Codex không xuất hiện như một provider `/model` bình thường:** điều này là dự kiến đối với cấu hình mới. Chọn một mô hình `openai/gpt-*` với `agentRuntime.id: "codex"` (hoặc một ref `codex/*` cũ), bật `plugins.entries.codex.enabled`, và kiểm tra liệu `plugins.allow` có loại trừ -`codex` hay không. +`codex` không. **OpenClaw dùng PI thay vì Codex:** `agentRuntime.id: "auto"` vẫn có thể dùng PI làm backend tương thích khi không có harness Codex nào nhận lượt chạy. Đặt -`agentRuntime.id: "codex"` để buộc chọn Codex trong khi kiểm thử. Runtime -Codex bị ép buộc sẽ thất bại thay vì fallback về PI. Sau khi máy chủ ứng dụng Codex -được chọn, các lỗi của nó sẽ hiển thị trực tiếp. +`agentRuntime.id: "codex"` để buộc chọn Codex trong khi kiểm thử. Một +runtime Codex bị buộc sẽ thất bại thay vì fallback về PI. Sau khi app-server Codex +được chọn, lỗi của nó sẽ hiển thị trực tiếp. -**Máy chủ ứng dụng bị từ chối:** nâng cấp Codex để quá trình bắt tay máy chủ ứng dụng -báo cáo phiên bản `0.125.0` hoặc mới hơn. Các prerelease cùng phiên bản hoặc phiên bản có hậu tố build -như `0.125.0-alpha.2` hoặc `0.125.0+custom` bị từ chối vì ngưỡng giao thức -ổn định `0.125.0` là thứ OpenClaw kiểm thử. +**App-server bị từ chối:** nâng cấp Codex để bắt tay app-server +báo cáo phiên bản `0.125.0` hoặc mới hơn. Các bản prerelease cùng phiên bản hoặc phiên bản có hậu tố build +như `0.125.0-alpha.2` hoặc `0.125.0+custom` bị từ chối vì +ngưỡng giao thức ổn định `0.125.0` là mức OpenClaw kiểm thử. **Khám phá mô hình chậm:** giảm `plugins.entries.codex.config.discovery.timeoutMs` hoặc tắt khám phá. -**Truyền tải WebSocket thất bại ngay lập tức:** kiểm tra `appServer.url`, `authToken`, -và đảm bảo máy chủ ứng dụng từ xa nói cùng phiên bản giao thức máy chủ ứng dụng Codex. +**Transport WebSocket thất bại ngay lập tức:** kiểm tra `appServer.url`, `authToken`, +và đảm bảo app-server từ xa nói cùng phiên bản giao thức app-server Codex. -**Một mô hình không phải Codex dùng PI:** điều đó là dự kiến trừ khi bạn đã buộc -`agentRuntime.id: "codex"` cho tác nhân đó hoặc chọn một ref -`codex/*` cũ. Các ref `openai/gpt-*` thuần và provider khác vẫn ở trên đường dẫn -provider bình thường của chúng trong chế độ `auto`. Nếu bạn buộc `agentRuntime.id: "codex"`, mọi lượt -nhúng cho tác nhân đó phải là mô hình OpenAI được Codex hỗ trợ. +**Một mô hình không phải Codex dùng PI:** điều này là dự kiến trừ khi bạn đã buộc +`agentRuntime.id: "codex"` cho agent đó hoặc chọn một ref +`codex/*` cũ. Các ref `openai/gpt-*` thuần và provider khác vẫn ở trên +đường dẫn provider bình thường của chúng trong chế độ `auto`. Nếu bạn buộc `agentRuntime.id: "codex"`, mọi lượt nhúng +cho agent đó phải là mô hình OpenAI được Codex hỗ trợ. -**Computer Use đã được cài đặt nhưng công cụ không chạy:** kiểm tra -`/codex computer-use status` từ một phiên mới. Nếu một công cụ báo -`Native hook relay unavailable`, dùng `/new` hoặc `/reset`; nếu lỗi vẫn còn, khởi động lại -gateway để xóa các đăng ký hook gốc cũ. Nếu `computer-use.list_apps` -hết thời gian chờ, khởi động lại Codex Computer Use hoặc Codex Desktop và thử lại. +**Computer Use đã được cài nhưng công cụ không chạy:** kiểm tra +`/codex computer-use status` từ một phiên mới. Nếu một công cụ báo cáo +`Native hook relay unavailable`, dùng `/new` hoặc `/reset`; nếu vẫn tiếp diễn, khởi động lại +gateway để xóa các đăng ký hook native cũ. Nếu `computer-use.list_apps` +hết thời gian chờ, khởi động lại Codex Computer Use hoặc Codex Desktop rồi thử lại. ## Liên quan -- [Plugin harness tác nhân](/vi/plugins/sdk-agent-harness) -- [Runtime tác nhân](/vi/concepts/agent-runtimes) +- [Plugin harness agent](/vi/plugins/sdk-agent-harness) +- [Runtime agent](/vi/concepts/agent-runtimes) - [Provider mô hình](/vi/concepts/model-providers) - [Provider OpenAI](/vi/providers/openai) - [Trạng thái](/vi/cli/status) diff --git a/docs/vi/plugins/dependency-resolution.md b/docs/vi/plugins/dependency-resolution.md index 9a84a3ce5..4797b437a 100644 --- a/docs/vi/plugins/dependency-resolution.md +++ b/docs/vi/plugins/dependency-resolution.md @@ -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 --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 @@ -89,44 +92,45 @@ openclaw plugins install 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/` để 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/` để 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/` | 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/` | 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. diff --git a/docs/vi/plugins/hooks.md b/docs/vi/plugins/hooks.md index 66995fadd..a3d8cb12d 100644 --- a/docs/vi/plugins/hooks.md +++ b/docs/vi/plugins/hooks.md @@ -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.` 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.` 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..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..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) diff --git a/docs/vi/plugins/manage-plugins.md b/docs/vi/plugins/manage-plugins.md index 751dd5e06..3ff90212e 100644 --- a/docs/vi/plugins/manage-plugins.md +++ b/docs/vi/plugins/manage-plugins.md @@ -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 --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 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 ` 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 ` 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 --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 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 diff --git a/docs/vi/plugins/sdk-overview.md b/docs/vi/plugins/sdk-overview.md index c698009a6..faa43c9fc 100644 --- a/docs/vi/plugins/sdk-overview.md +++ b/docs/vi/plugins/sdk-overview.md @@ -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ý**. - 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ế. -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. ## 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. - 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. ## 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 | - 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. 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. ### Đă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.`. -- Cấu hình người dùng vẫn thắng. OpenClaw hợp nhất `agents.defaults.cliBackends.` 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.` 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` | Cấu hình riêng của plugin từ `plugins.entries..config` | +| `api.pluginConfig` | `Record` | Cấu hình riêng của Plugin từ `plugins.entries..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/ ``` - Không bao giờ import chính plugin của bạn thông qua `openclaw/plugin-sdk/` - 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/` + 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. -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. - Mã production extension cũng nên tránh import `openclaw/plugin-sdk/`. - 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/`. + 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. ## Liên quan - Tùy chọn `definePluginEntry` và `defineChannelPluginEntry`. + Các tùy chọn `definePluginEntry` và `defineChannelPluginEntry`. - - Tài liệu tham chiếu đầy đủ cho không gian tên `api.runtime`. + + Tài liệu tham chiếu đầy đủ cho namespace `api.runtime`. - Đóng gói, manifest và schema cấu hình. + Đóng gói, manifest và lược đồ cấu hình. Tiện ích kiểm thử và quy tắc lint. - 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ị. - 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. diff --git a/docs/vi/providers/openrouter.md b/docs/vi/providers/openrouter.md index 062ae88a6..82ade3e3e 100644 --- a/docs/vi/providers/openrouter.md +++ b/docs/vi/providers/openrouter.md @@ -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 - + Tạo khóa API tại [openrouter.ai/keys](https://openrouter.ai/keys). @@ -56,19 +56,19 @@ OpenRouter cung cấp một **API hợp nhất** định tuyến yêu cầu đ Tham chiếu mô hình tuân theo mẫu `openrouter//`. Để xem danh sách đầy đủ -các nhà cung cấp và mô hình 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). 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` | -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. ## Cấu hình nâng cao - Bộ nhớ đệm phản hồi OpenRouter là tùy chọn bật rõ ràng. Bật theo từng mô hình OpenRouter bằng + 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. - - 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. + + 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. - - Trên các tuyến OpenRouter đã xác minh, tham chiếu mô hình Anthropic có bật reasoning - sẽ bỏ các lượt điền trước assistant ở cuối trước khi yêu cầu đến OpenRouter, - khớp với yêu cầu của Anthropic rằng hội thoại reasoning phải kết thúc bằng lượt của người dùng. + + Trên các 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. - 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 đó. - - 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. + + 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`. - 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. - - 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. + + 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. @@ -242,9 +244,9 @@ Nếu bạn trỏ lại nhà cung cấp OpenRouter đến một proxy hoặc URL - 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. - 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. diff --git a/docs/vi/reference/RELEASING.md b/docs/vi/reference/RELEASING.md index fcdadbb09..268f90912 100644 --- a/docs/vi/reference/RELEASING.md +++ b/docs/vi/reference/RELEASING.md @@ -1,276 +1,284 @@ --- read_when: - - Đang tìm định nghĩa kênh phát hành công khai - - Chạy xác thực bản phát hành hoặc kiểm nhận gói - - Tìm thông tin về cách đặt tên phiên bản và nhịp phát hành -summary: Các luồng phát hành, danh sách kiểm tra dành cho người vận hành, các hộp xác thực, cách đặt tên phiên bản và nhịp phát hành + - Đang tìm các định nghĩa kênh phát hành công khai + - Chạy xác thực bản phát hành hoặc nghiệm thu gói + - Tìm cách đặt tên phiên bản và nhịp phát hành +summary: Các làn phát hành, danh sách kiểm tra cho người vận hành, các máy xác thực, cách đặt tên phiên bản và nhịp phát hành title: Chính sách phát hành x-i18n: - generated_at: "2026-05-04T07:06:10Z" + generated_at: "2026-05-05T01:50:00Z" model: gpt-5.5 provider: openai - source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 + source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw có ba nhánh phát hành công khai: +OpenClaw có ba luồng phát hành công khai: -- stable: bản phát hành được gắn thẻ, mặc định phát hành lên npm `beta`, hoặc lên npm `latest` khi được yêu cầu rõ ràng -- beta: thẻ tiền phát hành được phát hành lên npm `beta` +- stable: các bản phát hành được gắn thẻ, mặc định phát hành lên npm `beta`, hoặc lên npm `latest` khi được yêu cầu rõ ràng +- beta: các thẻ tiền phát hành được phát hành lên npm `beta` - dev: đầu nhánh đang thay đổi của `main` ## Cách đặt tên phiên bản -- Phiên bản phát hành stable: `YYYY.M.D` +- Phiên bản phát hành ổn định: `YYYY.M.D` - Thẻ Git: `vYYYY.M.D` -- Phiên bản phát hành sửa lỗi stable: `YYYY.M.D-N` +- Phiên bản phát hành sửa lỗi ổn định: `YYYY.M.D-N` - Thẻ Git: `vYYYY.M.D-N` - Phiên bản tiền phát hành beta: `YYYY.M.D-beta.N` - Thẻ Git: `vYYYY.M.D-beta.N` - Không thêm số 0 ở đầu tháng hoặc ngày -- `latest` nghĩa là bản phát hành npm stable hiện tại đã được quảng bá +- `latest` nghĩa là bản phát hành npm ổn định hiện tại đã được quảng bá - `beta` nghĩa là mục tiêu cài đặt beta hiện tại -- Các bản phát hành stable và sửa lỗi stable mặc định phát hành lên npm `beta`; người vận hành phát hành có thể nhắm tới `latest` một cách rõ ràng, hoặc quảng bá một bản dựng beta đã được thẩm định sau đó -- Mọi bản phát hành OpenClaw stable đều phát hành gói npm và ứng dụng macOS cùng nhau; - các bản phát hành beta thường xác thực và phát hành đường dẫn npm/package trước, còn - việc build/ký/notarize ứng dụng mac được dành cho stable trừ khi được yêu cầu rõ ràng +- Các bản phát hành ổn định và bản phát hành sửa lỗi ổn định mặc định phát hành lên npm `beta`; người vận hành phát hành có thể nhắm đến `latest` một cách rõ ràng, hoặc quảng bá một bản dựng beta đã được kiểm định sau đó +- Mọi bản phát hành OpenClaw ổn định đều phát hành gói npm và ứng dụng macOS cùng nhau; + các bản phát hành beta thường xác thực và phát hành đường dẫn npm/gói trước, còn + việc dựng/ký/công chứng ứng dụng mac được dành cho bản ổn định trừ khi được yêu cầu rõ ràng ## Nhịp phát hành - Các bản phát hành đi theo hướng beta trước -- Stable chỉ theo sau sau khi bản beta mới nhất đã được xác thực -- Maintainer thường cắt bản phát hành từ một nhánh `release/YYYY.M.D` được tạo +- Bản ổn định chỉ theo sau sau khi bản beta mới nhất được xác thực +- Người bảo trì thường cắt bản phát hành từ một nhánh `release/YYYY.M.D` được tạo từ `main` hiện tại, để việc xác thực và sửa lỗi phát hành không chặn phát triển mới trên `main` -- Nếu một thẻ beta đã được đẩy hoặc phát hành và cần sửa lỗi, maintainer cắt +- Nếu một thẻ beta đã được đẩy hoặc phát hành và cần sửa lỗi, người bảo trì cắt thẻ `-beta.N` tiếp theo thay vì xóa hoặc tạo lại thẻ beta cũ - Quy trình phát hành chi tiết, phê duyệt, thông tin xác thực và ghi chú khôi phục - chỉ dành cho maintainer + chỉ dành cho người bảo trì -## Danh sách kiểm tra cho người vận hành phát hành +## Danh sách kiểm tra dành cho người vận hành phát hành Danh sách kiểm tra này là hình dạng công khai của luồng phát hành. Thông tin xác thực riêng tư, -ký, notarization, khôi phục dist-tag và chi tiết rollback khẩn cấp nằm trong -runbook phát hành chỉ dành cho maintainer. +ký, công chứng, khôi phục dist-tag và chi tiết khôi phục khẩn cấp được giữ trong +sổ tay phát hành chỉ dành cho người bảo trì. 1. Bắt đầu từ `main` hiện tại: kéo bản mới nhất, xác nhận commit mục tiêu đã được đẩy, và xác nhận CI của `main` hiện tại đủ xanh để tạo nhánh từ đó. -2. Viết lại phần đầu của `CHANGELOG.md` từ lịch sử commit thực bằng - `/changelog`, giữ các mục hướng tới người dùng, commit, đẩy, rồi rebase/pull +2. Viết lại phần trên cùng của `CHANGELOG.md` từ lịch sử commit thực bằng + `/changelog`, giữ các mục hướng đến người dùng, commit, đẩy, rồi rebase/kéo thêm một lần nữa trước khi tạo nhánh. -3. Rà soát các bản ghi tương thích phát hành trong +3. Xem lại các bản ghi tương thích phát hành trong `src/plugins/compat/registry.ts` và `src/commands/doctor/shared/deprecation-compat.ts`. Chỉ xóa tương thích đã hết hạn khi đường dẫn nâng cấp vẫn được bao phủ, hoặc ghi lại lý do vì sao nó được - chủ ý giữ lại. + cố ý giữ lại. 4. Tạo `release/YYYY.M.D` từ `main` hiện tại; không thực hiện công việc phát hành bình thường trực tiếp trên `main`. 5. Tăng mọi vị trí phiên bản bắt buộc cho thẻ dự định, chạy `pnpm plugins:sync` để các gói Plugin có thể phát hành chia sẻ phiên bản phát hành - và siêu dữ liệu tương thích, rồi chạy preflight xác định cục bộ: + và siêu dữ liệu tương thích, rồi chạy bước kiểm tra sơ bộ xác định cục bộ: `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, và `pnpm release:check`. 6. Chạy `OpenClaw NPM Release` với `preflight_only=true`. Trước khi có thẻ, - SHA nhánh phát hành đủ 40 ký tự được phép dùng cho preflight chỉ để xác thực. - Lưu `preflight_run_id` thành công. -7. Khởi chạy toàn bộ kiểm thử tiền phát hành bằng `Full Release Validation` cho - nhánh phát hành, thẻ, hoặc SHA commit đầy đủ. Đây là entrypoint thủ công duy nhất + SHA đầy đủ 40 ký tự của nhánh phát hành được phép dùng cho kiểm tra sơ bộ + chỉ để xác thực. Lưu `preflight_run_id` thành công. +7. Khởi động tất cả kiểm thử tiền phát hành bằng `Full Release Validation` cho + nhánh phát hành, thẻ, hoặc SHA commit đầy đủ. Đây là điểm vào thủ công duy nhất cho bốn hộp kiểm thử phát hành lớn: Vitest, Docker, QA Lab và Package. -8. Nếu xác thực thất bại, sửa trên nhánh phát hành và chạy lại tệp, lane, - job workflow, hồ sơ package, provider hoặc allowlist model nhỏ nhất đã thất bại - để chứng minh bản sửa. Chỉ chạy lại toàn bộ umbrella khi bề mặt đã thay đổi khiến - bằng chứng trước đó không còn mới. +8. Nếu xác thực thất bại, sửa trên nhánh phát hành và chạy lại tệp, luồng, + công việc workflow, hồ sơ gói, nhà cung cấp, hoặc danh sách cho phép mô hình + nhỏ nhất đã thất bại để chứng minh bản sửa. Chỉ chạy lại toàn bộ lớp bao trùm + khi bề mặt thay đổi khiến bằng chứng trước đó không còn mới. 9. Với beta, gắn thẻ `vYYYY.M.D-beta.N`, rồi chạy `OpenClaw Release Publish` từ - nhánh `release/YYYY.M.D` tương ứng. Nó xác minh `pnpm plugins:sync:check`, - phát hành tất cả gói Plugin có thể phát hành lên npm trước, phát hành cùng tập hợp đó - lên ClawHub thứ hai dưới dạng tarball ClawPack npm-pack, rồi quảng bá artifact - preflight npm OpenClaw đã chuẩn bị với dist-tag tương ứng. Sau khi phát hành, - chạy kiểm tra chấp nhận package sau phát hành - đối với package `openclaw@YYYY.M.D-beta.N` hoặc - `openclaw@beta` đã phát hành. Nếu một bản tiền phát hành đã đẩy hoặc đã phát hành cần sửa, - cắt số tiền phát hành tương ứng tiếp theo; không xóa hoặc viết lại bản tiền phát hành cũ. -10. Với stable, chỉ tiếp tục sau khi beta hoặc release candidate đã được thẩm định có - bằng chứng xác thực bắt buộc. Việc phát hành npm stable cũng đi qua - `OpenClaw Release Publish`, tái sử dụng artifact preflight thành công qua - `preflight_run_id`; trạng thái sẵn sàng phát hành stable macOS cũng yêu cầu - `.zip`, `.dmg`, `.dSYM.zip` đã được đóng gói, và `appcast.xml` đã cập nhật trên `main`. -11. Sau khi phát hành, chạy trình xác minh npm sau phát hành, tùy chọn E2E Telegram - published-npm độc lập khi bạn cần bằng chứng kênh sau phát hành, - quảng bá dist-tag khi cần, ghi chú GitHub release/prerelease từ phần + nhánh `release/YYYY.M.D` khớp. Nó xác minh `pnpm plugins:sync:check`, + phát hành tất cả gói Plugin có thể phát hành lên npm trước, phát hành cùng + tập hợp đó lên ClawHub thứ hai dưới dạng tarball ClawPack npm-pack, rồi quảng bá + hiện vật kiểm tra sơ bộ npm OpenClaw đã chuẩn bị với dist-tag khớp. Sau khi + phát hành, chạy chấp nhận gói sau phát hành + đối với gói `openclaw@YYYY.M.D-beta.N` hoặc + `openclaw@beta` đã phát hành. Nếu một bản tiền phát hành đã đẩy hoặc đã phát hành cần sửa lỗi, + cắt số tiền phát hành khớp tiếp theo; không xóa hoặc viết lại bản tiền phát hành cũ. +10. Với bản ổn định, chỉ tiếp tục sau khi bản beta hoặc ứng viên phát hành đã kiểm định có + bằng chứng xác thực bắt buộc. Phát hành npm ổn định cũng đi qua + `OpenClaw Release Publish`, tái sử dụng hiện vật kiểm tra sơ bộ thành công qua + `preflight_run_id`; mức sẵn sàng phát hành macOS ổn định cũng yêu cầu + các gói `.zip`, `.dmg`, `.dSYM.zip`, và `appcast.xml` đã cập nhật trên `main`. +11. Sau khi phát hành, chạy bộ xác minh npm sau phát hành, kiểm thử E2E Telegram + từ npm đã phát hành độc lập tùy chọn khi bạn cần bằng chứng kênh sau phát hành, + quảng bá dist-tag khi cần, ghi chú phát hành/tiền phát hành GitHub từ phần `CHANGELOG.md` hoàn chỉnh tương ứng, và các bước thông báo phát hành. -## Preflight phát hành +## Kiểm tra sơ bộ phát hành -- Chạy `pnpm check:test-types` trước release preflight để TypeScript của kiểm thử vẫn được - bao phủ bên ngoài gate `pnpm check` cục bộ nhanh hơn -- Chạy `pnpm check:architecture` trước release preflight để các kiểm tra rộng hơn về chu - trình import và ranh giới kiến trúc đều xanh bên ngoài gate cục bộ nhanh hơn -- Chạy `pnpm build && pnpm ui:build` trước `pnpm release:check` để các artifact phát hành - `dist/*` dự kiến và bundle Control UI tồn tại cho bước xác thực pack -- Chạy `pnpm plugins:sync` sau khi tăng phiên bản ở root và trước khi gắn tag. Lệnh này - cập nhật phiên bản package của các plugin có thể publish, metadata tương thích - peer/API của OpenClaw, metadata build và stub changelog plugin để khớp với phiên bản - phát hành core. `pnpm plugins:sync:check` là guard phát hành không làm thay đổi dữ liệu; - workflow publish sẽ thất bại trước bất kỳ thay đổi registry nào nếu bước này bị +- Chạy `pnpm check:test-types` trước bước kiểm tra trước phát hành để TypeScript của kiểm thử vẫn được + bao phủ ngoài cổng `pnpm check` cục bộ nhanh hơn +- Chạy `pnpm check:architecture` trước bước kiểm tra trước phát hành để các kiểm tra chu trình import + và ranh giới kiến trúc rộng hơn đều xanh ngoài cổng cục bộ nhanh hơn +- Chạy `pnpm build && pnpm ui:build` trước `pnpm release:check` để các tạo tác phát hành + `dist/*` dự kiến và gói Control UI tồn tại cho bước xác thực đóng gói +- Chạy `pnpm plugins:sync` sau khi tăng phiên bản gốc và trước khi gắn thẻ. Lệnh này + cập nhật các phiên bản gói Plugin có thể phát hành, siêu dữ liệu tương thích + peer/API của OpenClaw, siêu dữ liệu build, và các stub changelog Plugin để khớp với phiên bản phát hành + lõi. `pnpm plugins:sync:check` là bộ bảo vệ phát hành không thay đổi dữ liệu; + workflow phát hành sẽ thất bại trước mọi thay đổi registry nếu bước này bị quên. - Chạy workflow thủ công `Full Release Validation` trước khi phê duyệt phát hành để - khởi động tất cả test box tiền phát hành từ một entrypoint. Workflow này nhận branch, - tag hoặc SHA commit đầy đủ, dispatch `CI` thủ công và dispatch - `OpenClaw Release Checks` cho install smoke, package acceptance, các suite đường dẫn - phát hành Docker, live/E2E, OpenWebUI, parity QA Lab, Matrix và các lane Telegram. Với - `release_profile=full` và `rerun_group=all`, nó cũng chạy package Telegram E2E với - artifact `release-package-under-test` từ release checks. Cung cấp - `npm_telegram_package_spec` sau khi publish khi cùng Telegram E2E cũng cần chứng minh - package npm đã publish. Cung cấp `package_acceptance_package_spec` sau khi publish khi - Package Acceptance cần chạy ma trận package/update của nó với package npm đã ship thay - vì artifact được build từ SHA. Cung cấp - `evidence_package_spec` khi báo cáo bằng chứng riêng tư cần chứng minh validation khớp - với package npm đã publish mà không bắt buộc Telegram E2E. + khởi động tất cả hộp kiểm thử tiền phát hành từ một điểm vào. Nó chấp nhận một nhánh, + thẻ, hoặc SHA commit đầy đủ, dispatch `CI` thủ công, và dispatch + `OpenClaw Release Checks` cho kiểm tra smoke cài đặt, chấp nhận gói, kiểm tra gói + đa hệ điều hành, đối sánh QA Lab, Matrix, và các làn Telegram. Các lần chạy ổn định/mặc định + giữ E2E/live toàn diện và soak đường dẫn phát hành Docker phía sau + `run_release_soak=true`; `release_profile=full` buộc bật soak. Với + `release_profile=full` và `rerun_group=all`, nó cũng chạy E2E Telegram gói + trên tạo tác `release-package-under-test` từ kiểm tra phát hành. + Cung cấp `npm_telegram_package_spec` sau khi phát hành khi cùng E2E + Telegram cũng cần chứng minh gói npm đã phát hành. Cung cấp + `package_acceptance_package_spec` sau khi phát hành khi Package Acceptance + cần chạy ma trận gói/cập nhật của nó trên gói npm đã giao thay vì + tạo tác được build từ SHA. Cung cấp + `evidence_package_spec` khi báo cáo bằng chứng riêng tư cần chứng minh rằng + quá trình xác thực khớp với một gói npm đã phát hành mà không buộc chạy E2E Telegram. Ví dụ: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Chạy workflow thủ công `Package Acceptance` khi bạn muốn bằng chứng kênh phụ cho một - ứng viên package trong lúc công việc phát hành tiếp tục. Dùng `source=npm` cho - `openclaw@beta`, `openclaw@latest` hoặc một phiên bản phát hành chính xác; `source=ref` - để pack một branch/tag/SHA `package_ref` tin cậy bằng harness `workflow_ref` hiện tại; - `source=url` cho tarball HTTPS với SHA-256 bắt buộc; hoặc `source=artifact` cho tarball - được upload bởi một lần chạy GitHub Actions khác. Workflow phân giải ứng viên thành - `package-under-test`, tái sử dụng bộ lập lịch Docker E2E release với tarball đó, và có - thể chạy Telegram QA với cùng tarball bằng `telegram_mode=mock-openai` hoặc - `telegram_mode=live-frontier`. Khi các lane Docker đã chọn bao gồm - `published-upgrade-survivor`, artifact package là ứng viên và - `published_upgrade_survivor_baseline` chọn baseline đã publish. +- Chạy workflow thủ công `Package Acceptance` khi bạn muốn bằng chứng kênh phụ + cho một ứng viên gói trong khi công việc phát hành tiếp tục. Dùng `source=npm` cho + `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 nhánh/thẻ/SHA `package_ref` đáng tin cậy bằng harness + `workflow_ref` hiện tại; `source=url` cho tarball HTTPS với + SHA-256 bắt buộc; hoặc `source=artifact` cho tarball được tải lên bởi một lần chạy + GitHub Actions khác. Workflow phân giải ứng viên thành + `package-under-test`, tái sử dụng bộ lập lịch phát hành Docker E2E trên + tarball đó, và có thể chạy QA Telegram trên cùng tarball với + `telegram_mode=mock-openai` hoặc `telegram_mode=live-frontier`. Khi các làn + Docker đã chọn bao gồm `published-upgrade-survivor`, tạo tác gói là ứng viên và + `published_upgrade_survivor_baseline` chọn baseline đã phát hành. Ví dụ: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` Hồ sơ phổ biến: - - `smoke`: các lane cài đặt/kênh/agent, mạng Gateway và tải lại cấu hình - - `package`: các lane package/update/plugin gốc artifact, không có OpenWebUI hoặc ClawHub live - - `product`: hồ sơ package cộng với kênh MCP, dọn dẹp cron/subagent, - tìm kiếm web OpenAI và OpenWebUI + - `smoke`: các làn cài đặt/kênh/agent, mạng Gateway, và tải lại cấu hình + - `package`: các làn gói/cập nhật/Plugin gốc tạo tác không có OpenWebUI hoặc ClawHub live + - `product`: hồ sơ gói cộng thêm các kênh MCP, dọn dẹp cron/subagent, + tìm kiếm web OpenAI, và OpenWebUI - `full`: các phần đường dẫn phát hành Docker với OpenWebUI - `custom`: lựa chọn `docker_lanes` chính xác cho một lần chạy lại tập trung -- Chạy trực tiếp workflow thủ công `CI` khi bạn chỉ cần độ bao phủ CI đầy đủ thông thường - cho ứng viên phát hành. Các dispatch CI thủ công bỏ qua phạm vi changed và ép các shard - Linux Node, shard bundled-plugin, hợp đồng kênh, tương thích Node 22, `check`, - `check-additional`, build smoke, kiểm tra docs, Python skills, Windows, macOS, Android - và các lane i18n Control UI. +- Chạy trực tiếp workflow thủ công `CI` khi bạn chỉ cần phạm vi bao phủ CI bình thường đầy đủ + cho ứng viên phát hành. Các dispatch CI thủ công bỏ qua phạm vi theo thay đổi + và buộc các shard Linux Node, shard Plugin tích hợp, hợp đồng kênh, + tương thích Node 22, `check`, `check-additional`, smoke build, + kiểm tra tài liệu, Python skills, Windows, macOS, Android, và các làn i18n + Control UI. Ví dụ: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Chạy `pnpm qa:otel:smoke` khi xác thực telemetry phát hành. Lệnh này chạy - QA-lab qua một receiver OTLP/HTTP cục bộ và xác minh tên trace span đã export, - thuộc tính bị giới hạn và việc biên tập nội dung/định danh mà không cần Opik, - Langfuse hoặc collector bên ngoài khác. -- Chạy `pnpm release:check` trước mỗi phát hành được gắn tag -- Chạy `OpenClaw Release Publish` cho chuỗi publish có thay đổi sau khi tag tồn tại. - Dispatch từ `release/YYYY.M.D` (hoặc `main` khi publish một tag có thể truy cập từ - main), truyền tag phát hành và `preflight_run_id` npm OpenClaw thành công, đồng thời - giữ phạm vi publish plugin mặc định `all-publishable` trừ khi bạn cố ý chạy một bản sửa - tập trung. Workflow tuần tự hóa publish npm plugin, publish ClawHub plugin và publish - npm OpenClaw để package core không được publish trước các plugin đã externalize của nó. -- Release checks hiện chạy trong một workflow thủ công riêng: +- Chạy `pnpm qa:otel:smoke` khi xác thực telemetry phát hành. Lệnh này thực thi + QA-lab qua một bộ nhận OTLP/HTTP cục bộ và xác minh tên span trace được xuất, + thuộc tính có giới hạn, và việc biên tập nội dung/định danh mà không + yêu cầu Opik, Langfuse, hoặc bộ thu thập bên ngoài khác. +- Chạy `pnpm release:check` trước mỗi phát hành được gắn thẻ +- Chạy `OpenClaw Release Publish` cho chuỗi phát hành có thay đổi dữ liệu sau khi + thẻ tồn tại. Dispatch nó từ `release/YYYY.M.D` (hoặc `main` khi phát hành một + thẻ có thể truy cập từ main), truyền thẻ phát hành và `preflight_run_id` npm + OpenClaw thành công, và giữ phạm vi phát hành Plugin mặc định + `all-publishable` trừ khi bạn chủ ý chạy một lần sửa chữa tập trung. Workflow + tuần tự hóa phát hành npm Plugin, phát hành ClawHub Plugin, và phát hành npm OpenClaw + để gói lõi không được phát hành trước các Plugin đã được externalize. +- Kiểm tra phát hành hiện chạy trong một workflow thủ công riêng: `OpenClaw Release Checks` -- `OpenClaw Release Checks` cũng chạy lane parity mock QA Lab cùng với hồ sơ Matrix live - nhanh và lane Telegram QA trước khi phê duyệt phát hành. Các lane live dùng môi trường - `qa-live-shared`; Telegram cũng dùng lease thông tin xác thực Convex CI. Chạy workflow - thủ công `QA-Lab - All Lanes` với `matrix_profile=all` và `matrix_shards=true` khi bạn - muốn toàn bộ inventory transport, media và E2EE Matrix chạy song song. -- Validation runtime cài đặt và nâng cấp đa hệ điều hành là một phần của - `OpenClaw Release Checks` công khai và `Full Release Validation`, gọi trực tiếp +- `OpenClaw Release Checks` cũng chạy làn đối sánh mô phỏng QA Lab cộng với hồ sơ + Matrix live nhanh và làn QA Telegram trước khi phê duyệt phát hành. Các làn live + dùng môi trường `qa-live-shared`; Telegram cũng dùng các lease thông tin xác thực Convex CI. + Chạy workflow thủ công `QA-Lab - All Lanes` với + `matrix_profile=all` và `matrix_shards=true` khi bạn muốn toàn bộ kiểm kê truyền tải + Matrix, media, và E2EE chạy song song. +- Xác thực runtime cài đặt và nâng cấp đa hệ điều hành là một phần của + `OpenClaw Release Checks` và `Full Release Validation` công khai, vốn gọi trực tiếp workflow tái sử dụng `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` - Việc tách này là có chủ ý: giữ đường dẫn phát hành npm thật ngắn, - xác định và tập trung vào artifact, trong khi các kiểm tra live chậm hơn nằm trong lane - riêng để chúng không làm đình trệ hoặc chặn publish -- Các release checks mang secret nên được dispatch qua `Full Release + xác định, và tập trung vào tạo tác, trong khi các kiểm tra live chậm hơn nằm trong + làn riêng để chúng không làm đình trệ hoặc chặn phát hành +- Các kiểm tra phát hành mang bí mật nên được dispatch qua `Full Release Validation` hoặc từ workflow ref `main`/release để logic workflow và - secret vẫn được kiểm soát -- `OpenClaw Release Checks` nhận branch, tag hoặc SHA commit đầy đủ miễn là - commit được phân giải có thể truy cập từ một branch OpenClaw hoặc tag phát hành -- Preflight chỉ validation của `OpenClaw NPM Release` cũng nhận SHA commit đầy đủ - 40 ký tự của workflow-branch hiện tại mà không yêu cầu tag đã push -- Đường dẫn SHA đó chỉ dành cho validation và không thể được nâng cấp thành publish thật -- Ở chế độ SHA, workflow tổng hợp `v` chỉ cho kiểm tra - metadata package; publish thật vẫn yêu cầu tag phát hành thật -- Cả hai workflow giữ đường dẫn publish và promotion thật trên runner do GitHub host, - trong khi đường dẫn validation không làm thay đổi dữ liệu có thể dùng các runner + bí mật vẫn được kiểm soát +- `OpenClaw Release Checks` chấp nhận một nhánh, thẻ, hoặc SHA commit đầy đủ miễn là + commit được phân giải có thể truy cập từ một nhánh OpenClaw hoặc thẻ phát hành +- Bước kiểm tra trước chỉ xác thực của `OpenClaw NPM Release` cũng chấp nhận SHA commit + đầy đủ 40 ký tự của nhánh workflow hiện tại mà không yêu cầu thẻ đã được push +- Đường dẫn SHA đó chỉ dùng để xác thực và không thể được nâng cấp thành phát hành thật +- Ở chế độ SHA, workflow chỉ tổng hợp `v` cho kiểm tra + siêu dữ liệu gói; phát hành thật vẫn yêu cầu một thẻ phát hành thật +- Cả hai workflow giữ đường dẫn phát hành và thăng hạng thật trên runner do GitHub lưu trữ, + trong khi đường dẫn xác thực không thay đổi dữ liệu có thể dùng runner Blacksmith Linux lớn hơn - Workflow đó chạy `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - bằng cả secret workflow `OPENAI_API_KEY` và `ANTHROPIC_API_KEY` -- Preflight phát hành npm không còn chờ lane release checks riêng biệt + bằng cả hai secret workflow `OPENAI_API_KEY` và `ANTHROPIC_API_KEY` +- Bước kiểm tra trước phát hành npm không còn chờ làn kiểm tra phát hành riêng - Chạy `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (hoặc tag beta/correction tương ứng) trước khi phê duyệt -- Sau khi publish npm, chạy + (hoặc thẻ beta/sửa lỗi tương ứng) trước khi phê duyệt +- Sau khi phát hành npm, chạy `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - (hoặc phiên bản beta/correction tương ứng) để xác minh đường dẫn cài đặt registry đã - publish trong một temp prefix mới -- Sau khi publish beta, chạy `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` - để xác minh onboarding package đã cài đặt, thiết lập Telegram và Telegram E2E thật với - package npm đã publish bằng pool thông tin xác thực Telegram dùng chung được lease. - Các lần chạy cục bộ một lần của maintainer có thể bỏ qua các biến Convex và truyền trực - tiếp ba thông tin xác thực env `OPENCLAW_QA_TELEGRAM_*`. -- Để chạy toàn bộ post-publish beta smoke từ máy maintainer, dùng `pnpm release:beta-smoke -- --beta betaN`. Helper chạy validation npm update/fresh-target trên Parallels, dispatch `NPM Telegram Beta E2E`, poll đúng workflow run, tải xuống artifact và in báo cáo Telegram. -- Maintainer có thể chạy cùng kiểm tra post-publish từ GitHub Actions qua workflow thủ - công `NPM Telegram Beta E2E`. Workflow này cố ý chỉ chạy thủ công và không chạy trên - mọi merge. -- Tự động hóa phát hành của maintainer hiện dùng preflight-rồi-promote: - - publish npm thật phải vượt qua `preflight_run_id` npm thành công - - publish npm thật phải được dispatch từ cùng branch `main` hoặc - `release/YYYY.M.D` với lần chạy preflight thành công - - phát hành npm stable mặc định là `beta` - - publish npm stable có thể nhắm rõ ràng tới `latest` qua input workflow + (hoặc phiên bản beta/sửa lỗi tương ứng) để xác minh đường dẫn cài đặt registry đã phát hành + trong một prefix tạm mới +- Sau khi phát hành beta, chạy `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` + để xác minh onboarding gói đã cài đặt, thiết lập Telegram, và E2E Telegram thật + trên gói npm đã phát hành bằng nhóm thông tin xác thực Telegram dùng chung theo lease. + Các lần chạy một lần cục bộ của maintainer có thể bỏ qua các biến Convex và truyền trực tiếp ba + thông tin xác thực env `OPENCLAW_QA_TELEGRAM_*`. +- Để chạy toàn bộ smoke beta sau phát hành từ máy maintainer, dùng `pnpm release:beta-smoke -- --beta betaN`. Trình trợ giúp chạy xác thực cập nhật npm Parallels/mục tiêu mới, dispatch `NPM Telegram Beta E2E`, poll đúng lần chạy workflow, tải xuống tạo tác, và in báo cáo Telegram. +- Maintainer có thể chạy cùng kiểm tra sau phát hành từ GitHub Actions qua + workflow thủ công `NPM Telegram Beta E2E`. Nó cố ý chỉ chạy thủ công và + không chạy trên mọi lần merge. +- Tự động hóa phát hành của maintainer hiện dùng kiểm tra trước rồi thăng hạng: + - phát hành npm thật phải vượt qua `preflight_run_id` npm thành công + - phát hành npm thật phải được dispatch từ cùng nhánh `main` hoặc + `release/YYYY.M.D` với lần chạy kiểm tra trước thành công + - các bản phát hành npm ổn định mặc định là `beta` + - phát hành npm ổn định có thể nhắm rõ `latest` qua input workflow - thay đổi npm dist-tag dựa trên token hiện nằm trong `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - để bảo mật, vì `npm dist-tag add` vẫn cần `NPM_TOKEN` trong khi repo công khai - giữ publish chỉ dùng OIDC - - `macOS Release` công khai chỉ dùng cho validation; khi tag chỉ tồn tại trên một - branch release nhưng workflow được dispatch từ `main`, đặt + vì lý do bảo mật, vì `npm dist-tag add` vẫn cần `NPM_TOKEN` trong khi + repo công khai giữ phát hành chỉ dùng OIDC + - `macOS Release` công khai chỉ dùng để xác thực; khi một thẻ chỉ tồn tại trên + nhánh phát hành nhưng workflow được dispatch từ `main`, đặt `public_release_branch=release/YYYY.M.D` - - publish mac riêng tư thật phải vượt qua `preflight_run_id` mac riêng tư thành công và - `validate_run_id` - - các đường dẫn publish thật promote artifact đã chuẩn bị thay vì build lại chúng -- Với các bản phát hành correction stable như `YYYY.M.D-N`, verifier post-publish + - phát hành mac riêng tư thật phải vượt qua `preflight_run_id` và + `validate_run_id` mac riêng tư thành công + - các đường dẫn phát hành thật thăng hạng tạo tác đã chuẩn bị thay vì build lại + chúng một lần nữa +- Với các bản phát hành sửa lỗi ổn định như `YYYY.M.D-N`, bộ xác minh sau phát hành cũng kiểm tra cùng đường dẫn nâng cấp temp-prefix từ `YYYY.M.D` lên `YYYY.M.D-N` - để các bản sửa phát hành không thể âm thầm để lại bản cài đặt global cũ trên payload - stable cơ sở -- Preflight phát hành npm thất bại đóng trừ khi tarball bao gồm cả + để các bản sửa lỗi phát hành không thể âm thầm để các cài đặt global cũ ở + payload ổn định cơ sở +- Bước kiểm tra trước phát hành npm thất bại đóng trừ khi tarball bao gồm cả `dist/control-ui/index.html` và payload `dist/control-ui/assets/` không rỗng - để chúng ta không ship dashboard trình duyệt trống một lần nữa -- Verification post-publish cũng kiểm tra rằng entrypoint plugin đã publish và - metadata package có mặt trong bố cục registry đã cài đặt. Một bản phát hành ship thiếu - payload runtime plugin sẽ làm verifier postpublish thất bại và không thể được promote - lên `latest`. -- `pnpm test:install:smoke` cũng áp dụng ngân sách `unpackedSize` của npm pack lên - tarball cập nhật ứng viên, để installer e2e bắt được việc pack phình to ngoài ý muốn - trước đường dẫn publish phát hành -- Nếu công việc phát hành chạm tới lập kế hoạch CI, manifest thời gian plugin hoặc - ma trận kiểm thử plugin, hãy tạo lại và review các output ma trận + để chúng ta không giao lại một dashboard trình duyệt rỗng +- Xác minh sau phát hành cũng kiểm tra rằng các entrypoint Plugin đã phát hành và + siêu dữ liệu gói có trong bố cục registry đã cài đặt. Một bản phát hành + thiếu payload runtime Plugin sẽ thất bại ở bộ xác minh sau phát hành và + không thể được thăng hạng lên `latest`. +- `pnpm test:install:smoke` cũng thực thi ngân sách `unpackedSize` của gói npm trên + tarball cập nhật ứng viên, để e2e trình cài đặt bắt được việc gói phình to ngoài ý muốn + trước đường dẫn phát hành +- Nếu công việc phát hành chạm tới lập kế hoạch CI, manifest thời gian extension, hoặc + ma trận kiểm thử extension, hãy tạo lại và xem xét các đầu ra ma trận `plugin-prerelease-extension-shard` do planner sở hữu từ - `.github/workflows/plugin-prerelease.yml` trước khi phê duyệt để release notes không - mô tả một bố cục CI đã cũ -- Mức sẵn sàng phát hành macOS stable cũng bao gồm các bề mặt updater: - - GitHub release cuối cùng phải có `.zip`, `.dmg` và `.dSYM.zip` đã đóng gói - - `appcast.xml` trên `main` phải trỏ tới zip stable mới sau khi publish - - app đã đóng gói phải giữ bundle id không phải debug, URL Sparkle feed không rỗng và - `CFBundleVersion` bằng hoặc cao hơn mức sàn build Sparkle chuẩn cho phiên bản phát - hành đó + `.github/workflows/plugin-prerelease.yml` trước khi phê duyệt để ghi chú phát hành không + mô tả một bố cục CI đã lỗi thời +- Trạng thái sẵn sàng phát hành macOS ổn định cũng bao gồm các bề mặt updater: + - GitHub release phải kết thúc với các gói `.zip`, `.dmg`, và `.dSYM.zip` + - `appcast.xml` trên `main` phải trỏ tới zip ổn định mới sau khi phát hành + - ứng dụng đã đóng gói phải giữ bundle id không phải debug, URL feed Sparkle + không rỗng, và `CFBundleVersion` bằng hoặc cao hơn mức sàn build Sparkle chuẩn + cho phiên bản phát hành đó -## Test box phát hành +## Hộp kiểm thử phát hành `Full Release Validation` là cách operator khởi động tất cả kiểm thử tiền phát hành từ -một entrypoint. Để có bằng chứng commit đã pin trên một branch thay đổi nhanh, dùng -helper để mọi workflow con chạy từ một branch tạm thời được cố định ở SHA mục tiêu: +một điểm vào. Để có bằng chứng commit được ghim trên một nhánh thay đổi nhanh, dùng +trình trợ giúp để mọi workflow con chạy từ một nhánh tạm thời cố định tại SHA mục tiêu: ```bash pnpm ci:full-release --sha ``` -Helper push `release-ci/-...`, dispatch `Full Release Validation` -từ branch đó với `ref=`, xác minh mọi workflow con có `headSha` -khớp với mục tiêu, rồi xóa branch tạm thời. Việc này tránh vô tình chứng minh một lần -chạy con `main` mới hơn. +Trình trợ giúp push `release-ci/-...`, dispatch `Full Release Validation` +từ nhánh đó với `ref=`, xác minh mọi `headSha` workflow con +khớp với mục tiêu, rồi xóa nhánh tạm thời. Điều này tránh việc vô tình chứng minh một +lần chạy con `main` mới hơn. -Để validation branch hoặc tag phát hành, chạy từ workflow ref `main` tin cậy và truyền -branch hoặc tag phát hành làm `ref`: +Để xác thực nhánh hoặc thẻ phát hành, chạy nó từ workflow ref `main` đáng tin cậy +và truyền nhánh hoặc thẻ phát hành làm `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -282,46 +290,51 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -Quy trình làm việc phân giải ref đích, kích hoạt thủ công `CI` với -`target_ref=`, kích hoạt `OpenClaw Release Checks`, chuẩn bị artifact -cha `release-package-under-test` cho các kiểm tra hướng đến gói, và -kích hoạt Telegram E2E độc lập cho gói khi `release_profile=full` với -`rerun_group=all` hoặc khi `npm_telegram_package_spec` được đặt. Sau đó `OpenClaw Release -Checks` mở rộng thành install smoke, kiểm tra phát hành đa hệ điều hành, phạm vi -live/E2E Docker cho đường dẫn phát hành, Package Acceptance với QA gói Telegram, QA Lab -parity, Matrix live, và Telegram live. Một lượt chạy đầy đủ chỉ được chấp nhận khi +Quy trình phân giải ref đích, kích hoạt thủ công `CI` với +`target_ref=`, kích hoạt `OpenClaw Release Checks`, chuẩn bị một +artifact cha `release-package-under-test` cho các kiểm tra hướng đến package, và +kích hoạt Telegram E2E package độc lập khi `release_profile=full` với +`rerun_group=all` hoặc khi `npm_telegram_package_spec` được đặt. Sau đó +`OpenClaw Release Checks` mở rộng sang install smoke, kiểm tra phát hành đa hệ điều hành, phạm vi live/E2E Docker +trên đường dẫn phát hành khi soak được bật, Package Acceptance với QA package +Telegram, QA Lab parity, Matrix live, và Telegram live. Một lần chạy đầy đủ chỉ được chấp nhận khi tóm tắt `Full Release Validation` hiển thị `normal_ci` và `release_checks` thành công. Ở chế độ full/all, -child `npm_telegram` cũng phải thành công; ngoài full/all, nó bị bỏ qua +nhánh con `npm_telegram` cũng phải thành công; ngoài full/all, nhánh này được bỏ qua trừ khi đã cung cấp một `npm_telegram_package_spec` đã phát hành. Tóm tắt -xác minh cuối cùng bao gồm các bảng job chậm nhất cho từng child run, để người quản lý phát hành -có thể thấy đường tới hạn hiện tại mà không cần tải log xuống. +xác minh cuối cùng bao gồm các bảng tác vụ chậm nhất cho từng lần chạy con, để người quản lý phát hành +có thể thấy đường găng hiện tại mà không cần tải nhật ký xuống. Xem [Xác thực phát hành đầy đủ](/vi/reference/full-release-validation) để biết -ma trận giai đoạn đầy đủ, tên job workflow chính xác, khác biệt giữa profile stable và full, -artifact, và các handle rerun tập trung. -Các workflow con được kích hoạt từ ref tin cậy chạy `Full Release -Validation`, thường là `--ref main`, ngay cả khi `ref` đích trỏ tới một -nhánh hoặc tag phát hành cũ hơn. Không có input workflow-ref riêng cho Full Release Validation; -hãy chọn harness tin cậy bằng cách chọn ref chạy workflow. -Không dùng `--ref main -f ref=` để làm bằng chứng commit chính xác trên `main` đang dịch chuyển; -SHA commit thô không thể là workflow dispatch ref, vì vậy hãy dùng +ma trận giai đoạn hoàn chỉnh, tên tác vụ workflow chính xác, khác biệt giữa hồ sơ stable và full, +artifact, và các handle chạy lại tập trung. +Các workflow con được kích hoạt từ ref đáng tin cậy chạy `Full Release +Validation`, thường là `--ref main`, ngay cả khi `ref` đích trỏ đến một +nhánh hoặc thẻ phát hành cũ hơn. Không có input workflow-ref riêng cho Full Release Validation; +hãy chọn harness đáng tin cậy bằng cách chọn ref chạy workflow. +Không dùng `--ref main -f ref=` để chứng minh commit chính xác trên `main` đang di chuyển; +SHA commit thô không thể là ref kích hoạt workflow, vì vậy hãy dùng `pnpm ci:full-release --sha ` để tạo nhánh tạm thời đã ghim. -Dùng `release_profile` để chọn phạm vi live/provider: +Dùng `release_profile` để chọn độ phủ live/provider: -- `minimum`: đường dẫn OpenAI/core live và Docker nhanh nhất, quan trọng cho phát hành -- `stable`: minimum cộng với phạm vi provider/backend ổn định để phê duyệt phát hành -- `full`: stable cộng với phạm vi provider/media tư vấn rộng +- `minimum`: đường dẫn OpenAI/core live và Docker nhanh nhất, trọng yếu cho phát hành +- `stable`: minimum cộng thêm độ phủ provider/backend ổn định để phê duyệt phát hành +- `full`: stable cộng thêm độ phủ provider/media tư vấn rộng -`OpenClaw Release Checks` dùng ref workflow tin cậy để phân giải ref đích -một lần thành `release-package-under-test` và tái sử dụng artifact đó trong cả -kiểm tra Docker đường dẫn phát hành lẫn Package Acceptance. Điều này giữ mọi -box hướng đến gói trên cùng một bộ byte và tránh build gói lặp lại. +Dùng `run_release_soak=true` với `stable` khi các lane chặn phát hành đã +xanh và bạn muốn quét live/E2E đầy đủ, đường dẫn phát hành Docker, và +toàn bộ upgrade-survivor từ 2026.4.23 trở đi trước khi promotion. `full` ngụ ý +`run_release_soak=true`. + +`OpenClaw Release Checks` dùng ref workflow đáng tin cậy để phân giải ref đích +một lần thành `release-package-under-test` và tái sử dụng artifact đó trong các kiểm tra đa hệ điều hành, +Package Acceptance, và Docker đường dẫn phát hành khi soak chạy. Điều này giữ +mọi máy kiểm tra hướng đến package trên cùng một byte và tránh build package lặp lại. Install smoke OpenAI đa hệ điều hành dùng `OPENCLAW_CROSS_OS_OPENAI_MODEL` khi biến repo/org được đặt, nếu không thì dùng `openai/gpt-5.4`, vì lane này đang -chứng minh cài đặt gói, onboarding, khởi động gateway, và một lượt tác nhân live -thay vì benchmark model mặc định chậm nhất. Ma trận provider live rộng hơn -vẫn là nơi dành cho phạm vi theo model cụ thể. +chứng minh cài đặt package, onboarding, khởi động gateway, và một lượt agent live +thay vì benchmark mô hình mặc định chậm nhất. Ma trận provider live rộng hơn +vẫn là nơi dành cho độ phủ theo từng mô hình. Dùng các biến thể này tùy theo giai đoạn phát hành: @@ -353,40 +366,44 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Không dùng umbrella đầy đủ làm lượt rerun đầu tiên sau một bản sửa tập trung. Nếu một box -thất bại, hãy dùng workflow con, job, lane Docker, profile gói, provider model, -hoặc lane QA đã thất bại cho bằng chứng tiếp theo. Chỉ chạy lại umbrella đầy đủ khi -bản sửa đã thay đổi điều phối phát hành dùng chung hoặc làm bằng chứng mọi box trước đó -trở nên lỗi thời. Bộ xác minh cuối của umbrella kiểm tra lại các id run workflow con -đã ghi nhận, vì vậy sau khi một workflow con được rerun thành công, chỉ rerun job cha +Không dùng umbrella đầy đủ làm lần chạy lại đầu tiên sau một bản sửa tập trung. Nếu một máy +thất bại, hãy dùng workflow con, tác vụ, lane Docker, hồ sơ package, provider +mô hình, hoặc lane QA bị lỗi cho bằng chứng tiếp theo. Chỉ chạy lại umbrella đầy đủ khi +bản sửa đã thay đổi điều phối phát hành dùng chung hoặc làm bằng chứng toàn bộ máy trước đó +không còn hiện hành. Bộ xác minh cuối cùng của umbrella kiểm tra lại các id lần chạy workflow con +đã ghi lại, vì vậy sau khi một workflow con được chạy lại thành công, chỉ chạy lại tác vụ cha `Verify full validation` đã thất bại. -Để khôi phục có giới hạn, truyền `rerun_group` cho umbrella. `all` là lượt chạy -release-candidate thực sự, `ci` chỉ chạy child CI bình thường, `plugin-prerelease` -chỉ chạy child plugin chỉ dành cho phát hành, `release-checks` chạy mọi box phát hành, +Để phục hồi có giới hạn, truyền `rerun_group` cho umbrella. `all` là lần chạy +release-candidate thực sự, `ci` chỉ chạy nhánh con CI bình thường, `plugin-prerelease` +chỉ chạy nhánh con plugin chỉ dành cho phát hành, `release-checks` chạy mọi hộp phát hành, và các nhóm phát hành hẹp hơn là `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, và `npm-telegram`. -Các rerun `npm-telegram` tập trung yêu cầu `npm_telegram_package_spec`; các lượt full/all -với `release_profile=full` dùng artifact gói release-checks. +Các lần chạy lại `npm-telegram` tập trung yêu cầu `npm_telegram_package_spec`; các lần chạy full/all +với `release_profile=full` dùng artifact package của release-checks. Các lần chạy lại +đa hệ điều hành tập trung có thể thêm `cross_os_suite_filter=windows/packaged-upgrade` hoặc +bộ lọc OS/suite khác. Lỗi QA release-check là tư vấn; lỗi chỉ ở QA +không chặn xác thực phát hành. ### Vitest -Box Vitest là workflow con `CI` thủ công. CI thủ công cố ý -bỏ qua scoping theo thay đổi và ép đồ thị kiểm thử bình thường cho release -candidate: shard Linux Node, shard Plugin đi kèm, contract kênh, khả năng tương thích Node 22, -`check`, `check-additional`, build smoke, kiểm tra docs, Skills Python, Windows, macOS, Android, và Control UI i18n. +Hộp Vitest là workflow con `CI` thủ công. CI thủ công cố ý +bỏ qua phạm vi changed và buộc đồ thị kiểm thử bình thường cho ứng viên phát hành: +các shard Linux Node, shard bundled-plugin, hợp đồng kênh, tương thích Node 22, +`check`, `check-additional`, build smoke, kiểm tra tài liệu, Python +skills, Windows, macOS, Android, và i18n Control UI. -Dùng box này để trả lời "cây nguồn có vượt qua toàn bộ bộ kiểm thử bình thường không?" +Dùng hộp này để trả lời "cây mã nguồn có vượt qua bộ kiểm thử bình thường đầy đủ không?" Nó không giống xác thực sản phẩm theo đường dẫn phát hành. Bằng chứng cần giữ: -- tóm tắt `Full Release Validation` hiển thị URL run `CI` đã kích hoạt -- run `CI` xanh trên đúng SHA đích -- tên shard thất bại hoặc chậm từ các job CI khi điều tra hồi quy -- artifact timing Vitest như `.artifacts/vitest-shard-timings.json` khi - một lượt chạy cần phân tích hiệu năng +- tóm tắt `Full Release Validation` hiển thị URL lần chạy `CI` đã kích hoạt +- lần chạy `CI` xanh trên SHA đích chính xác +- tên shard lỗi hoặc chậm từ các tác vụ CI khi điều tra hồi quy +- artifact thời gian Vitest như `.artifacts/vitest-shard-timings.json` khi + một lần chạy cần phân tích hiệu năng -Chỉ chạy CI thủ công trực tiếp khi bản phát hành cần CI bình thường tất định nhưng -không cần Docker, QA Lab, live, đa hệ điều hành, hoặc box gói: +Chỉ chạy CI thủ công trực tiếp khi phát hành cần CI bình thường xác định nhưng +không cần các hộp Docker, QA Lab, live, đa hệ điều hành, hoặc package: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -394,17 +411,17 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Box Docker nằm trong `OpenClaw Release Checks` thông qua -`openclaw-live-and-e2e-checks-reusable.yml`, cộng với workflow `install-smoke` -chế độ phát hành. Nó xác thực release candidate qua môi trường Docker đóng gói -thay vì chỉ qua kiểm thử cấp nguồn. +Hộp Docker nằm trong `OpenClaw Release Checks` thông qua +`openclaw-live-and-e2e-checks-reusable.yml`, cộng với workflow +`install-smoke` chế độ phát hành. Nó xác thực ứng viên phát hành thông qua môi trường +Docker đã đóng gói thay vì chỉ kiểm thử ở mức mã nguồn. -Phạm vi Docker phát hành bao gồm: +Độ phủ Docker phát hành bao gồm: -- install smoke đầy đủ với slow Bun global install smoke được bật -- chuẩn bị/tái sử dụng image smoke Dockerfile gốc theo SHA đích, với các job QR, - root/gateway, và installer/Bun smoke chạy như các shard install-smoke riêng -- các lane E2E của repository +- install smoke đầy đủ với smoke cài đặt Bun global chậm được bật +- chuẩn bị/tái sử dụng image smoke root Dockerfile theo SHA đích, với các tác vụ smoke QR, + root/gateway, và installer/Bun chạy như các shard install-smoke riêng +- các lane E2E kho mã - các chunk Docker đường dẫn phát hành: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, @@ -412,91 +429,94 @@ Phạm vi Docker phát hành bao gồm: `plugins-runtime-install-c`, `plugins-runtime-install-d`, `plugins-runtime-install-e`, `plugins-runtime-install-f`, `plugins-runtime-install-g`, và `plugins-runtime-install-h` -- phạm vi OpenWebUI bên trong chunk `plugins-runtime-services` khi được yêu cầu -- các lane cài đặt/gỡ cài đặt Plugin đi kèm đã tách +- độ phủ OpenWebUI bên trong chunk `plugins-runtime-services` khi được yêu cầu +- các lane cài đặt/gỡ cài đặt bundled plugin được tách `bundled-plugin-install-uninstall-0` đến `bundled-plugin-install-uninstall-23` -- các bộ provider live/E2E và phạm vi model live Docker khi release checks - bao gồm bộ live +- các bộ provider live/E2E và độ phủ mô hình Docker live khi release checks + bao gồm các bộ live -Dùng artifact Docker trước khi rerun. Bộ lập lịch đường dẫn phát hành tải lên -`.artifacts/docker-tests/` với log lane, `summary.json`, `failures.json`, -timing pha, JSON kế hoạch scheduler, và lệnh rerun. Để khôi phục tập trung, +Dùng artifact Docker trước khi chạy lại. Bộ lập lịch đường dẫn phát hành tải lên +`.artifacts/docker-tests/` với nhật ký lane, `summary.json`, `failures.json`, +thời gian pha, JSON kế hoạch lập lịch, và lệnh chạy lại. Để phục hồi tập trung, dùng `docker_lanes=` trên workflow live/E2E tái sử dụng thay vì -rerun mọi chunk phát hành. Các lệnh rerun được tạo bao gồm +chạy lại mọi chunk phát hành. Các lệnh chạy lại được tạo bao gồm `package_artifact_run_id` trước đó và input image Docker đã chuẩn bị khi có, để một lane thất bại có thể tái sử dụng cùng tarball và image GHCR. ### QA Lab -Box QA Lab cũng là một phần của `OpenClaw Release Checks`. Đây là cổng phát hành -hành vi tác nhân và cấp kênh, tách biệt với cơ chế gói của Vitest và Docker. +Hộp QA Lab cũng là một phần của `OpenClaw Release Checks`. Đây là +cổng phát hành cho hành vi agentic và cấp kênh, tách biệt với Vitest và cơ chế +package Docker. -Phạm vi QA Lab phát hành bao gồm: +Độ phủ QA Lab phát hành bao gồm: -- lane parity giả lập so sánh lane candidate OpenAI với baseline Opus 4.6 - bằng agentic parity pack -- profile QA Matrix live nhanh dùng môi trường `qa-live-shared` -- lane QA Telegram live dùng lease thông tin xác thực Convex CI +- lane parity mock so sánh lane ứng viên OpenAI với baseline Opus 4.6 + bằng pack parity agentic +- hồ sơ QA Matrix live nhanh bằng môi trường `qa-live-shared` +- lane QA Telegram live bằng lease thông tin xác thực Convex CI - `pnpm qa:otel:smoke` khi telemetry phát hành cần bằng chứng cục bộ rõ ràng -Dùng box này để trả lời "bản phát hành có hoạt động đúng trong các kịch bản QA và -luồng kênh live không?" Giữ các URL artifact cho các lane parity, Matrix, và Telegram -khi phê duyệt phát hành. Phạm vi Matrix đầy đủ vẫn có sẵn dưới dạng -lượt chạy QA-Lab sharded thủ công thay vì lane mặc định quan trọng cho phát hành. +Dùng hộp này để trả lời "bản phát hành có hoạt động đúng trong các kịch bản QA và +luồng kênh live không?" Giữ URL artifact cho các lane parity, Matrix, và Telegram +khi phê duyệt phát hành. Độ phủ Matrix đầy đủ vẫn có sẵn dưới dạng lần chạy QA-Lab +sharded thủ công thay vì lane mặc định trọng yếu cho phát hành. -### Gói +### Package -Box Gói là cổng sản phẩm có thể cài đặt. Nó được hậu thuẫn bởi +Hộp Package là cổng sản phẩm có thể cài đặt. Nó được hỗ trợ bởi `Package Acceptance` và resolver `scripts/resolve-openclaw-package-candidate.mjs`. Resolver chuẩn hóa một -candidate thành tarball `package-under-test` được Docker E2E tiêu thụ, xác thực -inventory gói, ghi lại phiên bản gói và SHA-256, và giữ ref harness workflow -tách biệt với ref nguồn gói. +ứng viên thành tarball `package-under-test` được Docker E2E dùng, xác thực +inventory package, ghi lại phiên bản package và SHA-256, và giữ ref harness +workflow tách khỏi ref nguồn package. -Các nguồn candidate được hỗ trợ: +Nguồn ứng viên được hỗ trợ: - `source=npm`: `openclaw@beta`, `openclaw@latest`, hoặc một phiên bản phát hành OpenClaw chính xác -- `source=ref`: đóng gói một nhánh `package_ref`, tag, hoặc SHA commit đầy đủ tin cậy +- `source=ref`: đóng gói một nhánh, thẻ, hoặc SHA commit đầy đủ `package_ref` đáng tin cậy với harness `workflow_ref` đã chọn -- `source=url`: tải xuống `.tgz` HTTPS với `package_sha256` bắt buộc -- `source=artifact`: tái sử dụng `.tgz` được tải lên bởi một run GitHub Actions khác +- `source=url`: tải xuống một `.tgz` HTTPS với `package_sha256` bắt buộc +- `source=artifact`: tái sử dụng một `.tgz` do lần chạy GitHub Actions khác tải lên `OpenClaw Release Checks` chạy Package Acceptance với `source=artifact`, artifact -gói phát hành đã chuẩn bị, `suite_profile=custom`, +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`, -`published_upgrade_survivor_baselines=all-since-2026.4.23`, -`published_upgrade_survivor_scenarios=reported-issues`, và -`telegram_mode=mock-openai`. Package Acceptance giữ migration, update, dọn dẹp phụ thuộc Plugin cũ, -fixture Plugin offline, update Plugin, và QA gói Telegram trên cùng tarball đã phân giải. Ma trận nâng cấp bao phủ mọi baseline ổn định đã phát hành npm từ `2026.4.23` đến `latest`; dùng -Package Acceptance với `source=npm` cho một candidate đã phát hành, hoặc -`source=ref`/`source=artifact` cho một tarball npm cục bộ có backing SHA trước khi -publish. Đây là giải pháp thay thế GitHub-native -cho phần lớn phạm vi package/update trước đây cần Parallels. Kiểm tra phát hành đa hệ điều hành vẫn quan trọng cho onboarding, -installer, và hành vi nền tảng theo hệ điều hành, nhưng xác thực sản phẩm package/update nên +`telegram_mode=mock-openai`. Package Acceptance giữ migration, update, dọn dẹp +phụ thuộc plugin cũ, fixture plugin offline, update plugin, và QA package Telegram +trên cùng một tarball đã phân giải. Các kiểm tra phát hành chặn dùng baseline +package đã phát hành mới nhất mặc định; `run_release_soak=true` hoặc +`release_profile=full` mở rộng tới mọi baseline npm-published ổn định từ +`2026.4.23` đến `latest` cộng với fixture issue đã báo cáo. Dùng +Package Acceptance với `source=npm` cho một ứng viên đã shipped, hoặc +`source=ref`/`source=artifact` cho tarball npm cục bộ có SHA hậu thuẫn trước khi +publish. Đây là giải pháp thay thế gốc GitHub cho phần lớn độ phủ package/update +trước đây cần Parallels. Kiểm tra phát hành đa hệ điều hành vẫn quan trọng cho onboarding, +installer, và hành vi nền tảng riêng theo OS, nhưng xác thực sản phẩm package/update nên ưu tiên Package Acceptance. -Checklist chuẩn cho xác thực update và Plugin là -[Kiểm thử update và Plugin](/vi/help/testing-updates-plugins). Dùng nó khi +Checklist chính tắc cho xác thực update và plugin là +[Kiểm thử update và plugin](/vi/help/testing-updates-plugins). Dùng nó khi quyết định lane cục bộ, Docker, Package Acceptance, hoặc release-check nào chứng minh một -thay đổi cài đặt/update Plugin, dọn dẹp doctor, hoặc migration gói đã phát hành. -Migration update đã phát hành toàn diện từ mọi gói ổn định `2026.4.23+` là -một workflow `Update Migration` thủ công riêng, không thuộc Full Release CI. +thay đổi cài đặt/update plugin, dọn dẹp doctor, hoặc migration package đã phát hành. +Migration update đã phát hành đầy đủ từ mọi package `2026.4.23+` ổn định là +workflow `Update Migration` thủ công riêng, không phải một phần của Full Release CI. -Tính nới lỏng package-acceptance kế thừa được giới hạn thời gian có chủ ý. Các gói đến -`2026.4.25` có thể dùng đường tương thích cho các khoảng trống metadata đã phát hành -lên npm: mục inventory QA private thiếu trong tarball, thiếu -`gateway install --wrapper`, thiếu patch file trong fixture git dẫn xuất từ tarball, -thiếu `update.channel` được lưu bền, vị trí bản ghi cài đặt Plugin cũ, -thiếu lưu bền bản ghi cài đặt marketplace, và migration metadata config -trong `plugins update`. Gói `2026.4.26` đã phát hành có thể cảnh báo -cho 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 contract gói hiện đại; chính các khoảng trống đó sẽ làm xác thực +Sự nới lỏng package-acceptance legacy được cố ý giới hạn thời gian. Các package đến +`2026.4.25` có thể dùng đường dẫn tương thích cho các khoảng trống metadata đã được publish +lên npm: mục inventory QA private bị thiếu trong tarball, thiếu +`gateway install --wrapper`, thiếu file patch trong fixture git dẫn xuất từ tarball, +thiếu `update.channel` đã persisted, vị trí install-record plugin legacy, +thiếu persistence install-record marketplace, và migration metadata config +trong `plugins update`. Package `2026.4.26` đã publish có thể cảnh báo +về các file stamp metadata build cục bộ đã được shipped. Các package sau đó +phải thỏa mãn hợp đồng package hiện đại; chính các khoảng trống đó sẽ làm xác thực phát hành thất bại. -Dùng các profile Package Acceptance rộng hơn khi câu hỏi phát hành liên quan đến một -gói thực sự có thể cài đặt: +Dùng hồ sơ Package Acceptance rộng hơn khi câu hỏi phát hành liên quan đến một +package có thể cài đặt thực tế: ```bash gh workflow run package-acceptance.yml \ @@ -508,34 +528,34 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -Các profile gói thường dùng: +Các hồ sơ gói phổ biến: -- `smoke`: các làn cài đặt nhanh gói/kênh/agent, mạng Gateway và tải lại cấu hình -- `package`: các hợp đồng cài đặt/cập nhật/gói Plugin không có ClawHub trực tiếp; đây là mặc định kiểm tra phát hành -- `product`: `package` cộng với các kênh MCP, dọn dẹp cron/subagent, tìm kiếm web OpenAI và OpenWebUI +- `smoke`: các làn cài đặt gói/kênh/tác tử, mạng Gateway và tải lại cấu hình nhanh +- `package`: hợp đồng cài đặt/cập nhật/gói Plugin không có ClawHub trực tiếp; đây là mặc định của kiểm tra phát hành +- `product`: `package` cộng với các kênh MCP, dọn dẹp cron/tác tử phụ, tìm kiếm web OpenAI và OpenWebUI - `full`: các phần đường dẫn phát hành Docker với OpenWebUI - `custom`: danh sách `docker_lanes` chính xác cho các lần chạy lại tập trung -Để có bằng chứng Telegram cho ứng viên gói, hãy bật `telegram_mode=mock-openai` hoặc -`telegram_mode=live-frontier` trên Package Acceptance. Quy trình truyền tarball -`package-under-test` đã phân giải vào làn Telegram; quy trình Telegram độc lập -vẫn chấp nhận đặc tả npm đã phát hành cho các kiểm tra sau phát hành. +Để chứng minh Telegram cho ứng viên gói, hãy bật `telegram_mode=mock-openai` hoặc +`telegram_mode=live-frontier` trên Package Acceptance. Workflow truyền tarball +`package-under-test` đã được phân giải vào làn Telegram; workflow Telegram độc lập +vẫn chấp nhận thông số npm đã phát hành cho các kiểm tra sau phát hành. -## Tự động hóa phát hành bản xuất bản +## Tự động hóa phát hành -`OpenClaw Release Publish` là điểm vào xuất bản có thay đổi trạng thái thông thường. Nó -điều phối các quy trình trusted-publisher theo thứ tự mà bản phát hành cần: +`OpenClaw Release Publish` là điểm vào phát hành có thay đổi trạng thái thông thường. Nó +điều phối các workflow nhà phát hành tin cậy theo thứ tự mà bản phát hành cần: 1. Checkout thẻ phát hành và phân giải SHA commit của thẻ đó. -2. Xác minh thẻ có thể truy cập từ `main` hoặc `release/*`. +2. Xác minh thẻ có thể truy cập được từ `main` hoặc `release/*`. 3. Chạy `pnpm plugins:sync:check`. -4. Dispatch `Plugin NPM Release` với `publish_scope=all-publishable` và +4. Kích hoạt `Plugin NPM Release` với `publish_scope=all-publishable` và `ref=`. -5. Dispatch `Plugin ClawHub Release` với cùng phạm vi và SHA. -6. Dispatch `OpenClaw NPM Release` với thẻ phát hành, npm dist-tag và +5. Kích hoạt `Plugin ClawHub Release` với cùng phạm vi và SHA. +6. Kích hoạt `OpenClaw NPM Release` với thẻ phát hành, dist-tag npm và `preflight_run_id` đã lưu. -Ví dụ xuất bản beta: +Ví dụ phát hành beta: ```bash gh workflow run openclaw-release-publish.yml \ @@ -545,7 +565,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Xuất bản ổn định lên dist-tag beta mặc định: +Phát hành ổn định lên dist-tag beta mặc định: ```bash gh workflow run openclaw-release-publish.yml \ @@ -555,7 +575,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Quảng bá bản ổn định trực tiếp lên `latest` là thao tác tường minh: +Quảng bá ổn định trực tiếp lên `latest` là thao tác tường minh: ```bash gh workflow run openclaw-release-publish.yml \ @@ -565,92 +585,95 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -Chỉ dùng các quy trình cấp thấp hơn `Plugin NPM Release` và `Plugin ClawHub Release` -cho công việc sửa chữa hoặc xuất bản lại tập trung. Để sửa chữa một Plugin đã chọn, truyền +Chỉ dùng các workflow cấp thấp hơn `Plugin NPM Release` và `Plugin ClawHub Release` +cho công việc sửa chữa hoặc phát hành lại tập trung. Với một sửa chữa Plugin được chọn, truyền `plugin_publish_scope=selected` và `plugins=@openclaw/name` cho -`OpenClaw Release Publish`, hoặc dispatch trực tiếp quy trình con khi không được xuất bản +`OpenClaw Release Publish`, hoặc kích hoạt trực tiếp workflow con khi không được phát hành gói OpenClaw. -## Đầu vào quy trình NPM +## Đầu vào workflow NPM -`OpenClaw NPM Release` chấp nhận các đầu vào do operator kiểm soát sau: +`OpenClaw NPM Release` chấp nhận các đầu vào do người vận hành kiểm soát sau: -- `tag`: thẻ phát hành bắt buộc như `v2026.4.2`, `v2026.4.2-1` hoặc - `v2026.4.2-beta.1`; khi `preflight_only=true`, nó cũng có thể là SHA commit - đầy đủ 40 ký tự hiện tại của nhánh quy trình cho preflight chỉ xác thực -- `preflight_only`: `true` để chỉ xác thực/xây dựng/đóng gói, `false` cho đường dẫn - xuất bản thật -- `preflight_run_id`: bắt buộc trên đường dẫn xuất bản thật để quy trình dùng lại +- `tag`: thẻ phát hành bắt buộc, chẳng hạn như `v2026.4.2`, `v2026.4.2-1` hoặc + `v2026.4.2-beta.1`; khi `preflight_only=true`, nó cũng có thể là SHA commit đầy đủ + 40 ký tự hiện tại của nhánh workflow cho preflight chỉ xác thực +- `preflight_only`: `true` chỉ để xác thực/build/gói, `false` cho đường dẫn phát hành thật +- `preflight_run_id`: bắt buộc trên đường dẫn phát hành thật để workflow dùng lại tarball đã chuẩn bị từ lần chạy preflight thành công -- `npm_dist_tag`: thẻ đích npm cho đường dẫn xuất bản; mặc định là `beta` +- `npm_dist_tag`: thẻ npm đích cho đường dẫn phát hành; mặc định là `beta` -`OpenClaw Release Publish` chấp nhận các đầu vào do operator kiểm soát sau: +`OpenClaw Release Publish` chấp nhận các đầu vào do người vận hành kiểm soát sau: - `tag`: thẻ phát hành bắt buộc; phải đã tồn tại - `preflight_run_id`: id lần chạy preflight `OpenClaw NPM Release` thành công; bắt buộc khi `publish_openclaw_npm=true` -- `npm_dist_tag`: thẻ đích npm cho gói OpenClaw +- `npm_dist_tag`: thẻ npm đích cho gói OpenClaw - `plugin_publish_scope`: mặc định là `all-publishable`; chỉ dùng `selected` cho công việc sửa chữa tập trung - `plugins`: tên gói `@openclaw/*` phân tách bằng dấu phẩy khi `plugin_publish_scope=selected` -- `publish_openclaw_npm`: mặc định là `true`; chỉ đặt `false` khi dùng quy trình - như một bộ điều phối sửa chữa chỉ dành cho Plugin +- `publish_openclaw_npm`: mặc định là `true`; chỉ đặt `false` khi dùng workflow + làm bộ điều phối sửa chữa chỉ dành cho Plugin -`OpenClaw Release Checks` chấp nhận các đầu vào do operator kiểm soát sau: +`OpenClaw Release Checks` chấp nhận các đầu vào do người vận hành kiểm soát sau: -- `ref`: nhánh, thẻ hoặc SHA commit đầy đủ để xác thực. Các kiểm tra có chứa secret - yêu cầu commit đã phân giải có thể truy cập từ một nhánh OpenClaw hoặc +- `ref`: nhánh, thẻ hoặc SHA commit đầy đủ cần xác thực. Các kiểm tra mang bí mật + yêu cầu commit đã phân giải phải có thể truy cập được từ một nhánh OpenClaw hoặc thẻ phát hành. +- `run_release_soak`: chọn chạy soak đầy đủ live/E2E, đường dẫn phát hành Docker và + tất cả các kiểm tra upgrade-survivor kể từ trước trên các kiểm tra phát hành ổn định/mặc định. Nó bị buộc + bật bởi `release_profile=full`. Quy tắc: -- Thẻ ổn định và thẻ sửa lỗi có thể xuất bản lên `beta` hoặc `latest` -- Thẻ prerelease beta chỉ có thể xuất bản lên `beta` +- Thẻ ổn định và thẻ sửa lỗi có thể phát hành lên `beta` hoặc `latest` +- Thẻ prerelease beta chỉ có thể phát hành lên `beta` - Với `OpenClaw NPM Release`, đầu vào SHA commit đầy đủ chỉ được phép khi `preflight_only=true` -- `OpenClaw Release Checks` và `Full Release Validation` luôn chỉ dùng để xác thực -- Đường dẫn xuất bản thật phải dùng cùng `npm_dist_tag` đã dùng trong preflight; - quy trình xác minh metadata đó trước khi tiếp tục xuất bản +- `OpenClaw Release Checks` và `Full Release Validation` luôn + chỉ để xác thực +- Đường dẫn phát hành thật phải dùng cùng `npm_dist_tag` đã dùng trong preflight; + workflow xác minh metadata đó trước khi tiếp tục phát hành ## Trình tự phát hành npm ổn định Khi tạo một bản phát hành npm ổn định: 1. Chạy `OpenClaw NPM Release` với `preflight_only=true` - - Trước khi thẻ tồn tại, bạn có thể dùng SHA commit đầy đủ hiện tại của nhánh quy trình - cho một lần chạy thử chỉ xác thực của quy trình preflight -2. Chọn `npm_dist_tag=beta` cho luồng beta-trước thông thường, hoặc `latest` chỉ - khi bạn cố ý muốn xuất bản ổn định trực tiếp + - Trước khi có thẻ, bạn có thể dùng SHA commit đầy đủ hiện tại của nhánh workflow + cho một lần chạy thử chỉ xác thực của workflow preflight +2. Chọn `npm_dist_tag=beta` cho luồng beta trước thông thường, hoặc `latest` chỉ + khi bạn cố ý muốn phát hành ổn định trực tiếp 3. Chạy `Full Release Validation` trên nhánh phát hành, thẻ phát hành hoặc SHA - commit đầy đủ khi bạn muốn CI thông thường cộng với prompt cache trực tiếp, Docker, QA Lab, - Matrix và phạm vi Telegram từ một quy trình thủ công + commit đầy đủ khi bạn muốn CI thông thường cộng với phạm vi bao phủ bộ nhớ đệm prompt live, + Docker, QA Lab, Matrix và Telegram từ một workflow thủ công 4. Nếu bạn cố ý chỉ cần đồ thị kiểm thử thông thường có tính xác định, hãy chạy - quy trình thủ công `CI` trên ref phát hành thay vào đó + workflow `CI` thủ công trên ref phát hành thay vào đó 5. Lưu `preflight_run_id` thành công -6. Chạy `OpenClaw Release Publish` với cùng `tag`, cùng `npm_dist_tag`, - và `preflight_run_id` đã lưu; nó xuất bản các Plugin đã externalize lên npm +6. Chạy `OpenClaw Release Publish` với cùng `tag`, cùng `npm_dist_tag` + và `preflight_run_id` đã lưu; nó phát hành các Plugin đã externalize lên npm và ClawHub trước khi quảng bá gói npm OpenClaw -7. Nếu bản phát hành đã lên `beta`, hãy dùng quy trình riêng tư +7. Nếu bản phát hành đã lên `beta`, dùng workflow riêng tư `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` để quảng bá phiên bản ổn định đó từ `beta` lên `latest` -8. Nếu bản phát hành cố ý được xuất bản trực tiếp lên `latest` và `beta` - nên theo cùng bản dựng ổn định ngay lập tức, hãy dùng cùng quy trình riêng tư đó - để trỏ cả hai dist-tag vào phiên bản ổn định, hoặc để đồng bộ tự phục hồi theo lịch của nó - chuyển `beta` sau +8. Nếu bản phát hành cố ý phát hành trực tiếp lên `latest` và `beta` + cần theo cùng bản build ổn định ngay lập tức, hãy dùng cùng workflow riêng tư đó + để trỏ cả hai dist-tag tới phiên bản ổn định, hoặc để đồng bộ tự khôi phục theo lịch + của workflow đó chuyển `beta` sau -Việc thay đổi dist-tag nằm trong repo riêng tư vì lý do bảo mật, vì nó vẫn -yêu cầu `NPM_TOKEN`, trong khi repo công khai giữ xuất bản chỉ dùng OIDC. +Thao tác thay đổi dist-tag nằm trong repo riêng tư vì lý do bảo mật, vì nó vẫn +yêu cầu `NPM_TOKEN`, trong khi repo công khai giữ phát hành chỉ dùng OIDC. -Điều đó giữ cho cả đường dẫn xuất bản trực tiếp và đường dẫn quảng bá beta-trước -đều được ghi tài liệu và hiển thị với operator. +Điều đó giữ cho cả đường dẫn phát hành trực tiếp và đường dẫn quảng bá beta trước +đều được ghi lại trong tài liệu và hiển thị cho người vận hành. -Nếu maintainer phải quay về xác thực npm cục bộ, chỉ chạy mọi lệnh 1Password -CLI (`op`) bên trong một phiên tmux chuyên dụng. Không gọi `op` -trực tiếp từ shell agent chính; giữ nó bên trong tmux giúp các prompt, -cảnh báo và xử lý OTP có thể quan sát được, đồng thời ngăn các cảnh báo host lặp lại. +Nếu một maintainer phải quay về xác thực npm cục bộ, chỉ chạy mọi lệnh CLI 1Password +(`op`) bên trong một phiên tmux chuyên dụng. Không gọi `op` +trực tiếp từ shell tác tử chính; giữ nó bên trong tmux giúp các prompt, +cảnh báo và xử lý OTP có thể quan sát được và ngăn cảnh báo máy chủ lặp lại. -## Tham chiếu công khai +## Tài liệu tham khảo công khai - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml) diff --git a/docs/vi/reference/full-release-validation.md b/docs/vi/reference/full-release-validation.md index e64ae6623..86ac35c41 100644 --- a/docs/vi/reference/full-release-validation.md +++ b/docs/vi/reference/full-release-validation.md @@ -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`
**Workflow con:** không có
**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.
**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`
**Workflow con:** `CI`
**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.
**Chạy lại:** `rerun_group=ci`. | -| Plugin trước phát hành | **Job:** `Run plugin prerelease validation`
**Workflow con:** `Plugin Prerelease`
**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.
**Chạy lại:** `rerun_group=plugin-prerelease`. | -| Kiểm tra phát hành | **Job:** `Run release/live/Docker/QA validation`
**Workflow con:** `OpenClaw Release Checks`
**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.
**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`
**Workflow con:** không có
**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`.
**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`
**Workflow con:** `NPM Telegram Beta E2E`
**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.
**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`
**Workflow con:** không có
**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.
**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`
**Workflow con:** không có
**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.
**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`
**Workflow con:** `CI`
**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.
**Chạy lại:** `rerun_group=ci`. | +| Tiền phát hành Plugin | **Công việc:** `Run plugin prerelease validation`
**Workflow con:** `Plugin Prerelease`
**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.
**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`
**Workflow con:** `OpenClaw Release Checks`
**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.
**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`
**Workflow con:** không có
**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`.
**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`
**Workflow con:** `NPM Telegram Beta E2E`
**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.
**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`
**Workflow con:** không có
**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.
**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`
**Workflow nền:** không có
**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.
**Chạy lại:** `rerun_group=release-checks`. | -| Artifact package | **Job:** `Prepare release package artifact`
**Workflow nền:** không có
**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.
**Chạy lại:** nhóm package, đa OS, hoặc live/E2E bị ảnh hưởng. | -| Install smoke | **Job:** `Run install smoke`
**Workflow nền:** `Install Smoke`
**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.
**Chạy lại:** `rerun_group=install-smoke`. | -| Đa OS | **Job:** `cross_os_release_checks`
**Workflow nền:** `OpenClaw Cross-OS Release Checks (Reusable)`
**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.
**Chạy lại:** `rerun_group=cross-os`. | -| Repo và live E2E | **Job:** `Run repo/live E2E validation`
**Workflow nền:** `OpenClaw Live And E2E Checks (Reusable)`
**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`.
**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`
**Workflow nền:** `OpenClaw Live And E2E Checks (Reusable)`
**Kiểm thử:** các chunk Docker đường dẫn phát hành trên artifact package dùng chung.
**Chạy lại:** `rerun_group=live-e2e`. | -| Package Acceptance | **Job:** `Run package acceptance`
**Workflow nền:** `Package Acceptance`
**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.
**Chạy lại:** `rerun_group=package`. | -| Tương đương QA | **Job:** `Run QA Lab parity lane` và `Run QA Lab parity report`
**Workflow nền:** job trực tiếp
**Kiểm thử:** các pack tương đương agentic ứng viên và baseline, sau đó là báo cáo tương đương.
**Chạy lại:** `rerun_group=qa-parity` hoặc `rerun_group=qa`. | -| QA live Matrix | **Job:** `Run QA Lab live Matrix lane`
**Workflow nền:** job trực tiếp
**Kiểm thử:** profile QA Matrix live nhanh trong môi trường `qa-live-shared`.
**Chạy lại:** `rerun_group=qa-live` hoặc `rerun_group=qa`. | -| QA live Telegram | **Job:** `Run QA Lab live Telegram lane`
**Workflow nền:** job trực tiếp
**Kiểm thử:** QA Telegram live với các lease thông tin đăng nhập Convex CI.
**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`
**Workflow nền:** không có
**Kiểm thử:** các job release-check bắt buộc cho nhóm chạy lại đã chọn.
**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`
**Quy trình công việc nền:** không có
**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.
**Chạy lại:** `rerun_group=release-checks`. | +| Tạo phẩm gói | **Công việc:** `Prepare release package artifact`
**Quy trình công việc nền:** không có
**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.
**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`
**Quy trình công việc nền:** `Install Smoke`
**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.
**Chạy lại:** `rerun_group=install-smoke`. | +| Đa hệ điều hành | **Công việc:** `cross_os_release_checks`
**Quy trình công việc nền:** `OpenClaw Cross-OS Release Checks (Reusable)`
**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.
**Chạy lại:** `rerun_group=cross-os`. | +| Repo và E2E trực tiếp | **Công việc:** `Run repo/live E2E validation`
**Quy trình công việc nền:** `OpenClaw Live And E2E Checks (Reusable)`
**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`.
**Chạy:** `run_release_soak=true`, `release_profile=full`, hoặc `rerun_group=live-e2e` có trọng tâm.
**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`
**Quy trình công việc nền:** `OpenClaw Live And E2E Checks (Reusable)`
**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.
**Chạy:** `run_release_soak=true`, `release_profile=full`, hoặc `rerun_group=live-e2e` có trọng tâm.
**Chạy lại:** `rerun_group=live-e2e`. | +| Chấp nhận gói | **Công việc:** `Run package acceptance`
**Quy trình công việc nền:** `Package Acceptance`
**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.
**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`
**Quy trình công việc nền:** các công việc trực tiếp
**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.
**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`
**Quy trình công việc nền:** công việc trực tiếp
**Kiểm thử:** hồ sơ QA Matrix trực tiếp nhanh trong môi trường `qa-live-shared`.
**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`
**Quy trình công việc nền:** công việc trực tiếp
**Kiểm thử:** QA Telegram trực tiếp với các lease thông tin xác thực Convex CI.
**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`
**Quy trình công việc nền:** không có
**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.
**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=` 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=` 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` diff --git a/docs/vi/reference/test.md b/docs/vi/reference/test.md index 49871db74..d79e786cd 100644 --- a/docs/vi/reference/test.md +++ b/docs/vi/reference/test.md @@ -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 ` 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 @@ -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. @@ -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. - 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. - 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. - 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. 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. 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`. @@ -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. - 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`. Chỉ một tham chiếu hình ảnh duy nhất. 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. - 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. -## 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) diff --git a/docs/vi/web/dashboard.md b/docs/vi/web/dashboard.md index 7264f4d85..bb8f54b6f 100644 --- a/docs/vi/web/dashboard.md +++ b/docs/vi/web/dashboard.md @@ -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). ## 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