diff --git a/docs/zh-TW/automation/tasks.md b/docs/zh-TW/automation/tasks.md index e988db27a..ca31de446 100644 --- a/docs/zh-TW/automation/tasks.md +++ b/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 --- -正在尋找排程功能？請參閱[自動化與任務](/zh-TW/automation)以選擇合適的機制。此頁面是背景工作的活動帳本，而不是排程器。 +正在尋找排程？請參閱[自動化與任務](/zh-TW/automation)，以選擇正確的機制。本頁是背景工作的活動帳本，不是排程器。 -背景任務會追蹤在**主要對話工作階段之外**執行的工作：ACP 執行、子代理產生、隔離的 cron 作業執行，以及由 CLI 啟動的操作。 +背景任務會追蹤在**主要對話工作階段之外**執行的工作：ACP 執行、子代理產生、隔離的 cron 工作執行，以及由 CLI 啟動的操作。 -任務**不會**取代工作階段、cron 作業或 Heartbeat —— 它們是**活動帳本**，用來記錄發生了哪些分離式工作、發生時間，以及是否成功。 +任務**不會**取代工作階段、cron 工作或 heartbeats — 它們是**活動帳本**，記錄發生了哪些分離式工作、何時發生，以及是否成功。 -不是每次代理執行都會建立任務。Heartbeat 回合與一般互動式聊天不會。所有 cron 執行、ACP 產生、子代理產生，以及 CLI 代理命令都會建立任務。 +並非每次代理執行都會建立任務。Heartbeat 回合和一般互動式聊天不會。所有 cron 執行、ACP 產生、子代理產生，以及 CLI 代理命令都會。 -## 簡短摘要 +## 太長；沒讀 -- 任務是**記錄**，不是排程器 —— 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 天，然後自動清除。 ## 快速開始 - + ```bash # List all tasks (newest first) openclaw tasks list @@ -57,13 +58,13 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -73,7 +74,7 @@ x-i18n: ``` - + ```bash # Run a health audit openclaw tasks audit @@ -84,7 +85,7 @@ x-i18n: ``` - + ```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` | - - 主要工作階段 cron 任務預設使用 `silent` 通知政策 —— 它們會建立記錄以供追蹤，但不會產生通知。隔離的 cron 任務也預設為 `silent`，但因為它們在自己的工作階段中執行，所以更容易被看到。 + + 主要工作階段 cron 任務預設使用 `silent` 通知政策 — 它們會建立用於追蹤的記錄，但不會產生通知。隔離的 cron 任務也預設為 `silent`，但因為它們在自己的工作階段中執行，所以更容易被看見。 - 由工作階段支援的 `music_generate` 與 `video_generate` 執行也使用 `silent` 通知政策。它們仍會建立任務記錄，但完成結果會作為內部喚醒交回原始代理工作階段，讓代理可以自行寫入後續訊息並附上完成的媒體。如果你選擇啟用 `tools.media.asyncCompletion.directSend`，非同步 `video_generate` 完成可以先嘗試直接傳遞到頻道；非同步 `music_generate` 完成則維持在請求者工作階段喚醒路徑上。 + 由工作階段支援的 `music_generate` 和 `video_generate` 執行也使用 `silent` 通知政策。它們仍會建立任務記錄，但完成會以內部喚醒的形式交回原始代理工作階段，讓代理能寫出後續訊息並自行附加完成的媒體。群組/頻道完成會遵循一般的可見回覆政策，因此當來源傳遞需要時，代理會使用訊息工具。 - - 當由工作階段支援的 `video_generate` 任務仍處於作用中時，該工具也會充當防護：同一工作階段中重複的 `video_generate` 呼叫會回傳作用中任務狀態，而不是啟動第二個並行產生。當你想從代理端明確查詢進度/狀態時，請使用 `action: "status"`。 + + 當由工作階段支援的 `video_generate` 任務仍在活動時，該工具也會作為護欄：同一工作階段中重複的 `video_generate` 呼叫會回傳作用中任務狀態，而不是開始第二個並行生成。當你想從代理端明確查詢進度/狀態時，請使用 `action: "status"`。 - - - Heartbeat 回合 —— 主要工作階段；請參閱 [Heartbeat](/zh-TW/gateway/heartbeat) + + - 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 出現。 -任務完成會觸發立即 Heartbeat 喚醒，讓你能快速看到結果 —— 你不必等待下一個排定的 Heartbeat tick。 +任務完成會觸發立即的 heartbeat 喚醒，讓你很快看到結果 — 你不必等到下一個排程 heartbeat tick。 -這表示一般工作流程是以推送為基礎：啟動一次分離式工作，然後讓執行階段在完成時喚醒或通知你。只有在需要偵錯、介入或明確稽核時，才輪詢任務狀態。 +這表示一般工作流程是推送式的：啟動一次分離式工作，然後讓 runtime 在完成時喚醒或通知你。只有在需要除錯、介入或明確 audit 時，才輪詢任務狀態。 ### 通知政策 -控制你會收到每個任務多少資訊： +控制你會收到多少關於每個任務的通知： | 政策 | 傳遞內容 | | --------------------- | ----------------------------------------------------------------------- | -| `done_only`（預設） | 只有終端狀態（succeeded、failed 等）—— **這是預設值** | -| `state_changes` | 每次狀態轉換與進度更新 | +| `done_only`（預設） | 只有終端狀態（succeeded、failed 等）— **這是預設值** | +| `state_changes` | 每次狀態轉換和進度更新 | | `silent` | 完全不傳遞 | -在任務執行期間變更政策： +在任務執行中變更政策： ```bash openclaw tasks notify state_changes @@ -209,7 +210,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - 查詢權杖接受任務 ID、執行 ID 或工作階段鍵。顯示完整記錄，包括時間、傳遞狀態、錯誤與終端摘要。 + 查詢權杖接受任務 ID、執行 ID 或工作階段鍵。顯示完整記錄，包括時間、傳遞狀態、錯誤和終端摘要。 @@ -217,7 +218,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - 對 ACP 與子代理任務，這會終止子工作階段。對 CLI 追蹤的任務，取消會記錄在任務登錄檔中（沒有獨立的子執行階段控制代碼）。狀態會轉換為 `cancelled`，並在適用時傳送傳遞通知。 + 對於 ACP 和子代理任務，這會終止子工作階段。對於由 CLI 追蹤的任務，取消會記錄在任務登錄中（沒有單獨的子 runtime 控制代碼）。狀態會轉換為 `cancelled`，並在適用時傳送傳遞通知。 @@ -230,16 +231,16 @@ openclaw tasks notify 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` | 警告 | 時間軸違規（例如結束早於開始） | @@ -248,21 +249,21 @@ openclaw tasks notify 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 文字，而且只有逾時的工具呼叫執行可收斂成簡短的部分進度摘要。終止失敗的執行會公告失敗狀態，而不重播擷取的回覆文字。 - 清理失敗不會遮蔽真正的任務結果。 @@ -273,18 +274,18 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - 當你關心的是編排中的 Task Flow，而不是單一背景任務記錄時，請使用這些指令。 + 當你關心的是負責協調的任務流程，而不是單一背景任務記錄時，請使用這些命令。 ## 聊天任務看板 (`/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 秒** 執行一次，並處理四件事： - - 檢查作用中任務是否仍有權威 runtime backing。ACP/subagent 任務使用 child-session 狀態，cron 任務使用 active-job 擁有權，而由聊天支援的 CLI 任務使用所屬的 run context。如果該 backing 狀態消失超過 5 分鐘，任務會標記為 `lost`。 + + 檢查作用中任務是否仍有權威的執行階段支援。ACP/子代理任務使用子工作階段狀態，cron 任務使用作用中工作所有權，而由聊天支援的 CLI 任務使用擁有它的執行上下文。如果該支援狀態消失超過 5 分鐘，任務會被標記為 `lost`。 - - 關閉已終止或孤立、由父層擁有的一次性 ACP session；並且只有在沒有剩餘作用中的 conversation binding 時，才關閉過時的終端或孤立持久 ACP session。 + + 關閉已終止或孤立的父層擁有一次性 ACP 工作階段；只有在沒有作用中的對話繫結留下時，才會關閉過期終止或孤立的持久 ACP 工作階段。 - 在終端任務上設定 `cleanupAfter` 時間戳記（endedAt + 7 天）。在保留期間，遺失任務仍會在稽核中以警告顯示；在 `cleanupAfter` 到期後，或清理 metadata 遺失時，它們會成為錯誤。 + 在終止任務上設定 `cleanupAfter` 時間戳（endedAt + 7 天）。在保留期間，遺失任務仍會以警告形式出現在稽核中；`cleanupAfter` 過期後，或清理中繼資料缺失時，它們會成為錯誤。 刪除超過其 `cleanupAfter` 日期的記錄。 @@ -335,42 +336,42 @@ sweeper 每 **60 秒** 執行一次，並處理四件事： -**保留：** 終端任務記錄會保留 **7 天**，然後自動剪除。不需要設定。 +**保留：**終止任務記錄會保留 **7 天**，然後自動剪除。不需要設定。 -## 任務與其他系統的關係 +## 任務如何與其他系統相關 - - [Task Flow](/zh-TW/automation/taskflow) 是背景任務上方的流程編排層。單一 flow 可以在其生命週期中使用受管理或鏡像的同步模式來協調多個任務。使用 `openclaw tasks` 檢查個別任務記錄，並使用 `openclaw tasks flow` 檢查編排中的 flow。 + + [任務流程](/zh-TW/automation/taskflow) 是背景任務之上的流程協調層。單一流程可在其生命週期內使用受管或鏡像同步模式協調多個任務。使用 `openclaw tasks` 檢查個別任務記錄，並使用 `openclaw tasks flow` 檢查負責協調的流程。 - 詳情請參閱 [Task Flow](/zh-TW/automation/taskflow)。 + 詳情請參閱[任務流程](/zh-TW/automation/taskflow)。 - 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)。 - Heartbeat 執行是 main-session turn，不會建立任務記錄。當任務完成時，可以觸發 heartbeat 喚醒，讓你能立即看到結果。 + Heartbeat 執行是主工作階段回合，它們不會建立任務記錄。任務完成時，可以觸發 Heartbeat 喚醒，讓你能立即看到結果。 請參閱 [Heartbeat](/zh-TW/gateway/heartbeat)。 - - 任務可以參照 `childSessionKey`（工作執行的位置）和 `requesterSessionKey`（啟動它的人）。Session 是對話情境；任務則是在其上方進行活動追蹤。 + + 任務可以參照 `childSessionKey`（工作執行的位置）與 `requesterSessionKey`（啟動它的人）。工作階段是對話上下文；任務則是在其上的活動追蹤。 - - 任務的 `runId` 會連結到正在執行工作的 agent run。Agent 生命週期事件（開始、結束、錯誤）會自動更新任務狀態，你不需要手動管理生命週期。 + + 任務的 `runId` 會連結到正在執行工作的代理執行。代理生命週期事件（開始、結束、錯誤）會自動更新任務狀態，你不需要手動管理生命週期。 ## 相關 - [自動化與任務](/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) — 任務之上的流程協調 diff --git a/docs/zh-TW/channels/slack.md b/docs/zh-TW/channels/slack.md index 4cfda53c3..1d0615f16 100644 --- a/docs/zh-TW/channels/slack.md +++ b/docs/zh-TW/channels/slack.md @@ -1,43 +1,200 @@ --- read_when: - 設定 Slack 或偵錯 Slack 通訊端/HTTP 模式 -summary: Slack 設定與執行階段行為（Socket 模式 + HTTP 請求 URL） +summary: Slack 設定與執行階段行為（Socket Mode + HTTP 請求 URL） title: Slack x-i18n: - generated_at: "2026-05-04T07:02:49Z" + generated_at: "2026-05-05T01:44:12Z" model: gpt-5.5 provider: openai - source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 + source_hash: 9a8e1cbfd3d99bfc24d79b56ee762d1ab399402391b241ff40698249b0828008 source_path: channels/slack.md workflow: 16 --- -可透過 Slack app 整合在 DM 和頻道中用於生產環境。預設模式為 Socket Mode；也支援 HTTP Request URLs。 +透過 Slack 應用程式整合，已可投入生產環境用於私訊和頻道。預設模式為 Socket 模式；也支援 HTTP 請求 URL。 - Slack DM 預設使用配對模式。 + Slack 私訊預設使用配對模式。 - 原生命令行為與命令目錄。 + 原生指令行為與指令目錄。 - 跨頻道診斷與修復教戰手冊。 + 跨頻道診斷與修復手冊。 +## 選擇 Socket 模式或 HTTP 請求 URL + +兩種傳輸方式皆可投入生產環境，並在訊息、斜線指令、應用程式首頁和互動性上達到功能等價。請依部署型態選擇，而不是依功能選擇。 + +| 考量 | Socket 模式（預設） | HTTP 請求 URL | +| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| 公開 Gateway URL | 不需要 | 需要（DNS、TLS、反向代理或通道） | +| 對外網路 | 必須可對外連線至 `wss-primary.slack.com` 的 WSS | 沒有對外 WS；僅需入站 HTTPS | +| 所需權杖 | 機器人權杖 (`xoxb-...`) + 應用層級權杖 (`xapp-...`)，並具備 `connections:write` | 機器人權杖 (`xoxb-...`) + 簽署祕密 | +| 開發筆電／防火牆後方 | 可直接使用 | 需要公開通道（ngrok、Cloudflare Tunnel、Tailscale Funnel）或預備環境 Gateway | +| 水平擴充 | 每個應用程式在每台主機上只能有一個 Socket 模式工作階段；多個 Gateway 需要個別的 Slack 應用程式 | 無狀態 POST 處理常式；多個 Gateway 複本可在負載平衡器後方共用一個應用程式 | +| 單一 Gateway 上的多帳號 | 支援；每個帳號會開啟自己的 WS | 支援；每個帳號都需要唯一的 `webhookPath`（預設 `/slack/events`），讓註冊不會衝突 | +| 斜線指令傳輸 | 透過 WS 連線傳遞；`slash_commands[].url` 會被忽略 | Slack 會 POST 到 `slash_commands[].url`；此欄位是派發指令的必要欄位 | +| 請求簽署 | 不使用（驗證使用應用層級權杖） | Slack 會簽署每個請求；OpenClaw 會使用 `signingSecret` 驗證 | +| 連線中斷時的復原 | Slack SDK 會自動重新連線；套用 Gateway 的 pong-timeout 傳輸調校 | 沒有會中斷的持久連線；重試由 Slack 依每個請求執行 | + + + **選擇 Socket 模式**，適用於單一 Gateway 主機、開發筆電，以及可對外連至 `*.slack.com` 但無法接受入站 HTTPS 的內部部署網路。 + +**選擇 HTTP 請求 URL**，適用於在負載平衡器後方執行多個 Gateway 複本、對外 WSS 遭封鎖但允許入站 HTTPS，或你已在反向代理終止 Slack Webhook 的情境。 + + ## 快速設定 - + - - 在 Slack app 設定中按下 **[Create New App](https://api.slack.com/apps/new)** 按鈕： + + 開啟 [api.slack.com/apps](https://api.slack.com/apps/new) → **建立新應用程式** → **從資訊清單** → 選取你的工作區 → 貼上下列其中一份資訊清單 → **下一步** → **建立**。 - - 選擇 **from a manifest**，並為你的 app 選取工作區 - - 貼上下面的[範例 manifest](#manifest-and-scope-checklist)，並繼續建立 - - 產生具有 `connections:write` 的 **App-Level Token**（`xapp-...`） - - 安裝 app，並複製顯示的 **Bot Token**（`xoxb-...`） + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + } + } +} +``` + + + + + **建議**符合內建 Slack Plugin 的完整功能集：應用程式首頁、斜線指令、檔案、反應、釘選、群組私訊，以及表情符號/使用者群組讀取。當工作區政策限制權限範圍時，請選擇 **最小**：它涵蓋私訊、頻道/群組記錄、提及和斜線指令，但不包含檔案、反應、釘選、群組私訊 (`mpim:*`)、`emoji:read` 和 `usergroups:read`。請參閱[資訊清單與權限範圍檢查清單](#manifest-and-scope-checklist)，了解各權限範圍的理由，以及額外斜線指令等可加選項。 + + + Slack 建立應用程式後： + + - **基本資訊 → 應用層級權杖 → 產生權杖和權限範圍**：新增 `connections:write`、儲存，然後複製 `xapp-...` 值。 + - **安裝應用程式 → 安裝到工作區**：複製 `xoxb-...` 機器人使用者 OAuth 權杖。 @@ -64,7 +221,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - 環境變數備援（僅預設帳號）： + 環境變數後備（僅限預設帳號）： ```bash SLACK_APP_TOKEN=xapp-... @@ -84,19 +241,170 @@ openclaw gateway - + - - 在 Slack app 設定中按下 **[Create New App](https://api.slack.com/apps/new)** 按鈕： + + 開啟 [api.slack.com/apps](https://api.slack.com/apps/new) → **建立新應用程式** → **從資訊清單** → 選取你的工作區 → 貼上下列其中一份資訊清單 → 將 `https://gateway-host.example.com/slack/events` 替換為你的公開 Gateway URL → **下一步** → **建立**。 - - 選擇 **from a manifest**，並為你的 app 選取工作區 - - 貼上[範例 manifest](#manifest-and-scope-checklist)，並在建立前更新 URL - - 儲存用於請求驗證的 **Signing Secret** - - 安裝 app，並複製顯示的 **Bot Token**（`xoxb-...`） + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + **建議** 會符合內建 Slack Plugin 的完整功能集；**最小** 會移除檔案、反應、釘選、群組 DM（`mpim:*`）、`emoji:read` 與 `usergroups:read`，適用於限制較嚴格的工作區。請參閱[資訊清單與範圍檢查清單](#manifest-and-scope-checklist)，了解各範圍的理由。 + + + + 三個 URL 欄位（`slash_commands[].url`、`event_subscriptions.request_url`，以及 `interactivity.request_url` / `message_menu_options_url`）都指向同一個 OpenClaw 端點。Slack 的資訊清單結構描述要求它們分別命名，但 OpenClaw 會依照承載資料類型路由，因此單一 `webhookPath`（預設 `/slack/events`）就足夠。未設定 `slash_commands[].url` 的斜線指令會在 HTTP 模式中靜默無作用。 + + + Slack 建立應用程式後： + + - **Basic Information → App Credentials**：複製 **Signing Secret** 以進行請求驗證。 + - **Install App → Install to Workspace**：複製 `xoxb-...` Bot User OAuth Token。 - + 建議的 SecretRef 設定： @@ -121,14 +429,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - 為多帳號 HTTP 使用唯一的 webhook 路徑 + 為多帳號 HTTP 使用唯一的 Webhook 路徑 - 為每個帳號指定不同的 `webhookPath`（預設為 `/slack/events`），避免註冊發生衝突。 + 為每個帳號指定不同的 `webhookPath`（預設 `/slack/events`），使註冊不會發生衝突。 - + ```bash openclaw gateway @@ -159,13 +467,13 @@ OpenClaw 預設會將 Socket Mode 的 Slack SDK 用戶端 pong 逾時設為 15 } ``` -僅在記錄 Slack websocket pong/server-ping 逾時，或執行於已知有事件迴圈飢餓問題主機的 Socket Mode 工作區使用此設定。`clientPingTimeout` 是 SDK 傳送用戶端 ping 後等待 pong 的時間；`serverPingTimeout` 是等待 Slack 伺服器 ping 的時間。App 訊息和事件仍是應用程式狀態，而不是傳輸存活性訊號。 +只在記錄到 Slack websocket pong/server-ping 逾時，或執行在已知事件迴圈飢餓主機上的 Socket Mode 工作區使用此設定。`clientPingTimeout` 是 SDK 傳送用戶端 ping 後等待 pong 的時間；`serverPingTimeout` 是等待 Slack 伺服器 ping 的時間。應用程式訊息與事件仍是應用程式狀態，而不是傳輸存活訊號。 -## Manifest 與 scope 檢查清單 +## 資訊清單與範圍檢查清單 -Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只有 `settings` 區塊（以及斜線指令的 `url`）不同。 +基礎 Slack 應用程式資訊清單對 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 區塊（以及斜線指令 `url`）不同。 -基礎 manifest（Socket Mode 預設）： +基礎資訊清單（Socket Mode 預設）： ```json { @@ -240,7 +548,7 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只 } ``` -若使用 **HTTP Request URLs 模式**，請將 `settings` 替換為 HTTP 版本，並在每個斜線指令新增 `url`。需要公開 URL： +若使用 **HTTP Request URLs 模式**，請將 `settings` 替換為 HTTP 變體，並為每個斜線指令新增 `url`。需要公開 URL： ```json { @@ -282,24 +590,24 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只 } ``` -### 其他 manifest 設定 +### 其他資訊清單設定 -顯示可擴充上述預設值的不同功能。 +呈現擴充上述預設值的不同功能。 -預設 manifest 會啟用 Slack App Home 的 **Home** 分頁，並訂閱 `app_home_opened`。當工作區成員開啟 Home 分頁時，OpenClaw 會使用 `views.publish` 發布安全的預設 Home 檢視；其中不包含對話承載資料或私人設定。Slack DM 仍會啟用 **Messages** 分頁。 +預設資訊清單會啟用 Slack App Home 的 **Home** 分頁，並訂閱 `app_home_opened`。當工作區成員開啟 Home 分頁時，OpenClaw 會透過 `views.publish` 發布安全的預設 Home 檢視；不會包含對話承載資料或私人設定。**Messages** 分頁仍會為 Slack DM 啟用。 - + - 可使用多個[原生斜線指令](#commands-and-slash-behavior)取代單一設定命令，但需注意細節： + 可使用多個[原生斜線指令](#commands-and-slash-behavior)取代單一已設定指令，並保留細節差異： - - 使用 `/agentstatus` 而不是 `/status`，因為 `/status` 命令已被保留。 - - 一次最多可提供 25 個斜線指令。 + - 使用 `/agentstatus` 而非 `/status`，因為 `/status` 指令已保留。 + - 一次最多只能提供 25 個斜線指令。 - 將現有的 `features.slash_commands` 區段替換為[可用命令](/zh-TW/tools/slash-commands#command-list)的子集： + 將現有的 `features.slash_commands` 區段替換為[可用指令](/zh-TW/tools/slash-commands#command-list)的子集： - + ```json { @@ -423,7 +731,7 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只 - 使用上方與 Socket Mode 相同的 `slash_commands` 清單，並在每個項目新增 `"url": "https://gateway-host.example.com/slack/events"`。範例： + 使用與上方 Socket Mode 相同的 `slash_commands` 清單，並在每個項目加入 `"url": "https://gateway-host.example.com/slack/events"`。範例： ```json { @@ -443,20 +751,20 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只 } ``` - 在清單中的每個命令重複使用該 `url` 值。 + 對清單中的每個指令重複該 `url` 值。 - 如果你希望傳出訊息使用作用中的代理身分（自訂使用者名稱和圖示），而不是預設的 Slack 應用程式身分，請新增 `chat:write.customize` 機器人範圍。 + 如果你希望傳出訊息使用作用中的代理身分（自訂使用者名稱和圖示），而不是預設的 Slack 應用程式身分，請加入 `chat:write.customize` 機器人範圍。 - 如果使用表情符號圖示，Slack 會要求使用 `:emoji_name:` 語法。 + 如果你使用表情符號圖示，Slack 預期使用 `:emoji_name:` 語法。 - 如果你設定 `channels.slack.userToken`，典型的讀取範圍為： + 如果你設定 `channels.slack.userToken`，典型讀取範圍為： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -475,9 +783,9 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只 - HTTP 模式需要 `botToken` + `signingSecret`。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受純文字 字串或 SecretRef 物件。 -- 設定權杖會覆寫 env 備援。 -- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env 備援只套用於預設帳戶。 -- `userToken` (`xoxp-...`) 僅能透過設定提供（沒有 env 備援），並預設為唯讀行為 (`userTokenReadOnly: true`)。 +- 設定權杖會覆寫環境變數後援。 +- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 環境變數後援只套用於預設帳戶。 +- `userToken`（`xoxp-...`）僅能透過設定提供（沒有環境變數後援），且預設為唯讀行為（`userTokenReadOnly: true`）。 狀態快照行為： @@ -485,30 +793,30 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只 欄位（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - 狀態為 `available`、`configured_unavailable` 或 `missing`。 - `configured_unavailable` 表示帳戶是透過 SecretRef - 或另一個非內嵌祕密來源設定，但目前的命令/執行階段路徑 + 或其他非內嵌祕密來源設定，但目前的命令/執行階段路徑 無法解析實際值。 - 在 HTTP 模式中會包含 `signingSecretStatus`；在 Socket Mode 中， 必要配對是 `botTokenStatus` + `appTokenStatus`。 -對於動作/目錄讀取，設定後可以優先使用使用者權杖。對於寫入，仍會優先使用機器人權杖；只有在 `userTokenReadOnly: false` 且機器人權杖不可用時，才允許使用者權杖寫入。 +對於動作/目錄讀取，已設定時可優先使用使用者權杖。對於寫入，仍優先使用機器人權杖；只有在 `userTokenReadOnly: false` 且機器人權杖不可用時，才允許使用使用者權杖寫入。 -## 動作與閘門 +## 動作和閘門 Slack 動作由 `channels.slack.actions.*` 控制。 目前 Slack 工具中可用的動作群組： | 群組 | 預設 | -| ---------- | ---- | -| messages | 啟用 | -| reactions | 啟用 | -| pins | 啟用 | -| memberInfo | 啟用 | -| emojiList | 啟用 | +| ---------- | ------- | +| messages | 已啟用 | +| reactions | 已啟用 | +| pins | 已啟用 | +| memberInfo | 已啟用 | +| emojiList | 已啟用 | -目前 Slack 訊息動作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受傳入檔案預留位置中顯示的 Slack 檔案 ID，並會對圖片傳回圖片預覽，或對其他檔案類型傳回本機檔案中繼資料。 +目前 Slack 訊息動作包含 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受傳入檔案預留位置中顯示的 Slack 檔案 ID，並針對圖片傳回圖片預覽，或針對其他檔案類型傳回本機檔案中繼資料。 ## 存取控制與路由 @@ -518,7 +826,7 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - `pairing`（預設） - `allowlist` - - `open`（要求 `channels.slack.allowFrom` 包含 `"*"`） + - `open`（需要 `channels.slack.allowFrom` 包含 `"*"`） - `disabled` DM 旗標： @@ -535,7 +843,7 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - 具名帳戶在自己的 `allowFrom` 未設定時，會繼承 `channels.slack.allowFrom`。 - 具名帳戶不會繼承 `channels.slack.accounts.default.allowFrom`。 - 舊版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍會讀取以維持相容性。`openclaw doctor --fix` 會在不變更存取權的情況下，將它們遷移到 `dmPolicy` 和 `allowFrom`。 + 舊版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍會為了相容性而讀取。`openclaw doctor --fix` 會在不變更存取權的情況下，將它們遷移到 `dmPolicy` 和 `allowFrom`。 DM 中的配對使用 `openclaw pairing approve slack `。 @@ -548,20 +856,20 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - `allowlist` - `disabled` - 頻道允許清單位於 `channels.slack.channels` 底下，且**必須使用穩定的 Slack 頻道 ID**（例如 `C12345678`）作為設定鍵。 + 頻道允許清單位於 `channels.slack.channels` 底下，且 **必須使用穩定的 Slack 頻道 ID**（例如 `C12345678`）作為設定鍵。 - 執行階段注意事項：如果完全缺少 `channels.slack`（僅 env 設定），執行階段會退回到 `groupPolicy="allowlist"` 並記錄警告（即使已設定 `channels.defaults.groupPolicy`）。 + 執行階段注意事項：如果完全缺少 `channels.slack`（僅環境變數設定），執行階段會退回到 `groupPolicy="allowlist"` 並記錄警告（即使已設定 `channels.defaults.groupPolicy` 也是如此）。 名稱/ID 解析： - - 當權杖存取允許時，會在啟動時解析頻道允許清單項目和 DM 允許清單項目 - - 未解析的頻道名稱項目會保留原設定，但預設會在路由時忽略 - - 傳入授權和頻道路由預設以 ID 優先；直接使用者名稱/slug 比對需要 `channels.slack.dangerouslyAllowNameMatching: true` + - 頻道允許清單項目和 DM 允許清單項目會在啟動時於權杖存取允許的情況下解析 + - 未解析的頻道名稱項目會保留為已設定狀態，但預設會被路由忽略 + - 傳入授權和頻道路由預設優先使用 ID；直接使用者名稱/slug 比對需要 `channels.slack.dangerouslyAllowNameMatching: true` - 以名稱為基礎的鍵（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不會**符合。頻道查找預設以 ID 優先，因此以名稱為基礎的鍵永遠無法成功路由，該頻道中的所有訊息都會被靜默封鎖。這與 `groupPolicy: "open"` 不同，後者不需要頻道鍵即可路由，因此以名稱為基礎的鍵看起來會生效。 + 以名稱為基礎的鍵（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不會**相符。頻道查詢預設優先使用 ID，因此以名稱為基礎的鍵永遠無法成功路由，且該頻道中的所有訊息都會被靜默封鎖。這不同於 `groupPolicy: "open"`；在該模式下，路由不需要頻道鍵，且以名稱為基礎的鍵看起來可以運作。 - 請一律使用 Slack 頻道 ID 作為鍵。查找方式：在 Slack 中以滑鼠右鍵點選頻道 → **複製連結** — ID (`C...`) 會出現在 URL 末尾。 + 一律使用 Slack 頻道 ID 作為鍵。尋找方式：在 Slack 中以右鍵點選頻道 → **複製連結** — ID（`C...`）會出現在 URL 末端。 正確： @@ -596,17 +904,17 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - - 頻道訊息預設會受到提及門檻控管。 + + 頻道訊息預設會受到提及門檻限制。 提及來源： - 明確的應用程式提及（`<@botId>`） - - Slack 使用者群組提及（``），當 Bot 使用者是該使用者群組成員時適用；需要 `usergroups:read` - - 提及 regex 模式（`agents.list[].groupChat.mentionPatterns`，後援為 `messages.groupChat.mentionPatterns`） - - 隱含的回覆 Bot 執行緒行為（當 `thread.requireExplicitMention` 為 `true` 時停用） + - Slack 使用者群組提及（``），前提是機器人使用者是該使用者群組的成員；需要 `usergroups:read` + - 提及正規表示式模式（`agents.list[].groupChat.mentionPatterns`，備援為 `messages.groupChat.mentionPatterns`） + - 隱含的回覆機器人執行緒行為（當 `thread.requireExplicitMention` 為 `true` 時停用） - 各頻道控制項（`channels.slack.channels.`；名稱只能透過啟動時解析或 `dangerouslyAllowNameMatching` 使用）： + 每個頻道的控制項（`channels.slack.channels.`；名稱只能透過啟動時解析或 `dangerouslyAllowNameMatching` 使用）： - `requireMention` - `users`（允許清單） @@ -614,30 +922,30 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - `toolsBySender` 鍵格式：`id:`, `e164:`, `username:`, `name:` 或 `"*"` 萬用字元 - （舊版無前綴鍵仍只會對應至 `id:`） + - `toolsBySender` 鍵格式：`id:`, `e164:`, `username:`, `name:`，或 `"*"` 萬用字元 + （舊版未加前綴的鍵仍只會對應到 `id:`） - `allowBots` 對頻道和私人頻道採保守策略：Bot 撰寫的聊天室訊息只有在傳送該訊息的 Bot 明確列在該聊天室的 `users` 允許清單中，或 `channels.slack.allowFrom` 中至少有一個明確 Slack 擁有者 ID 目前是聊天室成員時，才會被接受。萬用字元和顯示名稱擁有者項目不符合擁有者存在條件。擁有者存在檢查使用 Slack `conversations.members`；請確認應用程式具有該聊天室類型對應的讀取範圍（公開頻道為 `channels:read`，私人頻道為 `groups:read`）。如果成員查詢失敗，OpenClaw 會丟棄 Bot 撰寫的聊天室訊息。 + `allowBots` 對頻道與私人頻道採保守策略：只有在發送訊息的機器人明確列在該聊天室的 `users` 允許清單中，或 `channels.slack.allowFrom` 中至少有一個明確的 Slack 擁有者 ID 目前是聊天室成員時，才會接受由機器人撰寫的聊天室訊息。萬用字元與顯示名稱形式的擁有者項目不符合擁有者在場條件。擁有者在場檢查使用 Slack `conversations.members`；請確認應用程式具備符合聊天室類型的讀取範圍（公開頻道為 `channels:read`，私人頻道為 `groups:read`）。如果成員查詢失敗，OpenClaw 會捨棄由機器人撰寫的聊天室訊息。 ## 執行緒、工作階段與回覆標籤 -- DM 路由為 `direct`；頻道為 `channel`；MPIM 為 `group`。 -- Slack 路由繫結接受原始對等 ID，以及 Slack 目標形式，例如 `channel:C12345678`、`user:U12345678` 和 `<@U12345678>`。 -- 使用預設 `session.dmScope=main` 時，Slack DM 會收斂到代理的主要工作階段。 +- 私人訊息會路由為 `direct`；頻道為 `channel`；多人私人訊息（MPIM）為 `group`。 +- Slack 路由繫結接受原始對等 ID，以及 `channel:C12345678`、`user:U12345678` 和 `<@U12345678>` 等 Slack 目標形式。 +- 使用預設 `session.dmScope=main` 時，Slack 私人訊息會合併到代理程式的主要工作階段。 - 頻道工作階段：`agent::slack:channel:`。 -- 適用時，執行緒回覆可以建立執行緒工作階段後綴（`:thread:`）。 +- 在適用時，執行緒回覆可以建立執行緒工作階段後綴（`:thread:`）。 - `channels.slack.thread.historyScope` 預設為 `thread`；`thread.inheritParent` 預設為 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新執行緒工作階段啟動時要擷取多少則既有執行緒訊息（預設 `20`；設為 `0` 可停用）。 -- `channels.slack.thread.requireExplicitMention`（預設 `false`）：當為 `true` 時，抑制隱含執行緒提及，因此 Bot 只會回應執行緒內明確的 `@bot` 提及，即使 Bot 已經參與該執行緒也是如此。若未啟用此設定，在 Bot 已參與的執行緒中的回覆會略過 `requireMention` 門檻控管。 +- `channels.slack.thread.initialHistoryLimit` 控制新的執行緒工作階段啟動時要擷取多少則既有執行緒訊息（預設 `20`；設為 `0` 可停用）。 +- `channels.slack.thread.requireExplicitMention`（預設 `false`）：當為 `true` 時，抑制隱含的執行緒提及，因此機器人只會回應執行緒內明確的 `@bot` 提及，即使機器人已參與該執行緒亦然。若未啟用，已由機器人參與的執行緒中的回覆會繞過 `requireMention` 門檻。 回覆執行緒控制項： -- `channels.slack.replyToMode`: `off|first|all|batched`（預設 `off`） -- `channels.slack.replyToModeByChatType`：依 `direct|group|channel` 設定 -- 直接聊天的舊版後援：`channels.slack.dm.replyToMode` +- `channels.slack.replyToMode`：`off|first|all|batched`（預設 `off`） +- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分別設定 +- 私人聊天的舊版備援：`channels.slack.dm.replyToMode` 支援手動回覆標籤： @@ -645,37 +953,37 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - `[[reply_to:]]` -`replyToMode="off"` 會停用 Slack 中的**所有**回覆執行緒，包括明確的 `[[reply_to_*]]` 標籤。這與 Telegram 不同；在 Telegram 中，即使處於 `"off"` 模式，明確標籤仍會被遵循。Slack 執行緒會將訊息隱藏於頻道之外，而 Telegram 回覆則維持行內可見。 +`replyToMode="off"` 會停用 Slack 中的**所有**回覆執行緒，包括明確的 `[[reply_to_*]]` 標籤。這與 Telegram 不同；在 Telegram 中，明確標籤即使在 `"off"` 模式下仍會被採用。Slack 執行緒會在頻道中隱藏訊息，而 Telegram 回覆會保留在行內可見。 ## 確認反應 -`ackReaction` 會在 OpenClaw 處理傳入訊息時傳送確認 emoji。 +`ackReaction` 會在 OpenClaw 處理傳入訊息時送出確認表情符號。 解析順序： - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 代理身分 emoji 後援（`agents.list[].identity.emoji`，否則為 "👀"） +- 代理程式身分表情符號備援（`agents.list[].identity.emoji`，否則為 "👀"） 注意事項： - Slack 預期使用短代碼（例如 `"eyes"`）。 -- 使用 `""` 可針對 Slack 帳號或全域停用反應。 +- 使用 `""` 停用該 Slack 帳戶或全域的反應。 ## 文字串流 `channels.slack.streaming` 控制即時預覽行為： - `off`：停用即時預覽串流。 -- `partial`（預設）：用最新的部分輸出取代預覽文字。 +- `partial`（預設）：將預覽文字替換為最新的部分輸出。 - `block`：附加分塊預覽更新。 -- `progress`：產生時顯示進度狀態文字，然後傳送最終文字。 -- `streaming.preview.toolProgress`：當草稿預覽啟用時，將工具/進度更新路由到同一則已編輯的預覽訊息（預設：`true`）。設為 `false` 可保留獨立的工具/進度訊息。 -- `streaming.preview.commandText` / `streaming.progress.commandText`：設為 `status` 可在隱藏原始 command/exec 文字時保留精簡的工具進度行（預設：`raw`）。 +- `progress`：生成期間顯示進度狀態文字，然後送出最終文字。 +- `streaming.preview.toolProgress`：草稿預覽啟用時，將工具/進度更新路由到同一則編輯中的預覽訊息（預設：`true`）。設為 `false` 可保留個別的工具/進度訊息。 +- `streaming.preview.commandText` / `streaming.progress.commandText`：設為 `status` 可在隱藏原始命令/執行文字的同時保留精簡的工具進度行（預設：`raw`）。 -隱藏原始 command/exec 文字，同時保留精簡進度行： +隱藏原始命令/執行文字，同時保留精簡的進度行： ```json { @@ -693,16 +1001,16 @@ Slack 動作由 `channels.slack.actions.*` 控制。 } ``` -`channels.slack.streaming.nativeTransport` 會在 `channels.slack.streaming.mode` 為 `partial` 時控制 Slack 原生文字串流（預設：`true`）。 +`channels.slack.streaming.nativeTransport` 在 `channels.slack.streaming.mode` 為 `partial` 時控制 Slack 原生文字串流（預設：`true`）。 -- 必須有可用的回覆執行緒，原生文字串流和 Slack 助理執行緒狀態才會出現。執行緒選取仍遵循 `replyToMode`。 -- 當原生串流無法使用或沒有回覆執行緒時，頻道、群組聊天和頂層 DM 根訊息仍可使用一般草稿預覽。 -- 頂層 Slack DM 預設不進入執行緒，因此不會顯示 Slack 執行緒樣式的原生串流/狀態預覽；OpenClaw 會改在 DM 中發布並編輯草稿預覽。 -- 媒體和非文字承載會後援為一般傳遞。 -- 媒體/錯誤最終訊息會取消待處理的預覽編輯；符合條件的文字/block 最終訊息只有在能就地編輯預覽時才會清空送出。 -- 如果串流在回覆中途失敗，OpenClaw 會對剩餘承載後援為一般傳遞。 +- 必須有可用的回覆執行緒，原生文字串流與 Slack 助理執行緒狀態才會顯示。執行緒選擇仍遵循 `replyToMode`。 +- 當原生串流不可用或沒有回覆執行緒時，頻道、群組聊天與頂層私人訊息根節點仍可使用一般草稿預覽。 +- 頂層 Slack 私人訊息預設保持非執行緒狀態，因此不會顯示 Slack 的執行緒樣式原生串流/狀態預覽；OpenClaw 會改在私人訊息中發布並編輯草稿預覽。 +- 媒體與非文字酬載會回退到一般傳遞。 +- 媒體/錯誤最終內容會取消待處理的預覽編輯；符合條件的文字/區塊最終內容只有在能就地編輯預覽時才會送出。 +- 如果串流在回覆途中失敗，OpenClaw 會將剩餘酬載回退到一般傳遞。 -使用草稿預覽而非 Slack 原生文字串流： +使用草稿預覽取代 Slack 原生文字串流： ```json5 { @@ -723,9 +1031,9 @@ Slack 動作由 `channels.slack.actions.*` 控制。 - 布林值 `channels.slack.streaming` 會自動遷移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 舊版 `channels.slack.nativeStreaming` 會自動遷移到 `channels.slack.streaming.nativeTransport`。 -## 輸入反應後援 +## 輸入中反應備援 -`typingReaction` 會在 OpenClaw 處理回覆期間，為傳入的 Slack 訊息加上暫時反應，並在執行完成時移除。這在 thread 回覆以外最有用，因為 thread 回覆會使用預設的「is typing...」狀態指示器。 +`typingReaction` 會在 OpenClaw 處理回覆時，對傳入的 Slack 訊息加入暫時反應，並在執行完成時移除。這在對話串回覆以外的情境最有用，因為對話串回覆會使用預設的「正在輸入...」狀態指示器。 解析順序： @@ -734,43 +1042,43 @@ Slack 動作由 `channels.slack.actions.*` 控制。 注意事項： -- Slack 預期使用短代碼（例如 `"hourglass_flowing_sand"`）。 -- 反應會盡力處理，並在回覆或失敗路徑完成後自動嘗試清理。 +- Slack 需要短代碼（例如 `"hourglass_flowing_sand"`）。 +- 反應是盡力而為，回覆或失敗路徑完成後會自動嘗試清理。 -## 媒體、分塊與傳遞 +## 媒體、分塊與傳送 - Slack 檔案附件會從 Slack 託管的私有 URL 下載（token 驗證請求流程），並在擷取成功且大小限制允許時寫入媒體儲存區。檔案預留位置包含 Slack `fileId`，讓 agent 可用 `download-file` 擷取原始檔案。 + Slack 檔案附件會從 Slack 託管的私人 URL（權杖驗證要求流程）下載，並在擷取成功且大小限制允許時寫入媒體儲存區。檔案佔位符包含 Slack `fileId`，因此代理程式可以使用 `download-file` 擷取原始檔案。 - 下載使用有界限的閒置與總逾時。如果 Slack 檔案擷取停滯或失敗，OpenClaw 會繼續處理訊息，並回退到檔案預留位置。 + 下載會使用有界的閒置與總逾時。如果 Slack 檔案擷取停滯或失敗，OpenClaw 會繼續處理訊息，並退回使用檔案佔位符。 - 執行階段的傳入大小上限預設為 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆寫。 + 執行階段傳入大小上限預設為 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆寫。 - 文字分塊使用 `channels.slack.textChunkLimit`（預設 4000） - - `channels.slack.chunkMode="newline"` 會啟用段落優先分割 - - 檔案傳送使用 Slack 上傳 API，並可包含 thread 回覆（`thread_ts`） - - 傳出媒體上限在設定時遵循 `channels.slack.mediaMaxMb`；否則 channel 傳送會使用媒體管線中的 MIME 種類預設值 + - `channels.slack.chunkMode="newline"` 啟用段落優先分割 + - 檔案傳送使用 Slack 上傳 API，並可包含對話串回覆（`thread_ts`） + - 設定時，傳出媒體上限會遵循 `channels.slack.mediaMaxMb`；否則頻道傳送會使用媒體管線中的 MIME 類型預設值 - - 建議使用明確目標： + + 偏好的明確目標： - `user:` 用於 DM - - `channel:` 用於 channel + - `channel:` 用於頻道 - 僅文字/區塊的 Slack DM 可直接發佈到使用者 ID；檔案上傳與 thread 傳送會先透過 Slack conversation API 開啟 DM，因為這些路徑需要具體的 conversation ID。 + 僅含文字/區塊的 Slack DM 可以直接發佈到使用者 ID；檔案上傳和對話串傳送會先透過 Slack conversation API 開啟 DM，因為這些路徑需要具體的 conversation ID。 -## 指令與 slash 行為 +## 指令與斜線行為 -Slash commands 在 Slack 中可顯示為單一已設定指令或多個原生指令。設定 `channels.slack.slashCommand` 以變更指令預設值： +斜線指令在 Slack 中會顯示為單一已設定指令或多個原生指令。設定 `channels.slack.slashCommand` 以變更指令預設值： - `enabled: false` - `name: "openclaw"` @@ -781,7 +1089,7 @@ Slash commands 在 Slack 中可顯示為單一已設定指令或多個原生指 /openclaw /help ``` -原生指令需要在你的 Slack app 中設定[其他 manifest 設定](#additional-manifest-settings)，並改用 `channels.slack.commands.native: true` 啟用，或在全域設定中使用 `commands.native: true`。 +原生指令需要在你的 Slack app 中使用[額外的資訊清單設定](#additional-manifest-settings)，並以 `channels.slack.commands.native: true` 啟用，或改在全域設定中使用 `commands.native: true`。 - Slack 的原生指令自動模式為**關閉**，因此 `commands.native: "auto"` 不會啟用 Slack 原生指令。 @@ -789,22 +1097,22 @@ Slash commands 在 Slack 中可顯示為單一已設定指令或多個原生指 /help ``` -原生引數選單使用自適應呈現策略，會在分派所選選項值前顯示確認 modal： +原生引數選單使用自適應呈現策略，會在分派所選選項值前顯示確認互動視窗： -- 最多 5 個選項：button blocks -- 6-100 個選項：static select menu -- 超過 100 個選項：在 interactivity options handlers 可用時，使用 external select 搭配非同步選項篩選 -- 超過 Slack 限制：已編碼的選項值會回退為按鈕 +- 最多 5 個選項：按鈕區塊 +- 6-100 個選項：靜態選取選單 +- 超過 100 個選項：當 interactivity 選項處理常式可用時，使用具有非同步選項篩選的外部選取 +- 超過 Slack 限制：編碼選項值會退回使用按鈕 ```txt /think ``` -Slash sessions 使用像 `agent::slack:slash:` 這樣的隔離 key，且仍會使用 `CommandTargetSessionKey` 將指令執行路由到目標 conversation session。 +斜線工作階段使用像 `agent::slack:slash:` 這類隔離金鑰，且仍會使用 `CommandTargetSessionKey` 將指令執行路由到目標對話工作階段。 ## 互動式回覆 -Slack 可以呈現 agent 撰寫的互動式回覆控制項，但此功能預設停用。 +Slack 可以呈現由代理程式撰寫的互動式回覆控制項，但此功能預設停用。 全域啟用： @@ -820,7 +1128,7 @@ Slack 可以呈現 agent 撰寫的互動式回覆控制項，但此功能預設 } ``` -或只為一個 Slack 帳戶啟用： +或僅為一個 Slack 帳號啟用： ```json5 { @@ -838,44 +1146,43 @@ Slack 可以呈現 agent 撰寫的互動式回覆控制項，但此功能預設 } ``` -啟用後，agent 可以發出僅限 Slack 的回覆指示： +啟用後，代理程式可以發出僅適用於 Slack 的回覆指示： - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -這些指示會編譯為 Slack Block Kit，並透過既有 Slack interaction event 路徑把點擊或選取路由回來。 +這些指示會編譯成 Slack Block Kit，並透過既有 Slack 互動事件路徑路由點擊或選取。 注意事項： -- 這是 Slack 專用 UI。其他 channel 不會將 Slack Block Kit 指示轉譯為自己的按鈕系統。 -- 互動式 callback 值是 OpenClaw 產生的不透明 token，不是 agent 撰寫的原始值。 -- 如果產生的互動式 blocks 會超過 Slack Block Kit 限制，OpenClaw 會回退為原始文字回覆，而不是傳送無效的 blocks payload。 +- 這是 Slack 專用 UI。其他頻道不會將 Slack Block Kit 指示轉譯成自己的按鈕系統。 +- 互動式回呼值是由 OpenClaw 產生的不透明權杖，不是代理程式撰寫的原始值。 +- 如果產生的互動式區塊會超過 Slack Block Kit 限制，OpenClaw 會退回傳送原始文字回覆，而不是傳送無效的 blocks 承載。 -## Slack 中的 Exec 核准 +## Slack 中的執行核准 -Slack 可作為具有互動式按鈕與互動的原生核准用戶端，而不是回退到 Web UI 或 terminal。 +Slack 可以作為具有互動式按鈕與互動的原生核准用戶端，而不是退回使用 Web UI 或終端機。 -- Exec 核准使用 `channels.slack.execApprovals.*` 進行原生 DM/channel 路由。 -- 當請求已落在 Slack 中且核准 id 種類為 `plugin:` 時，Plugin 核准仍可透過相同的 Slack 原生按鈕介面解析。 -- 核准者授權仍會強制執行：只有識別為核准者的使用者可透過 Slack 核准或拒絕請求。 +- 執行核准使用 `channels.slack.execApprovals.*` 進行原生 DM/頻道路由。 +- 當要求已經落在 Slack 中，且核准 ID 類型為 `plugin:` 時，Plugin 核准仍可透過相同的 Slack 原生按鈕介面解析。 +- 仍會強制執行核准者授權：只有識別為核准者的使用者可以透過 Slack 核准或拒絕要求。 -這會使用與其他 channel 相同的共用核准按鈕介面。當你的 Slack app 設定中啟用 `interactivity` 時，核准提示會在 conversation 中直接呈現為 Block Kit 按鈕。 -當這些按鈕存在時，它們就是主要核准 UX；OpenClaw -只有在工具結果表示聊天核准不可用，或手動核准是唯一路徑時， +這使用與其他頻道相同的共用核准按鈕介面。當你的 Slack app 設定中啟用 `interactivity` 時，核准提示會直接在對話中呈現為 Block Kit 按鈕。 +當這些按鈕存在時，它們就是主要核准使用者體驗；OpenClaw +只有在工具結果表示聊天核准無法使用，或手動核准是唯一路徑時， 才應包含手動 `/approve` 指令。 設定路徑： - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers`（選用；可行時回退到 `commands.ownerAllowFrom`） +- `channels.slack.execApprovals.approvers`（選用；可行時會退回使用 `commands.ownerAllowFrom`） - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，預設：`dm`） -- `agentFilter`、`sessionFilter` +- `agentFilter`, `sessionFilter` -當 `enabled` 未設定或為 `"auto"` 且至少解析出一位 -核准者時，Slack 會自動啟用原生 exec 核准。設定 `enabled: false` 可明確停用 Slack 作為原生核准用戶端。 -設定 `enabled: true` 可在解析出核准者時強制啟用原生核准。 +當 `enabled` 未設定或為 `"auto"`，且至少一位核准者可解析時，Slack 會自動啟用原生執行核准。設定 `enabled: false` 可明確停用 Slack 作為原生核准用戶端。 +設定 `enabled: true` 可在核准者解析時強制開啟原生核准。 -沒有明確 Slack exec 核准設定時的預設行為： +沒有明確 Slack 執行核准設定時的預設行為： ```json5 { @@ -885,8 +1192,8 @@ Slack 可作為具有互動式按鈕與互動的原生核准用戶端，而不 } ``` -只有在你想覆寫核准者、新增篩選器，或 -選擇加入來源聊天傳遞時，才需要明確的 Slack 原生設定： +只有在你想要覆寫核准者、新增篩選器，或選擇加入來源聊天傳送時， +才需要明確的 Slack 原生設定： ```json5 { @@ -902,51 +1209,51 @@ Slack 可作為具有互動式按鈕與互動的原生核准用戶端，而不 } ``` -共用 `approvals.exec` 轉送是分開的。只有當 exec 核准提示也必須 -路由到其他聊天或明確的頻外目標時才使用它。共用 `approvals.plugin` 轉送也 -是分開的；當這些請求已落在 Slack 中時，Slack 原生按鈕仍可解析 Plugin 核准。 +共用 `approvals.exec` 轉送是獨立的。只有在執行核准提示也必須 +路由到其他聊天或明確的頻外目標時才使用。共用 `approvals.plugin` 轉送也是 +獨立的；當這些要求已經落在 Slack 中時，Slack 原生按鈕仍可解析 Plugin 核准。 -同一聊天中的 `/approve` 也可在已支援指令的 Slack channel 與 DM 中運作。完整核准轉送模型請參閱 [Exec 核准](/zh-TW/tools/exec-approvals)。 +同一聊天中的 `/approve` 也可在已支援指令的 Slack 頻道與 DM 中運作。請參閱[執行核准](/zh-TW/tools/exec-approvals)以了解完整的核准轉送模型。 -## 事件與操作行為 +## 事件與營運行為 -- 訊息編輯/刪除會映射為 system events。 -- Thread broadcasts（「Also send to channel」thread 回覆）會作為一般使用者訊息處理。 -- Reaction add/remove events 會映射為 system events。 -- Member join/leave、channel created/renamed，以及 pin add/remove events 會映射為 system events。 -- 啟用 `configWrites` 時，`channel_id_changed` 可遷移 channel config keys。 -- Channel topic/purpose metadata 會被視為不受信任的上下文，且可注入 routing context。 -- 適用時，thread starter 與初始 thread-history context seeding 會依設定的 sender allowlists 篩選。 -- Block actions 與 modal interactions 會發出結構化的 `Slack interaction: ...` system events，並帶有豐富的 payload fields： - - block actions：selected values、labels、picker values，以及 `workflow_*` metadata - - modal `view_submission` 與 `view_closed` events，包含已路由的 channel metadata 與 form inputs +- 訊息編輯/刪除會對應到系統事件。 +- 對話串廣播（「也傳送到頻道」的對話串回覆）會作為一般使用者訊息處理。 +- 反應新增/移除事件會對應到系統事件。 +- 成員加入/離開、頻道建立/重新命名，以及釘選新增/移除事件會對應到系統事件。 +- 啟用 `configWrites` 時，`channel_id_changed` 可以遷移頻道設定金鑰。 +- 頻道主題/用途中繼資料會被視為不受信任的脈絡，並可注入路由脈絡。 +- 對話串起始者與初始對話串歷史脈絡植入，會在適用時依設定的寄件者允許清單進行篩選。 +- 區塊動作與互動視窗互動會發出結構化的 `Slack interaction: ...` 系統事件，並包含豐富的承載欄位： + - 區塊動作：選取值、標籤、選擇器值，以及 `workflow_*` 中繼資料 + - 互動視窗 `view_submission` 與 `view_closed` 事件，含已路由的頻道中繼資料與表單輸入 ## 設定參考 -主要參考：[Configuration reference - Slack](/zh-TW/gateway/config-channels#slack)。 +主要參考：[設定參考 - Slack](/zh-TW/gateway/config-channels#slack)。 -- mode/auth：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` -- DM access：`dm.enabled`、`dmPolicy`、`allowFrom`（舊版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` -- compatibility toggle：`dangerouslyAllowNameMatching`（break-glass；除非需要，否則保持關閉） -- channel access：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` -- threading/history：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- delivery：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress` -- ops/features：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly` +- 模式/驗證：`mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` +- DM 存取：`dm.enabled`, `dmPolicy`, `allowFrom`（舊版：`dm.policy`, `dm.allowFrom`）、`dm.groupEnabled`, `dm.groupChannels` +- 相容性切換：`dangerouslyAllowNameMatching`（break-glass；除非需要，否則保持關閉） +- 頻道存取：`groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` +- 對話串/歷史：`replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- 傳送：`textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` +- 營運/功能：`configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## 疑難排解 - + 依序檢查： - `groupPolicy` - - channel allowlist（`channels.slack.channels`）— **key 必須是 channel ID**（`C12345678`），不是名稱（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，以名稱為基礎的 key 會靜默失敗，因為 channel 路由預設是 ID 優先。若要尋找 ID：在 Slack 中以右鍵點選 channel → **Copy link** — URL 結尾的 `C...` 值就是 channel ID。 + - 頻道允許清單（`channels.slack.channels`）— **金鑰必須是頻道 ID**（`C12345678`），不是名稱（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，名稱式金鑰會無聲失敗，因為頻道路由預設以 ID 優先。若要尋找 ID：在 Slack 中以右鍵點擊頻道 → **複製連結** — URL 結尾的 `C...` 值就是頻道 ID。 - `requireMention` - - 每個 channel 的 `users` allowlist + - 各頻道的 `users` 允許清單 實用指令： @@ -963,10 +1270,10 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或舊版 `channels.slack.dm.policy`） - - pairing approvals / allowlist entries - - Slack Assistant DM events：提到 `drop message_changed` 的 verbose logs - 通常表示 Slack 傳送了已編輯的 Assistant-thread event，但 message metadata 中沒有 - 可復原的人類 sender + - 配對核准 / 允許清單項目 + - Slack Assistant DM 事件：提到 `drop message_changed` 的詳細記錄 + 通常表示 Slack 傳送了一個已編輯的 Assistant 對話串事件，但訊息中繼資料中沒有 + 可復原的人類寄件者 ```bash openclaw pairing list slack @@ -974,103 +1281,103 @@ openclaw pairing list slack - - 在 Slack app 設定中驗證 bot + app tokens 與 Socket Mode 啟用狀態。 + + 在 Slack app 設定中驗證 bot + app 權杖與 Socket Mode 啟用狀態。 如果 `openclaw channels status --probe --json` 顯示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，表示 Slack 帳戶已設定， - 但目前 runtime 無法解析 SecretRef 支援的 + `appTokenStatus: "configured_unavailable"`，表示 Slack 帳號已設定， + 但目前執行階段無法解析由 SecretRef 支援的 值。 - + 驗證： - - signing secret - - webhook path - - Slack Request URLs（Events + Interactivity + Slash Commands） - - 每個 HTTP 帳戶唯一的 `webhookPath` + - 簽章密鑰 + - Webhook 路徑 + - Slack 要求 URL（事件 + 互動 + 斜線指令） + - 每個 HTTP 帳號唯一的 `webhookPath` - 如果 account snapshots 中出現 `signingSecretStatus: "configured_unavailable"`， - 表示 HTTP 帳戶已設定，但目前 runtime 無法 - 解析 SecretRef 支援的 signing secret。 + 如果帳號快照中出現 `signingSecretStatus: "configured_unavailable"`， + 表示 HTTP 帳號已設定，但目前執行階段無法 + 解析由 SecretRef 支援的簽章密鑰。 - + 確認你的意圖是： - - 原生指令模式（`channels.slack.commands.native: true`），且 Slack 中已註冊相符的 slash commands - - 或單一 slash command 模式（`channels.slack.slashCommand.enabled: true`） + - 原生指令模式（`channels.slack.commands.native: true`），且已在 Slack 中註冊相符的斜線指令 + - 或單一斜線指令模式（`channels.slack.slashCommand.enabled: true`） - 也請檢查 `commands.useAccessGroups` 與 channel/user allowlists。 + 也請檢查 `commands.useAccessGroups` 與頻道/使用者允許清單。 -## 附件 vision 參考 +## 附件視覺參考 -當 Slack 檔案下載成功且大小限制允許時，Slack 可將下載的媒體附加到 agent turn。影像檔案可以透過媒體理解路徑傳遞，或直接傳給具 vision 能力的回覆模型；其他檔案會保留為可下載檔案上下文，而不是視為影像輸入。 +當 Slack 檔案下載成功且大小限制允許時，Slack 可以將已下載的媒體附加到代理程式回合。圖片檔案可以透過媒體理解路徑傳遞，或直接傳給具備視覺能力的回覆模型；其他檔案會保留為可下載的檔案脈絡，而不會被視為圖片輸入。 ### 支援的媒體類型 | 媒體類型 | 來源 | 目前行為 | 備註 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| JPEG / PNG / GIF / WebP 圖片 | Slack 檔案 URL | 已下載並附加到該輪對話，以供具備視覺能力的處理使用 | 每檔上限：`channels.slack.mediaMaxMb`（預設 20 MB） | -| PDF 檔案 | Slack 檔案 URL | 已下載並作為檔案內容提供給 `download-file` 或 `pdf` 等工具 | Slack 入站不會自動將 PDF 轉換為圖片視覺輸入 | -| 其他檔案 | Slack 檔案 URL | 可行時下載，並作為檔案內容提供 | 二進位檔案不會被視為圖片輸入 | -| 執行緒回覆 | 執行緒起始訊息檔案 | 當回覆沒有直接媒體時，根訊息檔案可作為內容補足 | 僅含檔案的起始訊息會使用附件佔位符 | -| 多圖片訊息 | 多個 Slack 檔案 | 每個檔案都會獨立評估 | Slack 處理上限為每則訊息八個檔案 | +| JPEG / PNG / GIF / WebP 圖片 | Slack 檔案 URL | 已下載並附加到該輪次，以供具備視覺能力的處理使用 | 單一檔案上限：`channels.slack.mediaMaxMb`（預設 20 MB） | +| PDF 檔案 | Slack 檔案 URL | 已下載並作為檔案內容脈絡提供給 `download-file` 或 `pdf` 等工具使用 | Slack 輸入不會自動將 PDF 轉換成影像視覺輸入 | +| 其他檔案 | Slack 檔案 URL | 可行時下載，並作為檔案內容脈絡提供 | 二進位檔案不會被視為影像輸入 | +| 執行緒回覆 | 執行緒起始訊息檔案 | 當回覆沒有直接媒體時，根訊息檔案可作為內容脈絡補齊 | 只有檔案的起始訊息會使用附件預留位置 | +| 多圖片訊息 | 多個 Slack 檔案 | 每個檔案都會獨立評估 | Slack 處理每則訊息最多八個檔案 | -### 入站管線 +### 輸入管線 -當含有檔案附件的 Slack 訊息抵達時： +當帶有檔案附件的 Slack 訊息抵達時： -1. OpenClaw 會使用機器人 Token（`xoxb-...`）從 Slack 的私人 URL 下載檔案。 +1. OpenClaw 會使用機器人權杖（`xoxb-...`）從 Slack 的私有 URL 下載檔案。 2. 下載成功後，檔案會寫入媒體儲存區。 -3. 已下載媒體的路徑與內容類型會加入入站內容。 -4. 具備圖片能力的模型/工具路徑可以使用該內容中的圖片附件。 -5. 非圖片檔案仍會以檔案中繼資料或媒體參照的形式，提供給能處理它們的工具。 +3. 已下載媒體路徑和內容類型會加入輸入內容脈絡。 +4. 具備影像能力的模型／工具路徑可使用該內容脈絡中的影像附件。 +5. 非影像檔案仍會作為檔案中繼資料或媒體參照，提供給能處理它們的工具使用。 ### 執行緒根附件繼承 -當訊息抵達某個執行緒時（具有 `thread_ts` 父項）： +當訊息抵達執行緒中（具有 `thread_ts` 父項）時： -- 如果回覆本身沒有直接媒體，而包含的根訊息有檔案，Slack 可以將根檔案補足為執行緒起始內容。 +- 如果回覆本身沒有直接媒體，而包含的根訊息有檔案，Slack 可將根檔案補齊為執行緒起始內容脈絡。 - 直接回覆附件優先於根訊息附件。 -- 只有檔案且沒有文字的根訊息會以附件佔位符表示，使備援仍可包含其檔案。 +- 只有檔案且沒有文字的根訊息會以附件預留位置表示，因此後援仍可包含其檔案。 ### 多附件處理 當單一 Slack 訊息包含多個檔案附件時： - 每個附件都會透過媒體管線獨立處理。 -- 已下載的媒體參照會彙總到訊息內容中。 -- 處理順序會依照事件酬載中的 Slack 檔案順序。 -- 某個附件下載失敗不會阻擋其他附件。 +- 已下載的媒體參照會彙總到訊息內容脈絡中。 +- 處理順序遵循事件承載中 Slack 的檔案順序。 +- 某個附件下載失敗不會阻止其他附件。 ### 大小、下載與模型限制 - **大小上限**：預設每個檔案 20 MB。可透過 `channels.slack.mediaMaxMb` 設定。 -- **下載失敗**：Slack 無法提供的檔案、過期 URL、無法存取的檔案、超過大小限制的檔案，以及 Slack 驗證/登入 HTML 回應會被略過，而不是回報為不支援的格式。 -- **視覺模型**：圖片分析會在作用中的回覆模型支援視覺時使用該模型，否則使用 `agents.defaults.imageModel` 設定的圖片模型。 +- **下載失敗**：Slack 無法提供的檔案、過期 URL、無法存取的檔案、超過大小限制的檔案，以及 Slack 驗證／登入 HTML 回應都會被略過，而不是回報為不支援的格式。 +- **視覺模型**：影像分析會在作用中回覆模型支援視覺時使用該模型，或使用 `agents.defaults.imageModel` 設定的影像模型。 ### 已知限制 | 情境 | 目前行為 | 因應方式 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 過期的 Slack 檔案 URL | 檔案被略過；不會顯示錯誤 | 在 Slack 重新上傳檔案 | -| 未設定視覺模型 | 圖片附件會儲存為媒體參照，但不會作為圖片分析 | 設定 `agents.defaults.imageModel`，或使用具備視覺能力的回覆模型 | -| 非常大的圖片（預設 > 20 MB） | 依大小上限略過 | 若 Slack 允許，增加 `channels.slack.mediaMaxMb` | -| 轉寄/共享附件 | 文字與 Slack 託管的圖片/檔案媒體會盡力處理 | 直接在 OpenClaw 執行緒中重新分享 | -| PDF 附件 | 儲存為檔案/媒體內容，不會自動路由至圖片視覺 | 使用 `download-file` 取得檔案中繼資料，或使用 `pdf` 工具分析 PDF | +| 過期的 Slack 檔案 URL | 略過檔案；不顯示錯誤 | 在 Slack 中重新上傳檔案 | +| 未設定視覺模型 | 影像附件會儲存為媒體參照，但不會作為影像分析 | 設定 `agents.defaults.imageModel`，或使用具備視覺能力的回覆模型 | +| 非常大的圖片（預設 > 20 MB） | 依大小上限略過 | 如果 Slack 允許，請提高 `channels.slack.mediaMaxMb` | +| 轉寄／共享的附件 | 文字與 Slack 託管的影像／檔案媒體會盡力處理 | 直接在 OpenClaw 執行緒中重新分享 | +| PDF 附件 | 儲存為檔案／媒體內容脈絡，不會自動透過影像視覺路由 | 使用 `download-file` 取得檔案中繼資料，或使用 `pdf` 工具進行 PDF 分析 | ### 相關文件 - [媒體理解管線](/zh-TW/nodes/media-understanding) - [PDF 工具](/zh-TW/tools/pdf) -- Epic：[ #51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件視覺啟用 +- 史詩：[ #51349](https://github.com/openclaw/openclaw/issues/51349) — 啟用 Slack 附件視覺 - 迴歸測試：[ #51353](https://github.com/openclaw/openclaw/issues/51353) - 即時驗證：[ #51354](https://github.com/openclaw/openclaw/issues/51354) @@ -1078,13 +1385,13 @@ openclaw pairing list slack - 將 Slack 使用者與 Gateway 配對。 + 將 Slack 使用者配對到 Gateway。 頻道與群組 DM 行為。 - 將入站訊息路由至代理程式。 + 將輸入訊息路由到代理。 威脅模型與強化。 diff --git a/docs/zh-TW/ci.md b/docs/zh-TW/ci.md index 8a32cd62f..d5445f7cc 100644 --- a/docs/zh-TW/ci.md +++ b/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= | 執行器 | 工作 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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//-//` 底下。目前受測 ref 指標會寫入為 `openclaw-performance//latest-.json`。 +每個通道都會上傳 GitHub artifacts。設定 `CLAWGRIT_REPORTS_TOKEN` 時，工作流程也會將 `report.json`、`report.md`、套件、`index.md`，以及原始碼探測 artifacts 提交到 `openclaw/clawgrit-reports` 的 `openclaw-performance//-//` 底下。目前測試 ref 指標會寫入為 `openclaw-performance//latest-.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=`： +若要在快速變動分支上取得釘選 commit 證明，請使用輔助程式，而不是 `gh workflow run ... --ref main -f ref=`： ```bash pnpm ci:full-release --sha ``` -GitHub 工作流程派送 ref 必須是分支或標籤，不能是原始 commit SHA。此 -helper 會在目標 SHA 推送暫時的 `release-ci/-...` 分支， -從該釘選 ref 派送 `Full Release Validation`，驗證每個子 -工作流程的 `headSha` 都符合目標，並在執行完成時刪除暫時分支。如果任何子工作流程在 -不同的 SHA 上執行，總控驗證器也會失敗。 +GitHub 工作流程分派 ref 必須是分支或標籤，不能是原始 commit SHA。輔助程式會在目標 SHA 推送一個臨時的 `release-ci/-...` 分支，從該釘選 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:` 映像。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:` 映像。即時發行工作流程會建置並推送該映像一次，然後 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 # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # 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 ``` -只有在你有意需要在同一個已 hydrate 的 box 上執行多個命令時，才使用重用： +只有在你刻意需要於同一個已水合 box 上執行多個命令時，才使用重複使用： ```bash pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " pnpm crabbox:stop -- ``` -如果 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 "env CI=1 NODE_OPTIONS=--max-old-space-size blacksmith testbox stop --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 --timing-json --shell -- "env NODE_OPT pnpm crabbox:stop -- ``` -`.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 ` 命令的非 secret 環境交接。 +`.crabbox.yaml` 負責自有雲端檢查線的提供者、同步與 GitHub Actions 水合預設值。它會排除本機 `.git`，讓已水合的 Actions checkout 保留自己的遠端 Git 中繼資料，而不是同步維護者本機的遠端與物件儲存，並且會排除不應傳輸的本機執行期/建置成品。`.github/workflows/crabbox-hydrate.yml` 負責 checkout、Node/pnpm 設定、`origin/main` 擷取，以及自有雲端 `crabbox run --id ` 命令的非密鑰環境交接。 ## 相關 diff --git a/docs/zh-TW/cli/dashboard.md b/docs/zh-TW/cli/dashboard.md index c908cb427..795bdfaaf 100644 --- a/docs/zh-TW/cli/dashboard.md +++ b/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) diff --git a/docs/zh-TW/cli/doctor.md b/docs/zh-TW/cli/doctor.md index 3f4658d37..df99840cd 100644 --- a/docs/zh-TW/cli/doctor.md +++ b/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.` 需要互動式確認；`--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.` 項目並移除其無效的 `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.` 需要互動式確認；`--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.` 項目，並移除其無效的 `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.`。 -- 重複執行 `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..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..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 diff --git a/docs/zh-TW/cli/gateway.md b/docs/zh-TW/cli/gateway.md index aefd4f037..b475404c4 100644 --- a/docs/zh-TW/cli/gateway.md +++ b/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 …` 之下。 - + 本機 mDNS + 廣域 DNS-SD 設定。 - - OpenClaw 如何公布並尋找 Gateway。 + + OpenClaw 如何公告與尋找 Gateway。 - - 頂層 Gateway 組態鍵。 + + 頂層 Gateway 設定鍵。 @@ -44,13 +44,13 @@ openclaw gateway run ``` - - - 依預設，除非 `~/.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，請在結束前還原終端。 + + - 預設情況下，除非 `~/.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，請在結束前還原終端機。 @@ -58,7 +58,7 @@ openclaw gateway run ### 選項 - WebSocket 連接埠（預設來自組態/環境；通常是 `18789`）。 + WebSocket 連接埠（預設值來自設定/env；通常為 `18789`）。 監聽器綁定模式。 @@ -67,7 +67,7 @@ openclaw gateway run 驗證模式覆寫。 - Token 覆寫（也會為程序設定 `OPENCLAW_GATEWAY_TOKEN`）。 + token 覆寫（也會為程序設定 `OPENCLAW_GATEWAY_TOKEN`）。 密碼覆寫。 @@ -79,28 +79,28 @@ openclaw gateway run 透過 Tailscale 暴露 Gateway。 - 關閉時重設 Tailscale serve/funnel 組態。 + 關閉時重設 Tailscale serve/funnel 設定。 - 允許在組態中沒有 `gateway.mode=local` 時啟動 Gateway。僅針對臨時/開發啟動程序繞過啟動護欄；不會寫入或修復組態檔。 + 允許在設定中沒有 `gateway.mode=local` 時啟動 Gateway。僅針對臨時/開發 bootstrap 繞過啟動防護；不會寫入或修復設定檔。 - 如果缺少，建立開發組態 + 工作區（略過 BOOTSTRAP.md）。 + 如果缺少，則建立開發設定 + 工作區（略過 BOOTSTRAP.md）。 - 重設開發組態 + 認證 + 工作階段 + 工作區（需要 `--dev`）。 + 重設開發設定 + 憑證 + 工作階段 + 工作區（需要 `--dev`）。 啟動前終止所選連接埠上的任何既有監聽器。 - 詳細記錄。 + 詳細日誌。 - 僅在主控台顯示 CLI 後端記錄（並啟用 stdout/stderr）。 + 僅在主控台顯示 CLI 後端日誌（並啟用 stdout/stderr）。 - WebSocket 記錄樣式。 + WebSocket 日誌樣式。 `--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`。 -行內 `--password` 可能會暴露在本機程序清單中。請優先使用 `--password-file`、環境變數，或由 SecretRef 支援的 `gateway.auth.password`。 +行內 `--password` 可能會暴露在本機程序清單中。建議使用 `--password-file`、env，或由 SecretRef 支援的 `gateway.auth.password`。 -### 啟動效能剖析 +### 啟動剖析 -- 設定 `OPENCLAW_GATEWAY_STARTUP_TRACE=1`，可在 Gateway 啟動期間記錄各階段耗時，包括每階段的 `eventLoopMax` 延遲，以及已安裝索引、manifest 登錄、啟動規劃和 owner-map 工作的 Plugin 查找表耗時。 -- 設定 `OPENCLAW_DIAGNOSTICS=timeline` 搭配 `OPENCLAW_DIAGNOSTICS_TIMELINE_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=`，可為外部 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。 - - - 預設：人類可讀（TTY 中會有色彩）。 + + - 預設：人類可讀（在 TTY 中著色）。 - `--json`：機器可讀 JSON（無樣式/旋轉指示器）。 - `--no-color`（或 `NO_COLOR=1`）：停用 ANSI，同時保留人類可讀版面。 - + - `--url `：Gateway WebSocket URL。 - `--token `：Gateway token。 - `--password `：Gateway 密碼。 - `--timeout `：逾時/預算（依命令而異）。 - - `--expect-final`：等待「final」回應（agent 呼叫）。 + - `--expect-final`：等待「final」回應（代理呼叫）。 -當你設定 `--url` 時，CLI 不會回退使用組態或環境認證。請明確傳入 `--token` 或 `--password`。缺少明確認證是一項錯誤。 +設定 `--url` 時，CLI 不會回退使用設定或環境憑證。請明確傳入 `--token` 或 `--password`。缺少明確憑證是錯誤。 ### `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 ``` - 要包含的近期事件數上限（最大 `1000`）。 + 要包含的近期事件最大數量（最大 `1000`）。 依診斷事件類型篩選，例如 `payload.large` 或 `diagnostic.memory.pressure`。 @@ -201,26 +201,26 @@ openclaw gateway stability --json 僅包含診斷序號之後的事件。 - 讀取持久化的穩定性套件，而不是呼叫執行中的 Gateway。針對狀態目錄下最新的套件，請使用 `--bundle latest`（或只用 `--bundle`），或直接傳入套件 JSON 路徑。 + 讀取持久化的穩定性 bundle，而不是呼叫執行中的 Gateway。使用 `--bundle latest`（或只用 `--bundle`）讀取狀態目錄下最新的 bundle，或直接傳入 bundle JSON 路徑。 - 寫入可分享的支援診斷 zip，而不是列印穩定性細節。 + 寫入可分享的支援診斷 zip，而不是列印穩定性詳細資料。 `--export` 的輸出路徑。 - - - 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/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` 也適用於套件輸出。 + + - 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/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 輸出。 ### `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 路徑。預設為狀態目錄下的支援匯出。 - 要包含的已清理記錄行數上限。 + 要包含的已清理日誌行數上限。 - 要檢查的記錄位元組數上限。 + 要檢查的日誌位元組上限。 - 用於健康快照的 Gateway WebSocket URL。 + 健康快照的 Gateway WebSocket URL。 - 用於健康快照的 Gateway token。 + 健康快照的 Gateway token。 - 用於健康快照的 Gateway 密碼。 + 健康快照的 Gateway 密碼。 狀態/健康快照逾時。 - 略過持久化穩定性套件查找。 + 略過持久化穩定性 bundle 查詢。 - 以 JSON 列印寫入的路徑、大小和 manifest。 + 以 JSON 列印寫入路徑、大小和 manifest。 -匯出內容包含 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 仍會被探測。 - 探測使用的 Token 驗證。 + 探測的權杖驗證。 - 探測使用的密碼驗證。 + 探測的密碼驗證。 探測逾時。 - 跳過連線能力探測（僅服務檢視）。 + 略過連線能力探測（僅服務檢視）。 也掃描系統層級服務。 - 將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零狀態結束。不可與 `--no-probe` 搭配使用。 + 將預設連線能力探測升級為讀取探測，且在該讀取探測失敗時以非零狀態碼退出。不可與 `--no-probe` 合併使用。 - - 即使本機 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 與服務設定路徑/有效性快照，以協助診斷設定檔或狀態目錄漂移。 - - - 在 Linux systemd 安裝中，服務驗證偏移檢查會從 unit 讀取 `Environment=` 與 `EnvironmentFile=` 值（包括 `%h`、加引號的路徑、多個檔案，以及選用的 `-` 檔案）。 - - 偏移檢查會使用合併後的執行階段環境解析 `gateway.auth.token` SecretRefs（先使用服務命令環境，再回退到處理程序環境）。 - - 如果 Token 驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或模式未設定且密碼可能優先、且沒有 Token 候選可優先），Token 偏移檢查會跳過設定 Token 解析。 + + - 在 Linux systemd 安裝上，服務驗證漂移檢查會從 unit 讀取 `Environment=` 與 `EnvironmentFile=` 值（包含 `%h`、加引號的路徑、多個檔案，以及可選的 `-` 檔案）。 + - 漂移檢查會使用合併後的執行階段 env 解析 `gateway.auth.token` SecretRefs（先使用服務命令 env，再退回處理程序 env）。 + - 如果權杖驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或 mode 未設定且密碼可勝出、沒有權杖候選可勝出），權杖漂移檢查會略過設定權杖解析。 ### `gateway probe` -`gateway probe` 是「偵錯一切」命令。它一律會探測： +`gateway probe` 是「偵錯所有項目」命令。它一律會探測： -- 你已設定的遠端 Gateway（如果已設定），以及 +- 你已設定的遠端 gateway（如果已設定），以及 - localhost（loopback），**即使已設定遠端**。 -如果你傳入 `--url`，該明確目標會被加入兩者之前。人類可讀輸出會將目標標示為： +如果你傳入 `--url`，該明確目標會被加到兩者之前。人類可讀輸出會將目標標示為： - `URL (explicit)` - `Remote (configured)` 或 `Remote (configured, inactive)` - `Local loopback` -如果可連線到多個 Gateway，它會全部列印出來。當你使用隔離的設定檔／連接埠時（例如救援 bot），支援多個 Gateway，但大多數安裝仍只執行單一 Gateway。 +如果可連線到多個 gateway，它會列印全部。當你使用隔離的設定檔/連接埠時（例如救援 bot），支援多個 gateway，但大多數安裝仍只執行單一 gateway。 ```bash @@ -338,52 +338,52 @@ openclaw gateway probe --json - `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 會重複使用既有的快取裝置驗證，但不會建立首次裝置身分或配對狀態。 + - 只有在沒有任何被探測目標可連線時，退出碼才會是非零。 - 頂層： + 最上層： - - `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`：該目標顯示出的驗證能力分類。 - - `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` 而受限。 -#### 透過 SSH 遠端連線（Mac app parity） +#### 透過 SSH 遠端（與 Mac 應用程式對等） -macOS app 的「Remote over SSH」模式使用本機連接埠轉送，因此遠端 Gateway（可能只繫結到 loopback）可在 `ws://127.0.0.1:` 連線。 +macOS 應用程式的「Remote over SSH」模式會使用本機連接埠轉送，讓遠端 gateway（可能只綁定到 loopback）可在 `ws://127.0.0.1:` 連線。 -CLI 等效命令： +CLI 對等命令： ```bash openclaw gateway probe --ssh user@gateway-host @@ -396,10 +396,10 @@ openclaw gateway probe --ssh user@gateway-host 身分檔案。 - 從已解析的探索端點（`local.` 加上已設定的廣域網域，如有）選擇第一個探索到的 Gateway 主機作為 SSH 目標。純 TXT 提示會被忽略。 + 從已解析的 discovery 端點（`local.` 加上已設定的廣域網域，如果有）挑選第一個探索到的 gateway 主機作為 SSH 目標。僅 TXT 的提示會被忽略。 -設定（選用，用作預設值）： +設定（可選，用作預設值）： - `gateway.remote.sshTarget` - `gateway.remote.sshIdentity` @@ -414,13 +414,13 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' ``` - 參數用的 JSON 物件字串。 + params 的 JSON 物件字串。 Gateway WebSocket URL。 - Gateway Token。 + Gateway 權杖。 Gateway 密碼。 @@ -429,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' 逾時預算。 - 主要用於 agent 樣式的 RPC，這類 RPC 會在最終 payload 前串流中繼事件。 + 主要用於 agent 風格的 RPC，這類 RPC 會在最終 payload 前串流中繼事件。 - 機器可讀 JSON 輸出。 + 機器可讀的 JSON 輸出。 @@ -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 - `gateway status`：`--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json` - `gateway install`：`--port`、`--runtime `、`--token`、`--wrapper `、`--force`、`--json` - - `gateway restart`：`--force`、`--wait `、`--json` + - `gateway restart`：`--safe`、`--force`、`--wait `、`--json` - `gateway uninstall|start|stop`：`--json` - - 使用 `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` 以供腳本使用。 - - 當 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`，安裝會被阻擋，直到明確設定模式。 -## 探索 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 每個命令的逾時時間（瀏覽/解析）。 - 機器可讀輸出（也會停用樣式/旋轉指示器）。 + 機器可讀輸出（也會停用樣式/載入指示器）。 範例： @@ -549,9 +550,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- 啟用廣域網域時，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` 在該處也維持選用。 diff --git a/docs/zh-TW/cli/plugins.md b/docs/zh-TW/cli/plugins.md index 003c5f4b4..85f94ca13 100644 --- a/docs/zh-TW/cli/plugins.md +++ b/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。 - - 安裝、啟用與疑難排解 Plugin 的終端使用者指南。 + + 給終端使用者的 Plugin 安裝、啟用與疑難排解指南。 - + 安裝、列出、更新、解除安裝與發布的快速範例。 - - 套件組相容性模型。 + + Bundle 相容性模型。 - 資訊清單欄位與設定結構描述。 + Manifest 欄位與設定 schema。 - - Plugin 安裝的安全強化。 + + Plugin 安裝的安全性強化。 @@ -62,14 +62,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --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)。 -隨附的 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。 ### 安裝 @@ -91,93 +91,93 @@ openclaw plugins install --marketplace https://github.com// -在啟動切換期間，裸套件名稱預設會從 npm 安裝。ClawHub 請使用 `clawhub:`。請將 Plugin 安裝視同執行程式碼。建議使用釘選版本。 +在啟動切換期間，裸套件名稱預設會從 npm 安裝。ClawHub 請使用 `clawhub:`。請像執行程式碼一樣看待 Plugin 安裝。建議優先使用釘選版本。 -`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`。 -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`。 - - 如果你的 `plugins` 區段由單一檔案 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會寫入該被包含的檔案，並保持 `openclaw.json` 不變。根層包含、包含陣列，以及帶有同層覆寫的包含都會封閉失敗，而不是攤平成單一內容。支援的形狀請參閱[設定包含](/zh-TW/gateway/configuration)。 + + 如果你的 `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 復原路徑。 - - `--force` 會重用現有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件包。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm 成品重新安裝相同 id 時使用。對於已追蹤的 npm Plugin 的例行升級，建議使用 `openclaw plugins update `。 + + `--force` 會重用既有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm artifact 重新安裝相同 id 時使用它。對於已追蹤 npm Plugin 的例行升級，建議使用 `openclaw plugins update `。 - 如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並指引你使用 `plugins update ` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時，使用 `plugins install --force`。 + 如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並引導你使用 `plugins update ` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時使用 `plugins install --force`。 - - `--pin` 只適用於 npm 安裝。不支援搭配 `git:` 安裝；若你想要釘選來源，請使用明確的 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它也不支援搭配 `--marketplace`，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm 規格。 + + `--pin` 只適用於 npm 安裝。不支援與 `git:` 安裝搭配；如果你想要釘選來源，請使用明確的 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它也不支援與 `--marketplace` 搭配，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm spec。 - `--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) 中的發布者步驟。 - - `plugins install` 也是安裝 hook 套件包的介面，這些套件包會在 `package.json` 中公開 `openclaw.hooks`。請使用 `openclaw hooks` 取得篩選後的 hook 可見性與個別 hook 啟用狀態，而不是用於套件安裝。 + + `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:`。在啟動切換期間，裸套件規格也會直接從 npm 安裝。 + 當你想明確使用 npm 解析時，請使用 `npm:`。在啟動切換期間，裸套件 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`）。 - 使用 `git:` 可直接從 git 儲存庫安裝。支援的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URL。加入 `@` 或 `#` 可在安裝前取出分支、標籤或 commit。 + 使用 `git:` 直接從 git repository 安裝。支援的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URLs。加入 `@` 或 `#` 可在安裝前 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 --runtime --json` 驗證執行階段註冊，例如 gateway 方法與 CLI 命令。如果 Plugin 使用 `api.registerCli` 註冊了 CLI 根命令，請透過 OpenClaw 根 CLI 直接執行該命令，例如 `openclaw demo-plugin ping`。 + 從 git 安裝後，請使用 `openclaw plugins inspect --runtime --json` 驗證 runtime 註冊，例如 gateway methods 與 CLI commands。如果該 Plugin 使用 `api.registerCli` 註冊了 CLI root，請直接透過 OpenClaw root CLI 執行該命令，例如 `openclaw demo-plugin ping`。 - - 支援的封存檔：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin 封存檔必須在解壓後的 Plugin 根目錄包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。 + + 支援的封存檔：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin 封存檔必須在解壓後的 Plugin root 包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。 也支援 Claude marketplace 安裝。 -ClawHub 安裝會使用明確的 `clawhub:` 定位器： +ClawHub 安裝使用明確的 `clawhub:` 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 @@ -195,27 +195,27 @@ openclaw plugins install --marketplace ./my-marketplace - - 來自 `~/.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 - 對於從 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 來源。 對於本機路徑與封存檔，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`) -相容套件組合會安裝到一般 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 中，但尚未接入執行階段執行。 ### 列出 @@ -234,56 +234,56 @@ openclaw plugins search --json 只顯示已啟用的 plugins。 - 從表格檢視切換為每個 Plugin 的詳細行，包含來源/起源/版本/啟用中繼資料。 + 從表格檢視切換為每個 plugin 的詳細行，包含 source/origin/version/activation metadata。 - 機器可讀的清單，加上 registry 診斷與套件相依安裝狀態。 + 機器可讀取的 inventory，加上 registry diagnostics 與 package dependency install state。 -`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。 -`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:`。 -若要在封裝的 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 --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..hooks.allowConversationAccess=true`。 +- `openclaw plugins inspect --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..hooks.allowConversationAccess=true`。 -使用 `--link` 可避免複製本機目錄（會加入 `plugins.load.paths`）： +使用 `--link` 以避免複製本機目錄（會加入 `plugins.load.paths`）： ```bash openclaw plugins install -l ./my-plugin ``` -`--force` 不支援與 `--link` 搭配使用，因為連結式安裝會重用來源路徑，而不是覆寫受管理的安裝目標。 +`--force` 不支援與 `--link` 搭配使用，因為 linked installs 會重用來源路徑，而不是覆寫受管理的安裝目標。 -在 npm 安裝上使用 `--pin`，可將解析出的精確 spec（`name@version`）儲存在受管理的 Plugin 索引中，同時保留預設的未釘選行為。 +在 npm installs 上使用 `--pin`，可在受管理的 plugin index 中儲存已解析的精確 spec (`name@version`)，同時保持預設行為為未釘選。 -### 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 --dry-run openclaw plugins uninstall --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`。 -`--keep-config` 支援作為 `--keep-files` 的已棄用別名。 +`--keep-config` 支援作為 `--keep-files` 的 deprecated alias。 ### 更新 @@ -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。 - 當你傳入 Plugin id 時，OpenClaw 會重用該 Plugin 記錄的安裝 spec。這表示先前儲存的 dist-tags（例如 `@beta`）與精確釘選版本，會在之後的 `update ` 執行中繼續使用。 + 當你傳入 plugin id 時，OpenClaw 會重用該 plugin 記錄的 install spec。這表示先前儲存的 dist-tags，例如 `@beta`，以及精確釘選版本，會在後續 `update ` 執行時繼續使用。 - 對於 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 預設發行線時，請使用此方式。 - `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。 - 在即時 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。 - `--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。 @@ -343,21 +343,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --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 ...` 執行它；例如，註冊 `demo-git` 的 Plugin 可用 `openclaw demo-git ping` 驗證。 +Plugin 擁有的 CLI commands 會安裝為根層級 `openclaw` command groups。在 `inspect --runtime` 顯示 `cliCommands` 下的 command 後，請以 `openclaw ...` 執行它；例如，註冊 `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。 -`--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。 ### 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.` 或 `plugins.allow` config。 +如果已設定的 plugin 存在於磁碟上，但被 loader 的 path-safety checks 阻擋，config validation 會保留 plugin 項目，並將其回報為 `present but blocked`。請修正前面的 blocked-plugin diagnostic，例如 path ownership 或 world-writable permissions，而不是移除 `plugins.entries.` 或 `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 會移除該過期套件並重新建置登錄檔，讓啟動時能根據內建資訊清單進行驗證。 -`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 後援僅用於遷移推出期間的緊急啟動復原。 ### 市集 @@ -397,7 +397,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -市集清單接受本機市集路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。`--json` 會印出解析後的來源標籤，以及剖析後的市集資訊清單與 Plugin 項目。 +市集列表接受本機市集路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub 儲存庫 URL，或 git URL。`--json` 會輸出已解析的來源標籤，以及已剖析的市集資訊清單與 Plugin 項目。 ## 相關 diff --git a/docs/zh-TW/cli/sessions.md b/docs/zh-TW/cli/sessions.md index 515c6ed8a..9540e1b62 100644 --- a/docs/zh-TW/cli/sessions.md +++ b/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 ` 以取得較小/較大的視窗，或在你刻意 +需要完整儲存區時使用 `--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 `：一個已設定的代理程式儲存區 -- `--all-agents`：彙總所有已設定的代理程式儲存區 +- `--agent `：一個已設定的代理儲存區 +- `--all-agents`：彙總所有已設定的代理儲存區 - `--store `：明確的儲存區路徑（不能與 `--agent` 或 `--all-agents` 合併使用） +- `--limit `：要輸出的最大資料列數（預設 `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/.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/.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 `：保護特定作用中金鑰，避免因磁碟預算而遭到淘汰。持久的外部對話指標，例如群組工作階段和執行緒範圍聊天工作階段，也會由年齡/數量/磁碟預算維護保留。 -- `--agent `：為一個已設定的代理程式儲存區執行清理。 -- `--all-agents`：為所有已設定的代理程式儲存區執行清理。 +- `--fix-missing`：移除其轉錄稿檔案遺失的項目，即使它們通常尚未因存留時間/數量而淘汰。 +- `--active-key `：保護特定作用中金鑰不受磁碟預算逐出。耐久的外部對話指標，例如群組工作階段和執行緒範圍的聊天工作階段，也會在依存留時間/數量/磁碟預算進行維護時保留。 +- `--agent `：針對一個已設定的代理儲存區執行清理。 +- `--all-agents`：針對所有已設定的代理儲存區執行清理。 - `--store `：針對特定 `sessions.json` 檔案執行。 -- `--json`：列印 JSON 摘要。使用 `--all-agents` 時，輸出會包含每個儲存區的一份摘要。 +- `--json`：列印 JSON 摘要。搭配 `--all-agents` 時，輸出會包含每個儲存區的一份摘要。 -當 Gateway 可連線時，針對已設定代理程式儲存區的非 dry-run 清理會透過 Gateway 傳送，因此會與執行階段流量共用相同的工作階段儲存區寫入器。使用 `--store ` 可對儲存區檔案進行明確的離線修復。 +當 Gateway 可連線時，已設定代理儲存區的非 dry-run 清理會 +透過 Gateway 傳送，因此它會與執行階段流量共用相同的工作階段儲存區寫入器。 +使用 `--store ` 可明確離線修復儲存區檔案。 `openclaw sessions cleanup --all-agents --dry-run --json`： diff --git a/docs/zh-TW/cli/update.md b/docs/zh-TW/cli/update.md index 9626784b4..c5f22cb61 100644 --- a/docs/zh-TW/cli/update.md +++ b/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 `：設定更新頻道（git + npm；會保存至設定）。 -- `--tag `：僅針對本次更新覆寫套件目標。對於套件安裝，`main` 會對應到 `github:openclaw/openclaw#main`。 -- `--dry-run`：預覽規劃的更新動作（頻道/標籤/目標/重新啟動流程），不寫入設定、不安裝、不同步 Plugin，也不重新啟動。 -- `--json`：輸出機器可讀的 `UpdateRunResult` JSON，包括 - 在更新後 Plugin 同步期間偵測到 npm Plugin 成品漂移時的 +- `--no-restart`：成功更新後略過重新啟動 Gateway 服務。會重新啟動 Gateway 的套件管理器更新，會先驗證重新啟動的服務回報預期的更新版本，命令才會成功。 +- `--channel `：設定更新通道（git + npm；會持久化到設定）。 +- `--tag `：僅針對這次更新覆寫套件目標。對於套件安裝，`main` 會對應到 `github:openclaw/openclaw#main`。 +- `--dry-run`：預覽預計的更新動作（通道/標籤/目標/重新啟動流程），不寫入設定、不安裝、不同步 plugins，也不重新啟動。 +- `--json`：列印機器可讀的 `UpdateRunResult` JSON，包括 + 在更新後 plugin 同步期間偵測到 npm plugin 成品漂移時的 `postUpdate.plugins.integrityDrifts`。 -- `--timeout `：每個步驟的逾時時間（預設為 1800s）。 -- `--yes`：略過確認提示（例如降版確認）。 +- `--timeout `：每個步驟的逾時時間（預設為 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)。 -降版需要確認，因為較舊版本可能會破壞設定。 +降級需要確認，因為較舊版本可能會破壞設定。 ## `update status` -顯示作用中的更新頻道 + git 標籤/分支/SHA（適用於來源 checkout），以及更新可用性。 +顯示目前作用中的更新通道 + git 標籤/分支/SHA（對原始碼 checkout 而言），以及更新可用性。 ```bash openclaw update status @@ -74,14 +74,14 @@ openclaw update status --timeout 10 選項： -- `--json`：輸出機器可讀的狀態 JSON。 -- `--timeout `：檢查逾時時間（預設為 3s）。 +- `--json`：列印機器可讀的狀態 JSON。 +- `--timeout `：檢查的逾時時間（預設為 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 請 要求沒有未提交的變更。 - - 切換到所選頻道（標籤或分支）。 + + 切換到所選通道（標籤或分支）。 僅限 dev。 - 在暫時 worktree 中執行 lint 與 TypeScript 建置。如果 tip 失敗，會往回最多 10 個 commit，尋找最新的乾淨建置。 + 在暫存 worktree 中執行 lint 與 TypeScript 建置。如果 tip 失敗，會往回最多 10 個 commit，以尋找最新的乾淨建置。 Rebase 到所選 commit（僅限 dev）。 - 使用 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`。 建置 gateway 與 Control UI。 - `openclaw doctor` 會作為最後的安全更新檢查執行。 + `openclaw doctor` 會作為最終安全更新檢查執行。 - - 將 Plugin 同步到作用中的頻道。Dev 使用內建 Plugin；stable 與 beta 使用 npm。更新已追蹤的 Plugin 安裝。 + + 將 plugins 同步到作用中的通道。Dev 使用隨附 plugins；stable 與 beta 使用 npm。更新已追蹤的 plugin 安裝。 -在 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 也會回退。 +精確版本與明確標籤不會被改寫。 -如果精確釘選的 npm Plugin 更新解析到其完整性與儲存安裝記錄不同的成品，`openclaw update` 會中止該 Plugin 成品更新，而不是安裝它。只有在確認你信任新成品後，才明確重新安裝或更新該 Plugin。 +如果精確釘選的 npm plugin 更新解析到的成品，其完整性與儲存的安裝記錄不同，`openclaw update` 會中止該 plugin 成品更新，而不是安裝它。只有在驗證你信任新成品後，才明確重新安裝或更新該 plugin。 -更新後 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`。 ## `--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) diff --git a/docs/zh-TW/concepts/models.md b/docs/zh-TW/concepts/models.md index a7e30caf5..fbbb910a7 100644 --- a/docs/zh-TW/concepts/models.md +++ b/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 --- - Auth 設定檔輪替、冷卻時間，以及這些如何與備援互動。 + Auth 設定檔輪替、冷卻時間，以及這如何與備援互動。 - - 供應商快速概覽與範例。 + + 快速的提供者概覽和範例。 - - PI、Codex，以及其他 agent 迴圈執行階段。 + + PI、Codex 和其他代理迴圈執行階段。 模型設定鍵。 -模型參照會選擇供應商和模型。它們通常不會選擇低階 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 會依照下列順序選擇模型： @@ -43,50 +43,50 @@ OpenClaw 會依下列順序選擇模型： `agents.defaults.model.fallbacks`（依序）。 - - Auth 容錯移轉會先在供應商內發生，然後才移至下一個模型。 + + Auth 容錯移轉會在移至下一個模型之前，於提供者內部發生。 - `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)）。 ## 選擇來源與備援行為 -同一個 `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` 的自訂提供者） -模型參照會正規化為小寫。像 `z.ai/*` 這類供應商別名會正規化為 `zai/*`。 +模型 ref 會正規化為小寫。像 `z.ai/*` 這類提供者別名會正規化為 `zai/*`。 -供應商設定範例（包括 OpenCode）位於 [OpenCode](/zh-TW/providers/opencode)。 +提供者設定範例（包括 OpenCode）位於 [OpenCode](/zh-TW/providers/opencode)。 ### 安全的允許清單編輯 @@ -113,35 +113,38 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json ``` - - `openclaw config set` 會保護模型/供應商對應表，避免意外覆寫。對 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 的一般物件指派，若會移除既有項目就會遭拒。請使用 `--merge` 進行加法變更；只有在提供的值應成為完整目標值時才使用 `--replace`。 + + `openclaw config set` 會保護模型/提供者映射，避免意外覆蓋。對 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 進行一般物件指派時，如果會移除現有項目，就會遭到拒絕。加法變更請使用 `--merge`；只有在提供的值應成為完整目標值時才使用 `--replace`。 - 互動式供應商設定和 `openclaw configure --section model` 也會將供應商範圍的選擇合併到既有允許清單中，因此新增 Codex、Ollama 或其他供應商不會移除不相關的模型項目。重新套用供應商 auth 時，configure 會保留既有的 `agents.defaults.model.primary`。明確設定預設值的命令，例如 `openclaw models auth login --provider --set-default` 和 `openclaw models set `，仍會取代 `agents.defaults.model.primary`。 + 互動式提供者設定和 `openclaw configure --section model` 也會將提供者範圍的選擇合併到現有允許清單，因此新增 Codex、Ollama 或其他提供者不會移除不相關的模型項目。重新套用提供者 Auth 時，Configure 會保留現有的 `agents.defaults.model.primary`。明確設定預設值的命令，例如 `openclaw models auth login --provider --set-default` 和 `openclaw models set `，仍會取代 `agents.defaults.model.primary`。 -## 「不允許使用模型」（以及回覆停止的原因） +## 「模型不被允許」（以及回覆停止的原因） -如果設定了 `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 to list models. +Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` -這會在一般回覆產生**之前**發生，因此訊息可能感覺像是「沒有回應」。修正方式是擇一： +這會在產生一般回覆**之前**發生，因此訊息可能感覺像是「沒有回應」。修正方式是下列其中之一： -- 將模型加入 `agents.defaults.models`，或 +- 將模型新增到 `agents.defaults.models`，或 - 清除允許清單（移除 `agents.defaults.models`），或 - 從 `/model list` 選擇模型。 -對於本機/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/model。 -當允許清單啟用時，僅有本機檔名或顯示名稱並不足夠。 +`openclaw models list --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. - - `/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 <#>` 會從該選擇器中選取。 - - - `/model` 會立即持久化新的工作階段選擇。 - - 如果 agent 閒置，下一次執行會立刻使用新模型。 - - 如果已有執行中的工作，OpenClaw 會將即時切換標記為待處理，並只會在乾淨的重試點重新啟動至新模型。 - - 如果工具活動或回覆輸出已經開始，待處理切換可能會排隊到稍後的重試機會或下一個使用者回合。 - - 使用者選擇的 `/model` 參照對該工作階段是嚴格的：如果所選供應商/模型無法存取，回覆會明確失敗，而不是靜默地從 `agents.defaults.model.fallbacks` 回答。這不同於已設定的預設值和 cron 工作主要模型，後兩者仍可使用備援鏈。 - - `/model status` 是詳細檢視（auth 候選，以及設定時的供應商端點 `baseUrl` + `api` 模式）。 + + - `/model` 會立即保存新的工作階段選擇。 + - 如果代理閒置，下一次執行會立刻使用新模型。 + - 如果已有執行正在進行，OpenClaw 會將即時切換標記為待處理，並只會在乾淨的重試點重新啟動到新模型。 + - 如果工具活動或回覆輸出已經開始，待處理的切換可能會保持佇列狀態，直到稍後的重試機會或下一個使用者回合。 + - 使用者選取的 `/model` ref 對該工作階段是嚴格的：如果選取的提供者/模型無法連線，回覆會明確失敗，而不是默默從 `agents.defaults.model.fallbacks` 回答。這不同於已設定的預設值和 cron 工作主要模型，後者仍可使用備援鏈。 + - `/model status` 是詳細檢視（Auth 候選項，以及設定時的提供者端點 `baseUrl` + `api` 模式）。 - - - 模型參照會依**第一個** `/` 分割來解析。輸入 `/model ` 時請使用 `provider/model`。 - - 如果模型 ID 本身包含 `/`（OpenRouter 風格），你必須包含供應商前綴（範例：`/model openrouter/moonshotai/kimi-k2`）。 - - 如果省略供應商，OpenClaw 會依下列順序解析輸入： - 1. 別名符合 - 2. 對該精確未加前綴模型 id 的唯一已設定供應商符合 - 3. 已棄用的備援：退回到已設定的預設供應商 — 如果該供應商不再公開已設定的預設模型，OpenClaw 會改為退回到第一個已設定的供應商/模型，以避免暴露過期的已移除供應商預設值。 + + - 模型 ref 會透過**第一個** `/` 分割來解析。輸入 `/model ` 時請使用 `provider/model`。 + - 如果模型 ID 本身包含 `/`（OpenRouter 風格），你必須包含提供者前綴（範例：`/model openrouter/moonshotai/kimi-k2`）。 + - 如果省略提供者，OpenClaw 會依下列順序解析輸入： + 1. 別名相符 + 2. 該確切未加前綴模型 ID 的唯一已設定提供者相符 + 3. 已淘汰的退回到已設定預設提供者 — 如果該提供者不再公開已設定的預設模型，OpenClaw 會改為退回到第一個已設定的 provider/model，以避免顯示過時的已移除提供者預設值。 @@ -222,14 +225,14 @@ openclaw models image-fallbacks remove openclaw models image-fallbacks clear ``` -`openclaw models`（無子命令）是 `models status` 的捷徑。 +`openclaw models`（沒有子命令）是 `models status` 的捷徑。 ### `models list` -預設顯示已設定/可用 auth 的模型。實用旗標： +預設顯示已設定／可用驗證的模型。實用旗標： - 完整目錄。包含在設定驗證前由內建提供者擁有的靜態目錄列，因此僅供探索的檢視可以顯示在你加入相符提供者憑證前不可用的模型。 + 完整目錄。包含在設定驗證之前由內建提供者擁有的靜態目錄列，因此僅供探索的檢視可以顯示在新增相符提供者憑證之前無法使用的模型。 僅限本機提供者。 @@ -246,21 +249,21 @@ openclaw models image-fallbacks clear ### `models status` -顯示解析後的主要模型、備援、影像模型，以及已設定提供者的驗證概覽。它也會顯示驗證儲存區中找到的設定檔 OAuth 到期狀態（預設會在 24 小時內發出警告）。`--plain` 只會列印解析後的主要模型。 +顯示解析後的主要模型、備用模型、影像模型，以及已設定提供者的驗證概覽。它也會揭露驗證儲存區中找到的設定檔 OAuth 到期狀態（預設會在 24 小時內發出警告）。`--plain` 只會列印解析後的主要模型。 - - - OAuth 狀態一律會顯示（並包含在 `--json` 輸出中）。如果已設定的提供者沒有憑證，`models status` 會列印 **缺少驗證** 區段。 - - JSON 包含 `auth.oauth`（警告時間範圍 + 設定檔）和 `auth.providers`（每個提供者的有效驗證，包括由環境支援的憑證）。`auth.oauth` 只代表驗證儲存區設定檔健康狀態；僅使用環境的提供者不會出現在其中。 - - 自動化請使用 `--check`（缺少/已到期時結束碼為 `1`，即將到期時為 `2`）。 - - 使用 `--probe` 進行即時驗證檢查；探測列可來自驗證設定檔、環境憑證或 `models.json`。 - - 如果明確的 `auth.order.` 省略了已儲存的設定檔，探測會回報 `excluded_by_auth_order`，而不是嘗試使用它。如果驗證存在，但無法為該提供者解析出可探測的模型，探測會回報 `status: no_model`。 + + - OAuth 狀態一律顯示（也包含在 `--json` 輸出中）。如果已設定的提供者沒有憑證，`models status` 會列印 **Missing auth** 區段。 + - JSON 包含 `auth.oauth`（警告視窗 + 設定檔）和 `auth.providers`（每個提供者的有效驗證，包括由環境支援的憑證）。`auth.oauth` 僅是驗證儲存區設定檔健康狀態；僅使用環境變數的提供者不會出現在其中。 + - 將 `--check` 用於自動化（缺少／已到期時結束碼為 `1`，即將到期時為 `2`）。 + - 將 `--probe` 用於即時驗證檢查；探測列可來自驗證設定檔、環境憑證或 `models.json`。 + - 如果明確的 `auth.order.` 省略已儲存的設定檔，探測會回報 `excluded_by_auth_order`，而不是嘗試它。如果驗證存在，但無法為該提供者解析出可探測的模型，探測會回報 `status: no_model`。 -驗證選擇取決於提供者/帳戶。對於常駐 Gateway 主機，API 金鑰通常最可預期；也支援 Claude CLI 重用，以及既有的 Anthropic OAuth/token 設定檔。 +驗證選擇取決於提供者／帳戶。對於常駐 Gateway 主機，API 金鑰通常最可預測；也支援重用 Claude CLI 以及現有 Anthropic OAuth／權杖設定檔。 範例（Claude CLI）： @@ -272,22 +275,22 @@ openclaw models status ## 掃描（OpenRouter 免費模型） -`openclaw models scan` 會檢查 OpenRouter 的**免費模型目錄**，並可選擇性探測模型是否支援工具和影像。 +`openclaw models scan` 會檢查 OpenRouter 的**免費模型目錄**，並可選擇性地探測模型是否支援工具和影像。 - 跳過即時探測（僅中繼資料）。 + 略過即時探測（僅中繼資料）。 - 最小參數規模（十億）。 + 最小參數大小（十億）。 - 跳過較舊的模型。 + 略過較舊的模型。 提供者前綴篩選器。 - 備援清單大小。 + 備用清單大小。 將 `agents.defaults.model.primary` 設為第一個選項。 @@ -297,7 +300,7 @@ openclaw models status -OpenRouter `/models` 目錄是公開的，因此僅中繼資料掃描可以在沒有金鑰的情況下列出免費候選項。探測與推論仍需要 OpenRouter API 金鑰（來自驗證設定檔或 `OPENROUTER_API_KEY`）。如果沒有可用金鑰，`openclaw models scan` 會退回僅中繼資料輸出，並保持設定不變。使用 `--no-probe` 可明確要求僅中繼資料模式。 +OpenRouter `/models` 目錄是公開的，因此僅中繼資料掃描可以在沒有金鑰的情況下列出免費候選項目。探測和推論仍需要 OpenRouter API 金鑰（來自驗證設定檔或 `OPENROUTER_API_KEY`）。如果沒有可用金鑰，`openclaw models scan` 會退回為僅中繼資料輸出，並保持設定不變。使用 `--no-probe` 可明確要求僅中繼資料模式。 掃描結果排序依據： @@ -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//agent/models.json`）。除非 `models.mode` 設為 `replace`，否則此檔案預設會合併。 +`models.providers` 中的自訂提供者會寫入代理目錄下的 `models.json`（預設為 `~/.openclaw/agents//agent/models.json`）。除非 `models.mode` 設為 `replace`，否則預設會合併此檔案。 相符提供者 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`。 - 其他提供者欄位會從設定和正規化的目錄資料重新整理。 -標記持久化以來源為權威：OpenClaw 會寫入來自主動來源設定快照（解析前）的標記，而不是解析後的執行階段密鑰值。這適用於 OpenClaw 重新產生 `models.json` 的任何情況，包括 `openclaw agent` 等命令驅動路徑。 +標記持久化以來源為權威：OpenClaw 會從作用中的來源設定快照（解析前）寫入標記，而不是從解析後的執行階段祕密值寫入。這適用於 OpenClaw 重新產生 `models.json` 的所有情況，包括像 `openclaw agent` 這類由命令驅動的路徑。 ## 相關 -- [代理程式執行階段](/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) — 影片模型設定 diff --git a/docs/zh-TW/concepts/qa-e2e-automation.md b/docs/zh-TW/concepts/qa-e2e-automation.md index 764b71505..dc3fe204a 100644 --- a/docs/zh-TW/concepts/qa-e2e-automation.md +++ b/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 ` 下執行。許多命令有 `pnpm qa:*` 指令碼別名；兩種形式都支援。 +每個 QA 流程都在 `pnpm openclaw qa ` 下執行。許多都有 `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-/` 下寫入 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-/` 下寫入 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 `。使用 `--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 `。使用 `--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 ` 調整 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 ` 來調整 +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 ` | — | 只執行此情境。可重複。 | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | 寫入 reports/summary/observed messages 和 output log 的位置。相對路徑會依 `--repo-root` 解析。 | -| `--repo-root ` | `process.cwd()` | 從中立 cwd 呼叫時的 repository root。 | -| `--sut-account ` | `sut` | QA gateway config 內的暫時 account id。 | -| `--provider-mode ` | `live-frontier` | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可使用）。 | -| `--model ` / `--alt-model ` | provider 預設值 | 主要/替代 model refs。 | -| `--fast` | 關閉 | 支援時的 provider fast mode。 | -| `--credential-source ` | `env` | 請參閱 [Convex credential pool](#convex-credential-pool)。 | -| `--credential-role ` | CI 中為 `ci`，否則為 `maintainer` | `--credential-source convex` 時使用的角色。 | +| `--scenario ` | — | 只執行此情境。可重複指定。 | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | 報告、摘要、觀察到的訊息與輸出日誌寫入的位置。相對路徑會相對於 `--repo-root` 解析。 | +| `--repo-root ` | `process.cwd()` | 從中性 cwd 呼叫時的 repository root。 | +| `--sut-account ` | `sut` | QA Gateway config 內的臨時帳戶 id。 | +| `--provider-mode ` | `live-frontier` | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可使用）。 | +| `--model ` / `--alt-model ` | provider 預設值 | 主要/替代 model refs。 | +| `--fast` | 關閉 | provider 支援時的快速模式。 | +| `--credential-source ` | `env` | 請參閱 [Convex credential pool](#convex-credential-pool)。 | +| `--credential-role ` | 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//*.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 ` 如何掛載在共用 `qa` 根底下 -- Gateway 如何針對該傳輸進行設定 +- Gateway 如何針對該傳輸設定 - 如何檢查就緒狀態 -- 如何注入傳入事件 -- 如何觀察傳出訊息 -- 如何公開逐字稿與正規化傳輸狀態 +- 如何注入入站事件 +- 如何觀察出站訊息 +- 如何公開 transcript 與正規化傳輸狀態 - 如何執行傳輸支援的動作 -- 如何處理傳輸特定的重設或清理 +- 如何處理傳輸專用 reset 或 cleanup -新通道的最低採用門檻： +新頻道的最低採用門檻： -1. 讓 `qa-lab` 繼續作為共用 `qa` 根的擁有者。 -2. 在共用 `qa-lab` 主機銜接面上實作傳輸執行器。 -3. 將傳輸特定機制保留在執行器 Plugin 或通道 harness 內。 -4. 將執行器掛載為 `openclaw qa `，而不是註冊競爭性的根命令。執行器 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 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=` 內嵌覆寫特定候選。 -`--thinking ` 仍會設定全域 fallback，而較舊的 +`--thinking ` 仍會設定全域後援，而較舊的 `--model-thinking ` 形式會保留以維持相容性。 -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) diff --git a/docs/zh-TW/gateway/config-tools.md b/docs/zh-TW/gateway/config-tools.md index fc1f6127a..fb078d0ae 100644 --- a/docs/zh-TW/gateway/config-tools.md +++ b/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` 之前設定基礎允許清單： -本機 onboarding 會在未設定時，將新的本機設定預設為 `tools.profile: "coding"`（既有的明確設定檔會保留）。 +本機初始設定會在未設定時，將新的本機設定預設為 `tools.profile: "coding"`（既有的明確設定檔會保留）。 | 設定檔 | 包含 | @@ -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: ``` - 保留用於迴圈分析的最大工具呼叫歷史。 + 保留用於迴圈分析的最大工具呼叫記錄。 - 發出警告的重複無進展模式閾值。 + 重複無進展模式的警告閾值。 - 封鎖嚴重迴圈的較高重複閾值。 + 用於封鎖嚴重迴圈的較高重複閾值。 - 任何無進展執行的硬停止閾值。 + 任何無進展執行的硬性停止閾值。 - 對重複的相同工具/相同參數呼叫發出警告。 + 對重複的相同工具/相同引數呼叫發出警告。 - 對已知輪詢工具（`process.poll`、`command_status` 等）的情況發出警告/封鎖。 + 對已知輪詢工具（`process.poll`、`command_status` 等）發出警告/封鎖。 對交替無進展的成對模式發出警告/封鎖。 @@ -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: ``` - - **提供者項目**（`type: "provider"` 或省略）： + + **供應商項目**（`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`：已淘汰的相容性旗標。已完成的非同步媒體任務會維持由請求者工作階段居中處理，讓代理收到結果、決定如何告知使用者，並在來源傳遞需要時使用訊息工具。 @@ -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: ``` - - - `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`。 + + - `self`：僅目前工作階段金鑰。 + - `tree`：目前工作階段 + 由目前工作階段衍生的工作階段（子代理）。 + - `agent`：屬於目前代理 ID 的任何工作階段（如果你在同一個代理 ID 下依傳送者執行工作階段，可能包含其他使用者）。 + - `all`：任何工作階段。跨代理指定目標仍需要 `tools.agentToAgent`。 + - 沙箱限制：當目前工作階段在沙箱中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 時，即使 `tools.sessions.visibility="all"`，可見性也會強制為 `tree`。 @@ -336,13 +336,13 @@ x-i18n: ``` - - - 附件僅支援 `runtime: "subagent"`。ACP runtime 會拒絕附件。 - - 檔案會實體化到子工作區的 `.openclaw/attachments//`，並包含 `.manifest.json`。 - - 附件內容會自動從逐字稿持久化中遮蔽。 - - Base64 輸入會以嚴格的字母表/填充檢查和解碼前大小防護進行驗證。 - - 檔案權限為：目錄 `0700`，檔案 `0600`。 - - 清理會遵循 `cleanup` 政策：`delete` 一律移除附件；`keep` 只有在 `retainOnSessionKeep: true` 時才保留附件。 + + - 附件僅支援 `runtime: "subagent"`。ACP 執行階段會拒絕它們。 + - 檔案會具體化到子工作區的 `.openclaw/attachments//`，並帶有 `.manifest.json`。 + - 附件內容會自動從轉錄持久化中遮蔽。 + - Base64 輸入會使用嚴格的字母表/填充檢查，以及解碼前大小保護進行驗證。 + - 目錄的檔案權限為 `0700`，檔案的權限為 `0600`。 + - 清理會遵循 `cleanup` 政策：`delete` 一律移除附件；`keep` 只會在 `retainOnSessionKeep: true` 時保留附件。 @@ -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//agent/models.json` 新增自訂提供者。 +OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 加入自訂提供者。 ```json5 { @@ -424,84 +424,84 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~ ``` - + - 對自訂驗證需求使用 `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"`。 + - 標記持久化以來源為權威：標記會從作用中的來源設定快照（解析前）寫入，而不是從已解析的執行階段秘密值寫入。 -### 提供者欄位詳細資訊 +### 提供者欄位詳細資料 - + - `models.mode`：提供者目錄行為（`merge` 或 `replace`）。 - - `models.providers`：以提供者 ID 為鍵的自訂提供者對映。 - - 安全編輯：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 進行增量更新。除非傳入 `--replace`，否則 `config set` 會拒絕破壞性替換。 + - `models.providers`：以提供者 ID 為鍵的自訂提供者對應。 + - 安全編輯：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 進行附加更新。除非你傳入 `--replace`，否則 `config set` 會拒絕破壞性替換。 - - - `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/環境變數替換）。 + + - `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`：用於代理/租戶路由的額外靜態標頭。 - + `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`。 - + - `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` 陣列攤平成一般字串。 - - - `plugins.entries.amazon-bedrock.config.discovery`：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`：已探索模型的後援最大輸出權杖數。 -互動式自訂提供者導引會針對常見視覺模型 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` 可強制使用純文字中繼資料。 ### 提供者範例 - - 隨附的 `cerebras` 提供者 Plugin 可透過 `openclaw onboard --auth-choice cerebras-api-key` 設定此項。只有在覆寫預設值時才使用明確的提供者設定。 + + 內建的 `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`。 - + ```json5 { env: { KIMI_API_KEY: "sk-..." }, @@ -554,10 +554,10 @@ OpenClaw 使用內建模型目錄。透過設定中的 `models.providers` 或 `~ Anthropic 相容的內建提供者。捷徑：`openclaw onboard --auth-choice kimi-code-api-key`。 - - 請參閱[本機模型](/zh-TW/gateway/local-models)。簡短說明：在高階硬體上透過 LM Studio Responses API 執行大型本機模型；保留已合併的託管模型作為備援。 + + 請參閱[本機模型](/zh-TW/gateway/local-models)。摘要：在高階硬體上透過 LM Studio Responses API 執行大型本機模型；保留已合併的託管模型作為備援。 - + ```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`。 @@ -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。 @@ -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`。 - + ```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 覆寫的自訂提供者。 @@ -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) diff --git a/docs/zh-TW/gateway/configuration-reference.md b/docs/zh-TW/gateway/configuration-reference.md index 6be0d5134..2f6217e86 100644 --- a/docs/zh-TW/gateway/configuration-reference.md +++ b/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..enabled: false`：即使 skill 是 bundled/installed，也會停用它。 -- `entries..apiKey`：供宣告主要 env var 的 skills 使用的便利設定（純文字字串或 SecretRef 物件）。 +- `entries..enabled: false`：即使 skill 是內建隨附/已安裝，也會停用該 skill。 +- `entries..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`、`/.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..apiKey`：plugin 層級 API key 便利欄位（當 plugin 支援時）。 -- `plugins.entries..env`：plugin 範圍的 env var map。 -- `plugins.entries..hooks.allowPromptInjection`：為 `false` 時，核心會阻擋 `before_prompt_build`，並忽略 legacy `before_agent_start` 中會改變 prompt 的欄位，同時保留 legacy `modelOverride` 和 `providerOverride`。適用於原生 plugin hooks 與受支援 bundle 提供的 hook 目錄。 -- `plugins.entries..hooks.allowConversationAccess`：為 `true` 時，受信任的非 bundled plugins 可從型別化 hooks（例如 `llm_input`、`llm_output`、`before_agent_finalize` 與 `agent_end`）讀取原始對話內容。 -- `plugins.entries..subagent.allowModelOverride`：明確信任此 plugin 可為背景子代理執行要求逐次執行的 `provider` 與 `model` 覆寫。 -- `plugins.entries..subagent.allowedModels`：受信任子代理覆寫可用的標準 `provider/model` 目標選用 allowlist。只有在你刻意想允許任何模型時才使用 `"*"`。 -- `plugins.entries..config`：plugin 定義的設定物件（可用時會由原生 OpenClaw plugin schema 驗證）。 -- 頻道 plugin 帳號/執行階段設定位於 `channels.` 下，並應由擁有該項目的 plugin manifest `channelConfigs` 中繼資料描述，而不是由中央 OpenClaw 選項 registry 描述。 +- `plugins.entries..env`：plugin 範圍的環境變數對應。 +- `plugins.entries..hooks.allowPromptInjection`：為 `false` 時，核心會封鎖 `before_prompt_build`，並忽略舊版 `before_agent_start` 中會變更提示的欄位，同時保留舊版 `modelOverride` 與 `providerOverride`。適用於原生 plugin hooks 與受支援的 bundle 提供 hook 目錄。 +- `plugins.entries..hooks.allowConversationAccess`：為 `true` 時，受信任的非內建 plugins 可從型別化 hooks（例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）讀取原始對話內容。 +- `plugins.entries..subagent.allowModelOverride`：明確信任此 plugin 可為背景 subagent 執行要求每次執行的 `provider` 與 `model` 覆寫。 +- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆寫可用的標準 `provider/model` 目標選用允許清單。只有在你有意允許任何模型時才使用 `"*"`。 +- `plugins.entries..config`：plugin 定義的設定物件（當可用時由原生 OpenClaw plugin schema 驗證）。 +- 頻道 plugin 帳號/執行階段設定位於 `channels.` 下，並應由擁有該設定的 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..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..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 } ``` - + -- `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..healthMonitor.enabled`：每個通道可選擇退出健康監控重啟，同時保留全域監控啟用。 -- `channels..accounts..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..healthMonitor.enabled`：針對單一通道退出健康監控重啟，同時保留全域監控啟用。 +- `channels..accounts..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 拒絕清單中移除工具名稱。 @@ -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 ` 或 `x-openclaw-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/` → 透過 `hooks.mappings` 解析 - - 由樣板渲染的 mapping `sessionKey` 值會被視為外部提供，也需要 `hooks.allowRequestSessionKey=true`。 + - 由範本轉譯的對應 `sessionKey` 值會被視為外部提供，也需要 `hooks.allowRequestSessionKey=true`。 - + -- `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（如果已設定模型目錄，必須允許該模型）。 ### 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://:/__openclaw__/canvas/` - `http://:/__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 } ``` -- 每個代理的設定檔會儲存在 `/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..mode = "oauth"`）不支援以 SecretRef 作為後盾的驗證設定檔憑證。 -- 靜態執行階段憑證來自記憶體中已解析的快照；發現舊版靜態 `auth.json` 項目時會將其清除。 +- 每個 agent 的設定檔會儲存在 `/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..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` 可移除未知鍵）。 @@ -1094,11 +1105,11 @@ CLI 引導式設定流程（`onboard`、`configure`、`doctor`）寫入的中繼 } ``` -- `sessionRetention`：在從 `sessions.json` 剪除前，已完成的隔離 Cron 執行工作階段要保留多久。也控制已封存且刪除的 Cron 逐字稿清理。預設：`24h`；設為 `false` 可停用。 -- `runLog.maxBytes`：剪除前每個執行記錄檔（`cron/runs/.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/.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 擁有的寫入是唯讀；這些寫入會關閉並失敗，而不是將設定扁平化。 +- 錯誤：針對檔案遺失、解析錯誤與循環包含提供清楚訊息。 --- diff --git a/docs/zh-TW/gateway/diagnostics.md b/docs/zh-TW/gateway/diagnostics.md index dcb029d0a..09f3c0fe6 100644 --- a/docs/zh-TW/gateway/diagnostics.md +++ b/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 ` 命令。該檢查工作流程請參閱 [Codex harness](/zh-TW/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)。 +這讓常見的 Codex 偵錯循環很短：在 Telegram、Discord 或其他頻道中 +注意到不良行為，執行 `/diagnostics`，核准一次，將回報分享給支援人員， +然後如果你想自行檢查原生 Codex 執行緒，就在本機執行列印出的 +`codex resume ` 命令。該檢查工作流程請參閱 +[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 `：寫入特定 zip 路徑。 -- `--log-lines `：要包含的最大清理後日誌行數。 -- `--log-bytes `：要檢查的最大日誌位元組數。 -- `--url `：用於狀態與健康狀態快照的 Gateway WebSocket URL。 -- `--token `：用於狀態與健康狀態快照的 Gateway 權杖。 -- `--password `：用於狀態與健康狀態快照的 Gateway 密碼。 -- `--timeout `：狀態與健康狀態快照逾時。 -- `--no-stability-bundle`：略過保存的穩定性套件查詢。 +- `--log-lines `：要包含的最大清理後記錄行數。 +- `--log-bytes `：要檢查的最大記錄位元組數。 +- `--url `：用於狀態與健康快照的 Gateway WebSocket URL。 +- `--token `：用於狀態與健康快照的 Gateway 權杖。 +- `--password `：用於狀態與健康快照的 Gateway 密碼。 +- `--timeout `：狀態與健康快照逾時。 +- `--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) — 將串流診斷傳送到收集器的獨立流程 diff --git a/docs/zh-TW/gateway/doctor.md b/docs/zh-TW/gateway/doctor.md index becb3bb44..f83511e6c 100644 --- a/docs/zh-TW/gateway/doctor.md +++ b/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 與自動化模式 +### 無介面與自動化模式 @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - 不提示就接受預設值（包含適用時的重新啟動/服務/沙盒修復步驟）。 + 不提示而接受預設值（適用時包括重新啟動/服務/沙箱修復步驟）。 @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - 不提示就套用建議的修復（安全時包含修復與重新啟動）。 + 不提示而套用建議修復（在安全情況下包含修復 + 重新啟動）。 @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 也套用更積極的修復（會覆寫自訂 supervisor 設定）。 + 也套用侵入性較高的修復（會覆寫自訂 supervisor 設定）。 @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - 在不提示的情況下執行，且只套用安全遷移（設定正規化 + 磁碟狀態搬移）。略過需要人工確認的重新啟動/服務/沙盒動作。偵測到舊版狀態遷移時會自動執行。 + 在不提示的情況下執行，且只套用安全遷移（設定正規化 + 磁碟上的狀態移動）。略過需要人工確認的重新啟動/服務/沙箱動作。偵測到舊版狀態遷移時會自動執行。 @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - 掃描系統服務以找出額外的 gateway 安裝（launchd/systemd/schtasks）。 + 掃描系統服務以尋找額外的 Gateway 安裝（launchd/systemd/schtasks）。 @@ -78,114 +78,114 @@ cat ~/.openclaw/openclaw.json - git 安裝的選用前置更新（僅限互動模式）。 - - UI 通訊協定新鮮度檢查（當通訊協定 schema 較新時重建 Control UI）。 - - 健康狀態檢查 + 重新啟動提示。 - - Skills 狀態摘要（符合資格/缺少/已封鎖）與 plugin 狀態。 + - UI 通訊協定新鮮度檢查（當通訊協定結構描述較新時重建 Control UI）。 + - 健康檢查 + 重新啟動提示。 + - Skills 狀態摘要（符合資格/缺少/被封鎖）與 Plugin 狀態。 - 舊版值的設定正規化。 - - Talk 設定從舊版扁平 `talk.*` 欄位遷移到 `talk.provider` + `talk.providers.`。 - - 舊版 Chrome 擴充功能設定與 Chrome MCP 就緒狀態的瀏覽器遷移檢查。 + - 將 Talk 設定從舊版扁平 `talk.*` 欄位遷移到 `talk.provider` + `talk.providers.`。 + - 針對舊版 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 參照會被視為惰性的隔離設定並保留。 - - 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`）。 - - - 啟用 sandboxing 時的 sandbox image 修復。 - - 舊版服務遷移與額外 gateway 偵測。 + + - 啟用沙箱時修復沙箱映像。 + - 舊版服務遷移與額外 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`）。 - - - 開放 DM 政策的安全性警告。 - - 本機 token 模式的 Gateway auth 檢查（沒有 token source 時提供 token 產生；不會覆寫 token SecretRef 設定）。 - - 裝置 pairing 問題偵測（待處理的首次 pair 請求、待處理的 role/scope 升級、過時的本機 device-token cache drift，以及 paired-record auth drift）。 + + - 開放 DM 政策的安全警告。 + - 本機 token 模式的 Gateway 驗證檢查（當不存在 token 來源時提供 token 產生；不會覆寫 token SecretRef 設定）。 + - 裝置配對問題偵測（待處理的首次配對要求、待處理的角色/範圍升級、過期本機 device-token 快取漂移，以及已配對記錄的驗證漂移）。 - + - 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。 -## 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` 作為檢閱介面。 -## 詳細行為與理由 +## 詳細行為與設計理由 - 如果這是 git checkout 且 doctor 正以互動方式執行，它會在執行 doctor 前提供更新（fetch/rebase/build）。 + 如果這是 git checkout 且 doctor 正在互動模式下執行，它會在執行 doctor 前提供更新（fetch/rebase/build）選項。 - 如果設定包含舊版值形狀（例如沒有 channel-specific override 的 `messages.ackReaction`），doctor 會將它們正規化為目前的 schema。 + 如果設定包含舊版值形狀（例如沒有 channel 特定覆寫的 `messages.ackReaction`），doctor 會將它們正規化為目前結構描述。 - 這包含舊版 Talk 扁平欄位。目前公開 Talk 設定是 `talk.provider` + `talk.providers.`。Doctor 會把舊的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形狀重寫到 provider map。 + 這包括舊版 Talk 扁平欄位。目前公開的 Talk 設定是 `talk.provider` + `talk.providers.`。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"` 設定。 - - 當設定包含已棄用的 keys 時，其他 commands 會拒絕執行，並要求你執行 `openclaw doctor`。 + + 當設定包含已棄用鍵時，其他命令會拒絕執行並要求你執行 `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..timeoutSeconds` + - 移除 `agents.defaults.llm`；對於緩慢的供應商/模型逾時，請使用 `models.providers..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..accounts` 項目，但未設定 `channels..defaultAccount` 或 `accounts.default`，doctor 會警告後援路由可能選到非預期的帳號。 - - 如果 `channels..defaultAccount` 設為未知的帳號 ID，doctor 會警告並列出已設定的帳號 ID。 + - 如果設定了兩個以上 `channels..accounts` 項目，但沒有 `channels..defaultAccount` 或 `accounts.default`，doctor 會警告後援路由可能挑選到非預期的帳號。 + - 如果 `channels..defaultAccount` 設為未知帳號 ID，doctor 會警告並列出已設定的帳號 ID。 - 如果你手動新增了 `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 路由與成本。 如果你的瀏覽器設定仍指向已移除的 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。 - 設定 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 健康，探測也會執行。 - 如果你先前在 `models.providers.openai-codex` 下新增了舊版 OpenAI 傳輸設定，它們可能會遮蔽較新版本自動使用的內建 Codex OAuth 供應商路徑。Doctor 看到這些舊傳輸設定與 Codex OAuth 並存時會警告，讓你可以移除或改寫過時的傳輸覆寫，取回內建的路由/後援行為。自訂代理和僅標頭覆寫仍受支援，且不會觸發此警告。 + 如果你先前在 `models.providers.openai-codex` 下加入舊版 OpenAI 傳輸設定，它們可能會遮蔽較新版本自動使用的內建 Codex OAuth 供應商路徑。當 Doctor 看到這些舊傳輸設定與 Codex OAuth 同時存在時會發出警告，讓你移除或重寫過時的傳輸覆寫，並取回內建路由/後援行為。仍支援自訂代理和僅標頭覆寫，且不會觸發此警告。 - 啟用隨附的 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 是有意設定時，請保持警告不變。 - - Doctor 可以將較舊的磁碟布局遷移到目前結構： + + 在你將已設定的預設/後援模型或執行階段從 Plugin 擁有的路由（例如 Codex）移開後，Doctor 也會掃描作用中的工作階段儲存區，尋找過時的自動建立路由狀態。 - - 工作階段儲存區 + 轉錄： + `openclaw doctor --fix` 可清除自動建立的過時狀態，例如 `modelOverrideSource: "auto"` 模型釘選、執行階段模型中繼資料、釘選的 harness ID、CLI 工作階段繫結，以及當其擁有路由已不再設定時的自動驗證設定檔覆寫。明確的使用者或舊版工作階段模型選擇會回報供手動檢閱並保持不變；當不再打算使用該路由時，請用 `/model ...`、`/new` 切換，或重設工作階段。 + + + + Doctor 可將較舊的磁碟配置遷移到目前結構： + + - 工作階段儲存區 + 逐字稿： - 從 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` - Agent 目錄： - 從 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` - WhatsApp 驗證狀態（Baileys）： - - 從舊版 `~/.openclaw/credentials/*.json`（除了 `oauth.json`） + - 從舊版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） - 到 `~/.openclaw/credentials/whatsapp//...`（預設帳號 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` 變更。 - 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` 鍵已經有相同值，舊版鍵會被移除，而不會複製資料。 - 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`。 - doctor 會掃描每個代理程式工作階段目錄中的過時寫入鎖定檔，也就是工作階段異常結束後遺留下來的檔案。對於找到的每個鎖定檔，它會回報：路徑、PID、該 PID 是否仍在執行、鎖定存在時間，以及是否被視為過時（PID 已死或超過 30 分鐘）。在 `--fix` / `--repair` 模式中，它會自動移除過時的鎖定檔；否則會列印一則提示，指示你使用 `--fix` 重新執行。 + Doctor 會掃描每個代理程式工作階段目錄，尋找過時的寫入鎖定檔案，也就是工作階段異常結束後遺留的檔案。對於找到的每個鎖定檔，它會回報：路徑、PID、PID 是否仍存活、鎖定存在時間，以及是否被視為過時（PID 已失效或超過 30 分鐘）。在 `--fix` / `--repair` 模式中，它會自動移除過時的鎖定檔；否則會列印提示，並指示你使用 `--fix` 重新執行。 - doctor 會掃描代理程式工作階段 JSONL 檔案，尋找由 2026.4.24 提示轉錄重寫錯誤所建立的重複分支形狀：一個被棄用的使用者回合包含 OpenClaw 內部執行階段內容，旁邊還有一個作用中的同層分支，含有相同的可見使用者提示。在 `--fix` / `--repair` 模式中，doctor 會在原始檔旁備份每個受影響的檔案，並將轉錄重寫為作用中的分支，使 gateway 歷程與記憶讀取器不再看到重複回合。 + Doctor 會掃描代理程式工作階段 JSONL 檔案，尋找 2026.4.24 提示轉錄重寫錯誤所建立的重複分支形狀：一個帶有 OpenClaw 內部執行階段內容的棄用使用者輪次，以及一個包含相同可見使用者提示的作用中同層項目。在 `--fix` / `--repair` 模式中，doctor 會在每個受影響檔案旁邊建立備份，然後將轉錄重寫到作用中分支，讓 Gateway 歷程與記憶讀取器不再看到重複輪次。 - 狀態目錄是作業上的腦幹。如果它消失，你會失去工作階段、憑證、日誌與設定（除非你在其他地方有備份）。 + 狀態目錄是操作核心。如果它消失，你會失去工作階段、憑證、記錄與設定（除非你在其他地方有備份）。 - 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` 的選項。 - 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 也會回報因下列原因暫時無法使用的驗證設定檔： - 短暫冷卻時間（速率限制/逾時/驗證失敗） - - 較長時間的停用（帳單/點數失敗） + - 較長停用（帳單/額度失敗） - - 如果已設定 `hooks.gmail.model`，doctor 會根據 catalog 與 allowlist 驗證模型參照，並在無法解析或不允許時發出警告。 + + 如果設定了 `hooks.gmail.model`，doctor 會根據目錄與允許清單驗證模型參照，並在它無法解析或不被允許時發出警告。 - - 啟用沙箱時，doctor 會檢查 Docker 映像，並在目前映像遺失時提供建置或切換到舊版名稱的選項。 + + 啟用沙盒時，doctor 會檢查 Docker 映像，並在目前映像遺失時提供建置或切換到舊名稱的選項。 - 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 工作。 - 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`。 - 當 Matrix 頻道帳戶有待處理或可執行的舊版狀態遷移時，doctor（在 `--fix` / `--repair` 模式中）會建立遷移前快照，然後執行 best-effort 遷移步驟：舊版 Matrix 狀態遷移與舊版加密狀態準備。這兩個步驟都不是致命錯誤；錯誤會被記錄，啟動會繼續。在唯讀模式（不帶 `--fix` 的 `openclaw doctor`）中，這項檢查會完全略過。 + 當 Matrix 頻道帳號有待處理或可採取動作的舊版狀態遷移時，doctor（在 `--fix` / `--repair` 模式中）會建立遷移前快照，然後執行盡力而為的遷移步驟：舊版 Matrix 狀態遷移與舊版加密狀態準備。兩個步驟都不是致命錯誤；錯誤會被記錄，而啟動會繼續。在唯讀模式（未帶 `--fix` 的 `openclaw doctor`）中，這項檢查會完全略過。 - doctor 現在會在一般健康檢查中檢查裝置配對狀態。 + Doctor 現在會將裝置配對狀態作為一般健康檢查的一部分進行檢查。 它會回報： - - 待處理的首次配對請求 - - 已配對裝置待處理的角色升級 - - 已配對裝置待處理的範圍升級 - - 裝置 id 仍相符但裝置身分已不再符合已核准記錄的公開金鑰不相符修復 - - 缺少已核准角色作用中 token 的已配對記錄 - - 範圍漂移到已核准配對基準之外的已配對 token - - 目前機器上的本機快取裝置 token 項目，其早於 gateway 端 token 輪替，或帶有過時的範圍中繼資料 + - 待處理的首次配對要求 + - 已配對裝置的待處理角色升級 + - 已配對裝置的待處理範圍升級 + - 裝置 ID 仍相符但裝置身分不再符合已核准記錄的公開金鑰不相符修復 + - 已配對記錄缺少核准角色的作用中權杖 + - 範圍偏離已核准配對基準線的已配對權杖 + - 目前機器上早於 Gateway 端權杖輪替或帶有過時範圍中繼資料的本機快取裝置權杖項目 - doctor 不會自動核准配對請求，也不會自動輪替裝置 token。它會改為列印精確的後續步驟： + Doctor 不會自動核准配對要求或自動輪替裝置權杖。它會改為列印確切的後續步驟： - - 使用 `openclaw devices list` 檢查待處理請求 - - 使用 `openclaw devices approve ` 核准精確請求 - - 使用 `openclaw devices rotate --device --role ` 輪替新的 token + - 使用 `openclaw devices list` 檢查待處理要求 + - 使用 `openclaw devices approve ` 核准確切要求 + - 使用 `openclaw devices rotate --device --role ` 輪替新權杖 - 使用 `openclaw devices remove ` 移除並重新核准過時記錄 - 這會補上常見的「已配對但仍然收到需要配對」缺口：doctor 現在會區分首次配對、待處理角色/範圍升級，以及過時 token/裝置身分漂移。 + 這修補了常見的「已配對但仍收到需要配對」漏洞：doctor 現在會區分首次配對、待處理角色/範圍升級，以及過時權杖/裝置身分漂移。 - 當 provider 對 DM 開放但沒有 allowlist，或 policy 以危險方式設定時，doctor 會發出警告。 + 當提供者對私訊開放但沒有允許清單，或政策以危險方式設定時，Doctor 會發出警告。 - 如果以 systemd 使用者服務執行，doctor 會確保已啟用 lingering，讓 gateway 在登出後仍保持執行。 + 如果以 systemd 使用者服務執行，doctor 會確保已啟用 lingering，讓 Gateway 在登出後仍保持運作。 - - doctor 會列印預設代理程式的工作區狀態摘要： + + 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 登錄在載入期間輸出的任何警告或錯誤。 - - doctor 會檢查工作區 bootstrap 檔案（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的內容檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始與注入字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及總注入字元數佔總預算的比例。當檔案被截斷或接近限制時，doctor 會列印調整 `agents.defaults.bootstrapMaxChars` 與 `agents.defaults.bootstrapTotalMaxChars` 的提示。 + + Doctor 會檢查工作區啟動檔案（例如 `AGENTS.md`、`CLAUDE.md`，或其他注入的內容檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始與注入字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及總注入字元佔總預算的比例。當檔案被截斷或接近限制時，doctor 會列印調整 `agents.defaults.bootstrapMaxChars` 與 `agents.defaults.bootstrapTotalMaxChars` 的提示。 - 當 `openclaw doctor --fix` 移除遺失的頻道 Plugin 時，它也會移除參照該 Plugin 的懸空頻道範圍 config：`channels.` 項目、命名該頻道的 Heartbeat targets，以及 `agents.*.models["/*"]` overrides。這能避免頻道 runtime 已消失但 config 仍要求 gateway 綁定到它所造成的 Gateway 啟動迴圈。 + 當 `openclaw doctor --fix` 移除遺失的頻道 Plugin 時，它也會移除參照該 Plugin 的懸空頻道範圍設定：`channels.` 項目、命名該頻道的 Heartbeat 目標，以及 `agents.*.models["/*"]` 覆寫。這會防止頻道執行階段已不存在但設定仍要求 Gateway 綁定到它而造成 Gateway 啟動迴圈。 - 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` 可手動重新產生快取。 - - doctor 會檢查本機 gateway token 驗證就緒狀態。 + + 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 時強制產生。 - - 某些修復流程需要檢查已設定的憑證，同時不削弱 runtime fail-fast 行為。 + + 某些修復流程需要檢查已設定的憑證，而不削弱執行階段快速失敗行為。 - - `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 缺失。 - Doctor 會執行健康檢查，並在 Gateway 看起來不健康時提議重新啟動 Gateway。 + Doctor 會執行健康檢查，並在 Gateway 看起來不健康時提議重新啟動。 - - Doctor 會檢查已設定的記憶體搜尋嵌入提供者是否已為預設代理程式就緒。行為取決於已設定的後端與提供者： + + 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` 在執行階段驗證嵌入就緒狀態。 如果 Gateway 健康，doctor 會執行通道狀態探測，並回報警告與建議修復方式。 - 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` 強制完整重寫。 - - Doctor 會檢查服務執行時（PID、上次結束狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查 Gateway 連接埠（預設 `18789`）上的連接埠衝突，並回報可能原因（Gateway 已在執行、SSH tunnel）。 + + Doctor 會檢查服務執行階段（PID、上次退出狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查 Gateway 連接埠（預設 `18789`）上的連接埠衝突，並回報可能原因（Gateway 已在執行、SSH 通道）。 - - 當 Gateway 服務在 Bun 或版本管理的 Node 路徑（`nvm`、`fnm`、`volta`、`asdf` 等）上執行時，Doctor 會發出警告。WhatsApp + Telegram 通道需要 Node，而版本管理器路徑在升級後可能失效，因為服務不會載入你的 shell init。Doctor 會在可用時提議遷移到系統 Node 安裝（Homebrew/apt/choco）。 + + 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。 Doctor 會持久化任何設定變更，並標記精靈中繼資料以記錄 doctor 執行。 - - Doctor 會在缺少時建議工作區記憶體系統，並在工作區尚未納入 git 時列印備份提示。 + + Doctor 會在缺少工作區記憶系統時提出建議，並在工作區尚未納入 git 管理時列印備份提示。 - 請參閱 [/concepts/agent-workspace](/zh-TW/concepts/agent-workspace)，取得工作區結構與 git 備份的完整指南（建議使用私有 GitHub 或 GitLab）。 + 請參閱 [/concepts/agent-workspace](/zh-TW/concepts/agent-workspace)，了解工作區結構與 git 備份的完整指南（建議使用私有 GitHub 或 GitLab）。 ## 相關 -- [Gateway runbook](/zh-TW/gateway) +- [Gateway 執行手冊](/zh-TW/gateway) - [Gateway 疑難排解](/zh-TW/gateway/troubleshooting) diff --git a/docs/zh-TW/gateway/logging.md b/docs/zh-TW/gateway/logging.md index 5a6213c8e..6bc65bb6d 100644 --- a/docs/zh-TW/gateway/logging.md +++ b/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) diff --git a/docs/zh-TW/help/debugging.md b/docs/zh-TW/help/debugging.md index 5eb2fa1fe..e94eecc80 100644 --- a/docs/zh-TW/help/debugging.md +++ b/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 `。 -當你想讓被基準測試的 child 跳過預設 `--force` port 清理，並在 Gateway port 已在使用中時快速失敗，請使用 -`--benchmark-no-force`。 +當你想將 profiles 放到其他位置時，請使用 `--benchmark-dir `。 +當你想讓 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 -## 原始串流記錄（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) diff --git a/docs/zh-TW/help/faq-models.md b/docs/zh-TW/help/faq-models.md index 5329f1dae..1d31b972f 100644 --- a/docs/zh-TW/help/faq-models.md +++ b/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)。 - ## 模型：預設值、選擇、別名、切換 + ## 模型：預設值、選取、別名、切換 @@ -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`。 **建議預設值：**使用你的提供者堆疊中可用的最強最新世代模型。 **對於啟用工具或不受信任輸入的代理：**優先考量模型能力，而不是成本。 - **對於例行/低風險聊天：**使用較便宜的備援模型，並依代理角色路由。 + **對於例行/低風險聊天：**使用較便宜的備用模型，並依代理角色路由。 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)。 - 使用**模型命令**，或只編輯**模型**欄位。避免完整替換設定。 + 使用**模型命令**，或只編輯**模型**欄位。避免完整取代設定。 安全選項： - - 聊天中的 `/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)。 - 可以。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/` + - `kimi-k2.5:cloud` 等雲端模型不需要本機拉取 + - 若要手動切換，請使用 `openclaw models list` 和 `openclaw models set ollama/` - 安全性注意事項：較小或高度量化的模型更容易受到提示 - 注入影響。對於任何可以使用工具的機器人，我們強烈建議使用**大型模型**。 - 如果你仍想使用小型模型，請啟用沙盒化與嚴格的工具允許清單。 + 安全性注意事項：較小或大量量化的模型更容易受到提示詞 + 注入影響。我們強烈建議任何可使用工具的機器人都使用**大型模型**。 + 如果你仍想使用小型模型，請啟用沙箱與嚴格的工具允許清單。 文件：[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)。 - 這些部署可能不同，且可能隨時間變更；沒有固定的提供者建議。 - 使用 `openclaw models status` 檢查每個 Gateway 上目前的執行階段設定。 - - 對於安全性敏感/啟用工具的代理，使用可用的最強最新世代模型。 + - 對於安全性敏感/啟用工具的代理，請使用可用的最強最新世代模型。 @@ -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 `）。 - 使用 `/model status` 確認哪個驗證設定檔處於作用中。 + 如果想回到預設值，請從 `/model` 中選擇它（或傳送 `/model `）。 + 使用 `/model status` 確認目前作用中的認證設定檔。 - - 可以。將模型選擇與執行階段選擇分開處理： + + 可以。請將模型選擇和執行階段選擇分開處理： - - **原生 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)。 使用工作階段切換或設定預設值： - - **每個工作階段：**當工作階段使用 `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)。 - - 如果設定了 `agents.defaults.models`，它會成為 `/model` 和任何 + + 如果設定了 `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 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` 命令。 - - 這表示**提供者尚未設定**（找不到 MiniMax 提供者設定或驗證 + + 這表示**尚未設定提供者**（找不到 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)。 - - 可以。將 **MiniMax 作為預設值**，並在需要時**依工作階段**切換模型。 - 備援是用於**錯誤**，不是用於「困難任務」，因此請使用 `/model` 或另一個代理。 + + 可以。使用 **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: - 是。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` - 如果你使用相同名稱設定自己的別名，會以你的值為準。 + 如果你用相同名稱設定自己的別名，會以你的值為準。 @@ -304,12 +307,12 @@ x-i18n: } ``` - 接著 `/model sonnet`（或在支援時使用 `/`）會解析到該模型 ID。 + 然後 `/model sonnet`（或支援時的 `/`）會解析為該模型 ID。 - - OpenRouter（按 token 付費；多種模型）： + + 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//agent/auth-profiles.json @@ -350,10 +353,10 @@ x-i18n: 修正選項： - 執行 `openclaw agents add `，並在精靈中設定驗證。 - - 或者只將可攜式靜態 `api_key` / `token` 設定檔，從主要代理程式的驗證儲存區複製到新代理程式的驗證儲存區。 - - 對於 OAuth 設定檔，當新代理程式需要自己的帳號時，請從新代理程式登入；否則 OpenClaw 可以讀取預設/主要代理程式，而不需要複製重新整理權杖。 + - 或者只將可攜式靜態 `api_key` / `token` 設定檔，從主要代理程式的驗證存放區複製到新代理程式的驗證存放區。 + - 對於 OAuth 設定檔，當新的代理程式需要自己的帳戶時，請從該新代理程式登入；否則 OpenClaw 可以讀取預設/主要代理程式，而不需要複製重新整理權杖。 - 請**不要**在代理程式之間重複使用 `agentDir`；這會造成驗證/工作階段衝突。 + 請**不要**在多個代理程式之間重複使用 `agentDir`；這會造成驗證/工作階段衝突。 @@ -362,145 +365,147 @@ x-i18n: - 容錯移轉分成兩個階段： + 容錯移轉分兩個階段進行： - 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.` 這樣的一般內部備援文字會保持保守，本身不會觸發模型備援。 - 這表示系統嘗試使用驗證設定檔 ID `anthropic:default`，但無法在預期的驗證儲存區中找到它的憑證。 + 這表示系統嘗試使用驗證設定檔 ID `anthropic:default`，但無法在預期的驗證存放區中找到其憑證。 **修正檢查清單：** - - **確認驗證設定檔所在位置**（新路徑與舊路徑） + - **確認驗證設定檔的位置**（新路徑與舊路徑） - 目前：`~/.openclaw/agents//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 機器上，而不是你的筆記型電腦上。 - - 如果你的模型設定包含 Google Gemini 作為備援（或你切換到 Gemini 簡寫），OpenClaw 會在模型備援期間嘗試它。如果你尚未設定 Google 憑證，就會看到 `No API key found for provider "google"`。 + + 如果你的模型設定包含 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`。 -## 驗證設定檔：它們是什麼以及如何管理 +## 驗證設定檔：它們是什麼，以及如何管理 -相關：[/concepts/oauth](/zh-TW/concepts/oauth)（OAuth 流程、權杖儲存、多帳號模式） +相關：[/concepts/oauth](/zh-TW/concepts/oauth)（OAuth 流程、權杖儲存、多帳戶模式） - 驗證設定檔是綁定至供應商的具名憑證記錄（OAuth 或 API 金鑰）。設定檔位於： + 驗證設定檔是繫結到提供者的具名憑證記錄（OAuth 或 API 金鑰）。設定檔位於： ``` ~/.openclaw/agents//agent/auth-profiles.json ``` + 若要在不傾印祕密的情況下檢查已儲存的設定檔，請執行 `openclaw models auth list`（可選擇加上 `--provider ` 或 `--json`）。詳情請參閱[模型 CLI](/zh-TW/cli/models#openclaw-models-auth-list)。 + - OpenClaw 使用帶有供應商前綴的 ID，例如： + OpenClaw 使用帶有提供者前綴的 ID，例如： - - `anthropic:default`（沒有電子郵件身分時很常見） + - `anthropic:default`（沒有電子郵件身分時常見） - OAuth 身分使用 `anthropic:` - 你選擇的自訂 ID（例如 `anthropic:work`） - 可以。設定支援設定檔的選用中繼資料，以及每個供應商的排序（`auth.order.`）。這**不會**儲存祕密；它會將 ID 對應到供應商/模式，並設定輪替順序。 + 可以。設定支援設定檔的選用中繼資料，以及每個提供者的排序（`auth.order.`）。這**不會**儲存祕密；它會將 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`，而不是靜默嘗試它。 - 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) diff --git a/docs/zh-TW/help/testing-updates-plugins.md b/docs/zh-TW/help/testing-updates-plugins.md index e99c4531a..af24b4e3e 100644 --- a/docs/zh-TW/help/testing-updates-plugins.md +++ b/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。 +優先使用相同套件產物重新執行失敗的精確跑道，而不是 +重新執行整個發行總括流程。 diff --git a/docs/zh-TW/help/testing.md b/docs/zh-TW/help/testing.md index d054c6bba..4e3a2de70 100644 --- a/docs/zh-TW/help/testing.md +++ b/docs/zh-TW/help/testing.md @@ -1,182 +1,220 @@ --- read_when: - 在本機或 CI 中執行測試 - - 為模型/提供者錯誤新增迴歸測試 - - 偵錯 Gateway + 代理行為 -summary: 測試工具組：單元／端對端／即時測試套件、Docker 執行器，以及各項測試涵蓋的內容 + - 新增模型/提供者錯誤的回歸測試 + - 偵錯 Gateway + 代理程式行為 +summary: 測試工具包：unit/e2e/live 測試套件、Docker 執行器，以及每項測試涵蓋的內容 title: 測試 x-i18n: - generated_at: "2026-05-04T07:04:53Z" + generated_at: "2026-05-05T01:47:48Z" model: gpt-5.5 provider: openai - source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 + source_hash: 8d051bf6a01f6caf7755ad1d7107f21ae2d440b55a65bb7f18ee4a81f5f0e3b2 source_path: help/testing.md workflow: 16 --- -OpenClaw 有三個 Vitest 測試套件（單元/整合、e2e、live）和一小組 -Docker 執行器。本文件是「我們如何測試」指南： +OpenClaw 有三個 Vitest 套件（單元/整合、e2e、live）以及一小組 +Docker runner。這份文件是「我們如何測試」指南： -- 每個套件涵蓋的內容（以及它刻意_不_涵蓋的內容）。 -- 常見工作流程要執行哪些命令（本機、推送前、偵錯）。 -- live 測試如何探索憑證並選擇模型/供應商。 +- 每個套件涵蓋什麼（以及它刻意_不_涵蓋什麼）。 +- 常見工作流程要執行哪些命令（本機、推送前、除錯）。 +- live 測試如何探索認證資料並選擇模型/供應商。 - 如何為真實世界的模型/供應商問題新增回歸測試。 -**QA 堆疊（qa-lab、qa-channel、live 傳輸通道）**另有文件說明： +**QA 堆疊（qa-lab、qa-channel、live transport lanes）**另有文件說明： - [QA 概覽](/zh-TW/concepts/qa-e2e-automation) — 架構、命令介面、情境撰寫。 -- [矩陣 QA](/zh-TW/concepts/qa-matrix) — `pnpm openclaw qa matrix` 的參考。 -- [QA channel](/zh-TW/channels/qa-channel) — repo 支援情境所使用的合成傳輸 Plugin。 +- [Matrix QA](/zh-TW/concepts/qa-matrix) — `pnpm openclaw qa matrix` 的參考。 +- [QA channel](/zh-TW/channels/qa-channel) — repo 支援情境使用的合成傳輸 Plugin。 -本頁涵蓋一般測試套件和 Docker/Parallels 執行器的執行方式。下方的 QA 專用執行器區段（[QA-specific runners](#qa-specific-runners)）列出具體的 `qa` 呼叫方式，並指回上述參考。 +本頁涵蓋一般測試套件與 Docker/Parallels runner 的執行方式。下方的 QA 專用 runner 區段（[QA 專用 runner](#qa-specific-runners)）列出具體的 `qa` 呼叫，並指回上方參考資料。 ## 快速開始 -大多數日子： +多數時候： - 完整閘門（推送前預期執行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 在資源充裕的機器上更快執行本機完整套件：`pnpm test:max` -- 直接 Vitest 監看迴圈：`pnpm test:watch` +- 在資源充足機器上較快的本機完整套件執行：`pnpm test:max` +- 直接的 Vitest 監看迴圈：`pnpm test:watch` - 直接指定檔案現在也會路由 extension/channel 路徑：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 當你正在迭代單一失敗時，優先使用目標式執行。 -- Docker 支援的 QA 站台：`pnpm qa:lab:up` -- Linux VM 支援的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- 當你正在迭代單一失敗時，優先使用目標明確的執行。 +- Docker 支援的 QA site：`pnpm qa:lab:up` +- Linux VM 支援的 QA lane：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -當你碰到測試或想要額外信心時： +當你觸及測試或想要額外信心時： - 覆蓋率閘門：`pnpm test:coverage` - E2E 套件：`pnpm test:e2e` -偵錯真實供應商/模型時（需要真實憑證）： +當除錯真實供應商/模型時（需要真實認證資料）： -- Live 套件（模型 + gateway 工具/影像探針）：`pnpm test:live` +- Live 套件（模型 + Gateway 工具/圖片探測）：`pnpm test:live` - 安靜地指定一個 live 檔案：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -- 執行階段效能報告：分派 `OpenClaw Performance`，使用 - `live_gpt54=true` 進行真實 `openai/gpt-5.4` agent 回合，或使用 - `deep_profile=true` 產生 Kova CPU/heap/trace 成品。當設定 `CLAWGRIT_REPORTS_TOKEN` 時，每日排程執行會將 mock-provider、deep-profile 和 GPT 5.4 通道成品發布到 +- 執行階段效能報告：dispatch `OpenClaw Performance`，搭配 + `live_gpt54=true` 進行真實 `openai/gpt-5.4` agent turn，或搭配 + `deep_profile=true` 產生 Kova CPU/heap/trace 成品。每日排程執行會在 + `CLAWGRIT_REPORTS_TOKEN` 已設定時，將 mock-provider、deep-profile 與 GPT 5.4 lane 成品發布到 `openclaw/clawgrit-reports`。mock-provider 報告也包含原始碼層級的 gateway 啟動、記憶體、 - plugin 壓力、重複 fake-model hello-loop，以及 CLI 啟動數字。 + plugin-pressure、重複 fake-model hello-loop，以及 CLI 啟動數據。 - Docker live 模型掃描：`pnpm test:docker:live-models` - - 每個選取的模型現在會執行一個文字回合，再加上一個小型檔案讀取風格探針。 - 中繼資料宣告支援 `image` 輸入的模型也會執行一個小型影像回合。 - 在隔離供應商失敗時，可用 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 停用額外探針。 + - 每個選取的模型現在會執行一個文字 turn 加上一個小型 file-read 風格探測。 + 中繼資料宣告支援 `image` 輸入的模型也會執行一個小型圖片 turn。 + 隔離供應商失敗時，可用 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 停用額外探測。 - CI 覆蓋範圍：每日 `OpenClaw Scheduled Live And E2E Checks` 和手動 - `OpenClaw Release Checks` 都會以 `include_live_suites: true` 呼叫可重用的 live/E2E workflow，其中包含依供應商分片的個別 Docker live 模型矩陣作業。 - - 若要聚焦 CI 重新執行，請分派 `OpenClaw Live And E2E Checks (Reusable)`， - 並設定 `include_live_suites: true` 與 `live_models_only: true`。 - - 將新的高訊號供應商 secret 新增到 `scripts/ci-hydrate-live-auth.sh`， + `OpenClaw Release Checks` 都會以 `include_live_suites: true` 呼叫可重用的 live/E2E workflow， + 其中包含依供應商分片的個別 Docker live 模型矩陣工作。 + - 針對重點 CI 重新執行，dispatch `OpenClaw Live And E2E Checks (Reusable)`， + 搭配 `include_live_suites: true` 與 `live_models_only: true`。 + - 將新的高訊號供應商 secrets 新增到 `scripts/ci-hydrate-live-auth.sh`， 以及 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 和其 - scheduled/release 呼叫端。 + 排程/發布呼叫端。 - 原生 Codex bound-chat smoke：`pnpm test:docker:live-codex-bind` - - 針對 Codex app-server 路徑執行 Docker live 通道，使用 `/codex bind` 綁定合成 - Slack DM，執行 `/codex fast` 和 - `/codex permissions`，接著驗證純文字回覆和影像附件會經由原生 Plugin 綁定路由，而不是 ACP。 + - 針對 Codex app-server 路徑執行 Docker live lane，使用 `/codex bind` 綁定合成 + Slack DM，演練 `/codex fast` 和 + `/codex permissions`，接著驗證純文字回覆與圖片附件會透過原生 Plugin 綁定路由，而不是 ACP。 - Codex app-server harness smoke：`pnpm test:docker:live-codex-harness` - - 透過 Plugin 擁有的 Codex app-server harness 執行 gateway agent 回合， - 驗證 `/codex status` 和 `/codex models`，並預設執行影像、 - cron MCP、子 agent 和 Guardian 探針。隔離其他 Codex + - 透過 Plugin 擁有的 Codex app-server harness 執行 Gateway agent turn， + 驗證 `/codex status` 和 `/codex models`，並預設演練圖片、 + cron MCP、sub-agent 與 Guardian 探測。隔離其他 Codex app-server 失敗時，可用 - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` 停用子 agent 探針。若要進行聚焦的子 agent 檢查，請停用其他探針： - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - 除非設定 `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`，否則這會在子 agent 探針後結束。 -- Crestodian 救援命令 smoke：`pnpm test:live:crestodian-rescue-channel` - - 訊息 channel 救援命令介面的選擇性雙重保險檢查。 - 它會執行 `/crestodian status`，將持久模型變更新增到佇列， - 回覆 `/crestodian yes`，並驗證稽核/config 寫入路徑。 + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` 停用 sub-agent 探測。若要進行聚焦的 sub-agent 檢查，停用其他探測： + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`。 + 這會在 sub-agent 探測後結束，除非已設定 + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`。 +- Crestodian rescue command smoke：`pnpm test:live:crestodian-rescue-channel` + - 針對 message-channel rescue command + 介面的選用雙重保險檢查。它會演練 `/crestodian status`，佇列持久模型 + 變更，回覆 `/crestodian yes`，並驗證稽核/設定寫入路徑。 - Crestodian planner Docker smoke：`pnpm test:docker:crestodian-planner` - - 在無 config 的容器中執行 Crestodian，並在 `PATH` 上提供 fake Claude CLI， - 驗證 fuzzy planner fallback 會轉換成經稽核的型別化 config 寫入。 + - 在沒有設定檔的容器中執行 Crestodian，且 `PATH` + 上有假的 Claude CLI，並驗證模糊 planner fallback 會轉譯成經稽核的具型別 + 設定寫入。 - Crestodian first-run Docker smoke：`pnpm test:docker:crestodian-first-run` - - 從空的 OpenClaw 狀態目錄開始，將裸 `openclaw` 路由到 + - 從空的 OpenClaw state dir 開始，將裸 `openclaw` 路由到 Crestodian，套用 setup/model/agent/Discord Plugin + SecretRef 寫入， - 驗證 config，並驗證稽核項目。相同的 Ring 0 設定路徑也由 QA Lab 中的 + 驗證設定，並驗證稽核項目。同一個 Ring 0 設定路徑也由 QA Lab 中的 `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` 覆蓋。 -- Moonshot/Kimi 成本 smoke：設定 `MOONSHOT_API_KEY` 後，執行 +- Moonshot/Kimi cost smoke：設定 `MOONSHOT_API_KEY` 後，執行 `openclaw models list --provider moonshot --json`，接著針對 `moonshot/kimi-k2.6` 執行隔離的 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`。 - 驗證 JSON 回報 Moonshot/K2.6，且 assistant transcript 儲存正規化的 `usage.cost`。 + 驗證 JSON 回報 Moonshot/K2.6，且 assistant transcript 儲存正規化後的 `usage.cost`。 -當你只需要一個失敗案例時，優先透過下方說明的 allowlist 環境變數縮小 live 測試範圍。 +當你只需要一個失敗案例時，優先使用下方描述的 allowlist env vars 縮小 live 測試範圍。 -## QA 專用執行器 +## QA 專用 runner -當你需要 QA-lab 的真實度時，這些命令位於主要測試套件旁： +當你需要 QA-lab 的真實度時，這些命令與主要測試套件並列： CI 會在專用 workflow 中執行 QA Lab。Agentic parity 巢狀位於 `QA-Lab - All Lanes` 和發布驗證之下，而不是獨立的 PR workflow。 -廣泛驗證應使用 `Full Release Validation` 搭配 -`rerun_group=qa-parity`，或 release-checks QA 群組。`QA-Lab - All Lanes` -每晚在 `main` 上執行，也可透過手動分派執行，並將 mock parity 通道、live -Matrix 通道、Convex 管理的 live Telegram 通道，以及 Convex 管理的 live Discord -通道作為平行作業。排程 QA 和發布檢查會明確傳遞 Matrix -`--profile fast`，而 Matrix CLI 和手動 workflow 輸入的預設值仍為 -`all`；手動分派可將 `all` 分片成 `transport`、 -`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作業。`OpenClaw Release -Checks` 會在發布核准前執行 parity 加上 fast Matrix 和 Telegram 通道， -並使用 `mock-openai/gpt-5.5` 進行發布傳輸檢查，使它們保持決定性並避免一般 provider-plugin 啟動。這些 live 傳輸 -gateway 會停用記憶體搜尋；記憶體行為仍由 QA parity +廣泛驗證應使用 `Full Release Validation`，搭配 +`rerun_group=qa-parity` 或 release-checks QA group。穩定/預設發布 +檢查會把完整 live/Docker soak 保留在 `run_release_soak=true` 之後；`full` profile 會強制啟用 soak。`QA-Lab - All Lanes` +會在 `main` 每晚執行，並可透過手動 dispatch 執行，其中 mock parity lane、live +Matrix lane、Convex 管理的 live Telegram lane，以及 Convex 管理的 live Discord +lane 會作為平行工作執行。排程 QA 和發布檢查會明確傳入 Matrix +`--profile fast`，而 Matrix CLI 與手動 workflow input +預設仍為 `all`；手動 dispatch 可將 `all` 分片為 `transport`、 +`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 工作。`OpenClaw Release +Checks` 會在發布核准前執行 parity 加上快速 Matrix 與 Telegram lane， +並使用 `mock-openai/gpt-5.5` 進行發布傳輸檢查，讓它們保持 +決定性並避免一般 provider-plugin 啟動。這些 live transport +gateways 會停用記憶體搜尋；記憶體行為仍由 QA parity 套件覆蓋。 完整發布 live media 分片使用 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`，其中已包含 -`ffmpeg` 和 `ffprobe`。Docker live 模型/後端分片使用共享的 -`ghcr.io/openclaw/openclaw-live-test:` 映像，針對選取的 -commit 建置一次，接著用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 拉取它，而不是在每個分片內重新建置。 +`ffmpeg` 和 `ffprobe`。Docker live model/backend 分片使用共用 +`ghcr.io/openclaw/openclaw-live-test:` 映像檔，該映像檔會針對選取的 +commit 建置一次，接著以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 拉取，而不是在每個分片內重新建置。 - `pnpm openclaw qa suite` - - 直接在主機上執行以 repo 為基礎的 QA 情境。 - - 預設會使用隔離的 Gateway worker 平行執行多個選取的情境。`qa-channel` 預設並行數為 4（受選取情境數量限制）。使用 `--concurrency ` 調整 worker - 數量，或使用 `--concurrency 1` 執行較舊的序列通道。 - - 任一情境失敗時會以非零碼結束。若你想要產出成品但不要失敗的結束碼，請使用 `--allow-failures`。 - - 支援 provider 模式 `live-frontier`、`mock-openai` 和 `aimock`。 - `aimock` 會啟動本機 AIMock 後端的 provider 伺服器，用於實驗性 fixture 和 protocol-mock 涵蓋範圍，而不會取代具情境感知能力的 - `mock-openai` 通道。 + - 直接在主機上執行由 repo 支援的 QA 情境。 + - 預設會透過隔離的 + Gateway worker 平行執行多個選定情境。`qa-channel` 預設並行度為 4（受限於 + 選定情境數量）。使用 `--concurrency ` 調整 worker + 數量，或使用 `--concurrency 1` 執行較舊的序列路徑。 + - 當任何情境失敗時會以非零狀態結束。當你想要產生成品但不想要失敗結束碼時，請使用 `--allow-failures`。 + - 支援提供者模式 `live-frontier`、`mock-openai` 和 `aimock`。 + `aimock` 會啟動本機 AIMock 支援的提供者伺服器，用於實驗性 + fixture 和 protocol-mock 覆蓋範圍，而不會取代具情境感知能力的 + `mock-openai` 路徑。 +- `pnpm test:plugins:kitchen-sink-live` + - 透過 QA Lab 執行 live OpenAI Kitchen Sink Plugin 挑戰。它會 + 安裝外部 Kitchen Sink 套件、驗證 Plugin SDK surface + inventory、探測 `/healthz` 和 `/readyz`、記錄 Gateway CPU/RSS + 證據、執行一次 live OpenAI 回合，並檢查對抗式診斷。 + 需要 live OpenAI 驗證，例如 `OPENAI_API_KEY`。在已補齊環境的 Testbox + 工作階段中，當存在 `openclaw-testbox-env` helper 時，它會自動載入 Testbox + live-auth profile。 - `pnpm test:gateway:cpu-scenarios` - - 執行 Gateway 啟動基準測試，加上一小組模擬 QA Lab 情境包 + - 執行 Gateway 啟動 bench 加上一小組模擬 QA Lab 情境包 (`channel-chat-baseline`, `memory-failure-fallback`, - `gateway-restart-inflight-run`)，並在 `.artifacts/gateway-cpu-scenarios/` 下寫入合併的 CPU 觀察摘要。 - - 預設只標記持續的高 CPU 觀察結果（`--cpu-core-warn` - 加上 `--hot-wall-warn-ms`），因此短暫的啟動突增會記錄為指標，而不會看起來像持續數分鐘的 Gateway 滿載退化問題。 - - 使用已建置的 `dist` 成品；若 checkout 尚未有最新的執行階段輸出，請先執行建置。 + `gateway-restart-inflight-run`)，並在 `.artifacts/gateway-cpu-scenarios/` + 下寫入合併的 CPU 觀察摘要。 + - 預設只標記持續高 CPU 觀察結果（`--cpu-core-warn` + 加上 `--hot-wall-warn-ms`），因此短暫的啟動尖峰會被記錄為指標， + 不會看起來像持續數分鐘的 Gateway 滿載回歸。 + - 使用建置完成的 `dist` 成品；當 checkout 尚未有新的 runtime 輸出時，請先執行建置。 - `pnpm openclaw qa suite --runner multipass` - - 在可拋棄的 Multipass Linux VM 內執行相同的 QA 套件。 - - 保持與主機上 `qa suite` 相同的情境選取行為。 - - 重用與 `qa suite` 相同的 provider/model 選取旗標。 - - Live 執行會轉送對 guest 實用且受支援的 QA auth 輸入： - 以 env 為基礎的 provider 金鑰、QA live provider 設定路徑，以及存在時的 `CODEX_HOME`。 - - 輸出目錄必須保持在 repo 根目錄之下，讓 guest 能透過掛載的工作區寫回。 - - 在 `.artifacts/qa-e2e/...` 下寫入一般 QA 報告與摘要，以及 Multipass 日誌。 + - 在一次性的 Multipass Linux VM 內執行相同的 QA suite。 + - 保持與主機上 `qa suite` 相同的情境選擇行為。 + - 重用與 `qa suite` 相同的提供者/模型選擇旗標。 + - live 執行會轉送對 guest 可行且支援的 QA auth 輸入： + 以 env 為基礎的提供者金鑰、QA live provider config path，以及存在時的 `CODEX_HOME`。 + - 輸出目錄必須保持在 repo 根目錄下，讓 guest 可以透過 + 掛載的工作區寫回。 + - 在 `.artifacts/qa-e2e/...` 下寫入一般 QA 報告與摘要，加上 Multipass 記錄。 - `pnpm qa:lab:up` - - 啟動 Docker 後端的 QA 網站，用於 operator 風格的 QA 工作。 + - 啟動 Docker 支援的 QA site，用於操作員式 QA 工作。 - `pnpm test:docker:npm-onboard-channel-agent` - - 從目前 checkout 建置 npm tarball，在 Docker 中全域安裝，執行非互動式 OpenAI API 金鑰 onboarding，預設設定 Telegram，驗證封裝後的 Plugin 執行階段可在不需啟動依賴修復的情況下載入，執行 doctor，並對模擬的 OpenAI endpoint 執行一次本機 agent 回合。 - - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 以 Discord 執行相同的封裝安裝通道。 + - 從目前 checkout 建置 npm tarball、在 + Docker 中全域安裝、執行非互動式 OpenAI API key onboarding、預設設定 Telegram、 + 驗證封裝後的 Plugin runtime 載入時不需要啟動期 + dependency repair、執行 doctor，並針對模擬的 OpenAI endpoint 執行一次本機 agent 回合。 + - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 以 Discord 執行相同的 packaged-install + 路徑。 - `pnpm test:docker:session-runtime-context` - - 針對嵌入式執行階段 context transcript 執行決定性的已建置 app Docker smoke。它會驗證隱藏的 OpenClaw 執行階段 context 會作為非顯示自訂訊息保存，而不是洩漏到可見的使用者回合中，接著植入受影響的損壞 session JSONL，並驗證 - `openclaw doctor --fix` 會以備份將其重寫到作用中分支。 + - 針對嵌入式 runtime context + transcript 執行決定性的 built-app Docker smoke。它會驗證隱藏的 OpenClaw runtime context 會以 + 非顯示 custom message 持久化，而不是洩漏到可見的使用者回合中， + 然後植入受影響的損壞 session JSONL，並驗證 + `openclaw doctor --fix` 會將它重寫到 active branch 並建立備份。 - `pnpm test:docker:npm-telegram-live` - - 在 Docker 中安裝 OpenClaw package 候選項，執行已安裝 package 的 onboarding，透過已安裝的 CLI 設定 Telegram，然後以該已安裝 package 作為 SUT Gateway，重用 live Telegram QA 通道。 + - 在 Docker 中安裝 OpenClaw package candidate、執行 installed-package + onboarding、透過已安裝的 CLI 設定 Telegram，然後使用該已安裝套件作為 SUT Gateway + 重用 live Telegram QA 路徑。 - 預設為 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`；設定 `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` 或 - `OPENCLAW_CURRENT_PACKAGE_TGZ`，即可測試已解析的本機 tarball，而不是從 registry 安裝。 - - 使用與 `pnpm openclaw qa telegram` 相同的 Telegram env credentials 或 Convex credential 來源。對於 CI/release 自動化，請設定 - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，再加上 - `OPENCLAW_QA_CONVEX_SITE_URL` 和角色 secret。若 - `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色 secret 存在於 CI 中，Docker wrapper 會自動選取 Convex。 - - wrapper 會先在主機上驗證 Telegram 或 Convex credential env，再進行 Docker build/install 工作。只有在刻意偵錯 credential 前置設定時，才設定 `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1`。 - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 只會針對此通道覆寫共用的 + `OPENCLAW_CURRENT_PACKAGE_TGZ`，可測試已解析的本機 tarball，而不是 + 從 registry 安裝。 + - 使用與 `pnpm openclaw qa telegram` 相同的 Telegram env credentials 或 Convex credential source。 + 對於 CI/release automation，請設定 + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` 加上 + `OPENCLAW_QA_CONVEX_SITE_URL` 和 role secret。如果 + `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex role secret 存在於 CI， + Docker wrapper 會自動選擇 Convex。 + - wrapper 會在 Docker build/install 工作前，在主機上驗證 Telegram 或 Convex credential env。 + 只有在刻意偵錯 credential 前置設定時，才設定 `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1`。 + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 只會針對此路徑覆寫共用的 `OPENCLAW_QA_CREDENTIAL_ROLE`。 - - GitHub Actions 將此通道公開為手動 maintainer workflow + - GitHub Actions 將此路徑公開為手動 maintainer workflow `NPM Telegram Beta E2E`。它不會在 merge 時執行。該 workflow 使用 - `qa-live-shared` environment 和 Convex CI credential lease。 -- GitHub Actions 也公開 `Package Acceptance`，用於對單一候選 package 進行旁路產品驗證。它接受受信任的 ref、已發布的 npm spec、HTTPS tarball URL 加 SHA-256，或另一個 run 的 tarball artifact，將標準化的 `openclaw-current.tgz` 上傳為 `package-under-test`，接著使用 smoke、package、product、full 或 custom 通道 profile 執行既有 Docker E2E scheduler。設定 `telegram_mode=mock-openai` 或 `live-frontier`，即可讓 Telegram QA workflow 針對同一個 `package-under-test` artifact 執行。 - - 最新 beta 產品驗證： + `qa-live-shared` environment 和 Convex CI credential leases。 +- GitHub Actions 也公開 `Package Acceptance`，用於針對單一 candidate package + 進行 side-run 產品證明。它接受受信任的 ref、已發布的 npm spec、 + HTTPS tarball URL 加 SHA-256，或來自另一個 run 的 tarball artifact，並上傳 + 正規化的 `openclaw-current.tgz` 作為 `package-under-test`，接著使用 smoke、package、product、full 或 custom + 路徑 profile 執行既有 Docker E2E scheduler。設定 `telegram_mode=mock-openai` 或 `live-frontier` + 可讓 Telegram QA workflow 針對相同的 `package-under-test` artifact 執行。 + - 最新 beta 產品證明： ```bash gh workflow run package-acceptance.yml --ref main \ @@ -186,7 +224,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- 精確 tarball URL 驗證需要 digest： +- 精確 tarball URL 證明需要 digest： ```bash gh workflow run package-acceptance.yml --ref main \ @@ -196,7 +234,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Artifact 驗證會從另一個 Actions run 下載 tarball artifact： +- artifact 證明會從另一個 Actions run 下載 tarball artifact： ```bash gh workflow run package-acceptance.yml --ref main \ @@ -207,78 +245,99 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - 在 Docker 中封裝並安裝目前的 OpenClaw build，以已設定的 OpenAI 啟動 Gateway，接著透過 config 編輯啟用 bundled channel/plugins。 - - 驗證 setup discovery 會讓未設定的可下載 Plugin 保持缺席，第一次設定後的 doctor repair 會明確安裝每個缺少的可下載 Plugin，而第二次重啟不會執行隱藏的依賴修復。 + - 在 Docker 中封裝並安裝目前的 OpenClaw build、啟動已設定 OpenAI 的 Gateway， + 然後透過 config 編輯啟用 bundled channel/plugins。 + - 驗證 setup discovery 會讓未設定的可下載 Plugin 保持不存在、 + 第一次設定完成的 doctor repair 會明確安裝每個缺少的可下載 + Plugin，而第二次重新啟動不會執行隱藏的 dependency + repair。 - 也會安裝已知較舊的 npm baseline，在執行 - `openclaw update --tag ` 前啟用 Telegram，並驗證候選項的更新後 doctor 會清理舊版 Plugin 依賴殘留，而不需要 harness 端 postinstall repair。 + `openclaw update --tag ` 前啟用 Telegram，並驗證 candidate 的 + post-update doctor 會清理 legacy Plugin dependency 碎片，而不需要 + harness-side postinstall repair。 - `pnpm test:parallels:npm-update` - - 跨 Parallels guest 執行原生封裝安裝更新 smoke。每個選取的平台會先安裝要求的 baseline package，接著在同一個 guest 中執行已安裝的 `openclaw update` 命令，並驗證已安裝版本、更新狀態、Gateway 就緒狀態，以及一次本機 agent 回合。 - - 在針對單一 guest 迭代時，使用 `--platform macos`、`--platform windows` 或 `--platform linux`。使用 `--json` 取得摘要 artifact 路徑和各通道狀態。 - - OpenAI 通道預設使用 `openai/gpt-5.5` 進行 live agent 回合驗證。若刻意驗證其他 OpenAI model，請傳入 `--model ` 或設定 + - 跨 Parallels guest 執行原生 packaged-install update smoke。每個 + 選定平台會先安裝指定的 baseline package，然後在同一個 guest 中執行 + 已安裝的 `openclaw update` 命令，並驗證已安裝版本、update status、Gateway readiness，以及一次本機 agent + 回合。 + - 迭代單一 guest 時使用 `--platform macos`、`--platform windows` 或 `--platform linux`。 + 使用 `--json` 取得摘要 artifact path 和各路徑狀態。 + - OpenAI 路徑預設使用 `openai/gpt-5.5` 作為 live agent-turn 證明。 + 當刻意驗證另一個 OpenAI 模型時，傳入 `--model ` 或設定 `OPENCLAW_PARALLELS_OPENAI_MODEL`。 - - 將長時間本機執行包在主機 timeout 中，避免 Parallels transport 停滯耗盡剩餘測試時間： + - 用主機 timeout 包住長時間本機執行，避免 Parallels transport 停滯 + 消耗剩餘測試時間： ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - 腳本會在 `/tmp/openclaw-parallels-npm-update.*` 下寫入巢狀通道日誌。 - 在假設外層 wrapper 卡住之前，請檢查 `windows-update.log`、`macos-update.log` 或 `linux-update.log`。 - - Windows 更新在冷 guest 上可能會花 10 到 15 分鐘進行更新後 doctor 和 package 更新工作；只要巢狀 npm debug log 持續前進，這仍然是健康狀態。 - - 請勿將這個聚合 wrapper 與個別 Parallels macOS、Windows 或 Linux smoke 通道平行執行。它們共用 VM 狀態，可能在 snapshot restore、package serving 或 guest Gateway 狀態上發生衝突。 - - 更新後驗證會執行一般 bundled Plugin surface，因為語音、影像生成、媒體理解等 capability facade 會透過 bundled runtime API 載入，即使 agent 回合本身只檢查簡單文字回應。 + - script 會在 `/tmp/openclaw-parallels-npm-update.*` 下寫入巢狀路徑記錄。 + 在假設外層 wrapper 卡住之前，先檢查 `windows-update.log`、`macos-update.log` 或 `linux-update.log`。 + - Windows update 在 cold guest 上可能會花 10 到 15 分鐘進行 post-update doctor 和 package + update 工作；只要巢狀 npm debug log 持續前進，這仍然是健康狀態。 + - 不要將這個彙總 wrapper 與個別 Parallels + macOS、Windows 或 Linux smoke 路徑平行執行。它們共用 VM state，可能在 + snapshot restore、package serving 或 guest Gateway state 上衝突。 + - post-update 證明會執行一般 bundled Plugin surface，因為 + speech、image generation 和 media + understanding 等 capability facade 是透過 bundled runtime API 載入，即使 agent + 回合本身只檢查簡單文字回應。 - `pnpm openclaw qa aimock` - - 只啟動本機 AIMock provider 伺服器，用於直接 protocol smoke 測試。 + - 只啟動本機 AIMock 提供者伺服器，用於直接 protocol smoke + testing。 - `pnpm openclaw qa matrix` - - 對一次性 Docker 後端的 Tuwunel homeserver 執行 Matrix live QA 通道。僅限 source-checkout，封裝安裝不會附帶 `qa-lab`。 - - 完整 CLI、profile/scenario catalog、env vars 和 artifact 版面配置：[Matrix QA](/zh-TW/concepts/qa-matrix)。 + - 針對一次性的 Docker 支援 Tuwunel homeserver 執行 Matrix live QA 路徑。僅限 source-checkout，packaged install 不會隨附 `qa-lab`。 + - 完整 CLI、profile/scenario catalog、env vars 和 artifact layout：[Matrix QA](/zh-TW/concepts/qa-matrix)。 - `pnpm openclaw qa telegram` - - 使用 env 中的 driver 和 SUT bot token，針對真實私人群組執行 Telegram live QA 通道。 + - 使用來自 env 的 driver 和 SUT bot token，針對真實 private group 執行 Telegram live QA 路徑。 - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。group id 必須是數字 Telegram chat id。 - - 支援 `--credential-source convex` 以使用共用 pooled credentials。預設使用 env 模式，或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以選用 pooled lease。 - - 任一情境失敗時會以非零碼結束。若你想要產出成品但不要失敗的結束碼，請使用 `--allow-failures`。 - - 需要同一個私人群組中的兩個不同 bot，且 SUT bot 必須公開 Telegram username。 - - 為了穩定的 bot 對 bot 觀察，請在 `@BotFather` 中為兩個 bot 啟用 Bot-to-Bot Communication Mode，並確保 driver bot 能觀察群組 bot 流量。 - - 在 `.artifacts/qa-e2e/...` 下寫入 Telegram QA 報告、摘要和 observed-messages artifact。回覆情境包含從 driver 傳送請求到觀察到 SUT 回覆的 RTT。 + - 支援 `--credential-source convex` 以使用共用 pooled credentials。預設使用 env 模式，或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以選擇使用 pooled leases。 + - 當任何情境失敗時會以非零狀態結束。當你想要產生成品但不想要失敗結束碼時，請使用 `--allow-failures`。 + - 需要同一個 private group 中兩個不同的 bot，且 SUT bot 必須公開 Telegram username。 + - 為了穩定的 bot-to-bot 觀察，請在 `@BotFather` 中為兩個 bot 啟用 Bot-to-Bot Communication Mode，並確保 driver bot 可以觀察 group bot traffic。 + - 在 `.artifacts/qa-e2e/...` 下寫入 Telegram QA report、summary 和 observed-messages artifact。replying 情境包含從 driver send request 到觀察到 SUT reply 的 RTT。 -Live transport 通道共用一個標準 contract，讓新 transport 不會漂移；各通道涵蓋矩陣位於 [QA 概覽 → Live transport 涵蓋範圍](/zh-TW/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 是廣泛的合成套件，不屬於該矩陣。 +live transport 路徑共用一份標準 contract，讓新的 transport 不會偏離；各路徑 coverage matrix 位於 [QA overview → Live transport coverage](/zh-TW/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 是廣泛的 synthetic suite，不屬於該 matrix。 ### 透過 Convex 共用 Telegram credentials (v1) -當 `openclaw qa telegram` 啟用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）時，QA lab 會從 Convex 後端的 pool 取得獨占 lease，在通道執行期間對該 lease 送出 heartbeat，並在關閉時釋放 lease。 +當為 `openclaw qa telegram` 啟用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）時，QA lab +會從 Convex 支援的 pool 取得 exclusive lease，在路徑執行期間對該 lease 傳送 Heartbeat， +並在 shutdown 時釋放該 lease。 -參考 Convex 專案 scaffold： +參考 Convex project scaffold： - `qa/convex-credential-broker/` 必要 env vars： - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`） -- 所選角色的一個 secret： +- 選定 role 的一個 secret： - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 用於 `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` 用於 `ci` -- Credential 角色選取： +- Credential role selection： - CLI：`--credential-role maintainer|ci` - - Env 預設：`OPENCLAW_QA_CREDENTIAL_ROLE`（CI 中預設為 `ci`，否則為 `maintainer`） + - Env 預設值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中預設為 `ci`，否則為 `maintainer`） -可選 env vars： +選用 env vars： - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS`（預設 `1200000`） - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS`（預設 `30000`） - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（預設 `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（預設 `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（預設 `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可選 trace id） -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允許本機限定開發使用 loopback `http://` Convex URL。 +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（選用 trace id） +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允許 local-only 開發使用 loopback `http://` Convex URL。 -`OPENCLAW_QA_CONVEX_SITE_URL` 在一般操作中應使用 `https://`。 +`OPENCLAW_QA_CONVEX_SITE_URL` 在正常操作中應使用 `https://`。 -Maintainer admin 命令（pool add/remove/list）明確需要 +Maintainer 管理命令（集區新增/移除/列出）特別需要 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 -Maintainer 的 CLI helper： +Maintainer 的 CLI 輔助工具： ```bash pnpm openclaw qa credentials doctor @@ -287,12 +346,12 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Use `doctor` 前，請先檢查 Convex 站台 URL、broker 密鑰、 -端點前綴、HTTP 逾時，以及 admin/list 可達性，且不要列印 -密鑰值。在指令稿和 CI -公用工具中使用 `--json` 取得機器可讀輸出。 +在即時執行前使用 `doctor`，以檢查 Convex 網站 URL、broker secrets、 +endpoint prefix、HTTP timeout，以及 admin/list 可連線性，且不列印 +secret values。在腳本與 CI +公用程式中使用 `--json` 取得機器可讀輸出。 -預設端點合約（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： +預設 endpoint contract（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： - `POST /acquire` - 請求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -304,370 +363,406 @@ Use `doctor` 前，請先檢查 Convex 站台 URL、broker 密鑰、 - `POST /release` - 請求：`{ kind, ownerId, actorRole, credentialId, leaseToken }` - 成功：`{ status: "ok" }`（或空的 `2xx`） -- `POST /admin/add`（僅維護者密鑰） +- `POST /admin/add`（僅限 maintainer secret） - 請求：`{ kind, actorId, payload, note?, status? }` - 成功：`{ status: "ok", credential }` -- `POST /admin/remove`（僅維護者密鑰） +- `POST /admin/remove`（僅限 maintainer secret） - 請求：`{ credentialId, actorId }` - 成功：`{ status: "ok", changed, credential }` - - 作用中租約保護：`{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（僅維護者密鑰） + - 作用中 lease 防護：`{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list`（僅限 maintainer secret） - 請求：`{ kind?, status?, includePayload?, limit? }` - 成功：`{ status: "ok", credentials, count }` -Telegram kind 的 payload 形狀： +Telegram 類型的 payload shape： - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` 必須是數字型 Telegram 聊天 id 字串。 -- `admin/add` 會針對 `kind: "telegram"` 驗證此形狀，並拒絕格式錯誤的 payload。 +- `groupId` 必須是數字形式的 Telegram chat id 字串。 +- `admin/add` 會針對 `kind: "telegram"` 驗證此 shape，並拒絕格式錯誤的 payload。 -### 將通道新增至 QA +### 將 channel 新增到 QA -新通道轉接器的架構和情境輔助程式名稱位於 [QA 概覽 → 新增通道](/zh-TW/concepts/qa-e2e-automation#adding-a-channel)。最低標準：在共用 `qa-lab` 主機銜接面上實作傳輸執行器，在 Plugin 資訊清單中宣告 `qaRunners`，掛載為 `openclaw qa `，並在 `qa/scenarios/` 下撰寫情境。 +新 channel adapters 的架構與 scenario-helper 名稱位於 [QA overview → 新增 channel](/zh-TW/concepts/qa-e2e-automation#adding-a-channel)。最低要求：在共用 `qa-lab` host seam 上實作 transport runner、在 Plugin manifest 中宣告 `qaRunners`、掛載為 `openclaw qa `，並在 `qa/scenarios/` 下撰寫 scenarios。 -## 測試套件（在哪裡執行什麼） +## Test suites（哪些項目在哪裡執行） -將套件視為「真實度逐步提高」（且不穩定性/成本也逐步提高）： +可將 suites 視為「逐步提高真實程度」（同時也提高不穩定性/成本）： -### 單元 / 整合（預設） +### Unit / integration（預設） -- 指令：`pnpm test` -- 設定：未指定目標的執行會使用 `vitest.full-*.config.ts` 分片集合，並可能將多專案分片展開成每個專案的設定以便平行排程 -- 檔案：`src/**/*.test.ts`、`packages/**/*.test.ts` 和 `test/**/*.test.ts` 下的核心/單元清單；UI 單元測試會在專用的 `unit-ui` 分片中執行 +- 命令：`pnpm test` +- 設定：未指定目標的執行會使用 `vitest.full-*.config.ts` shard 集合，並可能將多專案 shards 展開成個別專案 configs 以進行平行排程 +- 檔案：`src/**/*.test.ts`、`packages/**/*.test.ts` 與 `test/**/*.test.ts` 下的 core/unit inventories；UI unit tests 在專用的 `unit-ui` shard 中執行 - 範圍： - - 純單元測試 - - 程序內整合測試（Gateway 驗證、路由、工具、解析、設定） - - 已知錯誤的確定性迴歸測試 -- 預期： + - 純 unit tests + - In-process integration tests（Gateway auth、routing、tooling、parsing、config） + - 已知 bug 的確定性 regressions +- 期望： - 在 CI 中執行 - - 不需要真實金鑰 + - 不需要真實 keys - 應快速且穩定 - - 解析器與公開介面載入器測試必須使用產生的小型 Plugin fixture，證明廣泛的 `api.js` 和 - `runtime-api.js` 後援行為，而不是使用真實內建 Plugin 來源 API。真實 Plugin API 載入屬於 - Plugin 擁有的合約/整合套件。 + - Resolver 與 public-surface loader tests 必須使用產生的小型 Plugin fixtures，證明廣泛 `api.js` 與 + `runtime-api.js` fallback 行為，而不是 + 真實 bundled Plugin source APIs。真實 Plugin API loads 屬於 + Plugin 擁有的 contract/integration suites。 - + - - 未指定目標的 `pnpm test` 會執行十二個較小的分片設定（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一個巨大的原生根專案程序。這會降低高負載機器上的峰值 RSS，並避免 auto-reply/extension 工作拖慢不相關的套件。 - - `pnpm test --watch` 仍使用原生根 `vitest.config.ts` 專案圖，因為多分片 watch 迴圈並不實際。 - - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 會先透過範圍化通道路由明確的檔案/目錄目標，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可避免支付完整根專案啟動成本。 - - `pnpm test:changed` 預設會將變更的 git 路徑展開成低成本的範圍化通道：直接測試編輯、同層 `*.test.ts` 檔案、明確來源對應，以及本機匯入圖相依項。設定/設置/package 編輯不會廣泛執行測試，除非你明確使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 - - `pnpm check:changed` 是窄範圍工作的正常智慧本機檢查閘門。它會將 diff 分類成核心、核心測試、extensions、extension 測試、apps、docs、release metadata、live Docker tooling 和 tooling，然後執行對應的型別檢查、lint 和保護指令。它不會執行 Vitest 測試；若需要測試證明，請呼叫 `pnpm test:changed` 或明確的 `pnpm test `。僅 release metadata 的版本提升會執行目標式版本/設定/根相依性檢查，並有一道保護會拒絕頂層版本欄位以外的 package 變更。 - - Live Docker ACP harness 編輯會執行聚焦檢查：live Docker 驗證指令稿的 shell 語法，以及 live Docker 排程器 dry-run。只有當 diff 限於 `scripts["test:docker:live-*"]` 時才包含 `package.json` 變更；相依性、export、version 和其他 package 介面編輯仍使用較廣泛的保護。 - - 來自 agents、commands、plugins、auto-reply helpers、`plugin-sdk` 和類似純公用工具區域的輕匯入單元測試，會路由到 `unit-fast` 通道，該通道會略過 `test/setup-openclaw-runtime.ts`；有狀態/重 runtime 的檔案會留在現有通道上。 - - 選定的 `plugin-sdk` 和 `commands` 輔助來源檔案，也會在變更模式執行時對應到這些輕量通道中的明確同層測試，因此輔助程式編輯可避免重新執行該目錄的完整重型套件。 - - `auto-reply` 有專用 bucket，分別用於頂層核心輔助程式、頂層 `reply.*` 整合測試，以及 `src/auto-reply/reply/**` 子樹。CI 進一步將 reply 子樹拆分成 agent-runner、dispatch 和 commands/state-routing 分片，因此單一匯入繁重的 bucket 不會占用完整 Node 尾端。 - - 一般 PR/main CI 會刻意略過 extension 批次掃描和僅 release 的 `agentic-plugins` 分片。完整 Release Validation 會針對 release candidate 分派獨立的 `Plugin Prerelease` 子工作流程，以執行這些 Plugin/extension 重型套件。 + - 未指定目標的 `pnpm test` 會執行十二個較小的 shard configs（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一個巨大的原生 root-project process。這會降低負載機器上的尖峰 RSS，並避免 auto-reply/extension 工作讓不相關 suites 缺乏資源。 + - `pnpm test --watch` 仍使用原生 root `vitest.config.ts` project graph，因為 multi-shard watch loop 不實用。 + - `pnpm test`、`pnpm test:watch` 與 `pnpm test:perf:imports` 會先透過 scoped lanes 路由明確的檔案/目錄目標，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可避免支付完整 root project 啟動成本。 + - `pnpm test:changed` 預設會將已變更的 git paths 展開成便宜的 scoped lanes：直接測試編輯、同層 `*.test.ts` 檔案、明確來源 mappings，以及本機 import-graph dependents。除非你明確使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`，否則 config/setup/package 編輯不會 broad-run tests。 + - `pnpm check:changed` 是窄範圍工作的正常智慧本機檢查 gate。它會將 diff 分類為 core、core tests、extensions、extension tests、apps、docs、release metadata、live Docker tooling 與 tooling，然後執行相符的 typecheck、lint 與 guard commands。它不會執行 Vitest tests；如需 test proof，請呼叫 `pnpm test:changed` 或明確的 `pnpm test `。僅 release metadata 的版本 bumps 會執行目標版本/config/root-dependency checks，並有 guard 會拒絕 top-level version field 之外的 package 變更。 + - Live Docker ACP harness 編輯會執行聚焦 checks：live Docker auth scripts 的 shell syntax，以及 live Docker scheduler dry-run。只有當 diff 限於 `scripts["test:docker:live-*"]` 時才包含 `package.json` 變更；dependency、export、version 與其他 package-surface 編輯仍使用較廣泛的 guards。 + - 來自 agents、commands、plugins、auto-reply helpers、`plugin-sdk` 與類似純公用程式區域的 import-light unit tests，會透過 `unit-fast` lane 路由，該 lane 會略過 `test/setup-openclaw-runtime.ts`；stateful/runtime-heavy 檔案維持在既有 lanes。 + - 選定的 `plugin-sdk` 與 `commands` helper source files 也會將 changed-mode runs 映射到這些 light lanes 中明確的同層 tests，因此 helper 編輯可避免重新執行該目錄的完整 heavy suite。 + - `auto-reply` 針對 top-level core helpers、top-level `reply.*` integration tests，以及 `src/auto-reply/reply/**` 子樹有專用 buckets。CI 會進一步將 reply 子樹拆成 agent-runner、dispatch 與 commands/state-routing shards，避免單一 import-heavy bucket 擁有完整 Node 尾端。 + - 一般 PR/main CI 會刻意略過 extension batch sweep 與僅 release 的 `agentic-plugins` shard。Full Release Validation 會針對 release candidates 派發獨立的 `Plugin Prerelease` 子 workflow，以執行這些 Plugin/extension-heavy suites。 - + - - 當你變更訊息工具探索輸入或 compaction runtime - context 時，請保留兩個層級的涵蓋範圍。 - - 為純路由與正規化邊界新增聚焦的輔助程式迴歸測試。 - - 維持嵌入式執行器整合套件健康： + - 當你變更 message-tool discovery inputs 或 Compaction runtime + context 時，請保留兩個層級的 coverage。 + - 為純 routing 與 normalization + boundaries 新增聚焦 helper regressions。 + - 維持 embedded runner integration suites 健康： `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 和 + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`，以及 `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - 這些套件會驗證範圍化 id 與 compaction 行為仍會流經 - 真實的 `run.ts` / `compact.ts` 路徑；僅輔助程式的測試 - 不能充分替代這些整合路徑。 + - 這些 suites 驗證 scoped ids 與 Compaction 行為仍會 + 透過真實 `run.ts` / `compact.ts` paths 流動；僅 helper 的 tests + 不足以取代這些 integration paths。 - + - - 基礎 Vitest 設定預設為 `threads`。 - - 共用 Vitest 設定固定 `isolate: false`，並在根專案、e2e 和 live 設定中使用 - 非隔離執行器。 - - 根 UI 通道保留其 `jsdom` 設置與 optimizer，但也在 - 共用非隔離執行器上執行。 - - 每個 `pnpm test` 分片都會從共用 Vitest 設定繼承相同的 `threads` + `isolate: false` - 預設值。 - - `scripts/run-vitest.mjs` 預設會為 Vitest 子 Node - 程序加入 `--no-maglev`，以減少大型本機執行期間的 V8 編譯 churn。 - 設定 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可與原廠 V8 + - Base Vitest config 預設為 `threads`。 + - 共用 Vitest config 會固定 `isolate: false`，並在 + root projects、e2e 與 live configs 中使用 + non-isolated runner。 + - Root UI lane 保留其 `jsdom` setup 與 optimizer，但也在 + 共用 non-isolated runner 上執行。 + - 每個 `pnpm test` shard 都會從共用 Vitest config 繼承相同的 `threads` + `isolate: false` + defaults。 + - `scripts/run-vitest.mjs` 預設會為 Vitest child Node + processes 加上 `--no-maglev`，以降低大型本機執行期間的 V8 compile churn。 + 設定 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可與標準 V8 行為比較。 - - `pnpm changed:lanes` 會顯示 diff 觸發哪些架構通道。 - - pre-commit hook 僅負責格式化。它會重新暫存已格式化的檔案， - 不會執行 lint、型別檢查或測試。 - - 在交接或 push 前，若你需要智慧本機檢查閘門，請明確執行 `pnpm check:changed`。 - - `pnpm test:changed` 預設會透過低成本的範圍化通道路由。只有當 agent - 判定 harness、設定、package 或合約編輯確實需要更廣泛的 - Vitest 涵蓋範圍時，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 - - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由 - 行為，只是使用較高的 worker 上限。 - - 本機 worker 自動縮放刻意保守，並會在主機 load average 已偏高時退讓， - 因此多個並行 Vitest 執行預設造成較少影響。 - - 基礎 Vitest 設定會將專案/設定檔標記為 - `forceRerunTriggers`，因此測試 wiring 變更時，變更模式重新執行仍保持正確。 - - 設定會在支援的主機上保持啟用 `OPENCLAW_VITEST_FS_MODULE_CACHE`； - 若你想要為直接 profiling 指定一個明確的快取位置，請設定 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 + - `pnpm changed:lanes` 會顯示 diff 觸發哪些 architectural lanes。 + - pre-commit hook 只做 formatting。它會重新 stage 已格式化檔案，且 + 不會執行 lint、typecheck 或 tests。 + - 在 handoff 或 push 前，當你需要智慧本機檢查 gate 時， + 明確執行 `pnpm check:changed`。 + - `pnpm test:changed` 預設會透過便宜的 scoped lanes 路由。只有當 agent + 判定 harness、config、package 或 contract 編輯確實需要更廣泛的 + Vitest coverage 時，才使用 + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。 + - `pnpm test:max` 與 `pnpm test:changed:max` 保持相同的 routing + 行為，只是提高 worker cap。 + - 本機 worker auto-scaling 刻意保守，且會在 host load average 已經偏高時退讓，因此多個並行 + Vitest runs 預設造成的影響較小。 + - Base Vitest config 會將 projects/config files 標記為 + `forceRerunTriggers`，因此當 test wiring 變更時，changed-mode reruns 仍保持正確。 + - Config 會在支援的 hosts 上維持啟用 `OPENCLAW_VITEST_FS_MODULE_CACHE`； + 若你想要一個明確的 direct profiling cache 位置，請設定 + `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 - + - - `pnpm test:perf:imports` 會啟用 Vitest 匯入耗時報告與 - import-breakdown 輸出。 - - `pnpm test:perf:imports:changed` 會將相同的 profiling 視圖範圍化到 + - `pnpm test:perf:imports` 會啟用 Vitest import-duration reporting 加上 + import-breakdown output。 + - `pnpm test:perf:imports:changed` 會將相同 profiling view 範圍限定到 自 `origin/main` 以來變更的檔案。 - - 分片時間資料會寫入 `.artifacts/vitest-shard-timings.json`。 - 全設定執行會使用設定路徑作為 key；include-pattern CI - 分片會附加分片名稱，因此可分別追蹤已過濾的分片。 - - 當某個 hot test 仍將大部分時間花在啟動匯入時， - 請將重型相依性放在窄範圍本機 `*.runtime.ts` 銜接面之後， - 並直接 mock 該銜接面，而不是 deep-import runtime helpers 只為了 - 將它們傳入 `vi.mock(...)`。 - - `pnpm test:perf:changed:bench -- --ref ` 會將路由後的 - `test:changed` 與該已提交 diff 的原生根專案路徑比較， - 並列印 wall time 與 macOS max RSS。 + - Shard timing data 會寫入 `.artifacts/vitest-shard-timings.json`。 + Whole-config runs 會使用 config path 作為 key；include-pattern CI + shards 會附加 shard name，讓 filtered shards 可被分開追蹤。 + - 當某個 hot test 仍將大部分時間花在 startup imports 時， + 請將 heavy dependencies 放在窄範圍本機 `*.runtime.ts` seam 後方，並 + 直接 mock 該 seam，而不是 deep-importing runtime helpers 只是 + 為了將它們傳給 `vi.mock(...)`。 + - `pnpm test:perf:changed:bench -- --ref ` 會針對該已 commit 的 + diff，比較 routed `test:changed` 與原生 root-project path，並列印 wall time 與 macOS max RSS。 - `pnpm test:perf:changed:bench -- --worktree` 會透過 - `scripts/test-projects.mjs` 和根 Vitest 設定，路由變更檔案清單， - 以 benchmark 目前的 dirty tree。 + `scripts/test-projects.mjs` 與 root Vitest config 路由 changed file list，以 benchmark 目前的 + dirty tree。 - `pnpm test:perf:profile:main` 會為 - Vitest/Vite 啟動與轉換 overhead 寫入主執行緒 CPU profile。 - - `pnpm test:perf:profile:runner` 會在停用檔案平行處理時，為 - 單元套件寫入 runner CPU+heap profiles。 + Vitest/Vite startup 與 transform overhead 寫入 main-thread CPU profile。 + - `pnpm test:perf:profile:runner` 會為 + 停用 file parallelism 的 unit suite 寫入 runner CPU+heap profiles。 -### 穩定性（Gateway） +### Stability（gateway） -- 指令：`pnpm test:stability:gateway` -- 設定：`vitest.gateway.config.ts`，強制使用一個 worker +- 命令：`pnpm test:stability:gateway` +- Config：`vitest.gateway.config.ts`，強制使用一個 worker - 範圍： - - 啟動真實的 loopback Gateway，預設啟用診斷 - - 透過診斷事件路徑驅動合成 Gateway 訊息、記憶體與大型 payload churn + - 啟動真實 loopback Gateway，預設啟用 diagnostics + - 透過 diagnostic event path 驅動合成 gateway message、memory 與 large-payload churn - 透過 Gateway WS RPC 查詢 `diagnostics.stability` - - 涵蓋診斷穩定性 bundle 持久化輔助程式 - - 斷言 recorder 保持有界、合成 RSS 樣本維持在壓力預算內，且每個 session 的佇列深度會排空回到零 -- 預期： - - 可安全用於 CI 且不需金鑰 - - 穩定性迴歸後續處理的窄通道，不是完整 Gateway 套件的替代品 + - 涵蓋 diagnostic stability bundle persistence helpers + - 斷言 recorder 保持 bounded、合成 RSS samples 維持在 pressure budget 以下，且 per-session queue depths 會 drain back to zero +- 期望： + - CI-safe 且不需要 key + - 這是 stability-regression follow-up 的窄 lane，不是完整 Gateway suite 的替代品 -### E2E（Gateway smoke） +### E2E（gateway smoke） - 命令：`pnpm test:e2e` - 設定：`vitest.e2e.config.ts` -- 檔案：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的 bundled-plugin E2E 測試 +- 檔案：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 底下的內建 Plugin E2E 測試 - 執行階段預設值： - - 使用 Vitest `threads` 並設定 `isolate: false`，與 repo 其餘部分一致。 + - 使用 Vitest `threads` 搭配 `isolate: false`，與儲存庫其餘部分一致。 - 使用自適應 worker（CI：最多 2 個，本機：預設 1 個）。 - 預設以靜默模式執行，以降低主控台 I/O 開銷。 - 實用覆寫： - - `OPENCLAW_E2E_WORKERS=` 用於強制指定 worker 數量（上限為 16）。 - - `OPENCLAW_E2E_VERBOSE=1` 用於重新啟用詳細主控台輸出。 + - `OPENCLAW_E2E_WORKERS=` 可強制指定 worker 數量（上限為 16）。 + - `OPENCLAW_E2E_VERBOSE=1` 可重新啟用詳細主控台輸出。 - 範圍： - - 多實例 gateway 端對端行為 + - 多執行個體 Gateway 端對端行為 - WebSocket/HTTP 介面、Node 配對，以及較重的網路功能 - 預期： - - 在 CI 中執行（當 pipeline 中啟用時） + - 在 CI 中執行（當管線中啟用時） - 不需要真實金鑰 - 比單元測試有更多移動部件（可能較慢） -### E2E：OpenShell backend smoke +### E2E：OpenShell 後端煙霧測試 - 命令：`pnpm test:e2e:openshell` - 檔案：`extensions/openshell/src/backend.e2e.test.ts` - 範圍： - - 透過 Docker 在主機上啟動隔離的 OpenShell gateway - - 從暫存本機 Dockerfile 建立 sandbox - - 透過真實的 `sandbox ssh-config` + SSH exec 測試 OpenClaw 的 OpenShell backend - - 透過 sandbox fs bridge 驗證遠端標準 filesystem 行為 + - 透過 Docker 在主機上啟動隔離的 OpenShell Gateway + - 從暫存本機 Dockerfile 建立沙箱 + - 透過真實的 `sandbox ssh-config` + SSH exec 測試 OpenClaw 的 OpenShell 後端 + - 透過沙箱 fs 橋接器驗證遠端標準檔案系統行為 - 預期： - - 僅限 opt-in；不是預設 `pnpm test:e2e` 執行的一部分 - - 需要本機 `openshell` CLI 以及可運作的 Docker daemon - - 使用隔離的 `HOME` / `XDG_CONFIG_HOME`，然後銷毀測試 gateway 與 sandbox + - 僅限選擇加入；不屬於預設 `pnpm test:e2e` 執行的一部分 + - 需要本機 `openshell` CLI 以及可用的 Docker daemon + - 使用隔離的 `HOME` / `XDG_CONFIG_HOME`，然後銷毀測試 Gateway 和沙箱 - 實用覆寫： - - `OPENCLAW_E2E_OPENSHELL=1` 用於手動執行較完整的 e2e 測試套件時啟用此測試 - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 用於指向非預設的 CLI binary 或 wrapper script + - `OPENCLAW_E2E_OPENSHELL=1` 可在手動執行較廣泛的 e2e 套件時啟用此測試 + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 可指向非預設的 CLI 二進位檔或 wrapper script ### 即時（真實提供者 + 真實模型） - 命令：`pnpm test:live` - 設定：`vitest.live.config.ts` -- 檔案：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的 bundled-plugin 即時測試 +- 檔案：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 底下的內建 Plugin 即時測試 - 預設值：由 `pnpm test:live` **啟用**（設定 `OPENCLAW_LIVE_TEST=1`） - 範圍： - - 「這個提供者/模型 _今天_ 真的能用真實憑證運作嗎？」 - - 捕捉提供者格式變更、tool-calling quirks、驗證問題，以及速率限制行為 + - 「這個提供者/模型在 _今天_ 搭配真實憑證是否真的可用？」 + - 捕捉提供者格式變更、工具呼叫怪異行為、驗證問題，以及速率限制行為 - 預期： - - 設計上並非 CI 穩定（真實網路、真實提供者政策、配額、中斷） - - 會花錢 / 使用速率限制額度 - - 偏好執行縮小範圍的子集，而不是「全部」 -- 即時執行會 source `~/.profile` 以取得遺漏的 API keys。 -- 預設情況下，即時執行仍會隔離 `HOME`，並將設定/驗證材料複製到暫存測試 home，讓單元測試 fixture 無法修改你真實的 `~/.openclaw`。 -- 只有在你刻意需要即時測試使用真實 home directory 時，才設定 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 -- `pnpm test:live` 現在預設為較安靜的模式：保留 `[live] ...` progress output，但抑制額外的 `~/.profile` notice，並讓 gateway bootstrap logs/Bonjour chatter 靜音。如果你想要完整 startup logs，請設定 `OPENCLAW_LIVE_TEST_QUIET=0`。 -- API key 輪替（特定提供者）：使用逗號/分號格式設定 `*_API_KEYS`，或設定 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或透過 `OPENCLAW_LIVE_*_KEY` 進行每次即時執行覆寫；測試會在速率限制回應時重試。 -- 進度/heartbeat 輸出： - - 即時測試套件現在會向 stderr 發出進度行，因此即使 Vitest 主控台擷取很安靜，長時間的提供者呼叫仍可明顯看出正在活動。 - - `vitest.live.config.ts` 會停用 Vitest 主控台攔截，因此提供者/gateway 進度行會在即時執行期間立即串流。 - - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 調整 direct-model heartbeats。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 調整 gateway/probe heartbeats。 + - 依設計並非 CI 穩定（真實網路、真實提供者政策、配額、中斷） + - 會花錢 / 使用速率限制 + - 優先執行縮小範圍的子集，而不是「全部」 +- 即時執行會 source `~/.profile` 以取得缺少的 API 金鑰。 +- 預設情況下，即時執行仍會隔離 `HOME`，並將設定/驗證素材複製到暫存測試 home，讓單元 fixture 無法修改你真實的 `~/.openclaw`。 +- 只有在你刻意需要即時測試使用真實 home 目錄時，才設定 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 +- `pnpm test:live` 現在預設為較安靜的模式：它保留 `[live] ...` 進度輸出，但抑制額外的 `~/.profile` 通知，並靜音 Gateway bootstrap 記錄/Bonjour 雜訊。如果你想恢復完整啟動記錄，請設定 `OPENCLAW_LIVE_TEST_QUIET=0`。 +- API 金鑰輪替（依提供者而定）：設定 `*_API_KEYS` 使用逗號/分號格式，或設定 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或透過 `OPENCLAW_LIVE_*_KEY` 進行單次即時覆寫；測試會在速率限制回應時重試。 +- 進度/Heartbeat 輸出： + - 即時套件現在會將進度行輸出到 stderr，因此即使 Vitest 主控台擷取很安靜，長時間的提供者呼叫也會明顯顯示為作用中。 + - `vitest.live.config.ts` 會停用 Vitest 主控台攔截，因此提供者/Gateway 進度行會在即時執行期間立即串流。 + - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 調整直接模型 Heartbeat。 + - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 調整 Gateway/探測 Heartbeat。 -## 我應該執行哪個測試套件？ +## 我應該執行哪個套件？ 使用這個決策表： -- 編輯邏輯/測試：執行 `pnpm test`（如果你變更很多，另執行 `pnpm test:coverage`） -- 觸及 gateway networking / WS protocol / pairing：加上 `pnpm test:e2e` -- 偵錯「my bot is down」/ 提供者特定失敗 / tool calling：執行縮小範圍的 `pnpm test:live` +- 編輯邏輯/測試：執行 `pnpm test`（如果變更很多，另執行 `pnpm test:coverage`） +- 觸碰 Gateway 網路 / WS protocol / 配對：加入 `pnpm test:e2e` +- 偵錯「我的 bot 掛了」/ 提供者特定失敗 / 工具呼叫：執行縮小範圍的 `pnpm test:live` -## 即時（會觸及網路）測試 +## 即時（觸碰網路的）測試 -關於即時模型矩陣、CLI backend smokes、ACP smokes、Codex app-server -harness，以及所有 media-provider 即時測試（Deepgram、BytePlus、ComfyUI、image、 -music、video、media harness），再加上即時執行的憑證處理，請參閱 -[測試即時測試套件](/zh-TW/help/testing-live)。關於專用的更新與 -plugin 驗證檢查清單，請參閱 -[測試更新與 plugins](/zh-TW/help/testing-updates-plugins)。 +關於即時模型矩陣、CLI 後端煙霧測試、ACP 煙霧測試、Codex app-server +harness，以及所有媒體提供者即時測試（Deepgram、BytePlus、ComfyUI、影像、 +音樂、影片、媒體 harness）以及即時執行的憑證處理，請參閱 +[測試即時套件](/zh-TW/help/testing-live)。關於專用更新與 +Plugin 驗證檢查清單，請參閱 +[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。 -## Docker runners（選用的「可在 Linux 運作」檢查） +## Docker runner（選用的「在 Linux 中可運作」檢查） -這些 Docker runners 分成兩個類別： +這些 Docker runner 分成兩類： -- 即時模型 runners：`test:docker:live-models` 和 `test:docker:live-gateway` 只會在 repo Docker image 內執行其相符的 profile-key 即時檔案（`src/agents/models.profiles.live.test.ts` 與 `src/gateway/gateway-models.profiles.live.test.ts`），掛載你的本機 config dir 和 workspace（如果已掛載，也會 source `~/.profile`）。相符的本機 entrypoints 是 `test:live:models-profiles` 與 `test:live:gateway-profiles`。 -- Docker 即時 runners 預設使用較小的 smoke 上限，讓完整 Docker sweep 保持可行： +- 即時模型 runner：`test:docker:live-models` 和 `test:docker:live-gateway` 只會在儲存庫 Docker 映像內執行其相符 profile-key 的即時檔案（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），掛載你的本機設定目錄與工作區（如果已掛載，也會 source `~/.profile`）。相符的本機進入點是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 +- Docker 即時 runner 預設使用較小的煙霧測試上限，讓完整 Docker 掃描保持實用： `test:docker:live-models` 預設為 `OPENCLAW_LIVE_MAX_MODELS=12`，而 `test:docker:live-gateway` 預設為 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`，以及 - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。只有在你明確想要較大的詳盡掃描時，才覆寫那些 env vars。 -- `test:docker:all` 會先透過 `test:docker:live-build` 建置即時 Docker image 一次，透過 `scripts/package-openclaw-for-docker.mjs` 將 OpenClaw 打包成 npm tarball 一次，然後建置/重用兩個 `scripts/e2e/Dockerfile` images。bare image 只是用於 install/update/plugin-dependency lanes 的 Node/Git runner；那些 lanes 會掛載預先建置的 tarball。functional image 會將同一個 tarball 安裝到 `/app`，供 built-app functionality lanes 使用。Docker lane 定義位於 `scripts/lib/docker-e2e-scenarios.mjs`；planner 邏輯位於 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 會執行選定的 plan。彙總使用加權本機 scheduler：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制 process slots，而 resource caps 會避免 heavy live、npm-install，以及 multi-service lanes 全部同時啟動。如果單一 lane 比啟用中的 caps 還重，scheduler 仍可在 pool 為空時啟動它，然後讓它單獨執行，直到再次有容量可用。預設值為 10 slots、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`，以及 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；只有在 Docker host 有更多餘裕時，才調整 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。runner 預設會執行 Docker preflight、移除過期的 OpenClaw E2E containers、每 30 秒列印狀態、將成功 lane timings 儲存在 `.artifacts/docker-tests/lane-timings.json`，並在後續執行中使用這些 timings 優先啟動較長的 lanes。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可列印加權 lane manifest，而不建置或執行 Docker；或使用 `node scripts/test-docker-all.mjs --plan-json` 列印選定 lanes、package/image needs，以及 credentials 的 CI plan。 -- `Package Acceptance` 是 GitHub 原生 package gate，用於檢查「這個可安裝的 tarball 是否能作為產品運作？」它會從 `source=npm`、`source=ref`、`source=url` 或 `source=artifact` 解析一個候選 package，將其上傳為 `package-under-test`，然後對該確切 tarball 執行可重用的 Docker E2E lanes，而不是重新打包選定的 ref。Profiles 依廣度排序：`smoke`、`package`、`product` 與 `full`。請參閱[測試更新與 plugins](/zh-TW/help/testing-updates-plugins)，了解 package/update/plugin contract、published-upgrade survivor matrix、release defaults，以及 failure triage。 -- Build 與 release checks 會在 tsdown 後執行 `scripts/check-cli-bootstrap-imports.mjs`。此 guard 會從 `dist/entry.js` 與 `dist/cli/run-main.js` 走訪靜態建置 graph，如果 pre-dispatch startup 在 command dispatch 前匯入 Commander、prompt UI、undici 或 logging 等 package dependencies，就會失敗；它也會讓 bundled gateway run chunk 保持在預算內，並拒絕已知 cold gateway paths 的 static imports。Packaged CLI smoke 也涵蓋 root help、onboard help、doctor help、status、config schema，以及 model-list command。 -- Package Acceptance legacy compatibility 截止於 `2026.4.25`（包含 `2026.4.25-beta.*`）。在該截止點之前，harness 只容許已發佈 package 的 metadata gaps：省略 private QA inventory entries、缺少 `gateway install --wrapper`、tarball-derived git fixture 中缺少 patch files、缺少 persisted `update.channel`、legacy plugin install-record locations、缺少 marketplace install-record persistence，以及 `plugins update` 期間的 config metadata migration。對於 `2026.4.25` 之後的 packages，這些路徑都是嚴格失敗。 -- Container smoke runners：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:upgrade-survivor`、`test:docker:published-upgrade-survivor`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update`、`test:docker:plugin-lifecycle-matrix`，以及 `test:docker:config-reload` 會啟動一個或多個真實 containers，並驗證較高層級的整合路徑。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。當你明確需要較大的詳盡掃描時，可覆寫這些 env vars。 +- `test:docker:all` 會先透過 `test:docker:live-build` 建立即時 Docker 映像一次，透過 `scripts/package-openclaw-for-docker.mjs` 將 OpenClaw 打包成 npm tarball 一次，然後建置/重用兩個 `scripts/e2e/Dockerfile` 映像。bare 映像只是用於安裝/更新/Plugin 依賴 lane 的 Node/Git runner；這些 lane 會掛載預先建置的 tarball。functional 映像會將同一個 tarball 安裝到 `/app`，用於已建置應用程式功能 lane。Docker lane 定義位於 `scripts/lib/docker-e2e-scenarios.mjs`；規劃器邏輯位於 `scripts/lib/docker-e2e-plan.mjs`；`scripts/test-docker-all.mjs` 執行所選計畫。彙總執行使用加權本機排程器：`OPENCLAW_DOCKER_ALL_PARALLELISM` 控制程序 slot，而資源上限會避免繁重的即時、npm-install，以及多服務 lane 全部同時啟動。如果單一 lane 比作用中的上限更重，排程器在池為空時仍可啟動它，並讓它獨自持續執行，直到容量再次可用。預設值為 10 個 slot、`OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`，以及 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`；只有在 Docker 主機有更多餘裕時，才調整 `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` 或 `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`。runner 預設會執行 Docker preflight、移除過期的 OpenClaw E2E container、每 30 秒列印狀態、將成功 lane 計時儲存在 `.artifacts/docker-tests/lane-timings.json`，並在後續執行中使用這些計時優先啟動較長的 lane。使用 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 可列印加權 lane manifest，而不建置或執行 Docker；或使用 `node scripts/test-docker-all.mjs --plan-json` 列印所選 lane、package/image 需求，以及憑證的 CI 計畫。 +- `Package Acceptance` 是 GitHub 原生 package gate，用來驗證「這個可安裝 tarball 是否能作為產品運作？」它會從 `source=npm`、`source=ref`、`source=url` 或 `source=artifact` 解析一個候選 package，上傳為 `package-under-test`，然後針對該精確 tarball 執行可重用的 Docker E2E lane，而不是重新打包所選 ref。Profile 依涵蓋廣度排序：`smoke`、`package`、`product` 和 `full`。關於 package/update/Plugin 合約、已發布升級 survivor 矩陣、release 預設值，以及失敗分流，請參閱[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。 +- 建置與 release 檢查會在 tsdown 之後執行 `scripts/check-cli-bootstrap-imports.mjs`。guard 會從 `dist/entry.js` 和 `dist/cli/run-main.js` 走訪靜態建置圖，若預派送啟動流程在命令派送前匯入 Commander、prompt UI、undici 或 logging 等 package dependencies，就會失敗；它也會讓內建 Gateway run chunk 保持在預算內，並拒絕已知冷 Gateway 路徑的靜態匯入。封裝後的 CLI 煙霧測試也涵蓋 root help、onboard help、doctor help、status、config schema，以及 model-list 命令。 +- Package Acceptance 舊版相容性上限為 `2026.4.25`（包含 `2026.4.25-beta.*`）。在該截止點之前，harness 只容忍已發布 package 的 metadata 缺口：省略的 private QA inventory entries、缺少 `gateway install --wrapper`、tarball 衍生 git fixture 中缺少 patch files、缺少持久化的 `update.channel`、舊版 Plugin install-record 位置、缺少 marketplace install-record 持久化，以及 `plugins update` 期間的 config metadata 遷移。對於 `2026.4.25` 之後的 package，這些路徑都是嚴格失敗。 +- Container 煙霧測試 runner：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:update-channel-switch`、`test:docker:upgrade-survivor`、`test:docker:published-upgrade-survivor`、`test:docker:session-runtime-context`、`test:docker:agents-delete-shared-workspace`、`test:docker:gateway-network`、`test:docker:browser-cdp-snapshot`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update`、`test:docker:plugin-lifecycle-matrix`，以及 `test:docker:config-reload` 會啟動一個或多個真實 container，並驗證較高層級的整合路徑。 -即時模型 Docker runners 也只會 bind-mount 需要的 CLI auth homes（或在執行未縮小範圍時掛載所有支援的 auth homes），然後在執行前將它們複製到 container home，讓 external-CLI OAuth 可以重新整理 tokens，而不會修改 host auth store： +即時模型 Docker runner 也只會 bind-mount 所需的 CLI auth homes（或在未縮小範圍執行時掛載所有支援項目），然後在執行前將它們複製到 container home，因此外部 CLI OAuth 可以重新整理 token，而不會修改主機 auth store： - 直接模型：`pnpm test:docker:live-models`（腳本：`scripts/test-live-models-docker.sh`） -- ACP 繫結冒煙測試：`pnpm test:docker:live-acp-bind`（腳本：`scripts/test-live-acp-bind-docker.sh`；預設涵蓋 Claude、Codex 和 Gemini，並透過 `pnpm test:docker:live-acp-bind:droid` 和 `pnpm test:docker:live-acp-bind:opencode` 提供嚴格的 Droid/OpenCode 覆蓋） +- ACP 繫結冒煙測試：`pnpm test:docker:live-acp-bind`（腳本：`scripts/test-live-acp-bind-docker.sh`；預設涵蓋 Claude、Codex 和 Gemini，並透過 `pnpm test:docker:live-acp-bind:droid` 與 `pnpm test:docker:live-acp-bind:opencode` 嚴格涵蓋 Droid/OpenCode） - CLI 後端冒煙測試：`pnpm test:docker:live-cli-backend`（腳本：`scripts/test-live-cli-backend-docker.sh`） -- Codex app-server harness 冒煙測試：`pnpm test:docker:live-codex-harness`（腳本：`scripts/test-live-codex-harness-docker.sh`） +- Codex app-server 測試框架冒煙測試：`pnpm test:docker:live-codex-harness`（腳本：`scripts/test-live-codex-harness-docker.sh`） - Gateway + 開發代理：`pnpm test:docker:live-gateway`（腳本：`scripts/test-live-gateway-models-docker.sh`） -- 可觀測性冒煙測試：`pnpm qa:otel:smoke` 是私有 QA 原始碼 checkout 通道。它刻意不屬於套件 Docker 發行通道，因為 npm tarball 會省略 QA Lab。 +- 可觀測性冒煙測試：`pnpm qa:otel:smoke` 是私有 QA 原始碼簽出通道。它刻意不屬於套件 Docker 發行通道，因為 npm tarball 會省略 QA Lab。 - Open WebUI 即時冒煙測試：`pnpm test:docker:openwebui`（腳本：`scripts/e2e/openwebui-docker.sh`） -- Onboarding 精靈（TTY，完整 scaffold）：`pnpm test:docker:onboard`（腳本：`scripts/e2e/onboard-docker.sh`） -- Npm tarball onboarding/channel/agent 冒煙測試：`pnpm test:docker:npm-onboard-channel-agent` 會在 Docker 中全域安裝打包好的 OpenClaw tarball，預設透過 env-ref onboarding 設定 OpenAI 加上 Telegram，執行 doctor，並執行一次模擬的 OpenAI agent 回合。使用 `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 重用預先建置的 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳過主機重建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切換 channel。 -- 更新 channel 切換冒煙測試：`pnpm test:docker:update-channel-switch` 會在 Docker 中全域安裝打包好的 OpenClaw tarball，從套件 `stable` 切換到 git `dev`，驗證持久化的 channel 和 Plugin 更新後運作正常，接著切回套件 `stable` 並檢查更新狀態。 -- 升級存活冒煙測試：`pnpm test:docker:upgrade-survivor` 會把打包好的 OpenClaw tarball 安裝到帶有 agents、channel 設定、Plugin allowlists、過期 Plugin 相依狀態，以及既有 workspace/session 檔案的髒舊使用者 fixture 上。它會在沒有即時 provider 或 channel 金鑰的情況下執行套件更新與非互動式 doctor，接著啟動 loopback Gateway，並檢查設定/狀態保留與啟動/狀態預算。 -- 已發布升級存活冒煙測試：`pnpm test:docker:published-upgrade-survivor` 預設安裝 `openclaw@latest`，植入逼真的既有使用者檔案，用內建命令配方設定該基準線，驗證產生的設定，把該已發布安裝更新到候選 tarball，執行非互動式 doctor，寫入 `.artifacts/upgrade-survivor/summary.json`，接著啟動 loopback Gateway，並檢查已設定 intents、狀態保留、啟動、`/healthz`、`/readyz` 與 RPC 狀態預算。使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 覆寫單一基準線，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 要求彙總排程器展開精確基準線，例如 `all-since-2026.4.23`，並使用 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 展開 issue 形狀的 fixture，例如 `reported-issues`；reported-issues 集合包含 `configured-plugin-installs`，用於自動外部 OpenClaw Plugin 安裝修復。Package Acceptance 會將這些公開為 `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines` 和 `published_upgrade_survivor_scenarios`。 -- Session runtime context 冒煙測試：`pnpm test:docker:session-runtime-context` 驗證隱藏 runtime context transcript 持久化，以及 doctor 對受影響重複 prompt-rewrite 分支的修復。 -- Bun 全域安裝冒煙測試：`bash scripts/e2e/bun-global-install-smoke.sh` 會打包目前的 tree，在隔離 home 中以 `bun install -g` 安裝，並驗證 `openclaw infer image providers --json` 會回傳內建影像 providers，而不是卡住。使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 重用預先建置的 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳過主機建置，或使用 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 從已建置的 Docker 映像複製 `dist/`。 -- Installer Docker 冒煙測試：`bash scripts/test-install-sh-docker.sh` 會在其 root、update 和 direct-npm 容器之間共用一個 npm 快取。Update 冒煙測試預設以 npm `latest` 作為 stable 基準線，再升級到候選 tarball。本機可用 `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` 覆寫，或在 GitHub 上使用 Install Smoke workflow 的 `update_baseline_version` 輸入覆寫。非 root installer 檢查會保留隔離 npm 快取，讓 root 擁有的快取項目不會掩蓋使用者本機安裝行為。設定 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`，即可在本機重新執行時重用 root/update/direct-npm 快取。 -- Install Smoke CI 會以 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳過重複的 direct-npm 全域更新；需要直接 `npm install -g` 覆蓋時，請在本機不帶該 env 執行腳本。 -- Agents 刪除共享 workspace CLI 冒煙測試：`pnpm test:docker:agents-delete-shared-workspace`（腳本：`scripts/e2e/agents-delete-shared-workspace-docker.sh`）預設建置 root Dockerfile 映像，在隔離容器 home 中植入兩個 agents 與一個 workspace，執行 `agents delete --json`，並驗證有效 JSON 與保留 workspace 行為。使用 `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` 重用 install-smoke 映像。 -- Gateway 網路（兩個容器，WS 驗證 + health）：`pnpm test:docker:gateway-network`（腳本：`scripts/e2e/gateway-network-docker.sh`） -- 瀏覽器 CDP snapshot 冒煙測試：`pnpm test:docker:browser-cdp-snapshot`（腳本：`scripts/e2e/browser-cdp-snapshot-docker.sh`）會建置原始碼 E2E 映像加上一層 Chromium，使用原始 CDP 啟動 Chromium，執行 `browser doctor --deep`，並驗證 CDP role snapshots 涵蓋連結 URL、cursor-promoted clickables、iframe refs 和 frame metadata。 -- OpenAI Responses web_search minimal reasoning 回歸測試：`pnpm test:docker:openai-web-search-minimal`（腳本：`scripts/e2e/openai-web-search-minimal-docker.sh`）會透過 Gateway 執行模擬的 OpenAI server，驗證 `web_search` 會將 `reasoning.effort` 從 `minimal` 提升到 `low`，接著強制 provider schema 拒絕，並檢查原始詳細資訊是否出現在 Gateway logs 中。 -- MCP channel bridge（已植入 Gateway + stdio bridge + 原始 Claude notification-frame 冒煙測試）：`pnpm test:docker:mcp-channels`（腳本：`scripts/e2e/mcp-channels-docker.sh`） +- 入門精靈（TTY，完整鷹架）：`pnpm test:docker:onboard`（腳本：`scripts/e2e/onboard-docker.sh`） +- Npm tarball 入門/channel/agent 冒煙測試：`pnpm test:docker:npm-onboard-channel-agent` 會在 Docker 中全域安裝封裝好的 OpenClaw tarball，透過 env-ref 入門流程設定 OpenAI，並預設設定 Telegram，接著執行 doctor，並執行一次模擬的 OpenAI agent 回合。使用 `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 重用預建 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 略過主機重建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 或 `OPENCLAW_NPM_ONBOARD_CHANNEL=slack` 切換 channel。 +- 更新 channel 切換冒煙測試：`pnpm test:docker:update-channel-switch` 會在 Docker 中全域安裝封裝好的 OpenClaw tarball，從套件 `stable` 切換到 git `dev`，驗證已持久化的 channel 和 Plugin 更新後可運作，然後切回套件 `stable` 並檢查更新狀態。 +- 升級存活者冒煙測試：`pnpm test:docker:upgrade-survivor` 會在帶有 agents、channel 設定、Plugin allowlists、過期 Plugin 依賴狀態，以及現有工作區/session 檔案的髒舊使用者 fixture 上，安裝封裝好的 OpenClaw tarball。它會在沒有即時 provider 或 channel keys 的情況下執行套件更新加上非互動式 doctor，然後啟動 loopback Gateway，並檢查設定/狀態保留以及啟動/狀態預算。 +- 已發布升級存活者冒煙測試：`pnpm test:docker:published-upgrade-survivor` 預設安裝 `openclaw@latest`、植入逼真的既有使用者檔案、用內建命令配方設定該基準、驗證產生的設定、將該已發布安裝更新到候選 tarball、執行非互動式 doctor、寫入 `.artifacts/upgrade-survivor/summary.json`，然後啟動 loopback Gateway，並檢查已設定 intents、狀態保留、啟動、`/healthz`、`/readyz` 和 RPC 狀態預算。使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 覆寫一個基準，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 要求彙總排程器展開精確基準，例如 `all-since-2026.4.23`，並使用 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 展開 issue 形狀的 fixtures，例如 `reported-issues`；reported-issues 集合包含 `configured-plugin-installs`，用於自動外部 OpenClaw Plugin 安裝修復。Package Acceptance 會將這些公開為 `published_upgrade_survivor_baseline`、`published_upgrade_survivor_baselines` 和 `published_upgrade_survivor_scenarios`；Full Release Validation 會在阻斷路徑中使用預設 latest 基準，且只在 `run_release_soak=true` 或 `release_profile=full` 時展開到 all-since/reported-issues。 +- Session 執行階段 context 冒煙測試：`pnpm test:docker:session-runtime-context` 驗證隱藏執行階段 context transcript 持久化，以及 doctor 對受影響重複 prompt-rewrite 分支的修復。 +- Bun 全域安裝冒煙測試：`bash scripts/e2e/bun-global-install-smoke.sh` 會封裝目前樹狀內容，在隔離 home 中以 `bun install -g` 安裝，並驗證 `openclaw infer image providers --json` 回傳內建 image providers，而不是掛起。使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 重用預建 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 略過主機建置，或使用 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 從已建置的 Docker 映像複製 `dist/`。 +- Installer Docker 冒煙測試：`bash scripts/test-install-sh-docker.sh` 會在其 root、update 和 direct-npm 容器之間共用一個 npm 快取。更新冒煙測試預設使用 npm `latest` 作為 stable 基準，再升級到候選 tarball。在本機使用 `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` 覆寫，或在 GitHub 上使用 Install Smoke workflow 的 `update_baseline_version` 輸入覆寫。非 root installer 檢查會保留隔離的 npm 快取，因此 root 擁有的快取項目不會掩蓋使用者本機安裝行為。設定 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本機重跑時重用 root/update/direct-npm 快取。 +- Install Smoke CI 使用 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 略過重複的 direct-npm 全域更新；需要 direct `npm install -g` 涵蓋時，請在本機不帶該 env 執行腳本。 +- Agents 刪除共用工作區 CLI 冒煙測試：`pnpm test:docker:agents-delete-shared-workspace`（腳本：`scripts/e2e/agents-delete-shared-workspace-docker.sh`）預設會建置 root Dockerfile 映像，在隔離容器 home 中植入兩個 agents 和一個工作區，執行 `agents delete --json`，並驗證有效 JSON 以及工作區保留行為。使用 `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` 重用 install-smoke 映像。 +- Gateway 網路（兩個容器，WS auth + health）：`pnpm test:docker:gateway-network`（腳本：`scripts/e2e/gateway-network-docker.sh`） +- Browser CDP snapshot 冒煙測試：`pnpm test:docker:browser-cdp-snapshot`（腳本：`scripts/e2e/browser-cdp-snapshot-docker.sh`）會建置 source E2E 映像加上一層 Chromium，使用原始 CDP 啟動 Chromium，執行 `browser doctor --deep`，並驗證 CDP role snapshots 涵蓋 link URLs、cursor-promoted clickables、iframe refs 和 frame metadata。 +- OpenAI Responses web_search minimal reasoning 迴歸測試：`pnpm test:docker:openai-web-search-minimal`（腳本：`scripts/e2e/openai-web-search-minimal-docker.sh`）會透過 Gateway 執行模擬的 OpenAI server，驗證 `web_search` 將 `reasoning.effort` 從 `minimal` 提升到 `low`，然後強制 provider schema reject，並檢查原始 detail 出現在 Gateway logs 中。 +- MCP channel bridge（已植入的 Gateway + stdio bridge + 原始 Claude notification-frame 冒煙測試）：`pnpm test:docker:mcp-channels`（腳本：`scripts/e2e/mcp-channels-docker.sh`） - Pi bundle MCP tools（真實 stdio MCP server + 內嵌 Pi profile allow/deny 冒煙測試）：`pnpm test:docker:pi-bundle-mcp-tools`（腳本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） -- Cron/subagent MCP cleanup（真實 Gateway + 在隔離 Cron 和一次性 subagent 執行後拆除 stdio MCP child）：`pnpm test:docker:cron-mcp-cleanup`（腳本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） -- Plugins（針對 local path、`file:`、帶 hoisted dependencies 的 npm registry、git moving refs、ClawHub kitchen-sink、marketplace updates，以及 Claude-bundle enable/inspect 的 install/update 冒煙測試）：`pnpm test:docker:plugins`（腳本：`scripts/e2e/plugins-docker.sh`） - 設定 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可跳過 ClawHub 區塊，或使用 `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` 和 `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` 覆寫預設 kitchen-sink package/runtime 配對。沒有 `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` 時，測試會使用 hermetic 本機 ClawHub fixture server。 +- Cron/subagent MCP 清理（真實 Gateway + 在隔離 cron 與一次性 subagent 執行後拆除 stdio MCP child）：`pnpm test:docker:cron-mcp-cleanup`（腳本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） +- Plugins（local path、`file:`、帶 hoisted dependencies 的 npm registry、git moving refs、ClawHub kitchen-sink、marketplace updates，以及 Claude-bundle enable/inspect 的 install/update 冒煙測試）：`pnpm test:docker:plugins`（腳本：`scripts/e2e/plugins-docker.sh`） + 設定 `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` 可略過 ClawHub 區塊，或使用 `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` 和 `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` 覆寫預設的 kitchen-sink package/runtime 配對。若沒有 `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`，測試會使用 hermetic 本機 ClawHub fixture server。 - Plugin 更新未變更冒煙測試：`pnpm test:docker:plugin-update`（腳本：`scripts/e2e/plugin-update-unchanged-docker.sh`） -- Plugin lifecycle matrix 冒煙測試：`pnpm test:docker:plugin-lifecycle-matrix` 會在裸容器中安裝打包好的 OpenClaw tarball，安裝 npm Plugin，切換 enable/disable，透過本機 npm registry 升級與降級它，刪除已安裝程式碼，接著驗證 uninstall 仍會移除過期狀態，同時記錄每個 lifecycle 階段的 RSS/CPU 指標。 -- Config reload metadata 冒煙測試：`pnpm test:docker:config-reload`（腳本：`scripts/e2e/config-reload-source-docker.sh`） -- Plugins：`pnpm test:docker:plugins` 涵蓋針對 local path、`file:`、帶 hoisted dependencies 的 npm registry、git moving refs、ClawHub fixtures、marketplace updates，以及 Claude-bundle enable/inspect 的 install/update 冒煙測試。`pnpm test:docker:plugin-update` 涵蓋已安裝 Plugin 的未變更更新行為。`pnpm test:docker:plugin-lifecycle-matrix` 涵蓋資源追蹤的 npm Plugin 安裝、啟用、停用、升級、降級和缺失程式碼 uninstall。 +- Plugin lifecycle matrix 冒煙測試：`pnpm test:docker:plugin-lifecycle-matrix` 會在裸容器中安裝封裝好的 OpenClaw tarball、安裝 npm Plugin、切換啟用/停用、透過本機 npm registry 升級和降級它、刪除已安裝程式碼，然後驗證 uninstall 仍會移除過期狀態，同時記錄每個 lifecycle 階段的 RSS/CPU 指標。 +- 設定重新載入 metadata 冒煙測試：`pnpm test:docker:config-reload`（腳本：`scripts/e2e/config-reload-source-docker.sh`） +- Plugins：`pnpm test:docker:plugins` 涵蓋 local path、`file:`、帶 hoisted dependencies 的 npm registry、git moving refs、ClawHub fixtures、marketplace updates，以及 Claude-bundle enable/inspect 的 install/update 冒煙測試。`pnpm test:docker:plugin-update` 涵蓋已安裝 Plugins 的未變更更新行為。`pnpm test:docker:plugin-lifecycle-matrix` 涵蓋具資源追蹤的 npm Plugin install、enable、disable、upgrade、downgrade，以及 missing-code uninstall。 -若要手動預先建置並重用共享 functional 映像： +若要手動預建並重用共用 functional 映像： ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -設定時，套件特定映像覆寫（例如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`）仍會優先。當 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向遠端共享映像時，如果它尚未存在於本機，腳本會拉取該映像。QR 和 installer Docker 測試會保留自己的 Dockerfiles，因為它們驗證的是套件/安裝行為，而不是共享的已建置 app runtime。 +設定時，套件專屬映像覆寫值（例如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`）仍會優先。當 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向遠端共用映像時，如果本機尚未存在，腳本會拉取該映像。QR 和 installer Docker 測試保留自己的 Dockerfiles，因為它們驗證的是套件/安裝行為，而不是共用 built-app runtime。 -即時模型 Docker 執行器也會以唯讀方式 bind-mount 目前的 checkout，並將其 staged 到容器內的臨時工作目錄。這讓執行階段映像保持精簡，同時仍針對你的確切本機來源/config 執行 Vitest。 -staging 步驟會略過大型的僅限本機快取與 app 建置輸出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及 app 本機的 `.build` 或 Gradle 輸出目錄，讓 Docker live 執行不會花好幾分鐘複製機器特定的 artifacts。 -它們也會設定 `OPENCLAW_SKIP_CHANNELS=1`，因此 gateway live probes 不會在容器內啟動真正的 Telegram/Discord/等通道 workers。 -`test:docker:live-models` 仍會執行 `pnpm test:live`，因此當你需要從該 Docker lane 縮小或排除 gateway live 覆蓋範圍時，也要傳入 `OPENCLAW_LIVE_GATEWAY_*`。 -`test:docker:openwebui` 是較高階的相容性 smoke：它會啟動一個啟用 OpenAI 相容 HTTP endpoints 的 OpenClaw gateway 容器，啟動一個針對該 gateway 的 pinned Open WebUI 容器，透過 Open WebUI 登入，驗證 `/api/models` 暴露 `openclaw/default`，然後透過 Open WebUI 的 `/api/chat/completions` proxy 傳送真正的 chat request。 -第一次執行可能明顯較慢，因為 Docker 可能需要拉取 Open WebUI image，而 Open WebUI 也可能需要完成自己的 cold-start 設定。 -此 lane 需要可用的 live model key，而 `OPENCLAW_PROFILE_FILE`（預設為 `~/.profile`）是在 Dockerized 執行中提供它的主要方式。 -成功執行會列印一小段 JSON payload，例如 `{ "ok": true, "model": +即時模型 Docker 執行器也會以唯讀方式 bind-mount 目前 checkout，並 +將它暫存到容器內的臨時工作目錄。這可保持 runtime +映像精簡，同時仍能針對你確切的本機 source/config 執行 Vitest。 +暫存步驟會略過大型的本機專用快取與 app 建置輸出，例如 +`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及 app 本機的 `.build` 或 +Gradle 輸出目錄，因此 Docker 即時執行不會花數分鐘複製 +機器專用成品。 +它們也會設定 `OPENCLAW_SKIP_CHANNELS=1`，因此 Gateway 即時探測不會在 +容器內啟動真正的 Telegram/Discord/等 channel workers。 +`test:docker:live-models` 仍會執行 `pnpm test:live`，所以當你需要縮小或排除該 Docker lane 的 Gateway +即時覆蓋範圍時，也要傳入 `OPENCLAW_LIVE_GATEWAY_*`。 +`test:docker:openwebui` 是較高階的相容性 smoke：它會啟動一個 +已啟用 OpenAI 相容 HTTP 端點的 OpenClaw Gateway 容器， +再啟動一個釘選版本的 Open WebUI 容器連到該 Gateway，透過 +Open WebUI 登入，驗證 `/api/models` 會暴露 `openclaw/default`，然後透過 Open WebUI 的 `/api/chat/completions` proxy 傳送一個 +真正的聊天請求。 +第一次執行可能明顯較慢，因為 Docker 可能需要拉取 +Open WebUI 映像，而 Open WebUI 也可能需要完成自己的冷啟動設定。 +此 lane 預期有可用的即時模型 key，而 `OPENCLAW_PROFILE_FILE` +（預設為 `~/.profile`）是在 Docker 化執行中提供它的主要方式。 +成功執行會印出一小段 JSON payload，例如 `{ "ok": true, "model": "openclaw/default", ... }`。 -`test:docker:mcp-channels` 是刻意設計為 deterministic，且不需要真正的 Telegram、Discord 或 iMessage 帳號。它會啟動一個 seeded Gateway 容器，啟動第二個容器來 spawn `openclaw mcp serve`，然後驗證 routed conversation discovery、transcript reads、attachment metadata、live event queue behavior、outbound send routing，以及透過真正 stdio MCP bridge 傳送的 Claude-style 通道 + permission notifications。notification 檢查會直接檢查原始 stdio MCP frames，因此 smoke 驗證的是 bridge 實際發出的內容，而不只是特定 client SDK 剛好呈現的內容。 -`test:docker:pi-bundle-mcp-tools` 是 deterministic，且不需要 live model key。它會建置 repo Docker image，在容器內啟動真正的 stdio MCP probe server，透過 embedded Pi bundle MCP runtime materialize 該 server，執行 tool，然後驗證 `coding` 和 `messaging` 會保留 `bundle-mcp` tools，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 會過濾它們。 -`test:docker:cron-mcp-cleanup` 是 deterministic，且不需要 live model key。它會以真正的 stdio MCP probe server 啟動一個 seeded Gateway，執行 isolated cron turn 和 `/subagents spawn` one-shot child turn，然後驗證 MCP child process 會在每次執行後結束。 +`test:docker:mcp-channels` 是刻意設計成確定性的，且不需要 +真正的 Telegram、Discord 或 iMessage 帳號。它會啟動一個 seeded Gateway +容器，啟動第二個容器來 spawn `openclaw mcp serve`，然後 +驗證 routed conversation discovery、transcript reads、attachment metadata、 +live event queue behavior、outbound send routing，以及透過真正 stdio MCP bridge 的 Claude 風格 channel + +permission notifications。notification 檢查會直接檢查 raw stdio MCP frames， +因此此 smoke 驗證的是 bridge 實際發出的內容，而不只是特定 client SDK +剛好呈現的內容。 +`test:docker:pi-bundle-mcp-tools` 是確定性的，且不需要即時 +模型 key。它會建置 repo Docker 映像，在容器內啟動真正的 stdio MCP probe server， +透過 embedded Pi bundle MCP runtime 將該 server materialize， +執行 tool，然後驗證 `coding` 和 `messaging` 會保留 +`bundle-mcp` tools，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 會過濾它們。 +`test:docker:cron-mcp-cleanup` 是確定性的，且不需要即時模型 +key。它會啟動含有真正 stdio MCP probe server 的 seeded Gateway，執行 +隔離的 cron turn 和一個 `/subagents spawn` one-shot child turn，然後驗證 +MCP 子程序會在每次執行後結束。 -手動 ACP plain-language thread smoke（非 CI）： +手動 ACP 純語言 thread smoke（非 CI）： - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- 保留此 script 供 regression/debug 工作流程使用。ACP thread routing validation 之後可能還會需要它，因此不要刪除。 +- 保留此 script 供迴歸/除錯工作流程使用。ACP thread routing 驗證日後可能還會再次需要它，因此不要刪除。 -實用 env vars： +實用環境變數： -- `OPENCLAW_CONFIG_DIR=...`（預設：`~/.openclaw`）mounted 到 `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...`（預設：`~/.openclaw/workspace`）mounted 到 `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...`（預設：`~/.profile`）mounted 到 `/home/node/.profile`，並在執行測試前 source -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 僅驗證從 `OPENCLAW_PROFILE_FILE` sourced 的 env vars，使用臨時 config/workspace dirs，且不掛載外部 CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（預設：`~/.cache/openclaw/docker-cli-tools`）mounted 到 `/home/node/.npm-global`，供 Docker 內 cached CLI installs 使用 -- `$HOME` 下的外部 CLI auth dirs/files 會以唯讀方式 mounted 到 `/host-auth...` 下，然後在測試開始前複製到 `/home/node/...` - - 預設 dirs：`.minimax` - - 預設 files：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 縮小範圍的 provider runs 只會掛載從 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推斷需要的 dirs/files - - 以 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或逗號清單（例如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`）手動 override -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用於縮小執行範圍 -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用於在容器內過濾 providers -- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用於在不需要重建的 reruns 中重用既有的 `openclaw:local-live` image -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用於確保 creds 來自 profile store（不是 env） -- `OPENCLAW_OPENWEBUI_MODEL=...` 用於選擇 gateway 為 Open WebUI smoke 暴露的 model -- `OPENCLAW_OPENWEBUI_PROMPT=...` 用於 override Open WebUI smoke 使用的 nonce-check prompt -- `OPENWEBUI_IMAGE=...` 用於 override pinned Open WebUI image tag +- `OPENCLAW_CONFIG_DIR=...`（預設：`~/.openclaw`）掛載到 `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...`（預設：`~/.openclaw/workspace`）掛載到 `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...`（預設：`~/.profile`）掛載到 `/home/node/.profile`，並在執行測試前 source +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 僅驗證從 `OPENCLAW_PROFILE_FILE` source 的環境變數，使用臨時 config/workspace 目錄且不掛載外部 CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（預設：`~/.cache/openclaw/docker-cli-tools`）掛載到 `/home/node/.npm-global`，供 Docker 內快取 CLI installs +- `$HOME` 底下的外部 CLI auth dirs/files 會以唯讀方式掛載在 `/host-auth...` 底下，然後在測試開始前複製到 `/home/node/...` + - 預設目錄：`.minimax` + - 預設檔案：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` + - 縮小範圍的 provider 執行只會掛載從 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推斷出的必要 dirs/files + - 可用 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或像 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 這樣的 comma list 手動覆寫 +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用來縮小執行範圍 +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用來在容器內過濾 providers +- `OPENCLAW_SKIP_DOCKER_BUILD=1` 可在不需要 rebuild 的重跑中重用現有 `openclaw:local-live` 映像 +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 確保 creds 來自 profile store（而不是 env） +- `OPENCLAW_OPENWEBUI_MODEL=...` 用來選擇 Gateway 為 Open WebUI smoke 暴露的模型 +- `OPENCLAW_OPENWEBUI_PROMPT=...` 用來覆寫 Open WebUI smoke 使用的 nonce-check prompt +- `OPENWEBUI_IMAGE=...` 用來覆寫釘選的 Open WebUI image tag -## 文件 sanity +## 文件健全性檢查 -編輯文件後執行 docs checks：`pnpm check:docs`。 -當你也需要 in-page heading checks 時，執行完整的 Mintlify anchor validation：`pnpm docs:check-links:anchors`。 +文件編輯後執行 docs 檢查：`pnpm check:docs`。 +當你也需要頁面內 heading 檢查時，執行完整 Mintlify anchor validation：`pnpm docs:check-links:anchors`。 -## Offline regression（CI-safe） +## 離線迴歸（CI 安全） -這些是不使用真正 providers 的「真實 pipeline」regressions： +這些是不使用真正 providers 的「真實 pipeline」迴歸： -- Gateway tool calling（mock OpenAI，真正 gateway + agent loop）：`src/gateway/gateway.test.ts`（case: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） -- Gateway wizard（WS `wizard.start`/`wizard.next`，寫入 config + auth enforced）：`src/gateway/gateway.test.ts`（case: "runs wizard over ws and writes auth token config"） +- Gateway tool calling（mock OpenAI，真實 gateway + agent loop）：`src/gateway/gateway.test.ts`（case: "runs a mock OpenAI tool call end-to-end via gateway agent loop"） +- Gateway wizard（WS `wizard.start`/`wizard.next`，寫入 config + 強制 auth）：`src/gateway/gateway.test.ts`（case: "runs wizard over ws and writes auth token config"） -## Agent reliability evals（skills） +## Agent 可靠性評估（skills） -我們已經有一些 CI-safe tests，行為類似「agent reliability evals」： +我們已經有一些 CI 安全測試，行為類似「agent reliability evals」： -- 透過真正 gateway + agent loop 進行 Mock tool-calling（`src/gateway/gateway.test.ts`）。 -- 驗證 session wiring 與 config effects 的 end-to-end wizard flows（`src/gateway/gateway.test.ts`）。 +- 透過真實 Gateway + agent loop 的 Mock tool-calling（`src/gateway/gateway.test.ts`）。 +- 驗證 session wiring 和 config effects 的端到端 wizard flows（`src/gateway/gateway.test.ts`）。 -Skills 仍缺少的項目（見 [Skills](/zh-TW/tools/skills)）： +Skills 仍缺少的項目（請見 [Skills](/zh-TW/tools/skills)）： -- **Decisioning：**當 prompt 中列出 skills 時，agent 是否會選擇正確的 skill（或避開無關的 skill）？ -- **Compliance：**agent 是否會在使用前讀取 `SKILL.md`，並遵循 required steps/args？ -- **Workflow contracts：**multi-turn scenarios，用於 assert tool order、session history carryover，以及 sandbox boundaries。 +- **決策：** 當 prompt 中列出 skills 時，agent 是否會選擇正確的 skill（或避開不相關的 skill）？ +- **合規：** agent 是否會在使用前閱讀 `SKILL.md`，並遵循必要 steps/args？ +- **工作流程契約：** 斷言 tool order、session history carryover 和 sandbox boundaries 的多輪 scenarios。 -未來 evals 應先保持 deterministic： +未來 evals 應優先保持確定性： -- 使用 mock providers 的 scenario runner，用於 assert tool calls + order、skill file reads，以及 session wiring。 +- 使用 mock providers 的 scenario runner，用來斷言 tool calls + order、skill file reads 和 session wiring。 - 一小套以 skill 為重點的 scenarios（use vs avoid、gating、prompt injection）。 -- Optional live evals（opt-in、env-gated）僅在 CI-safe suite 到位後加入。 +- Optional live evals（opt-in、env-gated）僅在 CI 安全 suite 就位後才加入。 -## Contract tests（Plugin 與通道 shape） +## 契約測試（Plugin 和 channel shape） -Contract tests 會驗證每個已註冊的 Plugin 和通道都符合其 interface contract。它們會 iterate 所有 discovered plugins，並執行一組 shape 和 behavior assertions。預設的 `pnpm test` unit lane 會刻意略過這些 shared seam 和 smoke files；當你觸及 shared channel 或 provider surfaces 時，請明確執行 contract commands。 +契約測試會驗證每個已註冊 Plugin 和 channel 都符合其 +interface contract。它們會迭代所有 discovered plugins，並執行一套 +shape 和 behavior assertions。預設的 `pnpm test` unit lane 會刻意 +略過這些 shared seam 和 smoke files；當你觸及 shared channel 或 provider surfaces 時， +請明確執行 contract commands。 ### Commands - 所有 contracts：`pnpm test:contracts` -- 僅通道 contracts：`pnpm test:contracts:channels` -- 僅 Provider contracts：`pnpm test:contracts:plugins` +- 僅 channel contracts：`pnpm test:contracts:channels` +- 僅 provider contracts：`pnpm test:contracts:plugins` ### Channel contracts @@ -706,26 +801,26 @@ Contract tests 會驗證每個已註冊的 Plugin 和通道都符合其 interfac ### 何時執行 - 變更 plugin-sdk exports 或 subpaths 後 -- 新增或修改通道或 provider Plugin 後 +- 新增或修改 channel 或 provider Plugin 後 - 重構 Plugin registration 或 discovery 後 -Contract tests 會在 CI 執行，且不需要真正的 API keys。 +契約測試會在 CI 中執行，且不需要真正的 API keys。 -## 新增 regressions（指南） +## 新增迴歸（指引） -當你修復 live 中發現的 provider/model issue 時： +當你修復在 live 中發現的 provider/model 問題時： -- 盡可能新增 CI-safe regression（mock/stub provider，或 capture 確切的 request-shape transformation） -- 如果本質上只能 live-only（rate limits、auth policies），請讓 live test 維持 narrow，並透過 env vars opt-in -- 優先 target 能抓到 bug 的最小 layer： +- 盡可能新增 CI 安全迴歸（mock/stub provider，或捕捉確切的 request-shape transformation） +- 如果本質上只能 live 測試（rate limits、auth policies），請保持 live test 範圍狹窄，並透過 env vars opt-in +- 優先鎖定能捕捉該 bug 的最小層級： - provider request conversion/replay bug → direct models test - - gateway session/history/tool pipeline bug → gateway live smoke 或 CI-safe gateway mock test + - gateway session/history/tool pipeline bug → gateway live smoke 或 CI 安全 gateway mock test - SecretRef traversal guardrail： - - `src/secrets/exec-secret-ref-id-parity.test.ts` 會從 registry metadata（`listSecretTargetRegistryEntries()`）為每個 SecretRef class derive 一個 sampled target，然後 assert traversal-segment exec ids 會被 rejected。 - - 如果你在 `src/secrets/target-registry-data.ts` 新增新的 `includeInPlan` SecretRef target family，請更新該測試中的 `classifyTargetClass`。該測試會刻意在 unclassified target ids 上失敗，讓新 classes 無法被默默略過。 + - `src/secrets/exec-secret-ref-id-parity.test.ts` 會從 registry metadata（`listSecretTargetRegistryEntries()`）為每個 SecretRef class 推導一個 sampled target，然後斷言 traversal-segment exec ids 會被拒絕。 + - 如果你在 `src/secrets/target-registry-data.ts` 新增新的 `includeInPlan` SecretRef target family，請更新該測試中的 `classifyTargetClass`。該測試會刻意在未分類的 target ids 上失敗，讓新的 classes 不會被無聲略過。 ## 相關 -- [Testing live](/zh-TW/help/testing-live) -- [Testing updates and plugins](/zh-TW/help/testing-updates-plugins) +- [測試 live](/zh-TW/help/testing-live) +- [測試 updates 和 plugins](/zh-TW/help/testing-updates-plugins) - [CI](/zh-TW/ci) diff --git a/docs/zh-TW/plugins/bundles.md b/docs/zh-TW/plugins/bundles.md index 62ecdc4e9..0eee83773 100644 --- a/docs/zh-TW/plugins/bundles.md +++ b/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 工具等原生功能。 - bundle **不同於** 原生 OpenClaw Plugin。原生 Plugin 會在 - 處理序內執行，並且可以註冊任何能力。bundle 則是內容套件，具備 - 選擇性的功能對應，以及較窄的信任邊界。 + 套件包與 OpenClaw 原生 Plugin **不同**。原生 Plugin 會在程序內執行， + 並且可以註冊任何能力。套件包是內容套件，具有選擇性的功能對應， + 並且信任邊界較窄。 -## bundle 存在的原因 +## 為什麼存在套件包 -許多實用的 Plugin 會以 Codex、Claude 或 Cursor 格式發布。OpenClaw -不要求作者將它們重寫為原生 OpenClaw Plugin，而是偵測這些格式， -並將其支援的內容對應到原生功能集合。這表示你可以安裝 Claude 指令套件 -或 Codex skill bundle，並立即使用。 +許多實用 Plugin 會以 Codex、Claude 或 Cursor 格式發布。OpenClaw 不要求 +作者將它們重寫成 OpenClaw 原生 Plugin，而是偵測這些格式，並將其支援的 +內容對應到原生功能集。這代表你可以安裝 Claude 指令套件或 Codex skill +套件包，並立即使用。 -## 安裝 bundle +## 安裝套件包 @@ -49,13 +49,13 @@ OpenClaw 會將其對應到 Skills、hook 和 MCP 工具等原生功能。 - + ```bash openclaw plugins list openclaw plugins inspect ``` - bundle 會顯示為 `Format: bundle`，並帶有 `codex`、`claude` 或 `cursor` 子類型。 + 套件包會顯示為 `Format: bundle`，並帶有 `codex`、`claude` 或 `cursor` 子類型。 @@ -69,57 +69,55 @@ OpenClaw 會將其對應到 Skills、hook 和 MCP 工具等原生功能。 -## 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 ` 中 +- 啟用的 Claude 套件包可以提供 LSP 伺服器設定 +- OpenClaw 會載入 `.lsp.json` 以及任何 manifest 宣告的 `lspServers` 路徑 +- 套件包 LSP 設定會合併到有效的內嵌 Pi LSP 預設值中 +- 目前只有支援的 stdio 後端 LSP 伺服器可執行；不支援的傳輸仍會顯示在 `openclaw plugins inspect ` 中 ### 已偵測但不執行 -這些項目會被識別並顯示在診斷資訊中，但 OpenClaw 不會執行它們： +以下項目會被辨識並顯示在診斷中，但 OpenClaw 不會執行它們： - Claude `agents`、`hooks.json` 自動化、`outputStyles` - Cursor `.cursor/agents`、`.cursor/hooks.json`、`.cursor/rules` -- Codex inline/app 中繼資料，但能力回報除外 +- Codex 行內/app 中介資料，能力回報以外的部分 -## bundle 格式 +## 套件包格式 - + 標記：`.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。 - + 兩種偵測模式： - - **基於清單：** `.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 中的自訂元件路徑是累加式的（它們會擴充預設值，而不是取代預設值） - + 標記：`.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` 只會被偵測 @@ -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 視為其公開功能的受信任內容。 +這讓套件包預設更安全，但你仍應將第三方套件包視為其公開功能的可信內容。 ## 疑難排解 - - 執行 `openclaw plugins inspect `。如果某項能力有列出但標記為 - 尚未接線，這是產品限制，不是安裝損壞。 + + 執行 `openclaw plugins inspect `。如果某項能力已列出但標示為 + 尚未接線，那是產品限制，而不是安裝損壞。 - - 確認 bundle 已啟用，且 markdown 檔案位於偵測到的 - `commands/` 或 `skills/` root 內。 + + 請確認套件包已啟用，且 Markdown 檔案位於已偵測到的 + `commands/` 或 `skills/` 根目錄內。 - - 只支援來自 `settings.json` 的內嵌 Pi 設定。OpenClaw 不會 - 將 bundle 設定視為原始 config patch。 + + 只支援來自 `settings.json` 的內嵌 Pi 設定。OpenClaw 不會將套件包設定 + 視為原始設定修補。 - - `hooks/hooks.json` 僅偵測。如果需要可執行的 hook，請使用 - OpenClaw hook-pack 配置，或出貨原生 Plugin。 + + `hooks/hooks.json` 只會被偵測。如果你需要可執行的 hook，請使用 + OpenClaw hook 套件版面配置，或出貨原生 Plugin。 -## 相關 +## 相關內容 -- [安裝與設定 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 diff --git a/docs/zh-TW/plugins/codex-harness.md b/docs/zh-TW/plugins/codex-harness.md index 8c1e32405..b1edda596 100644 --- a/docs/zh-TW/plugins/codex-harness.md +++ b/docs/zh-TW/plugins/codex-harness.md @@ -1,43 +1,48 @@ --- read_when: - - 您想要使用隨附的 Codex app-server 測試框架 + - 你想要使用隨附的 Codex app-server 測試框架 - 你需要 Codex 執行框架設定範例 - - 你希望僅限 Codex 的部署失敗，而不是退回使用 PI -summary: 透過隨附的 Codex app-server 測試框架執行 OpenClaw 嵌入式代理回合 + - 你希望僅使用 Codex 的部署失敗，而不是回退到 PI +summary: 透過隨附的 Codex 應用程式伺服器測試框架執行 OpenClaw 嵌入式代理回合 title: Codex 執行框架 x-i18n: - generated_at: "2026-05-03T21:37:25Z" + generated_at: "2026-05-05T01:48:08Z" model: gpt-5.5 provider: openai - source_hash: f5187e54e2dc94e511c0243227f741d3486669f595c2b15cf239b1c03ea466c8 + source_hash: 76302351e7e162e858dd6e3cffca84b3fd54497dd060104da9f90fe4c1a33f9b source_path: plugins/codex-harness.md workflow: 16 --- -內建的 `codex` Plugin 讓 OpenClaw 透過 Codex app-server 執行嵌入式代理回合，而不是使用內建的 PI harness。 +隨附的 `codex` Plugin 可讓 OpenClaw 透過 Codex app-server 執行嵌入式 agent turn，而不是使用內建的 PI harness。 -當你希望由 Codex 擁有底層代理工作階段時，請使用此功能：模型探索、原生執行緒恢復、原生 Compaction，以及 app-server 執行。OpenClaw 仍然擁有聊天頻道、工作階段檔案、模型選擇、工具、核准、媒體傳遞，以及可見轉錄鏡像。 +當你希望 Codex 擁有低階 agent session 時，請使用此方式：模型探索、原生 thread resume、原生 compaction，以及 app-server execution。OpenClaw 仍然擁有 chat channels、session files、model selection、tools、approvals、media delivery，以及可見 transcript mirror。 -當來源聊天回合透過 Codex harness 執行時，若部署尚未明確設定 `messages.visibleReplies`，可見回覆預設會使用 OpenClaw `message` 工具。代理仍可私下完成其 Codex 回合；只有在呼叫 `message(action="send")` 時才會發佈到頻道。將 `messages.visibleReplies: "automatic"` 設為保留直接聊天最終回覆的舊版自動傳遞路徑。 +當來源 chat turn 透過 Codex harness 執行時，如果部署尚未明確設定 `messages.visibleReplies`，可見回覆預設會使用 OpenClaw `message` tool。agent 仍可私下完成其 Codex turn；只有在呼叫 `message(action="send")` 時才會發佈到 channel。將 `messages.visibleReplies: "automatic"` 設為保留 direct-chat final replies 使用舊版自動傳遞路徑。 -Codex Heartbeat 回合預設也會取得 `heartbeat_respond` 工具，因此代理可以記錄這次喚醒應保持安靜或發出通知，而不必在最終文字中編碼該控制流程。 +Codex heartbeat turns 預設也會取得 `heartbeat_respond` tool，因此 agent 可以記錄這次喚醒應保持安靜還是發出通知，而不必把該控制流程編碼在 final text 中。 -Heartbeat 專用的主動性指引會作為 Codex 協作模式開發者指令，傳送到 Heartbeat 回合本身。一般聊天回合會還原 Codex Default 模式，而不是在其正常執行階段提示中攜帶 Heartbeat 哲學。 +Heartbeat 專用的 initiative guidance 會在 heartbeat turn 本身作為 Codex collaboration-mode developer instruction 傳送。一般 chat turns 會還原 Codex Default mode，而不是在其一般 runtime prompt 中攜帶 heartbeat philosophy。 -如果你正在嘗試建立方向感，請從[代理執行階段](/zh-TW/concepts/agent-runtimes)開始。簡短來說： -`openai/gpt-5.5` 是模型參照，`codex` 是執行階段，而 Telegram、Discord、Slack 或其他頻道仍是通訊介面。 +如果你正在嘗試建立方向感，請從 +[Agent runtimes](/zh-TW/concepts/agent-runtimes) 開始。簡短版本是： +`openai/gpt-5.5` 是 model ref，`codex` 是 runtime，而 Telegram、 +Discord、Slack 或其他 channel 仍然是 communication surface。 ## 快速設定 -多數想要「Codex in OpenClaw」的使用者需要這條路徑：使用 ChatGPT/Codex 訂閱登入，然後透過原生 Codex app-server 執行階段執行嵌入式代理回合。模型參照仍維持 `openai/gpt-*` 作為標準；訂閱驗證來自 Codex 帳戶/設定檔，而不是來自 `openai-codex/*` 模型前綴。 +大多數想要「Codex in OpenClaw」的使用者會想要這條路徑：使用 +ChatGPT/Codex 訂閱登入，然後透過原生 Codex app-server runtime 執行嵌入式 agent turns。model ref 仍維持正規形式 +`openai/gpt-*`；subscription auth 來自 Codex account/profile，而不是來自 +`openai-codex/*` model prefix。 -如果尚未登入，請先使用 Codex OAuth 登入： +如果你尚未登入，請先使用 Codex OAuth 登入： ```bash openclaw models auth login --provider openai-codex ``` -接著啟用內建的 `codex` Plugin，並強制使用 Codex 執行階段： +然後啟用隨附的 `codex` Plugin，並強制使用 Codex runtime： ```json5 { @@ -59,7 +64,7 @@ openclaw models auth login --provider openai-codex } ``` -如果你的設定使用 `plugins.allow`，也請在其中包含 `codex`： +如果你的設定使用 `plugins.allow`，也要在其中包含 `codex`： ```json5 { @@ -74,132 +79,199 @@ openclaw models auth login --provider openai-codex } ``` -當你指的是原生 Codex 執行階段時，不要使用 `openai-codex/gpt-*`。該前綴是明確的「透過 PI 使用 Codex OAuth」路徑。設定變更會套用到新的或重設的工作階段；現有工作階段會保留其已記錄的執行階段。 +當你指的是原生 Codex runtime 時，不要使用 `openai-codex/gpt-*`。該 prefix +是明確的「Codex OAuth through PI」路徑。設定變更會套用到新的或 reset sessions；既有 sessions 會保留其已記錄的 runtime。 -## 這個 Plugin 會改變什麼 +## 此 Plugin 變更的內容 -內建的 `codex` Plugin 提供幾項彼此獨立的能力： +隨附的 `codex` Plugin 提供數個獨立能力： -| 能力 | 使用方式 | 作用 | +| 能力 | 你如何使用 | 它的作用 | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| 原生嵌入式執行階段 | `agentRuntime.id: "codex"` | 透過 Codex app-server 執行 OpenClaw 嵌入式代理回合。 | -| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 從訊息對話綁定並控制 Codex app-server 執行緒。 | -| Codex app-server 提供者/目錄 | `codex` internals, surfaced through the harness | 讓執行階段探索並驗證 app-server 模型。 | -| Codex 媒體理解路徑 | `codex/*` image-model compatibility paths | 針對支援的影像理解模型執行有界的 Codex app-server 回合。 | -| 原生 hook 轉送 | Plugin hooks around Codex-native events | 讓 OpenClaw 觀察/阻擋支援的 Codex 原生工具/最終化事件。 | +| 原生嵌入式 runtime | `agentRuntime.id: "codex"` | 透過 Codex app-server 執行 OpenClaw 嵌入式 agent turns。 | +| 原生 chat-control commands | `/codex bind`, `/codex resume`, `/codex steer`, ... | 從 messaging conversation 綁定並控制 Codex app-server threads。 | +| Codex app-server provider/catalog | `codex` internals, surfaced through the harness | 讓 runtime 探索並驗證 app-server models。 | +| Codex media-understanding path | `codex/*` image-model compatibility paths | 為支援的 image understanding models 執行有界的 Codex app-server turns。 | +| 原生 hook relay | Plugin hooks around Codex-native events | 讓 OpenClaw 觀察/封鎖支援的 Codex-native tool/finalization events。 | 啟用 Plugin 會讓這些能力可用。它**不會**： -- 開始對每個 OpenAI 模型使用 Codex -- 將 `openai-codex/*` 模型參照轉換為原生執行階段 -- 讓 ACP/acpx 成為預設的 Codex 路徑 -- 熱切換已記錄 PI 執行階段的現有工作階段 -- 取代 OpenClaw 頻道傳遞、工作階段檔案、驗證設定檔儲存，或訊息路由 +- 開始對每個 OpenAI model 使用 Codex +- 將 `openai-codex/*` model refs 轉換為原生 runtime +- 讓 ACP/acpx 成為預設 Codex path +- 熱切換已經記錄 PI runtime 的既有 sessions +- 取代 OpenClaw channel delivery、session files、auth-profile storage 或 + message routing -同一個 Plugin 也擁有原生 `/codex` 聊天控制命令介面。如果 Plugin 已啟用，且使用者要求從聊天中綁定、恢復、導向、停止或檢查 Codex 執行緒，代理應優先使用 `/codex ...` 而不是 ACP。當使用者要求 ACP/acpx 或正在測試 ACP Codex 配接器時，ACP 仍是明確的備援。 +同一個 Plugin 也擁有原生 `/codex` chat-control command surface。如果 +Plugin 已啟用，且使用者要求從 chat 綁定、resume、steer、停止或檢查 +Codex threads，agents 應優先使用 `/codex ...`，而不是 ACP。當使用者要求 +ACP/acpx 或正在測試 ACP Codex adapter 時，ACP 仍是明確的 fallback。 -原生 Codex 回合會保留 OpenClaw Plugin hooks 作為公開相容層。這些是處理序內的 OpenClaw hooks，不是 Codex `hooks.json` 命令 hooks： +原生 Codex turns 會保留 OpenClaw Plugin hooks 作為公開相容層。這些是 +in-process OpenClaw hooks，而不是 Codex `hooks.json` command hooks： - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` 用於鏡像轉錄記錄 -- `before_agent_finalize` 透過 Codex `Stop` 轉送 +- `before_message_write` for mirrored transcript records +- `before_agent_finalize` through Codex `Stop` relay - `agent_end` -Plugin 也可以註冊執行階段中立的工具結果中介軟體，在 OpenClaw 執行工具後、結果傳回 Codex 前，重寫 OpenClaw 動態工具結果。這與公開的 `tool_result_persist` Plugin hook 分開，後者會轉換 OpenClaw 擁有的轉錄工具結果寫入。 +Plugins 也可以註冊 runtime-neutral tool-result middleware，用於在 OpenClaw +執行 tool 之後、result 返回 Codex 之前，重寫 OpenClaw dynamic tool results。這與公開的 +`tool_result_persist` Plugin hook 分開；後者會轉換 OpenClaw 擁有的 transcript +tool-result writes。 -如需 Plugin hook 語義本身，請參閱 [Plugin hooks](/zh-TW/plugins/hooks) 和 [Plugin 防護行為](/zh-TW/tools/plugin)。 +若要了解 Plugin hook semantics 本身，請參閱 [Plugin hooks](/zh-TW/plugins/hooks) +和 [Plugin guard behavior](/zh-TW/tools/plugin)。 -此 harness 預設為關閉。新設定應維持 OpenAI 模型參照以 `openai/gpt-*` 作為標準，並在需要原生 app-server 執行時，明確強制使用 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。舊版 `codex/*` 模型參照仍會為了相容性自動選取 harness，但以執行階段支援的舊版提供者前綴不會顯示為一般模型/提供者選項。 +harness 預設為關閉。新設定應將 OpenAI model refs 保持為正規形式 +`openai/gpt-*`，並在想要原生 app-server execution 時明確強制使用 +`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。舊版 +`codex/*` model refs 仍會為了相容性而自動選取 harness，但 runtime-backed +legacy provider prefixes 不會顯示為一般 model/provider choices。 -如果 `codex` Plugin 已啟用，但主要模型仍是 `openai-codex/*`，`openclaw doctor` 會提出警告，而不是變更路徑。這是刻意設計：`openai-codex/*` 仍是 PI Codex OAuth/訂閱路徑，而原生 app-server 執行仍是明確的執行階段選擇。 +如果 `codex` Plugin 已啟用，但 primary model 仍是 +`openai-codex/*`，`openclaw doctor` 會發出警告，而不是變更路徑。這是刻意的： +`openai-codex/*` 仍然是 PI Codex OAuth/subscription path，而原生 app-server +execution 仍是明確的 runtime choice。 -## 路徑對照 +## 路徑對照表 變更設定前請使用此表： -| 期望行為 | 模型參照 | 執行階段設定 | 驗證/設定檔路徑 | 預期狀態標籤 | -| ---------------------------------------------------- | -------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- | -| 搭配原生 Codex 執行階段的 ChatGPT/Codex 訂閱 | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth 或 Codex 帳戶 | `Runtime: OpenAI Codex` | -| 透過一般 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | omitted or `runtime: "pi"` | OpenAI API key | `Runtime: OpenClaw Pi Default` | -| 透過 PI 使用 ChatGPT/Codex 訂閱 | `openai-codex/gpt-*` | omitted or `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | -| 搭配保守自動模式的混合提供者 | provider-specific refs | `agentRuntime.id: "auto"` | Per selected provider | Depends on selected runtime | -| 明確的 Codex ACP 配接器工作階段 | ACP prompt/model dependent | `sessions_spawn` with `runtime: "acp"` | ACP backend auth | ACP task/session status | +| 期望行為 | Model ref | Runtime config | Auth/profile route | Expected status label | +| ---------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | +| 使用原生 Codex runtime 的 ChatGPT/Codex 訂閱 | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth 或 Codex account | `Runtime: OpenAI Codex` | +| 透過一般 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | omitted or `runtime: "pi"` | OpenAI API key | `Runtime: OpenClaw Pi Default` | +| 透過 PI 使用 ChatGPT/Codex 訂閱 | `openai-codex/gpt-*` | omitted or `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | +| 使用保守 auto mode 的混合 providers | provider-specific refs | `agentRuntime.id: "auto"` | Per selected provider | Depends on selected runtime | +| 明確的 Codex ACP adapter session | ACP prompt/model dependent | `sessions_spawn` with `runtime: "acp"` | ACP backend auth | ACP task/session status | -重點差異是提供者與執行階段： +重要的區分是 provider 與 runtime： -- `openai-codex/*` 回答「PI 應使用哪個提供者/驗證路徑？」 -- `agentRuntime.id: "codex"` 回答「哪個迴圈應執行這個嵌入式回合？」 -- `/codex ...` 回答「這個聊天應綁定或控制哪個原生 Codex 對話？」 -- ACP 回答「acpx 應啟動哪個外部 harness 處理序？」 +- `openai-codex/*` 回答「PI 應該使用哪個 provider/auth route？」 +- `agentRuntime.id: "codex"` 回答「哪個 loop 應該執行這個 + embedded turn？」 +- `/codex ...` 回答「此 chat 應該綁定或控制哪個原生 Codex conversation？」 +- ACP 回答「acpx 應該啟動哪個 external harness process？」 -## 選擇正確的模型前綴 +## 選擇正確的 model prefix -OpenAI 系列路徑依前綴區分。對於常見的訂閱加原生 Codex 執行階段設定，請使用 `openai/*` 搭配 `agentRuntime.id: "codex"`。只有在你刻意要透過 PI 使用 Codex OAuth 時，才使用 `openai-codex/*`： +OpenAI-family routes 是 prefix-specific。對常見的訂閱加原生 Codex runtime +設定，請使用 `openai/*` 搭配 `agentRuntime.id: "codex"`。只有在你刻意要透過 +PI 使用 Codex OAuth 時，才使用 `openai-codex/*`： -| 模型參照 | 執行階段路徑 | 使用時機 | -| --------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | -| `openai/gpt-5.4` | 透過 OpenClaw/PI 管線使用 OpenAI 提供者 | 你要以 `OPENAI_API_KEY` 使用目前的直接 OpenAI Platform API 存取。 | -| `openai-codex/gpt-5.5` | 透過 OpenClaw/PI 使用 OpenAI Codex OAuth | 你要以預設 PI runner 使用 ChatGPT/Codex 訂閱驗證。 | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你要以原生 Codex 執行使用 ChatGPT/Codex 訂閱驗證。 | +| Model ref | Runtime path | 使用時機 | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | OpenAI provider through OpenClaw/PI plumbing | 你想要使用目前透過 `OPENAI_API_KEY` 的直接 OpenAI Platform API 存取。 | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth through OpenClaw/PI | 你想要使用 ChatGPT/Codex subscription auth 搭配預設 PI runner。 | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你想要使用 ChatGPT/Codex subscription auth 搭配原生 Codex execution。 | -當你的帳戶公開這些路徑時，GPT-5.5 可以同時出現在直接 OpenAI API-key 與 Codex 訂閱路徑上。原生 Codex 執行階段請使用 `openai/gpt-5.5` 搭配 Codex app-server harness；PI OAuth 請使用 `openai-codex/gpt-5.5`；直接 API-key 流量請使用沒有 Codex 執行階段覆寫的 `openai/gpt-5.5`。 +當你的 account 公開這些路徑時，GPT-5.5 可以同時出現在直接 OpenAI API-key +與 Codex subscription routes 上。原生 Codex runtime 請使用 `openai/gpt-5.5` +搭配 Codex app-server harness；PI OAuth 請使用 `openai-codex/gpt-5.5`；直接 +API-key traffic 請使用未覆寫 Codex runtime 的 `openai/gpt-5.5`。 -舊版 `codex/gpt-*` 參照仍作為相容別名接受。Doctor 相容性遷移會將舊版主要執行階段參照重寫為標準模型參照，並分開記錄執行階段政策，而僅作為備援的舊版參照會保持不變，因為執行階段是為整個代理容器設定。新的 PI Codex OAuth 設定應使用 `openai-codex/gpt-*`；新的原生 app-server harness 設定應使用 `openai/gpt-*` 加上 `agentRuntime.id: "codex"`。 +舊版 `codex/gpt-*` refs 仍會作為 compatibility aliases 被接受。Doctor +compatibility migration 會將舊版 primary runtime refs 重寫為正規 model +refs，並另外記錄 runtime policy；而 fallback-only legacy refs 會保持不變，因為 runtime +是針對整個 agent container 設定。新的 PI Codex OAuth 設定應使用 +`openai-codex/gpt-*`；新的原生 app-server harness 設定應使用 +`openai/gpt-*` 加上 `agentRuntime.id: "codex"`。 -`agents.defaults.imageModel` 遵循相同的前綴區分。當影像理解應透過 OpenAI Codex OAuth 提供者路徑執行時，請使用 `openai-codex/gpt-*`。當影像理解應透過有界的 Codex app-server 回合執行時，請使用 `codex/gpt-*`。Codex app-server 模型必須宣告支援影像輸入；純文字 Codex 模型會在媒體回合開始前失敗。 +`agents.defaults.imageModel` 遵循相同的 prefix 區分。當 image understanding +應透過 OpenAI Codex OAuth provider path 執行時，請使用 +`openai-codex/gpt-*`。當 image understanding 應透過有界的 Codex +app-server turn 執行時，請使用 `codex/gpt-*`。Codex app-server model 必須宣告支援 +image input；text-only Codex models 會在 media turn 開始前失敗。 -使用 `/status` 確認目前工作階段的有效 harness。如果選擇結果出乎意料，請啟用 `agents/harness` 子系統的除錯記錄，並檢查 Gateway 的結構化 `agent harness selected` 記錄。它包含選取的 harness id、選取原因、執行階段/備援政策，以及在 `auto` 模式中每個 Plugin 候選項目的支援結果。 +使用 `/status` 確認目前 session 的有效 harness。如果選擇結果令人意外，請為 +`agents/harness` subsystem 啟用 debug logging，並檢查 gateway 的 structured +`agent harness selected` record。它包含 selected harness id、selection reason、 +runtime/fallback policy，以及在 `auto` mode 中每個 Plugin candidate 的 support result。 -### Doctor 警告代表什麼 +### doctor warnings 的意思 -當以下全部為真時，`openclaw doctor` 會提出警告： +當以下全部為真時，`openclaw doctor` 會發出警告： -- 內建的 `codex` Plugin 已啟用或允許 -- 代理的主要模型是 `openai-codex/*` -- 該代理的有效執行階段不是 `codex` +- 隨附的 `codex` Plugin 已啟用或允許 +- agent 的 primary model 是 `openai-codex/*` +- 該 agent 的 effective runtime 不是 `codex` -此警告存在，是因為使用者常預期「Codex Plugin 已啟用」代表「原生 Codex app-server 執行階段」。OpenClaw 不會做出這個跳躍。此警告表示： +此警告存在，是因為使用者常預期「已啟用 Codex Plugin」就代表「原生 Codex app-server runtime」。OpenClaw 不會做出這種推斷。此警告表示： - 如果你原本就打算透過 PI 使用 ChatGPT/Codex OAuth，則**不需要變更**。 -- 如果你打算使用原生 app-server 執行，請將模型變更為 `openai/`，並設定 `agentRuntime.id: "codex"`。 -- 執行階段變更後，現有工作階段仍需要 `/new` 或 `/reset`，因為工作階段執行階段釘選是黏著的。 +- 如果你原本打算使用原生 app-server execution，請將 model 改為 + `openai/`，並設定 `agentRuntime.id: "codex"`。 +- runtime 變更後，既有 sessions 仍需要 `/new` 或 `/reset`，因為 session runtime + pins 是 sticky。 -Harness 選擇不是即時工作階段控制。當嵌入式回合執行時，OpenClaw 會在該工作階段記錄所選的 harness id，並在同一工作階段 id 的後續回合中繼續使用。當你希望未來工作階段使用另一個 harness 時，請變更 `agentRuntime` 設定或 `OPENCLAW_AGENT_RUNTIME`；在既有對話於 PI 與 Codex 之間切換前，請使用 `/new` 或 `/reset` 啟動新的工作階段。這可避免透過兩個不相容的原生工作階段系統重放同一份轉錄。 +Harness selection 不是 live session control。當 embedded turn 執行時，OpenClaw +會在該 session 上記錄 selected harness id，並在同一 session id 的後續 turns +持續使用它。當你希望未來 sessions 使用另一個 harness 時，請變更 `agentRuntime` +設定或 `OPENCLAW_AGENT_RUNTIME`；在既有 conversation 於 PI 與 Codex 之間切換前，請使用 +`/new` 或 `/reset` 開始新的 session。這可避免透過兩個不相容的原生 session systems +重播同一份 transcript。 -在 harness 固定機制推出前建立的舊版工作階段，只要已有 transcript 歷史，就會被視為已固定到 PI。變更設定後，請使用 `/new` 或 `/reset` 讓該對話改用 Codex。 +舊版工作階段在 harness pin 推出前建立，只要已有逐字稿歷史， +就會視為已釘選到 PI。變更設定後，使用 `/new` 或 `/reset` 讓該對話改用 +Codex。 -`/status` 會顯示實際生效的模型 runtime。預設 PI harness 會顯示為 `Runtime: OpenClaw Pi Default`，Codex app-server harness 則會顯示為 `Runtime: OpenAI Codex`。 +`/status` 會顯示有效的模型執行環境。預設 PI harness 顯示為 +`Runtime: OpenClaw Pi Default`，Codex app-server harness 顯示為 +`Runtime: OpenAI Codex`。 ## 需求 -- OpenClaw，且隨附的 `codex` Plugin 可用。 -- Codex app-server `0.125.0` 或更新版本。隨附的 Plugin 預設會管理相容的 Codex app-server binary，因此 `PATH` 上的本機 `codex` 指令不會影響一般 harness 啟動。 -- app-server 程序或 OpenClaw 的 Codex auth bridge 可使用 Codex 驗證。本機 app-server 啟動會為每個 agent 使用由 OpenClaw 管理的 Codex home，以及隔離的子程序 `HOME`，因此預設不會讀取你的個人 `~/.codex` 帳戶、skills、plugins、config、thread state，或原生 `$HOME/.agents/skills`。 +- 可使用隨附 `codex` Plugin 的 OpenClaw。 +- Codex app-server `0.125.0` 或更新版本。隨附 Plugin 預設會管理相容的 + Codex app-server 二進位檔，因此 `PATH` 上的本機 `codex` 指令不會影響一般 + harness 啟動。 +- app-server 程序或 OpenClaw 的 Codex 驗證橋接可用的 Codex 驗證。 + 本機 app-server 啟動會為每個 agent 使用 OpenClaw 管理的 Codex home + 以及隔離的子程序 `HOME`，因此預設不會讀取你的個人 + `~/.codex` 帳號、skills、plugins、設定、thread 狀態，或原生 + `$HOME/.agents/skills`。 -Plugin 會封鎖較舊或未標版本的 app-server handshake。這能讓 OpenClaw 維持在已測試過的 protocol surface 上。 +Plugin 會封鎖較舊或未版本化的 app-server 交握。這能讓 +OpenClaw 保持在已測試過的通訊協定表面上。 -對於 live 和 Docker smoke tests，auth 通常來自 Codex CLI 帳戶或 OpenClaw `openai-codex` auth profile。本機 stdio app-server 啟動在沒有帳戶時，也可以 fallback 到 `CODEX_API_KEY` / `OPENAI_API_KEY`。 +對於即時與 Docker smoke 測試，驗證通常來自 Codex CLI 帳號 +或 OpenClaw `openai-codex` 驗證設定檔。當沒有帳號時，本機 stdio app-server +啟動也可以退回使用 `CODEX_API_KEY` / `OPENAI_API_KEY`。 -## 工作區 bootstrap 檔案 +## 工作區啟動檔案 -Codex 會透過原生 project-doc discovery 自行處理 `AGENTS.md`。OpenClaw 不會寫入合成的 Codex project-doc 檔案，也不依賴 Codex fallback 檔名作為 persona files，因為 Codex fallbacks 只會在缺少 `AGENTS.md` 時套用。 +Codex 會透過原生專案文件探索自行處理 `AGENTS.md`。OpenClaw +不會寫入合成的 Codex 專案文件檔案，也不依賴 Codex persona 檔案的後援 +檔名，因為 Codex 後援只會在缺少 `AGENTS.md` 時套用。 -為了保持 OpenClaw 工作區一致性，Codex harness 會解析其他 bootstrap 檔案（存在時包含 `SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` 和 `MEMORY.md`），並在 `thread/start` 和 `thread/resume` 時透過 Codex config instructions 轉送。這會讓 `SOUL.md` 和相關工作區 persona/profile context 保持可見，而不需要複製 `AGENTS.md`。 +為了 OpenClaw 工作區一致性，Codex harness 會解析其他啟動檔案 +（存在時包括 `SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、 +`BOOTSTRAP.md` 和 `MEMORY.md`），並在 `thread/start` 和 `thread/resume` +透過 Codex 設定指令轉送。這會讓 `SOUL.md` 和相關工作區 persona/profile +內容可見，而不需複製 `AGENTS.md`。 -## 將 Codex 加到其他模型旁邊 +## 將 Codex 與其他模型並用 -如果同一個 agent 應該能在 Codex 和非 Codex provider models 之間自由切換，請不要全域設定 `agentRuntime.id: "codex"`。強制 runtime 會套用到該 agent 或 session 的每個 embedded turn。如果在該 runtime 被強制時選取 Anthropic model，OpenClaw 仍會嘗試使用 Codex harness，並以 fail closed 結束，而不是默默將該 turn 路由 through PI。 +如果同一個 agent 應能在 Codex 與非 Codex provider 模型之間自由切換， +不要全域設定 `agentRuntime.id: "codex"`。強制執行環境會套用到該 agent +或工作階段的每個嵌入式回合。如果在強制使用該執行環境時選取 Anthropic +模型，OpenClaw 仍會嘗試 Codex harness 並關閉失敗，而不是靜默地將該回合 +透過 PI 路由。 -請改用以下其中一種形態： +請改用以下其中一種形式： - 將 Codex 放在具有 `agentRuntime.id: "codex"` 的專用 agent 上。 -- 將預設 agent 保持在 `agentRuntime.id: "auto"`，並使用 PI fallback 進行一般混合 provider 使用。 -- 只為相容性使用舊版 `codex/*` refs。新設定應偏好 `openai/*` 加上明確的 Codex runtime policy。 +- 將預設 agent 保持在 `agentRuntime.id: "auto"`，並為一般混合 + provider 使用保留 PI 後援。 +- 僅為相容性使用舊版 `codex/*` 參照。新設定應偏好 + `openai/*` 加上明確的 Codex 執行環境政策。 -例如，以下會讓預設 agent 維持一般自動選取，並新增一個獨立的 Codex agent： +例如，這會讓預設 agent 保持一般自動選取，並新增獨立的 Codex agent： ```json5 { @@ -235,33 +307,37 @@ Codex 會透過原生 project-doc discovery 自行處理 `AGENTS.md`。OpenClaw } ``` -使用此形態時： +使用此形式時： -- 預設 `main` agent 會使用一般 provider path 和 PI compatibility fallback。 +- 預設 `main` agent 會使用一般 provider 路徑和 PI 相容性後援。 - `codex` agent 會使用 Codex app-server harness。 -- 如果 `codex` agent 缺少 Codex 或不支援 Codex，該 turn 會失敗，而不是悄悄使用 PI。 +- 如果 `codex` agent 缺少 Codex 或不支援 Codex，該回合會失敗， + 而不是悄悄使用 PI。 ## Agent 指令路由 -Agents 應該依意圖路由使用者請求，而不是只看「Codex」這個字： +Agent 應依意圖路由使用者請求，而不只依據「Codex」一詞： -| 使用者要求... | Agent 應使用... | +| 使用者要求... | Agent 應使用... | | ------------------------------------------------------ | ------------------------------------------------ | -| 「將此 chat 綁定到 Codex」 | `/codex bind` | -| 「在這裡恢復 Codex thread ``」 | `/codex resume ` | +| 「將此聊天綁定到 Codex」 | `/codex bind` | +| 「在這裡接續 Codex thread ``」 | `/codex resume ` | | 「顯示 Codex threads」 | `/codex threads` | -| 「為一次不良 Codex run 提交 support report」 | `/diagnostics [note]` | -| 「只針對這個附加 thread 傳送 Codex feedback」 | `/codex diagnostics [note]` | -| 「以 Codex runtime 使用我的 ChatGPT/Codex 訂閱」 | `openai/*` 加上 `agentRuntime.id: "codex"` | +| 「為不良的 Codex 執行提交支援報告」 | `/diagnostics [note]` | +| 「只針對這個附加的 thread 傳送 Codex 意見回饋」 | `/codex diagnostics [note]` | +| 「透過 Codex runtime 使用我的 ChatGPT/Codex 訂閱」 | `openai/*` 加上 `agentRuntime.id: "codex"` | | 「透過 PI 使用我的 ChatGPT/Codex 訂閱」 | `openai-codex/*` model refs | -| 「透過 ACP/acpx 執行 Codex」 | ACP `sessions_spawn({ runtime: "acp", ... })` | +| 「透過 ACP/acpx 執行 Codex」 | ACP `sessions_spawn({ runtime: "acp", ... })` | | 「在 thread 中啟動 Claude Code/Gemini/OpenCode/Cursor」 | ACP/acpx，而不是 `/codex`，也不是原生 sub-agents | -OpenClaw 只會在 ACP 已啟用、可 dispatch，且由已載入的 runtime backend 支援時，才向 agents 公告 ACP spawn guidance。如果 ACP 不可用，system prompt 和 plugin skills 不應教 agent ACP routing。 +OpenClaw 只會在 ACP 已啟用、可分派，且由已載入的執行環境後端支援時， +向 agent 宣告 ACP 產生指引。如果 ACP 不可用，系統提示和 Plugin skills +不應教導 agent 關於 ACP 路由。 -## Codex-only 部署 +## 僅 Codex 部署 -當你需要證明每個 embedded agent turn 都使用 Codex 時，請強制使用 Codex harness。明確的 Plugin runtimes 會 fail closed，絕不會默默 through PI 重試： +當你需要證明每個嵌入式 agent 回合都使用 Codex 時，請強制使用 Codex +harness。明確的 Plugin 執行環境會關閉失敗，絕不會靜默地透過 PI 重試： ```json5 { @@ -282,11 +358,13 @@ OpenClaw 只會在 ACP 已啟用、可 dispatch，且由已載入的 runtime bac OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -強制使用 Codex 時，如果 Codex Plugin 已停用、app-server 太舊，或 app-server 無法啟動，OpenClaw 會提早失敗。 +強制使用 Codex 時，如果 Codex Plugin 已停用、app-server 太舊， +或 app-server 無法啟動，OpenClaw 會提早失敗。 ## 個別 agent 的 Codex -你可以讓一個 agent 只使用 Codex，而預設 agent 保持一般 auto-selection： +你可以讓一個 agent 只使用 Codex，同時讓預設 agent 保持一般 +自動選取： ```json5 { @@ -315,17 +393,21 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -使用一般 session commands 切換 agents 和 models。`/new` 會建立新的 OpenClaw session，Codex harness 會視需要建立或恢復它的 sidecar app-server thread。`/reset` 會清除該 thread 的 OpenClaw session binding，並讓下一個 turn 再次從目前設定解析 harness。 +使用一般工作階段指令來切換 agent 和模型。`/new` 會建立新的 +OpenClaw 工作階段，而 Codex harness 會視需要建立或接續其 sidecar app-server +thread。`/reset` 會清除該 thread 的 OpenClaw 工作階段綁定， +並讓下一個回合再次從目前設定解析 harness。 -## 模型 discovery +## 模型探索 -預設情況下，Codex Plugin 會向 app-server 詢問可用模型。如果 discovery 失敗或逾時，它會使用隨附的 fallback catalog： +預設情況下，Codex Plugin 會向 app-server 詢問可用模型。如果 +探索失敗或逾時，它會使用隨附的後援目錄： - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -你可以在 `plugins.entries.codex.config.discovery` 下調整 discovery： +你可以在 `plugins.entries.codex.config.discovery` 下調整探索： ```json5 { @@ -345,7 +427,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -當你希望啟動時避免 probing Codex 並固定使用 fallback catalog，請停用 discovery： +當你希望啟動時避免探測 Codex 並固定使用後援目錄時，請停用探索： ```json5 { @@ -364,19 +446,26 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -## App-server 連線與 policy +## App-server 連線與政策 -預設情況下，Plugin 會以以下方式在本機啟動 OpenClaw 管理的 Codex binary： +預設情況下，Plugin 會使用以下方式在本機啟動 OpenClaw 管理的 Codex +二進位檔： ```bash codex app-server --listen stdio:// ``` -受管理的 binary 會隨 `codex` Plugin package 一起發布。這會讓 app-server 版本綁定到隨附的 Plugin，而不是本機剛好安裝的其他 Codex CLI。只有在你有意執行不同 executable 時，才設定 `appServer.command`。 +受管理的二進位檔會隨 `codex` Plugin 套件一起提供。這會讓 +app-server 版本綁定到隨附 Plugin，而不是本機剛好安裝的其他 +Codex CLI。只有在你刻意要執行不同可執行檔時，才設定 `appServer.command`。 -預設情況下，OpenClaw 會以 YOLO mode 啟動本機 Codex harness sessions：`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 `sandbox: "danger-full-access"`。這是 autonomous heartbeats 使用的受信任本機 operator posture：Codex 可以使用 shell 和 network tools，而不會停在沒有人能回答的原生 approval prompts。 +預設情況下，OpenClaw 會以 YOLO 模式啟動本機 Codex harness 工作階段： +`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 +`sandbox: "danger-full-access"`。這是用於自主 Heartbeat 的受信任本機 +操作者姿態：Codex 可以使用 shell 和網路工具，而不會停在沒有人能回應的 +原生核准提示上。 -若要 opt in 到 Codex guardian-reviewed approvals，請設定 `appServer.mode: +若要選擇使用 Codex guardian-reviewed 核准，請設定 `appServer.mode: "guardian"`： ```json5 @@ -397,11 +486,19 @@ codex app-server --listen stdio:// } ``` -Guardian mode 會使用 Codex 的原生 auto-review approval path。當 Codex 要求離開 sandbox、寫入 workspace 之外，或新增 network access 等權限時，Codex 會將該 approval request 路由給原生 reviewer，而不是 human prompt。reviewer 會套用 Codex 的 risk framework，並核准或拒絕該特定請求。當你想要比 YOLO mode 更多 guardrails，但仍需要 unattended agents 持續推進時，請使用 Guardian。 +Guardian 模式會使用 Codex 的原生自動審查核准路徑。當 Codex 要求 +離開 sandbox、寫入工作區外部，或新增網路存取等權限時，Codex 會將該 +核准請求路由到原生 reviewer，而不是人類提示。Reviewer 會套用 Codex +的風險框架，並核准或拒絕該特定請求。當你需要比 YOLO 模式更多防護， +但仍需要無人值守的 agent 持續推進時，請使用 Guardian。 -`guardian` preset 會展開為 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`，以及 `sandbox: "workspace-write"`。個別 policy fields 仍會覆寫 `mode`，因此進階部署可以將 preset 與明確選項混用。較舊的 `guardian_subagent` reviewer value 仍會作為 compatibility alias 接受，但新設定應使用 `auto_review`。 +`guardian` 預設集會展開為 `approvalPolicy: "on-request"`、 +`approvalsReviewer: "auto_review"`，以及 `sandbox: "workspace-write"`。 +個別政策欄位仍會覆寫 `mode`，因此進階部署可以將預設集與明確選項混用。 +較舊的 `guardian_subagent` reviewer 值仍會作為相容性別名接受， +但新設定應使用 `auto_review`。 -對於已在執行的 app-server，請使用 WebSocket transport： +對於已在執行中的 app-server，請使用 WebSocket transport： ```json5 { @@ -423,26 +520,46 @@ Guardian mode 會使用 Codex 的原生 auto-review approval path。當 Codex } ``` -Stdio app-server 啟動預設會繼承 OpenClaw 的 process environment，但 OpenClaw 擁有 Codex app-server account bridge，並將 `CODEX_HOME` 和 `HOME` 都設為該 agent 的 OpenClaw state 下的個別 agent 目錄。Codex 自己的 skill loader 會讀取 `$CODEX_HOME/skills` 和 `$HOME/.agents/skills`，因此兩個值都會針對本機 app-server 啟動隔離。這會讓 Codex 原生 skills、plugins、config、accounts 和 thread state 限定在 OpenClaw agent 範圍內，而不是從 operator 的個人 Codex CLI home 外洩進來。 +Stdio app-server 啟動預設會繼承 OpenClaw 的程序環境， +但 OpenClaw 擁有 Codex app-server 帳號橋接，並將 `CODEX_HOME` 和 +`HOME` 都設定為該 agent 的 OpenClaw 狀態下的個別 agent 目錄。 +Codex 自身的 skill loader 會讀取 `$CODEX_HOME/skills` 和 +`$HOME/.agents/skills`，因此本機 app-server 啟動的兩個值都會被隔離。 +這會讓 Codex 原生 skills、plugins、設定、帳號和 thread 狀態限定在 +OpenClaw agent 範圍內，而不會從操作者的個人 Codex CLI home 洩漏進來。 -OpenClaw plugins 和 OpenClaw skill snapshots 仍會透過 OpenClaw 自己的 plugin registry 和 skill loader 流動。個人 Codex CLI assets 不會。如果你有實用的 Codex CLI skills 或 plugins 應該成為 OpenClaw agent 的一部分，請明確 inventory 它們： +OpenClaw plugins 和 OpenClaw skill snapshots 仍會透過 OpenClaw 自己的 +Plugin registry 和 skill loader 流動。個人 Codex CLI 資產不會。如果你有 +有用的 Codex CLI skills 或 plugins 應成為 OpenClaw agent 的一部分， +請明確盤點它們： ```bash openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -Codex migration provider 會將 skills 複製到目前 OpenClaw agent workspace。Codex 原生 plugins、hooks 和 config files 會被回報或封存以供手動 review，而不是自動啟用，因為它們可能執行 commands、暴露 MCP servers，或攜帶 credentials。 +Codex migration provider 會將 skills 複製到目前的 OpenClaw agent +工作區。Codex 原生 plugins、hooks 和設定檔會回報或封存以供手動審查， +而不是自動啟用，因為它們可以執行指令、公開 MCP servers，或攜帶憑證。 -Auth 會依以下順序選取： +驗證會依以下順序選取： -1. 該 agent 的明確 OpenClaw Codex auth profile。 -2. 該 agent 的 Codex home 中 app-server 的現有帳戶。 -3. 僅限本機 stdio app-server 啟動，當沒有 app-server 帳戶且仍需要 OpenAI auth 時，使用 `CODEX_API_KEY`，再使用 `OPENAI_API_KEY`。 +1. 該 agent 的明確 OpenClaw Codex 驗證設定檔。 +2. 該 agent 的 Codex home 中 app-server 既有帳號。 +3. 僅限本機 stdio app-server 啟動，當沒有 app-server 帳號且仍需要 + OpenAI 驗證時，使用 `CODEX_API_KEY`，接著使用 + `OPENAI_API_KEY`。 -當 OpenClaw 偵測到 ChatGPT subscription-style Codex auth profile 時，會從產生的 Codex 子程序移除 `CODEX_API_KEY` 和 `OPENAI_API_KEY`。這會讓 Gateway 層級 API keys 仍可用於 embeddings 或 direct OpenAI models，而不會意外讓原生 Codex app-server turns 透過 API 計費。明確的 Codex API-key profiles 和本機 stdio env-key fallback 會使用 app-server login，而不是繼承的 child-process env。WebSocket app-server connections 不會收到 Gateway env API-key fallback；請使用明確的 auth profile 或遠端 app-server 自己的帳戶。 +當 OpenClaw 看到 ChatGPT 訂閱樣式的 Codex 驗證設定檔時，會從產生的 +Codex 子程序移除 `CODEX_API_KEY` 和 `OPENAI_API_KEY`。這會讓 Gateway +層級 API 金鑰仍可用於 embeddings 或直接 OpenAI 模型，而不會意外讓原生 +Codex app-server 回合透過 API 計費。明確的 Codex API-key 設定檔和 +本機 stdio env-key 後援會使用 app-server 登入，而不是繼承的子程序 env。 +WebSocket app-server 連線不會接收 Gateway env API-key 後援；請使用明確 +驗證設定檔或遠端 app-server 自己的帳號。 -如果部署需要額外的環境隔離，請將那些變數加入 `appServer.clearEnv`： +如果部署需要額外的環境隔離，請將那些變數新增至 +`appServer.clearEnv`： ```json5 { @@ -461,50 +578,52 @@ Auth 會依以下順序選取： } ``` -`appServer.clearEnv` 只會影響衍生出的 Codex app-server 子程序。 +`appServer.clearEnv` 只會影響產生的 Codex app-server 子程序。 -Codex 動態工具預設使用 `native-first` 設定檔。在該模式中， -OpenClaw 不會公開與 Codex 原生工作區作業重複的動態工具： +Codex 動態工具預設使用 `native-first` 設定檔。在該模式下， +OpenClaw 不會公開與 Codex 原生工作區操作重複的動態工具： `read`、`write`、`edit`、`apply_patch`、`exec`、`process` 和 -`update_plan`。OpenClaw 整合工具，例如訊息傳遞、工作階段、媒體、 -Cron、瀏覽器、節點、Gateway、`heartbeat_respond` 和 `web_search` 仍會 +`update_plan`。OpenClaw 整合工具，例如訊息、工作階段、媒體、 +cron、瀏覽器、節點、gateway、`heartbeat_respond` 和 `web_search` 仍然 可用。 支援的頂層 Codex Plugin 欄位： -| 欄位 | 預設值 | 含義 | -| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | 使用 `"openclaw-compat"` 可向 Codex app-server 公開完整的 OpenClaw 動態工具集。 | -| `codexDynamicToolsExclude` | `[]` | 要從 Codex app-server 回合中省略的其他 OpenClaw 動態工具名稱。 | +| 欄位 | 預設值 | 意義 | +| -------------------------- | ---------------- | -------------------------------------------------------------------------------------------- | +| `codexDynamicToolsProfile` | `"native-first"` | 使用 `"openclaw-compat"` 將完整的 OpenClaw 動態工具集公開給 Codex app-server。 | +| `codexDynamicToolsExclude` | `[]` | 要在 Codex app-server 回合中省略的其他 OpenClaw 動態工具名稱。 | 支援的 `appServer` 欄位： -| 欄位 | 預設值 | 含義 | -| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` 會衍生 Codex；`"websocket"` 會連線到 `url`。 | -| `command` | 受管理的 Codex 二進位檔 | stdio 傳輸使用的可執行檔。保留未設定會使用受管理的二進位檔；只有在明確覆寫時才設定。 | -| `args` | `["app-server", "--listen", "stdio://"]` | stdio 傳輸使用的引數。 | -| `url` | 未設定 | WebSocket app-server URL。 | -| `authToken` | 未設定 | WebSocket 傳輸使用的 Bearer 權杖。 | -| `headers` | `{}` | 額外的 WebSocket 標頭。 | -| `clearEnv` | `[]` | 在 OpenClaw 建立繼承環境之後，從衍生出的 stdio app-server 程序移除的額外環境變數名稱。`CODEX_HOME` 和 `HOME` 保留給 OpenClaw 在本機啟動時為每個代理程式提供的 Codex 隔離。 | -| `requestTimeoutMs` | `60000` | app-server 控制平面呼叫的逾時。 | -| `mode` | `"yolo"` | YOLO 或由守護者審查執行的預設組態。 | -| `approvalPolicy` | `"never"` | 傳送到執行緒開始/恢復/回合的原生 Codex 核准政策。 | -| `sandbox` | `"danger-full-access"` | 傳送到執行緒開始/恢復的原生 Codex 沙盒模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 讓 Codex 審查原生核准提示。`guardian_subagent` 仍是舊版別名。 | -| `serviceTier` | 未設定 | 可選的 Codex app-server 服務層級：`"fast"`、`"flex"` 或 `null`。無效的舊版值會被忽略。 | +| 欄位 | 預設值 | 意義 | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` 會產生 Codex；`"websocket"` 會連線到 `url`。 | +| `command` | 受管理的 Codex 二進位檔 | stdio 傳輸使用的可執行檔。保留未設定會使用受管理的二進位檔；只有在明確覆寫時才設定。 | +| `args` | `["app-server", "--listen", "stdio://"]` | stdio 傳輸使用的引數。 | +| `url` | 未設定 | WebSocket app-server URL。 | +| `authToken` | 未設定 | WebSocket 傳輸使用的 Bearer 權杖。 | +| `headers` | `{}` | 額外的 WebSocket 標頭。 | +| `clearEnv` | `[]` | 在 OpenClaw 建立其繼承環境後，從產生的 stdio app-server 程序移除的額外環境變數名稱。`CODEX_HOME` 和 `HOME` 保留給 OpenClaw 在本機啟動時進行每個代理的 Codex 隔離。 | +| `requestTimeoutMs` | `60000` | app-server 控制平面呼叫的逾時時間。 | +| `mode` | `"yolo"` | YOLO 或 guardian 審查執行的預設值。 | +| `approvalPolicy` | `"never"` | 傳送至執行緒啟動／恢復／回合的原生 Codex 核准政策。 | +| `sandbox` | `"danger-full-access"` | 傳送至執行緒啟動／恢復的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 讓 Codex 審查原生核准提示。`guardian_subagent` 仍是舊版別名。 | +| `serviceTier` | 未設定 | 選用的 Codex app-server 服務層級：`"fast"`、`"flex"` 或 `null`。無效的舊版值會被忽略。 | -OpenClaw 所擁有的動態工具呼叫會獨立於 -`appServer.requestTimeoutMs` 設定界限：每個 Codex `item/tool/call` 請求都必須在 -30 秒內收到 OpenClaw 回應。逾時時，OpenClaw 會在支援的情況下中止工具 -訊號，並向 Codex 傳回失敗的動態工具回應，讓該回合可以繼續，而不是讓工作階段停留在 -`processing`。 +OpenClaw 擁有的動態工具呼叫會獨立於 +`appServer.requestTimeoutMs` 受到限制：每個 Codex `item/tool/call` 請求都必須在 +30 秒內收到 OpenClaw 回應。逾時時，OpenClaw 會在支援處中止工具 +訊號，並向 Codex 傳回失敗的動態工具回應，讓該回合可以繼續， +而不是讓工作階段停留在 `processing`。 -OpenClaw 回應 Codex 回合範圍的 app-server 請求之後，測試工具也會期待 -Codex 以 `turn/completed` 完成原生回合。如果 app-server 在該回應後 -60 秒內沒有動靜，OpenClaw 會盡力中斷 Codex 回合、記錄診斷逾時，並釋放 -OpenClaw 工作階段通道，避免後續聊天訊息排在過期的原生回合之後。 +OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架 +也預期 Codex 以 `turn/completed` 完成原生回合。如果 +app-server 在該回應後安靜 60 秒，OpenClaw 會盡力 +中斷 Codex 回合、記錄診斷逾時，並釋放 +OpenClaw 工作階段通道，讓後續聊天訊息不會排在過期的 +原生回合後面。 本機測試仍可使用環境覆寫： @@ -517,22 +636,25 @@ OpenClaw 工作階段通道，避免後續聊天訊息排在過期的原生回 當 `appServer.command` 未設定時，`OPENCLAW_CODEX_APP_SERVER_BIN` 會略過受管理的二進位檔。 `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。請改用 -`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本機測試中使用 -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。對於可重複部署，建議使用設定檔，因為這會讓 Plugin 行為與其餘 Codex 測試工具設定保存在同一個已審查檔案中。 +`plugins.entries.codex.config.appServer.mode: "guardian"`，或使用 +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` 進行一次性本機測試。對於 +可重複部署，建議使用設定，因為它會將 Plugin 行為保留在與其餘 +Codex 測試框架設定相同的已審查檔案中。 ## 電腦使用 -電腦使用有自己的設定指南： +電腦使用已在其專屬設定指南中說明： [Codex 電腦使用](/zh-TW/plugins/codex-computer-use)。 -簡短版本：OpenClaw 不會內建桌面控制應用程式，也不會自行執行桌面動作。它會準備 Codex app-server、驗證 -`computer-use` MCP 伺服器可用，然後讓 Codex 在 Codex 模式回合期間處理原生 +簡短版本：OpenClaw 不會將桌面控制應用程式納入供應，也不會自行執行 +桌面動作。它會準備 Codex app-server、驗證 +`computer-use` MCP 伺服器可用，然後讓 Codex 在 Codex 模式回合中處理原生 MCP 工具呼叫。 若要在 Codex marketplace 流程之外直接存取 TryCua 驅動程式，請使用 `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` 註冊 -`cua-driver mcp`。 -請參閱 [Codex 電腦使用](/zh-TW/plugins/codex-computer-use)，了解 Codex 所擁有的電腦使用與直接 MCP 註冊之間的差異。 +`cua-driver mcp`。請參閱 [Codex 電腦使用](/zh-TW/plugins/codex-computer-use) 了解 +Codex 擁有的電腦使用與直接 MCP 註冊之間的差異。 最小設定： @@ -561,25 +683,18 @@ MCP 工具呼叫。 } ``` -可以從命令介面檢查或安裝設定： +可以從命令介面檢查或安裝此設定： - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -電腦使用是 macOS 專用功能，可能需要本機作業系統權限，Codex MCP 伺服器才能控制應用程式。如果 `computerUse.enabled` 為 true 且 MCP -伺服器不可用，Codex 模式回合會在線程開始前失敗，而不是在沒有原生電腦使用工具的情況下靜默執行。請參閱 -[Codex 電腦使用](/zh-TW/plugins/codex-computer-use)，了解 marketplace 選項、 -遠端目錄限制、狀態原因和疑難排解。 +Computer Use 僅適用於 macOS，且在 Codex MCP 伺服器能控制應用程式之前，可能需要本機作業系統權限。如果 `computerUse.enabled` 為 true 且 MCP 伺服器無法使用，Codex 模式的回合會在線程開始前失敗，而不是在沒有原生 Computer Use 工具的情況下靜默執行。請參閱 [Codex Computer Use](/zh-TW/plugins/codex-computer-use)，了解 marketplace 選項、遠端目錄限制、狀態原因與疑難排解。 -當 `computerUse.autoInstall` 為 true 時，如果 Codex 尚未發現本機 marketplace， -OpenClaw 可以從 -`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` -註冊標準內建 Codex Desktop marketplace。變更執行階段或電腦使用設定後，請使用 -`/new` 或 `/reset`，避免既有工作階段保留舊的 PI 或 Codex 執行緒繫結。 +當 `computerUse.autoInstall` 為 true 時，如果 Codex 尚未發現本機 marketplace，OpenClaw 可以從 `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 註冊標準的隨附 Codex Desktop marketplace。變更 runtime 或 Computer Use 設定後，請使用 `/new` 或 `/reset`，讓現有工作階段不會保留舊的 Pi 或 Codex 線程綁定。 -## 常見範例 +## 常見設定範例 使用預設 stdio 傳輸的本機 Codex： @@ -595,7 +710,7 @@ OpenClaw 可以從 } ``` -僅 Codex 測試工具驗證： +僅 Codex 的測試架構驗證： ```json5 { @@ -617,7 +732,7 @@ OpenClaw 可以從 } ``` -由守護者審查的 Codex 核准： +由 guardian 審查的 Codex 核准： ```json5 { @@ -662,215 +777,217 @@ OpenClaw 可以從 } ``` -模型切換仍由 OpenClaw 控制。當 OpenClaw 工作階段附加到既有 Codex 執行緒時，下一個回合會再次將目前選取的 -OpenAI 模型、供應商、核准政策、沙盒和服務層級傳送到 -app-server。從 `openai/gpt-5.5` 切換到 `openai/gpt-5.2` 會保留執行緒繫結，但要求 Codex 繼續使用新選取的模型。 +模型切換仍由 OpenClaw 控制。當 OpenClaw 工作階段附加到現有的 Codex 線程時，下一個回合會再次將目前選取的 OpenAI 模型、供應商、核准原則、沙箱與服務層級傳送至 app-server。從 `openai/gpt-5.5` 切換到 `openai/gpt-5.2` 會保留線程綁定，但要求 Codex 使用新選取的模型繼續。 ## Codex 命令 -內建 Plugin 會將 `/codex` 註冊為已授權的斜線命令。它是通用的，適用於任何支援 OpenClaw 文字命令的頻道。 +隨附的 Plugin 會將 `/codex` 註冊為已授權的斜線命令。它是通用命令，可在任何支援 OpenClaw 文字命令的通道上運作。 常見形式： -- `/codex status` 顯示即時應用伺服器連線、模型、帳戶、速率限制、MCP 伺服器，以及 Skills。 -- `/codex models` 列出即時 Codex 應用伺服器模型。 -- `/codex threads [filter]` 列出最近的 Codex 執行緒。 -- `/codex resume ` 將目前的 OpenClaw 工作階段附加到既有 Codex 執行緒。 -- `/codex compact` 要求 Codex 應用伺服器壓縮已附加的執行緒。 -- `/codex review` 對已附加的執行緒啟動 Codex 原生審查。 -- `/codex diagnostics [note]` 在傳送已附加執行緒的 Codex 診斷回饋前先詢問。 -- `/codex computer-use status` 檢查已設定的 Computer Use Plugin 和 MCP 伺服器。 +- `/codex status` 顯示即時應用程式伺服器連線能力、模型、帳戶、速率限制、MCP 伺服器與 Skills。 +- `/codex models` 列出即時 Codex 應用程式伺服器模型。 +- `/codex threads [filter]` 列出最近的 Codex 對話串。 +- `/codex resume ` 將目前的 OpenClaw 工作階段附加到現有的 Codex 對話串。 +- `/codex compact` 要求 Codex 應用程式伺服器對已附加的對話串進行 compact。 +- `/codex review` 為已附加的對話串啟動 Codex 原生審查。 +- `/codex diagnostics [note]` 會在傳送已附加對話串的 Codex 診斷回饋前先詢問。 +- `/codex computer-use status` 檢查已設定的 Computer Use Plugin 與 MCP 伺服器。 - `/codex computer-use install` 安裝已設定的 Computer Use Plugin 並重新載入 MCP 伺服器。 - `/codex account` 顯示帳戶與速率限制狀態。 -- `/codex mcp` 列出 Codex 應用伺服器 MCP 伺服器狀態。 -- `/codex skills` 列出 Codex 應用伺服器 Skills。 +- `/codex mcp` 列出 Codex 應用程式伺服器 MCP 伺服器狀態。 +- `/codex skills` 列出 Codex 應用程式伺服器 Skills。 + +當 Codex 回報使用量限制失敗時，若 Codex 有提供下一次 +應用程式伺服器重設時間，OpenClaw 會一併包含該時間。在同一個 +對話中使用 `/codex account` 檢查目前的帳戶與速率限制時段。 ### 常見除錯工作流程 -當 Codex 支援的代理程式在 Telegram、Discord、Slack， -或其他通道中做出意外行為時，請從發生問題的對話開始： +當由 Codex 支援的代理程式在 Telegram、Discord、Slack +或其他通道中做出令人意外的行為時，請從發生問題的對話開始： -1. 執行 `/diagnostics bad tool choice after image upload` 或另一則描述你所見情況的簡短備註。 -2. 核准診斷要求一次。核准會建立本機 Gateway - 診斷 zip，且因為該工作階段正在使用 Codex harness，也會 - 將相關 Codex 回饋套件傳送到 OpenAI 伺服器。 +1. 執行 `/diagnostics bad tool choice after image upload` 或另一則簡短註記 + 來描述你看到的情況。 +2. 核准診斷要求一次。該核准會建立本機 Gateway + 診斷 zip，並且因為工作階段使用 Codex harness，也會 + 將相關的 Codex 回饋套件傳送到 OpenAI 伺服器。 3. 將完成的診斷回覆複製到錯誤報告或支援討論串中。 - 它包含本機套件路徑、隱私摘要、OpenClaw 工作階段 ID、 - Codex 執行緒 ID，以及每個 Codex 執行緒的一行 `Inspect locally`。 -4. 如果你想自行除錯該次執行，請在終端機中執行列印出的 `Inspect locally` + 其中包含本機套件路徑、隱私摘要、OpenClaw 工作階段 ID、 + Codex 對話串 ID，以及每個 Codex 對話串的 `Inspect locally` 行。 +4. 如果你想自行除錯這次執行，請在終端機中執行列印出的 `Inspect locally` 命令。它看起來像 `codex resume `，並會開啟 - 原生 Codex 執行緒，讓你檢查對話、在本機繼續， - 或詢問 Codex 為何選擇特定工具或計畫。 + 原生 Codex 對話串，讓你檢查對話、在本機繼續它， + 或詢問 Codex 為什麼選擇特定工具或計畫。 -只有在你特別想為目前已附加的執行緒上傳 Codex +只有在你特別想為目前附加的對話串上傳 Codex 回饋，而不需要完整 OpenClaw -Gateway 診斷套件時，才使用 `/codex diagnostics [note]`。對多數支援報告而言，`/diagnostics [note]` -是更好的起點，因為它會在單一回覆中把本機 Gateway 狀態和 Codex -執行緒 ID 串在一起。完整隱私模型與群組聊天行為請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。 +Gateway 診斷套件時，才使用 `/codex diagnostics [note]`。對大多數支援報告來說，`/diagnostics [note]` 是 +更好的起點，因為它會在同一則回覆中把本機 Gateway 狀態與 Codex +對話串 ID 串在一起。完整隱私模型與群組聊天行為請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。 核心 OpenClaw 也公開僅限擁有者使用的 `/diagnostics [note]`，作為一般 Gateway 診斷命令。它的核准提示會顯示敏感資料 前言、連結到 [診斷匯出](/zh-TW/gateway/diagnostics)，並且每次都透過明確的 exec 核准 -要求執行 `openclaw gateway diagnostics export --json`。不要使用允許所有項目的規則核准診斷。核准後， -OpenClaw 會傳送一份可貼上的報告，其中包含本機套件路徑與資訊清單 -摘要。當作用中的 OpenClaw 工作階段使用 Codex harness 時，該 -同一核准也會授權將相關 Codex 回饋套件傳送到 -OpenAI 伺服器。核准提示會說明將會傳送 Codex 回饋，但 -在核准前不會列出 Codex 工作階段或執行緒 ID。 +要求 `openclaw gateway diagnostics export --json`。請勿使用允許全部規則核准診斷。核准後， +OpenClaw 會傳送可貼上的報告，其中包含本機套件路徑與資訊清單 +摘要。當作用中的 OpenClaw 工作階段使用 Codex harness 時，同一個核准 +也會授權將相關的 Codex 回饋套件傳送到 +OpenAI 伺服器。核准提示會說明將傳送 Codex 回饋，但 +它不會在核准前列出 Codex 工作階段或對話串 ID。 -如果 `/diagnostics` 由擁有者在群組聊天中叫用，OpenClaw 會保持 -共用通道乾淨：群組只會收到一則簡短通知，而 -診斷前言、核准提示，以及 Codex 工作階段/執行緒 ID 會透過 +如果擁有者在群組聊天中呼叫 `/diagnostics`，OpenClaw 會保持 +共用通道整潔：群組只會收到簡短通知，而 +診斷前言、核准提示與 Codex 工作階段/對話串 ID 會透過 私人核准路由傳送給擁有者。如果沒有私人擁有者路由， -OpenClaw 會拒絕群組要求，並要求擁有者從 DM 執行。 +OpenClaw 會拒絕群組要求，並請擁有者從私訊執行。 -已核准的 Codex 上傳會呼叫 Codex 應用伺服器 `feedback/upload`，並要求 -應用伺服器在可用時包含每個列出執行緒和衍生 Codex 子執行緒的日誌。 -上傳會透過 Codex 的一般回饋路徑送到 OpenAI -伺服器；如果該應用伺服器停用了 Codex 回饋，命令會回傳 -應用伺服器錯誤。完成的診斷回覆會列出通道、 -OpenClaw 工作階段 ID、Codex 執行緒 ID，以及已傳送執行緒的本機 `codex resume ` +已核准的 Codex 上傳會呼叫 Codex 應用程式伺服器 `feedback/upload`，並要求 +應用程式伺服器在可用時包含每個列出的對話串與衍生 Codex 子對話串 +的記錄。上傳會透過 Codex 的一般回饋路徑前往 OpenAI +伺服器；如果該應用程式伺服器停用了 Codex 回饋，命令會傳回 +應用程式伺服器錯誤。完成的診斷回覆會列出通道、 +OpenClaw 工作階段 ID、Codex 對話串 ID，以及已傳送對話串的本機 `codex resume ` 命令。如果你拒絕或忽略核准， OpenClaw 不會列印那些 Codex ID。這次上傳不會取代本機 Gateway 診斷匯出。 -`/codex resume` 會寫入與 harness 正常輪次所使用相同的 sidecar 繫結檔案。 -在下一則訊息時，OpenClaw 會恢復該 Codex 執行緒，將 -目前選取的 OpenClaw 模型傳入應用伺服器，並保持延伸歷史記錄 +`/codex resume` 會寫入與 harness 正常回合使用相同的 sidecar 繫結檔案。 +在下一則訊息時，OpenClaw 會恢復該 Codex 對話串，將 +目前選取的 OpenClaw 模型傳入應用程式伺服器，並保持延伸歷史 啟用。 -### 從 CLI 檢查 Codex 執行緒 +### 從 CLI 檢查 Codex 對話串 -理解不佳 Codex 執行狀況最快的方式，通常是直接開啟原生 Codex -執行緒： +了解有問題的 Codex 執行，最快的方式通常是直接開啟原生 Codex +對話串： ```sh codex resume ``` 當你在通道對話中注意到錯誤，並想檢查 -有問題的 Codex 工作階段、在本機繼續它，或詢問 Codex 為何做出 +有問題的 Codex 工作階段、在本機繼續它，或詢問 Codex 為什麼做出 特定工具或推理選擇時，請使用此方式。最簡單的路徑通常是先執行 `/diagnostics [note]`：核准後，完成的報告會列出 -每個 Codex 執行緒並列印 `Inspect locally` 命令，例如 +每個 Codex 對話串，並列印 `Inspect locally` 命令，例如 `codex resume `。你可以直接將該命令複製到終端機。 -你也可以從目前聊天的 `/codex binding`，或最近 Codex 應用伺服器執行緒的 -`/codex threads [filter]` 取得執行緒 ID，然後在 shell 中執行相同的 +你也可以從目前聊天的 `/codex binding` 取得對話串 ID，或從 +最近 Codex 應用程式伺服器對話串的 `/codex threads [filter]` 取得，然後在 shell 中執行相同的 `codex resume` 命令。 -此命令介面需要 Codex 應用伺服器 `0.125.0` 或更新版本。如果未來或自訂 -應用伺服器未公開該 JSON-RPC 方法，個別 -控制方法會回報為 `unsupported by this Codex app-server`。 +此命令介面需要 Codex 應用程式伺服器 `0.125.0` 或更新版本。如果未來或自訂的應用程式伺服器未公開該 JSON-RPC 方法，個別控制方法會回報為 `unsupported by this Codex app-server`。 -## 掛鉤邊界 +## Hook 邊界 -Codex harness 有三個掛鉤層： +Codex harness 有三個 hook 層： -| 層 | 擁有者 | 目的 | +| 層 | 擁有者 | 用途 | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw Plugin 掛鉤 | OpenClaw | 跨 PI 與 Codex harness 的產品/Plugin 相容性。 | -| Codex 應用伺服器擴充中介軟體 | OpenClaw 內建 Plugin | 圍繞 OpenClaw 動態工具的每輪次配接器行為。 | -| Codex 原生掛鉤 | Codex | 來自 Codex 設定的低階 Codex 生命週期與原生工具政策。 | +| OpenClaw Plugin hooks | OpenClaw | 跨 PI 與 Codex harness 的產品/Plugin 相容性。 | +| Codex 應用程式伺服器 extension middleware | OpenClaw bundled plugins | 圍繞 OpenClaw 動態工具的逐回合 adapter 行為。 | +| Codex 原生 hooks | Codex | 來自 Codex 設定的低階 Codex 生命週期與原生工具政策。 | -OpenClaw 不使用專案或全域 Codex `hooks.json` 檔案來路由 -OpenClaw Plugin 行為。對於支援的原生工具與權限橋接， +OpenClaw 不會使用專案或全域 Codex `hooks.json` 檔案來路由 +OpenClaw Plugin 行為。對於受支援的原生工具與權限橋接， OpenClaw 會為 `PreToolUse`、`PostToolUse`、 -`PermissionRequest` 和 `Stop` 注入每個執行緒的 Codex 設定。其他 Codex 掛鉤，例如 `SessionStart` 和 -`UserPromptSubmit`，仍然是 Codex 層級的控制；它們不會在 v1 合約中公開為 -OpenClaw Plugin 掛鉤。 +`PermissionRequest` 與 `Stop` 注入逐對話串 Codex 設定。其他 Codex hooks，例如 `SessionStart` 與 +`UserPromptSubmit`，仍是 Codex 層級的控制；它們不會在 v1 合約中作為 +OpenClaw Plugin hooks 公開。 對於 OpenClaw 動態工具，OpenClaw 會在 Codex 要求 -呼叫後執行該工具，因此 OpenClaw 會在 -harness 配接器中觸發它擁有的 Plugin 與中介軟體行為。對於 Codex 原生工具，Codex 擁有標準工具記錄。 -OpenClaw 可以鏡射選定事件，但除非 Codex 透過應用伺服器或原生掛鉤 -回呼公開該操作，否則無法重寫原生 Codex -執行緒。 +呼叫後執行工具，因此 OpenClaw 會在 +harness adapter 中觸發它所擁有的 Plugin 與 middleware 行為。對於 Codex 原生工具，Codex 擁有標準工具記錄。 +OpenClaw 可以鏡像選定事件，但除非 Codex 透過應用程式伺服器或原生 hook +回呼公開該操作，否則它無法重寫原生 Codex +對話串。 -Compaction 與 LLM 生命週期投射來自 Codex 應用伺服器 -通知和 OpenClaw 配接器狀態，而不是原生 Codex 掛鉤命令。 -OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 -`llm_output` 事件是配接器層級的觀察，不是 Codex 內部要求或 Compaction payload 的逐位元組擷取。 +Compaction 與 LLM 生命週期投影來自 Codex 應用程式伺服器 +通知與 OpenClaw adapter 狀態，而不是原生 Codex hook 命令。 +OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 與 +`llm_output` 事件是 adapter 層級觀察，而不是逐位元組擷取 +Codex 內部請求或 compaction payload。 -Codex 原生 `hook/started` 和 `hook/completed` 應用伺服器通知會被 -投射為 `codex_app_server.hook` 代理程式事件，用於軌跡與除錯。 -它們不會叫用 OpenClaw Plugin 掛鉤。 +Codex 原生 `hook/started` 與 `hook/completed` 應用程式伺服器通知會 +投影為 `codex_app_server.hook` 代理程式事件，用於軌跡與除錯。 +它們不會呼叫 OpenClaw Plugin hooks。 ## V1 支援合約 -Codex 模式不是在底層使用不同模型呼叫的 PI。Codex 擁有更多 -原生模型迴圈，而 OpenClaw 會圍繞該邊界配接其 Plugin 與工作階段介面。 +Codex 模式不是在底層換成不同模型呼叫的 PI。Codex 擁有更多 +原生模型迴圈，而 OpenClaw 會圍繞該邊界調整其 Plugin 與工作階段介面。 Codex runtime v1 支援： | 介面 | 支援 | 原因 | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 透過 Codex 的 OpenAI 模型迴圈 | 支援 | Codex 應用伺服器擁有 OpenAI 輪次、原生執行緒恢復，以及原生工具延續。 | -| OpenClaw 通道路由與傳遞 | 支援 | Telegram、Discord、Slack、WhatsApp、iMessage，以及其他通道都留在模型 runtime 之外。 | -| OpenClaw 動態工具 | 支援 | Codex 要求 OpenClaw 執行這些工具，因此 OpenClaw 保留在執行路徑中。 | -| 提示詞與上下文 Plugin | 支援 | OpenClaw 會在啟動或恢復執行緒前建立提示詞覆蓋層，並將上下文投射到 Codex 輪次中。 | -| 上下文引擎生命週期 | 支援 | 組裝、擷取或輪次後維護，以及上下文引擎 Compaction 協調會為 Codex 輪次執行。 | -| 動態工具掛鉤 | 支援 | `before_tool_call`、`after_tool_call` 和工具結果中介軟體會圍繞 OpenClaw 擁有的動態工具執行。 | -| 生命週期掛鉤 | 作為配接器觀察支援 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 會以誠實的 Codex 模式 payload 觸發。 | -| 最終答案修訂閘門 | 透過原生掛鉤轉送支援 | Codex `Stop` 會被轉送到 `before_agent_finalize`；`revise` 會要求 Codex 在最終化前再進行一次模型傳遞。 | -| 原生 shell、patch 和 MCP 封鎖或觀察 | 透過原生掛鉤轉送支援 | Codex `PreToolUse` 和 `PostToolUse` 會針對已提交的原生工具介面轉送，包括 Codex 應用伺服器 `0.125.0` 或更新版本上的 MCP payload。支援封鎖；不支援引數重寫。 | -| 原生權限政策 | 透過原生掛鉤轉送支援 | 在 runtime 公開時，Codex `PermissionRequest` 可透過 OpenClaw 政策路由。如果 OpenClaw 未回傳決策，Codex 會透過其一般 guardian 或使用者核准路徑繼續。 | -| 應用伺服器軌跡擷取 | 支援 | OpenClaw 會記錄它傳送給應用伺服器的要求，以及它收到的應用伺服器通知。 | +| 透過 Codex 的 OpenAI 模型迴圈 | 支援 | Codex 應用程式伺服器擁有 OpenAI 回合、原生對話串恢復與原生工具續行。 | +| OpenClaw 通道路由與交付 | 支援 | Telegram、Discord、Slack、WhatsApp、iMessage 與其他通道會留在模型 runtime 之外。 | +| OpenClaw 動態工具 | 支援 | Codex 要求 OpenClaw 執行這些工具，因此 OpenClaw 仍在執行路徑中。 | +| Prompt 與內容 Plugin | 支援 | OpenClaw 會在開始或恢復對話串前建立 prompt 覆蓋層，並將內容投影到 Codex 回合中。 | +| 內容引擎生命週期 | 支援 | 組裝、擷取或回合後維護，以及內容引擎 compaction 協調，都會為 Codex 回合執行。 | +| 動態工具 hooks | 支援 | `before_tool_call`、`after_tool_call` 與工具結果 middleware 會圍繞 OpenClaw 擁有的動態工具執行。 | +| 生命週期 hooks | 作為 adapter 觀察支援 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 與 `after_compaction` 會以誠實的 Codex 模式 payload 觸發。 | +| 最終答案修訂 gate | 透過原生 hook relay 支援 | Codex `Stop` 會 relay 到 `before_agent_finalize`；`revise` 會要求 Codex 在最終定稿前再進行一次模型 pass。 | +| 原生 shell、patch 與 MCP 封鎖或觀察 | 透過原生 hook relay 支援 | Codex `PreToolUse` 與 `PostToolUse` 會針對已承諾的原生工具介面 relay，包括 Codex 應用程式伺服器 `0.125.0` 或更新版本上的 MCP payload。支援封鎖；不支援參數重寫。 | +| 原生權限政策 | 透過原生 hook relay 支援 | Codex `PermissionRequest` 可在 runtime 公開時透過 OpenClaw 政策路由。如果 OpenClaw 未回傳決策，Codex 會繼續走其一般 guardian 或使用者核准路徑。 | +| 應用程式伺服器軌跡擷取 | 支援 | OpenClaw 會記錄它傳送給應用程式伺服器的請求，以及它收到的應用程式伺服器通知。 | Codex runtime v1 不支援： -| 介面 | V1 邊界 | 未來路徑 | +| 表面 | V1 邊界 | 未來路徑 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| 原生工具參數變更 | Codex 原生前置工具 hooks 可以封鎖，但 OpenClaw 不會改寫 Codex 原生工具參數。 | 需要 Codex hook/schema 支援替換工具輸入。 | -| 可編輯的 Codex 原生對話紀錄歷史 | Codex 擁有標準原生執行緒歷史。OpenClaw 擁有鏡像並可投射未來脈絡，但不應變更未支援的內部結構。 | 如果需要原生執行緒手術，新增明確的 Codex app-server API。 | -| Codex 原生工具記錄的 `tool_result_persist` | 該 hook 轉換 OpenClaw 擁有的對話紀錄寫入，而不是 Codex 原生工具記錄。 | 可以鏡像轉換後的記錄，但標準改寫需要 Codex 支援。 | -| 豐富的原生 Compaction 中繼資料 | OpenClaw 觀察 Compaction 開始與完成，但不會收到穩定的保留/捨棄清單、token 差異或摘要 payload。 | 需要更豐富的 Codex Compaction 事件。 | -| Compaction 介入 | 目前在 Codex 模式中，OpenClaw Compaction hooks 屬於通知層級。 | 如果 plugins 需要否決或改寫原生 Compaction，新增 Codex 前置/後置 Compaction hooks。 | -| 逐位元組模型 API 請求擷取 | OpenClaw 可以擷取 app-server 請求與通知，但 Codex 核心會在內部建立最終的 OpenAI API 請求。 | 需要 Codex 模型請求追蹤事件或除錯 API。 | +| 原生工具引數變更 | Codex 原生工具前置 hook 可以封鎖，但 OpenClaw 不會重寫 Codex 原生工具引數。 | 需要 Codex hook/schema 支援替換工具輸入。 | +| 可編輯的 Codex 原生對話紀錄歷史 | Codex 擁有權威原生執行緒歷史。OpenClaw 擁有鏡像並可投射未來脈絡，但不應變更不受支援的內部實作。 | 如果需要原生執行緒手術，請新增明確的 Codex 應用程式伺服器 API。 | +| Codex 原生工具記錄的 `tool_result_persist` | 該 hook 會轉換 OpenClaw 擁有的對話紀錄寫入，而不是 Codex 原生工具記錄。 | 可以鏡像已轉換的記錄，但權威重寫需要 Codex 支援。 | +| 豐富的原生 Compaction 中繼資料 | OpenClaw 會觀察 Compaction 開始與完成，但不會收到穩定的保留/捨棄清單、token 差異或摘要酬載。 | 需要更豐富的 Codex Compaction 事件。 | +| Compaction 介入 | 目前 OpenClaw Compaction hook 在 Codex 模式中屬於通知層級。 | 如果 Plugin 需要否決或重寫原生 Compaction，請新增 Codex 前置/後置 Compaction hook。 | +| 逐位元組一致的模型 API 請求擷取 | OpenClaw 可以擷取應用程式伺服器請求與通知，但 Codex 核心會在內部建構最終 OpenAI API 請求。 | 需要 Codex 模型請求追蹤事件或除錯 API。 | ## 工具、媒體與 Compaction -Codex harness 只會變更低階嵌入式 agent 執行器。 +Codex harness 只會變更低階嵌入式代理執行器。 -OpenClaw 仍會建立工具清單，並從 harness 接收動態工具結果。文字、圖片、影片、音樂、TTS、核准，以及訊息工具輸出會繼續走一般 OpenClaw 傳遞路徑。 +OpenClaw 仍會建構工具清單，並從 harness 接收動態工具結果。文字、圖片、影片、音樂、TTS、核准與訊息工具輸出會繼續透過一般 OpenClaw 傳遞路徑處理。 -原生 hook relay 有意保持通用，但 v1 支援合約僅限於 OpenClaw 測試過的 Codex 原生工具與權限路徑。在 Codex runtime 中，這包含 shell、patch，以及 MCP `PreToolUse`、`PostToolUse` 和 `PermissionRequest` payloads。在 runtime 合約明確命名之前，不要假設每個未來 Codex hook 事件都是 OpenClaw plugin 介面。 +原生 hook relay 是刻意設計成通用的，但 v1 支援合約僅限於 OpenClaw 測試過的 Codex 原生工具與權限路徑。在 Codex 執行階段中，這包含 shell、patch 與 MCP `PreToolUse`、`PostToolUse` 和 `PermissionRequest` 酬載。在執行階段合約命名之前，請勿假設每個未來 Codex hook 事件都是 OpenClaw Plugin 表面。 -對於 `PermissionRequest`，OpenClaw 只有在 policy 做出決定時才會回傳明確允許或拒絕。沒有決定的結果並不是允許。Codex 會將其視為沒有 hook 決定，並落入自己的 guardian 或使用者核准路徑。 +對於 `PermissionRequest`，OpenClaw 只會在策略決定時回傳明確的允許或拒絕決策。無決策結果不是允許。Codex 會將其視為沒有 hook 決策，並交由自己的守護程式或使用者核准路徑處理。 -當 Codex 將 `_meta.codex_approval_kind` 標記為 `"mcp_tool_call"` 時，Codex MCP 工具核准請求會透過 OpenClaw 的 plugin 核准流程路由。Codex `request_user_input` 提示會被送回原始聊天，而下一個排入佇列的後續訊息會回答該原生伺服器請求，而不是被導向為額外脈絡。其他 MCP elicitation 請求仍會失敗關閉。 +當 Codex 將 `_meta.codex_approval_kind` 標記為 `"mcp_tool_call"` 時，Codex MCP 工具核准徵詢會透過 OpenClaw 的 Plugin 核准流程路由。Codex `request_user_input` 提示會送回原始聊天，下一個排入佇列的後續訊息會回答該原生伺服器請求，而不是被導向為額外脈絡。其他 MCP 徵詢請求仍會封閉失敗。 -作用中執行佇列導向會對應到 Codex app-server `turn/steer`。使用預設的 `messages.queue.mode: "steer"` 時，OpenClaw 會在設定的安靜視窗內批次處理排入佇列的聊天訊息，並依抵達順序將它們作為一個 `turn/steer` 請求送出。舊版 `queue` 模式會送出個別的 `turn/steer` 請求。Codex review 與手動 Compaction turn 可以拒絕同一 turn 的導向；在這種情況下，當選取的模式允許 fallback 時，OpenClaw 會使用後續佇列。請參閱[導向佇列](/zh-TW/concepts/queue-steering)。 +作用中執行佇列導向會對應到 Codex 應用程式伺服器 `turn/steer`。使用預設的 `messages.queue.mode: "steer"` 時，OpenClaw 會在設定的安靜視窗內批次處理排入佇列的聊天訊息，並依抵達順序將它們作為一個 `turn/steer` 請求送出。舊版 `queue` 模式會送出個別的 `turn/steer` 請求。Codex review 與手動 Compaction 回合可能拒絕同一回合導向，在此情況下，若選取的模式允許 fallback，OpenClaw 會使用後續佇列。請參閱[導向佇列](/zh-TW/concepts/queue-steering)。 -當選取的模型使用 Codex harness 時，原生執行緒 Compaction 會委派給 Codex app-server。OpenClaw 會保留對話紀錄鏡像，用於頻道歷史、搜尋、`/new`、`/reset`，以及未來模型或 harness 切換。當 app-server 發出時，鏡像會包含使用者提示、最終 assistant 文字，以及輕量的 Codex 推理或計畫記錄。目前，OpenClaw 只會記錄原生 Compaction 開始與完成訊號。它尚未公開人類可讀的 Compaction 摘要，或可稽核的清單來列出 Codex 在 Compaction 後保留了哪些項目。 +當選取的模型使用 Codex harness 時，原生執行緒 Compaction 會委派給 Codex 應用程式伺服器。OpenClaw 會保留對話紀錄鏡像，用於頻道歷史、搜尋、`/new`、`/reset`，以及未來的模型或 harness 切換。當應用程式伺服器發出時，該鏡像會包含使用者提示、最終助理文字，以及輕量的 Codex reasoning 或 plan 記錄。目前，OpenClaw 只記錄原生 Compaction 開始與完成訊號。它尚未公開人類可讀的 Compaction 摘要，或可稽核的 Codex 在 Compaction 後保留哪些項目的清單。 -由於 Codex 擁有標準原生執行緒，`tool_result_persist` 目前不會改寫 Codex 原生工具結果記錄。它只會在 OpenClaw 寫入 OpenClaw 擁有的 session 對話紀錄工具結果時套用。 +因為 Codex 擁有權威原生執行緒，`tool_result_persist` 目前不會重寫 Codex 原生工具結果記錄。它只會在 OpenClaw 寫入 OpenClaw 擁有的工作階段對話紀錄工具結果時套用。 -媒體產生不需要 PI。圖片、影片、音樂、PDF、TTS 與媒體理解會繼續使用相符的 provider/model 設定，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 +媒體生成不需要 PI。圖片、影片、音樂、PDF、TTS 與媒體理解會繼續使用相符的 provider/model 設定，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 疑難排解 -**Codex 不會以一般 `/model` provider 顯示：** 對新設定來說這是預期行為。選取帶有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或舊版 `codex/*` 參照）、啟用 `plugins.entries.codex.enabled`，並檢查 `plugins.allow` 是否排除了 `codex`。 +**Codex 不會顯示為一般 `/model` provider：** 這對新設定而言是預期行為。請選取具有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或舊版 `codex/*` ref）、啟用 `plugins.entries.codex.enabled`，並檢查 `plugins.allow` 是否排除 `codex`。 -**OpenClaw 使用 PI 而不是 Codex：** 當沒有 Codex harness 宣告該次執行時，`agentRuntime.id: "auto"` 仍可使用 PI 作為相容性後端。測試時請設定 `agentRuntime.id: "codex"` 以強制選取 Codex。強制 Codex runtime 會失敗，而不是 fallback 到 PI。一旦選取 Codex app-server，其失敗會直接浮現。 +**OpenClaw 使用 PI 而非 Codex：** 當沒有 Codex harness 宣告該次執行時，`agentRuntime.id: "auto"` 仍可使用 PI 作為相容性後端。測試時請設定 `agentRuntime.id: "codex"` 以強制選取 Codex。強制 Codex 執行階段會失敗，而不是 fallback 到 PI。一旦選取 Codex 應用程式伺服器，其失敗會直接浮現。 -**app-server 被拒絕：** 升級 Codex，讓 app-server handshake 回報版本 `0.125.0` 或更新版本。相同版本的 prerelease 或帶有 build suffix 的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，會被拒絕，因為 OpenClaw 測試的是穩定版 `0.125.0` protocol floor。 +**應用程式伺服器遭拒：** 請升級 Codex，讓應用程式伺服器交握回報版本 `0.125.0` 或更新版本。同版本的 prerelease 或帶有建置尾碼的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom` 會遭拒，因為 OpenClaw 測試的是穩定版 `0.125.0` 協定下限。 -**模型探索速度緩慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或停用探索。 +**模型探索很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或停用探索。 -**WebSocket 傳輸立即失敗：** 檢查 `appServer.url`、`authToken`，以及遠端 app-server 是否使用相同的 Codex app-server protocol 版本。 +**WebSocket 傳輸立即失敗：** 請檢查 `appServer.url`、`authToken`，以及遠端應用程式伺服器是否使用相同的 Codex 應用程式伺服器協定版本。 -**非 Codex 模型使用 PI：** 這是預期行為，除非你為該 agent 強制設定了 `agentRuntime.id: "codex"`，或選取了舊版 `codex/*` 參照。在 `auto` 模式中，純 `openai/gpt-*` 和其他 provider 參照會留在其一般 provider 路徑。如果強制設定 `agentRuntime.id: "codex"`，該 agent 的每個嵌入式 turn 都必須是 Codex 支援的 OpenAI 模型。 +**非 Codex 模型使用 PI：** 除非你為該代理強制設定 `agentRuntime.id: "codex"`，或選取舊版 `codex/*` ref，否則這是預期行為。一般 `openai/gpt-*` 與其他 provider ref 在 `auto` 模式中會維持其正常 provider 路徑。如果你強制設定 `agentRuntime.id: "codex"`，該代理的每個嵌入式回合都必須是 Codex 支援的 OpenAI 模型。 -**Computer Use 已安裝但工具未執行：** 從新的 session 檢查 `/codex computer-use status`。如果工具回報 `Native hook relay unavailable`，請使用 `/new` 或 `/reset`；如果仍持續發生，請重新啟動 gateway 以清除過時的原生 hook 註冊。如果 `computer-use.list_apps` 逾時，請重新啟動 Codex Computer Use 或 Codex Desktop 後重試。 +**Computer Use 已安裝但工具未執行：** 從全新工作階段檢查 `/codex computer-use status`。如果工具回報 `Native hook relay unavailable`，請使用 `/new` 或 `/reset`；如果仍持續發生，請重新啟動 Gateway 以清除過時的原生 hook 註冊。如果 `computer-use.list_apps` 逾時，請重新啟動 Codex Computer Use 或 Codex Desktop，然後重試。 -## 相關內容 +## 相關 -- [Agent harness plugins](/zh-TW/plugins/sdk-agent-harness) -- [Agent runtimes](/zh-TW/concepts/agent-runtimes) -- [Model providers](/zh-TW/concepts/model-providers) +- [代理 harness Plugin](/zh-TW/plugins/sdk-agent-harness) +- [代理執行階段](/zh-TW/concepts/agent-runtimes) +- [模型 provider](/zh-TW/concepts/model-providers) - [OpenAI provider](/zh-TW/providers/openai) - [狀態](/zh-TW/cli/status) -- [Plugin hooks](/zh-TW/plugins/hooks) +- [Plugin hook](/zh-TW/plugins/hooks) - [設定參考](/zh-TW/gateway/configuration-reference) - [測試](/zh-TW/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/zh-TW/plugins/dependency-resolution.md b/docs/zh-TW/plugins/dependency-resolution.md index 5c888d208..39272bb7b 100644 --- a/docs/zh-TW/plugins/dependency-resolution.md +++ b/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 --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 @@ -78,26 +78,26 @@ openclaw plugins install 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/` 載入，因此套件本機的 workspace 相依性可用，且編輯會直接被採用。原始碼 checkout 開發僅支援 pnpm；在儲存庫根目錄執行純 `npm install` 不是準備內建 Plugin 相依性的支援方式。 +在原始碼 checkout 中，OpenClaw 會將儲存庫視為 pnpm monorepo。執行 `pnpm install` 後，內建 Plugin 會從 `extensions/` 載入，因此套件本機 workspace 依賴項可用，且編輯會直接生效。原始碼 checkout 開發僅支援 pnpm；在儲存庫根目錄執行一般 `npm install` 不是準備內建 Plugin 依賴項的支援方式。 -| 安裝形式 | 內建 Plugin 位置 | 相依性擁有者 | +| 安裝形態 | 內建 Plugin 位置 | 依賴項擁有者 | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | -| `npm install -g openclaw` | 套件內的建置執行階段樹 | OpenClaw 套件，以及明確的 Plugin 安裝/更新/doctor 流程 | -| Git checkout 加上 `pnpm install` | `extensions/` workspace 套件 | pnpm workspace，包含每個 Plugin 套件自己的相依性 | +| `npm install -g openclaw` | 套件內建置的執行階段樹 | OpenClaw 套件，以及明確的 Plugin 安裝/更新/doctor 流程 | +| Git checkout 加上 `pnpm install` | `extensions/` 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 套件匯入。 -這些路徑只是舊版殘留物。新的安裝不應建立它們。 +這些路徑只是舊版殘留。新安裝不應建立它們。 diff --git a/docs/zh-TW/plugins/manage-plugins.md b/docs/zh-TW/plugins/manage-plugins.md index 724fd349d..80c409ae7 100644 --- a/docs/zh-TW/plugins/manage-plugins.md +++ b/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 --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 openclaw plugins update --all ``` -如果 Plugin 是從 npm dist-tag（例如 `@beta`）安裝，後續的 -`update ` 呼叫會重用該已記錄的 tag。傳入明確的 npm spec -會把追蹤的安裝切換到該 spec，以供未來更新使用。 +如果某個 Plugin 是從 npm dist-tag（例如 `@beta`）安裝，後續的 +`update ` 呼叫會重用該已記錄的標籤。傳入明確的 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 --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: openclaw plugins install ``` -裸格式仍會先檢查 ClawHub。 +裸形式仍會先檢查 ClawHub。 ### 發布到 npmjs.com @@ -160,7 +160,7 @@ openclaw plugins install 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 與套件中繼資料 diff --git a/docs/zh-TW/providers/openrouter.md b/docs/zh-TW/providers/openrouter.md index 4daa33b24..c96ea944c 100644 --- a/docs/zh-TW/providers/openrouter.md +++ b/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 金鑰將請求 ``` - Onboarding 預設使用 `openrouter/auto`。之後可選擇具體模型： + Onboarding 預設為 `openrouter/auto`。稍後可選擇具體模型： ```bash openclaw models set openrouter// @@ -54,19 +54,19 @@ OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求 ## 模型參照 -模型參照遵循 `openrouter//` 模式。如需可用提供者和模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。 +模型參照遵循 `openrouter//` 模式。如需可用 provider 和模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。 -內建備援範例： +內建後援範例： | 模型參照 | 備註 | | --------------------------------- | ---------------------------- | | `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` | -如果你將 OpenRouter 提供者重新指向其他 proxy 或基底 URL，OpenClaw **不會**注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。 +如果你將 OpenRouter provider 重新指向其他 proxy 或基礎 URL，OpenClaw **不會**注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。 ## 進階設定 - 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。 - 在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會使用這些標記在系統/開發者提示區塊上提升提示快取重用率。 + 在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會用這些標記在 system/developer prompt 區塊上提升 prompt-cache 重用率。 - - 在已驗證的 OpenRouter 路由上，啟用推理的 Anthropic 模型參照會在請求到達 OpenRouter 前移除結尾的助理預填輪次，以符合 Anthropic 對推理對話必須以使用者輪次結尾的要求。 + + 在已驗證的 OpenRouter 路由上，啟用 reasoning 的 Anthropic 模型參照會在請求到達 OpenRouter 前移除結尾的 assistant 預填回合，以符合 Anthropic 對 reasoning 對話必須以 user 回合結尾的要求。 - - 在支援的非 `auto` 路由上，OpenClaw 會將選定的思考層級對應到 OpenRouter proxy 推理 payload。不支援的模型提示和 `openrouter/auto` 會略過該推理注入。Hunter Alpha 也會對過期設定的模型參照略過 proxy 推理，因為 OpenRouter 可能會針對該已淘汰路由在推理欄位中傳回最終答案文字。 + + 在支援的非 `auto` 路由上，OpenClaw 會將選取的 thinking 層級對應到 OpenRouter proxy reasoning payload。不支援的模型提示和 `openrouter/auto` 會略過該 reasoning 注入。Hunter Alpha 也會因為 OpenRouter 可能在該已退役路由的 reasoning 欄位中傳回最終答案文字，而對過時設定的模型參照略過 proxy reasoning。 - - 在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的助理輪次中補上缺失的 `reasoning_content`，讓思考/工具對話保留 DeepSeek V4 所需的後續形狀。 + + 在已驗證的 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`。 - - OpenRouter 仍會透過 proxy 風格的 OpenAI 相容路徑執行，因此不會轉送原生僅 OpenAI 的請求形塑，例如 `serviceTier`、Responses `store`、OpenAI 推理相容 payload，以及提示快取提示。 + + OpenRouter 仍會經由 proxy 風格的 OpenAI 相容路徑執行，因此不會轉送原生僅 OpenAI 的請求塑形，例如 `serviceTier`、Responses `store`、OpenAI reasoning 相容 payload，以及 prompt-cache 提示。 - Gemini 支援的 OpenRouter 參照會留在 proxy-Gemini 路徑上：OpenClaw 會在該處保留 Gemini thought-signature 清理，但不會啟用原生 Gemini 重播驗證或 bootstrap 重寫。 + Gemini 支援的 OpenRouter 參照會維持在 proxy-Gemini 路徑上：OpenClaw 會在該處保留 Gemini thought-signature 清理，但不會啟用原生 Gemini 重播驗證或 bootstrap 重寫。 - - 如果你在模型參數下傳入 OpenRouter 提供者路由，OpenClaw 會在共用串流包裝器執行前，將其作為 OpenRouter 路由中繼資料轉送。 + + 如果你在模型參數下傳遞 OpenRouter provider 路由，OpenClaw 會在共用串流包裝器執行前，將其作為 OpenRouter 路由中繼資料轉送。 @@ -205,9 +205,9 @@ OpenRouter 底層會使用帶有你的 API 金鑰的 Bearer 權杖。 - 選擇提供者、模型參照和容錯移轉行為。 + 選擇 provider、模型參照與容錯移轉行為。 - agents、模型和提供者的完整設定參考。 + agents、模型和 provider 的完整設定參考。 diff --git a/docs/zh-TW/reference/RELEASING.md b/docs/zh-TW/reference/RELEASING.md index 1f1c8b68f..f6250c279 100644 --- a/docs/zh-TW/reference/RELEASING.md +++ b/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`；真正發布仍需要真正的發布標籤 -- 兩個工作流程都讓真正的發布與提升路徑維持在 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`；真實發布仍需要真正的發布標籤 +- 兩個 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 ``` -helper 會推送 `release-ci/-...`，從該分支分派 `Full Release Validation` 並設定 `ref=`，驗證每個子工作流程的 `headSha` 都符合目標，然後刪除暫時分支。這可避免意外證明較新的 `main` 子 run。 +該 helper 會推送 `release-ci/-...`，從該分支派發 `Full Release Validation` 並帶入 `ref=`，驗證每個 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=` 觸發手動 `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 不能作為工作流程觸發 ref，因此請使用 `pnpm ci:full-release --sha ` 建立固定的暫時分支。 +工作流程會解析目標 ref，以 `target_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=` 作為精確 commit 證明；原始 commit SHA 不能作為 workflow dispatch ref，因此請使用 `pnpm ci:full-release --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=`，而不是重新執行所有發行區塊。產生的重新執行命令會在可用時包含先前的 `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=`，而不是重新執行所有發布 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=` 派發 `Plugin NPM Release`。 -5. 使用相同範圍與 SHA 派發 `Plugin ClawHub Release`。 -6. 使用發布標籤、npm dist-tag，以及 - 已儲存的 `preflight_run_id` 派發 `OpenClaw NPM Release`。 + `ref=` 派送 `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) diff --git a/docs/zh-TW/reference/full-release-validation.md b/docs/zh-TW/reference/full-release-validation.md index e9ebb579e..1ab3b9c5c 100644 --- a/docs/zh-TW/reference/full-release-validation.md +++ b/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`
**子 workflow:** 無
**證明：** 解析發行分支、標籤或完整 commit SHA，並記錄選取的輸入。
**重跑：** 如果此步驟失敗，重跑總括流程。 | -| Vitest 與一般 CI | **Job:** `Run normal full CI`
**子 workflow:** `CI`
**證明：** 針對目標 ref 的手動完整 CI 圖，包括 Linux Node lanes、內建 Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python skills、Windows、macOS、Control UI i18n，以及透過總括流程執行的 Android。
**重跑：** `rerun_group=ci`。 | -| Plugin 預發行 | **Job:** `Run plugin prerelease validation`
**子 workflow:** `Plugin Prerelease`
**證明：** 僅限發行的 Plugin 靜態檢查、agentic Plugin 覆蓋率、完整擴充批次分片，以及 Plugin 預發行 Docker lanes。
**重跑：** `rerun_group=plugin-prerelease`。 | -| 發行檢查 | **Job:** `Run release/live/Docker/QA validation`
**子 workflow:** `OpenClaw Release Checks`
**證明：** 安裝煙霧測試、跨 OS 套件檢查、live/E2E 測試套件、Docker 發行路徑區塊、套件驗收、QA Lab parity、live Matrix，以及 live Telegram。
**重跑：** `rerun_group=release-checks` 或更窄的 release-checks handle。 | -| 套件成品 | **Job:** `Prepare release package artifact`
**子 workflow:** 無
**證明：** 夠早建立父層 `release-package-under-test` tarball，供不需要等待 `OpenClaw Release Checks` 的套件面向檢查使用。
**重跑：** 重跑總括流程，或為 `rerun_group=npm-telegram` 提供 `npm_telegram_package_spec`。 | -| 套件 Telegram | **Job:** `Run package Telegram E2E`
**子 workflow:** `NPM Telegram Beta E2E`
**證明：** 在 `rerun_group=all` 且 `release_profile=full` 時，提供由父層成品支援的 Telegram 套件驗證；或在設定 `npm_telegram_package_spec` 時，提供已發布套件的 Telegram 驗證。
**重跑：** `rerun_group=npm-telegram` 搭配 `npm_telegram_package_spec`。 | -| 總括驗證器 | **Job:** `Verify full validation`
**子 workflow:** 無
**證明：** 重新檢查已記錄的子執行結論，並附加子 workflow 的最慢 job 表格。
**重跑：** 在重跑失敗的子 workflow 並轉綠後，只重跑此 job。 | +| 階段 | 詳細資料 | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 目標解析 | **作業：** `Resolve target ref`
**子工作流程：** 無
**證明：** 解析發布分支、標籤或完整 commit SHA，並記錄選取的輸入。
**重新執行：** 如果此項失敗，重新執行總工作流程。 | +| Vitest 與一般 CI | **作業：** `Run normal full CI`
**子工作流程：** `CI`
**證明：** 針對目標 ref 執行手動完整 CI 圖，包括 Linux Node 執行線、內建 Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python Skills、Windows、macOS、Control UI i18n，以及透過總工作流程執行的 Android。
**重新執行：** `rerun_group=ci`。 | +| Plugin 預發布 | **作業：** `Run plugin prerelease validation`
**子工作流程：** `Plugin Prerelease`
**證明：** 僅發布使用的 Plugin 靜態檢查、代理式 Plugin 覆蓋、完整 Plugin 批次分片，以及 Plugin 預發布 Docker 執行線。
**重新執行：** `rerun_group=plugin-prerelease`。 | +| 發布檢查 | **作業：** `Run release/live/Docker/QA validation`
**子工作流程：** `OpenClaw Release Checks`
**證明：** 安裝煙霧測試、跨作業系統套件檢查、套件驗收、QA Lab 一致性、即時 Matrix，以及即時 Telegram。使用 `run_release_soak=true` 或 `release_profile=full` 時，也會執行完整的即時/E2E 套件和 Docker 發布路徑區塊。
**重新執行：** `rerun_group=release-checks` 或較窄的發布檢查控制代碼。 | +| 套件成品 | **作業：** `Prepare release package artifact`
**子工作流程：** 無
**證明：** 提早建立父層 `release-package-under-test` tarball，供不需要等待 `OpenClaw Release Checks` 的套件相關檢查使用。
**重新執行：** 重新執行總工作流程，或為 `rerun_group=npm-telegram` 提供 `npm_telegram_package_spec`。 | +| 套件 Telegram | **作業：** `Run package Telegram E2E`
**子工作流程：** `NPM Telegram Beta E2E`
**證明：** 在 `rerun_group=all` 且 `release_profile=full` 時，提供由父層成品支援的 Telegram 套件證明；或在設定 `npm_telegram_package_spec` 時，提供已發布套件的 Telegram 證明。
**重新執行：** 使用 `npm_telegram_package_spec` 的 `rerun_group=npm-telegram`。 | +| 總工作流程驗證器 | **作業：** `Verify full validation`
**子工作流程：** 無
**證明：** 重新檢查已記錄的子執行結論，並附加來自子工作流程的最慢作業表格。
**重新執行：** 在重新執行失敗的子工作流程並轉為綠燈後，只重新執行此作業。 | -對於 `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`
**後備 workflow:** 無
**測試：** 選取的 ref、選擇性的預期 SHA、profile、重跑群組，以及聚焦的 live 測試套件篩選器。
**重跑：** `rerun_group=release-checks`。 | -| 套件成品 | **Job:** `Prepare release package artifact`
**後備 workflow:** 無
**測試：** 打包或解析一個候選 tarball，並上傳 `release-package-under-test` 供下游套件面向檢查使用。
**重跑：** 受影響的套件、跨 OS 或 live/E2E 群組。 | -| 安裝煙霧測試 | **Job:** `Run install smoke`
**後備 workflow:** `Install Smoke`
**測試：** 完整安裝路徑，包含根層 Dockerfile 煙霧測試映像重用、QR 套件安裝、根層與 Gateway Docker 煙霧測試、安裝程式 Docker 測試、Bun 全域安裝映像提供者煙霧測試，以及快速內建 Plugin 安裝/解除安裝 E2E。
**重跑：** `rerun_group=install-smoke`。 | -| 跨 OS | **Job:** `cross_os_release_checks`
**後備 workflow:** `OpenClaw Cross-OS Release Checks (Reusable)`
**測試：** 在 Linux、Windows 和 macOS 上，使用候選 tarball 加上基準套件，針對選取的提供者與模式執行全新安裝和升級 lanes。
**重跑：** `rerun_group=cross-os`。 | -| Repo 與 live E2E | **Job:** `Run repo/live E2E validation`
**後備 workflow:** `OpenClaw Live And E2E Checks (Reusable)`
**測試：** repository E2E、live cache、OpenAI websocket streaming、原生 live 提供者與 Plugin 分片，以及由 `release_profile` 選取的 Docker 支援 live model/backend/gateway 測試框架。
**重跑：** `rerun_group=live-e2e`，可選擇搭配 `live_suite_filter`。 | -| Docker 發行路徑 | **Job:** `Run Docker release-path validation`
**後備 workflow:** `OpenClaw Live And E2E Checks (Reusable)`
**測試：** 針對共用套件成品執行發行路徑 Docker 區塊。
**重跑：** `rerun_group=live-e2e`。 | -| 套件驗收 | **Job:** `Run package acceptance`
**後備 workflow:** `Package Acceptance`
**測試：** 離線 Plugin 套件 fixture、Plugin 更新、mock-OpenAI Telegram 套件驗收，以及從每個 `2026.4.23` 或之後的穩定 npm 發行版，針對相同 tarball 執行的已發布升級 survivor 檢查。
**重跑：** `rerun_group=package`。 | -| QA parity | **Job:** `Run QA Lab parity lane` 與 `Run QA Lab parity report`
**後備 workflow:** 直接 job
**測試：** 候選與基準 agentic parity packs，然後執行 parity 報告。
**重跑：** `rerun_group=qa-parity` 或 `rerun_group=qa`。 | -| QA live Matrix | **Job:** `Run QA Lab live Matrix lane`
**後備 workflow:** 直接 job
**測試：** `qa-live-shared` 環境中的快速 live Matrix QA profile。
**重跑：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | -| QA live Telegram | **Job:** `Run QA Lab live Telegram lane`
**後備 workflow:** 直接 job
**測試：** 使用 Convex CI credential leases 的 live Telegram QA。
**重跑：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | -| 發行驗證器 | **Job:** `Verify release checks`
**後備 workflow:** 無
**測試：** 針對選取重跑群組所需的 release-check jobs。
**重跑：** 在聚焦的子 jobs 通過後重跑。 | +| 階段 | 詳細 | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 發行目標 | **作業：** `Resolve target ref`
**支援工作流程：** 無
**測試：** 選取的 ref、選用的預期 SHA、設定檔、重新執行群組，以及聚焦的即時套件篩選器。
**重新執行：** `rerun_group=release-checks`。 | +| 套件成品 | **作業：** `Prepare release package artifact`
**支援工作流程：** 無
**測試：** 封裝或解析一個候選 tarball，並上傳 `release-package-under-test` 供下游面向套件的檢查使用。
**重新執行：** 受影響的套件、跨作業系統或即時/E2E 群組。 | +| 安裝煙霧測試 | **作業：** `Run install smoke`
**支援工作流程：** `Install Smoke`
**測試：** 完整安裝路徑，包含重用根 Dockerfile 煙霧測試映像、QR 套件安裝、根與 Gateway Docker 煙霧測試、安裝程式 Docker 測試、Bun 全域安裝 image-provider 煙霧測試，以及快速 bundled-plugin 安裝/解除安裝 E2E。
**重新執行：** `rerun_group=install-smoke`。 | +| 跨作業系統 | **作業：** `cross_os_release_checks`
**支援工作流程：** `OpenClaw Cross-OS Release Checks (Reusable)`
**測試：** 針對選取的提供者與模式，在 Linux、Windows 和 macOS 上執行全新與升級路線，使用候選 tarball 加上基準套件。
**重新執行：** `rerun_group=cross-os`。 | +| 儲存庫與即時 E2E | **作業：** `Run repo/live E2E validation`
**支援工作流程：** `OpenClaw Live And E2E Checks (Reusable)`
**測試：** 儲存庫 E2E、即時快取、OpenAI websocket 串流、原生即時提供者與 Plugin 分片，以及由 `release_profile` 選取、Docker 支援的即時模型/後端/Gateway 測試框架。
**執行條件：** `run_release_soak=true`、`release_profile=full`，或聚焦的 `rerun_group=live-e2e`。
**重新執行：** `rerun_group=live-e2e`，可選擇搭配 `live_suite_filter`。 | +| Docker 發行路徑 | **作業：** `Run Docker release-path validation`
**支援工作流程：** `OpenClaw Live And E2E Checks (Reusable)`
**測試：** 針對共用套件成品的發行路徑 Docker 區塊。
**執行條件：** `run_release_soak=true`、`release_profile=full`，或聚焦的 `rerun_group=live-e2e`。
**重新執行：** `rerun_group=live-e2e`。 | +| Package Acceptance | **作業：** `Run package acceptance`
**支援工作流程：** `Package Acceptance`
**測試：** 離線 Plugin 套件夾具、Plugin 更新、mock-OpenAI Telegram 套件驗收，以及針對同一個 tarball 的已發布升級存活檢查。阻擋發行的檢查使用預設的最新已發布基準；浸泡測試會擴展到 `2026.4.23` 當天或之後的每個穩定 npm 發行版，加上已回報問題的夾具。
**重新執行：** `rerun_group=package`。 | +| QA 同等性 | **作業：** `Run QA Lab parity lane` 和 `Run QA Lab parity report`
**支援工作流程：** 直接作業
**測試：** 候選與基準代理同等性套件，接著產生同等性報告。
**重新執行：** `rerun_group=qa-parity` 或 `rerun_group=qa`。 | +| QA 即時 Matrix | **作業：** `Run QA Lab live Matrix lane`
**支援工作流程：** 直接作業
**測試：** `qa-live-shared` 環境中的快速即時 Matrix QA 設定檔。
**重新執行：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | +| QA 即時 Telegram | **作業：** `Run QA Lab live Telegram lane`
**支援工作流程：** 直接作業
**測試：** 使用 Convex CI 憑證租約的即時 Telegram QA。
**重新執行：** `rerun_group=qa-live` 或 `rerun_group=qa`。 | +| 發行驗證器 | **作業：** `Verify release checks`
**支援工作流程：** 無
**測試：** 選取重新執行群組所需的發行檢查作業。
**重新執行：** 在聚焦的子作業通過後重新執行。 | ## 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=`。發行成品會在可用時包含每個通道的重新執行命令，並帶有套件成品與映像重用輸入。 +當只有一條 Docker 路線失敗時，請在可重用的即時/E2E 工作流程上使用目標式 `docker_lanes=`。發行成品會包含每條路線的重新執行命令，並在可用時帶有套件成品與映像重用輸入。 ## 發行設定檔 -`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 成品 ## 工作流程檔案 diff --git a/docs/zh-TW/reference/test.md b/docs/zh-TW/reference/test.md index 643122800..015bcde91 100644 --- a/docs/zh-TW/reference/test.md +++ b/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 ` 作為測試證明。 -- `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