From b36ce71e65ba0fa872829c970359a43edb342686 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 5 May 2026 08:27:40 +0000 Subject: [PATCH] chore(i18n): refresh vi translations --- docs/vi/automation/hooks.md | 144 +++--- docs/vi/channels/troubleshooting.md | 117 ++--- docs/vi/cli/doctor.md | 75 +-- docs/vi/cli/gateway.md | 275 +++++----- docs/vi/cli/hooks.md | 80 +-- docs/vi/cli/sessions.md | 39 +- docs/vi/concepts/mantis.md | 479 +++++++++--------- docs/vi/gateway/doctor.md | 377 +++++++------- docs/vi/install/docker.md | 288 +++++------ .../session-management-compaction.md | 271 +++++----- 10 files changed, 1071 insertions(+), 1074 deletions(-) diff --git a/docs/vi/automation/hooks.md b/docs/vi/automation/hooks.md index 3a095e215..884f6b544 100644 --- a/docs/vi/automation/hooks.md +++ b/docs/vi/automation/hooks.md @@ -1,26 +1,26 @@ --- read_when: - - Bạn muốn tự động hóa theo sự kiện cho /new, /reset, /stop và các sự kiện vòng đời tác nhân + - Bạn muốn tự động hóa theo sự kiện cho /new, /reset, /stop và các sự kiện vòng đời của tác tử - Bạn muốn xây dựng, cài đặt hoặc gỡ lỗi các móc nối summary: 'Móc nối: tự động hóa theo sự kiện cho các lệnh và sự kiện vòng đời' title: Móc nối x-i18n: - generated_at: "2026-05-03T21:27:30Z" + generated_at: "2026-05-05T08:25:35Z" model: gpt-5.5 provider: openai - source_hash: 15f0d120ccf7314a991da5d66e65e5c78375222a846ba01d7a04ddfe1f02cb32 + source_hash: 321eb7a583d5e8c90d2c2026f6e1cf46cd207bef52213774b469a8d46b993967 source_path: automation/hooks.md workflow: 16 --- -Hooks là các tập lệnh nhỏ chạy khi có điều gì đó xảy ra bên trong Gateway. Chúng có thể được phát hiện từ các thư mục và được kiểm tra bằng `openclaw hooks`. Gateway chỉ tải các hook nội bộ sau khi bạn bật hooks hoặc cấu hình ít nhất một mục hook, gói hook, trình xử lý cũ, hoặc thư mục hook bổ sung. +Hook là các script nhỏ chạy khi có điều gì đó xảy ra bên trong Gateway. Chúng có thể được phát hiện từ các thư mục và kiểm tra bằng `openclaw hooks`. Gateway chỉ tải các hook nội bộ sau khi bạn bật hook hoặc cấu hình ít nhất một mục hook, gói hook, trình xử lý cũ, hoặc thư mục hook bổ sung. Có hai loại hook trong OpenClaw: - **Hook nội bộ** (trang này): chạy bên trong Gateway khi các sự kiện agent kích hoạt, như `/new`, `/reset`, `/stop`, hoặc các sự kiện vòng đời. -- **Webhooks**: các endpoint HTTP bên ngoài cho phép hệ thống khác kích hoạt công việc trong OpenClaw. Xem [Webhooks](/vi/automation/cron-jobs#webhooks). +- **Webhook**: các endpoint HTTP bên ngoài cho phép hệ thống khác kích hoạt công việc trong OpenClaw. Xem [Webhook](/vi/automation/cron-jobs#webhooks). -Hook cũng có thể được đóng gói bên trong plugins. `openclaw hooks list` hiển thị cả hook độc lập và hook do plugin quản lý. +Hook cũng có thể được đóng gói bên trong Plugin. `openclaw hooks list` hiển thị cả hook độc lập và hook do Plugin quản lý. ## Bắt đầu nhanh @@ -40,25 +40,25 @@ openclaw hooks info session-memory ## Loại sự kiện -| Sự kiện | Khi nào kích hoạt | -| ------------------------ | ---------------------------------------------------------- | -| `command:new` | Lệnh `/new` được phát hành | -| `command:reset` | Lệnh `/reset` được phát hành | -| `command:stop` | Lệnh `/stop` được phát hành | -| `command` | Bất kỳ sự kiện lệnh nào (trình lắng nghe chung) | -| `session:compact:before` | Trước khi compaction tóm tắt lịch sử | -| `session:compact:after` | Sau khi compaction hoàn tất | -| `session:patch` | Khi thuộc tính phiên được sửa đổi | -| `agent:bootstrap` | Trước khi các tệp bootstrap của không gian làm việc được chèn | -| `gateway:startup` | Sau khi các kênh khởi động và hooks được tải | -| `gateway:shutdown` | Khi quá trình tắt gateway bắt đầu | -| `gateway:pre-restart` | Trước một lần khởi động lại gateway dự kiến | -| `message:received` | Tin nhắn đến từ bất kỳ kênh nào | -| `message:transcribed` | Sau khi phiên âm âm thanh hoàn tất | -| `message:preprocessed` | Sau khi tiền xử lý phương tiện và liên kết hoàn tất hoặc bị bỏ qua | -| `message:sent` | Tin nhắn gửi đi đã được chuyển phát | +| Sự kiện | Khi nào kích hoạt | +| ------------------------ | -------------------------------------------------------- | +| `command:new` | Lệnh `/new` được phát hành | +| `command:reset` | Lệnh `/reset` được phát hành | +| `command:stop` | Lệnh `/stop` được phát hành | +| `command` | Bất kỳ sự kiện lệnh nào (trình nghe chung) | +| `session:compact:before` | Trước khi Compaction tóm tắt lịch sử | +| `session:compact:after` | Sau khi Compaction hoàn tất | +| `session:patch` | Khi thuộc tính phiên được sửa đổi | +| `agent:bootstrap` | Trước khi các tệp bootstrap workspace được chèn vào | +| `gateway:startup` | Sau khi các kênh khởi động và hook được tải | +| `gateway:shutdown` | Khi quá trình tắt gateway bắt đầu | +| `gateway:pre-restart` | Trước một lần khởi động lại gateway dự kiến | +| `message:received` | Tin nhắn đến từ bất kỳ kênh nào | +| `message:transcribed` | Sau khi phiên âm âm thanh hoàn tất | +| `message:preprocessed` | Sau khi tiền xử lý media và liên kết hoàn tất hoặc bị bỏ qua | +| `message:sent` | Tin nhắn gửi đi đã được chuyển phát | -## Viết hooks +## Viết hook ### Cấu trúc hook @@ -87,17 +87,17 @@ Detailed documentation goes here. **Trường metadata** (`metadata.openclaw`): -| Trường | Mô tả | -| ---------- | ---------------------------------------------------- | -| `emoji` | Emoji hiển thị cho CLI | -| `events` | Mảng các sự kiện cần lắng nghe | -| `export` | Export có tên cần dùng (mặc định là `"default"`) | -| `os` | Nền tảng bắt buộc (ví dụ: `["darwin", "linux"]`) | +| Trường | Mô tả | +| ---------- | ----------------------------------------------------- | +| `emoji` | Emoji hiển thị cho CLI | +| `events` | Mảng sự kiện cần lắng nghe | +| `export` | Export được đặt tên để dùng (mặc định là `"default"`) | +| `os` | Nền tảng bắt buộc (ví dụ: `["darwin", "linux"]`) | | `requires` | Các đường dẫn `bins`, `anyBins`, `env`, hoặc `config` bắt buộc | -| `always` | Bỏ qua kiểm tra đủ điều kiện (boolean) | -| `install` | Phương thức cài đặt | +| `always` | Bỏ qua kiểm tra điều kiện hợp lệ (boolean) | +| `install` | Phương thức cài đặt | -### Triển khai handler +### Triển khai trình xử lý ```typescript const handler = async (event) => { @@ -115,61 +115,61 @@ const handler = async (event) => { export default handler; ``` -Mỗi sự kiện bao gồm: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push để gửi cho người dùng), và `context` (dữ liệu theo từng sự kiện). Ngữ cảnh hook của agent và tool plugin cũng có thể bao gồm `trace`, một ngữ cảnh trace chẩn đoán chỉ đọc tương thích W3C mà plugin có thể truyền vào nhật ký có cấu trúc để tương quan OTEL. +Mỗi sự kiện bao gồm: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push để gửi cho người dùng), và `context` (dữ liệu dành riêng cho sự kiện). Ngữ cảnh hook của agent và Plugin công cụ cũng có thể bao gồm `trace`, một ngữ cảnh vết chẩn đoán tương thích W3C ở chế độ chỉ đọc mà Plugin có thể truyền vào log có cấu trúc để tương quan OTEL. ### Điểm nổi bật về ngữ cảnh sự kiện **Sự kiện lệnh** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`. -**Sự kiện tin nhắn** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (dữ liệu theo từng provider bao gồm `senderId`, `senderName`, `guildId`). `context.content` ưu tiên nội dung lệnh không trống cho các tin nhắn giống lệnh, sau đó quay lại nội dung đến thô và nội dung chung; nó không bao gồm phần làm giàu chỉ dành cho agent như lịch sử luồng hoặc tóm tắt liên kết. +**Sự kiện tin nhắn** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (dữ liệu dành riêng cho provider bao gồm `senderId`, `senderName`, `guildId`). `context.content` ưu tiên phần thân lệnh không trống cho các tin nhắn giống lệnh, sau đó rơi về phần thân đến thô và phần thân chung; nó không bao gồm phần làm giàu chỉ dành cho agent như lịch sử luồng hoặc tóm tắt liên kết. **Sự kiện tin nhắn** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`. **Sự kiện tin nhắn** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. -**Sự kiện tin nhắn** (`message:preprocessed`): `context.bodyForAgent` (nội dung làm giàu cuối cùng), `context.from`, `context.channelId`. +**Sự kiện tin nhắn** (`message:preprocessed`): `context.bodyForAgent` (phần thân làm giàu cuối cùng), `context.from`, `context.channelId`. **Sự kiện bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (mảng có thể thay đổi), `context.agentId`. -**Sự kiện bản vá phiên** (`session:patch`): `context.sessionEntry`, `context.patch` (chỉ các trường đã thay đổi), `context.cfg`. Chỉ các client đặc quyền mới có thể kích hoạt sự kiện patch. +**Sự kiện bản vá phiên** (`session:patch`): `context.sessionEntry`, `context.patch` (chỉ các trường đã thay đổi), `context.cfg`. Chỉ các client đặc quyền mới có thể kích hoạt sự kiện bản vá. **Sự kiện Compaction**: `session:compact:before` bao gồm `messageCount`, `tokenCount`. `session:compact:after` thêm `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. -`command:stop` quan sát việc người dùng phát hành `/stop`; đây là vòng đời hủy/lệnh, không phải cổng hoàn tất agent. Plugin cần kiểm tra câu trả lời cuối tự nhiên và yêu cầu agent thực hiện thêm một lượt nên dùng hook plugin có kiểu `before_agent_finalize` thay vào đó. Xem [Hook plugin](/vi/plugins/hooks). +`command:stop` quan sát việc người dùng phát hành `/stop`; đây là vòng đời hủy/lệnh, không phải cổng hoàn tất agent. Plugin cần kiểm tra câu trả lời cuối tự nhiên và yêu cầu agent chạy thêm một lượt nên dùng hook Plugin có kiểu `before_agent_finalize` thay thế. Xem [Hook Plugin](/vi/plugins/hooks). -**Sự kiện vòng đời Gateway**: `gateway:shutdown` bao gồm `reason` và `restartExpectedMs`, đồng thời kích hoạt khi quá trình tắt gateway bắt đầu. `gateway:pre-restart` bao gồm cùng ngữ cảnh nhưng chỉ kích hoạt khi việc tắt là một phần của lần khởi động lại dự kiến và giá trị `restartExpectedMs` hữu hạn được cung cấp. Trong quá trình tắt, mỗi lần chờ hook vòng đời là nỗ lực tốt nhất và có giới hạn để quá trình tắt tiếp tục nếu một handler bị treo. +**Sự kiện vòng đời Gateway**: `gateway:shutdown` bao gồm `reason` và `restartExpectedMs` và kích hoạt khi quá trình tắt gateway bắt đầu. `gateway:pre-restart` bao gồm cùng ngữ cảnh nhưng chỉ kích hoạt khi việc tắt là một phần của lần khởi động lại dự kiến và một giá trị `restartExpectedMs` hữu hạn được cung cấp. Trong quá trình tắt, mỗi lần chờ hook vòng đời là nỗ lực tốt nhất và có giới hạn để quá trình tắt vẫn tiếp tục nếu một trình xử lý bị treo. ## Phát hiện hook Hook được phát hiện từ các thư mục này, theo thứ tự độ ưu tiên ghi đè tăng dần: 1. **Hook đi kèm**: được phát hành cùng OpenClaw -2. **Hook plugin**: hook được đóng gói bên trong plugin đã cài đặt -3. **Hook được quản lý**: `~/.openclaw/hooks/` (do người dùng cài đặt, chia sẻ giữa các không gian làm việc). Các thư mục bổ sung từ `hooks.internal.load.extraDirs` dùng chung mức ưu tiên này. -4. **Hook không gian làm việc**: `/hooks/` (theo từng agent, bị tắt theo mặc định cho đến khi được bật rõ ràng) +2. **Hook Plugin**: hook được đóng gói bên trong Plugin đã cài đặt +3. **Hook được quản lý**: `~/.openclaw/hooks/` (do người dùng cài đặt, dùng chung giữa các workspace). Các thư mục bổ sung từ `hooks.internal.load.extraDirs` chia sẻ độ ưu tiên này. +4. **Hook workspace**: `/hooks/` (theo từng agent, mặc định bị tắt cho đến khi được bật rõ ràng) -Hook không gian làm việc có thể thêm tên hook mới nhưng không thể ghi đè hook đi kèm, hook được quản lý, hoặc hook do plugin cung cấp có cùng tên. +Hook workspace có thể thêm tên hook mới nhưng không thể ghi đè các hook đi kèm, được quản lý, hoặc do Plugin cung cấp có cùng tên. -Gateway bỏ qua việc phát hiện hook nội bộ khi khởi động cho đến khi hooks nội bộ được cấu hình. Bật một hook đi kèm hoặc được quản lý bằng `openclaw hooks enable `, cài đặt một gói hook, hoặc đặt `hooks.internal.enabled=true` để tham gia. Khi bạn bật một hook có tên, Gateway chỉ tải handler của hook đó; `hooks.internal.enabled=true`, thư mục hook bổ sung, và handler cũ tham gia phát hiện rộng. +Gateway bỏ qua việc phát hiện hook nội bộ khi khởi động cho đến khi hook nội bộ được cấu hình. Bật một hook đi kèm hoặc hook được quản lý bằng `openclaw hooks enable `, cài đặt gói hook, hoặc đặt `hooks.internal.enabled=true` để chọn tham gia. Khi bạn bật một hook được đặt tên, Gateway chỉ tải trình xử lý của hook đó; `hooks.internal.enabled=true`, thư mục hook bổ sung, và trình xử lý cũ chọn tham gia phát hiện rộng. ### Gói hook -Gói hook là các gói npm export hooks thông qua `openclaw.hooks` trong `package.json`. Cài đặt bằng: +Gói hook là các gói npm xuất hook qua `openclaw.hooks` trong `package.json`. Cài đặt bằng: ```bash openclaw plugins install ``` -Spec npm chỉ dùng registry (tên gói + phiên bản chính xác tùy chọn hoặc dist-tag). Spec Git/URL/file và dải semver bị từ chối. +Đặc tả npm chỉ dùng registry (tên gói + phiên bản chính xác hoặc dist-tag tùy chọn). Đặc tả Git/URL/file và dải semver sẽ bị từ chối. ## Hook đi kèm -| Hook | Sự kiện | Chức năng | +| Hook | Sự kiện | Chức năng | | --------------------- | ------------------------------------------------- | -------------------------------------------------------------- | | session-memory | `command:new`, `command:reset` | Lưu ngữ cảnh phiên vào `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | Chèn thêm tệp bootstrap từ các mẫu glob | +| bootstrap-extra-files | `agent:bootstrap` | Chèn các tệp bootstrap bổ sung từ mẫu glob | | command-logger | `command` | Ghi nhật ký tất cả lệnh vào `~/.openclaw/logs/commands.log` | -| compaction-notifier | `session:compact:before`, `session:compact:after` | Gửi thông báo chat hiển thị khi compaction phiên bắt đầu/kết thúc | +| compaction-notifier | `session:compact:before`, `session:compact:after` | Gửi thông báo chat hiển thị khi Compaction phiên bắt đầu/kết thúc | | boot-md | `gateway:startup` | Chạy `BOOT.md` khi gateway khởi động | Bật bất kỳ hook đi kèm nào: @@ -182,7 +182,7 @@ openclaw hooks enable ### Chi tiết session-memory -Trích xuất 15 tin nhắn người dùng/assistant cuối cùng, tạo slug tên tệp mô tả thông qua LLM, và lưu vào `/memory/YYYY-MM-DD-slug.md` bằng ngày cục bộ của host. Yêu cầu cấu hình `workspace.dir`. +Trích xuất 15 tin nhắn người dùng/trợ lý gần nhất và lưu vào `/memory/YYYY-MM-DD-HHMM.md` theo ngày cục bộ của máy chủ. Việc ghi lại bộ nhớ chạy trong nền nên xác nhận `/new` và `/reset` không bị chậm bởi quá trình đọc bản ghi hội thoại hoặc tạo slug tùy chọn. Đặt `hooks.internal.entries.session-memory.llmSlug: true` để tạo slug tên tệp mô tả bằng mô hình đã cấu hình. Yêu cầu cấu hình `workspace.dir`. @@ -203,7 +203,7 @@ Trích xuất 15 tin nhắn người dùng/assistant cuối cùng, tạo slug t } ``` -Đường dẫn được phân giải tương đối với không gian làm việc. Chỉ các tên cơ sở bootstrap được nhận diện mới được tải (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). +Đường dẫn được phân giải tương đối với workspace. Chỉ các tên cơ sở bootstrap được nhận diện mới được tải (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). @@ -215,22 +215,22 @@ Ghi nhật ký mọi lệnh slash vào `~/.openclaw/logs/commands.log`. ### Chi tiết compaction-notifier -Gửi các tin nhắn trạng thái ngắn vào cuộc trò chuyện hiện tại khi OpenClaw bắt đầu và kết thúc việc compact transcript phiên. Điều này giúp các lượt dài bớt khó hiểu trên bề mặt chat vì người dùng có thể thấy assistant đang tóm tắt ngữ cảnh và sẽ tiếp tục sau compaction. +Gửi thông báo trạng thái ngắn vào cuộc trò chuyện hiện tại khi OpenClaw bắt đầu và hoàn tất việc nén bản ghi phiên. Điều này giúp các lượt dài bớt khó hiểu trên bề mặt chat vì người dùng có thể thấy trợ lý đang tóm tắt ngữ cảnh và sẽ tiếp tục sau Compaction. ### Chi tiết boot-md -Chạy `BOOT.md` từ không gian làm việc đang hoạt động khi gateway khởi động. +Chạy `BOOT.md` từ workspace đang hoạt động khi gateway khởi động. -## Hook plugin +## Hook Plugin -Plugin có thể đăng ký hook có kiểu thông qua Plugin SDK để tích hợp sâu hơn: -chặn lời gọi công cụ, sửa đổi prompt, kiểm soát luồng tin nhắn, và nhiều hơn nữa. -Dùng hook plugin khi bạn cần `before_tool_call`, `before_agent_reply`, +Plugin có thể đăng ký các hook có kiểu thông qua Plugin SDK để tích hợp sâu hơn: +chặn lời gọi công cụ, sửa đổi prompt, điều khiển luồng tin nhắn, v.v. +Dùng hook Plugin khi bạn cần `before_tool_call`, `before_agent_reply`, `before_install`, hoặc các hook vòng đời trong tiến trình khác. -Để xem tham chiếu hook plugin đầy đủ, xem [Hook plugin](/vi/plugins/hooks). +Để xem tài liệu tham khảo đầy đủ về hook Plugin, hãy xem [Hook Plugin](/vi/plugins/hooks). ## Cấu hình @@ -280,7 +280,7 @@ Thư mục hook bổ sung: ``` -Định dạng cấu hình mảng `hooks.internal.handlers` cũ vẫn được hỗ trợ để tương thích ngược, nhưng hooks mới nên dùng hệ thống dựa trên phát hiện. +Định dạng cấu hình mảng `hooks.internal.handlers` cũ vẫn được hỗ trợ để tương thích ngược, nhưng hook mới nên dùng hệ thống dựa trên khám phá. ## Tham chiếu CLI @@ -300,16 +300,16 @@ openclaw hooks enable openclaw hooks disable ``` -## Phương pháp tốt nhất +## Thực hành tốt nhất -- **Giữ trình xử lý chạy nhanh.** Hook chạy trong quá trình xử lý lệnh. Chạy công việc nặng theo kiểu fire-and-forget bằng `void processInBackground(event)`. -- **Xử lý lỗi nhẹ nhàng.** Bọc các thao tác rủi ro trong try/catch; không throw để các trình xử lý khác vẫn có thể chạy. -- **Lọc sự kiện sớm.** Trả về ngay nếu loại/hành động sự kiện không liên quan. +- **Giữ các trình xử lý chạy nhanh.** Móc nối chạy trong quá trình xử lý lệnh. Chạy tác vụ nặng theo kiểu không chờ kết quả bằng `void processInBackground(event)`. +- **Xử lý lỗi một cách êm thấm.** Bọc các thao tác rủi ro trong try/catch; không throw để các trình xử lý khác vẫn có thể chạy. +- **Lọc sự kiện sớm.** Trả về ngay nếu kiểu/hành động sự kiện không liên quan. - **Dùng khóa sự kiện cụ thể.** Ưu tiên `"events": ["command:new"]` thay vì `"events": ["command"]` để giảm chi phí xử lý. ## Khắc phục sự cố -### Không phát hiện thấy hook +### Không phát hiện được móc nối ```bash # Verify directory structure @@ -320,7 +320,7 @@ ls -la ~/.openclaw/hooks/my-hook/ openclaw hooks list ``` -### Hook không đủ điều kiện +### Móc nối không đủ điều kiện ```bash openclaw hooks info my-hook @@ -328,15 +328,15 @@ openclaw hooks info my-hook Kiểm tra các tệp nhị phân bị thiếu (PATH), biến môi trường, giá trị cấu hình hoặc khả năng tương thích hệ điều hành. -### Hook không thực thi +### Móc nối không thực thi -1. Xác minh hook đã được bật: `openclaw hooks list` -2. Khởi động lại tiến trình gateway của bạn để tải lại hook. -3. Kiểm tra nhật ký gateway: `./scripts/clawlog.sh | grep hook` +1. Xác minh móc nối đã được bật: `openclaw hooks list` +2. Khởi động lại tiến trình Gateway để các móc nối được tải lại. +3. Kiểm tra nhật ký Gateway: `./scripts/clawlog.sh | grep hook` ## Liên quan -- [Tham chiếu CLI: hooks](/vi/cli/hooks) -- [Webhooks](/vi/automation/cron-jobs#webhooks) -- [Plugin hooks](/vi/plugins/hooks) — các hook vòng đời Plugin trong tiến trình +- [Tham chiếu CLI: móc nối](/vi/cli/hooks) +- [Webhook](/vi/automation/cron-jobs#webhooks) +- [Móc nối Plugin](/vi/plugins/hooks) — móc nối vòng đời Plugin trong tiến trình - [Cấu hình](/vi/gateway/configuration-reference#hooks) diff --git a/docs/vi/channels/troubleshooting.md b/docs/vi/channels/troubleshooting.md index 395080136..dd01bf6eb 100644 --- a/docs/vi/channels/troubleshooting.md +++ b/docs/vi/channels/troubleshooting.md @@ -1,23 +1,23 @@ --- read_when: - - Bộ truyền tải kênh báo đã kết nối nhưng không gửi được phản hồi - - Bạn cần các bước kiểm tra riêng theo kênh trước khi đọc tài liệu chuyên sâu về nhà cung cấp -summary: Khắc phục sự cố nhanh ở cấp kênh với dấu hiệu lỗi và cách khắc phục cho từng kênh + - Bộ vận chuyển kênh báo đã kết nối nhưng phản hồi không gửi được + - Cần kiểm tra theo từng kênh trước khi đi sâu vào tài liệu nhà cung cấp +summary: Khắc phục sự cố nhanh ở cấp kênh với các dấu hiệu lỗi và cách khắc phục theo từng kênh title: Khắc phục sự cố kênh x-i18n: - generated_at: "2026-05-04T02:22:31Z" + generated_at: "2026-05-05T08:25:34Z" model: gpt-5.5 provider: openai - source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2 + source_hash: 360184c41ce6929c696688af597c5104a8a28b54620c354f7ee400a2e5490519 source_path: channels/troubleshooting.md workflow: 16 --- -Sử dụng trang này khi một kênh kết nối được nhưng hoạt động không đúng. +Sử dụng trang này khi một kênh kết nối được nhưng hành vi không đúng. -## Chuỗi lệnh +## Thang lệnh -Trước tiên, chạy các lệnh này theo thứ tự: +Chạy các lệnh này theo thứ tự trước: ```bash openclaw status @@ -27,7 +27,7 @@ openclaw doctor openclaw channels status --probe ``` -Mốc cơ sở khỏe mạnh: +Đường cơ sở khỏe mạnh: - `Runtime: running` - `Connectivity probe: ok` @@ -38,12 +38,13 @@ Mốc cơ sở khỏe mạnh: ### Dấu hiệu lỗi WhatsApp -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| Đã kết nối nhưng không trả lời DM | `openclaw pairing list whatsapp` | Phê duyệt người gửi hoặc chuyển chính sách/allowlist DM. | -| Tin nhắn nhóm bị bỏ qua | Kiểm tra `requireMention` + mẫu mention trong cấu hình | Mention bot hoặc nới lỏng chính sách mention cho nhóm đó. | -| Đăng nhập QR hết thời gian chờ với 408 | Kiểm tra env `HTTPS_PROXY` / `HTTP_PROXY` của Gateway | Đặt một proxy có thể truy cập; chỉ dùng `NO_PROXY` cho các trường hợp bỏ qua. | -| Ngắt kết nối/đăng nhập lại ngẫu nhiên | `openclaw channels status --probe` + nhật ký | Các lần kết nối lại gần đây vẫn được gắn cờ ngay cả khi hiện đang kết nối; theo dõi nhật ký, khởi động lại Gateway, rồi liên kết lại nếu tình trạng chập chờn tiếp diễn. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Đã kết nối nhưng không trả lời DM | `openclaw pairing list whatsapp` | Phê duyệt người gửi hoặc đổi chính sách/allowlist DM. | +| Tin nhắn nhóm bị bỏ qua | Kiểm tra `requireMention` + mẫu nhắc đến trong cấu hình | Nhắc đến bot hoặc nới lỏng chính sách nhắc đến cho nhóm đó. | +| Đăng nhập QR hết thời gian với 408 | Kiểm tra env `HTTPS_PROXY` / `HTTP_PROXY` của gateway | Đặt proxy có thể truy cập; chỉ dùng `NO_PROXY` cho các trường hợp bỏ qua. | +| Ngắt kết nối/vòng lặp đăng nhập lại ngẫu nhiên | `openclaw channels status --probe` + nhật ký | Các lần kết nối lại gần đây vẫn được đánh dấu ngay cả khi hiện đang kết nối; theo dõi nhật ký, khởi động lại gateway, rồi liên kết lại nếu tình trạng chập chờn tiếp diễn. | +| Phản hồi đến trễ vài giây/phút | `openclaw doctor --fix` | Doctor dừng các client TUI cục bộ cũ đã xác minh khi chúng làm suy giảm vòng lặp sự kiện Gateway. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố WhatsApp](/vi/channels/whatsapp#troubleshooting) @@ -51,15 +52,15 @@ Khắc phục sự cố đầy đủ: [Khắc phục sự cố WhatsApp](/vi/cha ### Dấu hiệu lỗi Telegram -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | -| `/start` nhưng không có luồng trả lời dùng được | `openclaw pairing list telegram` | Phê duyệt ghép nối hoặc thay đổi chính sách DM. | -| Bot trực tuyến nhưng nhóm vẫn im lặng | Xác minh yêu cầu mention và chế độ quyền riêng tư của bot | Tắt chế độ quyền riêng tư để nhóm có thể hiển thị, hoặc mention bot. | -| Gửi thất bại với lỗi mạng | Kiểm tra nhật ký để tìm lỗi gọi Telegram API | Sửa định tuyến DNS/IPv6/proxy tới `api.telegram.org`. | -| Khi khởi động báo cáo `getMe returned 401` | Kiểm tra nguồn token đã cấu hình | Sao chép lại hoặc tạo lại token BotFather và cập nhật `botToken`, `tokenFile`, hoặc `TELEGRAM_BOT_TOKEN` của tài khoản mặc định. | -| Polling bị dừng hoặc kết nối lại chậm | `openclaw logs --follow` để xem chẩn đoán polling | Nâng cấp; nếu các lần khởi động lại là dương tính giả, tinh chỉnh `pollingStallThresholdMs`. Tình trạng dừng kéo dài vẫn chỉ ra proxy/DNS/IPv6. | -| `setMyCommands` bị từ chối khi khởi động | Kiểm tra nhật ký để tìm `BOT_COMMANDS_TOO_MUCH` | Giảm số lệnh Telegram của Plugin/skill/tùy chỉnh hoặc tắt menu gốc. | -| Đã nâng cấp và allowlist chặn bạn | `openclaw security audit` và allowlist cấu hình | Chạy `openclaw doctor --fix` hoặc thay `@username` bằng ID người gửi dạng số. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| `/start` nhưng không có luồng phản hồi dùng được | `openclaw pairing list telegram` | Phê duyệt ghép nối hoặc đổi chính sách DM. | +| Bot online nhưng nhóm vẫn im lặng | Xác minh yêu cầu nhắc đến và chế độ riêng tư của bot | Tắt chế độ riêng tư để nhóm nhìn thấy hoặc nhắc đến bot. | +| Gửi thất bại với lỗi mạng | Kiểm tra nhật ký để tìm lỗi gọi Telegram API | Sửa định tuyến DNS/IPv6/proxy tới `api.telegram.org`. | +| Khởi động báo `getMe returned 401` | Kiểm tra nguồn token đã cấu hình | Sao chép lại hoặc tạo lại token BotFather và cập nhật `botToken`, `tokenFile`, hoặc default-account `TELEGRAM_BOT_TOKEN`. | +| Polling bị treo hoặc kết nối lại chậm | `openclaw logs --follow` để xem chẩn đoán polling | Nâng cấp; nếu khởi động lại là dương tính giả, điều chỉnh `pollingStallThresholdMs`. Tình trạng treo kéo dài vẫn chỉ ra proxy/DNS/IPv6. | +| `setMyCommands` bị từ chối khi khởi động | Kiểm tra nhật ký để tìm `BOT_COMMANDS_TOO_MUCH` | Giảm số lệnh Telegram của plugin/skill/tùy chỉnh hoặc tắt menu gốc. | +| Sau khi nâng cấp, allowlist chặn bạn | `openclaw security audit` và allowlist cấu hình | Chạy `openclaw doctor --fix` hoặc thay `@username` bằng ID người gửi dạng số. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Telegram](/vi/channels/telegram#troubleshooting) @@ -67,12 +68,12 @@ Khắc phục sự cố đầy đủ: [Khắc phục sự cố Telegram](/vi/cha ### Dấu hiệu lỗi Discord -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ---------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bot trực tuyến nhưng không trả lời trong guild | `openclaw channels status --probe` | Cho phép guild/kênh và xác minh message content intent. | -| Tin nhắn nhóm bị bỏ qua | Kiểm tra nhật ký để tìm các lần chặn do cổng mention | Mention bot hoặc đặt `requireMention: false` cho guild/kênh. | -| Có nhập/chỉ dùng token nhưng không có tin nhắn Discord | Nhật ký phiên hiển thị văn bản của trợ lý với `didSendViaMessagingTool: false` | Mô hình đã trả lời riêng thay vì gọi công cụ nhắn tin. Dùng mô hình đáng tin cậy cho tool-call, hoặc đặt `messages.groupChat.visibleReplies: "automatic"` để tự động đăng. | -| Thiếu trả lời DM | `openclaw pairing list discord` | Phê duyệt ghép nối DM hoặc điều chỉnh chính sách DM. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bot online nhưng không trả lời guild | `openclaw channels status --probe` | Cho phép guild/kênh và xác minh message content intent. | +| Tin nhắn nhóm bị bỏ qua | Kiểm tra nhật ký để tìm các lần loại bỏ do cổng nhắc đến | Nhắc đến bot hoặc đặt `requireMention: false` cho guild/kênh. | +| Có hoạt động gõ/sử dụng token nhưng không có tin nhắn Discord | Nhật ký phiên hiển thị văn bản trợ lý với `didSendViaMessagingTool: false` | Mô hình đã trả lời riêng thay vì gọi công cụ nhắn tin. Dùng mô hình đáng tin cậy với tool-call, hoặc đặt `messages.groupChat.visibleReplies: "automatic"` để tự động đăng. | +| Thiếu phản hồi DM | `openclaw pairing list discord` | Phê duyệt ghép nối DM hoặc điều chỉnh chính sách DM. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Discord](/vi/channels/discord#troubleshooting) @@ -80,11 +81,11 @@ Khắc phục sự cố đầy đủ: [Khắc phục sự cố Discord](/vi/chan ### Dấu hiệu lỗi Slack -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ---------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| Chế độ socket đã kết nối nhưng không có phản hồi | `openclaw channels status --probe` | Xác minh app token + bot token và các scope bắt buộc; theo dõi `botTokenStatus` / `appTokenStatus = configured_unavailable` trên các thiết lập dựa trên SecretRef. | -| DM bị chặn | `openclaw pairing list slack` | Phê duyệt ghép nối hoặc nới lỏng chính sách DM. | -| Tin nhắn kênh bị bỏ qua | Kiểm tra `groupPolicy` và allowlist kênh | Cho phép kênh hoặc chuyển chính sách sang `open`. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Socket mode đã kết nối nhưng không phản hồi | `openclaw channels status --probe` | Xác minh app token + bot token và các scope bắt buộc; theo dõi `botTokenStatus` / `appTokenStatus = configured_unavailable` trên thiết lập dùng SecretRef. | +| DM bị chặn | `openclaw pairing list slack` | Phê duyệt ghép nối hoặc nới lỏng chính sách DM. | +| Tin nhắn kênh bị bỏ qua | Kiểm tra `groupPolicy` và allowlist kênh | Cho phép kênh hoặc đổi chính sách sang `open`. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Slack](/vi/channels/slack#troubleshooting) @@ -92,11 +93,11 @@ Khắc phục sự cố đầy đủ: [Khắc phục sự cố Slack](/vi/channe ### Dấu hiệu lỗi iMessage và BlueBubbles -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| -------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------- | -| Không có sự kiện đến | Xác minh khả năng truy cập webhook/máy chủ và quyền của ứng dụng | Sửa URL webhook hoặc trạng thái máy chủ BlueBubbles. | -| Có thể gửi nhưng không nhận trên macOS | Kiểm tra quyền riêng tư macOS cho tự động hóa Messages | Cấp lại quyền TCC và khởi động lại tiến trình kênh. | -| Người gửi DM bị chặn | `openclaw pairing list imessage` hoặc `openclaw pairing list bluebubbles` | Phê duyệt ghép nối hoặc cập nhật allowlist. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------- | +| Không có sự kiện đến | Xác minh khả năng truy cập webhook/server và quyền ứng dụng | Sửa URL webhook hoặc trạng thái server BlueBubbles. | +| Có thể gửi nhưng không nhận trên macOS | Kiểm tra quyền riêng tư macOS cho tự động hóa Messages | Cấp lại quyền TCC và khởi động lại tiến trình kênh. | +| Người gửi DM bị chặn | `openclaw pairing list imessage` hoặc `openclaw pairing list bluebubbles` | Phê duyệt ghép nối hoặc cập nhật allowlist. | Khắc phục sự cố đầy đủ: @@ -107,11 +108,11 @@ Khắc phục sự cố đầy đủ: ### Dấu hiệu lỗi Signal -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------ | -| Daemon có thể truy cập nhưng bot im lặng | `openclaw channels status --probe` | Xác minh URL/tài khoản daemon `signal-cli` và chế độ nhận. | -| DM bị chặn | `openclaw pairing list signal` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | -| Trả lời nhóm không kích hoạt | Kiểm tra allowlist nhóm và mẫu mention | Thêm người gửi/nhóm hoặc nới lỏng cổng kiểm soát. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | ---------------------------------------- | --------------------------------------------------------- | +| Daemon truy cập được nhưng bot im lặng | `openclaw channels status --probe` | Xác minh URL/tài khoản daemon `signal-cli` và chế độ nhận. | +| DM bị chặn | `openclaw pairing list signal` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | +| Phản hồi nhóm không kích hoạt | Kiểm tra allowlist nhóm và mẫu nhắc đến | Thêm người gửi/nhóm hoặc nới lỏng cổng kiểm soát. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố Signal](/vi/channels/signal#troubleshooting) @@ -119,12 +120,12 @@ Khắc phục sự cố đầy đủ: [Khắc phục sự cố Signal](/vi/chann ### Dấu hiệu lỗi QQ Bot -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ----------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- | -| Bot trả lời "gone to Mars" | Xác minh `appId` và `clientSecret` trong cấu hình | Đặt thông tin xác thực hoặc khởi động lại Gateway. | -| Không có tin nhắn đến | `openclaw channels status --probe` | Xác minh thông tin xác thực trên QQ Open Platform. | -| Giọng nói không được phiên âm | Kiểm tra cấu hình nhà cung cấp STT | Cấu hình `channels.qqbot.stt` hoặc `tools.media.audio`. | -| Tin nhắn chủ động không đến | Kiểm tra yêu cầu tương tác của nền tảng QQ | QQ có thể chặn tin nhắn do bot khởi tạo nếu không có tương tác gần đây. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- | +| Bot trả lời "gone to Mars" | Xác minh `appId` và `clientSecret` trong cấu hình | Đặt thông tin xác thực hoặc khởi động lại gateway. | +| Không có tin nhắn đến | `openclaw channels status --probe` | Xác minh thông tin xác thực trên QQ Open Platform. | +| Giọng nói không được phiên âm | Kiểm tra cấu hình nhà cung cấp STT | Cấu hình `channels.qqbot.stt` hoặc `tools.media.audio`. | +| Tin nhắn chủ động không đến | Kiểm tra yêu cầu tương tác của nền tảng QQ | QQ có thể chặn tin nhắn do bot khởi tạo nếu không có tương tác gần đây. | Khắc phục sự cố đầy đủ: [Khắc phục sự cố QQ Bot](/vi/channels/qqbot#troubleshooting) @@ -132,13 +133,13 @@ Khắc phục sự cố đầy đủ: [Khắc phục sự cố QQ Bot](/vi/chann ### Dấu hiệu lỗi Matrix -| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | -| ----------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | -| Đã đăng nhập nhưng bỏ qua tin nhắn phòng | `openclaw channels status --probe` | Kiểm tra `groupPolicy`, allowlist phòng và cổng mention. | -| DM không được xử lý | `openclaw pairing list matrix` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | -| Phòng được mã hóa bị lỗi | `openclaw matrix verify status` | Xác minh lại thiết bị, rồi kiểm tra `openclaw matrix verify backup status`. | -| Khôi phục bản sao lưu đang chờ/bị hỏng | `openclaw matrix verify backup status` | Chạy `openclaw matrix verify backup restore` hoặc chạy lại với khóa khôi phục. | -| Cross-signing/bootstrap trông sai | `openclaw matrix verify bootstrap` | Sửa secret storage, cross-signing và trạng thái sao lưu trong một lượt. | +| Triệu chứng | Kiểm tra nhanh nhất | Cách khắc phục | +| ----------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- | +| Đã đăng nhập nhưng bỏ qua tin nhắn phòng | `openclaw channels status --probe` | Kiểm tra `groupPolicy`, allowlist phòng và cổng nhắc đến. | +| DM không được xử lý | `openclaw pairing list matrix` | Phê duyệt người gửi hoặc điều chỉnh chính sách DM. | +| Phòng mã hóa bị lỗi | `openclaw matrix verify status` | Xác minh lại thiết bị, rồi kiểm tra `openclaw matrix verify backup status`. | +| Khôi phục bản sao lưu đang chờ/bị lỗi | `openclaw matrix verify backup status` | Chạy `openclaw matrix verify backup restore` hoặc chạy lại với khóa khôi phục. | +| Cross-signing/bootstrap trông sai | `openclaw matrix verify bootstrap` | Sửa secret storage, cross-signing và trạng thái sao lưu trong một lượt. | Thiết lập và cấu hình đầy đủ: [Matrix](/vi/channels/matrix) diff --git a/docs/vi/cli/doctor.md b/docs/vi/cli/doctor.md index abef17f56..bb1a39727 100644 --- a/docs/vi/cli/doctor.md +++ b/docs/vi/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - Bạn gặp sự cố kết nối/xác thực và muốn được hướng dẫn khắc phục - - Bạn đã cập nhật và muốn kiểm tra nhanh -summary: Tài liệu tham khảo CLI cho `openclaw doctor` (kiểm tra tình trạng + sửa chữa có hướng dẫn) + - Bạn gặp sự cố về kết nối/xác thực và muốn được hướng dẫn cách khắc phục + - Bạn đã cập nhật và muốn kiểm tra sơ bộ +summary: Tài liệu tham chiếu CLI cho `openclaw doctor` (kiểm tra tình trạng + sửa chữa có hướng dẫn) title: Chẩn đoán x-i18n: - generated_at: "2026-05-05T01:44:14Z" + generated_at: "2026-05-05T08:25:32Z" model: gpt-5.5 provider: openai - source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5 + source_hash: d6101008d1cb7e08f9902a8a29785710f325966524b003b87b5c628fe906ab78 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Kiểm tra sức khỏe + sửa nhanh cho Gateway và các kênh. +Kiểm tra tình trạng + sửa nhanh cho gateway và các kênh. Liên quan: @@ -35,44 +35,45 @@ openclaw doctor --generate-gateway-token ## Tùy chọn - `--no-workspace-suggestions`: tắt gợi ý bộ nhớ/tìm kiếm workspace -- `--yes`: chấp nhận mặc định mà không hỏi -- `--repair`: áp dụng các sửa chữa được khuyến nghị không liên quan đến dịch vụ mà không hỏi; cài đặt và ghi lại dịch vụ Gateway vẫn cần xác nhận tương tác hoặc lệnh Gateway rõ ràng +- `--yes`: chấp nhận mặc định mà không nhắc +- `--repair`: áp dụng các sửa chữa không thuộc dịch vụ được khuyến nghị mà không nhắc; việc cài đặt và ghi lại dịch vụ gateway vẫn cần xác nhận tương tác hoặc lệnh gateway rõ ràng - `--fix`: bí danh cho `--repair` -- `--force`: áp dụng sửa chữa mạnh tay, bao gồm ghi đè cấu hình dịch vụ tùy chỉnh khi cần -- `--non-interactive`: chạy không có lời nhắc; chỉ áp dụng di chuyển an toàn và sửa chữa không liên quan đến dịch vụ -- `--generate-gateway-token`: tạo và cấu hình token Gateway -- `--deep`: quét các dịch vụ hệ thống để tìm các bản cài đặt Gateway bổ sung +- `--force`: áp dụng các sửa chữa mạnh, bao gồm ghi đè cấu hình dịch vụ tùy chỉnh khi cần +- `--non-interactive`: chạy không có lời nhắc; chỉ áp dụng di chuyển an toàn và sửa chữa không thuộc dịch vụ +- `--generate-gateway-token`: tạo và cấu hình token gateway +- `--deep`: quét dịch vụ hệ thống để tìm các bản cài đặt gateway bổ sung và báo cáo các lần chuyển giao khởi động lại gần đây của supervisor Gateway Ghi chú: -- Lời nhắc tương tác (như sửa keychain/OAuth) chỉ chạy khi stdin là TTY và **không** đặt `--non-interactive`. Các lần chạy không giao diện (cron, Telegram, không có terminal) sẽ bỏ qua lời nhắc. -- Hiệu năng: các lần chạy `doctor` không tương tác bỏ qua việc tải Plugin sớm để kiểm tra sức khỏe không giao diện vẫn nhanh. Phiên tương tác vẫn tải đầy đủ Plugin khi một kiểm tra cần phần đóng góp của chúng. -- `--fix` (bí danh cho `--repair`) ghi bản sao lưu vào `~/.openclaw/openclaw.json.bak` và loại bỏ các khóa cấu hình không xác định, liệt kê từng mục bị loại bỏ. -- `doctor --fix --non-interactive` báo cáo các định nghĩa dịch vụ Gateway bị thiếu hoặc cũ nhưng không cài đặt hay ghi lại chúng bên ngoài chế độ sửa chữa cập nhật. Chạy `openclaw gateway install` cho dịch vụ bị thiếu, hoặc `openclaw gateway install --force` khi bạn chủ ý muốn thay thế trình khởi chạy. -- Kiểm tra tính toàn vẹn trạng thái hiện phát hiện các tệp transcript mồ côi trong thư mục phiên. Việc lưu trữ chúng dưới dạng `.deleted.` cần xác nhận tương tác; `--fix`, `--yes`, và các lần chạy không giao diện giữ nguyên chúng. -- Doctor cũng quét `~/.openclaw/cron/jobs.json` (hoặc `cron.store`) để tìm dạng tác vụ cron cũ và có thể ghi lại chúng tại chỗ trước khi bộ lập lịch phải tự chuẩn hóa chúng lúc chạy. -- Trên Linux, doctor cảnh báo khi crontab của người dùng vẫn chạy `~/.openclaw/bin/ensure-whatsapp.sh` cũ; script đó không còn được bảo trì và có thể ghi nhật ký sai về sự cố Gateway WhatsApp khi cron thiếu môi trường user-bus của systemd. -- Doctor dọn trạng thái staging phụ thuộc Plugin cũ do các phiên bản OpenClaw cũ tạo ra. Nó cũng sửa các Plugin có thể tải xuống bị thiếu được tham chiếu bởi cấu hình, chẳng hạn như `plugins.entries`, các kênh đã cấu hình, thiết lập provider/search đã cấu hình, hoặc runtime agent đã cấu hình. Trong quá trình cập nhật gói, doctor bỏ qua sửa chữa Plugin của trình quản lý gói cho đến khi hoán đổi gói hoàn tất; chạy lại `openclaw doctor --fix` sau đó nếu một Plugin đã cấu hình vẫn cần khôi phục. Nếu tải xuống thất bại, doctor báo cáo lỗi cài đặt và giữ mục Plugin đã cấu hình cho lần sửa chữa tiếp theo. -- Doctor sửa cấu hình Plugin cũ bằng cách xóa các id Plugin bị thiếu khỏi `plugins.allow`/`plugins.entries`, cùng với cấu hình kênh treo, mục tiêu Heartbeat, và ghi đè mô hình kênh tương ứng khi việc phát hiện Plugin hoạt động bình thường. -- Doctor cách ly cấu hình Plugin không hợp lệ bằng cách tắt mục `plugins.entries.` bị ảnh hưởng và xóa payload `config` không hợp lệ của nó. Khởi động Gateway vốn đã chỉ bỏ qua Plugin lỗi đó để các Plugin và kênh khác có thể tiếp tục chạy. -- Đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một supervisor khác sở hữu vòng đời Gateway. Doctor vẫn báo cáo sức khỏe Gateway/dịch vụ và áp dụng sửa chữa không liên quan đến dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ và dọn dịch vụ cũ. -- Trên Linux, doctor bỏ qua các systemd unit không hoạt động nhưng giống Gateway bổ sung và không ghi lại metadata lệnh/entrypoint cho dịch vụ Gateway systemd đang chạy trong quá trình sửa chữa. Dừng dịch vụ trước hoặc dùng `openclaw gateway install --force` khi bạn chủ ý muốn thay thế trình khởi chạy đang hoạt động. -- Doctor tự động di chuyển cấu hình Talk phẳng cũ (`talk.voiceId`, `talk.modelId`, và các mục liên quan) vào `talk.provider` + `talk.providers.`. -- Các lần chạy lặp lại `doctor --fix` không còn báo cáo/áp dụng chuẩn hóa Talk khi khác biệt duy nhất là thứ tự khóa đối tượng. -- Doctor bao gồm kiểm tra mức sẵn sàng tìm kiếm bộ nhớ và có thể khuyến nghị `openclaw configure --section model` khi thiếu thông tin xác thực embedding. -- Doctor cảnh báo khi chưa cấu hình chủ sở hữu lệnh. Chủ sở hữu lệnh là tài khoản người vận hành được phép chạy các lệnh chỉ dành cho chủ sở hữu và phê duyệt hành động nguy hiểm. Ghép đôi DM chỉ cho phép ai đó nói chuyện với bot; nếu bạn đã phê duyệt một người gửi trước khi bootstrap chủ sở hữu đầu tiên tồn tại, hãy đặt rõ `commands.ownerAllowFrom`. -- Doctor cảnh báo khi agent chế độ Codex được cấu hình và tài sản Codex CLI cá nhân tồn tại trong thư mục home Codex của người vận hành. Các lần khởi chạy app-server Codex cục bộ dùng home riêng biệt cho từng agent, vì vậy dùng `openclaw migrate codex --dry-run` để kiểm kê tài sản nên được chủ ý nâng cấp. -- Doctor cảnh báo khi Skills được phép cho agent mặc định không khả dụng trong môi trường runtime hiện tại vì thiếu bin, biến môi trường, cấu hình, hoặc yêu cầu hệ điều hành. `doctor --fix` có thể tắt các Skills không khả dụng đó bằng `skills.entries..enabled=false`; thay vào đó hãy cài đặt/cấu hình yêu cầu còn thiếu khi bạn muốn giữ skill hoạt động. +- Lời nhắc tương tác (như sửa keychain/OAuth) chỉ chạy khi stdin là TTY và **không** đặt `--non-interactive`. Các lần chạy không có giao diện (cron, Telegram, không có terminal) sẽ bỏ qua lời nhắc. +- Hiệu năng: các lần chạy `doctor` không tương tác bỏ qua việc tải plugin sớm để kiểm tra tình trạng không có giao diện luôn nhanh. Phiên tương tác vẫn tải đầy đủ plugin khi một kiểm tra cần phần đóng góp của chúng. +- `--fix` (bí danh cho `--repair`) ghi bản sao lưu vào `~/.openclaw/openclaw.json.bak` và loại bỏ các khóa cấu hình không xác định, liệt kê từng mục bị xóa. +- `doctor --fix --non-interactive` báo cáo các định nghĩa dịch vụ gateway bị thiếu hoặc cũ nhưng không cài đặt hoặc ghi lại chúng bên ngoài chế độ sửa chữa cập nhật. Chạy `openclaw gateway install` cho dịch vụ bị thiếu, hoặc `openclaw gateway install --force` khi bạn chủ ý muốn thay thế trình khởi chạy. +- Các kiểm tra toàn vẹn trạng thái hiện phát hiện tệp transcript mồ côi trong thư mục phiên. Việc lưu trữ chúng dưới dạng `.deleted.` cần xác nhận tương tác; `--fix`, `--yes`, và các lần chạy không có giao diện sẽ giữ nguyên chúng. +- Doctor cũng quét `~/.openclaw/cron/jobs.json` (hoặc `cron.store`) để tìm các dạng cron job cũ và có thể ghi lại chúng tại chỗ trước khi scheduler phải tự động chuẩn hóa chúng lúc chạy. +- Trên Linux, doctor cảnh báo khi crontab của người dùng vẫn chạy `~/.openclaw/bin/ensure-whatsapp.sh` cũ; script đó không còn được duy trì và có thể ghi log sai về sự cố ngừng hoạt động của gateway WhatsApp khi cron thiếu môi trường user-bus của systemd. +- Khi WhatsApp được bật, doctor kiểm tra vòng lặp sự kiện Gateway bị suy giảm với các client `openclaw-tui` cục bộ vẫn đang chạy. `doctor --fix` chỉ dừng các client TUI cục bộ đã xác minh để trả lời WhatsApp không bị xếp hàng sau các vòng lặp làm mới TUI cũ. +- Doctor dọn trạng thái staging phụ thuộc plugin cũ do các phiên bản OpenClaw cũ tạo. Nó cũng sửa các plugin có thể tải xuống bị thiếu đang được tham chiếu bởi cấu hình, chẳng hạn như `plugins.entries`, các kênh đã cấu hình, cài đặt provider/tìm kiếm đã cấu hình, hoặc runtime agent đã cấu hình. Trong quá trình cập nhật gói, doctor bỏ qua sửa chữa plugin của package-manager cho đến khi việc hoán đổi gói hoàn tất; chạy lại `openclaw doctor --fix` sau đó nếu plugin đã cấu hình vẫn cần khôi phục. Nếu tải xuống thất bại, doctor báo cáo lỗi cài đặt và giữ lại mục plugin đã cấu hình cho lần sửa chữa tiếp theo. +- Doctor sửa cấu hình plugin cũ bằng cách xóa các id plugin bị thiếu khỏi `plugins.allow`/`plugins.entries`, cùng với cấu hình kênh treo tương ứng, mục tiêu heartbeat, và ghi đè mô hình kênh khi phát hiện plugin hoạt động bình thường. +- Doctor cách ly cấu hình plugin không hợp lệ bằng cách tắt mục `plugins.entries.` bị ảnh hưởng và xóa payload `config` không hợp lệ của nó. Khởi động Gateway vốn đã chỉ bỏ qua plugin lỗi đó để các plugin và kênh khác có thể tiếp tục chạy. +- Đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một supervisor khác sở hữu vòng đời gateway. Doctor vẫn báo cáo tình trạng gateway/dịch vụ và áp dụng sửa chữa không thuộc dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ và dọn dẹp dịch vụ cũ. +- Trên Linux, doctor bỏ qua các unit systemd giống gateway bổ sung không hoạt động và không ghi lại metadata lệnh/entrypoint cho dịch vụ gateway systemd đang chạy trong quá trình sửa chữa. Dừng dịch vụ trước hoặc dùng `openclaw gateway install --force` khi bạn chủ ý muốn thay thế trình khởi chạy đang hoạt động. +- Doctor tự động di chuyển cấu hình Talk phẳng cũ (`talk.voiceId`, `talk.modelId`, và các mục liên quan) sang `talk.provider` + `talk.providers.`. +- Các lần chạy lại `doctor --fix` không còn báo cáo/áp dụng chuẩn hóa Talk khi khác biệt duy nhất là thứ tự khóa đối tượng. +- Doctor bao gồm kiểm tra mức độ sẵn sàng của tìm kiếm bộ nhớ và có thể khuyến nghị `openclaw configure --section model` khi thiếu thông tin đăng nhập embedding. +- Doctor cảnh báo khi chưa cấu hình chủ sở hữu lệnh. Chủ sở hữu lệnh là tài khoản người vận hành được phép chạy lệnh chỉ dành cho owner và phê duyệt hành động nguy hiểm. Ghép cặp DM chỉ cho phép ai đó nói chuyện với bot; nếu bạn đã phê duyệt một người gửi trước khi bootstrap owner đầu tiên tồn tại, hãy đặt rõ `commands.ownerAllowFrom`. +- Doctor cảnh báo khi các agent chế độ Codex được cấu hình và tài sản Codex CLI cá nhân tồn tại trong Codex home của người vận hành. Các lần khởi chạy app-server Codex cục bộ dùng home riêng biệt cho từng agent, vì vậy hãy dùng `openclaw migrate codex --dry-run` để kiểm kê tài sản cần được đưa vào có chủ đích. +- Doctor cảnh báo khi skills được phép cho agent mặc định không khả dụng trong môi trường runtime hiện tại vì thiếu bin, biến môi trường, cấu hình, hoặc yêu cầu hệ điều hành. `doctor --fix` có thể tắt các skill không khả dụng đó bằng `skills.entries..enabled=false`; thay vào đó hãy cài đặt/cấu hình yêu cầu còn thiếu khi bạn muốn giữ skill hoạt động. - Nếu chế độ sandbox được bật nhưng Docker không khả dụng, doctor báo cáo cảnh báo tín hiệu cao kèm cách khắc phục (`install Docker` hoặc `openclaw config set agents.defaults.sandbox.mode off`). -- Nếu có các tệp registry sandbox cũ (`~/.openclaw/sandbox/containers.json` hoặc `~/.openclaw/sandbox/browsers.json`), doctor báo cáo chúng; `openclaw doctor --fix` di chuyển các mục hợp lệ vào thư mục registry phân mảnh và cách ly các tệp cũ không hợp lệ. -- Nếu `gateway.auth.token`/`gateway.auth.password` được SecretRef quản lý và không khả dụng trong đường dẫn lệnh hiện tại, doctor báo cáo cảnh báo chỉ đọc và không ghi thông tin xác thực dự phòng dạng văn bản thuần. -- Nếu kiểm tra SecretRef của kênh thất bại trong đường dẫn sửa chữa, doctor tiếp tục và báo cáo cảnh báo thay vì thoát sớm. -- Sau các di chuyển thư mục trạng thái, doctor cảnh báo khi tài khoản Telegram hoặc Discord mặc định đã bật phụ thuộc vào env fallback và `TELEGRAM_BOT_TOKEN` hoặc `DISCORD_BOT_TOKEN` không khả dụng với tiến trình doctor. -- Tự động phân giải username `allowFrom` của Telegram (`doctor --fix`) cần token Telegram có thể phân giải trong đường dẫn lệnh hiện tại. Nếu không thể kiểm tra token, doctor báo cáo cảnh báo và bỏ qua tự động phân giải cho lần chạy đó. +- Nếu có tệp registry sandbox cũ (`~/.openclaw/sandbox/containers.json` hoặc `~/.openclaw/sandbox/browsers.json`), doctor báo cáo chúng; `openclaw doctor --fix` di chuyển các mục hợp lệ vào thư mục registry được phân mảnh và cách ly các tệp cũ không hợp lệ. +- Nếu `gateway.auth.token`/`gateway.auth.password` được quản lý bởi SecretRef và không khả dụng trong đường dẫn lệnh hiện tại, doctor báo cáo cảnh báo chỉ đọc và không ghi thông tin đăng nhập dự phòng dạng plaintext. +- Nếu kiểm tra SecretRef của kênh thất bại trong đường dẫn sửa lỗi, doctor tiếp tục và báo cáo cảnh báo thay vì thoát sớm. +- Sau các lần di chuyển thư mục trạng thái, doctor cảnh báo khi tài khoản Telegram hoặc Discord mặc định đã bật phụ thuộc vào env fallback và `TELEGRAM_BOT_TOKEN` hoặc `DISCORD_BOT_TOKEN` không khả dụng cho tiến trình doctor. +- Tự động phân giải tên người dùng `allowFrom` của Telegram (`doctor --fix`) cần token Telegram có thể phân giải trong đường dẫn lệnh hiện tại. Nếu không thể kiểm tra token, doctor báo cáo cảnh báo và bỏ qua tự động phân giải cho lượt đó. ## macOS: ghi đè env `launchctl` -Nếu trước đây bạn đã chạy `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (hoặc `...PASSWORD`), giá trị đó ghi đè tệp cấu hình của bạn và có thể gây lỗi “unauthorized” dai dẳng. +Nếu trước đây bạn đã chạy `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (hoặc `...PASSWORD`), giá trị đó sẽ ghi đè tệp cấu hình của bạn và có thể gây lỗi “unauthorized” kéo dài. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -85,4 +86,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## Liên quan - [Tham chiếu CLI](/vi/cli) -- [Gateway doctor](/vi/gateway/doctor) +- [Doctor Gateway](/vi/gateway/doctor) diff --git a/docs/vi/cli/gateway.md b/docs/vi/cli/gateway.md index 2ef9f0bb5..62ff81fa3 100644 --- a/docs/vi/cli/gateway.md +++ b/docs/vi/cli/gateway.md @@ -1,31 +1,31 @@ --- read_when: - - Chạy Gateway từ CLI (môi trường phát triển hoặc máy chủ) - - Gỡ lỗi xác thực Gateway, chế độ ràng buộc và khả năng kết nối + - Chạy Gateway từ CLI (phát triển hoặc máy chủ) + - Gỡ lỗi xác thực Gateway, chế độ bind và khả năng kết nối - Khám phá các Gateway qua Bonjour (DNS-SD cục bộ + diện rộng) sidebarTitle: Gateway summary: OpenClaw Gateway CLI (`openclaw gateway`) — chạy, truy vấn và khám phá các Gateway title: Gateway x-i18n: - generated_at: "2026-05-05T01:44:30Z" + generated_at: "2026-05-05T08:25:36Z" model: gpt-5.5 provider: openai - source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038 + source_hash: 89f798724971151cdd297fcdbbc1fe79dedc19f57521f2ad2c1fff0f9acf9b24 source_path: cli/gateway.md workflow: 16 --- -Gateway là máy chủ WebSocket của OpenClaw (kênh, nút, phiên, hook). Các lệnh con trong trang này nằm dưới `openclaw gateway …`. +Gateway là máy chủ WebSocket của OpenClaw (kênh, Node, phiên, hook). Các lệnh con trên trang này nằm dưới `openclaw gateway …`. - + Thiết lập mDNS cục bộ + DNS-SD diện rộng. - - Cách OpenClaw quảng bá và tìm gateway. + + Cách OpenClaw quảng bá và tìm Gateway. - - Các khóa cấu hình gateway cấp cao nhất. + + Các khóa cấu hình Gateway cấp cao nhất. @@ -44,13 +44,13 @@ openclaw gateway run ``` - + - Theo mặc định, Gateway từ chối khởi động trừ khi `gateway.mode=local` được đặt trong `~/.openclaw/openclaw.json`. Dùng `--allow-unconfigured` cho các lần chạy ad-hoc/dev. - `openclaw onboard --mode local` và `openclaw setup` được kỳ vọng sẽ ghi `gateway.mode=local`. Nếu tệp tồn tại nhưng thiếu `gateway.mode`, hãy coi đó là cấu hình bị hỏng hoặc bị ghi đè và sửa nó thay vì ngầm giả định chế độ cục bộ. - - Nếu tệp tồn tại và thiếu `gateway.mode`, Gateway coi đó là hư hỏng cấu hình đáng ngờ và từ chối "đoán local" thay bạn. - - Việc bind vượt ra ngoài loopback mà không có xác thực sẽ bị chặn (rào chắn an toàn). - - `SIGUSR1` kích hoạt khởi động lại trong tiến trình khi được cho phép (`commands.restart` được bật theo mặc định; đặt `commands.restart: false` để chặn khởi động lại thủ công, trong khi công cụ/cấu hình gateway apply/update vẫn được phép). - - Các handler `SIGINT`/`SIGTERM` dừng tiến trình gateway, nhưng không khôi phục bất kỳ trạng thái terminal tùy chỉnh nào. Nếu bạn bọc CLI bằng TUI hoặc đầu vào raw-mode, hãy khôi phục terminal trước khi thoát. + - Nếu tệp tồn tại và thiếu `gateway.mode`, Gateway coi đó là hư hại cấu hình đáng ngờ và từ chối "đoán local" thay bạn. + - Việc bind vượt ra ngoài loopback mà không có xác thực sẽ bị chặn (hàng rào an toàn). + - `SIGUSR1` kích hoạt khởi động lại trong tiến trình khi được ủy quyền (`commands.restart` được bật theo mặc định; đặt `commands.restart: false` để chặn khởi động lại thủ công, trong khi áp dụng/cập nhật công cụ/cấu hình Gateway vẫn được phép). + - Các handler `SIGINT`/`SIGTERM` dừng tiến trình Gateway, nhưng chúng không khôi phục bất kỳ trạng thái terminal tùy chỉnh nào. Nếu bạn bọc CLI bằng TUI hoặc đầu vào raw-mode, hãy khôi phục terminal trước khi thoát. @@ -61,7 +61,7 @@ openclaw gateway run Cổng WebSocket (mặc định đến từ cấu hình/env; thường là `18789`). - Chế độ bind của listener. + Chế độ bind listener. Ghi đè chế độ xác thực. @@ -73,16 +73,16 @@ openclaw gateway run Ghi đè mật khẩu. - Đọc mật khẩu gateway từ một tệp. + Đọc mật khẩu Gateway từ một tệp. Công khai Gateway qua Tailscale. - Đặt lại cấu hình Tailscale serve/funnel khi tắt. + Đặt lại cấu hình serve/funnel của Tailscale khi tắt. - Cho phép gateway khởi động mà không có `gateway.mode=local` trong cấu hình. Chỉ bỏ qua guard khởi động cho bootstrap ad-hoc/dev; không ghi hoặc sửa tệp cấu hình. + Cho phép khởi động Gateway mà không có `gateway.mode=local` trong cấu hình. Chỉ bỏ qua chốt bảo vệ khởi động cho bootstrap ad-hoc/dev; không ghi hoặc sửa tệp cấu hình. Tạo cấu hình dev + workspace nếu thiếu (bỏ qua BOOTSTRAP.md). @@ -91,25 +91,25 @@ openclaw gateway run Đặt lại cấu hình dev + thông tin xác thực + phiên + workspace (yêu cầu `--dev`). - Kill mọi listener hiện có trên cổng đã chọn trước khi khởi động. + Dừng bất kỳ listener hiện có nào trên cổng đã chọn trước khi khởi động. - Nhật ký chi tiết. + Log chi tiết. - Chỉ hiển thị nhật ký backend CLI trong console (và bật stdout/stderr). + Chỉ hiển thị log backend CLI trong console (và bật stdout/stderr). - Kiểu nhật ký Websocket. + Kiểu log WebSocket. Bí danh cho `--ws-log compact`. - Ghi nhật ký các sự kiện luồng mô hình thô vào jsonl. + Ghi log các sự kiện stream model thô vào jsonl. - Đường dẫn jsonl của luồng thô. + Đường dẫn jsonl của stream thô. ## Khởi động lại Gateway @@ -120,41 +120,41 @@ openclaw gateway restart --safe openclaw gateway restart --force ``` -`openclaw gateway restart --safe` yêu cầu Gateway đang chạy preflight công việc OpenClaw đang hoạt động trước khi khởi động lại. Nếu các thao tác trong hàng đợi, phân phối phản hồi, lượt chạy nhúng, hoặc lượt chạy tác vụ đang hoạt động, Gateway báo cáo các blocker, gộp các yêu cầu khởi động lại an toàn bị trùng lặp, và khởi động lại sau khi công việc đang hoạt động được rút hết. `restart` thông thường giữ hành vi service-manager hiện có để tương thích. Chỉ dùng `--force` khi bạn rõ ràng muốn đường dẫn ghi đè ngay lập tức. +`openclaw gateway restart --safe` yêu cầu Gateway đang chạy preflight công việc OpenClaw đang hoạt động trước khi khởi động lại. Nếu có thao tác trong hàng đợi, phân phối phản hồi, lần chạy nhúng, hoặc lần chạy tác vụ đang hoạt động, Gateway báo cáo các điểm chặn, gộp các yêu cầu khởi động lại an toàn trùng lặp và khởi động lại sau khi công việc đang hoạt động đã thoát hết. `restart` thông thường giữ hành vi service-manager hiện có để tương thích. Chỉ dùng `--force` khi bạn rõ ràng muốn đường dẫn ghi đè tức thì. -`--password` inline có thể bị lộ trong danh sách tiến trình cục bộ. Ưu tiên `--password-file`, env, hoặc `gateway.auth.password` được hỗ trợ bởi SecretRef. +`--password` inline có thể bị lộ trong danh sách tiến trình cục bộ. Ưu tiên `--password-file`, env, hoặc `gateway.auth.password` dựa trên SecretRef. -### Profiling khởi động +### Lập hồ sơ khởi động -- Đặt `OPENCLAW_GATEWAY_STARTUP_TRACE=1` để ghi nhật ký thời gian từng pha trong khi Gateway khởi động, bao gồm độ trễ `eventLoopMax` theo từng pha và thời gian bảng tra cứu plugin cho installed-index, manifest registry, startup planning, và owner-map. -- Đặt `OPENCLAW_DIAGNOSTICS=timeline` cùng `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` để ghi timeline chẩn đoán khởi động JSONL theo best-effort cho các bộ kiểm thử QA bên ngoài. Bạn cũng có thể bật cờ bằng `diagnostics.flags: ["timeline"]` trong cấu hình; đường dẫn vẫn được cung cấp qua env. Thêm `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` để bao gồm các mẫu event-loop. -- Chạy `pnpm test:startup:gateway -- --runs 5 --warmup 1` để benchmark khởi động Gateway. Benchmark ghi lại đầu ra đầu tiên của tiến trình, `/healthz`, `/readyz`, thời gian startup trace, độ trễ event-loop, và chi tiết thời gian bảng tra cứu plugin. +- Đặt `OPENCLAW_GATEWAY_STARTUP_TRACE=1` để ghi log thời gian từng pha trong quá trình khởi động Gateway, bao gồm độ trễ `eventLoopMax` theo từng pha và thời gian bảng tra cứu plugin cho installed-index, manifest registry, startup planning và owner-map. +- Đặt `OPENCLAW_DIAGNOSTICS=timeline` với `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` để ghi timeline chẩn đoán khởi động JSONL best-effort cho các harness QA bên ngoài. Bạn cũng có thể bật cờ bằng `diagnostics.flags: ["timeline"]` trong cấu hình; đường dẫn vẫn được cung cấp qua env. Thêm `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` để bao gồm các mẫu event-loop. +- Chạy `pnpm test:startup:gateway -- --runs 5 --warmup 1` để benchmark quá trình khởi động Gateway. Benchmark ghi lại đầu ra tiến trình đầu tiên, `/healthz`, `/readyz`, thời gian startup trace, độ trễ event-loop, và chi tiết thời gian bảng tra cứu plugin. ## Truy vấn Gateway đang chạy -Tất cả lệnh truy vấn đều dùng WebSocket RPC. +Tất cả lệnh truy vấn dùng WebSocket RPC. - + - Mặc định: dễ đọc cho người dùng (có màu trong TTY). - - `--json`: JSON dễ đọc cho máy (không styling/spinner). + - `--json`: JSON để máy đọc (không styling/spinner). - `--no-color` (hoặc `NO_COLOR=1`): tắt ANSI trong khi vẫn giữ bố cục cho người dùng. - + - `--url `: URL WebSocket của Gateway. - `--token `: token Gateway. - `--password `: mật khẩu Gateway. - - `--timeout `: timeout/ngân sách (khác nhau theo lệnh). + - `--timeout `: timeout/ngân sách thời gian (khác nhau theo từng lệnh). - `--expect-final`: chờ phản hồi "final" (lệnh gọi agent). -Khi bạn đặt `--url`, CLI không fallback về thông tin xác thực trong cấu hình hoặc môi trường. Truyền rõ ràng `--token` hoặc `--password`. Thiếu thông tin xác thực rõ ràng là lỗi. +Khi bạn đặt `--url`, CLI không fallback về thông tin xác thực từ cấu hình hoặc môi trường. Truyền `--token` hoặc `--password` một cách rõ ràng. Thiếu thông tin xác thực tường minh là lỗi. ### `gateway health` @@ -163,11 +163,11 @@ Khi bạn đặt `--url`, CLI không fallback về thông tin xác thực trong openclaw gateway health --url ws://127.0.0.1:18789 ``` -Endpoint HTTP `/healthz` là probe liveness: nó trả về khi máy chủ có thể trả lời HTTP. Endpoint HTTP `/readyz` nghiêm ngặt hơn và vẫn đỏ trong khi startup plugin sidecar, kênh, hoặc hook đã cấu hình vẫn đang ổn định. Phản hồi readiness chi tiết cục bộ hoặc đã xác thực bao gồm khối chẩn đoán `eventLoop` với độ trễ event-loop, mức sử dụng event-loop, tỷ lệ lõi CPU, và cờ `degraded`. +Endpoint HTTP `/healthz` là liveness probe: nó trả về khi máy chủ có thể trả lời HTTP. Endpoint HTTP `/readyz` nghiêm ngặt hơn và vẫn đỏ khi các sidecar plugin khởi động, kênh hoặc hook đã cấu hình vẫn đang ổn định. Phản hồi readiness chi tiết cục bộ hoặc đã xác thực bao gồm một khối chẩn đoán `eventLoop` với độ trễ event-loop, mức sử dụng event-loop, tỷ lệ CPU core và cờ `degraded`. ### `gateway usage-cost` -Lấy tóm tắt chi phí sử dụng từ nhật ký phiên. +Lấy tóm tắt chi phí sử dụng từ log phiên. ```bash openclaw gateway usage-cost @@ -181,7 +181,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -Lấy trình ghi ổn định chẩn đoán gần đây từ Gateway đang chạy. +Lấy bộ ghi ổn định chẩn đoán gần đây từ Gateway đang chạy. ```bash openclaw gateway stability @@ -198,29 +198,29 @@ openclaw gateway stability --json Lọc theo loại sự kiện chẩn đoán, chẳng hạn như `payload.large` hoặc `diagnostic.memory.pressure`. - Chỉ bao gồm các sự kiện sau một số thứ tự chẩn đoán. + Chỉ bao gồm sự kiện sau một số thứ tự chẩn đoán. - Đọc bundle ổn định đã lưu thay vì gọi Gateway đang chạy. Dùng `--bundle latest` (hoặc chỉ `--bundle`) cho bundle mới nhất trong thư mục trạng thái, hoặc truyền trực tiếp đường dẫn JSON của bundle. + Đọc một stability bundle đã lưu thay vì gọi Gateway đang chạy. Dùng `--bundle latest` (hoặc chỉ `--bundle`) cho bundle mới nhất trong thư mục trạng thái, hoặc truyền trực tiếp đường dẫn JSON bundle. - Ghi một zip chẩn đoán hỗ trợ có thể chia sẻ thay vì in chi tiết ổn định. + Ghi zip chẩn đoán hỗ trợ có thể chia sẻ thay vì in chi tiết độ ổn định. Đường dẫn đầu ra cho `--export`. - - - Bản ghi giữ siêu dữ liệu vận hành: tên sự kiện, số lượng, kích thước byte, số đo bộ nhớ, trạng thái hàng đợi/phiên, tên kênh/plugin, và tóm tắt phiên đã biên tập. Chúng không giữ văn bản chat, nội dung webhook, đầu ra công cụ, nội dung yêu cầu hoặc phản hồi thô, token, cookie, giá trị bí mật, hostname, hoặc id phiên thô. Đặt `diagnostics.enabled: false` để tắt hoàn toàn trình ghi. - - Khi Gateway thoát nghiêm trọng, hết thời gian tắt, và khởi động lại thất bại khi startup, OpenClaw ghi cùng ảnh chụp chẩn đoán vào `~/.openclaw/logs/stability/openclaw-stability-*.json` khi trình ghi có sự kiện. Kiểm tra bundle mới nhất bằng `openclaw gateway stability --bundle latest`; `--limit`, `--type`, và `--since-seq` cũng áp dụng cho đầu ra bundle. + + - Bản ghi giữ metadata vận hành: tên sự kiện, số lượng, kích thước byte, chỉ số bộ nhớ, trạng thái hàng đợi/phiên, tên kênh/plugin và tóm tắt phiên đã biên tập. Chúng không giữ văn bản chat, nội dung Webhook, đầu ra công cụ, nội dung request hoặc response thô, token, cookie, giá trị bí mật, hostname hoặc id phiên thô. Đặt `diagnostics.enabled: false` để tắt hoàn toàn bộ ghi. + - Khi Gateway thoát do lỗi nghiêm trọng, timeout khi tắt và lỗi khởi động sau khi restart, OpenClaw ghi cùng snapshot chẩn đoán vào `~/.openclaw/logs/stability/openclaw-stability-*.json` khi bộ ghi có sự kiện. Kiểm tra bundle mới nhất bằng `openclaw gateway stability --bundle latest`; `--limit`, `--type` và `--since-seq` cũng áp dụng cho đầu ra bundle. ### `gateway diagnostics export` -Ghi một zip chẩn đoán cục bộ được thiết kế để đính kèm vào báo cáo lỗi. Để biết mô hình quyền riêng tư và nội dung bundle, xem [Xuất chẩn đoán](/vi/gateway/diagnostics). +Ghi một zip chẩn đoán cục bộ được thiết kế để đính kèm vào báo cáo lỗi. Để xem mô hình quyền riêng tư và nội dung bundle, xem [Diagnostics Export](/vi/gateway/diagnostics). ```bash openclaw gateway diagnostics export @@ -229,40 +229,40 @@ openclaw gateway diagnostics export --json ``` - Đường dẫn zip đầu ra. Mặc định là một bản xuất hỗ trợ trong thư mục trạng thái. + Đường dẫn zip đầu ra. Mặc định là bản xuất hỗ trợ trong thư mục trạng thái. - Số dòng nhật ký đã làm sạch tối đa cần bao gồm. + Số dòng log đã làm sạch tối đa cần bao gồm. - Số byte nhật ký tối đa cần kiểm tra. + Số byte log tối đa cần kiểm tra. - URL WebSocket của Gateway cho ảnh chụp health. + URL WebSocket của Gateway cho snapshot health. - Token Gateway cho ảnh chụp health. + Token Gateway cho snapshot health. - Mật khẩu Gateway cho ảnh chụp health. + Mật khẩu Gateway cho snapshot health. - Timeout cho ảnh chụp trạng thái/health. + Timeout snapshot trạng thái/health. - Bỏ qua tra cứu bundle ổn định đã lưu. + Bỏ qua việc tra cứu stability bundle đã lưu. - In đường dẫn đã ghi, kích thước, và manifest dưới dạng JSON. + In đường dẫn đã ghi, kích thước và manifest dưới dạng JSON. -Bản xuất chứa một manifest, tóm tắt Markdown, hình dạng cấu hình, chi tiết cấu hình đã làm sạch, tóm tắt nhật ký đã làm sạch, ảnh chụp trạng thái/health của Gateway đã làm sạch, và bundle ổn định mới nhất khi có. +Bản xuất chứa manifest, tóm tắt Markdown, hình dạng cấu hình, chi tiết cấu hình đã làm sạch, tóm tắt log đã làm sạch, snapshot trạng thái/health Gateway đã làm sạch và stability bundle mới nhất khi có. -Nó được thiết kế để chia sẻ. Nó giữ các chi tiết vận hành giúp gỡ lỗi, chẳng hạn như trường nhật ký OpenClaw an toàn, tên subsystem, mã trạng thái, thời lượng, chế độ đã cấu hình, cổng, id plugin, id provider, cài đặt tính năng không bí mật, và thông điệp nhật ký vận hành đã biên tập. Nó bỏ qua hoặc biên tập văn bản chat, nội dung webhook, đầu ra công cụ, thông tin xác thực, cookie, định danh tài khoản/tin nhắn, văn bản prompt/hướng dẫn, hostname, và giá trị bí mật. Khi một thông điệp kiểu LogTape trông giống văn bản payload người dùng/chat/công cụ, bản xuất chỉ giữ lại việc một thông điệp đã bị bỏ qua cùng số byte của nó. +Nó được dùng để chia sẻ. Nó giữ các chi tiết vận hành hỗ trợ gỡ lỗi, chẳng hạn như các trường log OpenClaw an toàn, tên subsystem, mã trạng thái, thời lượng, chế độ đã cấu hình, cổng, id plugin, id nhà cung cấp, cài đặt tính năng không bí mật và thông điệp log vận hành đã biên tập. Nó bỏ qua hoặc biên tập văn bản chat, nội dung Webhook, đầu ra công cụ, thông tin xác thực, cookie, định danh tài khoản/tin nhắn, văn bản prompt/instruction, hostname và giá trị bí mật. Khi một thông điệp kiểu LogTape trông giống văn bản payload người dùng/chat/công cụ, bản xuất chỉ giữ lại việc một thông điệp đã bị bỏ qua cùng số byte của nó. ### `gateway status` -`gateway status` hiển thị dịch vụ Gateway (launchd/systemd/schtasks) cộng với một probe tùy chọn về khả năng kết nối/xác thực. +`gateway status` hiển thị dịch vụ Gateway (launchd/systemd/schtasks) cùng với một probe tùy chọn về khả năng kết nối/xác thực. ```bash openclaw gateway status @@ -271,63 +271,64 @@ openclaw gateway status --require-rpc ``` - Thêm một mục tiêu dò tìm rõ ràng. Remote đã cấu hình + localhost vẫn được dò tìm. + Thêm một mục tiêu thăm dò rõ ràng. Remote đã cấu hình + localhost vẫn được thăm dò. - Xác thực bằng token cho lần dò tìm. + Xác thực bằng token cho thăm dò. - Xác thực bằng mật khẩu cho lần dò tìm. + Xác thực bằng mật khẩu cho thăm dò. - Thời gian chờ dò tìm. + Thời gian chờ thăm dò. - Bỏ qua dò tìm kết nối (chỉ xem dịch vụ). + Bỏ qua thăm dò kết nối (chỉ xem dịch vụ). Quét cả các dịch vụ cấp hệ thống. - Nâng cấp lần dò tìm kết nối mặc định thành dò tìm đọc và thoát với mã khác 0 khi lần dò tìm đọc đó thất bại. Không thể kết hợp với `--no-probe`. + Nâng cấp thăm dò kết nối mặc định thành thăm dò đọc và thoát với mã khác 0 khi thăm dò đọc đó thất bại. Không thể kết hợp với `--no-probe`. - - - `gateway status` vẫn khả dụng để chẩn đoán ngay cả khi cấu hình CLI cục bộ bị thiếu hoặc không hợp lệ. - - `gateway status` mặc định xác minh trạng thái dịch vụ, kết nối WebSocket và khả năng xác thực nhìn thấy được tại thời điểm bắt tay. Nó không xác minh các thao tác đọc/ghi/quản trị. - - Các lần dò tìm chẩn đoán không gây thay đổi đối với xác thực thiết bị lần đầu: chúng dùng lại token thiết bị đã lưu trong bộ nhớ đệm hiện có khi có, nhưng không tạo danh tính thiết bị CLI mới hoặc bản ghi ghép đôi thiết bị chỉ đọc chỉ để kiểm tra trạng thái. - - `gateway status` phân giải các SecretRefs xác thực đã cấu hình cho xác thực dò tìm khi có thể. - - Nếu SecretRef xác thực bắt buộc chưa được phân giải trong đường dẫn lệnh này, `gateway status --json` báo cáo `rpc.authWarning` khi kết nối/xác thực dò tìm thất bại; truyền rõ `--token`/`--password` hoặc phân giải nguồn secret trước. - - Nếu lần dò tìm thành công, cảnh báo auth-ref chưa phân giải sẽ bị ẩn để tránh báo sai. - - Dùng `--require-rpc` trong script và tự động hóa khi chỉ có dịch vụ đang lắng nghe là chưa đủ và bạn cũng cần các lệnh gọi RPC phạm vi đọc hoạt động tốt. - - `--deep` thêm một lần quét nỗ lực tối đa cho các bản cài đặt launchd/systemd/schtasks bổ sung. Khi phát hiện nhiều dịch vụ giống Gateway, đầu ra cho người dùng in gợi ý dọn dẹp và cảnh báo rằng hầu hết thiết lập nên chạy một Gateway trên mỗi máy. - - Đầu ra cho người dùng bao gồm đường dẫn log tệp đã phân giải cộng với ảnh chụp nhanh đường dẫn/tính hợp lệ cấu hình CLI so với dịch vụ để giúp chẩn đoán sai lệch profile hoặc thư mục trạng thái. + + - `gateway status` vẫn khả dụng cho chẩn đoán ngay cả khi cấu hình CLI cục bộ bị thiếu hoặc không hợp lệ. + - `gateway status` mặc định chứng minh trạng thái dịch vụ, kết nối WebSocket và khả năng xác thực hiển thị tại thời điểm bắt tay. Nó không chứng minh các thao tác đọc/ghi/quản trị. + - Thăm dò chẩn đoán không gây biến đổi đối với xác thực thiết bị lần đầu: chúng tái sử dụng token thiết bị đã lưu trong bộ nhớ đệm khi có, nhưng không tạo danh tính thiết bị CLI mới hoặc bản ghi ghép đôi thiết bị chỉ đọc chỉ để kiểm tra trạng thái. + - `gateway status` phân giải SecretRefs xác thực đã cấu hình cho xác thực thăm dò khi có thể. + - Nếu một SecretRef xác thực bắt buộc chưa được phân giải trong đường dẫn lệnh này, `gateway status --json` báo cáo `rpc.authWarning` khi kết nối/xác thực thăm dò thất bại; hãy truyền rõ ràng `--token`/`--password` hoặc phân giải nguồn bí mật trước. + - Nếu thăm dò thành công, cảnh báo auth-ref chưa phân giải sẽ bị ẩn để tránh dương tính giả. + - Dùng `--require-rpc` trong script và tự động hóa khi một dịch vụ đang lắng nghe là chưa đủ và bạn cũng cần các lệnh gọi RPC phạm vi đọc hoạt động tốt. + - `--deep` thêm quét nỗ lực tối đa cho các bản cài đặt launchd/systemd/schtasks bổ sung. Khi phát hiện nhiều dịch vụ giống gateway, đầu ra cho người dùng in gợi ý dọn dẹp và cảnh báo rằng hầu hết thiết lập nên chạy một gateway trên mỗi máy. + - `--deep` cũng báo cáo một lần bàn giao khởi động lại Gateway supervisor gần đây khi tiến trình dịch vụ đã thoát sạch để một supervisor bên ngoài khởi động lại. + - Đầu ra cho người dùng bao gồm đường dẫn log tệp đã phân giải cùng ảnh chụp nhanh đường dẫn/tính hợp lệ của cấu hình CLI so với dịch vụ để giúp chẩn đoán lệch profile hoặc state-dir. - - - Trên các bản cài đặt Linux systemd, kiểm tra sai lệch xác thực dịch vụ đọc cả giá trị `Environment=` và `EnvironmentFile=` từ unit (bao gồm `%h`, đường dẫn có dấu ngoặc kép, nhiều tệp và các tệp tùy chọn có tiền tố `-`). - - Kiểm tra sai lệch phân giải SecretRefs `gateway.auth.token` bằng env runtime đã hợp nhất (env lệnh dịch vụ trước, sau đó dự phòng bằng env tiến trình). - - Nếu xác thực token thực tế không hoạt động (`gateway.auth.mode` rõ ràng là `password`/`none`/`trusted-proxy`, hoặc mode chưa đặt trong đó mật khẩu có thể thắng và không ứng viên token nào có thể thắng), kiểm tra sai lệch token bỏ qua phân giải token cấu hình. + + - Trên các bản cài đặt systemd Linux, kiểm tra lệch xác thực dịch vụ đọc cả giá trị `Environment=` và `EnvironmentFile=` từ unit (bao gồm `%h`, đường dẫn có trích dẫn, nhiều tệp và các tệp `-` tùy chọn). + - Kiểm tra lệch phân giải SecretRefs `gateway.auth.token` bằng env runtime đã hợp nhất (env lệnh dịch vụ trước, rồi dự phòng về env tiến trình). + - Nếu xác thực token không thực sự hoạt động (đặt rõ `gateway.auth.mode` là `password`/`none`/`trusted-proxy`, hoặc chưa đặt mode khi mật khẩu có thể thắng và không có ứng viên token nào có thể thắng), kiểm tra token-drift bỏ qua phân giải token cấu hình. ### `gateway probe` -`gateway probe` là lệnh "gỡ lỗi mọi thứ". Nó luôn dò tìm: +`gateway probe` là lệnh "debug mọi thứ". Nó luôn thăm dò: -- Gateway remote đã cấu hình của bạn (nếu đã đặt), và +- gateway remote đã cấu hình của bạn (nếu đã đặt), và - localhost (loopback) **ngay cả khi remote đã được cấu hình**. -Nếu bạn truyền `--url`, mục tiêu rõ ràng đó được thêm vào trước cả hai. Đầu ra cho người dùng gắn nhãn các mục tiêu là: +Nếu bạn truyền `--url`, mục tiêu rõ ràng đó sẽ được thêm trước cả hai. Đầu ra cho người dùng gắn nhãn các mục tiêu là: - `URL (explicit)` - `Remote (configured)` hoặc `Remote (configured, inactive)` - `Local loopback` -Nếu nhiều Gateway có thể truy cập được, lệnh sẽ in tất cả. Nhiều Gateway được hỗ trợ khi bạn dùng profile/cổng tách biệt (ví dụ: bot cứu hộ), nhưng hầu hết bản cài đặt vẫn chạy một Gateway duy nhất. +Nếu có thể truy cập nhiều gateway, lệnh sẽ in tất cả. Nhiều gateway được hỗ trợ khi bạn dùng các profile/cổng tách biệt (ví dụ: bot cứu hộ), nhưng hầu hết bản cài đặt vẫn chạy một gateway duy nhất. ```bash @@ -336,30 +337,30 @@ openclaw gateway probe --json ``` - + - `Reachable: yes` nghĩa là ít nhất một mục tiêu đã chấp nhận kết nối WebSocket. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` báo cáo những gì lần dò tìm có thể xác minh về xác thực. Nó tách biệt với khả năng truy cập. - - `Read probe: ok` nghĩa là các lệnh gọi RPC chi tiết phạm vi đọc (`health`/`status`/`system-presence`/`config.get`) cũng thành công. - - `Read probe: limited - missing scope: operator.read` nghĩa là kết nối thành công nhưng RPC phạm vi đọc bị giới hạn. Trạng thái này được báo cáo là khả năng truy cập **suy giảm**, không phải thất bại hoàn toàn. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` báo cáo những gì thăm dò có thể chứng minh về xác thực. Nó tách biệt với khả năng truy cập. + - `Read probe: ok` nghĩa là các lệnh gọi RPC chi tiết phạm vi đọc (`health`/`status`/`system-presence`/`config.get`) cũng đã thành công. + - `Read probe: limited - missing scope: operator.read` nghĩa là kết nối thành công nhưng RPC phạm vi đọc bị giới hạn. Trường hợp này được báo cáo là khả năng truy cập **suy giảm**, không phải thất bại hoàn toàn. - `Read probe: failed` sau `Connect: ok` nghĩa là Gateway đã chấp nhận kết nối WebSocket, nhưng chẩn đoán đọc tiếp theo đã hết thời gian chờ hoặc thất bại. Đây cũng là khả năng truy cập **suy giảm**, không phải Gateway không thể truy cập. - - Giống `gateway status`, probe dùng lại xác thực thiết bị đã lưu trong bộ nhớ đệm hiện có nhưng không tạo danh tính thiết bị lần đầu hoặc trạng thái ghép đôi. - - Mã thoát khác 0 chỉ khi không có mục tiêu được dò tìm nào có thể truy cập. + - Giống `gateway status`, thăm dò tái sử dụng xác thực thiết bị đã lưu trong bộ nhớ đệm nhưng không tạo danh tính thiết bị lần đầu hoặc trạng thái ghép đôi. + - Mã thoát khác 0 chỉ khi không có mục tiêu được thăm dò nào có thể truy cập. - + Cấp cao nhất: - `ok`: ít nhất một mục tiêu có thể truy cập. - `degraded`: ít nhất một mục tiêu đã chấp nhận kết nối nhưng không hoàn tất chẩn đoán RPC chi tiết đầy đủ. - - `capability`: khả năng tốt nhất nhìn thấy trên các mục tiêu có thể truy cập (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, hoặc `unknown`). - - `primaryTargetId`: mục tiêu tốt nhất để coi là mục tiêu thắng đang hoạt động theo thứ tự này: URL rõ ràng, đường hầm SSH, remote đã cấu hình, rồi local loopback. - - `warnings[]`: bản ghi cảnh báo nỗ lực tối đa với `code`, `message` và `targetIds` tùy chọn. - - `network`: gợi ý URL local loopback/tailnet bắt nguồn từ cấu hình hiện tại và mạng của host. - - `discovery.timeoutMs` và `discovery.count`: ngân sách/kết quả đếm khám phá thực tế được dùng cho lượt dò tìm này. + - `capability`: khả năng tốt nhất quan sát được trên các mục tiêu có thể truy cập (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, hoặc `unknown`). + - `primaryTargetId`: mục tiêu tốt nhất để xem là mục tiêu thắng đang hoạt động theo thứ tự này: URL rõ ràng, đường hầm SSH, remote đã cấu hình, rồi local loopback. + - `warnings[]`: các bản ghi cảnh báo nỗ lực tối đa với `code`, `message` và `targetIds` tùy chọn. + - `network`: gợi ý URL local loopback/tailnet được suy ra từ cấu hình hiện tại và mạng của host. + - `discovery.timeoutMs` và `discovery.count`: ngân sách khám phá/số lượng kết quả thực tế dùng cho lượt thăm dò này. Theo từng mục tiêu (`targets[].connect`): - - `ok`: khả năng truy cập sau kết nối + phân loại suy giảm. + - `ok`: khả năng truy cập sau phân loại kết nối + suy giảm. - `rpcOk`: RPC chi tiết đầy đủ thành công. - `scopeLimited`: RPC chi tiết thất bại do thiếu phạm vi operator. @@ -370,20 +371,20 @@ openclaw gateway probe --json - `capability`: phân loại khả năng xác thực được hiển thị cho mục tiêu đó. - - - `ssh_tunnel_failed`: thiết lập đường hầm SSH thất bại; lệnh đã chuyển về dò tìm trực tiếp. - - `multiple_gateways`: có thể truy cập nhiều hơn một mục tiêu; điều này không bình thường trừ khi bạn cố ý chạy các profile tách biệt, chẳng hạn như bot cứu hộ. + + - `ssh_tunnel_failed`: thiết lập đường hầm SSH thất bại; lệnh đã dự phòng sang thăm dò trực tiếp. + - `multiple_gateways`: có thể truy cập nhiều hơn một mục tiêu; điều này bất thường trừ khi bạn cố ý chạy các profile tách biệt, chẳng hạn như bot cứu hộ. - `auth_secretref_unresolved`: không thể phân giải SecretRef xác thực đã cấu hình cho một mục tiêu thất bại. - - `probe_scope_limited`: kết nối WebSocket thành công, nhưng dò tìm đọc bị giới hạn do thiếu `operator.read`. + - `probe_scope_limited`: kết nối WebSocket thành công, nhưng thăm dò đọc bị giới hạn do thiếu `operator.read`. -#### Remote qua SSH (ngang bằng ứng dụng Mac) +#### Remote qua SSH (tương đương ứng dụng Mac) -Chế độ "Remote over SSH" của ứng dụng macOS dùng chuyển tiếp cổng cục bộ để Gateway remote (có thể chỉ được bind với loopback) có thể truy cập tại `ws://127.0.0.1:`. +Chế độ "Remote over SSH" của ứng dụng macOS dùng chuyển tiếp cổng cục bộ để gateway remote (có thể chỉ được bind vào loopback) có thể truy cập tại `ws://127.0.0.1:`. -Tương đương trong CLI: +Tương đương trên CLI: ```bash openclaw gateway probe --ssh user@gateway-host @@ -396,7 +397,7 @@ openclaw gateway probe --ssh user@gateway-host Tệp danh tính. - Chọn host Gateway đầu tiên được phát hiện làm mục tiêu SSH từ endpoint khám phá đã phân giải (`local.` cộng với miền diện rộng đã cấu hình, nếu có). Các gợi ý chỉ TXT bị bỏ qua. + Chọn host gateway đầu tiên được khám phá làm mục tiêu SSH từ endpoint khám phá đã phân giải (`local.` cộng với miền diện rộng đã cấu hình, nếu có). Các gợi ý chỉ có TXT bị bỏ qua. Cấu hình (tùy chọn, dùng làm mặc định): @@ -406,7 +407,7 @@ Cấu hình (tùy chọn, dùng làm mặc định): ### `gateway call ` -Trình trợ giúp RPC cấp thấp. +Trợ giúp RPC cấp thấp. ```bash openclaw gateway call status @@ -429,10 +430,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Ngân sách thời gian chờ. - Chủ yếu dành cho RPC kiểu agent phát luồng sự kiện trung gian trước payload cuối cùng. + Chủ yếu dành cho RPC kiểu agent phát các sự kiện trung gian trước payload cuối cùng. - Đầu ra JSON cho máy đọc. + Đầu ra JSON đọc được bằng máy. @@ -451,7 +452,9 @@ openclaw gateway uninstall ### Cài đặt với wrapper -Dùng `--wrapper` khi dịch vụ được quản lý phải khởi động thông qua một executable khác, ví dụ như shim trình quản lý secret hoặc trình trợ giúp run-as. Wrapper nhận các đối số Gateway bình thường và chịu trách nhiệm cuối cùng exec `openclaw` hoặc Node với các đối số đó. +Dùng `--wrapper` khi dịch vụ được quản lý phải khởi động thông qua một executable khác, ví dụ một +shim trình quản lý bí mật hoặc trình trợ giúp chạy với người dùng khác. Wrapper nhận các đối số Gateway bình thường và chịu +trách nhiệm cuối cùng exec `openclaw` hoặc Node với các đối số đó. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -465,14 +468,16 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -Bạn cũng có thể đặt wrapper thông qua môi trường. `gateway install` xác thực rằng đường dẫn là một tệp executable, ghi wrapper vào `ProgramArguments` của dịch vụ và lưu `OPENCLAW_WRAPPER` trong môi trường dịch vụ cho các lần cài đặt lại bắt buộc, cập nhật và sửa chữa doctor sau này. +Bạn cũng có thể đặt wrapper thông qua môi trường. `gateway install` xác thực rằng đường dẫn là +một tệp executable, ghi wrapper vào `ProgramArguments` của dịch vụ và lưu giữ +`OPENCLAW_WRAPPER` trong môi trường dịch vụ cho các lần cài đặt lại bắt buộc, cập nhật và sửa chữa bằng doctor sau này. ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force openclaw doctor ``` -Để xóa wrapper đã lưu, hãy xóa `OPENCLAW_WRAPPER` trong khi cài đặt lại: +Để xóa một wrapper đã lưu giữ, hãy xóa `OPENCLAW_WRAPPER` trong khi cài đặt lại: ```bash OPENCLAW_WRAPPER= openclaw gateway install --force @@ -480,26 +485,26 @@ openclaw gateway restart ``` - + - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` - `gateway install`: `--port`, `--runtime `, `--token`, `--wrapper `, `--force`, `--json` - `gateway restart`: `--safe`, `--force`, `--wait `, `--json` - `gateway uninstall|start|stop`: `--json` - - - Dùng `gateway restart` để khởi động lại dịch vụ được quản lý. Đừng nối chuỗi `gateway stop` và `gateway start` để thay thế restart; trên macOS, `gateway stop` cố ý tắt LaunchAgent trước khi dừng nó. - - `gateway restart --safe` yêu cầu Gateway đang chạy preflight công việc OpenClaw đang hoạt động và trì hoãn restart cho đến khi việc gửi trả lời, các lần chạy nhúng và các lần chạy tác vụ rút hết. `--safe` không thể kết hợp với `--force` hoặc `--wait`. - - `gateway restart --wait 30s` ghi đè ngân sách drain restart đã cấu hình cho lần restart đó. Số không kèm đơn vị là mili giây; các đơn vị như `s`, `m` và `h` được chấp nhận. `--wait 0` chờ vô thời hạn. - - `gateway restart --force` bỏ qua drain công việc đang hoạt động và restart ngay lập tức. Dùng tùy chọn này khi operator đã kiểm tra các bộ chặn tác vụ được liệt kê và muốn Gateway hoạt động trở lại ngay. - - Các lệnh vòng đời chấp nhận `--json` để viết script. + + - Dùng `gateway restart` để khởi động lại một dịch vụ được quản lý. Không nối `gateway stop` và `gateway start` để thay thế thao tác khởi động lại; trên macOS, `gateway stop` cố ý vô hiệu hóa LaunchAgent trước khi dừng nó. + - `gateway restart --safe` yêu cầu Gateway đang chạy kiểm tra trước công việc OpenClaw đang hoạt động và trì hoãn khởi động lại cho đến khi việc gửi trả lời, các lần chạy nhúng và các lần chạy tác vụ rút hết. Không thể kết hợp `--safe` với `--force` hoặc `--wait`. + - `gateway restart --wait 30s` ghi đè ngân sách rút cạn khi khởi động lại đã cấu hình cho lần khởi động lại đó. Số trần là mili giây; các đơn vị như `s`, `m` và `h` được chấp nhận. `--wait 0` chờ vô thời hạn. + - `gateway restart --force` bỏ qua việc rút cạn công việc đang hoạt động và khởi động lại ngay lập tức. Dùng tùy chọn này khi operator đã kiểm tra các tác vụ chặn được liệt kê và muốn gateway hoạt động trở lại ngay. + - Các lệnh vòng đời chấp nhận `--json` cho script. - - Khi xác thực bằng token yêu cầu token và `gateway.auth.token` được quản lý bằng SecretRef, `gateway install` xác thực rằng SecretRef có thể phân giải được nhưng không lưu token đã phân giải vào siêu dữ liệu môi trường dịch vụ. - - Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, quá trình cài đặt sẽ thất bại theo hướng an toàn thay vì lưu văn bản thuần dự phòng. - - Với xác thực bằng mật khẩu trên `gateway run`, hãy ưu tiên `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, hoặc `gateway.auth.password` dựa trên SecretRef thay vì `--password` nội tuyến. - - Ở chế độ xác thực suy luận, `OPENCLAW_GATEWAY_PASSWORD` chỉ có trong shell không nới lỏng yêu cầu token khi cài đặt; hãy dùng cấu hình bền vững (`gateway.auth.password` hoặc `env` trong cấu hình) khi cài đặt một dịch vụ được quản lý. + - Khi xác thực bằng token yêu cầu token và `gateway.auth.token` được quản lý bằng SecretRef, `gateway install` xác thực rằng SecretRef có thể được phân giải nhưng không lưu token đã phân giải vào siêu dữ liệu môi trường dịch vụ. + - Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, quá trình cài đặt sẽ thất bại theo hướng đóng thay vì lưu văn bản thuần dự phòng. + - Với xác thực bằng mật khẩu trên `gateway run`, ưu tiên `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, hoặc `gateway.auth.password` dựa trên SecretRef thay vì `--password` nội tuyến. + - Trong chế độ xác thực suy luận, `OPENCLAW_GATEWAY_PASSWORD` chỉ có trong shell không nới lỏng yêu cầu token khi cài đặt; hãy dùng cấu hình bền vững (`gateway.auth.password` hoặc cấu hình `env`) khi cài đặt một dịch vụ được quản lý. - Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, quá trình cài đặt sẽ bị chặn cho đến khi chế độ được đặt rõ ràng. @@ -509,20 +514,20 @@ openclaw gateway restart `gateway discover` quét các beacon Gateway (`_openclaw-gw._tcp`). -- DNS-SD multicast: `local.` -- DNS-SD unicast (Bonjour diện rộng): chọn một miền (ví dụ: `openclaw.internal.`) và thiết lập DNS phân tách + một máy chủ DNS; xem [Bonjour](/vi/gateway/bonjour). +- Multicast DNS-SD: `local.` +- Unicast DNS-SD (Wide-Area Bonjour): chọn một miền (ví dụ: `openclaw.internal.`) và thiết lập DNS phân tách + máy chủ DNS; xem [Bonjour](/vi/gateway/bonjour). -Chỉ những gateway đã bật khám phá Bonjour (mặc định) mới quảng bá beacon. +Chỉ các gateway đã bật khám phá Bonjour (mặc định) mới quảng bá beacon. -Bản ghi khám phá diện rộng bao gồm (TXT): +Bản ghi khám phá Wide-Area bao gồm (TXT): - `role` (gợi ý vai trò gateway) -- `transport` (gợi ý transport, ví dụ `gateway`) +- `transport` (gợi ý phương thức truyền tải, ví dụ `gateway`) - `gatewayPort` (cổng WebSocket, thường là `18789`) -- `sshPort` (tùy chọn; client mặc định mục tiêu SSH là `22` khi mục này vắng mặt) +- `sshPort` (tùy chọn; client mặc định dùng mục tiêu SSH là `22` khi không có trường này) - `tailnetDns` (tên máy chủ MagicDNS, khi có) -- `gatewayTls` / `gatewayTlsSha256` (TLS đã bật + vân tay chứng chỉ) -- `cliPath` (gợi ý cài đặt từ xa được ghi vào vùng diện rộng) +- `gatewayTls` / `gatewayTlsSha256` (TLS đã bật + dấu vân tay chứng chỉ) +- `cliPath` (gợi ý cài đặt từ xa được ghi vào vùng wide-area) ### `gateway discover` @@ -531,10 +536,10 @@ openclaw gateway discover ``` - Thời gian chờ cho mỗi lệnh (browse/resolve). + Thời gian chờ cho mỗi lệnh (duyệt/phân giải). - Đầu ra máy đọc được (đồng thời tắt styling/spinner). + Đầu ra máy đọc được (cũng tắt định dạng/spinner). Ví dụ: @@ -545,13 +550,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- CLI quét `local.` cùng với miền diện rộng đã cấu hình khi có miền được bật. -- `wsUrl` trong đầu ra JSON được suy ra từ điểm cuối dịch vụ đã phân giải, không phải từ các gợi ý chỉ có trong TXT như `lanHost` hoặc `tailnetDns`. -- Trên mDNS `local.`, `sshPort` và `cliPath` chỉ được phát khi `discovery.mdns.mode` là `full`. DNS-SD diện rộng vẫn ghi `cliPath`; `sshPort` cũng vẫn là tùy chọn ở đó. +- CLI quét `local.` cùng với miền wide-area đã cấu hình khi một miền được bật. +- `wsUrl` trong đầu ra JSON được suy ra từ endpoint dịch vụ đã phân giải, không phải từ các gợi ý chỉ có trong TXT như `lanHost` hoặc `tailnetDns`. +- Trên mDNS `local.`, `sshPort` và `cliPath` chỉ được phát khi `discovery.mdns.mode` là `full`. DNS-SD wide-area vẫn ghi `cliPath`; `sshPort` cũng vẫn là tùy chọn ở đó. ## Liên quan - [Tham chiếu CLI](/vi/cli) -- [Runbook Gateway](/vi/gateway) +- [Sổ tay vận hành Gateway](/vi/gateway) diff --git a/docs/vi/cli/hooks.md b/docs/vi/cli/hooks.md index f285cb551..7f940cad2 100644 --- a/docs/vi/cli/hooks.md +++ b/docs/vi/cli/hooks.md @@ -1,21 +1,21 @@ --- read_when: - - Bạn muốn quản lý các hook của agent - - Bạn muốn kiểm tra tính khả dụng của điểm móc hoặc bật các điểm móc của không gian làm việc -summary: Tài liệu tham khảo CLI cho `openclaw hooks` (các hook tác tử) -title: Các móc nối + - Bạn muốn quản lý các móc nối của tác nhân + - Bạn muốn kiểm tra tính khả dụng của móc nối hoặc bật móc nối không gian làm việc +summary: Tham chiếu CLI cho `openclaw hooks` (các móc tác tử) +title: Móc nối x-i18n: - generated_at: "2026-05-02T20:41:57Z" + generated_at: "2026-05-05T08:25:41Z" model: gpt-5.5 provider: openai - source_hash: 3b02c176b4a310adba3fa1fde3758f6c8a19d454aeec58e919458b3f1a66c87d + source_hash: 8e860d4a20a09526e804fa1aff8c983a75396fcd1e6e24f742252fdf1812f6b7 source_path: cli/hooks.md workflow: 16 --- # `openclaw hooks` -Quản lý các hook của tác tử (tự động hóa theo sự kiện cho các lệnh như `/new`, `/reset` và lúc khởi động Gateway). +Quản lý các hook của agent (tự động hóa theo sự kiện cho các lệnh như `/new`, `/reset` và khởi động Gateway). Chạy `openclaw hooks` mà không có lệnh con tương đương với `openclaw hooks list`. @@ -30,8 +30,8 @@ Liên quan: openclaw hooks list ``` -Liệt kê tất cả hook được phát hiện từ thư mục workspace, managed, extra và bundled. -Khởi động Gateway không tải trình xử lý hook nội bộ cho đến khi có ít nhất một hook nội bộ được cấu hình. +Liệt kê tất cả hook được phát hiện từ các thư mục workspace, được quản lý, bổ sung và đi kèm. +Khởi động Gateway không tải các trình xử lý hook nội bộ cho đến khi có ít nhất một hook nội bộ được cấu hình. **Tùy chọn:** @@ -129,15 +129,15 @@ Ready: 4 Not ready: 0 ``` -## Bật Hook +## Bật một Hook ```bash openclaw hooks enable ``` -Bật một hook cụ thể bằng cách thêm hook đó vào cấu hình của bạn (`~/.openclaw/openclaw.json` theo mặc định). +Bật một hook cụ thể bằng cách thêm hook đó vào cấu hình của bạn (mặc định là `~/.openclaw/openclaw.json`). -**Lưu ý:** Hook workspace bị tắt theo mặc định cho đến khi được bật ở đây hoặc trong cấu hình. Các hook do Plugin quản lý hiển thị `plugin:` trong `openclaw hooks list` và không thể bật/tắt ở đây. Hãy bật/tắt Plugin thay thế. +**Lưu ý:** Hook workspace bị tắt theo mặc định cho đến khi được bật tại đây hoặc trong cấu hình. Các hook do Plugin quản lý hiển thị `plugin:` trong `openclaw hooks list` và không thể bật/tắt tại đây. Thay vào đó, hãy bật/tắt Plugin. **Đối số:** @@ -157,18 +157,18 @@ openclaw hooks enable session-memory **Việc này làm gì:** -- Kiểm tra xem hook có tồn tại và đủ điều kiện không +- Kiểm tra hook có tồn tại và đủ điều kiện không - Cập nhật `hooks.internal.entries..enabled = true` trong cấu hình của bạn -- Lưu cấu hình vào đĩa +- Lưu cấu hình vào ổ đĩa Nếu hook đến từ `/hooks/`, bước chọn tham gia này là bắt buộc trước khi Gateway tải hook đó. **Sau khi bật:** -- Khởi động lại Gateway để các hook được tải lại (khởi động lại ứng dụng thanh menu trên macOS, hoặc khởi động lại tiến trình Gateway của bạn trong môi trường phát triển). +- Khởi động lại Gateway để hook được tải lại (khởi động lại ứng dụng thanh menu trên macOS, hoặc khởi động lại tiến trình Gateway của bạn khi phát triển). -## Tắt Hook +## Tắt một Hook ```bash openclaw hooks disable @@ -194,14 +194,14 @@ openclaw hooks disable command-logger **Sau khi tắt:** -- Khởi động lại Gateway để các hook được tải lại +- Khởi động lại Gateway để hook được tải lại ## Ghi chú - `openclaw hooks list --json`, `info --json` và `check --json` ghi JSON có cấu trúc trực tiếp ra stdout. -- Không thể bật hoặc tắt các hook do Plugin quản lý ở đây; hãy bật hoặc tắt Plugin sở hữu chúng thay thế. +- Hook do Plugin quản lý không thể được bật hoặc tắt tại đây; thay vào đó, hãy bật hoặc tắt Plugin sở hữu hook đó. -## Cài đặt gói hook +## Cài đặt các gói hook ```bash openclaw plugins install # npm by default @@ -212,30 +212,30 @@ openclaw plugins install # local path Cài đặt các gói hook thông qua trình cài đặt Plugin hợp nhất. -`openclaw hooks install` vẫn hoạt động như một alias tương thích, nhưng nó in +`openclaw hooks install` vẫn hoạt động như một bí danh tương thích, nhưng sẽ in cảnh báo ngừng dùng và chuyển tiếp đến `openclaw plugins install`. -Thông số npm **chỉ dùng registry** (tên gói + tùy chọn **phiên bản chính xác** hoặc -**dist-tag**). Thông số Git/URL/file và dải semver bị từ chối. Việc cài đặt dependency -chạy cục bộ theo dự án với `--ignore-scripts` để đảm bảo an toàn, ngay cả khi -shell của bạn có cài đặt cài đặt npm toàn cục. +Đặc tả npm là **chỉ registry** (tên gói + **phiên bản chính xác** tùy chọn hoặc +**dist-tag**). Đặc tả Git/URL/file và dải semver sẽ bị từ chối. Việc cài đặt phụ thuộc +chạy cục bộ theo dự án với `--ignore-scripts` để an toàn, ngay cả khi shell của bạn +có thiết lập cài đặt npm toàn cục. -Thông số trần và `@latest` ở lại kênh ổn định. Nếu npm phân giải một trong hai -thành bản phát hành trước, OpenClaw sẽ dừng và yêu cầu bạn chọn tham gia rõ ràng bằng -thẻ phát hành trước như `@beta`/`@rc` hoặc một phiên bản phát hành trước chính xác. +Đặc tả trần và `@latest` giữ nguyên trên kênh ổn định. Nếu npm phân giải một trong +hai loại đó thành bản prerelease, OpenClaw sẽ dừng và yêu cầu bạn chọn tham gia rõ ràng bằng +thẻ prerelease như `@beta`/`@rc` hoặc một phiên bản prerelease chính xác. **Việc này làm gì:** - Sao chép gói hook vào `~/.openclaw/hooks/` - Bật các hook đã cài đặt trong `hooks.internal.entries.*` -- Ghi lại cài đặt trong `hooks.internal.installs` +- Ghi lại lần cài đặt trong `hooks.internal.installs` **Tùy chọn:** - `-l, --link`: Liên kết một thư mục cục bộ thay vì sao chép (thêm thư mục đó vào `hooks.internal.load.extraDirs`) -- `--pin`: Ghi lại cài đặt npm dưới dạng `name@version` đã phân giải chính xác trong `hooks.internal.installs` +- `--pin`: Ghi các lần cài đặt npm dưới dạng `name@version` đã phân giải chính xác trong `hooks.internal.installs` -**Kho lưu trữ được hỗ trợ:** `.zip`, `.tgz`, `.tar.gz`, `.tar` +**Lưu trữ được hỗ trợ:** `.zip`, `.tgz`, `.tar.gz`, `.tar` **Ví dụ:** @@ -253,10 +253,10 @@ openclaw plugins install @openclaw/my-hook-pack openclaw plugins install -l ./my-hook-pack ``` -Các gói hook được liên kết được xem là hook managed từ một thư mục do người vận hành cấu hình, -không phải là hook workspace. +Các gói hook được liên kết được xem là hook được quản lý từ một thư mục do operator cấu hình, +không phải hook workspace. -## Cập nhật gói hook +## Cập nhật các gói hook ```bash openclaw plugins update @@ -265,7 +265,7 @@ openclaw plugins update --all Cập nhật các gói hook dựa trên npm đang được theo dõi thông qua trình cập nhật Plugin hợp nhất. -`openclaw hooks update` vẫn hoạt động như một alias tương thích, nhưng nó in +`openclaw hooks update` vẫn hoạt động như một bí danh tương thích, nhưng sẽ in cảnh báo ngừng dùng và chuyển tiếp đến `openclaw plugins update`. **Tùy chọn:** @@ -273,15 +273,15 @@ cảnh báo ngừng dùng và chuyển tiếp đến `openclaw plugins update`. - `--all`: Cập nhật tất cả gói hook đang được theo dõi - `--dry-run`: Hiển thị những gì sẽ thay đổi mà không ghi -Khi tồn tại hash toàn vẹn đã lưu và hash artifact được lấy về thay đổi, -OpenClaw in cảnh báo và yêu cầu xác nhận trước khi tiếp tục. Dùng -`--yes` toàn cục để bỏ qua lời nhắc trong các lượt chạy CI/không tương tác. +Khi có hash toàn vẹn đã lưu và hash artifact được tải về thay đổi, +OpenClaw sẽ in cảnh báo và yêu cầu xác nhận trước khi tiếp tục. Dùng +`--yes` toàn cục để bỏ qua lời nhắc trong CI/lần chạy không tương tác. ## Hook đi kèm ### session-memory -Lưu ngữ cảnh phiên vào bộ nhớ khi bạn phát hành `/new` hoặc `/reset`. +Lưu ngữ cảnh phiên vào bộ nhớ khi bạn phát `/new` hoặc `/reset`. **Bật:** @@ -289,13 +289,13 @@ Lưu ngữ cảnh phiên vào bộ nhớ khi bạn phát hành `/new` hoặc `/r openclaw hooks enable session-memory ``` -**Đầu ra:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md` +**Đầu ra:** mặc định là `~/.openclaw/workspace/memory/YYYY-MM-DD-HHMM.md`. Đặt `hooks.internal.entries.session-memory.llmSlug: true` cho slug tên tệp do mô hình tạo. **Xem:** [tài liệu session-memory](/vi/automation/hooks#session-memory) ### bootstrap-extra-files -Chèn các tệp bootstrap bổ sung (ví dụ `AGENTS.md` / `TOOLS.md` cục bộ trong monorepo) trong lúc `agent:bootstrap`. +Chèn các tệp bootstrap bổ sung (ví dụ `AGENTS.md` / `TOOLS.md` cục bộ của monorepo) trong `agent:bootstrap`. **Bật:** diff --git a/docs/vi/cli/sessions.md b/docs/vi/cli/sessions.md index 454f5851e..d6f5fcc91 100644 --- a/docs/vi/cli/sessions.md +++ b/docs/vi/cli/sessions.md @@ -4,10 +4,10 @@ read_when: summary: Tài liệu tham chiếu CLI cho `openclaw sessions` (liệt kê các phiên đã lưu + cách sử dụng) title: Phiên làm việc x-i18n: - generated_at: "2026-05-05T01:44:53Z" + generated_at: "2026-05-05T08:25:16Z" model: gpt-5.5 provider: openai - source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7 + source_hash: a204189952bc82788eb724c0a6b6db93c7d6795ad69bb6d498e8575236c3272e source_path: cli/sessions.md workflow: 16 --- @@ -16,9 +16,9 @@ x-i18n: Liệt kê các phiên hội thoại đã lưu. -Danh sách phiên không phải là kiểm tra khả năng hoạt động của kênh/nhà cung cấp. Chúng hiển thị các hàng hội thoại đã được lưu bền vững từ kho phiên. Một kênh Discord, Slack, Telegram hoặc kênh khác đang im lặng có thể kết nối lại thành công mà không tạo hàng phiên mới cho đến khi một tin nhắn được xử lý. Dùng `openclaw channels status --probe`, `openclaw status --deep`, hoặc `openclaw health --verbose` khi bạn cần kết nối kênh trực tiếp. +Danh sách phiên không phải là kiểm tra trạng thái hoạt động của kênh/nhà cung cấp. Chúng hiển thị các hàng hội thoại đã được lưu bền vững từ kho lưu trữ phiên. Một Discord, Slack, Telegram hoặc kênh khác đang im lặng vẫn có thể kết nối lại thành công mà không tạo hàng phiên mới cho đến khi một tin nhắn được xử lý. Dùng `openclaw channels status --probe`, `openclaw status --deep`, hoặc `openclaw health --verbose` khi bạn cần kiểm tra kết nối kênh trực tiếp. -Phản hồi của `openclaw sessions` và Gateway `sessions.list` được giới hạn theo mặc định để các kho lớn tồn tại lâu không thể chiếm độc quyền tiến trình CLI hoặc vòng lặp sự kiện Gateway. CLI trả về 100 phiên mới nhất theo mặc định; truyền `--limit ` để dùng cửa sổ nhỏ hơn/lớn hơn hoặc `--limit all` khi bạn thực sự cần toàn bộ kho. Phản hồi JSON bao gồm `totalCount`, `limitApplied`, và `hasMore` khi bên gọi cần hiển thị rằng còn nhiều hàng hơn. +Phản hồi của `openclaw sessions` và Gateway `sessions.list` được giới hạn theo mặc định để các kho lưu trữ lớn tồn tại lâu không thể chiếm độc quyền tiến trình CLI hoặc vòng lặp sự kiện Gateway. Theo mặc định, CLI trả về 100 phiên mới nhất; truyền `--limit ` để lấy một cửa sổ nhỏ hơn/lớn hơn hoặc `--limit all` khi bạn chủ ý cần toàn bộ kho lưu trữ. Phản hồi JSON bao gồm `totalCount`, `limitApplied`, và `hasMore` khi bên gọi cần hiển thị rằng vẫn còn thêm hàng. ```bash openclaw sessions @@ -32,11 +32,11 @@ openclaw sessions --json Chọn phạm vi: -- mặc định: kho agent mặc định đã cấu hình +- mặc định: kho lưu trữ tác nhân mặc định đã cấu hình - `--verbose`: ghi log chi tiết -- `--agent `: một kho agent đã cấu hình -- `--all-agents`: tổng hợp tất cả kho agent đã cấu hình -- `--store `: đường dẫn kho rõ ràng (không thể kết hợp với `--agent` hoặc `--all-agents`) +- `--agent `: một kho lưu trữ tác nhân đã cấu hình +- `--all-agents`: tổng hợp tất cả kho lưu trữ tác nhân đã cấu hình +- `--store `: đường dẫn kho lưu trữ rõ ràng (không thể kết hợp với `--agent` hoặc `--all-agents`) - `--limit `: số hàng tối đa để xuất (mặc định `100`; `all` khôi phục đầu ra đầy đủ) Xuất một gói quỹ đạo cho một phiên đã lưu: @@ -46,9 +46,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -Đây là đường dẫn lệnh được lệnh slash `/export-trajectory` sử dụng sau khi chủ sở hữu phê duyệt yêu cầu exec. Thư mục đầu ra luôn được phân giải bên trong `.openclaw/trajectory-exports/` trong workspace đã chọn. +Đây là đường dẫn lệnh được dùng bởi lệnh gạch chéo `/export-trajectory` sau khi chủ sở hữu phê duyệt yêu cầu exec. Thư mục đầu ra luôn được phân giải bên trong `.openclaw/trajectory-exports/` dưới workspace đã chọn. -`openclaw sessions --all-agents` đọc các kho agent đã cấu hình. Cơ chế khám phá phiên của Gateway và ACP rộng hơn: chúng cũng bao gồm các kho chỉ có trên đĩa được tìm thấy dưới gốc `agents/` mặc định hoặc gốc `session.store` theo mẫu. Các kho được khám phá đó phải phân giải thành các tệp `sessions.json` thông thường bên trong gốc agent; symlink và đường dẫn ngoài gốc sẽ bị bỏ qua. +`openclaw sessions --all-agents` đọc các kho lưu trữ tác nhân đã cấu hình. Việc khám phá phiên của Gateway và ACP rộng hơn: chúng cũng bao gồm các kho chỉ có trên đĩa được tìm thấy dưới gốc `agents/` mặc định hoặc gốc `session.store` theo mẫu. Các kho được khám phá đó phải phân giải thành các tệp `sessions.json` thông thường bên trong gốc tác nhân; symlink và đường dẫn ngoài gốc sẽ bị bỏ qua. Ví dụ JSON: @@ -87,21 +87,22 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` sử dụng cài đặt `session.maintenance` từ cấu hình: +`openclaw sessions cleanup` dùng các thiết lập `session.maintenance` từ cấu hình: -- Ghi chú phạm vi: `openclaw sessions cleanup` bảo trì kho phiên, bản ghi hội thoại, và sidecar quỹ đạo. Nó không cắt tỉa log lần chạy cron (`cron/runs/.jsonl`), vốn được quản lý bởi `cron.runLog.maxBytes` và `cron.runLog.keepLines` trong [Cấu hình Cron](/vi/automation/cron-jobs#configuration) và được giải thích trong [Bảo trì Cron](/vi/automation/cron-jobs#maintenance). +- Ghi chú phạm vi: `openclaw sessions cleanup` bảo trì kho lưu trữ phiên, bản ghi transcript, và các tệp phụ trợ quỹ đạo. Nó không cắt tỉa log chạy cron (`cron/runs/.jsonl`), vốn được quản lý bởi `cron.runLog.maxBytes` và `cron.runLog.keepLines` trong [cấu hình Cron](/vi/automation/cron-jobs#configuration) và được giải thích trong [bảo trì Cron](/vi/automation/cron-jobs#maintenance). +- Việc dọn dẹp cũng cắt tỉa các transcript chính không được tham chiếu, điểm kiểm tra Compaction, và tệp phụ trợ quỹ đạo cũ hơn `session.maintenance.pruneAfter`; các tệp vẫn được `sessions.json` tham chiếu sẽ được giữ lại. -- `--dry-run`: xem trước có bao nhiêu mục sẽ bị cắt tỉa/giới hạn mà không ghi. +- `--dry-run`: xem trước bao nhiêu mục sẽ bị cắt tỉa/giới hạn mà không ghi dữ liệu. - Ở chế độ văn bản, dry-run in một bảng hành động theo từng phiên (`Action`, `Key`, `Age`, `Model`, `Flags`) để bạn có thể thấy mục nào sẽ được giữ lại so với bị xóa. - `--enforce`: áp dụng bảo trì ngay cả khi `session.maintenance.mode` là `warn`. -- `--fix-missing`: xóa các mục có tệp bản ghi hội thoại bị thiếu, ngay cả khi thông thường chúng chưa bị loại theo tuổi/số lượng. -- `--active-key `: bảo vệ một khóa đang hoạt động cụ thể khỏi việc bị loại do ngân sách đĩa. Các con trỏ hội thoại bên ngoài bền vững, chẳng hạn như phiên nhóm và phiên trò chuyện theo phạm vi luồng, cũng được giữ lại bởi bảo trì theo tuổi/số lượng/ngân sách đĩa. -- `--agent `: chạy dọn dẹp cho một kho agent đã cấu hình. -- `--all-agents`: chạy dọn dẹp cho tất cả kho agent đã cấu hình. +- `--fix-missing`: xóa các mục có tệp transcript bị thiếu, ngay cả khi bình thường chúng chưa bị loại theo tuổi/số lượng. +- `--active-key `: bảo vệ một khóa đang hoạt động cụ thể khỏi bị loại do ngân sách đĩa. Các con trỏ hội thoại bên ngoài bền vững, chẳng hạn như phiên nhóm và phiên trò chuyện theo phạm vi luồng, cũng được bảo toàn bởi bảo trì theo tuổi/số lượng/ngân sách đĩa. +- `--agent `: chạy dọn dẹp cho một kho lưu trữ tác nhân đã cấu hình. +- `--all-agents`: chạy dọn dẹp cho tất cả kho lưu trữ tác nhân đã cấu hình. - `--store `: chạy trên một tệp `sessions.json` cụ thể. -- `--json`: in tóm tắt JSON. Với `--all-agents`, đầu ra bao gồm một tóm tắt cho mỗi kho. +- `--json`: in bản tóm tắt JSON. Với `--all-agents`, đầu ra bao gồm một bản tóm tắt cho mỗi kho lưu trữ. -Khi có thể truy cập Gateway, thao tác dọn dẹp không phải dry-run cho các kho agent đã cấu hình sẽ được gửi qua Gateway để nó dùng chung trình ghi kho phiên với lưu lượng runtime. Dùng `--store ` để sửa chữa ngoại tuyến rõ ràng một tệp kho. +Khi có thể truy cập Gateway, việc dọn dẹp không phải dry-run cho các kho lưu trữ tác nhân đã cấu hình được gửi qua Gateway để nó dùng chung trình ghi kho lưu trữ phiên với lưu lượng runtime. Dùng `--store ` để sửa chữa ngoại tuyến rõ ràng một tệp kho lưu trữ. `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/vi/concepts/mantis.md b/docs/vi/concepts/mantis.md index b7628ecbf..665b3fd6f 100644 --- a/docs/vi/concepts/mantis.md +++ b/docs/vi/concepts/mantis.md @@ -1,86 +1,65 @@ --- read_when: - - Xây dựng hoặc chạy quy trình đảm bảo chất lượng trực quan trực tiếp cho các lỗi OpenClaw - - Thêm xác minh trước và sau cho một pull request - - Thêm Discord, Slack, WhatsApp hoặc các kịch bản truyền tải trực tiếp khác + - Xây dựng hoặc chạy QA trực quan trực tiếp cho lỗi OpenClaw + - Thêm bước xác minh trước và sau cho một yêu cầu kéo + - Thêm các kịch bản cho Discord, Slack, WhatsApp hoặc các phương thức truyền tải trực tiếp khác - Gỡ lỗi các lần chạy QA cần ảnh chụp màn hình, tự động hóa trình duyệt hoặc quyền truy cập VNC -summary: Mantis là hệ thống xác minh trực quan từ đầu đến cuối để tái hiện lỗi OpenClaw trên các kênh truyền tải trực tiếp, thu thập bằng chứng trước và sau, và đính kèm tạo tác vào các PR. +summary: Mantis là hệ thống xác minh đầu cuối trực quan để tái hiện lỗi OpenClaw trên các phương thức truyền tải đang hoạt động, thu thập bằng chứng trước và sau, rồi đính kèm các tạo tác vào PR. title: Bọ ngựa x-i18n: - generated_at: "2026-05-05T06:16:34Z" + generated_at: "2026-05-05T08:25:49Z" model: gpt-5.5 provider: openai - source_hash: 26a9671135e38bf82d3627364f691f8d91cc8649ffc2e5fa782ebef474a44fa1 + source_hash: 6b287e2832e3e49de6b3cb65aeb1d381a36fc30ce9c94dc5b6b4d7e928c2706c source_path: concepts/mantis.md workflow: 16 --- -Mantis là hệ thống xác minh đầu-cuối của OpenClaw dành cho các lỗi cần runtime -thật, transport thật và bằng chứng có thể nhìn thấy. Nó chạy một kịch bản trên -một ref đã biết là lỗi, thu thập bằng chứng, chạy cùng kịch bản đó trên một ref -ứng viên, rồi xuất bản phần so sánh dưới dạng artifact mà maintainer có thể kiểm -tra từ PR hoặc từ một lệnh cục bộ. +Mantis là hệ thống xác minh đầu cuối của OpenClaw dành cho các lỗi cần runtime thật, transport thật và bằng chứng trực quan. Hệ thống chạy một kịch bản trên một ref đã biết là lỗi, thu thập bằng chứng, chạy cùng kịch bản đó trên một ref ứng viên, rồi xuất bản phần so sánh dưới dạng artifact để maintainer có thể kiểm tra từ PR hoặc từ lệnh cục bộ. -Mantis bắt đầu với Discord vì Discord cung cấp cho chúng ta một làn đầu tiên có -giá trị cao: xác thực bot thật, kênh guild thật, phản ứng, thread, lệnh native và -giao diện trình duyệt nơi con người có thể xác nhận trực quan những gì transport -đã hiển thị. +Mantis bắt đầu với Discord vì Discord cung cấp cho chúng ta một lane đầu tiên có giá trị cao: xác thực bot thật, kênh guild thật, reaction, thread, lệnh gốc và một UI trình duyệt nơi con người có thể xác nhận trực quan những gì transport đã hiển thị. ## Mục tiêu -- Tái hiện lỗi từ một issue hoặc PR trên GitHub với cùng hình dạng transport mà - người dùng nhìn thấy. +- Tái hiện một lỗi từ GitHub issue hoặc PR với cùng hình dạng transport mà người dùng thấy. - Thu thập artifact **trước** trên ref baseline trước khi áp dụng bản sửa. - Thu thập artifact **sau** trên ref ứng viên sau khi áp dụng bản sửa. -- Dùng oracle xác định được bất cứ khi nào có thể, chẳng hạn đọc phản ứng qua - Discord REST hoặc kiểm tra transcript của kênh. -- Chụp ảnh màn hình khi lỗi có bề mặt UI nhìn thấy được. +- Sử dụng oracle xác định khi có thể, chẳng hạn như đọc reaction qua Discord REST hoặc kiểm tra transcript kênh. +- Chụp ảnh màn hình khi lỗi có bề mặt UI thấy được. - Chạy cục bộ từ CLI do agent kiểm soát và chạy từ xa từ GitHub. -- Giữ lại đủ trạng thái máy để cứu hộ qua VNC khi đăng nhập, tự động hóa trình - duyệt hoặc xác thực provider bị kẹt. -- Đăng trạng thái ngắn gọn lên kênh Discord của operator khi lượt chạy bị chặn, - cần trợ giúp VNC thủ công hoặc hoàn tất. +- Giữ đủ trạng thái máy để cứu hộ qua VNC khi đăng nhập, tự động hóa trình duyệt hoặc xác thực provider bị kẹt. +- Đăng trạng thái ngắn gọn lên kênh Discord của operator khi lượt chạy bị chặn, cần trợ giúp VNC thủ công hoặc hoàn tất. ## Không phải mục tiêu -- Mantis không thay thế cho kiểm thử đơn vị. Một lượt chạy Mantis thường nên trở - thành một kiểm thử hồi quy nhỏ hơn sau khi đã hiểu bản sửa. -- Mantis không phải cổng CI nhanh thông thường. Nó chậm hơn, dùng credential - live và được dành cho các lỗi mà môi trường live có ý nghĩa. -- Mantis không nên cần con người trong vận hành thông thường. VNC thủ công là - đường cứu hộ, không phải luồng lý tưởng. -- Mantis không lưu secret thô trong artifact, log, ảnh chụp màn hình, báo cáo - Markdown hoặc bình luận PR. +- Mantis không thay thế unit test. Một lượt chạy Mantis thường nên trở thành một regression test nhỏ hơn sau khi đã hiểu bản sửa. +- Mantis không phải cổng CI nhanh thông thường. Nó chậm hơn, dùng credential live và chỉ dành cho các lỗi mà môi trường live có ý nghĩa. +- Mantis không nên cần con người trong vận hành bình thường. VNC thủ công là đường cứu hộ, không phải happy path. +- Mantis không lưu secret thô trong artifact, log, ảnh chụp màn hình, báo cáo Markdown hoặc bình luận PR. ## Quyền sở hữu -Mantis nằm trong stack QA của OpenClaw. +Mantis nằm trong ngăn xếp QA của OpenClaw. -- OpenClaw sở hữu runtime kịch bản, adapter transport, schema bằng chứng và CLI - cục bộ dưới `pnpm openclaw qa mantis`. -- QA Lab sở hữu các phần live transport harness, helper chụp trình duyệt và bộ - ghi artifact. -- Crabbox sở hữu các máy Linux đã làm nóng khi cần VM từ xa. -- GitHub Actions sở hữu điểm vào workflow từ xa và việc lưu giữ artifact. -- ClawSweeper sở hữu định tuyến bình luận GitHub: phân tích lệnh maintainer, - dispatch workflow và đăng bình luận PR cuối cùng. -- Agent OpenClaw điều khiển Mantis thông qua Codex khi kịch bản cần thiết lập - kiểu agentic, gỡ lỗi hoặc báo cáo trạng thái bị kẹt. +- OpenClaw sở hữu runtime kịch bản, adapter transport, schema bằng chứng và CLI cục bộ dưới `pnpm openclaw qa mantis`. +- QA Lab sở hữu các phần harness transport live, helper chụp trình duyệt và writer artifact. +- Crabbox sở hữu các máy Linux đã được làm nóng khi cần VM từ xa. +- GitHub Actions sở hữu entrypoint workflow từ xa và chính sách giữ artifact. +- ClawSweeper sở hữu định tuyến bình luận GitHub: phân tích lệnh maintainer, dispatch workflow và đăng bình luận PR cuối cùng. +- OpenClaw agent điều khiển Mantis qua Codex khi một kịch bản cần thiết lập kiểu agentic, gỡ lỗi hoặc báo cáo trạng thái bị kẹt. -Ranh giới này giữ kiến thức transport trong OpenClaw, lập lịch máy trong -Crabbox, và phần kết nối workflow maintainer trong ClawSweeper. +Ranh giới này giữ kiến thức transport trong OpenClaw, lập lịch máy trong Crabbox và phần keo workflow maintainer trong ClawSweeper. ## Hình dạng lệnh -Lệnh cục bộ đầu tiên xác minh bot Discord, guild, kênh, gửi tin nhắn, gửi phản -ứng và đường dẫn artifact: +Lệnh cục bộ đầu tiên xác minh bot Discord, guild, kênh, gửi tin nhắn, gửi reaction và đường dẫn artifact: ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -Runner cục bộ trước và sau nhận hình dạng này: +Runner cục bộ trước và sau chấp nhận hình dạng này: ```bash pnpm openclaw qa mantis run \ @@ -91,11 +70,7 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -Runner tạo các worktree baseline và candidate tách rời dưới thư mục output, cài -đặt dependency, build từng ref, chạy kịch bản với `--allow-failures`, rồi ghi -`baseline/`, `candidate/`, `comparison.json` và `mantis-report.md`. Với kịch bản -Discord đầu tiên, xác minh thành công nghĩa là trạng thái baseline là `fail` và -trạng thái candidate là `pass`. +Runner tạo baseline worktree và candidate worktree tách rời dưới thư mục output, cài dependency, build từng ref, chạy kịch bản với `--allow-failures`, rồi ghi `baseline/`, `candidate/`, `comparison.json` và `mantis-report.md`. Với kịch bản Discord đầu tiên, xác minh thành công nghĩa là trạng thái baseline là `fail` và trạng thái candidate là `pass`. Primitive VM/trình duyệt đầu tiên là desktop smoke: @@ -104,22 +79,17 @@ pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -Nó thuê hoặc tái sử dụng một máy desktop Crabbox, khởi động trình duyệt nhìn thấy -được bên trong phiên VNC, chụp desktop, kéo artifact về thư mục output cục bộ và -ghi lệnh kết nối lại vào báo cáo. Lệnh mặc định dùng provider Hetzner vì đây là -provider đầu tiên có coverage desktop/VNC hoạt động trong làn Mantis. Ghi đè nó -bằng `--provider`, `--crabbox-bin` hoặc -`OPENCLAW_MANTIS_CRABBOX_PROVIDER` khi chạy với một fleet Crabbox khác. +Nó thuê hoặc tái sử dụng một máy desktop Crabbox, khởi động một trình duyệt hiển thị bên trong phiên VNC, chụp desktop, kéo artifact về thư mục output cục bộ và ghi lệnh kết nối lại vào báo cáo. Lệnh mặc định dùng provider Hetzner vì đây là provider đầu tiên có coverage desktop/VNC hoạt động trong lane Mantis. Ghi đè bằng `--provider`, `--crabbox-bin` hoặc `OPENCLAW_MANTIS_CRABBOX_PROVIDER` khi chạy với một fleet Crabbox khác. Các flag desktop smoke hữu ích: -- `--lease-id ` hoặc `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` tái sử dụng desktop đã làm nóng. -- `--browser-url ` thay đổi trang được mở trong trình duyệt nhìn thấy được. -- `--html-file ` render một artifact HTML cục bộ trong repo trong trình duyệt nhìn thấy được. Mantis dùng cách này để chụp timeline phản ứng trạng thái Discord đã tạo thông qua desktop Crabbox thật. -- `--keep-lease` hoặc `OPENCLAW_MANTIS_KEEP_VM=1` giữ lease mới tạo đang pass mở để kiểm tra qua VNC. Các lượt chạy thất bại mặc định giữ lease khi lease được tạo để operator có thể kết nối lại. -- `--class`, `--idle-timeout` và `--ttl` điều chỉnh kích thước máy và thời gian tồn tại của lease. +- `--lease-id ` hoặc `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` tái sử dụng một desktop đã được làm nóng. +- `--browser-url ` thay đổi trang được mở trong trình duyệt hiển thị. +- `--html-file ` render một artifact HTML cục bộ của repo trong trình duyệt hiển thị. Mantis dùng tùy chọn này để chụp timeline status-reaction Discord đã tạo thông qua một desktop Crabbox thật. +- `--keep-lease` hoặc `OPENCLAW_MANTIS_KEEP_VM=1` giữ một lease mới tạo đã pass mở để kiểm tra qua VNC. Các lượt chạy thất bại mặc định giữ lease khi một lease được tạo để operator có thể kết nối lại. +- `--class`, `--idle-timeout` và `--ttl` điều chỉnh kích thước máy và thời lượng lease. -Primitive desktop transport đầy đủ đầu tiên là Slack desktop smoke: +Primitive transport desktop đầy đủ đầu tiên là Slack desktop smoke: ```bash pnpm openclaw qa mantis slack-desktop-smoke \ @@ -129,18 +99,9 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -Nó thuê hoặc tái sử dụng một máy desktop Crabbox, đồng bộ checkout hiện tại vào -VM, chạy `pnpm openclaw qa slack` bên trong VM đó, mở Slack Web trong trình duyệt -VNC, chụp desktop nhìn thấy được và sao chép cả artifact Slack QA lẫn ảnh chụp -màn hình VNC về thư mục output cục bộ. Đây là hình dạng Mantis đầu tiên mà SUT -OpenClaw gateway và trình duyệt đều nằm trong cùng một VM desktop Linux. +Nó thuê hoặc tái sử dụng một máy desktop Crabbox, đồng bộ checkout hiện tại vào VM, chạy `pnpm openclaw qa slack` bên trong VM đó, mở Slack Web trong trình duyệt VNC, chụp desktop hiển thị và sao chép cả artifact Slack QA lẫn ảnh chụp VNC về thư mục output cục bộ. Đây là hình dạng Mantis đầu tiên mà Gateway OpenClaw SUT và trình duyệt đều nằm trong cùng một VM desktop Linux. -Với `--gateway-setup`, lệnh chuẩn bị một home OpenClaw dùng một lần nhưng bền -vững tại `$HOME/.openclaw-mantis/slack-openclaw`, vá cấu hình Slack Socket Mode -cho kênh đã chọn, khởi động `openclaw gateway run` trên cổng `38973` và giữ -Chrome chạy trong phiên VNC. Đây là chế độ "để lại cho tôi một desktop Linux có -Slack và một claw đang chạy"; làn Slack QA bot-to-bot vẫn là mặc định khi bỏ qua -`--gateway-setup`. +Với `--gateway-setup`, lệnh chuẩn bị một home OpenClaw dùng một lần nhưng bền vững tại `$HOME/.openclaw-mantis/slack-openclaw`, vá cấu hình Slack Socket Mode cho kênh đã chọn, khởi động `openclaw gateway run` trên cổng `38973` và giữ Chrome chạy trong phiên VNC. Đây là chế độ "để lại cho tôi một desktop Linux có Slack và một claw đang chạy"; lane Slack QA bot-to-bot vẫn là mặc định khi bỏ qua `--gateway-setup`. Input bắt buộc cho `--credential-source env`: @@ -148,49 +109,78 @@ Input bắt buộc cho `--credential-source env`: - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN` - `OPENCLAW_QA_SLACK_SUT_APP_TOKEN` -- `OPENCLAW_LIVE_OPENAI_KEY` cho làn model từ xa. Nếu chỉ - `OPENAI_API_KEY` được đặt cục bộ, Mantis ánh xạ nó sang `OPENCLAW_LIVE_OPENAI_KEY` - trước khi gọi Crabbox để cơ chế chuyển tiếp env `OPENCLAW_*` của Crabbox có thể - đưa nó vào VM. +- `OPENCLAW_LIVE_OPENAI_KEY` cho lane model từ xa. Nếu chỉ có `OPENAI_API_KEY` được đặt cục bộ, Mantis ánh xạ nó sang `OPENCLAW_LIVE_OPENAI_KEY` trước khi gọi Crabbox để cơ chế chuyển tiếp env `OPENCLAW_*` của Crabbox có thể mang nó vào VM. Các flag Slack desktop hữu ích: -- `--lease-id ` chạy lại trên một máy nơi operator đã đăng nhập vào Slack Web qua VNC. -- `--gateway-setup` khởi động một OpenClaw Slack gateway bền vững trong VM thay vì chỉ chạy làn QA bot-to-bot. +- `--lease-id ` chạy lại trên một máy mà operator đã đăng nhập vào Slack Web qua VNC. +- `--gateway-setup` khởi động một Gateway Slack OpenClaw bền vững trong VM thay vì chỉ chạy lane QA bot-to-bot. - `--slack-url ` mở một URL Slack Web cụ thể. Nếu không có, Mantis suy ra `https://app.slack.com/client//` từ Slack `auth.test` khi token bot SUT có sẵn. -- `--slack-channel-id ` kiểm soát allowlist kênh Slack được dùng bởi thiết lập gateway. -- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` kiểm soát profile Chrome bền vững bên trong VM. Mặc định là `$HOME/.config/openclaw-mantis/slack-chrome-profile`, nên một phiên đăng nhập Slack Web thủ công vẫn tồn tại qua các lần chạy lại trên cùng lease. +- `--slack-channel-id ` kiểm soát allowlist kênh Slack được dùng bởi thiết lập Gateway. +- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` kiểm soát profile Chrome bền vững bên trong VM. Mặc định là `$HOME/.config/openclaw-mantis/slack-chrome-profile`, nên đăng nhập Slack Web thủ công sẽ tồn tại qua các lần chạy lại trên cùng lease. - `--credential-source convex --credential-role ci` dùng pool credential dùng chung thay vì token env Slack trực tiếp. -- `--provider-mode`, `--model`, `--alt-model` và `--fast` được truyền tiếp sang làn Slack live. +- `--provider-mode`, `--model`, `--alt-model` và `--fast` được truyền tiếp sang lane live Slack. -Workflow smoke GitHub là `Mantis Discord Smoke`. Workflow GitHub trước và sau -cho kịch bản thật đầu tiên là `Mantis Discord Status Reactions`. Nó nhận: +Workflow smoke GitHub là `Mantis Discord Smoke`. Workflow GitHub trước và sau cho kịch bản thật đầu tiên là `Mantis Discord Status Reactions`. Nó chấp nhận: -- `baseline_ref`: ref được kỳ vọng tái hiện hành vi chỉ-queued. -- `candidate_ref`: ref được kỳ vọng hiển thị `queued -> thinking -> done`. +- `baseline_ref`: ref dự kiến tái hiện hành vi chỉ queued. +- `candidate_ref`: ref dự kiến hiển thị `queued -> thinking -> done`. -Nó checkout ref harness workflow, build các worktree baseline và candidate riêng -biệt, chạy `discord-status-reactions-tool-only` trên từng worktree và upload -`baseline/`, `candidate/`, `comparison.json` và `mantis-report.md` dưới dạng -artifact Actions. Nó cũng render HTML timeline của từng làn trong trình duyệt -desktop Crabbox và xuất bản các ảnh chụp màn hình VNC đó bên cạnh các PNG -timeline xác định được trong bình luận PR. Cùng bình luận PR đó liên kết tới các -bản ghi MP4 desktop được chụp trong quá trình render trình duyệt VNC, còn ảnh -chụp màn hình vẫn nằm inline để review nhanh. Workflow build Crabbox CLI từ -`openclaw/crabbox` main để có thể dùng các flag lease desktop/trình duyệt hiện -tại trước khi bản phát hành binary Crabbox tiếp theo được cắt. +Nó checkout ref harness workflow, build các worktree baseline và candidate riêng biệt, chạy `discord-status-reactions-tool-only` trên từng worktree và tải lên `baseline/`, `candidate/`, `comparison.json` và `mantis-report.md` dưới dạng artifact Actions. Nó cũng render HTML timeline của từng lane trong trình duyệt desktop Crabbox và xuất bản các ảnh chụp VNC đó bên cạnh PNG timeline xác định trong bình luận PR. Cùng bình luận PR đó nhúng các preview GIF nhẹ đã cắt theo chuyển động được tạo bởi `crabbox media preview`, liên kết tới các clip MP4 tương ứng đã cắt theo chuyển động và giữ các file MP4 desktop đầy đủ để kiểm tra sâu. Ảnh chụp màn hình vẫn được nhúng inline để review nhanh. Workflow build Crabbox CLI từ `openclaw/crabbox` main để có thể dùng các flag lease desktop/trình duyệt hiện tại trước khi bản phát hành binary Crabbox tiếp theo được cắt. -Bạn cũng có thể kích hoạt lượt chạy status-reactions trực tiếp từ bình luận PR: +`Mantis Scenario` là entrypoint thủ công chung. Nó nhận `scenario_id`, `candidate_ref`, `baseline_ref` tùy chọn và `pr_number` tùy chọn, rồi dispatch workflow do kịch bản sở hữu. Wrapper này cố ý mỏng: workflow kịch bản vẫn sở hữu thiết lập transport, credential, lớp VM, oracle kỳ vọng và manifest artifact của nó. + +`Mantis Slack Desktop Smoke` là workflow VM Slack đầu tiên. Nó checkout ref ứng viên đáng tin cậy trong một worktree riêng, thuê desktop Linux Crabbox, chạy `pnpm openclaw qa mantis slack-desktop-smoke --gateway-setup` với ứng viên đó, mở Slack Web trong trình duyệt VNC, ghi lại desktop, tạo preview đã cắt theo chuyển động bằng `crabbox media preview`, tải lên toàn bộ thư mục artifact và tùy chọn đăng bình luận bằng chứng inline trên PR mục tiêu. Dùng lane này khi bạn muốn "một desktop Linux có Slack và một claw đang chạy" thay vì chỉ một transcript Slack bot-to-bot. + +Mọi kịch bản xuất bản PR đều ghi `mantis-evidence.json` cạnh báo cáo của nó. Schema này là phần bàn giao giữa code kịch bản và bình luận GitHub: + +```json +{ + "schemaVersion": 1, + "id": "discord-status-reactions", + "title": "Mantis Discord Status Reactions QA", + "summary": "Human-readable top summary for the PR comment.", + "scenario": "discord-status-reactions-tool-only", + "comparison": { + "baseline": { "sha": "...", "status": "fail", "expected": "queued-only" }, + "candidate": { "sha": "...", "status": "pass", "expected": "queued -> thinking -> done" }, + "pass": true + }, + "artifacts": [ + { + "kind": "timeline", + "lane": "baseline", + "label": "Baseline queued-only", + "path": "baseline/timeline.png", + "targetPath": "baseline.png", + "alt": "Baseline Discord timeline", + "width": 420 + } + ] +} +``` + +Giá trị `path` của artifact tương đối với thư mục manifest. Giá trị `targetPath` là đường dẫn tương đối dưới thư mục publish nhánh `qa-artifacts`. Publisher từ chối path traversal và bỏ qua các mục được đánh dấu `"required": false` khi preview hoặc video tùy chọn không khả dụng. + +Các kind artifact được hỗ trợ: + +- `timeline`: ảnh chụp màn hình kịch bản xác định, thường là trước/sau. +- `desktopScreenshot`: ảnh chụp màn hình desktop VNC/trình duyệt. +- `motionPreview`: GIF động inline được tạo từ bản ghi desktop. +- `motionClip`: MP4 đã cắt theo chuyển động, loại bỏ phần tĩnh đầu và cuối. +- `fullVideo`: bản ghi MP4 đầy đủ để kiểm tra sâu. +- `metadata`: sidecar JSON/log. +- `report`: báo cáo Markdown. + +Publisher tái sử dụng là `scripts/mantis/publish-pr-evidence.mjs`. Workflow gọi nó với manifest, PR mục tiêu, root mục tiêu `qa-artifacts`, marker bình luận, URL artifact Actions, URL lượt chạy và nguồn yêu cầu. Nó sao chép các artifact đã khai báo sang nhánh `qa-artifacts`, build một bình luận PR đặt tóm tắt lên trước với ảnh/preview inline và video được liên kết, rồi cập nhật bình luận marker hiện có hoặc tạo mới. + +Bạn cũng có thể kích hoạt trực tiếp lượt chạy status-reactions từ bình luận PR: ```text @Mantis discord status reactions ``` -Trigger qua bình luận được cố ý giới hạn hẹp. Nó chỉ chạy trên bình luận pull -request từ người dùng có quyền write, maintain hoặc admin, và chỉ nhận diện các -yêu cầu phản ứng trạng thái Discord. Mặc định, nó dùng ref baseline đã biết là -lỗi và SHA head của PR hiện tại làm candidate. Maintainer có thể ghi đè một -trong hai ref: +Trigger bình luận này được cố ý giới hạn hẹp. Nó chỉ chạy trên bình luận pull request từ người dùng có quyền write, maintain hoặc admin, và chỉ nhận dạng yêu cầu status-reaction của Discord. Theo mặc định, nó dùng ref baseline lỗi đã biết và SHA head PR hiện tại làm ứng viên. Maintainer có thể ghi đè một trong hai ref: ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -203,52 +193,51 @@ Ví dụ lệnh ClawSweeper: @clawsweeper verify e2e discord ``` -Lệnh đầu tiên rõ ràng và tập trung vào kịch bản. Lệnh thứ hai về sau có thể ánh -xạ một PR hoặc issue sang các kịch bản Mantis được khuyến nghị từ label, file đã -thay đổi và phát hiện review của ClawSweeper. +Lệnh đầu tiên rõ ràng và tập trung vào kịch bản. Lệnh thứ hai về sau có thể ánh xạ một PR +hoặc issue tới các kịch bản Mantis được khuyến nghị từ nhãn, tệp đã thay đổi và +các phát hiện đánh giá của ClawSweeper. ## Vòng đời chạy -1. Lấy credential. -2. Cấp phát hoặc tái sử dụng VM. -3. Chuẩn bị profile desktop/trình duyệt khi kịch bản cần bằng chứng UI. -4. Chuẩn bị checkout sạch cho ref baseline. +1. Lấy thông tin xác thực. +2. Cấp phát hoặc tái sử dụng một VM. +3. Chuẩn bị hồ sơ desktop/trình duyệt khi kịch bản cần bằng chứng UI. +4. Chuẩn bị một checkout sạch cho ref baseline. 5. Cài đặt dependency và chỉ build những gì kịch bản cần. -6. Khởi động OpenClaw Gateway con với thư mục trạng thái cô lập. -7. Cấu hình live transport, provider, model và profile trình duyệt. +6. Khởi động một OpenClaw Gateway con với thư mục trạng thái cô lập. +7. Cấu hình transport trực tiếp, nhà cung cấp, model và hồ sơ trình duyệt. 8. Chạy kịch bản và thu thập bằng chứng baseline. 9. Dừng gateway và giữ lại log. 10. Chuẩn bị ref candidate trong cùng VM. -11. Chạy cùng kịch bản đó và thu thập bằng chứng candidate. +11. Chạy cùng kịch bản và thu thập bằng chứng candidate. 12. So sánh kết quả oracle và bằng chứng trực quan. -13. Ghi Markdown, JSON, log, ảnh chụp màn hình và artifact trace tùy chọn. -14. Upload artifact GitHub Actions. +13. Ghi Markdown, JSON, log, ảnh chụp màn hình và các artifact trace tùy chọn. +14. Tải artifact GitHub Actions lên. 15. Đăng một thông báo trạng thái PR hoặc Discord ngắn gọn. -Kịch bản nên có thể thất bại theo hai cách khác nhau: +Kịch bản phải có thể thất bại theo hai cách khác nhau: -- **Đã tái hiện lỗi**: baseline thất bại theo cách được kỳ vọng. -- **Lỗi harness**: thiết lập môi trường, credential, Discord API, trình duyệt - hoặc provider thất bại trước khi bug oracle có ý nghĩa. +- **Đã tái hiện lỗi**: baseline thất bại theo cách dự kiến. +- **Lỗi harness**: thiết lập môi trường, thông tin xác thực, Discord API, trình duyệt hoặc + nhà cung cấp thất bại trước khi oracle lỗi có ý nghĩa. -Báo cáo cuối cùng phải tách riêng các trường hợp này để maintainer không nhầm -môi trường không ổn định với hành vi sản phẩm. +Báo cáo cuối cùng phải tách riêng các trường hợp này để maintainer không nhầm lẫn một môi trường +không ổn định với hành vi của sản phẩm. ## MVP Discord -Kịch bản đầu tiên nên nhắm tới phản ứng trạng thái Discord trong kênh guild nơi +Kịch bản đầu tiên nên nhắm tới phản ứng trạng thái Discord trong các kênh guild nơi chế độ gửi trả lời nguồn là `message_tool_only`. Vì sao đây là hạt giống Mantis tốt: - Nó hiển thị trong Discord dưới dạng phản ứng trên tin nhắn kích hoạt. - Nó có oracle REST mạnh thông qua trạng thái phản ứng tin nhắn Discord. -- Nó chạy qua OpenClaw Gateway thật, xác thực bot Discord, dispatch tin nhắn, - chế độ gửi trả lời nguồn, trạng thái phản ứng trạng thái và vòng đời lượt - model. -- Nó đủ hẹp để giữ cho phần triển khai đầu tiên trung thực. +- Nó kiểm tra một OpenClaw Gateway thật, xác thực bot Discord, điều phối tin nhắn, + chế độ gửi trả lời nguồn, trạng thái phản ứng trạng thái và vòng đời lượt model. +- Nó đủ hẹp để giữ cho triển khai đầu tiên trung thực. -Hình dạng kịch bản kỳ vọng: +Hình dạng kịch bản dự kiến: ```yaml id: discord-status-reactions-tool-only @@ -279,12 +268,12 @@ evidence: screenshotMessageRow: true ``` -Bằng chứng baseline nên cho thấy phản ứng xác nhận queued nhưng không có chuyển -tiếp vòng đời trong chế độ tool-only. Bằng chứng candidate nên cho thấy các phản -ứng trạng thái vòng đời chạy khi `messages.statusReactions.enabled` được bật rõ -ràng. +Bằng chứng baseline phải cho thấy phản ứng xác nhận đã xếp hàng nhưng không có +chuyển tiếp vòng đời trong chế độ chỉ dùng công cụ. Bằng chứng candidate phải cho thấy các phản ứng +trạng thái vòng đời chạy khi `messages.statusReactions.enabled` được đặt rõ ràng là +true. -Lát cắt thực thi đầu tiên là kịch bản QA live Discord opt-in: +Lát cắt thực thi đầu tiên là kịch bản QA trực tiếp Discord opt-in: ```bash pnpm openclaw qa discord \ @@ -296,34 +285,34 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Lệnh này cấu hình SUT với xử lý guild luôn bật, `visibleReplies: -"message_tool"`, `ackReaction: "👀"`, và các phản ứng trạng thái tường minh. Oracle -thăm dò thông báo kích hoạt Discord thật và mong đợi chuỗi quan sát được -`👀 -> 🤔 -> 👍`. Hiện vật bao gồm `discord-qa-reaction-timelines.json`, +Nó cấu hình SUT với xử lý guild luôn bật, `visibleReplies: +"message_tool"`, `ackReaction: "👀"`, và phản ứng trạng thái rõ ràng. Oracle +poll tin nhắn kích hoạt Discord thật và kỳ vọng chuỗi quan sát được +`👀 -> 🤔 -> 👍`. Artifact bao gồm `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html`, và `discord-status-reactions-tool-only-timeline.png`. -## Các Thành Phần QA Hiện Có +## Các phần QA hiện có -Mantis nên xây dựng dựa trên ngăn xếp QA riêng tư hiện có thay vì bắt đầu từ +Mantis nên xây dựng trên stack QA riêng tư hiện có thay vì bắt đầu từ con số không: -- `pnpm openclaw qa discord` đã chạy một làn Discord trực tiếp với bot điều khiển và +- `pnpm openclaw qa discord` đã chạy một lane Discord trực tiếp với driver và bot SUT. -- Bộ chạy truyền tải trực tiếp đã ghi báo cáo và hiện vật thông báo quan sát được +- Trình chạy transport trực tiếp đã ghi báo cáo và artifact tin nhắn quan sát được trong `.artifacts/qa-e2e/`. -- Các lease thông tin xác thực Convex đã cung cấp quyền truy cập độc quyền vào thông tin xác thực - truyền tải trực tiếp dùng chung. +- Lease thông tin xác thực Convex đã cung cấp quyền truy cập độc quyền vào thông tin xác thực + transport trực tiếp dùng chung. - Dịch vụ điều khiển trình duyệt đã hỗ trợ ảnh chụp màn hình, snapshot, - hồ sơ headless được quản lý, và hồ sơ CDP từ xa. -- QA Lab đã có giao diện trình gỡ lỗi và bus cho kiểm thử theo dạng truyền tải. + hồ sơ được quản lý không giao diện và hồ sơ CDP từ xa. +- QA Lab đã có UI trình gỡ lỗi và bus cho kiểm thử theo hình dạng transport. -Bản triển khai Mantis đầu tiên có thể là một bộ chạy trước/sau mỏng trên các -thành phần này, cộng thêm một lớp bằng chứng trực quan. +Triển khai Mantis đầu tiên có thể là một trình chạy trước/sau mỏng trên các phần +này, cộng thêm một lớp bằng chứng trực quan. -## Mô Hình Bằng Chứng +## Mô hình bằng chứng -Mỗi lần chạy ghi một thư mục hiện vật ổn định: +Mỗi lần chạy ghi một thư mục artifact ổn định: ```text .artifacts/qa-e2e/mantis// @@ -343,79 +332,79 @@ Mỗi lần chạy ghi một thư mục hiện vật ổn định: run.log ``` -`mantis-summary.json` nên là nguồn sự thật máy đọc được. Báo cáo +`mantis-summary.json` phải là nguồn sự thật máy đọc được. Báo cáo Markdown dành cho bình luận PR và đánh giá của con người. -Bản tóm tắt phải bao gồm: +Tóm tắt phải bao gồm: -- các ref và SHA đã kiểm thử -- truyền tải và id kịch bản +- ref và SHA đã kiểm thử +- transport và id kịch bản - nhà cung cấp máy và id máy hoặc id lease -- nguồn thông tin xác thực không kèm giá trị bí mật +- nguồn thông tin xác thực không có giá trị bí mật - kết quả baseline - kết quả candidate -- lỗi có tái hiện trên baseline hay không +- lỗi có được tái hiện trên baseline hay không - candidate có sửa được lỗi hay không -- đường dẫn hiện vật -- các vấn đề thiết lập hoặc dọn dẹp đã được làm sạch +- đường dẫn artifact +- vấn đề thiết lập hoặc dọn dẹp đã được lọc thông tin nhạy cảm Ảnh chụp màn hình là bằng chứng, không phải bí mật. Chúng vẫn cần kỷ luật biên tập: -tên kênh riêng tư, tên người dùng, hoặc nội dung thông báo có thể xuất hiện. Với PR công khai, -ưu tiên liên kết hiện vật GitHub Actions thay vì ảnh nội tuyến cho đến khi câu chuyện biên tập +tên kênh riêng tư, tên người dùng hoặc nội dung tin nhắn có thể xuất hiện. Với PR công khai, +ưu tiên liên kết artifact GitHub Actions hơn ảnh inline cho đến khi câu chuyện biên tập mạnh hơn. -## Trình Duyệt Và VNC +## Trình duyệt và VNC -Làn trình duyệt có hai chế độ: +Lane trình duyệt có hai chế độ: -- **Tự động hóa headless**: mặc định cho CI. Chrome chạy với CDP được bật, và +- **Tự động hóa không giao diện**: mặc định cho CI. Chrome chạy với CDP được bật, và Playwright hoặc điều khiển trình duyệt OpenClaw chụp ảnh màn hình. -- **Cứu hộ VNC**: được bật trên cùng VM khi đăng nhập, MFA, chống tự động hóa Discord, +- **Cứu hộ VNC**: bật trên cùng VM khi đăng nhập, MFA, chống tự động hóa của Discord, hoặc gỡ lỗi trực quan cần con người. -Hồ sơ trình duyệt quan sát Discord nên đủ bền để tránh phải +Hồ sơ trình duyệt quan sát Discord nên đủ bền để tránh đăng nhập cho mỗi lần chạy, nhưng tách biệt khỏi trạng thái trình duyệt cá nhân. Một hồ sơ -thuộc về nhóm máy Mantis, không thuộc về laptop của nhà phát triển. +thuộc về nhóm máy Mantis, không thuộc về laptop của developer. Khi Mantis bị kẹt, nó đăng một thông báo trạng thái Discord với: - id lần chạy - id kịch bản - nhà cung cấp máy -- thư mục hiện vật +- thư mục artifact - hướng dẫn kết nối VNC hoặc noVNC nếu có -- nội dung ngắn về điểm chặn +- văn bản chặn ngắn -Bản triển khai riêng tư đầu tiên có thể đăng các thông báo này vào kênh điều hành -hiện có và chuyển sang một kênh Mantis chuyên dụng sau. +Triển khai riêng tư đầu tiên có thể đăng các thông báo này vào kênh operator +hiện có và chuyển sang kênh Mantis chuyên dụng sau. ## Máy -Mantis nên ưu tiên AWS thông qua Crabbox cho bản triển khai từ xa đầu tiên. -Crabbox cung cấp máy đã làm ấm, theo dõi lease, hydration, nhật ký, kết quả, và -dọn dẹp. Nếu dung lượng AWS quá chậm hoặc không khả dụng, hãy thêm nhà cung cấp Hetzner -phía sau cùng giao diện máy. +Mantis nên ưu tiên AWS thông qua Crabbox cho triển khai từ xa đầu tiên. +Crabbox cung cấp máy đã được làm nóng, theo dõi lease, hydration, log, kết quả và +dọn dẹp. Nếu dung lượng AWS quá chậm hoặc không khả dụng, thêm một nhà cung cấp Hetzner +đằng sau cùng giao diện máy. Yêu cầu VM tối thiểu: -- Linux có cài đặt Chrome hoặc Chromium hỗ trợ desktop +- Linux có Chrome hoặc Chromium có thể chạy desktop - quyền truy cập CDP cho tự động hóa trình duyệt - VNC hoặc noVNC để cứu hộ - Node 22 và pnpm -- checkout OpenClaw và bộ nhớ đệm phụ thuộc -- bộ nhớ đệm trình duyệt Chromium của Playwright khi dùng Playwright -- đủ CPU và bộ nhớ cho một OpenClaw Gateway, một trình duyệt, và một lần chạy mô hình -- quyền truy cập outbound tới Discord, GitHub, nhà cung cấp mô hình, và broker thông tin xác thực +- checkout OpenClaw và cache dependency +- cache trình duyệt Playwright Chromium khi dùng Playwright +- đủ CPU và bộ nhớ cho một OpenClaw Gateway, một trình duyệt và một lần chạy model +- quyền truy cập outbound tới Discord, GitHub, nhà cung cấp model và broker thông tin xác thực -VM không nên giữ bí mật thô dài hạn bên ngoài các kho thông tin xác thực hoặc +VM không nên giữ bí mật thô tồn tại lâu ngoài các kho thông tin xác thực hoặc hồ sơ trình duyệt dự kiến. -## Bí Mật +## Bí mật -Bí mật nằm trong bí mật cấp tổ chức hoặc kho lưu trữ GitHub cho các lần chạy từ xa, và trong -một tệp bí mật do operator kiểm soát cục bộ cho các lần chạy cục bộ. +Bí mật nằm trong secret của tổ chức hoặc repository GitHub cho các lần chạy từ xa, và trong +một tệp bí mật cục bộ do operator kiểm soát cho các lần chạy cục bộ. -Tên bí mật được khuyến nghị: +Tên secret được khuyến nghị: - `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` @@ -423,20 +412,20 @@ Tên bí mật được khuyến nghị: - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` cho tải hiện vật GitHub công khai +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` cho tải artifact GitHub công khai lên - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -Về dài hạn, nhóm thông tin xác thực Convex nên tiếp tục là nguồn thông thường cho thông tin xác thực -truyền tải trực tiếp. Bí mật GitHub khởi động broker và các làn dự phòng. -Workflow phản ứng trạng thái Discord ánh xạ các bí mật Mantis Crabbox trở lại +Về lâu dài, nhóm thông tin xác thực Convex nên vẫn là nguồn bình thường cho thông tin xác thực +transport trực tiếp. GitHub secrets bootstrap broker và các lane fallback. +Workflow Discord status-reactions ánh xạ secret Mantis Crabbox trở lại các biến môi trường `CRABBOX_COORDINATOR` và `CRABBOX_COORDINATOR_TOKEN` -mà Crabbox CLI mong đợi. Tên bí mật GitHub `CRABBOX_*` thuần vẫn -được chấp nhận làm dự phòng tương thích. +mà Crabbox CLI kỳ vọng. Tên GitHub secret `CRABBOX_*` thuần vẫn +được chấp nhận làm fallback tương thích. -Bộ chạy Mantis không bao giờ được in: +Trình chạy Mantis không bao giờ được in: - token bot Discord - khóa API của nhà cung cấp @@ -445,28 +434,28 @@ Bộ chạy Mantis không bao giờ được in: - mật khẩu VNC - payload thông tin xác thực thô -Tải hiện vật công khai cũng nên biên tập siêu dữ liệu mục tiêu Discord như id bot, -guild, kênh, và thông báo. Workflow smoke GitHub bật +Tải artifact công khai lên cũng nên biên tập metadata mục tiêu Discord như bot, +guild, kênh và id tin nhắn. Workflow smoke GitHub bật `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` vì lý do này. -Nếu token vô tình bị dán vào issue, PR, chat, hoặc nhật ký, hãy xoay vòng token đó -sau khi bí mật mới đã được lưu. +Nếu một token vô tình bị dán vào issue, PR, chat hoặc log, hãy xoay vòng nó +sau khi secret mới đã được lưu. -## Hiện Vật GitHub Và Bình Luận PR +## Artifact GitHub và bình luận PR -Các workflow Mantis nên tải toàn bộ gói bằng chứng lên dưới dạng hiện vật Actions -ngắn hạn. Khi workflow được chạy cho báo cáo lỗi hoặc PR sửa lỗi, nó cũng nên +Workflow Mantis nên tải toàn bộ gói bằng chứng lên dưới dạng artifact Actions +ngắn hạn. Khi workflow được chạy cho một báo cáo lỗi hoặc PR sửa lỗi, nó cũng nên xuất bản ảnh chụp màn hình PNG đã biên tập lên nhánh `qa-artifacts` và upsert một -bình luận trên lỗi hoặc PR sửa lỗi đó với ảnh chụp màn hình trước/sau nội tuyến. Không đăng -bằng chứng chính chỉ trên một PR tự động hóa QA chung. Nhật ký thô, thông báo quan sát được, -và bằng chứng cồng kềnh khác ở lại trong hiện vật Actions. +bình luận trên lỗi hoặc PR sửa lỗi đó với ảnh chụp màn hình trước/sau inline. Không đăng +bằng chứng chính chỉ trên một PR tự động hóa QA chung. Log thô, tin nhắn quan sát được +và bằng chứng cồng kềnh khác ở lại trong artifact Actions. -Workflow production nên đăng các bình luận đó bằng GitHub App Mantis, không phải -bằng `github-actions[bot]`. Lưu app id và khóa riêng tư dưới dạng bí mật GitHub Actions -`MANTIS_GITHUB_APP_ID` và `MANTIS_GITHUB_APP_PRIVATE_KEY`. -Workflow dùng một marker ẩn làm khóa upsert, cập nhật -bình luận đó khi token có thể chỉnh sửa nó, và tạo bình luận mới do Mantis sở hữu khi -marker cũ do bot sở hữu không thể chỉnh sửa. +Workflow production nên đăng các bình luận đó bằng Mantis GitHub App, không phải +bằng `github-actions[bot]`. Lưu app id và khóa riêng tư dưới dạng +secret GitHub Actions `MANTIS_GITHUB_APP_ID` và `MANTIS_GITHUB_APP_PRIVATE_KEY`. +Workflow dùng một marker ẩn làm khóa upsert, cập nhật bình luận đó +khi token có thể sửa nó, và tạo một bình luận mới thuộc sở hữu Mantis khi +một marker cũ thuộc sở hữu bot không thể sửa được. Bình luận PR nên ngắn gọn và trực quan: @@ -489,36 +478,36 @@ candidate showed the expected queued -> thinking -> done sequence. ``` Khi lần chạy thất bại vì harness thất bại, bình luận phải nói rõ điều đó thay vì -ngụ ý candidate đã thất bại. +ngụ ý candidate thất bại. -## Ghi Chú Triển Khai Riêng Tư +## Ghi chú triển khai riêng tư -Một bản triển khai riêng tư có thể đã có ứng dụng Discord Mantis. Tái sử dụng -ứng dụng đó thay vì tạo app khác khi nó có quyền bot phù hợp +Một triển khai riêng tư có thể đã có ứng dụng Discord Mantis. Tái sử dụng ứng dụng đó +thay vì tạo app khác khi nó có quyền bot phù hợp và có thể được xoay vòng an toàn. -Thiết lập kênh thông báo operator ban đầu thông qua bí mật hoặc cấu hình -triển khai. Ban đầu nó có thể trỏ tới một kênh maintainer hoặc vận hành hiện có, -rồi chuyển sang kênh Mantis chuyên dụng khi có kênh đó. +Đặt kênh thông báo operator ban đầu thông qua secret hoặc cấu hình triển khai. +Nó có thể trỏ tới một kênh maintainer hoặc vận hành hiện có +trước, rồi chuyển sang kênh Mantis chuyên dụng khi có. -Không đưa guild id, channel id, bot token, cookie trình duyệt, hoặc mật khẩu VNC -vào tài liệu này. Lưu chúng trong bí mật GitHub, broker thông tin xác thực, hoặc -kho bí mật cục bộ của operator. +Không đưa guild id, channel id, bot token, cookie trình duyệt hoặc mật khẩu VNC +vào tài liệu này. Lưu chúng trong GitHub secrets, broker thông tin xác thực hoặc kho bí mật +cục bộ của operator. -## Thêm Một Kịch Bản +## Thêm một kịch bản Một kịch bản Mantis nên khai báo: - id và tiêu đề -- truyền tải +- transport - thông tin xác thực bắt buộc - chính sách ref baseline - chính sách ref candidate - bản vá cấu hình OpenClaw - bước thiết lập - kích thích -- oracle baseline mong đợi -- oracle candidate mong đợi +- oracle baseline dự kiến +- oracle candidate dự kiến - mục tiêu chụp trực quan - ngân sách thời gian chờ - bước dọn dẹp @@ -526,35 +515,35 @@ Một kịch bản Mantis nên khai báo: Kịch bản nên ưu tiên các oracle nhỏ, có kiểu: - trạng thái phản ứng Discord cho lỗi phản ứng -- tham chiếu thông báo Discord cho lỗi luồng -- ts luồng Slack và trạng thái API phản ứng cho lỗi Slack -- id thông báo email và header cho lỗi email -- ảnh chụp màn hình trình duyệt khi UI là đối tượng quan sát đáng tin cậy duy nhất +- tham chiếu tin nhắn Discord cho lỗi threading +- thread ts Slack và trạng thái API phản ứng cho lỗi Slack +- id và header tin nhắn email cho lỗi email +- ảnh chụp màn hình trình duyệt khi UI là quan sát đáng tin cậy duy nhất -Kiểm tra bằng thị giác nên có tính bổ sung. Nếu API nền tảng có thể chứng minh lỗi, hãy dùng -API làm oracle đạt/không đạt và giữ ảnh chụp màn hình để con người tin tưởng hơn. +Kiểm tra vision nên có tính bổ sung. Nếu một API nền tảng có thể chứng minh lỗi, hãy dùng +API làm oracle đạt/không đạt và giữ ảnh chụp màn hình để tăng độ tin cậy cho con người. -## Mở Rộng Nhà Cung Cấp +## Mở rộng nhà cung cấp -Sau Discord, cùng bộ chạy có thể thêm: +Sau Discord, cùng trình chạy có thể thêm: -- Slack: phản ứng, luồng, nhắc đến app, modal, tải tệp lên. -- Email: xác thực Gmail và phân luồng thông báo bằng `gog` khi connector là chưa +- Slack: phản ứng, luồng, lượt nhắc đến ứng dụng, modal, tải tệp lên. +- Email: xác thực Gmail và luồng thư bằng `gog` khi các trình kết nối không đủ. -- WhatsApp: đăng nhập QR, nhận dạng lại, gửi thông báo, phương tiện, phản ứng. -- Telegram: kiểm soát nhắc đến trong nhóm, lệnh, phản ứng khi khả dụng. -- Matrix: phòng được mã hóa, quan hệ luồng hoặc trả lời, tiếp tục sau khởi động lại. +- WhatsApp: đăng nhập bằng QR, nhận dạng lại, gửi tin nhắn, phương tiện, phản ứng. +- Telegram: kiểm soát lượt nhắc trong nhóm, lệnh, phản ứng khi có sẵn. +- Matrix: phòng được mã hóa, quan hệ luồng hoặc trả lời, khôi phục sau khi khởi động lại. -Mỗi truyền tải nên có một kịch bản smoke rẻ và một hoặc nhiều kịch bản theo lớp lỗi. -Các kịch bản trực quan tốn kém nên được giữ ở chế độ opt-in. +Mỗi kênh truyền tải nên có một kịch bản smoke nhẹ và một hoặc nhiều kịch bản +theo lớp lỗi. Các kịch bản trực quan tốn kém nên tiếp tục là tùy chọn tham gia. -## Câu Hỏi Mở +## Câu hỏi mở -- Bot Discord nào nên là driver, và bot nào nên là SUT, khi - bot Mantis hiện có được tái sử dụng? -- Đăng nhập trình duyệt quan sát nên dùng tài khoản Discord của con người, tài khoản kiểm thử, - hay chỉ bằng chứng REST mà bot có thể đọc cho giai đoạn đầu? -- GitHub nên giữ hiện vật Mantis cho PR trong bao lâu? -- Khi nào ClawSweeper nên tự động khuyến nghị Mantis thay vì chờ - lệnh từ maintainer? -- Ảnh chụp màn hình có nên được biên tập hoặc cắt trước khi tải lên cho PR công khai không? +- Bot Discord nào nên là trình điều khiển và bot nào nên là SUT khi bot Mantis + hiện có được dùng lại? +- Phiên đăng nhập trình duyệt của quan sát viên nên dùng tài khoản Discord của người dùng thật, tài khoản kiểm thử, + hay chỉ bằng chứng REST mà bot có thể đọc được trong giai đoạn đầu? +- GitHub nên lưu giữ các artifact Mantis cho PR trong bao lâu? +- Khi nào ClawSweeper nên tự động đề xuất Mantis thay vì chờ lệnh của + maintainer? +- Có nên biên tập hoặc cắt ảnh chụp màn hình trước khi tải lên cho các PR công khai không? diff --git a/docs/vi/gateway/doctor.md b/docs/vi/gateway/doctor.md index e30c288e3..70288026d 100644 --- a/docs/vi/gateway/doctor.md +++ b/docs/vi/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - Thêm hoặc sửa đổi các chuyển đổi của doctor + - Thêm hoặc sửa đổi các di trú của doctor - Giới thiệu các thay đổi cấu hình phá vỡ tương thích sidebarTitle: Doctor -summary: 'Lệnh doctor: kiểm tra tình trạng, chuyển đổi cấu hình và các bước sửa chữa' +summary: 'Lệnh Doctor: kiểm tra tình trạng, chuyển đổi cấu hình và các bước sửa chữa' title: Chẩn đoán x-i18n: - generated_at: "2026-05-05T01:47:06Z" + generated_at: "2026-05-05T08:25:35Z" model: gpt-5.5 provider: openai - source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d + source_hash: 360f9f7a349e4633ff61d526f1eb5b668b595b4f35c5e0fd2a314715a0599c4c source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` là công cụ sửa chữa + di trú cho OpenClaw. Công cụ này sửa cấu hình/trạng thái cũ, kiểm tra tình trạng hoạt động và cung cấp các bước sửa chữa có thể thực hiện. +`openclaw doctor` là công cụ sửa chữa + di trú cho OpenClaw. Công cụ này sửa cấu hình/trạng thái lỗi thời, kiểm tra sức khỏe, và cung cấp các bước sửa chữa có thể thực hiện. ## Bắt đầu nhanh @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Chấp nhận mặc định mà không nhắc hỏi (bao gồm các bước sửa chữa khởi động lại/dịch vụ/sandbox khi áp dụng). + Chấp nhận mặc định mà không nhắc hỏi (bao gồm các bước sửa chữa khởi động lại/dịch vụ/môi trường cách ly khi áp dụng). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Chạy không có lời nhắc và chỉ áp dụng các di trú an toàn (chuẩn hóa cấu hình + di chuyển trạng thái trên đĩa). Bỏ qua các hành động khởi động lại/dịch vụ/sandbox cần xác nhận của con người. Các di trú trạng thái cũ sẽ tự động chạy khi được phát hiện. + Chạy không có lời nhắc và chỉ áp dụng các di trú an toàn (chuẩn hóa cấu hình + di chuyển trạng thái trên đĩa). Bỏ qua các hành động khởi động lại/dịch vụ/môi trường cách ly cần xác nhận của con người. Các di trú trạng thái cũ tự động chạy khi được phát hiện. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Quét các dịch vụ hệ thống để tìm các bản cài đặt Gateway bổ sung (launchd/systemd/schtasks). + Quét dịch vụ hệ thống để tìm các bản cài đặt gateway bổ sung (launchd/systemd/schtasks). @@ -73,12 +73,12 @@ Nếu bạn muốn xem lại các thay đổi trước khi ghi, hãy mở tệp cat ~/.openclaw/openclaw.json ``` -## Chức năng (tóm tắt) +## Chức năng của công cụ (tóm tắt) - - - Cập nhật trước khi chạy tùy chọn cho các bản cài đặt git (chỉ khi tương tác). - - Kiểm tra độ mới của giao thức UI (xây dựng lại Control UI khi schema giao thức mới hơn). + + - Cập nhật tiền kiểm tùy chọn cho các bản cài đặt git (chỉ khi tương tác). + - Kiểm tra độ mới của giao thức giao diện (dựng lại Giao diện điều khiển khi schema giao thức mới hơn). - Kiểm tra sức khỏe + lời nhắc khởi động lại. - Tóm tắt trạng thái Skills (đủ điều kiện/thiếu/bị chặn) và trạng thái plugin. @@ -89,78 +89,79 @@ cat ~/.openclaw/openclaw.json - Kiểm tra di trú trình duyệt cho cấu hình tiện ích Chrome cũ và mức sẵn sàng Chrome MCP. - Cảnh báo ghi đè provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Cảnh báo che khuất OAuth Codex (`models.providers.openai-codex`). - - Kiểm tra điều kiện tiên quyết TLS OAuth cho hồ sơ OAuth OpenAI Codex. - - Cảnh báo danh sách cho phép plugin/công cụ khi `plugins.allow` bị giới hạn nhưng chính sách công cụ vẫn yêu cầu wildcard hoặc công cụ do plugin sở hữu. - - Di trú trạng thái cũ trên đĩa (sessions/thư mục agent/xác thực WhatsApp). + - Kiểm tra điều kiện tiên quyết TLS của OAuth cho hồ sơ OAuth OpenAI Codex. + - Cảnh báo danh sách cho phép plugin/công cụ khi `plugins.allow` có tính hạn chế nhưng chính sách công cụ vẫn yêu cầu ký tự đại diện hoặc công cụ do plugin sở hữu. + - Di trú trạng thái cũ trên đĩa (phiên/thư mục agent/xác thực WhatsApp). - Di trú khóa hợp đồng manifest plugin cũ (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Di trú kho Cron cũ (`jobId`, `schedule.cron`, các trường delivery/payload cấp cao nhất, payload `provider`, các job dự phòng webhook `notify: true` đơn giản). + - Di trú kho cron cũ (`jobId`, `schedule.cron`, các trường delivery/payload cấp cao nhất, payload `provider`, các tác vụ dự phòng webhook đơn giản `notify: true`). - Di trú chính sách runtime agent cũ sang `agents.defaults.agentRuntime` và `agents.list[].agentRuntime`. - - Dọn dẹp cấu hình plugin lỗi thời khi plugin được bật; khi `plugins.enabled=false`, các tham chiếu plugin lỗi thời được xem là cấu hình khoanh vùng bất hoạt và được giữ nguyên. + - Dọn dẹp cấu hình plugin lỗi thời khi plugin được bật; khi `plugins.enabled=false`, tham chiếu plugin lỗi thời được coi là cấu hình bao bọc bất hoạt và được giữ nguyên. - Kiểm tra tệp khóa phiên và dọn dẹp khóa lỗi thời. - - Sửa chữa bản ghi phiên cho các nhánh viết lại prompt bị trùng lặp do các bản dựng 2026.4.24 bị ảnh hưởng tạo ra. - - Phát hiện tombstone phục hồi khởi động lại subagent bị kẹt, có hỗ trợ `--fix` để xóa cờ phục hồi đã hủy lỗi thời để quá trình khởi động không tiếp tục xem tiến trình con là đã bị hủy khởi động lại. - - Kiểm tra tính toàn vẹn trạng thái và quyền (sessions, transcripts, thư mục trạng thái). + - Sửa bản ghi phiên cho các nhánh viết lại prompt bị trùng lặp do các bản dựng 2026.4.24 bị ảnh hưởng tạo ra. + - Phát hiện tombstone khôi phục-khởi động lại subagent bị kẹt, có hỗ trợ `--fix` để xóa các cờ khôi phục bị hủy lỗi thời nhằm tránh startup tiếp tục coi child là bị hủy khi khởi động lại. + - Kiểm tra tính toàn vẹn trạng thái và quyền (phiên, bản ghi, thư mục trạng thái). - Kiểm tra quyền tệp cấu hình (chmod 600) khi chạy cục bộ. - - Sức khỏe xác thực mô hình: kiểm tra hết hạn OAuth, có thể làm mới token sắp hết hạn và báo cáo trạng thái cooldown/bị tắt của auth-profile. + - Sức khỏe xác thực mô hình: kiểm tra hết hạn OAuth, có thể làm mới token sắp hết hạn, và báo cáo trạng thái cooldown/bị vô hiệu hóa của auth-profile. - Phát hiện thư mục workspace bổ sung (`~/openclaw`). - - - Sửa chữa image sandbox khi sandboxing được bật. - - Di trú dịch vụ cũ và phát hiện Gateway bổ sung. - - Di trú trạng thái cũ của kênh Matrix (ở chế độ `--fix` / `--repair`). - - Kiểm tra runtime Gateway (dịch vụ đã cài nhưng không chạy; nhãn launchd được lưu cache). - - Cảnh báo trạng thái kênh (được dò từ Gateway đang chạy). + + - Sửa image môi trường cách ly khi tính năng cách ly được bật. + - Di trú dịch vụ cũ và phát hiện gateway bổ sung. + - Di trú trạng thái cũ của kênh Matrix (trong chế độ `--fix` / `--repair`). + - Kiểm tra runtime Gateway (dịch vụ đã cài đặt nhưng không chạy; nhãn launchd được lưu cache). + - Cảnh báo trạng thái kênh (thăm dò từ gateway đang chạy). + - Kiểm tra mức phản hồi của WhatsApp khi sức khỏe event-loop Gateway suy giảm trong lúc client TUI cục bộ vẫn đang chạy; `--fix` chỉ dừng các client TUI cục bộ đã được xác minh. - Kiểm tra cấu hình supervisor (launchd/systemd/schtasks) với sửa chữa tùy chọn. - - Dọn dẹp môi trường proxy nhúng cho các dịch vụ Gateway đã thu thập giá trị shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` trong lúc cài đặt hoặc cập nhật. + - Dọn dẹp môi trường proxy nhúng cho các dịch vụ gateway đã ghi lại giá trị shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` trong lúc cài đặt hoặc cập nhật. - Kiểm tra thực hành tốt nhất cho runtime Gateway (Node so với Bun, đường dẫn trình quản lý phiên bản). - Chẩn đoán xung đột cổng Gateway (mặc định `18789`). - + - Cảnh báo bảo mật cho chính sách DM mở. - Kiểm tra xác thực Gateway cho chế độ token cục bộ (đề xuất tạo token khi không có nguồn token; không ghi đè cấu hình token SecretRef). - - Phát hiện sự cố ghép đôi thiết bị (yêu cầu ghép đôi lần đầu đang chờ, nâng cấp vai trò/phạm vi đang chờ, sai lệch cache device-token cục bộ lỗi thời và sai lệch xác thực bản ghi đã ghép đôi). + - Phát hiện sự cố ghép đôi thiết bị (yêu cầu ghép đôi lần đầu đang chờ, nâng cấp vai trò/phạm vi đang chờ, sai lệch cache device-token cục bộ lỗi thời, và sai lệch xác thực bản ghi đã ghép đôi). - Kiểm tra systemd linger trên Linux. - - Kiểm tra kích thước tệp bootstrap workspace (cảnh báo bị cắt/gần giới hạn cho các tệp ngữ cảnh). - - Kiểm tra mức sẵn sàng Skills cho agent mặc định; báo cáo các skill được phép nhưng thiếu binary, env, cấu hình hoặc yêu cầu OS, và `--fix` có thể tắt các skill không khả dụng trong `skills.entries`. - - Kiểm tra trạng thái shell completion và tự động cài đặt/nâng cấp. - - Kiểm tra mức sẵn sàng provider embedding tìm kiếm bộ nhớ (mô hình cục bộ, khóa API từ xa hoặc binary QMD). - - Kiểm tra cài đặt từ nguồn (pnpm workspace không khớp, thiếu tài nguyên UI, thiếu binary tsx). + - Kiểm tra kích thước tệp bootstrap workspace (cảnh báo bị cắt/gần giới hạn cho tệp ngữ cảnh). + - Kiểm tra mức sẵn sàng Skills cho agent mặc định; báo cáo các kỹ năng được phép nhưng thiếu binary, env, cấu hình, hoặc yêu cầu OS, và `--fix` có thể vô hiệu hóa kỹ năng không khả dụng trong `skills.entries`. + - Kiểm tra trạng thái completion của shell và tự động cài đặt/nâng cấp. + - Kiểm tra mức sẵn sàng provider embedding tìm kiếm bộ nhớ (mô hình cục bộ, khóa API từ xa, hoặc binary QMD). + - Kiểm tra bản cài đặt từ nguồn (không khớp workspace pnpm, thiếu tài sản giao diện, thiếu binary tsx). - Ghi cấu hình đã cập nhật + metadata wizard. -## Điền bù và đặt lại UI Dreams +## Điền bù và đặt lại giao diện Dreams -Cảnh Dreams của Control UI bao gồm các hành động **Backfill**, **Reset** và **Clear Grounded** cho quy trình grounded dreaming. Các hành động này dùng các phương thức RPC kiểu gateway doctor, nhưng chúng **không** phải là một phần của sửa chữa/di trú CLI `openclaw doctor`. +Cảnh Dreams trong Giao diện điều khiển bao gồm các hành động **Điền bù**, **Đặt lại**, và **Xóa đã bám nền** cho workflow dreaming đã bám nền. Các hành động này dùng các phương thức RPC kiểu doctor của gateway, nhưng chúng **không** phải là một phần của sửa chữa/di trú CLI `openclaw doctor`. -Những việc chúng làm: +Chúng làm gì: -- **Backfill** quét các tệp `memory/YYYY-MM-DD.md` lịch sử trong workspace đang hoạt động, chạy lượt nhật ký REM grounded và ghi các mục điền bù có thể hoàn tác vào `DREAMS.md`. -- **Reset** chỉ xóa các mục nhật ký điền bù đã được đánh dấu đó khỏi `DREAMS.md`. -- **Clear Grounded** chỉ xóa các mục ngắn hạn chỉ-grounded đã được đưa vào hàng chờ đến từ phát lại lịch sử và chưa tích lũy recall trực tiếp hoặc hỗ trợ hằng ngày. +- **Điền bù** quét các tệp lịch sử `memory/YYYY-MM-DD.md` trong workspace đang hoạt động, chạy lượt nhật ký grounded REM, và ghi các mục điền bù có thể đảo ngược vào `DREAMS.md`. +- **Đặt lại** chỉ xóa các mục nhật ký điền bù đã được đánh dấu đó khỏi `DREAMS.md`. +- **Xóa đã bám nền** chỉ xóa các mục ngắn hạn chỉ-bám-nền đã được stage, đến từ phát lại lịch sử và chưa tích lũy recall trực tiếp hoặc hỗ trợ hằng ngày. -Những việc chúng **không** tự làm: +Tự thân chúng **không** làm gì: - chúng không chỉnh sửa `MEMORY.md` - chúng không chạy toàn bộ di trú doctor -- chúng không tự động đưa các ứng viên grounded vào kho promotion ngắn hạn trực tiếp trừ khi bạn chạy rõ ràng đường dẫn CLI đã đưa vào hàng chờ trước +- chúng không tự động stage ứng viên đã bám nền vào kho thăng hạng ngắn hạn trực tiếp trừ khi bạn chạy rõ ràng đường dẫn CLI đã stage trước -Nếu bạn muốn phát lại lịch sử grounded ảnh hưởng đến làn promotion sâu thông thường, hãy dùng luồng CLI thay thế: +Nếu bạn muốn phát lại lịch sử đã bám nền ảnh hưởng đến lane thăng hạng sâu thông thường, hãy dùng luồng CLI thay thế: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Lệnh đó đưa các ứng viên durable grounded vào kho dreaming ngắn hạn trong khi vẫn giữ `DREAMS.md` làm bề mặt xem xét. +Lệnh đó stage các ứng viên bền vững đã bám nền vào kho dreaming ngắn hạn trong khi vẫn giữ `DREAMS.md` làm bề mặt xem xét. ## Hành vi chi tiết và lý do @@ -169,16 +170,16 @@ Lệnh đó đưa các ứng viên durable grounded vào kho dreaming ngắn h Nếu đây là một git checkout và doctor đang chạy tương tác, công cụ sẽ đề xuất cập nhật (fetch/rebase/build) trước khi chạy doctor. - Nếu cấu hình chứa các dạng giá trị cũ (ví dụ `messages.ackReaction` không có ghi đè riêng theo kênh), doctor sẽ chuẩn hóa chúng vào schema hiện tại. + Nếu cấu hình chứa các dạng giá trị cũ (ví dụ `messages.ackReaction` mà không có ghi đè riêng theo kênh), doctor chuẩn hóa chúng vào schema hiện tại. Điều đó bao gồm các trường phẳng Talk cũ. Cấu hình Talk công khai hiện tại là `talk.provider` + `talk.providers.`. Doctor viết lại các dạng `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` cũ vào bản đồ provider. Doctor cũng cảnh báo khi `plugins.allow` không rỗng và chính sách công cụ dùng - các mục công cụ wildcard hoặc do plugin sở hữu. `tools.allow: ["*"]` chỉ khớp các công cụ - từ những plugin thật sự được tải; nó không bỏ qua danh sách cho phép plugin độc quyền. - Doctor ghi `plugins.bundledDiscovery: "compat"` cho các cấu hình danh sách cho phép cũ đã di trú - để giữ nguyên hành vi provider đi kèm hiện có, rồi - trỏ tới thiết lập `"allowlist"` nghiêm ngặt hơn. + ký tự đại diện hoặc mục công cụ do plugin sở hữu. `tools.allow: ["*"]` chỉ khớp các công cụ + từ plugin thực sự tải; nó không bỏ qua danh sách cho phép plugin độc quyền. + Doctor ghi `plugins.bundledDiscovery: "compat"` cho các cấu hình danh sách cho phép cũ đã được di trú + để giữ nguyên hành vi provider đóng gói hiện có, rồi + trỏ đến cài đặt `"allowlist"` nghiêm ngặt hơn. @@ -186,11 +187,11 @@ Lệnh đó đưa các ứng viên durable grounded vào kho dreaming ngắn h Doctor sẽ: - - Giải thích những khóa cũ nào đã được tìm thấy. + - Giải thích các khóa cũ nào đã được tìm thấy. - Hiển thị di trú đã áp dụng. - Ghi lại `~/.openclaw/openclaw.json` với schema đã cập nhật. - Gateway cũng tự động chạy các di trú doctor khi khởi động nếu phát hiện định dạng cấu hình cũ, vì vậy các cấu hình lỗi thời được sửa chữa mà không cần can thiệp thủ công. Di trú kho job Cron được xử lý bởi `openclaw doctor --fix`. + Gateway cũng tự động chạy các di trú doctor khi startup nếu phát hiện định dạng cấu hình cũ, để cấu hình lỗi thời được sửa mà không cần can thiệp thủ công. Di trú kho tác vụ Cron do `openclaw doctor --fix` xử lý. Các di trú hiện tại: @@ -199,7 +200,7 @@ Lệnh đó đưa các ứng viên durable grounded vào kho dreaming ngắn h - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention` - - cấu hình configured-channel thiếu chính sách phản hồi hiển thị → `messages.groupChat.visibleReplies: "message_tool"` + - cấu hình configured-channel thiếu chính sách trả lời hiển thị → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - `routing.bindings` → `bindings` cấp cao nhất - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` @@ -217,290 +218,290 @@ Lệnh đó đưa các ứng viên durable grounded vào kho dreaming ngắn h - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Với các kênh có `accounts` được đặt tên nhưng vẫn còn các giá trị kênh cấp cao nhất cho tài khoản đơn lẻ, hãy chuyển các giá trị theo phạm vi tài khoản đó vào tài khoản được nâng cấp đã chọn cho kênh đó (`accounts.default` cho hầu hết các kênh; Matrix có thể giữ một đích được đặt tên/mặc định hiện có nếu khớp) + - Với các kênh có `accounts` được đặt tên nhưng vẫn còn các giá trị kênh cấp cao nhất cho một tài khoản, hãy chuyển các giá trị theo phạm vi tài khoản đó vào tài khoản được nâng cấp đã chọn cho kênh đó (`accounts.default` cho hầu hết các kênh; Matrix có thể giữ lại một đích được đặt tên/mặc định hiện có khớp) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - xóa `agents.defaults.llm`; dùng `models.providers..timeoutSeconds` cho thời gian chờ nhà cung cấp/mô hình chậm + - xóa `agents.defaults.llm`; dùng `models.providers..timeoutSeconds` cho thời gian chờ provider/model chậm - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - xóa `browser.relayBindHost` (thiết lập relay extension cũ) - - `models.providers.*.api: "openai"` cũ → `"openai-completions"` (Gateway khi khởi động cũng bỏ qua các nhà cung cấp có `api` được đặt thành giá trị enum tương lai hoặc không xác định thay vì thất bại đóng) + - xóa `browser.relayBindHost` (cài đặt chuyển tiếp extension cũ) + - `models.providers.*.api: "openai"` cũ → `"openai-completions"` (khi khởi động, Gateway cũng bỏ qua các provider có `api` được đặt thành giá trị enum tương lai hoặc không xác định thay vì đóng thất bại) - Cảnh báo của doctor cũng bao gồm hướng dẫn mặc định tài khoản cho các kênh nhiều tài khoản: + Cảnh báo của doctor cũng bao gồm hướng dẫn tài khoản mặc định cho các kênh nhiều tài khoản: - Nếu có từ hai mục `channels..accounts` trở lên được cấu hình mà không có `channels..defaultAccount` hoặc `accounts.default`, doctor cảnh báo rằng định tuyến dự phòng có thể chọn một tài khoản không mong muốn. - - Nếu `channels..defaultAccount` được đặt thành một ID tài khoản không xác định, doctor cảnh báo và liệt kê các ID tài khoản đã cấu hình. + - Nếu `channels..defaultAccount` được đặt thành ID tài khoản không xác định, doctor cảnh báo và liệt kê các ID tài khoản đã cấu hình. - - Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, cấu hình đó sẽ ghi đè danh mục OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể buộc mô hình dùng sai API hoặc đưa chi phí về 0. Doctor cảnh báo để bạn có thể xóa ghi đè và khôi phục định tuyến API + chi phí theo từng mô hình. + + Nếu bạn đã thêm thủ công `models.providers.opencode`, `opencode-zen`, hoặc `opencode-go`, nó sẽ ghi đè danh mục OpenCode tích hợp từ `@mariozechner/pi-ai`. Điều đó có thể buộc model dùng sai API hoặc đặt chi phí về 0. Doctor cảnh báo để bạn có thể xóa phần ghi đè và khôi phục định tuyến API + chi phí theo từng model. - - Nếu cấu hình trình duyệt của bạn vẫn trỏ tới đường dẫn extension Chrome đã bị xóa, doctor chuẩn hóa nó sang mô hình gắn Chrome MCP cục bộ trên host hiện tại: + + Nếu cấu hình trình duyệt của bạn vẫn trỏ đến đường dẫn Chrome extension đã bị xóa, doctor chuẩn hóa nó sang mô hình gắn Chrome MCP cục bộ trên host hiện tại: - `browser.profiles.*.driver: "extension"` trở thành `"existing-session"` - `browser.relayBindHost` bị xóa - Doctor cũng kiểm tra đường dẫn Chrome MCP cục bộ trên host khi bạn dùng `defaultProfile: "user"` hoặc một hồ sơ `existing-session` đã cấu hình: + Doctor cũng kiểm tra đường dẫn Chrome MCP cục bộ trên host khi bạn dùng `defaultProfile: "user"` hoặc một profile `existing-session` đã cấu hình: - - kiểm tra Google Chrome có được cài trên cùng host cho các hồ sơ tự động kết nối mặc định hay không - - kiểm tra phiên bản Chrome được phát hiện và cảnh báo khi phiên bản thấp hơn Chrome 144 - - nhắc bạn bật gỡ lỗi từ xa trong trang inspect của trình duyệt (ví dụ `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, hoặc `edge://inspect/#remote-debugging`) + - kiểm tra Google Chrome có được cài đặt trên cùng host cho các profile tự động kết nối mặc định hay không + - kiểm tra phiên bản Chrome phát hiện được và cảnh báo khi phiên bản đó thấp hơn Chrome 144 + - nhắc bạn bật gỡ lỗi từ xa trong trang kiểm tra của trình duyệt (ví dụ `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, hoặc `edge://inspect/#remote-debugging`) - Doctor không thể bật thiết lập phía Chrome thay bạn. Chrome MCP cục bộ trên host vẫn yêu cầu: + Doctor không thể bật cài đặt phía Chrome thay bạn. Chrome MCP cục bộ trên host vẫn yêu cầu: - - một trình duyệt dựa trên Chromium 144+ trên host gateway/node + - trình duyệt dựa trên Chromium 144+ trên host gateway/node - trình duyệt đang chạy cục bộ - - gỡ lỗi từ xa được bật trong trình duyệt đó - - phê duyệt lời nhắc đồng ý gắn lần đầu trong trình duyệt + - đã bật gỡ lỗi từ xa trong trình duyệt đó + - chấp thuận lời nhắc đồng ý gắn lần đầu trong trình duyệt - Trạng thái sẵn sàng ở đây chỉ liên quan đến các điều kiện tiên quyết để gắn cục bộ. Existing-session giữ các giới hạn tuyến Chrome MCP hiện tại; các tuyến nâng cao như `responsebody`, xuất PDF, chặn tải xuống, và hành động theo lô vẫn yêu cầu trình duyệt được quản lý hoặc hồ sơ CDP thô. + Mức sẵn sàng ở đây chỉ nói về các điều kiện tiên quyết để gắn cục bộ. Existing-session giữ nguyên các giới hạn tuyến Chrome MCP hiện tại; các tuyến nâng cao như `responsebody`, xuất PDF, chặn tải xuống, và hành động theo lô vẫn yêu cầu trình duyệt được quản lý hoặc profile CDP thô. - Kiểm tra này **không** áp dụng cho Docker, sandbox, remote-browser, hoặc các luồng headless khác. Những luồng đó tiếp tục dùng CDP thô. + Kiểm tra này **không** áp dụng cho Docker, sandbox, remote-browser, hoặc các luồng headless khác. Các luồng đó tiếp tục dùng CDP thô. - Khi một hồ sơ OpenAI Codex OAuth được cấu hình, doctor thăm dò điểm cuối ủy quyền OpenAI để xác minh rằng ngăn xếp TLS Node/OpenSSL cục bộ có thể xác thực chuỗi chứng chỉ. Nếu thăm dò thất bại với lỗi chứng chỉ (ví dụ `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, chứng chỉ hết hạn, hoặc chứng chỉ tự ký), doctor in hướng dẫn khắc phục theo từng nền tảng. Trên macOS với Node từ Homebrew, cách khắc phục thường là `brew postinstall ca-certificates`. Với `--deep`, thăm dò chạy ngay cả khi gateway khỏe mạnh. + Khi một profile OpenAI Codex OAuth được cấu hình, doctor thăm dò endpoint ủy quyền OpenAI để xác minh rằng ngăn xếp TLS Node/OpenSSL cục bộ có thể xác thực chuỗi chứng chỉ. Nếu thăm dò thất bại với lỗi chứng chỉ (ví dụ `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, chứng chỉ hết hạn, hoặc chứng chỉ tự ký), doctor in hướng dẫn sửa lỗi theo từng nền tảng. Trên macOS với Node từ Homebrew, cách sửa thường là `brew postinstall ca-certificates`. Với `--deep`, thăm dò chạy ngay cả khi gateway khỏe mạnh. - - Nếu trước đây bạn đã thêm thiết lập truyền tải OpenAI cũ dưới `models.providers.openai-codex`, chúng có thể che khuất đường dẫn nhà cung cấp Codex OAuth tích hợp mà các bản phát hành mới hơn dùng tự động. Doctor cảnh báo khi thấy các thiết lập truyền tải cũ đó đi cùng Codex OAuth để bạn có thể xóa hoặc viết lại ghi đè truyền tải lỗi thời và lấy lại hành vi định tuyến/dự phòng tích hợp. Proxy tùy chỉnh và ghi đè chỉ header vẫn được hỗ trợ và không kích hoạt cảnh báo này. + + Nếu trước đây bạn đã thêm các cài đặt truyền tải OpenAI cũ dưới `models.providers.openai-codex`, chúng có thể che khuất đường dẫn provider Codex OAuth tích hợp mà các bản phát hành mới hơn tự động dùng. Doctor cảnh báo khi thấy các cài đặt truyền tải cũ đó cùng với Codex OAuth để bạn có thể xóa hoặc viết lại phần ghi đè truyền tải lỗi thời và khôi phục hành vi định tuyến/dự phòng tích hợp. Proxy tùy chỉnh và ghi đè chỉ header vẫn được hỗ trợ và không kích hoạt cảnh báo này. - Khi Plugin Codex đi kèm được bật, doctor cũng kiểm tra liệu các tham chiếu mô hình chính `openai-codex/*` vẫn phân giải qua trình chạy PI mặc định hay không. Tổ hợp đó hợp lệ khi bạn muốn xác thực Codex OAuth/gói đăng ký thông qua PI, nhưng dễ bị nhầm với harness app-server Codex gốc. Doctor cảnh báo và trỏ tới dạng app-server rõ ràng: `openai/*` cộng với `agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex`. + Khi Plugin Codex đi kèm được bật, doctor cũng kiểm tra xem các tham chiếu model chính `openai-codex/*` có còn phân giải qua PI runner mặc định hay không. Tổ hợp đó hợp lệ khi bạn muốn auth Codex OAuth/subscription thông qua PI, nhưng dễ bị nhầm với harness app-server Codex gốc. Doctor cảnh báo và trỏ đến dạng app-server rõ ràng: `openai/*` cộng với `agentRuntime.id: "codex"` hoặc `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor không tự động sửa điều này vì cả hai tuyến đều hợp lệ: + Doctor không tự động sửa vì cả hai tuyến đều hợp lệ: - - `openai-codex/*` + PI nghĩa là "dùng xác thực Codex OAuth/gói đăng ký thông qua trình chạy OpenClaw thông thường." + - `openai-codex/*` + PI nghĩa là "dùng auth Codex OAuth/subscription thông qua runner OpenClaw bình thường." - `openai/*` + `agentRuntime.id: "codex"` nghĩa là "chạy lượt nhúng thông qua app-server Codex gốc." - `/codex ...` nghĩa là "điều khiển hoặc liên kết một cuộc trò chuyện Codex gốc từ chat." - - `/acp ...` hoặc `runtime: "acp"` nghĩa là "dùng bộ điều hợp ACP/acpx bên ngoài." + - `/acp ...` hoặc `runtime: "acp"` nghĩa là "dùng adapter ACP/acpx bên ngoài." - Nếu cảnh báo xuất hiện, hãy chọn tuyến bạn dự định dùng và sửa cấu hình thủ công. Giữ nguyên cảnh báo khi PI Codex OAuth là có chủ đích. + Nếu cảnh báo xuất hiện, hãy chọn tuyến bạn dự định và sửa cấu hình thủ công. Giữ nguyên cảnh báo khi PI Codex OAuth là chủ ý. - Doctor cũng quét kho phiên hoạt động để tìm trạng thái tuyến tự tạo đã lỗi thời sau khi bạn chuyển mô hình hoặc runtime mặc định/dự phòng đã cấu hình khỏi một tuyến do Plugin sở hữu, chẳng hạn như Codex. + Doctor cũng quét kho phiên đang hoạt động để tìm trạng thái tuyến tự tạo lỗi thời sau khi bạn chuyển model hoặc runtime mặc định/dự phòng đã cấu hình khỏi một tuyến do Plugin sở hữu, chẳng hạn Codex. - `openclaw doctor --fix` có thể xóa trạng thái lỗi thời tự tạo như ghim mô hình `modelOverrideSource: "auto"`, metadata mô hình runtime, ID harness đã ghim, liên kết phiên CLI, và ghi đè hồ sơ xác thực tự động khi tuyến sở hữu chúng không còn được cấu hình. Các lựa chọn mô hình phiên rõ ràng của người dùng hoặc phiên cũ được báo cáo để xem xét thủ công và giữ nguyên; chuyển chúng bằng `/model ...`, `/new`, hoặc đặt lại phiên khi tuyến đó không còn là ý định sử dụng. + `openclaw doctor --fix` có thể xóa trạng thái lỗi thời tự tạo như ghim model `modelOverrideSource: "auto"`, siêu dữ liệu model runtime, ID harness đã ghim, liên kết phiên CLI, và ghi đè auth-profile tự động khi tuyến sở hữu chúng không còn được cấu hình. Lựa chọn model phiên rõ ràng của người dùng hoặc cũ được báo cáo để xem xét thủ công và được giữ nguyên; chuyển chúng bằng `/model ...`, `/new`, hoặc đặt lại phiên khi tuyến đó không còn được dự định dùng. - - Doctor có thể di chuyển các bố cục cũ trên ổ đĩa vào cấu trúc hiện tại: + + Doctor có thể di chuyển các bố cục cũ trên đĩa vào cấu trúc hiện tại: - Kho phiên + bản ghi: - từ `~/.openclaw/sessions/` sang `~/.openclaw/agents//sessions/` - Thư mục agent: - từ `~/.openclaw/agent/` sang `~/.openclaw/agents//agent/` - - Trạng thái xác thực WhatsApp (Baileys): - - từ `~/.openclaw/credentials/*.json` cũ (ngoại trừ `oauth.json`) + - Trạng thái auth WhatsApp (Baileys): + - từ `~/.openclaw/credentials/*.json` cũ (trừ `oauth.json`) - sang `~/.openclaw/credentials/whatsapp//...` (ID tài khoản mặc định: `default`) - Các lần di chuyển này là nỗ lực tốt nhất và có tính lặp lại an toàn; doctor sẽ phát cảnh báo khi để lại bất kỳ thư mục cũ nào làm bản sao lưu. Gateway/CLI cũng tự động di chuyển phiên cũ + thư mục agent khi khởi động để lịch sử/xác thực/mô hình nằm trong đường dẫn theo từng agent mà không cần chạy doctor thủ công. Chuẩn hóa nhà cung cấp talk/bản đồ nhà cung cấp hiện so sánh bằng bình đẳng cấu trúc, nên các khác biệt chỉ do thứ tự khóa không còn kích hoạt lặp lại các thay đổi `doctor --fix` không có tác dụng. + Các lần di chuyển này là nỗ lực tối đa và có tính lặp lại an toàn; doctor sẽ phát cảnh báo khi để lại bất kỳ thư mục cũ nào làm bản sao lưu. Gateway/CLI cũng tự động di chuyển kho phiên cũ + thư mục agent khi khởi động để lịch sử/auth/model nằm trong đường dẫn theo từng agent mà không cần chạy doctor thủ công. Auth WhatsApp được chủ ý chỉ di chuyển qua `openclaw doctor`. Chuẩn hóa provider/provider-map cho Talk hiện so sánh bằng bình đẳng cấu trúc, nên các khác biệt chỉ do thứ tự khóa không còn kích hoạt các thay đổi `doctor --fix` lặp lại nhưng không làm gì. - Doctor quét tất cả manifest Plugin đã cài đặt để tìm các khóa capability cấp cao nhất không còn dùng (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Khi tìm thấy, nó đề nghị chuyển chúng vào đối tượng `contracts` và viết lại tệp manifest tại chỗ. Quá trình di chuyển này có tính lặp lại an toàn; nếu khóa `contracts` đã có cùng các giá trị, khóa cũ sẽ bị xóa mà không nhân đôi dữ liệu. + Doctor quét tất cả manifest Plugin đã cài đặt để tìm các khóa capability cấp cao nhất đã lỗi thời (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Khi tìm thấy, nó đề nghị chuyển chúng vào đối tượng `contracts` và ghi lại trực tiếp tệp manifest. Lần di chuyển này có tính lặp lại an toàn; nếu khóa `contracts` đã có cùng giá trị, khóa cũ sẽ bị xóa mà không nhân đôi dữ liệu. - Doctor cũng kiểm tra kho công việc cron (`~/.openclaw/cron/jobs.json` theo mặc định, hoặc `cron.store` khi bị ghi đè) để tìm các dạng công việc cũ mà bộ lập lịch vẫn chấp nhận để tương thích. + Doctor cũng kiểm tra kho job Cron (`~/.openclaw/cron/jobs.json` theo mặc định, hoặc `cron.store` khi được ghi đè) để tìm các dạng job cũ mà bộ lập lịch vẫn chấp nhận để tương thích. - Các dọn dẹp cron hiện tại bao gồm: + Các dọn dẹp Cron hiện tại bao gồm: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - các trường payload cấp cao nhất (`message`, `model`, `thinking`, ...) → `payload` - các trường delivery cấp cao nhất (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - bí danh delivery `provider` trong payload → `delivery.channel` rõ ràng - - các công việc webhook dự phòng `notify: true` cũ đơn giản → `delivery.mode="webhook"` rõ ràng với `delivery.to=cron.webhook` + - alias delivery `provider` trong payload → `delivery.channel` rõ ràng + - các job webhook dự phòng `notify: true` cũ đơn giản → `delivery.mode="webhook"` rõ ràng với `delivery.to=cron.webhook` - Doctor chỉ tự động di chuyển các công việc `notify: true` khi có thể làm vậy mà không thay đổi hành vi. Nếu một công việc kết hợp dự phòng notify cũ với một chế độ delivery không phải webhook hiện có, doctor cảnh báo và để công việc đó lại để xem xét thủ công. + Doctor chỉ tự động di chuyển các job `notify: true` khi có thể làm vậy mà không thay đổi hành vi. Nếu một job kết hợp dự phòng notify cũ với một chế độ delivery không phải webhook hiện có, doctor cảnh báo và để job đó lại để xem xét thủ công. - Trên Linux, doctor cũng cảnh báo khi crontab của người dùng vẫn gọi `~/.openclaw/bin/ensure-whatsapp.sh` cũ. Tập lệnh cục bộ trên máy chủ đó không được OpenClaw hiện tại duy trì và có thể ghi các thông báo `Gateway inactive` sai vào `~/.openclaw/logs/whatsapp-health.log` khi cron không thể truy cập systemd user bus. Xóa mục crontab đã lỗi thời bằng `crontab -e`; dùng `openclaw channels status --probe`, `openclaw doctor`, và `openclaw gateway status` cho các lần kiểm tra tình trạng hiện tại. + Trên Linux, doctor cũng cảnh báo khi crontab của người dùng vẫn gọi `~/.openclaw/bin/ensure-whatsapp.sh` cũ. Tập lệnh cục bộ trên máy chủ đó không còn được OpenClaw hiện tại bảo trì và có thể ghi các thông báo `Gateway inactive` sai vào `~/.openclaw/logs/whatsapp-health.log` khi cron không thể truy cập bus người dùng systemd. Xóa mục crontab lỗi thời bằng `crontab -e`; dùng `openclaw channels status --probe`, `openclaw doctor`, và `openclaw gateway status` cho các kiểm tra sức khỏe hiện tại. - Doctor quét mọi thư mục phiên tác nhân để tìm các tệp khóa ghi lỗi thời — các tệp còn sót lại khi một phiên thoát bất thường. Với mỗi tệp khóa tìm thấy, nó báo cáo: đường dẫn, PID, liệu PID còn đang chạy hay không, tuổi của khóa, và liệu khóa có được xem là lỗi thời hay không (PID đã chết hoặc cũ hơn 30 phút). Ở chế độ `--fix` / `--repair`, nó tự động xóa các tệp khóa lỗi thời; nếu không, nó in một ghi chú và hướng dẫn bạn chạy lại với `--fix`. + Doctor quét mọi thư mục phiên tác tử để tìm các tệp khóa ghi lỗi thời — các tệp còn sót lại khi một phiên thoát bất thường. Với mỗi tệp khóa tìm thấy, nó báo cáo: đường dẫn, PID, PID còn sống hay không, tuổi của khóa, và khóa có được xem là lỗi thời hay không (PID đã chết hoặc cũ hơn 30 phút). Ở chế độ `--fix` / `--repair`, nó tự động xóa các tệp khóa lỗi thời; nếu không, nó in ghi chú và hướng dẫn bạn chạy lại với `--fix`. - Doctor quét các tệp JSONL phiên tác nhân để tìm cấu trúc nhánh bị nhân đôi do lỗi viết lại bản ghi prompt ngày 2026.4.24 tạo ra: một lượt người dùng bị bỏ rơi có ngữ cảnh runtime nội bộ của OpenClaw cùng với một nhánh anh em đang hoạt động chứa cùng prompt người dùng hiển thị. Ở chế độ `--fix` / `--repair`, doctor sao lưu từng tệp bị ảnh hưởng bên cạnh tệp gốc và viết lại bản ghi về nhánh đang hoạt động để lịch sử gateway và các bộ đọc bộ nhớ không còn thấy các lượt trùng lặp. + Doctor quét các tệp JSONL phiên tác tử để tìm hình dạng nhánh bị lặp do lỗi viết lại bản ghi prompt ngày 2026.4.24 tạo ra: một lượt người dùng bị bỏ rơi với ngữ cảnh runtime nội bộ của OpenClaw cùng một nhánh anh em đang hoạt động chứa cùng prompt người dùng hiển thị. Ở chế độ `--fix` / `--repair`, doctor sao lưu từng tệp bị ảnh hưởng bên cạnh tệp gốc và viết lại bản ghi sang nhánh đang hoạt động để lịch sử Gateway và trình đọc bộ nhớ không còn thấy các lượt trùng lặp. - - Thư mục trạng thái là trung khu vận hành. Nếu nó biến mất, bạn sẽ mất phiên, thông tin xác thực, nhật ký và cấu hình (trừ khi bạn có bản sao lưu ở nơi khác). + + Thư mục trạng thái là thân não vận hành. Nếu nó biến mất, bạn sẽ mất phiên, thông tin xác thực, nhật ký, và cấu hình (trừ khi bạn có bản sao lưu ở nơi khác). Doctor kiểm tra: - **Thiếu thư mục trạng thái**: cảnh báo về mất trạng thái nghiêm trọng, nhắc tạo lại thư mục, và nhắc bạn rằng nó không thể khôi phục dữ liệu bị thiếu. - - **Quyền thư mục trạng thái**: xác minh khả năng ghi; đề nghị sửa quyền (và phát ra gợi ý `chown` khi phát hiện chủ sở hữu/nhóm không khớp). - - **Thư mục trạng thái được đồng bộ đám mây trên macOS**: cảnh báo khi trạng thái phân giải dưới iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) hoặc `~/Library/CloudStorage/...` vì các đường dẫn được đồng bộ có thể gây I/O chậm hơn và tranh chấp khóa/đồng bộ. - - **Thư mục trạng thái SD hoặc eMMC trên Linux**: cảnh báo khi trạng thái phân giải tới nguồn gắn kết `mmcblk*`, vì I/O ngẫu nhiên dựa trên SD hoặc eMMC có thể chậm hơn và hao mòn nhanh hơn khi ghi phiên và thông tin xác thực. - - **Thiếu thư mục phiên**: `sessions/` và thư mục lưu phiên là bắt buộc để lưu lịch sử và tránh sự cố `ENOENT`. - - **Bản ghi không khớp**: cảnh báo khi các mục phiên gần đây thiếu tệp bản ghi. - - **Phiên chính "JSONL 1 dòng"**: đánh dấu khi bản ghi chính chỉ có một dòng (lịch sử không được tích lũy). - - **Nhiều thư mục trạng thái**: cảnh báo khi nhiều thư mục `~/.openclaw` tồn tại trên các thư mục home hoặc khi `OPENCLAW_STATE_DIR` trỏ đến nơi khác (lịch sử có thể bị chia tách giữa các bản cài đặt). - - **Nhắc nhở chế độ từ xa**: nếu `gateway.mode=remote`, doctor nhắc bạn chạy nó trên máy chủ từ xa (trạng thái nằm ở đó). - - **Quyền tệp cấu hình**: cảnh báo nếu `~/.openclaw/openclaw.json` có thể đọc bởi nhóm/mọi người và đề nghị siết chặt thành `600`. + - **Quyền thư mục trạng thái**: xác minh khả năng ghi; đề xuất sửa quyền (và phát gợi ý `chown` khi phát hiện chủ sở hữu/nhóm không khớp). + - **Thư mục trạng thái được đồng bộ đám mây trên macOS**: cảnh báo khi trạng thái phân giải dưới iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) hoặc `~/Library/CloudStorage/...` vì các đường dẫn dựa trên đồng bộ có thể làm I/O chậm hơn và gây tranh chấp khóa/đồng bộ. + - **Thư mục trạng thái trên SD hoặc eMMC Linux**: cảnh báo khi trạng thái phân giải đến nguồn gắn kết `mmcblk*`, vì I/O ngẫu nhiên dựa trên SD hoặc eMMC có thể chậm hơn và hao mòn nhanh hơn khi ghi phiên và thông tin xác thực. + - **Thiếu thư mục phiên**: cần có `sessions/` và thư mục kho phiên để lưu lịch sử và tránh sự cố `ENOENT`. + - **Bản ghi không khớp**: cảnh báo khi các mục phiên gần đây bị thiếu tệp bản ghi. + - **Phiên chính "JSONL 1 dòng"**: gắn cờ khi bản ghi chính chỉ có một dòng (lịch sử không tích lũy). + - **Nhiều thư mục trạng thái**: cảnh báo khi nhiều thư mục `~/.openclaw` tồn tại trên các thư mục home hoặc khi `OPENCLAW_STATE_DIR` trỏ đến nơi khác (lịch sử có thể bị tách giữa các bản cài đặt). + - **Nhắc chế độ từ xa**: nếu `gateway.mode=remote`, doctor nhắc bạn chạy nó trên máy chủ từ xa (trạng thái nằm ở đó). + - **Quyền tệp cấu hình**: cảnh báo nếu `~/.openclaw/openclaw.json` có thể đọc bởi nhóm/toàn thế giới và đề xuất siết chặt thành `600`. - - Doctor kiểm tra các hồ sơ OAuth trong kho xác thực, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể làm mới chúng khi an toàn. Nếu hồ sơ OAuth/token Anthropic đã lỗi thời, nó gợi ý khóa API Anthropic hoặc đường dẫn setup-token Anthropic. Lời nhắc làm mới chỉ xuất hiện khi chạy tương tác (TTY); `--non-interactive` bỏ qua các lần thử làm mới. + + Doctor kiểm tra các hồ sơ OAuth trong kho xác thực, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể làm mới chúng khi an toàn. Nếu hồ sơ OAuth/token Anthropic đã cũ, nó đề xuất khóa API Anthropic hoặc đường dẫn setup-token Anthropic. Lời nhắc làm mới chỉ xuất hiện khi chạy tương tác (TTY); `--non-interactive` bỏ qua các lần thử làm mới. - Khi làm mới OAuth thất bại vĩnh viễn (ví dụ `refresh_token_reused`, `invalid_grant`, hoặc nhà cung cấp yêu cầu bạn đăng nhập lại), doctor báo rằng cần xác thực lại và in đúng lệnh `openclaw models auth login --provider ...` cần chạy. + Khi làm mới OAuth thất bại vĩnh viễn (ví dụ `refresh_token_reused`, `invalid_grant`, hoặc nhà cung cấp yêu cầu bạn đăng nhập lại), doctor báo rằng cần xác thực lại và in chính xác lệnh `openclaw models auth login --provider ...` cần chạy. Doctor cũng báo cáo các hồ sơ xác thực tạm thời không dùng được do: - thời gian chờ ngắn (giới hạn tốc độ/hết thời gian chờ/lỗi xác thực) - - vô hiệu hóa dài hơn (lỗi thanh toán/tín dụng) + - vô hiệu hóa lâu hơn (lỗi thanh toán/tín dụng) - Nếu `hooks.gmail.model` được đặt, doctor xác thực tham chiếu mô hình với catalog và danh sách cho phép, đồng thời cảnh báo khi nó không phân giải được hoặc không được cho phép. + Nếu `hooks.gmail.model` được đặt, doctor xác thực tham chiếu mô hình theo danh mục và danh sách cho phép, đồng thời cảnh báo khi nó không phân giải được hoặc không được phép. - Khi sandboxing được bật, doctor kiểm tra Docker images và đề nghị xây dựng hoặc chuyển sang tên cũ nếu ảnh hiện tại bị thiếu. + Khi bật sandbox, doctor kiểm tra ảnh Docker và đề xuất xây dựng hoặc chuyển sang tên cũ nếu thiếu ảnh hiện tại. - Doctor xóa trạng thái staging dependency plugin cũ do OpenClaw tạo ở chế độ `openclaw doctor --fix` / `openclaw doctor --repair`. Việc này bao gồm các gốc dependency được tạo đã lỗi thời, thư mục install-stage cũ, mảnh vụn cục bộ trong package từ mã sửa dependency bundled-plugin trước đây, và các bản sao npm được quản lý của các plugin `@openclaw/*` bundled bị mồ côi hoặc được khôi phục có thể che khuất manifest bundled hiện tại. + Doctor xóa trạng thái staging phụ thuộc Plugin cũ do OpenClaw tạo ra trong chế độ `openclaw doctor --fix` / `openclaw doctor --repair`. Điều này bao gồm các gốc phụ thuộc được tạo đã cũ, thư mục giai đoạn cài đặt cũ, mảnh vụn cục bộ theo gói từ mã sửa phụ thuộc Plugin đóng gói trước đây, và các bản sao npm được quản lý bị mồ côi hoặc khôi phục của các Plugin `@openclaw/*` đóng gói có thể che khuất manifest đóng gói hiện tại. - Doctor cũng có thể cài đặt lại các plugin có thể tải xuống bị thiếu khi cấu hình tham chiếu đến chúng nhưng registry plugin cục bộ không tìm thấy. Ví dụ gồm `plugins.entries` thực tế, thiết lập channel/provider/search đã cấu hình, và runtime tác nhân đã cấu hình. Trong quá trình cập nhật package, doctor tránh chạy sửa plugin bằng package-manager khi package lõi đang được thay thế; chạy lại `openclaw doctor --fix` sau khi cập nhật nếu một plugin đã cấu hình vẫn cần khôi phục. Khởi động Gateway và tải lại cấu hình không chạy package managers; cài đặt plugin vẫn là công việc doctor/install/update rõ ràng. + Doctor cũng có thể cài đặt lại các Plugin có thể tải xuống bị thiếu khi cấu hình tham chiếu đến chúng nhưng sổ đăng ký Plugin cục bộ không tìm thấy. Ví dụ bao gồm `plugins.entries` cụ thể, thiết lập kênh/nhà cung cấp/tìm kiếm đã cấu hình, và runtime tác tử đã cấu hình. Trong quá trình cập nhật gói, doctor tránh chạy sửa Plugin bằng trình quản lý gói trong khi gói lõi đang được thay thế; chạy lại `openclaw doctor --fix` sau khi cập nhật nếu một Plugin đã cấu hình vẫn cần khôi phục. Khởi động Gateway và tải lại cấu hình không chạy trình quản lý gói; cài đặt Plugin vẫn là công việc doctor/install/update rõ ràng. - - Doctor phát hiện các dịch vụ gateway cũ (launchd/systemd/schtasks) và đề nghị xóa chúng rồi cài đặt dịch vụ OpenClaw bằng cổng gateway hiện tại. Nó cũng có thể quét các dịch vụ giống gateway bổ sung và in gợi ý dọn dẹp. Các dịch vụ gateway OpenClaw được đặt tên theo hồ sơ được xem là hạng nhất và không bị đánh dấu là "bổ sung." + + Doctor phát hiện các dịch vụ gateway cũ (launchd/systemd/schtasks) và đề xuất xóa chúng rồi cài đặt dịch vụ OpenClaw bằng cổng gateway hiện tại. Nó cũng có thể quét các dịch vụ giống gateway bổ sung và in gợi ý dọn dẹp. Các dịch vụ gateway OpenClaw được đặt tên theo hồ sơ được xem là hạng nhất và không bị gắn cờ là "bổ sung." - Trên Linux, nếu dịch vụ gateway cấp người dùng bị thiếu nhưng có dịch vụ gateway OpenClaw cấp hệ thống, doctor không tự động cài đặt dịch vụ cấp người dùng thứ hai. Kiểm tra bằng `openclaw gateway status --deep` hoặc `openclaw doctor --deep`, sau đó xóa bản trùng lặp hoặc đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một trình giám sát hệ thống sở hữu vòng đời gateway. + Trên Linux, nếu thiếu dịch vụ gateway cấp người dùng nhưng tồn tại dịch vụ gateway OpenClaw cấp hệ thống, doctor không tự động cài đặt dịch vụ cấp người dùng thứ hai. Kiểm tra bằng `openclaw gateway status --deep` hoặc `openclaw doctor --deep`, rồi xóa bản trùng lặp hoặc đặt `OPENCLAW_SERVICE_REPAIR_POLICY=external` khi một trình giám sát hệ thống sở hữu vòng đời gateway. - - Khi một tài khoản channel Matrix có quá trình di chuyển trạng thái cũ đang chờ hoặc có thể hành động, doctor (ở chế độ `--fix` / `--repair`) tạo snapshot trước di chuyển rồi chạy các bước di chuyển best-effort: di chuyển trạng thái Matrix cũ và chuẩn bị trạng thái mã hóa cũ. Cả hai bước đều không gây lỗi nghiêm trọng; lỗi được ghi nhật ký và quá trình khởi động tiếp tục. Ở chế độ chỉ đọc (`openclaw doctor` không có `--fix`), kiểm tra này bị bỏ qua hoàn toàn. + + Khi một tài khoản kênh Matrix có di trú trạng thái cũ đang chờ hoặc có thể thực hiện, doctor (ở chế độ `--fix` / `--repair`) tạo ảnh chụp trước di trú rồi chạy các bước di trú theo khả năng tốt nhất: di trú trạng thái Matrix cũ và chuẩn bị trạng thái mã hóa cũ. Cả hai bước đều không gây lỗi nghiêm trọng; lỗi được ghi nhật ký và quá trình khởi động tiếp tục. Ở chế độ chỉ đọc (`openclaw doctor` không có `--fix`), kiểm tra này bị bỏ qua hoàn toàn. - - Doctor hiện kiểm tra trạng thái ghép nối thiết bị như một phần của lượt kiểm tra tình trạng bình thường. + + Doctor hiện kiểm tra trạng thái ghép cặp thiết bị như một phần của lượt kiểm tra sức khỏe thông thường. - Nội dung nó báo cáo: + Những gì nó báo cáo: - - yêu cầu ghép nối lần đầu đang chờ - - nâng cấp vai trò đang chờ cho thiết bị đã ghép nối - - nâng cấp phạm vi đang chờ cho thiết bị đã ghép nối - - sửa lỗi public-key không khớp khi device id vẫn khớp nhưng danh tính thiết bị không còn khớp với bản ghi đã phê duyệt - - bản ghi đã ghép nối thiếu token hoạt động cho một vai trò đã phê duyệt - - token đã ghép nối có phạm vi lệch khỏi baseline ghép nối đã phê duyệt - - mục device-token được cache cục bộ cho máy hiện tại có trước lần xoay token phía gateway hoặc mang metadata phạm vi lỗi thời + - yêu cầu ghép cặp lần đầu đang chờ + - nâng cấp vai trò đang chờ cho các thiết bị đã ghép cặp + - nâng cấp phạm vi đang chờ cho các thiết bị đã ghép cặp + - sửa lỗi không khớp khóa công khai khi id thiết bị vẫn khớp nhưng danh tính thiết bị không còn khớp bản ghi đã phê duyệt + - bản ghi đã ghép cặp thiếu token đang hoạt động cho một vai trò đã phê duyệt + - token đã ghép cặp có phạm vi lệch khỏi đường cơ sở ghép cặp đã phê duyệt + - mục token thiết bị được lưu đệm cục bộ cho máy hiện tại có trước một lần xoay token phía gateway hoặc mang metadata phạm vi đã cũ - Doctor không tự động phê duyệt yêu cầu ghép nối hoặc tự động xoay token thiết bị. Thay vào đó, nó in đúng các bước tiếp theo: + Doctor không tự phê duyệt yêu cầu ghép cặp hoặc tự xoay token thiết bị. Thay vào đó, nó in chính xác các bước tiếp theo: - kiểm tra yêu cầu đang chờ bằng `openclaw devices list` - phê duyệt đúng yêu cầu bằng `openclaw devices approve ` - xoay token mới bằng `openclaw devices rotate --device --role ` - - xóa và phê duyệt lại bản ghi lỗi thời bằng `openclaw devices remove ` + - xóa và phê duyệt lại bản ghi cũ bằng `openclaw devices remove ` - Việc này đóng lỗ hổng phổ biến "đã ghép nối nhưng vẫn nhận yêu cầu ghép nối": doctor hiện phân biệt ghép nối lần đầu với nâng cấp vai trò/phạm vi đang chờ và với lệch token/danh tính thiết bị lỗi thời. + Điều này đóng lỗ hổng phổ biến "đã ghép cặp nhưng vẫn bị yêu cầu ghép cặp": doctor giờ phân biệt ghép cặp lần đầu với nâng cấp vai trò/phạm vi đang chờ và với lệch token/danh tính thiết bị đã cũ. - Doctor phát cảnh báo khi một provider mở cho DM mà không có danh sách cho phép, hoặc khi một chính sách được cấu hình theo cách nguy hiểm. + Doctor phát cảnh báo khi một nhà cung cấp mở cho DM mà không có danh sách cho phép, hoặc khi một chính sách được cấu hình theo cách nguy hiểm. Nếu đang chạy dưới dạng dịch vụ người dùng systemd, doctor đảm bảo lingering được bật để gateway vẫn hoạt động sau khi đăng xuất. - - Doctor in tóm tắt trạng thái workspace cho tác nhân mặc định: + + Doctor in tóm tắt trạng thái workspace cho tác tử mặc định: - - **Trạng thái Skills**: đếm Skills đủ điều kiện, thiếu-yêu-cầu và bị danh sách-cho-phép chặn. - - **Thư mục workspace cũ**: cảnh báo khi `~/openclaw` hoặc các thư mục workspace cũ khác tồn tại bên cạnh workspace hiện tại. - - **Trạng thái Plugin**: đếm plugins đã bật/đã tắt/bị lỗi; liệt kê ID plugin cho mọi lỗi; báo cáo khả năng bundle plugin. - - **Cảnh báo tương thích Plugin**: đánh dấu plugins có vấn đề tương thích với runtime hiện tại. - - **Chẩn đoán Plugin**: hiển thị mọi cảnh báo hoặc lỗi tại thời điểm tải do registry plugin phát ra. + - **Trạng thái Skills**: đếm các skill đủ điều kiện, thiếu-yêu-cầu, và bị chặn bởi danh sách cho phép. + - **Thư mục workspace cũ**: cảnh báo khi `~/openclaw` hoặc các thư mục workspace cũ khác tồn tại cùng workspace hiện tại. + - **Trạng thái Plugin**: đếm các Plugin đã bật/đã tắt/bị lỗi; liệt kê ID Plugin cho mọi lỗi; báo cáo năng lực Plugin đóng gói. + - **Cảnh báo tương thích Plugin**: gắn cờ các Plugin có vấn đề tương thích với runtime hiện tại. + - **Chẩn đoán Plugin**: hiển thị mọi cảnh báo hoặc lỗi lúc tải do sổ đăng ký Plugin phát ra. - Doctor kiểm tra liệu các tệp bootstrap workspace (ví dụ `AGENTS.md`, `CLAUDE.md`, hoặc các tệp ngữ cảnh được chèn khác) có gần hoặc vượt ngân sách ký tự đã cấu hình hay không. Nó báo cáo số ký tự thô so với đã chèn theo từng tệp, phần trăm cắt ngắn, nguyên nhân cắt ngắn (`max/file` hoặc `max/total`), và tổng số ký tự đã chèn dưới dạng tỷ lệ của tổng ngân sách. Khi các tệp bị cắt ngắn hoặc gần giới hạn, doctor in mẹo để tinh chỉnh `agents.defaults.bootstrapMaxChars` và `agents.defaults.bootstrapTotalMaxChars`. + Doctor kiểm tra xem các tệp bootstrap workspace (ví dụ `AGENTS.md`, `CLAUDE.md`, hoặc các tệp ngữ cảnh được tiêm khác) có gần hoặc vượt ngân sách ký tự đã cấu hình hay không. Nó báo cáo số ký tự thô so với số ký tự được tiêm theo từng tệp, phần trăm cắt ngắn, nguyên nhân cắt ngắn (`max/file` hoặc `max/total`), và tổng số ký tự được tiêm dưới dạng một phần của tổng ngân sách. Khi tệp bị cắt ngắn hoặc gần giới hạn, doctor in mẹo để tinh chỉnh `agents.defaults.bootstrapMaxChars` và `agents.defaults.bootstrapTotalMaxChars`. - - Khi `openclaw doctor --fix` xóa một plugin channel bị thiếu, nó cũng xóa cấu hình treo theo phạm vi channel đã tham chiếu đến plugin đó: các mục `channels.`, mục tiêu Heartbeat đã nêu tên channel, và ghi đè `agents.*.models["/*"]`. Điều này ngăn các vòng lặp khởi động Gateway khi runtime channel đã biến mất nhưng cấu hình vẫn yêu cầu gateway liên kết với nó. + + Khi `openclaw doctor --fix` xóa một Plugin kênh bị thiếu, nó cũng xóa cấu hình theo phạm vi kênh đang treo đã tham chiếu Plugin đó: các mục `channels.`, mục tiêu heartbeat đã đặt tên kênh, và ghi đè `agents.*.models["/*"]`. Điều này ngăn các vòng lặp khởi động Gateway khi runtime kênh đã biến mất nhưng cấu hình vẫn yêu cầu gateway gắn với nó. - - Doctor kiểm tra liệu tab completion có được cài đặt cho shell hiện tại (zsh, bash, fish, hoặc PowerShell) hay không: + + Doctor kiểm tra xem hoàn tất bằng phím tab đã được cài đặt cho shell hiện tại (zsh, bash, fish, hoặc PowerShell) hay chưa: - - Nếu hồ sơ shell dùng mẫu completion động chậm (`source <(openclaw completion ...)`), doctor nâng cấp nó lên biến thể tệp cache nhanh hơn. - - Nếu completion được cấu hình trong hồ sơ nhưng tệp cache bị thiếu, doctor tự động tạo lại cache. - - Nếu chưa có completion nào được cấu hình, doctor nhắc cài đặt nó (chỉ chế độ tương tác; bỏ qua với `--non-interactive`). + - Nếu hồ sơ shell dùng mẫu hoàn tất động chậm (`source <(openclaw completion ...)`), doctor nâng cấp nó lên biến thể tệp lưu đệm nhanh hơn. + - Nếu hoàn tất được cấu hình trong hồ sơ nhưng thiếu tệp lưu đệm, doctor tự động tạo lại bộ đệm. + - Nếu hoàn toàn chưa cấu hình hoàn tất, doctor nhắc cài đặt nó (chỉ chế độ tương tác; bị bỏ qua với `--non-interactive`). - Chạy `openclaw completion --write-state` để tạo lại cache thủ công. + Chạy `openclaw completion --write-state` để tạo lại bộ đệm theo cách thủ công. Doctor kiểm tra mức sẵn sàng xác thực token gateway cục bộ. - - Nếu chế độ token cần token và không có nguồn token nào tồn tại, doctor đề nghị tạo một token. - - Nếu `gateway.auth.token` do SecretRef quản lý nhưng không khả dụng, doctor cảnh báo và không ghi đè nó bằng plaintext. + - Nếu chế độ token cần một token và không có nguồn token nào tồn tại, doctor đề xuất tạo một token. + - Nếu `gateway.auth.token` do SecretRef quản lý nhưng không khả dụng, doctor cảnh báo và không ghi đè nó bằng văn bản thuần. - `openclaw doctor --generate-gateway-token` chỉ buộc tạo khi không có SecretRef token nào được cấu hình. - + Một số luồng sửa chữa cần kiểm tra thông tin xác thực đã cấu hình mà không làm suy yếu hành vi fail-fast của runtime. - - `openclaw doctor --fix` hiện dùng cùng mô hình tóm tắt SecretRef chỉ đọc như các lệnh thuộc nhóm trạng thái cho các sửa chữa cấu hình có mục tiêu. - - Ví dụ: sửa chữa Telegram `allowFrom` / `groupAllowFrom` `@username` cố gắng dùng thông tin đăng nhập bot đã cấu hình khi có sẵn. - - Nếu token bot Telegram được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại, doctor báo cáo rằng thông tin đăng nhập đã được cấu hình-nhưng-không-khả-dụng và bỏ qua tự động phân giải thay vì gặp lỗi hoặc báo sai rằng token bị thiếu. + - `openclaw doctor --fix` hiện dùng cùng mô hình tóm tắt SecretRef chỉ đọc như các lệnh cùng nhóm trạng thái cho những sửa chữa cấu hình có mục tiêu. + - Ví dụ: sửa chữa `allowFrom` / `groupAllowFrom` `@username` của Telegram cố gắng dùng thông tin xác thực bot đã cấu hình khi có sẵn. + - Nếu token bot Telegram được cấu hình qua SecretRef nhưng không có sẵn trong đường dẫn lệnh hiện tại, doctor báo rằng thông tin xác thực đã được cấu hình nhưng không khả dụng và bỏ qua tự động phân giải thay vì bị lỗi hoặc báo sai rằng token bị thiếu. - - Doctor chạy kiểm tra sức khỏe và đề xuất khởi động lại gateway khi có vẻ không khỏe. + + Doctor chạy kiểm tra tình trạng và đề nghị khởi động lại Gateway khi Gateway có vẻ không khỏe. - - Doctor kiểm tra xem nhà cung cấp embedding tìm kiếm bộ nhớ đã cấu hình có sẵn sàng cho tác tử mặc định hay không. Hành vi phụ thuộc vào backend và nhà cung cấp đã cấu hình: + + Doctor kiểm tra xem trình cung cấp embedding tìm kiếm bộ nhớ đã cấu hình có sẵn sàng cho tác nhân mặc định hay không. Hành vi phụ thuộc vào backend và trình cung cấp đã cấu hình: - **Backend QMD**: thăm dò xem binary `qmd` có khả dụng và có thể khởi động hay không. Nếu không, in hướng dẫn sửa lỗi bao gồm gói npm và tùy chọn đường dẫn binary thủ công. - - **Nhà cung cấp cục bộ tường minh**: kiểm tra tệp mô hình cục bộ hoặc URL mô hình từ xa/có thể tải xuống được nhận diện. Nếu thiếu, đề xuất chuyển sang nhà cung cấp từ xa. - - **Nhà cung cấp từ xa tường minh** (`openai`, `voyage`, v.v.): xác minh khóa API có trong môi trường hoặc kho xác thực. In gợi ý sửa lỗi có thể hành động nếu thiếu. - - **Nhà cung cấp tự động**: kiểm tra tính khả dụng của mô hình cục bộ trước, rồi thử từng nhà cung cấp từ xa theo thứ tự tự động chọn. + - **Trình cung cấp cục bộ tường minh**: kiểm tra tệp mô hình cục bộ hoặc URL mô hình từ xa/có thể tải xuống được nhận diện. Nếu thiếu, đề xuất chuyển sang trình cung cấp từ xa. + - **Trình cung cấp từ xa tường minh** (`openai`, `voyage`, v.v.): xác minh khóa API có mặt trong môi trường hoặc kho xác thực. In gợi ý sửa lỗi có thể thực hiện nếu thiếu. + - **Trình cung cấp tự động**: kiểm tra khả năng có sẵn của mô hình cục bộ trước, rồi thử từng trình cung cấp từ xa theo thứ tự tự động chọn. - Khi có kết quả thăm dò gateway được lưu trong bộ nhớ đệm (gateway khỏe tại thời điểm kiểm tra), doctor đối chiếu kết quả đó với cấu hình CLI có thể thấy và ghi chú mọi điểm không khớp. Doctor không khởi động ping embedding mới trên đường dẫn mặc định; dùng lệnh trạng thái bộ nhớ sâu khi bạn muốn kiểm tra nhà cung cấp trực tiếp. + Khi có kết quả thăm dò Gateway được lưu trong bộ nhớ đệm (Gateway khỏe tại thời điểm kiểm tra), doctor đối chiếu kết quả đó với cấu hình mà CLI thấy được và ghi chú mọi khác biệt. Doctor không khởi động ping embedding mới trên đường dẫn mặc định; hãy dùng lệnh trạng thái bộ nhớ sâu khi bạn muốn kiểm tra trình cung cấp trực tiếp. Dùng `openclaw memory status --deep` để xác minh mức sẵn sàng của embedding khi chạy. - Nếu gateway khỏe, doctor chạy thăm dò trạng thái kênh và báo cáo cảnh báo kèm các sửa lỗi được đề xuất. + Nếu Gateway khỏe, doctor chạy thăm dò trạng thái kênh và báo cáo cảnh báo kèm các sửa lỗi được đề xuất. - - Doctor kiểm tra cấu hình supervisor đã cài đặt (launchd/systemd/schtasks) để tìm các mặc định bị thiếu hoặc đã lỗi thời (ví dụ: phụ thuộc systemd network-online và độ trễ khởi động lại). Khi tìm thấy điểm không khớp, nó đề xuất cập nhật và có thể ghi lại tệp dịch vụ/tác vụ theo các mặc định hiện tại. + + Doctor kiểm tra cấu hình supervisor đã cài đặt (launchd/systemd/schtasks) để tìm các mặc định bị thiếu hoặc lỗi thời (ví dụ: phụ thuộc systemd network-online và độ trễ khởi động lại). Khi phát hiện không khớp, doctor đề xuất cập nhật và có thể ghi lại tệp dịch vụ/tác vụ theo các mặc định hiện tại. Ghi chú: - `openclaw doctor` nhắc trước khi ghi lại cấu hình supervisor. - `openclaw doctor --yes` chấp nhận các lời nhắc sửa chữa mặc định. - - `openclaw doctor --repair` áp dụng các sửa lỗi được đề xuất mà không cần lời nhắc. + - `openclaw doctor --repair` áp dụng các sửa lỗi được đề xuất mà không nhắc. - `openclaw doctor --repair --force` ghi đè cấu hình supervisor tùy chỉnh. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` giữ doctor ở chế độ chỉ đọc cho vòng đời dịch vụ gateway. Nó vẫn báo cáo sức khỏe dịch vụ và chạy các sửa chữa không thuộc dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ, ghi lại cấu hình supervisor, và dọn dẹp dịch vụ cũ vì một supervisor bên ngoài sở hữu vòng đời đó. - - Trên Linux, doctor không ghi lại metadata lệnh/entrypoint khi unit gateway systemd tương ứng đang hoạt động. Nó cũng bỏ qua các unit giống gateway bổ sung không hoạt động và không phải legacy trong quá trình quét dịch vụ trùng lặp để các tệp dịch vụ đồng hành không tạo nhiễu dọn dẹp. - - Nếu xác thực bằng token yêu cầu token và `gateway.auth.token` được quản lý bằng SecretRef, quá trình cài đặt/sửa chữa dịch vụ của doctor xác thực SecretRef nhưng không lưu giá trị token văn bản thuần đã phân giải vào metadata môi trường dịch vụ supervisor. - - Doctor phát hiện các giá trị môi trường dịch vụ được quản lý bằng `.env`/SecretRef mà các bản cài LaunchAgent, systemd, hoặc Windows Scheduled Task cũ đã nhúng inline và ghi lại metadata dịch vụ để các giá trị đó tải từ nguồn runtime thay vì định nghĩa supervisor. - - Doctor phát hiện khi lệnh dịch vụ vẫn ghim `--port` cũ sau khi `gateway.port` thay đổi và ghi lại metadata dịch vụ sang cổng hiện tại. - - Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, doctor chặn đường dẫn cài đặt/sửa chữa kèm hướng dẫn có thể hành động. - - Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, doctor chặn cài đặt/sửa chữa cho đến khi mode được đặt tường minh. - - Đối với các unit user-systemd trên Linux, kiểm tra trôi lệch token của doctor giờ bao gồm cả nguồn `Environment=` và `EnvironmentFile=` khi so sánh metadata xác thực dịch vụ. - - Sửa chữa dịch vụ của doctor từ chối ghi lại, dừng, hoặc khởi động lại dịch vụ gateway từ binary OpenClaw cũ hơn khi cấu hình được ghi lần cuối bởi phiên bản mới hơn. Xem [Khắc phục sự cố Gateway](/vi/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` giữ doctor ở chế độ chỉ đọc cho vòng đời dịch vụ Gateway. Doctor vẫn báo cáo tình trạng dịch vụ và chạy các sửa chữa không thuộc dịch vụ, nhưng bỏ qua cài đặt/khởi động/khởi động lại/bootstrap dịch vụ, ghi lại cấu hình supervisor và dọn dẹp dịch vụ cũ vì một supervisor bên ngoài sở hữu vòng đời đó. + - Trên Linux, doctor không ghi lại siêu dữ liệu lệnh/entrypoint khi unit Gateway systemd tương ứng đang hoạt động. Doctor cũng bỏ qua các unit bổ sung giống Gateway, không phải loại cũ và đang không hoạt động trong quá trình quét dịch vụ trùng lặp để các tệp dịch vụ đi kèm không tạo nhiễu khi dọn dẹp. + - Nếu xác thực bằng token yêu cầu token và `gateway.auth.token` được quản lý bằng SecretRef, quá trình cài đặt/sửa chữa dịch vụ của doctor xác thực SecretRef nhưng không lưu các giá trị token plaintext đã phân giải vào siêu dữ liệu môi trường dịch vụ supervisor. + - Doctor phát hiện các giá trị môi trường dịch vụ được quản lý bằng `.env`/SecretRef mà các bản cài đặt LaunchAgent, systemd hoặc Windows Scheduled Task cũ hơn đã nhúng inline, rồi ghi lại siêu dữ liệu dịch vụ để các giá trị đó tải từ nguồn runtime thay vì từ định nghĩa supervisor. + - Doctor phát hiện khi lệnh dịch vụ vẫn ghim `--port` cũ sau khi `gateway.port` thay đổi và ghi lại siêu dữ liệu dịch vụ sang cổng hiện tại. + - Nếu xác thực bằng token yêu cầu token và SecretRef token đã cấu hình chưa được phân giải, doctor chặn đường dẫn cài đặt/sửa chữa với hướng dẫn có thể thực hiện. + - Nếu cả `gateway.auth.token` và `gateway.auth.password` đều được cấu hình và `gateway.auth.mode` chưa được đặt, doctor chặn cài đặt/sửa chữa cho đến khi chế độ được đặt tường minh. + - Với các unit user-systemd trên Linux, kiểm tra sai lệch token của doctor hiện bao gồm cả nguồn `Environment=` và `EnvironmentFile=` khi so sánh siêu dữ liệu xác thực dịch vụ. + - Sửa chữa dịch vụ của doctor từ chối ghi lại, dừng hoặc khởi động lại dịch vụ Gateway từ một binary OpenClaw cũ hơn khi cấu hình được ghi lần cuối bởi phiên bản mới hơn. Xem [Khắc phục sự cố Gateway](/vi/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Bạn luôn có thể buộc ghi lại toàn bộ qua `openclaw gateway install --force`. - - Doctor kiểm tra runtime dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã cài đặt nhưng thực tế không chạy. Nó cũng kiểm tra xung đột cổng trên cổng gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng (gateway đã chạy, đường hầm SSH). + + Doctor kiểm tra runtime dịch vụ (PID, trạng thái thoát gần nhất) và cảnh báo khi dịch vụ đã được cài đặt nhưng thực tế không chạy. Doctor cũng kiểm tra xung đột cổng trên cổng Gateway (mặc định `18789`) và báo cáo các nguyên nhân có khả năng xảy ra (Gateway đã chạy, đường hầm SSH). - Doctor cảnh báo khi dịch vụ gateway chạy trên Bun hoặc đường dẫn Node do trình quản lý phiên bản quản lý (`nvm`, `fnm`, `volta`, `asdf`, v.v.). Các kênh WhatsApp + Telegram yêu cầu Node, và đường dẫn trình quản lý phiên bản có thể hỏng sau khi nâng cấp vì dịch vụ không tải init shell của bạn. Doctor đề xuất di chuyển sang bản cài Node hệ thống khi có sẵn (Homebrew/apt/choco). + Doctor cảnh báo khi dịch vụ Gateway chạy trên Bun hoặc đường dẫn Node do trình quản lý phiên bản quản lý (`nvm`, `fnm`, `volta`, `asdf`, v.v.). Các kênh WhatsApp + Telegram yêu cầu Node, và đường dẫn trình quản lý phiên bản có thể hỏng sau khi nâng cấp vì dịch vụ không tải khởi tạo shell của bạn. Doctor đề nghị di chuyển sang bản cài đặt Node hệ thống khi có sẵn (Homebrew/apt/choco). - Các macOS LaunchAgent mới được cài đặt hoặc sửa chữa dùng PATH hệ thống chuẩn (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) thay vì sao chép PATH shell tương tác, nên Volta, asdf, fnm, pnpm, và các thư mục trình quản lý phiên bản khác không thay đổi Node mà tiến trình con phân giải. Dịch vụ Linux vẫn giữ các root môi trường tường minh (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) và các thư mục user-bin ổn định, nhưng các thư mục dự phòng trình quản lý phiên bản được đoán chỉ được ghi vào PATH dịch vụ khi các thư mục đó tồn tại trên đĩa. + Các LaunchAgent macOS mới được cài đặt hoặc sửa chữa dùng PATH hệ thống chuẩn (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) thay vì sao chép PATH của shell tương tác, vì vậy Volta, asdf, fnm, pnpm và các thư mục trình quản lý phiên bản khác không thay đổi Node mà các tiến trình con phân giải. Dịch vụ Linux vẫn giữ các gốc môi trường tường minh (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) và các thư mục user-bin ổn định, nhưng các thư mục dự phòng trình quản lý phiên bản được đoán chỉ được ghi vào PATH dịch vụ khi những thư mục đó tồn tại trên đĩa. - - Doctor lưu mọi thay đổi cấu hình và đóng dấu metadata wizard để ghi lại lần chạy doctor. + + Doctor lưu mọi thay đổi cấu hình và đóng dấu siêu dữ liệu trình hướng dẫn để ghi nhận lần chạy doctor. - - Doctor đề xuất một hệ thống bộ nhớ workspace khi thiếu và in mẹo sao lưu nếu workspace chưa nằm trong git. + + Doctor đề xuất hệ thống bộ nhớ không gian làm việc khi thiếu và in mẹo sao lưu nếu không gian làm việc chưa nằm trong git. - Xem [/concepts/agent-workspace](/vi/concepts/agent-workspace) để có hướng dẫn đầy đủ về cấu trúc workspace và sao lưu git (khuyến nghị GitHub hoặc GitLab riêng tư). + Xem [/concepts/agent-workspace](/vi/concepts/agent-workspace) để có hướng dẫn đầy đủ về cấu trúc không gian làm việc và sao lưu git (khuyến nghị GitHub hoặc GitLab riêng tư). diff --git a/docs/vi/install/docker.md b/docs/vi/install/docker.md index acfe0ebca..ecf4b2040 100644 --- a/docs/vi/install/docker.md +++ b/docs/vi/install/docker.md @@ -1,53 +1,53 @@ --- read_when: - - Bạn muốn một Gateway được đóng gói trong container thay vì các bản cài đặt cục bộ - - Bạn đang xác thực quy trình Docker -summary: Thiết lập và hướng dẫn làm quen tùy chọn dựa trên Docker cho OpenClaw + - Bạn muốn một Gateway chạy trong container thay vì cài đặt cục bộ + - Bạn đang xác thực luồng Docker +summary: Thiết lập và hướng dẫn bắt đầu bằng Docker tùy chọn cho OpenClaw title: Docker x-i18n: - generated_at: "2026-05-02T20:45:20Z" + generated_at: "2026-05-05T08:26:03Z" model: gpt-5.5 provider: openai - source_hash: 5e57659c89a0b207b4b331752e7faaa814fe1f0043dad97043e95e460286c551 + source_hash: f57db2ec12f1a1fd681ec90cc43b2c945755a9240f571de46688777e957f1b8e source_path: install/docker.md workflow: 16 --- -Docker là **tùy chọn**. Chỉ dùng nếu bạn muốn Gateway dạng container hoặc muốn xác thực luồng Docker. +Docker là **tùy chọn**. Chỉ dùng nếu bạn muốn Gateway chạy trong container hoặc muốn xác thực luồng Docker. ## Docker có phù hợp với tôi không? -- **Có**: bạn muốn một môi trường Gateway tách biệt, dùng xong bỏ, hoặc muốn chạy OpenClaw trên một host không cài đặt cục bộ. -- **Không**: bạn đang chạy trên máy của mình và chỉ muốn vòng lặp phát triển nhanh nhất. Thay vào đó, hãy dùng luồng cài đặt thông thường. -- **Lưu ý về sandboxing**: backend sandbox mặc định dùng Docker khi sandboxing được bật, nhưng sandboxing tắt theo mặc định và **không** yêu cầu toàn bộ Gateway chạy trong Docker. Các backend sandbox SSH và OpenShell cũng có sẵn. Xem [Sandboxing](/vi/gateway/sandboxing). +- **Có**: bạn muốn một môi trường Gateway cô lập, dùng xong bỏ, hoặc muốn chạy OpenClaw trên một máy chủ không có cài đặt cục bộ. +- **Không**: bạn đang chạy trên máy của mình và chỉ muốn vòng lặp phát triển nhanh nhất. Hãy dùng luồng cài đặt thông thường. +- **Lưu ý về sandbox**: backend sandbox mặc định dùng Docker khi sandbox được bật, nhưng sandbox mặc định đang tắt và **không** yêu cầu toàn bộ Gateway chạy trong Docker. Các backend sandbox SSH và OpenShell cũng có sẵn. Xem [Sandbox](/vi/gateway/sandboxing). ## Điều kiện tiên quyết - Docker Desktop (hoặc Docker Engine) + Docker Compose v2 -- Ít nhất 2 GB RAM để build image (`pnpm install` có thể bị OOM-killed trên host 1 GB với mã thoát 137) +- Tối thiểu 2 GB RAM để build image (`pnpm install` có thể bị dừng do hết bộ nhớ trên máy chủ 1 GB với mã thoát 137) - Đủ dung lượng đĩa cho image và log -- Nếu chạy trên VPS/host công khai, hãy xem lại - [Gia cố bảo mật khi mở mạng](/vi/gateway/security), +- Nếu chạy trên VPS/máy chủ công khai, hãy xem lại + [Gia cố bảo mật khi phơi ra mạng](/vi/gateway/security), đặc biệt là chính sách tường lửa Docker `DOCKER-USER`. -## Gateway dạng container +## Gateway chạy trong container - Từ gốc repo, chạy script thiết lập: + Từ thư mục gốc của repo, chạy script thiết lập: ```bash ./scripts/docker/setup.sh ``` - Lệnh này build image Gateway cục bộ. Để dùng image đã build sẵn thay thế: + Lệnh này build image Gateway cục bộ. Để dùng image đã build sẵn thay vào đó: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" ./scripts/docker/setup.sh ``` - Image build sẵn được phát hành tại + Image đã build sẵn được phát hành tại [GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw). Các tag phổ biến: `main`, `latest`, `` (ví dụ `2026.2.26`). @@ -56,22 +56,22 @@ Docker là **tùy chọn**. Chỉ dùng nếu bạn muốn Gateway dạng contai Script thiết lập tự động chạy onboarding. Nó sẽ: - - yêu cầu khóa API của nhà cung cấp + - nhắc nhập khóa API của nhà cung cấp - tạo token Gateway và ghi vào `.env` - khởi động Gateway qua Docker Compose - Trong quá trình thiết lập, onboarding trước khi khởi động và các lần ghi cấu hình được chạy trực tiếp qua + Trong quá trình thiết lập, onboarding trước khi khởi động và các thao tác ghi cấu hình chạy trực tiếp qua `openclaw-gateway`. `openclaw-cli` dành cho các lệnh bạn chạy sau khi container Gateway đã tồn tại. - + Mở `http://127.0.0.1:18789/` trong trình duyệt và dán shared secret đã cấu hình - vào Settings. Theo mặc định, script thiết lập ghi một token vào `.env`; nếu bạn chuyển cấu hình container sang xác thực bằng mật khẩu, hãy dùng mật khẩu đó - thay thế. + vào Settings. Theo mặc định, script thiết lập ghi token vào `.env`; nếu bạn chuyển cấu hình container sang xác thực bằng mật khẩu, hãy dùng + mật khẩu đó thay thế. - Cần xem lại URL? + Cần lại URL? ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -112,15 +112,15 @@ docker compose up -d openclaw-gateway ``` -Chạy `docker compose` từ gốc repo. Nếu bạn đã bật `OPENCLAW_EXTRA_MOUNTS` +Chạy `docker compose` từ thư mục gốc của repo. Nếu bạn đã bật `OPENCLAW_EXTRA_MOUNTS` hoặc `OPENCLAW_HOME_VOLUME`, script thiết lập sẽ ghi `docker-compose.extra.yml`; -hãy bao gồm nó bằng `-f docker-compose.yml -f docker-compose.extra.yml`. +hãy thêm nó bằng `-f docker-compose.yml -f docker-compose.extra.yml`. -Vì `openclaw-cli` dùng chung namespace mạng của `openclaw-gateway`, nó là một -công cụ sau khởi động. Trước khi chạy `docker compose up -d openclaw-gateway`, hãy chạy onboarding -và các lần ghi cấu hình lúc thiết lập qua `openclaw-gateway` với +Vì `openclaw-cli` chia sẻ namespace mạng của `openclaw-gateway`, nó là công cụ +sau khi khởi động. Trước `docker compose up -d openclaw-gateway`, hãy chạy onboarding +và các thao tác ghi cấu hình trong thời gian thiết lập qua `openclaw-gateway` với `--no-deps --entrypoint node`. @@ -131,34 +131,34 @@ Script thiết lập chấp nhận các biến môi trường tùy chọn sau: | Biến | Mục đích | | ------------------------------------------ | --------------------------------------------------------------- | | `OPENCLAW_IMAGE` | Dùng image từ xa thay vì build cục bộ | -| `OPENCLAW_DOCKER_APT_PACKAGES` | Cài đặt thêm các gói apt trong lúc build (phân tách bằng khoảng trắng) | -| `OPENCLAW_EXTENSIONS` | Bao gồm các helper Plugin được bundle đã chọn tại thời điểm build | -| `OPENCLAW_EXTRA_MOUNTS` | Các bind mount host bổ sung (phân tách bằng dấu phẩy `source:target[:opts]`) | -| `OPENCLAW_HOME_VOLUME` | Duy trì `/home/node` trong một Docker volume có tên | -| `OPENCLAW_SANDBOX` | Chọn tham gia khởi tạo sandbox (`1`, `true`, `yes`, `on`) | +| `OPENCLAW_DOCKER_APT_PACKAGES` | Cài thêm gói apt trong quá trình build (phân tách bằng dấu cách) | +| `OPENCLAW_EXTENSIONS` | Bao gồm các trình trợ giúp Plugin đi kèm được chọn khi build | +| `OPENCLAW_EXTRA_MOUNTS` | Bind mount bổ sung từ máy chủ (phân tách bằng dấu phẩy `source:target[:opts]`) | +| `OPENCLAW_HOME_VOLUME` | Lưu giữ `/home/node` trong một Docker volume có tên | +| `OPENCLAW_SANDBOX` | Bật bootstrap sandbox (`1`, `true`, `yes`, `on`) | | `OPENCLAW_SKIP_ONBOARDING` | Bỏ qua bước onboarding tương tác (`1`, `true`, `yes`, `on`) | | `OPENCLAW_DOCKER_SOCKET` | Ghi đè đường dẫn Docker socket | | `OPENCLAW_DISABLE_BONJOUR` | Tắt quảng bá Bonjour/mDNS (mặc định là `1` cho Docker) | -| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Tắt các overlay bind-mount mã nguồn Plugin được bundle | +| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Tắt các lớp phủ bind-mount nguồn Plugin đi kèm | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint collector OTLP/HTTP dùng chung cho xuất OpenTelemetry | -| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Endpoint OTLP theo từng tín hiệu cho trace, metric hoặc log | +| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Endpoint OTLP theo tín hiệu cho trace, metric hoặc log | | `OTEL_EXPORTER_OTLP_PROTOCOL` | Ghi đè giao thức OTLP. Hiện chỉ hỗ trợ `http/protobuf` | | `OTEL_SERVICE_NAME` | Tên dịch vụ dùng cho tài nguyên OpenTelemetry | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Chọn tham gia các thuộc tính ngữ nghĩa GenAI thử nghiệm mới nhất | -| `OPENCLAW_OTEL_PRELOADED` | Bỏ qua việc khởi động SDK OpenTelemetry thứ hai khi một SDK đã được tải sẵn | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Bật các thuộc tính ngữ nghĩa GenAI thử nghiệm mới nhất | +| `OPENCLAW_OTEL_PRELOADED` | Bỏ qua việc khởi động SDK OpenTelemetry thứ hai khi đã preload một SDK | -Maintainer có thể kiểm thử mã nguồn Plugin được bundle với một image đã đóng gói bằng cách mount -một thư mục mã nguồn Plugin lên trên đường dẫn mã nguồn đã đóng gói của nó, ví dụ +Maintainer có thể kiểm thử nguồn Plugin đi kèm với một image đóng gói bằng cách mount +một thư mục nguồn Plugin lên đường dẫn nguồn đã đóng gói của nó, ví dụ `OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`. -Thư mục mã nguồn được mount đó ghi đè bundle đã biên dịch tương ứng +Thư mục nguồn đã mount đó ghi đè bundle đã biên dịch tương ứng `/app/dist/extensions/synology-chat` cho cùng id Plugin. -### Khả năng quan sát +### Quan sát hệ thống -Xuất OpenTelemetry là luồng outbound từ container Gateway đến OTLP -collector của bạn. Việc này không yêu cầu cổng Docker đã phát hành. Nếu bạn build image -cục bộ và muốn exporter OpenTelemetry được bundle có sẵn bên trong image, -hãy bao gồm các dependency runtime của nó: +Xuất OpenTelemetry là kết nối đi từ container Gateway tới collector OTLP +của bạn. Việc này không yêu cầu cổng Docker được công bố. Nếu bạn build image +cục bộ và muốn exporter OpenTelemetry đi kèm có sẵn bên trong image, +hãy bao gồm các phụ thuộc runtime của nó: ```bash export OPENCLAW_EXTENSIONS="diagnostics-otel" @@ -167,16 +167,16 @@ export OTEL_SERVICE_NAME="openclaw-gateway" ./scripts/docker/setup.sh ``` -Cài đặt Plugin chính thức `@openclaw/diagnostics-otel` từ ClawHub trong -các bản cài Docker đã đóng gói trước khi bật xuất. Image build từ mã nguồn tùy chỉnh vẫn có thể -bao gồm mã nguồn Plugin cục bộ bằng -`OPENCLAW_EXTENSIONS=diagnostics-otel`. Để bật xuất, hãy cho phép và bật -Plugin `diagnostics-otel` trong cấu hình, rồi đặt -`diagnostics.otel.enabled=true` hoặc dùng ví dụ cấu hình trong [xuất OpenTelemetry +Cài Plugin chính thức `@openclaw/diagnostics-otel` từ ClawHub trong +các bản cài Docker đóng gói trước khi bật xuất. Image tự build từ nguồn tùy chỉnh vẫn có thể +bao gồm nguồn Plugin cục bộ bằng +`OPENCLAW_EXTENSIONS=diagnostics-otel`. Để bật xuất, cho phép và bật +Plugin `diagnostics-otel` trong cấu hình, sau đó đặt +`diagnostics.otel.enabled=true` hoặc dùng ví dụ cấu hình trong [Xuất OpenTelemetry ](/vi/gateway/opentelemetry). Header xác thực collector được cấu hình qua `diagnostics.otel.headers`, không phải qua biến môi trường Docker. -Metric Prometheus dùng cổng Gateway đã được phát hành sẵn. Cài đặt +Metric Prometheus dùng cổng Gateway đã được công bố sẵn. Cài `clawhub:@openclaw/diagnostics-prometheus`, bật Plugin `diagnostics-prometheus`, rồi scrape: @@ -184,24 +184,24 @@ Metric Prometheus dùng cổng Gateway đã được phát hành sẵn. Cài đ http://:18789/api/diagnostics/prometheus ``` -Route này được bảo vệ bằng xác thực Gateway. Không mở một cổng `/metrics` -công khai riêng hoặc đường dẫn reverse-proxy không xác thực. Xem -[metric Prometheus](/vi/gateway/prometheus). +Tuyến này được bảo vệ bằng xác thực Gateway. Không phơi một cổng +`/metrics` công khai riêng hoặc đường dẫn reverse-proxy không xác thực. Xem +[Metric Prometheus](/vi/gateway/prometheus). ### Kiểm tra sức khỏe -Endpoint probe của container (không yêu cầu xác thực): +Endpoint probe container (không yêu cầu xác thực): ```bash curl -fsS http://127.0.0.1:18789/healthz # liveness curl -fsS http://127.0.0.1:18789/readyz # readiness ``` -Image Docker bao gồm `HEALTHCHECK` tích hợp sẵn, ping `/healthz`. -Nếu các kiểm tra tiếp tục thất bại, Docker đánh dấu container là `unhealthy` và +Docker image bao gồm `HEALTHCHECK` tích hợp sẵn ping `/healthz`. +Nếu các kiểm tra liên tục thất bại, Docker đánh dấu container là `unhealthy` và các hệ thống điều phối có thể khởi động lại hoặc thay thế nó. -Snapshot sức khỏe sâu có xác thực: +Ảnh chụp sức khỏe sâu có xác thực: ```bash docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN" @@ -209,83 +209,83 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA ### LAN so với loopback -`scripts/docker/setup.sh` mặc định `OPENCLAW_GATEWAY_BIND=lan` để truy cập từ host đến -`http://127.0.0.1:18789` hoạt động với cơ chế phát hành cổng của Docker. +`scripts/docker/setup.sh` mặc định `OPENCLAW_GATEWAY_BIND=lan` để quyền truy cập từ máy chủ tới +`http://127.0.0.1:18789` hoạt động với việc công bố cổng Docker. -- `lan` (mặc định): trình duyệt host và CLI host có thể truy cập cổng Gateway đã phát hành. +- `lan` (mặc định): trình duyệt trên máy chủ và CLI trên máy chủ có thể truy cập cổng Gateway đã công bố. - `loopback`: chỉ các tiến trình bên trong namespace mạng của container mới có thể truy cập trực tiếp Gateway. -Dùng các giá trị chế độ bind trong `gateway.bind` (`lan` / `loopback` / `custom` / -`tailnet` / `auto`), không dùng bí danh host như `0.0.0.0` hoặc `127.0.0.1`. +Dùng giá trị chế độ bind trong `gateway.bind` (`lan` / `loopback` / `custom` / +`tailnet` / `auto`), không dùng alias máy chủ như `0.0.0.0` hoặc `127.0.0.1`. -### Nhà cung cấp cục bộ trên host +### Nhà cung cấp cục bộ trên máy chủ -Khi OpenClaw chạy trong Docker, `127.0.0.1` bên trong container là chính container -đó, không phải máy host của bạn. Dùng `host.docker.internal` cho các nhà cung cấp AI -chạy trên host: +Khi OpenClaw chạy trong Docker, `127.0.0.1` bên trong container là chính container đó, +không phải máy chủ của bạn. Dùng `host.docker.internal` cho các nhà cung cấp AI +chạy trên máy chủ: -| Nhà cung cấp | URL mặc định của host | URL thiết lập Docker | +| Nhà cung cấp | URL mặc định trên máy chủ | URL thiết lập Docker | | ------------ | ------------------------- | ----------------------------------- | -| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` | -| Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` | +| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` | +| Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` | -Thiết lập Docker được bundle dùng các URL host đó làm mặc định onboarding cho LM Studio và Ollama, -và `docker-compose.yml` ánh xạ `host.docker.internal` đến -Gateway host của Docker cho Linux Docker Engine. Docker Desktop đã cung cấp -cùng hostname trên macOS và Windows. +Thiết lập Docker đi kèm dùng các URL máy chủ đó làm giá trị mặc định onboarding +cho LM Studio và Ollama, và `docker-compose.yml` ánh xạ `host.docker.internal` tới +Gateway máy chủ của Docker cho Linux Docker Engine. Docker Desktop đã cung cấp +cùng hostname đó trên macOS và Windows. -Dịch vụ host cũng phải lắng nghe trên một địa chỉ có thể truy cập từ Docker: +Dịch vụ trên máy chủ cũng phải lắng nghe trên một địa chỉ có thể truy cập từ Docker: ```bash lms server start --port 1234 --bind 0.0.0.0 OLLAMA_HOST=0.0.0.0:11434 ollama serve ``` -Nếu bạn dùng file Compose hoặc lệnh `docker run` riêng, hãy tự thêm cùng ánh xạ host -đó, ví dụ +Nếu bạn dùng Compose file riêng hoặc lệnh `docker run`, hãy tự thêm cùng ánh xạ máy chủ, +ví dụ `--add-host=host.docker.internal:host-gateway`. ### Bonjour / mDNS Mạng bridge của Docker thường không chuyển tiếp multicast Bonjour/mDNS -(`224.0.0.251:5353`) một cách đáng tin cậy. Vì vậy, thiết lập Compose được bundle mặc định -`OPENCLAW_DISABLE_BONJOUR=1` để Gateway không rơi vào vòng lặp crash hoặc liên tục -khởi động lại việc quảng bá khi bridge làm rơi lưu lượng multicast. +(`224.0.0.251:5353`) một cách đáng tin cậy. Vì vậy, thiết lập Compose đi kèm mặc định +`OPENCLAW_DISABLE_BONJOUR=1` để Gateway không bị vòng lặp crash hoặc liên tục +khởi động lại quảng bá khi bridge làm rơi lưu lượng multicast. -Dùng URL Gateway đã phát hành, Tailscale hoặc DNS-SD diện rộng cho host Docker. -Chỉ đặt `OPENCLAW_DISABLE_BONJOUR=0` khi chạy với host networking, macvlan, -hoặc một mạng khác mà multicast mDNS đã được biết là hoạt động. +Dùng URL Gateway đã công bố, Tailscale, hoặc DNS-SD diện rộng cho máy chủ Docker. +Chỉ đặt `OPENCLAW_DISABLE_BONJOUR=0` khi chạy với mạng host, macvlan, +hoặc mạng khác mà multicast mDNS được biết là hoạt động. -Để biết các điểm dễ lỗi và cách khắc phục, xem [khám phá Bonjour](/vi/gateway/bonjour). +Để xem các điểm dễ vướng và cách khắc phục sự cố, xem [Khám phá Bonjour](/vi/gateway/bonjour). ### Lưu trữ và duy trì dữ liệu Docker Compose bind-mount `OPENCLAW_CONFIG_DIR` vào `/home/node/.openclaw` và `OPENCLAW_WORKSPACE_DIR` vào `/home/node/.openclaw/workspace`, nên các đường dẫn đó -vẫn tồn tại sau khi thay thế container. Khi một trong hai biến chưa được đặt, -`docker-compose.yml` được bundle sẽ fallback về `${HOME}/.openclaw` (và -`${HOME}/.openclaw/workspace` cho workspace mount), hoặc `/tmp/.openclaw` +vẫn tồn tại sau khi thay thế container. Khi một trong hai biến chưa được đặt, file +`docker-compose.yml` đi kèm sẽ fallback về `${HOME}/.openclaw` (và +`${HOME}/.openclaw/workspace` cho mount workspace), hoặc `/tmp/.openclaw` khi chính `HOME` cũng bị thiếu. Điều đó giúp `docker compose up` không -phát ra spec volume nguồn rỗng trên các môi trường tối thiểu. +phát ra spec volume có source trống trong các môi trường tối giản. -Thư mục cấu hình được mount đó là nơi OpenClaw lưu: +Thư mục cấu hình đã mount đó là nơi OpenClaw lưu: - `openclaw.json` cho cấu hình hành vi -- `agents//agent/auth-profiles.json` cho xác thực OAuth/API-key đã lưu của nhà cung cấp +- `agents//agent/auth-profiles.json` cho xác thực OAuth/API-key của nhà cung cấp đã lưu - `.env` cho các bí mật runtime dựa trên env như `OPENCLAW_GATEWAY_TOKEN` -Các Plugin có thể tải xuống đã cài đặt lưu trạng thái package của chúng dưới thư mục home OpenClaw -được mount, nên bản ghi cài đặt Plugin và gốc package vẫn tồn tại sau khi -thay thế container. Quá trình khởi động Gateway không tạo cây dependency cho Plugin được bundle. +Các Plugin tải xuống đã cài đặt lưu trạng thái package của chúng trong OpenClaw home đã mount, +nên bản ghi cài đặt Plugin và gốc package vẫn tồn tại sau khi thay thế container. +Khởi động Gateway không tạo cây phụ thuộc cho Plugin đi kèm. -Để biết đầy đủ chi tiết duy trì dữ liệu trên triển khai VM, xem +Để biết đầy đủ chi tiết duy trì dữ liệu trên các triển khai VM, xem [Docker VM Runtime - Nội dung nào được duy trì ở đâu](/vi/install/docker-vm-runtime#what-persists-where). **Điểm nóng tăng dung lượng đĩa:** theo dõi `media/`, các tệp JSONL phiên, -`cron/runs/*.jsonl`, thư mục gốc gói Plugin đã cài đặt, và nhật ký tệp luân phiên +`cron/runs/*.jsonl`, thư mục gốc của các gói Plugin đã cài đặt, và log tệp luân phiên trong `/tmp/openclaw/`. ### Trình trợ giúp shell (tùy chọn) @@ -297,20 +297,20 @@ mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/open echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -Nếu bạn đã cài ClawDock từ đường dẫn raw cũ `scripts/shell-helpers/clawdock-helpers.sh`, hãy chạy lại lệnh cài đặt ở trên để tệp trợ giúp cục bộ của bạn theo dõi vị trí mới. +Nếu bạn đã cài ClawDock từ đường dẫn raw cũ `scripts/shell-helpers/clawdock-helpers.sh`, hãy chạy lại lệnh cài đặt ở trên để tệp trợ giúp cục bộ của bạn theo vị trí mới. Sau đó dùng `clawdock-start`, `clawdock-stop`, `clawdock-dashboard`, v.v. Chạy `clawdock-help` để xem tất cả lệnh. Xem [ClawDock](/vi/install/clawdock) để đọc hướng dẫn đầy đủ về trình trợ giúp. - + ```bash export OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh ``` - Đường dẫn socket tùy chỉnh (ví dụ: Docker không root): + Đường dẫn socket tùy chỉnh (ví dụ Docker rootless): ```bash export OPENCLAW_SANDBOX=1 @@ -318,8 +318,8 @@ Xem [ClawDock](/vi/install/clawdock) để đọc hướng dẫn đầy đủ v ./scripts/docker/setup.sh ``` - Tập lệnh chỉ gắn kết `docker.sock` sau khi các điều kiện tiên quyết của hộp cát đạt. Nếu - quá trình thiết lập hộp cát không thể hoàn tất, tập lệnh đặt lại `agents.defaults.sandbox.mode` + Tập lệnh chỉ mount `docker.sock` sau khi các điều kiện tiên quyết của sandbox đạt. Nếu + thiết lập sandbox không thể hoàn tất, tập lệnh đặt lại `agents.defaults.sandbox.mode` về `off`. @@ -336,14 +336,14 @@ Xem [ClawDock](/vi/install/clawdock) để đọc hướng dẫn đầy đủ v `openclaw-cli` dùng `network_mode: "service:openclaw-gateway"` để các lệnh CLI - có thể truy cập Gateway qua `127.0.0.1`. Hãy coi đây là một ranh giới tin cậy - dùng chung. Cấu hình compose loại bỏ `NET_RAW`/`NET_ADMIN` và bật - `no-new-privileges` trên `openclaw-cli`. + có thể truy cập Gateway qua `127.0.0.1`. Hãy xem đây là một ranh giới tin cậy + dùng chung. Cấu hình compose bỏ `NET_RAW`/`NET_ADMIN` và bật + `no-new-privileges` trên cả `openclaw-gateway` và `openclaw-cli`. Image chạy dưới dạng `node` (uid 1000). Nếu bạn thấy lỗi quyền trên - `/home/node/.openclaw`, hãy đảm bảo các bind mount của máy chủ thuộc sở hữu của uid 1000: + `/home/node/.openclaw`, hãy bảo đảm các bind mount của máy chủ thuộc sở hữu uid 1000: ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -351,8 +351,8 @@ Xem [ClawDock](/vi/install/clawdock) để đọc hướng dẫn đầy đủ v - - Sắp xếp Dockerfile để các lớp phụ thuộc được lưu vào bộ nhớ đệm. Điều này tránh chạy lại + + Sắp xếp Dockerfile để các layer phụ thuộc được lưu cache. Việc này tránh chạy lại `pnpm install` trừ khi lockfile thay đổi: ```dockerfile @@ -392,18 +392,18 @@ Xem [ClawDock](/vi/install/clawdock) để đọc hướng dẫn đầy đủ v - + Nếu bạn chọn OpenAI Codex OAuth trong trình hướng dẫn, nó sẽ mở một URL trình duyệt. Trong - Docker hoặc thiết lập headless, hãy sao chép URL chuyển hướng đầy đủ bạn nhận được và dán + Docker hoặc thiết lập không giao diện, hãy sao chép URL chuyển hướng đầy đủ mà bạn truy cập đến và dán lại vào trình hướng dẫn để hoàn tất xác thực. - - Image runtime Docker chính dùng `node:24-bookworm-slim` và phát hành chú thích OCI - cho image cơ sở, bao gồm `org.opencontainers.image.base.name`, - `org.opencontainers.image.source`, và các chú thích khác. Digest cơ sở Node được - làm mới qua các PR image cơ sở Docker của Dependabot; bản dựng phát hành không chạy - lớp nâng cấp bản phân phối. Xem + + Image runtime Docker chính dùng `node:24-bookworm-slim` và xuất bản chú thích OCI + cho image nền tảng, bao gồm `org.opencontainers.image.base.name`, + `org.opencontainers.image.source`, và các chú thích khác. Digest của Node base được + làm mới qua các PR Dependabot Docker base-image; bản build phát hành không chạy + layer nâng cấp distro. Xem [chú thích image OCI](https://github.com/opencontainers/image-spec/blob/main/annotations.md). @@ -414,24 +414,24 @@ Xem [Hetzner (Docker VPS)](/vi/install/hetzner) và [Docker VM Runtime](/vi/install/docker-vm-runtime) để biết các bước triển khai VM dùng chung, bao gồm đóng gói binary, duy trì dữ liệu, và cập nhật. -## Hộp cát tác nhân +## Sandbox tác tử Khi `agents.defaults.sandbox` được bật với backend Docker, Gateway -chạy thực thi công cụ của tác nhân (shell, đọc/ghi tệp, v.v.) bên trong các container Docker -cô lập trong khi bản thân Gateway vẫn ở trên máy chủ. Điều này tạo một bức tường cứng -quanh các phiên tác nhân không tin cậy hoặc đa tenant mà không cần container hóa toàn bộ +chạy việc thực thi công cụ của tác tử (shell, đọc/ghi tệp, v.v.) bên trong các container Docker +cô lập, trong khi bản thân Gateway vẫn ở trên máy chủ. Điều này tạo cho bạn một bức tường cứng +bao quanh các phiên tác tử không tin cậy hoặc đa bên thuê mà không cần container hóa toàn bộ Gateway. -Phạm vi hộp cát có thể theo từng tác nhân (mặc định), theo từng phiên, hoặc dùng chung. Mỗi phạm vi -có workspace riêng được gắn kết tại `/workspace`. Bạn cũng có thể cấu hình -chính sách công cụ cho phép/từ chối, cô lập mạng, giới hạn tài nguyên, và container -trình duyệt. +Phạm vi sandbox có thể là theo tác tử (mặc định), theo phiên, hoặc dùng chung. Mỗi phạm vi +có workspace riêng được mount tại `/workspace`. Bạn cũng có thể cấu hình +chính sách cho phép/từ chối công cụ, cô lập mạng, giới hạn tài nguyên, và +container trình duyệt. -Để xem cấu hình đầy đủ, image, ghi chú bảo mật, và hồ sơ đa tác nhân, xem: +Để xem cấu hình đầy đủ, image, ghi chú bảo mật, và hồ sơ đa tác tử, xem: -- [Hộp cát](/vi/gateway/sandboxing) -- tài liệu tham khảo đầy đủ về hộp cát -- [OpenShell](/vi/gateway/openshell) -- quyền truy cập shell tương tác vào container hộp cát -- [Hộp cát và công cụ đa tác nhân](/vi/tools/multi-agent-sandbox-tools) -- ghi đè theo từng tác nhân +- [Sandboxing](/vi/gateway/sandboxing) -- tham chiếu sandbox đầy đủ +- [OpenShell](/vi/gateway/openshell) -- truy cập shell tương tác vào container sandbox +- [Multi-Agent Sandbox and Tools](/vi/tools/multi-agent-sandbox-tools) -- ghi đè theo tác tử ### Bật nhanh @@ -448,41 +448,41 @@ trình duyệt. } ``` -Dựng image hộp cát mặc định (từ checkout mã nguồn): +Build image sandbox mặc định (từ checkout mã nguồn): ```bash scripts/sandbox-setup.sh ``` -Đối với cài đặt npm không có checkout mã nguồn, xem [Hộp cát § Image và thiết lập](/vi/gateway/sandboxing#images-and-setup) để biết các lệnh `docker build` inline. +Với bản cài npm không có checkout mã nguồn, xem [Sandboxing § Image và thiết lập](/vi/gateway/sandboxing#images-and-setup) để biết các lệnh `docker build` nội tuyến. ## Khắc phục sự cố - - Dựng image hộp cát bằng + + Build image sandbox bằng [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) - (checkout mã nguồn) hoặc lệnh `docker build` inline từ [Hộp cát § Image và thiết lập](/vi/gateway/sandboxing#images-and-setup) (cài đặt npm), + (checkout mã nguồn) hoặc lệnh `docker build` nội tuyến từ [Sandboxing § Image và thiết lập](/vi/gateway/sandboxing#images-and-setup) (cài đặt npm), hoặc đặt `agents.defaults.sandbox.docker.image` thành image tùy chỉnh của bạn. - Container được tự động tạo theo từng phiên khi cần. + Container được tự động tạo theo phiên khi cần. - - Đặt `docker.user` thành UID:GID khớp với quyền sở hữu workspace đã gắn kết của bạn, + + Đặt `docker.user` thành UID:GID khớp với quyền sở hữu workspace đã mount của bạn, hoặc chown thư mục workspace. - - OpenClaw chạy lệnh bằng `sh -lc` (login shell), nguồn từ + + OpenClaw chạy lệnh bằng `sh -lc` (login shell), nguồn hóa `/etc/profile` và có thể đặt lại PATH. Đặt `docker.env.PATH` để thêm trước các - đường dẫn công cụ tùy chỉnh của bạn, hoặc thêm tập lệnh trong `/etc/profile.d/` trong Dockerfile của bạn. + đường dẫn công cụ tùy chỉnh của bạn, hoặc thêm một tập lệnh trong `/etc/profile.d/` trong Dockerfile của bạn. - - VM cần ít nhất 2 GB RAM. Dùng lớp máy lớn hơn và thử lại. + + VM cần ít nhất 2 GB RAM. Dùng một lớp máy lớn hơn và thử lại. - + Lấy liên kết dashboard mới và phê duyệt thiết bị trình duyệt: ```bash @@ -491,12 +491,12 @@ scripts/sandbox-setup.sh docker compose run --rm openclaw-cli devices approve ``` - Chi tiết hơn: [Dashboard](/vi/web/dashboard), [Thiết bị](/vi/cli/devices). + Chi tiết hơn: [Dashboard](/vi/web/dashboard), [Devices](/vi/cli/devices). - - Đặt lại chế độ Gateway và bind: + + Đặt lại chế độ và bind của Gateway: ```bash docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]' @@ -509,7 +509,7 @@ scripts/sandbox-setup.sh ## Liên quan - [Tổng quan cài đặt](/vi/install) — tất cả phương thức cài đặt -- [Podman](/vi/install/podman) — lựa chọn thay thế Docker bằng Podman +- [Podman](/vi/install/podman) — lựa chọn thay thế Podman cho Docker - [ClawDock](/vi/install/clawdock) — thiết lập cộng đồng Docker Compose - [Cập nhật](/vi/install/updating) — giữ OpenClaw luôn cập nhật - [Cấu hình](/vi/gateway/configuration) — cấu hình Gateway sau khi cài đặt diff --git a/docs/vi/reference/session-management-compaction.md b/docs/vi/reference/session-management-compaction.md index 025832784..871d5e8fa 100644 --- a/docs/vi/reference/session-management-compaction.md +++ b/docs/vi/reference/session-management-compaction.md @@ -1,30 +1,30 @@ --- read_when: - - Bạn cần gỡ lỗi ID phiên, JSONL bản ghi hội thoại hoặc các trường sessions.json - - Bạn đang thay đổi hành vi tự động Compaction hoặc thêm tác vụ dọn dẹp “trước Compaction” - - Bạn muốn triển khai cơ chế xả bộ nhớ hoặc các lượt hệ thống im lặng -summary: 'Tìm hiểu chuyên sâu: kho lưu trữ phiên + bản ghi hội thoại, vòng đời và cơ chế nội bộ của Compaction (tự động)' + - Bạn cần gỡ lỗi mã định danh phiên, JSONL bản ghi hội thoại hoặc các trường sessions.json + - Bạn đang thay đổi hành vi Compaction tự động hoặc thêm công việc dọn dẹp “trước Compaction” + - Bạn muốn triển khai việc xả bộ nhớ hoặc các lượt hệ thống im lặng +summary: 'Chuyên sâu: kho lưu phiên + bản ghi phiên, vòng đời và cơ chế nội bộ của Compaction (tự động)' title: Tìm hiểu chuyên sâu về quản lý phiên x-i18n: - generated_at: "2026-05-02T20:57:29Z" + generated_at: "2026-05-05T08:26:27Z" model: gpt-5.5 provider: openai - source_hash: 8271d7b0786e1c47a8cec6e7bd73c3c86a433d629e17937fdd87fa756ed78d73 + source_hash: 3161dd9c98bff7ea24266f44a9261693d8a9ee2b47d9af2d152de7057016748b source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw quản lý các phiên từ đầu đến cuối trên các khu vực sau: +OpenClaw quản lý phiên từ đầu đến cuối trên các khu vực sau: - **Định tuyến phiên** (cách thông điệp đến ánh xạ tới một `sessionKey`) - **Kho phiên** (`sessions.json`) và những gì nó theo dõi - **Lưu bền transcript** (`*.jsonl`) và cấu trúc của nó -- **Vệ sinh transcript** (các điều chỉnh theo từng nhà cung cấp trước khi chạy) +- **Vệ sinh transcript** (các chỉnh sửa riêng theo provider trước khi chạy) - **Giới hạn ngữ cảnh** (cửa sổ ngữ cảnh so với token được theo dõi) -- **Compaction** (Compaction thủ công và tự động) và nơi hook công việc trước Compaction -- **Dọn dẹp âm thầm** (ghi bộ nhớ không nên tạo đầu ra hiển thị cho người dùng) +- **Compaction** (Compaction thủ công và tự động) và nơi móc công việc trước Compaction +- **Dọn dẹp ngầm** (các lần ghi bộ nhớ không nên tạo đầu ra hiển thị cho người dùng) -Nếu bạn muốn xem tổng quan cấp cao trước, hãy bắt đầu với: +Nếu bạn muốn xem tổng quan cấp cao hơn trước, hãy bắt đầu với: - [Quản lý phiên](/vi/concepts/session) - [Compaction](/vi/concepts/compaction) @@ -39,8 +39,8 @@ Nếu bạn muốn xem tổng quan cấp cao trước, hãy bắt đầu với: OpenClaw được thiết kế xoay quanh một **tiến trình Gateway** duy nhất sở hữu trạng thái phiên. -- Các UI (ứng dụng macOS, web Control UI, TUI) nên truy vấn Gateway để lấy danh sách phiên và số lượng token. -- Ở chế độ từ xa, các tệp phiên nằm trên máy chủ từ xa; “kiểm tra các tệp cục bộ trên máy Mac của bạn” sẽ không phản ánh những gì Gateway đang dùng. +- UI (ứng dụng macOS, Control UI trên web, TUI) nên truy vấn Gateway để lấy danh sách phiên và số lượng token. +- Ở chế độ từ xa, các tệp phiên nằm trên máy chủ từ xa; “kiểm tra các tệp Mac cục bộ của bạn” sẽ không phản ánh những gì Gateway đang sử dụng. --- @@ -51,21 +51,21 @@ OpenClaw lưu bền phiên trong hai lớp: 1. **Kho phiên (`sessions.json`)** - Bản đồ khóa/giá trị: `sessionKey -> SessionEntry` - Nhỏ, có thể thay đổi, an toàn để chỉnh sửa (hoặc xóa mục) - - Theo dõi siêu dữ liệu phiên (id phiên hiện tại, hoạt động gần nhất, công tắc, bộ đếm token, v.v.) + - Theo dõi siêu dữ liệu phiên (id phiên hiện tại, hoạt động cuối, các bật/tắt, bộ đếm token, v.v.) 2. **Transcript (`.jsonl`)** - - Transcript chỉ ghi thêm với cấu trúc cây (các mục có `id` + `parentId`) + - Transcript chỉ ghi nối tiếp với cấu trúc cây (các mục có `id` + `parentId`) - Lưu cuộc trò chuyện thực tế + lệnh gọi công cụ + tóm tắt Compaction - - Được dùng để xây dựng lại ngữ cảnh mô hình cho các lượt sau - - Các checkpoint gỡ lỗi lớn trước Compaction sẽ bị bỏ qua khi transcript - đang hoạt động vượt quá giới hạn kích thước checkpoint, tránh tạo thêm một bản sao + - Được dùng để dựng lại ngữ cảnh mô hình cho các lượt sau + - Các checkpoint gỡ lỗi lớn trước Compaction được bỏ qua khi transcript + đang hoạt động vượt quá giới hạn kích thước checkpoint, tránh tạo bản sao `.checkpoint.*.jsonl` khổng lồ thứ hai. -Trình đọc lịch sử Gateway nên tránh vật chất hóa toàn bộ transcript trừ khi -bề mặt đó cần truy cập lịch sử tùy ý một cách rõ ràng. Lịch sử trang đầu, -lịch sử trò chuyện nhúng, khôi phục khi khởi động lại, và kiểm tra token/mức dùng dùng các lượt đọc đuôi có giới hạn. -Các lượt quét transcript đầy đủ đi qua chỉ mục transcript bất đồng bộ, được -lưu cache theo đường dẫn tệp cộng với `mtimeMs`/`size` và được chia sẻ giữa các trình đọc đồng thời. +Các bộ đọc lịch sử Gateway nên tránh nạp toàn bộ transcript vào bộ nhớ trừ khi +bề mặt đó thật sự cần truy cập lịch sử tùy ý. Lịch sử trang đầu, lịch sử chat +nhúng, khôi phục khi khởi động lại, và kiểm tra token/mức dùng sử dụng các lần +đọc phần đuôi có giới hạn. Quét toàn bộ transcript đi qua chỉ mục transcript bất đồng bộ, được +lưu cache theo đường dẫn tệp cộng với `mtimeMs`/`size` và dùng chung giữa các bộ đọc đồng thời. --- @@ -77,42 +77,42 @@ Theo từng agent, trên máy chủ Gateway: - Transcript: `~/.openclaw/agents//sessions/.jsonl` - Phiên chủ đề Telegram: `.../-topic-.jsonl` -OpenClaw phân giải các đường dẫn này qua `src/config/sessions.ts`. +OpenClaw phân giải các vị trí này qua `src/config/sessions.ts`. --- ## Bảo trì kho và kiểm soát đĩa -Lưu bền phiên có các kiểm soát bảo trì tự động (`session.maintenance`) cho `sessions.json`, hiện vật transcript, và sidecar quỹ đạo: +Lưu bền phiên có các kiểm soát bảo trì tự động (`session.maintenance`) cho `sessions.json`, artifact transcript, và sidecar trajectory: - `mode`: `warn` (mặc định) hoặc `enforce` -- `pruneAfter`: ngưỡng tuổi mục cũ (mặc định `30d`) +- `pruneAfter`: ngưỡng tuổi cho mục cũ (mặc định `30d`) - `maxEntries`: giới hạn số mục trong `sessions.json` (mặc định `500`) - `resetArchiveRetention`: thời gian giữ lại cho kho lưu trữ transcript `*.reset.` (mặc định: giống `pruneAfter`; `false` tắt dọn dẹp) -- `maxDiskBytes`: ngân sách tùy chọn cho thư mục phiên +- `maxDiskBytes`: ngân sách thư mục phiên tùy chọn - `highWaterBytes`: mục tiêu tùy chọn sau khi dọn dẹp (mặc định `80%` của `maxDiskBytes`) -Các lượt ghi Gateway thông thường đi qua một bộ ghi phiên theo từng kho, tuần tự hóa các thay đổi trong tiến trình mà không lấy khóa tệp runtime. Các helper vá trên đường nóng mượn cache có thể thay đổi đã được xác thực trong khi giữ slot bộ ghi đó, nên các tệp `sessions.json` lớn không bị clone hoặc đọc lại cho mọi lần cập nhật siêu dữ liệu. Mã runtime nên ưu tiên `updateSessionStore(...)` hoặc `updateSessionStoreEntry(...)`; lưu toàn bộ kho trực tiếp là công cụ tương thích và bảo trì ngoại tuyến. Khi có thể truy cập Gateway, `openclaw sessions cleanup` và `openclaw agents delete` không chạy dry-run sẽ ủy nhiệm thay đổi kho cho Gateway để quá trình dọn dẹp tham gia cùng hàng đợi bộ ghi; `--store ` là đường dẫn sửa chữa ngoại tuyến rõ ràng cho bảo trì tệp trực tiếp. Dọn dẹp `maxEntries` vẫn được gom lô cho các giới hạn cỡ sản xuất, nên kho có thể tạm thời vượt quá giới hạn đã cấu hình trước khi lần dọn dẹp ngưỡng cao tiếp theo ghi lại để giảm xuống. Các lượt đọc kho phiên không cắt tỉa hoặc giới hạn mục trong lúc Gateway khởi động; dùng các lượt ghi hoặc `openclaw sessions cleanup --enforce` để dọn dẹp. `openclaw sessions cleanup --enforce` vẫn áp dụng giới hạn đã cấu hình ngay lập tức. +Các lần ghi Gateway thông thường đi qua một bộ ghi phiên theo từng kho, tuần tự hóa các thay đổi trong tiến trình mà không cần khóa tệp runtime. Các helper vá trên đường nóng mượn cache có thể thay đổi đã được xác thực trong khi giữ slot ghi đó, nên các tệp `sessions.json` lớn không bị sao chép hoặc đọc lại cho mọi lần cập nhật siêu dữ liệu. Mã runtime nên ưu tiên `updateSessionStore(...)` hoặc `updateSessionStoreEntry(...)`; lưu toàn bộ kho trực tiếp là công cụ tương thích và bảo trì ngoại tuyến. Khi có thể truy cập Gateway, `openclaw sessions cleanup` không phải dry run và `openclaw agents delete` ủy quyền các thay đổi kho cho Gateway để việc dọn dẹp tham gia cùng hàng đợi ghi; `--store ` là đường sửa chữa ngoại tuyến tường minh cho bảo trì tệp trực tiếp. Dọn dẹp `maxEntries` vẫn được gom lô cho các giới hạn cỡ production, nên một kho có thể tạm thời vượt quá giới hạn đã cấu hình trước khi lần dọn dẹp high-water tiếp theo ghi lại nó xuống thấp hơn. Các lần đọc kho phiên không cắt tỉa hoặc giới hạn mục trong lúc Gateway khởi động; hãy dùng các lần ghi hoặc `openclaw sessions cleanup --enforce` để dọn dẹp. `openclaw sessions cleanup --enforce` vẫn áp dụng giới hạn đã cấu hình ngay lập tức và cắt tỉa các artifact transcript, checkpoint, và trajectory cũ không còn được tham chiếu ngay cả khi không cấu hình ngân sách đĩa. -Bảo trì giữ lại các con trỏ hội thoại ngoài bền vững như phiên nhóm -và phiên trò chuyện theo thread, nhưng các mục runtime tổng hợp cho cron, hook, -Heartbeat, ACP, và sub-agent vẫn có thể bị xóa khi chúng vượt quá -tuổi, số lượng, hoặc ngân sách đĩa đã cấu hình. +Bảo trì giữ các con trỏ cuộc trò chuyện bên ngoài bền vững như phiên nhóm +và phiên chat theo phạm vi luồng, nhưng các mục runtime tổng hợp cho cron, hook, +heartbeat, ACP, và sub-agent vẫn có thể bị xóa khi vượt quá tuổi, +số lượng, hoặc ngân sách đĩa đã cấu hình. -OpenClaw không còn tạo các bản sao lưu xoay vòng `sessions.json.bak.*` tự động trong các lượt ghi Gateway. Khóa `session.maintenance.rotateBytes` cũ bị bỏ qua và `openclaw doctor --fix` xóa nó khỏi các cấu hình cũ. +OpenClaw không còn tạo các bản sao lưu xoay vòng `sessions.json.bak.*` tự động trong các lần ghi Gateway. Khóa `session.maintenance.rotateBytes` cũ bị bỏ qua và `openclaw doctor --fix` xóa nó khỏi cấu hình cũ. -Các thay đổi transcript dùng khóa ghi phiên trên tệp transcript. Việc lấy khóa chờ tối đa -`session.writeLock.acquireTimeoutMs` trước khi hiển thị lỗi phiên bận; mặc định là `60000` -ms. Chỉ tăng giá trị này khi công việc chuẩn bị, dọn dẹp, Compaction, hoặc phản chiếu transcript hợp lệ tranh chấp -lâu hơn trên máy chậm. Phát hiện khóa cũ và cảnh báo thời gian giữ tối đa vẫn là các chính sách riêng biệt. +Các thay đổi transcript dùng một khóa ghi phiên trên tệp transcript. Việc lấy khóa chờ tối đa +`session.writeLock.acquireTimeoutMs` trước khi báo lỗi phiên bận; mặc định là `60000` +ms. Chỉ tăng giá trị này khi các công việc chuẩn bị, dọn dẹp, Compaction, hoặc mirror transcript hợp lệ tranh chấp +lâu hơn trên máy chậm. Phát hiện khóa cũ và cảnh báo thời gian giữ tối đa vẫn là các chính sách riêng. Thứ tự thực thi khi dọn dẹp ngân sách đĩa (`mode: "enforce"`): -1. Xóa hiện vật lưu trữ cũ nhất, transcript mồ côi, hoặc quỹ đạo mồ côi trước. -2. Nếu vẫn cao hơn mục tiêu, loại bỏ các mục phiên cũ nhất và tệp transcript/quỹ đạo của chúng. +1. Xóa các artifact đã lưu trữ, transcript mồ côi, hoặc trajectory mồ côi cũ nhất trước. +2. Nếu vẫn vượt mục tiêu, loại bỏ các mục phiên cũ nhất và các tệp transcript/trajectory của chúng. 3. Tiếp tục cho đến khi mức dùng bằng hoặc thấp hơn `highWaterBytes`. -Trong `mode: "warn"`, OpenClaw báo cáo các lượt loại bỏ tiềm năng nhưng không thay đổi kho/tệp. +Trong `mode: "warn"`, OpenClaw báo cáo các trường hợp có thể bị loại bỏ nhưng không thay đổi kho/tệp. Chạy bảo trì theo yêu cầu: @@ -125,34 +125,34 @@ openclaw sessions cleanup --enforce ## Phiên Cron và nhật ký chạy -Các lần chạy cron cô lập cũng tạo mục phiên/transcript, và chúng có các kiểm soát giữ lại riêng: +Các lần chạy cron cô lập cũng tạo mục phiên/transcript, và chúng có kiểm soát lưu giữ riêng: - `cron.sessionRetention` (mặc định `24h`) cắt tỉa các phiên chạy cron cô lập cũ khỏi kho phiên (`false` tắt). - `cron.runLog.maxBytes` + `cron.runLog.keepLines` cắt tỉa các tệp `~/.openclaw/cron/runs/.jsonl` (mặc định: `2_000_000` byte và `2000` dòng). Khi cron buộc tạo một phiên chạy cô lập mới, nó làm sạch mục phiên `cron:` trước đó trước khi ghi hàng mới. Nó mang theo các tùy chọn an toàn -như thiết lập suy nghĩ/nhanh/chi tiết, nhãn, và các override mô hình/xác thực do -người dùng chọn rõ ràng. Nó bỏ ngữ cảnh hội thoại xung quanh như -định tuyến kênh/nhóm, chính sách gửi hoặc hàng đợi, nâng quyền, nguồn gốc, và ràng buộc runtime ACP -để một lần chạy cô lập mới không thể thừa hưởng quyền gửi hoặc -runtime đã cũ từ một lần chạy cũ hơn. +như thiết lập thinking/fast/verbose, nhãn, và các ghi đè model/auth do người dùng +chọn tường minh. Nó bỏ ngữ cảnh cuộc trò chuyện môi trường như định tuyến +channel/group, chính sách gửi hoặc xếp hàng, elevation, origin, và ràng buộc runtime ACP +để một lần chạy cô lập mới không thể kế thừa quyền phân phối hoặc runtime cũ +từ một lần chạy trước. --- ## Khóa phiên (`sessionKey`) -`sessionKey` xác định _bạn đang ở bucket hội thoại nào_ (định tuyến + cô lập). +Một `sessionKey` xác định _bạn đang ở trong bucket cuộc trò chuyện nào_ (định tuyến + cô lập). Các mẫu phổ biến: -- Trò chuyện chính/trực tiếp (theo agent): `agent::` (mặc định `main`) +- Chat chính/trực tiếp (theo agent): `agent::` (mặc định `main`) - Nhóm: `agent:::group:` -- Phòng/kênh (Discord/Slack): `agent:::channel:` hoặc `...:room:` +- Phòng/channel (Discord/Slack): `agent:::channel:` hoặc `...:room:` - Cron: `cron:` - Webhook: `hook:` (trừ khi bị ghi đè) -Các quy tắc chuẩn được ghi lại tại [/concepts/session](/vi/concepts/session). +Các quy tắc chuẩn được ghi tại [/concepts/session](/vi/concepts/session). --- @@ -163,12 +163,12 @@ Mỗi `sessionKey` trỏ tới một `sessionId` hiện tại (tệp transcript Quy tắc kinh nghiệm: - **Đặt lại** (`/new`, `/reset`) tạo một `sessionId` mới cho `sessionKey` đó. -- **Đặt lại hằng ngày** (mặc định 4:00 sáng giờ cục bộ trên máy chủ Gateway) tạo một `sessionId` mới ở thông điệp tiếp theo sau ranh giới đặt lại. -- **Hết hạn do nhàn rỗi** (`session.reset.idleMinutes` hoặc `session.idleMinutes` cũ) tạo một `sessionId` mới khi có thông điệp đến sau cửa sổ nhàn rỗi. Khi cả hằng ngày + nhàn rỗi đều được cấu hình, cái nào hết hạn trước sẽ thắng. -- **Sự kiện hệ thống** (Heartbeat, đánh thức cron, thông báo exec, ghi chép sổ sách Gateway) có thể thay đổi hàng phiên nhưng không kéo dài độ mới của đặt lại hằng ngày/nhàn rỗi. Rollover đặt lại loại bỏ các thông báo sự kiện hệ thống đã xếp hàng cho phiên trước trước khi prompt mới được xây dựng. -- **Chính sách fork cha** dùng nhánh đang hoạt động của PI khi tạo một thread hoặc fork subagent. Nếu nhánh đó quá lớn, OpenClaw bắt đầu child với ngữ cảnh cô lập thay vì thất bại hoặc thừa hưởng lịch sử không dùng được. Chính sách định cỡ là tự động; cấu hình cũ `session.parentForkMaxTokens` bị `openclaw doctor --fix` xóa. +- **Đặt lại hằng ngày** (mặc định 4:00 sáng giờ địa phương trên máy chủ gateway) tạo một `sessionId` mới ở thông điệp tiếp theo sau ranh giới đặt lại. +- **Hết hạn do nhàn rỗi** (`session.reset.idleMinutes` hoặc `session.idleMinutes` cũ) tạo một `sessionId` mới khi có thông điệp đến sau cửa sổ nhàn rỗi. Khi cả đặt lại hằng ngày và nhàn rỗi đều được cấu hình, mục nào hết hạn trước sẽ thắng. +- **Sự kiện hệ thống** (heartbeat, đánh thức cron, thông báo exec, bookkeeping gateway) có thể thay đổi hàng phiên nhưng không kéo dài độ mới cho đặt lại hằng ngày/nhàn rỗi. Chuyển phiên đặt lại loại bỏ các thông báo sự kiện hệ thống đã xếp hàng cho phiên trước trước khi prompt mới được dựng. +- **Chính sách fork cha** dùng nhánh đang hoạt động của PI khi tạo một luồng hoặc fork subagent. Nếu nhánh đó quá lớn, OpenClaw khởi động con với ngữ cảnh cô lập thay vì thất bại hoặc kế thừa lịch sử không dùng được. Chính sách định cỡ là tự động; cấu hình `session.parentForkMaxTokens` cũ được `openclaw doctor --fix` xóa. -Chi tiết triển khai: quyết định diễn ra trong `initSessionState()` ở `src/auto-reply/reply/session.ts`. +Chi tiết triển khai: quyết định diễn ra trong `initSessionState()` tại `src/auto-reply/reply/session.ts`. --- @@ -178,30 +178,30 @@ Kiểu giá trị của kho là `SessionEntry` trong `src/config/sessions.ts`. Các trường chính (không đầy đủ): -- `sessionId`: id transcript hiện tại (tên tệp được suy ra từ đây trừ khi `sessionFile` được đặt) -- `sessionStartedAt`: dấu thời gian bắt đầu cho `sessionId` hiện tại; độ mới của đặt lại hằng ngày +- `sessionId`: id transcript hiện tại (tên tệp được suy ra từ giá trị này trừ khi `sessionFile` được đặt) +- `sessionStartedAt`: timestamp bắt đầu cho `sessionId` hiện tại; độ mới của đặt lại hằng ngày dùng trường này. Các hàng cũ có thể suy ra nó từ header phiên JSONL. -- `lastInteractionAt`: dấu thời gian tương tác người dùng/kênh thực gần nhất; độ mới của đặt lại nhàn rỗi - dùng trường này để Heartbeat, cron, và sự kiện exec không giữ phiên - sống. Các hàng cũ không có trường này quay về thời gian bắt đầu phiên đã khôi phục +- `lastInteractionAt`: timestamp tương tác người dùng/channel thật gần nhất; độ mới của đặt lại do nhàn rỗi + dùng trường này để heartbeat, cron, và sự kiện exec không giữ phiên + còn sống. Các hàng cũ không có trường này fallback về thời gian bắt đầu phiên đã khôi phục cho độ mới nhàn rỗi. -- `updatedAt`: dấu thời gian thay đổi hàng kho gần nhất, dùng cho liệt kê, cắt tỉa, và - ghi chép sổ sách. Nó không phải nguồn thẩm quyền cho độ mới của đặt lại hằng ngày/nhàn rỗi. -- `sessionFile`: override đường dẫn transcript rõ ràng tùy chọn +- `updatedAt`: timestamp thay đổi hàng kho gần nhất, được dùng cho liệt kê, cắt tỉa, và + bookkeeping. Nó không phải nguồn thẩm quyền cho độ mới đặt lại hằng ngày/nhàn rỗi. +- `sessionFile`: ghi đè đường dẫn transcript tường minh tùy chọn - `chatType`: `direct | group | room` (giúp UI và chính sách gửi) -- `provider`, `subject`, `room`, `space`, `displayName`: siêu dữ liệu cho nhãn nhóm/kênh -- Công tắc: +- `provider`, `subject`, `room`, `space`, `displayName`: siêu dữ liệu để gắn nhãn nhóm/channel +- Bật/tắt: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - - `sendPolicy` (override theo phiên) + - `sendPolicy` (ghi đè theo phiên) - Chọn mô hình: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Bộ đếm token (nỗ lực tốt nhất / phụ thuộc nhà cung cấp): +- Bộ đếm token (nỗ lực tốt nhất / phụ thuộc provider): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: số lần tự động Compaction hoàn tất cho khóa phiên này -- `memoryFlushAt`: dấu thời gian cho lần flush bộ nhớ trước Compaction gần nhất +- `compactionCount`: số lần auto-compaction hoàn tất cho khóa phiên này +- `memoryFlushAt`: timestamp của lần flush bộ nhớ trước Compaction gần nhất - `memoryFlushCompactionCount`: số lần Compaction khi lần flush gần nhất chạy -Kho an toàn để chỉnh sửa, nhưng Gateway là nguồn thẩm quyền: nó có thể ghi lại hoặc tái cấp nước các mục khi phiên chạy. +Kho an toàn để chỉnh sửa, nhưng Gateway là nguồn thẩm quyền: nó có thể ghi lại hoặc tái hydrate các mục khi phiên chạy. --- @@ -211,68 +211,67 @@ Transcript được quản lý bởi `SessionManager` của `@mariozechner/pi-co Tệp là JSONL: -- Dòng đầu tiên: header phiên (`type: "session"`, bao gồm `id`, `cwd`, `timestamp`, `parentSession` tùy chọn) +- Dòng đầu tiên: header phiên (`type: "session"`, gồm `id`, `cwd`, `timestamp`, `parentSession` tùy chọn) - Sau đó: các mục phiên với `id` + `parentId` (cây) Các kiểu mục đáng chú ý: -- `message`: thông điệp người dùng/assistant/toolResult -- `custom_message`: thông điệp do extension chèn vào và _có_ đi vào ngữ cảnh mô hình (có thể bị ẩn khỏi UI) +- `message`: thông điệp user/assistant/toolResult +- `custom_message`: thông điệp do extension chèn vào và _có_ đi vào ngữ cảnh mô hình (có thể ẩn khỏi UI) - `custom`: trạng thái extension _không_ đi vào ngữ cảnh mô hình -- `compaction`: tóm tắt Compaction được lưu bền với `firstKeptEntryId` và `tokensBefore` -- `branch_summary`: tóm tắt được lưu bền khi điều hướng một nhánh cây +- `compaction`: tóm tắt Compaction đã lưu bền với `firstKeptEntryId` và `tokensBefore` +- `branch_summary`: tóm tắt đã lưu bền khi điều hướng một nhánh cây -OpenClaw cố ý **không** “sửa chữa” transcript; Gateway dùng `SessionManager` để đọc/ghi chúng. +OpenClaw cố ý **không** “sửa” transcript; Gateway dùng `SessionManager` để đọc/ghi chúng. --- ## Cửa sổ ngữ cảnh so với token được theo dõi -Hai khái niệm khác nhau là quan trọng: +Có hai khái niệm khác nhau quan trọng: -1. **Cửa sổ ngữ cảnh mô hình**: giới hạn cứng theo từng mô hình (token hiển thị với mô hình) +1. **Cửa sổ ngữ cảnh của mô hình**: giới hạn cứng theo từng mô hình (token hiển thị với mô hình) 2. **Bộ đếm kho phiên**: thống kê cuốn chiếu được ghi vào `sessions.json` (dùng cho /status và dashboard) Nếu bạn đang tinh chỉnh giới hạn: -- Cửa sổ ngữ cảnh đến từ catalog mô hình (và có thể bị override qua cấu hình). -- `contextTokens` trong kho là giá trị ước tính/báo cáo runtime; đừng xem nó như một bảo đảm nghiêm ngặt. +- Cửa sổ ngữ cảnh đến từ catalog mô hình (và có thể được ghi đè qua cấu hình). +- `contextTokens` trong kho là giá trị ước tính/báo cáo runtime; đừng xem nó là bảo đảm nghiêm ngặt. -Để biết thêm, xem [/token-use](/vi/reference/token-use). +Xem thêm tại [/token-use](/vi/reference/token-use). --- ## Compaction: nó là gì -Compaction tóm tắt hội thoại cũ hơn thành một mục `compaction` được lưu bền trong transcript và giữ nguyên các thông điệp gần đây. +Compaction tóm tắt cuộc trò chuyện cũ hơn thành một mục `compaction` đã lưu bền trong transcript và giữ nguyên các thông điệp gần đây. -Sau Compaction, các lượt tương lai thấy: +Sau Compaction, các lượt sau thấy: - Tóm tắt Compaction - Các thông điệp sau `firstKeptEntryId` -Compaction là **lưu bền** (khác với cắt tỉa phiên). Xem [/concepts/session-pruning](/vi/concepts/session-pruning). +Compaction là **bền vững** (không giống như cắt tỉa phiên). Xem [/concepts/session-pruning](/vi/concepts/session-pruning). ## Ranh giới đoạn Compaction và ghép cặp công cụ -Khi OpenClaw chia một bản chép dài thành các đoạn Compaction, nó giữ các lệnh gọi công cụ của trợ lý được ghép cặp với các mục `toolResult` tương ứng. +Khi OpenClaw chia một bản ghi dài thành các đoạn Compaction, nó giữ các lệnh gọi công cụ của assistant được ghép cặp với các mục `toolResult` tương ứng. -- Nếu điểm chia theo tỷ lệ token rơi vào giữa một lệnh gọi công cụ và kết quả của nó, OpenClaw sẽ dịch chuyển ranh giới đến thông điệp gọi công cụ của trợ lý thay vì tách cặp đó. -- Nếu một khối kết quả công cụ ở cuối nếu giữ nguyên sẽ làm đoạn vượt mục tiêu, OpenClaw bảo toàn khối công cụ đang chờ đó và giữ nguyên phần đuôi chưa được tóm tắt. -- Các khối gọi công cụ bị hủy/lỗi không giữ một điểm chia đang chờ mở. +- Nếu điểm chia theo tỷ lệ token rơi vào giữa một lệnh gọi công cụ và kết quả của nó, OpenClaw dịch ranh giới về thông điệp lệnh gọi công cụ của assistant thay vì tách cặp đó. +- Nếu một khối kết quả công cụ ở cuối nếu không sẽ đẩy đoạn vượt quá mục tiêu, OpenClaw giữ nguyên khối công cụ đang chờ đó và giữ nguyên phần đuôi chưa được tóm tắt. +- Các khối lệnh gọi công cụ bị hủy/lỗi không giữ một điểm chia đang chờ mở. --- -## Khi nào tự động Compaction xảy ra (runtime Pi) +## Khi tự động Compaction diễn ra (thời gian chạy Pi) -Trong agent Pi nhúng, tự động Compaction được kích hoạt trong hai trường hợp: +Trong tác nhân Pi nhúng, tự động Compaction kích hoạt trong hai trường hợp: -1. **Khôi phục khi tràn**: mô hình trả về lỗi tràn ngữ cảnh - (`request_too_large`, `context length exceeded`, `input exceeds the maximum +1. **Khôi phục tràn**: mô hình trả về lỗi tràn ngữ cảnh (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded`, và các biến thể tương tự theo dạng nhà cung cấp) → nén → thử lại. -2. **Duy trì theo ngưỡng**: sau một lượt thành công, khi: +exceeded`, và các biến thể tương tự theo dạng nhà cung cấp) → Compaction → thử lại. +2. **Duy trì ngưỡng**: sau một lượt thành công, khi: `contextTokens > contextWindow - reserveTokens` @@ -281,18 +280,18 @@ Trong đó: - `contextWindow` là cửa sổ ngữ cảnh của mô hình - `reserveTokens` là phần dự phòng dành cho prompt + đầu ra mô hình tiếp theo -Đây là ngữ nghĩa runtime Pi (OpenClaw tiêu thụ các sự kiện, nhưng Pi quyết định khi nào nén). +Đây là ngữ nghĩa thời gian chạy Pi (OpenClaw tiêu thụ các sự kiện, nhưng Pi quyết định khi nào Compaction). -OpenClaw cũng có thể kích hoạt Compaction cục bộ kiểm tra trước trước khi mở lượt chạy tiếp theo khi `agents.defaults.compaction.maxActiveTranscriptBytes` được đặt và tệp bản chép đang hoạt động đạt đến kích thước đó. Đây là một cơ chế bảo vệ theo kích thước tệp cho chi phí mở lại cục bộ, không phải lưu trữ thô: OpenClaw vẫn chạy Compaction ngữ nghĩa thông thường, và nó yêu cầu `truncateAfterCompaction` để bản tóm tắt đã nén có thể trở thành bản chép kế nhiệm mới. +OpenClaw cũng có thể kích hoạt Compaction cục bộ trước kiểm tra trước khi mở lượt chạy tiếp theo khi `agents.defaults.compaction.maxActiveTranscriptBytes` được đặt và tệp bản ghi đang hoạt động đạt kích thước đó. Đây là bộ bảo vệ kích thước tệp cho chi phí mở lại cục bộ, không phải lưu trữ thô: OpenClaw vẫn chạy Compaction ngữ nghĩa thông thường, và nó yêu cầu `truncateAfterCompaction` để bản tóm tắt đã Compaction có thể trở thành một bản ghi kế nhiệm mới. -Đối với các lượt chạy Pi nhúng, `agents.defaults.compaction.midTurnPrecheck.enabled: true` thêm một cơ chế bảo vệ vòng lặp công cụ tùy chọn. Sau khi một kết quả công cụ được thêm vào và trước lệnh gọi mô hình tiếp theo, OpenClaw ước tính áp lực prompt bằng cùng logic ngân sách kiểm tra trước được dùng ở đầu lượt. Nếu ngữ cảnh không còn vừa, cơ chế bảo vệ không nén bên trong hook `transformContext` của Pi. Nó phát một tín hiệu kiểm tra trước giữa lượt có cấu trúc, dừng lần gửi prompt hiện tại, và để vòng lặp chạy bên ngoài dùng đường khôi phục hiện có: cắt bớt kết quả công cụ quá lớn khi như vậy là đủ, hoặc kích hoạt chế độ Compaction đã cấu hình và thử lại. Tùy chọn này bị tắt theo mặc định và hoạt động với cả chế độ Compaction `default` và `safeguard`, bao gồm Compaction safeguard được hỗ trợ bởi nhà cung cấp. -Điều này độc lập với `maxActiveTranscriptBytes`: cơ chế bảo vệ theo kích thước byte chạy trước khi một lượt mở ra, trong khi kiểm tra trước giữa lượt chạy muộn hơn trong vòng lặp công cụ Pi nhúng sau khi các kết quả công cụ mới đã được thêm vào. +Đối với các lượt chạy Pi nhúng, `agents.defaults.compaction.midTurnPrecheck.enabled: true` thêm một bộ bảo vệ vòng lặp công cụ tùy chọn. Sau khi một kết quả công cụ được thêm vào và trước lệnh gọi mô hình tiếp theo, OpenClaw ước tính áp lực prompt bằng cùng logic ngân sách kiểm tra trước được dùng lúc bắt đầu lượt. Nếu ngữ cảnh không còn vừa, bộ bảo vệ không Compaction bên trong hook `transformContext` của Pi. Nó phát tín hiệu kiểm tra trước giữa lượt có cấu trúc, dừng lần gửi prompt hiện tại, và cho phép vòng lặp chạy bên ngoài dùng đường khôi phục hiện có: cắt ngắn các kết quả công cụ quá lớn khi như vậy là đủ, hoặc kích hoạt chế độ Compaction đã cấu hình và thử lại. Tùy chọn này bị tắt theo mặc định và hoạt động với cả chế độ Compaction `default` và `safeguard`, bao gồm Compaction bảo vệ dựa trên nhà cung cấp. +Điều này độc lập với `maxActiveTranscriptBytes`: bộ bảo vệ kích thước byte chạy trước khi một lượt mở ra, trong khi kiểm tra trước giữa lượt chạy muộn hơn trong vòng lặp công cụ Pi nhúng sau khi các kết quả công cụ mới đã được thêm vào. --- ## Cài đặt Compaction (`reserveTokens`, `keepRecentTokens`) -Cài đặt Compaction của Pi nằm trong cài đặt Pi: +Các cài đặt Compaction của Pi nằm trong cài đặt Pi: ```json5 { @@ -306,16 +305,16 @@ Cài đặt Compaction của Pi nằm trong cài đặt Pi: OpenClaw cũng áp dụng một mức sàn an toàn cho các lượt chạy nhúng: -- Nếu `compaction.reserveTokens < reserveTokensFloor`, OpenClaw sẽ tăng nó lên. +- Nếu `compaction.reserveTokens < reserveTokensFloor`, OpenClaw tăng nó lên. - Mức sàn mặc định là `20000` token. - Đặt `agents.defaults.compaction.reserveTokensFloor: 0` để tắt mức sàn. - Nếu nó đã cao hơn, OpenClaw giữ nguyên. -- `/compact` thủ công tôn trọng `agents.defaults.compaction.keepRecentTokens` rõ ràng và giữ điểm cắt phần đuôi gần đây của Pi. Nếu không có ngân sách giữ lại rõ ràng, Compaction thủ công vẫn là một checkpoint cứng và ngữ cảnh được dựng lại bắt đầu từ bản tóm tắt mới. -- Đặt `agents.defaults.compaction.midTurnPrecheck.enabled: true` để chạy kiểm tra trước vòng lặp công cụ tùy chọn sau các kết quả công cụ mới và trước lệnh gọi mô hình tiếp theo. Đây chỉ là một trigger; việc tạo bản tóm tắt vẫn dùng đường Compaction đã cấu hình. Nó độc lập với `maxActiveTranscriptBytes`, vốn là cơ chế bảo vệ theo kích thước byte của bản chép đang hoạt động ở đầu lượt. -- Đặt `agents.defaults.compaction.maxActiveTranscriptBytes` thành một giá trị byte hoặc chuỗi như `"20mb"` để chạy Compaction cục bộ trước một lượt khi bản chép đang hoạt động trở nên lớn. Cơ chế bảo vệ này chỉ hoạt động khi `truncateAfterCompaction` cũng được bật. Để trống hoặc đặt `0` để tắt. -- Khi `agents.defaults.compaction.truncateAfterCompaction` được bật, OpenClaw xoay vòng bản chép đang hoạt động sang JSONL kế nhiệm đã nén sau Compaction. Bản chép đầy đủ cũ vẫn được lưu trữ và liên kết từ checkpoint Compaction thay vì bị ghi lại tại chỗ. +- `/compact` thủ công tôn trọng `agents.defaults.compaction.keepRecentTokens` rõ ràng và giữ điểm cắt phần đuôi gần đây của Pi. Nếu không có ngân sách giữ lại rõ ràng, Compaction thủ công vẫn là một điểm kiểm tra cứng và ngữ cảnh được dựng lại bắt đầu từ bản tóm tắt mới. +- Đặt `agents.defaults.compaction.midTurnPrecheck.enabled: true` để chạy kiểm tra trước vòng lặp công cụ tùy chọn sau các kết quả công cụ mới và trước lệnh gọi mô hình tiếp theo. Đây chỉ là bộ kích hoạt; việc tạo bản tóm tắt vẫn dùng đường Compaction đã cấu hình. Nó độc lập với `maxActiveTranscriptBytes`, vốn là bộ bảo vệ kích thước byte của bản ghi đang hoạt động lúc bắt đầu lượt. +- Đặt `agents.defaults.compaction.maxActiveTranscriptBytes` thành một giá trị byte hoặc chuỗi như `"20mb"` để chạy Compaction cục bộ trước một lượt khi bản ghi đang hoạt động trở nên lớn. Bộ bảo vệ này chỉ hoạt động khi `truncateAfterCompaction` cũng được bật. Để không đặt hoặc đặt `0` để tắt. +- Khi `agents.defaults.compaction.truncateAfterCompaction` được bật, OpenClaw xoay bản ghi đang hoạt động sang một JSONL kế nhiệm đã Compaction sau khi Compaction. Bản ghi đầy đủ cũ vẫn được lưu trữ và liên kết từ điểm kiểm tra Compaction thay vì bị ghi đè tại chỗ. -Lý do: chừa đủ khoảng dự phòng cho “công việc duy trì” nhiều lượt (như ghi bộ nhớ) trước khi Compaction trở nên không thể tránh khỏi. +Lý do: chừa đủ khoảng trống cho “việc dọn dẹp” nhiều lượt (như ghi bộ nhớ) trước khi Compaction trở nên không thể tránh khỏi. Triển khai: `ensurePiCompactionReserveTokens()` trong `src/agents/pi-settings.ts` (được gọi từ `src/agents/pi-embedded-runner.ts`). @@ -324,58 +323,58 @@ Triển khai: `ensurePiCompactionReserveTokens()` trong `src/agents/pi-settings. ## Nhà cung cấp Compaction có thể cắm được -Các Plugin có thể đăng ký một nhà cung cấp Compaction qua `registerCompactionProvider()` trên API Plugin. Khi `agents.defaults.compaction.provider` được đặt thành một id nhà cung cấp đã đăng ký, phần mở rộng safeguard ủy quyền việc tóm tắt cho nhà cung cấp đó thay vì pipeline `summarizeInStages` tích hợp sẵn. +Plugin có thể đăng ký một nhà cung cấp Compaction thông qua `registerCompactionProvider()` trên API Plugin. Khi `agents.defaults.compaction.provider` được đặt thành một id nhà cung cấp đã đăng ký, tiện ích mở rộng bảo vệ ủy quyền việc tóm tắt cho nhà cung cấp đó thay vì pipeline `summarizeInStages` tích hợp sẵn. -- `provider`: id của một Plugin nhà cung cấp Compaction đã đăng ký. Để trống để dùng tóm tắt LLM mặc định. +- `provider`: id của Plugin nhà cung cấp Compaction đã đăng ký. Để trống để dùng tóm tắt LLM mặc định. - Đặt một `provider` sẽ buộc `mode: "safeguard"`. -- Các nhà cung cấp nhận cùng chỉ dẫn Compaction và chính sách bảo toàn định danh như đường tích hợp sẵn. -- Safeguard vẫn bảo toàn ngữ cảnh hậu tố lượt gần đây và lượt bị chia sau đầu ra của nhà cung cấp. -- Tóm tắt safeguard tích hợp sẵn chưng cất lại các bản tóm tắt trước đó với các thông điệp mới thay vì giữ nguyên văn toàn bộ bản tóm tắt trước đó. -- Chế độ safeguard bật kiểm toán chất lượng tóm tắt theo mặc định; đặt `qualityGuard.enabled: false` để bỏ qua hành vi thử lại khi đầu ra sai định dạng. -- Nếu nhà cung cấp thất bại hoặc trả về kết quả rỗng, OpenClaw tự động quay về tóm tắt LLM tích hợp sẵn. -- Tín hiệu hủy/hết thời gian chờ được ném lại (không bị nuốt) để tôn trọng việc hủy của bên gọi. +- Nhà cung cấp nhận cùng chỉ dẫn Compaction và chính sách bảo toàn định danh như đường tích hợp sẵn. +- Cơ chế bảo vệ vẫn giữ ngữ cảnh hậu tố của lượt gần đây và lượt bị chia sau đầu ra của nhà cung cấp. +- Tóm tắt bảo vệ tích hợp sẵn chưng cất lại các bản tóm tắt trước đó với thông điệp mới thay vì giữ nguyên văn toàn bộ bản tóm tắt trước. +- Chế độ bảo vệ bật kiểm toán chất lượng tóm tắt theo mặc định; đặt `qualityGuard.enabled: false` để bỏ qua hành vi thử lại khi đầu ra sai định dạng. +- Nếu nhà cung cấp thất bại hoặc trả về kết quả rỗng, OpenClaw tự động quay lại tóm tắt LLM tích hợp sẵn. +- Tín hiệu hủy/hết thời gian chờ được ném lại (không bị nuốt) để tôn trọng việc hủy từ bên gọi. Nguồn: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. --- -## Bề mặt hiển thị cho người dùng +## Bề mặt người dùng thấy được -Bạn có thể quan sát trạng thái Compaction và phiên qua: +Bạn có thể quan sát Compaction và trạng thái phiên thông qua: -- `/status` (trong bất kỳ phiên chat nào) +- `/status` (trong bất kỳ phiên trò chuyện nào) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` - Chế độ chi tiết: `🧹 Auto-compaction complete` + số lần Compaction --- -## Công việc duy trì im lặng (`NO_REPLY`) +## Dọn dẹp âm thầm (`NO_REPLY`) -OpenClaw hỗ trợ các lượt “im lặng” cho tác vụ nền khi người dùng không nên thấy đầu ra trung gian. +OpenClaw hỗ trợ các lượt “âm thầm” cho tác vụ nền nơi người dùng không nên thấy đầu ra trung gian. Quy ước: -- Trợ lý bắt đầu đầu ra bằng token im lặng chính xác `NO_REPLY` / - `no_reply` để chỉ ra “không gửi phản hồi cho người dùng”. -- OpenClaw loại bỏ/ẩn phần này ở lớp gửi. -- Việc ẩn token im lặng chính xác không phân biệt chữ hoa chữ thường, vì vậy `NO_REPLY` và - `no_reply` đều được tính khi toàn bộ payload chỉ là token im lặng. -- Điều này chỉ dành cho các lượt nền/không gửi thật sự; nó không phải lối tắt cho các yêu cầu người dùng thông thường có thể hành động. +- assistant bắt đầu đầu ra bằng token âm thầm chính xác `NO_REPLY` / + `no_reply` để chỉ ra “không gửi câu trả lời cho người dùng”. +- OpenClaw loại bỏ/ẩn điều này ở lớp gửi. +- Việc ẩn token âm thầm chính xác không phân biệt chữ hoa chữ thường, nên `NO_REPLY` và + `no_reply` đều được tính khi toàn bộ payload chỉ là token âm thầm. +- Điều này chỉ dành cho các lượt nền/thực sự không gửi; nó không phải lối tắt cho các yêu cầu người dùng thông thường cần hành động. -Kể từ `2026.1.10`, OpenClaw cũng ẩn **luồng nháp/đang nhập** khi một đoạn một phần bắt đầu bằng `NO_REPLY`, để các thao tác im lặng không rò rỉ đầu ra một phần giữa lượt. +Kể từ `2026.1.10`, OpenClaw cũng ẩn **phát trực tuyến nháp/đang nhập** khi một đoạn một phần bắt đầu bằng `NO_REPLY`, để các thao tác âm thầm không rò rỉ đầu ra một phần giữa lượt. --- ## "Xả bộ nhớ" trước Compaction (đã triển khai) -Mục tiêu: trước khi tự động Compaction xảy ra, chạy một lượt agentic im lặng ghi trạng thái bền vững xuống đĩa (ví dụ `memory/YYYY-MM-DD.md` trong workspace của agent) để Compaction không thể xóa ngữ cảnh quan trọng. +Mục tiêu: trước khi tự động Compaction diễn ra, chạy một lượt tác nhân âm thầm ghi trạng thái bền vững vào đĩa (ví dụ `memory/YYYY-MM-DD.md` trong workspace của tác nhân) để Compaction không thể xóa ngữ cảnh quan trọng. OpenClaw dùng cách tiếp cận **xả trước ngưỡng**: -1. Giám sát mức sử dụng ngữ cảnh của phiên. -2. Khi nó vượt qua một “ngưỡng mềm” (thấp hơn ngưỡng Compaction của Pi), chạy một chỉ thị “ghi bộ nhớ ngay” im lặng cho agent. -3. Dùng token im lặng chính xác `NO_REPLY` / `no_reply` để người dùng không thấy gì. +1. Giám sát mức sử dụng ngữ cảnh phiên. +2. Khi nó vượt qua “ngưỡng mềm” (dưới ngưỡng Compaction của Pi), chạy chỉ thị “ghi bộ nhớ ngay” âm thầm cho tác nhân. +3. Dùng token âm thầm chính xác `NO_REPLY` / `no_reply` để người dùng không thấy gì. Cấu hình (`agents.defaults.compaction.memoryFlush`): @@ -388,25 +387,25 @@ Cấu hình (`agents.defaults.compaction.memoryFlush`): Ghi chú: - Prompt/prompt hệ thống mặc định bao gồm gợi ý `NO_REPLY` để ẩn việc gửi. -- Khi `model` được đặt, lượt xả dùng mô hình đó mà không kế thừa chuỗi fallback của phiên đang hoạt động, để công việc duy trì chỉ cục bộ không âm thầm fallback sang mô hình hội thoại trả phí. +- Khi `model` được đặt, lượt xả dùng mô hình đó mà không kế thừa chuỗi dự phòng của phiên đang hoạt động, để việc dọn dẹp chỉ cục bộ không âm thầm dự phòng sang một mô hình hội thoại trả phí. - Lượt xả chạy một lần cho mỗi chu kỳ Compaction (được theo dõi trong `sessions.json`). - Lượt xả chỉ chạy cho các phiên Pi nhúng (backend CLI bỏ qua). -- Lượt xả bị bỏ qua khi workspace của phiên là chỉ đọc (`workspaceAccess: "ro"` hoặc `"none"`). +- Lượt xả bị bỏ qua khi workspace phiên ở chế độ chỉ đọc (`workspaceAccess: "ro"` hoặc `"none"`). - Xem [Bộ nhớ](/vi/concepts/memory) để biết bố cục tệp workspace và mẫu ghi. -Pi cũng cung cấp hook `session_before_compact` trong API phần mở rộng, nhưng logic xả của OpenClaw hiện nằm ở phía Gateway. +Pi cũng cung cấp hook `session_before_compact` trong API tiện ích mở rộng, nhưng logic xả của OpenClaw hiện nằm ở phía Gateway. --- ## Danh sách kiểm tra khắc phục sự cố - Khóa phiên sai? Bắt đầu với [/concepts/session](/vi/concepts/session) và xác nhận `sessionKey` trong `/status`. -- Store và bản chép không khớp? Xác nhận host Gateway và đường dẫn store từ `openclaw status`. -- Compaction lặp quá nhiều? Kiểm tra: +- Kho lưu trữ và bản ghi không khớp? Xác nhận máy chủ Gateway và đường dẫn kho lưu trữ từ `openclaw status`. +- Compaction quá nhiều? Kiểm tra: - cửa sổ ngữ cảnh của mô hình (quá nhỏ) - cài đặt Compaction (`reserveTokens` quá cao so với cửa sổ mô hình có thể gây Compaction sớm hơn) - - kết quả công cụ phình to: bật/tinh chỉnh việc cắt tỉa phiên -- Lượt im lặng bị rò rỉ? Xác nhận phản hồi bắt đầu bằng `NO_REPLY` (token chính xác không phân biệt chữ hoa chữ thường) và bạn đang dùng bản dựng có bản sửa ẩn luồng. + - kết quả công cụ phình to: bật/tinh chỉnh cắt tỉa phiên +- Lượt âm thầm bị rò rỉ? Xác nhận câu trả lời bắt đầu bằng `NO_REPLY` (token chính xác không phân biệt chữ hoa chữ thường) và bạn đang dùng bản dựng có bản sửa ẩn phát trực tuyến. ## Liên quan