From ffe4df986d5bdd99ccd5edd3ff88a38502f97da9 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 23:42:20 +0000 Subject: [PATCH] chore(i18n): refresh vi translations --- docs/vi/ci.md | 404 ++++++++-------- docs/vi/concepts/system-prompt.md | 265 +++++----- docs/vi/nodes/audio.md | 83 ++-- docs/vi/plugins/codex-harness.md | 779 +++++++++++++++--------------- docs/vi/providers/arcee.md | 81 ++-- docs/vi/reference/RELEASING.md | 574 +++++++++++----------- docs/vi/web/control-ui.md | 286 +++++------ docs/vi/web/webchat.md | 77 +-- 8 files changed, 1274 insertions(+), 1275 deletions(-) diff --git a/docs/vi/ci.md b/docs/vi/ci.md index 59955a27b..0af86116f 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 kiểm tra GitHub Actions bị lỗi - - 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 điều phối ClawSweeper hoặc chuyển tiếp hoạt động GitHub -summary: Đồ thị công việc CI, cổng phạm vi, phạm vi phát hành bao trùm và các lệnh cục bộ tương đương + - Bạn cần hiểu vì sao một tác vụ CI đã chạy hoặc không chạy + - Bạn đang gỡ lỗi một kiểm tra GitHub Actions bị thất bại + - Bạn đang điều phối một lượt chạy hoặc chạy lại xác thực bản phát hành + - Bạn đang thay đổi cơ chế điều phối ClawSweeper hoặc chuyển tiếp hoạt động GitHub +summary: Đồ thị công việc CI, cổng phạm vi, nhóm phát hành bao quát và các lệnh cục bộ tương đương title: Quy trình CI x-i18n: - generated_at: "2026-05-02T22:17:32Z" + generated_at: "2026-05-02T23:39:33Z" model: gpt-5.5 provider: openai - source_hash: a8033b928b26adfa340200ea69fd63d339a6e65c21659b8119a68b23b8b16016 + source_hash: 321fe0a061044f75b8e1d03b4d3e76d4f8dd2dae0ebc58831887fc20af953cf1 source_path: ci.md workflow: 16 --- -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 các release candidate và xác thực 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 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. +OpenClaw CI chạy trên mọi lần đẩy lên `main` và mọi pull request. Tác vụ `preflight` phân loại diff và tắt các luồng tốn kém khi chỉ những 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 các ứng viên phát hành và xác thực rộng. Các luồng Android vẫn là tùy chọn thông qua `include_android`. Phạm vi kiểm thử Plugin chỉ dành cho phát hành nằm trong quy trình [`Plugin Prerelease`](#plugin-prerelease) riêng và chỉ chạy từ [`Full Release Validation`](#full-release-validation) hoặc một lần kích hoạt 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ỉ 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 dựa trên advisory npm | Luôn chạy trên 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 push và PR không phải draft | -| `check-dependencies` | Lượt kiểm tra Knip chỉ dependency production cộng với 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 built-artifact, và artifact hạ nguồn có thể tái sử dụng | Thay đổi liên quan đến Node | -| `checks-fast-core` | Các lane kiểm tra đúng 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 hợp đồng kênh được 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 core, không bao gồm lane kênh, bundled, contract, và extension | Thay đổi liên quan đến Node | -| `check` | Tương đương gate local chính được 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, boundary, drift snapshot prompt, guard bề mặt extension, package-boundary, và các shard gateway-watch | Thay đổi liên quan đến Node | -| `build-smoke` | Kiểm thử smoke built-CLI và smoke bộ nhớ khởi động | Thay đổi liên quan đến Node | -| `checks` | Trình xác minh cho kiểm thử kênh built-artifact | 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 phát hành | -| `check-docs` | Định dạng tài liệu, lint, và kiểm tra 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 Python-skill | -| `checks-windows` | Kiểm thử process/path 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 macOS dùng các artifact đã build 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` | Kiểm thử unit Android cho cả hai flavor cộng với một bản build debug APK | Thay đổi liên quan đến Android | -| `test-performance-agent` | Tối ưu hóa kiểm thử chậm Codex hằng ngày 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 các lane mock-provider, deep-profile, và GPT 5.4 live | Theo lịch và dispatch thủ công | +| Tác vụ | 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 lần đẩy và PR không phải bản nháp | +| `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 các lần đẩy và PR không phải bản nháp | +| `security-dependency-audit` | Kiểm tra lockfile production không cần dependency dựa trên advisories của npm | Luôn chạy trên các lần đẩy và PR không phải bản nháp | +| `security-fast` | Tác vụ tổng hợp bắt buộc cho các tác vụ bảo mật nhanh | Luôn chạy trên các lần đẩy và PR không phải bản nháp | +| `check-dependencies` | Lượt kiểm tra Knip chỉ dành cho dependency production cộng với guard allowlist tệp không dùng | Các 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 | Các thay đổi liên quan đến Node | +| `checks-fast-core` | Các luồng kiểm tra đúng đắn Linux nhanh như kiểm tra bundled/plugin-contract/protocol | Các thay đổi liên quan đến Node | +| `checks-fast-contracts-channels` | Kiểm tra contract của kênh theo shard với kết quả kiểm tra tổng hợp ổn định | Các thay đổi liên quan đến Node | +| `checks-node-core-test` | Các shard kiểm thử Node lõi, không gồm các luồng kênh, bundled, contract, và extension | Các thay đổi liên quan đến Node | +| `check` | Tương đương cổng kiểm tra cục bộ chính theo shard: kiểu production, lint, guard, kiểu kiểm thử, và smoke nghiêm ngặt | Các thay đổi liên quan đến Node | +| `check-additional` | Kiến trúc, ranh giới, drift snapshot prompt, guard bề mặt extension, ranh giới package, và các shard gateway-watch | Các thay đổi liên quan đến Node | +| `build-smoke` | Kiểm thử smoke CLI đã dựng và smoke bộ nhớ khởi động | Các thay đổi liên quan đến Node | +| `checks` | Bộ xác minh cho kiểm thử kênh artifact đã dựng | Các thay đổi liên quan đến Node | +| `checks-node-compat-node22` | Luồng build và smoke tương thích Node 22 | Kích hoạt CI thủ công cho phát hành | +| `check-docs` | Định dạng tài liệu, lint, và kiểm tra liên kết hỏng | Tài liệu thay đổi | +| `skills-python` | Ruff + pytest cho Skills có nền tảng Python | Các thay đổi liên quan đến Python-skill | +| `checks-windows` | Kiểm thử process/path dành riêng cho Windows cộng với hồi quy specifier import runtime dùng chung | Các thay đổi liên quan đến Windows | +| `macos-node` | Luồng kiểm thử TypeScript trên macOS dùng artifact đã dựng dùng chung | Các thay đổi liên quan đến macOS | +| `macos-swift` | Swift lint, build, và kiểm thử cho ứng dụng macOS | Các thay đổi liên quan đến macOS | +| `android` | Kiểm thử unit Android cho cả hai flavor cộng với một bản build APK debug | Các thay đổi liên quan đến Android | +| `test-performance-agent` | Tối ưu kiểm thử chậm hằng ngày bằng Codex sau hoạt động đáng tin cậy | CI chính thành công hoặc kích hoạt 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 luồng mock-provider, deep-profile, và GPT 5.4 live | Theo lịch và kích hoạt thủ công | ## Thứ tự fail-fast -1. `preflight` quyết định lane nào 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 để consumer hạ nguồn 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`. +1. `preflight` quyết định những luồng nào tồn tại. Logic `docs-scope` và `changed-scope` là các bước bên trong tác vụ này, không phải tác vụ độ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 tác vụ artifact và ma trận nền tảng nặng hơn. +3. `build-artifacts` chạy chồng lấp với các luồng Linux nhanh để các bên tiêu thụ downstream có thể bắt đầu ngay khi bản build dùng chung sẵn sàng. +4. Các luồng 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 vào 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 version hóa (`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 diễn ra. +GitHub có thể đánh dấu các tác vụ bị thay thế là `cancelled` khi một lần đẩy mới hơn xuất hiện trê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()` để vẫn báo cáo lỗi shard thông thường nhưng không xếp hàng sau khi toàn bộ workflow đã bị thay thế. Khóa đồng thời CI tự động được tạo 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 diễn ra. ## 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`. Kích hoạt 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 lint workflow, nhưng tự thân chúng không buộc build 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 nền tảng. -- **Chỉnh sửa chỉ định tuyến CI, một số chỉnh sửa fixture core-test rẻ, và chỉnh sửa hẹp helper/test-routing plugin contract** dùng đường dẫn manifest nhanh chỉ Node: `preflight`, bảo mật, và một tác vụ `checks-fast-core` duy nhất. Đường dẫn đó bỏ qua build artifact, tương thích Node 22, contract kênh, 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 thực thi. -- **Kiểm tra Node Windows** được giới hạn ở các wrapper process/path 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ỉ test không liên quan vẫn ở trên các lane Linux Node. +- **Chỉnh sửa workflow CI** xác thực đồ thị Node CI cộng với lint workflow, nhưng tự chúng không buộc build native Windows, Android, hoặc macOS; các luồng nền tảng đó vẫn được giới hạn theo thay đổi mã nguồn nền tảng. +- **Chỉnh sửa chỉ định tuyến CI, chỉnh sửa fixture core-test rẻ được chọn, và chỉnh sửa helper/test-routing hẹp cho contract Plugin** dùng đường dẫn manifest nhanh chỉ dành cho Node: `preflight`, bảo mật, và một tác vụ `checks-fast-core` duy nhất. Đường dẫn đó bỏ qua build artifact, 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 ở 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 vào các 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 luồng đó; các thay đổi mã nguồn, Plugin, install-smoke, và chỉ kiểm thử không liên quan vẫn nằm trên các luồng Linux Node. -Các họ 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ữ quá nhiều runner: contract kênh chạy dưới dạng ba shard có trọng số, các lane unit core nhỏ được ghép cặp, auto-reply chạy dưới dạng bốn worker cân bằng (với cây con reply được tách thành các shard agent-runner, dispatch, và commands/state-routing), và cấu hình Gateway/Plugin agentic được trải trên các job Node agentic chỉ source hiện có thay vì chờ built artifact. Các kiểm thử browser, QA, media, và Plugin linh tinh rộng dùng cấu hình Vitest chuyên dụng của chúng thay vì catch-all Plugin dùng chung. Các shard include-pattern ghi mục timing bằng tên shard CI, để `.artifacts/vitest-shard-timings.json` có thể phân biệt toàn bộ cấu hình 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; shard guard boundary chạy các guard độc lập nhỏ của nó đồng thời trong một job, bao gồm `pnpm prompt:snapshots:check` để drift prompt đường dẫn thành công Codex được ghim vào PR gây ra nó. Gateway watch, kiểm thử kênh, và shard support-boundary core chạy đồng thời trong `build-artifacts` sau khi `dist/` và `dist-runtime/` đã được build. +Các họ kiểm thử Node chậm nhất được tách hoặc cân bằng để mỗi tác vụ vẫn nhỏ mà không đặt trước runner quá mức: contract kênh chạy dưới dạng ba shard có trọng số, các luồng unit lõi nhỏ được ghép cặp, auto-reply chạy dưới dạng bốn worker cân bằng (với cây con reply được tách thành các shard agent-runner, dispatch, và commands/state-routing), và cấu hình gateway/plugin dạng agentic được phân bổ trên các tác vụ Node agentic chỉ theo mã nguồn hiện có thay vì chờ artifact đã dựng. Các kiểm thử trình duyệt rộng, QA, media, và Plugin khác dùng cấu hình Vitest chuyên biệt của chú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, để `.artifacts/vitest-shard-timings.json` có thể phân biệt toàn bộ cấu hình với shard đã lọc. `check-additional` giữ công việc biên dịch/canary package-boundary cùng nhau và tách kiến trúc topology runtime khỏi phạm vi gateway watch; shard guard ranh giới chạy các guard độc lập nhỏ của nó đồng thời bên trong một tác vụ, bao gồm `pnpm prompt:snapshots:check` để drift prompt đường dẫn thành công của runtime Codex được ghim vào PR đã gây ra nó. Gateway watch, kiểm thử kênh, và shard support-boundary lõi chạy đồng thời bên trong `build-artifacts` sau khi `dist/` và `dist-runtime/` đã được dựng. -Android CI chạy cả `testPlayDebugUnitTest` và `testThirdPartyDebugUnitTest` rồi build Play debug APK. Flavor bên thứ ba 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ờ SMS/call-log BuildConfig, đồ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` rồi dựng APK debug Play. Flavor bên thứ ba không có source set hoặc manifest riêng; luồng 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 tác vụ đóng gói APK debug trùng lặp trên mọi lần đẩy liên quan đến Android. -Shard `check-dependencies` chạy `pnpm deadcode:dependencies` (một lượt kiểm tra Knip chỉ dependency production đượ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 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ũ, 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. +Shard `check-dependencies` chạy `pnpm deadcode:dependencies` (một lượt kiểm tra Knip chỉ dành cho dependency production đượ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 bản cài `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 rà soát hoặc để lại mục allowlist cũ, trong khi vẫn giữ các bề mặt Plugin động, generated, build, live-test, và cầu nối package có chủ đí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 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`. +`.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 gửi payload `repository_dispatch` gọn đến `openclaw/clawsweeper`. -Workflow có bốn lane: +Workflow có bốn luồng: -- `clawsweeper_item` cho yêu cầu review chính xác issue và pull request; -- `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 `main`; -- `github_activity` cho hoạt động GitHub chung mà agent ClawSweeper có thể kiểm tra. +- `clawsweeper_item` cho yêu cầu review issue và pull request chính xác; +- `clawsweeper_comment` cho các 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 lần đẩy `main`; +- `github_activity` cho hoạt động GitHub chung mà tác nhân 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, 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ộ body Webhook. Workflow nhận trong `openclaw/clawsweeper` là `.github/workflows/github-activity.yml`, workflow này đăng event đã chuẩn hóa lên hook OpenClaw Gateway cho agent ClawSweeper. +Luồng `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à các đ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ộ thân webhook. Workflow nhận trong `openclaw/clawsweeper` là `.github/workflows/github-activity.yml`, đăng sự kiện đã chuẩn hóa tới hook OpenClaw Gateway cho tác nhân ClawSweeper. -Hoạt động chung là quan sát, không phải mặc định giao hàng. Agent ClawSweeper nhận mục tiêu Discord trong prompt của nó và chỉ nên đăng lên `#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ần mở, chỉnh sửa, bot churn, 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 gửi mặc định. Tác nhân ClawSweeper nhận đích Discord trong prompt và chỉ nên đăng lên `#clawsweeper` khi sự kiện bất ngờ, có thể hành động, rủi ro, hoặc hữu ích về mặt vận hành. Các lần mở, chỉnh sửa, biến động bot, nhiễu webhook trùng lặp, và lưu lượng review thông thường nên trả về `NO_REPLY`. -Xem tiêu đề, bình luận, body, văn bản review, tên branch, và thông điệp commit 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à phân loại, không phải chỉ dẫn cho workflow hoặc runtime agent. +Hãy coi tiêu đề, bình luận, thân nội dung, 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 xuyên suốt đường dẫn 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 tác nhân. -## Dispatch thủ công +## Kích hoạt thủ công -Các lần 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 đượ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 docs, Python skills, Windows, macOS và Control UI i18n. Các lần dispatch 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`. Kiểm tra tĩnh prerelease Plugin, shard chỉ dành cho phát hành `agentic-plugins`, sweep batch 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` dispatch workflow `Plugin Prerelease` riêng với gate release-validation được bật. +Các lần điều phối 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, shard Plugin đó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, Skills Python, Windows, macOS và i18n Control UI. Các lần điều phối CI thủ công độc lập chỉ chạy Android với `include_android=true`; ô bao phủ 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`, đợt quét toàn bộ extension đầy đủ và các lane Docker tiền phát hành Plugin bị loại khỏi CI. Bộ kiểm thử tiền phát hành Docker chỉ chạy khi `Full Release Validation` điều phối workflow `Plugin Prerelease` riêng với cổng xác thực phát hành được bật. -Các lần chạy thủ công dùng một nhóm concurrency duy nhất để bộ đầy đủ của release-candidate không bị hủy bởi một lần push hoặc PR khác trên cùng ref. Input tùy chọn `target_ref` cho phép một caller đáng tin cậy chạy đồ thị đó với một branch, tag hoặc commit SHA đầy đủ trong khi dùng workflow file từ dispatch ref đã chọn. +Các lần chạy thủ công dùng một nhóm đồng thời duy nhất để bộ đầy đủ của release-candidate 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 `target_ref` tùy chọn cho phép một caller đáng tin cậy chạy đồ thị đó trên một nhánh, tag hoặc SHA commit đầy đủ trong khi dùng tệp workflow từ ref điều phối đã chọn. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Runner -| Runner | Job | +| Runner | Công việc | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, các job bảo mật nhanh và job tổng hợp (`security-scm-fast`, `security-dependency-audit`, `security-fast`), kiểm tra nhanh protocol/contract/bundled, kiểm tra hợp đồng kênh theo shard, các shard `check` ngoại trừ lint, các shard và job tổng hợp `check-additional`, trình xác minh tổng hợp test Node, kiểm tra docs, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight cũng dùng GitHub-hosted Ubuntu để ma trận 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 test Linux Node, các shard test Plugin được đóng gói, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (đủ nhạy với CPU nên 8 vCPU tốn kém hơn phần tiết kiệm được); các bản build Docker install-smoke (thời gian xếp hàng 32-vCPU tốn kém hơn phần tiết kiệm được) | +| `ubuntu-24.04` | `preflight`, các công việc 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/đóng gói nhanh, các kiểm tra hợp đồng kênh được chia 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, Skills Python, workflow-sanity, labeler, auto-response; preflight install-smoke cũng dùng Ubuntu do GitHub lưu trữ để ma trận 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 đóng gói, `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 build 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ộ @@ -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. Workflow này 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 điều phối thủ công: ```bash gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 @@ -146,27 +146,27 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 Workflow cài đặt OCM từ một bản phát hành được ghim và Kova từ input `kova_ref` được ghim, rồi chạy ba lane: -- `mock-provider`: các scenario chẩn đoán Kova chạy với runtime local-build bằng auth giả tương thích OpenAI có tính xác định. -- `mock-deep-profile`: profiling CPU/heap/trace cho startup, Gateway và các hotspot agent-turn. -- `live-gpt54`: một lượt agent OpenAI `openai/gpt-5.4` thật, được 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 điểm nóng khi khởi động, Gateway và lượt tác tử. +- `live-gpt54`: Một lượt tác tử OpenAI `openai/gpt-5.4` thật, được bỏ qua khi `OPENAI_API_KEY` không khả dụng. -Lane mock-provider cũng chạy các probe nguồn gốc OpenClaw-native sau lượt Kova: thời gian boot Gateway và bộ nhớ qua 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 khởi động CLI chạy với Gateway đã boot. Bản tóm tắt Markdown của source probe nằm tại `source/index.md` trong report bundle, kèm JSON thô bên cạnh. +Lane mock-provider cũng chạy các probe nguồn native của OpenClaw sau lượt Kova: thời gian khởi động Gateway và bộ nhớ trên các trường hợp khởi động mặc định, hook và 50-Plugin; các vòng hello `channel-chat-baseline` mock-OpenAI lặp lại; và các lệnh khởi động CLI trên Gateway đã boot. 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. -Mỗi lane upload GitHub artifacts. Khi `CLAWGRIT_REPORTS_TOKEN` được cấu hình, workflow cũng commit `report.json`, `report.md`, bundles, `index.md` và artifact source-probe vào `openclaw/clawgrit-reports` dưới `openclaw-performance//-//`. Con trỏ branch hiện tại được ghi thành `openclaw-performance//latest-.json`. +Mỗi lane tải artifact GitHub lên. Khi `CLAWGRIT_REPORTS_TOKEN` được cấu hình, workflow cũng commit `report.json`, `report.md`, bundles, `index.md` và artifact source-probe vào `openclaw/clawgrit-reports` dưới `openclaw-performance//-//`. Con trỏ nhánh 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 umbrella thủ công cho "chạy mọi thứ trước khi phát hành." Workflow này nhận branch, tag hoặc commit SHA đầy đủ, dispatch workflow thủ công `CI` với target đó, dispatch `Plugin Prerelease` để có bằng chứng Plugin/package/static/Docker chỉ dành cho phát hành, và dispatch `OpenClaw Release Checks` cho install smoke, package acceptance, các bộ release-path Docker, live/E2E, OpenWebUI, QA Lab parity, Matrix và các lane Telegram. Với `rerun_group=all` và `release_profile=full`, workflow cũng chạy `NPM Telegram Beta E2E` với artifact `release-package-under-test` từ release checks. Sau khi publish, truyền `npm_telegram_package_spec` để chạy lại cùng lane package Telegram với package npm đã publish. +`Full Release Validation` là workflow ô bao phủ thủ công cho "chạy mọi thứ trước khi phát hành." Nó nhận một nhánh, tag hoặc SHA commit đầy đủ, điều phối workflow `CI` thủ công với target đó, điều phối `Plugin Prerelease` cho bằng chứng Plugin/gói/tĩnh/Docker chỉ dành cho phát hành, và điều phối `OpenClaw Release Checks` cho install smoke, package acceptance, các bộ kiểm thử đường dẫn phát hành Docker, live/E2E, OpenWebUI, QA Lab parity, Matrix và các lane Telegram. Với `rerun_group=all` và `release_profile=full`, nó cũng chạy `NPM Telegram Beta E2E` trên artifact `release-package-under-test` từ release checks. Sau khi phát hành, truyền `npm_telegram_package_spec` để chạy lại cùng lane gói Telegram trên gói npm đã phát hành. -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 profile, artifacts và -các handle rerun tập trung. +Xem [Xác thực phát hành đầy đủ](/vi/reference/full-release-validation) để biết +ma trận 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 tập trung. -`OpenClaw Release Publish` là workflow phát hành thủ công có thay đổi trạng thái. Dispatch workflow này +`OpenClaw Release Publish` là workflow phát hành thủ công có thay đổi trạng thái. Điều phối nó từ `release/YYYY.M.D` hoặc `main` sau khi tag phát hành tồn tại và sau khi -OpenClaw npm preflight đã thành công. Workflow xác minh `pnpm plugins:sync:check`, -dispatch `Plugin NPM Release` cho mọi package Plugin có thể publish, dispatch -`Plugin ClawHub Release` cho cùng release SHA, và chỉ sau đó mới dispatch +preflight npm OpenClaw đã thành công. Nó xác minh `pnpm plugins:sync:check`, +điều phối `Plugin NPM Release` cho tất cả các gói Plugin có thể publish, điều phối +`Plugin ClawHub Release` cho cùng SHA phát hành, và chỉ sau đó điều phối `OpenClaw NPM Release` với `preflight_run_id` đã lưu. ```bash @@ -177,46 +177,46 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Để có bằng chứng commit được ghim trên một branch thay đổi nhanh, dùng helper thay vì +Để có bằng chứng commit được ghim trên một nhánh thay đổi nhanh, hãy dùng helper thay vì `gh workflow run ... --ref main -f ref=`: ```bash pnpm ci:full-release --sha ``` -GitHub workflow dispatch refs 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, -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ần chạy hoàn tất. Trình xác minh umbrella cũng fail nếu bất kỳ workflow con nào chạy ở +Các ref điều phối workflow GitHub phải là nhánh hoặc tag, không phải SHA commit thô. Helper +đẩy một nhánh tạm thời `release-ci/-...` tại SHA target, +điều phối `Full Release Validation` từ ref đã ghim đó, xác minh mọi workflow con +`headSha` khớp với target, và xóa nhánh tạm thời khi lần chạy hoàn tất. Trình xác minh ô bao phủ cũng thất bại nếu bất kỳ workflow con nào đã chạy ở một SHA khác. -`release_profile` kiểm soát độ rộng live/provider được truyền vào release checks. Các workflow phát hành -thủ công mặc định là `stable`; chỉ dùng `full` khi bạn +`release_profile` kiểm soát độ rộng live/provider được truyền vào release checks. 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. -- `minimum` giữ các lane OpenAI/core release-critical nhanh nhất. -- `stable` thêm tập provider/backend ổn định. +- `minimum` giữ các lane OpenAI/core nhanh nhất và trọng yếu cho phát hành. +- `stable` thêm bộ provider/backend ổn định. - `full` chạy ma trận provider/media tư vấn rộng. -Umbrella ghi lại các child run id đã dispatch, và job cuối cùng `Verify full validation` kiểm tra lại conclusion hiện tại của các child run và nối thêm bảng job chậm nhất cho từng child run. Nếu một workflow con được chạy lại và chuyển xanh, chỉ chạy lại job verifier của parent để làm mới kết quả umbrella và bản tóm tắt thời gian. +Ô bao phủ ghi lại các id lần chạy con đã điều phối, và công việc cuối cùng `Verify full validation` kiểm tra lại kết luận hiện tại của các lần chạy con và thêm các bảng công việc 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 công việc xác minh cha để làm mới kết quả ô bao phủ 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 bản ứng viên phát hành, `ci` chỉ cho nhánh con CI đầy đủ thông thường, `plugin-prerelease` chỉ cho nhánh con phát hành trước Plugin, `release-checks` cho mọi nhánh con 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 workflow bao trùm. Cách này giữ phạm vi chạy lại một hộp phát hành bị lỗi được 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 tiến trình con CI đầy đủ thông thường, `plugin-prerelease` chỉ cho tiến trình con phát hành trước của plugin, `release-checks` cho mọi tiến trình con 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 workflow bao trùm. Điều này giữ cho việc chạy lại một hộp phát hành bị lỗi được giới hạn sau một bản sửa tập trung. -`OpenClaw Release Checks` dùng tham chiếu workflow tin cậy để phân giải tham chiếu đã chọn một lần thành tarball `release-package-under-test`, rồi truyền artifact đó cho cả workflow Docker đường dẫn phát hành live/E2E và shard chấp nhận gói. Điều đó giữ các byte của gói nhất quán giữa các hộp phát hành và tránh đóng gói lại cùng một ứng viên trong nhiều job con. +`OpenClaw Release Checks` dùng tham chiếu workflow tin cậy để phân giải tham chiếu đã chọn một lần thành tarball `release-package-under-test`, rồi truyền hiện vật đó cho cả workflow Docker đường dẫn phát hành live/E2E và shard chấp nhận gói. Điều đó giữ cho 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 ứng viên trong nhiều tác vụ con. Các lần chạy `Full Release Validation` trùng lặp cho `ref=main` và `rerun_group=all` -thay thế workflow bao trùm cũ hơn. Bộ giám sát cha hủy mọi workflow con mà nó -đã dispatch khi workflow cha bị hủy, vì vậy quá trình xác thực main mới hơn -không phải chờ sau một lần chạy release-check cũ kéo dài hai giờ. Việc xác thực -nhánh/thẻ phát hành và các nhóm chạy lại tập trung giữ `cancel-in-progress: false`. +thay thế workflow bao trùm cũ hơn. Trình giám sát cha hủy mọi workflow con mà nó +đã dispatch khi tiến trình cha bị hủy, vì vậy xác thực main mới hơn +không phải chờ sau một lần chạy release-check cũ 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 -Nhánh con live/E2E phát hành giữ phạm vi bao phủ rộng của `pnpm test:live` native, nhưng chạy nó dưới dạng các shard có tên thông qua `scripts/test-live-shard.mjs` thay vì một job tuần tự: +Tiến trình con live/E2E của phát hành giữ phạm vi bao phủ rộng của `pnpm test:live` native, nhưng chạy nó dưới dạng các shard có tên thông qua `scripts/test-live-shard.mjs` thay vì một tác vụ nối tiếp: - `native-live-src-agents` - `native-live-src-gateway-core` -- các job `native-live-src-gateway-profiles` được lọc theo nhà cung cấp +- các tác vụ `native-live-src-gateway-profiles` được lọc theo provider - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -224,35 +224,35 @@ Nhánh con live/E2E phát hành giữ phạm vi bao phủ rộng của `pnpm tes - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- các shard âm thanh/video media được tách riêng và các shard nhạc được lọc theo nhà cung cấp +- các shard media audio/video được tách riêng và các shard music được lọc theo provider -Cách này giữ cùng phạm vi bao phủ tệp trong khi giúp dễ chạy lại và chẩn đoán các lỗi nhà cung cấp live chậm. 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 bao phủ tệp trong khi giúp 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ượt. -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 các binary trước khi thiết lập. Giữ các bộ kiểm thử live dựa trên Docker trên các runner Blacksmith thông thường — container job không phải nơi phù hợp để khởi chạy các 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 tác vụ media chỉ xác minh các 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 — tác vụ container là nơi không phù hợp để khởi chạy các kiểm thử Docker lồng nhau. -Các shard mô hình/backend live dựa trên Docker dùng một image chia sẻ riêng `ghcr.io/openclaw/openclaw-live-test:` cho mỗi commit đã chọn. Workflow phát hành live build và push image đó một lần, rồi các shard mô hình Docker live, Gateway được chia shard theo nhà cung cấp, backend CLI, liên kết ACP, và harness Codex 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 của job workflow để một container bị kẹt hoặc đường dẫn dọn dẹp bị lỗ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 toàn bộ target Docker nguồn một cách độc lập, lần chạy phát hành đã bị cấu hình sai và sẽ lãng phí thời gian thực tế cho các bả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 model live Docker, Gateway được chia shard theo provider, backend CLI, bind ACP, và harness Codex chạy với `OPENCLAW_SKIP_DOCKER_BUILD=1`. Các shard Docker Gateway mang giới hạn `timeout` rõ ràng ở cấp script thấp hơn timeout của tác vụ workflow để một container bị kẹt hoặc đường dẫn dọn dẹp lỗ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 target Docker nguồn đầy đủ một cách độc lập, lần chạy phát hành đang bị cấu hình sai và sẽ lãng phí thời gian chạy thực tế vào các bản build image trùng lặp. ## Chấp nhận gói -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, còn chấp nhận gói xác thực một tarball duy nhất thông qua cùng harness Docker E2E mà người dùng thực thi sau khi cài đặt hoặc cập nhật. +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 thông qua cùng harness Docker E2E mà người dùng chạy sau khi cài đặt hoặc cập nhật. -### Job +### Tác vụ -1. `resolve_package` checkout `workflow_ref`, phân giải một ứng viên gói, 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, tham chiếu workflow, tham chiếu gói, phiên bản, SHA-256, và hồ sơ trong phần 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 danh mục tarball, chuẩn bị các image Docker theo digest gói khi cần, và chạy các lane Docker đã chọn trên gói đó thay vì đóng gói checkout workflow. Khi một hồ sơ chọn nhiều `docker_lanes` được nhắm mục tiêu, workflow tái sử dụng chuẩn bị gói và các image chia sẻ một lần, rồi fan out các lane đó thành các job Docker được nhắm mục tiêu song song với artifact riêng biệ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 chấp nhận gói đã phân giải một gói; dispatch Telegram độc lập vẫn có thể cài đặt một đặc tả npm đã phát hành. -4. `summary` làm workflow thất bại nếu quá trình 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 gói, 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 hiện vật `package-under-test`, và in nguồn, tham chiếu workflow, tham chiếu gói, 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 hiện vật đó xuống, xác thực inventory tarball, chuẩn bị image Docker theo digest gói khi cần, và chạy các lane Docker đã chọn trên gói đó thay vì đóng gói checkout workflow. Khi một profile chọn nhiều `docker_lanes` được nhắm mục tiêu, workflow tái sử dụng chuẩn bị gói và các image dùng chung một lần, rồi fan out các lane đó thành các tác vụ Docker được nhắm mục tiêu chạy song song với hiện vật 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 hiện vật `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 đã phát hành. +4. `summary` làm workflow thất bại nếu phân giải gói, chấp nhận Docker, hoặc lane Telegram tùy chọn thất bại. ### Nguồn ứng viên -- `source=npm` chỉ chấp nhận `openclaw@alpha`, `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 nguồn này cho chấp nhận bản phát hành trước/ổn định đã phát hành. -- `source=ref` đóng gói một nhánh, thẻ, hoặc SHA commit đầy đủ `package_ref` tin cậy. Bộ phân giải fetch các nhánh/thẻ OpenClaw, xác minh commit đã chọn có thể truy cập từ lịch sử nhánh repository hoặc một thẻ phát hành, cài đặt dependency trong một worktree tách rời, và đóng gói 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 các artifact được chia sẻ bên ngoài. +- `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 chấp nhận bản phát hành trước/ổn định đã phát hành. +- `source=ref` đóng gói một nhánh, tag, hoặc SHA commit đầy đủ `package_ref` tin cậy. Trình phân giải fetch các nhánh/tag OpenClaw, xác minh commit đã chọn có thể truy cập từ lịch sử nhánh kho lưu trữ hoặc một tag phát hành, cài đặt dependency trong một worktree tách rời, và đóng gói bằng `scripts/package-openclaw-for-docker.mjs`. +- `source=url` tải xuống một `.tgz` HTTPS; `package_sha256` là bắt buộc. +- `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 hiện vật được chia sẻ bên ngoài. -Giữ `workflow_ref` và `package_ref` riêng 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ũ. +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ũ. -### Hồ sơ bộ kiểm thử +### 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` @@ -260,25 +260,25 @@ Giữ `workflow_ref` và `package_ref` riêng biệt. `workflow_ref` là mã wor - `full` — các phần Docker đường dẫn phát hành đầy đủ với OpenWebUI - `custom` — `docker_lanes` chính xác; bắt buộc khi `suite_profile=custom` -Hồ sơ `package` dùng phạm vi bao phủ Plugin offline để việc xác thực gói đã phát hành không bị chặn bởi 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`, với đường dẫn đặc tả npm đã phát hành được giữ cho các dispatch độc lập. +Profile `package` dùng phạm vi bao phủ plugin offline để xác thực gói đã 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 hiện vật `package-under-test` trong `NPM Telegram Beta E2E`, với đường dẫn spec npm đã phát hành được giữ cho các dispatch độc lập. -Để xem chính sách chuyên dụng cho cập nhật và kiểm thử Plugin, bao gồm các lệnh cục bộ, -lane Docker, đầu vào chấp nhận gói, 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). +Để xem chính sách kiểm thử dành riêng cho cập nhật và plugin, bao gồm các lệnh cục bộ, +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 chấp nhận gói 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 di chuyển 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 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 đó trên một gói npm đã giao thay vì artifact được build từ SHA. Cross-OS release checks vẫn bao phủ onboarding, trình cài đặt, và hành vi nền tảng dành riêng cho OS; xác thực sản phẩm gói/cập nhật nên bắt đầu bằng chấp nhận gói. Lane Docker `published-upgrade-survivor` xác thực một baseline gói đã phát hành cho mỗi lần chạy. Trong chấp nhận gói, 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 bị lỗ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 để lấy mẫu rộng hơn thủ công 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 các fixture có dạng issue cho cấu hình Feishu, các tệp bootstrap/persona được giữ lại, cài đặt Plugin OpenClaw đã cấu hình, đường dẫn log dấu ngã, và các gốc dependency Plugin kế thừa 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 toàn diện, không phải độ rộng Full Release CI thông thường. Các lần chạy tổng hợp cục bộ có thể truyền đặc tả 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 đã phát hành cấu hình baseline bằng một công thức lệnh `openclaw config set` được nhúng sẵn, ghi lại các bước công thức trong `summary.json`, và thăm dò `/healthz`, `/readyz`, cùng trạng thái RPC sau khi Gateway khởi động. Các lane mới của gói Windows và trình cài đặt cũng xác minh rằng một gói đã cài đặt có thể import một override browser-control 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`, để bằng chứng cài đặt và Gateway vẫn ở trên một mô hình 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`, hiện vật 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 di chuyển 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 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ì hiện vật được build theo SHA. Cross-OS release checks vẫn bao phủ onboarding, trình cài đặt, và hành vi nền tảng 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 gói đã phát hành cho mỗi lần chạy. 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 đó. Đặ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 khả dụng cho việc lấy mẫu thủ công rộng hơn với mốc ngày cũ hơn. Đặt `published_upgrade_survivor_scenarios=reported-issues` để mở rộng cùng các baseline đó trên các fixture theo dạng issue cho cấu hình Feishu, các tệp bootstrap/persona được giữ lại, cài đặt plugin OpenClaw đã cấu hình, đường dẫn log dấu ngã, và các gốc 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 đã phát hành toàn diện, không phải phạm vi CI Full Release 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 đã phát hành cấu hình baseline bằng công thức lệnh `openclaw config set` được nhúng sẵn, ghi lại các bước công thức trong `summary.json`, và dò `/healthz`, `/readyz`, cộng với trạng thái RPC sau khi Gateway khởi động. Các lane mới của gói Windows và trình cài đặt cũng xác minh rằng một gói đã cài đặt có thể import một override browser-control 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 dùng 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 kế thừa +### Cửa sổ tương thích legacy -Chấp nhận gói có các cửa sổ tương thích kế thừa có giới hạn cho các gói đã phát hành. Các gói đến `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 gói đã phát hành. Các gói đến `2026.4.25`, bao gồm `2026.4.25-beta.*`, có thể dùng đường dẫn tương thích: -- các mục QA riêng tư đã biết trong `dist/postinstall-inventory.json` có thể trỏ đến các tệp bị lược khỏi tarball; -- `doctor-switch` có thể bỏ qua tiểu trường hợp lưu giữ `gateway install --wrapper` khi gói không phơi bày flag đó; -- `update-channel-switch` có thể cắt bớt `pnpm.patchedDependencies` bị thiếu khỏi fixture git giả lập xuất phát từ tarball và có thể ghi log `update.channel` đã lưu giữ bị thiếu; -- các smoke Plugin có thể đọc các vị trí bản ghi cài đặt kế thừa hoặc chấp nhận việc thiếu lưu giữ bản ghi cài đặt marketplace; -- `plugin-update` có thể cho phép di chuyển metadata cấu hình trong khi vẫn yêu cầu bản ghi cài đặt và hành vi không cài đặt lại giữ nguyên. +- các mục QA riêng đã biết trong `dist/postinstall-inventory.json` có thể trỏ đến các tệp 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ể loại bỏ `pnpm.patchedDependencies` bị thiếu khỏi fixture git giả được dẫn xuất từ tarball và có thể ghi log `update.channel` được duy trì bị thiếu; +- các smoke plugin có thể đọc vị trí install-record legacy hoặc chấp nhận thiếu duy trì install-record marketplace; +- `plugin-update` có thể cho phép di chuyển 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. -Gói `2026.4.26` đã phát hành cũng có thể cảnh báo về các tệp dấu metadata build cục bộ đã được giao. Các gói sau đó phải đáp ứng 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. +Gói `2026.4.26` đã phát hành cũng có thể cảnh báo về các tệp dấu 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 các điều kiện sẽ thất bại thay vì cảnh báo hoặc bỏ qua. ### Ví dụ @@ -321,151 +321,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 thất bạ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 gian từng pha và các lệnh chạy lại. Ưu tiên chạy lại hồ sơ gói thất bại hoặc đúng 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 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` và 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 profile gói bị lỗi hoặc các lane Docker chính xác thay vì chạy lại toàn bộ xác thực phát hành. ## Smoke cài đặt -Quy trình làm việc `Install Smoke` riêng biệt tái sử dụng cùng script phạm vi thông qua job `preflight` của nó. Nó 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` riêng của nó. Nó chia phạm vi smoke thành `run_fast_install_smoke` và `run_full_install_smoke`. -- **Đường nhanh** chạy cho pull request chạm tới bề mặt Docker/gói, thay đổi gói/manifest Plugin đi kèm, hoặc các bề mặt Plugin SDK/plugin/channel/gateway lõi mà các job Docker smoke kiểm thử. Các thay đổi Plugin đi kèm chỉ ở mã nguồn, chỉnh sửa chỉ ở kiểm thử và chỉnh sửa chỉ ở tài liệu không giữ trước Docker worker. Đường nhanh xây dựng image Dockerfile gốc một lần, kiểm tra CLI, chạy smoke CLI xóa agents shared-workspace, chạy e2e gateway-network trong container, xác minh một build arg extension đi kèm và chạy hồ sơ Docker Plugin đi kèm có giới hạn dưới timeout lệnh tổng hợp 240 giây (mỗi lần chạy Docker của 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 của 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à 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 image 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/cập nhật và E2E Docker Plugin đi kèm nhanh dưới dạng các job riêng để công việc trình cài đặt không phải chờ sau các smoke image gốc. +- **Đường nhanh** chạy cho các pull request chạm đến 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õi kênh/Gateway/Plugin SDK mà các job Docker smoke thực thi. Các thay đổi Plugin được đóng gói kèm chỉ ở mã nguồn, chỉnh sửa chỉ liên quan đến kiểm thử và chỉnh sửa chỉ liên quan đến tài liệu không giữ trước worker Docker. Đường nhanh xây dựng image Dockerfile gốc một lần, kiểm tra CLI, chạy smoke CLI xóa agent trong workspace dùng chung, chạy e2e Gateway-network trong container, xác minh một đối số build cho extension được đóng gói kèm, và chạy profile Docker Plugin được đóng gói kèm 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 đầy đủ** giữ phạm vi cài đặt gói QR và Docker/update của trình 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à các pull request thực sự chạm đến 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 image smoke Dockerfile gốc GHCR theo SHA mục tiêu, sau đó chạy cài đặt gói QR, smoke Dockerfile gốc/Gateway, smoke trình cài đặt/cập nhật, và Docker E2E Plugin được đóng gói kèm đường nhanh dưới dạng các job riêng để công việc trình cài đặt không phải chờ sau các smoke image gốc. -Các lần push lên `main` (bao gồm merge commit) không ép chạy đường đầy đủ; khi logic phạm vi thay đổi yêu cầu phạm vi đầy đủ trên một lần push, quy trình làm việc giữ Docker smoke nhanh và để smoke cài đặt đầy đủ cho nightly hoặc xác thực phát hành. +Các lần push lên `main` (bao gồm cả merge commit) không bắt buộc chạy đườ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ữ Docker smoke đường nhanh và để smoke cài đặt đầy đủ cho hằng đêm hoặc xác thực phát hành. -Smoke image-provider cài đặt toàn cục Bun chậm được chặn riêng bởi `run_bun_global_install_smoke`. Nó chạy theo lịch hằng đêm và từ quy trình làm việc kiểm tra phát hành, và các đ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. +Smoke nhà cung cấp image cài đặt toàn cục Bun chậm được kiểm soát riêng bởi `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 dispatch `Install Smoke` thủ công có thể chọn tham gia, nhưng các 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. -## E2E Docker cục bộ +## Docker E2E cục bộ -`pnpm test:docker:all` dựng trước một image 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 image `scripts/e2e/Dockerfile` dùng chung: +`pnpm test:docker:all` dựng sẵn một image 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 image `scripts/e2e/Dockerfile` dùng chung: - một runner Node/Git tối giản cho các lane trình cài đặt/cập nhật/phụ thuộc Plugin; - một image 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 image cho 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 image theo từng lane bằng `OPENCLAW_DOCKER_E2E_BARE_IMAGE` và `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, sau đó chạy các lane với `OPENCLAW_SKIP_DOCKER_BUILD=1`. -### Thông số có thể điều chỉnh +### Tham số tinh chỉnh | Biến | Mặc định | Mục đích | | -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- | | `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Số slot pool chính cho các lane thông thường. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Số slot pool đuôi nhạy cảm với provider. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Giới hạn lane live đồng thời để provider không throttle. | -| `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 | Độ lệch giữa các lần bắt đầu lane để tránh bão tạo Docker daemon; đặt `0` để không lệch. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout dự phòng cho từng lane (120 phút); các lane live/tail được chọn 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 để agents có thể tái hiện một lane thất bại. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Số slot pool đuôi nhạy cảm với nhà cung cấp. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Giới hạn lane live đồng thời để nhà cung cấp không bị throttle. | +| `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 khởi động lane để tránh bão tạo Docker daemon; đặt `0` để không giãn cách. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Thời gian chờ dự phòng theo 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` | chưa đặt | `1` in kế hoạch của bộ lập lịch mà không chạy lane. | +| `OPENCLAW_DOCKER_ALL_LANES` | chưa đặt | 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 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. Tổng hợp cục bộ preflight Docker, xóa các container E2E OpenClaw 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 pool mới sau lỗi đầu tiên. +Một lane nặng hơn giới hạn hiệu dụng 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. Tổng hợp cục bộ chạy preflight 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 lâu 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. -### Quy trình làm việc live/E2E có thể tái sử dụng +### Workflow live/E2E có thể tái sử dụng -Quy trình làm việc live/E2E có thể tái sử dụng hỏi `scripts/test-docker-all.mjs --plan-json` để biết phạm vi gói, loại image, image live, lane và thông tin xác thực cần thiết. Sau đó `scripts/docker-e2e.mjs` chuyển kế hoạch đó thành output và tóm tắt GitHub. Nó hoặc đó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; xây dựng và push các image E2E Docker GHCR bare/functional được gắn tag bằng digest gói thông qua cache 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 input `docker_e2e_bare_image`/`docker_e2e_functional_image` được cung cấp hoặc các image digest gói hiện có thay vì xây dựng lại. Các lần pull image Docker được thử lại với timeout 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 có thể tái sử dụng hỏi `scripts/test-docker-all.mjs --plan-json` để biết phạm vi gói, loại image, image live, lane và thông tin xác thực nào là bắt buộc. `scripts/docker-e2e.mjs` sau đó chuyển kế hoạch đó thành output và tóm tắt GitHub. Nó hoặc đó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 image Docker E2E bare/functional GHCR được gắn thẻ 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 input `docker_e2e_bare_image`/`docker_e2e_functional_image` được cung cấp hoặc các image theo digest gói hiện có thay vì xây dựng lại. Các lần pull image Docker được thử lại với thời gian chờ 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 thụ phần lớn đường tới hạn của CI. -### Các phần của đường phát hành +### Chunk đường phát hành -Phạm vi Docker phát hành chạy các job được chia nhỏ hơn với `OPENCLAW_SKIP_DOCKER_BUILD=1` để mỗi phần chỉ pull loại image nó cần 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 được chia chunk nhỏ hơn với `OPENCLAW_SKIP_DOCKER_BUILD=1` để mỗi chunk chỉ pull loại image 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 phầ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 alias Plugin/runtime tổng hợp. Alias lane `install-e2e` vẫn là alias 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à alias tổng hợp 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 trình cài đặt nhà cung cấp. -OpenWebUI được gộp vào `plugins-runtime-services` khi phạm vi release-path đầy đủ yêu cầu, và chỉ giữ một phầ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 đi kèm thử lại một lần khi có lỗi mạng npm tạm thời. +OpenWebUI được gộp vào `plugins-runtime-services` khi phạm vi release-path đầy đủ yêu cầu nó, 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 được đóng gói kèm thử lại một lần đối với lỗi mạng npm tạm thời. -Mỗi phần tải lên `.artifacts/docker-tests/` cùng nhật ký lane, thời gian, `summary.json`, `failures.json`, thời gian từng pha, JSON kế hoạch 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 quy trình làm việc chạy các lane được chọn trên các image đã chuẩn bị thay vì các job phần, nhờ đó việc gỡ lỗi lane thất bại được giới hạn trong một job Docker nhắm 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 được chọn là lane Docker live, job nhắm mục tiêu xây dựng image live-test cục bộ cho lần chạy lại đó. Các lệnh chạy lại GitHub được tạo theo từng lane bao gồm `package_artifact_run_id`, `package_artifact_name` và input image đã 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 đúng gói và image 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 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 được chọn trên các image đã chuẩn bị thay vì các job chunk, giúp việc gỡ lỗi lane thất bại được giới hạn trong một job Docker nhắm 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 được chọn là lane Docker live, job nhắm mục tiêu sẽ xây dựng image live-test cục bộ cho lần chạy lại đó. Các lệnh chạy lại GitHub được tạo theo từng lane bao gồm `package_artifact_run_id`, `package_artifact_name`, và input image đã 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à image từ lần chạy thất bạ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 ``` -Quy trình làm việc live/E2E theo lịch chạy toàn bộ bộ 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 -`Plugin Prerelease` là phạm vi sản phẩm/gói tốn kém hơn, vì vậy đây là một quy trình làm việc riêng được điều phối bởi `Full Release Validation` hoặc bởi một operator rõ ràng. Pull request thông thường, các lần push lên `main` và các điều phối CI thủ công độc lập giữ bộ này tắt. Nó cân bằng kiểm thử Plugin đ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 batch Plugin nặng import không tạo thêm job CI. Đường tiền phát hành Docker chỉ dành cho phát hành gom các lane Docker nhắm mục tiêu thành các nhóm nhỏ để tránh giữ hàng chục runner cho các job 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 operator rõ ràng. Các pull request thông thường, các lần push lên `main`, và các dispatch CI thủ công độc lập giữ suite đó ở trạng thái tắt. 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 về import không tạo thêm job CI. Đường tiền phát hành Docker chỉ dành cho phát hành gom nhóm các lane Docker nhắm mục tiêu thành các nhóm nhỏ để tránh giữ hàng chục runner cho những job kéo dài một đến ba phút. ## QA Lab -QA Lab có các lane CI chuyên dụng bên ngoài quy trình làm việc có phạm vi thông minh chính. Parity agentic được lồng dưới các harness QA và phát hành rộng, không phải một quy trình làm việc 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 bên ngoài workflow chính có phạm vi thông minh. Tính tương đồng agentic được lồng dưới các bộ chạy 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 tính tương đồng cần đi cùng một lần chạy xác thực rộng. -- Quy trình làm việc `QA-Lab - All Lanes` chạy hằng đêm trên `main` và khi điều phối thủ công; nó fan out 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. +- Workflow `QA-Lab - All Lanes` chạy hằng đêm trên `main` và khi dispatch thủ công; nó fan out lane tương đồng 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. -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 tách khỏi độ trễ model live và khởi động Plugin provider thông thường. Gateway vận chuyển live tắt tìm kiếm bộ nhớ vì QA parity bao phủ hành vi bộ nhớ riêng; kết nối provider được bao phủ bởi các bộ model live, provider native và provider Docker riêng. +Các kiểm tra phát hành chạy các lane vận chuyển Matrix và Telegram live với nhà cung cấp 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à quá trình khởi động Plugin nhà cung cấp thông thường. Gateway vận chuyển live tắt tìm kiếm bộ nhớ vì QA parity bao phủ hành vi bộ nhớ riêng; kết nối nhà cung cấp được bao phủ bởi các bộ live model, nhà cung cấp native và nhà cung cấp Docker riêng. -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 quy trình làm việc thủ công vẫn là `all`; điều phối thủ công `matrix_profile=all` luôn 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 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`; dispatch thủ công `matrix_profile=all` luôn 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 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 pack candidate và baseline dưới dạng các job lane song song, rồi tải cả hai tạo tác vào một job báo cáo nhỏ cho lần so sánh parity cuối cùng. +`OpenClaw Release Checks` cũng chạy các lane QA Lab quan trọng cho phát hành trước khi phê duyệt phát hành; cổng QA parity của nó chạy các pack candidate và baseline dưới dạng các job lane song song, sau đó tải cả hai artifact xuống một job báo cáo nhỏ cho so sánh tương đồng cuối cùng. -Với PR thông thường, hãy theo bằng chứng CI/check 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 theo bằng chứng CI/kiểm tra có phạm vi thay vì xem parity là một trạng thái bắt buộc. ## CodeQL -Quy trình `CodeQL` được chủ ý thiết kế như một trình quét bảo mật bước đầu có phạm vi hẹp, không phải lượt quét toàn bộ kho lưu trữ. Các lượt chạy hằng ngày, thủ công và bảo vệ yêu cầu kéo không phải bản nháp sẽ quét mã workflow 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 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 thiết kế có chủ ý như một trình quét bảo mật bước đầu có phạm vi hẹp, không phải đợt quét toàn bộ kho lưu trữ. Các lượt chạy hằng ngày, thủ công và bảo vệ yêu cầu kéo không phải bản nháp sẽ quét mã quy trình làm việc 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 có độ tin cậy cao, được lọc theo `security-severity` cao/nghiêm trọng. -Bộ bảo vệ yêu cầu kéo 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 đã lên lịch. Android và macOS CodeQL không nằm trong mặc định PR. +Cơ chế bảo vệ yêu cầu kéo vẫn nhẹ: nó chỉ khởi động cho 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ư quy trình làm việc theo lịch. Android và macOS CodeQL không nằm trong mặc định cho yêu cầu kéo. ### Danh mục bảo mật | Danh mục | Bề mặt | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Auth, secrets, 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 runtime Plugin kênh, gateway, Plugin SDK, secrets, các điểm chạm audit | -| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, phân tích IP, network guard, web-fetch và các bề mặt chính sách SSRF của Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | Máy chủ MCP, helper thực thi tiến trình, phân phối ra ngoài và các 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, loader, manifest, registry, cài đặt package-manager, tải nguồn và hợp đồng gói Plugin SDK | +| `/codeql-security-high/core-auth-secrets` | Auth, secrets, 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, secrets, các điểm chạm kiểm toán | +| `/codeql-security-high/network-ssrf-boundary` | Các bề mặt SSRF lõi, phân tích IP, bảo vệ mạng, web-fetch, và chính sách SSRF của Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | Máy chủ MCP, helper thực thi tiến trình, phân phối đi ra, và cổng thực thi công cụ của tác nhân | +| `/codeql-security-high/plugin-trust-boundary` | Các bề mặt tin cậy của cài đặt Plugin, loader, manifest, registry, cài đặt package-manager, nạp nguồn, và hợp đồng gói Plugin SDK | -### Shard bảo mật theo nền tảng +### Phân đoạn bảo mật theo nền tảng -- `CodeQL Android Critical Security` — shard 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` — shard 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 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 runtime ngay cả khi sạch. +- `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 dependency 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ếm phần lớn thời gian chạy ngay cả khi sạch. ### Danh mục chất lượng nghiêm trọng -`CodeQL Critical Quality` là shard phi bảo mật tương ứng. Nó chỉ chạy các truy vấn chất lượng JavaScript/TypeScript phi bảo mật ở mức độ nghiêm trọng lỗi 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ệ yêu cầu kéo của nó cố ý nhỏ hơn hồ sơ đã lên lịch: PR không phải bản nháp chỉ chạy các shard tương ứng `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` cho mã thực thi lệnh/mô hình/công cụ của agent và gửi trả lời, mã schema/migration/IO cấu hình, mã auth/secrets/sandbox/security, runtime kênh lõi và Plugin kênh đi kèm, giao thức Gateway/server-method, runtime bộ nhớ/keo SDK, MCP/process/phân phối ra ngoài, runtime provider/danh mục mô hình, chẩn đoán phiên/hàng đợi phân phối, loader Plugin, hợp đồng Plugin SDK/gói, hoặc các thay đổi runtime trả lời Plugin SDK. Các thay đổi cấu hình CodeQL và workflow chất lượng sẽ chạy cả mười hai shard chất lượng PR. +`CodeQL Critical Quality` là phân đoạn tương ứng không thuộc bảo mật. Nó chỉ chạy các truy vấn chất lượng JavaScript/TypeScript không thuộc bảo mật, mức lỗi, trên các bề mặt hẹp có giá trị cao trên runner Blacksmith Linux nhỏ hơn. Cơ chế bảo vệ yêu cầu kéo của nó cố ý nhỏ hơn profile theo lịch: các yêu cầu kéo không phải bản nháp chỉ chạy các phân đoạn tương ứng `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` cho các thay đổi trong mã thực thi lệnh/mô hình/công cụ của tác nhân và phân phối phản hồi, schema config/migration/IO, auth/secrets/sandbox/security, runtime kênh lõi và Plugin kênh đi kèm, protocol/server-method của Gateway, runtime bộ nhớ/SDK glue, MCP/process/phân phối đi ra, runtime provider/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 phản hồi Plugin SDK. Các thay đổi config CodeQL và quy trình làm việc chất lượng sẽ chạy cả mười hai phân đoạn chất lượng cho yêu cầu kéo. -Gử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à hook hướng dẫn/lặp để chạy riêng một shard chất lượng. +Các profile hẹp là các hook giảng dạy/lặp lại để chạy riêng một phân đoạn chất lượng. | Danh mục | Bề mặt | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | Mã ranh giới bảo mật auth, secrets, 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/core-auth-secrets` | Mã ranh giới bảo mật auth, secrets, sandbox, Cron, và Gateway | +| `/codeql-critical-quality/config-boundary` | Schema config, migration, chuẩn hóa, và hợp đồng IO | +| `/codeql-critical-quality/gateway-runtime-boundary` | Schema protocol 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 đi kèm | -| `/codeql-critical-quality/agent-runtime-boundary` | Thực thi lệnh, điều phối mô hình/provider, đ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ụ, helper giám sát tiến trình, và hợp đồng phân phối ra ngoài | -| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK, facade runtime bộ nhớ, alias 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, helper binding/phân phối phiên ra ngoài, 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 đến Plugin SDK, helper payload/chunking/runtime trả lời, tùy chọn trả lời kênh, hàng đợi phân phối và helper binding phiên/luồng | -| `/codeql-critical-quality/provider-runtime-boundary` | Chuẩn hóa danh mục mô hình, auth và khám phá provider, đăng ký runtime provider, mặc định/danh mục provider, và registry web/search/fetch/embedding | -| `/codeql-critical-quality/ui-control-plane` | Bootstrap giao diện điều khiển, 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` | Web fetch/search lõi, IO phương tiện, hiểu phương tiện, tạo ảnh và hợp đồng runtime tạo phương tiện | -| `/codeql-critical-quality/plugin-boundary` | Loader, registry, bề mặt công khai và hợp đồng đ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à helper hợp đồng gói plugin | +| `/codeql-critical-quality/agent-runtime-boundary` | Thực thi lệnh, dispatch mô hình/provider, dispatch 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ụ, helper giám sát tiến trình, và hợp đồng phân phối đi ra | +| `/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 phản hồi, hàng đợi phân phối phiên, helper liên kết/phân phối phiên đi ra, 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` | Dispatch phản hồi đến của Plugin SDK, helper payload/chunking/runtime phản hồi, tùy chọn phản hồi kênh, hàng đợi phân phối, và helper liên kết phiên/luồng | +| `/codeql-critical-quality/provider-runtime-boundary` | Chuẩn hóa danh mục mô hình, auth và discovery của provider, đăng ký runtime provider, mặc định/danh mục provider, 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 ảnh, và tạo media | +| `/codeql-critical-quality/plugin-boundary` | Loader, registry, bề mặt công khai, và hợp đồng entrypoint Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Nguồn Plugin SDK phía gói đã phát hành và helper 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 đi kèm 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 shard sau khi các hồ sơ hẹp có runtime 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, tắt, 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 đi kèm 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 phân đoạn sau khi các profile hẹp có thời gian chạy và tín hiệu ổn định. -## Workflow bảo trì +## Quy trình làm việc bảo trì ### Docs Agent -Workflow `Docs Agent` là một lane bảo trì Codex theo sự kiện để giữ tài liệu hiện có đồng bộ với các thay đổi mới được land. 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à gửi thủ công có thể chạy trực tiếp. Các lượt 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ờ vừa qua. Khi chạy, nó rà soát phạm vi commit từ SHA nguồn Docs Agent không bị bỏ qua trước đó đến `main` hiện tại, vì vậy một lượt chạy hằng giờ có thể bao phủ toàn bộ thay đổi main tích lũy kể từ lượt xử lý tài liệu trước. +Quy trình làm việc `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 hợp nhất. 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ời gọi workflow-run sẽ 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ờ vừa qua. 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, vì vậy một lượt chạy hằng giờ có thể bao phủ tất cả thay đổi trên main được tích lũy từ lần kiểm tra tài liệu trước. ### Test Performance Agent -Workflow `Test Performance Agent` là một lane bảo trì Codex theo sự kiện cho các bài kiểm thử 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ượt gọi workflow-run khác đã chạy hoặc đang chạy trong ngày UTC đó. Gửi thủ công bỏ qua cổng hoạt động hằng ngày đó. Lane này tạo 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 hiệu năng kiểm thử nhỏ vẫn giữ nguyên độ bao phủ thay vì refactor 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ử baseline đang pass. Nếu baseline có bài kiểm thử failing, Codex chỉ có thể sửa các lỗi rõ ràng và báo cáo toàn bộ bộ kiểm thử sau agent phải pass trước khi bất cứ thứ gì được commit. Khi `main` tiến lên trước khi bot push được land, lane 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 lưu trữ để action Codex có thể giữ cùng tư thế an toàn drop-sudo như docs agent. +Quy trình làm việc `Test Performance Agent` là một làn bảo trì Codex theo sự kiện cho các kiểm thử 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ó sẽ bỏ qua nếu một lời 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 xây dựng một 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 bản sửa hiệu năng kiểm thử nhỏ vẫn giữ nguyên độ bao phủ thay vì refactor 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 kiểm thử vượt qua ở baseline. Nếu baseline có kiểm thử thất bại, Codex chỉ được sửa các lỗi rõ ràng 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 đưa lên, làn này rebase bản vá đã được xác thực, chạy lại `pnpm check:changed`, và thử push lại; các bản vá cũ có xung đột sẽ bị bỏ qua. Nó dùng Ubuntu do GitHub-hosted để hành động Codex có thể giữ cùng tư thế an toàn drop-sudo như docs agent. -### PR trùng lặp sau khi merge +### Yêu cầu kéo trùng lặp sau khi hợp nhất -Workflow `Duplicate PRs After Merge` là workflow thủ công cho maintainer để dọn dẹp bản trùng lặp sau land. Nó 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ó issue được tham chiếu chung hoặc các hunk thay đổi chồng lấn. +Quy trình làm việc `Duplicate PRs After Merge` là một quy trình làm việc thủ công cho maintainer để dọn dẹp trùng lặp sau khi hợp nhất. Mặc định là dry-run và chỉ đóng các yêu cầu kéo được liệt kê rõ ràng khi `apply=true`. Trước khi thay đổi GitHub, nó xác minh rằng yêu cầu kéo đã landed đã được hợp nhất và mỗi bản trùng lặp có hoặc một issue được tham chiếu chung hoặc các hunk thay đổi chồng lấn. ```bash gh workflow run duplicate-after-merge.yml \ @@ -479,24 +479,24 @@ gh workflow run duplicate-after-merge.yml \ 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: - các thay đổi production lõi chạy typecheck core prod và core test cộng với lint/guard lõi; -- các thay đổi chỉ kiểm thử lõi chỉ chạy typecheck core test cộng với lint lõi; +- các thay đổi chỉ dành cho kiểm thử lõi chỉ chạy typecheck core test cộng với lint lõi; - các thay đổi production extension chạy typecheck extension prod và extension test cộng với lint extension; -- các thay đổi chỉ kiểm thử extension chạy typecheck extension test cộng với 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ử tường minh); -- các lần 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 gốc có mục tiêu; -- các thay đổi root/config không xác định fail safe sang tất cả lane kiểm tra. +- các thay đổi chỉ dành cho kiểm thử extension chạy typecheck extension test cộng với lint extension; +- các thay đổi Plugin SDK công khai hoặc hợp đồng Plugin mở rộng sang typecheck extension vì các extension phụ thuộc vào các hợp đồng lõi đó (các đợ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/config/root-dependency có mục tiêu; +- các thay đổi root/config không xác định sẽ fail safe sang tất cả các làn kiểm tra. -Định tuyến changed-test cục bộ nằm trong `scripts/test-projects.test-support.mjs` và cố ý rẻ hơn `check:changed`: sửa trực tiếp bài kiểm thử thì chạy chính nó, sửa nguồn ưu tiên ánh xạ tường minh, sau đó là bài kiểm thử cùng cấp và phần phụ thuộc theo import-graph. Cấu hình phân phối group-room dùng chung là một trong các ánh xạ tường minh: thay đổi cấu hình trả lời hiển thị với 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 bài kiểm thử trả lời lõi cộng với hồi quy phân phối Discord và Slack để một 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 đến mức tập được ánh xạ rẻ không phải proxy đáng tin cậy. +Định tuyến changed-test cục bộ nằm trong `scripts/test-projects.test-support.mjs` và cố ý rẻ hơn `check:changed`: các chỉnh sửa kiểm thử trực tiếp chạy chính chúng, chỉnh sửa nguồn ưu tiên ánh xạ rõ ràng, sau đó là kiểm thử sibling và các phần phụ thuộc trong import-graph. Config phân phối group-room dùng chung là một trong các ánh xạ rõ ràng: các thay đổi đối với config visible-reply của nhóm, chế độ phân phối phản hồi nguồn, hoặc prompt hệ thống message-tool sẽ đi qua các kiểm thử phản hồi lõi cộng với 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 yêu cầu kéo đầu tiên. Chỉ dùng `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` khi thay đổi đủ rộng trên toàn harness đến mức tập ánh xạ rẻ không phải là proxy đáng tin cậy. ## Xác thực Testbox -Chạy Testbox từ thư mục gốc của repo và ưu tiên một box mới đã được làm nóng sẵn cho bằng chứng phạm vi rộng. Trước khi dùng một gate 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ầ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 repo và ưu tiên một máy mới đã được khởi động sẵn cho xác minh diện rộng. Trước khi dành một cổng kiểm tra chậm cho một máy đã đượ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 thường, hãy chạy `pnpm testbox:sanity` bên trong máy đó trước. -Kiểm tra sanity 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 đã 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à làm nóng 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 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 máy đó và khởi động sẵn một máy 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, hãy đặt `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` cho lần chạy sanity đó. -`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. +`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 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à đường dẫn remote-box thứ hai do repo sở hữu cho bằng chứng Linux khi Blacksmith không khả dụng hoặc khi ưu tiên dùng dung lượng cloud được sở hữu. Làm nóng một box, hydrate nó thông qua workflow của dự án, rồi chạy lệnh qua Crabbox CLI: +Crabbox là đường dẫn máy từ xa thứ hai do repo sở hữu để xác minh Linux khi Blacksmith không khả dụng hoặc khi nên ưu tiên năng lực đám mây do dự án sở hữu. Khởi động sẵn một máy, hydrate máy đó thông qua quy trình công việc của dự án, rồi chạy lệnh qua Crabbox CLI: ```bash pnpm crabbox:warmup -- --idle-timeout 90m @@ -505,7 +505,7 @@ pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed pnpm crabbox:stop -- ``` -`.crabbox.yaml` sở hữu các mặc định về provider, đồng bộ, và hydrate GitHub Actions. Nó loại trừ `.git` cục bộ để checkout Actions đã hydrate giữ metadata Git từ xa riêng của nó thay vì đồng bộ các remote và object store cục bộ của maintainer, đồng thời loại trừ các artifact runtime/build cục bộ không bao giờ nên được chuyển. `.github/workflows/crabbox-hydrate.yml` sở hữu checkout, thiết lập Node/pnpm, fetch `origin/main`, và phần chuyển giao môi trường không bí mật mà các lệnh `crabbox run --id ` về sau sẽ source. +`.crabbox.yaml` sở hữu các mặc định về provider, đồng bộ và hydrate GitHub Actions. Tệp này loại trừ `.git` cục bộ để bản checkout Actions đã hydrate giữ siêu dữ liệu Git từ xa riêng của nó thay vì đồng bộ các remote và kho đối tượng cục bộ của maintainer, đồng thời loại trừ các artifact runtime/build cục bộ không bao giờ nên được chuyển. `.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 bí mật mà các lệnh `crabbox run --id ` sau này sẽ source. ## Liên quan diff --git a/docs/vi/concepts/system-prompt.md b/docs/vi/concepts/system-prompt.md index b03e4ac90..2d105914d 100644 --- a/docs/vi/concepts/system-prompt.md +++ b/docs/vi/concepts/system-prompt.md @@ -1,85 +1,85 @@ --- read_when: - - Chỉnh sửa văn bản lời nhắc hệ thống, danh sách công cụ hoặc các phần thời gian/Heartbeat + - Chỉnh sửa văn bản prompt hệ thống, danh sách công cụ, hoặc các phần thời gian/Heartbeat - Thay đổi hành vi khởi tạo không gian làm việc hoặc chèn Skills -summary: Prompt hệ thống OpenClaw chứa những gì và được lắp ráp như thế nào +summary: Nội dung lời nhắc hệ thống của OpenClaw gồm những gì và được tập hợp như thế nào title: Lời nhắc hệ thống x-i18n: - generated_at: "2026-05-02T22:17:57Z" + generated_at: "2026-05-02T23:39:17Z" model: gpt-5.5 provider: openai - source_hash: 3b8761a8722bb328b937e0832774be7b4e99602ae032c9a255f26843237c110c + source_hash: f8e0234453812c16cf5d273096d335049bf435ca76ade36200caf4bb344624e5 source_path: concepts/system-prompt.md workflow: 16 --- -OpenClaw xây dựng một prompt hệ thống tùy chỉnh cho mỗi lần chạy tác nhân. Prompt này do **OpenClaw sở hữu** và không sử dụng prompt mặc định của pi-coding-agent. +OpenClaw xây dựng một lời nhắc hệ thống tùy chỉnh cho mỗi lần chạy agent. Lời nhắc này do **OpenClaw sở hữu** và không dùng lời nhắc mặc định của pi-coding-agent. -Prompt được OpenClaw lắp ráp và chèn vào từng lần chạy tác nhân. +Lời nhắc được OpenClaw lắp ráp và chèn vào từng lần chạy agent. -Các Plugin nhà cung cấp có thể đóng góp hướng dẫn prompt có nhận biết bộ nhớ đệm mà không thay thế -toàn bộ prompt do OpenClaw sở hữu. Runtime của nhà cung cấp có thể: +Plugin nhà cung cấp có thể đóng góp hướng dẫn lời nhắc có nhận biết bộ nhớ đệm mà không thay thế +toàn bộ lời nhắc do OpenClaw sở hữu. Runtime nhà cung cấp có thể: - thay thế một tập nhỏ các phần lõi có tên (`interaction_style`, `tool_call_style`, `execution_bias`) -- chèn một **tiền tố ổn định** phía trên ranh giới bộ nhớ đệm prompt -- chèn một **hậu tố động** phía dưới ranh giới bộ nhớ đệm prompt +- chèn một **tiền tố ổn định** phía trên ranh giới bộ nhớ đệm lời nhắc +- chèn một **hậu tố động** phía dưới ranh giới bộ nhớ đệm lời nhắc -Sử dụng các đóng góp do nhà cung cấp sở hữu để tinh chỉnh riêng cho từng họ mô hình. Giữ cơ chế đột biến prompt -`before_prompt_build` cũ để tương thích hoặc cho các thay đổi prompt thật sự mang tính toàn cục, +Dùng các đóng góp do nhà cung cấp sở hữu để tinh chỉnh theo từng họ mô hình. Giữ lại việc biến đổi lời nhắc +`before_prompt_build` cũ cho mục đích tương thích hoặc các thay đổi lời nhắc thật sự toàn cục, không phải hành vi nhà cung cấp thông thường. -Lớp phủ họ OpenAI GPT-5 giữ quy tắc thực thi lõi gọn nhẹ và bổ sung -hướng dẫn riêng theo mô hình cho việc khóa persona, đầu ra ngắn gọn, kỷ luật dùng công cụ, -tra cứu song song, độ bao phủ sản phẩm bàn giao, xác minh, thiếu ngữ cảnh, và +Lớp phủ họ OpenAI GPT-5 giữ quy tắc thực thi lõi nhỏ gọn và thêm +hướng dẫn theo mô hình cho việc bám giữ persona, đầu ra súc tích, kỷ luật dùng công cụ, +tra cứu song song, độ bao phủ sản phẩm bàn giao, xác minh, thiếu ngữ cảnh và vệ sinh công cụ terminal. ## Cấu trúc -Prompt được cố ý giữ gọn và dùng các phần cố định: +Lời nhắc được chủ ý giữ gọn và dùng các phần cố định: -- **Công cụ**: lời nhắc về nguồn sự thật cho structured-tool cùng hướng dẫn sử dụng công cụ runtime. -- **Thiên hướng thực thi**: hướng dẫn theo sát gọn nhẹ: hành động ngay trong lượt với - các yêu cầu có thể thực hiện, tiếp tục cho đến khi xong hoặc bị chặn, phục hồi sau kết quả công cụ - yếu, kiểm tra trực tiếp trạng thái có thể thay đổi, và xác minh trước khi hoàn tất. -- **An toàn**: lời nhắc rào chắn ngắn để tránh hành vi tìm kiếm quyền lực hoặc vượt qua giám sát. -- **Skills** (khi có): cho mô hình biết cách tải hướng dẫn Skills theo nhu cầu. +- **Công cụ**: nhắc nhở nguồn chân lý của công cụ có cấu trúc cùng hướng dẫn dùng công cụ trong runtime. +- **Thiên hướng thực thi**: hướng dẫn theo đến cùng ngắn gọn: hành động ngay trong lượt với + các yêu cầu có thể thực hiện, tiếp tục cho đến khi xong hoặc bị chặn, phục hồi từ kết quả công cụ yếu, + kiểm tra trực tiếp trạng thái có thể thay đổi, và xác minh trước khi kết thúc. +- **An toàn**: nhắc nhở rào chắn ngắn để tránh hành vi tìm kiếm quyền lực hoặc vượt qua giám sát. +- **Skills** (khi có): cho mô hình biết cách tải hướng dẫn skill theo yêu cầu. - **Tự cập nhật OpenClaw**: cách kiểm tra cấu hình an toàn bằng `config.schema.lookup`, vá cấu hình bằng `config.patch`, thay thế toàn bộ - cấu hình bằng `config.apply`, và chỉ chạy `update.run` khi có yêu cầu rõ ràng từ người dùng. - Công cụ `gateway` chỉ dành cho chủ sở hữu cũng từ chối ghi lại - `tools.exec.ask` / `tools.exec.security`, bao gồm các bí danh cũ `tools.bash.*` + cấu hình bằng `config.apply`, và chỉ chạy `update.run` khi người dùng yêu cầu + rõ ràng. Công cụ chỉ dành cho chủ sở hữu `gateway` cũng từ chối viết lại + `tools.exec.ask` / `tools.exec.security`, bao gồm các alias cũ `tools.bash.*` được chuẩn hóa về các đường dẫn exec được bảo vệ đó. -- **Không gian làm việc**: thư mục làm việc (`agents.defaults.workspace`). -- **Tài liệu**: đường dẫn cục bộ đến tài liệu OpenClaw (repo hoặc gói npm) và khi nào nên đọc. -- **Tệp không gian làm việc (được chèn)**: cho biết các tệp bootstrap được đưa vào bên dưới. -- **Sandbox** (khi bật): cho biết runtime sandbox, đường dẫn sandbox, và liệu có exec nâng quyền hay không. -- **Ngày & giờ hiện tại**: thời gian theo cục bộ người dùng, múi giờ, và định dạng thời gian. +- **Workspace**: thư mục làm việc (`agents.defaults.workspace`). +- **Tài liệu**: đường dẫn cục bộ đến tài liệu OpenClaw (repo hoặc gói npm) và thời điểm cần đọc. +- **Tệp Workspace (được chèn)**: cho biết các tệp bootstrap được bao gồm bên dưới. +- **Sandbox** (khi bật): cho biết runtime sandbox, đường dẫn sandbox và việc có sẵn exec nâng quyền hay không. +- **Ngày & Giờ hiện tại**: thời gian cục bộ của người dùng, múi giờ và định dạng thời gian. - **Thẻ trả lời**: cú pháp thẻ trả lời tùy chọn cho các nhà cung cấp được hỗ trợ. -- **Heartbeats**: prompt Heartbeat và hành vi xác nhận, khi Heartbeat được bật cho tác nhân mặc định. -- **Runtime**: máy chủ, OS, node, mô hình, gốc repo (khi phát hiện), mức suy nghĩ (một dòng). +- **Heartbeat**: lời nhắc heartbeat và hành vi ack, khi heartbeat được bật cho agent mặc định. +- **Runtime**: host, OS, node, mô hình, gốc repo (khi phát hiện), mức suy nghĩ (một dòng). - **Suy luận**: mức hiển thị hiện tại + gợi ý bật/tắt /reasoning. -OpenClaw giữ nội dung ổn định lớn, bao gồm **Ngữ cảnh dự án**, phía trên -ranh giới bộ nhớ đệm prompt nội bộ. Các phần kênh/phiên dễ thay đổi như +OpenClaw giữ nội dung lớn và ổn định, bao gồm **Ngữ cảnh dự án**, phía trên +ranh giới bộ nhớ đệm lời nhắc nội bộ. Các phần kênh/phiên biến động như hướng dẫn nhúng Control UI, **Nhắn tin**, **Giọng nói**, **Ngữ cảnh trò chuyện nhóm**, -**Phản ứng**, **Heartbeats**, và **Runtime** được nối thêm phía dưới ranh giới đó -để các backend cục bộ có bộ nhớ đệm tiền tố có thể tái sử dụng tiền tố không gian làm việc ổn định -qua các lượt kênh. Tương tự, mô tả công cụ nên tránh nhúng tên kênh hiện tại +**Phản ứng**, **Heartbeat**, và **Runtime** được thêm phía dưới ranh giới đó +để các backend cục bộ có bộ nhớ đệm tiền tố có thể tái sử dụng tiền tố workspace ổn định +qua các lượt kênh. Mô tả công cụ cũng nên tránh nhúng tên kênh hiện tại khi schema được chấp nhận đã mang chi tiết runtime đó. Phần Công cụ cũng bao gồm hướng dẫn runtime cho công việc chạy lâu: -- dùng cron cho theo dõi trong tương lai (`check back later`, lời nhắc, công việc định kỳ) - thay vì vòng lặp sleep bằng `exec`, mẹo trì hoãn `yieldMs`, hoặc thăm dò `process` +- dùng cron cho theo dõi trong tương lai (`check back later`, nhắc nhở, công việc lặp lại) + thay vì vòng lặp ngủ `exec`, thủ thuật trì hoãn `yieldMs`, hoặc thăm dò `process` lặp lại - dùng `exec` / `process` chỉ cho các lệnh bắt đầu ngay và tiếp tục chạy - nền -- khi đánh thức hoàn tất tự động được bật, khởi động lệnh một lần và dựa vào + ở nền +- khi bật đánh thức hoàn tất tự động, khởi chạy lệnh một lần và dựa vào đường dẫn đánh thức dựa trên push khi nó phát ra đầu ra hoặc thất bại -- dùng `process` cho log, trạng thái, đầu vào, hoặc can thiệp khi bạn cần +- dùng `process` cho log, trạng thái, nhập liệu hoặc can thiệp khi bạn cần kiểm tra một lệnh đang chạy -- nếu tác vụ lớn hơn, ưu tiên `sessions_spawn`; hoàn tất của tác nhân phụ là +- nếu tác vụ lớn hơn, ưu tiên `sessions_spawn`; việc hoàn tất sub-agent là dựa trên push và tự động thông báo lại cho người yêu cầu - không thăm dò `subagents list` / `sessions_list` trong vòng lặp chỉ để chờ hoàn tất @@ -88,67 +88,67 @@ Khi công cụ thử nghiệm `update_plan` được bật, Công cụ cũng yê mô hình chỉ dùng nó cho công việc nhiều bước không tầm thường, giữ đúng một bước `in_progress`, và tránh lặp lại toàn bộ kế hoạch sau mỗi lần cập nhật. -Các rào chắn an toàn trong prompt hệ thống mang tính khuyến nghị. Chúng định hướng hành vi mô hình nhưng không thực thi chính sách. Dùng chính sách công cụ, phê duyệt exec, sandboxing, và danh sách cho phép theo kênh để thực thi cứng; theo thiết kế, người vận hành có thể tắt các cơ chế này. +Các rào chắn an toàn trong lời nhắc hệ thống có tính khuyến nghị. Chúng định hướng hành vi mô hình nhưng không thực thi chính sách. Dùng chính sách công cụ, phê duyệt exec, sandboxing và danh sách cho phép kênh để thực thi cứng; operator có thể vô hiệu hóa các mục này theo thiết kế. -Trên các kênh có thẻ/nút phê duyệt gốc, prompt runtime hiện yêu cầu -tác nhân ưu tiên dựa vào UI phê duyệt gốc đó. Nó chỉ nên bao gồm lệnh -`/approve` thủ công khi kết quả công cụ nói rằng phê duyệt qua chat không khả dụng hoặc -phê duyệt thủ công là con đường duy nhất. +Trên các kênh có thẻ/nút phê duyệt gốc, lời nhắc runtime hiện yêu cầu +agent ưu tiên dựa vào UI phê duyệt gốc đó. Agent 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. -## Chế độ prompt +## Chế độ lời nhắc -OpenClaw có thể render prompt hệ thống nhỏ hơn cho tác nhân phụ. Runtime đặt -`promptMode` cho mỗi lần chạy (không phải cấu hình hướng tới người dùng): +OpenClaw có thể kết xuất lời nhắc hệ thống nhỏ hơn cho sub-agent. Runtime đặt một +`promptMode` cho mỗi lần chạy (không phải cấu hình hiển thị cho người dùng): - `full` (mặc định): bao gồm tất cả các phần ở trên. -- `minimal`: dùng cho tác nhân phụ; bỏ qua **Skills**, **Truy hồi bộ nhớ**, **Tự cập nhật OpenClaw**, - **Bí danh mô hình**, **Danh tính người dùng**, **Thẻ trả lời**, - **Nhắn tin**, **Trả lời im lặng**, và **Heartbeats**. Công cụ, **An toàn**, - Không gian làm việc, Sandbox, Ngày & giờ hiện tại (khi biết), Runtime, và ngữ cảnh - được chèn vẫn có sẵn. +- `minimal`: dùng cho sub-agent; bỏ qua **Skills**, **Truy hồi bộ nhớ**, **Tự cập nhật OpenClaw**, + **Alias mô hình**, **Danh tính người dùng**, **Thẻ trả lời**, + **Nhắn tin**, **Trả lời im lặng**, và **Heartbeat**. Công cụ, **An toàn**, + Workspace, Sandbox, Ngày & Giờ hiện tại (khi biết), Runtime, và ngữ cảnh + được chèn vẫn khả dụng. - `none`: chỉ trả về dòng danh tính cơ sở. -Khi `promptMode=minimal`, các prompt được chèn thêm được gắn nhãn **Ngữ cảnh tác nhân phụ** +Khi `promptMode=minimal`, các lời nhắc được chèn thêm được gắn nhãn **Ngữ cảnh Subagent** thay vì **Ngữ cảnh trò chuyện nhóm**. Đối với các lần chạy tự động trả lời theo kênh, OpenClaw có thể bỏ qua phần **Trả lời im lặng** chung khi ngữ cảnh chat trực tiếp/nhóm đã bao gồm hành vi `NO_REPLY` -riêng theo cuộc trò chuyện đã được giải quyết. Điều này tránh lặp lại cơ chế token -trong cả prompt hệ thống toàn cục và ngữ cảnh kênh. +được phân giải theo cuộc trò chuyện cụ thể. Điều này tránh lặp lại cơ chế token +trong cả lời nhắc hệ thống toàn cục và ngữ cảnh kênh. -## Ảnh chụp prompt +## Ảnh chụp lời nhắc -OpenClaw giữ các ảnh chụp prompt happy-path đã commit cho runtime Codex/message-tool -trong `test/fixtures/agents/prompt-snapshots/happy-path/`. Chúng render -các tham số luồng/lượt app-server được chọn cùng một ngăn xếp lớp prompt gắn với mô hình -được tái dựng cho các lượt Telegram trực tiếp, nhóm Discord, và Heartbeat. Ngăn xếp đó -bao gồm một fixture prompt mô hình Codex `gpt-5.5` được ghim, tạo từ hình dạng catalog/bộ nhớ đệm -mô hình của Codex, văn bản developer về quyền happy-path của Codex, -hướng dẫn developer OpenClaw, đầu vào lượt người dùng, và tham chiếu tới các +OpenClaw giữ các ảnh chụp lời nhắc đã commit cho đường dẫn thành công của runtime Codex dưới +`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Chúng kết xuất +các tham số thread/turn app-server được chọn cùng một ngăn xếp lớp lời nhắc gắn với mô hình +được tái dựng cho các lượt Telegram trực tiếp, nhóm Discord và heartbeat. Ngăn xếp đó +bao gồm một fixture lời nhắc mô hình Codex `gpt-5.5` được ghim, tạo từ hình dạng +catalog/bộ nhớ đệm mô hình của Codex, văn bản developer quyền đường dẫn thành công của Codex, +hướng dẫn developer OpenClaw, đầu vào lượt người dùng, và tham chiếu đến các đặc tả công cụ động. -Làm mới fixture prompt mô hình Codex đã ghim bằng +Làm mới fixture lời nhắc mô hình Codex được ghim bằng `pnpm prompt:snapshots:sync-codex-model`. Theo mặc định, script tìm -bộ nhớ đệm runtime của Codex tại `$CODEX_HOME/models_cache.json`, rồi -`~/.codex/models_cache.json`, và chỉ sau đó mới fallback sang quy ước checkout Codex +bộ nhớ đệm runtime của Codex tại `$CODEX_HOME/models_cache.json`, sau đó +`~/.codex/models_cache.json`, và chỉ sau đó mới fallback về quy ước checkout Codex của maintainer tại `~/code/codex/codex-rs/models-manager/models.json`. Nếu -không có nguồn nào trong số đó tồn tại, lệnh thoát mà không thay đổi fixture -đã commit. Truyền `--catalog ` để làm mới từ một tệp `models_cache.json` +không có nguồn nào tồn tại, lệnh thoát mà không thay đổi fixture đã commit. +Truyền `--catalog ` để làm mới từ một tệp `models_cache.json` hoặc `models.json` cụ thể. -Các ảnh chụp này vẫn không phải bản ghi yêu cầu OpenAI thô từng byte một. Codex -có thể thêm ngữ cảnh không gian làm việc do runtime sở hữu như `AGENTS.md`, ngữ cảnh -môi trường, ký ức, hướng dẫn app/Plugin, và hướng dẫn chế độ cộng tác trong tương lai -bên trong runtime Codex sau khi OpenClaw gửi tham số luồng và lượt. +Các ảnh chụp này vẫn không phải bản chụp yêu cầu OpenAI thô khớp từng byte. Codex +có thể thêm ngữ cảnh workspace do runtime sở hữu như `AGENTS.md`, ngữ cảnh +môi trường, bộ nhớ, hướng dẫn app/plugin và các hướng dẫn chế độ cộng tác +trong tương lai bên trong runtime Codex sau khi OpenClaw gửi tham số thread và turn. -Tạo lại chúng bằng `pnpm prompt:snapshots:gen` và xác minh drift bằng +Tái tạo chúng bằng `pnpm prompt:snapshots:gen` và xác minh drift bằng `pnpm prompt:snapshots:check`. CI chạy kiểm tra drift trong shard ranh giới -bổ sung để các thay đổi prompt và cập nhật ảnh chụp luôn gắn với cùng một +bổ sung để các thay đổi lời nhắc và cập nhật ảnh chụp luôn gắn với cùng một PR. -## Chèn bootstrap không gian làm việc +## Chèn bootstrap Workspace -Các tệp bootstrap được cắt gọn và nối thêm dưới **Ngữ cảnh dự án** để mô hình thấy ngữ cảnh danh tính và hồ sơ mà không cần đọc rõ ràng: +Các tệp bootstrap được cắt gọn và thêm dưới **Ngữ cảnh dự án** để mô hình thấy ngữ cảnh danh tính và hồ sơ mà không cần đọc rõ ràng: - `AGENTS.md` - `SOUL.md` @@ -156,71 +156,78 @@ Các tệp bootstrap được cắt gọn và nối thêm dưới **Ngữ cảnh - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (chỉ trên không gian làm việc hoàn toàn mới) +- `BOOTSTRAP.md` (chỉ trên workspace hoàn toàn mới) - `MEMORY.md` khi có -Tất cả các tệp này được **chèn vào cửa sổ ngữ cảnh** ở mọi lượt trừ khi -có cổng riêng theo tệp được áp dụng. `HEARTBEAT.md` bị bỏ qua trong các lần chạy thông thường khi -Heartbeat bị tắt cho tác nhân mặc định hoặc +Tất cả các tệp này được **chèn vào cửa sổ ngữ cảnh** ở mỗi lượt trừ khi +áp dụng cổng riêng cho tệp. `HEARTBEAT.md` được bỏ qua trong các lần chạy bình thường khi +heartbeat bị tắt cho agent mặc định hoặc `agents.defaults.heartbeat.includeSystemPromptSection` là false. Giữ các tệp được chèn -ngắn gọn — đặc biệt là `MEMORY.md`, tệp có thể tăng dần theo thời gian và dẫn đến -mức sử dụng ngữ cảnh cao ngoài dự kiến và Compaction thường xuyên hơn. +ngắn gọn — đặc biệt là `MEMORY.md`, vì tệp này có thể lớn dần theo thời gian và dẫn đến +mức dùng ngữ cảnh cao ngoài dự kiến cùng việc compaction thường xuyên hơn. + +Khi một phiên chạy trên harness Codex gốc, Codex tải `AGENTS.md` +thông qua cơ chế khám phá tài liệu dự án riêng của nó. OpenClaw vẫn phân giải các tệp +bootstrap còn lại và chuyển tiếp chúng dưới dạng hướng dẫn cấu hình Codex, vì vậy `SOUL.md`, +`TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, và +`MEMORY.md` vẫn giữ cùng vai trò ngữ cảnh workspace mà không nhân đôi +`AGENTS.md`. -Các tệp hằng ngày `memory/*.md` **không** thuộc Ngữ cảnh dự án bootstrap thông thường. Trong các lượt bình thường, chúng được truy cập theo nhu cầu qua các công cụ `memory_search` và `memory_get`, nên chúng không tính vào cửa sổ ngữ cảnh trừ khi mô hình đọc chúng một cách rõ ràng. Các lượt `/new` và `/reset` trần là ngoại lệ: runtime có thể thêm trước ký ức hằng ngày gần đây dưới dạng một khối ngữ cảnh khởi động dùng một lần cho lượt đầu tiên đó. +Các tệp hằng ngày `memory/*.md` **không** phải là một phần của Ngữ cảnh dự án bootstrap thông thường. Trong các lượt thông thường, chúng được truy cập theo yêu cầu qua các công cụ `memory_search` và `memory_get`, vì vậy chúng không tính vào cửa sổ ngữ cảnh trừ khi mô hình đọc chúng rõ ràng. Các lượt `/new` và `/reset` trần là ngoại lệ: runtime có thể thêm trước bộ nhớ hằng ngày gần đây dưới dạng một khối ngữ cảnh khởi động một lần cho lượt đầu tiên đó. -Các tệp lớn bị cắt với một marker. Kích thước tối đa cho mỗi tệp được kiểm soát bởi -`agents.defaults.bootstrapMaxChars` (mặc định: 12000). Tổng nội dung bootstrap được chèn -trên các tệp bị giới hạn bởi `agents.defaults.bootstrapTotalMaxChars` -(mặc định: 60000). Các tệp thiếu sẽ chèn một marker ngắn báo thiếu tệp. Khi xảy ra cắt ngắn, -OpenClaw có thể chèn một khối cảnh báo trong Ngữ cảnh dự án; kiểm soát việc này bằng +Các tệp lớn bị cắt ngắn kèm một marker. Kích thước tối đa theo từng tệp được kiểm soát bởi +`agents.defaults.bootstrapMaxChars` (mặc định: 12000). Tổng nội dung bootstrap +được chèn trên tất cả tệp bị giới hạn bởi `agents.defaults.bootstrapTotalMaxChars` +(mặc định: 60000). Tệp bị thiếu sẽ chèn một marker thiếu tệp ngắn. Khi xảy ra cắt ngắn, +OpenClaw có thể chèn một khối cảnh báo trong Ngữ cảnh dự án; kiểm soát điều này bằng `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; mặc định: `once`). -Các phiên tác nhân phụ chỉ chèn `AGENTS.md` và `TOOLS.md` (các tệp bootstrap khác -được lọc ra để giữ ngữ cảnh tác nhân phụ nhỏ). +Các phiên sub-agent chỉ chèn `AGENTS.md` và `TOOLS.md` (các tệp bootstrap khác +được lọc ra để giữ ngữ cảnh sub-agent nhỏ). -Các hook nội bộ có thể chặn bước này qua `agent:bootstrap` để đột biến hoặc thay thế -các tệp bootstrap được chèn (ví dụ hoán đổi `SOUL.md` bằng một persona thay thế). +Hook nội bộ có thể chặn bước này qua `agent:bootstrap` để biến đổi hoặc thay thế +các tệp bootstrap được chèn (ví dụ thay `SOUL.md` bằng một persona thay thế). -Nếu bạn muốn làm cho tác nhân nghe ít chung chung hơn, hãy bắt đầu với -[Hướng dẫn tính cách SOUL.md](/vi/concepts/soul). +Nếu bạn muốn làm cho agent nghe ít chung chung hơn, hãy bắt đầu với +[Hướng dẫn persona SOUL.md](/vi/concepts/soul). -Để kiểm tra mỗi tệp được chèn đóng góp bao nhiêu (thô so với đã chèn, cắt ngắn, cộng với chi phí schema công cụ), dùng `/context list` hoặc `/context detail`. Xem [Ngữ cảnh](/vi/concepts/context). +Để kiểm tra mỗi tệp được chèn đóng góp bao nhiêu (thô so với được chèn, cắt ngắn, cộng thêm overhead schema công cụ), dùng `/context list` hoặc `/context detail`. Xem [Ngữ cảnh](/vi/concepts/context). ## Xử lý thời gian -Prompt hệ thống bao gồm một phần **Ngày & giờ hiện tại** chuyên biệt khi -biết múi giờ của người dùng. Để giữ prompt ổn định với bộ nhớ đệm, hiện nó chỉ bao gồm +Lời nhắc hệ thống bao gồm một phần **Ngày & Giờ hiện tại** riêng khi biết +múi giờ của người dùng. Để giữ bộ nhớ đệm lời nhắc ổn định, giờ đây nó chỉ bao gồm **múi giờ** (không có đồng hồ động hoặc định dạng thời gian). -Dùng `session_status` khi tác nhân cần thời gian hiện tại; thẻ trạng thái -bao gồm một dòng dấu thời gian. Cùng công cụ đó có thể tùy chọn đặt ghi đè mô hình theo từng phiên -(`model=default` xóa ghi đè đó). +Dùng `session_status` khi agent cần thời gian hiện tại; thẻ trạng thái +bao gồm một dòng dấu thời gian. Cùng công cụ đó có thể tùy chọn đặt một ghi đè mô hình +theo phiên (`model=default` xóa nó). Cấu hình bằng: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Xem [Ngày & giờ](/vi/date-time) để biết đầy đủ chi tiết hành vi. +Xem [Ngày & Giờ](/vi/date-time) để biết đầy đủ chi tiết hành vi. ## Skills -Khi có Skills đủ điều kiện, OpenClaw chèn một **danh sách Skills khả dụng** gọn nhẹ -(`formatSkillsForPrompt`) bao gồm **đường dẫn tệp** cho từng Skills. Prompt +Khi có các skill đủ điều kiện, OpenClaw chèn một **danh sách skills khả dụng** gọn +(`formatSkillsForPrompt`) bao gồm **đường dẫn tệp** cho từng skill. Lời nhắc hướng dẫn mô hình dùng `read` để tải SKILL.md tại vị trí được liệt kê -(không gian làm việc, được quản lý, hoặc đi kèm). Nếu không có Skills nào đủ điều kiện, phần +(workspace, được quản lý, hoặc được đóng gói kèm). Nếu không có skill nào đủ điều kiện, phần Skills bị bỏ qua. -Điều kiện đủ bao gồm các cổng siêu dữ liệu Skills, kiểm tra môi trường/cấu hình runtime, -và danh sách cho phép Skills hiệu lực của tác nhân khi `agents.defaults.skills` hoặc +Điều kiện đủ bao gồm cổng siêu dữ liệu skill, kiểm tra môi trường/cấu hình runtime, +và danh sách cho phép skill hiệu lực của agent khi `agents.defaults.skills` hoặc `agents.list[].skills` được cấu hình. -Skills đi kèm Plugin chỉ đủ điều kiện khi Plugin sở hữu chúng được bật. -Điều này cho phép các Plugin công cụ cung cấp hướng dẫn vận hành sâu hơn mà không nhúng toàn bộ -hướng dẫn đó trực tiếp vào mọi mô tả công cụ. +Các skill được đóng gói kèm Plugin chỉ đủ điều kiện khi plugin sở hữu chúng được bật. +Điều này cho phép plugin công cụ phơi bày hướng dẫn vận hành sâu hơn mà không nhúng toàn bộ +hướng dẫn đó trực tiếp trong mọi mô tả công cụ. ``` @@ -232,42 +239,28 @@ hướng dẫn đó trực tiếp vào mọi mô tả công cụ. ``` -Điều này giữ prompt cơ sở nhỏ trong khi vẫn cho phép sử dụng Skills có mục tiêu. +Điều này giữ lời nhắc cơ sở nhỏ trong khi vẫn cho phép dùng skill có mục tiêu. -Ngân sách danh sách Skills do hệ thống Skills sở hữu: +Ngân sách danh sách skills thuộc sở hữu của hệ thống con skills: - Mặc định toàn cục: `skills.limits.maxSkillsPromptChars` -- Ghi đè theo tác nhân: `agents.list[].skillsLimits.maxSkillsPromptChars` +- Ghi đè theo từng agent: `agents.list[].skillsLimits.maxSkillsPromptChars` -Các đoạn trích runtime giới hạn chung dùng một bề mặt khác: +Các đoạn trích runtime có giới hạn chung dùng một bề mặt khác: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Sự tách biệt đó giữ kích thước Skills tách khỏi kích thước đọc/chèn runtime như -`memory_get`, kết quả công cụ trực tiếp, và làm mới AGENTS.md sau Compaction. +Sự phân tách đó giữ việc định cỡ Skills riêng với việc định cỡ đọc/chèn lúc thời gian chạy như `memory_get`, kết quả công cụ trực tiếp và các lần làm mới AGENTS.md sau Compaction. ## Tài liệu -Lời nhắc hệ thống bao gồm một phần **Tài liệu**. Khi tài liệu cục bộ có sẵn, phần này -trỏ đến thư mục tài liệu OpenClaw cục bộ (`docs/` trong một bản Git checkout hoặc tài liệu -gói npm đi kèm). Nếu tài liệu cục bộ không có sẵn, phần này sẽ chuyển sang -[https://docs.openclaw.ai](https://docs.openclaw.ai). +Prompt hệ thống bao gồm một phần **Tài liệu**. Khi có tài liệu cục bộ, phần này trỏ đến thư mục tài liệu OpenClaw cục bộ (`docs/` trong một bản checkout Git hoặc tài liệu đi kèm trong gói npm). Nếu không có tài liệu cục bộ, nó sẽ dùng phương án dự phòng là [https://docs.openclaw.ai](https://docs.openclaw.ai). -Phần tương tự cũng bao gồm vị trí mã nguồn OpenClaw. Các bản Git checkout cung cấp thư mục gốc -mã nguồn cục bộ để tác nhân có thể kiểm tra mã trực tiếp. Các bản cài đặt gói bao gồm URL -mã nguồn GitHub và yêu cầu tác nhân xem xét mã nguồn ở đó bất cứ khi nào tài liệu chưa đầy đủ hoặc -đã lỗi thời. Lời nhắc cũng ghi chú bản sao tài liệu công khai, Discord cộng đồng và ClawHub -([https://clawhub.ai](https://clawhub.ai)) để khám phá skills. Nó yêu cầu mô hình -tham khảo tài liệu trước đối với hành vi, lệnh, cấu hình hoặc kiến trúc của OpenClaw, và tự -chạy `openclaw status` khi có thể (chỉ hỏi người dùng khi không có quyền truy cập). -Riêng với cấu hình, nó hướng tác nhân đến hành động công cụ `gateway` -`config.schema.lookup` để có tài liệu và ràng buộc chính xác ở cấp trường, rồi đến -`docs/gateway/configuration.md` và `docs/gateway/configuration-reference.md` -để xem hướng dẫn rộng hơn. +Phần này cũng bao gồm vị trí mã nguồn OpenClaw. Các bản checkout Git hiển thị thư mục gốc mã nguồn cục bộ để tác tử có thể kiểm tra mã trực tiếp. Các bản cài đặt gói bao gồm URL mã nguồn GitHub và yêu cầu tác tử xem xét mã nguồn ở đó bất cứ khi nào tài liệu chưa đầy đủ hoặc đã cũ. Prompt cũng ghi chú bản sao tài liệu công khai, Discord cộng đồng và ClawHub ([https://clawhub.ai](https://clawhub.ai)) để khám phá Skills. Nó yêu cầu mô hình tham khảo tài liệu trước đối với hành vi, lệnh, cấu hình hoặc kiến trúc của OpenClaw, và tự chạy `openclaw status` khi có thể (chỉ hỏi người dùng khi không có quyền truy cập). Riêng với cấu hình, nó trỏ tác tử đến thao tác công cụ `gateway` là `config.schema.lookup` để xem tài liệu và ràng buộc chính xác ở cấp trường, sau đó đến `docs/gateway/configuration.md` và `docs/gateway/configuration-reference.md` để có hướng dẫn rộng hơn. ## Liên quan -- [Thời gian chạy tác nhân](/vi/concepts/agent) -- [Không gian làm việc của tác nhân](/vi/concepts/agent-workspace) +- [Runtime của tác tử](/vi/concepts/agent) +- [Không gian làm việc của tác tử](/vi/concepts/agent-workspace) - [Công cụ ngữ cảnh](/vi/concepts/context-engine) diff --git a/docs/vi/nodes/audio.md b/docs/vi/nodes/audio.md index 54699f4c3..dac00c845 100644 --- a/docs/vi/nodes/audio.md +++ b/docs/vi/nodes/audio.md @@ -1,13 +1,13 @@ --- read_when: - - Thay đổi phiên âm âm thanh hoặc xử lý phương tiện -summary: Cách âm thanh/ghi chú thoại đến được tải xuống, phiên âm và đưa vào phản hồi + - Thay đổi tính năng phiên âm âm thanh hoặc xử lý phương tiện +summary: Cách âm thanh/ghi chú thoại gửi đến được tải xuống, phiên âm và chèn vào các câu trả lời title: Âm thanh và ghi chú thoại x-i18n: - generated_at: "2026-04-29T22:54:18Z" + generated_at: "2026-05-02T23:39:11Z" model: gpt-5.5 provider: openai - source_hash: 35074d79104f767ee252064462202a8ec21ac26f6db25c39e67f31f6b40edeb7 + source_hash: 91cd6951f80c6137061a7d4e82415b0872bc92c6d6ad136273a2e9ad7ec00ac1 source_path: nodes/audio.md workflow: 16 --- @@ -16,33 +16,34 @@ x-i18n: ## Những gì hoạt động -- **Hiểu nội dung phương tiện (âm thanh)**: Nếu tính năng hiểu âm thanh được bật (hoặc được tự động phát hiện), OpenClaw: +- **Hiểu phương tiện (âm thanh)**: Nếu tính năng hiểu âm thanh được bật (hoặc được tự động phát hiện), OpenClaw: 1. Định vị tệp đính kèm âm thanh đầu tiên (đường dẫn cục bộ hoặc URL) và tải xuống nếu cần. 2. Áp dụng `maxBytes` trước khi gửi tới từng mục mô hình. 3. Chạy mục mô hình đủ điều kiện đầu tiên theo thứ tự (nhà cung cấp hoặc CLI). - 4. Nếu thất bại hoặc bị bỏ qua (kích thước/hết thời gian), thử mục tiếp theo. - 5. Khi thành công, thay thế `Body` bằng khối `[Audio]` và đặt `{{Transcript}}`. + 4. Nếu thất bại hoặc bị bỏ qua (kích thước/hết thời gian chờ), nó thử mục tiếp theo. + 5. Khi thành công, nó thay thế `Body` bằng một khối `[Audio]` và đặt `{{Transcript}}`. - **Phân tích lệnh**: Khi phiên âm thành công, `CommandBody`/`RawBody` được đặt thành bản phiên âm để các lệnh gạch chéo vẫn hoạt động. - **Ghi nhật ký chi tiết**: Trong `--verbose`, chúng tôi ghi nhật ký khi phiên âm chạy và khi nó thay thế phần thân. +- **Đọc chính tả trong giao diện điều khiển**: Trình soạn Chat có thể gửi một đoạn âm thanh micro được trình duyệt ghi lại tới `chat.transcribeAudio`. RPC Gateway đó ghi đoạn âm thanh vào một tệp cục bộ tạm thời, chạy cùng quy trình phiên âm âm thanh này, trả văn bản nháp về trình duyệt, rồi xóa tệp tạm thời. Bản thân nó không tạo một lượt chạy tác nhân. ## Tự động phát hiện (mặc định) Nếu bạn **không cấu hình mô hình** và `tools.media.audio.enabled` **không** được đặt thành `false`, -OpenClaw tự động phát hiện theo thứ tự này và dừng ở tùy chọn đầu tiên hoạt động: +OpenClaw tự động phát hiện theo thứ tự này và dừng ở tùy chọn hoạt động đầu tiên: 1. **Mô hình trả lời đang hoạt động** khi nhà cung cấp của nó hỗ trợ hiểu âm thanh. 2. **CLI cục bộ** (nếu đã cài đặt) - `sherpa-onnx-offline` (yêu cầu `SHERPA_ONNX_MODEL_DIR` với encoder/decoder/joiner/tokens) - - `whisper-cli` (từ `whisper-cpp`; dùng `WHISPER_CPP_MODEL` hoặc mô hình tiny đi kèm) - - `whisper` (Python CLI; tự động tải xuống mô hình) -3. **Gemini CLI** (`gemini`) dùng `read_many_files` + - `whisper-cli` (từ `whisper-cpp`; sử dụng `WHISPER_CPP_MODEL` hoặc mô hình tiny đi kèm) + - `whisper` (CLI Python; tự động tải xuống mô hình) +3. **Gemini CLI** (`gemini`) sử dụng `read_many_files` 4. **Xác thực nhà cung cấp** - Các mục `models.providers.*` đã cấu hình có hỗ trợ âm thanh sẽ được thử trước - Thứ tự dự phòng đi kèm: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral Để tắt tự động phát hiện, đặt `tools.media.audio.enabled: false`. Để tùy chỉnh, đặt `tools.media.audio.models`. -Lưu ý: Việc phát hiện tệp nhị phân là nỗ lực tốt nhất trên macOS/Linux/Windows; hãy bảo đảm CLI nằm trên `PATH` (chúng tôi mở rộng `~`), hoặc đặt một mô hình CLI rõ ràng với đường dẫn lệnh đầy đủ. +Lưu ý: Việc phát hiện nhị phân là nỗ lực tối đa trên macOS/Linux/Windows; hãy bảo đảm CLI nằm trên `PATH` (chúng tôi mở rộng `~`), hoặc đặt một mô hình CLI rõ ràng với đường dẫn lệnh đầy đủ. ## Ví dụ cấu hình @@ -70,7 +71,7 @@ Lưu ý: Việc phát hiện tệp nhị phân là nỗ lực tốt nhất trên } ``` -### Chỉ nhà cung cấp với kiểm soát phạm vi +### Chỉ nhà cung cấp với giới hạn phạm vi ```json5 { @@ -134,7 +135,7 @@ Lưu ý: Việc phát hiện tệp nhị phân là nỗ lực tốt nhất trên } ``` -### Gửi lại bản phiên âm vào cuộc trò chuyện (chọn tham gia) +### Phản hồi bản phiên âm vào cuộc trò chuyện (chọn bật) ```json5 { @@ -155,22 +156,22 @@ Lưu ý: Việc phát hiện tệp nhị phân là nỗ lực tốt nhất trên - Xác thực nhà cung cấp tuân theo thứ tự xác thực mô hình tiêu chuẩn (hồ sơ xác thực, biến môi trường, `models.providers.*.apiKey`). - Chi tiết thiết lập Groq: [Groq](/vi/providers/groq). -- Deepgram nhận `DEEPGRAM_API_KEY` khi dùng `provider: "deepgram"`. +- Deepgram nhận `DEEPGRAM_API_KEY` khi sử dụng `provider: "deepgram"`. - Chi tiết thiết lập Deepgram: [Deepgram (phiên âm âm thanh)](/vi/providers/deepgram). - Chi tiết thiết lập Mistral: [Mistral](/vi/providers/mistral). -- SenseAudio nhận `SENSEAUDIO_API_KEY` khi dùng `provider: "senseaudio"`. +- SenseAudio nhận `SENSEAUDIO_API_KEY` khi sử dụng `provider: "senseaudio"`. - Chi tiết thiết lập SenseAudio: [SenseAudio](/vi/providers/senseaudio). -- Các nhà cung cấp âm thanh có thể ghi đè `baseUrl`, `headers` và `providerOptions` thông qua `tools.media.audio`. -- Giới hạn kích thước mặc định là 20MB (`tools.media.audio.maxBytes`). Âm thanh quá kích thước sẽ bị bỏ qua cho mô hình đó và mục tiếp theo sẽ được thử. -- Các tệp âm thanh nhỏ/trống dưới 1024 byte bị bỏ qua trước khi phiên âm bằng nhà cung cấp/CLI. -- `maxChars` mặc định cho âm thanh **chưa được đặt** (bản phiên âm đầy đủ). Đặt `tools.media.audio.maxChars` hoặc `maxChars` theo từng mục để cắt ngắn đầu ra. +- Nhà cung cấp âm thanh có thể ghi đè `baseUrl`, `headers` và `providerOptions` qua `tools.media.audio`. +- Giới hạn kích thước mặc định là 20MB (`tools.media.audio.maxBytes`). Âm thanh vượt kích thước bị bỏ qua cho mô hình đó và mục tiếp theo sẽ được thử. +- Các tệp âm thanh rất nhỏ/rỗng dưới 1024 byte bị bỏ qua trước khi phiên âm bằng nhà cung cấp/CLI. +- `maxChars` mặc định cho âm thanh là **chưa đặt** (toàn bộ bản phiên âm). Đặt `tools.media.audio.maxChars` hoặc `maxChars` cho từng mục để cắt ngắn đầu ra. - Mặc định tự động của OpenAI là `gpt-4o-mini-transcribe`; đặt `model: "gpt-4o-transcribe"` để có độ chính xác cao hơn. - Dùng `tools.media.audio.attachments` để xử lý nhiều ghi chú thoại (`mode: "all"` + `maxAttachments`). -- Bản phiên âm có sẵn cho mẫu dưới dạng `{{Transcript}}`. -- `tools.media.audio.echoTranscript` mặc định tắt; bật để gửi xác nhận bản phiên âm trở lại cuộc trò chuyện gốc trước khi agent xử lý. -- `tools.media.audio.echoFormat` tùy chỉnh văn bản gửi lại (placeholder: `{transcript}`). +- Bản phiên âm có sẵn cho các mẫu dưới dạng `{{Transcript}}`. +- `tools.media.audio.echoTranscript` mặc định tắt; bật tùy chọn này để gửi xác nhận bản phiên âm trở lại cuộc trò chuyện gốc trước khi tác nhân xử lý. +- `tools.media.audio.echoFormat` tùy chỉnh văn bản phản hồi (placeholder: `{transcript}`). - stdout của CLI bị giới hạn (5MB); hãy giữ đầu ra CLI ngắn gọn. -- `args` của CLI nên dùng `{{MediaPath}}` cho đường dẫn tệp âm thanh cục bộ. Chạy `openclaw doctor --fix` để di chuyển các placeholder `{input}` không còn được khuyến nghị từ cấu hình `audio.transcription.command` cũ hơn. +- `args` của CLI nên dùng `{{MediaPath}}` cho đường dẫn tệp âm thanh cục bộ. Chạy `openclaw doctor --fix` để di chuyển các placeholder `{input}` đã không còn khuyến nghị từ cấu hình `audio.transcription.command` cũ. ### Hỗ trợ môi trường proxy @@ -183,42 +184,42 @@ Phiên âm âm thanh dựa trên nhà cung cấp tôn trọng các biến môi t - `http_proxy` - `all_proxy` -Nếu không có biến môi trường proxy nào được đặt, kết nối ra trực tiếp sẽ được dùng. Nếu cấu hình proxy sai định dạng, OpenClaw ghi nhật ký cảnh báo và quay về tải trực tiếp. +Nếu không có biến môi trường proxy nào được đặt, kết nối đi trực tiếp sẽ được sử dụng. Nếu cấu hình proxy sai định dạng, OpenClaw ghi nhật ký cảnh báo và quay lại fetch trực tiếp. -## Phát hiện lượt nhắc trong nhóm +## Phát hiện đề cập trong nhóm -Khi `requireMention: true` được đặt cho cuộc trò chuyện nhóm, OpenClaw giờ đây phiên âm âm thanh **trước khi** kiểm tra lượt nhắc. Điều này cho phép ghi chú thoại được xử lý ngay cả khi chúng chứa lượt nhắc. +Khi `requireMention: true` được đặt cho một cuộc trò chuyện nhóm, OpenClaw hiện phiên âm âm thanh **trước khi** kiểm tra đề cập. Điều này cho phép xử lý ghi chú thoại ngay cả khi chúng chứa đề cập. **Cách hoạt động:** -1. Nếu một tin nhắn thoại không có phần thân văn bản và nhóm yêu cầu lượt nhắc, OpenClaw thực hiện phiên âm "preflight". -2. Bản phiên âm được kiểm tra theo các mẫu lượt nhắc (ví dụ: `@BotName`, trình kích hoạt emoji). -3. Nếu tìm thấy lượt nhắc, tin nhắn đi qua toàn bộ quy trình trả lời. -4. Bản phiên âm được dùng để phát hiện lượt nhắc để ghi chú thoại có thể vượt qua cổng lượt nhắc. +1. Nếu một tin nhắn thoại không có phần thân văn bản và nhóm yêu cầu đề cập, OpenClaw thực hiện phiên âm "preflight". +2. Bản phiên âm được kiểm tra các mẫu đề cập (ví dụ: `@BotName`, trình kích hoạt emoji). +3. Nếu tìm thấy đề cập, tin nhắn tiếp tục qua toàn bộ quy trình trả lời. +4. Bản phiên âm được dùng để phát hiện đề cập để ghi chú thoại có thể vượt qua cổng đề cập. **Hành vi dự phòng:** -- Nếu phiên âm thất bại trong preflight (hết thời gian, lỗi API, v.v.), tin nhắn được xử lý dựa trên phát hiện lượt nhắc chỉ bằng văn bản. -- Điều này bảo đảm rằng các tin nhắn hỗn hợp (văn bản + âm thanh) không bao giờ bị loại bỏ sai. +- Nếu phiên âm thất bại trong preflight (hết thời gian chờ, lỗi API, v.v.), tin nhắn được xử lý dựa trên phát hiện đề cập chỉ bằng văn bản. +- Điều này bảo đảm các tin nhắn hỗn hợp (văn bản + âm thanh) không bao giờ bị loại bỏ sai. **Tắt theo từng nhóm/chủ đề Telegram:** -- Đặt `channels.telegram.groups..disableAudioPreflight: true` để bỏ qua kiểm tra lượt nhắc bằng bản phiên âm preflight cho nhóm đó. +- Đặt `channels.telegram.groups..disableAudioPreflight: true` để bỏ qua kiểm tra đề cập trong bản phiên âm preflight cho nhóm đó. - Đặt `channels.telegram.groups..topics..disableAudioPreflight` để ghi đè theo từng chủ đề (`true` để bỏ qua, `false` để buộc bật). -- Mặc định là `false` (preflight được bật khi điều kiện có cổng lượt nhắc khớp). +- Mặc định là `false` (preflight được bật khi điều kiện có cổng đề cập khớp). -**Ví dụ:** Người dùng gửi một ghi chú thoại nói "Hey @Claude, what's the weather?" trong nhóm Telegram có `requireMention: true`. Ghi chú thoại được phiên âm, lượt nhắc được phát hiện và agent trả lời. +**Ví dụ:** Một người dùng gửi ghi chú thoại nói "Hey @Claude, what's the weather?" trong một nhóm Telegram có `requireMention: true`. Ghi chú thoại được phiên âm, đề cập được phát hiện, và tác nhân trả lời. -## Những điểm cần lưu ý +## Lưu ý dễ vấp -- Quy tắc phạm vi dùng lượt khớp đầu tiên thắng. `chatType` được chuẩn hóa thành `direct`, `group` hoặc `room`. +- Quy tắc phạm vi dùng nguyên tắc khớp đầu tiên thắng. `chatType` được chuẩn hóa thành `direct`, `group` hoặc `room`. - Bảo đảm CLI của bạn thoát với mã 0 và in văn bản thuần; JSON cần được xử lý qua `jq -r .text`. -- Với `parakeet-mlx`, nếu bạn truyền `--output-dir`, OpenClaw đọc `/.txt` khi `--output-format` là `txt` (hoặc bị bỏ qua); các định dạng đầu ra không phải `txt` quay về phân tích stdout. +- Với `parakeet-mlx`, nếu bạn truyền `--output-dir`, OpenClaw đọc `/.txt` khi `--output-format` là `txt` (hoặc bị bỏ qua); các định dạng đầu ra không phải `txt` quay lại phân tích stdout. - Giữ thời gian chờ hợp lý (`timeoutSeconds`, mặc định 60 giây) để tránh chặn hàng đợi trả lời. -- Phiên âm preflight chỉ xử lý tệp đính kèm âm thanh **đầu tiên** để phát hiện lượt nhắc. Âm thanh bổ sung được xử lý trong giai đoạn hiểu phương tiện chính. +- Phiên âm preflight chỉ xử lý tệp đính kèm âm thanh **đầu tiên** để phát hiện đề cập. Âm thanh bổ sung được xử lý trong giai đoạn hiểu phương tiện chính. ## Liên quan -- [Hiểu nội dung phương tiện](/vi/nodes/media-understanding) +- [Hiểu phương tiện](/vi/nodes/media-understanding) - [Chế độ trò chuyện](/vi/nodes/talk) - [Đánh thức bằng giọng nói](/vi/nodes/voicewake) diff --git a/docs/vi/plugins/codex-harness.md b/docs/vi/plugins/codex-harness.md index 44243fa94..849eaaf50 100644 --- a/docs/vi/plugins/codex-harness.md +++ b/docs/vi/plugins/codex-harness.md @@ -1,58 +1,58 @@ --- read_when: - - Bạn muốn dùng bộ khung app-server Codex đi kèm - - Bạn cần các ví dụ về cấu hình bộ chạy Codex + - Bạn muốn sử dụng bộ khung app-server đi kèm của Codex + - Bạn cần các ví dụ cấu hình bộ điều phối 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 của OpenClaw thông qua harness app-server Codex được đóng gói kèm +summary: Chạy các lượt tác nhân nhúng của OpenClaw thông qua bộ khung app-server Codex đi kèm title: Bộ khung Codex x-i18n: - generated_at: "2026-05-02T10:47:20Z" + generated_at: "2026-05-02T23:39:32Z" model: gpt-5.5 provider: openai - source_hash: 107f9fc0a3e8ad6a4790fc9eb68276c81d299236f11293014d2ab9bf6e235133 + source_hash: 8ffa0cbb28422b2ed8d7c0eef6ee0222072c523d170b4b33597bb37bd3fa9700 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 -máy chủ ứng dụng Codex thay vì harness PI tích hợp sẵn. +Plugin `codex` được đóng gói cho phép OpenClaw chạy các lượt agent nhúng thông qua +app-server Codex thay vì harness PI tích hợp sẵn. -Dùng cách này khi bạn muốn Codex sở hữu phiên agent cấp thấp: khám phá model, -tiếp tục thread gốc, Compaction gốc và thực thi trên máy chủ ứng dụng. -OpenClaw vẫn sở hữu các kênh chat, tệp phiên, lựa chọn model, công cụ, +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 trò chuyện, 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ị. -Khi một lượt chat nguồn chạy qua harness Codex, các câu trả lờ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 mình một cách riêng tư; +Khi một lượt trò chuyện nguồn chạy qua harness Codex, các phản hồi hiển thị mặc định +dùng công cụ OpenClaw `message` 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 câu trả lời cuối cùng trong chat trực tiếp trên +`messages.visibleReplies: "automatic"` để giữ các phản hồi cuối của trò chuyện trực tiếp trên đường phân phối tự động cũ. -Các lượt Heartbeat của Codex cũng mặc định nhận công cụ `heartbeat_respond`, để -agent 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 cùng. +Các lượt heartbeat Codex cũng nhận công cụ `heartbeat_respond` theo mặc định, để +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. Nếu bạn đang cố định hướng, hãy bắt đầu với -[Runtime của agent](/vi/concepts/agent-runtimes). Phiên bản ngắn gọn là: -`openai/gpt-5.5` là tham chiếu model, `codex` là runtime, còn Telegram, +[Thời gian chạy 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à thời gian chạy, còn Telegram, Discord, Slack hoặc một 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 lộ trình 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 -máy chủ ứng dụng Codex gốc. Tham chiếu model vẫn giữ dạng chuẩn là +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 một +gói đăng ký ChatGPT/Codex, rồi chạy các lượt agent nhúng qua thời gian chạy +app-server Codex 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ố model `openai-codex/*`. +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 ``` -Sau đó bật Plugin `codex` đi kèm và ép dùng runtime Codex: +Sau đó bật Plugin `codex` được đóng gói và ép dùng thời gian chạy Codex: ```json5 { @@ -90,182 +90,189 @@ Nếu cấu hình của bạn dùng `plugins.allow`, hãy thêm cả `codex` và } ``` -Không dùng `openai-codex/gpt-*` khi ý bạn là runtime Codex gốc. Tiền tố đó -là lộ trình rõ ràng "Codex OAuth thông qua PI". Các 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 lại của chúng. +Đừng dùng `openai-codex/gpt-*` khi bạn muốn thời gian chạy Codex gốc. Tiền tố đó +là tuyến rõ ràng "Codex OAuth qua PI". Các 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ữ thời gian chạy đã ghi nhận của chúng. ## Plugin này thay đổi gì -Plugin `codex` đi kèm đóng góp một số năng lực riêng biệt: +Plugin `codex` được đóng gói đóng góp nhiều năng lực riêng biệt: -| Năng lực | Cách bạn dùng | Chức năng | -| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| Runtime nhúng gốc | `agentRuntime.id: "codex"` | Chạy các lượt agent nhúng của OpenClaw thông qua máy chủ ứng dụng Codex. | -| 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 thread máy chủ ứng dụng Codex từ cuộc trò chuyện nhắn tin. | -| Nhà cung cấp/danh mục máy chủ ứng dụng Codex | phần nội bộ `codex`, được bộc lộ thông qua harness | Cho phép runtime khám phá và xác thực các model máy chủ ứng dụng. | -| Đường hiểu phương tiện Codex | đường tương thích model hình ảnh `codex/*` | Chạy các lượt máy chủ ứng dụng Codex có giới hạn cho các model hiểu hình ảnh được hỗ trợ. | -| Chuyển tiếp hook gốc | Hook của 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ợ. | +| Năng lực | Cách bạn dùng | Nó làm gì | +| -------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Thời gian chạy nhúng gốc | `agentRuntime.id: "codex"` | Chạy các lượt agent nhúng của OpenClaw qua app-server Codex. | +| Lệnh điều khiển trò chuyện gốc | `/codex bind`, `/codex resume`, `/codex steer`, ... | Liên kết và điều khiển các luồng app-server Codex từ một cuộc trò chuyện nhắn tin. | +| Nhà cung cấp/danh mục app-server Codex | nội bộ `codex`, được hiển thị qua harness | Cho phép thời gian chạy khám phá và xác thực các mô hình app-server. | +| Đường hiểu phương tiện Codex | các đường tương thích mô hình hình ảnh `codex/*` | Chạy các lượt app-server Codex có giới hạn cho những 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 gốc của Codex | 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 năng lực đó sẵn dùng. Nó **không**: +Bật Plugin sẽ làm cho các năng lực đó khả dụng. Việc này **không**: -- bắt đầu dùng Codex cho mọi model OpenAI -- chuyển đổi tham chiếu model `openai-codex/*` thành runtime gốc +- 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 thời gian chạy gốc - đặt ACP/acpx làm đường Codex mặc định -- chuyển nóng các phiên hiện có đã ghi lại runtime PI -- thay thế phân phối kênh của OpenClaw, tệp phiên, lưu trữ hồ sơ xác thực hoặc - định tuyến tin nhắn +- chuyển nóng các phiên hiện có đã ghi nhận thời gian chạy PI +- thay thế việc 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 -Cùng Plugin đó cũng sở hữu bề mặt lệnh điều khiển chat `/codex` gốc. Nếu +Cùng Plugin đó cũng sở hữu bề mặt lệnh điều khiển trò chuyện `/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 thread Codex từ chat, agent nên ưu tiên `/codex ...` thay vì ACP. ACP vẫn là +các luồng Codex từ trò chuyện, 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. +ACP 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 cùng tiến trình, không phải hook lệnh `hooks.json` của Codex: +Các lượt Codex gốc giữ các 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 sao chiếu +- `before_message_write` cho các bản ghi transcript được sao chép - `before_agent_finalize` thông qua chuyển tiếp `Stop` của Codex - `agent_end` -Plugin cũng có thể đăng ký middleware kết quả công cụ trung lập với runtime để viết lại +Plugin cũng có thể đăng ký middleware kết quả công cụ trung lập với thời gian chạy để 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 chuyển đổi các lượt ghi kết quả công cụ trong transcript do OpenClaw sở hữu. +kết quả được trả về Codex. Việc 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ụ vào transcript do OpenClaw sở hữu. -Để biết ngữ nghĩa của chính các hook Plugin, xem [Hook của Plugin](/vi/plugins/hooks) -và [Hành vi guard của Plugin](/vi/tools/plugin). +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). -Harness tắt theo mặc định. Cấu hình mới nên giữ tham chiếu model OpenAI -ở dạng chuẩn là `openai/gpt-*` và ép rõ -`agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex` khi chúng -muốn thực thi trên máy chủ ứng dụng gốc. Các tham chiếu model `codex/*` cũ 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ư các lựa chọn model/nhà cung cấp thông thường. +Harness tắt theo mặc định. Cấu hình mới nên giữ tham chiếu mô hình OpenAI +ở dạng chuẩn `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 `codex/*` cũ vẫn tự động chọn +harness để tương thích, nhưng các tiền tố nhà cung cấp cũ được hỗ trợ bởi thời gian chạy +không 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 model chính vẫn là -`openai-codex/*`, `openclaw doctor` sẽ cảnh báo thay vì thay đổi lộ trình. Điều đó là -có chủ ý: `openai-codex/*` vẫn là đường PI Codex OAuth/gói đăng ký, và -thực thi máy chủ ứng dụng gốc vẫn là một lựa chọn runtime rõ rà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à +có chủ ý: `openai-codex/*` vẫn là đường Codex OAuth/gói đăng ký qua PI, còn +thực thi app-server gốc vẫn là một lựa chọn thời gian chạy rõ ràng. -## Bản đồ lộ trình +## 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 model | Cấu hình runtime | Lộ trình xác thực/hồ sơ | Nhãn trạng thái dự kiến | -| -------------------------------------------------- | -------------------------- | -------------------------------------- | ----------------------------- | ------------------------------ | -| 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 qua trình chạy 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 theo nhà cung cấp | `agentRuntime.id: "auto"` | Theo nhà cung cấp được chọn | Tùy runtime được chọn | -| Phiên bộ chuyển đổi Codex ACP rõ ràng | phụ thuộc prompt/model 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 thời gian chạy | 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 thời gian chạy Codex gốc | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth hoặc tài khoản Codex | `Runtime: OpenAI Codex` | +| OpenAI API qua trình chạy 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 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 đã chọn | Phụ thuộc vào thời gian chạy đã 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 tách quan trọng là nhà cung cấp so với runtime: +Điểm phân tách quan trọng là nhà cung cấp so với thời gian chạy: -- `openai-codex/*` trả lời "PI nên dùng nhà cung cấp/lộ trình 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 +- `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à trò chuyện này nên liên kết hoặc điều khiển?" -- ACP trả lời "quy trình harness bên ngoài nào mà acpx nên khởi chạy?" +- ACP trả lời "acpx nên khởi chạy tiến trình harness bên ngoài nào?" -## Chọn đúng tiền tố model +## Chọn đúng tiền tố mô hình -Các lộ trình thuộc 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 -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: +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 +thời gian chạy Codex gốc, dùng `openai/*` với `agentRuntime.id: "codex"`. +Chỉ dùng `openai-codex/*` khi bạn cố ý muốn Codex OAuth qua PI: -| Tham chiếu model | Đường runtime | Dùng khi | +| Tham chiếu mô hình | Đường thời gian chạy | 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 thông qua OpenClaw/PI | Bạn muốn xác thực gói đăng ký ChatGPT/Codex với trình chạy PI mặc định. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness máy chủ ứng dụng Codex | Bạn muốn xác thực gói đăng ký ChatGPT/Codex với thực thi Codex gốc. | +| `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 trình chạy PI mặc định. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness app-server Codex | 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ả lộ trình khóa API OpenAI trực tiếp và 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 harness máy chủ ứng dụng Codex -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 khóa API trực tiếp. +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 harness app-server Codex +cho thời gian chạy Codex gốc, `openai-codex/gpt-5.5` cho PI OAuth, hoặc +`openai/gpt-5.5` không có ghi đè thời gian chạy Codex cho lưu lượng khóa API trực tiếp. -Các tham chiếu `codex/gpt-*` cũ 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 model chuẩn -và ghi lại chính sách runtime riêng, còn 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ác tham chiếu `codex/gpt-*` cũ vẫn được chấp nhận như 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 thời gian chạy chính cũ thành tham chiếu mô hình +chuẩn và ghi chính sách thời gian chạy riêng, trong khi các tham chiếu cũ chỉ dùng dự phòng +được giữ nguyên vì thời gian chạy đượ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 -máy chủ ứng dụng gốc mới nên dùng `openai/gpt-*` cộng +app-server gốc mới nên dùng `openai/gpt-*` cộng `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` tuân theo cùng phân tách tiền tố. Dùng -`openai-codex/gpt-*` khi việc hiểu hình ảnh nên chạy qua đường nhà cung cấp -OpenAI Codex OAuth. Dùng `codex/gpt-*` khi việc hiểu hình ảnh nên chạy -qua một lượt máy chủ ứng dụng Codex có giới hạn. Model máy chủ ứng dụng Codex phải -quảng bá hỗ trợ đầu vào hình ảnh; các model Codex chỉ văn bản thất bại trước khi lượt phương tiện +`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 app-server Codex có giới hạn. Mô hình app-server Codex 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ẽ lỗ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 nhật ký gỡ lỗi cho hệ thống con `agents/harness` -và kiểm tra bản ghi có cấu trúc `agent harness selected` của Gateway. Nó -bao gồm id harness được chọn, lý do lựa chọn, chính sách runtime/dự phòng, và, +gây bất ngờ, bật ghi nhật ký gỡ lỗi cho hệ thống con `agents/harness` +và kiểm tra bản ghi có cấu trúc `agent harness selected` của gateway. Nó +bao gồm id harness đã chọn, lý do lựa chọn, chính sách thời gian chạy/dự phòng và, ở chế độ `auto`, kết quả hỗ trợ của từng ứng viên Plugin. -### Cảnh báo doctor có nghĩa gì +### Ý nghĩa của cảnh báo doctor `openclaw doctor` cảnh báo khi tất cả điều sau là đúng: -- Plugin `codex` đi kèm được bật hoặc được cho phép -- model 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` được đóng gói được bật hoặc được cho phép +- mô hình chính của một agent là `openai-codex/*` +- thời gian chạy hiệu lực của agent đó 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 được bật" sẽ hàm ý -"runtime máy chủ ứng dụng Codex gốc." OpenClaw không tự suy luận như vậy. Cảnh báo +Cảnh báo đó tồn tại vì người dùng thường kỳ vọng "Plugin Codex được bật" đồng nghĩa với +"thời gian chạy app-server Codex gốc." OpenClaw không tự suy ra như vậy. Cảnh báo có nghĩa là: -- **Không cần thay đổi** nếu bạn chủ định dùng ChatGPT/Codex OAuth thông qua PI. -- Đổi model thành `openai/` và đặt - `agentRuntime.id: "codex"` nếu bạn chủ định thực thi trên máy chủ ứng dụng - gốc. -- Các phiên hiện có vẫn cần `/new` hoặc `/reset` sau khi thay đổi runtime, - vì ghim runtime của phiên là bám dính. +- **Không cần thay đổi** nếu bạn dự định dùng ChatGPT/Codex OAuth qua PI. +- Đổi mô hình thành `openai/` và đặt + `agentRuntime.id: "codex"` nếu bạn dự định 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 thời gian chạy, + vì các ghim thời gian chạy của phiên là cố định. -Lựa chọn harness không phải điều khiển phiên trực tiếp. Khi một lượt nhúng chạy, -OpenClaw ghi lại id harness đã chọn trên phiên đó và tiếp tục dùng nó cho +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 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 +`OPENCLAW_AGENT_RUNTIME` khi bạn muốn các phiên tương lai dùng một 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. Việc 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 cũ được tạo trước khi có ghim harness được xem là đã ghim PI sau khi chúng -có lịch sử transcript. Dùng `/new` hoặc `/reset` để chọn cho cuộc trò chuyện đó vào +Các phiên cũ được tạo trước khi có ghim harness sẽ đượ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 thay đổi cấu hình. -`/status` hiển thị runtime mô hình có 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 dưới dạng +`Runtime: OpenClaw Pi Default`, còn harness app-server Codex xuất hiện dưới dạng `Runtime: OpenAI Codex`. ## Yêu cầu -- OpenClaw có sẵn Plugin `codex` được đóng gói kèm. -- App-server Codex `0.125.0` trở lên. Theo mặc định, Plugin được đóng gói kèm quản lý một tệp nhị phân app-server Codex tương thích, vì vậy các lệnh `codex` cục bộ trên `PATH` 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ộ sử dụng một home Codex do OpenClaw quản lý cho từng tác tử và một `HOME` con biệt lập, vì vậy theo mặc định chúng không đọc tài khoản `~/.codex` cá nhân, Skills, plugins, cấu hình, trạng thái luồng hoặc `$HOME/.agents/skills` gốc của bạn. +- OpenClaw có sẵn plugin `codex` được đóng gói kèm. +- App-server Codex `0.125.0` trở lên. Theo mặc định, plugin được đóng gói kèm quản lý một tệp nhị phân app-server Codex tương thích, vì vậy các lệnh `codex` cục bộ trên `PATH` không ảnh hưởng đến quá trình khởi động harness thông thường. +- Auth Codex có sẵn cho tiến trình app-server hoặc cho bridge auth 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 tách biệt, nên theo mặc định chúng không đọc tài khoản `~/.codex`, skills, plugins, cấu hình, trạng thái thread hoặc `$HOME/.agents/skills` native cá nhân của bạn. -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ữ OpenClaw trên bề mặt giao thức mà OpenClaw đã được kiểm thử. +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 protocol đã được kiểm thử. -Đối với các bài kiểm thử smoke trực tiếp và Docker, xác thực thường đến từ tài khoản CLI Codex hoặc 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 sang `CODEX_API_KEY` / `OPENAI_API_KEY` khi không có tài khoản nào. +Đối với các kiểm thử smoke live và Docker, auth thường đến từ tài khoản CLI Codex hoặc một hồ sơ auth `openai-codex` của OpenClaw. Các lần khởi chạy app-server 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. -## Thêm Codex bên cạnh các mô hình khác +## Tệp bootstrap workspace -Không đặt `agentRuntime.id: "codex"` trên toàn cục nếu cùng một tác tử 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 tác tử 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à thất bại đóng thay vì âm thầm định tuyến lượt đó qua PI. +Codex tự xử lý `AGENTS.md` thông qua cơ chế khám phá tài liệu dự án native. 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 các tên tệp fallback của Codex cho tệp persona, vì fallback của Codex chỉ áp dụng khi thiếu `AGENTS.md`. -Thay vào đó, hãy dùng một trong các dạng sau: +Để đạt 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ó) rồi chuyển tiếp chúng qua hướng dẫn cấu hình 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 hiển thị mà không nhân bản `AGENTS.md`. -- Đặt Codex trên một tác tử chuyên dụng với `agentRuntime.id: "codex"`. -- Giữ tác tử mặc định trên `agentRuntime.id: "auto"` và dự phòng PI cho việc sử dụng nhà cung cấp hỗn hợp thông thường. -- Chỉ dùng các tham chiếu `codex/*` cũ để 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. +## Thêm Codex cùng các mô hình khác -Ví dụ, cấu hình này giữ tác tử mặc định trên lựa chọn tự động thông thường và thêm một tác tử Codex riêng: +Khô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 provider 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 session đó. 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à fail closed thay vì âm thầm định tuyến lượt đó qua PI. + +Hãy dùng một trong các dạng sau: + +- Đặt Codex trên một agent chuyên biệt với `agentRuntime.id: "codex"`. +- Giữ agent mặc định trên `agentRuntime.id: "auto"` và PI fallback cho cách dùng provider hỗn hợp thông thường. +- Chỉ dùng các ref `codex/*` legacy để 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. + +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: ```json5 { @@ -304,31 +311,31 @@ Ví dụ, cấu hình này giữ tác tử mặc định trên lựa chọn tự Với dạng này: -- Tác tử `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. -- Tác tử `codex` dùng harness app-server Codex. -- Nếu Codex bị thiếu hoặc không được hỗ trợ cho tác tử `codex`, lượt sẽ thất bại thay vì âm thầm dùng 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 đó thất bại thay vì lặng lẽ dùng PI. -## Định tuyến lệnh tác tử +## Định tuyến lệnh agent -Tác tử nên định tuyến yêu cầu của người dùng theo ý định, không chỉ theo 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... | Tác tử nên dùng... | +| Người dùng yêu cầu... | Agent nên dùng... | | ------------------------------------------------------ | ------------------------------------------------ | -| "Bind this chat to Codex" | `/codex bind` | -| "Resume Codex thread `` here" | `/codex resume ` | -| "Show Codex threads" | `/codex threads` | -| "File a support report for a bad Codex run" | `/diagnostics [note]` | -| "Only send Codex feedback for this attached thread" | `/codex diagnostics [note]` | -| "Use my ChatGPT/Codex subscription with Codex runtime" | `openai/*` plus `agentRuntime.id: "codex"` | -| "Use my ChatGPT/Codex subscription through PI" | `openai-codex/*` model refs | -| "Run Codex through ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Start Claude Code/Gemini/OpenCode/Cursor in a thread" | ACP/acpx, not `/codex` and not native sub-agents | +| “Bind this chat to Codex” | `/codex bind` | +| “Resume Codex thread `` here” | `/codex resume ` | +| “Show Codex threads” | `/codex threads` | +| “File a support report for a bad Codex run” | `/diagnostics [note]` | +| “Only send Codex feedback for this attached thread” | `/codex diagnostics [note]` | +| “Use my ChatGPT/Codex subscription with Codex runtime” | `openai/*` cộng với `agentRuntime.id: "codex"` | +| “Use my ChatGPT/Codex subscription through PI” | ref mô hình `openai-codex/*` | +| “Run Codex through ACP/acpx” | ACP `sessions_spawn({ runtime: "acp", ... })` | +| “Start Claude Code/Gemini/OpenCode/Cursor in a thread” | ACP/acpx, không phải `/codex` và không phải sub-agent native | -OpenClaw chỉ quảng bá hướng dẫn sinh ACP cho tác tử khi ACP được bật, có thể điều phối và được một backend runtime đã tải hỗ trợ. Nếu ACP không khả dụng, prompt hệ thống và Skills của Plugin không nên dạy tác tử 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ậu thuẫn 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 tác tử nhúng đều dùng Codex. Runtime Plugin rõ ràng mặc định không có dự phòng PI, vì vậy `fallback: "none"` là tùy chọn nhưng thường hữu ích như tài liệu: +Ép buộc 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 tường minh mặc định không có PI fallback, nên `fallback: "none"` là tùy chọn nhưng thường hữu ích như tài liệu: ```json5 { @@ -344,17 +351,17 @@ OpenClaw chỉ quảng bá hướng dẫn sinh ACP cho tác tử khi ACP đượ } ``` -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. Chỉ đặt `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` nếu bạn cố ý muốn PI xử lý khi không chọn được harness. +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. Chỉ đặt `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` nếu bạn chủ ý muốn PI xử lý khi thiếu lựa chọn harness. -## Codex theo từng tác tử +## Codex theo từng agent -Bạn có thể đặt một tác tử chỉ dùng Codex trong khi tác tử mặc định giữ cơ chế tự động chọn thông thường: +Bạn có thể đặt một agent chỉ dùng Codex trong khi agent mặc định giữ lựa chọn tự động thông thường: ```json5 { @@ -385,11 +392,11 @@ Bạn có thể đặt một tác tử chỉ dùng Codex trong khi tác tử m } ``` -Dùng các lệnh phiên thông thường để chuyển đổi tác tử 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 luồng app-server sidecar của nó khi cần. `/reset` xóa ràng buộc phiên OpenClaw cho luồng đó 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 session thông thường để chuyển agent và mô hình. `/new` tạo một session 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 session 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. ## 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 khám phá thất bại hoặc hết thời gian, nó dùng danh mục dự phòng được đóng gói kèm cho: +Theo mặc định, plugin Codex yêu cầu app-server cung cấp các mô hình khả dụng. Nếu khám phá thất bại hoặc hết thời gian chờ, nó dùng catalog fallback được đóng gói kèm cho: - GPT-5.5 - GPT-5.4 mini @@ -415,7 +422,7 @@ Bạn có thể tinh chỉnh khám phá trong `plugins.entries.codex.config.disc } ``` -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 danh mục dự phòng: +Tắt khám phá khi bạn muốn quá trình khởi động tránh probe Codex và chỉ dùng catalog fallback: ```json5 { @@ -436,17 +443,19 @@ Tắt khám phá khi bạn muốn quá trình khởi động tránh thăm dò Co ## Kết nối và chính sách app-server -Theo mặc định, Plugin khởi động tệp nhị phân Codex do OpenClaw quản lý cục bộ với: +Theo mặc định, plugin khởi động tệp nhị phân Codex do OpenClaw quản lý ở cục bộ với: ```bash codex app-server --listen stdio:// ``` -Tệp nhị phân đượ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 được đóng gói kèm thay vì bất kỳ CLI Codex riêng biệt 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. +Tệp nhị phân đượ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 được đóng gói kèm thay vì bất kỳ CLI Codex riêng nào tình cờ được cài đặt cục bộ. Chỉ đặt `appServer.command` khi bạn chủ ý muốn chạy một executable 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 được dùng cho Heartbeat tự trị: Codex có thể dùng công cụ shell và mạng mà không dừng ở các prompt phê duyệt gốc khi không có ai ở đó để trả lời. +Theo mặc định, OpenClaw khởi động các session harness Codex cục bộ ở chế độ YOLO: +`approvalPolicy: "never"`, `approvalsReviewer: "user"`, và +`sandbox: "danger-full-access"`. Đây là tư thế operator cục bộ đáng tin cậy dùng cho Heartbeat tự trị: Codex có thể dùng shell và công cụ mạng mà không dừng ở các prompt phê duyệt native không có ai ở đó để trả lời. -Để chọn dùng phê duyệt do guardian của Codex xem xét, đặt `appServer.mode: +Để chọn tham gia phê duyệt do guardian của Codex xem xét, đặt `appServer.mode: "guardian"`: ```json5 @@ -467,11 +476,13 @@ Theo mặc định, OpenClaw khởi động các phiên harness Codex cục bộ } ``` -Chế độ guardian dùng đường dẫn phê duyệt tự động xem xét gốc của Codex. Khi Codex yêu cầu rời sandbox, ghi 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 bộ xem xét gốc thay vì prompt cho con người. Bộ xem xét á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 các tác tử không có 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 native của Codex. Khi Codex yêu cầu rời sandbox, ghi 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 native 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 guardrail 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`, vì vậy các triển khai nâng cao có thể trộn preset với các lựa chọn rõ ràng. Giá trị bộ xem xét `guardian_subagent` cũ hơn 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`. +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`, vì vậy các triển khai nâng cao có thể trộn preset với lựa chọn tường minh. Giá trị reviewer cũ hơn `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: +Với app-server đang chạy sẵn, dùng transport WebSocket: ```json5 { @@ -493,26 +504,28 @@ Preset `guardian` mở rộng thành `approvalPolicy: "on-request"`, `approvalsR } ``` -Theo mặc đị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, 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 các thư mục theo từng tác tử dưới trạng thái OpenClaw của tác tử đó. Trình tải skill riêng của Codex đọc `$CODEX_HOME/skills` và `$HOME/.agents/skills`, vì vậy 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 Codex, plugins, cấu hình, tài khoản và trạng thái luồng nằm trong phạm vi tác tử OpenClaw thay vì rò rỉ từ home CLI Codex 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 bridge tài khoản app-server Codex 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 đó. Bộ tải skill riêng của Codex đọc `$CODEX_HOME/skills` và `$HOME/.agents/skills`, nên cả hai giá trị đều được tách biệt cho các lần khởi chạy app-server cục bộ. Điều đó giữ cho skills, plugins, cấu hình, tài khoản và trạng thái thread native của Codex nằm trong phạm vi agent OpenClaw thay vì rò rỉ từ home CLI Codex cá nhân của operator. -Plugins 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 CLI Codex cá nhân thì không. Nếu bạn có Skills CLI Codex hoặc plugins hữu ích cần trở thành một phần của tác tử OpenClaw, hãy kiểm kê chúng rõ ràng: +Plugin OpenClaw và snapshot skill OpenClaw vẫn đi qua registry plugin và bộ tải skill riêng của OpenClaw. Tài sản CLI Codex cá nhân thì không. Nếu bạn có skills hoặc plugins CLI Codex 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 openclaw migrate apply codex --yes ``` -Nhà cung cấp di chuyển Codex sao chép Skills vào workspace tác tử OpenClaw hiện tại. Plugins gốc 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. +Provider di trú Codex sao chép skills vào workspace agent OpenClaw hiện tại. Plugins, hooks và tệp cấu hình native của Codex đượ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. -Xác thực được chọn theo thứ tự này: +Auth được chọn theo thứ tự sau: -1. Hồ sơ xác thực Codex OpenClaw rõ ràng cho tác tử. -2. Tài khoản hiện có của app-server trong home Codex của tác tử đó. -3. Chỉ với các lần khởi chạy app-server stdio cục bộ, `CODEX_API_KEY`, sau đó `OPENAI_API_KEY`, khi không có tài khoản app-server nào và xác thực OpenAI vẫn được yêu cầu. +1. Một hồ sơ auth Codex OpenClaw tường minh 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 và auth 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ó xóa `CODEX_API_KEY` và `OPENAI_API_KEY` khỏi tiến trình con Codex được sinh ra. Điều đó giữ các khóa API cấp Gateway khả dụng cho embeddings hoặc các mô hình OpenAI trực tiếp mà không vô tình làm 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 khóa môi trường stdio cục bộ dùng đăng nhập app-server thay vì môi trường tiến trình con được kế thừa. Kết nối app-server WebSocket không nhận dự phòng khóa API môi trường 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ơ auth Codex kiểu đăng ký ChatGPT, nó xóa `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 native tính phí qua API. Hồ sơ khóa API Codex tường minh và fallback khóa môi trường 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ơ auth tường minh hoặc tài khoản riêng của app-server từ xa. -Nếu một triển khai cần thêm cách ly môi trường, thêm các biến đó vào `appServer.clearEnv`: +Nếu một triển khai cần tách biệt môi trường bổ sung, hãy thêm các biến đó vào +`appServer.clearEnv`: ```json5 { @@ -533,47 +546,51 @@ Nếu một triển khai cần thêm cách ly môi trường, thêm các biến `appServer.clearEnv` chỉ ảnh hưởng đến tiến trình con app-server Codex được sinh ra. -Công cụ động Codex mặc định dùng hồ sơ `native-first`. Trong chế độ đó, OpenClaw không phơi bày các công cụ động trùng lặp với thao tác workspace gốc 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, nút, gateway, `heartbeat_respond` và `web_search` vẫn khả dụng. +Các công cụ động của Codex mặc định dùng hồ sơ `native-first`. Trong chế độ đó, +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, 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ông cụ động OpenClaw bổ sung cần bỏ qua khỏi 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 app-server Codex. | Các trường `appServer` được hỗ trợ: -| Trường | Mặc định | Ý nghĩa | -| ------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` khởi chạy 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 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 | Token Bearer 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 sinh ra sau khi OpenClaw xây dựng môi trường kế thừa của nó. `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 của app-server. | -| `mode` | `"yolo"` | Preset cho thực thi YOLO hoặc thực thi được guardian xem xét. | -| `approvalPolicy` | `"never"` | Chính sách phê duyệt Codex gốc được gửi tới lượt bắt đầu/tiếp tục/lượt. | -| `sandbox` | `"danger-full-access"` | Chế độ sandbox Codex gốc được gửi tới lượt bắt đầu/tiếp tục. | -| `approvalsReviewer` | `"user"` | Dùng `"auto_review"` để Codex xem xét các lời nhắc phê duyệt gốc. `guardian_subagent` vẫn là bí danh kế thừa. | -| `serviceTier` | chưa đặt | Bậc dịch vụ app-server Codex tùy chọn: `"fast"`, `"flex"`, hoặc `null`. Các giá trị kế thừa không hợp lệ sẽ bị bỏ qua. | +| Trường | Mặc định | Ý nghĩa | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` sinh 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 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 | Token Bearer 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 sinh ra 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ách ly Codex theo từng tác tử 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 có guardian duyệt. | +| `approvalPolicy` | `"never"` | Chính sách phê duyệt Codex gốc được gửi đến 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 đến lúc bắt đầu/tiếp tục luồng. | +| `approvalsReviewer` | `"user"` | Dùng `"auto_review"` để cho Codex duyệ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. | 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 Codex `item/tool/call` 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ếu đượ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 `item/tool/call` của Codex 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ếu đượ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 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 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 lane phiên -OpenClaw để các tin nhắn chat 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 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 +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 chat 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 có sẵn cho kiểm thử cục bộ: +Các ghi đè môi trường vẫn khả dụng cho kiểm thử cục bộ: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -584,26 +601,26 @@ Các ghi đè môi trường vẫn có sẵn 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 đó, dùng +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` đã bị gỡ bỏ. Thay vào đó, 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 xem xét với phần còn lại của thiết lập harness Codex. +được ưu tiên cho triển khai có thể lặp lại vì nó giữ hành vi Plugin trong cùng +tệp đã được duyệt 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: -[Sử dụng máy tính của Codex](/vi/plugins/codex-computer-use). +Sử dụng máy tính được đề cập trong hướng dẫn thiết lập riêng: +[Sử dụng máy tính với Codex](/vi/plugins/codex-computer-use). Phiên 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 hành động desktop. Nó chuẩn bị app-server Codex, xác minh rằng MCP -server `computer-use` có sẵn, rồi để Codex xử lý các lệnh gọi công cụ MCP gốc +thực thi hành động desktop. 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, đăng ký +Để truy cập trực tiếp driver TryCua ngoài luồng marketplace Codex, đăng ký `cua-driver mcp` bằng `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Xem [Sử dụng máy tính của Codex](/vi/plugins/codex-computer-use) để biết điểm 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. +Xem [Sử dụng máy tính với Codex](/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. Cấu hình tối thiểu: @@ -633,28 +650,28 @@ Cấu hình tối thiểu: } ``` -Có thể kiểm tra hoặc cài đặt phần thiết lập từ bề mặt lệnh: +Có thể kiểm tra hoặc cài đặt thiết lập từ bề mặt lệnh: - `/codex computer-use status` - `/codex computer-use install` - `/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ể yêu cầu quyền OS 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 có sẵn, các lượt chế độ Codex sẽ thất bại trước khi thread -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 -[Sử dụng máy tính của Codex](/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ố. +Sử dụng máy tính là tính năng riêng cho macOS và có thể cần 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ụ Sử dụng máy tính gốc. Xem +[Sử dụng máy tính với Codex](/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à khắc phục sự cố. Khi `computerUse.autoInstall` là true, OpenClaw có thể đăng ký marketplace -Codex Desktop tiêu chuẩn được đóng gói từ +Codex Desktop đóng gói 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 thread Codex cũ. +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 luồng PI hoặc Codex cũ. -## Công thức phổ biến +## Công thức thường dùng Codex cục bộ với transport stdio mặc định: @@ -692,7 +709,7 @@ Xác thực harness chỉ dùng Codex: } ``` -Phê duyệt Codex được guardian xem xét: +Phê duyệt Codex có guardian duyệt: ```json5 { @@ -737,89 +754,89 @@ App-server từ xa với header rõ ràng: } ``` -Việc chuyển đổi model vẫn do OpenClaw kiểm soát. Khi một phiên OpenClaw được gắn -vào một thread Codex hiện có, lượt tiếp theo lại gửi model OpenAI, provider, -chính sách phê duyệt, sandbox và bậc dịch vụ đang được chọn tới app-server. -Chuyển từ `openai/gpt-5.5` sang `openai/gpt-5.2` giữ ràng buộc thread nhưng yêu -cầu Codex tiếp tục với model mới được chọn. +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à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ữ 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. ## Lệnh Codex -Plugin được đóng gói đăng ký `/codex` làm lệnh slash đượ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 +mang 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: +Các dạng thường dùng: -- `/codex status` hiển thị kết nối app-server trực tiếp, model, tài khoản, giới hạn tốc độ, MCP server và skills. -- `/codex models` liệt kê các model app-server Codex trực tiếp. -- `/codex threads [filter]` liệt kê các thread Codex gần đây. -- `/codex resume ` gắn phiên OpenClaw hiện tại vào một thread Codex hiện có. -- `/codex compact` yêu cầu app-server Codex nén thread đã gắn. -- `/codex review` bắt đầu đánh giá gốc của Codex cho thread đã gắn. -- `/codex diagnostics [note]` hỏi trước khi gửi phản hồi chẩn đoán Codex cho thread đã gắn. -- `/codex computer-use status` kiểm tra Plugin Sử dụng máy tính đã cấu hình và MCP server. -- `/codex computer-use install` cài đặt Plugin Sử dụng máy tính đã cấu hình và tải lại các MCP server. +- `/codex status` hiển thị kết nối máy chủ ứng dụng trực tiếp, model, tài khoản, giới hạn tốc độ, máy chủ MCP và Skills. +- `/codex models` liệt kê các model 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 nén 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 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 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 MCP server của app-server Codex. -- `/codex skills` liệt kê skills của app-server Codex. +- `/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. ### 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 trò chuyện nơi vấn đề xảy ra: +Khi một tác nhân dựa trên Codex thực hiện đ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ả những gì bạn thấy. -2. Phê duyệt yêu cầu diagnostics một lần. Việc phê duyệt tạo tệp zip diagnostics 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 diagnostics đã hoàn tất vào báo cáo lỗi hoặc luồng hỗ trợ. + mô tả những gì 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. +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 từng 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` đã in ra - trong terminal. Lệnh trông giống như `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 nó cục bộ, + id luồng Codex và một dòng `Inspect locally` cho từng 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` + đã in trong terminal. Lệnh này trông như `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 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 được gắn mà không có đầy đủ gói diagnostics Gateway -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ó liên kết 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 diagnostics](/vi/gateway/diagnostics) -để biết đầy đủ mô hình quyền riêng tư và hành vi trong trò chuyện nhóm. +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 +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 trò chuyện nhóm. -Lõi OpenClaw cũng cung cấp `/diagnostics [note]` chỉ dành cho chủ sở hữu như lệnh -diagnostics Gateway chung. Lời nhắc phê duyệt của lệnh này hiển thị phần mở đầu -về dữ liệu nhạy cảm, liên kết đến [Xuất Diagnostics](/vi/gateway/diagnostics), và yêu cầu -`openclaw gateway diagnostics export --json` thông qua phê duyệt exec tường minh -mỗi lần. Không phê duyệt diagnostics 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 -ủy quyền 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 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 này 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 exec 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 được 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, chính +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 id luồng Codex trước khi phê duyệt. -Nếu `/diagnostics` được một chủ sở hữu gọi trong trò chuyện nhóm, OpenClaw giữ -kênh chia sẻ gọn gàng: nhóm chỉ nhận một thông báo ngắn, còn phần mở đầu -diagnostics, 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 tư. Nếu không có tuyến chủ sở hữu riêng tư, OpenClaw -từ chối yêu cầu nhóm và yêu cầu chủ sở hữu chạy lệnh này từ DM. +Nếu `/diagnostics` được một chủ sở hữu gọi trong cuộc trò chuyện nhóm, OpenClaw giữ cho +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 đến +chủ sở hữu qua tuyến phê duyệt riêng tư. Nếu không có tuyến riêng tư cho chủ sở hữu, +OpenClaw từ chối yêu cầu nhóm và yêu cầu chủ sở hữu chạy lệnh đó từ DM. -Tải lên Codex đã được phê duyệt gọi `feedback/upload` của app-server Codex và yêu cầu -app-server bao gồm nhật ký cho từng luồng được liệt kê và các luồng con Codex -đã sinh ra khi có. Việc tải lên đ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 app-server đó, lệnh trả về -lỗi app-server. Phản hồi diagnostics đã 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 ` +Lần tải Codex đã 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 đã liệt kê và các luồng con Codex +được sinh ra khi có sẵn. Việc tải lên đi qua đường phản hồi thông 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 -diagnostics Gateway cục bộ. +OpenClaw không in các id Codex đó. Lần 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 -đang được chọn vào app-server, và giữ bật lịch sử mở rộng. +`/codex resume` ghi cùng tệp liên kết sidecar mà harness dùng cho +các lượt thông thường. Ở tin nhắn tiếp theo, OpenClaw tiếp tục luồng Codex đó, truyền +model OpenClaw hiện được chọn vào máy chủ ứng dụng, và giữ bật lịch sử mở rộng. -### Kiểm tra một luồng Codex từ CLI +### Kiểm tra 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: @@ -828,20 +845,20 @@ gốc: codex resume ``` -Dùng lệnh 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 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 dẫn 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ê +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 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 dẫn 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 lệnh đó trực tiếp vào terminal. +`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 cuộc trò chuyện hiện tại hoặc -`/codex threads [filter]` cho các luồng app-server Codex gần đây, rồi chạy cùng -lệnh `codex resume` trong shell. +`/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 app-server Codex `0.125.0` hoặc mới hơ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 app-server 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` hoặc mới hơn. Từng +phương thức điều khiển được báo là `unsupported by this Codex app-server` nếu một +máy chủ ứng dụng trong tương lai hoặc tùy chỉnh không cung cấp phương thức JSON-RPC đó. ## Ranh giới hook @@ -849,154 +866,154 @@ 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 app-server Codex | Plugin tích hợp OpenClaw | Hành vi bộ chuyển đổi 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 mở rộng máy chủ ứng dụng Codex | Plugin được đóng gói cùng OpenClaw | Hành vi bộ chuyển đổi theo từng 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. Đối với cầu nối công cụ gốc và quyền được hỗ trợ, +hành vi Plugin OpenClaw. Với cầu nối công cụ gốc và quyền được hỗ trợ, OpenClaw chèn 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. +`UserPromptSubmit` vẫn là điều khiển cấp Codex; chúng không được cung cấp làm +hook Plugin OpenClaw trong hợp đồng v1. Đối với công cụ động OpenClaw, OpenClaw thực thi công cụ sau khi Codex yêu cầu -cuộc gọi, nên OpenClaw kích hoạt hành vi plugin và middleware mà nó sở hữu trong -bộ chuyển đổi harness. Đối 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 các 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 đó thông qua app-server hoặc -callback hook gốc. +lệnh gọi, nên OpenClaw kích hoạt hành vi Plugin và middleware mà nó sở hữu trong +bộ chuyển đổi harness. Đối 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 đó thông qua máy chủ ứng dụng hoặc callback +hook gốc. -Compaction và các phép chiếu vòng đời LLM đến từ thông báo app-server Codex -và trạng thái bộ chuyển đổi OpenClaw, không phải từ lệnh hook Codex gốc. +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à các 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. +`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 app-server `hook/started` và `hook/completed` gốc Codex được chiếu thành -sự kiện agent `codex_app_server.hook` để theo dõi quỹ đạo và gỡ lỗi. -Chúng không gọi hook plugin OpenClaw. +Thông báo `hook/started` và `hook/completed` máy chủ ứng dụng gốc Codex được +chiếu thành sự kiện tác nhân `codex_app_server.hook` cho 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 trong 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 nó quanh ranh giới đó. +Chế độ Codex không phải là PI với một lệnh gọi model khác bên dưới. Codex sở hữu nhiều hơn +vòng lặp model gốc, và OpenClaw điều chỉnh các bề mặt Plugin và phiên của nó +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 thông qua Codex | Được hỗ trợ | App-server 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 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 engine ngữ cảnh | Được hỗ trợ | Việc lắp ráp, nạp hoặc bảo trì sau lượt, và phối hợp compaction engine 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 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 ở chế độ Codex. | -| Cổng sửa đổi câu trả lời cuối | Được hỗ trợ thông 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ợ thông 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 app-server 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ợ thông 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 dẫn guardian hoặc phê duyệt người dùng bình thường. | -| Ghi lại quỹ đạo app-server | Được hỗ trợ | OpenClaw ghi lại yêu cầu nó đã gửi đến app-server và các thông báo app-server mà nó nhận. | +| Bề mặt | Hỗ trợ | Lý do | +| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Vòng lặp model 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 model. | +| 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 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ợ | Việc lắp ráp, nạp hoặc bảo trì sau lượt, và điều phối 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 bộ chuyển đổi | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, và `after_compaction` kích hoạt với payload chế độ Codex trung thực. | +| Cổng sửa đổi câu trả lời cuối | Được hỗ trợ thông 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 model trước khi hoàn tất. | +| Chặn hoặc quan sát shell, patch và MCP gốc | Được hỗ trợ thông 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ợ viết lại đối số. | +| Chính sách quyền gốc | Được hỗ trợ thông 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 hoặc phê duyệt người dùng thông thườ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 mà nó nhận. | Không được hỗ trợ trong runtime Codex v1: | 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 để thay thế đầu vào công cụ. | -| Lịch sử transcript gốc Codex có thể chỉnh sửa | Codex sở hữu lịch sử luồng gốc chuẩn tắc. 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 đột biến nội bộ không được hỗ trợ. | Thêm API app-server 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 Codex | Hook đó chuyển đổi các lần ghi transcript do OpenClaw sở hữu, không phải bản ghi công cụ gốc Codex. | Có thể phản chiếu các bản ghi đã chuyển đổi, nhưng việc viết lại chuẩn tắc cần hỗ trợ từ Codex. | -| Siêu dữ liệu Compaction gốc phong phú | OpenClaw quan sát điểm bắt đầu và hoàn tất Compaction, nhưng không nhận danh sách giữ/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 của 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 yêu cầu và thông báo app-server, 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 một sự kiện truy vết yêu cầu mô hình của Codex hoặc API gỡ lỗi. | +| Đột biến đối số công cụ gố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 Codex hỗ trợ hook/schema để thay thế đầu vào công cụ. | +| Lịch sử transcript 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 đột biến các phần nội bộ không được hỗ trợ. | Thêm API app-server Codex rõ ràng nếu cần can thiệp luồng gốc. | +| `tool_result_persist` cho bản ghi công cụ gốc của Codex | Hook đó chuyển đổi các lượt ghi transcript 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 đã chuyển đổi, nhưng việc viết lại chuẩn cần Codex hỗ trợ. | +| 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ữ/bỏ ổn định, chênh lệch token, hoặc tải trọng tóm tắt. | Cần các sự kiện compaction Codex phong phú hơn. | +| Can thiệp compaction | Các hook compaction OpenClaw hiện tại ở 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 gốc. | +| Ghi lại yêu cầu API mô hình từng byte một | OpenClaw có thể ghi lại các yêu cầu và thông báo app-server, nhưng lõi Codex tự xây dựng yêu cầu OpenAI API cuối cùng ở bên trong. | Cần một sự kiện theo dõi 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ụ, phương tiện và compaction -Bộ harness Codex chỉ thay đổi executor tác tử nhúng cấp thấp. +Harness Codex chỉ thay đổi trình thực thi tác tử 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 thông thường. -Relay hook gốc được cố ý thiết kế chung, nhưng hợp đồng hỗ trợ v1 -giới hạn trong các đường dẫn công cụ và quyền gốc Codex mà OpenClaw kiểm thử. Trong +Relay hook gốc được thiết kế có chủ đích là 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 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 +là một bề mặt plugin 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à chuyển tiếp đến guardian riêng hoặc đường dẫn phê duyệt của người dùng. +quyết định hook và chuyển tiếp sang đường dẫn bảo vệ hoặc phê duyệt người dùng riêng của nó. -Các yêu cầu khơi gợi 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"`. Các lời nhắc `request_user_input` của Codex được gửi lại tới -cuộc trò chuyện khởi nguồn, và tin nhắn theo sau tiếp theo trong hàng đợi sẽ trả lời yêu cầu -máy chủ gốc đó thay vì bị điều hướng như ngữ cảnh bổ sung. Các yêu cầu khơi gợi MCP khác -vẫn đóng lỗi an toàn. +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"`. Lời nhắc `request_user_input` của Codex được gửi lại về +cuộc trò chuyện gốc, và tin nhắn theo sau tiếp theo trong hàng đợi sẽ 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 MCP elicitation +khác vẫn đóng lỗi an toàn. -Điều hướng hàng đợi lượt chạy đang hoạt động ánh xạ vào `turn/steer` 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 lặng đã cấu hình và gửi chúng dưới dạng 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 cùng lượt, trong trường hợp đó +Điều hướng hàng đợi lượt đang hoạt động ánh xạ sang `turn/steer` của app-server Codex. Với +mặc định `messages.queue.mode: "steer"`, OpenClaw gom nhóm các tin nhắn trò chuyện đã xếp hàng +trong khoảng thời gian yên lặng được cấu hình và gửi chúng dưới dạng 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 Codex và compaction thủ công có thể từ chối điều hướng cùng lượt, trong trường hợp đó OpenClaw dùng hàng đợi theo sau khi chế độ đã chọn cho phép dự phòng. 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 +Khi mô hình đã chọn dùng harness Codex, compaction luồng gốc được ủy quyền cho app-server Codex. OpenClaw giữ một bản phản chiếu 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 -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 suy luận hoặc kế hoạch -Codex nhẹ khi app-server phát ra chúng. Hiện nay, OpenClaw chỉ -ghi nhận tín hiệu bắt đầu và hoàn tất Compaction gốc. Nó chưa hiển thị -tóm tắt Compaction dạng người đọc được hoặc danh sách có thể kiểm toán về những mục Codex -đã giữ sau Compaction. +phản chiếu bao gồm lời nhắc người dùng, văn bản trợ lý cuối cùng và các bản ghi suy luận +hoặc kế hoạch Codex nhẹ 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 gốc. Nó chưa hiển thị +bản tóm tắt compaction mà con người có thể đọc hoặc danh sách có thể kiểm tra về những mục Codex +đã giữ lại sau compaction. -Vì Codex sở hữu luồng gốc chuẩn tắc, `tool_result_persist` hiện không -viết lại các bản ghi kết quả công cụ gốc Codex. Nó chỉ áp dụng khi +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ụ 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à hiểu phương tiện -tiếp tục dùng các thiết lập nhà cung cấp/mô hình tương ứng như +Tạo phương tiện không yêu cầu PI. Hình ảnh, video, nhạc, PDF, TTS và hiểu +phương tiện tiếp tục dùng các cài đặt nhà cung cấp/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 nhà cung cấp `/model` thông thường:** điều đó là dự kiến đối với +**Codex không xuất hiện như một nhà cung cấp `/model` thông thường:** điều đó là bình thường 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 tham chiếu `codex/*` cũ), bật -`plugins.entries.codex.enabled` và kiểm tra liệu `plugins.allow` có loại trừ -`codex` hay không. +`plugins.entries.codex.enabled`, và kiểm tra xem `plugins.allow` có loại trừ +`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 khi kiểm thử. Một -runtime Codex bắt buộc hiện sẽ thất bại thay vì quay về PI trừ khi bạn -đặt rõ `agentRuntime.fallback: "pi"`. Khi app-server Codex được +`agentRuntime.id: "codex"` để buộc chọn Codex trong khi kiểm thử. Một +runtime Codex bị ép buộc hiện sẽ thất bại thay vì rơi về PI trừ khi bạn +đặt rõ `agentRuntime.fallback: "pi"`. Sau khi app-server Codex được chọn, lỗi của nó sẽ hiển thị trực tiếp mà không cần cấu hình dự phòng bổ sung. **app-server bị từ chối:** nâng cấp Codex để quá trình 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 bản có hậu tố build +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ì -sàn giao thức ổn định `0.125.0` là thứ OpenClaw kiểm thử. +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á. **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. +và đảm bảo app-server từ xa dùng 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 tử đó hoặc chọn một tham chiếu -`codex/*` cũ. Các tham chiếu `openai/gpt-*` thuần và nhà cung cấp khác vẫn đi theo -đường dẫn nhà cung cấp thông thường trong chế độ `auto`. Nếu bạn buộc `agentRuntime.id: "codex"`, mọi lượt nhúng -cho tác tử đó 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 đó là bình thường trừ khi bạn đã buộc +`agentRuntime.id: "codex"` cho tác tử đó hoặc chọn một tham chiếu `codex/*` +cũ. Các tham chiếu `openai/gpt-*` thuần và tham chiếu nhà cung cấp khác vẫn ở đường dẫn +nhà cung cấp thông thường trong chế độ `auto`. Nếu bạn buộc `agentRuntime.id: "codex"`, mọi lượt +nhúng cho tác tử đó 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 vẫn còn, khởi động lại +`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 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 rồi thử lại. @@ -1007,6 +1024,6 @@ hết thời gian chờ, khởi động lại Codex Computer Use hoặc Codex De - [Nhà cung cấp mô hình](/vi/concepts/model-providers) - [Nhà cung cấp OpenAI](/vi/providers/openai) - [Trạng thái](/vi/cli/status) -- [Hook Plugin](/vi/plugins/hooks) +- [Hook plugin](/vi/plugins/hooks) - [Tham chiếu cấu hình](/vi/gateway/configuration-reference) - [Kiểm thử](/vi/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/vi/providers/arcee.md b/docs/vi/providers/arcee.md index 945d8d9c1..f176228ac 100644 --- a/docs/vi/providers/arcee.md +++ b/docs/vi/providers/arcee.md @@ -1,43 +1,43 @@ --- read_when: - Bạn muốn sử dụng Arcee AI với OpenClaw - - Bạn cần biến môi trường chứa khóa API hoặc lựa chọn xác thực CLI -summary: Thiết lập Arcee AI (xác thực + chọn mô hình) + - Bạn cần biến môi trường khóa API hoặc tùy chọn xác thực CLI +summary: Thiết lập Arcee AI (xác thực + lựa chọn mô hình) title: Arcee AI x-i18n: - generated_at: "2026-04-29T23:04:55Z" + generated_at: "2026-05-02T23:39:10Z" model: gpt-5.5 provider: openai - source_hash: 54989e1706901fedc8a0c816ca7ee7f877fa4b973697540dd90cb9182420043f + source_hash: 622ee5288aec3ae0b45d3f06ba65fd6f972e07d7a7596ae3905d6fbdac0bf737 source_path: providers/arcee.md workflow: 16 --- -[Arcee AI](https://arcee.ai) cung cấp quyền truy cập vào họ mô hình mixture-of-experts Trinity thông qua API tương thích OpenAI. Tất cả mô hình Trinity đều được cấp phép Apache 2.0. +[Arcee AI](https://arcee.ai) cung cấp quyền truy cập vào họ mô hình mixture-of-experts Trinity thông qua API tương thích với OpenAI. Tất cả mô hình Trinity đều được cấp phép Apache 2.0. -Có thể truy cập các mô hình Arcee AI trực tiếp qua nền tảng Arcee hoặc thông qua [OpenRouter](/vi/providers/openrouter). +Có thể truy cập trực tiếp các mô hình Arcee AI qua nền tảng Arcee hoặc thông qua [OpenRouter](/vi/providers/openrouter). | Thuộc tính | Giá trị | | -------- | ------------------------------------------------------------------------------------- | -| Nhà cung cấp | `arcee` | -| Xác thực | `ARCEEAI_API_KEY` (trực tiếp) hoặc `OPENROUTER_API_KEY` (qua OpenRouter) | -| API | Tương thích OpenAI | +| Nhà cung cấp | `arcee` | +| Xác thực | `ARCEEAI_API_KEY` (trực tiếp) hoặc `OPENROUTER_API_KEY` (qua OpenRouter) | +| API | Tương thích với OpenAI | | URL cơ sở | `https://api.arcee.ai/api/v1` (trực tiếp) hoặc `https://openrouter.ai/api/v1` (OpenRouter) | ## Bắt đầu - + - + Tạo khóa API tại [Arcee AI](https://chat.arcee.ai/). - + ```bash openclaw onboard --auth-choice arceeai-api-key ``` - + ```json5 { agents: { @@ -51,17 +51,17 @@ Có thể truy cập các mô hình Arcee AI trực tiếp qua nền tảng Arce - + - + Tạo khóa API tại [OpenRouter](https://openrouter.ai/keys). - + ```bash openclaw onboard --auth-choice arceeai-openrouter ``` - + ```json5 { agents: { @@ -72,7 +72,7 @@ Có thể truy cập các mô hình Arcee AI trực tiếp qua nền tảng Arce } ``` - Cùng các tham chiếu mô hình đó hoạt động cho cả thiết lập trực tiếp và OpenRouter (ví dụ `arcee/trinity-large-thinking`). + Cùng các tham chiếu mô hình hoạt động cho cả thiết lập trực tiếp và OpenRouter (ví dụ `arcee/trinity-large-thinking`). @@ -82,7 +82,7 @@ Có thể truy cập các mô hình Arcee AI trực tiếp qua nền tảng Arce ## Thiết lập không tương tác - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -91,7 +91,7 @@ Có thể truy cập các mô hình Arcee AI trực tiếp qua nền tảng Arce ``` - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -103,38 +103,39 @@ Có thể truy cập các mô hình Arcee AI trực tiếp qua nền tảng Arce ## Danh mục tích hợp sẵn -OpenClaw hiện đi kèm danh mục Arcee được đóng gói sẵn này: +OpenClaw hiện đi kèm danh mục Arcee được đóng gói này: -| Tham chiếu mô hình | Tên | Đầu vào | Ngữ cảnh | Chi phí (vào/ra mỗi 1M) | Ghi chú | -| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- | -| `arcee/trinity-large-thinking` | Trinity Large Thinking | text | 256K | $0.25 / $0.90 | Mô hình mặc định; đã bật suy luận | -| `arcee/trinity-large-preview` | Trinity Large Preview | text | 128K | $0.25 / $1.00 | Đa dụng; 400B tham số, 13B hoạt động | -| `arcee/trinity-mini` | Trinity Mini 26B | text | 128K | $0.045 / $0.15 | Nhanh và tiết kiệm chi phí; gọi hàm | +| Tham chiếu mô hình | Tên | Đầu vào | Ngữ cảnh | Chi phí (vào/ra trên 1 triệu) | Ghi chú | +| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ------------------------------------------ | +| `arcee/trinity-large-thinking` | Trinity Large Thinking | văn bản | 256K | $0.25 / $0.90 | Mô hình mặc định; đã bật lập luận; không có công cụ | +| `arcee/trinity-large-preview` | Trinity Large Preview | văn bản | 128K | $0.25 / $1.00 | Đa dụng; 400B tham số, 13B hoạt động | +| `arcee/trinity-mini` | Trinity Mini 26B | văn bản | 128K | $0.045 / $0.15 | Nhanh và tiết kiệm chi phí; gọi hàm | -Preset onboarding đặt `arcee/trinity-large-thinking` làm mô hình mặc định. +Preset onboarding đặt `arcee/trinity-large-thinking` làm mô hình mặc định. Đây là mô hình chỉ hỗ trợ lập luận/văn bản và không hỗ trợ sử dụng công cụ hoặc gọi hàm. ## Tính năng được hỗ trợ -| Tính năng | Được hỗ trợ | -| --------------------------------------------- | ---------------------------- | -| Streaming | Có | -| Sử dụng công cụ / gọi hàm | Có | -| Đầu ra có cấu trúc (chế độ JSON và lược đồ JSON) | Có | -| Suy nghĩ mở rộng | Có (Trinity Large Thinking) | +| Tính năng | Được hỗ trợ | +| --------------------------------------------- | ------------------------------------------- | +| Streaming | Có | +| Sử dụng công cụ / gọi hàm | Tùy thuộc mô hình; không phải Trinity Large Thinking | +| Đầu ra có cấu trúc (chế độ JSON và lược đồ JSON) | Có | +| Suy nghĩ mở rộng | Có (Trinity Large Thinking) | - - Nếu Gateway chạy dưới dạng daemon (launchd/systemd), hãy bảo đảm `ARCEEAI_API_KEY` - (hoặc `OPENROUTER_API_KEY`) có sẵn cho tiến trình đó (ví dụ, trong + + Nếu Gateway chạy dưới dạng daemon (launchd/systemd), hãy đảm bảo `ARCEEAI_API_KEY` + (hoặc `OPENROUTER_API_KEY`) có sẵn cho tiến trình đó (ví dụ trong `~/.openclaw/.env` hoặc qua `env.shellEnv`). - - Khi sử dụng các mô hình Arcee qua OpenRouter, cùng các tham chiếu mô hình `arcee/*` sẽ áp dụng. + + Khi sử dụng các mô hình Arcee qua OpenRouter, cùng các tham chiếu mô hình `arcee/*` sẽ được áp dụng. OpenClaw xử lý định tuyến một cách minh bạch dựa trên lựa chọn xác thực của bạn. Xem - [tài liệu nhà cung cấp OpenRouter](/vi/providers/openrouter) để biết chi tiết cấu hình dành riêng cho OpenRouter. + [tài liệu nhà cung cấp OpenRouter](/vi/providers/openrouter) để biết chi tiết cấu hình + dành riêng cho OpenRouter. @@ -144,7 +145,7 @@ Preset onboarding đặt `arcee/trinity-large-thinking` làm mô hình mặc đ Truy cập các mô hình Arcee và nhiều mô hình khác thông qua một khóa API duy nhất. - + Chọn nhà cung cấp, tham chiếu mô hình và hành vi chuyển đổi dự phòng. diff --git a/docs/vi/reference/RELEASING.md b/docs/vi/reference/RELEASING.md index fcf3170ad..5568866ca 100644 --- a/docs/vi/reference/RELEASING.md +++ b/docs/vi/reference/RELEASING.md @@ -1,53 +1,49 @@ --- read_when: - - Đ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 chấp nhận gói - - Tìm quy ước đặ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 cho người vận hành, 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 đị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 tra chấp nhận gói + - Tìm 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 cho người vận hành, máy kiểm chứng, cách đặt tên phiên bản và nhịp độ title: Chính sách phát hành x-i18n: - generated_at: "2026-05-02T20:57:24Z" + generated_at: "2026-05-02T23:39:23Z" model: gpt-5.5 provider: openai - source_hash: 493cb8b42f0e15f3bf5f8fb9be7d01fd626f4f16db9ac0a85e6efa747ef12d12 + source_hash: ba316d1736eae8edd2fb0a71b9a3da345f8895c3b536e9a1f619718ea12fc851 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw có bốn luồng phát hành công khai: +OpenClaw có ba nhánh phát hành công khai: - ổn định: 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 -- alpha: các thẻ tiền phát hành được phát hành lên npm `alpha` - 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` -## Đặt tên phiên bản +## Cách đặt tên phiên bản - 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 ổn định: `YYYY.M.D-N` - Thẻ Git: `vYYYY.M.D-N` -- Phiên bản tiền phát hành alpha: `YYYY.M.D-alpha.N` - - Thẻ Git: `vYYYY.M.D-alpha.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 ổn định đã được thăng cấp hiện tại -- `alpha` nghĩa là mục tiêu cài đặt alpha hiện tại +- `latest` nghĩa là bản phát hành npm ổn định hiện đang đượ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 ổn định và 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 rõ ràng đến `latest`, hoặc thăng cấp một bản dựng beta đã được kiểm duyệt sau đó +- Các bản phát hành ổn định và 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 tới `latest` một cách rõ ràng, hoặc quảng bá một bản dựng beta đã được kiểm chứng 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/package trước, còn + 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 -- Bản ổn định chỉ theo sau sau khi beta mới nhất được xác thực -- Các maintainer 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 +- Bản ổn định 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 + từ `main` hiện tại, để việc xác thực phát hành và sửa lỗi không chặn phát triển mới trên `main` -- Nếu một thẻ beta đã được đẩy lên 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, maintainer 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 @@ -55,127 +51,131 @@ OpenClaw có bốn luồng phát hành công khai: ## Danh sách kiểm tra 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ý, công chứng, khôi phục dist-tag và chi tiết rollback khẩn cấp nằm trong +việc ký, công chứng, 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. -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 lên, - và xác nhận CI của `main` hiện tại đủ xanh để tạo nhánh từ đó. +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 hiện tại của `main` đủ 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 đến người dùng, commit, đẩy lên, rồi rebase/pull + `/changelog`, giữ các mục hướng tới người dùng, commit, đẩy lên, rồi rebase/kéo thêm một lần trước khi tạo nhánh. -3. Xem lại các bản ghi tương thích phát hành trong +3. Rà soát 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 nó - được giữ lại có chủ ý. -4. Tạo `release/YYYY.M.D` từ `main` hiện tại; không làm công việc phát hành thông thường + `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 + 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 thông 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 dùng chung phiên bản phát hành - và metadata tương thích, rồi chạy preflight cục bộ có tính quyết định: + `pnpm plugins:sync` để các gói Plugin có thể phát hành dùng chung phiên bản + phát hành và siêu dữ liệu tương thích, sau đó chạy preflight 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. + SHA nhánh phát hành đầy đủ 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 động tất cả kiểm thử tiền phát hành bằng `Full Release Validation` cho +7. Khởi động tất cả các bài 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, luồng, job workflow, - hồ sơ package, provider, hoặc danh sách cho phép model nhỏ nhất đã thất bại để - chứng minh bản sửa. Chỉ chạy lại umbrella đầy đủ khi bề mặt thay đổi khiến - bằng chứng trước đó không còn mới. -9. Với alpha hoặc beta, gắn thẻ `vYYYY.M.D-alpha.N` hoặc `vYYYY.M.D-beta.N`, rồi chạy `OpenClaw Release Publish` từ +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, làn, job workflow, + hồ sơ gói, 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 làm bằng chứng trước đó + không còn mới. +9. Đối 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 đó lên ClawHub sau, rồi thăng cấp artifact preflight OpenClaw npm đã 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-alpha.N`, `openclaw@alpha`, - `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 lên hoặc - đã phát hành cần sửa lỗi, 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 bản ổn định, chỉ tiếp tục sau khi beta hoặc release candidate đã được kiểm duyệt 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 artifact preflight thành công qua + phát hành tất cả cá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, 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 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 tiền phát hành đã được đẩy hoặc phát hành cần sửa lỗi, + 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 tiền phát hành cũ. +10. Đối với bản ổn định, chỉ tiếp tục sau khi beta hoặc release candidate đã được kiểm chứng có + bằng chứng xác thực bắt buộc. Việc phát hành npm ổn định cũng đi qua + `OpenClaw Release Publish`, tái sử dụng artifact preflight thành công thô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 tệp `.zip`, `.dmg`, `.dSYM.zip` đã đó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, E2E Telegram - published-npm độc lập tùy chọn khi bạn cần bằng chứng kênh sau phát hành, - thăng cấp dist-tag khi cần, ghi chú GitHub release/prerelease từ - phần `CHANGELOG.md` tương ứng đầy đủ, và các bước thông báo phát hành. + `.zip`, `.dmg`, `.dSYM.zip` đã đó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 sau phát hành npm, E2E Telegram độc lập + tùy chọn cho npm đã phát hành 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ú release/prerelease trên GitHub từ + toàn bộ phần `CHANGELOG.md` tương ứng, và các bước thông báo phát hành. ## Preflight phát hành -- 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ủ bên ngoài cổng kiểm tra `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 rộng hơn và ranh giới kiến trúc đều đạt bên 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 phẩm 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 root và trước khi gắn thẻ. Lệnh này cập nhật 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 bản dựng, và các khung nhật ký thay đổi 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 trạng thái; quy trình phát hành sẽ thất bại trước khi có bất kỳ thay đổi nào trong kho đăng ký nếu quên bước này. -- Chạy quy trình thủ công `Full Release Validation` trước khi phê duyệt phát hành để khởi chạy tất cả hộp kiểm thử trước phát hành từ một điểm vào. Quy trình này chấp nhận nhánh, thẻ hoặc SHA commit đầy đủ, kích hoạt `CI` thủ công, và kích hoạt `OpenClaw Release Checks` cho kiểm thử khói cài đặt, chấp nhận gói, các bộ kiểm thử đường phát hành Docker, trực tiếp/E2E, OpenWebUI, tương đương QA Lab, Matrix, và các luồng Telegram. Với `release_profile=full` và `rerun_group=all`, quy trình cũng chạy Telegram E2E cho gói với tạo phẩm `release-package-under-test` từ các kiểm tra phát hành. Cung cấp `npm_telegram_package_spec` sau khi phát hành khi cùng Telegram E2E đó 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 nên chạy ma trận gói/cập nhật của nó với gói npm đã giao thay vì tạo phẩm đượ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 phần xác thực khớp với một gói npm đã phát hành mà không bắt buộc chạy Telegram E2E. Ví dụ: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Chạy quy trình thủ công `Package Acceptance` khi bạn muốn có bằng chứng bổ sung 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@alpha`, `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/thẻ/SHA `package_ref` đáng tin cậy bằng bộ khung `workflow_ref` hiện tại; `source=url` cho một gói nén tar HTTPS bắt buộc có SHA-256; hoặc `source=artifact` cho một gói nén tar do lần chạy GitHub Actions khác tải lên. Quy trình phân giải ứng viên thành `package-under-test`, dùng lại bộ lập lịch phát hành Docker E2E với gói nén tar đó, và có thể chạy Telegram QA với cùng gói nén tar bằng `telegram_mode=mock-openai` hoặc `telegram_mode=live-frontier`. Khi các luồng Docker đã chọn bao gồm `published-upgrade-survivor`, tạo phẩm gói là ứng viên và `published_upgrade_survivor_baseline` chọn đường cơ sở đã phát hành. +- Chạy `pnpm check:test-types` trước bước kiểm tra sơ bộ phát hành để TypeScript trong 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 sơ bộ phát hành để các kiểm tra rộng hơn về chu trình import và ranh giới kiến trúc đề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 artifact phát hành `dist/*` dự kiến và bundle 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 ở root và trước khi gắn thẻ. Lệnh này cập nhật phiên bản các package Plugin có thể phát hành, metadata tương thích peer/API của OpenClaw, metadata build, và các stub changelog Plugin để khớp với phiên bản phát hành core. `pnpm plugins:sync:check` là chốt phát hành không làm 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 chạy tất cả hộp kiểm thử tiền phát hành từ một điểm vào. Workflow này 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 smoke cài đặt, chấp nhận package, các bộ kiểm thử đường dẫn phát hành Docker, live/E2E, OpenWebUI, đối sánh QA Lab, Matrix, và các lane Telegram. Với `release_profile=full` và `rerun_group=all`, workflow cũng chạy package Telegram E2E dựa trên artifact `release-package-under-test` từ các kiểm tra phát hành. Cung cấp `npm_telegram_package_spec` sau khi phát hành khi cùng Telegram E2E cũng cần chứng minh package 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 package/cập nhật của nó dựa trên package npm đã xuất xưởng 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 rằng việc xác thực khớp với một package npm đã phát hành mà không buộc chạy Telegram E2E. 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` để đóng gói một 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 dựa trên tarball đó, và có thể chạy Telegram QA dựa trên cùng tarball với `telegram_mode=mock-openai` hoặc `telegram_mode=live-frontier`. Khi các lane Docker được chọn bao gồm `published-upgrade-survivor`, artifact package 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` - Các hồ sơ phổ biến: - - `smoke`: các luồng cài đặt/kênh/tác tử, mạng Gateway, và tải lại cấu hình - - `package`: các luồng gói/cập nhật/plugin dùng trực tiếp tạo phẩm, không có OpenWebUI hoặc ClawHub trực tiếp - - `product`: hồ sơ gói cộng với các kênh MCP, dọn dẹp Cron/tác tử con, tìm kiếm web OpenAI, và OpenWebUI - - `full`: các phần đường phát hành Docker với OpenWebUI - - `custom`: lựa chọn chính xác `docker_lanes` cho một lần chạy lại tập trung -- Chạy trực tiếp quy trình thủ công `CI` khi bạn chỉ cần độ bao phủ CI bình thường đầy đủ cho ứng viên phát hành. Các lần kích hoạt CI thủ công bỏ qua phạm vi theo thay đổi và bắt buộc chạy các shard Linux Node, shard plugin đi kèm, hợp đồng kênh, tương thích Node 22, `check`, `check-additional`, kiểm thử khói bản dựng, kiểm tra tài liệu, Skills Python, Windows, macOS, Android, và các luồng i18n Control UI. + 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/cập nhật/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 + - `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 thông thường đầy đủ cho ứng viên phát hành. Dispatch CI thủ công bỏ qua phạm vi changed và buộc chạy các shard Linux Node, shard Plugin đóng gói, 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 lane 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 đo từ xa phát hành. Lệnh này chạy QA-lab qua một bộ nhận OTLP/HTTP cục bộ và xác minh tên span trace đã xuất, thuộc tính có giới hạn, và biên tập nội dung/mã định danh mà không cần Opik, Langfuse, hoặc bộ thu thập bên ngoài khác. +- 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 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 một collector bên ngoài khác. - Chạy `pnpm release:check` trước mọi bản phát hành đã gắn thẻ -- Chạy `OpenClaw Release Publish` cho chuỗi phát hành có thay đổi trạng thái sau khi thẻ đã tồn tại. Kích hoạt 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 đang cố ý chạy một sửa chữa tập trung. Quy trình này 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 đã tách ngoài của nó. -- Các kiểm tra phát hành hiện chạy trong một quy trình thủ công riêng: +- Chạy `OpenClaw Release Publish` cho chuỗi phát hành có thay đổi sau khi thẻ đã tồn tại. Dispatch workflow này 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 cố ý chạy một bả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 để package core không được phát hành trước các Plugin đã được externalize. +- Các 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 luồng tương đương mock QA Lab cùng với hồ sơ Matrix trực tiếp nhanh và luồng QA Telegram trước khi phê duyệt phát hành. Các luồng trực tiếp dùng môi trường `qa-live-shared`; Telegram cũng dùng các phiên thuê thông tin xác thực CI Convex. Chạy quy trình 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ê giao vận, phương tiện, và E2EE của Matrix chạy song song. -- Xác thực thời gian chạy 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, các quy trình này gọi trực tiếp quy trình tái sử dụng `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- Sự tách biệt này là có chủ ý: giữ đường phát hành npm thật ngắn, tất định, và tập trung vào tạo phẩm, trong khi các kiểm tra trực tiếp chậm hơn nằm trong luồng 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 dùng bí mật nên được kích hoạt qua `Full Release Validation` hoặc từ ref quy trình `main`/release để logic quy trình và bí mật vẫn được kiểm soát -- `OpenClaw Release Checks` chấp nhận nhánh, thẻ hoặc SHA commit đầy đủ miễn là commit đã phân giải có thể truy cập từ một nhánh OpenClaw hoặc thẻ phát hành -- Kiểm tra trước phát hành 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 quy trình hiện tại mà không yêu cầu thẻ đã được đẩy -- Cách dùng SHA đó chỉ dành cho xác thực và không thể được nâng thành phát hành thật -- Ở chế độ SHA, quy trình tổng hợp `v` chỉ cho kiểm tra siêu dữ liệu gói; phát hành thật vẫn yêu cầu thẻ phát hành thật -- Cả hai quy trình giữ đường phát hành và quảng bá thật trên các trình chạy do GitHub lưu trữ, trong khi đường xác thực không thay đổi trạng thái có thể dùng các trình chạy Linux Blacksmith lớn hơn -- Quy trình đó chạy +- `OpenClaw Release Checks` cũng chạy lane đối sánh 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 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 được, và tập trung vào artifact, trong khi các kiểm tra live chậm hơn ở lane 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 thông qua `Full Release Validation` hoặc từ workflow ref `main`/release để logic workflow và 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 đã phân giải có thể truy cập từ một nhánh OpenClaw hoặc thẻ phát hành +- Kiểm tra sơ bộ chỉ xác thực `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 đẩy +- Đường dẫn SHA đó chỉ dành cho xác thực và không thể được thăng cấp thành phát hành thật +- Ở chế độ SHA, workflow chỉ tổng hợp `v` cho kiểm tra metadata package; phát hành thật vẫn yêu cầu thẻ phát hành thật +- Cả hai workflow giữ đường dẫn phát hành và thăng cấp thật trên runner do GitHub host, trong khi đường dẫn xác thực không làm thay đổi dữ liệu có thể dùng các runner Linux Blacksmith lớn hơn +- Workflow đó chạy `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - bằng cả hai bí mật quy trình `OPENAI_API_KEY` và `ANTHROPIC_API_KEY` -- Kiểm tra trước phát hành npm không còn chờ luồng kiểm tra phát hành riêng biệt -- Chạy `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (hoặc thẻ beta/bản sửa lỗi tương ứng) trước khi phê duyệt + bằng cả hai secret workflow `OPENAI_API_KEY` và `ANTHROPIC_API_KEY` +- Kiểm tra sơ bộ phát hành npm không còn chờ lane 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 thẻ beta/correction 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/bản sửa lỗi tương ứng) để xác minh đường cài đặt kho đăng ký đã phát hành trong một tiền tố tạm thời mới -- Sau một lần 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 quá trình thiết lập ban đầu của gói đã cài đặt, thiết lập Telegram, và E2E Telegram thật với gói npm đã phát hành bằng nhóm thông tin xác thực Telegram thuê dùng chung. Các lần chạy cục bộ một lần của người bảo trì có thể bỏ các biến Convex và truyền trực tiếp ba thông tin xác thực môi trường `OPENCLAW_QA_TELEGRAM_*`. -- Người bảo trì có thể chạy cùng kiểm tra sau phát hành từ GitHub Actions qua quy trình thủ công `NPM Telegram Beta E2E`. Quy trình này cố ý chỉ chạy thủ công và không chạy ở mọi lần hợp nhất. -- Tự động hóa phát hành của người bảo trì hiện dùng quy trình kiểm tra trước rồi quảng bá: - - lần phát hành npm thật phải vượt qua một `preflight_run_id` npm thành công - - lần phát hành npm thật phải được kích hoạt 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 dùng `beta` - - phát hành npm ổn định có thể nhắm rõ `latest` qua đầu vào quy trình - - thay đổi dist-tag npm dựa trên token hiện nằm trong `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` vì lý do bảo mật, bởi vì `npm dist-tag add` vẫn cần `NPM_TOKEN` trong khi kho 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 thẻ chỉ nằm trên nhánh phát hành nhưng quy trình được kích hoạt từ `main`, đặt `public_release_branch=release/YYYY.M.D` + (hoặc phiên bản beta/correction 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 một bản 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 package đã cài đặt, thiết lập Telegram, và Telegram E2E thật dựa trên package npm đã phát hành bằng pool thông tin xác thực Telegram thuê dùng chung. 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_*`. +- 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`. 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 kiểm tra sơ bộ rồi thăng cấp: + - phát hành npm thật phải vượt qua một npm `preflight_run_id` 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 sơ bộ thành công + - phát hành npm ổn định mặc định là `beta` + - phát hành npm ổn định có thể nhắm rõ ràng tới `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` + 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ành cho 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` - 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 phát hành thật quảng bá các tạo phẩm đã chuẩn bị thay vì build lại chúng -- Đối với các bản phát hành sửa lỗi ổn định như `YYYY.M.D-N`, trình xác minh sau phát hành cũng kiểm tra cùng đường nâng cấp bằng tiền tố tạm thời 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 để các cài đặt toàn cục cũ ở lại gói nội dung ổn định gốc -- Kiểm tra trước phát hành npm sẽ thất bại theo hướng chặn trừ khi gói nén tar bao gồm cả `dist/control-ui/index.html` và phần nội dung `dist/control-ui/assets/` không rỗng để chúng ta không phát hành lại bảng điều khiển trình duyệt rỗng -- Xác minh sau phát hành cũng kiểm tra rằng các điểm vào plugin đã phát hành và siêu dữ liệu gói có mặt trong bố cục kho đăng ký đã cài đặt. Một bản phát hành giao thiếu nội dung thời gian chạy plugin sẽ làm trình xác minh sau phát hành thất bại và không thể được quảng bá lên `latest`. -- `pnpm test:install:smoke` cũng thực thi ngân sách `unpackedSize` của npm pack trên gói nén tar cập nhật ứng viên, để E2E trình cài đặt bắt được việc phình to gói ngoài ý muốn trước đường phát hành -- Nếu công việc phát hành chạm tới lập kế hoạch CI, bản kê thời gian của tiện ích mở rộng, hoặc ma trận kiểm thử tiện ích mở rộng, hãy tái tạo và rà soát các đầu ra ma trận `plugin-prerelease-extension-shard` do bộ lập kế hoạch sở hữu từ `.github/workflows/plugin-prerelease.yml` trước khi phê duyệt để ghi chú phát hành không mô tả bố cục CI lỗi thời -- Mức sẵn sàng của bản phát hành macOS ổn định cũng bao gồm các phần liên quan đến trình cập nhật: - - bản phát hành GitHub 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 tệp zip ổn định mới sau khi phát hành - - ứng dụng đã đóng gói phải giữ mã định danh gói không gỡ lỗi, URL nguồn cấp Sparkle không rỗng, và `CFBundleVersion` bằng hoặc cao hơn ngưỡng build Sparkle chuẩn cho phiên bản phát hành đó + - các đường dẫn phát hành thật thăng cấp artifact đã chuẩn bị thay vì build lại chúng +- 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 lỗi phát hành không thể âm thầm để các bản cài đặt global cũ ở payload ổn định gốc +- Kiểm tra sơ bộ phát hành npm thất bại đóng nếu tarball không chứa cả `dist/control-ui/index.html` và payload `dist/control-ui/assets/` không rỗng, để chúng ta không phát hành 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à metadata package có mặt 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 postpublish và không thể được thăng cấp lên `latest`. +- `pnpm test:install:smoke` cũng thực thi ngân sách `unpackedSize` của npm pack trên tarball cập nhật ứng viên, để installer e2e bắt được việc phình to gói 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 của Plugin, hoặc ma trận kiểm thử Plugin, hãy tạo lại và rà soát các output ma trận `plugin-prerelease-extension-shard` do planner sở hữu từ `.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 +- Mức 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 `.zip`, `.dmg`, và `.dSYM.zip` đã được đóng gói + - `appcast.xml` trên `main` phải trỏ tới zip ổn định mới sau khi phát hành + - app đã đó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 đó -## Hộp kiểm thử bản phát hành +## Hộp kiểm thử phát hành -`Full Release Validation` là cách người vận hành khởi chạy tất cả kiểm thử trước phát hành từ một điểm vào. Để có bằng chứng commit được ghim trên một nhánh thay đổi nhanh, hãy dùng trình trợ giúp để mọi quy trình con chạy từ một nhánh tạm thời cố định ở SHA mục tiêu: +`Full Release Validation` là cách các operator khởi chạy tất cả kiểm thử tiền phát hành từ một điểm vào. Để có bằng chứng commit đã ghim trên một nhánh thay đổi nhanh, dùng helper để mọi workflow con chạy từ một nhánh tạm cố định tại SHA đích: ```bash pnpm ci:full-release --sha ``` -Trình trợ giúp đẩy `release-ci/-...`, kích hoạt `Full Release Validation` từ nhánh đó với `ref=`, xác minh `headSha` của mọi quy trình 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 vô tình chứng minh một lần chạy con mới hơn của `main`. +Helper đẩy `release-ci/-...`, dispatch `Full Release Validation` từ nhánh đó với `ref=`, xác minh mọi workflow con có `headSha` khớp với mục tiêu, rồi xóa nhánh tạm. Đ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. -Để xác thực nhánh hoặc thẻ phát hành, chạy từ ref quy trình `main` đáng tin cậy và truyền nhánh hoặc thẻ phát hành làm `ref`: +Để xác thực nhánh phát hành hoặc thẻ, chạy workflow từ ref workflow `main` đáng tin cậy và truyền nhánh phát hành hoặc thẻ làm `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -187,47 +187,46 @@ 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, dispatch thủ công `CI` với +Quy trình làm việc phân giải ref mục tiêu, dispatch `CI` thủ công với `target_ref=`, dispatch `OpenClaw Release Checks`, và dispatch -package Telegram E2E độc lập khi `release_profile=full` với -`rerun_group=all` hoặc khi `npm_telegram_package_spec` được đặt. Sau đó `OpenClaw Release +Telegram E2E gói độ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 ra install smoke, kiểm tra phát hành đa hệ điều hành, phạm vi -kiểm thử live/E2E Docker theo release-path, Package Acceptance với Telegram package QA, QA Lab -parity, live Matrix, và live Telegram. Một lần chạy đầy đủ chỉ được chấp nhận khi -phần 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 thì nó bị bỏ qua -trừ khi một `npm_telegram_package_spec` đã phát hành được cung cấp. Phần tóm tắt -xác minh cuối cùng bao gồm bảng các job chậm nhất cho từng lần chạy child, để release -manager có thể thấy critical path hiện tại mà không cần tải log 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 hồ sơ stable và full, -artifact, và các handle rerun tập trung. -Các workflow child được dispatch 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 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 đá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 dispatch workflow, vì vậy hãy dùng -`pnpm ci:full-release --sha ` để tạo nhánh tạm thời đã ghim. +đường dẫn phát hành Docker live/E2E, Package Acceptance với QA gói Telegram, QA +Lab parity, Matrix live, và Telegram live. Một lần chạy đầy đủ chỉ được chấp +nhận khi bản tóm tắt `Full Release Validation` hiển thị `normal_ci` và +`release_checks` là thành công. Ở chế độ full/all, child `npm_telegram` cũng +phải thành công; ngoài full/all thì nó bị bỏ qua trừ khi đã cung cấp +`npm_telegram_package_spec` đã xuất bản. Bản tóm tắt trình xác minh cuối cùng +bao gồm các bảng job chậm nhất cho từng lần chạy child, để release manager có +thể thấy đường găng hiện tại mà không cần tải logs. +Xem [Xác thực phát hành đầy đủ](/vi/reference/full-release-validation) để biết ma +trận stage đầy đủ, tên job workflow chính xác, khác biệt giữa profile stable và +full, artifacts, và các handle rerun tập trung. +Các workflow child được dispatch từ ref tin cậy chạy `Full Release +Validation`, thường là `--ref main`, ngay cả khi `ref` mục tiêu 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; 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 di chuyển; SHA commit thô không thể là workflow dispatch refs, 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: -- `minimum`: đường dẫn OpenAI/core live và Docker quan trọng cho phát hành nhanh nhất +- `minimum`: đường dẫn live và Docker OpenAI/core quan trọng cho phát hành nhanh nhất - `stable`: minimum cộng thêm phạm vi provider/backend ổn định để phê duyệt phát hành -- `full`: stable cộng thêm phạm vi provider/media tư vấn rộng hơn +- `full`: stable cộng thêm phạm vi provider/media tư vấn rộng -`OpenClaw Release Checks` dùng ref workflow đáng tin cậy để phân giải ref đích -một lần dưới dạng `release-package-under-test` và tái sử dụng artifact đó trong cả -kiểm tra Docker theo release-path và Package Acceptance. Điều này giữ tất cả -box hướng 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 -chứng minh cài đặt package, onboarding, khởi động Gateway, và một lượt tác tử 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ể. +`OpenClaw Release Checks` dùng ref workflow tin cậy để phân giải ref mục tiêu +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ữ tất cả +box hướng tới gói trên cùng một bytes và tránh build gói lặp lại. +OpenAI install smoke đ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 chứng +minh cài đặt gói, onboarding, khởi động gateway, và một lượt agent 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 +cho phạm vi riêng theo model. -Dùng các biến thể này tùy theo giai đoạn phát hành: +Dùng các biến thể này tùy theo stage phát hành: ```bash # Validate an unpublished release candidate branch. @@ -257,41 +256,42 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Đừng dùng umbrella đầy đủ làm lần 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 child, job, lane Docker, hồ sơ package, 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 all-box trước đó -không còn mới. Verifier cuối cùng của umbrella kiểm tra lại các id lần chạy workflow child -đã ghi lại, vì vậy sau khi một workflow child được rerun thành công, chỉ rerun job cha -`Verify full validation` đã thất bại. +Không dùng umbrella đầy đủ làm lần 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 child, 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 toàn bộ box trước đó trở nên lỗi thời. Trình xác minh cuối cùng của +umbrella kiểm tra lại các id lần chạy workflow child đã ghi, vì vậy sau khi một +workflow child được rerun thành công, chỉ rerun job 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ần chạy -release-candidate thật, `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 release -box, và các nhóm phát hành hẹp hơn là `install-smoke`, `cross-os`, +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, 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ần chạy full/all -với `release_profile=full` dùng artifact package của release-checks. +Rerun `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 gói release-checks. ### Vitest -Box Vitest là workflow child `CI` thủ công. CI thủ công cố ý -bỏ qua phạm vi theo thay đổi và ép graph kiểm thử bình thường cho release -candidate: 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à Control UI i18n. +Box Vitest là workflow child `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 release candidate: Linux Node +shards, bundled-plugin shards, channel contracts, tương thích Node 22, `check`, +`check-additional`, build smoke, kiểm tra docs, Python skills, Windows, macOS, +Android, và i18n Control UI. -Dùng box này để trả lời "source tree có vượt qua toàn bộ bộ kiểm thử bình thường không?" -Nó không giống với xác thực sản phẩm theo release-path. Bằng chứng cần giữ: +Dùng box này để trả lời "source tree 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 lần chạy `CI` đã dispatch -- lần chạy `CI` xanh trên SHA đích chính xác +- bản tóm tắt `Full Release Validation` hiển thị URL lần chạy `CI` đã dispatch +- lần chạy `CI` xanh trên SHA mục tiêu chính xác - tên shard thất bại hoặc chậm từ các job 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 +- 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 xác định được nhưng -không cần các box Docker, QA Lab, live, đa hệ điều hành, hoặc package: +Chỉ chạy CI thủ công trực tiếp khi phát hành cần CI bình thường có tính xác định +nhưng không cần các box Docker, QA Lab, live, đa hệ điều hành, hoặc gói: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -300,17 +300,16 @@ 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 thông qua môi trường -Docker đã đóng package thay vì chỉ các kiểm thử cấp source. +`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 thông qua môi trường Docker +đóng gói thay vì chỉ kiểm thử cấp source. Phạm vi 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 dưới dạng shard install-smoke riêng +- install smoke đầy đủ với smoke cài đặt global Bun chậm được bật +- chuẩn bị/tái sử dụng image smoke Dockerfile gốc theo SHA mục tiêu, với các job QR, root/gateway, và installer/Bun smoke chạy dưới dạng install-smoke shards riêng - các lane E2E repository -- các chunk Docker theo release-path: `core`, `package-update-openai`, +- 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`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, @@ -318,91 +317,90 @@ Phạm vi Docker phát hành bao gồm: `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/gỡ Plugin bundled tách riêng +- các lane cài đặt/gỡ cài đặt bundled plugin được tách riêng `bundled-plugin-install-uninstall-0` đến `bundled-plugin-install-uninstall-23` -- các suite provider live/E2E và phạm vi model live Docker khi release checks - bao gồm các suite live +- bộ provider live/E2E và phạm vi model live Docker khi release checks bao gồm bộ live -Dùng artifact Docker trước khi rerun. Scheduler theo release-path tải lên -`.artifacts/docker-tests/` với log lane, `summary.json`, `failures.json`, -thời gian pha, JSON kế hoạch scheduler, và lệnh rerun. Để khôi phục 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 sẽ 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. +Dùng artifacts Docker trước khi rerun. Bộ lập lịch đường dẫn phát hành upload +`.artifacts/docker-tests/` với logs lane, `summary.json`, `failures.json`, thời +gian phase, JSON kế hoạch scheduler, và lệnh rerun. Để khôi phục tập trung, dùng +`docker_lanes=` trên workflow live/E2E tái sử dụng thay vì rerun +tất cả chunk phát hành. Các lệnh rerun được tạo bao gồm `package_artifact_run_id` +trước đó và input image Docker đã chuẩn bị khi có, vì vậy 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à gate phát hành -hành vi agentic và cấp kênh, tách biệt với Vitest và cơ chế package Docker. +Box QA Lab cũng là một phần của `OpenClaw Release Checks`. Đây là cổng phát +hành về hành vi agentic và cấp channel, tách biệt với cơ chế gói Vitest và +Docker. Phạm vi QA Lab phát hành bao gồm: -- lane mock parity so sánh lane candidate OpenAI với baseline Opus 4.6 - bằng agentic parity pack -- hồ sơ QA Matrix live nhanh dùng môi trường `qa-live-shared` -- lane QA Telegram live dùng lease credential Convex CI +- lane parity mock 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 credentials 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ữ 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ần chạy QA-Lab sharded thủ công thay vì lane quan trọng cho phát hành mặc định. +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 channel live không?" Giữ 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ần chạy QA-Lab thủ công chia shard thay vì lane mặc định quan trọng cho phát +hành. -### Package +### Gói -Box Package là gate sản phẩm có thể cài đặt. Nó được hỗ trợ bởi +Box Gói 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 package, ghi lại phiên bản package và SHA-256, và giữ ref harness -workflow tách biệt với ref source package. +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 source gói. -Các nguồn candidate được hỗ trợ: +Nguồn candidate đượ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, tag, hoặc SHA commit đầy đủ `package_ref` đáng tin cậy - với harness `workflow_ref` đã chọn +- `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, tag, hoặc SHA commit đầy đủ `package_ref` tin cậy với harness `workflow_ref` đã chọn - `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 một lần chạy GitHub Actions khác tải lên +- `source=artifact`: tái sử dụng một `.tgz` được upload bởi một lần chạy GitHub Actions khác -`OpenClaw Release Checks` chạy Package Acceptance với `source=artifact`, -artifact package phát hành đã chuẩn bị, `suite_profile=custom`, +`OpenClaw Release Checks` chạy 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`. Package Acceptance giữ migration, update, dọn dẹp -phụ thuộc Plugin lỗi thời, fixture Plugin offline, cập nhật Plugin, và Telegram -package QA trên cùng tarball đã phân giải. Ma trận upgrade bao phủ mọi baseline ổn định đã phát hành trên 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 tarball npm cục bộ có SHA hỗ trợ trước khi -publish. Đây là giải pháp thay thế gốc GitHub -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 OS, -nhưng xác thực sản phẩm package/update nên ưu tiên Package Acceptance. +phụ thuộc Plugin cũ, fixture Plugin offline, update Plugin, và QA gói Telegram +trên cùng một tarball đã phân giải. Ma trận upgrade bao phủ mọi baseline ổn định +đã xuất bản npm từ `2026.4.23` đến `latest`; dùng Package Acceptance với +`source=npm` cho candidate đã được phát hành, hoặc `source=ref`/`source=artifact` +cho tarball npm cục bộ có SHA hậu thuẫn trước khi publish. Đây là phương án +GitHub-native thay thế cho hầu hết phạm vi gói/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 đặc thù hệ điều hành, nhưng xác thực sản phẩm gói/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 -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/cập nhật Plugin, dọn dẹp bằng doctor, hoặc migration package đã phát hành. -Migration update đã phát hành toàn diện từ mọi package ổn định `2026.4.23+` là -workflow `Update Migration` thủ công riêng, không thuộc Full Release CI. +[Kiểm thử update và Plugin](/vi/help/testing-updates-plugins). Dùng checklist đó +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 đã xuất bản. Migration update đã xuất bản toàn diện từ mọi gói ổn định +`2026.4.23+` là workflow `Update Migration` thủ công riêng, không phải một phần +của Full Release CI. -Sự nới lỏng package-acceptance legacy được cố ý giới hạn theo 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 phát hành -lên npm: mục inventory QA private bị thiếu khỏi tarball, thiếu -`gateway install --wrapper`, thiếu file patch trong fixture git dẫn xuất từ tarball, -thiếu `update.channel` được lưu bền, vị trí install-record -Plugin legacy, thiếu lưu bền install-record marketplace, và migration metadata -config trong `plugins update`. Package `2026.4.26` đã phát hành có thể cảnh báo -về các file stamp metadata build cục bộ đã được ship. Các package sau đó -phải đáp ứng hợp đồng package hiện đại; những khoảng trống tương tự sẽ làm xác thực -phát hành thất bại. +Sự nới lỏng package-acceptance legacy được cố ý giới hạn thời gian. Các gói đến +`2026.4.25` có thể dùng đường dẫn tương thích cho các khoảng trống metadata đã +xuất bản lên npm: mục inventory QA riêng tư bị thiếu khỏi tarball, thiếu +`gateway install --wrapper`, thiếu patch files trong fixture git dẫn xuất từ +tarball, thiếu `update.channel` đã lưu, vị trí install-record Plugin legacy, +thiếu lưu install-record marketplace, và migration metadata config trong +`plugins update`. Gói `2026.4.26` đã xuất bản 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 về sau phải đáp ứng hợp đồng +gói hiện đại; cùng 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 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ế: +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: ```bash gh workflow run package-acceptance.yml \ @@ -414,34 +412,31 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -Các hồ sơ package phổ biến: +Các profile gói phổ biến: -- `smoke`: các lane cài đặt package/kênh/tác tử nhanh, mạng Gateway, và reload - config -- `package`: hợp đồng package cài đặt/update/Plugin không có ClawHub live; đây là mặc định - release-check -- `product`: `package` cộng thêm kênh MCP, dọn dẹp cron/subagent, tìm kiếm web OpenAI, - và OpenWebUI -- `full`: các chunk Docker theo release-path với OpenWebUI +- `smoke`: lane cài đặt gói/channel/agent nhanh, mạng gateway, và reload config +- `package`: hợp đồng cài đặt/update/gói Plugin không có ClawHub live; đây là mặc định của release-check +- `product`: `package` cộng thêm MCP channels, dọn dẹp cron/subagent, tìm kiếm web OpenAI, và OpenWebUI +- `full`: chunk đường dẫn phát hành Docker với OpenWebUI - `custom`: danh sách `docker_lanes` chính xác cho rerun tập trung -Để có bằng chứng Telegram cho ứng viên gói, bật `telegram_mode=mock-openai` hoặc -`telegram_mode=live-frontier` trên Package Acceptance. Workflow truyền tarball -`package-under-test` đã phân giải vào lane Telegram; workflow Telegram độc lập +Để có bằng chứng Telegram cho gói ứng viên, bật `telegram_mode=mock-openai` hoặc +`telegram_mode=live-frontier` trên Package Acceptance. Quy trình làm việc truyền tarball +`package-under-test` đã phân giải vào làn Telegram; quy trình làm việc Telegram độc lập vẫn chấp nhận một đặc tả 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 phát hành `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 đáng tin cậy theo thứ tự mà bản phát hành cần: +điều phối các quy trình làm việc trusted publisher theo thứ tự mà bản phát hành cần: -1. Check out 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 được từ `main` hoặc `release/*`. +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/*`. 3. Chạy `pnpm plugins:sync:check`. 4. Kích hoạt `Plugin NPM Release` với `publish_scope=all-publishable` và `ref=`. 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, npm dist-tag, và +6. Kích hoạt `OpenClaw NPM Release` với thẻ phát hành, npm dist-tag và `preflight_run_id` đã lưu. Ví dụ phát hành beta: @@ -454,17 +449,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Ví dụ phát hành alpha: - -```bash -gh workflow run openclaw-release-publish.yml \ - --ref release/YYYY.M.D \ - -f tag=vYYYY.M.D-alpha.N \ - -f preflight_run_id= \ - -f npm_dist_tag=alpha -``` - -Phát hành ổn định lên dist-tag beta mặc định: +Phát hành ổn định tới dist-tag beta mặc định: ```bash gh workflow run openclaw-release-publish.yml \ @@ -474,7 +459,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Thăng hạng ổn định trực tiếp lên `latest` là thao tác tường minh: +Thăng hạng ổn định trực tiếp lên `latest` là hành động tường minh: ```bash gh workflow run openclaw-release-publish.yml \ @@ -484,22 +469,22 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -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 có trọng tâm. Để sửa chữa một plugin đã chọn, truyền +Chỉ dùng các quy trình làm việc cấp thấp hơn `Plugin NPM Release` và `Plugin ClawHub Release` +cho công việc sửa chữa tập trung hoặc phát hành lại. Để sửa chữa một Plugin đã chọn, truyền `plugin_publish_scope=selected` và `plugins=@openclaw/name` cho -`OpenClaw Release Publish`, hoặc kích hoạt trực tiếp workflow con khi +`OpenClaw Release Publish`, hoặc kích hoạt trực tiếp quy trình làm việc con khi gói OpenClaw không được phát hành. -## Đầu vào workflow NPM +## Đầu vào quy trình làm việc NPM `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-alpha.1` hay `v2026.4.2-beta.1`; khi `preflight_only=true`, giá trị này cũng có thể là - SHA commit đầy đủ 40 ký tự hiện tại của nhánh workflow để chạy preflight chỉ xác thực -- `preflight_only`: `true` chỉ để xác thực/build/package, `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 tái sử dụng +- `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 quy trình làm việc cho preflight chỉ xác thực +- `preflight_only`: `true` cho chỉ xác thực/xây dựng/đóng 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 để quy trình làm việc tái sử dụng tarball đã chuẩn bị từ lần chạy preflight thành công - `npm_dist_tag`: thẻ đích npm cho đường dẫn phát hành; mặc định là `beta` @@ -510,66 +495,65 @@ gói OpenClaw không được phát hành. bắt buộc khi `publish_openclaw_npm=true` - `npm_dist_tag`: thẻ đích npm 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 có trọng tâm + 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 - workflow làm 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 quy trình làm việc + 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 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 bí mật - yêu cầu commit đã phân giải có thể truy cập được từ một nhánh OpenClaw hoặc +- `ref`: nhánh, thẻ hoặc SHA commit đầy đủ để 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 từ một nhánh OpenClaw hoặc thẻ phát hành. Quy tắc: -- Thẻ ổn định và thẻ sửa lỗi có thể phát hành lên `beta` hoặc `latest` -- Thẻ prerelease alpha chỉ có thể phát hành lên `alpha` -- Thẻ prerelease beta chỉ có thể phát hành lên `beta` +- Thẻ ổn định và thẻ sửa lỗi có thể phát hành tới `beta` hoặc `latest` +- Thẻ beta prerelease chỉ có thể phát hành tới `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 +- `OpenClaw Release Checks` và `Full Release Validation` luôn 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 siêu dữ liệu đó trước khi tiếp tục phát hành + quy trình làm việc xác minh siêu dữ liệu đó 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: +Khi cắt 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 workflow - để chạy thử workflow preflight chỉ xác thực + - 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 làm việc + để chạy thử khô chỉ xác thực cho quy trình làm việc 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 phạm vi kiểm thử live prompt cache, 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 - workflow `CI` thủ công trên ref phát hành thay vào đó + khi bạn chủ ý 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 phạm vi bao phủ live prompt cache, Docker, QA Lab, + Matrix và Telegram từ một quy trình làm việc thủ công +4. Nếu bạn chủ ý chỉ cần đồ thị kiểm thử thông thường có tính xác định, hãy chạy + quy trình làm việc `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; workflow này phát hành các plugin đã ngoại hóa lên npm + và `preflight_run_id` đã lưu; nó phát hành các Plugin đã ngoại hóa lên npm và ClawHub trước khi thăng hạng gói npm OpenClaw -7. Nếu bản phát hành được đưa lên `beta`, dùng workflow riêng tư +7. Nếu bản phát hành đã vào `beta`, dùng quy trình làm việc riêng tư `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` để thăng hạng phiên bản ổn định đó từ `beta` lên `latest` -8. Nếu bản phát hành cố ý được phát hành trực tiếp lên `latest` và `beta` - nên theo cùng bản build ổn định ngay lập tức, 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ự phục hồi theo lịch của workflow +8. Nếu bản phát hành chủ ý được phát hành trực tiếp lên `latest` và `beta` + nên trỏ ngay tới cùng bản dựng ổn định đó, hãy dùng cùng quy trình làm việc riêng tư + để trỏ cả hai dist-tag tới 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 -Việc thay đổi dist-tag nằm trong repo riêng tư vì lý do bảo mật do nó vẫn +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 phát hành trực tiếp và đường dẫn thăng hạng beta-trước -được ghi tài liệu và hiển thị với người vận hành. +đều được ghi tài liệu và hiển thị với người vận hành. -Nếu maintainer phải quay lại 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 nhân chính; giữ nó bên trong tmux giúp các lời nhắc, -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. +Nếu một maintainer phải fallback sang xác thực npm cục bộ, chỉ chạy bất kỳ lệnh CLI +1Password (`op`) nào 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 làm cho 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 diff --git a/docs/vi/web/control-ui.md b/docs/vi/web/control-ui.md index 4041928c3..8b143778f 100644 --- a/docs/vi/web/control-ui.md +++ b/docs/vi/web/control-ui.md @@ -6,20 +6,20 @@ sidebarTitle: Control UI summary: Giao diện điều khiển dựa trên trình duyệt cho Gateway (trò chuyện, nút, cấu hình) title: Giao diện điều khiển x-i18n: - generated_at: "2026-05-02T20:58:54Z" + generated_at: "2026-05-02T23:39:16Z" model: gpt-5.5 provider: openai - source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c + source_hash: 50bef807915f27406e19f1c6ca7d839a610d79ba79da85d7a78523400cbf9208 source_path: web/control-ui.md workflow: 16 --- -Giao diện điều khiển là một ứng dụng một trang **Vite + Lit** nhỏ được Gateway phục vụ: +Giao diện Điều khiển là một ứng dụng một trang nhỏ dùng **Vite + Lit** do Gateway phục vụ: - mặc định: `http://:18789/` - tiền tố tùy chọn: đặt `gateway.controlUi.basePath` (ví dụ: `/openclaw`) -Ứng dụng này giao tiếp **trực tiếp với Gateway WebSocket** trên cùng cổng. +Nó giao tiếp **trực tiếp với Gateway WebSocket** trên cùng cổng. ## Mở nhanh (cục bộ) @@ -34,15 +34,15 @@ Xác thực được cung cấp trong quá trình bắt tay WebSocket qua: - `connect.params.auth.token` - `connect.params.auth.password` - tiêu đề danh tính Tailscale Serve khi `gateway.auth.allowTailscale: true` -- tiêu đề danh tính trusted-proxy khi `gateway.auth.mode: "trusted-proxy"` +- tiêu đề danh tính proxy tin cậy khi `gateway.auth.mode: "trusted-proxy"` -Bảng cài đặt dashboard giữ một token cho phiên tab trình duyệt hiện tại và URL gateway đã chọn; mật khẩu không được lưu giữ. Onboarding thường tạo một token gateway cho xác thực bí mật dùng chung trong lần kết nối đầu tiên, nhưng xác thực bằng mật khẩu cũng hoạt động khi `gateway.auth.mode` là `"password"`. +Bảng cài đặt của bảng điều khiển lưu một token cho phiên tab trình duyệt hiện tại và URL gateway đã chọn; mật khẩu không được lưu lại. Quy trình thiết lập ban đầu thường tạo token gateway cho xác thực bí mật dùng chung ở lần kết nối đầu tiên, nhưng xác thực bằng mật khẩu cũng hoạt động khi `gateway.auth.mode` là `"password"`. -## Ghép nối thiết bị (kết nối đầu tiên) +## Ghép đôi thiết bị (kết nối đầu tiên) -Khi bạn kết nối tới Giao diện điều khiển từ một trình duyệt hoặc thiết bị mới, Gateway thường yêu cầu **phê duyệt ghép nối một lần**. Đây là một biện pháp bảo mật để ngăn truy cập trái phép. +Khi bạn kết nối tới Giao diện Điều khiển từ một trình duyệt hoặc thiết bị mới, Gateway thường yêu cầu **phê duyệt ghép đôi một lần**. Đây là biện pháp bảo mật để ngăn truy cập trái phép. -**Bạn sẽ thấy:** "đã ngắt kết nối (1008): cần ghép nối" +**Bạn sẽ thấy:** "đã ngắt kết nối (1008): yêu cầu ghép đôi" @@ -57,182 +57,184 @@ Khi bạn kết nối tới Giao diện điều khiển từ một trình duyệ -Nếu trình duyệt thử ghép nối lại với chi tiết xác thực đã thay đổi (vai trò/phạm vi/khóa công khai), yêu cầu đang chờ trước đó sẽ bị thay thế và một `requestId` mới được tạo. Chạy lại `openclaw devices list` trước khi phê duyệt. +Nếu trình duyệt thử lại việc ghép đôi với thông tin xác thực đã thay đổi (vai trò/phạm vi/khóa công khai), yêu cầu đang chờ trước đó sẽ bị thay thế và một `requestId` mới được tạo. Chạy lại `openclaw devices list` trước khi phê duyệt. -Nếu trình duyệt đã được ghép nối và bạn đổi trình duyệt đó từ quyền đọc sang quyền ghi/quản trị, việc này được coi là nâng cấp phê duyệt, không phải tự động kết nối lại âm thầm. OpenClaw giữ phê duyệt cũ còn hiệu lực, chặn lần kết nối lại với phạm vi rộng hơn, và yêu cầu bạn phê duyệt rõ ràng bộ phạm vi mới. +Nếu trình duyệt đã được ghép đôi và bạn đổi từ quyền đọc sang quyền ghi/quản trị, việc này được xem là nâng cấp phê duyệt, không phải tự động kết nối lại âm thầm. OpenClaw giữ phê duyệt cũ còn hiệu lực, chặn lần kết nối lại với phạm vi rộng hơn, và yêu cầu bạn phê duyệt rõ ràng bộ phạm vi mới. -Sau khi được phê duyệt, thiết bị sẽ được ghi nhớ và không cần phê duyệt lại trừ khi bạn thu hồi thiết bị bằng `openclaw devices revoke --device --role `. Xem [CLI thiết bị](/vi/cli/devices) để biết về xoay vòng và thu hồi token. +Sau khi được phê duyệt, thiết bị sẽ được ghi nhớ và không cần phê duyệt lại trừ khi bạn thu hồi bằng `openclaw devices revoke --device --role `. Xem [CLI Thiết bị](/vi/cli/devices) để biết về xoay vòng và thu hồi token. -- Kết nối trình duyệt local loopback trực tiếp (`127.0.0.1` / `localhost`) được tự động phê duyệt. -- Tailscale Serve có thể bỏ qua vòng ghép nối cho các phiên vận hành Giao diện điều khiển khi `gateway.auth.allowTailscale: true`, danh tính Tailscale được xác minh, và trình duyệt xuất trình danh tính thiết bị của nó. -- Liên kết Tailnet trực tiếp, kết nối trình duyệt LAN, và hồ sơ trình duyệt không có danh tính thiết bị vẫn yêu cầu phê duyệt rõ ràng. -- Mỗi hồ sơ trình duyệt tạo một ID thiết bị duy nhất, nên việc đổi trình duyệt hoặc xóa dữ liệu trình duyệt sẽ yêu cầu ghép nối lại. +- Các kết nối trình duyệt local loopback trực tiếp (`127.0.0.1` / `localhost`) được tự động phê duyệt. +- Tailscale Serve có thể bỏ qua vòng ghép đôi cho phiên vận hành Giao diện Điều khiển khi `gateway.auth.allowTailscale: true`, danh tính Tailscale xác minh thành công, và trình duyệt trình diện danh tính thiết bị của nó. +- Các bind Tailnet trực tiếp, kết nối trình duyệt LAN, và hồ sơ trình duyệt không có danh tính thiết bị vẫn yêu cầu phê duyệt rõ ràng. +- Mỗi hồ sơ trình duyệt tạo một ID thiết bị duy nhất, vì vậy đổi trình duyệt hoặc xóa dữ liệu trình duyệt sẽ yêu cầu ghép đôi lại. ## Danh tính cá nhân (cục bộ trong trình duyệt) -Giao diện điều khiển hỗ trợ danh tính cá nhân theo từng trình duyệt (tên hiển thị và ảnh đại diện) gắn vào tin nhắn gửi đi để quy kết tác giả trong các phiên dùng chung. Danh tính này nằm trong bộ nhớ trình duyệt, giới hạn trong hồ sơ trình duyệt hiện tại, và không được đồng bộ sang thiết bị khác hoặc lưu giữ phía máy chủ ngoài metadata tác giả transcript thông thường trên các tin nhắn bạn thực sự gửi. Xóa dữ liệu trang hoặc đổi trình duyệt sẽ đặt lại danh tính này về trống. +Giao diện Điều khiển hỗ trợ danh tính cá nhân theo từng trình duyệt (tên hiển thị và ảnh đại diện) được gắn vào tin nhắn gửi đi để ghi nhận tác giả trong các phiên dùng chung. Danh tính này nằm trong bộ nhớ trình duyệt, giới hạn trong hồ sơ trình duyệt hiện tại, và không được đồng bộ sang thiết bị khác hoặc lưu ở phía máy chủ ngoài siêu dữ liệu tác giả transcript thông thường trên các tin nhắn bạn thực sự gửi. Xóa dữ liệu trang hoặc đổi trình duyệt sẽ đặt lại thành trống. -Mẫu cục bộ trong trình duyệt tương tự áp dụng cho ghi đè ảnh đại diện của trợ lý. Ảnh đại diện trợ lý được tải lên chỉ phủ lên danh tính do gateway phân giải trong trình duyệt cục bộ và không bao giờ đi vòng qua `config.patch`. Trường cấu hình dùng chung `ui.assistant.avatar` vẫn khả dụng cho các client không phải UI ghi trực tiếp trường này (chẳng hạn như gateway theo script hoặc dashboard tùy chỉnh). +Mẫu cục bộ trong trình duyệt tương tự cũng áp dụng cho phần ghi đè ảnh đại diện của trợ lý. Ảnh đại diện trợ lý đã tải lên phủ lên danh tính do gateway phân giải chỉ trong trình duyệt cục bộ và không bao giờ đi vòng qua `config.patch`. Trường cấu hình dùng chung `ui.assistant.avatar` vẫn khả dụng cho các client không phải UI ghi trực tiếp trường này (chẳng hạn gateway theo script hoặc bảng điều khiển tùy chỉnh). ## Endpoint cấu hình runtime -Giao diện điều khiển lấy cài đặt runtime từ `/__openclaw/control-ui-config.json`. Endpoint đó được kiểm soát bởi cùng xác thực gateway như phần còn lại của bề mặt HTTP: trình duyệt chưa xác thực không thể lấy dữ liệu từ đó, và một lần lấy dữ liệu thành công yêu cầu token/mật khẩu gateway đã hợp lệ, danh tính Tailscale Serve, hoặc danh tính trusted-proxy. +Giao diện Điều khiển lấy cài đặt runtime từ `/__openclaw/control-ui-config.json`. Endpoint đó được bảo vệ bằng cùng cơ chế xác thực gateway như phần còn lại của bề mặt HTTP: trình duyệt chưa xác thực không thể lấy nó, và việc lấy thành công yêu cầu token/mật khẩu gateway đã hợp lệ, danh tính Tailscale Serve, hoặc danh tính proxy tin cậy. ## Hỗ trợ ngôn ngữ -Giao diện điều khiển có thể tự bản địa hóa trong lần tải đầu tiên dựa trên locale của trình duyệt. Để ghi đè sau đó, mở **Tổng quan -> Truy cập Gateway -> Ngôn ngữ**. Bộ chọn locale nằm trong thẻ Truy cập Gateway, không nằm dưới Giao diện. +Giao diện Điều khiển có thể tự bản địa hóa trong lần tải đầu tiên dựa trên locale của trình duyệt. Để ghi đè sau này, mở **Tổng quan -> Truy cập Gateway -> Ngôn ngữ**. Bộ chọn locale nằm trong thẻ Truy cập Gateway, không nằm dưới Giao diện. - Locale được hỗ trợ: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` - Các bản dịch không phải tiếng Anh được tải lười trong trình duyệt. -- Locale đã chọn được lưu trong bộ nhớ trình duyệt và dùng lại trong các lần truy cập sau. -- Khóa bản dịch bị thiếu sẽ quay về tiếng Anh. +- Locale đã chọn được lưu trong bộ nhớ trình duyệt và dùng lại ở các lần truy cập sau. +- Khóa dịch bị thiếu sẽ quay về tiếng Anh. -Bản dịch tài liệu được tạo cho cùng bộ locale không phải tiếng Anh, nhưng bộ chọn ngôn ngữ Mintlify tích hợp của trang tài liệu bị giới hạn ở các mã locale mà Mintlify chấp nhận. Tài liệu tiếng Thái (`th`) và tiếng Ba Tư (`fa`) vẫn được tạo trong repo xuất bản; chúng có thể chưa xuất hiện trong bộ chọn đó cho đến khi Mintlify hỗ trợ các mã này. +Bản dịch tài liệu được tạo cho cùng tập locale không phải tiếng Anh, nhưng bộ chọn ngôn ngữ Mintlify tích hợp của trang tài liệu bị giới hạn ở các mã locale mà Mintlify chấp nhận. Tài liệu tiếng Thái (`th`) và tiếng Ba Tư (`fa`) vẫn được tạo trong repo xuất bản; chúng có thể chưa xuất hiện trong bộ chọn đó cho tới khi Mintlify hỗ trợ các mã này. ## Chủ đề giao diện -Bảng Giao diện giữ các chủ đề Claw, Knot, và Dash tích hợp, cộng với một ô nhập tweakcn cục bộ trong trình duyệt. Để nhập một chủ đề, mở [chủ đề tweakcn](https://tweakcn.com/themes), chọn hoặc tạo một chủ đề, bấm **Chia sẻ**, rồi dán liên kết chủ đề đã sao chép vào Giao diện. Bộ nhập cũng chấp nhận URL registry `https://tweakcn.com/r/themes/`, URL trình chỉnh sửa như `https://tweakcn.com/editor/theme?theme=amethyst-haze`, đường dẫn tương đối `/themes/`, ID chủ đề thô, và tên chủ đề mặc định như `amethyst-haze`. +Bảng Giao diện giữ các chủ đề Claw, Knot và Dash tích hợp sẵn, cùng một khe nhập tweakcn cục bộ trong trình duyệt. Để nhập một chủ đề, mở [chủ đề tweakcn](https://tweakcn.com/themes), chọn hoặc tạo một chủ đề, bấm **Chia sẻ**, rồi dán liên kết chủ đề đã sao chép vào Giao diện. Trình nhập cũng chấp nhận URL registry `https://tweakcn.com/r/themes/`, URL trình chỉnh sửa như `https://tweakcn.com/editor/theme?theme=amethyst-haze`, đường dẫn tương đối `/themes/`, ID chủ đề thô, và tên chủ đề mặc định như `amethyst-haze`. -Các chủ đề đã nhập chỉ được lưu trong hồ sơ trình duyệt hiện tại. Chúng không được ghi vào cấu hình gateway và không đồng bộ giữa các thiết bị. Thay thế chủ đề đã nhập sẽ cập nhật một ô cục bộ; xóa ô đó sẽ chuyển chủ đề đang hoạt động về Claw nếu chủ đề đã nhập đang được chọn. +Chủ đề đã nhập chỉ được lưu trong hồ sơ trình duyệt hiện tại. Chúng không được ghi vào cấu hình gateway và không đồng bộ giữa các thiết bị. Thay thế chủ đề đã nhập sẽ cập nhật một khe cục bộ; xóa nó sẽ chuyển chủ đề đang hoạt động về Claw nếu chủ đề đã nhập đang được chọn. -## Những việc có thể làm (hiện nay) +## Hiện có thể làm gì (hôm nay) - - - Trò chuyện với mô hình qua Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Đàm thoại thông qua phiên realtime của trình duyệt. OpenAI dùng WebRTC trực tiếp, Google Live dùng token trình duyệt dùng một lần bị giới hạn qua WebSocket, và các Plugin giọng nói realtime chỉ backend dùng kênh chuyển tiếp của Gateway. Kênh chuyển tiếp giữ thông tin xác thực nhà cung cấp trên Gateway trong khi trình duyệt stream PCM từ micrô qua RPC `talk.realtime.relay*` và gửi lệnh gọi công cụ `openclaw_agent_consult` ngược qua `chat.send` cho mô hình OpenClaw lớn hơn đã cấu hình. - - Stream lệnh gọi công cụ + thẻ đầu ra công cụ trực tiếp trong Trò chuyện (sự kiện tác tử). + + - Chat với model qua Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). + - Đọc chính tả vào trình soạn Chat bằng STT phía máy chủ (`chat.transcribeAudio`). Trình duyệt ghi một đoạn micro ngắn và gửi tới Gateway, nơi chạy pipeline phiên âm `tools.media.audio` đã cấu hình và trả về văn bản nháp mà không làm lộ thông tin xác thực nhà cung cấp cho trình duyệt. + - Nói chuyện qua các phiên realtime trong trình duyệt. OpenAI dùng WebRTC trực tiếp, Google Live dùng token trình duyệt dùng một lần có giới hạn qua WebSocket, và các plugin thoại realtime chỉ chạy backend dùng truyền tải chuyển tiếp của Gateway. Bộ chuyển tiếp giữ thông tin xác thực nhà cung cấp trên Gateway trong khi trình duyệt stream PCM micro qua các RPC `talk.realtime.relay*` và gửi các lệnh gọi công cụ `openclaw_agent_consult` ngược qua `chat.send` cho model OpenClaw lớn hơn đã cấu hình. + - Stream lệnh gọi công cụ + thẻ đầu ra công cụ trực tiếp trong Chat (sự kiện agent). - - Kênh: trạng thái kênh tích hợp cộng với kênh Plugin đóng gói/bên ngoài, đăng nhập QR, và cấu hình theo từng kênh (`channels.status`, `web.login.*`, `config.patch`). + - Kênh: trạng thái kênh tích hợp sẵn cùng kênh plugin đi kèm/bên ngoài, đăng nhập QR, và cấu hình theo từng kênh (`channels.status`, `web.login.*`, `config.patch`). - Instance: danh sách hiện diện + làm mới (`system-presence`). - - Phiên: danh sách + ghi đè theo từng phiên cho mô hình/thinking/fast/verbose/trace/reasoning (`sessions.list`, `sessions.patch`). - - Giấc mơ: trạng thái dreaming, nút bật/tắt, và trình đọc Nhật ký giấc mơ (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + - Phiên: danh sách + ghi đè model/thinking/fast/verbose/trace/reasoning theo từng phiên (`sessions.list`, `sessions.patch`). + - Giấc mơ: trạng thái dreaming, nút bật/tắt, và trình đọc Nhật ký Giấc mơ (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - Công việc Cron: liệt kê/thêm/sửa/chạy/bật/tắt + lịch sử chạy (`cron.*`). + - Cron job: liệt kê/thêm/sửa/chạy/bật/tắt + lịch sử chạy (`cron.*`). - Skills: trạng thái, bật/tắt, cài đặt, cập nhật khóa API (`skills.*`). - - Node: danh sách + khả năng (`node.list`). - - Phê duyệt exec: chỉnh sửa danh sách cho phép gateway hoặc node + chính sách hỏi cho `exec host=gateway/node` (`exec.approvals.*`). + - Node: danh sách + capability (`node.list`). + - Phê duyệt exec: sửa allowlist gateway hoặc node + chính sách hỏi cho `exec host=gateway/node` (`exec.approvals.*`). - Xem/sửa `~/.openclaw/openclaw.json` (`config.get`, `config.set`). - - Áp dụng + khởi động lại kèm xác thực (`config.apply`) và đánh thức phiên hoạt động cuối cùng. - - Các thao tác ghi bao gồm bộ bảo vệ base-hash để tránh ghi đè các chỉnh sửa đồng thời. - - Các thao tác ghi (`config.set`/`config.apply`/`config.patch`) kiểm tra trước việc phân giải SecretRef đang hoạt động cho các ref trong payload cấu hình đã gửi; ref đang hoạt động đã gửi nhưng không phân giải được sẽ bị từ chối trước khi ghi. - - Schema + kết xuất biểu mẫu (`config.schema` / `config.schema.lookup`, bao gồm `title` / `description` của trường, gợi ý UI khớp, tóm tắt con trực tiếp, metadata tài liệu trên các node đối tượng lồng nhau/wildcard/mảng/composition, cộng với schema Plugin + kênh khi khả dụng); trình chỉnh sửa JSON thô chỉ khả dụng khi snapshot có khả năng vòng lặp thô an toàn. - - Nếu snapshot không thể vòng lặp văn bản thô một cách an toàn, Giao diện điều khiển buộc dùng chế độ Biểu mẫu và tắt chế độ Thô cho snapshot đó. - - "Đặt lại về đã lưu" của trình chỉnh sửa JSON thô giữ nguyên hình dạng do tác giả thô tạo ra (định dạng, chú thích, bố cục `$include`) thay vì kết xuất lại một snapshot đã làm phẳng, nên các chỉnh sửa bên ngoài vẫn tồn tại sau khi đặt lại khi snapshot có thể vòng lặp an toàn. - - Giá trị đối tượng SecretRef có cấu trúc được kết xuất chỉ đọc trong ô nhập văn bản biểu mẫu để ngăn vô tình làm hỏng đối tượng thành chuỗi. + - Áp dụng + khởi động lại với xác thực (`config.apply`) và đánh thức phiên hoạt động gần nhất. + - Ghi dữ liệu có cơ chế bảo vệ bằng base-hash để tránh ghi đè các chỉnh sửa đồng thời. + - Các thao tác ghi (`config.set`/`config.apply`/`config.patch`) kiểm tra trước việc phân giải SecretRef đang hoạt động cho các ref trong payload cấu hình đã gửi; các ref đang hoạt động đã gửi nhưng không phân giải được sẽ bị từ chối trước khi ghi. + - Schema + hiển thị biểu mẫu (`config.schema` / `config.schema.lookup`, bao gồm `title` / `description` của trường, gợi ý UI khớp, tóm tắt con trực tiếp, siêu dữ liệu tài liệu trên node object/wildcard/array/composition lồng nhau, cộng với schema plugin + kênh khi có); trình chỉnh sửa JSON thô chỉ khả dụng khi snapshot có thể round-trip thô an toàn. + - Nếu một snapshot không thể round-trip văn bản thô một cách an toàn, Giao diện Điều khiển buộc dùng chế độ Biểu mẫu và tắt chế độ Thô cho snapshot đó. + - Trình chỉnh sửa JSON thô "Đặt lại về bản đã lưu" giữ nguyên hình dạng do người dùng viết thô (định dạng, chú thích, bố cục `$include`) thay vì render lại một snapshot đã làm phẳng, nên các chỉnh sửa bên ngoài vẫn tồn tại sau khi đặt lại khi snapshot có thể round-trip an toàn. + - Các giá trị object SecretRef có cấu trúc được render chỉ đọc trong ô nhập văn bản của biểu mẫu để tránh vô tình làm hỏng object thành chuỗi. - - - Gỡ lỗi: snapshot trạng thái/sức khỏe/mô hình + nhật ký sự kiện + lệnh gọi RPC thủ công (`status`, `health`, `models.list`). - - Log: theo dõi trực tiếp log tệp gateway với lọc/xuất (`logs.tail`). - - Cập nhật: chạy cập nhật package/git + khởi động lại (`update.run`) với báo cáo khởi động lại, sau đó thăm dò `update.status` sau khi kết nối lại để xác minh phiên bản gateway đang chạy. + + - Gỡ lỗi: snapshot trạng thái/sức khỏe/model + nhật ký sự kiện + lệnh gọi RPC thủ công (`status`, `health`, `models.list`). + - Nhật ký: tail trực tiếp nhật ký tệp gateway với lọc/xuất (`logs.tail`). + - Cập nhật: chạy cập nhật package/git + khởi động lại (`update.run`) với báo cáo khởi động lại, rồi poll `update.status` sau khi kết nối lại để xác minh phiên bản gateway đang chạy. - - - Với công việc cô lập, mặc định gửi thông báo tóm tắt. Bạn có thể chuyển sang không gửi nếu muốn các lần chạy chỉ nội bộ. - - Các trường kênh/mục tiêu xuất hiện khi thông báo được chọn. - - Chế độ Webhook dùng `delivery.mode = "webhook"` với `delivery.to` được đặt thành một URL webhook HTTP(S) hợp lệ. - - Với công việc phiên chính, các chế độ gửi webhook và không gửi đều khả dụng. - - Điều khiển chỉnh sửa nâng cao bao gồm xóa sau khi chạy, xóa ghi đè tác tử, tùy chọn cron exact/stagger, ghi đè mô hình/thinking của tác tử, và nút bật/tắt gửi theo nỗ lực tối đa. - - Xác thực biểu mẫu hiển thị nội tuyến với lỗi cấp trường; giá trị không hợp lệ sẽ tắt nút lưu cho đến khi được sửa. - - Đặt `cron.webhookToken` để gửi token bearer chuyên dụng; nếu bỏ qua thì webhook được gửi không có tiêu đề xác thực. - - Phương án dự phòng không được khuyến nghị: công việc legacy đã lưu với `notify: true` vẫn có thể dùng `cron.webhook` cho đến khi được di chuyển. + + - Với job cô lập, mặc định phân phối là thông báo tóm tắt. Bạn có thể chuyển sang không gửi nếu muốn các lần chạy chỉ dùng nội bộ. + - Các trường kênh/đích xuất hiện khi chọn thông báo. + - Chế độ Webhook dùng `delivery.mode = "webhook"` với `delivery.to` đặt thành một URL webhook HTTP(S) hợp lệ. + - Với job phiên chính, chế độ phân phối webhook và không gửi đều khả dụng. + - Điều khiển chỉnh sửa nâng cao gồm xóa sau khi chạy, xóa ghi đè agent, tùy chọn cron chính xác/rải đều, ghi đè model/thinking của agent, và bật/tắt phân phối best-effort. + - Xác thực biểu mẫu hiển thị inline với lỗi theo từng trường; giá trị không hợp lệ sẽ tắt nút lưu cho đến khi được sửa. + - Đặt `cron.webhookToken` để gửi một bearer token riêng; nếu bỏ qua, webhook sẽ được gửi không kèm tiêu đề xác thực. + - Dự phòng không khuyến nghị: các job legacy đã lưu với `notify: true` vẫn có thể dùng `cron.webhook` cho đến khi được di trú. -## Hành vi trò chuyện +## Hành vi Chat - - - `chat.send` là **không chặn**: nó xác nhận ngay bằng `{ runId, status: "started" }` và phản hồi được truyền qua các sự kiện `chat`. - - Tải lên trong trò chuyện chấp nhận hình ảnh cùng các tệp không phải video. Hình ảnh giữ đường dẫn hình ảnh gốc; các tệp khác được lưu dưới dạng phương tiện được quản lý và hiển thị trong lịch sử dưới dạng liên kết tệp đính kèm. - - Gửi lại với cùng `idempotencyKey` trả về `{ status: "in_flight" }` khi đang chạy, và `{ status: "ok" }` sau khi hoàn tất. - - Phản hồi `chat.history` được giới hạn kích thước để bảo đảm an toàn cho UI. Khi các mục bản ghi quá lớn, Gateway có thể cắt bớt các trường văn bản dài, bỏ qua các khối siêu dữ liệu nặng, và thay thế thông điệp quá khổ bằng một phần giữ chỗ (`[chat.history omitted: message too large]`). - - Hình ảnh do trợ lý/tạo sinh được lưu bền vững dưới dạng tham chiếu phương tiện được quản lý và được phục vụ lại qua các URL phương tiện Gateway đã xác thực, nên việc tải lại không phụ thuộc vào việc payload hình ảnh base64 thô còn nằm trong phản hồi lịch sử trò chuyện. - - `chat.history` cũng loại bỏ khỏi văn bản trợ lý hiển thị các thẻ chỉ thị nội tuyến chỉ dùng cho hiển thị (ví dụ `[[reply_to_*]]` và `[[audio_as_voice]]`), payload XML gọi công cụ dạng văn bản thuần (bao gồm `...`, `...`, `...`, `...`, và các khối gọi công cụ đã bị cắt bớt), cũng như các token điều khiển mô hình ASCII/toàn chiều bị rò rỉ, và bỏ qua các mục trợ lý mà toàn bộ văn bản hiển thị chỉ là token im lặng chính xác `NO_REPLY` / `no_reply`. - - Trong khi một lượt gửi đang hoạt động và khi làm mới lịch sử cuối cùng, chế độ xem trò chuyện giữ các thông điệp người dùng/trợ lý cục bộ lạc quan hiển thị nếu `chat.history` tạm thời trả về một snapshot cũ hơn; bản ghi chuẩn sẽ thay thế các thông điệp cục bộ đó khi lịch sử Gateway bắt kịp. - - `chat.inject` thêm một ghi chú trợ lý vào bản ghi phiên và phát một sự kiện `chat` cho các cập nhật chỉ dành cho UI (không có lượt chạy agent, không gửi qua kênh). - - Bộ chọn mô hình và suy nghĩ ở tiêu đề trò chuyện vá phiên hoạt động ngay lập tức thông qua `sessions.patch`; chúng là các ghi đè phiên bền vững, không phải tùy chọn gửi chỉ áp dụng cho một lượt. - - Gõ `/new` trong Giao diện điều khiển tạo và chuyển sang cùng phiên bảng điều khiển mới như Trò chuyện mới. Gõ `/reset` giữ cơ chế đặt lại tại chỗ rõ ràng của Gateway cho phiên hiện tại. - - Bộ chọn mô hình trò chuyện yêu cầu chế độ xem mô hình đã cấu hình của Gateway. Nếu có `agents.defaults.models`, danh sách cho phép đó sẽ điều khiển bộ chọn. Nếu không, bộ chọn hiển thị các mục `models.providers.*.models` rõ ràng cùng các nhà cung cấp có xác thực dùng được. Toàn bộ danh mục vẫn có sẵn qua RPC gỡ lỗi `models.list` với `view: "all"`. - - Khi báo cáo sử dụng phiên Gateway mới cho thấy áp lực ngữ cảnh cao, khu vực trình soạn trò chuyện hiển thị thông báo ngữ cảnh và, ở các mức Compaction được khuyến nghị, một nút thu gọn chạy đường dẫn Compaction phiên thông thường. Các snapshot token cũ bị ẩn cho đến khi Gateway báo cáo lại mức sử dụng mới. + + - `chat.send` là **không chặn**: nó xác nhận ngay với `{ runId, status: "started" }` và phản hồi được truyền qua các sự kiện `chat`. + - `chat.transcribeAudio` là trình trợ giúp đọc chính tả một lần cho bản nháp Chat. Nó nhận âm thanh base64 do trình duyệt ghi, giữ dữ liệu tải lên dưới giới hạn khung WebSocket của Gateway, ghi một tệp cục bộ tạm thời, chạy phiên âm âm thanh bằng khả năng hiểu phương tiện với cấu hình Gateway đang hoạt động, trả về `{ text, provider, model }`, rồi xóa tệp tạm thời. Nó không tạo lượt chạy agent và tách biệt với Talk thời gian thực. + - Nội dung tải lên trong Chat chấp nhận hình ảnh cùng các tệp không phải video. Hình ảnh giữ đường dẫn ảnh gốc; các tệp khác được lưu dưới dạng phương tiện được quản lý và hiển thị trong lịch sử dưới dạng liên kết tệp đính kèm. + - Gửi lại với cùng `idempotencyKey` sẽ trả về `{ status: "in_flight" }` khi đang chạy, và `{ status: "ok" }` sau khi hoàn tất. + - Phản hồi `chat.history` được giới hạn kích thước để đảm bảo an toàn cho UI. Khi các mục bản ghi quá lớn, Gateway có thể cắt bớt các trường văn bản dài, bỏ qua các khối siêu dữ liệu nặng, và thay thế các tin nhắn quá khổ bằng một placeholder (`[chat.history omitted: message too large]`). + - Hình ảnh do trợ lý tạo ra được lưu bền vững dưới dạng tham chiếu phương tiện được quản lý và được phục vụ lại qua các URL phương tiện Gateway đã xác thực, nên việc tải lại không phụ thuộc vào việc payload hình ảnh base64 thô còn nằm trong phản hồi lịch sử chat. + - `chat.history` cũng loại bỏ các thẻ chỉ thị nội tuyến chỉ dùng để hiển thị khỏi văn bản trợ lý nhìn thấy được (ví dụ `[[reply_to_*]]` và `[[audio_as_voice]]`), payload XML gọi công cụ dạng văn bản thuần (bao gồm `...`, `...`, `...`, `...`, và các khối gọi công cụ bị cắt ngắn), cũng như các token điều khiển mô hình ASCII/toàn chiều bị rò rỉ, và bỏ qua các mục trợ lý có toàn bộ văn bản nhìn thấy được chỉ là token im lặng chính xác `NO_REPLY` / `no_reply`. + - Trong khi một lượt gửi đang hoạt động và khi làm mới lịch sử cuối cùng, chế độ xem chat giữ các tin nhắn người dùng/trợ lý lạc quan cục bộ hiển thị nếu `chat.history` tạm thời trả về một ảnh chụp cũ hơn; bản ghi chuẩn sẽ thay thế các tin nhắn cục bộ đó khi lịch sử Gateway bắt kịp. + - `chat.inject` nối thêm một ghi chú trợ lý vào bản ghi phiên và phát một sự kiện `chat` cho các cập nhật chỉ dành cho UI (không có lượt chạy agent, không gửi qua kênh). + - Bộ chọn mô hình và suy luận trong tiêu đề chat vá phiên đang hoạt động ngay lập tức thông qua `sessions.patch`; chúng là các ghi đè phiên bền vững, không phải tùy chọn gửi chỉ áp dụng cho một lượt. + - Nhập `/new` trong Control UI sẽ tạo và chuyển sang cùng một phiên bảng điều khiển mới như New Chat. Nhập `/reset` giữ thao tác đặt lại tại chỗ rõ ràng của Gateway cho phiên hiện tại. + - Bộ chọn mô hình chat yêu cầu chế độ xem mô hình đã cấu hình của Gateway. Nếu có `agents.defaults.models`, danh sách cho phép đó sẽ điều khiển bộ chọn. Nếu không, bộ chọn hiển thị các mục `models.providers.*.models` rõ ràng cùng các nhà cung cấp có xác thực dùng được. Toàn bộ danh mục vẫn có sẵn thông qua RPC gỡ lỗi `models.list` với `view: "all"`. + - Khi báo cáo sử dụng phiên Gateway mới cho thấy áp lực ngữ cảnh cao, vùng soạn chat hiển thị thông báo ngữ cảnh và, ở các mức Compaction được khuyến nghị, một nút thu gọn chạy đường dẫn Compaction phiên bình thường. Các ảnh chụp token cũ bị ẩn cho đến khi Gateway báo cáo mức sử dụng mới trở lại. - - Chế độ trò chuyện thoại sử dụng một nhà cung cấp giọng nói thời gian thực đã đăng ký. Cấu hình OpenAI bằng `talk.provider: "openai"` cộng với `talk.providers.openai.apiKey`, hoặc cấu hình Google bằng `talk.provider: "google"` cộng với `talk.providers.google.apiKey`; cấu hình nhà cung cấp thời gian thực Voice Call vẫn có thể được tái sử dụng làm phương án dự phòng. Trình duyệt không bao giờ nhận khóa API nhà cung cấp tiêu chuẩn. OpenAI nhận một bí mật máy khách Realtime tạm thời cho WebRTC. Google Live nhận một token xác thực Live API dùng một lần có ràng buộc cho phiên WebSocket trình duyệt, với chỉ dẫn và khai báo công cụ được Gateway khóa vào token. Các nhà cung cấp chỉ cung cấp cầu nối thời gian thực phía backend sẽ chạy qua truyền tải chuyển tiếp Gateway, để thông tin xác thực và socket nhà cung cấp vẫn ở phía máy chủ trong khi âm thanh trình duyệt đi qua các RPC Gateway đã xác thực. Lời nhắc phiên Realtime được Gateway lắp ráp; `talk.realtime.session` không chấp nhận ghi đè chỉ dẫn do bên gọi cung cấp. + + Chế độ Talk sử dụng một nhà cung cấp giọng nói thời gian thực đã đăng ký. Cấu hình OpenAI với `talk.provider: "openai"` cộng với `talk.providers.openai.apiKey`, hoặc cấu hình Google với `talk.provider: "google"` cộng với `talk.providers.google.apiKey`; cấu hình nhà cung cấp thời gian thực Voice Call vẫn có thể được tái sử dụng làm phương án dự phòng. Trình duyệt không bao giờ nhận khóa API nhà cung cấp tiêu chuẩn. OpenAI nhận một bí mật ứng dụng khách Realtime tạm thời cho WebRTC. Google Live nhận token xác thực Live API bị ràng buộc dùng một lần cho phiên WebSocket trình duyệt, với hướng dẫn và khai báo công cụ được Gateway khóa vào token. Các nhà cung cấp chỉ cung cấp cầu nối thời gian thực phía backend sẽ chạy qua transport chuyển tiếp của Gateway, nên thông tin xác thực và socket của nhà cung cấp vẫn ở phía máy chủ trong khi âm thanh trình duyệt đi qua các RPC Gateway đã xác thực. Prompt phiên Realtime được Gateway lắp ráp; `talk.realtime.session` không chấp nhận ghi đè hướng dẫn do bên gọi cung cấp. - Trong trình soạn Trò chuyện, điều khiển Trò chuyện thoại là nút sóng cạnh nút đọc chính tả bằng micrô. Khi Trò chuyện thoại bắt đầu, hàng trạng thái của trình soạn hiển thị `Connecting Talk...`, rồi `Talk live` khi âm thanh đã kết nối, hoặc `Asking OpenClaw...` khi một lệnh gọi công cụ thời gian thực đang tham vấn mô hình lớn hơn đã cấu hình thông qua `chat.send`. + Trong trình soạn Chat, điều khiển Talk là nút hình sóng bên cạnh nút đọc chính tả bằng micrô. Khi Talk bắt đầu, hàng trạng thái của trình soạn hiển thị `Connecting Talk...`, sau đó là `Talk live` khi âm thanh đã kết nối, hoặc `Asking OpenClaw...` trong khi một lệnh gọi công cụ thời gian thực đang tham vấn mô hình lớn hơn đã cấu hình thông qua `chat.send`. - Kiểm thử khói live cho maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` xác minh trao đổi SDP WebRTC trình duyệt của OpenAI, thiết lập WebSocket trình duyệt bằng token ràng buộc của Google Live, và bộ điều hợp trình duyệt chuyển tiếp Gateway với phương tiện micrô giả. Lệnh chỉ in trạng thái nhà cung cấp và không ghi log bí mật. + Kiểm thử khói trực tiếp dành cho maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` xác minh trao đổi SDP WebRTC trình duyệt OpenAI, thiết lập WebSocket trình duyệt bằng token ràng buộc Google Live, và adapter trình duyệt chuyển tiếp Gateway với phương tiện micrô giả. Lệnh chỉ in trạng thái nhà cung cấp và không ghi nhật ký bí mật. - - - Nhấp **Dừng** (gọi `chat.abort`). - - Khi một lượt chạy đang hoạt động, các phản hồi tiếp theo thông thường sẽ được đưa vào hàng đợi. Nhấp **Điều hướng** trên một thông điệp đang xếp hàng để chèn phản hồi tiếp theo đó vào lượt đang chạy. - - Gõ `/stop` (hoặc các cụm hủy độc lập như `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) để hủy ngoài băng. + + - Nhấp **Stop** (gọi `chat.abort`). + - Khi một lượt chạy đang hoạt động, các lượt theo dõi bình thường sẽ được xếp hàng. Nhấp **Steer** trên một tin nhắn đã xếp hàng để chèn lượt theo dõi đó vào lượt đang chạy. + - Nhập `/stop` (hoặc các cụm từ hủy độc lập như `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) để hủy ngoài luồng. - `chat.abort` hỗ trợ `{ sessionKey }` (không có `runId`) để hủy tất cả lượt chạy đang hoạt động cho phiên đó. - + - Khi một lượt chạy bị hủy, văn bản trợ lý một phần vẫn có thể được hiển thị trong UI. - - Gateway lưu bền vững văn bản trợ lý một phần đã bị hủy vào lịch sử bản ghi khi có đầu ra đã được đệm. - - Các mục được lưu bền vững bao gồm siêu dữ liệu hủy để bên tiêu thụ bản ghi có thể phân biệt phần hủy bỏ một phần với đầu ra hoàn tất bình thường. + - Gateway lưu bền vững văn bản trợ lý một phần đã hủy vào lịch sử bản ghi khi có đầu ra đã được đệm. + - Các mục đã lưu bao gồm siêu dữ liệu hủy để người tiêu thụ bản ghi có thể phân biệt phần hủy một phần với đầu ra hoàn tất bình thường. ## Cài đặt PWA và web push -Giao diện điều khiển đi kèm một `manifest.webmanifest` và một service worker, nên các trình duyệt hiện đại có thể cài đặt nó dưới dạng một PWA độc lập. Web Push cho phép Gateway đánh thức PWA đã cài đặt bằng thông báo ngay cả khi tab hoặc cửa sổ trình duyệt không mở. +Control UI đi kèm một `manifest.webmanifest` và một service worker, nên các trình duyệt hiện đại có thể cài đặt nó như một PWA độc lập. Web Push cho phép Gateway đánh thức PWA đã cài đặt bằng thông báo ngay cả khi tab hoặc cửa sổ trình duyệt không mở. | Bề mặt | Chức năng | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | Manifest PWA. Trình duyệt đề xuất "Cài đặt ứng dụng" khi có thể truy cập. | +| `ui/public/manifest.webmanifest` | Manifest PWA. Trình duyệt đề xuất "Install app" khi truy cập được. | | `ui/public/sw.js` | Service worker xử lý các sự kiện `push` và lượt nhấp thông báo. | -| `push/vapid-keys.json` (trong thư mục trạng thái OpenClaw) | Cặp khóa VAPID được tự động tạo dùng để ký payload Web Push. | -| `push/web-push-subscriptions.json` | Các endpoint đăng ký trình duyệt đã lưu bền vững. | +| `push/vapid-keys.json` (trong thư mục trạng thái OpenClaw) | Cặp khóa VAPID tự tạo dùng để ký payload Web Push. | +| `push/web-push-subscriptions.json` | Các endpoint đăng ký trình duyệt đã được lưu bền vững. | -Ghi đè cặp khóa VAPID thông qua biến môi trường trên tiến trình Gateway khi bạn muốn ghim khóa (cho triển khai nhiều máy chủ, xoay vòng bí mật, hoặc kiểm thử): +Ghi đè cặp khóa VAPID thông qua biến môi trường trên tiến trình Gateway khi bạn muốn cố định khóa (cho triển khai nhiều máy chủ, luân phiên bí mật, hoặc kiểm thử): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT` (mặc định là `mailto:openclaw@localhost`) -Giao diện điều khiển sử dụng các phương thức Gateway có giới hạn phạm vi này để đăng ký và kiểm thử đăng ký trình duyệt: +Control UI sử dụng các phương thức Gateway được giới hạn theo phạm vi này để đăng ký và kiểm thử đăng ký trình duyệt: - `push.web.vapidPublicKey` — lấy khóa công khai VAPID đang hoạt động. -- `push.web.subscribe` — đăng ký một `endpoint` cùng `keys.p256dh`/`keys.auth`. +- `push.web.subscribe` — đăng ký một `endpoint` cùng với `keys.p256dh`/`keys.auth`. - `push.web.unsubscribe` — xóa một endpoint đã đăng ký. -- `push.web.test` — gửi thông báo kiểm thử đến đăng ký của bên gọi. +- `push.web.test` — gửi thông báo kiểm thử tới đăng ký của bên gọi. -Web Push độc lập với đường dẫn chuyển tiếp APNS của iOS (xem [Cấu hình](/vi/gateway/configuration) để biết push dựa trên chuyển tiếp) và phương thức `push.test` hiện có, vốn nhắm đến ghép đôi di động gốc. +Web Push độc lập với đường dẫn chuyển tiếp APNS iOS (xem [Cấu hình](/vi/gateway/configuration) cho push dựa trên chuyển tiếp) và phương thức `push.test` hiện có, vốn nhắm tới ghép đôi di động gốc. ## Nhúng được lưu trữ -Thông điệp trợ lý có thể kết xuất nội dung web được lưu trữ trực tiếp bằng shortcode `[embed ...]`. Chính sách sandbox iframe được điều khiển bởi `gateway.controlUi.embedSandbox`: +Tin nhắn trợ lý có thể kết xuất nội dung web được lưu trữ nội tuyến bằng shortcode `[embed ...]`. Chính sách sandbox iframe được điều khiển bởi `gateway.controlUi.embedSandbox`: - + Tắt thực thi script bên trong nội dung nhúng được lưu trữ. - - Cho phép nội dung nhúng tương tác trong khi vẫn giữ cô lập origin; đây là mặc định và thường đủ cho các trò chơi/widget trình duyệt độc lập. + + Cho phép nội dung nhúng tương tác trong khi vẫn giữ cách ly origin; đây là mặc định và thường đủ cho các trò chơi/widget trình duyệt tự chứa. - - Thêm `allow-same-origin` bên trên `allow-scripts` cho các tài liệu cùng site cố ý cần đặc quyền mạnh hơn. + + Thêm `allow-same-origin` bên trên `allow-scripts` cho các tài liệu cùng site có chủ ý cần đặc quyền mạnh hơn. @@ -249,14 +251,14 @@ Ví dụ: ``` -Chỉ dùng `trusted` khi tài liệu được nhúng thực sự cần hành vi cùng origin. Với hầu hết trò chơi và canvas tương tác do agent tạo, `scripts` là lựa chọn an toàn hơn. +Chỉ dùng `trusted` khi tài liệu được nhúng thực sự cần hành vi cùng origin. Với hầu hết trò chơi do agent tạo và canvas tương tác, `scripts` là lựa chọn an toàn hơn. -URL nhúng `http(s)` tuyệt đối bên ngoài vẫn bị chặn theo mặc định. Nếu bạn chủ ý muốn `[embed url="https://..."]` tải các trang bên thứ ba, hãy đặt `gateway.controlUi.allowExternalEmbedUrls: true`. +Các URL nhúng `http(s)` tuyệt đối bên ngoài vẫn bị chặn theo mặc định. Nếu bạn chủ ý muốn `[embed url="https://..."]` tải các trang bên thứ ba, hãy đặt `gateway.controlUi.allowExternalEmbedUrls: true`. -## Độ rộng thông điệp trò chuyện +## Chiều rộng tin nhắn chat -Các thông điệp trò chuyện được nhóm sử dụng max-width mặc định dễ đọc. Các triển khai màn hình rộng có thể ghi đè mà không cần vá CSS đi kèm bằng cách đặt `gateway.controlUi.chatMessageMaxWidth`: +Các tin nhắn chat được nhóm dùng max-width mặc định dễ đọc. Các triển khai trên màn hình rộng có thể ghi đè mà không cần vá CSS đi kèm bằng cách đặt `gateway.controlUi.chatMessageMaxWidth`: ```json5 { @@ -268,12 +270,12 @@ Các thông điệp trò chuyện được nhóm sử dụng max-width mặc đ } ``` -Giá trị được xác thực trước khi đến trình duyệt. Các giá trị được hỗ trợ bao gồm độ dài và phần trăm thuần như `960px` hoặc `82%`, cùng các biểu thức độ rộng có ràng buộc `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, và `fit-content(...)`. +Giá trị được xác thực trước khi tới trình duyệt. Các giá trị được hỗ trợ bao gồm chiều dài và phần trăm thuần như `960px` hoặc `82%`, cộng với các biểu thức chiều rộng bị ràng buộc `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, và `fit-content(...)`. -## Truy cập tailnet (khuyến nghị) +## Truy cập tailnet (được khuyến nghị) - + Giữ Gateway trên loopback và để Tailscale Serve proxy nó bằng HTTPS: ```bash @@ -284,16 +286,16 @@ Giá trị được xác thực trước khi đến trình duyệt. Các giá tr - `https:///` (hoặc `gateway.controlUi.basePath` đã cấu hình của bạn) - Theo mặc định, các yêu cầu Serve của Giao diện điều khiển/WebSocket có thể xác thực qua header định danh Tailscale (`tailscale-user-login`) khi `gateway.auth.allowTailscale` là `true`. OpenClaw xác minh định danh bằng cách phân giải địa chỉ `x-forwarded-for` với `tailscale whois` và khớp nó với header, và chỉ chấp nhận các yêu cầu này khi yêu cầu đi vào loopback với các header `x-forwarded-*` của Tailscale. Với các phiên vận hành Giao diện điều khiển có định danh thiết bị trình duyệt, đường dẫn Serve đã xác minh này cũng bỏ qua vòng ghép đôi thiết bị; trình duyệt không có thiết bị và kết nối vai trò node vẫn đi theo các kiểm tra thiết bị thông thường. Đặt `gateway.auth.allowTailscale: false` nếu bạn muốn yêu cầu thông tin xác thực bí mật dùng chung rõ ràng ngay cả với lưu lượng Serve. Sau đó dùng `gateway.auth.mode: "token"` hoặc `"password"`. + Theo mặc định, các yêu cầu Control UI/WebSocket Serve có thể xác thực qua header định danh Tailscale (`tailscale-user-login`) khi `gateway.auth.allowTailscale` là `true`. OpenClaw xác minh định danh bằng cách phân giải địa chỉ `x-forwarded-for` với `tailscale whois` và khớp nó với header, và chỉ chấp nhận các yêu cầu này khi yêu cầu đi vào loopback với các header `x-forwarded-*` của Tailscale. Đối với phiên vận hành Control UI có định danh thiết bị trình duyệt, đường dẫn Serve đã xác minh này cũng bỏ qua vòng ghép đôi thiết bị; các trình duyệt không có thiết bị và kết nối vai trò node vẫn tuân theo các kiểm tra thiết bị bình thường. Đặt `gateway.auth.allowTailscale: false` nếu bạn muốn yêu cầu thông tin xác thực bí mật dùng chung rõ ràng ngay cả với lưu lượng Serve. Sau đó dùng `gateway.auth.mode: "token"` hoặc `"password"`. - Với đường dẫn định danh Serve bất đồng bộ đó, các lần xác thực thất bại cho cùng IP máy khách và phạm vi xác thực được tuần tự hóa trước khi ghi giới hạn tốc độ. Vì vậy, các lần thử lại sai đồng thời từ cùng trình duyệt có thể hiển thị `retry later` ở yêu cầu thứ hai thay vì hai lỗi không khớp thuần chạy song song. + Với đường dẫn định danh Serve bất đồng bộ đó, các lần xác thực thất bại cho cùng một IP ứng dụng khách và phạm vi xác thực được tuần tự hóa trước khi ghi giới hạn tốc độ. Vì vậy, các lần thử lại sai đồng thời từ cùng trình duyệt có thể hiển thị `retry later` ở yêu cầu thứ hai thay vì hai lỗi không khớp thuần túy chạy song song. - Xác thực Serve không cần token giả định máy chủ gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin có thể chạy trên máy chủ đó, hãy yêu cầu xác thực token/mật khẩu. + Xác thực Serve không dùng token giả định rằng máy chủ gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin cậy có thể chạy trên máy chủ đó, hãy yêu cầu xác thực bằng token/mật khẩu. - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` @@ -302,28 +304,28 @@ Giá trị được xác thực trước khi đến trình duyệt. Các giá tr - `http://:18789/` (hoặc `gateway.controlUi.basePath` đã cấu hình của bạn) - Dán bí mật dùng chung khớp vào cài đặt UI (được gửi dưới dạng `connect.params.auth.token` hoặc `connect.params.auth.password`). + Dán bí mật dùng chung tương ứng vào phần cài đặt UI (được gửi dưới dạng `connect.params.auth.token` hoặc `connect.params.auth.password`). ## HTTP không an toàn -Nếu bạn mở bảng điều khiển qua HTTP thuần (`http://` hoặc `http://`), trình duyệt chạy trong **ngữ cảnh không an toàn** và chặn WebCrypto. Theo mặc định, OpenClaw **chặn** kết nối Giao diện điều khiển không có định danh thiết bị. +Nếu bạn mở bảng điều khiển qua HTTP thuần (`http://` hoặc `http://`), trình duyệt chạy trong **ngữ cảnh không an toàn** và chặn WebCrypto. Theo mặc định, OpenClaw **chặn** các kết nối Control UI không có định danh thiết bị. Các ngoại lệ đã được ghi tài liệu: -- tương thích HTTP không an toàn chỉ cho localhost với `gateway.controlUi.allowInsecureAuth=true` -- xác thực Giao diện điều khiển cho operator thành công thông qua `gateway.auth.mode: "trusted-proxy"` -- tùy chọn phá kính `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- khả năng tương thích HTTP không bảo mật chỉ dành cho localhost với `gateway.controlUi.allowInsecureAuth=true` +- xác thực Control UI của người vận hành thành công thông qua `gateway.auth.mode: "trusted-proxy"` +- cấu hình khẩn cấp `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**Cách khắc phục khuyến nghị:** dùng HTTPS (Tailscale Serve) hoặc mở UI cục bộ: +**Cách khắc phục được khuyến nghị:** sử dụng HTTPS (Tailscale Serve) hoặc mở UI cục bộ: - `https:///` (Serve) - `http://127.0.0.1:18789/` (trên máy chủ gateway) - + ```json5 { gateway: { @@ -334,10 +336,10 @@ Các ngoại lệ đã được ghi tài liệu: } ``` - `allowInsecureAuth` chỉ là nút bật/tắt tương thích cục bộ: + `allowInsecureAuth` chỉ là một nút bật/tắt tương thích cục bộ: - Nó cho phép các phiên Control UI trên localhost tiếp tục mà không cần danh tính thiết bị trong ngữ cảnh HTTP không bảo mật. - - Nó không bỏ qua các kiểm tra ghép đôi. + - Nó không bỏ qua kiểm tra ghép nối. - Nó không nới lỏng yêu cầu danh tính thiết bị từ xa (không phải localhost). @@ -353,14 +355,14 @@ Các ngoại lệ đã được ghi tài liệu: ``` - `dangerouslyDisableDeviceAuth` tắt các kiểm tra danh tính thiết bị của Control UI và là một mức hạ cấp bảo mật nghiêm trọng. Hãy hoàn nguyên nhanh chóng sau khi dùng khẩn cấp. + `dangerouslyDisableDeviceAuth` tắt kiểm tra danh tính thiết bị của Control UI và là một mức hạ cấp bảo mật nghiêm trọng. Hãy hoàn nguyên nhanh sau khi sử dụng khẩn cấp. - - - Xác thực proxy đáng tin cậy thành công có thể cho phép các phiên Control UI của **người vận hành** mà không cần danh tính thiết bị. - - Điều này **không** áp dụng cho các phiên Control UI với vai trò node. - - Các proxy ngược local loopback cùng máy chủ vẫn không đáp ứng xác thực proxy đáng tin cậy; xem [Xác thực proxy đáng tin cậy](/vi/gateway/trusted-proxy-auth). + + - Xác thực trusted-proxy thành công có thể cho phép các phiên Control UI của **người vận hành** không cần danh tính thiết bị. + - Điều này **không** mở rộng sang các phiên Control UI có vai trò nút. + - Proxy ngược loopback cùng máy chủ vẫn không đáp ứng xác thực trusted-proxy; xem [Xác thực proxy đáng tin cậy](/vi/gateway/trusted-proxy-auth). @@ -369,30 +371,30 @@ Xem [Tailscale](/vi/gateway/tailscale) để biết hướng dẫn thiết lập ## Chính sách bảo mật nội dung -Control UI đi kèm với chính sách `img-src` chặt chẽ: chỉ cho phép tài nguyên **cùng nguồn**, URL `data:`, và URL `blob:` được tạo cục bộ. Các URL hình ảnh từ xa dạng `http(s)` và URL hình ảnh tương đối theo giao thức sẽ bị trình duyệt từ chối và không tạo yêu cầu mạng. +Control UI đi kèm chính sách `img-src` chặt chẽ: chỉ cho phép tài nguyên **cùng nguồn gốc**, URL `data:`, và URL `blob:` được tạo cục bộ. URL hình ảnh từ xa `http(s)` và URL hình ảnh tương đối theo giao thức bị trình duyệt từ chối và không phát sinh lượt tải qua mạng. Ý nghĩa trong thực tế: -- Avatar và hình ảnh được phục vụ dưới các đường dẫn tương đối (ví dụ `/avatars/`) vẫn hiển thị, bao gồm các tuyến avatar đã xác thực mà UI tìm nạp và chuyển đổi thành URL `blob:` cục bộ. -- URL nội tuyến `data:image/...` vẫn hiển thị (hữu ích cho payload trong giao thức). +- Avatar và hình ảnh được phục vụ dưới các đường dẫn tương đối (ví dụ `/avatars/`) vẫn hiển thị, bao gồm cả các route avatar đã xác thực mà UI tải và chuyển đổi thành URL `blob:` cục bộ. +- URL `data:image/...` nội tuyến vẫn hiển thị (hữu ích cho payload trong giao thức). - URL `blob:` cục bộ do Control UI tạo vẫn hiển thị. -- URL avatar từ xa do siêu dữ liệu kênh phát ra sẽ bị loại bỏ tại các helper avatar của Control UI và được thay bằng logo/huy hiệu tích hợp, vì vậy một kênh bị xâm phạm hoặc độc hại không thể buộc trình duyệt của người vận hành tìm nạp hình ảnh từ xa tùy ý. +- URL avatar từ xa do siêu dữ liệu kênh phát ra bị loại bỏ tại các helper avatar của Control UI và được thay thế bằng logo/huy hiệu tích hợp, nên một kênh bị xâm phạm hoặc độc hại không thể buộc trình duyệt của người vận hành tải hình ảnh từ xa tùy ý. Bạn không cần thay đổi gì để có hành vi này — nó luôn được bật và không thể cấu hình. -## Xác thực tuyến avatar +## Xác thực route avatar Khi xác thực gateway được cấu hình, endpoint avatar của Control UI yêu cầu cùng token gateway như phần còn lại của API: - `GET /avatar/` chỉ trả về hình ảnh avatar cho bên gọi đã xác thực. `GET /avatar/?meta=1` trả về siêu dữ liệu avatar theo cùng quy tắc. -- Các yêu cầu chưa xác thực đến một trong hai tuyến đều bị từ chối (khớp với tuyến assistant-media cùng cấp). Điều này ngăn tuyến avatar làm rò rỉ danh tính agent trên các máy chủ vốn được bảo vệ. -- Bản thân Control UI chuyển tiếp token gateway dưới dạng bearer header khi tìm nạp avatar, và dùng các URL blob đã xác thực để hình ảnh vẫn hiển thị trong dashboard. +- Yêu cầu chưa xác thực tới một trong hai route đều bị từ chối (khớp với route assistant-media cùng cấp). Điều này ngăn route avatar rò rỉ danh tính agent trên các máy chủ vốn được bảo vệ. +- Bản thân Control UI chuyển tiếp token gateway dưới dạng header bearer khi tải avatar, và sử dụng URL blob đã xác thực để hình ảnh vẫn hiển thị trong dashboard. -Nếu bạn tắt xác thực gateway (không khuyến nghị trên máy chủ dùng chung), tuyến avatar cũng trở thành không cần xác thực, phù hợp với phần còn lại của gateway. +Nếu bạn tắt xác thực gateway (không được khuyến nghị trên máy chủ dùng chung), route avatar cũng trở thành chưa xác thực, phù hợp với phần còn lại của gateway. ## Xây dựng UI -Gateway phục vụ tệp tĩnh từ `dist/control-ui`. Xây dựng chúng bằng: +Gateway phục vụ các tệp tĩnh từ `dist/control-ui`. Xây dựng chúng bằng: ```bash pnpm ui:build @@ -410,11 +412,11 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build pnpm ui:dev ``` -Sau đó trỏ UI đến URL Gateway WS của bạn (ví dụ `ws://127.0.0.1:18789`). +Sau đó trỏ UI tới URL Gateway WS của bạn (ví dụ `ws://127.0.0.1:18789`). ## Gỡ lỗi/kiểm thử: máy chủ dev + Gateway từ xa -Control UI là các tệp tĩnh; đích WebSocket có thể cấu hình và có thể khác với nguồn HTTP. Điều này hữu ích khi bạn muốn chạy máy chủ dev Vite cục bộ nhưng Gateway chạy ở nơi khác. +Control UI là các tệp tĩnh; đích WebSocket có thể cấu hình và có thể khác với nguồn gốc HTTP. Điều này hữu ích khi bạn muốn dùng máy chủ dev Vite cục bộ nhưng Gateway chạy ở nơi khác. @@ -422,7 +424,7 @@ Control UI là các tệp tĩnh; đích WebSocket có thể cấu hình và có pnpm ui:dev ``` - + ```text http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` @@ -438,17 +440,17 @@ Control UI là các tệp tĩnh; đích WebSocket có thể cấu hình và có - - `gatewayUrl` được lưu trong localStorage sau khi tải và bị xóa khỏi URL. - - Nếu bạn truyền một endpoint `ws://` hoặc `wss://` đầy đủ qua `gatewayUrl`, hãy mã hóa URL giá trị `gatewayUrl` để trình duyệt phân tích chuỗi truy vấn chính xác. - - `token` nên được truyền qua fragment URL (`#token=...`) bất cứ khi nào có thể. Fragment không được gửi đến máy chủ, giúp tránh rò rỉ qua nhật ký yêu cầu và Referer. Các tham số truy vấn cũ `?token=` vẫn được nhập một lần để tương thích, nhưng chỉ như phương án dự phòng, và bị loại bỏ ngay sau bootstrap. + - `gatewayUrl` được lưu trong localStorage sau khi tải và được xóa khỏi URL. + - Nếu bạn truyền một endpoint `ws://` hoặc `wss://` đầy đủ qua `gatewayUrl`, hãy mã hóa URL cho giá trị `gatewayUrl` để trình duyệt phân tích chuỗi truy vấn chính xác. + - `token` nên được truyền qua fragment URL (`#token=...`) bất cứ khi nào có thể. Fragment không được gửi tới máy chủ, giúp tránh rò rỉ qua nhật ký yêu cầu và Referer. Tham số truy vấn `?token=` cũ vẫn được nhập một lần để tương thích, nhưng chỉ như phương án dự phòng, và bị loại bỏ ngay sau khi bootstrap. - `password` chỉ được giữ trong bộ nhớ. - - Khi `gatewayUrl` được đặt, UI không dùng dự phòng thông tin xác thực từ cấu hình hoặc môi trường. Hãy cung cấp `token` (hoặc `password`) rõ ràng. Thiếu thông tin xác thực rõ ràng là lỗi. + - Khi `gatewayUrl` được đặt, UI không dùng dự phòng thông tin xác thực từ cấu hình hoặc môi trường. Hãy cung cấp `token` (hoặc `password`) một cách rõ ràng. Thiếu thông tin xác thực rõ ràng là lỗi. - Dùng `wss://` khi Gateway nằm sau TLS (Tailscale Serve, proxy HTTPS, v.v.). - `gatewayUrl` chỉ được chấp nhận trong cửa sổ cấp cao nhất (không nhúng) để ngăn clickjacking. - - Các triển khai Control UI không phải loopback phải đặt `gateway.controlUi.allowedOrigins` rõ ràng (nguồn đầy đủ). Điều này bao gồm cả các thiết lập dev từ xa. - - Khi khởi động, Gateway có thể gieo các nguồn cục bộ như `http://localhost:` và `http://127.0.0.1:` từ bind và cổng runtime có hiệu lực, nhưng các nguồn trình duyệt từ xa vẫn cần mục nhập rõ ràng. - - Không dùng `gateway.controlUi.allowedOrigins: ["*"]` ngoại trừ kiểm thử cục bộ được kiểm soát chặt chẽ. Nó có nghĩa là cho phép mọi nguồn trình duyệt, không phải "khớp với bất kỳ host nào tôi đang dùng." - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` bật chế độ dự phòng nguồn theo Host header, nhưng đây là chế độ bảo mật nguy hiểm. + - Các triển khai Control UI không phải loopback phải đặt `gateway.controlUi.allowedOrigins` một cách rõ ràng (origin đầy đủ). Điều này bao gồm các thiết lập dev từ xa. + - Khi khởi động, Gateway có thể seed các origin cục bộ như `http://localhost:` và `http://127.0.0.1:` từ bind và cổng runtime hiệu lực, nhưng các origin trình duyệt từ xa vẫn cần mục nhập rõ ràng. + - Không dùng `gateway.controlUi.allowedOrigins: ["*"]` trừ khi kiểm thử cục bộ được kiểm soát chặt chẽ. Nó có nghĩa là cho phép mọi origin trình duyệt, không phải "khớp với bất kỳ host nào tôi đang dùng." + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` bật chế độ dự phòng origin theo header Host, nhưng đây là một chế độ bảo mật nguy hiểm. @@ -471,5 +473,5 @@ Chi tiết thiết lập truy cập từ xa: [Truy cập từ xa](/vi/gateway/re - [Dashboard](/vi/web/dashboard) — dashboard gateway - [Kiểm tra tình trạng](/vi/gateway/health) — giám sát tình trạng gateway -- [TUI](/vi/web/tui) — giao diện người dùng terminal +- [TUI](/vi/web/tui) — giao diện người dùng trong terminal - [WebChat](/vi/web/webchat) — giao diện trò chuyện dựa trên trình duyệt diff --git a/docs/vi/web/webchat.md b/docs/vi/web/webchat.md index 12265af60..fb374dc25 100644 --- a/docs/vi/web/webchat.md +++ b/docs/vi/web/webchat.md @@ -1,70 +1,71 @@ --- read_when: - Gỡ lỗi hoặc cấu hình quyền truy cập WebChat -summary: Máy chủ tĩnh WebChat loopback và cách sử dụng WS Gateway cho giao diện trò chuyện +summary: Máy chủ tĩnh WebChat vòng lặp cục bộ và cách sử dụng WS của Gateway cho giao diện trò chuyện title: Trò chuyện web x-i18n: - generated_at: "2026-05-02T10:57:16Z" + generated_at: "2026-05-02T23:39:10Z" model: gpt-5.5 provider: openai - source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d + source_hash: ad3a09c8962e3a6dda83716d319df7ba27e18105cee50721278b5cba0a85c52f source_path: web/webchat.md workflow: 16 --- -Trạng thái: giao diện trò chuyện SwiftUI trên macOS/iOS giao tiếp trực tiếp với Gateway WebSocket. +Trạng thái: giao diện trò chuyện SwiftUI macOS/iOS giao tiếp trực tiếp với Gateway WebSocket. ## Đây là gì -- Giao diện trò chuyện native cho Gateway (không có trình duyệt nhúng và không có máy chủ tĩnh cục bộ). -- Sử dụng cùng các phiên và quy tắc định tuyến như các kênh khác. +- Giao diện trò chuyện native cho gateway (không có trình duyệt nhúng và không có máy chủ tĩnh cục bộ). +- Sử dụng cùng phiên và quy tắc định tuyến như các kênh khác. - Định tuyến xác định: phản hồi luôn quay lại WebChat. ## Khởi động nhanh -1. Khởi động Gateway. -2. Mở giao diện WebChat (ứng dụng macOS/iOS) hoặc tab trò chuyện của Control UI. -3. Đảm bảo đã cấu hình đường dẫn xác thực Gateway hợp lệ (mặc định là shared-secret, +1. Khởi động gateway. +2. Mở giao diện WebChat (ứng dụng macOS/iOS) hoặc thẻ trò chuyện của Control UI. +3. Đảm bảo đã cấu hình một đường dẫn xác thực gateway hợp lệ (mặc định là shared-secret, ngay cả trên loopback). ## Cách hoạt động (hành vi) -- Giao diện kết nối tới Gateway WebSocket và sử dụng `chat.history`, `chat.send`, và `chat.inject`. -- `chat.history` được giới hạn để đảm bảo ổn định: Gateway có thể cắt bớt các trường văn bản dài, bỏ qua metadata nặng, và thay thế các mục quá lớn bằng `[chat.history omitted: message too large]`. -- `chat.history` theo nhánh transcript đang hoạt động đối với các tệp phiên append-only hiện đại, nên các nhánh ghi lại bị bỏ và các bản sao prompt đã bị thay thế sẽ không được hiển thị trong WebChat. -- Control UI ghi nhớ Gateway `sessionId` nền do `chat.history` trả về và đưa nó vào các lệnh gọi `chat.send` tiếp theo, nên việc kết nối lại và làm mới trang sẽ tiếp tục cùng cuộc trò chuyện đã lưu trừ khi người dùng bắt đầu hoặc đặt lại phiên. -- Control UI gộp các lượt gửi đang xử lý bị trùng cho cùng phiên, tin nhắn, và tệp đính kèm trước khi tạo id chạy `chat.send` mới; Gateway vẫn khử trùng lặp các yêu cầu lặp lại dùng lại cùng khóa idempotency. -- `chat.history` cũng được chuẩn hóa cho hiển thị: ngữ cảnh OpenClaw chỉ dùng lúc runtime, - các wrapper phong bì đầu vào, các thẻ chỉ thị phân phối inline +- Giao diện kết nối với Gateway WebSocket và sử dụng `chat.history`, `chat.send`, `chat.inject`, và `chat.transcribeAudio`. +- `chat.history` được giới hạn để ổn định: Gateway có thể cắt bớt các trường văn bản dài, bỏ qua metadata nặng, và thay thế các mục quá lớn bằng `[chat.history omitted: message too large]`. +- `chat.history` đi theo nhánh bản ghi hội thoại đang hoạt động đối với các tệp phiên append-only hiện đại, nên các nhánh viết lại bị bỏ và bản sao prompt đã bị thay thế sẽ không được hiển thị trong WebChat. +- Control UI ghi nhớ Gateway `sessionId` nền do `chat.history` trả về và đưa nó vào các lệnh gọi `chat.send` tiếp theo, nên các lần kết nối lại và làm mới trang tiếp tục cùng cuộc trò chuyện đã lưu trữ trừ khi người dùng bắt đầu hoặc đặt lại phiên. +- Control UI gộp các lần gửi đang xử lý trùng lặp cho cùng phiên, tin nhắn và tệp đính kèm trước khi tạo id lần chạy `chat.send` mới; Gateway vẫn khử trùng lặp các yêu cầu lặp lại tái sử dụng cùng khóa idempotency. +- `chat.history` cũng được chuẩn hóa để hiển thị: ngữ cảnh OpenClaw chỉ dùng lúc chạy, + wrapper phong bì đầu vào, thẻ chỉ thị gửi nội tuyến như `[[reply_to_*]]` và `[[audio_as_voice]]`, payload XML gọi công cụ dạng văn bản thuần (bao gồm `...`, `...`, `...`, - `...`, và các khối gọi công cụ bị cắt ngắn), cùng - các token điều khiển mô hình ASCII/full-width bị rò rỉ sẽ bị loại khỏi văn bản hiển thị, + `...`, và các khối gọi công cụ bị cắt ngắn), và + token điều khiển mô hình ASCII/full-width bị rò rỉ sẽ bị loại khỏi văn bản hiển thị, và các mục assistant có toàn bộ văn bản hiển thị chỉ là token im lặng chính xác `NO_REPLY` / `no_reply` sẽ bị bỏ qua. -- Payload phản hồi được gắn cờ reasoning (`isReasoning: true`) bị loại khỏi nội dung assistant của WebChat, văn bản phát lại transcript, và các khối nội dung âm thanh, nên các payload chỉ để suy nghĩ không xuất hiện dưới dạng tin nhắn assistant hiển thị hoặc âm thanh có thể phát. -- `chat.inject` thêm trực tiếp một ghi chú assistant vào transcript và phát nó tới giao diện (không chạy agent). -- Các lượt chạy bị hủy có thể giữ đầu ra assistant một phần hiển thị trong giao diện. -- Gateway lưu văn bản assistant một phần đã bị hủy vào lịch sử transcript khi có đầu ra đã được đệm, và đánh dấu các mục đó bằng metadata hủy. -- Lịch sử luôn được lấy từ Gateway (không theo dõi tệp cục bộ). -- Nếu không thể truy cập Gateway, WebChat ở chế độ chỉ đọc. +- Payload phản hồi được gắn cờ suy luận (`isReasoning: true`) bị loại khỏi nội dung assistant của WebChat, văn bản phát lại bản ghi hội thoại và các khối nội dung âm thanh, nên payload chỉ dùng để suy nghĩ không xuất hiện dưới dạng tin nhắn assistant hiển thị hoặc âm thanh có thể phát. +- `chat.transcribeAudio` cung cấp tính năng đọc chính tả phía máy chủ trong trình soạn trò chuyện của Control UI. Trình duyệt ghi âm microphone, gửi dưới dạng base64 đến Gateway, và Gateway chạy pipeline `tools.media.audio` đã cấu hình. Bản chép lời trả về được chèn vào bản nháp; không có lần chạy agent nào được bắt đầu cho đến khi người dùng gửi. +- `chat.inject` thêm trực tiếp một ghi chú assistant vào bản ghi hội thoại và phát nó đến giao diện (không có lần chạy agent). +- Các lần chạy bị hủy có thể giữ đầu ra assistant một phần hiển thị trong giao diện. +- Gateway lưu văn bản assistant một phần đã bị hủy vào lịch sử bản ghi hội thoại khi có đầu ra được đệm, và đánh dấu các mục đó bằng metadata hủy. +- Lịch sử luôn được lấy từ gateway (không theo dõi tệp cục bộ). +- Nếu không thể truy cập gateway, WebChat ở chế độ chỉ đọc. ## Bảng công cụ agent của Control UI -- Bảng Tools của Control UI `/agents` có hai chế độ xem riêng: - - **Hiện Có Ngay** dùng `tools.effective(sessionKey=...)` và hiển thị những gì phiên hiện tại - thực sự có thể dùng lúc runtime, bao gồm các công cụ thuộc core, plugin, và kênh. - - **Cấu Hình Công Cụ** dùng `tools.catalog` và tập trung vào profile, override, và +- Bảng Tools của Control UI `/agents` có hai chế độ xem riêng biệt: + - **Khả dụng ngay bây giờ** sử dụng `tools.effective(sessionKey=...)` và hiển thị những gì phiên hiện tại + thực sự có thể dùng lúc chạy, bao gồm công cụ thuộc core, plugin và kênh. + - **Cấu hình công cụ** sử dụng `tools.catalog` và tiếp tục tập trung vào hồ sơ, ghi đè và ngữ nghĩa catalog. -- Khả dụng lúc runtime có phạm vi theo phiên. Chuyển phiên trên cùng agent có thể thay đổi danh sách - **Hiện Có Ngay**. -- Trình chỉnh sửa cấu hình không ngụ ý khả dụng lúc runtime; quyền truy cập hiệu lực vẫn tuân theo thứ tự ưu tiên chính sách - (`allow`/`deny`, override theo agent và provider/kênh). +- Khả dụng lúc chạy được giới hạn theo phiên. Chuyển phiên trên cùng một agent có thể thay đổi danh sách + **Khả dụng ngay bây giờ**. +- Trình chỉnh sửa cấu hình không ngụ ý khả dụng lúc chạy; quyền truy cập hiệu lực vẫn tuân theo thứ tự ưu tiên chính sách + (`allow`/`deny`, ghi đè theo từng agent và provider/kênh). ## Sử dụng từ xa -- Chế độ từ xa tunnel Gateway WebSocket qua SSH/Tailscale. +- Chế độ từ xa đường hầm Gateway WebSocket qua SSH/Tailscale. - Bạn không cần chạy máy chủ WebChat riêng. ## Tham chiếu cấu hình (WebChat) @@ -73,20 +74,20 @@ Cấu hình đầy đủ: [Cấu hình](/vi/gateway/configuration) Tùy chọn WebChat: -- `gateway.webchat.chatHistoryMaxChars`: số ký tự tối đa cho các trường văn bản trong phản hồi `chat.history`. Khi một mục transcript vượt quá giới hạn này, Gateway cắt bớt các trường văn bản dài và có thể thay thế tin nhắn quá lớn bằng placeholder. Client cũng có thể gửi `maxChars` theo từng yêu cầu để ghi đè mặc định này cho một lệnh gọi `chat.history` duy nhất. +- `gateway.webchat.chatHistoryMaxChars`: số ký tự tối đa cho các trường văn bản trong phản hồi `chat.history`. Khi một mục bản ghi hội thoại vượt quá giới hạn này, Gateway sẽ cắt bớt các trường văn bản dài và có thể thay thế tin nhắn quá lớn bằng placeholder. `maxChars` theo từng yêu cầu cũng có thể được client gửi để ghi đè mặc định này cho một lệnh gọi `chat.history` duy nhất. Tùy chọn toàn cục liên quan: - `gateway.port`, `gateway.bind`: máy chủ/cổng WebSocket. - `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`: xác thực WebSocket shared-secret. -- `gateway.auth.allowTailscale`: tab trò chuyện Control UI trong trình duyệt có thể dùng header danh tính Tailscale +- `gateway.auth.allowTailscale`: thẻ trò chuyện Control UI trên trình duyệt có thể dùng header định danh Tailscale Serve khi được bật. -- `gateway.auth.mode: "trusted-proxy"`: xác thực reverse-proxy cho client trình duyệt phía sau nguồn proxy **không phải loopback** nhận biết danh tính (xem [Xác Thực Trusted Proxy](/vi/gateway/trusted-proxy-auth)). -- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: đích Gateway từ xa. +- `gateway.auth.mode: "trusted-proxy"`: xác thực reverse-proxy cho client trình duyệt phía sau một nguồn proxy **không phải loopback** nhận biết danh tính (xem [Xác thực proxy tin cậy](/vi/gateway/trusted-proxy-auth)). +- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: mục tiêu gateway từ xa. - `session.*`: lưu trữ phiên và mặc định khóa chính. ## Liên quan - [Control UI](/vi/web/control-ui) -- [Dashboard](/vi/web/dashboard) +- [Bảng điều khiển](/vi/web/dashboard)