diff --git a/docs/zh-TW/concepts/qa-e2e-automation.md b/docs/zh-TW/concepts/qa-e2e-automation.md index d8618aac5..975c073c2 100644 --- a/docs/zh-TW/concepts/qa-e2e-automation.md +++ b/docs/zh-TW/concepts/qa-e2e-automation.md @@ -1,80 +1,71 @@ --- read_when: - - 了解品質保證堆疊如何協同運作 + - 了解 QA 堆疊如何協同運作 - 擴充 qa-lab、qa-channel 或傳輸配接器 - - 新增由儲存庫支援的 QA 情境 - - 圍繞 Gateway 儀表板建立更高擬真度的 QA 自動化 -summary: QA 堆疊概覽：qa-lab、qa-channel、由 repo 支援的情境、即時傳輸通道、傳輸轉接器，以及報告。 -title: QA 概觀 + - 新增以儲存庫為後盾的 QA 情境 + - 圍繞 Gateway 儀表板建構更高真實度的 QA 自動化 +summary: QA 堆疊概觀：qa-lab、qa-channel、以儲存庫支援的情境、即時傳輸通道、傳輸配接器與報告。 +title: 品質保證概觀 x-i18n: - generated_at: "2026-05-03T21:31:22Z" + generated_at: "2026-05-04T02:44:27Z" model: gpt-5.5 provider: openai - source_hash: 6a1446fddb00855634d34662a0a47be1e5054a9e7bfed5bc9ae21185d87094d8 + source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba 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 plugins：即時傳輸介面卡， - 會在子 QA gateway 內驅動真實通道。 -- `qa/`：由 repo 支援的啟動任務種子資產與基準 QA - 情境。 -- [Mantis](/zh-TW/concepts/mantis)：針對需要真實傳輸、瀏覽器截圖、VM 狀態與 PR 證據的錯誤， - 進行修正前後的即時驗證。 +- `extensions/qa-channel`：合成訊息通道，具備 DM、頻道、執行緒、反應、編輯與刪除介面。 +- `extensions/qa-lab`：除錯器 UI 與 QA 匯流排，用於觀察逐字稿、注入傳入訊息，以及匯出 Markdown 報告。 +- `extensions/qa-matrix`、未來的執行器 Plugin：即時傳輸配接器，會在子 QA gateway 內驅動真實通道。 +- `qa/`：由 repo 支援的 kickoff 任務與基準 QA 情境種子資產。 +- [Mantis](/zh-TW/concepts/mantis)：針對需要真實傳輸、瀏覽器螢幕截圖、VM 狀態與 PR 證據的錯誤，進行修正前後的即時驗證。 -## 指令介面 +## 命令介面 -每個 QA 流程都在 `pnpm openclaw qa ` 下執行。許多都有 `pnpm qa:*` -script 別名；兩種形式都受支援。 +每個 QA 流程都在 `pnpm openclaw qa ` 下執行。許多流程有 `pnpm qa:*` script 別名；兩種形式都支援。 -| 指令 | 用途 | -| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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 執行一次性提示。 | -| `qa ui` | 啟動 QA 偵錯器 UI 與本機 QA 匯流排（別名：`pnpm qa:lab:ui`）。 | -| `qa docker-build-image` | 建置預先烘焙的 QA Docker 映像。 | -| `qa docker-scaffold` | 寫入 QA dashboard + gateway lane 的 docker-compose scaffold。 | -| `qa up` | 建置 QA site、啟動 Docker 支援的 stack、印出 URL（別名：`pnpm qa:lab:up`；`:fast` 變體會加入 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。 | -| `qa aimock` | 只啟動 AIMock provider server。 | -| `qa mock-openai` | 只啟動具情境感知的 `mock-openai` provider server。 | -| `qa credentials doctor` / `add` / `list` / `remove` | 管理共用 Convex credential pool。 | -| `qa matrix` | 針對一次性 Tuwunel homeserver 的即時傳輸 lane。請參閱 [Matrix QA](/zh-TW/concepts/qa-matrix)。 | -| `qa telegram` | 針對真實私有 Telegram 群組的即時傳輸 lane。 | -| `qa discord` | 針對真實私有 Discord guild channel 的即時傳輸 lane。 | -| `qa mantis` | 用於即時傳輸錯誤修正前後驗證的 runner，包含第一個 Discord 狀態反應情境。請參閱 [Mantis](/zh-TW/concepts/mantis)。 | +| 命令 | 用途 | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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` 檔案，並寫入 agentic 對等報告。 | +| `qa character-eval` | 跨多個即時模型執行角色 QA 情境，並產生經評判的報告。請參閱[報告](#reporting)。 | +| `qa manual` | 對選取的 provider/model lane 執行一次性提示。 | +| `qa ui` | 啟動 QA 除錯器 UI 與本機 QA 匯流排（別名：`pnpm qa:lab:ui`）。 | +| `qa docker-build-image` | 建置預先烘焙的 QA Docker 映像。 | +| `qa docker-scaffold` | 寫入 QA 儀表板 + gateway lane 的 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 的即時傳輸 lane。請參閱 [Matrix QA](/zh-TW/concepts/qa-matrix)。 | +| `qa telegram` | 針對真實私人 Telegram 群組的即時傳輸 lane。 | +| `qa discord` | 針對真實私人 Discord guild 頻道的即時傳輸 lane。 | +| `qa slack` | 針對真實私人 Slack 頻道的即時傳輸 lane。 | +| `qa mantis` | 針對即時傳輸錯誤的修正前後驗證執行器，包含 Discord 狀態反應證據與 Crabbox 桌面/瀏覽器 smoke。請參閱 [Mantis](/zh-TW/concepts/mantis)。 | -## 操作者流程 +## 操作員流程 -目前的 QA 操作者流程是一個雙窗格 QA site： +目前的 QA 操作員流程是雙窗格 QA 站台： -- 左側：帶有代理程式的 Gateway dashboard（Control UI）。 +- 左側：含 agent 的 Gateway 儀表板（控制 UI）。 - 右側：QA Lab，顯示類 Slack 的逐字稿與情境計畫。 -使用以下指令執行： +執行方式： ```bash pnpm qa:lab:up ``` -這會建置 QA site、啟動 Docker 支援的 gateway lane，並公開 -QA Lab 頁面，讓操作者或自動化迴圈可以給代理程式 QA -任務、觀察真實通道行為，並記錄哪些成功、失敗或 -仍受阻。 +這會建置 QA 站台、啟動 Docker 支援的 gateway lane，並公開 QA Lab 頁面，讓操作員或自動化迴圈可以給 agent 一個 QA 任務、觀察真實通道行為，並記錄哪些項目成功、失敗或仍遭阻塞。 -若要更快反覆開發 QA Lab UI，而不必每次都重建 Docker 映像， -請使用 bind-mounted QA Lab bundle 啟動 stack： +若要更快速地迭代 QA Lab UI，而不必每次都重建 Docker 映像，請使用 bind-mounted QA Lab bundle 啟動堆疊： ```bash pnpm openclaw qa docker-build-image @@ -83,10 +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` container。`qa:lab:watch` -會在變更時重建該 bundle，而當 QA Lab -資產 hash 變更時，瀏覽器會自動重新載入。 +`qa:lab:up:fast` 會讓 Docker 服務使用預先建置的映像，並將 `extensions/qa-lab/web/dist` bind-mount 到 `qa-lab` 容器中。`qa:lab:watch` 會在變更時重建該 bundle，而當 QA Lab 資產雜湊變更時，瀏覽器會自動重新載入。 若要進行本機 OpenTelemetry trace smoke，請執行： @@ -94,101 +82,82 @@ pnpm qa:lab:watch pnpm qa:otel:smoke ``` -該 script 會啟動本機 OTLP/HTTP trace receiver，在啟用 -`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.*` attributes 必須留在 trace 之外。它會在 QA suite artifacts 旁寫入 -`otel-smoke-summary.json`。 +該 script 會啟動本機 OTLP/HTTP trace 接收器，在啟用 `diagnostics-otel` Plugin 的情況下執行 `otel-trace-smoke` QA 情境，接著解碼匯出的 protobuf spans，並斷言 release-critical 形狀：必須存在 `openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、`openclaw.context.assembled` 與 `openclaw.message.delivery`；成功回合中的模型呼叫不得匯出 `StreamAbandoned`；原始診斷 ID 與 `openclaw.content.*` 屬性必須留在 trace 之外。它會在 QA suite artifact 旁寫入 `otel-smoke-summary.json`。 -可觀測性 QA 僅限 source checkout。npm tarball 會刻意省略 -QA Lab，因此 package Docker release lanes 不會執行 `qa` 指令。變更 diagnostics -instrumentation 時，請從已建置的 source checkout 使用 -`pnpm qa:otel:smoke`。 +Observability QA 僅適用於原始碼 checkout。npm tarball 會有意省略 QA Lab，因此套件 Docker release lane 不會執行 `qa` 命令。變更診斷 instrumentation 時，請從已建置的原始碼 checkout 執行 `pnpm qa:otel:smoke`。 -若要執行 transport-real Matrix smoke lane，請執行： +若要執行傳輸真實的 Matrix smoke lane，請執行： ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -此 lane 的完整 CLI 參考、profile/scenario 目錄、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 與合併輸出記錄。 +此 lane 的完整 CLI 參考、profile/情境目錄、環境變數與 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 與合併輸出日誌。 -針對 transport-real Telegram 與 Discord smoke lanes： +針對傳輸真實的 Telegram、Discord 與 Slack smoke lane： ```bash pnpm openclaw qa telegram pnpm openclaw qa discord +pnpm openclaw qa slack ``` -兩者都以既有真實通道為目標，並使用兩個 bots（driver + SUT）。必要 env vars、情境清單、輸出 artifacts 與 Convex credential pool 記錄於下方的 [Telegram 與 Discord QA 參考](#telegram-and-discord-qa-reference)。 +它們會以含兩個 bot（driver + SUT）的既有真實通道為目標。必要環境變數、情境清單、輸出 artifact 與 Convex 憑證池記錄於下方的 [Telegram、Discord 與 Slack QA 參考](#telegram-discord-and-slack-qa-reference)。 -使用 pooled live credentials 前，請執行： +使用集區化即時憑證之前，請執行： ```bash pnpm openclaw qa credentials doctor ``` -doctor 會檢查 Convex broker env、驗證 endpoint 設定，並在 maintainer secret 存在時驗證 admin/list 可達性。它只會回報 secret 的已設定/缺漏狀態。 +doctor 會檢查 Convex broker 環境、驗證 endpoint 設定，並在 maintainer secret 存在時驗證 admin/list 可達性。它只會回報 secret 的已設定/缺漏狀態。 -## 即時傳輸涵蓋率 +## 即時傳輸覆蓋率 -即時傳輸 lanes 共用一份契約，而不是各自發明自己的情境清單形狀。`qa-channel` 是廣泛的合成產品行為 suite，不屬於即時傳輸涵蓋率矩陣。 +即時傳輸 lane 共用一份合約，而不是各自發明自己的情境清單形狀。`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 | -| -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | -| Matrix | x | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | x | | | | | | | x | | -| Discord | x | x | x | | | | | | | | x | +| Lane | Canary | 提及閘控 | Bot 對 Bot | Allowlist 封鎖 | 頂層回覆 | 重新啟動續接 | 執行緒後續追蹤 | 執行緒隔離 | 反應觀察 | Help 命令 | 原生命令註冊 | +| -------- | ------ | -------- | ---------- | --------------- | -------- | ------------ | ---------------- | ------------ | -------- | --------- | ------------ | +| 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 與未來的即時傳輸共用一份明確的傳輸合約檢查清單。 -若要在不將 Docker 帶入 QA 路徑的情況下執行一次性 Linux VM lane，請執行： +若要在不把 Docker 帶入 QA 路徑的情況下執行一次性 Linux VM lane，請執行： ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -這會啟動全新的 Multipass guest、安裝 dependencies、在 guest 內建置 OpenClaw、 -執行 `qa suite`，然後將正常 QA 報告與 -摘要複製回 host 上的 `.artifacts/qa-e2e/...`。 +這會啟動全新的 Multipass guest、安裝相依性、在 guest 內建置 OpenClaw、執行 `qa suite`，接著將一般 QA 報告與摘要複製回 host 上的 `.artifacts/qa-e2e/...`。 它會重用與 host 上 `qa suite` 相同的情境選取行為。 -Host 與 Multipass suite runs 預設會使用隔離的 gateway workers 平行執行多個選取情境。 -`qa-channel` 預設 concurrency 為 -4，並受選取的情境數量限制。使用 `--concurrency ` 調整 -worker 數量，或使用 `--concurrency 1` 進行序列執行。 -當任何情境失敗時，指令會以非零碼結束。若你想要 artifacts 但不想要失敗的 exit code， -請使用 `--allow-failures`。 -Live runs 會轉送對 guest 實用且受支援的 QA auth inputs： -env-based provider keys、QA live provider config path，以及 -`CODEX_HOME`（若存在）。請將 `--output-dir` 保持在 repo root 下，讓 guest -可以透過掛載的 workspace 寫回。 +Host 與 Multipass suite run 預設會以隔離的 gateway workers 平行執行多個選取的情境。`qa-channel` 預設 concurrency 為 4，並受選取的情境數量上限限制。使用 `--concurrency ` 調整 worker 數量，或使用 `--concurrency 1` 進行序列執行。 +當任何情境失敗時，命令會以非零狀態結束。當你想要 artifact 而不要失敗的結束碼時，請使用 `--allow-failures`。 +即時 run 會轉送對 guest 實用的受支援 QA auth 輸入：以環境為基礎的 provider key、QA live provider 設定路徑，以及存在時的 `CODEX_HOME`。請將 `--output-dir` 保持在 repo root 底下，讓 guest 能透過掛載的 workspace 寫回。 -## Telegram 與 Discord QA 參考 +## Telegram、Discord 與 Slack QA 參考 -Matrix 有[專屬頁面](/zh-TW/concepts/qa-matrix)，因為它的情境數量與 Docker-backed homeserver 佈建較多。Telegram 與 Discord 較小型，每個只有少數情境、沒有 profile system，並針對既有真實通道，因此它們的參考放在這裡。 +Matrix 有一個[專屬頁面](/zh-TW/concepts/qa-matrix)，因為其情境數量與 Docker 支援的 homeserver 佈建。Telegram、Discord 與 Slack 較小，每個只有少數情境、沒有 profile 系統，並針對既有真實通道，因此它們的參考位於此處。 -### 共用 CLI flags +### 共享 CLI 旗標 -兩個 lanes 都透過 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 註冊，並接受相同 flags： +這些 lane 透過 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 註冊，並接受相同旗標： -| Flag | Default | Description | -| ------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | 只執行此情境。可重複指定。 | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord}-` | 寫入報告、摘要、觀察到的訊息與輸出記錄的位置。相對路徑會以 `--repo-root` 為基準解析。 | -| `--repo-root ` | `process.cwd()` | 從中立 cwd 呼叫時的儲存庫根目錄。 | -| `--sut-account ` | `sut` | QA Gateway 設定內的暫時帳號 ID。 | -| `--provider-mode ` | `live-frontier` | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可運作）。 | -| `--model ` / `--alt-model ` | 提供者預設值 | 主要/替代模型參照。 | -| `--fast` | 關閉 | 支援時使用提供者快速模式。 | -| `--credential-source ` | `env` | 請參閱 [Convex 憑證池](#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 呼叫時的儲存庫根目錄。 | +| `--sut-account ` | `sut` | QA Gateway 設定內的暫時帳號 id。 | +| `--provider-mode ` | `live-frontier` | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可使用）。 | +| `--model ` / `--alt-model ` | provider default | 主要／替代模型參照。 | +| `--fast` | off | 支援時啟用供應商快速模式。 | +| `--credential-source ` | `env` | 請參閱 [Convex 憑證池](#convex-credential-pool)。 | +| `--credential-role ` | CI 中為 `ci`，否則為 `maintainer` | 使用 `--credential-source convex` 時使用的角色。 | -任何情境失敗時，兩者都會以非零狀態結束。`--allow-failures` 會寫入成品，但不會設定失敗的結束代碼。 +任何情境失敗時，各通道都會以非零狀態結束。`--allow-failures` 會寫入成品，但不會設定失敗的退出碼。 ### Telegram QA @@ -196,17 +165,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 對 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` — 數值聊天 id（字串）。 - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` 選用： -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 會在觀察到的訊息成品中保留訊息本文（預設會遮蔽）。 +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文（預設會遮蔽）。 情境（`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`）： @@ -222,7 +191,7 @@ pnpm openclaw qa telegram 輸出成品： - `telegram-qa-report.md` -- `telegram-qa-summary.json` — 包含從 canary 開始的每則回覆 RTT（driver 傳送 → 觀察到 SUT 回覆）。 +- `telegram-qa-summary.json` — 從 canary 開始，包含每則回覆的 RTT（driver 傳送 → 觀察到 SUT 回覆）。 - `telegram-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`，否則本文會被遮蔽。 ### Discord QA @@ -231,28 +200,28 @@ pnpm openclaw qa telegram pnpm openclaw qa discord ``` -目標是一個真實的私人 Discord guild 頻道，並使用兩個 Bot：由測試框架控制的 driver Bot，以及由子 OpenClaw Gateway 透過內建 Discord Plugin 啟動的 SUT Bot。會驗證頻道提及處理、SUT Bot 已向 Discord 註冊原生 `/help` 指令，以及選擇啟用的 Mantis 證據情境。 +目標是一個真實的私人 Discord guild 頻道，搭配兩個 bot：由測試框架控制的 driver bot，以及由子 OpenClaw Gateway 透過 bundled Discord plugin 啟動的 SUT bot。驗證頻道提及處理、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 使用者 ID（否則該通道會快速失敗）。 +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必須符合 Discord 傳回的 SUT bot 使用者 id（否則該通道會快速失敗）。 選用： -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 會在觀察到的訊息成品中保留訊息本文。 +- `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` — 選擇啟用的 Mantis 情境。因為它會將 SUT 切換為永遠開啟、僅工具的 guild 回覆，並設定 `messages.statusReactions.enabled=true`，接著擷取 REST reaction 時間軸以及 HTML/PNG 視覺成品，所以會單獨執行。 +- `discord-status-reactions-tool-only` — 選擇啟用的 Mantis 情境。因為它會將 SUT 切換為一律啟用、僅工具的 guild 回覆，並設定 `messages.statusReactions.enabled=true`，接著擷取 REST 反應時間軸以及 HTML/PNG 視覺成品，所以會單獨執行。 -明確執行 Mantis status-reaction 情境： +明確執行 Mantis 狀態反應情境： ```bash pnpm openclaw qa discord \ @@ -268,118 +237,148 @@ pnpm openclaw qa discord \ - `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-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。 + +### Slack QA + +```bash +pnpm openclaw qa slack +``` + +目標是一個真實的私人 Slack 頻道，搭配兩個不同的 bot：由測試框架控制的 driver bot，以及由子 OpenClaw Gateway 透過 bundled Slack plugin 啟動的 SUT bot。 + +使用 `--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` 會在觀察訊息成品中保留訊息本文。 + +情境（`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`，否則本文會被遮蔽。 ### Convex 憑證池 -Telegram 和 Discord 通道都可以從共用的 Convex 池租用憑證，而不是讀取上方 env vars。傳入 `--credential-source convex`（或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 會取得獨佔租約、在執行期間對租約送出 Heartbeat，並在關閉時釋放租約。池種類為 `"telegram"` 和 `"discord"`。 +Telegram、Discord 和 Slack 通道可以從共享的 Convex 池租用憑證，而不是讀取上述 env vars。傳入 `--credential-source convex`（或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 會取得一個獨佔租約，在執行期間傳送 Heartbeat，並在關閉時釋放租約。池種類為 `"telegram"`、`"discord"` 和 `"slack"`。 -Broker 在 `admin/add` 驗證的 payload 形狀： +Broker 會在 `admin/add` 驗證的 payload 形狀： -- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }` — `groupId` 必須是數字 chat-id 字串。 +- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }` — `groupId` 必須是數值聊天 id 字串。 - Discord（`kind: "discord"`）：`{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`。 -操作用 env vars 與 Convex broker 端點合約位於 [測試 → 透過 Convex 共用 Telegram 憑證](/zh-TW/help/testing#shared-telegram-credentials-via-convex-v1)（該區段名稱早於 Discord 支援；兩種種類的 broker 語義相同）。 +操作用 env vars 和 Convex broker 端點合約位於 [測試 → 透過 Convex 共享 Telegram 憑證](/zh-TW/help/testing#shared-telegram-credentials-via-convex-v1)（該章節名稱早於 Discord 支援；兩種種類的 broker 語意相同）。 -## Repo 支援的種子 +## 儲存庫支援的種子 種子資產位於 `qa/`： - `qa/scenarios/index.md` - `qa/scenarios//*.md` -這些刻意放在 git 中，讓 QA 計畫對人類與代理都可見。 +這些檔案刻意放在 git 中，讓 QA 計畫對人員與 agent 都可見。 -`qa-lab` 應保持為通用 markdown 執行器。每個情境 markdown 檔案都是一次測試執行的事實來源，並應定義： +`qa-lab` 應保持為通用 markdown runner。每個情境 markdown 檔案都是一次測試執行的真實來源，且應定義： - 情境中繼資料 -- 選用的分類、能力、通道與風險中繼資料 +- 選用的類別、能力、通道和風險中繼資料 - 文件與程式碼參照 -- 選用的 Plugin 需求 -- 選用的 Gateway 設定 patch +- 選用的 plugin 需求 +- 選用的 Gateway 設定修補 - 可執行的 `qa-flow` -支援 `qa-flow` 的可重用 runtime 介面可以維持通用且跨領域。例如，markdown 情境可以結合傳輸端輔助工具與瀏覽器端輔助工具，透過 Gateway `browser.request` seam 驅動內嵌 Control UI，而不需要加入特殊案例執行器。 +支援 `qa-flow` 的可重用執行階段介面可以保持通用且跨面向。例如，markdown 情境可以結合傳輸端 helper 與瀏覽器端 helper，透過 Gateway `browser.request` seam 驅動內嵌的 Control UI，而不需要加入特殊案例 runner。 -情境檔案應依產品能力分組，而不是依原始碼樹資料夾分組。檔案移動時請保持情境 ID 穩定；使用 `docsRefs` 和 `codeRefs` 追蹤實作。 +情境檔案應依產品能力分組，而不是依原始碼樹資料夾分組。檔案移動時請保持情境 ID 穩定；使用 `docsRefs` 和 `codeRefs` 進行實作可追溯性。 基準清單應保持足夠廣泛，以涵蓋： -- DM 與頻道聊天 +- DM 和頻道聊天 - thread 行為 - 訊息動作生命週期 -- cron callback +- cron callbacks - 記憶回想 - 模型切換 -- 子代理交接 -- 儲存庫讀取與文件讀取 +- subagent handoff +- 讀取儲存庫與讀取文件 - 一個小型建置任務，例如 Lobster Invaders -## 提供者模擬通道 +## 供應商 mock 通道 -`qa suite` 有兩個本機提供者模擬通道： +`qa suite` 有兩個本機供應商 mock 通道： -- `mock-openai` 是具備情境感知能力的 OpenClaw 模擬。它仍是 repo 支援 QA 與 parity gate 的預設決定性模擬通道。 -- `aimock` 會啟動 AIMock 支援的提供者伺服器，用於實驗性協定、fixture、record/replay 與 chaos 覆蓋。它是加成項，不會取代 `mock-openai` 情境分派器。 +- `mock-openai` 是具情境感知的 OpenClaw mock。它仍是儲存庫支援 QA 和 parity gates 的預設決定性 mock 通道。 +- `aimock` 會啟動由 AIMock 支援的供應商伺服器，用於實驗性通訊協定、fixture、record/replay 和 chaos 覆蓋。它是加成性質，且不會取代 `mock-openai` 情境 dispatcher。 -提供者通道實作位於 `extensions/qa-lab/src/providers/`。每個提供者都擁有自己的預設值、本機伺服器啟動、Gateway 模型設定、auth-profile 暫存需求，以及 live/mock 能力旗標。共用 suite 與 Gateway 程式碼應透過提供者登錄路由，而不是依提供者名稱分支。 +供應商通道實作位於 `extensions/qa-lab/src/providers/` 之下。每個供應商都擁有自己的預設值、本機伺服器啟動、Gateway 模型設定、auth-profile staging 需求，以及 live/mock 能力旗標。共享 suite 和 Gateway 程式碼應透過供應商 registry 路由，而不是依供應商名稱分支。 ## 傳輸配接器 -`qa-lab` 擁有用於 markdown QA 情境的通用傳輸 seam。`qa-channel` 是該 seam 上的第一個配接器，但設計目標更廣：未來真實或合成頻道應接入同一個 suite 執行器，而不是新增傳輸專用 QA 執行器。 +`qa-lab` 擁有一個供 markdown QA 情境使用的通用傳輸 seam。`qa-channel` 是該 seam 上的第一個配接器，但設計目標更廣：未來真實或合成頻道應接入相同的 suite runner，而不是加入傳輸專屬 QA runner。 在架構層級，分工如下： - `qa-lab` 擁有通用情境執行、worker 並行、成品寫入與報告。 -- 傳輸配接器擁有 Gateway 設定、就緒狀態、輸入與輸出觀察、傳輸動作，以及正規化傳輸狀態。 -- `qa/scenarios/` 下的 markdown 情境檔案定義測試執行；`qa-lab` 提供執行它們的可重用 runtime 介面。 +- 傳輸配接器擁有 Gateway 設定、就緒狀態、入站與出站觀察、傳輸動作，以及正規化傳輸狀態。 +- `qa/scenarios/` 下的 markdown 情境檔案定義測試執行；`qa-lab` 提供執行它們的可重用執行階段介面。 ### 新增頻道 -將頻道加入 markdown QA 系統只需要兩件事： +將頻道加入 markdown QA 系統時，只需要兩件事： 1. 該頻道的傳輸配接器。 -2. 測試該頻道合約的情境包。 +2. 測試該頻道合約的情境套件。 -當共用 `qa-lab` host 可以擁有流程時，請勿新增頂層 QA 指令根。 +當共享的 `qa-lab` host 可以擁有流程時，不要新增新的頂層 QA 命令根。 -`qa-lab` 擁有共用 host 機制： +`qa-lab` 擁有共享 host 機制： -- `openclaw qa` 指令根 -- suite 啟動與拆卸 +- `openclaw qa` 命令根 +- suite 啟動與拆除 - worker 並行 - 成品寫入 - 報告產生 - 情境執行 -- 舊版 `qa-channel` 情境的相容 alias +- 舊版 `qa-channel` 情境的相容別名 -執行器 Plugin 擁有傳輸合約： +Runner plugins 擁有傳輸合約： -- `openclaw qa ` 如何掛載在共用 `qa` 根底下 -- 如何為該傳輸設定 Gateway +- `openclaw qa ` 如何掛載在共享 `qa` 根之下 +- Gateway 如何針對該傳輸進行設定 - 如何檢查就緒狀態 -- 如何注入輸入事件 -- 如何觀察輸出訊息 -- 如何公開 transcript 與正規化傳輸狀態 +- 如何注入入站事件 +- 如何觀察出站訊息 +- 如何公開 transcripts 和正規化傳輸狀態 - 如何執行傳輸支援的動作 -- 如何處理傳輸專用 reset 或清理 +- 如何處理傳輸專屬重設或清理 新頻道的最低採用門檻： -1. 讓 `qa-lab` 繼續作為共用 `qa` 根的擁有者。 -2. 在共用 `qa-lab` host seam 上實作傳輸執行器。 -3. 將傳輸專用機制保留在執行器 Plugin 或頻道測試框架內。 -4. 將執行器掛載為 `openclaw qa `，而不是註冊競爭的根指令。執行器 Plugin 應在 `openclaw.plugin.json` 宣告 `qaRunners`，並從 `runtime-api.ts` 匯出相符的 `qaRunnerCliRegistrations` 陣列。保持 `runtime-api.ts` 輕量；lazy CLI 與執行器執行應留在個別進入點後方。 -5. 在主題式 `qa/scenarios/` 目錄下撰寫或改寫 markdown 情境。 -6. 為新情境使用通用情境輔助工具。 -7. 除非儲存庫正在進行有意的遷移，否則保持既有相容 alias 可運作。 +1. 保留 `qa-lab` 作為共用 `qa` 根的擁有者。 +2. 在共用的 `qa-lab` 主機銜接層上實作傳輸執行器。 +3. 將傳輸專屬機制保留在執行器 Plugin 或通道測試工具中。 +4. 將執行器掛載為 `openclaw qa `，而不是註冊互相競爭的根命令。執行器 Plugin 應在 `openclaw.plugin.json` 中宣告 `qaRunners`，並從 `runtime-api.ts` 匯出相符的 `qaRunnerCliRegistrations` 陣列。讓 `runtime-api.ts` 保持輕量；延遲 CLI 和執行器執行應保留在獨立進入點後方。 +5. 在主題式 `qa/scenarios/` 目錄下撰寫或調整 Markdown 情境。 +6. 對新情境使用通用情境輔助工具。 +7. 除非 repo 正在進行有意的遷移，否則保持現有相容性別名可用。 決策規則很嚴格： - 如果行為可以在 `qa-lab` 中表達一次，就放在 `qa-lab`。 -- 如果行為取決於單一頻道傳輸，就保留在該執行器 Plugin 或 Plugin 測試框架中。 -- 如果某個情境需要多個頻道都能使用的新能力，請新增通用輔助工具，而不是在 `suite.ts` 中加入頻道專用分支。 -- 如果某個行為只對單一傳輸有意義，請讓情境維持傳輸專用，並在情境合約中明確表示。 +- 如果行為依賴單一通道傳輸，就將它保留在該執行器 Plugin 或 Plugin 測試工具中。 +- 如果情境需要多個通道都能使用的新能力，請新增通用輔助工具，而不是在 `suite.ts` 中加入通道專屬分支。 +- 如果某個行為只對單一傳輸有意義，請讓情境保持傳輸專屬，並在情境契約中明確說明。 ### 情境輔助工具名稱 @@ -398,22 +397,22 @@ Broker 在 `admin/add` 驗證的 payload 形狀： - `formatTransportTranscript` - `resetTransport` -相容性別名仍可用於現有情境 — `waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus` — 但新的情境撰寫應使用通用名稱。這些別名的存在是為了避免一次性遷移，而不是未來的模式。 +相容性別名仍可供現有情境使用 — `waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus` — 但撰寫新情境時應使用通用名稱。這些別名存在是為了避免一次性遷移，而不是未來的模型。 ## 回報 `qa-lab` 會從觀察到的匯流排時間軸匯出 Markdown 協定報告。 報告應回答： -- 哪些項目正常運作 -- 哪些項目失敗 -- 哪些項目仍受阻 +- 哪些正常運作 +- 哪些失敗 +- 哪些仍受阻 - 哪些後續情境值得加入 -若要取得可用情境的清單 — 在評估後續工作規模或接入新傳輸時很有用 — 請執行 `pnpm openclaw qa coverage`（加入 `--json` 可取得機器可讀輸出）。 +若要查看可用情境清單 — 在評估後續工作規模或接線新傳輸時很有用 — 請執行 `pnpm openclaw qa coverage`（加入 `--json` 取得機器可讀輸出）。 -若要進行角色與風格檢查，請在多個即時模型 -refs 上執行相同情境，並寫出經評審的 Markdown 報告： +若要進行角色與風格檢查，請跨多個即時模型 +refs 執行相同情境，並撰寫經評審的 Markdown 報告： ```bash pnpm openclaw qa character-eval \ @@ -434,30 +433,31 @@ pnpm openclaw qa character-eval \ 此命令會執行本機 QA Gateway 子程序，而不是 Docker。角色評估 情境應透過 `SOUL.md` 設定 persona，然後執行一般使用者回合， -例如聊天、工作區協助，以及小型檔案任務。不應告知候選模型 -它正在被評估。此命令會保留每份完整 -transcript，記錄基本執行統計資料，然後在支援時以快速模式搭配 -`xhigh` reasoning 詢問評審模型，依自然度、氛圍和幽默感為執行結果排名。 -比較不同提供者時請使用 `--blind-judge-models`：評審提示仍會取得 -每份 transcript 和執行狀態，但候選 refs 會被替換為中性的 +例如聊天、workspace 協助，以及小型檔案任務。不應告知候選模型 +它正在接受評估。此命令會保留每份完整 +transcript、記錄基本執行統計，然後請評審模型以快速模式搭配 +支援時的 `xhigh` reasoning，依自然度、氛圍和幽默感對執行結果排名。 +比較供應商時使用 `--blind-judge-models`：評審提示仍會取得 +每份 transcript 與執行狀態，但候選 refs 會替換成中性 標籤，例如 `candidate-01`；報告會在解析後將排名對應回真實 refs。 -候選執行預設使用 `high` thinking，GPT-5.5 使用 `medium`，較舊且支援的 OpenAI 評估 refs 使用 `xhigh`。可用 -`--model provider/model,thinking=` 內嵌覆寫特定候選。`--thinking ` 仍會設定 -全域備援，而較舊的 `--model-thinking ` 形式會 -保留以維持相容性。 -OpenAI 候選 refs 預設使用快速模式，因此在提供者支援時會使用 -優先處理。當單一候選或評審需要覆寫時，請內嵌加入 `,fast`、`,no-fast` 或 `,fast=false`。只有在你想要 -強制所有候選模型開啟快速模式時，才傳入 `--fast`。候選與評審的耗時會 -記錄在報告中供基準分析使用，但評審提示會明確說明 +候選執行預設使用 `high` thinking，GPT-5.5 使用 `medium`，而支援它的 +較舊 OpenAI 評估 refs 使用 `xhigh`。用 +`--model provider/model,thinking=` 內聯覆寫特定候選。`--thinking ` 仍會設定 +全域 fallback，且較舊的 `--model-thinking ` 形式 +會保留以維持相容性。 +OpenAI 候選 refs 預設使用快速模式，因此在供應商支援時會使用 +優先處理。當單一候選或評審需要覆寫時，請內聯加入 `,fast`、`,no-fast` 或 `,fast=false`。只有在想要 +強制所有候選模型開啟快速模式時才傳入 `--fast`。候選和評審耗時會 +記錄在報告中以供基準分析，但評審提示會明確要求 不要依速度排名。 -候選與評審模型執行預設並行度皆為 16。當提供者限制或本機 Gateway -壓力使執行過於嘈雜時，請降低 +候選與評審模型執行都預設使用並行度 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`。 +未傳入 `--model` 時的 `google/gemini-3.1-pro-preview`。 未傳入 `--judge-model` 時，評審預設為 `openai/gpt-5.5,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。 @@ -467,4 +467,4 @@ OpenAI 候選 refs 預設使用快速模式，因此在提供者支援時會使 - [矩陣 QA](/zh-TW/concepts/qa-matrix) - [QA 通道](/zh-TW/channels/qa-channel) - [測試](/zh-TW/help/testing) -- [儀表板](/zh-TW/web/dashboard) +- [Dashboard](/zh-TW/web/dashboard) diff --git a/docs/zh-TW/concepts/system-prompt.md b/docs/zh-TW/concepts/system-prompt.md index e1f70db16..76f25cea3 100644 --- a/docs/zh-TW/concepts/system-prompt.md +++ b/docs/zh-TW/concepts/system-prompt.md @@ -1,145 +1,149 @@ --- read_when: - 編輯系統提示詞文字、工具清單或時間/Heartbeat 區段 - - 變更工作區啟動程序或 Skills 注入行為 -summary: OpenClaw 系統提示包含哪些內容及其組裝方式 + - 變更工作區初始化或 Skills 注入行為 +summary: OpenClaw 系統提示包含的內容及其組裝方式 title: 系統提示詞 x-i18n: - generated_at: "2026-05-03T21:31:20Z" + generated_at: "2026-05-04T02:44:15Z" model: gpt-5.5 provider: openai - source_hash: 93533ac8090897a7b5fd82b80e542a4ad573670408314b3519c5e317d0408ade + source_hash: 5e6067e760eccf58106f0a646c2656e902d5951580abd750f342d70b0568b81b source_path: concepts/system-prompt.md workflow: 16 --- -OpenClaw 會為每次代理執行建構自訂系統提示。該提示由 **OpenClaw 擁有**，不使用 pi-coding-agent 預設提示。 +OpenClaw 會為每次代理執行建構自訂系統提示詞。該提示詞由 **OpenClaw 擁有**，且不使用 pi-coding-agent 預設提示詞。 -提示由 OpenClaw 組裝，並注入每次代理執行中。 +提示詞由 OpenClaw 組裝，並注入每次代理執行中。 -提供者 Plugin 可以貢獻具快取感知能力的提示指引，而不取代 -完整的 OpenClaw 擁有提示。提供者執行階段可以： +供應商 Plugin 可以提供具備快取感知能力的提示詞指引，而不取代 +完整的 OpenClaw 擁有提示詞。供應商執行階段可以： - 取代一小組具名核心區段（`interaction_style`、 `tool_call_style`、`execution_bias`） -- 在提示快取邊界上方注入 **穩定前綴** -- 在提示快取邊界下方注入 **動態後綴** +- 在提示詞快取邊界上方注入**穩定前綴** +- 在提示詞快取邊界下方注入**動態後綴** -使用提供者擁有的貢獻來進行模型系列特定的調校。保留舊版 -`before_prompt_build` 提示變更機制，用於相容性或真正全域的提示 -變更，而不是一般提供者行為。 +使用供應商擁有的貢獻來進行特定模型系列調校。保留舊版 +`before_prompt_build` 提示詞變異，用於相容性或真正全域的提示詞 +變更，而非一般供應商行為。 OpenAI GPT-5 系列覆蓋層會讓核心執行規則保持精簡，並加入 -模型特定指引，涵蓋角色鎖定、精簡輸出、工具紀律、 -平行查詢、交付項目覆蓋、驗證、缺少情境，以及 +針對模型的指引，涵蓋人設鎖定、精簡輸出、工具紀律、 +平行查詢、交付內容覆蓋、驗證、缺少脈絡，以及 終端工具衛生。 ## 結構 -提示刻意保持精簡，並使用固定區段： +提示詞刻意保持精簡，並使用固定區段： -- **工具**：結構化工具的真實來源提醒，加上執行階段工具使用指引。 -- **執行偏向**：精簡的貫徹執行指引：對可行動請求在當回合採取行動， - 持續直到完成或受阻，從弱工具結果中恢復，對可變狀態進行即時檢查， +- **工具**：結構化工具真實來源提醒，加上執行階段工具使用指引。 +- **執行偏向**：精簡的跟進指引：針對可執行請求在同一回合採取行動， + 持續進行直到完成或受阻，從不佳的工具結果中復原，即時檢查可變狀態， 並在最終回覆前驗證。 -- **安全**：簡短護欄提醒，避免追求權力的行為或繞過監督。 -- **Skills**（可用時）：告知模型如何依需求載入 skill 指示。 +- **安全**：簡短的防護提醒，避免追求權力的行為或繞過監督。 +- **Skills**（可用時）：告知模型如何按需載入技能指示。 - **OpenClaw 自我更新**：如何使用 `config.schema.lookup` 安全檢查設定、使用 `config.patch` 修補設定、 - 使用 `config.apply` 取代完整設定，並只在使用者明確要求時執行 - `update.run`。僅限擁有者使用的 `gateway` 工具也會拒絕重寫 - `tools.exec.ask` / `tools.exec.security`，包括會正規化到這些受保護 + 使用 `config.apply` 取代完整設定，以及僅在使用者明確要求時執行 + `update.run`。僅限擁有者的 `gateway` 工具也會拒絕重寫 + `tools.exec.ask` / `tools.exec.security`，包括會正規化為這些受保護 exec 路徑的舊版 `tools.bash.*` 別名。 - **工作區**：工作目錄（`agents.defaults.workspace`）。 -- **文件**：OpenClaw 文件的本機路徑（repo 或 npm 套件），以及何時閱讀它們。 -- **工作區檔案（已注入）**：表示啟動檔案已包含於下方。 +- **文件**：OpenClaw 文件的本機路徑（repo 或 npm 套件），以及何時讀取。 +- **工作區檔案（已注入）**：表示啟動檔案已包含在下方。 - **沙箱**（啟用時）：表示沙箱化執行階段、沙箱路徑，以及是否可使用提升權限的 exec。 - **目前日期與時間**：使用者本地時間、時區與時間格式。 -- **回覆標籤**：支援提供者的選用回覆標籤語法。 -- **Heartbeats**：當預設代理啟用 heartbeats 時的 heartbeat 提示與確認行為。 +- **回覆標籤**：支援供應商的選用回覆標籤語法。 +- **Heartbeat**：預設代理啟用 Heartbeat 時的 Heartbeat 提示詞與 ack 行為。 - **執行階段**：主機、作業系統、node、模型、repo 根目錄（偵測到時）、思考層級（一行）。 - **推理**：目前可見性層級 + /reasoning 切換提示。 -OpenClaw 會將大型穩定內容（包括 **專案情境**）保留在 -內部提示快取邊界上方。易變的頻道/工作階段區段，例如 -Control UI 嵌入指引、**訊息傳遞**、**語音**、**群組聊天情境**、 -**反應**、**Heartbeats** 和 **執行階段**，會附加在該邊界下方， -讓具前綴快取的本機後端可在跨頻道回合中重用穩定的工作區前綴。 -同樣地，當已接受的 schema 已承載該執行階段細節時， -工具描述應避免嵌入目前頻道名稱。 +OpenClaw 會將大型穩定內容（包括**專案脈絡**）保留在 +內部提示詞快取邊界上方。易變的頻道/工作階段區段，例如 +Control UI 嵌入指引、**訊息傳遞**、**語音**、**群組聊天脈絡**、 +**反應**、**Heartbeat** 與**執行階段**，會附加在該邊界下方， +讓具有前綴快取的本機後端能跨頻道回合重用穩定的工作區前綴。 +工具描述同樣應避免嵌入目前頻道名稱，當已接受的 schema +已攜帶該執行階段細節時更是如此。 工具區段也包含長時間執行工作的執行階段指引： -- 針對未來追蹤（`check back later`、提醒、週期性工作）使用 cron， - 而不是 `exec` sleep 迴圈、`yieldMs` 延遲技巧或重複的 `process` +- 使用 cron 處理未來跟進（`check back later`、提醒、週期性工作）， + 而不是 `exec` 睡眠迴圈、`yieldMs` 延遲技巧，或重複的 `process` 輪詢 -- 只將 `exec` / `process` 用於現在開始並在背景持續執行的命令 -- 啟用自動完成喚醒時，啟動命令一次，並在它發出輸出或失敗時依賴 - push 型喚醒路徑 -- 當你需要檢查正在執行的命令時，使用 `process` 查看日誌、狀態、 - 輸入或介入 -- 如果任務較大，優先使用 `sessions_spawn`；子代理完成是 push 型， - 並會自動向請求者公告 -- 不要為了等待完成而在迴圈中輪詢 `subagents list` / `sessions_list` +- 只有在命令立即開始且會在背景繼續執行時，才使用 `exec` / `process` +- 啟用自動完成喚醒時，只啟動命令一次，並在其輸出或失敗時仰賴 + 推送式喚醒路徑 +- 當你需要檢查執行中命令的日誌、狀態、輸入或介入時，使用 `process` +- 如果任務較大，優先使用 `sessions_spawn`；子代理完成是推送式， + 並會自動向請求者宣告 +- 不要只為了等待完成而在迴圈中輪詢 `subagents list` / `sessions_list` -啟用實驗性 `update_plan` 工具時，工具區段也會告訴模型僅對非瑣碎的多步驟工作使用它、精確保持一個 `in_progress` 步驟，並避免在每次更新後重複整個計畫。 +啟用實驗性 `update_plan` 工具時，工具區段也會告訴模型 +只在非平凡的多步驟工作中使用它，保持剛好一個 `in_progress` 步驟， +並避免每次更新後重複整個計畫。 -系統提示中的安全護欄是建議性質。它們會引導模型行為，但不強制執行政策。請使用工具政策、exec 核准、沙箱化和頻道允許清單進行硬性執行；營運者可依設計停用這些機制。 +系統提示詞中的安全防護是建議性質。它們引導模型行為，但不強制執行政策。請使用工具政策、exec 核准、沙箱化與頻道允許清單進行強制執行；操作員可依設計停用這些機制。 -在具有原生核准卡片/按鈕的頻道上，執行階段提示現在會告訴 -代理優先依賴該原生核准 UI。只有當工具結果表示聊天核准不可用， +在具有原生核准卡片/按鈕的頻道上，執行階段提示詞現在會告訴 +代理優先依賴該原生核准 UI。只有在工具結果表示聊天核准不可用， 或手動核准是唯一途徑時，才應包含手動 `/approve` 命令。 -## 提示模式 +## 提示詞模式 -OpenClaw 可以為子代理呈現較小的系統提示。執行階段會為每次執行設定 +OpenClaw 可以為子代理呈現較小的系統提示詞。執行階段會為每次執行設定 `promptMode`（不是面向使用者的設定）： - `full`（預設）：包含上述所有區段。 -- `minimal`：用於子代理；省略 **Skills**、**Memory Recall**、**OpenClaw +- `minimal`：用於子代理；省略 **Skills**、**記憶召回**、**OpenClaw 自我更新**、**模型別名**、**使用者身分**、**回覆標籤**、 - **訊息傳遞**、**靜默回覆** 和 **Heartbeats**。工具、**安全**、 - 工作區、沙箱、目前日期與時間（已知時）、執行階段和已注入情境 - 仍可使用。 + **訊息傳遞**、**靜默回覆** 與 **Heartbeat**。工具、**安全**、 + 工作區、沙箱、目前日期與時間（已知時）、執行階段與注入脈絡 + 仍會保留。 - `none`：只回傳基礎身分行。 -當 `promptMode=minimal` 時，額外注入的提示會標示為 **子代理情境**， -而不是 **群組聊天情境**。 +當 `promptMode=minimal` 時，額外注入的提示詞會標示為**子代理 +脈絡**，而不是**群組聊天脈絡**。 -對於頻道自動回覆執行，當直接/群組聊天情境已包含已解析的 -對話特定 `NO_REPLY` 行為時，OpenClaw 可以省略通用的 **靜默回覆** -區段。這可避免在全域系統提示和頻道情境中重複 token 機制。 +對於頻道自動回覆執行，當直接/群組聊天脈絡已包含已解析的 +特定對話 `NO_REPLY` 行為時，OpenClaw 可以省略通用的**靜默回覆** +區段。這避免在全域系統提示詞與頻道脈絡中重複 token 機制。 -## 提示快照 +## 提示詞快照 OpenClaw 會在 -`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/` 下保留 -Codex 執行階段快樂路徑的已提交提示快照。它們會呈現選定的 app-server -thread/turn 參數，以及重建的模型繫結提示層堆疊，用於 Telegram 直接、 -Discord 群組和 heartbeat 回合。該堆疊包含從 Codex 模型目錄/快取形狀 -產生的已釘選 Codex `gpt-5.5` 模型提示 fixture、Codex 快樂路徑權限 -developer 文字、OpenClaw developer 指示、OpenClaw 提供時的回合範圍 -協作模式指示、使用者回合輸入，以及對動態工具規格的參照。 +`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/` 下 +保留已提交的 Codex 執行階段快樂路徑提示詞快照。它們會呈現 +選定的 app-server thread/turn 參數，以及重建的模型綁定提示詞 +層堆疊，用於 Telegram 直接訊息、Discord 群組與 Heartbeat 回合。 +該堆疊包含從 Codex 模型目錄/快取形狀產生的固定 Codex `gpt-5.5` +模型提示詞 fixture、Codex 快樂路徑權限 developer 文字、 +OpenClaw developer 指示、OpenClaw 提供時的回合範圍協作模式指示、 +使用者回合輸入，以及動態工具規格的參照。 -使用 `pnpm prompt:snapshots:sync-codex-model` 重新整理已釘選的 Codex 模型提示 fixture。預設情況下，該 script 會先尋找 -Codex 在 `$CODEX_HOME/models_cache.json` 的執行階段快取，接著是 -`~/.codex/models_cache.json`，最後才退回維護者 Codex checkout 慣例路徑 -`~/code/codex/codex-rs/models-manager/models.json`。如果這些來源都不存在， -命令會在不變更已提交 fixture 的情況下結束。傳入 `--catalog ` 可從 -特定 `models_cache.json` 或 `models.json` 檔案重新整理。 +使用 `pnpm prompt:snapshots:sync-codex-model` 重新整理固定的 Codex +模型提示詞 fixture。預設情況下，腳本會先尋找 Codex 在 +`$CODEX_HOME/models_cache.json` 的執行階段快取，接著是 +`~/.codex/models_cache.json`，最後才回退到 maintainer Codex +checkout 慣例路徑 `~/code/codex/codex-rs/models-manager/models.json`。 +如果這些來源都不存在，命令會結束而不變更已提交的 fixture。 +傳入 `--catalog ` 可從特定 `models_cache.json` 或 `models.json` +檔案重新整理。 -這些快照仍不是逐位元組的原始 OpenAI 請求擷取。在 OpenClaw 傳送 -thread 和 turn 參數後，Codex 可以在 Codex 執行階段中加入執行階段擁有的 -工作區情境，例如 `AGENTS.md`、環境情境、記憶、app/plugin 指示，以及 -內建的預設協作模式指示。 +這些快照仍不是逐位元組的原始 OpenAI 請求擷取。OpenClaw 傳送 +thread 與 turn 參數後，Codex 可以在 Codex 執行階段內加入 +執行階段擁有的工作區脈絡，例如 `AGENTS.md`、環境脈絡、記憶、 +app/Plugin 指示，以及內建 Default 協作模式指示。 使用 `pnpm prompt:snapshots:gen` 重新產生它們，並使用 -`pnpm prompt:snapshots:check` 驗證漂移。CI 會在額外邊界 shard 中執行 -漂移檢查，讓提示變更和快照更新保持附著在同一個 PR。 +`pnpm prompt:snapshots:check` 驗證漂移。CI 會在額外邊界 shard 中 +執行漂移檢查，讓提示詞變更與快照更新保持附著在同一個 PR。 ## 工作區啟動注入 -啟動檔案會經過修剪並附加在 **專案情境** 下，讓模型無需明確讀取即可看到身分和設定檔情境： +啟動檔案會被修剪並附加在**專案脈絡**下方，讓模型不需要明確讀取就能看到身分與設定檔脈絡： - `AGENTS.md` - `SOUL.md` @@ -151,66 +155,73 @@ thread 和 turn 參數後，Codex 可以在 Codex 執行階段中加入執行階 - `MEMORY.md`（存在時） 除非套用檔案特定閘門，否則所有這些檔案都會在每個回合中 -**注入情境視窗**。在一般執行中，當預設代理停用 heartbeats 或 +**注入脈絡視窗**。當預設代理停用 Heartbeat，或 `agents.defaults.heartbeat.includeSystemPromptSection` 為 false 時， -會省略 `HEARTBEAT.md`。請保持注入檔案精簡，尤其是 `MEMORY.md`， -它可能隨時間成長，導致非預期的高情境用量與更頻繁的 Compaction。 +一般執行會省略 `HEARTBEAT.md`。保持注入檔案精簡， +尤其是可能隨時間成長並導致非預期高脈絡使用量與更頻繁 Compaction 的 +`MEMORY.md`。 -當工作階段在原生 Codex harness 上執行時，Codex 會透過自己的專案文件探索載入 `AGENTS.md`。OpenClaw 仍會解析其餘啟動檔案，並將它們作為 Codex 設定指示轉送，因此 `SOUL.md`、 -`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` 和 -`MEMORY.md` 會維持相同的工作區情境角色，而不重複 `AGENTS.md`。 +當工作階段在原生 Codex harness 上執行時，Codex 會透過自己的 +專案文件探索載入 `AGENTS.md`。OpenClaw 仍會解析其餘啟動檔案， +並將它們作為 Codex 設定指示轉送，因此 `SOUL.md`、 +`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` +與 `MEMORY.md` 會維持相同的工作區脈絡角色，而不重複 +`AGENTS.md`。 -`memory/*.md` 每日檔案**不是**一般啟動專案情境的一部分。在一般回合中，它們會依需求透過 `memory_search` 和 `memory_get` 工具存取，因此除非模型明確讀取它們，否則不會佔用情境視窗。裸 `/new` 和 `/reset` 回合是例外：執行階段可為第一個回合前置最近的每日記憶，作為一次性啟動情境區塊。 +`memory/*.md` 每日檔案**不是**一般啟動專案脈絡的一部分。在普通回合中，它們會透過 `memory_search` 與 `memory_get` 工具按需存取，因此除非模型明確讀取它們，否則不會計入脈絡視窗。裸 `/new` 與 `/reset` 回合是例外：執行階段可以為第一個回合預先加入近期每日記憶，作為一次性的啟動脈絡區塊。 大型檔案會以標記截斷。每個檔案的最大大小由 -`agents.defaults.bootstrapMaxChars` 控制（預設：12000）。跨檔案注入的啟動 -內容總量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制 +`agents.defaults.bootstrapMaxChars` 控制（預設：12000）。跨檔案注入的 +啟動內容總量由 `agents.defaults.bootstrapTotalMaxChars` 限制 （預設：60000）。缺少的檔案會注入簡短的缺檔標記。發生截斷時， -OpenClaw 可在專案情境中注入警告區塊；使用 -`agents.defaults.bootstrapPromptTruncationWarning` 控制此行為（`off`、`once`、`always`； -預設：`once`）。 +OpenClaw 可以注入精簡的系統提示詞警告通知；使用 +`agents.defaults.bootstrapPromptTruncationWarning` 控制此行為 +（`off`、`once`、`always`；預設：`once`）。詳細的原始/注入計數會保留在 +`/context`、`/status`、doctor 與日誌等診斷中。 -子代理工作階段只會注入 `AGENTS.md` 和 `TOOLS.md`（其他啟動檔案會被過濾掉，以保持子代理情境精簡）。 +子代理工作階段只會注入 `AGENTS.md` 與 `TOOLS.md`（其他啟動檔案 +會被過濾掉，以保持子代理脈絡精簡）。 內部 hook 可以透過 `agent:bootstrap` 攔截此步驟，以變更或取代 -已注入的啟動檔案（例如將 `SOUL.md` 換成替代 persona）。 +注入的啟動檔案（例如將 `SOUL.md` 換成替代人設）。 -如果你想讓代理聽起來不那麼制式，請從 -[SOUL.md 個性指南](/zh-TW/concepts/soul) 開始。 +如果你想讓代理聽起來不那麼通用，請從 +[SOUL.md 人格指南](/zh-TW/concepts/soul)開始。 -若要檢查每個注入檔案貢獻了多少內容（原始與注入、截斷，加上工具 schema 開銷），請使用 `/context list` 或 `/context detail`。請參閱[情境](/zh-TW/concepts/context)。 +若要檢查每個注入檔案貢獻多少內容（原始與注入、截斷，加上工具 schema 額外負擔），請使用 `/context list` 或 `/context detail`。請參閱[脈絡](/zh-TW/concepts/context)。 ## 時間處理 -當使用者時區已知時，系統提示會包含專用的 **目前日期與時間** 區段。 -為了讓提示快取保持穩定，現在它只包含 **時區**（沒有動態時鐘或時間格式）。 +當使用者時區已知時，系統提示詞會包含專用的**目前日期與時間**區段。 +為了保持提示詞快取穩定，現在只包含**時區**（不包含動態時鐘或時間格式）。 -當代理需要目前時間時，請使用 `session_status`；狀態卡片包含時間戳行。 +當代理需要目前時間時，請使用 `session_status`；狀態卡片包含時間戳記行。 同一工具也可以選擇性設定每個工作階段的模型覆寫 （`model=default` 會清除它）。 -設定項目： +使用以下項目設定： - `agents.defaults.userTimezone` -- `agents.defaults.timeFormat` (`auto` | `12` | `24`) +- `agents.defaults.timeFormat`（`auto` | `12` | `24`） 完整行為細節請參閱[日期與時間](/zh-TW/date-time)。 ## Skills -當存在符合資格的 skills 時，OpenClaw 會注入精簡的 **可用 skills 清單** -（`formatSkillsForPrompt`），其中包含每個 skill 的 **檔案路徑**。提示會指示 -模型使用 `read` 載入列出位置（工作區、受管理或內建）的 SKILL.md。 -如果沒有符合資格的 skills，會省略 Skills 區段。 +當存在符合資格的 Skills 時，OpenClaw 會注入精簡的**可用 Skills 清單** +（`formatSkillsForPrompt`），其中包含每個 Skills 的**檔案路徑**。 +提示詞會指示模型使用 `read` 載入所列位置（工作區、受管理或內建）的 +SKILL.md。如果沒有符合資格的 Skills，會省略 Skills 區段。 -資格包含 skill metadata 閘門、執行階段環境/設定檢查，以及當 -`agents.defaults.skills` 或 `agents.list[].skills` 已設定時生效的 -代理 skill 允許清單。 +資格包含 Skills metadata 閘門、執行階段環境/設定檢查， +以及設定 `agents.defaults.skills` 或 `agents.list[].skills` 時的 +有效代理 Skills 允許清單。 -Plugin 內建 skills 只有在其所屬 Plugin 啟用時才符合資格。這讓工具 Plugin -可以公開更深入的操作指南，而不必將所有指引直接嵌入每個工具描述中。 +Plugin 內建 Skills 只有在其擁有的 Plugin 啟用時才符合資格。 +這讓工具 Plugin 能公開更深入的操作指南，而不需要將所有指引 +直接嵌入每個工具描述中。 ``` @@ -222,25 +233,27 @@ Plugin 內建 skills 只有在其所屬 Plugin 啟用時才符合資格。這讓 ``` -這能讓基礎提示保持精簡，同時仍啟用目標式 skill 使用。 +這會讓基礎提示詞保持精簡，同時仍能啟用針對性的 Skills 使用。 -skills 清單預算由 skills 子系統擁有： +Skills 清單預算由 Skills 子系統擁有： - 全域預設值：`skills.limits.maxSkillsPromptChars` -- 每個代理覆寫：`agents.list[].skillsLimits.maxSkillsPromptChars` +- 每個代理程式覆寫：`agents.list[].skillsLimits.maxSkillsPromptChars` -一般有界執行階段摘錄使用不同介面： +通用的有界限執行階段摘錄使用不同的介面： - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -這種分離會將 Skills 大小設定，與執行階段讀取/注入大小設定區分開來，例如 `memory_get`、即時工具結果，以及 Compaction 後的 AGENTS.md 重新整理。 +這項區分會將 Skills 大小設定，與執行階段讀取/注入大小設定分開，例如 `memory_get`、即時工具結果，以及 Compaction 後的 AGENTS.md 重新整理。 ## 文件 -系統提示包含 **文件** 區段。當本機文件可用時，這會指向本機 OpenClaw 文件目錄（Git checkout 中的 `docs/` 或隨附 npm 套件文件）。如果本機文件無法使用，則會退回至 [https://docs.openclaw.ai](https://docs.openclaw.ai)。 +系統提示包含一個 **文件** 區段。當本機文件可用時，它會指向本機 OpenClaw 文件目錄（Git checkout 中的 `docs/`，或隨附 npm 套件文件）。如果本機文件不可用，則會退回至 +[https://docs.openclaw.ai](https://docs.openclaw.ai)。 -同一區段也包含 OpenClaw 原始碼位置。Git checkout 會公開本機原始碼根目錄，讓代理程式可以直接檢查程式碼。套件安裝包含 GitHub 原始碼 URL，並告知代理程式在文件不完整或過期時前往該處檢閱原始碼。提示也會註明公開文件鏡像、社群 Discord，以及用於探索 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。它會告訴模型，針對 OpenClaw 行為、命令、設定或架構，應先查閱文件，並在可行時自行執行 `openclaw status`（只有在缺少存取權時才詢問使用者）。特別是針對設定，它會指引代理程式使用 `gateway` 工具動作 `config.schema.lookup`，取得精確的欄位層級文件與限制，接著再參考 `docs/gateway/configuration.md` 和 `docs/gateway/configuration-reference.md` 以取得更廣泛的指引。 +同一區段也包含 OpenClaw 原始碼位置。Git checkout 會公開本機原始碼根目錄，讓代理程式可以直接檢查程式碼。套件安裝會包含 GitHub 原始碼 URL，並告訴代理程式在文件不完整或過期時到該處檢閱原始碼。提示也會提及公開文件鏡像、社群 Discord，以及用於探索 Skills 的 ClawHub +([https://clawhub.ai](https://clawhub.ai))。它會告訴模型，針對 OpenClaw 行為、命令、設定或架構，應先查閱文件，並在可能時自行執行 `openclaw status`（只有在缺乏存取權時才詢問使用者）。針對設定，它會特別指示代理程式先使用 `gateway` 工具動作 `config.schema.lookup` 取得精確的欄位層級文件與限制，然後再參閱 `docs/gateway/configuration.md` 和 `docs/gateway/configuration-reference.md` 取得更廣泛的指引。 ## 相關 diff --git a/docs/zh-TW/gateway/config-agents.md b/docs/zh-TW/gateway/config-agents.md index 3844a7a15..942da5e7d 100644 --- a/docs/zh-TW/gateway/config-agents.md +++ b/docs/zh-TW/gateway/config-agents.md @@ -1,24 +1,24 @@ --- read_when: - 調整代理預設值（模型、思考、工作區、Heartbeat、媒體、Skills） - - 設定多代理路由與綁定 + - 設定多代理路由與繫結 - 調整工作階段、訊息傳遞與對話模式行為 -summary: 代理預設值、多代理路由、工作階段、訊息和對話設定 +summary: 代理預設值、多代理路由、工作階段、訊息與對話設定 title: 設定 — 代理程式 x-i18n: - generated_at: "2026-05-03T21:32:01Z" + generated_at: "2026-05-04T02:44:27Z" model: gpt-5.5 provider: openai - source_hash: b25371c34b9f8b0cacce021879e43e6a65b86d626dc87d5bfa05dcae80ac32e4 + source_hash: 9d339b82b8b3b82e55820ca6568b3ed569fe64135e698515fa7f316c3afbbfd9 source_path: gateway/config-agents.md workflow: 16 --- -代理程式範圍的設定鍵位於 `agents.*`、`multiAgent.*`、`session.*`、 -`messages.*` 和 `talk.*` 之下。關於通道、工具、Gateway 執行階段，以及其他 +Agent 作用域的設定鍵位於 `agents.*`、`multiAgent.*`、`session.*`、 +`messages.*` 和 `talk.*` 下。關於通道、工具、Gateway 執行階段，以及其他 頂層鍵，請參閱[設定參考](/zh-TW/gateway/configuration-reference)。 -## 代理程式預設值 +## Agent 預設值 ### `agents.defaults.workspace` @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -選用的儲存庫根目錄，會顯示在系統提示詞的 Runtime 行中。若未設定，OpenClaw 會從工作區往上自動偵測。 +選用的儲存庫根目錄，會顯示在系統提示的執行階段行中。如果未設定，OpenClaw 會從工作區往上自動偵測。 ```json5 { @@ -42,8 +42,8 @@ x-i18n: ### `agents.defaults.skills` -選用的代理程式預設 Skills 允許清單，適用於未設定 -`agents.list[].skills` 的代理程式。 +選用的預設 Skills 允許清單，適用於未設定 +`agents.list[].skills` 的 agent。 ```json5 { @@ -58,15 +58,15 @@ x-i18n: } ``` -- 省略 `agents.defaults.skills` 時，預設不限制 Skills。 -- 省略 `agents.list[].skills` 時，會繼承預設值。 -- 將 `agents.list[].skills: []` 設為沒有 Skills。 -- 非空的 `agents.list[].skills` 清單就是該代理程式的最終集合；它 +- 省略 `agents.defaults.skills`，即可預設不限制 Skills。 +- 省略 `agents.list[].skills`，即可繼承預設值。 +- 設定 `agents.list[].skills: []`，即可不使用 Skills。 +- 非空的 `agents.list[].skills` 清單就是該 agent 的最終集合； 不會與預設值合併。 ### `agents.defaults.skipBootstrap` -停用自動建立工作區啟動程序檔案（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +停用自動建立工作區啟動檔案（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -76,7 +76,7 @@ x-i18n: ### `agents.defaults.skipOptionalBootstrapFiles` -略過建立選定的選用工作區檔案，同時仍會寫入必要的啟動程序檔案。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。 +在仍寫入必要啟動檔案的同時，略過建立選定的選用工作區檔案。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。 ```json5 { @@ -90,10 +90,10 @@ x-i18n: ### `agents.defaults.contextInjection` -控制工作區啟動程序檔案何時注入系統提示詞。預設值：`"always"`。 +控制工作區啟動檔案何時注入系統提示。預設值：`"always"`。 -- `"continuation-skip"`：安全的延續回合（在已完成的助理回應之後）會略過重新注入工作區啟動程序，降低提示詞大小。Heartbeat 執行與 Compaction 後重試仍會重建脈絡。 -- `"never"`：在每個回合停用工作區啟動程序與脈絡檔案注入。僅應用於完全自行管理提示詞生命週期的代理程式（自訂脈絡引擎、建置自身脈絡的原生執行階段，或不需要啟動程序的特殊工作流程）。Heartbeat 與 Compaction 復原回合也會略過注入。 +- `"continuation-skip"`：安全的延續回合（在已完成的助理回應之後）會略過重新注入工作區啟動內容，以減少提示大小。Heartbeat 執行和 Compaction 後重試仍會重建上下文。 +- `"never"`：在每個回合停用工作區啟動與上下文檔案注入。僅對完全自行掌控提示生命週期的 agent 使用此選項（自訂上下文引擎、建立自身上下文的原生執行階段，或不需要專用啟動流程的工作流程）。Heartbeat 和 Compaction 復原回合也會略過注入。 ```json5 { @@ -103,7 +103,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每個工作區啟動程序檔案在截斷前的最大字元數。預設值：`12000`。 +截斷前每個工作區啟動檔案的字元上限。預設值：`12000`。 ```json5 { @@ -113,7 +113,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -所有工作區啟動程序檔案合計注入的最大總字元數。預設值：`60000`。 +跨所有工作區啟動檔案注入的總字元上限。預設值：`60000`。 ```json5 { @@ -123,12 +123,16 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制啟動程序脈絡遭截斷時，代理程式可見的警告文字。 +控制啟動上下文被截斷時，agent 可見的系統提示通知。 預設值：`"once"`。 -- `"off"`：永不將警告文字注入系統提示詞。 -- `"once"`：每個唯一截斷簽章只注入一次警告（建議）。 -- `"always"`：存在截斷時，每次執行都注入警告。 +- `"off"`：永不將截斷通知文字注入系統提示。 +- `"once"`：每個唯一截斷簽章只注入一次簡潔通知（建議）。 +- `"always"`：只要存在截斷，每次執行都注入簡潔通知。 + +詳細的原始/注入計數與設定調校欄位會保留在診斷資料中， +例如上下文/狀態報告和記錄；例行 WebChat 使用者/執行階段上下文只會 +取得簡潔的復原通知。 ```json5 { @@ -136,35 +140,35 @@ x-i18n: } ``` -### 脈絡預算所有權對照表 +### 上下文預算歸屬對照表 -OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分離， +OpenClaw 有多個高容量提示/上下文預算，且刻意依子系統拆分， 而不是全部流經同一個通用旋鈕。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 一般工作區啟動程序注入。 + 一般工作區啟動注入。 - `agents.defaults.startupContext.*`： - 一次性的重設／啟動模型執行前置內容，包含近期每日 - `memory/*.md` 檔案。單純聊天 `/new` 與 `/reset` 命令會 - 確認重設，而不叫用模型。 + 一次性的重設/啟動模型執行前置內容，包括最近的每日 + `memory/*.md` 檔案。單獨的聊天 `/new` 和 `/reset` 命令會 + 在不叫用模型的情況下確認重設。 - `skills.limits.*`： - 注入系統提示詞的精簡 Skills 清單。 + 注入系統提示的精簡 Skills 清單。 - `agents.defaults.contextLimits.*`： - 有界限的執行階段摘錄，以及注入的執行階段所擁有區塊。 + 有界的執行階段摘錄和注入的執行階段所屬區塊。 - `memory.qmd.limits.*`： - 索引記憶體搜尋片段與注入大小設定。 + 已索引記憶體搜尋片段與注入大小。 -只有在某個代理程式需要不同預算時，才使用對應的每代理程式覆寫： +只有在某個 agent 需要不同預算時，才使用相符的每 agent 覆寫： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制重設／啟動模型執行時，第一回合注入的啟動前置內容。 -單純聊天 `/new` 與 `/reset` 命令會確認重設，而不叫用 -模型，因此不會載入此前置內容。 +控制在重設/啟動模型執行時注入的第一回合啟動前置內容。 +單獨的聊天 `/new` 和 `/reset` 命令會在不叫用模型的情況下確認重設， +因此不會載入此前置內容。 ```json5 { @@ -185,7 +189,7 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分 #### `agents.defaults.contextLimits` -有界限執行階段脈絡介面的共用預設值。 +有界執行階段上下文表面的共用預設值。 ```json5 { @@ -202,15 +206,17 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分 } ``` -- `memoryGetMaxChars`：在加入截斷中繼資料與延續通知前，預設的 `memory_get` 摘錄上限。 -- `memoryGetDefaultLines`：省略 `lines` 時，預設的 `memory_get` 行視窗。 -- `toolResultMaxChars`：即時工具結果上限，用於持久化結果與溢位復原。 +- `memoryGetMaxChars`：加入截斷中繼資料和延續通知前， + 預設的 `memory_get` 摘錄上限。 +- `memoryGetDefaultLines`：省略 `lines` 時， + 預設的 `memory_get` 行視窗。 +- `toolResultMaxChars`：用於持久化結果和溢位復原的即時工具結果上限。 - `postCompactionMaxChars`：Compaction 後重新整理注入期間使用的 AGENTS.md 摘錄上限。 #### `agents.list[].contextLimits` -共用 `contextLimits` 旋鈕的每代理程式覆寫。省略的欄位會繼承 -自 `agents.defaults.contextLimits`。 +共用 `contextLimits` 旋鈕的每 agent 覆寫。省略的欄位會繼承自 +`agents.defaults.contextLimits`。 ```json5 { @@ -236,7 +242,7 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分 #### `skills.limits.maxSkillsPromptChars` -注入系統提示詞的精簡 Skills 清單全域上限。這 +注入系統提示的精簡 Skills 清單全域上限。這 不會影響依需求讀取 `SKILL.md` 檔案。 ```json5 @@ -251,7 +257,7 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示詞預算的每代理程式覆寫。 +Skills 提示預算的每 agent 覆寫。 ```json5 { @@ -270,11 +276,11 @@ Skills 提示詞預算的每代理程式覆寫。 ### `agents.defaults.imageMaxDimensionPx` -在呼叫供應商前，逐字稿／工具圖片區塊中圖片最長邊的最大像素尺寸。 +提供者呼叫前，逐字稿/工具影像區塊中最長影像邊的像素上限。 預設值：`1200`。 -較低的值通常可降低大量截圖執行時的視覺權杖用量與請求承載大小。 -較高的值可保留更多視覺細節。 +較低的值通常會降低大量截圖執行的視覺權杖用量和請求酬載大小。 +較高的值會保留更多視覺細節。 ```json5 { @@ -284,7 +290,7 @@ Skills 提示詞預算的每代理程式覆寫。 ### `agents.defaults.userTimezone` -系統提示詞脈絡的時區（不是訊息時間戳記）。會退回使用主機時區。 +系統提示上下文的時區（不是訊息時間戳記）。會回退到主機時區。 ```json5 { @@ -294,7 +300,7 @@ Skills 提示詞預算的每代理程式覆寫。 ### `agents.defaults.timeFormat` -系統提示詞中的時間格式。預設值：`auto`（作業系統偏好）。 +系統提示中的時間格式。預設值：`auto`（作業系統偏好設定）。 ```json5 { @@ -340,6 +346,7 @@ Skills 提示詞預算的每代理程式覆寫。 pdfMaxPages: 20, thinkingDefault: "low", verboseDefault: "off", + toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", timeoutSeconds: 600, @@ -352,58 +359,59 @@ Skills 提示詞預算的每代理程式覆寫。 ``` - `model`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。 - - 字串形式只會設定主要模型。 - - 物件形式會設定主要模型加上有序容錯移轉模型。 + - 字串形式只設定主要模型。 + - 物件形式會設定主要模型加上有序的容錯移轉模型。 - `imageModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。 - - 由 `image` 工具路徑作為其視覺模型設定使用。 - - 也會在所選/預設模型無法接受影像輸入時，作為備援路由使用。 - - 建議使用明確的 `provider/model` 參照。為了相容性，裸 ID 仍會被接受；如果裸 ID 唯一符合 `models.providers.*.models` 中已設定且具備影像能力的項目，OpenClaw 會將其限定到該供應商。已設定的符合項目若有歧義，則需要明確的供應商前綴。 + - 由 `image` 工具路徑用作其視覺模型設定。 + - 當選取的／預設模型無法接受影像輸入時，也用作備援路由。 + - 建議使用明確的 `provider/model` 參照。為了相容性也接受裸 ID；如果裸 ID 唯一符合 `models.providers.*.models` 中已設定且支援影像的項目，OpenClaw 會將其限定到該供應商。已設定的符合項目若不明確，則需要明確的供應商前綴。 - `imageGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。 - - 由共用影像生成能力，以及任何未來會生成影像的工具/Plugin 介面使用。 - - 常見值：原生 Gemini 影像生成使用 `google/gemini-3.1-flash-image-preview`，fal 使用 `fal/fal-ai/flux/dev`，OpenAI Images 使用 `openai/gpt-image-2`，或透明背景 OpenAI PNG/WebP 輸出使用 `openai/gpt-image-1.5`。 - - 如果你直接選取供應商/模型，也要設定相符的供應商驗證（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，然後依供應商 ID 順序嘗試其餘已註冊的影像生成供應商。 + - 由共用的影像產生能力，以及任何未來會產生影像的工具／Plugin 表面使用。 + - 常見值：原生 Gemini 影像產生使用 `google/gemini-3.1-flash-image-preview`，fal 使用 `fal/fal-ai/flux/dev`，OpenAI Images 使用 `openai/gpt-image-2`，或透明背景 OpenAI PNG/WebP 輸出使用 `openai/gpt-image-1.5`。 + - 如果你直接選取供應商／模型，也要設定相符的供應商驗證（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著依供應商 ID 順序嘗試其餘已註冊的影像產生供應商。 - `musicGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。 - - 由共用音樂生成能力和內建 `music_generate` 工具使用。 - - 常見值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。 - - 如果省略，`music_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，然後依供應商 ID 順序嘗試其餘已註冊的音樂生成供應商。 - - 如果你直接選取供應商/模型，也要設定相符的供應商驗證/API 金鑰。 + - 由共用的音樂產生能力與內建的 `music_generate` 工具使用。 + - 常見值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`，或 `minimax/music-2.6`。 + - 如果省略，`music_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著依供應商 ID 順序嘗試其餘已註冊的音樂產生供應商。 + - 如果你直接選取供應商／模型，也要設定相符的供應商驗證／API 金鑰。 - `videoGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。 - - 由共用影片生成能力和內建 `video_generate` 工具使用。 - - 常見值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，然後依供應商 ID 順序嘗試其餘已註冊的影片生成供應商。 - - 如果你直接選取供應商/模型，也要設定相符的供應商驗證/API 金鑰。 - - 內建 Qwen 影片生成供應商最多支援 1 個輸出影片、1 張輸入影像、4 個輸入影片、10 秒長度，以及供應商層級的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 選項。 + - 由共用的影片產生能力與內建的 `video_generate` 工具使用。 + - 常見值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`，或 `qwen/wan2.7-r2v`。 + - 如果省略，`video_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著依供應商 ID 順序嘗試其餘已註冊的影片產生供應商。 + - 如果你直接選取供應商／模型，也要設定相符的供應商驗證／API 金鑰。 + - 隨附的 Qwen 影片產生供應商支援最多 1 個輸出影片、1 張輸入影像、4 個輸入影片、10 秒時長，以及供應商層級的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 選項。 - `pdfModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。 - 由 `pdf` 工具用於模型路由。 - - 如果省略，PDF 工具會退回使用 `imageModel`，再退回使用已解析的工作階段/預設模型。 -- `pdfMaxBytesMb`：當呼叫時未傳入 `maxBytesMb` 時，`pdf` 工具的預設 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具中擷取備援模式會考量的預設最大頁數。 + - 如果省略，PDF 工具會備援到 `imageModel`，再備援到解析後的工作階段／預設模型。 +- `pdfMaxBytesMb`：在呼叫時未傳入 `maxBytesMb` 時，`pdf` 工具的預設 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具中擷取備援模式會考慮的預設頁數上限。 - `verboseDefault`：代理程式的預設詳細程度。值：`"off"`、`"on"`、`"full"`。預設：`"off"`。 -- `reasoningDefault`：代理程式的預設推理可見性。值：`"off"`、`"on"`、`"stream"`。每個代理程式的 `agents.list[].reasoningDefault` 會覆寫此預設值。已設定的推理預設值只會在沒有設定每則訊息或工作階段推理覆寫時，套用於擁有者、已授權寄件者，或 operator-admin gateway 情境。 +- `toolProgressDetail`：`/verbose` 工具摘要與進度草稿工具列的詳細模式。值：`"explain"`（預設，精簡的人類可讀標籤）或 `"raw"`（可用時附加原始命令／詳細資訊）。每個代理程式的 `agents.list[].toolProgressDetail` 會覆寫此預設值。 +- `reasoningDefault`：代理程式的預設推理可見性。值：`"off"`、`"on"`、`"stream"`。每個代理程式的 `agents.list[].reasoningDefault` 會覆寫此預設值。已設定的推理預設值只會在沒有設定每則訊息或工作階段推理覆寫時，套用於擁有者、授權傳送者，或操作者管理員 Gateway 情境。 - `elevatedDefault`：代理程式的預設提升輸出層級。值：`"off"`、`"on"`、`"ask"`、`"full"`。預設：`"on"`。 -- `model.primary`：格式為 `provider/model`（例如 API 金鑰存取使用 `openai/gpt-5.5`，或 Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略供應商，OpenClaw 會先嘗試別名，再嘗試該確切模型 ID 的唯一已設定供應商符合項目，最後才退回已設定的預設供應商（已棄用的相容性行為，因此建議使用明確的 `provider/model`）。如果該供應商不再公開已設定的預設模型，OpenClaw 會退回使用第一個已設定的供應商/模型，而不是顯示過時且已移除供應商的預設值。 -- `models`：已設定的模型目錄，以及 `/model` 的允許清單。每個項目可包含 `alias`（捷徑）和 `params`（供應商專屬，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。 - - 安全編輯：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 新增項目。除非你傳入 `--replace`，否則 `config set` 會拒絕移除既有允許清單項目的替換。 - - 供應商範圍的設定/入門流程會將所選供應商模型合併到此對應表，並保留已設定的其他無關供應商。 - - 對於直接的 OpenAI Responses 模型，會自動啟用伺服器端 Compaction。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆寫閾值。請參閱 [OpenAI 伺服器端 Compaction](/zh-TW/providers/openai#server-side-compaction-responses-api)。 -- `params`：套用到所有模型的全域預設供應商參數。設定於 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合併優先順序（設定）：`agents.defaults.params`（全域基底）會被 `agents.defaults.models["provider/model"].params`（每模型）覆寫，然後 `agents.list[].params`（相符代理程式 ID）會依鍵覆寫。詳情請參閱 [Prompt Caching](/zh-TW/reference/prompt-caching)。 -- `params.extra_body`/`params.extraBody`：進階透傳 JSON，會合併到 OpenAI 相容代理的 `api: "openai-completions"` 請求主體。如果它與生成的請求鍵衝突，額外主體會勝出；非原生 completions 路由之後仍會移除僅限 OpenAI 的 `store`。 -- `params.chat_template_kwargs`：vLLM/OpenAI 相容的聊天範本參數，會合併到頂層 `api: "openai-completions"` 請求主體。對於關閉 thinking 的 `vllm/nemotron-3-*`，內建 vLLM Plugin 會自動傳送 `enable_thinking: false` 和 `force_nonempty_content: true`；明確的 `chat_template_kwargs` 會覆寫生成的預設值，而 `extra_body.chat_template_kwargs` 仍具有最終優先權。對於 vLLM Qwen thinking 控制，請在該模型項目上將 `params.qwenThinkingFormat` 設為 `"chat-template"` 或 `"top-level"`。 -- `compat.supportedReasoningEfforts`：每模型的 OpenAI 相容推理強度清單。對真正接受它的自訂端點加入 `"xhigh"`；OpenClaw 接著會在指令選單、Gateway 工作階段列、工作階段修補驗證、代理程式 CLI 驗證，以及該已設定供應商/模型的 `llm-task` 驗證中公開 `/think xhigh`。當後端需要規範層級的供應商專屬值時，請使用 `compat.reasoningEffortMap`。 -- `params.preserveThinking`：僅限 Z.AI 的保留 thinking 選用功能。啟用且 thinking 開啟時，OpenClaw 會傳送 `thinking.clear_thinking: false` 並重播先前的 `reasoning_content`；請參閱 [Z.AI thinking 與保留 thinking](/zh-TW/providers/zai#thinking-and-preserved-thinking)。 -- `agentRuntime`：預設低階代理程式執行階段政策。省略 id 時預設為 OpenClaw Pi。使用 `id: "pi"` 強制使用內建 PI harness，使用 `id: "auto"` 讓已註冊的 Plugin harness 宣告支援的模型，且在沒有符合項目時使用 PI，使用已註冊的 harness id（例如 `id: "codex"`）要求該 harness，或使用受支援的 CLI 後端別名（例如 `id: "claude-cli"`）。明確的 Plugin 執行階段會在 harness 不可用或失敗時關閉失敗。請將模型參照維持為規範的 `provider/model`；請透過執行階段設定選取 Codex、Claude CLI、Gemini CLI 和其他執行後端，而不是使用舊版執行階段供應商前綴。這與供應商/模型選取的差異，請參閱 [Agent runtimes](/zh-TW/concepts/agent-runtimes)。 -- 會變更這些欄位的設定寫入器（例如 `/models set`、`/models set-image` 和備援新增/移除指令）會儲存規範物件形式，並盡可能保留既有備援清單。 -- `maxConcurrent`：跨工作階段的最大平行代理程式執行數（每個工作階段仍會序列化）。預設：4。 +- `model.primary`：格式為 `provider/model`（例如 API 金鑰存取使用 `openai/gpt-5.5`，Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略供應商，OpenClaw 會先嘗試別名，接著對該精確模型 ID 嘗試唯一的已設定供應商符合項，最後才備援到已設定的預設供應商（已淘汰的相容性行為，因此建議使用明確的 `provider/model`）。如果該供應商不再公開已設定的預設模型，OpenClaw 會備援到第一個已設定的供應商／模型，而不是顯示過時且已移除的供應商預設值。 +- `models`：為 `/model` 設定的模型目錄與允許清單。每個項目可包含 `alias`（捷徑）和 `params`（供應商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。 + - 安全編輯：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 新增項目。除非你傳入 `--replace`，否則 `config set` 會拒絕移除現有允許清單項目的替換。 + - 供應商範圍的設定／上線流程會將所選供應商模型合併到此對應表，並保留已設定的無關供應商。 + - 對於直接的 OpenAI Responses 模型，伺服器端 Compaction 會自動啟用。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆寫閾值。請參閱 [OpenAI 伺服器端 Compaction](/zh-TW/providers/openai#server-side-compaction-responses-api)。 +- `params`：套用至所有模型的全域預設供應商參數。設定於 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合併優先順序（設定）：`agents.defaults.params`（全域基底）會由 `agents.defaults.models["provider/model"].params`（每個模型）覆寫，接著 `agents.list[].params`（符合的代理程式 ID）會依鍵覆寫。詳情請參閱 [提示快取](/zh-TW/reference/prompt-caching)。 +- `params.extra_body`/`params.extraBody`：進階傳遞 JSON，會合併到 OpenAI 相容代理的 `api: "openai-completions"` 請求主體中。如果它與產生的請求鍵衝突，額外主體會優先；非原生 completions 路由之後仍會移除僅 OpenAI 使用的 `store`。 +- `params.chat_template_kwargs`：vLLM/OpenAI 相容的聊天範本引數，會合併到頂層 `api: "openai-completions"` 請求主體。對於關閉思考的 `vllm/nemotron-3-*`，隨附的 vLLM Plugin 會自動傳送 `enable_thinking: false` 和 `force_nonempty_content: true`；明確的 `chat_template_kwargs` 會覆寫產生的預設值，而 `extra_body.chat_template_kwargs` 仍具有最終優先權。對於 vLLM Qwen 思考控制，請在該模型項目將 `params.qwenThinkingFormat` 設為 `"chat-template"` 或 `"top-level"`。 +- `compat.supportedReasoningEfforts`：每個模型的 OpenAI 相容推理努力程度清單。對於真正接受 `"xhigh"` 的自訂端點，請包含 `"xhigh"`；OpenClaw 接著會在命令選單、Gateway 工作階段列、工作階段修補驗證、代理程式 CLI 驗證，以及該已設定供應商／模型的 `llm-task` 驗證中公開 `/think xhigh`。當後端需要某個標準層級的供應商特定值時，請使用 `compat.reasoningEffortMap`。 +- `params.preserveThinking`：僅 Z.AI 適用的保留思考選擇加入。啟用且思考開啟時，OpenClaw 會傳送 `thinking.clear_thinking: false` 並重播先前的 `reasoning_content`；請參閱 [Z.AI 思考與保留思考](/zh-TW/providers/zai#thinking-and-preserved-thinking)。 +- `agentRuntime`：預設低階代理程式執行階段政策。省略的 ID 預設為 OpenClaw Pi。使用 `id: "pi"` 強制使用內建 PI harness，使用 `id: "auto"` 讓已註冊的 Plugin harness 認領支援的模型，且在沒有符合項時使用 PI，使用已註冊的 harness ID（例如 `id: "codex"`）要求該 harness，或使用支援的 CLI 後端別名（例如 `id: "claude-cli"`）。明確的 Plugin 執行階段會在 harness 不可用或失敗時封閉失敗。模型參照請保持 `provider/model` 的標準形式；透過執行階段設定選取 Codex、Claude CLI、Gemini CLI 和其他執行後端，而不是使用舊版執行階段供應商前綴。關於這與供應商／模型選擇有何不同，請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)。 +- 會改動這些欄位的設定寫入器（例如 `/models set`、`/models set-image`，以及備援新增／移除命令）會儲存標準物件形式，並在可能時保留既有備援清單。 +- `maxConcurrent`：跨工作階段的最大並行代理程式執行數（每個工作階段仍會序列化）。預設：4。 ### `agents.defaults.agentRuntime` -`agentRuntime` 控制哪個低階執行器執行代理程式回合。大多數 -部署應保留預設的 OpenClaw Pi 執行階段。當受信任的 -Plugin 提供原生 harness（例如內建 Codex app-server harness）， -或你想使用受支援的 CLI 後端（例如 Claude CLI）時使用它。關於心智 -模型，請參閱 [Agent runtimes](/zh-TW/concepts/agent-runtimes)。 +`agentRuntime` 控制哪個低階執行器會執行代理程式回合。多數 +部署應維持預設的 OpenClaw Pi 執行階段。當受信任的 +Plugin 提供原生 harness（例如隨附的 Codex app-server harness）， +或當你想使用支援的 CLI 後端（例如 Claude CLI）時使用它。關於心智 +模型，請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)。 ```json5 { @@ -418,16 +426,16 @@ Plugin 提供原生 harness（例如內建 Codex app-server harness）， } ``` -- `id`：`"auto"`、`"pi"`、已註冊的 Plugin harness id，或受支援的 CLI 後端別名。內建 Codex Plugin 會註冊 `codex`；內建 Anthropic Plugin 提供 `claude-cli` CLI 後端。 -- `id: "auto"` 讓已註冊的 Plugin harness 宣告支援的回合，並在沒有符合 harness 時使用 PI。明確的 Plugin 執行階段（例如 `id: "codex"`）要求該 harness，且在它不可用或失敗時關閉失敗。 +- `id`：`"auto"`、`"pi"`、已註冊的 Plugin harness ID，或支援的 CLI 後端別名。隨附的 Codex Plugin 會註冊 `codex`；隨附的 Anthropic Plugin 提供 `claude-cli` CLI 後端。 +- `id: "auto"` 讓已註冊的 Plugin harness 認領支援的回合，且在沒有 harness 符合時使用 PI。明確的 Plugin 執行階段（例如 `id: "codex"`）要求該 harness，並在其不可用或失敗時封閉失敗。 - 環境覆寫：`OPENCLAW_AGENT_RUNTIME=` 會覆寫該程序的 `id`。 -- 對於僅使用 Codex 的部署，請設定 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。 -- 對於 Claude CLI 部署，建議使用 `model: "anthropic/claude-opus-4-7"` 加上 `agentRuntime.id: "claude-cli"`。舊版 `claude-cli/claude-opus-4-7` 模型參照仍可為了相容性運作，但新設定應維持供應商/模型選取的規範形式，並將執行後端放在 `agentRuntime.id`。 +- 對於僅 Codex 的部署，請設定 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。 +- 對於 Claude CLI 部署，建議使用 `model: "anthropic/claude-opus-4-7"` 加上 `agentRuntime.id: "claude-cli"`。舊版 `claude-cli/claude-opus-4-7` 模型參照仍可為了相容性運作，但新設定應保持標準的供應商／模型選擇，並將執行後端放在 `agentRuntime.id`。 - 較舊的執行階段政策鍵會由 `openclaw doctor --fix` 重寫為 `agentRuntime`。 -- Harness 選擇會在第一次嵌入式執行後，依工作階段 ID 固定。設定/env 變更會影響新的或已重設的工作階段，而不是既有 transcript。具有 transcript 歷史但沒有記錄固定值的舊版工作階段會被視為已固定為 PI。`/status` 會回報有效執行階段，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 -- 這只控制文字代理程式回合執行。媒體生成、視覺、PDF、音樂、影片和 TTS 仍會使用其供應商/模型設定。 +- Harness 選擇會在第一次嵌入式執行後，依工作階段 ID 固定。設定／環境變更會影響新的或重設的工作階段，不會影響既有 transcript。具有 transcript 歷史但沒有已記錄固定值的舊版工作階段會視為已固定到 PI。`/status` 會回報有效的執行階段，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 +- 這只控制文字代理程式回合的執行。媒體產生、視覺、PDF、音樂、影片和 TTS 仍使用其供應商／模型設定。 -**內建別名簡寫**（只在模型位於 `agents.defaults.models` 中時套用）： +**內建別名簡寫**（只有在模型位於 `agents.defaults.models` 時才適用）： | 別名 | 模型 | | ------------------- | ------------------------------------------ | @@ -442,13 +450,13 @@ Plugin 提供原生 harness（例如內建 Codex app-server harness）， 你設定的別名一律優先於預設值。 -Z.AI GLM-4.x 模型會自動啟用 thinking mode，除非你設定 `--thinking off`，或自行定義 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型預設會啟用 `tool_stream` 以進行 tool call streaming。將 `agents.defaults.models["zai/"].params.tool_stream` 設為 `false` 即可停用。 -Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 `adaptive` thinking。 +Z.AI GLM-4.x 模型會自動啟用思考模式，除非你設定 `--thinking off`，或自行定義 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型預設會啟用 `tool_stream` 以進行工具呼叫串流。將 `agents.defaults.models["zai/"].params.tool_stream` 設為 `false` 即可停用。 +Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `adaptive` 思考。 ### `agents.defaults.cliBackends` -用於純文字 fallback 執行的選用 CLI 後端（無工具呼叫）。當 API 提供者失敗時，可作為備援。 +用於純文字後備執行的選用 CLI 後端（無工具呼叫）。在 API 提供者失敗時，可作為備援使用。 ```json5 { @@ -479,11 +487,11 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 - CLI 後端以文字為優先；工具一律停用。 - 設定 `sessionArg` 時支援工作階段。 -- 當 `imageArg` 接受檔案路徑時，支援影像透傳。 +- 當 `imageArg` 接受檔案路徑時，支援影像傳遞。 ### `agents.defaults.systemPromptOverride` -以固定字串取代 OpenClaw 組裝的整個系統提示。可在預設層級（`agents.defaults.systemPromptOverride`）或每個代理（`agents.list[].systemPromptOverride`）設定。每個代理的值優先；空值或僅包含空白字元的值會被忽略。適合受控提示實驗。 +用固定字串取代整個由 OpenClaw 組裝的系統提示詞。可在預設層級（`agents.defaults.systemPromptOverride`）或個別代理（`agents.list[].systemPromptOverride`）設定。個別代理的值優先；空值或僅含空白的值會被忽略。適合用於受控的提示詞實驗。 ```json5 { @@ -497,7 +505,7 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 ### `agents.defaults.promptOverlays` -依模型家族套用、與提供者無關的提示覆疊。GPT-5 家族模型 ID 會跨提供者接收共享行為合約；`personality` 只控制友善互動風格層。 +依模型家族套用、與提供者無關的提示詞覆蓋層。GPT-5 家族模型 ID 會在各提供者間接收共用的行為契約；`personality` 只控制友善互動風格層。 ```json5 { @@ -514,8 +522,8 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 ``` - `"friendly"`（預設）和 `"on"` 會啟用友善互動風格層。 -- `"off"` 只會停用友善層；已標記的 GPT-5 行為合約仍會啟用。 -- 未設定此共享設定時，仍會讀取舊版 `plugins.entries.openai.config.personality`。 +- `"off"` 只會停用友善層；已標記的 GPT-5 行為契約仍會保持啟用。 +- 未設定這個共用設定時，仍會讀取舊版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` @@ -547,15 +555,15 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 } ``` -- `every`：持續時間字串（ms/s/m/h）。預設：`30m`（API 金鑰驗證）或 `1h`（OAuth 驗證）。設為 `0m` 可停用。 -- `includeSystemPromptSection`：為 false 時，會從系統提示省略 Heartbeat 區段，並略過將 `HEARTBEAT.md` 注入啟動環境脈絡。預設：`true`。 -- `suppressToolErrorWarnings`：為 true 時，會在 Heartbeat 執行期間抑制工具錯誤警告 payload。 +- `every`：期間字串（ms/s/m/h）。預設：`30m`（API 金鑰驗證）或 `1h`（OAuth 驗證）。設為 `0m` 即可停用。 +- `includeSystemPromptSection`：為 false 時，會從系統提示詞省略 Heartbeat 區段，並略過將 `HEARTBEAT.md` 注入啟動內容。預設：`true`。 +- `suppressToolErrorWarnings`：為 true 時，會在 Heartbeat 執行期間抑制工具錯誤警告酬載。 - `timeoutSeconds`：Heartbeat 代理回合在中止前允許的最長秒數。未設定時會使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接/DM 傳送政策。`allow`（預設）允許傳送至直接目標。`block` 會抑制傳送至直接目標，並發出 `reason=dm-blocked`。 -- `lightContext`：為 true 時，Heartbeat 執行會使用輕量啟動環境脈絡，且只保留工作區啟動環境檔案中的 `HEARTBEAT.md`。 -- `isolatedSession`：為 true 時，每次 Heartbeat 都會在沒有先前對話歷史的新工作階段中執行。模式與 cron `sessionTarget: "isolated"` 相同。可將每次 Heartbeat 的 token 成本從約 100K 降至約 2-5K token。 -- `skipWhenBusy`：為 true 時，Heartbeat 執行會在額外忙碌的 lane 上延後：子代理或巢狀命令工作。Cron lane 一律會延後 Heartbeat，即使沒有此旗標也一樣。 -- 每個代理：設定 `agents.list[].heartbeat`。當任一代理定義 `heartbeat` 時，**只有那些代理**會執行 Heartbeat。 +- `directPolicy`：直接/DM 傳遞政策。`allow`（預設）允許傳遞至直接目標。`block` 會抑制直接目標傳遞，並發出 `reason=dm-blocked`。 +- `lightContext`：為 true 時，Heartbeat 執行會使用輕量啟動內容，並且只保留工作區啟動檔案中的 `HEARTBEAT.md`。 +- `isolatedSession`：為 true 時，每次 Heartbeat 都會在全新工作階段中執行，沒有先前對話歷史。與 Cron `sessionTarget: "isolated"` 相同的隔離模式。將每次 Heartbeat 的 token 成本從約 100K 降至約 2-5K token。 +- `skipWhenBusy`：為 true 時，Heartbeat 執行會因額外忙碌通道而延後：子代理或巢狀命令工作。即使沒有此旗標，Cron 通道也一律會延後 Heartbeat。 +- 個別代理：設定 `agents.list[].heartbeat`。當任何代理定義了 `heartbeat`，**只有那些代理**會執行 Heartbeat。 - Heartbeat 會執行完整代理回合，較短的間隔會消耗更多 token。 ### `agents.defaults.compaction` @@ -593,22 +601,22 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 ``` - `mode`：`default` 或 `safeguard`（針對長歷史的分塊摘要）。請參閱 [Compaction](/zh-TW/concepts/compaction)。 -- `provider`：已註冊 Compaction provider Plugin 的 ID。設定後，會呼叫該 provider 的 `summarize()`，而不是內建 LLM 摘要。失敗時會 fallback 至內建摘要。設定 provider 會強制 `mode: "safeguard"`。請參閱 [Compaction](/zh-TW/concepts/compaction)。 +- `provider`：已註冊 Compaction 提供者 Plugin 的 ID。設定後，會呼叫提供者的 `summarize()`，而不是內建 LLM 摘要。失敗時會退回內建摘要。設定提供者會強制 `mode: "safeguard"`。請參閱 [Compaction](/zh-TW/concepts/compaction)。 - `timeoutSeconds`：單次 Compaction 作業在 OpenClaw 中止前允許的最長秒數。預設：`900`。 -- `keepRecentTokens`：Pi 切點預算，用於逐字保留最新的逐字稿尾端。手動 `/compact` 只有在明確設定時才會遵守此值；否則手動 Compaction 會是一個硬 checkpoint。 -- `identifierPolicy`：`strict`（預設）、`off` 或 `custom`。`strict` 會在 Compaction 摘要期間前置內建的不透明識別碼保留指引。 +- `keepRecentTokens`：Pi 切點預算，用於逐字保留最近的逐字稿尾端。手動 `/compact` 在明確設定時會遵循此值；否則手動 Compaction 會是硬檢查點。 +- `identifierPolicy`：`strict`（預設）、`off` 或 `custom`。`strict` 會在 Compaction 摘要期間加上內建的不透明識別碼保留指引前綴。 - `identifierInstructions`：當 `identifierPolicy=custom` 時使用的選用自訂識別碼保留文字。 -- `qualityGuard`：針對 safeguard 摘要的格式錯誤輸出重試檢查。在 safeguard 模式中預設啟用；設為 `enabled: false` 可略過稽核。 -- `midTurnPrecheck`：選用的 Pi tool-loop 壓力檢查。當 `enabled: true` 時，OpenClaw 會在工具結果附加後、下一次模型呼叫前檢查脈絡壓力。如果脈絡已無法容納，它會在提交提示前中止目前嘗試，並重用既有的預檢復原路徑來截斷工具結果，或進行 Compaction 後重試。可搭配 `default` 和 `safeguard` Compaction 模式使用。預設：停用。 -- `postCompactionSections`：選用的 AGENTS.md H2/H3 區段名稱，用於在 Compaction 後重新注入。預設為 `["Session Startup", "Red Lines"]`；設為 `[]` 可停用重新注入。未設定或明確設為該預設配對時，也會接受較舊的 `Every Session`/`Safety` 標題作為舊版 fallback。 -- `model`：僅用於 Compaction 摘要的選用 `provider/model-id` 覆寫。當主要工作階段應保留一個模型，但 Compaction 摘要應在另一個模型上執行時使用；未設定時，Compaction 會使用工作階段的主要模型。 -- `maxActiveTranscriptBytes`：選用的位元組門檻（`number` 或類似 `"20mb"` 的字串），當作用中 JSONL 超過門檻時，會在執行前觸發一般本機 Compaction。需要 `truncateAfterCompaction`，成功的 Compaction 才能輪替至較小的後續逐字稿。未設定或為 `0` 時停用。 -- `notifyUser`：為 `true` 時，會在 Compaction 開始和完成時傳送簡短通知給使用者（例如「正在壓縮脈絡...」和「Compaction 完成」）。預設停用，以維持 Compaction 靜默。 -- `memoryFlush`：自動 Compaction 前的靜默代理回合，用於儲存持久記憶。當這個 housekeeping 回合應留在本機模型上時，將 `model` 設為精確的 provider/model，例如 `ollama/qwen3:8b`；此覆寫不會繼承作用中工作階段的 fallback 鏈。工作區為唯讀時會略過。 +- `qualityGuard`：針對 safeguard 摘要的格式錯誤輸出重試檢查。在 safeguard 模式中預設啟用；設定 `enabled: false` 可略過稽核。 +- `midTurnPrecheck`：選用的 Pi 工具迴圈壓力檢查。當 `enabled: true` 時，OpenClaw 會在附加工具結果後、下一次模型呼叫前檢查內容壓力。若內容已無法容納，它會在提交提示詞前中止目前嘗試，並重用既有的預檢復原路徑來截斷工具結果，或執行 Compaction 後重試。可與 `default` 和 `safeguard` 兩種 Compaction 模式搭配使用。預設：停用。 +- `postCompactionSections`：Compaction 後要重新注入的選用 AGENTS.md H2/H3 區段名稱。預設為 `["Session Startup", "Red Lines"]`；設為 `[]` 可停用重新注入。未設定或明確設為該預設組合時，也會接受舊版 `Every Session`/`Safety` 標題作為相容後備。 +- `model`：僅用於 Compaction 摘要的選用 `provider/model-id` 覆蓋。當主要工作階段應保留一個模型，但 Compaction 摘要應在另一個模型上執行時使用；未設定時，Compaction 會使用工作階段的主要模型。 +- `maxActiveTranscriptBytes`：選用位元組閾值（`number` 或像 `"20mb"` 的字串），當作用中 JSONL 超過閾值時，會在執行前觸發一般本機 Compaction。需要 `truncateAfterCompaction`，讓成功的 Compaction 能輪替到較小的後續逐字稿。未設定或為 `0` 時停用。 +- `notifyUser`：為 `true` 時，會在 Compaction 開始與完成時向使用者傳送簡短通知（例如「正在壓縮內容...」和「Compaction 完成」）。預設停用，以保持 Compaction 靜默。 +- `memoryFlush`：自動 Compaction 前的靜默代理式回合，用於儲存持久記憶。當此維護回合應保留在本機模型上時，將 `model` 設為精確的提供者/模型，例如 `ollama/qwen3:8b`；此覆蓋不會繼承作用中工作階段的後備鏈。工作區為唯讀時會略過。 ### `agents.defaults.contextPruning` -在傳送給 LLM 前，從記憶體脈絡中修剪**舊工具結果**。**不會**修改磁碟上的工作階段歷史。 +在傳送給 LLM 前，從記憶體內容修剪**舊工具結果**。**不會**修改磁碟上的工作階段歷史。 ```json5 { @@ -630,25 +638,25 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 } ``` - + -- `mode: "cache-ttl"` 會啟用修剪 pass。 -- `ttl` 控制修剪多久後可以再次執行（自上次 cache touch 後）。 -- 修剪會先 soft-trim 過大的工具結果，接著在需要時 hard-clear 較舊的工具結果。 +- `mode: "cache-ttl"` 會啟用修剪階段。 +- `ttl` 控制修剪多久後才能再次執行（從上次快取觸碰後開始算）。 +- 修剪會先軟修剪過大的工具結果，接著在需要時硬清除較舊的工具結果。 -**Soft-trim** 會保留開頭 + 結尾，並在中間插入 `...`。 +**軟修剪**會保留開頭 + 結尾，並在中間插入 `...`。 -**Hard-clear** 會以 placeholder 取代整個工具結果。 +**硬清除**會用佔位符取代整個工具結果。 注意事項： -- 影像區塊絕不會被修剪/清除。 -- 比率以字元為基準（近似值），不是精確的 token 計數。 -- 如果助理訊息少於 `keepLastAssistants`，會略過修剪。 +- 影像區塊永遠不會被修剪/清除。 +- 比率以字元為基準（近似值），不是精確的 token 數。 +- 如果助理訊息少於 `keepLastAssistants` 則會略過修剪。 -行為細節請參閱 [工作階段修剪](/zh-TW/concepts/session-pruning)。 +請參閱 [工作階段修剪](/zh-TW/concepts/session-pruning) 了解行為細節。 ### 區塊串流 @@ -667,10 +675,10 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 ``` - 非 Telegram 頻道需要明確設定 `*.blockStreaming: true` 才能啟用區塊回覆。 -- 頻道覆寫：`channels..blockStreamingCoalesce`（以及每個帳號的變體）。Signal/Slack/Discord/Google Chat 預設為 `minChars: 1500`。 -- `humanDelay`：區塊回覆之間的隨機暫停。`natural` = 800-2500ms。每個代理覆寫：`agents.list[].humanDelay`。 +- 頻道覆蓋：`channels..blockStreamingCoalesce`（以及個別帳號變體）。Signal/Slack/Discord/Google Chat 預設為 `minChars: 1500`。 +- `humanDelay`：區塊回覆之間的隨機暫停。`natural` = 800–2500ms。個別代理覆蓋：`agents.list[].humanDelay`。 -行為與分塊細節請參閱 [串流](/zh-TW/concepts/streaming)。 +請參閱 [串流](/zh-TW/concepts/streaming) 了解行為 + 分塊細節。 ### 輸入指示器 @@ -686,15 +694,15 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 ``` - 預設值：直接聊天/提及使用 `instant`，未提及的群組聊天使用 `message`。 -- 每個工作階段覆寫：`session.typingMode`、`session.typingIntervalSeconds`。 +- 每工作階段覆寫：`session.typingMode`、`session.typingIntervalSeconds`。 -請參閱[輸入指示器](/zh-TW/concepts/typing-indicators)。 +請參閱 [輸入指示器](/zh-TW/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式代理的選用沙箱化設定。完整指南請參閱[沙箱化](/zh-TW/gateway/sandboxing)。 +嵌入式代理的選用沙箱化。完整指南請參閱 [沙箱化](/zh-TW/gateway/sandboxing)。 ```json5 { @@ -802,39 +810,39 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 **SSH 後端設定：** -- `target`：`user@host[:port]` 格式的 SSH 目標 +- `target`：`user@host[:port]` 形式的 SSH 目標 - `command`：SSH 用戶端命令（預設：`ssh`） -- `workspaceRoot`：用於各範圍工作區的遠端絕對根目錄 +- `workspaceRoot`：用於各範圍工作區的絕對遠端根目錄 - `identityFile` / `certificateFile` / `knownHostsFile`：傳遞給 OpenSSH 的現有本機檔案 -- `identityData` / `certificateData` / `knownHostsData`：內嵌內容或 SecretRefs，OpenClaw 會在執行階段將其實體化為暫存檔 -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主機金鑰原則旋鈕 +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在執行階段具體化為暫存檔案的內嵌內容或 SecretRef +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主機金鑰政策控制項 **SSH 驗證優先順序：** - `identityData` 優先於 `identityFile` - `certificateData` 優先於 `certificateFile` - `knownHostsData` 優先於 `knownHostsFile` -- 由 SecretRef 支援的 `*Data` 值會在沙箱工作階段啟動前，從作用中的祕密執行階段快照解析 +- 由 SecretRef 支援的 `*Data` 值會在沙箱工作階段開始前，從作用中的密鑰執行階段快照解析 **SSH 後端行為：** -- 建立或重新建立後，會將遠端工作區植入一次 -- 接著保持遠端 SSH 工作區為權威來源 -- 透過 SSH 路由 `exec`、檔案工具與媒體路徑 +- 建立或重新建立後，會為遠端工作區植入一次 +- 然後保持遠端 SSH 工作區為標準來源 +- 透過 SSH 路由 `exec`、檔案工具和媒體路徑 - 不會自動將遠端變更同步回主機 - 不支援沙箱瀏覽器容器 **工作區存取：** -- `none`：位於 `~/.openclaw/sandboxes` 底下的各範圍沙箱工作區 +- `none`：位於 `~/.openclaw/sandboxes` 下的各範圍沙箱工作區 - `ro`：沙箱工作區位於 `/workspace`，代理工作區以唯讀方式掛載於 `/agent` - `rw`：代理工作區以讀寫方式掛載於 `/workspace` **範圍：** -- `session`：每個工作階段一個容器與工作區 -- `agent`：每個代理一個容器與工作區（預設） -- `shared`：共用容器與工作區（沒有跨工作階段隔離） +- `session`：每個工作階段各自的容器 + 工作區 +- `agent`：每個代理一個容器 + 工作區（預設） +- `shared`：共用容器和工作區（無跨工作階段隔離） **OpenShell Plugin 設定：** @@ -864,29 +872,29 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 **OpenShell 模式：** -- `mirror`：執行前從本機植入遠端，執行後同步回來；本機工作區保持為權威來源 -- `remote`：建立沙箱時將遠端植入一次，接著保持遠端工作區為權威來源 +- `mirror`：執行前從本機植入遠端，執行後同步回來；本機工作區維持為標準來源 +- `remote`：建立沙箱時植入遠端一次，之後保持遠端工作區為標準來源 -在 `remote` 模式中，於 OpenClaw 外部所做的主機本機編輯，在植入步驟後不會自動同步進沙箱。 -傳輸是透過 SSH 進入 OpenShell 沙箱，但 Plugin 擁有沙箱生命週期與選用的鏡像同步。 +在 `remote` 模式中，於 OpenClaw 外部進行的主機本機編輯，在植入步驟後不會自動同步至沙箱。 +傳輸是透過 SSH 進入 OpenShell 沙箱，但 Plugin 負責沙箱生命週期和選用的鏡像同步。 -**`setupCommand`** 會在容器建立後執行一次（透過 `sh -lc`）。需要網路輸出、可寫入的根目錄、root 使用者。 +**`setupCommand`** 會在容器建立後執行一次（透過 `sh -lc`）。需要網路出口、可寫入根目錄、root 使用者。 -**容器預設為 `network: "none"`** —— 如果代理需要對外存取，請設為 `"bridge"`（或自訂橋接網路）。 -`"host"` 會被封鎖。`"container:"` 預設會被封鎖，除非你明確設定 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急例外）。 +**容器預設為 `network: "none"`** — 若代理需要對外存取，請設為 `"bridge"`（或自訂橋接網路）。 +`"host"` 會被封鎖。除非你明確設定 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急例外），否則預設會封鎖 `"container:"`。 -**傳入附件** 會暫存到作用中工作區的 `media/inbound/*`。 +**傳入附件** 會暫存至作用中工作區的 `media/inbound/*`。 -**`docker.binds`** 會掛載額外的主機目錄；全域與每個代理的繫結會合併。 +**`docker.binds`** 會掛載額外的主機目錄；全域和各代理繫結會合併。 **沙箱化瀏覽器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 會注入系統提示。不需要在 `openclaw.json` 中設定 `browser.enabled`。 -noVNC 觀察者存取預設使用 VNC 驗證，OpenClaw 會發出短期有效的權杖 URL（而不是在共用 URL 中暴露密碼）。 +noVNC 觀察者存取預設使用 VNC 驗證，且 OpenClaw 會發出短期有效的權杖 URL（而不是在共用 URL 中暴露密碼）。 -- `allowHostControl: false`（預設）會阻止沙箱化工作階段指定主機瀏覽器。 +- `allowHostControl: false`（預設）會阻止沙箱化工作階段鎖定主機瀏覽器。 - `network` 預設為 `openclaw-sandbox-browser`（專用橋接網路）。只有在你明確想要全域橋接連線時，才設為 `bridge`。 -- `cdpSourceRange` 可選擇性地將容器邊緣的 CDP 輸入限制為 CIDR 範圍（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 只會將額外的主機目錄掛載到沙箱瀏覽器容器中。設定後（包含 `[]`），它會取代瀏覽器容器的 `docker.binds`。 +- `cdpSourceRange` 可選擇性地將容器邊界的 CDP 入口限制在 CIDR 範圍內（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 只會將額外的主機目錄掛載到沙箱瀏覽器容器中。設定時（包括 `[]`），它會取代瀏覽器容器的 `docker.binds`。 - 啟動預設值定義於 `scripts/sandbox-browser-entrypoint.sh`，並針對容器主機調校： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -906,14 +914,14 @@ noVNC 觀察者存取預設使用 VNC 驗證，OpenClaw 會發出短期有效的 - `--metrics-recording-only` - `--disable-extensions`（預設啟用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 預設啟用；如果 WebGL/3D 使用情境需要，可透過 + 預設啟用；若 WebGL/3D 使用情境需要，可透過 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 停用。 - - 如果你的工作流程依賴擴充功能，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 會重新啟用擴充功能。 + - 若你的工作流程依賴擴充功能，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 會重新啟用擴充功能。 - `--renderer-process-limit=2` 可透過 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 變更；設為 `0` 以使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 變更；設為 `0` 可使用 Chromium 的 預設程序限制。 - 啟用 `noSandbox` 時，另加 `--no-sandbox`。 - - 預設值是容器映像基準；若要變更容器預設值，請使用具自訂 + - 預設值是容器映像基準；若要變更容器預設值，請使用具有自訂 進入點的自訂瀏覽器映像。 @@ -927,16 +935,16 @@ scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` -若 npm 安裝沒有原始碼 checkout，請參閱[沙箱化 § 映像與設定](/zh-TW/gateway/sandboxing#images-and-setup)，取得內嵌的 `docker build` 命令。 +若是沒有原始碼 checkout 的 npm 安裝，內嵌 `docker build` 命令請參閱 [沙箱化 § 映像與設定](/zh-TW/gateway/sandboxing#images-and-setup)。 -### `agents.list`（每個代理覆寫） +### `agents.list`（各代理覆寫） -使用 `agents.list[].tts` 為代理指定自己的 TTS 供應商、語音、模型、 -風格或自動 TTS 模式。代理區塊會深度合併到全域 -`messages.tts` 之上，因此共用憑證可以保留在同一處，而個別 -代理只覆寫其需要的語音或供應商欄位。作用中代理的 +使用 `agents.list[].tts` 可為代理指定自己的 TTS 提供者、語音、模型、 +樣式或自動 TTS 模式。代理區塊會深度合併到全域 +`messages.tts` 之上，因此共用憑證可以保留在同一處，而各個 +代理只覆寫它們需要的語音或提供者欄位。作用中代理的 覆寫會套用到自動語音回覆、`/tts audio`、`/tts status` 和 -`tts` 代理工具。供應商範例與優先順序請參閱[文字轉語音](/zh-TW/tools/tts#per-agent-voice-overrides)。 +`tts` 代理工具。提供者範例和優先順序請參閱 [文字轉語音](/zh-TW/tools/tts#per-agent-voice-overrides)。 ```json5 { @@ -990,28 +998,28 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`：穩定的代理程式 ID（必填）。 -- `default`：設定多個時，第一個生效（會記錄警告）。如果都未設定，清單中的第一個項目就是預設值。 -- `model`：字串形式會設定嚴格的每代理程式主要模型，且沒有模型後援；物件形式 `{ primary }` 也同樣嚴格，除非你加入 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 讓該代理程式選擇啟用後援，或使用 `{ primary, fallbacks: [] }` 明確指定嚴格行為。只覆寫 `primary` 的 Cron 工作仍會繼承預設後援，除非你設定 `fallbacks: []`。 -- `params`：每代理程式串流參數，會合併覆寫 `agents.defaults.models` 中選取的模型項目。可用於代理程式特定覆寫，例如 `cacheRetention`、`temperature` 或 `maxTokens`，不必複製整個模型目錄。 -- `tts`：選用的每代理程式文字轉語音覆寫。此區塊會深度合併覆寫 `messages.tts`，因此請將共用提供者憑證與後援政策保留在 `messages.tts`，並只在此設定角色特定值，例如提供者、語音、模型、風格或自動模式。 -- `skills`：選用的每代理程式 Skills 允許清單。如果省略，代理程式會在已設定時繼承 `agents.defaults.skills`；明確清單會取代預設值而非合併，且 `[]` 表示沒有 Skills。 -- `thinkingDefault`：選用的每代理程式預設思考等級（`off | minimal | low | medium | high | xhigh | adaptive | max`）。當未設定每訊息或工作階段覆寫時，會覆寫此代理程式的 `agents.defaults.thinkingDefault`。所選提供者/模型設定檔會控制哪些值有效；對於 Google Gemini，`adaptive` 會保留提供者擁有的動態思考（Gemini 3/3.1 省略 `thinkingLevel`，Gemini 2.5 使用 `thinkingBudget: -1`）。 -- `reasoningDefault`：選用的每代理程式預設推理可見性（`on | off | stream`）。當未設定每訊息或工作階段推理覆寫時，會覆寫此代理程式的 `agents.defaults.reasoningDefault`。 -- `fastModeDefault`：選用的每代理程式快速模式預設值（`true | false`）。當未設定每訊息或工作階段快速模式覆寫時套用。 -- `agentRuntime`：選用的每代理程式低階執行階段政策覆寫。使用 `{ id: "codex" }` 可讓某個代理程式僅使用 Codex，而其他代理程式在 `auto` 模式中保留預設 PI 後援。 -- `runtime`：選用的每代理程式執行階段描述元。當代理程式應預設為 ACP harness 工作階段時，搭配 `runtime.acp` 預設值（`agent`、`backend`、`mode`、`cwd`）使用 `type: "acp"`。 -- `identity.avatar`：工作區相對路徑、`http(s)` URL 或 `data:` URI。 -- `identity` 會推導預設值：從 `emoji` 推導 `ackReaction`，從 `name`/`emoji` 推導 `mentionPatterns`。 -- `subagents.allowAgents`：明確 `sessions_spawn.agentId` 目標的代理程式 ID 允許清單（`["*"]` = 任意；預設：僅相同代理程式）。當應允許自我目標的 `agentId` 呼叫時，請包含請求者 ID。 -- 沙箱繼承防護：如果請求者工作階段受沙箱限制，`sessions_spawn` 會拒絕將在非沙箱環境中執行的目標。 -- `subagents.requireAgentId`：為 true 時，封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔；預設：false）。 +- `id`：穩定的代理 id（必填）。 +- `default`：設定多個時，第一個生效（會記錄警告）。如果未設定任何一個，清單第一項就是預設值。 +- `model`：字串形式會設定嚴格的每代理主要模型，不使用模型備援；物件形式 `{ primary }` 也同樣嚴格，除非你加入 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 讓該代理選擇啟用備援，或使用 `{ primary, fallbacks: [] }` 明確指定嚴格行為。只覆寫 `primary` 的 Cron 工作仍會繼承預設備援，除非你設定 `fallbacks: []`。 +- `params`：每代理串流參數，會合併覆蓋 `agents.defaults.models` 中選取的模型項目。若要為代理指定 `cacheRetention`、`temperature` 或 `maxTokens` 等專屬覆寫，而不複製整個模型目錄，請使用此設定。 +- `tts`：選用的每代理文字轉語音覆寫。此區塊會深度合併覆蓋 `messages.tts`，因此請將共用提供者憑證與備援政策保留在 `messages.tts`，並只在此設定角色專屬值，例如提供者、語音、模型、風格或自動模式。 +- `skills`：選用的每代理 Skills 允許清單。若省略，代理會在已設定時繼承 `agents.defaults.skills`；明確清單會取代預設值而非合併，且 `[]` 表示不使用 Skills。 +- `thinkingDefault`：選用的每代理預設思考層級（`off | minimal | low | medium | high | xhigh | adaptive | max`）。當未設定每則訊息或工作階段覆寫時，會為此代理覆寫 `agents.defaults.thinkingDefault`。選取的提供者/模型設定檔會控制哪些值有效；對 Google Gemini 而言，`adaptive` 會保留提供者擁有的動態思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：選用的每代理預設推理可見性（`on | off | stream`）。當未設定每則訊息或工作階段推理覆寫時，會為此代理覆寫 `agents.defaults.reasoningDefault`。 +- `fastModeDefault`：選用的每代理快速模式預設值（`true | false`）。當未設定每則訊息或工作階段快速模式覆寫時套用。 +- `agentRuntime`：選用的每代理低階執行階段政策覆寫。使用 `{ id: "codex" }` 可讓某個代理僅使用 Codex，而其他代理在 `auto` 模式下維持預設 PI 備援。 +- `runtime`：選用的每代理執行階段描述元。當代理應預設使用 ACP harness 工作階段時，請搭配 `runtime.acp` 預設值（`agent`、`backend`、`mode`、`cwd`）使用 `type: "acp"`。 +- `identity.avatar`：相對於工作區的路徑、`http(s)` URL，或 `data:` URI。 +- `identity` 會衍生預設值：`ackReaction` 來自 `emoji`，`mentionPatterns` 來自 `name`/`emoji`。 +- `subagents.allowAgents`：明確 `sessions_spawn.agentId` 目標的代理 id 允許清單（`["*"]` = 任意；預設：僅相同代理）。當應允許自我目標的 `agentId` 呼叫時，請包含請求端 id。 +- 沙箱繼承防護：如果請求端工作階段已沙箱化，`sessions_spawn` 會拒絕會以非沙箱方式執行的目標。 +- `subagents.requireAgentId`：為 true 時，封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選取設定檔；預設：false）。 --- -## 多代理程式路由 +## 多代理路由 -在一個 Gateway 內執行多個隔離的代理程式。請參閱 [Multi-Agent](/zh-TW/concepts/multi-agent)。 +在一個 Gateway 內執行多個隔離的代理。請參閱[多代理](/zh-TW/concepts/multi-agent)。 ```json5 { @@ -1028,13 +1036,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### 綁定比對欄位 +### 繫結比對欄位 -- `type`（選用）：`route` 用於一般路由（缺少 type 時預設為 route），`acp` 用於持久 ACP 對話綁定。 +- `type`（選用）：一般路由使用 `route`（缺少 type 時預設為 route），持久 ACP 對話繫結使用 `acp`。 - `match.channel`（必填） - `match.accountId`（選用；`*` = 任意帳號；省略 = 預設帳號） - `match.peer`（選用；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（選用；通道特定） +- `match.guildId` / `match.teamId`（選用；頻道專屬） - `acp`（選用；僅適用於 `type: "acp"`）：`{ mode, label, cwd, backend }` **確定性比對順序：** @@ -1043,16 +1051,16 @@ scripts/sandbox-browser-setup.sh # optional browser image 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精確，無 peer/guild/team） -5. `match.accountId: "*"`（整個通道） -6. 預設代理程式 +5. `match.accountId: "*"`（全頻道） +6. 預設代理 在每一層中，第一個相符的 `bindings` 項目會生效。 -對於 `type: "acp"` 項目，OpenClaw 會依精確對話身分（`match.channel` + 帳號 + `match.peer.id`）解析，且不使用上方的路由綁定層級順序。 +對於 `type: "acp"` 項目，OpenClaw 會依精確的對話身分（`match.channel` + 帳號 + `match.peer.id`）解析，且不使用上述路由繫結層級順序。 -### 每代理程式存取設定檔 +### 每代理存取設定檔 - + ```json5 { @@ -1070,7 +1078,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1099,7 +1107,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1145,7 +1153,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -如需優先順序詳細資訊，請參閱[多代理沙箱與工具](/zh-TW/tools/multi-agent-sandbox-tools)。 +如需優先順序詳細資訊，請參閱 [Multi-Agent Sandbox & Tools](/zh-TW/tools/multi-agent-sandbox-tools)。 --- @@ -1197,33 +1205,33 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群組聊天情境的基礎工作階段分組策略。 - - `per-sender`（預設）：每個傳送者在某個頻道情境中取得獨立工作階段。 - - `global`：某個頻道情境中的所有參與者共用單一工作階段（僅在需要共用情境時使用）。 + - `per-sender`（預設）：每位傳送者在一個頻道情境中都有隔離的工作階段。 + - `global`：一個頻道情境中的所有參與者共用單一工作階段（僅在需要共用情境時使用）。 - **`dmScope`**：DM 的分組方式。 - `main`：所有 DM 共用主要工作階段。 - `per-peer`：跨頻道依傳送者 ID 隔離。 - `per-channel-peer`：依頻道 + 傳送者隔離（建議用於多使用者收件匣）。 - - `per-account-channel-peer`：依帳戶 + 頻道 + 傳送者隔離（建議用於多帳戶）。 -- **`identityLinks`**：將標準 ID 對應到帶有供應商前綴的對等方，以便跨頻道共用工作階段。諸如 `/dock_discord` 的 Dock 命令會使用相同對應，將作用中工作階段的回覆路由切換到另一個已連結的頻道對等方；請參閱[頻道 docking](/zh-TW/concepts/channel-docking)。 -- **`reset`**：主要重設政策。`daily` 會在本機時間 `atHour` 重設；`idle` 會在 `idleMinutes` 後重設。同時設定時，先到期者生效。每日重設的新鮮度使用工作階段列的 `sessionStartedAt`；閒置重設的新鮮度使用 `lastInteractionAt`。背景/系統事件寫入（例如 Heartbeat、Cron 喚醒、exec 通知和 Gateway 簿記）可以更新 `updatedAt`，但不會讓每日/閒置工作階段保持新鮮。 + - `per-account-channel-peer`：依帳號 + 頻道 + 傳送者隔離（建議用於多帳號）。 +- **`identityLinks`**：將標準 ID 對應到具有提供者前綴的對等端，以便跨頻道共用工作階段。Dock 指令（例如 `/dock_discord`）使用相同對應，將作用中工作階段的回覆路由切換到另一個已連結的頻道對等端；請參閱[頻道停駐](/zh-TW/concepts/channel-docking)。 +- **`reset`**：主要重設原則。`daily` 會在本機時間 `atHour` 重設；`idle` 會在 `idleMinutes` 後重設。兩者都設定時，先到期者生效。每日重設的新鮮度使用工作階段列的 `sessionStartedAt`；閒置重設的新鮮度使用 `lastInteractionAt`。背景/系統事件寫入（例如 Heartbeat、Cron 喚醒、exec 通知和 Gateway 簿記）可以更新 `updatedAt`，但不會讓每日/閒置工作階段保持新鮮。 - **`resetByType`**：依類型覆寫（`direct`、`group`、`thread`）。舊版 `dm` 可作為 `direct` 的別名。 -- **`mainKey`**：舊版欄位。執行階段一律使用 `"main"` 作為主要直接聊天儲存桶。 -- **`agentToAgent.maxPingPongTurns`**：代理對代理交換期間，代理之間回覆往返的最大回合數（整數，範圍：`0`–`5`）。`0` 會停用 ping-pong 串接。 -- **`sendPolicy`**：依 `channel`、`chatType`（`direct|group|channel`，含舊版 `dm` 別名）、`keyPrefix` 或 `rawKeyPrefix` 比對。第一個拒絕規則生效。 +- **`mainKey`**：舊版欄位。Runtime 一律使用 `"main"` 作為主要直接聊天桶。 +- **`agentToAgent.maxPingPongTurns`**：在代理程式對代理程式交換期間，代理程式之間的最大來回回覆輪數（整數，範圍：`0`–`5`）。`0` 會停用來回串接。 +- **`sendPolicy`**：依 `channel`、`chatType`（`direct|group|channel`，含舊版 `dm` 別名）、`keyPrefix` 或 `rawKeyPrefix` 比對。第一個拒絕規則優先。 - **`maintenance`**：工作階段儲存清理 + 保留控制。 - `mode`：`warn` 只發出警告；`enforce` 會套用清理。 - - `pruneAfter`：過期項目的年齡截斷點（預設 `30d`）。 - - `maxEntries`：`sessions.json` 中的項目數量上限（預設 `500`）。執行階段會使用小型高水位緩衝區批次寫入清理，以支援生產規模上限；`openclaw sessions cleanup --enforce` 會立即套用上限。 - - `rotateBytes`：已淘汰且會被忽略；`openclaw doctor --fix` 會將它從較舊設定中移除。 - - `resetArchiveRetention`：`*.reset.` 轉錄封存的保留期。預設為 `pruneAfter`；設為 `false` 可停用。 - - `maxDiskBytes`：選用的工作階段目錄磁碟預算。在 `warn` 模式會記錄警告；在 `enforce` 模式會先移除最舊的成品/工作階段。 + - `pruneAfter`：過時項目的年齡截止值（預設 `30d`）。 + - `maxEntries`：`sessions.json` 中的項目數上限（預設 `500`）。Runtime 會以適合正式環境大小上限的小型高水位緩衝區批次寫入清理；`openclaw sessions cleanup --enforce` 會立即套用上限。 + - `rotateBytes`：已淘汰且會被忽略；`openclaw doctor --fix` 會從較舊的設定中移除它。 + - `resetArchiveRetention`：`*.reset.` 對話逐字稿封存的保留期。預設為 `pruneAfter`；設為 `false` 可停用。 + - `maxDiskBytes`：選用的工作階段目錄磁碟預算。在 `warn` 模式中會記錄警告；在 `enforce` 模式中會先移除最舊的成品/工作階段。 - `highWaterBytes`：預算清理後的選用目標。預設為 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：執行緒綁定工作階段功能的全域預設值。 - - `enabled`：主要預設開關（供應商可覆寫；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：預設非活動自動取消聚焦時間（小時）（`0` 會停用；供應商可覆寫） - - `maxAgeHours`：預設硬性最大年齡（小時）（`0` 會停用；供應商可覆寫） - - `spawnSessions`：從 `sessions_spawn` 和 ACP 執行緒生成建立執行緒綁定工作階段的預設閘門。啟用執行緒綁定時預設為 `true`；供應商/帳戶可覆寫。 - - `defaultSpawnContext`：執行緒綁定生成的預設原生子代理情境（`"fork"` 或 `"isolated"`）。預設為 `"fork"`。 + - `enabled`：主要預設開關（提供者可以覆寫；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：預設閒置自動取消聚焦時數（`0` 會停用；提供者可以覆寫） + - `maxAgeHours`：預設硬性最大時數（`0` 會停用；提供者可以覆寫） + - `spawnSessions`：從 `sessions_spawn` 和 ACP 執行緒產生建立執行緒綁定工作階段的預設閘門。啟用執行緒綁定時預設為 `true`；提供者/帳號可以覆寫。 + - `defaultSpawnContext`：執行緒綁定產生的預設原生子代理程式情境（`"fork"` 或 `"isolated"`）。預設為 `"fork"`。 @@ -1263,34 +1271,34 @@ scripts/sandbox-browser-setup.sh # optional browser image 每個頻道/帳號覆寫：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析方式（最具體者優先）：帳號 → 頻道 → 全域。`""` 會停用並停止串接。`"auto"` 會衍生 `[{identity.name}]`。 +解析順序（最具體者優先）：帳號 → 頻道 → 全域。`""` 會停用並停止串接。`"auto"` 會衍生為 `[{identity.name}]`。 **範本變數：** -| 變數 | 說明 | 範例 | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | 簡短模型名稱 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型識別碼 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供者名稱 | `anthropic` | -| `{thinkingLevel}` | 目前思考層級 | `high`, `low`, `off` | -| `{identity.name}` | Agent 身分名稱 | （與 `"auto"` 相同） | +| 變數 | 說明 | 範例 | +| ----------------- | -------------------- | --------------------------- | +| `{model}` | 簡短模型名稱 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型識別碼 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供者名稱 | `anthropic` | +| `{thinkingLevel}` | 目前思考層級 | `high`, `low`, `off` | +| `{identity.name}` | 代理身分名稱 | （與 `"auto"` 相同） | 變數不區分大小寫。`{think}` 是 `{thinkingLevel}` 的別名。 ### 確認反應 -- 預設為作用中 agent 的 `identity.emoji`，否則為 `"👀"`。設為 `""` 可停用。 +- 預設為作用中代理的 `identity.emoji`，否則為 `"👀"`。設為 `""` 可停用。 - 每個頻道覆寫：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析順序：帳號 → 頻道 → `messages.ackReaction` → 身分備援。 +- 解析順序：帳號 → 頻道 → `messages.ackReaction` → 身分後援。 - 範圍：`group-mentions`（預設）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在支援反應的頻道（例如 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles）上，回覆後移除確認反應。 +- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支援反應的頻道上，回覆後移除確認反應。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上啟用生命週期狀態反應。 - 在 Slack 和 Discord 上，未設定時，只要確認反應為作用中，狀態反應就會保持啟用。 - 在 Telegram 上，請明確設為 `true` 以啟用生命週期狀態反應。 + 在 Slack 和 Discord 上，未設定時，如果確認反應為作用中，狀態反應會保持啟用。 + 在 Telegram 上，需明確將其設為 `true` 才會啟用生命週期狀態反應。 ### 傳入防抖 -將同一寄件者快速送出的純文字訊息批次合併為單一 agent 回合。媒體/附件會立即刷新。控制命令會略過防抖。 +將同一傳送者快速送出的純文字訊息合併成單一代理回合。媒體/附件會立即送出。控制命令會略過防抖。 ### TTS（文字轉語音） @@ -1340,19 +1348,19 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制預設自動 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆寫本機偏好設定，`/tts status` 會顯示實際生效狀態。 -- `summaryModel` 會覆寫自動摘要的 `agents.defaults.model.primary`。 +- `auto` 控制預設自動 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆寫本機偏好設定，`/tts status` 會顯示有效狀態。 +- `summaryModel` 會覆寫自動摘要所用的 `agents.defaults.model.primary`。 - `modelOverrides` 預設啟用；`modelOverrides.allowProvider` 預設為 `false`（選擇加入）。 -- API 金鑰會回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- 內建語音提供者由 Plugin 擁有。如果已設定 `plugins.allow`，請加入每個你想使用的 TTS 提供者 Plugin，例如 Edge TTS 的 `microsoft`。舊版 `edge` 提供者 id 會作為 `microsoft` 的別名接受。 -- `providers.openai.baseUrl` 會覆寫 OpenAI TTS 端點。解析順序為設定，接著是 `OPENAI_TTS_BASE_URL`，最後是 `https://api.openai.com/v1`。 -- 當 `providers.openai.baseUrl` 指向非 OpenAI 端點時，OpenClaw 會將它視為 OpenAI 相容的 TTS 伺服器，並放寬模型/語音驗證。 +- API 金鑰會後援至 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 +- 內建語音提供者由 Plugin 擁有。如果已設定 `plugins.allow`，請納入你想使用的每個 TTS 提供者 Plugin，例如 Edge TTS 的 `microsoft`。舊版 `edge` 提供者 ID 會被接受為 `microsoft` 的別名。 +- `providers.openai.baseUrl` 會覆寫 OpenAI TTS 端點。解析順序為設定，接著是 `OPENAI_TTS_BASE_URL`，再接著是 `https://api.openai.com/v1`。 +- 當 `providers.openai.baseUrl` 指向非 OpenAI 端點時，OpenClaw 會將其視為 OpenAI 相容的 TTS 伺服器，並放寬模型/語音驗證。 --- ## Talk -Talk 模式的預設值（macOS/iOS/Android）。 +Talk 模式（macOS/iOS/Android）的預設值。 ```json5 { @@ -1382,20 +1390,20 @@ Talk 模式的預設值（macOS/iOS/Android）。 ``` - 設定多個 Talk 提供者時，`talk.provider` 必須符合 `talk.providers` 中的某個鍵。 -- 舊版扁平 Talk 鍵（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）僅供相容使用，並會自動遷移到 `talk.providers.`。 -- 語音 ID 會回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- 舊版扁平 Talk 鍵（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）僅供相容性使用，並會自動遷移至 `talk.providers.`。 +- 語音 ID 會後援至 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受純文字字串或 SecretRef 物件。 -- `ELEVENLABS_API_KEY` 備援只會在未設定 Talk API 金鑰時套用。 -- `providers.*.voiceAliases` 讓 Talk 指令可以使用易懂的名稱。 +- `ELEVENLABS_API_KEY` 後援僅在未設定 Talk API 金鑰時套用。 +- `providers.*.voiceAliases` 讓 Talk 指令能使用易懂名稱。 - `providers.mlx.modelId` 會選取 macOS 本機 MLX 輔助程式使用的 Hugging Face 儲存庫。如省略，macOS 會使用 `mlx-community/Soprano-80M-bf16`。 -- macOS MLX 播放會在存在時透過內建的 `openclaw-mlx-tts` 輔助程式執行，或使用 `PATH` 上的可執行檔；`OPENCLAW_MLX_TTS_BIN` 會覆寫開發用的輔助程式路徑。 -- `speechLocale` 會設定 iOS/macOS Talk 語音辨識使用的 BCP 47 地區設定 id。保留未設定即可使用裝置預設值。 -- `silenceTimeoutMs` 控制 Talk 模式在使用者靜默後等待多久才傳送逐字稿。未設定時會保留平台預設暫停時間窗（`macOS 和 Android 為 700 ms，iOS 為 900 ms`）。 +- macOS MLX 播放會在存在時透過內建的 `openclaw-mlx-tts` 輔助程式執行，否則使用 `PATH` 上的可執行檔；`OPENCLAW_MLX_TTS_BIN` 會覆寫開發用的輔助程式路徑。 +- `speechLocale` 設定 iOS/macOS Talk 語音辨識使用的 BCP 47 語言環境 ID。保持未設定即可使用裝置預設值。 +- `silenceTimeoutMs` 控制 Talk 模式在使用者靜默後等待多久才送出逐字稿。未設定時會保留平台預設暫停時間窗（`macOS 和 Android 為 700 ms，iOS 為 900 ms`）。 --- ## 相關 - [設定參考](/zh-TW/gateway/configuration-reference) — 所有其他設定鍵 -- [設定](/zh-TW/gateway/configuration) — 常見工作和快速設定 +- [設定](/zh-TW/gateway/configuration) — 常見工作與快速設定 - [設定範例](/zh-TW/gateway/configuration-examples) diff --git a/docs/zh-TW/gateway/config-channels.md b/docs/zh-TW/gateway/config-channels.md index 4d5fe8fc5..ed401edb5 100644 --- a/docs/zh-TW/gateway/config-channels.md +++ b/docs/zh-TW/gateway/config-channels.md @@ -1,54 +1,54 @@ --- read_when: - - 設定頻道 Plugin（驗證、存取控制、多帳號） - - 各頻道設定鍵的疑難排解 + - 設定頻道 Plugin（身分驗證、存取控制、多帳號） + - 疑難排解各通道設定鍵 - 稽核私訊政策、群組政策或提及閘控 -summary: 通道設定：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等通道的存取控制、配對與每通道金鑰 +summary: 通道設定：涵蓋 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的存取控制、配對與每個通道的金鑰 title: 設定 — 頻道 x-i18n: - generated_at: "2026-05-03T21:32:03Z" + generated_at: "2026-05-04T02:44:23Z" model: gpt-5.5 provider: openai - source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c + source_hash: 57dcc0b5148324ea6fdee51b7b6e97ec7bd7dc3ca89518ab0816fe4172feefbc source_path: gateway/config-channels.md workflow: 16 --- -每個通道的設定鍵位於 `channels.*` 底下。涵蓋 DM 和群組存取、多帳號設定、提及門檻，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他內建通道 Plugin 的個別通道鍵。 +每個通道的設定鍵位於 `channels.*` 底下。涵蓋 DM 與群組存取、多帳號設定、提及閘控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他內建通道 Plugin 的每通道鍵。 -如需 agents、工具、Gateway 執行階段和其他頂層鍵，請參閱 +若要設定代理、工具、Gateway 執行階段與其他頂層鍵，請參閱 [設定參考](/zh-TW/gateway/configuration-reference)。 ## 通道 -每個通道會在其設定區段存在時自動啟動（除非 `enabled: false`）。 +每個通道都會在其設定區段存在時自動啟動（除非 `enabled: false`）。 -### DM 和群組存取 +### DM 與群組存取 -所有通道都支援 DM 政策和群組政策： +所有通道都支援 DM 政策與群組政策： -| DM 政策 | 行為 | +| DM 政策 | 行為 | | ------------------- | --------------------------------------------------------------- | -| `pairing` (default) | 未知傳送者會取得一次性配對碼；擁有者必須核准 | -| `allowlist` | 只允許 `allowFrom`（或已配對允許儲存區）中的傳送者 | -| `open` | 允許所有傳入 DM（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有傳入 DM | +| `pairing`（預設） | 未知寄件者會取得一次性配對碼；擁有者必須核准 | +| `allowlist` | 僅允許 `allowFrom`（或已配對允許儲存區）中的寄件者 | +| `open` | 允許所有傳入 DM（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有傳入 DM | -| 群組政策 | 行為 | -| --------------------- | -------------------------------------------------------- | -| `allowlist` (default) | 只允許符合已設定允許清單的群組 | -| `open` | 略過群組允許清單（提及門檻仍然適用） | +| 群組政策 | 行為 | +| --------------------- | ------------------------------------------------------ | +| `allowlist`（預設） | 僅允許符合已設定允許清單的群組 | +| `open` | 略過群組允許清單（提及閘控仍會套用） | | `disabled` | 封鎖所有群組/聊天室訊息 | -`channels.defaults.groupPolicy` 會在供應商的 `groupPolicy` 未設定時設定預設值。 +`channels.defaults.groupPolicy` 會在提供者的 `groupPolicy` 未設定時指定預設值。 配對碼會在 1 小時後過期。待處理的 DM 配對請求上限為**每個通道 3 個**。 -如果供應商區塊完全缺失（沒有 `channels.`），執行階段群組政策會退回到 `allowlist`（失敗時關閉），並顯示啟動警告。 +如果提供者區塊完全缺失（沒有 `channels.`），執行階段群組政策會回退到 `allowlist`（失敗關閉），並在啟動時發出警告。 ### 通道模型覆寫 -使用 `channels.modelByChannel` 將特定通道 ID 固定到某個模型。值可接受 `provider/model` 或已設定的模型別名。當工作階段尚未有模型覆寫時（例如透過 `/model` 設定），通道對應會套用。 +使用 `channels.modelByChannel` 將特定通道 ID 固定到某個模型。值可接受 `provider/model` 或已設定的模型別名。當工作階段尚未有模型覆寫時（例如透過 `/model` 設定），會套用通道對應。 ```json5 { @@ -69,9 +69,9 @@ x-i18n: } ``` -### 通道預設值和 Heartbeat +### 通道預設值與 Heartbeat -使用 `channels.defaults` 在各供應商之間共享群組政策和 Heartbeat 行為： +使用 `channels.defaults` 設定跨提供者共用的群組政策與 Heartbeat 行為： ```json5 { @@ -89,15 +89,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：供應商層級的 `groupPolicy` 未設定時的後備群組政策。 -- `channels.defaults.contextVisibility`：所有通道的預設補充脈絡可見性模式。值：`all`（預設，包含所有引用/執行緒/歷史脈絡）、`allowlist`（只包含來自允許清單傳送者的脈絡）、`allowlist_quote`（與 allowlist 相同，但保留明確的引用/回覆脈絡）。個別通道覆寫：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：提供者層級的 `groupPolicy` 未設定時的後援群組政策。 +- `channels.defaults.contextVisibility`：所有通道的預設補充上下文可見性模式。值：`all`（預設，包含所有引用/討論串/歷史上下文）、`allowlist`（僅包含允許清單寄件者的上下文）、`allowlist_quote`（與 allowlist 相同，但保留明確的引用/回覆上下文）。每通道覆寫：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在 Heartbeat 輸出中包含健康的通道狀態。 - `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 輸出中包含降級/錯誤狀態。 - `channels.defaults.heartbeat.useIndicator`：呈現精簡指示器樣式的 Heartbeat 輸出。 ### WhatsApp -WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的工作階段存在時，它會自動啟動。 +WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的工作階段存在時會自動啟動。 ```json5 { @@ -135,7 +135,7 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的 } ``` - + ```json5 { @@ -153,10 +153,10 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的 } ``` -- 外送命令預設使用 `default` 帳號（如果存在）；否則使用第一個已設定的帳號 ID（排序後）。 -- 選用的 `channels.whatsapp.defaultAccount` 會在符合已設定帳號 ID 時覆寫該後備預設帳號選擇。 -- 舊版單帳號 Baileys auth 目錄會由 `openclaw doctor` 遷移到 `whatsapp/default`。 -- 個別帳號覆寫：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 若存在 `default`，傳出命令預設使用帳號 `default`；否則使用第一個已設定的帳號 ID（排序後）。 +- 選用的 `channels.whatsapp.defaultAccount` 會在符合已設定帳號 ID 時覆寫該後援預設帳號選擇。 +- 舊版單帳號 Baileys 驗證目錄會由 `openclaw doctor` 遷移到 `whatsapp/default`。 +- 每帳號覆寫：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -215,13 +215,13 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的 } ``` -- Bot 權杖：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（僅一般檔案；拒絕符號連結），預設帳號則以 `TELEGRAM_BOT_TOKEN` 作為後備。 -- `apiRoot` 只是 Telegram Bot API 根路徑。使用 `https://api.telegram.org` 或你的自架/代理根路徑，不要使用 `https://api.telegram.org/bot`；`openclaw doctor --fix` 會移除意外尾隨的 `/bot` 後綴。 +- Bot 權杖：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（僅限一般檔案；拒絕符號連結），預設帳號會以 `TELEGRAM_BOT_TOKEN` 作為後援。 +- `apiRoot` 僅是 Telegram Bot API 根目錄。請使用 `https://api.telegram.org` 或你的自架/Proxy 根目錄，不要使用 `https://api.telegram.org/bot`；`openclaw doctor --fix` 會移除意外加上的尾端 `/bot` 後綴。 - 選用的 `channels.telegram.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。 -- 在多帳號設定（2 個以上帳號 ID）中，請設定明確預設值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免後備路由；缺失或無效時，`openclaw doctor` 會發出警告。 +- 在多帳號設定（2 個以上帳號 ID）中，請設定明確預設值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免後援路由；缺失或無效時，`openclaw doctor` 會發出警告。 - `configWrites: false` 會封鎖由 Telegram 發起的設定寫入（超級群組 ID 遷移、`/config set|unset`）。 -- 含有 `type: "acp"` 的頂層 `bindings[]` 項目會為論壇主題設定持久 ACP 繫結（在 `match.peer.id` 使用標準 `chatId:topic:topicId`）。欄位語意在 [ACP Agents](/zh-TW/tools/acp-agents#persistent-channel-bindings) 中共用。 -- Telegram 串流預覽使用 `sendMessage` + `editMessageText`（可在直接和群組聊天中運作）。 +- 帶有 `type: "acp"` 的頂層 `bindings[]` 項目會為論壇主題設定持久 ACP 繫結（在 `match.peer.id` 中使用標準 `chatId:topic:topicId`）。欄位語意在 [ACP 代理](/zh-TW/tools/acp-agents#persistent-channel-bindings) 中共用。 +- Telegram 串流預覽使用 `sendMessage` + `editMessageText`（可在直接聊天與群組聊天中運作）。 - 重試政策：請參閱[重試政策](/zh-TW/concepts/retry)。 ### Discord @@ -327,38 +327,38 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的 } ``` -- 權杖：`channels.discord.token`，預設帳號會以 `DISCORD_BOT_TOKEN` 作為備援。 -- 提供明確 Discord `token` 的直接對外呼叫會使用該權杖進行呼叫；帳號重試/政策設定仍來自作用中執行階段快照中選取的帳號。 -- 可選的 `channels.discord.defaultAccount` 在符合已設定帳號 ID 時，會覆寫預設帳號選擇。 -- 使用 `user:`（DM）或 `channel:`（公會頻道）作為傳送目標；裸數字 ID 會被拒絕。 -- 公會 slug 會轉為小寫並將空格替換為 `-`；頻道鍵使用已 slug 化的名稱（不含 `#`）。建議優先使用公會 ID。 -- 預設會忽略由機器人撰寫的訊息。`allowBots: true` 會啟用這些訊息；使用 `allowBots: "mentions"` 則只接受提及該機器人的機器人訊息（自己的訊息仍會被篩除）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及頻道覆寫）會丟棄提及其他使用者或角色、但未提及該機器人的訊息（不含 @everyone/@here）。 -- `channels.discord.mentionAliases` 會在傳送前將穩定的對外 `@handle` 文字對應到 Discord 使用者 ID，因此即使暫時目錄快取為空，也能以確定方式提及已知隊友。個別帳號覆寫位於 `channels.discord.accounts..mentionAliases`。 -- `maxLinesPerMessage`（預設 17）即使在 2000 字元以內，也會拆分過高的訊息。 +- Token：`channels.discord.token`，預設帳戶可使用 `DISCORD_BOT_TOKEN` 作為備援。 +- 提供明確 Discord `token` 的直接對外呼叫會使用該 Token 進行呼叫；帳戶重試/政策設定仍來自作用中執行階段快照中的所選帳戶。 +- 選用的 `channels.discord.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選擇。 +- 使用 `user:`（DM）或 `channel:`（伺服器頻道）作為傳送目標；不接受裸數字 ID。 +- 伺服器 slug 為小寫，空格會替換為 `-`；頻道鍵使用 slug 化名稱（不含 `#`）。建議使用伺服器 ID。 +- 預設會忽略機器人作者的訊息。`allowBots: true` 會啟用它們；使用 `allowBots: "mentions"` 則只接受提及該機器人的機器人訊息（自己的訊息仍會被過濾）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及頻道覆寫）會捨棄提及其他使用者或角色、但未提及該機器人的訊息（排除 @everyone/@here）。 +- `channels.discord.mentionAliases` 會在傳送前將穩定的對外 `@handle` 文字對應到 Discord 使用者 ID，因此即使暫時性目錄快取為空，也能確定性地提及已知隊友。每個帳戶的覆寫位於 `channels.discord.accounts..mentionAliases` 下。 +- `maxLinesPerMessage`（預設 17）即使在低於 2000 字元時也會拆分較高的訊息。 - `channels.discord.threadBindings` 控制 Discord 執行緒綁定路由： - - `enabled`：Discord 對執行緒綁定工作階段功能的覆寫（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及綁定傳送/路由） - - `idleHours`：Discord 對閒置自動取消聚焦時數的覆寫（`0` 會停用） - - `maxAgeHours`：Discord 對硬性最大時數的覆寫（`0` 會停用） - - `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 執行緒產生自動建立/綁定執行緒的開關（預設：`true`） - - `defaultSpawnContext`：執行緒綁定產生的原生子代理程式情境（預設為 `"fork"`） -- 具有 `type: "acp"` 的頂層 `bindings[]` 項目會為頻道和執行緒設定持久 ACP 綁定（在 `match.peer.id` 中使用頻道/執行緒 ID）。欄位語意共用於 [ACP 代理程式](/zh-TW/tools/acp-agents#persistent-channel-bindings)。 -- `channels.discord.ui.components.accentColor` 設定 Discord components v2 容器的強調色。 -- `channels.discord.voice` 啟用 Discord 語音頻道對話，以及可選的自動加入 + LLM + TTS 覆寫。純文字 Discord 設定預設會關閉語音；設定 `channels.discord.voice.enabled=true` 以選擇啟用。 -- `channels.discord.voice.model` 可選擇覆寫 Discord 語音頻道回覆所使用的 LLM 模型。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 會傳遞至 `@discordjs/voice` DAVE 選項（預設為 `true` 和 `24`）。 + - `enabled`：針對執行緒綁定工作階段功能的 Discord 覆寫（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及綁定的傳送/路由） + - `idleHours`：以小時計算的閒置自動取消聚焦 Discord 覆寫（`0` 會停用） + - `maxAgeHours`：以小時計算的硬性最長存續時間 Discord 覆寫（`0` 會停用） + - `spawnSessions`：`sessions_spawn({ thread: true })` 與 ACP 執行緒衍生自動建立/綁定執行緒的開關（預設：`true`） + - `defaultSpawnContext`：執行緒綁定衍生的原生子代理程式情境（預設為 `"fork"`） +- 具有 `type: "acp"` 的頂層 `bindings[]` 項目會為頻道和執行緒設定持久 ACP 綁定（在 `match.peer.id` 中使用頻道/執行緒 ID）。欄位語意在 [ACP 代理程式](/zh-TW/tools/acp-agents#persistent-channel-bindings) 中共用。 +- `channels.discord.ui.components.accentColor` 設定 Discord 元件 v2 容器的強調色。 +- `channels.discord.voice` 啟用 Discord 語音頻道對話，以及選用的自動加入 + LLM + TTS 覆寫。純文字 Discord 設定預設會關閉語音；設定 `channels.discord.voice.enabled=true` 即可選擇啟用。 +- `channels.discord.voice.model` 可選擇性覆寫用於 Discord 語音頻道回應的 LLM 模型。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 會傳遞至 `@discordjs/voice` DAVE 選項（預設分別為 `true` 和 `24`）。 - `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自動加入嘗試的初始 `@discordjs/voice` Ready 等待時間（預設為 `30000`）。 -- `channels.discord.voice.reconnectGraceMs` 控制已中斷連線的語音工作階段可在 OpenClaw 銷毀前花多久時間進入重新連線訊號狀態（預設為 `15000`）。 -- OpenClaw 另外會在重複解密失敗後，透過離開/重新加入語音工作階段來嘗試語音接收復原。 -- `channels.discord.streaming` 是標準串流模式鍵。舊版 `streamMode` 和布林值 `streaming` 會自動遷移。 -- `channels.discord.autoPresence` 會將執行階段可用性對應到機器人狀態（healthy => online、degraded => idle、exhausted => dnd），並允許可選的狀態文字覆寫。 +- `channels.discord.voice.reconnectGraceMs` 控制已中斷連線的語音工作階段在 OpenClaw 銷毀它之前，可花多久時間進入重新連線訊號狀態（預設為 `15000`）。 +- OpenClaw 也會在重複解密失敗後，透過離開/重新加入語音工作階段來嘗試語音接收復原。 +- `channels.discord.streaming` 是正式的串流模式鍵。舊版 `streamMode` 和布林值 `streaming` 會自動遷移。 +- `channels.discord.autoPresence` 會將執行階段可用性對應至機器人狀態（healthy => online、degraded => idle、exhausted => dnd），並允許選用的狀態文字覆寫。 - `channels.discord.dangerouslyAllowNameMatching` 會重新啟用可變名稱/標籤比對（緊急相容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 核准傳送和核准者授權。 - - `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當可從 `approvers` 或 `commands.ownerAllowFrom` 解析核准者時，exec 核准會啟用。 - - `approvers`：允許核准 exec 要求的 Discord 使用者 ID。省略時會退回使用 `commands.ownerAllowFrom`。 - - `agentFilter`：可選的代理程式 ID 允許清單。省略時會轉送所有代理程式的核准。 - - `sessionFilter`：可選的工作階段鍵模式（子字串或 regex）。 - - `target`：傳送核准提示的位置。`"dm"`（預設）傳送至核准者 DM，`"channel"` 傳送至來源頻道，`"both"` 兩者都傳送。當 target 包含 `"channel"` 時，按鈕只能由已解析的核准者使用。 +- `channels.discord.execApprovals`：Discord 原生 exec 核准傳送與核准者授權。 + - `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當核准者可從 `approvers` 或 `commands.ownerAllowFrom` 解析時，exec 核准就會啟用。 + - `approvers`：允許核准 exec 請求的 Discord 使用者 ID。省略時會退回使用 `commands.ownerAllowFrom`。 + - `agentFilter`：選用的代理程式 ID 允許清單。省略即可轉送所有代理程式的核准。 + - `sessionFilter`：選用的工作階段鍵模式（子字串或正規表示式）。 + - `target`：核准提示的傳送位置。`"dm"`（預設）會傳送給核准者 DM，`"channel"` 會傳送到來源頻道，`"both"` 會兩者都傳送。當目標包含 `"channel"` 時，按鈕僅可由已解析的核准者使用。 - `cleanupAfterResolve`：為 `true` 時，會在核准、拒絕或逾時後刪除核准 DM。 **反應通知模式：** `off`（無）、`own`（機器人的訊息，預設）、`all`（所有訊息）、`allowlist`（來自所有訊息上的 `guilds..users`）。 @@ -392,9 +392,9 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的 } ``` -- 服務帳號 JSON：行內（`serviceAccount`）或檔案式（`serviceAccountFile`）。 -- 也支援服務帳號 SecretRef（`serviceAccountRef`）。 -- 環境備援：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 服務帳戶 JSON：行內（`serviceAccount`）或檔案型（`serviceAccountFile`）。 +- 也支援服務帳戶 SecretRef（`serviceAccountRef`）。 +- 環境變數備援：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 使用 `spaces/` 或 `users/` 作為傳送目標。 - `channels.googlechat.dangerouslyAllowNameMatching` 會重新啟用可變電子郵件主體比對（緊急相容模式）。 @@ -468,43 +468,44 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的 } ``` -- **Socket mode** 需要同時有 `botToken` 和 `appToken`（預設帳號環境備援為 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（在根層或個別帳號中）。 -- `socketMode` 會將 Slack SDK Socket Mode 傳輸調校傳遞至公開 Bolt receiver API。僅在調查 ping/pong 逾時或過期 websocket 行為時使用。 +- **Socket mode** 需要同時有 `botToken` 和 `appToken`（預設帳戶環境變數備援為 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（位於根層級或每個帳戶）。 +- `socketMode` 會將 Slack SDK Socket Mode 傳輸調校傳遞給公開 Bolt 接收器 API。僅在調查 ping/pong 逾時或過期 websocket 行為時使用它。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受純文字 字串或 SecretRef 物件。 -- Slack 帳號快照會公開個別憑證來源/狀態欄位，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 中的 - `signingSecretStatus`。`configured_unavailable` 表示該帳號已透過 SecretRef - 設定，但目前的命令/執行階段路徑無法解析祕密值。 -- `configWrites: false` 會阻止由 Slack 發起的設定寫入。 -- 可選的 `channels.slack.defaultAccount` 在符合已設定帳號 ID 時，會覆寫預設帳號選擇。 -- `channels.slack.streaming.mode` 是標準 Slack 串流模式鍵。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生串流傳輸。舊版 `streamMode`、布林值 `streaming` 和 `nativeStreaming` 會自動遷移。 +- Slack 帳戶快照會公開每個憑證的來源/狀態欄位，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式中的 + `signingSecretStatus`。`configured_unavailable` 表示帳戶是 + 透過 SecretRef 設定，但目前的命令/執行階段路徑無法 + 解析密鑰值。 +- `configWrites: false` 會封鎖由 Slack 發起的設定寫入。 +- 選用的 `channels.slack.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選擇。 +- `channels.slack.streaming.mode` 是正式的 Slack 串流模式鍵。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生串流傳輸。舊版 `streamMode`、布林值 `streaming` 和 `nativeStreaming` 會自動遷移。 - 使用 `user:`（DM）或 `channel:` 作為傳送目標。 **反應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。 -**執行緒工作階段隔離：** `thread.historyScope` 為個別執行緒（預設）或跨頻道共用。`thread.inheritParent` 會將父頻道逐字稿複製到新執行緒。 +**執行緒工作階段隔離：** `thread.historyScope` 為每個執行緒（預設）或跨頻道共用。`thread.inheritParent` 會將父頻道轉錄複製到新執行緒。 -- Slack 原生串流加上 Slack 助理風格的「is typing...」執行緒狀態需要回覆執行緒目標。頂層 DM 預設保持在執行緒外，因此仍可透過 Slack 草稿張貼並編輯預覽來串流，而不是顯示執行緒風格的原生串流/狀態預覽。 -- `typingReaction` 會在回覆執行期間，向傳入的 Slack 訊息加入暫時反應，並在完成時移除。請使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 核准傳送和核准者授權。與 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 使用者 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生串流加上 Slack 助理風格的「is typing...」執行緒狀態需要回覆執行緒目標。頂層 DM 預設保持非執行緒，因此它們仍可透過 Slack 草稿發文並編輯預覽進行串流，而不是顯示執行緒風格的原生串流/狀態預覽。 +- `typingReaction` 會在回覆執行期間，將暫時性反應新增到傳入的 Slack 訊息，然後在完成時移除。請使用 Slack emoji 短代碼，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 核准傳送與核准者授權。結構描述與 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 使用者 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 動作群組 | 預設 | 備註 | +| 動作群組 | 預設 | 備註 | | ------------ | ------- | ---------------------- | -| reactions | enabled | 反應 + 列出反應 | -| messages | enabled | 讀取/傳送/編輯/刪除 | -| pins | enabled | 釘選/取消釘選/列出 | -| memberInfo | enabled | 成員資訊 | -| emojiList | enabled | 自訂 emoji 清單 | +| reactions | 已啟用 | 反應 + 列出反應 | +| messages | 已啟用 | 讀取/傳送/編輯/刪除 | +| pins | 已啟用 | 釘選/取消釘選/列出 | +| memberInfo | 已啟用 | 成員資訊 | +| emojiList | 已啟用 | 自訂 emoji 清單 | ### Mattermost -Mattermost 在目前 OpenClaw 版本中作為 bundled Plugin 隨附。較舊或 +Mattermost 在目前的 OpenClaw 版本中以 bundled Plugin 形式提供。較舊或 自訂建置可以使用 -`openclaw plugins install @openclaw/mattermost` 安裝目前的 npm package。固定版本前，請查看 +`openclaw plugins install @openclaw/mattermost` 安裝目前的 npm 套件。固定版本前，請先查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) -取得目前的 dist-tags。 +以確認目前的 dist-tags。 ```json5 { @@ -534,18 +535,18 @@ Mattermost 在目前 OpenClaw 版本中作為 bundled Plugin 隨附。較舊或 } ``` -聊天模式：`oncall`（在 @ 提及時回應，預設）、`onmessage`（每則訊息）、`onchar`（以觸發前綴開頭的訊息）。 +聊天模式：`oncall`（在 @-提及時回應，預設）、`onmessage`（每則訊息）、`onchar`（以觸發前綴開頭的訊息）。 啟用 Mattermost 原生命令時： -- `commands.callbackPath` 必須是路徑（例如 `/api/channels/mattermost/command`），不是完整 URL。 -- `commands.callbackUrl` 必須解析到 OpenClaw gateway 端點，且 Mattermost 伺服器必須可連線。 -- 原生斜線命令回呼會使用 Mattermost 在斜線命令註冊期間傳回的每個命令 token 進行驗證。如果註冊失敗或沒有啟用任何命令，OpenClaw 會以 `Unauthorized: invalid command token.` 拒絕回呼。 -- 對於私有/tailnet/內部回呼主機，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回呼主機/網域。請使用主機/網域值，不要使用完整 URL。 -- `channels.mattermost.configWrites`：允許或拒絕 Mattermost 發起的設定寫入。 -- `channels.mattermost.requireMention`：在頻道中回覆前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：每個頻道的提及門控覆寫（`"*"` 表示預設）。 -- 可選的 `channels.mattermost.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。 +- `commands.callbackPath` 必須是路徑（例如 `/api/channels/mattermost/command`），而不是完整 URL。 +- `commands.callbackUrl` 必須解析到 OpenClaw gateway 端點，且可由 Mattermost 伺服器存取。 +- 原生斜線命令回呼會使用 Mattermost 在註冊斜線命令時傳回的逐命令權杖進行驗證。如果註冊失敗或沒有啟用任何命令，OpenClaw 會以 `Unauthorized: invalid command token.` 拒絕回呼。 +- 對於私有、tailnet 或內部回呼主機，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含該回呼主機/網域。請使用主機/網域值，而不是完整 URL。 +- `channels.mattermost.configWrites`：允許或拒絕由 Mattermost 發起的設定寫入。 +- `channels.mattermost.requireMention`：要求在頻道中回覆前必須有 `@mention`。 +- `channels.mattermost.groups..requireMention`：逐頻道的提及門檻覆寫（`"*"` 表示預設）。 +- 選用的 `channels.mattermost.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。 ### Signal @@ -566,15 +567,15 @@ Mattermost 在目前 OpenClaw 版本中作為 bundled Plugin 隨附。較舊或 } ``` -**回應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。 +**反應通知模式：**`off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。 -- `channels.signal.account`：將頻道啟動固定到特定的 Signal 帳號身分。 -- `channels.signal.configWrites`：允許或拒絕 Signal 發起的設定寫入。 -- 可選的 `channels.signal.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。 +- `channels.signal.account`：將頻道啟動固定到特定 Signal 帳號身分。 +- `channels.signal.configWrites`：允許或拒絕由 Signal 發起的設定寫入。 +- 選用的 `channels.signal.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。 ### BlueBubbles -BlueBubbles 是建議的 iMessage 路徑（由 plugin 支援，設定於 `channels.bluebubbles` 之下）。 +BlueBubbles 是建議的 iMessage 路徑（由 Plugin 支援，設定於 `channels.bluebubbles` 下）。 ```json5 { @@ -589,9 +590,9 @@ BlueBubbles 是建議的 iMessage 路徑（由 plugin 支援，設定於 `channe } ``` -- 這裡涵蓋的核心 key path：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可選的 `channels.bluebubbles.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。 -- 頂層 `bindings[]` 項目搭配 `type: "acp"` 可將 BlueBubbles 對話繫結到持續性 ACP 工作階段。在 `match.peer.id` 中使用 BlueBubbles handle 或目標字串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP Agents](/zh-TW/tools/acp-agents#persistent-channel-bindings)。 +- 此處涵蓋的核心鍵路徑：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 +- 選用的 `channels.bluebubbles.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。 +- 具有 `type: "acp"` 的頂層 `bindings[]` 項目可將 BlueBubbles 對話繫結到持久 ACP 工作階段。請在 `match.peer.id` 中使用 BlueBubbles handle 或目標字串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP 代理](/zh-TW/tools/acp-agents#persistent-channel-bindings)。 - 完整的 BlueBubbles 頻道設定記錄於 [BlueBubbles](/zh-TW/channels/bluebubbles)。 ### iMessage @@ -620,17 +621,17 @@ OpenClaw 會產生 `imsg rpc`（透過 stdio 的 JSON-RPC）。不需要 daemon } ``` -- 可選的 `channels.imessage.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。 +- 選用的 `channels.imessage.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。 -- 需要 Messages DB 的完整磁碟存取權。 -- 建議使用 `chat_id:` 目標。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH wrapper；設定 `remoteHost`（`host` 或 `user@host`）以擷取 SCP 附件。 +- 需要對 Messages DB 授予完整磁碟存取權。 +- 優先使用 `chat_id:` 目標。使用 `imsg chats --limit 20` 列出聊天。 +- `cliPath` 可以指向 SSH 包裝器；設定 `remoteHost`（`host` 或 `user@host`）以擷取 SCP 附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 會限制傳入附件路徑（預設：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用嚴格的 host-key 檢查，因此請確認轉送主機金鑰已存在於 `~/.ssh/known_hosts`。 -- `channels.imessage.configWrites`：允許或拒絕 iMessage 發起的設定寫入。 -- 頂層 `bindings[]` 項目搭配 `type: "acp"` 可將 iMessage 對話繫結到持續性 ACP 工作階段。在 `match.peer.id` 中使用正規化 handle 或明確聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP Agents](/zh-TW/tools/acp-agents#persistent-channel-bindings)。 +- SCP 使用嚴格主機金鑰檢查，因此請確保轉送主機金鑰已存在於 `~/.ssh/known_hosts`。 +- `channels.imessage.configWrites`：允許或拒絕由 iMessage 發起的設定寫入。 +- 具有 `type: "acp"` 的頂層 `bindings[]` 項目可將 iMessage 對話繫結到持久 ACP 工作階段。請在 `match.peer.id` 中使用正規化 handle 或明確的聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP 代理](/zh-TW/tools/acp-agents#persistent-channel-bindings)。 - + ```bash #!/usr/bin/env bash @@ -641,7 +642,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由 plugin 支援，並設定於 `channels.matrix` 之下。 +Matrix 由 Plugin 支援，並設定於 `channels.matrix` 下。 ```json5 { @@ -671,25 +672,25 @@ Matrix 由 plugin 支援，並設定於 `channels.matrix` 之下。 } ``` -- Token 驗證使用 `accessToken`；密碼驗證使用 `userId` + `password`。 +- 權杖驗證使用 `accessToken`；密碼驗證使用 `userId` + `password`。 - `channels.matrix.proxy` 會透過明確的 HTTP(S) proxy 路由 Matrix HTTP 流量。具名帳號可使用 `channels.matrix.accounts..proxy` 覆寫。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允許私有/內部 homeserver。`proxy` 和這個網路 opt-in 是獨立控制項。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允許私有/內部 homeserver。`proxy` 與此網路選擇加入是獨立控制項。 - `channels.matrix.defaultAccount` 會在多帳號設定中選取偏好的帳號。 -- `channels.matrix.autoJoin` 預設為 `off`，因此受邀房間和新的 DM 樣式邀請會被忽略，直到你設定 `autoJoin: "allowlist"` 搭配 `autoJoinAllowlist`，或設定 `autoJoin: "always"`。 +- `channels.matrix.autoJoin` 預設為 `off`，因此受邀房間與新的 DM 樣式邀請都會被忽略，直到你設定 `autoJoin: "allowlist"` 搭配 `autoJoinAllowlist`，或設定 `autoJoin: "always"`。 - `channels.matrix.execApprovals`：Matrix 原生 exec 核准傳遞與核准者授權。 - `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當可從 `approvers` 或 `commands.ownerAllowFrom` 解析核准者時，exec 核准會啟用。 - - `approvers`：允許核准 exec 要求的 Matrix 使用者 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可選的代理程式 ID allowlist。省略時會轉送所有代理程式的核准。 - - `sessionFilter`：可選的工作階段 key 模式（substring 或 regex）。 - - `target`：核准提示的傳送位置。`"dm"`（預設）、`"channel"`（來源房間）或 `"both"`。 - - 每帳號覆寫：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix DM 如何分組為工作階段：`per-user`（預設）會依路由後的 peer 共用，而 `per-room` 會隔離每個 DM 房間。 -- Matrix 狀態探測和即時目錄查詢會使用與執行階段流量相同的 proxy 原則。 -- 完整的 Matrix 設定、目標規則和設定範例記錄於 [Matrix](/zh-TW/channels/matrix)。 + - `approvers`：允許核准 exec 請求的 Matrix 使用者 ID（例如 `@owner:example.org`）。 + - `agentFilter`：選用代理 ID allowlist。省略時會轉送所有代理的核准。 + - `sessionFilter`：選用工作階段鍵模式（子字串或 regex）。 + - `target`：傳送核准提示的位置。`"dm"`（預設）、`"channel"`（來源房間）或 `"both"`。 + - 逐帳號覆寫：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix DM 如何分組成工作階段：`per-user`（預設）依路由對等端共用，而 `per-room` 會隔離每個 DM 房間。 +- Matrix 狀態探測與即時目錄查詢使用與執行階段流量相同的 proxy 原則。 +- 完整的 Matrix 設定、目標規則與設定範例記錄於 [Matrix](/zh-TW/channels/matrix)。 ### Microsoft Teams -Microsoft Teams 由 plugin 支援，並設定於 `channels.msteams` 之下。 +Microsoft Teams 由 Plugin 支援，並設定於 `channels.msteams` 下。 ```json5 { @@ -704,12 +705,12 @@ Microsoft Teams 由 plugin 支援，並設定於 `channels.msteams` 之下。 } ``` -- 這裡涵蓋的核心 key path：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 設定（認證、webhook、DM/群組原則、每個 team/每個頻道覆寫）記錄於 [Microsoft Teams](/zh-TW/channels/msteams)。 +- 此處涵蓋的核心鍵路徑：`channels.msteams`、`channels.msteams.configWrites`。 +- 完整的 Teams 設定（認證、Webhook、DM/群組原則、逐團隊/逐頻道覆寫）記錄於 [Microsoft Teams](/zh-TW/channels/msteams)。 ### IRC -IRC 由 plugin 支援，並設定於 `channels.irc` 之下。 +IRC 由 Plugin 支援，並設定於 `channels.irc` 下。 ```json5 { @@ -730,9 +731,9 @@ IRC 由 plugin 支援，並設定於 `channels.irc` 之下。 } ``` -- 這裡涵蓋的核心 key path：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可選的 `channels.irc.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。 -- 完整的 IRC 頻道設定（host/port/TLS/頻道/allowlist/提及門控）記錄於 [IRC](/zh-TW/channels/irc)。 +- 此處涵蓋的核心鍵路徑：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 +- 選用的 `channels.irc.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。 +- 完整的 IRC 頻道設定（主機/連接埠/TLS/頻道/allowlist/提及門檻）記錄於 [IRC](/zh-TW/channels/irc)。 ### 多帳號（所有頻道） @@ -758,33 +759,35 @@ IRC 由 plugin 支援，並設定於 `channels.irc` 之下。 ``` - 省略 `accountId` 時會使用 `default`（CLI + 路由）。 -- Env token 只套用到 **default** 帳號。 -- 基礎頻道設定會套用到所有帳號，除非每個帳號另有覆寫。 -- 使用 `bindings[].match.accountId` 將每個帳號路由到不同代理程式。 -- 如果你透過 `openclaw channels add`（或頻道 onboarding）新增非預設帳號，而目前仍使用單帳號頂層頻道設定，OpenClaw 會先將帳號作用域的頂層單帳號值提升到頻道帳號 map，讓原始帳號繼續運作。多數頻道會將它們移入 `channels..accounts.default`；Matrix 則可保留現有相符的具名/預設目標。 -- 現有的僅頻道繫結（沒有 `accountId`）會繼續符合預設帳號；帳號作用域繫結仍為可選。 -- `openclaw doctor --fix` 也會修復混合形狀，方法是將帳號作用域的頂層單帳號值移入該頻道所選的提升帳號。多數頻道使用 `accounts.default`；Matrix 則可保留現有相符的具名/預設目標。 +- Env 權杖只會套用到**預設**帳號。 +- 基礎頻道設定會套用到所有帳號，除非逐帳號覆寫。 +- 使用 `bindings[].match.accountId` 將每個帳號路由到不同代理。 +- 如果你透過 `openclaw channels add`（或頻道 onboarding）新增非預設帳號，同時仍使用單帳號頂層頻道設定，OpenClaw 會先將帳號範圍的頂層單帳號值提升到頻道帳號對應表，使原始帳號繼續運作。大多數頻道會將它們移入 `channels..accounts.default`；Matrix 則可改為保留現有相符的具名/預設目標。 +- 現有僅限頻道的繫結（沒有 `accountId`）會繼續符合預設帳號；帳號範圍的繫結仍為選用。 +- `openclaw doctor --fix` 也會透過將帳號範圍的頂層單帳號值移入該頻道所選的已提升帳號，來修復混合形狀。大多數頻道使用 `accounts.default`；Matrix 則可改為保留現有相符的具名/預設目標。 -### 其他 plugin 頻道 +### 其他 Plugin 頻道 -許多 plugin 頻道設定為 `channels.`，並記錄於各自的專用頻道頁面（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +許多 Plugin 頻道會設定為 `channels.`，並記錄於其專用頻道頁面（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 請參閱完整頻道索引：[頻道](/zh-TW/channels)。 -### 群組聊天提及門控 +### 群組聊天提及門檻 -群組訊息預設為 **要求提及**（metadata 提及或安全 regex 模式）。適用於 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群組聊天。 +群組訊息預設為**要求提及**（中繼資料提及或安全的 regex 模式）。適用於 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群組聊天。 -可見回覆會另行控制。群組/頻道房間預設為 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍會處理該輪次，但一般最終回覆會保持私密，可見房間輸出需要 `message(action=send)`。只有在你想要舊版行為，也就是一般回覆會貼回房間時，才設定 `"automatic"`。若要將相同的僅工具可見回覆行為也套用到直接聊天，請設定 `messages.visibleReplies: "message_tool"`；Codex harness 也會將該僅工具行為作為未設定的直接聊天預設。 +可見回覆由另一組設定控制。群組/頻道房間預設為 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍會處理該輪對話，但一般最終回覆會保持私密，可見的房間輸出需要 `message(action=send)`。只有在你想要舊有行為，也就是一般回覆會張貼回房間時，才設定 `"automatic"`。若也要將相同的僅工具可見回覆行為套用到直接聊天，請設定 `messages.visibleReplies: "message_tool"`；Codex harness 也會將該僅工具行為作為其未設定的直接聊天預設。 -如果訊息工具在作用中的工具原則下不可用，OpenClaw 會退回自動可見回覆，而不是靜默抑制回應。`openclaw doctor` 會警告此不相符狀態。 +僅工具可見回覆需要能可靠呼叫工具的模型/執行階段。如果工作階段記錄顯示 assistant 文字帶有 `didSendViaMessagingTool: false`，表示模型產生了私密最終答案，而不是呼叫 message 工具。請改用該頻道的更強工具呼叫模型，或設定 `messages.groupChat.visibleReplies: "automatic"` 以還原舊有可見最終回覆。 -Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署中停用檔案監看或設定重新載入時才需要重新啟動。 +如果 message 工具在作用中的工具原則下不可用，OpenClaw 會退回到自動可見回覆，而不是靜默抑制回應。`openclaw doctor` 會針對此不相符狀況發出警告。 + +gateway 會在檔案儲存後熱重載 `messages` 設定。只有在部署中停用檔案監看或設定重載時，才需要重新啟動。 **提及類型：** -- **Metadata 提及**：原生平台 @-mentions。在 WhatsApp 自我聊天模式中會忽略。 +- **中繼資料提及**：原生平台 @-提及。在 WhatsApp 自我聊天模式中會被忽略。 - **文字模式**：`agents.list[].groupChat.mentionPatterns` 中的安全 regex 模式。無效模式和不安全的巢狀重複會被忽略。 -- 只有在可偵測時（原生提及或至少一個模式），才會強制執行提及門控。 +- 只有在可偵測時才會強制執行提及閘控（原生提及或至少一個模式）。 ```json5 { @@ -801,11 +804,11 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署 } ``` -`messages.groupChat.historyLimit` 會設定全域預設值。頻道可使用 `channels..historyLimit`（或依帳號）覆寫。設為 `0` 可停用。 +`messages.groupChat.historyLimit` 會設定全域預設值。頻道可以用 `channels..historyLimit`（或依帳號）覆寫。設為 `0` 可停用。 -`messages.visibleReplies` 是全域來源回合預設值；`messages.groupChat.visibleReplies` 會針對群組/頻道來源回合覆寫它。當 `messages.visibleReplies` 未設定時，harness 可以提供自己的直接/來源預設值；Codex harness 預設為 `message_tool`。頻道允許清單與提及閘控仍會決定是否處理某個回合。 +`messages.visibleReplies` 是全域來源回合預設值；`messages.groupChat.visibleReplies` 會針對群組/頻道來源回合覆寫它。當 `messages.visibleReplies` 未設定時，harness 可以提供自己的直接/來源預設值；Codex harness 預設為 `message_tool`。頻道允許清單和提及閘控仍會決定是否處理某個回合。 -#### 私訊歷史記錄限制 +#### DM 歷史限制 ```json5 { @@ -820,13 +823,13 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署 } ``` -解析順序：依私訊覆寫 → provider 預設值 → 無限制（全部保留）。 +解析順序：依 DM 覆寫 → 提供者預設值 → 無限制（全部保留）。 支援：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自我聊天模式 -在 `allowFrom` 中包含你自己的號碼，即可啟用自我聊天模式（忽略原生 @-提及，只回應文字模式）： +在 `allowFrom` 中加入你自己的號碼以啟用自我聊天模式（忽略原生 @-提及，只回應文字模式）： ```json5 { @@ -847,7 +850,7 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署 } ``` -### 指令（聊天指令處理） +### 命令（聊天命令處理） ```json5 { @@ -874,34 +877,34 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署 } ``` - + -- 此區塊會設定指令介面。若要查看目前內建 + 隨附的指令目錄，請參閱[斜線指令](/zh-TW/tools/slash-commands)。 -- 此頁是**設定鍵參考**，不是完整指令目錄。頻道/Plugin 擁有的指令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、裝置配對 `/pair`、記憶體 `/dreaming`、電話控制 `/phone`，以及 Talk `/voice`，會在其頻道/Plugin 頁面與[斜線指令](/zh-TW/tools/slash-commands)中記錄。 -- 文字指令必須是帶有前導 `/` 的**獨立**訊息。 -- `native: "auto"` 會為 Discord/Telegram 開啟原生指令，並讓 Slack 維持關閉。 -- `nativeSkills: "auto"` 會為 Discord/Telegram 開啟原生 Skills 指令，並讓 Slack 維持關閉。 -- 依頻道覆寫：`channels.discord.commands.native`（bool 或 `"auto"`）。對 Discord 而言，`false` 會在啟動期間略過原生指令註冊與清理。 -- 使用 `channels..commands.nativeSkills` 依頻道覆寫原生 Skills 註冊。 -- `channels.telegram.customCommands` 會加入額外 Telegram 機器人選單項目。 +- 這個區塊會設定命令介面。若要查看目前內建 + 隨附的命令目錄，請參閱 [斜線命令](/zh-TW/tools/slash-commands)。 +- 本頁是**設定鍵參考**，不是完整命令目錄。頻道/Plugin 擁有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、裝置配對 `/pair`、記憶 `/dreaming`、電話控制 `/phone` 和 Talk `/voice`，會記錄在其頻道/Plugin 頁面以及 [斜線命令](/zh-TW/tools/slash-commands)。 +- 文字命令必須是以 `/` 開頭的**獨立**訊息。 +- `native: "auto"` 會為 Discord/Telegram 開啟原生命令，並讓 Slack 維持關閉。 +- `nativeSkills: "auto"` 會為 Discord/Telegram 開啟原生 skill 命令，並讓 Slack 維持關閉。 +- 依頻道覆寫：`channels.discord.commands.native`（布林值或 `"auto"`）。對於 Discord，`false` 會在啟動期間略過原生命令註冊與清理。 +- 使用 `channels..commands.nativeSkills` 依頻道覆寫原生 skill 註冊。 +- `channels.telegram.customCommands` 會加入額外的 Telegram Bot 選單項目。 - `bash: true` 會為主機 shell 啟用 `! `。需要 `tools.elevated.enabled`，且傳送者必須在 `tools.elevated.allowFrom.` 中。 -- `config: true` 會啟用 `/config`（讀取/寫入 `openclaw.json`）。對於 Gateway `chat.send` 用戶端，持久性 `/config set|unset` 寫入還需要 `operator.admin`；唯讀 `/config show` 仍可供一般寫入範圍的 operator 用戶端使用。 -- `mcp: true` 會為 `mcp.servers` 底下的 OpenClaw 代管 MCP 伺服器設定啟用 `/mcp`。 -- `plugins: true` 會為 Plugin 探索、安裝與啟用/停用控制啟用 `/plugins`。 -- `channels..configWrites` 會依頻道管控設定變更（預設值：true）。 -- 對於多帳號頻道，`channels..accounts..configWrites` 也會管控以該帳號為目標的寫入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 會停用 `/restart` 與 Gateway 重新啟動工具動作。預設值：`true`。 -- `ownerAllowFrom` 是僅限擁有者指令/工具的明確擁有者允許清單。它與 `allowFrom` 分開。 +- `config: true` 會啟用 `/config`（讀取/寫入 `openclaw.json`）。對於 gateway `chat.send` 用戶端，持久性 `/config set|unset` 寫入也需要 `operator.admin`；唯讀 `/config show` 仍可供一般寫入範圍的 operator 用戶端使用。 +- `mcp: true` 會為 `mcp.servers` 下由 OpenClaw 管理的 MCP 伺服器設定啟用 `/mcp`。 +- `plugins: true` 會為 Plugin 探索、安裝，以及啟用/停用控制項啟用 `/plugins`。 +- `channels..configWrites` 會依頻道閘控設定變更（預設：true）。 +- 對於多帳號頻道，`channels..accounts..configWrites` 也會閘控以該帳號為目標的寫入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `restart: false` 會停用 `/restart` 和 Gateway 重新啟動工具動作。預設：`true`。 +- `ownerAllowFrom` 是 owner-only 命令/工具的明確擁有者允許清單。它與 `allowFrom` 分開。 - `ownerDisplay: "hash"` 會在系統提示中雜湊擁有者 ID。設定 `ownerDisplaySecret` 可控制雜湊。 -- `allowFrom` 是依 provider 設定。設定後，它會是**唯一**授權來源（頻道允許清單/配對與 `useAccessGroups` 會被忽略）。 -- `useAccessGroups: false` 允許指令在未設定 `allowFrom` 時略過存取群組政策。 -- 指令文件對照： - - 內建 + 隨附目錄：[斜線指令](/zh-TW/tools/slash-commands) - - 頻道專屬指令介面：[頻道](/zh-TW/channels) - - QQ Bot 指令：[QQ Bot](/zh-TW/channels/qqbot) - - 配對指令：[配對](/zh-TW/channels/pairing) - - LINE 卡片指令：[LINE](/zh-TW/channels/line) - - 記憶體 Dreaming：[Dreaming](/zh-TW/concepts/dreaming) +- `allowFrom` 是依提供者設定。設定後，它就是**唯一**授權來源（頻道允許清單/配對和 `useAccessGroups` 都會被忽略）。 +- 當未設定 `allowFrom` 時，`useAccessGroups: false` 允許命令繞過存取群組政策。 +- 命令文件對照： + - 內建 + 隨附目錄：[斜線命令](/zh-TW/tools/slash-commands) + - 頻道特定命令介面：[頻道](/zh-TW/channels) + - QQ Bot 命令：[QQ Bot](/zh-TW/channels/qqbot) + - 配對命令：[配對](/zh-TW/channels/pairing) + - LINE 卡片命令：[LINE](/zh-TW/channels/line) + - 記憶 Dreaming：[Dreaming](/zh-TW/concepts/dreaming) @@ -911,4 +914,4 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署 - [設定參考](/zh-TW/gateway/configuration-reference) — 頂層鍵 - [設定 — agents](/zh-TW/gateway/config-agents) -- [頻道概覽](/zh-TW/channels) +- [頻道概觀](/zh-TW/channels) diff --git a/docs/zh-TW/gateway/configuration-examples.md b/docs/zh-TW/gateway/configuration-examples.md index 8a31b6711..119d97271 100644 --- a/docs/zh-TW/gateway/configuration-examples.md +++ b/docs/zh-TW/gateway/configuration-examples.md @@ -3,18 +3,18 @@ read_when: - 了解如何設定 OpenClaw - 正在尋找設定範例 - 首次設定 OpenClaw -summary: 符合結構描述的常見 OpenClaw 設定範例 +summary: 常見 OpenClaw 設定的符合結構描述的設定範例 title: 設定範例 x-i18n: - generated_at: "2026-04-30T03:05:00Z" + generated_at: "2026-05-04T02:44:16Z" model: gpt-5.5 provider: openai - source_hash: 8bc1f8877bc635d6e3aafd911852d61e71fa08de9144751209542fd67c70f0ba + source_hash: 60c8c2d731f8dce93c4d14657041d72043bc36e3d71ab6cb13c02993ba90dbe3 source_path: gateway/configuration-examples.md workflow: 16 --- -以下範例與目前的設定結構描述一致。完整參考與各欄位備註，請參閱 [設定](/zh-TW/gateway/configuration)。 +範例如下，與目前的設定結構描述一致。如需完整參考與各欄位註記，請參閱[設定](/zh-TW/gateway/configuration)。 ## 快速開始 @@ -27,7 +27,7 @@ x-i18n: } ``` -儲存到 `~/.openclaw/openclaw.json`，你就能從該號碼私訊 bot。 +儲存到 `~/.openclaw/openclaw.json` 後，你就可以從該號碼私訊機器人。 ### 建議的起始設定 @@ -59,7 +59,7 @@ x-i18n: ## 展開範例（主要選項） -> JSON5 允許你使用註解與尾隨逗號。一般 JSON 也可以使用。 +> JSON5 可讓你使用註解和尾隨逗號。一般 JSON 也可以使用。 ```json5 { @@ -256,6 +256,7 @@ x-i18n: skills: ["github", "weather"], // inherited by agents that omit list[].skills thinkingDefault: "low", verboseDefault: "off", + toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", blockStreamingDefault: "off", @@ -472,7 +473,7 @@ x-i18n: ## 常見模式 -### 具有一項覆寫的共用 skill 基準 +### 共用技能基準搭配一個覆寫 ```json5 { @@ -490,8 +491,8 @@ x-i18n: ``` - `agents.defaults.skills` 是共用基準。 -- `agents.list[].skills` 會替換單一代理程式的該基準。 -- 當代理程式不應看到任何 Skills 時，請使用 `skills: []`。 +- `agents.list[].skills` 會為單一代理取代該基準。 +- 當代理不應看到任何 Skills 時，請使用 `skills: []`。 ### 多平台設定 @@ -514,9 +515,9 @@ x-i18n: } ``` -### 受信任 Node 網路自動核准 +### 受信任的 Node 網路自動核准 -除非你能控制網路路徑，否則請維持手動裝置配對。若是專用實驗室或 tailnet 子網路，你可以選擇使用精確的 CIDR 或 IP，啟用首次 Node 裝置自動核准： +除非你控制網路路徑，否則請保持裝置配對為手動。對於專用實驗室或 tailnet 子網路，你可以選擇使用精確的 CIDR 或 IP 啟用首次 Node 裝置自動核准： ```json5 { @@ -530,11 +531,11 @@ x-i18n: } ``` -未設定時，這會保持關閉。它只適用於沒有要求範圍的新 `role: node` 配對。Operator/瀏覽器用戶端，以及角色、範圍、中繼資料或公開金鑰升級，仍然需要手動核准。 +未設定時，此功能會保持關閉。它只適用於沒有要求任何範圍的全新 `role: node` 配對。操作者/瀏覽器用戶端，以及角色、範圍、中繼資料或公開金鑰升級，仍需要手動核准。 ### 安全 DM 模式（共用收件匣 / 多使用者 DM） -如果有超過一個人可以傳 DM 給你的機器人（`allowFrom` 中有多個項目、多人的配對核准，或 `dmPolicy: "open"`），請啟用**安全 DM 模式**，讓不同寄件者的 DM 預設不會共用同一個上下文： +如果有超過一個人可以 DM 你的 bot（`allowFrom` 中有多個項目、核准多人的配對，或 `dmPolicy: "open"`），請啟用 **安全 DM 模式**，讓不同寄件者的 DM 預設不會共用同一個上下文： ```json5 { @@ -558,10 +559,10 @@ x-i18n: } ``` -對於 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，寄件者授權預設優先使用 ID。 -只有在你明確接受該風險時，才可使用各頻道的 `dangerouslyAllowNameMatching: true` 啟用直接可變名稱/電子郵件/nick 比對。 +對於 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，寄件者授權預設以 ID 優先。 +只有在你明確接受該風險時，才為各頻道啟用透過 `dangerouslyAllowNameMatching: true` 進行直接可變的名稱/email/nick 比對。 -### Anthropic API 金鑰 + MiniMax 備援 +### Anthropic API 金鑰 + MiniMax 後備 ```json5 { @@ -595,7 +596,7 @@ x-i18n: } ``` -### 工作機器人（受限存取） +### 工作 bot（受限制存取） ```json5 { @@ -620,7 +621,7 @@ x-i18n: } ``` -### 僅限本機模型 +### 僅使用本機模型 ```json5 { @@ -655,11 +656,11 @@ x-i18n: ## 提示 - 如果你設定 `dmPolicy: "open"`，對應的 `allowFrom` 清單必須包含 `"*"`。 -- 供應商 ID 各不相同（電話號碼、使用者 ID、頻道 ID）。請使用供應商文件確認格式。 +- 提供者 ID 會有所不同（電話號碼、使用者 ID、頻道 ID）。請使用提供者文件確認格式。 - 稍後可新增的選用區段：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。 -- 如需更深入的設定說明，請參閱[供應商](/zh-TW/providers)和[疑難排解](/zh-TW/gateway/troubleshooting)。 +- 請參閱[提供者](/zh-TW/providers)與[疑難排解](/zh-TW/gateway/troubleshooting)，了解更深入的設定說明。 ## 相關 -- [設定參考](/zh-TW/gateway/configuration-reference) -- [設定](/zh-TW/gateway/configuration) +- [組態參考](/zh-TW/gateway/configuration-reference) +- [組態](/zh-TW/gateway/configuration) diff --git a/docs/zh-TW/gateway/opentelemetry.md b/docs/zh-TW/gateway/opentelemetry.md index 7a57ad34c..7bc3d83cc 100644 --- a/docs/zh-TW/gateway/opentelemetry.md +++ b/docs/zh-TW/gateway/opentelemetry.md @@ -1,36 +1,33 @@ --- read_when: - - 您想將 OpenClaw 模型使用量、訊息流程或工作階段指標傳送到 OpenTelemetry 收集器 + - 您想要將 OpenClaw 模型使用情況、訊息流程或工作階段指標傳送至 OpenTelemetry 收集器 - 你正在將追蹤、指標或日誌接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 後端 - - 若要建立儀表板或警示，你需要確切的指標名稱、追蹤區段名稱或屬性結構 -summary: 透過 diagnostics-otel Plugin (OTLP/HTTP)，將 OpenClaw 診斷資料匯出至任何 OpenTelemetry 收集器 + - 您需要確切的指標名稱、span 名稱或屬性結構，才能建立儀表板或警示 +summary: 透過 diagnostics-otel Plugin（OTLP/HTTP）將 OpenClaw 診斷資料匯出到任何 OpenTelemetry 收集器 title: OpenTelemetry 匯出 x-i18n: - generated_at: "2026-05-03T21:33:55Z" + generated_at: "2026-05-04T02:44:21Z" model: gpt-5.5 provider: openai - source_hash: c8091aa633a3e10593681f94913a858587a5dc69d9947e0c0d4132f6e897b00b + source_hash: d0b5be99b29fe5f13132b03cfeaf3ce978ee16f29e307aa76769bc414b5ca35f source_path: gateway/opentelemetry.md workflow: 16 --- -OpenClaw 透過官方 `diagnostics-otel` Plugin 匯出診斷資料 -使用 **OTLP/HTTP (protobuf)**。任何接受 OTLP/HTTP 的 collector 或後端 -都可不需變更程式碼直接運作。若要了解本機檔案記錄以及如何閱讀，請參閱 +OpenClaw 透過官方 `diagnostics-otel` Plugin +使用 **OTLP/HTTP (protobuf)** 匯出診斷資料。任何接受 OTLP/HTTP +的收集器或後端都能在不修改程式碼的情況下運作。如需本機檔案記錄及其讀取方式，請參閱 [記錄](/zh-TW/logging)。 -## 運作方式 +## 整體如何搭配運作 -- **診斷事件** 是由 - Gateway 和隨附 Plugin 針對模型執行、訊息流程、工作階段、佇列 - 和 exec 發出的結構化處理程序內記錄。 -- **`diagnostics-otel` Plugin** 會訂閱這些事件，並透過 OTLP/HTTP 將其匯出為 +- **診斷事件** 是由 Gateway 和內建 Plugin 在程序內發出的結構化記錄， + 用於模型執行、訊息流程、工作階段、佇列和 exec。 +- **`diagnostics-otel` Plugin** 會訂閱這些事件，並透過 OTLP/HTTP 將它們匯出為 OpenTelemetry **指標**、**追蹤** 和 **記錄**。 -- **提供者呼叫** 會在提供者傳輸接受自訂標頭時，從 OpenClaw 的 - 受信任模型呼叫 span 內容接收 W3C `traceparent` 標頭。 - Plugin 發出的追蹤內容不會被傳播。 -- 只有在診斷介面和 Plugin - 都啟用時，匯出器才會附加，因此預設的處理程序內成本接近於零。 +- 當提供者傳輸接受自訂標頭時，**提供者呼叫** 會從 OpenClaw + 受信任的模型呼叫 span 情境收到 W3C `traceparent` 標頭。Plugin 發出的追蹤情境不會被傳播。 +- 匯出器只會在診斷介面與 Plugin 都啟用時附加，因此程序內成本預設會維持接近零。 ## 快速開始 @@ -72,18 +69,19 @@ openclaw plugins enable diagnostics-otel ``` -`protocol` 目前僅支援 `http/protobuf`。`grpc` 會被忽略。 +`protocol` 目前只支援 `http/protobuf`。`grpc` 會被忽略。 ## 匯出的訊號 | 訊號 | 內容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **指標** | 權杖使用量、成本、執行時間、訊息流程、佇列通道、工作階段狀態、exec 和記憶體壓力的計數器與直方圖。 | -| **追蹤** | 模型使用量、模型呼叫、harness 生命週期、工具執行、exec、Webhook/訊息處理、內容組裝和工具迴圈的 span。 | +| **指標** | token 用量、成本、執行期間、訊息流程、佇列通道、工作階段狀態、exec 和記憶體壓力的計數器與直方圖。 | +| **追蹤** | 模型用量、模型呼叫、harness 生命週期、工具執行、exec、webhook/訊息處理、情境組裝，以及工具迴圈的 span。 | | **記錄** | 啟用 `diagnostics.otel.logs` 時，透過 OTLP 匯出的結構化 `logging.file` 記錄。 | -可獨立切換 `traces`、`metrics` 和 `logs`。當 `diagnostics.otel.enabled` 為 true 時，三者預設全部開啟。 +可分別切換 `traces`、`metrics` 和 `logs`。當 +`diagnostics.otel.enabled` 為 true 時，三者預設都會開啟。 ## 設定參考 @@ -120,118 +118,118 @@ openclaw plugins enable diagnostics-otel ### 環境變數 -| 變數 | 用途 | -| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆寫 `diagnostics.otel.endpoint`。如果值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，則會照原樣使用。 | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 當相符的 `diagnostics.otel.*Endpoint` 設定鍵未設定時使用的訊號專屬端點覆寫。訊號專屬設定優先於訊號專屬 env，而訊號專屬 env 又優先於共用端點。 | -| `OTEL_SERVICE_NAME` | 覆寫 `diagnostics.otel.serviceName`。 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆寫線路通訊協定（目前僅採用 `http/protobuf`）。 | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | 設為 `gen_ai_latest_experimental`，即可發出最新實驗性 GenAI span 屬性 (`gen_ai.provider.name`)，而不是舊版 `gen_ai.system`。GenAI 指標一律使用有界、低基數的語意屬性。 | -| `OPENCLAW_OTEL_PRELOADED` | 當另一個 preload 或主機處理程序已註冊全域 OpenTelemetry SDK 時設為 `1`。Plugin 接著會略過自己的 NodeSDK 生命週期，但仍會連接診斷監聽器並遵循 `traces`/`metrics`/`logs`。 | +| 變數 | 用途 | +| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆寫 `diagnostics.otel.endpoint`。如果值已經包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，會依原樣使用。 | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 在對應的 `diagnostics.otel.*Endpoint` 設定鍵未設定時使用的特定訊號端點覆寫。特定訊號設定優先於特定訊號環境變數，而特定訊號環境變數優先於共用端點。 | +| `OTEL_SERVICE_NAME` | 覆寫 `diagnostics.otel.serviceName`。 | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆寫線路協定（目前只採用 `http/protobuf`）。 | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | 設為 `gen_ai_latest_experimental`，即可發出最新的實驗性 GenAI span 屬性 (`gen_ai.provider.name`)，而不是舊版 `gen_ai.system`。無論如何，GenAI 指標一律使用有界且低基數的語意屬性。 | +| `OPENCLAW_OTEL_PRELOADED` | 當另一個 preload 或主機程序已註冊全域 OpenTelemetry SDK 時設為 `1`。Plugin 接著會略過自己的 NodeSDK 生命週期，但仍會接線診斷監聽器，並遵守 `traces`/`metrics`/`logs`。 | ## 隱私與內容擷取 -原始模型/工具內容預設**不會**匯出。Span 只攜帶有界的 -識別符（channel、provider、model、error category、僅雜湊的 request ids）， +原始模型/工具內容預設**不會**匯出。Span 只攜帶有界識別符 +（通道、提供者、模型、錯誤類別、僅雜湊的請求 ID）， 且絕不包含提示文字、回應文字、工具輸入、工具輸出或 工作階段金鑰。 傳出的模型請求可能包含 W3C `traceparent` 標頭。該標頭只會 -從 OpenClaw 擁有的診斷追蹤內容針對作用中的模型 -呼叫產生。既有由呼叫端提供的 `traceparent` 標頭會被取代，因此 Plugin 或 +從作用中模型呼叫的 OpenClaw 所有診斷追蹤情境產生。 +既有由呼叫端提供的 `traceparent` 標頭會被取代，因此 Plugin 或 自訂提供者選項無法偽造跨服務追蹤祖先關係。 -只有當你的 collector 和 -保留政策已核准可處理提示、回應、工具或系統提示 -文字時，才將 `diagnostics.otel.captureContent.*` 設為 `true`。每個子鍵都可獨立選擇啟用： +只有在你的收集器與保留政策已核准可存放提示、回應、工具或系統提示 +文字時，才將 `diagnostics.otel.captureContent.*` 設為 `true`。 +每個子鍵都可獨立選擇啟用： - `inputMessages` — 使用者提示內容。 - `outputMessages` — 模型回應內容。 -- `toolInputs` — 工具引數酬載。 -- `toolOutputs` — 工具結果酬載。 +- `toolInputs` — 工具引數承載。 +- `toolOutputs` — 工具結果承載。 - `systemPrompt` — 組裝後的系統/開發者提示。 -當任何子鍵啟用時，模型和工具 span 只會針對該類別取得有界、已遮蔽的 +啟用任何子鍵時，模型與工具 span 只會針對該類別取得有界且經過遮蔽的 `openclaw.content.*` 屬性。 -## 取樣與清除 +## 取樣與排清 -- **追蹤：** `diagnostics.otel.sampleRate`（僅 root-span，`0.0` 丟棄全部， +- **追蹤：** `diagnostics.otel.sampleRate`（僅 root span，`0.0` 丟棄全部， `1.0` 保留全部）。 - **指標：** `diagnostics.otel.flushIntervalMs`（最低 `1000`）。 - **記錄：** OTLP 記錄會遵循 `logging.level`（檔案記錄層級）。它們使用 - 診斷記錄項目的遮蔽路徑，而非主控台格式化。高流量 - 安裝應優先使用 OTLP collector 取樣/篩選，而不是本機取樣。 -- **檔案記錄關聯：** 當記錄呼叫攜帶有效的 - 診斷追蹤內容時，JSONL 檔案記錄會包含頂層 `traceId`、 - `spanId`、`parentSpanId` 和 `traceFlags`，讓記錄處理器能將本機記錄行與 - 匯出的 span 關聯。 -- **請求關聯：** Gateway HTTP 請求和 WebSocket 訊框會建立 - 內部請求追蹤範圍。該範圍內的記錄和診斷事件 - 預設會繼承請求追蹤，而代理程式執行和模型呼叫 span 會 - 建立為子項，因此提供者 `traceparent` 標頭會留在同一個追蹤上。 + 診斷記錄資料的遮蔽路徑，而不是主控台格式化。高流量 + 安裝應優先使用 OTLP 收集器取樣/篩選，而不是本機取樣。 +- **檔案記錄關聯：** 當記錄呼叫帶有有效的診斷追蹤情境時，JSONL 檔案記錄會包含頂層 + `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，讓記錄處理器能將本機記錄行與 + 匯出的 span 串接。 +- **請求關聯：** Gateway HTTP 請求與 WebSocket frame 會建立 + 內部請求追蹤範圍。該範圍內的記錄與診斷事件 + 預設會繼承請求追蹤，而代理執行與模型呼叫 span 則會 + 作為子項建立，因此提供者 `traceparent` 標頭會留在同一條追蹤上。 ## 匯出的指標 -### 模型使用量 +### 模型用量 -- `openclaw.tokens`（計數器，attrs：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.agent`） -- `openclaw.cost.usd`（計數器，attrs：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `openclaw.run.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `openclaw.context.tokens`（直方圖，attrs：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `gen_ai.client.token.usage`（直方圖，GenAI 語意慣例指標，attrs：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`） -- `gen_ai.client.operation.duration`（直方圖，秒，GenAI 語意慣例指標，attrs：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`、選用 `error.type`） -- `openclaw.model_call.duration_ms`（直方圖，attrs：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及分類錯誤上的 `openclaw.errorCategory` 和 `openclaw.failureKind`） -- `openclaw.model_call.request_bytes`（直方圖，最終模型請求酬載的 UTF-8 位元組大小；不含原始酬載內容） +- `openclaw.tokens`（計數器，屬性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.agent`） +- `openclaw.cost.usd`（計數器，屬性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `openclaw.run.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `openclaw.context.tokens`（直方圖，屬性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `gen_ai.client.token.usage`（直方圖，GenAI 語意慣例指標，屬性：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`） +- `gen_ai.client.operation.duration`（直方圖，秒，GenAI 語意慣例指標，屬性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`，選用 `error.type`） +- `openclaw.model_call.duration_ms`（直方圖，屬性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及分類錯誤上的 `openclaw.errorCategory` 和 `openclaw.failureKind`） +- `openclaw.model_call.request_bytes`（直方圖，最終模型請求承載的 UTF-8 位元組大小；不含原始承載內容） - `openclaw.model_call.response_bytes`（直方圖，串流模型回應事件的 UTF-8 位元組大小；不含原始回應內容） -- `openclaw.model_call.time_to_first_byte_ms`（直方圖，第一個串流回應事件前的經過時間） +- `openclaw.model_call.time_to_first_byte_ms`（直方圖，第一個串流回應事件前經過的時間） ### 訊息流程 -- `openclaw.webhook.received`（計數器，attrs：`openclaw.channel`、`openclaw.webhook`） -- `openclaw.webhook.error`（計數器，attrs：`openclaw.channel`、`openclaw.webhook`） -- `openclaw.webhook.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.webhook`） -- `openclaw.message.queued`（計數器，attrs：`openclaw.channel`、`openclaw.source`） -- `openclaw.message.processed`（計數器，attrs：`openclaw.channel`、`openclaw.outcome`） -- `openclaw.message.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.outcome`） -- `openclaw.message.delivery.started`（計數器，attrs：`openclaw.channel`、`openclaw.delivery.kind`） -- `openclaw.message.delivery.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`） +- `openclaw.webhook.received`（計數器，屬性：`openclaw.channel`、`openclaw.webhook`） +- `openclaw.webhook.error`（計數器，屬性：`openclaw.channel`、`openclaw.webhook`） +- `openclaw.webhook.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.webhook`） +- `openclaw.message.queued`（計數器，屬性：`openclaw.channel`、`openclaw.source`） +- `openclaw.message.processed`（計數器，屬性：`openclaw.channel`、`openclaw.outcome`） +- `openclaw.message.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.outcome`） +- `openclaw.message.delivery.started`（計數器，屬性：`openclaw.channel`、`openclaw.delivery.kind`） +- `openclaw.message.delivery.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`） ### 佇列與工作階段 -- `openclaw.queue.lane.enqueue`（計數器，attrs：`openclaw.lane`） -- `openclaw.queue.lane.dequeue`（計數器，attrs：`openclaw.lane`） -- `openclaw.queue.depth`（直方圖，attrs：`openclaw.lane` 或 `openclaw.channel=heartbeat`） -- `openclaw.queue.wait_ms`（直方圖，attrs：`openclaw.lane`） -- `openclaw.session.state`（計數器，attrs：`openclaw.state`、`openclaw.reason`） -- `openclaw.session.stuck`（計數器，attrs：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出） -- `openclaw.session.stuck_age_ms`（直方圖，attrs：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出） -- `openclaw.run.attempt`（計數器，attrs：`openclaw.attempt`） +- `openclaw.queue.lane.enqueue`（計數器，屬性：`openclaw.lane`） +- `openclaw.queue.lane.dequeue`（計數器，屬性：`openclaw.lane`） +- `openclaw.queue.depth`（直方圖，屬性：`openclaw.lane` 或 `openclaw.channel=heartbeat`） +- `openclaw.queue.wait_ms`（直方圖，屬性：`openclaw.lane`） +- `openclaw.session.state`（計數器，屬性：`openclaw.state`、`openclaw.reason`） +- `openclaw.session.stuck`（計數器，屬性：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出） +- `openclaw.session.stuck_age_ms`（直方圖，屬性：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出） +- `openclaw.run.attempt`（計數器，屬性：`openclaw.attempt`） -### 工作階段活性遙測 +### 工作階段存活遙測 -`diagnostics.stuckSessionWarnMs` 是工作階段 -活性診斷的無進度時間閾值。當 OpenClaw 觀察到回覆、工具、狀態、區塊或 ACP 執行階段進度時，`processing` 工作階段不會朝此閾值累積時間。 -Typing keepalive 不會計為進度，因此仍可偵測 -靜默的模型或 harness。 +`diagnostics.stuckSessionWarnMs` 是工作階段存活診斷的無進度時間閾值。 +當 OpenClaw 觀察到回覆、工具、狀態、區塊或 ACP runtime 進度時， +`processing` 工作階段不會朝此閾值累積時間。 +輸入狀態 keepalive 不會算作進度，因此靜默的模型或 harness +仍可被偵測到。 -OpenClaw 會依其仍可觀察到的工作來分類工作階段： +OpenClaw 會依它仍可觀察到的工作分類工作階段： -- `session.long_running`：作用中的嵌入式工作、模型呼叫或工具呼叫仍在推進。 -- `session.stalled`：存在作用中工作，但作用中的執行尚未回報近期進度。停滯的嵌入式執行一開始維持僅觀察，然後在至少 10 分鐘且達到 5 倍 `diagnostics.stuckSessionWarnMs` 仍無進度後進入中止並清空，讓該通道後方排隊的回合可以繼續。 -- `session.stuck`：沒有作用中工作的過時工作階段簿記。這會立即釋放受影響的工作階段通道。 +- `session.long_running`：作用中的嵌入式工作、模型呼叫或工具呼叫仍在進行。 +- `session.stalled`：存在作用中的工作，但作用中的執行最近未回報進度。停滯的嵌入式執行一開始會維持僅觀察，接著在至少 10 分鐘且達到 5 倍 `diagnostics.stuckSessionWarnMs` 仍無進度後中止並清空，讓該通道後方排隊的回合可以恢復。 +- `session.stuck`：沒有作用中工作的過期工作階段記帳。這會立即釋放受影響的工作階段通道。 -只有 `session.stuck` 會發出 `openclaw.session.stuck` 計數器、`openclaw.session.stuck_age_ms` 直方圖，以及 `openclaw.session.stuck` span。重複的 `session.stuck` 診斷會在工作階段維持不變時退避，因此儀表板應針對持續增加發出警示，而不是對每個 Heartbeat tick 發出警示。關於設定旋鈕與預設值，請參閱[設定參考](/zh-TW/gateway/configuration-reference#diagnostics)。 +只有 `session.stuck` 會發出 `openclaw.session.stuck` 計數器、`openclaw.session.stuck_age_ms` 直方圖，以及 `openclaw.session.stuck` span。重複的 `session.stuck` 診斷會在工作階段保持不變時退避，因此儀表板應針對持續增加發出警示，而不是每個 Heartbeat tick 都警示。如需設定旋鈕與預設值，請參閱[設定參考](/zh-TW/gateway/configuration-reference#diagnostics)。 ### Harness 生命週期 -- `openclaw.harness.duration_ms`（直方圖，屬性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、錯誤時的 `openclaw.harness.phase`） +- `openclaw.harness.duration_ms`（直方圖，屬性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，發生錯誤時包含 `openclaw.harness.phase`） -### Exec +### 執行 - `openclaw.exec.duration_ms`（直方圖，屬性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） -### 診斷內部（記憶體與工具迴圈） +### 診斷內部機制（記憶體與工具迴圈） - `openclaw.memory.heap_used_bytes`（直方圖，屬性：`openclaw.memory.kind`） - `openclaw.memory.rss_bytes`（直方圖） @@ -243,7 +241,7 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段： - `openclaw.model.usage` - `openclaw.channel`、`openclaw.provider`、`openclaw.model` - - `openclaw.tokens.*`（input/output/cache_read/cache_write/total） + - `openclaw.tokens.*`（輸入/輸出/快取讀取/快取寫入/總計） - 預設為 `gen_ai.system`，或在選用最新 GenAI 語意慣例時使用 `gen_ai.provider.name` - `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*` - `openclaw.run` @@ -251,43 +249,43 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段： - `openclaw.model.call` - 預設為 `gen_ai.system`，或在選用最新 GenAI 語意慣例時使用 `gen_ai.provider.name` - `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport` - - 錯誤時的 `openclaw.errorCategory` 與選用的 `openclaw.failureKind` + - 發生錯誤時包含 `openclaw.errorCategory` 與選用的 `openclaw.failureKind` - `openclaw.model_call.request_bytes`、`openclaw.model_call.response_bytes`、`openclaw.model_call.time_to_first_byte_ms` - `openclaw.provider.request_id_hash`（上游提供者請求 ID 的有界 SHA 型雜湊；不會匯出原始 ID） - `openclaw.harness.run` - `openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、`openclaw.provider`、`openclaw.model`、`openclaw.channel` - 完成時：`openclaw.harness.result_classification`、`openclaw.harness.yield_detected`、`openclaw.harness.items.started`、`openclaw.harness.items.completed`、`openclaw.harness.items.active` - - 錯誤時：`openclaw.harness.phase`、`openclaw.errorCategory`、選用的 `openclaw.harness.cleanup_failed` + - 發生錯誤時：`openclaw.harness.phase`、`openclaw.errorCategory`、選用的 `openclaw.harness.cleanup_failed` - `openclaw.tool.execution` - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、`openclaw.tool.params.*` - `openclaw.exec` - `openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`、`openclaw.exec.command_length`、`openclaw.exec.exit_code`、`openclaw.exec.timed_out` - `openclaw.webhook.processed` - - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId` + - `openclaw.channel`、`openclaw.webhook` - `openclaw.webhook.error` - - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、`openclaw.error` + - `openclaw.channel`、`openclaw.webhook`、`openclaw.error` - `openclaw.message.processed` - - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、`openclaw.messageId`、`openclaw.reason` + - `openclaw.channel`、`openclaw.outcome`、`openclaw.reason` - `openclaw.message.delivery` - `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`、`openclaw.delivery.result_count` - `openclaw.session.stuck` - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（沒有提示、歷史、回應或工作階段金鑰內容） + - `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含提示、歷史、回應或工作階段金鑰內容） - `openclaw.tool.loop` - - `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（沒有迴圈訊息、參數或工具輸出） + - `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（不包含迴圈訊息、參數或工具輸出） - `openclaw.memory.pressure` - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes` -明確啟用內容擷取時，模型與工具 span 也可以包含你已選用之特定內容類別的有界、已遮蔽 `openclaw.content.*` 屬性。 +明確啟用內容擷取時，模型與工具 span 也可以包含你選用的特定內容類別之有界且已遮蔽的 `openclaw.content.*` 屬性。 ## 診斷事件目錄 -下列事件支援上述指標與 span。Plugin 也可以直接訂閱這些事件，而不需 OTLP 匯出。 +下列事件支援上述指標與 span。Plugin 也可以直接訂閱這些事件，而不需要 OTLP 匯出。 -**模型使用量** +**模型用量** -- `model.usage` — token、成本、持續時間、context、提供者/模型/通道、工作階段 ID。`usage` 是提供者/回合的成本與遙測統計；`context.used` 是目前的提示/context 快照，在涉及快取輸入或工具迴圈呼叫時，可能低於提供者的 `usage.total`。 +- `model.usage` — token、成本、持續時間、內容、提供者/模型/頻道、工作階段 ID。`usage` 是用於成本與遙測的提供者/回合計帳；`context.used` 是目前的提示/內容快照，當涉及快取輸入或工具迴圈呼叫時，可能低於提供者的 `usage.total`。 **訊息流程** @@ -304,15 +302,15 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段： **Harness 生命週期** -- `harness.run.started` / `harness.run.completed` / `harness.run.error` — agent harness 的每次執行生命週期。包含 `harnessId`、選用的 `pluginId`、提供者/模型/通道，以及執行 ID。完成時加入 `durationMs`、`outcome`、選用的 `resultClassification`、`yieldDetected`，以及 `itemLifecycle` 計數。錯誤時加入 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory`，以及選用的 `cleanupFailed`。 +- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 代理 harness 的每次執行生命週期。包含 `harnessId`、選用的 `pluginId`、提供者/模型/頻道，以及執行 ID。完成時會新增 `durationMs`、`outcome`、選用的 `resultClassification`、`yieldDetected`，以及 `itemLifecycle` 計數。錯誤會新增 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory`，以及選用的 `cleanupFailed`。 -**Exec** +**執行** - `exec.process.completed` — 終端結果、持續時間、目標、模式、結束碼與失敗種類。不包含命令文字與工作目錄。 -## 沒有匯出器時 +## 不使用匯出器 -你可以讓診斷事件保持可供 Plugin 或自訂 sink 使用，而不執行 `diagnostics-otel`： +你可以不執行 `diagnostics-otel`，仍讓診斷事件可供 Plugin 或自訂接收端使用： ```json5 { @@ -320,7 +318,7 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段： } ``` -若要在不提高 `logging.level` 的情況下取得目標式偵錯輸出，請使用診斷旗標。旗標不區分大小寫，並支援萬用字元（例如 `telegram.*` 或 `*`）： +如需在不提高 `logging.level` 的情況下取得目標式除錯輸出，請使用診斷旗標。旗標不區分大小寫，並支援萬用字元（例如 `telegram.*` 或 `*`）： ```json5 { @@ -328,13 +326,13 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段： } ``` -或作為一次性的環境變數覆寫： +或作為一次性的環境覆寫： ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -旗標輸出會寫入標準記錄檔（`logging.file`），且仍會由 `logging.redactSensitive` 進行遮蔽。完整指南：[診斷旗標](/zh-TW/diagnostics/flags)。 +旗標輸出會寫入標準記錄檔（`logging.file`），且仍會由 `logging.redactSensitive` 遮蔽。完整指南：[診斷旗標](/zh-TW/diagnostics/flags)。 ## 停用 @@ -344,12 +342,12 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway } ``` -你也可以將 `diagnostics-otel` 從 `plugins.allow` 中移除，或執行 `openclaw plugins disable diagnostics-otel`。 +你也可以將 `diagnostics-otel` 排除於 `plugins.allow` 之外，或執行 `openclaw plugins disable diagnostics-otel`。 ## 相關 -- [記錄](/zh-TW/logging) — 檔案記錄、主控台輸出、CLI tailing，以及 Control UI 記錄分頁 -- [Gateway 記錄內部](/zh-TW/gateway/logging) — WS 記錄樣式、子系統前綴與主控台擷取 -- [診斷旗標](/zh-TW/diagnostics/flags) — 目標式偵錯記錄旗標 -- [診斷匯出](/zh-TW/gateway/diagnostics) — 操作者支援組合工具（與 OTEL 匯出分開） +- [記錄](/zh-TW/logging) — 檔案記錄、主控台輸出、CLI tail，以及 Control UI 記錄分頁 +- [Gateway 記錄內部機制](/zh-TW/gateway/logging) — WS 記錄樣式、子系統前綴與主控台擷取 +- [診斷旗標](/zh-TW/diagnostics/flags) — 目標式除錯記錄旗標 +- [診斷匯出](/zh-TW/gateway/diagnostics) — 操作者支援套件工具（與 OTEL 匯出分開） - [設定參考](/zh-TW/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 欄位參考 diff --git a/docs/zh-TW/gateway/operator-scopes.md b/docs/zh-TW/gateway/operator-scopes.md index 36f99ee1a..2bacb4db6 100644 --- a/docs/zh-TW/gateway/operator-scopes.md +++ b/docs/zh-TW/gateway/operator-scopes.md @@ -1,25 +1,25 @@ --- read_when: - - 偵錯缺少操作者範圍的錯誤 + - 除錯缺少操作員範圍的錯誤 - 檢視裝置或 Node 配對核准 - 新增或分類 Gateway RPC 方法 -summary: Gateway 用戶端的操作者角色、範圍與批准時檢查 +summary: Gateway 用戶端的操作者角色、範圍與核准時檢查 title: 操作員範圍 x-i18n: - generated_at: "2026-05-03T02:44:26Z" + generated_at: "2026-05-04T02:44:21Z" model: gpt-5.5 provider: openai - source_hash: 48f59f96b41333af9124ad4083ac5442eedb2d6cebdfff74e3ba256f06d36add + source_hash: f05d6bdbf9bdad2aef1c9664bb7ebb4b6241334b8aefac7993104e9977e40450 source_path: gateway/operator-scopes.md workflow: 16 --- -Operator 範圍定義 Gateway 用戶端在完成驗證後可以執行的操作。 -它們是在單一可信任 Gateway 操作者網域內的控制平面防護機制， -不是敵對多租戶隔離。如果你需要在人員、團隊或機器之間建立強隔離， -請在不同 OS 使用者或主機下執行獨立的 Gateways。 +Operator 範圍定義 Gateway 用戶端在驗證後可以執行的操作。 +它們是一個受信任 Gateway operator 網域內的控制平面防護機制， +不是敵意多租戶隔離。如果你需要在人員、團隊或機器之間建立強隔離， +請在不同的 OS 使用者或主機下執行獨立的 Gateway。 -相關：[安全性](/zh-TW/gateway/security)、[Gateway 通訊協定](/zh-TW/gateway/protocol)、 +相關：[安全性](/zh-TW/gateway/security)、[Gateway 協定](/zh-TW/gateway/protocol)、 [Gateway 配對](/zh-TW/gateway/pairing)、[裝置 CLI](/zh-TW/cli/devices)。 ## 角色 @@ -27,73 +27,70 @@ Operator 範圍定義 Gateway 用戶端在完成驗證後可以執行的操作 Gateway WebSocket 用戶端會以一種角色連線： - `operator`：控制平面用戶端，例如 CLI、Control UI、自動化，以及 - 可信任的輔助程序。 -- `node`：能力主機，例如 macOS、iOS、Android，或透過 `node.invoke` - 暴露命令的無頭節點。 + 受信任的輔助程序。 +- `node`：功能主機，例如 macOS、iOS、Android，或透過 `node.invoke` + 公開命令的 headless 節點。 -Operator RPC 方法需要 `operator` 角色。Node 發起的方法 -需要 `node` 角色。 +Operator RPC 方法需要 `operator` 角色。源自 Node 的方法需要 +`node` 角色。 ## 範圍層級 -| 範圍 | 意義 | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `operator.read` | 唯讀狀態、清單、目錄、記錄、工作階段讀取，以及其他不會變更狀態的控制平面呼叫。 | -| `operator.write` | 一般會變更狀態的操作者動作，例如傳送訊息、呼叫工具、更新 talk/voice 設定，以及 Node 命令轉送。也滿足 `operator.read`。 | -| `operator.admin` | 管理性的控制平面存取。滿足每個 `operator.*` 範圍。設定變更、更新、原生 hooks、敏感保留命名空間，以及高風險核准都需要此範圍。 | -| `operator.pairing` | 裝置和 Node 配對管理，包括列出、核准、拒絕、移除、輪替與撤銷配對記錄或裝置權杖。 | -| `operator.approvals` | Exec 和 Plugin 核准 API。 | -| `operator.talk.secrets` | 讀取包含密鑰的 Talk 設定。 | +| 範圍 | 含義 | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `operator.read` | 唯讀狀態、清單、目錄、記錄、工作階段讀取，以及其他不會變更狀態的控制平面呼叫。 | +| `operator.write` | 一般會變更狀態的 operator 動作，例如傳送訊息、叫用工具、更新對話/語音設定，以及 Node 命令轉送。也滿足 `operator.read`。 | +| `operator.admin` | 管理性控制平面存取。滿足每個 `operator.*` 範圍。設定變更、更新、原生 hook、敏感保留命名空間，以及高風險核准都需要此範圍。 | +| `operator.pairing` | 裝置與 Node 配對管理，包括列出、核准、拒絕、移除、輪替，以及撤銷配對記錄或裝置權杖。 | +| `operator.approvals` | Exec 與 Plugin 核准 API。 | +| `operator.talk.secrets` | 讀取包含密鑰的 Talk 設定。 | -未知的未來 `operator.*` 範圍需要完全相符，除非呼叫者具有 +未知的未來 `operator.*` 範圍需要精確符合，除非呼叫端具有 `operator.admin`。 -## 方法範圍只是第一道關卡 +## 方法範圍只是第一道門檻 -每個 Gateway RPC 都有最小權限的方法範圍。該方法範圍會決定 -請求是否可以到達處理常式。某些處理常式接著會根據實際要核准或變更的具體項目， +每個 Gateway RPC 都有一個最低權限的方法範圍。該方法範圍會決定 +請求是否可以到達處理常式。部分處理常式接著會根據實際被核准或變更的項目， 套用更嚴格的核准時檢查。 範例： -- `device.pair.approve` 可透過 `operator.pairing` 存取，但核准 - 操作者裝置只能發行或保留呼叫者已持有的範圍。 -- `node.pair.approve` 可透過 `operator.pairing` 存取，然後會從待處理的 - Node 命令清單推導額外核准範圍。 +- `device.pair.approve` 可透過 `operator.pairing` 到達，但核准 + operator 裝置時，只能鑄造或保留呼叫端已持有的範圍。 +- `node.pair.approve` 可透過 `operator.pairing` 到達，接著會從待處理的 + Node 命令清單衍生額外的核准範圍。 - `chat.send` 通常是寫入範圍的方法，但持久性的 `/config set` - 和 `/config unset` 需要命令層級的 `operator.admin`。 + 與 `/config unset` 在命令層級需要 `operator.admin`。 -這讓較低範圍的操作者可以執行低風險配對動作，而不必讓 -所有配對核准都僅限管理員。 +這讓較低範圍的 operator 可以執行低風險配對動作，而不必讓所有配對核准都僅限 admin。 ## 裝置配對核准 裝置配對記錄是已核准角色與範圍的持久來源。 -已配對的裝置不會悄悄取得更廣的存取權：重新連線時若要求 -更廣的角色或更廣的範圍，會建立新的待處理升級請求。 +已配對的裝置不會默默取得更廣的存取權：如果重新連線時要求更廣的角色或更廣的範圍， +就會建立新的待處理升級請求。 核准裝置請求時： -- 沒有操作者角色的請求不需要操作者權杖範圍核准。 -- 對 `operator.read`、`operator.write`、`operator.approvals`、 - `operator.pairing` 或 `operator.talk.secrets` 的請求，需要呼叫者持有 +- 沒有 operator 角色的請求不需要 operator 權杖範圍核准。 +- 要求 `operator.read`、`operator.write`、`operator.approvals`、 + `operator.pairing` 或 `operator.talk.secrets` 的請求，需要呼叫端持有 這些範圍或 `operator.admin`。 -- 對 `operator.admin` 的請求需要 `operator.admin`。 -- 沒有明確範圍的修復請求可以繼承現有的操作者權杖範圍。 - 如果該現有權杖是管理員範圍，核准仍需要 `operator.admin`。 +- 要求 `operator.admin` 的請求需要 `operator.admin`。 +- 沒有明確範圍的修復請求可以繼承現有 operator 權杖範圍。如果該現有權杖具有 admin 範圍， + 核准仍然需要 `operator.admin`。 -對於已配對裝置權杖工作階段，管理預設限於自身範圍，除非呼叫者 -也具有 `operator.admin`：非管理員呼叫者只能輪替、撤銷或移除 -自己的裝置項目。 +對於已配對裝置的權杖工作階段，管理是自我範圍限定的，除非呼叫端也具有 +`operator.admin`：非 admin 呼叫端只會看到自己的配對項目，只能核准或拒絕自己的待處理請求， +且只能輪替、撤銷或移除自己的裝置項目。 ## Node 配對核准 -舊版 `node.pair.*` 使用另一個由 Gateway 擁有的 Node 配對儲存區。WS Node -會使用具有 `role: node` 的裝置配對，但相同的核准層級詞彙 -仍然適用。 +舊版 `node.pair.*` 使用由 Gateway 擁有的獨立 Node 配對儲存區。WS Node +使用帶有 `role: node` 的裝置配對，但同一組核准層級詞彙仍然適用。 -`node.pair.approve` 會使用待處理請求的命令清單推導額外的 -必要範圍： +`node.pair.approve` 會使用待處理請求的命令清單來衍生額外的必要範圍： - 無命令請求：`operator.pairing` - 非 exec Node 命令：`operator.pairing` + `operator.write` @@ -103,11 +100,11 @@ Operator RPC 方法需要 `operator` 角色。Node 發起的方法 Node 配對會建立身分與信任。它不會取代 Node 自身的 `system.run` exec 核准政策。 -## 共用密鑰驗證 +## 共享密鑰驗證 -共用 Gateway 權杖/密碼驗證會被視為該 Gateway 的可信任操作者存取。 -OpenAI 相容的 HTTP 介面和 `/tools/invoke` 會為共用密鑰 bearer 驗證 -還原一般完整操作者預設範圍集，即使呼叫者送出較窄的宣告範圍也是如此。 +共享 Gateway 權杖/密碼驗證會被視為該 Gateway 的受信任 operator 存取。 +OpenAI 相容 HTTP 介面與 `/tools/invoke` 會為共享密鑰 bearer 驗證還原一般完整的 +operator 預設範圍集合，即使呼叫端傳送較窄的已宣告範圍也是如此。 -帶有身分的模式，例如可信任 Proxy 驗證或私有入口 `none`， -仍可遵循明確宣告的範圍。請使用獨立的 Gateways 來進行真正的信任邊界隔離。 +帶有身分的模式，例如受信任 Proxy 驗證或私有入口 `none`， +仍可遵守明確宣告的範圍。請使用獨立的 Gateway 來實現真正的信任邊界隔離。 diff --git a/docs/zh-TW/plugins/building-plugins.md b/docs/zh-TW/plugins/building-plugins.md index 68d33cfb7..37c95bbc6 100644 --- a/docs/zh-TW/plugins/building-plugins.md +++ b/docs/zh-TW/plugins/building-plugins.md @@ -1,35 +1,39 @@ --- read_when: - - 您想建立新的 OpenClaw Plugin - - 您需要一份 Plugin 開發快速入門指南 - - 你正在為 OpenClaw 新增通道、提供者、工具或其他功能 + - 你想要建立新的 OpenClaw Plugin + - 您需要 Plugin 開發的快速入門指南 + - 你正在為 OpenClaw 新增頻道、提供者、工具或其他功能 sidebarTitle: Getting Started summary: 在幾分鐘內建立你的第一個 OpenClaw Plugin -title: 建構 Plugin +title: 建置 Plugin x-i18n: - generated_at: "2026-05-02T20:51:43Z" + generated_at: "2026-05-04T02:44:25Z" model: gpt-5.5 provider: openai - source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1 + source_hash: 3e6c55c551629da54b3f150ce6299694186fe4434cfd7978a2d43d175d33a5d9 source_path: plugins/building-plugins.md workflow: 16 --- -Plugin 以新功能擴充 OpenClaw：頻道、模型提供者、語音、即時轉錄、即時語音、媒體理解、圖像生成、影片生成、網頁擷取、網頁搜尋、代理工具，或任意組合。 +Plugin 透過新增能力來擴充 OpenClaw：通道、模型提供者、 +語音、即時轉錄、即時語音、媒體理解、影像 +生成、影片生成、網頁擷取、網頁搜尋、代理工具，或任何 +組合。 你不需要將你的 Plugin 加入 OpenClaw 儲存庫。發布到 -[ClawHub](/zh-TW/tools/clawhub)，使用者即可透過 -`openclaw plugins install clawhub:` 安裝。裸套件規格在啟動切換期間仍會從 npm 安裝。 +[ClawHub](/zh-TW/tools/clawhub)，使用者可透過 +`openclaw plugins install clawhub:` 安裝。純套件規格在 +啟動切換期間仍會從 npm 安裝。 ## 先決條件 -- Node >= 22 和套件管理器（npm 或 pnpm） +- Node >= 22 與套件管理器（npm 或 pnpm） - 熟悉 TypeScript（ESM） - 對於儲存庫內 Plugin：已複製儲存庫並完成 `pnpm install`。原始碼 - checkout 的 Plugin 開發僅支援 pnpm，因為 OpenClaw 會從 `extensions/*` 工作區套件載入內建 - Plugin。 + checkout Plugin 開發僅支援 pnpm，因為 OpenClaw 會從 `extensions/*` workspace 套件載入 + 內建 Plugin。 -## 哪一種 Plugin？ +## 哪種 Plugin？ @@ -39,21 +43,22 @@ Plugin 以新功能擴充 OpenClaw：頻道、模型提供者、語音、即時 新增模型提供者（LLM、代理或自訂端點） - 註冊代理工具、事件 hook 或服務 — 請繼續閱讀下方內容 + 註冊代理工具、事件掛鉤或服務 — 繼續閱讀下方內容 -對於無法保證在 onboarding/setup 執行時已安裝的頻道 Plugin，請使用 +對於在 onboarding/setup 執行時不保證已安裝的通道 Plugin，請使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。 -它會產生一組設定配接器與精靈，宣告安裝需求，並在 Plugin 尚未安裝前，對實際設定寫入採取失敗關閉策略。 +它會產生一組 setup adapter + wizard pair，用來宣告安裝需求，並在 Plugin 安裝之前 +對實際設定寫入採取封閉式失敗。 ## 快速開始：工具 Plugin -本逐步說明會建立一個最小 Plugin，用來註冊代理工具。頻道與提供者 -Plugin 有上方連結的專屬指南。 +本逐步指南會建立一個最小 Plugin，用來註冊代理工具。通道 +與提供者 Plugin 有上方連結的專屬指南。 - + ```json package.json { @@ -94,15 +99,15 @@ Plugin 有上方連結的專屬指南。 每個 Plugin 都需要 manifest，即使沒有設定也一樣。執行階段註冊的工具 - 必須列在 `contracts.tools` 中，讓 OpenClaw 不必載入每個 Plugin 執行階段也能發現擁有它的 + 必須列在 `contracts.tools` 中，讓 OpenClaw 不必載入每個 Plugin runtime 也能探索擁有它的 Plugin。Plugin 也應有意識地宣告 - `activation.onStartup`。這個範例將它設為 `true`。完整 schema 請參閱 + `activation.onStartup`。此範例將其設為 `true`。完整 schema 請參閱 [Manifest](/zh-TW/plugins/manifest)。標準 ClawHub 發布片段位於 `docs/snippets/plugin-publish/`。 - + ```typescript // index.ts @@ -126,13 +131,13 @@ Plugin 有上方連結的專屬指南。 }); ``` - `definePluginEntry` 適用於非頻道 Plugin。對於頻道，請使用 + `definePluginEntry` 用於非通道 Plugin。對於通道，請使用 `defineChannelPluginEntry` — 請參閱 [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins)。 - 完整進入點選項請參閱 [Entry Points](/zh-TW/plugins/sdk-entrypoints)。 + 完整的進入點選項請參閱 [Entry Points](/zh-TW/plugins/sdk-entrypoints)。 - + **外部 Plugin：** 使用 ClawHub 驗證並發布，然後安裝： @@ -142,10 +147,10 @@ Plugin 有上方連結的專屬指南。 openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - 像 `@myorg/openclaw-my-plugin` 這樣的裸套件規格會在啟動切換期間從 npm 安裝。 - 想使用 ClawHub 解析時，請使用 `clawhub:`。 + 像 `@myorg/openclaw-my-plugin` 這樣的純套件規格會在 + 啟動切換期間從 npm 安裝。需要 ClawHub 解析時請使用 `clawhub:`。 - **儲存庫內 Plugin：** 放在內建 Plugin 工作區樹狀結構下 — 會自動被發現。 + **儲存庫內 Plugin：** 放在內建 Plugin workspace 樹下 — 會自動被探索。 ```bash pnpm test -- /my-plugin/ @@ -154,20 +159,20 @@ Plugin 有上方連結的專屬指南。 -## Plugin 功能 +## Plugin 能力 -單一 Plugin 可以透過 `api` 物件註冊任意數量的功能： +單一 Plugin 可以透過 `api` 物件註冊任意數量的能力： -| 功能 | 註冊方法 | 詳細指南 | +| 能力 | 註冊方法 | 詳細指南 | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | | 文字推論（LLM） | `api.registerProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) | | CLI 推論後端 | `api.registerCliBackend(...)` | [CLI Backends](/zh-TW/gateway/cli-backends) | -| 頻道 / 訊息 | `api.registerChannel(...)` | [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) | +| 通道 / 訊息 | `api.registerChannel(...)` | [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) | | 語音（TTS/STT） | `api.registerSpeechProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 即時轉錄 | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 即時語音 | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 媒體理解 | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 圖像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 影像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 音樂生成 | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 影片生成 | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 網頁擷取 | `api.registerWebFetchProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | @@ -175,47 +180,49 @@ Plugin 有上方連結的專屬指南。 | 工具結果 middleware | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/zh-TW/plugins/sdk-overview#registration-api) | | 代理工具 | `api.registerTool(...)` | 下方 | | 自訂命令 | `api.registerCommand(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) | -| Plugin hook | `api.on(...)` | [Plugin hooks](/zh-TW/plugins/hooks) | -| 內部事件 hook | `api.registerHook(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) | +| Plugin hooks | `api.on(...)` | [Plugin hooks](/zh-TW/plugins/hooks) | +| 內部事件掛鉤 | `api.registerHook(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) | | HTTP 路由 | `api.registerHttpRoute(...)` | [Internals](/zh-TW/plugins/architecture-internals#gateway-http-routes) | | CLI 子命令 | `api.registerCli(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) | 完整註冊 API 請參閱 [SDK Overview](/zh-TW/plugins/sdk-overview#registration-api)。 -內建 Plugin 在需要於模型看到輸出前進行非同步工具結果重寫時，可以使用 `api.registerAgentToolResultMiddleware(...)`。 -請在 `contracts.agentToolResultMiddleware` 中宣告目標執行階段，例如 -`["pi", "codex"]`。這是受信任的內建 Plugin seam；外部 -Plugin 應優先使用一般 OpenClaw Plugin hook，除非 OpenClaw 為此功能增加明確的信任政策。 +內建 Plugin 在需要於模型看到輸出之前進行非同步工具結果重寫時， +可以使用 `api.registerAgentToolResultMiddleware(...)`。請在 +`contracts.agentToolResultMiddleware` 中宣告目標 runtime，例如 +`["pi", "codex"]`。這是一個受信任的內建 Plugin seam；外部 +Plugin 應優先使用一般 OpenClaw Plugin hooks，除非 OpenClaw 為此能力新增 +明確的信任政策。 -如果你的 Plugin 註冊自訂 Gateway RPC 方法，請將它們保留在 +如果你的 Plugin 註冊自訂 Gateway RPC 方法，請將它們放在 Plugin 專屬前綴下。核心管理命名空間（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）會保持保留，且一律解析為 -`operator.admin`，即使 Plugin 要求較窄的 scope 也是如此。 +`exec.approvals.*`、`wizard.*`、`update.*`）會保留，且永遠解析為 +`operator.admin`，即使 Plugin 要求較窄的 scope 也一樣。 -需要記住的 hook guard 語意： +請記住以下 hook guard 語意： -- `before_tool_call`：`{ block: true }` 是終止性決策，並會停止較低優先級的處理常式。 +- `before_tool_call`：`{ block: true }` 是終止結果，會停止較低優先序的 handler。 - `before_tool_call`：`{ block: false }` 會被視為沒有決策。 -- `before_tool_call`：`{ requireApproval: true }` 會暫停代理執行，並透過 exec 核准覆蓋層、Telegram 按鈕、Discord 互動，或任何頻道上的 `/approve` 命令提示使用者核准。 -- `before_install`：`{ block: true }` 是終止性決策，並會停止較低優先級的處理常式。 +- `before_tool_call`：`{ requireApproval: true }` 會暫停代理執行，並透過 exec approval overlay、Telegram 按鈕、Discord 互動，或任何通道上的 `/approve` 命令提示使用者核准。 +- `before_install`：`{ block: true }` 是終止結果，會停止較低優先序的 handler。 - `before_install`：`{ block: false }` 會被視為沒有決策。 -- `message_sending`：`{ cancel: true }` 是終止性決策，並會停止較低優先級的處理常式。 +- `message_sending`：`{ cancel: true }` 是終止結果，會停止較低優先序的 handler。 - `message_sending`：`{ cancel: false }` 會被視為沒有決策。 -- `message_received`：需要傳入 thread/topic 路由時，請優先使用型別化的 `threadId` 欄位。將 `metadata` 保留給頻道專屬的額外資訊。 -- `message_sending`：請優先使用型別化的 `replyToId` / `threadId` 路由欄位，而不是頻道專屬的 metadata key。 +- `message_received`：需要傳入 thread/topic routing 時，請優先使用型別化的 `threadId` 欄位。將 `metadata` 保留給通道特定的額外資訊。 +- `message_sending`：請優先使用型別化的 `replyToId` / `threadId` routing 欄位，而不是通道特定的 metadata key。 -`/approve` 命令會以有界 fallback 處理 exec 與 Plugin 核准：找不到 exec 核准 id 時，OpenClaw 會以相同 id 重試 Plugin 核准。Plugin 核准轉送可透過設定中的 `approvals.plugin` 獨立設定。 +`/approve` 命令會以有界 fallback 處理 exec 與 Plugin approval：找不到 exec approval id 時，OpenClaw 會用相同 id 透過 Plugin approval 重試。Plugin approval forwarding 可以透過設定中的 `approvals.plugin` 獨立設定。 -如果自訂核准接線需要偵測相同的有界 fallback 情況， -請優先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`， -而不是手動比對核准到期字串。 +如果自訂 approval plumbing 需要偵測同一個有界 fallback 情況， +請優先使用 `openclaw/plugin-sdk/error-runtime` 的 `isApprovalNotFoundError`， +而不是手動比對 approval 到期字串。 -範例與 hook 參考請參閱 [Plugin hooks](/zh-TW/plugins/hooks)。 +範例與 hook reference 請參閱 [Plugin hooks](/zh-TW/plugins/hooks)。 ## 註冊代理工具 -工具是 LLM 可以呼叫的型別化函式。它們可以是必要的（永遠 -可用）或選用的（使用者選擇加入）： +工具是 LLM 可以呼叫的型別化函式。它們可以是必要（永遠 +可用）或選用（使用者 opt-in）： ```typescript register(api) { @@ -244,23 +251,31 @@ register(api) { } ``` -每個透過 `api.registerTool(...)` 註冊的工具，也必須在 +所有透過 `api.registerTool(...)` 註冊的工具，也必須在 Plugin manifest 中宣告： ```json { "contracts": { "tools": ["my_tool", "workflow_tool"] + }, + "toolMetadata": { + "workflow_tool": { + "optional": true + } } } ``` -OpenClaw 會擷取並快取已註冊工具的已驗證描述子， -因此 Plugin 不需要在 manifest 中重複 `description` 或 schema 資料。 -manifest contract 只宣告擁有權與發現；執行仍會呼叫 -即時註冊的工具實作。 +OpenClaw 會擷取並快取已註冊工具中通過驗證的描述元， +因此 plugins 不需要在 manifest 中重複 `description` 或 schema 資料。這個 +manifest 合約只宣告擁有權與探索；執行時仍會呼叫 +即時註冊工具的實作。 +對於使用 `api.registerTool(..., { optional: true })` 註冊的工具，請設定 +`toolMetadata..optional: true`，讓 OpenClaw 可以避免載入該 +plugin runtime，直到此工具被明確加入允許清單。 -使用者可在設定中啟用選用工具： +使用者可在設定中啟用 optional tools： ```json5 { @@ -268,14 +283,16 @@ manifest contract 只宣告擁有權與發現；執行仍會呼叫 } ``` -- 工具名稱不得與核心工具衝突（衝突項目會被略過） -- 註冊物件格式錯誤的工具（包括缺少 `parameters`）會被略過，並改在 Plugin 診斷中回報，而不是中斷代理程式執行 -- 對於具有副作用或需要額外二進位檔的工具，請使用 `optional: true` -- 使用者可以將 Plugin ID 加到 `tools.allow`，以啟用某個 Plugin 的所有工具 +- 工具名稱不得與 core tools 衝突（衝突項目會被略過） +- 含有格式錯誤註冊物件的工具，包括缺少 `parameters`，會被略過並在 plugin diagnostics 中回報，而不是中斷 agent 執行 +- 對具有副作用或額外 binary 需求的工具使用 `optional: true` +- 使用者可以將 plugin id 加入 `tools.allow`，以啟用某個 plugin 的所有工具 ## 註冊 CLI 指令 -Plugin 可以透過 `api.registerCli` 新增根層級 `openclaw` 指令群組。請為每個頂層指令根提供 `descriptors`，讓 OpenClaw 不必急切載入每個 Plugin 執行階段，就能顯示並路由該指令。 +Plugins 可以使用 `api.registerCli` 新增 root `openclaw` command groups。請為 +每個頂層命令 root 提供 `descriptors`，讓 OpenClaw 可以顯示並路由 +該命令，而不必急切載入每個 plugin runtime。 ```typescript register(api) { @@ -305,7 +322,7 @@ register(api) { } ``` -安裝後，驗證執行階段註冊並執行指令： +安裝後，請驗證 runtime 註冊並執行指令： ```bash openclaw plugins inspect demo-plugin --runtime --json @@ -324,53 +341,58 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { ... } from "openclaw/plugin-sdk"; ``` -完整子路徑參考請見 [SDK 概覽](/zh-TW/plugins/sdk-overview)。 +完整的 subpath 參考請見 [SDK 概覽](/zh-TW/plugins/sdk-overview)。 -在你的 Plugin 內，請使用本機 barrel 檔案（`api.ts`、`runtime-api.ts`）進行內部匯入，絕對不要透過其 SDK 路徑匯入自己的 Plugin。 +在你的 plugin 中，請使用本機 barrel files（`api.ts`、`runtime-api.ts`）進行 +內部匯入，不要透過 SDK 路徑匯入自己的 plugin。 -對於提供者 Plugin，請將提供者特定的輔助工具保留在那些套件根層級 barrel 中，除非該接縫確實是通用的。目前的內建範例： +對於 provider plugins，請將 provider-specific helpers 保留在那些 package-root +barrels 中，除非該 seam 確實是通用的。目前 bundled examples： -- Anthropic：Claude 串流包裝器與 `service_tier` / beta 輔助工具 -- OpenAI：提供者建構器、預設模型輔助工具、即時提供者 -- OpenRouter：提供者建構器加上 onboarding/設定輔助工具 +- Anthropic：Claude stream wrappers 與 `service_tier` / beta helpers +- OpenAI：provider builders、default-model helpers、realtime providers +- OpenRouter：provider builder 加上 onboarding/config helpers -如果某個輔助工具只在單一內建提供者套件內有用，請將它保留在該套件根層級接縫上，而不是提升到 `openclaw/plugin-sdk/*`。 +如果某個 helper 只在單一 bundled provider package 內有用，請將它保留在該 +package-root seam，而不是提升到 `openclaw/plugin-sdk/*`。 -部分產生的 `openclaw/plugin-sdk/` 輔助接縫仍存在，用於有追蹤擁有者使用情況的內建 Plugin 維護。請將這些視為保留介面，而不是新第三方 Plugin 的預設模式。 +部分產生的 `openclaw/plugin-sdk/` helper seams 仍存在， +用於有追蹤擁有者使用情境的 bundled-plugin 維護。請將這些視為 +保留介面，而不是新 third-party plugins 的預設模式。 ## 提交前檢查清單 -**package.json** 具有正確的 `openclaw` 中繼資料 +**package.json** 具有正確的 `openclaw` metadata **openclaw.plugin.json** manifest 存在且有效 進入點使用 `defineChannelPluginEntry` 或 `definePluginEntry` 所有匯入都使用聚焦的 `plugin-sdk/` 路徑 -內部匯入使用本機模組，而非 SDK 自我匯入 +內部匯入使用本機模組，而不是 SDK self-imports 測試通過（`pnpm test -- /my-plugin/`） -`pnpm check` 通過（儲存庫內 Plugin） +`pnpm check` 通過（repo 內 plugins） -## Beta 發布測試 +## Beta 版本測試 -1. 留意 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 發布標籤，並透過 `Watch` > `Releases` 訂閱。Beta 標籤看起來像 `v2026.3.N-beta.1`。你也可以開啟官方 OpenClaw X 帳號 [@openclaw](https://x.com/openclaw) 的通知，以接收發布公告。 -2. Beta 標籤一出現，就立即針對它測試你的 Plugin。穩定版發布前的時間窗口通常只有幾個小時。 -3. 測試後，請在 `plugin-forum` Discord 頻道中你的 Plugin 討論串張貼 `all good` 或說明壞掉的內容。如果你還沒有討論串，請建立一個。 -4. 如果有東西壞掉，請開啟或更新標題為 `Beta blocker: - ` 的 issue，並套用 `beta-blocker` 標籤。將 issue 連結放到你的討論串中。 -5. 開啟一個指向 `main`、標題為 `fix(): beta blocker - ` 的 PR，並在 PR 和你的 Discord 討論串中連結該 issue。貢獻者無法替 PR 加標籤，因此標題是給維護者與自動化使用的 PR 端訊號。有 PR 的阻擋問題會被合併；沒有 PR 的阻擋問題仍可能照常發布。維護者會在 beta 測試期間關注這些討論串。 -6. 沉默代表綠燈。如果你錯過時間窗口，你的修正很可能會在下一個週期落地。 +1. 追蹤 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub release tags，並透過 `Watch` > `Releases` 訂閱。Beta tags 形式像 `v2026.3.N-beta.1`。你也可以開啟官方 OpenClaw X 帳號 [@openclaw](https://x.com/openclaw) 的通知，以接收 release 公告。 +2. Beta tag 一出現，請盡快用它測試你的 plugin。進入 stable 前的時間窗口通常只有幾個小時。 +3. 測試後，在 `plugin-forum` Discord channel 中你的 plugin thread 發文，內容可為 `all good` 或說明哪裡壞了。如果你還沒有 thread，請建立一個。 +4. 如果發生問題，請開啟或更新標題為 `Beta blocker: - ` 的 issue，並套用 `beta-blocker` label。將 issue link 放到你的 thread 中。 +5. 開啟一個指向 `main` 的 PR，標題為 `fix(): beta blocker - `，並在 PR 和你的 Discord thread 中連結該 issue。Contributors 無法為 PR 加 label，因此標題是給 maintainers 與 automation 的 PR 端訊號。有 PR 的 blockers 會被合併；沒有 PR 的 blockers 可能仍會照常發布。Maintainers 會在 beta testing 期間關注這些 threads。 +6. 沉默表示綠燈。如果你錯過窗口，你的修正很可能會進入下一個 cycle。 ## 下一步 - - 建置訊息通道 Plugin + + 建置 messaging channel plugin - 建置模型提供者 Plugin + 建置 model provider plugin - 匯入對應與註冊 API 參考 + Import map 與 registration API 參考 - - TTS、搜尋、透過 api.runtime 使用 subagent + + 透過 api.runtime 使用 TTS、search、subagent 測試工具與模式 @@ -384,6 +406,6 @@ import { ... } from "openclaw/plugin-sdk"; - [Plugin 架構](/zh-TW/plugins/architecture) — 內部架構深入解析 - [SDK 概覽](/zh-TW/plugins/sdk-overview) — Plugin SDK 參考 -- [Manifest](/zh-TW/plugins/manifest) — Plugin manifest 格式 -- [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) — 建置通道 Plugin -- [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) — 建置提供者 Plugin +- [Manifest](/zh-TW/plugins/manifest) — plugin manifest 格式 +- [通道 Plugins](/zh-TW/plugins/sdk-channel-plugins) — 建置 channel plugins +- [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) — 建置 provider plugins diff --git a/docs/zh-TW/plugins/google-meet.md b/docs/zh-TW/plugins/google-meet.md index f3929ba84..9a1aee7b7 100644 --- a/docs/zh-TW/plugins/google-meet.md +++ b/docs/zh-TW/plugins/google-meet.md @@ -1,36 +1,44 @@ --- read_when: - - 您想讓 OpenClaw 代理程式加入 Google Meet 通話 - - 你想讓 OpenClaw 代理程式建立新的 Google Meet 通話 - - 你正在將 Chrome、Chrome 節點或 Twilio 設定為 Google Meet 傳輸方式 -summary: Google Meet Plugin：透過 Chrome 或 Twilio 加入明確指定的 Meet URL，並套用即時語音預設值 + - 你想讓 OpenClaw 代理加入 Google Meet 通話 + - 你想讓 OpenClaw 代理建立新的 Google Meet 通話 + - 你正在將 Chrome、Chrome 節點或 Twilio 設定為 Google Meet 傳輸通道 +summary: Google Meet Plugin：透過 Chrome 或 Twilio 加入明確指定的 Meet URL，並使用代理程式回話預設值 title: Google Meet Plugin x-i18n: - generated_at: "2026-05-02T20:52:12Z" + generated_at: "2026-05-04T02:45:13Z" model: gpt-5.5 provider: openai - source_hash: 0dc515382d2cc7beacaf18a50b75cb0f4eda3038cfd8efe73ea3ce7b5007bc43 + source_hash: 79d04eb50b157863cce9b03f1195ae01628f21966267485df1e489c843e55826 source_path: plugins/google-meet.md workflow: 16 --- -OpenClaw 的 Google Meet 參與者支援是刻意設計為明確操作的 Plugin： +Google Meet 參與者支援對 OpenClaw 而言是刻意明確設計的 Plugin： - 它只會加入明確的 `https://meet.google.com/...` URL。 -- 它可以透過 Google Meet API 建立新的 Meet 空間，然後加入傳回的 URL。 -- `realtime` 語音是預設模式。 -- 當需要更深入的推理或工具時，即時語音可以回呼完整的 OpenClaw agent。 -- Agents 透過 `mode` 選擇加入行為：使用 `realtime` 進行即時聆聽/回話，或使用 `transcribe` 加入/控制瀏覽器而不啟用即時語音橋接。 -- 驗證一開始可使用個人 Google OAuth 或已登入的 Chrome 設定檔。 -- 沒有自動同意公告。 -- 預設的 Chrome 音訊後端是 `BlackHole 2ch`。 -- Chrome 可以在本機執行，也可以在配對的 Node 主機上執行。 -- Twilio 接受撥入號碼以及可選的 PIN 或 DTMF 序列；它無法直接撥打 Meet URL。 -- CLI 指令是 `googlemeet`；`meet` 保留給更廣泛的 agent 電話會議工作流程。 +- 它可以透過 Google Meet API 建立新的 Meet 空間，然後加入傳回的 + URL。 +- `agent` 是預設的回話模式：即時轉錄會聆聽，已設定的 OpenClaw agent 會回答，而一般 OpenClaw TTS 會在 Meet 中發聲。 +- `bidi` 仍可作為備援的直接即時語音模型模式。 +- Agents 會用 `mode` 選擇加入行為：使用 `agent` 進行即時 + 聆聽/回話，使用 `bidi` 作為直接即時語音備援，或使用 `transcribe` + 加入/控制瀏覽器而不啟用回話橋接。 +- 驗證一開始支援個人 Google OAuth，或已登入的 Chrome profile。 +- 沒有自動同意宣告。 +- 預設 Chrome 音訊後端是 `BlackHole 2ch`。 +- Chrome 可以在本機執行，或在已配對的 node host 上執行。 +- Twilio 接受撥入號碼，以及選用的 PIN 或 DTMF 序列；它 + 無法直接撥打 Meet URL。 +- CLI 命令是 `googlemeet`；`meet` 保留給更廣泛的 agent + 電話會議工作流程。 ## 快速開始 -安裝本機音訊相依項，並設定後端即時語音提供者。OpenAI 是預設值；Google Gemini Live 也可搭配 `realtime.provider: "google"` 使用： +安裝本機音訊相依項目，並設定即時轉錄 +provider 加上一般 OpenClaw TTS。OpenAI 是預設轉錄 +provider；Google Gemini Live 也可搭配 `realtime.provider: "google"` 用於 +`bidi` 模式： ```bash brew install blackhole-2ch sox @@ -39,13 +47,14 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` 會安裝 `BlackHole 2ch` 虛擬音訊裝置。Homebrew 的安裝程式需要重新開機，macOS 才會公開該裝置： +`blackhole-2ch` 會安裝 `BlackHole 2ch` 虛擬音訊裝置。Homebrew 的 +安裝程式需要重新開機，macOS 才會公開該裝置： ```bash sudo reboot ``` -重新開機後，驗證兩個項目： +重新開機後，驗證兩個部分： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -73,21 +82,32 @@ command -v sox openclaw googlemeet setup ``` -設定輸出的用途是讓 agent 可讀取，並且會感知模式。它會回報 Chrome 設定檔、Node 固定，以及針對即時 Chrome 加入，回報 BlackHole/SoX 音訊橋接和延遲即時介紹檢查。若是僅觀察加入，請使用 `--mode transcribe` 檢查相同傳輸；該模式會略過即時音訊先決條件，因為它不會透過橋接聆聽或說話： +設定輸出設計為 agent 可讀且會感知模式。它會回報 Chrome +profile、node 固定，以及針對即時 Chrome 加入，回報 BlackHole/SoX 音訊 +橋接與延遲即時開場檢查。若為僅觀察加入，請使用 `--mode transcribe` 檢查相同的 +傳輸；該模式會略過即時音訊前置需求，因為它不會透過橋接 +聆聽或發聲： ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -設定 Twilio 委派時，setup 也會回報 `voice-call` Plugin、Twilio 憑證和公開 Webhook 暴露是否就緒。請在要求 agent 加入之前，將任何 `ok: false` 檢查視為所檢查傳輸和模式的阻斷項。腳本或機器可讀輸出請使用 `openclaw googlemeet setup --json`。在 agent 嘗試前，使用 `--transport chrome`、`--transport chrome-node` 或 `--transport twilio` 預檢特定傳輸。 +設定 Twilio 委派時，設定也會回報 +`voice-call` Plugin、Twilio 憑證，以及公開 Webhook 暴露是否就緒。 +在要求 agent 加入前，請將任何 `ok: false` 檢查視為所檢查傳輸與模式的 +阻擋項目。使用 `openclaw googlemeet setup --json` 取得 +scripts 或機器可讀輸出。使用 `--transport chrome`、 +`--transport chrome-node`，或 `--transport twilio`，在 agent 嘗試前預檢特定 +傳輸。 -對 Twilio 而言，當預設傳輸是 Chrome 時，請一律明確預檢傳輸： +對 Twilio 而言，當預設傳輸是 Chrome 時，請一律明確預檢該傳輸： ```bash openclaw googlemeet setup --transport twilio ``` -這會在 agent 嘗試撥打會議前，捕捉缺少的 `voice-call` 接線、Twilio 憑證或無法連線的 Webhook 暴露。 +這會在 agent 嘗試撥打會議前，捕捉缺少的 `voice-call` 接線、Twilio 憑證，或無法連線的 +Webhook 暴露。 加入會議： @@ -102,27 +122,39 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij "action": "join", "url": "https://meet.google.com/abc-defg-hij", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` -面向 agent 的 `google_meet` 工具在非 macOS 主機上仍可用於成品、行事曆、設定、轉錄、Twilio 和 `chrome-node` 流程。本機 Chrome 即時動作會在該處被阻擋，因為內建的即時 Chrome 音訊路徑目前依賴 macOS `BlackHole 2ch`。在 Linux 上，請使用 `mode: "transcribe"`、Twilio 撥入，或 macOS `chrome-node` 主機進行即時 Chrome 參與。 +面向 agent 的 `google_meet` 工具在非 macOS host 上仍可用於 +artifact、calendar、setup、transcribe、Twilio 和 `chrome-node` 流程。本機 +Chrome 回話動作在那些 host 上會被阻擋，因為內建的 Chrome 音訊路徑 +目前依賴 macOS `BlackHole 2ch`。在 Linux 上，請使用 `mode: "transcribe"`、 +Twilio 撥入，或 macOS `chrome-node` host 進行 Chrome 回話 +參與。 建立新會議並加入： ```bash -openclaw googlemeet create --transport chrome-node --mode realtime +openclaw googlemeet create --transport chrome-node --mode agent ``` -對 API 建立的會議室，當你希望會議室的免敲門政策明確設定，而不是繼承自 Google 帳戶預設值時，請使用 Google Meet `SpaceConfig.accessType`： +對 API 建立的房間，若你希望房間的免敲門政策是明確指定，而不是繼承自 Google +帳戶預設值，請使用 Google Meet `SpaceConfig.accessType`： ```bash -openclaw googlemeet create --access-type OPEN --transport chrome-node --mode realtime +openclaw googlemeet create --access-type OPEN --transport chrome-node --mode agent ``` -`OPEN` 允許任何持有 Meet URL 的人不需敲門即可加入。`TRUSTED` 允許主辦者組織中的受信任使用者、受邀外部使用者和撥入使用者不需敲門即可加入。`RESTRICTED` 將免敲門進入限制為受邀者。這些設定只適用於官方 Google Meet API 建立路徑，因此必須設定 OAuth 憑證。 +`OPEN` 允許任何持有 Meet URL 的人免敲門加入。`TRUSTED` 允許 +host 組織的受信任使用者、受邀的外部使用者，以及撥入使用者 +免敲門加入。`RESTRICTED` 將免敲門進入限制為受邀者。這些 +設定只適用於官方 Google Meet API 建立路徑，因此必須已設定 OAuth +憑證。 -如果你在此選項可用之前已驗證 Google Meet，請在將 `meetings.space.settings` 範圍新增到你的 Google OAuth 同意畫面後，重新執行 `openclaw googlemeet auth login --json`。 +如果你在此選項可用前已驗證 Google Meet，請在將 +`meetings.space.settings` scope 加入你的 Google OAuth 同意畫面後，重新執行 +`openclaw googlemeet auth login --json`。 只建立 URL 而不加入： @@ -132,40 +164,86 @@ openclaw googlemeet create --no-join `googlemeet create` 有兩條路徑： -- API 建立：在已設定 Google Meet OAuth 憑證時使用。這是最具決定性的路徑，且不依賴瀏覽器 UI 狀態。 -- 瀏覽器後援：在缺少 OAuth 憑證時使用。OpenClaw 使用固定的 Chrome Node，開啟 `https://meet.google.com/new`，等待 Google 重新導向到真實的會議代碼 URL，然後傳回該 URL。此路徑要求 Node 上的 OpenClaw Chrome 設定檔已登入 Google。瀏覽器自動化會處理 Meet 自己的首次執行麥克風提示；該提示不會被視為 Google 登入失敗。 - 加入和建立流程也會先嘗試重用現有的 Meet 分頁，再開啟新分頁。比對時會忽略無害的 URL 查詢字串，例如 `authuser`，因此 agent 重試時應聚焦已開啟的會議，而不是建立第二個 Chrome 分頁。 +- API create：在已設定 Google Meet OAuth 憑證時使用。這是 + 最具決定性的路徑，且不依賴瀏覽器 UI 狀態。 +- Browser fallback：在缺少 OAuth 憑證時使用。OpenClaw 使用 + 固定的 Chrome node，開啟 `https://meet.google.com/new`，等待 Google + 重新導向至真正的會議代碼 URL，然後傳回該 URL。此路徑要求 + node 上的 OpenClaw Chrome profile 已登入 Google。 + 瀏覽器自動化會處理 Meet 自身的首次執行麥克風提示；該提示 + 不會被視為 Google 登入失敗。 + 加入與建立流程也會在開啟新分頁前嘗試重用既有 Meet 分頁。 + 比對會忽略無害的 URL 查詢字串，例如 `authuser`，因此 agent 重試 + 應聚焦已開啟的會議，而不是建立第二個 + Chrome 分頁。 -指令/工具輸出包含 `source` 欄位（`api` 或 `browser`），讓 agents 可以說明使用了哪條路徑。`create` 預設會加入新會議，並傳回 `joined: true` 加上加入工作階段。若只要產生 URL，請在 CLI 使用 `create --no-join`，或將 `"join": false` 傳給工具。 +命令/工具輸出包含 `source` 欄位（`api` 或 `browser`），讓 agents +可以說明使用了哪條路徑。`create` 預設會加入新會議，並 +傳回 `joined: true` 加上加入 session。若只要產生 URL，請在 +CLI 使用 `create --no-join`，或向工具傳入 `"join": false`。 -或告訴 agent：「建立一個 Google Meet，用即時語音加入，並把連結傳給我。」agent 應以 `action: "create"` 呼叫 `google_meet`，然後分享傳回的 `meetingUri`。 +或告訴 agent：「建立一個 Google Meet，用 agent 回話模式加入， +然後把連結傳給我。」agent 應使用 +`action: "create"` 呼叫 `google_meet`，然後分享傳回的 `meetingUri`。 ```json { "action": "create", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` -若要僅觀察/瀏覽器控制加入，請設定 `"mode": "transcribe"`。這不會啟動雙工即時模型橋接，不需要 BlackHole 或 SoX，也不會在會議中回話。此模式下的 Chrome 加入也會避免 OpenClaw 的麥克風/攝影機權限授與，並避免 Meet **使用麥克風** 路徑。如果 Meet 顯示音訊選擇插頁，自動化會嘗試無麥克風路徑，否則會回報需要手動操作，而不是開啟本機麥克風。在轉錄模式中，受管理的 Chrome 傳輸也會安裝盡力而為的 Meet 字幕觀察器。`googlemeet status --json` 和 `googlemeet doctor` 會顯示 `captioning`、`captionsEnabledAttempted`、`transcriptLines`、`lastCaptionAt`、`lastCaptionSpeaker`、`lastCaptionText`，以及一段簡短的 `recentTranscript` 尾端，讓操作者判斷瀏覽器是否已加入通話，以及 Meet 字幕是否正在產生文字。 -當你需要是/否探測時，請使用 `openclaw googlemeet test-listen --transport chrome-node`：它會以轉錄模式加入，等待新的字幕或轉錄變動，並傳回 `listenVerified`、`listenTimedOut`、手動操作欄位，以及最新的字幕健康狀態。 +若要僅觀察/瀏覽器控制的加入，請設定 `"mode": "transcribe"`。這不會 +啟動雙工即時語音橋接，不需要 BlackHole 或 SoX， +也不會在會議中回話。此模式中的 Chrome 加入也會避免 +OpenClaw 的麥克風/相機權限授與，並避免 Meet **使用 +麥克風** 路徑。若 Meet 顯示音訊選擇插頁，自動化會嘗試 +無麥克風路徑，否則回報需要手動操作，而不是開啟 +本機麥克風。在 transcribe 模式中，受管理的 Chrome 傳輸也會安裝 +盡力而為的 Meet 字幕觀察器。`googlemeet status --json` 和 +`googlemeet doctor` 會顯示 `captioning`、`captionsEnabledAttempted`、 +`transcriptLines`、`lastCaptionAt`、`lastCaptionSpeaker`、`lastCaptionText` +以及簡短的 `recentTranscript` 尾端，讓操作員能判斷瀏覽器 +是否已加入通話，以及 Meet 字幕是否正在產生文字。 +需要是/否探測時，請使用 `openclaw googlemeet test-listen --transport chrome-node`： +它會以 transcribe 模式加入，等待新的字幕或 +轉錄變化，並傳回 `listenVerified`、`listenTimedOut`、手動 +操作欄位，以及最新的字幕健康狀態。 -即時工作階段期間，`google_meet` 狀態包含瀏覽器和音訊橋接健康狀態，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、上次輸入/輸出時間戳、位元組計數器，以及橋接關閉狀態。如果出現安全的 Meet 頁面提示，瀏覽器自動化會在可行時處理它。登入、主辦者准入和瀏覽器/作業系統權限提示會回報為需要手動操作，並附上原因和訊息供 agent 轉述。受管理的 Chrome 工作階段只會在瀏覽器健康狀態回報 `inCall: true` 後發出介紹或測試短語；否則狀態會回報 `speechReady: false`，並阻擋語音嘗試，而不是假裝 agent 已在會議中說話。 +在即時 session 期間，`google_meet` status 包含瀏覽器與音訊橋接 +健康狀態，例如 `inCall`、`manualActionRequired`、`providerConnected`、 +`realtimeReady`、`audioInputActive`、`audioOutputActive`、最後輸入/輸出 +時間戳、位元組計數，以及橋接關閉狀態。若出現安全的 Meet 頁面提示， +瀏覽器自動化會在可行時處理。登入、host 准入，以及 +瀏覽器/作業系統權限提示會被回報為手動操作，並附上原因與 +訊息供 agent 轉述。受管理的 Chrome sessions 只有在瀏覽器健康狀態回報 +`inCall: true` 後才會發出開場或測試詞句；否則 status 會回報 +`speechReady: false`，且語音嘗試會被阻擋，而不是假裝 +agent 已在會議中發聲。 -本機 Chrome 會透過已登入的 OpenClaw 瀏覽器設定檔加入。即時模式需要 `BlackHole 2ch`，用於 OpenClaw 使用的麥克風/喇叭路徑。若要乾淨的雙工音訊，請使用分離的虛擬裝置或 Loopback 風格的圖；單一 BlackHole 裝置足以進行第一次煙霧測試，但可能會產生回音。 +本機 Chrome 透過已登入的 OpenClaw 瀏覽器 profile 加入。即時模式 +需要 `BlackHole 2ch` 供 OpenClaw 使用的麥克風/喇叭路徑。為了 +乾淨的雙工音訊，請使用分離的虛擬裝置或 Loopback 風格圖形；單一 BlackHole +裝置足以進行第一次煙霧測試，但可能產生回音。 ### 本機 Gateway + Parallels Chrome -若只是要讓 VM 擁有 Chrome，你**不**需要在 macOS VM 內放置完整 OpenClaw Gateway 或模型 API key。請在本機執行 Gateway 和 agent，然後在 VM 內執行 Node 主機。在 VM 上啟用一次內建 Plugin，讓 Node 公告 Chrome 指令： +只為了讓 VM 擁有 Chrome，你**不**需要在 macOS VM 內放完整的 OpenClaw Gateway 或模型 API key。 +在本機執行 Gateway 和 agent，然後在 VM 中執行 +node host。在 VM 上啟用一次內建 Plugin，讓 node +宣告 Chrome 命令： -各處執行內容： +各自執行的位置： -- Gateway 主機：OpenClaw Gateway、agent 工作區、模型/API keys、即時提供者，以及 Google Meet Plugin 設定。 -- Parallels macOS VM：OpenClaw CLI/Node 主機、Google Chrome、SoX、BlackHole 2ch，以及已登入 Google 的 Chrome 設定檔。 -- VM 中不需要：Gateway 服務、agent 設定、OpenAI/GPT key，或模型提供者設定。 +- Gateway host：OpenClaw Gateway、agent 工作區、模型/API keys、即時 + provider，以及 Google Meet Plugin 設定。 +- Parallels macOS VM：OpenClaw CLI/node host、Google Chrome、SoX、BlackHole 2ch， + 以及已登入 Google 的 Chrome profile。 +- VM 中不需要：Gateway service、agent config、OpenAI/GPT key，或模型 + provider 設定。 -安裝 VM 相依項： +安裝 VM 相依項目： ```bash brew install blackhole-2ch sox @@ -177,7 +255,7 @@ brew install blackhole-2ch sox sudo reboot ``` -重新開機後，驗證 VM 能看到音訊裝置和 SoX 指令： +重新開機後，驗證 VM 能看到音訊裝置與 SoX 命令： ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -190,20 +268,21 @@ command -v sox openclaw plugins enable google-meet ``` -在 VM 中啟動 Node 主機： +在 VM 中啟動 node host： ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -如果 `` 是 LAN IP 且你未使用 TLS，除非你針對該受信任的私人網路選擇加入，否則 Node 會拒絕純文字 WebSocket： +如果 `` 是 LAN IP，而且你沒有使用 TLS，node 會拒絕 +明文 WebSocket，除非你為該受信任的私人網路明確選擇加入： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -將 Node 安裝為 LaunchAgent 時，請使用相同環境變數： +安裝 node 作為 LaunchAgent 時，使用相同的環境變數： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -211,22 +290,25 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是程序環境，不是 `openclaw.json` 設定。當它出現在安裝指令上時，`openclaw node install` 會將它儲存在 LaunchAgent 環境中。 +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是程序環境，而不是 +`openclaw.json` 設定。當它出現在安裝命令上時，`openclaw node install` +會把它儲存在 LaunchAgent 環境中。 -從 Gateway 主機核准 Node： +從 Gateway host 核准 node： ```bash openclaw devices list openclaw devices approve ``` -確認 Gateway 看得到 Node，並且它公告 `googlemeet.chrome` 和瀏覽器 capability/`browser.proxy`： +確認 Gateway 看得到 node，且它宣告了 `googlemeet.chrome` +與瀏覽器 capability/`browser.proxy`： ```bash openclaw nodes status ``` -在 Gateway 主機上透過該 Node 路由 Meet： +在 Gateway host 上透過該 node 路由 Meet： ```json5 { @@ -256,86 +338,64 @@ openclaw nodes status } ``` -現在從 Gateway 主機正常加入： +現在從 Gateway host 正常加入： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -或要求 agent 使用帶有 `transport: "chrome-node"` 的 `google_meet` 工具。 +或要求 agent 使用 `google_meet` 工具並指定 `transport: "chrome-node"`。 -若要進行單一指令煙霧測試，建立或重用工作階段、說出已知短語，並列印工作階段健康狀態： +若要執行單一命令煙霧測試來建立或重用 session、說出已知 +詞句，並列印 session 健康狀態： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -在即時加入期間，OpenClaw 瀏覽器自動化會填入訪客名稱、點擊 -Join/Ask to join，並在 Meet 首次執行的「Use microphone」選項提示出現時接受該選項。於僅觀察加入或僅使用瀏覽器建立會議期間，若同一提示提供不使用麥克風的選項，它會繼續越過該提示。 -如果瀏覽器設定檔尚未登入、Meet 正在等待主持人准入、Chrome 需要即時加入的麥克風/攝影機權限，或 Meet 卡在自動化無法解決的提示上，join/test-speech 結果會回報 -`manualActionRequired: true`，並附上 `manualActionReason` 和 -`manualActionMessage`。Agent 應停止重試加入，回報該確切訊息以及目前的 -`browserUrl`/`browserTitle`，並且只在手動瀏覽器動作完成後才重試。 +在 realtime 加入期間，OpenClaw 瀏覽器自動化會填入訪客名稱、點選 Join/Ask to join，並在該提示出現時接受 Meet 首次執行的「Use microphone」選項。在僅觀察加入或僅瀏覽器建立會議期間，當相同提示提供不使用麥克風的選項時，它會繼續通過該提示。如果瀏覽器設定檔尚未登入、Meet 正在等待主持人准入、Chrome 需要 realtime 加入的麥克風/攝影機權限，或 Meet 卡在自動化無法解決的提示上，join/test-speech 結果會回報 `manualActionRequired: true`，並帶有 `manualActionReason` 和 `manualActionMessage`。Agents 應停止重試加入，回報該確切訊息以及目前的 `browserUrl`/`browserTitle`，並且只在手動瀏覽器動作完成後才重試。 -如果省略 `chromeNode.node`，OpenClaw 只會在剛好有一個已連線節點同時宣告 -`googlemeet.chrome` 和瀏覽器控制時自動選取。如果有多個具備能力的節點已連線，請將 -`chromeNode.node` 設為節點 ID、顯示名稱或遠端 IP。 +如果省略 `chromeNode.node`，OpenClaw 只會在恰好有一個已連線 Node 同時宣告 `googlemeet.chrome` 和瀏覽器控制時自動選取。如果有多個可用 Node 已連線，請將 `chromeNode.node` 設為 Node ID、顯示名稱或遠端 IP。 常見失敗檢查： -- `Configured Google Meet node ... is not usable: offline`：已釘選的節點為 - Gateway 所知，但目前不可用。Agent 應將該節點視為診斷狀態，而不是可用的 Chrome 主機，並回報設定阻礙，而非退回到另一個傳輸方式，除非使用者要求如此。 -- `No connected Google Meet-capable node`：在 VM 中啟動 `openclaw node run`， - 核准配對，並確認已在 VM 中執行 `openclaw plugins enable google-meet` 和 - `openclaw plugins enable browser`。也請確認 Gateway 主機允許這兩個節點命令： - `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`。 -- `BlackHole 2ch audio device not found`：在被檢查的主機上安裝 `blackhole-2ch`， - 並在使用本機 Chrome 音訊前重新開機。 -- `BlackHole 2ch audio device not found on the node`：在 VM 中安裝 `blackhole-2ch`， - 並重新啟動 VM。 -- Chrome 會開啟但無法加入：在 VM 內的瀏覽器設定檔登入，或保持設定 - `chrome.guestName` 以進行訪客加入。訪客自動加入會透過節點瀏覽器代理使用 OpenClaw - 瀏覽器自動化；請確認節點瀏覽器設定指向你想要的設定檔，例如 - `browser.defaultProfile: "user"` 或具名的現有工作階段設定檔。 -- 重複的 Meet 分頁：保持啟用 `chrome.reuseExistingTab: true`。OpenClaw 會在開啟新分頁前啟用相同 Meet URL 的現有分頁，而瀏覽器會議建立會在開啟另一個分頁前重用進行中的 - `https://meet.google.com/new` 或 Google 帳戶提示分頁。 -- 沒有音訊：在 Meet 中，將麥克風/喇叭路由到 OpenClaw 使用的虛擬音訊裝置路徑；使用個別的虛擬裝置或 Loopback 風格的路由，以取得乾淨的雙向音訊。 +- `Configured Google Meet node ... is not usable: offline`：釘選的 Node 已知存在於 Gateway，但目前不可用。Agents 應將該 Node 視為診斷狀態，而不是可用的 Chrome 主機，並回報設定阻礙，而非退回到其他傳輸，除非使用者要求如此。 +- `No connected Google Meet-capable node`：在 VM 中啟動 `openclaw node run`，核准配對，並確認已在 VM 中執行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。也請確認 Gateway 主機透過 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允許兩個 Node 命令。 +- `BlackHole 2ch audio device not found`：在正在檢查的主機上安裝 `blackhole-2ch`，並在使用本機 Chrome 音訊前重新開機。 +- `BlackHole 2ch audio device not found on the node`：在 VM 中安裝 `blackhole-2ch`，並重新啟動 VM。 +- Chrome 開啟但無法加入：登入 VM 內的瀏覽器設定檔，或保持設定 `chrome.guestName` 以供訪客加入。訪客自動加入會透過 Node 瀏覽器代理使用 OpenClaw 瀏覽器自動化；請確認 Node 瀏覽器設定指向你想使用的設定檔，例如 `browser.defaultProfile: "user"` 或具名的既有工作階段設定檔。 +- 重複的 Meet 分頁：保持啟用 `chrome.reuseExistingTab: true`。OpenClaw 會在開啟新分頁前啟用同一 Meet URL 的既有分頁，而瀏覽器會議建立也會在開啟另一個分頁前重用進行中的 `https://meet.google.com/new` 或 Google 帳戶提示分頁。 +- 沒有音訊：在 Meet 中，將麥克風/喇叭路由到 OpenClaw 使用的虛擬音訊裝置路徑；若要乾淨的雙工音訊，請使用分離的虛擬裝置或 Loopback 風格的路由。 ## 安裝注意事項 -Chrome 即時預設值使用兩個外部工具： +Chrome talk-back 預設使用兩個外部工具： - `sox`：命令列音訊工具。Plugin 會針對預設的 24 kHz PCM16 音訊橋接使用明確的 CoreAudio 裝置命令。 -- `blackhole-2ch`：macOS 虛擬音訊驅動程式。它會建立 Chrome/Meet 可透過其路由的 - `BlackHole 2ch` 音訊裝置。 +- `blackhole-2ch`：macOS 虛擬音訊驅動程式。它會建立 `BlackHole 2ch` 音訊裝置，讓 Chrome/Meet 可透過該裝置路由。 -OpenClaw 不會內建或重新散布任一套件。文件會要求使用者透過 Homebrew 將它們安裝為主機相依項。SoX 授權為 -`LGPL-2.0-only AND GPL-2.0-only`；BlackHole 為 GPL-3.0。如果你建置的安裝程式或 appliance 會將 BlackHole 與 OpenClaw 綑綁，請檢閱 BlackHole 的上游授權條款，或向 Existential Audio 取得個別授權。 +OpenClaw 不會綁定或重新散佈任一套件。文件會要求使用者透過 Homebrew 將它們安裝為主機相依項。SoX 採用 `LGPL-2.0-only AND GPL-2.0-only` 授權；BlackHole 採用 GPL-3.0。如果你建置會將 BlackHole 與 OpenClaw 綁定的安裝程式或設備，請檢閱 BlackHole 的上游授權條款，或向 Existential Audio 取得個別授權。 -## 傳輸方式 +## 傳輸 ### Chrome -Chrome 傳輸會透過 OpenClaw 瀏覽器控制開啟 Meet URL，並以已登入的 OpenClaw 瀏覽器設定檔加入。在 macOS 上，Plugin 會在啟動前檢查 -`BlackHole 2ch`。如果已設定，它也會在開啟 Chrome 前執行音訊橋接健康狀態命令和啟動命令。當 Chrome/音訊位於 Gateway 主機時使用 `chrome`；當 Chrome/音訊位於已配對節點（例如 Parallels macOS VM）時使用 `chrome-node`。對於本機 Chrome，請使用 -`browser.defaultProfile` 選擇設定檔；`chrome.browserProfile` 會傳遞給 -`chrome-node` 主機。 +Chrome 傳輸會透過 OpenClaw 瀏覽器控制開啟 Meet URL，並以已登入的 OpenClaw 瀏覽器設定檔加入。在 macOS 上，Plugin 會在啟動前檢查 `BlackHole 2ch`。如果已設定，它也會在開啟 Chrome 前執行音訊橋接健康狀態命令和啟動命令。當 Chrome/音訊位於 Gateway 主機上時使用 `chrome`；當 Chrome/音訊位於已配對 Node，例如 Parallels macOS VM 上時，使用 `chrome-node`。對於本機 Chrome，使用 `browser.defaultProfile` 選擇設定檔；`chrome.browserProfile` 會傳遞給 `chrome-node` 主機。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -將 Chrome 麥克風和喇叭音訊路由到本機 OpenClaw 音訊橋接。如果未安裝 -`BlackHole 2ch`，加入會因設定錯誤而失敗，而不是在沒有音訊路徑的情況下悄悄加入。 +將 Chrome 麥克風和喇叭音訊透過本機 OpenClaw 音訊橋接路由。如果未安裝 `BlackHole 2ch`，加入會以設定錯誤失敗，而不是在沒有音訊路徑的情況下靜默加入。 ### Twilio -Twilio 傳輸是委派給 Voice Call Plugin 的嚴格撥號計畫。它不會剖析 Meet 頁面來取得電話號碼。 +Twilio 傳輸是委派給 Voice Call Plugin 的嚴格撥號計畫。它不會剖析 Meet 頁面以取得電話號碼。 -當無法使用 Chrome 參與，或你想要電話撥入備援時使用此選項。Google Meet 必須為該會議公開電話撥入號碼和 PIN；OpenClaw 不會從 Meet 頁面探索這些資訊。 +當 Chrome 參與不可用，或你想要電話撥入備援時使用這個方式。Google Meet 必須為會議公開電話撥入號碼和 PIN；OpenClaw 不會從 Meet 頁面探索這些資訊。 -在 Gateway 主機上啟用 Voice Call Plugin，而不是在 Chrome 節點上： +在 Gateway 主機上啟用 Voice Call Plugin，而不是在 Chrome Node 上： ```json5 { @@ -360,7 +420,7 @@ Twilio 傳輸是委派給 Voice Call Plugin 的嚴格撥號計畫。它不會剖 } ``` -透過環境或設定提供 Twilio 認證。環境變數可讓機密不進入 `openclaw.json`： +透過環境或設定提供 Twilio 憑證。環境變數可讓秘密不進入 `openclaw.json`： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -368,7 +428,7 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -啟用 `voice-call` 後重新啟動或重新載入 Gateway；Plugin 設定變更在 Gateway 程序重新載入前，不會出現在已在執行的 Gateway 程序中。 +啟用 `voice-call` 後，重新啟動或重新載入 Gateway；Plugin 設定變更在重新載入前，不會出現在已經執行中的 Gateway 程序。 接著驗證： @@ -378,9 +438,7 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -當 Twilio 委派已接好時，`googlemeet setup` 會包含成功的 -`twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 -`twilio-voice-call-webhook` 檢查。 +當 Twilio 委派已接線時，`googlemeet setup` 會包含成功的 `twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 檢查。 ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -389,7 +447,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -當會議需要自訂序列時使用 `--dtmf-sequence`： +當會議需要自訂序列時，使用 `--dtmf-sequence`： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -400,30 +458,29 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth 和預檢 -OAuth 對於建立 Meet 連結是選用的，因為 `googlemeet create` 可以退回使用瀏覽器自動化。當你需要官方 API 建立、空間解析，或 Meet Media API 預檢時，請設定 OAuth。 +OAuth 對於建立 Meet 連結是選用的，因為 `googlemeet create` 可退回到瀏覽器自動化。當你想使用官方 API 建立、空間解析或 Meet Media API 預檢時，請設定 OAuth。 -Google Meet API 存取使用使用者 OAuth：建立 Google Cloud OAuth 用戶端、要求必要範圍、授權 Google 帳戶，然後將產生的 refresh token 儲存在 Google Meet Plugin 設定中，或提供 -`OPENCLAW_GOOGLE_MEET_*` 環境變數。 +Google Meet API 存取使用使用者 OAuth：建立 Google Cloud OAuth 用戶端、要求必要範圍、授權 Google 帳戶，然後將產生的重新整理權杖儲存在 Google Meet Plugin 設定中，或提供 `OPENCLAW_GOOGLE_MEET_*` 環境變數。 -OAuth 不會取代 Chrome 加入路徑。Chrome 和 Chrome-node 傳輸在你使用瀏覽器參與時，仍會透過已登入的 Chrome 設定檔、BlackHole/SoX，以及已連線的節點加入。OAuth 僅用於官方 Google Meet API 路徑：建立會議空間、解析空間，以及執行 Meet Media API 預檢。 +OAuth 不會取代 Chrome 加入路徑。當你使用瀏覽器參與時，Chrome 和 Chrome-node 傳輸仍會透過已登入的 Chrome 設定檔、BlackHole/SoX，以及已連線的 Node 加入。OAuth 僅用於官方 Google Meet API 路徑：建立會議空間、解析空間，以及執行 Meet Media API 預檢。 -### 建立 Google 認證 +### 建立 Google 憑證 在 Google Cloud Console 中： 1. 建立或選取 Google Cloud 專案。 2. 為該專案啟用 **Google Meet REST API**。 3. 設定 OAuth 同意畫面。 - - **Internal** 對 Google Workspace 組織最簡單。 - - **External** 適用於個人/測試設定；當應用程式處於 Testing 時，將每個會授權該應用程式的 Google 帳戶新增為測試使用者。 + - **內部** 對 Google Workspace 組織最簡單。 + - **外部** 適用於個人/測試設定；當應用程式處於測試中時，將每個要授權此應用程式的 Google 帳戶新增為測試使用者。 4. 新增 OpenClaw 要求的範圍： - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.space.settings` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` 5. 建立 OAuth 用戶端 ID。 - - 應用程式類型：**Web application**。 - - 已授權重新導向 URI： + - 應用程式類型：**網頁應用程式**。 + - 已授權的重新導向 URI： ```text http://localhost:8085/oauth2callback @@ -432,23 +489,20 @@ OAuth 不會取代 Chrome 加入路徑。Chrome 和 Chrome-node 傳輸在你使 6. 複製用戶端 ID 和用戶端密鑰。 Google Meet `spaces.create` 需要 `meetings.space.created`。 -`meetings.space.readonly` 讓 OpenClaw 能將 Meet URL/代碼解析為空間。 -`meetings.space.settings` 讓 OpenClaw 在透過 API 建立房間時傳遞 -`SpaceConfig` 設定，例如 `accessType`。 -`meetings.conference.media.readonly` 用於 Meet Media API 預檢和媒體工作；Google 可能會要求加入 Developer Preview 才能實際使用 Media API。 -如果你只需要以瀏覽器為基礎的 Chrome 加入，請完全略過 OAuth。 +`meetings.space.readonly` 讓 OpenClaw 將 Meet URL/代碼解析為空間。 +`meetings.space.settings` 讓 OpenClaw 在 API 房間建立期間傳遞 `SpaceConfig` 設定，例如 `accessType`。 +`meetings.conference.media.readonly` 用於 Meet Media API 預檢和媒體工作；Google 可能會要求加入 Developer Preview，才能實際使用 Media API。 +如果你只需要以瀏覽器為基礎的 Chrome 加入，可以完全略過 OAuth。 -### Mint refresh token +### 鑄造重新整理權杖 -設定 `oauth.clientId` 以及選擇性設定 `oauth.clientSecret`，或將它們作為環境變數傳入，然後執行： +設定 `oauth.clientId`，並可選擇設定 `oauth.clientSecret`，或將它們作為環境變數傳入，然後執行： ```bash openclaw googlemeet auth login --json ``` -該命令會列印包含 refresh token 的 `oauth` 設定區塊。它使用 PKCE、位於 -`http://localhost:8085/oauth2callback` 的 localhost callback，以及使用 -`--manual` 的手動複製/貼上流程。 +該命令會列印含有重新整理權杖的 `oauth` 設定區塊。它使用 PKCE、位於 `http://localhost:8085/oauth2callback` 的 localhost 回呼，以及搭配 `--manual` 的手動複製/貼上流程。 範例： @@ -458,7 +512,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -當瀏覽器無法連到本機 callback 時使用手動模式： +當瀏覽器無法到達本機回呼時，使用手動模式： ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -481,7 +535,7 @@ JSON 輸出包含： } ``` -將 `oauth` 物件儲存在 Google Meet Plugin 設定下： +將 `oauth` 物件儲存在 Google Meet Plugin 設定底下： ```json5 { @@ -502,41 +556,37 @@ JSON 輸出包含： } ``` -當你不想讓 refresh token 進入設定時，優先使用環境變數。如果同時存在設定和環境值，Plugin 會先解析設定，然後才退回到環境。 +當你不想將重新整理權杖放在設定中時，偏好使用環境變數。如果同時存在設定和環境值，Plugin 會先解析設定，然後才退回環境。 -OAuth 同意包含 Meet 空間建立、Meet 空間讀取存取，以及 Meet 會議媒體讀取存取。如果你在會議建立支援存在前已驗證，請重新執行 -`openclaw googlemeet auth login --json`，讓 refresh token 具有 -`meetings.space.created` 範圍。 +OAuth 同意包含 Meet 空間建立、Meet 空間讀取存取，以及 Meet 會議媒體讀取存取。如果你在會議建立支援存在之前已完成驗證，請重新執行 `openclaw googlemeet auth login --json`，讓重新整理權杖具備 `meetings.space.created` 範圍。 ### 使用 doctor 驗證 OAuth -當你需要快速、不含機密的健康狀態檢查時，執行 OAuth doctor： +當你想要快速、非秘密的健康檢查時，執行 OAuth doctor： ```bash openclaw googlemeet doctor --oauth --json ``` -這不會載入 Chrome runtime，也不需要已連線的 Chrome 節點。它會檢查 OAuth 設定是否存在，以及 refresh token 是否能 mint access token。JSON 報告只包含 -`ok`、`configured`、`tokenSource`、`expiresAt` 和檢查訊息等狀態欄位；它不會列印 access token、refresh token 或用戶端密鑰。 +這不會載入 Chrome runtime，也不需要已連線的 Chrome Node。它會檢查 OAuth 設定是否存在，以及重新整理權杖是否能鑄造存取權杖。JSON 報告只包含狀態欄位，例如 `ok`、`configured`、`tokenSource`、`expiresAt` 和檢查訊息；它不會列印存取權杖、重新整理權杖或用戶端密鑰。 常見結果： -| 檢查 | 意義 | -| -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | 存在 `oauth.clientId` 加上 `oauth.refreshToken`，或存在已快取的 access token。 | -| `oauth-token` | 已快取的 access token 仍有效，或 refresh token 已 mint 新的 access token。 | -| `meet-spaces-get` | 選用的 `--meeting` 檢查已解析現有 Meet 空間。 | +| 檢查 | 含義 | +| -------------------- | -------------------------------------------------------------------------------------- | +| `oauth-config` | 存在 `oauth.clientId` 加上 `oauth.refreshToken`，或快取的存取權杖。 | +| `oauth-token` | 快取的存取權杖仍有效，或重新整理權杖已鑄造新的存取權杖。 | +| `meet-spaces-get` | 選用的 `--meeting` 檢查已解析既有 Meet 空間。 | | `meet-spaces-create` | 選用的 `--create-space` 檢查已建立新的 Meet 空間。 | -若要同時證明 Google Meet API 啟用狀態和 `spaces.create` 範圍，請執行具副作用的建立檢查： +若也要證明 Google Meet API 啟用和 `spaces.create` 範圍，請執行會產生副作用的建立檢查： ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` 會建立一個拋棄式 Meet URL。當你需要確認 -Google Cloud 專案已啟用 Meet API，且已授權帳戶具有 `meetings.space.created` 範圍時使用它。 +`--create-space` 會建立一個拋棄式 Meet URL。當你需要確認 Google Cloud 專案已啟用 Meet API，且已授權帳戶具有 `meetings.space.created` 範圍時使用它。 若要證明對現有會議空間的讀取存取權： @@ -545,25 +595,21 @@ openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hi openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` 與 `resolve-space` 可證明對已授權 Google 帳戶可存取的現有 -space 具有讀取存取權。這些檢查傳回 `403` 通常表示 Google Meet REST API 已停用、已同意的重新整理權杖缺少必要範圍，或該 Google 帳戶無法存取該 Meet -space。重新整理權杖錯誤表示需重新執行 `openclaw googlemeet auth login +`doctor --oauth --meeting` 和 `resolve-space` 會證明已授權 Google 帳戶可存取的現有空間讀取權限。這些檢查回傳 `403` 通常表示 Google Meet REST API 已停用、已同意的重新整理權杖缺少必要範圍，或 Google 帳戶無法存取該 Meet 空間。重新整理權杖錯誤表示請重新執行 `openclaw googlemeet auth login --json`，並儲存新的 `oauth` 區塊。 -瀏覽器備援不需要 OAuth 認證。在該模式中，Google -驗證來自所選節點上已登入的 Chrome 設定檔，而不是來自 -OpenClaw 設定。 +瀏覽器後援不需要 OAuth 憑證。在該模式中，Google 驗證來自所選 Node 上已登入的 Chrome 設定檔，而不是來自 OpenClaw 設定。 -下列環境變數可作為備援接受： +接受這些環境變數作為後援： -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` -- `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET` -- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN` -- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 或 `GOOGLE_MEET_ACCESS_TOKEN` -- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 或 +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` or `GOOGLE_MEET_CLIENT_ID` +- `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` or `GOOGLE_MEET_CLIENT_SECRET` +- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` or `GOOGLE_MEET_REFRESH_TOKEN` +- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` or `GOOGLE_MEET_ACCESS_TOKEN` +- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` or `GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` -- `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` 或 `GOOGLE_MEET_DEFAULT_MEETING` -- `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` 或 `GOOGLE_MEET_PREVIEW_ACK` +- `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` or `GOOGLE_MEET_DEFAULT_MEETING` +- `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` or `GOOGLE_MEET_PREVIEW_ACK` 透過 `spaces.get` 解析 Meet URL、代碼或 `spaces/{id}`： @@ -577,7 +623,7 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -在 Meet 建立會議記錄後列出會議成品與出席狀況： +在 Meet 建立會議紀錄後，列出會議產物和出席紀錄： ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -585,10 +631,9 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -搭配 `--meeting` 時，`artifacts` 與 `attendance` 預設會使用最新的會議記錄。當你想取得該會議所有保留的記錄時，請傳入 `--all-conference-records`。 +使用 `--meeting` 時，`artifacts` 和 `attendance` 預設使用最新的會議紀錄。當你想要該會議的每筆保留紀錄時，傳入 `--all-conference-records`。 -Calendar 查詢可先從 Google Calendar 解析會議 URL，再讀取 -Meet 成品： +Calendar 查詢可以在讀取 Meet 產物前，從 Google Calendar 解析會議 URL： ```bash openclaw googlemeet latest --today @@ -597,13 +642,9 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` 會在今天的 `primary` 日曆中搜尋含有 -Google Meet 連結的 Calendar 事件。使用 `--event ` 搜尋相符的事件文字，並使用 -`--calendar ` 指定非主要日曆。Calendar 查詢需要包含 Calendar events readonly 範圍的全新 -OAuth 登入。`calendar-events` 會預覽相符的 Meet 事件，並標記 -`latest`、`artifacts`、`attendance` 或 `export` 將選擇的事件。 +`--today` 會搜尋今天的 `primary` 行事曆中含有 Google Meet 連結的 Calendar 事件。使用 `--event ` 搜尋相符的事件文字，並用 `--calendar ` 指定非主要行事曆。Calendar 查詢需要包含 Calendar events readonly 範圍的新 OAuth 登入。`calendar-events` 會預覽相符的 Meet 事件，並標示 `latest`、`artifacts`、`attendance` 或 `export` 將選擇的事件。 -如果你已知道會議記錄 ID，可直接指定它： +如果你已經知道會議紀錄 ID，請直接指定： ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -611,15 +652,13 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -當你想在通話後關閉房間時，可結束 API 建立空間中的作用中會議： +當你想在通話後關閉房間時，結束 API 建立空間的使用中會議： ```bash openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -這會呼叫 Google Meet `spaces.endActiveConference`，並需要 OAuth 對已授權帳戶可管理的空間具有 -`meetings.space.created` 範圍。OpenClaw 接受 Meet URL、會議代碼或 `spaces/{id}` 輸入，並在結束作用中會議前將其解析為 API 空間資源。 -它與 `googlemeet leave` 不同：`leave` 會停止 OpenClaw 的本機/工作階段參與，而 `end-active-conference` 會要求 Google Meet 結束該空間的作用中會議。 +這會呼叫 Google Meet `spaces.endActiveConference`，並且對於已授權帳戶可管理的空間，需要具有 `meetings.space.created` 範圍的 OAuth。OpenClaw 接受 Meet URL、會議代碼或 `spaces/{id}` 輸入，並在結束使用中會議前將其解析為 API 空間資源。它與 `googlemeet leave` 分開：`leave` 會停止 OpenClaw 的本機/工作階段參與，而 `end-active-conference` 會要求 Google Meet 結束該空間的使用中會議。 寫入可讀報告： @@ -636,18 +675,11 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -當 Google 為該會議公開資料時，`artifacts` 會傳回會議記錄中繼資料，以及參與者、錄影、逐字稿、結構化逐字稿項目和智慧筆記資源中繼資料。大型會議可使用 `--no-transcript-entries` 跳過項目查詢。`attendance` 會將參與者展開為 -participant-session 列，其中包含首次/最後看到時間、總工作階段持續時間、遲到/提早離開旗標，並依已登入使用者或顯示名稱合併重複的參與者資源。傳入 `--no-merge-duplicates` 可保留原始參與者資源彼此分開，`--late-after-minutes` 可調整遲到偵測，`--early-before-minutes` 可調整提早離開偵測。 +當 Google 為該會議公開時，`artifacts` 會回傳會議紀錄中繼資料，以及參與者、錄影、逐字稿、結構化逐字稿項目和智慧筆記資源中繼資料。大型會議可使用 `--no-transcript-entries` 跳過項目查詢。`attendance` 會將參與者展開為 participant-session 列，包含首次/最後出現時間、總工作階段持續時間、遲到/提早離開旗標，並依已登入使用者或顯示名稱合併重複的參與者資源。傳入 `--no-merge-duplicates` 可讓原始參與者資源保持分開，傳入 `--late-after-minutes` 可調整遲到偵測，傳入 `--early-before-minutes` 可調整提早離開偵測。 -`export` 會寫入一個資料夾，其中包含 `summary.md`、`attendance.csv`、 -`transcript.md`、`artifacts.json`、`attendance.json` 和 `manifest.json`。 -`manifest.json` 會記錄所選輸入、匯出選項、會議記錄、輸出檔案、計數、權杖來源、使用過的 Calendar 事件，以及任何部分擷取警告。傳入 `--zip` 也會在資料夾旁寫入可攜式封存檔。傳入 `--include-doc-bodies` 可透過 Google Drive `files.export` 匯出連結的逐字稿和智慧筆記 Google Docs 文字；這需要包含 Drive Meet readonly 範圍的全新 OAuth 登入。若未使用 -`--include-doc-bodies`，匯出只會包含 Meet 中繼資料和結構化逐字稿項目。如果 Google 傳回部分成品失敗，例如智慧筆記清單、逐字稿項目或 Drive 文件本文錯誤，摘要與 -manifest 會保留警告，而不是讓整個匯出失敗。 -使用 `--dry-run` 可擷取相同的成品/出席資料，並列印 -manifest JSON，而不建立資料夾或 ZIP。這在寫入大型匯出前，或代理程式只需要計數、所選記錄和警告時很有用。 +`export` 會寫入包含 `summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json`、`attendance.json` 和 `manifest.json` 的資料夾。`manifest.json` 會記錄所選輸入、匯出選項、會議紀錄、輸出檔案、計數、權杖來源、使用過的 Calendar 事件，以及任何部分擷取警告。傳入 `--zip` 也會在資料夾旁寫入可攜封存檔。傳入 `--include-doc-bodies` 可透過 Google Drive `files.export` 匯出連結逐字稿和智慧筆記 Google Docs 文字；這需要包含 Drive Meet readonly 範圍的新 OAuth 登入。若沒有 `--include-doc-bodies`，匯出只會包含 Meet 中繼資料和結構化逐字稿項目。如果 Google 回傳部分產物失敗，例如智慧筆記清單、逐字稿項目或 Drive 文件本文錯誤，摘要和 manifest 會保留警告，而不是讓整個匯出失敗。使用 `--dry-run` 可擷取相同的產物/出席資料並列印 manifest JSON，而不建立資料夾或 ZIP。這在寫入大型匯出前，或 agent 只需要計數、所選紀錄和警告時很有用。 -代理程式也可以透過 `google_meet` 工具建立相同套件： +Agent 也可以透過 `google_meet` 工具建立相同套件： ```json { @@ -659,20 +691,20 @@ manifest JSON，而不建立資料夾或 ZIP。這在寫入大型匯出前，或 } ``` -設定 `"dryRun": true` 只傳回匯出 manifest 並略過檔案寫入。 +設定 `"dryRun": true` 可只回傳匯出 manifest 並跳過檔案寫入。 -代理程式也可以建立具有明確存取政策的 API 支援房間： +Agent 也可以使用明確的存取政策建立 API 支援的房間： ```json { "action": "create", "transport": "chrome-node", - "mode": "realtime", + "mode": "agent", "accessType": "OPEN" } ``` -它們也可以結束已知房間的作用中會議： +並且可以結束已知房間的使用中會議： ```json { @@ -681,7 +713,7 @@ manifest JSON，而不建立資料夾或 ZIP。這在寫入大型匯出前，或 } ``` -若要進行先聽後驗證，代理程式應在宣稱會議有用前使用 `test_listen`： +對於先聽後驗證，agent 應先使用 `test_listen`，再宣稱會議有用： ```json { @@ -692,7 +724,7 @@ manifest JSON，而不建立資料夾或 ZIP。這在寫入大型匯出前，或 } ``` -針對真實保留會議執行受保護的即時煙霧測試： +針對真實保留會議執行受保護的即時冒煙測試： ```bash OPENCLAW_LIVE_TEST=1 \ @@ -700,43 +732,40 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -針對有人會發言且 Meet 字幕可用的會議，執行即時先聽瀏覽器探測： +針對有人會說話且 Meet 字幕可用的會議，執行即時先聽瀏覽器探測： ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -即時煙霧測試環境： +即時冒煙測試環境： - `OPENCLAW_LIVE_TEST=1` 會啟用受保護的即時測試。 - `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` 指向保留的 Meet URL、代碼或 `spaces/{id}`。 -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` 提供 OAuth +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` or `GOOGLE_MEET_CLIENT_ID` 提供 OAuth 用戶端 ID。 -- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN` 提供 +- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` or `GOOGLE_MEET_REFRESH_TOKEN` 提供 重新整理權杖。 - 選用：`OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`、 `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 和 - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 使用不含 `OPENCLAW_` 前綴的相同備援名稱。 + `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 使用不含 `OPENCLAW_` 前綴的相同後援名稱。 -基礎成品/出席即時煙霧測試需要 +基礎產物/出席紀錄即時冒煙測試需要 `https://www.googleapis.com/auth/meetings.space.readonly` 和 -`https://www.googleapis.com/auth/meetings.conference.media.readonly`。Calendar -查詢需要 `https://www.googleapis.com/auth/calendar.events.readonly`。Drive -文件本文匯出需要 +`https://www.googleapis.com/auth/meetings.conference.media.readonly`。Calendar 查詢需要 `https://www.googleapis.com/auth/calendar.events.readonly`。Drive 文件本文匯出需要 `https://www.googleapis.com/auth/drive.meet.readonly`。 -建立全新的 Meet 空間： +建立新的 Meet 空間： ```bash openclaw googlemeet create ``` -該命令會列印新的 `meeting uri`、來源與加入工作階段。若有 OAuth -認證，它會使用官方 Google Meet API。若沒有 OAuth 認證，它會使用釘選 Chrome 節點的已登入瀏覽器設定檔作為備援。代理程式可以使用 `google_meet` 工具搭配 `action: "create"` 一步建立並加入。若只要建立 URL，請傳入 `"join": false`。 +此命令會列印新的 `meeting uri`、來源和加入工作階段。有 OAuth 憑證時，它會使用官方 Google Meet API。沒有 OAuth 憑證時，它會使用釘選 Chrome Node 的已登入瀏覽器設定檔作為後援。Agent 可以使用 `google_meet` 工具搭配 `action: "create"`，一步建立並加入。若只要建立 URL，請傳入 `"join": false`。 -瀏覽器備援的 JSON 輸出範例： +瀏覽器後援的 JSON 輸出範例： ```json { @@ -756,8 +785,7 @@ openclaw googlemeet create } ``` -如果瀏覽器備援在可建立 URL 前遇到 Google 登入或 Meet 權限封鎖，Gateway 方法會傳回失敗回應，且 -`google_meet` 工具會傳回結構化詳細資料，而不是純字串： +如果瀏覽器後援在建立 URL 前遇到 Google 登入或 Meet 權限阻擋，Gateway 方法會回傳失敗回應，而 `google_meet` 工具會回傳結構化詳細資料，而不是純字串： ```json { @@ -775,9 +803,7 @@ openclaw googlemeet create } ``` -當代理程式看到 `manualActionRequired: true` 時，應回報 -`manualActionMessage` 加上瀏覽器節點/分頁情境，並停止開啟新的 -Meet 分頁，直到操作員完成瀏覽器步驟。 +當 agent 看到 `manualActionRequired: true` 時，應回報 `manualActionMessage` 加上瀏覽器 Node/分頁內容，並停止開啟新的 Meet 分頁，直到操作員完成瀏覽器步驟。 API 建立的 JSON 輸出範例： @@ -800,15 +826,13 @@ API 建立的 JSON 輸出範例： } ``` -建立 Meet 預設會加入。Chrome 或 Chrome-node 傳輸仍需要已登入的 Google Chrome 設定檔，才能透過瀏覽器加入。如果設定檔已登出，OpenClaw 會回報 `manualActionRequired: true` 或瀏覽器備援錯誤，並要求操作員先完成 Google 登入再重試。 +建立 Meet 預設會加入。Chrome 或 Chrome-node 傳輸仍需要已登入的 Google Chrome 設定檔，才能透過瀏覽器加入。如果設定檔已登出，OpenClaw 會回報 `manualActionRequired: true` 或瀏覽器後援錯誤，並要求操作員完成 Google 登入後再重試。 -只有在確認你的 Cloud 專案、OAuth 主體與會議參與者已加入 Google -Workspace Developer Preview Program for Meet media APIs 後，才設定 `preview.enrollmentAcknowledged: true`。 +只有在確認你的 Cloud 專案、OAuth 主體和會議參與者都已加入 Google Workspace Developer Preview Program for Meet media APIs 後，才設定 `preview.enrollmentAcknowledged: true`。 ## 設定 -常見的 Chrome 即時路徑只需要啟用 Plugin、BlackHole、SoX，以及後端即時語音提供者金鑰。OpenAI 是預設值；設定 -`realtime.provider: "google"` 可使用 Google Gemini Live： +常見的 Chrome agent 路徑只需要啟用 Plugin、BlackHole、SoX、即時轉錄提供者金鑰，以及已設定的 OpenClaw TTS 提供者。OpenAI 是預設轉錄提供者；設定 `realtime.provider: "google"` 可在 `bidi` 模式中使用 Google Gemini Live： ```bash brew install blackhole-2ch sox @@ -835,25 +859,29 @@ export GEMINI_API_KEY=... 預設值： - `defaultTransport: "chrome"` -- `defaultMode: "realtime"` -- `chromeNode.node`：選用的 `chrome-node` 節點 ID/名稱/IP +- `defaultMode: "agent"`（`"realtime"` 只會作為 `"agent"` 的舊版相容別名接受；新的工具呼叫應使用 `"agent"`） +- `chromeNode.node`：`chrome-node` 的選用 node ID／名稱／IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`：用於未登入 Meet 訪客畫面的名稱 +- `chrome.guestName: "OpenClaw Agent"`：已登出 Meet 訪客畫面使用的名稱 - `chrome.autoJoin: true`：透過 `chrome-node` 上的 OpenClaw 瀏覽器自動化，盡力填入訪客名稱並點擊立即加入 - `chrome.reuseExistingTab: true`：啟用現有 Meet 分頁，而不是開啟重複分頁 -- `chrome.waitForInCallMs: 20000`：等待 Meet 分頁回報已在通話中，再觸發即時簡介 -- `chrome.audioFormat: "pcm16-24khz"`：命令配對音訊格式。只有仍會發出電話音訊的舊版/自訂命令配對才使用 `"g711-ulaw-8khz"`。 +- `chrome.waitForInCallMs: 20000`：等待 Meet 分頁回報已在通話中，然後才觸發回話介紹 +- `chrome.audioFormat: "pcm16-24khz"`：命令配對音訊格式。只有仍會發出電話音訊的舊版／自訂命令配對才使用 `"g711-ulaw-8khz"`。 +- `chrome.audioBufferBytes: 4096`：產生的 Chrome 命令配對音訊命令所用的 SoX 處理緩衝區。這是 SoX 預設 8192 位元組緩衝區的一半，可降低預設管線延遲，同時保留在繁忙主機上提高該值的空間。低於 SoX 最小值的值會被限制為 17 位元組。 - `chrome.audioInputCommand`：從 CoreAudio `BlackHole 2ch` 讀取並以 `chrome.audioFormat` 寫入音訊的 SoX 命令 - `chrome.audioOutputCommand`：以 `chrome.audioFormat` 讀取音訊並寫入 CoreAudio `BlackHole 2ch` 的 SoX 命令 -- `chrome.bargeInInputCommand`：選用的本機麥克風命令，會寫入有號 16 位元小端序單聲道 PCM，用於在助理播放期間偵測人工插話。這目前適用於 Gateway 託管的 `chrome` 命令配對橋接。 -- `chrome.bargeInRmsThreshold: 650`：在 `chrome.bargeInInputCommand` 上視為人工中斷的 RMS 等級 -- `chrome.bargeInPeakThreshold: 2500`：在 `chrome.bargeInInputCommand` 上視為人工中斷的峰值等級 -- `chrome.bargeInCooldownMs: 900`：重複清除人工中斷之間的最小延遲 -- `realtime.provider: "openai"` +- `chrome.bargeInInputCommand`：選用的本機麥克風命令，在助理播放作用中時寫入有號 16 位元小端序單聲道 PCM，用於偵測人為插話。這目前適用於 Gateway 託管的 `chrome` 命令配對橋接器。 +- `chrome.bargeInRmsThreshold: 650`：在 `chrome.bargeInInputCommand` 上計為人為打斷的 RMS 音量 +- `chrome.bargeInPeakThreshold: 2500`：在 `chrome.bargeInInputCommand` 上計為人為打斷的峰值音量 +- `chrome.bargeInCooldownMs: 900`：重複清除人為打斷之間的最短延遲 +- `mode: "agent"`：預設回話模式。參與者語音會由設定的即時轉錄提供者轉錄，傳送到每場會議子代理程式工作階段中的已設定 OpenClaw 代理程式，並透過一般 OpenClaw TTS 執行階段回放語音。 +- `mode: "bidi"`：備援直接雙向即時模型模式。即時語音提供者會直接回答參與者語音，並且可呼叫 `openclaw_agent_consult` 取得更深入／由工具支援的答案。 +- `mode: "transcribe"`：沒有回話橋接器的僅觀察模式。 +- `realtime.provider: "openai"`：`agent` 模式用於即時轉錄、`bidi` 模式用於即時語音的提供者 ID。 - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`：簡短口語回覆，使用 `openclaw_agent_consult` 取得更深入的答案 -- `realtime.introMessage`：即時橋接連線時的簡短口語就緒檢查；設為 `""` 可靜默加入 -- `realtime.agentId`：`openclaw_agent_consult` 的選用 OpenClaw 代理 ID；預設為 `main` +- `realtime.instructions`：簡短語音回覆，並使用 `openclaw_agent_consult` 取得更深入的答案 +- `realtime.introMessage`：即時橋接器連線時的簡短語音就緒檢查；將它設為 `""` 可安靜加入 +- `realtime.agentId`：`openclaw_agent_consult` 的選用 OpenClaw 代理程式 ID；預設為 `main` 選用覆寫： @@ -890,6 +918,7 @@ export GEMINI_API_KEY=... chromeNode: { node: "parallels-macos", }, + defaultMode: "agent", realtime: { provider: "google", agentId: "jay", @@ -920,34 +949,36 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` 預設為 `true`；使用 Twilio 傳輸時，它會將實際的 PSTN 通話、DTMF 和開場問候委派給 Voice Call Plugin。Voice Call 會先播放 DTMF 序列，再開啟即時媒體串流，然後使用儲存的簡介文字作為初始即時問候。如果未啟用 `voice-call`，Google Meet 仍可驗證並記錄撥號方案，但無法撥打 Twilio 通話。 +`voiceCall.enabled` 預設為 `true`；使用 Twilio 傳輸時，它會將實際 PSTN 通話、DTMF 和介紹問候委派給 Voice Call Plugin。Voice Call 會在開啟即時媒體串流前播放 DTMF 序列，然後使用已儲存的介紹文字作為初始即時問候。如果未啟用 `voice-call`，Google Meet 仍可驗證並記錄撥號計畫，但無法撥出 Twilio 通話。 ## 工具 -代理可以使用 `google_meet` 工具： +代理程式可以使用 `google_meet` 工具： ```json { "action": "join", "url": "https://meet.google.com/abc-defg-hij", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` -當 Chrome 在 Gateway 主機上執行時，使用 `transport: "chrome"`。當 Chrome 在已配對節點（例如 Parallels VM）上執行時，使用 `transport: "chrome-node"`。在兩種情況下，即時模型和 `openclaw_agent_consult` 都在 Gateway 主機上執行，因此模型憑證會留在那裡。 +當 Chrome 在 Gateway 主機上執行時，使用 `transport: "chrome"`。當 Chrome 在已配對 node（例如 Parallels VM）上執行時，使用 `transport: "chrome-node"`。在兩種情況下，模型提供者和 `openclaw_agent_consult` 都會在 Gateway 主機上執行，因此模型憑證會留在那裡。使用預設 `mode: "agent"` 時，即時轉錄提供者會負責聆聽，已設定的 OpenClaw 代理程式會產生答案，而一般 OpenClaw TTS 會將其朗讀到 Meet 中。當你想讓即時語音模型直接回答時，使用 `mode: "bidi"`。 +原始 `mode: "realtime"` 仍會作為 `mode: "agent"` 的舊版相容別名接受，但不再於代理程式工具結構描述中宣傳。 -使用 `action: "status"` 列出作用中工作階段或檢查工作階段 ID。使用帶有 `sessionId` 和 `message` 的 `action: "speak"`，可讓即時代理立即說話。使用 `action: "test_speech"` 可建立或重用工作階段、觸發已知片語，並在 Chrome 主機可回報時回傳 `inCall` 健康狀態。`test_speech` 一律強制 `mode: "realtime"`，且如果要求以 `mode: "transcribe"` 執行會失敗，因為僅觀察工作階段刻意不能發出語音。其 `speechOutputVerified` 結果是根據這次測試呼叫期間即時音訊輸出位元組是否增加，因此含有舊音訊的重用工作階段不會算作新的成功語音檢查。使用 `action: "leave"` 將工作階段標記為已結束。 +使用 `action: "status"` 可列出作用中的工作階段或檢查工作階段 ID。使用帶有 `sessionId` 和 `message` 的 `action: "speak"` 可讓即時代理程式立即說話。使用 `action: "test_speech"` 可建立或重用工作階段、觸發已知片語，並在 Chrome 主機可回報時傳回 `inCall` 健康狀態。`test_speech` 一律強制使用 `mode: "agent"`，如果要求它在 `mode: "transcribe"` 中執行則會失敗，因為僅觀察工作階段刻意不能發出語音。其 `speechOutputVerified` 結果會根據此測試呼叫期間即時音訊輸出位元組是否增加，因此含有較舊音訊的重用工作階段不會計為新的成功語音檢查。使用 `action: "leave"` 可將工作階段標記為已結束。 -`status` 會在可用時包含 Chrome 健康狀態： +可用時，`status` 會包含 Chrome 健康狀態： -- `inCall`：Chrome 似乎位於 Meet 通話內 +- `inCall`：Chrome 似乎位於 Meet 通話中 - `micMuted`：盡力取得的 Meet 麥克風狀態 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：瀏覽器設定檔需要手動登入、Meet 主持人准入、權限，或先修復瀏覽器控制，語音才能運作 -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`：目前是否允許受管理的 Chrome 語音。`speechReady: false` 表示 OpenClaw 未將簡介/測試片語送入音訊橋接。 -- `providerConnected` / `realtimeReady`：即時語音橋接狀態 -- `lastInputAt` / `lastOutputAt`：最近一次從橋接看到或送往橋接的音訊 -- `lastSuppressedInputAt` / `suppressedInputBytes`：助理播放期間被忽略的回送輸入 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：瀏覽器設定檔需要手動登入、Meet 主持人允許加入、權限，或瀏覽器控制修復，語音才能運作 +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`：受管理的 Chrome 語音現在是否允許。`speechReady: false` 表示 OpenClaw 未將介紹／測試片語送入音訊橋接器。 +- `providerConnected` / `realtimeReady`：即時語音橋接器狀態 +- `lastInputAt` / `lastOutputAt`：橋接器最後看到或傳送的音訊 +- `audioOutputRouted` / `audioOutputDeviceLabel`：Meet 分頁的媒體輸出是否已主動路由到橋接器使用的 BlackHole 裝置 +- `lastSuppressedInputAt` / `suppressedInputBytes`：助理播放作用中時被忽略的回送輸入 ```json { @@ -957,29 +988,39 @@ export GEMINI_API_KEY=... } ``` -## 即時代理諮詢 +## 代理程式與 Bidi 模式 -Chrome 即時模式針對即時語音循環最佳化。即時語音供應商會聽取會議音訊，並透過設定的音訊橋接發聲。當即時模型需要更深入推理、目前資訊或一般 OpenClaw 工具時，可以呼叫 `openclaw_agent_consult`。 +Chrome `agent` 模式針對「我的代理程式在會議中」的行為最佳化。即時轉錄提供者會聽取會議音訊，最終參與者逐字稿會路由到已設定的 OpenClaw 代理程式，而答案會透過一般 OpenClaw TTS 執行階段朗讀。當你想讓即時語音模型直接回答時，設定 `mode: "bidi"`。 +鄰近的最終逐字稿片段會在諮詢前合併，讓一個語音回合不會產生數個過時的部分答案。排入佇列的助理音訊仍在播放時，也會抑制即時輸入，而且在代理程式諮詢前會忽略最近類似助理的逐字稿回音，避免 BlackHole 回送讓代理程式回答自己的語音。 -諮詢工具會在幕後使用近期會議逐字稿脈絡執行一般 OpenClaw 代理，並將精簡的口語答案回傳給即時語音工作階段。語音模型接著可以將該答案說回會議中。它使用與 Voice Call 相同的共用即時諮詢工具。 +| 模式 | 誰決定答案 | 語音輸出路徑 | 使用時機 | +| ------- | ----------------------------- | -------------------------------------- | ----------------------------------------------------- | +| `agent` | 已設定的 OpenClaw 代理程式 | 一般 OpenClaw TTS 執行階段 | 你想要「我的代理程式在會議中」的行為 | +| `bidi` | 即時語音模型 | 即時語音提供者音訊回應 | 你想要最低延遲的對話式語音迴圈 | -預設情況下，諮詢會針對 `main` 代理執行。當某個 Meet 通道應諮詢專用 OpenClaw 代理工作區、模型預設值、工具政策、記憶體和工作階段歷史時，請設定 `realtime.agentId`。 +在 `bidi` 模式中，當即時模型需要更深入推理、目前資訊，或一般 OpenClaw 工具時，它可以呼叫 `openclaw_agent_consult`。 + +諮詢工具會在幕後使用最近的會議逐字稿內容脈絡執行一般 OpenClaw 代理程式，並傳回簡潔的語音答案。在 `agent` 模式中，OpenClaw 會將該答案直接傳送到 TTS 執行階段；在 `bidi` 模式中，即時語音模型可以將諮詢結果說回會議中。它使用與 Voice Call 相同的共用諮詢機制。 + +預設情況下，諮詢會針對 `main` 代理程式執行。當 Meet 通道應諮詢專用的 OpenClaw 代理程式工作區、模型預設值、工具政策、記憶體和工作階段歷史時，設定 `realtime.agentId`。 + +代理程式模式諮詢會使用每場會議的 `agent::subagent:google-meet:` 工作階段金鑰，讓後續問題保留會議脈絡，同時繼承已設定代理程式的一般代理程式政策。 `realtime.toolPolicy` 控制諮詢執行： -- `safe-read-only`：公開諮詢工具，並將一般代理限制為 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 -- `owner`：公開諮詢工具，並讓一般代理使用正常的代理工具政策。 -- `none`：不向即時語音模型公開諮詢工具。 +- `safe-read-only`：公開諮詢工具，並將一般代理程式限制為 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 +- `owner`：公開諮詢工具，並讓一般代理程式使用一般代理程式工具政策。 +- `none`：不要向即時語音模型公開諮詢工具。 -諮詢工作階段金鑰會依 Meet 工作階段設定範圍，因此後續諮詢呼叫可在同一場會議中重用先前的諮詢脈絡。 +諮詢工作階段金鑰會依 Meet 工作階段限定範圍，因此後續諮詢呼叫可在同一場會議期間重用先前的諮詢脈絡。 -若要在 Chrome 完全加入通話後強制執行口語就緒檢查： +若要在 Chrome 完全加入通話後強制執行語音就緒檢查： ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -完整的加入並說話煙霧測試： +完整加入並說話的煙霧測試： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -989,7 +1030,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## 即時測試檢查清單 -在將會議交給無人值守代理之前，請使用此序列： +將會議交給無人值守代理程式前，使用此序列： ```bash openclaw googlemeet setup @@ -1002,10 +1043,10 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ 預期的 Chrome-node 狀態： - `googlemeet setup` 全部為綠色。 -- 當 Chrome-node 是預設傳輸或已固定節點時，`googlemeet setup` 包含 `chrome-node-connected`。 -- `nodes status` 顯示所選節點已連線。 -- 所選節點會宣告 `googlemeet.chrome` 和 `browser.proxy`。 -- Meet 分頁加入通話，且 `test-speech` 回傳帶有 `inCall: true` 的 Chrome 健康狀態。 +- 當 Chrome-node 是預設傳輸或已釘選 node 時，`googlemeet setup` 會包含 `chrome-node-connected`。 +- `nodes status` 顯示選取的 node 已連線。 +- 選取的 node 會宣告 `googlemeet.chrome` 和 `browser.proxy`。 +- Meet 分頁加入通話，且 `test-speech` 傳回含有 `inCall: true` 的 Chrome 健康狀態。 對於遠端 Chrome 主機（例如 Parallels macOS VM），這是在更新 Gateway 或 VM 後最短的安全檢查： @@ -1018,9 +1059,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -這會證明 Gateway Plugin 已載入、VM 節點已使用目前權杖連線，且 Meet 音訊橋接可用，然後代理才會開啟真實會議分頁。 +這會在代理程式開啟真正的會議分頁前，證明 Gateway Plugin 已載入、VM node 已使用目前權杖連線，且 Meet 音訊橋接器可用。 -若要進行 Twilio 煙霧測試，請使用會公開電話撥入詳細資訊的會議： +若要進行 Twilio 煙霧測試，請使用會公開電話撥入詳細資料的會議： ```bash openclaw googlemeet setup @@ -1032,15 +1073,17 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ 預期的 Twilio 狀態： -- `googlemeet setup` 包含綠色的 `twilio-voice-call-plugin`、`twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 檢查。 -- Gateway 重新載入後，CLI 中可使用 `voicecall`。 -- 回傳的工作階段具有 `transport: "twilio"` 和 `twilio.voiceCallId`。 -- `openclaw logs --follow` 顯示先提供 DTMF TwiML，再提供即時 TwiML，接著是已佇列初始問候的即時橋接。 +- `googlemeet setup` 包含綠色的 `twilio-voice-call-plugin`、 + `twilio-voice-call-credentials` 和 `twilio-voice-call-webhook` 檢查。 +- Gateway 重新載入後，`voicecall` 可在 CLI 中使用。 +- 傳回的工作階段有 `transport: "twilio"` 和 `twilio.voiceCallId`。 +- `openclaw logs --follow` 顯示 DTMF TwiML 先於即時 TwiML 提供，接著是 + 已排入初始問候語的即時橋接。 - `googlemeet leave ` 會掛斷委派的語音通話。 ## 疑難排解 -### 代理看不到 Google Meet 工具 +### Agent 看不到 Google Meet 工具 確認 Plugin 已在 Gateway 設定中啟用，並重新載入 Gateway： @@ -1049,13 +1092,17 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -如果你剛編輯過 `plugins.entries.google-meet`，請重新啟動或重新載入 Gateway。執行中的代理只會看到目前 Gateway 程序註冊的 Plugin 工具。 +如果你剛編輯了 `plugins.entries.google-meet`，請重新啟動或重新載入 Gateway。 +執行中的 agent 只會看到目前 Gateway 行程註冊的 Plugin 工具。 -在非 macOS Gateway 主機上，面向代理的 `google_meet` 工具仍會顯示，但本機 Chrome 即時動作會在到達音訊橋接之前被封鎖。本機 Chrome 即時音訊目前依賴 macOS `BlackHole 2ch`，因此 Linux 代理應使用 `mode: "transcribe"`、Twilio 撥入，或 macOS `chrome-node` 主機，而不是預設的本機 Chrome 即時路徑。 +在非 macOS Gateway 主機上，面向 agent 的 `google_meet` 工具仍會保持可見， +但本機 Chrome 回話動作會在抵達音訊橋接前被封鎖。本機 Chrome 回話音訊目前依賴 +macOS `BlackHole 2ch`，因此 Linux agent 應使用 `mode: "transcribe"`、Twilio 撥入， +或 macOS `chrome-node` 主機，而不是預設的本機 Chrome agent 路徑。 -### 沒有已連線且支援 Google Meet 的節點 +### 沒有已連線且支援 Google Meet 的 Node -在節點主機上執行： +在 Node 主機上執行： ```bash openclaw plugins enable google-meet @@ -1064,7 +1111,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -在 Gateway 主機上，核准節點並驗證命令： +在 Gateway 主機上，核准 Node 並驗證命令： ```bash openclaw devices list @@ -1072,7 +1119,8 @@ openclaw devices approve openclaw nodes status ``` -節點必須已連線，並列出 `googlemeet.chrome` 加上 `browser.proxy`。Gateway 設定必須允許這些節點命令： +Node 必須已連線，並列出 `googlemeet.chrome` 加上 `browser.proxy`。 +Gateway 設定必須允許這些 Node 命令： ```json5 { @@ -1084,7 +1132,9 @@ openclaw nodes status } ``` -如果 `googlemeet setup` 的 `chrome-node-connected` 失敗，或 Gateway 記錄回報 `gateway token mismatch`，請使用目前的 Gateway 權杖重新安裝或重新啟動節點。對於 LAN Gateway，這通常表示： +如果 `googlemeet setup` 的 `chrome-node-connected` 失敗，或 Gateway 記錄回報 +`gateway token mismatch`，請使用目前的 Gateway token 重新安裝或重新啟動 Node。 +對 LAN Gateway 而言，這通常表示： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1095,37 +1145,57 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -然後重新載入節點服務並重新執行： +然後重新載入 Node 服務並重新執行： ```bash openclaw googlemeet setup openclaw nodes status --connected ``` -### 瀏覽器已開啟但代理無法加入 +### 瀏覽器開啟但 agent 無法加入 -對僅觀察加入執行 `googlemeet test-listen`，或對即時加入執行 `googlemeet test-speech`，然後檢查回傳的 Chrome 健康狀態。如果任一探測回報 `manualActionRequired: true`，請向操作員顯示 `manualActionMessage`，並在瀏覽器動作完成前停止重試。 +對僅觀察加入執行 `googlemeet test-listen`，或對即時加入執行 `googlemeet test-speech`， +然後檢查傳回的 Chrome 健康狀態。如果任一探測回報 `manualActionRequired: true`， +請向操作員顯示 `manualActionMessage`，並停止重試直到瀏覽器動作完成。 -常見的手動動作： +常見手動動作： - 登入 Chrome 設定檔。 -- 從 Meet 主持人帳戶准入訪客。 -- 當 Chrome 原生權限提示出現時，授予 Chrome 麥克風/相機權限。 +- 從 Meet 主持帳戶准許訪客加入。 +- 當 Chrome 原生權限提示出現時，授予 Chrome 麥克風/攝影機權限。 - 關閉或修復卡住的 Meet 權限對話框。 -不要只因為 Meet 顯示「你要讓會議中的其他人聽到你的聲音嗎？」就回報「未登入」。那是 Meet 的音訊選擇中介畫面；OpenClaw 會在可用時透過瀏覽器自動化點擊 **使用麥克風**，並持續等待真正的會議狀態。對於僅建立會議的瀏覽器備援，OpenClaw 可能會點擊 **不使用麥克風繼續**，因為建立 URL 不需要即時音訊路徑。 +不要只因為 Meet 顯示「你想讓會議中的人聽到你的聲音嗎？」就回報「未登入」。 +那是 Meet 的音訊選擇中介頁；OpenClaw 會在可用時透過瀏覽器自動化點選 +**使用麥克風**，並持續等待真正的會議狀態。對於僅建立的瀏覽器備援， +OpenClaw 可能會點選 **不使用麥克風繼續**，因為建立 URL 不需要即時音訊路徑。 ### 會議建立失敗 -`googlemeet create` 會先在已設定 OAuth 認證時使用 Google Meet API 的 `spaces.create` 端點。沒有 OAuth 認證時，會退回使用固定的 Chrome node 瀏覽器。請確認： +`googlemeet create` 會在已設定 OAuth 認證時，先使用 Google Meet API +`spaces.create` 端點。沒有 OAuth 認證時，會退回使用釘選的 Chrome Node 瀏覽器。 +請確認： -- 針對 API 建立：已設定 `oauth.clientId` 和 `oauth.refreshToken`，或存在相符的 `OPENCLAW_GOOGLE_MEET_*` 環境變數。 -- 針對 API 建立：refresh token 是在新增建立支援後產生的。較舊的 token 可能缺少 `meetings.space.created` scope；重新執行 `openclaw googlemeet auth login --json` 並更新 Plugin 設定。 -- 針對瀏覽器備援：`defaultTransport: "chrome-node"`，且 `chromeNode.node` 指向已連線、具備 `browser.proxy` 和 `googlemeet.chrome` 的 node。 -- 針對瀏覽器備援：該 node 上的 OpenClaw Chrome 設定檔已登入 Google，並且可以開啟 `https://meet.google.com/new`。 -- 針對瀏覽器備援：重試時會先重用現有的 `https://meet.google.com/new` 或 Google 帳戶提示分頁，再開啟新分頁。如果 agent 逾時，請重試工具呼叫，而不是手動開啟另一個 Meet 分頁。 -- 針對瀏覽器備援：如果工具回傳 `manualActionRequired: true`，請使用回傳的 `browser.nodeId`、`browser.targetId`、`browserUrl` 和 `manualActionMessage` 來引導操作員。在該動作完成前，不要迴圈重試。 -- 針對瀏覽器備援：如果 Meet 顯示「你要讓會議中的其他人聽到你的聲音嗎？」，請保持分頁開啟。OpenClaw 應透過瀏覽器自動化點擊 **使用麥克風**，或在僅建立會議的備援情境中點擊 **不使用麥克風繼續**，並繼續等待產生的 Meet URL。如果無法做到，錯誤應提及 `meet-audio-choice-required`，而不是 `google-login-required`。 +- 對 API 建立：已設定 `oauth.clientId` 和 `oauth.refreshToken`， + 或存在相符的 `OPENCLAW_GOOGLE_MEET_*` 環境變數。 +- 對 API 建立：重新整理 token 是在新增建立支援後產生的。較舊的 token 可能缺少 + `meetings.space.created` scope；請重新執行 `openclaw googlemeet auth login --json` + 並更新 Plugin 設定。 +- 對瀏覽器備援：`defaultTransport: "chrome-node"`，且 + `chromeNode.node` 指向已連線並具有 `browser.proxy` 和 + `googlemeet.chrome` 的 Node。 +- 對瀏覽器備援：該 Node 上的 OpenClaw Chrome 設定檔已登入 Google， + 並可開啟 `https://meet.google.com/new`。 +- 對瀏覽器備援：重試會先重用既有的 `https://meet.google.com/new` + 或 Google 帳戶提示分頁，再開啟新分頁。如果 agent 逾時，請重試工具呼叫， + 而不是手動開啟另一個 Meet 分頁。 +- 對瀏覽器備援：如果工具傳回 `manualActionRequired: true`，請使用傳回的 + `browser.nodeId`、`browser.targetId`、`browserUrl` 和 + `manualActionMessage` 來引導操作員。在該動作完成前，不要迴圈重試。 +- 對瀏覽器備援：如果 Meet 顯示「你想讓會議中的人聽到你的聲音嗎？」，請保持分頁開啟。 + OpenClaw 應透過瀏覽器自動化點選 **使用麥克風**，或在僅建立備援時點選 + **不使用麥克風繼續**，並持續等待產生的 Meet URL。如果無法做到， + 錯誤應提及 `meet-audio-choice-required`，而不是 `google-login-required`。 ### Agent 加入但不說話 @@ -1136,33 +1206,53 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -使用 `mode: "realtime"` 進行聆聽／回話。`mode: "transcribe"` 會刻意不啟動雙工即時語音橋接。若要進行僅觀察的除錯，請在參與者發言後執行 `openclaw googlemeet status --json `，並檢查 `captioning`、`transcriptLines` 和 `lastCaptionText`。如果 `inCall` 為 true 但 `transcriptLines` 維持在 `0`，可能是 Meet 字幕已停用、觀察器安裝後沒有人發言、Meet UI 已變更，或該會議語言／帳戶無法使用即時字幕。 +使用 `mode: "agent"` 作為一般 STT -> OpenClaw agent -> TTS 回話路徑， +或使用 `mode: "bidi"` 作為直接即時語音備援。`mode: "transcribe"` +刻意不啟動回話橋接。對僅觀察除錯，請在參與者發言後執行 +`openclaw googlemeet status --json `，並檢查 `captioning`、 +`transcriptLines` 和 `lastCaptionText`。如果 `inCall` 為 true，但 +`transcriptLines` 維持 `0`，可能是 Meet 字幕已停用、觀察者安裝後沒有人發言、 +Meet UI 已變更，或該會議語言/帳戶無法使用即時字幕。 -`googlemeet test-speech` 一律檢查即時路徑，並回報該次呼叫是否觀察到橋接輸出位元組。如果 `speechOutputVerified` 為 false 且 `speechOutputTimedOut` 為 true，即時提供者可能已接受該語句，但 OpenClaw 沒有看到新的輸出位元組抵達 Chrome 音訊橋接。 +`googlemeet test-speech` 一律檢查即時路徑，並回報該次叫用是否觀察到橋接輸出位元組。 +如果 `speechOutputVerified` 為 false 且 `speechOutputTimedOut` 為 true， +即時提供者可能已接受語句，但 OpenClaw 沒有看到新的輸出位元組抵達 Chrome 音訊橋接。 -也請確認： +也請驗證： -- Gateway 主機上可用即時提供者金鑰，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 -- Chrome 主機上可看到 `BlackHole 2ch`。 -- Chrome 主機上存在 `sox`。 -- Meet 麥克風和喇叭已透過 OpenClaw 使用的虛擬音訊路徑路由。 +- Gateway 主機上有可用的即時提供者金鑰，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 +- `BlackHole 2ch` 在 Chrome 主機上可見。 +- `sox` 存在於 Chrome 主機上。 +- Meet 麥克風與喇叭已透過 OpenClaw 使用的虛擬音訊路徑路由。 + 對本機 Chrome 即時加入，`doctor` 應顯示 `meet output routed: yes`。 -`googlemeet doctor [session-id]` 會列印 session、node、通話中狀態、手動動作原因、即時提供者連線、`realtimeReady`、音訊輸入／輸出活動、最後音訊時間戳、位元組計數器，以及瀏覽器 URL。需要原始 JSON 時，使用 `googlemeet status [session-id] --json`。需要在不暴露 token 的情況下驗證 Google Meet OAuth refresh 時，使用 `googlemeet doctor --oauth`；如果也需要 Google Meet API 證明，請加上 `--meeting` 或 `--create-space`。 +`googlemeet doctor [session-id]` 會列印工作階段、Node、通話中狀態、 +手動動作原因、即時提供者連線、`realtimeReady`、音訊輸入/輸出活動、 +最後音訊時間戳記、位元組計數器，以及瀏覽器 URL。需要原始 JSON 時， +請使用 `googlemeet status [session-id] --json`。需要在不暴露 token 的情況下 +驗證 Google Meet OAuth 重新整理時，請使用 `googlemeet doctor --oauth`； +若也需要 Google Meet API 證明，請加上 `--meeting` 或 `--create-space`。 -如果 agent 逾時，而你可以看到 Meet 分頁已經開啟，請檢查該分頁，不要再開啟另一個： +如果 agent 逾時，而你可以看到已開啟的 Meet 分頁，請檢查該分頁，不要再開另一個： ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -等效的工具動作是 `recover_current_tab`。它會聚焦並檢查所選傳輸方式的現有 Meet 分頁。使用 `chrome` 時，它透過 Gateway 使用本機瀏覽器控制；使用 `chrome-node` 時，它使用已設定的 Chrome node。它不會開啟新分頁或建立新 session；它會回報目前的阻擋因素，例如登入、准入、權限或音訊選擇狀態。CLI 命令會與已設定的 Gateway 通訊，因此 Gateway 必須正在執行；`chrome-node` 也需要 Chrome node 已連線。 +等效的工具動作是 `recover_current_tab`。它會聚焦並檢查所選傳輸的既有 Meet 分頁。 +使用 `chrome` 時，它會透過 Gateway 使用本機瀏覽器控制；使用 `chrome-node` 時， +它會使用已設定的 Chrome Node。它不會開啟新分頁或建立新工作階段；它會回報目前阻礙， +例如登入、准入、權限或音訊選擇狀態。CLI 命令會與已設定的 Gateway 通訊， +因此 Gateway 必須正在執行；`chrome-node` 也需要 Chrome Node 已連線。 ### Twilio 設定檢查失敗 -`twilio-voice-call-plugin` 會在 `voice-call` 未被允許或未啟用時失敗。將它加入 `plugins.allow`，啟用 `plugins.entries.voice-call`，然後重新載入 Gateway。 +當 `voice-call` 未被允許或未啟用時，`twilio-voice-call-plugin` 會失敗。 +將它加入 `plugins.allow`、啟用 `plugins.entries.voice-call`，並重新載入 Gateway。 -`twilio-voice-call-credentials` 會在 Twilio 後端缺少帳戶 SID、auth token 或來電號碼時失敗。在 Gateway 主機上設定這些項目： +當 Twilio 後端缺少帳戶 SID、auth token 或來電號碼時， +`twilio-voice-call-credentials` 會失敗。請在 Gateway 主機上設定這些項目： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1170,11 +1260,16 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`twilio-voice-call-webhook` 會在 `voice-call` 沒有公開 Webhook 暴露，或 `publicUrl` 指向 loopback 或私人網路空間時失敗。將 `plugins.entries.voice-call.config.publicUrl` 設為公開提供者 URL，或設定 `voice-call` 通道／Tailscale 暴露。 +當 `voice-call` 沒有公開 Webhook 暴露，或 `publicUrl` 指向 loopback 或私有網路空間時， +`twilio-voice-call-webhook` 會失敗。請將 +`plugins.entries.voice-call.config.publicUrl` 設為公開提供者 URL， +或設定 `voice-call` tunnel/Tailscale 暴露。 -Loopback 和私人 URL 不適合用於電信業者回呼。請不要使用 `localhost`、`127.0.0.1`、`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、`192.168.x`、`169.254.x`、`fc00::/7` 或 `fd00::/8` 作為 `publicUrl`。 +Loopback 和私有 URL 不能用於電信業者 callback。不要使用 `localhost`、`127.0.0.1`、 +`0.0.0.0`、`10.x`、`172.16.x`-`172.31.x`、`192.168.x`、`169.254.x`、 +`fc00::/7` 或 `fd00::/8` 作為 `publicUrl`。 -若要使用穩定的公開 URL： +對穩定的公開 URL： ```json5 { @@ -1193,7 +1288,7 @@ Loopback 和私人 URL 不適合用於電信業者回呼。請不要使用 `loca } ``` -本機開發時，請使用通道或 Tailscale 暴露，而不是私人主機 URL： +對本機開發，請使用 tunnel 或 Tailscale 暴露，而不是私有主機 URL： ```json5 { @@ -1211,7 +1306,7 @@ Loopback 和私人 URL 不適合用於電信業者回呼。請不要使用 `loca } ``` -接著重新啟動或重新載入 Gateway，並執行： +然後重新啟動或重新載入 Gateway 並執行： ```bash openclaw googlemeet setup --transport twilio @@ -1219,13 +1314,13 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` 預設僅檢查就緒狀態。若要對特定號碼進行 dry-run： +`voicecall smoke` 預設只檢查就緒狀態。若要對特定號碼做 dry-run： ```bash openclaw voicecall smoke --to "+15555550123" ``` -只有在你有意要撥出即時外撥通知電話時，才加入 `--yes`： +只有在你刻意想撥出即時外撥通知通話時，才加上 `--yes`： ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -1233,7 +1328,7 @@ openclaw voicecall smoke --to "+15555550123" --yes ### Twilio 通話開始但從未進入會議 -確認 Meet 事件公開了電話撥入詳細資訊。傳入精確的撥入號碼和 PIN，或自訂 DTMF 序列： +確認 Meet 事件公開電話撥入詳細資料。傳入精確的撥入號碼與 PIN，或自訂 DTMF 序列： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1242,38 +1337,73 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -如果提供者在輸入 PIN 前需要暫停，請在 `--dtmf-sequence` 中使用前置 `w` 或逗號。 +如果提供者需要在輸入 PIN 前暫停，請在 `--dtmf-sequence` 中使用前置 `w` 或逗號。 -如果電話通話已建立，但 Meet 名單中從未顯示撥入參與者： +如果電話通話已建立，但 Meet 名單從未顯示撥入參與者： -- 執行 `openclaw googlemeet doctor `，確認委派的 Twilio 通話 ID、DTMF 是否已排入佇列，以及是否已要求開場問候。 -- 執行 `openclaw voicecall status --call-id `，並確認通話仍在進行。 -- 執行 `openclaw voicecall tail`，並檢查 Twilio Webhook 是否抵達 Gateway。 -- 執行 `openclaw logs --follow`，並尋找 Twilio Meet 序列：Google Meet 委派加入、Voice Call 啟動電話端、Google Meet 等待 `voiceCall.dtmfDelayMs`、使用 `voicecall.dtmf` 傳送 DTMF、等待 `voiceCall.postDtmfSpeechDelayMs`，然後使用 `voicecall.speak` 要求開場語音。 -- 重新執行 `openclaw googlemeet setup --transport twilio`；綠色設定檢查是必要條件，但不證明會議 PIN 序列正確。 +- 執行 `openclaw googlemeet doctor ` 以確認委派的 Twilio + 通話 ID、DTMF 是否已排入佇列，以及是否已要求開場問候。 +- 執行 `openclaw voicecall status --call-id ` 並確認通話仍然 + 啟用中。 +- 執行 `openclaw voicecall tail` 並檢查 Twilio Webhook 是否正抵達 + Gateway。 +- 執行 `openclaw logs --follow` 並尋找 Twilio Meet 序列：Google + Meet 委派加入、Voice Call 啟動電話端、Google Meet 等待 + `voiceCall.dtmfDelayMs`、使用 `voicecall.dtmf` 傳送 DTMF、等待 + `voiceCall.postDtmfSpeechDelayMs`，然後使用 + `voicecall.speak` 要求開場語音。 +- 重新執行 `openclaw googlemeet setup --transport twilio`；必須有綠色的設定檢查， + 但這不證明會議 PIN 序列正確。 - 確認撥入號碼屬於與 PIN 相同的 Meet 邀請和區域。 -- 如果 Meet 接聽較慢，或通話逐字稿在傳送 DTMF 後仍顯示要求輸入 PIN 的提示，請增加 `voiceCall.dtmfDelayMs`。 -- 如果參與者已加入，但你聽不到問候語，請在 `openclaw logs --follow` 中檢查 DTMF 後的 `voicecall.speak` 要求，以及媒體串流 TTS 播放或 Twilio `` 備援。如果通話逐字稿仍包含「輸入會議 PIN」，表示電話端尚未加入 Meet 會議室，因此會議參與者不會聽到語音。 +- 如果 Meet 回應緩慢，或通話轉錄在 DTMF 已傳送後仍顯示要求輸入 PIN 的提示， + 請增加 `voiceCall.dtmfDelayMs`。 +- 如果參與者加入但你沒有聽到問候，請檢查 + `openclaw logs --follow` 中 DTMF 後的 `voicecall.speak` 要求，以及 + 媒體串流 TTS 播放或 Twilio `` 備援。如果通話轉錄仍包含 + "enter the meeting PIN"，表示電話端尚未加入 Meet 房間，因此會議參與者不會聽到語音。 -如果 Webhook 沒有抵達，請先除錯 Voice Call Plugin：提供者必須能連到 `plugins.entries.voice-call.config.publicUrl` 或已設定的通道。請參閱 [語音通話疑難排解](/zh-TW/plugins/voice-call#troubleshooting)。 +如果 Webhook 沒有抵達，請先偵錯 Voice Call Plugin：提供者必須能夠 +連到 `plugins.entries.voice-call.config.publicUrl` 或已設定的通道。 +請參閱[語音通話疑難排解](/zh-TW/plugins/voice-call#troubleshooting)。 ## 備註 -Google Meet 的官方媒體 API 偏向接收，因此要在 Meet 通話中說話仍需要參與者路徑。此 Plugin 會讓該邊界保持可見：Chrome 處理瀏覽器參與和本機音訊路由；Twilio 處理電話撥入參與。 +Google Meet 的官方媒體 API 以接收為主，因此要在 Meet +通話中說話仍需要參與者路徑。此 Plugin 會讓該邊界保持可見： +Chrome 處理瀏覽器參與和本機音訊路由；Twilio 處理電話撥入參與。 -Chrome 即時模式需要 `BlackHole 2ch`，以及下列其中一項： +Chrome 回話模式需要 `BlackHole 2ch` 加上以下其中一項： -- `chrome.audioInputCommand` 加上 `chrome.audioOutputCommand`：OpenClaw 擁有即時模型橋接，並在這些命令與所選即時語音提供者之間，以 `chrome.audioFormat` 管線傳遞音訊。預設 Chrome 路徑是 24 kHz PCM16；8 kHz G.711 mu-law 仍可供舊版命令組合使用。 -- `chrome.audioBridgeCommand`：外部橋接命令擁有整個本機音訊路徑，並且必須在啟動或驗證其 daemon 後結束。 +- `chrome.audioInputCommand` 加上 `chrome.audioOutputCommand`：OpenClaw 擁有 + 橋接，並在這些命令與所選提供者之間以 `chrome.audioFormat` 傳送音訊。 + Agent 模式使用即時轉錄加上一般 TTS； + bidi 模式使用即時語音提供者。預設 Chrome 路徑是 24 kHz + PCM16，並使用 `chrome.audioBufferBytes: 4096`；8 kHz G.711 mu-law 仍可供 + 舊版命令配對使用。 +- `chrome.audioBridgeCommand`：外部橋接命令擁有整個本機 + 音訊路徑，且必須在啟動或驗證其常駐程式後結束。這只對 + `bidi` 有效，因為 `agent` 模式需要直接的命令配對存取權來使用 TTS。 -若要取得乾淨的雙工音訊，請將 Meet 輸出和 Meet 麥克風透過不同的虛擬裝置，或 Loopback 風格的虛擬裝置圖路由。單一共用的 BlackHole 裝置可能會把其他參與者回音送回通話中。 +若要取得乾淨的雙工音訊，請將 Meet 輸出和 Meet 麥克風路由到不同的 +虛擬裝置，或使用 Loopback 風格的虛擬裝置圖。單一共用的 +BlackHole 裝置可能會把其他參與者的聲音回音回通話中。 -使用命令組合 Chrome 橋接時，`chrome.bargeInInputCommand` 可以聆聽獨立的本機麥克風，並在人類開始說話時清除助理播放。即使共用 BlackHole loopback 輸入在助理播放期間暫時被抑制，這仍能讓人類語音優先於助理輸出。與 `chrome.audioInputCommand` 和 `chrome.audioOutputCommand` 一樣，它是由操作員設定的本機命令。請使用明確且受信任的命令路徑或引數列表，不要將它指向不受信任位置的腳本。 +使用命令配對 Chrome 橋接時，`chrome.bargeInInputCommand` 可以監聽 +另一個本機麥克風，並在人類開始說話時清除助理播放。 +即使共用的 BlackHole loopback 輸入在助理播放期間暫時受到抑制， +這仍可讓人類語音優先於助理輸出。 +和 `chrome.audioInputCommand` 與 `chrome.audioOutputCommand` 一樣，它是 +操作員設定的本機命令。請使用明確且受信任的命令路徑或 +引數清單，且不要將它指向不受信任位置的指令碼。 -`googlemeet speak` 會觸發 Chrome session 的有效即時音訊橋接。`googlemeet leave` 會停止該橋接。對於透過 Voice Call Plugin 委派的 Twilio session，`leave` 也會掛斷底層語音通話。當你也想關閉 API 管理空間中的有效 Google Meet 會議時，請使用 `googlemeet end-active-conference`。 +`googlemeet speak` 會觸發 Chrome +工作階段的啟用中回話音訊橋接。`googlemeet leave` 會停止該橋接。對於透過 +Voice Call Plugin 委派的 Twilio 工作階段，`leave` 也會掛斷底層語音通話。 +當你也想關閉 API 管理空間中啟用中的 +Google Meet 會議時，請使用 `googlemeet end-active-conference`。 ## 相關 -- [Voice call Plugin](/zh-TW/plugins/voice-call) -- [通話模式](/zh-TW/nodes/talk) +- [Voice Call Plugin](/zh-TW/plugins/voice-call) +- [Talk 模式](/zh-TW/nodes/talk) - [建置 Plugin](/zh-TW/plugins/building-plugins) diff --git a/docs/zh-TW/plugins/memory-wiki.md b/docs/zh-TW/plugins/memory-wiki.md index 26868fe19..0f318274e 100644 --- a/docs/zh-TW/plugins/memory-wiki.md +++ b/docs/zh-TW/plugins/memory-wiki.md @@ -1,103 +1,104 @@ --- read_when: - - 你想要的不只是普通的 MEMORY.md 筆記，而是持久知識 + - 你需要超越單純 MEMORY.md 筆記的持久知識 - 你正在設定隨附的 memory-wiki Plugin - 你想了解 wiki_search、wiki_get 或橋接模式 -summary: memory-wiki：含出處、聲明、儀表板和橋接模式的已編譯知識庫 +summary: memory-wiki：已編譯的知識庫，包含來源依據、主張、儀表板與橋接模式 title: 記憶維基 x-i18n: - generated_at: "2026-04-30T03:24:21Z" + generated_at: "2026-05-04T02:45:28Z" model: gpt-5.5 provider: openai - source_hash: 744d569f8b0c9b668ea54dc057f808544359eaae87d5557de2e6acd1b31acd89 + source_hash: b070177b7c1217e9102bc57680b4009265e3584ede7ad6dc3ba7b6393260fefe source_path: plugins/memory-wiki.md workflow: 16 --- -`memory-wiki` 是一個內建 Plugin，會將持久記憶轉換成編譯後的知識庫。 +`memory-wiki` 是一個內建 Plugin，會將持久記憶轉換為已編譯的知識庫。 -它**不會**取代 Active Memory Plugin。Active Memory Plugin 仍然負責召回、提升、索引與 Dreaming。`memory-wiki` 與它並列運作，並將持久知識編譯成可瀏覽的 wiki，包含確定性頁面、結構化主張、來源、儀表板與機器可讀摘要。 +它**不會**取代 Active Memory Plugin。Active Memory Plugin 仍然負責回想、提升、索引與 Dreaming。`memory-wiki` 位於它旁邊，並將持久知識編譯成可導覽的 wiki，包含確定性頁面、結構化主張、來源、儀表板，以及機器可讀的摘要。 -當你希望記憶更像是維護良好的知識層，而不是一堆 Markdown 檔案時，就使用它。 +當你希望記憶的行為更像維護良好的知識層，而不是一堆 Markdown 檔案時，請使用它。 ## 它新增了什麼 -- 具有確定性頁面版面的專用 wiki 知識庫 -- 結構化主張與證據中繼資料，而不只是散文 -- 頁面層級的來源、信心度、矛盾與待解問題 -- 供代理程式與執行階段使用者使用的編譯摘要 -- wiki 原生搜尋、取得、套用與 lint 工具 +- 具備確定性頁面配置的專用 wiki vault +- 結構化的主張與證據中繼資料，而不只是文字敘述 +- 頁面層級的來源、信心度、矛盾與開放問題 +- 供 agent/runtime 消費者使用的已編譯摘要 +- wiki 原生的搜尋/取得/套用/lint 工具 - 可選的橋接模式，可從 Active Memory Plugin 匯入公開成品 -- 可選的 Obsidian 友善轉譯模式與 CLI 整合 +- 可選的 Obsidian 友善算繪模式與 CLI 整合 -## 它如何與記憶配合 +## 它如何配合記憶 -可以把分工想成這樣： +可以這樣理解分工： | 層級 | 負責 | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| Active Memory Plugin（`memory-core`、QMD、Honcho 等） | 召回、語意搜尋、提升、Dreaming、記憶執行階段 | -| `memory-wiki` | 編譯後的 wiki 頁面、富含來源的綜合內容、儀表板、wiki 專用搜尋、取得與套用 | +| Active Memory Plugin (`memory-core`, QMD, Honcho 等) | 回想、語意搜尋、提升、Dreaming、記憶 runtime | +| `memory-wiki` | 已編譯 wiki 頁面、富含來源的綜合內容、儀表板、wiki 專用搜尋/取得/套用 | -如果 Active Memory Plugin 暴露共享召回成品，OpenClaw 可以使用 `memory_search corpus=all` 在一次流程中搜尋兩個層級。 +如果 Active Memory Plugin 暴露共享回想成品，OpenClaw 可以透過 `memory_search corpus=all` 在一次流程中搜尋兩個層級。 -當你需要 wiki 專用排序、來源，或直接頁面存取時，請改用 wiki 原生工具。 +當你需要 wiki 專用的排序、來源或直接頁面存取時，請改用 wiki 原生工具。 ## 建議的混合模式 -對於本機優先設定，一個穩健的預設值是： +對 local-first 設定來說，一個穩健的預設是： -- 使用 QMD 作為 Active Memory 後端，用於召回與廣泛語意搜尋 -- 以 `bridge` 模式使用 `memory-wiki`，產生持久的綜合知識頁面 +- 使用 QMD 作為 Active Memory 後端，用於回想與廣泛語意搜尋 +- 使用 `memory-wiki` 的 `bridge` 模式建立持久的綜合知識頁面 -這種分工很有效，因為每個層級都能保持專注： +這樣的分工效果很好，因為每個層級都能保持專注： - QMD 讓原始筆記、工作階段匯出與額外集合保持可搜尋 - `memory-wiki` 編譯穩定實體、主張、儀表板與來源頁面 -實用規則： +實務規則： -- 當你想要跨記憶進行一次廣泛召回時，使用 `memory_search` -- 當你想要具備來源感知的 wiki 結果時，使用 `wiki_search` 與 `wiki_get` -- 當你希望共享搜尋涵蓋兩個層級時，使用 `memory_search corpus=all` +- 當你想跨記憶做一次廣泛回想時，使用 `memory_search` +- 當你想取得具備來源感知的 wiki 結果時，使用 `wiki_search` 和 `wiki_get` +- 當你想讓共享搜尋橫跨兩個層級時，使用 `memory_search corpus=all` -如果橋接模式回報匯出的成品為零，表示 Active Memory Plugin 目前尚未暴露公開橋接輸入。請先執行 `openclaw wiki doctor`，然後確認 Active Memory Plugin 支援公開成品。 +如果橋接模式回報匯出的成品為零，表示 Active Memory Plugin 目前尚未暴露公開橋接輸入。先執行 `openclaw wiki doctor`，再確認 Active Memory Plugin 支援公開成品。 -當橋接模式啟用且 `bridge.readMemoryArtifacts` 已啟用時，`openclaw wiki status`、`openclaw wiki doctor` 與 `openclaw wiki bridge import` 會透過正在執行的 Gateway 讀取。這會讓 CLI 橋接檢查與執行階段記憶 Plugin 情境保持一致。如果橋接停用或成品讀取已關閉，這些命令會維持其本機與離線行為。 +當橋接模式啟用且 `bridge.readMemoryArtifacts` 已啟用時，`openclaw wiki status`、`openclaw wiki doctor` 與 `openclaw wiki bridge +import` 會透過執行中的 Gateway 讀取。這會讓 CLI 橋接檢查與 runtime 記憶 Plugin 上下文保持一致。如果橋接已停用或成品讀取已關閉，這些命令會保留其本機/離線行為。 -## 知識庫模式 +## Vault 模式 -`memory-wiki` 支援三種知識庫模式： +`memory-wiki` 支援三種 vault 模式： ### `isolated` -自有知識庫、自有來源，不依賴 `memory-core`。 +自己的 vault、自己的來源，不依賴 `memory-core`。 -當你希望 wiki 成為自己的策展知識儲存庫時，使用此模式。 +當你希望 wiki 成為獨立策展的知識儲存庫時，請使用此模式。 ### `bridge` -透過公開 Plugin SDK 接縫，從 Active Memory Plugin 讀取公開記憶成品與記憶事件。 +透過公開 Plugin SDK seam，從 Active Memory Plugin 讀取公開記憶成品與記憶事件。 -當你希望 wiki 編譯並整理記憶 Plugin 的匯出成品，而不深入私有 Plugin 內部實作時，使用此模式。 +當你希望 wiki 編譯並整理記憶 Plugin 匯出的成品，而不深入私有 Plugin 內部實作時，請使用此模式。 橋接模式可以索引： - 匯出的記憶成品 - 夢境報告 - 每日筆記 -- 記憶根目錄檔案 +- 記憶根檔案 - 記憶事件記錄 ### `unsafe-local` -明確的同機器逃生出口，用於本機私有路徑。 +明確的同機器逃生口，用於本機私有路徑。 -此模式刻意設計為實驗性且不可攜。只有在你了解信任邊界，且特別需要橋接模式無法提供的本機檔案系統存取時才使用。 +此模式刻意設計為實驗性且不可攜。僅在你理解信任邊界，且明確需要橋接模式無法提供的本機檔案系統存取時使用。 -## 知識庫版面 +## Vault 配置 -此 Plugin 會初始化如下的知識庫： +Plugin 會像這樣初始化 vault： ```text / @@ -120,14 +121,14 @@ x-i18n: 主要頁面群組為： - `sources/` 用於匯入的原始材料與橋接支援頁面 -- `entities/` 用於持久的事物、人物、系統、專案與物件 +- `entities/` 用於持久事物、人物、系統、專案與物件 - `concepts/` 用於想法、抽象概念、模式與政策 -- `syntheses/` 用於編譯後摘要與維護中的彙整 +- `syntheses/` 用於已編譯摘要與維護中的彙總 - `reports/` 用於產生的儀表板 ## 結構化主張與證據 -頁面可以攜帶結構化 `claims` frontmatter，而不只是自由格式文字。 +頁面可以攜帶結構化的 `claims` frontmatter，而不只是自由格式文字。 每個主張可以包含： @@ -150,24 +151,24 @@ x-i18n: - `note` - `updatedAt` -這正是讓 wiki 更像信念層，而不是被動筆記堆的原因。主張可以被追蹤、評分、質疑，並回溯到來源加以解析。 +這讓 wiki 更像信念層，而不是被動的筆記傾倒處。主張可以被追蹤、評分、質疑，並解析回來源。 -## 面向代理程式的實體中繼資料 +## 面向 Agent 的實體中繼資料 -實體頁面也可以攜帶供代理程式使用的路由中繼資料。這是通用 frontmatter，因此適用於人物、團隊、系統、專案或任何其他實體類型。 +實體頁面也可以攜帶供 agent 使用的路由中繼資料。這是通用 frontmatter，因此適用於人物、團隊、系統、專案或任何其他實體類型。 常見欄位包括： - `entityType`：例如 `person`、`team`、`system` 或 `project` - `canonicalId`：跨別名與匯入使用的穩定身分鍵 -- `aliases`：應解析到同一頁面的名稱、帳號或標籤 +- `aliases`：應解析到同一頁面的名稱、handle 或標籤 - `privacyTier`：`public`、`local-private`、`sensitive` 或 `confirm-before-use` - `bestUsedFor` / `notEnoughFor`：精簡路由提示 - `lastRefreshedAt`：與頁面編輯時間分開的來源重新整理時間戳 -- `personCard`：可選的人物專用路由卡，包含帳號、社群、電子郵件、時區、路線、適合詢問、避免詢問、信心度與隱私 +- `personCard`：可選的人物專用路由卡，包含 handle、社群、電子郵件、時區、lane、ask-for、avoid-asking-for、信心度與隱私 - `relationships`：指向相關頁面的型別化邊，包含目標、種類、權重、信心度、證據種類、隱私層級與備註 -對於人物 wiki，代理程式通常應先從 `reports/person-agent-directory.md` 開始，接著在使用聯絡資訊或推論事實之前，用 `wiki_get` 開啟人物頁面。 +對人物 wiki 來說，agent 通常應先從 `reports/person-agent-directory.md` 開始，接著用 `wiki_get` 開啟人物頁面，再使用聯絡資訊或推論出的事實。 範例： @@ -219,19 +220,19 @@ claims: ## 編譯管線 -編譯步驟會讀取 wiki 頁面、正規化摘要，並在以下位置輸出穩定的機器面向成品： +編譯步驟會讀取 wiki 頁面、正規化摘要，並在下列位置輸出穩定的機器面向成品： - `.openclaw-wiki/cache/agent-digest.json` - `.openclaw-wiki/cache/claims.jsonl` -這些摘要的存在，是為了讓代理程式與執行階段程式碼不必抓取 Markdown 頁面。 +這些摘要存在的目的，是讓 agent 與 runtime 程式碼不必爬取 Markdown 頁面。 -編譯後輸出也會支援： +已編譯輸出也會支援： -- 搜尋與取得流程的一階 wiki 索引 -- 從主張 ID 查回擁有該主張的頁面 -- 精簡提示補充內容 -- 報告與儀表板產生 +- 搜尋/取得流程的第一階 wiki 索引 +- claim-id 查詢回擁有頁面 +- 精簡提示補充 +- 報告/儀表板產生 ## 儀表板與健康報告 @@ -249,27 +250,27 @@ claims: - `reports/provenance-coverage.md` - `reports/privacy-review.md` -這些報告會追蹤如下項目： +這些報告會追蹤下列事項： - 矛盾備註叢集 -- 競爭主張叢集 +- 競爭性主張叢集 - 缺少結構化證據的主張 - 低信心度頁面與主張 -- 過期或未知的新鮮度 -- 有未解問題的頁面 -- 人物與實體路由卡 +- 過時或未知的新鮮度 +- 含有未解問題的頁面 +- 人物/實體路由卡 - 結構化關係邊 - 證據類別覆蓋率 - 使用前需要審查的非公開隱私層級 ## 搜尋與擷取 -`memory-wiki` 支援兩種搜尋後端： +`memory-wiki` 支援兩個搜尋後端： - `shared`：可用時使用共享記憶搜尋流程 - `local`：在本機搜尋 wiki -它也支援三種語料庫： +它也支援三個語料庫： - `wiki` - `memory` @@ -277,30 +278,30 @@ claims: 重要行為： -- `wiki_search` 與 `wiki_get` 會在可能時使用編譯摘要作為第一階段 -- 主張 ID 可以解析回擁有該主張的頁面 -- 受爭議、過期與新鮮主張會影響排序 +- `wiki_search` 與 `wiki_get` 會在可能時使用已編譯摘要作為第一階段 +- claim id 可以解析回擁有頁面 +- 受質疑/過時/新鮮主張會影響排序 - 來源標籤可以保留到結果中 - 搜尋模式可以偏向人物查找、問題路由、來源證據或原始主張的排序 -實用規則： +實務規則： -- 使用 `memory_search corpus=all` 進行一次廣泛召回 -- 當你在意 wiki 專用排序、來源或頁面層級信念結構時，使用 `wiki_search` + `wiki_get` +- 使用 `memory_search corpus=all` 進行一次廣泛回想 +- 當你重視 wiki 專用排序、來源或頁面層級信念結構時，使用 `wiki_search` + `wiki_get` 搜尋模式： - `auto`：平衡的預設值 -- `find-person`：提高類人物實體、別名、帳號、社群與 canonical ID 的權重 -- `route-question`：提高代理程式卡、適合詢問提示、最適用提示與關係情境的權重 -- `source-evidence`：提高來源頁面與結構化證據中繼資料的權重 -- `raw-claim`：提高相符結構化主張的權重，並在結果中傳回主張與證據中繼資料 +- `find-person`：加權人物類實體、別名、handle、社群與 canonical ID +- `route-question`：加權 agent 卡、ask-for 提示、best-used-for 提示與關係上下文 +- `source-evidence`：加權來源頁面與結構化證據中繼資料 +- `raw-claim`：加權相符的結構化主張，並在結果中回傳主張/證據中繼資料 -當結果符合結構化主張時，`wiki_search` 可以在其詳細資料 payload 中傳回 `matchedClaimId`、`matchedClaimStatus`、`matchedClaimConfidence`、`evidenceKinds` 與 `evidenceSourceIds`。文字輸出也會在可用時包含精簡的 `Claim:` 與 `Evidence:` 行。 +當結果符合結構化主張時，`wiki_search` 可以在其詳細資料 payload 中回傳 `matchedClaimId`、`matchedClaimStatus`、`matchedClaimConfidence`、`evidenceKinds` 與 `evidenceSourceIds`。可用時，文字輸出也會包含精簡的 `Claim:` 與 `Evidence:` 行。 -## 代理程式工具 +## Agent 工具 -此 Plugin 會註冊這些工具： +Plugin 會註冊這些工具： - `wiki_status` - `wiki_search` @@ -310,27 +311,27 @@ claims: 它們的用途： -- `wiki_status`：目前的知識庫模式、健康狀態、Obsidian CLI 可用性 -- `wiki_search`：搜尋 wiki 頁面，以及在設定時搜尋共享記憶語料庫；接受 `mode` 以進行人物查找、問題路由、來源證據或原始主張深入查詢 -- `wiki_get`：依 ID 或路徑讀取 wiki 頁面，或回退到共享記憶語料庫 -- `wiki_apply`：進行狹窄的綜合與中繼資料變更，不做自由格式頁面手術 -- `wiki_lint`：結構檢查、來源缺口、矛盾、待解問題 +- `wiki_status`：目前 vault 模式、健康狀態、Obsidian CLI 可用性 +- `wiki_search`：搜尋 wiki 頁面，以及在設定時搜尋共享記憶語料庫；接受 `mode` 進行人物查找、問題路由、來源證據或原始主張下鑽 +- `wiki_get`：依 id/path 讀取 wiki 頁面，或退回共享記憶語料庫 +- `wiki_apply`：狹窄的綜合/中繼資料變更，不進行自由格式頁面手術 +- `wiki_lint`：結構檢查、來源缺口、矛盾、開放問題 -此 Plugin 也會註冊非獨佔的記憶語料庫補充，因此當 Active Memory Plugin 支援語料庫選擇時，共享的 `memory_search` 與 `memory_get` 可以連到 wiki。 +Plugin 也會註冊非獨占的記憶語料庫補充，因此當 Active Memory Plugin 支援語料庫選擇時，共享的 `memory_search` 與 `memory_get` 可以觸及 wiki。 -## 提示與情境行為 +## 提示與上下文行為 -當 `context.includeCompiledDigestPrompt` 啟用時，記憶提示區段會附加來自 `agent-digest.json` 的精簡編譯快照。 +當 `context.includeCompiledDigestPrompt` 啟用時，記憶提示區段會附加來自 `agent-digest.json` 的精簡已編譯快照。 -該快照刻意保持小而高訊號： +該快照刻意保持小巧且高訊號： -- 僅限最重要頁面 -- 僅限最重要主張 +- 僅頂層頁面 +- 僅頂層主張 - 矛盾數量 - 問題數量 -- 信心度與新鮮度限定詞 +- 信心度/新鮮度限定詞 -這是選擇性啟用，因為它會改變提示形狀，且主要適用於明確使用記憶補充內容的情境引擎或舊版提示組裝。 +這是選擇加入，因為它會改變提示形狀，且主要適用於明確消費記憶補充的上下文引擎或舊式提示組裝。 ## 設定 @@ -386,11 +387,11 @@ claims: } ``` -主要切換選項： +主要切換項： - `vaultMode`：`isolated`、`bridge`、`unsafe-local` - `vault.renderMode`：`native` 或 `obsidian` -- `bridge.readMemoryArtifacts`：匯入 Active Memory Plugin 公開成品 +- `bridge.readMemoryArtifacts`：匯入 Active Memory Plugin 的公開成品 - `bridge.followMemoryEvents`：在橋接模式中包含事件記錄 - `search.backend`：`shared` 或 `local` - `search.corpus`：`wiki`、`memory` 或 `all` @@ -400,12 +401,15 @@ claims: ### 範例：QMD + 橋接模式 -當你想用 QMD 進行回想，並用 `memory-wiki` 維護知識層時，請使用這個設定： +當你想使用 QMD 進行回憶，並使用 `memory-wiki` 作為維護式知識層時，請使用此設定： ```json5 { memory: { backend: "qmd", + }, + plugins: { + entries: { "memory-wiki": { enabled: true, config: { @@ -432,11 +436,11 @@ claims: } ``` -這會保持： +這會維持： -- 由 QMD 負責 Active Memory 回想 +- QMD 負責 Active Memory 回憶 - `memory-wiki` 專注於已編譯頁面與儀表板 -- 提示形狀維持不變，直到你有意啟用已編譯摘要提示為止 +- 提示形狀保持不變，直到你有意啟用已編譯摘要提示 ## CLI @@ -456,11 +460,11 @@ openclaw wiki bridge import openclaw wiki obsidian status ``` -完整命令參考請見 [CLI：wiki](/zh-TW/cli/wiki)。 +完整命令參考請參閱 [CLI：wiki](/zh-TW/cli/wiki)。 ## Obsidian 支援 -當 `vault.renderMode` 是 `obsidian` 時，Plugin 會寫入適合 Obsidian 的 Markdown，並可選擇使用官方 `obsidian` CLI。 +當 `vault.renderMode` 為 `obsidian` 時，Plugin 會寫入 Obsidian 友善的 Markdown，並可選擇使用官方 `obsidian` CLI。 支援的工作流程包括： @@ -468,23 +472,23 @@ openclaw wiki obsidian status - vault 搜尋 - 開啟頁面 - 呼叫 Obsidian 命令 -- 跳到每日筆記 +- 跳至每日筆記 -這是選用功能。即使沒有 Obsidian，wiki 仍可在原生模式中運作。 +這是可選的。即使沒有 Obsidian，wiki 仍可在原生模式下運作。 ## 建議工作流程 -1. 保留你的 Active Memory Plugin 來進行回想、提升與 Dreaming。 +1. 保留你的 Active Memory Plugin 以進行回憶、提升與 Dreaming。 2. 啟用 `memory-wiki`。 -3. 除非你明確想要橋接模式，否則先從 `isolated` 模式開始。 -4. 當來源可追溯性很重要時，使用 `wiki_search` / `wiki_get`。 -5. 使用 `wiki_apply` 進行範圍精準的整合或中繼資料更新。 +3. 除非你明確想使用橋接模式，否則請從 `isolated` 模式開始。 +4. 當來源脈絡很重要時，使用 `wiki_search` / `wiki_get`。 +5. 使用 `wiki_apply` 進行小範圍綜合或中繼資料更新。 6. 在有意義的變更後執行 `wiki_lint`。 -7. 如果你想看見過時/矛盾內容，請開啟儀表板。 +7. 如果你想要 stale/contradiction 可見性，請開啟儀表板。 ## 相關文件 -- [記憶概觀](/zh-TW/concepts/memory) +- [Memory 概觀](/zh-TW/concepts/memory) - [CLI：memory](/zh-TW/cli/memory) - [CLI：wiki](/zh-TW/cli/wiki) - [Plugin SDK 概觀](/zh-TW/plugins/sdk-overview) diff --git a/docs/zh-TW/providers/openrouter.md b/docs/zh-TW/providers/openrouter.md index 82520bb10..4daa33b24 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 金鑰 + - 你想透過 OpenRouter 在 OpenClaw 中執行模型 + - 你想使用 OpenRouter 進行影像生成 + - 你想使用 OpenRouter 進行影片生成 +summary: 使用 OpenRouter 的統一 API，在 OpenClaw 中存取多種模型 title: OpenRouter x-i18n: - generated_at: "2026-05-02T21:02:53Z" + generated_at: "2026-05-04T02:45:38Z" model: gpt-5.5 provider: openai - source_hash: e98b8b540265b6d11681390c02cb68312f33625bf223823a2dbca17e877c0422 + source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc source_path: providers/openrouter.md workflow: 16 --- -OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求路由到許多模型。它與 OpenAI 相容，因此大多數 OpenAI SDK 只要切換基底 URL 即可使用。 +OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求路由到多種模型。它與 OpenAI 相容，因此大多數 OpenAI SDK 只要切換基底 URL 即可運作。 ## 開始使用 @@ -23,13 +23,13 @@ OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求 在 [openrouter.ai/keys](https://openrouter.ai/keys) 建立 API 金鑰。 - + ```bash openclaw onboard --auth-choice openrouter-api-key ``` - - 上線設定預設為 `openrouter/auto`。之後可選擇具體模型： + + Onboarding 預設使用 `openrouter/auto`。之後可選擇具體模型： ```bash openclaw models set openrouter// @@ -54,7 +54,7 @@ OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求 ## 模型參照 -模型參照遵循 `openrouter//` 模式。如需可用供應商與模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。 +模型參照遵循 `openrouter//` 模式。如需可用提供者和模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。 內建備援範例： @@ -64,9 +64,9 @@ OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求 | `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.ima } ``` -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 的聊天補全圖片 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 提供者使用。 ```json5 { @@ -125,63 +125,89 @@ OpenRouter 也可透過其與 OpenAI 相容的 `/audio/speech` 端點作為 TTS } ``` -如果省略 `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 權杖。 在實際 OpenRouter 請求（`https://openrouter.ai/api/v1`）中，OpenClaw 也會加入 OpenRouter 文件化的應用程式歸因標頭： -| 標頭 | 值 | -| ------------------------- | --------------------- | -| `HTTP-Referer` | `https://openclaw.ai` | -| `X-OpenRouter-Title` | `OpenClaw` | -| `X-OpenRouter-Categories` | `cli-agent` | +| 標頭 | 值 | +| ------------------------- | ------------------------------------------------------------------------------------------------------ | +| `HTTP-Referer` | `https://openclaw.ai` | +| `X-OpenRouter-Title` | `OpenClaw` | +| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` | -如果你將 OpenRouter 供應商重新指向其他 Proxy 或基底 URL，OpenClaw **不會** 注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。 +如果你將 OpenRouter 提供者重新指向其他 proxy 或基底 URL，OpenClaw **不會**注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。 ## 進階設定 + + OpenRouter 回應快取需要選擇啟用。可使用模型參數為每個 OpenRouter 模型啟用： + + ```json5 + { + agents: { + defaults: { + models: { + "openrouter/auto": { + params: { + responseCache: true, + responseCacheTtlSeconds: 300, + }, + }, + }, + }, + }, + } + ``` + + 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。 + + + - 在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會用這些標記在系統／開發者提示區塊上更好地重複使用提示快取。 + 在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會使用這些標記在系統/開發者提示區塊上提升提示快取重用率。 - - 在已驗證的 OpenRouter 路由上，啟用 reasoning 的 Anthropic 模型參照會在請求送達 OpenRouter 前移除尾端 assistant 預填回合，以符合 Anthropic 要求 reasoning 對話必須以 user 回合結尾的規定。 + + 在已驗證的 OpenRouter 路由上，啟用推理的 Anthropic 模型參照會在請求到達 OpenRouter 前移除結尾的助理預填輪次，以符合 Anthropic 對推理對話必須以使用者輪次結尾的要求。 - - 在支援的非 `auto` 路由上，OpenClaw 會將選取的思考層級對應到 OpenRouter Proxy reasoning 酬載。不支援的模型提示和 `openrouter/auto` 會略過該 reasoning 注入。Hunter Alpha 也會針對過時的已設定模型參照略過 Proxy reasoning，因為 OpenRouter 可能會針對該已退役路由在 reasoning 欄位中回傳最終答案文字。 + + 在支援的非 `auto` 路由上，OpenClaw 會將選定的思考層級對應到 OpenRouter proxy 推理 payload。不支援的模型提示和 `openrouter/auto` 會略過該推理注入。Hunter Alpha 也會對過期設定的模型參照略過 proxy 推理，因為 OpenRouter 可能會針對該已淘汰路由在推理欄位中傳回最終答案文字。 - - 在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的 assistant 回合補上缺少的 `reasoning_content`，讓思考／工具對話維持 DeepSeek V4 要求的後續形狀。 + + 在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的助理輪次中補上缺失的 `reasoning_content`，讓思考/工具對話保留 DeepSeek V4 所需的後續形狀。 - - OpenRouter 仍會透過 Proxy 風格、與 OpenAI 相容的路徑執行，因此不會轉送原生僅限 OpenAI 的請求塑形，例如 `serviceTier`、Responses `store`、OpenAI reasoning 相容酬載，以及提示快取提示。 + + OpenRouter 仍會透過 proxy 風格的 OpenAI 相容路徑執行，因此不會轉送原生僅 OpenAI 的請求形塑，例如 `serviceTier`、Responses `store`、OpenAI 推理相容 payload，以及提示快取提示。 - Gemini 支援的 OpenRouter 參照會停留在 Proxy-Gemini 路徑：OpenClaw 會在該處保留 Gemini 思考簽章清理，但不會啟用原生 Gemini 重播驗證或啟動重寫。 + Gemini 支援的 OpenRouter 參照會留在 proxy-Gemini 路徑上：OpenClaw 會在該處保留 Gemini thought-signature 清理，但不會啟用原生 Gemini 重播驗證或 bootstrap 重寫。 - - 如果你在模型參數下傳入 OpenRouter 供應商路由，OpenClaw 會先將其轉送為 OpenRouter 路由中繼資料，然後再執行共用串流包裝器。 + + 如果你在模型參數下傳入 OpenRouter 提供者路由，OpenClaw 會在共用串流包裝器執行前，將其作為 OpenRouter 路由中繼資料轉送。 -## 相關內容 +## 相關 - 選擇供應商、模型參照與容錯移轉行為。 + 選擇提供者、模型參照和容錯移轉行為。 - agents、models 與 providers 的完整設定參考。 + agents、模型和提供者的完整設定參考。 diff --git a/docs/zh-TW/security/network-proxy.md b/docs/zh-TW/security/network-proxy.md index e56765bdf..ac04d554e 100644 --- a/docs/zh-TW/security/network-proxy.md +++ b/docs/zh-TW/security/network-proxy.md @@ -1,36 +1,36 @@ --- read_when: - - 你希望針對 SSRF 與 DNS 重新綁定攻擊採取縱深防禦 - - 為 OpenClaw 執行階段流量設定外部正向代理 -summary: 如何透過由操作人員管理的篩選代理路由 OpenClaw 執行階段 HTTP 和 WebSocket 流量 + - 你想要針對 SSRF 與 DNS 重新綁定攻擊採取縱深防禦 + - 設定 OpenClaw 執行階段流量的外部正向代理 +summary: 如何透過操作員管理的篩選代理路由 OpenClaw 執行階段 HTTP 與 WebSocket 流量 title: 網路代理 x-i18n: - generated_at: "2026-05-02T02:59:32Z" + generated_at: "2026-05-04T02:45:35Z" model: gpt-5.5 provider: openai - source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3 + source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9 source_path: security/network-proxy.md workflow: 16 --- # 網路代理 -OpenClaw 可以透過操作員管理的正向代理路由執行階段 HTTP 和 WebSocket 流量。這是可選的縱深防禦，適用於想要集中出口控制、更強 SSRF 防護，以及更好的網路稽核能力的部署。 +OpenClaw 可以透過操作員管理的正向代理，路由執行階段的 HTTP 和 WebSocket 流量。這是選用的縱深防禦措施，適用於需要集中輸出控制、更強 SSRF 防護，以及更好網路可稽核性的部署。 -OpenClaw 不會隨附、下載、啟動、設定或認證代理。你可以執行符合環境需求的代理技術，而 OpenClaw 會透過該代理路由一般程序本機的 HTTP 和 WebSocket 用戶端。 +OpenClaw 不會隨附、下載、啟動、設定或認證代理。你可以執行符合環境需求的代理技術，而 OpenClaw 會透過它路由一般程序本機的 HTTP 和 WebSocket 用戶端。 -## 為什麼使用代理？ +## 為什麼要使用代理？ -代理讓操作員能以單一網路控制點管理輸出 HTTP 和 WebSocket 流量。即使不只為了 SSRF 強化，這也可能很有用： +代理可讓操作員以單一網路控制點管理輸出的 HTTP 和 WebSocket 流量。即使不是為了強化 SSRF，這也很有用： -- 集中政策：維護單一出口政策，而不是仰賴每個應用程式 HTTP 呼叫位置都正確套用網路規則。 -- 連線時檢查：在 DNS 解析後、代理開啟上游連線之前立即評估目的地。 -- DNS 重新綁定防禦：縮小應用程式層級 DNS 檢查與實際輸出連線之間的落差。 +- 集中政策：維護單一輸出政策，而不是仰賴每個應用程式 HTTP 呼叫點都正確套用網路規則。 +- 連線時檢查：在 DNS 解析後、代理開啟上游連線前立即評估目的地。 +- DNS 重綁防禦：縮小應用程式層級 DNS 檢查與實際輸出連線之間的落差。 - 更廣泛的 JavaScript 覆蓋範圍：透過同一路徑路由一般 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch，以及類似用戶端。 -- 可稽核性：在出口邊界記錄允許與拒絕的目的地。 -- 營運控制：在不重新建置 OpenClaw 的情況下強制執行目的地規則、網路分段、速率限制或輸出允許清單。 +- 可稽核性：在輸出邊界記錄允許和拒絕的目的地。 +- 營運控制：不需重建 OpenClaw，就能強制執行目的地規則、網路分段、速率限制或輸出允許清單。 -代理路由是一般 HTTP 和 WebSocket 輸出的程序層級防護欄。它讓操作員能以失敗即關閉的路徑，將受支援的 JavaScript HTTP 用戶端透過自己的過濾代理路由，但它不是作業系統層級的網路沙箱，也不代表 OpenClaw 會認證代理的目的地政策。 +代理路由是一般 HTTP 和 WebSocket 輸出的程序層級護欄。它可讓操作員透過自己的過濾代理，為受支援的 JavaScript HTTP 用戶端提供失敗即封閉的路由路徑，但它不是作業系統層級的網路沙箱，也不表示 OpenClaw 會認證代理的目的地政策。 ## OpenClaw 如何路由流量 @@ -43,27 +43,27 @@ OpenClaw process WebSocket clients -> operator-managed filtering proxy -> public internet ``` -公開合約是路由行為，而不是用來實作它的內部 Node hook。OpenClaw Gateway 控制平面 WebSocket 用戶端在 Gateway URL 使用 `localhost` 或字面 loopback IP，例如 `127.0.0.1` 或 `[::1]` 時，會對 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作員代理封鎖 loopback 目的地，該控制平面路徑也必須能夠連到 loopback Gateway。一般執行階段 HTTP 和 WebSocket 請求仍會使用設定的代理。 +公開合約是路由行為，而不是用來實作它的內部 Node 掛鉤。當 Gateway URL 使用 `localhost`，或使用像 `127.0.0.1` 或 `[::1]` 這類明確 loopback IP 時，OpenClaw Gateway 控制平面 WebSocket 用戶端會針對 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作員代理阻擋 loopback 目的地，該控制平面路徑也必須能連到 loopback Gateway。一般執行階段 HTTP 和 WebSocket 請求仍會使用設定的代理。 -在內部，OpenClaw 會為此功能使用兩個程序層級路由 hook： +在內部，OpenClaw 針對此功能使用兩個程序層級的路由掛鉤： - Undici dispatcher 路由涵蓋 `fetch`、以 undici 為基礎的用戶端，以及提供自身 undici dispatcher 的傳輸。 -- `global-agent` 路由涵蓋 Node 核心 `node:http` 和 `node:https` 呼叫端，包括許多建構在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的函式庫。受管理的代理模式會強制使用該全域 agent，因此明確的 Node HTTP agent 不會意外繞過操作員代理。 +- `global-agent` 路由涵蓋 Node 核心 `node:http` 和 `node:https` 呼叫者，包括許多建立在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的函式庫。受管理代理模式會強制使用該全域代理，避免明確的 Node HTTP agent 意外繞過操作員代理。 -某些 Plugin 擁有自訂傳輸，即使存在程序層級路由，也需要明確的代理接線。例如，Telegram 的 Bot API 傳輸使用自己的 HTTP/1 undici dispatcher，因此會在該擁有者專屬傳輸路徑中遵循程序代理環境，加上受管理的 `OPENCLAW_PROXY_URL` 備援。 +有些 Plugin 擁有自訂傳輸，即使已有程序層級路由，也需要明確的代理接線。例如，Telegram 的 Bot API 傳輸使用自己的 HTTP/1 undici dispatcher，因此會在該擁有者專屬的傳輸路徑中遵循程序代理環境，以及受管理的 `OPENCLAW_PROXY_URL` 備援。 -代理 URL 本身必須使用 `http://`。HTTPS 目的地仍可透過具備 HTTP `CONNECT` 的代理支援；這只表示 OpenClaw 預期的是純 HTTP 正向代理監聽器，例如 `http://127.0.0.1:3128`。 +代理 URL 本身必須使用 `http://`。透過代理使用 HTTP `CONNECT` 時，仍支援 HTTPS 目的地；這只表示 OpenClaw 預期的是純 HTTP 正向代理監聽器，例如 `http://127.0.0.1:3128`。 -代理啟用期間，OpenClaw 會清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。這些繞過清單是以目的地為基礎，因此若保留 `localhost` 或 `127.0.0.1`，就會讓高風險 SSRF 目標跳過過濾代理。 +代理啟用時，OpenClaw 會清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。這些繞過清單是以目的地為基礎，因此若保留 `localhost` 或 `127.0.0.1`，高風險 SSRF 目標就能跳過過濾代理。 關閉時，OpenClaw 會還原先前的代理環境，並重設快取的程序路由狀態。 ## 相關代理術語 -- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 執行階段輸出的輸出正向代理路由。本頁記錄此功能。 -- `gateway.auth.mode: "trusted-proxy"`：用於 Gateway 存取的輸入身分感知反向代理驗證。請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)。 -- `openclaw proxy`：用於開發與支援的本機偵錯代理與擷取檢查器。請參閱 [openclaw proxy](/zh-TW/cli/proxy)。 -- 通道或提供者專屬代理設定：特定傳輸的擁有者專屬覆寫。當目標是在整個執行階段集中控制出口時，請優先使用受管理的網路代理。 +- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 執行階段輸出的輸出正向代理路由。本頁說明此功能。 +- `gateway.auth.mode: "trusted-proxy"`：用於 Gateway 存取的輸入身分識別感知反向代理驗證。請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)。 +- `openclaw proxy`：用於開發和支援的本機除錯代理與擷取檢查器。請參閱 [openclaw proxy](/zh-TW/cli/proxy)。 +- 通道或供應商專屬代理設定：特定傳輸的擁有者專屬覆寫。若目標是在整個執行階段集中控制輸出，請優先使用受管理的網路代理。 ## 設定 @@ -92,63 +92,63 @@ openclaw gateway install --force openclaw gateway start ``` -環境備援最適合前景執行。如果你將它用於已安裝服務，請將 `OPENCLAW_PROXY_URL` 放入服務的持久環境，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然後重新安裝服務，讓 launchd、systemd 或 Scheduled Tasks 以該值啟動 Gateway。 +環境備援最適合前景執行。如果你將它用於已安裝的服務，請將 `OPENCLAW_PROXY_URL` 放入服務的持久環境，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然後重新安裝服務，讓 launchd、systemd 或排程工作以該值啟動 Gateway。 -對於 `openclaw --container ...` 命令，當設定了 `OPENCLAW_PROXY_URL` 時，OpenClaw 會將它轉送到以容器為目標的子 CLI。該 URL 必須能從容器內部連線；`127.0.0.1` 指的是容器本身，而不是主機。除非你明確覆寫該安全檢查，否則 OpenClaw 會拒絕以容器為目標命令的 loopback 代理 URL。 +對於 `openclaw --container ...` 命令，若已設定 `OPENCLAW_PROXY_URL`，OpenClaw 會將其轉發到以容器為目標的子 CLI。URL 必須能從容器內部連線；`127.0.0.1` 指的是容器本身，而不是主機。OpenClaw 會拒絕以容器為目標命令中的 loopback 代理 URL，除非你明確覆寫該安全檢查。 ## 代理需求 -代理政策是安全邊界。OpenClaw 無法驗證代理是否封鎖了正確的目標。 +代理政策是安全邊界。OpenClaw 無法驗證代理是否阻擋正確的目標。 -設定代理以： +請將代理設定為： -- 僅繫結到 loopback 或私有受信任介面。 -- 限制存取，讓只有 OpenClaw 程序、主機、容器或服務帳號可以使用它。 -- 自行解析目的地，並在 DNS 解析後封鎖目的地 IP。 -- 對純 HTTP 請求和 HTTPS `CONNECT` 通道，在連線時套用政策。 -- 拒絕對 loopback、私有、link-local、metadata、多播、保留或文件範圍的目的地型繞過。 +- 僅繫結至 loopback 或私有受信任介面。 +- 限制存取權，讓只有 OpenClaw 程序、主機、容器或服務帳戶可以使用它。 +- 自行解析目的地，並在 DNS 解析後阻擋目的地 IP。 +- 對純 HTTP 請求與 HTTPS `CONNECT` 通道，在連線時套用政策。 +- 拒絕對 loopback、私有、link-local、中繼資料、多播、保留或文件範圍的目的地型繞過。 - 除非你完全信任 DNS 解析路徑，否則避免使用主機名稱允許清單。 -- 記錄目的地、決策、狀態和原因，但不記錄請求本文、授權標頭、Cookie 或其他秘密。 +- 記錄目的地、決策、狀態和原因，但不要記錄請求本文、授權標頭、Cookie 或其他秘密。 - 將代理政策納入版本控制，並像審查安全敏感設定一樣審查變更。 -## 建議封鎖的目的地 +## 建議阻擋的目的地 -將此拒絕清單作為任何正向代理、防火牆或出口政策的起點。 +將此拒絕清單作為任何正向代理、防火牆或輸出政策的起點。 -OpenClaw 應用程式層級分類器邏輯位於 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相關的同等性 hook 是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及對 NAT64、6to4、Teredo、ISATAP 和 IPv4-mapped 形式的嵌入式 IPv4 哨兵處理。維護外部代理政策時，這些檔案是有用參考，但 OpenClaw 不會自動匯出或在你的代理中強制執行那些規則。 +OpenClaw 應用程式層級分類器邏輯位於 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相關的對等掛鉤是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及 NAT64、6to4、Teredo、ISATAP 和 IPv4-mapped 形式的內嵌 IPv4 哨兵處理。維護外部代理政策時，這些檔案是實用參考，但 OpenClaw 不會自動匯出或在你的代理中強制執行這些規則。 -| 範圍或主機 | 封鎖原因 | +| 範圍或主機 | 阻擋原因 | | ------------------------------------------------------------------------------------ | ---------------------------------------------------- | | `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback | | `::1/128` | IPv6 loopback | -| `0.0.0.0/8`, `::/128` | 未指定與此網路位址 | -| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有網路 | -| `169.254.0.0/16`, `fe80::/10` | Link-local 位址與常見雲端 metadata 路徑 | -| `169.254.169.254`, `metadata.google.internal` | 雲端 metadata 服務 | -| `100.64.0.0/10` | 電信級 NAT 共享位址空間 | -| `198.18.0.0/15`, `2001:2::/48` | 基準測試範圍 | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途與文件範圍 | -| `224.0.0.0/4`, `ff00::/8` | 多播 | -| `240.0.0.0/4` | 保留的 IPv4 | -| `fc00::/7`, `fec0::/10` | IPv6 本機/私有範圍 | -| `100::/64`, `2001:20::/28` | IPv6 丟棄與 ORCHIDv2 範圍 | -| `64:ff9b::/96`, `64:ff9b:1::/48` | 帶有嵌入式 IPv4 的 NAT64 前綴 | -| `2002::/16`, `2001::/32` | 帶有嵌入式 IPv4 的 6to4 和 Teredo | +| `0.0.0.0/8`, `::/128` | 未指定與此網路位址 | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有網路 | +| `169.254.0.0/16`, `fe80::/10` | Link-local 位址與常見雲端中繼資料路徑 | +| `169.254.169.254`, `metadata.google.internal` | 雲端中繼資料服務 | +| `100.64.0.0/10` | 電信級 NAT 共享位址空間 | +| `198.18.0.0/15`, `2001:2::/48` | 基準測試範圍 | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途與文件範圍 | +| `224.0.0.0/4`, `ff00::/8` | 多播 | +| `240.0.0.0/4` | 保留 IPv4 | +| `fc00::/7`, `fec0::/10` | IPv6 本機/私有範圍 | +| `100::/64`, `2001:20::/28` | IPv6 discard 與 ORCHIDv2 範圍 | +| `64:ff9b::/96`, `64:ff9b:1::/48` | 含內嵌 IPv4 的 NAT64 前綴 | +| `2002::/16`, `2001::/32` | 含內嵌 IPv4 的 6to4 與 Teredo | | `::/96`, `::ffff:0:0/96` | IPv4-compatible 與 IPv4-mapped IPv6 | -如果你的雲端提供者或網路平台記錄了其他 metadata 主機或保留範圍，也請加入它們。 +如果你的雲端供應商或網路平台記載了其他中繼資料主機或保留範圍，也請一併加入。 ## 驗證 -從執行 OpenClaw 的同一部主機、容器或服務帳號驗證代理： +從執行 OpenClaw 的同一主機、容器或服務帳戶驗證代理： ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -預設情況下，當未提供自訂目的地時，命令會檢查 `https://example.com/` 是否成功，並啟動一個臨時 loopback canary，代理不得連到它。當代理回傳非 2xx 拒絕回應，或以傳輸失敗封鎖 canary 時，預設拒絕檢查會通過；如果成功回應抵達 canary，則會失敗。如果未啟用與設定代理，驗證會報告設定問題；在變更設定前，可使用 `--proxy-url` 進行一次性預檢。使用 `--allowed-url` 和 `--denied-url` 測試部署專屬預期。自訂拒絕目的地是失敗即關閉：任何 HTTP 回應都表示目的地可透過代理連到，而任何傳輸錯誤都會回報為無法判定，因為 OpenClaw 無法證明代理封鎖了可連線的來源。驗證失敗時，命令會以代碼 1 結束。 +預設情況下，若未提供自訂目的地，命令會檢查 `https://example.com/` 是否成功，並啟動一個代理不得連到的暫時 loopback canary。預設拒絕檢查會在代理傳回非 2xx 拒絕回應，或以傳輸失敗阻擋 canary 時通過；若成功回應抵達 canary，則會失敗。如果未啟用並設定代理，驗證會回報設定問題；在變更設定前，可使用 `--proxy-url` 進行一次性預檢。使用 `--allowed-url` 和 `--denied-url` 測試部署專屬預期。自訂拒絕目的地採用失敗即封閉：任何 HTTP 回應都表示可透過代理連到該目的地，而任何傳輸錯誤都會回報為無法判定，因為 OpenClaw 無法證明代理阻擋了可連線的來源。驗證失敗時，命令會以代碼 1 結束。 -使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及每個目的地檢查。代理 URL 認證資料會在文字和 JSON 輸出中遮蔽： +使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及各目的地檢查。代理 URL 認證會在文字與 JSON 輸出中遮蔽： ```json { @@ -178,9 +178,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -公開請求應該會成功。回送與中繼資料請求應該會被代理封鎖。對於 `openclaw proxy validate`，內建的回送金絲雀可以區分代理拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀，因此除非你的代理公開了可另行驗證的部署專屬拒絕訊號，否則請將 HTTP 回應與不明確的傳輸失敗都視為驗證失敗。 +對公網的請求應該成功。回環與中繼資料請求應該會被代理伺服器封鎖。對於 `openclaw proxy validate`，內建的回環金絲雀可以區分代理伺服器拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀，因此除非你的代理伺服器公開了可另行驗證的部署專屬拒絕訊號，否則請將 HTTP 回應與含糊的傳輸失敗都視為驗證失敗。 -接著啟用 OpenClaw 代理路由： +然後啟用 OpenClaw 代理伺服器路由： ```bash openclaw config set proxy.enabled true @@ -198,9 +198,10 @@ proxy: ## 限制 -- 代理會改善程序本機 JavaScript HTTP 和 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。 -- 原始 `net`、`tls` 和 `http2` socket、原生附加元件與子程序，除非繼承並遵守代理環境變數，否則可能繞過 Node 層級的代理路由。 -- 使用者的本機 WebUI 和本機模型伺服器應在需要時加入操作者代理政策的允許清單；OpenClaw 不會為它們公開一般的本機網路繞過機制。 -- Gateway 控制平面代理繞過刻意限制為 `localhost` 與明確的回送 IP URL。對於本機直接 Gateway 控制平面連線，請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主機名稱會像一般主機名稱型流量一樣路由。 -- OpenClaw 不會檢查、測試或認證你的代理政策。 -- 請將代理政策變更視為具安全敏感性的營運變更。 +- 代理伺服器可提升對程序本機 JavaScript HTTP 與 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。 +- 原始 `net`、`tls` 和 `http2` 通訊端、原生附加元件與子程序，除非繼承並遵守代理伺服器環境變數，否則可能會繞過 Node 層級的代理伺服器路由。 +- IRC 是位於操作員管理的正向代理伺服器路由之外的原始 TCP/TLS 通道。在要求所有輸出流量都必須經過該正向代理伺服器的部署中，除非已明確核准直接 IRC 輸出流量，否則請設定 `channels.irc.enabled=false`。 +- 需要時，使用者本機 WebUI 與本機模型伺服器應在操作員代理伺服器政策中列入允許清單；OpenClaw 不會為它們公開一般性的本機網路繞過機制。 +- Gateway 控制平面代理伺服器繞過刻意限制於 `localhost` 與字面回環 IP URL。針對本機直接 Gateway 控制平面連線，請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主機名稱會像一般以主機名稱為基礎的流量一樣路由。 +- OpenClaw 不會檢查、測試或認證你的代理伺服器政策。 +- 請將代理伺服器政策變更視為安全性敏感的營運變更。 diff --git a/docs/zh-TW/tools/llm-task.md b/docs/zh-TW/tools/llm-task.md index 3b35f09fb..913abcb0b 100644 --- a/docs/zh-TW/tools/llm-task.md +++ b/docs/zh-TW/tools/llm-task.md @@ -1,19 +1,19 @@ --- read_when: - - 你希望在工作流程中加入僅輸出 JSON 的 LLM 步驟 - - 你需要經結構描述驗證的 LLM 輸出來進行自動化 -summary: 用於工作流程的 JSON-only LLM 任務（選用 Plugin 工具） + - 您想在工作流程中使用僅限 JSON 的 LLM 步驟 + - 你需要經結構描述驗證、可用於自動化的大型語言模型輸出 +summary: 工作流程的僅限 JSON 的 LLM 任務（選用 Plugin 工具） title: 大型語言模型任務 x-i18n: - generated_at: "2026-04-30T03:45:55Z" + generated_at: "2026-05-04T02:45:51Z" model: gpt-5.5 provider: openai - source_hash: 613aefd1bac5b9675821a118c11130c8bfaefb1673d0266f14ff4e91b47fed8b + source_hash: 9cdc5d4feef17fb6d6d90d819d4c92d26a4ec43e4f5364c6acbaad1934a89269 source_path: tools/llm-task.md workflow: 16 --- -`llm-task` 是一個**選用的 Plugin 工具**，會執行僅 JSON 的 LLM 工作，並傳回結構化輸出（可選擇依 JSON Schema 驗證）。 +`llm-task` 是一個**選用 Plugin 工具**，會執行僅輸出 JSON 的 LLM 任務，並傳回結構化輸出（可選擇使用 JSON Schema 驗證）。 這很適合 Lobster 這類工作流程引擎：你可以加入單一 LLM 步驟，而不必為每個工作流程撰寫自訂 OpenClaw 程式碼。 @@ -31,21 +31,18 @@ x-i18n: } ``` -2. 將工具加入允許清單（它是以 `optional: true` 註冊）： +2. 允許選用工具： ```json { - "agents": { - "list": [ - { - "id": "main", - "tools": { "allow": ["llm-task"] } - } - ] + "tools": { + "alsoAllow": ["llm-task"] } } ``` +只有在你想使用限制性允許清單模式時，才使用 `tools.allow`。 + ## 設定（選用） ```json @@ -68,7 +65,7 @@ x-i18n: } ``` -`allowedModels` 是 `provider/model` 字串的允許清單。如果已設定，清單以外的任何請求都會被拒絕。 +`allowedModels` 是 `provider/model` 字串的允許清單。如果有設定，清單外的任何請求都會被拒絕。 ## 工具參數 @@ -83,11 +80,11 @@ x-i18n: - `maxTokens`（數字，選用） - `timeoutMs`（數字，選用） -`thinking` 接受標準的 OpenClaw 推理預設值，例如 `low` 或 `medium`。 +`thinking` 接受標準 OpenClaw 推理預設值，例如 `low` 或 `medium`。 ## 輸出 -傳回包含已解析 JSON 的 `details.json`（並在提供 `schema` 時依其驗證）。 +傳回包含已剖析 JSON 的 `details.json`（提供 `schema` 時也會據此驗證）。 ## 範例：Lobster 工作流程步驟 @@ -113,13 +110,13 @@ openclaw.invoke --tool llm-task --action json --args-json '{ ## 安全注意事項 -- 此工具是**僅 JSON**，並會指示模型只輸出 JSON（不含程式碼圍欄、沒有說明文字）。 -- 這次執行不會向模型暴露任何工具。 -- 除非你使用 `schema` 驗證，否則應將輸出視為不可信。 -- 在任何有副作用的步驟（send、post、exec）之前放置核准流程。 +- 此工具**僅輸出 JSON**，並指示模型只輸出 JSON（不得包含程式碼區塊或評論）。 +- 此次執行不會向模型公開任何工具。 +- 除非你使用 `schema` 驗證，否則應將輸出視為不受信任。 +- 在任何會產生副作用的步驟（send、post、exec）之前放置核准流程。 -## 相關內容 +## 相關 -- [思考層級](/zh-TW/tools/thinking) +- [推理層級](/zh-TW/tools/thinking) - [Sub-agents](/zh-TW/tools/subagents) - [斜線命令](/zh-TW/tools/slash-commands) diff --git a/docs/zh-TW/tools/lobster.md b/docs/zh-TW/tools/lobster.md index 67f8f1b6c..7e5c7c4de 100644 --- a/docs/zh-TW/tools/lobster.md +++ b/docs/zh-TW/tools/lobster.md @@ -1,52 +1,52 @@ --- read_when: - - 你需要具備明確核准機制的確定性多步驟工作流程 - - 您需要繼續某個工作流程，而不重新執行先前的步驟 -summary: 適用於 OpenClaw 的型別化工作流程執行階段，具備可恢復的核准閘門。 + - 您需要具備明確核准機制的確定性多步驟工作流程 + - 你需要在不重新執行先前步驟的情況下恢復工作流程 +summary: 具備可恢復核准閘門的 OpenClaw 型別化工作流程執行階段。 title: 龍蝦 x-i18n: - generated_at: "2026-04-30T03:45:53Z" + generated_at: "2026-05-04T02:46:07Z" model: gpt-5.5 provider: openai - source_hash: 1700bcfdbcf4558cb908935834e9059221d0d26ad78ed6f9e2158f7e0b83edbd + source_hash: 67f5145b11f2d6e07e9d78a44a389ae5f236c85ec8c287ab0f217a18b622ece0 source_path: tools/lobster.md workflow: 16 --- -Lobster 是一個工作流程 shell，讓 OpenClaw 能將多步驟工具序列作為單一、確定性的操作執行，並具備明確的核准檢查點。 +Lobster 是一個工作流程 shell，讓 OpenClaw 能將多步驟工具序列作為單一、確定性的操作執行，並具有明確的核准檢查點。 -Lobster 是位於卸離背景工作之上的一層編寫層。若要了解個別任務之上的流程協調，請參閱 [Task Flow](/zh-TW/automation/taskflow)（`openclaw tasks flow`）。若要了解任務活動帳本，請參閱 [`openclaw tasks`](/zh-TW/automation/tasks)。 +Lobster 是高於 detached background work 的一層編寫層。若要了解個別任務之上的流程編排，請參閱 [TaskFlow](/zh-TW/automation/taskflow)（`openclaw tasks flow`）。若要了解任務活動帳本，請參閱 [`openclaw tasks`](/zh-TW/automation/tasks)。 ## Hook -你的助理可以建置管理自身的工具。提出一個工作流程需求，30 分鐘後你就會有一個 CLI 加上一組能以一次呼叫執行的管線。Lobster 就是缺少的那一塊：確定性的管線、明確核准，以及可恢復的狀態。 +你的助理可以建構管理自身的工具。要求一個工作流程，30 分鐘後你就會有一個 CLI 加上可作為一次呼叫執行的管線。Lobster 是缺少的那一塊：確定性管線、明確核准，以及可恢復的狀態。 ## 為什麼 -如今，複雜工作流程需要多次來回工具呼叫。每次呼叫都會消耗 token，而 LLM 必須協調每個步驟。Lobster 將這種協調移入具型別的執行階段： +如今，複雜工作流程需要許多來回工具呼叫。每次呼叫都會耗費 tokens，而 LLM 必須編排每個步驟。Lobster 將該編排移入具型別的執行階段： -- **一次呼叫取代多次呼叫**：OpenClaw 執行一次 Lobster 工具呼叫並取得結構化結果。 -- **內建核准**：副作用（傳送電子郵件、發布留言）會暫停工作流程，直到明確核准為止。 -- **可恢復**：暫停的工作流程會回傳 token；核准後可恢復，而不必重新執行所有內容。 +- **一次呼叫取代多次呼叫**：OpenClaw 執行一次 Lobster 工具呼叫，並取得結構化結果。 +- **內建核准**：副作用（寄送電子郵件、發布留言）會暫停工作流程，直到明確核准。 +- **可恢復**：暫停的工作流程會回傳 token；核准後即可恢復，而不必重新執行所有內容。 -## 為什麼使用 DSL 而不是普通程式？ +## 為什麼使用 DSL 而不是一般程式？ -Lobster 刻意保持小巧。目標不是「一種新語言」，而是一種可預測、AI 友善的管線規格，並將核准與恢復 token 作為一等功能。 +Lobster 刻意保持小而精。目標不是「一種新語言」，而是一個可預測、AI 友善的管線規格，並具備一等公民的核准與恢復 tokens。 -- **內建核准/恢復**：一般程式可以提示人類，但若沒有你自己發明該執行階段，它無法透過持久 token _暫停並恢復_。 -- **確定性 + 可稽核性**：管線是資料，因此很容易記錄、比較差異、重播與審查。 -- **為 AI 限縮的介面**：微小文法 + JSON 管線可減少「創意」程式路徑，並讓驗證變得務實可行。 -- **內建安全政策**：逾時、輸出上限、沙箱檢查與 allowlist 由執行階段強制執行，而不是由每個指令碼各自處理。 -- **仍可程式化**：每個步驟都能呼叫任何 CLI 或指令碼。若你想使用 JS/TS，可從程式碼產生 `.lobster` 檔案。 +- **內建核准/恢復**：一般程式可以提示人類，但無法在沒有自行發明執行階段的情況下，使用持久 token _暫停並恢復_。 +- **確定性 + 可稽核性**：管線是資料，因此容易記錄、比較差異、重播與審查。 +- **為 AI 限縮表面**：極小文法 + JSON 管道可減少「創意」程式碼路徑，並讓驗證變得實際可行。 +- **內建安全政策**：逾時、輸出上限、沙盒檢查與 allowlists 由執行階段強制執行，而不是由每個腳本各自處理。 +- **仍可程式化**：每個步驟都可以呼叫任何 CLI 或腳本。如果你想使用 JS/TS，可以從程式碼產生 `.lobster` 檔案。 ## 運作方式 -OpenClaw 使用內嵌 runner **於行程內**執行 Lobster 工作流程。不會產生外部 CLI 子行程；工作流程引擎在 Gateway 行程內執行，並直接回傳 JSON envelope。 +OpenClaw 使用嵌入式 runner **在程序內**執行 Lobster 工作流程。不會產生外部 CLI 子程序；工作流程引擎會在 gateway 程序內執行，並直接回傳 JSON envelope。 如果管線因核准而暫停，工具會回傳 `resumeToken`，讓你稍後繼續。 -## 模式：小型 CLI + JSON 管線 + 核准 +## 模式：小型 CLI + JSON 管道 + 核准 -建置會輸出 JSON 的小型命令，然後將它們串接成單一 Lobster 呼叫。（以下範例命令名稱請替換成你自己的。） +建構會說 JSON 的小型命令，然後將它們串接成單一 Lobster 呼叫。（以下範例命令名稱僅供參考，請替換成你自己的命令。） ```bash inbox list --json @@ -62,7 +62,7 @@ inbox apply --json } ``` -如果管線要求核准，使用 token 恢復： +如果管線要求核准，請使用 token 恢復： ```json { @@ -74,7 +74,7 @@ inbox apply --json AI 觸發工作流程；Lobster 執行步驟。核准閘門讓副作用保持明確且可稽核。 -範例：將輸入項目映射成工具呼叫： +範例：將輸入項目映射為工具呼叫： ```bash gog.gmail.search --query 'newer_than:1d' \ @@ -83,9 +83,9 @@ gog.gmail.search --query 'newer_than:1d' \ ## 僅 JSON 的 LLM 步驟（llm-task） -對於需要**結構化 LLM 步驟**的工作流程，啟用選用的 -`llm-task` plugin 工具，並從 Lobster 呼叫它。這能讓工作流程 -保持確定性，同時仍可用模型進行分類、摘要與草擬。 +對於需要**結構化 LLM 步驟**的工作流程，請啟用選用的 +`llm-task` Plugin 工具，並從 Lobster 呼叫它。這能讓工作流程保持 +確定性，同時仍能使用模型進行分類/摘要/草擬。 啟用工具： @@ -100,7 +100,7 @@ gog.gmail.search --query 'newer_than:1d' \ "list": [ { "id": "main", - "tools": { "allow": ["llm-task"] } + "tools": { "alsoAllow": ["llm-task"] } } ] } @@ -130,7 +130,7 @@ openclaw.invoke --tool llm-task --action json --args-json '{ ## 工作流程檔案（.lobster） -Lobster 可以執行包含 `name`、`args`、`steps`、`env`、`condition` 與 `approval` 欄位的 YAML/JSON 工作流程檔案。在 OpenClaw 工具呼叫中，將 `pipeline` 設為檔案路徑。 +Lobster 可以執行具有 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 欄位的 YAML/JSON 工作流程檔案。在 OpenClaw 工具呼叫中，將 `pipeline` 設為檔案路徑。 ```yaml name: inbox-triage @@ -153,22 +153,22 @@ steps: condition: $approve.approved ``` -注意： +注意事項： -- `stdin: $step.stdout` 和 `stdin: $step.json` 會傳遞前一個步驟的輸出。 -- `condition`（或 `when`）可依據 `$step.approved` 控制步驟是否執行。 +- `stdin: $step.stdout` 和 `stdin: $step.json` 會傳遞先前步驟的輸出。 +- `condition`（或 `when`）可以根據 `$step.approved` 為步驟設閘。 ## 安裝 Lobster -內建的 Lobster 工作流程會於行程內執行；不需要個別的 `lobster` 二進位檔。內嵌 runner 隨 Lobster plugin 一起提供。 +隨附的 Lobster 工作流程會在程序內執行；不需要單獨的 `lobster` 二進位檔。嵌入式 runner 會隨 Lobster Plugin 一起提供。 -如果你需要獨立的 Lobster CLI 來開發或執行外部管線，請從 [Lobster repo](https://github.com/openclaw/lobster) 安裝，並確保 `lobster` 位於 `PATH`。 +如果你需要獨立的 Lobster CLI 進行開發或外部管線，請從 [Lobster repo](https://github.com/openclaw/lobster) 安裝，並確保 `lobster` 位於 `PATH`。 ## 啟用工具 -Lobster 是**選用**的 plugin 工具（預設未啟用）。 +Lobster 是**選用**的 Plugin 工具（預設未啟用）。 -建議做法（累加且安全）： +建議方式（加法式、安全）： ```json { @@ -178,7 +178,7 @@ Lobster 是**選用**的 plugin 工具（預設未啟用）。 } ``` -或依 agent 設定： +或按代理程式設定： ```json { @@ -195,13 +195,13 @@ Lobster 是**選用**的 plugin 工具（預設未啟用）。 } ``` -除非你打算以限制性 allowlist 模式執行，否則請避免使用 `tools.allow: ["lobster"]`。 +除非你打算在限制性 allowlist 模式中執行，否則請避免使用 `tools.allow: ["lobster"]`。 -allowlist 對選用 plugin 採用選擇啟用。如果你的 allowlist 只列出 plugin 工具（例如 `lobster`），OpenClaw 會保持核心工具啟用。若要限制核心工具，也請將你想要的核心工具或群組納入 allowlist。 +選用 Plugins 的 allowlists 是選擇加入。`alsoAllow` 只會啟用具名的選用 Plugin 工具，同時保留一般核心工具集。若要限制核心工具，請將 `tools.allow` 與你想要的核心工具或群組搭配使用。 -## 範例：電子郵件分類處理 +## 範例：電子郵件分診 沒有 Lobster： @@ -216,7 +216,7 @@ User: "Check my email and draft replies" (repeat daily, no memory of what was triaged) ``` -有 Lobster： +使用 Lobster： ```json { @@ -270,7 +270,7 @@ User: "Check my email and draft replies" } ``` -使用引數執行工作流程檔案： +使用 args 執行工作流程檔案： ```json { @@ -282,7 +282,7 @@ User: "Check my email and draft replies" ### `resume` -在核准後繼續暫停的工作流程。 +在核准後繼續已暫停的工作流程。 ```json { @@ -294,20 +294,20 @@ User: "Check my email and draft replies" ### 選用輸入 -- `cwd`：管線的相對工作目錄（必須保持在 Gateway 工作目錄內）。 -- `timeoutMs`：如果工作流程超過此持續時間則中止（預設：20000）。 -- `maxStdoutBytes`：如果輸出超過此大小則中止工作流程（預設：512000）。 +- `cwd`：管線的相對工作目錄（必須保持在 gateway 工作目錄內）。 +- `timeoutMs`：如果工作流程超過此時長，則中止（預設：20000）。 +- `maxStdoutBytes`：如果輸出超過此大小，則中止（預設：512000）。 - `argsJson`：傳遞給 `lobster run --args-json` 的 JSON 字串（僅限工作流程檔案）。 ## 輸出 envelope -Lobster 會回傳 JSON envelope，其狀態為以下三者之一： +Lobster 會回傳具有三種狀態之一的 JSON envelope： - `ok` → 已成功完成 - `needs_approval` → 已暫停；需要 `requiresApproval.resumeToken` 才能恢復 - `cancelled` → 已明確拒絕或取消 -工具會同時在 `content`（格式化 JSON）與 `details`（原始物件）中公開 envelope。 +此工具會同時在 `content`（美化 JSON）和 `details`（原始物件）中公開 envelope。 ## 核准 @@ -316,40 +316,40 @@ Lobster 會回傳 JSON envelope，其狀態為以下三者之一： - `approve: true` → 恢復並繼續副作用 - `approve: false` → 取消並完成工作流程 -使用 `approve --preview-from-stdin --limit N` 可將 JSON 預覽附加到核准要求，而不需要自訂 jq/heredoc 黏合邏輯。恢復 token 現在很精簡：Lobster 會將工作流程恢復狀態儲存在其狀態目錄下，並回傳一個小型 token key。 +使用 `approve --preview-from-stdin --limit N`，即可將 JSON 預覽附加到核准要求，而不需要自訂 jq/heredoc 黏合程式碼。恢復 tokens 現在很精簡：Lobster 會將工作流程恢復狀態儲存在其狀態目錄下，並回傳一個小型 token key。 ## OpenProse -OpenProse 與 Lobster 搭配良好：使用 `/prose` 協調多 agent 準備工作，然後執行 Lobster 管線以取得確定性核准。如果 Prose 程式需要 Lobster，請透過 `tools.subagents.tools` 允許子 agent 使用 `lobster` 工具。請參閱 [OpenProse](/zh-TW/prose)。 +OpenProse 與 Lobster 搭配得很好：使用 `/prose` 編排多代理程式準備工作，然後執行 Lobster 管線以取得確定性的核准。如果 Prose 程式需要 Lobster，請透過 `tools.subagents.tools` 為子代理程式允許 `lobster` 工具。請參閱 [OpenProse](/zh-TW/prose)。 ## 安全性 -- **僅限本機行程內** — 工作流程在 Gateway 行程內執行；plugin 本身不會進行網路呼叫。 -- **不處理密鑰** — Lobster 不管理 OAuth；它會呼叫負責這些工作的 OpenClaw 工具。 -- **沙箱感知** — 當工具內容在沙箱中時會停用。 -- **已強化** — 逾時與輸出上限由內嵌 runner 強制執行。 +- **僅限本機程序內** — 工作流程在 gateway 程序內執行；Plugin 本身不會發出網路呼叫。 +- **無秘密** — Lobster 不管理 OAuth；它會呼叫負責處理的 OpenClaw 工具。 +- **沙盒感知** — 當工具情境處於沙盒中時會停用。 +- **已強化** — 逾時與輸出上限由嵌入式 runner 強制執行。 ## 疑難排解 -- **`lobster timed out`** → 增加 `timeoutMs`，或拆分長管線。 +- **`lobster timed out`** → 增加 `timeoutMs`，或拆分較長的管線。 - **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或減少輸出大小。 - **`lobster returned invalid JSON`** → 確保管線以工具模式執行，且只列印 JSON。 -- **`lobster failed`** → 查看 Gateway 記錄，以取得內嵌 runner 錯誤詳細資料。 +- **`lobster failed`** → 檢查 gateway 記錄以取得嵌入式 runner 錯誤詳細資訊。 -## 了解更多 +## 深入了解 - [Plugins](/zh-TW/tools/plugin) - [Plugin 工具編寫](/zh-TW/plugins/building-plugins#registering-agent-tools) ## 案例研究：社群工作流程 -一個公開範例：「第二大腦」CLI + Lobster 管線，用於管理三個 Markdown vault（個人、伴侶、共享）。CLI 會為統計資料、收件匣列表與過期掃描輸出 JSON；Lobster 則將這些命令串接成 `weekly-review`、`inbox-triage`、`memory-consolidation` 與 `shared-task-sync` 等工作流程，每個都具備核准閘門。可用時，AI 會處理判斷（分類）；不可用時，則退回確定性規則。 +一個公開範例：一個「第二大腦」CLI + Lobster 管線，用來管理三個 Markdown vault（個人、夥伴、共享）。該 CLI 會為統計資料、收件匣清單與過期掃描輸出 JSON；Lobster 會將這些命令串接成 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 等工作流程，每個都有核准閘門。AI 會在可用時處理判斷（分類），不可用時則回退到確定性規則。 -- 討論串：[https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033) -- Repo：[https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli) +- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033) +- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli) ## 相關 - [自動化與任務](/zh-TW/automation) — 排程 Lobster 工作流程 - [自動化概覽](/zh-TW/automation) — 所有自動化機制 -- [工具概覽](/zh-TW/tools) — 所有可用的 agent 工具 +- [工具概覽](/zh-TW/tools) — 所有可用的代理程式工具 diff --git a/docs/zh-TW/tools/slash-commands.md b/docs/zh-TW/tools/slash-commands.md index 4648458ed..5f13eabb8 100644 --- a/docs/zh-TW/tools/slash-commands.md +++ b/docs/zh-TW/tools/slash-commands.md @@ -3,40 +3,40 @@ read_when: - 使用或設定聊天指令 - 偵錯命令路由或權限 sidebarTitle: Slash commands -summary: 斜線命令：文字與原生、設定和支援的命令 +summary: 斜線命令：文字與原生模式、設定與支援的命令 title: 斜線指令 x-i18n: - generated_at: "2026-05-03T21:44:24Z" + generated_at: "2026-05-04T02:46:28Z" model: gpt-5.5 provider: openai - source_hash: 9fbdd76ccd43159cabfbc3f15f7bddd2a7ada07fcd6eea2e169d2d88df18f28c + source_hash: 49eb41674c8d0a01dbd28a2df783eb9aba3dde18d8425951a266cede825e9a84 source_path: tools/slash-commands.md workflow: 16 --- -Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，並以 `/` 開頭。僅限主機的 bash 聊天命令使用 `! `（`/bash ` 為別名）。 +Commands 由 Gateway 處理。大多數指令都必須作為以 `/` 開頭的**獨立**訊息傳送。僅限主機的 bash 聊天指令使用 `! `（`/bash ` 為別名）。 -當對話或對話串繫結至 ACP 工作階段時，一般後續文字會路由到該 ACP harness。Gateway 管理命令仍會保留在本機：`/acp ...` 一律會送達 OpenClaw ACP 命令處理器，而只要該介面啟用了命令處理，`/status` 與 `/unfocus` 就會保留在本機。 +當對話或討論串繫結到 ACP 工作階段時，一般後續文字會路由到該 ACP harness。Gateway 管理指令仍保持本機處理：`/acp ...` 一律會送達 OpenClaw ACP 指令處理器，而只要該介面啟用了指令處理，`/status` 與 `/unfocus` 就會保持本機處理。 有兩個相關系統： - + 獨立的 `/...` 訊息。 - - `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`。 + + `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令會在模型看到訊息前從訊息中移除。 - - 在一般聊天訊息中（不是僅含指令），它們會被視為「行內提示」，而且**不會**保留工作階段設定。 - - 在僅含指令的訊息中（訊息只包含指令），它們會保留到工作階段，並回覆確認訊息。 - - 指令只會套用於**已授權的傳送者**。如果已設定 `commands.allowFrom`，它就是唯一使用的允許清單；否則授權會來自通道允許清單／配對加上 `commands.useAccessGroups`。未授權的傳送者會看到指令被視為純文字。 + - 指示詞會先從訊息中移除，模型才會看到。 + - 在一般聊天訊息中（非純指示詞），它們會被視為「行內提示」，且**不會**持續保存工作階段設定。 + - 在純指示詞訊息中（訊息只包含指示詞），它們會持續保存到工作階段，並以確認訊息回覆。 + - 指示詞只會套用於**已授權的傳送者**。如果設定了 `commands.allowFrom`，它就是唯一使用的允許清單；否則授權來自頻道允許清單/配對加上 `commands.useAccessGroups`。未授權的傳送者會看到指示詞被當作純文字處理。 - 僅限允許清單／已授權的傳送者：`/help`, `/commands`, `/status`, `/whoami` (`/id`)。 + 僅限允許清單/已授權的傳送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它們會立即執行，在模型看到訊息前被移除，而剩餘文字會繼續通過一般流程。 + 它們會立即執行，在模型看到訊息前被移除，而剩餘文字會繼續走一般流程。 @@ -69,136 +69,137 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， ``` - 啟用在聊天訊息中解析 `/...`。在沒有原生命令的介面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你將此項設為 `false`，文字命令仍可運作。 + 啟用聊天訊息中的 `/...` 解析。在沒有原生指令的介面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你將此項設為 `false`，文字指令仍可運作。 - 註冊原生命令。自動：Discord/Telegram 開啟；Slack 關閉（直到你新增斜線命令）；對不支援原生命令的供應商會被忽略。設定 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native`，即可依供應商覆寫（布林值或 `"auto"`）。在 Discord 上，`false` 會在啟動期間略過斜線命令註冊與清理；先前註冊的命令可能會持續可見，直到你從 Discord 應用程式移除它們。Slack 命令是在 Slack 應用程式中管理，且不會自動移除。 + 註冊原生指令。自動：Discord/Telegram 啟用；Slack 停用（直到你加入斜線指令）；沒有原生支援的提供者會忽略。設定 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native`，可依提供者覆寫（布林值或 `"auto"`）。在 Discord 上，`false` 會在啟動期間略過斜線指令註冊與清理；先前註冊的指令可能仍會可見，直到你從 Discord 應用程式中移除。Slack 指令在 Slack 應用程式中管理，且不會自動移除。 -在 Discord 上，原生命令規格可包含 `descriptionLocalizations`，OpenClaw 會將其發布為 Discord `description_localizations`，並納入調和比較。 +在 Discord 上，原生指令規格可包含 `descriptionLocalizations`，OpenClaw 會將其發布為 Discord `description_localizations`，並納入協調比較。 - 在支援時以原生方式註冊 **skill** 命令。自動：Discord/Telegram 開啟；Slack 關閉（Slack 需要為每個 skill 建立一個斜線命令）。設定 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills`，即可依供應商覆寫（布林值或 `"auto"`）。 + 在支援時以原生方式註冊**技能**指令。自動：Discord/Telegram 啟用；Slack 停用（Slack 需要為每個技能建立一個斜線指令）。設定 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills`，可依提供者覆寫（布林值或 `"auto"`）。 - 啟用 `! ` 以執行主機 shell 命令（`/bash ` 是別名；需要 `tools.elevated` 允許清單）。 + 啟用 `! ` 以執行主機 shell 指令（`/bash ` 是別名；需要 `tools.elevated` 允許清單）。 控制 bash 在切換到背景模式前等待多久（`0` 會立即轉入背景）。 - 啟用 `/config`（讀取／寫入 `openclaw.json`）。 + 啟用 `/config`（讀取/寫入 `openclaw.json`）。 - 啟用 `/mcp`（讀取／寫入 `mcp.servers` 下由 OpenClaw 管理的 MCP 設定）。 + 啟用 `/mcp`（讀取/寫入 OpenClaw 管理、位於 `mcp.servers` 下的 MCP 設定）。 - 啟用 `/plugins`（Plugin 探索／狀態，以及安裝與啟用／停用控制）。 + 啟用 `/plugins`（Plugin 探索/狀態，以及安裝與啟用/停用控制）。 - 啟用 `/debug`（僅限執行階段覆寫）。 + 啟用 `/debug`（僅限執行階段的覆寫）。 - 啟用 `/restart` 加上 Gateway 重新啟動工具動作。 + 啟用 `/restart` 以及 Gateway 重新啟動工具動作。 - 設定僅限擁有者命令／工具介面的明確擁有者允許清單。這是可以核准危險動作並執行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人類操作員帳號。它與 `commands.allowFrom` 以及 DM 配對存取是分開的。 + 為僅限擁有者的指令/工具介面設定明確的擁有者允許清單。這是可核准危險動作並執行 `/diagnostics`、`/export-trajectory` 和 `/config` 等指令的人類操作者帳號。它與 `commands.allowFrom` 以及 DM 配對存取是分開的。 - 依通道設定：讓僅限擁有者命令必須具備**擁有者身分**才能在該介面上執行。當為 `true` 時，傳送者必須符合已解析的擁有者候選項（例如 `commands.ownerAllowFrom` 中的項目，或供應商原生擁有者中繼資料），或在內部訊息通道上持有內部 `operator.admin` 範圍。通道 `allowFrom` 中的萬用字元項目，或空白／未解析的擁有者候選清單，**不足以**通過條件；僅限擁有者命令會在該通道上預設拒絕。如果你希望僅限擁有者命令只由 `ownerAllowFrom` 與標準命令允許清單把關，請保持此項關閉。 + 依頻道設定：讓僅限擁有者的指令在該介面上執行時必須具備**擁有者身分**。當為 `true` 時，傳送者必須符合已解析的擁有者候選項目（例如 `commands.ownerAllowFrom` 中的項目或提供者原生的擁有者中繼資料），或在內部訊息頻道上持有內部 `operator.admin` 範圍。頻道 `allowFrom` 中的萬用字元項目，或空的/未解析的擁有者候選清單，**不足以**通過；僅限擁有者的指令會在該頻道上預設拒絕。若你希望僅限擁有者的指令只由 `ownerAllowFrom` 和標準指令允許清單把關，請關閉此項。 控制擁有者 ID 在系統提示中如何顯示。 - 可選擇性設定 `commands.ownerDisplay="hash"` 時使用的 HMAC secret。 + 可選擇設定在 `commands.ownerDisplay="hash"` 時使用的 HMAC 密鑰。 - 依供應商設定的命令授權允許清單。設定後，它會成為命令與指令的唯一授權來源（通道允許清單／配對與 `commands.useAccessGroups` 會被忽略）。使用 `"*"` 作為全域預設；供應商專屬鍵會覆寫它。 + 依提供者設定指令授權允許清單。設定後，它會是指令與指示詞唯一的授權來源（頻道允許清單/配對以及 `commands.useAccessGroups` 會被忽略）。使用 `"*"` 作為全域預設；提供者專屬鍵會覆寫它。 - 在未設定 `commands.allowFrom` 時，對命令強制套用允許清單／政策。 + 當未設定 `commands.allowFrom` 時，對指令強制套用允許清單/政策。 -## 命令清單 +## 指令清單 目前的真實來源： - 核心內建項目來自 `src/auto-reply/commands-registry.shared.ts` -- 產生的 dock 命令來自 `src/auto-reply/commands-registry.data.ts` -- Plugin 命令來自 Plugin `registerCommand()` 呼叫 -- 你的 Gateway 上的實際可用性仍取決於設定旗標、通道介面，以及已安裝／啟用的 Plugin +- 產生的 dock 指令來自 `src/auto-reply/commands-registry.data.ts` +- Plugin 指令來自 Plugin `registerCommand()` 呼叫 +- 在你的 Gateway 上的實際可用性仍取決於設定旗標、頻道介面，以及已安裝/啟用的 Plugins -### 核心內建命令 +### 核心內建指令 - - `/new [model]` 會啟動新工作階段；`/reset` 是重設別名。 + - `/new [model]` 會啟動新的工作階段；`/reset` 是重設別名。 - Control UI 會攔截輸入的 `/new`，以建立並切換到新的儀表板工作階段；輸入的 `/reset` 仍會執行 Gateway 的就地重設。 - - `/reset soft [message]` 會保留目前轉錄稿、丟棄重用的 CLI 後端工作階段 ID，並就地重新執行啟動／系統提示載入。 - - `/compact [instructions]` 會壓縮工作階段脈絡。請參閱 [Compaction](/zh-TW/concepts/compaction)。 - - `/stop` 會中止目前執行。 - - `/session idle ` 和 `/session max-age ` 管理對話串繫結到期時間。 + - `/reset soft [message]` 會保留目前逐字稿、捨棄重用的 CLI 後端工作階段 ID，並就地重新執行啟動/系統提示載入。 + - `/compact [instructions]` 會壓縮工作階段內容。請參閱 [Compaction](/zh-TW/concepts/compaction)。 + - `/stop` 會中止目前的執行。 + - `/session idle ` 和 `/session max-age ` 管理討論串繫結到期時間。 - `/export-session [path]` 會將目前工作階段匯出為 HTML。別名：`/export`。 - - `/export-trajectory [path]` 會要求 exec 核准，然後為目前工作階段匯出 JSONL [trajectory bundle](/zh-TW/tools/trajectory)。當你需要某個 OpenClaw 工作階段的提示、工具與轉錄稿時間軸時使用它。在群組聊天中，核准提示與匯出結果會私下傳給擁有者。別名：`/trajectory`。 + - `/export-trajectory [path]` 會要求 exec 核准，然後為目前工作階段匯出 JSONL [軌跡組合包](/zh-TW/tools/trajectory)。當你需要某個 OpenClaw 工作階段的提示、工具與逐字稿時間軸時使用它。在群組聊天中，核准提示與匯出結果會私下傳送給擁有者。別名：`/trajectory`。 - - `/think ` 設定 thinking 層級。選項來自作用中模型的供應商 profile；常見層級為 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二元 `on` 等自訂層級僅在支援處可用。別名：`/thinking`, `/t`。 + - `/think ` 設定思考層級。選項來自使用中模型的提供者設定檔；常見層級為 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二元 `on` 等自訂層級只在支援處可用。別名：`/thinking`、`/t`。 - `/verbose on|off|full` 切換詳細輸出。別名：`/v`。 - - `/trace on|off` 切換目前工作階段的 Plugin trace 輸出。 + - `/trace on|off` 切換目前工作階段的 Plugin 追蹤輸出。 - `/fast [status|on|off]` 顯示或設定快速模式。 - - `/reasoning [on|off|stream]` 切換 reasoning 可見性。別名：`/reason`。 - - `/elevated [on|off|ask|full]` 切換 elevated 模式。別名：`/elev`。 + - `/reasoning [on|off|stream]` 切換推理可見性。別名：`/reason`。 + - `/elevated [on|off|ask|full]` 切換提升模式。別名：`/elev`。 - `/exec host= security= ask= node=` 顯示或設定 exec 預設值。 - `/model [name|#|status]` 顯示或設定模型。 - - `/models [provider] [page] [limit=|size=|all]` 列出已設定／可用授權的供應商，或某個供應商的模型；加入 `all` 可瀏覽該供應商的完整目錄。 - - `/queue ` 管理佇列行為（`steer`、舊版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等選項；`/queue default` 或 `/queue reset` 會清除工作階段覆寫。請參閱 [命令佇列](/zh-TW/concepts/queue) 與 [Steering 佇列](/zh-TW/concepts/queue-steering)。 + - `/models [provider] [page] [limit=|size=|all]` 列出已設定/可用授權的提供者，或某個提供者的模型；加入 `all` 可瀏覽該提供者的完整目錄。 + - `/queue ` 管理佇列行為（`steer`、舊版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等選項；`/queue default` 或 `/queue reset` 會清除工作階段覆寫。請參閱 [指令佇列](/zh-TW/concepts/queue) 和 [Steering 佇列](/zh-TW/concepts/queue-steering)。 + - `/steer ` 會將指引注入目前工作階段的執行中，不受 `/queue` 模式影響。當工作階段閒置時，它不會啟動新的執行。別名：`/tell`。請參閱 [Steer](/zh-TW/tools/steer)。 - `/help` 顯示簡短說明摘要。 - - `/commands` 顯示產生的命令目錄。 - - `/tools [compact|verbose]` 顯示目前 agent 現在可以使用的項目。 - - `/status` 顯示執行／執行階段狀態，包括 `Execution`／`Runtime` 標籤，以及可用時的供應商用量／配額。 - - `/diagnostics [note]` 是僅限擁有者的支援報告流程，用於 Gateway 錯誤與 Codex harness 執行。它每次都會在執行 `openclaw gateway diagnostics export --json` 前要求明確 exec 核准；請勿使用 allow-all 規則核准診斷。核准後，它會傳送可貼上的報告，包含本機 bundle 路徑、manifest 摘要、隱私權注意事項與相關工作階段 ID。在群組聊天中，核准提示與報告會私下傳給擁有者。當作用中工作階段使用 OpenAI Codex harness 時，同一項核准也會將相關 Codex 回饋傳送到 OpenAI 伺服器，且完成的回覆會列出 OpenClaw 工作階段 ID、Codex 對話串 ID，以及 `codex resume ` 命令。請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。 - - `/crestodian ` 會從擁有者 DM 執行 Crestodian 設定與修復輔助工具。 - - `/tasks` 列出目前工作階段的作用中／近期背景工作。 - - `/context [list|detail|json]` 說明脈絡是如何組合的。 + - `/commands` 顯示產生的指令目錄。 + - `/tools [compact|verbose]` 顯示目前代理現在可以使用的工具。 + - `/status` 顯示執行/執行階段狀態，包括 `Execution`/`Runtime` 標籤，以及可用時的提供者使用量/配額。 + - `/diagnostics [note]` 是僅限擁有者使用的支援報告流程，用於 Gateway 錯誤與 Codex harness 執行。每次執行 `openclaw gateway diagnostics export --json` 前都會要求明確的 exec 核准；請勿使用全允許規則核准診斷。核准後，它會傳送可貼上的報告，包含本機組合包路徑、manifest 摘要、隱私注意事項與相關工作階段 ID。在群組聊天中，核准提示與報告會私下傳送給擁有者。當使用中的工作階段使用 OpenAI Codex harness 時，同一個核准也會將相關 Codex 回饋傳送到 OpenAI 伺服器，且完成的回覆會列出 OpenClaw 工作階段 ID、Codex 討論串 ID，以及 `codex resume ` 指令。請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。 + - `/crestodian ` 從擁有者 DM 執行 Crestodian 設定與修復輔助工具。 + - `/tasks` 列出目前工作階段的使用中/近期背景工作。 + - `/context [list|detail|json]` 說明內容如何組合。 - `/whoami` 顯示你的傳送者 ID。別名：`/id`。 - - `/usage off|tokens|full|cost` 控制每則回應的用量頁尾，或列印本機費用摘要。 + - `/usage off|tokens|full|cost` 控制每個回覆的使用量頁尾，或列印本機成本摘要。 - - `/skill [input]` 依名稱執行 skill。 + - `/skill [input]` 依名稱執行技能。 - `/allowlist [list|add|remove] ...` 管理允許清單項目。僅限文字。 - - `/approve ` 解析 exec 核准提示。 - - `/btw ` 提出附帶問題，而不變更未來工作階段脈絡。別名：`/side`。請參閱 [BTW](/zh-TW/tools/btw)。 + - `/approve ` 解決 exec 核准提示。 + - `/btw ` 詢問旁支問題，而不變更未來工作階段內容。別名：`/side`。請參閱 [BTW](/zh-TW/tools/btw)。 - + - `/subagents list|kill|log|info|send|steer|spawn` 管理目前工作階段的子代理執行。 - - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 工作階段與執行階段選項。 + - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 工作階段和執行階段選項。 - `/focus ` 將目前的 Discord 討論串或 Telegram 主題/對話繫結到工作階段目標。 - `/unfocus` 移除目前的繫結。 - `/agents` 列出目前工作階段中繫結到討論串的代理。 - - `/kill ` 中止一個或所有正在執行的子代理。 - - `/steer ` 將引導訊息傳送給正在執行的子代理。別名：`/tell`。 + - `/kill ` 中止一個或所有執行中的子代理。 + - `/subagents steer ` 向執行中的子代理傳送導引。請參閱 [導引](/zh-TW/tools/steer)。 - + - `/config show|get|set|unset` 讀取或寫入 `openclaw.json`。僅限擁有者。需要 `commands.config: true`。 - `/mcp show|get|set|unset` 讀取或寫入 `mcp.servers` 下由 OpenClaw 管理的 MCP 伺服器設定。僅限擁有者。需要 `commands.mcp: true`。 - `/plugins list|inspect|show|get|install|enable|disable` 檢查或變更 Plugin 狀態。`/plugin` 是別名。寫入僅限擁有者。需要 `commands.plugins: true`。 - `/debug show|set|unset|reset` 管理僅限執行階段的設定覆寫。僅限擁有者。需要 `commands.debug: true`。 - - `/restart` 在啟用時重新啟動 OpenClaw。預設：啟用；設定 `commands.restart: false` 可將其停用。 - - `/send on|off|inherit` 設定傳送政策。僅限擁有者。 + - `/restart` 在啟用時重新啟動 OpenClaw。預設：已啟用；設定 `commands.restart: false` 可停用。 + - `/send on|off|inherit` 設定傳送策略。僅限擁有者。 - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。請參閱 [TTS](/zh-TW/tools/tts)。 - `/activation mention|always` 設定群組啟用模式。 - - `/bash ` 執行主機 Shell 命令。僅限文字。別名：`! `。需要 `commands.bash: true` 加上 `tools.elevated` 允許清單。 - - `!poll [sessionId]` 檢查背景 bash 作業。 - - `!stop [sessionId]` 停止背景 bash 作業。 + - `/bash ` 執行主機 shell 命令。僅文字。別名：`! `。需要 `commands.bash: true` 加上 `tools.elevated` 允許清單。 + - `!poll [sessionId]` 檢查背景 bash 工作。 + - `!stop [sessionId]` 停止背景 bash 工作。 @@ -206,31 +207,32 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， ### 產生的停靠命令 停靠命令會將目前工作階段的回覆路由切換到另一個已連結的 -頻道。設定、範例與疑難排解請參閱[頻道停靠](/zh-TW/concepts/channel-docking)。 +頻道。請參閱 [頻道停靠](/zh-TW/concepts/channel-docking) 以取得設定、 +範例和疑難排解。 -停靠命令由支援原生命令的頻道 Plugin 產生。目前內建集合： +停靠命令是從支援原生命令的頻道 Plugin 產生。目前內建集合： - `/dock-discord`（別名：`/dock_discord`） - `/dock-mattermost`（別名：`/dock_mattermost`） - `/dock-slack`（別名：`/dock_slack`） - `/dock-telegram`（別名：`/dock_telegram`） -從直接聊天使用停靠命令，可將目前工作階段的回覆路由切換到另一個已連結的頻道。代理會保留相同的工作階段內容，但該工作階段之後的回覆會傳送到選取的頻道對等端。 +從直接聊天使用停靠命令，可將目前工作階段的回覆路由切換到另一個已連結的頻道。代理會保留相同的工作階段上下文，但該工作階段未來的回覆會傳送到所選的頻道對等端。 -停靠命令需要 `session.identityLinks`。來源傳送者與目標對等端必須位於相同身分群組中，例如 `["telegram:123", "discord:456"]`。如果 id 為 `123` 的 Telegram 使用者傳送 `/dock_discord`，OpenClaw 會在作用中的工作階段上儲存 `lastChannel: "discord"` 與 `lastTo: "456"`。如果傳送者未連結到 Discord 對等端，命令會回覆設定提示，而不是落入一般聊天流程。 +停靠命令需要 `session.identityLinks`。來源傳送者和目標對等端必須位於同一個身分群組中，例如 `["telegram:123", "discord:456"]`。如果 id 為 `123` 的 Telegram 使用者傳送 `/dock_discord`，OpenClaw 會在作用中的工作階段上儲存 `lastChannel: "discord"` 和 `lastTo: "456"`。如果傳送者未連結到 Discord 對等端，命令會回覆設定提示，而不是落入一般聊天流程。 -停靠只會變更作用中工作階段路由。它不會建立頻道帳號、授予存取權、繞過頻道允許清單，或將逐字稿歷史移到另一個工作階段。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一個產生的停靠命令來再次切換路由。 +停靠只會變更作用中工作階段的路由。它不會建立頻道帳號、授予存取權、略過頻道允許清單，或將逐字稿歷史移到另一個工作階段。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或其他產生的停靠命令再次切換路由。 ### 內建 Plugin 命令 -內建 Plugin 可以新增更多斜線命令。此 repo 中目前的內建命令： +內建 Plugin 可以新增更多斜線命令。此 repo 目前的內建命令： -- `/dreaming [on|off|status|help]` 切換記憶體 Dreaming。請參閱 [Dreaming](/zh-TW/concepts/dreaming)。 -- `/pair [qr|status|pending|approve|cleanup|notify]` 管理裝置配對/設定流程。請參閱[配對](/zh-TW/channels/pairing)。 +- `/dreaming [on|off|status|help]` 切換記憶 Dreaming。請參閱 [Dreaming](/zh-TW/concepts/dreaming)。 +- `/pair [qr|status|pending|approve|cleanup|notify]` 管理裝置配對/設定流程。請參閱 [配對](/zh-TW/channels/pairing)。 - `/phone status|arm [duration]|disarm` 暫時啟用高風險手機 Node 命令。 - `/voice status|list [limit]|set ` 管理 Talk 語音設定。在 Discord 上，原生命令名稱是 `/talkvoice`。 - `/card ...` 傳送 LINE 豐富卡片預設。請參閱 [LINE](/zh-TW/channels/line)。 -- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 檢查並控制內建 Codex 應用程式伺服器控管架構。請參閱 [Codex 控管架構](/zh-TW/plugins/codex-harness)。 +- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 檢查並控制內建 Codex app-server harness。請參閱 [Codex harness](/zh-TW/plugins/codex-harness)。 - 僅限 QQBot 的命令： - `/bot-ping` - `/bot-version` @@ -238,94 +240,94 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， - `/bot-upgrade` - `/bot-logs` -### 動態 Skill 命令 +### 動態 skill 命令 使用者可呼叫的 Skills 也會公開為斜線命令： -- `/skill [input]` 一律可作為通用進入點使用。 -- 當 Skill/Plugin 註冊時，Skills 也可能顯示為像 `/prose` 這樣的直接命令。 -- 原生 Skill 命令註冊由 `commands.nativeSkills` 與 `channels..commands.nativeSkills` 控制。 -- 命令規格可以為支援在地化描述的原生介面提供 `descriptionLocalizations`，包括 Discord。 +- `/skill [input]` 永遠可作為通用進入點使用。 +- 當 skill/Plugin 註冊時，skills 也可能以 `/prose` 這類直接命令出現。 +- 原生 skill 命令註冊由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 命令規格可以為支援本地化描述的原生介面提供 `descriptionLocalizations`，包含 Discord。 - - - 命令接受命令與引數之間的選用 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - - `/new ` 接受模型別名、`provider/model` 或供應商名稱（模糊比對）；如果沒有符合項目，文字會被視為訊息本文。 - - 如需完整供應商用量細分，請使用 `openclaw status --usage`。 + + - 命令可在命令與引數之間接受選用的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - `/new ` 接受模型別名、`provider/model`，或提供者名稱（模糊比對）；若沒有相符項，文字會被視為訊息本文。 + - 如需完整的提供者用量細分，請使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，並遵循頻道 `configWrites`。 - - 在多帳號頻道中，以設定為目標的 `/allowlist --account ` 與 `/config set channels..accounts....` 也會遵循目標帳號的 `configWrites`。 + - 在多帳號頻道中，針對設定的 `/allowlist --account ` 和 `/config set channels..accounts....` 也會遵循目標帳號的 `configWrites`。 - `/usage` 控制每次回覆的用量頁尾；`/usage cost` 會從 OpenClaw 工作階段記錄列印本機成本摘要。 - - `/restart` 預設為啟用；設定 `commands.restart: false` 可將其停用。 - - `/plugins install ` 接受與 `openclaw plugins install` 相同的 Plugin 規格：本機路徑/封存檔、npm 套件、`git:` 或 `clawhub:`，然後因為 Plugin 原始碼模組已變更而要求 Gateway 重新啟動。 - - `/plugins enable|disable` 更新 Plugin 設定，並為新的代理回合觸發 Gateway Plugin 重新載入。 + - `/restart` 預設啟用；設定 `commands.restart: false` 可停用。 + - `/plugins install ` 接受與 `openclaw plugins install` 相同的 Plugin 規格：本機路徑/封存檔、npm 套件、`git:` 或 `clawhub:`，然後因為 Plugin 來源模組已變更而要求重新啟動 Gateway。 + - `/plugins enable|disable` 會更新 Plugin 設定，並為新的代理回合觸發 Gateway Plugin 重新載入。 - - 僅限 Discord 的原生命令：`/vc join|leave|status` 控制語音頻道（無法作為文字使用）。`join` 需要 guild 與選取的語音/stage 頻道。需要 `channels.discord.voice` 與原生命令。 - - Discord 討論串繫結命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要有效啟用討論串繫結（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 + - 僅限 Discord 的原生命令：`/vc join|leave|status` 控制語音頻道（無法作為文字使用）。`join` 需要伺服器以及選取的語音/舞台頻道。需要 `channels.discord.voice` 和原生命令。 + - Discord 討論串繫結命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要啟用有效的討論串繫結（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令參考與執行階段行為：[ACP 代理](/zh-TW/tools/acp-agents)。 - - - `/verbose` 用於偵錯與提供額外可見性；一般使用時請保持**關閉**。 - - `/trace` 比 `/verbose` 範圍更窄：它只會顯示 Plugin 擁有的追蹤/偵錯行，並保持一般詳細工具雜訊關閉。 + + - `/verbose` 用於偵錯和提供額外可見性；一般使用時請保持**關閉**。 + - `/trace` 比 `/verbose` 範圍更窄：它只會揭露 Plugin 擁有的追蹤/偵錯行，並保持一般詳細工具訊息關閉。 - `/fast on|off` 會保存工作階段覆寫。使用 Sessions UI 的 `inherit` 選項可清除它並退回設定預設值。 - - `/fast` 依供應商而異：OpenAI/OpenAI Codex 會在原生 Responses 端點將它對應到 `service_tier=priority`，而直接公開 Anthropic 請求，包括傳送到 `api.anthropic.com` 的 OAuth 驗證流量，會將它對應到 `service_tier=auto` 或 `standard_only`。請參閱 [OpenAI](/zh-TW/providers/openai) 與 [Anthropic](/zh-TW/providers/anthropic)。 - - 相關時仍會顯示工具失敗摘要，但只有在 `/verbose` 為 `on` 或 `full` 時才會包含詳細失敗文字。 - - `/reasoning`、`/verbose` 與 `/trace` 在群組環境中有風險：它們可能揭露你不打算公開的內部推理、工具輸出或 Plugin 診斷。建議保持關閉，尤其是在群組聊天中。 + - `/fast` 依提供者而異：OpenAI/OpenAI Codex 會在原生 Responses 端點上將其對應到 `service_tier=priority`，而直接公開的 Anthropic 請求，包含傳送到 `api.anthropic.com` 的 OAuth 驗證流量，會將其對應到 `service_tier=auto` 或 `standard_only`。請參閱 [OpenAI](/zh-TW/providers/openai) 和 [Anthropic](/zh-TW/providers/anthropic)。 + - 工具失敗摘要在相關時仍會顯示，但詳細失敗文字只會在 `/verbose` 為 `on` 或 `full` 時包含。 + - `/reasoning`、`/verbose` 和 `/trace` 在群組環境中有風險：它們可能揭露你不打算公開的內部推理、工具輸出或 Plugin 診斷。建議保持關閉，尤其是在群組聊天中。 - `/model` 會立即保存新的工作階段模型。 - - 如果代理處於閒置狀態，下一次執行會立即使用它。 - - 如果已有執行處於作用中，OpenClaw 會將即時切換標記為待處理，並只會在乾淨的重試點重新啟動到新模型。 - - 如果工具活動或回覆輸出已經開始，待處理切換可能會維持佇列狀態，直到稍後的重試機會或下一個使用者回合。 - - 在本機 TUI 中，`/crestodian [request]` 會從一般代理 TUI 返回 Crestodian。這與訊息頻道救援模式分開，且不會授予遠端設定權限。 + - 如果代理閒置，下一次執行會立刻使用它。 + - 如果已有執行正在進行中，OpenClaw 會將即時切換標記為待處理，並只在乾淨的重試點重新啟動到新模型。 + - 如果工具活動或回覆輸出已經開始，待處理切換可能會保持佇列狀態，直到稍後的重試機會或下一個使用者回合。 + - 在本機 TUI 中，`/crestodian [request]` 會從一般代理 TUI 返回 Crestodian。這與訊息頻道救援模式分開，且不授予遠端設定權限。 - - - **快速路徑：** 來自允許清單傳送者的僅命令訊息會立即處理（繞過佇列 + 模型）。 - - **群組提及閘控：** 來自允許清單傳送者的僅命令訊息會繞過提及需求。 - - **行內捷徑（僅限允許清單傳送者）：** 某些命令嵌入一般訊息時也能運作，並會在模型看到剩餘文字之前被移除。 + + - **快速路徑：** 來自允許清單傳送者且僅含命令的訊息會立即處理（略過佇列 + 模型）。 + - **群組提及門檻：** 來自允許清單傳送者且僅含命令的訊息會略過提及需求。 + - **行內捷徑（僅限允許清單傳送者）：** 某些命令嵌入一般訊息時也能運作，並且會在模型看到剩餘文字前被移除。 - 範例：`hey /status` 會觸發狀態回覆，剩餘文字則繼續走一般流程。 - 目前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - - 未授權的僅命令訊息會被靜默忽略，行內 `/...` 權杖會被視為純文字。 + - 未授權的僅命令訊息會被靜默忽略，而行內 `/...` 權杖會被視為純文字。 - - - **Skill 命令：** `user-invocable` Skills 會公開為斜線命令。名稱會清理為 `a-z0-9_`（最多 32 個字元）；衝突會取得數字尾碼（例如 `_2`）。 - - `/skill [input]` 依名稱執行 Skill（在原生命令限制阻止每個 Skill 一個命令時很有用）。 - - 預設情況下，Skill 命令會作為一般請求轉送給模型。 - - Skills 可選擇宣告 `command-dispatch: tool`，將命令直接路由到工具（確定性，無模型）。 + + - **Skill 命令：** `user-invocable` skills 會公開為斜線命令。名稱會清理為 `a-z0-9_`（最多 32 個字元）；衝突時會加上數字後綴（例如 `_2`）。 + - `/skill [input]` 依名稱執行 skill（當原生命令限制無法支援每個 skill 各自的命令時很有用）。 + - 預設情況下，skill 命令會作為一般請求轉送給模型。 + - Skills 可以選擇宣告 `command-dispatch: tool`，將命令直接路由到工具（確定性，無模型）。 - 範例：`/prose`（OpenProse Plugin）— 請參閱 [OpenProse](/zh-TW/prose)。 - - **原生命令引數：** Discord 對動態選項使用自動完成（以及在你省略必要引數時使用按鈕選單）。當命令支援選項且你省略引數時，Telegram 與 Slack 會顯示按鈕選單。動態選項會依目標工作階段模型解析，因此像 `/think` 層級這類模型特定選項會遵循該工作階段的 `/model` 覆寫。 + - **原生命令引數：** Discord 對動態選項使用自動完成（而當你省略必要引數時使用按鈕選單）。Telegram 和 Slack 會在命令支援選項且你省略引數時顯示按鈕選單。動態選項會依目標工作階段模型解析，因此 `/think` 層級等模型特定選項會遵循該工作階段的 `/model` 覆寫。 ## `/tools` -`/tools` 回答的是執行階段問題，而不是設定問題：**這個代理現在在這段對話中可以使用什麼**。 +`/tools` 回答的是執行階段問題，而不是設定問題：**此代理現在在這段對話中可以使用什麼**。 -- 預設 `/tools` 精簡且最佳化以便快速掃描。 +- 預設 `/tools` 精簡，並針對快速瀏覽最佳化。 - `/tools verbose` 會加入簡短描述。 -- 支援引數的原生命令介面會公開相同的模式切換為 `compact|verbose`。 -- 結果以工作階段為範圍，因此變更代理、頻道、討論串、傳送者授權或模型都可能改變輸出。 -- `/tools` 包含執行階段實際可存取的工具，包括核心工具、已連線的 Plugin 工具，以及頻道擁有的工具。 +- 支援引數的原生命令介面會公開相同的模式切換 `compact|verbose`。 +- 結果以工作階段為範圍，因此變更代理、頻道、討論串、傳送者授權或模型，都可能改變輸出。 +- `/tools` 包含執行階段實際可達的工具，包含核心工具、已連接的 Plugin 工具和頻道擁有的工具。 -若要編輯設定檔與覆寫，請使用 Control UI Tools 面板或設定/目錄介面，而不是將 `/tools` 視為靜態目錄。 +若要編輯設定檔和覆寫，請使用 Control UI Tools 面板或設定/目錄介面，而不是將 `/tools` 視為靜態目錄。 -## 用量介面（顯示位置） +## 使用介面（顯示位置） -- **提供者用量/配額**（範例：「Claude 剩餘 80%」）會在啟用用量追蹤時，針對目前的模型提供者顯示在 `/status` 中。OpenClaw 會將提供者的視窗標準化為「剩餘 %」；對於 MiniMax，僅剩餘百分比欄位會在顯示前反轉，而 `model_remains` 回應會優先使用聊天模型項目加上帶有模型標籤的方案標籤。 -- **Token/快取行** 在 `/status` 中，當即時工作階段快照內容稀疏時，可以回退到最新的轉錄用量項目。既有的非零即時值仍然優先，而轉錄回退也可以在已儲存總數缺失或較小時，復原目前作用中的執行階段模型標籤，以及較大的提示導向總數。 -- **執行與執行階段：** `/status` 會以 `Execution` 回報有效的沙盒路徑，並以 `Runtime` 回報實際執行工作階段的是誰：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 後端，或 ACP 後端。 -- **每次回應的 token/成本** 由 `/usage off|tokens|full` 控制（附加到一般回覆）。 -- `/model status` 是關於**模型/驗證/端點**，不是用量。 +- **供應商用量/配額**（範例：「Claude 剩餘 80%」）會在啟用用量追蹤時，針對目前的模型供應商顯示於 `/status`。OpenClaw 會將供應商視窗正規化為「剩餘 %」；對於 MiniMax，只提供剩餘百分比的欄位會在顯示前反轉，而 `model_remains` 回應會優先使用聊天模型項目加上帶有模型標籤的方案標籤。 +- **權杖/快取行** 在 `/status` 中，當即時工作階段快照資料稀疏時，可以退回使用最新的逐字稿用量項目。現有的非零即時值仍會優先採用，而逐字稿退回也能在已儲存總量缺失或較小時，恢復作用中的執行階段模型標籤，以及較大的、偏向提示的總量。 +- **執行與執行階段：** `/status` 會針對有效的沙箱路徑回報 `Execution`，並針對實際執行工作階段的對象回報 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 後端，或 ACP 後端。 +- **每次回應的權杖/成本** 由 `/usage off|tokens|full` 控制（附加到一般回覆）。 +- `/model status` 關注的是 **模型/驗證/端點**，不是用量。 ## 模型選擇（`/model`） -`/model` 實作為指令。 +`/model` 是以指示實作。 範例： @@ -340,14 +342,14 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， 注意事項： -- `/model` 和 `/model list` 會顯示精簡的編號選擇器（模型家族 + 可用提供者）。 -- 在 Discord 上，`/model` 和 `/models` 會開啟互動式選擇器，包含提供者與模型下拉選單，以及送出步驟。 -- `/model <#>` 會從該選擇器中選取（並在可能時優先使用目前提供者）。 -- `/model status` 會顯示詳細檢視，包含已設定的提供者端點（`baseUrl`）與 API 模式（`api`）（如果可用）。 +- `/model` 和 `/model list` 會顯示精簡的編號選擇器（模型系列 + 可用供應商）。 +- 在 Discord 上，`/model` 和 `/models` 會開啟互動式選擇器，包含供應商與模型下拉選單，以及「提交」步驟。 +- `/model <#>` 會從該選擇器中選取（並在可能時偏好目前供應商）。 +- `/model status` 會顯示詳細檢視，包含已設定的供應商端點（`baseUrl`）和 API 模式（`api`，若可用）。 -## 除錯覆寫 +## 偵錯覆寫 -`/debug` 可讓你設定**僅限執行階段**的設定覆寫（記憶體中，不寫入磁碟）。僅限擁有者。預設停用；使用 `commands.debug: true` 啟用。 +`/debug` 可讓你設定 **僅限執行階段** 的設定覆寫（記憶體中，而非磁碟）。僅限擁有者。預設停用；使用 `commands.debug: true` 啟用。 範例： @@ -365,7 +367,7 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， ## Plugin 追蹤輸出 -`/trace` 可讓你切換**工作階段範圍的 Plugin 追蹤/除錯行**，而不需開啟完整詳細模式。 +`/trace` 可讓你切換 **工作階段範圍的 Plugin 追蹤/偵錯行**，而不必開啟完整詳細模式。 範例： @@ -377,11 +379,11 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， 注意事項： -- 不帶引數的 `/trace` 會顯示目前工作階段的追蹤狀態。 +- 不帶引數的 `/trace` 會顯示目前的工作階段追蹤狀態。 - `/trace on` 會為目前工作階段啟用 Plugin 追蹤行。 - `/trace off` 會再次停用它們。 - Plugin 追蹤行可能出現在 `/status` 中，也可能在一般助理回覆後作為後續診斷訊息出現。 -- `/trace` 不會取代 `/debug`；`/debug` 仍然管理僅限執行階段的設定覆寫。 +- `/trace` 不會取代 `/debug`；`/debug` 仍負責管理僅限執行階段的設定覆寫。 - `/trace` 不會取代 `/verbose`；一般詳細工具/狀態輸出仍屬於 `/verbose`。 ## 設定更新 @@ -416,12 +418,12 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， ``` -`/mcp` 會將設定儲存在 OpenClaw 設定中，而不是 Pi 擁有的專案設定。執行階段配接器會決定哪些傳輸實際上可執行。 +`/mcp` 會將設定儲存在 OpenClaw 設定中，而不是 Pi 擁有的專案設定。執行階段配接器會決定實際可執行哪些傳輸。 ## Plugin 更新 -`/plugins` 可讓操作員檢視已探索到的 Plugins，並在設定中切換啟用狀態。唯讀流程可以使用 `/plugin` 作為別名。預設停用；使用 `commands.plugins: true` 啟用。 +`/plugins` 可讓操作員檢查已發現的 Plugins，並在設定中切換啟用狀態。唯讀流程可使用 `/plugin` 作為別名。預設停用；使用 `commands.plugins: true` 啟用。 範例： @@ -434,46 +436,46 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， ``` -- `/plugins list` 和 `/plugins show` 會針對目前工作區加上磁碟設定，使用真實的 Plugin 探索。 +- `/plugins list` 和 `/plugins show` 會使用目前工作區加上磁碟設定，執行真正的 Plugin 探索。 - `/plugins install` 會從 ClawHub、npm、git、本機目錄和封存檔安裝。 - `/plugins enable|disable` 只會更新 Plugin 設定；它不會安裝或解除安裝 Plugins。 -- 啟用與停用變更會熱重新載入 Gateway Plugin 執行階段介面，供新的代理回合使用；安裝會要求重新啟動 Gateway，因為 Plugin 原始模組已變更。 +- 啟用與停用變更會為新的 agent 回合熱重新載入 Gateway Plugin 執行階段表面；安裝會要求重新啟動 Gateway，因為 Plugin 來源模組已變更。 -## 介面注意事項 +## 表面注意事項 - - - **文字指令**會在一般聊天工作階段中執行（DM 共用 `main`，群組有自己的工作階段）。 - - **原生命令**使用隔離工作階段： + + - **文字指令** 會在一般聊天工作階段中執行（私訊共用 `main`，群組有自己的工作階段）。 + - **原生指令** 使用隔離工作階段： - Discord：`agent::discord:slash:` - - Slack：`agent::slack:slash:`（前置字可透過 `channels.slack.slashCommand.sessionPrefix` 設定） + - Slack：`agent::slack:slash:`（前綴可透過 `channels.slack.slashCommand.sessionPrefix` 設定） - Telegram：`telegram:slash:`（透過 `CommandTargetSessionKey` 指向聊天工作階段） - **`/stop`** 會指向作用中的聊天工作階段，以便中止目前執行。 - `channels.slack.slashCommand` 仍支援單一 `/openclaw` 風格命令。如果你啟用 `commands.native`，必須為每個內建命令建立一個 Slack 斜線命令（名稱與 `/help` 相同）。Slack 的命令引數選單會以暫時性 Block Kit 按鈕傳送。 + `channels.slack.slashCommand` 仍支援單一 `/openclaw` 樣式指令。如果你啟用 `commands.native`，就必須為每個內建指令建立一個 Slack slash command（名稱與 `/help` 相同）。Slack 的指令引數選單會以臨時 Block Kit 按鈕傳送。 - Slack 原生例外：註冊 `/agentstatus`（不是 `/status`），因為 Slack 保留了 `/status`。文字 `/status` 在 Slack 訊息中仍可運作。 + Slack 原生例外：註冊 `/agentstatus`（不是 `/status`），因為 Slack 保留 `/status`。文字 `/status` 仍可在 Slack 訊息中運作。 -## BTW 旁支問題 +## BTW 附帶問題 -`/btw` 是關於目前工作階段的快速**旁支問題**。`/side` 是別名。 +`/btw` 是針對目前工作階段的快速 **附帶問題**。`/side` 是別名。 不同於一般聊天： -- 它會使用目前工作階段作為背景脈絡， -- 它會作為獨立的**無工具**一次性呼叫執行， +- 它使用目前工作階段作為背景脈絡， +- 它會作為獨立的 **無工具** 一次性呼叫執行， - 它不會改變未來的工作階段脈絡， -- 它不會寫入轉錄歷史， -- 它會作為即時旁支結果傳送，而不是一般助理訊息。 +- 它不會寫入逐字稿歷史， +- 它會作為即時附帶結果傳送，而不是一般助理訊息。 -這讓 `/btw` 在你想要臨時釐清，同時讓主要工作繼續進行時很有用。 +這讓 `/btw` 適合在主要任務持續進行時，取得暫時性的釐清。 範例： @@ -482,7 +484,7 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送， /side what changed while the main run continued? ``` -完整行為與用戶端 UX 詳情，請參閱 [BTW 旁支問題](/zh-TW/tools/btw)。 +完整行為與用戶端 UX 詳細資訊，請參閱 [BTW 附帶問題](/zh-TW/tools/btw)。 ## 相關 diff --git a/docs/zh-TW/tools/steer.md b/docs/zh-TW/tools/steer.md new file mode 100644 index 000000000..6315e21b7 --- /dev/null +++ b/docs/zh-TW/tools/steer.md @@ -0,0 +1,74 @@ +--- +read_when: + - 在代理程式已在執行時使用 /steer 或 /tell + - 比較 /steer 與 /queue steer + - 判斷要引導目前的執行、子代理，還是 ACP 工作階段 +sidebarTitle: Steer +summary: 在不變更佇列模式的情況下引導進行中的執行 +title: 引導 +x-i18n: + generated_at: "2026-05-04T02:46:33Z" + model: gpt-5.5 + provider: openai + source_hash: 71e1c80c0eea86d5c3c29513d3ed0675c04779fc9c6ee3b8a76c4bedaa264d22 + source_path: tools/steer.md + workflow: 16 +--- + +`/steer` 會將指引傳送給已在作用中的執行。它用於「在這次執行仍在工作時調整它」的情境，而不是用來開始新的回合。 + +## 目前工作階段 + +使用頂層 `/steer` 來指定目前工作階段的作用中執行： + +```text +/steer prefer the smaller patch and keep the tests focused +/tell summarize before making the next tool call +``` + +行為： + +- 只指定目前工作階段的作用中執行。 +- 獨立於工作階段的 `/queue` 模式運作。 +- 當工作階段閒置時，不會開始新的執行。 +- 當沒有可引導的作用中執行時，會回覆警告。 +- 使用作用中 runtime 的引導路徑，因此模型會在下一個支援的 runtime 邊界看到該指引。 + +## 引導與佇列 + +`/queue steer` 會變更一般傳入訊息在執行作用中時到達的行為。`/steer ` 是明確命令，會嘗試在下一個支援的 runtime 邊界，將該命令的訊息注入作用中執行，不受已儲存的 `/queue` 設定影響。 + +使用： + +- 當你想立即引導作用中執行時，使用 `/steer `。 +- 當你想讓未來的一般訊息預設引導作用中執行時，使用 `/queue steer`。 +- 當新訊息應等待稍後回合，而不是引導作用中執行時，使用 `/queue collect` 或 `/queue followup`。 + +如需佇列模式與備援行為，請參閱[命令佇列](/zh-TW/concepts/queue)和[引導佇列](/zh-TW/concepts/queue-steering)。 + +## 子代理 + +當目標是子執行時，使用 `/subagents steer`： + +```text +/subagents steer 2 focus only on the API surface +``` + +頂層 `/steer` 不會依 id 或清單索引選取子代理。它一律指定目前工作階段的作用中執行。請參閱[子代理](/zh-TW/tools/subagents)，了解子代理 id、標籤與控制命令。 + +## ACP 工作階段 + +當目標是 ACP harness 工作階段時，使用 `/acp steer`： + +```text +/acp steer --session agent:main:acp:codex tighten the repro +``` + +請參閱 [ACP 代理](/zh-TW/tools/acp-agents)，了解 ACP 工作階段選取與 runtime 行為。 + +## 相關 + +- [斜線命令](/zh-TW/tools/slash-commands) +- [命令佇列](/zh-TW/concepts/queue) +- [引導佇列](/zh-TW/concepts/queue-steering) +- [子代理](/zh-TW/tools/subagents) diff --git a/docs/zh-TW/tools/subagents.md b/docs/zh-TW/tools/subagents.md index 56bad9807..a4b7eadb5 100644 --- a/docs/zh-TW/tools/subagents.md +++ b/docs/zh-TW/tools/subagents.md @@ -1,37 +1,41 @@ --- read_when: - - 您想透過代理程式進行背景或平行工作 + - 你想透過代理程式進行背景或平行工作 - 你正在變更 sessions_spawn 或子代理工具政策 - - 你正在實作或疑難排解綁定執行緒的子代理工作階段 + - 您正在實作或疑難排解綁定執行緒的子代理工作階段 sidebarTitle: Sub-agents -summary: 啟動隔離的背景代理執行工作，並將結果回報至發出請求的聊天 +summary: 啟動隔離的背景代理執行，並將結果回報至請求者的聊天對話 title: 子代理 x-i18n: - generated_at: "2026-05-02T21:06:23Z" + generated_at: "2026-05-04T02:46:41Z" model: gpt-5.5 provider: openai - source_hash: 0e964df543bd19435daf94f2c85a34b9d32e07662405d2eac7635935f1e7bf64 + source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37 source_path: tools/subagents.md workflow: 16 --- -子代理是從現有代理執行中產生的背景代理執行。 -它們會在自己的工作階段中執行（`agent::subagent:`），並在完成時將結果**公告**回請求者聊天頻道。每個子代理執行都會被追蹤為一個[背景工作](/zh-TW/automation/tasks)。 +子代理是在既有代理執行中生成的背景代理執行。 +它們會在自己的工作階段（`agent::subagent:`）中執行， +並在完成後將結果**公告**回請求者聊天 +頻道。每次子代理執行都會作為 +[背景任務](/zh-TW/automation/tasks)追蹤。 主要目標： -- 平行處理「研究 / 長時間工作 / 慢速工具」工作，而不阻塞主要執行。 -- 預設保持子代理隔離（工作階段分離 + 選用沙盒）。 -- 讓工具介面難以誤用：子代理預設**不會**取得工作階段工具。 -- 支援可設定的巢狀深度，以用於協調器模式。 +- 平行處理「研究／長任務／慢速工具」工作，而不阻塞主要執行。 +- 預設讓子代理保持隔離（工作階段分離 + 選用沙箱）。 +- 讓工具介面難以被誤用：子代理預設**不會**取得工作階段工具。 +- 支援可設定的巢狀深度，以配合協調器模式。 -**成本注意事項：**每個子代理預設都有自己的脈絡與權杖使用量。對於繁重或重複性的工作，請為子代理設定較便宜的模型，並讓主要代理使用較高品質的模型。可透過 `agents.defaults.subagents.model` 或個別代理覆寫進行設定。當子代理確實需要請求者目前的逐字稿時，代理可以在該次產生時要求 `context: "fork"`。繫結執行緒的子代理工作階段預設為 `context: "fork"`，因為它們會將目前對話分支到後續執行緒。 +**成本注意事項：**每個子代理預設都有自己的上下文與權杖用量。對於繁重或重複性任務，請為子代理設定較便宜的模型，並讓主要代理使用較高品質的模型。可透過 `agents.defaults.subagents.model` 或個別代理覆寫設定。當子執行確實需要請求者目前的對話紀錄時，代理可以在該次生成時要求 `context: "fork"`。執行緒綁定的子代理工作階段預設為 `context: "fork"`，因為它們會把目前對話分支到後續執行緒。 ## 斜線命令 -使用 `/subagents` 檢查或控制**目前工作階段**的子代理執行： +使用 `/subagents` 檢查或控制**目前 +工作階段**的子代理執行： ```text /subagents list @@ -43,11 +47,14 @@ x-i18n: /subagents spawn [--model ] [--thinking ] ``` -`/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 id、逐字稿路徑、清理）。使用 `sessions_history` 取得有界且經安全篩選的回想檢視；需要原始完整逐字稿時，請檢查磁碟上的逐字稿路徑。 +使用頂層 [`/steer `](/zh-TW/tools/steer) 來引導目前請求者工作階段的作用中執行。當目標是子執行時，請使用 `/subagents steer `。 -### 執行緒繫結控制 +`/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 ID、 +對話紀錄路徑、清理）。使用 `sessions_history` 取得有界且經安全篩選的回想檢視；當你需要原始完整對話紀錄時，請檢查磁碟上的對話紀錄路徑。 -這些命令適用於支援持久執行緒繫結的頻道。 +### 執行緒綁定控制 + +這些命令可用於支援持久執行緒綁定的頻道。 請參閱下方的[支援執行緒的頻道](#thread-supporting-channels)。 ```text @@ -58,141 +65,162 @@ x-i18n: /session max-age ``` -### 產生行為 +### 生成行為 -`/subagents spawn` 會以使用者命令啟動背景子代理（不是內部轉送），並在執行完成時將一則最終完成更新傳回請求者聊天。 +`/subagents spawn` 會以使用者命令（而非內部轉送）啟動一個背景子代理，並在執行完成時將一則最終完成更新送回 +請求者聊天。 - - - 產生命令是非阻塞的；它會立即傳回執行 id。 - - 完成時，子代理會向請求者聊天頻道公告摘要/結果訊息。 - - 完成採用推送式。產生後，請**不要**為了等待完成而迴圈輪詢 `/subagents list`、`sessions_list` 或 `sessions_history`；只有在除錯或介入時才按需檢查狀態。 - - 完成時，在公告清理流程繼續之前，OpenClaw 會盡力關閉該子代理工作階段開啟並追蹤的瀏覽器分頁/程序。 + + - 生成命令是非阻塞的；它會立即傳回執行 ID。 + - 完成時，子代理會將摘要／結果訊息公告回請求者聊天頻道。 + - 完成是推送式的。一旦生成後，請**不要**為了等待它完成而循環輪詢 `/subagents list`、`sessions_list` 或 `sessions_history`；只在除錯或介入時按需檢查狀態。 + - 完成時，OpenClaw 會盡最大努力在公告清理流程繼續前，關閉該子代理工作階段開啟且已追蹤的瀏覽器分頁／程序。 - - - OpenClaw 會先嘗試使用穩定的冪等性金鑰直接 `agent` 傳遞。 - - 如果直接傳遞失敗，會退回佇列路由。 + + - OpenClaw 會先嘗試使用穩定的冪等性鍵進行直接 `agent` 交付。 + - 如果直接交付失敗，會退回佇列路由。 - 如果佇列路由仍不可用，公告會以短暫的指數退避重試，然後才最終放棄。 - - 完成傳遞會保留已解析的請求者路由：可用時，繫結執行緒或繫結對話的完成路由優先；如果完成來源只提供頻道，OpenClaw 會從請求者工作階段已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）補上缺少的目標/帳號，讓直接傳遞仍可運作。 + - 完成交付會保留已解析的請求者路由：可用時，執行緒綁定或對話綁定的完成路由優先；如果完成來源只提供頻道，OpenClaw 會從請求者工作階段已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）補齊遺失的目標／帳戶，讓直接交付仍可運作。 - - 交還給請求者工作階段的完成交接內容，是執行階段產生的內部脈絡（不是使用者撰寫的文字），並包含： + + 給請求者工作階段的完成交接是執行階段產生的內部上下文（不是使用者撰寫文字），並包含： - - `Result` — 最新可見的 `assistant` 回覆文字，否則為已清理的最新工具/toolResult 文字。終止失敗的執行不會重用擷取到的回覆文字。 + - `Result` — 最新可見的 `assistant` 回覆文字；否則為經清理的最新工具／toolResult 文字。終止且失敗的執行不會重用已擷取的回覆文字。 - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。 - - 精簡的執行階段/權杖統計。 - - 一項傳遞指示，要求請求者代理以一般助理語氣改寫（而不是轉送原始內部中繼資料）。 + - 精簡的執行階段／權杖統計。 + - 一則交付指示，要求請求者代理以一般助理語氣重寫（不要轉發原始內部中繼資料）。 - + - `--model` 和 `--thinking` 會覆寫該特定執行的預設值。 - 使用 `info`/`log` 在完成後檢查詳細資料與輸出。 - - `/subagents spawn` 是一次性模式（`mode: "run"`）。若要使用持久的繫結執行緒工作階段，請使用 `sessions_spawn` 搭配 `thread: true` 和 `mode: "session"`。 - - 對於 ACP 控制程式工作階段（Claude Code、Gemini CLI、OpenCode，或明確的 Codex ACP/acpx），當工具宣告該執行階段時，請使用 `sessions_spawn` 搭配 `runtime: "acp"`。除錯完成或代理對代理迴圈時，請參閱 [ACP 傳遞模型](/zh-TW/tools/acp-agents#delivery-model)。啟用 `codex` Plugin 時，Codex 聊天/執行緒控制應優先使用 `/codex ...`，而不是 ACP，除非使用者明確要求 ACP/acpx。 - - OpenClaw 會隱藏 `runtime: "acp"`，直到 ACP 已啟用、請求者未被沙盒化，且已載入如 `acpx` 這類後端 Plugin。`runtime: "acp"` 需要外部 ACP 控制程式 id，或 `runtime.type="acp"` 的 `agents.list[]` 項目；對於來自 `agents_list` 的一般 OpenClaw 設定代理，請使用預設子代理執行階段。 + - `/subagents spawn` 是一次性模式（`mode: "run"`）。若要使用持久執行緒綁定工作階段，請搭配 `thread: true` 和 `mode: "session"` 使用 `sessions_spawn`。 + - 對於 ACP 控制器工作階段（Claude Code、Gemini CLI、OpenCode，或明確的 Codex ACP/acpx），當工具宣告該執行階段時，請搭配 `runtime: "acp"` 使用 `sessions_spawn`。除錯完成或代理對代理迴圈時，請參閱 [ACP 交付模型](/zh-TW/tools/acp-agents#delivery-model)。啟用 `codex` Plugin 時，除非使用者明確要求 ACP/acpx，否則 Codex 聊天／執行緒控制應偏好 `/codex ...` 而非 ACP。 + - OpenClaw 會隱藏 `runtime: "acp"`，直到 ACP 已啟用、請求者未被沙箱化，且已載入例如 `acpx` 的後端 Plugin。`runtime: "acp"` 預期使用外部 ACP 控制器 ID，或具有 `runtime.type="acp"` 的 `agents.list[]` 項目；一般 OpenClaw 設定代理從 `agents_list` 使用預設子代理執行階段。 -## 脈絡模式 +## 上下文模式 -原生子代理會以隔離狀態啟動，除非呼叫端明確要求分支目前逐字稿。 +原生子代理會以隔離方式啟動，除非呼叫端明確要求分支目前的對話紀錄。 | 模式 | 使用時機 | 行為 | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | 全新研究、獨立實作、慢速工具工作，或任何可在工作文字中簡要說明的事項 | 建立乾淨的子逐字稿。這是預設值，並能降低權杖使用量。 | -| `fork` | 依賴目前對話、先前工具結果，或請求者逐字稿中既有細緻指示的工作 | 在子代理開始前，將請求者逐字稿分支到子工作階段。 | +| `isolated` | 全新研究、獨立實作、慢速工具工作，或任何可在任務文字中簡報的事項 | 建立乾淨的子對話紀錄。這是預設值，並可降低權杖使用量。 | +| `fork` | 依賴目前對話、先前工具結果，或請求者對話紀錄中已存在的細緻指示的工作 | 在子執行開始前，將請求者對話紀錄分支到子工作階段。 | -請謹慎使用 `fork`。它用於對脈絡敏感的委派，而不是取代清楚撰寫工作提示。 +請節制使用 `fork`。它是為了上下文敏感的委派，不是撰寫清楚任務提示的替代品。 ## 工具：`sessions_spawn` -在全域 `subagent` 通道上以 `deliver: false` 啟動子代理執行，然後執行公告步驟，並將公告回覆發布到請求者聊天頻道。 +在全域 `subagent` 通道上以 `deliver: false` 啟動子代理執行， +然後執行公告步驟，並將公告回覆發布到請求者 +聊天頻道。 -可用性取決於呼叫端的有效工具政策。`coding` 和 `full` 設定檔預設公開 `sessions_spawn`。`messaging` 設定檔不會；若應委派工作的代理需要，請加入 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` 或使用 `tools.profile: "coding"`。頻道/群組、提供者、沙盒，以及個別代理的允許/拒絕政策，仍可在設定檔階段後移除此工具。從相同工作階段使用 `/tools` 確認有效工具清單。 +可用性取決於呼叫端的有效工具政策。`coding` 和 +`full` 設定檔預設會公開 `sessions_spawn`。`messaging` 設定檔 +不會；請加入 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", +"subagents"]`，或對應該委派工作的代理使用 `tools.profile: "coding"`。 +頻道／群組、提供者、沙箱，以及個別代理的允許／拒絕政策， +仍可在設定檔階段後移除該工具。請在相同工作階段使用 `/tools` +確認有效工具清單。 **預設值：** -- **模型：**繼承呼叫端，除非你設定 `agents.defaults.subagents.model`（或個別代理的 `agents.list[].subagents.model`）；明確的 `sessions_spawn.model` 仍會優先。 -- **思考：**繼承呼叫端，除非你設定 `agents.defaults.subagents.thinking`（或個別代理的 `agents.list[].subagents.thinking`）；明確的 `sessions_spawn.thinking` 仍會優先。 +- **模型：**除非你設定 `agents.defaults.subagents.model`（或個別代理的 `agents.list[].subagents.model`），否則會繼承呼叫端；明確的 `sessions_spawn.model` 仍會優先。 +- **Thinking：**除非你設定 `agents.defaults.subagents.thinking`（或個別代理的 `agents.list[].subagents.thinking`），否則會繼承呼叫端；明確的 `sessions_spawn.thinking` 仍會優先。 - **執行逾時：**如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 會在已設定時使用 `agents.defaults.subagents.runTimeoutSeconds`；否則退回 `0`（無逾時）。 ### 工具參數 - 子代理的工作說明。 + 子代理的任務描述。 選用的人類可讀標籤。 - 在 `subagents.allowAgents` 允許時，於另一個代理 id 底下產生。 + 在 `subagents.allowAgents` 允許時，於另一個代理 ID 之下生成。 - `acp` 僅適用於外部 ACP 控制程式（`claude`、`droid`、`gemini`、`opencode`，或明確要求的 Codex ACP/acpx），以及 `runtime.type` 為 `acp` 的 `agents.list[]` 項目。 + `acp` 僅用於外部 ACP 控制器（`claude`、`droid`、`gemini`、`opencode`，或明確要求的 Codex ACP/acpx），以及其 `runtime.type` 為 `acp` 的 `agents.list[]` 項目。 - 僅限 ACP。當 `runtime: "acp"` 時恢復現有 ACP 控制程式工作階段；原生子代理產生會忽略此項。 + 僅限 ACP。當 `runtime: "acp"` 時，繼續既有 ACP 控制器工作階段；原生子代理生成會忽略此參數。 - 僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流到父工作階段；原生子代理產生請省略。 + 僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流到父工作階段；原生子代理生成請省略。 - 覆寫子代理模型。無效值會被略過，子代理會在預設模型上執行，並在工具結果中附上警告。 + 覆寫子代理模型。無效值會被略過，子代理會在預設模型上執行，並在工具結果中顯示警告。 - 覆寫子代理執行的思考層級。 + 覆寫子代理執行的 thinking 等級。 已設定時預設為 `agents.defaults.subagents.runTimeoutSeconds`，否則為 `0`。設定後，子代理執行會在 N 秒後中止。 - 當為 `true` 時，會為此子代理工作階段要求頻道執行緒繫結。 + 當為 `true` 時，會為此子代理工作階段要求頻道執行緒綁定。 如果 `thread: true` 且省略 `mode`，預設會變成 `session`。`mode: "session"` 需要 `thread: true`。 - `"delete"` 會在公告後立即封存（仍會透過重新命名保留逐字稿）。 + `"delete"` 會在公告後立即封存（仍會透過重新命名保留對話紀錄）。 - `require` 會拒絕產生，除非目標子執行階段已沙盒化。 + `require` 會拒絕生成，除非目標子執行階段已沙箱化。 - `fork` 會將請求者目前逐字稿分支到子工作階段。僅限原生子代理。繫結執行緒的產生預設為 `fork`；非執行緒產生預設為 `isolated`。 + `fork` 會將請求者目前的對話紀錄分支到子工作階段。僅限原生子代理。執行緒綁定生成預設為 `fork`；非執行緒生成預設為 `isolated`。 -`sessions_spawn` **不**接受頻道傳遞參數（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需傳遞，請從已產生的執行使用 `message`/`sessions_send`。 +`sessions_spawn` **不**接受頻道交付參數（`target`、 +`channel`、`to`、`threadId`、`replyTo`、`transport`）。若要交付，請從生成的執行使用 +`message`/`sessions_send`。 -## 繫結執行緒的工作階段 +## 執行緒綁定工作階段 -當頻道啟用執行緒繫結時，子代理可以保持繫結到某個執行緒，讓該執行緒中的後續使用者訊息持續路由到相同的子代理工作階段。 +當頻道啟用執行緒綁定時，子代理可以保持綁定到 +某個執行緒，讓該執行緒中的後續使用者訊息持續路由到 +同一個子代理工作階段。 ### 支援執行緒的頻道 -**Discord** 目前是唯一支援的頻道。它支援持久的繫結執行緒子代理工作階段（`sessions_spawn` 搭配 `thread: true`）、手動執行緒控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及配接器金鑰 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSessions`。 +**Discord** 目前是唯一支援的頻道。它支援 +持久執行緒綁定的子代理工作階段（搭配 +`thread: true` 的 `sessions_spawn`）、手動執行緒控制（`/focus`、`/unfocus`、`/agents`、 +`/session idle`、`/session max-age`），以及配接器鍵 +`channels.discord.threadBindings.enabled`、 +`channels.discord.threadBindings.idleHours`、 +`channels.discord.threadBindings.maxAgeHours` 和 +`channels.discord.threadBindings.spawnSessions`。 ### 快速流程 - - `sessions_spawn` 搭配 `thread: true`（並可選擇搭配 `mode: "session"`）。 + + 搭配 `thread: true`（並可選擇搭配 `mode: "session"`）使用 `sessions_spawn`。 - - OpenClaw 會在作用中的頻道中建立執行緒，或將執行緒繫結到該工作階段目標。 + + OpenClaw 會在作用中頻道中建立或綁定一個執行緒到該工作階段目標。 - - 該執行緒中的回覆與後續訊息會路由到已繫結的工作階段。 + + 該執行緒中的回覆與後續訊息會路由到已綁定的工作階段。 - - 使用 `/session idle` 檢查/更新因閒置而自動取消聚焦的設定，並使用 `/session max-age` 控制硬性上限。 + + 使用 `/session idle` 檢查／更新非作用狀態自動取消聚焦，並使用 + `/session max-age` 控制硬性上限。 - - 使用 `/unfocus` 手動分離。 + + 使用 `/unfocus` 手動解除附加。 @@ -200,58 +228,57 @@ x-i18n: | 指令 | 效果 | | ------------------ | --------------------------------------------------------------------- | -| `/focus ` | 將目前執行緒（或建立一個）綁定到子代理/session 目標 | -| `/unfocus` | 移除目前已綁定執行緒的綁定 | -| `/agents` | 列出作用中的執行與綁定狀態（`thread:` 或 `unbound`） | -| `/session idle` | 檢查/更新閒置自動解除焦點（僅限已聚焦的綁定執行緒） | -| `/session max-age` | 檢查/更新硬性上限（僅限已聚焦的綁定執行緒） | +| `/focus ` | 將目前執行緒（或建立一個）繫結至子代理/工作階段目標 | +| `/unfocus` | 移除目前已繫結執行緒的繫結 | +| `/agents` | 列出作用中的執行與繫結狀態（`thread:` 或 `unbound`） | +| `/session idle` | 檢查/更新閒置自動解除聚焦（僅限已聚焦的已繫結執行緒） | +| `/session max-age` | 檢查/更新硬性上限（僅限已聚焦的已繫結執行緒） | ### 設定開關 - **全域預設值：** `session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 -- **頻道覆寫與生成自動綁定鍵** 視配接器而定。請參閱上方的[支援執行緒的頻道](#thread-supporting-channels)。 +- **頻道覆寫與產生時自動繫結鍵** 視配接器而定。請參閱上方的[支援執行緒的頻道](#thread-supporting-channels)。 -請參閱[設定參考](/zh-TW/gateway/configuration-reference)與 -[斜線指令](/zh-TW/tools/slash-commands)，了解目前的配接器詳細資訊。 +請參閱[設定參考](/zh-TW/gateway/configuration-reference)和 +[斜線指令](/zh-TW/tools/slash-commands)，以取得目前的配接器詳細資料。 ### 允許清單 - 可透過明確 `agentId` 指定為目標的 agent ID 清單（`["*"]` 允許任何項目）。預設值：僅限請求者 agent。如果你設定了清單，且仍希望請求者能以 `agentId` 生成自身，請在清單中包含請求者 ID。 + 可透過明確 `agentId` 指定為目標的代理 ID 清單（`["*"]` 允許任何代理）。預設值：僅限請求端代理。如果你設定清單，且仍希望請求端能使用 `agentId` 產生自身，請在清單中加入請求端 ID。 - 當請求者 agent 未設定自己的 `subagents.allowAgents` 時使用的預設目標 agent 允許清單。 + 當請求端代理未設定自己的 `subagents.allowAgents` 時使用的預設目標代理允許清單。 - 封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔）。每個 agent 的覆寫：`agents.list[].subagents.requireAgentId`。 + 封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔）。單一代理覆寫：`agents.list[].subagents.requireAgentId`。 -如果請求者 session 受沙箱限制，`sessions_spawn` 會拒絕 -可能以非沙箱方式執行的目標。 +如果請求端工作階段在沙箱中執行，`sessions_spawn` 會拒絕 +將在非沙箱中執行的目標。 ### 探索 -使用 `agents_list` 查看哪些 agent ID 目前允許用於 -`sessions_spawn`。回應會包含每個列出 agent 的有效 -模型與嵌入式執行階段中繼資料，讓呼叫者能區分 Pi、Codex -app-server 與其他已設定的原生執行階段。 +使用 `agents_list` 查看目前允許 `sessions_spawn` 的代理 ID。 +回應會包含每個列出代理的有效模型與嵌入式執行階段中繼資料， +讓呼叫端能區分 Pi、Codex 應用程式伺服器，以及其他已設定的原生執行階段。 ### 自動封存 -- 子代理 session 會在 `agents.defaults.subagents.archiveAfterMinutes` 之後自動封存（預設 `60`）。 -- 封存會使用 `sessions.delete`，並將逐字稿重新命名為 `*.deleted.`（同一資料夾）。 -- `cleanup: "delete"` 會在 announce 後立即封存（仍會透過重新命名保留逐字稿）。 -- 自動封存是盡力而為；如果 Gateway 重新啟動，待處理的計時器會遺失。 -- `runTimeoutSeconds` **不會** 自動封存；它只會停止執行。session 會保留到自動封存為止。 -- 自動封存同樣適用於深度 1 與深度 2 的 session。 -- 瀏覽器清理與封存清理是分開的：追蹤的瀏覽器分頁/程序會在執行完成時盡力關閉，即使逐字稿/session 記錄仍被保留。 +- 子代理工作階段會在 `agents.defaults.subagents.archiveAfterMinutes` 後自動封存（預設為 `60`）。 +- 封存會使用 `sessions.delete`，並將記錄重新命名為 `*.deleted.`（同一資料夾）。 +- `cleanup: "delete"` 會在回報後立即封存（仍會透過重新命名保留記錄）。 +- 自動封存是盡力而為；如果 gateway 重新啟動，待處理的計時器會遺失。 +- `runTimeoutSeconds` **不會**自動封存；它只會停止執行。工作階段會保留到自動封存為止。 +- 自動封存同樣適用於深度 1 和深度 2 工作階段。 +- 瀏覽器清理與封存清理是分開的：追蹤中的瀏覽器分頁/程序會在執行完成時盡力關閉，即使記錄/工作階段紀錄被保留也一樣。 ## 巢狀子代理 -預設情況下，子代理不能生成自己的子代理 -（`maxSpawnDepth: 1`）。設定 `maxSpawnDepth: 2` 可啟用一層 -巢狀結構，也就是**協調器模式**：主要 → 協調器子代理 → -工作子子代理。 +預設情況下，子代理無法產生自己的子代理 +（`maxSpawnDepth: 1`）。設定 `maxSpawnDepth: 2` 可啟用一層巢狀 +結構，即**協調器模式**：主代理 → 協調器子代理 → +工作子代理的子代理。 ```json5 { @@ -270,153 +297,149 @@ app-server 與其他已設定的原生執行階段。 ### 深度層級 -| 深度 | Session 鍵形狀 | 角色 | 可以生成？ | +| 深度 | 工作階段鍵形狀 | 角色 | 可以產生嗎？ | | ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | 主要 agent | 一律可以 | +| 0 | `agent::main` | 主代理 | 一律可以 | | 1 | `agent::subagent:` | 子代理（允許深度 2 時為協調器） | 僅當 `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | 子子代理（葉節點工作者） | 永不 | +| 2 | `agent::subagent::subagent:` | 子代理的子代理（葉節點工作代理） | 永不 | -### Announce 鏈 +### 回報鏈 -結果會沿著鏈往上回傳： +結果會沿著鏈向上流動： -1. 深度 2 工作者完成 → announce 給其父層（深度 1 協調器）。 -2. 深度 1 協調器收到 announce、彙整結果並完成 → announce 給主要項目。 -3. 主要 agent 收到 announce，並交付給使用者。 +1. 深度 2 工作代理完成 → 回報給其父層（深度 1 協調器）。 +2. 深度 1 協調器收到回報、整合結果、完成 → 回報給主代理。 +3. 主代理收到回報並傳遞給使用者。 -每一層只會看到其直接子層的 announce。 +每一層只會看到來自其直接子層的回報。 -**操作指引：** 啟動子工作一次，然後等待完成 -事件，而不是圍繞 `sessions_list`、 -`sessions_history`、`/subagents list` 或 `exec` sleep 指令建立輪詢迴圈。 -`sessions_list` 與 `/subagents list` 會讓子 session 關係 -聚焦在即時工作上：即時子項會保持附加，已結束子項會在短暫的近期視窗中保持 -可見，而過期的僅儲存子連結會在其新鮮度視窗後被 -忽略。這可防止舊的 `spawnedBy` / -`parentSessionKey` 中繼資料在 -重新啟動後重新喚回幽靈子項。如果子項完成事件在你已送出 -最終答案後才抵達，正確的後續動作是精確的靜默 token +**操作指南：**啟動子層工作一次，然後等待完成事件， +而不是圍繞 `sessions_list`、`sessions_history`、`/subagents list` +或 `exec` 睡眠指令建立輪詢迴圈。 +`sessions_list` 和 `/subagents list` 會讓子工作階段關係 +聚焦於即時工作：即時子工作階段會保持附加，已結束的子工作階段會在短暫的近期視窗中保持可見， +而過時的僅儲存子連結會在其新鮮度視窗後被忽略。這能避免舊的 `spawnedBy` / +`parentSessionKey` 中繼資料在重新啟動後復活幽靈子層。 +如果子層完成事件在你已送出最終答案後才抵達，正確的後續回應是完全靜默權杖 `NO_REPLY` / `no_reply`。 -### 依深度區分的工具政策 +### 依深度的工具政策 -- 角色與控制範圍會在生成時寫入 session 中繼資料。這可避免扁平或還原的 session 鍵意外重新取得協調器權限。 -- **深度 1（協調器，當 `maxSpawnDepth >= 2`）：** 取得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子項。其他 session/系統工具仍會被拒絕。 -- **深度 1（葉節點，當 `maxSpawnDepth == 1`）：** 沒有 session 工具（目前的預設行為）。 -- **深度 2（葉節點工作者）：** 沒有 session 工具，`sessions_spawn` 在深度 2 一律會被拒絕。無法再生成更多子項。 +- 角色與控制範圍會在產生時寫入工作階段中繼資料。這可避免扁平或已還原的工作階段鍵意外重新取得協調器權限。 +- **深度 1（協調器，當 `maxSpawnDepth >= 2` 時）：**取得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，因此可以管理其子層。其他工作階段/系統工具仍會被拒絕。 +- **深度 1（葉節點，當 `maxSpawnDepth == 1` 時）：**沒有工作階段工具（目前預設行為）。 +- **深度 2（葉節點工作代理）：**沒有工作階段工具，`sessions_spawn` 在深度 2 一律被拒絕。不能再產生更多子層。 -### 每個 agent 的生成限制 +### 單一代理產生限制 -每個 agent session（任何深度）一次最多可以有 `maxChildrenPerAgent` -個作用中子項（預設 `5`）。這可防止單一協調器造成失控扇出。 +每個代理工作階段（任何深度）同一時間最多可有 `maxChildrenPerAgent` +（預設 `5`）個作用中子層。這可避免單一協調器造成失控的扇出。 -### 級聯停止 +### 串聯停止 停止深度 1 協調器會自動停止其所有深度 2 -子項： +子層： -- 主要聊天中的 `/stop` 會停止所有深度 1 agent，並級聯到其深度 2 子項。 -- `/subagents kill ` 會停止特定子代理，並級聯到其子項。 -- `/subagents kill all` 會停止請求者的所有子代理並級聯。 +- 主聊天中的 `/stop` 會停止所有深度 1 代理，並串聯停止其深度 2 子層。 +- `/subagents kill ` 會停止特定子代理，並串聯停止其子層。 +- `/subagents kill all` 會停止請求端的所有子代理並串聯停止。 ## 驗證 -子代理驗證是依 **agent ID** 解析，而不是依 session 類型： +子代理驗證會依**代理 ID**解析，而不是依工作階段類型： -- 子代理 session 鍵為 `agent::subagent:`。 -- 驗證儲存會從該 agent 的 `agentDir` 載入。 -- 主要 agent 的驗證設定檔會合併為**備援**；發生衝突時，agent 設定檔會覆寫主要設定檔。 +- 子代理工作階段鍵為 `agent::subagent:`。 +- 驗證儲存會從該代理的 `agentDir` 載入。 +- 主代理的驗證設定檔會作為**備援**合併；發生衝突時，代理設定檔會覆寫主設定檔。 -合併是加成式的，因此主要設定檔一律可作為 -備援使用。尚不支援每個 agent 完全隔離的驗證。 +合併是加成式的，因此主設定檔永遠可作為備援使用。 +尚未支援每個代理完全隔離的驗證。 -## Announce +## 回報 -子代理會透過 announce 步驟回報： +子代理會透過回報步驟回傳： -- announce 步驟在子代理 session 內執行（不是請求者 session）。 -- 如果子代理精確回覆 `ANNOUNCE_SKIP`，則不會張貼任何內容。 -- 如果最新的 assistant 文字是精確的靜默 token `NO_REPLY` / `no_reply`，即使先前存在可見進度，也會抑制 announce 輸出。 +- 回報步驟在子代理工作階段內執行（不是請求端工作階段）。 +- 如果子代理精確回覆 `ANNOUNCE_SKIP`，就不會發布任何內容。 +- 如果最新的助理文字是完全靜默權杖 `NO_REPLY` / `no_reply`，即使先前已有可見進度，回報輸出也會被抑制。 -交付取決於請求者深度： +傳遞方式取決於請求端深度： -- 頂層請求者 session 會使用帶有外部交付的後續 `agent` 呼叫（`deliver=true`）。 -- 巢狀請求者 subagent session 會收到內部後續注入（`deliver=false`），讓協調器能在 session 內彙整子項結果。 -- 如果巢狀請求者 subagent session 已不存在，OpenClaw 會在可用時退回到該 session 的請求者。 +- 最上層請求端工作階段會使用帶外部傳遞的後續 `agent` 呼叫（`deliver=true`）。 +- 巢狀請求端子代理工作階段會收到內部後續注入（`deliver=false`），讓協調器能在工作階段內整合子層結果。 +- 如果巢狀請求端子代理工作階段已不存在，OpenClaw 會在可用時退回使用該工作階段的請求端。 -對於頂層請求者 session，完成模式的直接交付會先 -解析任何已綁定的對話/執行緒路由與 hook 覆寫，然後從 -請求者 session 儲存的路由填入缺少的頻道目標欄位。 -這可確保完成結果留在正確的聊天/主題中，即使完成 -來源只識別了頻道。 +對最上層請求端工作階段而言，完成模式的直接傳遞會先 +解析任何已繫結的對話/執行緒路由和 hook 覆寫，然後從 +請求端工作階段儲存的路由補齊缺少的頻道目標欄位。 +這能讓完成訊息停留在正確的聊天/主題中，即使完成來源 +只識別頻道也是如此。 -建立巢狀完成發現項目時，子項完成彙總會限定在目前請求者執行範圍內， -防止過去執行的過期子項 -輸出洩漏到目前 announce。當頻道配接器可用時，announce 回覆會保留 -執行緒/主題路由。 +建立巢狀完成發現時，子層完成彙總會限定於目前請求端執行， +避免過時的先前執行子層輸出洩漏到目前回報中。當頻道配接器 +提供執行緒/主題路由時，回報回覆會保留該路由。 -### Announce 內容脈絡 +### 回報內容 -Announce 內容脈絡會正規化為穩定的內部事件區塊： +回報內容會正規化為穩定的內部事件區塊： -| 欄位 | 來源 | -| -------------- | ------------------------------------------------------------------------------------------------------------- | -| 來源 | `subagent` 或 `cron` | -| Session ID | 子 session 鍵/ID | -| 類型 | Announce 類型 + 任務標籤 | -| 狀態 | 從執行階段結果衍生（`success`、`error`、`timeout` 或 `unknown`）— **不是** 從模型文字推斷 | -| 結果內容 | 最新可見的 assistant 文字，否則為已清理的最新 tool/toolResult 文字 | -| 後續動作 | 描述何時回覆與何時保持靜默的指示 | +| 欄位 | 來源 | +| ---------- | ------------------------------------------------------------------------------------------------------------- | +| 來源 | `subagent` 或 `cron` | +| 工作階段 ID | 子工作階段鍵/ID | +| 類型 | 回報類型 + 工作標籤 | +| 狀態 | 從執行階段結果衍生（`success`、`error`、`timeout` 或 `unknown`），**不是**從模型文字推斷 | +| 結果內容 | 最新可見助理文字，否則為經清理的最新工具/toolResult 文字 | +| 後續 | 描述何時回覆與何時保持靜默的指示 | 終端失敗執行會回報失敗狀態，而不重播擷取到的 -回覆文字。逾時時，如果子項只完成了工具呼叫，announce -可以將該歷史壓縮成簡短的部分進度摘要，而不是 +回覆文字。逾時時，如果子層只完成工具呼叫，回報 +可以將該歷史折疊成簡短的部分進度摘要，而不是 重播原始工具輸出。 -### 統計列 +### 統計行 -Announce 承載內容會在結尾包含統計列（即使被包裝時也是如此）： +回報承載會在結尾包含統計行（即使被包裝也一樣）： - 執行階段（例如 `runtime 5m12s`）。 -- Token 使用量（輸入/輸出/總計）。 -- 設定模型定價時的估計成本（`models.providers.*.models[].cost`）。 -- `sessionKey`、`sessionId` 與逐字稿路徑，讓主要 agent 能透過 `sessions_history` 擷取歷史，或檢查磁碟上的檔案。 +- 權杖使用量（輸入/輸出/總計）。 +- 當已設定模型定價時的估算成本（`models.providers.*.models[].cost`）。 +- `sessionKey`、`sessionId` 和記錄路徑，讓主代理可透過 `sessions_history` 擷取歷史，或檢查磁碟上的檔案。 -內部中繼資料僅用於協調；面向使用者的回覆 -應以一般 assistant 語氣重寫。 +內部中繼資料僅供協調使用；面向使用者的回覆 +應以一般助理語氣重寫。 ### 為何偏好 `sessions_history` `sessions_history` 是較安全的協調路徑： -- Assistant 回憶會先正規化：移除 thinking 標籤；移除 `` / `` 腳手架；移除純文字工具呼叫 XML 承載區塊（``、``、``、``），包括從未乾淨關閉的截斷承載；移除降級的工具呼叫/結果腳手架與歷史脈絡標記；移除洩漏的模型控制 token（`<|assistant|>`、其他 ASCII `<|...|>`、全形 `<｜...｜>`）；移除格式錯誤的 MiniMax 工具呼叫 XML。 -- 類似憑證/token 的文字會被遮蔽。 -- 長區塊可以被截斷。 -- 非常大的歷史可以丟棄較舊的列，或用 `[sessions_history omitted: message too large]` 取代過大的列。 -- 當你需要完整逐位元組一致的逐字稿時，原始磁碟逐字稿檢查是備援方式。 +- 助理回憶會先正規化：移除 thinking 標籤；移除 `` / `` 鷹架；移除純文字工具呼叫 XML 承載區塊（``、``、``、``），包含永遠未乾淨閉合的截斷承載；移除降級的工具呼叫/結果鷹架和歷史內容標記；移除洩漏的模型控制權杖（`<|assistant|>`、其他 ASCII `<|...|>`、全形 `<｜...｜>`）；移除格式錯誤的 MiniMax 工具呼叫 XML。 +- 憑證/類似權杖的文字會被遮蔽。 +- 長區塊可被截斷。 +- 非常大的歷史可捨棄較舊列，或用 `[sessions_history omitted: message too large]` 取代過大的列。 +- 當你需要完整逐位元組一致的記錄時，原始磁碟記錄檢查是備援方式。 ## 工具政策 -子代理會先使用與父層或目標 agent 相同的設定檔與工具政策 -管線。之後，OpenClaw 會套用子代理限制 -層。 +子代理會先使用與父代理或目標代理相同的設定檔和工具政策 +管線。之後，OpenClaw 會套用子代理限制層。 -在沒有具限制性的 `tools.profile` 時，子代理會取得**除了 -session 工具**與系統工具以外的**所有工具**： +若沒有具限制性的 `tools.profile`，子代理會取得**除了 +工作階段工具**和系統工具之外的所有工具： - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -`sessions_history` 在這裡也仍是有界且已清理的回憶視圖， -不是原始逐字稿傾印。 +`sessions_history` 在此仍是有界且經清理的回憶檢視，並 +不是原始記錄傾印。 當 `maxSpawnDepth >= 2` 時，深度 1 協調器子代理會額外 -收到 `sessions_spawn`、`subagents`、`sessions_list` 與 -`sessions_history`，以便管理其子項。 +收到 `sessions_spawn`、`subagents`、`sessions_list` 和 +`sessions_history`，因此可以管理其子層。 ### 透過設定覆寫 @@ -443,10 +466,10 @@ session 工具**與系統工具以外的**所有工具**： ``` `tools.subagents.tools.allow` 是最終的僅允許篩選器。它可以縮小 -已解析的工具集，但無法**加回**已被 `tools.profile` 移除的工具。 +已解析的工具集，但無法**加回**已由 `tools.profile` 移除的工具。 例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`， 但不包含 `browser` 工具。若要讓 coding-profile 子代理使用瀏覽器自動化， -請在設定檔階段加入 browser： +請在 profile 階段加入 browser： ```json5 { @@ -457,53 +480,55 @@ session 工具**與系統工具以外的**所有工具**： } ``` -當只有一個代理應取得瀏覽器自動化能力時，請使用每代理的 `agents.list[].tools.alsoAllow: ["browser"]`。 +當只有單一代理應取得瀏覽器自動化時，請使用每個代理的 `agents.list[].tools.alsoAllow: ["browser"]`。 ## 並行 -子代理使用專用的進程內佇列通道： +子代理使用專用的程序內佇列通道： - **通道名稱：** `subagent` -- **並行數：** `agents.defaults.subagents.maxConcurrent`（預設為 `8`） +- **並行數：** `agents.defaults.subagents.maxConcurrent`（預設 `8`） -## 活性與復原 +## 存活性與復原 -OpenClaw 不會將缺少 `endedAt` 視為子代理仍然存活的永久證明。 -早於過時執行時間窗的未結束執行，不再於 `/subagents list`、狀態摘要、 -後代完成閘控，以及每工作階段並行檢查中計為作用中/待處理。 +OpenClaw 不會把缺少 `endedAt` 視為子代理仍然存活的永久證明。 +早於過期執行時間窗且未結束的執行，會停止在 `/subagents list`、狀態摘要、 +子代完成門檻，以及每個工作階段的並行檢查中計為作用中/待處理。 -Gateway 重新啟動後，過時且未結束的已還原執行會被修剪，除非其子工作階段 -標記為 `abortedLastRun: true`。這些因重新啟動而中止的子工作階段仍可透過 -子代理孤立復原流程恢復；該流程會先傳送合成的恢復訊息，再清除中止標記。 +Gateway 重新啟動後，除非其子工作階段標記為 `abortedLastRun: true`， +否則過期且未結束的已還原執行會被剪除。這些因重新啟動而中止的子工作階段， +仍可透過子代理孤兒復原流程復原；該流程會先傳送合成的恢復訊息， +再清除中止標記。 -自動重新啟動復原會按每個子工作階段設限。若同一個子代理子項在快速重新卡住 -時間窗內反覆被接受進行孤立復原，OpenClaw 會在該工作階段上持久化復原墓碑， +自動重新啟動復原會以每個子工作階段為界限。如果同一個子代理子項在快速重卡住時間窗內 +反覆被接受進行孤兒復原，OpenClaw 會在該工作階段上保留復原墓碑， 並在後續重新啟動時停止自動恢復它。執行 `openclaw tasks maintenance --apply` -以協調任務記錄，或執行 `openclaw doctor --fix` 以清除墓碑工作階段上過時的 -中止復原旗標。 +以協調任務記錄，或執行 `openclaw doctor --fix` 以清除已設墓碑工作階段上的 +過期中止復原旗標。 -如果子代理生成因 Gateway `PAIRING_REQUIRED` / `scope-upgrade` 而失敗， -請先檢查 RPC 呼叫端，再編輯配對狀態。內部 `sessions_spawn` 協調應以 -`client.id: "gateway-client"` 搭配 `client.mode: "backend"`，透過直接 -loopback 共享 token/密碼驗證進行連線；該路徑不依賴 CLI 的已配對裝置範圍基準。 -遠端呼叫端、明確的 `deviceIdentity`、明確的裝置 token 路徑，以及瀏覽器/node -用戶端仍需一般裝置核准才能進行範圍升級。 +如果子代理產生失敗並出現 Gateway `PAIRING_REQUIRED` / +`scope-upgrade`，請先檢查 RPC 呼叫端，再編輯配對狀態。 +內部 `sessions_spawn` 協調應透過直接 loopback 共享權杖/密碼驗證， +以 `client.id: "gateway-client"` 和 `client.mode: "backend"` 連線； +該路徑不依賴 CLI 的已配對裝置範圍基準。遠端呼叫端、明確的 +`deviceIdentity`、明確的裝置權杖路徑，以及瀏覽器/node 用戶端， +仍需要一般裝置核准才能進行範圍升級。 ## 停止 -- 在請求者聊天中傳送 `/stop` 會中止請求者工作階段，並停止由其生成的任何作用中子代理執行，連鎖套用至巢狀子項。 -- `/subagents kill ` 會停止指定的子代理，並連鎖停止其子項。 +- 在請求者聊天中傳送 `/stop` 會中止請求者工作階段，並停止從中產生的任何作用中子代理執行，連鎖套用至巢狀子項。 +- `/subagents kill ` 會停止特定子代理，並連鎖停止其子項。 ## 限制 -- 子代理公告是**盡力而為**。如果 gateway 重新啟動，待處理的「公告回傳」工作會遺失。 -- 子代理仍共用相同的 gateway 行程資源；請將 `maxConcurrent` 視為安全閥。 -- `sessions_spawn` 一律為非阻塞：它會立即回傳 `{ status: "accepted", runId, childSessionKey }`。 -- 子代理內容脈絡只注入 `AGENTS.md` + `TOOLS.md`（沒有 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 +- 子代理公告是**盡力而為**。如果 gateway 重新啟動，待處理的「回報公告」工作會遺失。 +- 子代理仍共用相同的 gateway 程序資源；請將 `maxConcurrent` 視為安全閥。 +- `sessions_spawn` 一律為非阻塞：它會立即傳回 `{ status: "accepted", runId, childSessionKey }`。 +- 子代理內容只注入 `AGENTS.md` + `TOOLS.md`（沒有 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。 - 最大巢狀深度為 5（`maxSpawnDepth` 範圍：1–5）。大多數使用案例建議使用深度 2。 -- `maxChildrenPerAgent` 限制每個工作階段的作用中子項數量（預設 `5`，範圍 `1–20`）。 +- `maxChildrenPerAgent` 會限制每個工作階段的作用中子項數量（預設 `5`，範圍 `1–20`）。 ## 相關 diff --git a/docs/zh-TW/tools/thinking.md b/docs/zh-TW/tools/thinking.md index 22f908bad..232353904 100644 --- a/docs/zh-TW/tools/thinking.md +++ b/docs/zh-TW/tools/thinking.md @@ -1,140 +1,143 @@ --- read_when: - - 調整思考、快速模式或詳細指令的解析或預設值 -summary: 用於 /think、/fast、/verbose、/trace 與推理可見性的指令語法 + - 調整思考、快速模式或詳細指令的剖析或預設值 +summary: /think、/fast、/verbose、/trace 的指令語法與推理可見性 title: 思考層級 x-i18n: - generated_at: "2026-04-30T16:30:54Z" + generated_at: "2026-05-04T02:46:38Z" model: gpt-5.5 provider: openai - source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7 + source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f source_path: tools/thinking.md workflow: 16 --- -## 功能說明 +## 功能 - 任何傳入本文中的行內指令：`/t `、`/think:` 或 `/thinking `。 - 層級（別名）：`off | minimal | low | medium | high | xhigh | adaptive | max` - - minimal → “think” - - low → “think hard” - - medium → “think harder” - - high → “ultrathink”（最大預算） - - xhigh → “ultrathink+”（GPT-5.2+ 與 Codex 模型，加上 Anthropic Claude Opus 4.7 effort） - - adaptive → 提供者管理的自適應思考（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 動態思考） + - minimal →「think」 + - low →「think hard」 + - medium →「think harder」 + - high →「ultrathink」（最大預算） + - xhigh →「ultrathink+」（GPT-5.2+ 與 Codex 模型，加上 Anthropic Claude Opus 4.7 effort） + - adaptive → 由提供者管理的自適應思考（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 動態思考） - max → 提供者最大推理（Anthropic Claude Opus 4.7；Ollama 會將此對應到其最高原生 `think` effort） - - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 對應到 `xhigh`。 - - `highest` 對應到 `high`。 + - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 會對應到 `xhigh`。 + - `highest` 會對應到 `high`。 - 提供者注意事項： - - 思考選單與選擇器由提供者設定檔驅動。提供者 Plugin 會宣告所選模型的確切層級集合，包括二元 `on` 這類標籤。 - - `adaptive`、`xhigh` 和 `max` 只會針對支援它們的提供者/模型設定檔顯示。不支援層級的輸入指令會被拒絕，並回覆該模型的有效選項。 - - 既有儲存的不支援層級會依提供者設定檔排名重新對應。在非自適應模型上，`adaptive` 會回退到 `medium`，而 `xhigh` 和 `max` 會回退到所選模型支援的最大非 off 層級。 - - 未設定明確思考層級時，Anthropic Claude 4.6 模型預設為 `adaptive`。 - - Anthropic Claude Opus 4.7 不預設使用自適應思考。除非你明確設定思考層級，否則其 API effort 預設值仍由提供者擁有。 + - 思考選單與選擇器由提供者設定檔驅動。提供者 Plugin 會宣告所選模型的確切層級集合，包含二元 `on` 等標籤。 + - `adaptive`、`xhigh` 和 `max` 只會對支援它們的提供者/模型設定檔顯示。針對不支援層級的已輸入指令，會以該模型的有效選項拒絕。 + - 既有已儲存的不支援層級會依提供者設定檔排名重新對應。`adaptive` 在非自適應模型上會退回到 `medium`，而 `xhigh` 和 `max` 會退回到所選模型支援的最大非 off 層級。 + - Anthropic Claude 4.6 模型在未設定明確思考層級時，預設為 `adaptive`。 + - Anthropic Claude Opus 4.7 不會預設使用自適應思考。除非你明確設定思考層級，否則其 API effort 預設值仍由提供者擁有。 - Anthropic Claude Opus 4.7 會將 `/think xhigh` 對應到自適應思考加上 `output_config.effort: "xhigh"`，因為 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 設定。 - - Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到相同的提供者自有最大 effort 路徑。 - - DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，較低的非 off 層級則對應到 `high`。 + - Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到相同的提供者所屬最大 effort 路徑。 + - DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，而較低的非 off 層級會對應到 `high`。 - 具備思考能力的 Ollama 模型公開 `/think low|medium|high|max`；`max` 會對應到原生 `think: "high"`，因為 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字串。 - - OpenAI GPT 模型會透過模型特定的 Responses API effort 支援來對應 `/think`。只有目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用推理的 payload，而不是傳送不支援的值。 - - 自訂 OpenAI 相容目錄項目可以透過設定 `models.providers..models[].compat.supportedReasoningEfforts` 包含 `"xhigh"`，選擇加入 `/think xhigh`。這會使用相同的 compat 中繼資料來對應傳出的 OpenAI 推理 effort payload，因此選單、工作階段驗證、代理 CLI 和 `llm-task` 都會與傳輸行為一致。 - - 過時設定的 OpenRouter Hunter Alpha 參照會略過代理推理注入，因為該已退役路由可能透過推理欄位回傳最終答案文字。 - - Google Gemini 會將 `/think adaptive` 對應到 Gemini 的提供者自有動態思考。Gemini 3 請求會省略固定的 `thinkingLevel`，而 Gemini 2.5 請求會傳送 `thinkingBudget: -1`；固定層級仍會對應到該模型系列最接近的 Gemini `thinkingLevel` 或預算。 - - Anthropic 相容串流路徑上的 MiniMax（`minimax/*`）預設為 `thinking: { type: "disabled" }`，除非你在模型參數或請求參數中明確設定思考。這可避免 MiniMax 非原生 Anthropic 串流格式洩漏 `reasoning_content` delta。 + - OpenAI GPT 模型會透過模型專屬的 Responses API effort 支援來對應 `/think`。只有在目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用的推理酬載，而不是傳送不支援的值。 + - 自訂 OpenAI 相容型目錄項目可以透過將 `models.providers..models[].compat.supportedReasoningEfforts` 設為包含 `"xhigh"`，選擇啟用 `/think xhigh`。這會使用相同的相容性中繼資料來對應傳出的 OpenAI 推理 effort 酬載，因此選單、工作階段驗證、代理程式 CLI 與 `llm-task` 都會與傳輸行為一致。 + - 過期設定的 OpenRouter Hunter Alpha 參照會略過代理推理注入，因為該已淘汰路由可能透過推理欄位回傳最終答案文字。 + - Google Gemini 會將 `/think adaptive` 對應到 Gemini 的提供者所屬動態思考。Gemini 3 請求會省略固定的 `thinkingLevel`，而 Gemini 2.5 請求會傳送 `thinkingBudget: -1`；固定層級仍會對應到該模型系列最接近的 Gemini `thinkingLevel` 或預算。 + - Anthropic 相容串流路徑上的 MiniMax（`minimax/*`）預設為 `thinking: { type: "disabled" }`，除非你在模型參數或請求參數中明確設定思考。這可避免 MiniMax 非原生 Anthropic 串流格式洩漏 `reasoning_content` 增量。 - Z.AI（`zai/*`）只支援二元思考（`on`/`off`）。任何非 `off` 層級都會被視為 `on`（對應到 `low`）。 - - Moonshot（`moonshot/*`）會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 層級對應到 `thinking: { type: "enabled" }`。啟用思考時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值標準化為 `auto`。 + - Moonshot（`moonshot/*`）會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 層級對應到 `thinking: { type: "enabled" }`。啟用思考時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值正規化為 `auto`。 ## 解析順序 1. 訊息上的行內指令（只套用於該訊息）。 -2. 工作階段覆寫（透過傳送僅含指令的訊息設定）。 -3. 個別代理預設值（設定中的 `agents.list[].thinkingDefault`）。 +2. 工作階段覆寫（透過傳送只有指令的訊息設定）。 +3. 每個代理程式預設值（設定中的 `agents.list[].thinkingDefault`）。 4. 全域預設值（設定中的 `agents.defaults.thinkingDefault`）。 -5. 回退：有提供者宣告的預設值時使用它；否則具備推理能力的模型會解析為 `medium` 或該模型最接近且支援的非 `off` 層級，而非推理模型維持 `off`。 +5. 後援：有提供者宣告的預設值時使用該值；否則具備推理能力的模型會解析為 `medium` 或該模型最接近的受支援非 `off` 層級，而非推理模型維持 `off`。 ## 設定工作階段預設值 -- 傳送**只有**指令的訊息（允許空白），例如 `/think:medium` 或 `/t high`。 -- 這會固定用於目前工作階段（預設按傳送者區分）；可由 `/think:off` 或工作階段閒置重設清除。 -- 系統會傳送確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果層級無效（例如 `/thinking big`），指令會被拒絕並附上提示，工作階段狀態維持不變。 -- 傳送不帶引數的 `/think`（或 `/think:`）即可查看目前思考層級。 +- 傳送一則**只有**指令的訊息（允許空白），例如 `/think:medium` 或 `/t high`。 +- 該設定會在目前工作階段中持續有效（預設依傳送者區分）；可由 `/think:off` 或工作階段閒置重設清除。 +- 會傳送確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果層級無效（例如 `/thinking big`），指令會以提示拒絕，且工作階段狀態保持不變。 +- 傳送沒有引數的 `/think`（或 `/think:`）可查看目前思考層級。 -## 依代理套用 +## 依代理程式套用 -- **嵌入式 Pi**：解析後的層級會傳遞給處理程序內的 Pi 代理執行階段。 +- **嵌入式 Pi**：已解析的層級會傳遞給處理程序內 Pi 代理程式執行階段。 ## 快速模式（/fast） - 層級：`on|off`。 -- 僅含指令的訊息會切換工作階段快速模式覆寫，並回覆 `Fast mode enabled.` / `Fast mode disabled.`。 -- 傳送不帶模式的 `/fast`（或 `/fast status`）即可查看目前有效的快速模式狀態。 +- 只有指令的訊息會切換工作階段快速模式覆寫，並回覆 `Fast mode enabled.` / `Fast mode disabled.`。 +- 傳送沒有模式的 `/fast`（或 `/fast status`）可查看目前有效的快速模式狀態。 - OpenClaw 會依此順序解析快速模式： - 1. 行內/僅指令 `/fast on|off` + 1. 行內/只有指令的 `/fast on|off` 2. 工作階段覆寫 - 3. 個別代理預設值（`agents.list[].fastModeDefault`） - 4. 個別模型設定：`agents.defaults.models["/"].params.fastMode` - 5. 回退：`off` -- 對於 `openai/*`，快速模式會在支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI 優先處理。 -- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 會在兩種驗證路徑間保留一個共用的 `/fast` 切換。 + 3. 每個代理程式預設值（`agents.list[].fastModeDefault`） + 4. 每個模型設定：`agents.defaults.models["/"].params.fastMode` + 5. 後援：`off` +- 對於 `openai/*`，快速模式會透過在受支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI 優先處理。 +- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 會在兩種驗證路徑間維持一個共用的 `/fast` 切換。 - 對於直接公開的 `anthropic/*` 請求，包括傳送到 `api.anthropic.com` 的 OAuth 驗證流量，快速模式會對應到 Anthropic 服務層級：`/fast on` 設定 `service_tier=auto`，`/fast off` 設定 `service_tier=standard_only`。 -- 對於 Anthropic 相容路徑上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）會將 `MiniMax-M2.7` 重寫為 `MiniMax-M2.7-highspeed`。 -- 同時設定時，明確的 Anthropic `serviceTier` / `service_tier` 模型參數會覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理 base URL 略過 Anthropic 服務層級注入。 -- `/status` 只有在啟用快速模式時才會顯示 `Fast`。 +- 對於 Anthropic 相容路徑上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。 +- 明確的 Anthropic `serviceTier` / `service_tier` 模型參數會在兩者都設定時覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理基底 URL 略過 Anthropic 服務層級注入。 +- `/status` 只會在啟用快速模式時顯示 `Fast`。 ## 詳細指令（/verbose 或 /v） - 層級：`on`（最小）| `full` | `off`（預設）。 -- 僅含指令的訊息會切換工作階段詳細模式，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。 -- `/verbose off` 會儲存明確的工作階段覆寫；可在 Sessions UI 中選擇 `inherit` 來清除。 -- 行內指令只影響該訊息；否則會套用工作階段/全域預設值。 -- 傳送不帶引數的 `/verbose`（或 `/verbose:`）即可查看目前詳細層級。 -- 啟用詳細模式時，會發出結構化工具結果的代理（Pi、其他 JSON 代理）會將每次工具呼叫作為自己的僅中繼資料訊息傳回，可用時前綴為 ` : `（路徑/指令）。這些工具摘要會在每個工具開始時立即傳送（分開的氣泡），而不是作為串流 delta。 -- 工具失敗摘要在一般模式中仍會顯示，但原始錯誤詳細資料後綴會隱藏，除非詳細模式為 `on` 或 `full`。 -- 當詳細模式為 `full` 時，工具輸出也會在完成後轉送（分開的氣泡，截斷到安全長度）。如果你在執行期間切換 `/verbose on|full|off`，後續工具氣泡會遵循新設定。 +- 只有指令的訊息會切換工作階段詳細模式，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。 +- `/verbose off` 會儲存明確的工作階段覆寫；可在工作階段 UI 中選擇 `inherit` 清除。 +- 行內指令只影響該訊息；否則套用工作階段/全域預設值。 +- 傳送沒有引數的 `/verbose`（或 `/verbose:`）可查看目前詳細層級。 +- 開啟詳細模式時，會發出結構化工具結果的代理程式（Pi、其他 JSON 代理程式）會將每個工具呼叫作為自己的僅中繼資料訊息傳回；可用時前置 ` : `。這些工具摘要會在每個工具開始時立即傳送（分開的訊息泡泡），而不是作為串流增量。 +- 工具失敗摘要在一般模式中仍會顯示，但原始錯誤詳細後綴會隱藏，除非詳細模式為 `on` 或 `full`。 +- 當詳細模式為 `full` 時，工具輸出也會在完成後轉送（分開的訊息泡泡，截斷至安全長度）。如果你在執行進行中切換 `/verbose on|full|off`，後續工具訊息泡泡會遵循新設定。 +- `agents.defaults.toolProgressDetail` 控制 `/verbose` 工具摘要與進度草稿工具行的形狀。使用 `"explain"`（預設）可取得精簡的人類標籤，例如 `🛠️ Exec: checking JS syntax`；若你也想附加原始命令/詳細資訊以便偵錯，請使用 `"raw"`。每個代理程式的 `agents.list[].toolProgressDetail` 會覆寫預設值。 + - `explain`：`🛠️ Exec: check JS syntax for /tmp/app.js` + - `raw`：`🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` ## Plugin 追蹤指令（/trace） - 層級：`on` | `off`（預設）。 -- 僅含指令的訊息會切換工作階段 Plugin 追蹤輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。 -- 行內指令只影響該訊息；否則會套用工作階段/全域預設值。 -- 傳送不帶引數的 `/trace`（或 `/trace:`）即可查看目前追蹤層級。 -- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 擁有的追蹤/偵錯行，例如 Active Memory 偵錯摘要。 -- 追蹤行可能出現在 `/status` 中，也可能在一般助理回覆後作為後續診斷訊息出現。 +- 只有指令的訊息會切換工作階段 Plugin 追蹤輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。 +- 行內指令只影響該訊息；否則套用工作階段/全域預設值。 +- 傳送沒有引數的 `/trace`（或 `/trace:`）可查看目前追蹤層級。 +- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 所屬的追蹤/偵錯行，例如 Active Memory 偵錯摘要。 +- 追蹤行可以出現在 `/status` 中，也可以作為一般助理回覆後的後續診斷訊息。 ## 推理可見性（/reasoning） - 層級：`on|off|stream`。 -- 僅含指令的訊息會切換是否在回覆中顯示思考區塊。 -- 啟用時，推理會作為**獨立訊息**傳送，並以前綴 `Reasoning:` 開頭。 -- `stream`（僅 Telegram）：在產生回覆時將推理串流到 Telegram 草稿氣泡，然後傳送不含推理的最終答案。 +- 只有指令的訊息會切換是否在回覆中顯示思考區塊。 +- 啟用時，推理會作為**分開的訊息**傳送，前置 `Reasoning:`。 +- `stream`（僅 Telegram）：在產生回覆時將推理串流到 Telegram 草稿訊息泡泡，然後傳送不含推理的最終答案。 - 別名：`/reason`。 -- 傳送不帶引數的 `/reasoning`（或 `/reasoning:`）即可查看目前推理層級。 -- 解析順序：行內指令，接著工作階段覆寫，接著個別代理預設值（`agents.list[].reasoningDefault`），最後回退（`off`）。 +- 傳送沒有引數的 `/reasoning`（或 `/reasoning:`）可查看目前推理層級。 +- 解析順序：行內指令，接著是工作階段覆寫，再來是每個代理程式預設值（`agents.list[].reasoningDefault`），最後是後援（`off`）。 -格式不正確的本機模型推理標籤會保守處理。封閉的 `...` 區塊會在一般回覆中維持隱藏，已可見文字後未封閉的推理也會隱藏。如果回覆完整包在單一未封閉開啟標籤中，且原本會作為空文字傳送，OpenClaw 會移除格式不正確的開啟標籤並傳送剩餘文字。 +格式錯誤的本機模型推理標籤會保守處理。封閉的 `...` 區塊會在一般回覆中保持隱藏，且已可見文字之後未封閉的推理也會隱藏。如果回覆完全包在單一未封閉的開頭標籤中，且否則會傳送為空文字，OpenClaw 會移除格式錯誤的開頭標籤並傳送剩餘文字。 -## 相關內容 +## 相關 -- Elevated mode 文件位於 [Elevated mode](/zh-TW/tools/elevated)。 +- 提權模式文件位於[提權模式](/zh-TW/tools/elevated)。 -## Heartbeats +## Heartbeat -- Heartbeat 探測本文是設定的 Heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的行內指令會照常套用（但請避免從 Heartbeat 變更工作階段預設值）。 -- Heartbeat 傳遞預設只傳送最終 payload。若也要傳送獨立的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或個別代理的 `agents.list[].heartbeat.includeReasoning: true`。 +- Heartbeat 探測本文是設定的 Heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的行內指令會照常套用（但避免從 Heartbeat 變更工作階段預設值）。 +- Heartbeat 傳送預設只傳送最終酬載。若也要傳送分開的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或每個代理程式的 `agents.list[].heartbeat.includeReasoning: true`。 ## 網頁聊天 UI - 網頁聊天思考選擇器會在頁面載入時，從傳入工作階段儲存區/設定映照工作階段已儲存的層級。 -- 選擇另一個層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，也不是一次性的 `thinkingOnce` 覆寫。 -- 第一個選項一律是 `Default ()`，其中解析後的預設值來自作用中工作階段模型的提供者思考設定檔，加上 `/status` 與 `session_status` 使用的相同回退邏輯。 -- 選擇器使用 Gateway 工作階段列/預設值回傳的 `thinkingLevels`，並將 `thinkingOptions` 保留為舊版標籤清單。瀏覽器 UI 不會保留自己的提供者 regex 清單；模型特定層級集合由 Plugin 擁有。 -- `/think:` 仍可運作並更新相同的已儲存工作階段層級，因此聊天指令與選擇器會保持同步。 +- 選擇另一個層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，且不是一次性的 `thinkingOnce` 覆寫。 +- 第一個選項一律為 `Default ()`，其中已解析的預設值來自作用中工作階段模型的提供者思考設定檔，加上 `/status` 和 `session_status` 使用的相同後援邏輯。 +- 選擇器使用 Gateway 工作階段資料列/預設值回傳的 `thinkingLevels`，並保留 `thinkingOptions` 作為舊版標籤清單。瀏覽器 UI 不會保留自己的提供者 regex 清單；Plugin 擁有模型專屬層級集合。 +- `/think:` 仍可運作，並會更新相同儲存的工作階段層級，因此聊天指令與選擇器會保持同步。 ## 提供者設定檔 -- 提供者 Plugin 可以公開 `resolveThinkingProfile(ctx)`，用來定義模型支援的層級與預設值。 -- 代理 Claude 模型的提供者 Plugin 應重用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 與代理目錄保持一致。 -- 每個設定檔層級都有儲存的標準 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），也可以包含顯示用的 `label`。二元提供者使用 `{ id: "low", label: "on" }`。 -- 需要驗證明確思考覆寫的工具 Plugin 應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 搭配 `api.runtime.agent.normalizeThinkingLevel(...)`；它們不應維護自己的提供者/模型層級清單。 -- 可存取已設定自訂模型中繼資料的工具 Plugin，可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 選擇加入項目反映在 Plugin 端驗證中。 -- 已發布的舊版 hook（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）會保留作為相容性配接器，但新的自訂層級集合應使用 `resolveThinkingProfile`。 -- Gateway 列/defaults 會公開 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證所用相同的設定檔 ID 與標籤。 +- 供應商 Plugin 可以公開 `resolveThinkingProfile(ctx)`，以定義模型支援的層級與預設值。 +- 代理 Claude 模型的供應商 Plugin 應重用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 與代理目錄保持一致。 +- 每個設定檔層級都有儲存的正規 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），也可以包含顯示用 `label`。二元供應商使用 `{ id: "low", label: "on" }`。 +- 需要驗證明確思考覆寫的工具 Plugin，應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它們不應維護自己的供應商/模型層級清單。 +- 能存取已設定自訂模型中繼資料的工具 Plugin，可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 的選擇加入反映在 Plugin 端驗證中。 +- 已發布的舊版掛鉤（`supportsXHighThinking`、`isBinaryThinking` 與 `resolveDefaultThinkingLevel`）會保留作為相容性配接器，但新的自訂層級集應使用 `resolveThinkingProfile`。 +- Gateway 列/預設值公開 `thinkingLevels`、`thinkingOptions` 與 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證相同的設定檔 ID 與標籤。 diff --git a/docs/zh-TW/tools/web-fetch.md b/docs/zh-TW/tools/web-fetch.md index 718616c00..d9a6b3663 100644 --- a/docs/zh-TW/tools/web-fetch.md +++ b/docs/zh-TW/tools/web-fetch.md @@ -1,29 +1,29 @@ --- read_when: - - 你想擷取 URL 並提取可讀內容 - - 你需要設定 web_fetch 或其 Firecrawl 備援 - - 你想了解 web_fetch 的限制與快取 + - 你想取得一個 URL 並擷取可讀內容 + - 你需要設定 web_fetch 或其 Firecrawl 後備方案 + - 你想了解 web_fetch 的限制和快取 sidebarTitle: Web Fetch -summary: web_fetch 工具 -- 具備可讀內容擷取的 HTTP 擷取 +summary: web_fetch 工具 -- 具備可讀內容擷取功能的 HTTP 擷取 title: 網頁擷取 x-i18n: - generated_at: "2026-05-02T21:06:48Z" + generated_at: "2026-05-04T02:46:49Z" model: gpt-5.5 provider: openai - source_hash: f455da77c20049f0ed0246fa53e9f49d3cf2004e65bd64a0bf871861c6e93229 + source_hash: c8c3efbf4a640b2fd69cc9532dcb06a873a6830a2e8a85ab7510ab38207c8670 source_path: tools/web-fetch.md workflow: 16 --- `web_fetch` 工具會執行一般 HTTP GET，並擷取可讀內容 -（HTML 轉為 markdown 或文字）。它**不會**執行 JavaScript。 +（將 HTML 轉為 Markdown 或文字）。它**不會**執行 JavaScript。 -對於高度依賴 JS 的網站或受登入保護的頁面，請改用 +對於大量依賴 JS 的網站或受登入保護的頁面，請改用 [網頁瀏覽器](/zh-TW/tools/browser)。 ## 快速開始 -`web_fetch` **預設啟用** -- 不需要設定。代理可以立即呼叫它： +`web_fetch` **預設已啟用** -- 不需要設定。代理可以立即呼叫它： ```javascript await web_fetch({ url: "https://example.com/article" }); @@ -32,15 +32,15 @@ await web_fetch({ url: "https://example.com/article" }); ## 工具參數 -要擷取的 URL。僅支援 `http(s)`。 +要擷取的 URL。僅限 `http(s)`。 -主要內容擷取後的輸出格式。 +主內容擷取後的輸出格式。 -將輸出截斷至這個字元數。 +將輸出截斷為此字元數。 ## 運作方式 @@ -48,17 +48,18 @@ await web_fetch({ url: "https://example.com/article" }); 使用類似 Chrome 的 User-Agent 和 `Accept-Language` - 標頭傳送 HTTP GET。封鎖私人／內部主機名稱，並重新檢查重新導向。 + 標頭傳送 HTTP GET。封鎖私有/內部主機名稱，並重新檢查重新導向。 - - 在 HTML 回應上執行 Readability（主要內容擷取）。 + + 在 HTML 回應上執行 Readability（主內容擷取）。 - - 如果 Readability 失敗且已設定 Firecrawl，會透過 - Firecrawl API 以規避機器人限制模式重試。 + + 如果 Readability 失敗且已設定 Firecrawl，則透過 + Firecrawl API 以規避機器人偵測模式重試。 - 結果會快取 15 分鐘（可設定），以減少對同一 URL 的重複擷取。 + 結果會快取 15 分鐘（可設定），以減少對相同 URL 的重複 + 擷取。 @@ -77,6 +78,7 @@ await web_fetch({ url: "https://example.com/article" }); timeoutSeconds: 30, cacheTtlMinutes: 15, maxRedirects: 3, + useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS readability: true, // use Readability extraction userAgent: "Mozilla/5.0 ...", // override User-Agent ssrfPolicy: { @@ -89,10 +91,10 @@ await web_fetch({ url: "https://example.com/article" }); } ``` -## Firecrawl 備援 +## Firecrawl 後援 -如果 Readability 擷取失敗，`web_fetch` 可以退回使用 -[Firecrawl](/zh-TW/tools/firecrawl)，以規避機器人限制並取得更好的擷取結果： +如果 Readability 擷取失敗，`web_fetch` 可以後援到 +[Firecrawl](/zh-TW/tools/firecrawl)，用於規避機器人偵測並提供更好的擷取： ```json5 { @@ -126,37 +128,57 @@ await web_fetch({ url: "https://example.com/article" }); 舊版 `tools.web.fetch.firecrawl.*` 設定會由 `openclaw doctor --fix` 自動遷移。 - 如果 Firecrawl 已啟用，但其 SecretRef 無法解析，且沒有 - `FIRECRAWL_API_KEY` 環境變數備援，Gateway 啟動會快速失敗。 + 如果 Firecrawl 已啟用，且其 SecretRef 未解析且沒有 + `FIRECRAWL_API_KEY` 環境後援，Gateway 啟動會快速失敗。 - Firecrawl `baseUrl` 覆寫受到嚴格限制：託管流量使用 - `https://api.firecrawl.dev`；自託管覆寫必須指向私人或 - 內部端點，而 `http://` 只會被這類私人目標接受。 + Firecrawl `baseUrl` 覆寫受到限制：託管流量使用 + `https://api.firecrawl.dev`；自架覆寫必須指向私有或 + 內部端點，且 `http://` 只接受用於這些私有目標。 目前的執行階段行為： -- `tools.web.fetch.provider` 會明確選取擷取備援提供者。 -- 如果省略 `provider`，OpenClaw 會從可用憑證中自動偵測第一個就緒的 web-fetch - 提供者。非沙盒化的 `web_fetch` 可以使用已安裝、宣告 `contracts.webFetchProviders` 並在 - 執行階段註冊相符提供者的 plugins。目前內建提供者是 Firecrawl。 -- 沙盒化的 `web_fetch` 呼叫仍限制為只能使用內建提供者。 -- 如果停用 Readability，`web_fetch` 會直接跳到所選的 - 提供者備援。如果沒有可用提供者，則會封閉式失敗。 +- `tools.web.fetch.provider` 會明確選擇擷取後援提供者。 +- 如果省略 `provider`，OpenClaw 會從可用憑證中自動偵測第一個就緒的網頁擷取 + 提供者。非沙盒化的 `web_fetch` 可以使用已安裝且宣告 + `contracts.webFetchProviders`，並在執行階段註冊相符提供者的 plugins。 + 目前內建提供者是 Firecrawl。 +- 沙盒化的 `web_fetch` 呼叫仍限制為內建提供者。 +- 如果 Readability 已停用，`web_fetch` 會直接跳到所選的 + 提供者後援。如果沒有可用提供者，則會封閉失敗。 + +## 受信任的環境代理 + +如果你的部署需要讓 `web_fetch` 透過受信任的出站 +HTTP(S) 代理，請設定 `tools.web.fetch.useTrustedEnvProxy: true`。 + +在此模式下，OpenClaw 仍會在傳送請求前套用基於主機名稱的 SSRF 檢查， +但會讓代理解析 DNS，而不是執行本機 DNS +釘選。只有在代理由操作者控制，並且會在 DNS 解析後強制執行 +出站政策時，才啟用此選項。 + + + 如果未設定 HTTP(S) 代理環境變數，或目標主機被 + `NO_PROXY` 排除，`web_fetch` 會回退到使用本機 DNS + 釘選的一般嚴格路徑。 + ## 限制與安全性 -- `maxChars` 會被限制在 `tools.web.fetch.maxCharsCap` -- 回應主體會在解析前限制為 `maxResponseBytes`；過大的 - 回應會被截斷並附上警告 -- 私人／內部主機名稱會被封鎖 +- `maxChars` 會限制在 `tools.web.fetch.maxCharsCap` +- 回應本文在解析前會限制為 `maxResponseBytes`；過大的 + 回應會被截斷並附帶警告 +- 私有/內部主機名稱會被封鎖 - `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` 和 - `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是針對受信任假 IP 代理堆疊的狹義選擇加入； - 除非你的代理擁有這些合成範圍並執行自己的目的地政策，否則請保留未設定 + `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是針對受信任假 IP 代理堆疊的狹義選用項； + 除非你的代理擁有這些合成範圍並強制執行自己的目的地政策， + 否則請不要設定 - 重新導向會被檢查，並受 `maxRedirects` 限制 -- `web_fetch` 是盡力而為 -- 有些網站需要使用[網頁瀏覽器](/zh-TW/tools/browser) +- `useTrustedEnvProxy` 是明確的選用項，且只應為 + 操作者控制、仍會在 DNS 解析後強制執行出站政策的代理啟用 +- `web_fetch` 是盡力而為 -- 有些網站需要[網頁瀏覽器](/zh-TW/tools/browser) ## 工具設定檔 @@ -174,5 +196,5 @@ await web_fetch({ url: "https://example.com/article" }); ## 相關 - [網頁搜尋](/zh-TW/tools/web) -- 使用多個提供者搜尋網頁 -- [網頁瀏覽器](/zh-TW/tools/browser) -- 用於高度依賴 JS 網站的完整瀏覽器自動化 -- [Firecrawl](/zh-TW/tools/firecrawl) -- Firecrawl 搜尋與爬取工具 +- [網頁瀏覽器](/zh-TW/tools/browser) -- 適用於大量依賴 JS 網站的完整瀏覽器自動化 +- [Firecrawl](/zh-TW/tools/firecrawl) -- Firecrawl 搜尋與擷取工具 diff --git a/docs/zh-TW/web/control-ui.md b/docs/zh-TW/web/control-ui.md index a0a904459..b9e426a16 100644 --- a/docs/zh-TW/web/control-ui.md +++ b/docs/zh-TW/web/control-ui.md @@ -3,13 +3,13 @@ read_when: - 您想要從瀏覽器操作 Gateway - 你想要無需 SSH 通道即可存取 Tailnet sidebarTitle: Control UI -summary: 以瀏覽器為基礎的 Gateway 控制 UI（聊天、節點、設定） -title: 控制介面 +summary: Gateway 的瀏覽器式控制介面（聊天、節點、設定） +title: 控制使用者介面 x-i18n: - generated_at: "2026-05-03T02:46:31Z" + generated_at: "2026-05-04T02:47:04Z" model: gpt-5.5 provider: openai - source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c + source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e source_path: web/control-ui.md workflow: 16 --- @@ -17,7 +17,7 @@ x-i18n: Control UI 是由 Gateway 提供服務的小型 **Vite + Lit** 單頁應用程式： - 預設：`http://:18789/` -- 選用前綴：設定 `gateway.controlUi.basePath`（例如 `/openclaw`） +- 選用前置路徑：設定 `gateway.controlUi.basePath`（例如 `/openclaw`） 它會在同一個連接埠上**直接與 Gateway WebSocket** 通訊。 @@ -29,210 +29,211 @@ Control UI 是由 Gateway 提供服務的小型 **Vite + Lit** 單頁應用程 如果頁面載入失敗，請先啟動 Gateway：`openclaw gateway`。 -驗證會在 WebSocket 握手期間透過以下方式提供： +驗證會在 WebSocket 交握期間透過下列方式提供： - `connect.params.auth.token` - `connect.params.auth.password` -- 當 `gateway.auth.allowTailscale: true` 時的 Tailscale Serve 身分標頭 -- 當 `gateway.auth.mode: "trusted-proxy"` 時的受信任 Proxy 身分標頭 +- 當 `gateway.auth.allowTailscale: true` 時使用 Tailscale Serve 身分標頭 +- 當 `gateway.auth.mode: "trusted-proxy"` 時使用信任 Proxy 身分標頭 -儀表板設定面板會為目前瀏覽器分頁工作階段與選取的 Gateway URL 保留 token；密碼不會被持久保存。上手流程通常會在首次連線時產生 Gateway token，用於共用祕密驗證，但當 `gateway.auth.mode` 是 `"password"` 時，也可以使用密碼驗證。 +儀表板設定面板會為目前的瀏覽器分頁工作階段和所選 Gateway URL 保留 Token；密碼不會被持久化。首次連線時，導覽流程通常會為共用密鑰驗證產生 Gateway Token，但當 `gateway.auth.mode` 為 `"password"` 時，也可以使用密碼驗證。 -## 裝置配對（第一次連線） +## 裝置配對（首次連線） -當你從新的瀏覽器或裝置連線到 Control UI 時，Gateway 通常會要求**一次性配對核准**。這是一項安全措施，用來防止未授權存取。 +當你從新的瀏覽器或裝置連線到 Control UI 時，Gateway 通常會要求**一次性配對核准**。這是防止未授權存取的安全措施。 -**你會看到：**「disconnected (1008): pairing required」 +**你會看到的內容：**「disconnected (1008): pairing required」 - + ```bash openclaw devices list ``` - + ```bash openclaw devices approve ``` -如果瀏覽器以變更後的驗證詳細資料（角色/範圍/公開金鑰）重試配對，先前待處理的要求會被取代，並建立新的 `requestId`。核准前請重新執行 `openclaw devices list`。 +如果瀏覽器以變更後的驗證詳細資料（角色/範圍/公開金鑰）重試配對，前一個待處理請求會被取代，並建立新的 `requestId`。核准前請重新執行 `openclaw devices list`。 -如果瀏覽器已經配對，而你將它從讀取存取變更為寫入/管理員存取，這會被視為核准升級，而不是靜默重新連線。OpenClaw 會保留舊核准有效、阻擋範圍更廣的重新連線，並要求你明確核准新的範圍集合。 +如果瀏覽器已經配對，而你將它從讀取存取權變更為寫入/管理員存取權，這會被視為核准升級，而不是靜默重新連線。OpenClaw 會保留舊核准有效、阻擋更廣泛的重新連線，並要求你明確核准新的範圍集合。 -核准後，系統會記住該裝置；除非你使用 `openclaw devices revoke --device --role ` 撤銷，否則不需要重新核准。請參閱 [裝置 CLI](/zh-TW/cli/devices) 了解 token 輪替與撤銷。 +核准後，裝置會被記住，除非你使用 `openclaw devices revoke --device --role ` 撤銷它，否則不需要重新核准。請參閱[裝置 CLI](/zh-TW/cli/devices) 了解 Token 輪替與撤銷。 - 直接的 local loopback 瀏覽器連線（`127.0.0.1` / `localhost`）會自動核准。 -- 當 `gateway.auth.allowTailscale: true`、Tailscale 身分通過驗證，且瀏覽器提供其裝置身分時，Tailscale Serve 可以為 Control UI 操作者工作階段略過配對往返。 -- 直接的 Tailnet 繫結、LAN 瀏覽器連線，以及沒有裝置身分的瀏覽器設定檔仍需要明確核准。 -- 每個瀏覽器設定檔都會產生唯一裝置 ID，因此切換瀏覽器或清除瀏覽器資料都會需要重新配對。 +- 當 `gateway.auth.allowTailscale: true`、Tailscale 身分驗證通過，且瀏覽器出示其裝置身分時，Tailscale Serve 可以略過 Control UI 操作者工作階段的配對往返流程。 +- 直接 Tailnet 綁定、LAN 瀏覽器連線，以及沒有裝置身分的瀏覽器設定檔仍需要明確核准。 +- 每個瀏覽器設定檔都會產生唯一的裝置 ID，因此切換瀏覽器或清除瀏覽器資料會需要重新配對。 ## 個人身分（瀏覽器本機） -Control UI 支援每個瀏覽器各自的個人身分（顯示名稱與頭像），會附加到傳出的訊息上，用於共用工作階段中的歸屬標示。它存在於瀏覽器儲存空間中，範圍限定於目前瀏覽器設定檔，不會同步到其他裝置，也不會在伺服器端持久保存，除了你實際送出的訊息上一般的逐字稿作者中繼資料。清除網站資料或切換瀏覽器會將它重設為空白。 +Control UI 支援每個瀏覽器各自的個人身分（顯示名稱與頭像），會附加到傳出的訊息，以便在共用工作階段中標示歸屬。它存在於瀏覽器儲存空間中，作用範圍限於目前的瀏覽器設定檔，不會同步到其他裝置，也不會在伺服器端持久化，除了你實際送出的訊息上一般的逐字稿作者中繼資料。清除網站資料或切換瀏覽器會將它重設為空白。 -相同的瀏覽器本機模式也適用於助理頭像覆寫。上傳的助理頭像只會在本機瀏覽器上覆蓋由 Gateway 解析出的身分，而且絕不會透過 `config.patch` 往返傳送。共用的 `ui.assistant.avatar` 設定欄位仍可供非 UI 用戶端直接寫入該欄位（例如腳本化 Gateway 或自訂儀表板）。 +同樣的瀏覽器本機模式也適用於助理頭像覆寫。上傳的助理頭像只會在本機瀏覽器中覆蓋 Gateway 解析出的身分，且絕不會透過 `config.patch` 往返傳送。共用的 `ui.assistant.avatar` 設定欄位仍可供非 UI 用戶端直接寫入該欄位（例如指令碼化 Gateway 或自訂儀表板）。 ## 執行階段設定端點 -Control UI 會從 `/__openclaw/control-ui-config.json` 擷取其執行階段設定。該端點與其餘 HTTP 介面一樣受相同 Gateway 驗證保護：未驗證的瀏覽器無法擷取它，而成功擷取需要已有效的 Gateway token/密碼、Tailscale Serve 身分，或受信任 Proxy 身分。 +Control UI 會從 `/__openclaw/control-ui-config.json` 擷取其執行階段設定。該端點受到與其餘 HTTP 介面相同的 Gateway 驗證保護：未驗證的瀏覽器無法擷取它，成功擷取需要已有效的 Gateway Token/密碼、Tailscale Serve 身分，或信任 Proxy 身分。 ## 語言支援 -Control UI 可在首次載入時依據你的瀏覽器語言環境進行本地化。若要稍後覆寫，請開啟 **概覽 -> Gateway 存取 -> 語言**。語言環境選擇器位於 Gateway 存取卡片中，不在外觀底下。 +Control UI 可以在首次載入時根據你的瀏覽器語言環境自動本地化。若要稍後覆寫它，請開啟 **Overview -> Gateway Access -> Language**。語言環境選擇器位於 Gateway Access 卡片中，而不是 Appearance 底下。 - 支援的語言環境：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa` - 非英文翻譯會在瀏覽器中延遲載入。 -- 選取的語言環境會儲存在瀏覽器儲存空間，並在日後造訪時重複使用。 -- 缺漏的翻譯鍵會退回英文。 +- 所選語言環境會儲存在瀏覽器儲存空間中，並在未來造訪時重複使用。 +- 缺少的翻譯鍵會退回英文。 -文件翻譯會針對相同的非英文語言環境集合產生，但文件網站內建的 Mintlify 語言選擇器僅限於 Mintlify 接受的語言環境代碼。泰文（`th`）與波斯文（`fa`）文件仍會在發布 repo 中產生；在 Mintlify 支援這些代碼之前，它們可能不會出現在該選擇器中。 +文件翻譯會為同一組非英文語言環境產生，但文件網站內建的 Mintlify 語言選擇器受限於 Mintlify 接受的語言環境代碼。泰文（`th`）和波斯文（`fa`）文件仍會在發布 Repo 中產生；在 Mintlify 支援這些代碼之前，它們可能不會出現在該選擇器中。 ## 外觀主題 -外觀面板保留內建的 Claw、Knot 與 Dash 主題，另加一個瀏覽器本機的 tweakcn 匯入插槽。若要匯入主題，請開啟 [tweakcn 主題](https://tweakcn.com/themes)，選擇或建立主題，點擊 **分享**，然後將複製的主題連結貼到外觀中。匯入器也接受 `https://tweakcn.com/r/themes/` 登錄 URL、像 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 這樣的編輯器 URL、相對 `/themes/` 路徑、原始主題 ID，以及像 `amethyst-haze` 這樣的預設主題名稱。 +Appearance 面板保留內建的 Claw、Knot 和 Dash 主題，外加一個瀏覽器本機的 tweakcn 匯入槽。若要匯入主題，請開啟 [tweakcn 主題](https://tweakcn.com/themes)、選擇或建立主題、按一下 **Share**，然後將複製的主題連結貼到 Appearance 中。匯入器也接受 `https://tweakcn.com/r/themes/` Registry URL、像 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 這類編輯器 URL、相對 `/themes/` 路徑、原始主題 ID，以及像 `amethyst-haze` 這類預設主題名稱。 -匯入的主題只會儲存在目前瀏覽器設定檔中。它們不會寫入 Gateway 設定，也不會跨裝置同步。替換匯入的主題會更新單一本機插槽；若清除它，且匯入的主題當時被選取，作用中主題會切回 Claw。 +匯入的主題只會儲存在目前瀏覽器設定檔中。它們不會寫入 Gateway 設定，也不會跨裝置同步。取代匯入的主題會更新唯一的本機槽；如果已選取匯入主題，清除它會將作用中主題切回 Claw。 -## 它可以做什麼（目前） +## 它目前能做什麼 - + - 透過 Gateway WS 與模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。 - - 透過瀏覽器即時工作階段進行語音交談。OpenAI 使用直接 WebRTC，Google Live 透過 WebSocket 使用受限的一次性瀏覽器 token，而僅後端的即時語音 Plugin 則使用 Gateway 轉送傳輸。轉送會將提供者憑證保留在 Gateway 上，同時瀏覽器透過 `talk.realtime.relay*` RPC 串流麥克風 PCM，並將 `openclaw_agent_consult` 工具呼叫透過 `chat.send` 傳回給設定中較大的 OpenClaw 模型。 - - 在聊天中串流工具呼叫 + 即時工具輸出卡片（代理事件）。 + - 透過瀏覽器即時工作階段通話。OpenAI 使用直接 WebRTC，Google Live 透過 WebSocket 使用受限的一次性瀏覽器 Token，而僅後端的即時語音 Plugin 使用 Gateway Relay 傳輸。Relay 會將供應商憑證保留在 Gateway 上，同時瀏覽器透過 `talk.realtime.relay*` RPC 串流麥克風 PCM，並透過 `chat.send` 將 `openclaw_agent_consult` 工具呼叫送回更大的已設定 OpenClaw 模型。 + - 在 Chat 中串流工具呼叫與即時工具輸出卡片（代理事件）。 - - - 頻道：內建加上隨附/外部 Plugin 頻道狀態、QR 登入，以及每個頻道設定（`channels.status`、`web.login.*`、`config.patch`）。 - - 執行個體：在線清單 + 重新整理（`system-presence`）。 - - 工作階段：清單 + 每個工作階段的模型/思考/快速/詳細/追蹤/推理覆寫（`sessions.list`、`sessions.patch`）。 - - 夢境：dreaming 狀態、啟用/停用切換，以及 Dream Diary 閱讀器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 + + - Channel：內建 Channel 加上隨附/外部 Plugin Channel 狀態、QR 登入，以及每個 Channel 的設定（`channels.status`、`web.login.*`、`config.patch`）。 + - 執行個體：存在清單與重新整理（`system-presence`）。 + - 工作階段：清單與每個工作階段的模型/思考/快速/詳細/追蹤/推理覆寫（`sessions.list`、`sessions.patch`）。 + - Dreams：Dreaming 狀態、啟用/停用切換，以及 Dream Diary 閱讀器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 - - - Cron 作業：列出/新增/編輯/執行/啟用/停用 + 執行歷史（`cron.*`）。 - - Skills：狀態、啟用/停用、安裝、API key 更新（`skills.*`）。 - - 節點：清單 + 能力（`node.list`）。 - - Exec 核准：編輯 Gateway 或節點 allowlist + `exec host=gateway/node` 的詢問政策（`exec.approvals.*`）。 + + - Cron 工作：列出/新增/編輯/執行/啟用/停用，加上執行歷程（`cron.*`）。 + - Skills：狀態、啟用/停用、安裝、API 金鑰更新（`skills.*`）。 + - Node：清單與能力（`node.list`）。 + - Exec 核准：編輯 Gateway 或 Node 允許清單，以及 `exec host=gateway/node` 的詢問政策（`exec.approvals.*`）。 - + - 檢視/編輯 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 - - 套用 + 以驗證重新啟動（`config.apply`），並喚醒最後一個作用中工作階段。 - - 寫入包含 base-hash 防護，以防止覆蓋並行編輯。 - - 寫入（`config.set`/`config.apply`/`config.patch`）會對已提交設定酬載中的 refs 預先檢查作用中的 SecretRef 解析；未解析的作用中已提交 refs 會在寫入前遭到拒絕。 - - 結構描述 + 表單算繪（`config.schema` / `config.schema.lookup`，包含欄位 `title` / `description`、相符的 UI 提示、直接子項摘要、巢狀物件/萬用字元/陣列/組合節點上的文件中繼資料，以及可用時的 Plugin + 頻道結構描述）；只有當快照具備安全的原始往返時，才可使用原始 JSON 編輯器。 - - 如果快照無法安全地以原始文字往返，Control UI 會強制使用表單模式，並針對該快照停用原始模式。 - - 原始 JSON 編輯器的「重設為已儲存」會保留原始撰寫的形狀（格式、註解、`$include` 版面），而不是重新算繪扁平化快照，因此當快照可以安全往返時，外部編輯在重設後仍會保留。 - - 結構化 SecretRef 物件值會在表單文字輸入中以唯讀呈現，以防止意外的物件轉字串損毀。 + - 套用並透過驗證重新啟動（`config.apply`），並喚醒上一個作用中工作階段。 + - 寫入包含基底雜湊保護，以防止覆寫並行編輯。 + - 寫入（`config.set`/`config.apply`/`config.patch`）會對提交設定 Payload 中的 Ref 預先檢查作用中的 SecretRef 解析；未解析的作用中已提交 Ref 會在寫入前被拒絕。 + - Schema 與表單渲染（`config.schema` / `config.schema.lookup`，包含欄位 `title` / `description`、相符的 UI 提示、直接子項摘要、巢狀物件/萬用字元/陣列/組合節點上的文件中繼資料，以及可用時的 Plugin 與 Channel Schema）；只有當快照具有安全的原始往返能力時，才可使用 Raw JSON 編輯器。 + - 如果快照無法安全地以原始文字往返，Control UI 會強制使用 Form 模式，並針對該快照停用 Raw 模式。 + - Raw JSON 編輯器的「Reset to saved」會保留原始撰寫的形狀（格式、註解、`$include` 版面），而不是重新渲染扁平化快照，因此當快照可以安全往返時，外部編輯會在重設後保留下來。 + - 結構化 SecretRef 物件值會在表單文字輸入中以唯讀方式渲染，以防止意外的物件轉字串損毀。 - - - 偵錯：狀態/健康狀態/模型快照 + 事件日誌 + 手動 RPC 呼叫（`status`、`health`、`models.list`）。 - - 日誌：即時追蹤 Gateway 檔案日誌，支援篩選/匯出（`logs.tail`）。 - - 更新：執行套件/git 更新 + 重新啟動（`update.run`）並產生重新啟動報告，然後在重新連線後輪詢 `update.status`，以確認正在執行的 Gateway 版本。 + + - Debug：狀態/健康狀態/模型快照、事件記錄，以及手動 RPC 呼叫（`status`、`health`、`models.list`）。 + - Log：即時追蹤 Gateway 檔案 Log，並可篩選/匯出（`logs.tail`）。 + - 更新：執行套件/git 更新並重新啟動（`update.run`），附帶重新啟動報告，然後在重新連線後輪詢 `update.status` 以驗證正在執行的 Gateway 版本。 - - - 對於隔離作業，遞送預設為宣布摘要。如果你想要僅供內部執行，可以切換為無。 - - 選取宣布時會顯示頻道/目標欄位。 - - Webhook 模式使用 `delivery.mode = "webhook"`，且 `delivery.to` 設為有效的 HTTP(S) Webhook URL。 - - 對於主工作階段作業，可使用 Webhook 與無遞送模式。 - - 進階編輯控制項包含執行後刪除、清除代理覆寫、cron 精確/錯開選項、代理模型/思考覆寫，以及最佳努力遞送切換。 + + - 對於隔離工作，交付預設為宣布摘要。如果你想要僅內部執行，可以切換為無。 + - 選取宣布時，會顯示 Channel/目標欄位。 + - Webhook 模式使用 `delivery.mode = "webhook"`，並將 `delivery.to` 設為有效的 HTTP(S) Webhook URL。 + - 對於主要工作階段工作，可使用 Webhook 和無交付模式。 + - 進階編輯控制包含執行後刪除、清除代理覆寫、Cron 精確/錯開選項、代理模型/思考覆寫，以及盡力交付切換。 - 表單驗證會以欄位層級錯誤內嵌顯示；無效值會停用儲存按鈕，直到修正為止。 - - 設定 `cron.webhookToken` 以傳送專用 bearer token；若省略，Webhook 會在沒有驗證標頭的情況下傳送。 - - 已棄用的後援：儲存的舊版作業若有 `notify: true`，在遷移前仍可使用 `cron.webhook`。 + - 設定 `cron.webhookToken` 可傳送專用 Bearer Token；如果省略，Webhook 會在沒有驗證標頭的情況下傳送。 + - 已淘汰的後援：儲存的舊版工作若有 `notify: true`，在遷移前仍可使用 `cron.webhook`。 -## 聊天行為 +## Chat 行為 - - - `chat.send` 是**非阻塞**的：它會立即以 `{ runId, status: "started" }` 確認，並透過 `chat` 事件串流回應。 - - 聊天上傳接受圖片以及非影片檔案。圖片會保留原生圖片路徑；其他檔案會儲存為受管理媒體，並在歷程中顯示為附件連結。 - - 使用相同 `idempotencyKey` 重新傳送時，執行中會回傳 `{ status: "in_flight" }`，完成後會回傳 `{ status: "ok" }`。 - - `chat.history` 回應基於 UI 安全而有大小限制。當對話記錄項目過大時，Gateway 可能會截斷長文字欄位、省略龐大的中繼資料區塊，並以預留位置取代過大的訊息（`[chat.history omitted: message too large]`）。 - - 助理/產生的圖片會保存為受管理媒體參照，並透過經驗證的 Gateway 媒體 URL 回傳，因此重新載入不會依賴原始 base64 圖片酬載仍保留在聊天歷程回應中。 - - `chat.history` 也會從可見的助理文字中移除僅供顯示的行內指令標籤（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、純文字工具呼叫 XML 酬載（包含 `...`、`...`、`...`、`...`，以及被截斷的工具呼叫區塊）、洩漏的 ASCII/全形模型控制詞元，並省略可見全文只有精確靜默詞元 `NO_REPLY` / `no_reply` 的助理項目。 - - 在作用中的傳送期間以及最後的歷程重新整理期間，如果 `chat.history` 短暫回傳較舊的快照，聊天檢視會保持本機樂觀使用者/助理訊息可見；一旦 Gateway 歷程追上，標準對話記錄就會取代這些本機訊息。 - - `chat.inject` 會將助理備註附加到工作階段對話記錄，並廣播 `chat` 事件以進行僅限 UI 的更新（不會執行代理，也不會傳送到頻道）。 - - 聊天標頭的模型與思考選擇器會立即透過 `sessions.patch` 修補作用中的工作階段；它們是持久的工作階段覆寫，而不是僅限單輪的傳送選項。 - - 在 Control UI 中輸入 `/new` 會建立並切換到與新增聊天相同的全新儀表板工作階段。輸入 `/reset` 則會保留 Gateway 對目前工作階段的明確原地重設。 - - 聊天模型選擇器會請求 Gateway 設定的模型檢視。如果存在 `agents.defaults.models`，該允許清單會驅動選擇器。否則，選擇器會顯示明確的 `models.providers.*.models` 項目，以及具備可用驗證的提供者。完整型錄仍可透過除錯用 `models.list` RPC 搭配 `view: "all"` 取得。 - - 當新的 Gateway 工作階段使用量報告顯示高上下文壓力時，聊天撰寫區會顯示上下文提示，並在建議的 Compaction 等級顯示一個緊縮按鈕，用來執行一般工作階段 Compaction 路徑。過期的詞元快照會被隱藏，直到 Gateway 再次回報新的使用量。 + + - `chat.send` 是**非阻塞**的：它會立即以 `{ runId, status: "started" }` 確認，回應則透過 `chat` 事件串流傳送。 + - 聊天上傳接受圖片和非影片檔案。圖片會保留原生圖片路徑；其他檔案會儲存為受管理媒體，並在歷史記錄中顯示為附件連結。 + - 使用相同的 `idempotencyKey` 重新傳送時，執行中會回傳 `{ status: "in_flight" }`，完成後會回傳 `{ status: "ok" }`。 + - `chat.history` 回應會為了 UI 安全限制大小。當逐字稿項目過大時，Gateway 可能會截斷長文字欄位、省略大型中繼資料區塊，並以預留位置取代過大的訊息（`[chat.history omitted: message too large]`）。 + - 助理/產生的圖片會保存為受管理媒體參照，並透過已驗證的 Gateway 媒體 URL 回傳，因此重新載入不依賴原始 base64 圖片負載留在聊天歷史記錄回應中。 + - `chat.history` 也會從可見的助理文字中移除僅供顯示的行內指令標籤（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、純文字工具呼叫 XML 負載（包括 `...`、`...`、`...`、`...` 和截斷的工具呼叫區塊），以及洩漏的 ASCII/全形模型控制權杖，並省略整段可見文字只有精確靜默權杖 `NO_REPLY` / `no_reply` 的助理項目。 + - 在作用中的傳送期間和最終歷史記錄重新整理時，如果 `chat.history` 短暫回傳較舊的快照，聊天檢視會讓本機樂觀使用者/助理訊息保持可見；一旦 Gateway 歷史記錄追上，規範逐字稿就會取代這些本機訊息。 + - 即時 `chat` 事件是傳送狀態，而 `chat.history` 會從耐久工作階段逐字稿重建。工具最終事件之後，Control UI 會重新載入歷史記錄，且只合併一小段樂觀尾端；逐字稿邊界記錄於 [WebChat](/zh-TW/web/webchat)。 + - `chat.inject` 會將助理備註附加到工作階段逐字稿，並廣播 `chat` 事件供僅限 UI 的更新使用（沒有代理程式執行，也沒有通道傳送）。 + - 聊天標頭的模型和思考選擇器會透過 `sessions.patch` 立即修補作用中的工作階段；它們是持久的工作階段覆寫，不是僅限單回合的傳送選項。 + - 在 Control UI 中輸入 `/new` 會建立並切換到與 New Chat 相同的全新儀表板工作階段。輸入 `/reset` 會保留 Gateway 對目前工作階段的明確就地重設。 + - 聊天模型選擇器會請求 Gateway 已設定的模型檢視。如果存在 `agents.defaults.models`，該允許清單會驅動選擇器。否則選擇器會顯示明確的 `models.providers.*.models` 項目，以及具有可用驗證的提供者。完整型錄仍可透過偵錯用 `models.list` RPC 搭配 `view: "all"` 取得。 + - 當新的 Gateway 工作階段用量報告顯示高上下文壓力時，聊天撰寫區會顯示上下文通知；在建議的 Compaction 層級，會顯示一個緊湊按鈕來執行一般工作階段 Compaction 路徑。過期的權杖快照會隱藏，直到 Gateway 再次回報新的用量。 - 通話模式使用已註冊的即時語音提供者。設定 OpenAI 時使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey`，或設定 Google 時使用 `talk.provider: "google"` 加上 `talk.providers.google.apiKey`；語音通話即時提供者設定仍可重用為後援。瀏覽器絕不會收到標準提供者 API key。OpenAI 會收到用於 WebRTC 的短暫 Realtime 用戶端密鑰。Google Live 會收到用於瀏覽器 WebSocket 工作階段的一次性受限 Live API 驗證權杖，其指示與工具宣告會由 Gateway 鎖定在權杖中。僅公開後端即時橋接的提供者會透過 Gateway 中繼傳輸執行，因此憑證與廠商 socket 會保留在伺服器端，而瀏覽器音訊則透過經驗證的 Gateway RPC 移動。Realtime 工作階段提示由 Gateway 組裝；`talk.realtime.session` 不接受呼叫者提供的指示覆寫。 + 通話模式使用已註冊的即時語音提供者。設定 OpenAI 時使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey`，或設定 Google 時使用 `talk.provider: "google"` 加上 `talk.providers.google.apiKey`；Voice Call 即時提供者設定仍可重複用作後援。瀏覽器永遠不會收到標準提供者 API 金鑰。OpenAI 會收到用於 WebRTC 的臨時 Realtime 用戶端密鑰。Google Live 會收到一次性、受限制的 Live API 驗證權杖，用於瀏覽器 WebSocket 工作階段，且指示與工具宣告會由 Gateway 鎖定在權杖中。僅公開後端即時橋接的提供者會透過 Gateway 轉送傳輸執行，因此憑證和供應商通訊端會留在伺服器端，而瀏覽器音訊則透過已驗證的 Gateway RPC 傳輸。Realtime 工作階段提示由 Gateway 組裝；`talk.realtime.session` 不接受呼叫端提供的指示覆寫。 - 在聊天撰寫器中，通話控制項是麥克風聽寫按鈕旁的波浪按鈕。通話開始時，撰寫器狀態列會顯示 `Connecting Talk...`，音訊連線後顯示 `Talk live`，或在即時工具呼叫透過 `chat.send` 諮詢已設定的較大模型時顯示 `Asking OpenClaw...`。 + 在聊天撰寫器中，通話控制項是麥克風聽寫按鈕旁的波浪按鈕。通話開始時，撰寫器狀態列會顯示 `Connecting Talk...`，音訊連線後顯示 `Talk live`，或在即時工具呼叫透過 `chat.send` 諮詢已設定的較大型模型時顯示 `Asking OpenClaw...`。 - 維護者即時煙霧測試：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 會驗證 OpenAI 瀏覽器 WebRTC SDP 交換、Google Live 受限權杖瀏覽器 WebSocket 設定，以及搭配假麥克風媒體的 Gateway 中繼瀏覽器介面卡。此命令只列印提供者狀態，且不記錄密鑰。 + 維護者即時煙霧測試：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 會驗證 OpenAI 瀏覽器 WebRTC SDP 交換、Google Live 受限制權杖瀏覽器 WebSocket 設定，以及使用假麥克風媒體的 Gateway 轉送瀏覽器介面卡。此命令只列印提供者狀態，不會記錄密鑰。 - - 按一下**停止**（呼叫 `chat.abort`）。 - - 執行作用中時，一般後續訊息會排入佇列。按一下佇列訊息上的**引導**，可將該後續訊息注入正在執行的輪次。 - - 輸入 `/stop`（或獨立的中止片語，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以帶外中止。 - - `chat.abort` 支援 `{ sessionKey }`（沒有 `runId`）來中止該工作階段的所有作用中執行。 + - 按一下 **Stop**（呼叫 `chat.abort`）。 + - 當執行處於作用中時，一般後續訊息會排入佇列。按一下佇列訊息上的 **Steer**，可將該後續訊息注入正在執行的回合。 + - 輸入 `/stop`（或獨立的中止片語，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可帶外中止。 + - `chat.abort` 支援 `{ sessionKey }`（沒有 `runId`），可中止該工作階段的所有作用中執行。 - - - 當執行被中止時，部分助理文字仍可顯示在 UI 中。 - - 當存在已緩衝輸出時，Gateway 會將已中止的部分助理文字保存到對話記錄歷程。 - - 保存的項目包含中止中繼資料，讓對話記錄取用者能區分中止部分內容與正常完成輸出。 + + - 當執行遭到中止時，部分助理文字仍可顯示在 UI 中。 + - 當存在已緩衝輸出時，Gateway 會將中止的部分助理文字保存到逐字稿歷史記錄中。 + - 保存的項目包含中止中繼資料，因此逐字稿消費者可以區分中止部分與一般完成輸出。 ## PWA 安裝與 Web Push -Control UI 隨附 `manifest.webmanifest` 和服務工作者，因此現代瀏覽器可以將它安裝為獨立 PWA。Web Push 讓 Gateway 即使在分頁或瀏覽器視窗未開啟時，也能以通知喚醒已安裝的 PWA。 +Control UI 隨附 `manifest.webmanifest` 和服務工作程式，因此現代瀏覽器可將其安裝為獨立 PWA。Web Push 可讓 Gateway 即使在分頁或瀏覽器視窗未開啟時，也能透過通知喚醒已安裝的 PWA。 -| 介面 | 作用 | +| 表面 | 功能 | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | PWA manifest。瀏覽器在可連線後會提供「安裝應用程式」。 | -| `ui/public/sw.js` | 處理 `push` 事件與通知點擊的服務工作者。 | -| `push/vapid-keys.json`（位於 OpenClaw 狀態目錄下） | 自動產生的 VAPID 金鑰組，用於簽署 Web Push 酬載。 | +| `ui/public/manifest.webmanifest` | PWA 資訊清單。瀏覽器可連到它後，就會提供「安裝應用程式」。 | +| `ui/public/sw.js` | 處理 `push` 事件和通知點擊的服務工作程式。 | +| `push/vapid-keys.json`（在 OpenClaw 狀態目錄下） | 自動產生的 VAPID 金鑰組，用於簽署 Web Push 負載。 | | `push/web-push-subscriptions.json` | 保存的瀏覽器訂閱端點。 | -當你想固定金鑰時（用於多主機部署、密鑰輪替或測試），可透過 Gateway 處理程序上的環境變數覆寫 VAPID 金鑰組： +當你想釘選金鑰（用於多主機部署、密鑰輪替或測試）時，可在 Gateway 行程上透過環境變數覆寫 VAPID 金鑰組： - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT`（預設為 `mailto:openclaw@localhost`） -Control UI 使用這些受範圍控管的 Gateway 方法來註冊與測試瀏覽器訂閱： +Control UI 使用這些受範圍限制的 Gateway 方法註冊和測試瀏覽器訂閱： -- `push.web.vapidPublicKey` — 擷取作用中的 VAPID 公開金鑰。 -- `push.web.subscribe` — 註冊 `endpoint` 加上 `keys.p256dh`/`keys.auth`。 +- `push.web.vapidPublicKey` — 擷取作用中的 VAPID 公鑰。 +- `push.web.subscribe` — 註冊 `endpoint` 以及 `keys.p256dh`/`keys.auth`。 - `push.web.unsubscribe` — 移除已註冊的端點。 -- `push.web.test` — 將測試通知傳送到呼叫者的訂閱。 +- `push.web.test` — 傳送測試通知到呼叫端的訂閱。 -Web Push 獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱[設定](/zh-TW/gateway/configuration)）以及既有的 `push.test` 方法，後兩者以原生行動配對為目標。 +Web Push 獨立於 iOS APNS 轉送路徑（轉送支援推播請見[設定](/zh-TW/gateway/configuration)）和現有的 `push.test` 方法，後兩者以原生行動配對為目標。 ## 託管嵌入 -助理訊息可以透過 `[embed ...]` 短代碼行內呈現託管的網頁內容。iframe 沙箱政策由 `gateway.controlUi.embedSandbox` 控制： +助理訊息可以使用 `[embed ...]` 短代碼行內轉譯託管網頁內容。iframe 沙箱政策由 `gateway.controlUi.embedSandbox` 控制： - - 停用託管嵌入內的腳本執行。 + + 停用託管嵌入內的指令碼執行。 - + 允許互動式嵌入，同時保持來源隔離；這是預設值，通常足以支援自包含的瀏覽器遊戲/小工具。 - - 在 `allow-scripts` 之外為刻意需要更高權限的同站文件加上 `allow-same-origin`。 + + 在 `allow-scripts` 之上新增 `allow-same-origin`，供刻意需要更高權限的同站文件使用。 @@ -249,14 +250,14 @@ Web Push 獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱[設定 ``` -只有在嵌入文件確實需要同源行為時才使用 `trusted`。對大多數代理產生的遊戲與互動畫布而言，`scripts` 是較安全的選擇。 +只有在嵌入文件確實需要同源行為時才使用 `trusted`。對於大多數代理程式產生的遊戲和互動式畫布，`scripts` 是較安全的選擇。 -絕對外部 `http(s)` 嵌入 URL 預設仍會被封鎖。如果你刻意想讓 `[embed url="https://..."]` 載入第三方頁面，請設定 `gateway.controlUi.allowExternalEmbedUrls: true`。 +絕對外部 `http(s)` 嵌入 URL 預設仍會被封鎖。如果你刻意希望 `[embed url="https://..."]` 載入第三方頁面，請設定 `gateway.controlUi.allowExternalEmbedUrls: true`。 ## 聊天訊息寬度 -群組化的聊天訊息使用易讀的預設最大寬度。寬螢幕部署可以透過設定 `gateway.controlUi.chatMessageMaxWidth` 覆寫它，而不必修補隨附的 CSS： +群組化聊天訊息使用易讀的預設最大寬度。寬螢幕部署可以透過設定 `gateway.controlUi.chatMessageMaxWidth` 覆寫，而不必修補隨附的 CSS： ```json5 { @@ -268,13 +269,13 @@ Web Push 獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱[設定 } ``` -此值會在抵達瀏覽器前進行驗證。支援的值包含純長度與百分比，例如 `960px` 或 `82%`，以及受限制的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 寬度運算式。 +該值會在送達瀏覽器前驗證。支援的值包括一般長度和百分比，例如 `960px` 或 `82%`，以及受限制的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 寬度運算式。 ## Tailnet 存取（建議） - - 將 Gateway 保持在迴路介面上，並讓 Tailscale Serve 透過 HTTPS 代理它： + + 將 Gateway 保持在 loopback，並讓 Tailscale Serve 透過 HTTPS 代理它： ```bash openclaw gateway --tailscale serve @@ -282,42 +283,42 @@ Web Push 獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱[設定 開啟： - - `https:///`（或你設定的 `gateway.controlUi.basePath`） + - `https:///`（或你已設定的 `gateway.controlUi.basePath`） - 預設情況下，當 `gateway.auth.allowTailscale` 為 `true` 時，Control UI/WebSocket Serve 請求可透過 Tailscale 身分標頭（`tailscale-user-login`）進行驗證。OpenClaw 會透過 `tailscale whois` 解析 `x-forwarded-for` 位址並比對該標頭來驗證身分，且只在請求透過 Tailscale 的 `x-forwarded-*` 標頭打到迴路介面時接受這些身分。對於具有瀏覽器裝置身分的 Control UI 操作者工作階段，此已驗證的 Serve 路徑也會略過裝置配對往返流程；無裝置的瀏覽器與節點角色連線仍會遵循一般裝置檢查。如果你想要求即使是 Serve 流量也必須使用明確的共用密鑰憑證，請設定 `gateway.auth.allowTailscale: false`。然後使用 `gateway.auth.mode: "token"` 或 `"password"`。 + 預設情況下，當 `gateway.auth.allowTailscale` 為 `true` 時，Control UI/WebSocket Serve 請求可透過 Tailscale 身分標頭（`tailscale-user-login`）驗證。OpenClaw 會使用 `tailscale whois` 解析 `x-forwarded-for` 位址並比對該標頭來驗證身分，而且只有在請求透過 loopback 並帶有 Tailscale 的 `x-forwarded-*` 標頭時才接受這些身分。對於具有瀏覽器裝置身分的 Control UI 操作者工作階段，這個已驗證的 Serve 路徑也會略過裝置配對往返；無裝置瀏覽器和節點角色連線仍會遵循一般裝置檢查。如果你想即使對 Serve 流量也要求明確的共享密鑰憑證，請設定 `gateway.auth.allowTailscale: false`。然後使用 `gateway.auth.mode: "token"` 或 `"password"`。 - 對於該非同步 Serve 身分路徑，相同用戶端 IP 與驗證範圍的失敗驗證嘗試會在寫入速率限制前序列化。因此，來自同一瀏覽器的並行錯誤重試可能會在第二個請求上顯示 `retry later`，而不是兩個單純不相符的請求平行競爭。 + 對於該非同步 Serve 身分路徑，同一用戶端 IP 和驗證範圍的驗證失敗嘗試，會在寫入速率限制前序列化。因此，同一瀏覽器的並行錯誤重試，可能會在第二個請求看到 `retry later`，而不是兩個一般不相符結果並行競爭。 - 無權杖 Serve 驗證假設 Gateway 主機可信任。如果不受信任的本機程式碼可能在該主機上執行，請要求權杖/密碼驗證。 + 無權杖 Serve 驗證假設 Gateway 主機是可信任的。如果不受信任的本機程式碼可能在該主機上執行，請要求權杖/密碼驗證。 - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` 然後開啟： - - `http://:18789/`（或你設定的 `gateway.controlUi.basePath`） + - `http://:18789/`（或你已設定的 `gateway.controlUi.basePath`） - 將相符的共用密鑰貼到 UI 設定中（以 `connect.params.auth.token` 或 `connect.params.auth.password` 傳送）。 + 將相符的共享密鑰貼到 UI 設定中（以 `connect.params.auth.token` 或 `connect.params.auth.password` 傳送）。 -## 不安全的 HTTP +## 不安全 HTTP -如果你透過一般 HTTP（`http://` 或 `http://`）開啟儀表板，瀏覽器會在**非安全情境**中執行並封鎖 WebCrypto。預設情況下，OpenClaw 會**封鎖**沒有裝置身分的 Control UI 連線。 +如果你透過純 HTTP（`http://` 或 `http://`）開啟儀表板，瀏覽器會在**非安全上下文**中執行並封鎖 WebCrypto。預設情況下，OpenClaw 會**封鎖**沒有裝置身分的 Control UI 連線。 已記錄的例外： -- 使用 `gateway.controlUi.allowInsecureAuth=true` 的僅限 localhost 不安全 HTTP 相容性 +- 僅限 localhost 的不安全 HTTP 相容性搭配 `gateway.controlUi.allowInsecureAuth=true` - 透過 `gateway.auth.mode: "trusted-proxy"` 成功進行的操作者 Control UI 驗證 -- 緊急破窗 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- 緊急破例用 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**建議修正方式：**使用 HTTPS（Tailscale Serve），或在本機開啟 UI： +**建議修正：**使用 HTTPS（Tailscale Serve）或在本機開啟 UI： - `https:///`（Serve） - `http://127.0.0.1:18789/`（在 Gateway 主機上） @@ -336,12 +337,12 @@ Web Push 獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱[設定 `allowInsecureAuth` 只是本機相容性切換： - - 它允許 localhost Control UI 工作階段在非安全 HTTP 情境下不需要裝置身分即可繼續。 + - 它允許 localhost 控制 UI 工作階段在非安全 HTTP 環境中不需裝置身分即可繼續。 - 它不會略過配對檢查。 - - 它不會放寬遠端（非 localhost）的裝置身分要求。 + - 它不會放寬遠端（非 localhost）裝置身分要求。 - + ```json5 { gateway: { @@ -353,42 +354,42 @@ Web Push 獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱[設定 ``` - `dangerouslyDisableDeviceAuth` 會停用 Control UI 裝置身分檢查，並且是嚴重的安全性降級。緊急使用後請盡快還原。 + `dangerouslyDisableDeviceAuth` 會停用控制 UI 裝置身分檢查，是嚴重的安全性降級。緊急使用後請盡快還原。 - - 成功的受信任 Proxy 驗證可以允許沒有裝置身分的 **operator** Control UI 工作階段進入。 - - 這**不會**延伸到 node-role Control UI 工作階段。 - - 同主機 loopback 反向 Proxy 仍然不符合受信任 Proxy 驗證；請參閱[受信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。 + - 成功的受信任 Proxy 驗證可以允許沒有裝置身分的**操作者**控制 UI 工作階段進入。 + - 這**不會**延伸到節點角色的控制 UI 工作階段。 + - 同主機 loopback 反向 Proxy 仍然不會滿足受信任 Proxy 驗證；請參閱[受信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。 請參閱 [Tailscale](/zh-TW/gateway/tailscale) 以取得 HTTPS 設定指引。 -## 內容安全政策 +## 內容安全性政策 -Control UI 隨附嚴格的 `img-src` 政策：只允許**同源**資產、`data:` URL，以及本機產生的 `blob:` URL。遠端 `http(s)` 和通訊協定相對圖片 URL 會被瀏覽器拒絕，且不會發出網路擷取。 +控制 UI 隨附嚴格的 `img-src` 政策：只允許**同源**資產、`data:` URL，以及本機產生的 `blob:` URL。瀏覽器會拒絕遠端 `http(s)` 和通訊協定相對圖片 URL，且不會發出網路擷取。 -這在實務上的意思是： +這在實務上的意義： -- 透過相對路徑提供的頭像和圖片（例如 `/avatars/`）仍會算繪，包括 UI 擷取並轉換成本機 `blob:` URL 的已驗證頭像路由。 -- 內嵌 `data:image/...` URL 仍會算繪（對通訊協定內酬載很有用）。 -- Control UI 建立的本機 `blob:` URL 仍會算繪。 -- 頻道中繼資料發出的遠端頭像 URL 會在 Control UI 的頭像輔助程式中被移除，並替換為內建標誌/徽章，因此遭入侵或惡意的頻道無法強迫操作員瀏覽器擷取任意遠端圖片。 +- 透過相對路徑提供的頭像和圖片（例如 `/avatars/`）仍會呈現，包括 UI 擷取並轉換成本機 `blob:` URL 的已驗證頭像路由。 +- 內嵌 `data:image/...` URL 仍會呈現（對通訊協定內承載資料很有用）。 +- 控制 UI 建立的本機 `blob:` URL 仍會呈現。 +- 通道中繼資料送出的遠端頭像 URL 會在控制 UI 的頭像輔助程式中被移除，並替換為內建標誌/徽章，因此遭入侵或惡意的通道無法強迫操作者瀏覽器擷取任意遠端圖片。 -你不需要變更任何設定即可取得此行為，這一律啟用且不可設定。 +你不需要變更任何內容即可取得此行為 — 它一律啟用且不可設定。 ## 頭像路由驗證 -設定 Gateway 驗證時，Control UI 頭像端點需要與 API 其餘部分相同的 Gateway token： +設定 Gateway 驗證後，控制 UI 頭像端點需要與其餘 API 相同的 Gateway 權杖： -- `GET /avatar/` 只會向已驗證呼叫者傳回頭像圖片。`GET /avatar/?meta=1` 會依相同規則傳回頭像中繼資料。 -- 對任一路由的未驗證請求都會被拒絕（與同層的 assistant-media 路由一致）。這會防止頭像路由在其他部分受保護的主機上洩漏代理身分。 -- Control UI 本身在擷取頭像時會以 bearer 標頭轉送 Gateway token，並使用已驗證的 blob URL，讓圖片仍能在儀表板中算繪。 +- `GET /avatar/` 只會將頭像圖片傳回給已驗證的呼叫端。`GET /avatar/?meta=1` 會在相同規則下傳回頭像中繼資料。 +- 對任一路由的未驗證請求都會遭拒（與相鄰的 assistant-media 路由一致）。這可防止頭像路由在原本受保護的主機上洩漏代理身分。 +- 控制 UI 在擷取頭像時會將 Gateway 權杖作為 bearer 標頭轉送，並使用已驗證的 blob URL，讓圖片仍可在儀表板中呈現。 -如果你停用 Gateway 驗證（不建議在共用主機上這麼做），頭像路由也會變成未驗證，與 Gateway 的其餘部分一致。 +如果你停用 Gateway 驗證（不建議在共用主機上使用），頭像路由也會與 Gateway 其餘部分一致，變成不需驗證。 ## 建置 UI @@ -398,7 +399,7 @@ Gateway 會從 `dist/control-ui` 提供靜態檔案。使用以下命令建置 pnpm ui:build ``` -選用的絕對基底路徑（當你想要固定資產 URL 時）： +選用的絕對基底（當你想要固定資產 URL 時）： ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build @@ -410,11 +411,11 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build pnpm ui:dev ``` -然後將 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。 +接著將 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。 ## 偵錯/測試：開發伺服器 + 遠端 Gateway -Control UI 是靜態檔案；WebSocket 目標可設定，且可以不同於 HTTP 來源。當你想在本機使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這很方便。 +控制 UI 是靜態檔案；WebSocket 目標可設定，且可以不同於 HTTP 來源。當你想在本機使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這很方便。 @@ -427,7 +428,7 @@ Control UI 是靜態檔案；WebSocket 目標可設定，且可以不同於 HTTP http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` - 選用的一次性驗證（如需要）： + 選用的一次性驗證（如有需要）： ```text http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= @@ -440,15 +441,15 @@ Control UI 是靜態檔案；WebSocket 目標可設定，且可以不同於 HTTP - `gatewayUrl` 會在載入後儲存在 localStorage，並從 URL 中移除。 - 如果你透過 `gatewayUrl` 傳入完整的 `ws://` 或 `wss://` 端點，請對 `gatewayUrl` 值進行 URL 編碼，讓瀏覽器正確解析查詢字串。 - - 只要可行，`token` 應透過 URL 片段（`#token=...`）傳遞。片段不會傳送到伺服器，因此可避免請求記錄和 Referer 洩漏。舊版 `?token=` 查詢參數仍會為了相容性匯入一次，但僅作為備援，並會在啟動後立即移除。 - - `password` 只會保存在記憶體中。 - - 設定 `gatewayUrl` 時，UI 不會回退到設定或環境憑證。請明確提供 `token`（或 `password`）。缺少明確憑證會造成錯誤。 - - 當 Gateway 位於 TLS 後方（Tailscale Serve、HTTPS Proxy 等）時，請使用 `wss://`。 - - `gatewayUrl` 只會在頂層視窗中接受（不接受嵌入式視窗），以防止 clickjacking。 - - 非 loopback Control UI 部署必須明確設定 `gateway.controlUi.allowedOrigins`（完整來源）。這包含遠端開發設定。 - - Gateway 啟動時可能會從有效的執行階段 bind 和連接埠植入本機來源，例如 `http://localhost:` 和 `http://127.0.0.1:`，但遠端瀏覽器來源仍需要明確項目。 - - 除了嚴格受控的本機測試外，請勿使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允許任何瀏覽器來源，而不是「符合我正在使用的任何主機」。 - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host-header 來源備援模式，但這是危險的安全性模式。 + - 只要可行，`token` 應透過 URL 片段（`#token=...`）傳遞。片段不會傳送到伺服器，可避免請求日誌和 Referer 洩漏。舊版 `?token=` 查詢參數仍會為了相容性匯入一次，但只作為後備，且會在啟動後立即移除。 + - `password` 只會保留在記憶體中。 + - 設定 `gatewayUrl` 時，UI 不會退回使用設定或環境憑證。請明確提供 `token`（或 `password`）。缺少明確憑證會造成錯誤。 + - 當 Gateway 位於 TLS 後方時（Tailscale Serve、HTTPS Proxy 等），請使用 `wss://`。 + - `gatewayUrl` 只會在最上層視窗中接受（不可嵌入），以防止點擊劫持。 + - 非 loopback 控制 UI 部署必須明確設定 `gateway.controlUi.allowedOrigins`（完整來源）。這包含遠端開發設定。 + - Gateway 啟動時可能會從有效的執行階段繫結和連接埠植入本機來源，例如 `http://localhost:` 和 `http://127.0.0.1:`，但遠端瀏覽器來源仍需要明確項目。 + - 除非是嚴格受控的本機測試，否則不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允許任何瀏覽器來源，而不是「符合我正在使用的任何主機」。 + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host 標頭來源後備模式，但這是危險的安全模式。 @@ -465,11 +466,11 @@ Control UI 是靜態檔案；WebSocket 目標可設定，且可以不同於 HTTP } ``` -遠端存取設定詳細資訊：[遠端存取](/zh-TW/gateway/remote)。 +遠端存取設定詳細資料：[遠端存取](/zh-TW/gateway/remote)。 ## 相關 - [儀表板](/zh-TW/web/dashboard) — Gateway 儀表板 - [健康狀態檢查](/zh-TW/gateway/health) — Gateway 健康狀態監控 - [TUI](/zh-TW/web/tui) — 終端機使用者介面 -- [WebChat](/zh-TW/web/webchat) — 瀏覽器式聊天介面 +- [WebChat](/zh-TW/web/webchat) — 瀏覽器型聊天介面 diff --git a/docs/zh-TW/web/webchat.md b/docs/zh-TW/web/webchat.md index 887b7fe7f..b6f3d0fbb 100644 --- a/docs/zh-TW/web/webchat.md +++ b/docs/zh-TW/web/webchat.md @@ -1,71 +1,83 @@ --- read_when: - - 偵錯或設定 WebChat 存取權 -summary: Loopback WebChat 靜態主機與聊天 UI 的 Gateway WS 使用方式 + - 偵錯或設定 WebChat 存取 +summary: 聊天 UI 的迴路網頁聊天靜態託管與 Gateway WS 使用方式 title: 網頁聊天 x-i18n: - generated_at: "2026-05-03T21:44:33Z" + generated_at: "2026-05-04T02:47:05Z" model: gpt-5.5 provider: openai - source_hash: 48024e58259901c6feb67168c5c1ce32f46b8ad9b6f4511e56d2000478a3ed60 + source_hash: bf435585a13a1cde5885714837017109eeeb61ffa5e33a400017706f676f57ea source_path: web/webchat.md workflow: 16 --- 狀態：macOS/iOS SwiftUI 聊天 UI 會直接與 Gateway WebSocket 通訊。 -## 它是什麼 +## 這是什麼 -- Gateway 的原生聊天 UI（沒有嵌入式瀏覽器，也沒有本機靜態伺服器）。 +- 適用於 Gateway 的原生聊天 UI（沒有嵌入式瀏覽器，也沒有本機靜態伺服器）。 - 使用與其他通道相同的工作階段與路由規則。 -- 決定性路由：回覆一律回到 WebChat。 +- 決定性路由：回覆一律傳回 WebChat。 ## 快速開始 1. 啟動 Gateway。 -2. 開啟 WebChat UI（macOS/iOS 應用程式）或 Control UI 聊天分頁。 -3. 確認已設定有效的 Gateway 驗證路徑（預設為共享密鑰， +2. 開啟 WebChat UI（macOS/iOS app）或 Control UI 聊天分頁。 +3. 確認已設定有效的 Gateway 驗證路徑（預設為 shared-secret， 即使在 loopback 上也是如此）。 ## 運作方式（行為） -- UI 會連線至 Gateway WebSocket，並使用 `chat.history`、`chat.send` 和 `chat.inject`。 -- `chat.history` 為了穩定性而有界限：Gateway 可能會截斷很長的文字欄位、省略大型中繼資料，並以 `[chat.history omitted: message too large]` 取代過大的項目。 -- `chat.history` 會針對現代僅附加工作階段檔案遵循作用中的逐字稿分支，因此已放棄的重寫分支和已被取代的提示副本不會在 WebChat 中呈現。 -- Compaction 項目會呈現為明確的已壓縮歷史分隔線。該分隔線會說明較早的回合已保留在檢查點中，並連結到工作階段檢查點控制項，操作員可在權限允許時從那裡分支或還原 Compaction 前的檢視。 -- Control UI 會記住 `chat.history` 傳回的後端 Gateway `sessionId`，並在後續 `chat.send` 呼叫中包含它，因此重新連線和頁面重新整理會繼續相同的已儲存對話，除非使用者啟動或重設工作階段。 -- Control UI 會在產生新的 `chat.send` 執行 ID 前，合併同一工作階段、訊息和附件的重複進行中提交；Gateway 仍會對重複使用相同冪等性金鑰的重複請求進行去重。 -- `chat.history` 也會進行顯示正規化：僅限執行階段的 OpenClaw 上下文、 - 傳入封套包裝、內嵌傳遞指令標籤 +- UI 連線到 Gateway WebSocket，並使用 `chat.history`、`chat.send` 和 `chat.inject`。 +- `chat.history` 會受到限制以維持穩定性：Gateway 可能會截斷過長的文字欄位、省略龐大的中繼資料，並以 `[chat.history omitted: message too large]` 取代過大的項目。 +- 對於現代的僅附加工作階段檔案，`chat.history` 會遵循作用中的逐字稿分支，因此已放棄的重寫分支和被取代的提示副本不會在 WebChat 中呈現。 +- Compaction 項目會呈現為明確的已壓縮歷史分隔線。分隔線會說明較早的回合已保存在檢查點中，並連結到 Sessions 檢查點控制項；在權限允許時，操作人員可以在那裡建立分支或還原 Compaction 前的檢視。 +- Control UI 會記住 `chat.history` 傳回的後端 Gateway `sessionId`，並在後續的 `chat.send` 呼叫中包含它，因此重新連線與頁面重新整理會繼續同一個已儲存的對話，除非使用者開始或重設工作階段。 +- Control UI 會在產生新的 `chat.send` 執行 ID 前，合併同一個工作階段、訊息與附件的重複進行中提交；Gateway 仍會對重複使用相同冪等鍵的重複請求進行去重。 +- 工作區啟動檔案與待處理的 `BOOTSTRAP.md` 指示會透過代理系統提示的 Project Context 提供，而不是複製到 WebChat 使用者訊息中。Bootstrap 截斷只會加入簡潔的系統提示復原通知；詳細計數與設定旋鈕會保留在診斷介面上。 +- `chat.history` 也會進行顯示正規化：僅執行期的 OpenClaw 內容、 + 傳入信封包裝、內嵌傳遞指令標籤 例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、純文字工具呼叫 XML - 酬載（包括 `...`、 + 承載（包括 `...`、 `...`、`...`、 `...`，以及截斷的工具呼叫區塊），以及 - 外洩的 ASCII/全形模型控制權杖，都會從可見文字中移除， - 而整段可見文字僅為精確靜默 - 權杖 `NO_REPLY` / `no_reply` 的助理項目會被省略。 -- 帶有推理標記的回覆酬載（`isReasoning: true`）會從 WebChat 助理內容、逐字稿重播文字和音訊內容區塊中排除，因此僅供思考的酬載不會顯示為可見的助理訊息或可播放音訊。 -- `chat.inject` 會將助理備註直接附加到逐字稿，並廣播到 UI（不執行代理）。 -- 已中止的執行可讓部分助理輸出持續顯示在 UI 中。 -- 當存在已緩衝輸出時，Gateway 會將已中止的部分助理文字持久化到逐字稿歷史中，並以中止中繼資料標記這些項目。 + 洩漏的 ASCII/全形模型控制權杖，都會從可見文字中移除， + 而整個可見文字僅為精確靜默 + 權杖 `NO_REPLY` / `no_reply` 的 assistant 項目會被省略。 +- 標記為推理的回覆承載（`isReasoning: true`）會從 WebChat assistant 內容、逐字稿重播文字與音訊內容區塊中排除，因此僅思考用的承載不會顯示為可見的 assistant 訊息或可播放音訊。 +- `chat.inject` 會將 assistant 備註直接附加到逐字稿，並廣播給 UI（不執行代理）。 +- 中止的執行可以讓部分 assistant 輸出持續顯示在 UI 中。 +- 當存在已緩衝輸出時，Gateway 會將中止的部分 assistant 文字持久化到逐字稿歷史中，並以中止中繼資料標記這些項目。 - 歷史一律從 Gateway 擷取（不監看本機檔案）。 -- 如果無法連線到 Gateway，WebChat 會是唯讀。 +- 如果無法連上 Gateway，WebChat 會是唯讀狀態。 + +### 逐字稿與傳遞模型 + +WebChat 有兩條獨立的資料路徑： + +- 工作階段 JSONL 檔案是持久化的模型/執行期逐字稿。對於一般代理執行，Pi 會透過其工作階段管理器持久化模型可見的 `user`、`assistant` 和 `toolResult` 訊息。WebChat 不會將任意傳遞、狀態或輔助文字寫入該逐字稿。 +- Gateway `ReplyPayload` 事件是即時傳遞投影。它們可以針對 WebChat/通道顯示、區塊串流、指令標籤、媒體嵌入、TTS/音訊旗標與 UI 備援行為進行正規化。它們本身並不是權威的工作階段記錄。 +- WebChat 只會在 Gateway 擁有一般 Pi assistant 回合之外顯示的訊息時，注入 assistant 逐字稿項目：`chat.inject`、非代理命令回覆、中止的部分輸出，以及 WebChat 管理的媒體逐字稿補充內容。 +- `chat.history` 會讀取已儲存的工作階段逐字稿，並套用 WebChat 顯示投影。如果即時 assistant 文字在執行期間出現，但在重新載入歷史後消失，請先檢查原始 JSONL 是否包含該 assistant 文字，接著檢查 `chat.history` 投影是否將其移除，再檢查 Control UI 樂觀尾端合併是否以持久化快照取代了本機傳遞狀態。 + +一般代理執行的最終答案應該是持久化的，因為 Pi 會寫入 assistant `message_end`。任何將已傳遞最終承載鏡像到逐字稿中的備援，都必須先避免重複建立 Pi 已經寫入的 assistant 回合。 ## Control UI 代理工具面板 - Control UI `/agents` 工具面板有兩個獨立檢視： - **目前可用** 使用 `tools.effective(sessionKey=...)`，並顯示目前 - 工作階段在執行階段實際可使用的內容，包括核心、Plugin 和通道擁有的工具。 - - **工具設定** 使用 `tools.catalog`，並持續專注於設定檔、覆寫和 + 工作階段在執行期實際可用的內容，包括核心、Plugin 與通道擁有的工具。 + - **工具設定** 使用 `tools.catalog`，並聚焦於設定檔、覆寫與 目錄語意。 -- 執行階段可用性以工作階段為範圍。在同一代理上切換工作階段可能會變更 +- 執行期可用性以工作階段為範圍。在同一個代理上切換工作階段，可能會變更 **目前可用** 清單。 -- 設定編輯器不代表執行階段可用性；有效存取仍遵循政策 - 優先順序（`allow`/`deny`、每代理與供應商/通道覆寫）。 +- 設定編輯器不代表執行期可用；有效存取仍會遵循原則 + 優先順序（`allow`/`deny`、每代理與提供者/通道覆寫）。 ## 遠端使用 -- 遠端模式會透過 SSH/Tailscale 對 Gateway WebSocket 建立隧道。 +- 遠端模式會透過 SSH/Tailscale 建立 Gateway WebSocket 通道。 - 你不需要執行獨立的 WebChat 伺服器。 ## 設定參考（WebChat） @@ -74,20 +86,20 @@ x-i18n: WebChat 選項： -- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 回應中文字欄位的最大字元數。當逐字稿項目超過此限制時，Gateway 會截斷很長的文字欄位，並可能以預留位置取代過大的訊息。用戶端也可以傳送每次請求的 `maxChars`，針對單一 `chat.history` 呼叫覆寫此預設值。 +- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 回應中文字欄位的最大字元數。當逐字稿項目超過此限制時，Gateway 會截斷過長的文字欄位，並可能以預留位置取代過大的訊息。用戶端也可以傳送單次請求的 `maxChars`，以覆寫單次 `chat.history` 呼叫的此預設值。 相關全域選項： - `gateway.port`、`gateway.bind`：WebSocket 主機/連接埠。 - `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`： - 共享密鑰 WebSocket 驗證。 + shared-secret WebSocket 驗證。 - `gateway.auth.allowTailscale`：啟用時，瀏覽器 Control UI 聊天分頁可以使用 Tailscale Serve 身分標頭。 -- `gateway.auth.mode: "trusted-proxy"`：供位於具身分感知能力的**非 loopback** Proxy 來源後方之瀏覽器用戶端使用的反向 Proxy 驗證（請參閱 [可信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)）。 +- `gateway.auth.mode: "trusted-proxy"`：供位於具身分感知能力的**非 loopback** 代理來源後方的瀏覽器用戶端使用的反向代理驗證（請參閱 [Trusted Proxy Auth](/zh-TW/gateway/trusted-proxy-auth)）。 - `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：遠端 Gateway 目標。 - `session.*`：工作階段儲存與主要金鑰預設值。 ## 相關 - [Control UI](/zh-TW/web/control-ui) -- [儀表板](/zh-TW/web/dashboard) +- [Dashboard](/zh-TW/web/dashboard)