chore(i18n): refresh zh-TW translations

docs/zh-TW/automation/tasks.md

@@ -1,52 +1,53 @@
 ---
 read_when:
-    - 檢視進行中或最近完成的背景作業
-    - 偵錯分離式代理執行的傳遞失敗
+    - 檢查正在進行或最近完成的背景工作
+    - 偵錯分離式代理程式執行的傳遞失敗
     - 了解背景執行與工作階段、Cron 和 Heartbeat 的關係
 sidebarTitle: Background tasks
-summary: 用於 ACP 執行、子代理、隔離式 Cron 作業和 CLI 操作的背景任務追蹤
+summary: 用於 ACP 執行、子代理、隔離 Cron 工作和 CLI 操作的背景任務追蹤
 title: 背景任務
 x-i18n:
-    generated_at: "2026-05-02T02:44:06Z"
+    generated_at: "2026-05-05T01:44:24Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
+    source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991
     source_path: automation/tasks.md
     workflow: 16
 ---
 
 <Note>
-正在尋找排程功能？請參閱[自動化與任務](/zh-TW/automation)以選擇合適的機制。此頁面是背景工作的活動帳本，而不是排程器。
+正在尋找排程？請參閱[自動化與任務](/zh-TW/automation)，以選擇正確的機制。本頁是背景工作的活動帳本，不是排程器。
 </Note>
 
-背景任務會追蹤在**主要對話工作階段之外**執行的工作：ACP 執行、子代理產生、隔離的 cron 作業執行，以及由 CLI 啟動的操作。
+背景任務會追蹤在**主要對話工作階段之外**執行的工作：ACP 執行、子代理產生、隔離的 cron 工作執行，以及由 CLI 啟動的操作。
 
-任務**不會**取代工作階段、cron 作業或 Heartbeat —— 它們是**活動帳本**，用來記錄發生了哪些分離式工作、發生時間，以及是否成功。
+任務**不會**取代工作階段、cron 工作或 heartbeats — 它們是**活動帳本**，記錄發生了哪些分離式工作、何時發生，以及是否成功。
 
 <Note>
-不是每次代理執行都會建立任務。Heartbeat 回合與一般互動式聊天不會。所有 cron 執行、ACP 產生、子代理產生，以及 CLI 代理命令都會建立任務。
+並非每次代理執行都會建立任務。Heartbeat 回合和一般互動式聊天不會。所有 cron 執行、ACP 產生、子代理產生，以及 CLI 代理命令都會。
 </Note>
 
-## 簡短摘要
+## 太長；沒讀
 
-- 任務是**記錄**，不是排程器 —— cron 和 Heartbeat 決定工作_何時_執行，任務追蹤_發生了什麼_。
-- ACP、子代理、所有 cron 作業，以及 CLI 操作都會建立任務。Heartbeat 回合不會。
+- 任務是**記錄**，不是排程器 — cron 和 heartbeat 決定工作_何時_執行，任務追蹤_發生了什麼_。
+- ACP、子代理、所有 cron 工作，以及 CLI 操作都會建立任務。Heartbeat 回合不會。
 - 每個任務都會經過 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。
-- 只要 cron 執行階段仍然擁有該作業，Cron 任務就會保持啟用；如果
-  記憶體中的執行階段狀態已消失，任務維護會先檢查持久化 cron
+- 只要 cron runtime 仍擁有該工作，Cron 任務就會保持活動狀態；如果
+  記憶體內的 runtime 狀態消失，任務維護會先檢查持久化的 cron
   執行歷史，再將任務標記為 lost。
-- 完成是推送驅動的：分離式工作可在完成時直接通知，或喚醒
-  請求者工作階段/Heartbeat，因此狀態輪詢迴圈通常不是正確形態。
-- 隔離的 cron 執行與子代理完成時，會盡力在最終清理記帳前，清理其子工作階段追蹤的瀏覽器分頁/程序。
-- 當後代子代理工作仍在排空時，隔離的 cron 傳遞會抑制過期的臨時父回覆；若最終後代輸出在傳遞前抵達，則優先使用該輸出。
-- 完成通知會直接傳遞到頻道，或排入下一次 Heartbeat。
-- `openclaw tasks list` 顯示所有任務；`openclaw tasks audit` 會顯示問題。
-- 終端記錄會保留 7 天，然後自動修剪。
+- 完成是由推送驅動：分離式工作可以在完成時直接通知，或喚醒
+  requester 工作階段/heartbeat，因此狀態輪詢迴圈
+  通常不是正確的形式。
+- 隔離的 cron 執行和子代理完成會盡力在最終清理簿記前，清理由其子工作階段追蹤的瀏覽器分頁/程序。
+- 當後代子代理工作仍在清空時，隔離的 cron 傳遞會抑制過期的中繼父回覆，並且若最終後代輸出在傳遞前抵達，會優先使用該輸出。
+- 完成通知會直接傳遞到頻道，或排入下一次 heartbeat。
+- `openclaw tasks list` 會顯示所有任務；`openclaw tasks audit` 會呈現問題。
+- 終端記錄會保留 7 天，然後自動清除。
 
 ## 快速開始
 
 <Tabs>
-  <Tab title="列出與篩選">
+  <Tab title="List and filter">
     ```bash
     # List all tasks (newest first)
     openclaw tasks list
@@ -57,13 +58,13 @@ x-i18n:
     ```
 
   </Tab>
-  <Tab title="檢查">
+  <Tab title="Inspect">
     ```bash
     # Show details for a specific task (by ID, run ID, or session key)
     openclaw tasks show <lookup>
     ```
   </Tab>
-  <Tab title="取消與通知">
+  <Tab title="Cancel and notify">
     ```bash
     # Cancel a running task (kills the child session)
     openclaw tasks cancel <lookup>
@@ -73,7 +74,7 @@ x-i18n:
     ```
 
   </Tab>
-  <Tab title="稽核與維護">
+  <Tab title="Audit and maintenance">
     ```bash
     # Run a health audit
     openclaw tasks audit
@@ -84,7 +85,7 @@ x-i18n:
     ```
 
   </Tab>
-  <Tab title="任務流程">
+  <Tab title="Task flow">
     ```bash
     # Inspect TaskFlow state
     openclaw tasks flow list
@@ -96,26 +97,26 @@ x-i18n:
 
 ## 什麼會建立任務
 
-| 來源                   | 執行階段類型 | 任務記錄建立時機                                       | 預設通知政策          |
-| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
-| ACP 背景執行           | `acp`        | 產生子 ACP 工作階段                                    | `done_only`           |
-| 子代理編排             | `subagent`   | 透過 `sessions_spawn` 產生子代理                       | `done_only`           |
-| Cron 作業（所有類型）  | `cron`       | 每次 cron 執行（主要工作階段與隔離執行）               | `silent`              |
-| CLI 操作               | `cli`        | 透過 Gateway 執行的 `openclaw agent` 命令              | `silent`              |
-| 代理媒體作業           | `cli`        | 由工作階段支援的 `music_generate`/`video_generate` 執行 | `silent`              |
+| 來源                   | Runtime 類型 | 何時建立任務記錄                                         | 預設通知政策 |
+| ---------------------- | ------------ | -------------------------------------------------------- | ------------ |
+| ACP 背景執行           | `acp`        | 產生子 ACP 工作階段                                      | `done_only`  |
+| 子代理協調             | `subagent`   | 透過 `sessions_spawn` 產生子代理                         | `done_only`  |
+| Cron 工作（所有類型）  | `cron`       | 每次 cron 執行（主要工作階段和隔離）                     | `silent`     |
+| CLI 操作               | `cli`        | 透過 gateway 執行的 `openclaw agent` 命令                | `silent`     |
+| 代理媒體工作           | `cli`        | 由工作階段支援的 `music_generate`/`video_generate` 執行  | `silent`     |
 
 <AccordionGroup>
-  <Accordion title="cron 與媒體的通知預設值">
-    主要工作階段 cron 任務預設使用 `silent` 通知政策 —— 它們會建立記錄以供追蹤，但不會產生通知。隔離的 cron 任務也預設為 `silent`，但因為它們在自己的工作階段中執行，所以更容易被看到。
+  <Accordion title="Notify defaults for cron and media">
+    主要工作階段 cron 任務預設使用 `silent` 通知政策 — 它們會建立用於追蹤的記錄，但不會產生通知。隔離的 cron 任務也預設為 `silent`，但因為它們在自己的工作階段中執行，所以更容易被看見。
 
-    由工作階段支援的 `music_generate` 與 `video_generate` 執行也使用 `silent` 通知政策。它們仍會建立任務記錄，但完成結果會作為內部喚醒交回原始代理工作階段，讓代理可以自行寫入後續訊息並附上完成的媒體。如果你選擇啟用 `tools.media.asyncCompletion.directSend`，非同步 `video_generate` 完成可以先嘗試直接傳遞到頻道；非同步 `music_generate` 完成則維持在請求者工作階段喚醒路徑上。
+    由工作階段支援的 `music_generate` 和 `video_generate` 執行也使用 `silent` 通知政策。它們仍會建立任務記錄，但完成會以內部喚醒的形式交回原始代理工作階段，讓代理能寫出後續訊息並自行附加完成的媒體。群組/頻道完成會遵循一般的可見回覆政策，因此當來源傳遞需要時，代理會使用訊息工具。
 
   </Accordion>
-  <Accordion title="並行 video_generate 防護">
-    當由工作階段支援的 `video_generate` 任務仍處於作用中時，該工具也會充當防護：同一工作階段中重複的 `video_generate` 呼叫會回傳作用中任務狀態，而不是啟動第二個並行產生。當你想從代理端明確查詢進度/狀態時，請使用 `action: "status"`。
+  <Accordion title="Concurrent video_generate guardrail">
+    當由工作階段支援的 `video_generate` 任務仍在活動時，該工具也會作為護欄：同一工作階段中重複的 `video_generate` 呼叫會回傳作用中任務狀態，而不是開始第二個並行生成。當你想從代理端明確查詢進度/狀態時，請使用 `action: "status"`。
   </Accordion>
-  <Accordion title="什麼不會建立任務">
-    - Heartbeat 回合 —— 主要工作階段；請參閱 [Heartbeat](/zh-TW/gateway/heartbeat)
+  <Accordion title="What does not create tasks">
+    - Heartbeat 回合 — 主要工作階段；請參閱 [Heartbeat](/zh-TW/gateway/heartbeat)
     - 一般互動式聊天回合
     - 直接的 `/command` 回應
 
@@ -136,58 +137,58 @@ stateDiagram-v2
     running --> lost : session gone > 5 min
 ```
 
-| 狀態        | 含義                                                                       |
+| 狀態        | 意義                                                                       |
 | ----------- | -------------------------------------------------------------------------- |
 | `queued`    | 已建立，正在等待代理啟動                                                   |
 | `running`   | 代理回合正在主動執行                                                       |
 | `succeeded` | 已成功完成                                                                 |
 | `failed`    | 已完成但發生錯誤                                                           |
-| `timed_out` | 超過設定的逾時時間                                                         |
+| `timed_out` | 超過設定的逾時                                                             |
 | `cancelled` | 由操作員透過 `openclaw tasks cancel` 停止                                  |
-| `lost`      | 執行階段在 5 分鐘寬限期後失去權威後端狀態                                  |
+| `lost`      | runtime 在 5 分鐘寬限期後遺失權威的後備狀態                                |
 
-轉換會自動發生 —— 當關聯的代理執行結束時，任務狀態會更新為相符狀態。
+轉換會自動發生 — 當關聯的代理執行結束時，任務狀態會更新為相符狀態。
 
-代理執行完成是作用中任務記錄的權威依據。成功的分離式執行會最終化為 `succeeded`，一般執行錯誤會最終化為 `failed`，逾時或中止結果會最終化為 `timed_out`。如果操作員已取消任務，或執行階段已記錄更強的終端狀態，例如 `failed`、`timed_out` 或 `lost`，較晚的成功訊號不會將該終端狀態降級。
+代理執行完成是作用中任務記錄的權威依據。成功的分離式執行會最終化為 `succeeded`，一般執行錯誤會最終化為 `failed`，逾時或中止結果會最終化為 `timed_out`。如果操作員已取消任務，或 runtime 已記錄較強的終端狀態，例如 `failed`、`timed_out` 或 `lost`，稍後的成功訊號不會降級該終端狀態。
 
-`lost` 會感知執行階段：
+`lost` 會感知 runtime：
 
-- ACP 任務：後端 ACP 子工作階段中繼資料消失。
-- 子代理任務：後端子工作階段從目標代理儲存中消失。
-- Cron 任務：cron 執行階段不再將該作業追蹤為作用中，且持久化
-  cron 執行歷史未顯示該次執行的終端結果。離線 CLI
-  稽核不會將它自己的空白程序內 cron 執行階段狀態視為權威。
-- CLI 任務：隔離的子工作階段任務使用子工作階段；由聊天支援的
-  CLI 任務改用即時執行脈絡，因此殘留的
-  頻道/群組/直接工作階段列不會讓它們保持作用中。由 Gateway 支援的
-  `openclaw agent` 執行也會根據其執行結果最終化，因此已完成的執行
-  不會一直處於作用中，直到清掃器將它們標記為 `lost`。
+- ACP 任務：後備 ACP 子工作階段中繼資料消失。
+- 子代理任務：後備子工作階段從目標代理儲存中消失。
+- Cron 任務：cron runtime 不再將該工作追蹤為活動中，且持久化的
+  cron 執行歷史未顯示該執行的終端結果。離線 CLI
+  audit 不會將其自身空白的程序內 cron runtime 狀態視為權威。
+- CLI 任務：隔離子工作階段任務使用子工作階段；由聊天支援的
+  CLI 任務則使用即時執行內容，因此殘留的
+  頻道/群組/直接訊息工作階段列不會讓它們維持活動。由 Gateway 支援的
+  `openclaw agent` 執行也會依執行結果最終化，因此已完成的執行
+  不會一直維持活動直到清掃器將它們標記為 `lost`。
 
 ## 傳遞與通知
 
-當任務到達終端狀態時，OpenClaw 會通知你。有兩種傳遞路徑：
+當任務達到終端狀態時，OpenClaw 會通知你。有兩種傳遞路徑：
 
-**直接傳遞** —— 如果任務有頻道目標（`requesterOrigin`），完成訊息會直接送到該頻道（Telegram、Discord、Slack 等）。對於子代理完成，OpenClaw 也會在可用時保留繫結的執行緒/主題路由，並可在放棄直接傳遞前，從請求者工作階段儲存的路由（`lastChannel` / `lastTo` / `lastAccountId`）補上缺少的 `to` / 帳號。
+**直接傳遞** — 如果任務有頻道目標（`requesterOrigin`），完成訊息會直接送到該頻道（Telegram、Discord、Slack 等）。對於子代理完成，OpenClaw 也會在可用時保留綁定的執行緒/主題路由，並且可以在放棄直接傳遞前，從 requester 工作階段儲存的路由（`lastChannel` / `lastTo` / `lastAccountId`）補齊缺少的 `to` / 帳號。
 
-**工作階段佇列傳遞** —— 如果直接傳遞失敗或未設定來源，更新會作為系統事件排入請求者的工作階段，並在下一次 Heartbeat 顯示。
+**排入工作階段的傳遞** — 如果直接傳遞失敗或未設定來源，更新會作為系統事件排入 requester 的工作階段，並在下一次 heartbeat 出現。
 
 <Tip>
-任務完成會觸發立即 Heartbeat 喚醒，讓你能快速看到結果 —— 你不必等待下一個排定的 Heartbeat tick。
+任務完成會觸發立即的 heartbeat 喚醒，讓你很快看到結果 — 你不必等到下一個排程 heartbeat tick。
 </Tip>
 
-這表示一般工作流程是以推送為基礎：啟動一次分離式工作，然後讓執行階段在完成時喚醒或通知你。只有在需要偵錯、介入或明確稽核時，才輪詢任務狀態。
+這表示一般工作流程是推送式的：啟動一次分離式工作，然後讓 runtime 在完成時喚醒或通知你。只有在需要除錯、介入或明確 audit 時，才輪詢任務狀態。
 
 ### 通知政策
 
-控制你會收到每個任務多少資訊：
+控制你會收到多少關於每個任務的通知：
 
 | 政策                  | 傳遞內容                                                                |
 | --------------------- | ----------------------------------------------------------------------- |
-| `done_only`（預設）   | 只有終端狀態（succeeded、failed 等）—— **這是預設值**                  |
-| `state_changes`       | 每次狀態轉換與進度更新                                                  |
+| `done_only`（預設）   | 只有終端狀態（succeeded、failed 等）— **這是預設值**                    |
+| `state_changes`       | 每次狀態轉換和進度更新                                                  |
 | `silent`              | 完全不傳遞                                                              |
 
-在任務執行期間變更政策：
+在任務執行中變更政策：
 
 ```bash
 openclaw tasks notify <lookup> state_changes
@@ -209,7 +210,7 @@ openclaw tasks notify <lookup> state_changes
     openclaw tasks show <lookup>
     ```
 
-    查詢權杖接受任務 ID、執行 ID 或工作階段鍵。顯示完整記錄，包括時間、傳遞狀態、錯誤與終端摘要。
+    查詢權杖接受任務 ID、執行 ID 或工作階段鍵。顯示完整記錄，包括時間、傳遞狀態、錯誤和終端摘要。
 
   </Accordion>
   <Accordion title="tasks cancel">
@@ -217,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
     openclaw tasks cancel <lookup>
     ```
 
-    對 ACP 與子代理任務，這會終止子工作階段。對 CLI 追蹤的任務，取消會記錄在任務登錄檔中（沒有獨立的子執行階段控制代碼）。狀態會轉換為 `cancelled`，並在適用時傳送傳遞通知。
+    對於 ACP 和子代理任務，這會終止子工作階段。對於由 CLI 追蹤的任務，取消會記錄在任務登錄中（沒有單獨的子 runtime 控制代碼）。狀態會轉換為 `cancelled`，並在適用時傳送傳遞通知。
 
   </Accordion>
   <Accordion title="tasks notify">
@@ -230,16 +231,16 @@ openclaw tasks notify <lookup> state_changes
     openclaw tasks audit [--json]
     ```
 
-    顯示操作問題。偵測到問題時，發現項目也會出現在 `openclaw status` 中。
+    呈現操作問題。偵測到問題時，發現也會出現在 `openclaw status` 中。
 
     | 發現項目                  | 嚴重性     | 觸發條件                                                                                                     |
     | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
-    | `stale_queued`            | 警告       | 排入佇列超過 10 分鐘                                                                                         |
+    | `stale_queued`            | 警告       | 佇列超過 10 分鐘                                                                                             |
     | `stale_running`           | 錯誤       | 執行超過 30 分鐘                                                                                             |
-    | `lost`                    | 警告/錯誤  | 由 runtime 支援的任務擁有權消失；保留的遺失任務在 `cleanupAfter` 前會發出警告，之後會變成錯誤              |
-    | `delivery_failed`         | 警告       | 傳送失敗，且通知政策不是 `silent`                                                                            |
-    | `missing_cleanup`         | 警告       | 終端任務沒有清理時間戳記                                                                                    |
-    | `inconsistent_timestamps` | 警告       | 時間軸違規（例如結束時間早於開始時間）                                                                      |
+    | `lost`                    | 警告/錯誤  | 由執行階段支援的任務所有權消失；保留的遺失任務在 `cleanupAfter` 前會警告，之後會變成錯誤                   |
+    | `delivery_failed`         | 警告       | 傳送失敗且通知政策不是 `silent`                                                                              |
+    | `missing_cleanup`         | 警告       | 終止任務沒有清理時間戳                                                                                       |
+    | `inconsistent_timestamps` | 警告       | 時間軸違規（例如結束早於開始）                                                                               |
 
   </Accordion>
   <Accordion title="任務維護">
@@ -248,21 +249,21 @@ openclaw tasks notify <lookup> state_changes
     openclaw tasks maintenance --apply [--json]
     ```
 
-    使用這個指令預覽或套用任務與 Task Flow 狀態的調節、清理標記和剪除。
+    使用此命令來預覽或套用任務與任務流程狀態的協調、清理標記與剪除。
 
-    調節會感知 runtime：
+    協調會感知執行階段：
 
-    - ACP/subagent 任務會檢查其背後的子 session。
-    - 子 session 有 restart-recovery tombstone 的 subagent 任務，會標記為遺失，而不是被視為可復原的背後 session。
-    - Cron 任務會檢查 cron runtime 是否仍擁有該 job，接著從持久化的 cron 執行記錄/job 狀態復原終端狀態，然後才回退到 `lost`。只有 Gateway 程序對記憶體內的 cron active-job set 具有權威性；離線 CLI 稽核會使用持久化歷史，但不會只因為該本機 Set 是空的，就將 cron 任務標記為遺失。
-    - 由聊天支援的 CLI 任務會檢查所屬的即時 run context，而不只是聊天 session row。
+    - ACP/子代理任務會檢查其背後的子工作階段。
+    - 子代理任務若其子工作階段有重啟復原墓碑，會被標記為遺失，而不是視為可復原的背後工作階段。
+    - Cron 任務會檢查 cron 執行階段是否仍擁有該工作，然後從持久化的 cron 執行記錄/工作狀態復原終止狀態，再退回到 `lost`。只有 Gateway 程序對記憶體中的 cron 作用中工作集合具有權威性；離線 CLI 稽核會使用持久歷史，但不會只因為該本機 Set 為空就將 cron 任務標記為遺失。
+    - 由聊天支援的 CLI 任務會檢查擁有它的即時執行上下文，而不只是聊天工作階段資料列。
 
-    完成清理也會感知 runtime：
+    完成清理也會感知執行階段：
 
-    - Subagent 完成時，會在宣布清理繼續前盡力關閉為子 session 追蹤的瀏覽器分頁/程序。
-    - 隔離 cron 完成時，會在該次執行完全拆除前盡力關閉為 cron session 追蹤的瀏覽器分頁/程序。
-    - 隔離 cron 傳送會在需要時等候後代 subagent follow-up，並抑制過時的父層確認文字，而不是宣布它。
-    - Subagent 完成傳送會偏好最新可見的 assistant 文字；如果它是空的，會回退到已清理的最新 tool/toolResult 文字，而只有逾時 tool-call 的執行可以折疊為簡短的部分進度摘要。終端失敗的執行會宣布失敗狀態，而不重播擷取到的回覆文字。
+    - 子代理完成時，會盡力先關閉針對子工作階段追蹤的瀏覽器分頁/程序，然後公告清理才會繼續。
+    - 隔離的 cron 完成時，會盡力先關閉針對 cron 工作階段追蹤的瀏覽器分頁/程序，然後執行才會完全拆除。
+    - 隔離的 cron 傳送會在需要時等待後代子代理後續動作完成，並抑制過期的父層確認文字，而不是公告它。
+    - 子代理完成傳送會偏好最新可見的助理文字；如果為空，會退回到已清理的最新工具/toolResult 文字，而且只有逾時的工具呼叫執行可收斂成簡短的部分進度摘要。終止失敗的執行會公告失敗狀態，而不重播擷取的回覆文字。
     - 清理失敗不會遮蔽真正的任務結果。
 
   </Accordion>
@@ -273,18 +274,18 @@ openclaw tasks notify <lookup> state_changes
     openclaw tasks flow cancel <lookup>
     ```
 
-    當你關心的是編排中的 Task Flow，而不是單一背景任務記錄時，請使用這些指令。
+    當你關心的是負責協調的任務流程，而不是單一背景任務記錄時，請使用這些命令。
 
   </Accordion>
 </AccordionGroup>
 
 ## 聊天任務看板 (`/tasks`)
 
-在任何聊天 session 中使用 `/tasks`，即可查看連結到該 session 的背景任務。看板會顯示作用中和最近完成的任務，包含 runtime、狀態、時間，以及進度或錯誤詳細資料。
+在任何聊天工作階段中使用 `/tasks`，即可查看連結到該工作階段的背景任務。看板會顯示作用中與最近完成的任務，以及執行階段、狀態、時間、進度或錯誤詳細資料。
 
-當目前 session 沒有可見的連結任務時，`/tasks` 會回退到 agent-local 任務計數，因此你仍能取得概覽，而不洩漏其他 session 的詳細資料。
+當目前工作階段沒有可見的連結任務時，`/tasks` 會退回到代理本機任務計數，因此你仍能取得概覽，而不洩漏其他工作階段的詳細資料。
 
-如需完整的 operator ledger，請使用 CLI：`openclaw tasks list`。
+若要查看完整的操作員帳本，請使用 CLI：`openclaw tasks list`。
 
 ## 狀態整合（任務壓力）
 
@@ -296,38 +297,38 @@ Tasks: 3 queued · 2 running · 1 issues
 
 摘要會回報：
 
-- **作用中** — `queued` + `running` 的數量
-- **失敗** — `failed` + `timed_out` + `lost` 的數量
-- **byRuntime** — 依 `acp`、`subagent`、`cron`、`cli` 的細分
+- **作用中** — `queued` + `running` 的計數
+- **失敗** — `failed` + `timed_out` + `lost` 的計數
+- **依執行階段** — 依 `acp`、`subagent`、`cron`、`cli` 細分
 
-`/status` 和 `session_status` 工具都使用會感知清理的任務快照：優先顯示作用中任務，隱藏過時的已完成 row，而且只有在沒有作用中工作剩餘時，才會顯示最近的失敗。這讓狀態卡片能專注於目前真正重要的事項。
+`/status` 和 `session_status` 工具都會使用感知清理的任務快照：優先顯示作用中任務、隱藏過期的已完成資料列，而且只有在沒有作用中工作留下時才會顯示最近失敗。這會讓狀態卡片聚焦在目前重要的事項。
 
 ## 儲存與維護
 
 ### 任務存放位置
 
-任務記錄會持久化在 SQLite：
+任務記錄會持久化到 SQLite，位置為：
 
 ```
 $OPENCLAW_STATE_DIR/tasks/runs.sqlite
 ```
 
-registry 會在 gateway 啟動時載入到記憶體，並將寫入同步到 SQLite，以便跨重新啟動保持持久性。
-Gateway 會使用 SQLite 預設的 autocheckpoint threshold，加上定期和關閉時的 `TRUNCATE` checkpoints，來限制 SQLite write-ahead log 的大小。
+登錄檔會在 gateway 啟動時載入記憶體，並將寫入同步到 SQLite，以便在重啟之間保持耐久性。
+Gateway 會使用 SQLite 的預設自動檢查點閾值，加上定期與關機時的 `TRUNCATE` 檢查點，讓 SQLite 預寫式記錄維持在受限大小。
 
 ### 自動維護
 
-sweeper 每 **60 秒** 執行一次，並處理四件事：
+清掃器每 **60 秒** 執行一次，並處理四件事：
 
 <Steps>
-  <Step title="調節">
-    檢查作用中任務是否仍有權威 runtime backing。ACP/subagent 任務使用 child-session 狀態，cron 任務使用 active-job 擁有權，而由聊天支援的 CLI 任務使用所屬的 run context。如果該 backing 狀態消失超過 5 分鐘，任務會標記為 `lost`。
+  <Step title="協調">
+    檢查作用中任務是否仍有權威的執行階段支援。ACP/子代理任務使用子工作階段狀態，cron 任務使用作用中工作所有權，而由聊天支援的 CLI 任務使用擁有它的執行上下文。如果該支援狀態消失超過 5 分鐘，任務會被標記為 `lost`。
   </Step>
-  <Step title="ACP session 修復">
-    關閉已終止或孤立、由父層擁有的一次性 ACP session；並且只有在沒有剩餘作用中的 conversation binding 時，才關閉過時的終端或孤立持久 ACP session。
+  <Step title="ACP 工作階段修復">
+    關閉已終止或孤立的父層擁有一次性 ACP 工作階段；只有在沒有作用中的對話繫結留下時，才會關閉過期終止或孤立的持久 ACP 工作階段。
   </Step>
   <Step title="清理標記">
-    在終端任務上設定 `cleanupAfter` 時間戳記（endedAt + 7 天）。在保留期間，遺失任務仍會在稽核中以警告顯示；在 `cleanupAfter` 到期後，或清理 metadata 遺失時，它們會成為錯誤。
+    在終止任務上設定 `cleanupAfter` 時間戳（endedAt + 7 天）。在保留期間，遺失任務仍會以警告形式出現在稽核中；`cleanupAfter` 過期後，或清理中繼資料缺失時，它們會成為錯誤。
   </Step>
   <Step title="剪除">
     刪除超過其 `cleanupAfter` 日期的記錄。
@@ -335,42 +336,42 @@ sweeper 每 **60 秒** 執行一次，並處理四件事：
 </Steps>
 
 <Note>
-**保留：** 終端任務記錄會保留 **7 天**，然後自動剪除。不需要設定。
+**保留：**終止任務記錄會保留 **7 天**，然後自動剪除。不需要設定。
 </Note>
 
-## 任務與其他系統的關係
+## 任務如何與其他系統相關
 
 <AccordionGroup>
-  <Accordion title="任務與 Task Flow">
-    [Task Flow](/zh-TW/automation/taskflow) 是背景任務上方的流程編排層。單一 flow 可以在其生命週期中使用受管理或鏡像的同步模式來協調多個任務。使用 `openclaw tasks` 檢查個別任務記錄，並使用 `openclaw tasks flow` 檢查編排中的 flow。
+  <Accordion title="任務與任務流程">
+    [任務流程](/zh-TW/automation/taskflow) 是背景任務之上的流程協調層。單一流程可在其生命週期內使用受管或鏡像同步模式協調多個任務。使用 `openclaw tasks` 檢查個別任務記錄，並使用 `openclaw tasks flow` 檢查負責協調的流程。
 
-    詳情請參閱 [Task Flow](/zh-TW/automation/taskflow)。
+    詳情請參閱[任務流程](/zh-TW/automation/taskflow)。
 
   </Accordion>
   <Accordion title="任務與 cron">
-    cron job **定義** 位於 `~/.openclaw/cron/jobs.json`；runtime 執行狀態則位於旁邊的 `~/.openclaw/cron/jobs-state.json`。**每次** cron 執行都會建立任務記錄，包含 main-session 和隔離執行。Main-session cron 任務預設使用 `silent` 通知政策，因此它們會被追蹤，但不會產生通知。
+    cron 工作**定義**位於 `~/.openclaw/cron/jobs.json`；執行階段執行狀態則位於旁邊的 `~/.openclaw/cron/jobs-state.json`。**每次** cron 執行都會建立一筆任務記錄，包括主工作階段與隔離工作階段。主工作階段 cron 任務預設使用 `silent` 通知政策，因此可以追蹤而不產生通知。
 
-    請參閱 [Cron Jobs](/zh-TW/automation/cron-jobs)。
+    請參閱 [Cron 工作](/zh-TW/automation/cron-jobs)。
 
   </Accordion>
   <Accordion title="任務與 Heartbeat">
-    Heartbeat 執行是 main-session turn，不會建立任務記錄。當任務完成時，可以觸發 heartbeat 喚醒，讓你能立即看到結果。
+    Heartbeat 執行是主工作階段回合，它們不會建立任務記錄。任務完成時，可以觸發 Heartbeat 喚醒，讓你能立即看到結果。
 
     請參閱 [Heartbeat](/zh-TW/gateway/heartbeat)。
 
   </Accordion>
-  <Accordion title="任務與 session">
-    任務可以參照 `childSessionKey`（工作執行的位置）和 `requesterSessionKey`（啟動它的人）。Session 是對話情境；任務則是在其上方進行活動追蹤。
+  <Accordion title="任務與工作階段">
+    任務可以參照 `childSessionKey`（工作執行的位置）與 `requesterSessionKey`（啟動它的人）。工作階段是對話上下文；任務則是在其上的活動追蹤。
   </Accordion>
-  <Accordion title="任務與 agent 執行">
-    任務的 `runId` 會連結到正在執行工作的 agent run。Agent 生命週期事件（開始、結束、錯誤）會自動更新任務狀態，你不需要手動管理生命週期。
+  <Accordion title="任務與代理執行">
+    任務的 `runId` 會連結到正在執行工作的代理執行。代理生命週期事件（開始、結束、錯誤）會自動更新任務狀態，你不需要手動管理生命週期。
   </Accordion>
 </AccordionGroup>
 
 ## 相關
 
 - [自動化與任務](/zh-TW/automation) — 所有自動化機制一覽
-- [CLI：任務](/zh-TW/cli/tasks) — CLI 指令參考
-- [Heartbeat](/zh-TW/gateway/heartbeat) — 定期 main-session turn
+- [CLI：任務](/zh-TW/cli/tasks) — CLI 命令參考
+- [Heartbeat](/zh-TW/gateway/heartbeat) — 定期主工作階段回合
 - [排程任務](/zh-TW/automation/cron-jobs) — 排程背景工作
-- [Task Flow](/zh-TW/automation/taskflow) — 任務上方的流程編排
+- [任務流程](/zh-TW/automation/taskflow) — 任務之上的流程協調

docs/zh-TW/ci.md

@@ -1,94 +1,94 @@
 ---
 read_when:
-    - 您需要了解某個 CI 作業為什麼有執行或沒有執行。
-    - 你正在偵錯失敗的 GitHub Actions 檢查
-    - 您正在協調一次發布驗證執行或重新執行
-    - 你正在變更 ClawSweeper 分派或 GitHub 活動轉發
-summary: CI 作業圖、範圍閘門、發行總括流程與本機命令對應項
-title: CI 管線
+    - 你需要了解 CI 作業為什麼有執行或沒有執行
+    - 你正在偵錯一個失敗的 GitHub Actions 檢查
+    - 你正在協調發行驗證的執行或重新執行
+    - 你正在變更 ClawSweeper 派送或 GitHub 活動轉送
+summary: CI 作業圖、範圍閘門、發行總括項目與本機對應命令
+title: 持續整合管線
 x-i18n:
-    generated_at: "2026-05-04T07:03:11Z"
+    generated_at: "2026-05-05T01:44:36Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
+    source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66
     source_path: ci.md
     workflow: 16
 ---
 
-OpenClaw CI 會在每次推送到 `main` 以及每個 pull request 上執行。`preflight` 工作會分類差異，並在只有不相關區域變更時關閉昂貴的 lane。手動 `workflow_dispatch` 執行會刻意略過智慧範圍限定，並為候選發行版本與廣泛驗證展開完整圖形。Android lane 透過 `include_android` 保持選擇性啟用。僅限發行的 Plugin 覆蓋位於獨立的 [`Plugin 預先發行`](#plugin-prerelease) 工作流程中，且只會從 [`完整發行驗證`](#full-release-validation) 或明確的手動觸發執行。
+OpenClaw CI 會在每次推送到 `main` 以及每個 pull request 上執行。`preflight` 工作會分類差異，並在只有不相關區域變更時關閉昂貴的 lane。手動 `workflow_dispatch` 執行會刻意繞過智慧範圍界定，並展開完整圖形以用於發布候選版本與廣泛驗證。Android lane 透過 `include_android` 維持選擇加入。僅限發布的 Plugin 涵蓋範圍位於獨立的 [`Plugin 預發布`](#plugin-prerelease) workflow 中，且只會從 [`完整發布驗證`](#full-release-validation) 或明確的手動 dispatch 執行。
 
-## 管線概覽
+## Pipeline 概覽
 
-| 工作                             | 目的                                                                                                      | 執行時機                           |
+| 工作                             | 用途                                                                                                      | 執行時機                           |
 | -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| `preflight`                      | 偵測僅文件變更、已變更範圍、已變更 extension，並建置 CI manifest                                         | 一律在非草稿推送與 PR 上執行       |
-| `security-scm-fast`              | 透過 `zizmor` 進行私鑰偵測與工作流程稽核                                                                 | 一律在非草稿推送與 PR 上執行       |
-| `security-dependency-audit`      | 針對 npm advisories 執行不需相依套件的 production lockfile 稽核                                           | 一律在非草稿推送與 PR 上執行       |
-| `security-fast`                  | 快速安全性工作的必要彙總                                                                                  | 一律在非草稿推送與 PR 上執行       |
-| `check-dependencies`             | Production Knip 僅相依套件檢查，加上未使用檔案允許清單防護                                               | Node 相關變更                      |
-| `build-artifacts`                | 建置 `dist/`、Control UI、已建置成品檢查，以及可重用的下游成品                                           | Node 相關變更                      |
+| `preflight`                      | 偵測僅文件變更、已變更範圍、已變更擴充套件，並建置 CI manifest                                           | 一律在非草稿推送和 PR 上執行      |
+| `security-scm-fast`              | 透過 `zizmor` 偵測私密金鑰並稽核 workflow                                                                 | 一律在非草稿推送和 PR 上執行      |
+| `security-dependency-audit`      | 針對 npm advisories 執行不需相依性的生產 lockfile 稽核                                                    | 一律在非草稿推送和 PR 上執行      |
+| `security-fast`                  | 快速安全工作的必要彙總                                                                                    | 一律在非草稿推送和 PR 上執行      |
+| `check-dependencies`             | 生產 Knip 僅相依性 pass 加上未使用檔案 allowlist guard                                                    | Node 相關變更                      |
+| `build-artifacts`                | 建置 `dist/`、Control UI、已建置成品檢查，以及可重用的下游成品                                            | Node 相關變更                      |
 | `checks-fast-core`               | 快速 Linux 正確性 lane，例如 bundled/plugin-contract/protocol 檢查                                        | Node 相關變更                      |
-| `checks-fast-contracts-channels` | 分片的 channel contract 檢查，並提供穩定的彙總檢查結果                                                   | Node 相關變更                      |
-| `checks-node-core-test`          | Core Node 測試分片，不包含 channel、bundled、contract 與 extension lane                                  | Node 相關變更                      |
-| `check`                          | 分片的主要本機 gate 等價項：prod types、lint、guards、test types，以及嚴格 smoke                         | Node 相關變更                      |
-| `check-additional`               | 架構、分片的 boundary/prompt drift、extension guards、package boundary，以及 gateway watch                | Node 相關變更                      |
-| `build-smoke`                    | 已建置 CLI smoke 測試與 startup-memory smoke                                                             | Node 相關變更                      |
-| `checks`                         | 已建置成品 channel 測試的驗證器                                                                          | Node 相關變更                      |
-| `checks-node-compat-node22`      | Node 22 相容性建置與 smoke lane                                                                          | 發行用手動 CI 觸發                 |
-| `check-docs`                     | 文件格式、lint 與 broken-link 檢查                                                                       | 文件已變更                         |
-| `skills-python`                  | Python 支援的 skills 的 Ruff + pytest                                                                    | Python skill 相關變更              |
-| `checks-windows`                 | Windows 特定 process/path 測試，加上共用 runtime import specifier regression                             | Windows 相關變更                   |
-| `macos-node`                     | 使用共用已建置成品的 macOS TypeScript 測試 lane                                                          | macOS 相關變更                     |
-| `macos-swift`                    | macOS app 的 Swift lint、build 與測試                                                                    | macOS 相關變更                     |
-| `android`                        | 兩種 flavor 的 Android unit tests，加上一個 debug APK build                                              | Android 相關變更                   |
-| `test-performance-agent`         | 受信任活動後每日 Codex 慢速測試最佳化                                                                    | Main CI 成功或手動觸發             |
-| `openclaw-performance`           | 每日/隨需 Kova runtime 效能報告，包含 mock-provider、deep-profile 與 GPT 5.4 live lane                   | 排程與手動觸發                     |
+| `checks-fast-contracts-channels` | 分片 channel contract 檢查，並提供穩定的彙總檢查結果                                                      | Node 相關變更                      |
+| `checks-node-core-test`          | Core Node 測試分片，不含 channel、bundled、contract 和 extension lane                                     | Node 相關變更                      |
+| `check`                          | 分片主本機 gate 等效項目：prod types、lint、guards、test types 和 strict smoke                            | Node 相關變更                      |
+| `check-additional`               | 架構、分片 boundary/prompt drift、extension guards、package boundary，以及 gateway watch                   | Node 相關變更                      |
+| `build-smoke`                    | 已建置 CLI smoke 測試與 startup-memory smoke                                                              | Node 相關變更                      |
+| `checks`                         | 已建置成品 channel 測試的 verifier                                                                        | Node 相關變更                      |
+| `checks-node-compat-node22`      | Node 22 相容性建置與 smoke lane                                                                           | 針對發布的手動 CI dispatch         |
+| `check-docs`                     | 文件格式、lint 和 broken-link 檢查                                                                        | 文件已變更                         |
+| `skills-python`                  | Python-backed skills 的 Ruff + pytest                                                                     | Python-skill 相關變更              |
+| `checks-windows`                 | Windows 特定 process/path 測試，以及共享 runtime import specifier 迴歸                                    | Windows 相關變更                   |
+| `macos-node`                     | 使用共享已建置成品的 macOS TypeScript 測試 lane                                                           | macOS 相關變更                     |
+| `macos-swift`                    | macOS app 的 Swift lint、建置與測試                                                                       | macOS 相關變更                     |
+| `android`                        | 兩種 flavor 的 Android unit tests 加上一個 debug APK 建置                                                 | Android 相關變更                   |
+| `test-performance-agent`         | 受信任活動後的每日 Codex slow-test 最佳化                                                                 | Main CI 成功或手動 dispatch        |
+| `openclaw-performance`           | 每日/隨選 Kova runtime 效能報告，包含 mock-provider、deep-profile 和 GPT 5.4 live lane                    | 排程與手動 dispatch                |
 
-## 快速失敗順序
+## Fail-fast 順序
 
-1. `preflight` 決定哪些 lane 實際存在。`docs-scope` 與 `changed-scope` 邏輯是此工作內的步驟，不是獨立工作。
-2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 與 `skills-python` 會快速失敗，而不等待較重的成品與平台矩陣工作。
-3. `build-artifacts` 會與快速 Linux lane 重疊，讓下游消費者能在共用 build 準備好後立即開始。
-4. 較重的平台與 runtime lane 會在之後展開：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 與 `android`。
+1. `preflight` 決定哪些 lane 實際存在。`docs-scope` 和 `changed-scope` 邏輯是此工作內的步驟，不是獨立工作。
+2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 會快速失敗，而不等待較重的成品與平台矩陣工作。
+3. `build-artifacts` 會與快速 Linux lane 重疊，讓下游消費者能在共享建置準備好後立即開始。
+4. 較重的平台與 runtime lane 之後展開：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。
 
-當較新的推送落在同一個 PR 或 `main` ref 上時，GitHub 可能會將被取代的工作標記為 `cancelled`。除非同一 ref 的最新執行也失敗，否則將其視為 CI 雜訊。彙總分片檢查使用 `!cancelled() && always()`，因此仍會回報正常的分片失敗，但不會在整個工作流程已被取代後繼續排隊。自動 CI 並行鍵已版本化（`CI-v7-*`），所以 GitHub 端舊佇列群組中的僵屍工作不會無限期阻塞較新的 main 執行。手動完整套件執行使用 `CI-manual-v1-*`，且不會取消進行中的執行。
+當較新的推送落在同一個 PR 或 `main` ref 上時，GitHub 可能會將被取代的工作標記為 `cancelled`。除非同一 ref 的最新執行也失敗，否則應將其視為 CI 雜訊。彙總分片檢查使用 `!cancelled() && always()`，因此它們仍會回報一般分片失敗，但不會在整個 workflow 已被取代後繼續排隊。自動 CI concurrency key 已版本化為 (`CI-v7-*`)，因此 GitHub 端舊 queue group 中的殭屍項目無法無限期阻擋較新的 main 執行。手動 full-suite 執行使用 `CI-manual-v1-*`，且不會取消進行中的執行。
 
 ## 範圍與路由
 
-範圍邏輯位於 `scripts/ci-changed-scope.mjs`，並由 `src/scripts/ci-changed-scope.test.ts` 中的 unit tests 覆蓋。手動觸發會略過 changed-scope 偵測，並讓 preflight manifest 表現得像每個 scoped area 都已變更。
+範圍邏輯位於 `scripts/ci-changed-scope.mjs`，並由 `src/scripts/ci-changed-scope.test.ts` 中的 unit tests 涵蓋。手動 dispatch 會略過 changed-scope 偵測，並讓 preflight manifest 表現得像每個有範圍的區域都已變更。
 
-- **CI 工作流程編輯**會驗證 Node CI 圖形與工作流程 linting，但本身不會強制 Windows、Android 或 macOS native builds；這些平台 lane 仍限定於平台原始碼變更。
-- **CI 僅路由編輯、選定的廉價 core-test fixture 編輯，以及狹窄的 plugin contract helper/test-routing 編輯**會使用快速的僅 Node manifest 路徑：`preflight`、security，以及單一 `checks-fast-core` 工作。當變更限於快速工作直接測試的 routing 或 helper surface 時，該路徑會略過 build artifacts、Node 22 compatibility、channel contracts、完整 core shards、bundled-plugin shards，以及 additional guard matrices。
-- **Windows Node 檢查**限定於 Windows 特定 process/path wrappers、npm/pnpm/UI runner helpers、package manager config，以及執行該 lane 的 CI workflow surfaces；不相關的 source、plugin、install-smoke 與 test-only 變更仍留在 Linux Node lane。
+- **CI workflow 編輯**會驗證 Node CI 圖形加上 workflow linting，但不會單獨強制 Windows、Android 或 macOS native builds；這些平台 lane 仍限於平台原始碼變更。
+- **僅 CI 路由編輯、選定的廉價 core-test fixture 編輯，以及狹窄的 plugin contract helper/test-routing 編輯**會使用快速 Node-only manifest 路徑：`preflight`、security，以及單一 `checks-fast-core` 任務。當變更僅限於該快速任務直接執行的路由或 helper 表面時，該路徑會略過 build artifacts、Node 22 compatibility、channel contracts、完整 core shards、bundled-plugin shards 和 additional guard matrices。
+- **Windows Node 檢查**的範圍限於 Windows 特定的 process/path wrappers、npm/pnpm/UI runner helpers、package manager config，以及執行該 lane 的 CI workflow 表面；不相關的原始碼、plugin、install-smoke 和僅測試變更會留在 Linux Node lane 上。
 
-最慢的 Node 測試家族會被拆分或平衡，讓每個工作保持小型且不過度預留 runner：channel contracts 以三個加權分片執行，core unit fast/support lane 分開執行，core runtime infra 分拆為 state 與 process/config shard，auto-reply 以平衡 worker 執行（reply subtree 分拆為 agent-runner、dispatch 與 commands/state-routing shard），agentic gateway/server configs 則分拆到 chat/auth/model/http-plugin/runtime/startup lane，而不是等待 built artifacts。廣泛的 browser、QA、media 與 miscellaneous plugin 測試使用其專用 Vitest configs，而不是共用的 plugin catch-all。Include-pattern shards 會使用 CI shard name 記錄 timing entries，因此 `.artifacts/vitest-shard-timings.json` 可以區分整個 config 與 filtered shard。`check-additional` 將 package-boundary compile/canary 工作放在一起，並將 runtime topology architecture 與 gateway watch coverage 分開；boundary guard list 會橫向分散到四個 matrix shard，每個 shard 會並行執行選定的獨立 guards，並列印每個檢查的 timing，包括 `pnpm prompt:snapshots:check`，因此 Codex runtime happy-path prompt drift 會被釘選到造成它的 PR。Gateway watch、channel tests 與 core support-boundary shard 會在 `dist/` 與 `dist-runtime/` 已建置完成後，在 `build-artifacts` 內並行執行。
+最慢的 Node 測試家族會被拆分或平衡，讓每個工作保持小型而不過度保留 runner：channel contracts 以三個加權分片執行，core unit fast/support lane 分開執行，core runtime infra 在 state 與 process/config 分片之間拆分，auto-reply 以平衡 worker 執行（reply subtree 拆成 agent-runner、dispatch 和 commands/state-routing 分片），而 agentic gateway/server config 則跨 chat/auth/model/http-plugin/runtime/startup lane 拆分，而不是等待已建置成品。廣泛的 browser、QA、media 和 miscellaneous plugin 測試使用其專用 Vitest config，而不是共享 plugin catch-all。Include-pattern 分片使用 CI 分片名稱記錄 timing entries，因此 `.artifacts/vitest-shard-timings.json` 可以區分整個 config 與 filtered shard。`check-additional` 將 package-boundary compile/canary 工作放在一起，並將 runtime topology architecture 與 gateway watch coverage 分離；boundary guard list 橫向切成四個 matrix shards，每個分片同時執行選定的獨立 guards 並列印各檢查 timing，包括 `pnpm prompt:snapshots:check`，因此 Codex runtime happy-path prompt drift 會被固定到造成它的 PR。Gateway watch、channel tests 和 core support-boundary shard 會在 `dist/` 和 `dist-runtime/` 已建置後，於 `build-artifacts` 內同時執行。
 
-Android CI 會執行 `testPlayDebugUnitTest` 與 `testThirdPartyDebugUnitTest`，接著建置 Play debug APK。third-party flavor 沒有獨立的 source set 或 manifest；其 unit-test lane 仍會使用 SMS/call-log BuildConfig flags 編譯該 flavor，同時避免在每個 Android 相關推送上執行重複的 debug APK packaging 工作。
+Android CI 會同時執行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然後建置 Play debug APK。third-party flavor 沒有獨立的 source set 或 manifest；其 unit-test lane 仍會使用 SMS/call-log BuildConfig flags 編譯該 flavor，同時避免在每次 Android 相關推送上執行重複的 debug APK packaging 工作。
 
-`check-dependencies` shard 會執行 `pnpm deadcode:dependencies`（production Knip 僅相依套件檢查，釘選到最新 Knip 版本，且為 `dlx` 安裝停用 pnpm 的 minimum release age）與 `pnpm deadcode:unused-files`，後者會將 Knip 的 production unused-file findings 與 `scripts/deadcode-unused-files.allowlist.mjs` 比對。當 PR 新增未審查的未使用檔案，或留下過時的 allowlist entry 時，unused-file guard 會失敗，同時保留 Knip 無法靜態解析的刻意 dynamic plugin、generated、build、live-test 與 package bridge surfaces。
+`check-dependencies` 分片執行 `pnpm deadcode:dependencies`（固定到最新 Knip 版本的生產 Knip 僅相依性 pass，且為 `dlx` install 停用 pnpm 的 minimum release age）和 `pnpm deadcode:unused-files`，後者會將 Knip 的生產未使用檔案發現項目與 `scripts/deadcode-unused-files.allowlist.mjs` 比較。當 PR 新增未審核的未使用檔案或留下過時的 allowlist entry 時，unused-file guard 會失敗，同時保留 Knip 無法靜態解析的有意動態 plugin、generated、build、live-test 和 package bridge 表面。
 
 ## ClawSweeper 活動轉送
 
-`.github/workflows/clawsweeper-dispatch.yml` 是從 OpenClaw repository activity 到 ClawSweeper 的目標端橋接。它不會 checkout 或執行不受信任的 pull request code。此 workflow 會從 `CLAWSWEEPER_APP_PRIVATE_KEY` 建立 GitHub App token，接著將精簡的 `repository_dispatch` payloads dispatch 到 `openclaw/clawsweeper`。
+`.github/workflows/clawsweeper-dispatch.yml` 是從 OpenClaw repository activity 進入 ClawSweeper 的目標端橋接器。它不會 checkout 或執行不受信任的 pull request code。該 workflow 會從 `CLAWSWEEPER_APP_PRIVATE_KEY` 建立 GitHub App token，然後將精簡的 `repository_dispatch` payloads dispatch 到 `openclaw/clawsweeper`。
 
-此 workflow 有四個 lane：
+該 workflow 有四個 lane：
 
-- `clawsweeper_item` 用於精確的 issue 與 pull request review requests；
-- `clawsweeper_comment` 用於 issue comments 中的明確 ClawSweeper commands；
+- `clawsweeper_item` 用於精確的 issue 和 pull request review requests；
+- `clawsweeper_comment` 用於 issue comments 中明確的 ClawSweeper commands；
 - `clawsweeper_commit_review` 用於 `main` pushes 上的 commit-level review requests；
 - `github_activity` 用於 ClawSweeper agent 可能檢查的一般 GitHub activity。
 
-`github_activity` lane 只會轉送正規化 metadata：event type、action、actor、repository、item number、URL、title、state，以及存在時的 comments 或 reviews 短摘錄。它刻意避免轉送完整 webhook body。`openclaw/clawsweeper` 中的接收 workflow 是 `.github/workflows/github-activity.yml`，會將正規化 event 發布到 OpenClaw Gateway hook，供 ClawSweeper agent 使用。
+`github_activity` lane 只轉送正規化的 metadata：event type、action、actor、repository、item number、URL、title、state，以及存在時的 comments 或 reviews 短 excerpt。它刻意避免轉送完整 webhook body。`openclaw/clawsweeper` 中的接收 workflow 是 `.github/workflows/github-activity.yml`，會將正規化 event 發布到 ClawSweeper agent 的 OpenClaw Gateway hook。
 
-一般 activity 是觀察，而非預設投遞。ClawSweeper agent 會在其 prompt 中收到 Discord target，且只有在事件令人意外、可行、有風險或對營運有用時，才應發布到 `#clawsweeper`。例行 opens、edits、bot churn、duplicate webhook noise 與一般 review traffic 應產生 `NO_REPLY`。
+一般活動是觀察，不是預設交付。ClawSweeper agent 會在 prompt 中收到 Discord target，且只有在事件令人意外、可行動、有風險或具操作用途時，才應發布到 `#clawsweeper`。例行 open、edit、bot churn、duplicate webhook noise 和正常 review traffic 應產生 `NO_REPLY`。
 
-在整個路徑中，請將 GitHub titles、comments、bodies、review text、branch names 與 commit messages 視為不受信任的資料。它們是 summarization 與 triage 的輸入，不是 workflow 或 agent runtime 的指令。
+在整個路徑中，請將 GitHub titles、comments、bodies、review text、branch names 和 commit messages 視為不受信任的資料。它們是 summarization 和 triage 的輸入，不是 workflow 或 agent runtime 的指令。
 
-## 手動觸發
+## 手動 dispatches
 
-手動 CI 派送會執行與一般 CI 相同的工作圖，但會強制啟用每個非 Android 範圍的通道：Linux Node 分片、 bundled-Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置 smoke、文件檢查、Python Skills、Windows、macOS，以及 Control UI i18n。獨立手動 CI 派送只會在 `include_android=true` 時執行 Android；完整發行總控流程會透過傳遞 `include_android=true` 啟用 Android。Plugin 預發行靜態檢查、僅限發行的 `agentic-plugins` 分片、完整擴充功能批次掃描，以及 Plugin 預發行 Docker 通道會排除在 CI 之外。Docker 預發行套件只會在 `Full Release Validation` 派送已啟用發行驗證 gate 的獨立 `Plugin Prerelease` 工作流程時執行。
+手動 CI 分派會執行與一般 CI 相同的工作圖，但會強制啟用所有非 Android 範圍的通道：Linux Node 分片、隨附 Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python skills、Windows、macOS，以及 Control UI i18n。獨立的手動 CI 分派只會在 `include_android=true` 時執行 Android；完整發布總控會透過傳入 `include_android=true` 啟用 Android。Plugin 預發布靜態檢查、僅發布用的 `agentic-plugins` 分片、完整 extension 批次掃描，以及 Plugin 預發布 Docker 通道會從 CI 中排除。Docker 預發布套件只會在 `Full Release Validation` 分派個別的 `Plugin Prerelease` 工作流程，且啟用發布驗證閘門時執行。
 
-手動執行會使用唯一的並行群組，因此發行候選完整套件不會被同一個 ref 上的其他 push 或 PR 執行取消。選用的 `target_ref` 輸入可讓受信任的呼叫端針對分支、標籤或完整 commit SHA 執行該圖，同時使用所選派送 ref 的工作流程檔案。
+手動執行會使用唯一的並行群組，因此發布候選的完整套件不會被同一 ref 上的另一個推送或 PR 執行取消。選用的 `target_ref` 輸入可讓受信任的呼叫者在使用所選分派 ref 的工作流程檔案時，針對分支、標籤或完整 commit SHA 執行該圖。
 
 ```bash
 gh workflow run ci.yml --ref release/YYYY.M.D
@@ -100,15 +100,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
 
 | 執行器                           | 工作                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ubuntu-24.04`                   | `preflight`、快速安全性工作與彙總（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速協定/合約/bundled 檢查、分片通道合約檢查、除 lint 外的 `check` 分片、`check-additional` 分片與彙總、Node 測試彙總驗證器、文件檢查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 託管的 Ubuntu，讓 Blacksmith 矩陣可以更早排隊 |
-| `blacksmith-4vcpu-ubuntu-2404`   | `CodeQL Critical Quality`、較低權重的擴充功能分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types`                                                                                                                                                                                                                                                                                                                   |
-| `blacksmith-8vcpu-ubuntu-2404`   | `build-artifacts`、build-smoke、Linux Node 測試分片、bundled Plugin 測試分片、`android`                                                                                                                                                                                                                                                                                                                                                                           |
-| `blacksmith-16vcpu-ubuntu-2404`  | `check-lint`（對 CPU 足夠敏感，8 vCPU 的成本高於節省的時間）；install-smoke Docker 建置（32-vCPU 排隊時間的成本高於節省的時間）                                                                                                                                                                                                                                                                                                                     |
+| `ubuntu-24.04`                   | `preflight`、快速安全性工作與彙總（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速協定/合約/隨附檢查、分片通道合約檢查、除了 lint 之外的 `check` 分片、`check-additional` 分片與彙總、Node 測試彙總驗證器、文件檢查、Python skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也會使用 GitHub 託管的 Ubuntu，因此 Blacksmith 矩陣可以更早排隊 |
+| `blacksmith-4vcpu-ubuntu-2404`   | `CodeQL Critical Quality`、較低權重的 extension 分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types`，以及 `check-test-types`                                                                                                                                                                                                                                                                                                                   |
+| `blacksmith-8vcpu-ubuntu-2404`   | `build-artifacts`、build-smoke、Linux Node 測試分片、隨附 Plugin 測試分片、`android`                                                                                                                                                                                                                                                                                                                                                                           |
+| `blacksmith-16vcpu-ubuntu-2404`  | `check-lint`（對 CPU 足夠敏感，以致 8 vCPU 花費比節省更多）；install-smoke Docker 建置（32-vCPU 佇列時間成本比節省更多）                                                                                                                                                                                                                                                                                                                     |
 | `blacksmith-16vcpu-windows-2025` | `checks-windows`                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `blacksmith-6vcpu-macos-latest`  | `openclaw/openclaw` 上的 `macos-node`；fork 會退回 `macos-latest`                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 會退回 `macos-latest`                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `blacksmith-6vcpu-macos-latest`  | `openclaw/openclaw` 上的 `macos-node`；fork 會退回到 `macos-latest`                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 會退回到 `macos-latest`                                                                                                                                                                                                                                                                                                                                                                                                 |
 
-## 本機對等項目
+## 本機對應指令
 
 ```bash
 pnpm changed:lanes                            # inspect the local changed-lane classifier for origin/main...HEAD
@@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
 
 ## OpenClaw 效能
 
-`OpenClaw Performance` 是產品/執行階段效能工作流程。它每天在 `main` 上執行，也可以手動派送：
+`OpenClaw Performance` 是產品/執行階段效能工作流程。它每天在 `main` 上執行，也可以手動分派：
 
 ```bash
 gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@@ -145,27 +145,25 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
 ```
 
-手動派送通常會對工作流程 ref 進行基準測試。設定 `target_ref` 可使用目前的工作流程實作，對發行標籤或其他分支進行基準測試。已發布的報告路徑與最新指標會依受測 ref 建立索引，而每個 `index.md` 都會記錄受測 ref/SHA、工作流程 ref/SHA、Kova ref、設定檔、通道驗證模式、模型、重複次數，以及情境篩選器。
+手動分派通常會對工作流程 ref 進行基準測試。設定 `target_ref` 可使用目前的工作流程實作，對發布標籤或另一個分支進行基準測試。已發布的報告路徑與最新指標會依測試的 ref 作為索引鍵，且每個 `index.md` 都會記錄測試的 ref/SHA、工作流程 ref/SHA、Kova ref、profile、通道授權模式、模型、重複次數，以及情境篩選器。
 
-工作流程會從釘選的發行版本安裝 OCM，並從 `openclaw/Kova` 的釘選 `kova_ref` 輸入安裝 Kova，接著執行三個通道：
+工作流程會從釘選的發布安裝 OCM，並從 `openclaw/Kova` 的釘選 `kova_ref` 輸入安裝 Kova，接著執行三個通道：
 
-- `mock-provider`：使用確定性的假 OpenAI 相容驗證，針對本機建置執行階段執行 Kova 診斷情境。
-- `mock-deep-profile`：針對啟動、Gateway 和 agent-turn 熱點進行 CPU/heap/trace profiling。
-- `live-gpt54`：真實的 OpenAI `openai/gpt-5.4` agent turn，當 `OPENAI_API_KEY` 無法使用時會跳過。
+- `mock-provider`：Kova 診斷情境，針對使用確定性假 OpenAI 相容授權的本機建置執行階段。
+- `mock-deep-profile`：針對啟動、Gateway，以及代理程式回合熱點的 CPU/heap/trace profiling。
+- `live-gpt54`：真實 OpenAI `openai/gpt-5.4` 代理程式回合，當 `OPENAI_API_KEY` 無法使用時略過。
 
-mock-provider 通道也會在 Kova pass 之後執行 OpenClaw 原生原始碼探針：預設、hook 和 50-Plugin 啟動案例中的 Gateway 啟動時間與記憶體；重複的 mock-OpenAI `channel-chat-baseline` hello 迴圈；以及針對已啟動 Gateway 的 CLI 啟動命令。原始碼探針 Markdown 摘要位於報告 bundle 的 `source/index.md`，旁邊附有原始 JSON。
+mock-provider 通道也會在 Kova 通過後執行 OpenClaw 原生原始碼探測：預設、hook 與 50-Plugin 啟動案例中的 Gateway 啟動計時與記憶體；重複的 mock-OpenAI `channel-chat-baseline` hello 迴圈；以及針對已啟動 Gateway 的 CLI 啟動命令。原始碼探測 Markdown 摘要位於報告套件中的 `source/index.md`，原始 JSON 則在旁邊。
 
-每個通道都會上傳 GitHub artifacts。設定 `CLAWGRIT_REPORTS_TOKEN` 時，工作流程也會將 `report.json`、`report.md`、bundles、`index.md` 和原始碼探針 artifacts 提交到 `openclaw/clawgrit-reports` 的 `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/` 底下。目前受測 ref 指標會寫入為 `openclaw-performance/<tested-ref>/latest-<lane>.json`。
+每個通道都會上傳 GitHub artifacts。設定 `CLAWGRIT_REPORTS_TOKEN` 時，工作流程也會將 `report.json`、`report.md`、套件、`index.md`，以及原始碼探測 artifacts 提交到 `openclaw/clawgrit-reports` 的 `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/` 底下。目前測試 ref 指標會寫入為 `openclaw-performance/<tested-ref>/latest-<lane>.json`。
 
-## 完整發行驗證
+## 完整發布驗證
 
-`Full Release Validation` 是用於「發行前執行所有項目」的手動總控工作流程。它接受分支、標籤或完整 commit SHA，使用該目標派送手動 `CI` 工作流程，派送 `Plugin Prerelease` 以取得僅限發行的 Plugin/package/static/Docker 證明，並派送 `OpenClaw Release Checks` 以執行 install smoke、package acceptance、Docker release-path 套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。使用 `rerun_group=all` 和 `release_profile=full` 時，它也會針對 release checks 的 `release-package-under-test` artifact 執行 `NPM Telegram Beta E2E`。發布後，傳遞 `npm_telegram_package_spec` 可針對已發布的 npm package 重新執行相同的 Telegram package 通道。
+`Full Release Validation` 是用於「發布前執行所有項目」的手動總控工作流程。它接受分支、標籤或完整 commit SHA，使用該目標分派手動 `CI` 工作流程，分派 `Plugin Prerelease` 以取得僅發布用的 Plugin/套件/靜態/Docker 證明，並分派 `OpenClaw Release Checks` 以進行安裝煙霧測試、套件驗收、跨 OS 套件檢查、QA Lab parity、Matrix，以及 Telegram 通道。穩定/預設執行會將詳盡的 live/E2E 與 Docker 發布路徑覆蓋保留在 `run_release_soak=true` 後方；`release_profile=full` 會強制啟用該 soak 覆蓋，因此廣泛 advisory 驗證仍會保持廣泛。使用 `rerun_group=all` 與 `release_profile=full` 時，它也會針對來自發布檢查的 `release-package-under-test` artifact 執行 `NPM Telegram Beta E2E`。發布後，傳入 `npm_telegram_package_spec` 可針對已發布的 npm 套件重新執行相同的 Telegram 套件通道。
 
-請參閱 [完整發行驗證](/zh-TW/reference/full-release-validation)，了解
-階段矩陣、精確的工作流程工作名稱、設定檔差異、artifacts，以及
-聚焦重新執行控制代碼。
+請參閱[完整發布驗證](/zh-TW/reference/full-release-validation)，了解階段矩陣、確切的工作流程工作名稱、profile 差異、artifacts，以及聚焦重新執行控制代碼。
 
-`OpenClaw Release Publish` 是會進行變更的手動發行工作流程。在發行標籤存在且 OpenClaw npm preflight 成功後，從 `release/YYYY.M.D` 或 `main` 派送它。它會驗證 `pnpm plugins:sync:check`，針對所有可發布的 Plugin packages 派送 `Plugin NPM Release`，針對相同發行 SHA 派送 `Plugin ClawHub Release`，然後才會使用已儲存的 `preflight_run_id` 派送 `OpenClaw NPM Release`。
+`OpenClaw Release Publish` 是手動且會變更狀態的發布工作流程。在發布標籤存在且 OpenClaw npm preflight 成功後，從 `release/YYYY.M.D` 或 `main` 分派它。它會驗證 `pnpm plugins:sync:check`，為所有可發布的 Plugin 套件分派 `Plugin NPM Release`，為相同的發布 SHA 分派 `Plugin ClawHub Release`，然後才使用已儲存的 `preflight_run_id` 分派 `OpenClaw NPM Release`。
 
 ```bash
 gh workflow run openclaw-release-publish.yml \
@@ -175,40 +173,35 @@ gh workflow run openclaw-release-publish.yml \
   -f npm_dist_tag=beta
 ```
 
-若要在快速移動的分支上取得釘選 commit 證明，請使用 helper，而不是
-`gh workflow run ... --ref main -f ref=<sha>`：
+若要在快速變動分支上取得釘選 commit 證明，請使用輔助程式，而不是 `gh workflow run ... --ref main -f ref=<sha>`：
 
 ```bash
 pnpm ci:full-release --sha <full-sha>
 ```
 
-GitHub 工作流程派送 ref 必須是分支或標籤，不能是原始 commit SHA。此
-helper 會在目標 SHA 推送暫時的 `release-ci/<sha>-...` 分支，
-從該釘選 ref 派送 `Full Release Validation`，驗證每個子
-工作流程的 `headSha` 都符合目標，並在執行完成時刪除暫時分支。如果任何子工作流程在
-不同的 SHA 上執行，總控驗證器也會失敗。
+GitHub 工作流程分派 ref 必須是分支或標籤，不能是原始 commit SHA。輔助程式會在目標 SHA 推送一個臨時的 `release-ci/<sha>-...` 分支，從該釘選 ref 分派 `Full Release Validation`，驗證每個子工作流程的 `headSha` 都符合目標，並在執行完成時刪除臨時分支。如果任何子工作流程在不同 SHA 上執行，總控驗證器也會失敗。
 
-`release_profile` 控制傳遞給 release 檢查的 live/提供者涵蓋範圍。手動 release workflow 預設為 `stable`；只有在你刻意想要廣泛的 advisory 提供者/媒體矩陣時，才使用 `full`。
+`release_profile` 控制傳入發行檢查的即時/供應商涵蓋範圍。手動發行工作流程預設為 `stable`；只有在你刻意需要寬廣的 advisory 供應商/媒體矩陣時，才使用 `full`。`run_release_soak` 控制 stable/預設發行檢查是否執行完整的即時/E2E 與 Docker 發行路徑 soak；`full` 會強制啟用 soak。
 
-- `minimum` 保留最快的 OpenAI/核心 release 關鍵 lane。
-- `stable` 加入穩定的提供者/後端集合。
-- `full` 執行廣泛的 advisory 提供者/媒體矩陣。
+- `minimum` 保留最快的 OpenAI/核心發行關鍵通道。
+- `stable` 加入穩定的供應商/後端集合。
+- `full` 執行寬廣的 advisory 供應商/媒體矩陣。
 
-umbrella 會記錄已派發的子執行 ID，而最後的 `Verify full validation` job 會重新檢查目前子執行的結論，並為每個子執行附加最慢 job 表格。如果某個子 workflow 重新執行後轉綠，只需重新執行父層 verifier job，就能刷新 umbrella 結果與時間摘要。
+umbrella 會記錄已派發的子執行 ID，最終的 `Verify full validation` 工作會重新檢查目前子執行結論，並為每個子執行附加最慢工作表格。如果子工作流程重新執行後轉為綠燈，只需重新執行父驗證器工作，即可重新整理 umbrella 結果與時間摘要。
 
-針對復原，`Full Release Validation` 與 `OpenClaw Release Checks` 都接受 `rerun_group`。release candidate 使用 `all`，只要一般完整 CI 子項使用 `ci`，只要 Plugin prerelease 子項使用 `plugin-prerelease`，每個 release 子項使用 `release-checks`，或在 umbrella 上使用更窄的群組：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。這能讓失敗的 release box 在聚焦修正後，重新執行的範圍保持有界。
+復原時，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。發行候選版本使用 `all`，只針對一般完整 CI 子流程使用 `ci`，只針對 Plugin prerelease 子流程使用 `plugin-prerelease`，針對每個發行子流程使用 `release-checks`，或在 umbrella 上使用更窄的群組：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。這能讓失敗的發行機器在聚焦修正後只進行有限範圍的重新執行。若只有一個跨 OS 通道失敗，請將 `rerun_group=cross-os` 與 `cross_os_suite_filter` 搭配使用，例如 `windows/packaged-upgrade`；長時間的跨 OS 命令會輸出 heartbeat 行，packaged-upgrade 摘要會包含各階段計時。QA release-check 通道屬於 advisory，因此只有 QA 失敗時會提出警告，但不會阻擋 release-check 驗證器。
 
-`OpenClaw Release Checks` 使用受信任的 workflow ref，將選定 ref 解析一次為 `release-package-under-test` tarball，然後把該 artifact 傳給 live/E2E release-path Docker workflow 與 package acceptance shard。這能讓 package 位元組在各個 release box 之間保持一致，並避免在多個子 job 中重新打包同一個候選項。
+`OpenClaw Release Checks` 會使用受信任的工作流程 ref，將所選 ref 一次解析為 `release-package-under-test` tarball，然後把該成品傳給跨 OS 檢查和 Package Acceptance，並在執行 soak 涵蓋時傳給即時/E2E 發行路徑 Docker 工作流程。這能讓套件位元組在各發行機器之間保持一致，並避免在多個子工作中重複封裝同一個候選版本。
 
-`ref=main` 與 `rerun_group=all` 的重複 `Full Release Validation` 執行會取代較舊的 umbrella。當父層被取消時，父層 monitor 會取消任何它已派發的子 workflow，因此較新的 main validation 不會卡在過時的兩小時 release-check 執行後面。Release branch/tag validation 與聚焦 rerun group 會保留 `cancel-in-progress: false`。
+對於 `ref=main` 和 `rerun_group=all` 的重複 `Full Release Validation` 執行，較新的 umbrella 會取代較舊的 umbrella。父監視器在父流程被取消時，會取消其已派發的任何子工作流程，因此較新的 main 驗證不會排在過時的兩小時 release-check 執行後面。發行分支/標籤驗證與聚焦重新執行群組會保持 `cancel-in-progress: false`。
 
-## Live 與 E2E 分片
+## 即時與 E2E 分片
 
-release live/E2E 子項保留廣泛的原生 `pnpm test:live` 涵蓋範圍，但它會透過 `scripts/test-live-shard.mjs` 以命名分片執行，而不是一個序列 job：
+發行即時/E2E 子流程保留寬廣的原生 `pnpm test:live` 涵蓋範圍，但它會透過 `scripts/test-live-shard.mjs` 以具名分片執行，而不是單一序列工作：
 
 - `native-live-src-agents`
 - `native-live-src-gateway-core`
-- 提供者篩選的 `native-live-src-gateway-profiles` job
+- 依供應商篩選的 `native-live-src-gateway-profiles` 工作
 - `native-live-src-gateway-backends`
 - `native-live-test`
 - `native-live-extensions-a-k`
@@ -216,59 +209,59 @@ release live/E2E 子項保留廣泛的原生 `pnpm test:live` 涵蓋範圍，但
 - `native-live-extensions-openai`
 - `native-live-extensions-o-z-other`
 - `native-live-extensions-xai`
-- 分割的媒體音訊/影片分片與提供者篩選的音樂分片
+- 拆分的媒體音訊/影片分片，以及依供應商篩選的音樂分片
 
-這會保留相同的檔案涵蓋範圍，同時讓緩慢的 live 提供者失敗更容易重新執行與診斷。彙總的 `native-live-extensions-o-z`、`native-live-extensions-media` 與 `native-live-extensions-media-music` 分片名稱仍可用於手動一次性重新執行。
+這會保留相同的檔案涵蓋範圍，同時讓緩慢的即時供應商失敗更容易重新執行與診斷。彙總的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` 分片名稱仍可用於手動一次性重新執行。
 
-原生 live 媒體分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中執行，該映像由 `Live Media Runner Image` workflow 建置。該映像預先安裝 `ffmpeg` 與 `ffprobe`；媒體 job 只會在設定前驗證這些 binary。讓 Docker 支援的 live suite 保持在一般 Blacksmith runner 上執行；container job 不是啟動巢狀 Docker 測試的正確位置。
+原生即時媒體分片會在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中執行，該映像由 `Live Media Runner Image` 工作流程建置。該映像預先安裝 `ffmpeg` 和 `ffprobe`；媒體工作只會在設定前驗證二進位檔。請將 Docker 支援的即時套件保留在一般 Blacksmith runner 上執行，容器工作不適合啟動巢狀 Docker 測試。
 
-Docker 支援的 live model/後端分片會針對每個選定 commit 使用獨立共用的 `ghcr.io/openclaw/openclaw-live-test:<sha>` 映像。live release workflow 會建置並推送該映像一次，然後 Docker live model、提供者分片的 Gateway、CLI 後端、ACP bind 與 Codex harness 分片會以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行。Gateway Docker 分片在 script 層級帶有明確的 `timeout` 上限，低於 workflow job timeout，因此卡住的 container 或 cleanup path 會快速失敗，而不是耗盡整個 release-check 預算。如果這些分片各自重新建置完整 source Docker target，表示 release 執行設定錯誤，會把 wall clock 浪費在重複的映像建置上。
+Docker 支援的即時模型/後端分片會針對每個所選提交使用個別共享的 `ghcr.io/openclaw/openclaw-live-test:<sha>` 映像。即時發行工作流程會建置並推送該映像一次，然後 Docker 即時模型、依供應商分片的 Gateway、CLI 後端、ACP bind 和 Codex harness 分片會以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行。Gateway Docker 分片在指令碼層級帶有明確的 `timeout` 上限，低於工作流程工作逾時，讓卡住的容器或清理路徑能快速失敗，而不是耗完整個 release-check 預算。如果這些分片各自重新建置完整的來源 Docker 目標，代表發行執行設定錯誤，會把時間浪費在重複映像建置上。
 
 ## Package Acceptance
 
-當問題是「這個可安裝的 OpenClaw package 是否能作為產品運作？」時，請使用 `Package Acceptance`。它不同於一般 CI：一般 CI 驗證 source tree，而 package acceptance 會透過使用者在安裝或更新後會執行的同一套 Docker E2E harness，驗證單一 tarball。
+當問題是「這個可安裝的 OpenClaw 套件作為產品是否可用？」時，請使用 `Package Acceptance`。它不同於一般 CI：一般 CI 驗證來源樹，而 package acceptance 會透過使用者安裝或更新後會使用的同一套 Docker E2E harness，驗證單一 tarball。
 
-### Job
+### 工作
 
-1. `resolve_package` 會 checkout `workflow_ref`、解析一個 package 候選項、寫入 `.artifacts/docker-e2e-package/openclaw-current.tgz`、寫入 `.artifacts/docker-e2e-package/package-candidate.json`、將兩者上傳為 `package-under-test` artifact，並在 GitHub step summary 中列印來源、workflow ref、package ref、版本、SHA-256 與 profile。
-2. `docker_acceptance` 會以 `ref=workflow_ref` 與 `package_artifact_name=package-under-test` 呼叫 `openclaw-live-and-e2e-checks-reusable.yml`。可重用 workflow 會下載該 artifact、驗證 tarball inventory、在需要時準備 package-digest Docker 映像，並針對該 package 執行選定的 Docker lane，而不是打包 workflow checkout。當某個 profile 選取多個目標 `docker_lanes` 時，可重用 workflow 會準備 package 與共用映像一次，然後將這些 lane 展開成平行的目標 Docker job，並使用唯一 artifact。
-3. `package_telegram` 可選擇性呼叫 `NPM Telegram Beta E2E`。當 `telegram_mode` 不是 `none` 時會執行，而且在 Package Acceptance 解析出一個 package 時會安裝相同的 `package-under-test` artifact；獨立 Telegram dispatch 仍可安裝已發布的 npm spec。
-4. `summary` 會在 package 解析、Docker acceptance 或可選的 Telegram lane 失敗時，讓 workflow 失敗。
+1. `resolve_package` 會 checkout `workflow_ref`、解析一個套件候選版本、寫入 `.artifacts/docker-e2e-package/openclaw-current.tgz`、寫入 `.artifacts/docker-e2e-package/package-candidate.json`、將兩者作為 `package-under-test` 成品上傳，並在 GitHub 步驟摘要中列印來源、工作流程 ref、套件 ref、版本、SHA-256 和 profile。
+2. `docker_acceptance` 會以 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 呼叫 `openclaw-live-and-e2e-checks-reusable.yml`。可重用工作流程會下載該成品、驗證 tarball 清單、在需要時準備 package-digest Docker 映像，並針對該套件執行所選 Docker 通道，而不是封裝工作流程 checkout。當某個 profile 選取多個目標 `docker_lanes` 時，可重用工作流程會準備套件與共享映像一次，然後將這些通道扇出為平行的目標 Docker 工作，並使用唯一成品。
+3. `package_telegram` 可選擇性呼叫 `NPM Telegram Beta E2E`。當 `telegram_mode` 不是 `none` 時會執行，並在 Package Acceptance 解析出套件時安裝相同的 `package-under-test` 成品；獨立 Telegram 派發仍可安裝已發布的 npm spec。
+4. 若套件解析、Docker acceptance 或可選 Telegram 通道失敗，`summary` 會讓工作流程失敗。
 
 ### 候選來源
 
-- `source=npm` 只接受 `openclaw@beta`、`openclaw@latest`，或精確的 OpenClaw release 版本，例如 `openclaw@2026.4.27-beta.2`。將此用於已發布 prerelease/stable acceptance。
-- `source=ref` 會打包受信任的 `package_ref` branch、tag 或完整 commit SHA。resolver 會擷取 OpenClaw branch/tag，驗證選定 commit 可從 repository branch history 或 release tag 抵達，在 detached worktree 中安裝 deps，並用 `scripts/package-openclaw-for-docker.mjs` 打包。
+- `source=npm` 只接受 `openclaw@beta`、`openclaw@latest`，或確切的 OpenClaw 發行版本，例如 `openclaw@2026.4.27-beta.2`。請用於已發布的 prerelease/stable acceptance。
+- `source=ref` 會封裝受信任的 `package_ref` 分支、標籤或完整提交 SHA。解析器會擷取 OpenClaw 分支/標籤、驗證所選提交可從儲存庫分支歷史或發行標籤到達、在 detached worktree 中安裝依賴項，並用 `scripts/package-openclaw-for-docker.mjs` 封裝。
 - `source=url` 會下載 HTTPS `.tgz`；必須提供 `package_sha256`。
-- `source=artifact` 會從 `artifact_run_id` 與 `artifact_name` 下載一個 `.tgz`；`package_sha256` 為選填，但對外部分享的 artifact 應提供。
+- `source=artifact` 會從 `artifact_run_id` 和 `artifact_name` 下載一個 `.tgz`；`package_sha256` 可選，但外部共享成品應提供。
 
-保持 `workflow_ref` 與 `package_ref` 分離。`workflow_ref` 是執行測試的受信任 workflow/harness code。`package_ref` 是當 `source=ref` 時會被打包的 source commit。這讓目前的 test harness 能驗證較舊的受信任 source commit，而不執行舊的 workflow logic。
+請保持 `workflow_ref` 和 `package_ref` 分離。`workflow_ref` 是執行測試的受信任工作流程/harness 程式碼。`package_ref` 是 `source=ref` 時會被封裝的來源提交。這讓目前的測試 harness 能驗證較舊的受信任來源提交，而不執行舊的工作流程邏輯。
 
-### Suite profile
+### 套件 profile
 
 - `smoke` — `npm-onboard-channel-agent`、`gateway-network`、`config-reload`
 - `package` — `npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`upgrade-survivor`、`published-upgrade-survivor`、`plugins-offline`、`plugin-update`
 - `product` — `package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui`
-- `full` — 含 OpenWebUI 的完整 Docker release-path chunk
+- `full` — 搭配 OpenWebUI 的完整 Docker 發行路徑區塊
 - `custom` — 精確的 `docker_lanes`；當 `suite_profile=custom` 時必填
 
-`package` profile 使用離線 Plugin 涵蓋範圍，因此已發布 package validation 不會受制於 live ClawHub 可用性。可選的 Telegram lane 會在 `NPM Telegram Beta E2E` 中重用 `package-under-test` artifact，而已發布 npm spec path 則保留給獨立 dispatch。
+`package` profile 使用離線 Plugin 涵蓋，因此已發布套件驗證不會受限於 ClawHub 即時可用性。可選 Telegram 通道會在 `NPM Telegram Beta E2E` 中重用 `package-under-test` 成品，並保留已發布 npm spec 路徑供獨立派發使用。
 
-若要了解專用的更新與 Plugin 測試政策，包括本機指令、Docker lane、Package Acceptance 輸入、release 預設值與失敗分流，請參閱[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。
+如需專門的更新與 Plugin 測試政策，包括本機命令、Docker 通道、Package Acceptance 輸入、發行預設值與失敗分流，請參閱[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。
 
-Release 檢查會以 `source=artifact`、準備好的 release package artifact、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 與 `telegram_mode=mock-openai` 呼叫 Package Acceptance。這讓 package migration、update、過時 Plugin dependency cleanup、已設定 Plugin install repair、離線 Plugin、plugin-update 與 Telegram proof 都在同一個已解析 package tarball 上執行。在 Full Release Validation 或 OpenClaw Release Checks 上設定 `package_acceptance_package_spec`，即可針對已出貨的 npm package 執行相同矩陣，而不是針對以 SHA 建置的 artifact。Cross-OS release 檢查仍涵蓋 OS 特定的 onboarding、installer 與 platform 行為；package/update product validation 應從 Package Acceptance 開始。`published-upgrade-survivor` Docker lane 每次執行會驗證一個已發布 package baseline。在 Package Acceptance 中，解析出的 `package-under-test` tarball 永遠是候選項，而 `published_upgrade_survivor_baseline` 會選取 fallback 已發布 baseline，預設為 `openclaw@latest`；失敗 lane 的重新執行指令會保留該 baseline。設定 `published_upgrade_survivor_baselines=all-since-2026.4.23`，可將 Full Release CI 擴展到從 `2026.4.23` 到 `latest` 的每個 stable npm release；`release-history` 仍可用於手動進行更廣泛取樣，並使用較舊的 pre-date anchor。設定 `published_upgrade_survivor_scenarios=reported-issues`，可將相同 baseline 擴展到 issue 形狀的 fixture，涵蓋 Feishu config、保留的 bootstrap/persona 檔案、已設定的 OpenClaw Plugin 安裝、tilde log path 與過時 legacy Plugin dependency root。獨立的 `Update Migration` workflow 會在問題是徹底的已發布 update cleanup，而不是一般 Full Release CI 廣度時，使用 `update-migration` Docker lane，搭配 `all-since-2026.4.23` 與 `plugin-deps-cleanup`。本機彙總執行可用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 傳入精確 package spec、用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保留單一 lane，例如 `openclaw@2026.4.15`，或設定 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 來執行情境矩陣。已發布 lane 會用烘焙好的 `openclaw config set` 指令配方設定 baseline、在 `summary.json` 記錄配方步驟，並在 Gateway 啟動後探測 `/healthz`、`/readyz` 與 RPC status。Windows packaged 與 installer fresh lane 也會驗證已安裝 package 能從原始絕對 Windows path 匯入 browser-control override。OpenAI cross-OS agent-turn smoke 在有設定時預設使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因此 install 與 Gateway proof 會維持在 GPT-5 測試 model 上，同時避免 GPT-4.x 預設值。
+發行檢查會以 `source=artifact`、準備好的發行套件成品、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` 和 `telegram_mode=mock-openai` 呼叫 Package Acceptance。這會讓套件遷移、更新、過時 Plugin 依賴項清理、已設定 Plugin 安裝修復、離線 Plugin、Plugin 更新和 Telegram 證明都使用同一個已解析的套件 tarball。在 Full Release Validation 或 OpenClaw Release Checks 上設定 `package_acceptance_package_spec`，即可針對已出貨的 npm 套件而不是 SHA 建置成品執行同一個矩陣。跨 OS 發行檢查仍涵蓋 OS 特定 onboarding、安裝程式與平台行為；套件/更新產品驗證應從 Package Acceptance 開始。`published-upgrade-survivor` Docker 通道會在阻擋式發行路徑中，每次執行驗證一個已發布套件基準。在 Package Acceptance 中，已解析的 `package-under-test` tarball 永遠是候選版本，而 `published_upgrade_survivor_baseline` 會選取備援已發布基準，預設為 `openclaw@latest`；失敗通道重新執行命令會保留該基準。當 Full Release Validation 設定 `run_release_soak=true` 或 `release_profile=full` 時，會設定 `published_upgrade_survivor_baselines=all-since-2026.4.23` 和 `published_upgrade_survivor_scenarios=reported-issues`，以擴展涵蓋從 `2026.4.23` 到 `latest` 的每個穩定 npm 發行，以及 Feishu 設定、保留的 bootstrap/persona 檔案、已設定的 OpenClaw Plugin 安裝、波浪號記錄路徑與過時 legacy Plugin 依賴項根目錄等議題形狀 fixture。個別的 `Update Migration` 工作流程會在問題是完整已發布更新清理，而不是一般 Full Release CI 廣度時，使用 `update-migration` Docker 通道搭配 `all-since-2026.4.23` 和 `plugin-deps-cleanup`。本機彙總執行可用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 傳入精確套件 spec、用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保留單一通道，例如 `openclaw@2026.4.15`，或設定 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 供情境矩陣使用。已發布通道會用內建的 `openclaw config set` 命令 recipe 設定基準、在 `summary.json` 中記錄 recipe 步驟，並在 Gateway 啟動後探測 `/healthz`、`/readyz` 以及 RPC 狀態。Windows packaged 和 installer fresh 通道也會驗證已安裝套件能從原始絕對 Windows 路徑匯入 browser-control override。OpenAI 跨 OS agent-turn smoke 在有設定時預設使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因此安裝與 Gateway 證明會停留在 GPT-5 測試模型，同時避免 GPT-4.x 預設值。
 
-### Legacy compatibility window
+### Legacy 相容性窗口
 
-Package Acceptance 對已發布 package 有有界的 legacy-compatibility window。到 `2026.4.25` 為止的 package，包括 `2026.4.25-beta.*`，可使用 compatibility path：
+Package Acceptance 對已發布套件有有限範圍的 legacy 相容性窗口。到 `2026.4.25` 為止的套件，包括 `2026.4.25-beta.*`，可使用相容性路徑：
 
-- `dist/postinstall-inventory.json` 中已知的 private QA entry 可能指向 tarball 省略的檔案；
-- 當 package 未公開 `gateway install --wrapper` flag 時，`doctor-switch` 可略過 `gateway install --wrapper` persistence subcase；
-- `update-channel-switch` 可從 tarball 衍生的假 git fixture 中移除缺失的 `pnpm.patchedDependencies`，並可記錄缺失的已保存 `update.channel`；
-- Plugin smoke 可讀取 legacy install-record 位置，或接受缺失的 marketplace install-record persistence；
-- `plugin-update` 可允許 config metadata migration，同時仍要求 install record 與 no-reinstall 行為保持不變。
+- `dist/postinstall-inventory.json` 中的已知私有 QA 項目可指向 tarball 省略的檔案；
+- 當套件未公開該旗標時，`doctor-switch` 可略過 `gateway install --wrapper` 持久化子案例；
+- `update-channel-switch` 可從 tarball 衍生的假 git fixture 中修剪缺失的 `pnpm.patchedDependencies`，並可記錄缺失的持久化 `update.channel`；
+- Plugin smoke 可讀取 legacy 安裝記錄位置，或接受缺失的 marketplace 安裝記錄持久化；
+- `plugin-update` 可允許設定中繼資料遷移，同時仍要求安裝記錄與不重新安裝行為保持不變。
 
-已發布的 `2026.4.26` package 也可能對已出貨的本機建置 metadata stamp 檔案發出警告。之後的 package 必須滿足現代 contract；相同條件會失敗，而不是警告或略過。
+已發布的 `2026.4.26` 套件也可對已經出貨的本機建置中繼資料戳記檔案提出警告。較新的套件必須滿足現代合約；相同條件會失敗，而不是警告或略過。
 
 ### 範例
 
@@ -311,112 +304,112 @@ gh workflow run package-acceptance.yml \
   -f docker_lanes='install-e2e plugin-update'
 ```
 
-偵錯失敗的套件驗收執行時，請從 `resolve_package` 摘要開始，確認套件來源、版本和 SHA-256。接著檢查 `docker_acceptance` 子執行及其 Docker 成品：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道記錄、階段計時，以及重新執行命令。請優先重新執行失敗的套件設定檔或精確的 Docker 通道，而不是重新執行完整發行驗證。
+偵錯失敗的套件驗收執行時，請先從 `resolve_package` 摘要開始，確認套件來源、版本與 SHA-256。接著檢查 `docker_acceptance` 子執行及其 Docker 成品：`.artifacts/docker-tests/**/summary.json`、`failures.json`、通道日誌、階段計時與重新執行命令。優先重新執行失敗的套件設定檔或精確的 Docker 通道，而不是重新執行完整 release 驗證。
 
 ## 安裝煙霧測試
 
-獨立的 `Install Smoke` 工作流程會透過自己的 `preflight` 作業重用相同的範圍指令碼。它會將煙霧測試涵蓋範圍拆分為 `run_fast_install_smoke` 和 `run_full_install_smoke`。
+獨立的 `Install Smoke` workflow 會透過自己的 `preflight` 作業重用相同的範圍指令碼。它會將煙霧測試覆蓋範圍拆分為 `run_fast_install_smoke` 與 `run_full_install_smoke`。
 
-- **快速路徑**會在 pull request 觸及 Docker/套件介面、內建 Plugin 套件/manifest 變更，或 Docker 煙霧測試作業會涵蓋的核心 Plugin/通道/Gateway/Plugin SDK 介面時執行。僅來源的內建 Plugin 變更、僅測試編輯，以及僅文件編輯不會保留 Docker worker。快速路徑會建置根 Dockerfile 映像一次、檢查 CLI、執行 agents delete shared-workspace CLI 煙霧測試、執行容器 gateway-network e2e、驗證內建擴充功能建置參數，並在 240 秒彙總命令逾時內執行有界的內建 Plugin Docker 設定檔（每個情境的 Docker 執行會個別設上限）。
-- **完整路徑**會保留 QR 套件安裝與安裝程式 Docker/更新涵蓋範圍，用於每夜排程執行、手動派送、workflow-call 發行檢查，以及真正觸及安裝程式/套件/Docker 介面的 pull request。在完整模式中，install-smoke 會準備或重用一個目標 SHA 的 GHCR 根 Dockerfile 煙霧測試映像，然後將 QR 套件安裝、根 Dockerfile/Gateway 煙霧測試、安裝程式/更新煙霧測試，以及快速內建 Plugin Docker E2E 作為獨立作業執行，讓安裝程式工作不會被根映像煙霧測試阻塞。
+- **快速路徑** 會在 pull request 觸及 Docker/套件表面、內建 Plugin 套件/manifest 變更，或 Docker 煙霧測試作業會演練的核心 Plugin/通道/Gateway/Plugin SDK 表面時執行。只有原始碼的內建 Plugin 變更、僅測試編輯與僅文件編輯不會保留 Docker worker。快速路徑會建置一次根 Dockerfile 映像、檢查 CLI、執行 agents delete shared-workspace CLI 煙霧測試、執行容器 gateway-network e2e、驗證內建擴充功能建置引數，並在 240 秒彙總命令逾時內執行有界的內建 Plugin Docker 設定檔（每個情境的 Docker 執行各自設上限）。
+- **完整路徑** 會為每晚排程執行、手動派送、workflow-call release 檢查，以及真正觸及安裝程式/套件/Docker 表面的 pull request 保留 QR 套件安裝與安裝程式 Docker/更新覆蓋範圍。在完整模式中，install-smoke 會準備或重用一個目標 SHA 的 GHCR 根 Dockerfile 煙霧測試映像，接著將 QR 套件安裝、根 Dockerfile/Gateway 煙霧測試、安裝程式/更新煙霧測試，以及快速內建 Plugin Docker E2E 作為獨立作業執行，讓安裝程式工作不必等待根映像煙霧測試。
 
-`main` 推送（包括合併提交）不會強制使用完整路徑；當變更範圍邏輯會在推送時要求完整涵蓋範圍，工作流程會保留快速 Docker 煙霧測試，並將完整安裝煙霧測試留給每夜或發行驗證。
+`main` 推送（包含合併提交）不會強制完整路徑；當變更範圍邏輯會在推送上要求完整覆蓋時，workflow 會保留快速 Docker 煙霧測試，並將完整安裝煙霧測試留給每晚或 release 驗證。
 
-較慢的 Bun 全域安裝 image-provider 煙霧測試會由 `run_bun_global_install_smoke` 另行控管。它會在每夜排程和發行檢查工作流程中執行，且手動 `Install Smoke` 派送可以選擇加入，但 pull request 和 `main` 推送不會執行。QR 與安裝程式 Docker 測試會保留各自專注於安裝的 Dockerfile。
+較慢的 Bun 全域安裝 image-provider 煙霧測試會由 `run_bun_global_install_smoke` 個別控管。它會在每晚排程與 release checks workflow 中執行，且手動 `Install Smoke` 派送可選擇加入，但 pull request 與 `main` 推送不會執行。QR 與安裝程式 Docker 測試會保留各自偏重安裝的 Dockerfile。
 
 ## 本機 Docker E2E
 
-`pnpm test:docker:all` 會預先建置一個共用 live-test 映像、將 OpenClaw 打包一次為 npm tarball，並建置兩個共用的 `scripts/e2e/Dockerfile` 映像：
+`pnpm test:docker:all` 會預先建置一個共享的 live-test 映像，將 OpenClaw 封裝一次為 npm tarball，並建置兩個共享的 `scripts/e2e/Dockerfile` 映像：
 
-- 用於安裝程式/更新/Plugin 相依性通道的純 Node/Git runner；
-- 將相同 tarball 安裝到 `/app`，用於一般功能通道的功能性映像。
+- 用於安裝程式/更新/Plugin 相依通道的裸 Node/Git runner；
+- 將同一個 tarball 安裝到 `/app` 中、供一般功能通道使用的功能映像。
 
-Docker 通道定義位於 `scripts/lib/docker-e2e-scenarios.mjs`，規劃器邏輯位於 `scripts/lib/docker-e2e-plan.mjs`，runner 只會執行選取的計畫。排程器會使用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 為每個通道選取映像，然後以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行通道。
+Docker 通道定義位於 `scripts/lib/docker-e2e-scenarios.mjs`，規劃器邏輯位於 `scripts/lib/docker-e2e-plan.mjs`，runner 只會執行選取的計畫。排程器會透過 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 與 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 依通道選取映像，接著用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行通道。
 
-### 可調整項目
+### 可調參數
 
-| 變數                                   | 預設值 | 用途                                                                                          |
+| 變數                                   | 預設值  | 用途                                                                                          |
 | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
-| `OPENCLAW_DOCKER_ALL_PARALLELISM`      | 10      | 一般通道的主集區 slot 數量。                                                                  |
-| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10      | 對提供者敏感的尾端集區 slot 數量。                                                            |
-| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT`       | 9       | 並行即時通道上限，避免提供者進行限流。                                                        |
-| `OPENCLAW_DOCKER_ALL_NPM_LIMIT`        | 10      | 並行 npm 安裝通道上限。                                                                       |
-| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT`    | 7       | 並行多服務通道上限。                                                                          |
-| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000    | 通道啟動之間的錯開時間，以避免 Docker daemon 建立風暴；設為 `0` 表示不錯開。                 |
-| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`  | 7200000 | 每個通道的備援逾時（120 分鐘）；選定的即時/尾端通道會使用更嚴格的上限。                      |
-| `OPENCLAW_DOCKER_ALL_DRY_RUN`          | unset   | `1` 會列印排程器計畫而不執行通道。                                                           |
-| `OPENCLAW_DOCKER_ALL_LANES`            | unset   | 以逗號分隔的精確通道清單；會略過清理煙霧測試，讓 agent 可以重現一個失敗通道。               |
+| `OPENCLAW_DOCKER_ALL_PARALLELISM`      | 10      | 一般通道的主池槽位數。                                                                        |
+| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10      | 對提供者敏感的尾池槽位數。                                                                    |
+| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT`       | 9       | 同時執行的 live 通道上限，避免提供者節流。                                                    |
+| `OPENCLAW_DOCKER_ALL_NPM_LIMIT`        | 10      | 同時執行的 npm 安裝通道上限。                                                                 |
+| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT`    | 7       | 同時執行的多服務通道上限。                                                                    |
+| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000    | 通道啟動之間的錯開時間，以避免 Docker daemon 建立風暴；設為 `0` 則不錯開。                   |
+| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`  | 7200000 | 每個通道的後備逾時（120 分鐘）；選定的 live/tail 通道使用更嚴格的上限。                      |
+| `OPENCLAW_DOCKER_ALL_DRY_RUN`          | 未設定  | `1` 會列印排程器計畫，而不執行通道。                                                         |
+| `OPENCLAW_DOCKER_ALL_LANES`            | 未設定  | 逗號分隔的精確通道清單；略過清理煙霧測試，讓 agent 能重現單一失敗通道。                      |
 
-比其有效上限更重的通道仍可從空集區啟動，然後獨自執行直到釋放容量。本機彙總會預檢 Docker、移除過期的 OpenClaw E2E 容器、輸出作用中通道狀態、保留通道計時以供最長優先排序，並預設在第一次失敗後停止排程新的集區通道。
+比有效上限更重的通道仍可從空池啟動，接著會獨自執行直到釋放容量。本機彙總會預檢 Docker、移除過期的 OpenClaw E2E 容器、輸出作用中通道狀態、保存通道計時以供最長優先排序，並預設在首次失敗後停止排程新的池化通道。
 
-### 可重用的即時/E2E 工作流程
+### 可重用的 live/E2E workflow
 
-可重用的即時/E2E 工作流程會詢問 `scripts/test-docker-all.mjs --plan-json` 需要哪些套件、映像種類、即時映像、通道和憑證涵蓋範圍。`scripts/docker-e2e.mjs` 接著會將該計畫轉換成 GitHub 輸出和摘要。它會透過 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下載目前執行的套件成品，或從 `package_artifact_run_id` 下載套件成品；驗證 tarball 清單；當計畫需要已安裝套件的通道時，透過 Blacksmith 的 Docker layer cache 建置並推送以套件摘要標記的 bare/functional GHCR Docker E2E 映像；並重用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 輸入或既有的套件摘要映像，而不是重新建置。Docker 映像拉取會以每次嘗試 180 秒的有界逾時重試，讓卡住的 registry/cache 串流能快速重試，而不是消耗 CI 關鍵路徑的大部分時間。
+可重用的 live/E2E workflow 會詢問 `scripts/test-docker-all.mjs --plan-json` 需要哪個套件、映像種類、live 映像、通道與憑證覆蓋範圍。`scripts/docker-e2e.mjs` 接著會將該計畫轉換為 GitHub 輸出與摘要。它會透過 `scripts/package-openclaw-for-docker.mjs` 封裝 OpenClaw、下載目前執行的套件成品，或從 `package_artifact_run_id` 下載套件成品；驗證 tarball 清單；在計畫需要已安裝套件的通道時，透過 Blacksmith 的 Docker layer cache 建置並推送以套件摘要標記的裸/功能 GHCR Docker E2E 映像；並重用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` 輸入或現有套件摘要映像，而不是重新建置。Docker 映像拉取會以每次嘗試 180 秒的有界逾時重試，讓卡住的 registry/cache stream 能快速重試，而不是消耗大部分 CI 關鍵路徑。
 
-### 發行路徑區塊
+### Release 路徑分塊
 
-發行 Docker 涵蓋範圍會使用較小的分塊作業搭配 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行，讓每個區塊只拉取所需的映像種類，並透過相同的加權排程器執行多個通道：
+Release Docker 覆蓋範圍會用較小的分塊作業搭配 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行，讓每個分塊只拉取所需的映像種類，並透過同一個加權排程器執行多個通道：
 
 - `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
 - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
 
-目前的發行 Docker 區塊為 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及從 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是彙總 Plugin/runtime 別名。`install-e2e` 通道別名仍是兩個提供者安裝程式通道的彙總手動重新執行別名。
+目前的 release Docker 分塊為 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及從 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 與 `plugins-integrations` 仍然是彙總 Plugin/runtime 別名。`install-e2e` 通道別名仍然是兩個提供者安裝程式通道的彙總手動重新執行別名。
 
-當完整 release-path 涵蓋範圍要求時，OpenWebUI 會併入 `plugins-runtime-services`，而只在 OpenWebUI-only 派送時保留獨立的 `openwebui` 區塊。內建通道更新通道會針對暫時性 npm 網路失敗重試一次。
+當完整 release-path 覆蓋要求 OpenWebUI 時，它會被併入 `plugins-runtime-services`，並只在僅 OpenWebUI 的派送中保留獨立的 `openwebui` 分塊。內建通道更新通道會針對暫時性 npm 網路失敗重試一次。
 
-每個區塊都會上傳 `.artifacts/docker-tests/`，其中包含通道記錄、計時、`summary.json`、`failures.json`、階段計時、排程器計畫 JSON、慢通道表格，以及每通道重新執行命令。工作流程的 `docker_lanes` 輸入會針對已準備的映像執行所選通道，而不是執行區塊作業，這會將失敗通道偵錯限制在一個目標 Docker 作業中，並為該次執行準備、下載或重用套件成品；如果所選通道是即時 Docker 通道，目標作業會在本機為該次重新執行建置 live-test 映像。產生的每通道 GitHub 重新執行命令會在這些值存在時包含 `package_artifact_run_id`、`package_artifact_name` 和已準備映像輸入，因此失敗通道可以重用失敗執行中的精確套件和映像。
+每個分塊都會上傳 `.artifacts/docker-tests/`，其中包含通道日誌、計時、`summary.json`、`failures.json`、階段計時、排程器計畫 JSON、慢通道表，以及每個通道的重新執行命令。workflow 的 `docker_lanes` 輸入會針對已準備的映像執行選取的通道，而不是執行分塊作業，讓失敗通道偵錯限制在一個有針對性的 Docker 作業中，並為該執行準備、下載或重用套件成品；如果選取的通道是 live Docker 通道，目標作業會在本機建置 live-test 映像以供該次重新執行。產生的每通道 GitHub 重新執行命令會在這些值存在時包含 `package_artifact_run_id`、`package_artifact_name` 與已準備的映像輸入，讓失敗通道能重用失敗執行中的精確套件與映像。
 
 ```bash
 pnpm test:docker:rerun <run-id>      # download Docker artifacts and print combined/per-lane targeted rerun commands
 pnpm test:docker:timings <summary>   # slow-lane and phase critical-path summaries
 ```
 
-排程的即時/E2E 工作流程會每日執行完整 release-path Docker 套件。
+排程的 live/E2E workflow 每天會執行完整 release-path Docker 套件。
 
 ## Plugin 預先發行
 
-`Plugin Prerelease` 是成本較高的產品/套件涵蓋範圍，因此它是由 `Full Release Validation` 或明確操作者派送的獨立工作流程。一般 pull request、`main` 推送，以及獨立的手動 CI 派送會停用該套件。它會在八個擴充功能 worker 之間平衡內建 Plugin 測試；這些擴充功能分片作業會一次最多執行兩個 Plugin 設定群組，每組使用一個 Vitest worker 和更大的 Node heap，讓匯入繁重的 Plugin 批次不會建立額外的 CI 作業。僅限發行的 Docker 預先發行路徑會以小群組批次執行目標 Docker 通道，避免為一到三分鐘的作業保留數十個 runner。
+`Plugin Prerelease` 是成本更高的產品/套件覆蓋範圍，因此它是由 `Full Release Validation` 或明確操作員派送的獨立 workflow。一般 pull request、`main` 推送與獨立手動 CI 派送都會關閉該套件。它會在八個擴充功能 worker 之間平衡內建 Plugin 測試；這些擴充功能分片作業一次最多執行兩個 Plugin 設定群組，每個群組使用一個 Vitest worker 與較大的 Node heap，讓大量匯入的 Plugin 批次不會建立額外 CI 作業。僅 release 的 Docker 預先發行路徑會將目標 Docker 通道分成小群組批次執行，避免為一到三分鐘的作業保留數十個 runner。
 
 ## QA Lab
 
-QA Lab 在主要智慧範圍工作流程之外有專用 CI 通道。Agentic parity 巢狀於廣泛的 QA 和發行測試框架之下，不是獨立的 PR 工作流程。當 parity 應該隨廣泛驗證執行一起跑時，請使用 `Full Release Validation` 搭配 `rerun_group=qa-parity`。
+QA Lab 在主要智慧範圍 workflow 之外有專用 CI 通道。Agentic parity 巢狀位於廣泛 QA 與 release harness 之下，不是獨立的 PR workflow。當 parity 應該搭配廣泛驗證執行時，請使用 `Full Release Validation` 並設定 `rerun_group=qa-parity`。
 
-- `QA-Lab - All Lanes` 工作流程會每晚在 `main` 上執行，也會在手動派送時執行；它會將 mock parity 通道、即時 Matrix 通道，以及即時 Telegram 和 Discord 通道展開為平行作業。即時作業使用 `qa-live-shared` 環境，而 Telegram/Discord 使用 Convex lease。
+- `QA-Lab - All Lanes` workflow 會在 `main` 上每晚執行，也可手動派送；它會將 mock parity 通道、live Matrix 通道，以及 live Telegram 與 Discord 通道展開為平行作業。Live 作業使用 `qa-live-shared` 環境，而 Telegram/Discord 使用 Convex lease。
 
-發行檢查會使用決定性的 mock provider 和 mock-qualified 模型（`mock-openai/gpt-5.5` 和 `mock-openai/gpt-5.5-alt`）執行 Matrix 與 Telegram 即時傳輸通道，讓通道合約與即時模型延遲和一般 provider-plugin 啟動隔離。即時傳輸 Gateway 會停用記憶體搜尋，因為 QA parity 會另外涵蓋記憶體行為；提供者連線能力則由獨立的即時模型、原生提供者，以及 Docker 提供者套件涵蓋。
+Release 檢查會使用決定性的 mock 提供者與 mock 限定模型（`mock-openai/gpt-5.5` 與 `mock-openai/gpt-5.5-alt`）執行 Matrix 與 Telegram live transport 通道，讓通道合約與 live 模型延遲及一般提供者 Plugin 啟動隔離。live transport Gateway 會停用記憶體搜尋，因為 QA parity 會另外涵蓋記憶體行為；提供者連線能力則由獨立的 live 模型、原生提供者與 Docker 提供者套件涵蓋。
 
-Matrix 會在排程和發行 gate 中使用 `--profile fast`，且只在已 checkout 的 CLI 支援時加入 `--fail-fast`。CLI 預設值和手動工作流程輸入仍為 `all`；手動 `matrix_profile=all` 派送一律會將完整 Matrix 涵蓋範圍分片為 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作業。
+Matrix 會在排程與 release gate 中使用 `--profile fast`，且只在簽出的 CLI 支援時加上 `--fail-fast`。CLI 預設值與手動 workflow 輸入仍為 `all`；手動 `matrix_profile=all` 派送一律會將完整 Matrix 覆蓋範圍分片為 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 與 `e2ee-cli` 作業。
 
-`OpenClaw Release Checks` 也會在發行核准前執行發行關鍵的 QA Lab 通道；其 QA parity gate 會將候選與基準套件作為平行通道作業執行，然後將兩者的成品下載到一個小型報告作業中，供最終 parity 比較使用。
+`OpenClaw Release Checks` 也會在 release 核准前執行 release 關鍵的 QA Lab 通道；其 QA parity gate 會將候選與基準套件作為平行通道作業執行，接著將兩者成品下載到小型報告作業中，進行最終 parity 比較。
 
-對於一般 PR，請依循有範圍的 CI/檢查證據，而不是將 parity 視為必要狀態。
+對一般 PR，請遵循範圍化 CI/檢查證據，而不是將 parity 視為必要狀態。
 
 ## CodeQL
 
-`CodeQL` 工作流程刻意設計為範圍狹窄的第一輪安全掃描器，而不是完整的儲存庫掃描。每日、手動與非草稿 pull request 防護執行會掃描 Actions 工作流程程式碼，以及風險最高的 JavaScript/TypeScript 表面，並使用高信心度的安全查詢，篩選為高/嚴重 `security-severity`。
+`CodeQL` 工作流程刻意是範圍狹窄的第一輪安全掃描器，而不是完整的儲存庫掃描。每日、手動，以及非草稿 pull request 的防護執行，會掃描 Actions 工作流程程式碼，加上最高風險的 JavaScript/TypeScript 表面，並使用高信心度的安全查詢，篩選至高/嚴重 `security-severity`。
 
-pull request 防護維持輕量：它只會在 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 底下有變更時啟動，並執行與排程工作流程相同的高信心度安全矩陣。Android 和 macOS CodeQL 不納入 PR 預設值。
+pull request 防護保持輕量：它只會在 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 底下有變更時啟動，並執行與排程工作流程相同的高信心度安全矩陣。Android 和 macOS CodeQL 不包含在 PR 預設值中。
 
 ### 安全類別
 
-| 類別                                              | 表面                                                                                                                                |
+| 類別                                          | 表面                                                                                                                             |
 | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `/codeql-security-high/core-auth-secrets`         | 驗證、祕密、沙箱、Cron 與 Gateway 基準                                                                                              |
-| `/codeql-security-high/channel-runtime-boundary`  | 核心頻道實作合約，加上頻道 Plugin 執行階段、Gateway、Plugin SDK、祕密與稽核接觸點                                                   |
-| `/codeql-security-high/network-ssrf-boundary`     | 核心 SSRF、IP 剖析、網路防護、網頁擷取與 Plugin SDK SSRF 政策表面                                                                    |
-| `/codeql-security-high/mcp-process-tool-boundary` | MCP 伺服器、程序執行輔助工具、對外傳遞，以及代理工具執行閘門                                                                         |
-| `/codeql-security-high/plugin-trust-boundary`     | Plugin 安裝、載入器、manifest、registry、套件管理器安裝、來源載入，以及 Plugin SDK 套件合約信任表面                                  |
+| `/codeql-security-high/core-auth-secrets`         | Auth、祕密、沙箱、Cron 和 Gateway 基準                                                                                  |
+| `/codeql-security-high/channel-runtime-boundary`  | 核心頻道實作合約，加上頻道 Plugin runtime、Gateway、Plugin SDK、祕密、稽核接觸點              |
+| `/codeql-security-high/network-ssrf-boundary`     | 核心 SSRF、IP 解析、網路防護、web-fetch 和 Plugin SDK SSRF 政策表面                                                |
+| `/codeql-security-high/mcp-process-tool-boundary` | MCP 伺服器、程序執行輔助工具、外送交付，以及代理工具執行閘門                                           |
+| `/codeql-security-high/plugin-trust-boundary`     | Plugin 安裝、載入器、manifest、registry、套件管理器安裝、來源載入，以及 Plugin SDK 套件合約信任表面 |
 
 ### 平台特定安全分片
 
-- `CodeQL Android Critical Security` — 排程的 Android 安全分片。為 CodeQL 在工作流程健全性接受的最小 Blacksmith Linux runner 上手動建置 Android app。上傳至 `/codeql-critical-security/android` 底下。
-- `CodeQL macOS Critical Security` — 每週/手動 macOS 安全分片。在 Blacksmith macOS 上為 CodeQL 手動建置 macOS app，從上傳的 SARIF 中篩除相依性建置結果，並上傳至 `/codeql-critical-security/macos` 底下。由於 macOS 建置即使乾淨也會主導執行時間，因此保留在每日預設值之外。
+- `CodeQL Android Critical Security` — 排程的 Android 安全分片。在工作流程健全性接受的最小 Blacksmith Linux runner 上，為 CodeQL 手動建置 Android 應用程式。上傳到 `/codeql-critical-security/android` 底下。
+- `CodeQL macOS Critical Security` — 每週/手動的 macOS 安全分片。在 Blacksmith macOS 上為 CodeQL 手動建置 macOS 應用程式，從上傳的 SARIF 中篩除相依項建置結果，並上傳到 `/codeql-critical-security/macos` 底下。因為即使乾淨時 macOS 建置也主導 runtime，所以保持在每日預設值之外。
 
 ### 關鍵品質類別
 
-`CodeQL Critical Quality` 是對應的非安全分片。它只在較小的 Blacksmith Linux runner 上，針對範圍狹窄但高價值的表面執行錯誤嚴重性、非安全的 JavaScript/TypeScript 品質查詢。它的 pull request 防護刻意比排程設定檔更小：非草稿 PR 只會針對代理命令/模型/工具執行與回覆分派程式碼、設定 schema/遷移/IO 程式碼、驗證/祕密/沙箱/安全程式碼、核心頻道與 bundled 頻道 Plugin 執行階段、Gateway protocol/server-method、記憶體執行階段/SDK 黏合、MCP/程序/對外傳遞、提供者執行階段/模型 catalog、工作階段診斷/傳遞佇列、Plugin 載入器、Plugin SDK/套件合約，或 Plugin SDK 回覆執行階段變更，執行相符的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 與 `plugin-sdk-reply-runtime` 分片。CodeQL 設定與品質工作流程變更會執行全部十二個 PR 品質分片。
+`CodeQL Critical Quality` 是對應的非安全分片。它只在較小的 Blacksmith Linux runner 上，對範圍狹窄且高價值的表面執行錯誤嚴重度、非安全性的 JavaScript/TypeScript 品質查詢。它的 pull request 防護刻意比排程設定檔更小：非草稿 PR 只會在代理命令/模型/工具執行與回覆派送程式碼、config schema/migration/IO 程式碼、auth/祕密/沙箱/安全程式碼、核心頻道與隨附頻道 Plugin runtime、Gateway protocol/server-method、記憶體 runtime/SDK 銜接、MCP/程序/外送交付、provider runtime/模型目錄、session diagnostics/交付佇列、Plugin loader、Plugin SDK/套件合約，或 Plugin SDK 回覆 runtime 有變更時，執行對應的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 和 `plugin-sdk-reply-runtime` 分片。CodeQL config 與品質工作流程變更會執行全部十二個 PR 品質分片。
 
-手動 dispatch 接受：
+手動派送接受：
 
 ```
 profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
@@ -424,38 +417,38 @@ profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-run
 
 狹窄設定檔是用於單獨執行一個品質分片的教學/迭代掛鉤。
 
-| 類別                                                    | 表面                                                                                                                                                              |
+| 類別                                                | 表面                                                                                                                                                           |
 | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/codeql-critical-quality/core-auth-secrets`            | 驗證、祕密、沙箱、Cron 與 Gateway 安全邊界程式碼                                                                                                                  |
-| `/codeql-critical-quality/config-boundary`              | 設定 schema、遷移、正規化與 IO 合約                                                                                                                               |
-| `/codeql-critical-quality/gateway-runtime-boundary`     | Gateway 協定 schema 與伺服器方法合約                                                                                                                             |
-| `/codeql-critical-quality/channel-runtime-boundary`     | 核心頻道與 bundled 頻道 Plugin 實作合約                                                                                                                          |
-| `/codeql-critical-quality/agent-runtime-boundary`       | 命令執行、模型/提供者分派、自動回覆分派與佇列，以及 ACP 控制平面執行階段合約                                                                                      |
-| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 伺服器與工具橋接、程序監督輔助工具，以及對外傳遞合約                                                                                                          |
-| `/codeql-critical-quality/memory-runtime-boundary`      | 記憶體主機 SDK、記憶體執行階段 facade、記憶體 Plugin SDK 別名、記憶體執行階段啟用黏合，以及記憶體 doctor 命令                                                     |
-| `/codeql-critical-quality/session-diagnostics-boundary` | 回覆佇列內部、工作階段傳遞佇列、對外工作階段繫結/傳遞輔助工具、診斷事件/記錄 bundle 表面，以及工作階段 doctor CLI 合約                                           |
-| `/codeql-critical-quality/plugin-sdk-reply-runtime`     | Plugin SDK 傳入回覆分派、回覆 payload/分塊/執行階段輔助工具、頻道回覆選項、傳遞佇列，以及工作階段/thread 繫結輔助工具                                           |
-| `/codeql-critical-quality/provider-runtime-boundary`    | 模型 catalog 正規化、提供者驗證與探索、提供者執行階段註冊、提供者預設值/catalog，以及 web/search/fetch/embedding registry                                        |
-| `/codeql-critical-quality/ui-control-plane`             | 控制 UI bootstrap、本機持久化、Gateway 控制流程，以及任務控制平面執行階段合約                                                                                    |
-| `/codeql-critical-quality/web-media-runtime-boundary`   | 核心網頁擷取/搜尋、媒體 IO、媒體理解、影像生成，以及媒體生成執行階段合約                                                                                          |
-| `/codeql-critical-quality/plugin-boundary`              | 載入器、registry、公用表面，以及 Plugin SDK 進入點合約                                                                                                            |
-| `/codeql-critical-quality/plugin-sdk-package-contract`  | 已發布套件端 Plugin SDK 來源與 Plugin 套件合約輔助工具                                                                                                           |
+| `/codeql-critical-quality/core-auth-secrets`            | Auth、祕密、沙箱、Cron 和 Gateway 安全邊界程式碼                                                                                                  |
+| `/codeql-critical-quality/config-boundary`              | Config schema、migration、normalization 和 IO 合約                                                                                                         |
+| `/codeql-critical-quality/gateway-runtime-boundary`     | Gateway protocol schema 和伺服器方法合約                                                                                                              |
+| `/codeql-critical-quality/channel-runtime-boundary`     | 核心頻道與隨附頻道 Plugin 實作合約                                                                                                  |
+| `/codeql-critical-quality/agent-runtime-boundary`       | 命令執行、模型/provider 派送、自動回覆派送與佇列，以及 ACP 控制平面 runtime 合約                                               |
+| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 伺服器與工具橋接、程序監督輔助工具，以及外送交付合約                                                                        |
+| `/codeql-critical-quality/memory-runtime-boundary`      | 記憶體主機 SDK、記憶體 runtime facade、記憶體 Plugin SDK alias、記憶體 runtime 啟用銜接，以及記憶體 doctor 命令                                    |
+| `/codeql-critical-quality/session-diagnostics-boundary` | 回覆佇列內部、session 交付佇列、外送 session 綁定/交付輔助工具、診斷事件/記錄 bundle 表面，以及 session doctor CLI 合約 |
+| `/codeql-critical-quality/plugin-sdk-reply-runtime`     | Plugin SDK 入站回覆派送、回覆 payload/chunking/runtime 輔助工具、頻道回覆選項、交付佇列，以及 session/thread 綁定輔助工具             |
+| `/codeql-critical-quality/provider-runtime-boundary`    | 模型目錄標準化、provider auth 與 discovery、provider runtime 註冊、provider defaults/catalogs，以及 web/search/fetch/embedding registry    |
+| `/codeql-critical-quality/ui-control-plane`             | 控制 UI 啟動、local persistence、Gateway 控制流程，以及任務控制平面 runtime 合約                                                          |
+| `/codeql-critical-quality/web-media-runtime-boundary`   | 核心 web fetch/search、media IO、media understanding、image-generation，以及 media-generation runtime 合約                                                    |
+| `/codeql-critical-quality/plugin-boundary`              | Loader、registry、public-surface，以及 Plugin SDK entrypoint 合約                                                                                             |
+| `/codeql-critical-quality/plugin-sdk-package-contract`  | 已發布套件端 Plugin SDK 來源與 Plugin 套件合約輔助工具                                                                                      |
 
-品質與安全分開，以便品質發現可以被排程、衡量、停用或擴充，而不會遮蔽安全訊號。Swift、Python 與 bundled-Plugin CodeQL 擴充應只在狹窄設定檔具備穩定執行時間與訊號後，作為範圍化或分片化的後續工作加回來。
+品質與安全保持分離，讓品質發現可以排程、量測、停用或擴展，而不會遮蔽安全訊號。Swift、Python 和隨附 Plugin 的 CodeQL 擴展，應該只在狹窄設定檔已有穩定 runtime 和訊號之後，再以有範圍或分片的後續工作加回來。
 
 ## 維護工作流程
 
-### Docs Agent
+### 文件代理
 
-`Docs Agent` 工作流程是一條事件驅動的 Codex 維護路徑，用於讓現有文件與最近 landed 的變更保持一致。它沒有純排程：`main` 上成功的非 bot push CI 執行可以觸發它，手動 dispatch 也可以直接執行它。當 `main` 已經往前移動，或上一小時內已建立另一個未略過的 Docs Agent 執行時，workflow-run 叫用會略過。執行時，它會檢閱從前一個未略過的 Docs Agent 來源 SHA 到目前 `main` 的 commit 範圍，因此每小時一次的執行可以涵蓋自上次文件通過後累積的所有 main 變更。
+`Docs Agent` 工作流程是事件驅動的 Codex 維護通道，用於讓現有文件與近期落地的變更保持一致。它沒有純排程：`main` 上成功的非 bot push CI 執行可以觸發它，手動派送也可以直接執行它。當 `main` 已經前進，或最近一小時內已建立另一個非跳過的 Docs Agent 執行時，workflow-run 叫用會跳過。當它執行時，會檢閱從前一次非跳過的 Docs Agent 來源 SHA 到目前 `main` 的提交範圍，因此每小時一次的執行可以涵蓋上次文件檢查後累積的所有 main 變更。
 
-### Test Performance Agent
+### 測試效能代理
 
-`Test Performance Agent` 工作流程是一條事件驅動的 Codex 維護路徑，用於處理緩慢測試。它沒有純排程：`main` 上成功的非 bot push CI 執行可以觸發它，但如果另一個 workflow-run 叫用已在該 UTC 日執行或正在執行，它會略過。手動 dispatch 會繞過該每日活動閘門。這條路徑會建置完整套件分組 Vitest 效能報告，讓 Codex 只進行小型且保留覆蓋率的測試效能修正，而不是大範圍重構，接著重新執行完整套件報告，並拒絕會降低通過基準測試數量的變更。如果基準有失敗測試，Codex 只能修正明顯失敗，且代理後的完整套件報告必須通過，才會提交任何內容。當 `main` 在 bot push landed 前前進時，這條路徑會 rebase 已驗證的 patch，重新執行 `pnpm check:changed`，並重試 push；有衝突的過期 patch 會被略過。它使用 GitHub-hosted Ubuntu，讓 Codex action 可以維持與 docs agent 相同的 drop-sudo 安全姿態。
+`Test Performance Agent` 工作流程是事件驅動的 Codex 維護通道，用於慢速測試。它沒有純排程：`main` 上成功的非 bot push CI 執行可以觸發它，但如果另一個 workflow-run 叫用在該 UTC 日已經執行過或正在執行，則會跳過。手動派送會略過該每日活動閘門。此通道會建置完整套件分組的 Vitest 效能報告，讓 Codex 只進行小型、保留覆蓋率的測試效能修正，而不是大範圍重構，然後重新執行完整套件報告，並拒絕會降低通過基準測試數量的變更。如果基準有失敗測試，Codex 只能修正明顯失敗，而且代理後的完整套件報告必須通過，才會提交任何內容。當 `main` 在 bot push 落地前前進時，此通道會 rebase 已驗證的 patch、重新執行 `pnpm check:changed`，並重試 push；有衝突的過期 patch 會被跳過。它使用 GitHub-hosted Ubuntu，因此 Codex action 可以保持與 docs agent 相同的 drop-sudo 安全姿態。
 
 ### 合併後的重複 PR
 
-`Duplicate PRs After Merge` 工作流程是手動 maintainer 工作流程，用於 landed 後的重複項清理。它預設為 dry-run，且只有在 `apply=true` 時才會關閉明確列出的 PR。在變更 GitHub 之前，它會確認 landed PR 已合併，並確認每個重複項都有共用的 referenced issue 或重疊的 changed hunks。
+`Duplicate PRs After Merge` 工作流程是供維護者使用的手動工作流程，用於落地後的重複項清理。它預設為 dry-run，且只會在 `apply=true` 時關閉明確列出的 PR。在修改 GitHub 之前，它會驗證已落地 PR 已合併，且每個重複項都有共同參照的 issue 或重疊的變更 hunk。
 
 ```bash
 gh workflow run duplicate-after-merge.yml \
@@ -466,37 +459,37 @@ gh workflow run duplicate-after-merge.yml \
 
 ## 本機檢查閘門與變更路由
 
-本機 changed-lane 邏輯位於 `scripts/changed-lanes.mjs`，並由 `scripts/check-changed.mjs` 執行。該本機檢查閘門在架構邊界上比廣泛的 CI 平台範圍更嚴格：
+本機 changed-lane 邏輯位於 `scripts/changed-lanes.mjs`，並由 `scripts/check-changed.mjs` 執行。該本機檢查閘門對架構邊界的要求，比廣泛的 CI 平台範圍更嚴格：
 
-- 核心生產變更會執行核心 prod 與核心 test 型別檢查，加上核心 lint/防護；
-- 僅核心測試變更只會執行核心 test 型別檢查，加上核心 lint；
-- extension 生產變更會執行 extension prod 與 extension test 型別檢查，加上 extension lint；
-- 僅 extension 測試變更會執行 extension test 型別檢查，加上 extension lint；
-- 公用 Plugin SDK 或 Plugin 合約變更會擴展到 extension 型別檢查，因為 extension 依賴那些核心合約（Vitest extension 掃描仍是明確的測試工作）；
-- 僅 release metadata 的版本 bump 會執行目標式版本/設定/root-dependency 檢查；
-- 未知 root/設定變更會 fail safe 到所有檢查路徑。
+- 核心 production 變更會執行核心 prod 與核心 test typecheck，加上核心 lint/guard；
+- 僅核心測試變更只會執行核心 test typecheck，加上核心 lint；
+- extension production 變更會執行 extension prod 與 extension test typecheck，加上 extension lint；
+- 僅 extension 測試變更會執行 extension test typecheck，加上 extension lint；
+- 公開 Plugin SDK 或 Plugin 合約變更會擴展到 extension typecheck，因為 extension 依賴那些核心合約（Vitest extension sweep 保持為明確的測試工作）；
+- 僅 release metadata 的版本升級會執行目標版本/config/root-dependency 檢查；
+- 未知的 root/config 變更會 fail safe 到所有檢查通道。
 
-本機 changed-test 路由位於 `scripts/test-projects.test-support.mjs`，且刻意比 `check:changed` 便宜：直接測試編輯會執行自身，來源編輯優先使用明確映射，接著是 sibling tests 與 import-graph dependents。共用群組聊天室傳遞設定是明確映射之一：對群組可見回覆設定、來源回覆傳遞模式或 message-tool 系統提示的變更，會路由到核心回覆測試，加上 Discord 與 Slack 傳遞迴歸，讓共用預設值變更在第一個 PR push 前失敗。只有當變更廣泛到測試框架層級，以至於便宜的映射集合不是可信 proxy 時，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
+本機 changed-test 路由位於 `scripts/test-projects.test-support.mjs`，並且刻意比 `check:changed` 更便宜：直接測試編輯會執行自身，來源編輯優先使用明確對應，接著是同層測試與 import-graph 依賴項。共享群組房間交付 config 是其中一個明確對應：對群組可見回覆 config、來源回覆交付模式，或 message-tool system prompt 的變更，會透過核心回覆測試加上 Discord 和 Slack 交付回歸，因此共享預設值變更會在第一次 PR push 前失敗。只有當變更廣泛影響測試框架，使便宜的對應集合不足以作為可信代理時，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
 
 ## Testbox 驗證
 
-從 repo 根目錄執行 Testbox，並且在需要廣泛驗證證據時，優先使用全新預熱的 box。在將緩慢的 gate 花在重複使用、已過期，或剛回報異常大量同步的 box 之前，先在該 box 內執行 `pnpm testbox:sanity`。
+在儲存庫根目錄執行 Testbox，且對於大範圍驗證，偏好使用新的已預熱 box。若要在曾重複使用、已過期，或剛回報非預期大量同步的 box 上執行耗時檢查閘，請先在該 box 內執行 `pnpm testbox:sanity`。
 
-當必要的根目錄檔案（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 顯示至少 200 個已追蹤檔案遭刪除時，健全性檢查會快速失敗。這通常表示遠端同步狀態不是該 PR 的可信副本；請停止該 box 並改為預熱新的 box，而不是除錯產品測試失敗。對於有意的大量刪除 PR，請在該次健全性執行中設定 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
+當必要的根目錄檔案（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 顯示至少 200 個已追蹤檔案遭刪除時，健全性檢查會快速失敗。這通常表示遠端同步狀態不是提取請求的可信副本；請停止該 box 並改為預熱新的 box，而不是偵錯產品測試失敗。對於刻意大量刪除的提取請求，請在該次健全性檢查設定 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
 
-`pnpm testbox:run` 也會終止停留在同步階段超過五分鐘且沒有同步後輸出的本機 Blacksmith CLI 呼叫。設定 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可停用該保護，或針對異常龐大的本機 diff 使用更大的毫秒值。
+`pnpm testbox:run` 也會終止停留在同步階段超過五分鐘且沒有同步後輸出的本機 Blacksmith CLI 呼叫。設定 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可停用該防護；若本機差異異常龐大，則可使用較大的毫秒值。
 
-Crabbox 是 repo 擁有的遠端 box 包裝器，用於維護者 Linux 驗證。當檢查對本機編輯迴圈而言過於廣泛、CI parity 很重要，或驗證需要 secrets、Docker、package lanes、可重用 box 或遠端日誌時使用它。一般 OpenClaw 後端是 `blacksmith-testbox`；自有 AWS/Hetzner 容量是 Blacksmith 中斷、配額問題，或明確要測試自有容量時的備援。
+Crabbox 是儲存庫擁有的遠端 box 包裝器，用於維護者的 Linux 驗證。當檢查對本機編輯迴圈而言過於廣泛、CI 等價性很重要，或驗證需要密鑰、Docker、套件檢查線、可重複使用的 box 或遠端日誌時，請使用它。一般的 OpenClaw 後端是 `blacksmith-testbox`；擁有的 AWS/Hetzner 容量則是在 Blacksmith 中斷、配額問題，或明確測試自有容量時的備援。
 
-第一次執行前，請從 repo 根目錄檢查包裝器：
+第一次執行前，請從儲存庫根目錄檢查包裝器：
 
 ```bash
 pnpm crabbox:run -- --help | sed -n '1,120p'
 ```
 
-如果 Crabbox binary 過舊且未宣告 `blacksmith-testbox`，repo 包裝器會拒絕它。即使 `.crabbox.yaml` 具有自有雲端預設值，也請明確傳入 provider。
+若 Crabbox 二進位檔過舊且未宣告 `blacksmith-testbox`，儲存庫包裝器會拒絕使用。即使 `.crabbox.yaml` 有自有雲端預設值，也請明確傳入提供者。
 
-變更 gate：
+變更檢查閘：
 
 ```bash
 pnpm crabbox:run -- --provider blacksmith-testbox \
@@ -511,7 +504,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
   "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
 ```
 
-聚焦測試重新執行：
+聚焦測試重跑：
 
 ```bash
 pnpm crabbox:run -- --provider blacksmith-testbox \
@@ -541,21 +534,21 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
   "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
 ```
 
-閱讀最終 JSON 摘要。有用欄位是 `provider`、`leaseId`、`syncDelegated`、`exitCode`、`commandMs` 和 `totalMs`。一次性的 Blacksmith 後端 Crabbox 執行應該會自動停止 Testbox；如果執行被中斷或清理狀態不明，請檢查即時 box，並只停止你建立的 box：
+閱讀最終的 JSON 摘要。有用的欄位是 `provider`、`leaseId`、`syncDelegated`、`exitCode`、`commandMs` 和 `totalMs`。由 Blacksmith 支援的一次性 Crabbox 執行應會自動停止 Testbox；若執行被中斷或清理狀態不明，請檢查仍在執行的 box，並只停止你建立的 box：
 
 ```bash
 blacksmith testbox list
 blacksmith testbox stop --id <tbx_id>
 ```
 
-只有在你有意需要在同一個已 hydrate 的 box 上執行多個命令時，才使用重用：
+只有在你刻意需要於同一個已水合 box 上執行多個命令時，才使用重複使用：
 
 ```bash
 pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
 pnpm crabbox:stop -- <tbx_id>
 ```
 
-如果 Crabbox 是損壞的層，但 Blacksmith 本身可運作，請使用直接 Blacksmith 作為狹窄備援：
+若損壞的層是 Crabbox，但 Blacksmith 本身可用，請使用直接 Blacksmith 作為狹窄備援：
 
 ```bash
 blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
@@ -563,7 +556,7 @@ blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
 blacksmith testbox stop --id <tbx_id>
 ```
 
-只有在 Blacksmith 停機、受配額限制、缺少所需環境，或自有容量明確是目標時，才升級到自有 Crabbox 容量：
+只有在 Blacksmith 中斷、受配額限制、缺少所需環境，或自有容量明確是目標時，才升級到自有 Crabbox 容量：
 
 ```bash
 pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
@@ -572,7 +565,7 @@ pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
 pnpm crabbox:stop -- <cbx_id-or-slug>
 ```
 
-`.crabbox.yaml` 擁有自有雲端 lanes 的 provider、sync 和 GitHub Actions hydration 預設值。它會排除本機 `.git`，讓已 hydrate 的 Actions checkout 保留自己的遠端 Git metadata，而不是同步維護者本機的 remotes 與 object stores；它也會排除不應傳輸的本機 runtime/build artifacts。`.github/workflows/crabbox-hydrate.yml` 擁有 checkout、Node/pnpm 設定、`origin/main` fetch，以及自有雲端 `crabbox run --id <cbx_id>` 命令的非 secret 環境交接。
+`.crabbox.yaml` 負責自有雲端檢查線的提供者、同步與 GitHub Actions 水合預設值。它會排除本機 `.git`，讓已水合的 Actions checkout 保留自己的遠端 Git 中繼資料，而不是同步維護者本機的遠端與物件儲存，並且會排除不應傳輸的本機執行期/建置成品。`.github/workflows/crabbox-hydrate.yml` 負責 checkout、Node/pnpm 設定、`origin/main` 擷取，以及自有雲端 `crabbox run --id <cbx_id>` 命令的非密鑰環境交接。
 
 ## 相關
 

docs/zh-TW/cli/dashboard.md

@@ -1,21 +1,21 @@
 ---
 read_when:
-    - 你想使用目前的 token 開啟 Control UI
-    - 您想要在不啟動瀏覽器的情況下印出 URL
-summary: '`openclaw dashboard` 的 CLI 參考（開啟控制 UI）'
+    - 您想使用目前的權杖開啟控制 UI
+    - 你想要印出 URL，而不啟動瀏覽器
+summary: '`openclaw dashboard` 的 CLI 參考（開啟控制介面）'
 title: 儀表板
 x-i18n:
-    generated_at: "2026-04-30T02:52:59Z"
+    generated_at: "2026-05-05T01:44:17Z"
     model: gpt-5.5
     provider: openai
-    source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c
+    source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f
     source_path: cli/dashboard.md
     workflow: 16
 ---
 
 # `openclaw dashboard`
 
-使用你目前的身分驗證開啟控制 UI。
+使用目前的驗證資訊開啟控制 UI。
 
 ```bash
 openclaw dashboard
@@ -24,13 +24,17 @@ openclaw dashboard --no-open
 
 注意事項：
 
-- `dashboard` 會在可行時解析已設定的 `gateway.auth.token` SecretRefs。
-- `dashboard` 會遵循 `gateway.tls.enabled`：已啟用 TLS 的 Gateway 會列印/開啟
+- `dashboard` 會在可行時解析已設定的 `gateway.auth.token` SecretRef。
+- `dashboard` 會遵循 `gateway.tls.enabled`：啟用 TLS 的 Gateway 會列印/開啟
   `https://` 控制 UI URL，並透過 `wss://` 連線。
-- 對於由 SecretRef 管理的權杖（已解析或未解析），`dashboard` 會列印/複製/開啟不含權杖的 URL，以避免在終端機輸出、剪貼簿歷史記錄或瀏覽器啟動引數中暴露外部祕密。
-- 如果 `gateway.auth.token` 由 SecretRef 管理，但在此命令路徑中未解析，命令會列印不含權杖的 URL，並提供明確的修復指引，而不是嵌入無效的權杖預留位置。
+- 如果已透過 token 驗證的 dashboard URL 無法傳送到剪貼簿/瀏覽器，
+  `dashboard` 會記錄一則安全的手動驗證提示，指出 `OPENCLAW_GATEWAY_TOKEN`、
+  `gateway.auth.token` 和片段鍵 `token`，但不會列印 token
+  值。
+- 對於由 SecretRef 管理的 token（無論已解析或未解析），`dashboard` 會列印/複製/開啟不含 token 的 URL，以避免在終端機輸出、剪貼簿歷史記錄或瀏覽器啟動引數中暴露外部密鑰。
+- 如果 `gateway.auth.token` 是由 SecretRef 管理，但在此命令路徑中尚未解析，該命令會列印不含 token 的 URL 和明確的修復指引，而不是嵌入無效的 token 預留位置。
 
 ## 相關
 
 - [CLI 參考](/zh-TW/cli)
-- [儀表板](/zh-TW/web/dashboard)
+- [Dashboard](/zh-TW/web/dashboard)

docs/zh-TW/cli/doctor.md

@@ -1,21 +1,21 @@
 ---
 read_when:
-    - 你遇到連線/驗證問題，並想要引導式修復
+    - 您遇到連線/身分驗證問題，並想要引導式修正
     - 你已更新並想要進行合理性檢查
-summary: '`openclaw doctor` 的 CLI 參考（健康檢查 + 引導式修復）'
+summary: CLI 參考文件：`openclaw doctor`（健康檢查 + 引導式修復）
 title: 診斷
 x-i18n:
-    generated_at: "2026-05-04T02:22:33Z"
+    generated_at: "2026-05-05T01:44:19Z"
     model: gpt-5.5
     provider: openai
-    source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
+    source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5
     source_path: cli/doctor.md
     workflow: 16
 ---
 
 # `openclaw doctor`
 
-Gateway 與通道的健康檢查與快速修復。
+Gateway 和通道的健康檢查 + 快速修復。
 
 相關：
 
@@ -36,43 +36,43 @@ openclaw doctor --generate-gateway-token
 
 - `--no-workspace-suggestions`：停用工作區記憶體/搜尋建議
 - `--yes`：不提示並接受預設值
-- `--repair`：不提示並套用建議的非服務修復；Gateway 服務安裝與重寫仍需要互動式確認或明確的 Gateway 指令
+- `--repair`：不提示並套用建議的非服務修復；Gateway 服務安裝和重寫仍需要互動式確認或明確的 Gateway 命令
 - `--fix`：`--repair` 的別名
 - `--force`：套用積極修復，包括在需要時覆寫自訂服務設定
-- `--non-interactive`：不顯示提示執行；僅進行安全遷移與非服務修復
-- `--generate-gateway-token`：產生並設定 Gateway token
+- `--non-interactive`：不顯示提示執行；僅執行安全遷移和非服務修復
+- `--generate-gateway-token`：產生並設定 Gateway 權杖
 - `--deep`：掃描系統服務以尋找額外的 Gateway 安裝
 
-注意事項：
+備註：
 
-- 互動式提示（例如 keychain/OAuth 修復）只會在 stdin 是 TTY 且**未**設定 `--non-interactive` 時執行。無頭執行（cron、Telegram、沒有終端機）會略過提示。
-- 效能：非互動式 `doctor` 執行會略過急切 Plugin 載入，讓無頭健康檢查保持快速。互動式工作階段在檢查需要 Plugin 貢獻時仍會完整載入 Plugin。
-- `--fix`（`--repair` 的別名）會將備份寫入 `~/.openclaw/openclaw.json.bak`，並移除未知設定鍵，列出每個移除項目。
-- `doctor --fix --non-interactive` 會回報遺失或過期的 Gateway 服務定義，但不會在更新修復模式之外安裝或重寫它們。服務遺失時請執行 `openclaw gateway install`，或在你刻意要取代啟動器時執行 `openclaw gateway install --force`。
-- 狀態完整性檢查現在會偵測 sessions 目錄中的孤立 transcript 檔案。將它們封存為 `.deleted.<timestamp>` 需要互動式確認；`--fix`、`--yes` 和無頭執行會讓它們留在原位。
-- Doctor 也會掃描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的舊版 Cron job 形狀，並可在排程器於執行階段自動正規化它們之前就地重寫。
-- 在 Linux 上，當使用者的 crontab 仍執行舊版 `~/.openclaw/bin/ensure-whatsapp.sh` 時，doctor 會發出警告；該指令碼已不再維護，且當 cron 缺少 systemd 使用者匯流排環境時，可能記錄錯誤的 WhatsApp Gateway 中斷。
-- Doctor 會清理較舊 OpenClaw 版本建立的舊版 Plugin 相依性暫存狀態。當 registry 能解析時，它也會修復遺失的已設定可下載 Plugin，而 2026.5.2 doctor pass 會自動安裝舊設定已使用的可下載 Plugin，然後才將設定標記為該版本已觸碰。如果下載失敗，doctor 會回報安裝錯誤，並保留已設定的 Plugin 項目供下次修復嘗試。
-- Doctor 會透過從 `plugins.allow`/`plugins.entries` 移除遺失的 Plugin id，以及相符的懸空通道設定、Heartbeat 目標和通道模型覆寫，修復過期的 Plugin 設定，前提是 Plugin 探索狀態正常。
-- Doctor 會隔離無效的 Plugin 設定，方法是停用受影響的 `plugins.entries.<id>` 項目並移除其無效的 `config` payload。Gateway 啟動時已只會略過該錯誤 Plugin，因此其他 Plugin 和通道可以繼續執行。
-- 當另一個 supervisor 擁有 Gateway 生命週期時，請設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍會回報 Gateway/服務健康狀態並套用非服務修復，但會略過服務安裝/啟動/重新啟動/bootstrap，以及舊版服務清理。
-- 在 Linux 上，doctor 會忽略非作用中的額外類 Gateway systemd units，且在修復期間不會重寫執行中 systemd Gateway 服務的 command/entrypoint metadata。若你刻意要取代作用中的啟動器，請先停止服務或使用 `openclaw gateway install --force`。
+- 互動式提示（例如鑰匙圈/OAuth 修復）只會在 stdin 是 TTY 且**未**設定 `--non-interactive` 時執行。無頭執行（cron、Telegram、無終端機）會略過提示。
+- 效能：非互動式 `doctor` 執行會略過積極 Plugin 載入，讓無頭健康檢查保持快速。互動式工作階段仍會在檢查需要 Plugin 貢獻時完整載入 Plugin。
+- `--fix`（`--repair` 的別名）會將備份寫入 `~/.openclaw/openclaw.json.bak`，並移除未知的設定鍵，同時列出每個移除項目。
+- `doctor --fix --non-interactive` 會回報遺失或過期的 Gateway 服務定義，但不會在更新修復模式以外安裝或重寫它們。對於遺失的服務，執行 `openclaw gateway install`；如果你刻意要取代啟動器，則執行 `openclaw gateway install --force`。
+- 狀態完整性檢查現在會偵測工作階段目錄中的孤立轉錄檔案。將它們封存為 `.deleted.<timestamp>` 需要互動式確認；`--fix`、`--yes` 和無頭執行會讓它們留在原處。
+- Doctor 也會掃描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的舊版 cron 工作形狀，並可在排程器必須於執行階段自動正規化它們之前就地重寫。
+- 在 Linux 上，當使用者的 crontab 仍執行舊版 `~/.openclaw/bin/ensure-whatsapp.sh` 時，doctor 會發出警告；該指令碼已不再維護，且當 cron 缺少 systemd 使用者匯流排環境時，可能會記錄錯誤的 WhatsApp Gateway 中斷。
+- Doctor 會清理由較舊 OpenClaw 版本建立的舊版 Plugin 相依項暫存狀態。它也會修復設定所參照但遺失的可下載 Plugin，例如 `plugins.entries`、已設定的通道、已設定的提供者/搜尋設定，或已設定的代理程式執行階段。在套件更新期間，doctor 會略過套件管理器 Plugin 修復，直到套件替換完成；如果已設定的 Plugin 之後仍需要復原，請重新執行 `openclaw doctor --fix`。如果下載失敗，doctor 會回報安裝錯誤，並保留已設定的 Plugin 項目供下一次修復嘗試使用。
+- Doctor 會移除 `plugins.allow`/`plugins.entries` 中遺失的 Plugin ID，以及相符的懸空通道設定、Heartbeat 目標和通道模型覆寫，藉此修復過期的 Plugin 設定，前提是 Plugin 探索狀態健康。
+- Doctor 會隔離無效的 Plugin 設定，方法是停用受影響的 `plugins.entries.<id>` 項目，並移除其無效的 `config` 承載。Gateway 啟動已經只會略過該不良 Plugin，因此其他 Plugin 和通道可以繼續執行。
+- 當另一個監督器負責 Gateway 生命週期時，請設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍會回報 Gateway/服務健康狀態並套用非服務修復，但會略過服務安裝/啟動/重新啟動/bootstrap 和舊版服務清理。
+- 在 Linux 上，doctor 會忽略未啟用的額外 Gateway 類 systemd 單元，並且不會在修復期間重寫執行中 systemd Gateway 服務的命令/進入點中繼資料。如果你刻意要取代作用中的啟動器，請先停止服務或使用 `openclaw gateway install --force`。
 - Doctor 會自動將舊版扁平 Talk 設定（`talk.voiceId`、`talk.modelId` 和相關項目）遷移到 `talk.provider` + `talk.providers.<provider>`。
-- 重複執行 `doctor --fix` 時，若唯一差異是物件鍵順序，將不再回報/套用 Talk 正規化。
-- Doctor 包含記憶體搜尋就緒檢查，並可在 embedding credentials 遺失時建議 `openclaw configure --section model`。
-- Doctor 會在未設定 command owner 時發出警告。command owner 是被允許執行僅限 owner 指令並核准危險動作的人類操作員帳號。DM pairing 只讓某人能與 bot 對話；如果你在 first-owner bootstrap 存在前曾核准 sender，請明確設定 `commands.ownerAllowFrom`。
-- Doctor 會在已設定 Codex-mode agents，且操作員的 Codex home 中存在個人 Codex CLI assets 時發出警告。本機 Codex app-server 啟動會使用每個 agent 隔離的 home，因此請使用 `openclaw migrate codex --dry-run` 盤點應刻意提升的 assets。
-- Doctor 會在目前執行階段環境中，因為缺少 bins、env vars、config 或 OS requirements 而導致 default agent 允許的 skills 無法使用時發出警告。`doctor --fix` 可用 `skills.entries.<skill>.enabled=false` 停用這些無法使用的 skills；若你想保持 skill 作用中，請改為安裝/設定遺失的需求。
-- 如果 sandbox mode 已啟用但 Docker 無法使用，doctor 會回報高訊號警告並附上補救方式（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
-- 如果存在舊版 sandbox registry 檔案（`~/.openclaw/sandbox/containers.json` 或 `~/.openclaw/sandbox/browsers.json`），doctor 會回報它們；`openclaw doctor --fix` 會將有效項目遷移到分片 registry 目錄，並隔離無效的舊版檔案。
-- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理且在目前 command path 中無法使用，doctor 會回報唯讀警告，且不會寫入 plaintext fallback credentials。
-- 如果通道 SecretRef 檢查在 fix path 中失敗，doctor 會繼續並回報警告，而不是提早退出。
-- 狀態目錄遷移後，當已啟用的預設 Telegram 或 Discord 帳號依賴 env fallback，且 `TELEGRAM_BOT_TOKEN` 或 `DISCORD_BOT_TOKEN` 無法供 doctor process 使用時，doctor 會發出警告。
-- Telegram `allowFrom` username 自動解析（`doctor --fix`）需要目前 command path 中有可解析的 Telegram token。如果 token 檢查無法使用，doctor 會回報警告，並略過該次 pass 的自動解析。
+- 重複執行 `doctor --fix` 時，如果唯一差異只是物件鍵順序，將不再回報/套用 Talk 正規化。
+- Doctor 包含記憶體搜尋就緒狀態檢查，並可在缺少嵌入認證時建議 `openclaw configure --section model`。
+- Doctor 會在未設定命令擁有者時發出警告。命令擁有者是允許執行僅限擁有者命令並核准危險動作的人類操作員帳戶。DM 配對只會讓某人能與機器人交談；如果你在第一個擁有者 bootstrap 存在前核准過寄件者，請明確設定 `commands.ownerAllowFrom`。
+- 當已設定 Codex 模式代理程式，且操作員的 Codex home 中存在個人 Codex CLI 資產時，Doctor 會發出警告。本機 Codex 應用程式伺服器啟動會使用隔離的每代理程式 home，因此請使用 `openclaw migrate codex --dry-run` 盤點應有意提升的資產。
+- 當預設代理程式允許的 Skills 因缺少 bin、環境變數、設定或 OS 需求而無法在目前執行階段環境中使用時，Doctor 會發出警告。`doctor --fix` 可透過 `skills.entries.<skill>.enabled=false` 停用這些不可用的 Skills；如果你想保持該 skill 啟用，請改為安裝/設定缺少的需求。
+- 如果已啟用沙箱模式但 Docker 不可用，doctor 會回報高訊號警告並附上修復方式（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
+- 如果存在舊版沙箱登錄檔案（`~/.openclaw/sandbox/containers.json` 或 `~/.openclaw/sandbox/browsers.json`），doctor 會回報它們；`openclaw doctor --fix` 會將有效項目遷移到分片登錄目錄，並隔離無效的舊版檔案。
+- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理且在目前命令路徑中不可用，doctor 會回報唯讀警告，且不會寫入純文字後援認證。
+- 如果通道 SecretRef 檢查在修復路徑中失敗，doctor 會繼續並回報警告，而不是提前結束。
+- 在狀態目錄遷移後，當已啟用的預設 Telegram 或 Discord 帳戶依賴環境後援，且 `TELEGRAM_BOT_TOKEN` 或 `DISCORD_BOT_TOKEN` 對 doctor 程序不可用時，doctor 會發出警告。
+- Telegram `allowFrom` 使用者名稱自動解析（`doctor --fix`）需要目前命令路徑中有可解析的 Telegram 權杖。如果權杖檢查不可用，doctor 會回報警告，並略過該次執行的自動解析。
 
-## macOS：`launchctl` env 覆寫
+## macOS：`launchctl` 環境變數覆寫
 
-如果你先前執行過 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），該值會覆寫你的設定檔，並可能造成持續的「未授權」錯誤。
+如果你先前執行過 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），該值會覆寫你的設定檔，並可能導致持續的「未授權」錯誤。
 
 ```bash
 launchctl getenv OPENCLAW_GATEWAY_TOKEN

docs/zh-TW/cli/gateway.md

@@ -1,31 +1,31 @@
 ---
 read_when:
     - 從 CLI 執行 Gateway（開發或伺服器）
-    - 偵錯 Gateway 身分驗證、繫結模式與連線能力
-    - 透過 Bonjour 探索 Gateway（本機 + 廣域 DNS-SD）
+    - 偵錯 Gateway 驗證、繫結模式與連線能力
+    - 透過 Bonjour 探索 Gateway（本地 + 廣域 DNS-SD）
 sidebarTitle: Gateway
 summary: OpenClaw Gateway CLI (`openclaw gateway`) — 執行、查詢並探索 Gateway
 title: Gateway
 x-i18n:
-    generated_at: "2026-05-04T18:23:42Z"
+    generated_at: "2026-05-05T01:44:29Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
+    source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
     source_path: cli/gateway.md
     workflow: 16
 ---
 
-Gateway 是 OpenClaw 的 WebSocket 伺服器（通道、節點、工作階段、hook）。本頁中的子命令位於 `openclaw gateway …` 之下。
+Gateway 是 OpenClaw 的 WebSocket 伺服器（通道、節點、工作階段、hook）。此頁中的子命令位於 `openclaw gateway …` 之下。
 
 <CardGroup cols={3}>
-  <Card title="Bonjour 探索" href="/zh-TW/gateway/bonjour">
+  <Card title="Bonjour discovery" href="/zh-TW/gateway/bonjour">
     本機 mDNS + 廣域 DNS-SD 設定。
   </Card>
-  <Card title="探索概覽" href="/zh-TW/gateway/discovery">
-    OpenClaw 如何公布並尋找 Gateway。
+  <Card title="Discovery overview" href="/zh-TW/gateway/discovery">
+    OpenClaw 如何公告與尋找 Gateway。
   </Card>
-  <Card title="組態" href="/zh-TW/gateway/configuration">
-    頂層 Gateway 組態鍵。
+  <Card title="Configuration" href="/zh-TW/gateway/configuration">
+    頂層 Gateway 設定鍵。
   </Card>
 </CardGroup>
 
@@ -44,13 +44,13 @@ openclaw gateway run
 ```
 
 <AccordionGroup>
-  <Accordion title="啟動行為">
-    - 依預設，除非 `~/.openclaw/openclaw.json` 中設定了 `gateway.mode=local`，否則 Gateway 會拒絕啟動。針對臨時/開發執行，請使用 `--allow-unconfigured`。
-    - `openclaw onboard --mode local` 和 `openclaw setup` 預期會寫入 `gateway.mode=local`。如果檔案存在但缺少 `gateway.mode`，請將其視為損壞或被覆寫的組態並修復，而不是隱含假設為本機模式。
-    - 如果檔案存在且缺少 `gateway.mode`，Gateway 會將其視為可疑的組態損壞，並拒絕替你「猜測為本機」。
-    - 未經驗證就綁定到 loopback 以外的位置會被封鎖（安全護欄）。
-    - `SIGUSR1` 會在獲授權時觸發程序內重新啟動（`commands.restart` 預設啟用；設定 `commands.restart: false` 可封鎖手動重新啟動，同時仍允許 Gateway 工具/組態套用/更新）。
-    - `SIGINT`/`SIGTERM` 處理常式會停止 Gateway 程序，但不會還原任何自訂終端狀態。如果你用 TUI 或原始模式輸入包裝 CLI，請在結束前還原終端。
+  <Accordion title="Startup behavior">
+    - 預設情況下，除非 `~/.openclaw/openclaw.json` 中已設定 `gateway.mode=local`，否則 Gateway 會拒絕啟動。將 `--allow-unconfigured` 用於臨時/開發執行。
+    - 預期 `openclaw onboard --mode local` 和 `openclaw setup` 會寫入 `gateway.mode=local`。如果檔案存在但缺少 `gateway.mode`，請將其視為損壞或被覆寫的設定並修復，而不是隱含假設為本機模式。
+    - 如果檔案存在且缺少 `gateway.mode`，Gateway 會將其視為可疑的設定損壞，並拒絕替你「猜測為本機」。
+    - 未經驗證而綁定到 loopback 之外的位置會被封鎖（安全護欄）。
+    - 授權時，`SIGUSR1` 會觸發程序內重新啟動（`commands.restart` 預設啟用；設定 `commands.restart: false` 可阻擋手動重新啟動，同時仍允許 Gateway 工具/設定套用/更新）。
+    - `SIGINT`/`SIGTERM` 處理常式會停止 Gateway 程序，但不會還原任何自訂終端機狀態。如果你以 TUI 或原始模式輸入包裝 CLI，請在結束前還原終端機。
 
   </Accordion>
 </AccordionGroup>
@@ -58,7 +58,7 @@ openclaw gateway run
 ### 選項
 
 <ParamField path="--port <port>" type="number">
-  WebSocket 連接埠（預設來自組態/環境；通常是 `18789`）。
+  WebSocket 連接埠（預設值來自設定/env；通常為 `18789`）。
 </ParamField>
 <ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
   監聽器綁定模式。
@@ -67,7 +67,7 @@ openclaw gateway run
   驗證模式覆寫。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  Token 覆寫（也會為程序設定 `OPENCLAW_GATEWAY_TOKEN`）。
+  token 覆寫（也會為程序設定 `OPENCLAW_GATEWAY_TOKEN`）。
 </ParamField>
 <ParamField path="--password <password>" type="string">
   密碼覆寫。
@@ -79,28 +79,28 @@ openclaw gateway run
   透過 Tailscale 暴露 Gateway。
 </ParamField>
 <ParamField path="--tailscale-reset-on-exit" type="boolean">
-  關閉時重設 Tailscale serve/funnel 組態。
+  關閉時重設 Tailscale serve/funnel 設定。
 </ParamField>
 <ParamField path="--allow-unconfigured" type="boolean">
-  允許在組態中沒有 `gateway.mode=local` 時啟動 Gateway。僅針對臨時/開發啟動程序繞過啟動護欄；不會寫入或修復組態檔。
+  允許在設定中沒有 `gateway.mode=local` 時啟動 Gateway。僅針對臨時/開發 bootstrap 繞過啟動防護；不會寫入或修復設定檔。
 </ParamField>
 <ParamField path="--dev" type="boolean">
-  如果缺少，建立開發組態 + 工作區（略過 BOOTSTRAP.md）。
+  如果缺少，則建立開發設定 + 工作區（略過 BOOTSTRAP.md）。
 </ParamField>
 <ParamField path="--reset" type="boolean">
-  重設開發組態 + 認證 + 工作階段 + 工作區（需要 `--dev`）。
+  重設開發設定 + 憑證 + 工作階段 + 工作區（需要 `--dev`）。
 </ParamField>
 <ParamField path="--force" type="boolean">
   啟動前終止所選連接埠上的任何既有監聽器。
 </ParamField>
 <ParamField path="--verbose" type="boolean">
-  詳細記錄。
+  詳細日誌。
 </ParamField>
 <ParamField path="--cli-backend-logs" type="boolean">
-  僅在主控台顯示 CLI 後端記錄（並啟用 stdout/stderr）。
+  僅在主控台顯示 CLI 後端日誌（並啟用 stdout/stderr）。
 </ParamField>
 <ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
-  WebSocket 記錄樣式。
+  WebSocket 日誌樣式。
 </ParamField>
 <ParamField path="--compact" type="boolean">
   `--ws-log compact` 的別名。
@@ -120,41 +120,41 @@ openclaw gateway restart --safe
 openclaw gateway restart --force
 ```
 
-`openclaw gateway restart --safe` 會要求執行中的 Gateway 在重新啟動前預檢作用中的 OpenClaw 工作。如果佇列作業、回覆遞送、嵌入式執行或任務執行仍在作用中，Gateway 會回報阻礙項目，合併重複的安全重新啟動請求，並在作用中工作清空後重新啟動。純 `restart` 會保留既有的服務管理員行為以維持相容性。只有在你明確想要立即覆寫路徑時才使用 `--force`。
+`openclaw gateway restart --safe` 會要求執行中的 Gateway 在重新啟動前對作用中的 OpenClaw 工作進行預檢。如果佇列中的操作、回覆傳遞、嵌入式執行或任務執行仍在進行，Gateway 會回報阻擋項目、合併重複的安全重新啟動請求，並在作用中工作清空後重新啟動。一般 `restart` 會保留既有服務管理器行為以維持相容性。只有在你明確想要立即覆寫路徑時才使用 `--force`。
 
 <Warning>
-行內 `--password` 可能會暴露在本機程序清單中。請優先使用 `--password-file`、環境變數，或由 SecretRef 支援的 `gateway.auth.password`。
+行內 `--password` 可能會暴露在本機程序清單中。建議使用 `--password-file`、env，或由 SecretRef 支援的 `gateway.auth.password`。
 </Warning>
 
-### 啟動效能剖析
+### 啟動剖析
 
-- 設定 `OPENCLAW_GATEWAY_STARTUP_TRACE=1`，可在 Gateway 啟動期間記錄各階段耗時，包括每階段的 `eventLoopMax` 延遲，以及已安裝索引、manifest 登錄、啟動規劃和 owner-map 工作的 Plugin 查找表耗時。
-- 設定 `OPENCLAW_DIAGNOSTICS=timeline` 搭配 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`，可為外部 QA 測試架構寫入盡力而為的 JSONL 啟動診斷時間軸。你也可以在組態中使用 `diagnostics.flags: ["timeline"]` 啟用此旗標；路徑仍由環境提供。加入 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 可包含事件迴圈樣本。
-- 執行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 來基準測試 Gateway 啟動。此基準測試會記錄第一個程序輸出、`/healthz`、`/readyz`、啟動追蹤耗時、事件迴圈延遲，以及 Plugin 查找表耗時細節。
+- 設定 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 可在 Gateway 啟動期間記錄階段計時，包括每個階段的 `eventLoopMax` 延遲，以及 installed-index、manifest registry、啟動規劃和 owner-map 工作的 Plugin 查詢表計時。
+- 設定 `OPENCLAW_DIAGNOSTICS=timeline` 並搭配 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`，可為外部 QA harness 寫入盡力而為的 JSONL 啟動診斷時間軸。你也可以在設定中以 `diagnostics.flags: ["timeline"]` 啟用該旗標；路徑仍由 env 提供。加入 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 可包含事件迴圈取樣。
+- 執行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 以對 Gateway 啟動進行基準測試。基準測試會記錄第一個程序輸出、`/healthz`、`/readyz`、啟動追蹤計時、事件迴圈延遲，以及 Plugin 查詢表計時詳細資料。
 
 ## 查詢執行中的 Gateway
 
 所有查詢命令都使用 WebSocket RPC。
 
 <Tabs>
-  <Tab title="輸出模式">
-    - 預設：人類可讀（TTY 中會有色彩）。
+  <Tab title="Output modes">
+    - 預設：人類可讀（在 TTY 中著色）。
     - `--json`：機器可讀 JSON（無樣式/旋轉指示器）。
     - `--no-color`（或 `NO_COLOR=1`）：停用 ANSI，同時保留人類可讀版面。
 
   </Tab>
-  <Tab title="共用選項">
+  <Tab title="Shared options">
     - `--url <url>`：Gateway WebSocket URL。
     - `--token <token>`：Gateway token。
     - `--password <password>`：Gateway 密碼。
     - `--timeout <ms>`：逾時/預算（依命令而異）。
-    - `--expect-final`：等待「final」回應（agent 呼叫）。
+    - `--expect-final`：等待「final」回應（代理呼叫）。
 
   </Tab>
 </Tabs>
 
 <Note>
-當你設定 `--url` 時，CLI 不會回退使用組態或環境認證。請明確傳入 `--token` 或 `--password`。缺少明確認證是一項錯誤。
+設定 `--url` 時，CLI 不會回退使用設定或環境憑證。請明確傳入 `--token` 或 `--password`。缺少明確憑證是錯誤。
 </Note>
 
 ### `gateway health`
@@ -163,11 +163,11 @@ openclaw gateway restart --force
 openclaw gateway health --url ws://127.0.0.1:18789
 ```
 
-HTTP `/healthz` 端點是存活探針：伺服器能回應 HTTP 時就會回傳。HTTP `/readyz` 端點更嚴格，會在啟動中的 Plugin sidecar、通道或已設定 hook 仍在穩定時維持紅燈。本機或已驗證的詳細就緒回應包含 `eventLoop` 診斷區塊，其中有事件迴圈延遲、事件迴圈使用率、CPU 核心比例，以及 `degraded` 旗標。
+HTTP `/healthz` 端點是存活探針：它會在伺服器可回應 HTTP 時回傳。HTTP `/readyz` 端點更嚴格，會在啟動中的 Plugin sidecar、通道或已設定 hook 仍在就緒時保持紅色。本機或已驗證的詳細就緒回應包含 `eventLoop` 診斷區塊，內含事件迴圈延遲、事件迴圈使用率、CPU 核心比率，以及 `degraded` 旗標。
 
 ### `gateway usage-cost`
 
-從工作階段記錄擷取使用成本摘要。
+從工作階段日誌擷取使用成本摘要。
 
 ```bash
 openclaw gateway usage-cost
@@ -181,7 +181,7 @@ openclaw gateway usage-cost --json
 
 ### `gateway stability`
 
-從執行中的 Gateway 擷取最近的診斷穩定性記錄器。
+從執行中的 Gateway 擷取近期診斷穩定性記錄器。
 
 ```bash
 openclaw gateway stability
@@ -192,7 +192,7 @@ openclaw gateway stability --json
 ```
 
 <ParamField path="--limit <limit>" type="number" default="25">
-  要包含的近期事件數上限（最大 `1000`）。
+  要包含的近期事件最大數量（最大 `1000`）。
 </ParamField>
 <ParamField path="--type <type>" type="string">
   依診斷事件類型篩選，例如 `payload.large` 或 `diagnostic.memory.pressure`。
@@ -201,26 +201,26 @@ openclaw gateway stability --json
   僅包含診斷序號之後的事件。
 </ParamField>
 <ParamField path="--bundle [path]" type="string">
-  讀取持久化的穩定性套件，而不是呼叫執行中的 Gateway。針對狀態目錄下最新的套件，請使用 `--bundle latest`（或只用 `--bundle`），或直接傳入套件 JSON 路徑。
+  讀取持久化的穩定性 bundle，而不是呼叫執行中的 Gateway。使用 `--bundle latest`（或只用 `--bundle`）讀取狀態目錄下最新的 bundle，或直接傳入 bundle JSON 路徑。
 </ParamField>
 <ParamField path="--export" type="boolean">
-  寫入可分享的支援診斷 zip，而不是列印穩定性細節。
+  寫入可分享的支援診斷 zip，而不是列印穩定性詳細資料。
 </ParamField>
 <ParamField path="--output <path>" type="string">
   `--export` 的輸出路徑。
 </ParamField>
 
 <AccordionGroup>
-  <Accordion title="隱私與套件行為">
-    - 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/Plugin 名稱，以及已遮蔽的工作階段摘要。它們不會保留聊天文字、webhook 主體、工具輸出、原始請求或回應主體、token、cookie、秘密值、主機名稱，或原始工作階段 ID。設定 `diagnostics.enabled: false` 可完全停用記錄器。
-    - 在 Gateway 致命結束、關閉逾時和重新啟動啟動失敗時，若記錄器有事件，OpenClaw 會將相同的診斷快照寫入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。用 `openclaw gateway stability --bundle latest` 檢查最新套件；`--limit`、`--type` 和 `--since-seq` 也適用於套件輸出。
+  <Accordion title="Privacy and bundle behavior">
+    - 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/Plugin 名稱，以及已修訂的工作階段摘要。它們不會保留聊天文字、Webhook 內文、工具輸出、原始請求或回應內文、token、cookie、祕密值、主機名稱或原始工作階段 ID。設定 `diagnostics.enabled: false` 可完全停用記錄器。
+    - 在致命 Gateway 結束、關閉逾時和重新啟動啟動失敗時，如果記錄器有事件，OpenClaw 會將相同的診斷快照寫入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 檢查最新 bundle；`--limit`、`--type` 和 `--since-seq` 也適用於 bundle 輸出。
 
   </Accordion>
 </AccordionGroup>
 
 ### `gateway diagnostics export`
 
-寫入本機診斷 zip，設計用於附加到錯誤回報。關於隱私模型與套件內容，請參閱[診斷匯出](/zh-TW/gateway/diagnostics)。
+寫入本機診斷 zip，設計用於附加到錯誤報告。關於隱私模型和 bundle 內容，請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。
 
 ```bash
 openclaw gateway diagnostics export
@@ -232,37 +232,37 @@ openclaw gateway diagnostics export --json
   輸出 zip 路徑。預設為狀態目錄下的支援匯出。
 </ParamField>
 <ParamField path="--log-lines <count>" type="number" default="5000">
-  要包含的已清理記錄行數上限。
+  要包含的已清理日誌行數上限。
 </ParamField>
 <ParamField path="--log-bytes <bytes>" type="number" default="1000000">
-  要檢查的記錄位元組數上限。
+  要檢查的日誌位元組上限。
 </ParamField>
 <ParamField path="--url <url>" type="string">
-  用於健康快照的 Gateway WebSocket URL。
+  健康快照的 Gateway WebSocket URL。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  用於健康快照的 Gateway token。
+  健康快照的 Gateway token。
 </ParamField>
 <ParamField path="--password <password>" type="string">
-  用於健康快照的 Gateway 密碼。
+  健康快照的 Gateway 密碼。
 </ParamField>
 <ParamField path="--timeout <ms>" type="number" default="3000">
   狀態/健康快照逾時。
 </ParamField>
 <ParamField path="--no-stability-bundle" type="boolean">
-  略過持久化穩定性套件查找。
+  略過持久化穩定性 bundle 查詢。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  以 JSON 列印寫入的路徑、大小和 manifest。
+  以 JSON 列印寫入路徑、大小和 manifest。
 </ParamField>
 
-匯出內容包含 manifest、Markdown 摘要、組態形狀、已清理的組態細節、已清理的記錄摘要、已清理的 Gateway 狀態/健康快照，以及最新的穩定性套件（若存在）。
+匯出包含 manifest、Markdown 摘要、設定形狀、已清理設定詳細資料、已清理日誌摘要、已清理 Gateway 狀態/健康快照，以及存在時最新的穩定性 bundle。
 
-這是用來分享的。它會保留有助於偵錯的操作細節，例如安全的 OpenClaw 記錄欄位、子系統名稱、狀態碼、持續時間、已設定模式、連接埠、Plugin ID、provider ID、非秘密功能設定，以及已遮蔽的操作記錄訊息。它會省略或遮蔽聊天文字、webhook 主體、工具輸出、認證、cookie、帳號/訊息識別碼、提示/指示文字、主機名稱和秘密值。當 LogTape 風格訊息看起來像使用者/聊天/工具 payload 文字時，匯出只會保留該訊息已被省略，以及其位元組數。
+它是用來分享的。它會保留有助於除錯的操作詳細資料，例如安全的 OpenClaw 日誌欄位、子系統名稱、狀態碼、持續時間、已設定模式、連接埠、Plugin ID、供應商 ID、非祕密功能設定，以及已修訂的操作日誌訊息。它會省略或修訂聊天文字、Webhook 內文、工具輸出、憑證、cookie、帳號/訊息識別碼、提示/指令文字、主機名稱和祕密值。當 LogTape 風格的訊息看起來像使用者/聊天/工具 payload 文字時，匯出只會保留訊息已省略以及其位元組計數。
 
 ### `gateway status`
 
-`gateway status` 會顯示 Gateway 服務（launchd/systemd/schtasks），並加上選用的連線能力/驗證能力探測。
+`gateway status` 會顯示 Gateway 服務（launchd/systemd/schtasks），以及選用的連線/驗證能力探測。
 
 ```bash
 openclaw gateway status
@@ -274,60 +274,60 @@ openclaw gateway status --require-rpc
   新增明確的探測目標。已設定的遠端與 localhost 仍會被探測。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  探測使用的 Token 驗證。
+  探測的權杖驗證。
 </ParamField>
 <ParamField path="--password <password>" type="string">
-  探測使用的密碼驗證。
+  探測的密碼驗證。
 </ParamField>
 <ParamField path="--timeout <ms>" type="number" default="10000">
   探測逾時。
 </ParamField>
 <ParamField path="--no-probe" type="boolean">
-  跳過連線能力探測（僅服務檢視）。
+  略過連線能力探測（僅服務檢視）。
 </ParamField>
 <ParamField path="--deep" type="boolean">
   也掃描系統層級服務。
 </ParamField>
 <ParamField path="--require-rpc" type="boolean">
-  將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零狀態結束。不可與 `--no-probe` 搭配使用。
+  將預設連線能力探測升級為讀取探測，且在該讀取探測失敗時以非零狀態碼退出。不可與 `--no-probe` 合併使用。
 </ParamField>
 
 <AccordionGroup>
   <Accordion title="狀態語意">
-    - 即使本機 CLI 設定缺失或無效，`gateway status` 仍可用於診斷。
-    - 預設的 `gateway status` 會證明服務狀態、WebSocket 連線，以及握手時可見的驗證能力。它不會證明讀取／寫入／管理操作。
-    - 診斷探測對首次裝置驗證不會造成變更：若既有快取裝置 Token 存在，會重複使用它，但不會只為了檢查狀態而建立新的 CLI 裝置身分或唯讀裝置配對記錄。
-    - `gateway status` 會在可能時解析已設定的驗證 SecretRefs，以供探測驗證使用。
-    - 如果此命令路徑中必要的驗證 SecretRef 未解析，當探測連線能力／驗證失敗時，`gateway status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析祕密來源。
-    - 如果探測成功，未解析驗證參照警告會被抑制，以避免誤報。
-    - 當僅有監聽中的服務仍不足夠，且你還需要讀取範圍 RPC 呼叫也保持健康時，請在指令碼與自動化中使用 `--require-rpc`。
-    - `--deep` 會加入對額外 launchd/systemd/schtasks 安裝的盡力掃描。偵測到多個類 Gateway 服務時，人類可讀輸出會列印清理提示，並警告大多數設定應該每台機器只執行一個 Gateway。
-    - 人類可讀輸出包含已解析的檔案日誌路徑，以及 CLI 與服務設定路徑／有效性快照，以協助診斷設定檔或狀態目錄偏移。
+    - 即使本機 CLI 設定遺失或無效，`gateway status` 仍可用於診斷。
+    - 預設的 `gateway status` 會證明服務狀態、WebSocket 連線，以及交握時可見的驗證能力。它不會證明讀取/寫入/管理操作。
+    - 診斷探測對首次裝置驗證不會進行變更：若現有快取裝置權杖存在，會重複使用，但不會只為了檢查狀態而建立新的 CLI 裝置身分或唯讀裝置配對記錄。
+    - `gateway status` 會在可能時解析已設定的驗證 SecretRefs，以用於探測驗證。
+    - 如果此命令路徑中必要的驗證 SecretRef 無法解析，當探測連線能力/驗證失敗時，`gateway status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析祕密來源。
+    - 如果探測成功，未解析的 auth-ref 警告會被抑制，以避免誤報。
+    - 在腳本與自動化中，若僅有正在監聽的服務還不夠，且你也需要讀取範圍 RPC 呼叫維持健康，請使用 `--require-rpc`。
+    - `--deep` 會加入盡力而為的掃描，尋找額外的 launchd/systemd/schtasks 安裝。偵測到多個類 Gateway 服務時，人類可讀輸出會列印清理提示，並警告大多數設定應在每台機器上只執行一個 gateway。
+    - 人類可讀輸出包含已解析的檔案記錄路徑，以及 CLI 與服務設定路徑/有效性快照，以協助診斷設定檔或狀態目錄漂移。
 
   </Accordion>
-  <Accordion title="Linux systemd 驗證偏移檢查">
-    - 在 Linux systemd 安裝中，服務驗證偏移檢查會從 unit 讀取 `Environment=` 與 `EnvironmentFile=` 值（包括 `%h`、加引號的路徑、多個檔案，以及選用的 `-` 檔案）。
-    - 偏移檢查會使用合併後的執行階段環境解析 `gateway.auth.token` SecretRefs（先使用服務命令環境，再回退到處理程序環境）。
-    - 如果 Token 驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或模式未設定且密碼可能優先、且沒有 Token 候選可優先），Token 偏移檢查會跳過設定 Token 解析。
+  <Accordion title="Linux systemd 驗證漂移檢查">
+    - 在 Linux systemd 安裝上，服務驗證漂移檢查會從 unit 讀取 `Environment=` 與 `EnvironmentFile=` 值（包含 `%h`、加引號的路徑、多個檔案，以及可選的 `-` 檔案）。
+    - 漂移檢查會使用合併後的執行階段 env 解析 `gateway.auth.token` SecretRefs（先使用服務命令 env，再退回處理程序 env）。
+    - 如果權杖驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或 mode 未設定且密碼可勝出、沒有權杖候選可勝出），權杖漂移檢查會略過設定權杖解析。
 
   </Accordion>
 </AccordionGroup>
 
 ### `gateway probe`
 
-`gateway probe` 是「偵錯一切」命令。它一律會探測：
+`gateway probe` 是「偵錯所有項目」命令。它一律會探測：
 
-- 你已設定的遠端 Gateway（如果已設定），以及
+- 你已設定的遠端 gateway（如果已設定），以及
 - localhost（loopback），**即使已設定遠端**。
 
-如果你傳入 `--url`，該明確目標會被加入兩者之前。人類可讀輸出會將目標標示為：
+如果你傳入 `--url`，該明確目標會被加到兩者之前。人類可讀輸出會將目標標示為：
 
 - `URL (explicit)`
 - `Remote (configured)` 或 `Remote (configured, inactive)`
 - `Local loopback`
 
 <Note>
-如果可連線到多個 Gateway，它會全部列印出來。當你使用隔離的設定檔／連接埠時（例如救援 bot），支援多個 Gateway，但大多數安裝仍只執行單一 Gateway。
+如果可連線到多個 gateway，它會列印全部。當你使用隔離的設定檔/連接埠時（例如救援 bot），支援多個 gateway，但大多數安裝仍只執行單一 gateway。
 </Note>
 
 ```bash
@@ -338,52 +338,52 @@ openclaw gateway probe --json
 <AccordionGroup>
   <Accordion title="解讀">
     - `Reachable: yes` 表示至少一個目標接受了 WebSocket 連線。
-    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 會回報探測能夠證明的驗證能力。這與可達性是分開的。
-    - `Read probe: ok` 表示讀取範圍詳細 RPC 呼叫（`health`/`status`/`system-presence`/`config.get`）也成功。
-    - `Read probe: limited - missing scope: operator.read` 表示連線成功，但讀取範圍 RPC 受限。這會回報為**降級**可達性，而不是完全失敗。
-    - `Read probe: failed` 在 `Connect: ok` 之後出現，表示 Gateway 接受了 WebSocket 連線，但後續讀取診斷逾時或失敗。這同樣是**降級**可達性，不是無法到達 Gateway。
-    - 與 `gateway status` 一樣，探測會重複使用既有快取裝置驗證，但不會建立首次裝置身分或配對狀態。
-    - 只有在沒有任何被探測的目標可達時，結束碼才會是非零。
+    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 會回報探測能證明的驗證能力。它與可連線性是分開的。
+    - `Read probe: ok` 表示讀取範圍的詳細 RPC 呼叫（`health`/`status`/`system-presence`/`config.get`）也成功。
+    - `Read probe: limited - missing scope: operator.read` 表示連線成功，但讀取範圍 RPC 受限。這會被回報為**降級**的可連線性，而不是完全失敗。
+    - `Connect: ok` 之後的 `Read probe: failed` 表示 Gateway 接受了 WebSocket 連線，但後續讀取診斷逾時或失敗。這也屬於**降級**的可連線性，而不是無法連線的 Gateway。
+    - 和 `gateway status` 一樣，probe 會重複使用既有的快取裝置驗證，但不會建立首次裝置身分或配對狀態。
+    - 只有在沒有任何被探測目標可連線時，退出碼才會是非零。
 
   </Accordion>
   <Accordion title="JSON 輸出">
-    頂層：
+    最上層：
 
-    - `ok`：至少一個目標可達。
+    - `ok`：至少一個目標可連線。
     - `degraded`：至少一個目標接受了連線，但未完成完整的詳細 RPC 診斷。
-    - `capability`：在可達目標中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
-    - `primaryTargetId`：依此順序視為作用中勝出者的最佳目標：明確 URL、SSH tunnel、已設定的遠端，然後是 local loopback。
-    - `warnings[]`：盡力提供的警告記錄，含 `code`、`message`，以及選用的 `targetIds`。
-    - `network`：從目前設定與主機網路衍生出的 local loopback/tailnet URL 提示。
-    - `discovery.timeoutMs` 與 `discovery.count`：此探測回合實際使用的探索預算／結果數。
+    - `capability`：在可連線目標中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
+    - `primaryTargetId`：要視為有效勝出者的最佳目標，順序為：明確 URL、SSH tunnel、已設定遠端，然後是 local loopback。
+    - `warnings[]`：盡力而為的警告記錄，包含 `code`、`message`，以及可選的 `targetIds`。
+    - `network`：從目前設定與主機網路衍生的 local loopback/tailnet URL 提示。
+    - `discovery.timeoutMs` 與 `discovery.count`：此探測流程使用的實際 discovery 預算/結果數量。
 
     每個目標（`targets[].connect`）：
 
-    - `ok`：連線加上降級分類後的可達性。
+    - `ok`：connect 後的可連線性與降級分類。
     - `rpcOk`：完整詳細 RPC 成功。
-    - `scopeLimited`：詳細 RPC 因缺少 operator 範圍而失敗。
+    - `scopeLimited`：詳細 RPC 因缺少 operator scope 而失敗。
 
     每個目標（`targets[].auth`）：
 
     - `role`：可用時，在 `hello-ok` 中回報的驗證角色。
-    - `scopes`：可用時，在 `hello-ok` 中回報的已授予範圍。
-    - `capability`：該目標顯示的驗證能力分類。
+    - `scopes`：可用時，在 `hello-ok` 中回報的已授與 scopes。
+    - `capability`：該目標顯示出的驗證能力分類。
 
   </Accordion>
   <Accordion title="常見警告代碼">
-    - `ssh_tunnel_failed`：SSH tunnel 設定失敗；命令已回退到直接探測。
-    - `multiple_gateways`：有多個目標可達；除非你有意執行隔離設定檔，例如救援 bot，否則這並不常見。
-    - `auth_secretref_unresolved`：已設定的驗證 SecretRef 無法為失敗目標解析。
+    - `ssh_tunnel_failed`：SSH tunnel 設定失敗；命令退回直接探測。
+    - `multiple_gateways`：有多個目標可連線；除非你刻意執行隔離設定檔，例如救援 bot，否則這並不常見。
+    - `auth_secretref_unresolved`：無法為失敗目標解析已設定的驗證 SecretRef。
     - `probe_scope_limited`：WebSocket 連線成功，但讀取探測因缺少 `operator.read` 而受限。
 
   </Accordion>
 </AccordionGroup>
 
-#### 透過 SSH 遠端連線（Mac app parity）
+#### 透過 SSH 遠端（與 Mac 應用程式對等）
 
-macOS app 的「Remote over SSH」模式使用本機連接埠轉送，因此遠端 Gateway（可能只繫結到 loopback）可在 `ws://127.0.0.1:<port>` 連線。
+macOS 應用程式的「Remote over SSH」模式會使用本機連接埠轉送，讓遠端 gateway（可能只綁定到 loopback）可在 `ws://127.0.0.1:<port>` 連線。
 
-CLI 等效命令：
+CLI 對等命令：
 
 ```bash
 openclaw gateway probe --ssh user@gateway-host
@@ -396,10 +396,10 @@ openclaw gateway probe --ssh user@gateway-host
   身分檔案。
 </ParamField>
 <ParamField path="--ssh-auto" type="boolean">
-  從已解析的探索端點（`local.` 加上已設定的廣域網域，如有）選擇第一個探索到的 Gateway 主機作為 SSH 目標。純 TXT 提示會被忽略。
+  從已解析的 discovery 端點（`local.` 加上已設定的廣域網域，如果有）挑選第一個探索到的 gateway 主機作為 SSH 目標。僅 TXT 的提示會被忽略。
 </ParamField>
 
-設定（選用，用作預設值）：
+設定（可選，用作預設值）：
 
 - `gateway.remote.sshTarget`
 - `gateway.remote.sshIdentity`
@@ -414,13 +414,13 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
 ```
 
 <ParamField path="--params <json>" type="string" default="{}">
-  參數用的 JSON 物件字串。
+  params 的 JSON 物件字串。
 </ParamField>
 <ParamField path="--url <url>" type="string">
   Gateway WebSocket URL。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  Gateway Token。
+  Gateway 權杖。
 </ParamField>
 <ParamField path="--password <password>" type="string">
   Gateway 密碼。
@@ -429,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
   逾時預算。
 </ParamField>
 <ParamField path="--expect-final" type="boolean">
-  主要用於 agent 樣式的 RPC，這類 RPC 會在最終 payload 前串流中繼事件。
+  主要用於 agent 風格的 RPC，這類 RPC 會在最終 payload 前串流中繼事件。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  機器可讀 JSON 輸出。
+  機器可讀的 JSON 輸出。
 </ParamField>
 
 <Note>
@@ -452,8 +452,8 @@ openclaw gateway uninstall
 ### 使用 wrapper 安裝
 
 當受管理服務必須透過另一個可執行檔啟動時，請使用 `--wrapper`，例如
-secrets manager shim 或 run-as helper。wrapper 會接收一般 Gateway 引數，並
-負責最終以這些引數 exec `openclaw` 或 Node。
+祕密管理器 shim 或 run-as 輔助工具。wrapper 會收到正常的 Gateway args，並
+負責最終 exec `openclaw` 或帶有這些 args 的 Node。
 
 ```bash
 cat > ~/.local/bin/openclaw-doppler <<'EOF'
@@ -468,8 +468,8 @@ openclaw gateway restart
 ```
 
 你也可以透過環境設定 wrapper。`gateway install` 會驗證該路徑是
-可執行檔，將 wrapper 寫入服務 `ProgramArguments`，並在服務環境中保存
-`OPENCLAW_WRAPPER`，供日後強制重新安裝、更新與 doctor
+可執行檔，將 wrapper 寫入服務 `ProgramArguments`，並在服務環境中保留
+`OPENCLAW_WRAPPER`，以供日後強制重新安裝、更新與 doctor
 修復使用。
 
 ```bash
@@ -477,7 +477,7 @@ OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --
 openclaw doctor
 ```
 
-若要移除已保存的 wrapper，請在重新安裝時清除 `OPENCLAW_WRAPPER`：
+若要移除已保留的 wrapper，請在重新安裝時清除 `OPENCLAW_WRAPPER`：
 
 ```bash
 OPENCLAW_WRAPPER= openclaw gateway install --force
@@ -488,42 +488,43 @@ openclaw gateway restart
   <Accordion title="命令選項">
     - `gateway status`：`--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json`
     - `gateway install`：`--port`、`--runtime <node|bun>`、`--token`、`--wrapper <path>`、`--force`、`--json`
-    - `gateway restart`：`--force`、`--wait <duration>`、`--json`
+    - `gateway restart`：`--safe`、`--force`、`--wait <duration>`、`--json`
     - `gateway uninstall|start|stop`：`--json`
 
   </Accordion>
   <Accordion title="生命週期行為">
-    - 使用 `gateway restart` 重新啟動受管理服務。不要將 `gateway stop` 與 `gateway start` 串接作為重新啟動的替代方式；在 macOS 上，`gateway stop` 會在停止 LaunchAgent 前刻意停用它。
-    - `gateway restart --wait 30s` 會覆寫此次重新啟動設定的重啟排空預算。裸數字為毫秒；接受 `s`、`m`、`h` 等單位。`--wait 0` 會無限期等待。
-    - `gateway restart --force` 會跳過作用中工作排空並立即重新啟動。當操作員已檢查列出的任務阻擋項，且希望 Gateway 立即恢復時使用。
-    - 生命週期命令接受 `--json` 以供指令碼使用。
+    - 使用 `gateway restart` 重新啟動受管理服務。不要串接 `gateway stop` 與 `gateway start` 作為重新啟動替代方案；在 macOS 上，`gateway stop` 會刻意在停止 LaunchAgent 前停用它。
+    - `gateway restart --safe` 會要求執行中的 Gateway 預檢作用中的 OpenClaw 工作，並延後重新啟動，直到回覆傳遞、embedded runs 與 task runs 全部清空。`--safe` 不可與 `--force` 或 `--wait` 合併使用。
+    - `gateway restart --wait 30s` 會覆寫該次重新啟動已設定的 restart drain 預算。單純數字是毫秒；也接受 `s`、`m`、`h` 等單位。`--wait 0` 會無限期等待。
+    - `gateway restart --force` 會略過作用中工作 drain，並立即重新啟動。當 operator 已檢查列出的 task blockers 並希望 gateway 立即恢復時，請使用它。
+    - 生命週期命令接受 `--json` 以供腳本使用。
 
   </Accordion>
   <Accordion title="安裝時的驗證與 SecretRefs">
-    - 當 Token 驗證需要 Token，且 `gateway.auth.token` 由 SecretRef 管理時，`gateway install` 會驗證 SecretRef 可解析，但不會將已解析 Token 保存到服務環境中繼資料。
-    - 如果 Token 驗證需要 Token，且已設定的 Token SecretRef 未解析，安裝會以失敗關閉，而不是保存回退純文字。
-    - 對 `gateway run` 的密碼驗證，優先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或由 SecretRef 支援的 `gateway.auth.password`，而不是內嵌 `--password`。
-    - 在推斷驗證模式中，僅 shell 的 `OPENCLAW_GATEWAY_PASSWORD` 不會放寬安裝 Token 要求；安裝受管理服務時，請使用持久設定（`gateway.auth.password` 或設定 `env`）。
-    - 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，安裝會被封鎖，直到明確設定模式。
+    - 當權杖驗證需要權杖且 `gateway.auth.token` 由 SecretRef 管理時，`gateway install` 會驗證 SecretRef 可解析，但不會將解析出的權杖保存到服務環境中繼資料。
+    - 如果權杖驗證需要權杖，而設定的權杖 SecretRef 無法解析，安裝會以關閉失敗處理，而不是保存備援純文字。
+    - 對於 `gateway run` 上的密碼驗證，請優先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或由 SecretRef 支援的 `gateway.auth.password`，而不是內嵌的 `--password`。
+    - 在推斷的驗證模式中，僅存在於 shell 的 `OPENCLAW_GATEWAY_PASSWORD` 不會放寬安裝權杖需求；安裝受管理服務時，請使用持久設定（`gateway.auth.password` 或設定 `env`）。
+    - 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且未設定 `gateway.auth.mode`，安裝會被阻擋，直到明確設定模式。
 
   </Accordion>
 </AccordionGroup>
 
-## 探索 Gateway（Bonjour）
+## 探索 Gateway (Bonjour)
 
-`gateway discover` 會掃描 Gateway beacon（`_openclaw-gw._tcp`）。
+`gateway discover` 會掃描 Gateway 信標（`_openclaw-gw._tcp`）。
 
-- 多點傳播 DNS-SD：`local.`
-- 單點傳播 DNS-SD（Wide-Area Bonjour）：選擇一個網域（例如：`openclaw.internal.`）並設定分割 DNS + DNS 伺服器；請參閱 [Bonjour](/zh-TW/gateway/bonjour)。
+- 多播 DNS-SD：`local.`
+- 單播 DNS-SD（廣域 Bonjour）：選擇一個網域（例如：`openclaw.internal.`）並設定分割 DNS + DNS 伺服器；請參閱 [Bonjour](/zh-TW/gateway/bonjour)。
 
-只有啟用 Bonjour 探索功能的 Gateway（預設）會公告信標。
+只有啟用 Bonjour 探索（預設）的 Gateway 會廣播信標。
 
 廣域探索記錄包含（TXT）：
 
 - `role`（Gateway 角色提示）
 - `transport`（傳輸提示，例如 `gateway`）
 - `gatewayPort`（WebSocket 連接埠，通常是 `18789`）
-- `sshPort`（選用；不存在時用戶端預設 SSH 目標為 `22`）
+- `sshPort`（選用；缺少時，客戶端預設 SSH 目標為 `22`）
 - `tailnetDns`（MagicDNS 主機名稱，可用時）
 - `gatewayTls` / `gatewayTlsSha256`（已啟用 TLS + 憑證指紋）
 - `cliPath`（寫入廣域區域的遠端安裝提示）
@@ -538,7 +539,7 @@ openclaw gateway discover
   每個命令的逾時時間（瀏覽/解析）。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  機器可讀輸出（也會停用樣式/旋轉指示器）。
+  機器可讀輸出（也會停用樣式/載入指示器）。
 </ParamField>
 
 範例：
@@ -549,9 +550,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
 ```
 
 <Note>
-- 啟用廣域網域時，CLI 會掃描 `local.` 加上已設定的廣域網域。
-- JSON 輸出中的 `wsUrl` 是從已解析的服務端點衍生而來，而不是來自僅限 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
-- 在 `local.` mDNS 上，只有當 `discovery.mdns.mode` 為 `full` 時，才會廣播 `sshPort` 和 `cliPath`。廣域 DNS-SD 仍會寫入 `cliPath`；`sshPort` 在那裡也維持選用。
+- CLI 會掃描 `local.`，以及啟用時所設定的廣域網域。
+- JSON 輸出中的 `wsUrl` 是從解析出的服務端點衍生而來，而不是來自僅限 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
+- 在 `local.` mDNS 上，只有當 `discovery.mdns.mode` 為 `full` 時，才會廣播 `sshPort` 和 `cliPath`。廣域 DNS-SD 仍會寫入 `cliPath`；`sshPort` 在該處也維持選用。
 
 </Note>
 

docs/zh-TW/cli/plugins.md

@@ -1,36 +1,36 @@
 ---
 read_when:
-    - 你想安裝或管理 Gateway Plugin 或相容套件組合
-    - 你想要偵錯 Plugin 載入失敗問題
+    - 你想要安裝或管理 Gateway Plugin 或相容套件
+    - 你想偵錯 Plugin 載入失敗
 sidebarTitle: Plugins
-summary: '`openclaw plugins` 的 CLI 參考（列出、安裝、市集、解除安裝、啟用/停用、診斷）'
-title: Plugin
+summary: CLI 參考：`openclaw plugins`（列出、安裝、市集、解除安裝、啟用/停用、doctor）
+title: Plugins
 x-i18n:
-    generated_at: "2026-05-04T09:37:05Z"
+    generated_at: "2026-05-05T01:44:26Z"
     model: gpt-5.5
     provider: openai
-    source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
+    source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a
     source_path: cli/plugins.md
     workflow: 16
 ---
 
-管理 Gateway Plugin、hook 套件包與相容套件組。
+管理 Gateway Plugin、hook 套件與相容的 bundle。
 
 <CardGroup cols={2}>
-  <Card title="Plugin system" href="/zh-TW/tools/plugin">
-    安裝、啟用與疑難排解 Plugin 的終端使用者指南。
+  <Card title="Plugin 系統" href="/zh-TW/tools/plugin">
+    給終端使用者的 Plugin 安裝、啟用與疑難排解指南。
   </Card>
-  <Card title="Manage plugins" href="/zh-TW/plugins/manage-plugins">
+  <Card title="管理 Plugin" href="/zh-TW/plugins/manage-plugins">
     安裝、列出、更新、解除安裝與發布的快速範例。
   </Card>
-  <Card title="Plugin bundles" href="/zh-TW/plugins/bundles">
-    套件組相容性模型。
+  <Card title="Plugin bundle" href="/zh-TW/plugins/bundles">
+    Bundle 相容性模型。
   </Card>
   <Card title="Plugin manifest" href="/zh-TW/plugins/manifest">
-    資訊清單欄位與設定結構描述。
+    Manifest 欄位與設定 schema。
   </Card>
-  <Card title="Security" href="/zh-TW/gateway/security">
-    Plugin 安裝的安全強化。
+  <Card title="安全性" href="/zh-TW/gateway/security">
+    Plugin 安裝的安全性強化。
   </Card>
 </CardGroup>
 
@@ -62,14 +62,14 @@ openclaw plugins marketplace list <marketplace>
 openclaw plugins marketplace list <marketplace> --json
 ```
 
-若要調查緩慢的安裝、檢查、解除安裝或登錄重新整理，請搭配 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 執行命令。追蹤會將階段計時寫入 stderr，並讓 JSON 輸出保持可解析。請參閱[偵錯](/zh-TW/help/debugging#plugin-lifecycle-trace)。
+若要調查緩慢的安裝、檢查、解除安裝或 registry 重新整理，請使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 執行該命令。Trace 會將各階段耗時寫入 stderr，並保持 JSON 輸出可解析。請參閱[偵錯](/zh-TW/help/debugging#plugin-lifecycle-trace)。
 
 <Note>
-隨附的 Plugin 會與 OpenClaw 一起提供。有些預設啟用（例如隨附的模型提供者、隨附的語音提供者，以及隨附的瀏覽器 Plugin）；其他則需要執行 `plugins enable`。
+Bundled plugins 會隨 OpenClaw 一起提供。有些預設啟用（例如 bundled model providers、bundled speech providers，以及 bundled browser plugin）；其他則需要 `plugins enable`。
 
-原生 OpenClaw Plugin 必須提供 `openclaw.plugin.json`，並包含內嵌 JSON Schema（`configSchema`，即使是空的也一樣）。相容套件組則改用自己的套件組資訊清單。
+原生 OpenClaw Plugin 必須隨附 `openclaw.plugin.json`，並包含內嵌 JSON Schema（`configSchema`，即使是空的也一樣）。相容的 bundle 則使用自己的 bundle manifest。
 
-`plugins list` 會顯示 `Format: openclaw` 或 `Format: bundle`。詳細列出/資訊輸出也會顯示套件組子類型（`codex`、`claude` 或 `cursor`）以及偵測到的套件組功能。
+`plugins list` 會顯示 `Format: openclaw` 或 `Format: bundle`。詳細 list/info 輸出也會顯示 bundle 子類型（`codex`、`claude` 或 `cursor`）以及偵測到的 bundle capabilities。
 </Note>
 
 ### 安裝
@@ -91,93 +91,93 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
 ```
 
 <Warning>
-在啟動切換期間，裸套件名稱預設會從 npm 安裝。ClawHub 請使用 `clawhub:<package>`。請將 Plugin 安裝視同執行程式碼。建議使用釘選版本。
+在啟動切換期間，裸套件名稱預設會從 npm 安裝。ClawHub 請使用 `clawhub:<package>`。請像執行程式碼一樣看待 Plugin 安裝。建議優先使用釘選版本。
 </Warning>
 
-`plugins search` 會查詢 ClawHub 中可安裝的 Plugin 套件，並印出可直接安裝的套件名稱。它會搜尋 code-plugin 與 bundle-plugin 套件，而不是 Skills。若要搜尋 ClawHub Skills，請使用 `openclaw skills search`。
+`plugins search` 會查詢 ClawHub 中可安裝的 Plugin 套件，並列印可直接安裝的套件名稱。它會搜尋 code-plugin 與 bundle-plugin 套件，而不是 Skills。ClawHub Skills 請使用 `openclaw skills search`。
 
 <Note>
-ClawHub 是大多數 Plugin 的主要發佈與探索介面。npm 仍是受支援的備援與直接安裝路徑。OpenClaw 擁有的 `@openclaw/*` Plugin 套件已重新發布到 npm；請在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [Plugin 清單](/zh-TW/plugins/plugin-inventory)查看目前清單。穩定版安裝使用 `latest`。Beta 通道安裝與更新會在 npm `beta` dist-tag 可用時優先使用該標籤，然後才回退到 `latest`。
+ClawHub 是大多數 Plugin 的主要散佈與探索介面。Npm 仍是受支援的備援與直接安裝路徑。OpenClaw 擁有的 `@openclaw/*` Plugin 套件已重新發布到 npm；請在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [Plugin 庫存](/zh-TW/plugins/plugin-inventory)查看目前清單。穩定版安裝使用 `latest`。Beta-channel 安裝與更新會在 npm `beta` dist-tag 可用時優先使用該 tag，然後才回退到 `latest`。
 </Note>
 
 <AccordionGroup>
-  <Accordion title="Config includes and invalid-config repair">
-    如果你的 `plugins` 區段由單一檔案 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會寫入該被包含的檔案，並保持 `openclaw.json` 不變。根層包含、包含陣列，以及帶有同層覆寫的包含都會封閉失敗，而不是攤平成單一內容。支援的形狀請參閱[設定包含](/zh-TW/gateway/configuration)。
+  <Accordion title="設定 include 與無效設定修復">
+    如果你的 `plugins` 區段由單一檔案 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會寫入該被 include 的檔案，並保持 `openclaw.json` 不變。根 include、include 陣列，以及帶有同層覆寫的 include 會 fail closed，而不是被攤平成單一設定。支援的形狀請參閱[設定 include](/zh-TW/gateway/configuration)。
 
-    如果安裝期間設定無效，`plugins install` 通常會封閉失敗，並告訴你先執行 `openclaw doctor --fix`。在 Gateway 啟動與熱重新載入期間，無效的 Plugin 設定會像任何其他無效設定一樣封閉失敗；`openclaw doctor --fix` 可以隔離無效的 Plugin 項目。唯一記載的安裝時例外，是針對明確選擇加入 `openclaw.install.allowInvalidConfigRecovery` 的 Plugin 所提供的狹窄隨附 Plugin 復原路徑。
+    如果安裝期間設定無效，`plugins install` 通常會 fail closed，並提示你先執行 `openclaw doctor --fix`。Gateway 啟動與熱重新載入期間，無效的 Plugin 設定會像其他無效設定一樣 fail closed；`openclaw doctor --fix` 可以隔離無效的 Plugin 項目。唯一記錄於文件中的安裝時例外，是針對明確選擇加入 `openclaw.install.allowInvalidConfigRecovery` 的 Plugin 所提供的狹窄 bundled-plugin 復原路徑。
 
   </Accordion>
-  <Accordion title="--force and reinstall vs update">
-    `--force` 會重用現有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件包。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm 成品重新安裝相同 id 時使用。對於已追蹤的 npm Plugin 的例行升級，建議使用 `openclaw plugins update <id-or-npm-spec>`。
+  <Accordion title="--force 與重新安裝相對於更新">
+    `--force` 會重用既有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm artifact 重新安裝相同 id 時使用它。對於已追蹤 npm Plugin 的例行升級，建議使用 `openclaw plugins update <id-or-npm-spec>`。
 
-    如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並指引你使用 `plugins update <id-or-npm-spec>` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時，使用 `plugins install <package> --force`。
+    如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並引導你使用 `plugins update <id-or-npm-spec>` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時使用 `plugins install <package> --force`。
 
   </Accordion>
-  <Accordion title="--pin scope">
-    `--pin` 只適用於 npm 安裝。不支援搭配 `git:` 安裝；若你想要釘選來源，請使用明確的 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它也不支援搭配 `--marketplace`，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm 規格。
+  <Accordion title="--pin 範圍">
+    `--pin` 只適用於 npm 安裝。不支援與 `git:` 安裝搭配；如果你想要釘選來源，請使用明確的 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它也不支援與 `--marketplace` 搭配，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm spec。
   </Accordion>
   <Accordion title="--dangerously-force-unsafe-install">
-    `--dangerously-force-unsafe-install` 是針對內建危險程式碼掃描器誤判的緊急選項。即使內建掃描器回報 `critical` 發現，它也允許安裝繼續，但它**不會**略過 Plugin `before_install` hook 政策阻擋，也**不會**略過掃描失敗。
+    `--dangerously-force-unsafe-install` 是針對內建 dangerous-code scanner 誤判的 break-glass 選項。即使內建 scanner 回報 `critical` findings，它也允許安裝繼續，但它**不會**繞過 Plugin `before_install` hook 政策封鎖，也**不會**繞過掃描失敗。
 
-    此 CLI 旗標適用於 Plugin 安裝/更新流程。由 Gateway 支援的 skill 相依性安裝會使用對應的 `dangerouslyForceUnsafeInstall` 請求覆寫，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
+    這個 CLI flag 適用於 Plugin 安裝/更新流程。Gateway-backed skill 依賴安裝使用相符的 `dangerouslyForceUnsafeInstall` request override，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
 
-    如果你發布在 ClawHub 的 Plugin 被登錄掃描阻擋，請使用 [ClawHub](/zh-TW/tools/clawhub) 中的發布者步驟。
+    如果你發布在 ClawHub 的 Plugin 被 registry 掃描封鎖，請使用 [ClawHub](/zh-TW/tools/clawhub) 中的發布者步驟。
 
   </Accordion>
-  <Accordion title="Hook packs and npm specs">
-    `plugins install` 也是安裝 hook 套件包的介面，這些套件包會在 `package.json` 中公開 `openclaw.hooks`。請使用 `openclaw hooks` 取得篩選後的 hook 可見性與個別 hook 啟用狀態，而不是用於套件安裝。
+  <Accordion title="Hook 套件與 npm specs">
+    `plugins install` 也是安裝在 `package.json` 中公開 `openclaw.hooks` 的 hook 套件的介面。請使用 `openclaw hooks` 查看經篩選的 hook 可見性與個別 hook 啟用狀態，而不是用於套件安裝。
 
-    npm 規格是**僅限登錄**（套件名稱 + 選用的**精確版本**或 **dist-tag**）。Git/URL/file 規格與 semver 範圍會被拒絕。為了安全，即使你的 shell 有全域 npm 安裝設定，相依性安裝也會以專案本機方式搭配 `--ignore-scripts` 執行。
+    Npm specs **僅限 registry**（套件名稱 + 選用的**精確版本**或 **dist-tag**）。Git/URL/file specs 與 semver ranges 會被拒絕。為了安全，即使你的 shell 有全域 npm 安裝設定，依賴安裝也會以專案本機方式搭配 `--ignore-scripts` 執行。
 
-    當你想明確使用 npm 解析時，請使用 `npm:<package>`。在啟動切換期間，裸套件規格也會直接從 npm 安裝。
+    當你想明確使用 npm 解析時，請使用 `npm:<package>`。在啟動切換期間，裸套件 spec 也會直接從 npm 安裝。
 
-    裸規格與 `@latest` 會保持在穩定軌道。OpenClaw 日期戳記修正版（例如 `2026.5.3-1`）在此檢查中屬於穩定版本。如果 npm 將其中任一解析為預發行版本，OpenClaw 會停止並要求你以預發行標籤（例如 `@beta`/`@rc`）或精確預發行版本（例如 `@1.2.3-beta.4`）明確選擇加入。
+    裸 specs 與 `@latest` 會留在穩定版軌道。OpenClaw 日期戳記修正版，例如 `2026.5.3-1`，在此檢查中屬於穩定版發行。如果 npm 將其中任何一種解析為 prerelease，OpenClaw 會停止並要求你使用 prerelease tag（例如 `@beta`/`@rc`）或精確的 prerelease 版本（例如 `@1.2.3-beta.4`）明確選擇加入。
 
-    如果裸安裝規格符合官方 Plugin id（例如 `diffs`），OpenClaw 會直接安裝目錄項目。若要安裝同名 npm 套件，請使用明確的 scoped 規格（例如 `@scope/diffs`）。
+    如果裸安裝 spec 符合官方 Plugin id（例如 `diffs`），OpenClaw 會直接安裝 catalog 項目。若要安裝同名 npm 套件，請使用明確的 scoped spec（例如 `@scope/diffs`）。
 
   </Accordion>
   <Accordion title="Git repositories">
-    使用 `git:<repo>` 可直接從 git 儲存庫安裝。支援的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URL。加入 `@<ref>` 或 `#<ref>` 可在安裝前取出分支、標籤或 commit。
+    使用 `git:<repo>` 直接從 git repository 安裝。支援的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URLs。加入 `@<ref>` 或 `#<ref>` 可在安裝前 checkout 分支、tag 或 commit。
 
-    Git 安裝會 clone 到暫存目錄，在有要求的 ref 時將其取出，然後使用一般 Plugin 目錄安裝器。這表示資訊清單驗證、危險程式碼掃描、套件管理器安裝工作與安裝記錄的行為會像 npm 安裝一樣。已記錄的 git 安裝會包含來源 URL/ref 以及已解析的 commit，讓 `openclaw plugins update` 之後可以重新解析來源。
+    Git 安裝會 clone 到暫存目錄，在有要求 ref 時 checkout 該 ref，然後使用一般 Plugin 目錄安裝程式。這表示 manifest 驗證、dangerous-code 掃描、package-manager 安裝工作，以及安裝記錄的行為都會像 npm 安裝一樣。記錄的 git 安裝會包含來源 URL/ref 以及解析後的 commit，讓 `openclaw plugins update` 之後可以重新解析來源。
 
-    從 git 安裝後，請使用 `openclaw plugins inspect <id> --runtime --json` 驗證執行階段註冊，例如 gateway 方法與 CLI 命令。如果 Plugin 使用 `api.registerCli` 註冊了 CLI 根命令，請透過 OpenClaw 根 CLI 直接執行該命令，例如 `openclaw demo-plugin ping`。
+    從 git 安裝後，請使用 `openclaw plugins inspect <id> --runtime --json` 驗證 runtime 註冊，例如 gateway methods 與 CLI commands。如果該 Plugin 使用 `api.registerCli` 註冊了 CLI root，請直接透過 OpenClaw root CLI 執行該命令，例如 `openclaw demo-plugin ping`。
 
   </Accordion>
-  <Accordion title="Archives">
-    支援的封存檔：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin 封存檔必須在解壓後的 Plugin 根目錄包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。
+  <Accordion title="封存檔">
+    支援的封存檔：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin 封存檔必須在解壓後的 Plugin root 包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。
 
     也支援 Claude marketplace 安裝。
 
   </Accordion>
 </AccordionGroup>
 
-ClawHub 安裝會使用明確的 `clawhub:<package>` 定位器：
+ClawHub 安裝使用明確的 `clawhub:<package>` locator：
 
 ```bash
 openclaw plugins install clawhub:openclaw-codex-app-server
 openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
 ```
 
-在啟動切換期間，裸 npm 安全 Plugin 規格預設會從 npm 安裝：
+在啟動切換期間，裸 npm-safe Plugin specs 預設會從 npm 安裝：
 
 ```bash
 openclaw plugins install openclaw-codex-app-server
 ```
 
-使用 `npm:` 可明確指定僅使用 npm 解析：
+使用 `npm:` 明確指定僅使用 npm 解析：
 
 ```bash
 openclaw plugins install npm:openclaw-codex-app-server
 openclaw plugins install npm:@scope/plugin-name@1.0.1
 ```
 
-OpenClaw 會在安裝前檢查公告的 Plugin API / 最低 gateway 相容性。當選取的 ClawHub 版本發布 ClawPack 成品時，OpenClaw 會下載版本化 npm-pack `.tgz`，驗證 ClawHub digest 標頭與成品 digest，然後透過一般封存路徑安裝。沒有 ClawPack 中繼資料的較舊 ClawHub 版本仍會透過舊版套件封存驗證路徑安裝。已記錄的安裝會保留其 ClawHub 來源中繼資料、成品種類、npm integrity、npm shasum、tarball 名稱，以及 ClawPack digest 事實，以供之後更新。
-未指定版本的 ClawHub 安裝會保留未指定版本的記錄規格，讓 `openclaw plugins update` 可以跟隨較新的 ClawHub 發行；明確版本或標籤選擇器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）則會保持釘選到該選擇器。
+OpenClaw 會在安裝前檢查宣告的 Plugin API / 最低 gateway 相容性。當選取的 ClawHub 版本發布 ClawPack artifact 時，OpenClaw 會下載 versioned npm-pack `.tgz`、驗證 ClawHub digest header 與 artifact digest，然後透過一般封存檔路徑安裝。沒有 ClawPack metadata 的舊版 ClawHub 版本仍會透過 legacy package archive verification 路徑安裝。記錄的安裝會保留其 ClawHub 來源中繼資料、artifact kind、npm integrity、npm shasum、tarball name，以及 ClawPack digest facts，以供日後更新使用。
+未版本化的 ClawHub 安裝會保留未版本化的 recorded spec，讓 `openclaw plugins update` 可以跟隨較新的 ClawHub 發行；明確版本或 tag selectors，例如 `clawhub:pkg@1.2.3` 與 `clawhub:pkg@beta`，則會維持釘選到該 selector。
 
 #### Marketplace 簡寫
 
-當 marketplace 名稱存在於 Claude 位於 `~/.claude/plugins/known_marketplaces.json` 的本機登錄快取中時，請使用 `plugin@marketplace` 簡寫：
+當 marketplace 名稱存在於 Claude 位於 `~/.claude/plugins/known_marketplaces.json` 的本機 registry cache 時，使用 `plugin@marketplace` 簡寫：
 
 ```bash
 openclaw plugins marketplace list <marketplace-name>
@@ -195,27 +195,27 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
 
 <Tabs>
   <Tab title="Marketplace sources">
-    - 來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名稱
-    - 本機 marketplace 根目錄或 `marketplace.json` 路徑
+    - 來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知市集名稱
+    - 本機市集根目錄或 `marketplace.json` 路徑
     - GitHub repo 簡寫，例如 `owner/repo`
     - GitHub repo URL，例如 `https://github.com/owner/repo`
     - git URL
 
   </Tab>
   <Tab title="Remote marketplace rules">
-    對於從 GitHub 或 git 載入的遠端 marketplace，Plugin 項目必須保留在複製下來的 marketplace repo 內。OpenClaw 會接受來自該 repo 的相對路徑來源，並拒絕遠端 manifest 中的 HTTP(S)、絕對路徑、git、GitHub，以及其他非路徑 Plugin 來源。
+    對於從 GitHub 或 git 載入的遠端市集，plugin 項目必須留在已複製的市集 repo 內。OpenClaw 接受來自該 repo 的相對路徑來源，並拒絕遠端 manifest 中的 HTTP(S)、絕對路徑、git、GitHub，以及其他非路徑的 plugin 來源。
   </Tab>
 </Tabs>
 
 對於本機路徑與封存檔，OpenClaw 會自動偵測：
 
-- 原生 OpenClaw plugins（`openclaw.plugin.json`）
-- Codex 相容套件組合（`.codex-plugin/plugin.json`）
-- Claude 相容套件組合（`.claude-plugin/plugin.json` 或預設 Claude 元件版面配置）
-- Cursor 相容套件組合（`.cursor-plugin/plugin.json`）
+- 原生 OpenClaw plugins (`openclaw.plugin.json`)
+- Codex 相容套件 (`.codex-plugin/plugin.json`)
+- Claude 相容套件 (`.claude-plugin/plugin.json` 或預設的 Claude 元件版面配置)
+- Cursor 相容套件 (`.cursor-plugin/plugin.json`)
 
 <Note>
-相容套件組合會安裝到一般 Plugin 根目錄，並參與相同的列出/資訊/啟用/停用流程。目前支援套件組合 Skills、Claude command-skills、Claude `settings.json` 預設值、Claude `.lsp.json` / manifest 宣告的 `lspServers` 預設值、Cursor command-skills，以及相容的 Codex hook 目錄；其他偵測到的套件組合功能會顯示在診斷/資訊中，但尚未接入 runtime 執行。
+相容套件會安裝到一般 plugin 根目錄，並參與相同的 list/info/enable/disable 流程。目前支援套件 skills、Claude command-skills、Claude `settings.json` 預設值、Claude `.lsp.json` / manifest 宣告的 `lspServers` 預設值、Cursor command-skills，以及相容的 Codex hook 目錄；其他偵測到的套件能力會顯示在 diagnostics/info 中，但尚未接入執行階段執行。
 </Note>
 
 ### 列出
@@ -234,56 +234,56 @@ openclaw plugins search <query> --json
   只顯示已啟用的 plugins。
 </ParamField>
 <ParamField path="--verbose" type="boolean">
-  從表格檢視切換為每個 Plugin 的詳細行，包含來源/起源/版本/啟用中繼資料。
+  從表格檢視切換為每個 plugin 的詳細行，包含 source/origin/version/activation metadata。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  機器可讀的清單，加上 registry 診斷與套件相依安裝狀態。
+  機器可讀取的 inventory，加上 registry diagnostics 與 package dependency install state。
 </ParamField>
 
 <Note>
-`plugins list` 會先讀取持久化的本機 Plugin registry；當 registry 缺失或無效時，會使用僅由 manifest 推導出的 fallback。它可用來檢查某個 Plugin 是否已安裝、已啟用，並且對冷啟動規劃可見，但它不是對已在執行中的 Gateway 程序進行即時 runtime 探測。變更 Plugin 程式碼、啟用狀態、hook 政策或 `plugins.load.paths` 之後，請重新啟動服務該通道的 Gateway，再期待新的 `register(api)` 程式碼或 hooks 執行。對於遠端/容器部署，請確認你重新啟動的是實際的 `openclaw gateway run` 子程序，而不只是包裝程序。
+`plugins list` 會先讀取已持久化的本機 plugin registry；當 registry 遺失或無效時，會使用僅由 manifest 推導出的備援。它可用來檢查 plugin 是否已安裝、已啟用，且對冷啟動規劃可見，但它不是針對已在執行中的 Gateway 程序的即時執行階段探測。變更 plugin 程式碼、啟用狀態、hook policy 或 `plugins.load.paths` 後，請重新啟動服務該 channel 的 Gateway，再預期新的 `register(api)` 程式碼或 hooks 會執行。對於遠端/容器部署，請確認你正在重新啟動實際的 `openclaw gateway run` 子程序，而不只是 wrapper 程序。
 
-`plugins list --json` 會包含每個 Plugin 來自 `package.json`
-`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 會檢查這些套件
-名稱是否存在於該 Plugin 一般 Node `node_modules` 查找路徑上；它
-不會匯入 Plugin runtime 程式碼、執行套件管理器，或修復缺失的
-相依套件。
+`plugins list --json` 會包含每個 plugin 來自 `package.json`
+`dependencies` 與 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 會檢查這些 package
+名稱是否存在於 plugin 一般 Node `node_modules` 查找路徑上；它
+不會匯入 plugin 執行階段程式碼、執行 package manager，或修復遺失的
+dependencies。
 </Note>
 
-`plugins search` 是遠端 ClawHub 目錄查詢。它不會檢查本機
-狀態、變更 config、安裝套件，或載入 Plugin runtime 程式碼。搜尋
-結果包含 ClawHub 套件名稱、family、channel、版本、摘要，以及
+`plugins search` 是遠端 ClawHub catalog 查詢。它不會檢查本機
+狀態、變更 config、安裝 packages，或載入 plugin 執行階段程式碼。搜尋
+結果包含 ClawHub package 名稱、family、channel、version、summary，以及
 安裝提示，例如 `openclaw plugins install clawhub:<package>`。
 
-若要在封裝的 Docker 映像中處理內建 Plugin，請將 Plugin
+若要在封裝好的 Docker image 內處理內建 plugin，請將 plugin
 來源目錄 bind-mount 到相符的封裝來源路徑上，例如
-`/app/extensions/synology-chat`。OpenClaw 會先於
-`/app/dist/extensions/synology-chat` 發現該掛載的來源
-覆寫；單純複製的來源目錄會保持無作用，因此一般封裝安裝仍會使用已編譯的 dist。
+`/app/extensions/synology-chat`。OpenClaw 會先探索該掛載的來源
+overlay，再探索 `/app/dist/extensions/synology-chat`；單純複製的來源
+目錄仍會保持無作用，因此一般封裝安裝仍使用已編譯的 dist。
 
-若要偵錯 runtime hook：
+針對執行階段 hook 偵錯：
 
-- `openclaw plugins inspect <id> --runtime --json` 會顯示來自模組載入檢查流程的已註冊 hooks 與診斷。Runtime 檢查永遠不會安裝相依套件；請使用 `openclaw doctor --fix` 清理舊版相依狀態，或安裝缺失且已設定的可下載 plugins。
-- `openclaw gateway status --deep --require-rpc` 會確認可連線的 Gateway、服務/程序提示、config 路徑，以及 RPC 健康狀態。
-- 非內建的對話 hooks（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
+- `openclaw plugins inspect <id> --runtime --json` 會顯示來自 module-loaded inspection pass 的已註冊 hooks 與 diagnostics。Runtime inspection 永遠不會安裝 dependencies；使用 `openclaw doctor --fix` 清理舊版 dependency state，或恢復 config 參照但遺失的可下載 plugins。
+- `openclaw gateway status --deep --require-rpc` 會確認可連線的 Gateway、service/process 提示、config 路徑，以及 RPC 健康狀態。
+- 非內建 conversation hooks (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) 需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
 
-使用 `--link` 可避免複製本機目錄（會加入 `plugins.load.paths`）：
+使用 `--link` 以避免複製本機目錄（會加入 `plugins.load.paths`）：
 
 ```bash
 openclaw plugins install -l ./my-plugin
 ```
 
 <Note>
-`--force` 不支援與 `--link` 搭配使用，因為連結式安裝會重用來源路徑，而不是覆寫受管理的安裝目標。
+`--force` 不支援與 `--link` 搭配使用，因為 linked installs 會重用來源路徑，而不是覆寫受管理的安裝目標。
 
-在 npm 安裝上使用 `--pin`，可將解析出的精確 spec（`name@version`）儲存在受管理的 Plugin 索引中，同時保留預設的未釘選行為。
+在 npm installs 上使用 `--pin`，可在受管理的 plugin index 中儲存已解析的精確 spec (`name@version`)，同時保持預設行為為未釘選。
 </Note>
 
-### Plugin 索引
+### Plugin index
 
-Plugin 安裝中繼資料是由機器管理的狀態，不是使用者 config。安裝與更新會將它寫入作用中 OpenClaw 狀態目錄底下的 `plugins/installs.json`。其頂層 `installRecords` map 是安裝中繼資料的持久來源，其中包含毀損或缺失 Plugin manifest 的記錄。`plugins` 陣列是由 manifest 推導出的冷 registry 快取。該檔案包含請勿編輯警告，並由 `openclaw plugins update`、解除安裝、診斷，以及冷 Plugin registry 使用。
+Plugin install metadata 是機器管理的狀態，不是使用者 config。安裝與更新會把它寫入作用中 OpenClaw state 目錄下的 `plugins/installs.json`。其頂層 `installRecords` map 是 install metadata 的持久來源，包括損壞或遺失的 plugin manifests 記錄。`plugins` array 是由 manifest 推導出的 cold registry cache。此檔案包含請勿編輯警告，並由 `openclaw plugins update`、uninstall、diagnostics，以及 cold plugin registry 使用。
 
-當 OpenClaw 在 config 中看到已出貨的舊版 `plugins.installs` 記錄時，會將它們移到 Plugin 索引並移除該 config key；如果任一寫入失敗，config 記錄會被保留，確保安裝中繼資料不會遺失。
+當 OpenClaw 在 config 中看到已出貨的舊版 `plugins.installs` 記錄時，會將它們移到 plugin index 並移除 config key；如果任一寫入失敗，config 記錄會保留，避免 install metadata 遺失。
 
 ### 解除安裝
 
@@ -293,10 +293,10 @@ openclaw plugins uninstall <id> --dry-run
 openclaw plugins uninstall <id> --keep-files
 ```
 
-`uninstall` 會從 `plugins.entries`、持久化 Plugin 索引、Plugin 允許/拒絕清單項目，以及適用時已連結的 `plugins.load.paths` 項目中移除 Plugin 記錄。除非設定 `--keep-files`，解除安裝也會在追蹤的受管理安裝目錄位於 OpenClaw 的 Plugin extensions 根目錄內時移除該目錄。對於 Active Memory plugins，memory slot 會重設為 `memory-core`。
+`uninstall` 會從 `plugins.entries`、已持久化的 plugin index、plugin allow/deny list 項目，以及適用時的 linked `plugins.load.paths` 項目中移除 plugin 記錄。除非設定 `--keep-files`，否則 uninstall 也會移除位於 OpenClaw plugin extensions root 內的受追蹤管理安裝目錄。對於 active memory plugins，memory slot 會重設為 `memory-core`。
 
 <Note>
-`--keep-config` 支援作為 `--keep-files` 的已棄用別名。
+`--keep-config` 支援作為 `--keep-files` 的 deprecated alias。
 </Note>
 
 ### 更新
@@ -309,29 +309,29 @@ openclaw plugins update @openclaw/voice-call
 openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
 ```
 
-更新會套用到受管理 Plugin 索引中已追蹤的 Plugin 安裝，以及 `hooks.internal.installs` 中已追蹤的 hook-pack 安裝。
+更新會套用到 managed plugin index 中受追蹤的 plugin installs，以及 `hooks.internal.installs` 中受追蹤的 hook-pack installs。
 
 <AccordionGroup>
   <Accordion title="Resolving plugin id vs npm spec">
-    當你傳入 Plugin id 時，OpenClaw 會重用該 Plugin 記錄的安裝 spec。這表示先前儲存的 dist-tags（例如 `@beta`）與精確釘選版本，會在之後的 `update <id>` 執行中繼續使用。
+    當你傳入 plugin id 時，OpenClaw 會重用該 plugin 記錄的 install spec。這表示先前儲存的 dist-tags，例如 `@beta`，以及精確釘選版本，會在後續 `update <id>` 執行時繼續使用。
 
-    對於 npm 安裝，你也可以傳入含有 dist-tag 或精確版本的明確 npm 套件 spec。OpenClaw 會將該套件名稱解析回已追蹤的 Plugin 記錄、更新該已安裝 Plugin，並記錄新的 npm spec，供未來以 id 為基礎的更新使用。
+    對於 npm installs，你也可以傳入帶有 dist-tag 或精確版本的明確 npm package spec。OpenClaw 會將該 package 名稱解析回受追蹤的 plugin 記錄，更新該已安裝的 plugin，並記錄新的 npm spec 供未來以 id 為基礎的更新使用。
 
-    傳入不含版本或 tag 的 npm 套件名稱，也會解析回已追蹤的 Plugin 記錄。當某個 Plugin 先前已釘選到精確版本，而你想將它移回 registry 的預設發行線時，請使用這個方式。
+    傳入不含版本或標籤的 npm package 名稱，也會解析回受追蹤的 plugin 記錄。當 plugin 已釘選到精確版本，而你想將它移回 registry 預設發行線時，請使用此方式。
 
   </Accordion>
   <Accordion title="Beta channel updates">
-    `openclaw plugins update` 會重用已追蹤的 Plugin spec，除非你傳入新的 spec。`openclaw update` 另外知道作用中的 OpenClaw 更新 channel：在 beta channel 上，預設線 npm 與 ClawHub Plugin 記錄會先嘗試 `@beta`，如果沒有 Plugin beta 發行版，才 fallback 到記錄的預設/latest spec。精確版本與明確 tags 會持續釘選到該 selector。
+    `openclaw plugins update` 會重用受追蹤的 plugin spec，除非你傳入新的 spec。`openclaw update` 另外知道作用中的 OpenClaw update channel：在 beta channel 上，default-line npm 與 ClawHub plugin 記錄會先嘗試 `@beta`，若沒有 plugin beta release，則退回已記錄的 default/latest spec。精確版本與明確標籤會保持釘選到該 selector。
 
   </Accordion>
   <Accordion title="Version checks and integrity drift">
-    在即時 npm 更新之前，OpenClaw 會根據 npm registry 中繼資料檢查已安裝套件版本。如果已安裝版本與記錄的成品身分已符合解析出的目標，更新會被略過，不會下載、重新安裝或重寫 `openclaw.json`。
+    在即時 npm update 前，OpenClaw 會根據 npm registry metadata 檢查已安裝 package 版本。如果已安裝版本與已記錄 artifact identity 已符合解析後目標，更新會略過，不會下載、重新安裝或重寫 `openclaw.json`。
 
-    當已儲存 integrity hash，且抓取到的成品 hash 發生變化時，OpenClaw 會將其視為 npm 成品漂移。互動式 `openclaw plugins update` 命令會列印預期與實際 hash，並在繼續前要求確認。非互動式更新輔助程式會 fail closed，除非呼叫端提供明確的繼續政策。
+    當存在已儲存的 integrity hash 且擷取到的 artifact hash 改變時，OpenClaw 會將其視為 npm artifact drift。互動式 `openclaw plugins update` command 會列印預期與實際 hash，並在繼續前要求確認。非互動式 update helpers 會 fail closed，除非呼叫端提供明確的 continuation policy。
 
   </Accordion>
   <Accordion title="--dangerously-force-unsafe-install on update">
-    `--dangerously-force-unsafe-install` 也可在 `plugins update` 上使用，作為 Plugin 更新期間內建 dangerous-code 掃描誤判的 break-glass 覆寫。它仍不會繞過 Plugin `before_install` 政策封鎖或掃描失敗封鎖，而且只適用於 Plugin 更新，不適用於 hook-pack 更新。
+    `--dangerously-force-unsafe-install` 也可用於 `plugins update`，作為 plugin updates 期間內建 dangerous-code scan false positives 的 break-glass override。它仍不會繞過 plugin `before_install` policy blocks 或 scan-failure blocking，且只適用於 plugin updates，不適用於 hook-pack updates。
   </Accordion>
 </AccordionGroup>
 
@@ -343,21 +343,21 @@ openclaw plugins inspect <id> --runtime
 openclaw plugins inspect <id> --json
 ```
 
-Inspect 預設不會匯入 Plugin runtime，會顯示身分、載入狀態、來源、manifest 功能、政策旗標、診斷、安裝中繼資料、套件組合功能，以及任何偵測到的 MCP 或 LSP server 支援。加入 `--runtime` 可載入 Plugin 模組，並包含已註冊 hooks、tools、commands、services、gateway methods，以及 HTTP routes。Runtime 檢查會直接回報缺失的 Plugin 相依套件；安裝與修復仍留在 `openclaw plugins install`、`openclaw plugins update`，以及 `openclaw doctor --fix` 中進行。
+Inspect 預設不會匯入 plugin 執行階段，並會顯示 identity、load status、source、manifest capabilities、policy flags、diagnostics、install metadata、bundle capabilities，以及任何偵測到的 MCP 或 LSP server 支援。加入 `--runtime` 可載入 plugin module，並包含已註冊的 hooks、tools、commands、services、gateway methods 與 HTTP routes。Runtime inspection 會直接回報遺失的 plugin dependencies；安裝與修復仍位於 `openclaw plugins install`、`openclaw plugins update` 與 `openclaw doctor --fix`。
 
-Plugin 擁有的 CLI commands 會安裝為根層級 `openclaw` command groups。當 `inspect --runtime` 在 `cliCommands` 下顯示某個 command 後，請以 `openclaw <command> ...` 執行它；例如，註冊 `demo-git` 的 Plugin 可用 `openclaw demo-git ping` 驗證。
+Plugin 擁有的 CLI commands 會安裝為根層級 `openclaw` command groups。在 `inspect --runtime` 顯示 `cliCommands` 下的 command 後，請以 `openclaw <command> ...` 執行它；例如，註冊 `demo-git` 的 plugin 可用 `openclaw demo-git ping` 驗證。
 
-每個 Plugin 會依照它在 runtime 實際註冊的內容分類：
+每個 plugin 會依其在執行階段實際註冊的內容分類：
 
-- **plain-capability** — 一種 capability 類型（例如僅 provider 的 Plugin）
-- **hybrid-capability** — 多種 capability 類型（例如文字 + 語音 + 圖像）
+- **plain-capability** — 一種 capability 類型（例如僅 provider 的 plugin）
+- **hybrid-capability** — 多種 capability 類型（例如 text + speech + images）
 - **hook-only** — 只有 hooks，沒有 capabilities 或 surfaces
-- **non-capability** — tools/commands/services，但沒有 capabilities
+- **non-capability** — 有 tools/commands/services，但沒有 capabilities
 
-如需 capability model 的更多資訊，請參閱 [Plugin shapes](/zh-TW/plugins/architecture#plugin-shapes)。
+請參閱 [Plugin 形態](/zh-TW/plugins/architecture#plugin-shapes) 以了解更多 capability model。
 
 <Note>
-`--json` 旗標會輸出適合 scripting 與 auditing 的機器可讀報告。`inspect --all` 會呈現全體範圍的表格，包含 shape、capability kinds、compatibility notices、bundle capabilities，以及 hook summary 欄位。`info` 是 `inspect` 的別名。
+`--json` flag 會輸出適合 scripting 與 auditing 的機器可讀報告。`inspect --all` 會呈現整體 fleet-wide 表格，包含 shape、capability kinds、compatibility notices、bundle capabilities 與 hook summary 欄位。`info` 是 `inspect` 的 alias。
 </Note>
 
 ### Doctor
@@ -366,11 +366,11 @@ Plugin 擁有的 CLI commands 會安裝為根層級 `openclaw` command groups。
 openclaw plugins doctor
 ```
 
-`doctor` 會回報 Plugin 載入錯誤、manifest/discovery 診斷，以及相容性 notices。當一切正常時，它會印出 `No plugin issues detected.`
+`doctor` 會回報 plugin load errors、manifest/discovery diagnostics 與 compatibility notices。當一切乾淨時，它會列印 `No plugin issues detected.`
 
-如果已設定的 Plugin 存在於磁碟上，但被 loader 的路徑安全檢查封鎖，config 驗證會保留該 Plugin 項目，並將它回報為 `present but blocked`。請修正前面的 blocked-plugin 診斷，例如路徑 ownership 或 world-writable permissions，而不是移除 `plugins.entries.<id>` 或 `plugins.allow` config。
+如果已設定的 plugin 存在於磁碟上，但被 loader 的 path-safety checks 阻擋，config validation 會保留 plugin 項目，並將其回報為 `present but blocked`。請修正前面的 blocked-plugin diagnostic，例如 path ownership 或 world-writable permissions，而不是移除 `plugins.entries.<id>` 或 `plugins.allow` config。
 
-對於缺少 `register`/`activate` exports 這類 module-shape 失敗，請使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新執行，以在診斷輸出中包含精簡的 export-shape 摘要。
+對於 module-shape failures，例如遺失 `register`/`activate` exports，請使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新執行，以在 diagnostic output 中包含精簡的 export-shape summary。
 
 ### Registry
 
@@ -380,14 +380,14 @@ openclaw plugins registry --refresh
 openclaw plugins registry --json
 ```
 
-本機 Plugin registry 是 OpenClaw 為已安裝 Plugin 身分、啟用狀態、來源中繼資料，以及貢獻 ownership 所持久化的冷讀取模型。一般啟動、provider owner 查找、channel setup 分類，以及 Plugin 清單都可以在不匯入 Plugin runtime 模組的情況下讀取它。
+本機 plugin registry 是 OpenClaw 對已安裝 plugin identity、enablement、source metadata 與 contribution ownership 的已持久化 cold read model。一般 startup、provider owner lookup、channel setup classification 與 plugin inventory 都可以讀取它，而不必匯入 plugin runtime modules。
 
-使用 `plugins registry` 檢查持久化 registry 是否存在、為最新或已過期。使用 `--refresh` 從持久化 Plugin 索引、設定政策，以及資訊清單/套件中繼資料重建它。這是修復路徑，不是執行階段啟用路徑。
+使用 `plugins registry` 檢查持久化登錄檔是否存在、是否為目前版本，或是否已過期。使用 `--refresh` 從持久化的 Plugin 索引、設定政策，以及資訊清單/套件中繼資料重新建置它。這是修復路徑，不是執行階段啟用路徑。
 
-`openclaw doctor --fix` 也會修復與 registry 相鄰的受管理 npm 漂移：如果受管理 Plugin npm 根目錄下有孤立或復原的 `@openclaw/*` 套件遮蔽了隨附 Plugin，doctor 會移除該過期套件並重建 registry，讓啟動流程能依據隨附資訊清單進行驗證。
+`openclaw doctor --fix` 也會修復登錄檔相鄰的受管理 npm 偏移：如果受管理的 Plugin npm 根目錄下有孤立或已復原的 `@openclaw/*` 套件遮蔽了內建 Plugin，doctor 會移除該過期套件並重新建置登錄檔，讓啟動時能根據內建資訊清單進行驗證。
 
 <Warning>
-`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已棄用的緊急相容性開關，用於 registry 讀取失敗。請優先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；此 env 後援僅供遷移推出期間的緊急啟動復原使用。
+`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已棄用的破窗相容性開關，用於登錄檔讀取失敗。請優先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；env 後援僅用於遷移推出期間的緊急啟動復原。
 </Warning>
 
 ### 市集
@@ -397,7 +397,7 @@ openclaw plugins marketplace list <source>
 openclaw plugins marketplace list <source> --json
 ```
 
-市集清單接受本機市集路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。`--json` 會印出解析後的來源標籤，以及剖析後的市集資訊清單與 Plugin 項目。
+市集列表接受本機市集路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub 儲存庫 URL，或 git URL。`--json` 會輸出已解析的來源標籤，以及已剖析的市集資訊清單與 Plugin 項目。
 
 ## 相關
 

docs/zh-TW/cli/sessions.md

@@ -1,13 +1,13 @@
 ---
 read_when:
-    - 你想列出已儲存的工作階段並查看近期活動
-summary: '`openclaw sessions` 的 CLI 參考（列出已儲存的工作階段 + 用法）'
+    - 您想列出已儲存的工作階段並查看近期活動
+summary: CLI 參考：`openclaw sessions`（列出已儲存的工作階段 + 使用方式）
 title: 工作階段
 x-i18n:
-    generated_at: "2026-05-04T07:02:46Z"
+    generated_at: "2026-05-05T01:44:16Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
+    source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7
     source_path: cli/sessions.md
     workflow: 16
 ---
@@ -16,37 +16,55 @@ x-i18n:
 
 列出已儲存的對話工作階段。
 
-工作階段清單不是通道/提供者的存活檢查。它們顯示來自工作階段儲存區的持久化對話列。安靜的 Discord、Slack、Telegram 或其他通道可以成功重新連線，但在處理訊息之前不會建立新的工作階段列。當你需要即時通道連線狀態時，請使用 `openclaw channels status --probe`、`openclaw status --deep` 或 `openclaw health --verbose`。
+工作階段清單不是通道/供應者存活狀態檢查。它們顯示來自工作階段儲存區的持久化
+對話資料列。安靜的 Discord、Slack、Telegram 或
+其他通道可以成功重新連線，而不會建立新的工作階段資料列，
+直到處理訊息為止。當你需要即時
+通道連線能力時，請使用 `openclaw channels status --probe`、
+`openclaw status --deep` 或 `openclaw health --verbose`。
 
-Gateway `sessions.list` 回應預設有界限，因此大型長期儲存區無法壟斷 Gateway 事件迴圈。當需要不同的結果視窗時，RPC 用戶端請傳入明確的正數 `limit`；當呼叫端需要顯示還有更多列存在時，回應會包含 `totalCount`、`limitApplied` 和 `hasMore`。
+`openclaw sessions` 和 Gateway `sessions.list` 回應預設都有界限，
+因此大型長期儲存區無法獨佔 CLI 程序或 Gateway
+事件迴圈。CLI 預設會回傳最新的 100 個工作階段；傳入
+`--limit <n>` 以取得較小/較大的視窗，或在你刻意
+需要完整儲存區時使用 `--limit all`。JSON 回應包含 `totalCount`、`limitApplied` 和
+`hasMore`，供呼叫端需要顯示還有更多資料列存在時使用。
 
 ```bash
 openclaw sessions
 openclaw sessions --agent work
 openclaw sessions --all-agents
 openclaw sessions --active 120
+openclaw sessions --limit 25
 openclaw sessions --verbose
 openclaw sessions --json
 ```
 
 範圍選擇：
 
-- 預設：已設定的預設代理程式儲存區
+- 預設：已設定的預設代理儲存區
 - `--verbose`：詳細記錄
-- `--agent <id>`：一個已設定的代理程式儲存區
-- `--all-agents`：彙總所有已設定的代理程式儲存區
+- `--agent <id>`：一個已設定的代理儲存區
+- `--all-agents`：彙總所有已設定的代理儲存區
 - `--store <path>`：明確的儲存區路徑（不能與 `--agent` 或 `--all-agents` 合併使用）
+- `--limit <n|all>`：要輸出的最大資料列數（預設 `100`；`all` 會恢復完整輸出）
 
-為已儲存的工作階段匯出軌跡套件：
+匯出已儲存工作階段的軌跡套件：
 
 ```bash
 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
 ```
 
-這是擁有者核准 exec 要求後，`/export-trajectory` 斜線命令使用的命令路徑。輸出目錄一律解析到所選工作區下的 `.openclaw/trajectory-exports/` 內。
+這是 `/export-trajectory` 斜線指令在
+擁有者核准執行要求後使用的指令路徑。輸出目錄一律解析到
+所選工作區底下的 `.openclaw/trajectory-exports/` 內。
 
-`openclaw sessions --all-agents` 會讀取已設定的代理程式儲存區。Gateway 和 ACP 工作階段探索範圍更廣：它們也會包含在預設 `agents/` 根目錄或樣板化 `session.store` 根目錄下找到的純磁碟儲存區。這些探索到的儲存區必須解析為代理程式根目錄內的一般 `sessions.json` 檔案；符號連結和根目錄外路徑會被略過。
+`openclaw sessions --all-agents` 會讀取已設定的代理儲存區。Gateway 和 ACP
+工作階段探索範圍更廣：它們也包含在
+預設 `agents/` 根目錄或範本化 `session.store` 根目錄底下找到的僅磁碟儲存區。那些
+探索到的儲存區必須解析為代理根目錄內的一般 `sessions.json` 檔案；
+符號連結和根目錄外路徑會被略過。
 
 JSON 範例：
 
@@ -61,6 +79,9 @@ JSON 範例：
   ],
   "allAgents": true,
   "count": 2,
+  "totalCount": 2,
+  "limitApplied": 100,
+  "hasMore": false,
   "activeMinutes": null,
   "sessions": [
     { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
@@ -84,19 +105,21 @@ openclaw sessions cleanup --json
 
 `openclaw sessions cleanup` 會使用設定中的 `session.maintenance` 設定：
 
-- 範圍注意事項：`openclaw sessions cleanup` 會維護工作階段儲存區、逐字稿和軌跡附屬檔案。它不會修剪 cron 執行記錄（`cron/runs/<jobId>.jsonl`），這些記錄由 [Cron 設定](/zh-TW/automation/cron-jobs#configuration)中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，並在 [Cron 維護](/zh-TW/automation/cron-jobs#maintenance)中說明。
+- 範圍注意事項：`openclaw sessions cleanup` 會維護工作階段儲存區、轉錄稿和軌跡附屬檔。它不會修剪 Cron 執行記錄（`cron/runs/<jobId>.jsonl`），這些記錄由 [Cron 設定](/zh-TW/automation/cron-jobs#configuration)中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，並在 [Cron 維護](/zh-TW/automation/cron-jobs#maintenance)中說明。
 
-- `--dry-run`：預覽在不寫入的情況下會修剪/限制多少項目。
-  - 在文字模式中，dry-run 會列印每個工作階段的動作表（`Action`、`Key`、`Age`、`Model`、`Flags`），讓你可以看到哪些會保留、哪些會移除。
+- `--dry-run`：預覽將修剪/限制多少項目，而不寫入。
+  - 在文字模式中，dry-run 會列印每個工作階段的動作表（`Action`、`Key`、`Age`、`Model`、`Flags`），讓你可以查看哪些會保留、哪些會移除。
 - `--enforce`：即使 `session.maintenance.mode` 為 `warn`，也套用維護。
-- `--fix-missing`：移除逐字稿檔案遺失的項目，即使它們通常尚未因年齡/數量而淘汰。
-- `--active-key <key>`：保護特定作用中金鑰，避免因磁碟預算而遭到淘汰。持久的外部對話指標，例如群組工作階段和執行緒範圍聊天工作階段，也會由年齡/數量/磁碟預算維護保留。
-- `--agent <id>`：為一個已設定的代理程式儲存區執行清理。
-- `--all-agents`：為所有已設定的代理程式儲存區執行清理。
+- `--fix-missing`：移除其轉錄稿檔案遺失的項目，即使它們通常尚未因存留時間/數量而淘汰。
+- `--active-key <key>`：保護特定作用中金鑰不受磁碟預算逐出。耐久的外部對話指標，例如群組工作階段和執行緒範圍的聊天工作階段，也會在依存留時間/數量/磁碟預算進行維護時保留。
+- `--agent <id>`：針對一個已設定的代理儲存區執行清理。
+- `--all-agents`：針對所有已設定的代理儲存區執行清理。
 - `--store <path>`：針對特定 `sessions.json` 檔案執行。
-- `--json`：列印 JSON 摘要。使用 `--all-agents` 時，輸出會包含每個儲存區的一份摘要。
+- `--json`：列印 JSON 摘要。搭配 `--all-agents` 時，輸出會包含每個儲存區的一份摘要。
 
-當 Gateway 可連線時，針對已設定代理程式儲存區的非 dry-run 清理會透過 Gateway 傳送，因此會與執行階段流量共用相同的工作階段儲存區寫入器。使用 `--store <path>` 可對儲存區檔案進行明確的離線修復。
+當 Gateway 可連線時，已設定代理儲存區的非 dry-run 清理會
+透過 Gateway 傳送，因此它會與執行階段流量共用相同的工作階段儲存區寫入器。
+使用 `--store <path>` 可明確離線修復儲存區檔案。
 
 `openclaw sessions cleanup --all-agents --dry-run --json`：
 

docs/zh-TW/cli/update.md

@@ -1,25 +1,25 @@
 ---
 read_when:
-    - 你想要安全地更新簽出的原始碼
+    - 您想安全地更新原始碼簽出目錄
     - 你正在偵錯 `openclaw update` 的輸出或選項
-    - 您需要了解 `--update` 的簡寫行為
-summary: '`openclaw update` 的 CLI 參考（較安全的原始碼更新 + Gateway 自動重新啟動）'
+    - 你需要了解 `--update` 的簡寫行為
+summary: '`openclaw update` 的 CLI 參考（相對安全的原始碼更新 + Gateway 自動重新啟動）'
 title: 更新
 x-i18n:
-    generated_at: "2026-05-03T21:29:45Z"
+    generated_at: "2026-05-05T01:45:07Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8
+    source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f
     source_path: cli/update.md
     workflow: 16
 ---
 
 # `openclaw update`
 
-安全地更新 OpenClaw，並在 stable/beta/dev 頻道之間切換。
+安全地更新 OpenClaw，並在 stable/beta/dev 通道之間切換。
 
 如果你是透過 **npm/pnpm/bun** 安裝（全域安裝，沒有 git 中繼資料），
-更新會透過 [Updating](/zh-TW/install/updating) 中的套件管理器流程進行。
+更新會透過 [更新](/zh-TW/install/updating) 中的套件管理器流程進行。
 
 ## 用法
 
@@ -40,31 +40,31 @@ openclaw --update
 
 ## 選項
 
-- `--no-restart`：成功更新後略過重新啟動 Gateway 服務。若套件管理器更新會重新啟動 Gateway，則會在命令成功前驗證重新啟動的服務回報預期的更新版本。
-- `--channel <stable|beta|dev>`：設定更新頻道（git + npm；會保存至設定）。
-- `--tag <dist-tag|version|spec>`：僅針對本次更新覆寫套件目標。對於套件安裝，`main` 會對應到 `github:openclaw/openclaw#main`。
-- `--dry-run`：預覽規劃的更新動作（頻道/標籤/目標/重新啟動流程），不寫入設定、不安裝、不同步 Plugin，也不重新啟動。
-- `--json`：輸出機器可讀的 `UpdateRunResult` JSON，包括
-  在更新後 Plugin 同步期間偵測到 npm Plugin 成品漂移時的
+- `--no-restart`：成功更新後略過重新啟動 Gateway 服務。會重新啟動 Gateway 的套件管理器更新，會先驗證重新啟動的服務回報預期的更新版本，命令才會成功。
+- `--channel <stable|beta|dev>`：設定更新通道（git + npm；會持久化到設定）。
+- `--tag <dist-tag|version|spec>`：僅針對這次更新覆寫套件目標。對於套件安裝，`main` 會對應到 `github:openclaw/openclaw#main`。
+- `--dry-run`：預覽預計的更新動作（通道/標籤/目標/重新啟動流程），不寫入設定、不安裝、不同步 plugins，也不重新啟動。
+- `--json`：列印機器可讀的 `UpdateRunResult` JSON，包括
+  在更新後 plugin 同步期間偵測到 npm plugin 成品漂移時的
   `postUpdate.plugins.integrityDrifts`。
-- `--timeout <seconds>`：每個步驟的逾時時間（預設為 1800s）。
-- `--yes`：略過確認提示（例如降版確認）。
+- `--timeout <seconds>`：每個步驟的逾時時間（預設為 1800 秒）。
+- `--yes`：略過確認提示（例如降級確認）。
 
 `openclaw update` 沒有 `--verbose` 旗標。使用 `--dry-run` 預覽
-規劃的頻道/標籤/安裝/重新啟動動作，使用 `--json` 取得機器可讀的
-結果；若你只需要頻道與可用性詳細資訊，請使用 `openclaw update status --json`。
-如果你正在偵錯更新前後的 Gateway 日誌，
-主控台詳細程度與檔案日誌層級是分開的：Gateway `--verbose` 會影響
-終端機/WebSocket 輸出，而檔案日誌需要在設定中使用 `logging.level: "debug"` 或
-`"trace"`。請參閱 [Gateway 日誌](/zh-TW/gateway/logging)。
+預計的通道/標籤/安裝/重新啟動動作，使用 `--json` 取得機器可讀的
+結果；如果你只需要通道與可用性詳細資料，請使用
+`openclaw update status --json`。如果你正在除錯更新前後的 Gateway 記錄，
+主控台詳細程度與檔案記錄層級是分開的：Gateway `--verbose` 會影響
+終端機/WebSocket 輸出，而檔案記錄需要在設定中使用 `logging.level: "debug"` 或
+`"trace"`。請參閱 [Gateway 記錄](/zh-TW/gateway/logging)。
 
 <Warning>
-降版需要確認，因為較舊版本可能會破壞設定。
+降級需要確認，因為較舊版本可能會破壞設定。
 </Warning>
 
 ## `update status`
 
-顯示作用中的更新頻道 + git 標籤/分支/SHA（適用於來源 checkout），以及更新可用性。
+顯示目前作用中的更新通道 + git 標籤/分支/SHA（對原始碼 checkout 而言），以及更新可用性。
 
 ```bash
 openclaw update status
@@ -74,14 +74,14 @@ openclaw update status --timeout 10
 
 選項：
 
-- `--json`：輸出機器可讀的狀態 JSON。
-- `--timeout <seconds>`：檢查逾時時間（預設為 3s）。
+- `--json`：列印機器可讀的狀態 JSON。
+- `--timeout <seconds>`：檢查的逾時時間（預設為 3 秒）。
 
 ## `update wizard`
 
-互動式流程，用於選擇更新頻道，並確認更新後是否重新啟動 Gateway
+互動式流程，用於選擇更新通道，並確認更新後是否要重新啟動 Gateway
 （預設會重新啟動）。如果你選擇 `dev` 但沒有 git checkout，它會
-提出建立一個 checkout。
+提議建立一個。
 
 選項：
 
@@ -89,54 +89,54 @@ openclaw update status --timeout 10
 
 ## 它會做什麼
 
-當你明確切換頻道（`--channel ...`）時，OpenClaw 也會保持
-安裝方式一致：
+當你明確切換通道（`--channel ...`）時，OpenClaw 也會讓
+安裝方式保持一致：
 
 - `dev` → 確保有 git checkout（預設：`~/openclaw`，可用 `OPENCLAW_GIT_DIR` 覆寫），
   更新它，並從該 checkout 安裝全域 CLI。
 - `stable` → 使用 `latest` 從 npm 安裝。
-- `beta` → 優先使用 npm dist-tag `beta`，但當 beta 缺失或比目前穩定版更舊時，
-  會退回使用 `latest`。
+- `beta` → 優先使用 npm dist-tag `beta`，但當 beta
+  缺失或比目前 stable 發行版本更舊時，會回退到 `latest`。
 
 Gateway 核心自動更新器（透過設定啟用時）會在即時 Gateway 請求處理常式之外
 啟動 CLI 更新路徑。控制平面 `update.run` 套件管理器更新會在套件替換後
-強制執行非延後、無冷卻時間的更新重新啟動，
-因為舊的 Gateway 程序可能仍有指向新套件已移除檔案的記憶體內片段。
+強制進行非延後、無冷卻時間的更新重新啟動，
+因為舊的 Gateway 程序可能仍有記憶體中的區塊指向
+新套件已移除的檔案。
 
-對於套件管理器安裝，`openclaw update` 會在叫用套件管理器前解析目標套件
-版本。npm 全域安裝會使用暫存安裝：OpenClaw 會將新套件安裝到暫時的 npm 前綴，
-在該處驗證封裝的 `dist` 清單，然後將該乾淨的套件樹替換到
-真正的全域前綴。如果驗證失敗，更新後 doctor、Plugin 同步與
-重新啟動工作不會從可疑的套件樹執行。即使已安裝版本
-已符合目標，該命令仍會重新整理全域套件安裝，
-然後執行 Plugin 同步、核心命令補全重新整理，以及重新啟動工作。這會
-讓封裝的 sidecar 與頻道擁有的 Plugin 記錄與
-已安裝的 OpenClaw 建置保持一致，同時將完整的 Plugin 命令補全重建留給
+對於套件管理器安裝，`openclaw update` 會在呼叫套件管理器之前解析目標套件
+版本。npm 全域安裝會使用分段安裝：OpenClaw 會把新套件安裝到暫存 npm 前綴，
+在其中驗證已封裝的 `dist` 清單，然後把該乾淨的套件樹替換到
+真正的全域前綴。如果驗證失敗，更新後 doctor、plugin 同步與
+重新啟動工作不會從可疑的樹執行。即使已安裝版本已經符合目標，
+此命令也會重新整理全域套件安裝，
+然後執行 plugin 同步、核心命令補全重新整理與重新啟動工作。這會讓
+已封裝的 sidecar 與通道擁有的 plugin 記錄和已安裝的 OpenClaw 建置保持一致，
+同時把完整的 plugin 命令補全重建留給
 明確的 `openclaw completion --write-state` 執行。
 
-當本機受管理的 Gateway 服務已安裝且啟用重新啟動時，
+當已安裝本機受管理的 Gateway 服務且已啟用重新啟動時，
 套件管理器更新會先停止執行中的服務，再替換套件
-樹，接著從更新後的安裝重新整理服務中繼資料、重新啟動
+樹，然後從更新後的安裝重新整理服務中繼資料，重新啟動
 服務，並在回報成功前驗證重新啟動的 Gateway 回報預期版本。
 在 macOS 上，更新後檢查也會驗證 LaunchAgent
-已為作用中的設定檔載入/執行，且設定的 loopback 連接埠
+已針對作用中的設定檔載入/執行，且設定的迴路連接埠
 健康。如果 plist 已安裝但 launchd 未監督它，OpenClaw
 會自動重新 bootstrap LaunchAgent，然後重新執行
-健康/版本/頻道就緒檢查。新的 bootstrap 會直接載入 RunAtLoad
-作業，因此更新復原不會立刻對新產生的 Gateway 執行 `kickstart -k`。
-如果 Gateway 仍未變得健康，命令會以非零狀態結束，
-並列印重新啟動日誌路徑，以及明確的重新啟動、重新安裝與
+健康/版本/通道就緒檢查。全新的 bootstrap 會直接載入 RunAtLoad
+作業，因此更新復原不會立即對新產生的 Gateway 執行 `kickstart -k`。
+如果 Gateway 仍然無法變得健康，命令會以非零狀態結束，
+並列印重新啟動記錄路徑，以及明確的重新啟動、重新安裝與
 套件回復指示。使用 `--no-restart` 時，
 套件替換仍會執行，但受管理服務不會被停止或
-重新啟動，因此執行中的 Gateway 可能會持續使用舊程式碼，直到你手動
-重新啟動它。
+重新啟動，因此執行中的 Gateway 可能會保留舊程式碼，直到你手動重新啟動它。
 
 ## Git checkout 流程
 
-### 頻道選擇
+### 通道選擇
 
 - `stable`：checkout 最新的非 beta 標籤，然後建置並執行 doctor。
-- `beta`：優先使用最新的 `-beta` 標籤，但當 beta 缺失或較舊時，退回到最新的穩定版標籤。
+- `beta`：優先使用最新的 `-beta` 標籤，但當 beta 缺失或較舊時，會回退到最新的 stable 標籤。
 - `dev`：checkout `main`，然後 fetch 並 rebase。
 
 ### 更新步驟
@@ -145,56 +145,57 @@ Gateway 核心自動更新器（透過設定啟用時）會在即時 Gateway 請
   <Step title="驗證乾淨的 worktree">
     要求沒有未提交的變更。
   </Step>
-  <Step title="切換頻道">
-    切換到所選頻道（標籤或分支）。
+  <Step title="切換通道">
+    切換到所選通道（標籤或分支）。
   </Step>
   <Step title="Fetch upstream">
     僅限 dev。
   </Step>
   <Step title="預檢建置（僅限 dev）">
-    在暫時 worktree 中執行 lint 與 TypeScript 建置。如果 tip 失敗，會往回最多 10 個 commit，尋找最新的乾淨建置。
+    在暫存 worktree 中執行 lint 與 TypeScript 建置。如果 tip 失敗，會往回最多 10 個 commit，以尋找最新的乾淨建置。
   </Step>
   <Step title="Rebase">
     Rebase 到所選 commit（僅限 dev）。
   </Step>
   <Step title="安裝相依套件">
-    使用 repo 套件管理器。對於 pnpm checkout，更新器會按需 bootstrap `pnpm`（先透過 `corepack`，然後使用暫時的 `npm install pnpm@10` 備援），而不是在 pnpm workspace 內執行 `npm run build`。
+    使用 repo 套件管理器。對於 pnpm checkout，更新器會按需 bootstrap `pnpm`（先透過 `corepack`，再使用暫時的 `npm install pnpm@10` 回退），而不是在 pnpm workspace 內執行 `npm run build`。
   </Step>
   <Step title="建置 Control UI">
     建置 gateway 與 Control UI。
   </Step>
   <Step title="執行 doctor">
-    `openclaw doctor` 會作為最後的安全更新檢查執行。
+    `openclaw doctor` 會作為最終安全更新檢查執行。
   </Step>
-  <Step title="同步 Plugin">
-    將 Plugin 同步到作用中的頻道。Dev 使用內建 Plugin；stable 與 beta 使用 npm。更新已追蹤的 Plugin 安裝。
+  <Step title="同步 plugins">
+    將 plugins 同步到作用中的通道。Dev 使用隨附 plugins；stable 與 beta 使用 npm。更新已追蹤的 plugin 安裝。
   </Step>
 </Steps>
 
-在 beta 更新頻道上，追蹤且遵循 default/latest 線的 npm 與 ClawHub Plugin 安裝
-會先嘗試 Plugin `@beta` 發行版本。如果 Plugin 沒有
-beta 發行版本，OpenClaw 會退回到已記錄的 default/latest spec。精確
-版本與明確標籤不會被改寫。
+在 beta 更新通道上，遵循預設/latest 線的已追蹤 npm 與 ClawHub plugin 安裝
+會先嘗試 plugin `@beta` 發行版本。如果 plugin 沒有
+beta 發行版本，OpenClaw 會回退到已記錄的預設/latest 規格。對於 npm
+plugins，當 beta 套件存在但安裝驗證失敗時，OpenClaw 也會回退。
+精確版本與明確標籤不會被改寫。
 
 <Warning>
-如果精確釘選的 npm Plugin 更新解析到其完整性與儲存安裝記錄不同的成品，`openclaw update` 會中止該 Plugin 成品更新，而不是安裝它。只有在確認你信任新成品後，才明確重新安裝或更新該 Plugin。
+如果精確釘選的 npm plugin 更新解析到的成品，其完整性與儲存的安裝記錄不同，`openclaw update` 會中止該 plugin 成品更新，而不是安裝它。只有在驗證你信任新成品後，才明確重新安裝或更新該 plugin。
 </Warning>
 
 <Note>
-更新後 Plugin 同步失敗會讓更新結果失敗，並停止後續重新啟動工作。修正 Plugin 安裝或更新錯誤，然後重新執行 `openclaw update`。
+更新後 plugin 同步失敗會讓更新結果失敗，並停止後續重新啟動工作。請修正 plugin 安裝或更新錯誤，然後重新執行 `openclaw update`。
 
-當更新後的 Gateway 啟動時，Plugin 載入僅做驗證：啟動不會執行套件管理器，也不會變更相依套件樹。套件管理器 `update.run` 重新啟動會在套件樹替換後繞過一般的閒置延後與重新啟動冷卻，因此舊程序無法繼續 lazy-load 已移除的片段。
+當更新後的 Gateway 啟動時，plugin 載入只會進行驗證：啟動不會執行套件管理器，也不會變更相依樹。套件管理器 `update.run` 重新啟動會在套件樹已替換後，略過一般閒置延後與重新啟動冷卻時間，因此舊程序無法繼續 lazy-load 已移除的區塊。
 
-如果 pnpm bootstrap 仍然失敗，更新器會提早停止並顯示套件管理器專屬錯誤，而不是嘗試在 checkout 內執行 `npm run build`。
+如果 pnpm bootstrap 仍然失敗，更新器會提早停止並顯示套件管理器特定錯誤，而不是嘗試在 checkout 內執行 `npm run build`。
 </Note>
 
 ## `--update` 簡寫
 
-`openclaw --update` 會重寫為 `openclaw update`（對 shell 與啟動器 script 很有用）。
+`openclaw --update` 會改寫為 `openclaw update`（對 shell 與 launcher 指令碼很有用）。
 
 ## 相關
 
-- `openclaw doctor`（在 git checkout 上會提出先執行 update）
-- [開發頻道](/zh-TW/install/development-channels)
-- [Updating](/zh-TW/install/updating)
+- `openclaw doctor`（在 git checkout 上會提議先執行 update）
+- [開發通道](/zh-TW/install/development-channels)
+- [更新](/zh-TW/install/updating)
 - [CLI 參考](/zh-TW/cli)

docs/zh-TW/concepts/models.md

@@ -1,40 +1,40 @@
 ---
 read_when:
     - 新增或修改模型 CLI（models list/set/scan/aliases/fallbacks）
-    - 變更模型備援行為或選擇使用者體驗
+    - 變更模型備援行為或選擇體驗
     - 更新模型掃描探針（工具/圖片）
 sidebarTitle: Models CLI
 summary: 模型 CLI：列出、設定、別名、備援、掃描、狀態
 title: 模型 CLI
 x-i18n:
-    generated_at: "2026-05-02T20:46:07Z"
+    generated_at: "2026-05-05T01:45:06Z"
     model: gpt-5.5
     provider: openai
-    source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f
+    source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f
     source_path: concepts/models.md
     workflow: 16
 ---
 
 <CardGroup cols={2}>
   <Card title="模型容錯移轉" href="/zh-TW/concepts/model-failover">
-    Auth 設定檔輪替、冷卻時間，以及這些如何與備援互動。
+    Auth 設定檔輪替、冷卻時間，以及這如何與備援互動。
   </Card>
-  <Card title="模型供應商" href="/zh-TW/concepts/model-providers">
-    供應商快速概覽與範例。
+  <Card title="模型提供者" href="/zh-TW/concepts/model-providers">
+    快速的提供者概覽和範例。
   </Card>
-  <Card title="Agent 執行階段" href="/zh-TW/concepts/agent-runtimes">
-    PI、Codex，以及其他 agent 迴圈執行階段。
+  <Card title="代理執行階段" href="/zh-TW/concepts/agent-runtimes">
+    PI、Codex 和其他代理迴圈執行階段。
   </Card>
   <Card title="設定參考" href="/zh-TW/gateway/config-agents#agent-defaults">
     模型設定鍵。
   </Card>
 </CardGroup>
 
-模型參照會選擇供應商和模型。它們通常不會選擇低階 agent 執行階段。例如，`openai/gpt-5.5` 可以透過一般 OpenAI 供應商路徑執行，也可以透過 Codex app-server 執行階段執行，取決於 `agents.defaults.agentRuntime.id`。在 Codex 執行階段模式中，`openai/gpt-*` 參照不代表使用 API 金鑰計費；驗證可以來自 Codex 帳戶或 `openai-codex` auth 設定檔。請參閱 [Agent 執行階段](/zh-TW/concepts/agent-runtimes)。
+模型 ref 會選擇提供者和模型。它們通常不會選擇低階代理執行階段。例如，`openai/gpt-5.5` 可以透過一般 OpenAI 提供者路徑執行，也可以透過 Codex app-server 執行階段執行，取決於 `agents.defaults.agentRuntime.id`。在 Codex 執行階段模式中，`openai/gpt-*` ref 不代表 API 金鑰計費；Auth 可以來自 Codex 帳戶或 `openai-codex` Auth 設定檔。請參閱[代理執行階段](/zh-TW/concepts/agent-runtimes)。
 
-## 模型選擇的運作方式
+## 模型選擇如何運作
 
-OpenClaw 會依下列順序選擇模型：
+OpenClaw 會依照下列順序選擇模型：
 
 <Steps>
   <Step title="主要模型">
@@ -43,50 +43,50 @@ OpenClaw 會依下列順序選擇模型：
   <Step title="備援">
     `agents.defaults.model.fallbacks`（依序）。
   </Step>
-  <Step title="供應商 auth 容錯移轉">
-    Auth 容錯移轉會先在供應商內發生，然後才移至下一個模型。
+  <Step title="提供者 Auth 容錯移轉">
+    Auth 容錯移轉會在移至下一個模型之前，於提供者內部發生。
   </Step>
 </Steps>
 
 <AccordionGroup>
   <Accordion title="相關模型介面">
     - `agents.defaults.models` 是 OpenClaw 可使用模型的允許清單/目錄（加上別名）。
-    - `agents.defaults.imageModel` **只有在**主要模型無法接受圖片時使用。
-    - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，工具會退回到 `agents.defaults.imageModel`，再退回到已解析的工作階段/預設模型。
-    - `agents.defaults.imageGenerationModel` 由共用圖片生成能力使用。如果省略，`image_generate` 仍可推斷由 auth 支援的供應商預設值。它會先嘗試目前的預設供應商，接著依 provider-id 順序嘗試其餘已註冊的圖片生成供應商。如果你設定特定供應商/模型，也請設定該供應商的 auth/API 金鑰。
-    - `agents.defaults.musicGenerationModel` 由共用音樂生成能力使用。如果省略，`music_generate` 仍可推斷由 auth 支援的供應商預設值。它會先嘗試目前的預設供應商，接著依 provider-id 順序嘗試其餘已註冊的音樂生成供應商。如果你設定特定供應商/模型，也請設定該供應商的 auth/API 金鑰。
-    - `agents.defaults.videoGenerationModel` 由共用影片生成能力使用。如果省略，`video_generate` 仍可推斷由 auth 支援的供應商預設值。它會先嘗試目前的預設供應商，接著依 provider-id 順序嘗試其餘已註冊的影片生成供應商。如果你設定特定供應商/模型，也請設定該供應商的 auth/API 金鑰。
-    - 每個 agent 的預設值可透過 `agents.list[].model` 加上繫結覆寫 `agents.defaults.model`（請參閱[多 agent 路由](/zh-TW/concepts/multi-agent)）。
+    - `agents.defaults.imageModel` **只會在**主要模型無法接受影像時使用。
+    - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，工具會退回到 `agents.defaults.imageModel`，接著退回到解析後的工作階段/預設模型。
+    - `agents.defaults.imageGenerationModel` 由共用的影像生成能力使用。如果省略，`image_generate` 仍可推斷由 Auth 支援的提供者預設值。它會先嘗試目前的預設提供者，然後依 provider-id 順序嘗試其餘已註冊的影像生成提供者。如果你設定特定提供者/模型，也請設定該提供者的 Auth/API 金鑰。
+    - `agents.defaults.musicGenerationModel` 由共用的音樂生成能力使用。如果省略，`music_generate` 仍可推斷由 Auth 支援的提供者預設值。它會先嘗試目前的預設提供者，然後依 provider-id 順序嘗試其餘已註冊的音樂生成提供者。如果你設定特定提供者/模型，也請設定該提供者的 Auth/API 金鑰。
+    - `agents.defaults.videoGenerationModel` 由共用的影片生成能力使用。如果省略，`video_generate` 仍可推斷由 Auth 支援的提供者預設值。它會先嘗試目前的預設提供者，然後依 provider-id 順序嘗試其餘已註冊的影片生成提供者。如果你設定特定提供者/模型，也請設定該提供者的 Auth/API 金鑰。
+    - 每個代理的預設值可以透過 `agents.list[].model` 加上繫結覆寫 `agents.defaults.model`（請參閱[多代理路由](/zh-TW/concepts/multi-agent)）。
 
   </Accordion>
 </AccordionGroup>
 
 ## 選擇來源與備援行為
 
-同一個 `provider/model` 可能會因來源不同而代表不同意義：
+相同的 `provider/model` 可能會依其來源代表不同含義：
 
-- 已設定的預設值（`agents.defaults.model.primary` 與 agent 專屬主要模型）是一般起點，並會使用 `agents.defaults.model.fallbacks`。
-- 自動備援選擇是暫時復原狀態。它們會以 `modelOverrideSource: "auto"` 儲存，讓後續回合可以繼續使用備援鏈，而不必先探測已知故障的主要模型。
-- 使用者工作階段選擇是精確的。`/model`、模型選擇器、`session_status(model=...)` 和 `sessions.patch` 會儲存 `modelOverrideSource: "user"`；如果所選供應商/模型無法存取，OpenClaw 會明確失敗，而不是落到另一個已設定模型。
-- Cron `--model` / payload `model` 是每個工作的主要模型。它仍會使用已設定的備援，除非工作提供明確的 payload `fallbacks`（若要嚴格 cron 執行，請使用 `fallbacks: []`）。
-- CLI 預設模型與允許清單選擇器會遵守 `models.mode: "replace"`，列出明確的 `models.providers.*.models`，而不是載入完整內建目錄。
-- Control UI 模型選擇器會向 Gateway 要求其已設定的模型檢視：存在時使用 `agents.defaults.models`，否則使用明確的 `models.providers.*.models` 加上具可用 auth 的供應商。完整內建目錄保留給明確的瀏覽檢視，例如帶有 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。
+- 已設定的預設值（`agents.defaults.model.primary` 和代理專屬主要模型）是一般起點，並使用 `agents.defaults.model.fallbacks`。
+- 自動備援選擇是暫時復原狀態。它們會以 `modelOverrideSource: "auto"` 儲存，讓後續回合能繼續使用備援鏈，而不必先探測已知有問題的主要模型。
+- 使用者工作階段選擇是精確的。`/model`、模型選擇器、`session_status(model=...)` 和 `sessions.patch` 會儲存 `modelOverrideSource: "user"`；如果該選取的提供者/模型無法連線，OpenClaw 會明確失敗，而不是落入另一個已設定的模型。
+- Cron `--model` / payload `model` 是每個工作的主要模型。除非工作提供明確的 payload `fallbacks`，否則它仍會使用已設定的備援（若要嚴格執行 cron，請使用 `fallbacks: []`）。
+- CLI 預設模型和允許清單選擇器會遵守 `models.mode: "replace"`，列出明確的 `models.providers.*.models`，而不是載入完整的內建目錄。
+- Control UI 模型選擇器會向 Gateway 詢問其已設定的模型檢視：存在時使用 `agents.defaults.models`，否則使用明確的 `models.providers.*.models` 加上具有可用 Auth 的提供者。完整內建目錄保留給明確瀏覽檢視，例如含有 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。
 
 ## 快速模型政策
 
-- 將主要模型設為你可用的最強最新世代模型。
-- 對成本/延遲敏感的工作與低風險聊天使用備援。
-- 對啟用工具的 agent 或不受信任的輸入，避免使用較舊/較弱的模型層級。
+- 將主要模型設定為你可用的最強最新世代模型。
+- 對成本/延遲敏感任務和較低風險聊天使用備援。
+- 對於啟用工具的代理或不受信任的輸入，避免使用較舊/較弱的模型層級。
 
-## 上線設定（建議）
+## 入門設定（建議）
 
-如果你不想手動編輯設定，請執行上線設定：
+如果你不想手動編輯設定，請執行入門設定：
 
 ```bash
 openclaw onboard
 ```
 
-它可以為常見供應商設定模型與 auth，包括 **OpenAI Code (Codex) 訂閱**（OAuth）和 **Anthropic**（API 金鑰或 Claude CLI）。
+它可以為常見提供者設定模型 + Auth，包括 **OpenAI Code (Codex) 訂閱**（OAuth）和 **Anthropic**（API 金鑰或 Claude CLI）。
 
 ## 設定鍵（概覽）
 
@@ -95,13 +95,13 @@ openclaw onboard
 - `agents.defaults.pdfModel.primary` 和 `agents.defaults.pdfModel.fallbacks`
 - `agents.defaults.imageGenerationModel.primary` 和 `agents.defaults.imageGenerationModel.fallbacks`
 - `agents.defaults.videoGenerationModel.primary` 和 `agents.defaults.videoGenerationModel.fallbacks`
-- `agents.defaults.models`（允許清單 + 別名 + 供應商參數）
-- `models.providers`（寫入 `models.json` 的自訂供應商）
+- `agents.defaults.models`（允許清單 + 別名 + 提供者參數）
+- `models.providers`（寫入 `models.json` 的自訂提供者）
 
 <Note>
-模型參照會正規化為小寫。像 `z.ai/*` 這類供應商別名會正規化為 `zai/*`。
+模型 ref 會正規化為小寫。像 `z.ai/*` 這類提供者別名會正規化為 `zai/*`。
 
-供應商設定範例（包括 OpenCode）位於 [OpenCode](/zh-TW/providers/opencode)。
+提供者設定範例（包括 OpenCode）位於 [OpenCode](/zh-TW/providers/opencode)。
 </Note>
 
 ### 安全的允許清單編輯
@@ -113,35 +113,38 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
 ```
 
 <AccordionGroup>
-  <Accordion title="覆寫保護規則">
-    `openclaw config set` 會保護模型/供應商對應表，避免意外覆寫。對 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 的一般物件指派，若會移除既有項目就會遭拒。請使用 `--merge` 進行加法變更；只有在提供的值應成為完整目標值時才使用 `--replace`。
+  <Accordion title="覆蓋保護規則">
+    `openclaw config set` 會保護模型/提供者映射，避免意外覆蓋。對 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 進行一般物件指派時，如果會移除現有項目，就會遭到拒絕。加法變更請使用 `--merge`；只有在提供的值應成為完整目標值時才使用 `--replace`。
 
-    互動式供應商設定和 `openclaw configure --section model` 也會將供應商範圍的選擇合併到既有允許清單中，因此新增 Codex、Ollama 或其他供應商不會移除不相關的模型項目。重新套用供應商 auth 時，configure 會保留既有的 `agents.defaults.model.primary`。明確設定預設值的命令，例如 `openclaw models auth login --provider <id> --set-default` 和 `openclaw models set <model>`，仍會取代 `agents.defaults.model.primary`。
+    互動式提供者設定和 `openclaw configure --section model` 也會將提供者範圍的選擇合併到現有允許清單，因此新增 Codex、Ollama 或其他提供者不會移除不相關的模型項目。重新套用提供者 Auth 時，Configure 會保留現有的 `agents.defaults.model.primary`。明確設定預設值的命令，例如 `openclaw models auth login --provider <id> --set-default` 和 `openclaw models set <model>`，仍會取代 `agents.defaults.model.primary`。
 
   </Accordion>
 </AccordionGroup>
 
-## 「不允許使用模型」（以及回覆停止的原因）
+## 「模型不被允許」（以及回覆停止的原因）
 
-如果設定了 `agents.defaults.models`，它會成為 `/model` 和工作階段覆寫的**允許清單**。當使用者選擇不在該允許清單中的模型時，OpenClaw 會傳回：
+如果已設定 `agents.defaults.models`，它會成為 `/model` 和工作階段覆寫的**允許清單**。當使用者選擇不在該允許清單中的模型時，OpenClaw 會回傳：
 
 ```
-Model "provider/model" is not allowed. Use /model to list available models.
+Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
+Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
 ```
 
 <Warning>
-這會在一般回覆產生**之前**發生，因此訊息可能感覺像是「沒有回應」。修正方式是擇一：
+這會在產生一般回覆**之前**發生，因此訊息可能感覺像是「沒有回應」。修正方式是下列其中之一：
 
-- 將模型加入 `agents.defaults.models`，或
+- 將模型新增到 `agents.defaults.models`，或
 - 清除允許清單（移除 `agents.defaults.models`），或
 - 從 `/model list` 選擇模型。
 
 </Warning>
 
-對於本機/GGUF 模型，請在允許清單中儲存完整的供應商前綴參照，
+當被拒絕的命令包含執行階段覆寫，例如 `/model openai/gpt-5.5 --runtime codex`，請先修正允許清單，然後重試相同的 `/model ... --runtime ...` 命令。對於原生 Codex 執行，選取的模型仍是 `openai/gpt-5.5`；`codex` 執行階段會選擇 harness，並另外使用 Codex Auth。
+
+對於本機/GGUF 模型，請將完整的 provider-prefixed ref 儲存在允許清單中，
 例如 `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`，或
-`openclaw models list --provider <provider>` 顯示的精確 provider/model。
-當允許清單啟用時，僅有本機檔名或顯示名稱並不足夠。
+`openclaw models list --provider <provider>` 顯示的
+確切 provider/model。當允許清單啟用時，單獨的本機檔名或顯示名稱並不足夠。
 
 允許清單設定範例：
 
@@ -157,9 +160,9 @@ Model "provider/model" is not allowed. Use /model to list available models.
 }
 ```
 
-## 在聊天中切換模型（`/model`）
+## 在聊天中切換模型 (`/model`)
 
-你可以在不重新啟動的情況下切換目前工作階段的模型：
+你可以在不重新啟動的情況下，為目前工作階段切換模型：
 
 ```
 /model
@@ -171,29 +174,29 @@ Model "provider/model" is not allowed. Use /model to list available models.
 
 <AccordionGroup>
   <Accordion title="選擇器行為">
-    - `/model`（和 `/model list`）是精簡的編號選擇器（模型系列 + 可用供應商）。
-    - 在 Discord 上，`/model` 和 `/models` 會開啟互動式選擇器，包含供應商與模型下拉選單，以及 Submit 步驟。
-    - 在 Telegram 上，`/models` 選擇器選項只作用於工作階段；它們不會變更 agent 在 `openclaw.json` 中的持久預設值。
-    - `/models add` 已棄用，現在會傳回棄用訊息，而不是從聊天註冊模型。
+    - `/model`（和 `/model list`）是精簡的編號選擇器（模型家族 + 可用提供者）。
+    - 在 Discord 上，`/model` 和 `/models` 會開啟互動式選擇器，其中包含提供者和模型下拉選單，以及提交步驟。
+    - 在 Telegram 上，`/models` 選擇器的選取項目只限於工作階段；它們不會變更 `openclaw.json` 中代理的持久預設值。
+    - `/models add` 已淘汰，現在會回傳淘汰訊息，而不是從聊天註冊模型。
     - `/model <#>` 會從該選擇器中選取。
 
   </Accordion>
-  <Accordion title="持久化與即時切換">
-    - `/model` 會立即持久化新的工作階段選擇。
-    - 如果 agent 閒置，下一次執行會立刻使用新模型。
-    - 如果已有執行中的工作，OpenClaw 會將即時切換標記為待處理，並只會在乾淨的重試點重新啟動至新模型。
-    - 如果工具活動或回覆輸出已經開始，待處理切換可能會排隊到稍後的重試機會或下一個使用者回合。
-    - 使用者選擇的 `/model` 參照對該工作階段是嚴格的：如果所選供應商/模型無法存取，回覆會明確失敗，而不是靜默地從 `agents.defaults.model.fallbacks` 回答。這不同於已設定的預設值和 cron 工作主要模型，後兩者仍可使用備援鏈。
-    - `/model status` 是詳細檢視（auth 候選，以及設定時的供應商端點 `baseUrl` + `api` 模式）。
+  <Accordion title="持久性與即時切換">
+    - `/model` 會立即保存新的工作階段選擇。
+    - 如果代理閒置，下一次執行會立刻使用新模型。
+    - 如果已有執行正在進行，OpenClaw 會將即時切換標記為待處理，並只會在乾淨的重試點重新啟動到新模型。
+    - 如果工具活動或回覆輸出已經開始，待處理的切換可能會保持佇列狀態，直到稍後的重試機會或下一個使用者回合。
+    - 使用者選取的 `/model` ref 對該工作階段是嚴格的：如果選取的提供者/模型無法連線，回覆會明確失敗，而不是默默從 `agents.defaults.model.fallbacks` 回答。這不同於已設定的預設值和 cron 工作主要模型，後者仍可使用備援鏈。
+    - `/model status` 是詳細檢視（Auth 候選項，以及設定時的提供者端點 `baseUrl` + `api` 模式）。
 
   </Accordion>
-  <Accordion title="參照解析">
-    - 模型參照會依**第一個** `/` 分割來解析。輸入 `/model <ref>` 時請使用 `provider/model`。
-    - 如果模型 ID 本身包含 `/`（OpenRouter 風格），你必須包含供應商前綴（範例：`/model openrouter/moonshotai/kimi-k2`）。
-    - 如果省略供應商，OpenClaw 會依下列順序解析輸入：
-      1. 別名符合
-      2. 對該精確未加前綴模型 id 的唯一已設定供應商符合
-      3. 已棄用的備援：退回到已設定的預設供應商 — 如果該供應商不再公開已設定的預設模型，OpenClaw 會改為退回到第一個已設定的供應商/模型，以避免暴露過期的已移除供應商預設值。
+  <Accordion title="Ref 解析">
+    - 模型 ref 會透過**第一個** `/` 分割來解析。輸入 `/model <ref>` 時請使用 `provider/model`。
+    - 如果模型 ID 本身包含 `/`（OpenRouter 風格），你必須包含提供者前綴（範例：`/model openrouter/moonshotai/kimi-k2`）。
+    - 如果省略提供者，OpenClaw 會依下列順序解析輸入：
+      1. 別名相符
+      2. 該確切未加前綴模型 ID 的唯一已設定提供者相符
+      3. 已淘汰的退回到已設定預設提供者 — 如果該提供者不再公開已設定的預設模型，OpenClaw 會改為退回到第一個已設定的 provider/model，以避免顯示過時的已移除提供者預設值。
   </Accordion>
 </AccordionGroup>
 
@@ -222,14 +225,14 @@ openclaw models image-fallbacks remove <provider/model>
 openclaw models image-fallbacks clear
 ```
 
-`openclaw models`（無子命令）是 `models status` 的捷徑。
+`openclaw models`（沒有子命令）是 `models status` 的捷徑。
 
 ### `models list`
 
-預設顯示已設定/可用 auth 的模型。實用旗標：
+預設顯示已設定／可用驗證的模型。實用旗標：
 
 <ParamField path="--all" type="boolean">
-  完整目錄。包含在設定驗證前由內建提供者擁有的靜態目錄列，因此僅供探索的檢視可以顯示在你加入相符提供者憑證前不可用的模型。
+  完整目錄。包含在設定驗證之前由內建提供者擁有的靜態目錄列，因此僅供探索的檢視可以顯示在新增相符提供者憑證之前無法使用的模型。
 </ParamField>
 <ParamField path="--local" type="boolean">
   僅限本機提供者。
@@ -246,21 +249,21 @@ openclaw models image-fallbacks clear
 
 ### `models status`
 
-顯示解析後的主要模型、備援、影像模型，以及已設定提供者的驗證概覽。它也會顯示驗證儲存區中找到的設定檔 OAuth 到期狀態（預設會在 24 小時內發出警告）。`--plain` 只會列印解析後的主要模型。
+顯示解析後的主要模型、備用模型、影像模型，以及已設定提供者的驗證概覽。它也會揭露驗證儲存區中找到的設定檔 OAuth 到期狀態（預設會在 24 小時內發出警告）。`--plain` 只會列印解析後的主要模型。
 
 <AccordionGroup>
-  <Accordion title="驗證和探測行為">
-    - OAuth 狀態一律會顯示（並包含在 `--json` 輸出中）。如果已設定的提供者沒有憑證，`models status` 會列印 **缺少驗證** 區段。
-    - JSON 包含 `auth.oauth`（警告時間範圍 + 設定檔）和 `auth.providers`（每個提供者的有效驗證，包括由環境支援的憑證）。`auth.oauth` 只代表驗證儲存區設定檔健康狀態；僅使用環境的提供者不會出現在其中。
-    - 自動化請使用 `--check`（缺少/已到期時結束碼為 `1`，即將到期時為 `2`）。
-    - 使用 `--probe` 進行即時驗證檢查；探測列可來自驗證設定檔、環境憑證或 `models.json`。
-    - 如果明確的 `auth.order.<provider>` 省略了已儲存的設定檔，探測會回報 `excluded_by_auth_order`，而不是嘗試使用它。如果驗證存在，但無法為該提供者解析出可探測的模型，探測會回報 `status: no_model`。
+  <Accordion title="驗證與探測行為">
+    - OAuth 狀態一律顯示（也包含在 `--json` 輸出中）。如果已設定的提供者沒有憑證，`models status` 會列印 **Missing auth** 區段。
+    - JSON 包含 `auth.oauth`（警告視窗 + 設定檔）和 `auth.providers`（每個提供者的有效驗證，包括由環境支援的憑證）。`auth.oauth` 僅是驗證儲存區設定檔健康狀態；僅使用環境變數的提供者不會出現在其中。
+    - 將 `--check` 用於自動化（缺少／已到期時結束碼為 `1`，即將到期時為 `2`）。
+    - 將 `--probe` 用於即時驗證檢查；探測列可來自驗證設定檔、環境憑證或 `models.json`。
+    - 如果明確的 `auth.order.<provider>` 省略已儲存的設定檔，探測會回報 `excluded_by_auth_order`，而不是嘗試它。如果驗證存在，但無法為該提供者解析出可探測的模型，探測會回報 `status: no_model`。
 
   </Accordion>
 </AccordionGroup>
 
 <Note>
-驗證選擇取決於提供者/帳戶。對於常駐 Gateway 主機，API 金鑰通常最可預期；也支援 Claude CLI 重用，以及既有的 Anthropic OAuth/token 設定檔。
+驗證選擇取決於提供者／帳戶。對於常駐 Gateway 主機，API 金鑰通常最可預測；也支援重用 Claude CLI 以及現有 Anthropic OAuth／權杖設定檔。
 </Note>
 
 範例（Claude CLI）：
@@ -272,22 +275,22 @@ openclaw models status
 
 ## 掃描（OpenRouter 免費模型）
 
-`openclaw models scan` 會檢查 OpenRouter 的**免費模型目錄**，並可選擇性探測模型是否支援工具和影像。
+`openclaw models scan` 會檢查 OpenRouter 的**免費模型目錄**，並可選擇性地探測模型是否支援工具和影像。
 
 <ParamField path="--no-probe" type="boolean">
-  跳過即時探測（僅中繼資料）。
+  略過即時探測（僅中繼資料）。
 </ParamField>
 <ParamField path="--min-params <b>" type="number">
-  最小參數規模（十億）。
+  最小參數大小（十億）。
 </ParamField>
 <ParamField path="--max-age-days <days>" type="number">
-  跳過較舊的模型。
+  略過較舊的模型。
 </ParamField>
 <ParamField path="--provider <name>" type="string">
   提供者前綴篩選器。
 </ParamField>
 <ParamField path="--max-candidates <n>" type="number">
-  備援清單大小。
+  備用清單大小。
 </ParamField>
 <ParamField path="--set-default" type="boolean">
   將 `agents.defaults.model.primary` 設為第一個選項。
@@ -297,7 +300,7 @@ openclaw models status
 </ParamField>
 
 <Note>
-OpenRouter `/models` 目錄是公開的，因此僅中繼資料掃描可以在沒有金鑰的情況下列出免費候選項。探測與推論仍需要 OpenRouter API 金鑰（來自驗證設定檔或 `OPENROUTER_API_KEY`）。如果沒有可用金鑰，`openclaw models scan` 會退回僅中繼資料輸出，並保持設定不變。使用 `--no-probe` 可明確要求僅中繼資料模式。
+OpenRouter `/models` 目錄是公開的，因此僅中繼資料掃描可以在沒有金鑰的情況下列出免費候選項目。探測和推論仍需要 OpenRouter API 金鑰（來自驗證設定檔或 `OPENROUTER_API_KEY`）。如果沒有可用金鑰，`openclaw models scan` 會退回為僅中繼資料輸出，並保持設定不變。使用 `--no-probe` 可明確要求僅中繼資料模式。
 </Note>
 
 掃描結果排序依據：
@@ -312,38 +315,38 @@ OpenRouter `/models` 目錄是公開的，因此僅中繼資料掃描可以在
 - OpenRouter `/models` 清單（篩選 `:free`）
 - 即時探測需要來自驗證設定檔或 `OPENROUTER_API_KEY` 的 OpenRouter API 金鑰（請參閱[環境變數](/zh-TW/help/environment)）
 - 選用篩選器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
-- 請求/探測控制項：`--timeout`、`--concurrency`
+- 請求／探測控制：`--timeout`、`--concurrency`
 
-在 TTY 中執行即時探測時，你可以互動式選取備援。在非互動模式中，傳入 `--yes` 以接受預設值。僅中繼資料結果僅供參考；`--set-default` 和 `--set-image` 需要即時探測，OpenClaw 才不會設定無金鑰且不可用的 OpenRouter 模型。
+當即時探測在 TUI 中執行時，你可以互動式選取備用模型。在非互動模式下，傳入 `--yes` 以接受預設值。僅中繼資料結果僅供參考；`--set-default` 和 `--set-image` 需要即時探測，這樣 OpenClaw 才不會設定無法使用、沒有金鑰的 OpenRouter 模型。
 
 ## 模型登錄檔（`models.json`）
 
-`models.providers` 中的自訂提供者會寫入代理程式目錄下的 `models.json`（預設為 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非 `models.mode` 設為 `replace`，否則此檔案預設會合併。
+`models.providers` 中的自訂提供者會寫入代理目錄下的 `models.json`（預設為 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非 `models.mode` 設為 `replace`，否則預設會合併此檔案。
 
 <AccordionGroup>
   <Accordion title="合併模式優先順序">
     相符提供者 ID 的合併模式優先順序：
 
-    - 代理程式 `models.json` 中已存在的非空 `baseUrl` 優先。
-    - 代理程式 `models.json` 中的非空 `apiKey` 只有在該提供者目前設定/驗證設定檔內容中不是由 SecretRef 管理時才優先。
-    - 由 SecretRef 管理的提供者 `apiKey` 值會從來源標記重新整理（環境參照為 `ENV_VAR_NAME`，file/exec 參照為 `secretref-managed`），而不是持久化解析後的密鑰。
-    - 由 SecretRef 管理的提供者標頭值會從來源標記重新整理（環境參照為 `secretref-env:ENV_VAR_NAME`，file/exec 參照為 `secretref-managed`）。
-    - 空白或缺少的代理程式 `apiKey`/`baseUrl` 會退回設定中的 `models.providers`。
+    - 代理 `models.json` 中已存在的非空 `baseUrl` 優先。
+    - 只有當該提供者在目前設定／驗證設定檔內容中不是由 SecretRef 管理時，代理 `models.json` 中的非空 `apiKey` 才會優先。
+    - 由 SecretRef 管理的提供者 `apiKey` 值會從來源標記重新整理（環境參照為 `ENV_VAR_NAME`，檔案／執行參照為 `secretref-managed`），而不是持久化解析後的祕密。
+    - 由 SecretRef 管理的提供者標頭值會從來源標記重新整理（環境參照為 `secretref-env:ENV_VAR_NAME`，檔案／執行參照為 `secretref-managed`）。
+    - 空白或缺少的代理 `apiKey`／`baseUrl` 會退回到設定中的 `models.providers`。
     - 其他提供者欄位會從設定和正規化的目錄資料重新整理。
 
   </Accordion>
 </AccordionGroup>
 
 <Note>
-標記持久化以來源為權威：OpenClaw 會寫入來自主動來源設定快照（解析前）的標記，而不是解析後的執行階段密鑰值。這適用於 OpenClaw 重新產生 `models.json` 的任何情況，包括 `openclaw agent` 等命令驅動路徑。
+標記持久化以來源為權威：OpenClaw 會從作用中的來源設定快照（解析前）寫入標記，而不是從解析後的執行階段祕密值寫入。這適用於 OpenClaw 重新產生 `models.json` 的所有情況，包括像 `openclaw agent` 這類由命令驅動的路徑。
 </Note>
 
 ## 相關
 
-- [代理程式執行階段](/zh-TW/concepts/agent-runtimes) — PI、Codex 和其他代理程式迴圈執行階段
+- [代理執行階段](/zh-TW/concepts/agent-runtimes) — PI、Codex 和其他代理迴圈執行階段
 - [設定參考](/zh-TW/gateway/config-agents#agent-defaults) — 模型設定鍵
 - [影像生成](/zh-TW/tools/image-generation) — 影像模型設定
-- [模型容錯移轉](/zh-TW/concepts/model-failover) — 備援鏈
+- [模型容錯移轉](/zh-TW/concepts/model-failover) — 備用鏈
 - [模型提供者](/zh-TW/concepts/model-providers) — 提供者路由與驗證
 - [音樂生成](/zh-TW/tools/music-generation) — 音樂模型設定
 - [影片生成](/zh-TW/tools/video-generation) — 影片模型設定

docs/zh-TW/concepts/qa-e2e-automation.md

@@ -2,60 +2,60 @@
 read_when:
     - 了解 QA 堆疊如何整合運作
     - 擴充 qa-lab、qa-channel 或傳輸配接器
-    - 新增由儲存庫支援的品質保證情境
-    - 圍繞 Gateway 儀表板建構更高真實度的品質保證自動化
-summary: QA 堆疊概覽：qa-lab、qa-channel、由儲存庫支援的情境、即時傳輸通道、傳輸配接器，以及報告。
-title: QA 概覽
+    - 新增由儲存庫支援的 QA 情境
+    - 圍繞 Gateway 儀表板建置更高擬真度的 QA 自動化
+summary: QA 堆疊概覽：qa-lab、qa-channel、由儲存庫支援的情境、即時傳輸通道、傳輸轉接器與報告。
+title: QA 概觀
 x-i18n:
-    generated_at: "2026-05-04T07:04:31Z"
+    generated_at: "2026-05-05T01:45:20Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
+    source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96
     source_path: concepts/qa-e2e-automation.md
     workflow: 16
 ---
 
-私有 QA 堆疊旨在以比單一單元測試更貼近真實、通道形態的方式演練 OpenClaw。
+私有 QA 堆疊旨在以更貼近真實、通道形態的方式測試 OpenClaw，這是單一單元測試無法做到的。
 
-目前組件：
+目前組成：
 
-- `extensions/qa-channel`：合成訊息通道，具備 DM、頻道、執行緒、反應、編輯與刪除介面。
-- `extensions/qa-lab`：除錯器 UI 與 QA 匯流排，用於觀察文字記錄、注入傳入訊息，以及匯出 Markdown 報告。
-- `extensions/qa-matrix`、未來的 runner Plugin：即時傳輸配接器，用於在子 QA Gateway 內驅動真實通道。
+- `extensions/qa-channel`：合成訊息通道，包含 DM、頻道、執行緒、反應、編輯與刪除介面。
+- `extensions/qa-lab`：用於觀察逐字稿、注入傳入訊息，以及匯出 Markdown 報告的除錯器 UI 與 QA 匯流排。
+- `extensions/qa-matrix`、未來的執行器 Plugin：即時傳輸配接器，會在子 QA Gateway 內驅動真實通道。
 - `qa/`：由 repo 支援的啟動任務種子資產與基準 QA 情境。
 - [Mantis](/zh-TW/concepts/mantis)：針對需要真實傳輸、瀏覽器截圖、VM 狀態與 PR 證據的錯誤，進行修復前後的即時驗證。
 
 ## 命令介面
 
-每個 QA 流程都在 `pnpm openclaw qa <subcommand>` 下執行。許多命令有 `pnpm qa:*` 指令碼別名；兩種形式都支援。
+每個 QA 流程都在 `pnpm openclaw qa <subcommand>` 下執行。許多都有 `pnpm qa:*` 指令碼別名；兩種形式都支援。
 
-| 命令                                                | 用途                                                                                                                                                                                                 |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `qa run`                                            | 內建 QA 自我檢查；寫入 Markdown 報告。                                                                                                                                                               |
-| `qa suite`                                          | 針對 QA Gateway lane 執行 repo 支援的情境。別名：`pnpm openclaw qa suite --runner multipass` 用於一次性的 Linux VM。                                                                                  |
-| `qa coverage`                                       | 列印 Markdown 情境覆蓋清單（`--json` 用於機器輸出）。                                                                                                                                                 |
-| `qa parity-report`                                  | 比較兩個 `qa-suite-summary.json` 檔案，並寫入代理式對等報告。                                                                                                                                         |
-| `qa character-eval`                                 | 跨多個即時模型執行角色 QA 情境，並產生評審報告。請參閱[報告](#reporting)。                                                                                                                           |
-| `qa manual`                                         | 針對所選 provider/model lane 執行一次性 prompt。                                                                                                                                                     |
-| `qa ui`                                             | 啟動 QA 除錯器 UI 與本機 QA 匯流排（別名：`pnpm qa:lab:ui`）。                                                                                                                                        |
-| `qa docker-build-image`                             | 建置預先烘焙的 QA Docker 映像檔。                                                                                                                                                                    |
-| `qa docker-scaffold`                                | 寫入 QA 儀表板 + Gateway lane 的 docker-compose scaffold。                                                                                                                                            |
-| `qa up`                                             | 建置 QA site、啟動 Docker 支援的堆疊，並列印 URL（別名：`pnpm qa:lab:up`；`:fast` 變體會加入 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。                                               |
-| `qa aimock`                                         | 僅啟動 AIMock provider 伺服器。                                                                                                                                                                      |
-| `qa mock-openai`                                    | 僅啟動可感知情境的 `mock-openai` provider 伺服器。                                                                                                                                                   |
-| `qa credentials doctor` / `add` / `list` / `remove` | 管理共用的 Convex 憑證集區。                                                                                                                                                                        |
-| `qa matrix`                                         | 針對一次性 Tuwunel homeserver 的即時傳輸 lane。請參閱 [Matrix QA](/zh-TW/concepts/qa-matrix)。                                                                                                             |
-| `qa telegram`                                       | 針對真實私人 Telegram 群組的即時傳輸 lane。                                                                                                                                                          |
-| `qa discord`                                        | 針對真實私人 Discord guild 頻道的即時傳輸 lane。                                                                                                                                                     |
-| `qa slack`                                          | 針對真實私人 Slack 頻道的即時傳輸 lane。                                                                                                                                                             |
-| `qa mantis`                                         | 用於即時傳輸錯誤的修復前後驗證 runner，包含 Discord 狀態反應證據、Crabbox 桌面/瀏覽器 smoke，以及 Slack-in-VNC smoke。請參閱 [Mantis](/zh-TW/concepts/mantis)。                                           |
+| 命令                                                | 用途                                                                                                                                                                                         |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `qa run`                                            | 內建 QA 自我檢查；寫入 Markdown 報告。                                                                                                                                                      |
+| `qa suite`                                          | 針對 QA Gateway 跑道執行 repo 支援的情境。別名：`pnpm openclaw qa suite --runner multipass`，用於一次性 Linux VM。                                                                          |
+| `qa coverage`                                       | 列印 markdown 情境涵蓋率清單（`--json` 用於機器輸出）。                                                                                                                                     |
+| `qa parity-report`                                  | 比較兩個 `qa-suite-summary.json` 檔案並寫入代理式一致性報告。                                                                                                                               |
+| `qa character-eval`                                 | 跨多個即時模型執行角色 QA 情境，並產生經評審的報告。請參閱[報告](#reporting)。                                                                                                              |
+| `qa manual`                                         | 針對所選 provider/model 跑道執行一次性提示。                                                                                                                                                |
+| `qa ui`                                             | 啟動 QA 除錯器 UI 與本機 QA 匯流排（別名：`pnpm qa:lab:ui`）。                                                                                                                              |
+| `qa docker-build-image`                             | 建置預先烘焙的 QA Docker 映像。                                                                                                                                                             |
+| `qa docker-scaffold`                                | 寫入 QA 儀表板 + Gateway 跑道的 docker-compose 鷹架。                                                                                                                                       |
+| `qa up`                                             | 建置 QA 站台、啟動 Docker 支援的堆疊，並列印 URL（別名：`pnpm qa:lab:up`；`:fast` 變體會加入 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。                                     |
+| `qa aimock`                                         | 只啟動 AIMock provider 伺服器。                                                                                                                                                             |
+| `qa mock-openai`                                    | 只啟動具備情境感知能力的 `mock-openai` provider 伺服器。                                                                                                                                    |
+| `qa credentials doctor` / `add` / `list` / `remove` | 管理共用 Convex 憑證池。                                                                                                                                                                    |
+| `qa matrix`                                         | 針對一次性 Tuwunel homeserver 的即時傳輸跑道。請參閱 [Matrix QA](/zh-TW/concepts/qa-matrix)。                                                                                                      |
+| `qa telegram`                                       | 針對真實私有 Telegram 群組的即時傳輸跑道。                                                                                                                                                  |
+| `qa discord`                                        | 針對真實私有 Discord guild 頻道的即時傳輸跑道。                                                                                                                                             |
+| `qa slack`                                          | 針對真實私有 Slack 頻道的即時傳輸跑道。                                                                                                                                                     |
+| `qa mantis`                                         | 用於即時傳輸錯誤的修復前後驗證執行器，包含 Discord 狀態反應證據、Crabbox 桌面/瀏覽器 smoke，以及 Slack-in-VNC smoke。請參閱 [Mantis](/zh-TW/concepts/mantis)。 |
 
-## 操作員流程
+## 操作者流程
 
-目前的 QA 操作員流程是一個雙窗格 QA site：
+目前的 QA 操作者流程是一個雙窗格 QA 站台：
 
-- 左側：包含代理的 Gateway 儀表板（Control UI）。
-- 右側：QA Lab，顯示類 Slack 的文字記錄與情境計畫。
+- 左側：帶有代理的 Gateway 儀表板（Control UI）。
+- 右側：QA Lab，顯示類 Slack 的逐字稿與情境計畫。
 
 使用以下命令執行：
 
@@ -63,9 +63,9 @@ x-i18n:
 pnpm qa:lab:up
 ```
 
-這會建置 QA site、啟動 Docker 支援的 Gateway lane，並公開 QA Lab 頁面，讓操作員或自動化迴圈可以給代理一個 QA 任務、觀察真實通道行為，並記錄哪些運作正常、失敗或仍受阻。
+這會建置 QA 站台、啟動 Docker 支援的 Gateway 跑道，並公開 QA Lab 頁面，讓操作者或自動化迴圈可以給代理一個 QA 任務、觀察真實通道行為，並記錄哪些成功、失敗或仍被阻擋。
 
-若要更快迭代 QA Lab UI，而不必每次都重新建置 Docker 映像檔，請使用 bind-mounted QA Lab bundle 啟動堆疊：
+若要在每次不重新建置 Docker 映像的情況下更快迭代 QA Lab UI，請使用繫結掛載的 QA Lab bundle 啟動堆疊：
 
 ```bash
 pnpm openclaw qa docker-build-image
@@ -74,7 +74,7 @@ pnpm qa:lab:up:fast
 pnpm qa:lab:watch
 ```
 
-`qa:lab:up:fast` 讓 Docker 服務使用預建映像檔，並將 `extensions/qa-lab/web/dist` bind-mount 到 `qa-lab` 容器中。`qa:lab:watch` 會在變更時重新建置該 bundle，而當 QA Lab 資產 hash 變更時，瀏覽器會自動重新載入。
+`qa:lab:up:fast` 會讓 Docker 服務使用預先建置的映像，並將 `extensions/qa-lab/web/dist` 繫結掛載到 `qa-lab` 容器中。`qa:lab:watch` 會在變更時重建該 bundle，而當 QA Lab 資產雜湊變更時，瀏覽器會自動重新載入。
 
 若要執行本機 OpenTelemetry trace smoke，請執行：
 
@@ -82,19 +82,19 @@ pnpm qa:lab:watch
 pnpm qa:otel:smoke
 ```
 
-該指令碼會啟動本機 OTLP/HTTP trace 接收器，在啟用 `diagnostics-otel` Plugin 的情況下執行 `otel-trace-smoke` QA 情境，然後解碼匯出的 protobuf spans，並斷言發行關鍵形狀：`openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、`openclaw.context.assembled` 與 `openclaw.message.delivery` 必須存在；成功回合中的模型呼叫不得匯出 `StreamAbandoned`；原始診斷 ID 與 `openclaw.content.*` 屬性必須留在 trace 之外。它會在 QA suite artifacts 旁寫入 `otel-smoke-summary.json`。
+該指令碼會啟動本機 OTLP/HTTP trace 接收器，在啟用 `diagnostics-otel` Plugin 的情況下執行 `otel-trace-smoke` QA 情境，接著解碼匯出的 protobuf spans，並斷言 release 關鍵形狀：必須存在 `openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、`openclaw.context.assembled` 與 `openclaw.message.delivery`；模型呼叫在成功輪次中不得匯出 `StreamAbandoned`；原始診斷 ID 與 `openclaw.content.*` 屬性必須留在 trace 之外。它會在 QA suite artifacts 旁寫入 `otel-smoke-summary.json`。
 
-可觀測性 QA 僅保留於來源 checkout。npm tarball 會刻意省略 QA Lab，因此套件 Docker release lane 不會執行 `qa` 命令。變更診斷檢測時，請從已建置的來源 checkout 執行 `pnpm qa:otel:smoke`。
+Observability QA 僅限 source checkout。npm tarball 會刻意省略 QA Lab，因此 package Docker release 跑道不會執行 `qa` 命令。變更 diagnostics instrumentation 時，請從已建置的 source checkout 執行 `pnpm qa:otel:smoke`。
 
-若要執行 transport-real Matrix smoke lane，請執行：
+若要執行真實傳輸的 Matrix smoke 跑道，請執行：
 
 ```bash
 pnpm openclaw qa matrix --profile fast --fail-fast
 ```
 
-此 lane 的完整 CLI 參考、profile/情境目錄、env vars 與 artifact 版面配置位於 [Matrix QA](/zh-TW/concepts/qa-matrix)。概覽如下：它會在 Docker 中佈建一次性 Tuwunel homeserver，註冊臨時 driver/SUT/observer 使用者，在限定於該傳輸的子 QA Gateway 內執行真實 Matrix Plugin（不含 `qa-channel`），然後在 `.artifacts/qa-e2e/matrix-<timestamp>/` 下寫入 Markdown 報告、JSON 摘要、observed-events artifact 與合併輸出 log。
+此跑道的完整 CLI 參考、profile/情境目錄、env vars 與 artifact 配置位於 [Matrix QA](/zh-TW/concepts/qa-matrix)。簡而言之：它會在 Docker 中佈建一次性的 Tuwunel homeserver、註冊暫時的 driver/SUT/observer 使用者、在限定於該傳輸的子 QA Gateway 內執行真實 Matrix Plugin（沒有 `qa-channel`），然後在 `.artifacts/qa-e2e/matrix-<timestamp>/` 下寫入 Markdown 報告、JSON 摘要、觀察到的事件 artifact，以及合併輸出 log。
 
-若要執行 transport-real Telegram、Discord 與 Slack smoke lane：
+針對真實傳輸的 Telegram、Discord 與 Slack smoke 跑道：
 
 ```bash
 pnpm openclaw qa telegram
@@ -102,9 +102,9 @@ pnpm openclaw qa discord
 pnpm openclaw qa slack
 ```
 
-它們會以預先存在且真實的通道為目標，並使用兩個 bot（driver + SUT）。必要 env vars、情境清單、輸出 artifacts 與 Convex 憑證集區記錄在下方的 [Telegram、Discord 與 Slack QA 參考](#telegram-discord-and-slack-qa-reference)。
+它們會以預先存在、帶有兩個 bot（driver + SUT）的真實通道為目標。必要的 env vars、情境清單、輸出 artifacts 與 Convex 憑證池，記錄在下方的 [Telegram、Discord 與 Slack QA 參考](#telegram-discord-and-slack-qa-reference)。
 
-若要執行包含 VNC 救援的完整 Slack 桌面 VM 執行，請執行：
+若要執行含 VNC 救援的完整 Slack 桌面 VM 執行，請執行：
 
 ```bash
 pnpm openclaw qa mantis slack-desktop-smoke \
@@ -113,62 +113,71 @@ pnpm openclaw qa mantis slack-desktop-smoke \
   --keep-lease
 ```
 
-該命令會租用 Crabbox 桌面/瀏覽器機器，在 VM 內執行 Slack 即時 lane，在 VNC 瀏覽器中開啟 Slack Web，擷取桌面，並將 `slack-qa/` 與 `slack-desktop-smoke.png` 複製回 Mantis artifact 目錄。透過 VNC 手動登入 Slack Web 後，請重複使用 `--lease-id <cbx_...>`。使用 `--gateway-setup` 時，Mantis 會在 VM 內留下持久執行的 OpenClaw Slack Gateway，連接埠為 `38973`；未使用時，該命令會執行一般 bot-to-bot Slack QA lane，並在擷取 artifact 後結束。
+該命令會租用一台 Crabbox 桌面/瀏覽器機器，在 VM 內執行 Slack 即時跑道，在 VNC 瀏覽器中開啟 Slack Web、擷取桌面，並將 `slack-qa/` 加上 `slack-desktop-smoke.png` 複製回 Mantis artifact 目錄。透過 VNC 手動登入 Slack Web 後，可重用 `--lease-id <cbx_...>`。使用 `--gateway-setup` 時，Mantis 會在 VM 內的 `38973` 連接埠留下持久執行的 OpenClaw Slack Gateway；不使用時，該命令會執行一般 bot-to-bot Slack QA 跑道，並在擷取 artifact 後結束。
 
-使用集區中的即時憑證前，請執行：
+使用 pooled 即時憑證之前，請執行：
 
 ```bash
 pnpm openclaw qa credentials doctor
 ```
 
-doctor 會檢查 Convex broker env、驗證 endpoint 設定，並在存在 maintainer secret 時確認 admin/list 可連線性。它只會回報 secret 的已設定/缺漏狀態。
+doctor 會檢查 Convex broker env、驗證 endpoint 設定，並在 maintainer secret 存在時驗證 admin/list 可達性。它只會回報 secrets 的已設定/缺失狀態。
 
-## 即時傳輸覆蓋範圍
+## 即時傳輸涵蓋率
 
-即時傳輸 lane 共用同一份合約，而不是各自發明情境清單形狀。`qa-channel` 是廣泛的合成產品行為 suite，不屬於即時傳輸覆蓋矩陣。
+即時傳輸跑道共用同一份合約，而不是各自發明自己的情境清單形狀。`qa-channel` 是廣泛的合成產品行為 suite，並不是即時傳輸涵蓋率矩陣的一部分。
 
-| Lane     | Canary | Mention gating | Bot-to-bot | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | Native command registration |
+| 跑道     | Canary | 提及門控       | Bot-to-bot | Allowlist block | 頂層回覆        | 重新啟動續接   | 執行緒後續追蹤   | 執行緒隔離       | 反應觀察             | 說明命令     | 原生命令註冊                |
 | -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- |
 | Matrix   | x      | x              | x          | x               | x               | x              | x                | x                | x                    |              |                             |
 | Telegram | x      | x              | x          |                 |                 |                |                  |                  |                      | x            |                             |
 | Discord  | x      | x              | x          |                 |                 |                |                  |                  |                      |              | x                           |
 | Slack    | x      | x              | x          |                 |                 |                |                  |                  |                      |              |                             |
 
-這會將 `qa-channel` 保留為廣泛的產品行為 suite，同時讓 Matrix、Telegram 與未來的即時傳輸共用一份明確的傳輸合約檢查清單。
+這會讓 `qa-channel` 維持為廣泛的產品行為 suite，同時讓 Matrix、Telegram 與未來的即時傳輸共用一份明確的傳輸合約檢查清單。
 
-若要執行一次性 Linux VM lane，且不將 Docker 帶入 QA 路徑，請執行：
+若要執行一次性 Linux VM 跑道，且不將 Docker 帶入 QA 路徑，請執行：
 
 ```bash
 pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
 ```
 
-這會啟動新的 Multipass 客體、安裝相依套件、在客體內建置 OpenClaw，執行 `qa suite`，然後將一般 QA 報告和摘要複製回主機上的 `.artifacts/qa-e2e/...`。
+這會啟動全新的 Multipass 客體、安裝相依套件、在客體內建置 OpenClaw
+、執行 `qa suite`，然後將一般 QA 報告與
+摘要複製回主機上的 `.artifacts/qa-e2e/...`。
 它會重用與主機上 `qa suite` 相同的情境選擇行為。
-主機和 Multipass 套件執行預設會使用隔離的 gateway workers 並行執行多個已選情境。`qa-channel` 預設並行數為 4，並受限於已選情境數。使用 `--concurrency <count>` 調整 worker 數量，或使用 `--concurrency 1` 進行序列執行。
-當任何情境失敗時，命令會以非零狀態結束。當你需要產物但不想要失敗結束碼時，請使用 `--allow-failures`。
-Live 執行會轉送對客體實用且受支援的 QA 驗證輸入：以 env 為基礎的 provider keys、QA live provider config path，以及存在時的 `CODEX_HOME`。請將 `--output-dir` 保持在 repo root 底下，讓客體能透過已掛載的工作區寫回。
+主機與 Multipass suite 執行預設會以隔離的 Gateway worker
+平行執行多個選取的情境。`qa-channel` 預設並行數為
+4，並受選取情境數量限制。使用 `--concurrency <count>` 來調整
+worker 數量，或使用 `--concurrency 1` 進行序列執行。
+任何情境失敗時，命令都會以非零狀態結束。當你
+想取得成品但不想要失敗結束碼時，使用 `--allow-failures`。
+即時執行會轉送客體可實際使用的受支援 QA 驗證輸入：
+以 env 為基礎的 provider keys、QA live provider config 路徑，以及
+存在時的 `CODEX_HOME`。請將 `--output-dir` 保持在 repo root 底下，讓客體
+可以透過掛載的 workspace 寫回。
 
-## Telegram、Discord 和 Slack QA 參考
+## Telegram、Discord 與 Slack QA 參考
 
-Matrix 有[專屬頁面](/zh-TW/concepts/qa-matrix)，因為它的情境數量和 Docker-backed homeserver 佈建較多。Telegram、Discord 和 Slack 較小型，每個只有少數情境、沒有 profile system，並針對預先存在的真實 channels，因此它們的參考資料放在這裡。
+Matrix 有一個[專屬頁面](/zh-TW/concepts/qa-matrix)，因為它的情境數量較多，且需要以 Docker 支援的 homeserver 佈建。Telegram、Discord 與 Slack 較小型，每個只有少數情境，沒有 profile 系統，並針對既有的真實頻道，因此它們的參考資料放在這裡。
 
 ### 共用 CLI 旗標
 
-這些 lanes 透過 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 註冊，並接受相同旗標：
+這些 lane 會透過 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 註冊，並接受相同旗標：
 
-| 旗標                                  | 預設值                                                          | 說明                                                                                                                  |
+| 旗標                                  | 預設值                                                         | 說明                                                                                                           |
 | ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `--scenario <id>`                     | —                                                               | 只執行此情境。可重複。                                                                                               |
-| `--output-dir <path>`                 | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 寫入 reports/summary/observed messages 和 output log 的位置。相對路徑會依 `--repo-root` 解析。                       |
-| `--repo-root <path>`                  | `process.cwd()`                                                 | 從中立 cwd 呼叫時的 repository root。                                                                                |
-| `--sut-account <id>`                  | `sut`                                                           | QA gateway config 內的暫時 account id。                                                                              |
-| `--provider-mode <mode>`              | `live-frontier`                                                 | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可使用）。                                                     |
-| `--model <ref>` / `--alt-model <ref>` | provider 預設值                                                 | 主要/替代 model refs。                                                                                               |
-| `--fast`                              | 關閉                                                            | 支援時的 provider fast mode。                                                                                        |
-| `--credential-source <env\|convex>`   | `env`                                                           | 請參閱 [Convex credential pool](#convex-credential-pool)。                                                           |
-| `--credential-role <maintainer\|ci>`  | CI 中為 `ci`，否則為 `maintainer`                               | `--credential-source convex` 時使用的角色。                                                                          |
+| `--scenario <id>`                     | —                                                               | 只執行此情境。可重複指定。                                                                                   |
+| `--output-dir <path>`                 | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 報告、摘要、觀察到的訊息與輸出日誌寫入的位置。相對路徑會相對於 `--repo-root` 解析。 |
+| `--repo-root <path>`                  | `process.cwd()`                                                 | 從中性 cwd 呼叫時的 repository root。                                                                     |
+| `--sut-account <id>`                  | `sut`                                                           | QA Gateway config 內的臨時帳戶 id。                                                                    |
+| `--provider-mode <mode>`              | `live-frontier`                                                 | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可使用）。                                                  |
+| `--model <ref>` / `--alt-model <ref>` | provider 預設值                                                | 主要/替代 model refs。                                                                                         |
+| `--fast`                              | 關閉                                                             | provider 支援時的快速模式。                                                                                   |
+| `--credential-source <env\|convex>`   | `env`                                                           | 請參閱 [Convex credential pool](#convex-credential-pool)。                                                                |
+| `--credential-role <maintainer\|ci>`  | CI 中為 `ci`，否則為 `maintainer`                              | 使用 `--credential-source convex` 時的角色。                                                                          |
 
-任何情境失敗時，各 lane 都會以非零狀態結束。`--allow-failures` 會寫入產物，而不設定失敗結束碼。
+任何情境失敗時，每個 lane 都會以非零狀態結束。`--allow-failures` 會寫入成品，但不設定失敗結束碼。
 
 ### Telegram QA
 
@@ -176,17 +185,17 @@ Matrix 有[專屬頁面](/zh-TW/concepts/qa-matrix)，因為它的情境數量
 pnpm openclaw qa telegram
 ```
 
-目標是一個真實的私有 Telegram 群組，並使用兩個不同的 bot（driver + SUT）。SUT bot 必須有 Telegram 使用者名稱；當兩個 bot 都在 `@BotFather` 中啟用 **Bot-to-Bot Communication Mode** 時，bot-to-bot 觀察效果最佳。
+目標是一個真實的私人 Telegram 群組，並使用兩個不同 bot（driver + SUT）。SUT bot 必須有 Telegram 使用者名稱；當兩個 bot 都在 `@BotFather` 中啟用 **Bot-to-Bot Communication Mode** 時，bot 對 bot 觀察效果最好。
 
-使用 `--credential-source env` 時必要的 env：
+使用 `--credential-source env` 時必要 env：
 
-- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — 數值 chat id（字串）。
+- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — 數字 chat id（字串）。
 - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
 - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
 
-可選：
+選用：
 
-- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 會在 observed-message 產物中保留訊息本文（預設會遮蔽）。
+- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文（預設會遮蔽）。
 
 情境（`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`）：
 
@@ -199,11 +208,11 @@ pnpm openclaw qa telegram
 - `telegram-whoami-command`
 - `telegram-context-command`
 
-輸出產物：
+輸出成品：
 
 - `telegram-qa-report.md`
-- `telegram-qa-summary.json` — 包含從 canary 開始的每則回覆 RTT（driver send → observed SUT reply）。
-- `telegram-qa-observed-messages.json` — 除非 `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
+- `telegram-qa-summary.json` — 包含從 canary 開始的每次回覆 RTT（driver 傳送 → 觀察到 SUT 回覆）。
+- `telegram-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
 
 ### Discord QA
 
@@ -211,26 +220,26 @@ pnpm openclaw qa telegram
 pnpm openclaw qa discord
 ```
 
-目標是一個真實的私有 Discord guild channel，並使用兩個 bot：由 harness 控制的 driver bot，以及由子 OpenClaw gateway 透過 bundled Discord plugin 啟動的 SUT bot。驗證 channel mention 處理、SUT bot 已向 Discord 註冊原生 `/help` 命令，以及 opt-in Mantis 證據情境。
+目標是一個真實的私人 Discord guild channel，並使用兩個 bot：由 harness 控制的 driver bot，以及由 child OpenClaw Gateway 透過隨附的 Discord Plugin 啟動的 SUT bot。驗證頻道 mention 處理、SUT bot 已向 Discord 註冊原生 `/help` 命令，以及選擇性啟用的 Mantis 證據情境。
 
-使用 `--credential-source env` 時必要的 env：
+使用 `--credential-source env` 時必要 env：
 
 - `OPENCLAW_QA_DISCORD_GUILD_ID`
 - `OPENCLAW_QA_DISCORD_CHANNEL_ID`
 - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
 - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
-- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必須與 Discord 回傳的 SUT bot user id 相符（否則該 lane 會快速失敗）。
+- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必須符合 Discord 回傳的 SUT bot user id（否則此 lane 會快速失敗）。
 
-可選：
+選用：
 
-- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 會在 observed-message 產物中保留訊息本文。
+- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文。
 
 情境（`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`）：
 
 - `discord-canary`
 - `discord-mention-gating`
 - `discord-native-help-command-registration`
-- `discord-status-reactions-tool-only` — opt-in Mantis 情境。它會單獨執行，因為它會將 SUT 切換為 always-on、tool-only guild replies，並設定 `messages.statusReactions.enabled=true`，接著擷取 REST reaction timeline 加上 HTML/PNG 視覺產物。
+- `discord-status-reactions-tool-only` — 選擇性啟用的 Mantis 情境。它會單獨執行，因為它會將 SUT 切換為 always-on、tool-only 的 guild 回覆，並設定 `messages.statusReactions.enabled=true`，接著擷取 REST reaction timeline 以及 HTML/PNG 視覺成品。
 
 明確執行 Mantis status-reaction 情境：
 
@@ -243,12 +252,12 @@ pnpm openclaw qa discord \
   --fast
 ```
 
-輸出產物：
+輸出成品：
 
 - `discord-qa-report.md`
 - `discord-qa-summary.json`
-- `discord-qa-observed-messages.json` — 除非 `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
-- status-reaction 情境執行時會產生 `discord-qa-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。
+- `discord-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
+- 執行 status-reaction 情境時會產生 `discord-qa-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。
 
 ### Slack QA
 
@@ -256,140 +265,315 @@ pnpm openclaw qa discord \
 pnpm openclaw qa slack
 ```
 
-目標是一個真實的私有 Slack channel，並使用兩個不同的 bot：由 harness 控制的 driver bot，以及由子 OpenClaw gateway 透過 bundled Slack plugin 啟動的 SUT bot。
+目標是一個真實的私人 Slack channel，並使用兩個不同 bot：由 harness 控制的 driver bot，以及由 child OpenClaw Gateway 透過隨附的 Slack Plugin 啟動的 SUT bot。
 
-使用 `--credential-source env` 時必要的 env：
+使用 `--credential-source env` 時必要 env：
 
 - `OPENCLAW_QA_SLACK_CHANNEL_ID`
 - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
 - `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
 - `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
 
-可選：
+選用：
 
-- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` 會在 observed-message 產物中保留訊息本文。
+- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文。
 
 情境（`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`）：
 
 - `slack-canary`
 - `slack-mention-gating`
 
-輸出產物：
+輸出成品：
 
 - `slack-qa-report.md`
 - `slack-qa-summary.json`
-- `slack-qa-observed-messages.json` — 除非 `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
+- `slack-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
 
-### Convex credential pool
+#### 設定 Slack workspace
 
-Telegram、Discord 和 Slack lanes 可以從共用 Convex pool 租用 credentials，而不是讀取上述 env vars。傳入 `--credential-source convex`（或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 會取得獨占 lease，在執行期間對其傳送 Heartbeat，並在關閉時釋放。Pool kinds 為 `"telegram"`、`"discord"` 和 `"slack"`。
+此 lane 需要在同一個 workspace 中有兩個不同 Slack app，以及一個兩個 bot 都是成員的 channel：
 
-Broker 在 `admin/add` 上驗證的 payload shapes：
+- `channelId` — 兩個 bot 都已受邀加入的 channel 的 `Cxxxxxxxxxx` id。請使用專用 channel；此 lane 每次執行都會發文。
+- `driverBotToken` — **Driver** app 的 bot token（`xoxb-...`）。
+- `sutBotToken` — **SUT** app 的 bot token（`xoxb-...`），它必須是與 driver 分開的 Slack app，讓其 bot user id 不同。
+- `sutAppToken` — SUT app 具備 `connections:write` 的 app-level token（`xapp-...`），由 Socket Mode 使用，讓 SUT app 可以接收事件。
 
-- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }` — `groupId` 必須是數值 chat-id 字串。
+建議使用專供 QA 的 Slack workspace，而不是重用 production workspace。
+
+以下 SUT manifest 對應隨附 Slack Plugin 的 production install（`extensions/slack/src/setup-shared.ts:10`）。若要查看使用者看到的 production-channel 設定，請參閱 [Slack channel quick setup](/zh-TW/channels/slack#quick-setup)；QA Driver/SUT 組合刻意分開，因為此 lane 需要同一個 workspace 中有兩個不同的 bot user id。
+
+**1. 建立 Driver app**
+
+前往 [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → 選取 QA workspace，貼上以下 manifest，然後 _Install to Workspace_：
+
+```json
+{
+  "display_information": {
+    "name": "OpenClaw QA Driver",
+    "description": "Test driver bot for OpenClaw QA Slack live lane"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "OpenClaw QA Driver",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": ["chat:write", "channels:history", "groups:history", "users:read"]
+    }
+  },
+  "settings": {
+    "socket_mode_enabled": false
+  }
+}
+```
+
+複製 _Bot User OAuth Token_（`xoxb-...`）— 這會成為 `driverBotToken`。driver 只需要發佈訊息並識別自身；不需要事件，也不需要 Socket Mode。
+
+**2. 建立 SUT app**
+
+在同一個 workspace 中重複 _Create New App → From a manifest_。scope 集合對應隨附 Slack Plugin 的 production install（`extensions/slack/src/setup-shared.ts:10`）：
+
+```json
+{
+  "display_information": {
+    "name": "OpenClaw QA SUT",
+    "description": "OpenClaw QA SUT connector for OpenClaw"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "OpenClaw QA SUT",
+      "always_online": true
+    },
+    "app_home": {
+      "home_tab_enabled": true,
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "app_mentions:read",
+        "assistant:write",
+        "channels:history",
+        "channels:read",
+        "chat:write",
+        "commands",
+        "emoji:read",
+        "files:read",
+        "files:write",
+        "groups:history",
+        "groups:read",
+        "im:history",
+        "im:read",
+        "im:write",
+        "mpim:history",
+        "mpim:read",
+        "mpim:write",
+        "pins:read",
+        "pins:write",
+        "reactions:read",
+        "reactions:write",
+        "usergroups:read",
+        "users:read"
+      ]
+    }
+  },
+  "settings": {
+    "socket_mode_enabled": true,
+    "event_subscriptions": {
+      "bot_events": [
+        "app_home_opened",
+        "app_mention",
+        "channel_rename",
+        "member_joined_channel",
+        "member_left_channel",
+        "message.channels",
+        "message.groups",
+        "message.im",
+        "message.mpim",
+        "pin_added",
+        "pin_removed",
+        "reaction_added",
+        "reaction_removed"
+      ]
+    }
+  }
+}
+```
+
+Slack 建立 app 後，請在其 settings page 上執行兩件事：
+
+- _Install to Workspace_ → 複製 _Bot User OAuth Token_ → 這會成為 `sutBotToken`。
+- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → 新增 scope `connections:write` → 儲存 → 複製 `xapp-...` 值 → 這會成為 `sutAppToken`。
+
+透過對每個 token 呼叫 `auth.test`，驗證兩個 bot 具有不同的使用者 ID。runtime 會依使用者 ID 區分 driver 與 SUT；重複使用同一個 app 會讓提及閘控立即失敗。
+
+**3. 建立頻道**
+
+在 QA 工作區中建立一個頻道（例如 `#openclaw-qa`），並從頻道內邀請兩個 bot：
+
+```
+/invite @OpenClaw QA Driver
+/invite @OpenClaw QA SUT
+```
+
+從 _channel info → About → Channel ID_ 複製 `Cxxxxxxxxxx` ID，那會成為 `channelId`。公開頻道可用；如果使用私人頻道，兩個 app 已經都有 `groups:history`，因此測試框架的歷史讀取仍會成功。
+
+**4. 註冊憑證**
+
+有兩種選項。單機除錯時使用環境變數（設定四個 `OPENCLAW_QA_SLACK_*` 變數並傳入 `--credential-source env`），或植入共用的 Convex 集區，讓 CI 和其他維護者可以租用。
+
+對於 Convex 集區，將四個欄位寫入 JSON 檔案：
+
+```json
+{
+  "channelId": "Cxxxxxxxxxx",
+  "driverBotToken": "xoxb-...",
+  "sutBotToken": "xoxb-...",
+  "sutAppToken": "xapp-..."
+}
+```
+
+在你的 shell 中匯出 `OPENCLAW_QA_CONVEX_SITE_URL` 和 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 後，註冊並驗證：
+
+```bash
+pnpm openclaw qa credentials add \
+  --kind slack \
+  --payload-file slack-creds.json \
+  --note "QA Slack pool seed"
+
+pnpm openclaw qa credentials list --kind slack --status all --json
+```
+
+預期 `count: 1`、`status: "active"`，且沒有 `lease` 欄位。
+
+**5. 端對端驗證**
+
+在本機執行該通道，確認兩個 bot 可透過 broker 彼此通訊：
+
+```bash
+pnpm openclaw qa slack \
+  --credential-source convex \
+  --credential-role maintainer \
+  --output-dir .artifacts/qa-e2e/slack-local
+```
+
+綠燈執行會在遠少於 30 秒內完成，且 `slack-qa-report.md` 會顯示 `slack-canary` 和 `slack-mention-gating` 的狀態皆為 `pass`。如果通道停滯約 90 秒後以 `Convex credential pool exhausted for kind "slack"` 結束，表示集區為空，或每一列都已被租用；`qa credentials list --kind slack --status all --json` 會告訴你是哪一種情況。
+
+### Convex 憑證集區
+
+Telegram、Discord 和 Slack 通道可以從共用 Convex 集區租用憑證，而不是讀取上述環境變數。傳入 `--credential-source convex`（或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 會取得專屬租約，在執行期間送出 Heartbeat，並在關閉時釋放。集區種類為 `"telegram"`、`"discord"` 和 `"slack"`。
+
+broker 會在 `admin/add` 驗證的 payload 形狀：
+
+- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }`，`groupId` 必須是數字 chat-id 字串。
 - Discord（`kind: "discord"`）：`{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`。
+- Slack（`kind: "slack"`）：`{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }`，`channelId` 必須符合 `^[A-Z][A-Z0-9]+$`（例如 `Cxxxxxxxxxx` 的 Slack ID）。請參閱[設定 Slack 工作區](#setting-up-the-slack-workspace)，了解 app 與 scope 佈建。
 
-Operational env vars 和 Convex broker endpoint contract 位於 [Testing → Shared Telegram credentials via Convex](/zh-TW/help/testing#shared-telegram-credentials-via-convex-v1)（此章節名稱早於 Discord 支援；兩種 kinds 的 broker semantics 相同）。
+操作用環境變數與 Convex broker 端點合約位於[測試 → 透過 Convex 共用 Telegram 憑證](/zh-TW/help/testing#shared-telegram-credentials-via-convex-v1)（該章節名稱早於 Discord 支援；兩種種類的 broker 語意相同）。
 
-## Repo-backed seeds
+## repo 支援的種子
 
-Seed assets 位於 `qa/`：
+種子資產位於 `qa/`：
 
 - `qa/scenarios/index.md`
 - `qa/scenarios/<theme>/*.md`
 
-這些內容刻意放在 git 中，讓 QA plan 對人類和 agent 都可見。
+這些內容刻意放在 git 中，讓 QA 計畫可供人類與 agent 查看。
 
-`qa-lab` 應維持為通用 markdown runner。每個 scenario markdown file 都是一個 test run 的真實來源，並應定義：
+`qa-lab` 應維持為通用 Markdown 執行器。每個情境 Markdown 檔案都是一次測試執行的事實來源，並應定義：
 
-- scenario metadata
-- 可選的 category、capability、lane 和 risk metadata
-- docs 和 code refs
-- 可選的 plugin requirements
-- 可選的 gateway config patch
+- 情境中繼資料
+- 選用的類別、能力、通道與風險中繼資料
+- 文件與程式碼參照
+- 選用 Plugin 需求
+- 選用 Gateway 設定補丁
 - 可執行的 `qa-flow`
 
-支援 `qa-flow` 的可重用 runtime surface 可保持通用且跨領域。例如，markdown scenarios 可以結合 transport-side helpers 與 browser-side helpers，透過 Gateway `browser.request` seam 驅動嵌入式 Control UI，而不需要新增特殊案例 runner。
+支援 `qa-flow` 的可重用 runtime 介面可以維持通用且橫切。例如，Markdown 情境可以結合傳輸端 helper 與瀏覽器端 helper，透過 Gateway `browser.request` seam 驅動嵌入式 Control UI，而不需要加入特殊案例 runner。
 
-Scenario files 應依 product capability 分組，而不是依 source tree folder 分組。移動檔案時請保持 scenario IDs 穩定；使用 `docsRefs` 和 `codeRefs` 來追蹤實作。
+情境檔案應依產品能力分組，而不是依原始碼樹資料夾分組。檔案移動時請保持情境 ID 穩定；使用 `docsRefs` 和 `codeRefs` 追蹤實作。
 
-Baseline list 應維持足夠廣泛，以涵蓋：
+基準清單應保持足夠廣泛，以涵蓋：
 
-- DM 和 channel chat
-- thread behavior
-- message action lifecycle
-- Cron callbacks
-- memory recall
-- model switching
-- subagent handoff
-- repo-reading 和 docs-reading
-- 一個小型 build task，例如 Lobster Invaders
+- DM 和頻道聊天
+- thread 行為
+- 訊息動作生命週期
+- cron 回呼
+- 記憶回想
+- 模型切換
+- subagent 交接
+- repo 讀取與文件讀取
+- 一個小型建置任務，例如 Lobster Invaders
 
-## Provider mock lanes
+## Provider 模擬通道
 
-`qa suite` 有兩個本機 provider mock lanes：
+`qa suite` 有兩個本機 provider 模擬通道：
 
-- `mock-openai` 是 scenario-aware OpenClaw mock。它仍是 repo-backed QA 和 parity gates 的預設 deterministic mock lane。
-- `aimock` 會啟動 AIMock-backed provider server，用於實驗性 protocol、fixture、record/replay 和 chaos coverage。它是附加項目，並不取代 `mock-openai` scenario dispatcher。
+- `mock-openai` 是情境感知的 OpenClaw 模擬。它仍是 repo 支援 QA 與 parity gate 的預設確定性模擬通道。
+- `aimock` 會啟動 AIMock 支援的 provider 伺服器，用於實驗性 protocol、fixture、record/replay 與 chaos 覆蓋。它是加成項目，不會取代 `mock-openai` 情境 dispatcher。
 
-Provider-lane implementation 位於 `extensions/qa-lab/src/providers/` 底下。每個 provider 都擁有自己的 defaults、local server startup、gateway model config、auth-profile staging needs，以及 live/mock capability flags。Shared suite 和 gateway code 應透過 provider registry 路由，而不是依 provider names 分支。
+Provider 通道實作位於 `extensions/qa-lab/src/providers/`。每個 provider 都擁有自己的預設值、本機伺服器啟動、Gateway 模型設定、auth-profile staging 需求，以及 live/mock 能力旗標。共用 suite 與 Gateway 程式碼應透過 provider registry 路由，而不是依 provider 名稱分支。
 
-## Transport adapters
+## 傳輸配接器
 
-`qa-lab` 為 markdown QA scenarios 擁有通用 transport seam。`qa-channel` 是該 seam 上的第一個 adapter，但設計目標更廣：未來的真實或 synthetic channels 應接入同一個 suite runner，而不是新增 transport-specific QA runner。
+`qa-lab` 為 Markdown QA 情境擁有通用傳輸 seam。`qa-channel` 是該 seam 上的第一個配接器，但設計目標更廣：未來的真實或合成頻道應接入同一個 suite runner，而不是新增傳輸專用 QA runner。
 
 在架構層級，分工如下：
 
-- `qa-lab` 擁有 generic scenario execution、worker concurrency、artifact writing 和 reporting。
-- Transport adapter 擁有 gateway config、readiness、inbound and outbound observation、transport actions，以及 normalized transport state。
-- `qa/scenarios/` 底下的 Markdown scenario files 定義 test run；`qa-lab` 提供執行它們的可重用 runtime surface。
+- `qa-lab` 擁有通用情境執行、worker 並行、artifact 寫入與回報。
+- 傳輸配接器擁有 Gateway 設定、就緒狀態、入站與出站觀察、傳輸動作，以及正規化傳輸狀態。
+- `qa/scenarios/` 下的 Markdown 情境檔案定義測試執行；`qa-lab` 提供執行它們的可重用 runtime 介面。
 
-### 新增 channel
+### 新增頻道
 
-將 channel 新增到 markdown QA system 只需要兩件事：
+將頻道新增至 Markdown QA 系統只需要兩件事：
 
-1. 該 channel 的 transport adapter。
-2. 驗證 channel contract 的 scenario pack。
+1. 該頻道的傳輸配接器。
+2. 測試頻道合約的情境套件。
 
-當共用 `qa-lab` host 能擁有 flow 時，不要新增新的 top-level QA command root。
+當共用 `qa-lab` host 可以擁有流程時，不要新增新的頂層 QA 命令根。
 
-`qa-lab` 負責共用主機機制：
+`qa-lab` 擁有共用 host 機制：
 
 - `openclaw qa` 命令根
-- 套件啟動與清理
+- suite 啟動與拆除
 - worker 並行
-- 成品寫入
+- artifact 寫入
 - 報告產生
 - 情境執行
 - 舊版 `qa-channel` 情境的相容別名
 
-執行器 Plugin 負責傳輸契約：
+Runner plugin 擁有傳輸合約：
 
 - `openclaw qa <runner>` 如何掛載在共用 `qa` 根底下
-- Gateway 如何針對該傳輸進行設定
+- Gateway 如何針對該傳輸設定
 - 如何檢查就緒狀態
-- 如何注入傳入事件
-- 如何觀察傳出訊息
-- 如何公開逐字稿與正規化傳輸狀態
+- 如何注入入站事件
+- 如何觀察出站訊息
+- 如何公開 transcript 與正規化傳輸狀態
 - 如何執行傳輸支援的動作
-- 如何處理傳輸特定的重設或清理
+- 如何處理傳輸專用 reset 或 cleanup
 
-新通道的最低採用門檻：
+新頻道的最低採用門檻：
 
-1. 讓 `qa-lab` 繼續作為共用 `qa` 根的擁有者。
-2. 在共用 `qa-lab` 主機銜接面上實作傳輸執行器。
-3. 將傳輸特定機制保留在執行器 Plugin 或通道 harness 內。
-4. 將執行器掛載為 `openclaw qa <runner>`，而不是註冊競爭性的根命令。執行器 Plugin 應在 `openclaw.plugin.json` 中宣告 `qaRunners`，並從 `runtime-api.ts` 匯出相符的 `qaRunnerCliRegistrations` 陣列。保持 `runtime-api.ts` 輕量；延遲 CLI 和執行器執行應留在獨立進入點後面。
-5. 在主題式 `qa/scenarios/` 目錄下撰寫或改寫 Markdown 情境。
-6. 新情境使用通用情境 helper。
-7. 除非 repo 正在進行有意的遷移，否則保持既有相容別名可用。
+1. 保持 `qa-lab` 作為共用 `qa` 根的擁有者。
+2. 在共用 `qa-lab` host seam 上實作傳輸 runner。
+3. 將傳輸專用機制保留在 runner plugin 或頻道測試框架內。
+4. 將 runner 掛載為 `openclaw qa <runner>`，而不是註冊競爭的根命令。Runner plugin 應在 `openclaw.plugin.json` 中宣告 `qaRunners`，並從 `runtime-api.ts` 匯出相符的 `qaRunnerCliRegistrations` 陣列。保持 `runtime-api.ts` 輕量；lazy CLI 與 runner 執行應保留在獨立進入點後方。
+5. 在主題式 `qa/scenarios/` 目錄下撰寫或調整 Markdown 情境。
+6. 對新情境使用通用情境 helper。
+7. 除非 repo 正在進行刻意遷移，否則保持現有相容別名可用。
 
-判斷規則很嚴格：
+決策規則很嚴格：
 
-- 如果行為可以在 `qa-lab` 中一次表達，放在 `qa-lab`。
-- 如果行為依賴單一通道傳輸，保留在該執行器 Plugin 或 Plugin harness 中。
-- 如果某個情境需要一個可供多個通道使用的新能力，加入通用 helper，而不是在 `suite.ts` 中加入通道特定分支。
-- 如果某個行為只對單一傳輸有意義，保持情境為傳輸特定，並在情境契約中明確說明。
+- 如果行為可以在 `qa-lab` 中一次表達，請放在 `qa-lab`。
+- 如果行為取決於單一頻道傳輸，請保留在該 runner plugin 或 Plugin 測試框架中。
+- 如果情境需要一項可供多個頻道使用的新能力，請新增通用 helper，而不是在 `suite.ts` 中加入頻道專用分支。
+- 如果某個行為只對單一傳輸有意義，請保持情境為傳輸專用，並在情境合約中明確表示。
 
 ### 情境 helper 名稱
 
@@ -408,22 +592,21 @@ Provider-lane implementation 位於 `extensions/qa-lab/src/providers/` 底下。
 - `formatTransportTranscript`
 - `resetTransport`
 
-既有情境仍可使用相容別名：`waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus`，但新的情境撰寫應使用通用名稱。這些別名是為了避免一次性遷移，而不是未來的模型。
+現有情境仍可使用相容別名：`waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus`，但撰寫新情境應使用通用名稱。這些別名的存在是為了避免一次性大遷移，而不是未來的模型。
 
-## 報告
+## 回報
 
-`qa-lab` 會從觀察到的 bus 時間軸匯出 Markdown 協定報告。
+`qa-lab` 會從觀察到的 bus 時間軸匯出 Markdown protocol 報告。
 報告應回答：
 
-- 哪些有效
-- 哪些失敗
-- 哪些仍受阻
-- 哪些後續情境值得加入
+- 哪些項目正常運作
+- 哪些項目失敗
+- 哪些項目仍被阻塞
+- 哪些後續情境值得新增
 
-若要查看可用情境清單，這在估算後續工作或接線新傳輸時很有用，請執行 `pnpm openclaw qa coverage`（加入 `--json` 可取得機器可讀輸出）。
+若要查看可用情境清單，用於評估後續工作規模或串接新傳輸，請執行 `pnpm openclaw qa coverage`（加入 `--json` 可取得機器可讀輸出）。
 
-若要進行角色與風格檢查，請在多個即時模型 ref 上執行相同情境，
-並寫出經評審的 Markdown 報告：
+對於角色與風格檢查，請使用多個 live 模型 ref 執行相同情境，並寫出經評審的 Markdown 報告：
 
 ```bash
 pnpm openclaw qa character-eval \
@@ -442,40 +625,40 @@ pnpm openclaw qa character-eval \
   --judge-concurrency 16
 ```
 
-此命令會執行本機 QA Gateway 子行程，而不是 Docker。角色評估
-情境應透過 `SOUL.md` 設定 persona，接著執行一般使用者回合，
-例如聊天、workspace 協助，以及小型檔案任務。不應告知候選模型
-它正在被評估。此命令會保留每份完整逐字稿，記錄基本執行統計，
-接著以 fast mode 要求評審模型在支援時使用 `xhigh` reasoning，
-依自然度、vibe 與幽默感排序各次執行。
-比較 provider 時使用 `--blind-judge-models`：評審提示仍會取得
-每份逐字稿與執行狀態，但候選 ref 會替換為中性標籤，
-例如 `candidate-01`；報告會在解析後將排名對應回真實 ref。
-候選執行預設使用 `high` thinking，GPT-5.5 使用 `medium`，
-支援的舊版 OpenAI eval ref 使用 `xhigh`。使用
+此命令會執行本機 QA Gateway 子程序，而不是 Docker。角色評估
+情境應透過 `SOUL.md` 設定 persona，然後執行一般使用者回合，
+例如聊天、工作區協助和小型檔案任務。不應告知候選模型
+它正在接受評估。此命令會保留每份完整逐字稿，
+記錄基本執行統計，接著以快速模式要求評審模型在支援時使用
+`xhigh` 推理，依自然度、氛圍和幽默感為執行結果排名。
+比較供應商時請使用 `--blind-judge-models`：評審提示仍會取得
+每份逐字稿與執行狀態，但候選參照會替換為中性標籤，
+例如 `candidate-01`；報告會在解析後將排名映射回真實參照。
+候選執行預設使用 `high` 思考，GPT-5.5 使用 `medium`，
+而支援的較舊 OpenAI 評估參照使用 `xhigh`。可使用
 `--model provider/model,thinking=<level>` 內嵌覆寫特定候選。
-`--thinking <level>` 仍會設定全域 fallback，而較舊的
+`--thinking <level>` 仍會設定全域後援，而較舊的
 `--model-thinking <provider/model=level>` 形式會保留以維持相容性。
-OpenAI 候選 ref 預設使用 fast mode，因此在 provider 支援時
-會使用優先處理。當單一候選或評審需要覆寫時，內嵌加入
-`,fast`、`,no-fast` 或 `,fast=false`。只有在想強制所有候選模型
-都啟用 fast mode 時，才傳入 `--fast`。候選與評審耗時會記錄在
-報告中以供基準分析，但評審提示會明確要求不要依速度排名。
-候選與評審模型執行的並行預設皆為 16。當 provider 限制或本機
-Gateway 壓力讓執行結果過於嘈雜時，降低 `--concurrency` 或
+OpenAI 候選參照預設使用快速模式，因此在供應商支援時會使用
+優先處理。當單一候選或評審需要覆寫時，請內嵌加入 `,fast`、
+`,no-fast` 或 `,fast=false`。只有在想要強制每個候選模型都啟用
+快速模式時，才傳入 `--fast`。報告會記錄候選與評審的耗時以供
+基準分析，但評審提示會明確要求不要依速度排名。
+候選與評審模型執行的預設並行數皆為 16。當供應商限制或本機 Gateway
+壓力導致執行過於嘈雜時，請降低 `--concurrency` 或
 `--judge-concurrency`。
-當未傳入候選 `--model` 時，角色評估預設使用
+未傳入候選 `--model` 時，角色評估預設使用
 `openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、
 `anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、
 `moonshot/kimi-k2.5`，以及
 `google/gemini-3.1-pro-preview`。
-當未傳入 `--judge-model` 時，評審預設為
+未傳入 `--judge-model` 時，評審預設使用
 `openai/gpt-5.5,thinking=xhigh,fast` 和
 `anthropic/claude-opus-4-6,thinking=high`。
 
 ## 相關文件
 
-- [矩陣 QA](/zh-TW/concepts/qa-matrix)
-- [QA 通道](/zh-TW/channels/qa-channel)
+- [Matrix QA](/zh-TW/concepts/qa-matrix)
+- [QA Channel](/zh-TW/channels/qa-channel)
 - [測試](/zh-TW/help/testing)
 - [Dashboard](/zh-TW/web/dashboard)

docs/zh-TW/gateway/config-tools.md

@@ -2,20 +2,20 @@
 read_when:
     - 設定 `tools.*` 政策、允許清單或實驗性功能
     - 註冊自訂提供者或覆寫基底 URL
-    - 設定與 OpenAI 相容的自架端點
+    - 設定 OpenAI 相容的自行託管端点
 sidebarTitle: Tools and custom providers
-summary: 工具設定（政策、實驗性切換選項、由提供者支援的工具）與自訂提供者/基底 URL 設定
+summary: 工具設定（政策、實驗性切換項、由供應商支援的工具）與自訂供應商/base-URL 設定
 title: 設定 — 工具與自訂提供者
 x-i18n:
-    generated_at: "2026-05-03T21:32:33Z"
+    generated_at: "2026-05-05T01:45:43Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da
+    source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883
     source_path: gateway/config-tools.md
     workflow: 16
 ---
 
-`tools.*` 設定鍵與自訂 provider / base-URL 設定。如需 agents、channels 和其他頂層設定鍵，請參閱[設定參考](/zh-TW/gateway/configuration-reference)。
+`tools.*` 設定鍵與自訂供應商 / base-URL 設定。若要查看代理程式、頻道和其他頂層設定鍵，請參閱[設定參考](/zh-TW/gateway/configuration-reference)。
 
 ## 工具
 
@@ -24,7 +24,7 @@ x-i18n:
 `tools.profile` 會在 `tools.allow`/`tools.deny` 之前設定基礎允許清單：
 
 <Note>
-本機 onboarding 會在未設定時，將新的本機設定預設為 `tools.profile: "coding"`（既有的明確設定檔會保留）。
+本機初始設定會在未設定時，將新的本機設定預設為 `tools.profile: "coding"`（既有的明確設定檔會保留）。
 </Note>
 
 | 設定檔      | 包含                                                                                                                            |
@@ -38,7 +38,7 @@ x-i18n:
 
 | 群組               | 工具                                                                                                                    |
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime`    | `exec`, `process`, `code_execution`（`bash` 可作為 `exec` 的別名）                                                      |
+| `group:runtime`    | `exec`, `process`, `code_execution`（`bash` 可作為 `exec` 的別名）                                                       |
 | `group:fs`         | `read`, `write`, `edit`, `apply_patch`                                                                                  |
 | `group:sessions`   | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
 | `group:memory`     | `memory_search`, `memory_get`                                                                                           |
@@ -49,11 +49,11 @@ x-i18n:
 | `group:nodes`      | `nodes`                                                                                                                 |
 | `group:agents`     | `agents_list`                                                                                                           |
 | `group:media`      | `image`, `image_generate`, `video_generate`, `tts`                                                                      |
-| `group:openclaw`   | 所有內建工具（不含 provider plugins）                                                                                   |
+| `group:openclaw`   | 所有內建工具（不包含供應商 Plugin）                                                                                     |
 
 ### `tools.allow` / `tools.deny`
 
-全域工具允許/拒絕政策（拒絕優先）。不區分大小寫，支援 `*` 萬用字元。即使 Docker 沙箱關閉也會套用。
+全域工具允許/拒絕政策（拒絕優先）。不區分大小寫，支援 `*` 萬用字元。即使 Docker 沙盒關閉也會套用。
 
 ```json5
 {
@@ -61,7 +61,7 @@ x-i18n:
 }
 ```
 
-`write` 和 `apply_patch` 是不同的工具 ID。`allow: ["write"]` 也會為相容模型啟用 `apply_patch`，但 `deny: ["write"]` 不會拒絕 `apply_patch`。若要封鎖所有檔案變更，請拒絕 `group:fs`，或明確列出每個會變更檔案的工具：
+`write` 和 `apply_patch` 是獨立的工具 ID。`allow: ["write"]` 也會為相容模型啟用 `apply_patch`，但 `deny: ["write"]` 不會拒絕 `apply_patch`。若要封鎖所有檔案變更，請拒絕 `group:fs`，或明確列出每個會變更檔案的工具：
 
 ```json5
 {
@@ -71,7 +71,7 @@ x-i18n:
 
 ### `tools.byProvider`
 
-進一步限制特定 provider 或模型的工具。順序：基礎設定檔 → provider 設定檔 → 允許/拒絕。
+進一步限制特定供應商或模型的工具。順序：基礎設定檔 → 供應商設定檔 → 允許/拒絕。
 
 ```json5
 {
@@ -87,7 +87,7 @@ x-i18n:
 
 ### `tools.elevated`
 
-控制沙箱外的 elevated exec 存取權：
+控制沙盒外的提升權限 exec 存取：
 
 ```json5
 {
@@ -103,9 +103,9 @@ x-i18n:
 }
 ```
 
-- 每個 agent 的覆寫（`agents.list[].tools.elevated`）只能進一步限制。
+- 每個代理程式覆寫（`agents.list[].tools.elevated`）只能進一步限制。
 - `/elevated on|off|ask|full` 會依工作階段儲存狀態；行內指令僅套用於單則訊息。
-- Elevated `exec` 會繞過沙箱，並使用已設定的逸出路徑（預設為 `gateway`，或當 exec 目標為 `node` 時使用 `node`）。
+- 提升權限的 `exec` 會繞過沙盒，並使用設定的逸出路徑（預設為 `gateway`，或在 exec 目標是 `node` 時使用 `node`）。
 
 ### `tools.exec`
 
@@ -129,7 +129,7 @@ x-i18n:
 
 ### `tools.loopDetection`
 
-工具迴圈安全檢查**預設為停用**。設定 `enabled: true` 以啟用偵測。設定可在 `tools.loopDetection` 中全域定義，並在每個 agent 的 `agents.list[].tools.loopDetection` 覆寫。
+工具迴圈安全檢查**預設停用**。設定 `enabled: true` 可啟用偵測。設定可在 `tools.loopDetection` 中全域定義，並可於 `agents.list[].tools.loopDetection` 針對每個代理程式覆寫。
 
 ```json5
 {
@@ -151,22 +151,22 @@ x-i18n:
 ```
 
 <ParamField path="historySize" type="number">
-  保留用於迴圈分析的最大工具呼叫歷史。
+  保留用於迴圈分析的最大工具呼叫記錄。
 </ParamField>
 <ParamField path="warningThreshold" type="number">
-  發出警告的重複無進展模式閾值。
+  重複無進展模式的警告閾值。
 </ParamField>
 <ParamField path="criticalThreshold" type="number">
-  封鎖嚴重迴圈的較高重複閾值。
+  用於封鎖嚴重迴圈的較高重複閾值。
 </ParamField>
 <ParamField path="globalCircuitBreakerThreshold" type="number">
-  任何無進展執行的硬停止閾值。
+  任何無進展執行的硬性停止閾值。
 </ParamField>
 <ParamField path="detectors.genericRepeat" type="boolean">
-  對重複的相同工具/相同參數呼叫發出警告。
+  對重複的相同工具/相同引數呼叫發出警告。
 </ParamField>
 <ParamField path="detectors.knownPollNoProgress" type="boolean">
-  對已知輪詢工具（`process.poll`、`command_status` 等）的情況發出警告/封鎖。
+  對已知輪詢工具（`process.poll`、`command_status` 等）發出警告/封鎖。
 </ParamField>
 <ParamField path="detectors.pingPong" type="boolean">
   對交替無進展的成對模式發出警告/封鎖。
@@ -208,7 +208,7 @@ x-i18n:
 
 ### `tools.media`
 
-設定傳入媒體理解（影像/音訊/影片）：
+設定傳入媒體理解（圖片/音訊/影片）：
 
 ```json5
 {
@@ -216,7 +216,7 @@ x-i18n:
     media: {
       concurrency: 2,
       asyncCompletion: {
-        directSend: false, // opt-in: send finished async video directly to the channel
+        directSend: false, // deprecated: completions stay agent-mediated
       },
       audio: {
         enabled: true,
@@ -246,30 +246,30 @@ x-i18n:
 ```
 
 <AccordionGroup>
-  <Accordion title="媒體模型項目欄位">
-    **提供者項目**（`type: "provider"` 或省略）：
+  <Accordion title="Media model entry fields">
+    **供應商項目**（`type: "provider"` 或省略）：
 
-    - `provider`：API 提供者 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等）
-    - `model`：模型 id 覆寫
+    - `provider`：API 供應商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等）
+    - `model`：模型 ID 覆寫
     - `profile` / `preferredProfile`：`auth-profiles.json` 設定檔選擇
 
     **CLI 項目**（`type: "cli"`）：
 
     - `command`：要執行的可執行檔
-    - `args`：範本化引數（支援 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等；`openclaw doctor --fix` 會將已淘汰的 `{input}` placeholder 遷移至 `{{MediaPath}}`）
+    - `args`：範本化引數（支援 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等；`openclaw doctor --fix` 會將已淘汰的 `{input}` 預留位置遷移到 `{{MediaPath}}`）
 
     **通用欄位：**
 
-    - `capabilities`：選用清單（`image`、`audio`、`video`）。預設值：`openai`/`anthropic`/`minimax` → 影像，`google` → 影像+音訊+影片，`groq` → 音訊。
-    - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每個項目的覆寫值。
-    - `tools.media.image.timeoutSeconds` 和相符影像模型的 `timeoutSeconds` 項目，也會在代理呼叫明確的 `image` 工具時套用。
-    - 失敗時會回退到下一個項目。
+    - `capabilities`：選用清單（`image`、`audio`、`video`）。預設值：`openai`/`anthropic`/`minimax` → 圖片，`google` → 圖片+音訊+影片，`groq` → 音訊。
+    - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：逐項目覆寫。
+    - 當代理呼叫明確的 `image` 工具時，`tools.media.image.timeoutSeconds` 和相符圖片模型的 `timeoutSeconds` 項目也會套用。
+    - 失敗時會退回到下一個項目。
 
-    提供者驗證遵循標準順序：`auth-profiles.json` → env vars → `models.providers.*.apiKey`。
+    供應商驗證會依照標準順序：`auth-profiles.json` → 環境變數 → `models.providers.*.apiKey`。
 
     **非同步完成欄位：**
 
-    - `asyncCompletion.directSend`：當為 `true` 時，支援直接完成交付的已完成非同步媒體工作，會先嘗試直接 channel 交付。預設值：`false`（requester-session 喚醒/模型交付路徑）。目前這會套用至非同步 `video_generate`；即使啟用此項，非同步 `music_generate` 完成仍會透過 requester-session 中介。
+    - `asyncCompletion.directSend`：已淘汰的相容性旗標。已完成的非同步媒體任務會維持由請求者工作階段居中處理，讓代理收到結果、決定如何告知使用者，並在來源傳遞需要時使用訊息工具。
 
   </Accordion>
 </AccordionGroup>
@@ -289,9 +289,9 @@ x-i18n:
 
 ### `tools.sessions`
 
-控制哪些 session 可由 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）指定為目標。
+控制哪些工作階段可由工作階段工具（`sessions_list`、`sessions_history`、`sessions_send`）作為目標。
 
-預設值：`tree`（目前 session + 由其產生的 session，例如 subagents）。
+預設值：`tree`（目前工作階段 + 由其衍生的工作階段，例如子代理）。
 
 ```json5
 {
@@ -305,12 +305,12 @@ x-i18n:
 ```
 
 <AccordionGroup>
-  <Accordion title="可見性範圍">
-    - `self`：僅目前的 session key。
-    - `tree`：目前 session + 由目前 session 產生的 session（subagents）。
-    - `agent`：屬於目前 agent id 的任何 session（如果你在同一個 agent id 下執行每個 sender 的 session，可能包含其他使用者）。
-    - `all`：任何 session。跨代理指定目標仍需要 `tools.agentToAgent`。
-    - 沙盒限制：當目前 session 位於沙盒中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 時，即使 `tools.sessions.visibility="all"`，可見性也會被強制為 `tree`。
+  <Accordion title="Visibility scopes">
+    - `self`：僅目前工作階段金鑰。
+    - `tree`：目前工作階段 + 由目前工作階段衍生的工作階段（子代理）。
+    - `agent`：屬於目前代理 ID 的任何工作階段（如果你在同一個代理 ID 下依傳送者執行工作階段，可能包含其他使用者）。
+    - `all`：任何工作階段。跨代理指定目標仍需要 `tools.agentToAgent`。
+    - 沙箱限制：當目前工作階段在沙箱中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 時，即使 `tools.sessions.visibility="all"`，可見性也會強制為 `tree`。
 
   </Accordion>
 </AccordionGroup>
@@ -336,13 +336,13 @@ x-i18n:
 ```
 
 <AccordionGroup>
-  <Accordion title="Attachment notes">
-    - 附件僅支援 `runtime: "subagent"`。ACP runtime 會拒絕附件。
-    - 檔案會實體化到子工作區的 `.openclaw/attachments/<uuid>/`，並包含 `.manifest.json`。
-    - 附件內容會自動從逐字稿持久化中遮蔽。
-    - Base64 輸入會以嚴格的字母表/填充檢查和解碼前大小防護進行驗證。
-    - 檔案權限為：目錄 `0700`，檔案 `0600`。
-    - 清理會遵循 `cleanup` 政策：`delete` 一律移除附件；`keep` 只有在 `retainOnSessionKeep: true` 時才保留附件。
+  <Accordion title="附件注意事項">
+    - 附件僅支援 `runtime: "subagent"`。ACP 執行階段會拒絕它們。
+    - 檔案會具體化到子工作區的 `.openclaw/attachments/<uuid>/`，並帶有 `.manifest.json`。
+    - 附件內容會自動從轉錄持久化中遮蔽。
+    - Base64 輸入會使用嚴格的字母表/填充檢查，以及解碼前大小保護進行驗證。
+    - 目錄的檔案權限為 `0700`，檔案的權限為 `0600`。
+    - 清理會遵循 `cleanup` 政策：`delete` 一律移除附件；`keep` 只會在 `retainOnSessionKeep: true` 時保留附件。
 
   </Accordion>
 </AccordionGroup>
@@ -364,8 +364,8 @@ x-i18n:
 ```
 
 - `planTool`：為非瑣碎的多步驟工作追蹤啟用結構化 `update_plan` 工具。
-- 預設：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每個代理的覆寫）針對 OpenAI 或 OpenAI Codex GPT-5 系列執行設定為 `"strict-agentic"`。設定為 `true` 可在該範圍之外強制啟用工具，或設定為 `false` 即使在嚴格代理式 GPT-5 執行中也保持關閉。
-- 啟用時，系統提示也會加入使用指引，讓模型只在實質工作中使用它，並且最多保持一個步驟為 `in_progress`。
+- 預設值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每個代理的覆寫）針對 OpenAI 或 OpenAI Codex GPT-5 系列執行設為 `"strict-agentic"`。設為 `true` 可在該範圍外強制開啟工具，或設為 `false` 即使在嚴格代理式 GPT-5 執行中也保持關閉。
+- 啟用時，系統提示也會加入使用指引，讓模型只在實質工作中使用它，並最多保持一個步驟為 `in_progress`。
 
 ### `agents.defaults.subagents`
 
@@ -386,15 +386,15 @@ x-i18n:
 ```
 
 - `model`：產生的子代理預設模型。若省略，子代理會繼承呼叫者的模型。
-- `allowAgents`：當請求代理未設定自己的 `subagents.allowAgents` 時，`sessions_spawn` 目標代理 ID 的預設允許清單（`["*"]` = 任意；預設：僅相同代理）。
-- `runTimeoutSeconds`：當工具呼叫省略 `runTimeoutSeconds` 時，`sessions_spawn` 的預設逾時（秒）。`0` 表示無逾時。
+- `allowAgents`：當請求代理未設定自己的 `subagents.allowAgents` 時，`sessions_spawn` 的目標代理 ID 預設允許清單（`["*"]` = 任何代理；預設：僅相同代理）。
+- `runTimeoutSeconds`：當工具呼叫省略 `runTimeoutSeconds` 時，`sessions_spawn` 的預設逾時（秒）。`0` 表示不逾時。
 - 每個子代理的工具政策：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
 
 ---
 
-## 自訂提供者與基底 URL
+## 自訂提供者與基礎 URL
 
-OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~/.openclaw/agents/<agentId>/agent/models.json` 新增自訂提供者。
+OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~/.openclaw/agents/<agentId>/agent/models.json` 加入自訂提供者。
 
 ```json5
 {
@@ -424,84 +424,84 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
 ```
 
 <AccordionGroup>
-  <Accordion title="Auth and merge precedence">
+  <Accordion title="驗證與合併優先順序">
     - 對自訂驗證需求使用 `authHeader: true` + `headers`。
-    - 使用 `OPENCLAW_AGENT_DIR` 覆寫代理設定根目錄（或 `PI_CODING_AGENT_DIR`，這是舊版環境變數別名）。
-    - 符合提供者 ID 的合併優先順序：
+    - 使用 `OPENCLAW_AGENT_DIR`（或舊版環境變數別名 `PI_CODING_AGENT_DIR`）覆寫代理設定根目錄。
+    - 相符提供者 ID 的合併優先順序：
       - 非空的代理 `models.json` `baseUrl` 值優先。
-      - 非空的代理 `apiKey` 值僅在目前設定/驗證設定檔情境中該提供者不是由 SecretRef 管理時優先。
-      - SecretRef 管理的提供者 `apiKey` 值會從來源標記重新整理（環境變數參照為 `ENV_VAR_NAME`，檔案/執行參照為 `secretref-managed`），而不是持久化已解析的祕密。
-      - SecretRef 管理的提供者標頭值會從來源標記重新整理（環境變數參照為 `secretref-env:ENV_VAR_NAME`，檔案/執行參照為 `secretref-managed`）。
+      - 非空的代理 `apiKey` 值僅在該提供者於目前設定/驗證設定檔內容中未由 SecretRef 管理時優先。
+      - 由 SecretRef 管理的提供者 `apiKey` 值會從來源標記重新整理（環境參照為 `ENV_VAR_NAME`，檔案/exec 參照為 `secretref-managed`），而不是持久化已解析的秘密。
+      - 由 SecretRef 管理的提供者標頭值會從來源標記重新整理（環境參照為 `secretref-env:ENV_VAR_NAME`，檔案/exec 參照為 `secretref-managed`）。
       - 空白或缺少的代理 `apiKey`/`baseUrl` 會回退到設定中的 `models.providers`。
-      - 符合模型的 `contextWindow`/`maxTokens` 會使用明確設定與隱含目錄值之間較高的值。
-      - 符合模型的 `contextTokens` 會在存在時保留明確的 runtime 上限；可用它限制有效情境，而不變更原生模型中繼資料。
-      - 若希望設定完整重寫 `models.json`，請使用 `models.mode: "replace"`。
-      - 標記持久化以來源為準：標記會從作用中的來源設定快照（解析前）寫入，而不是從已解析的 runtime 祕密值寫入。
+      - 相符模型的 `contextWindow`/`maxTokens` 會使用明確設定與隱含目錄值之間較高的值。
+      - 相符模型的 `contextTokens` 會在存在時保留明確的執行階段上限；使用它來限制有效內容，而不變更原生模型中繼資料。
+      - 當你想讓設定完整重寫 `models.json` 時，使用 `models.mode: "replace"`。
+      - 標記持久化以來源為權威：標記會從作用中的來源設定快照（解析前）寫入，而不是從已解析的執行階段秘密值寫入。
 
   </Accordion>
 </AccordionGroup>
 
-### 提供者欄位詳細資訊
+### 提供者欄位詳細資料
 
 <AccordionGroup>
-  <Accordion title="Top-level catalog">
+  <Accordion title="頂層目錄">
     - `models.mode`：提供者目錄行為（`merge` 或 `replace`）。
-    - `models.providers`：以提供者 ID 為鍵的自訂提供者對映。
-      - 安全編輯：使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` 進行增量更新。除非傳入 `--replace`，否則 `config set` 會拒絕破壞性替換。
+    - `models.providers`：以提供者 ID 為鍵的自訂提供者對應。
+      - 安全編輯：使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` 進行附加更新。除非你傳入 `--replace`，否則 `config set` 會拒絕破壞性替換。
 
   </Accordion>
-  <Accordion title="Provider connection and auth">
-    - `models.providers.*.api`：請求配接器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。對於自託管的 `/v1/chat/completions` 後端，例如 MLX、vLLM、SGLang，以及多數 OpenAI 相容的本機伺服器，請使用 `openai-completions`。含有 `baseUrl` 但沒有 `api` 的自訂提供者預設為 `openai-completions`；只有在後端支援 `/v1/responses` 時才設定 `openai-responses`。
-    - `models.providers.*.apiKey`：提供者憑證（偏好 SecretRef/環境變數替換）。
+  <Accordion title="提供者連線與驗證">
+    - `models.providers.*.api`：請求配接器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。對於 MLX、vLLM、SGLang 和大多數 OpenAI 相容本機伺服器等自託管 `/v1/chat/completions` 後端，使用 `openai-completions`。帶有 `baseUrl` 但沒有 `api` 的自訂提供者預設為 `openai-completions`；只有在後端支援 `/v1/responses` 時才設定 `openai-responses`。
+    - `models.providers.*.apiKey`：提供者憑證（偏好 SecretRef/env 替換）。
     - `models.providers.*.auth`：驗證策略（`api-key`、`token`、`oauth`、`aws-sdk`）。
-    - `models.providers.*.contextWindow`：當模型項目未設定 `contextWindow` 時，此提供者下模型的預設原生情境視窗。
-    - `models.providers.*.contextTokens`：當模型項目未設定 `contextTokens` 時，此提供者下模型的預設有效 runtime 情境上限。
+    - `models.providers.*.contextWindow`：當模型項目未設定 `contextWindow` 時，此提供者下模型的預設原生內容窗口。
+    - `models.providers.*.contextTokens`：當模型項目未設定 `contextTokens` 時，此提供者下模型的預設有效執行階段內容上限。
     - `models.providers.*.maxTokens`：當模型項目未設定 `maxTokens` 時，此提供者下模型的預設輸出權杖上限。
-    - `models.providers.*.timeoutSeconds`：選用的每提供者模型 HTTP 請求逾時秒數，包含連線、標頭、主體與總請求中止處理。
+    - `models.providers.*.timeoutSeconds`：選用的每個提供者模型 HTTP 請求逾時秒數，包含連線、標頭、本文與總請求中止處理。
     - `models.providers.*.injectNumCtxForOpenAICompat`：對 Ollama + `openai-completions`，將 `options.num_ctx` 注入請求（預設：`true`）。
-    - `models.providers.*.authHeader`：需要時強制透過 `Authorization` 標頭傳輸憑證。
-    - `models.providers.*.baseUrl`：上游 API 基底 URL。
+    - `models.providers.*.authHeader`：在需要時強制透過 `Authorization` 標頭傳輸憑證。
+    - `models.providers.*.baseUrl`：上游 API 基礎 URL。
     - `models.providers.*.headers`：用於代理/租戶路由的額外靜態標頭。
 
   </Accordion>
-  <Accordion title="Request transport overrides">
+  <Accordion title="請求傳輸覆寫">
     `models.providers.*.request`：模型提供者 HTTP 請求的傳輸覆寫。
 
     - `request.headers`：額外標頭（與提供者預設值合併）。值接受 SecretRef。
-    - `request.auth`：驗證策略覆寫。模式：`"provider-default"`（使用提供者內建驗證）、`"authorization-bearer"`（搭配 `token`）、`"header"`（搭配 `headerName`、`value`、選用 `prefix`）。
+    - `request.auth`：驗證策略覆寫。模式：`"provider-default"`（使用提供者的內建驗證）、`"authorization-bearer"`（搭配 `token`）、`"header"`（搭配 `headerName`、`value`、選用的 `prefix`）。
     - `request.proxy`：HTTP 代理覆寫。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 環境變數）、`"explicit-proxy"`（搭配 `url`）。兩種模式都接受選用的 `tls` 子物件。
     - `request.tls`：直接連線的 TLS 覆寫。欄位：`ca`、`cert`、`key`、`passphrase`（全部接受 SecretRef）、`serverName`、`insecureSkipVerify`。
-    - `request.allowPrivateNetwork`：設為 `true` 時，當 DNS 解析到私有、CGNAT 或類似範圍，允許透過提供者 HTTP 擷取防護對 `baseUrl` 使用 HTTPS（操作員為受信任的自託管 OpenAI 相容端點選擇加入）。local loopback 模型提供者串流 URL，例如 `localhost`、`127.0.0.1` 與 `[::1]`，除非明確設為 `false`，否則會自動允許；LAN、tailnet 與私有 DNS 主機仍需選擇加入。WebSocket 對標頭/TLS 使用相同的 `request`，但不使用該擷取 SSRF 閘門。預設為 `false`。
+    - `request.allowPrivateNetwork`：為 `true` 時，當 DNS 解析到私有、CGNAT 或類似範圍時，允許透過提供者 HTTP 擷取保護對 `baseUrl` 使用 HTTPS（營運者針對受信任自託管 OpenAI 相容端點的選擇加入）。`localhost`、`127.0.0.1` 和 `[::1]` 等回送模型提供者串流 URL 會自動允許，除非明確設為 `false`；LAN、tailnet 和私有 DNS 主機仍需選擇加入。WebSocket 對標頭/TLS 使用相同的 `request`，但不使用該擷取 SSRF 閘門。預設 `false`。
 
   </Accordion>
-  <Accordion title="Model catalog entries">
+  <Accordion title="模型目錄項目">
     - `models.providers.*.models`：明確的提供者模型目錄項目。
-    - `models.providers.*.models.*.input`：模型輸入模態。文字專用模型使用 `["text"]`，原生圖片/視覺模型使用 `["text", "image"]`。只有在所選模型標記為支援圖片時，圖片附件才會注入代理回合。
-    - `models.providers.*.models.*.contextWindow`：原生模型情境視窗中繼資料。這會覆寫該模型的提供者層級 `contextWindow`。
-    - `models.providers.*.models.*.contextTokens`：選用 runtime 情境上限。這會覆寫提供者層級 `contextTokens`；當你希望有效情境預算小於模型原生 `contextWindow` 時使用；`openclaw models list` 會在兩個值不同時顯示兩者。
-    - `models.providers.*.models.*.compat.supportsDeveloperRole`：選用相容性提示。對於 `api: "openai-completions"` 且具有非空非原生 `baseUrl`（主機不是 `api.openai.com`）的情況，OpenClaw 會在 runtime 強制將其設為 `false`。空白/省略的 `baseUrl` 會保留預設 OpenAI 行為。
-    - `models.providers.*.models.*.compat.requiresStringContent`：針對僅支援字串的 OpenAI 相容聊天端點的選用相容性提示。為 `true` 時，OpenClaw 會在送出請求前，將純文字 `messages[].content` 陣列攤平成純字串。
+    - `models.providers.*.models.*.input`：模型輸入模態。純文字模型使用 `["text"]`，原生圖片/視覺模型使用 `["text", "image"]`。只有在所選模型標記為支援圖片時，圖片附件才會注入代理輪次。
+    - `models.providers.*.models.*.contextWindow`：原生模型內容窗口中繼資料。這會覆寫該模型的提供者層級 `contextWindow`。
+    - `models.providers.*.models.*.contextTokens`：選用的執行階段內容上限。這會覆寫提供者層級的 `contextTokens`；當你想要比模型原生 `contextWindow` 更小的有效內容預算時使用它；`openclaw models list` 會在兩個值不同時顯示兩者。
+    - `models.providers.*.models.*.compat.supportsDeveloperRole`：選用的相容性提示。對於 `api: "openai-completions"` 且帶有非空、非原生 `baseUrl`（主機不是 `api.openai.com`）時，OpenClaw 會在執行階段強制將其設為 `false`。空白/省略的 `baseUrl` 會保留預設 OpenAI 行為。
+    - `models.providers.*.models.*.compat.requiresStringContent`：針對僅支援字串的 OpenAI 相容聊天端點的選用相容性提示。為 `true` 時，OpenClaw 會在傳送請求前，將純文字 `messages[].content` 陣列攤平成一般字串。
 
   </Accordion>
-  <Accordion title="Amazon Bedrock discovery">
-    - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自動探索設定根。
+  <Accordion title="Amazon Bedrock 探索">
+    - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自動探索設定根目錄。
     - `plugins.entries.amazon-bedrock.config.discovery.enabled`：開啟/關閉隱含探索。
-    - `plugins.entries.amazon-bedrock.config.discovery.region`：探索使用的 AWS 區域。
-    - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用於定向探索的選用提供者 ID 篩選器。
+    - `plugins.entries.amazon-bedrock.config.discovery.region`：用於探索的 AWS 區域。
+    - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用於目標探索的選用提供者 ID 篩選器。
     - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：探索重新整理的輪詢間隔。
-    - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已探索模型的後援情境視窗。
+    - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已探索模型的後援內容窗口。
     - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已探索模型的後援最大輸出權杖數。
 
   </Accordion>
 </AccordionGroup>
 
-互動式自訂提供者導引會針對常見視覺模型 ID 推斷圖片輸入，例如 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 與 GLM-4V，並對已知文字專用系列略過額外問題。未知模型 ID 仍會提示詢問圖片支援。非互動式導引使用相同推斷；傳入 `--custom-image-input` 可強制使用支援圖片的中繼資料，或傳入 `--custom-text-input` 可強制使用文字專用中繼資料。
+互動式自訂提供者上線會針對 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V 等常見視覺模型 ID 推斷圖片輸入，並對已知純文字系列略過額外問題。未知模型 ID 仍會提示詢問圖片支援。非互動式上線使用相同推斷；傳入 `--custom-image-input` 可強制使用支援圖片的中繼資料，或傳入 `--custom-text-input` 可強制使用純文字中繼資料。
 
 ### 提供者範例
 
 <AccordionGroup>
-  <Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
-    隨附的 `cerebras` 提供者 Plugin 可透過 `openclaw onboard --auth-choice cerebras-api-key` 設定此項。只有在覆寫預設值時才使用明確的提供者設定。
+  <Accordion title="Cerebras（GLM 4.7 / GPT OSS）">
+    內建的 `cerebras` provider plugin 可透過 `openclaw onboard --auth-choice cerebras-api-key` 設定此項。僅在覆寫預設值時才使用明確提供者設定。
 
     ```json5
     {
@@ -535,10 +535,10 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
     }
     ```
 
-    對 Cerebras 使用 `cerebras/zai-glm-4.7`；對 Z.AI direct 使用 `zai/glm-4.7`。
+    Cerebras 請使用 `cerebras/zai-glm-4.7`；Z.AI 直連請使用 `zai/glm-4.7`。
 
   </Accordion>
-  <Accordion title="Kimi Coding">
+  <Accordion title="Kimi 程式編寫">
     ```json5
     {
       env: { KIMI_API_KEY: "sk-..." },
@@ -554,10 +554,10 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
     Anthropic 相容的內建提供者。捷徑：`openclaw onboard --auth-choice kimi-code-api-key`。
 
   </Accordion>
-  <Accordion title="Local models (LM Studio)">
-    請參閱[本機模型](/zh-TW/gateway/local-models)。簡短說明：在高階硬體上透過 LM Studio Responses API 執行大型本機模型；保留已合併的託管模型作為備援。
+  <Accordion title="本機模型 (LM Studio)">
+    請參閱[本機模型](/zh-TW/gateway/local-models)。摘要：在高階硬體上透過 LM Studio Responses API 執行大型本機模型；保留已合併的託管模型作為備援。
   </Accordion>
-  <Accordion title="MiniMax M2.7 (direct)">
+  <Accordion title="MiniMax M2.7（直連）">
     ```json5
     {
       agents: {
@@ -592,7 +592,7 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
     }
     ```
 
-    設定 `MINIMAX_API_KEY`。捷徑：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目錄預設僅包含 M2.7。在 Anthropic 相容的串流路徑上，除非你明確自行設定 `thinking`，否則 OpenClaw 預設會停用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。
+    設定 `MINIMAX_API_KEY`。捷徑：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目錄預設僅使用 M2.7。在 Anthropic 相容的串流路徑上，除非你明確自行設定 `thinking`，否則 OpenClaw 預設會停用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。
 
   </Accordion>
   <Accordion title="Moonshot AI (Kimi)">
@@ -629,9 +629,9 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
     }
     ```
 
-    若使用中國端點：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。
+    中國端點請使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。
 
-    原生 Moonshot 端點會在共用的 `openai-completions` 傳輸上宣告串流用量相容性，而 OpenClaw 會依據端點能力啟用此行為，而不是只依賴內建提供者 id。
+    原生 Moonshot 端點會在共用的 `openai-completions` 傳輸上宣告串流用量相容性，OpenClaw 會依端點能力判斷，而不只依內建提供者 id。
 
   </Accordion>
   <Accordion title="OpenCode">
@@ -646,10 +646,10 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
     }
     ```
 
-    設定 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目錄使用 `opencode/...` 參照，Go 目錄使用 `opencode-go/...` 參照。捷徑：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。
+    設定 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目錄請使用 `opencode/...` 參照，Go 目錄請使用 `opencode-go/...` 參照。捷徑：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。
 
   </Accordion>
-  <Accordion title="Synthetic (Anthropic-compatible)">
+  <Accordion title="Synthetic（Anthropic 相容）">
     ```json5
     {
       env: { SYNTHETIC_API_KEY: "sk-..." },
@@ -698,11 +698,11 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
     }
     ```
 
-    設定 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的別名。捷徑：`openclaw onboard --auth-choice zai-api-key`。
+    設定 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 是可接受的別名。捷徑：`openclaw onboard --auth-choice zai-api-key`。
 
     - 一般端點：`https://api.z.ai/api/paas/v4`
-    - 程式碼端點（預設）：`https://api.z.ai/api/coding/paas/v4`
-    - 若使用一般端點，請定義自訂提供者並覆寫基礎 URL。
+    - 程式編寫端點（預設）：`https://api.z.ai/api/coding/paas/v4`
+    - 若要使用一般端點，請定義含有基礎 URL 覆寫的自訂提供者。
 
   </Accordion>
 </AccordionGroup>
@@ -714,4 +714,4 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~
 - [設定 — agents](/zh-TW/gateway/config-agents)
 - [設定 — channels](/zh-TW/gateway/config-channels)
 - [設定參考](/zh-TW/gateway/configuration-reference) — 其他頂層鍵
-- [工具與 plugins](/zh-TW/tools)
+- [工具和 plugins](/zh-TW/tools)

docs/zh-TW/gateway/configuration-reference.md

@@ -2,70 +2,62 @@
 read_when:
     - 你需要精確的欄位層級設定語意或預設值
     - 您正在驗證通道、模型、Gateway 或工具設定區塊
-summary: Gateway 設定參考，涵蓋核心 OpenClaw 金鑰、預設值，以及指向專用子系統參考的連結
+summary: Gateway 設定參考，涵蓋核心 OpenClaw 設定鍵、預設值，以及專用子系統參考資料的連結
 title: 設定參考
 x-i18n:
-    generated_at: "2026-05-03T21:32:27Z"
+    generated_at: "2026-05-05T01:45:59Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9
+    source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684
     source_path: gateway/configuration-reference.md
     workflow: 16
 ---
 
-核心設定參考，適用於 `~/.openclaw/openclaw.json`。如需任務導向的概覽，請參閱[設定](/zh-TW/gateway/configuration)。
+`~/.openclaw/openclaw.json` 的核心設定參考。如需以任務為導向的概覽，請參閱[設定](/zh-TW/gateway/configuration)。
 
-涵蓋主要 OpenClaw 設定介面，並在子系統有自己的更深入參考文件時連結出去。頻道與 plugin 擁有的指令目錄，以及深層記憶體/QMD 調整選項，位於各自的頁面，而不是本頁。
+涵蓋主要 OpenClaw 設定介面；若子系統有自己的更深入參考，則連結至該頁。頻道與 plugin 擁有的命令目錄，以及深層記憶體/QMD 調整項，位於各自頁面，而不是本頁。
 
-程式碼真相來源：
+程式碼事實來源：
 
-- `openclaw config schema` 會列印用於驗證與 Control UI 的即時 JSON Schema，並在可用時合併 bundled/plugin/channel 中繼資料
-- `config.schema.lookup` 會回傳一個路徑範圍的 schema 節點，供鑽取工具使用
-- `pnpm config:docs:check` / `pnpm config:docs:gen` 會依據目前的 schema 介面驗證設定文件基準雜湊
+- `openclaw config schema` 會列印用於驗證和 Control UI 的即時 JSON Schema，並在可用時合併內建/plugin/頻道中繼資料
+- `config.schema.lookup` 會傳回一個以路徑為範圍的 schema 節點，供下鑽工具使用
+- `pnpm config:docs:check` / `pnpm config:docs:gen` 會根據目前 schema 介面驗證設定文件基準雜湊
 
-代理查找路徑：編輯前，請使用 `gateway` 工具動作 `config.schema.lookup` 取得精確的欄位層級文件與限制。使用[設定](/zh-TW/gateway/configuration)取得任務導向指引，並使用本頁了解更完整的欄位地圖、預設值，以及子系統參考文件連結。
+代理查詢路徑：編輯前，請使用 `gateway` 工具動作 `config.schema.lookup` 取得精確的欄位層級文件與限制。使用[設定](/zh-TW/gateway/configuration)取得以任務為導向的指引，並使用本頁取得更完整的欄位地圖、預設值，以及子系統參考連結。
 
-專用深入參考：
+專屬深入參考：
 
-- [記憶體設定參考](/zh-TW/reference/memory-config)，適用於 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 設定
-- [斜線指令](/zh-TW/tools/slash-commands)，適用於目前內建 + bundled 指令目錄
-- 擁有頻道專屬指令介面的頻道/plugin 頁面
+- [記憶體設定參考](/zh-TW/reference/memory-config)，涵蓋 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 設定
+- [Slash 命令](/zh-TW/tools/slash-commands)，涵蓋目前內建 + 內建隨附的命令目錄
+- 擁有頻道特定命令介面的頻道/plugin 頁面
 
-設定格式為 **JSON5**（允許註解 + 尾端逗號）。所有欄位皆為選用；省略時 OpenClaw 會使用安全預設值。
+設定格式為 **JSON5**（允許註解 + 結尾逗號）。所有欄位都是選用的；省略時 OpenClaw 會使用安全預設值。
 
 ---
 
 ## 頻道
 
-每個頻道的設定鍵已移至專用頁面；請參閱
-[設定 — 頻道](/zh-TW/gateway/config-channels)了解 `channels.*`，
-包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage，以及其他
-bundled 頻道（驗證、存取控制、多帳號、提及閘控）。
+各頻道設定鍵已移至專屬頁面；請參閱[設定 — 頻道](/zh-TW/gateway/config-channels)以了解 `channels.*`，包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage，以及其他內建隨附頻道（驗證、存取控制、多帳號、提及閘控）。
 
 ## 代理預設值、多代理、工作階段與訊息
 
-已移至專用頁面；請參閱
-[設定 — 代理](/zh-TW/gateway/config-agents)，內容包括：
+已移至專屬頁面；請參閱[設定 — 代理](/zh-TW/gateway/config-agents)，內容包括：
 
-- `agents.defaults.*`（工作區、模型、思考、Heartbeat、記憶體、媒體、skills、沙箱）
+- `agents.defaults.*`（工作區、模型、思考、heartbeat、記憶體、媒體、skills、沙箱）
 - `multiAgent.*`（多代理路由與繫結）
-- `session.*`（工作階段生命週期、Compaction、修剪）
-- `messages.*`（訊息傳遞、TTS、Markdown 轉譯）
+- `session.*`（工作階段生命週期、compaction、修剪）
+- `messages.*`（訊息傳遞、TTS、markdown 算繪）
 - `talk.*`（Talk 模式）
-  - `talk.speechLocale`：iOS/macOS 上 Talk 語音辨識的選用 BCP 47 locale id
+  - `talk.speechLocale`：iOS/macOS 上 Talk 語音辨識的選用 BCP 47 語言環境 ID
   - `talk.silenceTimeoutMs`：未設定時，Talk 會在傳送逐字稿前保留平台預設暫停視窗（`macOS 和 Android 為 700 ms，iOS 為 900 ms`）
 
 ## 工具與自訂供應商
 
-工具政策、實驗性切換、供應商支援的工具設定，以及自訂
-供應商 / base-URL 設定已移至專用頁面；請參閱
-[設定 — 工具與自訂供應商](/zh-TW/gateway/config-tools)。
+工具政策、實驗性切換、供應商支援的工具設定，以及自訂供應商 / base-URL 設定已移至專屬頁面；請參閱[設定 — 工具與自訂供應商](/zh-TW/gateway/config-tools)。
 
 ## 模型
 
-供應商定義、模型 allowlist，以及自訂供應商設定位於
-[設定 — 工具與自訂供應商](/zh-TW/gateway/config-tools#custom-providers-and-base-urls)。
-`models` 根節點也負責全域模型目錄行為。
+供應商定義、模型允許清單，以及自訂供應商設定位於[設定 — 工具與自訂供應商](/zh-TW/gateway/config-tools#custom-providers-and-base-urls)。`models` 根節點也擁有全域模型目錄行為。
 
 ```json5
 {
@@ -77,12 +69,12 @@ bundled 頻道（驗證、存取控制、多帳號、提及閘控）。
 ```
 
 - `models.mode`：供應商目錄行為（`merge` 或 `replace`）。
-- `models.providers`：以供應商 id 作為鍵的自訂供應商 map。
-- `models.pricing.enabled`：控制背景 pricing bootstrap，會在 sidecar 與頻道抵達 Gateway ready path 後啟動。為 `false` 時，Gateway 會略過 OpenRouter 與 LiteLLM pricing-catalog 擷取；已設定的 `models.providers.*.models[].cost` 值仍可用於本機成本估算。
+- `models.providers`：以供應商 ID 為鍵的自訂供應商對應。
+- `models.pricing.enabled`：控制背景定價啟動流程，該流程會在 sidecar 與頻道到達 Gateway ready 路徑後開始。當為 `false` 時，Gateway 會略過 OpenRouter 和 LiteLLM 定價目錄擷取；已設定的 `models.providers.*.models[].cost` 值仍可用於本機成本估算。
 
 ## MCP
 
-OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi 與其他執行階段介面卡使用。`openclaw mcp list`、`show`、`set` 和 `unset` 指令會管理此區塊，而不會在設定編輯期間連線到目標伺服器。
+OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由嵌入式 Pi 與其他執行階段配接器取用。`openclaw mcp list`、`show`、`set` 和 `unset` 命令會管理此區塊，而不會在設定編輯期間連線到目標伺服器。
 
 ```json5
 {
@@ -106,12 +98,11 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 }
 ```
 
-- `mcp.servers`：具名 stdio 或遠端 MCP 伺服器定義，供公開已設定 MCP 工具的執行階段使用。遠端項目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生別名，`openclaw mcp set` 與 `openclaw doctor --fix` 會將其正規化為標準 `transport` 欄位。
-- `mcp.sessionIdleTtlMs`：工作階段範圍 bundled MCP 執行階段的閒置 TTL。一次性內嵌執行會要求在執行結束時清理；此 TTL 是長生命週期工作階段與未來呼叫者的後援機制。
-- `mcp.*` 下的變更會透過處置快取的工作階段 MCP 執行階段來熱套用。下一次工具探索/使用會依新設定重新建立它們，因此移除的 `mcp.servers` 項目會立即被回收，而不是等待閒置 TTL。
+- `mcp.servers`：具名 stdio 或遠端 MCP 伺服器定義，供會公開已設定 MCP 工具的執行階段使用。遠端項目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生別名，`openclaw mcp set` 和 `openclaw doctor --fix` 會將其正規化為標準 `transport` 欄位。
+- `mcp.sessionIdleTtlMs`：工作階段範圍內建隨附 MCP 執行階段的閒置 TTL。一次性嵌入式執行會要求執行結束清理；此 TTL 是長效工作階段與未來呼叫端的後備機制。
+- `mcp.*` 下的變更會透過處置快取的工作階段 MCP 執行階段即時套用。下一次工具探索/使用會根據新設定重新建立它們，因此已移除的 `mcp.servers` 項目會立即回收，而不是等待閒置 TTL。
 
-請參閱 [MCP](/zh-TW/cli/mcp#openclaw-as-an-mcp-client-registry) 和
-[CLI 後端](/zh-TW/gateway/cli-backends#bundle-mcp-overlays)了解執行階段行為。
+請參閱 [MCP](/zh-TW/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 後端](/zh-TW/gateway/cli-backends#bundle-mcp-overlays)以了解執行階段行為。
 
 ## Skills
 
@@ -138,12 +129,12 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 }
 ```
 
-- `allowBundled`：僅適用於 bundled skills 的選用 allowlist（不影響 managed/workspace skills）。
-- `load.extraDirs`：額外的共享 skill 根目錄（最低優先順序）。
-- `install.preferBrew`：為 true 時，如果 `brew` 可用，會優先使用 Homebrew 安裝器，再退回其他安裝器種類。
+- `allowBundled`：內建隨附 skills 的選用允許清單（不影響受管理/工作區 skills）。
+- `load.extraDirs`：額外共享 skill 根目錄（最低優先順序）。
+- `install.preferBrew`：為 true 時，如果 `brew` 可用，會在退回其他安裝器類型前優先使用 Homebrew 安裝器。
 - `install.nodeManager`：`metadata.openclaw.install` 規格的 node 安裝器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
-- `entries.<skillKey>.enabled: false`：即使 skill 是 bundled/installed，也會停用它。
-- `entries.<skillKey>.apiKey`：供宣告主要 env var 的 skills 使用的便利設定（純文字字串或 SecretRef 物件）。
+- `entries.<skillKey>.enabled: false`：即使 skill 是內建隨附/已安裝，也會停用該 skill。
+- `entries.<skillKey>.apiKey`：為宣告主要環境變數的 skills 提供的便利欄位（明文字串或 SecretRef 物件）。
 
 ---
 
@@ -154,6 +145,7 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
   plugins: {
     enabled: true,
     allow: ["voice-call"],
+    bundledDiscovery: "allowlist",
     deny: [],
     load: {
       paths: ["~/Projects/oss/voice-call-plugin"],
@@ -172,40 +164,41 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 ```
 
 - 從 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions`，以及 `plugins.load.paths` 載入。
-- 探索會接受原生 OpenClaw plugins，加上相容的 Codex bundles 與 Claude bundles，包括無 manifest 的 Claude 預設版面 bundles。
+- 探索接受原生 OpenClaw plugins，以及相容的 Codex bundle 和 Claude bundle，包括沒有 manifest 的 Claude 預設版面配置 bundle。
 - **設定變更需要重新啟動 gateway。**
-- `allow`：選用 allowlist（只載入列出的 plugins）。`deny` 優先。
+- `allow`：選用允許清單（只載入列出的 plugins）。`deny` 優先。
+- `bundledDiscovery`：新設定預設為 `"allowlist"`，因此非空的 `plugins.allow` 也會閘控內建隨附供應商 plugins，包括 web-search 執行階段供應商。Doctor 會為遷移的舊版允許清單設定寫入 `"compat"`，以在你選擇加入前保留既有內建隨附供應商行為。
 - `plugins.entries.<id>.apiKey`：plugin 層級 API key 便利欄位（當 plugin 支援時）。
-- `plugins.entries.<id>.env`：plugin 範圍的 env var map。
-- `plugins.entries.<id>.hooks.allowPromptInjection`：為 `false` 時，核心會阻擋 `before_prompt_build`，並忽略 legacy `before_agent_start` 中會改變 prompt 的欄位，同時保留 legacy `modelOverride` 和 `providerOverride`。適用於原生 plugin hooks 與受支援 bundle 提供的 hook 目錄。
-- `plugins.entries.<id>.hooks.allowConversationAccess`：為 `true` 時，受信任的非 bundled plugins 可從型別化 hooks（例如 `llm_input`、`llm_output`、`before_agent_finalize` 與 `agent_end`）讀取原始對話內容。
-- `plugins.entries.<id>.subagent.allowModelOverride`：明確信任此 plugin 可為背景子代理執行要求逐次執行的 `provider` 與 `model` 覆寫。
-- `plugins.entries.<id>.subagent.allowedModels`：受信任子代理覆寫可用的標準 `provider/model` 目標選用 allowlist。只有在你刻意想允許任何模型時才使用 `"*"`。
-- `plugins.entries.<id>.config`：plugin 定義的設定物件（可用時會由原生 OpenClaw plugin schema 驗證）。
-- 頻道 plugin 帳號/執行階段設定位於 `channels.<id>` 下，並應由擁有該項目的 plugin manifest `channelConfigs` 中繼資料描述，而不是由中央 OpenClaw 選項 registry 描述。
+- `plugins.entries.<id>.env`：plugin 範圍的環境變數對應。
+- `plugins.entries.<id>.hooks.allowPromptInjection`：為 `false` 時，核心會封鎖 `before_prompt_build`，並忽略舊版 `before_agent_start` 中會變更提示的欄位，同時保留舊版 `modelOverride` 與 `providerOverride`。適用於原生 plugin hooks 與受支援的 bundle 提供 hook 目錄。
+- `plugins.entries.<id>.hooks.allowConversationAccess`：為 `true` 時，受信任的非內建 plugins 可從型別化 hooks（例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）讀取原始對話內容。
+- `plugins.entries.<id>.subagent.allowModelOverride`：明確信任此 plugin 可為背景 subagent 執行要求每次執行的 `provider` 與 `model` 覆寫。
+- `plugins.entries.<id>.subagent.allowedModels`：受信任 subagent 覆寫可用的標準 `provider/model` 目標選用允許清單。只有在你有意允許任何模型時才使用 `"*"`。
+- `plugins.entries.<id>.config`：plugin 定義的設定物件（當可用時由原生 OpenClaw plugin schema 驗證）。
+- 頻道 plugin 帳號/執行階段設定位於 `channels.<id>` 下，並應由擁有該設定的 plugin manifest `channelConfigs` 中繼資料描述，而不是由中央 OpenClaw 選項登錄描述。
 - `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 供應商設定。
-  - `apiKey`：Firecrawl API key（接受 SecretRef）。會退回使用 `plugins.entries.firecrawl.config.webSearch.apiKey`、legacy `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` env var。
-  - `baseUrl`：Firecrawl API base URL（預設：`https://api.firecrawl.dev`；自架覆寫必須指向 private/internal endpoints）。
+  - `apiKey`：Firecrawl API key（接受 SecretRef）。會退回 `plugins.entries.firecrawl.config.webSearch.apiKey`、舊版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 環境變數。
+  - `baseUrl`：Firecrawl API base URL（預設：`https://api.firecrawl.dev`；自託管覆寫必須指向私人/內部端點）。
   - `onlyMainContent`：只從頁面擷取主要內容（預設：`true`）。
-  - `maxAgeMs`：快取最大時間，單位為毫秒（預設：`172800000` / 2 天）。
-  - `timeoutSeconds`：scrape request timeout，單位為秒（預設：`60`）。
-- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）設定。
+  - `maxAgeMs`：最大快取時間，以毫秒為單位（預設：`172800000` / 2 天）。
+  - `timeoutSeconds`：抓取要求逾時秒數（預設：`60`）。
+- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 網頁搜尋）設定。
   - `enabled`：啟用 X Search 供應商。
   - `model`：用於搜尋的 Grok 模型（例如 `"grok-4-1-fast"`）。
-- `plugins.entries.memory-core.config.dreaming`：記憶體 dreaming 設定。請參閱 [Dreaming](/zh-TW/concepts/dreaming)了解階段與臨界值。
+- `plugins.entries.memory-core.config.dreaming`：記憶體 dreaming 設定。請參閱 [Dreaming](/zh-TW/concepts/dreaming)以了解階段與門檻。
   - `enabled`：dreaming 主開關（預設 `false`）。
-  - `frequency`：每次完整 dreaming sweep 的 cron 節奏（預設為 `"0 3 * * *"`）。
-  - `model`：選用 Dream Diary 子代理模型覆寫。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；搭配 `allowedModels` 限制目標。模型不可用錯誤會使用工作階段預設模型重試一次；信任或 allowlist 失敗不會靜默退回。
-  - 階段政策與臨界值為實作細節（不是面向使用者的設定鍵）。
+  - `frequency`：每次完整 dreaming 掃描的 cron 週期（預設為 `"0 3 * * *"`）。
+  - `model`：選用的 Dream Diary subagent 模型覆寫。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；搭配 `allowedModels` 以限制目標。模型不可用錯誤會以工作階段預設模型重試一次；信任或允許清單失敗不會靜默退回。
+  - 階段政策與門檻屬於實作細節（不是面向使用者的設定鍵）。
 - 完整記憶體設定位於[記憶體設定參考](/zh-TW/reference/memory-config)：
   - `agents.defaults.memorySearch.*`
   - `memory.backend`
   - `memory.citations`
   - `memory.qmd.*`
   - `plugins.entries.memory-core.config.dreaming`
-- 已啟用的 Claude bundle plugins 也可以從 `settings.json` 提供內嵌 Pi 預設值；OpenClaw 會將這些套用為已清理的代理設定，而不是原始 OpenClaw 設定 patch。
-- `plugins.slots.memory`：選擇作用中的記憶體 plugin id，或使用 `"none"` 停用記憶體 plugins。
-- `plugins.slots.contextEngine`：選擇作用中的 context engine plugin id；除非你安裝並選擇另一個 engine，否則預設為 `"legacy"`。
+- 已啟用的 Claude bundle plugins 也可以從 `settings.json` 貢獻嵌入式 Pi 預設值；OpenClaw 會將其套用為已清理的代理設定，而不是原始 OpenClaw 設定修補。
+- `plugins.slots.memory`：選擇作用中的記憶體 plugin ID，或使用 `"none"` 停用記憶體 plugins。
+- `plugins.slots.contextEngine`：選擇作用中的 context engine plugin ID；除非你安裝並選擇其他 engine，否則預設為 `"legacy"`。
 
 請參閱 [Plugins](/zh-TW/tools/plugin)。
 
@@ -213,12 +206,12 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 
 ## 承諾
 
-`commitments` 控制推斷出的後續追蹤記憶體：OpenClaw 可以從對話回合中偵測 check-ins，並透過 heartbeat 執行傳遞它們。
+`commitments` 控制推斷的後續追蹤記憶體：OpenClaw 可以從對話回合偵測 check-in，並透過 heartbeat 執行傳遞它們。
 
-- `commitments.enabled`：啟用隱藏 LLM 擷取、儲存，以及透過 heartbeat 傳遞推斷出的後續追蹤承諾。預設：`false`。
-- `commitments.maxPerDay`：在 rolling day 內，每個代理工作階段傳遞的推斷後續追蹤承諾上限。預設：`3`。
+- `commitments.enabled`：啟用隱藏 LLM 擷取、儲存，以及 heartbeat 傳遞，用於推斷的後續承諾。預設：`false`。
+- `commitments.maxPerDay`：每個代理工作階段在滾動一天內傳遞的推斷後續承諾上限。預設：`3`。
 
-請參閱[推斷承諾](/zh-TW/concepts/commitments)。
+請參閱[推斷的承諾](/zh-TW/concepts/commitments)。
 
 ---
 
@@ -269,26 +262,44 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 ```
 
 - `evaluateEnabled: false` 會停用 `act:evaluate` 和 `wait --fn`。
-- `tabCleanup` 會在閒置時間過後，或當工作階段超過其上限時，回收已追蹤的主要代理程式分頁。設定 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可停用各自的清理模式。
-- 未設定 `ssrfPolicy.dangerouslyAllowPrivateNetwork` 時會停用，因此瀏覽器導覽預設會保持嚴格。
+- `tabCleanup` 會在閒置時間後，或當工作階段超過上限時，回收追蹤中的主要代理分頁。將 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 設定為
+  停用這些個別清理模式。
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未設定時會停用，因此瀏覽器導覽預設保持嚴格。
 - 只有在你有意信任私有網路瀏覽器導覽時，才設定 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
-- 在嚴格模式下，遠端 CDP 設定檔端點（`profiles.*.cdpUrl`）在可達性/探索檢查期間也會受到相同的私有網路封鎖。
-- `ssrfPolicy.allowPrivateNetwork` 仍作為舊版別名受到支援。
-- 在嚴格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作為明確例外。
-- 遠端設定檔僅能附加（停用啟動/停止/重設）。
-- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。當你想讓 OpenClaw 探索 `/json/version` 時使用 HTTP(S)；當你的提供者提供直接的 DevTools WebSocket URL 時使用 WS(S)。
-- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 適用於遠端和 `attachOnly` CDP 可達性，以及分頁開啟請求。受管理的 loopback 設定檔會保留本機 CDP 預設值。
-- 如果外部管理的 CDP 服務可透過 loopback 存取，請將該設定檔的 `attachOnly: true`；否則 OpenClaw 會將 loopback 連接埠視為本機受管理的瀏覽器設定檔，並可能回報本機連接埠擁有權錯誤。
-- `existing-session` 設定檔會使用 Chrome MCP 而不是 CDP，並可在選取的主機上或透過已連線的瀏覽器節點附加。
-- `existing-session` 設定檔可以設定 `userDataDir`，以指定特定的 Chromium 架構瀏覽器設定檔，例如 Brave 或 Edge。
-- `existing-session` 設定檔會保留目前的 Chrome MCP 路由限制：使用 snapshot/ref 驅動的動作，而不是 CSS 選擇器定位；單一檔案上傳鉤子；沒有對話方塊逾時覆寫；沒有 `wait --load networkidle`；也沒有 `responsebody`、PDF 匯出、下載攔截或批次動作。
-- 本機受管理的 `openclaw` 設定檔會自動指派 `cdpPort` 和 `cdpUrl`；只有遠端 CDP 才明確設定 `cdpUrl`。
-- 本機受管理的設定檔可以設定 `executablePath`，以覆寫該設定檔的全域 `browser.executablePath`。可用它讓一個設定檔在 Chrome 執行，另一個在 Brave 執行。
-- 本機受管理的設定檔會在程序啟動後，將 `browser.localLaunchTimeoutMs` 用於 Chrome CDP HTTP 探索，並將 `browser.localCdpReadyTimeoutMs` 用於啟動後的 CDP websocket 就緒狀態。在 Chrome 可成功啟動但就緒檢查與啟動競速的較慢主機上，請提高這些值。兩個值都必須是最高 `120000` ms 的正整數；無效的設定值會被拒絕。
-- 自動偵測順序：預設瀏覽器（若為 Chromium 架構）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
-- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 在 Chromium 啟動前，都接受 `~` 和 `~/...` 代表你的作業系統主目錄。`existing-session` 設定檔上的個別設定檔 `userDataDir` 也會展開波浪號。
-- 控制服務：僅 loopback（連接埠衍生自 `gateway.port`，預設為 `18791`）。
-- `extraArgs` 會將額外啟動旗標附加到本機 Chromium 啟動（例如 `--disable-gpu`、視窗大小設定或除錯旗標）。
+- 在嚴格模式下，遠端 CDP 設定檔端點 (`profiles.*.cdpUrl`) 在可連線性/探索檢查期間也會受到相同的私有網路封鎖限制。
+- `ssrfPolicy.allowPrivateNetwork` 仍支援作為舊版別名。
+- 在嚴格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 設定明確例外。
+- 遠端設定檔僅限附加（停用啟動/停止/重設）。
+- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
+  當你希望 OpenClaw 探索 `/json/version` 時使用 HTTP(S)；當你的供應商提供直接 DevTools WebSocket URL 時使用 WS(S)。
+- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 會套用到遠端與
+  `attachOnly` CDP 可連線性，以及開啟分頁的要求。受管理的 loopback
+  設定檔會保留本機 CDP 預設值。
+- 如果外部管理的 CDP 服務可透過 loopback 存取，請將該設定檔的
+  `attachOnly: true`；否則 OpenClaw 會將該 loopback 連接埠視為
+  本機受管理瀏覽器設定檔，並可能回報本機連接埠擁有權錯誤。
+- `existing-session` 設定檔使用 Chrome MCP 而非 CDP，並可在所選主機或透過已連線的瀏覽器節點附加。
+- `existing-session` 設定檔可設定 `userDataDir`，以指定特定
+  Chromium 系瀏覽器設定檔，例如 Brave 或 Edge。
+- `existing-session` 設定檔保留目前的 Chrome MCP 路由限制：
+  使用快照/參照驅動動作而不是 CSS 選擇器目標定位、單檔上傳
+  hook、無對話方塊逾時覆寫、無 `wait --load networkidle`，且不支援
+  `responsebody`、PDF 匯出、下載攔截或批次動作。
+- 本機受管理的 `openclaw` 設定檔會自動指派 `cdpPort` 和 `cdpUrl`；只有
+  遠端 CDP 才需要明確設定 `cdpUrl`。
+- 本機受管理設定檔可設定 `executablePath`，以覆寫該設定檔的全域
+  `browser.executablePath`。可用它讓一個設定檔在 Chrome 中執行，另一個在 Brave 中執行。
+- 本機受管理設定檔會使用 `browser.localLaunchTimeoutMs`，在程序啟動後進行 Chrome CDP HTTP
+  探索，並使用 `browser.localCdpReadyTimeoutMs`，在啟動後等待
+  CDP websocket 就緒。在較慢主機上，若 Chrome 能成功啟動但就緒檢查與啟動流程競速，請提高這些值。兩個值都必須是
+  最高 `120000` ms 的正整數；無效設定值會被拒絕。
+- 自動偵測順序：預設瀏覽器（若為 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
+- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 都
+  接受 `~` 和 `~/...`，在啟動 Chromium 前代表你的作業系統家目錄。
+  `existing-session` 設定檔上的每個設定檔 `userDataDir` 也會展開波浪號。
+- 控制服務：僅限 loopback（連接埠由 `gateway.port` 衍生，預設 `18791`）。
+- `extraArgs` 會將額外啟動旗標附加到本機 Chromium 啟動流程（例如
+  `--disable-gpu`、視窗大小或偵錯旗標）。
 
 ---
 
@@ -306,8 +317,8 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 }
 ```
 
-- `seamColor`：原生應用程式 UI chrome 的強調色（Talk Mode 氣泡色調等）。
-- `assistant`：Control UI 身分覆寫。會退回使用作用中代理程式身分。
+- `seamColor`：原生應用程式 UI chrome 的重點色（Talk Mode 氣泡色調等）。
+- `assistant`：Control UI 身分覆寫。會退回使用作用中的代理身分。
 
 ---
 
@@ -383,55 +394,55 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
 }
 ```
 
-<Accordion title="Gateway field details">
+<Accordion title="Gateway 欄位詳細資訊">
 
-- `mode`：`local`（執行 Gateway）或 `remote`（連線到遠端 Gateway）。除非是 `local`，否則 Gateway 會拒絕啟動。
+- `mode`：`local`（執行 Gateway）或 `remote`（連線到遠端 Gateway）。除非為 `local`，否則 Gateway 會拒絕啟動。
 - `port`：WS + HTTP 的單一多工連接埠。優先順序：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
-- `bind`：`auto`、`loopback`（預設）、`lan`（`0.0.0.0`）、`tailnet`（僅限 Tailscale IP）或 `custom`。
-- **舊版繫結別名**：在 `gateway.bind` 中使用繫結模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），而不是主機別名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
-- **Docker 注意事項**：預設的 `loopback` 繫結會在容器內監聽 `127.0.0.1`。使用 Docker 橋接網路（`-p 18789:18789`）時，流量會抵達 `eth0`，因此無法連到 Gateway。請使用 `--network host`，或設定 `bind: "lan"`（或搭配 `customBindHost: "0.0.0.0"` 的 `bind: "custom"`）以監聽所有介面。
-- **驗證**：預設為必要。非 loopback 繫結需要 Gateway 驗證。實務上，這表示需要共用權杖/密碼，或搭配 `gateway.auth.mode: "trusted-proxy"` 的具身分感知反向代理。導覽精靈預設會產生權杖。
-- 如果同時設定了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），請將 `gateway.auth.mode` 明確設為 `token` 或 `password`。兩者都已設定但未設定模式時，啟動與服務安裝/修復流程會失敗。
-- `gateway.auth.mode: "none"`：明確的無驗證模式。僅用於受信任的 local loopback 設定；導覽提示刻意不提供此選項。
-- `gateway.auth.mode: "trusted-proxy"`：將瀏覽器/使用者驗證委派給具身分感知的反向代理，並信任來自 `gateway.trustedProxies` 的身分標頭（請參閱 [受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)）。此模式預設預期代理來源為**非 loopback**；同主機 loopback 反向代理需要明確設定 `gateway.auth.trustedProxy.allowLoopback = true`。內部同主機呼叫端可以使用 `gateway.auth.password` 作為本機直接備援；`gateway.auth.token` 仍與 trusted-proxy 模式互斥。
-- `gateway.auth.allowTailscale`：當為 `true` 時，Tailscale Serve 身分標頭可滿足控制 UI/WebSocket 驗證（透過 `tailscale whois` 驗證）。HTTP API 端點**不會**使用該 Tailscale 標頭驗證；它們改用 Gateway 的一般 HTTP 驗證模式。此無權杖流程假設 Gateway 主機受信任。當 `tailscale.mode = "serve"` 時預設為 `true`。
-- `gateway.auth.rateLimit`：選用的驗證失敗限制器。依用戶端 IP 與驗證範圍套用（shared-secret 和 device-token 會分開追蹤）。遭封鎖的嘗試會回傳 `429` + `Retry-After`。
-  - 在非同步 Tailscale Serve 控制 UI 路徑上，同一個 `{scope, clientIp}` 的失敗嘗試會在寫入失敗之前序列化。因此，同一用戶端的並行錯誤嘗試可能會在第二個請求觸發限制器，而不是兩者都以單純不相符的結果競速通過。
-  - `gateway.auth.rateLimit.exemptLoopback` 預設為 `true`；若你刻意也想限制 localhost 流量（用於測試設定或嚴格代理部署），請設為 `false`。
-- 瀏覽器來源的 WS 驗證嘗試一律會被節流，且停用 loopback 豁免（針對基於瀏覽器的 localhost 暴力破解提供縱深防禦）。
-- 在 loopback 上，這些瀏覽器來源的鎖定會依正規化的 `Origin`
-  值隔離，因此來自某個 localhost 來源的重複失敗不會自動
-  鎖定不同來源。
-- `tailscale.mode`：`serve`（僅限 tailnet，loopback 繫結）或 `funnel`（公開，需要驗證）。
-- `controlUi.allowedOrigins`：Gateway WebSocket 連線的明確瀏覽器來源允許清單。當預期瀏覽器用戶端來自非 loopback 來源時必填。
-- `controlUi.chatMessageMaxWidth`：分組控制 UI 聊天訊息的選用最大寬度。接受受限的 CSS 寬度值，例如 `960px`、`82%`、`min(1280px, 82%)` 和 `calc(100% - 2rem)`。
-- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危險模式，會為刻意仰賴 Host 標頭來源政策的部署啟用 Host 標頭來源備援。
+- `bind`：`auto`、`loopback`（預設）、`lan`（`0.0.0.0`）、`tailnet`（僅 Tailscale IP），或 `custom`。
+- **舊版 bind 別名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主機別名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
+- **Docker 注意事項**：預設的 `loopback` bind 會在容器內監聽 `127.0.0.1`。使用 Docker bridge 網路（`-p 18789:18789`）時，流量會從 `eth0` 進入，因此無法連到 Gateway。請使用 `--network host`，或設定 `bind: "lan"`（或使用 `bind: "custom"` 搭配 `customBindHost: "0.0.0.0"`）以監聽所有介面。
+- **驗證**：預設為必需。非 loopback bind 需要 Gateway 驗證。實務上，這表示需要共用權杖/密碼，或搭配 `gateway.auth.mode: "trusted-proxy"` 的具身分識別能力反向代理。入門精靈預設會產生權杖。
+- 如果同時設定了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），請明確將 `gateway.auth.mode` 設為 `token` 或 `password`。兩者皆已設定但未設定模式時，啟動與服務安裝/修復流程會失敗。
+- `gateway.auth.mode: "none"`：明確的無驗證模式。僅用於受信任的 local loopback 設定；入門提示刻意不提供此選項。
+- `gateway.auth.mode: "trusted-proxy"`：將瀏覽器/使用者驗證委派給具身分識別能力的反向代理，並信任來自 `gateway.trustedProxies` 的身分標頭（請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)）。此模式預設預期代理來源為**非 loopback**；同主機 loopback 反向代理需要明確設定 `gateway.auth.trustedProxy.allowLoopback = true`。內部同主機呼叫者可使用 `gateway.auth.password` 作為本機直接備援；`gateway.auth.token` 仍與 trusted-proxy 模式互斥。
+- `gateway.auth.allowTailscale`：當為 `true` 時，Tailscale Serve 身分標頭可滿足 Control UI/WebSocket 驗證（透過 `tailscale whois` 驗證）。HTTP API 端點**不會**使用該 Tailscale 標頭驗證；它們改為遵循 Gateway 的一般 HTTP 驗證模式。此無權杖流程假設 Gateway 主機受信任。當 `tailscale.mode = "serve"` 時，預設為 `true`。
+- `gateway.auth.rateLimit`：選用的驗證失敗限制器。按用戶端 IP 和驗證範圍套用（shared-secret 和 device-token 會分開追蹤）。遭封鎖的嘗試會回傳 `429` + `Retry-After`。
+  - 在非同步 Tailscale Serve Control UI 路徑上，相同 `{scope, clientIp}` 的失敗嘗試會在寫入失敗前序列化。因此，來自同一用戶端的並行錯誤嘗試，可能會在第二個請求觸發限制器，而不是兩者都以一般不相符狀態競速通過。
+  - `gateway.auth.rateLimit.exemptLoopback` 預設為 `true`；當你刻意也想限制 localhost 流量速率時（用於測試設定或嚴格代理部署），請設為 `false`。
+- 瀏覽器來源的 WS 驗證嘗試一律會受到節流，且停用 loopback 豁免（針對瀏覽器型 localhost 暴力破解的縱深防禦）。
+- 在 loopback 上，這些瀏覽器來源鎖定會依正規化的 `Origin`
+  值隔離，因此來自某個 localhost origin 的重複失敗不會自動
+  鎖定不同 origin。
+- `tailscale.mode`：`serve`（僅 tailnet，loopback bind）或 `funnel`（公開，需要驗證）。
+- `controlUi.allowedOrigins`：Gateway WebSocket 連線的明確瀏覽器來源允許清單。當預期瀏覽器用戶端來自非 loopback origin 時為必需。
+- `controlUi.chatMessageMaxWidth`：群組化 Control UI 聊天訊息的選用 max-width。接受受限制的 CSS 寬度值，例如 `960px`、`82%`、`min(1280px, 82%)` 和 `calc(100% - 2rem)`。
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危險模式，會為刻意依賴 Host 標頭 origin 政策的部署啟用 Host-header origin 備援。
 - `remote.transport`：`ssh`（預設）或 `direct`（ws/wss）。對於 `direct`，`remote.url` 必須是 `ws://` 或 `wss://`。
-- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：用戶端程序環境的
-  緊急覆寫，允許純文字 `ws://` 連到受信任的私有網路
-  IP；純文字的預設仍僅限 loopback。沒有對應的 `openclaw.json`
-  設定，而且瀏覽器私有網路設定（例如
-  `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不會影響 Gateway
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：用戶端程序環境
+  break-glass 覆寫，允許明文 `ws://` 連到受信任的私有網路
+  IP；明文預設仍僅限 loopback。沒有對應的 `openclaw.json`
+  等效設定，且瀏覽器私有網路設定，例如
+  `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，不會影響 Gateway
   WebSocket 用戶端。
 - `gateway.remote.token` / `.password` 是遠端用戶端憑證欄位。它們本身不會設定 Gateway 驗證。
-- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 建置在向 Gateway 發布由轉送支援的註冊後，所使用外部 APNs 轉送的基礎 HTTPS URL。此 URL 必須符合編譯進 iOS 建置中的轉送 URL。
-- `gateway.push.apns.relay.timeoutMs`：Gateway 到轉送的傳送逾時，單位為毫秒。預設為 `10000`。
-- 由轉送支援的註冊會委派給特定的 Gateway 身分。配對的 iOS 應用程式會擷取 `gateway.identity.get`，在轉送註冊中包含該身分，並將註冊範圍的傳送授權轉送給 Gateway。另一個 Gateway 無法重用該已儲存的註冊。
-- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述轉送設定的臨時環境覆寫。
-- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：僅限開發使用的逃生口，用於 loopback HTTP 轉送 URL。正式環境轉送 URL 應維持使用 HTTPS。
-- `gateway.handshakeTimeoutMs`：驗證前 Gateway WebSocket 交握逾時，單位為毫秒。預設：`15000`。設定 `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 時會優先使用。若主機負載較高或效能較低，而本機用戶端可能在啟動暖機仍未穩定時連線，請增加此值。
+- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基礎 HTTPS URL，供官方/TestFlight iOS 建置在將 relay-backed 註冊發布到 Gateway 後使用。此 URL 必須符合編譯進 iOS 建置中的 relay URL。
+- `gateway.push.apns.relay.timeoutMs`：Gateway 到 relay 的傳送逾時，單位為毫秒。預設為 `10000`。
+- relay-backed 註冊會委派給特定 Gateway 身分。已配對的 iOS app 會擷取 `gateway.identity.get`，在 relay 註冊中包含該身分，並將註冊範圍的傳送授權轉送給 Gateway。另一個 Gateway 無法重複使用該已儲存的註冊。
+- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 設定的臨時環境覆寫。
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：僅供開發使用的逃生孔，適用於 loopback HTTP relay URL。正式環境 relay URL 應維持使用 HTTPS。
+- `gateway.handshakeTimeoutMs`：驗證前 Gateway WebSocket 握手逾時，單位為毫秒。預設：`15000`。設定時，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 優先。若主機負載較高或效能較低，而本機用戶端可在啟動暖機仍在穩定時連線，請提高此值。
 - `gateway.channelHealthCheckMinutes`：通道健康監控間隔，單位為分鐘。設為 `0` 可全域停用健康監控重啟。預設：`5`。
-- `gateway.channelStaleEventThresholdMinutes`：過期 socket 閾值，單位為分鐘。保持此值大於或等於 `gateway.channelHealthCheckMinutes`。預設：`30`。
-- `gateway.channelMaxRestartsPerHour`：每個通道/帳戶在滾動一小時內的健康監控重啟上限。預設：`10`。
-- `channels.<provider>.healthMonitor.enabled`：每個通道可選擇退出健康監控重啟，同時保留全域監控啟用。
-- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多帳戶通道的每帳戶覆寫。設定後，其優先順序高於通道層級覆寫。
-- 只有在未設定 `gateway.auth.*` 時，本機 Gateway 呼叫路徑才可使用 `gateway.remote.*` 作為備援。
-- 如果 `gateway.auth.token` / `gateway.auth.password` 透過 SecretRef 明確設定且無法解析，解析會以關閉方式失敗（不會讓遠端備援遮蔽問題）。
-- `trustedProxies`：終止 TLS 或注入轉送用戶端標頭的反向代理 IP。僅列出你控制的代理。Loopback 項目對同主機代理/本機偵測設定仍有效（例如 Tailscale Serve 或本機反向代理），但它們**不會**讓 loopback 請求有資格使用 `gateway.auth.mode: "trusted-proxy"`。
-- `allowRealIpFallback`：當為 `true` 時，如果缺少 `X-Forwarded-For`，Gateway 會接受 `X-Real-IP`。預設為 `false`，採用失敗關閉行為。
-- `gateway.nodes.pairing.autoApproveCidrs`：選用的 CIDR/IP 允許清單，用於自動核准沒有要求範圍的首次節點裝置配對。未設定時會停用。這不會自動核准操作員/瀏覽器/控制 UI/WebChat 配對，也不會自動核准角色、範圍、中繼資料或公開金鑰升級。
-- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配對與平台允許清單評估後，對宣告的節點命令進行全域允許/拒絕塑形。使用 `allowCommands` 以選擇加入危險的節點命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台預設或明確允許原本會包含某命令，`denyCommands` 也會移除該命令。節點變更其宣告的命令清單後，請拒絕並重新核准該裝置配對，讓 Gateway 儲存更新後的命令快照。
-- `gateway.tools.deny`：針對 HTTP `POST /tools/invoke` 封鎖的額外工具名稱（延伸預設拒絕清單）。
+- `gateway.channelStaleEventThresholdMinutes`：陳舊 socket 閾值，單位為分鐘。請讓此值大於或等於 `gateway.channelHealthCheckMinutes`。預設：`30`。
+- `gateway.channelMaxRestartsPerHour`：每個通道/帳戶在滾動一小時內的健康監控重啟次數上限。預設：`10`。
+- `channels.<provider>.healthMonitor.enabled`：針對單一通道退出健康監控重啟，同時保留全域監控啟用。
+- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多帳戶通道的逐帳戶覆寫。設定後，其優先於通道層級覆寫。
+- 本機 Gateway 呼叫路徑僅在未設定 `gateway.auth.*` 時，才可使用 `gateway.remote.*` 作為備援。
+- 如果 `gateway.auth.token` / `gateway.auth.password` 透過 SecretRef 明確設定但未解析，解析會 fail-closed（不會由遠端備援遮蔽）。
+- `trustedProxies`：終止 TLS 或注入 forwarded-client 標頭的反向代理 IP。僅列出你控制的代理。Loopback 項目對同主機代理/本機偵測設定仍有效（例如 Tailscale Serve 或本機反向代理），但它們**不會**讓 loopback 請求符合 `gateway.auth.mode: "trusted-proxy"` 條件。
+- `allowRealIpFallback`：當為 `true` 時，如果缺少 `X-Forwarded-For`，Gateway 會接受 `X-Real-IP`。預設為 `false`，採用 fail-closed 行為。
+- `gateway.nodes.pairing.autoApproveCidrs`：選用的 CIDR/IP 允許清單，用於自動核准首次節點裝置配對，且沒有請求的範圍。未設定時會停用。這不會自動核准 operator/browser/Control UI/WebChat 配對，也不會自動核准角色、範圍、中繼資料或公開金鑰升級。
+- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：配對與平台允許清單評估後，對已宣告節點命令進行全域允許/拒絕塑形。使用 `allowCommands` 選擇加入危險節點命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台預設或明確允許原本會包含某個命令，`denyCommands` 也會移除該命令。節點變更其宣告的命令清單後，請拒絕並重新核准該裝置配對，讓 Gateway 儲存更新後的命令快照。
+- `gateway.tools.deny`：為 HTTP `POST /tools/invoke` 額外封鎖的工具名稱（擴充預設拒絕清單）。
 - `gateway.tools.allow`：從預設 HTTP 拒絕清單中移除工具名稱。
 
 </Accordion>
@@ -444,14 +455,14 @@ OpenClaw 管理的 MCP 伺服器定義位於 `mcp.servers` 下，並由內嵌 Pi
   - `gateway.http.endpoints.responses.maxUrlParts`
   - `gateway.http.endpoints.responses.files.urlAllowlist`
   - `gateway.http.endpoints.responses.images.urlAllowlist`
-    空的允許清單會被視為未設定；使用 `gateway.http.endpoints.responses.files.allowUrl=false`
-    和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 以停用 URL 擷取。
+    空的允許清單會視為未設定；使用 `gateway.http.endpoints.responses.files.allowUrl=false`
+    和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 可停用 URL 擷取。
 - 選用的回應強化標頭：
-  - `gateway.http.securityHeaders.strictTransportSecurity`（僅針對你控制的 HTTPS 來源設定；請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
+  - `gateway.http.securityHeaders.strictTransportSecurity`（僅針對你控制的 HTTPS origin 設定；請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
 
 ### 多執行個體隔離
 
-在一台主機上以唯一連接埠與狀態目錄執行多個 Gateway：
+在一台主機上使用唯一連接埠與狀態目錄執行多個 Gateway：
 
 ```bash
 OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@@ -482,7 +493,7 @@ openclaw gateway --port 19001
 - `enabled`：在 Gateway 監聽器啟用 TLS 終止（HTTPS/WSS）（預設：`false`）。
 - `autoGenerate`：未設定明確檔案時，自動產生本機自簽憑證/金鑰組；僅供本機/開發使用。
 - `certPath`：TLS 憑證檔案的檔案系統路徑。
-- `keyPath`：TLS 私密金鑰檔案的檔案系統路徑；請限制權限。
+- `keyPath`：TLS 私密金鑰檔案的檔案系統路徑；請保持權限受限。
 - `caPath`：用於用戶端驗證或自訂信任鏈的選用 CA bundle 路徑。
 
 ### `gateway.reload`
@@ -499,13 +510,13 @@ openclaw gateway --port 19001
 }
 ```
 
-- `mode`：控制設定編輯在執行階段如何套用。
+- `mode`：控制如何在執行階段套用設定編輯。
   - `"off"`：忽略即時編輯；變更需要明確重啟。
   - `"restart"`：設定變更時一律重啟 Gateway 程序。
   - `"hot"`：在程序內套用變更，不重啟。
-  - `"hybrid"`（預設）：先嘗試熱重載；必要時退回重啟。
-- `debounceMs`：套用設定變更前的 debounce 視窗，單位為毫秒（非負整數）。
-- `deferralTimeoutMs`：選用的等待進行中操作完成之最長時間，單位為毫秒，超過後強制重啟。省略時使用預設的有界等待（`300000`）；設為 `0` 則無限期等待，並定期記錄仍在等待的警告。
+  - `"hybrid"`（預設）：先嘗試 hot reload；必要時退回重啟。
+- `debounceMs`：套用設定變更前的 debounce 視窗，單位為 ms（非負整數）。
+- `deferralTimeoutMs`：選用，在強制重啟前等待進行中作業的最長時間，單位為 ms。省略時使用預設的有界等待（`300000`）；設為 `0` 可無限期等待，並記錄週期性的仍待處理警告。
 
 ---
 
@@ -543,47 +554,47 @@ openclaw gateway --port 19001
 ```
 
 驗證：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
-查詢字串中的 hook 權杖會被拒絕。
+查詢字串 hook Token 會遭到拒絕。
 
 驗證與安全注意事項：
 
 - `hooks.enabled=true` 需要非空的 `hooks.token`。
-- `hooks.token` 必須與 `gateway.auth.token` **不同**；重複使用 Gateway 權杖會被拒絕。
+- `hooks.token` 必須與 `gateway.auth.token` **不同**；重複使用 Gateway Token 會遭到拒絕。
 - `hooks.path` 不能是 `/`；請使用專用子路徑，例如 `/hooks`。
 - 如果 `hooks.allowRequestSessionKey=true`，請限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
-- 如果 mapping 或 preset 使用樣板化的 `sessionKey`，請設定 `hooks.allowedSessionKeyPrefixes` 與 `hooks.allowRequestSessionKey=true`。靜態 mapping key 不需要該選項啟用。
+- 如果對應或預設集使用範本化的 `sessionKey`，請設定 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。靜態對應鍵不需要選擇加入。
 
 **端點：**
 
 - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
 - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
-  - 只有在 `hooks.allowRequestSessionKey=true`（預設：`false`）時，才會接受來自請求 payload 的 `sessionKey`。
+  - 只有在 `hooks.allowRequestSessionKey=true`（預設值：`false`）時，才會接受來自請求酬載的 `sessionKey`。
 - `POST /hooks/<name>` → 透過 `hooks.mappings` 解析
-  - 由樣板渲染的 mapping `sessionKey` 值會被視為外部提供，也需要 `hooks.allowRequestSessionKey=true`。
+  - 由範本轉譯的對應 `sessionKey` 值會被視為外部提供，也需要 `hooks.allowRequestSessionKey=true`。
 
-<Accordion title="Mapping 詳細資訊">
+<Accordion title="對應詳細資料">
 
-- `match.path` 會比對 `/hooks` 後面的子路徑（例如 `/hooks/gmail` → `gmail`）。
-- `match.source` 會比對 generic path 的 payload 欄位。
-- 像 `{{messages[0].subject}}` 這樣的樣板會從 payload 讀取。
-- `transform` 可以指向回傳 hook action 的 JS/TS 模組。
-  - `transform.module` 必須是相對路徑，且保持在 `hooks.transformsDir` 內（絕對路徑與路徑穿越會被拒絕）。
-  - 請將 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 之下；workspace skill 目錄會被拒絕。如果 `openclaw doctor` 回報此路徑無效，請將 transform 模組移到 hooks transforms 目錄中，或移除 `hooks.transformsDir`。
-- `agentId` 會路由到特定 agent；未知 ID 會退回預設值。
+- `match.path` 會比對 `/hooks` 之後的子路徑（例如 `/hooks/gmail` → `gmail`）。
+- `match.source` 會比對通用路徑的酬載欄位。
+- 像 `{{messages[0].subject}}` 這樣的範本會從酬載讀取。
+- `transform` 可以指向會傳回 hook 動作的 JS/TS 模組。
+  - `transform.module` 必須是相對路徑，且需位於 `hooks.transformsDir` 內（絕對路徑和路徑穿越會遭到拒絕）。
+  - 請將 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 之下；工作區 Skills 目錄會遭到拒絕。如果 `openclaw doctor` 回報此路徑無效，請將轉換模組移到 hooks 轉換目錄，或移除 `hooks.transformsDir`。
+- `agentId` 會路由到特定代理；未知 ID 會退回預設值。
 - `allowedAgentIds`：限制明確路由（`*` 或省略 = 全部允許，`[]` = 全部拒絕）。
-- `defaultSessionKey`：在沒有明確 `sessionKey` 的 hook agent 執行中使用的選用固定 session key。
-- `allowRequestSessionKey`：允許 `/hooks/agent` 呼叫端與樣板驅動的 mapping session key 設定 `sessionKey`（預設：`false`）。
-- `allowedSessionKeyPrefixes`：明確 `sessionKey` 值（request + mapping）的選用 prefix allowlist，例如 `["hook:"]`。當任何 mapping 或 preset 使用樣板化的 `sessionKey` 時，此項會變成必要。
-- `deliver: true` 會將最終回覆傳送到 channel；`channel` 預設為 `last`。
-- `model` 會覆寫此 hook 執行的 LLM（如果已設定 model catalog，則必須被允許）。
+- `defaultSessionKey`：選用的固定工作階段鍵，用於沒有明確 `sessionKey` 的 hook 代理執行。
+- `allowRequestSessionKey`：允許 `/hooks/agent` 呼叫端和由範本驅動的對應工作階段鍵設定 `sessionKey`（預設值：`false`）。
+- `allowedSessionKeyPrefixes`：明確 `sessionKey` 值（請求 + 對應）的選用前綴允許清單，例如 `["hook:"]`。當任何對應或預設集使用範本化的 `sessionKey` 時，這會變成必要項。
+- `deliver: true` 會將最終回覆傳送到頻道；`channel` 預設為 `last`。
+- `model` 會覆寫此 hook 執行使用的 LLM（如果已設定模型目錄，必須允許該模型）。
 
 </Accordion>
 
 ### Gmail 整合
 
-- 內建 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
+- 內建 Gmail 預設集使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
 - 如果保留該逐訊息路由，請設定 `hooks.allowRequestSessionKey: true`，並限制 `hooks.allowedSessionKeyPrefixes` 以符合 Gmail 命名空間，例如 `["hook:", "hook:gmail:"]`。
-- 如果需要 `hooks.allowRequestSessionKey: false`，請用靜態 `sessionKey` 覆寫 preset，而不是使用樣板化預設值。
+- 如果需要 `hooks.allowRequestSessionKey: false`，請以靜態 `sessionKey` 覆寫預設集，而不是使用範本化預設值。
 
 ```json5
 {
@@ -606,12 +617,12 @@ openclaw gateway --port 19001
 }
 ```
 
-- Gateway 會在啟動時自動啟動已設定的 `gog gmail watch serve`。設定 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可停用。
-- 不要在 Gateway 旁邊另外執行一個 `gog gmail watch serve`。
+- Gateway 會在設定後於啟動時自動啟動 `gog gmail watch serve`。設定 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可停用。
+- 不要在 Gateway 旁另外執行 `gog gmail watch serve`。
 
 ---
 
-## Canvas host
+## Canvas 主機
 
 ```json5
 {
@@ -623,18 +634,18 @@ openclaw gateway --port 19001
 }
 ```
 
-- 在 Gateway port 下透過 HTTP 提供 agent 可編輯的 HTML/CSS/JS 與 A2UI：
+- 在 Gateway 連接埠下透過 HTTP 提供代理可編輯的 HTML/CSS/JS 和 A2UI：
   - `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
   - `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
-- 僅限本機：保持 `gateway.bind: "loopback"`（預設）。
-- 非 loopback bind：canvas route 需要 Gateway 驗證（token/password/trusted-proxy），與其他 Gateway HTTP surface 相同。
-- Node WebViews 通常不會傳送 auth header；node 配對並連線後，Gateway 會公告 node-scoped capability URL 供 canvas/A2UI 存取。
-- Capability URL 會繫結到作用中的 node WS session，並很快過期。不使用 IP-based fallback。
-- 將 live-reload client 注入提供的 HTML。
-- 空白時自動建立 starter `index.html`。
+- 僅限本機：保留 `gateway.bind: "loopback"`（預設值）。
+- 非 loopback 綁定：Canvas 路由需要 Gateway 驗證（Token/密碼/受信任 Proxy），與其他 Gateway HTTP 介面相同。
+- Node WebView 通常不會傳送驗證標頭；Node 配對並連線後，Gateway 會通告 Node 範圍的功能 URL，供 Canvas/A2UI 存取。
+- 功能 URL 會綁定到使用中的 Node WS 工作階段，並且很快過期。不使用以 IP 為基礎的備援。
+- 將即時重新載入用戶端注入到提供的 HTML 中。
+- 空白時會自動建立入門 `index.html`。
 - 也會在 `/__openclaw__/a2ui/` 提供 A2UI。
-- 變更需要重新啟動 gateway。
-- 對大型目錄或 `EMFILE` 錯誤停用 live reload。
+- 變更需要重新啟動 Gateway。
+- 對大型目錄或 `EMFILE` 錯誤停用即時重新載入。
 
 ---
 
@@ -652,13 +663,13 @@ openclaw gateway --port 19001
 }
 ```
 
-- `minimal`（啟用 bundled `bonjour` plugin 時的預設值）：從 TXT records 省略 `cliPath` + `sshPort`。
-- `full`：包含 `cliPath` + `sshPort`；LAN multicast advertising 仍需要啟用 bundled `bonjour` plugin。
-- `off`：在不變更 plugin 啟用狀態的情況下，抑制 LAN multicast advertising。
-- bundled `bonjour` plugin 會在 macOS host 上自動啟動，並在 Linux、Windows 與容器化 Gateway 部署上採取 opt-in。
-- 當系統 hostname 是有效的 DNS label 時，hostname 會預設為系統 hostname，否則退回 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆寫。
+- `minimal`（啟用內建 `bonjour` Plugin 時的預設值）：從 TXT 記錄省略 `cliPath` + `sshPort`。
+- `full`：包含 `cliPath` + `sshPort`；區域網路多播通告仍需要啟用內建 `bonjour` Plugin。
+- `off`：在不變更 Plugin 啟用狀態的情況下，抑制區域網路多播通告。
+- 內建 `bonjour` Plugin 會在 macOS 主機上自動啟動，並在 Linux、Windows 和容器化 Gateway 部署中採選擇加入。
+- 主機名稱在是有效 DNS 標籤時預設為系統主機名稱，否則退回 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆寫。
 
-### Wide-area (DNS-SD)
+### 廣域 (DNS-SD)
 
 ```json5
 {
@@ -668,7 +679,7 @@ openclaw gateway --port 19001
 }
 ```
 
-在 `~/.openclaw/dns/` 下寫入 unicast DNS-SD zone。若要跨網路探索，請搭配 DNS server（建議 CoreDNS）+ Tailscale split DNS。
+在 `~/.openclaw/dns/` 下寫入單播 DNS-SD 區域。若要跨網路探索，請搭配 DNS 伺服器（建議使用 CoreDNS）+ Tailscale 分割 DNS。
 
 設定：`openclaw dns setup --apply`。
 
@@ -676,7 +687,7 @@ openclaw gateway --port 19001
 
 ## 環境
 
-### `env`（內嵌環境變數）
+### `env`（行內環境變數）
 
 ```json5
 {
@@ -693,14 +704,14 @@ openclaw gateway --port 19001
 }
 ```
 
-- 只有在程序環境缺少該鍵時，才會套用內嵌環境變數。
-- `.env` 檔案：目前工作目錄的 `.env` + `~/.openclaw/.env`（兩者都不會覆寫既有變數）。
+- 只有在程序環境缺少該鍵時，才會套用行內環境變數。
+- `.env` 檔案：CWD `.env` + `~/.openclaw/.env`（兩者都不會覆寫既有變數）。
 - `shellEnv`：從你的登入 shell 設定檔匯入缺少的預期鍵。
-- 完整優先順序請參閱[環境](/zh-TW/help/environment)。
+- 請參閱[環境](/zh-TW/help/environment)了解完整優先順序。
 
 ### 環境變數替換
 
-使用 `${VAR_NAME}` 在任何設定字串中參照環境變數：
+在任何設定字串中使用 `${VAR_NAME}` 參照環境變數：
 
 ```json5
 {
@@ -712,14 +723,14 @@ openclaw gateway --port 19001
 
 - 只會比對大寫名稱：`[A-Z_][A-Z0-9_]*`。
 - 缺少或空白的變數會在載入設定時擲出錯誤。
-- 使用 `$${VAR}` 跳脫，以表示字面值 `${VAR}`。
-- 可搭配 `$include` 使用。
+- 使用 `$${VAR}` 逸出，以表示字面值 `${VAR}`。
+- 可與 `$include` 搭配使用。
 
 ---
 
-## 機密
+## 密鑰
 
-機密參照是加成式的：純文字值仍然可用。
+密鑰參照是加成式的：純文字值仍可運作。
 
 ### `SecretRef`
 
@@ -735,15 +746,15 @@ openclaw gateway --port 19001
 - `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
 - `source: "file"` id：絕對 JSON 指標（例如 `"/providers/openai/apiKey"`）
 - `source: "exec"` id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
-- `source: "exec"` ids 不得包含 `.` 或 `..` 這類以斜線分隔的路徑片段（例如 `a/../b` 會被拒絕）
+- `source: "exec"` id 不得包含 `.` 或 `..` 這類以斜線分隔的路徑片段（例如 `a/../b` 會被拒絕）
 
 ### 支援的憑證介面
 
 - 標準矩陣：[SecretRef 憑證介面](/zh-TW/reference/secretref-credential-surface)
 - `secrets apply` 會以支援的 `openclaw.json` 憑證路徑為目標。
-- `auth-profiles.json` 參照會納入執行階段解析與稽核涵蓋範圍。
+- `auth-profiles.json` 參照會包含在執行期解析與稽核涵蓋範圍中。
 
-### 機密提供者設定
+### 密鑰提供者設定
 
 ```json5
 {
@@ -774,13 +785,13 @@ openclaw gateway --port 19001
 注意事項：
 
 - `file` 提供者支援 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式中，`id` 必須是 `"value"`）。
-- 當 Windows ACL 驗證無法使用時，file 和 exec 提供者路徑會封閉失敗。只有在無法驗證但可信任的路徑上，才設定 `allowInsecurePath: true`。
-- `exec` 提供者需要絕對 `command` 路徑，並在 stdin/stdout 上使用協定承載。
-- 預設會拒絕符號連結命令路徑。設定 `allowSymlinkCommand: true` 可允許符號連結路徑，同時驗證已解析的目標路徑。
-- 如果已設定 `trustedDirs`，可信任目錄檢查會套用到已解析的目標路徑。
-- `exec` 子環境預設是最小化的；請使用 `passEnv` 明確傳遞必要變數。
-- 機密參照會在啟用時解析為記憶體中的快照，之後請求路徑只讀取該快照。
-- 啟用期間會套用作用中介面篩選：已啟用介面上未解析的參照會讓啟動或重新載入失敗，而非作用中介面會被略過並附帶診斷資訊。
+- 當 Windows ACL 驗證無法使用時，檔案與 exec 提供者路徑會以失敗關閉處理。只有對無法驗證但可信任的路徑，才設定 `allowInsecurePath: true`。
+- `exec` 提供者需要絕對 `command` 路徑，並在 stdin/stdout 上使用通訊協定承載資料。
+- 預設會拒絕符號連結命令路徑。設定 `allowSymlinkCommand: true` 可允許符號連結路徑，同時驗證解析後的目標路徑。
+- 如果已設定 `trustedDirs`，可信任目錄檢查會套用到解析後的目標路徑。
+- `exec` 子程序環境預設為最小化；請使用 `passEnv` 明確傳遞必要變數。
+- 密鑰參照會在啟用時解析為記憶體內快照，之後請求路徑只會讀取該快照。
+- 啟用期間會套用作用中介面篩選：已啟用介面上的未解析參照會導致啟動/重新載入失敗，而非作用中介面會略過並附帶診斷資訊。
 
 ---
 
@@ -802,14 +813,14 @@ openclaw gateway --port 19001
 }
 ```
 
-- 每個代理的設定檔會儲存在 `<agentDir>/auth-profiles.json`。
-- `auth-profiles.json` 針對靜態憑證模式支援值層級參照（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
-- 舊版扁平 `auth-profiles.json` 對應，例如 `{ "provider": { "apiKey": "..." } }`，不是執行階段格式；`openclaw doctor --fix` 會將它們重寫為標準的 `provider:default` API 金鑰設定檔，並建立 `.legacy-flat.*.bak` 備份。
-- OAuth 模式設定檔（`auth.profiles.<id>.mode = "oauth"`）不支援以 SecretRef 作為後盾的驗證設定檔憑證。
-- 靜態執行階段憑證來自記憶體中已解析的快照；發現舊版靜態 `auth.json` 項目時會將其清除。
+- 每個 agent 的設定檔會儲存在 `<agentDir>/auth-profiles.json`。
+- `auth-profiles.json` 支援值層級參照（靜態憑證模式中，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
+- 舊版扁平 `auth-profiles.json` 對應，例如 `{ "provider": { "apiKey": "..." } }`，不是執行期格式；`openclaw doctor --fix` 會將它們重寫為標準 `provider:default` API 金鑰設定檔，並建立 `.legacy-flat.*.bak` 備份。
+- OAuth 模式設定檔（`auth.profiles.<id>.mode = "oauth"`）不支援以 SecretRef 作為後端的 auth-profile 憑證。
+- 靜態執行期憑證來自記憶體內已解析快照；發現舊版靜態 `auth.json` 項目時會將其清除。
 - 舊版 OAuth 會從 `~/.openclaw/credentials/oauth.json` 匯入。
 - 請參閱 [OAuth](/zh-TW/concepts/oauth)。
-- 機密執行階段行為與 `audit/configure/apply` 工具：[機密管理](/zh-TW/gateway/secrets)。
+- 密鑰執行期行為與 `audit/configure/apply` 工具：[密鑰管理](/zh-TW/gateway/secrets)。
 
 ### `auth.cooldowns`
 
@@ -831,15 +842,15 @@ openclaw gateway --port 19001
 }
 ```
 
-- `billingBackoffHours`：當設定檔因真正的計費/點數不足錯誤而失敗時，以小時為單位的基礎退避時間（預設：`5`）。明確的計費文字即使在 `401`/`403` 回應中仍可能歸到這裡，但供應商特定的文字比對器仍限於擁有它們的供應商範圍內（例如 OpenRouter `Key limit exceeded`）。可重試的 HTTP `402` 使用時段或組織/工作區支出上限訊息則留在 `rate_limit` 路徑中。
-- `billingBackoffHoursByProvider`：選用的各供應商計費退避小時數覆寫。
-- `billingMaxHours`：計費退避指數增長的小時數上限（預設：`24`）。
-- `authPermanentBackoffMinutes`：高信心 `auth_permanent` 失敗的基礎退避分鐘數（預設：`10`）。
-- `authPermanentMaxMinutes`：`auth_permanent` 退避增長的分鐘數上限（預設：`60`）。
-- `failureWindowHours`：用於退避計數器的滾動視窗小時數（預設：`24`）。
-- `overloadedProfileRotations`：因過載錯誤改用模型後援前，同一供應商授權設定檔輪替的最大次數（預設：`1`）。像 `ModelNotReadyException` 這類供應商忙碌形態會歸到這裡。
-- `overloadedBackoffMs`：重試過載供應商/設定檔輪替前的固定延遲（預設：`0`）。
-- `rateLimitedProfileRotations`：因速率限制錯誤改用模型後援前，同一供應商授權設定檔輪替的最大次數（預設：`1`）。該速率限制類別包含供應商形態的文字，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
+- `billingBackoffHours`：當設定檔因真正的計費/餘額不足錯誤失敗時，以小時為單位的基礎退避（預設：`5`）。即使在 `401`/`403` 回應中，明確的計費文字仍可能落在這裡，但提供者專屬的文字比對器仍限定於擁有它們的提供者範圍內（例如 OpenRouter 的 `Key limit exceeded`）。可重試的 HTTP `402` 使用量時段或組織/工作區支出限制訊息，則仍維持在 `rate_limit` 路徑。
+- `billingBackoffHoursByProvider`：可選的每個提供者計費退避小時數覆寫。
+- `billingMaxHours`：計費退避指數成長的小時上限（預設：`24`）。
+- `authPermanentBackoffMinutes`：高可信度 `auth_permanent` 失敗的基礎退避分鐘數（預設：`10`）。
+- `authPermanentMaxMinutes`：`auth_permanent` 退避成長的分鐘上限（預設：`60`）。
+- `failureWindowHours`：用於退避計數器的滾動時窗小時數（預設：`24`）。
+- `overloadedProfileRotations`：在切換到模型備援前，過載錯誤允許的同提供者驗證設定檔輪替最大次數（預設：`1`）。像 `ModelNotReadyException` 這類提供者忙碌的形態會落在這裡。
+- `overloadedBackoffMs`：重試過載的提供者/設定檔輪替前的固定延遲（預設：`0`）。
+- `rateLimitedProfileRotations`：在切換到模型備援前，速率限制錯誤允許的同提供者驗證設定檔輪替最大次數（預設：`1`）。該速率限制桶包含提供者形態的文字，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
 
 ---
 
@@ -859,10 +870,10 @@ openclaw gateway --port 19001
 ```
 
 - 預設記錄檔：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
-- 設定 `logging.file` 以使用穩定路徑。
+- 設定 `logging.file` 可使用固定路徑。
 - 使用 `--verbose` 時，`consoleLevel` 會提升為 `debug`。
 - `maxFileBytes`：輪替前作用中記錄檔的最大位元組大小（正整數；預設：`104857600` = 100 MB）。OpenClaw 會在作用中文件旁保留最多五個編號封存檔。
-- `redactSensitive` / `redactPatterns`：盡力遮罩主控台輸出、檔案記錄、OTLP 記錄項目，以及持久化工作階段逐字稿文字。`redactSensitive: "off"` 只會停用這個一般記錄/逐字稿政策；UI/工具/診斷安全介面在發出前仍會遮蔽密鑰。
+- `redactSensitive` / `redactPatterns`：針對主控台輸出、檔案記錄、OTLP 記錄項目，以及持久化的工作階段逐字稿文字進行盡力遮蔽。`redactSensitive: "off"` 只會停用這項一般記錄/逐字稿政策；UI/工具/診斷安全表面在發出前仍會遮蔽密鑰。
 
 ---
 
@@ -910,25 +921,25 @@ openclaw gateway --port 19001
 }
 ```
 
-- `enabled`：檢測輸出的主開關（預設：`true`）。
-- `flags`：啟用目標記錄輸出的旗標字串陣列（支援像 `"telegram.*"` 或 `"*"` 這樣的萬用字元）。
-- `stuckSessionWarnMs`：用來將長時間處理工作階段分類為 `session.long_running`、`session.stalled` 或 `session.stuck` 的無進度時間門檻，單位為 ms。回覆、工具、狀態、區塊和 ACP 進度會重設計時器；重複的 `session.stuck` 診斷在未變更時會退避。
-- `otel.enabled`：啟用 OpenTelemetry 匯出管線（預設：`false`）。完整設定、訊號目錄和隱私模型請參閱 [OpenTelemetry 匯出](/zh-TW/gateway/opentelemetry)。
+- `enabled`：儀表輸出的主開關（預設：`true`）。
+- `flags`：啟用目標記錄輸出的旗標字串陣列（支援像 `"telegram.*"` 或 `"*"` 的萬用字元）。
+- `stuckSessionWarnMs`：用於將長時間執行的處理工作階段分類為 `session.long_running`、`session.stalled` 或 `session.stuck` 的無進度時間閾值，單位為毫秒。回覆、工具、狀態、區塊與 ACP 進度會重設計時器；重複的 `session.stuck` 診斷在未變更時會退避。
+- `otel.enabled`：啟用 OpenTelemetry 匯出管線（預設：`false`）。完整設定、訊號目錄與隱私模型請參閱 [OpenTelemetry 匯出](/zh-TW/gateway/opentelemetry)。
 - `otel.endpoint`：OTel 匯出的收集器 URL。
-- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：選用的訊號專用 OTLP 端點。設定後，它們只會針對該訊號覆寫 `otel.endpoint`。
+- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可選的訊號專屬 OTLP 端點。設定後，僅針對該訊號覆寫 `otel.endpoint`。
 - `otel.protocol`：`"http/protobuf"`（預設）或 `"grpc"`。
 - `otel.headers`：隨 OTel 匯出請求傳送的額外 HTTP/gRPC 中繼資料標頭。
 - `otel.serviceName`：資源屬性的服務名稱。
 - `otel.traces` / `otel.metrics` / `otel.logs`：啟用追蹤、指標或記錄匯出。
 - `otel.sampleRate`：追蹤取樣率 `0`–`1`。
-- `otel.flushIntervalMs`：週期性遙測清出間隔，單位為 ms。
-- `otel.captureContent`：選擇加入 OTEL span 屬性的原始內容擷取。預設為關閉。布林值 `true` 會擷取非系統訊息/工具內容；物件形式可讓你明確啟用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
-- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：最新實驗性 GenAI span 供應商屬性的環境開關。預設情況下，span 會保留舊版 `gen_ai.system` 屬性以維持相容性；GenAI 指標使用有界語意屬性。
-- `OPENCLAW_OTEL_PRELOADED=1`：供已註冊全域 OpenTelemetry SDK 的主機使用的環境開關。OpenClaw 接著會略過 Plugin 擁有的 SDK 啟動/關閉，同時保持診斷監聽器啟用。
-- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：當相符設定鍵未設定時使用的訊號專用端點環境變數。
-- `cacheTrace.enabled`：記錄嵌入式執行的快取追蹤快照（預設：`false`）。
+- `otel.flushIntervalMs`：定期遙測資料清出間隔，單位為毫秒。
+- `otel.captureContent`：選擇性啟用 OTEL span 屬性的原始內容擷取。預設關閉。布林值 `true` 會擷取非系統訊息/工具內容；物件形式可讓你明確啟用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
+- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：最新實驗性 GenAI span 提供者屬性的環境開關。預設情況下，span 會保留舊版 `gen_ai.system` 屬性以維持相容性；GenAI 指標會使用有界語意屬性。
+- `OPENCLAW_OTEL_PRELOADED=1`：主機已註冊全域 OpenTelemetry SDK 時使用的環境開關。OpenClaw 接著會略過 Plugin 擁有的 SDK 啟動/關閉，同時保持診斷監聽器作用中。
+- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：當相符設定鍵未設定時使用的訊號專屬端點環境變數。
+- `cacheTrace.enabled`：為嵌入式執行記錄快取追蹤快照（預設：`false`）。
 - `cacheTrace.filePath`：快取追蹤 JSONL 的輸出路徑（預設：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
-- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制快取追蹤輸出包含的內容（全部預設：`true`）。
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制快取追蹤輸出中包含的內容（全部預設：`true`）。
 
 ---
 
@@ -950,12 +961,12 @@ openclaw gateway --port 19001
 }
 ```
 
-- `channel`：npm/git 安裝的發布頻道 — `"stable"`、`"beta"` 或 `"dev"`。
+- `channel`：npm/git 安裝的發行通道，為 `"stable"`、`"beta"` 或 `"dev"`。
 - `checkOnStart`：Gateway 啟動時檢查 npm 更新（預設：`true`）。
-- `auto.enabled`：啟用套件安裝的背景自動更新（預設：`false`）。
-- `auto.stableDelayHours`：stable 頻道自動套用前的最短延遲小時數（預設：`6`；最大：`168`）。
-- `auto.stableJitterHours`：額外的 stable 頻道推出分散視窗小時數（預設：`12`；最大：`168`）。
-- `auto.betaCheckIntervalHours`：beta 頻道檢查執行的頻率，以小時為單位（預設：`1`；最大：`24`）。
+- `auto.enabled`：為套件安裝啟用背景自動更新（預設：`false`）。
+- `auto.stableDelayHours`：穩定通道自動套用前的最短延遲小時數（預設：`6`；最大：`168`）。
+- `auto.stableJitterHours`：穩定通道推出額外分散時窗的小時數（預設：`12`；最大：`168`）。
+- `auto.betaCheckIntervalHours`：beta 通道檢查執行頻率的小時數（預設：`1`；最大：`24`）。
 
 ---
 
@@ -988,23 +999,23 @@ openclaw gateway --port 19001
 }
 ```
 
-- `enabled`：全域 ACP 功能閘門（預設：`true`；設為 `false` 可隱藏 ACP 派送和產生操作）。
-- `dispatch.enabled`：ACP 工作階段回合派送的獨立閘門（預設：`true`）。設為 `false` 可保留 ACP 命令可用，同時阻止執行。
+- `enabled`：全域 ACP 功能門檻（預設：`true`；設為 `false` 可隱藏 ACP 派送與生成操作）。
+- `dispatch.enabled`：ACP 工作階段回合派送的獨立門檻（預設：`true`）。設為 `false` 可保留 ACP 命令可用，同時阻止執行。
 - `backend`：預設 ACP 執行階段後端 ID（必須符合已註冊的 ACP 執行階段 Plugin）。
-  請先安裝後端 Plugin；如果設定了 `plugins.allow`，請包含後端 Plugin ID（例如 `acpx`），否則 ACP 後端不會載入。
-- `defaultAgent`：當產生未指定明確目標時的 ACP 目標代理 ID 後援。
+  請先安裝後端 Plugin；若已設定 `plugins.allow`，請包含後端 Plugin ID（例如 `acpx`），否則 ACP 後端不會載入。
+- `defaultAgent`：當生成未指定明確目標時使用的備援 ACP 目標代理 ID。
 - `allowedAgents`：允許用於 ACP 執行階段工作階段的代理 ID 允許清單；空白表示沒有額外限制。
 - `maxConcurrentSessions`：同時作用中的 ACP 工作階段最大數量。
-- `stream.coalesceIdleMs`：串流文字的閒置清出視窗，單位為 ms。
+- `stream.coalesceIdleMs`：串流文字的閒置清出時窗，單位為毫秒。
 - `stream.maxChunkChars`：分割串流區塊投影前的最大區塊大小。
-- `stream.repeatSuppression`：每回合抑制重複狀態/工具行（預設：`true`）。
+- `stream.repeatSuppression`：每個回合抑制重複的狀態/工具行（預設：`true`）。
 - `stream.deliveryMode`：`"live"` 會增量串流；`"final_only"` 會緩衝到回合終止事件。
 - `stream.hiddenBoundarySeparator`：隱藏工具事件後、可見文字前的分隔符（預設：`"paragraph"`）。
-- `stream.maxOutputChars`：每個 ACP 回合投影的助理輸出字元上限。
-- `stream.maxSessionUpdateChars`：投影 ACP 狀態/更新行的字元上限。
+- `stream.maxOutputChars`：每個 ACP 回合投影的助理輸出最大字元數。
+- `stream.maxSessionUpdateChars`：投影 ACP 狀態/更新行的最大字元數。
 - `stream.tagVisibility`：標籤名稱到串流事件布林可見性覆寫的記錄。
-- `runtime.ttlMinutes`：ACP 工作階段 worker 可清理前的閒置 TTL，單位為分鐘。
-- `runtime.installCommand`：引導 ACP 執行階段環境時要執行的選用安裝命令。
+- `runtime.ttlMinutes`：ACP 工作階段工作器符合清理條件前的閒置 TTL 分鐘數。
+- `runtime.installCommand`：啟動 ACP 執行階段環境時要執行的可選安裝命令。
 
 ---
 
@@ -1021,9 +1032,9 @@ openclaw gateway --port 19001
 ```
 
 - `cli.banner.taglineMode` 控制橫幅標語樣式：
-  - `"random"`（預設）：輪替的有趣/季節性標語。
-  - `"default"`：固定中性標語（`All your chats, one OpenClaw.`）。
-  - `"off"`：沒有標語文字（仍會顯示橫幅標題/版本）。
+  - `"random"`（預設）：輪換的趣味/季節性標語。
+  - `"default"`：固定的中性標語（`All your chats, one OpenClaw.`）。
+  - `"off"`：無標語文字（仍會顯示橫幅標題/版本）。
 - 若要隱藏整個橫幅（不只是標語），請設定環境變數 `OPENCLAW_HIDE_BANNER=1`。
 
 ---
@@ -1054,7 +1065,7 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 
 ## 橋接器（舊版，已移除）
 
-目前建置不再包含 TCP 橋接器。Node 會透過 Gateway WebSocket 連線。`bridge.*` 鍵不再是設定結構描述的一部分（驗證會失敗，直到移除為止；`openclaw doctor --fix` 可以刪除未知鍵）。
+目前版本不再包含 TCP 橋接器。Node 會透過 Gateway WebSocket 連線。`bridge.*` 鍵不再屬於設定結構描述（驗證會失敗，直到移除為止；`openclaw doctor --fix` 可移除未知鍵）。
 
 <Accordion title="舊版橋接器設定（歷史參考）">
 
@@ -1094,11 +1105,11 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 }
 ```
 
-- `sessionRetention`：在從 `sessions.json` 剪除前，已完成的隔離 Cron 執行工作階段要保留多久。也控制已封存且刪除的 Cron 逐字稿清理。預設：`24h`；設為 `false` 可停用。
-- `runLog.maxBytes`：剪除前每個執行記錄檔（`cron/runs/<jobId>.jsonl`）的最大大小。預設：`2_000_000` 位元組。
-- `runLog.keepLines`：觸發執行記錄剪除時保留的最新行數。預設：`2000`。
-- `webhookToken`：用於 Cron Webhook POST 傳遞（`delivery.mode = "webhook"`）的 bearer token；若省略則不會傳送授權標頭。
-- `webhook`：已棄用的舊版後援 Webhook URL（http/https），僅用於仍具有 `notify: true` 的已儲存工作。
+- `sessionRetention`：在從 `sessions.json` 修剪前，保留已完成隔離 Cron 執行工作階段的時間長度。也會控制已封存刪除 Cron 逐字稿的清理。預設：`24h`；設為 `false` 可停用。
+- `runLog.maxBytes`：修剪前每個執行記錄檔（`cron/runs/<jobId>.jsonl`）的最大大小。預設：`2_000_000` 位元組。
+- `runLog.keepLines`：觸發執行記錄修剪時保留的最新行數。預設：`2000`。
+- `webhookToken`：用於 Cron Webhook POST 傳遞（`delivery.mode = "webhook"`）的 bearer token；若省略，則不會傳送驗證標頭。
+- `webhook`：已棄用的舊版備援 Webhook URL（http/https），僅用於仍具有 `notify: true` 的已儲存工作。
 
 ### `cron.retry`
 
@@ -1114,11 +1125,11 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 }
 ```
 
-- `maxAttempts`：一次性工作在暫時性錯誤上的最大重試次數（預設：`3`；範圍：`0`–`10`）。
-- `backoffMs`：每次重試嘗試的退避延遲陣列，單位為毫秒（預設：`[30000, 60000, 300000]`；1–10 個項目）。
-- `retryOn`：會觸發重試的錯誤類型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略時會重試所有暫時性類型。
+- `maxAttempts`: 一次性作業在暫時性錯誤時的最大重試次數（預設值：`3`；範圍：`0`–`10`）。
+- `backoffMs`: 每次重試嘗試的退避延遲陣列，單位為毫秒（預設值：`[30000, 60000, 300000]`；1–10 個項目）。
+- `retryOn`: 會觸發重試的錯誤類型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略時會重試所有暫時性類型。
 
-僅適用於一次性 Cron 工作。週期性工作使用獨立的失敗處理。
+僅適用於一次性 Cron 作業。週期性作業使用獨立的失敗處理。
 
 ### `cron.failureAlert`
 
@@ -1137,12 +1148,12 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 }
 ```
 
-- `enabled`：啟用 Cron 工作的失敗警示（預設：`false`）。
-- `after`：觸發警示前的連續失敗次數（正整數，最小值：`1`）。
-- `cooldownMs`：同一工作重複警示之間的最小毫秒數（非負整數）。
-- `includeSkipped`：將連續略過的執行次數計入警示門檻（預設：`false`）。略過的執行會分開追蹤，且不會影響執行錯誤的退避。
-- `mode`：傳送模式 — `"announce"` 會透過通道訊息傳送；`"webhook"` 會發布到已設定的 Webhook。
-- `accountId`：可選的帳號或通道 id，用於限定警示傳送範圍。
+- `enabled`: 啟用 Cron 作業的失敗警示（預設值：`false`）。
+- `after`: 觸發警示前的連續失敗次數（正整數，最小值：`1`）。
+- `cooldownMs`: 同一作業重複警示之間的最小毫秒數（非負整數）。
+- `includeSkipped`: 將連續略過的執行計入警示門檻（預設值：`false`）。略過的執行會分開追蹤，且不會影響執行錯誤退避。
+- `mode`: 傳遞模式 — `"announce"` 透過頻道訊息傳送；`"webhook"` 會發佈到已設定的 Webhook。
+- `accountId`: 選用的帳戶或頻道 ID，用來限定警示傳遞範圍。
 
 ### `cron.failureDestination`
 
@@ -1159,16 +1170,16 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 }
 ```
 
-- 所有工作的 Cron 失敗通知預設目的地。
-- `mode`：`"announce"` 或 `"webhook"`；當有足夠目標資料時，預設為 `"announce"`。
-- `channel`：公告傳送的通道覆寫。`"last"` 會重用最後已知的傳送通道。
-- `to`：明確的公告目標或 Webhook URL。Webhook 模式需要此項。
-- `accountId`：可選的傳送帳號覆寫。
-- 每個工作的 `delivery.failureDestination` 會覆寫此全域預設值。
-- 當未設定全域或每個工作的失敗目的地時，已透過 `announce` 傳送的工作會在失敗時退回使用該主要公告目標。
-- `delivery.failureDestination` 僅支援 `sessionTarget="isolated"` 工作，除非該工作的主要 `delivery.mode` 是 `"webhook"`。
+- 所有作業 Cron 失敗通知的預設目的地。
+- `mode`: `"announce"` 或 `"webhook"`；當存在足夠目標資料時，預設為 `"announce"`。
+- `channel`: announce 傳遞的頻道覆寫。`"last"` 會重用上一個已知的傳遞頻道。
+- `to`: 明確的 announce 目標或 Webhook URL。Webhook 模式必填。
+- `accountId`: 選用的傳遞帳戶覆寫。
+- 每項作業的 `delivery.failureDestination` 會覆寫此全域預設值。
+- 當全域與每項作業的失敗目的地都未設定時，已透過 `announce` 傳遞的作業，會在失敗時退回使用該主要 announce 目標。
+- `delivery.failureDestination` 只支援 `sessionTarget="isolated"` 作業，除非該作業的主要 `delivery.mode` 為 `"webhook"`。
 
-請參閱 [Cron 工作](/zh-TW/automation/cron-jobs)。隔離的 Cron 執行會以[背景任務](/zh-TW/automation/tasks)追蹤。
+請參閱 [Cron 作業](/zh-TW/automation/cron-jobs)。隔離的 Cron 執行會作為[背景任務](/zh-TW/automation/tasks)追蹤。
 
 ---
 
@@ -1176,34 +1187,34 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 
 在 `tools.media.models[].args` 中展開的範本預留位置：
 
-| 變數               | 說明                                              |
+| 變數               | 說明                                             |
 | ------------------ | ------------------------------------------------- |
-| `{{Body}}`         | 完整的傳入訊息本文                                |
-| `{{RawBody}}`      | 原始本文（無歷史/傳送者包裝）                     |
-| `{{BodyStripped}}` | 移除群組提及後的本文                              |
-| `{{From}}`         | 傳送者識別碼                                      |
-| `{{To}}`           | 目的地識別碼                                      |
-| `{{MessageSid}}`   | 通道訊息 id                                       |
-| `{{SessionId}}`    | 目前的工作階段 UUID                               |
-| `{{IsNewSession}}` | 建立新工作階段時為 `"true"`                       |
-| `{{MediaUrl}}`     | 傳入媒體偽 URL                                    |
-| `{{MediaPath}}`    | 本機媒體路徑                                      |
-| `{{MediaType}}`    | 媒體類型（圖片/音訊/文件/…）                      |
-| `{{Transcript}}`   | 音訊逐字稿                                        |
-| `{{Prompt}}`       | CLI 項目的已解析媒體提示                          |
-| `{{MaxChars}}`     | CLI 項目的已解析最大輸出字元數                    |
-| `{{ChatType}}`     | `"direct"` 或 `"group"`                           |
-| `{{GroupSubject}}` | 群組主旨（盡力取得）                              |
-| `{{GroupMembers}}` | 群組成員預覽（盡力取得）                          |
-| `{{SenderName}}`   | 傳送者顯示名稱（盡力取得）                        |
-| `{{SenderE164}}`   | 傳送者電話號碼（盡力取得）                        |
-| `{{Provider}}`     | Provider 提示（WhatsApp、Telegram、Discord 等）   |
+| `{{Body}}`         | 完整的傳入訊息本文                              |
+| `{{RawBody}}`      | 原始本文（不含歷史記錄/寄件者包裝）             |
+| `{{BodyStripped}}` | 已移除群組提及的本文                            |
+| `{{From}}`         | 寄件者識別碼                                    |
+| `{{To}}`           | 目的地識別碼                                    |
+| `{{MessageSid}}`   | 頻道訊息 ID                                     |
+| `{{SessionId}}`    | 目前工作階段 UUID                               |
+| `{{IsNewSession}}` | 建立新工作階段時為 `"true"`                     |
+| `{{MediaUrl}}`     | 傳入媒體偽 URL                                  |
+| `{{MediaPath}}`    | 本機媒體路徑                                    |
+| `{{MediaType}}`    | 媒體類型（image/audio/document/…）               |
+| `{{Transcript}}`   | 音訊逐字稿                                      |
+| `{{Prompt}}`       | CLI 項目的已解析媒體提示                        |
+| `{{MaxChars}}`     | CLI 項目的已解析最大輸出字元數                  |
+| `{{ChatType}}`     | `"direct"` 或 `"group"`                          |
+| `{{GroupSubject}}` | 群組主旨（盡力提供）                            |
+| `{{GroupMembers}}` | 群組成員預覽（盡力提供）                        |
+| `{{SenderName}}`   | 寄件者顯示名稱（盡力提供）                      |
+| `{{SenderE164}}`   | 寄件者電話號碼（盡力提供）                      |
+| `{{Provider}}`     | Provider 提示（whatsapp、telegram、discord 等）  |
 
 ---
 
-## 設定包含 (`$include`)
+## 設定包含項目（`$include`）
 
-將設定拆分成多個檔案：
+將設定拆分為多個檔案：
 
 ```json5
 // ~/.openclaw/openclaw.json
@@ -1219,13 +1230,13 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼
 **合併行為：**
 
 - 單一檔案：取代包含它的物件。
-- 檔案陣列：依序深度合併（後者覆寫前者）。
-- 同層鍵：在包含項目之後合併（覆寫包含的值）。
-- 巢狀包含：最多 10 層深。
-- 路徑：相對於進行包含的檔案解析，但必須保留在最上層設定目錄內（`openclaw.json` 的 `dirname`）。只有在解析後仍位於該邊界內時，才允許絕對路徑/`../` 形式。
-- 由 OpenClaw 擁有的寫入若只變更由單一檔案包含支援的一個最上層區段，會直接寫入該包含檔案。例如，`plugins install` 會在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，並讓 `openclaw.json` 保持不變。
-- 根包含、包含陣列，以及含有同層覆寫的包含，對 OpenClaw 擁有的寫入為唯讀；這些寫入會封閉失敗，而不是攤平設定。
-- 錯誤：針對遺失檔案、剖析錯誤和循環包含提供清楚訊息。
+- 檔案陣列：依序深度合併（後面的會覆寫前面的）。
+- 同層鍵：在包含項目之後合併（覆寫已包含的值）。
+- 巢狀包含項目：最多深入 10 層。
+- 路徑：相對於進行包含的檔案解析，但必須留在頂層設定目錄（`openclaw.json` 的 `dirname`）內。只有在解析後仍位於該邊界內時，才允許絕對路徑/`../` 形式。
+- OpenClaw 擁有且只變更單一頂層區段的寫入，如果該區段由單一檔案包含項目支援，會直寫至該包含檔案。例如，`plugins install` 會在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，並讓 `openclaw.json` 保持不變。
+- 根包含項目、包含陣列，以及具有同層覆寫的包含項目，對 OpenClaw 擁有的寫入是唯讀；這些寫入會關閉並失敗，而不是將設定扁平化。
+- 錯誤：針對檔案遺失、解析錯誤與循環包含提供清楚訊息。
 
 ---
 

docs/zh-TW/gateway/diagnostics.md

@@ -1,22 +1,25 @@
 ---
 read_when:
     - 準備錯誤報告或支援請求
-    - 偵錯 Gateway 當機、重新啟動、記憶體壓力或過大的承載資料
-    - 檢閱已記錄或已遮蔽的診斷資料
-summary: 建立可分享的 Gateway 診斷資料包以供錯誤回報
+    - 偵錯 Gateway 當機、重新啟動、記憶體壓力或過大的酬載
+    - 檢視哪些診斷資料會被記錄或遮蔽
+summary: 建立可分享的 Gateway 診斷套件，用於錯誤報告
 title: 診斷資料匯出
 x-i18n:
-    generated_at: "2026-05-03T21:32:57Z"
+    generated_at: "2026-05-05T01:46:04Z"
     model: gpt-5.5
     provider: openai
-    source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b
+    source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382
     source_path: gateway/diagnostics.md
     workflow: 16
 ---
 
-OpenClaw 可以建立本機診斷 zip，供錯誤回報使用。它會合併經過清理的 Gateway 狀態、健康狀態、日誌、設定形狀，以及最近不含承載資料的穩定性事件。
+OpenClaw 可以為錯誤回報建立本機診斷 zip。它會合併
+經過清理的 Gateway 狀態、健康狀態、記錄、設定形狀，以及近期不含酬載的
+穩定性事件。
 
-在你檢閱之前，請把診斷套件視為秘密資訊。它們設計上會省略或遮蔽承載資料與憑證，但仍會摘要本機 Gateway 日誌與主機層級的執行階段狀態。
+在你檢視診斷封包之前，請將其視為機密。它們的設計會省略或遮蔽酬載與憑證，
+但仍會摘要本機 Gateway 記錄與主機層級的執行階段狀態。
 
 ## 快速開始
 
@@ -38,55 +41,91 @@ openclaw gateway diagnostics export --json
 
 ## 聊天命令
 
-擁有者可以在聊天中使用 `/diagnostics [note]` 來要求本機 Gateway 匯出。當錯誤發生在真實對話中，而你想要一份可複製貼上的支援回報時，請使用此方式：
+擁有者可以在聊天中使用 `/diagnostics [note]` 來要求匯出本機 Gateway。
+當錯誤發生在真實對話中，且你希望取得一份可複製貼上的支援回報時，
+請使用此命令：
 
-1. 在你注意到問題的對話中傳送 `/diagnostics`。如果有幫助，可以加上一段簡短註記，例如 `/diagnostics bad tool choice`。
-2. OpenClaw 會傳送診斷前言，並要求一次明確的 exec 核准。該核准會執行 `openclaw gateway diagnostics export --json`。請勿透過全部允許規則核准診斷。
-3. 核准後，OpenClaw 會回覆一份可貼上的報告，其中包含本機套件路徑、清單摘要、隱私權註記，以及相關工作階段 ID。
+1. 在你注意到問題的對話中傳送 `/diagnostics`。如果有幫助，可以加入
+   簡短備註，例如 `/diagnostics bad tool choice`。
+2. OpenClaw 會傳送診斷前言，並要求一次明確的 exec 核准。
+   該核准會執行 `openclaw gateway diagnostics export --json`。
+   不要透過允許全部的規則核准診斷。
+3. 核准後，OpenClaw 會回覆一份可貼上的回報，其中包含本機封包路徑、
+   manifest 摘要、隱私注意事項，以及相關工作階段 ID。
 
-在群組聊天中，擁有者仍可執行 `/diagnostics`，但 OpenClaw 不會把診斷詳細資料發回共用聊天。它會透過私人核准路徑，將前言、核准提示、Gateway 匯出結果，以及 Codex 工作階段/執行緒明細傳送給擁有者。群組只會收到一則簡短通知，說明診斷流程已私下傳送。如果 OpenClaw 找不到私人的擁有者路徑，命令會以關閉方式失敗，並要求擁有者從 DM 執行它。
+在群組聊天中，擁有者仍可執行 `/diagnostics`，但 OpenClaw 不會
+將診斷詳細資料貼回共享聊天。它會透過私有核准路由，將前言、核准提示、
+Gateway 匯出結果，以及 Codex 工作階段/執行緒明細傳送給擁有者。
+群組只會收到一則簡短通知，表示診斷流程已私下傳送。如果 OpenClaw 找不到
+私有擁有者路由，該命令會安全失敗，並要求擁有者從 DM 執行。
 
-當作用中的 OpenClaw 工作階段使用原生 OpenAI Codex harness 時，同一次 exec 核准也會涵蓋針對 OpenClaw 所知 Codex 執行階段執行緒的 OpenAI 回饋上傳。該上傳與本機 Gateway zip 分開，而且只會出現在 Codex harness 工作階段。核准前，提示會說明核准診斷也會傳送 Codex 回饋，但不會列出 Codex 工作階段或執行緒 ID。核准後，聊天回覆會列出已傳送到 OpenAI 伺服器的頻道、OpenClaw 工作階段 ID、Codex 執行緒 ID，以及本機續用命令。如果你拒絕或忽略核准，OpenClaw 不會執行匯出、不會傳送 Codex 回饋，也不會列印 Codex ID。
+當作用中的 OpenClaw 工作階段正在使用原生 OpenAI Codex 框架時，
+同一個 exec 核准也會涵蓋針對 OpenClaw 已知 Codex 執行階段執行緒的
+OpenAI 意見回饋上傳。該上傳與本機 Gateway zip 分開，且只會出現在
+Codex 框架工作階段中。核准前，提示會說明核准診斷也會傳送 Codex
+意見回饋，但不會列出 Codex 工作階段或執行緒 ID。核准後，聊天回覆會列出
+已傳送到 OpenAI 伺服器的頻道、OpenClaw 工作階段 ID、Codex 執行緒 ID，
+以及本機繼續命令。如果你拒絕或忽略核准，OpenClaw 不會執行匯出、
+不會傳送 Codex 意見回饋，也不會列印 Codex ID。
 
-這讓常見的 Codex 偵錯迴圈變得很短：在 Telegram、Discord 或其他頻道中注意到不良行為，執行 `/diagnostics`，核准一次，將報告分享給支援人員，接著如果你想自行檢查原生 Codex 執行緒，就在本機執行列印出的 `codex resume <thread-id>` 命令。該檢查工作流程請參閱 [Codex harness](/zh-TW/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)。
+這讓常見的 Codex 偵錯循環很短：在 Telegram、Discord 或其他頻道中
+注意到不良行為，執行 `/diagnostics`，核准一次，將回報分享給支援人員，
+然後如果你想自行檢查原生 Codex 執行緒，就在本機執行列印出的
+`codex resume <thread-id>` 命令。該檢查工作流程請參閱
+[Codex 框架](/zh-TW/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)。
 
 ## 匯出內容
 
-zip 包含：
+此 zip 包含：
 
 - `summary.md`：供支援人員閱讀的人類可讀概覽。
-- `diagnostics.json`：設定、日誌、狀態、健康狀態與穩定性資料的機器可讀摘要。
+- `diagnostics.json`：設定、記錄、狀態、健康狀態與穩定性資料的機器可讀摘要。
 - `manifest.json`：匯出中繼資料與檔案清單。
-- 經清理的設定形狀與非秘密設定詳細資料。
-- 經清理的日誌摘要與最近經遮蔽的日誌行。
-- 盡力而為的 Gateway 狀態與健康狀態快照。
-- `stability/latest.json`：可用時，最新保存的穩定性套件。
+- 經過清理的設定形狀與非機密設定細節。
+- 經過清理的記錄摘要，以及近期已遮蔽的記錄行。
+- 盡力取得的 Gateway 狀態與健康快照。
+- `stability/latest.json`：可用時的最新持久化穩定性封包。
 
-即使 Gateway 不健康，此匯出仍很有用。如果 Gateway 無法回應狀態或健康狀態請求，本機日誌、設定形狀與最新穩定性套件仍會在可用時被收集。
+即使 Gateway 不健康，匯出仍然有用。如果 Gateway 無法回應狀態或健康請求，
+仍會在可用時收集本機記錄、設定形狀與最新穩定性封包。
 
-## 隱私權模型
+## 隱私模型
 
-診斷設計為可分享。匯出會保留有助於偵錯的操作資料，例如：
+診斷的設計目標是可供分享。匯出會保留有助於偵錯的操作資料，例如：
 
-- 子系統名稱、Plugin ID、提供者 ID、頻道 ID，以及已設定的模式
-- 狀態碼、持續時間、位元組計數、佇列狀態與記憶體讀數
-- 經清理的日誌中繼資料與經遮蔽的操作訊息
-- 設定形狀與非秘密功能設定
+- 子系統名稱、Plugin ID、供應商 ID、頻道 ID，以及已設定的模式
+- 狀態碼、持續時間、位元組數、佇列狀態，以及記憶體讀數
+- 經過清理的記錄中繼資料，以及已遮蔽的操作訊息
+- 設定形狀與非機密功能設定
 
 匯出會省略或遮蔽：
 
-- 聊天文字、提示、指示、Webhook 內文與工具輸出
-- 憑證、API 金鑰、權杖、Cookie 與秘密值
+- 聊天文字、提示、指令、Webhook 內文，以及工具輸出
+- 憑證、API 金鑰、權杖、Cookie，以及機密值
 - 原始請求或回應內文
-- 帳號 ID、訊息 ID、原始工作階段 ID、主機名稱與本機使用者名稱
+- 帳號 ID、訊息 ID、原始工作階段 ID、主機名稱，以及本機使用者名稱
 
-當日誌訊息看起來像使用者、聊天、提示或工具承載文字時，匯出只會保留某則訊息已被省略以及位元組計數。
+當記錄訊息看起來像使用者、聊天、提示或工具酬載文字時，
+匯出只會保留訊息已被省略，以及位元組數。
 
 ## 穩定性記錄器
 
-啟用診斷時，Gateway 預設會記錄一個有界且不含承載資料的穩定性串流。它用於操作事實，而不是內容。
+當診斷啟用時，Gateway 預設會記錄有界且不含酬載的穩定性串流。
+它用於操作事實，而不是內容。
 
-當 Gateway 持續執行但 Node.js 事件迴圈或 CPU 看起來飽和時，同一個診斷 Heartbeat 會記錄存活性樣本。這些 `diagnostic.liveness.warning` 事件包含事件迴圈延遲、事件迴圈使用率、CPU 核心比率，以及作用中/等待中/已佇列的工作階段計數。閒置樣本會以 `info` 層級保留在遙測中。只有在工作正在等待或佇列中，或作用中工作與持續事件迴圈延遲重疊時，存活性樣本才會成為 Gateway 警告。在其他健康的背景工作期間，短暫的最大延遲尖峰會留在偵錯日誌中。它們本身不會重新啟動 Gateway。
+當 Gateway 持續執行，但 Node.js 事件迴圈或 CPU 看似飽和時，
+同一個診斷 Heartbeat 會記錄存活性樣本。這些
+`diagnostic.liveness.warning` 事件包含事件迴圈延遲、事件迴圈使用率、
+CPU 核心比率、作用中/等待中/已佇列的工作階段數、已知時的目前啟動/執行階段階段、
+近期階段區間，以及有界的作用中/已佇列工作標籤。閒置樣本會以 `info`
+層級保留在遙測中。只有當工作正在等待或已佇列，或作用中工作與持續事件迴圈延遲重疊時，
+存活性樣本才會成為 Gateway 警告。在其他方面健康的背景工作期間發生的短暫最大延遲尖峰，
+會保留在除錯記錄中。它們本身不會重新啟動 Gateway。
+
+啟動階段也會發出 `diagnostic.phase.completed` 事件，其中包含牆鐘時間與
+CPU 計時。停滯的內嵌執行診斷會在最後一次橋接進度看似終止時，
+例如原始回應項目或回應完成事件，但 Gateway 仍認為內嵌執行處於作用中，
+標記 `terminalProgressStale=true`。
 
 檢查即時記錄器：
 
@@ -96,19 +135,19 @@ openclaw gateway stability --type payload.large
 openclaw gateway stability --json
 ```
 
-在致命結束、關機逾時或重新啟動啟動失敗後，檢查最新保存的穩定性套件：
+在致命結束、關閉逾時或重新啟動啟動失敗後，檢查最新的持久化穩定性封包：
 
 ```bash
 openclaw gateway stability --bundle latest
 ```
 
-從最新保存的套件建立診斷 zip：
+從最新的持久化封包建立診斷 zip：
 
 ```bash
 openclaw gateway stability --bundle latest --export
 ```
 
-當事件存在時，保存的套件位於 `~/.openclaw/logs/stability/` 之下。
+當事件存在時，持久化封包會位於 `~/.openclaw/logs/stability/` 之下。
 
 ## 實用選項
 
@@ -120,13 +159,13 @@ openclaw gateway diagnostics export \
 ```
 
 - `--output <path>`：寫入特定 zip 路徑。
-- `--log-lines <count>`：要包含的最大清理後日誌行數。
-- `--log-bytes <bytes>`：要檢查的最大日誌位元組數。
-- `--url <url>`：用於狀態與健康狀態快照的 Gateway WebSocket URL。
-- `--token <token>`：用於狀態與健康狀態快照的 Gateway 權杖。
-- `--password <password>`：用於狀態與健康狀態快照的 Gateway 密碼。
-- `--timeout <ms>`：狀態與健康狀態快照逾時。
-- `--no-stability-bundle`：略過保存的穩定性套件查詢。
+- `--log-lines <count>`：要包含的最大清理後記錄行數。
+- `--log-bytes <bytes>`：要檢查的最大記錄位元組數。
+- `--url <url>`：用於狀態與健康快照的 Gateway WebSocket URL。
+- `--token <token>`：用於狀態與健康快照的 Gateway 權杖。
+- `--password <password>`：用於狀態與健康快照的 Gateway 密碼。
+- `--timeout <ms>`：狀態與健康快照逾時。
+- `--no-stability-bundle`：略過持久化穩定性封包查詢。
 - `--json`：列印機器可讀的匯出中繼資料。
 
 ## 停用診斷
@@ -141,12 +180,12 @@ openclaw gateway diagnostics export \
 }
 ```
 
-停用診斷會減少錯誤回報細節。它不會影響一般 Gateway 日誌記錄。
+停用診斷會減少錯誤回報細節。它不會影響一般 Gateway 記錄。
 
 ## 相關
 
 - [健康檢查](/zh-TW/gateway/health)
 - [Gateway CLI](/zh-TW/cli/gateway#gateway-diagnostics-export)
 - [Gateway protocol](/zh-TW/gateway/protocol#system-and-identity)
-- [日誌記錄](/zh-TW/logging)
-- [OpenTelemetry 匯出](/zh-TW/gateway/opentelemetry) — 將診斷串流到收集器的獨立流程
+- [記錄](/zh-TW/logging)
+- [OpenTelemetry 匯出](/zh-TW/gateway/opentelemetry) — 將串流診斷傳送到收集器的獨立流程

docs/zh-TW/gateway/doctor.md

@@ -3,18 +3,18 @@ read_when:
     - 新增或修改 doctor 遷移
     - 引入破壞性設定變更
 sidebarTitle: Doctor
-summary: Doctor 命令：健康檢查、設定遷移與修復步驟
+summary: Doctor 指令：健康檢查、設定遷移與修復步驟
 title: 診斷工具
 x-i18n:
-    generated_at: "2026-05-04T09:36:55Z"
+    generated_at: "2026-05-05T01:46:10Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
+    source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d
     source_path: gateway/doctor.md
     workflow: 16
 ---
 
-`openclaw doctor` 是 OpenClaw 的修復與遷移工具。它會修正過時的設定/狀態、檢查健康狀態，並提供可執行的修復步驟。
+`openclaw doctor` 是 OpenClaw 的修復 + 遷移工具。它會修復過期的設定/狀態、檢查健康狀態，並提供可執行的修復步驟。
 
 ## 快速開始
 
@@ -22,7 +22,7 @@ x-i18n:
 openclaw doctor
 ```
 
-### Headless 與自動化模式
+### 無介面與自動化模式
 
 <Tabs>
   <Tab title="--yes">
@@ -30,7 +30,7 @@ openclaw doctor
     openclaw doctor --yes
     ```
 
-    不提示就接受預設值（包含適用時的重新啟動/服務/沙盒修復步驟）。
+    不提示而接受預設值（適用時包括重新啟動/服務/沙箱修復步驟）。
 
   </Tab>
   <Tab title="--repair">
@@ -38,7 +38,7 @@ openclaw doctor
     openclaw doctor --repair
     ```
 
-    不提示就套用建議的修復（安全時包含修復與重新啟動）。
+    不提示而套用建議修復（在安全情況下包含修復 + 重新啟動）。
 
   </Tab>
   <Tab title="--repair --force">
@@ -46,7 +46,7 @@ openclaw doctor
     openclaw doctor --repair --force
     ```
 
-    也套用更積極的修復（會覆寫自訂 supervisor 設定）。
+    也套用侵入性較高的修復（會覆寫自訂 supervisor 設定）。
 
   </Tab>
   <Tab title="--non-interactive">
@@ -54,7 +54,7 @@ openclaw doctor
     openclaw doctor --non-interactive
     ```
 
-    在不提示的情況下執行，且只套用安全遷移（設定正規化 + 磁碟狀態搬移）。略過需要人工確認的重新啟動/服務/沙盒動作。偵測到舊版狀態遷移時會自動執行。
+    在不提示的情況下執行，且只套用安全遷移（設定正規化 + 磁碟上的狀態移動）。略過需要人工確認的重新啟動/服務/沙箱動作。偵測到舊版狀態遷移時會自動執行。
 
   </Tab>
   <Tab title="--deep">
@@ -62,7 +62,7 @@ openclaw doctor
     openclaw doctor --deep
     ```
 
-    掃描系統服務以找出額外的 gateway 安裝（launchd/systemd/schtasks）。
+    掃描系統服務以尋找額外的 Gateway 安裝（launchd/systemd/schtasks）。
 
   </Tab>
 </Tabs>
@@ -78,114 +78,114 @@ cat ~/.openclaw/openclaw.json
 <AccordionGroup>
   <Accordion title="健康狀態、UI 與更新">
     - git 安裝的選用前置更新（僅限互動模式）。
-    - UI 通訊協定新鮮度檢查（當通訊協定 schema 較新時重建 Control UI）。
-    - 健康狀態檢查 + 重新啟動提示。
-    - Skills 狀態摘要（符合資格/缺少/已封鎖）與 plugin 狀態。
+    - UI 通訊協定新鮮度檢查（當通訊協定結構描述較新時重建 Control UI）。
+    - 健康檢查 + 重新啟動提示。
+    - Skills 狀態摘要（符合資格/缺少/被封鎖）與 Plugin 狀態。
 
   </Accordion>
   <Accordion title="設定與遷移">
     - 舊版值的設定正規化。
-    - Talk 設定從舊版扁平 `talk.*` 欄位遷移到 `talk.provider` + `talk.providers.<provider>`。
-    - 舊版 Chrome 擴充功能設定與 Chrome MCP 就緒狀態的瀏覽器遷移檢查。
+    - 將 Talk 設定從舊版扁平 `talk.*` 欄位遷移到 `talk.provider` + `talk.providers.<provider>`。
+    - 針對舊版 Chrome extension 設定與 Chrome MCP 就緒狀態的瀏覽器遷移檢查。
     - OpenCode provider 覆寫警告（`models.providers.opencode` / `models.providers.opencode-go`）。
     - Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
     - OpenAI Codex OAuth 設定檔的 OAuth TLS 先決條件檢查。
-    - 當 `plugins.allow` 具限制性，但工具政策仍要求萬用字元或 plugin 擁有的工具時，發出 Plugin/工具允許清單警告。
+    - 當 `plugins.allow` 具限制性但工具政策仍要求萬用字元或 Plugin 所有工具時，發出 Plugin/工具允許清單警告。
     - 舊版磁碟狀態遷移（sessions/agent dir/WhatsApp auth）。
-    - 舊版 plugin manifest contract key 遷移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。
-    - 舊版 cron store 遷移（`jobId`, `schedule.cron`, 頂層 delivery/payload 欄位、payload `provider`、簡單 `notify: true` webhook 後援 jobs）。
-    - 舊版 agent runtime-policy 遷移到 `agents.defaults.agentRuntime` 與 `agents.list[].agentRuntime`。
-    - 啟用 plugins 時清理過時 plugin 設定；當 `plugins.enabled=false` 時，過時 plugin 參照會被視為惰性的隔離設定並保留。
+    - 舊版 Plugin manifest 合約鍵遷移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
+    - 舊版 cron 儲存遷移（`jobId`、`schedule.cron`、頂層 delivery/payload 欄位、payload `provider`、簡單 `notify: true` webhook 備援工作）。
+    - 舊版 agent 執行階段政策遷移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。
+    - 啟用 plugins 時清理過期 Plugin 設定；當 `plugins.enabled=false` 時，過期 Plugin 參照會被視為惰性的隔離設定並保留。
 
   </Accordion>
   <Accordion title="狀態與完整性">
-    - Session lock file 檢查與過時 lock 清理。
-    - 修復受影響的 2026.4.24 建置建立的重複 prompt-rewrite 分支 session transcript。
-    - 卡住的 subagent 重新啟動復原 tombstone 偵測，支援用 `--fix` 清除過時的 aborted recovery flags，讓啟動不會持續把 child 視為 restart-aborted。
+    - Session lock 檔案檢查與過期 lock 清理。
+    - 修復受影響的 2026.4.24 組建建立的重複 prompt-rewrite 分支 session transcript。
+    - 偵測卡住的 subagent 重新啟動復原 tombstone，並支援用 `--fix` 清除過期的已中止復原旗標，讓啟動不會持續將子項目視為重新啟動已中止。
     - 狀態完整性與權限檢查（sessions、transcripts、state dir）。
-    - 本機執行時的設定檔權限檢查（chmod 600）。
-    - Model auth 健康狀態：檢查 OAuth 到期、可重新整理即將到期的 tokens，並回報 auth-profile cooldown/disabled 狀態。
-    - 額外 workspace dir 偵測（`~/openclaw`）。
+    - 本機執行時檢查設定檔權限（chmod 600）。
+    - 模型驗證健康狀態：檢查 OAuth 到期、可重新整理即將到期的 token，並回報 auth-profile 冷卻/停用狀態。
+    - 額外工作區目錄偵測（`~/openclaw`）。
 
   </Accordion>
-  <Accordion title="Gateway、服務與 supervisors">
-    - 啟用 sandboxing 時的 sandbox image 修復。
-    - 舊版服務遷移與額外 gateway 偵測。
+  <Accordion title="Gateway、服務與 supervisor">
+    - 啟用沙箱時修復沙箱映像。
+    - 舊版服務遷移與額外 Gateway 偵測。
     - Matrix channel 舊版狀態遷移（在 `--fix` / `--repair` 模式中）。
-    - Gateway runtime 檢查（服務已安裝但未執行；快取的 launchd label）。
-    - Channel 狀態警告（從執行中的 gateway 探測）。
-    - Supervisor 設定稽核（launchd/systemd/schtasks），並可選擇修復。
-    - 清理 Gateway 服務的嵌入式 proxy 環境，這些服務在安裝或更新期間擷取了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。
-    - Gateway runtime 最佳實務檢查（Node vs Bun、version-manager 路徑）。
-    - Gateway port 衝突診斷（預設 `18789`）。
+    - Gateway 執行階段檢查（服務已安裝但未執行；快取的 launchd label）。
+    - Channel 狀態警告（從執行中的 Gateway 探測）。
+    - Supervisor 設定稽核（launchd/systemd/schtasks）與選用修復。
+    - 清理安裝或更新期間擷取 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值的 Gateway 服務內嵌 proxy 環境。
+    - Gateway 執行階段最佳實務檢查（Node vs Bun、版本管理器路徑）。
+    - Gateway 連接埠衝突診斷（預設 `18789`）。
 
   </Accordion>
-  <Accordion title="Auth、安全性與 pairing">
-    - 開放 DM 政策的安全性警告。
-    - 本機 token 模式的 Gateway auth 檢查（沒有 token source 時提供 token 產生；不會覆寫 token SecretRef 設定）。
-    - 裝置 pairing 問題偵測（待處理的首次 pair 請求、待處理的 role/scope 升級、過時的本機 device-token cache drift，以及 paired-record auth drift）。
+  <Accordion title="驗證、安全性與配對">
+    - 開放 DM 政策的安全警告。
+    - 本機 token 模式的 Gateway 驗證檢查（當不存在 token 來源時提供 token 產生；不會覆寫 token SecretRef 設定）。
+    - 裝置配對問題偵測（待處理的首次配對要求、待處理的角色/範圍升級、過期本機 device-token 快取漂移，以及已配對記錄的驗證漂移）。
 
   </Accordion>
-  <Accordion title="Workspace 與 shell">
+  <Accordion title="工作區與 shell">
     - Linux 上的 systemd linger 檢查。
-    - Workspace bootstrap file 大小檢查（context files 的截斷/接近上限警告）。
-    - 預設 agent 的 Skills 就緒狀態檢查；回報允許但缺少 bins、env、config 或 OS 需求的 skills，且 `--fix` 可在 `skills.entries` 中停用不可用的 skills。
+    - 工作區 bootstrap 檔案大小檢查（內容檔案截斷/接近限制警告）。
+    - 預設 agent 的 Skills 就緒狀態檢查；回報缺少 bin、env、config 或 OS 需求的允許 skills，且 `--fix` 可在 `skills.entries` 中停用不可用的 skills。
     - Shell completion 狀態檢查與自動安裝/升級。
-    - Memory search embedding provider 就緒狀態檢查（本機 model、遠端 API key 或 QMD binary）。
-    - Source install 檢查（pnpm workspace 不相符、缺少 UI assets、缺少 tsx binary）。
-    - 寫入更新後的設定 + wizard metadata。
+    - 記憶體搜尋 embedding provider 就緒狀態檢查（本機模型、遠端 API key 或 QMD binary）。
+    - 原始碼安裝檢查（pnpm workspace 不相符、缺少 UI assets、缺少 tsx binary）。
+    - 寫入更新後的設定 + 精靈 metadata。
 
   </Accordion>
 </AccordionGroup>
 
-## Dreams UI backfill 與 reset
+## Dreams UI 回填與重設
 
-Control UI Dreams 場景包含 grounded dreaming workflow 的 **Backfill**、**Reset** 與 **Clear Grounded** 動作。這些動作使用 gateway doctor-style RPC 方法，但它們**不是** `openclaw doctor` CLI 修復/遷移的一部分。
+Control UI Dreams 場景包含用於 grounded dreaming 工作流程的 **Backfill**、**Reset** 和 **Clear Grounded** 動作。這些動作使用 Gateway doctor 風格的 RPC 方法，但它們**不是** `openclaw doctor` CLI 修復/遷移的一部分。
 
-它們會做的事：
+它們會做什麼：
 
-- **Backfill** 會掃描 active workspace 中歷史的 `memory/YYYY-MM-DD.md` 檔案、執行 grounded REM diary pass，並將可逆的 backfill entries 寫入 `DREAMS.md`。
-- **Reset** 只會從 `DREAMS.md` 移除那些已標記的 backfill diary entries。
-- **Clear Grounded** 只會移除來自歷史 replay、且尚未累積 live recall 或 daily support 的 staged grounded-only short-term entries。
+- **Backfill** 會掃描目前工作區中的歷史 `memory/YYYY-MM-DD.md` 檔案，執行 grounded REM diary pass，並將可逆回填項目寫入 `DREAMS.md`。
+- **Reset** 只會從 `DREAMS.md` 移除那些標記的回填 diary 項目。
+- **Clear Grounded** 只會移除來自歷史重播、且尚未累積即時 recall 或每日支援的已暫存 grounded-only 短期項目。
 
-它們本身**不會**做的事：
+它們本身**不會**做什麼：
 
 - 它們不會編輯 `MEMORY.md`
-- 它們不會執行完整 doctor migrations
-- 除非你先明確執行 staged CLI path，否則它們不會自動將 grounded candidates stage 到 live short-term promotion store
+- 它們不會執行完整 doctor 遷移
+- 除非你先明確執行已暫存的 CLI 路徑，否則它們不會自動將 grounded 候選項目暫存到即時短期 promotion store
 
-如果你想讓 grounded historical replay 影響一般的 deep promotion lane，請改用 CLI flow：
+如果你想讓 grounded 歷史重播影響一般深度 promotion lane，請改用 CLI 流程：
 
 ```bash
 openclaw memory rem-backfill --path ./memory --stage-short-term
 ```
 
-這會將 grounded durable candidates stage 到 short-term dreaming store，同時讓 `DREAMS.md` 保持作為 review surface。
+這會將 grounded durable 候選項目暫存到短期 dreaming store，同時保留 `DREAMS.md` 作為檢閱介面。
 
-## 詳細行為與理由
+## 詳細行為與設計理由
 
 <AccordionGroup>
   <Accordion title="0. 選用更新（git 安裝）">
-    如果這是 git checkout 且 doctor 正以互動方式執行，它會在執行 doctor 前提供更新（fetch/rebase/build）。
+    如果這是 git checkout 且 doctor 正在互動模式下執行，它會在執行 doctor 前提供更新（fetch/rebase/build）選項。
   </Accordion>
   <Accordion title="1. 設定正規化">
-    如果設定包含舊版值形狀（例如沒有 channel-specific override 的 `messages.ackReaction`），doctor 會將它們正規化為目前的 schema。
+    如果設定包含舊版值形狀（例如沒有 channel 特定覆寫的 `messages.ackReaction`），doctor 會將它們正規化為目前結構描述。
 
-    這包含舊版 Talk 扁平欄位。目前公開 Talk 設定是 `talk.provider` + `talk.providers.<provider>`。Doctor 會把舊的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形狀重寫到 provider map。
+    這包括舊版 Talk 扁平欄位。目前公開的 Talk 設定是 `talk.provider` + `talk.providers.<provider>`。Doctor 會將舊的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形狀重寫到 provider map。
 
-    當 `plugins.allow` 非空且工具政策使用萬用字元或 plugin-owned tool entries 時，Doctor 也會警告。`tools.allow: ["*"]` 只會符合實際載入的 plugins 中的工具；它不會繞過專屬 plugin 允許清單。
+    當 `plugins.allow` 非空且工具政策使用萬用字元或 Plugin 所有工具項目時，Doctor 也會發出警告。`tools.allow: ["*"]` 只會符合實際載入的 plugins 中的工具；它不會繞過專屬 Plugin 允許清單。Doctor 會為已遷移的舊版允許清單設定寫入 `plugins.bundledDiscovery: "compat"`，以保留既有 bundled provider 行為，然後指向更嚴格的 `"allowlist"` 設定。
 
   </Accordion>
-  <Accordion title="2. 舊版設定 key 遷移">
-    當設定包含已棄用的 keys 時，其他 commands 會拒絕執行，並要求你執行 `openclaw doctor`。
+  <Accordion title="2. 舊版設定鍵遷移">
+    當設定包含已棄用鍵時，其他命令會拒絕執行並要求你執行 `openclaw doctor`。
 
     Doctor 會：
 
-    - 說明找到哪些舊版 keys。
+    - 說明找到哪些舊版鍵。
     - 顯示它套用的遷移。
-    - 使用更新後的 schema 重寫 `~/.openclaw/openclaw.json`。
+    - 使用更新後的結構描述重寫 `~/.openclaw/openclaw.json`。
 
-    Gateway 在啟動時偵測到舊版設定格式，也會自動執行 doctor migrations，因此過時設定不需人工介入就會被修復。Cron job store migrations 由 `openclaw doctor --fix` 處理。
+    Gateway 也會在啟動時偵測到舊版設定格式後自動執行 doctor 遷移，因此過期設定無需手動介入即可修復。Cron job store 遷移由 `openclaw doctor --fix` 處理。
 
     目前遷移：
 
@@ -193,6 +193,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
     - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
     - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
     - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
+    - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
     - 已設定的頻道設定缺少可見回覆政策 → `messages.groupChat.visibleReplies: "message_tool"`
     - `routing.queue` → `messages.queue`
     - `routing.bindings` → 頂層 `bindings`
@@ -211,24 +212,24 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
     - `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`
-    - 對於具有具名 `accounts` 但仍殘留單一帳號頂層頻道值的頻道，將這些帳號範圍值移入為該頻道選定的已提升帳號（多數頻道為 `accounts.default`；Matrix 可以保留既有相符的具名/預設目標）
+    - 對於有具名 `accounts` 但仍殘留單帳號頂層頻道值的頻道，將那些帳號範圍的值移入為該頻道選定的已提升帳號（大多數頻道為 `accounts.default`；Matrix 可保留現有相符的具名/預設目標）
     - `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`
-    - 移除 `agents.defaults.llm`；針對較慢的供應商/模型逾時，請使用 `models.providers.<id>.timeoutSeconds`
+    - 移除 `agents.defaults.llm`；對於緩慢的供應商/模型逾時，請使用 `models.providers.<id>.timeoutSeconds`
     - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
     - `browser.profiles.*.driver: "extension"` → `"existing-session"`
     - 移除 `browser.relayBindHost`（舊版擴充功能轉送設定）
-    - 舊版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 啟動時也會略過 `api` 設為未來或未知列舉值的供應商，而不是以關閉失敗）
+    - 舊版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 啟動時也會略過 `api` 設為未來或未知 enum 值的供應商，而不是封閉式失敗）
 
-    Doctor 警告也包含多帳號頻道的帳號預設值指引：
+    Doctor 警告也包含多帳號頻道的帳號預設指引：
 
-    - 如果設定了兩個或更多 `channels.<channel>.accounts` 項目，但未設定 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 會警告後援路由可能選到非預期的帳號。
-    - 如果 `channels.<channel>.defaultAccount` 設為未知的帳號 ID，doctor 會警告並列出已設定的帳號 ID。
+    - 如果設定了兩個以上 `channels.<channel>.accounts` 項目，但沒有 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 會警告後援路由可能挑選到非預期的帳號。
+    - 如果 `channels.<channel>.defaultAccount` 設為未知帳號 ID，doctor 會警告並列出已設定的帳號 ID。
 
   </Accordion>
   <Accordion title="2b. OpenCode 供應商覆寫">
-    如果你手動新增了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它會覆寫來自 `@mariozechner/pi-ai` 的內建 OpenCode 目錄。這可能會強制模型使用錯誤的 API，或將成本歸零。Doctor 會警告，讓你可以移除覆寫並恢復每個模型的 API 路由與成本。
+    如果你手動加入了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它會覆寫來自 `@mariozechner/pi-ai` 的內建 OpenCode 目錄。這可能會迫使模型使用錯誤的 API，或將成本歸零。Doctor 會警告，讓你移除覆寫並還原每個模型的 API 路由與成本。
   </Accordion>
   <Accordion title="2c. 瀏覽器遷移與 Chrome MCP 就緒狀態">
     如果你的瀏覽器設定仍指向已移除的 Chrome 擴充功能路徑，doctor 會將其正規化為目前的主機本機 Chrome MCP 附加模型：
@@ -238,222 +239,228 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
 
     當你使用 `defaultProfile: "user"` 或已設定的 `existing-session` 設定檔時，Doctor 也會稽核主機本機 Chrome MCP 路徑：
 
-    - 檢查 Google Chrome 是否安裝在同一台主機上，以供預設自動連線設定檔使用
+    - 檢查 Google Chrome 是否已安裝在同一台主機上，以供預設自動連線設定檔使用
     - 檢查偵測到的 Chrome 版本，並在低於 Chrome 144 時警告
-    - 提醒你在瀏覽器檢查頁面中啟用遠端偵錯（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
+    - 提醒你在瀏覽器檢查頁面啟用遠端偵錯（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
 
-    Doctor 無法替你啟用 Chrome 端設定。主機本機 Chrome MCP 仍需要：
+    Doctor 無法替你啟用 Chrome 端設定。主機本機 Chrome MCP 仍然需要：
 
-    - Gateway/Node 主機上的 Chromium 型瀏覽器 144+
+    - Gateway/Node 主機上有 Chromium 系瀏覽器 144+
     - 瀏覽器在本機執行
     - 該瀏覽器已啟用遠端偵錯
-    - 在瀏覽器中核准第一次附加同意提示
+    - 在瀏覽器中核准第一次附加的同意提示
 
-    這裡的就緒狀態只關於本機附加先決條件。Existing-session 會保留目前的 Chrome MCP 路由限制；像 `responsebody`、PDF 匯出、下載攔截和批次動作等進階路由仍需要受管理瀏覽器或原始 CDP 設定檔。
+    這裡的就緒狀態只關於本機附加的先決條件。Existing-session 會保留目前的 Chrome MCP 路由限制；`responsebody`、PDF 匯出、下載攔截和批次動作等進階路由，仍需要受管理瀏覽器或原始 CDP 設定檔。
 
-    此檢查**不**適用於 Docker、sandbox、remote-browser 或其他 headless 流程。這些流程會繼續使用原始 CDP。
+    此檢查**不**適用於 Docker、sandbox、remote-browser 或其他 headless 流程。那些流程會繼續使用原始 CDP。
 
   </Accordion>
   <Accordion title="2d. OAuth TLS 先決條件">
-    設定 OpenAI Codex OAuth 設定檔時，doctor 會探測 OpenAI 授權端點，以驗證本機 Node/OpenSSL TLS 堆疊能否驗證憑證鏈。如果探測因憑證錯誤而失敗（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、過期憑證或自簽憑證），doctor 會列印平台特定的修復指引。在使用 Homebrew Node 的 macOS 上，修復通常是 `brew postinstall ca-certificates`。使用 `--deep` 時，即使 Gateway 健康，探測也會執行。
+    設定 OpenAI Codex OAuth 設定檔時，doctor 會探測 OpenAI 授權端點，以驗證本機 Node/OpenSSL TLS 堆疊是否能驗證憑證鏈。如果探測因憑證錯誤而失敗（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、過期憑證或自簽憑證），doctor 會列印平台特定的修復指引。在 macOS 搭配 Homebrew Node 時，修復通常是 `brew postinstall ca-certificates`。使用 `--deep` 時，即使 Gateway 健康，探測也會執行。
   </Accordion>
   <Accordion title="2e. Codex OAuth 供應商覆寫">
-    如果你先前在 `models.providers.openai-codex` 下新增了舊版 OpenAI 傳輸設定，它們可能會遮蔽較新版本自動使用的內建 Codex OAuth 供應商路徑。Doctor 看到這些舊傳輸設定與 Codex OAuth 並存時會警告，讓你可以移除或改寫過時的傳輸覆寫，取回內建的路由/後援行為。自訂代理和僅標頭覆寫仍受支援，且不會觸發此警告。
+    如果你先前在 `models.providers.openai-codex` 下加入舊版 OpenAI 傳輸設定，它們可能會遮蔽較新版本自動使用的內建 Codex OAuth 供應商路徑。當 Doctor 看到這些舊傳輸設定與 Codex OAuth 同時存在時會發出警告，讓你移除或重寫過時的傳輸覆寫，並取回內建路由/後援行為。仍支援自訂代理和僅標頭覆寫，且不會觸發此警告。
   </Accordion>
   <Accordion title="2f. Codex Plugin 路由警告">
-    啟用隨附的 Codex Plugin 時，doctor 也會檢查 `openai-codex/*` 主要模型參照是否仍透過預設 PI 執行器解析。當你想透過 PI 使用 Codex OAuth/訂閱驗證時，這個組合是有效的，但很容易與原生 Codex app-server harness 混淆。Doctor 會警告並指向明確的 app-server 形狀：`openai/*` 加上 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
+    啟用內建 Codex Plugin 時，doctor 也會檢查 `openai-codex/*` 主要模型參照是否仍透過預設 PI 執行器解析。當你想透過 PI 使用 Codex OAuth/訂閱驗證時，這個組合是有效的，但很容易與原生 Codex app-server harness 混淆。Doctor 會警告並指向明確的 app-server 形狀：`openai/*` 加上 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
 
-    Doctor 不會自動修復此項，因為兩種路由都有效：
+    Doctor 不會自動修復，因為兩種路由都是有效的：
 
     - `openai-codex/*` + PI 表示「透過一般 OpenClaw 執行器使用 Codex OAuth/訂閱驗證。」
-    - `openai/*` + `agentRuntime.id: "codex"` 表示「透過原生 Codex app-server 執行嵌入式回合。」
-    - `/codex ...` 表示「從聊天控制或綁定原生 Codex 對話。」
+    - `openai/*` + `agentRuntime.id: "codex"` 表示「透過原生 Codex app-server 執行內嵌回合。」
+    - `/codex ...` 表示「從聊天控制或繫結原生 Codex 對話。」
     - `/acp ...` 或 `runtime: "acp"` 表示「使用外部 ACP/acpx 轉接器。」
 
-    如果出現警告，請選擇你原本想要的路由並手動編輯設定。當 PI Codex OAuth 是刻意設定時，請保留警告不變。
+    如果出現警告，請選擇你原本意圖使用的路由並手動編輯設定。當 PI Codex OAuth 是有意設定時，請保持警告不變。
 
   </Accordion>
-  <Accordion title="3. 舊版狀態遷移（磁碟布局）">
-    Doctor 可以將較舊的磁碟布局遷移到目前結構：
+  <Accordion title="2g. 工作階段路由清理">
+    在你將已設定的預設/後援模型或執行階段從 Plugin 擁有的路由（例如 Codex）移開後，Doctor 也會掃描作用中的工作階段儲存區，尋找過時的自動建立路由狀態。
 
-    - 工作階段儲存區 + 轉錄：
+    `openclaw doctor --fix` 可清除自動建立的過時狀態，例如 `modelOverrideSource: "auto"` 模型釘選、執行階段模型中繼資料、釘選的 harness ID、CLI 工作階段繫結，以及當其擁有路由已不再設定時的自動驗證設定檔覆寫。明確的使用者或舊版工作階段模型選擇會回報供手動檢閱並保持不變；當不再打算使用該路由時，請用 `/model ...`、`/new` 切換，或重設工作階段。
+
+  </Accordion>
+  <Accordion title="3. 舊版狀態遷移（磁碟配置）">
+    Doctor 可將較舊的磁碟配置遷移到目前結構：
+
+    - 工作階段儲存區 + 逐字稿：
       - 從 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
     - Agent 目錄：
       - 從 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
     - WhatsApp 驗證狀態（Baileys）：
-      - 從舊版 `~/.openclaw/credentials/*.json`（除了 `oauth.json`）
+      - 從舊版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
       - 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（預設帳號 ID：`default`）
 
-    這些遷移會盡力執行且具冪等性；當 doctor 留下任何舊版資料夾作為備份時，會發出警告。Gateway/CLI 在啟動時也會自動遷移舊版工作階段 + agent 目錄，讓歷史記錄/驗證/模型落在每個 agent 的路徑中，而不需要手動執行 doctor。WhatsApp 驗證刻意只透過 `openclaw doctor` 遷移。Talk 供應商/供應商對應正規化現在會以結構相等比較，因此只有鍵順序不同的差異不再觸發重複的無操作 `doctor --fix` 變更。
+    這些遷移是盡力而為且冪等；當 doctor 留下任何舊版資料夾作為備份時，會發出警告。Gateway/CLI 也會在啟動時自動遷移舊版工作階段與 Agent 目錄，讓歷史記錄/驗證/模型落在每個 Agent 的路徑中，而不需要手動執行 doctor。WhatsApp 驗證刻意只透過 `openclaw doctor` 遷移。Talk 供應商/供應商對映正規化現在會以結構相等性比較，因此只有鍵順序差異不再會觸發重複的無操作 `doctor --fix` 變更。
 
   </Accordion>
   <Accordion title="3a. 舊版 Plugin manifest 遷移">
-    Doctor 會掃描所有已安裝 Plugin manifest，尋找已棄用的頂層功能鍵（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到時，它會提出將這些鍵移入 `contracts` 物件，並就地改寫 manifest 檔案。此遷移具冪等性；如果 `contracts` 鍵已經有相同值，舊版鍵會被移除而不重複資料。
+    Doctor 會掃描所有已安裝的 Plugin manifest，尋找已淘汰的頂層能力鍵（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到時，它會提議將其移入 `contracts` 物件，並就地重寫 manifest 檔案。此遷移是冪等的；如果 `contracts` 鍵已經有相同值，舊版鍵會被移除，而不會複製資料。
   </Accordion>
   <Accordion title="3b. 舊版 Cron 儲存區遷移">
-    Doctor 也會檢查 Cron 工作儲存區（預設為 `~/.openclaw/cron/jobs.json`，或覆寫時的 `cron.store`），尋找排程器仍為相容性而接受的舊工作形狀。
+    Doctor 也會檢查 Cron 工作儲存區（預設為 `~/.openclaw/cron/jobs.json`，或在覆寫時為 `cron.store`），尋找排程器仍為相容性而接受的舊工作形狀。
 
-    目前的 Cron 清理包含：
+    目前的 Cron 清理包括：
 
     - `jobId` → `id`
     - `schedule.cron` → `schedule.expr`
     - 頂層 payload 欄位（`message`、`model`、`thinking`、...）→ `payload`
     - 頂層 delivery 欄位（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
     - payload `provider` delivery 別名 → 明確的 `delivery.channel`
-    - 簡單舊版 `notify: true` Webhook 後援工作 → 明確的 `delivery.mode="webhook"` 搭配 `delivery.to=cron.webhook`
+    - 簡單舊版 `notify: true` webhook 後援工作 → 明確的 `delivery.mode="webhook"` 搭配 `delivery.to=cron.webhook`
 
-    Doctor 只會在不改變行為時自動遷移 `notify: true` 工作。如果某個工作結合了舊版通知後援與既有的非 Webhook delivery 模式，doctor 會警告並保留該工作供手動審查。
+    Doctor 只會在不改變行為的情況下自動遷移 `notify: true` 工作。如果某個工作將舊版通知後援與現有非 webhook delivery 模式結合，doctor 會警告並保留該工作供手動檢閱。
 
-    在 Linux 上，當使用者的 crontab 仍叫用舊版 `~/.openclaw/bin/ensure-whatsapp.sh` 時，doctor 也會警告。該主機本機腳本不由目前的 OpenClaw 維護，且當 cron 無法連到 systemd 使用者匯流排時，可能會將錯誤的 `Gateway inactive` 訊息寫入 `~/.openclaw/logs/whatsapp-health.log`。請使用 `crontab -e` 移除過時的 crontab 項目；目前的健康檢查請使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
+    在 Linux 上，doctor 也會在使用者的 crontab 仍呼叫舊版 `~/.openclaw/bin/ensure-whatsapp.sh` 時發出警告。該主機本機腳本不再由目前的 OpenClaw 維護，且當 cron 無法連到 systemd 使用者匯流排時，可能會將錯誤的 `Gateway inactive` 訊息寫入 `~/.openclaw/logs/whatsapp-health.log`。請使用 `crontab -e` 移除過時的 crontab 項目；目前的健康檢查請使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
 
   </Accordion>
   <Accordion title="3c. 工作階段鎖定清理">
-    doctor 會掃描每個代理程式工作階段目錄中的過時寫入鎖定檔，也就是工作階段異常結束後遺留下來的檔案。對於找到的每個鎖定檔，它會回報：路徑、PID、該 PID 是否仍在執行、鎖定存在時間，以及是否被視為過時（PID 已死或超過 30 分鐘）。在 `--fix` / `--repair` 模式中，它會自動移除過時的鎖定檔；否則會列印一則提示，指示你使用 `--fix` 重新執行。
+    Doctor 會掃描每個代理程式工作階段目錄，尋找過時的寫入鎖定檔案，也就是工作階段異常結束後遺留的檔案。對於找到的每個鎖定檔，它會回報：路徑、PID、PID 是否仍存活、鎖定存在時間，以及是否被視為過時（PID 已失效或超過 30 分鐘）。在 `--fix` / `--repair` 模式中，它會自動移除過時的鎖定檔；否則會列印提示，並指示你使用 `--fix` 重新執行。
   </Accordion>
   <Accordion title="3d. 工作階段轉錄分支修復">
-    doctor 會掃描代理程式工作階段 JSONL 檔案，尋找由 2026.4.24 提示轉錄重寫錯誤所建立的重複分支形狀：一個被棄用的使用者回合包含 OpenClaw 內部執行階段內容，旁邊還有一個作用中的同層分支，含有相同的可見使用者提示。在 `--fix` / `--repair` 模式中，doctor 會在原始檔旁備份每個受影響的檔案，並將轉錄重寫為作用中的分支，使 gateway 歷程與記憶讀取器不再看到重複回合。
+    Doctor 會掃描代理程式工作階段 JSONL 檔案，尋找 2026.4.24 提示轉錄重寫錯誤所建立的重複分支形狀：一個帶有 OpenClaw 內部執行階段內容的棄用使用者輪次，以及一個包含相同可見使用者提示的作用中同層項目。在 `--fix` / `--repair` 模式中，doctor 會在每個受影響檔案旁邊建立備份，然後將轉錄重寫到作用中分支，讓 Gateway 歷程與記憶讀取器不再看到重複輪次。
   </Accordion>
   <Accordion title="4. 狀態完整性檢查（工作階段持久化、路由與安全性）">
-    狀態目錄是作業上的腦幹。如果它消失，你會失去工作階段、憑證、日誌與設定（除非你在其他地方有備份）。
+    狀態目錄是操作核心。如果它消失，你會失去工作階段、憑證、記錄與設定（除非你在其他地方有備份）。
 
-    doctor 會檢查：
+    Doctor 會檢查：
 
-    - **狀態目錄遺失**：警告災難性的狀態遺失，提示重新建立目錄，並提醒你它無法復原遺失的資料。
-    - **狀態目錄權限**：驗證可寫入性；提供修復權限的選項（偵測到擁有者/群組不相符時，會發出 `chown` 提示）。
-    - **macOS 雲端同步的狀態目錄**：當狀態解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 底下時發出警告，因為同步支援的路徑可能導致較慢的 I/O 以及鎖定/同步競爭。
-    - **Linux SD 或 eMMC 狀態目錄**：當狀態解析到 `mmcblk*` 掛載來源時發出警告，因為 SD 或 eMMC 支援的隨機 I/O 可能較慢，且在工作階段與憑證寫入下磨耗更快。
-    - **工作階段目錄遺失**：需要 `sessions/` 與工作階段儲存目錄，才能持久保存歷程並避免 `ENOENT` 當機。
-    - **轉錄不相符**：當近期工作階段項目缺少轉錄檔時發出警告。
-    - **主要工作階段「1 行 JSONL」**：當主要轉錄只有一行時標記（表示歷程沒有累積）。
-    - **多個狀態目錄**：當多個 home 目錄中存在多個 `~/.openclaw` 資料夾，或 `OPENCLAW_STATE_DIR` 指向其他位置時發出警告（歷程可能在不同安裝之間分裂）。
-    - **遠端模式提醒**：如果 `gateway.mode=remote`，doctor 會提醒你在遠端主機上執行（狀態位於那裡）。
+    - **狀態目錄遺失**：警告災難性狀態遺失，提示重新建立目錄，並提醒你它無法復原遺失的資料。
+    - **狀態目錄權限**：驗證是否可寫入；提供修復權限的選項（偵測到擁有者/群組不符時會輸出 `chown` 提示）。
+    - **macOS 雲端同步狀態目錄**：當狀態解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下時發出警告，因為同步支援的路徑可能造成較慢的 I/O 與鎖定/同步競態。
+    - **Linux SD 或 eMMC 狀態目錄**：當狀態解析到 `mmcblk*` 掛載來源時發出警告，因為以 SD 或 eMMC 支援的隨機 I/O 在工作階段與憑證寫入下可能較慢且磨耗更快。
+    - **工作階段目錄遺失**：`sessions/` 與工作階段儲存目錄是持久保存歷程並避免 `ENOENT` 當機所必需的。
+    - **轉錄不相符**：當最近的工作階段項目缺少轉錄檔案時發出警告。
+    - **主工作階段「1 行 JSONL」**：當主轉錄只有一行時標記（歷程沒有累積）。
+    - **多個狀態目錄**：當多個 `~/.openclaw` 資料夾存在於各家目錄，或 `OPENCLAW_STATE_DIR` 指向其他位置時發出警告（歷程可能在安裝之間分散）。
+    - **遠端模式提醒**：如果 `gateway.mode=remote`，doctor 會提醒你在遠端主機上執行它（狀態存放在那裡）。
     - **設定檔權限**：如果 `~/.openclaw/openclaw.json` 可被群組/所有人讀取，則發出警告並提供收緊為 `600` 的選項。
 
   </Accordion>
   <Accordion title="5. 模型驗證健康狀態（OAuth 到期）">
-    doctor 會檢查驗證儲存區中的 OAuth profile，在 token 即將到期/已到期時發出警告，並可在安全時重新整理它們。如果 Anthropic OAuth/token profile 已過時，它會建議使用 Anthropic API key 或 Anthropic setup-token 路徑。重新整理提示只會在互動式執行（TTY）時出現；`--non-interactive` 會略過重新整理嘗試。
+    Doctor 會檢查驗證儲存區中的 OAuth 設定檔，在權杖即將到期/已到期時發出警告，並在安全時重新整理它們。如果 Anthropic OAuth/權杖設定檔過期，它會建議 Anthropic API 金鑰或 Anthropic setup-token 路徑。重新整理提示只會在互動式執行（TTY）時出現；`--non-interactive` 會略過重新整理嘗試。
 
-    當 OAuth 重新整理永久失敗時（例如 `refresh_token_reused`、`invalid_grant`，或提供者要求你重新登入），doctor 會回報需要重新驗證，並列印要執行的精確 `openclaw models auth login --provider ...` 指令。
+    當 OAuth 重新整理永久失敗時（例如 `refresh_token_reused`、`invalid_grant`，或提供者要求你重新登入），doctor 會回報需要重新驗證，並列印要執行的確切 `openclaw models auth login --provider ...` 命令。
 
-    doctor 也會回報因下列原因而暫時無法使用的 auth profile：
+    Doctor 也會回報因下列原因暫時無法使用的驗證設定檔：
 
     - 短暫冷卻時間（速率限制/逾時/驗證失敗）
-    - 較長時間的停用（帳單/點數失敗）
+    - 較長停用（帳單/額度失敗）
 
   </Accordion>
-  <Accordion title="6. hooks 模型驗證">
-    如果已設定 `hooks.gmail.model`，doctor 會根據 catalog 與 allowlist 驗證模型參照，並在無法解析或不允許時發出警告。
+  <Accordion title="6. Hooks 模型驗證">
+    如果設定了 `hooks.gmail.model`，doctor 會根據目錄與允許清單驗證模型參照，並在它無法解析或不被允許時發出警告。
   </Accordion>
-  <Accordion title="7. 沙箱映像修復">
-    啟用沙箱時，doctor 會檢查 Docker 映像，並在目前映像遺失時提供建置或切換到舊版名稱的選項。
+  <Accordion title="7. 沙盒映像修復">
+    啟用沙盒時，doctor 會檢查 Docker 映像，並在目前映像遺失時提供建置或切換到舊名稱的選項。
   </Accordion>
   <Accordion title="7b. Plugin 安裝清理">
-    doctor 會在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式中移除舊版 OpenClaw 產生的 Plugin 依賴 staging 狀態。這涵蓋過時的已產生依賴根目錄、舊的 install-stage 目錄、早期 bundled-plugin 依賴修復程式碼留下的 package-local 雜物，以及可能遮蔽目前 bundled manifest 的孤立或已復原的託管 bundled `@openclaw/*` plugins npm 副本。
+    Doctor 會在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式中移除舊版 OpenClaw 產生的 Plugin 相依項暫存狀態。這涵蓋過時的產生相依項根目錄、舊安裝階段目錄、較早 bundled-plugin 相依項修復程式碼留下的套件本機殘留物，以及可能遮蔽目前 bundled manifest 的孤立或復原受管 npm bundled `@openclaw/*` plugins 副本。
 
-    當 config 參照已設定的可下載 plugins，但本機 plugin registry 找不到它們時，doctor 也可以重新安裝這些 plugins。對於 2026.5.2 bundled-plugin externalization，doctor 會自動安裝既有 config 已使用的可下載 plugins，然後依賴 `meta.lastTouchedVersion` 確保該發行版本處理只執行一次。Gateway 啟動與 config 重新載入不會執行 package manager；plugin 安裝仍是明確的 doctor/install/update 工作。
+    當設定參照可下載 Plugin 但本機 Plugin 登錄找不到它們時，Doctor 也可以重新安裝遺失的可下載 plugins。範例包括實際的 `plugins.entries`、已設定的頻道/提供者/搜尋設定，以及已設定的代理程式執行階段。在套件更新期間，doctor 會避免在核心套件被替換時執行套件管理器 Plugin 修復；如果更新後已設定的 Plugin 仍需要復原，請再次執行 `openclaw doctor --fix`。Gateway 啟動與設定重新載入不會執行套件管理器；Plugin 安裝仍是明確的 doctor/install/update 工作。
 
   </Accordion>
   <Accordion title="8. Gateway 服務遷移與清理提示">
-    doctor 會偵測舊版 gateway 服務（launchd/systemd/schtasks），並提供移除它們以及使用目前 gateway 連接埠安裝 OpenClaw 服務的選項。它也可以掃描額外的 gateway 類服務並列印清理提示。以 profile 命名的 OpenClaw gateway 服務會被視為一級項目，不會被標記為「額外」。
+    Doctor 會偵測舊版 Gateway 服務（launchd/systemd/schtasks），並提供移除它們以及使用目前 Gateway 連接埠安裝 OpenClaw 服務的選項。它也可以掃描額外類似 Gateway 的服務並列印清理提示。以設定檔命名的 OpenClaw Gateway 服務會被視為第一級項目，不會被標記為「額外」。
 
-    在 Linux 上，如果使用者層級 gateway 服務遺失但系統層級 OpenClaw gateway 服務存在，doctor 不會自動安裝第二個使用者層級服務。請使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 檢查，然後移除重複項，或在系統 supervisor 擁有 gateway 生命週期時設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
+    在 Linux 上，如果使用者層級 Gateway 服務遺失但存在系統層級 OpenClaw Gateway 服務，doctor 不會自動安裝第二個使用者層級服務。請使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 檢查，然後移除重複項，或在系統監督器負責 Gateway 生命週期時設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
 
   </Accordion>
   <Accordion title="8b. 啟動 Matrix 遷移">
-    當 Matrix 頻道帳戶有待處理或可執行的舊版狀態遷移時，doctor（在 `--fix` / `--repair` 模式中）會建立遷移前快照，然後執行 best-effort 遷移步驟：舊版 Matrix 狀態遷移與舊版加密狀態準備。這兩個步驟都不是致命錯誤；錯誤會被記錄，啟動會繼續。在唯讀模式（不帶 `--fix` 的 `openclaw doctor`）中，這項檢查會完全略過。
+    當 Matrix 頻道帳號有待處理或可採取動作的舊版狀態遷移時，doctor（在 `--fix` / `--repair` 模式中）會建立遷移前快照，然後執行盡力而為的遷移步驟：舊版 Matrix 狀態遷移與舊版加密狀態準備。兩個步驟都不是致命錯誤；錯誤會被記錄，而啟動會繼續。在唯讀模式（未帶 `--fix` 的 `openclaw doctor`）中，這項檢查會完全略過。
   </Accordion>
   <Accordion title="8c. 裝置配對與驗證漂移">
-    doctor 現在會在一般健康檢查中檢查裝置配對狀態。
+    Doctor 現在會將裝置配對狀態作為一般健康檢查的一部分進行檢查。
 
     它會回報：
 
-    - 待處理的首次配對請求
-    - 已配對裝置待處理的角色升級
-    - 已配對裝置待處理的範圍升級
-    - 裝置 id 仍相符但裝置身分已不再符合已核准記錄的公開金鑰不相符修復
-    - 缺少已核准角色作用中 token 的已配對記錄
-    - 範圍漂移到已核准配對基準之外的已配對 token
-    - 目前機器上的本機快取裝置 token 項目，其早於 gateway 端 token 輪替，或帶有過時的範圍中繼資料
+    - 待處理的首次配對要求
+    - 已配對裝置的待處理角色升級
+    - 已配對裝置的待處理範圍升級
+    - 裝置 ID 仍相符但裝置身分不再符合已核准記錄的公開金鑰不相符修復
+    - 已配對記錄缺少核准角色的作用中權杖
+    - 範圍偏離已核准配對基準線的已配對權杖
+    - 目前機器上早於 Gateway 端權杖輪替或帶有過時範圍中繼資料的本機快取裝置權杖項目
 
-    doctor 不會自動核准配對請求，也不會自動輪替裝置 token。它會改為列印精確的後續步驟：
+    Doctor 不會自動核准配對要求或自動輪替裝置權杖。它會改為列印確切的後續步驟：
 
-    - 使用 `openclaw devices list` 檢查待處理請求
-    - 使用 `openclaw devices approve <requestId>` 核准精確請求
-    - 使用 `openclaw devices rotate --device <deviceId> --role <role>` 輪替新的 token
+    - 使用 `openclaw devices list` 檢查待處理要求
+    - 使用 `openclaw devices approve <requestId>` 核准確切要求
+    - 使用 `openclaw devices rotate --device <deviceId> --role <role>` 輪替新權杖
     - 使用 `openclaw devices remove <deviceId>` 移除並重新核准過時記錄
 
-    這會補上常見的「已配對但仍然收到需要配對」缺口：doctor 現在會區分首次配對、待處理角色/範圍升級，以及過時 token/裝置身分漂移。
+    這修補了常見的「已配對但仍收到需要配對」漏洞：doctor 現在會區分首次配對、待處理角色/範圍升級，以及過時權杖/裝置身分漂移。
 
   </Accordion>
   <Accordion title="9. 安全性警告">
-    當 provider 對 DM 開放但沒有 allowlist，或 policy 以危險方式設定時，doctor 會發出警告。
+    當提供者對私訊開放但沒有允許清單，或政策以危險方式設定時，Doctor 會發出警告。
   </Accordion>
   <Accordion title="10. systemd linger（Linux）">
-    如果以 systemd 使用者服務執行，doctor 會確保已啟用 lingering，讓 gateway 在登出後仍保持執行。
+    如果以 systemd 使用者服務執行，doctor 會確保已啟用 lingering，讓 Gateway 在登出後仍保持運作。
   </Accordion>
-  <Accordion title="11. 工作區狀態（skills、plugins 與舊版目錄）">
-    doctor 會列印預設代理程式的工作區狀態摘要：
+  <Accordion title="11. 工作區狀態（Skills、plugins 與舊版目錄）">
+    Doctor 會列印預設代理程式的工作區狀態摘要：
 
-    - **Skills 狀態**：計算 eligible、missing-requirements 與 allowlist-blocked skills 的數量。
+    - **Skills 狀態**：計算符合資格、缺少需求，以及被允許清單阻擋的 skills。
     - **舊版工作區目錄**：當 `~/openclaw` 或其他舊版工作區目錄與目前工作區並存時發出警告。
-    - **Plugin 狀態**：計算已啟用/已停用/錯誤 plugins；列出任何錯誤的 plugin ID；回報 bundle plugin capabilities。
-    - **Plugin 相容性警告**：標記與目前 runtime 有相容性問題的 plugins。
-    - **Plugin 診斷**：顯示 plugin registry 在載入期間發出的任何警告或錯誤。
+    - **Plugin 狀態**：計算已啟用/已停用/錯誤的 plugins；列出任何錯誤的 Plugin ID；回報 bundle plugin 功能。
+    - **Plugin 相容性警告**：標記與目前執行階段有相容性問題的 plugins。
+    - **Plugin 診斷**：顯示 Plugin 登錄在載入期間輸出的任何警告或錯誤。
 
   </Accordion>
-  <Accordion title="11b. Bootstrap 檔案大小">
-    doctor 會檢查工作區 bootstrap 檔案（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的內容檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始與注入字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及總注入字元數佔總預算的比例。當檔案被截斷或接近限制時，doctor 會列印調整 `agents.defaults.bootstrapMaxChars` 與 `agents.defaults.bootstrapTotalMaxChars` 的提示。
+  <Accordion title="11b. 啟動檔案大小">
+    Doctor 會檢查工作區啟動檔案（例如 `AGENTS.md`、`CLAUDE.md`，或其他注入的內容檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始與注入字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及總注入字元佔總預算的比例。當檔案被截斷或接近限制時，doctor 會列印調整 `agents.defaults.bootstrapMaxChars` 與 `agents.defaults.bootstrapTotalMaxChars` 的提示。
   </Accordion>
   <Accordion title="11d. 過時頻道 Plugin 清理">
-    當 `openclaw doctor --fix` 移除遺失的頻道 Plugin 時，它也會移除參照該 Plugin 的懸空頻道範圍 config：`channels.<id>` 項目、命名該頻道的 Heartbeat targets，以及 `agents.*.models["<channel>/*"]` overrides。這能避免頻道 runtime 已消失但 config 仍要求 gateway 綁定到它所造成的 Gateway 啟動迴圈。
+    當 `openclaw doctor --fix` 移除遺失的頻道 Plugin 時，它也會移除參照該 Plugin 的懸空頻道範圍設定：`channels.<id>` 項目、命名該頻道的 Heartbeat 目標，以及 `agents.*.models["<channel>/*"]` 覆寫。這會防止頻道執行階段已不存在但設定仍要求 Gateway 綁定到它而造成 Gateway 啟動迴圈。
   </Accordion>
   <Accordion title="11c. Shell 補全">
-    doctor 會檢查目前 shell（zsh、bash、fish 或 PowerShell）是否已安裝 tab 補全：
+    Doctor 會檢查目前 shell（zsh、bash、fish 或 PowerShell）是否已安裝分頁補全：
 
-    - 如果 shell profile 使用較慢的動態補全模式（`source <(openclaw completion ...)`），doctor 會將其升級為較快的快取檔案變體。
-    - 如果 profile 中已設定補全但快取檔案遺失，doctor 會自動重新產生快取。
-    - 如果完全沒有設定補全，doctor 會提示安裝（僅互動模式；使用 `--non-interactive` 時略過）。
+    - 如果 shell 設定檔使用較慢的動態補全模式（`source <(openclaw completion ...)`），doctor 會將它升級為較快的快取檔案變體。
+    - 如果補全已在設定檔中設定但快取檔案遺失，doctor 會自動重新產生快取。
+    - 如果完全沒有設定補全，doctor 會提示安裝它（僅互動模式；使用 `--non-interactive` 時略過）。
 
     執行 `openclaw completion --write-state` 可手動重新產生快取。
 
   </Accordion>
-  <Accordion title="12. Gateway 驗證檢查（本機 token）">
-    doctor 會檢查本機 gateway token 驗證就緒狀態。
+  <Accordion title="12. Gateway 驗證檢查（本機權杖）">
+    Doctor 會檢查本機 Gateway 權杖驗證準備狀態。
 
-    - 如果 token 模式需要 token 但不存在 token 來源，doctor 會提供產生一個的選項。
+    - 如果權杖模式需要權杖但沒有權杖來源，doctor 會提供產生權杖的選項。
     - 如果 `gateway.auth.token` 由 SecretRef 管理但無法使用，doctor 會發出警告，且不會以純文字覆寫它。
-    - `openclaw doctor --generate-gateway-token` 只會在未設定 token SecretRef 時強制產生。
+    - `openclaw doctor --generate-gateway-token` 只會在未設定權杖 SecretRef 時強制產生。
 
   </Accordion>
-  <Accordion title="12b. 可感知 SecretRef 的唯讀修復">
-    某些修復流程需要檢查已設定的憑證，同時不削弱 runtime fail-fast 行為。
+  <Accordion title="12b. SecretRef 感知的唯讀修復">
+    某些修復流程需要檢查已設定的憑證，而不削弱執行階段快速失敗行為。
 
-    - `openclaw doctor --fix` 現在會使用與 status-family commands 相同的唯讀 SecretRef 摘要模型，來進行目標 config 修復。
-    - 範例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修復會在可用時嘗試使用已設定的 bot 憑證。
-    - 如果 Telegram bot token 是透過 SecretRef 設定，但在目前指令路徑中無法使用，doctor 會回報憑證為已設定但無法使用，並略過自動解析，而不是當機或誤報 token 遺失。
+    - `openclaw doctor --fix` 現在會使用與狀態系列命令相同的唯讀 SecretRef 摘要模型，來進行目標式設定修復。
+    - 範例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修復會在可用時嘗試使用已設定的機器人憑證。
+    - 如果 Telegram 機器人 token 是透過 SecretRef 設定，但在目前命令路徑中不可用，doctor 會回報該憑證已設定但不可用，並略過自動解析，而不是當機或誤報 token 缺失。
 
   </Accordion>
   <Accordion title="13. Gateway 健康檢查 + 重新啟動">
-    Doctor 會執行健康檢查，並在 Gateway 看起來不健康時提議重新啟動 Gateway。
+    Doctor 會執行健康檢查，並在 Gateway 看起來不健康時提議重新啟動。
   </Accordion>
-  <Accordion title="13b. 記憶體搜尋就緒狀態">
-    Doctor 會檢查已設定的記憶體搜尋嵌入提供者是否已為預設代理程式就緒。行為取決於已設定的後端與提供者：
+  <Accordion title="13b. 記憶搜尋就緒狀態">
+    Doctor 會檢查已設定的記憶搜尋嵌入提供者是否已準備好供預設 agent 使用。其行為取決於已設定的後端與提供者：
 
-    - **QMD 後端**：探測 `qmd` 二進位檔是否可用且可啟動。若不可用，會列印修復指引，包括 npm 套件與手動二進位檔路徑選項。
-    - **明確本機提供者**：檢查本機模型檔案或可辨識的遠端/可下載模型 URL。若缺少，建議切換到遠端提供者。
-    - **明確遠端提供者**（`openai`、`voyage` 等）：驗證環境或驗證儲存區中是否存在 API 金鑰。若缺少，會列印可操作的修復提示。
-    - **自動提供者**：先檢查本機模型可用性，接著依自動選擇順序嘗試每個遠端提供者。
+    - **QMD 後端**：探測 `qmd` 二進位檔是否可用且可啟動。若否，會列印修復指引，包括 npm 套件與手動二進位檔路徑選項。
+    - **明確的本機提供者**：檢查本機模型檔案，或已辨識的遠端／可下載模型 URL。若缺失，會建議切換到遠端提供者。
+    - **明確的遠端提供者**（`openai`、`voyage` 等）：驗證環境或驗證儲存中是否存在 API 金鑰。若缺失，會列印可操作的修復提示。
+    - **自動提供者**：先檢查本機模型可用性，然後依自動選取順序嘗試每個遠端提供者。
 
-    當快取的 Gateway 探測結果可用時（Gateway 在檢查當下是健康的），doctor 會將其結果與 CLI 可見的設定交叉比對，並註記任何差異。Doctor 不會在預設路徑上啟動新的嵌入 ping；若要即時提供者檢查，請使用深度記憶體狀態命令。
+    當快取的 Gateway 探測結果可用時（Gateway 在檢查時是健康的），doctor 會將其結果與 CLI 可見的設定交叉比對，並註記任何差異。Doctor 不會在預設路徑上啟動新的嵌入 ping；如果你想要即時提供者檢查，請使用深度記憶狀態命令。
 
-    使用 `openclaw memory status --deep` 在執行時驗證嵌入就緒狀態。
+    使用 `openclaw memory status --deep` 在執行階段驗證嵌入就緒狀態。
 
   </Accordion>
   <Accordion title="14. 通道狀態警告">
     如果 Gateway 健康，doctor 會執行通道狀態探測，並回報警告與建議修復方式。
   </Accordion>
   <Accordion title="15. Supervisor 設定稽核 + 修復">
-    Doctor 會檢查已安裝的 supervisor 設定（launchd/systemd/schtasks）是否缺少預設值或預設值過時（例如 systemd network-online 相依性與重新啟動延遲）。當發現不一致時，會建議更新，並可將服務檔案/工作重寫為目前預設值。
+    Doctor 會檢查已安裝的 supervisor 設定（launchd/systemd/schtasks）是否缺少預設值或使用過時預設值（例如 systemd network-online 相依性與重新啟動延遲）。當發現不一致時，它會建議更新，並可將服務檔案／工作重寫為目前預設值。
 
     注意：
 
@@ -461,39 +468,39 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
     - `openclaw doctor --yes` 會接受預設修復提示。
     - `openclaw doctor --repair` 會在不提示的情況下套用建議修復。
     - `openclaw doctor --repair --force` 會覆寫自訂 supervisor 設定。
-    - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 會讓 doctor 在 Gateway 服務生命週期中保持唯讀。它仍會回報服務健康狀態並執行非服務修復，但會略過服務安裝/啟動/重新啟動/bootstrap、supervisor 設定重寫，以及舊版服務清理，因為該生命週期由外部 supervisor 擁有。
-    - 在 Linux 上，當相符的 systemd Gateway unit 為作用中時，doctor 不會重寫命令/進入點中繼資料。它也會在重複服務掃描期間忽略非作用中的非舊版額外類 Gateway unit，因此輔助服務檔案不會產生清理雜訊。
-    - 如果 token 驗證需要 token，且 `gateway.auth.token` 由 SecretRef 管理，doctor 服務安裝/修復會驗證 SecretRef，但不會將解析後的純文字 token 值持久化到 supervisor 服務環境中繼資料中。
-    - Doctor 會偵測舊版 LaunchAgent、systemd 或 Windows 排程工作安裝中內嵌行內的受管理 `.env`/SecretRef 支援服務環境值，並重寫服務中繼資料，讓這些值從執行時來源載入，而非從 supervisor 定義載入。
-    - Doctor 會偵測服務命令在 `gateway.port` 變更後是否仍固定舊的 `--port`，並將服務中繼資料重寫為目前連接埠。
-    - 如果 token 驗證需要 token，且已設定的 token SecretRef 無法解析，doctor 會封鎖安裝/修復路徑並提供可操作的指引。
-    - 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，doctor 會封鎖安裝/修復，直到明確設定模式為止。
-    - 對於 Linux 使用者 systemd unit，doctor token 漂移檢查現在會在比較服務驗證中繼資料時包含 `Environment=` 與 `EnvironmentFile=` 來源。
-    - 當設定最後由較新版本寫入時，Doctor 服務修復會拒絕重寫、停止或重新啟動來自較舊 OpenClaw 二進位檔的 Gateway 服務。請參閱 [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
-    - 你一律可以透過 `openclaw gateway install --force` 強制完整重寫。
+    - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 會讓 doctor 對 Gateway 服務生命週期保持唯讀。它仍會回報服務健康狀態並執行非服務修復，但會略過服務安裝／啟動／重新啟動／bootstrap、supervisor 設定重寫，以及舊版服務清理，因為該生命週期由外部 supervisor 擁有。
+    - 在 Linux 上，當相符的 systemd Gateway unit 處於作用中時，doctor 不會重寫命令／進入點中繼資料。它也會在重複服務掃描期間忽略未啟用的非舊版額外 Gateway 類 unit，因此伴隨服務檔案不會產生清理雜訊。
+    - 如果 token 驗證需要 token 且 `gateway.auth.token` 由 SecretRef 管理，doctor 服務安裝／修復會驗證 SecretRef，但不會將解析出的明文 token 值持久化到 supervisor 服務環境中繼資料。
+    - Doctor 會偵測舊版 LaunchAgent、systemd 或 Windows 排定工作安裝中內嵌的受管理 `.env`／SecretRef 支援服務環境值，並重寫服務中繼資料，讓這些值從執行階段來源載入，而不是從 supervisor 定義載入。
+    - Doctor 會偵測服務命令在 `gateway.port` 變更後仍固定舊的 `--port`，並將服務中繼資料重寫為目前連接埠。
+    - 如果 token 驗證需要 token 且已設定的 token SecretRef 無法解析，doctor 會以可操作的指引阻擋安裝／修復路徑。
+    - 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，doctor 會阻擋安裝／修復，直到明確設定模式為止。
+    - 對於 Linux 使用者 systemd unit，doctor token 漂移檢查現在會在比較服務驗證中繼資料時，同時包含 `Environment=` 與 `EnvironmentFile=` 來源。
+    - 當設定最後是由較新版本寫入時，Doctor 服務修復會拒絕重寫、停止或重新啟動來自較舊 OpenClaw 二進位檔的 Gateway 服務。請參閱 [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
+    - 你始終可以透過 `openclaw gateway install --force` 強制完整重寫。
 
   </Accordion>
-  <Accordion title="16. Gateway 執行時 + 連接埠診斷">
-    Doctor 會檢查服務執行時（PID、上次結束狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查 Gateway 連接埠（預設 `18789`）上的連接埠衝突，並回報可能原因（Gateway 已在執行、SSH tunnel）。
+  <Accordion title="16. Gateway 執行階段 + 連接埠診斷">
+    Doctor 會檢查服務執行階段（PID、上次退出狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查 Gateway 連接埠（預設 `18789`）上的連接埠衝突，並回報可能原因（Gateway 已在執行、SSH 通道）。
   </Accordion>
-  <Accordion title="17. Gateway 執行時最佳實務">
-    當 Gateway 服務在 Bun 或版本管理的 Node 路徑（`nvm`、`fnm`、`volta`、`asdf` 等）上執行時，Doctor 會發出警告。WhatsApp + Telegram 通道需要 Node，而版本管理器路徑在升級後可能失效，因為服務不會載入你的 shell init。Doctor 會在可用時提議遷移到系統 Node 安裝（Homebrew/apt/choco）。
+  <Accordion title="17. Gateway 執行階段最佳實務">
+    Doctor 會在 Gateway 服務執行於 Bun 或版本管理的 Node 路徑（`nvm`、`fnm`、`volta`、`asdf` 等）時發出警告。WhatsApp + Telegram 通道需要 Node，而版本管理器路徑可能會在升級後中斷，因為服務不會載入你的 shell init。當系統 Node 安裝可用時（Homebrew/apt/choco），Doctor 會提議遷移到系統 Node 安裝。
 
-    新安裝或修復的 macOS LaunchAgent 會使用標準系統 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是複製互動式 shell PATH，因此 Volta、asdf、fnm、pnpm 與其他版本管理器目錄不會改變 Node 子程序解析的位置。Linux 服務仍會保留明確的環境根目錄（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）與穩定的使用者 bin 目錄，但推測的版本管理器後援目錄只會在那些目錄存在於磁碟上時寫入服務 PATH。
+    新安裝或修復的 macOS LaunchAgent 會使用標準系統 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是複製互動式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目錄不會改變 Node 子程序解析到哪裡。Linux 服務仍會保留明確的環境根目錄（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）與穩定的使用者 bin 目錄，但推測的版本管理器備援目錄只有在那些目錄實際存在於磁碟上時，才會寫入服務 PATH。
 
   </Accordion>
   <Accordion title="18. 設定寫入 + 精靈中繼資料">
     Doctor 會持久化任何設定變更，並標記精靈中繼資料以記錄 doctor 執行。
   </Accordion>
-  <Accordion title="19. 工作區提示（備份 + 記憶體系統）">
-    Doctor 會在缺少時建議工作區記憶體系統，並在工作區尚未納入 git 時列印備份提示。
+  <Accordion title="19. 工作區提示（備份 + 記憶系統）">
+    Doctor 會在缺少工作區記憶系統時提出建議，並在工作區尚未納入 git 管理時列印備份提示。
 
-    請參閱 [/concepts/agent-workspace](/zh-TW/concepts/agent-workspace)，取得工作區結構與 git 備份的完整指南（建議使用私有 GitHub 或 GitLab）。
+    請參閱 [/concepts/agent-workspace](/zh-TW/concepts/agent-workspace)，了解工作區結構與 git 備份的完整指南（建議使用私有 GitHub 或 GitLab）。
 
   </Accordion>
 </AccordionGroup>
 
 ## 相關
 
-- [Gateway runbook](/zh-TW/gateway)
+- [Gateway 執行手冊](/zh-TW/gateway)
 - [Gateway 疑難排解](/zh-TW/gateway/troubleshooting)

docs/zh-TW/gateway/logging.md

@@ -2,89 +2,112 @@
 read_when:
     - 變更日誌輸出或格式
     - 偵錯 CLI 或 Gateway 輸出
-summary: 日誌介面、檔案日誌、WS 日誌樣式，以及主控台格式設定
+summary: 日誌介面、檔案日誌、WS 日誌樣式與主控台格式設定
 title: Gateway 日誌記錄
 x-i18n:
-    generated_at: "2026-05-02T02:49:57Z"
+    generated_at: "2026-05-05T01:46:23Z"
     model: gpt-5.5
     provider: openai
-    source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13
+    source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246
     source_path: gateway/logging.md
     workflow: 16
 ---
 
-# 日誌
+# 記錄
 
-如需面向使用者的概覽（CLI + Control UI + 設定），請參閱 [/logging](/zh-TW/logging)。
+如需面向使用者的總覽（CLI + 控制 UI + 設定），請參閱 [/logging](/zh-TW/logging)。
 
-OpenClaw 有兩個日誌「介面」：
+OpenClaw 有兩個記錄「介面」：
 
-- **主控台輸出**（你在終端機 / Debug UI 中看到的內容）。
-- **檔案日誌**（JSON lines），由 Gateway 記錄器寫入。
+- **主控台輸出**（你在終端機 / 偵錯 UI 中看到的內容）。
+- **檔案記錄**（JSON 行），由 Gateway 記錄器寫入。
 
-## 檔案型記錄器
+啟動時，Gateway 會記錄解析後的預設代理模型，以及會影響新工作階段的
+模式預設值，例如：
 
-- 預設輪替日誌檔位於 `/tmp/openclaw/` 下（每天一個檔案）：`openclaw-YYYY-MM-DD.log`
+```text
+agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
+```
+
+`thinking` 來自預設代理、模型參數或全域代理預設值；
+未設定時，啟動摘要會顯示 `medium`。`fast` 來自預設代理或模型 `fastMode` 參數。
+
+## 檔案式記錄器
+
+- 預設輪替記錄檔位於 `/tmp/openclaw/` 下（每天一個檔案）：`openclaw-YYYY-MM-DD.log`
   - 日期使用 Gateway 主機的本地時區。
-- 作用中的日誌檔會在 `logging.maxFileBytes`（預設：100 MB）輪替，最多保留五個編號封存檔，並繼續寫入新的作用中檔案。
-- 日誌檔路徑和層級可透過 `~/.openclaw/openclaw.json` 設定：
+- 作用中的記錄檔會在 `logging.maxFileBytes` 時輪替（預設：100 MB），保留
+  最多五個編號封存檔，並繼續寫入新的作用中檔案。
+- 記錄檔路徑與層級可透過 `~/.openclaw/openclaw.json` 設定：
   - `logging.file`
   - `logging.level`
 
 檔案格式為每行一個 JSON 物件。
 
-Control UI 的 Logs 分頁會透過 Gateway 追蹤此檔案（`logs.tail`）。
+控制 UI 的記錄分頁會透過 Gateway 追蹤此檔案（`logs.tail`）。
 CLI 也可以執行相同操作：
 
 ```bash
 openclaw logs --follow
 ```
 
-**詳細模式與日誌層級**
+**詳細模式與記錄層級**
 
-- **檔案日誌**完全由 `logging.level` 控制。
-- `--verbose` 只影響**主控台詳細程度**（以及 WS 日誌樣式）；它**不會**提高檔案日誌層級。
-- 若要在檔案日誌中擷取僅詳細模式才有的細節，請將 `logging.level` 設為 `debug` 或 `trace`。
-- Trace 日誌也會包含所選熱路徑的診斷計時摘要，例如 Plugin 工具工廠準備。請參閱 [/tools/plugin#slow-plugin-tool-setup](/zh-TW/tools/plugin#slow-plugin-tool-setup)。
+- **檔案記錄**只由 `logging.level` 控制。
+- `--verbose` 只影響**主控台詳細程度**（以及 WS 記錄樣式）；它**不會**
+  提高檔案記錄層級。
+- 若要在檔案記錄中擷取僅詳細模式才有的細節，請將 `logging.level` 設為 `debug` 或
+  `trace`。
+- Trace 記錄也包含所選熱路徑的診斷計時摘要，
+  例如 Plugin 工具工廠準備。請參閱
+  [/tools/plugin#slow-plugin-tool-setup](/zh-TW/tools/plugin#slow-plugin-tool-setup)。
 
 ## 主控台擷取
 
-CLI 會擷取 `console.log/info/warn/error/debug/trace` 並寫入檔案日誌，同時仍會列印到 stdout/stderr。
+CLI 會擷取 `console.log/info/warn/error/debug/trace` 並將其寫入檔案記錄，
+同時仍會列印到 stdout/stderr。
 
 你可以透過以下項目獨立調整主控台詳細程度：
 
 - `logging.consoleLevel`（預設 `info`）
 - `logging.consoleStyle`（`pretty` | `compact` | `json`）
 
-## 遮蔽
+## 遮罩
 
-OpenClaw 可以在日誌或轉錄輸出離開程序前遮蔽敏感權杖。此日誌遮蔽政策會套用於主控台、檔案日誌、OTLP 日誌記錄和工作階段轉錄文字輸出端，因此相符的密鑰值會在 JSONL 行或訊息寫入磁碟前被遮蔽。
+OpenClaw 可以在記錄或逐字稿輸出離開程序前遮罩敏感權杖。
+此記錄遮罩政策會套用至主控台、檔案記錄、OTLP
+記錄項目與工作階段逐字稿文字接收端，因此相符的機密值會在 JSONL 行或訊息寫入磁碟前被遮罩。
 
-- `logging.redactSensitive`: `off` | `tools`（預設：`tools`）
-- `logging.redactPatterns`: regex 字串陣列（覆寫預設值）
+- `logging.redactSensitive`：`off` | `tools`（預設：`tools`）
+- `logging.redactPatterns`：regex 字串陣列（覆寫預設值）
   - 使用原始 regex 字串（自動 `gi`），或在需要自訂旗標時使用 `/pattern/flags`。
-  - 相符內容會透過保留前 6 + 後 4 個字元來遮蔽（長度 >= 18），否則為 `***`。
-  - 預設涵蓋常見的金鑰指定、CLI 旗標、JSON 欄位、bearer 標頭、PEM 區塊、常見權杖前綴，以及付款憑證欄位名稱，例如卡號、CVC/CVV、共用付款權杖和付款憑證。
+  - 相符項目會保留前 6 + 後 4 個字元（長度 >= 18）並遮罩，其餘則為 `***`。
+  - 預設值涵蓋常見金鑰指定、CLI 旗標、JSON 欄位、bearer 標頭、PEM 區塊、常見權杖前綴，以及付款憑證欄位名稱，例如卡號、CVC/CVV、共用付款權杖與付款憑證。
 
-某些安全邊界一律遮蔽，不受 `logging.redactSensitive` 影響。這包括 Control UI 工具呼叫事件、`sessions_history` 工具輸出、診斷支援匯出、提供者錯誤觀察、exec 核准命令顯示，以及 Gateway WebSocket 通訊協定日誌。這些介面仍可使用 `logging.redactPatterns` 作為額外模式，但 `redactSensitive: "off"` 不會讓它們輸出原始密鑰。
+部分安全邊界無論 `logging.redactSensitive` 為何都一律遮罩。
+這包括控制 UI 工具呼叫事件、`sessions_history` 工具輸出、
+診斷支援匯出、供應商錯誤觀察、exec 核准命令
+顯示，以及 Gateway WebSocket 通訊協定記錄。這些介面仍可使用
+`logging.redactPatterns` 作為額外模式，但 `redactSensitive: "off"`
+不會讓它們輸出原始機密。
 
-## Gateway WebSocket 日誌
+## Gateway WebSocket 記錄
 
-Gateway 會以兩種模式列印 WebSocket 通訊協定日誌：
+Gateway 會以兩種模式列印 WebSocket 通訊協定記錄：
 
-- **一般模式（沒有 `--verbose`）**：只列印「有意義」的 RPC 結果：
+- **一般模式（無 `--verbose`）**：只列印「有意義」的 RPC 結果：
   - 錯誤（`ok=false`）
-  - 慢速呼叫（預設閾值：`>= 50ms`）
+  - 緩慢呼叫（預設閾值：`>= 50ms`）
   - 剖析錯誤
-- **詳細模式（`--verbose`）**：列印所有 WS 要求/回應流量。
+- **詳細模式（`--verbose`）**：列印所有 WS 請求/回應流量。
 
-### WS 日誌樣式
+### WS 記錄樣式
 
 `openclaw gateway` 支援每個 Gateway 的樣式切換：
 
-- `--ws-log auto`（預設）：一般模式會最佳化；詳細模式使用精簡輸出
-- `--ws-log compact`：詳細模式時使用精簡輸出（配對的要求/回應）
-- `--ws-log full`：詳細模式時使用完整的逐訊框輸出
+- `--ws-log auto`（預設）：一般模式為最佳化；詳細模式使用精簡輸出
+- `--ws-log compact`：詳細模式時使用精簡輸出（成對的請求/回應）
+- `--ws-log full`：詳細模式時使用完整逐框輸出
 - `--compact`：`--ws-log compact` 的別名
 
 範例：
@@ -100,26 +123,27 @@ openclaw gateway --verbose --ws-log compact
 openclaw gateway --verbose --ws-log full
 ```
 
-## 主控台格式化（子系統日誌）
+## 主控台格式化（子系統記錄）
 
-主控台格式化器具備 **TTY 感知**能力，並會列印一致且帶有前綴的行。子系統記錄器會讓輸出保持分組且易於掃描。
+主控台格式化工具具備 **TTY 感知**能力，並列印一致且帶前綴的行。
+子系統記錄器會讓輸出保持分組且易於掃描。
 
 行為：
 
-- 每行都有**子系統前綴**（例如 `[gateway]`、`[canvas]`、`[tailscale]`）
-- **子系統顏色**（每個子系統穩定）加上層級著色
-- **當輸出是 TTY 或環境看起來像豐富終端機時使用顏色**（`TERM`/`COLORTERM`/`TERM_PROGRAM`），並遵循 `NO_COLOR`
-- **縮短的子系統前綴**：移除前導 `gateway/` + `channels/`，保留最後 2 個片段（例如 `whatsapp/outbound`）
-- **依子系統的子記錄器**（自動前綴 + 結構化欄位 `{ subsystem }`）
+- 每一行都有**子系統前綴**（例如 `[gateway]`、`[canvas]`、`[tailscale]`）
+- **子系統色彩**（每個子系統穩定）加上層級著色
+- **當輸出為 TTY 或環境看起來像豐富終端機時使用色彩**（`TERM`/`COLORTERM`/`TERM_PROGRAM`），並遵循 `NO_COLOR`
+- **縮短的子系統前綴**：移除前導 `gateway/` + `channels/`，保留最後 2 個區段（例如 `whatsapp/outbound`）
+- **依子系統建立子記錄器**（自動前綴 + 結構化欄位 `{ subsystem }`）
 - **`logRaw()`** 用於 QR/UX 輸出（無前綴、無格式化）
 - **主控台樣式**（例如 `pretty | compact | json`）
-- **主控台日誌層級**與檔案日誌層級分開（當 `logging.level` 設為 `debug`/`trace` 時，檔案會保留完整細節）
+- **主控台記錄層級**與檔案記錄層級分開（當 `logging.level` 設為 `debug`/`trace` 時，檔案會保留完整細節）
 - **WhatsApp 訊息本文**會以 `debug` 記錄（使用 `--verbose` 查看）
 
-這會讓既有檔案日誌保持穩定，同時讓互動式輸出更容易掃描。
+這會在維持現有檔案記錄穩定的同時，讓互動式輸出易於掃描。
 
 ## 相關
 
-- [日誌](/zh-TW/logging)
+- [記錄](/zh-TW/logging)
 - [OpenTelemetry 匯出](/zh-TW/gateway/opentelemetry)
 - [診斷匯出](/zh-TW/gateway/diagnostics)

docs/zh-TW/help/debugging.md

@@ -1,26 +1,26 @@
 ---
 read_when:
-    - 你需要檢查原始模型輸出是否有推理內容外洩
-    - 您想在反覆調整時以監看模式執行 Gateway
-    - 你需要一套可重複的除錯工作流程
-summary: 偵錯工具：監看模式、原始模型串流，以及追蹤推理洩漏
-title: 偵錯
+    - 你需要檢查原始模型輸出是否有推理洩漏
+    - 你想要在反覆開發時以監看模式執行 Gateway
+    - 你需要一套可重複的偵錯工作流程
+summary: 除錯工具：監看模式、原始模型串流，以及追蹤推理洩漏
+title: 除錯
 x-i18n:
-    generated_at: "2026-05-03T21:35:13Z"
+    generated_at: "2026-05-05T01:46:58Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc
+    source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec
     source_path: help/debugging.md
     workflow: 16
 ---
 
-串流輸出偵錯輔助工具，特別適用於提供者將推理內容混入一般文字時。
+偵錯串流輸出的輔助工具，特別適用於 provider 將 reasoning 混入一般文字時。
 
 ## 執行階段偵錯覆寫
 
-在聊天中使用 `/debug` 設定**僅限執行階段**的設定覆寫（記憶體，不寫入磁碟）。
+在聊天中使用 `/debug` 設定**僅限執行階段**的設定覆寫（記憶體中，而非磁碟）。
 `/debug` 預設停用；使用 `commands.debug: true` 啟用。
-當你需要切換冷門設定而不編輯 `openclaw.json` 時，這很方便。
+當你需要切換冷僻設定而不編輯 `openclaw.json` 時，這很方便。
 
 範例：
 
@@ -31,12 +31,12 @@ x-i18n:
 /debug reset
 ```
 
-`/debug reset` 會清除所有覆寫，並回到磁碟上的設定。
+`/debug reset` 會清除所有覆寫並回到磁碟上的設定。
 
-## Session 追蹤輸出
+## 工作階段追蹤輸出
 
-當你想在單一 Session 中查看 Plugin 擁有的追蹤／偵錯行，
-但不想開啟完整 verbose 模式時，請使用 `/trace`。
+當你想在單一工作階段中查看由 Plugin 擁有的追蹤/偵錯行，
+而不啟用完整詳細模式時，請使用 `/trace`。
 
 範例：
 
@@ -46,14 +46,14 @@ x-i18n:
 /trace off
 ```
 
-針對 Active Memory 偵錯摘要等 Plugin 診斷使用 `/trace`。
-一般 verbose 狀態／工具輸出請繼續使用 `/verbose`，僅限執行階段的設定覆寫則繼續使用
+使用 `/trace` 查看 Plugin 診斷，例如 Active Memory 偵錯摘要。
+一般詳細狀態/工具輸出請繼續使用 `/verbose`，而僅限執行階段的設定覆寫請繼續使用
 `/debug`。
 
 ## Plugin 生命週期追蹤
 
-當 Plugin 生命週期命令感覺很慢，而你需要內建的階段拆解來檢視 Plugin 中繼資料、探索、登錄、
-執行階段鏡像、設定變更與重新整理工作時，請使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。追蹤為選用，並寫入
+當 Plugin 生命週期命令感覺緩慢，且你需要內建的階段分解來檢查 Plugin 中繼資料、探索、登錄、
+執行階段鏡像、設定變更與重新整理工作時，請使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。此追蹤為選擇啟用，並寫入
 stderr，因此 JSON 命令輸出仍可解析。
 
 範例：
@@ -70,13 +70,14 @@ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
 [plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
 ```
 
-在使用 CPU profiler 之前，先用這個調查 Plugin 生命週期。
-如果命令是從原始碼 checkout 執行，建議在 `pnpm build` 後用 `node dist/entry.js ...` 測量建置後的
-runtime；`pnpm openclaw ...` 也會測量 source-runner 開銷。
+在使用 CPU profiler 之前，先用它調查 Plugin 生命週期。
+如果命令是從原始碼 checkout 執行，請優先在 `pnpm build` 後使用
+`node dist/entry.js ...` 測量已建置的執行階段；`pnpm openclaw ...`
+也會測量 source-runner 開銷。
 
-## CLI 啟動與命令剖析
+## CLI 啟動與命令 profiling
 
-當命令感覺很慢時，使用已簽入的啟動基準測試：
+當命令感覺緩慢時，使用已提交的啟動 benchmark：
 
 ```bash
 pnpm test:startup:bench:smoke
@@ -84,7 +85,7 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
 pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
 ```
 
-若要透過一般 source runner 進行一次性剖析，請設定
+若要透過一般 source runner 做一次性 profiling，請設定
 `OPENCLAW_RUN_NODE_CPU_PROF_DIR`：
 
 ```bash
@@ -92,21 +93,32 @@ OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
 ```
 
 source runner 會加入 Node CPU profile 旗標，並為該命令寫入 `.cpuprofile`。
-在向命令程式碼加入暫時 instrumentation 前，先使用這個方法。
+在向命令程式碼加入暫時 instrumentation 之前，先使用這個方法。
 
-## Gateway 監看模式
+對於看起來像同步檔案系統或 module-loader 工作造成的啟動停滯，
+請透過 source runner 加入 Node 的同步 I/O trace 旗標：
 
-為了快速迭代，請在檔案 watcher 下執行 gateway：
+```bash
+OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
+```
+
+`pnpm gateway:watch` 預設會為受監看的 Gateway 子程序啟用此旗標。
+設定 `OPENCLAW_TRACE_SYNC_IO=0` 可在 watch
+模式中抑制 Node 同步 I/O trace 輸出。
+
+## Gateway watch 模式
+
+若要快速迭代，請在檔案監看器下執行 gateway：
 
 ```bash
 pnpm gateway:watch
 ```
 
 預設情況下，這會啟動或重新啟動名為
-`openclaw-gateway-watch-main` 的 tmux Session（或 profile／port 專屬變體，例如
-`openclaw-gateway-watch-dev-19001`），並從互動式終端機自動附加。
-非互動式 shell、CI 和代理執行呼叫會保持分離，並改為列印附加指示。
-需要時可手動附加：
+`openclaw-gateway-watch-main` 的 tmux 工作階段（或 profile/port 專屬變體，例如
+`openclaw-gateway-watch-dev-19001`），並從互動式終端機自動 attach。
+非互動式 shell、CI 和 agent exec 呼叫會保持 detached，並改為列印 attach
+指示。需要時可手動 attach：
 
 ```bash
 tmux attach -t openclaw-gateway-watch-main
@@ -126,57 +138,63 @@ pnpm gateway:watch:raw
 OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
 ```
 
-保留 tmux 管理但停用自動附加：
+停用自動 attach，同時保留 tmux 管理：
 
 ```bash
 OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
 ```
 
-偵錯啟動／runtime 熱點時，剖析受監看的 Gateway CPU 時間：
+偵錯啟動/執行階段熱點時，profile 受監看的 Gateway CPU 時間：
 
 ```bash
 pnpm gateway:watch --benchmark
 ```
 
-watch wrapper 會在呼叫 Gateway 前消耗 `--benchmark`，並在每個 Gateway child 結束時，於
-`.artifacts/gateway-watch-profiles/` 下寫入一個 V8 `.cpuprofile`。
-停止或重新啟動受監看的 gateway 以 flush 目前 profile，然後用 Chrome DevTools 或 Speedscope 開啟：
+watch wrapper 會在叫用 Gateway 前消耗 `--benchmark`，並在
+`.artifacts/gateway-watch-profiles/` 下為每次 Gateway 子程序結束寫入一個 V8 `.cpuprofile`。
+停止或重新啟動受監看的 gateway 以 flush 目前的 profile，然後用 Chrome DevTools 或 Speedscope 開啟：
 
 ```bash
 npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
 ```
 
-當你想把 profile 放在其他地方時，使用 `--benchmark-dir <path>`。
-當你想讓被基準測試的 child 跳過預設 `--force` port 清理，並在 Gateway port 已在使用中時快速失敗，請使用
-`--benchmark-no-force`。
+當你想將 profiles 放到其他位置時，請使用 `--benchmark-dir <path>`。
+當你想讓 benchmarked 子程序略過預設的 `--force` 連接埠清理，並在 Gateway 連接埠已被使用時快速失敗，請使用 `--benchmark-no-force`。
+benchmark 模式預設會抑制同步 I/O trace 雜訊。當你明確同時需要 CPU
+profiles 和 Node 同步 I/O stack traces 時，請搭配 `--benchmark` 設定
+`OPENCLAW_TRACE_SYNC_IO=1`。在 benchmark 模式中，這些 trace block
+會寫入 benchmark 目錄下的 `gateway-watch-output.log`，並從終端機 pane 中過濾掉；一般 Gateway logs 仍會顯示。
 
-tmux wrapper 會將常見的非秘密 runtime 選擇器帶入 pane，例如
+tmux wrapper 會將常見的非秘密執行階段 selector 帶入 pane，例如
 `OPENCLAW_PROFILE`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、
-`OPENCLAW_GATEWAY_PORT` 和 `OPENCLAW_SKIP_CHANNELS`。請將提供者憑證放在一般 profile／config 中，或針對一次性暫時秘密使用原始前景模式。
-如果受監看的 Gateway 在啟動期間結束，watcher 會執行一次
-`openclaw doctor --fix --non-interactive`，然後重新啟動 Gateway child。
-當你想取得原始啟動失敗，而不要 dev-only 修復流程時，使用 `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`。
-受管理的 tmux pane 也預設使用彩色 Gateway 記錄以提高可讀性；
+`OPENCLAW_GATEWAY_PORT` 和 `OPENCLAW_SKIP_CHANNELS`。請將
+provider credentials 放在你的正常 profile/config 中，或使用原始前景模式處理一次性的 ephemeral secrets。
+如果受監看的 Gateway 在啟動期間退出，watcher 會執行一次
+`openclaw doctor --fix --non-interactive`，然後重新啟動 Gateway 子程序。
+當你想取得原始啟動失敗，而不執行僅限開發的修復 pass 時，請使用
+`OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`。
+受管理的 tmux pane 也預設使用彩色 Gateway logs 以提高可讀性；
 啟動 `pnpm gateway:watch` 時設定 `FORCE_COLOR=0` 可停用 ANSI 輸出。
 
-watcher 會在 `src/` 下與建置相關的檔案、extension 原始碼檔案、
+watcher 會在 `src/` 下與建置相關的檔案、extension 原始檔、
 extension `package.json` 與 `openclaw.plugin.json` 中繼資料、`tsconfig.json`、
-`package.json` 和 `tsdown.config.ts` 變更時重新啟動。Extension 中繼資料變更會在不強制 `tsdown` 重建的情況下重新啟動
-gateway；原始碼與設定變更仍會先重建 `dist`。
+`package.json` 和 `tsdown.config.ts` 變更時重新啟動。extension 中繼資料變更會重新啟動
+gateway，而不強制執行 `tsdown` rebuild；source 和 config 變更仍會先
+rebuild `dist`。
 
-在 `gateway:watch` 後加入任何 gateway CLI 旗標，這些旗標都會在每次重新啟動時傳遞。
-重新執行相同 watch 命令會重新產生具名 tmux pane，而原始 watcher 仍會維持其單一 watcher 鎖，因此重複的 watcher parent
-會被取代而不是堆疊。
+在 `gateway:watch` 後加入任何 gateway CLI 旗標，它們都會在每次重新啟動時傳遞。
+重新執行相同的 watch 命令會 respawn 具名 tmux pane，而原始 watcher 仍保有其 single-watcher lock，因此重複的 watcher parent
+會被替換，而不是不斷堆疊。
 
 ## Dev profile + dev gateway (--dev)
 
-使用 dev profile 隔離狀態，並啟動安全、可拋棄的設定以進行偵錯。
-有**兩個** `--dev` 旗標：
+使用 dev profile 來隔離狀態，並啟動安全、可拋棄的設定以供
+偵錯。這裡有**兩個** `--dev` 旗標：
 
-- **全域 `--dev`（profile）：** 將狀態隔離在 `~/.openclaw-dev` 下，並將
-  gateway port 預設為 `19001`（衍生 port 會隨之位移）。
-- **`gateway --dev`：告訴 Gateway 在缺少時自動建立預設 config +
-  workspace**（並跳過 BOOTSTRAP.md）。
+- **全域 `--dev`（profile）：** 將狀態隔離在 `~/.openclaw-dev` 下，並
+  將 gateway 連接埠預設為 `19001`（衍生連接埠會隨之平移）。
+- **`gateway --dev`：指示 Gateway 在缺少時自動建立預設 config +
+  workspace**（並略過 BOOTSTRAP.md）。
 
 建議流程（dev profile + dev bootstrap）：
 
@@ -185,24 +203,24 @@ pnpm gateway:dev
 OPENCLAW_PROFILE=dev openclaw tui
 ```
 
-如果你尚未全域安裝，請透過 `pnpm openclaw ...` 執行 CLI。
+如果你還沒有全域安裝，請透過 `pnpm openclaw ...` 執行 CLI。
 
-這會做的事：
+這會做什麼：
 
 1. **Profile 隔離**（全域 `--dev`）
    - `OPENCLAW_PROFILE=dev`
    - `OPENCLAW_STATE_DIR=~/.openclaw-dev`
    - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
-   - `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 也會相應位移）
+   - `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 會相應平移）
 
 2. **Dev bootstrap**（`gateway --dev`）
-   - 若缺少，寫入最小設定（`gateway.mode=local`，bind loopback）。
+   - 如果缺少，寫入最小 config（`gateway.mode=local`，bind loopback）。
    - 將 `agent.workspace` 設為 dev workspace。
-   - 設定 `agent.skipBootstrap=true`（沒有 BOOTSTRAP.md）。
-   - 若缺少，植入 workspace 檔案：
+   - 設定 `agent.skipBootstrap=true`（無 BOOTSTRAP.md）。
+   - 如果缺少，seed workspace 檔案：
      `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
-   - 預設身分：**C3‑PO**（禮儀機器人）。
-   - 在 dev 模式中跳過 channel provider（`OPENCLAW_SKIP_CHANNELS=1`）。
+   - 預設 identity：**C3‑PO**（protocol droid）。
+   - 在 dev 模式中略過 channel providers（`OPENCLAW_SKIP_CHANNELS=1`）。
 
 重設流程（全新開始）：
 
@@ -231,10 +249,11 @@ openclaw gateway stop
 
 </Tip>
 
-## 原始串流記錄（OpenClaw）
+## 原始 stream logging (OpenClaw)
 
-OpenClaw 可以在任何篩選／格式化之前記錄**原始 assistant 串流**。
-這是查看推理內容是否以純文字 deltas 到達（或以獨立 thinking blocks 到達）的最佳方式。
+OpenClaw 可以在任何 filtering/formatting 之前記錄**原始 assistant stream**。
+這是判斷 reasoning 是否以純文字 deltas 抵達
+（或以獨立 thinking blocks 抵達）的最佳方式。
 
 透過 CLI 啟用：
 
@@ -242,7 +261,7 @@ OpenClaw 可以在任何篩選／格式化之前記錄**原始 assistant 串流*
 pnpm gateway:watch --raw-stream
 ```
 
-選用路徑覆寫：
+可選的 path 覆寫：
 
 ```bash
 pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
@@ -259,16 +278,16 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
 
 `~/.openclaw/logs/raw-stream.jsonl`
 
-## 原始 chunk 記錄（pi-mono）
+## 原始 chunk logging (pi-mono)
 
-若要在解析成 blocks 之前擷取**原始 OpenAI 相容 chunks**，
+若要在 **raw OpenAI-compat chunks** 被解析成 blocks 前擷取它們，
 pi-mono 提供獨立 logger：
 
 ```bash
 PI_RAW_STREAM=1
 ```
 
-選用路徑：
+可選 path：
 
 ```bash
 PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
@@ -283,11 +302,11 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
 
 ## 安全注意事項
 
-- 原始串流記錄可能包含完整 prompts、工具輸出與使用者資料。
-- 將記錄保留在本機，並在偵錯後刪除。
-- 如果你分享記錄，請先清除秘密與 PII。
+- 原始 stream logs 可能包含完整 prompts、tool output 和 user data。
+- 將 logs 保持在本機，並在偵錯後刪除。
+- 如果你分享 logs，請先清除 secrets 和 PII。
 
 ## 相關
 
 - [疑難排解](/zh-TW/help/troubleshooting)
-- [FAQ](/zh-TW/help/faq)
+- [常見問題](/zh-TW/help/faq)

docs/zh-TW/help/faq-models.md

@@ -1,24 +1,24 @@
 ---
 read_when:
     - 選擇或切換模型、設定別名
-    - 模型容錯移轉偵錯 /「所有模型都失敗」
+    - 偵錯模型容錯移轉 /「所有模型皆失敗」
     - 了解驗證設定檔及其管理方式
 sidebarTitle: Models FAQ
-summary: 常見問題：模型預設值、選擇、別名、切換、容錯移轉與驗證設定檔
+summary: 常見問題：模型預設值、選擇、別名、切換、故障轉移與身分驗證設定檔
 title: 常見問題：模型與身分驗證
 x-i18n:
-    generated_at: "2026-05-02T02:52:23Z"
+    generated_at: "2026-05-05T01:47:11Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
+    source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54
     source_path: help/faq-models.md
     workflow: 16
 ---
 
-  模型與驗證設定檔問答。關於設定、工作階段、Gateway、通道與
-  疑難排解，請參閱主要[常見問題](/zh-TW/help/faq)。
+  模型與認證設定檔問答。如需設定、工作階段、Gateway、頻道與
+  疑難排解，請參閱主要 [FAQ](/zh-TW/help/faq)。
 
-  ## 模型：預設值、選擇、別名、切換
+  ## 模型：預設值、選取、別名、切換
 
   <AccordionGroup>
   <Accordion title='什麼是「預設模型」？'>
@@ -28,79 +28,80 @@ x-i18n:
     agents.defaults.model.primary
     ```
 
-    模型會以 `provider/model` 參照（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供者，OpenClaw 會先嘗試別名，接著尋找該確切模型 ID 在已設定提供者中的唯一相符項目，最後才會退回到已設定的預設提供者，這是一條已棄用的相容路徑。如果該提供者不再公開已設定的預設模型，OpenClaw 會退回到第一個已設定的提供者/模型，而不是顯示過時且已移除提供者的預設值。你仍應該**明確**設定 `provider/model`。
+    模型以 `provider/model` 參照（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供者，OpenClaw 會先嘗試別名，接著嘗試該精確模型 ID 的唯一已設定提供者相符項，最後才會退回到已設定的預設提供者，作為已淘汰的相容路徑。如果該提供者不再公開已設定的預設模型，OpenClaw 會退回到第一個已設定的提供者/模型，而不是顯示過時且已移除提供者的預設值。你仍應**明確**設定 `provider/model`。
 
   </Accordion>
 
   <Accordion title="你推薦哪個模型？">
     **建議預設值：**使用你的提供者堆疊中可用的最強最新世代模型。
     **對於啟用工具或不受信任輸入的代理：**優先考量模型能力，而不是成本。
-    **對於例行/低風險聊天：**使用較便宜的備援模型，並依代理角色路由。
+    **對於例行/低風險聊天：**使用較便宜的備用模型，並依代理角色路由。
 
     MiniMax 有自己的文件：[MiniMax](/zh-TW/providers/minimax) 和
     [本機模型](/zh-TW/gateway/local-models)。
 
-    經驗法則：高風險工作使用**你負擔得起的最佳模型**，例行聊天或摘要則使用較便宜的
-    模型。你可以依代理路由模型，並使用子代理平行處理長任務（每個子代理都會消耗 token）。請參閱[模型](/zh-TW/concepts/models)和
+    經驗法則：高風險工作使用你**負擔得起的最佳模型**，例行聊天或摘要則使用較便宜的
+    模型。你可以依代理路由模型，並使用子代理來
+    平行處理長任務（每個子代理都會消耗權杖）。請參閱 [模型](/zh-TW/concepts/models) 和
     [子代理](/zh-TW/tools/subagents)。
 
-    強烈警告：較弱或過度量化的模型更容易受到提示
-    注入與不安全行為影響。請參閱[安全性](/zh-TW/gateway/security)。
+    強烈警告：較弱/過度量化的模型更容易受到提示詞
+    注入與不安全行為影響。請參閱 [安全性](/zh-TW/gateway/security)。
 
     更多背景：[模型](/zh-TW/concepts/models)。
 
   </Accordion>
 
   <Accordion title="如何在不清除設定的情況下切換模型？">
-    使用**模型命令**，或只編輯**模型**欄位。避免完整替換設定。
+    使用**模型命令**，或只編輯**模型**欄位。避免完整取代設定。
 
     安全選項：
 
-    - 聊天中的 `/model`（快速、針對每個工作階段）
+    - 聊天中的 `/model`（快速、每個工作階段）
     - `openclaw models set ...`（只更新模型設定）
     - `openclaw configure --section model`（互動式）
     - 編輯 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model`
 
-    除非你打算替換整份設定，否則避免將部分物件用於 `config.apply`。
-    對於 RPC 編輯，先使用 `config.schema.lookup` 檢查，並優先使用 `config.patch`。lookup payload 會提供正規化路徑、淺層 schema 文件/限制，以及直接子項摘要。
+    避免對部分物件使用 `config.apply`，除非你打算取代整個設定。
+    對於 RPC 編輯，請先使用 `config.schema.lookup` 檢查，並優先使用 `config.patch`。lookup 承載會提供正規化路徑、淺層 schema 文件/限制，以及直接子項摘要。
     用於部分更新。
-    如果你覆寫了設定，請從備份還原，或重新執行 `openclaw doctor` 來修復。
+    如果你已覆寫設定，請從備份還原，或重新執行 `openclaw doctor` 來修復。
 
     文件：[模型](/zh-TW/concepts/models)、[設定](/zh-TW/cli/configure)、[Config](/zh-TW/cli/config)、[Doctor](/zh-TW/gateway/doctor)。
 
   </Accordion>
 
   <Accordion title="可以使用自架模型（llama.cpp、vLLM、Ollama）嗎？">
-    可以。Ollama 是使用本機模型最簡單的路徑。
+    可以。Ollama 是本機模型最簡單的路徑。
 
-    最快設定方式：
+    最快速設定：
 
     1. 從 `https://ollama.com/download` 安裝 Ollama
     2. 拉取本機模型，例如 `ollama pull gemma4`
-    3. 如果你也想使用雲端模型，執行 `ollama signin`
+    3. 如果也想使用雲端模型，請執行 `ollama signin`
     4. 執行 `openclaw onboard` 並選擇 `Ollama`
     5. 選擇 `Local` 或 `Cloud + Local`
 
     注意事項：
 
     - `Cloud + Local` 會提供雲端模型加上你的本機 Ollama 模型
-    - `kimi-k2.5:cloud` 這類雲端模型不需要本機拉取
-    - 如需手動切換，使用 `openclaw models list` 和 `openclaw models set ollama/<model>`
+    - `kimi-k2.5:cloud` 等雲端模型不需要本機拉取
+    - 若要手動切換，請使用 `openclaw models list` 和 `openclaw models set ollama/<model>`
 
-    安全性注意事項：較小或高度量化的模型更容易受到提示
-    注入影響。對於任何可以使用工具的機器人，我們強烈建議使用**大型模型**。
-    如果你仍想使用小型模型，請啟用沙盒化與嚴格的工具允許清單。
+    安全性注意事項：較小或大量量化的模型更容易受到提示詞
+    注入影響。我們強烈建議任何可使用工具的機器人都使用**大型模型**。
+    如果你仍想使用小型模型，請啟用沙箱與嚴格的工具允許清單。
 
     文件：[Ollama](/zh-TW/providers/ollama)、[本機模型](/zh-TW/gateway/local-models)、
     [模型提供者](/zh-TW/concepts/model-providers)、[安全性](/zh-TW/gateway/security)、
-    [沙盒化](/zh-TW/gateway/sandboxing)。
+    [沙箱](/zh-TW/gateway/sandboxing)。
 
   </Accordion>
 
   <Accordion title="OpenClaw、Flawd 和 Krill 使用哪些模型？">
     - 這些部署可能不同，且可能隨時間變更；沒有固定的提供者建議。
     - 使用 `openclaw models status` 檢查每個 Gateway 上目前的執行階段設定。
-    - 對於安全性敏感/啟用工具的代理，使用可用的最強最新世代模型。
+    - 對於安全性敏感/啟用工具的代理，請使用可用的最強最新世代模型。
 
   </Accordion>
 
@@ -121,21 +122,21 @@ x-i18n:
 
     你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。
 
-    `/model`（以及 `/model list`）會顯示精簡的編號選擇器。依編號選擇：
+    `/model`（和 `/model list`）會顯示精簡的編號選擇器。依編號選取：
 
     ```
     /model 3
     ```
 
-    你也可以強制該提供者使用特定驗證設定檔（針對每個工作階段）：
+    你也可以強制為提供者使用特定認證設定檔（每個工作階段）：
 
     ```
     /model opus@anthropic:default
     /model opus@anthropic:work
     ```
 
-    提示：`/model status` 會顯示哪個代理處於作用中、正在使用哪個 `auth-profiles.json` 檔案，以及接下來會嘗試哪個驗證設定檔。
-    可用時，它也會顯示已設定的提供者端點 (`baseUrl`) 與 API 模式 (`api`)。
+    提示：`/model status` 會顯示目前作用中的代理、正在使用哪個 `auth-profiles.json` 檔案，以及接下來會嘗試哪個認證設定檔。
+    可用時，它也會顯示已設定的提供者端點 (`baseUrl`) 和 API 模式 (`api`)。
 
     **如何取消固定我用 @profile 設定的設定檔？**
 
@@ -145,27 +146,27 @@ x-i18n:
     /model anthropic/claude-opus-4-6
     ```
 
-    如果你想回到預設值，請從 `/model` 選擇它（或傳送 `/model <default provider/model>`）。
-    使用 `/model status` 確認哪個驗證設定檔處於作用中。
+    如果想回到預設值，請從 `/model` 中選擇它（或傳送 `/model <default provider/model>`）。
+    使用 `/model status` 確認目前作用中的認證設定檔。
 
   </Accordion>
 
-  <Accordion title="我可以日常任務使用 GPT 5.5，寫程式使用 Codex 5.5 嗎？">
-    可以。將模型選擇與執行階段選擇分開處理：
+  <Accordion title="可以日常任務使用 GPT 5.5、寫程式使用 Codex 5.5 嗎？">
+    可以。請將模型選擇和執行階段選擇分開處理：
 
-    - **原生 Codex 程式撰寫代理：**將 `agents.defaults.model.primary` 設為 `openai/gpt-5.5`，並將 `agents.defaults.agentRuntime.id` 設為 `"codex"`。當你想使用 ChatGPT/Codex 訂閱驗證時，使用 `openclaw models auth login --provider openai-codex` 登入。
-    - **透過 PI 執行的直接 OpenAI API 任務：**使用 `/model openai/gpt-5.5`，不使用 Codex 執行階段覆寫，並設定 `OPENAI_API_KEY`。
-    - **透過 PI 使用 Codex OAuth：**只有在你刻意要使用一般 PI runner 搭配 Codex OAuth 時，才使用 `/model openai-codex/gpt-5.5`。
-    - **子代理：**將程式撰寫任務路由到只使用 Codex 的代理，並為其設定自己的模型和 `agentRuntime` 預設值。
+    - **原生 Codex 程式設計代理：**將 `agents.defaults.model.primary` 設為 `openai/gpt-5.5`，並將 `agents.defaults.agentRuntime.id` 設為 `"codex"`。當你想使用 ChatGPT/Codex 訂閱認證時，請用 `openclaw models auth login --provider openai-codex` 登入。
+    - **透過 PI 的直接 OpenAI API 任務：**使用 `/model openai/gpt-5.5`，不要覆寫 Codex 執行階段，並設定 `OPENAI_API_KEY`。
+    - **透過 PI 的 Codex OAuth：**只有在你刻意想以 Codex OAuth 使用一般 PI 執行器時，才使用 `/model openai-codex/gpt-5.5`。
+    - **子代理：**將程式設計任務路由到只有 Codex 的代理，並使用它自己的模型與 `agentRuntime` 預設值。
 
-    請參閱[模型](/zh-TW/concepts/models)和[斜線命令](/zh-TW/tools/slash-commands)。
+    請參閱 [模型](/zh-TW/concepts/models) 和 [斜線命令](/zh-TW/tools/slash-commands)。
 
   </Accordion>
 
   <Accordion title="如何為 GPT 5.5 設定快速模式？">
     使用工作階段切換或設定預設值：
 
-    - **每個工作階段：**當工作階段使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 時，傳送 `/fast on`。
+    - **每個工作階段：**在工作階段使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 時傳送 `/fast on`。
     - **每個模型預設值：**將 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 或 `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` 設為 `true`。
 
     範例：
@@ -186,39 +187,41 @@ x-i18n:
     }
     ```
 
-    對 OpenAI 而言，在支援的原生 Responses 請求上，快速模式會對應到 `service_tier = "priority"`。工作階段 `/fast` 覆寫的優先順序高於設定預設值。
+    對 OpenAI 而言，快速模式會對應到受支援原生 Responses 請求上的 `service_tier = "priority"`。工作階段 `/fast` 覆寫會優先於設定預設值。
 
-    請參閱[思考與快速模式](/zh-TW/tools/thinking)以及 [OpenAI 快速模式](/zh-TW/providers/openai#fast-mode)。
+    請參閱 [思考與快速模式](/zh-TW/tools/thinking) 和 [OpenAI 快速模式](/zh-TW/providers/openai#fast-mode)。
 
   </Accordion>
 
-  <Accordion title='為什麼我看到「Model ... is not allowed」然後沒有回覆？'>
-    如果設定了 `agents.defaults.models`，它會成為 `/model` 和任何
+  <Accordion title='為什麼我會看到「Model ... is not allowed」，然後沒有回覆？'>
+    如果設定了 `agents.defaults.models`，它就會成為 `/model` 和任何
     工作階段覆寫的**允許清單**。選擇不在該清單中的模型會回傳：
 
     ```
-    Model "provider/model" is not allowed. Use /model to list available models.
+    Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
+    Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
     ```
 
-    該錯誤會**取代**一般回覆。修正方式：將模型新增到
+    該錯誤會被回傳來**取代**一般回覆。修正方式：將模型新增到
     `agents.defaults.models`、移除允許清單，或從 `/model list` 選擇模型。
+    如果命令也包含 `--runtime codex`，請先新增模型，然後重試相同的
+    `/model provider/model --runtime codex` 命令。
 
   </Accordion>
 
-  <Accordion title='為什麼我看到「Unknown model: minimax/MiniMax-M2.7」？'>
-    這表示**提供者尚未設定**（找不到 MiniMax 提供者設定或驗證
+  <Accordion title='為什麼我會看到「Unknown model: minimax/MiniMax-M2.7」？'>
+    這表示**尚未設定提供者**（找不到 MiniMax 提供者設定或認證
     設定檔），因此無法解析模型。
 
     修正檢查清單：
 
     1. 升級到目前的 OpenClaw 版本（或從原始碼 `main` 執行），然後重新啟動 Gateway。
-    2. 確認 MiniMax 已設定（精靈或 JSON），或確認 env/驗證設定檔中存在 MiniMax 驗證資訊，
-       讓相符的提供者可以被注入
+    2. 確認已設定 MiniMax（精靈或 JSON），或 env/認證設定檔中存在 MiniMax 認證，
+       讓相符提供者可被注入
        （`MINIMAX_API_KEY` 用於 `minimax`，`MINIMAX_OAUTH_TOKEN` 或已儲存的 MiniMax
        OAuth 用於 `minimax-portal`）。
-    3. 依你的驗證路徑使用確切模型 ID（區分大小寫）：
-       API key 設定使用
-       `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`，
+    3. 針對你的認證路徑使用精確模型 ID（區分大小寫）：
+       API 金鑰設定使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`，
        OAuth 設定使用 `minimax-portal/MiniMax-M2.7` /
        `minimax-portal/MiniMax-M2.7-highspeed`。
     4. 執行：
@@ -229,13 +232,13 @@ x-i18n:
 
        並從清單中選擇（或在聊天中使用 `/model list`）。
 
-    請參閱 [MiniMax](/zh-TW/providers/minimax) 和[模型](/zh-TW/concepts/models)。
+    請參閱 [MiniMax](/zh-TW/providers/minimax) 和 [模型](/zh-TW/concepts/models)。
 
   </Accordion>
 
-  <Accordion title="我可以將 MiniMax 作為預設，並在複雜任務使用 OpenAI 嗎？">
-    可以。將 **MiniMax 作為預設值**，並在需要時**依工作階段**切換模型。
-    備援是用於**錯誤**，不是用於「困難任務」，因此請使用 `/model` 或另一個代理。
+  <Accordion title="可以將 MiniMax 作為預設，並將 OpenAI 用於複雜任務嗎？">
+    可以。使用 **MiniMax 作為預設值**，並在需要時**依工作階段**切換模型。
+    備援是用於**錯誤**，不是「困難任務」，因此請使用 `/model` 或另一個代理。
 
     **選項 A：依工作階段切換**
 
@@ -262,8 +265,8 @@ x-i18n:
 
     **選項 B：分開的代理**
 
-    - 代理 A 預設值：MiniMax
-    - 代理 B 預設值：OpenAI
+    - 代理 A 預設：MiniMax
+    - 代理 B 預設：OpenAI
     - 依代理路由，或使用 `/agent` 切換
 
     文件：[模型](/zh-TW/concepts/models)、[多代理路由](/zh-TW/concepts/multi-agent)、[MiniMax](/zh-TW/providers/minimax)、[OpenAI](/zh-TW/providers/openai)。
@@ -271,18 +274,18 @@ x-i18n:
   </Accordion>
 
   <Accordion title="opus / sonnet / gpt 是內建捷徑嗎？">
-    是。OpenClaw 內建一些預設簡寫（只有在模型存在於 `agents.defaults.models` 時才會套用）：
+    是。OpenClaw 隨附一些預設簡寫（只有在模型存在於 `agents.defaults.models` 時才會套用）：
 
     - `opus` → `anthropic/claude-opus-4-6`
     - `sonnet` → `anthropic/claude-sonnet-4-6`
-    - `gpt` → API key 設定使用 `openai/gpt-5.5`，或在設定為 Codex OAuth 時使用 `openai-codex/gpt-5.5`
+    - `gpt` → `openai/gpt-5.5`（API 金鑰設定），或設定為 Codex OAuth 時的 `openai-codex/gpt-5.5`
     - `gpt-mini` → `openai/gpt-5.4-mini`
     - `gpt-nano` → `openai/gpt-5.4-nano`
     - `gemini` → `google/gemini-3.1-pro-preview`
     - `gemini-flash` → `google/gemini-3-flash-preview`
     - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
 
-    如果你使用相同名稱設定自己的別名，會以你的值為準。
+    如果你用相同名稱設定自己的別名，會以你的值為準。
 
   </Accordion>
 
@@ -304,12 +307,12 @@ x-i18n:
     }
     ```
 
-    接著 `/model sonnet`（或在支援時使用 `/<alias>`）會解析到該模型 ID。
+    然後 `/model sonnet`（或支援時的 `/<alias>`）會解析為該模型 ID。
 
   </Accordion>
 
-  <Accordion title="如何新增來自 OpenRouter 或 Z.AI 等其他提供者的模型？">
-    OpenRouter（按 token 付費；多種模型）：
+  <Accordion title="如何新增其他提供者的模型，例如 OpenRouter 或 Z.AI？">
+    OpenRouter（按權杖付費；多種模型）：
 
     ```json5
     {
@@ -337,11 +340,11 @@ x-i18n:
     }
     ```
 
-    如果你參照了供應商/模型，但缺少必要的供應商金鑰，會收到執行階段驗證錯誤（例如 `No API key found for provider "zai"`）。
+    如果你參照了提供者/模型，但缺少必要的提供者金鑰，你會收到執行階段驗證錯誤（例如 `No API key found for provider "zai"`）。
 
-    **新增代理程式後找不到供應商的 API 金鑰**
+    **新增代理程式後找不到提供者的 API 金鑰**
 
-    這通常表示**新代理程式**有一個空的驗證儲存區。驗證是依代理程式分開的，並儲存在：
+    這通常表示**新的代理程式**有一個空的驗證存放區。驗證是以每個代理程式為單位，並儲存在：
 
     ```
     ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
@@ -350,10 +353,10 @@ x-i18n:
     修正選項：
 
     - 執行 `openclaw agents add <id>`，並在精靈中設定驗證。
-    - 或者只將可攜式靜態 `api_key` / `token` 設定檔，從主要代理程式的驗證儲存區複製到新代理程式的驗證儲存區。
-    - 對於 OAuth 設定檔，當新代理程式需要自己的帳號時，請從新代理程式登入；否則 OpenClaw 可以讀取預設/主要代理程式，而不需要複製重新整理權杖。
+    - 或者只將可攜式靜態 `api_key` / `token` 設定檔，從主要代理程式的驗證存放區複製到新代理程式的驗證存放區。
+    - 對於 OAuth 設定檔，當新的代理程式需要自己的帳戶時，請從該新代理程式登入；否則 OpenClaw 可以讀取預設/主要代理程式，而不需要複製重新整理權杖。
 
-    請**不要**在代理程式之間重複使用 `agentDir`；這會造成驗證/工作階段衝突。
+    請**不要**在多個代理程式之間重複使用 `agentDir`；這會造成驗證/工作階段衝突。
 
   </Accordion>
 </AccordionGroup>
@@ -362,145 +365,147 @@ x-i18n:
 
 <AccordionGroup>
   <Accordion title="容錯移轉如何運作？">
-    容錯移轉分成兩個階段：
+    容錯移轉分兩個階段進行：
 
-    1. 同一供應商內的**驗證設定檔輪替**。
+    1. 在同一個提供者內進行**驗證設定檔輪替**。
     2. **模型備援**到 `agents.defaults.model.fallbacks` 中的下一個模型。
 
-    冷卻時間會套用到失敗的設定檔（指數退避），因此即使供應商受到速率限制或暫時失敗，OpenClaw 仍可持續回應。
+    冷卻時間會套用到失敗的設定檔（指數退避），因此即使某個提供者受到速率限制或暫時失敗，OpenClaw 仍可繼續回應。
 
-    速率限制的分類不只包含一般的 `429` 回應。OpenClaw
+    速率限制桶不只包含單純的 `429` 回應。OpenClaw
     也會將 `Too many concurrent requests`、
     `ThrottlingException`、`concurrency limit reached`、
     `workers_ai ... quota limit exceeded`、`resource exhausted`，以及週期性
-    使用量視窗限制（`weekly/monthly limit reached`）等訊息視為值得進行容錯移轉的
+    使用視窗限制（`weekly/monthly limit reached`）等訊息視為值得觸發容錯移轉的
     速率限制。
 
-    有些看起來像帳單問題的回應不是 `402`，有些 HTTP `402`
-    回應也會留在暫時性分類中。如果供應商在 `401` 或 `403` 上回傳
-    明確的帳單文字，OpenClaw 仍可將它保留在
-    帳單通道中，但供應商特定的文字比對器會限制在
-    擁有它們的供應商範圍內（例如 OpenRouter 的 `Key limit exceeded`）。如果 `402`
-    訊息反而看起來像可重試的使用量視窗或
-    組織/工作區支出限制（`daily limit reached, resets tomorrow`、
-    `organization spending limit exceeded`），OpenClaw 會將它視為
-    `rate_limit`，而不是長時間的帳單停用。
+    有些看起來像計費的回應並不是 `402`，而且有些 HTTP `402`
+    回應也會留在該暫時性桶中。如果提供者在 `401` 或 `403` 上回傳
+    明確的計費文字，OpenClaw 仍可將其保留在
+    計費分類中，但提供者特定的文字比對器會限定在擁有它們的
+    提供者範圍內（例如 OpenRouter `Key limit exceeded`）。如果 `402`
+    訊息反而看起來像可重試的使用視窗，或
+    組織/工作區花費限制（`daily limit reached, resets tomorrow`、
+    `organization spending limit exceeded`），OpenClaw 會將其視為
+    `rate_limit`，而不是長時間的計費停用。
 
     上下文溢位錯誤則不同：像是
     `request_too_large`、`input exceeds the maximum number of tokens`、
     `input token count exceeds the maximum number of input tokens`、
     `input is too long for the model`，或 `ollama error: context length
-    exceeded` 這類特徵，會留在 Compaction/重試路徑上，而不是推進模型
+    exceeded` 這類特徵，會留在 Compaction/重試路徑，而不是推進模型
     備援。
 
-    一般伺服器錯誤文字刻意比「任何包含
-    unknown/error 的內容」更窄。OpenClaw 確實會在供應商上下文
-    相符時，將供應商範圍的暫時性形狀視為值得容錯移轉的逾時/過載訊號，
-    例如 Anthropic 裸露的 `An unknown error occurred`、OpenRouter 裸露的
+    一般伺服器錯誤文字有意比「任何包含
+    unknown/error 的內容」更窄。OpenClaw 確實會將提供者範圍內的暫時性形態
+    視為值得容錯移轉的逾時/過載訊號，例如 Anthropic 裸露的 `An unknown error occurred`、OpenRouter 裸露的
     `Provider returned error`、像 `Unhandled stop reason:
     error` 這樣的停止原因錯誤、帶有暫時性伺服器文字的 JSON `api_error` 酬載
     （`internal server error`、`unknown error, 520`、`upstream error`、`backend
-    error`），以及像 `ModelNotReadyException` 這樣的供應商忙碌錯誤。
+    error`），以及像 `ModelNotReadyException` 這樣的提供者忙碌錯誤，但前提是提供者上下文
+    相符。
     像 `LLM request failed with an unknown
-    error.` 這類一般內部備援文字會保持保守，本身不會觸發模型備援。
+    error.` 這樣的一般內部備援文字會保持保守，本身不會觸發模型備援。
 
   </Accordion>
 
   <Accordion title='「No credentials found for profile anthropic:default」是什麼意思？'>
-    這表示系統嘗試使用驗證設定檔 ID `anthropic:default`，但無法在預期的驗證儲存區中找到它的憑證。
+    這表示系統嘗試使用驗證設定檔 ID `anthropic:default`，但無法在預期的驗證存放區中找到其憑證。
 
     **修正檢查清單：**
 
-    - **確認驗證設定檔所在位置**（新路徑與舊路徑）
+    - **確認驗證設定檔的位置**（新路徑與舊路徑）
       - 目前：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
       - 舊版：`~/.openclaw/agent/*`（由 `openclaw doctor` 遷移）
     - **確認你的環境變數已由 Gateway 載入**
-      - 如果你在 shell 中設定 `ANTHROPIC_API_KEY`，但透過 systemd/launchd 執行 Gateway，它可能不會繼承該變數。請將它放入 `~/.openclaw/.env`，或啟用 `env.shellEnv`。
+      - 如果你在 shell 中設定 `ANTHROPIC_API_KEY`，但透過 systemd/launchd 執行 Gateway，它可能不會繼承該變數。請將它放在 `~/.openclaw/.env`，或啟用 `env.shellEnv`。
     - **確認你正在編輯正確的代理程式**
-      - 多代理程式設定代表可能會有多個 `auth-profiles.json` 檔案。
-    - **對模型/驗證狀態進行基本檢查**
-      - 使用 `openclaw models status` 查看已設定的模型，以及供應商是否已通過驗證。
+      - 多代理程式設定表示可能會有多個 `auth-profiles.json` 檔案。
+    - **基本檢查模型/驗證狀態**
+      - 使用 `openclaw models status` 查看已設定的模型，以及提供者是否已通過驗證。
 
     **「No credentials found for profile anthropic」的修正檢查清單**
 
-    這表示該次執行被固定到 Anthropic 驗證設定檔，但 Gateway
-    在其驗證儲存區中找不到它。
+    這表示執行被固定到某個 Anthropic 驗證設定檔，但 Gateway
+    無法在其驗證存放區中找到該設定檔。
 
     - **使用 Claude CLI**
       - 在 Gateway 主機上執行 `openclaw models auth login --provider anthropic --method cli --set-default`。
     - **如果你想改用 API 金鑰**
-      - 在 **Gateway 主機**上的 `~/.openclaw/.env` 中放入 `ANTHROPIC_API_KEY`。
-      - 清除任何會強制使用缺失設定檔的固定順序：
+      - 將 `ANTHROPIC_API_KEY` 放在 **Gateway 主機**上的 `~/.openclaw/.env`。
+      - 清除任何強制使用缺失設定檔的固定順序：
 
         ```bash
         openclaw models auth order clear --provider anthropic
         ```
 
     - **確認你是在 Gateway 主機上執行命令**
-      - 在遠端模式下，驗證設定檔位於 Gateway 機器上，而不是你的筆電上。
+      - 在遠端模式中，驗證設定檔位於 Gateway 機器上，而不是你的筆記型電腦上。
 
   </Accordion>
 
-  <Accordion title="為什麼它也嘗試了 Google Gemini 並失敗？">
-    如果你的模型設定包含 Google Gemini 作為備援（或你切換到 Gemini 簡寫），OpenClaw 會在模型備援期間嘗試它。如果你尚未設定 Google 憑證，就會看到 `No API key found for provider "google"`。
+  <Accordion title="為什麼它也嘗試 Google Gemini 並失敗？">
+    如果你的模型設定包含 Google Gemini 作為備援（或你切換到 Gemini 簡寫），OpenClaw 會在模型備援期間嘗試它。如果你尚未設定 Google 憑證，你會看到 `No API key found for provider "google"`。
 
-    修正方式：提供 Google 驗證，或在 `agents.defaults.model.fallbacks` / 別名中移除/避免使用 Google 模型，讓備援不會路由到那裡。
+    修正方式：提供 Google 驗證，或從 `agents.defaults.model.fallbacks` / 別名中移除/避免使用 Google 模型，這樣備援就不會路由到那裡。
 
-    **LLM 請求被拒絕：需要思考簽章（Google Antigravity）**
+    **LLM 要求遭拒：需要 thinking 簽章（Google Antigravity）**
 
-    原因：工作階段歷程包含**沒有簽章的思考區塊**（通常來自
-    已中止/部分的串流）。Google Antigravity 要求思考區塊必須有簽章。
+    原因：工作階段歷程包含**沒有簽章的 thinking 區塊**（通常來自
+    已中止/部分的串流）。Google Antigravity 要求 thinking 區塊必須有簽章。
 
-    修正方式：OpenClaw 現在會為 Google Antigravity Claude 移除未簽章的思考區塊。如果仍然出現，請開始一個**新工作階段**，或為該代理程式設定 `/thinking off`。
+    修正方式：OpenClaw 現在會為 Google Antigravity Claude 移除未簽章的 thinking 區塊。如果它仍然出現，請開始一個**新的工作階段**，或為該代理程式設定 `/thinking off`。
 
   </Accordion>
 </AccordionGroup>
 
-## 驗證設定檔：它們是什麼以及如何管理
+## 驗證設定檔：它們是什麼，以及如何管理
 
-相關：[/concepts/oauth](/zh-TW/concepts/oauth)（OAuth 流程、權杖儲存、多帳號模式）
+相關：[/concepts/oauth](/zh-TW/concepts/oauth)（OAuth 流程、權杖儲存、多帳戶模式）
 
 <AccordionGroup>
   <Accordion title="什麼是驗證設定檔？">
-    驗證設定檔是綁定至供應商的具名憑證記錄（OAuth 或 API 金鑰）。設定檔位於：
+    驗證設定檔是繫結到提供者的具名憑證記錄（OAuth 或 API 金鑰）。設定檔位於：
 
     ```
     ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
     ```
 
+    若要在不傾印祕密的情況下檢查已儲存的設定檔，請執行 `openclaw models auth list`（可選擇加上 `--provider <id>` 或 `--json`）。詳情請參閱[模型 CLI](/zh-TW/cli/models#openclaw-models-auth-list)。
+
   </Accordion>
 
   <Accordion title="常見的設定檔 ID 有哪些？">
-    OpenClaw 使用帶有供應商前綴的 ID，例如：
+    OpenClaw 使用帶有提供者前綴的 ID，例如：
 
-    - `anthropic:default`（沒有電子郵件身分時很常見）
+    - `anthropic:default`（沒有電子郵件身分時常見）
     - OAuth 身分使用 `anthropic:<email>`
     - 你選擇的自訂 ID（例如 `anthropic:work`）
 
   </Accordion>
 
   <Accordion title="我可以控制先嘗試哪個驗證設定檔嗎？">
-    可以。設定支援設定檔的選用中繼資料，以及每個供應商的排序（`auth.order.<provider>`）。這**不會**儲存祕密；它會將 ID 對應到供應商/模式，並設定輪替順序。
+    可以。設定支援設定檔的選用中繼資料，以及每個提供者的排序（`auth.order.<provider>`）。這**不會**儲存祕密；它會將 ID 對應到提供者/模式，並設定輪替順序。
 
-    如果設定檔處於短暫**冷卻**（速率限制/逾時/驗證失敗）或較長的**停用**狀態（帳單/點數不足），OpenClaw 可能會暫時略過該設定檔。若要檢查這項狀態，請執行 `openclaw models status --json` 並查看 `auth.unusableProfiles`。調校：`auth.cooldowns.billingBackoffHours*`。
+    如果某個設定檔處於短暫**冷卻**（速率限制/逾時/驗證失敗）或較長的**停用**狀態（計費/點數不足），OpenClaw 可能會暫時略過該設定檔。若要檢查這點，請執行 `openclaw models status --json` 並查看 `auth.unusableProfiles`。調整項：`auth.cooldowns.billingBackoffHours*`。
 
-    速率限制冷卻可以限定於模型。某個設定檔如果正在為
-    一個模型冷卻，仍可能可用於同一供應商上的同層模型，
-    而帳單/停用視窗仍會封鎖整個設定檔。
+    速率限制冷卻可以是模型範圍的。對某個模型正在冷卻的設定檔，
+    對同一提供者上的同層模型仍可能可用，
+    而計費/停用視窗仍會封鎖整個設定檔。
 
-    你也可以透過 CLI 設定**每個代理程式**的順序覆寫（儲存在該代理程式的 `auth-state.json`）：
+    你也可以透過 CLI 設定**每個代理程式**的順序覆寫（儲存在該代理程式的 `auth-state.json` 中）：
 
     ```bash
-    # Defaults to the configured default agent (omit --agent)
+    # 預設為已設定的預設代理程式（省略 --agent）
     openclaw models auth order get --provider anthropic
 
-    # Lock rotation to a single profile (only try this one)
+    # 將輪替鎖定到單一設定檔（只嘗試這一個）
     openclaw models auth order set --provider anthropic anthropic:default
 
-    # Or set an explicit order (fallback within provider)
+    # 或設定明確順序（提供者內備援）
     openclaw models auth order set --provider anthropic anthropic:work anthropic:default
 
-    # Clear override (fall back to config auth.order / round-robin)
+    # 清除覆寫（回退到 config auth.order / round-robin）
     openclaw models auth order clear --provider anthropic
     ```
 
@@ -510,22 +515,22 @@ x-i18n:
     openclaw models auth order set --provider anthropic --agent main anthropic:default
     ```
 
-    若要驗證實際會嘗試的內容，請使用：
+    若要驗證實際會嘗試哪些項目，請使用：
 
     ```bash
     openclaw models status --probe
     ```
 
-    如果儲存的設定檔被省略於明確順序之外，probe 會對該設定檔回報
-    `excluded_by_auth_order`，而不是默默嘗試它。
+    如果明確順序中省略了已儲存的設定檔，探測會為該設定檔回報
+    `excluded_by_auth_order`，而不是靜默嘗試它。
 
   </Accordion>
 
   <Accordion title="OAuth 與 API 金鑰有什麼差異？">
-    OpenClaw 兩者都支援：
+    OpenClaw 同時支援兩者：
 
-    - **OAuth** 通常會運用訂閱存取權限（適用時）。
-    - **API 金鑰** 使用按權杖計費。
+    - **OAuth** 通常會利用訂閱存取權（適用時）。
+    - **API 金鑰**使用按權杖付費的計費方式。
 
     精靈明確支援 Anthropic Claude CLI、OpenAI Codex OAuth，以及 API 金鑰。
 
@@ -534,7 +539,7 @@ x-i18n:
 
 ## 相關
 
-- [常見問題](/zh-TW/help/faq) — 主要常見問題
-- [常見問題 — 快速開始與首次執行設定](/zh-TW/help/faq-first-run)
+- [FAQ](/zh-TW/help/faq) — 主要 FAQ
+- [FAQ — 快速開始與首次執行設定](/zh-TW/help/faq-first-run)
 - [模型選擇](/zh-TW/concepts/model-providers)
 - [模型容錯移轉](/zh-TW/concepts/model-failover)

docs/zh-TW/help/testing-updates-plugins.md

@@ -1,38 +1,50 @@
 ---
 read_when:
-    - 變更 OpenClaw 更新、診斷、套件驗收或 Plugin 安裝行為
+    - 變更 OpenClaw 更新、doctor、套件驗收或 Plugin 安裝行為
     - 準備或核准發行候選版本
-    - 偵錯套件更新、Plugin 依賴項清理或 Plugin 安裝回歸
+    - 套件更新、Plugin 相依性清理或 Plugin 安裝回歸的偵錯
 sidebarTitle: Update and plugin tests
-summary: OpenClaw 如何驗證更新路徑、套件遷移與 Plugin 安裝／更新行為
+summary: OpenClaw 如何驗證更新路徑、套件移轉，以及 Plugin 安裝/更新行為
 title: 測試：更新與 Plugin
 x-i18n:
-    generated_at: "2026-05-03T21:35:56Z"
+    generated_at: "2026-05-05T01:47:34Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd
+    source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286
     source_path: help/testing-updates-plugins.md
     workflow: 16
 ---
 
-這是更新和 Plugin 驗證的專用檢查清單。目標很簡單：證明可安裝套件能更新真實使用者狀態、透過 `doctor` 修復過時的舊版狀態，並且仍能從支援的來源安裝、載入、更新與解除安裝 Plugin。
+這是專用於更新與 Plugin 驗證的檢查清單。目標很
+簡單：證明可安裝套件能更新真實使用者狀態、透過 `doctor` 修復過時的
+舊版狀態，並且仍能從支援的來源安裝、載入、更新與解除安裝
+Plugin。
 
-如需更完整的測試執行器對照圖，請參閱[測試](/zh-TW/help/testing)。如需即時 provider 金鑰與會觸及網路的測試套件，請參閱[即時測試](/zh-TW/help/testing-live)。
+如需更完整的測試執行器對照，請參閱[測試](/zh-TW/help/testing)。如需即時供應商
+金鑰與會觸及網路的測試套件，請參閱[即時測試](/zh-TW/help/testing-live)。
 
 ## 我們保護的內容
 
 更新與 Plugin 測試保護下列契約：
 
-- 套件 tarball 是完整的，具有有效的 `dist/postinstall-inventory.json`，且不依賴未封裝的 repo 檔案。
-- 使用者可以從較舊的已發佈套件移轉到候選套件，而不遺失設定、agent、session、workspace、Plugin allowlist 或 channel 設定。
-- `openclaw doctor --fix --non-interactive` 負責舊版清理與修復路徑。啟動流程不應為過時的 Plugin 狀態增加隱藏的相容性 migration。
-- Plugin 可從本機目錄、git repo、npm 套件，以及 ClawHub registry 路徑安裝。
-- Plugin npm 相依套件會安裝在受管理的 npm root 中，在信任前被掃描，並在解除安裝期間透過 npm 移除，使 hoisted 相依套件不會殘留。
-- 當沒有變更時，Plugin 更新是穩定的：安裝記錄、解析後來源、已安裝相依套件版面，以及啟用狀態都保持完整。
+- 套件 tarball 是完整的，具備有效的 `dist/postinstall-inventory.json`，
+  且不依賴未封裝的儲存庫檔案。
+- 使用者可以從較舊的已發佈套件移轉到候選套件，而不遺失設定、代理、工作階段、工作區、Plugin 允許清單或
+  頻道設定。
+- `openclaw doctor --fix --non-interactive` 負責舊版清理與修復
+  路徑。啟動流程不應為過時的
+  Plugin 狀態增加隱藏的相容性遷移。
+- Plugin 安裝可從本機目錄、git 儲存庫、npm 套件與
+  ClawHub 登錄路徑運作。
+- Plugin npm 相依套件會安裝在受管理的 npm 根目錄中，在信任前接受掃描，
+  並在解除安裝期間透過 npm 移除，因此被提升的相依套件不會
+  殘留。
+- 當沒有任何變更時，Plugin 更新應保持穩定：安裝記錄、解析後的
+  來源、已安裝的相依套件配置與啟用狀態都維持不變。
 
 ## 開發期間的本機證明
 
-從窄範圍開始：
+從狹窄範圍開始：
 
 ```bash
 pnpm changed:lanes --json
@@ -40,25 +52,31 @@ pnpm check:changed
 pnpm test:changed
 ```
 
-對於 Plugin 安裝、解除安裝、相依套件或套件 inventory 變更，也請執行涵蓋已編輯接縫的聚焦測試：
+若有 Plugin 安裝、解除安裝、相依套件或套件清單變更，也請
+執行涵蓋已編輯銜接面的聚焦測試：
 
 ```bash
 pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
 ```
 
-在任何套件 Docker lane 消耗 tarball 之前，先證明套件 artifact：
+在任何套件 Docker 跑道取用 tarball 前，先證明套件產物：
 
 ```bash
 pnpm release:check
 ```
 
-`release:check` 會執行設定/docs/API drift 檢查、寫入套件 dist inventory、執行 `npm pack --dry-run`、拒絕禁止封裝的檔案、將 tarball 安裝到暫存 prefix、執行 postinstall，並 smoke bundled channel entrypoint。
+`release:check` 會執行設定/文件/API 漂移檢查、寫入套件 dist
+清單、執行 `npm pack --dry-run`、拒絕被禁止的封裝檔案、將
+tarball 安裝到臨時前置目錄、執行 postinstall，並對內建頻道
+進入點做 smoke 測試。
 
-## Docker lane
+## Docker 跑道
 
-Docker lane 是產品層級的證明。它們會在 Linux container 內安裝或更新真實套件，並透過 CLI 指令、Gateway 啟動、HTTP probe、RPC 狀態與檔案系統狀態來斷言行為。
+Docker 跑道是產品層級的證明。它們會在 Linux 容器內安裝或更新真實
+套件，並透過 CLI 命令、Gateway 啟動、HTTP 探測、RPC 狀態與檔案系統狀態
+斷言行為。
 
-迭代時使用聚焦 lane：
+迭代時使用聚焦跑道：
 
 ```bash
 pnpm test:docker:plugins
@@ -69,14 +87,33 @@ pnpm test:docker:published-upgrade-survivor
 pnpm test:docker:update-migration
 ```
 
-重要 lane：
+重要跑道：
 
-- `test:docker:plugins` 驗證 Plugin 安裝 smoke、本機資料夾安裝、本機資料夾更新略過行為、具有預先安裝相依套件的本機資料夾、`file:` 套件安裝、帶有 CLI 執行的 git 安裝、git moving-ref 更新、具有 hoisted transitive 相依套件的 npm registry 安裝、npm 更新 no-op、本機 ClawHub fixture 安裝與更新 no-op、marketplace 更新行為，以及 Claude bundle 啟用/檢查。設定 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可讓 ClawHub 區塊保持 hermetic/離線。
-- `test:docker:plugin-lifecycle-matrix` 會在裸 container 中安裝候選套件，讓 npm Plugin 依序執行安裝、檢查、停用、啟用、明確升級、明確降級，以及刪除 Plugin 程式碼後的解除安裝。它會記錄每個階段的 RSS 與 CPU 指標。
-- `test:docker:plugin-update` 驗證未變更的已安裝 Plugin 在 `openclaw plugins update` 期間不會重新安裝或遺失安裝 metadata。
-- `test:docker:upgrade-survivor` 會將候選 tarball 安裝到髒的舊使用者 fixture 之上、執行套件更新加上非互動式 doctor，接著啟動 loopback Gateway 並檢查狀態保留。
-- `test:docker:published-upgrade-survivor` 會先安裝已發佈 baseline，透過 baked `openclaw config set` recipe 設定它，將它更新到候選 tarball，執行 doctor，檢查舊版清理，啟動 Gateway，並 probe `/healthz`、`/readyz` 與 RPC 狀態。
-- `test:docker:update-migration` 是著重清理的已發佈更新 lane。它會從已設定的 Discord/Telegram 風格使用者狀態開始，執行 baseline doctor 讓已設定的 Plugin 相依套件有機會具體化，為已設定的 packaged Plugin 植入舊版 Plugin 相依套件殘留物，更新到候選 tarball，並要求更新後 doctor 移除舊版相依套件 root。
+- `test:docker:plugins` 驗證 Plugin 安裝 smoke、本機資料夾安裝、
+  本機資料夾更新跳過行為、含預先安裝相依套件的本機資料夾、`file:` 套件安裝、含 CLI 執行的 git
+  安裝、git 移動參照更新、含被提升遞移
+  相依套件的 npm 登錄安裝、npm 更新無操作、本機 ClawHub fixture 安裝與更新
+  無操作、市集更新行為，以及 Claude-bundle 啟用/檢查。設定
+  `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可讓 ClawHub 區塊保持 hermetic/offline。
+- `test:docker:plugin-lifecycle-matrix` 會在空白
+  容器中安裝候選套件，讓 npm Plugin 依序經過安裝、檢查、停用、啟用、
+  明確升級、明確降級，以及刪除 Plugin
+  程式碼後解除安裝。它會記錄各階段的 RSS 與 CPU 指標。
+- `test:docker:plugin-update` 驗證未變更的已安裝 Plugin
+  不會在 `openclaw plugins update` 期間重新安裝或遺失安裝中繼資料。
+- `test:docker:upgrade-survivor` 會將候選 tarball 安裝到髒污的
+  舊使用者 fixture 上，執行套件更新加上非互動式 doctor，接著啟動
+  loopback Gateway 並檢查狀態保留。
+- `test:docker:published-upgrade-survivor` 會先安裝已發佈基準版本，
+  透過內建的 `openclaw config set` 配方設定它，將其更新到
+  候選 tarball，執行 doctor，檢查舊版清理，啟動 Gateway，並
+  探測 `/healthz`、`/readyz` 與 RPC 狀態。
+- `test:docker:update-migration` 是清理量較重的已發佈更新跑道。它
+  從已設定的 Discord/Telegram 風格使用者狀態開始，執行基準
+  doctor，讓已設定 Plugin 相依套件有機會實體化，為已設定的封裝 Plugin 植入
+  舊版 Plugin 相依套件碎屑，更新到
+  候選 tarball，並要求更新後的 doctor 移除舊版
+  相依套件根目錄。
 
 實用的已發佈升級 survivor 變體：
 
@@ -90,9 +127,15 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
 pnpm test:docker:published-upgrade-survivor
 ```
 
-可用情境包括 `base`、`feishu-channel`、`bootstrap-persona`、`plugin-deps-cleanup`、`configured-plugin-installs`、`tilde-log-path` 與 `versioned-runtime-deps`。在 aggregate 執行中，`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 會展開為所有 reported issue 形狀的情境，包括 configured-plugin install migration。
+可用情境為 `base`、`feishu-channel`、`bootstrap-persona`、
+`plugin-deps-cleanup`、`configured-plugin-installs`、
+`stale-source-plugin-shadow`、`tilde-log-path` 與 `versioned-runtime-deps`。在彙總執行中，
+`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 會展開為所有回報
+issue 形狀的情境，包括已設定 Plugin 安裝遷移。
 
-完整更新 migration 會刻意與 Full Release CI 分開。當 release 問題是「2026.4.23 之後的每個已發佈 stable release 是否都能更新到這個候選版本並清理 Plugin 相依套件殘留物？」時，請使用手動 `Update Migration` workflow：
+完整更新遷移刻意與 Full Release CI 分開。當發行問題是「從 2026.4.23 起的每個
+已發佈穩定版本，是否都能更新到此候選版本並
+清理 Plugin 相依套件碎屑？」時，請使用手動 `Update Migration` 工作流程：
 
 ```bash
 gh workflow run update-migration.yml \
@@ -105,18 +148,27 @@ gh workflow run update-migration.yml \
 
 ## Package Acceptance
 
-Package Acceptance 是 GitHub 原生的套件 gate。它會將一個候選套件解析成 `package-under-test` tarball、記錄版本與 SHA-256，接著針對該確切 tarball 執行可重用的 Docker E2E lane。workflow harness ref 與套件來源 ref 分離，因此目前的測試邏輯可以驗證較舊的受信任 release。
+Package Acceptance 是 GitHub 原生的套件閘門。它會將一個候選
+套件解析為 `package-under-test` tarball，記錄版本與 SHA-256，接著
+針對該精確 tarball 執行可重用 Docker E2E 跑道。工作流程 harness
+參照與套件來源參照分離，因此目前的測試邏輯可以驗證
+較舊的受信任版本。
 
 候選來源：
 
-- `source=npm`：驗證 `openclaw@beta`、`openclaw@latest` 或確切的已發佈版本。
-- `source=ref`：使用選取的目前 harness 封裝受信任的 branch、tag 或 commit。
-- `source=url`：驗證 HTTPS tarball，並要求 `package_sha256`。
-- `source=artifact`：重用另一個 Actions run 上傳的 tarball。
+- `source=npm`：驗證 `openclaw@beta`、`openclaw@latest`，或精確的
+  已發佈版本。
+- `source=ref`：使用選定的目前
+  harness 封裝受信任的分支、標籤或提交。
+- `source=url`：使用必要的 `package_sha256` 驗證 HTTPS tarball。
+- `source=artifact`：重用另一個 Actions 執行上傳的 tarball。
 
-Full Release Validation 預設使用 `source=artifact`，由解析後的 release SHA 建置。若要進行發佈後證明，請傳入 `package_acceptance_package_spec=openclaw@YYYY.M.D`，讓相同的升級矩陣以已出貨的 npm 套件為目標。
+Full Release Validation 預設使用 `source=artifact`，由已解析的
+發行 SHA 建置。若要做發佈後證明，請傳入
+`package_acceptance_package_spec=openclaw@YYYY.M.D`，讓相同升級矩陣
+改以已出貨的 npm 套件為目標。
 
-Release 檢查會使用 package/update/plugin 集合呼叫 Package Acceptance：
+發行檢查會以套件/更新/Plugin 集呼叫 Package Acceptance：
 
 ```text
 doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update
@@ -130,11 +182,16 @@ published_upgrade_survivor_scenarios=reported-issues
 telegram_mode=mock-openai
 ```
 
-這會讓套件 migration、更新 channel 切換、過時 Plugin 相依套件清理、離線 Plugin 覆蓋、Plugin 更新行為，以及 Telegram 套件 QA 都落在同一個解析後 artifact 上。
+這會讓套件遷移、更新頻道切換、過時 Plugin 相依套件
+清理、離線 Plugin 覆蓋、Plugin 更新行為與 Telegram 套件
+QA 都位於同一個已解析產物上。
 
-`all-since-2026.4.23` 是 Full Release CI 升級樣本：從 `2026.4.23` 到 `latest` 的每個 stable npm-published release。若要進行詳盡的已發佈更新 migration 覆蓋，請在獨立的 Update Migration workflow 中使用 `all-since-2026.4.23`，而不是 Full Release CI。當你也想要舊版前日期 anchor 時，`release-history` 仍可用於手動更廣泛抽樣。
+`all-since-2026.4.23` 是 Full Release CI 升級樣本：從 `2026.4.23` 到 `latest` 的每個穩定 npm 已發佈版本。若要取得完整的已發佈
+更新遷移覆蓋，請在獨立的 Update
+Migration 工作流程中使用 `all-since-2026.4.23`，而不是 Full Release CI。當你也需要舊版日期前
+錨點時，`release-history` 仍可供手動更廣泛抽樣。
 
-在 release 前驗證候選版本時，手動執行 package profile：
+在發行前驗證候選版本時，手動執行套件 profile：
 
 ```bash
 gh workflow run package-acceptance.yml \
@@ -148,49 +205,69 @@ gh workflow run package-acceptance.yml \
   -f telegram_mode=mock-openai
 ```
 
-當 release 問題包含 MCP channel、cron/subagent 清理、OpenAI web search 或 OpenWebUI 時，使用 `suite_profile=product`。只有在需要完整 Docker release-path 覆蓋時，才使用 `suite_profile=full`。
+當發行問題包含 MCP 頻道、cron/subagent 清理、OpenAI 網頁搜尋或 OpenWebUI 時，使用 `suite_profile=product`。只有在需要完整 Docker 發行路徑覆蓋時，才使用 `suite_profile=full`。
 
-## Release 預設值
+## 發行預設
 
-對於 release candidate，預設證明堆疊是：
+對於發行候選版本，預設證明堆疊如下：
 
-1. `pnpm check:changed` 與 `pnpm test:changed`，用於 source 層級 regression。
-2. `pnpm release:check`，用於套件 artifact 完整性。
-3. Package Acceptance `package` profile，或 release-check 自訂套件 lane，用於 install/update/plugin 契約。
-4. Cross-OS release 檢查，用於 OS-specific installer、onboarding 與 platform 行為。
-5. 只有當變更 surface 觸及 provider 或 hosted-service 行為時，才執行 live suite。
+1. `pnpm check:changed` 與 `pnpm test:changed`，用於來源層級的迴歸。
+2. `pnpm release:check`，用於套件產物完整性。
+3. Package Acceptance `package` profile，或 release-check 自訂套件
+   跑道，用於安裝/更新/Plugin 契約。
+4. 跨 OS 發行檢查，用於 OS 特定安裝器、onboarding 與平台
+   行為。
+5. 只有當變更表面觸及供應商或託管服務
+   行為時，才執行即時測試套件。
 
-在 maintainer 機器上，寬範圍 gate 與 Docker/package 產品證明應在 Testbox 中執行，除非明確進行本機證明。
+在維護者機器上，廣泛閘門與 Docker/套件產品證明應在
+Testbox 中執行，除非明確要做本機證明。
 
 ## 舊版相容性
 
-相容性寬容範圍很窄且有時間限制：
+相容性寬限範圍很窄且有時間限制：
 
-- 到 `2026.4.25` 為止的套件，包括 `2026.4.25-beta.*`，可容忍 Package Acceptance 中已出貨的套件 metadata 缺口。
-- 已發佈的 `2026.4.26` 套件可對已出貨的本機 build metadata stamp 檔案發出警告。
-- 較新的套件必須滿足現代契約。相同缺口會失敗，而不是警告或略過。
+- 到 `2026.4.25` 為止的套件，包括 `2026.4.25-beta.*`，可容許
+  Package Acceptance 中已出貨的套件中繼資料缺口。
+- 已發佈的 `2026.4.26` 套件可能會針對已出貨的本機建置中繼資料戳記
+  檔案發出警告。
+- 較新的套件必須符合現代契約。相同缺口會失敗，而不是
+  警告或跳過。
 
-不要為這些舊形狀新增啟動 migration。請新增或延伸 doctor 修復，然後使用 `upgrade-survivor` 或 `published-upgrade-survivor` 證明它。
+不要為這些舊形狀新增啟動遷移。新增或擴充 doctor
+修復，然後用 `upgrade-survivor` 或 `published-upgrade-survivor` 證明它。
 
 ## 新增覆蓋
 
-變更更新或 Plugin 行為時，請在能因正確理由失敗的最低層新增覆蓋：
+變更更新或 Plugin 行為時，請在能因正確原因
+失敗的最低層級新增覆蓋：
 
-- 純路徑或 metadata 邏輯：來源旁的 unit test。
-- 套件 inventory 或 packed-file 行為：`package-dist-inventory` 或 tarball checker test。
-- CLI 安裝/更新行為：Docker lane assertion 或 fixture。
-- 已發佈 release migration 行為：`published-upgrade-survivor` 情境。
-- Registry/package 來源行為：`test:docker:plugins` fixture 或 ClawHub fixture server。
-- 相依套件版面或清理行為：同時斷言 runtime 執行與檔案系統邊界。npm 相依套件可能 hoist 到受管理的 npm root 下，因此測試應證明 root 會被掃描/清理，而不是假設 package-local `node_modules` tree。
+- 純路徑或中繼資料邏輯：來源旁的單元測試。
+- 套件清單或封裝檔案行為：`package-dist-inventory` 或 tarball
+  檢查器測試。
+- CLI 安裝/更新行為：Docker 跑道斷言或 fixture。
+- 已發佈版本遷移行為：`published-upgrade-survivor` 情境。
+- 登錄/套件來源行為：`test:docker:plugins` fixture 或 ClawHub
+  fixture 伺服器。
+- 相依套件配置或清理行為：同時斷言執行階段執行與
+  檔案系統邊界。npm 相依套件可能會被提升到受管理的 npm
+  根目錄下，因此測試應證明該根目錄有被掃描/清理，而不是假設有
+  套件本機的 `node_modules` 樹。
 
-新的 Docker fixture 預設保持 hermetic。除非測試重點是 live registry 行為，否則使用本機 fixture registry 與 fake package。
+讓新的 Docker fixture 預設保持 hermetic。除非測試重點就是即時登錄行為，
+否則使用本機 fixture 登錄與假套件。
 
-## 失敗分類
+## 失敗分流
 
-從 artifact 身分開始：
+從產物身分開始：
 
-- Package Acceptance `resolve_package` 摘要：來源、版本、SHA-256 與 artifact 名稱。
-- Docker artifact：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane log 與 rerun 指令。
-- Upgrade survivor 摘要：`.artifacts/upgrade-survivor/summary.json`，包含 baseline 版本、候選版本、情境、階段 timing 與 recipe step。
+- Package Acceptance `resolve_package` 摘要：來源、版本、SHA-256 與
+  產物名稱。
+- Docker 產物：`.artifacts/docker-tests/**/summary.json`、
+  `failures.json`、跑道日誌與重新執行命令。
+- Upgrade survivor 摘要：`.artifacts/upgrade-survivor/summary.json`，
+  包含基準版本、候選版本、情境、階段時間與
+  配方步驟。
 
-優先使用相同套件 artifact 重新執行失敗的確切 lane，而不是重新執行整個 release umbrella。
+優先使用相同套件產物重新執行失敗的精確跑道，而不是
+重新執行整個發行總括流程。

docs/zh-TW/plugins/bundles.md

@@ -1,37 +1,37 @@
 ---
 read_when:
-    - 您想要安裝與 Codex、Claude 或 Cursor 相容的套件包
-    - 你需要了解 OpenClaw 如何將套件內容對應到原生功能
-    - 你正在偵錯套件組合偵測或缺少的能力
-summary: 安裝並將 Codex、Claude 和 Cursor 套件作為 OpenClaw Plugin 使用
+    - 您想安裝與 Codex、Claude 或 Cursor 相容的套件包
+    - 您需要了解 OpenClaw 如何將套件內容對應到原生功能
+    - 您正在偵錯套件組合偵測或缺少的功能
+summary: 將 Codex、Claude 和 Cursor 套件作為 OpenClaw Plugin 安裝並使用
 title: Plugin 套件包
 x-i18n:
-    generated_at: "2026-05-02T02:54:51Z"
+    generated_at: "2026-05-05T01:47:56Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4
+    source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157
     source_path: plugins/bundles.md
     workflow: 16
 ---
 
-OpenClaw 可以從三個外部生態系統安裝 Plugin：**Codex**、**Claude**，
-以及 **Cursor**。這些稱為 **bundle**，也就是內容與中繼資料套件，
+OpenClaw 可以從三個外部生態系安裝 Plugin：**Codex**、**Claude**，
+以及 **Cursor**。這些稱為 **套件包**，也就是內容與中介資料套件，
 OpenClaw 會將其對應到 Skills、hook 和 MCP 工具等原生功能。
 
 <Info>
-  bundle **不同於** 原生 OpenClaw Plugin。原生 Plugin 會在
-  處理序內執行，並且可以註冊任何能力。bundle 則是內容套件，具備
-  選擇性的功能對應，以及較窄的信任邊界。
+  套件包與 OpenClaw 原生 Plugin **不同**。原生 Plugin 會在程序內執行，
+  並且可以註冊任何能力。套件包是內容套件，具有選擇性的功能對應，
+  並且信任邊界較窄。
 </Info>
 
-## bundle 存在的原因
+## 為什麼存在套件包
 
-許多實用的 Plugin 會以 Codex、Claude 或 Cursor 格式發布。OpenClaw
-不要求作者將它們重寫為原生 OpenClaw Plugin，而是偵測這些格式，
-並將其支援的內容對應到原生功能集合。這表示你可以安裝 Claude 指令套件
-或 Codex skill bundle，並立即使用。
+許多實用 Plugin 會以 Codex、Claude 或 Cursor 格式發布。OpenClaw 不要求
+作者將它們重寫成 OpenClaw 原生 Plugin，而是偵測這些格式，並將其支援的
+內容對應到原生功能集。這代表你可以安裝 Claude 指令套件或 Codex skill
+套件包，並立即使用。
 
-## 安裝 bundle
+## 安裝套件包
 
 <Steps>
   <Step title="從目錄、封存檔或市集安裝">
@@ -49,13 +49,13 @@ OpenClaw 會將其對應到 Skills、hook 和 MCP 工具等原生功能。
 
   </Step>
 
-  <Step title="驗證偵測">
+  <Step title="驗證偵測結果">
     ```bash
     openclaw plugins list
     openclaw plugins inspect <id>
     ```
 
-    bundle 會顯示為 `Format: bundle`，並帶有 `codex`、`claude` 或 `cursor` 子類型。
+    套件包會顯示為 `Format: bundle`，並帶有 `codex`、`claude` 或 `cursor` 子類型。
 
   </Step>
 
@@ -69,57 +69,55 @@ OpenClaw 會將其對應到 Skills、hook 和 MCP 工具等原生功能。
   </Step>
 </Steps>
 
-## OpenClaw 會從 bundle 對應什麼
+## OpenClaw 從套件包對應哪些內容
 
-目前並非每項 bundle 功能都會在 OpenClaw 中執行。以下列出可用的功能，
-以及已偵測但尚未接線的功能。
+並非所有套件包功能目前都會在 OpenClaw 中執行。以下列出哪些可用，
+以及哪些已偵測但尚未接線。
 
 ### 目前支援
 
 | 功能          | 對應方式                                                                                    | 適用於         |
 | ------------- | ------------------------------------------------------------------------------------------- | -------------- |
-| Skill 內容    | bundle skill root 會以一般 OpenClaw Skills 載入                                             | 所有格式       |
-| 指令          | `commands/` 和 `.cursor/commands/` 會視為 skill root                                        | Claude、Cursor |
-| Hook 套件     | OpenClaw 風格的 `HOOK.md` + `handler.ts` 配置                                               | Codex          |
-| MCP 工具      | bundle MCP 設定會合併到內嵌 Pi 設定；載入支援的 stdio 和 HTTP 伺服器                       | 所有格式       |
-| LSP 伺服器    | Claude `.lsp.json` 和清單宣告的 `lspServers` 會合併到內嵌 Pi LSP 預設值                    | Claude         |
+| Skill 內容    | 套件包 skill 根目錄會以一般 OpenClaw Skills 載入                                           | 所有格式       |
+| 指令          | `commands/` 和 `.cursor/commands/` 會被視為 skill 根目錄                                   | Claude、Cursor |
+| Hook 套件     | OpenClaw 風格的 `HOOK.md` + `handler.ts` 版面配置                                           | Codex          |
+| MCP 工具      | 套件包 MCP 設定會合併到內嵌 Pi 設定；支援的 stdio 和 HTTP 伺服器會被載入                   | 所有格式       |
+| LSP 伺服器    | Claude `.lsp.json` 和 manifest 宣告的 `lspServers` 會合併到內嵌 Pi LSP 預設值              | Claude         |
 | 設定          | Claude `settings.json` 會匯入為內嵌 Pi 預設值                                               | Claude         |
 
 #### Skill 內容
 
-- bundle skill root 會以一般 OpenClaw skill root 載入
-- Claude `commands` root 會視為額外的 skill root
-- Cursor `.cursor/commands` root 會視為額外的 skill root
+- 套件包 skill 根目錄會以一般 OpenClaw skill 根目錄載入
+- Claude `commands` 根目錄會被視為額外的 skill 根目錄
+- Cursor `.cursor/commands` 根目錄會被視為額外的 skill 根目錄
 
-這表示 Claude markdown 指令檔會透過一般 OpenClaw skill
-loader 運作。Cursor 指令 markdown 也會透過相同路徑運作。
+這代表 Claude Markdown 指令檔會透過一般 OpenClaw skill 載入器運作。
+Cursor 指令 Markdown 也會透過同一路徑運作。
 
 #### Hook 套件
 
-- bundle hook root **只有**在使用一般 OpenClaw hook-pack
-  配置時才會運作。目前這主要是相容 Codex 的情況：
+- 套件包 hook 根目錄**只有**在使用一般 OpenClaw hook 套件版面配置時才會運作。
+  目前這主要是與 Codex 相容的情況：
   - `HOOK.md`
   - `handler.ts` 或 `handler.js`
 
 #### Pi 的 MCP
 
-- 已啟用的 bundle 可以提供 MCP 伺服器設定
-- OpenClaw 會將 bundle MCP 設定合併到有效的內嵌 Pi 設定中，作為
+- 啟用的套件包可以提供 MCP 伺服器設定
+- OpenClaw 會將套件包 MCP 設定合併到有效的內嵌 Pi 設定中，作為
   `mcpServers`
-- OpenClaw 會在內嵌 Pi agent 回合期間公開支援的 bundle MCP 工具，
-  方式是啟動 stdio 伺服器或連線到 HTTP 伺服器
-- `coding` 和 `messaging` 工具 profile 預設包含 bundle MCP 工具；
-  若要為 agent 或 gateway 退出，請使用 `tools.deny: ["bundle-mcp"]`
-- 專案本機 Pi 設定仍會在 bundle 預設值之後套用，因此 workspace
-  設定可在需要時覆寫 bundle MCP 項目
-- bundle MCP 工具目錄會在註冊前以確定性方式排序，因此上游 `listTools()`
-  順序變更不會讓 prompt-cache 工具區塊反覆震盪
+- OpenClaw 會在內嵌 Pi agent 回合期間，透過啟動 stdio 伺服器或連線到 HTTP 伺服器，
+  公開支援的套件包 MCP 工具
+- `coding` 和 `messaging` 工具設定檔預設包含套件包 MCP 工具；
+  若要讓 agent 或 gateway 停用，請使用 `tools.deny: ["bundle-mcp"]`
+- 專案本機 Pi 設定仍會在套件包預設值之後套用，因此工作區設定可以在需要時覆寫套件包 MCP 項目
+- 套件包 MCP 工具目錄會在註冊前以確定性方式排序，因此上游 `listTools()` 順序變更不會造成提示快取工具區塊反覆變動
 
 ##### 傳輸
 
 MCP 伺服器可以使用 stdio 或 HTTP 傳輸：
 
-**Stdio** 會啟動子處理序：
+**Stdio** 會啟動子程序：
 
 ```json
 {
@@ -135,7 +133,7 @@ MCP 伺服器可以使用 stdio 或 HTTP 傳輸：
 }
 ```
 
-**HTTP** 預設會透過 `sse` 連線到執行中的 MCP 伺服器，或在指定時使用 `streamable-http`：
+**HTTP** 預設會透過 `sse` 連線到執行中的 MCP 伺服器，或在要求時使用 `streamable-http`：
 
 ```json
 {
@@ -154,35 +152,32 @@ MCP 伺服器可以使用 stdio 或 HTTP 傳輸：
 }
 ```
 
-- `transport` 可設為 `"streamable-http"` 或 `"sse"`；省略時，OpenClaw 會使用 `sse`
-- `type: "http"` 是 CLI 原生的下游形狀；請在 OpenClaw 設定中使用 `transport: "streamable-http"`。`openclaw mcp set` 和 `openclaw doctor --fix` 會標準化常見別名。
+- `transport` 可以設為 `"streamable-http"` 或 `"sse"`；省略時，OpenClaw 會使用 `sse`
+- `type: "http"` 是 CLI 原生的下游形狀；在 OpenClaw 設定中請使用 `transport: "streamable-http"`。`openclaw mcp set` 和 `openclaw doctor --fix` 會正規化常見別名。
 - 只允許 `http:` 和 `https:` URL scheme
 - `headers` 值支援 `${ENV_VAR}` 插值
 - 同時具有 `command` 和 `url` 的伺服器項目會被拒絕
-- URL 憑證（userinfo 和 query params）會從工具
-  描述與記錄中遮蔽
+- URL 憑證（使用者資訊和查詢參數）會從工具說明和日誌中遮蔽
 - `connectionTimeoutMs` 會覆寫 stdio 和 HTTP 傳輸的預設 30 秒連線逾時
 
 ##### 工具命名
 
-OpenClaw 會以 provider-safe 名稱註冊 bundle MCP 工具，格式為
-`serverName__toolName`。例如，鍵為 `"vigil-harbor"` 的伺服器公開
+OpenClaw 會以供應商安全名稱註冊套件包 MCP 工具，格式為
+`serverName__toolName`。例如，鍵名為 `"vigil-harbor"` 的伺服器公開
 `memory_search` 工具時，會註冊為 `vigil-harbor__memory_search`。
 
 - `A-Za-z0-9_-` 以外的字元會替換為 `-`
 - 伺服器前綴上限為 30 個字元
 - 完整工具名稱上限為 64 個字元
-- 空白伺服器名稱會 fallback 至 `mcp`
-- 發生碰撞的清理後名稱會以數字後綴消歧
-- 最終公開的工具順序會依 safe name 確定性排序，以保持重複 Pi
-  回合的快取穩定
-- profile 篩選會將同一 bundle MCP 伺服器的所有工具視為由 `bundle-mcp`
-  這個 Plugin 擁有，因此 profile allowlist 和 deny list 可以包含
-  個別公開工具名稱，或 `bundle-mcp` Plugin 鍵
+- 空的伺服器名稱會退回使用 `mcp`
+- 發生衝突的清理後名稱會以數字後綴消除歧義
+- 最終公開的工具順序會依安全名稱確定性排序，以保持重複 Pi 回合的快取穩定
+- 設定檔篩選會將同一個套件包 MCP 伺服器中的所有工具視為由 `bundle-mcp` 擁有的 Plugin，
+  因此設定檔允許清單和拒絕清單可以包含個別公開的工具名稱，或 `bundle-mcp` Plugin 鍵
 
 #### 內嵌 Pi 設定
 
-- bundle 啟用時，Claude `settings.json` 會匯入為預設的內嵌 Pi 設定
+- 啟用套件包時，Claude `settings.json` 會匯入為預設內嵌 Pi 設定
 - OpenClaw 會先清理 shell 覆寫鍵，再套用它們
 
 清理後的鍵：
@@ -192,57 +187,56 @@ OpenClaw 會以 provider-safe 名稱註冊 bundle MCP 工具，格式為
 
 #### 內嵌 Pi LSP
 
-- 已啟用的 Claude bundle 可以提供 LSP 伺服器設定
-- OpenClaw 會載入 `.lsp.json` 加上任何清單宣告的 `lspServers` 路徑
-- bundle LSP 設定會合併到有效的內嵌 Pi LSP 預設值中
-- 目前只有支援的 stdio-backed LSP 伺服器可執行；不支援的
-  傳輸仍會顯示在 `openclaw plugins inspect <id>` 中
+- 啟用的 Claude 套件包可以提供 LSP 伺服器設定
+- OpenClaw 會載入 `.lsp.json` 以及任何 manifest 宣告的 `lspServers` 路徑
+- 套件包 LSP 設定會合併到有效的內嵌 Pi LSP 預設值中
+- 目前只有支援的 stdio 後端 LSP 伺服器可執行；不支援的傳輸仍會顯示在 `openclaw plugins inspect <id>` 中
 
 ### 已偵測但不執行
 
-這些項目會被識別並顯示在診斷資訊中，但 OpenClaw 不會執行它們：
+以下項目會被辨識並顯示在診斷中，但 OpenClaw 不會執行它們：
 
 - Claude `agents`、`hooks.json` 自動化、`outputStyles`
 - Cursor `.cursor/agents`、`.cursor/hooks.json`、`.cursor/rules`
-- Codex inline/app 中繼資料，但能力回報除外
+- Codex 行內/app 中介資料，能力回報以外的部分
 
-## bundle 格式
+## 套件包格式
 
 <AccordionGroup>
-  <Accordion title="Codex bundle">
+  <Accordion title="Codex 套件包">
     標記：`.codex-plugin/plugin.json`
 
     選用內容：`skills/`、`hooks/`、`.mcp.json`、`.app.json`
 
-    Codex bundle 在使用 skill root 和 OpenClaw 風格
-    hook-pack 目錄（`HOOK.md` + `handler.ts`）時最適合 OpenClaw。
+    當 Codex 套件包使用 skill 根目錄和 OpenClaw 風格的 hook 套件目錄
+    （`HOOK.md` + `handler.ts`）時，最適合 OpenClaw。
 
   </Accordion>
 
-  <Accordion title="Claude bundle">
+  <Accordion title="Claude 套件包">
     兩種偵測模式：
 
-    - **基於清單：** `.claude-plugin/plugin.json`
-    - **無清單：** 預設 Claude 配置（`skills/`、`commands/`、`agents/`、`hooks/`、`.mcp.json`、`.lsp.json`、`settings.json`）
+    - **以 Manifest 為基礎：** `.claude-plugin/plugin.json`
+    - **無 Manifest：** 預設 Claude 版面配置（`skills/`、`commands/`、`agents/`、`hooks/`、`.mcp.json`、`.lsp.json`、`settings.json`）
 
     Claude 專屬行為：
 
-    - `commands/` 會視為 skill 內容
-    - `settings.json` 會匯入內嵌 Pi 設定（shell 覆寫鍵會被清理）
+    - `commands/` 會被視為 skill 內容
+    - `settings.json` 會匯入到內嵌 Pi 設定（shell 覆寫鍵會被清理）
     - `.mcp.json` 會向內嵌 Pi 公開支援的 stdio 工具
-    - `.lsp.json` 加上清單宣告的 `lspServers` 路徑會載入內嵌 Pi LSP 預設值
-    - `hooks/hooks.json` 會被偵測但不執行
-    - 清單中的自訂元件路徑是加成式的（它們會擴充預設值，而非取代預設值）
+    - `.lsp.json` 以及 manifest 宣告的 `lspServers` 路徑會載入到內嵌 Pi LSP 預設值
+    - `hooks/hooks.json` 會被偵測，但不會執行
+    - manifest 中的自訂元件路徑是累加式的（它們會擴充預設值，而不是取代預設值）
 
   </Accordion>
 
-  <Accordion title="Cursor bundle">
+  <Accordion title="Cursor 套件包">
     標記：`.cursor-plugin/plugin.json`
 
     選用內容：`skills/`、`.cursor/commands/`、`.cursor/agents/`、`.cursor/rules/`、`.cursor/hooks.json`、`.mcp.json`
 
-    - `.cursor/commands/` 會視為 skill 內容
-    - `.cursor/rules/`、`.cursor/agents/` 和 `.cursor/hooks.json` 僅偵測
+    - `.cursor/commands/` 會被視為 skill 內容
+    - `.cursor/rules/`、`.cursor/agents/` 和 `.cursor/hooks.json` 只會被偵測
 
   </Accordion>
 </AccordionGroup>
@@ -251,61 +245,57 @@ OpenClaw 會以 provider-safe 名稱註冊 bundle MCP 工具，格式為
 
 OpenClaw 會先檢查原生 Plugin 格式：
 
-1. `openclaw.plugin.json` 或具有 `openclaw.extensions` 的有效 `package.json`，會視為**原生 Plugin**
-2. bundle 標記（`.codex-plugin/`、`.claude-plugin/`，或預設 Claude/Cursor 配置），會視為 **bundle**
+1. `openclaw.plugin.json` 或具有 `openclaw.extensions` 的有效 `package.json` — 視為**原生 Plugin**
+2. 套件包標記（`.codex-plugin/`、`.claude-plugin/`，或預設 Claude/Cursor 版面配置）— 視為**套件包**
 
-如果目錄同時包含兩者，OpenClaw 會使用原生路徑。這可防止
-雙格式套件被部分安裝為 bundle。
+如果目錄同時包含兩者，OpenClaw 會使用原生路徑。這可避免雙格式套件被部分安裝為套件包。
 
 ## 執行階段相依性與清理
 
-- 第三方相容 bundle 不會取得啟動時的 `npm install` 修復。它們
-  應透過 `openclaw plugins install` 安裝，並在已安裝的 Plugin 目錄中
-  隨附所需的一切。
-- OpenClaw 擁有的 bundled Plugin 會以輕量形式隨 core 出貨，或可透過
-  Plugin 安裝器下載。Gateway 啟動時絕不會為它們執行
-  package manager。
-- `openclaw doctor --fix` 會移除舊版暫存相依性目錄，並可安裝本機
-  Plugin 索引中缺少的已設定可下載 Plugin。
+- 第三方相容套件包不會取得啟動時的 `npm install` 修復。它們應透過 `openclaw plugins install` 安裝，
+  並在已安裝的 Plugin 目錄中附帶所需的一切。
+- OpenClaw 擁有的套裝 Plugin 會以輕量形式隨核心出貨，或可透過 Plugin 安裝程式下載。
+  Gateway 啟動時永遠不會為它們執行套件管理器。
+- `openclaw doctor --fix` 會移除舊版暫存相依性目錄，並且在設定引用本機 Plugin 索引中缺少的可下載 Plugin 時，
+  可以復原這些 Plugin。
 
 ## 安全性
 
-bundle 的信任邊界比原生 Plugin 更窄：
+套件包的信任邊界比原生 Plugin 更窄：
 
-- OpenClaw **不會**在處理序內載入任意 bundle runtime 模組
-- Skills 和 hook-pack 路徑必須保留在 Plugin root 內（經邊界檢查）
-- 設定檔會使用相同的邊界檢查讀取
-- 支援的 stdio MCP 伺服器可能會作為子處理序啟動
+- OpenClaw **不會**在程序內載入任意套件包執行階段模組
+- Skills 和 hook 套件路徑必須留在 Plugin 根目錄內（會檢查邊界）
+- 設定檔會以相同的邊界檢查讀取
+- 支援的 stdio MCP 伺服器可以作為子程序啟動
 
-這讓 bundle 預設更安全，但你仍應將第三方
-bundle 視為其公開功能的受信任內容。
+這讓套件包預設更安全，但你仍應將第三方套件包視為其公開功能的可信內容。
 
 ## 疑難排解
 
 <AccordionGroup>
-  <Accordion title="bundle 已被偵測但能力沒有執行">
-    執行 `openclaw plugins inspect <id>`。如果某項能力有列出但標記為
-    尚未接線，這是產品限制，不是安裝損壞。
+  <Accordion title="已偵測到套件包，但能力未執行">
+    執行 `openclaw plugins inspect <id>`。如果某項能力已列出但標示為
+    尚未接線，那是產品限制，而不是安裝損壞。
   </Accordion>
 
-  <Accordion title="Claude 指令檔沒有出現">
-    確認 bundle 已啟用，且 markdown 檔案位於偵測到的
-    `commands/` 或 `skills/` root 內。
+  <Accordion title="Claude 指令檔未出現">
+    請確認套件包已啟用，且 Markdown 檔案位於已偵測到的
+    `commands/` 或 `skills/` 根目錄內。
   </Accordion>
 
-  <Accordion title="Claude 設定沒有套用">
-    只支援來自 `settings.json` 的內嵌 Pi 設定。OpenClaw 不會
-    將 bundle 設定視為原始 config patch。
+  <Accordion title="Claude 設定未套用">
+    只支援來自 `settings.json` 的內嵌 Pi 設定。OpenClaw 不會將套件包設定
+    視為原始設定修補。
   </Accordion>
 
-  <Accordion title="Claude hook 沒有執行">
-    `hooks/hooks.json` 僅偵測。如果需要可執行的 hook，請使用
-    OpenClaw hook-pack 配置，或出貨原生 Plugin。
+  <Accordion title="Claude hook 未執行">
+    `hooks/hooks.json` 只會被偵測。如果你需要可執行的 hook，請使用
+    OpenClaw hook 套件版面配置，或出貨原生 Plugin。
   </Accordion>
 </AccordionGroup>
 
-## 相關
+## 相關內容
 
-- [安裝與設定 Plugin](/zh-TW/tools/plugin)
+- [安裝和設定 Plugin](/zh-TW/tools/plugin)
 - [建置 Plugin](/zh-TW/plugins/building-plugins) — 建立原生 Plugin
-- [Plugin 清單](/zh-TW/plugins/manifest) — 原生清單 schema
+- [Plugin Manifest](/zh-TW/plugins/manifest) — 原生 manifest schema

docs/zh-TW/plugins/dependency-resolution.md

@@ -1,31 +1,31 @@
 ---
 read_when:
     - 你正在偵錯 Plugin 套件安裝
-    - 你正在變更 Plugin 啟動、doctor 或套件管理器安裝行為
-    - 你正在維護封裝的 OpenClaw 安裝或內建 Plugin manifest
+    - 您正在變更 Plugin 啟動、doctor 或套件管理器安裝行為
+    - 你正在維護封裝版 OpenClaw 安裝或隨附的 Plugin 清單
 sidebarTitle: Dependencies
-summary: OpenClaw 如何安裝 Plugin 套件並解析 Plugin 相依性
-title: Plugin 相依性解析
+summary: OpenClaw 如何安裝 Plugin 套件並解析 Plugin 依賴關係
+title: Plugin 依賴解析
 x-i18n:
-    generated_at: "2026-05-03T21:37:54Z"
+    generated_at: "2026-05-05T01:48:22Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d
+    source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20
     source_path: plugins/dependency-resolution.md
     workflow: 16
 ---
 
-# Plugin 相依性解析
+# Plugin 依賴項解析
 
-OpenClaw 會在安裝/更新期間處理 Plugin 相依性工作。執行階段載入不會執行套件管理器、修復相依性樹，或變更 OpenClaw 套件目錄。
+OpenClaw 將 Plugin 依賴項處理保留在安裝/更新時進行。執行階段載入不會執行套件管理器、修復依賴項樹，或變更 OpenClaw 套件目錄。
 
-## 責任劃分
+## 責任分工
 
-Plugin 套件擁有自己的相依性圖：
+Plugin 套件擁有自己的依賴項圖：
 
-- 執行階段相依性位於 Plugin 套件的 `dependencies` 或 `optionalDependencies`
-- SDK/core 匯入是 peer 或由 OpenClaw 提供的匯入
-- 本機開發 Plugin 會自行帶入已安裝的相依性
+- 執行階段依賴項位於 Plugin 套件的 `dependencies` 或 `optionalDependencies`
+- SDK/核心匯入是對等依賴，或由 OpenClaw 提供的匯入
+- 本機開發 Plugin 會自備已安裝的依賴項
 - npm 和 git Plugin 會安裝到 OpenClaw 擁有的套件根目錄
 
 OpenClaw 只負責 Plugin 生命週期：
@@ -34,15 +34,15 @@ OpenClaw 只負責 Plugin 生命週期：
 - 在明確要求時安裝或更新套件
 - 記錄安裝中繼資料
 - 載入 Plugin 進入點
-- 在相依性缺失時，以可執行的錯誤失敗
+- 當依賴項缺失時，以可操作的錯誤失敗
 
 ## 安裝根目錄
 
-OpenClaw 會使用穩定的每來源根目錄：
+OpenClaw 使用穩定的每來源根目錄：
 
-- npm 套件安裝在 `~/.openclaw/npm` 底下
-- git 套件複製在 `~/.openclaw/git` 底下
-- 本機/路徑/封存安裝會被複製或參照，而不修復相依性
+- npm 套件安裝在 `~/.openclaw/npm` 下
+- git 套件複製到 `~/.openclaw/git` 下
+- 本機/路徑/封存檔安裝會被複製或參照，不會修復依賴項
 
 npm 安裝會在 npm 根目錄中執行：
 
@@ -50,7 +50,7 @@ npm 安裝會在 npm 根目錄中執行：
 npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
 ```
 
-npm 可能會將傳遞相依性提升到 Plugin 套件旁邊的 `~/.openclaw/npm/node_modules`。OpenClaw 會先掃描受管理的 npm 根目錄，再信任該安裝，並在解除安裝期間使用 npm 移除 npm 管理的套件，因此被提升的執行階段相依性會留在受管理的清理邊界內。
+npm 可能會將遞移依賴項提升到 Plugin 套件旁的 `~/.openclaw/npm/node_modules`。OpenClaw 會先掃描受管理的 npm 根目錄，再信任該安裝，並在解除安裝期間使用 npm 移除 npm 管理的套件，因此被提升的執行階段依賴項會留在受管理的清理邊界內。
 
 git 安裝會複製或重新整理儲存庫，然後執行：
 
@@ -58,19 +58,19 @@ git 安裝會複製或重新整理儲存庫，然後執行：
 npm install --omit=dev --ignore-scripts --no-audit --no-fund
 ```
 
-已安裝的 Plugin 接著會從該套件目錄載入，因此套件本機與父層 `node_modules` 解析的運作方式，會與一般 Node 套件相同。
+已安裝的 Plugin 接著會從該套件目錄載入，因此套件本機和父層 `node_modules` 解析的運作方式，會與一般 Node 套件相同。
 
 ## 本機 Plugin
 
-本機 Plugin 會被視為由開發者控制的目錄。OpenClaw 不會為它們執行 `npm install`、`pnpm install` 或相依性修復。如果本機 Plugin 有相依性，請先在該 Plugin 中安裝它們，再載入該 Plugin。
+本機 Plugin 會被視為開發者控制的目錄。OpenClaw 不會為它們執行 `npm install`、`pnpm install` 或依賴項修復。如果本機 Plugin 有依賴項，請先在該 Plugin 中安裝，再載入它。
 
-第三方 TypeScript 本機 Plugin 可以使用緊急 Jiti 路徑。封裝的 JavaScript Plugin 和內建內部 Plugin 會透過原生 import/require 載入，而不是 Jiti。
+第三方 TypeScript 本機 Plugin 可以使用緊急 Jiti 路徑。已封裝的 JavaScript Plugin 和內建內部 Plugin 會透過原生 import/require 載入，而不是透過 Jiti。
 
-## 啟動與重新載入
+## 啟動和重新載入
 
-Gateway 啟動和設定重新載入永遠不會安裝 Plugin 相依性。它們會讀取 Plugin 安裝記錄、計算進入點，並載入它。
+Gateway 啟動和設定重新載入絕不會安裝 Plugin 依賴項。它們會讀取 Plugin 安裝記錄、計算進入點，並載入它。
 
-如果執行階段缺少相依性，Plugin 會載入失敗，且錯誤應指引操作員採取明確修正：
+如果執行階段缺少依賴項，Plugin 會載入失敗，而且錯誤應指引操作員採取明確修復：
 
 ```bash
 openclaw plugins update <id>
@@ -78,26 +78,26 @@ openclaw plugins install <source>
 openclaw doctor --fix
 ```
 
-`doctor --fix` 可以清理舊版 OpenClaw 產生的相依性狀態，並安裝已設定但本機安裝記錄中缺失的可下載 Plugin。它不會修復已安裝本機 Plugin 的相依性。
+`doctor --fix` 可以清理舊版 OpenClaw 產生的依賴項狀態，並在設定參照可下載 Plugin、但本機安裝記錄缺少它們時復原這些 Plugin。Doctor 不會為已安裝的本機 Plugin 修復依賴項。
 
 ## 內建 Plugin
 
-輕量且核心關鍵的內建 Plugin 會作為 OpenClaw 的一部分出貨。它們應該沒有繁重的執行階段相依性樹，或被移出為 ClawHub/npm 上的可下載套件。
+輕量且對核心關鍵的內建 Plugin 會作為 OpenClaw 的一部分交付。它們應該沒有沉重的執行階段依賴項樹，或移出成為 ClawHub/npm 上的可下載套件。
 
-如需目前在核心套件中出貨、外部安裝或僅保留原始碼的 Plugin 產生清單，請參閱 [Plugin 清單](/zh-TW/plugins/plugin-inventory)。
+如需目前隨核心套件交付、外部安裝或僅保留原始碼的 Plugin 產生清單，請參閱 [Plugin 清單](/zh-TW/plugins/plugin-inventory)。
 
-內建 Plugin manifest 不得要求相依性 staging。大型或選用的 Plugin 功能應封裝為一般 Plugin，並透過與第三方 Plugin 相同的 npm/git/ClawHub 路徑安裝。
+內建 Plugin manifest 不得要求依賴項暫存。大型或選用的 Plugin 功能應封裝為一般 Plugin，並透過與第三方 Plugin 相同的 npm/git/ClawHub 路徑安裝。
 
-在原始碼 checkout 中，OpenClaw 會將儲存庫視為 pnpm monorepo。在 `pnpm install` 之後，內建 Plugin 會從 `extensions/<id>` 載入，因此套件本機的 workspace 相依性可用，且編輯會直接被採用。原始碼 checkout 開發僅支援 pnpm；在儲存庫根目錄執行純 `npm install` 不是準備內建 Plugin 相依性的支援方式。
+在原始碼 checkout 中，OpenClaw 會將儲存庫視為 pnpm monorepo。執行 `pnpm install` 後，內建 Plugin 會從 `extensions/<id>` 載入，因此套件本機 workspace 依賴項可用，且編輯會直接生效。原始碼 checkout 開發僅支援 pnpm；在儲存庫根目錄執行一般 `npm install` 不是準備內建 Plugin 依賴項的支援方式。
 
-| 安裝形式                         | 內建 Plugin 位置                     | 相依性擁有者                                                         |
+| 安裝形態                         | 內建 Plugin 位置                      | 依賴項擁有者                                                         |
 | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
-| `npm install -g openclaw`        | 套件內的建置執行階段樹               | OpenClaw 套件，以及明確的 Plugin 安裝/更新/doctor 流程              |
-| Git checkout 加上 `pnpm install` | `extensions/<id>` workspace 套件      | pnpm workspace，包含每個 Plugin 套件自己的相依性                    |
+| `npm install -g openclaw`        | 套件內建置的執行階段樹                | OpenClaw 套件，以及明確的 Plugin 安裝/更新/doctor 流程              |
+| Git checkout 加上 `pnpm install` | `extensions/<id>` workspace 套件      | pnpm workspace，包括每個 Plugin 套件自己的依賴項                    |
 | `openclaw plugins install ...`   | 受管理的 npm/git/ClawHub Plugin 根目錄 | Plugin 安裝/更新流程                                                 |
 
 ## 舊版清理
 
-較舊的 OpenClaw 版本會在啟動時或 doctor 修復期間產生內建 Plugin 相依性根目錄。目前的 doctor 清理會在使用 `--fix` 時移除這些過時的目錄和 symlink，包括舊的 `plugin-runtime-deps` 根目錄、指向已修剪 `plugin-runtime-deps` 目標的全域 Node-prefix 套件 symlink、`.openclaw-runtime-deps*` manifest、產生的 Plugin `node_modules`、安裝 staging 目錄，以及套件本機的 pnpm store。封裝的 postinstall 也會在修剪舊版目標根目錄之前移除這些全域 symlink，因此升級不會留下懸空的 ESM 套件匯入。
+較舊的 OpenClaw 版本會在啟動時或 doctor 修復期間產生內建 Plugin 依賴項根目錄。現在的 doctor 清理會在使用 `--fix` 時移除這些過時目錄和符號連結，包括舊的 `plugin-runtime-deps` 根目錄、指向已修剪 `plugin-runtime-deps` 目標的全域 Node 前綴套件符號連結、`.openclaw-runtime-deps*` manifest、產生的 Plugin `node_modules`、安裝暫存目錄，以及套件本機 pnpm 儲存區。封裝的 postinstall 也會在修剪舊版目標根目錄之前移除這些全域符號連結，讓升級不會留下懸空的 ESM 套件匯入。
 
-這些路徑只是舊版殘留物。新的安裝不應建立它們。
+這些路徑只是舊版殘留。新安裝不應建立它們。

docs/zh-TW/plugins/manage-plugins.md

@@ -1,21 +1,21 @@
 ---
 read_when:
-    - 你想要快速的 Plugin 安裝、列出、更新或解除安裝範例
-    - 你想在 ClawHub 與 npm Plugin 發布之間做選擇
-    - 你正在發布 Plugin 套件
+    - 你想要 Plugin 的快速安裝、列出、更新或解除安裝範例
+    - 你想在 ClawHub 與 npm Plugin 發佈之間做選擇
+    - 您正在發布 Plugin 套件
 sidebarTitle: Manage plugins
-summary: 安裝、列出、解除安裝、更新及發布 OpenClaw Plugin 的快速範例
+summary: 安裝、列出、解除安裝、更新和發布 OpenClaw Plugin 的快速範例
 title: 管理 Plugin
 x-i18n:
-    generated_at: "2026-05-02T22:19:43Z"
+    generated_at: "2026-05-05T01:48:41Z"
     model: gpt-5.5
     provider: openai
-    source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320
+    source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c
     source_path: plugins/manage-plugins.md
     workflow: 16
 ---
 
-大多數 Plugin 工作流程只需要幾個命令：搜尋、安裝、重新啟動 Gateway、
+大多數 Plugin 工作流程只需要幾個指令：搜尋、安裝、重新啟動 Gateway、
 驗證，並在不再需要該 Plugin 時解除安裝。
 
 ## 列出 Plugin
@@ -27,8 +27,8 @@ openclaw plugins list --verbose
 openclaw plugins list --json
 ```
 
-在腳本中使用 `--json`。當 Plugin 套件宣告 `dependencies` 或
-`optionalDependencies` 時，它會包含註冊表診斷資訊以及每個 Plugin 的
+對腳本使用 `--json`。它會包含登錄檔診斷資訊，以及當 Plugin 套件宣告 `dependencies` 或
+`optionalDependencies` 時，每個 Plugin 的
 靜態 `dependencyStatus`。
 
 ```bash
@@ -36,9 +36,9 @@ openclaw plugins list --json \
   | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
 ```
 
-`plugins list` 是冷啟動清查檢查。它會顯示 OpenClaw 可從設定、manifest
-和 Plugin 註冊表探索到的內容；但不會證明已在執行中的 Gateway 程序已匯入
-該 Plugin runtime。
+`plugins list` 是冷狀態的清查檢查。它會顯示 OpenClaw 可以從設定、
+manifest 和 Plugin 登錄檔中探索到的內容；它不會證明已在執行中的 Gateway
+程序已匯入該 Plugin runtime。
 
 ## 安裝 Plugin
 
@@ -65,15 +65,16 @@ openclaw plugins install ./my-plugin
 openclaw plugins install --link ./my-plugin
 ```
 
-安裝 Plugin 程式碼後，重新啟動為你的頻道提供服務的 Gateway：
+安裝 Plugin 程式碼後，重新啟動服務於你各通道的 Gateway：
 
 ```bash
 openclaw gateway restart
 openclaw plugins inspect <plugin-id> --runtime --json
 ```
 
-當你需要證明 Plugin 已註冊 runtime 介面，例如工具、hook、服務、Gateway
-方法，或 Plugin 擁有的 CLI 命令時，請使用 `inspect --runtime`。
+當你需要證明 Plugin 已註冊 runtime 介面時，請使用 `inspect --runtime`，
+例如工具、hook、服務、Gateway 方法，或 Plugin 擁有的 CLI
+指令。
 
 ## 更新 Plugin
 
@@ -83,22 +84,22 @@ openclaw plugins update <npm-package-or-spec>
 openclaw plugins update --all
 ```
 
-如果 Plugin 是從 npm dist-tag（例如 `@beta`）安裝，後續的
-`update <plugin-id>` 呼叫會重用該已記錄的 tag。傳入明確的 npm spec
-會把追蹤的安裝切換到該 spec，以供未來更新使用。
+如果某個 Plugin 是從 npm dist-tag（例如 `@beta`）安裝，後續的
+`update <plugin-id>` 呼叫會重用該已記錄的標籤。傳入明確的 npm spec
+會將追蹤中的安裝切換為該 spec，以供日後更新使用。
 
 ```bash
 openclaw plugins update @scope/openclaw-plugin@beta
 openclaw plugins update @scope/openclaw-plugin
 ```
 
-第二個命令會在 Plugin 先前固定到確切版本或 tag 時，將它移回註冊表的預設
-發布線。
+第二個指令會在 Plugin 先前固定到精確版本或標籤時，將其移回登錄檔的預設發行線。
 
-當 `openclaw update` 在 beta channel 上執行時，預設線的 npm 和 ClawHub
-Plugin 記錄會先嘗試相符的 Plugin `@beta` 版本。如果該 beta 版本不存在，
-OpenClaw 會退回到已記錄的 default/latest spec。確切版本和明確 tag
-（例如 `@rc` 或 `@beta`）會保留。
+當 `openclaw update` 在 beta 通道上執行時，預設線的 npm 和 ClawHub
+Plugin 記錄會先嘗試相符的 Plugin `@beta` 發行版。如果該 beta
+發行版不存在，OpenClaw 會退回到已記錄的預設/latest spec。
+對於 npm Plugin，若 beta 套件存在但未通過安裝驗證，OpenClaw 也會退回。
+精確版本與明確標籤（例如 `@rc` 或 `@beta`）會被保留。
 
 ## 解除安裝 Plugin
 
@@ -109,9 +110,8 @@ openclaw plugins uninstall <plugin-id> --keep-files
 openclaw gateway restart
 ```
 
-解除安裝會移除 Plugin 的設定項目、Plugin 索引記錄、允許/拒絕清單項目，
-以及適用時的連結載入路徑。除非你傳入 `--keep-files`，否則受管理的安裝目錄
-會被移除。
+解除安裝會在適用時移除該 Plugin 的設定項目、Plugin 索引記錄、允許/拒絕清單項目，
+以及連結的載入路徑。受管理的安裝目錄會被移除，除非你傳入 `--keep-files`。
 
 ## 發布 Plugin
 
@@ -120,8 +120,8 @@ openclaw gateway restart
 
 ### 發布到 ClawHub
 
-ClawHub 是 OpenClaw Plugin 的主要公開探索介面。它會在安裝前提供使用者可搜尋的
-中繼資料、版本歷史，以及註冊表掃描結果。
+ClawHub 是 OpenClaw Plugin 的主要公開探索介面。它讓使用者在安裝前取得
+可搜尋的中繼資料、版本歷史，以及登錄檔掃描結果。
 
 ```bash
 npm i -g clawhub
@@ -131,14 +131,14 @@ clawhub package publish your-org/your-plugin
 clawhub package publish your-org/your-plugin@v1.0.0
 ```
 
-使用者可透過以下方式從 ClawHub 安裝：
+使用者可透過 ClawHub 安裝：
 
 ```bash
 openclaw plugins install clawhub:<package>
 openclaw plugins install <package>
 ```
 
-裸格式仍會先檢查 ClawHub。
+裸形式仍會先檢查 ClawHub。
 
 ### 發布到 npmjs.com
 
@@ -160,7 +160,7 @@ openclaw plugins install <package>
 npm publish --access public
 ```
 
-使用者可透過以下方式安裝僅限 npm 的 Plugin：
+使用者可用 npm-only 方式安裝：
 
 ```bash
 openclaw plugins install npm:@acme/openclaw-plugin
@@ -168,20 +168,22 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta
 openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
 ```
 
-如果同一套件也可在 ClawHub 上取得，`npm:` 會略過 ClawHub 查詢並強制使用
-npm 解析。
+如果同一個套件也可在 ClawHub 取得，`npm:` 會略過 ClawHub 查詢並
+強制使用 npm 解析。
 
 ## 來源選擇
 
-- **ClawHub**：當你想要 OpenClaw 原生探索、掃描摘要、版本，以及安裝提示時使用。
-- **npmjs.com**：當你已經發布 JavaScript 套件，或需要 npm dist-tag/私有註冊表工作流程時使用。
-- **Git**：當你想要直接從分支、tag 或 commit 安裝時使用。
-- **本機路徑**：當你正在同一台機器上開發或測試 Plugin 時使用。
+- **ClawHub**：當你想要 OpenClaw 原生探索、掃描摘要、
+  版本，以及安裝提示時使用。
+- **npmjs.com**：當你已在發布 JavaScript 套件，或需要 npm
+  dist-tags/私有登錄檔工作流程時使用。
+- **Git**：當你想直接從分支、標籤或提交安裝時使用。
+- **本機路徑**：當你在同一台機器上開發或測試 Plugin 時使用。
 
 ## 相關
 
 - [Plugin](/zh-TW/tools/plugin) - 概觀與疑難排解
 - [`openclaw plugins`](/zh-TW/cli/plugins) - 完整 CLI 參考
-- [ClawHub](/zh-TW/tools/clawhub) - 發布與註冊表操作
+- [ClawHub](/zh-TW/tools/clawhub) - 發布與登錄檔操作
 - [建置 Plugin](/zh-TW/plugins/building-plugins) - 建立 Plugin 套件
 - [Plugin manifest](/zh-TW/plugins/manifest) - manifest 與套件中繼資料

docs/zh-TW/providers/openrouter.md

@@ -1,21 +1,21 @@
 ---
 read_when:
-    - 你想要一組可用於多種 LLM 的 API 金鑰
-    - 你想透過 OpenRouter 在 OpenClaw 中執行模型
-    - 你想使用 OpenRouter 進行影像生成
-    - 你想使用 OpenRouter 進行影片生成
-summary: 使用 OpenRouter 的統一 API，在 OpenClaw 中存取多種模型
+    - 你想要一個可用於多個 LLM 的單一 API 金鑰
+    - 你想在 OpenClaw 中透過 OpenRouter 執行模型
+    - 您想使用 OpenRouter 進行影像生成
+    - 您想使用 OpenRouter 進行影片生成
+summary: 使用 OpenRouter 的統一 API 在 OpenClaw 中存取多種模型
 title: OpenRouter
 x-i18n:
-    generated_at: "2026-05-04T02:45:38Z"
+    generated_at: "2026-05-05T01:48:43Z"
     model: gpt-5.5
     provider: openai
-    source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
+    source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244
     source_path: providers/openrouter.md
     workflow: 16
 ---
 
-OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求路由到多種模型。它與 OpenAI 相容，因此大多數 OpenAI SDK 只要切換基底 URL 即可運作。
+OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求路由到許多模型。它相容於 OpenAI，因此大多數 OpenAI SDK 只要切換基礎 URL 即可使用。
 
 ## 開始使用
 
@@ -29,7 +29,7 @@ OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求
     ```
   </Step>
   <Step title="（選用）切換到特定模型">
-    Onboarding 預設使用 `openrouter/auto`。之後可選擇具體模型：
+    Onboarding 預設為 `openrouter/auto`。稍後可選擇具體模型：
 
     ```bash
     openclaw models set openrouter/<provider>/<model>
@@ -54,19 +54,19 @@ OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求
 ## 模型參照
 
 <Note>
-模型參照遵循 `openrouter/<provider>/<model>` 模式。如需可用提供者和模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。
+模型參照遵循 `openrouter/<provider>/<model>` 模式。如需可用 provider 和模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。
 </Note>
 
-內建備援範例：
+內建後援範例：
 
 | 模型參照                          | 備註                         |
 | --------------------------------- | ---------------------------- |
 | `openrouter/auto`                 | OpenRouter 自動路由          |
 | `openrouter/moonshotai/kimi-k2.6` | 透過 MoonshotAI 使用 Kimi K2.6 |
 
-## 圖片產生
+## 圖像生成
 
-OpenRouter 也可以支援 `image_generate` 工具。在 `agents.defaults.imageGenerationModel` 下使用 OpenRouter 圖片模型：
+OpenRouter 也可以支援 `image_generate` 工具。請在 `agents.defaults.imageGenerationModel` 下使用 OpenRouter 圖像模型：
 
 ```json5
 {
@@ -82,11 +82,11 @@ OpenRouter 也可以支援 `image_generate` 工具。在 `agents.defaults.imageG
 }
 ```
 
-OpenClaw 會使用 `modalities: ["image", "text"]` 將圖片請求傳送到 OpenRouter 的聊天補全圖片 API。Gemini 圖片模型會透過 OpenRouter 的 `image_config` 接收支援的 `aspectRatio` 和 `resolution` 提示。對於速度較慢的 OpenRouter 圖片模型，請使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次呼叫的 `timeoutMs` 參數仍會優先。
+OpenClaw 會使用 `modalities: ["image", "text"]` 將圖像請求傳送到 OpenRouter 的 chat completions 圖像 API。Gemini 圖像模型會透過 OpenRouter 的 `image_config` 接收支援的 `aspectRatio` 和 `resolution` 提示。對於較慢的 OpenRouter 圖像模型，請使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次呼叫的 `timeoutMs` 參數仍會優先套用。
 
-## 影片產生
+## 影片生成
 
-OpenRouter 也可以透過其非同步 `/videos` API 支援 `video_generate` 工具。在 `agents.defaults.videoGenerationModel` 下使用 OpenRouter 影片模型：
+OpenRouter 也可以透過其非同步 `/videos` API 支援 `video_generate` 工具。請在 `agents.defaults.videoGenerationModel` 下使用 OpenRouter 影片模型：
 
 ```json5
 {
@@ -101,11 +101,11 @@ OpenRouter 也可以透過其非同步 `/videos` API 支援 `video_generate` 工
 }
 ```
 
-OpenClaw 會將文字轉影片和圖片轉影片作業提交給 OpenRouter，輪詢傳回的 `polling_url`，並從 OpenRouter 的 `unsigned_urls` 或文件化的作業內容端點下載完成的影片。參考圖片預設會作為第一/最後影格圖片傳送；標記為 `reference_image` 的圖片會作為 OpenRouter 輸入參考傳送。內建的 `google/veo-3.1-fast` 預設值宣告目前支援 4/6/8 秒時長、`720P`/`1080P` 解析度，以及 `16:9`/`9:16` 長寬比。OpenRouter 未註冊影片轉影片，因為上游影片產生 API 目前接受文字和圖片參考。
+OpenClaw 會將文字轉影片和圖像轉影片工作提交給 OpenRouter，輪詢傳回的 `polling_url`，並從 OpenRouter 的 `unsigned_urls` 或記載的工作內容端點下載完成的影片。參考圖像預設會作為首格/末格圖像傳送；標記為 `reference_image` 的圖像會作為 OpenRouter 輸入參考傳送。內建的 `google/veo-3.1-fast` 預設會宣告目前支援的 4/6/8 秒長度、`720P`/`1080P` 解析度，以及 `16:9`/`9:16` 長寬比。OpenRouter 未註冊影片轉影片，因為上游影片生成 API 目前接受文字與圖像參考。
 
 ## 文字轉語音
 
-OpenRouter 也可以透過其與 OpenAI 相容的 `/audio/speech` 端點作為 TTS 提供者使用。
+OpenRouter 也可以透過其相容 OpenAI 的 `/audio/speech` 端點作為 TTS provider 使用。
 
 ```json5
 {
@@ -125,13 +125,13 @@ OpenRouter 也可以透過其與 OpenAI 相容的 `/audio/speech` 端點作為 T
 }
 ```
 
-如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 會重用 `models.providers.openrouter.apiKey`，然後才使用 `OPENROUTER_API_KEY`。
+如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 會重用 `models.providers.openrouter.apiKey`，再使用 `OPENROUTER_API_KEY`。
 
 ## 驗證與標頭
 
-OpenRouter 底層會使用帶有你的 API 金鑰的 Bearer 權杖。
+OpenRouter 底層會使用搭配你 API 金鑰的 Bearer token。
 
-在實際 OpenRouter 請求（`https://openrouter.ai/api/v1`）中，OpenClaw 也會加入 OpenRouter 文件化的應用程式歸因標頭：
+在實際的 OpenRouter 請求（`https://openrouter.ai/api/v1`）上，OpenClaw 也會加入 OpenRouter 文件記載的應用程式歸因標頭：
 
 | 標頭                      | 值                                                                                                     |
 | ------------------------- | ------------------------------------------------------------------------------------------------------ |
@@ -140,14 +140,14 @@ OpenRouter 底層會使用帶有你的 API 金鑰的 Bearer 權杖。
 | `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` |
 
 <Warning>
-如果你將 OpenRouter 提供者重新指向其他 proxy 或基底 URL，OpenClaw **不會**注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。
+如果你將 OpenRouter provider 重新指向其他 proxy 或基礎 URL，OpenClaw **不會**注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。
 </Warning>
 
 ## 進階設定
 
 <AccordionGroup>
   <Accordion title="回應快取">
-    OpenRouter 回應快取需要選擇啟用。可使用模型參數為每個 OpenRouter 模型啟用：
+    OpenRouter 回應快取需要選擇啟用。透過模型參數為每個 OpenRouter 模型啟用：
 
     ```json5
     {
@@ -166,38 +166,38 @@ OpenRouter 底層會使用帶有你的 API 金鑰的 Bearer 權杖。
     }
     ```
 
-    OpenClaw 會傳送 `X-OpenRouter-Cache: true`，並在設定時傳送 `X-OpenRouter-Cache-TTL`。`responseCacheClear: true` 會強制重新整理目前請求，並儲存替換回應。也接受 snake_case 別名（`response_cache`、`response_cache_ttl_seconds` 和 `response_cache_clear`）。
+    OpenClaw 會傳送 `X-OpenRouter-Cache: true`，並在設定後傳送 `X-OpenRouter-Cache-TTL`。`responseCacheClear: true` 會強制重新整理目前請求並儲存替換回應。也接受 snake_case 別名（`response_cache`、`response_cache_ttl_seconds` 和 `response_cache_clear`）。
 
-    這與提供者提示快取以及 OpenRouter 的 Anthropic `cache_control` 標記不同。它只會套用在已驗證的 `openrouter.ai` 路由上，不會套用在自訂 proxy 基底 URL。
+    這與 provider prompt caching 和 OpenRouter 的 Anthropic `cache_control` 標記不同。它只會套用在已驗證的 `openrouter.ai` 路由上，而不是自訂 proxy 基礎 URL。
 
   </Accordion>
 
   <Accordion title="Anthropic 快取標記">
-    在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會使用這些標記在系統/開發者提示區塊上提升提示快取重用率。
+    在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會用這些標記在 system/developer prompt 區塊上提升 prompt-cache 重用率。
   </Accordion>
 
-  <Accordion title="Anthropic 推理預填">
-    在已驗證的 OpenRouter 路由上，啟用推理的 Anthropic 模型參照會在請求到達 OpenRouter 前移除結尾的助理預填輪次，以符合 Anthropic 對推理對話必須以使用者輪次結尾的要求。
+  <Accordion title="Anthropic reasoning 預填">
+    在已驗證的 OpenRouter 路由上，啟用 reasoning 的 Anthropic 模型參照會在請求到達 OpenRouter 前移除結尾的 assistant 預填回合，以符合 Anthropic 對 reasoning 對話必須以 user 回合結尾的要求。
   </Accordion>
 
-  <Accordion title="思考 / 推理注入">
-    在支援的非 `auto` 路由上，OpenClaw 會將選定的思考層級對應到 OpenRouter proxy 推理 payload。不支援的模型提示和 `openrouter/auto` 會略過該推理注入。Hunter Alpha 也會對過期設定的模型參照略過 proxy 推理，因為 OpenRouter 可能會針對該已淘汰路由在推理欄位中傳回最終答案文字。
+  <Accordion title="Thinking / reasoning 注入">
+    在支援的非 `auto` 路由上，OpenClaw 會將選取的 thinking 層級對應到 OpenRouter proxy reasoning payload。不支援的模型提示和 `openrouter/auto` 會略過該 reasoning 注入。Hunter Alpha 也會因為 OpenRouter 可能在該已退役路由的 reasoning 欄位中傳回最終答案文字，而對過時設定的模型參照略過 proxy reasoning。
   </Accordion>
 
-  <Accordion title="DeepSeek V4 推理重播">
-    在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的助理輪次中補上缺失的 `reasoning_content`，讓思考/工具對話保留 DeepSeek V4 所需的後續形狀。
+  <Accordion title="DeepSeek V4 reasoning 重播">
+    在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的 assistant 回合補上缺少的 `reasoning_content`，讓 thinking/tool 對話維持 DeepSeek V4 要求的後續形狀。OpenClaw 會為這些路由傳送 OpenRouter 支援的 `reasoning_effort` 值；`xhigh` 是宣告的最高層級，過時的 `max` 覆寫會對應到 `xhigh`。
   </Accordion>
 
-  <Accordion title="僅 OpenAI 的請求形塑">
-    OpenRouter 仍會透過 proxy 風格的 OpenAI 相容路徑執行，因此不會轉送原生僅 OpenAI 的請求形塑，例如 `serviceTier`、Responses `store`、OpenAI 推理相容 payload，以及提示快取提示。
+  <Accordion title="僅 OpenAI 的請求塑形">
+    OpenRouter 仍會經由 proxy 風格的 OpenAI 相容路徑執行，因此不會轉送原生僅 OpenAI 的請求塑形，例如 `serviceTier`、Responses `store`、OpenAI reasoning 相容 payload，以及 prompt-cache 提示。
   </Accordion>
 
   <Accordion title="Gemini 支援的路由">
-    Gemini 支援的 OpenRouter 參照會留在 proxy-Gemini 路徑上：OpenClaw 會在該處保留 Gemini thought-signature 清理，但不會啟用原生 Gemini 重播驗證或 bootstrap 重寫。
+    Gemini 支援的 OpenRouter 參照會維持在 proxy-Gemini 路徑上：OpenClaw 會在該處保留 Gemini thought-signature 清理，但不會啟用原生 Gemini 重播驗證或 bootstrap 重寫。
   </Accordion>
 
-  <Accordion title="提供者路由中繼資料">
-    如果你在模型參數下傳入 OpenRouter 提供者路由，OpenClaw 會在共用串流包裝器執行前，將其作為 OpenRouter 路由中繼資料轉送。
+  <Accordion title="Provider 路由中繼資料">
+    如果你在模型參數下傳遞 OpenRouter provider 路由，OpenClaw 會在共用串流包裝器執行前，將其作為 OpenRouter 路由中繼資料轉送。
   </Accordion>
 </AccordionGroup>
 
@@ -205,9 +205,9 @@ OpenRouter 底層會使用帶有你的 API 金鑰的 Bearer 權杖。
 
 <CardGroup cols={2}>
   <Card title="模型選擇" href="/zh-TW/concepts/model-providers" icon="layers">
-    選擇提供者、模型參照和容錯移轉行為。
+    選擇 provider、模型參照與容錯移轉行為。
   </Card>
   <Card title="設定參考" href="/zh-TW/gateway/configuration-reference" icon="gear">
-    agents、模型和提供者的完整設定參考。
+    agents、模型和 provider 的完整設定參考。
   </Card>
 </CardGroup>

docs/zh-TW/reference/RELEASING.md

@@ -1,162 +1,154 @@
 ---
 read_when:
-    - 正在尋找公開發布通道定義
-    - 執行發行驗證或套件驗收
-    - 尋找版本命名與發布節奏
+    - 正在尋找公開發行通道定義
+    - 執行發布驗證或套件驗收
+    - 正在尋找版本命名與發布節奏
 summary: 發布通道、操作員檢查清單、驗證環境、版本命名與節奏
 title: 發布政策
 x-i18n:
-    generated_at: "2026-05-04T07:06:01Z"
+    generated_at: "2026-05-05T01:48:44Z"
     model: gpt-5.5
     provider: openai
-    source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
+    source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3
     source_path: reference/RELEASING.md
     workflow: 16
 ---
 
-OpenClaw 有三個公開發布通道：
+OpenClaw 有三個公開發行通道：
 
-- 穩定版：已標記的發行版，預設發布到 npm `beta`，或在明確要求時發布到 npm `latest`
-- beta：發布到 npm `beta` 的預發行標籤
-- dev：`main` 的移動中最新提交
+- 穩定版：帶有標籤的發行版本，預設發布到 npm `beta`，或在明確要求時發布到 npm `latest`
+- Beta：發布到 npm `beta` 的預發行標籤
+- 開發版：`main` 的移動頭部
 
 ## 版本命名
 
 - 穩定版發行版本：`YYYY.M.D`
   - Git 標籤：`vYYYY.M.D`
-- 穩定修正版發行版本：`YYYY.M.D-N`
+- 穩定版修正發行版本：`YYYY.M.D-N`
   - Git 標籤：`vYYYY.M.D-N`
 - Beta 預發行版本：`YYYY.M.D-beta.N`
   - Git 標籤：`vYYYY.M.D-beta.N`
 - 月份或日期不要補零
-- `latest` 表示目前已晉升的穩定版 npm 發行版
-- `beta` 表示目前的 beta 安裝目標
-- 穩定版與穩定修正版發行版預設發布到 npm `beta`；發布操作員可以明確指定 `latest`，或稍後晉升已審核的 beta 組建
-- 每個穩定版 OpenClaw 發行版都會同時出貨 npm 套件與 macOS 應用程式；
-  beta 發行版通常會先驗證並發布 npm/套件路徑，
-  mac 應用程式的建置/簽署/公證則保留給穩定版，除非明確要求
+- `latest` 表示目前已提升的穩定版 npm 發行版本
+- `beta` 表示目前的 Beta 安裝目標
+- 穩定版和穩定版修正發行版本預設發布到 npm `beta`；發行操作員可以明確指定 `latest`，或稍後提升經過審核的 Beta 建置
+- 每個穩定版 OpenClaw 發行版本都會同時交付 npm 套件和 macOS 應用程式；
+  Beta 發行版本通常會先驗證並發布 npm／套件路徑，而 mac 應用程式的建置／簽署／公證則保留給穩定版，除非明確要求
 
-## 發布節奏
+## 發行節奏
 
-- 發布採 beta 優先
-- 只有在最新 beta 通過驗證後，穩定版才會接續發布
-- 維護者通常會從目前 `main` 建立的 `release/YYYY.M.D` 分支切出發行版，
-  因此發布驗證與修正不會阻擋 `main` 上的新開發
-- 如果 beta 標籤已推送或發布且需要修正，維護者會切下一個 `-beta.N` 標籤，而不是刪除或重新建立舊的 beta 標籤
-- 詳細發布程序、核准、憑證與復原備註僅限維護者使用
+- 發行採用 Beta 優先
+- 穩定版只會在最新 Beta 驗證完成後接續推出
+- 維護者通常會從目前 `main` 建立的 `release/YYYY.M.D` 分支切出發行版本，
+  因此發行驗證和修正不會阻塞 `main` 上的新開發
+- 如果 Beta 標籤已推送或發布且需要修正，維護者會切出下一個 `-beta.N` 標籤，而不是刪除或重新建立舊的 Beta 標籤
+- 詳細的發行程序、核准、憑證和復原備註僅供維護者使用
 
-## 發布操作員檢查清單
+## 發行操作員檢查清單
 
-此檢查清單是發布流程的公開形式。私有憑證、簽署、公證、dist-tag 復原與緊急回復細節保留在僅限維護者使用的發布 runbook 中。
+這份檢查清單是發行流程的公開形態。私有憑證、
+簽署、公證、dist-tag 復原和緊急回復細節會保留在
+僅供維護者使用的發行操作手冊中。
 
 1. 從目前的 `main` 開始：拉取最新內容，確認目標提交已推送，
-   並確認目前 `main` 的 CI 足夠穩定，可以從中建立分支。
+   並確認目前 `main` 的 CI 綠燈程度足以從它建立分支。
 2. 使用 `/changelog` 從真實提交歷史重寫最上方的 `CHANGELOG.md` 區段，
-   保持條目面向使用者，提交、推送，並在建立分支前再次 rebase/pull。
+   保持條目面向使用者，提交它、推送它，並在建立分支前再 rebase／pull
+   一次。
 3. 檢閱
    `src/plugins/compat/registry.ts` 和
-   `src/commands/doctor/shared/deprecation-compat.ts` 中的發布相容性記錄。只有在升級路徑仍有覆蓋時才移除已過期的
-   相容性，或記錄為何有意保留。
-4. 從目前的 `main` 建立 `release/YYYY.M.D`；不要直接在 `main` 上進行一般發布工作。
-5. 為預期標籤更新每個必要的版本位置，執行
-   `pnpm plugins:sync`，讓可發布的 Plugin 套件共享發行版本與相容性中繼資料，然後執行本機決定性預檢：
+   `src/commands/doctor/shared/deprecation-compat.ts` 中的發行相容性記錄。只有在升級路徑仍受到涵蓋時才移除過期相容性，或記錄為何刻意保留。
+4. 從目前的 `main` 建立 `release/YYYY.M.D`；不要直接在 `main` 上進行一般發行工作。
+5. 為預定標籤更新所有必要的版本位置，執行
+   `pnpm plugins:sync`，讓可發布的 Plugin 套件共用發行版本和相容性中繼資料，然後執行本機決定性預檢：
    `pnpm check:test-types`、`pnpm check:architecture`、
    `pnpm build && pnpm ui:build`、`pnpm plugins:sync:check` 和
    `pnpm release:check`。
 6. 以 `preflight_only=true` 執行 `OpenClaw NPM Release`。在標籤存在之前，
-   允許使用完整 40 字元的發布分支 SHA 進行僅驗證預檢。保存成功的 `preflight_run_id`。
-7. 對發布分支、標籤或完整提交 SHA 執行 `Full Release Validation`，啟動所有預發布測試。這是四個大型發布測試盒的唯一手動入口：
-   Vitest、Docker、QA Lab 和 Package。
-8. 如果驗證失敗，請在發布分支上修正，並重新執行能證明修正的最小失敗
-   檔案、通道、工作流程作業、套件設定檔、Provider 或模型允許清單。只有當變更的表面使先前證據過期時，才重新執行完整總括流程。
-9. 對 beta，標記 `vYYYY.M.D-beta.N`，然後從相符的 `release/YYYY.M.D` 分支執行 `OpenClaw Release Publish`。它會驗證 `pnpm plugins:sync:check`，
-   先將所有可發布的 Plugin 套件發布到 npm，再將相同集合以 ClawPack npm-pack tarball 形式發布到 ClawHub，
-   然後使用相符的 dist-tag 晉升已準備好的 OpenClaw npm 預檢成品。發布後，針對已發布的
-   `openclaw@YYYY.M.D-beta.N` 或
+   可使用完整 40 字元的發行分支 SHA 進行僅驗證預檢。儲存成功的 `preflight_run_id`。
+7. 針對發行分支、標籤或完整提交 SHA，以 `Full Release Validation`
+   啟動所有預發行測試。這是四個大型發行測試盒的唯一手動入口點：Vitest、Docker、QA Lab 和 Package。
+8. 如果驗證失敗，請在發行分支上修正，並重新執行能證明修正的最小失敗檔案、通道、工作流程工作、套件設定檔、提供者或模型允許清單。只有在變更表面使先前證據過期時，才重新執行完整 umbrella。
+9. 對於 Beta，標記 `vYYYY.M.D-beta.N`，然後從相符的 `release/YYYY.M.D` 分支執行 `OpenClaw Release Publish`。它會驗證 `pnpm plugins:sync:check`，先將所有可發布的 Plugin 套件發布到 npm，接著以 ClawPack npm-pack tarballs 的形式將同一組發布到 ClawHub，然後使用相符的 dist-tag 提升已準備好的 OpenClaw npm 預檢成品。發布後，對已發布的 `openclaw@YYYY.M.D-beta.N` 或
    `openclaw@beta` 套件執行發布後套件
-   acceptance。如果已推送或已發布的預發行需要修正，
-   請切下一個相符的預發行編號；不要刪除或重寫舊的
-   預發行。
-10. 對穩定版，只有在已審核的 beta 或發布候選版具備
-    必要驗證證據後才繼續。穩定版 npm 發布也會透過
-    `OpenClaw Release Publish`，透過
-    `preflight_run_id` 重用成功的預檢成品；穩定版 macOS 發布就緒也需要
-    `main` 上的已封裝 `.zip`、`.dmg`、`.dSYM.zip` 以及更新後的 `appcast.xml`。
-11. 發布後，執行 npm 發布後驗證器、在需要發布後通道證明時執行可選的獨立
-    published-npm Telegram E2E、
-    在需要時進行 dist-tag 晉升、從完整相符的 `CHANGELOG.md` 區段產生 GitHub 發行/預發行說明，
-    以及發布公告步驟。
+   acceptance。如果已推送或發布的預發行版本需要修正，
+   請切出下一個相符的預發行編號；不要刪除或重寫舊的
+   預發行版本。
+10. 對於穩定版，只有在經審核的 Beta 或發行候選版本具備所需驗證證據後才繼續。穩定版 npm 發布也會透過
+    `OpenClaw Release Publish`，並透過
+    `preflight_run_id` 重用成功的預檢成品；穩定版 macOS 發行準備狀態也要求 `main` 上有封裝好的 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的 `appcast.xml`。
+11. 發布後，執行 npm 發布後驗證器、在需要發布後通道證明時可選的獨立
+    已發布 npm Telegram E2E、必要時的 dist-tag 提升、從完整相符
+    `CHANGELOG.md` 區段產生的 GitHub 發行／預發行備註，以及發行公告
+    步驟。
 
-## 發布預檢
+## 發行預檢
 
-- 發布預檢前先執行 `pnpm check:test-types`，讓測試 TypeScript 在較快的本機 `pnpm check` 閘門之外仍受到涵蓋
-- 發布預檢前先執行 `pnpm check:architecture`，讓更廣泛的匯入循環與架構邊界檢查在較快的本機閘門之外保持綠燈
-- 在 `pnpm release:check` 前先執行 `pnpm build && pnpm ui:build`，讓預期的 `dist/*` 發布成品與 Control UI bundle 存在，以供封裝驗證步驟使用
-- 在根版本升級後、標記前執行 `pnpm plugins:sync`。它會更新可發布的 Plugin 套件版本、OpenClaw peer/API 相容性中繼資料、建置中繼資料，以及 Plugin 變更記錄 stub，以符合核心發布版本。`pnpm plugins:sync:check` 是不變更檔案的發布守衛；如果忘記此步驟，發布工作流程會在任何 registry 變更前失敗。
-- 在發布核准前執行手動 `Full Release Validation` 工作流程，從單一進入點啟動所有預發布測試盒。它接受分支、標籤或完整 commit SHA，分派手動 `CI`，並分派 `OpenClaw Release Checks`，涵蓋安裝 smoke、套件接受度、Docker 發布路徑套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 與 Telegram lane。使用 `release_profile=full` 和 `rerun_group=all` 時，它也會針對來自發布檢查的 `release-package-under-test` 成品執行套件 Telegram E2E。發布後提供 `npm_telegram_package_spec`，可讓同一個 Telegram E2E 也驗證已發布的 npm 套件。發布後提供 `package_acceptance_package_spec`，可讓 Package Acceptance 對已出貨的 npm 套件執行其套件/更新矩陣，而不是針對以 SHA 建置的成品執行。提供 `evidence_package_spec` 時，私有證據報告可證明驗證符合已發布的 npm 套件，而不強制執行 Telegram E2E。
-  範例：
-  `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
-- 當你想在發布工作繼續進行時，為套件候選版本取得旁路證據，請執行手動 `Package Acceptance` 工作流程。對 `openclaw@beta`、`openclaw@latest` 或精確發布版本使用 `source=npm`；使用 `source=ref` 以目前的 `workflow_ref` harness 封裝受信任的 `package_ref` 分支/標籤/SHA；對需要 SHA-256 的 HTTPS tarball 使用 `source=url`；或對另一個 GitHub Actions run 上傳的 tarball 使用 `source=artifact`。工作流程會將候選項解析為 `package-under-test`，重用 Docker E2E 發布排程器針對該 tarball 執行，並可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 對同一個 tarball 執行 Telegram QA。當所選 Docker lane 包含 `published-upgrade-survivor` 時，套件成品就是候選項，而 `published_upgrade_survivor_baseline` 會選擇已發布的基準。
+- 在發布預檢前執行 `pnpm check:test-types`，讓測試 TypeScript 在較快的本機 `pnpm check` 閘門之外也持續涵蓋
+- 在發布預檢前執行 `pnpm check:architecture`，讓更廣泛的匯入循環與架構邊界檢查在較快的本機閘門之外保持綠燈
+- 在執行 `pnpm release:check` 前執行 `pnpm build && pnpm ui:build`，讓預期的 `dist/*` 發布成品與 Control UI bundle 存在，供封裝驗證步驟使用
+- 在根版本升級後、標記前執行 `pnpm plugins:sync`。它會更新可發布的 Plugin package 版本、OpenClaw peer/API 相容性中繼資料、建置中繼資料，以及 Plugin 變更記錄 stub，以符合核心發布版本。`pnpm plugins:sync:check` 是不變更檔案的發布防護；如果忘記此步驟，發布 workflow 會在任何 registry 變更前失敗。
+- 在發布核准前執行手動 `Full Release Validation` workflow，從單一進入點啟動所有發布前測試盒。它接受分支、標籤或完整 commit SHA，會派發手動 `CI`，並派發 `OpenClaw Release Checks` 來執行安裝 smoke、package acceptance、跨 OS package 檢查、QA Lab parity、Matrix 與 Telegram lanes。Stable/default 執行會將完整 live/E2E 與 Docker 發布路徑 soak 保留在 `run_release_soak=true` 之後；`release_profile=full` 會強制啟用 soak。搭配 `release_profile=full` 與 `rerun_group=all` 時，它也會針對 release checks 產生的 `release-package-under-test` artifact 執行 package Telegram E2E。發布後，若同一個 Telegram E2E 也應驗證已發布的 npm package，請提供 `npm_telegram_package_spec`。發布後，若 Package Acceptance 應針對已出貨的 npm package 而非 SHA 建置 artifact 執行其 package/update 矩陣，請提供 `package_acceptance_package_spec`。若 private evidence report 應證明驗證符合已發布的 npm package，而不強制 Telegram E2E，請提供 `evidence_package_spec`。範例：`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
+- 當你想在發布工作繼續進行時，為 package 候選版本取得旁路證明，請執行手動 `Package Acceptance` workflow。針對 `openclaw@beta`、`openclaw@latest` 或精確發布版本使用 `source=npm`；若要用目前的 `workflow_ref` harness 封裝受信任的 `package_ref` 分支/標籤/SHA，使用 `source=ref`；針對需要 SHA-256 的 HTTPS tarball，使用 `source=url`；或針對另一個 GitHub Actions 執行上傳的 tarball，使用 `source=artifact`。該 workflow 會將候選版本解析為 `package-under-test`，針對該 tarball 重用 Docker E2E 發布排程器，並可用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 針對同一 tarball 執行 Telegram QA。當選取的 Docker lanes 包含 `published-upgrade-survivor` 時，package artifact 是候選版本，而 `published_upgrade_survivor_baseline` 會選取已發布的 baseline。
   範例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
-  常見設定檔：
-  - `smoke`：安裝/channel/agent、Gateway 網路與 config reload lane
-  - `package`：成品原生的套件/更新/Plugin lane，不包含 OpenWebUI 或 live ClawHub
-  - `product`：套件設定檔加上 MCP channels、cron/subagent cleanup、OpenAI web search 與 OpenWebUI
-  - `full`：包含 OpenWebUI 的 Docker 發布路徑區塊
-  - `custom`：用於聚焦重跑的精確 `docker_lanes` 選擇
-- 當你只需要發布候選版本的完整一般 CI 覆蓋時，直接執行手動 `CI` 工作流程。手動 CI 分派會略過 changed scoping，並強制執行 Linux Node shards、bundled-plugin shards、channel contracts、Node 22 相容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android 與 Control UI i18n lane。
+  常用 profile：
+  - `smoke`：安裝/channel/agent、Gateway 網路與設定重新載入 lanes
+  - `package`：artifact 原生 package/update/Plugin lanes，不包含 OpenWebUI 或 live ClawHub
+  - `product`：package profile 加上 MCP channels、cron/subagent cleanup、OpenAI web search 與 OpenWebUI
+  - `full`：含 OpenWebUI 的 Docker 發布路徑 chunks
+  - `custom`：用於聚焦重新執行的精確 `docker_lanes` 選取
+- 當你只需要發布候選版本的一般完整 CI 涵蓋時，請直接執行手動 `CI` workflow。手動 CI 派發會略過 changed scoping，並強制執行 Linux Node shards、bundled-Plugin shards、channel contracts、Node 22 相容性、`check`、`check-additional`、build smoke、docs checks、Python Skills、Windows、macOS、Android 與 Control UI i18n lanes。
   範例：`gh workflow run ci.yml --ref release/YYYY.M.D`
-- 驗證發布遙測時執行 `pnpm qa:otel:smoke`。它會透過本機 OTLP/HTTP receiver 演練 QA-lab，並驗證匯出的 trace span 名稱、有界屬性，以及內容/識別碼遮蔽，不需要 Opik、Langfuse 或其他外部 collector。
+- 驗證發布遙測時執行 `pnpm qa:otel:smoke`。它會透過本機 OTLP/HTTP receiver 執行 QA-lab，並驗證匯出的 trace span 名稱、有界屬性，以及內容/識別碼遮蔽，且不需要 Opik、Langfuse 或其他外部 collector。
 - 每次標記發布前執行 `pnpm release:check`
-- 標籤存在後，為會變更狀態的發布序列執行 `OpenClaw Release Publish`。從 `release/YYYY.M.D` 分派它（或在發布 main 可到達標籤時從 `main` 分派），傳入發布標籤與成功的 OpenClaw npm `preflight_run_id`，並保留預設 Plugin 發布範圍 `all-publishable`，除非你刻意執行聚焦修復。工作流程會序列化 Plugin npm publish、Plugin ClawHub publish 與 OpenClaw npm publish，確保核心套件不會在其外部化 Plugin 之前發布。
-- 發布檢查現在於獨立的手動工作流程中執行：
-  `OpenClaw Release Checks`
-- `OpenClaw Release Checks` 也會在發布核准前執行 QA Lab mock parity lane，加上快速 live Matrix profile 與 Telegram QA lane。live lane 使用 `qa-live-shared` 環境；Telegram 也使用 Convex CI credential lease。當你想平行取得完整 Matrix transport、media 與 E2EE inventory 時，請使用 `matrix_profile=all` 和 `matrix_shards=true` 執行手動 `QA-Lab - All Lanes` 工作流程。
-- 跨 OS 安裝與升級執行階段驗證是公開 `OpenClaw Release Checks` 與 `Full Release Validation` 的一部分，這些工作流程會直接呼叫可重用工作流程 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
-- 這個拆分是刻意設計的：讓真正的 npm 發布路徑保持短、確定且聚焦於成品，同時讓較慢的 live 檢查保留在自己的 lane 中，避免拖慢或阻擋發布
-- 帶有 secret 的發布檢查應透過 `Full Release Validation` 或從 `main`/release 工作流程 ref 分派，讓工作流程邏輯與 secret 維持受控
-- `OpenClaw Release Checks` 接受分支、標籤或完整 commit SHA，只要解析出的 commit 可從 OpenClaw 分支或發布標籤到達
-- `OpenClaw NPM Release` 僅驗證預檢也接受目前完整 40 字元工作流程分支 commit SHA，不需要已推送的標籤
-- 該 SHA 路徑僅供驗證，不能提升為真正發布
-- 在 SHA 模式中，工作流程只會為套件中繼資料檢查合成 `v<package.json version>`；真正發布仍需要真正的發布標籤
-- 兩個工作流程都讓真正的發布與提升路徑維持在 GitHub-hosted runner 上，而不變更狀態的驗證路徑可以使用較大的 Blacksmith Linux runner
-- 該工作流程會使用 `OPENAI_API_KEY` 與 `ANTHROPIC_API_KEY` 工作流程 secret 執行 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
-- npm 發布預檢不再等待獨立的發布檢查 lane
-- 核准前執行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或相符的 beta/correction 標籤）
-- npm 發布後，執行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或相符的 beta/correction 版本），在全新的暫時 prefix 中驗證已發布的 registry 安裝路徑
-- beta 發布後，執行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享租借的 Telegram credential pool，針對已發布的 npm 套件驗證已安裝套件 onboarding、Telegram 設定與真正的 Telegram E2E。本機 maintainer 的一次性執行可省略 Convex vars，並直接傳入三個 `OPENCLAW_QA_TELEGRAM_*` env credentials。
-- 若要從 maintainer 機器執行完整的發布後 beta smoke，請使用 `pnpm release:beta-smoke -- --beta betaN`。helper 會執行 Parallels npm update/fresh-target 驗證、分派 `NPM Telegram Beta E2E`、輪詢精確的工作流程 run、下載成品，並列印 Telegram 報告。
-- Maintainer 可以透過手動 `NPM Telegram Beta E2E` 工作流程，從 GitHub Actions 執行相同的發布後檢查。它刻意設為僅手動，不會在每次合併時執行。
-- Maintainer 發布自動化現在使用 preflight-then-promote：
-  - 真正的 npm publish 必須通過成功的 npm `preflight_run_id`
-  - 真正的 npm publish 必須從與成功預檢 run 相同的 `main` 或 `release/YYYY.M.D` 分支分派
-  - 穩定 npm 發布預設為 `beta`
-  - 穩定 npm publish 可透過工作流程輸入明確指定 `latest`
-  - 基於 token 的 npm dist-tag 變更現在位於 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，基於安全性，因為 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公開 repo 保持僅 OIDC publish
-  - 公開 `macOS Release` 僅供驗證；當標籤只存在於發布分支但工作流程從 `main` 分派時，設定 `public_release_branch=release/YYYY.M.D`
-  - 真正的私有 mac publish 必須通過成功的私有 mac `preflight_run_id` 與 `validate_run_id`
-  - 真正的發布路徑會提升已準備的成品，而不是再次重建它們
-- 對於像 `YYYY.M.D-N` 這樣的穩定修正發布，發布後 verifier 也會檢查從 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同暫時 prefix 升級路徑，避免發布修正悄悄讓較舊的全域安裝停留在基礎穩定 payload
-- npm 發布預檢預設失敗關閉，除非 tarball 同時包含 `dist/control-ui/index.html` 與非空的 `dist/control-ui/assets/` payload，避免再次出貨空的瀏覽器 dashboard
-- 發布後驗證也會檢查已發布的 Plugin entrypoint 與套件中繼資料是否存在於已安裝的 registry 版面中。若發布缺少 Plugin 執行階段 payload，會讓 postpublish verifier 失敗，且不能提升到 `latest`。
-- `pnpm test:install:smoke` 也會在候選更新 tarball 上強制執行 npm pack `unpackedSize` 預算，因此 installer e2e 會在發布 publish 路徑前捕捉意外的 pack 膨脹
-- 如果發布工作觸及 CI 規劃、Plugin timing manifests 或 Plugin test matrices，請在核准前重新產生並審查由 planner 擁有、來自 `.github/workflows/plugin-prerelease.yml` 的 `plugin-prerelease-extension-shard` matrix outputs，避免發布說明描述過期的 CI 版面
-- 穩定 macOS 發布就緒也包含 updater surfaces：
-  - GitHub release 最終必須包含已封裝的 `.zip`、`.dmg` 與 `.dSYM.zip`
-  - 發布後 `main` 上的 `appcast.xml` 必須指向新的穩定 zip
-  - 已封裝 app 必須保持非 debug bundle id、非空 Sparkle feed URL，以及等於或高於該發布版本 canonical Sparkle build floor 的 `CFBundleVersion`
+- 標籤存在後，執行 `OpenClaw Release Publish` 以進行會變更狀態的發布序列。從 `release/YYYY.M.D` 派發它（或在發布 main 可到達標籤時從 `main` 派發），傳入發布標籤與成功的 OpenClaw npm `preflight_run_id`，並保留預設 Plugin 發布範圍 `all-publishable`，除非你刻意執行聚焦修復。該 workflow 會序列化 Plugin npm publish、Plugin ClawHub publish 與 OpenClaw npm publish，避免核心 package 在其外部化 Plugins 之前發布。
+- Release checks 現在在個別的手動 workflow 中執行：`OpenClaw Release Checks`
+- `OpenClaw Release Checks` 也會在發布核准前執行 QA Lab mock parity lane，加上快速 live Matrix profile 與 Telegram QA lane。live lanes 使用 `qa-live-shared` environment；Telegram 也使用 Convex CI credential leases。當你想並行取得完整 Matrix transport、media 與 E2EE inventory 時，請使用 `matrix_profile=all` 與 `matrix_shards=true` 執行手動 `QA-Lab - All Lanes` workflow。
+- 跨 OS 安裝與升級 runtime 驗證是公開 `OpenClaw Release Checks` 與 `Full Release Validation` 的一部分，它們會直接呼叫可重用 workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
+- 這項拆分是刻意設計：保持真實 npm 發布路徑短、可預測且聚焦於 artifact，同時讓較慢的 live checks 留在自己的 lane 中，避免拖慢或阻擋發布
+- 帶有 secret 的 release checks 應透過 `Full Release Validation` 或從 `main`/release workflow ref 派發，讓 workflow 邏輯與 secrets 維持受控
+- `OpenClaw Release Checks` 接受分支、標籤或完整 commit SHA，只要解析出的 commit 可從 OpenClaw 分支或發布標籤到達即可
+- `OpenClaw NPM Release` 的 validation-only preflight 也接受目前完整 40 字元的 workflow-branch commit SHA，不需要已推送的標籤
+- 該 SHA 路徑僅供驗證，不能提升為真實發布
+- 在 SHA 模式中，workflow 只會為 package metadata check 合成 `v<package.json version>`；真實發布仍需要真正的發布標籤
+- 兩個 workflow 都讓真實 publish 與 promotion 路徑在 GitHub-hosted runners 上執行，而不變更狀態的驗證路徑可以使用較大的 Blacksmith Linux runners
+- 該 workflow 會使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`，並搭配 `OPENAI_API_KEY` 與 `ANTHROPIC_API_KEY` workflow secrets
+- npm release preflight 不再等待個別的 release checks lane
+- 在核准前執行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或對應的 beta/correction 標籤）
+- npm publish 後，執行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或對應的 beta/correction 版本），在全新的 temp prefix 中驗證已發布 registry 安裝路徑
+- beta publish 後，執行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共用租借 Telegram credential pool，針對已發布 npm package 驗證已安裝 package 的 onboarding、Telegram 設定與真實 Telegram E2E。本機 maintainer 一次性執行可以省略 Convex vars，並直接傳入三個 `OPENCLAW_QA_TELEGRAM_*` env credentials。
+- 若要從 maintainer 機器執行完整的 post-publish beta smoke，請使用 `pnpm release:beta-smoke -- --beta betaN`。此 helper 會執行 Parallels npm update/fresh-target 驗證、派發 `NPM Telegram Beta E2E`、輪詢精確 workflow run、下載 artifact，並列印 Telegram report。
+- Maintainers 可透過手動 `NPM Telegram Beta E2E` workflow，從 GitHub Actions 執行相同的 post-publish 檢查。它刻意設為僅手動執行，不會在每次 merge 時執行。
+- Maintainer release automation 現在使用 preflight-then-promote：
+  - 真實 npm publish 必須通過成功的 npm `preflight_run_id`
+  - 真實 npm publish 必須從與成功 preflight run 相同的 `main` 或 `release/YYYY.M.D` 分支派發
+  - stable npm releases 預設為 `beta`
+  - stable npm publish 可透過 workflow input 明確指定 `latest`
+  - token-based npm dist-tag 變更現在位於 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，這是基於安全性考量，因為 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而 public repo 保持 OIDC-only publish
+  - public `macOS Release` 僅供驗證；當標籤只存在於 release branch，但 workflow 從 `main` 派發時，設定 `public_release_branch=release/YYYY.M.D`
+  - 真實 private mac publish 必須通過成功的 private mac `preflight_run_id` 與 `validate_run_id`
+  - 真實 publish 路徑會提升已準備好的 artifact，而不是再次重建它們
+- 對於 `YYYY.M.D-N` 這類 stable correction releases，post-publish verifier 也會檢查從 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同 temp-prefix 升級路徑，避免 release corrections 靜默地讓較舊的全域安裝停留在基礎 stable payload
+- npm release preflight 會 fail closed，除非 tarball 同時包含 `dist/control-ui/index.html` 與非空的 `dist/control-ui/assets/` payload，這樣我們才不會再次出貨空的瀏覽器 dashboard
+- Post-publish verification 也會檢查已發布 Plugin 進入點與 package metadata 是否存在於已安裝的 registry layout 中。若某次發布缺少 Plugin runtime payloads，postpublish verifier 會失敗，且不能提升為 `latest`。
+- `pnpm test:install:smoke` 也會在 candidate update tarball 上強制執行 npm pack `unpackedSize` 預算，因此 installer e2e 能在 release publish 路徑前捕捉意外的 pack 膨脹
+- 如果發布工作觸及 CI planning、extension timing manifests 或 extension test matrices，請在核准前重新產生並審閱 planner-owned `plugin-prerelease-extension-shard` matrix outputs，來源為 `.github/workflows/plugin-prerelease.yml`，讓 release notes 不會描述過時的 CI layout
+- Stable macOS release readiness 也包含 updater surfaces：
+  - GitHub release 最終必須包含封裝好的 `.zip`、`.dmg` 與 `.dSYM.zip`
+  - `main` 上的 `appcast.xml` 必須在發布後指向新的 stable zip
+  - 封裝好的 app 必須保留 non-debug bundle id、非空 Sparkle feed URL，以及等於或高於該 release version 正規 Sparkle build floor 的 `CFBundleVersion`
 
 ## 發布測試盒
 
-`Full Release Validation` 是操作員從單一進入點啟動所有預發布測試的方式。若要在快速移動的分支上取得 pinned commit 證明，請使用 helper，讓每個子工作流程都從固定於目標 SHA 的暫時分支執行：
+`Full Release Validation` 是操作者從單一進入點啟動所有發布前測試的方式。若要在快速移動分支上取得 pinned commit proof，請使用 helper，讓每個 child workflow 都從固定於目標 SHA 的暫時分支執行：
 
 ```bash
 pnpm ci:full-release --sha <full-sha>
 ```
 
-helper 會推送 `release-ci/<sha>-...`，從該分支分派 `Full Release Validation` 並設定 `ref=<sha>`，驗證每個子工作流程的 `headSha` 都符合目標，然後刪除暫時分支。這可避免意外證明較新的 `main` 子 run。
+該 helper 會推送 `release-ci/<sha>-...`，從該分支派發 `Full Release Validation` 並帶入 `ref=<sha>`，驗證每個 child workflow 的 `headSha` 都符合目標，然後刪除暫時分支。這可避免意外證明了較新的 `main` child run。
 
-若要驗證發布分支或標籤，請從受信任的 `main` 工作流程 ref 執行，並將發布分支或標籤作為 `ref` 傳入：
+若要驗證 release branch 或 tag，請從受信任的 `main` workflow ref 執行，並將 release branch 或 tag 作為 `ref` 傳入：
 
 ```bash
 gh workflow run full-release-validation.yml \
@@ -168,21 +160,23 @@ gh workflow run full-release-validation.yml \
   -f evidence_package_spec=openclaw@YYYY.M.D-beta.N
 ```
 
-工作流程會解析目標 ref、以 `target_ref=<release-ref>` 觸發手動 `CI`、觸發 `OpenClaw Release Checks`、為面向套件的檢查準備父層 `release-package-under-test` 成品，並且在 `release_profile=full` 且 `rerun_group=all` 時，或設定了 `npm_telegram_package_spec` 時，觸發獨立套件 Telegram E2E。接著 `OpenClaw Release Checks` 會展開安裝冒煙測試、跨作業系統發行檢查、即時/E2E Docker 發行路徑涵蓋、含 Telegram 套件 QA 的 Package Acceptance、QA Lab 同等性、即時 Matrix，以及即時 Telegram。只有當 `Full Release Validation` 摘要顯示 `normal_ci` 和 `release_checks` 成功時，完整執行才可接受。在 full/all 模式中，`npm_telegram` 子項也必須成功；在 full/all 之外，除非提供了已發布的 `npm_telegram_package_spec`，否則會略過。最終驗證器摘要包含每個子執行的最慢工作表格，因此發行管理者無需下載日誌即可看到目前的關鍵路徑。
-如需完整階段矩陣、精確工作流程工作名稱、stable 與 full profile 差異、成品，以及聚焦重新執行控制代碼，請參閱[完整發行驗證](/zh-TW/reference/full-release-validation)。
-子工作流程會從執行 `Full Release Validation` 的受信任 ref 觸發，通常是 `--ref main`，即使目標 `ref` 指向較舊的發行分支或標籤也一樣。沒有單獨的 Full Release Validation workflow-ref 輸入；請透過選擇工作流程執行 ref 來選擇受信任的測試框架。
-不要在移動中的 `main` 上使用 `--ref main -f ref=<sha>` 取得精確提交證明；原始提交 SHA 不能作為工作流程觸發 ref，因此請使用 `pnpm ci:full-release --sha <sha>` 建立固定的暫時分支。
+工作流程會解析目標 ref，以 `target_ref=<release-ref>` 觸發手動 `CI`，觸發 `OpenClaw Release Checks`，為面向套件的檢查準備父層 `release-package-under-test` artifact，並在 `release_profile=full` 且 `rerun_group=all` 時，或設定了 `npm_telegram_package_spec` 時，觸發獨立的套件 Telegram E2E。接著 `OpenClaw Release
+Checks` 會展開安裝冒煙測試、跨作業系統發布檢查、啟用 soak 時的 live/E2E Docker 發布路徑涵蓋、含 Telegram 套件 QA 的 Package Acceptance、QA Lab parity、live Matrix，以及 live Telegram。完整執行只有在 `Full Release Validation` 摘要顯示 `normal_ci` 和 `release_checks` 成功時才可接受。在 full/all 模式中，`npm_telegram` 子項也必須成功；在 full/all 之外，除非提供了已發布的 `npm_telegram_package_spec`，否則會略過。最終驗證器摘要會包含每個子執行的最慢工作表格，讓發布管理者不必下載日誌即可查看目前的關鍵路徑。
+完整階段矩陣、確切工作流程工作名稱、stable 與 full profile 差異、artifact，以及聚焦重新執行控制代碼，請參閱[完整發布驗證](/zh-TW/reference/full-release-validation)。
+子工作流程會從執行 `Full Release
+Validation` 的可信任 ref 觸發，通常是 `--ref main`，即使目標 `ref` 指向較舊的發布分支或標籤也是如此。沒有單獨的 Full Release Validation workflow-ref 輸入；請透過選擇工作流程執行 ref 來選擇可信任的 harness。不要在移動中的 `main` 上使用 `--ref main -f ref=<sha>` 作為精確 commit 證明；原始 commit SHA 不能作為 workflow dispatch ref，因此請使用 `pnpm ci:full-release --sha <sha>` 建立固定的臨時分支。
 
-使用 `release_profile` 選擇即時/提供者涵蓋範圍：
+使用 `release_profile` 選擇 live/provider 廣度：
 
-- `minimum`：最快速的發行關鍵 OpenAI/core 即時與 Docker 路徑
-- `stable`：minimum 加上發行核准所需的穩定提供者/後端涵蓋
-- `full`：stable 加上廣泛的諮詢型提供者/媒體涵蓋
+- `minimum`：最快的發布關鍵 OpenAI/core live 與 Docker 路徑
+- `stable`：minimum 加上用於發布核准的穩定 provider/backend 涵蓋
+- `full`：stable 加上廣泛的 advisory provider/media 涵蓋
 
-`OpenClaw Release Checks` 會使用受信任的工作流程 ref，將目標 ref 解析一次為 `release-package-under-test`，並在發行路徑 Docker 檢查與 Package Acceptance 中重複使用該成品。這讓所有面向套件的機器使用相同位元組，並避免重複建置套件。
-跨作業系統 OpenAI 安裝冒煙測試會在設定 repo/org 變數時使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因為這條路徑是在證明套件安裝、onboarding、gateway 啟動，以及一次即時 agent 回合，而不是對最慢的預設模型進行基準測試。更廣泛的即時提供者矩陣仍然是模型特定涵蓋的地方。
+當發布阻斷 lane 已綠燈，且你想在升版前執行詳盡的 live/E2E、Docker 發布路徑，以及 all-since-2026.4.23 upgrade-survivor 掃描時，請搭配 `stable` 使用 `run_release_soak=true`。`full` 會隱含 `run_release_soak=true`。
 
-依照發行階段使用這些變體：
+`OpenClaw Release Checks` 會使用可信任的工作流程 ref，將目標 ref 解析一次為 `release-package-under-test`，並在 soak 執行時於跨作業系統、Package Acceptance，以及發布路徑 Docker 檢查中重用該 artifact。這能讓所有面向套件的 box 使用相同 bytes，並避免重複建置套件。跨作業系統 OpenAI 安裝冒煙測試會在 repo/org 變數已設定時使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因為此 lane 是在證明套件安裝、onboarding、gateway 啟動，以及一次 live agent 回合，而不是針對最慢的預設模型進行 benchmark。更廣泛的 live provider 矩陣仍是模型特定涵蓋的所在。
+
+根據發布階段使用這些變體：
 
 ```bash
 # Validate an unpublished release candidate branch.
@@ -212,23 +206,22 @@ gh workflow run full-release-validation.yml \
   -f npm_telegram_provider_mode=mock-openai
 ```
 
-不要將完整 umbrella 用作聚焦修正後的第一次重新執行。如果某台機器失敗，請將失敗的子工作流程、工作、Docker 路徑、套件 profile、模型提供者，或 QA 路徑用於下一次證明。只有當修正變更了共享發行協調，或讓先前全部機器的證據過期時，才再次執行完整 umbrella。umbrella 的最終驗證器會重新檢查記錄的子工作流程執行 id，因此在子工作流程成功重新執行後，只需重新執行失敗的 `Verify full validation` 父工作。
+不要在聚焦修正後第一次重新執行時使用完整 umbrella。如果某個 box 失敗，請使用失敗的子工作流程、工作、Docker lane、套件 profile、模型 provider，或 QA lane 作為下一次證明。只有在修正變更了共用發布 orchestration，或讓先前的全 box 證據過期時，才再次執行完整 umbrella。umbrella 的最終驗證器會重新檢查記錄的子工作流程執行 ID，因此在子工作流程成功重新執行後，只需重新執行失敗的父工作 `Verify full validation`。
 
-若要進行有界復原，請將 `rerun_group` 傳給 umbrella。`all` 是真正的發行候選執行，`ci` 只執行一般 CI 子項，`plugin-prerelease` 只執行僅發行使用的 plugin 子項，`release-checks` 執行每個發行機器，而較窄的發行群組是 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。
-聚焦的 `npm-telegram` 重新執行需要 `npm_telegram_package_spec`；使用 `release_profile=full` 的 full/all 執行會使用 release-checks 套件成品。
+若要進行有界恢復，請將 `rerun_group` 傳給 umbrella。`all` 是真正的 release-candidate 執行，`ci` 只執行一般 CI 子項，`plugin-prerelease` 只執行僅發布用 Plugin 子項，`release-checks` 會執行每個發布 box，而較窄的發布群組為 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。聚焦的 `npm-telegram` 重新執行需要 `npm_telegram_package_spec`；使用 `release_profile=full` 的 full/all 執行會使用 release-checks 套件 artifact。聚焦的跨作業系統重新執行可加入 `cross_os_suite_filter=windows/packaged-upgrade` 或其他作業系統/套件篩選器。QA release-check 失敗屬於 advisory；僅 QA 失敗不會阻斷發布驗證。
 
 ### Vitest
 
-Vitest 機器是手動 `CI` 子工作流程。手動 CI 會刻意繞過變更範圍界定，並強制對發行候選執行一般測試圖：Linux Node shards、bundled-plugin shards、channel contracts、Node 22 compatibility、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android，以及 Control UI i18n。
+Vitest box 是手動 `CI` 子工作流程。手動 CI 會刻意略過變更範圍界定，並強制對 release candidate 執行一般測試圖：Linux Node shard、bundled-plugin shard、channel contract、Node 22 相容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android，以及 Control UI i18n。
 
-使用這台機器回答「原始碼樹是否通過完整的一般測試套件？」這不同於發行路徑產品驗證。要保留的證據：
+使用此 box 回答「原始碼樹是否通過完整的一般測試套件？」它與發布路徑產品驗證不同。需要保留的證據：
 
 - 顯示已觸發 `CI` 執行 URL 的 `Full Release Validation` 摘要
-- 精確目標 SHA 上為綠燈的 `CI` 執行
-- 調查回歸時來自 CI 工作的失敗或緩慢 shard 名稱
-- 當執行需要效能分析時，保留 Vitest 計時成品，例如 `.artifacts/vitest-shard-timings.json`
+- `CI` 執行在確切目標 SHA 上為綠燈
+- 調查回歸時的失敗或緩慢 shard 名稱，來自 CI 工作
+- 需要效能分析時的 Vitest timing artifact，例如 `.artifacts/vitest-shard-timings.json`
 
-只有當發行需要確定性的一般 CI，但不需要 Docker、QA Lab、即時、跨作業系統或套件機器時，才直接執行手動 CI：
+只有在發布需要確定性的一般 CI，但不需要 Docker、QA Lab、live、跨作業系統或套件 box 時，才直接執行手動 CI：
 
 ```bash
 gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@@ -236,51 +229,59 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
 
 ### Docker
 
-Docker 機器位於 `OpenClaw Release Checks` 中，透過 `openclaw-live-and-e2e-checks-reusable.yml` 加上發行模式 `install-smoke` 工作流程。它會透過封裝的 Docker 環境驗證發行候選，而不只是原始碼層級測試。
+Docker box 位於 `OpenClaw Release Checks` 中，透過 `openclaw-live-and-e2e-checks-reusable.yml` 以及 release-mode `install-smoke` 工作流程執行。它會透過 packaged Docker 環境驗證 release candidate，而不只是原始碼層級測試。
 
-發行 Docker 涵蓋包括：
+發布 Docker 涵蓋包含：
 
-- 啟用緩慢 Bun 全域安裝冒煙測試的完整安裝冒煙測試
-- 依目標 SHA 準備/重複使用 root Dockerfile 冒煙映像，QR、root/gateway，以及 installer/Bun 冒煙工作會作為獨立 install-smoke shard 執行
-- repository E2E 路徑
-- 發行路徑 Docker 區塊：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g` 和 `plugins-runtime-install-h`
-- 要求時，在 `plugins-runtime-services` 區塊內提供 OpenWebUI 涵蓋
-- 分拆的 bundled plugin 安裝/解除安裝路徑，從 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23`
-- 當發行檢查包含即時套件時的即時/E2E 提供者套件與 Docker 即時模型涵蓋
+- 啟用緩慢 Bun global install smoke 的完整安裝冒煙測試
+- 依目標 SHA 準備/重用根 Dockerfile smoke image，並將 QR、root/gateway，以及 installer/Bun smoke 工作作為獨立 install-smoke shard 執行
+- repository E2E lane
+- 發布路徑 Docker chunk：`core`、`package-update-openai`、
+  `package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、
+  `plugins-runtime-services`、
+  `plugins-runtime-install-a`、`plugins-runtime-install-b`、
+  `plugins-runtime-install-c`、`plugins-runtime-install-d`、
+  `plugins-runtime-install-e`、`plugins-runtime-install-f`、
+  `plugins-runtime-install-g` 和 `plugins-runtime-install-h`
+- 要求時，在 `plugins-runtime-services` chunk 內的 OpenWebUI 涵蓋
+- 分割的 bundled Plugin 安裝/解除安裝 lane
+  `bundled-plugin-install-uninstall-0` 到
+  `bundled-plugin-install-uninstall-23`
+- 當發布檢查包含 live suite 時的 live/E2E provider suite 與 Docker live model 涵蓋
 
-重新執行前先使用 Docker 成品。發行路徑排程器會上傳 `.artifacts/docker-tests/`，其中包含路徑日誌、`summary.json`、`failures.json`、階段計時、排程器計畫 JSON，以及重新執行命令。若要聚焦復原，請在可重用的即時/E2E 工作流程上使用 `docker_lanes=<lane[,lane]>`，而不是重新執行所有發行區塊。產生的重新執行命令會在可用時包含先前的 `package_artifact_run_id` 和已準備的 Docker 映像輸入，因此失敗路徑可以重複使用相同 tarball 和 GHCR 映像。
+重新執行前請先使用 Docker artifact。發布路徑 scheduler 會上傳 `.artifacts/docker-tests/`，其中含 lane 日誌、`summary.json`、`failures.json`、階段 timing、scheduler plan JSON，以及重新執行命令。若要聚焦恢復，請在可重用 live/E2E 工作流程上使用 `docker_lanes=<lane[,lane]>`，而不是重新執行所有發布 chunk。產生的重新執行命令會在可用時包含先前的 `package_artifact_run_id` 和已準備的 Docker image 輸入，因此失敗的 lane 可以重用相同 tarball 和 GHCR image。
 
 ### QA Lab
 
-QA Lab 機器也是 `OpenClaw Release Checks` 的一部分。它是 agentic 行為與 channel 層級的發行閘門，獨立於 Vitest 和 Docker 套件機制。
+QA Lab box 也是 `OpenClaw Release Checks` 的一部分。它是 agentic 行為與 channel 層級的發布 gate，獨立於 Vitest 和 Docker 套件機制。
 
-發行 QA Lab 涵蓋包括：
+發布 QA Lab 涵蓋包含：
 
-- 使用 agentic parity pack，將 OpenAI 候選路徑與 Opus 4.6 基準線比較的 mock 同等性路徑
-- 使用 `qa-live-shared` 環境的快速即時 Matrix QA profile
-- 使用 Convex CI 憑證租約的即時 Telegram QA 路徑
-- 當發行遙測需要明確本機證明時的 `pnpm qa:otel:smoke`
+- 使用 agentic parity pack，將 OpenAI candidate lane 與 Opus 4.6 baseline 比較的 mock parity lane
+- 使用 `qa-live-shared` 環境的快速 live Matrix QA profile
+- 使用 Convex CI credential lease 的 live Telegram QA lane
+- 當發布 telemetry 需要明確本機證明時的 `pnpm qa:otel:smoke`
 
-使用這台機器回答「發行在 QA 情境與即時 channel 流程中是否行為正確？」核准發行時，請保留同等性、Matrix 和 Telegram 路徑的成品 URL。完整 Matrix 涵蓋仍可作為手動分片 QA-Lab 執行使用，而不是預設的發行關鍵路徑。
+使用此 box 回答「發布是否在 QA 情境和 live channel flow 中正確運作？」核准發布時，請保留 parity、Matrix 和 Telegram lane 的 artifact URL。完整 Matrix 涵蓋仍可作為手動 sharded QA-Lab 執行使用，而非預設的發布關鍵 lane。
 
 ### 套件
 
-Package 機器是可安裝產品閘門。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支援。解析器會將候選項正規化為 Docker E2E 使用的 `package-under-test` tarball、驗證套件清單、記錄套件版本和 SHA-256，並讓工作流程測試框架 ref 與套件來源 ref 分離。
+套件 box 是可安裝產品 gate。它由 `Package Acceptance` 和 resolver `scripts/resolve-openclaw-package-candidate.mjs` 支援。resolver 會將 candidate 正規化為 Docker E2E 使用的 `package-under-test` tarball，驗證套件 inventory，記錄套件版本與 SHA-256，並讓工作流程 harness ref 與套件來源 ref 分離。
 
-支援的候選來源：
+支援的 candidate 來源：
 
-- `source=npm`：`openclaw@beta`、`openclaw@latest`，或精確的 OpenClaw 發行版本
-- `source=ref`：使用選定的 `workflow_ref` 測試框架，封裝受信任的 `package_ref` 分支、標籤或完整提交 SHA
+- `source=npm`：`openclaw@beta`、`openclaw@latest`，或確切的 OpenClaw 發布版本
+- `source=ref`：以所選 `workflow_ref` harness 打包可信任的 `package_ref` 分支、標籤或完整 commit SHA
 - `source=url`：下載需要 `package_sha256` 的 HTTPS `.tgz`
-- `source=artifact`：重複使用另一個 GitHub Actions 執行上傳的 `.tgz`
+- `source=artifact`：重用另一個 GitHub Actions 執行上傳的 `.tgz`
 
-`OpenClaw Release Checks` 會使用 `source=artifact`、已準備的發行套件成品、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 執行 Package Acceptance。Package Acceptance 會針對相同解析 tarball 保持遷移、更新、過時 plugin 依賴清理、離線 plugin 夾具、plugin 更新，以及 Telegram 套件 QA。升級矩陣涵蓋從 `2026.4.23` 到 `latest` 的每個穩定 npm 已發布基準線；對已出貨候選項使用 `source=npm` 的 Package Acceptance，或在發布前對有 SHA 支援的本機 npm tarball 使用 `source=ref`/`source=artifact`。它是過去多數需要 Parallels 的套件/更新涵蓋的 GitHub 原生替代方案。跨作業系統發行檢查對作業系統特定的 onboarding、安裝程式與平台行為仍然重要，但套件/更新產品驗證應優先使用 Package Acceptance。
+`OpenClaw Release Checks` 會以 `source=artifact`、已準備的發布套件 artifact、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`telegram_mode=mock-openai` 執行 Package Acceptance。Package Acceptance 會針對同一個已解析 tarball 保持 migration、update、stale Plugin dependency cleanup、offline Plugin fixture、Plugin update，以及 Telegram 套件 QA。阻斷性發布檢查會使用預設的最新已發布套件 baseline；`run_release_soak=true` 或 `release_profile=full` 會擴展到從 `2026.4.23` 到 `latest` 的每個穩定 npm 已發布 baseline，再加上已回報問題 fixture。對已出貨 candidate 使用 `source=npm` 的 Package Acceptance；或在發布前，對 SHA 支援的本機 npm tarball 使用 `source=ref`/`source=artifact`。它是 GitHub 原生替代方案，用來取代過去大多數需要 Parallels 的 package/update 涵蓋。跨作業系統發布檢查對於作業系統特定 onboarding、installer 和 platform 行為仍然重要，但 package/update 產品驗證應優先使用 Package Acceptance。
 
-更新與 plugin 驗證的標準檢查清單是[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。在判斷哪個本機、Docker、Package Acceptance 或 release-check 路徑能證明 plugin 安裝/更新、doctor 清理，或已發布套件遷移變更時，請使用它。從每個穩定 `2026.4.23+` 套件進行的完整已發布更新遷移，是單獨的手動 `Update Migration` 工作流程，不屬於 Full Release CI。
+update 和 Plugin 驗證的標準檢查清單是[測試 update 和 Plugin](/zh-TW/help/testing-updates-plugins)。決定哪個本機、Docker、Package Acceptance 或 release-check lane 能證明 Plugin 安裝/update、doctor cleanup，或已發布套件 migration 變更時，請使用它。從每個穩定 `2026.4.23+` 套件進行的詳盡已發布 update migration 是單獨的手動 `Update Migration` 工作流程，不屬於 Full Release CI。
 
-舊版 package-acceptance 寬容性是刻意限時的。到 `2026.4.25` 為止的套件，可以對已發布到 npm 的中繼資料缺口使用相容性路徑：tarball 中缺少 private QA inventory entries、缺少 `gateway install --wrapper`、tarball 衍生 git 夾具中缺少 patch files、缺少持久化 `update.channel`、舊版 plugin install-record 位置、缺少 marketplace install-record persistence，以及 `plugins update` 期間的 config metadata migration。已發布的 `2026.4.26` 套件可能會對已出貨的本機建置中繼資料 stamp files 發出警告。較新的套件必須滿足現代套件合約；相同缺口會導致發行驗證失敗。
+Legacy package-acceptance 寬容度會刻意設定時間限制。到 `2026.4.25` 為止的套件，可能會針對已發布到 npm 的 metadata 缺口使用相容性路徑：tarball 中缺少 private QA inventory entry、缺少 `gateway install --wrapper`、tarball 衍生 git fixture 中缺少 patch file、缺少持久化 `update.channel`、legacy Plugin install-record 位置、缺少 marketplace install-record 持久化，以及 `plugins update` 期間的 config metadata migration。已發布的 `2026.4.26` 套件可能會對已出貨的本機 build metadata stamp file 發出警告。後續套件必須滿足現代套件 contract；相同缺口會使發布驗證失敗。
 
-當發行問題關於實際可安裝套件時，使用更廣泛的 Package Acceptance profiles：
+當發布問題關乎實際可安裝套件時，請使用更廣泛的 Package Acceptance profile：
 
 ```bash
 gh workflow run package-acceptance.yml \
@@ -292,35 +293,35 @@ gh workflow run package-acceptance.yml \
   -f published_upgrade_survivor_baseline=openclaw@2026.4.26
 ```
 
-常用套件 profiles：
+常見套件設定檔：
 
-- `smoke`：快速套件安裝/頻道/代理、Gateway 網路與設定
+- `smoke`：快速套件安裝/頻道/代理、Gateway 網路，以及設定
   重新載入通道
-- `package`：不使用即時 ClawHub 的安裝/更新/Plugin 套件合約；這是 release-check
+- `package`：安裝/更新/Plugin 套件合約，不含即時 ClawHub；這是 release-check
   預設值
 - `product`：`package` 加上 MCP 頻道、cron/subagent 清理、OpenAI 網頁
   搜尋，以及 OpenWebUI
-- `full`：包含 OpenWebUI 的 Docker 發布路徑區塊
+- `full`：含 OpenWebUI 的 Docker 發布路徑區塊
 - `custom`：用於聚焦重新執行的精確 `docker_lanes` 清單
 
-若要進行套件候選版 Telegram 驗證，請在 Package Acceptance 上啟用 `telegram_mode=mock-openai` 或
-`telegram_mode=live-frontier`。此工作流程會將解析出的
+如需套件候選版本的 Telegram 證明，請在 Package Acceptance 上啟用 `telegram_mode=mock-openai` 或
+`telegram_mode=live-frontier`。工作流程會將解析出的
 `package-under-test` tarball 傳入 Telegram 通道；獨立的
 Telegram 工作流程仍接受已發布的 npm 規格，用於發布後檢查。
 
 ## 發布自動化
 
-`OpenClaw Release Publish` 是一般會變更狀態的發布進入點。它會依照發布所需的順序
+`OpenClaw Release Publish` 是一般的可變更發布進入點。它會依照發布所需的順序
 協調 trusted-publisher 工作流程：
 
 1. 簽出發布標籤並解析其 commit SHA。
-2. 驗證該標籤可從 `main` 或 `release/*` 連到。
+2. 驗證該標籤可從 `main` 或 `release/*` 觸及。
 3. 執行 `pnpm plugins:sync:check`。
 4. 以 `publish_scope=all-publishable` 和
-   `ref=<release-sha>` 派發 `Plugin NPM Release`。
-5. 使用相同範圍與 SHA 派發 `Plugin ClawHub Release`。
-6. 使用發布標籤、npm dist-tag，以及
-   已儲存的 `preflight_run_id` 派發 `OpenClaw NPM Release`。
+   `ref=<release-sha>` 派送 `Plugin NPM Release`。
+5. 以相同的範圍和 SHA 派送 `Plugin ClawHub Release`。
+6. 以發布標籤、npm dist-tag，以及
+   已儲存的 `preflight_run_id` 派送 `OpenClaw NPM Release`。
 
 Beta 發布範例：
 
@@ -342,7 +343,7 @@ gh workflow run openclaw-release-publish.yml \
   -f npm_dist_tag=beta
 ```
 
-直接將穩定版提升到 `latest` 需要明確指定：
+直接將穩定版提升到 `latest` 必須明確指定：
 
 ```bash
 gh workflow run openclaw-release-publish.yml \
@@ -352,85 +353,90 @@ gh workflow run openclaw-release-publish.yml \
   -f npm_dist_tag=latest
 ```
 
-只有在聚焦修復或重新發布工作時，才使用較低階的 `Plugin NPM Release` 與 `Plugin ClawHub Release` 工作流程。若要修復選定的 plugin，請將
+僅在聚焦修復或重新發布工作時，才使用較底層的 `Plugin NPM Release` 和 `Plugin ClawHub Release` 工作流程。若要修復選定 Plugin，請將
 `plugin_publish_scope=selected` 和 `plugins=@openclaw/name` 傳給
-`OpenClaw Release Publish`，或在不得發布 OpenClaw 套件時直接派發子工作流程。
+`OpenClaw Release Publish`；或在不得發布 OpenClaw 套件時，直接派送子工作流程。
 
 ## NPM 工作流程輸入
 
-`OpenClaw NPM Release` 接受這些由操作者控制的輸入：
+`OpenClaw NPM Release` 接受以下由操作員控制的輸入：
 
 - `tag`：必要的發布標籤，例如 `v2026.4.2`、`v2026.4.2-1`，或
-  `v2026.4.2-beta.1`；當 `preflight_only=true` 時，也可以是目前
-  完整 40 字元的工作流程分支 commit SHA，用於僅驗證的預檢
+  `v2026.4.2-beta.1`；當 `preflight_only=true` 時，它也可以是目前
+  完整 40 字元的工作流程分支 commit SHA，用於僅驗證的 preflight
 - `preflight_only`：`true` 表示僅驗證/建置/打包，`false` 表示
   真正的發布路徑
 - `preflight_run_id`：真正發布路徑必填，讓工作流程重用
-  成功預檢執行所準備的 tarball
+  成功 preflight 執行中準備好的 tarball
 - `npm_dist_tag`：發布路徑的 npm 目標標籤；預設為 `beta`
 
-`OpenClaw Release Publish` 接受這些由操作者控制的輸入：
+`OpenClaw Release Publish` 接受以下由操作員控制的輸入：
 
-- `tag`：必要的發布標籤；必須已經存在
-- `preflight_run_id`：成功的 `OpenClaw NPM Release` 預檢執行 ID；
+- `tag`：必要的發布標籤；必須已存在
+- `preflight_run_id`：成功的 `OpenClaw NPM Release` preflight 執行 id；
   當 `publish_openclaw_npm=true` 時必填
 - `npm_dist_tag`：OpenClaw 套件的 npm 目標標籤
-- `plugin_publish_scope`：預設為 `all-publishable`；只有在
-  聚焦修復工作時才使用 `selected`
-- `plugins`：當 `plugin_publish_scope=selected` 時，逗號分隔的 `@openclaw/*` 套件名稱
-- `publish_openclaw_npm`：預設為 `true`；只有在使用此
-  工作流程作為僅 plugin 修復的協調器時才設為 `false`
+- `plugin_publish_scope`：預設為 `all-publishable`；僅在
+  聚焦修復工作時使用 `selected`
+- `plugins`：當 `plugin_publish_scope=selected` 時，使用逗號分隔的 `@openclaw/*` 套件名稱
+- `publish_openclaw_npm`：預設為 `true`；僅在將此
+  工作流程作為僅 Plugin 修復協調器時設為 `false`
 
-`OpenClaw Release Checks` 接受這些由操作者控制的輸入：
+`OpenClaw Release Checks` 接受以下由操作員控制的輸入：
 
-- `ref`：要驗證的分支、標籤，或完整 commit SHA。含有祕密的檢查
-  要求解析出的 commit 可從 OpenClaw 分支或
-  發布標籤連到。
+- `ref`：要驗證的分支、標籤，或完整 commit SHA。帶有秘密的檢查
+  需要解析後的 commit 可從 OpenClaw 分支或
+  發布標籤觸及。
+- `run_release_soak`：在穩定版/預設發布檢查中選擇執行完整的即時/E2E、Docker 發布路徑，以及
+  all-since upgrade-survivor soak。它會被
+  `release_profile=full` 強制開啟。
 
 規則：
 
-- 穩定版與修正版標籤可以發布到 `beta` 或 `latest`
-- Beta 預發布標籤只能發布到 `beta`
+- 穩定版和修正版標籤可發布到 `beta` 或 `latest`
+- Beta prerelease 標籤只能發布到 `beta`
 - 對於 `OpenClaw NPM Release`，只有在
-  `preflight_only=true` 時才允許完整 commit SHA 輸入
-- `OpenClaw Release Checks` 與 `Full Release Validation` 一律
-  只進行驗證
-- 真正發布路徑必須使用預檢期間所用的同一個 `npm_dist_tag`；
-  工作流程會在發布繼續前驗證該中繼資料
+  `preflight_only=true` 時才允許輸入完整 commit SHA
+- `OpenClaw Release Checks` 和 `Full Release Validation` 永遠
+  僅用於驗證
+- 真正的發布路徑必須使用 preflight 期間所用的相同 `npm_dist_tag`；
+  工作流程會在發布前驗證該中繼資料仍然一致
 
 ## 穩定版 npm 發布順序
 
 切出穩定版 npm 發布時：
 
-1. 使用 `preflight_only=true` 執行 `OpenClaw NPM Release`
+1. 以 `preflight_only=true` 執行 `OpenClaw NPM Release`
    - 在標籤存在之前，你可以使用目前完整的工作流程分支 commit
-     SHA，對預檢工作流程進行僅驗證的試執行
-2. 一般 beta-first 流程選擇 `npm_dist_tag=beta`，或只有在你有意直接發布穩定版時才選擇 `latest`
-3. 當你想從單一手動工作流程取得一般 CI 加上即時 prompt cache、Docker、QA Lab、
-   Matrix 與 Telegram 覆蓋時，請在發布分支、發布標籤，或完整
+     SHA，對 preflight 工作流程進行僅驗證的 dry run
+2. 一般 beta-first 流程請選擇 `npm_dist_tag=beta`；只有在你刻意想要直接發布穩定版時
+   才選擇 `latest`
+3. 當你想要從單一手動工作流程取得一般 CI 加上即時 prompt cache、Docker、QA Lab、
+   Matrix 和 Telegram 覆蓋時，請在發布分支、發布標籤，或完整
    commit SHA 上執行 `Full Release Validation`
-4. 如果你刻意只需要可重現的一般測試圖，請改在發布 ref 上執行
+4. 如果你刻意只需要確定性的正常測試圖，請改為在發布 ref 上執行
    手動 `CI` 工作流程
 5. 儲存成功的 `preflight_run_id`
-6. 使用相同的 `tag`、相同的 `npm_dist_tag`，
-   以及已儲存的 `preflight_run_id` 執行 `OpenClaw Release Publish`；它會先將外部化的 plugins 發布到 npm
-   與 ClawHub，再提升 OpenClaw npm 套件
+6. 以相同的 `tag`、相同的 `npm_dist_tag`，以及已儲存的 `preflight_run_id`
+   執行 `OpenClaw Release Publish`；它會先將外部化的 Plugin 發布到 npm
+   和 ClawHub，再提升 OpenClaw npm 套件
 7. 如果發布落在 `beta`，請使用私有的
    `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
    工作流程，將該穩定版本從 `beta` 提升到 `latest`
-8. 如果發布是有意直接發布到 `latest`，而 `beta`
-   應該立即跟隨同一個穩定版建置，請使用同一個私有
-   工作流程，讓兩個 dist-tags 都指向該穩定版本，或讓其排程的
+8. 如果發布是刻意直接發布到 `latest`，且 `beta`
+   應立即跟隨相同的穩定版建置，請使用同一個私有
+   工作流程，將兩個 dist-tag 都指向該穩定版本，或讓其排程的
    自我修復同步稍後移動 `beta`
 
-dist-tag 變更位於私有 repo 是出於安全考量，因為它仍然
-需要 `NPM_TOKEN`，而公開 repo 維持僅使用 OIDC 發布。
+dist-tag 變更位於私有 repo 中是基於安全性，因為它仍然
+需要 `NPM_TOKEN`，而公開 repo 則維持僅使用 OIDC 發布。
 
-這讓直接發布路徑與 beta-first 提升路徑都保有文件化且操作者可見。
+這會讓直接發布路徑和 beta-first 提升路徑都
+有文件記錄，且操作員可見。
 
-如果維護者必須退回本機 npm 驗證，請只在專用 tmux 工作階段內執行任何 1Password
-CLI (`op`) 命令。不要直接從主代理 shell 呼叫 `op`；將其保留在 tmux 內可讓提示、
-警示與 OTP 處理可觀察，並防止重複的主機警示。
+如果維護者必須回退到本機 npm 驗證，請只在專用 tmux 工作階段內執行任何 1Password
+CLI (`op`) 命令。請勿從主要代理 shell 直接呼叫 `op`；將它保留在 tmux 內可讓提示、
+警示和 OTP 處理可觀察，並防止重複的主機警示。
 
 ## 公開參考
 
@@ -446,8 +452,8 @@ CLI (`op`) 命令。不要直接從主代理 shell 呼叫 `op`；將其保留在
 
 維護者使用
 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
-中的私有發布文件作為實際操作手冊。
+中的私有發布文件作為實際執行手冊。
 
 ## 相關
 
-- [發布通道](/zh-TW/install/development-channels)
+- [發布頻道](/zh-TW/install/development-channels)

docs/zh-TW/reference/full-release-validation.md

@@ -1,24 +1,22 @@
 ---
 read_when:
-    - 執行或重新執行完整發布驗證
-    - 比較穩定版與完整版的發布驗證設定檔
+    - 執行或重新執行完整發行驗證
+    - 比較穩定版與完整發行驗證設定檔
     - 偵錯發布驗證階段失敗
-summary: 完整發布驗證階段、子工作流程、發布設定檔、重新執行控制代碼與佐證
+summary: 完整發行驗證的階段、子工作流程、發行設定檔、重新執行控制代碼與證據
 title: 完整發布驗證
 x-i18n:
-    generated_at: "2026-05-03T21:42:32Z"
+    generated_at: "2026-05-05T01:49:01Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7
+    source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d
     source_path: reference/full-release-validation.md
     workflow: 16
 ---
 
-`Full Release Validation` 是發行總括流程。它是發行前驗證的單一手動
-進入點，但大多數工作會在子 workflow 中進行，讓失敗的執行環境可以重跑，而不必重新啟動整個發行流程。
+`Full Release Validation` 是發布總工作流程。它是預發布驗證的單一手動進入點，但大多數工作會在子工作流程中進行，讓失敗的執行環境可以重新執行，而不必重新啟動整個發布流程。
 
-從受信任的 workflow ref 執行它，通常是 `main`，並將發行分支、
-標籤或完整 commit SHA 作為 `ref` 傳入：
+從受信任的工作流程 ref 執行，通常是 `main`，並將發布分支、標籤或完整 commit SHA 作為 `ref` 傳入：
 
 ```bash
 gh workflow run full-release-validation.yml \
@@ -29,124 +27,137 @@ gh workflow run full-release-validation.yml \
   -f release_profile=stable
 ```
 
-子 workflow 會將受信任的 workflow ref 用於測試框架，並將輸入的
-`ref` 用於待測候選版本。這能在驗證較舊的發行分支或標籤時，
-仍可使用新的驗證邏輯。
+子工作流程會使用受信任的工作流程 ref 作為測試框架，並使用輸入的 `ref` 作為受測候選版本。這讓驗證較舊的發布分支或標籤時，仍可使用新的驗證邏輯。
 
-套件驗收通常會從已解析的 `ref` 建置候選 tarball，
-包括透過 `pnpm ci:full-release` 派發的完整 SHA 執行。發布後，
-傳入 `package_acceptance_package_spec=openclaw@YYYY.M.D`（或
-`openclaw@beta`/`openclaw@latest`），即可改為針對已出貨的 npm 套件執行相同的套件/更新矩陣。
+預設情況下，`release_profile=stable` 會執行會阻擋發布的執行線，並略過完整的即時/Docker 長時間浸泡測試。傳入 `run_release_soak=true` 可在 stable 執行中包含浸泡測試執行線。`release_profile=full` 一律啟用浸泡測試執行線，讓廣泛的建議設定檔不會無聲地降低覆蓋率。
+
+套件驗收通常會從解析後的 `ref` 建置候選 tarball，包括透過 `pnpm ci:full-release` 分派的完整 SHA 執行。發布後，傳入 `package_acceptance_package_spec=openclaw@YYYY.M.D`（或 `openclaw@beta`/`openclaw@latest`），即可改為針對已發布的 npm 套件執行相同的套件/更新矩陣。
 
 ## 頂層階段
 
-| 階段                 | 詳細資訊                                                                                                                                                                                                                                                                                                                                                                                       |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 目標解析             | **Job:** `Resolve target ref`<br />**子 workflow:** 無<br />**證明：** 解析發行分支、標籤或完整 commit SHA，並記錄選取的輸入。<br />**重跑：** 如果此步驟失敗，重跑總括流程。                                                                                                                                               |
-| Vitest 與一般 CI     | **Job:** `Run normal full CI`<br />**子 workflow:** `CI`<br />**證明：** 針對目標 ref 的手動完整 CI 圖，包括 Linux Node lanes、內建 Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python skills、Windows、macOS、Control UI i18n，以及透過總括流程執行的 Android。<br />**重跑：** `rerun_group=ci`。 |
-| Plugin 預發行        | **Job:** `Run plugin prerelease validation`<br />**子 workflow:** `Plugin Prerelease`<br />**證明：** 僅限發行的 Plugin 靜態檢查、agentic Plugin 覆蓋率、完整擴充批次分片，以及 Plugin 預發行 Docker lanes。<br />**重跑：** `rerun_group=plugin-prerelease`。                                                                 |
-| 發行檢查             | **Job:** `Run release/live/Docker/QA validation`<br />**子 workflow:** `OpenClaw Release Checks`<br />**證明：** 安裝煙霧測試、跨 OS 套件檢查、live/E2E 測試套件、Docker 發行路徑區塊、套件驗收、QA Lab parity、live Matrix，以及 live Telegram。<br />**重跑：** `rerun_group=release-checks` 或更窄的 release-checks handle。 |
-| 套件成品             | **Job:** `Prepare release package artifact`<br />**子 workflow:** 無<br />**證明：** 夠早建立父層 `release-package-under-test` tarball，供不需要等待 `OpenClaw Release Checks` 的套件面向檢查使用。<br />**重跑：** 重跑總括流程，或為 `rerun_group=npm-telegram` 提供 `npm_telegram_package_spec`。                    |
-| 套件 Telegram        | **Job:** `Run package Telegram E2E`<br />**子 workflow:** `NPM Telegram Beta E2E`<br />**證明：** 在 `rerun_group=all` 且 `release_profile=full` 時，提供由父層成品支援的 Telegram 套件驗證；或在設定 `npm_telegram_package_spec` 時，提供已發布套件的 Telegram 驗證。<br />**重跑：** `rerun_group=npm-telegram` 搭配 `npm_telegram_package_spec`。 |
-| 總括驗證器           | **Job:** `Verify full validation`<br />**子 workflow:** 無<br />**證明：** 重新檢查已記錄的子執行結論，並附加子 workflow 的最慢 job 表格。<br />**重跑：** 在重跑失敗的子 workflow 並轉綠後，只重跑此 job。                                                                                                                   |
+| 階段                 | 詳細資料                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 目標解析             | **作業：** `Resolve target ref`<br />**子工作流程：** 無<br />**證明：** 解析發布分支、標籤或完整 commit SHA，並記錄選取的輸入。<br />**重新執行：** 如果此項失敗，重新執行總工作流程。                                                                                                                                                                                         |
+| Vitest 與一般 CI     | **作業：** `Run normal full CI`<br />**子工作流程：** `CI`<br />**證明：** 針對目標 ref 執行手動完整 CI 圖，包括 Linux Node 執行線、內建 Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python Skills、Windows、macOS、Control UI i18n，以及透過總工作流程執行的 Android。<br />**重新執行：** `rerun_group=ci`。 |
+| Plugin 預發布        | **作業：** `Run plugin prerelease validation`<br />**子工作流程：** `Plugin Prerelease`<br />**證明：** 僅發布使用的 Plugin 靜態檢查、代理式 Plugin 覆蓋、完整 Plugin 批次分片，以及 Plugin 預發布 Docker 執行線。<br />**重新執行：** `rerun_group=plugin-prerelease`。                                                                                                         |
+| 發布檢查             | **作業：** `Run release/live/Docker/QA validation`<br />**子工作流程：** `OpenClaw Release Checks`<br />**證明：** 安裝煙霧測試、跨作業系統套件檢查、套件驗收、QA Lab 一致性、即時 Matrix，以及即時 Telegram。使用 `run_release_soak=true` 或 `release_profile=full` 時，也會執行完整的即時/E2E 套件和 Docker 發布路徑區塊。<br />**重新執行：** `rerun_group=release-checks` 或較窄的發布檢查控制代碼。 |
+| 套件成品             | **作業：** `Prepare release package artifact`<br />**子工作流程：** 無<br />**證明：** 提早建立父層 `release-package-under-test` tarball，供不需要等待 `OpenClaw Release Checks` 的套件相關檢查使用。<br />**重新執行：** 重新執行總工作流程，或為 `rerun_group=npm-telegram` 提供 `npm_telegram_package_spec`。                                                               |
+| 套件 Telegram        | **作業：** `Run package Telegram E2E`<br />**子工作流程：** `NPM Telegram Beta E2E`<br />**證明：** 在 `rerun_group=all` 且 `release_profile=full` 時，提供由父層成品支援的 Telegram 套件證明；或在設定 `npm_telegram_package_spec` 時，提供已發布套件的 Telegram 證明。<br />**重新執行：** 使用 `npm_telegram_package_spec` 的 `rerun_group=npm-telegram`。 |
+| 總工作流程驗證器     | **作業：** `Verify full validation`<br />**子工作流程：** 無<br />**證明：** 重新檢查已記錄的子執行結論，並附加來自子工作流程的最慢作業表格。<br />**重新執行：** 在重新執行失敗的子工作流程並轉為綠燈後，只重新執行此作業。                                                                                                                                                |
 
-對於 `ref=main` 和 `rerun_group=all`，較新的總括流程會取代較舊的總括流程。
-當父層被取消時，它的監控器會取消任何已派發的子 workflow。
-發行分支與標籤驗證執行預設不會互相取消。
+對於 `ref=main` 和 `rerun_group=all`，較新的總工作流程會取代較舊的總工作流程。當父層被取消時，它的監控器會取消任何已經分派的子工作流程。發布分支與標籤驗證執行預設不會彼此取消。
 
-## 發行檢查階段
+## 發布檢查階段
 
-`OpenClaw Release Checks` 是最大的子 workflow。它會解析一次目標，
-並在套件或 Docker 面向階段需要時，準備共用的 `release-package-under-test` 成品。
+`OpenClaw Release Checks` 是最大的子工作流程。它會解析一次目標，並在套件或 Docker 相關階段需要時，準備共用的 `release-package-under-test` 成品。
 
-| 階段                | 詳細資訊                                                                                                                                                                                                                                                                                                                                                                                         |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 發行目標            | **Job:** `Resolve target ref`<br />**後備 workflow:** 無<br />**測試：** 選取的 ref、選擇性的預期 SHA、profile、重跑群組，以及聚焦的 live 測試套件篩選器。<br />**重跑：** `rerun_group=release-checks`。                                                                                                                     |
-| 套件成品            | **Job:** `Prepare release package artifact`<br />**後備 workflow:** 無<br />**測試：** 打包或解析一個候選 tarball，並上傳 `release-package-under-test` 供下游套件面向檢查使用。<br />**重跑：** 受影響的套件、跨 OS 或 live/E2E 群組。                                                                                         |
-| 安裝煙霧測試        | **Job:** `Run install smoke`<br />**後備 workflow:** `Install Smoke`<br />**測試：** 完整安裝路徑，包含根層 Dockerfile 煙霧測試映像重用、QR 套件安裝、根層與 Gateway Docker 煙霧測試、安裝程式 Docker 測試、Bun 全域安裝映像提供者煙霧測試，以及快速內建 Plugin 安裝/解除安裝 E2E。<br />**重跑：** `rerun_group=install-smoke`。 |
-| 跨 OS               | **Job:** `cross_os_release_checks`<br />**後備 workflow:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**測試：** 在 Linux、Windows 和 macOS 上，使用候選 tarball 加上基準套件，針對選取的提供者與模式執行全新安裝和升級 lanes。<br />**重跑：** `rerun_group=cross-os`。                                           |
-| Repo 與 live E2E    | **Job:** `Run repo/live E2E validation`<br />**後備 workflow:** `OpenClaw Live And E2E Checks (Reusable)`<br />**測試：** repository E2E、live cache、OpenAI websocket streaming、原生 live 提供者與 Plugin 分片，以及由 `release_profile` 選取的 Docker 支援 live model/backend/gateway 測試框架。<br />**重跑：** `rerun_group=live-e2e`，可選擇搭配 `live_suite_filter`。 |
-| Docker 發行路徑     | **Job:** `Run Docker release-path validation`<br />**後備 workflow:** `OpenClaw Live And E2E Checks (Reusable)`<br />**測試：** 針對共用套件成品執行發行路徑 Docker 區塊。<br />**重跑：** `rerun_group=live-e2e`。                                                                                                           |
-| 套件驗收            | **Job:** `Run package acceptance`<br />**後備 workflow:** `Package Acceptance`<br />**測試：** 離線 Plugin 套件 fixture、Plugin 更新、mock-OpenAI Telegram 套件驗收，以及從每個 `2026.4.23` 或之後的穩定 npm 發行版，針對相同 tarball 執行的已發布升級 survivor 檢查。<br />**重跑：** `rerun_group=package`。             |
-| QA parity           | **Job:** `Run QA Lab parity lane` 與 `Run QA Lab parity report`<br />**後備 workflow:** 直接 job<br />**測試：** 候選與基準 agentic parity packs，然後執行 parity 報告。<br />**重跑：** `rerun_group=qa-parity` 或 `rerun_group=qa`。                                                                                         |
-| QA live Matrix      | **Job:** `Run QA Lab live Matrix lane`<br />**後備 workflow:** 直接 job<br />**測試：** `qa-live-shared` 環境中的快速 live Matrix QA profile。<br />**重跑：** `rerun_group=qa-live` 或 `rerun_group=qa`。                                                                                                                     |
-| QA live Telegram    | **Job:** `Run QA Lab live Telegram lane`<br />**後備 workflow:** 直接 job<br />**測試：** 使用 Convex CI credential leases 的 live Telegram QA。<br />**重跑：** `rerun_group=qa-live` 或 `rerun_group=qa`。                                                                                                                   |
-| 發行驗證器          | **Job:** `Verify release checks`<br />**後備 workflow:** 無<br />**測試：** 針對選取重跑群組所需的 release-check jobs。<br />**重跑：** 在聚焦的子 jobs 通過後重跑。                                                                                                                                                            |
+| 階段                | 詳細                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 發行目標            | **作業：** `Resolve target ref`<br />**支援工作流程：** 無<br />**測試：** 選取的 ref、選用的預期 SHA、設定檔、重新執行群組，以及聚焦的即時套件篩選器。<br />**重新執行：** `rerun_group=release-checks`。                                                                                                                                                                                                                                                                              |
+| 套件成品            | **作業：** `Prepare release package artifact`<br />**支援工作流程：** 無<br />**測試：** 封裝或解析一個候選 tarball，並上傳 `release-package-under-test` 供下游面向套件的檢查使用。<br />**重新執行：** 受影響的套件、跨作業系統或即時/E2E 群組。                                                                                                                                                                                                              |
+| 安裝煙霧測試        | **作業：** `Run install smoke`<br />**支援工作流程：** `Install Smoke`<br />**測試：** 完整安裝路徑，包含重用根 Dockerfile 煙霧測試映像、QR 套件安裝、根與 Gateway Docker 煙霧測試、安裝程式 Docker 測試、Bun 全域安裝 image-provider 煙霧測試，以及快速 bundled-plugin 安裝/解除安裝 E2E。<br />**重新執行：** `rerun_group=install-smoke`。                                                                                                                                 |
+| 跨作業系統          | **作業：** `cross_os_release_checks`<br />**支援工作流程：** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**測試：** 針對選取的提供者與模式，在 Linux、Windows 和 macOS 上執行全新與升級路線，使用候選 tarball 加上基準套件。<br />**重新執行：** `rerun_group=cross-os`。                                                                                                                                                                                  |
+| 儲存庫與即時 E2E    | **作業：** `Run repo/live E2E validation`<br />**支援工作流程：** `OpenClaw Live And E2E Checks (Reusable)`<br />**測試：** 儲存庫 E2E、即時快取、OpenAI websocket 串流、原生即時提供者與 Plugin 分片，以及由 `release_profile` 選取、Docker 支援的即時模型/後端/Gateway 測試框架。<br />**執行條件：** `run_release_soak=true`、`release_profile=full`，或聚焦的 `rerun_group=live-e2e`。<br />**重新執行：** `rerun_group=live-e2e`，可選擇搭配 `live_suite_filter`。 |
+| Docker 發行路徑     | **作業：** `Run Docker release-path validation`<br />**支援工作流程：** `OpenClaw Live And E2E Checks (Reusable)`<br />**測試：** 針對共用套件成品的發行路徑 Docker 區塊。<br />**執行條件：** `run_release_soak=true`、`release_profile=full`，或聚焦的 `rerun_group=live-e2e`。<br />**重新執行：** `rerun_group=live-e2e`。                                                                                                                                                      |
+| Package Acceptance  | **作業：** `Run package acceptance`<br />**支援工作流程：** `Package Acceptance`<br />**測試：** 離線 Plugin 套件夾具、Plugin 更新、mock-OpenAI Telegram 套件驗收，以及針對同一個 tarball 的已發布升級存活檢查。阻擋發行的檢查使用預設的最新已發布基準；浸泡測試會擴展到 `2026.4.23` 當天或之後的每個穩定 npm 發行版，加上已回報問題的夾具。<br />**重新執行：** `rerun_group=package`。                          |
+| QA 同等性           | **作業：** `Run QA Lab parity lane` 和 `Run QA Lab parity report`<br />**支援工作流程：** 直接作業<br />**測試：** 候選與基準代理同等性套件，接著產生同等性報告。<br />**重新執行：** `rerun_group=qa-parity` 或 `rerun_group=qa`。                                                                                                                                                                                                                                          |
+| QA 即時 Matrix      | **作業：** `Run QA Lab live Matrix lane`<br />**支援工作流程：** 直接作業<br />**測試：** `qa-live-shared` 環境中的快速即時 Matrix QA 設定檔。<br />**重新執行：** `rerun_group=qa-live` 或 `rerun_group=qa`。                                                                                                                                                                                                                                                                           |
+| QA 即時 Telegram    | **作業：** `Run QA Lab live Telegram lane`<br />**支援工作流程：** 直接作業<br />**測試：** 使用 Convex CI 憑證租約的即時 Telegram QA。<br />**重新執行：** `rerun_group=qa-live` 或 `rerun_group=qa`。                                                                                                                                                                                                                                                                                       |
+| 發行驗證器          | **作業：** `Verify release checks`<br />**支援工作流程：** 無<br />**測試：** 選取重新執行群組所需的發行檢查作業。<br />**重新執行：** 在聚焦的子作業通過後重新執行。                                                                                                                                                                                                                                                                                                    |
 
 ## Docker 發行路徑區塊
 
 當 `live_suite_filter` 為空時，Docker 發行路徑階段會執行這些區塊：
 
-| 區塊                                                            | 覆蓋範圍                                                                |
+| 區塊                                                            | 涵蓋範圍                                                                |
 | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `core`                                                          | Core Docker 發行路徑煙霧測試 lanes。                                   |
+| `core`                                                          | 核心 Docker 發行路徑煙霧測試路線。                                     |
 | `package-update-openai`                                         | OpenAI 套件安裝與更新行為。                                             |
 | `package-update-anthropic`                                      | Anthropic 套件安裝與更新行為。                                          |
 | `package-update-core`                                           | 提供者中立的套件與更新行為。                                            |
-| `plugins-runtime-plugins`                                       | 執行 Plugin 行為的 Plugin runtime lanes。                               |
-| `plugins-runtime-services`                                      | 服務支援的 Plugin runtime lanes；在要求時包含 OpenWebUI。               |
+| `plugins-runtime-plugins`                                       | 測試 Plugin 行為的 Plugin runtime 路線。                                |
+| `plugins-runtime-services`                                      | 服務支援的 Plugin runtime 路線；在要求時包含 OpenWebUI。                |
 | `plugins-runtime-install-a` through `plugins-runtime-install-h` | 為平行發行驗證而拆分的 Plugin 安裝/runtime 批次。                       |
 
-當只有一個 Docker 通道失敗時，請在可重用的即時/E2E 工作流程上使用目標式 `docker_lanes=<lane[,lane]>`。發行成品會在可用時包含每個通道的重新執行命令，並帶有套件成品與映像重用輸入。
+當只有一條 Docker 路線失敗時，請在可重用的即時/E2E 工作流程上使用目標式 `docker_lanes=<lane[,lane]>`。發行成品會包含每條路線的重新執行命令，並在可用時帶有套件成品與映像重用輸入。
 
 ## 發行設定檔
 
-`release_profile` 主要控制發行檢查中的即時/供應商涵蓋範圍。它不會移除一般完整 CI、Plugin Prerelease、安裝煙霧測試、套件驗收、QA Lab，或 Docker 發行路徑區塊。`full` 也會讓傘狀執行在 `rerun_group=all` 時，針對父層發行套件成品執行套件 Telegram E2E，因此完整的預發布候選版本不會默默略過該 Telegram 套件通道。
+`release_profile` 主要控制發行檢查中的即時/提供者廣度。它不會移除一般完整 CI、Plugin Prerelease、安裝煙霧測試、套件驗收或 QA Lab。對於 `stable`，詳盡的儲存庫/即時 E2E 與 Docker 發行路徑區塊屬於浸泡測試涵蓋範圍，並在 `run_release_soak=true` 時執行。`full` 會強制開啟浸泡測試涵蓋範圍，並且在 `rerun_group=all` 時，讓傘狀執行針對父層發行套件成品執行套件 Telegram E2E，因此完整的預發布候選不會默默略過該 Telegram 套件路線。
 
-| 設定檔    | 預期用途                          | 包含的即時/供應商涵蓋範圍                                                                                                                                                          |
+| 設定檔    | 預期用途                          | 包含的即時/提供者涵蓋範圍                                                                                                                                                          |
 | --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `minimum` | 最快的發行關鍵煙霧測試。          | OpenAI/核心即時路徑、OpenAI 的 Docker 即時模型、原生 gateway 核心、原生 OpenAI gateway 設定檔、原生 OpenAI Plugin，以及 Docker 即時 gateway OpenAI。                              |
-| `stable`  | 預設發行核准設定檔。              | `minimum` 加上 Anthropic 煙霧測試、Google、MiniMax、後端、原生即時測試框架、Docker 即時 CLI 後端、Docker ACP 綁定、Docker Codex 框架，以及一個 OpenCode Go 煙霧測試分片。         |
-| `full`    | 廣泛的 advisory 掃描。            | `stable` 加上 advisory 供應商、Plugin 即時分片，以及媒體即時分片。                                                                                                                |
+| `minimum` | 最快的發行關鍵煙霧測試。          | OpenAI/核心即時路徑、OpenAI 的 Docker 即時模型、原生 Gateway 核心、原生 OpenAI Gateway 設定檔、原生 OpenAI Plugin，以及 Docker 即時 Gateway OpenAI。                              |
+| `stable`  | 預設發行核准設定檔。              | `minimum` 加上 Anthropic 煙霧測試、Google、MiniMax、後端、原生即時測試框架、Docker 即時 CLI 後端、Docker ACP bind、Docker Codex 測試框架，以及一個 OpenCode Go 煙霧測試分片。 |
+| `full`    | 廣泛的諮詢性掃描。                | `stable` 加上諮詢性提供者、Plugin 即時分片，以及媒體即時分片。                                                                                                                    |
 
-## 僅完整設定檔的新增項目
+## 僅限 full 的新增項目
 
 這些套件會被 `stable` 略過，並由 `full` 包含：
 
-| 區域                             | 僅完整設定檔的涵蓋範圍                                                                                                    |
+| 區域                             | 僅限 full 的涵蓋範圍                                                                                                         |
 | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Docker 即時模型                  | OpenCode Go、OpenRouter、xAI、Z.ai，以及 Fireworks。                                                                        |
-| Docker 即時 gateway              | advisory 供應商拆分為 DeepSeek/Fireworks、OpenCode Go/OpenRouter，以及 xAI/Z.ai 分片。                                    |
-| 原生 gateway 供應商設定檔        | 完整 Anthropic Opus 與 Sonnet/Haiku 分片、Fireworks、DeepSeek、完整 OpenCode Go 模型分片、OpenRouter、xAI，以及 Z.ai。     |
-| 原生 Plugin 即時分片             | Plugins A-K、L-N、O-Z other、Moonshot，以及 xAI。                                                                           |
-| 原生媒體即時分片                 | 音訊、Google 音樂、MiniMax 音樂，以及影片群組 A-D。                                                                        |
+| Docker 即時模型                  | OpenCode Go、OpenRouter、xAI、Z.ai，以及 Fireworks。                                                                         |
+| Docker 即時 Gateway              | 諮詢性提供者拆分為 DeepSeek/Fireworks、OpenCode Go/OpenRouter，以及 xAI/Z.ai 分片。                                          |
+| 原生 Gateway 提供者設定檔        | 完整 Anthropic Opus 與 Sonnet/Haiku 分片、Fireworks、DeepSeek、完整 OpenCode Go 模型分片、OpenRouter、xAI，以及 Z.ai。       |
+| 原生 Plugin 即時分片             | Plugins A-K、L-N、O-Z other、Moonshot，以及 xAI。                                                                            |
+| 原生媒體即時分片                 | 音訊、Google 音樂、MiniMax 音樂，以及影片群組 A-D。                                                                          |
 
-`stable` 包含 `native-live-src-gateway-profiles-anthropic-smoke` 和 `native-live-src-gateway-profiles-opencode-go-smoke`；`full` 則改用更廣泛的 Anthropic 與 OpenCode Go 模型分片。聚焦的重新執行仍可使用彙總的 `native-live-src-gateway-profiles-anthropic` 或 `native-live-src-gateway-profiles-opencode-go` 控制代碼。
+`stable` 包含 `native-live-src-gateway-profiles-anthropic-smoke` 和 `native-live-src-gateway-profiles-opencode-go-smoke`；`full` 則使用更廣泛的 Anthropic 與 OpenCode Go 模型分片。聚焦重新執行仍可使用彙總的 `native-live-src-gateway-profiles-anthropic` 或 `native-live-src-gateway-profiles-opencode-go` handle。
 
 ## 聚焦重新執行
 
-使用 `rerun_group` 以避免重複執行無關的發行機器：
+使用 `rerun_group` 以避免重複執行不相關的發行 box：
 
-| 控制代碼            | 範圍                                                                  |
+| 代號                | 範圍                                                                 |
 | ------------------- | --------------------------------------------------------------------- |
-| `all`               | 所有 Full Release Validation 階段。                                   |
-| `ci`                | 僅手動完整 CI 子流程。                                                |
-| `plugin-prerelease` | 僅 Plugin Prerelease 子流程。                                         |
+| `all`               | 所有 `Full Release Validation` 階段。                                   |
+| `ci`                | 僅手動完整 CI 子項。                                            |
+| `plugin-prerelease` | 僅 Plugin 預發布子項。                                         |
 | `release-checks`    | 所有 OpenClaw Release Checks 階段。                                   |
-| `install-smoke`     | 安裝煙霧測試到發行檢查。                                              |
-| `cross-os`          | 跨作業系統發行檢查。                                                  |
-| `live-e2e`          | 儲存庫/即時 E2E 與 Docker 發行路徑驗證。                              |
-| `package`           | Package Acceptance。                                                   |
-| `qa`                | QA parity 加上 QA 即時通道。                                          |
-| `qa-parity`         | 僅 QA parity 通道與報告。                                             |
-| `qa-live`           | 僅 QA 即時 Matrix 與 Telegram。                                       |
-| `npm-telegram`      | 已發布套件的 Telegram E2E；需要 `npm_telegram_package_spec`。         |
+| `install-smoke`     | 透過發布檢查進行 Install Smoke。                                 |
+| `cross-os`          | 跨 OS 發布檢查。                                              |
+| `live-e2e`          | 儲存庫/即時 E2E 與 Docker 發布路徑驗證。                     |
+| `package`           | 套件驗收。                                                   |
+| `qa`                | QA 同等性加上 QA 即時通道。                                         |
+| `qa-parity`         | 僅 QA 同等性通道與報告。                                      |
+| `qa-live`           | 僅 QA 即時 Matrix 與 Telegram。                                     |
+| `npm-telegram`      | 已發布套件 Telegram E2E；需要 `npm_telegram_package_spec`。 |
 
-當有一個即時套件失敗時，請搭配 `rerun_group=live-e2e` 使用 `live_suite_filter`。有效的篩選器 ID 定義於可重用的即時/E2E 工作流程中，包括 `docker-live-models`、`live-gateway-docker`、`live-gateway-anthropic-docker`、`live-gateway-google-docker`、`live-gateway-minimax-docker`、`live-gateway-advisory-docker`、`live-cli-backend-docker`、`live-acp-bind-docker`，以及 `live-codex-harness-docker`。
+當某個即時套件失敗時，請搭配 `rerun_group=live-e2e` 使用 `live_suite_filter`。
+有效的篩選器 ID 定義在可重用的即時/E2E 工作流程中，包括
+`docker-live-models`、`live-gateway-docker`、
+`live-gateway-anthropic-docker`、`live-gateway-google-docker`、
+`live-gateway-minimax-docker`、`live-gateway-advisory-docker`、
+`live-cli-backend-docker`、`live-acp-bind-docker`，以及
+`live-codex-harness-docker`。
 
-`live-gateway-advisory-docker` 控制代碼是其三個供應商分片的彙總重新執行控制代碼，因此仍會展開到所有 advisory Docker gateway 工作。
+`live-gateway-advisory-docker` 代號是其三個提供者分片的彙總重新執行代號，
+因此仍會展開到所有 advisory Docker Gateway 工作。
+
+當某個跨 OS 通道失敗時，請搭配 `rerun_group=cross-os` 使用 `cross_os_suite_filter`。
+此篩選器接受 OS ID、套件 ID，或 OS/套件配對，例如
+`windows/packaged-upgrade`、`windows` 或 `packaged-fresh`。跨 OS
+摘要包含已封裝升級通道的各階段耗時，而長時間執行的命令會列印 Heartbeat
+行，因此卡住的 Windows 更新在工作逾時前就能看見。
+
+QA 發布檢查通道屬於 advisory。僅 QA 失敗會回報為警告，
+且不會阻擋發布檢查驗證器；當你需要新的 QA 證據時，請重新執行 `rerun_group=qa`、
+`qa-parity` 或 `qa-live`。
 
 ## 要保留的證據
 
-保留 `Full Release Validation` 摘要作為發行層級索引。它會連結子流程執行 ID，並包含最慢工作的表格。若有失敗，請先檢查子工作流程，再重新執行上方最小的相符控制代碼。
+保留 `Full Release Validation` 摘要作為發布層級索引。它會連結
+子執行 ID，並包含最慢工作表。若發生失敗，請先檢查子
+工作流程，然後重新執行上方最小的相符代號。
 
-實用成品：
+有用的成品：
 
-- 來自 Full Release Validation 父流程和 `OpenClaw Release Checks` 的 `release-package-under-test`
-- `.artifacts/docker-tests/` 下的 Docker 發行路徑成品
-- Package Acceptance 的 `package-under-test` 與 Docker 驗收成品
-- 每個作業系統與套件的 Cross-OS 發行檢查成品
-- QA parity、Matrix，以及 Telegram 成品
+- 來自 Full Release Validation 父項與 `OpenClaw Release Checks` 的 `release-package-under-test`
+- `.artifacts/docker-tests/` 底下的 Docker 發布路徑成品
+- Package Acceptance `package-under-test` 與 Docker 驗收成品
+- 每個 OS 與套件的跨 OS 發布檢查成品
+- QA 同等性、Matrix 與 Telegram 成品
 
 ## 工作流程檔案
 

docs/zh-TW/reference/test.md

@@ -1,63 +1,63 @@
 ---
 read_when:
     - 執行或修正測試
-summary: 如何在本機執行測試 (vitest)，以及何時使用強制/覆蓋率模式
+summary: 如何在本機執行測試（vitest），以及何時使用強制/覆蓋率模式
 title: 測試
 x-i18n:
-    generated_at: "2026-05-02T21:03:31Z"
+    generated_at: "2026-05-05T01:48:55Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f
+    source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605
     source_path: reference/test.md
     workflow: 16
 ---
 
-- 完整測試工具組（測試套件、即時、Docker）：[測試](/zh-TW/help/testing)
+- 完整測試工具組（測試套件、即時測試、Docker）：[測試](/zh-TW/help/testing)
 - 更新與 Plugin 套件驗證：[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)
 
-- `pnpm test:force`：終止任何仍占用預設控制連接埠的 Gateway 程序，然後使用隔離的 Gateway 連接執行完整 Vitest 套件，讓伺服器測試不會與執行中的執行個體衝突。當先前的 Gateway 執行留下 18789 連接埠被占用時使用。
-- `pnpm test:coverage`：使用 V8 覆蓋率執行單元套件（透過 `vitest.unit.config.ts`）。這是已載入檔案的單元覆蓋率關卡，不是整個儲存庫所有檔案的覆蓋率。門檻為行數/函式/陳述式 70%，分支 55%。因為 `coverage.all` 為 false，此關卡會測量單元覆蓋率套件載入的檔案，而不是將每個分割通道來源檔都視為未覆蓋。
-- `pnpm test:coverage:changed`：只針對自 `origin/main` 以來變更的檔案執行單元覆蓋率。
-- `pnpm test:changed`：低成本的智慧變更測試執行。它會從直接測試編輯、同層 `*.test.ts` 檔案、明確來源對應，以及本機匯入圖執行精準目標。廣泛/設定/套件變更會略過，除非它們對應到精準測試。
-- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：明確的廣泛變更測試執行。當測試框架/設定/套件編輯應退回到 Vitest 較廣泛的變更測試行為時使用。
-- `pnpm changed:lanes`：顯示相對於 `origin/main` 的差異所觸發的架構通道。
-- `pnpm check:changed`：針對相對於 `origin/main` 的差異執行智慧變更檢查關卡。它會為受影響的架構通道執行型別檢查、lint 和防護命令，但不會執行 Vitest 測試。使用 `pnpm test:changed` 或明確的 `pnpm test <target>` 作為測試證明。
-- `pnpm test`：將明確的檔案/目錄目標透過有範圍的 Vitest 通道路由。未指定目標的執行會使用固定分片群組，並展開為葉層設定以供本機平行執行；擴充群組一律展開為逐擴充分片設定，而不是一個巨大的根專案程序。
-- 測試包裝器執行結尾會有簡短的 `[test] passed|failed|skipped ... in ...` 摘要。Vitest 自己的持續時間行仍保留為逐分片詳細資料。
-- 共享 OpenClaw 測試狀態：當測試需要隔離的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、設定 fixture、工作區、代理程式目錄或 auth-profile 儲存區時，從 Vitest 使用 `src/test-utils/openclaw-test-state.ts`。
-- 程序 E2E 輔助工具：當 Vitest 程序層級 E2E 測試需要執行中的 Gateway、CLI 環境、日誌擷取，以及集中清理時，使用 `test/helpers/openclaw-test-instance.ts`。
-- Docker/Bash E2E 輔助工具：來源載入 `scripts/lib/docker-e2e-image.sh` 的通道可以將 `docker_e2e_test_state_shell_b64 <label> <scenario>` 傳入容器，並用 `scripts/lib/openclaw-e2e-instance.sh` 解碼；多 HOME 指令碼可以傳入 `docker_e2e_test_state_function_b64`，並在每個流程中呼叫 `openclaw_test_state_create <label> <scenario>`。較低層級的呼叫端可以使用 `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` 取得容器內 shell 片段，或使用 `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` 取得可 source 的主機環境檔。`create` 前方的 `--` 可避免較新的 Node 執行階段將 `--env-file` 視為 Node 旗標。啟動 Gateway 的 Docker/Bash 通道可以在容器內 source `scripts/lib/openclaw-e2e-instance.sh`，用於進入點解析、模擬 OpenAI 啟動、Gateway 前景/背景啟動、就緒探測、狀態環境匯出、日誌傾印，以及程序清理。
-- 完整、擴充和 include-pattern 分片執行會更新 `.artifacts/vitest-shard-timings.json` 中的本機計時資料；之後的整體設定執行會使用這些計時來平衡慢速與快速分片。Include-pattern CI 分片會將分片名稱附加到計時鍵，讓篩選後的分片計時保持可見，而不取代整體設定計時資料。設定 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本機計時成品。
-- 選定的 `plugin-sdk` 和 `commands` 測試檔現在會透過專用輕量通道路由，只保留 `test/setup.ts`，讓執行階段較重的案例留在既有通道。
-- 有同層測試的來源檔會先對應到該同層測試，再退回到較寬的目錄 glob。`src/channels/plugins/contracts/test-helpers`、`src/plugin-sdk/test-helpers` 和 `src/plugins/contracts` 底下的輔助工具編輯會使用本機匯入圖來執行匯入它們的測試，而不是在相依路徑精準時廣泛執行每個分片。
-- `auto-reply` 現在也分割為三個專用設定（`core`、`top-level`、`reply`），讓回覆框架不會主導較輕量的頂層狀態/token/輔助工具測試。
-- 基礎 Vitest 設定現在預設為 `pool: "threads"` 和 `isolate: false`，並在整個儲存庫設定中啟用共享的非隔離 runner。
-- `pnpm test:channels` 執行 `vitest.channels.config.ts`。
-- `pnpm test:extensions` 和 `pnpm test extensions` 會執行所有擴充/Plugin 分片。較重的頻道 Plugin、瀏覽器 Plugin 和 OpenAI 會作為專用分片執行；其他 Plugin 群組維持批次處理。使用 `pnpm test extensions/<id>` 執行單一內建 Plugin 通道。
-- `pnpm test:perf:imports`：啟用 Vitest 匯入持續時間與匯入細目報告，同時仍對明確檔案/目錄目標使用有範圍的通道路由。
-- `pnpm test:perf:imports:changed`：相同的匯入效能分析，但只針對自 `origin/main` 以來變更的檔案。
-- `pnpm test:perf:changed:bench -- --ref <git-ref>` 會將路由後的 changed-mode 路徑，與同一個已提交 git 差異的原生根專案執行進行基準比較。
-- `pnpm test:perf:changed:bench -- --worktree` 會在不先提交的情況下，對目前工作樹變更集進行基準測試。
-- `pnpm test:perf:profile:main`：為 Vitest 主執行緒寫入 CPU profile（`.artifacts/vitest-main-profile`）。
-- `pnpm test:perf:profile:runner`：為單元 runner 寫入 CPU + heap profiles（`.artifacts/vitest-runner-profile`）。
-- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：序列執行每個完整套件 Vitest 葉層設定，並寫入分組持續時間資料，以及逐設定 JSON/日誌成品。Test Performance Agent 會在嘗試修復慢測試前，以此作為基準。
-- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在以效能為焦點的變更後比較分組報告。
+- `pnpm test:force`：終止任何仍占用預設控制埠的 Gateway 程序，然後使用隔離的 Gateway 埠執行完整 Vitest 套件，避免伺服器測試與正在執行的實例衝突。當先前的 Gateway 執行留下埠 18789 被占用時使用此命令。
+- `pnpm test:coverage`：使用 V8 覆蓋率執行單元套件（透過 `vitest.unit.config.ts`）。這是已載入檔案的單元覆蓋率閘門，不是整個儲存庫的所有檔案覆蓋率。閾值為 70% 行數/函式/陳述式，以及 55% 分支。因為 `coverage.all` 為 false，此閘門會測量單元覆蓋率套件載入的檔案，而不是將每個分割 lane 的原始檔視為未覆蓋。
+- `pnpm test:coverage:changed`：只對自 `origin/main` 以來變更的檔案執行單元覆蓋率。
+- `pnpm test:changed`：低成本的智慧變更測試執行。它會從直接測試編輯、同層 `*.test.ts` 檔案、明確來源對應，以及本機匯入圖執行精準目標。寬泛/config/package 變更會被略過，除非它們對應到精準測試。
+- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`：明確的寬泛變更測試執行。當測試框架/config/package 編輯應退回到 Vitest 較寬泛的變更測試行為時使用。
+- `pnpm changed:lanes`：顯示相對於 `origin/main` 的差異所觸發的架構 lane。
+- `pnpm check:changed`：針對相對於 `origin/main` 的差異執行智慧變更檢查閘門。它會針對受影響的架構 lane 執行 typecheck、lint 與 guard 命令，但不會執行 Vitest 測試。需要測試證明時，使用 `pnpm test:changed` 或明確的 `pnpm test <target>`。
+- `pnpm test`：將明確的檔案/目錄目標透過範圍化的 Vitest lane 路由。未指定目標的執行會使用固定 shard 群組，並展開為 leaf config 以供本機平行執行；extension 群組一律展開為逐 extension 的 shard config，而不是一個巨大的根專案程序。
+- 測試包裝器執行結束時會顯示簡短的 `[test] passed|failed|skipped ... in ...` 摘要。Vitest 自己的耗時行仍保留為每個 shard 的細節。
+- 共用 OpenClaw 測試狀態：當測試需要隔離的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、config fixture、workspace、agent dir 或 auth-profile store 時，在 Vitest 中使用 `src/test-utils/openclaw-test-state.ts`。
+- 程序 E2E 輔助工具：當 Vitest 程序層級 E2E 測試需要執行中的 Gateway、CLI env、日誌擷取與清理集中於一處時，使用 `test/helpers/openclaw-test-instance.ts`。
+- Docker/Bash E2E 輔助工具：source `scripts/lib/docker-e2e-image.sh` 的 lane 可將 `docker_e2e_test_state_shell_b64 <label> <scenario>` 傳入容器，並用 `scripts/lib/openclaw-e2e-instance.sh` 解碼；多 home 腳本可傳入 `docker_e2e_test_state_function_b64`，並在每個流程中呼叫 `openclaw_test_state_create <label> <scenario>`。較低階的呼叫端可使用 `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` 產生容器內 shell 片段，或使用 `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` 產生可 source 的主機 env 檔案。`create` 前面的 `--` 可避免較新的 Node runtime 將 `--env-file` 視為 Node flag。啟動 Gateway 的 Docker/Bash lane 可在容器內 source `scripts/lib/openclaw-e2e-instance.sh`，以取得 entrypoint 解析、mock OpenAI 啟動、Gateway 前景/背景啟動、就緒性探測、狀態 env 匯出、日誌傾印與程序清理。
+- 完整、extension 與 include-pattern shard 執行會更新 `.artifacts/vitest-shard-timings.json` 中的本機計時資料；之後的 whole-config 執行會使用這些計時來平衡慢速與快速 shard。Include-pattern CI shard 會將 shard 名稱附加到計時鍵，讓篩選後的 shard 計時保持可見，同時不取代 whole-config 計時資料。設定 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本機計時 artifact。
+- 選定的 `plugin-sdk` 與 `commands` 測試檔案現在會路由到專用輕量 lane，只保留 `test/setup.ts`，讓 runtime-heavy 案例維持在既有 lane 上。
+- 具有同層測試的原始檔會先對應到該同層測試，再退回到較寬泛的目錄 glob。`src/channels/plugins/contracts/test-helpers`、`src/plugin-sdk/test-helpers` 與 `src/plugins/contracts` 底下的 helper 編輯會使用本機匯入圖來執行匯入它們的測試，而不是在 dependency path 精準時寬泛執行每個 shard。
+- `auto-reply` 現在也分割為三個專用 config（`core`、`top-level`、`reply`），讓 reply harness 不會主導較輕量的 top-level status/token/helper 測試。
+- 基礎 Vitest config 現在預設為 `pool: "threads"` 與 `isolate: false`，並在整個儲存庫 config 啟用共用的非隔離 runner。
+- `pnpm test:channels` 會執行 `vitest.channels.config.ts`。
+- `pnpm test:extensions` 與 `pnpm test extensions` 會執行所有 extension/Plugin shard。重量級 channel Plugin、browser Plugin 與 OpenAI 會作為專用 shard 執行；其他 Plugin 群組維持批次執行。對單一 bundled Plugin lane 使用 `pnpm test extensions/<id>`。
+- `pnpm test:perf:imports`：啟用 Vitest 匯入耗時與匯入分解報告，同時仍對明確的檔案/目錄目標使用範圍化 lane 路由。
+- `pnpm test:perf:imports:changed`：相同的匯入 profiling，但只針對自 `origin/main` 以來變更的檔案。
+- `pnpm test:perf:changed:bench -- --ref <git-ref>`：針對同一個已提交的 git diff，比較 routed changed-mode path 與原生 root-project 執行的基準效能。
+- `pnpm test:perf:changed:bench -- --worktree`：不先提交，即對目前 worktree 變更集進行基準測試。
+- `pnpm test:perf:profile:main`：為 Vitest main thread 寫入 CPU profile（`.artifacts/vitest-main-profile`）。
+- `pnpm test:perf:profile:runner`：為 unit runner 寫入 CPU 與 heap profile（`.artifacts/vitest-runner-profile`）。
+- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：逐一序列執行每個 full-suite Vitest leaf config，並寫入分組耗時資料與每個 config 的 JSON/log artifact。Test Performance Agent 會將此作為嘗試修復慢速測試前的 baseline。
+- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在效能導向變更後比較分組報告。
 - Gateway 整合：透過 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 選擇加入。
-- `pnpm test:e2e`：執行 Gateway 端對端煙霧測試（多執行個體 WS/HTTP/node 配對）。預設為 `threads` + `isolate: false`，並在 `vitest.e2e.config.ts` 中使用自適應 workers；可用 `OPENCLAW_E2E_WORKERS=<n>` 調整，並設定 `OPENCLAW_E2E_VERBOSE=1` 取得詳細日誌。
-- `pnpm test:live`：執行提供者 live 測試（minimax/zai）。需要 API 金鑰和 `LIVE=1`（或提供者特定的 `*_LIVE_TEST=1`）才能取消略過。
-- `pnpm test:docker:all`：建置共享 live-test 映像檔，將 OpenClaw 一次打包為 npm tarball，建置/重用裸 Node/Git runner 映像檔，以及會將該 tarball 安裝到 `/app` 的功能映像檔，然後透過加權排程器以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行 Docker 煙霧通道。裸映像檔（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用於安裝器/更新/Plugin 相依性通道；這些通道會掛載預先建置的 tarball，而不是使用複製的儲存庫來源。功能映像檔（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）用於一般已建置應用程式功能通道。`scripts/package-openclaw-for-docker.mjs` 是單一本機/CI 套件打包器，並在 Docker 使用前驗證 tarball 與 `dist/postinstall-inventory.json`。Docker 通道定義位於 `scripts/lib/docker-e2e-scenarios.mjs`；規劃器邏輯位於 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 會執行選定的計畫。`node scripts/test-docker-all.mjs --plan-json` 會輸出排程器擁有的 CI 計畫，包含選定通道、映像種類、套件/live-image 需求、狀態場景，以及認證檢查，而不建置或執行 Docker。`OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 控制程序槽位，預設為 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` 控制對提供者敏感的尾端 pool，預設為 10。重型通道上限預設為 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；提供者上限預設為每個提供者一個重型通道，透過 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 和 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`。較大型主機可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。如果某個通道在低平行度主機上超過有效權重或資源上限，它仍可從空 pool 啟動，並會獨自執行直到釋放容量。通道啟動預設錯開 2 秒，以避免本機 Docker daemon 建立風暴；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>` 覆寫。Runner 預設會預先檢查 Docker、清理過期 OpenClaw E2E 容器、每 30 秒輸出作用中通道狀態、在相容通道之間共享提供者 CLI 工具快取、預設重試暫時性 live-provider 失敗一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`），並將通道計時儲存在 `.artifacts/docker-tests/lane-timings.json`，供之後執行時以最長優先排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可列印通道 manifest 而不執行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` 可調整狀態輸出，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 停用計時重用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 僅執行確定性/本機通道，或使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 僅執行 live-provider 通道；套件別名為 `pnpm test:docker:local:all` 和 `pnpm test:docker:live:all`。Live-only 模式會將主要與尾端 live 通道合併成一個最長優先 pool，讓提供者 bucket 能將 Claude、Codex 和 Gemini 工作一起打包。除非設定 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否則 runner 會在第一次失敗後停止排程新的 pooled 通道；每個通道都有 120 分鐘的備援逾時，可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆寫；選定的 live/tail 通道使用較嚴格的逐通道上限。CLI 後端 Docker 設定命令有自己的逾時，可透過 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 設定（預設 180）。逐通道日誌、`summary.json`、`failures.json` 和階段計時會寫入 `.artifacts/docker-tests/<run-id>/` 底下；使用 `pnpm test:docker:timings <summary.json>` 檢查慢速通道，使用 `pnpm test:docker:rerun <run-id|summary.json|failures.json>` 列印低成本的目標式重跑命令。
-- `pnpm test:docker:browser-cdp-snapshot`：建置由 Chromium 支援的來源 E2E 容器，啟動原始 CDP 加上隔離的 Gateway，執行 `browser doctor --deep`，並驗證 CDP 角色快照包含連結 URL、游標提升的可點擊項目、iframe 參照，以及 frame 中繼資料。
-- CLI 後端 live Docker 探測可以作為聚焦通道執行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 和 Gemini 有相對應的 `:resume` 與 `:mcp` 別名。
-- `pnpm test:docker:openwebui`：啟動 Docker 化的 OpenClaw + Open WebUI，透過 Open WebUI 登入，檢查 `/api/models`，然後透過 `/api/chat/completions` 執行真實的代理聊天。需要可用的 live 模型金鑰（例如 `~/.profile` 中的 OpenAI）、會拉取外部 Open WebUI 映像檔，且不預期像一般單元/e2e 套件一樣具備 CI 穩定性。
-- `pnpm test:docker:mcp-channels`：啟動已植入資料的 Gateway 容器，以及第二個會產生 `openclaw mcp serve` 的用戶端容器，然後驗證路由後的對話探索、transcript 讀取、附件中繼資料、live 事件佇列行為、對外傳送路由，以及真實 stdio bridge 上的 Claude 風格頻道 + 權限通知。Claude 通知斷言會直接讀取原始 stdio MCP frames，因此煙霧測試會反映 bridge 實際輸出的內容。
-- `pnpm test:docker:upgrade-survivor`：將打包好的 OpenClaw tarball 安裝到髒的舊使用者 fixture 上，執行套件更新加上不含即時 provider 或通道金鑰的非互動式 doctor，接著啟動迴路 Gateway，並檢查代理程式、通道設定、Plugin 允許清單、工作區/工作階段檔案、過時的舊版 Plugin 相依狀態、啟動與 RPC 狀態是否保留下來。
-- `pnpm test:docker:published-upgrade-survivor`：預設安裝 `openclaw@latest`，植入不含即時 provider 或通道金鑰的擬真既有使用者檔案，使用內建的 `openclaw config set` 命令配方設定該基準，將該已發布安裝更新到打包好的 OpenClaw tarball，執行非互動式 doctor，寫入 `.artifacts/upgrade-survivor/summary.json`，接著啟動迴路 Gateway，並檢查已設定的意圖、工作區/工作階段檔案、過時的 Plugin 設定與舊版相依狀態、啟動、`/healthz`、`/readyz` 與 RPC 狀態是否保留下來或能乾淨修復。用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 覆寫單一基準，用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 展開精確矩陣，例如 `all-since-2026.4.23`，或用 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 新增情境 fixture；reported-issues 集合包含 `configured-plugin-installs`，用來驗證已設定的外部 OpenClaw Plugin 會在升級期間自動安裝。Package Acceptance 會將這些公開為 `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines` 與 `published_upgrade_survivor_scenarios`。
-- `pnpm test:docker:update-migration`：在清理量大的 `plugin-deps-cleanup` 情境中執行已發布升級存活性 harness，預設從 `openclaw@2026.4.23` 開始。獨立的 `Update Migration` 工作流程會用 `baselines=all-since-2026.4.23` 展開這個 lane，讓從 `.23` 起的每個穩定已發布套件都更新到候選版本，並在 Full Release CI 之外證明已設定 Plugin 的相依清理。
-- `pnpm test:docker:plugins`：針對本機路徑、`file:`、具有 hoisted 相依的 npm registry 套件、git 移動 refs、ClawHub fixture、marketplace 更新，以及 Claude-bundle 啟用/檢查執行安裝/更新 smoke。
+- `pnpm test:e2e`：執行 Gateway 端到端 smoke 測試（多實例 WS/HTTP/node pairing）。預設使用 `threads` + `isolate: false`，並在 `vitest.e2e.config.ts` 中使用自適應 worker；可用 `OPENCLAW_E2E_WORKERS=<n>` 調整，並設定 `OPENCLAW_E2E_VERBOSE=1` 取得詳細日誌。
+- `pnpm test:live`：執行 provider live 測試（minimax/zai）。需要 API key 與 `LIVE=1`（或 provider-specific `*_LIVE_TEST=1`）才能取消略過。
+- `pnpm test:docker:all`：建置共用 live-test image，將 OpenClaw 打包一次為 npm tarball，建置/重用 bare Node/Git runner image，以及把該 tarball 安裝到 `/app` 的 functional image，接著透過 weighted scheduler 使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行 Docker smoke lane。bare image（`OPENCLAW_DOCKER_E2E_BARE_IMAGE`）用於 installer/update/plugin-dependency lane；這些 lane 會掛載預先建置的 tarball，而不是使用複製的儲存庫來源。functional image（`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`）用於一般 built-app functionality lane。`scripts/package-openclaw-for-docker.mjs` 是唯一的本機/CI package packer，並會在 Docker 使用前驗證 tarball 與 `dist/postinstall-inventory.json`。Docker lane 定義位於 `scripts/lib/docker-e2e-scenarios.mjs`；planner 邏輯位於 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 會執行選定的 plan。`node scripts/test-docker-all.mjs --plan-json` 會輸出 scheduler 擁有的 CI plan，內容包含選定 lane、image kind、package/live-image 需求、state scenario 與 credential check，而不建置或執行 Docker。`OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 控制程序 slot，預設為 10；`OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` 控制 provider-sensitive tail pool，預設為 10。重量級 lane cap 預設為 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 與 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；provider cap 預設透過 `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`、`OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` 與 `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`，每個 provider 一條重量級 lane。較大型主機可使用 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。如果某個 lane 在低平行度主機上超過有效 weight 或 resource cap，它仍可從空 pool 開始，並會獨自執行直到釋放容量。lane 啟動預設交錯 2 秒，以避免本機 Docker daemon create storm；可用 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>` 覆寫。runner 預設會 preflight Docker、清理 stale OpenClaw E2E 容器、每 30 秒輸出 active-lane 狀態、在相容 lane 之間共用 provider CLI 工具 cache、預設重試 transient live-provider failure 一次（`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`），並將 lane timing 儲存在 `.artifacts/docker-tests/lane-timings.json`，供後續執行以 longest-first 排序。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可印出 lane manifest 而不執行 Docker，使用 `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` 可調整狀態輸出，或使用 `OPENCLAW_DOCKER_ALL_TIMINGS=0` 停用計時重用。使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` 僅執行 deterministic/local lane，或使用 `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` 僅執行 live-provider lane；package alias 為 `pnpm test:docker:local:all` 與 `pnpm test:docker:live:all`。Live-only 模式會將 main 與 tail live lane 合併為單一 longest-first pool，讓 provider bucket 可一起打包 Claude、Codex 與 Gemini 工作。除非設定 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，runner 會在第一次失敗後停止排程新的 pooled lane，且每個 lane 都有 120 分鐘 fallback timeout，可用 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆寫；選定的 live/tail lane 使用較嚴格的每 lane cap。CLI backend Docker setup 命令有自己的 timeout，可透過 `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` 設定（預設 180）。每個 lane 的日誌、`summary.json`、`failures.json` 與 phase timing 會寫入 `.artifacts/docker-tests/<run-id>/` 底下；使用 `pnpm test:docker:timings <summary.json>` 檢查慢速 lane，並使用 `pnpm test:docker:rerun <run-id|summary.json|failures.json>` 印出低成本的精準 rerun 命令。
+- `pnpm test:docker:browser-cdp-snapshot`：建置以 Chromium 為後端的 source E2E 容器，啟動 raw CDP 加上一個隔離的 Gateway，執行 `browser doctor --deep`，並驗證 CDP role snapshot 包含 link URL、cursor-promoted clickable、iframe ref 與 frame metadata。
+- CLI backend live Docker probe 可作為聚焦 lane 執行，例如 `pnpm test:docker:live-cli-backend:codex`、`pnpm test:docker:live-cli-backend:codex:resume` 或 `pnpm test:docker:live-cli-backend:codex:mcp`。Claude 與 Gemini 也有相對應的 `:resume` 與 `:mcp` alias。
+- `pnpm test:docker:openwebui`：啟動 Docker 化的 OpenClaw + Open WebUI，透過 Open WebUI 登入，檢查 `/api/models`，然後透過 `/api/chat/completions` 執行真實的 proxied chat。需要可用的 live model key（例如 `~/.profile` 中的 OpenAI）、會拉取外部 Open WebUI image，且不預期像一般 unit/e2e 套件一樣 CI-stable。
+- `pnpm test:docker:mcp-channels`：啟動 seeded Gateway 容器與第二個 client 容器，後者會產生 `openclaw mcp serve`，接著驗證 routed conversation discovery、transcript read、attachment metadata、live event queue 行為、outbound send routing，以及透過真實 stdio bridge 的 Claude-style channel + permission notification。Claude notification assertion 會直接讀取 raw stdio MCP frame，因此 smoke 會反映 bridge 實際發出的內容。
+- `pnpm test:docker:upgrade-survivor`：將打包好的 OpenClaw tarball 安裝到狀態不乾淨的舊使用者測試夾具上，執行套件更新與非互動式診斷，且不使用即時提供者或頻道金鑰，接著啟動 local loopback Gateway，並檢查代理、頻道設定、Plugin 允許清單、工作區/工作階段檔案、過期的舊版 Plugin 相依狀態、啟動流程與 RPC 狀態都能保留下來。
+- `pnpm test:docker:published-upgrade-survivor`：預設安裝 `openclaw@latest`，植入不含即時提供者或頻道金鑰的擬真既有使用者檔案，使用內建的 `openclaw config set` 命令配方設定該基準，將該已發布安裝更新為打包好的 OpenClaw tarball，執行非互動式診斷，寫入 `.artifacts/upgrade-survivor/summary.json`，接著啟動 local loopback Gateway，並檢查已設定的意圖、工作區/工作階段檔案、過期的 Plugin 設定與舊版相依狀態、啟動流程、`/healthz`、`/readyz` 與 RPC 狀態都能保留下來或乾淨修復。使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 覆寫單一基準，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 展開精確矩陣，例如 `all-since-2026.4.23`，或使用 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` 加入情境測試夾具；reported-issues 集合包含 `configured-plugin-installs`，用來驗證已設定的外部 OpenClaw plugins 會在升級期間自動安裝，也包含 `stale-source-plugin-shadow`，用來避免僅存在於原始碼的 Plugin 遮蔽破壞啟動流程。Package Acceptance 會將這些公開為 `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines` 與 `published_upgrade_survivor_scenarios`。
+- `pnpm test:docker:update-migration`：在清理工作較重的 `plugin-deps-cleanup` 情境中執行已發布升級存活檢查工具，預設從 `openclaw@2026.4.23` 開始。獨立的 `Update Migration` workflow 會以 `baselines=all-since-2026.4.23` 展開此路徑，讓 `.23` 之後每個穩定發布的套件都更新到候選版本，並在 Full Release CI 之外證明已設定 Plugin 的相依清理可正常運作。
+- `pnpm test:docker:plugins`：針對本機路徑、`file:`、含提升相依的 npm registry 套件、git 移動參照、ClawHub 測試夾具、市集更新，以及 Claude 套裝啟用/檢查，執行安裝/更新冒煙測試。
 
-## 本機 PR 門檻檢查
+## 本機 PR 關卡
 
-若要在本機進行 PR 合併/門檻檢查，請執行：
+若要在本機執行 PR 合併/關卡檢查，請執行：
 
 - `pnpm check:changed`
 - `pnpm check`
@@ -66,20 +66,20 @@ x-i18n:
 - `pnpm test`
 - `pnpm check:docs`
 
-如果 `pnpm test` 在負載較高的主機上發生不穩定失敗，請先重新執行一次，再將其視為回歸問題；接著使用 `pnpm test <path/to/test>` 隔離問題。對於記憶體受限的主機，請使用：
+如果 `pnpm test` 在負載高的主機上出現不穩定失敗，請先重新執行一次，再將其視為回歸；接著用 `pnpm test <path/to/test>` 隔離問題。對於記憶體受限的主機，請使用：
 
 - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
 - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
 
 ## 模型延遲基準測試（本機金鑰）
 
-腳本：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
+指令碼：[`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
 
 用法：
 
 - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
 - 選用環境變數：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY`
-- 預設提示：「用單一詞回覆：ok。不要標點或額外文字。」
+- 預設提示詞：「請只回覆一個單字：ok。不要標點符號或額外文字。」
 
 上次執行（2025-12-31，20 次執行）：
 
@@ -88,7 +88,7 @@ x-i18n:
 
 ## CLI 啟動基準測試
 
-腳本：[`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
+指令碼：[`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
 
 用法：
 
@@ -114,35 +114,35 @@ x-i18n:
 - `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`tasks --json`、`tasks list --json`、`tasks audit --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port`
 - `all`：兩個預設集
 
-輸出包含每個命令的 `sampleCount`、平均值、p50、p95、最小/最大值、退出碼/訊號分布，以及最大 RSS 摘要。選用的 `--cpu-prof-dir` / `--heap-prof-dir` 會為每次執行寫入 V8 profile，讓計時與 profile 擷取使用相同的測試框架。
+輸出包含每個命令的 `sampleCount`、avg、p50、p95、min/max、退出碼/訊號分布，以及最大 RSS 摘要。選用的 `--cpu-prof-dir` / `--heap-prof-dir` 會為每次執行寫入 V8 profiles，讓計時與 profile 擷取使用相同的 harness。
 
 已儲存輸出慣例：
 
-- `pnpm test:startup:bench:smoke` 會將目標煙霧測試成品寫入 `.artifacts/cli-startup-bench-smoke.json`
-- `pnpm test:startup:bench:save` 會使用 `runs=5` 和 `warmup=1` 將完整套件成品寫入 `.artifacts/cli-startup-bench-all.json`
-- `pnpm test:startup:bench:update` 會使用 `runs=5` 和 `warmup=1` 重新整理簽入的基準 fixture，位置為 `test/fixtures/cli-startup-bench.json`
+- `pnpm test:startup:bench:smoke` 會將目標煙霧測試 artifact 寫入 `.artifacts/cli-startup-bench-smoke.json`
+- `pnpm test:startup:bench:save` 會使用 `runs=5` 和 `warmup=1`，將完整套件 artifact 寫入 `.artifacts/cli-startup-bench-all.json`
+- `pnpm test:startup:bench:update` 會使用 `runs=5` 和 `warmup=1`，重新整理已提交的基準 fixture `test/fixtures/cli-startup-bench.json`
 
-簽入的 fixture：
+已提交的 fixture：
 
 - `test/fixtures/cli-startup-bench.json`
 - 使用 `pnpm test:startup:bench:update` 重新整理
 - 使用 `pnpm test:startup:bench:check` 將目前結果與 fixture 比較
 
-## Onboarding E2E（Docker）
+## 入門 E2E（Docker）
 
-Docker 是選用項；只有在容器化 onboarding 煙霧測試時才需要。
+Docker 是選用的；這只在容器化入門煙霧測試中需要。
 
-在乾淨的 Linux 容器中執行完整冷啟動流程：
+在乾淨 Linux 容器中的完整冷啟動流程：
 
 ```bash
 scripts/e2e/onboard-docker.sh
 ```
 
-此腳本會透過 pseudo-tty 驅動互動式精靈，驗證設定/工作區/session 檔案，然後啟動 Gateway 並執行 `openclaw health`。
+這個指令碼會透過 pseudo-tty 驅動互動式精靈，驗證 config/workspace/session 檔案，接著啟動 Gateway 並執行 `openclaw health`。
 
 ## QR 匯入煙霧測試（Docker）
 
-確保維護中的 QR 執行階段輔助程式可在支援的 Docker Node 執行階段下載入（Node 24 預設、Node 22 相容）：
+確保維護中的 QR 執行階段輔助工具可在支援的 Docker Node 執行階段下載入（Node 24 預設，Node 22 相容）：
 
 ```bash
 pnpm test:docker:qr
@@ -152,4 +152,4 @@ pnpm test:docker:qr
 
 - [測試](/zh-TW/help/testing)
 - [即時測試](/zh-TW/help/testing-live)
-- [測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)
+- [測試更新與 plugins](/zh-TW/help/testing-updates-plugins)

docs/zh-TW/reference/transcript-hygiene.md

@@ -1,213 +1,179 @@
 ---
 read_when:
-    - 你正在偵錯與對話紀錄結構相關的提供者請求遭拒問題
-    - 您正在變更對話記錄清理或工具呼叫修復邏輯
-    - 你正在調查跨提供者的工具呼叫識別碼不相符問題
-summary: 參考：供應商特定的對話記錄清理與修復規則
+    - 你正在偵錯與對話記錄結構相關的提供者請求遭拒問題
+    - 你正在變更對話記錄清理或工具呼叫修復邏輯
+    - 你正在調查不同提供者之間的工具呼叫 ID 不一致問題
+summary: 參考：特定提供者的對話記錄清理與修復規則
 title: 對話記錄整理
 x-i18n:
-    generated_at: "2026-05-03T21:42:45Z"
+    generated_at: "2026-05-05T01:49:24Z"
     model: gpt-5.5
     provider: openai
-    source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
+    source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
     source_path: reference/transcript-hygiene.md
     workflow: 16
 ---
 
-OpenClaw 會在執行前（建構模型上下文時）對轉錄套用**供應商專屬修正**。其中大多數是為了滿足嚴格供應商要求而使用的**記憶體內**調整。另有一個獨立的工作階段檔案修復流程，也可能在載入工作階段前重寫已儲存的 JSONL，但只限於格式錯誤的行或無效持久記錄的已持久化回合。已傳遞的助理回覆會保留在磁碟上；供應商專屬的助理預填內容剝除只會在建構外送承載資料時發生。發生修復時，原始檔案會在工作階段檔案旁一併備份。
+OpenClaw 會在執行前（建構模型上下文時）對逐字記錄套用**特定提供者修正**。其中大多數是**記憶體內**調整，用來滿足嚴格的提供者要求。另一個工作階段檔案修復流程也可能在載入工作階段前重寫已儲存的 JSONL，但只限於格式錯誤的行，或作為持久記錄無效的已保存回合。已傳遞的助理回覆會保留在磁碟上；特定提供者的助理預填內容移除只會在建構對外承載資料時發生。發生修復時，原始檔案會在工作階段檔案旁一併備份。
 
-範圍包括：
+範圍包含：
 
-- 僅執行期使用的提示上下文不會進入使用者可見的轉錄回合
-- 工具呼叫 id 淨化
+- 僅限執行階段的提示上下文不進入使用者可見的逐字記錄回合
+- 工具呼叫 ID 清理
 - 工具呼叫輸入驗證
 - 工具結果配對修復
-- 回合驗證 / 排序
+- 回合驗證／排序
 - 思考簽章清理
 - Thinking 簽章清理
-- 圖片承載資料淨化
-- 在供應商重播前清理空白文字區塊
-- 使用者輸入來源標記（用於跨工作階段路由的提示）
-- Bedrock Converse 重播的空助理錯誤回合修復
+- 圖片承載資料清理
+- 提供者重放前的空白文字區塊清理
+- 使用者輸入來源標記（用於跨工作階段路由提示）
+- Bedrock Converse 重放的空助理錯誤回合修復
 
-如果你需要轉錄儲存詳細資訊，請參閱：
+如果你需要逐字記錄儲存詳細資訊，請參閱：
 
-- [工作階段管理深入說明](/zh-TW/reference/session-management-compaction)
+- [工作階段管理深入解析](/zh-TW/reference/session-management-compaction)
 
 ---
 
-## 全域規則：執行期上下文不是使用者轉錄
+## 全域規則：執行階段上下文不是使用者逐字記錄
 
-執行期/系統上下文可以加入某個回合的模型提示，但它不是
-終端使用者撰寫的內容。OpenClaw 會為 Gateway 回覆、排入佇列的後續訊息、ACP、CLI，以及嵌入式 Pi
-執行保留一份獨立的面向轉錄提示本文。已儲存的可見使用者回合會使用該轉錄本文，而不是
-加入執行期內容的提示。
+執行階段／系統上下文可以新增到某個回合的模型提示中，但它不是終端使用者撰寫的內容。OpenClaw 會為 Gateway 回覆、佇列中的後續回覆、ACP、CLI，以及嵌入式 Pi 執行，保留獨立的逐字記錄用提示本文。已儲存的可見使用者回合會使用該逐字記錄本文，而不是加入執行階段內容後的提示。
 
-對於已經持久化執行期包裝的舊版工作階段，Gateway 歷史
-介面會先套用顯示投影，再將訊息回傳給 WebChat、
-TUI、REST 或 SSE 用戶端。
+對於已保存執行階段包裝器的舊版工作階段，Gateway 歷史記錄介面在將訊息回傳給 WebChat、TUI、REST 或 SSE 用戶端前，會套用顯示投影。
 
 ---
 
 ## 執行位置
 
-所有轉錄衛生處理都集中在嵌入式執行器中：
+所有逐字記錄衛生處理都集中在嵌入式執行器中：
 
 - 政策選擇：`src/agents/transcript-policy.ts`
-- 淨化/修復套用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory`
+- 清理／修復套用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory`
 
-此政策會使用 `provider`、`modelApi` 和 `modelId` 來決定要套用的項目。
+此政策會使用 `provider`、`modelApi` 和 `modelId` 來決定要套用哪些處理。
 
-與轉錄衛生處理分開的是，工作階段檔案會在載入前視需要修復：
+與逐字記錄衛生處理分開，工作階段檔案會在載入前修復（如有需要）：
 
 - `src/agents/session-file-repair.ts` 中的 `repairSessionFileIfNeeded`
 - 從 `run/attempt.ts` 和 `compact.ts`（嵌入式執行器）呼叫
 
 ---
 
-## 全域規則：圖片淨化
+## 全域規則：圖片清理
 
-圖片承載資料一律會被淨化，以避免因大小
-限制導致供應商端拒絕（縮小/重新壓縮過大的 base64 圖片）。
+圖片承載資料一律會清理，以避免因大小限制而遭提供者端拒絕（縮小／重新壓縮過大的 base64 圖片）。
 
-這也有助於控制支援視覺模型中圖片造成的 token 壓力。
-較低的最大尺寸通常會減少 token 用量；較高的尺寸則保留細節。
+這也有助於控制支援視覺模型的圖片驅動 token 壓力。較低的最大尺寸通常會降低 token 使用量；較高的尺寸會保留細節。
 
 實作：
 
 - `src/agents/pi-embedded-helpers/images.ts` 中的 `sanitizeSessionMessagesImages`
 - `src/agents/tool-images.ts` 中的 `sanitizeContentBlocksImages`
 - 最大圖片邊長可透過 `agents.defaults.imageMaxDimensionPx` 設定（預設：`1200`）。
-- 此流程走訪重播內容時會移除空白文字區塊。變成空的助理
-  回合會從重播副本中丟棄；變成空的使用者與工具結果
-  回合會收到非空的省略內容預留位置。
+- 此流程走訪重放內容時會移除空白文字區塊。變成空的助理回合會從重放副本中移除；變成空的使用者與工具結果回合會收到非空的已省略內容佔位符。
 
 ---
 
 ## 全域規則：格式錯誤的工具呼叫
 
-缺少 `input` 和 `arguments` 的助理工具呼叫區塊會在建構
-模型上下文前被丟棄。這可防止部分
-持久化工具呼叫造成供應商拒絕（例如，在速率限制失敗之後）。
+在建構模型上下文前，缺少 `input` 和 `arguments` 兩者的助理工具呼叫區塊會被丟棄。這可避免因部分保存的工具呼叫而遭提供者拒絕（例如，在速率限制失敗後）。
 
 實作：
 
 - `src/agents/session-transcript-repair.ts` 中的 `sanitizeToolCallInputs`
-- 在 `src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` 套用
+- 在 `src/agents/pi-embedded-runner/replay-history.ts` 的 `sanitizeSessionHistory` 中套用
 
 ---
 
 ## 全域規則：跨工作階段輸入來源
 
-當代理透過 `sessions_send` 將提示送入另一個工作階段時（包括
-代理到代理的回覆/公告步驟），OpenClaw 會將建立的使用者回合持久化為：
+當某個代理透過 `sessions_send` 將提示傳送到另一個工作階段（包含代理對代理的回覆／公告步驟）時，OpenClaw 會保存所建立的使用者回合，並帶有：
 
 - `message.provenance.kind = "inter_session"`
 
-OpenClaw 也會在路由後的提示文字前，加上同一回合的 `[Inter-session message ... isUser=false]`
-標記，讓目前作用中的模型呼叫可以區分
-外來工作階段輸出與外部終端使用者指令。此標記在可用時會包含
-來源工作階段、頻道與工具。為了供應商相容性，轉錄仍使用
-`role: "user"`，但可見文字與來源中繼資料都會將該回合標記為跨工作階段資料。
+OpenClaw 也會在路由的提示文字前方加上同一回合的 `[Inter-session message ... isUser=false]` 標記，讓作用中的模型呼叫能區分外部工作階段輸出與外部終端使用者指令。可用時，此標記會包含來源工作階段、通道和工具。為了提供者相容性，逐字記錄仍會使用 `role: "user"`，但可見文字與來源中繼資料都會將該回合標記為跨工作階段資料。
 
-在重建上下文期間，OpenClaw 會對較舊且只具有來源中繼資料的已持久化
-跨工作階段使用者回合套用同樣的標記。
+重建上下文期間，OpenClaw 會對較舊、只有來源中繼資料的已保存跨工作階段使用者回合套用相同標記。
 
 ---
 
-## 供應商矩陣（目前行為）
+## 提供者矩陣（目前行為）
 
 **OpenAI / OpenAI Codex**
 
-- 僅圖片淨化。
-- 對 OpenAI Responses/Codex 轉錄丟棄孤立的推理簽章（沒有後續內容區塊的獨立推理項目），並在模型路由切換後丟棄可重播的 OpenAI 推理。
-- 保留可重播的 OpenAI Responses 推理項目承載資料，包括加密的空摘要項目，讓手動/WebSocket 重播能將必要的 `rs_*` 狀態與助理輸出項目配對。
-- 不進行工具呼叫 id 淨化。
-- 工具結果配對修復可能會移動真正相符的輸出，並為遺失的工具呼叫合成 Codex 風格的 `aborted` 輸出。
+- 僅進行圖片清理。
+- 對 OpenAI Responses/Codex 逐字記錄，丟棄孤立的推理簽章（沒有後續內容區塊的獨立推理項目），並在模型路由切換後丟棄可重放的 OpenAI 推理。
+- 保留可重放的 OpenAI Responses 推理項目承載資料，包含加密的空摘要項目，讓手動/WebSocket 重放能保留必要的 `rs_*` 狀態，並與助理輸出項目配對。
+- 原生 ChatGPT Codex Responses 會遵循 Codex 線路一致性，重放先前的 Responses 推理／訊息／函式承載資料，但不帶先前項目 ID，同時保留工作階段 `prompt_cache_key`。
+- 不進行工具呼叫 ID 清理。
+- 工具結果配對修復可能會移動真實且已匹配的輸出，並為缺少的工具呼叫合成 Codex 風格的 `aborted` 輸出。
 - 不進行回合驗證或重新排序。
-- 遺失的 OpenAI Responses 系列工具輸出會被合成為 `aborted`，以符合 Codex 重播正規化。
-- 不剝除思考簽章。
+- 缺少的 OpenAI Responses 系列工具輸出會被合成為 `aborted`，以符合 Codex 重放正規化。
+- 不移除思考簽章。
 
 **OpenAI 相容 Gemma 4**
 
-- 歷史助理 thinking/reasoning 區塊會在重播前被剝除，因此本機
-  OpenAI 相容 Gemma 4 伺服器不會收到前一回合的推理內容。
-- 目前同一回合的工具呼叫延續會保留附加在工具呼叫上的助理推理區塊，
-  直到工具結果已被重播。
+- 歷史助理 thinking/reasoning 區塊會在重放前移除，讓本機 OpenAI 相容 Gemma 4 伺服器不會收到先前回合的推理內容。
+- 目前同一回合的工具呼叫延續會保留附加到工具呼叫上的助理推理區塊，直到工具結果已被重放。
 
 **Google（Generative AI / Gemini CLI / Antigravity）**
 
-- 工具呼叫 id 淨化：嚴格英數字元。
+- 工具呼叫 ID 清理：嚴格英數字。
 - 工具結果配對修復與合成工具結果。
 - 回合驗證（Gemini 風格的回合交替）。
-- Google 回合排序修正（若歷史以助理開頭，則前置一個極小的使用者 bootstrap）。
+- Google 回合排序修正（如果歷史記錄以助理開頭，則前置一個很小的使用者啟動訊息）。
 - Antigravity Claude：正規化 thinking 簽章；丟棄未簽署的 thinking 區塊。
 
 **Anthropic / Minimax（Anthropic 相容）**
 
 - 工具結果配對修復與合成工具結果。
-- 回合驗證（合併連續使用者回合以滿足嚴格交替）。
-- 啟用 thinking 時，尾端的助理預填回合會從外送 Anthropic Messages
-  承載資料中剝除，包括 Cloudflare AI Gateway 路由。
-- 缺少、空白或空字串重播簽章的 Thinking 區塊會在
-  供應商轉換前被剝除。如果這讓助理回合變空，OpenClaw 會以非空的省略推理文字
-  保留回合形狀。
-- 較舊且必須剝除的純 thinking 助理回合會被取代為
-  非空的省略推理文字，讓供應商配接器不會丟棄重播
-  回合。
+- 回合驗證（合併連續的使用者回合，以滿足嚴格交替）。
+- 啟用 thinking 時，尾端助理預填回合會從對外 Anthropic Messages 承載資料中移除，包含 Cloudflare AI Gateway 路由。
+- 缺少、空值或空白重放簽章的 thinking 區塊會在提供者轉換前移除。如果這使助理回合變空，OpenClaw 會用非空的已省略推理文字保留回合形狀。
+- 必須移除的較舊 thinking-only 助理回合會以非空的已省略推理文字取代，讓提供者轉接器不會丟棄重放回合。
 
 **Amazon Bedrock（Converse API）**
 
-- 空的助理串流錯誤回合會在重播前修復為非空的備援文字區塊。
-  Bedrock Converse 會拒絕含有 `content: []` 的助理訊息，因此
-  具有 `stopReason: "error"` 且內容為空的已持久化助理回合也會
-  在載入前於磁碟上修復。
-- 只包含空白文字區塊的助理串流錯誤回合會
-  從記憶體內重播副本中丟棄，而不是重播無效的空白區塊。
-- 缺少、空白或空字串重播簽章的 Claude thinking 區塊會
-  在 Converse 重播前被剝除。如果這讓助理回合變空，OpenClaw
-  會以非空的省略推理文字保留回合形狀。
-- 較舊且必須剝除的純 thinking 助理回合會被取代為
-  非空的省略推理文字，讓 Converse 重播保留嚴格的回合形狀。
-- 重播會過濾 OpenClaw 傳遞鏡像與 Gateway 注入的助理回合。
-- 圖片淨化會依全域規則套用。
+- 空助理串流錯誤回合會在重放前修復為非空的備援文字區塊。Bedrock Converse 會拒絕 `content: []` 的助理訊息，因此帶有 `stopReason: "error"` 且內容為空的已保存助理回合，也會在載入前於磁碟上修復。
+- 只包含空白文字區塊的助理串流錯誤回合會從記憶體內重放副本中丟棄，而不是重放無效的空白區塊。
+- 缺少、空值或空白重放簽章的 Claude thinking 區塊會在 Converse 重放前移除。如果這使助理回合變空，OpenClaw 會用非空的已省略推理文字保留回合形狀。
+- 必須移除的較舊 thinking-only 助理回合會以非空的已省略推理文字取代，讓 Converse 重放保留嚴格回合形狀。
+- 重放會過濾 OpenClaw 傳遞鏡像與 Gateway 注入的助理回合。
+- 圖片清理會透過全域規則套用。
 
-**Mistral（包括基於 model-id 的偵測）**
+**Mistral（包含以 model-id 為基礎的偵測）**
 
-- 工具呼叫 id 淨化：strict9（長度 9 的英數字元）。
+- 工具呼叫 ID 清理：strict9（英數字長度 9）。
 
 **OpenRouter Gemini**
 
-- 思考簽章清理：剝除非 base64 的 `thought_signature` 值（保留 base64）。
+- 思考簽章清理：移除非 base64 的 `thought_signature` 值（保留 base64）。
 
 **OpenRouter Anthropic**
 
-- 啟用 reasoning 時，尾端助理預填回合會從已驗證的 OpenRouter
-  OpenAI 相容 Anthropic 模型承載資料中剝除，與
-  直接 Anthropic 和 Cloudflare Anthropic 重播行為一致。
+- 啟用 reasoning 時，尾端助理預填回合會從已驗證的 OpenRouter OpenAI 相容 Anthropic 模型承載資料中移除，以符合直接 Anthropic 與 Cloudflare Anthropic 重放行為。
 
 **其他所有項目**
 
-- 僅圖片淨化。
+- 僅進行圖片清理。
 
 ---
 
-## 歷史行為（2026.1.22 之前）
+## 歷史行為（2026.1.22 前）
 
-在 2026.1.22 版本之前，OpenClaw 會套用多層轉錄衛生處理：
+在 2026.1.22 版本之前，OpenClaw 會套用多層逐字記錄衛生處理：
 
-- 一個**轉錄淨化 Plugin**會在每次上下文建構時執行，並且可以：
-  - 修復工具使用/結果配對。
-  - 淨化工具呼叫 id（包括保留 `_`/`-` 的非嚴格模式）。
-- 執行器也會執行供應商專屬淨化，造成重複工作。
-- 額外的變更也會在供應商政策之外發生，包括：
-  - 在持久化前從助理文字剝除 `<final>` 標籤。
-  - 丟棄空的助理錯誤回合。
+- **transcript-sanitize extension** 會在每次上下文建構時執行，並且可以：
+  - 修復工具使用／結果配對。
+  - 清理工具呼叫 ID（包含會保留 `_`/`-` 的非嚴格模式）。
+- 執行器也會執行特定提供者清理，造成重複工作。
+- 其他變更發生在提供者政策之外，包含：
+  - 在保存前從助理文字移除 `<final>` 標籤。
+  - 丟棄空助理錯誤回合。
   - 在工具呼叫後修剪助理內容。
 
-這種複雜性造成跨供應商回歸（尤其是 `openai-responses`
-`call_id|fc_id` 配對）。2026.1.22 清理移除了 extension，將
-邏輯集中到執行器，並讓 OpenAI 除圖片淨化外保持**不碰觸**。
+這種複雜性造成跨提供者回歸（特別是 `openai-responses` 的 `call_id|fc_id` 配對）。2026.1.22 清理移除了 extension，將邏輯集中到執行器中，並讓 OpenAI 除了圖片清理之外**不做觸碰**。
 
 ## 相關
 

docs/zh-TW/security/network-proxy.md

@@ -1,40 +1,40 @@
 ---
 read_when:
-    - 你希望針對 SSRF 與 DNS 重綁定攻擊採取縱深防禦
+    - 你希望針對 SSRF 和 DNS 重新綁定攻擊採取縱深防禦
     - 為 OpenClaw 執行階段流量設定外部正向代理
-summary: 如何透過由操作人員管理的篩選代理伺服器路由 OpenClaw 執行階段的 HTTP 與 WebSocket 流量
+summary: 如何將 OpenClaw 執行階段 HTTP 與 WebSocket 流量透過由操作員管理的篩選代理伺服器路由
 title: 網路代理
 x-i18n:
-    generated_at: "2026-05-04T18:24:32Z"
+    generated_at: "2026-05-05T01:49:21Z"
     model: gpt-5.5
     provider: openai
-    source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
+    source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
     source_path: security/network-proxy.md
     workflow: 16
 ---
 
 # 網路代理
 
-OpenClaw 可以透過操作者管理的正向代理，路由執行階段的 HTTP 與 WebSocket 流量。對於想要集中出口控制、更強 SSRF 防護，以及更佳網路可稽核性的部署，這是選用的縱深防禦措施。
+OpenClaw 可以透過由操作員管理的正向代理，路由執行階段的 HTTP 和 WebSocket 流量。對於想要集中出口控制、更強 SSRF 防護，以及更好的網路稽核性的部署，這是選用的深層防禦措施。
 
-OpenClaw 不會隨附、下載、啟動、設定或認證代理。你可以執行適合自己環境的代理技術，而 OpenClaw 會透過它路由一般的程序本機 HTTP 與 WebSocket 用戶端。
+OpenClaw 不會隨附、下載、啟動、設定或認證代理。你可以執行適合你環境的代理技術，而 OpenClaw 會透過它路由一般的程序本機 HTTP 和 WebSocket 用戶端。
 
 ## 為什麼使用代理？
 
-代理讓操作者能有一個針對輸出 HTTP 與 WebSocket 流量的網路控制點。即使不是為了強化 SSRF，這也可能很有用：
+代理讓操作員能針對出站 HTTP 和 WebSocket 流量設置單一網路控制點。即使在 SSRF 強化之外，這也很有用：
 
-- 集中政策：維護單一出口政策，而不是仰賴每個應用程式 HTTP 呼叫位置都正確套用網路規則。
-- 連線時檢查：在 DNS 解析後、代理即將開啟上游連線前，評估目的地。
-- DNS 重新綁定防禦：縮小應用程式層級 DNS 檢查與實際輸出連線之間的落差。
-- 更廣泛的 JavaScript 覆蓋：將一般的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch，以及類似用戶端路由到同一路徑。
-- 可稽核性：在出口邊界記錄允許與拒絕的目的地。
-- 營運控制：不必重建 OpenClaw，即可強制套用目的地規則、網路分段、速率限制或輸出允許清單。
+- 集中政策：維護一套出口政策，而不是仰賴每個應用程式 HTTP 呼叫點都正確套用網路規則。
+- 連線時檢查：在 DNS 解析後、代理開啟上游連線前立即評估目的地。
+- DNS 重新繫結防禦：縮小應用程式層級 DNS 檢查與實際出站連線之間的落差。
+- 更廣泛的 JavaScript 覆蓋：將一般的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch，以及類似用戶端透過相同路徑路由。
+- 稽核性：在出口邊界記錄允許與拒絕的目的地。
+- 操作控制：不需重建 OpenClaw，即可強制執行目的地規則、網路分段、速率限制或出站允許清單。
 
-代理路由是一般 HTTP 與 WebSocket 輸出的程序層級防護欄。它讓操作者能以失敗即關閉的路徑，將受支援的 JavaScript HTTP 用戶端透過自己的過濾代理路由，但它不是作業系統層級的網路沙盒，也不代表 OpenClaw 會認證代理的目的地政策。
+代理路由是針對一般 HTTP 和 WebSocket 出口的程序層級防護欄。它讓操作員可以用預設拒絕的方式，將受支援的 JavaScript HTTP 用戶端透過自己的篩選代理路由，但它不是 OS 層級的網路沙箱，也不代表 OpenClaw 會認證代理的目的地政策。
 
 ## OpenClaw 如何路由流量
 
-當 `proxy.enabled=true` 且已設定代理 URL 時，受保護的執行階段程序，例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`，會透過已設定的代理路由一般 HTTP 與 WebSocket 輸出：
+當 `proxy.enabled=true` 且已設定代理 URL 時，受保護的執行階段程序，例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`，會透過設定的代理路由一般 HTTP 和 WebSocket 出口：
 
 ```text
 OpenClaw process
@@ -43,27 +43,28 @@ OpenClaw process
   WebSocket clients      -> operator-managed filtering proxy -> public internet
 ```
 
-公開契約是路由行為，而不是用來實作它的內部 Node hook。OpenClaw Gateway 控制平面 WebSocket 用戶端在 Gateway URL 使用 `localhost`，或使用像 `127.0.0.1` 或 `[::1]` 這類字面 loopback IP 時，會為 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作者代理封鎖 loopback 目的地，該控制平面路徑也必須能連到 loopback Gateway。一般執行階段 HTTP 與 WebSocket 請求仍會使用已設定的代理。
+公開合約是路由行為，而不是用來實作它的內部 Node hook。OpenClaw Gateway 控制平面 WebSocket 用戶端，在 Gateway URL 使用 `localhost` 或字面 local loopback IP（例如 `127.0.0.1` 或 `[::1]`）時，會針對 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作員代理封鎖 loopback 目的地，該控制平面路徑仍必須能到達 loopback Gateway。一般執行階段 HTTP 和 WebSocket 請求仍會使用設定的代理。
 
-在內部，OpenClaw 會針對此功能使用兩個程序層級的路由 hook：
+在內部，OpenClaw 針對此功能使用兩個程序層級的路由 hook：
 
-- Undici dispatcher 路由涵蓋 `fetch`、undici 後援的用戶端，以及提供自身 undici dispatcher 的傳輸。
-- `global-agent` 路由涵蓋 Node 核心 `node:http` 與 `node:https` 呼叫端，包括許多建構在 `http.request`、`https.request`、`http.get` 與 `https.get` 之上的函式庫。受管理代理模式會強制使用該全域代理，避免明確的 Node HTTP agent 意外繞過操作者代理。
+- Undici dispatcher 路由涵蓋 `fetch`、undici 支援的用戶端，以及提供自身 undici dispatcher 的傳輸。
+- `global-agent` 路由涵蓋 Node 核心 `node:http` 和 `node:https` 呼叫者，包括許多建構於 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的函式庫。受管理代理模式會強制使用該全域代理，避免明確的 Node HTTP 代理意外繞過操作員代理。
 
-部分 Plugin 擁有自訂傳輸，即使已有程序層級路由，也需要明確接上代理。例如，Telegram 的 Bot API 傳輸使用自己的 HTTP/1 undici dispatcher，因此會在該擁有者專屬傳輸路徑中遵循程序代理環境，以及受管理的 `OPENCLAW_PROXY_URL` 備援。
+有些 Plugin 擁有自訂傳輸，即使存在程序層級路由，也需要明確的代理接線。例如，Telegram 的 Bot API 傳輸使用自己的 HTTP/1 undici dispatcher，因此會遵守程序代理 env 加上受管理的 `OPENCLAW_PROXY_URL` 後備，並在該擁有者特定的傳輸路徑中套用。
 
-代理 URL 本身必須使用 `http://`。HTTPS 目的地仍可透過具備 HTTP `CONNECT` 的代理受到支援；這只表示 OpenClaw 預期的是純 HTTP 正向代理監聽器，例如 `http://127.0.0.1:3128`。
+代理 URL 本身必須使用 `http://`。HTTPS 目的地仍可透過代理搭配 HTTP `CONNECT` 支援；這只表示 OpenClaw 預期的是純 HTTP 正向代理監聽器，例如 `http://127.0.0.1:3128`。
 
-代理啟用時，OpenClaw 會清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。這些繞過清單是以目的地為基礎，因此若將 `localhost` 或 `127.0.0.1` 留在其中，會讓高風險 SSRF 目標略過過濾代理。
+代理啟用期間，OpenClaw 會清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。這些繞過清單是以目的地為基礎，因此若保留 `localhost` 或 `127.0.0.1`，高風險 SSRF 目標就能略過篩選代理。
 
 關閉時，OpenClaw 會還原先前的代理環境，並重設快取的程序路由狀態。
 
 ## 相關代理術語
 
-- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 執行階段輸出的輸出正向代理路由。本頁記錄此功能。
-- `gateway.auth.mode: "trusted-proxy"`：用於 Gateway 存取的輸入身分感知反向代理驗證。請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)。
-- `openclaw proxy`：用於開發與支援的本機除錯代理與擷取檢查器。請參閱 [openclaw proxy](/zh-TW/cli/proxy)。
-- 頻道或供應商專屬代理設定：特定傳輸的擁有者專屬覆寫。若目標是在整個執行階段集中出口控制，請優先使用受管理的網路代理。
+- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 執行階段出口的出站正向代理路由。本頁記錄此功能。
+- `gateway.auth.mode: "trusted-proxy"`：Gateway 存取的入站身分感知反向代理驗證。請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)。
+- `openclaw proxy`：用於開發和支援的本機除錯代理與擷取檢查器。請參閱 [openclaw proxy](/zh-TW/cli/proxy)。
+- `tools.web.fetch.useTrustedEnvProxy`：讓 `web_fetch` 選擇加入，以允許操作員控制的 HTTP(S) env 代理解析 DNS，同時保留預設的嚴格 DNS 釘選與主機名稱政策。請參閱 [Web 擷取](/zh-TW/tools/web-fetch#trusted-env-proxy)。
+- Channel 或 provider 特定代理設定：針對特定傳輸的擁有者特定覆寫。當目標是跨執行階段的集中出口控制時，請優先使用受管理的網路代理。
 
 ## 設定
 
@@ -81,7 +82,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
 
 `proxy.proxyUrl` 的優先順序高於 `OPENCLAW_PROXY_URL`。
 
-如果 `enabled=true` 但未設定有效的代理 URL，受保護的命令會在啟動時失敗，而不是退回到直接網路存取。
+如果 `enabled=true` 但未設定有效的代理 URL，受保護的命令會在啟動時失敗，而不是回退到直接網路存取。
 
 對於使用 `openclaw gateway start` 啟動的受管理 Gateway 服務，建議將 URL 儲存在設定中：
 
@@ -92,63 +93,63 @@ openclaw gateway install --force
 openclaw gateway start
 ```
 
-環境備援最適合前景執行。如果你將它用於已安裝的服務，請將 `OPENCLAW_PROXY_URL` 放入服務的持久環境，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然後重新安裝服務，讓 launchd、systemd 或 Scheduled Tasks 以該值啟動 gateway。
+環境後備最適合前景執行。如果你將它用於已安裝的服務，請將 `OPENCLAW_PROXY_URL` 放入服務的持久環境，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然後重新安裝服務，讓 launchd、systemd 或 Scheduled Tasks 以該值啟動 Gateway。
 
-對於 `openclaw --container ...` 命令，當 `OPENCLAW_PROXY_URL` 已設定時，OpenClaw 會將它轉送到以容器為目標的子 CLI。該 URL 必須能從容器內部連線；`127.0.0.1` 指的是容器本身，而不是主機。除非你明確覆寫該安全檢查，否則 OpenClaw 會拒絕容器目標命令使用 loopback 代理 URL。
+對於 `openclaw --container ...` 命令，當已設定 `OPENCLAW_PROXY_URL` 時，OpenClaw 會將它轉送到以容器為目標的子 CLI。該 URL 必須能從容器內部到達；`127.0.0.1` 指的是容器本身，而不是主機。除非你明確覆寫該安全檢查，否則 OpenClaw 會拒絕容器目標命令的 loopback 代理 URL。
 
 ## 代理需求
 
-代理政策是安全邊界。OpenClaw 無法驗證代理是否封鎖了正確目標。
+代理政策就是安全邊界。OpenClaw 無法驗證代理是否封鎖正確的目標。
 
 請將代理設定為：
 
-- 僅繫結到 loopback 或私有受信任介面。
-- 限制存取，讓只有 OpenClaw 程序、主機、容器或服務帳號可以使用。
+- 只繫結到 loopback 或私人受信任介面。
+- 限制存取，讓只有 OpenClaw 程序、主機、容器或服務帳戶可以使用它。
 - 自行解析目的地，並在 DNS 解析後封鎖目的地 IP。
-- 對純 HTTP 請求與 HTTPS `CONNECT` 通道，都在連線時套用政策。
-- 拒絕針對 loopback、私人、鏈路本機、中繼資料、多點傳送、保留或文件範圍的目的地式繞過。
-- 除非你完全信任 DNS 解析路徑，否則請避免使用主機名稱允許清單。
-- 記錄目的地、決策、狀態與原因，但不要記錄請求本文、授權標頭、Cookie 或其他秘密。
-- 將代理政策置於版本控制下，並像安全敏感設定一樣審查變更。
+- 針對純 HTTP 請求和 HTTPS `CONNECT` 通道，在連線時套用政策。
+- 拒絕針對 loopback、私人、link-local、中繼資料、多播、保留或文件範圍的目的地型繞過。
+- 除非你完全信任 DNS 解析路徑，否則避免使用主機名稱允許清單。
+- 記錄目的地、決策、狀態和原因，但不要記錄請求本文、授權標頭、Cookie 或其他祕密。
+- 將代理政策納入版本控制，並像審查安全敏感設定一樣審查變更。
 
-## 建議封鎖目的地
+## 建議封鎖的目的地
 
 請將此拒絕清單作為任何正向代理、防火牆或出口政策的起點。
 
-OpenClaw 應用程式層級分類器邏輯位於 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相關的對等 hook 是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及針對 NAT64、6to4、Teredo、ISATAP 和 IPv4 對應形式的嵌入式 IPv4 sentinel 處理。維護外部代理政策時，這些檔案是有用的參考，但 OpenClaw 不會自動匯出或在你的代理中強制套用這些規則。
+OpenClaw 應用程式層級分類器邏輯位於 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相關一致性 hook 包括 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及針對 NAT64、6to4、Teredo、ISATAP 和 IPv4-mapped 形式的內嵌 IPv4 sentinel 處理。維護外部代理政策時，這些檔案是有用的參考，但 OpenClaw 不會自動匯出或在你的代理中強制執行這些規則。
 
-| 範圍或主機                                                                         | 封鎖原因                                             |
-| ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                | IPv4 loopback                                        |
-| `::1/128`                                                                          | IPv6 loopback                                        |
-| `0.0.0.0/8`, `::/128`                                                              | 未指定與本網路位址                                   |
-| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                    | RFC1918 私有網路                                     |
-| `169.254.0.0/16`, `fe80::/10`                                                      | 鏈路本機位址與常見雲端中繼資料路徑                 |
-| `169.254.169.254`, `metadata.google.internal`                                      | 雲端中繼資料服務                                     |
-| `100.64.0.0/10`                                                                    | 電信級 NAT 共用位址空間                              |
-| `198.18.0.0/15`, `2001:2::/48`                                                     | 基準測試範圍                                         |
-| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途與文件範圍                                   |
-| `224.0.0.0/4`, `ff00::/8`                                                          | 多點傳送                                             |
-| `240.0.0.0/4`                                                                      | 保留 IPv4                                            |
-| `fc00::/7`, `fec0::/10`                                                            | IPv6 本機／私有範圍                                  |
-| `100::/64`, `2001:20::/28`                                                         | IPv6 discard 與 ORCHIDv2 範圍                        |
-| `64:ff9b::/96`, `64:ff9b:1::/48`                                                   | 含嵌入式 IPv4 的 NAT64 前綴                          |
-| `2002::/16`, `2001::/32`                                                           | 含嵌入式 IPv4 的 6to4 與 Teredo                      |
-| `::/96`, `::ffff:0:0/96`                                                           | IPv4 相容與 IPv4 對應的 IPv6                         |
+| 範圍或主機                                                                           | 封鎖原因                                             |
+| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                  | IPv4 loopback                                        |
+| `::1/128`                                                                            | IPv6 loopback                                        |
+| `0.0.0.0/8`, `::/128`                                                                | 未指定與此網路位址                                  |
+| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                      | RFC1918 私人網路                                    |
+| `169.254.0.0/16`, `fe80::/10`                                                        | Link-local 位址與常見雲端中繼資料路徑              |
+| `169.254.169.254`, `metadata.google.internal`                                        | 雲端中繼資料服務                                    |
+| `100.64.0.0/10`                                                                      | 電信級 NAT 共用位址空間                             |
+| `198.18.0.0/15`, `2001:2::/48`                                                       | 基準測試範圍                                        |
+| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途與文件範圍                                  |
+| `224.0.0.0/4`, `ff00::/8`                                                            | 多播                                                 |
+| `240.0.0.0/4`                                                                        | 保留的 IPv4                                         |
+| `fc00::/7`, `fec0::/10`                                                              | IPv6 本機/私人範圍                                  |
+| `100::/64`, `2001:20::/28`                                                           | IPv6 discard 與 ORCHIDv2 範圍                       |
+| `64:ff9b::/96`, `64:ff9b:1::/48`                                                     | 含內嵌 IPv4 的 NAT64 前綴                           |
+| `2002::/16`, `2001::/32`                                                             | 含內嵌 IPv4 的 6to4 與 Teredo                       |
+| `::/96`, `::ffff:0:0/96`                                                             | IPv4-compatible 與 IPv4-mapped IPv6                 |
 
 如果你的雲端供應商或網路平台記錄了其他中繼資料主機或保留範圍，也請一併加入。
 
 ## 驗證
 
-請從執行 OpenClaw 的同一個主機、容器或服務帳號驗證代理：
+請從執行 OpenClaw 的相同主機、容器或服務帳戶驗證代理：
 
 ```bash
 openclaw proxy validate --proxy-url http://127.0.0.1:3128
 ```
 
-預設情況下，若未提供自訂目的地，該命令會檢查 `https://example.com/` 是否成功，並啟動一個代理不得連到的暫時 loopback canary。當代理回傳非 2xx 拒絕回應，或以傳輸失敗封鎖 canary 時，預設拒絕檢查會通過；如果成功回應抵達 canary，則會失敗。如果未啟用並設定代理，驗證會回報設定問題；在變更設定前的一次性預檢，請使用 `--proxy-url`。使用 `--allowed-url` 與 `--denied-url` 測試部署專屬預期。加入 `--apns-reachable` 也會驗證直接 APNs HTTP/2 傳遞能透過代理開啟 CONNECT 通道，並收到沙盒 APNs 回應；該探測會使用刻意無效的供應商權杖，因此預期會得到 `403 InvalidProviderToken`，且會計為可連線。自訂拒絕目的地是失敗即關閉：任何 HTTP 回應都表示目的地可透過代理連到，而任何傳輸錯誤都會回報為無法判定，因為 OpenClaw 無法證明代理封鎖了一個可連線來源。驗證失敗時，命令會以代碼 1 結束。
+預設情況下，當未提供自訂目的地時，此命令會檢查 `https://example.com/` 是否成功，並啟動一個臨時 loopback canary，代理不得觸及它。當代理回傳非 2xx 拒絕回應，或因傳輸失敗而封鎖 canary 時，預設拒絕檢查會通過；如果成功回應到達 canary，則會失敗。如果未啟用並設定代理，驗證會回報設定問題；在變更設定前，請使用 `--proxy-url` 進行一次性預檢。使用 `--allowed-url` 和 `--denied-url` 測試部署特定預期。加入 `--apns-reachable` 也可驗證直接 APNs HTTP/2 傳遞是否能透過代理開啟 CONNECT 通道並接收 sandbox APNs 回應；此探測使用刻意無效的 provider token，因此預期會出現 `403 InvalidProviderToken`，且會視為可到達。自訂拒絕目的地採用預設拒絕：任何 HTTP 回應都表示該目的地可透過代理到達，而任何傳輸錯誤都會回報為不確定，因為 OpenClaw 無法證明代理封鎖了可到達的來源。驗證失敗時，命令會以代碼 1 結束。
 
-使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及各目的地檢查。代理 URL 認證資訊會在文字與 JSON 輸出中被遮蔽：
+使用 `--json` 進行自動化。JSON 輸出包含整體結果、實際生效的代理設定來源、任何設定錯誤，以及每個目的地檢查。Proxy URL 認證資訊會在文字和 JSON 輸出中被遮蔽：
 
 ```json
 {
@@ -184,9 +185,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
 curl -x http://127.0.0.1:3128 http://169.254.169.254/
 ```
 
-公開請求應該會成功。回送與中繼資料請求應該會被代理伺服器封鎖。對於 `openclaw proxy validate`，內建的回送金絲雀檢查可以區分代理伺服器拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀檢查，因此除非你的代理伺服器公開了可另行驗證的部署特定拒絕訊號，否則請將 HTTP 回應與模稜兩可的傳輸失敗都視為驗證失敗。
+公開請求應該會成功。loopback 和中繼資料請求應該會被代理封鎖。對於 `openclaw proxy validate`，內建的 loopback canary 可以區分代理拒絕與可連線來源。自訂 `--denied-url` 檢查沒有該 canary，因此請將 HTTP 回應和模稜兩可的傳輸失敗都視為驗證失敗，除非你的代理公開了可另外驗證的部署專屬拒絕訊號。
 
-接著啟用 OpenClaw 代理路由：
+然後啟用 OpenClaw 代理路由：
 
 ```bash
 openclaw config set proxy.enabled true
@@ -204,11 +205,11 @@ proxy:
 
 ## 限制
 
-- 代理伺服器可改善行程本機 JavaScript HTTP 與 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。
-- 原始 `net`、`tls` 與 `http2` 通訊端、原生附加元件和子行程，除非繼承並遵守代理伺服器環境變數，否則可能會略過 Node 層級的代理路由。
-- IRC 是運算子管理正向代理路由之外的原始 TCP/TLS 通道。在要求所有輸出流量都通過該正向代理伺服器的部署中，除非直接 IRC 輸出流量已明確核准，否則請設定 `channels.irc.enabled=false`。
-- 本機偵錯代理伺服器是診斷工具，且其對代理請求與 CONNECT 通道的直接上游轉送，在受管理代理模式啟用時預設為停用；只有針對已核准的本機診斷才啟用直接轉送。
-- 需要時，使用者本機 WebUI 與本機模型伺服器應加入運算子代理政策的允許清單；OpenClaw 不會為它們公開一般性的本機網路繞過機制。
-- Gateway 控制平面代理繞過刻意限制為 `localhost` 與字面回送 IP URL。請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789` 進行本機直接 Gateway 控制平面連線；其他主機名稱會像一般以主機名稱為基礎的流量一樣路由。
+- 代理可改善程序本機 JavaScript HTTP 和 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。
+- 原始 `net`、`tls` 和 `http2` socket、原生附加元件，以及子程序可能會繞過 Node 層級的代理路由，除非它們繼承並遵循代理環境變數。
+- IRC 是在操作員管理的轉送代理路由之外的原始 TCP/TLS channel。在要求所有輸出流量都經過該轉送代理的部署中，除非已明確核准直接 IRC 輸出，否則請設定 `channels.irc.enabled=false`。
+- 本機偵錯代理是診斷工具；在受管代理模式啟用時，其針對代理請求和 CONNECT 通道的直接上游轉送預設為停用；只有在已核准的本機診斷中才啟用直接轉送。
+- 需要時，使用者本機 WebUI 和本機模型伺服器應加入操作員代理政策的允許清單；OpenClaw 不會為它們公開一般性的本機網路繞過。
+- Gateway 控制平面代理繞過刻意限制為 `localhost` 和字面 loopback IP URL。請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789` 進行本機直接 Gateway 控制平面連線；其他主機名稱會像一般以主機名稱為基礎的流量一樣路由。
 - OpenClaw 不會檢查、測試或認證你的代理政策。
-- 請將代理政策變更視為安全性敏感的營運變更。
+- 請將代理政策變更視為安全敏感的營運變更。

docs/zh-TW/tools/loop-detection.md

@@ -1,27 +1,27 @@
 ---
 read_when:
-    - 使用者回報代理程式卡住並重複工具呼叫
+    - 使用者回報代理程式卡住，並反覆進行工具呼叫
     - 你需要調整重複呼叫保護
     - 你正在編輯代理程式工具／執行階段政策
-summary: 如何啟用並調校可偵測重複工具呼叫迴圈的防護機制
+summary: 如何啟用並調整可偵測重複工具呼叫迴圈的防護機制
 title: 工具迴圈偵測
 x-i18n:
-    generated_at: "2026-05-03T21:43:47Z"
+    generated_at: "2026-05-05T01:49:33Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
+    source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
     source_path: tools/loop-detection.md
     workflow: 16
 ---
 
-OpenClaw 可以避免代理程式卡在重複的工具呼叫模式中。
+OpenClaw 可以防止代理陷入重複的工具呼叫模式。
 此防護機制**預設為停用**。
 
-僅在需要時啟用，因為嚴格設定可能會封鎖合法的重複呼叫。
+只在需要的地方啟用，因為在嚴格設定下，它可能會阻擋合法的重複呼叫。
 
-## 為何需要此功能
+## 為什麼存在此功能
 
-- 偵測沒有取得進展的重複序列。
+- 偵測沒有進展的重複序列。
 - 偵測高頻率且沒有結果的迴圈（相同工具、相同輸入、重複錯誤）。
 - 偵測已知輪詢工具的特定重複呼叫模式。
 
@@ -48,7 +48,7 @@ OpenClaw 可以避免代理程式卡在重複的工具呼叫模式中。
 }
 ```
 
-每個代理程式的覆寫設定（選用）：
+每個代理的覆寫設定（選用）：
 
 ```json5
 {
@@ -73,42 +73,65 @@ OpenClaw 可以避免代理程式卡在重複的工具呼叫模式中。
 
 - `enabled`：主開關。`false` 表示不執行迴圈偵測。
 - `historySize`：保留供分析的近期工具呼叫數量。
-- `warningThreshold`：將模式分類為僅警告前的門檻。
-- `criticalThreshold`：封鎖重複迴圈模式的門檻。
-- `globalCircuitBreakerThreshold`：全域無進展斷路器門檻。
+- `warningThreshold`：將模式分類為僅警告前的閾值。
+- `criticalThreshold`：阻擋重複迴圈模式的閾值。
+- `globalCircuitBreakerThreshold`：全域無進展斷路器閾值。
 - `detectors.genericRepeat`：偵測重複的相同工具 + 相同參數模式。
-- `detectors.knownPollNoProgress`：偵測沒有狀態變更的已知類輪詢模式。
-- `detectors.pingPong`：偵測交替的 ping-pong 模式。
+- `detectors.knownPollNoProgress`：偵測沒有狀態變化的已知類輪詢模式。
+- `detectors.pingPong`：偵測交替的乒乓模式。
 
 對於 `exec`，無進展檢查會比較穩定的命令結果，並忽略易變的執行階段中繼資料，例如持續時間、PID、工作階段 ID 和工作目錄。
-當可用 run id 時，近期工具呼叫歷史只會在該次執行內評估，因此排程 Heartbeat 週期和新的執行不會繼承先前執行的過期迴圈計數。
+當可用執行 ID 時，近期工具呼叫歷史只會在該次執行內評估，因此排程的 Heartbeat 週期和新執行不會繼承較早執行中的過期迴圈計數。
 
 ## 建議設定
 
-- 對於較小型模型，從 `enabled: true` 開始，並維持預設值不變。旗艦模型很少需要迴圈偵測，可以保持停用。
-- 將門檻順序維持為 `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`。
+- 對於較小的模型，從 `enabled: true` 開始，並保持預設值不變。旗艦模型通常不需要迴圈偵測，可以保持停用。
+- 保持閾值順序為 `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`。
 - 如果發生誤判：
   - 提高 `warningThreshold` 和/或 `criticalThreshold`
   - （選用）提高 `globalCircuitBreakerThreshold`
   - 只停用造成問題的偵測器
-  - 降低 `historySize`，以取得較不嚴格的歷史情境
+  - 降低 `historySize` 以減少嚴格的歷史內容脈絡
+
+## Compaction 後防護機制
+
+當執行器完成自動 Compaction 重試（在內容脈絡溢位後）時，它會啟動一個短視窗防護機制，監看接下來幾次工具呼叫。如果代理在該視窗內多次發出_相同的_ `(toolName, args, result)` 三元組，防護機制會判定 Compaction 未能中斷迴圈，並以 `compaction_loop_persisted` 錯誤中止執行。
+
+這是獨立於全域 `tools.loopDetection` 偵測器的另一條程式碼路徑。它可以獨立設定：
+
+```json5
+{
+  tools: {
+    loopDetection: {
+      enabled: true, // existing master switch; set false to disable loop guards
+      postCompactionGuard: {
+        windowSize: 3, // default: 3
+      },
+    },
+  },
+}
+```
+
+- `windowSize`：Compaction 後工具呼叫的數量，在此期間防護機制會保持啟動，_並且_也是觸發中止所需的相同（工具、引數、結果）三元組計數。
+
+當結果正在變化時，防護機制絕不會中止，只有在整個視窗中的結果逐位元組相同時才會中止。它刻意保持狹窄範圍：只會在 Compaction 重試後的立即階段觸發。
 
 ## 記錄與預期行為
 
-偵測到迴圈時，OpenClaw 會回報迴圈事件，並視嚴重程度封鎖或抑制下一個工具週期。
-這可保護使用者免於失控的權杖花費和鎖死，同時保留正常的工具存取。
+偵測到迴圈時，OpenClaw 會回報迴圈事件，並依嚴重程度阻擋或緩和下一個工具週期。
+這可在保留正常工具存取的同時，保護使用者免於失控的權杖花費和鎖死。
 
 - 優先使用警告和暫時抑制。
-- 只有在重複證據累積時才升級處理。
+- 只有在重複證據累積後才升級。
 
 ## 注意事項
 
-- `tools.loopDetection` 會與代理程式層級的覆寫設定合併。
-- 每個代理程式的設定會完整覆寫或延伸全域值。
-- 如果沒有設定，防護機制會保持關閉。
+- `tools.loopDetection` 會與代理層級覆寫設定合併。
+- 每個代理的設定會完整覆寫或擴充全域值。
+- 如果不存在設定，防護欄會保持關閉。
 
 ## 相關
 
 - [Exec 核准](/zh-TW/tools/exec-approvals)
-- [思考等級](/zh-TW/tools/thinking)
-- [子代理程式](/zh-TW/tools/subagents)
+- [思考層級](/zh-TW/tools/thinking)
+- [子代理](/zh-TW/tools/subagents)

docs/zh-TW/tools/media-overview.md

@@ -1,56 +1,58 @@
 ---
 read_when:
-    - 尋找 OpenClaw 媒體功能概覽
+    - 尋找 OpenClaw 媒體功能的概覽
     - 決定要設定哪個媒體提供者
     - 了解非同步媒體生成的運作方式
 sidebarTitle: Media overview
-summary: 圖片、影片、音樂、語音與媒體理解能力一覽
+summary: 影像、影片、音樂、語音與媒體理解能力一覽
 title: 媒體概覽
 x-i18n:
-    generated_at: "2026-04-30T03:46:16Z"
+    generated_at: "2026-05-05T01:50:15Z"
     model: gpt-5.5
     provider: openai
-    source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
+    source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
     source_path: tools/media-overview.md
     workflow: 16
 ---
 
-OpenClaw 會生成圖片、影片和音樂，理解傳入媒體
-（圖片、音訊、影片），並使用文字轉語音大聲說出回覆。所有
-媒體功能都由工具驅動：代理會根據對話決定何時使用它們，
-而且每個工具只有在至少設定一個支援提供者時才會出現。
+OpenClaw 會產生影像、影片和音樂，理解傳入的媒體
+（圖片、音訊、影片），並透過文字轉語音大聲讀出回覆。所有
+媒體功能都由工具驅動：代理會根據對話判斷何時使用它們，
+而且每個工具只會在至少設定了一個後端
+供應商時出現。
 
 ## 功能
 
 <CardGroup cols={2}>
-  <Card title="圖片生成" href="/zh-TW/tools/image-generation" icon="image">
-    透過 `image_generate`，從文字提示或參考圖片建立和編輯圖片。
-    同步 - 會在回覆中內嵌完成。
+  <Card title="影像生成" href="/zh-TW/tools/image-generation" icon="image">
+    透過 `image_generate`，從文字提示或參考圖片建立和編輯影像。
+    同步 — 會隨回覆內嵌完成。
   </Card>
   <Card title="影片生成" href="/zh-TW/tools/video-generation" icon="video">
     透過 `video_generate` 進行文字轉影片、圖片轉影片和影片轉影片。
-    非同步 - 在背景執行，並在準備好後發佈結果。
+    非同步 — 在背景執行，並在就緒時發布結果。
   </Card>
   <Card title="音樂生成" href="/zh-TW/tools/music-generation" icon="music">
-    透過 `music_generate` 生成音樂或音軌。在共用
-    提供者上非同步；ComfyUI 工作流程路徑會同步執行。
+    透過 `music_generate` 產生音樂或音軌。共享
+    供應商為非同步；ComfyUI 工作流程路徑則同步執行。
   </Card>
   <Card title="文字轉語音" href="/zh-TW/tools/tts" icon="microphone">
-    透過 `tts` 工具加上 `messages.tts` 設定，將傳出的回覆
-    轉換為語音音訊。同步。
+    透過 `tts` 工具加上
+    `messages.tts` 設定，將傳出回覆轉換為語音音訊。同步。
   </Card>
   <Card title="媒體理解" href="/zh-TW/nodes/media-understanding" icon="eye">
-    使用具備視覺能力的模型提供者和專用媒體理解 Plugin，
-    摘要傳入圖片、音訊和影片。
+    使用具備視覺能力的模型供應商和專用媒體理解 plugins，
+    摘要傳入的圖片、音訊和影片。
   </Card>
   <Card title="語音轉文字" href="/zh-TW/nodes/audio" icon="ear-listen">
-    透過批次 STT 或 Voice Call 串流 STT 提供者轉錄傳入語音訊息。
+    透過批次 STT 或 Voice Call
+    串流 STT 供應商轉錄傳入的語音訊息。
   </Card>
 </CardGroup>
 
-## 提供者功能矩陣
+## 供應商功能矩陣
 
-| 提供者    | 圖片 | 影片 | 音樂 | TTS | STT | 即時語音 | 媒體理解 |
+| 供應商    | 影像 | 影片 | 音樂 | TTS | STT | 即時語音 | 媒體理解 |
 | ----------- | :---: | :---: | :---: | :-: | :-: | :------------: | :-----------------: |
 | Alibaba     |       |   ✓   |       |     |     |                |                     |
 | BytePlus    |       |   ✓   |       |     |     |                |                     |
@@ -76,68 +78,70 @@ OpenClaw 會生成圖片、影片和音樂，理解傳入媒體
 | Xiaomi MiMo |   ✓   |       |       |  ✓  |     |                |          ✓          |
 
 <Note>
-媒體理解會使用你提供者設定中註冊的任何具備視覺能力或音訊能力的模型。
-上方矩陣列出具備專用媒體理解支援的提供者；大多數多模態 LLM
-提供者（Anthropic、Google、OpenAI 等）在設定為目前作用中的回覆模型時，
-也可以理解傳入媒體。
+媒體理解會使用你供應商設定中註冊的任何具備視覺能力或音訊能力的模型。
+上方矩陣列出具備專用媒體理解支援的供應商；多數多模態 LLM
+供應商（Anthropic、Google、OpenAI 等）在設定為作用中的
+回覆模型時，也能理解傳入的媒體。
 </Note>
 
 ## 非同步與同步
 
 | 功能      | 模式         | 原因                                                                |
 | --------------- | ------------ | ------------------------------------------------------------------ |
-| 圖片           | 同步  | 提供者回應會在數秒內返回；會在回覆中內嵌完成。 |
-| 文字轉語音  | 同步  | 提供者回應會在數秒內返回；會附加到回覆音訊。 |
-| 影片           | 非同步 | 提供者處理需要 30 秒到數分鐘。                 |
-| 音樂（共用）  | 非同步 | 與影片相同的提供者處理特性。                  |
-| 音樂（ComfyUI） | 同步  | 本機工作流程會針對設定的 ComfyUI 伺服器內嵌執行。  |
+| 影像           | 同步  | 供應商回應會在數秒內返回；隨回覆內嵌完成。 |
+| 文字轉語音  | 同步  | 供應商回應會在數秒內返回；附加到回覆音訊。 |
+| 影片           | 非同步 | 供應商處理需要 30 秒到數分鐘。                 |
+| 音樂（共享）  | 非同步 | 與影片相同的供應商處理特性。                  |
+| 音樂（ComfyUI） | 同步  | 本機工作流程會針對已設定的 ComfyUI 伺服器內嵌執行。  |
 
-對於非同步工具，OpenClaw 會將請求提交給提供者、立即返回任務
-id，並在任務帳本中追蹤作業。代理會在作業執行期間繼續回應
-其他訊息。當提供者完成後，OpenClaw 會喚醒代理，讓它可以將完成的媒體
-發佈回原始頻道。
+對於非同步工具，OpenClaw 會將請求提交給供應商、立即返回任務
+id，並在任務帳本中追蹤作業。作業執行期間，代理會繼續
+回應其他訊息。供應商完成後，
+OpenClaw 會用產生的媒體路徑喚醒代理，讓它告知
+使用者，並在來源交付政策要求時，透過
+訊息工具轉送結果。
 
 ## 語音轉文字與 Voice Call
 
 Deepgram、DeepInfra、ElevenLabs、Mistral、OpenAI、SenseAudio 和 xAI 都可以在設定後，
-透過批次 `tools.media.audio` 路徑轉錄傳入音訊。
-預先檢查語音備註以進行提及閘控或命令
-解析的頻道 Plugin，會在傳入內容上標記已轉錄附件，因此共用
-媒體理解流程會重複使用該逐字稿，而不會針對同一段音訊再發出第二次
-STT 呼叫。
+透過批次 `tools.media.audio` 路徑轉錄
+傳入音訊。Channel plugins 會在為提及門檻或命令
+解析而預檢語音備註時，將已轉錄的附件標記在傳入內容上，
+因此共享媒體理解流程會重用該文字稿，而不是對同一段音訊
+進行第二次 STT 呼叫。
 
 Deepgram、ElevenLabs、Mistral、OpenAI 和 xAI 也會註冊 Voice Call
-串流 STT 提供者，因此可將即時電話音訊轉送到所選
+串流 STT 供應商，因此可以將即時電話音訊轉送給所選
 供應商，而不必等待錄音完成。
 
-## 提供者對應（供應商如何分佈於各介面）
+## 供應商對應（供應商如何分布於各介面）
 
 <AccordionGroup>
   <Accordion title="Google">
-    圖片、影片、音樂、批次 TTS、後端即時語音，以及
+    影像、影片、音樂、批次 TTS、後端即時語音，以及
     媒體理解介面。
   </Accordion>
   <Accordion title="OpenAI">
-    圖片、影片、批次 TTS、批次 STT、Voice Call 串流 STT、後端
+    影像、影片、批次 TTS、批次 STT、Voice Call 串流 STT、後端
     即時語音，以及記憶嵌入介面。
   </Accordion>
   <Accordion title="DeepInfra">
-    聊天/模型路由、圖片生成/編輯、文字轉影片、批次 TTS、
-    批次 STT、圖片媒體理解，以及記憶嵌入介面。
+    聊天/模型路由、影像生成/編輯、文字轉影片、批次 TTS、
+    批次 STT、影像媒體理解，以及記憶嵌入介面。
     DeepInfra 原生重新排序/分類/物件偵測模型尚未
-    註冊，直到 OpenClaw 針對這些
-    類別具備專用提供者合約為止。
+    註冊，直到 OpenClaw 為這些
+    類別提供專用供應商合約。
   </Accordion>
   <Accordion title="xAI">
-    圖片、影片、搜尋、程式碼執行、批次 TTS、批次 STT，以及 Voice
-    Call 串流 STT。xAI Realtime voice 是上游功能，但在共用即時語音合約能夠
-    表示它之前，不會在 OpenClaw 中註冊。
+    影像、影片、搜尋、程式碼執行、批次 TTS、批次 STT，以及 Voice
+    Call 串流 STT。xAI Realtime voice 是上游能力，但在共享即時語音合約能夠
+    表示它之前，不會註冊到 OpenClaw。
   </Accordion>
 </AccordionGroup>
 
 ## 相關
 
-- [圖片生成](/zh-TW/tools/image-generation)
+- [影像生成](/zh-TW/tools/image-generation)
 - [影片生成](/zh-TW/tools/video-generation)
 - [音樂生成](/zh-TW/tools/music-generation)
 - [文字轉語音](/zh-TW/tools/tts)

docs/zh-TW/tools/music-generation.md

@@ -2,36 +2,37 @@
 read_when:
     - 透過代理程式產生音樂或音訊
     - 設定音樂生成提供者與模型
-    - 了解 music_generate 工具的參數
+    - 了解 music_generate 工具參數
 sidebarTitle: Music generation
-summary: 透過 music_generate 在 Google Lyria、MiniMax 和 ComfyUI 工作流程中產生音樂
+summary: 透過 music_generate 跨 Google Lyria、MiniMax 與 ComfyUI 工作流程生成音樂
 title: 音樂生成
 x-i18n:
-    generated_at: "2026-05-02T21:05:56Z"
+    generated_at: "2026-05-05T01:50:19Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
+    source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
     source_path: tools/music-generation.md
     workflow: 16
 ---
 
-`music_generate` 工具可讓代理透過已設定的提供者，使用共享音樂生成能力建立音樂或音訊，目前支援 Google、MiniMax，以及以工作流程設定的 ComfyUI。
+`music_generate` 工具可讓代理程式透過已設定提供者的共用音樂生成能力建立音樂或音訊，目前支援 Google、MiniMax，以及由工作流程設定的 ComfyUI。
 
-對於有工作階段支援的代理執行，OpenClaw 會將音樂生成作為背景任務啟動，在任務帳本中追蹤，然後在曲目準備完成時再次喚醒代理，讓代理能將完成的音訊傳回原始通道。
+對於有工作階段支援的代理程式執行，OpenClaw 會將音樂生成作為背景任務啟動、在任務帳本中追蹤，然後在曲目準備就緒時再次喚醒代理程式，讓代理程式可以告知使用者並附上完成的音訊。在只使用訊息工具進行可見傳遞的群組／頻道聊天中，代理程式會透過訊息工具轉送結果。
 
 <Note>
-只有在至少有一個音樂生成提供者可用時，內建共享工具才會出現。如果你在代理的工具中沒有看到 `music_generate`，請設定 `agents.defaults.musicGenerationModel` 或設定提供者 API 金鑰。
+內建共用工具只會在至少有一個音樂生成提供者可用時出現。如果你在代理程式工具中沒有看到 `music_generate`，請設定 `agents.defaults.musicGenerationModel` 或設定提供者 API 金鑰。
 </Note>
 
 ## 快速開始
 
 <Tabs>
-  <Tab title="Shared provider-backed">
+  <Tab title="共用提供者支援">
     <Steps>
-      <Step title="Configure auth">
-        為至少一個提供者設定 API 金鑰，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
+      <Step title="設定驗證">
+        為至少一個提供者設定 API 金鑰，例如
+        `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
       </Step>
-      <Step title="Pick a default model (optional)">
+      <Step title="選擇預設模型（選用）">
         ```json5
         {
           agents: {
@@ -44,25 +45,25 @@ x-i18n:
         }
         ```
       </Step>
-      <Step title="Ask the agent">
-        _「生成一首關於夜晚駕車穿越霓虹城市的輕快合成器流行曲目。」_
+      <Step title="詢問代理程式">
+        _「生成一首關於夜晚駕車穿越霓虹城市的輕快 synthpop 曲目。」_
 
-        代理會自動呼叫 `music_generate`。不需要將工具加入允許清單。
+        代理程式會自動呼叫 `music_generate`。不需要工具允許清單。
       </Step>
     </Steps>
 
-    對於沒有工作階段支援代理執行的直接同步情境，內建工具仍會退回至內嵌生成，並在工具結果中傳回最終媒體路徑。
+    對於沒有工作階段支援代理程式執行的直接同步情境，內建工具仍會回退為行內生成，並在工具結果中回傳最終媒體路徑。
 
   </Tab>
-  <Tab title="ComfyUI workflow">
+  <Tab title="ComfyUI 工作流程">
     <Steps>
-      <Step title="Configure the workflow">
-        使用工作流程 JSON 和提示/輸出節點設定 `plugins.entries.comfy.config.music`。
+      <Step title="設定工作流程">
+        使用工作流程 JSON 和提示／輸出節點設定 `plugins.entries.comfy.config.music`。
       </Step>
-      <Step title="Cloud auth (optional)">
+      <Step title="雲端驗證（選用）">
         對於 Comfy Cloud，請設定 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
       </Step>
-      <Step title="Call the tool">
+      <Step title="呼叫工具">
         ```text
         /tool music_generate prompt="Warm ambient synth loop with soft tape texture"
         ```
@@ -83,23 +84,23 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
 
 ## 支援的提供者
 
-| 提供者 | 預設模型          | 參考輸入 | 支援的控制項                                        | 驗證                                   |
+| 提供者 | 預設模型               | 參考輸入 | 支援的控制項                                              | 驗證                                   |
 | -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
-| ComfyUI  | `workflow`             | 最多 1 張圖片    | 工作流程定義的音樂或音訊                           | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
-| Google   | `lyria-3-clip-preview` | 最多 10 張圖片  | `lyrics`, `instrumental`, `format`                        | `GEMINI_API_KEY`, `GOOGLE_API_KEY`     |
-| MiniMax  | `music-2.6`            | 無             | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` 或 MiniMax OAuth     |
+| ComfyUI  | `workflow`             | 最多 1 張圖片    | 工作流程定義的音樂或音訊                                  | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
+| Google   | `lyria-3-clip-preview` | 最多 10 張圖片   | `lyrics`, `instrumental`, `format`                        | `GEMINI_API_KEY`, `GOOGLE_API_KEY`     |
+| MiniMax  | `music-2.6`            | 無               | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` 或 MiniMax OAuth     |
 
 ### 能力矩陣
 
-`music_generate`、合約測試與共享即時掃描使用的明確模式合約：
+`music_generate`、合約測試與共用即時掃描使用的明確模式合約：
 
-| 提供者 | `generate` | `edit` | 編輯限制 | 共享即時通道                                                         |
+| 提供者 | `generate` | `edit` | 編輯限制 | 共用即時通道                                                              |
 | -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
-| ComfyUI  |     ✓      |   ✓    | 1 張圖片    | 不在共享掃描中；由 `extensions/comfy/comfy.live.test.ts` 涵蓋 |
+| ComfyUI  |     ✓      |   ✓    | 1 張圖片   | 不在共用掃描中；由 `extensions/comfy/comfy.live.test.ts` 涵蓋 |
 | Google   |     ✓      |   ✓    | 10 張圖片  | `generate`, `edit`                                                        |
-| MiniMax  |     ✓      |   —    | 無       | `generate`                                                                |
+| MiniMax  |     ✓      |   —    | 無         | `generate`                                                                |
 
-使用 `action: "list"` 在執行階段檢查可用的共享提供者和模型：
+使用 `action: "list"` 在執行階段檢查可用的共用提供者與模型：
 
 ```text
 /tool music_generate action=list
@@ -123,16 +124,16 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
   音樂生成提示。`action: "generate"` 必填。
 </ParamField>
 <ParamField path="action" type='"generate" | "status" | "list"' default="generate">
-  `"status"` 會傳回目前的工作階段任務；`"list"` 會檢查提供者。
+  `"status"` 會回傳目前的工作階段任務；`"list"` 會檢查提供者。
 </ParamField>
 <ParamField path="model" type="string">
-  提供者/模型覆寫（例如 `google/lyria-3-pro-preview`、`comfy/workflow`）。
+  提供者／模型覆寫（例如 `google/lyria-3-pro-preview`、`comfy/workflow`）。
 </ParamField>
 <ParamField path="lyrics" type="string">
-  當提供者支援明確歌詞輸入時的選用歌詞。
+  當提供者支援明確歌詞輸入時可選填歌詞。
 </ParamField>
 <ParamField path="instrumental" type="boolean">
-  當提供者支援時，要求僅輸出器樂。
+  當提供者支援時，請求純器樂輸出。
 </ParamField>
 <ParamField path="image" type="string">
   單一參考圖片路徑或 URL。
@@ -141,37 +142,37 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
   多張參考圖片（在支援的提供者上最多 10 張）。
 </ParamField>
 <ParamField path="durationSeconds" type="number">
-  當提供者支援時，以秒為單位的目標時長提示。
+  當提供者支援時的目標秒數長度提示。
 </ParamField>
 <ParamField path="format" type='"mp3" | "wav"'>
   當提供者支援時的輸出格式提示。
 </ParamField>
 <ParamField path="filename" type="string">輸出檔名提示。</ParamField>
-<ParamField path="timeoutMs" type="number">選用的提供者請求逾時，以毫秒為單位。低於 10000ms 的值會提高到 10000ms，並在工具結果中回報。</ParamField>
+<ParamField path="timeoutMs" type="number">選用的提供者請求逾時時間，以毫秒為單位。低於 10000ms 的值會提高到 10000ms，並在工具結果中回報。</ParamField>
 
 <Note>
-並非所有提供者都支援所有參數。OpenClaw 仍會在提交前驗證輸入數量等硬性限制。當提供者支援時長但使用的上限短於請求值時，OpenClaw 會限縮到最接近的支援時長。若選取的提供者或模型無法遵從真正不支援的選用提示，這些提示會被忽略並附上警告。工具結果會回報已套用的設定；`details.normalization` 會記錄任何從請求值到套用值的對應。
+並非所有提供者都支援所有參數。OpenClaw 仍會在提交前驗證輸入數量等硬性限制。當提供者支援時間長度但最大值比請求值更短時，OpenClaw 會限制為最接近的受支援時間長度。若選取的提供者或模型無法遵循真正不支援的選用提示，該提示會被忽略並顯示警告。工具結果會回報套用的設定；`details.normalization` 會擷取任何從請求值到套用值的對應。
 </Note>
 
 ## 非同步行為
 
-工作階段支援的音樂生成會作為背景任務執行：
+有工作階段支援的音樂生成會作為背景任務執行：
 
-- **背景任務：** `music_generate` 會建立背景任務，立即傳回已開始/任務回應，並稍後在後續代理訊息中張貼完成的曲目。
-- **防止重複：** 當任務為 `queued` 或 `running` 時，同一工作階段中的後續 `music_generate` 呼叫會傳回任務狀態，而不是開始另一個生成。使用 `action: "status"` 可明確檢查。
-- **狀態查詢：** `openclaw tasks list` 或 `openclaw tasks show <taskId>` 會檢查排隊中、執行中與終止狀態。
-- **完成喚醒：** OpenClaw 會將內部完成事件注入回同一工作階段，讓模型能自行撰寫面向使用者的後續訊息。
-- **提示提示：** 同一工作階段中的後續使用者/手動回合，會在已有音樂任務進行中時收到一小段執行階段提示，讓模型不會盲目再次呼叫 `music_generate`。
-- **無工作階段退回：** 沒有真實代理工作階段的直接/本機情境會內嵌執行，並在同一回合中傳回最終音訊結果。
+- **背景任務：** `music_generate` 會建立背景任務、立即回傳已開始／任務回應，並稍後在後續代理程式訊息中張貼完成的曲目。
+- **防止重複：** 當任務為 `queued` 或 `running` 時，同一工作階段中之後的 `music_generate` 呼叫會回傳任務狀態，而不是開始另一個生成。使用 `action: "status"` 明確檢查。
+- **狀態查詢：** `openclaw tasks list` 或 `openclaw tasks show <taskId>` 會檢查已佇列、執行中與終止狀態。
+- **完成喚醒：** OpenClaw 會將內部完成事件注入回同一工作階段，讓模型可以自行撰寫面向使用者的後續訊息。
+- **提示提示：** 同一工作階段中之後的使用者／手動回合，會在已有音樂任務進行中時取得小型執行階段提示，讓模型不會盲目再次呼叫 `music_generate`。
+- **無工作階段回退：** 沒有真實代理程式工作階段的直接／本機情境會行內執行，並在同一回合中回傳最終音訊結果。
 
 ### 任務生命週期
 
-| 狀態       | 意義                                                                                        |
+| 狀態        | 意義                                                                                           |
 | ----------- | ---------------------------------------------------------------------------------------------- |
-| `queued`    | 任務已建立，正在等待提供者接受。                                           |
-| `running`   | 提供者正在處理（通常為 30 秒到 3 分鐘，取決於提供者與時長）。 |
-| `succeeded` | 曲目已準備完成；代理會醒來並將其張貼到對話中。                                 |
-| `failed`    | 提供者錯誤或逾時；代理會醒來並附上錯誤詳細資料。                                 |
+| `queued`    | 工作已建立，正在等待供應商接受。                                                               |
+| `running`   | 供應商正在處理（通常需 30 秒到 3 分鐘，取決於供應商與時長）。                                  |
+| `succeeded` | 音軌已就緒；代理程式會喚醒並將其發佈到對話中。                                                 |
+| `failed`    | 供應商錯誤或逾時；代理程式會喚醒並附上錯誤詳細資料。                                           |
 
 從 CLI 檢查狀態：
 
@@ -181,7 +182,7 @@ openclaw tasks show <taskId>
 openclaw tasks cancel <taskId>
 ```
 
-## 設定
+## 組態
 
 ### 模型選擇
 
@@ -198,50 +199,62 @@ openclaw tasks cancel <taskId>
 }
 ```
 
-### 提供者選擇順序
+### 供應商選擇順序
 
-OpenClaw 會依此順序嘗試提供者：
+OpenClaw 會依照下列順序嘗試供應商：
 
-1. 工具呼叫中的 `model` 參數（如果代理指定）。
-2. 設定中的 `musicGenerationModel.primary`。
+1. 工具呼叫中的 `model` 參數（如果代理程式有指定）。
+2. 組態中的 `musicGenerationModel.primary`。
 3. 依序使用 `musicGenerationModel.fallbacks`。
-4. 僅使用驗證支援的提供者預設值進行自動偵測：
-   - 目前的預設提供者優先；
-   - 其餘已註冊的音樂生成提供者依 provider-id 順序。
+4. 僅使用由驗證支援的供應商預設值進行自動偵測：
+   - 目前的預設供應商優先；
+   - 其餘已註冊的音樂生成供應商，依 provider-id 順序排列。
 
-如果提供者失敗，會自動嘗試下一個候選項。如果全部失敗，錯誤會包含每次嘗試的詳細資料。
+如果供應商失敗，系統會自動嘗試下一個候選項。如果全部
+失敗，錯誤會包含每次嘗試的詳細資料。
 
-設定 `agents.defaults.mediaGenerationAutoProviderFallback: false` 可只使用明確的 `model`、`primary` 與 `fallbacks` 項目。
+將 `agents.defaults.mediaGenerationAutoProviderFallback: false` 設為僅使用
+明確的 `model`、`primary` 與 `fallbacks` 項目。
 
-## 提供者注意事項
+## 供應商注意事項
 
 <AccordionGroup>
   <Accordion title="ComfyUI">
-    由工作流程驅動，並取決於已設定的圖與提示/輸出欄位節點對應。隨附的 `comfy` Plugin 會透過音樂生成提供者登錄接入共享的 `music_generate` 工具。
+    由工作流程驅動，並取決於已設定的圖表加上用於提示/輸出欄位的節點對應。
+    內建的 `comfy` Plugin 會透過音樂生成供應商登錄檔接入共用的
+    `music_generate` 工具。
   </Accordion>
   <Accordion title="Google (Lyria 3)">
-    使用 Lyria 3 批次生成。目前隨附流程支援提示、選用歌詞文字與選用參考圖片。
+    使用 Lyria 3 批次生成。目前的內建流程支援提示、選用的歌詞文字，
+    以及選用的參考圖片。
   </Accordion>
   <Accordion title="MiniMax">
-    使用批次 `music_generation` 端點。支援提示、選用歌詞、器樂模式、時長導引，以及透過 `minimax` API 金鑰驗證或 `minimax-portal` OAuth 的 mp3 輸出。
+    使用批次 `music_generation` 端點。支援提示、選用歌詞、純樂器模式、
+    時長導引，以及透過 `minimax` API 金鑰驗證或 `minimax-portal` OAuth
+    輸出 mp3。
   </Accordion>
 </AccordionGroup>
 
 ## 選擇正確路徑
 
-- **由共享提供者支援**：當你需要模型選擇、提供者容錯移轉，以及內建非同步任務/狀態流程時使用。
-- **Plugin 路徑 (ComfyUI)**：當你需要自訂工作流程圖，或需要不屬於共享隨附音樂能力的提供者時使用。
+- 當你想要模型選擇、供應商容錯移轉，以及內建的非同步工作/狀態流程時，
+  使用**共用的供應商支援**路徑。
+- 當你需要自訂工作流程圖表，或需要不屬於共用內建音樂功能的供應商時，
+  使用 **Plugin 路徑 (ComfyUI)**。
 
-如果你正在偵錯 ComfyUI 特定行為，請參閱 [ComfyUI](/zh-TW/providers/comfy)。如果你正在偵錯共享提供者行為，請從 [Google (Gemini)](/zh-TW/providers/google) 或 [MiniMax](/zh-TW/providers/minimax) 開始。
+如果你正在偵錯 ComfyUI 特定行為，請參閱
+[ComfyUI](/zh-TW/providers/comfy)。如果你正在偵錯共用供應商行為，請從
+[Google (Gemini)](/zh-TW/providers/google) 或
+[MiniMax](/zh-TW/providers/minimax) 開始。
 
-## 提供者能力模式
+## 供應商功能模式
 
-共享音樂生成合約支援明確的模式宣告：
+共用音樂生成合約支援明確的模式宣告：
 
-- `generate` 用於僅提示生成。
+- `generate` 用於僅含提示的生成。
 - 當請求包含一張或多張參考圖片時使用 `edit`。
 
-新的提供者實作應優先使用明確模式區塊：
+新的供應商實作應優先使用明確的模式區塊：
 
 ```typescript
 capabilities: {
@@ -259,11 +272,14 @@ capabilities: {
 }
 ```
 
-舊版扁平欄位例如 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` **不足以** 宣告編輯支援。提供者應明確宣告 `generate` 與 `edit`，讓即時測試、合約測試與共享的 `music_generate` 工具能以確定性方式驗證模式支援。
+舊版扁平欄位，例如 `maxInputImages`、`supportsLyrics` 與
+`supportsFormat`，**不足以**宣告編輯支援。供應商應明確宣告
+`generate` 與 `edit`，讓即時測試、合約測試與共用的 `music_generate`
+工具能以確定性的方式驗證模式支援。
 
 ## 即時測試
 
-針對共享隨附提供者的選擇加入即時涵蓋：
+共用內建供應商的選擇性即時涵蓋範圍：
 
 ```bash
 OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@@ -275,26 +291,28 @@ Repo 包裝器：
 pnpm test:live:media music
 ```
 
-此即時檔案會從 `~/.profile` 載入缺少的提供者環境變數，預設會優先使用 live/env API 金鑰，而不是已儲存的驗證設定檔，並在提供者啟用編輯模式時同時執行 `generate` 與已宣告的 `edit` 涵蓋。目前涵蓋範圍：
+此即時檔案會從 `~/.profile` 載入缺少的供應商環境變數，預設優先使用
+即時/環境 API 金鑰，而非已儲存的驗證設定檔，並在供應商啟用編輯模式時，
+同時執行 `generate` 與已宣告的 `edit` 涵蓋範圍。目前涵蓋範圍：
 
 - `google`：`generate` 加上 `edit`
 - `minimax`：僅 `generate`
-- `comfy`：個別的 Comfy 即時涵蓋，不屬於共享提供者掃描
+- `comfy`：獨立的 Comfy 即時涵蓋範圍，不屬於共用供應商掃描
 
-針對隨附 ComfyUI 音樂路徑的選擇加入即時涵蓋：
+內建 ComfyUI 音樂路徑的選擇性即時涵蓋範圍：
 
 ```bash
 OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
 ```
 
-Comfy 即時檔案也涵蓋已設定那些區段時的 Comfy 圖像與影片工作流程。
+當這些區段完成設定時，Comfy live 檔案也涵蓋 Comfy 影像和影片工作流程。
 
 ## 相關
 
-- [背景任務](/zh-TW/automation/tasks) — 用於分離式 `music_generate` 執行的任務追蹤
+- [背景工作](/zh-TW/automation/tasks) — 用於分離式 `music_generate` 執行的工作追蹤
 - [ComfyUI](/zh-TW/providers/comfy)
 - [設定參考](/zh-TW/gateway/config-agents#agent-defaults) — `musicGenerationModel` 設定
 - [Google (Gemini)](/zh-TW/providers/google)
 - [MiniMax](/zh-TW/providers/minimax)
-- [模型](/zh-TW/concepts/models) — 模型設定與故障轉移
+- [模型](/zh-TW/concepts/models) — 模型設定與容錯移轉
 - [工具概覽](/zh-TW/tools)

docs/zh-TW/tools/plugin.md

@@ -2,29 +2,30 @@
 read_when:
     - 安裝或設定 Plugin
     - 了解 Plugin 探索與載入規則
-    - 使用與 Codex/Claude 相容的 Plugin 套件包
+    - 與 Codex/Claude 相容的 Plugin 套件
 sidebarTitle: Install and Configure
-summary: 安裝、設定和管理 OpenClaw Plugin
+summary: 安裝、設定並管理 OpenClaw Plugin
 title: Plugins
 x-i18n:
-    generated_at: "2026-05-03T21:44:15Z"
+    generated_at: "2026-05-05T01:50:33Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
+    source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
     source_path: tools/plugin.md
     workflow: 16
 ---
 
-Plugins 為 OpenClaw 擴充新能力：頻道、模型供應商、
-agent harness、工具、skills、語音、即時轉錄、即時
-語音、媒體理解、圖片生成、影片生成、網頁擷取、網頁
-搜尋等。有些 Plugin 是 **核心**（隨 OpenClaw 提供），其他則是
-**外部** Plugin。大多數外部 Plugin 透過
-[ClawHub](/zh-TW/tools/clawhub) 發布與探索。npm 仍支援直接安裝，以及在遷移完成前暫時支援一組由 OpenClaw 擁有的 Plugin 套件。
+Plugin 可為 OpenClaw 擴充新功能：通道、模型提供者、
+代理程式執行框架、工具、Skills、語音、即時轉錄、即時
+語音、媒體理解、影像生成、影片生成、網頁擷取、網頁
+搜尋，以及更多功能。有些 Plugin 是**核心**（隨 OpenClaw 提供），其他
+則是**外部**。大多數外部 Plugin 會透過
+[ClawHub](/zh-TW/tools/clawhub) 發布與探索。Npm 仍支援直接安裝，也支援一組
+暫時由 OpenClaw 擁有的 Plugin 套件，直到該遷移完成為止。
 
 ## 快速開始
 
-如需可複製貼上的安裝、列出、解除安裝、更新與發布範例，請參閱
+如需可直接複製貼上的安裝、列出、解除安裝、更新和發布範例，請參閱
 [管理 Plugin](/zh-TW/plugins/manage-plugins)。
 
 <Steps>
@@ -60,15 +61,16 @@ agent harness、工具、skills、語音、即時轉錄、即時
     openclaw gateway restart
     ```
 
-    然後在設定檔中的 `plugins.entries.\<id\>.config` 下設定。
+    然後在設定檔中的 `plugins.entries.\<id\>.config` 底下設定。
 
   </Step>
 
   <Step title="聊天原生管理">
-    在執行中的 Gateway 內，僅限擁有者使用的 `/plugins enable` 與 `/plugins disable`
-    會觸發 Gateway 設定重新載入器。Gateway 會在程序內重新載入 Plugin runtime
-    介面，而新的 agent 回合會從重新整理後的登錄檔重建工具清單。`/plugins install`
-    會變更 Plugin 原始碼，因此 Gateway 會要求重新啟動，而不是假裝目前程序可以安全地重新載入已匯入的模組。
+    在執行中的 Gateway 裡，僅限擁有者使用的 `/plugins enable` 和 `/plugins disable`
+    會觸發 Gateway 設定重新載入器。Gateway 會在程序內重新載入 Plugin 執行階段
+    介面，而新的代理程式回合會從重新整理後的登錄重建工具清單。`/plugins install`
+    會變更 Plugin 原始碼，因此 Gateway 會要求重新啟動，而不是假裝目前程序可以
+    安全地重新載入已匯入的模組。
 
   </Step>
 
@@ -80,14 +82,14 @@ agent harness、工具、skills、語音、即時轉錄、即時
     openclaw <plugin-command> --help
     ```
 
-    當你需要證明已註冊的工具、服務、gateway
-    方法、hook 或 Plugin 擁有的 CLI 命令時，請使用 `--runtime`。一般的 `inspect` 是冷態
-    manifest/registry 檢查，並且刻意避免匯入 Plugin runtime。
+    當你需要證明已註冊的工具、服務、Gateway 方法、掛鉤，或 Plugin 擁有的 CLI 命令時，
+    請使用 `--runtime`。單純的 `inspect` 是冷態資訊清單/登錄檢查，並刻意避免匯入
+    Plugin 執行階段。
 
   </Step>
 </Steps>
 
-如果你偏好聊天原生控制，請啟用 `commands.plugins: true` 並使用：
+如果偏好聊天原生控制，請啟用 `commands.plugins: true` 並使用：
 
 ```text
 /plugin install clawhub:<package>
@@ -96,30 +98,45 @@ agent harness、工具、skills、語音、即時轉錄、即時
 ```
 
 安裝路徑使用與 CLI 相同的解析器：本機路徑/封存檔、明確的
-`clawhub:<pkg>`、明確的 `npm:<pkg>`、明確的 `git:<repo>`，或透過 npm 的裸套件規格。
+`clawhub:<pkg>`、明確的 `npm:<pkg>`、明確的 `git:<repo>`，或透過 npm 的裸套件
+規格。
 
-如果設定無效，安裝通常會失敗關閉，並引導你使用
-`openclaw doctor --fix`。唯一的復原例外是一條狹窄的 bundled-plugin
-重新安裝路徑，僅適用於選擇加入
+如果設定無效，安裝通常會以封閉模式失敗，並指引你執行
+`openclaw doctor --fix`。唯一的復原例外是狹義的隨附 Plugin
+重新安裝路徑，適用於選擇啟用
 `openclaw.install.allowInvalidConfigRecovery` 的 Plugin。
-Gateway 啟動期間，無效的 Plugin 設定會像其他無效設定一樣失敗關閉。
-執行 `openclaw doctor --fix`，即可透過停用該 Plugin 項目並移除其無效設定 payload，隔離有問題的 Plugin 設定；一般設定備份會保留先前的值。
-當頻道設定參照的 Plugin 已無法再探索到，但相同的過期 Plugin id 仍留在 Plugin 設定或安裝記錄中時，Gateway 啟動會記錄警告並略過該頻道，而不是阻擋所有其他頻道。
-執行 `openclaw doctor --fix` 可移除過期的頻道/Plugin 項目；沒有過期 Plugin 證據的未知頻道鍵仍會驗證失敗，讓拼字錯誤保持可見。
-如果設定了 `plugins.enabled: false`，過期的 Plugin 參照會被視為惰性：
-Gateway 啟動會略過 Plugin 探索/載入工作，而 `openclaw doctor` 會保留已停用的 Plugin 設定，不會自動移除它。如果你想移除過期的 Plugin id，請先重新啟用 Plugin，再執行 doctor cleanup。
+在 Gateway 啟動期間，無效的 Plugin 設定會像其他無效設定一樣以封閉模式失敗。
+執行 `openclaw doctor --fix` 可隔離不良的 Plugin 設定，做法是停用該 Plugin 項目
+並移除其無效設定酬載；一般設定備份會保留先前的值。
+當通道設定參照已無法探索的 Plugin，但相同的過時 Plugin ID 仍留在 Plugin 設定或安裝記錄中時，
+Gateway 啟動會記錄警告並略過該通道，而不是封鎖其他所有通道。
+執行 `openclaw doctor --fix` 可移除過時的通道/Plugin 項目；沒有過時 Plugin 證據的未知
+通道鍵仍會驗證失敗，讓拼字錯誤保持可見。
+如果設定了 `plugins.enabled: false`，過時的 Plugin 參照會被視為非作用中：
+Gateway 啟動會略過 Plugin 探索/載入工作，而 `openclaw doctor` 會保留
+已停用的 Plugin 設定，而不是自動移除它。如果你想移除過時的 Plugin ID，
+請先重新啟用 Plugin，再執行 doctor 清理。
 
-Plugin 相依性安裝只會在明確的安裝/更新或 doctor 修復流程期間發生。Gateway 啟動、設定重新載入與 runtime 檢查不會執行套件管理器，也不會修復相依性樹。本機 Plugin 必須已安裝其相依性，而 npm、git 與 ClawHub Plugin 會安裝在 OpenClaw 的受管理 Plugin 根目錄下。npm 相依性可能會在 OpenClaw 的受管理 npm 根目錄內 hoist；安裝/更新會先掃描該受管理根目錄再信任，解除安裝則會透過 npm 移除由 npm 管理的套件。外部 Plugin 與自訂載入路徑仍必須透過 `openclaw plugins install` 安裝。
-使用 `openclaw plugins list --json` 可查看每個可見 Plugin 的靜態 `dependencyStatus`，而不需匯入 runtime 程式碼或修復相依性。
-請參閱 [Plugin 相依性解析](/zh-TW/plugins/dependency-resolution) 了解安裝時生命週期。
+Plugin 依賴安裝只會在明確的安裝/更新或 doctor 修復流程期間發生。
+Gateway 啟動、設定重新載入和執行階段檢查不會執行套件管理器，也不會修復依賴樹。
+本機 Plugin 必須已經安裝其依賴，而 npm、git 和 ClawHub Plugin 會安裝在
+OpenClaw 受管理的 Plugin 根目錄下。npm 依賴可能會提升到 OpenClaw 受管理的 npm 根目錄內；
+安裝/更新會先掃描該受管理根目錄再信任它，而解除安裝會透過 npm 移除 npm 管理的套件。
+外部 Plugin 和自訂載入路徑仍必須透過 `openclaw plugins install` 安裝。
+使用 `openclaw plugins list --json` 可查看每個可見 Plugin 的靜態 `dependencyStatus`，
+而不匯入執行階段程式碼或修復依賴。
+如需安裝期間生命週期，請參閱 [Plugin 依賴解析](/zh-TW/plugins/dependency-resolution)。
 
-對於 npm 安裝，像 `latest` 或 dist-tag 這類可變選擇器會在安裝前解析，然後固定到 OpenClaw 受管理 npm 根目錄中經過精確驗證的版本。npm 完成後，OpenClaw 會驗證已安裝的
-`package-lock.json` 項目仍符合解析後的版本與 integrity。如果 npm 寫入不同的套件中繼資料，安裝會失敗，並回復受管理套件，而不是接受不同的 Plugin artifact。
+對於 npm 安裝，像 `latest` 或發行標籤這類可變選擇器會在安裝前解析，
+然後固定到 OpenClaw 受管理 npm 根目錄中已驗證的精確版本。npm 完成後，
+OpenClaw 會驗證已安裝的 `package-lock.json` 項目仍符合解析後的版本與完整性。
+如果 npm 寫入不同的套件中繼資料，安裝會失敗，且受管理套件會回復，而不是接受
+不同的 Plugin 成品。
 
-原始碼 checkout 是 pnpm workspace。如果你 clone OpenClaw 來修改 bundled
-Plugin，請執行 `pnpm install`；OpenClaw 之後會從
-`extensions/<id>` 載入 bundled Plugin，因此編輯內容與套件本機相依性會被直接使用。
-一般 npm 根目錄安裝適用於封裝版 OpenClaw，不適用於原始碼 checkout 開發。
+原始碼簽出是 pnpm 工作區。如果你複製 OpenClaw 來開發隨附 Plugin，
+請執行 `pnpm install`；OpenClaw 接著會從 `extensions/<id>` 載入隨附 Plugin，
+讓編輯內容和套件本機依賴可直接使用。
+一般 npm 根目錄安裝適用於已打包的 OpenClaw，不適用於原始碼簽出開發。
 
 ## Plugin 類型
 
@@ -127,25 +144,29 @@ OpenClaw 可辨識兩種 Plugin 格式：
 
 | 格式       | 運作方式                                                           | 範例                                                   |
 | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
-| **原生**   | `openclaw.plugin.json` + runtime 模組；在程序內執行                | 官方 Plugin、社群 npm 套件                             |
-| **Bundle** | Codex/Claude/Cursor 相容版面配置；對應到 OpenClaw 功能             | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
+| **原生**   | `openclaw.plugin.json` + 執行階段模組；在程序內執行               | 官方 Plugin、社群 npm 套件                             |
+| **套件組合** | Codex/Claude/Cursor 相容結構；對應到 OpenClaw 功能               | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
 
-兩者都會出現在 `openclaw plugins list` 下。請參閱 [Plugin Bundle](/zh-TW/plugins/bundles) 了解 Bundle 詳細資訊。
+兩者都會出現在 `openclaw plugins list` 下。如需套件組合詳細資訊，請參閱 [Plugin 套件組合](/zh-TW/plugins/bundles)。
 
-如果你要撰寫原生 Plugin，請從 [建置 Plugin](/zh-TW/plugins/building-plugins)
-與 [Plugin SDK 概覽](/zh-TW/plugins/sdk-overview) 開始。
+如果你正在撰寫原生 Plugin，請從 [建置 Plugin](/zh-TW/plugins/building-plugins)
+和 [Plugin SDK 概覽](/zh-TW/plugins/sdk-overview) 開始。
 
-## 套件進入點
+## 套件入口點
 
 原生 Plugin npm 套件必須在 `package.json` 中宣告 `openclaw.extensions`。
-每個項目都必須保持在套件目錄內，並解析為可讀取的 runtime
-檔案，或解析為 TypeScript 原始檔，且有可推斷的已建置 JavaScript
-對等檔案，例如 `src/index.ts` 到 `dist/index.js`。
-封裝安裝必須隨附該 JavaScript runtime 輸出。TypeScript
-原始碼 fallback 適用於原始碼 checkout 與本機開發路徑，不適用於安裝到 OpenClaw 受管理 Plugin 根目錄中的 npm 套件。
+每個項目都必須位於套件目錄內，並解析為可讀取的執行階段檔案，
+或解析為 TypeScript 原始檔，且可推斷出建置後的 JavaScript 對應檔案，
+例如從 `src/index.ts` 到 `dist/index.js`。
+已打包安裝必須隨附該 JavaScript 執行階段輸出。TypeScript
+原始碼後援適用於原始碼簽出和本機開發路徑，不適用於安裝到 OpenClaw
+受管理 Plugin 根目錄中的 npm 套件。
 
-當已發布的 runtime 檔案不位於與來源項目相同的路徑時，請使用 `openclaw.runtimeExtensions`。存在時，`runtimeExtensions` 必須為每個 `extensions` 項目包含正好一個項目。不相符的清單會讓安裝與 Plugin 探索失敗，而不是靜默 fallback 到來源路徑。如果你也發布 `openclaw.setupEntry`，請為其已建置的
-JavaScript 對等檔案使用 `openclaw.runtimeSetupEntry`；宣告時該檔案為必需。
+當已發布的執行階段檔案不在原始碼項目的相同路徑時，請使用
+`openclaw.runtimeExtensions`。存在時，`runtimeExtensions` 必須為每個
+`extensions` 項目包含剛好一個項目。清單不相符會使安裝和 Plugin 探索失敗，
+而不是默默後援到原始碼路徑。如果你也發布 `openclaw.setupEntry`，請使用
+`openclaw.runtimeSetupEntry` 指向其建置後的 JavaScript 對應檔案；宣告後該檔案即為必要檔案。
 
 ```json
 {
@@ -161,10 +182,15 @@ JavaScript 對等檔案使用 `openclaw.runtimeSetupEntry`；宣告時該檔案
 
 ### 遷移期間由 OpenClaw 擁有的 npm 套件
 
-ClawHub 是大多數 Plugin 的主要發布路徑。目前封裝版
-OpenClaw 版本已經隨附許多官方 Plugin，因此在一般設定中不需要另外安裝 npm。直到每個由 OpenClaw 擁有的 Plugin 都遷移到 ClawHub 前，OpenClaw 仍會在 npm 上發布一些 `@openclaw/*` Plugin 套件，供舊版/自訂安裝與直接 npm 工作流程使用。
+ClawHub 是大多數 Plugin 的主要發行路徑。目前已打包的
+OpenClaw 版本已隨附許多官方 Plugin，因此在一般設定中不需要
+單獨的 npm 安裝。在每個由 OpenClaw 擁有的 Plugin 都遷移到
+ClawHub 之前，OpenClaw 仍會在 npm 上提供一些 `@openclaw/*` Plugin 套件，
+供較舊/自訂安裝和直接 npm 工作流程使用。
 
-如果 npm 將某個 `@openclaw/*` Plugin 套件回報為 deprecated，該套件版本來自較舊的外部套件列車。請使用目前 OpenClaw 隨附的 Plugin 或本機 checkout，直到較新的 npm 套件發布。
+如果 npm 將某個 `@openclaw/*` Plugin 套件回報為已棄用，該套件
+版本來自較舊的外部套件發行線。請使用目前 OpenClaw 中隨附的 Plugin，
+或使用本機簽出，直到較新的 npm 套件發布為止。
 
 | Plugin          | 套件                       | 文件                                       |
 | --------------- | -------------------------- | ------------------------------------------ |
@@ -185,7 +211,7 @@ OpenClaw 版本已經隨附許多官方 Plugin，因此在一般設定中不需
 ### 核心（隨 OpenClaw 提供）
 
 <AccordionGroup>
-  <Accordion title="模型供應商（預設啟用）">
+  <Accordion title="模型提供者（預設啟用）">
     `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
     `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
     `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@@ -193,27 +219,27 @@ OpenClaw 版本已經隨附許多官方 Plugin，因此在一般設定中不需
     `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
   </Accordion>
 
-  <Accordion title="Memory Plugin">
-    - `memory-core` — 隨附的記憶體搜尋（透過 `plugins.slots.memory` 作為預設）
-    - `memory-lancedb` — 由 LanceDB 支援的長期記憶體，具備自動回想/擷取功能（設定 `plugins.slots.memory = "memory-lancedb"`）
+  <Accordion title="記憶 Plugin">
+    - `memory-core` — 隨附的記憶搜尋（透過 `plugins.slots.memory` 預設使用）
+    - `memory-lancedb` — 由 LanceDB 支援的長期記憶，具備自動召回/擷取（設定 `plugins.slots.memory = "memory-lancedb"`）
 
-    請參閱 [Memory LanceDB](/zh-TW/plugins/memory-lancedb) 了解 OpenAI 相容的
-    embedding 設定、Ollama 範例、回想限制與疑難排解。
+    如需與 OpenAI 相容的嵌入設定、Ollama 範例、召回限制和疑難排解，請參閱
+    [Memory LanceDB](/zh-TW/plugins/memory-lancedb)。
 
   </Accordion>
 
-  <Accordion title="語音供應商（預設啟用）">
+  <Accordion title="語音提供者（預設啟用）">
     `elevenlabs`, `microsoft`
   </Accordion>
 
   <Accordion title="其他">
-    - `browser` — 隨附的瀏覽器 Plugin，用於瀏覽器工具、`openclaw browser` CLI、`browser.request` gateway 方法、瀏覽器 runtime，以及預設瀏覽器控制服務（預設啟用；替換前請先停用）
-    - `copilot-proxy` — VS Code Copilot Proxy bridge（預設停用）
+    - `browser` — 隨附的瀏覽器 Plugin，用於瀏覽器工具、`openclaw browser` CLI、`browser.request` Gateway 方法、瀏覽器執行階段，以及預設瀏覽器控制服務（預設啟用；替換前請先停用）
+    - `copilot-proxy` — VS Code Copilot Proxy 橋接器（預設停用）
 
   </Accordion>
 </AccordionGroup>
 
-在找第三方 Plugin？請參閱 [社群 Plugin](/zh-TW/plugins/community)。
+正在尋找第三方 Plugin 嗎？請參閱 [社群 Plugin](/zh-TW/plugins/community)。
 
 ## 設定
 
@@ -231,77 +257,80 @@ OpenClaw 版本已經隨附許多官方 Plugin，因此在一般設定中不需
 }
 ```
 
-| 欄位             | 說明                                                      |
-| ---------------- | --------------------------------------------------------- |
-| `enabled`        | 主開關（預設：`true`）                                   |
-| `allow`          | Plugin 允許清單（選用）                                  |
-| `deny`           | Plugin 拒絕清單（選用；拒絕優先）                        |
-| `load.paths`     | 額外的 Plugin 檔案/目錄                                  |
-| `slots`          | 專屬槽位選擇器（例如 `memory`、`contextEngine`）          |
-| `entries.\<id\>` | 每個 Plugin 的開關 + 設定                                |
+| 欄位               | 描述                                                      |
+| ------------------ | --------------------------------------------------------- |
+| `enabled`          | 主開關（預設：`true`）                                   |
+| `allow`            | Plugin 允許清單（可選）                                  |
+| `bundledDiscovery` | 內建 Plugin 探索模式（預設為 `allowlist`）               |
+| `deny`             | Plugin 拒絕清單（可選；拒絕優先）                       |
+| `load.paths`       | 額外的 Plugin 檔案/目錄                                  |
+| `slots`            | 專屬插槽選擇器（例如 `memory`、`contextEngine`）          |
+| `entries.\<id\>`   | 個別 Plugin 開關 + 設定                                  |
 
-`plugins.allow` 是排他的。當它非空時，只有列出的 Plugin 可以載入或公開工具，即使 `tools.allow` 包含 `"*"` 或特定 Plugin 擁有的工具名稱也是如此。如果工具允許清單參照 Plugin 工具，請將擁有該工具的 Plugin id 加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 會對這種形態發出警告。
+`plugins.allow` 是排他的。當它非空時，只有列出的 Plugin 可以載入或公開工具，即使 `tools.allow` 包含 `"*"` 或特定由 Plugin 擁有的工具名稱也一樣。如果工具允許清單引用 Plugin 工具，請將擁有該工具的 Plugin id 加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 會針對這種形態發出警告。
 
-透過 `/plugins enable` 或 `/plugins disable` 進行的設定變更會觸發進程內 Gateway Plugin 重新載入。新的代理回合會從已重新整理的 Plugin registry 重建其工具清單。安裝、更新、解除安裝等會變更來源的操作仍會重新啟動 Gateway 程序，因為已匯入的 Plugin 模組無法安全地就地替換。
+`plugins.bundledDiscovery` 對新設定預設為 `"allowlist"`，因此限制性的 `plugins.allow` 清單也會封鎖未列入的內建提供者 Plugin，包括執行階段網頁搜尋提供者探索。Doctor 會在遷移期間將較舊的限制性允許清單設定標記為 `"compat"`，讓升級在操作者選擇更嚴格模式前，持續保留舊版內建提供者行為。空的 `plugins.allow` 仍會被視為未設定/開放。
 
-`openclaw plugins list` 是本機 Plugin registry/設定快照。那裡顯示為 `enabled` 的 Plugin，表示持久化 registry 和目前設定允許該 Plugin 參與。這並不證明已在執行中的遠端 Gateway 已重新載入或重新啟動到相同的 Plugin 程式碼。在使用包裝器程序的 VPS/容器設定中，請將重新啟動或會觸發重新載入的寫入送到實際的 `openclaw gateway run` 程序，或在重新載入回報失敗時，對執行中的 Gateway 使用 `openclaw gateway restart`。
+透過 `/plugins enable` 或 `/plugins disable` 進行的設定變更會觸發程序內 Gateway Plugin 重新載入。新的代理回合會從重新整理後的 Plugin 登錄重新建構其工具清單。安裝、更新和解除安裝等變更來源的操作仍會重新啟動 Gateway 程序，因為已匯入的 Plugin 模組無法安全地原地替換。
 
-<Accordion title="Plugin 狀態：已停用、缺失、無效">
+`openclaw plugins list` 是本機 Plugin 登錄/設定快照。其中顯示為 `enabled` 的 Plugin 表示持久化登錄與目前設定允許該 Plugin 參與。這不代表已在執行中的遠端 Gateway 已重新載入或重新啟動到相同的 Plugin 程式碼。在使用包裝程序的 VPS/容器設定中，請將重新啟動或會觸發重新載入的寫入傳送到實際的 `openclaw gateway run` 程序，或在重新載入回報失敗時，對執行中的 Gateway 使用 `openclaw gateway restart`。
+
+<Accordion title="Plugin states: disabled vs missing vs invalid">
   - **已停用**：Plugin 存在，但啟用規則將其關閉。設定會保留。
-  - **缺失**：設定參照了探索時找不到的 Plugin id。
-  - **無效**：Plugin 存在，但其設定不符合宣告的 schema。Gateway 啟動只會略過該 Plugin；`openclaw doctor --fix` 可以透過停用它並移除其設定 payload，將無效項目隔離。
+  - **遺失**：設定引用了探索未找到的 Plugin id。
+  - **無效**：Plugin 存在，但其設定不符合宣告的結構描述。Gateway 啟動只會略過該 Plugin；`openclaw doctor --fix` 可以透過停用它並移除其設定酬載，將無效項目隔離。
 
 </Accordion>
 
 ## 探索與優先順序
 
-OpenClaw 會依此順序掃描 Plugin（第一個符合者勝出）：
+OpenClaw 會依照此順序掃描 Plugin（第一個符合者優先）：
 
 <Steps>
-  <Step title="設定路徑">
-    `plugins.load.paths` — 明確的檔案或目錄路徑。指回 OpenClaw 自身封裝的內建 Plugin 目錄的路徑會被忽略；執行 `openclaw doctor --fix` 以移除那些過期別名。
+  <Step title="Config paths">
+    `plugins.load.paths` — 明確的檔案或目錄路徑。指回 OpenClaw 自身封裝內建 Plugin 目錄的路徑會被忽略；請執行 `openclaw doctor --fix` 以移除那些過時別名。
   </Step>
 
-  <Step title="工作區 Plugin">
+  <Step title="Workspace plugins">
     `\<workspace\>/.openclaw/<plugin-root>/*.ts` 和 `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`。
   </Step>
 
-  <Step title="全域 Plugin">
+  <Step title="Global plugins">
     `~/.openclaw/<plugin-root>/*.ts` 和 `~/.openclaw/<plugin-root>/*/index.ts`。
   </Step>
 
-  <Step title="內建 Plugin">
-    隨 OpenClaw 一起提供。許多預設啟用（模型提供者、語音）。其他則需要明確啟用。
+  <Step title="Bundled plugins">
+    隨 OpenClaw 出貨。許多預設啟用（模型提供者、語音）。其他則需要明確啟用。
   </Step>
 </Steps>
 
-封裝安裝和 Docker 映像通常會從已編譯的 `dist/extensions` 樹解析內建 Plugin。如果某個內建 Plugin 來源目錄被 bind-mounted 到相符的封裝來源路徑上，例如 `/app/extensions/synology-chat`，OpenClaw 會將該掛載的來源目錄視為內建來源覆蓋，並在封裝的 `/app/dist/extensions/synology-chat` bundle 之前探索它。這能讓維護者容器迴圈持續運作，而不必把每個內建 Plugin 都切回 TypeScript 來源。設定 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可強制使用封裝的 dist bundle，即使存在來源覆蓋掛載也是如此。
+封裝安裝與 Docker 映像通常會從編譯後的 `dist/extensions` 樹解析內建 Plugin。如果內建 Plugin 原始碼目錄被 bind mount 到相符的封裝原始碼路徑上，例如 `/app/extensions/synology-chat`，OpenClaw 會將該掛載的原始碼目錄視為內建原始碼覆蓋層，並在封裝的 `/app/dist/extensions/synology-chat` bundle 之前探索它。這能讓維護者容器迴圈持續運作，而不必將每個內建 Plugin 切回 TypeScript 原始碼。設定 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可強制使用封裝的 dist bundle，即使存在原始碼覆蓋層掛載也一樣。
 
 ### 啟用規則
 
 - `plugins.enabled: false` 會停用所有 Plugin，並略過 Plugin 探索/載入工作
-- `plugins.deny` 一律優先於 allow
+- `plugins.deny` 一律優先於允許
 - `plugins.entries.\<id\>.enabled: false` 會停用該 Plugin
 - 工作區來源的 Plugin **預設停用**（必須明確啟用）
-- 內建 Plugin 會遵循內建預設啟用集合，除非被覆寫
-- 專屬槽位可以強制啟用該槽位選取的 Plugin
-- 當設定命名了 Plugin 擁有的介面時，部分內建選用 Plugin 會自動啟用，例如提供者模型 ref、通道設定，或 harness runtime
-- 當 `plugins.enabled: false` 啟用時，過期 Plugin 設定會被保留；如果你希望移除過期 id，請先重新啟用 Plugin，再執行 doctor 清理
-- OpenAI 系列 Codex 路由會保持獨立的 Plugin 邊界：`openai-codex/*` 屬於 OpenAI Plugin，而內建的 Codex app-server Plugin 則由 `agentRuntime.id: "codex"` 或舊版 `codex/*` 模型 refs 選取
+- 內建 Plugin 會遵循內建的預設開啟集合，除非被覆寫
+- 專屬插槽可以強制啟用該插槽所選的 Plugin
+- 某些內建選擇加入 Plugin 會在設定指定由 Plugin 擁有的介面時自動啟用，例如提供者模型參照、頻道設定或測試框架執行階段
+- 當 `plugins.enabled: false` 啟用時，過時的 Plugin 設定會被保留；如果你希望移除過時 id，請先重新啟用 Plugin 再執行 doctor 清理
+- OpenAI 系列 Codex 路由會維持獨立的 Plugin 邊界：`openai-codex/*` 屬於 OpenAI Plugin，而內建 Codex app-server Plugin 由 `agentRuntime.id: "codex"` 或舊版 `codex/*` 模型參照選取
 
-## 疑難排解 runtime hooks
+## 疑難排解執行階段 hook
 
-如果某個 Plugin 出現在 `plugins list` 中，但 `register(api)` 副作用或 hooks 沒有在即時聊天流量中執行，請先檢查這些項目：
+如果某個 Plugin 出現在 `plugins list` 中，但 `register(api)` 副作用或 hook 未在即時聊天流量中執行，請先檢查以下項目：
 
-- 執行 `openclaw gateway status --deep --require-rpc`，並確認作用中的 Gateway URL、profile、設定路徑和程序就是你正在編輯的那些。
-- 在 Plugin 安裝/設定/程式碼變更後，重新啟動即時 Gateway。在包裝器容器中，PID 1 可能只是 supervisor；請重新啟動或傳送 signal 給子 `openclaw gateway run` 程序。
-- 使用 `openclaw plugins inspect <id> --runtime --json` 確認 hook 註冊和診斷。非內建對話 hooks，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`，需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
-- 對於模型切換，建議使用 `before_model_resolve`。它會在代理回合進行模型解析前執行；`llm_output` 只會在模型嘗試產生 assistant 輸出後執行。
-- 若要證明有效的工作階段模型，請使用 `openclaw sessions` 或 Gateway 工作階段/狀態介面；在除錯提供者 payload 時，請使用 `--raw-stream --raw-stream-path <path>` 啟動 Gateway。
+- 執行 `openclaw gateway status --deep --require-rpc`，並確認作用中的 Gateway URL、設定檔、設定路徑與程序就是你正在編輯的那些。
+- 在 Plugin 安裝/設定/程式碼變更後重新啟動即時 Gateway。在包裝容器中，PID 1 可能只是監督器；請重新啟動子 `openclaw gateway run` 程序或向其傳送訊號。
+- 使用 `openclaw plugins inspect <id> --runtime --json` 確認 hook 註冊與診斷。非內建對話 hook，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`，需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
+- 對於模型切換，請優先使用 `before_model_resolve`。它會在代理回合的模型解析前執行；`llm_output` 只會在一次模型嘗試產生助理輸出後執行。
+- 若要證明有效的工作階段模型，請使用 `openclaw sessions` 或 Gateway 工作階段/狀態介面；偵錯提供者酬載時，請以 `--raw-stream --raw-stream-path <path>` 啟動 Gateway。
 
-### Plugin 工具設定緩慢
+### 緩慢的 Plugin 工具設定
 
-如果代理回合在準備工具時看起來停滯，請啟用 trace logging 並檢查 Plugin 工具 factory timing 行：
+如果代理回合在準備工具時看似停滯，請啟用追蹤記錄並檢查 Plugin 工具工廠計時行：
 
 ```bash
 openclaw config set logging.level trace
@@ -314,19 +343,19 @@ openclaw logs --follow
 [trace:plugin-tools] factory timings ...
 ```
 
-摘要會列出總 factory 時間和最慢的 Plugin 工具 factories，包括 Plugin id、宣告的工具名稱、結果形態，以及該工具是否為選用。當單一 factory 至少花費 1 秒，或 Plugin 工具 factory 準備總時間至少花費 5 秒時，緩慢行會提升為警告。
+摘要會列出總工廠時間與最慢的 Plugin 工具工廠，包括 Plugin id、宣告的工具名稱、結果形態，以及該工具是否為可選。當單一工廠耗時至少 1 秒，或 Plugin 工具工廠準備總耗時至少 5 秒時，緩慢行會提升為警告。
 
-OpenClaw 會針對相同有效請求內容脈絡的重複解析，快取成功的 Plugin 工具 factory 結果。快取鍵包含有效 runtime 設定、工作區、代理/工作階段 id、sandbox policy、瀏覽器設定、delivery context、requester identity 和 ownership state，因此依賴那些受信任欄位的 factories 會在內容脈絡變更時重新執行。
+OpenClaw 會針對相同有效請求情境的重複解析，快取成功的 Plugin 工具工廠結果。快取鍵包含有效執行階段設定、工作區、代理/工作階段 id、沙箱政策、瀏覽器設定、遞送情境、請求者身分與擁有權狀態，因此依賴這些受信任欄位的工廠會在情境變更時重新執行。
 
-如果某個 Plugin 佔用了大部分時間，請檢查其 runtime 註冊：
+如果某個 Plugin 佔據大部分計時，請檢查其執行階段註冊：
 
 ```bash
 openclaw plugins inspect <plugin-id> --runtime --json
 ```
 
-然後更新、重新安裝或停用該 Plugin。Plugin 作者應將昂貴的依賴載入移到工具執行路徑之後，而不是在工具 factory 內執行。
+接著更新、重新安裝或停用該 Plugin。Plugin 作者應將昂貴的依賴載入移到工具執行路徑後方，而不是在工具工廠內完成。
 
-### 重複的通道或工具 ownership
+### 重複的頻道或工具擁有權
 
 症狀：
 
@@ -334,24 +363,24 @@ openclaw plugins inspect <plugin-id> --runtime --json
 - `channel setup already registered: <channel-id> (<plugin-id>)`
 - `plugin tool name conflict (<plugin-id>): <tool-name>`
 
-這些表示有多個已啟用的 Plugin 正嘗試擁有相同的通道、設定流程或工具名稱。最常見的原因是某個外部通道 Plugin 安裝在現在提供相同通道 id 的內建 Plugin 旁邊。
+這表示有多個已啟用的 Plugin 嘗試擁有相同的頻道、設定流程或工具名稱。最常見的原因是外部頻道 Plugin 與現在提供相同頻道 id 的內建 Plugin 並存安裝。
 
-除錯步驟：
+偵錯步驟：
 
-- 執行 `openclaw plugins list --enabled --verbose`，查看每個已啟用的 Plugin 及其來源。
-- 針對每個可疑 Plugin 執行 `openclaw plugins inspect <id> --runtime --json`，並比較 `channels`、`channelConfigs`、`tools` 和診斷。
-- 安裝或移除 Plugin 套件後，執行 `openclaw plugins registry --refresh`，讓持久化 metadata 反映目前安裝。
-- 在安裝、registry 或設定變更後重新啟動 Gateway。
+- 執行 `openclaw plugins list --enabled --verbose`，查看每個已啟用的 Plugin 與來源。
+- 對每個疑似 Plugin 執行 `openclaw plugins inspect <id> --runtime --json`，並比較 `channels`、`channelConfigs`、`tools` 與診斷。
+- 安裝或移除 Plugin 套件後，執行 `openclaw plugins registry --refresh`，讓持久化中繼資料反映目前安裝。
+- 在安裝、登錄或設定變更後重新啟動 Gateway。
 
-修復選項：
+修正選項：
 
-- 如果某個 Plugin 有意替換另一個相同 channel id 的 Plugin，偏好的 Plugin 應宣告 `channelConfigs.<channel-id>.preferOver`，並填入較低優先順序的 Plugin id。請參閱 [/plugins/manifest#replacing-another-channel-plugin](/zh-TW/plugins/manifest#replacing-another-channel-plugin)。
-- 如果重複是意外造成，請使用 `plugins.entries.<plugin-id>.enabled: false` 停用其中一邊，或移除過期的 Plugin 安裝。
-- 如果你明確啟用了兩個 Plugin，OpenClaw 會保留該請求並回報衝突。請為該通道選擇一個 owner，或重新命名 Plugin 擁有的工具，讓 runtime 介面明確無歧義。
+- 如果某個 Plugin 有意替換另一個相同頻道 id 的 Plugin，偏好的 Plugin 應宣告 `channelConfigs.<channel-id>.preferOver`，並填入較低優先順序的 Plugin id。請參閱 [/plugins/manifest#replacing-another-channel-plugin](/zh-TW/plugins/manifest#replacing-another-channel-plugin)。
+- 如果重複是意外造成，請使用 `plugins.entries.<plugin-id>.enabled: false` 停用其中一方，或移除過時的 Plugin 安裝。
+- 如果你明確啟用了兩個 Plugin，OpenClaw 會保留該請求並回報衝突。請為該頻道選擇一個擁有者，或重新命名由 Plugin 擁有的工具，讓執行階段介面明確無歧義。
 
-## Plugin 槽位（專屬類別）
+## Plugin 插槽（專屬類別）
 
-部分類別是專屬的（一次只能有一個作用中）：
+某些類別是專屬的（同一時間只能有一個作用中）：
 
 ```json5
 {
@@ -364,10 +393,10 @@ openclaw plugins inspect <plugin-id> --runtime --json
 }
 ```
 
-| 槽位            | 控制項目              | 預設                |
+| 插槽            | 控制內容              | 預設                |
 | --------------- | --------------------- | ------------------- |
-| `memory`        | Active Memory Plugin  | `memory-core`       |
-| `contextEngine` | 作用中內容引擎        | `legacy`（內建）    |
+| `memory`        | 作用中的記憶體 Plugin | `memory-core`       |
+| `contextEngine` | 作用中的情境引擎      | `legacy`（內建）    |
 
 ## CLI 參考
 
@@ -417,35 +446,35 @@ openclaw plugins enable <id>
 openclaw plugins disable <id>
 ```
 
-隨附 Plugin 會與 OpenClaw 一起提供。許多預設會啟用（例如隨附模型提供者、隨附語音提供者，以及隨附瀏覽器 Plugin）。其他隨附 Plugin 仍需要 `openclaw plugins enable <id>`。
+內建 Plugin 隨 OpenClaw 一起提供。許多預設為啟用（例如內建模型提供者、內建語音提供者，以及內建瀏覽器 Plugin）。其他內建 Plugin 仍需要執行 `openclaw plugins enable <id>`。
 
-`--force` 會就地覆寫既有已安裝的 Plugin 或 hook pack。請使用 `openclaw plugins update <id-or-npm-spec>` 進行已追蹤 npm Plugin 的例行升級。它不支援與 `--link` 搭配使用，因為 `--link` 會重用來源路徑，而不是複製到受管理的安裝目標。
+`--force` 會就地覆寫既有已安裝的 Plugin 或 hook pack。例行升級受追蹤的 npm Plugin 時，請使用 `openclaw plugins update <id-or-npm-spec>`。它不支援與 `--link` 搭配使用，因為 `--link` 會重用來源路徑，而不是複製到受管理的安裝目標上。
 
-當 `plugins.allow` 已設定時，`openclaw plugins install` 會先將已安裝的 Plugin id 加入該允許清單，然後再啟用它。如果相同的 Plugin id 存在於 `plugins.deny`，安裝會移除該過時的拒絕項目，讓明確安裝的 Plugin 在重新啟動後可立即載入。
+當已設定 `plugins.allow` 時，`openclaw plugins install` 會先將已安裝的 Plugin id 加入該允許清單，再啟用它。如果同一個 Plugin id 存在於 `plugins.deny`，安裝流程會移除該過時的拒絕項目，讓明確安裝的 Plugin 在重新啟動後可立即載入。
 
-OpenClaw 會保留一份持久化的本機 Plugin registry，作為 Plugin 清單、貢獻擁有權與啟動規劃的冷讀取模型。安裝、更新、解除安裝、啟用與停用流程會在變更 Plugin 狀態後重新整理該 registry。同一個 `plugins/installs.json` 檔案會在頂層 `installRecords` 中保留持久安裝中繼資料，並在 `plugins` 中保留可重建的 manifest 中繼資料。如果 registry 遺失、過時或無效，`openclaw plugins registry --refresh` 會從安裝記錄、設定政策與 manifest/package 中繼資料重建其 manifest 檢視，而不載入 Plugin 執行階段模組。
-`openclaw plugins update <id-or-npm-spec>` 適用於已追蹤的安裝。傳入帶有 dist-tag 或精確版本的 npm package spec 時，會將套件名稱解析回已追蹤的 Plugin 記錄，並記錄新的 spec 供未來更新使用。傳入未帶版本的套件名稱時，會將精確釘選的安裝移回 registry 的預設發行線。如果已安裝的 npm Plugin 已符合解析後的版本與已記錄的 artifact 身分，OpenClaw 會略過更新，不下載、不重新安裝，也不重寫設定。
-當 `openclaw update` 在 beta 通道上執行時，預設線的 npm 與 ClawHub Plugin 記錄會先嘗試 `@beta`，若沒有 Plugin beta 發行版，則回退到預設/latest。精確版本與明確標籤會維持釘選。
+OpenClaw 會保留持久化的本機 Plugin 登錄，作為 Plugin 清單、貢獻歸屬與啟動規劃的冷讀取模型。安裝、更新、解除安裝、啟用與停用流程會在變更 Plugin 狀態後重新整理該登錄。同一個 `plugins/installs.json` 檔案會在頂層 `installRecords` 保留持久安裝中繼資料，並在 `plugins` 保留可重建的 manifest 中繼資料。如果登錄遺失、過時或無效，`openclaw plugins registry --refresh` 會從安裝記錄、設定政策，以及 manifest/package 中繼資料重建其 manifest 視圖，而不載入 Plugin runtime 模組。
+`openclaw plugins update <id-or-npm-spec>` 適用於受追蹤的安裝。傳入帶有 dist-tag 或精確版本的 npm package spec，會將套件名稱解析回受追蹤的 Plugin 記錄，並記錄新的 spec 供未來更新使用。傳入不含版本的套件名稱，會將精確釘選的安裝移回登錄的預設發行線。如果已安裝的 npm Plugin 已符合解析後的版本與已記錄的 artifact 身分，OpenClaw 會略過更新，不下載、不重新安裝，也不重寫設定。
+當 `openclaw update` 在 beta channel 執行時，預設線的 npm 與 ClawHub Plugin 記錄會先嘗試 `@beta`，並在沒有 Plugin beta 發行版時退回預設/latest。精確版本與明確標籤會維持釘選。
 
-`--pin` 僅適用於 npm。它不支援與 `--marketplace` 搭配使用，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm spec。
+`--pin` 僅適用於 npm。它不支援與 `--marketplace` 搭配使用，因為 marketplace 安裝會持久化 marketplace 來源中繼資料，而不是 npm spec。
 
-`--dangerously-force-unsafe-install` 是針對內建危險程式碼掃描器誤判的緊急覆寫。它允許 Plugin 安裝與 Plugin 更新繼續越過內建 `critical` 發現，但仍不會繞過 Plugin `before_install` 政策封鎖或掃描失敗封鎖。安裝掃描會忽略常見測試檔案與目錄，例如 `tests/`、`__tests__/`、`*.test.*` 與 `*.spec.*`，以避免封鎖已封裝的測試 mock；宣告的 Plugin 執行階段進入點即使使用其中一個名稱，仍會被掃描。
+`--dangerously-force-unsafe-install` 是用於內建危險程式碼掃描器誤判的緊急覆寫。它允許 Plugin 安裝與 Plugin 更新在內建 `critical` 發現項目後繼續進行，但仍不會略過 Plugin `before_install` 政策封鎖或掃描失敗封鎖。安裝掃描會忽略常見測試檔案與目錄，例如 `tests/`、`__tests__/`、`*.test.*` 與 `*.spec.*`，以避免封鎖打包的測試 mock；宣告的 Plugin runtime 進入點即使使用上述名稱之一，仍會被掃描。
 
-此 CLI flag 僅適用於 Plugin 安裝/更新流程。由 Gateway 支援的 skill 相依項安裝改用對應的 `dangerouslyForceUnsafeInstall` 請求覆寫，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
+此 CLI 旗標只適用於 Plugin 安裝/更新流程。Gateway 支援的 skill 相依項安裝會改用對應的 `dangerouslyForceUnsafeInstall` request 覆寫，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
 
-如果你在 ClawHub 發布的 Plugin 因掃描而被隱藏或封鎖，請開啟 ClawHub dashboard，或執行 `clawhub package rescan <name>` 要求 ClawHub 再次檢查它。`--dangerously-force-unsafe-install` 只影響你自己機器上的安裝；它不會要求 ClawHub 重新掃描該 Plugin，也不會讓被封鎖的發行版公開。
+如果你在 ClawHub 發佈的 Plugin 因掃描而被隱藏或封鎖，請開啟 ClawHub 儀表板，或執行 `clawhub package rescan <name>` 要求 ClawHub 再次檢查。`--dangerously-force-unsafe-install` 只會影響你自己機器上的安裝；它不會要求 ClawHub 重新掃描 Plugin，也不會讓被封鎖的發行版公開。
 
-相容套件組會參與相同的 Plugin 列表/檢查/啟用/停用流程。目前的執行階段支援包含套件組 Skills、Claude command-skills、Claude `settings.json` 預設值、Claude `.lsp.json` 與 manifest 宣告的 `lspServers` 預設值、Cursor command-skills，以及相容的 Codex hook 目錄。
+相容 bundle 會參與相同的 Plugin list/inspect/enable/disable 流程。目前 runtime 支援包含 bundle skills、Claude command-skills、Claude `settings.json` 預設值、Claude `.lsp.json` 與 manifest 宣告的 `lspServers` 預設值、Cursor command-skills，以及相容的 Codex hook 目錄。
 
-`openclaw plugins inspect <id>` 也會回報偵測到的套件組能力，以及套件組支援 Plugin 的受支援或不受支援 MCP 與 LSP server 項目。
+`openclaw plugins inspect <id>` 也會回報偵測到的 bundle 功能，以及 bundle 支援 Plugin 的已支援或不支援 MCP 與 LSP server 項目。
 
-Marketplace 來源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名稱、本機 marketplace 根目錄或 `marketplace.json` 路徑、像 `owner/repo` 的 GitHub 簡寫、GitHub repo URL，或 git URL。對於遠端 marketplace，Plugin 項目必須保留在複製的 marketplace repo 內，且只能使用相對路徑來源。
+Marketplace 來源可以是來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名稱、本機 marketplace root 或 `marketplace.json` 路徑、像 `owner/repo` 這類 GitHub 簡寫、GitHub repo URL，或 git URL。對於遠端 marketplace，Plugin 項目必須留在已複製的 marketplace repo 內，且只能使用相對路徑來源。
 
-完整詳細資訊請參閱 [`openclaw plugins` CLI 參考](/zh-TW/cli/plugins)。
+完整細節請參閱 [`openclaw plugins` CLI 參考](/zh-TW/cli/plugins)。
 
 ## Plugin API 概覽
 
-原生 Plugin 會匯出一個公開 `register(api)` 的 entry object。較舊的 Plugin 可能仍使用 `activate(api)` 作為舊版別名，但新的 Plugin 應使用 `register`。
+Native Plugin 會匯出一個 entry 物件，公開 `register(api)`。較舊的 Plugin 仍可使用 `activate(api)` 作為舊版別名，但新的 Plugin 應使用 `register`。
 
 ```typescript
 export default definePluginEntry({
@@ -465,26 +494,26 @@ export default definePluginEntry({
 });
 ```
 
-OpenClaw 會載入 entry object，並在 Plugin 啟用期間呼叫 `register(api)`。loader 仍會對較舊的 Plugin 回退到 `activate(api)`，但隨附 Plugin 與新的外部 Plugin 應將 `register` 視為公開契約。
+OpenClaw 會載入 entry 物件，並在 Plugin 啟用期間呼叫 `register(api)`。載入器仍會對較舊的 Plugin 退回使用 `activate(api)`，但內建 Plugin 與新的外部 Plugin 應將 `register` 視為公開合約。
 
 `api.registrationMode` 會告訴 Plugin 其 entry 為何被載入：
 
 | 模式            | 意義                                                                                                                          |
 | --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `full`          | 執行階段啟用。註冊工具、hook、服務、命令、路由與其他即時副作用。                              |
-| `discovery`     | 唯讀能力探索。註冊提供者與中繼資料；受信任的 Plugin entry 程式碼可載入，但應略過即時副作用。 |
-| `setup-only`    | 透過輕量 setup entry 載入通道 setup 中繼資料。                                                                |
-| `setup-runtime` | 同時需要執行階段 entry 的通道 setup 載入。                                                                         |
+| `full`          | Runtime 啟用。註冊工具、hook、服務、命令、路由與其他即時副作用。                              |
+| `discovery`     | 唯讀功能探索。註冊提供者與中繼資料；受信任的 Plugin entry 程式碼可能會載入，但應略過即時副作用。 |
+| `setup-only`    | 透過輕量 setup entry 載入 channel setup 中繼資料。                                                                |
+| `setup-runtime` | 同時需要 runtime entry 的 channel setup 載入。                                                                         |
 | `cli-metadata`  | 僅收集 CLI 命令中繼資料。                                                                                            |
 
-會開啟 socket、資料庫、背景 worker 或長生命週期 client 的 Plugin entry，應使用 `api.registrationMode === "full"` 保護這些副作用。探索載入會與啟用載入分開快取，且不會取代正在執行的 Gateway registry。探索是非啟用的，但不是免匯入：OpenClaw 可能會評估受信任的 Plugin entry 或通道 Plugin 模組來建立 snapshot。請保持模組頂層輕量且無副作用，並將網路 client、子程序、listener、憑證讀取與服務啟動移到完整執行階段路徑後方。
+會開啟 socket、database、background worker 或長生命週期 client 的 Plugin entry，應使用 `api.registrationMode === "full"` 保護這些副作用。Discovery 載入會與 activation 載入分開快取，且不會取代執行中的 Gateway 登錄。Discovery 是非啟用的，但不是免 import：OpenClaw 可能會評估受信任的 Plugin entry 或 channel Plugin 模組來建立 snapshot。請讓模組頂層保持輕量且無副作用，並將 network client、subprocess、listener、credential 讀取與 service startup 移到完整 runtime 路徑後方。
 
 常見註冊方法：
 
-| 方法                                  | 註冊內容           |
+| 方法                                  | 註冊項目           |
 | --------------------------------------- | --------------------------- |
-| `registerProvider`                      | 模型提供者（LLM）        |
-| `registerChannel`                       | 聊天通道                |
+| `registerProvider`                      | 模型提供者 (LLM)        |
+| `registerChannel`                       | 聊天 channel                |
 | `registerTool`                          | Agent 工具                  |
 | `registerHook` / `on(...)`              | 生命週期 hook             |
 | `registerSpeechProvider`                | 文字轉語音 / STT        |
@@ -494,31 +523,31 @@ OpenClaw 會載入 entry object，並在 Plugin 啟用期間呼叫 `register(api
 | `registerImageGenerationProvider`       | 影像生成            |
 | `registerMusicGenerationProvider`       | 音樂生成            |
 | `registerVideoGenerationProvider`       | 影片生成            |
-| `registerWebFetchProvider`              | Web 擷取 / scrape 提供者 |
+| `registerWebFetchProvider`              | Web fetch / scrape 提供者 |
 | `registerWebSearchProvider`             | Web 搜尋                  |
 | `registerHttpRoute`                     | HTTP endpoint               |
 | `registerCommand` / `registerCli`       | CLI 命令                |
 | `registerContextEngine`                 | Context engine              |
 | `registerService`                       | 背景服務          |
 
-型別化生命週期 hook 的 hook guard 行為：
+Typed lifecycle hook 的 hook guard 行為：
 
 - `before_tool_call`: `{ block: true }` 是終止性的；較低優先順序的 handler 會被略過。
-- `before_tool_call`: `{ block: false }` 是無操作，且不會清除先前的封鎖。
+- `before_tool_call`: `{ block: false }` 是 no-op，且不會清除先前的 block。
 - `before_install`: `{ block: true }` 是終止性的；較低優先順序的 handler 會被略過。
-- `before_install`: `{ block: false }` 是無操作，且不會清除先前的封鎖。
+- `before_install`: `{ block: false }` 是 no-op，且不會清除先前的 block。
 - `message_sending`: `{ cancel: true }` 是終止性的；較低優先順序的 handler 會被略過。
-- `message_sending`: `{ cancel: false }` 是無操作，且不會清除先前的取消。
+- `message_sending`: `{ cancel: false }` 是 no-op，且不會清除先前的 cancel。
 
-原生 Codex app-server 會將 Codex 原生工具事件橋接回這個 hook 介面。Plugin 可以透過 `before_tool_call` 封鎖原生 Codex 工具、透過 `after_tool_call` 觀察結果，並參與 Codex `PermissionRequest` 核准。該 bridge 尚未重寫 Codex 原生工具引數。確切的 Codex 執行階段支援邊界位於 [Codex harness v1 支援契約](/zh-TW/plugins/codex-harness#v1-support-contract)。
+Native Codex app-server 會將 Codex-native tool event 橋接回此 hook 介面。Plugin 可以透過 `before_tool_call` 封鎖 native Codex tool，透過 `after_tool_call` 觀察結果，並參與 Codex `PermissionRequest` 核准。此橋接尚未重寫 Codex-native tool 引數。確切的 Codex runtime 支援邊界位於 [Codex harness v1 支援合約](/zh-TW/plugins/codex-harness#v1-support-contract)。
 
-完整型別化 hook 行為請參閱 [SDK 概覽](/zh-TW/plugins/sdk-overview#hook-decision-semantics)。
+完整 typed hook 行為請參閱 [SDK 概覽](/zh-TW/plugins/sdk-overview#hook-decision-semantics)。
 
 ## 相關
 
 - [建置 Plugin](/zh-TW/plugins/building-plugins) — 建立你自己的 Plugin
-- [Plugin 套件組](/zh-TW/plugins/bundles) — Codex/Claude/Cursor 套件組相容性
-- [Plugin manifest](/zh-TW/plugins/manifest) — manifest schema
-- [註冊工具](/zh-TW/plugins/building-plugins#registering-agent-tools) — 在 Plugin 中新增 agent 工具
-- [Plugin 內部架構](/zh-TW/plugins/architecture) — 能力模型與載入 pipeline
-- [社群 Plugin](/zh-TW/plugins/community) — 第三方列表
+- [Plugin 套件組合](/zh-TW/plugins/bundles) — Codex/Claude/Cursor 套件組合相容性
+- [Plugin 資訊清單](/zh-TW/plugins/manifest) — 資訊清單結構描述
+- [註冊工具](/zh-TW/plugins/building-plugins#registering-agent-tools) — 在 Plugin 中新增代理工具
+- [Plugin 內部架構](/zh-TW/plugins/architecture) — 能力模型與載入管線
+- [社群 Plugin](/zh-TW/plugins/community) — 第三方清單

docs/zh-TW/tools/thinking.md

@@ -1,144 +1,145 @@
 ---
 read_when:
-    - 調整思考、快速模式或詳細指令的解析或預設值
-summary: /think、/fast、/verbose、/trace 的指令語法與推理可見度
+    - 調整 thinking、fast-mode 或 verbose 指令的解析或預設值
+summary: /think、/fast、/verbose、/trace 的指令語法和推理可見性
 title: 思考層級
 x-i18n:
-    generated_at: "2026-05-04T18:24:32Z"
+    generated_at: "2026-05-05T01:50:27Z"
     model: gpt-5.5
     provider: openai
-    source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
+    source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
     source_path: tools/thinking.md
     workflow: 16
 ---
 
 ## 功能
 
-- 在任何傳入本文中使用內嵌指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
-- 層級（別名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
-  - minimal → 「think」
-  - low → 「think hard」
-  - medium → 「think harder」
-  - high → 「ultrathink」（最大預算）
-  - xhigh → 「ultrathink+」（GPT-5.2+ 和 Codex 模型，加上 Anthropic Claude Opus 4.7 effort）
-  - adaptive → 供應商管理的自適應思考（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 動態思考）
-  - max → 供應商最大推理（Anthropic Claude Opus 4.7；Ollama 會將此對應到其最高原生 `think` effort）
+- 任何傳入本文中的行內指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
+- 等級（別名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
+  - minimal →「think」
+  - low →「think hard」
+  - medium →「think harder」
+  - high →「ultrathink」（最大預算）
+  - xhigh →「ultrathink+」（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort）
+  - adaptive → 供應商管理的 adaptive thinking（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini dynamic thinking）
+  - max → 供應商最大 reasoning（Anthropic Claude Opus 4.7；Ollama 會將此對應到其最高原生 `think` effort）
   - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 會對應到 `xhigh`。
   - `highest` 會對應到 `high`。
 - 供應商注意事項：
-  - 思考選單和選擇器由供應商設定檔驅動。供應商 Plugin 會宣告所選模型的確切層級集合，包括二元 `on` 等標籤。
-  - 只有支援的供應商/模型設定檔才會顯示 `adaptive`、`xhigh` 和 `max`。對不支援層級輸入的指令，會以該模型的有效選項拒絕。
-  - 既有儲存的不支援層級會依供應商設定檔排名重新對應。在非自適應模型上，`adaptive` 會回退到 `medium`，而 `xhigh` 和 `max` 會回退到所選模型支援的最大非 off 層級。
-  - 未明確設定思考層級時，Anthropic Claude 4.6 模型預設為 `adaptive`。
-  - Anthropic Claude Opus 4.7 不會預設為自適應思考。除非你明確設定思考層級，否則其 API effort 預設值仍由供應商管理。
-  - Anthropic Claude Opus 4.7 會將 `/think xhigh` 對應到自適應思考加上 `output_config.effort: "xhigh"`，因為 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 設定。
-  - Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到同一條供應商管理的最大 effort 路徑。
-  - DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，較低的非 off 層級則會對應到 `high`。
-  - 支援思考的 Ollama 模型公開 `/think low|medium|high|max`；`max` 會對應到原生 `think: "high"`，因為 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字串。
-  - OpenAI GPT 模型會依模型專屬的 Responses API effort 支援對應 `/think`。只有目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用的 reasoning 承載，而不是傳送不支援的值。
-  - 自訂 OpenAI 相容目錄項目可以透過將 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 設為包含 `"xhigh"` 來選擇支援 `/think xhigh`。這會使用同一份用於對應傳出 OpenAI reasoning effort 承載的相容性中繼資料，因此選單、工作階段驗證、agent CLI 和 `llm-task` 會與傳輸行為一致。
-  - 過期設定的 OpenRouter Hunter Alpha 參照會略過代理推理注入，因為該已退役路由可能透過推理欄位回傳最終答案文字。
-  - Google Gemini 會將 `/think adaptive` 對應到 Gemini 由供應商管理的動態思考。Gemini 3 請求會省略固定的 `thinkingLevel`，而 Gemini 2.5 請求會傳送 `thinkingBudget: -1`；固定層級仍會對應到該模型系列最接近的 Gemini `thinkingLevel` 或預算。
-  - Anthropic 相容串流路徑上的 MiniMax (`minimax/*`) 預設為 `thinking: { type: "disabled" }`，除非你在模型參數或請求參數中明確設定思考。這可避免 MiniMax 非原生 Anthropic 串流格式洩漏 `reasoning_content` 差異內容。
-  - Z.AI (`zai/*`) 只支援二元思考（`on`/`off`）。任何非 `off` 層級都會視為 `on`（對應到 `low`）。
-  - Moonshot (`moonshot/*`) 會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 層級對應到 `thinking: { type: "enabled" }`。啟用思考時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值正規化為 `auto`。
+  - Thinking 選單和選取器由供應商設定檔驅動。供應商 plugins 會宣告所選模型的確切等級集合，包括像 binary `on` 這樣的標籤。
+  - 只有支援的供應商/模型設定檔才會顯示 `adaptive`、`xhigh` 和 `max`。對不支援等級輸入的指令會被拒絕，並顯示該模型的有效選項。
+  - 現有已儲存的不支援等級會依供應商設定檔排名重新對應。`adaptive` 在非 adaptive 模型上會退回到 `medium`，而 `xhigh` 和 `max` 會退回到所選模型支援的最大非 off 等級。
+  - 未設定明確 thinking 等級時，Anthropic Claude 4.6 模型預設為 `adaptive`。
+  - Anthropic Claude Opus 4.7 不會預設為 adaptive thinking。除非你明確設定 thinking 等級，否則其 API effort 預設值仍由供應商擁有。
+  - Anthropic Claude Opus 4.7 會將 `/think xhigh` 對應到 adaptive thinking 加上 `output_config.effort: "xhigh"`，因為 `/think` 是 thinking 指令，而 `xhigh` 是 Opus 4.7 的 effort 設定。
+  - Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到同一條供應商擁有的 max effort 路徑。
+  - 直接 DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，而較低的非 off 等級會對應到 `high`。
+  - 由 OpenRouter 路由的 DeepSeek V4 模型公開 `/think xhigh`，並傳送 OpenRouter 支援的 `reasoning_effort` 值。已儲存的 `max` 覆寫會退回到 `xhigh`。
+  - Ollama 支援 thinking 的模型公開 `/think low|medium|high|max`；`max` 會對應到原生 `think: "high"`，因為 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字串。
+  - OpenAI GPT 模型會透過模型特定的 Responses API effort 支援對應 `/think`。只有當目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用的 reasoning payload，而不是傳送不支援的值。
+  - 自訂 OpenAI 相容目錄項目可以將 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 設定為包含 `"xhigh"`，以選擇加入 `/think xhigh`。這會使用同一份對應輸出 OpenAI reasoning effort payload 的相容性中繼資料，因此選單、工作階段驗證、agent CLI 和 `llm-task` 會與傳輸行為一致。
+  - 過期設定的 OpenRouter Hunter Alpha refs 會略過 proxy reasoning 注入，因為該已停用路由可能會透過 reasoning 欄位傳回最終回答文字。
+  - Google Gemini 會將 `/think adaptive` 對應到 Gemini 供應商擁有的 dynamic thinking。Gemini 3 請求會省略固定的 `thinkingLevel`，而 Gemini 2.5 請求會傳送 `thinkingBudget: -1`；固定等級仍會對應到該模型家族最接近的 Gemini `thinkingLevel` 或預算。
+  - Anthropic 相容串流路徑上的 MiniMax (`minimax/*`) 預設為 `thinking: { type: "disabled" }`，除非你在模型參數或請求參數中明確設定 thinking。這會避免 MiniMax 非原生 Anthropic 串流格式洩漏 `reasoning_content` deltas。
+  - Z.AI (`zai/*`) 只支援 binary thinking（`on`/`off`）。任何非 `off` 等級都會視為 `on`（對應到 `low`）。
+  - Moonshot (`moonshot/*`) 會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 等級對應到 `thinking: { type: "enabled" }`。啟用 thinking 時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值正規化為 `auto`。
 
 ## 解析順序
 
-1. 訊息上的內嵌指令（僅套用於該訊息）。
+1. 訊息上的行內指令（僅套用於該訊息）。
 2. 工作階段覆寫（透過傳送只有指令的訊息設定）。
-3. 每個 agent 的預設值（設定中的 `agents.list[].thinkingDefault`）。
-4. 全域預設值（設定中的 `agents.defaults.thinkingDefault`）。
-5. 回退：可用時使用供應商宣告的預設值；否則，具備推理能力的模型會解析為 `medium` 或該模型最接近的支援非 `off` 層級，而不具備推理能力的模型維持 `off`。
+3. 每個 agent 的預設值（config 中的 `agents.list[].thinkingDefault`）。
+4. 全域預設值（config 中的 `agents.defaults.thinkingDefault`）。
+5. 後援：可用時使用供應商宣告的預設值；否則具 reasoning 能力的模型會解析為 `medium` 或該模型最接近的受支援非 `off` 等級，而非 reasoning 模型會維持 `off`。
 
 ## 設定工作階段預設值
 
 - 傳送一則**只有**指令的訊息（允許空白），例如 `/think:medium` 或 `/t high`。
-- 這會在目前工作階段中保持生效（預設依傳送者區分）；可由 `/think:off` 或工作階段閒置重設清除。
-- 會傳送確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果層級無效（例如 `/thinking big`），命令會被拒絕並附上提示，工作階段狀態不會變更。
-- 傳送不含引數的 `/think`（或 `/think:`）可查看目前思考層級。
+- 該設定會固定於目前工作階段（預設按傳送者）；由 `/think:off` 或工作階段閒置重設清除。
+- 會送出確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果等級無效（例如 `/thinking big`），該命令會被拒絕並附上提示，且工作階段狀態保持不變。
+- 傳送沒有引數的 `/think`（或 `/think:`）可查看目前 thinking 等級。
 
 ## 依 agent 套用
 
-- **嵌入式 Pi**：解析出的層級會傳遞給程序內 Pi agent runtime。
-- **Claude CLI 後端**：使用 `claude-cli` 時，非 off 層級會以 `--effort` 傳遞給 Claude Code；請參閱 [CLI 後端](/zh-TW/gateway/cli-backends)。
+- **內嵌式 Pi**：已解析的等級會傳遞到程序內 Pi agent 執行階段。
+- **Claude CLI 後端**：使用 `claude-cli` 時，非 off 等級會作為 `--effort` 傳遞給 Claude Code；請參閱 [CLI 後端](/zh-TW/gateway/cli-backends)。
 
-## 快速模式 (/fast)
+## 快速模式（/fast）
 
-- 層級：`on|off`。
+- 等級：`on|off`。
 - 只有指令的訊息會切換工作階段快速模式覆寫，並回覆 `Fast mode enabled.` / `Fast mode disabled.`。
-- 傳送不含模式的 `/fast`（或 `/fast status`）可查看目前有效的快速模式狀態。
-- OpenClaw 會依此順序解析快速模式：
-  1. 內嵌/只有指令的 `/fast on|off`
+- 傳送沒有模式的 `/fast`（或 `/fast status`）可查看目前有效的快速模式狀態。
+- OpenClaw 會依下列順序解析快速模式：
+  1. 行內/只有指令的 `/fast on|off`
   2. 工作階段覆寫
   3. 每個 agent 的預設值（`agents.list[].fastModeDefault`）
   4. 每個模型設定：`agents.defaults.models["<provider>/<model>"].params.fastMode`
-  5. 回退：`off`
-- 對於 `openai/*`，快速模式會透過在支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI 優先處理。
-- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 在兩種驗證路徑間維持一個共用的 `/fast` 切換。
-- 對於直接公開的 `anthropic/*` 請求，包括傳送至 `api.anthropic.com` 的 OAuth 驗證流量，快速模式會對應到 Anthropic 服務層級：`/fast on` 設定 `service_tier=auto`，`/fast off` 設定 `service_tier=standard_only`。
+  5. 後援：`off`
+- 對於 `openai/*`，快速模式會在支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI priority processing。
+- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 會在兩條 auth 路徑之間保留一個共用的 `/fast` 切換。
+- 對於直接公開的 `anthropic/*` 請求，包括傳送到 `api.anthropic.com` 的 OAuth 驗證流量，快速模式會對應到 Anthropic service tiers：`/fast on` 設定 `service_tier=auto`，`/fast off` 設定 `service_tier=standard_only`。
 - 對於 Anthropic 相容路徑上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。
-- 同時設定時，明確的 Anthropic `serviceTier` / `service_tier` 模型參數會覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理基底 URL 略過 Anthropic 服務層級注入。
-- `/status` 只有在啟用快速模式時才會顯示 `Fast`。
+- 同時設定時，明確的 Anthropic `serviceTier` / `service_tier` 模型參數會覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic proxy base URL 略過 Anthropic service-tier 注入。
+- `/status` 只會在快速模式啟用時顯示 `Fast`。
 
-## 詳細指令 (/verbose 或 /v)
+## 詳細指令（/verbose 或 /v）
 
-- 層級：`on`（最小）| `full` | `off`（預設）。
-- 只有指令的訊息會切換工作階段詳細輸出，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。
-- `/verbose off` 會儲存明確的工作階段覆寫；可透過 Sessions UI 選擇 `inherit` 來清除。
-- 內嵌指令僅影響該訊息；否則會套用工作階段/全域預設值。
-- 傳送不含引數的 `/verbose`（或 `/verbose:`）可查看目前詳細層級。
-- 啟用詳細輸出時，會發出結構化工具結果的 agent（Pi、其他 JSON agent）會將每個工具呼叫以自己的僅中繼資料訊息傳回；可用時前置 `<emoji> <tool-name>: <arg>`。這些工具摘要會在每個工具開始時立即傳送（分開的訊息泡泡），而不是以串流差異內容傳送。
-- 工具失敗摘要在一般模式中仍可見，但原始錯誤詳細資料後綴會隱藏，除非詳細層級為 `on` 或 `full`。
-- 當詳細層級為 `full` 時，工具輸出也會在完成後轉送（分開的訊息泡泡，截斷至安全長度）。如果你在執行進行中切換 `/verbose on|full|off`，後續工具泡泡會遵循新的設定。
-- `agents.defaults.toolProgressDetail` 控制 `/verbose` 工具摘要和進度草稿工具行的形狀。使用 `"explain"`（預設）可取得精簡的人類標籤，例如 `🛠️ Exec: checking JS syntax`；如果你也想附加原始命令/詳細資料以進行偵錯，請使用 `"raw"`。每個 agent 的 `agents.list[].toolProgressDetail` 會覆寫預設值。
+- 等級：`on`（minimal）| `full` | `off`（預設）。
+- 只有指令的訊息會切換工作階段詳細模式並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效等級會傳回提示，且不會變更狀態。
+- `/verbose off` 會儲存明確的工作階段覆寫；透過 Sessions UI 選擇 `inherit` 可清除它。
+- 行內指令只會影響該訊息；否則會套用工作階段/全域預設值。
+- 傳送沒有引數的 `/verbose`（或 `/verbose:`）可查看目前詳細等級。
+- 開啟詳細模式時，會發出結構化工具結果的 agents（Pi、其他 JSON agents）會將每個工具呼叫作為自己的 metadata-only 訊息送回，可用時前綴為 `<emoji> <tool-name>: <arg>`。這些工具摘要會在每個工具一開始時立即送出（分開的泡泡），而不是作為 streaming deltas。
+- 工具失敗摘要在一般模式下仍然可見，但原始錯誤詳細資料後綴會被隱藏，除非 verbose 是 `on` 或 `full`。
+- 當 verbose 為 `full` 時，工具輸出也會在完成後轉送（分開的泡泡，截斷到安全長度）。如果你在執行期間切換 `/verbose on|full|off`，後續工具泡泡會遵循新設定。
+- `agents.defaults.toolProgressDetail` 控制 `/verbose` 工具摘要和進度草稿工具行的形態。使用 `"explain"`（預設）可取得精簡的人類標籤，例如 `🛠️ Exec: checking JS syntax`；當你也想附加原始命令/詳細資料以供偵錯時，使用 `"raw"`。每個 agent 的 `agents.list[].toolProgressDetail` 會覆寫預設值。
   - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
   - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
 
-## Plugin 追蹤指令 (/trace)
+## Plugin trace 指令（/trace）
 
-- 層級：`on` | `off`（預設）。
-- 只有指令的訊息會切換工作階段 Plugin 追蹤輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。
-- 內嵌指令僅影響該訊息；否則會套用工作階段/全域預設值。
-- 傳送不含引數的 `/trace`（或 `/trace:`）可查看目前追蹤層級。
-- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 擁有的追蹤/偵錯行，例如 Active Memory 偵錯摘要。
-- 追蹤行可能出現在 `/status` 中，也可能在一般助理回覆後作為後續診斷訊息出現。
+- 等級：`on` | `off`（預設）。
+- 只有指令的訊息會切換工作階段 Plugin trace 輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。
+- 行內指令只會影響該訊息；否則會套用工作階段/全域預設值。
+- 傳送沒有引數的 `/trace`（或 `/trace:`）可查看目前 trace 等級。
+- `/trace` 比 `/verbose` 更窄：它只會公開 Plugin 擁有的 trace/debug 行，例如 Active Memory debug 摘要。
+- Trace 行可以出現在 `/status` 中，也可以在一般 assistant 回覆後作為後續診斷訊息出現。
 
-## 推理可見性 (/reasoning)
+## Reasoning 可見性（/reasoning）
 
-- 層級：`on|off|stream`。
-- 只有指令的訊息會切換是否在回覆中顯示思考區塊。
-- 啟用時，推理會以前置 `Reasoning:` 的**分開訊息**傳送。
-- `stream`（僅 Telegram）：在回覆產生時將推理串流到 Telegram 草稿泡泡，然後傳送不含推理的最終答案。
+- 等級：`on|off|stream`。
+- 只有指令的訊息會切換是否在回覆中顯示 thinking blocks。
+- 啟用時，reasoning 會作為**分開的訊息**送出，前綴為 `Reasoning:`。
+- `stream`（僅 Telegram）：在產生回覆期間，將 reasoning 串流到 Telegram 草稿泡泡中，然後傳送不含 reasoning 的最終回答。
 - 別名：`/reason`。
-- 傳送不含引數的 `/reasoning`（或 `/reasoning:`）可查看目前推理層級。
-- 解析順序：內嵌指令，接著是工作階段覆寫，接著是每個 agent 的預設值（`agents.list[].reasoningDefault`），最後回退（`off`）。
+- 傳送沒有引數的 `/reasoning`（或 `/reasoning:`）可查看目前 reasoning 等級。
+- 解析順序：行內指令，然後工作階段覆寫，然後每個 agent 的預設值（`agents.list[].reasoningDefault`），最後是後援（`off`）。
 
-格式錯誤的本機模型推理標籤會保守處理。封閉的 `<think>...</think>` 區塊在一般回覆中維持隱藏，已可見文字之後未封閉的推理也會隱藏。如果回覆完全包在單一未封閉的開啟標籤中，且否則會以空文字交付，OpenClaw 會移除格式錯誤的開啟標籤並交付剩餘文字。
+格式錯誤的本機模型 reasoning 標籤會以保守方式處理。封閉的 `<think>...</think>` 區塊在一般回覆中會保持隱藏，而已可見文字之後未封閉的 reasoning 也會被隱藏。如果回覆完全包在單一未封閉開頭標籤中，且否則會以空文字傳遞，OpenClaw 會移除格式錯誤的開頭標籤並傳遞剩餘文字。
 
 ## 相關
 
-- 提升模式文件位於[提升模式](/zh-TW/tools/elevated)。
+- Elevated mode 文件位於 [Elevated mode](/zh-TW/tools/elevated)。
 
-## Heartbeat
+## Heartbeats
 
-- Heartbeat 探測本文是設定的 heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的內嵌指令會照常套用（但請避免從 heartbeat 變更工作階段預設值）。
-- Heartbeat 交付預設只傳送最終承載。若也要傳送分開的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或每個 agent 的 `agents.list[].heartbeat.includeReasoning: true`。
+- Heartbeat 探測本文是已設定的 Heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的行內指令照常套用（但避免從 Heartbeats 變更工作階段預設值）。
+- Heartbeat 傳遞預設只會傳送最終 payload。若也要傳送分開的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或每個 agent 的 `agents.list[].heartbeat.includeReasoning: true`。
 
-## Web 聊天 UI
+## 網頁聊天 UI
 
-- Web 聊天思考選擇器會在頁面載入時，從傳入工作階段儲存區/設定鏡像工作階段儲存的層級。
-- 選取其他層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，也不是一次性的 `thinkingOnce` 覆寫。
-- 第一個選項一律是 `Default (<resolved level>)`，其中解析出的預設值來自作用中工作階段模型的供應商思考設定檔，加上 `/status` 和 `session_status` 使用的相同回退邏輯。
-- 選擇器使用 Gateway 工作階段列/預設值回傳的 `thinkingLevels`，並將 `thinkingOptions` 保留為舊版標籤清單。瀏覽器 UI 不保留自己的供應商 regex 清單；Plugin 擁有模型專屬層級集合。
-- `/think:<level>` 仍可運作，並會更新同一個儲存的工作階段層級，因此聊天指令和選擇器會保持同步。
+- 網頁聊天 thinking 選取器會在頁面載入時，鏡像來自傳入工作階段 store/config 的工作階段已儲存等級。
+- 選擇另一個等級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，也不是一次性的 `thinkingOnce` 覆寫。
+- 第一個選項永遠是 `Default (<resolved level>)`，其中已解析的預設值來自作用中工作階段模型的供應商 thinking 設定檔，加上 `/status` 和 `session_status` 使用的相同後援邏輯。
+- 選取器使用 gateway 工作階段列/預設值傳回的 `thinkingLevels`，並保留 `thinkingOptions` 作為舊版標籤清單。瀏覽器 UI 不會保留自己的供應商 regex 清單；plugins 擁有模型特定的等級集合。
+- `/think:<level>` 仍然有效，並會更新同一個已儲存的工作階段等級，因此聊天指令和選取器會保持同步。
 
 ## 供應商設定檔
 
-- 提供者 Plugin 可以公開 `resolveThinkingProfile(ctx)`，以定義模型支援的層級與預設值。
-- 代理 Claude 模型的提供者 Plugin 應重用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 與代理目錄保持一致。
-- 每個設定檔層級都有儲存的標準 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），也可以包含顯示用的 `label`。二元提供者使用 `{ id: "low", label: "on" }`。
-- 需要驗證明確思考覆寫的工具 Plugin，應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 搭配 `api.runtime.agent.normalizeThinkingLevel(...)`；不應維護自己的提供者/模型層級清單。
-- 可存取已設定自訂模型中繼資料的工具 Plugin，可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 選擇加入設定反映在 Plugin 端驗證中。
-- 已發布的舊版掛鉤（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍作為相容性配接器保留，但新的自訂層級集合應使用 `resolveThinkingProfile`。
-- Gateway 列與預設值會公開 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證所用相同的設定檔 ID 與標籤。
+- Provider Plugin 可以公開 `resolveThinkingProfile(ctx)` 來定義模型支援的層級與預設值。
+- 代理 Claude 模型的 Provider Plugin 應重複使用來自 `openclaw/plugin-sdk/provider-model-shared` 的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 與代理目錄保持一致。
+- 每個設定檔層級都有儲存的標準 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），並且可以包含顯示用的 `label`。二元 Provider 使用 `{ id: "low", label: "on" }`。
+- 需要驗證明確思考覆寫的 Tool Plugin 應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它們不應維護自己的 Provider/模型層級清單。
+- 可存取已設定自訂模型中繼資料的 Tool Plugin 可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 的選擇加入反映在 Plugin 端驗證中。
+- 已發布的舊版 hooks（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）會保留作為相容性轉接器，但新的自訂層級集合應使用 `resolveThinkingProfile`。
+- Gateway 列/預設值會公開 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證所用相同的設定檔 id 和標籤。

docs/zh-TW/tools/video-generation.md

@@ -4,78 +4,78 @@ read_when:
     - 設定影片生成提供者與模型
     - 了解 video_generate 工具參數
 sidebarTitle: Video generation
-summary: 透過 video_generate，從文字、圖片或影片參照跨 16 個供應商後端產生影片
+summary: 透過 video_generate，跨 16 個提供者後端從文字、圖片或影片參考生成影片
 title: 影片生成
 x-i18n:
-    generated_at: "2026-04-30T03:49:00Z"
+    generated_at: "2026-05-05T01:50:51Z"
     model: gpt-5.5
     provider: openai
-    source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
+    source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
     source_path: tools/video-generation.md
     workflow: 16
 ---
 
-OpenClaw agents 可以從文字提示、參考圖片或既有影片產生影片。支援十六種供應商後端，每種都有不同的模型選項、輸入模式與功能集。agent 會根據你的設定與可用的 API keys 自動選擇合適的供應商。
+OpenClaw agents 可以從文字提示、參照圖片或現有影片生成影片。支援十六個提供者後端，每個後端都有不同的模型選項、輸入模式和功能集。agent 會根據你的設定和可用的 API 金鑰，自動選擇合適的提供者。
 
 <Note>
-`video_generate` 工具只會在至少有一個影片產生供應商可用時出現。如果你在 agent 工具中看不到它，請設定供應商 API key 或設定 `agents.defaults.videoGenerationModel`。
+`video_generate` 工具只有在至少有一個影片生成提供者可用時才會出現。如果你在 agent 工具中看不到它，請設定提供者 API 金鑰，或設定 `agents.defaults.videoGenerationModel`。
 </Note>
 
-OpenClaw 將影片產生視為三種執行階段模式：
+OpenClaw 將影片生成視為三種執行階段模式：
 
-- `generate` — 沒有參考媒體的文字轉影片請求。
-- `imageToVideo` — 請求包含一張或多張參考圖片。
-- `videoToVideo` — 請求包含一個或多個參考影片。
+- `generate` — 沒有參照媒體的文字轉影片請求。
+- `imageToVideo` — 請求包含一張或多張參照圖片。
+- `videoToVideo` — 請求包含一段或多段參照影片。
 
-供應商可以支援這些模式的任意子集。工具會在提交前驗證作用中的模式，並在 `action=list` 中回報支援的模式。
+提供者可以支援這些模式的任意子集。工具會在送出前驗證作用中的模式，並在 `action=list` 中回報支援的模式。
 
 ## 快速開始
 
 <Steps>
-  <Step title="設定驗證">
-    為任何支援的供應商設定 API key：
+  <Step title="Configure auth">
+    為任何支援的提供者設定 API 金鑰：
 
     ```bash
     export GEMINI_API_KEY="your-key"
     ```
 
   </Step>
-  <Step title="選擇預設模型（選用）">
+  <Step title="Pick a default model (optional)">
     ```bash
     openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
     ```
   </Step>
-  <Step title="詢問 agent">
-    > 產生一段 5 秒的電影感影片，內容是一隻友善的龍蝦在日落時衝浪。
+  <Step title="Ask the agent">
+    > 生成一段 5 秒鐘的電影感影片，內容是一隻友善的龍蝦在夕陽下衝浪。
 
     agent 會自動呼叫 `video_generate`。不需要工具允許清單。
 
   </Step>
 </Steps>
 
-## 非同步產生如何運作
+## 非同步生成的運作方式
 
-影片產生是非同步的。當 agent 在 session 中呼叫 `video_generate` 時：
+影片生成是非同步的。當 agent 在工作階段中呼叫 `video_generate` 時：
 
-1. OpenClaw 會將請求提交給供應商，並立即回傳 task id。
-2. 供應商會在背景處理工作（通常 30 秒到 5 分鐘，取決於供應商與解析度）。
-3. 影片準備好後，OpenClaw 會用內部完成事件喚醒同一個 session。
-4. agent 會將完成的影片張貼回原始對話。
+1. OpenClaw 會將請求送交提供者，並立即傳回任務 ID。
+2. 提供者會在背景處理工作（通常依提供者和解析度而定，需要 30 秒到 5 分鐘）。
+3. 影片準備好後，OpenClaw 會使用內部完成事件喚醒同一個工作階段。
+4. agent 會告知使用者並附上完成的影片。在使用僅訊息工具可見傳遞的群組/頻道聊天中，agent 會透過訊息工具轉送結果，而不是由 OpenClaw 直接發布。
 
-當工作正在進行時，同一個 session 中重複的 `video_generate` 呼叫會回傳目前的任務狀態，而不是開始另一個產生工作。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 從 CLI 檢查進度。
+當工作進行中時，同一工作階段中重複的 `video_generate` 呼叫會傳回目前任務狀態，而不是啟動另一個生成工作。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可從 CLI 檢查進度。
 
-在沒有 session 支援的 agent 執行之外（例如直接工具叫用），工具會退回到行內產生，並在同一回合回傳最終媒體路徑。
+在沒有工作階段支援的 agent 執行之外（例如直接工具呼叫），工具會退回為行內生成，並在同一回合中傳回最終媒體路徑。
 
-當供應商回傳位元組時，產生的影片檔案會儲存在 OpenClaw 管理的媒體儲存空間下。預設的產生影片儲存上限會遵循影片媒體限制，而 `agents.defaults.mediaMaxMb` 會提高上限以支援較大的算繪。當供應商也回傳託管輸出 URL 時，如果本機持久化因檔案過大而拒絕，OpenClaw 可以改為傳遞該 URL，而不是讓任務失敗。
+當提供者傳回位元組時，生成的影片檔案會儲存在 OpenClaw 管理的媒體儲存空間下。預設的生成影片儲存上限會遵循影片媒體限制，而 `agents.defaults.mediaMaxMb` 會提高此限制以支援較大的算繪結果。當提供者也傳回託管輸出 URL 時，如果本機持久化因檔案過大而拒絕儲存，OpenClaw 可以傳遞該 URL，而不是讓任務失敗。
 
 ### 任務生命週期
 
 | 狀態        | 意義                                                                                             |
 | ----------- | ------------------------------------------------------------------------------------------------ |
-| `queued`    | 任務已建立，正在等待供應商接受。                                                                 |
-| `running`   | 供應商正在處理（通常 30 秒到 5 分鐘，取決於供應商與解析度）。                                    |
-| `succeeded` | 影片已準備好；agent 會被喚醒並將它張貼到對話。                                                   |
-| `failed`    | 供應商錯誤或逾時；agent 會被喚醒並附上錯誤詳細資料。                                             |
+| `queued`    | 任務已建立，正在等待提供者接受。                                                                 |
+| `running`   | 提供者正在處理（通常依提供者和解析度而定，需要 30 秒到 5 分鐘）。                                |
+| `succeeded` | 影片已準備好；agent 會被喚醒並將影片發布到對話中。                                               |
+| `failed`    | 提供者錯誤或逾時；agent 會被喚醒並收到錯誤詳細資料。                                             |
 
 從 CLI 檢查狀態：
 
@@ -85,68 +85,68 @@ openclaw tasks show <taskId>
 openclaw tasks cancel <taskId>
 ```
 
-如果目前 session 已經有影片任務處於 `queued` 或 `running`，`video_generate` 會回傳既有任務狀態，而不是開始新的任務。使用 `action: "status"` 可明確檢查，而不會觸發新的產生工作。
+如果目前工作階段已有影片任務處於 `queued` 或 `running`，`video_generate` 會傳回現有任務狀態，而不是啟動新的任務。使用 `action: "status"` 可明確檢查狀態，而不觸發新的生成工作。
 
-## 支援的供應商
+## 支援的提供者
 
-| 供應商                | 預設模型                        | 文字 | 圖片參考                                             | 影片參考                                        | 驗證                                     |
+| 提供者                | 預設模型                        | 文字 | 圖片參照                                             | 影片參照                                        | 驗證                                     |
 | --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
 | Alibaba               | `wan2.6-t2v`                    |  ✓   | 是（遠端 URL）                                       | 是（遠端 URL）                                  | `MODELSTUDIO_API_KEY`                    |
-| BytePlus (1.0)        | `seedance-1-0-pro-250528`       |  ✓   | 最多 2 張圖片（僅限 I2V 模型；第一格 + 最後一格）    | —                                               | `BYTEPLUS_API_KEY`                       |
-| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215`       |  ✓   | 最多 2 張圖片（透過角色指定第一格 + 最後一格）       | —                                               | `BYTEPLUS_API_KEY`                       |
-| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128`  |  ✓   | 最多 9 張參考圖片                                    | 最多 3 個影片                                   | `BYTEPLUS_API_KEY`                       |
-| ComfyUI               | `workflow`                      |  ✓   | 1 張圖片                                             | —                                               | `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` |
+| BytePlus (1.0)        | `seedance-1-0-pro-250528`       |  ✓   | 最多 2 張圖片（僅限 I2V 模型；第一幀 + 最後一幀）    | —                                               | `BYTEPLUS_API_KEY`                       |
+| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215`       |  ✓   | 最多 2 張圖片（透過角色指定第一幀 + 最後一幀）       | —                                               | `BYTEPLUS_API_KEY`                       |
+| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128`  |  ✓   | 最多 9 張參照圖片                                    | 最多 3 段影片                                   | `BYTEPLUS_API_KEY`                       |
+| ComfyUI               | `workflow`                      |  ✓   | 1 張圖片                                             | —                                               | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
 | DeepInfra             | `Pixverse/Pixverse-T2V`         |  ✓   | —                                                    | —                                               | `DEEPINFRA_API_KEY`                      |
-| fal                   | `fal-ai/minimax/video-01-live`  |  ✓   | 1 張圖片；Seedance reference-to-video 最多 9 張      | Seedance reference-to-video 最多 3 個影片       | `FAL_KEY`                                |
-| Google                | `veo-3.1-fast-generate-preview` |  ✓   | 1 張圖片                                             | 1 個影片                                        | `GEMINI_API_KEY`                         |
+| fal                   | `fal-ai/minimax/video-01-live`  |  ✓   | 1 張圖片；使用 Seedance 參照轉影片時最多 9 張        | 使用 Seedance 參照轉影片時最多 3 段影片         | `FAL_KEY`                                |
+| Google                | `veo-3.1-fast-generate-preview` |  ✓   | 1 張圖片                                             | 1 段影片                                        | `GEMINI_API_KEY`                         |
 | MiniMax               | `MiniMax-Hailuo-2.3`            |  ✓   | 1 張圖片                                             | —                                               | `MINIMAX_API_KEY` 或 MiniMax OAuth       |
-| OpenAI                | `sora-2`                        |  ✓   | 1 張圖片                                             | 1 個影片                                        | `OPENAI_API_KEY`                         |
-| OpenRouter            | `google/veo-3.1-fast`           |  ✓   | 最多 4 張圖片（第一/最後一格或參考圖）               | —                                               | `OPENROUTER_API_KEY`                     |
+| OpenAI                | `sora-2`                        |  ✓   | 1 張圖片                                             | 1 段影片                                        | `OPENAI_API_KEY`                         |
+| OpenRouter            | `google/veo-3.1-fast`           |  ✓   | 最多 4 張圖片（第一/最後一幀或參照）                 | —                                               | `OPENROUTER_API_KEY`                     |
 | Qwen                  | `wan2.6-t2v`                    |  ✓   | 是（遠端 URL）                                       | 是（遠端 URL）                                  | `QWEN_API_KEY`                           |
-| Runway                | `gen4.5`                        |  ✓   | 1 張圖片                                             | 1 個影片                                        | `RUNWAYML_API_SECRET`                    |
+| Runway                | `gen4.5`                        |  ✓   | 1 張圖片                                             | 1 段影片                                        | `RUNWAYML_API_SECRET`                    |
 | Together              | `Wan-AI/Wan2.2-T2V-A14B`        |  ✓   | 1 張圖片                                             | —                                               | `TOGETHER_API_KEY`                       |
 | Vydra                 | `veo3`                          |  ✓   | 1 張圖片（`kling`）                                  | —                                               | `VYDRA_API_KEY`                          |
-| xAI                   | `grok-imagine-video`            |  ✓   | 1 張首格圖片或最多 7 張 `reference_image`s           | 1 個影片                                        | `XAI_API_KEY`                            |
+| xAI                   | `grok-imagine-video`            |  ✓   | 1 張第一幀圖片，或最多 7 張 `reference_image`        | 1 段影片                                        | `XAI_API_KEY`                            |
 
-有些供應商接受額外或替代的 API key 環境變數。詳情請參閱個別[供應商頁面](#related)。
+部分提供者接受額外或替代的 API 金鑰環境變數。詳情請參閱個別[提供者頁面](#related)。
 
-執行 `video_generate action=list` 可在執行階段檢查可用的供應商、模型與執行階段模式。
+執行 `video_generate action=list` 可在執行階段檢視可用的提供者、模型和執行階段模式。
 
 ### 功能矩陣
 
-`video_generate`、合約測試與共享 live sweep 使用的明確模式合約：
+`video_generate`、契約測試和共享即時掃描所使用的明確模式契約：
 
-| 供應商     | `generate` | `imageToVideo` | `videoToVideo` | 目前的共享 live lanes                                                                                                                   |
+| 提供者     | `generate` | `imageToVideo` | `videoToVideo` | 今日共享即時 lanes                                                                                                                       |
 | ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Alibaba    |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；已跳過 `videoToVideo`，因為此供應商需要遠端 `http(s)` 影片 URL                                               |
+| Alibaba    |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；略過 `videoToVideo`，因為此提供者需要遠端 `http(s)` 影片 URL                                                   |
 | BytePlus   |     ✓      |       ✓        |       —        | `generate`、`imageToVideo`                                                                                                               |
-| ComfyUI    |     ✓      |       ✓        |       —        | 不在共享 sweep 中；workflow 專屬涵蓋範圍位於 Comfy 測試中                                                                                |
-| DeepInfra  |     ✓      |       —        |       —        | `generate`；原生 DeepInfra 影片 schema 在內建合約中是文字轉影片                                                                          |
-| fal        |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；僅在使用 Seedance reference-to-video 時支援 `videoToVideo`                                                   |
-| Google     |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳過，因為目前以 buffer 支援的 Gemini/Veo sweep 不接受該輸入                           |
+| ComfyUI    |     ✓      |       ✓        |       —        | 不在共享掃描中；工作流程專屬覆蓋範圍位於 Comfy 測試中                                                                                   |
+| DeepInfra  |     ✓      |       —        |       —        | `generate`；原生 DeepInfra 影片 schema 在隨附契約中是文字轉影片                                                                          |
+| fal        |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；僅在使用 Seedance 參照轉影片時支援 `videoToVideo`                                                            |
+| Google     |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；略過共享 `videoToVideo`，因為目前以緩衝區支援的 Gemini/Veo 掃描不接受該輸入                                  |
 | MiniMax    |     ✓      |       ✓        |       —        | `generate`、`imageToVideo`                                                                                                               |
-| OpenAI     |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳過，因為此組織/輸入路徑目前需要供應商端 inpaint/remix 存取權                         |
+| OpenAI     |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；略過共享 `videoToVideo`，因為此組織/輸入路徑目前需要提供者端的 inpaint/remix 存取權限                         |
 | OpenRouter |     ✓      |       ✓        |       —        | `generate`、`imageToVideo`                                                                                                               |
-| Qwen       |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；已跳過 `videoToVideo`，因為此供應商需要遠端 `http(s)` 影片 URL                                               |
-| Runway     |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；只有在所選模型為 `runway/gen4_aleph` 時才執行 `videoToVideo`                                                 |
+| Qwen       |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；略過 `videoToVideo`，因為此提供者需要遠端 `http(s)` 影片 URL                                                   |
+| Runway     |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；只有當選取的模型是 `runway/gen4_aleph` 時才執行 `videoToVideo`                                                |
 | Together   |     ✓      |       ✓        |       —        | `generate`、`imageToVideo`                                                                                                               |
-| Vydra      |     ✓      |       ✓        |       —        | `generate`；共享 `imageToVideo` 已跳過，因為內建的 `veo3` 僅支援文字，而內建的 `kling` 需要遠端圖片 URL                                  |
-| xAI        |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；已跳過 `videoToVideo`，因為此供應商目前需要遠端 MP4 URL                                                      |
+| Vydra      |     ✓      |       ✓        |       —        | `generate`；略過共享 `imageToVideo`，因為隨附的 `veo3` 僅支援文字，且隨附的 `kling` 需要遠端圖片 URL                                      |
+| xAI        |     ✓      |       ✓        |       ✓        | `generate`、`imageToVideo`；略過 `videoToVideo`，因為此提供者目前需要遠端 MP4 URL                                                         |
 
 ## 工具參數
 
 ### 必填
 
 <ParamField path="prompt" type="string" required>
-  要產生的影片文字描述。`action: "generate"` 必填。
+  要生成的影片文字描述。`action: "generate"` 必填。
 </ParamField>
 
 ### 內容輸入
 
-<ParamField path="image" type="string">單一參考圖片（路徑或 URL）。</ParamField>
-<ParamField path="images" type="string[]">多個參考圖片（最多 9 個）。</ParamField>
+<ParamField path="image" type="string">單一參考影像（路徑或 URL）。</ParamField>
+<ParamField path="images" type="string[]">多個參考影像（最多 9 個）。</ParamField>
 <ParamField path="imageRoles" type="string[]">
-可選的逐位置角色提示，與合併後的圖片清單平行對應。
+可選的逐位置角色提示，與合併後的影像清單平行對應。
 標準值：`first_frame`、`last_frame`、`reference_image`。
 </ParamField>
 <ParamField path="video" type="string">單一參考影片（路徑或 URL）。</ParamField>
@@ -156,8 +156,8 @@ openclaw tasks cancel <taskId>
 標準值：`reference_video`。
 </ParamField>
 <ParamField path="audioRef" type="string">
-單一參考音訊（路徑或 URL）。當提供者支援音訊輸入時，用於背景音樂或語音
-參考。
+單一參考音訊（路徑或 URL）。當供應商支援音訊輸入時，
+用於背景音樂或語音參考。
 </ParamField>
 <ParamField path="audioRefs" type="string[]">多個參考音訊（最多 3 個）。</ParamField>
 <ParamField path="audioRoles" type="string[]">
@@ -166,121 +166,120 @@ openclaw tasks cancel <taskId>
 </ParamField>
 
 <Note>
-角色提示會原樣轉送給提供者。標準值來自
-`VideoGenerationAssetRole` 聯集，但提供者可能接受其他
-角色字串。`*Roles` 陣列的項目數不得超過
-對應的參考清單；差一個項目的錯誤會以明確錯誤失敗。
-使用空字串可讓某個位置保持未設定。對於 xAI，請將每個圖片角色設為
-`reference_image`，以使用其 `reference_images` 生成模式；省略
-角色或使用 `first_frame` 則可進行單圖片的圖片轉影片。
+角色提示會原樣轉送給供應商。標準值來自
+`VideoGenerationAssetRole` 聯集，但供應商可能接受其他
+角色字串。`*Roles` 陣列的項目數不得超過對應的
+參考清單；差一項的錯誤會以明確錯誤失敗。
+使用空字串可讓某個位置保持未設定。對於 xAI，將每個影像角色都設為
+`reference_image` 以使用其 `reference_images` 生成模式；若要使用單影像的影像轉影片，
+請省略角色或使用 `first_frame`。
 </Note>
 
 ### 樣式控制
 
 <ParamField path="aspectRatio" type="string">
-  `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，或 `adaptive`。
+  `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` 或 `adaptive`。
 </ParamField>
-<ParamField path="resolution" type="string">`480P`、`720P`、`768P`，或 `1080P`。</ParamField>
+<ParamField path="resolution" type="string">`480P`、`720P`、`768P` 或 `1080P`。</ParamField>
 <ParamField path="durationSeconds" type="number">
-  目標時長（秒），會四捨五入到最接近的提供者支援值。
+  目標秒數長度（四捨五入到最接近的供應商支援值）。
 </ParamField>
-<ParamField path="size" type="string">提供者支援時使用的尺寸提示。</ParamField>
+<ParamField path="size" type="string">供應商支援時使用的尺寸提示。</ParamField>
 <ParamField path="audio" type="boolean">
-  在支援時啟用輸出中的生成音訊。不同於 `audioRef*`（輸入）。
+  支援時在輸出中啟用生成音訊。與 `audioRef*`（輸入）不同。
 </ParamField>
-<ParamField path="watermark" type="boolean">在支援時切換提供者浮水印。</ParamField>
+<ParamField path="watermark" type="boolean">支援時切換供應商浮水印。</ParamField>
 
-`adaptive` 是提供者專屬的哨兵值：它會原樣轉送給
-在能力中宣告 `adaptive` 的提供者（例如 BytePlus
-Seedance 會用它從輸入圖片尺寸自動偵測比例）。
-未宣告它的提供者會在工具結果中透過
-`details.ignoredOverrides` 顯示該值，讓捨棄情況可見。
+`adaptive` 是供應商特定的哨兵值：它會原樣轉送給
+在能力中宣告 `adaptive` 的供應商（例如 BytePlus
+Seedance 會用它從輸入影像尺寸自動偵測比例）。
+未宣告它的供應商會在工具結果中透過
+`details.ignoredOverrides` 顯示該值，讓忽略情況可見。
 
 ### 進階
 
 <ParamField path="action" type='"generate" | "status" | "list"' default="generate">
-  `"status"` 會回傳目前工作階段的任務；`"list"` 會檢查提供者。
+  `"status"` 會傳回目前工作階段的任務；`"list"` 會檢查供應商。
 </ParamField>
-<ParamField path="model" type="string">提供者/模型覆寫（例如 `runway/gen4.5`）。</ParamField>
+<ParamField path="model" type="string">供應商／模型覆寫（例如 `runway/gen4.5`）。</ParamField>
 <ParamField path="filename" type="string">輸出檔名提示。</ParamField>
-<ParamField path="timeoutMs" type="number">可選的提供者請求逾時時間，以毫秒為單位。</ParamField>
+<ParamField path="timeoutMs" type="number">可選的供應商請求逾時時間，以毫秒為單位。</ParamField>
 <ParamField path="providerOptions" type="object">
-  以 JSON 物件表示的提供者專屬選項（例如 `{"seed": 42, "draft": true}`）。
-  宣告型別化結構描述的提供者會驗證鍵與型別；未知
-  鍵或不相符會在後援期間略過該候選項。未
-  宣告結構描述的提供者會原樣接收選項。執行 `video_generate action=list`
-  可查看每個提供者接受的內容。
+  供應商特定選項，以 JSON 物件表示（例如 `{"seed": 42, "draft": true}`）。
+  宣告型別化結構描述的供應商會驗證鍵與型別；未知
+  鍵或不相符會在後援期間略過該候選項。沒有
+  宣告結構描述的供應商會原樣接收選項。執行 `video_generate action=list`
+  可查看每個供應商接受的內容。
 </ParamField>
 
 <Note>
-並非所有提供者都支援所有參數。OpenClaw 會將時長正規化為
-最接近的提供者支援值，並在後援提供者暴露不同
-控制介面時，重新對應已轉譯的幾何提示，
-例如尺寸轉長寬比。真正不支援的覆寫會盡力
-忽略，並在工具結果中回報為警告。硬性能力限制
-（例如參考輸入過多）會在提交前失敗。工具結果
-會回報已套用的設定；`details.normalization` 會擷取任何
-請求到套用之間的轉譯。
+並非所有供應商都支援所有參數。OpenClaw 會將時長標準化為
+最接近的供應商支援值，並在後援供應商提供不同
+控制介面時，重新對應翻譯後的幾何提示，例如尺寸轉長寬比。
+真正不支援的覆寫會盡力忽略，並在工具結果中以警告回報。
+硬性能力限制（例如參考輸入過多）會在提交前失敗。工具結果
+會回報已套用的設定；`details.normalization` 會捕捉任何
+從請求到套用的轉換。
 </Note>
 
 參考輸入會選擇執行階段模式：
 
 - 沒有參考媒體 → `generate`
-- 任一圖片參考 → `imageToVideo`
-- 任一影片參考 → `videoToVideo`
-- 參考音訊輸入**不會**改變解析後的模式；它們會套用在
-  圖片/影片參考所選模式之上，且只適用於
-  宣告 `maxInputAudios` 的提供者。
+- 任何影像參考 → `imageToVideo`
+- 任何影片參考 → `videoToVideo`
+- 參考音訊輸入**不會**改變已解析的模式；它們會套用在
+  影像／影片參考所選模式之上，且只會搭配
+  宣告 `maxInputAudios` 的供應商運作。
 
-混合圖片與影片參考不是穩定的共享能力介面。
+混合影像與影片參考不是穩定的共享能力介面。
 建議每次請求只使用一種參考類型。
 
 #### 後援與型別化選項
 
-某些能力檢查會套用在後援層，而不是
-工具邊界，因此超過主要提供者限制的請求
-仍可在具備能力的後援上執行：
+部分能力檢查會套用在後援層，而不是
+工具邊界，因此超過主要供應商限制的請求仍可
+在有能力的後援上執行：
 
-- 當請求包含音訊參考時，會略過未宣告 `maxInputAudios`（或為 `0`）
-  的作用中候選項；接著嘗試下一個候選項。
+- 當請求包含音訊參考時，未宣告 `maxInputAudios`（或為 `0`）的
+  作用中候選項會被略過；接著嘗試下一個候選項。
 - 作用中候選項的 `maxDurationSeconds` 低於請求的 `durationSeconds`，
   且未宣告 `supportedDurationSeconds` 清單 → 略過。
 - 請求包含 `providerOptions`，且作用中候選項明確
-  宣告型別化 `providerOptions` 結構描述 → 如果提供的鍵
-  不在結構描述中，或值型別不相符，則略過。未
-  宣告結構描述的提供者會原樣接收選項（向後相容
-  直通）。提供者可透過
-  宣告空結構描述（`capabilities.providerOptions: {}`）選擇退出所有提供者選項，
+  宣告型別化 `providerOptions` 結構描述 → 若提供的鍵
+  不在結構描述中，或值型別不相符，則略過。沒有
+  宣告結構描述的供應商會原樣接收選項（向後相容
+  直通）。供應商可透過宣告空結構描述
+  （`capabilities.providerOptions: {}`）選擇退出所有供應商選項，
   這會造成與型別不相符相同的略過結果。
 
-請求中的第一個略過原因會以 `warn` 記錄，讓操作人員看到
-其主要提供者何時被跳過；後續略過會以 `debug` 記錄，以
-讓長後援鏈保持安靜。如果每個候選項都被略過，
+請求中的第一個略過原因會以 `warn` 記錄，讓操作人員看見
+其主要供應商何時被跳過；後續略過會以 `debug` 記錄，以
+讓較長的後援鏈保持安靜。如果每個候選項都被略過，
 彙總錯誤會包含每個候選項的略過原因。
 
 ## 動作
 
-| 動作       | 作用                                                                                                     |
+| 動作       | 功能                                                                                                     |
 | ---------- | -------------------------------------------------------------------------------------------------------- |
-| `generate` | 預設。從指定提示和可選參考輸入建立影片。                                                               |
-| `status`   | 檢查目前工作階段中進行中的影片任務狀態，而不開始另一個生成。                                           |
-| `list`     | 顯示可用的提供者、模型及其能力。                                                                       |
+| `generate` | 預設。從給定提示和可選參考輸入建立影片。                                                               |
+| `status`   | 檢查目前工作階段中進行中影片任務的狀態，不會開始另一個生成。                                           |
+| `list`     | 顯示可用供應商、模型及其能力。                                                                          |
 
 ## 模型選擇
 
-OpenClaw 會依此順序解析模型：
+OpenClaw 會依下列順序解析模型：
 
-1. **`model` 工具參數** — 如果 agent 在呼叫中指定一個。
+1. **`model` 工具參數** — 如果代理在呼叫中指定。
 2. 設定中的 **`videoGenerationModel.primary`**。
 3. 依序使用 **`videoGenerationModel.fallbacks`**。
-4. **自動偵測** — 具備有效驗證的提供者，從
-   目前預設提供者開始，接著是依字母順序排列的剩餘
-   提供者。
+4. **自動偵測** — 具有有效驗證的供應商，從
+   目前預設供應商開始，接著是剩餘供應商的字母
+   順序。
 
-如果提供者失敗，會自動嘗試下一個候選項。如果所有
-候選項都失敗，錯誤會包含每次嘗試的詳細資料。
+如果供應商失敗，會自動嘗試下一個候選項。如果所有
+候選項都失敗，錯誤會包含每次嘗試的詳細資訊。
 
-將 `agents.defaults.mediaGenerationAutoProviderFallback: false` 設定為只使用
+設定 `agents.defaults.mediaGenerationAutoProviderFallback: false` 可只使用
 明確的 `model`、`primary` 和 `fallbacks` 項目。
 
 ```json5
@@ -296,77 +295,77 @@ OpenClaw 會依此順序解析模型：
 }
 ```
 
-## 提供者注意事項
+## 供應商注意事項
 
 <AccordionGroup>
   <Accordion title="Alibaba">
-    使用 DashScope / Model Studio 非同步端點。參考圖片與
+    使用 DashScope / Model Studio 非同步端點。參考影像和
     影片必須是遠端 `http(s)` URL。
   </Accordion>
   <Accordion title="BytePlus (1.0)">
-    提供者 ID：`byteplus`。
+    供應商 ID：`byteplus`。
 
     模型：`seedance-1-0-pro-250528`（預設）、
     `seedance-1-0-pro-t2v-250528`、`seedance-1-0-pro-fast-251015`、
     `seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。
 
-    T2V 模型（`*-t2v-*`）不接受圖片輸入；I2V 模型和
-    一般 `*-pro-*` 模型支援單一參考圖片（第一
-    幀）。可依位置傳入圖片，或設定 `role: "first_frame"`。
-    提供圖片時，T2V 模型 ID 會自動切換為對應的 I2V
+    T2V 模型（`*-t2v-*`）不接受影像輸入；I2V 模型和
+    一般 `*-pro-*` 模型支援單一參考影像（第一幀）。
+    以位置方式傳入影像，或設定 `role: "first_frame"`。
+    提供影像時，T2V 模型 ID 會自動切換到對應的 I2V
     變體。
 
-    支援的 `providerOptions` 鍵：`seed`（數字）、`draft`（布林值 —
-    強制 480p）、`camera_fixed`（布林值）。
+    支援的 `providerOptions` 鍵：`seed`（數字）、`draft`（布林 —
+    強制 480p）、`camera_fixed`（布林）。
 
   </Accordion>
   <Accordion title="BytePlus Seedance 1.5">
     需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
-    plugin。提供者 ID：`byteplus-seedance15`。模型：
+    Plugin。供應商 ID：`byteplus-seedance15`。模型：
     `seedance-1-5-pro-251215`。
 
-    使用統一的 `content[]` API。最多支援 2 張輸入圖片
+    使用統一的 `content[]` API。最多支援 2 個輸入影像
     （`first_frame` + `last_frame`）。所有輸入都必須是遠端 `https://`
-    URL。請在每張圖片上設定 `role: "first_frame"` / `"last_frame"`，或
-    依位置傳入圖片。
+    URL。在每個影像上設定 `role: "first_frame"` / `"last_frame"`，或
+    以位置方式傳入影像。
 
-    `aspectRatio: "adaptive"` 會從輸入圖片自動偵測比例。
-    `audio: true` 會對應至 `generate_audio`。`providerOptions.seed`
+    `aspectRatio: "adaptive"` 會從輸入影像自動偵測比例。
+    `audio: true` 會對應到 `generate_audio`。`providerOptions.seed`
     （數字）會被轉送。
 
   </Accordion>
   <Accordion title="BytePlus Seedance 2.0">
     需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
-    plugin。提供者 ID：`byteplus-seedance2`。模型：
+    Plugin。供應商 ID：`byteplus-seedance2`。模型：
     `dreamina-seedance-2-0-260128`、
     `dreamina-seedance-2-0-fast-260128`。
 
-    使用統一的 `content[]` API。最多支援 9 張參考圖片、
+    使用統一的 `content[]` API。最多支援 9 個參考影像、
     3 個參考影片和 3 個參考音訊。所有輸入都必須是遠端
-    `https://` URL。請在每個資產上設定 `role` — 支援的值：
+    `https://` URL。在每個資產上設定 `role` — 支援的值：
     `"first_frame"`、`"last_frame"`、`"reference_image"`、
     `"reference_video"`、`"reference_audio"`。
 
-    `aspectRatio: "adaptive"` 會從輸入圖片自動偵測比例。
-    `audio: true` 會對應至 `generate_audio`。`providerOptions.seed`
+    `aspectRatio: "adaptive"` 會從輸入影像自動偵測比例。
+    `audio: true` 會對應到 `generate_audio`。`providerOptions.seed`
     （數字）會被轉送。
 
   </Accordion>
   <Accordion title="ComfyUI">
-    由工作流程驅動的本機或雲端執行。透過設定的圖
-    支援文字轉影片與圖片轉影片。
+    工作流程驅動的本機或雲端執行。透過已設定的圖支援文字轉影片和
+    影像轉影片。
   </Accordion>
   <Accordion title="fal">
-    對長時間執行的工作使用佇列支援流程。大多數 fal 影片模型
-    接受單一圖片參考。Seedance 2.0 參考轉影片
-    模型最多接受 9 張圖片、3 個影片和 3 個音訊參考，且
-    參考檔案總數最多 12 個。
+    對長時間執行的工作使用佇列支援流程。多數 fal 影片模型
+    接受單一影像參考。Seedance 2.0 參考轉影片
+    模型最多接受 9 個影像、3 個影片和 3 個音訊參考，
+    且參考檔案總數最多為 12 個。
   </Accordion>
   <Accordion title="Google (Gemini / Veo)">
-    支援一張圖片或一個影片參考。
+    支援一個影像或一個影片參考。
   </Accordion>
   <Accordion title="MiniMax">
-    僅支援單一圖片參考。
+    僅支援單一影像參考。
   </Accordion>
   <Accordion title="OpenAI">
     只會轉送 `size` 覆寫。其他樣式覆寫
@@ -377,38 +376,35 @@ OpenClaw 會依此順序解析模型：
     使用 OpenRouter 的非同步 `/videos` API。OpenClaw 會提交
     工作、輪詢 `polling_url`，並下載 `unsigned_urls` 或
     文件化的工作內容端點。內建的 `google/veo-3.1-fast` 預設值
-    標示支援 4/6/8 秒時長、`720P`/`1080P` 解析度，以及
+    宣告 4/6/8 秒時長、`720P`/`1080P` 解析度，以及
     `16:9`/`9:16` 長寬比。
   </Accordion>
   <Accordion title="Qwen">
-    與 Alibaba 使用相同的 DashScope 後端。參考輸入必須是遠端
+    與 Alibaba 相同的 DashScope 後端。參考輸入必須是遠端
     `http(s)` URL；本機檔案會預先被拒絕。
   </Accordion>
   <Accordion title="Runway">
     透過資料 URI 支援本機檔案。影片轉影片需要
-    `runway/gen4_aleph`。純文字執行會暴露 `16:9` 和 `9:16` 長寬
-    比。
+    `runway/gen4_aleph`。純文字執行會公開 `16:9` 和 `9:16` 長寬比。
   </Accordion>
   <Accordion title="Together">
-    僅支援單一圖片參考。
+    僅支援單一影像參考。
   </Accordion>
   <Accordion title="Vydra">
-    直接使用 `https://www.vydra.ai/api/v1` 以避免驗證遭重新導向
-    丟失。`veo3` 內建為僅文字轉影片；`kling` 需要
-    遠端圖片 URL。
+    直接使用 `https://www.vydra.ai/api/v1`，以避免會丟失驗證的
+    重新導向。`veo3` 內建為僅文字轉影片；`kling` 需要
+    遠端影像 URL。
   </Accordion>
   <Accordion title="xAI">
-    支援文字轉影片、單一第一幀圖片轉影片、透過 xAI `reference_images`
-    最多 7 個 `reference_image` 輸入，以及遠端
-    影片編輯/延伸流程。
+    支援文字轉影片、單一第一幀影像轉影片、透過 xAI
+    `reference_images` 最多 7 個 `reference_image` 輸入，以及遠端
+    影片編輯／延伸流程。
   </Accordion>
 </AccordionGroup>
 
-## 提供者能力模式
+## 供應商能力模式
 
-共享影片生成合約支援模式特定功能，
-而不只是扁平的彙總限制。新的提供者實作
-應優先使用明確的模式區塊：
+共享的影片生成合約支援特定模式能力，而不只是扁平的彙總限制。新的提供者實作應優先使用明確的模式區塊：
 
 ```typescript
 capabilities: {
@@ -433,54 +429,42 @@ capabilities: {
 }
 ```
 
-扁平彙總欄位（例如 `maxInputImages` 和 `maxInputVideos`）
-**不足以** 用來宣告支援轉換模式。提供者應
-明確宣告 `generate`、`imageToVideo` 和 `videoToVideo`，讓實際服務
-測試、合約測試和共享的 `video_generate` 工具能夠以確定性方式驗證
-模式支援。
+像 `maxInputImages` 和 `maxInputVideos` 這類扁平彙總欄位，**不足以**宣告支援轉換模式。提供者應明確宣告 `generate`、`imageToVideo` 和 `videoToVideo`，讓即時測試、合約測試和共享的 `video_generate` 工具能夠以決定性的方式驗證模式支援。
 
-當提供者中的某個模型比其他模型支援更寬鬆的參考輸入時，
-請使用 `maxInputImagesByModel`、`maxInputVideosByModel` 或
-`maxInputAudiosByModel`，而不是提高整個模式的限制。
+當提供者中的某個模型比其他模型支援更寬的參照輸入時，請使用 `maxInputImagesByModel`、`maxInputVideosByModel` 或 `maxInputAudiosByModel`，而不是提高整個模式的限制。
 
-## 實際服務測試
+## 即時測試
 
-為共享的內建提供者啟用選用的實際服務涵蓋範圍：
+為共享的內建提供者選擇加入即時覆蓋範圍：
 
 ```bash
 OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
 ```
 
-Repo 包裝器：
+儲存庫包裝器：
 
 ```bash
 pnpm test:live:media video
 ```
 
-這個實際服務檔案會從 `~/.profile` 載入缺少的提供者環境變數，
-預設優先使用實際服務/環境 API 金鑰，而不是已儲存的驗證設定檔，
-並預設執行適合發行驗證的煙霧測試：
+這個即時檔案會從 `~/.profile` 載入缺少的提供者環境變數，預設優先使用即時/環境 API 金鑰，而不是已儲存的驗證設定檔，並且預設執行適合發布流程的煙霧測試：
 
-- 掃描中每個非 FAL 提供者的 `generate`。
+- 針對掃描範圍中每個非 FAL 提供者執行 `generate`。
 - 一秒鐘的龍蝦提示詞。
-- 依提供者設定的操作上限來自
-  `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（預設為 `180000`）。
+- 依提供者設定的操作上限來自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（預設為 `180000`）。
 
-FAL 是選用的，因為提供者端佇列延遲可能主導發行時間：
+FAL 是選擇加入，因為提供者端佇列延遲可能主導發布時間：
 
 ```bash
 pnpm test:live:media video --video-providers fal
 ```
 
-設定 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，也會執行
-共享掃描能以本機媒體安全測試的已宣告轉換模式：
+設定 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，也會執行共享掃描可透過本機媒體安全測試的已宣告轉換模式：
 
 - 當 `capabilities.imageToVideo.enabled` 時執行 `imageToVideo`。
-- 當 `capabilities.videoToVideo.enabled` 且提供者/模型在共享
-  掃描中接受以緩衝區支援的本機影片輸入時執行 `videoToVideo`。
+- 當 `capabilities.videoToVideo.enabled` 且提供者/模型在共享掃描中接受以緩衝區支援的本機影片輸入時，執行 `videoToVideo`。
 
-目前，共享的 `videoToVideo` 實際服務通道只會在你選擇
-`runway/gen4_aleph` 時涵蓋 `runway`。
+目前，只有在你選取 `runway/gen4_aleph` 時，共享的 `videoToVideo` 即時通道才會涵蓋 `runway`。
 
 ## 設定
 
@@ -508,7 +492,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
 ## 相關
 
 - [Alibaba Model Studio](/zh-TW/providers/alibaba)
-- [背景工作](/zh-TW/automation/tasks) — 非同步影片生成的工作追蹤
+- [背景工作](/zh-TW/automation/tasks) — 用於非同步影片生成的工作追蹤
 - [BytePlus](/zh-TW/concepts/model-providers#byteplus-international)
 - [ComfyUI](/zh-TW/providers/comfy)
 - [設定參考](/zh-TW/gateway/config-agents#agent-defaults)

docs/zh-TW/web/dashboard.md

@@ -1,18 +1,18 @@
 ---
 read_when:
     - 變更儀表板的身分驗證或公開模式
-summary: Gateway 儀表板（控制 UI）存取與身分驗證
+summary: Gateway 儀表板（控制介面）的存取與身分驗證
 title: 儀表板
 x-i18n:
-    generated_at: "2026-04-30T03:49:34Z"
+    generated_at: "2026-05-05T01:50:46Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a
+    source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1
     source_path: web/dashboard.md
     workflow: 16
 ---
 
-Gateway 儀表板是預設由 `/` 提供服務的瀏覽器控制 UI
+Gateway 儀表板是預設由 `/` 提供的瀏覽器版控制 UI
 （可用 `gateway.controlUi.basePath` 覆寫）。
 
 快速開啟（本機 Gateway）：
@@ -21,76 +21,89 @@ Gateway 儀表板是預設由 `/` 提供服務的瀏覽器控制 UI
 - 使用 `gateway.tls.enabled: true` 時，請使用 `https://127.0.0.1:18789/`，並將
   `wss://127.0.0.1:18789` 作為 WebSocket 端點。
 
-重要參考：
+主要參考：
 
-- [控制 UI](/zh-TW/web/control-ui)：了解用法與 UI 功能。
-- [Tailscale](/zh-TW/gateway/tailscale)：了解 Serve/Funnel 自動化。
-- [Web 介面](/zh-TW/web)：了解繫結模式與安全性注意事項。
+- [控制 UI](/zh-TW/web/control-ui)：使用方式與 UI 功能。
+- [Tailscale](/zh-TW/gateway/tailscale)：Serve/Funnel 自動化。
+- [Web 介面](/zh-TW/web)：綁定模式與安全性注意事項。
 
-驗證會透過已設定的 gateway 驗證路徑，在 WebSocket 握手時強制執行：
+驗證會透過已設定的 gateway
+驗證路徑，在 WebSocket 握手時強制執行：
 
 - `connect.params.auth.token`
 - `connect.params.auth.password`
-- 當 `gateway.auth.allowTailscale: true` 時，使用 Tailscale Serve 身分標頭
-- 當 `gateway.auth.mode: "trusted-proxy"` 時，使用受信任 Proxy 身分標頭
+- `gateway.auth.allowTailscale: true` 時的 Tailscale Serve 身分標頭
+- `gateway.auth.mode: "trusted-proxy"` 時的 trusted-proxy 身分標頭
 
 請參閱 [Gateway 設定](/zh-TW/gateway/configuration)中的 `gateway.auth`。
 
-安全性注意事項：控制 UI 是**管理介面**（聊天、設定、執行核准）。
-請勿將其公開暴露。UI 會將儀表板 URL 權杖保存在目前瀏覽器分頁工作階段與所選 gateway URL 的 sessionStorage 中，並在載入後從 URL 移除。
+安全性注意事項：控制 UI 是**管理介面**（聊天、設定、exec 核准）。
+請勿公開曝露。UI 會針對目前瀏覽器分頁工作階段與所選 gateway URL，將儀表板 URL token 保存在 sessionStorage，
+並在載入後從 URL 中移除它們。
 建議使用 localhost、Tailscale Serve 或 SSH 通道。
 
 ## 快速路徑（建議）
 
-- 完成 onboarding 後，CLI 會自動開啟儀表板，並列印乾淨的（不含權杖）連結。
-- 隨時重新開啟：`openclaw dashboard`（複製連結、可行時開啟瀏覽器、在 headless 時顯示 SSH 提示）。
-- 如果 UI 提示進行共用密鑰驗證，請將已設定的權杖或
-  密碼貼到控制 UI 設定中。
+- 完成 onboarding 後，CLI 會自動開啟儀表板，並印出乾淨的（未 token 化）連結。
+- 隨時重新開啟：`openclaw dashboard`（複製連結，可能時開啟瀏覽器，若為 headless 則顯示 SSH 提示）。
+- 如果剪貼簿與瀏覽器傳遞都失敗，`openclaw dashboard` 仍會印出
+  乾淨的 URL，並告訴你使用 `OPENCLAW_GATEWAY_TOKEN` 或
+  `gateway.auth.token` 中的 token 作為 URL fragment key `token`；它不會在日誌中印出 token
+  值。
+- 如果 UI 提示 shared-secret 驗證，請將已設定的 token 或
+  password 貼到控制 UI 設定中。
 
 ## 驗證基礎（本機與遠端）
 
 - **Localhost**：開啟 `http://127.0.0.1:18789/`。
 - **Gateway TLS**：當 `gateway.tls.enabled: true` 時，儀表板/狀態連結會使用
   `https://`，控制 UI WebSocket 連結會使用 `wss://`。
-- **共用密鑰權杖來源**：`gateway.auth.token`（或
-  `OPENCLAW_GATEWAY_TOKEN`）；`openclaw dashboard` 可透過 URL fragment 傳遞它以進行一次性 bootstrap，而控制 UI 會將它保存在目前瀏覽器分頁工作階段與所選 gateway URL 的 sessionStorage 中，而不是 localStorage。
+- **Shared-secret token 來源**：`gateway.auth.token`（或
+  `OPENCLAW_GATEWAY_TOKEN`）；`openclaw dashboard` 可透過 URL fragment 傳遞它
+  以進行一次性 bootstrap，而控制 UI 會針對目前瀏覽器分頁工作階段與所選 gateway URL，將其保存在 sessionStorage，
+  而不是 localStorage。
 - 如果 `gateway.auth.token` 由 SecretRef 管理，`openclaw dashboard`
-  會依設計列印/複製/開啟不含權杖的 URL。這會避免在 shell 記錄、剪貼簿歷史或瀏覽器啟動引數中暴露外部管理的權杖。
-- 如果 `gateway.auth.token` 設定為 SecretRef，且在你目前的
-  shell 中尚未解析，`openclaw dashboard` 仍會列印不含權杖的 URL，以及可執行的驗證設定指引。
-- **共用密鑰密碼**：使用已設定的 `gateway.auth.password`（或
-  `OPENCLAW_GATEWAY_PASSWORD`）。儀表板不會在重新載入之間保留密碼。
-- **帶有身分的模式**：當 `gateway.auth.allowTailscale: true` 時，Tailscale Serve 可透過身分標頭滿足控制 UI/WebSocket 驗證；非 local loopback、具身分感知能力的反向 Proxy 可滿足
-  `gateway.auth.mode: "trusted-proxy"`。在這些模式中，儀表板不需要為 WebSocket 貼上共用密鑰。
-- **非 localhost**：使用 Tailscale Serve、非 local loopback 的共用密鑰繫結、
-  非 local loopback 且具身分感知能力的反向 Proxy 搭配
-  `gateway.auth.mode: "trusted-proxy"`，或 SSH 通道。HTTP API 仍會使用
-  共用密鑰驗證，除非你有意執行私人 ingress
+  會依設計印出/複製/開啟未 token 化的 URL。這可避免將
+  外部管理的 token 暴露在 shell 日誌、剪貼簿歷史或瀏覽器啟動
+  引數中。
+- 如果 `gateway.auth.token` 設定為 SecretRef，且在你
+  目前的 shell 中未解析，`openclaw dashboard` 仍會印出未 token 化的 URL，以及
+  可執行的驗證設定指引。
+- **Shared-secret password**：使用已設定的 `gateway.auth.password`（或
+  `OPENCLAW_GATEWAY_PASSWORD`）。儀表板不會在重新載入後保留 password。
+- **帶有身分的模式**：當 `gateway.auth.allowTailscale: true` 時，Tailscale Serve 可透過身分標頭滿足控制 UI/WebSocket
+  驗證，而具備身分感知能力的非 loopback 反向代理可滿足
+  `gateway.auth.mode: "trusted-proxy"`。在這些模式中，儀表板不需要
+  貼上的 shared secret 即可使用 WebSocket。
+- **非 localhost**：使用 Tailscale Serve、非 loopback shared-secret 綁定、
+  具備身分感知能力且使用
+  `gateway.auth.mode: "trusted-proxy"` 的非 loopback 反向代理，或 SSH 通道。HTTP API 仍會使用
+  shared-secret 驗證，除非你刻意執行 private-ingress
   `gateway.auth.mode: "none"` 或 trusted-proxy HTTP 驗證。請參閱
   [Web 介面](/zh-TW/web)。
 
 <a id="if-you-see-unauthorized-1008"></a>
 
-## 如果你看到 "unauthorized" / 1008
+## 如果你看到「unauthorized」/ 1008
 
-- 確認 gateway 可以連線（本機：`openclaw status`；遠端：SSH 通道 `ssh -N -L 18789:127.0.0.1:18789 user@host`，然後開啟 `http://127.0.0.1:18789/`）。
-- 對於 `AUTH_TOKEN_MISMATCH`，當 gateway 傳回重試提示時，客戶端可使用快取的裝置權杖進行一次受信任重試。該快取權杖重試會重用此權杖快取的已核准範圍；明確的 `deviceToken` / 明確的 `scopes` 呼叫端會保留其要求的範圍集合。如果該次重試後驗證仍失敗，請手動解決權杖漂移。
-- 在該重試路徑之外，連線驗證優先順序為：明確的共用權杖/密碼優先，其次是明確的 `deviceToken`，再來是已儲存的裝置權杖，最後是 bootstrap 權杖。
-- 在非同步 Tailscale Serve 控制 UI 路徑上，同一個
-  `{scope, ip}` 的失敗嘗試會在失敗驗證限制器記錄它們之前被序列化，因此
-  第二個並行的錯誤重試可能已經顯示 `retry later`。
-- 如需權杖漂移修復步驟，請依照[權杖漂移復原檢查清單](/zh-TW/cli/devices#token-drift-recovery-checklist)。
-- 從 gateway 主機擷取或提供共用密鑰：
-  - 權杖：`openclaw config get gateway.auth.token`
-  - 密碼：解析已設定的 `gateway.auth.password` 或
+- 確認 gateway 可連線（本機：`openclaw status`；遠端：SSH 通道 `ssh -N -L 18789:127.0.0.1:18789 user@host`，然後開啟 `http://127.0.0.1:18789/`）。
+- 對於 `AUTH_TOKEN_MISMATCH`，當 gateway 回傳重試提示時，client 可以使用快取的裝置 token 進行一次受信任重試。該快取 token 重試會重用 token 的快取已核准 scope；明確 `deviceToken` / 明確 `scopes` 的呼叫者會保留其請求的 scope 集合。如果該次重試後驗證仍失敗，請手動解決 token 漂移。
+- 在該重試路徑之外，連線驗證優先順序為先使用明確 shared token/password，接著是明確 `deviceToken`，再來是已儲存的裝置 token，最後是 bootstrap token。
+- 在非同步 Tailscale Serve 控制 UI 路徑上，相同
+  `{scope, ip}` 的失敗嘗試會在 failed-auth limiter 記錄之前被序列化，因此
+  第二個並行的不良重試可能已經顯示 `retry later`。
+- 如需 token 漂移修復步驟，請依照 [Token 漂移復原檢查清單](/zh-TW/cli/devices#token-drift-recovery-checklist)。
+- 從 gateway 主機擷取或提供 shared secret：
+  - Token：`openclaw config get gateway.auth.token`
+  - Password：解析已設定的 `gateway.auth.password` 或
     `OPENCLAW_GATEWAY_PASSWORD`
-  - SecretRef 管理的權杖：解析外部密鑰提供者，或在此 shell 中匯出
+  - SecretRef 管理的 token：解析外部 secret provider，或在此 shell 中匯出
     `OPENCLAW_GATEWAY_TOKEN`，然後重新執行 `openclaw dashboard`
-  - 未設定共用密鑰：`openclaw doctor --generate-gateway-token`
-- 在儀表板設定中，將權杖或密碼貼到驗證欄位，
+  - 未設定 shared secret：`openclaw doctor --generate-gateway-token`
+- 在儀表板設定中，將 token 或 password 貼到驗證欄位，
   然後連線。
 - UI 語言選擇器位於 **Overview -> Gateway Access -> Language**。
-  它是存取卡的一部分，不在 Appearance 區段中。
+  它是存取卡片的一部分，不是 Appearance 區段。
 
 ## 相關