openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-TW translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 16:31:51 +00:00
parent 9d712ecc03
commit 7b58e6a070
19 changed files with 2539 additions and 2560 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
docs/zh-TW/automation/tasks.md
View File

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

188
docs/zh-TW/channels/groups.md
View File

@ -1,38 +1,38 @@
---
read_when:
- 變更群組聊天行為或提及閘控
- 變更群組聊天行為或提及門檻設定
sidebarTitle: Groups
summary: 跨各介面的群組聊天行為 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
summary: 跨介面的群組聊天行為 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: 群組
x-i18n:
generated_at: "2026-04-30T02:46:45Z"
generated_at: "2026-04-30T16:27:42Z"
model: gpt-5.5
provider: openai
source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998
source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e
source_path: channels/groups.md
workflow: 16
---
OpenClaw 在各個介面上一致地處理群組聊天：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
OpenClaw 會在各種介面上一致地處理群組聊天：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
## 初學者簡介（2 分鐘）
OpenClaw「存在」於你自己的訊息帳號中。沒有獨立的 WhatsApp bot 使用者。如果**你**在某個群組中，OpenClaw 就能看見該群組並在其中回應。
OpenClaw「存在」於你自己的訊息帳號中。沒有獨立的 WhatsApp bot 使用者。如果**你**在某個群組中，OpenClaw 就能看到該群組並在其中回應。
預設行為：
- 群組受到限制（`groupPolicy: "allowlist"`）。
- 除非你明確停用提及閘控，否則回覆需要提及。
- 群組/頻道中的一般最終回覆預設為私人。可見的聊天室輸出會使用 `message` 工具。
- 群組受限制（`groupPolicy: "allowlist"`）。
- 回覆需要提及，除非你明確停用提及門控。
- 群組/頻道中的一般最終回覆預設為私密。可見的聊天室輸出會使用 `message` 工具。
換句話說：允許清單中的傳送者可以透過提及 OpenClaw 來觸發它。
換句話說：列入允許清單的傳送者可以透過提及 OpenClaw 來觸發它。
<Note>
**TL;DR**
**太長不讀**
- **私訊存取**由 `*.allowFrom` 控制。
- **DM 存取**由 `*.allowFrom` 控制。
- **群組存取**由 `*.groupPolicy` + 允許清單（`*.groups`、`*.groupAllowFrom`）控制。
- **回覆觸發**由提及閘控（`requireMention`、`/activation`）控制。
- **回覆觸發**由提及門控（`requireMention`、`/activation`）控制。
</Note>
@ -47,16 +47,16 @@ otherwise -> reply
## 可見回覆
對於群組/頻道聊天室，OpenClaw 預設為 `messages.groupChat.visibleReplies: "message_tool"`。
這表示 agent 仍會處理該回合，並可更新記憶/session 狀態，但它的一般最終答案不會自動貼回聊天室。若要可見地發言，agent 會使用 `message(action=send)`。
對於群組/頻道聊天室，OpenClaw 預設使用 `messages.groupChat.visibleReplies: "message_tool"`。
這表示代理仍會處理該輪對話，也可以更新記憶/session 狀態，但其一般最終答案不會自動發回聊天室。若要可見地發言，代理會使用 `message(action=send)`。
對於直接聊天和任何其他來源回合，使用 `messages.visibleReplies: "message_tool"` 可在全域套用相同的僅工具可見回覆行為。`messages.groupChat.visibleReplies` 仍是群組/頻道聊天室更具體的覆寫設定。
對於直接聊天與任何其他來源輪次，使用 `messages.visibleReplies: "message_tool"` 可在全域套用相同的僅工具可見回覆行為。`messages.groupChat.visibleReplies` 仍是針對群組/頻道聊天室更具體的覆寫。
這取代了舊模式，也就是強迫模型在多數潛伏模式回合中回答 `NO_REPLY`。在僅工具模式中，沒有任何可見動作只代表沒有呼叫 message 工具。
這取代了舊模式中強迫模型在大多數潛伏模式輪次回答 `NO_REPLY` 的做法。在僅工具模式中，不做任何可見輸出只代表不呼叫 message 工具。
agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合的預設群組輸入模式會從「message」升級為「instant」，因為在 agent 決定是否呼叫 message 工具之前，可能永遠不會有一般 assistant 訊息文字。明確的輸入模式設定仍會優先。
代理在僅工具模式中工作時仍會送出輸入中指示器。這些輪次的預設群組輸入模式會從「message」升級為「instant」，因為在代理決定是否呼叫 message 工具之前，可能永遠不會有一般 assistant 訊息文字。明確的輸入模式設定仍然優先。
若要恢復群組/頻道聊天室的舊版自動最終回覆：
若要還原群組/頻道聊天室的舊版自動最終回覆：
```json5
{
@ -68,6 +68,8 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
}
```
Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署中停用檔案監看或設定重新載入時才需要重新啟動。
若要要求每個來源聊天的可見輸出都透過 message 工具：
```json5
@ -78,29 +80,29 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
}
```
原生 slash commands（Discord、Telegram，以及其他支援原生命令的介面）會繞過 `visibleReplies: "message_tool"`，並一律可見回覆，讓頻道原生命令 UI 取得預期回應。這只適用於已驗證的原生命令回合；文字輸入的 `/...` 命令和一般聊天回合仍會遵循已設定的群組預設值。
原生斜線命令（Discord、Telegram，以及其他支援原生命令的介面）會繞過 `visibleReplies: "message_tool"`，並一律可見地回覆，讓頻道原生命令 UI 取得預期的回應。這只適用於已驗證的原生命令輪次；以文字輸入的 `/...` 命令與一般聊天輪次仍會遵循設定的群組預設值。
## 脈絡可見性與允許清單
## 上下文可見性與允許清單
群組安全涉及兩種不同控制：
- **觸發授權**：誰可以觸發 agent（`groupPolicy`、`groups`、`groupAllowFrom`、頻道專屬允許清單）。
- **脈絡可見性**：哪些補充脈絡會注入模型（回覆文字、引文、討論串歷史、轉寄中繼資料）。
- **觸發授權**：誰可以觸發代理（`groupPolicy`、`groups`、`groupAllowFrom`、頻道專屬允許清單）。
- **上下文可見性**：哪些補充上下文會注入模型（回覆文字、引用、thread 歷史、轉寄中繼資料）。
預設情況下，OpenClaw 會優先維持一般聊天行為，並大多保留接收到的脈絡。這表示允許清單主要決定誰可以觸發動作，而不是每個引用或歷史片段的通用遮蔽邊界。
預設情況下，OpenClaw 會優先採用一般聊天行為，並大致保留接收到的上下文。這表示允許清單主要決定誰可以觸發動作，而不是每段引用或歷史片段的通用遮罩邊界。
<AccordionGroup>
<Accordion title="目前行為依頻道而異">
- 某些頻道已在特定路徑中對補充脈絡套用以傳送者為基礎的篩選（例如 Slack 討論串種子、Matrix 回覆/討論串查詢）。
- 其他頻道仍會照接收內容傳遞引用/回覆/轉寄脈絡。
<Accordion title="Current behavior is channel-specific">
- 部分頻道已在特定路徑中對補充上下文套用以傳送者為基礎的篩選（例如 Slack thread 植入、Matrix 回覆/thread 查詢）。
- 其他頻道仍會按照接收內容傳遞引用/回覆/轉寄上下文。
</Accordion>
<Accordion title="強化方向（已規劃）">
- `contextVisibility: "all"`（預設）保留目前照接收內容處理的行為。
- `contextVisibility: "allowlist"` 會將補充脈絡篩選為允許清單中的傳送者。
<Accordion title="Hardening direction (planned)">
- `contextVisibility: "all"`（預設）保留目前按照接收內容的行為。
- `contextVisibility: "allowlist"` 會將補充上下文篩選為列入允許清單的傳送者。
- `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一個明確的引用/回覆例外。
在此強化模型於各頻道一致實作之前，預期不同介面會有差異。
在此強化模型於各頻道間一致實作之前，請預期不同介面會有差異。
</Accordion>
</AccordionGroup>
@ -109,7 +111,7 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
如果你想要...
| 目標 | 要設定的內容 |
| 目標 | 要設定的內容 |
| -------------------------------------------- | ---------------------------------------------------------- |
| 允許所有群組，但只在 @提及時回覆 | `groups: { "*": { requireMention: true } }` |
| 停用所有群組回覆 | `groupPolicy: "disabled"` |
@ -119,29 +121,29 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
## Session 鍵
- 群組 session 使用 `agent:<agentId>:<channel>:group:<id>` session 鍵（聊天室/頻道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 論壇主題會在群組 ID 加上 `:topic:<threadId>`，因此每個主題都有自己的 session。
- 直接聊天使用主要 session（或在設定時使用每位傳送者各自的 session）。
- 群組 session 會略過 Heartbeat。
- Telegram 論壇主題會在群組 id 後加上 `:topic:<threadId>`，讓每個主題都有自己的 session。
- 直接聊天使用主要 session（或在已設定時依傳送者分開）。
- 群組 session 會跳過 Heartbeat。
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## 模式：個人私訊 + 公開群組（單一 agent）
## 模式：個人 DM + 公開群組（單一代理）
可以，若你的「個人」流量是**私訊**，而你的「公開」流量是**群組**，這個做法很適合。
可以，若你的「個人」流量是 **DM**，而「公開」流量是**群組**，這種方式效果很好。
原因：在單一 agent 模式中，私訊通常落在**主要** session 鍵（`agent:main:main`），而群組一律使用**非主要** session 鍵（`agent:main:<channel>:group:<id>`）。如果你使用 `mode: "non-main"` 啟用 sandboxing，這些群組 session 會在設定的 sandbox 後端中執行，而你的主要私訊 session 會留在主機上。如果你沒有選擇後端，Docker 是預設後端。
原因：在單一代理模式中，DM 通常會落在**主要** session 鍵（`agent:main:main`），而群組一律使用**非主要** session 鍵（`agent:main:<channel>:group:<id>`）。如果你以 `mode: "non-main"` 啟用沙箱，這些群組 session 會在設定的沙箱後端中執行，而你的主要 DM session 會留在主機上。如果你沒有選擇後端，Docker 是預設後端。
這會給你一個 agent「大腦」（共享工作區 + 記憶），但有兩種執行姿態：
這讓你擁有一個代理「大腦」（共享工作區 + 記憶），但有兩種執行姿態：
- **私訊**：完整工具（主機）
- **群組**：sandbox + 受限工具
- **DM**：完整工具（主機）
- **群組**：沙箱 + 受限工具
<Note>
如果你需要真正分離的工作區/persona（「個人」和「公開」絕不能混在一起），請使用第二個 agent + 繫結。請參閱[多 Agent 路由](/zh-TW/concepts/multi-agent)。
如果你需要真正分離的工作區/人格（「個人」與「公開」絕不能混用），請使用第二個代理 + 綁定。請參閱[多代理路由](/zh-TW/concepts/multi-agent)。
</Note>
<Tabs>
<Tab title="私訊在主機上，群組在 sandbox 中">
<Tab title="DMs on host, groups sandboxed">
```json5
{
agents: {
@ -165,8 +167,8 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
}
```
</Tab>
<Tab title="群組只看得到允許清單中的資料夾">
想要「群組只能看到資料夾 X」，而不是「沒有主機存取權」？保留 `workspaceAccess: "none"`，並只將允許清單中的路徑掛載到 sandbox：
<Tab title="Groups see only an allowlisted folder">
想要「群組只能看到資料夾 X」，而不是「沒有主機存取權」？保留 `workspaceAccess: "none"`，並只將列入允許清單的路徑掛載到沙箱中：
```json5
{
@ -194,13 +196,13 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
相關：
- 設定鍵與預設值：[Gateway 設定](/zh-TW/gateway/config-agents#agentsdefaultssandbox)
- 偵錯工具為何被封鎖：[Sandbox 與工具政策與提升權限](/zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated)
- Bind mount 詳細資訊：[Sandboxing](/zh-TW/gateway/sandboxing#custom-bind-mounts)
- 偵錯工具為何被封鎖：[沙箱 vs 工具政策 vs 提權](/zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated)
- 綁定掛載詳細資訊：[沙箱化](/zh-TW/gateway/sandboxing#custom-bind-mounts)
## 顯示標籤
- UI 標籤在可用時使用 `displayName`，格式為 `<channel>:<token>`。
- `#room` 保留給聊天室/頻道；群組聊天使用 `g-<slug>`（小寫、空格 -> `-`、保留 `#@+._-`）。
- UI 標籤會在可用時使用 `displayName`，格式為 `<channel>:<token>`。
- `#room` 保留給聊天室/頻道；群組聊天使用 `g-<slug>`（小寫、空格 -> `-`，保留 `#@+._-`）。
## 群組政策
@ -253,22 +255,23 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
| 政策 | 行為 |
| ------------- | ------------------------------------------------------------ |
| `"open"` | 群組會繞過允許清單；提及閘控仍會套用。 |
| `"open"` | 群組會繞過允許清單；提及門控仍會套用。 |
| `"disabled"` | 完全封鎖所有群組訊息。 |
| `"allowlist"` | 只允許符合已設定允許清單的群組/聊天室。 |
| `"allowlist"` | 只允許符合設定之允許清單的群組/聊天室。 |
<AccordionGroup>
<Accordion title="各頻道注意事項">
- `groupPolicy` 與提及閘控是分開的（後者需要 @提及）。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（備援：明確的 `allowFrom`）。
- 私訊配對核准（`*-allowFrom` 儲存項目）只適用於私訊存取；群組傳送者授權仍明確使用群組允許清單。
<Accordion title="Per-channel notes">
- `groupPolicy` 與提及門控（需要 @提及）是分開的。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（後援：明確的 `allowFrom`）。
- Signal：`groupAllowFrom` 可以符合傳入的 Signal 群組 id，或傳送者電話/UUID。
- DM 配對核准（`*-allowFrom` 儲存項目）只套用於 DM 存取；群組傳送者授權仍需明確列入群組允許清單。
- Discord：允許清單使用 `channels.discord.guilds.<id>.channels`。
- Slack：允許清單使用 `channels.slack.channels`。
- Matrix：允許清單使用 `channels.matrix.groups`。偏好使用聊天室 ID 或別名；已加入聊天室的名稱查詢是盡力而為，未解析的名稱會在執行階段被忽略。使用 `channels.matrix.groupAllowFrom` 來限制傳送者；也支援每個聊天室的 `users` 允許清單。
- 群組私訊會分開控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram 允許清單可比對使用者 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或使用者名稱（`"@alice"` 或 `"alice"`）；前綴不區分大小寫。
- Matrix：允許清單使用 `channels.matrix.groups`。偏好使用聊天室 ID 或別名；已加入聊天室名稱查詢為盡力而為，未解析的名稱會在執行階段被忽略。使用 `channels.matrix.groupAllowFrom` 來限制傳送者；也支援每個聊天室的 `users` 允許清單。
- 群組 DM 會分開控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram 允許清單可以符合使用者 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或使用者名稱（`"@alice"` 或 `"alice"`）；前綴不區分大小寫。
- 預設為 `groupPolicy: "allowlist"`；如果你的群組允許清單是空的，群組訊息會被封鎖。
- 執行階段安全性：當 provider 區塊完全缺失（沒有 `channels.<provider>`）時，群組政策會退回失敗關閉模式（通常是 `allowlist`），而不是繼承 `channels.defaults.groupPolicy`。
- 執行階段安全性：當 provider 區塊完全不存在時（缺少 `channels.<provider>`），群組政策會後援到失敗關閉模式（通常是 `allowlist`），而不是繼承 `channels.defaults.groupPolicy`。
</Accordion>
</AccordionGroup>
@ -279,19 +282,19 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
<Step title="groupPolicy">
`groupPolicy`（open/disabled/allowlist）。
</Step>
<Step title="群組允許清單">
<Step title="Group allowlists">
群組允許清單（`*.groups`、`*.groupAllowFrom`、頻道專屬允許清單）。
</Step>
<Step title="提及閘控">
提及閘控（`requireMention`、`/activation`）。
<Step title="Mention gating">
提及門控（`requireMention`、`/activation`）。
</Step>
</Steps>
## 提及閘控（預設）
## 提及門控（預設）
群組訊息需要提及，除非依群組覆寫。預設值位於每個子系統的 `*.groups."*"` 下。
群組訊息需要提及，除非針對每個群組覆寫。預設值位於 `*.groups."*"` 下各子系統中。
回覆機器人訊息在頻道支援回覆中繼資料時，會算作隱含提及。引用機器人訊息在公開引用中繼資料的頻道上，也可以算作隱含提及。目前內建案例包含 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 與 ZaloUser。
回覆機器人訊息在頻道支援回覆中繼資料時，會算作隱含提及。引用機器人訊息在會公開引用中繼資料的頻道上，也可能算作隱含提及。目前內建案例包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
```json5
{
@ -331,26 +334,27 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
<AccordionGroup>
<Accordion title="Mention gating notes">
- `mentionPatterns` 是不區分大小寫的安全 regex 模式；無效模式與不安全的巢狀重複形式會被忽略。
- 提供明確提及的介面仍會通過；模式是備援。
- 每代理覆寫：`agents.list[].groupChat.mentionPatterns`（在多個代理共用群組時很有用）。
- 提及門檻只會在可偵測提及時強制執行（已設定原生提及或 `mentionPatterns`）。
- 群組聊天提示詞上下文會在每一輪攜帶已解析的靜默回覆指令；工作區檔案不應重複 `NO_REPLY` 機制。
- 允許靜默回覆的群組，會將乾淨的空白或僅推理模型輪次視為靜默，等同於 `NO_REPLY`。直接聊天只有在明確允許直接靜默回覆時才會相同；否則空白回覆仍會保留為失敗的代理輪次。
- `mentionPatterns` 是不區分大小寫的安全 regex 模式；無效模式和不安全的巢狀重複形式會被忽略。
- 提供明確提及的介面仍會通過；模式只是備援。
- 個別代理覆寫：`agents.list[].groupChat.mentionPatterns`（多個代理共用同一群組時很有用）。
- 提及閘控只會在能偵測提及時強制執行（已設定原生提及或 `mentionPatterns`）。
- 將群組或寄件者加入允許清單不會停用提及閘控；當所有訊息都應觸發時，請將該群組的 `requireMention` 設為 `false`。
- 群組聊天提示詞內容會在每一輪攜帶已解析的靜默回覆指令；工作區檔案不應重複 `NO_REPLY` 機制。
- 允許靜默回覆的群組，會將乾淨的空白或僅推理的模型回合視為靜默，等同於 `NO_REPLY`。直接聊天只有在明確允許直接靜默回覆時才會這樣做；否則空白回覆仍會是失敗的代理回合。
- Discord 預設值位於 `channels.discord.guilds."*"`（可依 guild/channel 覆寫）。
- 群組歷史上下文會跨頻道一致包裝，且為 **pending-only**（因提及門檻而略過的訊息）；使用 `messages.groupChat.historyLimit` 作為全域預設值，並使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）進行覆寫。設為 `0` 可停用。
- 群組歷史內容會在各頻道間以一致方式包裝，且**僅限待處理**（因提及閘控而略過的訊息）；使用 `messages.groupChat.historyLimit` 作為全域預設值，並使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）進行覆寫。設為 `0` 可停用。
</Accordion>
</AccordionGroup>
## 群組/頻道工具限制（選用）
某些頻道設定支援限制 **特定群組/聊天室/頻道內** 可用的工具。
某些頻道設定支援限制**特定群組/聊天室/頻道內**可用的工具。
- `tools`：允許/拒絕整個群組的工具。
- `toolsBySender`：群組內依傳送者覆寫。使用明確的鍵前綴：`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>` 與 `"*"` 萬用字元。舊版未加前綴的鍵仍會接受，且只會以 `id:` 比對。
- `toolsBySender`：群組內依寄件者覆寫。使用明確的鍵前綴：`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>` 和 `"*"` 萬用字元。舊版未加前綴的鍵仍會被接受，且只會以 `id:` 比對。
解析順序（最具體者優先）：
解析順序（最明確者優先）：
<Steps>
<Step title="Group toolsBySender">
@ -360,10 +364,10 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
群組/頻道 `tools`。
</Step>
<Step title="Default toolsBySender">
預設 (`"*"`) `toolsBySender` 比對。
預設（`"*"`）`toolsBySender` 比對。
</Step>
<Step title="Default tools">
預設 (`"*"`) `tools`。
預設（`"*"`）`tools`。
</Step>
</Steps>
@ -388,7 +392,7 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
```
<Note>
群組/頻道工具限制會在全域/代理工具政策之外另行套用（拒絕仍然優先）。某些頻道會針對聊天室/頻道使用不同的巢狀結構（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
群組/頻道工具限制會套用在全域/代理工具政策之外（拒絕仍優先）。某些頻道對聊天室/頻道使用不同的巢狀結構（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
</Note>
## 群組允許清單
@ -396,7 +400,7 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
設定 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 時，鍵會作為群組允許清單。使用 `"*"` 可允許所有群組，同時仍設定預設提及行為。
<Warning>
常見混淆：DM 配對核准不等同於群組授權。對於支援 DM 配對的頻道，配對儲存區只會解鎖 DM。群組命令仍需要來自設定允許清單（例如 `groupAllowFrom`）或該頻道已記載設定備援的明確群組傳送者授權。
常見混淆：DM 配對核准不等同於群組授權。對於支援 DM 配對的頻道，配對儲存區只會解鎖 DM。群組指令仍需要來自設定允許清單的明確群組寄件者授權，例如 `groupAllowFrom` 或該頻道記載的設定備援。
</Warning>
常見意圖（複製/貼上）：
@ -456,37 +460,37 @@ agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合
- `/activation mention`
- `/activation always`
擁有者由 `channels.whatsapp.allowFrom` 判定（未設定時則使用機器人自己的 E.164）。請將命令作為獨立訊息傳送。其他介面目前會忽略 `/activation`。
擁有者由 `channels.whatsapp.allowFrom` 決定（未設定時則使用機器人自己的 E.164）。請將指令作為獨立訊息傳送。其他介面目前會忽略 `/activation`。
## 上下文字段
## 內容欄位
群組傳入 payload 會設定：
群組傳入酬載會設定：
- `ChatType=group`
- `GroupSubject`（若已知）
- `GroupMembers`（若已知）
- `WasMentioned`（提及門檻結果）
- Telegram 論壇主題也會包含 `MessageThreadId` 與 `IsForum`。
- `WasMentioned`（提及閘控結果）
- Telegram 論壇主題也會包含 `MessageThreadId` 和 `IsForum`。
頻道特定注意事項：
- BlueBubbles 可以選擇在填入 `GroupMembers` 前，先從本機「聯絡人」資料庫補充未命名的 macOS 群組參與者。這預設關閉，且只會在正常群組門檻通過後執行。
- BlueBubbles 可選擇在填入 `GroupMembers` 前，從本機通訊錄資料庫補充未命名的 macOS 群組參與者。這預設關閉，且只會在一般群組閘控通過後執行。
代理系統提示詞會在新群組工作階段的第一輪包含群組介紹。它會提醒模型像人類一樣回應、避免 Markdown 表格、盡量減少空白行並遵循一般聊天間距，以及避免輸入字面 `\n` 序列。頻道來源的群組名稱與參與者標籤會呈現為 fenced 不受信任中繼資料，而不是內嵌系統指令。
代理系統提示詞會在新群組工作階段的第一輪包含群組介紹。它會提醒模型像人類一樣回應、避免 Markdown 表格、盡量減少空行並遵循一般聊天間距，以及避免輸入字面上的 `\n` 序列。來自頻道的群組名稱和參與者標籤會呈現為 fenced 不受信任中繼資料，而不是行內系統指令。
## iMessage 細節
## iMessage 特定事項
- 路由或加入允許清單時，優先使用 `chat_id:<id>`。
- 路由或加入允許清單時，偏好使用 `chat_id:<id>`。
- 列出聊天：`imsg chats --limit 20`。
- 群組回覆一律傳回相同的 `chat_id`。
- 群組回覆一律會回到相同的 `chat_id`。
## WhatsApp 系統提示詞
請參閱 [WhatsApp](/zh-TW/channels/whatsapp#system-prompts)，了解權威的 WhatsApp 系統提示詞規則，包括群組與直接提示詞解析、萬用字元行為，以及帳號覆寫語意。
請參閱 [WhatsApp](/zh-TW/channels/whatsapp#system-prompts)，了解正式的 WhatsApp 系統提示詞規則，包括群組與直接提示詞解析、萬用字元行為，以及帳號覆寫語意。
## WhatsApp 細節
## WhatsApp 特定事項
請參閱 [群組訊息](/zh-TW/channels/group-messages)，了解 WhatsApp 專屬行為（歷史注入、提及處理細節）。
請參閱[群組訊息](/zh-TW/channels/group-messages)，了解僅限 WhatsApp 的行為（歷史注入、提及處理細節）。
## 相關

169
docs/zh-TW/channels/signal.md
View File

@ -1,34 +1,34 @@
---
read_when:
- 設定 Signal 支援
- Signal 傳送/接收偵錯
summary: 透過 signal-cli (JSON-RPC + SSE) 支援 Signal、設定路徑與號碼模型
- 設定 Signal 支援功能
- 偵錯 Signal 傳送/接收
summary: 透過 signal-cli（JSON-RPC + SSE）支援 Signal、設定路徑與號碼模型
title: Signal
x-i18n:
generated_at: "2026-04-30T02:48:59Z"
generated_at: "2026-04-30T16:27:46Z"
model: gpt-5.5
provider: openai
source_hash: d450454550a86cbf0e2b7231bb149f78275a756517db1f20d7a07e3d298febee
source_hash: 111b6ebe3bde4e03c7ed432f52d663f0b471f0fc4a4bf835c1ac1972467e0b96
source_path: channels/signal.md
workflow: 16
---
狀態：外部 CLI 整合。Gateway 透過 HTTP JSON-RPC + SSE 與 `signal-cli` 通訊。
Status: 外部 CLI 整合。Gateway 透過 `signal-cli` 經由 HTTP JSON-RPC + SSE 通訊。
## 先決條件
- 你的伺服器上已安裝 OpenClaw（以下 Linux 流程已在 Ubuntu 24 測試）。
- Gateway 執行所在主機上可使用 `signal-cli`。
- 可接收一則驗證簡訊的電話號碼（用於簡訊註冊路徑）。
- 註冊期間可透過瀏覽器存取 Signal captcha（`signalcaptchas.org`）。
- Gateway 執行所在主機可使用 `signal-cli`。
- 可接收一則驗證 SMS 的電話號碼（用於 SMS 註冊路徑）。
- 註冊期間可使用瀏覽器存取 Signal captcha（`signalcaptchas.org`）。
## 快速設定（初學者）
1. 為機器人使用**獨立的 Signal 號碼**（建議）。
2. 安裝 `signal-cli`（如果使用 JVM 建置版本，需安裝 Java）。
2. 安裝 `signal-cli`（如果使用 JVM 建置版，需先安裝 Java）。
3. 選擇一種設定路徑：
- **路徑 A（QR 連結）：** `signal-cli link -n "OpenClaw"`，然後使用 Signal 掃描。
- **路徑 B（簡訊註冊）：** 使用 captcha + 簡訊驗證註冊專用號碼。
- **路徑 B（SMS 註冊）：** 使用 captcha + SMS 驗證註冊專用號碼。
4. 設定 OpenClaw 並重新啟動 Gateway。
5. 傳送第一則私訊並核准配對（`openclaw pairing approve signal <CODE>`）。
@ -57,15 +57,15 @@ x-i18n:
| `dmPolicy` | 私訊存取政策（建議使用 `pairing`） |
| `allowFrom` | 允許傳送私訊的電話號碼或 `uuid:<id>` 值 |
## 它是什麼
## 這是什麼
- 透過 `signal-cli` 的 Signal 頻道（不是內嵌 libsignal）。
- 決定性路由：回覆一律回到 Signal。
- 私訊共用 agent 的主要工作階段；群組則隔離（`agent:<agentId>:signal:group:<groupId>`）。
- 透過 `signal-cli` 提供的 Signal 通道（不是內嵌的 libsignal）。
- 確定性路由：回覆一律送回 Signal。
- 私訊共用代理的主要工作階段；群組會隔離（`agent:<agentId>:signal:group:<groupId>`）。
## 設定寫入
預設情況下，Signal 允許寫入由 `/config set|unset` 觸發的設定更新（需要 `commands.config: true`）。
根據預設，Signal 可寫入由 `/config set|unset` 觸發的設定更新（需要 `commands.config: true`）。
使用以下設定停用：
@ -78,12 +78,12 @@ x-i18n:
## 號碼模型（重要）
- Gateway 會連線到一個 **Signal 裝置**（`signal-cli` 帳號）。
- 如果你在**自己的個人 Signal 帳號**上執行機器人，它會忽略你自己的訊息（迴圈保護）。
- 如果你在**個人的 Signal 帳號**上執行機器人，它會忽略你自己的訊息（迴圈保護）。
- 若要「我傳訊息給機器人，然後它回覆」，請使用**獨立的機器人號碼**。
## 設定路徑 A：連結現有 Signal 帳號（QR）
1. 安裝 `signal-cli`（JVM 或原生建置版本）。
1. 安裝 `signal-cli`（JVM 或原生建置版）。
2. 連結機器人帳號：
- `signal-cli link -n "OpenClaw"`，然後在 Signal 中掃描 QR。
3. 設定 Signal 並啟動 Gateway。
@ -106,11 +106,11 @@ x-i18n:
多帳號支援：使用 `channels.signal.accounts` 搭配每個帳號的設定與選用的 `name`。共享模式請參閱 [`gateway/configuration`](/zh-TW/gateway/config-channels#multi-account-all-channels)。
## 設定路徑 B：註冊專用機器人號碼（簡訊，Linux）
## 設定路徑 B：註冊專用機器人號碼（SMS，Linux）
當你想使用專用機器人號碼，而不是連結現有 Signal 應用程式帳號時，請使用此方式。
當你想使用專用機器人號碼，而不是連結現有 Signal app 帳號時，請使用此方式。
1. 取得可接收簡訊的號碼（或固定電話的語音驗證）。
1. 取得可接收 SMS 的號碼（或市話可使用語音驗證）。
- 使用專用機器人號碼，以避免帳號/工作階段衝突。
2. 在 Gateway 主機上安裝 `signal-cli`：
@ -122,8 +122,8 @@ sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version
```
如果你使用 JVM 建置版本（`signal-cli-${VERSION}.tar.gz`），請先安裝 JRE 25+。
請保持 `signal-cli` 更新；上游說明指出，舊版本可能會因 Signal 伺服器 API 變更而故障。
如果使用 JVM 建置版（`signal-cli-${VERSION}.tar.gz`），請先安裝 JRE 25+。
請保持 `signal-cli` 更新；上游說明指出，舊版本可能會因 Signal 伺服器 API 變更而失效。
3. 註冊並驗證號碼：
@ -143,7 +143,7 @@ signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
4. 設定 OpenClaw、重新啟動 Gateway、驗證頻道：
4. 設定 OpenClaw、重新啟動 Gateway，並驗證通道：
```bash
# If you run the gateway as a user systemd service:
@ -155,12 +155,12 @@ openclaw channels status --probe
```
5. 配對你的私訊傳送者：
- 傳送任何訊息到機器人號碼。
- 傳送任意訊息到機器人號碼。
- 在伺服器上核准代碼：`openclaw pairing approve signal <PAIRING_CODE>`。
- 將機器人號碼儲存為手機聯絡人，以避免顯示「未知聯絡人」。
- 將機器人號碼儲存為手機聯絡人，以避免「Unknown contact」。
<Warning>
使用 `signal-cli` 註冊電話號碼帳號，可能會讓該號碼的主要 Signal 應用程式工作階段失效。建議使用專用機器人號碼，或者如果你需要保留現有手機應用程式設定，請使用 QR 連結模式。
使用 `signal-cli` 註冊電話號碼帳號可能會讓該號碼的主要 Signal app 工作階段取消驗證。建議使用專用機器人號碼，或如果需要保留現有手機 app 設定，請使用 QR 連結模式。
</Warning>
上游參考：
@ -169,9 +169,9 @@ openclaw channels status --probe
- Captcha 流程：`https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha`
- 連結流程：`https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)`
## 外部 daemon 模式（httpUrl）
## 外部常駐程式模式（httpUrl）
如果你想自行管理 `signal-cli`（JVM 冷啟動較慢、容器初始化，或共用 CPU），請另外執行 daemon，並讓 OpenClaw 指向它：
如果你想自行管理 `signal-cli`（JVM 冷啟動緩慢、容器初始化或共享 CPU），請另行執行常駐程式，並將 OpenClaw 指向它：
```json5
{
@ -184,55 +184,56 @@ openclaw channels status --probe
}
```
這會略過 OpenClaw 內部的自動生成程序與啟動等待。若自動生成時啟動較慢，請設定 `channels.signal.startupTimeoutMs`。
這會略過 OpenClaw 內部的自動產生程序與啟動等待。若自動產生程序時啟動較慢，請設定 `channels.signal.startupTimeoutMs`。
## 存取控制（私訊 + 群組）
私訊：
- 預設：`channels.signal.dmPolicy = "pairing"`。
- 未知傳送者會收到配對代碼；訊息會在核准前被忽略（代碼 1 小時後過期）。
- 未知傳送者會收到配對代碼；訊息在核准前會被忽略（代碼會在 1 小時後過期）。
- 透過以下方式核准：
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
- 配對是 Signal 私訊的預設 token 交換方式。詳情：[配對](/zh-TW/channels/pairing)
- 配對是 Signal 私訊的預設 token 交換方式。詳細資訊：[配對](/zh-TW/channels/pairing)
- 僅 UUID 的傳送者（來自 `sourceUuid`）會以 `uuid:<id>` 儲存在 `channels.signal.allowFrom`。
群組：
- `channels.signal.groupPolicy = open | allowlist | disabled`。
- 當設定為 `allowlist` 時，`channels.signal.groupAllowFrom` 控制誰可以在群組中觸發。
- `channels.signal.groups["<group-id>" | "*"]` 可以使用 `requireMention`、`tools` 和 `toolsBySender` 覆寫群組行為。
- 在多帳號設定中，使用 `channels.signal.accounts.<id>.groups` 設定每個帳號的覆寫。
- 執行階段注意事項：如果完全缺少 `channels.signal`，執行階段會針對群組檢查回退到 `groupPolicy="allowlist"`（即使已設定 `channels.defaults.groupPolicy`）。
- `channels.signal.groupAllowFrom` 控制在設定 `allowlist` 時，哪些群組或傳送者可觸發群組回覆；項目可以是 Signal 群組 ID（原始值、`group:<id>` 或 `signal:group:<id>`）、傳送者電話號碼、`uuid:<id>` 值或 `*`。
- `channels.signal.groups["<group-id>" | "*"]` 可使用 `requireMention`、`tools` 和 `toolsBySender` 覆寫群組行為。
- 在多帳號設定中，使用 `channels.signal.accounts.<id>.groups` 進行每個帳號的覆寫。
- 透過 `groupAllowFrom` 將 Signal 群組加入允許清單，本身不會停用提及閘控。特別設定的 `channels.signal.groups["<group-id>"]` 項目會處理每則群組訊息，除非設定 `requireMention=true`。
- 執行階段注意事項：如果完全缺少 `channels.signal`，執行階段會針對群組檢查退回到 `groupPolicy="allowlist"`（即使已設定 `channels.defaults.groupPolicy`）。
## 運作方式（行為）
- `signal-cli` 以 daemon 形式執行；Gateway 透過 SSE 讀取事件。
- 傳入訊息會正規化為共享頻道 envelope。
- `signal-cli` 會以常駐程式執行；Gateway 透過 SSE 讀取事件。
- 傳入訊息會正規化為共享通道信封。
- 回覆一律路由回相同號碼或群組。
## 媒體 + 限制
- 傳出文字會切分到 `channels.signal.textChunkLimit`（預設 4000）。
- 選用換行切分：設定 `channels.signal.chunkMode="newline"`，先依空白行（段落邊界）切分，再依長度切分。
- 傳出文字會依 `channels.signal.textChunkLimit` 分段（預設 4000）。
- 選用換行分段：設定 `channels.signal.chunkMode="newline"`，即可在長度分段前先依空白行（段落邊界）切分。
- 支援附件（從 `signal-cli` 擷取 base64）。
- 當缺少 `contentType` 時，語音備忘附件會使用 `signal-cli` 檔名作為 MIME 後備，因此音訊轉錄仍可分類 AAC 語音備忘。
- 語音備忘附件會在缺少 `contentType` 時，使用 `signal-cli` 檔名作為 MIME 後援，因此音訊轉錄仍可分類 AAC 語音備忘。
- 預設媒體上限：`channels.signal.mediaMaxMb`（預設 8）。
- 使用 `channels.signal.ignoreAttachments` 跳過下載媒體。
- 群組歷史情境使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），並回退到 `messages.groupChat.historyLimit`。設定為 `0` 可停用（預設 50）。
- 使用 `channels.signal.ignoreAttachments` 跳過媒體下載。
- 群組歷史脈絡使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），並退回到 `messages.groupChat.historyLimit`。設定為 `0` 可停用（預設 50）。
## 輸入中 + 已讀回條
## 輸入狀態 + 已讀回條
- **輸入指示器**：OpenClaw 透過 `signal-cli sendTyping` 傳送輸入訊號，並在回覆執行期間持續刷新。
- **已讀回條**：當 `channels.signal.sendReadReceipts` 為 true 時，OpenClaw 會為允許的私訊轉發已讀回條。
- **輸入狀態指示器**：OpenClaw 透過 `signal-cli sendTyping` 傳送輸入狀態訊號，並在回覆執行期間重新整理。
- **已讀回條**：當 `channels.signal.sendReadReceipts` 為 true 時，OpenClaw 會轉送允許私訊的已讀回條。
- Signal-cli 不會公開群組的已讀回條。
## 反應（訊息工具）
- 使用 `message action=react` 搭配 `channel=signal`。
- 目標：傳送者 E.164 或 UUID（使用配對輸出中的 `uuid:<id>`；裸 UUID 也可）。
- `messageId` 是你要反應的訊息的 Signal 時間戳。
- 目標：傳送者 E.164 或 UUID（使用配對輸出的 `uuid:<id>`；裸 UUID 也可使用）。
- `messageId` 是你要反應之訊息的 Signal 時間戳記。
- 群組反應需要 `targetAuthor` 或 `targetAuthorUuid`。
範例：
@ -247,11 +248,11 @@ message action=react channel=signal target=signal:group:<groupId> targetAuthor=u
- `channels.signal.actions.reactions`：啟用/停用反應動作（預設 true）。
- `channels.signal.reactionLevel`：`off | ack | minimal | extensive`。
- `off`/`ack` 會停用 agent 反應（訊息工具 `react` 會出錯）。
- `minimal`/`extensive` 會啟用 agent 反應並設定指引層級。
- `off`/`ack` 會停用代理反應（訊息工具 `react` 會發生錯誤）。
- `minimal`/`extensive` 會啟用代理反應並設定指引層級。
- 每個帳號的覆寫：`channels.signal.accounts.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
## 傳送目標（CLI/Cron）
## 傳遞目標（CLI/Cron）
- 私訊：`signal:+15551234567`（或純 E.164）。
- UUID 私訊：`uuid:<id>`（或裸 UUID）。
@ -260,7 +261,7 @@ message action=react channel=signal target=signal:group:<groupId> targetAuthor=u
## 疑難排解
先執行此階梯：
請先執行這個階梯：
```bash
openclaw status
@ -270,7 +271,7 @@ openclaw doctor
openclaw channels status --probe
```
必要時再確認私訊配對狀態：
然後視需要確認私訊配對狀態：
```bash
openclaw pairing list signal
@ -278,9 +279,9 @@ openclaw pairing list signal
常見失敗：
- Daemon 可連線但沒有回覆：確認帳號/daemon 設定（`httpUrl`、`account`）與接收模式。
- 常駐程式可連線但沒有回覆：驗證帳號/常駐程式設定（`httpUrl`、`account`）和接收模式。
- 私訊被忽略：傳送者正在等待配對核准。
- 群組訊息被忽略：群組傳送者/提及閘控阻擋了傳送。
- 群組訊息被忽略：群組傳送者/提及閘控阻擋傳遞。
- 編輯後出現設定驗證錯誤：執行 `openclaw doctor --fix`。
- 診斷中缺少 Signal：確認 `channels.signal.enabled: true`。
@ -292,14 +293,14 @@ pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20
```
分流流程：[/channels/troubleshooting](/zh-TW/channels/troubleshooting)。
分級診斷流程：[/channels/troubleshooting](/zh-TW/channels/troubleshooting)。
## 安全性注意事項
## 安全注意事項
- `signal-cli` 會將帳號金鑰儲存在本機（通常是 `~/.local/share/signal-cli/data/`）。
- 伺服器遷移或重建前，請備份 Signal 帳號狀態。
- 除非你明確想要更廣泛的私訊存取，否則請保留 `channels.signal.dmPolicy: "pairing"`。
- 簡訊驗證只在註冊或復原流程需要，但失去對號碼/帳號的控制可能會讓重新註冊變得複雜。
- SMS 驗證只在註冊或復原流程中需要，但失去該號碼/帳號的控制權可能會讓重新註冊變得複雜。
## 設定參考（Signal）
@ -307,39 +308,39 @@ grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20
提供者選項：
- `channels.signal.enabled`: 啟用/停用頻道啟動。
- `channels.signal.account`: bot 帳號的 E.164。
- `channels.signal.cliPath`: `signal-cli` 的路徑。
- `channels.signal.httpUrl`: 完整的常駐程式 URL（覆寫 host/port）。
- `channels.signal.httpHost`, `channels.signal.httpPort`: 常駐程式繫結（預設 127.0.0.1:8080）。
- `channels.signal.autoStart`: 自動產生常駐程式（若未設定 `httpUrl`，預設為 true）。
- `channels.signal.startupTimeoutMs`: 啟動等待逾時，單位為毫秒（上限 120000）。
- `channels.signal.receiveMode`: `on-start | manual`。
- `channels.signal.ignoreAttachments`: 略過附件下載。
- `channels.signal.ignoreStories`: 忽略來自常駐程式的動態。
- `channels.signal.sendReadReceipts`: 轉送已讀回條。
- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled`（預設：pairing）。
- `channels.signal.allowFrom`: DM 允許清單（E.164 或 `uuid:<id>`）。`open` 需要 `"*"`。Signal 沒有使用者名稱；請使用電話/UUID ID。
- `channels.signal.groupPolicy`: `open | allowlist | disabled`（預設：allowlist）。
- `channels.signal.groupAllowFrom`: 群組傳送者允許清單。
- `channels.signal.groups`: 依 Signal 群組 ID（或 `"*"`）設定的個別群組覆寫。支援的欄位：`requireMention`、`tools`、`toolsBySender`。
- `channels.signal.accounts.<id>.groups`: 多帳號設定中，`channels.signal.groups` 的個別帳號版本。
- `channels.signal.historyLimit`: 要納入上下文的群組訊息上限（0 表示停用）。
- `channels.signal.dmHistoryLimit`: 以使用者回合數計算的 DM 歷史記錄限制。個別使用者覆寫：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
- `channels.signal.textChunkLimit`: 傳出分段大小（字元）。
- `channels.signal.chunkMode`: `length`（預設）或 `newline`，可在依長度分段前先按空白行（段落邊界）分割。
- `channels.signal.mediaMaxMb`: 傳入/傳出媒體上限（MB）。
- `channels.signal.enabled`：啟用/停用頻道啟動。
- `channels.signal.account`：機器人帳號的 E.164。
- `channels.signal.cliPath`：`signal-cli` 的路徑。
- `channels.signal.httpUrl`：完整的 daemon URL（覆寫主機/連接埠）。
- `channels.signal.httpHost`、`channels.signal.httpPort`：daemon 綁定（預設 127.0.0.1:8080）。
- `channels.signal.autoStart`：自動產生 daemon（若未設定 `httpUrl`，預設為 true）。
- `channels.signal.startupTimeoutMs`：啟動等待逾時，單位為毫秒（上限 120000）。
- `channels.signal.receiveMode`：`on-start | manual`。
- `channels.signal.ignoreAttachments`：略過附件下載。
- `channels.signal.ignoreStories`：忽略來自 daemon 的限時動態。
- `channels.signal.sendReadReceipts`：轉送已讀回條。
- `channels.signal.dmPolicy`：`pairing | allowlist | open | disabled`（預設：pairing）。
- `channels.signal.allowFrom`：私訊允許清單（E.164 或 `uuid:<id>`）。`open` 需要 `"*"`。Signal 沒有使用者名稱；請使用電話/UUID ID。
- `channels.signal.groupPolicy`：`open | allowlist | disabled`（預設：allowlist）。
- `channels.signal.groupAllowFrom`：群組允許清單；接受 Signal 群組 ID（原始格式、`group:<id>` 或 `signal:group:<id>`）、傳送者 E.164 號碼，或 `uuid:<id>` 值。
- `channels.signal.groups`：依 Signal 群組 ID（或 `"*"`）鍵入的逐群組覆寫。支援欄位：`requireMention`、`tools`、`toolsBySender`。
- `channels.signal.accounts.<id>.groups`：多帳號設定中 `channels.signal.groups` 的逐帳號版本。
- `channels.signal.historyLimit`：作為上下文納入的群組訊息數量上限（0 會停用）。
- `channels.signal.dmHistoryLimit`：以使用者回合計算的私訊記錄上限。逐使用者覆寫：`channels.signal.dms["<phone_or_uuid>"].historyLimit`。
- `channels.signal.textChunkLimit`：傳出分塊大小（字元）。
- `channels.signal.chunkMode`：`length`（預設）或 `newline`，先依空白行（段落邊界）分割，再依長度分塊。
- `channels.signal.mediaMaxMb`：傳入/傳出媒體上限（MB）。
相關全域選項：
- `agents.list[].groupChat.mentionPatterns`（Signal 不支援原生提及）。
- `messages.groupChat.mentionPatterns`（全域後援）。
- `messages.groupChat.mentionPatterns`（全域備援）。
- `messages.responsePrefix`。
## 相關
- [頻道總覽](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [頻道概觀](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — 私訊驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及門檻
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

407
docs/zh-TW/channels/slack.md
View File

@ -1,28 +1,28 @@
---
read_when:
- 設定 Slack 或偵錯 Slack socket/HTTP 模式
summary: Slack 設定與執行階段行為（Socket 模式 + HTTP 請求網址）
- 設定 Slack 或偵錯 Slack 通訊端/HTTP 模式
summary: Slack 設定與執行階段行為（Socket 模式 + HTTP 請求 URL）
title: Slack
x-i18n:
generated_at: "2026-04-30T02:49:07Z"
generated_at: "2026-04-30T16:27:44Z"
model: gpt-5.5
provider: openai
source_hash: 08024bd947ddeb00a1ab3aaa3864cf31817303bbc0523902acdc539fc662e127
source_hash: 55beddb43a6b91c6853dcf053eab713322de4da5beced7c107d73e1c066fded6
source_path: channels/slack.md
workflow: 16
---
可透過 Slack app 整合用於 DM 和頻道，並已達生產就緒。預設模式是 Socket Mode；也支援 HTTP Request URLs。
Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/zh-TW/channels/pairing">
Slack DM 預設使用配對模式。
Slack DMs 預設使用配對模式。
</Card>
<Card title="Slash commands" icon="terminal" href="/zh-TW/tools/slash-commands">
原生命令行為與命令目錄。
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/zh-TW/channels/troubleshooting">
跨頻道診斷與修復手冊。
跨通道診斷與修復操作手冊。
</Card>
</CardGroup>
@ -34,9 +34,9 @@ x-i18n:
<Step title="Create a new Slack app">
在 Slack app 設定中按下 **[Create New App](https://api.slack.com/apps/new)** 按鈕：
- 選擇 **from a manifest**，並為你的 app 選取工作區
- 貼上下面的[範例 manifest](#manifest-and-scope-checklist)，並繼續建立
- 產生具備 `connections:write` 的 **App-Level Token** (`xapp-...`)
- 選擇 **from a manifest**，並為你的 app 選取一個工作區
- 貼上下方的[範例 manifest](#manifest-and-scope-checklist)，然後繼續建立
- 產生具有 `connections:write` 的 **App-Level Token** (`xapp-...`)
- 安裝 app，並複製顯示的 **Bot Token** (`xoxb-...`)
</Step>
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5
```
env 後備方式（僅限預設帳戶）：
Env 後援（僅限預設帳戶）：
```bash
SLACK_APP_TOKEN=xapp-...
@ -89,9 +89,9 @@ openclaw gateway
<Step title="Create a new Slack app">
在 Slack app 設定中按下 **[Create New App](https://api.slack.com/apps/new)** 按鈕：
- 選擇 **from a manifest**，並為你的 app 選取工作區
- 選擇 **from a manifest**，並為你的 app 選取一個工作區
- 貼上[範例 manifest](#manifest-and-scope-checklist)，並在建立前更新 URL
- 儲存用於要求驗證的 **Signing Secret**
- 儲存 **Signing Secret** 以進行請求驗證
- 安裝 app，並複製顯示的 **Bot Token** (`xoxb-...`)
</Step>
@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5
```
<Note>
多帳戶 HTTP 請使用唯一的 Webhook 路徑
為多帳戶 HTTP 使用唯一的 webhook 路徑
為每個帳戶指定不同的 `webhookPath`（預設為 `/slack/events`），避免註冊互相衝突。
為每個帳戶指定不同的 `webhookPath`（預設 `/slack/events`），讓註冊不會互相衝突。
</Note>
</Step>
@ -142,7 +142,7 @@ openclaw gateway
## Socket Mode 傳輸調整
OpenClaw 預設會將 Socket Mode 的 Slack SDK 用戶端 pong 逾時設為 15 秒。只有在需要針對工作區或主機進行特定調整時，才覆寫傳輸設定：
OpenClaw 預設會將 Slack SDK 用戶端的 Socket Mode pong 逾時設為 15 秒。只有在需要針對工作區或主機進行特定調整時，才覆寫傳輸設定：
```json5
{
@ -159,11 +159,11 @@ OpenClaw 預設會將 Socket Mode 的 Slack SDK 用戶端 pong 逾時設為 15
}
```
只有在 Socket Mode 工作區記錄 Slack websocket pong/server-ping 逾時，或在已知事件迴圈飢餓的主機上執行時，才使用此設定。`clientPingTimeout` 是 SDK 傳送用戶端 ping 後等待 pong 的時間；`serverPingTimeout` 是等待 Slack 伺服器 ping 的時間。App 訊息與事件仍是應用程式狀態，不是傳輸活性訊號。
僅在會記錄 Slack websocket pong/server-ping 逾時的 Socket Mode 工作區，或在已知有事件迴圈飢餓問題的主機上使用此設定。`clientPingTimeout` 是 SDK 傳送用戶端 ping 後等待 pong 的時間；`serverPingTimeout` 是等待 Slack 伺服器 ping 的時間。App 訊息與事件仍是應用程式狀態，而不是傳輸存活訊號。
## Manifest 與 scope 檢查清單
Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只有 `settings` 區塊（以及 slash command 的 `url`）不同。
基礎 Slack app manifest 對 Socket Mode 和 HTTP Request URLs 都相同。只有 `settings` 區塊（以及 slash command 的 `url`）不同。
基礎 manifest（Socket Mode 預設）：
@ -269,17 +269,17 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只
### 其他 manifest 設定
呈現擴充上述預設值的不同功能。
呈現會擴充上述預設值的不同功能。
<AccordionGroup>
<Accordion title="Optional native slash commands">
可使用多個[原生 slash commands](#commands-and-slash-behavior)，取代單一已設定命令，並有以下細節：
可使用多個[原生 slash commands](#commands-and-slash-behavior)，以細緻差異取代單一設定命令：
- 使用 `/agentstatus` 而不是 `/status`，因為 `/status` 命令已保留。
- 一次最多只能提供 25 個 slash commands。
將現有的 `features.slash_commands` 區段替換為[可用命令](/zh-TW/tools/slash-commands#command-list)的子集：
請將現有的 `features.slash_commands` 區段替換為[可用命令](/zh-TW/tools/slash-commands#command-list)的子集：
<Tabs>
<Tab title="Socket Mode (default)">
@ -399,7 +399,7 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只
</Tab>
<Tab title="HTTP Request URLs">
使用與上方 Socket Mode 相同的 `slash_commands` 清單，並在每個項目加上 `"url": "https://gateway-host.example.com/slack/events"`。範例：
使用上方與 Socket Mode 相同的 `slash_commands` 清單，並在每個項目加上 `"url": "https://gateway-host.example.com/slack/events"`。範例：
```json
"slash_commands": [
@ -423,13 +423,13 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只
</Accordion>
<Accordion title="Optional authorship scopes (write operations)">
如果你希望外送訊息使用作用中代理的身分（自訂使用者名稱與圖示），而不是預設 Slack app 身分，請新增 `chat:write.customize` bot scope。
如果你希望外送訊息使用作用中代理的身分（自訂使用者名稱與圖示），而不是預設 Slack app 身分，請加入 `chat:write.customize` bot scope。
如果使用 emoji 圖示，Slack 會預期採用 `:emoji_name:` 語法。
如果你使用 emoji 圖示，Slack 會預期 `:emoji_name:` 語法。
</Accordion>
<Accordion title="Optional user-token scopes (read operations)">
如果你設定 `channels.slack.userToken`，典型的讀取 scope 包括：
如果你設定 `channels.slack.userToken`，常見的讀取 scope 為：
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -437,7 +437,7 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read`（如果你依賴 Slack 搜尋讀取）
- `search:read`（如果你仰賴 Slack 搜尋讀取）
</Accordion>
</AccordionGroup>
@ -446,34 +446,34 @@ Socket Mode 和 HTTP Request URLs 使用相同的基礎 Slack app manifest。只
- Socket Mode 需要 `botToken` + `appToken`。
- HTTP 模式需要 `botToken` + `signingSecret`。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受純文字
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文
字串或 SecretRef 物件。
- 設定權杖會覆寫環境變數備援。
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 環境變數備援只套用於預設帳戶。
- `userToken` (`xoxp-...`) 只能透過設定提供（沒有環境變數備援），並預設為唯讀行為 (`userTokenReadOnly: true`)。
- 設定中的 token 會覆寫環境變數後援。
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 環境變數後援只套用於預設帳號。
- `userToken` (`xoxp-...`) 僅限設定使用（無環境變數後援），且預設為唯讀行為 (`userTokenReadOnly: true`)。
狀態快照行為：
- Slack 帳戶檢查會追蹤每個憑證的 `*Source` 和 `*Status`
- Slack 帳號檢查會追蹤每個憑證的 `*Source` 和 `*Status`
欄位（`botToken`、`appToken`、`signingSecret`、`userToken`）。
- 狀態為 `available`、`configured_unavailable` 或 `missing`。
- `configured_unavailable` 表示帳戶是透過 SecretRef
或其他非內嵌祕密來源設定，但目前的命令/執行階段路徑
- `configured_unavailable` 表示帳號已透過 SecretRef
或其他非行內秘密來源設定，但目前的命令/執行階段路徑
無法解析實際值。
- 在 HTTP 模式中會包含 `signingSecretStatus`；在 Socket Mode 中，
必要配對是 `botTokenStatus` + `appTokenStatus`。
<Tip>
對於動作/目錄讀取，已設定時可優先使用使用者權杖。對於寫入，仍優先使用機器人權杖；只有在 `userTokenReadOnly: false` 且機器人權杖不可用時，才允許使用使用者權杖寫入。
對於動作/目錄讀取，設定後可優先使用使用者 token。對於寫入，仍優先使用 bot token；只有在 `userTokenReadOnly: false` 且 bot token 無法使用時，才允許使用者 token 寫入。
</Tip>
## 動作與閘門
## 動作和閘門
Slack 動作由 `channels.slack.actions.*` 控制。
目前 Slack 工具中可用的動作群組：
| 群組 | 預設值 |
| 群組 | 預設值 |
| ---------- | ------- |
| messages | 已啟用 |
| reactions | 已啟用 |
@ -481,9 +481,9 @@ Slack 動作由 `channels.slack.actions.*` 控制。
| memberInfo | 已啟用 |
| emojiList | 已啟用 |
目前 Slack 訊息動作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受傳入檔案佔位符中顯示的 Slack 檔案 ID，並針對圖片回傳圖片預覽，或針對其他檔案類型回傳本機檔案中繼資料。
目前 Slack 訊息動作包含 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站檔案佔位符中顯示的 Slack 檔案 ID，並針對圖片傳回圖片預覽，或針對其他檔案類型傳回本機檔案中繼資料。
## 存取控制與路由
## 存取控制和路由
<Tabs>
<Tab title="DM 政策">
@ -496,19 +496,19 @@ Slack 動作由 `channels.slack.actions.*` 控制。
DM 旗標：
- `dm.enabled`（預設為 true）
- `dm.enabled`（預設 true）
- `channels.slack.allowFrom`
- `dm.allowFrom`（舊版）
- `dm.groupEnabled`（群組 DM 預設為 false）
- `dm.groupEnabled`（群組 DM 預設 false）
- `dm.groupChannels`（選用 MPIM 允許清單）
多帳戶優先順序：
多帳號優先順序：
- `channels.slack.accounts.default.allowFrom` 只套用於 `default` 帳戶。
- 具名帳戶在本身的 `allowFrom` 未設定時，會繼承 `channels.slack.allowFrom`。
- 具名帳戶不會繼承 `channels.slack.accounts.default.allowFrom`。
- `channels.slack.accounts.default.allowFrom` 只套用於 `default` 帳號。
- 命名帳號在自己的 `allowFrom` 未設定時，會繼承 `channels.slack.allowFrom`。
- 命名帳號不會繼承 `channels.slack.accounts.default.allowFrom`。
為相容性仍會讀取舊版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom`。`openclaw doctor --fix` 會在不變更存取權的情況下，將其遷移到 `dmPolicy` 和 `allowFrom`。
舊版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍會讀取以維持相容性。`openclaw doctor --fix` 會在不變更存取權的情況下，盡可能將它們遷移到 `dmPolicy` 和 `allowFrom`。
DM 中的配對使用 `openclaw pairing approve slack <code>`。
@ -523,18 +523,18 @@ Slack 動作由 `channels.slack.actions.*` 控制。
頻道允許清單位於 `channels.slack.channels` 底下，且**必須使用穩定的 Slack 頻道 ID**（例如 `C12345678`）作為設定鍵。
執行階段注意事項：如果 `channels.slack` 完全缺少（僅使用環境變數設定），執行階段會退回到 `groupPolicy="allowlist"` 並記錄警告（即使已設定 `channels.defaults.groupPolicy`）。
執行階段注意事項：如果完全缺少 `channels.slack`（僅環境變數設定），執行階段會退回到 `groupPolicy="allowlist"` 並記錄警告（即使已設定 `channels.defaults.groupPolicy`）。
名稱/ID 解析：
- 頻道允許清單項目和 DM 允許清單項目會在啟動時於權杖存取允許時解析
- 未解析的頻道名稱項目會保留為已設定狀態，但預設會在路由時忽略
- 傳入授權與頻道路由預設以 ID 優先；直接使用者名稱/代稱比對需要 `channels.slack.dangerouslyAllowNameMatching: true`
- 當 token 存取允許時，頻道允許清單項目和 DM 允許清單項目會在啟動時解析
- 無法解析的頻道名稱項目會保留為已設定狀態，但預設會在路由時忽略
- 入站授權和頻道路由預設以 ID 優先；直接使用者名稱/slug 比對需要 `channels.slack.dangerouslyAllowNameMatching: true`
<Warning>
以名稱為基礎的鍵（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不會**相符。頻道查找預設以 ID 優先，因此以名稱為基礎的鍵永遠無法成功路由，該頻道中的所有訊息都會被靜默封鎖。這不同於 `groupPolicy: "open"`，在該模式中路由不需要頻道鍵，因此以名稱為基礎的鍵看起來可用。
在 `groupPolicy: "allowlist"` 下，基於名稱的鍵（`#channel-name` 或 `channel-name`）**不會**比對。頻道查找預設以 ID 優先，因此基於名稱的鍵永遠無法成功路由，該頻道中的所有訊息都會被靜默封鎖。這不同於 `groupPolicy: "open"`，後者不需要頻道鍵即可路由，且基於名稱的鍵看起來會正常運作。
一律使用 Slack 頻道 ID 作為鍵。尋找方式：在 Slack 中以右鍵點選頻道 → **複製連結** — ID (`C...`) 會出現在 URL 結尾。
一律使用 Slack 頻道 ID 作為鍵。尋找方式：在 Slack 中對頻道按右鍵 → **複製連結** — ID (`C...`) 會出現在 URL 結尾。
正確：
@ -551,7 +551,7 @@ Slack 動作由 `channels.slack.actions.*` 控制。
}
```
不正確（在 `groupPolicy: "allowlist"` 下會被靜默封鎖）：
錯誤（在 `groupPolicy: "allowlist"` 下會被靜默封鎖）：
```json5
{
@ -569,16 +569,16 @@ Slack 動作由 `channels.slack.actions.*` 控制。
</Tab>
<Tab title="提及與頻道使用者">
頻道訊息預設以提及作為門檻。
<Tab title="提及和頻道使用者">
頻道訊息預設受提及閘門控管。
提及來源：
- 明確的應用程式提及（`<@botId>`）
- 提及正則表示式模式（`agents.list[].groupChat.mentionPatterns`，備援為 `messages.groupChat.mentionPatterns`）
- 隱含的回覆機器人執行緒行為（當 `thread.requireExplicitMention` 為 `true` 時停用）
- 明確 app 提及 (`<@botId>`)
- 提及 regex 模式 (`agents.list[].groupChat.mentionPatterns`，後援 `messages.groupChat.mentionPatterns`)
- 隱含回覆 bot 的執行緒行為（當 `thread.requireExplicitMention` 為 `true` 時停用）
個別頻道控制項（`channels.slack.channels.<id>`；名稱只能透過啟動解析或 `dangerouslyAllowNameMatching` 使用）：
每個頻道控制項（`channels.slack.channels.<id>`；名稱僅透過啟動解析或 `dangerouslyAllowNameMatching`）：
- `requireMention`
- `users`（允許清單）
@ -587,26 +587,28 @@ Slack 動作由 `channels.slack.actions.*` 控制。
- `systemPrompt`
- `tools`、`toolsBySender`
- `toolsBySender` 鍵格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 萬用字元
（舊版未加前綴的鍵仍只會對應到 `id:`）
（舊版未加前綴的鍵仍只對應到 `id:`）
`allowBots` 對頻道和私人頻道採保守策略：只有當傳送的 bot 明確列在該房間的 `users` 允許清單中，或來自 `channels.slack.allowFrom` 的至少一個明確 Slack 擁有者 ID 目前是房間成員時，才接受 bot 撰寫的房間訊息。萬用字元和顯示名稱擁有者項目不滿足擁有者在場條件。擁有者在場使用 Slack `conversations.members`；請確保 app 具有對應房間類型的相符讀取 scope（公開頻道為 `channels:read`，私人頻道為 `groups:read`）。如果成員查找失敗，OpenClaw 會捨棄 bot 撰寫的房間訊息。
</Tab>
</Tabs>
## 執行緒、工作階段與回覆標籤
## 執行緒、工作階段和回覆標籤
- DM 會路由為 `direct`；頻道為 `channel`；MPIM 為 `group`。
- 使用預設 `session.dmScope=main` 時，Slack DM 會收斂到代理主工作階段。
- 使用預設 `session.dmScope=main` 時，Slack DM 會收合到代理的主工作階段。
- 頻道工作階段：`agent:<agentId>:slack:channel:<channelId>`。
- 適用時，執行緒回覆可以建立執行緒工作階段後綴（`:thread:<threadTs>`）。
- 執行緒回覆在適用時可以建立執行緒工作階段尾碼（`:thread:<threadTs>`）。
- `channels.slack.thread.historyScope` 預設為 `thread`；`thread.inheritParent` 預設為 `false`。
- `channels.slack.thread.initialHistoryLimit` 控制新執行緒工作階段開始時會擷取多少現有執行緒訊息（預設 `20`；設為 `0` 可停用）。
- `channels.slack.thread.requireExplicitMention`（預設 `false`）：當為 `true` 時，會抑制隱含的執行緒提及，因此機器人只會回應執行緒內明確的 `@bot` 提及，即使機器人已參與該執行緒也是如此。若沒有此設定，機器人已參與執行緒中的回覆會繞過 `requireMention` 門檻。
- `channels.slack.thread.initialHistoryLimit` 控制新執行緒工作階段啟動時要擷取多少既有執行緒訊息（預設 `20`；設為 `0` 可停用）。
- `channels.slack.thread.requireExplicitMention`（預設 `false`）：當為 `true` 時，會抑制隱含執行緒提及，因此 bot 只會回應執行緒內明確的 `@bot` 提及，即使 bot 已參與該執行緒。若沒有此設定，在 bot 已參與的執行緒中回覆會略過 `requireMention` 閘門控管。
回覆執行緒控制項：
- `channels.slack.replyToMode`：`off|first|all|batched`（預設 `off`）
- `channels.slack.replyToModeByChatType`：依 `direct|group|channel`
- 直接聊天的舊版備援：`channels.slack.dm.replyToMode`
- `channels.slack.replyToMode`: `off|first|all|batched`（預設 `off`）
- `channels.slack.replyToModeByChatType`: 依 `direct|group|channel` 設定
- 直接聊天的舊版後援：`channels.slack.dm.replyToMode`
支援手動回覆標籤：
@ -614,45 +616,45 @@ Slack 動作由 `channels.slack.actions.*` 控制。
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` 會停用 Slack 中的**所有**回覆執行緒，包括明確的 `[[reply_to_*]]` 標籤。這與 Telegram 不同，在 Telegram 中，明確標籤在 `"off"` 模式下仍會被採用。Slack 執行緒會將訊息從頻道中隱藏，而 Telegram 回覆會保持行內可見。
`replyToMode="off"` 會停用 Slack 中**所有**回覆執行緒，包括明確的 `[[reply_to_*]]` 標籤。這不同於 Telegram，後者在 `"off"` 模式下仍會遵循明確標籤。Slack 執行緒會從頻道中隱藏訊息，而 Telegram 回覆會維持在行內可見。
</Note>
## 確認反應
## Ack reaction
`ackReaction` 會在 OpenClaw 處理傳入訊息時傳送確認 emoji。
`ackReaction` 會在 OpenClaw 處理入站訊息時傳送確認 emoji。
解析順序：
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- 代理身分 emoji 備援（`agents.list[].identity.emoji`，否則為 "👀"）
- 代理身分 emoji 後援（`agents.list[].identity.emoji`，否則為 "👀"）
注意事項：
- Slack 預期使用短碼（例如 `"eyes"`）。
- 使用 `""` 可停用 Slack 帳戶或全域的反應。
- Slack 預期使用 shortcode（例如 `"eyes"`）。
- 使用 `""` 可停用 Slack 帳號或全域的 reaction。
## 文字串流
`channels.slack.streaming` 控制即時預覽行為：
- `off`：停用即時預覽串流。
- `partial`（預設）：以最新的部分輸出取代預覽文字。
- `block`：附加分塊預覽更新。
- `progress`：產生時顯示進度狀態文字，然後傳送最終文字。
- `streaming.preview.toolProgress`：當草稿預覽啟用時，將工具/進度更新路由到同一則已編輯的預覽訊息中（預設：`true`）。設為 `false` 可保留獨立的工具/進度訊息。
- `partial`（預設）：用最新的部分輸出取代預覽文字。
- `block`：附加分塊的預覽更新。
- `progress`：產生期間顯示進度狀態文字，然後傳送最終文字。
- `streaming.preview.toolProgress`：當草稿預覽啟用時，將工具/進度更新路由到同一則已編輯的預覽訊息中（預設：`true`）。設為 `false` 可保留個別工具/進度訊息。
當 `channels.slack.streaming.mode` 為 `partial` 時，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文字串流（預設：`true`）。
- 必須有可用的回覆執行緒，才會顯示原生文字串流和 Slack 助理執行緒狀態。執行緒選擇仍遵循 `replyToMode`。
- 當原生串流不可用時，頻道和群組聊天根訊息仍可使用一般草稿預覽。
- 頂層 Slack DM 預設不在執行緒中，因此不會顯示執行緒樣式預覽；如果你想在那裡顯示可見進度，請使用執行緒回覆或 `typingReaction`。
- 媒體和非文字承載會退回一般傳遞。
- 媒體/錯誤最終訊息會取消待處理的預覽編輯；符合條件的文字/區塊最終訊息只有在能就地編輯預覽時才會清出。
- 如果串流在回覆中途失敗，OpenClaw 會針對剩餘承載退回一般傳遞。
- 必須有可用的回覆執行緒，原生文字串流和 Slack 助理執行緒狀態才會出現。執行緒選擇仍遵循 `replyToMode`。
- 當原生串流無法使用時，頻道和群組聊天根訊息仍可使用一般草稿預覽。
- 頂層 Slack DM 預設不在執行緒中，因此不會顯示執行緒樣式預覽；如果想在那裡顯示可見進度，請使用執行緒回覆或 `typingReaction`。
- 媒體和非文字 payload 會退回到一般傳遞。
- 媒體/錯誤最終訊息會取消待處理的預覽編輯；符合條件的文字/區塊最終訊息只有在能就地編輯預覽時才會 flush。
- 如果串流在回覆中途失敗，OpenClaw 會對剩餘 payload 退回到一般傳遞。
使用草稿預覽而非 Slack 原生文字串流：
使用草稿預覽而不是 Slack 原生文字串流：
```json5
{
@ -670,12 +672,12 @@ Slack 動作由 `channels.slack.actions.*` 控制。
舊版鍵：
- `channels.slack.streamMode` (`replace | status_final | append`) 會自動遷移到 `channels.slack.streaming.mode`。
- 布林值 `channels.slack.streaming` 會自動遷移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
- boolean `channels.slack.streaming` 會自動遷移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
- 舊版 `channels.slack.nativeStreaming` 會自動遷移到 `channels.slack.streaming.nativeTransport`。
## 輸入中反應備援
## Typing reaction 後援
`typingReaction` 會在 OpenClaw 處理回覆時，對傳入的 Slack 訊息新增暫時反應，然後在執行完成時移除。這在執行緒回覆之外最有用，因為執行緒回覆會使用預設的「正在輸入...」狀態指示器。
`typingReaction` 會在 OpenClaw 處理回覆時，為入站 Slack 訊息新增暫時 reaction，並在執行完成時移除。這在執行緒回覆以外最有用，因為執行緒回覆會使用預設的「正在輸入...」狀態指示器。
解析順序：
@ -684,43 +686,43 @@ Slack 動作由 `channels.slack.actions.*` 控制。
注意事項：
- Slack 預期使用短碼（例如 `"hourglass_flowing_sand"`）。
- 此反應是盡力而為，並會在回覆或失敗路徑完成後自動嘗試清理。
- Slack 預期使用 shortcode（例如 `"hourglass_flowing_sand"`）。
- reaction 會以 best-effort 方式處理，並會在回覆或失敗路徑完成後自動嘗試清理。
## 媒體、分塊與傳遞
## 媒體、分塊和傳遞
<AccordionGroup>
<Accordion title="傳入附件">
Slack 檔案附件會從 Slack 託管的私人 URL 下載（以權杖驗證的請求流程），並在擷取成功且大小限制允許時寫入媒體儲存區。檔案佔位符包含 Slack `fileId`，讓代理可以透過 `download-file` 擷取原始檔案。
<Accordion title="入站附件">
Slack 檔案附件會從 Slack 代管的私人 URL 下載（token 驗證請求流程），並在擷取成功且大小限制允許時寫入媒體儲存區。檔案佔位符包含 Slack `fileId`，因此代理可以使用 `download-file` 擷取原始檔案。
下載會使用有界的閒置與總逾時。如果 Slack 檔案擷取停滯或失敗，OpenClaw 會繼續處理訊息，並退回到檔案佔位符。
下載使用有界限的閒置和總逾時。如果 Slack 檔案擷取停滯或失敗，OpenClaw 會繼續處理訊息，並退回到檔案佔位符。
執行階段傳入大小上限預設為 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆寫。
執行階段入站大小上限預設為 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆寫。
</Accordion>
<Accordion title="傳出文字與檔案">
- 文字分塊使用 `channels.slack.textChunkLimit`（預設 4000）
- `channels.slack.chunkMode="newline"` 啟用段落優先切分
- 檔案傳送使用 Slack 上傳 API，並可包含執行緒回覆（`thread_ts`）
- 設定後，傳出媒體上限會遵循 `channels.slack.mediaMaxMb`；否則頻道傳送會使用媒體管線中的 MIME 類型預設值
<Accordion title="傳出文字和檔案">
- 文字區塊使用 `channels.slack.textChunkLimit`（預設 4000）
- `channels.slack.chunkMode="newline"` 會啟用段落優先分割
- 檔案傳送使用 Slack 上傳 API，並可包含討論串回覆（`thread_ts`）
- 設定時，傳出媒體上限會遵循 `channels.slack.mediaMaxMb`；否則頻道傳送會使用媒體管線的 MIME 類型預設值
</Accordion>
<Accordion title="傳遞目標">
建議的明確目標：
<Accordion title="傳送目標">
建議使用明確目標：
- `user:<id>` 用於 DM
- `channel:<id>` 用於頻道
傳送到使用者目標時，Slack DM 會透過 Slack 對話 API 開啟。
傳送至使用者目標時，Slack DM 會透過 Slack conversation API 開啟。
</Accordion>
</AccordionGroup>
## 命令與斜線行為
## 指令與斜線行為
斜線命令會在 Slack 中顯示為單一已設定命令或多個原生命令。設定 `channels.slack.slashCommand` 可變更命令預設值：
斜線指令在 Slack 中會顯示為單一已設定指令，或多個原生指令。設定 `channels.slack.slashCommand` 以變更指令預設值：
- `enabled: false`
- `name: "openclaw"`
@ -731,30 +733,30 @@ Slack 動作由 `channels.slack.actions.*` 控制。
/openclaw /help
```
原生命令需要在你的 Slack app 中設定[額外的 manifest 設定](#additional-manifest-settings)，並改用全域設定中的 `channels.slack.commands.native: true` 或 `commands.native: true` 啟用。
原生指令需要在你的 Slack 應用程式中設定[額外的 manifest 設定](#additional-manifest-settings)，並改用 `channels.slack.commands.native: true` 啟用，或在全域設定中使用 `commands.native: true` 啟用。
- Slack 的原生命令自動模式預設為**關閉**，因此 `commands.native: "auto"` 不會啟用 Slack 原生命令。
- Slack 的原生指令自動模式為**關閉**，因此 `commands.native: "auto"` 不會啟用 Slack 原生指令。
```txt
/help
```
原生引數選單使用自適應轉譯策略，會在派送所選選項值前顯示確認 modal：
原生引數選單使用自適應轉譯策略，會在分派選取的選項值前顯示確認 modal：
- 最多 5 個選項：按鈕區塊
- 6-100 個選項：靜態選取選單
- 超過 100 個選項：當 interactivity options handlers 可用時，使用外部選取並進行非同步選項篩選
- 超出 Slack 限制：已編碼的選項值會退回使用按鈕
- 超過 100 個選項：可用互動性選項處理器時，使用含非同步選項篩選的外部選取
- 超過 Slack 限制：編碼後的選項值會退回使用按鈕
```txt
/think
```
Slash 工作階段使用像 `agent:<agentId>:slack:slash:<userId>` 這類隔離 key，並且仍會使用 `CommandTargetSessionKey` 將命令執行路由到目標對話工作階段。
斜線工作階段使用像 `agent:<agentId>:slack:slash:<userId>` 這樣的隔離金鑰，並仍會使用 `CommandTargetSessionKey` 將指令執行路由到目標對話工作階段。
## 互動式回覆
Slack 可以轉譯由代理撰寫的互動式回覆控制項，但此功能預設為停用。
Slack 可以轉譯代理撰寫的互動式回覆控制項，但此功能預設停用。
全域啟用：
@ -793,36 +795,37 @@ Slack 可以轉譯由代理撰寫的互動式回覆控制項，但此功能預
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
這些指令會編譯成 Slack Block Kit，並透過既有的 Slack 互動事件路徑將點擊或選取路由回來。
這些指令會編譯成 Slack Block Kit，並透過現有的 Slack 互動事件路徑將點擊或選取路由回來。
注意事項：
- 這是 Slack 專用 UI。其他通道不會將 Slack Block Kit 指令轉譯成自己的按鈕系統。
- 互動式 callback 值是 OpenClaw 產生的不透明 token，不是代理原始撰寫的值。
- 如果產生的互動式區塊會超出 Slack Block Kit 限制，OpenClaw 會退回原始文字回覆，而不是傳送無效的 blocks payload。
- 這是 Slack 專用 UI。其他頻道不會將 Slack Block Kit 指令轉譯為自己的按鈕系統。
- 互動式 callback 值是 OpenClaw 產生的不透明權杖，不是代理原始撰寫的值。
- 如果產生的互動區塊會超過 Slack Block Kit 限制，OpenClaw 會退回原始文字回覆，而不是傳送無效的 blocks payload。
## Slack 中的 exec 核准
## Slack 中的執行核准
Slack 可以作為具備互動式按鈕與互動的原生核准用戶端，而不是退回使用 Web UI 或 terminal。
Slack 可以作為具有互動式按鈕和互動的原生核准用戶端，而不是退回 Web UI 或終端機。
- Exec 核准使用 `channels.slack.execApprovals.*` 進行原生 DM/頻道路由。
- 當請求已經落在 Slack 且核准 id kind 為 `plugin:` 時，Plugin 核准仍可透過相同的 Slack 原生按鈕介面解析。
- 核准者授權仍會強制執行：只有被識別為核准者的使用者可以透過 Slack 核准或拒絕請求。
- 執行核准使用 `channels.slack.execApprovals.*` 進行原生 DM/頻道路由。
- 當請求已經落在 Slack 且核准 ID 類型是 `plugin:` 時，Plugin 核准仍可透過同一個 Slack 原生按鈕介面解析。
- 仍會強制執行核准者授權：只有被識別為核准者的使用者可以透過 Slack 核准或拒絕請求。
這會使用與其他通道相同的共用核准按鈕介面。當你的 Slack app 設定已啟用 `interactivity` 時，核准提示會直接在對話中轉譯為 Block Kit 按鈕。
當這些按鈕存在時，它們就是主要核准 UX；OpenClaw 只有在工具結果表示聊天核准不可用，或手動核准是唯一路徑時，才應包含手動 `/approve` 命令。
這使用與其他頻道相同的共用核准按鈕介面。當你的 Slack 應用程式設定中啟用 `interactivity` 時，核准提示會直接在對話中轉譯為 Block Kit 按鈕。
當這些按鈕存在時，它們是主要核准 UX；只有在工具結果表示聊天核准無法使用，或手動核准是唯一途徑時，OpenClaw
才應包含手動 `/approve` 指令。
設定路徑：
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers`（選用；可行時會退回使用 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.approvers`（選用；可行時退回 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，預設：`dm`）
- `agentFilter`、`sessionFilter`
當 `enabled` 未設定或為 `"auto"`，且至少解析出一位核准者時，Slack 會自動啟用原生 exec 核准。設定 `enabled: false` 可明確停用 Slack 作為原生核准用戶端。
設定 `enabled: true` 可在核准者解析成功時強制啟用原生核准。
當 `enabled` 未設定或為 `"auto"`，且至少解析到一位核准者時，Slack 會自動啟用原生執行核准。設定 `enabled: false` 可明確停用 Slack 作為原生核准用戶端。
設定 `enabled: true` 可在解析到核准者時強制啟用原生核准。
沒有明確 Slack exec 核准設定時的預設行為：
沒有明確 Slack 執行核准設定時的預設行為：
```json5
{
@ -832,7 +835,7 @@ Slack 可以作為具備互動式按鈕與互動的原生核准用戶端，而
}
```
只有在你想覆寫核准者、新增篩選器，或選擇加入來源聊天遞送時，才需要明確的 Slack 原生設定：
只有當你想覆寫核准者、新增篩選器，或選擇加入來源聊天傳送時，才需要明確的 Slack 原生設定：
```json5
{
@ -848,22 +851,22 @@ Slack 可以作為具備互動式按鈕與互動的原生核准用戶端，而
}
```
共用的 `approvals.exec` 轉送是分開的。只有當 exec 核准提示也必須路由到其他聊天或明確的頻外目標時才使用它。共用的 `approvals.plugin` 轉送也同樣分開；當這些請求已經落在 Slack 時，Slack 原生按鈕仍可解析 Plugin 核准。
共用的 `approvals.exec` 轉送是獨立的。只有當執行核准提示也必須路由到其他聊天或明確的頻外目標時才使用它。共用的 `approvals.plugin` 轉送也是獨立的；當這些請求已經落在 Slack 時，Slack 原生按鈕仍可解析 Plugin 核准。
相同聊天中的 `/approve` 也可在已支援命令的 Slack 頻道與 DM 中運作。完整核准轉送模型請參閱 [Exec 核准](/zh-TW/tools/exec-approvals)。
同聊天 `/approve` 也可在已支援指令的 Slack 頻道和 DM 中運作。完整的核准轉送模型請參閱[執行核准](/zh-TW/tools/exec-approvals)。
## 事件與操作行為
- 訊息編輯/刪除會對應為系統事件。
- 執行緒廣播（「也傳送到頻道」的執行緒回覆）會作為一般使用者訊息處理。
- 新增/移除 reaction 事件會對應為系統事件。
- 成員加入/離開、頻道建立/重新命名，以及新增/移除 pin 事件會對應為系統事件。
- 啟用 `configWrites` 時，`channel_id_changed` 可以遷移頻道設定 key。
- 頻道 topic/purpose metadata 會被視為不可信任的 context，並可注入到路由 context 中。
- 適用時，執行緒起始訊息與初始執行緒歷史 context 種子會依設定的傳送者 allowlists 篩選。
- Block actions 與 modal 互動會發出結構化的 `Slack interaction: ...` 系統事件，並包含豐富的 payload 欄位：
- block actions：所選值、標籤、picker 值，以及 `workflow_*` metadata
- modal `view_submission` 與 `view_closed` 事件，包含已路由的頻道 metadata 與表單輸入
- 討論串廣播（「同時傳送到頻道」的討論串回覆）會作為一般使用者訊息處理。
- 表情符號回應新增/移除事件會對應為系統事件。
- 成員加入/離開、頻道建立/重新命名，以及釘選新增/移除事件會對應為系統事件。
- 啟用 `configWrites` 時，`channel_id_changed` 可以遷移頻道設定金鑰。
- 頻道主題/用途中繼資料會被視為不受信任的內容，並可被注入路由內容。
- 適用時，討論串起始者和初始討論串歷史內容植入會依設定的寄件者允許清單篩選。
- 區塊動作和 modal 互動會發出具備豐富 payload 欄位的結構化 `Slack interaction: ...` 系統事件：
- 區塊動作：選取值、標籤、選擇器值，以及 `workflow_*` 中繼資料
- modal `view_submission` 和 `view_closed` 事件，包含已路由的頻道中繼資料和表單輸入
## 設定參考
@ -873,10 +876,10 @@ Slack 可以作為具備互動式按鈕與互動的原生核准用戶端，而
- 模式/驗證：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- DM 存取：`dm.enabled`、`dmPolicy`、`allowFrom`（舊版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
- 相容性切換：`dangerouslyAllowNameMatching`（緊急例外；除非需要，否則保持關閉）
- 相容性切換：`dangerouslyAllowNameMatching`（緊急破例；除非需要，否則保持關閉）
- 頻道存取：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
- 執行緒/歷史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 遞送：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
- 討論串/歷史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 傳送：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
- 操作/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly`
</Accordion>
@ -888,11 +891,11 @@ Slack 可以作為具備互動式按鈕與互動的原生核准用戶端，而
依序檢查：
- `groupPolicy`
- 頻道 allowlist（`channels.slack.channels`）— **key 必須是頻道 ID**（`C12345678`），不是名稱（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，名稱式 key 會靜默失敗，因為頻道路由預設優先使用 ID。若要尋找 ID：在 Slack 中對頻道按右鍵 → **複製連結** — URL 結尾的 `C...` 值就是頻道 ID。
- 頻道允許清單（`channels.slack.channels`）— **金鑰必須是頻道 ID**（`C12345678`），不是名稱（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，名稱型金鑰會無聲失敗，因為頻道路由預設以 ID 優先。若要尋找 ID：在 Slack 中以右鍵點選頻道 → **複製連結** — URL 末尾的 `C...` 值就是頻道 ID。
- `requireMention`
- 個別頻道的 `users` allowlist
- 每個頻道的 `users` 允許清單
實用命令：
實用指令：
```bash
openclaw channels status --probe
@ -907,10 +910,10 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy`（或舊版 `channels.slack.dm.policy`）
- 配對核准 / allowlist 項目
- Slack Assistant DM 事件：提到 `drop message_changed` 的 verbose logs
通常表示 Slack 傳送了已編輯的 Assistant 執行緒事件，但訊息 metadata 中
沒有可復原的人類傳送者
- 配對核准 / 允許清單項目
- Slack Assistant DM 事件：提到 `drop message_changed` 的詳細記錄
通常表示 Slack 傳送了已編輯的 Assistant 討論串事件，但訊息中繼資料中
沒有可復原的人類寄件者
```bash
openclaw pairing list slack
@ -918,123 +921,123 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket mode 未連線">
驗證 bot + app tokens，以及 Slack app 設定中的 Socket Mode 啟用狀態。
<Accordion title="Socket 模式未連線">
驗證 Slack 應用程式設定中的 bot + app 權杖和 Socket Mode 啟用狀態。
如果 `openclaw channels status --probe --json` 顯示 `botTokenStatus` 或
`appTokenStatus: "configured_unavailable"`，表示 Slack 帳號已設定，
但目前 runtime 無法解析 SecretRef 支援的值。
但目前執行階段無法解析由 SecretRef 支援的值。
</Accordion>
<Accordion title="HTTP mode 未接收事件">
<Accordion title="HTTP 模式未收到事件">
驗證：
- signing secret
- webhook path
- Slack Request URLs（Events + Interactivity + Slash Commands）
- 簽署密鑰
- Webhook 路徑
- Slack Request URL（Events + Interactivity + Slash Commands）
- 每個 HTTP 帳號的唯一 `webhookPath`
如果帳號 snapshot 中出現 `signingSecretStatus: "configured_unavailable"`，
表示 HTTP 帳號已設定，但目前 runtime 無法解析 SecretRef 支援的 signing secret。
如果帳號快照中出現 `signingSecretStatus: "configured_unavailable"`，
表示 HTTP 帳號已設定，但目前執行階段無法解析由 SecretRef 支援的簽署密鑰。
</Accordion>
<Accordion title="原生/slash 命令未觸發">
確認你的預期是：
<Accordion title="原生/斜線指令未觸發">
確認你的意圖是：
- 原生命令模式（`channels.slack.commands.native: true`），並在 Slack 中註冊相符的 slash commands
- 或單一 slash command 模式（`channels.slack.slashCommand.enabled: true`）
- 原生指令模式（`channels.slack.commands.native: true`），並在 Slack 中註冊相符的斜線指令
- 或單一斜線指令模式（`channels.slack.slashCommand.enabled: true`）
同時檢查 `commands.useAccessGroups` 與頻道/使用者 allowlists。
也請檢查 `commands.useAccessGroups` 和頻道/使用者允許清單。
</Accordion>
</AccordionGroup>
## 附件視覺參考
當 Slack 檔案下載成功且大小限制允許時，Slack 可以將下載的媒體附加到代理回合。影像檔可透過媒體理解路徑傳遞，或直接傳給支援視覺的回覆模型；其他檔案會保留為可下載檔案 context，而不是被視為影像輸入。
當 Slack 檔案下載成功且大小限制允許時，Slack 可以將下載的媒體附加到代理回合。影像檔案可透過媒體理解路徑傳遞，或直接傳給具備視覺能力的回覆模型；其他檔案會保留為可下載的檔案內容，而不是被視為影像輸入。
### 支援的媒體類型
| 媒體類型 | 來源 | 目前行為 | 注意事項 |
| 媒體類型 | 來源 | 目前行為 | 注意事項 |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| JPEG / PNG / GIF / WebP 影像 | Slack 檔案 URL | 已下載並附加到回合，以便支援視覺的處理 | 每檔案上限：`channels.slack.mediaMaxMb`（預設 20 MB） |
| PDF 檔案 | Slack 檔案 URL | 已下載並公開為檔案 context，供 `download-file` 或 `pdf` 等工具使用 | Slack inbound 不會自動將 PDF 轉換為影像視覺輸入 |
| 其他檔案 | Slack 檔案 URL | 可行時下載並公開為檔案 context | 二進位檔案不會被視為影像輸入 |
| 執行緒回覆 | 執行緒起始檔案 | 當回覆沒有直接媒體時，可將根訊息檔案補齊為 context | 只有檔案的起始訊息會使用附件 placeholder |
| 多影像訊息 | 多個 Slack 檔案 | 每個檔案都會獨立評估 | Slack 處理每則訊息最多八個檔案 |
| JPEG / PNG / GIF / WebP 影像 | Slack 檔案 URL | 已下載並附加到該回合，以便進行具備視覺能力的處理 | 每個檔案上限：`channels.slack.mediaMaxMb`（預設 20 MB） |
| PDF 檔案 | Slack 檔案 URL | 已下載並公開為檔案內容，供 `download-file` 或 `pdf` 等工具使用 | Slack 傳入不會自動將 PDF 轉換為影像視覺輸入 |
| 其他檔案 | Slack 檔案 URL | 可行時下載並公開為檔案內容 | 二進位檔案不會被視為影像輸入 |
| 討論串回覆 | 討論串起始檔案 | 當回覆沒有直接媒體時，可將根訊息檔案補充為內容 | 僅含檔案的起始訊息會使用附件預留位置 |
| 多影像訊息 | 多個 Slack 檔案 | 每個檔案會獨立評估 | Slack 處理每則訊息最多八個檔案 |
### Inbound pipeline
### 傳入管線
當帶有檔案附件的 Slack 訊息抵達時：
當包含檔案附件的 Slack 訊息抵達時：
1. OpenClaw 使用 bot token（`xoxb-...`）從 Slack 的私有 URL 下載檔案。
2. 成功時，檔案會寫入媒體儲存區。
3. 已下載的媒體路徑與內容類型會加入 inbound context。
4. 支援影像的模型/工具路徑可以使用該 context 中的影像附件。
5. 非影像檔案會以檔案 metadata 或媒體 reference 的形式保留，供可處理它們的工具使用。
1. OpenClaw 會使用 bot token（`xoxb-...`）從 Slack 的私人 URL 下載檔案。
2. 成功後，檔案會寫入媒體儲存區。
3. 下載的媒體路徑和內容類型會加入傳入情境。
4. 支援影像的模型/工具路徑可以使用該情境中的影像附件。
5. 非影像檔案仍可作為檔案中繼資料或媒體參照，供能處理它們的工具使用。
### 執行緒根附件繼承
當訊息抵達執行緒中（具有 `thread_ts` parent）時：
當訊息抵達執行緒中（具有 `thread_ts` 父項）時：
- 如果回覆本身沒有直接媒體，而包含的根訊息有檔案，Slack 可以將根檔案補齊為執行緒起始 context。
- 如果回覆本身沒有直接媒體，而包含的根訊息有檔案，Slack 可以將根檔案補入為執行緒起始情境。
- 直接回覆附件優先於根訊息附件。
- 只有檔案且沒有文字的根訊息會以附件 placeholder 表示，因此 fallback 仍可包含其檔案。
- 只有檔案且沒有文字的根訊息，會以附件預留位置表示，讓備援仍可包含其檔案。
### 多附件處理
當單一 Slack 訊息包含多個檔案附件時：
- 每個附件都會透過媒體管線獨立處理。
- 已下載的媒體參照會彙總到訊息情境中。
- 處理順序會依照事件有效負載中的 Slack 檔案順序。
- 其中一個附件下載失敗不會阻擋其他附件。
- 下載的媒體參照會彙總到訊息情境中。
- 處理順序會遵循事件承載中 Slack 的檔案順序。
- 某個附件下載失敗不會阻擋其他附件。
### 大小、下載與模型限制
- **大小上限**：預設每個檔案 20 MB。可透過 `channels.slack.mediaMaxMb` 設定。
- **下載失敗**：Slack 無法提供的檔案、過期的 URL、無法存取的檔案、超過大小限制的檔案，以及 Slack 驗證/登入 HTML 回應都會被略過，而不是回報為不支援的格式。
- **視覺模型**：影像分析會在作用中的回覆模型支援視覺時使用該模型，否則使用 `agents.defaults.imageModel` 設定的影像模型。
- **下載失敗**：Slack 無法提供的檔案、過期 URL、無法存取的檔案、超大檔案，以及 Slack 驗證/登入 HTML 回應，都會被略過，而不是回報為不支援的格式。
- **視覺模型**：影像分析會使用支援視覺的目前回覆模型，或使用在 `agents.defaults.imageModel` 設定的影像模型。
### 已知限制
| 情境 | 目前行為 | 解決方式 |
| 情境 | 目前行為 | 因應方式 |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 過期的 Slack 檔案 URL | 檔案被略過；不顯示錯誤 | 在 Slack 中重新上傳檔案 |
| 未設定視覺模型 | 影像附件會儲存為媒體參照，但不會作為影像分析 | 設定 `agents.defaults.imageModel`，或使用支援視覺的回覆模型 |
| 非常大的影像（預設 > 20 MB） | 依大小上限略過 | 如果 Slack 允許，請提高 `channels.slack.mediaMaxMb` |
| 轉寄/共享的附件 | 文字與 Slack 託管的影像/檔案媒體會以最佳努力方式處理 | 直接在 OpenClaw 執行緒中重新分享 |
| PDF 附件 | 儲存為檔案/媒體情境，不會自動透過影像視覺路由 | 使用 `download-file` 取得檔案中繼資料，或使用 `pdf` 工具進行 PDF 分析 |
| 過期的 Slack 檔案 URL | 檔案會被略過；不顯示錯誤 | 在 Slack 重新上傳檔案 |
| 未設定視覺模型 | 影像附件會儲存為媒體參照，但不會作為影像分析 | 設定 `agents.defaults.imageModel`，或使用支援視覺的回覆模型 |
| 非常大的影像（預設 > 20 MB） | 依大小上限略過 | 如果 Slack 允許，請提高 `channels.slack.mediaMaxMb` |
| 轉寄/共享的附件 | 文字和 Slack 託管的影像/檔案媒體會盡力處理 | 直接在 OpenClaw 執行緒中重新分享 |
| PDF 附件 | 儲存為檔案/媒體情境，不會自動透過影像視覺路由 | 使用 `download-file` 取得檔案中繼資料，或使用 `pdf` 工具進行 PDF 分析 |
### 相關文件
- [媒體理解管線](/zh-TW/nodes/media-understanding)
- [PDF 工具](/zh-TW/tools/pdf)
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件視覺啟用
- 迴歸測試：[#51353](https://github.com/openclaw/openclaw/issues/51353)
- 即時驗證：[#51354](https://github.com/openclaw/openclaw/issues/51354)
- 迴歸測試: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- 即時驗證: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## 相關
<CardGroup cols={2}>
<Card title="配對" icon="link" href="/zh-TW/channels/pairing">
將 Slack 使用者與 Gateway 配對。
<Card title="Pairing" icon="link" href="/zh-TW/channels/pairing">
將 Slack 使用者配對到 Gateway。
</Card>
<Card title="群組" icon="users" href="/zh-TW/channels/groups">
Channel 與群組 DM 行為。
<Card title="Groups" icon="users" href="/zh-TW/channels/groups">
頻道和群組 DM 行為。
</Card>
<Card title="Channel 路由" icon="route" href="/zh-TW/channels/channel-routing">
將傳入訊息路由至代理程式。
<Card title="Channel routing" icon="route" href="/zh-TW/channels/channel-routing">
將傳入訊息路由到代理。
</Card>
<Card title="安全性" icon="shield" href="/zh-TW/gateway/security">
威脅模型與強化措施。
<Card title="Security" icon="shield" href="/zh-TW/gateway/security">
威脅模型與強化。
</Card>
<Card title="設定" icon="sliders" href="/zh-TW/gateway/configuration">
<Card title="Configuration" icon="sliders" href="/zh-TW/gateway/configuration">
設定版面配置與優先順序。
</Card>
<Card title="斜線指令" icon="terminal" href="/zh-TW/tools/slash-commands">
<Card title="Slash commands" icon="terminal" href="/zh-TW/tools/slash-commands">
指令目錄與行為。
</Card>
</CardGroup>

599
docs/zh-TW/channels/telegram.md
View File

File diff suppressed because it is too large Load Diff

64
docs/zh-TW/concepts/memory-search.md
View File

@ -3,22 +3,22 @@ read_when:
- 你想了解 memory_search 的運作方式
- 您想選擇嵌入提供者
- 您想調整搜尋品質
summary: 記憶搜尋如何使用嵌入與混合檢索找到相關筆記
summary: 記憶搜尋如何使用嵌入和混合檢索找到相關筆記
title: 記憶搜尋
x-i18n:
generated_at: "2026-04-30T03:00:13Z"
generated_at: "2026-04-30T16:27:54Z"
model: gpt-5.5
provider: openai
source_hash: 3e6c44d90f49a797bda01b9a575928c128a334f89ae14fc3620e65562a866aa9
source_hash: 7f40bbe32453a28070ffc67f19a4c06e2fe59a24237a2aef353f4b9b8260bcf2
source_path: concepts/memory-search.md
workflow: 16
---
`memory_search` 會從你的記憶檔案中找出相關筆記，即使用字與原文不同也能找到。它的運作方式是將記憶索引成小區塊，並使用 embeddings、關鍵字，或兩者一起搜尋。
`memory_search` 會從你的記憶檔案中尋找相關筆記，即使用詞與原始文字不同也可以。它的運作方式是將記憶索引成小型區塊，並使用嵌入、關鍵字或兩者來搜尋。
## 快速開始
如果你已設定 GitHub Copilot 訂閱、OpenAI、Gemini、Voyage 或 Mistral API 金鑰，記憶搜尋會自動運作。若要明確設定供應商：
如果你已設定 GitHub Copilot 訂閱、OpenAI、Gemini、Voyage 或 Mistral API 金鑰，記憶搜尋會自動運作。若要明確設定提供者：
```json5
{
@ -32,28 +32,28 @@ x-i18n:
}
```
對於多端點設定，當該供應商設定了 `api: "ollama"` 或其他 embedding 配接器擁有者時，`provider` 也可以是自訂的 `models.providers.<id>` 項目，例如 `ollama-5080`。
對於多端點設定，當該提供者設定了 `api: "ollama"` 或其他嵌入配接器擁有者時，`provider` 也可以是自訂的 `models.providers.<id>` 項目，例如 `ollama-5080`。
若要使用不需 API 金鑰的本機 embeddings，請在 OpenClaw 旁安裝選用的 `node-llama-cpp` 執行階段套件，並使用 `provider: "local"`。
若要使用不需 API 金鑰的本機嵌入，請設定 `provider: "local"`。封裝安裝會在 OpenClaw 受管理的 Plugin runtime-deps 樹中保留原生 `node-llama-cpp` 執行階段；如果該樹需要修復，請執行 `openclaw doctor --fix`。
某些 OpenAI 相容的 embedding 端點需要非對稱標籤，例如搜尋使用 `input_type: "query"`，而索引區塊使用 `input_type: "document"` 或 `"passage"`。請用 `memorySearch.queryInputType` 和 `memorySearch.documentInputType` 設定這些選項；請參閱[記憶設定參考](/zh-TW/reference/memory-config#provider-specific-config)。
某些 OpenAI 相容的嵌入端點需要不對稱標籤，例如搜尋使用 `input_type: "query"`，索引區塊使用 `input_type: "document"` 或 `"passage"`。請使用 `memorySearch.queryInputType` 和 `memorySearch.documentInputType` 設定這些項目；請參閱[記憶設定參考](/zh-TW/reference/memory-config#provider-specific-config)。
## 支援的供應商
## 支援的提供者
| 供應商 | ID | 需要 API 金鑰 | 備註 |
| 提供者 | ID | 需要 API 金鑰 | 備註 |
| -------------- | ---------------- | ------------- | ---------------------------------------------------- |
| Bedrock | `bedrock` | 否 | AWS 憑證鏈可解析時會自動偵測 |
| Gemini | `gemini` | 是 | 支援圖片/音訊索引 |
| Bedrock | `bedrock` | 否 | AWS 憑證鏈解析成功時自動偵測 |
| Gemini | `gemini` | 是 | 支援影像/音訊索引 |
| GitHub Copilot | `github-copilot` | 否 | 自動偵測，使用 Copilot 訂閱 |
| Local | `local` | 否 | GGUF 模型，約 0.6 GB 下載 |
| Local | `local` | 否 | GGUF 模型，下載約 0.6 GB |
| Mistral | `mistral` | 是 | 自動偵測 |
| Ollama | `ollama` | 否 | 本機，必須明確設定 |
| OpenAI | `openai` | 是 | 自動偵測，速度快 |
| OpenAI | `openai` | 是 | 自動偵測，速度快 |
| Voyage | `voyage` | 是 | 自動偵測 |
## 搜尋的運作方式
## 搜尋如何運作
OpenClaw 會平行執行兩條擷取路徑，並合併結果：
OpenClaw 會平行執行兩條檢索路徑並合併結果：
```mermaid
flowchart LR
@ -66,14 +66,12 @@ flowchart LR
M --> R["Top Results"]
```
- **向量搜尋**會尋找語意相近的筆記（"gateway host" 會符合
"the machine running OpenClaw"）。
- **BM25 關鍵字搜尋**會尋找精確相符項（ID、錯誤字串、設定
keys）。
- **向量搜尋**會尋找語意相近的筆記（"gateway host" 會符合 "the machine running OpenClaw"）。
- **BM25 關鍵字搜尋**會尋找精確符合項（ID、錯誤字串、設定鍵）。
如果只有一條路徑可用（沒有 embeddings 或沒有 FTS），另一條會單獨執行。
如果只有一條路徑可用（沒有嵌入或沒有 FTS），另一條會單獨執行。
當 embeddings 無法使用時，OpenClaw 仍會對 FTS 結果使用詞彙排名，而不只是退回到原始的精確相符排序。這種降級模式會提升查詢詞覆蓋率較強、且檔案路徑相關的區塊，因此即使沒有 `sqlite-vec` 或 embedding 供應商，召回效果仍然實用。
當嵌入不可用時，OpenClaw 仍會對 FTS 結果使用詞彙排序，而不是只退回原始的精確符合排序。這種降級模式會提升查詢詞涵蓋度更高且檔案路徑相關的區塊，因此即使沒有 `sqlite-vec` 或嵌入提供者，也能維持有用的召回率。
## 改善搜尋品質
@ -81,18 +79,18 @@ flowchart LR
### 時間衰減
舊筆記會逐漸降低排名權重，讓近期資訊優先浮現。使用預設 30 天半衰期時，上個月的筆記分數會是原始權重的 50%。像 `MEMORY.md` 這類常青檔案永遠不會衰減。
舊筆記會逐漸降低排序權重，讓近期資訊優先浮現。使用預設的 30 天半衰期時，上個月的筆記分數會是原始權重的 50%。像 `MEMORY.md` 這類長青檔案不會衰減。
<Tip>
如果你的代理程式有數月的每日筆記，而過時資訊一直排在近期脈絡之前，請啟用時間衰減。
如果你的代理程式已有數月的每日筆記，而且過時資訊持續排在近期脈絡之前，請啟用時間衰減。
</Tip>
### MMR（多樣性）
減少重複結果。如果五則筆記都提到相同的路由器設定，MMR 會確保排名靠前的結果涵蓋不同主題，而不是重複出現。
減少重複結果。如果五則筆記都提到相同的路由器設定，MMR 會確保頂部結果涵蓋不同主題，而不是重複顯示。
<Tip>
如果 `memory_search` 一直從不同每日筆記傳回近乎重複的片段，請啟用 MMR。
如果 `memory_search` 持續從不同每日筆記傳回幾乎重複的片段，請啟用 MMR。
</Tip>
### 同時啟用兩者
@ -116,30 +114,30 @@ flowchart LR
## 多模態記憶
使用 Gemini Embedding 2 時，你可以把圖片和音訊檔案與 Markdown 一起索引。搜尋查詢仍是文字，但會比對視覺和音訊內容。設定方式請參閱[記憶設定參考](/zh-TW/reference/memory-config)。
使用 Gemini Embedding 2 時，你可以將影像和音訊檔案與 Markdown 一起索引。搜尋查詢仍是文字，但會比對視覺與音訊內容。設定方式請參閱[記憶設定參考](/zh-TW/reference/memory-config)。
## 工作階段記憶搜尋
你也可以選擇索引工作階段逐字稿，讓 `memory_search` 能回想先前的對話。這需要透過 `memorySearch.experimental.sessionMemory` 選擇加入。詳細資訊請參閱[設定參考](/zh-TW/reference/memory-config)。
你可以選擇索引工作階段逐字稿，讓 `memory_search` 能回想較早的對話。這需要透過 `memorySearch.experimental.sessionMemory` 明確加入。詳情請參閱[設定參考](/zh-TW/reference/memory-config)。
## 疑難排解
**沒有結果？** 執行 `openclaw memory status` 檢查索引。如果是空的，請執行 `openclaw memory index --force`。
**只有關鍵字相符？** 你的 embedding 供應商可能尚未設定。請檢查 `openclaw memory status --deep`。
**只有關鍵字符合？** 你的嵌入提供者可能尚未設定。請檢查 `openclaw memory status --deep`。
**本機 embeddings 逾時？** `ollama`、`lmstudio` 和 `local` 預設會使用較長的行內批次逾時。如果主機只是比較慢，請設定 `agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds`，然後重新執行 `openclaw memory index --force`。
**本機嵌入逾時？** `ollama`、`lmstudio` 和 `local` 預設使用較長的內嵌批次逾時。如果主機只是較慢，請設定 `agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds`，然後重新執行 `openclaw memory index --force`。
**找不到 CJK 文字？** 使用 `openclaw memory index --force` 重建 FTS 索引。
## 延伸閱讀
- [Active Memory](/zh-TW/concepts/active-memory) -- 互動式聊天工作階段的子代理程式記憶
- [記憶](/zh-TW/concepts/memory) -- 檔案配置、後端、工具
- [記憶](/zh-TW/concepts/memory) -- 檔案版面配置、後端、工具
- [記憶設定參考](/zh-TW/reference/memory-config) -- 所有設定旋鈕
## 相關內容
## 相關
- [記憶概覽](/zh-TW/concepts/memory)
- [記憶概觀](/zh-TW/concepts/memory)
- [Active Memory](/zh-TW/concepts/active-memory)
- [內建記憶引擎](/zh-TW/concepts/memory-builtin)

164
docs/zh-TW/concepts/messages.md
View File

@ -1,22 +1,22 @@
---
read_when:
- 說明傳入訊息如何變成回覆
- 釐清工作階段、佇列模式或串流行為
- 記錄推理可見性與使用上的影響
- 說明傳入訊息如何轉換為回覆
- 釐清工作階段、排隊模式或串流行為
- 說明推理可見度與使用影響
summary: 訊息流程、工作階段、佇列處理與推理可見性
title: 訊息
x-i18n:
generated_at: "2026-04-30T03:00:24Z"
generated_at: "2026-04-30T16:27:57Z"
model: gpt-5.5
provider: openai
source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
source_path: concepts/messages.md
workflow: 16
---
OpenClaw 透過一條包含工作階段解析、佇列、串流、工具執行與推理可見性的管線處理傳入訊息。本頁說明從傳入訊息到回覆的路徑。
OpenClaw 透過由工作階段解析、佇列、串流、工具執行與推理可見性組成的管線處理傳入訊息。本頁說明從傳入訊息到回覆的路徑。
## 訊息流程（高階）
## 訊息流程（高層次）
```
Inbound message
@ -26,27 +26,26 @@ Inbound message
-> outbound replies (channel limits + chunking)
```
關鍵調整項位於設定中：
主要旋鈕位於設定中：
- `messages.*` 用於前綴、佇列與群組行為。
- `agents.defaults.*` 用於區塊串流與分塊預設值。
- Channel 覆寫（`channels.whatsapp.*`、`channels.telegram.*` 等）用於上限與串流切換。
- 通道覆寫（`channels.whatsapp.*`、`channels.telegram.*` 等）用於上限與串流切換。
完整結構請參閱[設定](/zh-TW/gateway/configuration)。
完整結構描述請參閱[設定](/zh-TW/gateway/configuration)。
## 傳入去重
## 傳入訊息去重
Channel 可能會在重新連線後重新投遞相同訊息。OpenClaw 會保留一個
短期快取，以 channel/account/peer/session/message id 作為鍵，避免重複
投遞觸發另一個 agent 執行。
通道可能會在重新連線後重新傳送同一則訊息。OpenClaw 會保留一個
短期快取，依通道/帳號/對等方/工作階段/訊息 ID 建立鍵值，讓重複
傳送不會觸發另一個代理程式執行。
## 傳入防抖
## 傳入訊息防抖
來自**同一寄件者**的快速連續訊息，可透過 `messages.inbound` 批次合併為單一
agent 回合。防抖範圍限定在每個 channel + 對話，
並使用最新訊息作為回覆串接/ID。
來自**同一寄件者**的快速連續訊息，可透過 `messages.inbound` 批次合併成單一
代理程式回合。防抖範圍限於每個通道 + 對話，並使用最新訊息作為回覆串接/ID。
設定（全域預設 + 各 channel 覆寫）：
設定（全域預設值 + 每通道覆寫）：
```json5
{
@ -65,20 +64,20 @@ agent 回合。防抖範圍限定在每個 channel + 對話，
注意事項：
- 防抖適用於**純文字**訊息；媒體/附件會立即送出。
- 控制命令會略過防抖，因此會保持獨立處理，**除非**某個 channel 明確選擇加入同寄件者 DM 合併（例如 [BlueBubbles `coalesceSameSenderDms`](/zh-TW/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)），此時 DM 命令會在防抖視窗內等待，讓拆分傳送的負載可以加入同一個 agent 回合。
- 防抖套用於**純文字**訊息；媒體/附件會立即清空等待中的批次。
- 控制命令會略過防抖，以維持獨立處理；**但**若通道明確選擇加入同寄件者私訊合併（例如 [BlueBubbles `coalesceSameSenderDms`](/zh-TW/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)），私訊命令會在防抖視窗內等待，讓分段傳送的酬載能加入同一個代理程式回合。
## 工作階段與裝置
工作階段由 Gateway 擁有，而不是由用戶端擁有。
- 直接聊天會收斂到 agent 主要工作階段鍵。
- 群組/channel 會取得自己的工作階段鍵。
- 工作階段儲存與逐字稿位於 Gateway 主機上。
- 直接聊天會收斂到代理程式主工作階段鍵。
- 群組/通道會取得各自的工作階段鍵。
- 工作階段儲存區與逐字稿位於 Gateway 主機上。
多個裝置/channel 可以對應到同一個工作階段，但歷史記錄不會完整
多個裝置/通道可以對應到同一個工作階段，但歷史記錄不會完整
同步回每個用戶端。建議：長對話使用一個主要裝置，
以避免脈絡分歧。Control UI 與 TUI 永遠顯示
以避免脈絡分歧。Control UI 與 TUI 一律顯示
Gateway 支援的工作階段逐字稿，因此它們是事實來源。
詳細資訊：[工作階段管理](/zh-TW/concepts/session)。
@ -86,87 +85,92 @@ Gateway 支援的工作階段逐字稿，因此它們是事實來源。
## 工具結果中繼資料
工具結果的 `content` 是模型可見的結果。工具結果的 `details` 是
用於 UI 呈現、診斷、媒體投遞與 Plugin 的執行階段中繼資料。
用於 UI 呈現、診斷、媒體傳送與 Plugin 的執行階段中繼資料。
OpenClaw 明確維持這個邊界：
OpenClaw 會明確維持這個邊界：
- `toolResult.details` 會在供應商重播與 Compaction 輸入前被移除。
- 持久化工作階段逐字稿只保留受限的 `details`；過大的中繼資料
會被替換成標記為 `persistedDetailsTruncated: true` 的精簡摘要。
- Plugin 與工具應將模型必須讀取的文字放在 `content`，而不只
放在 `details`。
- `toolResult.details` 會在提供者重播與 Compaction 輸入前被移除。
- 已持久化的工作階段逐字稿只保留有界限的 `details`；過大的中繼資料
會以標記為 `persistedDetailsTruncated: true` 的精簡摘要取代。
- Plugin 與工具應將模型必須讀取的文字放在 `content` 中，而不是只放在
`details` 中。
## 傳入本文與歷史脈絡
OpenClaw 會區分**提示本文**與**命令本文**：
- `Body`：傳送給 agent 的提示文字。這可能包含 channel 信封與
選用的歷史包裝。
- `BodyForAgent`：目前訊息中面向主要模型的文字。通道
Plugin 應讓它聚焦於寄件者目前承載提示的文字。
- `Body`：舊版提示備援。這可能包含通道信封與
選用的歷史包裝，但目前通道不應在 `BodyForAgent` 可用時，
依賴它作為主要模型輸入。
- `CommandBody`：用於指令/命令解析的原始使用者文字。
- `RawBody`：`CommandBody` 的舊版別名（為相容性保留）。
- `RawBody`：`CommandBody` 的舊版別名（保留以維持相容性）。
當 channel 提供歷史時，會使用共用包裝：
當通道提供歷史記錄時，會使用共用包裝：
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
對於**非直接聊天**（群組/channel/房間），**目前訊息本文**會加上
寄件者標籤前綴（與歷史項目使用相同樣式）。這能讓即時與佇列/歷史
訊息在 agent 提示中保持一致。
對於**非直接聊天**（群組/通道/聊天室），**目前訊息本文**會加上
寄件者標籤前綴（與歷史項目使用相同樣式）。這讓即時與佇列/歷史
訊息在代理程式提示中保持一致。
歷史緩衝區是**僅待處理**：它們包含未觸發執行的群組訊息
（例如受提及限制的訊息），並**排除**已在工作階段逐字稿中的訊息。
歷史緩衝區是**僅限待處理**：它們包含未觸發執行的群組訊息
（例如受提及閘控的訊息），並**排除**已在工作階段逐字稿中的訊息。
指令剝離只套用於**目前訊息**區段，因此歷史會保持完整。
包裝歷史的 channel 應將 `CommandBody`（或 `RawBody`）設定為原始訊息文字，
並讓 `Body` 保持為合併後的提示。歷史緩衝區可透過
`messages.groupChat.historyLimit`（全域預設）與各 channel 覆寫設定，
例如 `channels.slack.historyLimit` 或
`channels.telegram.accounts.<id>.historyLimit`（設定為 `0` 可停用）。
指令移除只套用於**目前訊息**區段，因此歷史會保持完整。
包裝歷史的通道應將 `CommandBody`（或 `RawBody`）設為原始訊息文字，
並讓 `Body` 保持為合併後的提示。結構化歷史、回覆、轉寄與通道中繼資料
會在提示組裝期間呈現為使用者角色的不受信任脈絡區塊。
歷史緩衝區可透過 `messages.groupChat.historyLimit`（全域
預設值）與每通道覆寫設定，例如 `channels.slack.historyLimit` 或
`channels.telegram.accounts.<id>.historyLimit`（設為 `0` 可停用）。
## 佇列與後續處理
如果已有執行正在進行，傳入訊息可以被排入佇列、導向目前執行，
或收集到後續回合中。
如果已有執行處於作用中，傳入訊息可以被排入佇列、導向目前執行，
或收集到後續回合。
- 透過 `messages.queue`（以及 `messages.queue.byChannel`）設定。
- 預設模式為 `steer`，當導向退回到佇列後續投遞時，
- 預設模式為 `steer`，當導向回退到佇列後續傳送時，
會有 500ms 的後續防抖。
- 模式：`steer`、`followup`、`collect`、`steer-backlog`、`interrupt`，
以及舊版一次一個的 `queue` 模式。
詳細資訊：[命令佇列](/zh-TW/concepts/queue)與[導向佇列](/zh-TW/concepts/queue-steering)。
## Channel 執行擁有權
## 通道執行所有權
Channel Plugin 可以在訊息進入工作階段佇列前保留順序、對輸入進行防抖，
並套用傳輸背壓。它們不應在 agent 回合本身周圍施加
獨立逾時。一旦訊息被路由到工作階段，長時間執行的工作會由工作階段、工具與執行階段
生命週期管理，使所有 channel 都能一致地回報並從緩慢回合復原。
通道 Plugin 可在訊息進入工作階段佇列前保留順序、對輸入套用防抖，
並套用傳輸背壓。它們不應在代理程式回合本身周圍施加
個別逾時。一旦訊息被路由到
工作階段，長時間執行的工作會由工作階段、工具與執行階段
生命週期控管，讓所有通道都能一致回報慢速回合並從中復原。
## 串流、分塊與批次處理
區塊串流會在模型產生文字區塊時傳送部分回覆。
分塊會遵守 channel 文字限制，並避免拆開圍欄程式碼。
分塊會遵守通道文字限制，並避免切開圍欄式程式碼。
關鍵設定：
主要設定：
- `agents.defaults.blockStreamingDefault`（`on|off`，預設關閉）
- `agents.defaults.blockStreamingBreak`（`text_end|message_end`）
- `agents.defaults.blockStreamingChunk`（`minChars|maxChars|breakPreference`）
- `agents.defaults.blockStreamingCoalesce`（以閒置為基礎的批次處理）
- `agents.defaults.humanDelay`（區塊回覆之間類似人類的暫停）
- Channel 覆寫：`*.blockStreaming` 與 `*.blockStreamingCoalesce`（非 Telegram channel 需要明確設定 `*.blockStreaming: true`）
- `agents.defaults.blockStreamingCoalesce`（基於閒置的批次處理）
- `agents.defaults.humanDelay`（區塊回覆之間的類真人暫停）
- 通道覆寫：`*.blockStreaming` 與 `*.blockStreamingCoalesce`（非 Telegram 通道需要明確設定 `*.blockStreaming: true`）
詳細資訊：[串流 + 分塊](/zh-TW/concepts/streaming)。
## 推理可見性與權杖
OpenClaw 可以公開或隱藏模型推理：
OpenClaw 可以揭露或隱藏模型推理：
- `/reasoning on|off|stream` 控制可見性。
- 當模型產生推理內容時，它仍會計入權杖用量。
- Telegram 支援將推理串流到草稿氣泡中。
- 當模型產生推理內容時，仍會計入權杖使用量。
- Telegram 支援將推理串流到草稿泡泡中。
詳細資訊：[思考 + 推理指令](/zh-TW/tools/thinking)與[權杖使用量](/zh-TW/reference/token-use)。
@ -175,38 +179,38 @@ OpenClaw 可以公開或隱藏模型推理：
傳出訊息格式集中在 `messages` 中：
- `messages.responsePrefix`、`channels.<channel>.responsePrefix` 與 `channels.<channel>.accounts.<id>.responsePrefix`（傳出前綴串接），以及 `channels.whatsapp.messagePrefix`（WhatsApp 傳入前綴）
- 透過 `replyToMode` 與各 channel 預設值進行回覆串接
- 透過 `replyToMode` 與每通道預設值進行回覆串接
詳細資訊：[設定](/zh-TW/gateway/config-agents#messages)與 channel 文件。
詳細資訊：[設定](/zh-TW/gateway/config-agents#messages)與通道文件。
## 靜默回覆
精確的靜默權杖 `NO_REPLY` / `no_reply` 表示「不要投遞使用者可見的回覆」。
當某個回合同時有待處理的工具媒體（例如產生的 TTS 音訊）時，OpenClaw
會移除靜默文字，但仍會投遞媒體附件。
精確的靜默權杖 `NO_REPLY` / `no_reply` 表示「不要傳送使用者可見的回覆」。
當回合也有待處理的工具媒體時，例如產生的 TTS 音訊，OpenClaw
會移除靜默文字，但仍會傳送媒體附件。
OpenClaw 會依對話類型解析該行為：
- 直接對話預設不允許靜默，並會將單獨的靜默
回覆改寫為簡短的可見備援回覆。
- 群組/channel 預設允許靜默。
回覆改寫為簡短的可見備援。
- 群組/通道預設允許靜默。
- 內部編排預設允許靜默。
OpenClaw 也會針對非直接聊天中、任何助理回覆之前發生的內部執行器失敗使用靜默回覆，
因此群組/channel 不會看到
OpenClaw 也會將靜默回覆用於在非直接聊天中、任何助理回覆之前發生的
內部執行器失敗，因此群組/通道不會看到
Gateway 錯誤樣板文字。直接聊天預設會顯示精簡的失敗文案；
只有當 `/verbose` 為 `on` 或 `full` 時，才會顯示原始執行器詳細資訊。
預設值位於 `agents.defaults.silentReply` 與
`agents.defaults.silentReplyRewrite`；`surfaces.<id>.silentReply` 與
`surfaces.<id>.silentReplyRewrite` 可以針對每個介面覆寫它們。
`surfaces.<id>.silentReplyRewrite` 可以依表面覆寫它們。
當父工作階段有一個或多個待處理的已生成子 agent 執行時，單獨的
靜默回覆會在所有介面上被丟棄而不是被改寫，因此
父工作階段會保持安靜，直到子項完成事件投遞真正的回覆。
當父工作階段有一個或多個待處理的已產生子代理程式執行時，單獨的
靜默回覆會在所有表面上被捨棄，而不是被改寫，因此
父工作階段會保持安靜，直到子項完成事件傳送真正的回覆。
## 相關
- [串流](/zh-TW/concepts/streaming) — 即時訊息投遞
- [重試](/zh-TW/concepts/retry) — 訊息投遞重試行為
- [串流](/zh-TW/concepts/streaming) — 即時訊息傳送
- [重試](/zh-TW/concepts/retry) — 訊息傳送重試行為
- [佇列](/zh-TW/concepts/queue) — 訊息處理佇列
- [Channel](/zh-TW/channels) — 傳訊平台整合
- [通道](/zh-TW/channels) — 訊息平台整合

518
docs/zh-TW/gateway/config-agents.md
View File

@ -1,22 +1,20 @@
---
read_when:
- 調整代理預設值（模型、思考、工作區、Heartbeat、媒體、Skills）
- 設定多代理程式路由與繫結
- 調整工作階段、訊息傳遞和對話模式行為
summary: 代理預設值、多代理路由、工作階段、訊息與對話設定
- 設定多代理路由與綁定
- 調整工作階段、訊息傳遞和交談模式行為
summary: 代理程式預設值、多代理程式路由、工作階段、訊息與交談設定
title: 設定 — 代理程式
x-i18n:
generated_at: "2026-04-30T03:04:48Z"
generated_at: "2026-04-30T16:28:03Z"
model: gpt-5.5
provider: openai
source_hash: 61f2d33ae1d3f4ce07636ae4584b9e344fd14e8e08a2612bb1f39ed71c99c25a
source_hash: e6a38f42c35c6c6e46d6d00ad710c6c80d78703e0b7e3388f5631cf91eb17084
source_path: gateway/config-agents.md
workflow: 16
---
`agents.*`、`multiAgent.*`、`session.*`、
`messages.*` 和 `talk.*` 下的代理範圍設定鍵。若要查看通道、工具、Gateway 執行階段和其他
頂層鍵，請參閱[設定參考](/zh-TW/gateway/configuration-reference)。
`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 底下的代理範圍設定鍵。針對頻道、工具、Gateway 執行階段和其他頂層鍵，請參閱[設定參考](/zh-TW/gateway/configuration-reference)。
## 代理預設值
@ -32,7 +30,7 @@ x-i18n:
### `agents.defaults.repoRoot`
在系統提示 Runtime 行中顯示的選用儲存庫根目錄。若未設定，OpenClaw 會從工作區開始向上走訪來自動偵測。
可選的儲存庫根目錄，會顯示在系統提示的 Runtime 行中。若未設定，OpenClaw 會從工作區往上逐層自動偵測。
```json5
{
@ -42,7 +40,7 @@ x-i18n:
### `agents.defaults.skills`
未設定 `agents.list[].skills` 的代理可用的選用預設 Skills 允許清單。
未設定 `agents.list[].skills` 的代理可使用的可選預設 skill 允許清單。
```json5
{
@ -57,15 +55,14 @@ 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` 清單就是該代理的最終集合；它不會與預設值合併。
### `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
{
@ -75,10 +72,10 @@ x-i18n:
### `agents.defaults.contextInjection`
控制工作區啟動檔案何時注入系統提示。預設值：`"always"`。
控制何時將工作區啟動引導檔案注入系統提示。預設值：`"always"`。
- `"continuation-skip"`：安全的延續回合（在完成的助理回應之後）會跳過重新注入工作區啟動內容，以減少提示大小。Heartbeat 執行和 Compaction 後重試仍會重建脈絡。
- `"never"`：在每個回合都停用工作區啟動與脈絡檔案注入。僅適用於完全自行管理提示生命週期的代理（自訂脈絡引擎、會自行建立脈絡的原生執行階段，或專門不使用啟動流程的工作流程）。Heartbeat 和 Compaction 復原回合也會跳過注入。
- `"continuation-skip"`：安全的延續回合（在助理回應完成後）會跳過重新注入工作區啟動引導，降低提示大小。Heartbeat 執行和 Compaction 後重試仍會重建脈絡。
- `"never"`：在每個回合停用工作區啟動引導和脈絡檔案注入。僅適用於完全自行管理提示生命週期的代理（自訂脈絡引擎、會建立自身脈絡的原生執行階段，或不需要啟動引導的專用工作流程）。Heartbeat 和 Compaction 復原回合也會跳過注入。
```json5
{
@ -88,7 +85,7 @@ x-i18n:
### `agents.defaults.bootstrapMaxChars`
截斷前每個工作區啟動檔案的最大字元數。預設值：`12000`。
每個工作區啟動引導檔案在截斷前的最大字元數。預設值：`12000`。
```json5
{
@ -98,7 +95,7 @@ x-i18n:
### `agents.defaults.bootstrapTotalMaxChars`
跨所有工作區啟動檔案注入的最大總字元數。預設值：`60000`。
所有工作區啟動引導檔案合計注入的最大字元數。預設值：`60000`。
```json5
{
@ -108,11 +105,11 @@ x-i18n:
### `agents.defaults.bootstrapPromptTruncationWarning`
控制啟動脈絡被截斷時，代理可見的警告文字。
控制啟動引導脈絡被截斷時代理可見的警告文字。
預設值：`"once"`。
- `"off"`：絕不將警告文字注入系統提示。
- `"once"`：每個唯一截斷簽章注入一次警告（建議）。
- `"once"`：針對每個唯一的截斷簽章只注入一次警告（建議）。
- `"always"`：存在截斷時，每次執行都注入警告。
```json5
@ -121,35 +118,32 @@ x-i18n:
}
```
### 脈絡預算擁有權對照表
### 脈絡預算所有權對照表
OpenClaw 有多個高容量提示/脈絡預算，而且它們刻意依子系統拆分，
而不是全都流經一個通用旋鈕。
OpenClaw 有多個高容量提示／脈絡預算，而且這些預算刻意依子系統拆分，而不是全部流經單一通用旋鈕。
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`：
一般工作區啟動注入。
一般工作區啟動引導注入。
- `agents.defaults.startupContext.*`：
一次性重設/啟動模型執行序言，包括最近的每日
`memory/*.md` 檔案。裸聊天 `/new` 和 `/reset` 命令會在不叫用模型的情況下
確認重設。
一次性的重設／啟動模型執行前導內容，包括近期每日
`memory/*.md` 檔案。純聊天 `/new` 和 `/reset` 命令會在不叫用模型的情況下確認重設。
- `skills.limits.*`：
注入系統提示的精簡 Skills 清單。
- `agents.defaults.contextLimits.*`：
有界執行階段摘錄和注入的執行階段擁有區塊。
有界限的執行階段摘錄，以及由執行階段擁有並注入的區塊。
- `memory.qmd.limits.*`：
已索引記憶體搜尋片段與注入大小。
已索引記憶體搜尋片段和注入大小。
僅在某個代理需要不同預算時，才使用相符的每代理覆寫：
只有在某個代理需要不同預算時，才使用相符的逐代理覆寫：
- `agents.list[].skillsLimits.maxSkillsPromptChars`
- `agents.list[].contextLimits.*`
#### `agents.defaults.startupContext`
控制重設/啟動模型執行時，第一回合注入的啟動序言。
裸聊天 `/new` 和 `/reset` 命令會在不叫用模型的情況下確認重設，
因此不會載入此序言。
控制重設／啟動模型執行時，在第一回合注入的啟動前導內容。
純聊天 `/new` 和 `/reset` 命令會在不叫用模型的情況下確認重設，因此不會載入這段前導內容。
```json5
{
@ -170,7 +164,7 @@ OpenClaw 有多個高容量提示/脈絡預算，而且它們刻意依子系統
#### `agents.defaults.contextLimits`
有界執行階段脈絡介面的共用預設值。
有界限執行階段脈絡表面的共用預設值。
```json5
{
@ -187,15 +181,14 @@ OpenClaw 有多個高容量提示/脈絡預算，而且它們刻意依子系統
}
```
- `memoryGetMaxChars`：加入截斷中繼資料和延續通知前的預設 `memory_get` 摘錄上限。
- `memoryGetDefaultLines`：省略 `lines` 時的預設 `memory_get` 行視窗。
- `memoryGetMaxChars`：加入截斷中繼資料和接續通知前，預設的 `memory_get` 摘錄上限。
- `memoryGetDefaultLines`：省略 `lines` 時，預設的 `memory_get` 行視窗。
- `toolResultMaxChars`：用於持久化結果和溢位復原的即時工具結果上限。
- `postCompactionMaxChars`：Compaction 後重新整理注入期間使用的 AGENTS.md 摘錄上限。
#### `agents.list[].contextLimits`
共用 `contextLimits` 旋鈕的每代理覆寫。省略的欄位會繼承
`agents.defaults.contextLimits`。
共用 `contextLimits` 旋鈕的逐代理覆寫。省略的欄位會繼承自 `agents.defaults.contextLimits`。
```json5
{
@ -221,8 +214,7 @@ OpenClaw 有多個高容量提示/脈絡預算，而且它們刻意依子系統
#### `skills.limits.maxSkillsPromptChars`
注入系統提示的精簡 Skills 清單全域上限。這
不會影響依需求讀取 `SKILL.md` 檔案。
注入系統提示的精簡 Skills 清單全域上限。這不會影響按需讀取 `SKILL.md` 檔案。
```json5
{
@ -236,7 +228,7 @@ OpenClaw 有多個高容量提示/脈絡預算，而且它們刻意依子系統
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
Skills 提示預算的每代理覆寫。
Skills 提示預算的逐代理覆寫。
```json5
{
@ -255,10 +247,10 @@ Skills 提示預算的每代理覆寫。
### `agents.defaults.imageMaxDimensionPx`
在提供者呼叫前，逐字記錄/工具影像區塊中影像最長邊的最大像素尺寸。
供應商呼叫前，轉錄／工具圖片區塊中圖片最長邊的最大像素尺寸。
預設值：`1200`。
較低的值通常會減少大量截圖執行時的視覺權杖用量和請求酬載大小。
較低的值通常會降低大量截圖執行時的視覺權杖用量和請求承載大小。
較高的值會保留更多視覺細節。
```json5
@ -339,57 +331,53 @@ Skills 提示預算的每代理覆寫。
- `model`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 字串形式只設定主要模型。
- 物件形式設定主要模型加上有順序的故障轉移模型。
- 物件形式設定主要模型加上依序排列的容錯移轉模型。
- `imageModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由 `image` 工具路徑作為其視覺模型設定使用。
- 當選取的/預設模型無法接受圖片輸入時，也會作為備援路由使用。
- 優先使用明確的 `provider/model` 參照。為了相容性也接受裸 ID；如果裸 ID 在 `models.providers.*.models` 中唯一符合已設定且具備圖片能力的項目，OpenClaw 會將其限定到該供應商。模稜兩可的已設定符合項目需要明確的供應商前綴。
- 也會在所選/預設模型無法接受圖片輸入時，用作備援路由。
- 建議使用明確的 `provider/model` 參照。裸 ID 會為了相容性而被接受；如果裸 ID 唯一符合 `models.providers.*.models` 中已設定且支援圖片的項目，OpenClaw 會將其限定到該提供者。已設定的符合項目若有歧義，則需要明確的提供者前綴。
- `imageGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由共用圖片生成功能，以及任何未來會產生圖片的工具/Plugin 介面使用。
- 典型值：`google/gemini-3.1-flash-image-preview` 用於原生 Gemini 圖片生成、`fal/fal-ai/flux/dev` 用於 fal、`openai/gpt-image-2` 用於 OpenAI Images，或 `openai/gpt-image-1.5` 用於透明背景 OpenAI PNG/WebP 輸出。
- 如果你直接選取供應商/模型，也請設定對應的供應商驗證（例如 `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 情境。
- `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 '<json>' --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 相容的 chat-template 引數，會合併到頂層 `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 宣告支援的模型、已註冊的 harness ID（例如 `id: "codex"`），或支援的 CLI 後端別名（例如 `id: "claude-cli"`）。設定 `fallback: "none"` 可停用自動 PI 備援。明確的 Plugin 執行階段（例如 `codex`）預設會以封閉方式失敗，除非你在同一個覆寫範圍設定 `fallback: "pi"`。請將模型參照保持為標準的 `provider/model`；透過執行階段設定選取 Codex、Claude CLI、Gemini CLI 與其他執行後端，而不是使用舊版執行階段供應商前綴。請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)，了解這與供應商/模型選取有何不同。
- 會變更這些欄位的設定寫入器（例如 `/models set`、`/models set-image`，以及備援新增/移除命令）會儲存標準物件形式，並在可能時保留現有備援清單。
- `maxConcurrent`：跨工作階段的最大並行代理程式執行數（每個工作階段本身仍會序列化）。預設：4。
- `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 '<json>' --strict-json --merge` 新增項目。除非傳入 `--replace`，否則 `config set` 會拒絕會移除既有允許清單項目的替換。
- 提供者範圍的設定/導入流程會將所選提供者模型合併到此映射，並保留已設定的無關提供者。
- 對於直接 OpenAI Responses 模型，伺服器端壓縮會自動啟用。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆寫閾值。請參閱 [OpenAI 伺服器端壓縮](/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"` 請求主體。對於關閉 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 相容推理 effort 清單。對於真正接受它的自訂端點，請包含 `"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 宣告支援的模型，使用已註冊的 harness ID（例如 `id: "codex"`），或使用支援的 CLI 後端別名（例如 `id: "claude-cli"`）。設定 `fallback: "none"` 可停用自動 PI 備援。明確的 Plugin 執行階段（例如 `codex`）預設會封閉失敗，除非你在相同覆寫範圍內設定 `fallback: "pi"`。將模型參照保持為標準 `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）時使用它。關於心智
模型，請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)。
`agentRuntime` 控制哪個低階執行器會執行代理程式回合。大多數部署應保留預設 OpenClaw Pi 執行階段。當受信任的 Plugin 提供原生 harness（例如隨附的 Codex 應用程式伺服器 harness），或你想使用支援的 CLI 後端（例如 Claude CLI）時，請使用它。若要了解心智模型，請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)。
```json5
{
@ -406,15 +394,15 @@ Plugin 提供原生 harness（例如隨附的 Codex app-server harness），
```
- `id`：`"auto"`、`"pi"`、已註冊的 Plugin harness ID，或支援的 CLI 後端別名。隨附的 Codex Plugin 會註冊 `codex`；隨附的 Anthropic Plugin 提供 `claude-cli` CLI 後端。
- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的 fallback 預設為 `"pi"`，讓舊設定在沒有 Plugin harness 宣告某次執行時仍可繼續使用 PI。在明確的 Plugin 執行階段模式中，例如 `id: "codex"`，省略的 fallback 預設為 `"none"`，因此缺少 harness 時會失敗，而不是默默使用 PI。執行階段覆寫不會從較廣範圍繼承 fallback；當你有意要該相容性備援時，請在明確執行階段旁一併設定 `fallback: "pi"`。選取的 Plugin harness 失敗一律會直接顯示。
- 環境覆寫：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 覆寫 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆寫該程序的 fallback。
- 對於僅 Codex 的部署，請設定 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以明確設定 `agentRuntime.fallback: "none"` 以提高可讀性；這是明確 Plugin 執行階段的預設值。
- 對於 Claude CLI 部署，請優先使用 `model: "anthropic/claude-opus-4-7"` 加上 `agentRuntime.id: "claude-cli"`。舊版 `claude-cli/claude-opus-4-7` 模型參照仍可用於相容性，但新設定應保持供應商/模型選取的標準形式，並將執行後端放在 `agentRuntime.id`。
- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略 fallback 時預設為 `"pi"`，讓舊設定可在沒有 Plugin harness 宣告執行時繼續使用 PI。在明確 Plugin 執行階段模式中，例如 `id: "codex"`，省略 fallback 時預設為 `"none"`，因此缺少 harness 會失敗，而不是靜默使用 PI。執行階段覆寫不會從更廣範圍繼承 fallback；當你有意要該相容性備援時，請在明確執行階段旁設定 `fallback: "pi"`。所選 Plugin harness 失敗一律會直接浮現。
- 環境覆寫：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 會覆寫 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 會覆寫該程序的 fallback。
- 對於僅 Codex 的部署，請設定 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以為了可讀性明確設定 `agentRuntime.fallback: "none"`；這是明確 Plugin 執行階段的預設值。
- 對於 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 固定。設定/環境變更會影響新的或重設的工作階段，而不是既有的 transcript。具有 transcript 歷史但沒有記錄固定項目的舊版工作階段，會被視為已固定到 PI。`/status` 會回報有效的執行階段，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 這只控制文字代理程式回合執行。媒體生成、視覺、PDF、音樂、影片和 TTS 仍使用其供應商/模型設定。
- Harness 選擇會在第一次嵌入式執行後依工作階段 ID 釘選。設定/env 變更會影響新的或重設的工作階段，不會影響既有逐字稿。有逐字稿歷史但沒有記錄釘選的舊版工作階段，會視為已釘選 PI。`/status` 會回報有效執行階段，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 這只控制文字代理程式回合執行。媒體生成、視覺、PDF、音樂、影片和 TTS 仍會使用各自的提供者/模型設定。
**內建別名縮寫**（僅在模型位於 `agents.defaults.models` 時套用）：
**內建別名簡寫**（僅在模型位於 `agents.defaults.models` 時套用）：
| 別名 | 模型 |
| ------------------- | ------------------------------------------ |
@ -427,15 +415,15 @@ Plugin 提供原生 harness（例如隨附的 Codex app-server harness），
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
你設定的別名永遠優先於預設值。
你設定的別名一律優先於預設值。
Z.AI GLM-4.x 模型會自動啟用思考模式，除非你設定 `--thinking off`，或自行定義 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型預設會啟用 `tool_stream` 以進行工具呼叫串流。將 `agents.defaults.models["zai/<model>"].params.tool_stream` 設為 `false` 即可停用。
Z.AI 模型預設會啟用 `tool_stream` 以串流工具呼叫。將 `agents.defaults.models["zai/<model>"].params.tool_stream` 設為 `false` 即可停用。
Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `adaptive` 思考。
### `agents.defaults.cliBackends`
用於純文字備援執行的選用 CLI 後端（無工具呼叫）。在 API 提供者失敗時可作為備份。
文字專用備援執行的選用 CLI 後端（無工具呼叫）。當 API 提供者失敗時，可作為備份使用。
```json5
{
@ -464,13 +452,13 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
}
```
- CLI 後端以文字優先；工具一律停用。
- CLI 後端以文字為優先；工具一律停用。
- 設定 `sessionArg` 時支援工作階段。
- 當 `imageArg` 接受檔案路徑時，支援影像傳遞。
### `agents.defaults.systemPromptOverride`
以固定字串取代整個由 OpenClaw 組裝的系統提示。可在預設層級（`agents.defaults.systemPromptOverride`）或每個代理（`agents.list[].systemPromptOverride`）設定。每個代理的值優先；空值或僅含空白的值會被忽略。適合用於受控提示實驗。
以固定字串取代整個由 OpenClaw 組裝的系統提示。可在預設層級（`agents.defaults.systemPromptOverride`）或各代理（`agents.list[].systemPromptOverride`）設定。各代理的值優先；空值或僅含空白的值會被忽略。適合受控的提示實驗。
```json5
{
@ -484,7 +472,7 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
### `agents.defaults.promptOverlays`
依模型系列套用、與提供者無關的提示覆蓋。GPT-5 系列模型 ID 會在不同提供者間套用共用行為契約；`personality` 只控制友善互動風格層。
依模型系列套用、與提供者無關的提示覆蓋。GPT-5 系列模型 ID 會跨提供者接收共用的行為契約；`personality` 只控制友善互動風格層。
```json5
{
@ -501,12 +489,12 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
```
- `"friendly"`（預設）和 `"on"` 會啟用友善互動風格層。
- `"off"` 只會停用友善層；標記的 GPT-5 行為契約仍會保持啟用。
- 舊版 `plugins.entries.openai.config.personality` 在未設定此共用設定時仍會被讀取。
- `"off"` 只停用友善層；已標記的 GPT-5 行為契約仍會啟用。
- 未設定此共用設定時，仍會讀取舊版 `plugins.entries.openai.config.personality`。
### `agents.defaults.heartbeat`
定期 Heartbeat 執行。
週期性 Heartbeat 執行。
```json5
{
@ -534,16 +522,16 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
}
```
- `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 執行會在額外忙碌通道上延後：子代理或巢狀命令工作。Cron 通道一律會延後 Heartbeat，即使沒有此旗標也是如此。
- 每個代理：設定 `agents.list[].heartbeat`。當任何代理定義 `heartbeat` 時，**只有那些代理**會執行 Heartbeat。
- Heartbeat 會執行完整代理回合 — 較短的間隔會消耗更多 token。
- `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 執行會在額外繁忙通道上延後：子代理或巢狀命令工作。Cron 通道一律會延後 Heartbeat，即使未設定此旗標。
- 各代理：設定 `agents.list[].heartbeat`。當任何代理定義 `heartbeat` 時，**只有那些代理**會執行 Heartbeat。
- Heartbeat 會執行完整代理回合，間隔越短會消耗越多 token。
### `agents.defaults.compaction`
@ -560,6 +548,7 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
identifierPolicy: "strict", // strict | off | custom
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
qualityGuard: { enabled: true, maxRetries: 1 },
midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
@ -578,22 +567,23 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
}
```
- `mode`：`default` 或 `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 會是一個硬檢查點。
- `mode`：`default` 或 `safeguard`（長歷史的分塊摘要）。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `provider`：已註冊 Compaction 提供者 Plugin 的 ID。設定後，會呼叫提供者的 `summarize()`，而非內建 LLM 摘要。失敗時會回退到內建摘要。設定提供者會強制 `mode: "safeguard"`。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `timeoutSeconds`：OpenClaw 中止單次 Compaction 操作前允許的最長秒數。預設：`900`。
- `keepRecentTokens`：用於逐字保留最近轉錄尾端的 Pi 切點預算。手動 `/compact` 在明確設定時會遵循此值；否則手動 Compaction 是硬檢查點。
- `identifierPolicy`：`strict`（預設）、`off` 或 `custom`。`strict` 會在 Compaction 摘要期間前置內建的不透明識別碼保留指引。
- `identifierInstructions`：當 `identifierPolicy=custom` 時使用的選用自訂識別碼保留文字。
- `qualityGuard`：用於 safeguard 摘要的格式錯誤輸出重試檢查。在 safeguard 模式中預設啟用；設定 `enabled: false` 可跳過稽核。
- `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`；此覆蓋不會繼承作用中工作階段的備援鏈。工作區唯讀時會跳過。
- `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` 設為精確的 provider/model，例如 `ollama/qwen3:8b`；此覆蓋不會繼承作用中工作階段的備援鏈。工作區為唯讀時會略過。
### `agents.defaults.contextPruning`
在傳送給 LLM 前，從記憶體內內容脈絡修剪**舊工具結果**。**不會**修改磁碟上的工作階段歷史。
在傳送到 LLM 前，從記憶體內容中修剪**舊工具結果**。**不會**修改磁碟上的工作階段歷史。
```json5
{
@ -615,25 +605,25 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
}
```
<Accordion title="cache-ttl mode behavior">
<Accordion title="cache-ttl 模式行為">
- `mode: "cache-ttl"` 會啟用修剪流程。
- `ttl` 控制修剪多久可以再次執行（在上次觸碰快取之後）。
- 修剪會先軟修剪過大的工具結果，然後在需要時硬清除較舊的工具結果。
- `ttl` 控制修剪可再次執行的頻率（在最後一次快取觸碰之後）。
- 修剪會先軟修剪過大的工具結果，接著視需要硬清除較舊的工具結果。
**軟修剪**會保留開頭 + 結尾，並在中間插入 `...`。
**硬清除**會以預留位置取代整個工具結果。
**硬清除**會以佔位符取代整個工具結果。
注意：
注意事項：
- 影像區塊絕不會被修剪/清除。
- 比率是以字元為基礎（近似值），不是精確的 token 數。
- 如果助理訊息少於 `keepLastAssistants`，會跳過修剪。
- 影像區塊永遠不會被修剪/清除。
- 比率以字元為基準（近似值），不是精確 token 數。
- 如果助理訊息少於 `keepLastAssistants` 則會略過修剪。
</Accordion>
請參閱 [Session Pruning](/zh-TW/concepts/session-pruning) 以了解行為詳細資料。
請參閱 [工作階段修剪](/zh-TW/concepts/session-pruning) 了解行為詳細資料。
### 區塊串流
@ -651,11 +641,11 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
}
```
- 非 Telegram 頻道需要明確設定 `*.blockStreaming: true` 才能啟用區塊回覆。
- 頻道覆蓋：`channels.<channel>.blockStreamingCoalesce`（以及每個帳號的變體）。Signal/Slack/Discord/Google Chat 預設 `minChars: 1500`。
- `humanDelay`：區塊回覆之間的隨機暫停。`natural` = 800–2500ms。每個代理覆蓋：`agents.list[].humanDelay`。
- 非 Telegram 通道需要明確設定 `*.blockStreaming: true` 才能啟用區塊回覆。
- 通道覆寫：`channels.<channel>.blockStreamingCoalesce`（以及各帳號變體）。Signal/Slack/Discord/Google Chat 預設為 `minChars: 1500`。
- `humanDelay`：區塊回覆之間的隨機暫停。`natural` = 800–2500ms。每個代理程式覆寫：`agents.list[].humanDelay`。
請參閱 [Streaming](/zh-TW/concepts/streaming) 以了解行為 + 分塊詳細資料。
請參閱[串流](/zh-TW/concepts/streaming)，了解行為與分塊詳細資訊。
### 輸入中指示器
@ -670,7 +660,7 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
}
```
- 預設值：直接聊天/提及使用 `instant`，未提及的群組聊天使用 `message`。
- 預設值：直接聊天/提及為 `instant`，未提及的群組聊天為 `message`。
- 每個工作階段覆寫：`session.typingMode`、`session.typingIntervalSeconds`。
請參閱[輸入中指示器](/zh-TW/concepts/typing-indicators)。
@ -679,7 +669,7 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
### `agents.defaults.sandbox`
內嵌代理程式的選用沙盒化。完整指南請參閱[沙盒化](/zh-TW/gateway/sandboxing)。
嵌入式代理程式的選用沙盒化。完整指南請參閱[沙盒化](/zh-TW/gateway/sandboxing)。
```json5
{
@ -779,47 +769,47 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
**後端：**
- `docker`：本機 Docker 執行階段（預設）
- `ssh`：一般的 SSH 支援遠端執行階段
- `ssh`：通用的 SSH 支援遠端執行階段
- `openshell`：OpenShell 執行階段
選取 `backend: "openshell"` 時，執行階段專屬設定會移至
選取 `backend: "openshell"` 時，執行階段專用設定會移至
`plugins.entries.openshell.config`。
**SSH 後端設定：**
- `target`：`user@host[:port]` 形式的 SSH 目標
- `command`：SSH 用戶端指令（預設：`ssh`）
- `workspaceRoot`：用於每個作用域工作區的絕對遠端根目錄
- `command`：SSH 用戶端命令（預設：`ssh`）
- `workspaceRoot`：用於各範圍工作區的絕對遠端根目錄
- `identityFile` / `certificateFile` / `knownHostsFile`：傳遞給 OpenSSH 的現有本機檔案
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在執行階段具現化為暫存檔的內嵌內容或 SecretRefs
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主機金鑰策略控制項
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在執行階段具體化為暫存檔案的內嵌內容或 SecretRefs
- `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`：每個工作階段各自的容器與工作區
- `session`：每個工作階段一個容器與工作區
- `agent`：每個代理程式一個容器與工作區（預設）
- `shared`：共用容器和工作區（沒有跨工作階段隔離）
- `shared`：共用容器與工作區（無跨工作階段隔離）
**OpenShell Plugin 設定：**
@ -849,29 +839,29 @@ Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `ada
**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"`（或自訂 bridge 網路）。
`"host"` 會被封鎖。除非你明確設定
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急例外），否則預設會封鎖 `"container:<id>"`。
**容器預設為 `network: "none"`** — 如果代理程式需要對外存取，請設定為 `"bridge"`（或自訂橋接網路）。
`"host"` 會被阻擋。`"container:<id>"` 預設會被阻擋，除非你明確設定
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急破例）。
**傳入附件** 會暫存到作用中工作區的 `media/inbound/*`。
**`docker.binds`** 會掛載其他主機目錄；全域和每個代理程式的繫結會合併。
**`docker.binds`** 會掛載額外的主機目錄；全域與每個代理程式的繫結會合併。
**沙盒瀏覽器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 會注入系統提示。不需要在 `openclaw.json` 中啟用 `browser.enabled`。
noVNC 觀察者存取預設使用 VNC 驗證，OpenClaw 會發出短效權杖 URL（而不是在共用 URL 中暴露密碼）。
**沙盒化瀏覽器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 會注入系統提示。不需要在 `openclaw.json` 中設定 `browser.enabled`。
noVNC 觀察者存取預設使用 VNC 驗證，且 OpenClaw 會發出短效權杖 URL（而不是在共用 URL 中公開密碼）。
- `allowHostControl: false`（預設）會阻止沙盒化工作階段將主機瀏覽器作為目標。
- `network` 預設為 `openclaw-sandbox-browser`（專用 bridge 網路）。只有在你明確需要全域 bridge 連線時，才設為 `bridge`。
- `cdpSourceRange` 可選擇性地在容器邊界將 CDP 入口限制為 CIDR 範圍（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 只會將額外主機目錄掛載到沙盒瀏覽器容器中。設定時（包括 `[]`），它會取代瀏覽器容器的 `docker.binds`。
- `allowHostControl: false`（預設）會阻止沙盒化工作階段鎖定主機瀏覽器。
- `network` 預設為 `openclaw-sandbox-browser`（專用橋接網路）。只有在你明確想要全域橋接連線時，才設定為 `bridge`。
- `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=<derived from OPENCLAW_BROWSER_CDP_PORT>`
@ -890,20 +880,20 @@ noVNC 觀察者存取預設使用 VNC 驗證，OpenClaw 會發出短效權杖 UR
- `--no-zygote`
- `--metrics-recording-only`
- `--disable-extensions`（預設啟用）
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
預設啟用；如果 WebGL/3D 使用情境需要，可以用
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 預設為
啟用；如果 WebGL/3D 使用需要，可透過
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 停用。
- 如果你的工作流程依賴擴充功能，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 會重新啟用擴充功能。
- `--renderer-process-limit=2` 可用
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 變更；設為 `0` 則使用 Chromium
- `--renderer-process-limit=2` 可透過
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 變更；設定為 `0` 可使用 Chromium 的
預設程序限制。
- 當啟用 `noSandbox` 時，另加 `--no-sandbox`。
- 預設值是容器映像基準；若要變更容器預設值，請使用含自訂
- 啟用 `noSandbox` 時，另加 `--no-sandbox`。
- 預設值是容器映像基準；若要變更容器預設值，請使用具有自訂
進入點的自訂瀏覽器映像。
</Accordion>
瀏覽器沙盒化和 `sandbox.docker.binds` 僅適用於 Docker。
瀏覽器沙盒化與 `sandbox.docker.binds` 僅限 Docker。
建置映像：
@ -915,11 +905,11 @@ scripts/sandbox-browser-setup.sh # optional browser image
### `agents.list`（每個代理程式覆寫）
使用 `agents.list[].tts` 可為代理程式指定自己的 TTS 提供者、語音、模型、
風格或自動 TTS 模式。代理程式區塊會深度合併到全域
`messages.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
{
@ -973,28 +963,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 控制框架工作階段時，請搭配 `runtime.acp` 預設值（`agent`、`backend`、`mode`、`cwd`）使用 `type: "acp"`。
- `identity.avatar`：工作區相對路徑、`http(s)` URL，或 `data:` URI。
- `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）。
- `subagents.allowAgents`：明確 `sessions_spawn.agentId` 目標的代理程式 ID 允許清單（`["*"]` = 任何；預設：僅相同代理程式）。當應允許自我目標的 `agentId` 呼叫時，請包含請求者 ID。
- 沙箱繼承保護：如果請求者工作階段已沙箱化，`sessions_spawn` 會拒絕將在非沙箱中執行的目標。
- `subagents.requireAgentId`：為 true 時，封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選取設定檔；預設：false）。
---
## 多代理路由
## 多代理程式路由
在一個 Gateway 內執行多個隔離代理。請參閱[多代理](/zh-TW/concepts/multi-agent)。
在一個 Gateway 內執行多個隔離的代理程式。請參閱[多代理程式](/zh-TW/concepts/multi-agent)。
```json5
{
@ -1013,9 +1003,9 @@ scripts/sandbox-browser-setup.sh # optional browser image
### 繫結比對欄位
- `type`（選用）：一般路由使用 `route`（缺少 type 時預設為 route），持續性 ACP 對話繫結使用 `acp`。
- `type`（選用）：`route` 用於一般路由（缺少類型時預設為 route），`acp` 用於持續性 ACP 對話繫結。
- `match.channel`（必填）
- `match.accountId`（選用；`*` = 任意帳號；省略 = 預設帳號）
- `match.accountId`（選用；`*` = 任何帳號；省略 = 預設帳號）
- `match.peer`（選用；`{ kind: direct|group|channel, id }`）
- `match.guildId` / `match.teamId`（選用；通道專屬）
- `acp`（選用；僅適用於 `type: "acp"`）：`{ mode, label, cwd, backend }`
@ -1027,15 +1017,15 @@ scripts/sandbox-browser-setup.sh # optional browser image
3. `match.teamId`
4. `match.accountId`（精確，沒有 peer/guild/team）
5. `match.accountId: "*"`（整個通道）
6. 預設代理
6. 預設代理程式
在每個層級內，第一個相符的 `bindings` 項目會生效。
在每個層級中，第一個相符的 `bindings` 項目會生效。
對於 `type: "acp"` 項目，OpenClaw 會依精確的對話身分（`match.channel` + 帳號 + `match.peer.id`）解析，且不使用上述路由繫結層級順序。
對於 `type: "acp"` 項目，OpenClaw 會依精確對話身分解析（`match.channel` + 帳號 + `match.peer.id`），而不使用上方的路由繫結層級順序。
### 每代理存取設定檔
### 各代理程式存取設定檔
<Accordion title="完整存取權（無沙盒）">
<Accordion title="完整存取權（無沙箱）">
```json5
{
@ -1082,7 +1072,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
<Accordion title="無檔案系統存取權（僅訊息傳送）">
<Accordion title="無檔案系統存取權（僅訊息傳遞）">
```json5
{
@ -1128,7 +1118,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
優先順序詳細資料請參閱[多代理沙盒與工具](/zh-TW/tools/multi-agent-sandbox-tools)。
如需優先順序詳細資料，請參閱[多代理程式沙箱與工具](/zh-TW/tools/multi-agent-sandbox-tools)。
---
@ -1181,34 +1171,34 @@ scripts/sandbox-browser-setup.sh # optional browser image
<Accordion title="工作階段欄位詳細資料">
- **`scope`**：群組聊天情境的基礎工作階段分組策略。
- `per-sender`（預設）：每個傳送者在通道情境內取得隔離的工作階段。
- `global`：通道情境中的所有參與者共用單一工作階段（僅在有意使用共用情境時使用）。
- `per-sender`（預設）：每位傳送者在一個頻道情境中取得隔離的工作階段。
- `global`：頻道情境中的所有參與者共用單一工作階段（僅在有意使用共用情境時使用）。
- **`dmScope`**：DM 的分組方式。
- `main`：所有 DM 共用主要工作階段。
- `per-peer`：跨通道依傳送者 id 隔離。
- `per-channel-peer`：依通道 + 傳送者隔離（建議用於多使用者收件匣）。
- `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` 的別名。
- **`parentForkMaxTokens`**：建立分支執行緒工作階段時，允許的父工作階段 `totalTokens` 最大值（預設 `100000`）。
- 若父 `totalTokens` 高於此值，OpenClaw 會啟動新的執行緒工作階段，而不是繼承父轉錄歷史。
- 設定 `0` 可停用此保護，並一律允許父工作階段分支。
- `main`：所有 DM 共用主工作階段。
- `per-peer`：跨頻道依傳送者 ID 隔離。
- `per-channel-peer`：依頻道 + 傳送者隔離（建議用於多使用者收件匣）。
- `per-account-channel-peer`：依帳號 + 頻道 + 傳送者隔離（建議用於多帳號）。
- **`identityLinks`**：將 canonical ID 對應到帶有提供者前綴的對等端，以便跨頻道共用工作階段。`/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` 的別名。
- **`parentForkMaxTokens`**：建立分叉執行緒工作階段時允許的父工作階段 `totalTokens` 上限（預設 `100000`）。
- 如果父層 `totalTokens` 高於此值，OpenClaw 會啟動新的執行緒工作階段，而不是繼承父層逐字稿歷史。
- 設為 `0` 可停用此防護，並一律允許父層分叉。
- **`mainKey`**：舊版欄位。執行階段一律使用 `"main"` 作為主要直接聊天儲存桶。
- **`agentToAgent.maxPingPongTurns`**：代理對代理交換期間，代理之間回覆來回的最大回合數（整數，範圍：`0`–`5`）。`0` 會停用來回串接。
- **`sendPolicy`**：依 `channel`、`chatType`（`direct|group|channel`，含舊版 `dm` 別名）、`keyPrefix` 或 `rawKeyPrefix` 進行比對。第一個拒絕會生效。
- **`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.<timestamp>` 轉錄封存的保留期。預設為 `pruneAfter`；設定 `false` 可停用。
- `maxDiskBytes`：選用的工作階段目錄磁碟預算。在 `warn` 模式下會記錄警告；在 `enforce` 模式下會優先移除最舊的成品/工作階段。
- `pruneAfter`：過期項目的年齡截止點（預設 `30d`）。
- `maxEntries`：`sessions.json` 中的項目數上限（預設 `500`）。執行階段會以小型高水位緩衝區批次寫入清理，供生產規模上限使用；`openclaw sessions cleanup --enforce` 會立即套用上限。
- `rotateBytes`：已棄用並被忽略；`openclaw doctor --fix` 會將其從較舊的設定中移除。
- `resetArchiveRetention`：`*.reset.<timestamp>` 逐字稿封存的保留期限。預設為 `pruneAfter`；設為 `false` 可停用。
- `maxDiskBytes`：選用的工作階段目錄磁碟預算。在 `warn` 模式下會記錄警告；在 `enforce` 模式下會先移除最舊的成品/工作階段。
- `highWaterBytes`：預算清理後的選用目標。預設為 `maxDiskBytes` 的 `80%`。
- **`threadBindings`**：執行緒繫結工作階段功能的全域預設值。
- `enabled`：主要預設開關（提供者可覆寫；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：預設閒置自動取消聚焦的小時數（`0` 會停用；提供者可覆寫）
- `maxAgeHours`：預設硬性最長存在時間的小時數（`0` 會停用；提供者可覆寫）
- **`threadBindings`**：執行緒綁定工作階段功能的全域預設值。
- `enabled`：主要預設開關（提供者可以覆寫；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：預設非作用中自動取消聚焦的小時數（`0` 會停用；提供者可以覆寫）
- `maxAgeHours`：預設硬性最大年齡的小時數（`0` 會停用；提供者可以覆寫）
</Accordion>
@ -1244,38 +1234,38 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
### 回覆前綴
### 回應前綴
每個通道/帳戶的覆寫：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
每個頻道/帳號的覆寫：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.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}` | 代理身分名稱 | （與 `"auto"` 相同） |
| 變數 | 說明 | 範例 |
| ----------------- | ------------------ | --------------------------- |
| `{model}` | 簡短模型名稱 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型識別碼 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供者名稱 | `anthropic` |
| `{thinkingLevel}` | 目前思考層級 | `high`, `low`, `off` |
| `{identity.name}` | 代理身分名稱 | （與 `"auto"` 相同） |
變數不區分大小寫。`{think}` 是 `{thinkingLevel}` 的別名。
### 確認反應
- 預設為作用中代理程式的 `identity.emoji`，否則為 `"👀"`。設定為 `""` 可停用。
- 每個通道的覆寫：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析順序：帳戶 → 通道 → `messages.ackReaction` → 身分後備值。
- 預設為作用中代理的 `identity.emoji`，否則為 `"👀"`。設為 `""` 可停用。
- 每個頻道的覆寫：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析順序：帳號 → 頻道 → `messages.ackReaction` → 身分後援。
- 範圍：`group-mentions`（預設）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支援反應的通道上，回覆後移除確認反應。
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上啟用生命週期狀態反應。
在 Slack 和 Discord 上，未設定時會在確認反應啟用時保持狀態反應啟用。
在 Telegram 上，請明確設定為 `true` 以啟用生命週期狀態反應。
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 與 BlueBubbles 等支援反應的頻道上，回覆後移除確認反應。
- `messages.statusReactions.enabled`：在 Slack、Discord 與 Telegram 上啟用生命週期狀態反應。
在 Slack 與 Discord 上，未設定時會在確認反應啟用時保持狀態反應啟用。
在 Telegram 上，請明確將其設為 `true` 以啟用生命週期狀態反應。
### 傳入去抖動
### 傳入去抖
將同一寄件者快速傳入的純文字訊息批次合併為單一代理程式回合。媒體/附件會立即送出。控制命令會略過去抖動。
將同一傳送者快速傳來的純文字訊息批次合併為單一代理輪次。媒體/附件會立即清空批次。控制命令會略過去抖。
### TTS（文字轉語音）
@ -1325,19 +1315,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）。
語音對話模式（macOS/iOS/Android）的預設值。
```json5
{
@ -1366,16 +1356,16 @@ Talk 模式的預設值（macOS/iOS/Android）。
}
```
- 設定多個 Talk 提供者時，`talk.provider` 必須符合 `talk.providers` 中的某個鍵。
- 舊版扁平 Talk 鍵（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）僅供相容性使用，並會自動遷移到 `talk.providers.<provider>`。
- 語音 ID 會後備使用 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受純文字字串或 SecretRef 物件。
- 只有在未設定 Talk API 金鑰時，才會套用 `ELEVENLABS_API_KEY` 後備值。
- `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`）。
- 設定多個語音對話提供者時，`talk.provider` 必須符合 `talk.providers` 中的某個鍵。
- 舊版扁平語音對話鍵（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）僅供相容使用，並會自動遷移到 `talk.providers.<provider>`。
- 語音 ID 會後援至 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受明文字串或 SecretRef 物件。
- `ELEVENLABS_API_KEY` 後援僅在未設定語音對話 API 金鑰時套用。
- `providers.*.voiceAliases` 允許語音對話指令使用易記名稱。
- `providers.mlx.modelId` 會選擇 macOS 本地 MLX 輔助程式使用的 Hugging Face repo。若省略，macOS 會使用 `mlx-community/Soprano-80M-bf16`。
- macOS MLX 播放會在存在時透過內建的 `openclaw-mlx-tts` 輔助程式執行，或使用 `PATH` 上的可執行檔；`OPENCLAW_MLX_TTS_BIN` 會覆寫開發用輔助程式路徑。
- `speechLocale` 設定 iOS/macOS 語音對話語音辨識所使用的 BCP 47 語言環境 ID。保持未設定可使用裝置預設值。
- `silenceTimeoutMs` 控制語音對話模式在使用者靜音後等待多久才傳送逐字稿。未設定時會保留平台預設暫停時間窗（`macOS 與 Android 為 700 ms，iOS 為 900 ms`）。
---

349
docs/zh-TW/gateway/config-channels.md
View File

@ -1,54 +1,54 @@
---
read_when:
- 設定通道 Plugin（身分驗證、存取控制、多帳戶）
- 設定通道 Plugin（驗證、存取控制、多帳號）
- 各通道設定鍵疑難排解
- 稽核私訊政策、群組政策或提及閘控
summary: 頻道設定：存取控制、配對，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等各頻道金鑰
- 稽核 DM 政策、群組政策或提及控管
summary: 通道設定：涵蓋 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的存取控制、配對與每個通道的金鑰
title: 設定 — 通道
x-i18n:
generated_at: "2026-04-30T03:04:46Z"
generated_at: "2026-04-30T16:28:44Z"
model: gpt-5.5
provider: openai
source_hash: e16ab50020711aac8e06cd234739ac7b566420cf7ce8621c0aca12c22484f07f
source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915
source_path: gateway/config-channels.md
workflow: 16
---
`channels.*` 下的每通道設定鍵。涵蓋 DM 與群組存取、多帳號設定、提及門檻，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他內建通道 plugins 的每通道金鑰。
`channels.*` 下的各頻道設定鍵。涵蓋 DM 與群組存取、多帳號設定、提及控管，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 與其他內建頻道 Plugin 的各頻道鍵。
若要了解代理、工具、Gateway 執行階段，以及其他頂層鍵，請參閱
如需代理、工具、Gateway 執行階段與其他頂層鍵，請參閱
[設定參考](/zh-TW/gateway/configuration-reference)。
## 通道
## 頻道
每個通道會在其設定區段存在時自動啟動（除非 `enabled: false`）。
每個頻道都會在其設定區段存在時自動啟動（除非 `enabled: false`）。
### DM 與群組存取
所有通道都支援 DM 政策與群組政策：
所有頻道都支援 DM 政策與群組政策：
| DM 政策 | 行為 |
| DM 政策 | 行為 |
| ------------------- | --------------------------------------------------------------- |
| `pairing`（預設） | 未知寄件者會取得一次性配對碼；擁有者必須核准 |
| `allowlist` | 僅允許 `allowFrom` 中的寄件者（或已配對的允許儲存區） |
| `open` | 允許所有傳入 DM（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有傳入 DM |
| `pairing`（預設） | 未知傳送者會取得一次性配對碼；擁有者必須核准 |
| `allowlist` | 只允許 `allowFrom`（或已配對允許儲存區）中的傳送者 |
| `open` | 允許所有傳入 DM（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有傳入 DM |
| 群組政策 | 行為 |
| 群組政策 | 行為 |
| --------------------- | ------------------------------------------------------ |
| `allowlist`（預設） | 僅允許符合已設定允許清單的群組 |
| `open` | 略過群組允許清單（提及門檻仍適用） |
| `disabled` | 封鎖所有群組/聊天室訊息 |
| `allowlist`（預設） | 只允許符合已設定允許清單的群組 |
| `open` | 略過群組允許清單（提及控管仍適用） |
| `disabled` | 封鎖所有群組/聊天室訊息 |
<Note>
當提供者的 `groupPolicy` 未設定時，`channels.defaults.groupPolicy` 會設定預設值。
配對碼會在 1 小時後過期。待處理的 DM 配對請求上限為**每個通道 3 個**。
如果提供者區塊完全缺少（沒有 `channels.<provider>`），執行階段群組政策會退回到 `allowlist`（失敗關閉），並在啟動時發出警告。
`channels.defaults.groupPolicy` 會在提供者的 `groupPolicy` 未設定時設定預設值。
配對碼會在 1 小時後過期。待處理的 DM 配對請求上限為**每個頻道 3 個**。
如果提供者區塊完全缺失（沒有 `channels.<provider>`），執行階段群組政策會退回 `allowlist`（失敗關閉）並顯示啟動警告。
</Note>
### 通道模型覆寫
### 頻道模型覆寫
使用 `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.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在 Heartbeat 輸出中包含健康的通道狀態。
- `channels.defaults.groupPolicy`：提供者層級的 `groupPolicy` 未設定時的備援群組政策。
- `channels.defaults.contextVisibility`：所有頻道的預設補充脈絡可見性模式。值：`all`（預設，包含所有引用/對話串/歷史脈絡）、`allowlist`（只包含允許清單傳送者的脈絡）、`allowlist_quote`（與 allowlist 相同，但保留明確的引用/回覆脈絡）。各頻道覆寫：`channels.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在 Heartbeat 輸出中包含健康的頻道狀態。
- `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 輸出中包含降級/錯誤狀態。
- `channels.defaults.heartbeat.useIndicator`：呈現精簡指示器樣式的 Heartbeat 輸出。
### WhatsApp
WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的工作階段存在時，會自動啟動。
WhatsApp 會透過 Gateway 的網頁頻道（Baileys Web）執行。當已連結的工作階段存在時，它會自動啟動。
```json5
{
@ -155,10 +155,10 @@ WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的
}
```
- 如果存在 `default` 帳號，傳出命令預設使用帳號 `default`；否則使用第一個已設定的帳號 ID（排序後）。
- 選用的 `channels.whatsapp.defaultAccount` 可在符合已設定帳號 ID 時，覆寫該後備預設帳號選擇。
- 傳出命令預設會使用帳號 `default`（如果存在）；否則使用第一個已設定的帳號 ID（排序後）。
- 選用的 `channels.whatsapp.defaultAccount` 可在其符合已設定帳號 ID 時，覆寫該備援預設帳號選擇。
- 舊版單帳號 Baileys 驗證目錄會由 `openclaw doctor` 遷移到 `whatsapp/default`。
- 每帳號覆寫：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
- 各帳號覆寫：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
</Accordion>
@ -217,12 +217,12 @@ WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的
}
```
- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（僅限一般檔案；符號連結會被拒絕），預設帳號會以 `TELEGRAM_BOT_TOKEN` 作為後備。
- `apiRoot` 只可是 Telegram Bot API 根目錄。請使用 `https://api.telegram.org` 或你自行託管/代理的根目錄，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 會移除意外尾隨的 `/bot<TOKEN>` 後綴。
- 選用的 `channels.telegram.defaultAccount` 可在符合已設定帳號 ID 時，覆寫預設帳號選擇。
- 在多帳號設定（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 代理](/zh-TW/tools/acp-agents#channel-specific-settings) 中共用。
- Bot 權杖：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（僅限一般檔案；拒絕符號連結），預設帳號則以 `TELEGRAM_BOT_TOKEN` 作為備援。
- `apiRoot` 只表示 Telegram Bot API 根目錄。請使用 `https://api.telegram.org` 或你的自架/代理根目錄，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 會移除意外結尾的 `/bot<TOKEN>` 後綴。
- 選用的 `channels.telegram.defaultAccount` 可在其符合已設定帳號 ID 時，覆寫預設帳號選擇。
- 在多帳號設定（2 個以上帳號 ID）中，請設定明確的預設值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免備援路由；缺少或無效時，`openclaw doctor` 會提出警告。
- `configWrites: false` 會封鎖 Telegram 發起的設定寫入（超級群組 ID 遷移、`/config set|unset`）。
- 頂層 `bindings[]` 項目搭配 `type: "acp"` 會為論壇主題設定持久 ACP 綁定（在 `match.peer.id` 中使用標準 `chatId:topic:topicId`）。欄位語義在 [ACP 代理](/zh-TW/tools/acp-agents#channel-specific-settings) 中共用。
- Telegram 串流預覽使用 `sendMessage` + `editMessageText`（可在直接聊天與群組聊天中運作）。
- 重試政策：請參閱[重試政策](/zh-TW/concepts/retry)。
@ -326,35 +326,35 @@ WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的
}
```
- Token：`channels.discord.token`，預設帳戶以 `DISCORD_BOT_TOKEN` 作為後援。
- 提供明確 Discord `token` 的直接傳出呼叫會使用該 token 進行呼叫；帳戶重試/政策設定仍來自作用中執行階段快照中選取的帳戶。
- 選用的 `channels.discord.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選取。
- 使用 `user:<id>`（DM）或 `channel:<id>`（公會頻道）作為傳遞目標；純數字 ID 會被拒絕。
- 公會 slug 為小寫，空格會替換成 `-`；頻道鍵使用 slug 化名稱（不含 `#`）。建議優先使用公會 ID。
- 預設會忽略機器人撰寫的訊息。`allowBots: true` 會啟用它們；使用 `allowBots: "mentions"` 只接受提及該機器人的機器人訊息（仍會篩除自己的訊息）。
- Token：`channels.discord.token`，預設帳號會以 `DISCORD_BOT_TOKEN` 作為備援。
- 提供明確 Discord `token` 的直接出站呼叫會使用該 Token 執行該次呼叫；帳號重試/政策設定仍來自作用中執行階段快照中選取的帳號。
- 選用的 `channels.discord.defaultAccount` 會在符合已設定帳號 id 時覆寫預設帳號選取。
- 使用 `user:<id>`（DM）或 `channel:<id>`（公會頻道）作為傳遞目標；裸數字 ID 會被拒絕。
- 公會 slug 會轉為小寫並以 `-` 取代空格；頻道鍵使用已 slug 化的名稱（不含 `#`）。建議優先使用公會 ID。
- 預設會忽略機器人撰寫的訊息。`allowBots: true` 會啟用它們；使用 `allowBots: "mentions"` 只接受提及該機器人的機器人訊息（仍會過濾自己的訊息）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及頻道覆寫）會丟棄提及其他使用者或角色但未提及該機器人的訊息（不含 @everyone/@here）。
- `maxLinesPerMessage`（預設 17）即使在 2000 個字元以內，也會分割過高的訊息。
- `channels.discord.threadBindings` 控制 Discord 執行緒繫結路由：
- `enabled`：Discord 對執行緒繫結工作階段功能的覆寫（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及繫結的傳遞/路由）
- `idleHours`：Discord 對非作用中自動取消聚焦的小時數覆寫（`0` 會停用）
- `maxAgeHours`：Discord 對硬性最長存留時間的小時數覆寫（`0` 會停用）
- `spawnSubagentSessions`：`sessions_spawn({ thread: true })` 自動建立/繫結執行緒的選用開關
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目會為頻道和執行緒設定持久 ACP 繫結（在 `match.peer.id` 中使用頻道/執行緒 ID）。欄位語意共用於 [ACP 代理程式](/zh-TW/tools/acp-agents#channel-specific-settings)。
- `channels.discord.ui.components.accentColor` 設定 Discord 元件 v2 容器的強調色。
- `maxLinesPerMessage`（預設 17）即使在 2000 字元以內，也會分割過高的訊息。
- `channels.discord.threadBindings` 控制 Discord 綁定討論串的路由：
- `enabled`：Discord 對綁定討論串工作階段功能的覆寫（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及綁定傳遞/路由）
- `idleHours`：Discord 對閒置自動取消聚焦時數的覆寫（`0` 會停用）
- `maxAgeHours`：Discord 對硬性最大時數的覆寫（`0` 會停用）
- `spawnSubagentSessions`：`sessions_spawn({ thread: true })` 自動建立/綁定討論串的選用開關
- 最上層 `bindings[]` 中具有 `type: "acp"` 的項目會為頻道與討論串設定持久 ACP 綁定（在 `match.peer.id` 使用頻道/討論串 id）。欄位語意在 [ACP 代理](/zh-TW/tools/acp-agents#channel-specific-settings) 中共用。
- `channels.discord.ui.components.accentColor` 設定 Discord components v2 容器的強調色。
- `channels.discord.voice` 啟用 Discord 語音頻道對話，以及選用的自動加入 + LLM + TTS 覆寫。
- `channels.discord.voice.model` 可選擇性覆寫 Discord 語音頻道回應所使用的 LLM 模型。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 會傳遞至 `@discordjs/voice` DAVE 選項（預設為 `true` 和 `24`）。
- OpenClaw 另外會在重複解密失敗後，透過離開/重新加入語音工作階段來嘗試語音接收復原。
- `channels.discord.voice.model` 可選擇性覆寫用於 Discord 語音頻道回應的 LLM 模型。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 會傳遞給 `@discordjs/voice` DAVE 選項（預設為 `true` 和 `24`）。
- OpenClaw 另會在重複解密失敗後，透過離開/重新加入語音工作階段嘗試語音接收復原。
- `channels.discord.streaming` 是標準串流模式鍵。舊版 `streamMode` 和布林 `streaming` 值會自動遷移。
- `channels.discord.autoPresence` 會將執行階段可用性對應到機器人上線狀態（healthy => online、degraded => idle、exhausted => dnd），並允許選用的狀態文字覆寫。
- `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 允許清單。省略則轉送所有代理程式的核准。
- `approvers`：允許核准 exec 請求的 Discord 使用者 ID。省略時會退回使用 `commands.ownerAllowFrom`。
- `agentFilter`：選用的代理 ID 允許清單。省略時會轉送所有代理的核准。
- `sessionFilter`：選用的工作階段鍵模式（子字串或正規表示式）。
- `target`：傳送核准提示的位置。`"dm"`（預設）傳送到核准者 DM，`"channel"` 傳送到來源頻道，`"both"` 傳送到兩者。當目標包含 `"channel"` 時，按鈕只有已解析的核准者可使用。
- `cleanupAfterResolve`：為 `true` 時，在核准、拒絕或逾時後刪除核准 DM。
- `target`：核准提示的傳送位置。`"dm"`（預設）傳送至核准者 DM，`"channel"` 傳送至來源頻道，`"both"` 傳送至兩者。當 target 包含 `"channel"` 時，按鈕只可由已解析的核准者使用。
- `cleanupAfterResolve`：為 `true` 時，會在核准、拒絕或逾時後刪除核准 DM。
**反應通知模式：** `off`（無）、`own`（機器人的訊息，預設）、`all`（所有訊息）、`allowlist`（來自所有訊息上的 `guilds.<id>.users`）。
@ -389,7 +389,7 @@ WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的
- 服務帳戶 JSON：內嵌（`serviceAccount`）或檔案式（`serviceAccountFile`）。
- 也支援服務帳戶 SecretRef（`serviceAccountRef`）。
- 環境後援：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 環境備援：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 使用 `spaces/<spaceId>` 或 `users/<userId>` 作為傳遞目標。
- `channels.googlechat.dangerouslyAllowNameMatching` 會重新啟用可變電子郵件主體比對（緊急相容模式）。
@ -463,44 +463,44 @@ WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的
}
```
- **Socket 模式**需要同時有 `botToken` 和 `appToken`（預設帳戶環境後援為 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP 模式**需要 `botToken` 加上 `signingSecret`（位於根層級或各帳戶）。
- `socketMode` 會將 Slack SDK Socket Mode 傳輸調校傳遞至公開 Bolt 接收器 API。只在調查 ping/pong 逾時或過時 websocket 行為時使用。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文
- **Socket 模式**需要同時有 `botToken` 和 `appToken`（預設帳號環境備援為 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP 模式**需要 `botToken` 加上 `signingSecret`（位於根層級或個別帳號）。
- `socketMode` 會將 Slack SDK Socket Mode 傳輸調校傳遞至公開 Bolt receiver API。僅在調查 ping/pong 逾時或過期 websocket 行為時使用。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受純文字
字串或 SecretRef 物件。
- Slack 帳戶快照會公開每個認證的來源/狀態欄位，例如
- Slack 帳號快照會公開每個憑證的來源/狀態欄位，例如
`botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式中的
`signingSecretStatus`。`configured_unavailable` 表示帳戶是
透過 SecretRef 設定，但目前的命令/執行階段路徑無法
解析秘密值。
- `configWrites: false` 會封鎖由 Slack 發起的設定寫入。
- 選用的 `channels.slack.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選取。
`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:<id>`（DM）或 `channel:<id>` 作為傳遞目標。
**反應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。
**執行緒工作階段隔離：** `thread.historyScope` 是每個執行緒（預設）或在頻道間共用。`thread.inheritParent` 會將父頻道逐字稿複製到新執行緒。
**討論串工作階段隔離：** `thread.historyScope` 是個別討論串（預設）或在頻道間共用。`thread.inheritParent` 會將父頻道逐字稿複製到新的討論串。
- Slack 原生串流加上 Slack 助理樣式的「is typing...」執行緒狀態需要回覆執行緒目標。頂層 DM 預設保持在執行緒外，因此會改用 `typingReaction` 或一般傳遞，而不是執行緒樣式預覽。
- Slack 原生串流加上 Slack 助理樣式的「is typing...」討論串狀態需要回覆討論串目標。最上層 DM 預設保持不在討論串中，因此會改用 `typingReaction` 或一般傳遞，而不是討論串樣式預覽。
- `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"`）。
- `channels.slack.execApprovals`：Slack 原生 exec 核准傳遞與核准者授權。與 Discord 使用相同 schema：`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 發行版本中作為內建 Plugin 隨附。較舊或
自訂建置可以透過
Mattermost 在目前 OpenClaw 版本中作為內建 Plugin 隨附。較舊或
自訂建置可以使用
`openclaw plugins install @openclaw/mattermost` 安裝目前的 npm 套件；如果 npm 回報
OpenClaw 擁有的套件已棄用，請使用內建 Plugin 或本機 checkout，
直到更新的 npm 套件發布。
直到較新的 npm 套件發布。
```json5
{
@ -530,24 +530,23 @@ OpenClaw 擁有的套件已棄用，請使用內建 Plugin 或本機 checkout，
}
```
聊天模式：`oncall`（在 @-提及時回應，預設）、`onmessage`（每則訊息）、`onchar`（以觸發前綴開頭的訊息）。
聊天模式：`oncall`（在 @-mention 時回應，預設）、`onmessage`（每則訊息）、`onchar`（以觸發前綴開頭的訊息）。
啟用 Mattermost 原生命令時：
- `commands.callbackPath` 必須是路徑（例如 `/api/channels/mattermost/command`），不是完整 URL。
- `commands.callbackUrl` 必須解析為 OpenClaw Gateway 端點，並且可由 Mattermost 伺服器連線。
- 原生斜線回呼會使用 Mattermost 在斜線命令註冊期間傳回的每命令 token
進行驗證。如果註冊失敗或沒有命令啟用，
- `commands.callbackPath` 必須是路徑（例如 `/api/channels/mattermost/command`），而不是完整 URL。
- `commands.callbackUrl` 必須解析到 OpenClaw Gateway 端點，且 Mattermost 伺服器必須能夠連線。
- 原生斜線回呼會使用 Mattermost 在斜線命令註冊期間傳回的每個命令 Token
進行驗證。如果註冊失敗或沒有命令被啟用，
OpenClaw 會以
`Unauthorized: invalid command token.`
拒絕回呼。
- 對於私人/tailnet/內部回呼主機，Mattermost 可能要求
`ServiceSettings.AllowedUntrustedInternalConnections` 包含回呼主機/網域。
使用主機/網域值，而不是完整 URL。
`Unauthorized: invalid command token.` 拒絕回呼。
- 對於私人/tailnet/內部回呼主機，Mattermost 可能需要
`ServiceSettings.AllowedUntrustedInternalConnections` 包含該回呼主機/網域。
請使用主機/網域值，而不是完整 URL。
- `channels.mattermost.configWrites`：允許或拒絕由 Mattermost 發起的設定寫入。
- `channels.mattermost.requireMention`：在頻道回覆前要求 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：每頻道提及門檻覆寫（`"*"` 作為預設）。
- 選用的 `channels.mattermost.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選取。
- `channels.mattermost.requireMention`：在頻道中回覆前要求 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：個別頻道提及門檻覆寫（`"*"` 表示預設）。
- 選用的 `channels.mattermost.defaultAccount` 會在符合已設定帳號 id 時覆寫預設帳號選取。
### Signal
@ -568,9 +567,9 @@ OpenClaw 擁有的套件已棄用，請使用內建 Plugin 或本機 checkout，
}
```
**反應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。
**回應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。
- `channels.signal.account`：將 channel 啟動固定到特定的 Signal 帳號身分。
- `channels.signal.account`：將頻道啟動固定到特定的 Signal 帳號身分。
- `channels.signal.configWrites`：允許或拒絕由 Signal 發起的設定寫入。
- 選用的 `channels.signal.defaultAccount` 會在符合已設定的帳號 ID 時覆寫預設帳號選擇。
@ -591,10 +590,10 @@ BlueBubbles 是建議的 iMessage 路徑（由 Plugin 支援，設定於 `channe
}
```
- 此處涵蓋的核心 key 路徑：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 此處涵蓋的核心鍵路徑：`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#channel-specific-settings)。
- 完整的 BlueBubbles channel 設定記載於 [BlueBubbles](/zh-TW/channels/bluebubbles)。
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目可將 BlueBubbles 對話繫結到持久 ACP 工作階段。在 `match.peer.id` 中使用 BlueBubbles 控制代碼或目標字串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP 代理程式](/zh-TW/tools/acp-agents#channel-specific-settings)。
- 完整的 BlueBubbles 頻道設定記錄於 [BlueBubbles](/zh-TW/channels/bluebubbles)。
### iMessage
@ -624,13 +623,13 @@ OpenClaw 會產生 `imsg rpc`（透過 stdio 的 JSON-RPC）。不需要 daemon
- 選用的 `channels.imessage.defaultAccount` 會在符合已設定的帳號 ID 時覆寫預設帳號選擇。
- 需要對 Messages DB 具有完整磁碟存取權。
- 優先使用 `chat_id:<id>` 目標。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可以指向 SSH 包裝器；設定 `remoteHost`（`host` 或 `user@host`）以便透過 SCP 擷取附件。
- 需要對 Messages DB 的完整磁碟存取權。
- 偏好 `chat_id:<id>` 目標。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可指向 SSH 包裝器；設定 `remoteHost`（`host` 或 `user@host`）以擷取 SCP 附件。
- `attachmentRoots` 和 `remoteAttachmentRoots` 會限制傳入附件路徑（預設：`/Users/*/Library/Messages/Attachments`）。
- 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#channel-specific-settings)。
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目可將 iMessage 對話繫結到持久 ACP 工作階段。在 `match.peer.id` 中使用正規化控制代碼或明確聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP 代理程式](/zh-TW/tools/acp-agents#channel-specific-settings)。
<Accordion title="iMessage SSH 包裝器範例">
@ -643,7 +642,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
Matrix 由 Plugin 支援，並設定於 `channels.matrix` 下。
Matrix 由 Plugin 支援，設定於 `channels.matrix` 下。
```json5
{
@ -673,25 +672,25 @@ Matrix 由 Plugin 支援，並設定於 `channels.matrix` 下。
}
```
- Token 驗證使用 `accessToken`；密碼驗證使用 `userId` + `password`。
- `channels.matrix.proxy` 會透過明確的 HTTP(S) proxy 路由 Matrix HTTP 流量。具名帳號可以用 `channels.matrix.accounts.<id>.proxy` 覆寫。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允許私人/內部 homeserver。`proxy` 與此網路選擇加入是彼此獨立的控制項。
- 權杖驗證使用 `accessToken`；密碼驗證使用 `userId` + `password`。
- `channels.matrix.proxy` 會透過明確的 HTTP(S) Proxy 路由 Matrix HTTP 流量。具名帳號可使用 `channels.matrix.accounts.<id>.proxy` 覆寫它。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允許私人/內部 homeserver。`proxy` 與此網路選擇加入是獨立控制項。
- `channels.matrix.defaultAccount` 會在多帳號設定中選取偏好的帳號。
- `channels.matrix.autoJoin` 預設為 `off`，因此受邀房間與新的 DM 樣式邀請會被忽略，直到你使用 `autoJoinAllowlist` 設定 `autoJoin: "allowlist"`，或設定 `autoJoin: "always"`。
- `channels.matrix.execApprovals`：Matrix 原生 exec 核准遞送與核准者授權。
- `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當核准者可從 `approvers` 或 `commands.ownerAllowFrom` 解析時，exec 核准會啟用。
- `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 模式（子字串或 regex）。
- `target`：要傳送核准提示的位置。`"dm"`（預設）、`"channel"`（來源房間）或 `"both"`。
- 每帳號覆寫：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix DM 如何分組到工作階段：`per-user`（預設）依路由後的 peer 共用，而 `per-room` 會隔離每個 DM 房間。
- Matrix 狀態探測與即時目錄查詢會使用與執行階段流量相同的 proxy 政策。
- 完整的 Matrix 設定、目標規則與設定範例記載於 [Matrix](/zh-TW/channels/matrix)。
- `agentFilter`：選用的代理程式 ID 允許清單。省略則轉送所有代理程式的核准。
- `sessionFilter`：選用的工作階段鍵模式（子字串或 regex）。
- `target`：傳送核准提示的位置。`"dm"`（預設）、`"channel"`（來源房間）或 `"both"`。
- 個別帳號覆寫：`channels.matrix.accounts.<id>.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
{
@ -706,12 +705,12 @@ Microsoft Teams 由 Plugin 支援，並設定於 `channels.msteams` 下。
}
```
- 此處涵蓋的核心 key 路徑：`channels.msteams`、`channels.msteams.configWrites`。
- 完整 Teams 設定（憑證、webhook、DM/群組政策、每 team/每 channel 覆寫）記載於 [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
{
@ -732,13 +731,13 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
}
```
- 此處涵蓋的核心 key 路徑：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 此處涵蓋的核心鍵路徑：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 選用的 `channels.irc.defaultAccount` 會在符合已設定的帳號 ID 時覆寫預設帳號選擇。
- 完整的 IRC channel 設定（host/port/TLS/channels/allowlists/提及閘控）記載於 [IRC](/zh-TW/channels/irc)。
- 完整的 IRC 頻道設定（主機/連接埠/TLS/頻道/允許清單/提及門檻）記錄於 [IRC](/zh-TW/channels/irc)。
### 多帳號（所有 channel）
### 多帳號（所有頻道）
為每個 channel 執行多個帳號（每個都有自己的 `accountId`）：
每個頻道執行多個帳號（各自具有自己的 `accountId`）：
```json5
{
@ -760,29 +759,31 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
```
- 省略 `accountId` 時會使用 `default`（CLI + 路由）。
- Env token 只套用至**預設**帳號。
- 基礎 channel 設定會套用至所有帳號，除非每帳號覆寫。
- 使用 `bindings[].match.accountId` 將每個帳號路由到不同的代理程式。
- 如果你透過 `openclaw channels add`（或 channel onboarding）新增非預設帳號，而目前仍使用單帳號頂層 channel 設定，OpenClaw 會先將帳號範圍的頂層單帳號值提升到 channel 帳號對應表中，讓原始帳號繼續運作。大多數 channel 會將它們移入 `channels.<channel>.accounts.default`；Matrix 則可以保留現有相符的具名/預設目標。
- 現有僅 channel 的綁定（沒有 `accountId`）會繼續符合預設帳號；帳號範圍的綁定仍為選用。
- `openclaw doctor --fix` 也會修復混合形狀，方式是將帳號範圍的頂層單帳號值移入為該 channel 選定的已提升帳號。大多數 channel 使用 `accounts.default`；Matrix 則可以保留現有相符的具名/預設目標。
- Env 權杖只會套用到**預設**帳號。
- 基礎頻道設定會套用到所有帳號，除非於個別帳號覆寫。
- 使用 `bindings[].match.accountId` 將每個帳號路由到不同代理程式。
- 如果你透過 `openclaw channels add`（或頻道 onboarding）新增非預設帳號，同時仍使用單帳號頂層頻道設定，OpenClaw 會先將帳號範圍的頂層單帳號值提升到頻道帳號對應表，讓原始帳號繼續運作。多數頻道會將它們移到 `channels.<channel>.accounts.default`；Matrix 則可改為保留現有相符的具名/預設目標。
- 既有僅限頻道的繫結（沒有 `accountId`）會繼續符合預設帳號；帳號範圍的繫結仍為選用。
- `openclaw doctor --fix` 也會修復混合形狀，方式是將帳號範圍的頂層單帳號值移到為該頻道選定的已提升帳號。多數頻道使用 `accounts.default`；Matrix 則可改為保留現有相符的具名/預設目標。
### 其他 Plugin channel
### 其他 Plugin 頻道
許多 Plugin channel 都設定為 `channels.<id>`，並記載於各自專用的 channel 頁面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
請參閱完整 channel 索引：[Channels](/zh-TW/channels)。
許多 Plugin 頻道會設定為 `channels.<id>`，並在其專屬頻道頁面中記錄（例如 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 群組聊天。
可見回覆會分開控制。群組/channel 房間預設為 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍會處理該輪對話，但一般最終回覆會保持私密，而可見的房間輸出需要 `message(action=send)`。只有在你想要舊版行為，也就是一般回覆會發布回房間時，才設定 `"automatic"`。若要將相同的僅工具可見回覆行為也套用到直接聊天，請設定 `messages.visibleReplies: "message_tool"`。
可見回覆會分開控制。群組/頻道房間預設為 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍會處理該輪次，但一般最終回覆會保持私密，而可見的房間輸出需要 `message(action=send)`。只有在你想要舊版行為，也就是一般回覆會張貼回房間時，才設定 `"automatic"`。若也要將相同的僅工具可見回覆行為套用到直接聊天，請設定 `messages.visibleReplies: "message_tool"`。
Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署中停用檔案監看或設定重新載入時才需要重新啟動。
**提及類型：**
- **Metadata 提及**：原生平台 @-mentions。在 WhatsApp self-chat 模式中會被忽略。
- **中繼資料提及**：原生平台 @-提及。在 WhatsApp 自我聊天模式中會被忽略。
- **文字模式**：`agents.list[].groupChat.mentionPatterns` 中的安全 regex 模式。無效模式與不安全的巢狀重複會被忽略。
- 提及閘控只會在可偵測時強制執行（原生提及或至少一個模式）。
- 提及門檻只會在偵測可行時強制執行（原生提及或至少一個模式）。
```json5
{
@ -799,11 +800,11 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
}
```
`messages.groupChat.historyLimit` 會設定全域預設值。Channel 可以用 `channels.<channel>.historyLimit`（或每帳號）覆寫。設定為 `0` 可停用。
`messages.groupChat.historyLimit` 會設定全域預設。頻道可使用 `channels.<channel>.historyLimit`（或個別帳號）覆寫。設定 `0` 可停用。
`messages.visibleReplies` 是全域來源輪次預設值；`messages.groupChat.visibleReplies` 會為群組/channel 來源輪次覆寫它。Channel allowlist 與提及閘控仍會決定是否處理該輪對話。
`messages.visibleReplies` 是全域來源輪次預設；`messages.groupChat.visibleReplies` 會針對群組/頻道來源輪次覆寫它。頻道允許清單與提及門檻仍會決定是否處理該輪次。
#### DM 歷史記錄限制
#### DM 歷程限制
```json5
{
@ -818,13 +819,13 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
}
```
解析順序：每 DM 覆寫 → provider 預設值 → 無限制（全部保留）。
解析順序：個別 DM 覆寫 → 提供者預設 → 無限制（全部保留）。
支援：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。
#### Self-chat 模式
#### 自我聊天模式
在 `allowFrom` 中包含你自己的號碼以啟用 self-chat 模式（忽略原生 @-mentions，只回應文字模式）：
在 `allowFrom` 中包含你自己的號碼，以啟用自我聊天模式（忽略原生 @-提及，只回應文字模式）：
```json5
{
@ -845,7 +846,7 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
}
```
### Commands（聊天命令處理）
### 命令（聊天命令處理）
```json5
{
@ -872,34 +873,34 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
}
```
<Accordion title="指令詳細資料">
<Accordion title="命令詳細資料">
- 此區塊會設定指令介面。若要查看目前內建與隨附的指令目錄，請參閱[斜線指令](/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`（布林值或 `"auto"`）。`false` 會清除先前註冊的指令。
- 使用 `channels.<provider>.commands.nativeSkills` 可依頻道覆寫原生 Skills 註冊。
- `channels.telegram.customCommands` 會新增額外的 Telegram Bot 選單項目。
- `bash: true` 會為主機 shell 啟用 `! <cmd>`。需要 `tools.elevated.enabled`，且傳送者必須位於 `tools.elevated.allowFrom.<channel>`。
- `config: true` 會啟用 `/config`（讀取/寫入 `openclaw.json`）。對於 Gateway `chat.send` 用戶端，持久性 `/config set|unset` 寫入也需要 `operator.admin`；唯讀 `/config show` 仍可供一般具寫入範圍的操作員用戶端使用。
- `mcp: true` 會啟用 `/mcp`，用於 `mcp.servers` 下由 OpenClaw 管理的 MCP 伺服器設定。
- 此區塊會設定命令介面。若要查看目前的內建 + 隨附命令目錄，請參閱 [斜線命令](/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`（布林值或 `"auto"`）。`false` 會清除先前註冊的命令。
- 使用 `channels.<provider>.commands.nativeSkills` 依頻道覆寫原生 Skills 註冊。
- `channels.telegram.customCommands` 會新增額外的 Telegram bot 選單項目。
- `bash: true` 會為主機 shell 啟用 `! <cmd>`。需要 `tools.elevated.enabled`，且傳送者必須在 `tools.elevated.allowFrom.<channel>` 中。
- `config: true` 會啟用 `/config`（讀取/寫入 `openclaw.json`）。對於 Gateway `chat.send` 用戶端，持久性 `/config set|unset` 寫入還需要 `operator.admin`；唯讀 `/config show` 仍可供一般具寫入範圍的 operator 用戶端使用。
- `mcp: true` 會啟用 `/mcp`，用於 `mcp.servers` 下由 OpenClaw 管理的 MCP server 設定。
- `plugins: true` 會啟用 `/plugins`，用於 Plugin 探索、安裝，以及啟用/停用控制。
- `channels.<provider>.configWrites` 會依頻道控管設定變更（預設值：true）。
- `channels.<provider>.configWrites` 會依頻道控管設定變更（預設：true）。
- 對於多帳號頻道，`channels.<provider>.accounts.<id>.configWrites` 也會控管以該帳號為目標的寫入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 會停用 `/restart` 和 Gateway 重新啟動工具動作。預設值：`true`。
- `ownerAllowFrom` 是 owner-only 指令/工具的明確擁有者允許清單。它與 `allowFrom` 分開。
- `ownerDisplay: "hash"` 會在系統提示中雜湊擁有者 ID。設定 `ownerDisplaySecret` 可控制雜湊。
- `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)
- `ownerAllowFrom` 是 owner 專用命令/工具的明確 owner 允許清單。它與 `allowFrom` 分開。
- `ownerDisplay: "hash"` 會在系統提示中雜湊 owner id。設定 `ownerDisplaySecret` 以控制雜湊。
- `allowFrom` 是依 provider 設定。設定後，它會是**唯一**的授權來源（頻道允許清單/配對和 `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)
</Accordion>
@ -908,5 +909,5 @@ IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
## 相關
- [設定參考](/zh-TW/gateway/configuration-reference) — 頂層鍵
- [設定 — 代理](/zh-TW/gateway/config-agents)
- [頻道概覽](/zh-TW/channels)
- [設定 — agents](/zh-TW/gateway/config-agents)
- [頻道概觀](/zh-TW/channels)

389
docs/zh-TW/gateway/doctor.md
View File

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

38
docs/zh-TW/gateway/gateway-lock.md
View File

@ -1,44 +1,44 @@
---
read_when:
- 執行或偵錯 Gateway 程序
- 調查單一執行個體強制執行
summary: 使用 WebSocket 監聽器繫結的 Gateway 單例防護機制
- 執行或除錯 Gateway 程序
- 調查單一執行個體強制機制
summary: 使用 WebSocket 監聽器繫結的 Gateway 單例防護
title: Gateway 鎖定
x-i18n:
generated_at: "2026-04-30T03:06:05Z"
generated_at: "2026-04-30T16:29:01Z"
model: gpt-5.5
provider: openai
source_hash: fe61ff81106554e98de1ca04c213b76d230265cdf3e81b70897d2de00f6a0179
source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13
source_path: gateway/gateway-lock.md
workflow: 16
---
## 原因
- 確保同一主機上每個基本連接埠只執行一個 Gateway 執行個體；其他 Gateway 必須使用隔離的設定檔和唯一連接埠。
- 在當機/SIGKILL 後仍能復原，不會留下過期鎖定檔。
- 當控制連接埠已被占用時，以明確錯誤快速失敗。
- 確保同一主機上的每個基準連接埠只執行一個 Gateway 執行個體；額外的 Gateway 必須使用隔離的設定檔與唯一連接埠。
- 在當機/SIGKILL 後仍能恢復，且不留下過時的鎖定檔。
- 當控制連接埠已被佔用時，快速失敗並顯示清楚的錯誤。
## 機制
- Gateway 會先在狀態鎖定目錄下取得每個設定專用的鎖定檔，並探測已設定的連接埠是否有現有監聽器。
- 如果記錄的鎖定擁有者已不存在、連接埠可用，或鎖定已過期，啟動程序會取回鎖定並繼續。
- Gateway 接著會使用獨占 TCP 監聽器繫結 HTTP/WebSocket 監聽器（預設 `ws://127.0.0.1:18789`）。
- 如果繫結因 `EADDRINUSE` 失敗，啟動程序會拋出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- Gateway 會先在狀態鎖定目錄下取得每個設定專屬的鎖定檔，並探測已設定連接埠是否已有既有監聽器。
- 如果記錄的鎖定擁有者已不存在、連接埠可用，或鎖定已過時，啟動程序會收回鎖定並繼續。
- 接著 Gateway 會使用獨占 TCP 監聽器綁定 HTTP/WebSocket 監聽器（預設 `ws://127.0.0.1:18789`）。
- 如果綁定因 `EADDRINUSE` 失敗，啟動程序會拋出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- 關閉時，Gateway 會關閉 HTTP/WebSocket 伺服器並移除鎖定檔。
## 錯誤呈現
## 錯誤介面
- 如果另一個程序持有該連接埠，啟動程序會拋出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
- 其他繫結失敗會呈現為 `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`。
- 其他綁定失敗會呈現為 `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`。
## 操作注意事項
- 如果連接埠被_另一個_程序占用，錯誤相同；請釋放該連接埠，或使用 `openclaw gateway --port <port>` 選擇另一個連接埠。
- 在服務監督器下，新的 Gateway 程序如果看到現有健康的 `/healthz` 回應者，會成功結束並讓該程序保持控制權。如果現有程序一直無法變健康，重試會有界限，且啟動會以明確的鎖定錯誤失敗，而不是永遠循環。
- macOS 應用程式在產生 Gateway 前仍會維持自己的輕量 PID 防護；執行階段鎖定由鎖定檔加上 HTTP/WebSocket 繫結強制執行。
- 如果連接埠被_另一個_程序佔用，錯誤相同；釋放該連接埠，或使用 `openclaw gateway --port <port>` 選擇另一個連接埠。
- 在服務監督程式下，若新的 Gateway 程序看到現有健康的 `/healthz` 回應者，會讓該程序維持控制權。在 systemd 上，重複啟動者會以代碼 78 結束，因此預設的 `RestartPreventExitStatus=78` 會阻止 `Restart=always` 因鎖定或 `EADDRINUSE` 衝突而不斷迴圈。如果現有程序始終無法變為健康狀態，重試次數會受限，且啟動會以清楚的鎖定錯誤失敗，而不是永遠迴圈。
- macOS App 在產生 Gateway 前仍會維護自己的輕量 PID 防護；執行階段鎖定則由鎖定檔加上 HTTP/WebSocket 綁定強制執行。
## 相關內容
## 相關
- [多個 Gateway](/zh-TW/gateway/multiple-gateways) — 使用唯一連接埠執行多個執行個體
- [疑難排解](/zh-TW/gateway/troubleshooting) — 診斷 `EADDRINUSE` 和連接埠衝突
- [疑難排解](/zh-TW/gateway/troubleshooting) — 診斷 `EADDRINUSE` 與連接埠衝突

98
docs/zh-TW/platforms/mac/remote.md
View File

@ -1,108 +1,108 @@
---
read_when:
- 設定或偵錯遠端 Mac 控制
summary: 透過 SSH 控制遠端 OpenClaw Gateway 的 macOS app 流程
summary: 透過 SSH 控制遠端 OpenClaw Gateway 的 macOS 應用程式流程
title: 遠端控制
x-i18n:
generated_at: "2026-04-30T03:20:51Z"
generated_at: "2026-04-30T16:28:54Z"
model: gpt-5.5
provider: openai
source_hash: 4de4980fe378fc9b685cf7732d21a80c640088191308b8ef1d3df9f468cb5be2
source_hash: 2c63f752c3636a253220310c7c8e57a28549704b74b2f0370bac432bae28a7d3
source_path: platforms/mac/remote.md
workflow: 16
---
# 遠端 OpenClaw (macOS ⇄ 遠端主機)
此流程讓 macOS 應用程式可作為完整遠端控制器，控制在另一台主機（桌機/伺服器）上執行的 OpenClaw Gateway。這是應用程式的 **Remote over SSH**（遠端執行）功能。所有功能，包括健康檢查、Voice Wake 轉送和 Web Chat，都會重用來自 _Settings → General_ 的相同遠端 SSH 設定。
此流程可讓 macOS 應用程式作為完整遙控器，控制在另一部主機（桌上型電腦／伺服器）上執行的 OpenClaw Gateway。這是應用程式的 **透過 SSH 遠端**（遠端執行）功能。所有功能，包括健康狀態檢查、語音喚醒轉送和網頁聊天，都會重用 _設定 → 一般_ 中相同的遠端 SSH 設定。
## 模式
- **本機（這台 Mac）**：所有內容都在筆電上執行。不涉及 SSH。
- **Remote over SSH（預設）**：OpenClaw 命令會在遠端主機上執行。Mac 應用程式會使用 `-o BatchMode` 加上你選擇的身分/金鑰和本機連接埠轉送來開啟 SSH 連線。
- **遠端直接連線 (ws/wss)**：沒有 SSH 通道。Mac 應用程式會直接連線到 Gateway URL（例如透過 Tailscale Serve 或公開 HTTPS 反向 Proxy）。
- **本機（這台 Mac）**：所有項目都在筆電上執行。不涉及 SSH。
- **透過 SSH 遠端（預設）**：OpenClaw 指令會在遠端主機上執行。Mac 應用程式會使用 `-o BatchMode`、你選擇的身分／金鑰，以及本機連接埠轉送來開啟 SSH 連線。
- **遠端直接連線 (ws/wss)**：不使用 SSH 通道。Mac 應用程式會直接連線到 Gateway URL（例如透過 Tailscale Serve 或公開 HTTPS 反向代理）。
## 遠端傳輸
遠端模式支援兩種傳輸：
遠端模式支援兩種傳輸方式：
- **SSH 通道**（預設）：使用 `ssh -N -L ...` 將 Gateway 連接埠轉送到 localhost。Gateway 會將 Node 的 IP 視為 `127.0.0.1`，因為通道是回送。
- **SSH 通道**（預設）：使用 `ssh -N -L ...` 將 Gateway 連接埠轉送到 localhost。Gateway 會看到節點的 IP 是 `127.0.0.1`，因為通道是 loopback。
- **直接連線 (ws/wss)**：直接連線到 Gateway URL。Gateway 會看到實際的用戶端 IP。
在 SSH 通道模式中，探索到的 LAN/tailnet 主機名稱會儲存為
在 SSH 通道模式中，探索到的 LAN／tailnet 主機名稱會儲存為
`gateway.remote.sshTarget`。應用程式會將 `gateway.remote.url` 保持在本機
通道端點，例如 `ws://127.0.0.1:18789`，因此 CLI、Web Chat 和
本機 Node 主機服務都會使用相同的安全回送傳輸。
通道端點上，例如 `ws://127.0.0.1:18789`，因此 CLI、網頁聊天和
本機節點主機服務都會使用相同的安全 loopback 傳輸。
遠端模式中的瀏覽器自動化由 CLI Node 主機擁有，而不是由
原生 macOS 應用程式 Node 擁有。應用程式會在可能時啟動已安裝的 Node 主機服務；
如果你需要從那台 Mac 控制瀏覽器，請使用 `openclaw node install ...` 和
`openclaw node start` 安裝/啟動它（或在前景執行
`openclaw node run ...`），然後指定那個具備瀏覽器能力的
Node。
遠端模式中的瀏覽器自動化由 CLI 節點主機負責，而不是由
原生 macOS 應用程式節點負責。應用程式會盡可能啟動已安裝的節點主機服務；如果你需要從該 Mac 控制瀏覽器，請使用
`openclaw node install ...` 和 `openclaw node start` 安裝／啟動它（或在前景執行
`openclaw node run ...`），然後將目標指向具備瀏覽器能力的
節點。
## 遠端主機上的先決條件
## 遠端主機的先決條件
1. 安裝 Node + pnpm，並建置/安裝 OpenClaw CLI（`pnpm install && pnpm build && pnpm link --global`）。
2. 確保 `openclaw` 位於非互動式 Shell 的 PATH 中（必要時符號連結到 `/usr/local/bin` 或 `/opt/homebrew/bin`）。
3. 使用金鑰驗證開啟 SSH。我們建議使用 **Tailscale** IP，以便在 LAN 外保持穩定連線能力。
1. 安裝 Node + pnpm，並建置／安裝 OpenClaw CLI（`pnpm install && pnpm build && pnpm link --global`）。
2. 確保 `openclaw` 位於非互動式 shell 的 PATH 中（如有需要，符號連結到 `/usr/local/bin` 或 `/opt/homebrew/bin`）。
3. 使用金鑰驗證開啟 SSH。我們建議使用 **Tailscale** IP，以便在離開 LAN 後仍能穩定連線。
## macOS 應用程式設定
1. 開啟 _Settings → General_。
2. 在 **OpenClaw runs** 下，選擇 **Remote over SSH** 並設定：
1. 開啟 _設定 → 一般_。
2. 在 **OpenClaw 執行位置** 下，選擇 **透過 SSH 遠端**，並設定：
- **傳輸**：**SSH 通道** 或 **直接連線 (ws/wss)**。
- **SSH 目標**：`user@host`（可選 `:port`）。
- 如果 Gateway 位於相同 LAN 並公告 Bonjour，請從探索清單中選取，以自動填入此欄位。
- **Gateway URL**（僅限直接連線）：`wss://gateway.example.ts.net`（或本機/LAN 使用 `ws://...`）。
- 如果 Gateway 位於相同 LAN 並公告 Bonjour，請從探索清單中選擇它，以自動填入此欄位。
- **Gateway URL**（僅直接連線）：`wss://gateway.example.ts.net`（或用於本機／LAN 的 `ws://...`）。
- **身分檔案**（進階）：你的金鑰路徑。
- **專案根目錄**（進階）：用於命令的遠端 checkout 路徑。
- **CLI 路徑**（進階）：可選的可執行 `openclaw` 進入點/二進位檔路徑（公告時會自動填入）。
3. 按下 **測試遠端**。成功表示遠端 `openclaw status --json` 可正確執行。失敗通常表示 PATH/CLI 問題；結束碼 127 表示遠端找不到 CLI。
4. 健康檢查和 Web Chat 現在會自動透過此 SSH 通道執行。
- **專案根目錄**（進階）：用於指令的遠端 checkout 路徑。
- **CLI 路徑**（進階）：可執行 `openclaw` 進入點／二進位檔的選用路徑（在公告時自動填入）。
3. 點選 **測試遠端**。成功代表遠端 `openclaw status --json` 正確執行。失敗通常表示 PATH／CLI 問題；結束碼 127 表示在遠端找不到 CLI。
4. 健康狀態檢查和網頁聊天現在會自動透過此 SSH 通道執行。
## Web Chat
## 網頁聊天
- **SSH 通道**：Web Chat 會透過轉送的 WebSocket 控制連接埠（預設 18789）連線到 Gateway。
- **直接連線 (ws/wss)**：Web Chat 會直接連線到已設定的 Gateway URL。
- **SSH 通道**：網頁聊天會透過轉送的 WebSocket 控制連接埠（預設 18789）連線到 Gateway。
- **直接連線 (ws/wss)**：網頁聊天會直接連線到已設定的 Gateway URL。
- 不再有獨立的 WebChat HTTP 伺服器。
## 權限
- 遠端主機需要與本機相同的 TCC 核准（自動化、輔助使用、螢幕錄製、麥克風、語音辨識、通知）。在該機器上執行上線流程，以一次授予這些權限。
- Node 會透過 `node.list` / `node.describe` 公告其權限狀態，讓代理知道哪些能力可用。
- 遠端主機需要與本機相同的 TCC 核准（自動化、輔助使用、螢幕錄製、麥克風、語音辨識、通知）。在該機器上執行 onboarding，以一次授予這些權限。
- 節點會透過 `node.list` / `node.describe` 公告其權限狀態，讓代理知道有哪些可用項目。
## 安全性注意事項
- 建議在遠端主機上使用回送繫結，並透過 SSH 或 Tailscale 連線。
- SSH 通道會使用嚴格的主機金鑰檢查；請先信任主機金鑰，讓它存在於 `~/.ssh/known_hosts`。
- 如果你將 Gateway 繫結到非回送介面，請要求有效的 Gateway 驗證：權杖、密碼，或搭配 `gateway.auth.mode: "trusted-proxy"` 的身分感知反向 Proxy。
- 請參閱 [安全性](/zh-TW/gateway/security) 和 [Tailscale](/zh-TW/gateway/tailscale)。
- 優先在遠端主機上使用 loopback 綁定，並透過 SSH 或 Tailscale 連線。
- SSH 通道使用嚴格的主機金鑰檢查；請先信任主機金鑰，使其存在於 `~/.ssh/known_hosts`。
- 如果你將 Gateway 綁定到非 loopback 介面，請要求有效的 Gateway 驗證：token、密碼，或使用 `gateway.auth.mode: "trusted-proxy"` 的具身分感知能力反向代理。
- 請參閱[安全性](/zh-TW/gateway/security)和 [Tailscale](/zh-TW/gateway/tailscale)。
## WhatsApp 登入流程（遠端）
- **在遠端主機上**執行 `openclaw channels login --verbose`。使用你手機上的 WhatsApp 掃描 QR。
- 如果驗證過期，請在該主機上重新執行登入。健康檢查會顯示連結問題。
- **在遠端主機上**執行 `openclaw channels login --verbose`。使用手機上的 WhatsApp 掃描 QR。
- 如果驗證過期，請在該主機上重新執行登入。健康狀態檢查會顯示連結問題。
## 疑難排解
- **結束碼 127 / 找不到**：`openclaw` 不在非登入 Shell 的 PATH 中。將它新增到 `/etc/paths`、你的 Shell rc，或符號連結到 `/usr/local/bin`/`/opt/homebrew/bin`。
- **健康探測失敗**：檢查 SSH 可連線性、PATH，以及 Baileys 是否已登入（`openclaw status --json`）。
- **Web Chat 卡住**：確認 Gateway 正在遠端主機上執行，且轉送連接埠符合 Gateway WS 連接埠；UI 需要健康的 WS 連線。
- **Node IP 顯示 127.0.0.1**：使用 SSH 通道時這是預期行為。如果你希望 Gateway 看到實際用戶端 IP，請將 **傳輸** 切換為 **直接連線 (ws/wss)**。
- **Voice Wake**：在遠端模式中，觸發短語會自動轉送；不需要獨立轉送器。
- **exit 127 / 找不到**：`openclaw` 不在非登入 shell 的 PATH 中。將它加入 `/etc/paths`、你的 shell rc，或符號連結到 `/usr/local/bin`／`/opt/homebrew/bin`。
- **健康狀態探測失敗**：檢查 SSH 可達性、PATH，以及 Baileys 是否已登入（`openclaw status --json`）。
- **網頁聊天卡住**：確認 Gateway 正在遠端主機上執行，且轉送連接埠與 Gateway WS 連接埠相符；UI 需要健康的 WS 連線。
- **節點 IP 顯示 127.0.0.1**：使用 SSH 通道時這是預期行為。如果你希望 Gateway 看到實際的用戶端 IP，請將 **傳輸** 切換為 **直接連線 (ws/wss)**。
- **儀表板可運作但 Mac 能力離線**：這表示應用程式的操作者／控制連線正常，但 companion 節點連線未連接，或缺少其指令介面。開啟選單列裝置區段，檢查 Mac 是否為 `paired · disconnected`。對於 `wss://*.ts.net` Tailscale Serve 端點，應用程式會在憑證輪替後偵測過期的舊版 TLS leaf pin，於 macOS 信任新憑證時清除過期 pin，並自動重試。如果憑證不是系統信任，或主機不是 Tailscale Serve 名稱，請檢查憑證或切換到 **透過 SSH 遠端**。
- **語音喚醒**：在遠端模式中，觸發片語會自動轉送；不需要獨立的轉送器。
## 通知音效
使用含 `openclaw` 和 `node.invoke` 的指令碼，為每則通知選擇音效，例如：
使用含 `openclaw` 和 `node.invoke` 的指令碼，為每個通知選擇音效，例如：
```bash
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
```
應用程式中不再有全域「預設音效」切換；呼叫端會為每次請求選擇音效（或不選）。
應用程式中不再有全域「預設音效」切換；呼叫端會針對每個請求選擇音效（或不選）。
## 相關內容
## 相關
- [macOS 應用程式](/zh-TW/platforms/macos)
- [遠端存取](/zh-TW/gateway/remote)

78
docs/zh-TW/providers/deepseek.md
View File

@ -1,25 +1,25 @@
---
read_when:
- 你想將 DeepSeek 與 OpenClaw 搭配使用
- 需要 API 金鑰環境變數或 CLI 驗證選項
- 你想搭配 OpenClaw 使用 DeepSeek
- 你需要 API 金鑰環境變數或 CLI 驗證選項
summary: DeepSeek 設定（身分驗證 + 模型選擇）
title: DeepSeek
x-i18n:
generated_at: "2026-04-30T03:30:20Z"
generated_at: "2026-04-30T16:29:17Z"
model: gpt-5.5
provider: openai
source_hash: e84d989a7cba8d259779ac02293718050ce51efe6ce2bdbfacb9e22bbfd294ef
source_hash: 6fbc7bd4de14000eaa5c42b17eb8c9312321ed02ac1667e60774ead3f1749eb4
source_path: providers/deepseek.md
workflow: 16
---
[DeepSeek](https://www.deepseek.com) 提供功能強大的 AI 模型，並具備與 OpenAI 相容的 API。
[DeepSeek](https://www.deepseek.com) 提供強大的 AI 模型，並具備與 OpenAI 相容的 API。
| 屬性 | 值 |
| -------- | -------------------------- |
| ---- | -------------------------- |
| 提供者 | `deepseek` |
| 認證 | `DEEPSEEK_API_KEY` |
| API | 與 OpenAI 相容 |
| 驗證 | `DEEPSEEK_API_KEY` |
| API | 與 OpenAI 相容 |
| 基底 URL | `https://api.deepseek.com` |
## 開始使用
@ -28,7 +28,7 @@ x-i18n:
<Step title="取得你的 API 金鑰">
在 [platform.deepseek.com](https://platform.deepseek.com/api_keys) 建立 API 金鑰。
</Step>
<Step title="執行初始設定">
<Step title="執行 onboarding">
```bash
openclaw onboard --auth-choice deepseek-api-key
```
@ -41,7 +41,8 @@ x-i18n:
openclaw models list --provider deepseek
```
若要檢查內建的靜態目錄，而不需要執行中的 Gateway，請使用：
若要在不需要執行中 Gateway 的情況下檢查內建的靜態目錄，
請使用：
```bash
openclaw models list --all --provider deepseek
@ -52,7 +53,7 @@ x-i18n:
<AccordionGroup>
<Accordion title="非互動式設定">
若是指令碼化或無頭安裝，請直接傳入所有旗標：
對於指令碼化或無介面安裝，請直接傳入所有旗標：
```bash
openclaw onboard --non-interactive \
@ -67,52 +68,51 @@ x-i18n:
</AccordionGroup>
<Warning>
如果 Gateway 以 daemon（launchd/systemd）形式執行，請確認 `DEEPSEEK_API_KEY`
可供該處理程序使用（例如放在 `~/.openclaw/.env`，或透過
如果 Gateway 以 daemon（launchd/systemd）形式執行，請確保 `DEEPSEEK_API_KEY`
可供該程序使用（例如放在 `~/.openclaw/.env`，或透過
`env.shellEnv`）。
</Warning>
## 內建目錄
| 模型參照 | 名稱 | 輸入 | Context | 最大輸出 | 備註 |
| 模型參照 | 名稱 | 輸入 | 上下文 | 最大輸出 | 備註 |
| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 預設模型；具備 V4 thinking 能力的介面 |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | 具備 V4 thinking 能力的介面 |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 非 thinking 介面 |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 預設模型；支援 V4 思考能力的介面 |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | 支援 V4 思考能力的介面 |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 非思考介面 |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 啟用推理的 V3.2 介面 |
<Tip>
V4 模型支援 DeepSeek 的 `thinking` 控制。OpenClaw 也會在後續回合重播
DeepSeek `reasoning_content`，因此包含工具呼叫的 thinking 工作階段可以繼續。
DeepSeek `reasoning_content`，因此包含工具呼叫的思考工作階段可以繼續。
搭配 DeepSeek V4 模型使用 `/think xhigh` 或 `/think max`，即可要求 DeepSeek 的
最大 `reasoning_effort`。
</Tip>
## Thinking 與工具
## 思考與工具
DeepSeek V4 thinking 工作階段的重播合約比大多數與 OpenAI 相容的提供者更嚴格：在啟用 thinking 的回合使用工具後，DeepSeek
預期該回合被重播的 assistant 訊息在後續請求中包含
`reasoning_content`。OpenClaw 會在
DeepSeek Plugin 內處理這一點，因此一般的多回合工具使用可搭配
`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro` 運作。
相較於大多數與 OpenAI 相容的提供者，DeepSeek V4 思考工作階段有更嚴格的重播契約：啟用思考的回合使用工具後，DeepSeek
會期望該回合中重播的 assistant 訊息在後續請求中包含
`reasoning_content`。OpenClaw 會在 DeepSeek Plugin 內處理這一點，因此一般的多回合工具使用可搭配
`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro` 正常運作。
如果你將現有工作階段從另一個與 OpenAI 相容的提供者切換到
DeepSeek V4 模型，較舊的 assistant 工具呼叫回合可能沒有原生
DeepSeek `reasoning_content`。OpenClaw 會在 DeepSeek V4 thinking 請求的重播
assistant 訊息中填補該缺失欄位，讓提供者可接受
歷史記錄，而不需要 `/new`。
如果你將既有工作階段從另一個與 OpenAI 相容的提供者切換到
DeepSeek V4 模型，較舊的 assistant 工具呼叫回合可能沒有原生的
DeepSeek `reasoning_content`。OpenClaw 會在 DeepSeek V4 思考請求中，為重播的
assistant 訊息補上該缺少的欄位，讓提供者可接受歷史記錄，而不需要 `/new`。
當 OpenClaw 停用 thinking（包括 UI 的 **None** 選項）時，
在 OpenClaw 中停用思考時（包含 UI 的 **無** 選項），
OpenClaw 會傳送 DeepSeek `thinking: { type: "disabled" }`，並從傳出的歷史記錄中移除重播的
`reasoning_content`。這會讓停用 thinking 的
工作階段留在非 thinking 的 DeepSeek 路徑上。
`reasoning_content`。這會讓已停用思考的工作階段維持在 DeepSeek 的非思考路徑。
預設快速路徑請使用 `deepseek/deepseek-v4-flash`。當你想要更強的 V4 模型，且可接受
較高成本或延遲時，請使用
預設快速路徑請使用 `deepseek/deepseek-v4-flash`。如果你想要更強的 V4 模型，且可以接受
較高成本或延遲，請使用
`deepseek/deepseek-v4-pro`。
## 即時測試
直接即時模型套件在現代模型集合中包含 DeepSeek V4。若只要
執行 DeepSeek V4 直接模型檢查：
直接即時模型套件在現代模型集合中包含 DeepSeek V4。若要
只執行 DeepSeek V4 直接模型檢查：
```bash
OPENCLAW_LIVE_PROVIDERS=deepseek \
@ -120,7 +120,7 @@ OPENCLAW_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \
pnpm test:live src/agents/models.profiles.live.test.ts
```
該即時檢查會確認兩個 V4 模型都能完成，並確認 thinking/工具
該即時檢查會驗證兩個 V4 模型都能完成，並確認思考/工具
後續回合會保留 DeepSeek 所需的重播酬載。
## 設定範例
@ -136,13 +136,13 @@ pnpm test:live src/agents/models.profiles.live.test.ts
}
```
## 相關內容
## 相關
<CardGroup cols={2}>
<Card title="模型選擇" href="/zh-TW/concepts/model-providers" icon="layers">
選擇提供者、模型參照與容錯移轉行為。
</Card>
<Card title="設定參考" href="/zh-TW/gateway/configuration-reference" icon="gear">
agents、模型與提供者的完整設定參考。
agent、模型與提供者的完整設定參考。
</Card>
</CardGroup>

453
docs/zh-TW/providers/openai.md
View File

@ -1,84 +1,84 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 訂閱身分驗證，而不是 API 金鑰
- 你想要在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 訂閱驗證，而不是 API 金鑰
- 你需要更嚴格的 GPT-5 代理執行行為
summary: 在 OpenClaw 中透過 API 金鑰或 Codex 訂閱使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-04-30T03:32:55Z"
generated_at: "2026-04-30T16:29:44Z"
model: gpt-5.5
provider: openai
source_hash: be0e2cd14990a53533c800cd8d305c9c50b0fa7131f6638e7b9d8dd9f2942fe8
source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad
source_path: providers/openai.md
workflow: 16
---
OpenAI 提供 GPT 模型的開發者 API，而 Codex 也可透過 OpenAI 的 Codex 用戶端，作為 ChatGPT 方案的程式碼撰寫代理使用。OpenClaw 會將這些介面分開，讓設定保持可預測。
OpenAI 提供適用於 GPT 模型的開發者 API，Codex 也可透過 OpenAI 的 Codex 用戶端，作為 ChatGPT 方案的程式設計代理使用。OpenClaw 會將這些介面分開，讓設定保持可預期。
OpenClaw 支援三種 OpenAI 系列路由。模型前綴會選擇提供者/驗證路由；另一個獨立的執行階段設定會選擇由誰執行內嵌代理迴圈：
OpenClaw 支援三種 OpenAI 系列路由。模型前綴會選擇提供者/驗證路由；另一個獨立的執行階段設定則會選擇由誰執行內嵌代理迴圈：
- **API 金鑰** — 直接使用 OpenAI Platform，依用量計費（`openai/*` 模型）
- **API 金鑰** — 使用依用量計費的直接 OpenAI Platform 存取（`openai/*` 模型）
- **透過 PI 使用 Codex 訂閱** — 以 ChatGPT/Codex 登入並使用訂閱存取權（`openai-codex/*` 模型）
- **Codex 應用程式伺服器控制框架** — 原生 Codex 應用程式伺服器執行（`openai/*` 模型加上 `agents.defaults.agentRuntime.id: "codex"`）
- **Codex 應用程式伺服器執行架構** — 原生 Codex 應用程式伺服器執行（`openai/*` 模型加上 `agents.defaults.agentRuntime.id: "codex"`）
OpenAI 明確支援在外部工具與 OpenClaw 這類工作流程中使用訂閱 OAuth。
提供者、模型、執行階段和頻道是分開的層級。如果這些標籤被混在一起，請先閱讀 [代理執行階段](/zh-TW/concepts/agent-runtimes)，再變更設定。
提供者、模型、執行階段與通道是不同的層級。如果這些標籤被混在一起，請先閱讀 [代理執行階段](/zh-TW/concepts/agent-runtimes)，再變更設定。
## 快速選擇
| 目標 | 使用 | 備註 |
| 目標 | 使用 | 備註 |
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| 直接以 API 金鑰計費 | `openai/gpt-5.5` | 設定 `OPENAI_API_KEY`，或執行 OpenAI API 金鑰初始設定。 |
| 使用 ChatGPT/Codex 訂閱驗證的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的預設 PI 路由。訂閱設定的首選。 |
| 使用原生 Codex 應用程式伺服器行為的 GPT-5.5 | `openai/gpt-5.5` 加上 `agentRuntime.id: "codex"` | 對該模型參照強制使用 Codex 應用程式伺服器控制框架。 |
| 產生或編輯圖片 | `openai/gpt-image-2` | 可搭配 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 |
| 透明背景圖片 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，並設定 `openai.background=transparent`。 |
| 直接 API 金鑰計費 | `openai/gpt-5.5` | 設定 `OPENAI_API_KEY` 或執行 OpenAI API 金鑰導覽設定。 |
| 使用 ChatGPT/Codex 訂閱驗證的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的預設 PI 路由。最適合訂閱設定的首選。 |
| 使用原生 Codex 應用程式伺服器行為的 GPT-5.5 | `openai/gpt-5.5` 加上 `agentRuntime.id: "codex"` | 對該模型參照強制使用 Codex 應用程式伺服器執行架構。 |
| 圖像生成或編輯 | `openai/gpt-image-2` | 可搭配 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 |
| 透明背景圖像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，以及 `openai.background=transparent`。 |
## 命名對照
這些名稱相似，但不可互換：
| 你看到的名稱 | 層級 | 含義 |
| ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | 提供者前綴 | 直接 OpenAI Platform API 路由。 |
| `openai-codex` | 提供者前綴 | 透過一般 OpenClaw PI 執行器使用的 OpenAI Codex OAuth/訂閱路由。 |
| `codex` plugin | Plugin | 隨附的 OpenClaw plugin，提供原生 Codex 應用程式伺服器執行階段和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | 代理執行階段 | 對內嵌回合強制使用原生 Codex 應用程式伺服器控制框架。 |
| `/codex ...` | 聊天指令集 | 從對話中繫結/控制 Codex 應用程式伺服器執行緒。 |
| `runtime: "acp", agentId: "codex"` | ACP 工作階段路由 | 明確的備援路徑，透過 ACP/acpx 執行 Codex。 |
| 你會看到的名稱 | 層級 | 意義 |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | 提供者前綴 | 直接 OpenAI Platform API 路由。 |
| `openai-codex` | 提供者前綴 | 透過一般 OpenClaw PI 執行器使用的 OpenAI Codex OAuth/訂閱路由。 |
| `codex` Plugin | Plugin | 內建 OpenClaw Plugin，提供原生 Codex 應用程式伺服器執行階段與 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | 代理執行階段 | 對內嵌回合強制使用原生 Codex 應用程式伺服器執行架構。 |
| `/codex ...` | 聊天命令集 | 從對話中繫結/控制 Codex 應用程式伺服器執行緒。 |
| `runtime: "acp", agentId: "codex"` | ACP 工作階段路由 | 透過 ACP/acpx 執行 Codex 的明確後援路徑。 |
這表示設定可以有意同時包含 `openai-codex/*` 和 `codex` plugin。當你想透過 PI 使用 Codex OAuth，同時也想提供原生 `/codex` 聊天控制時，這是有效設定。`openclaw doctor` 會針對這個組合發出警告，讓你確認這是有意為之；它不會重寫設定。
這表示設定可以刻意同時包含 `openai-codex/*` 與 `codex` Plugin。當你想透過 PI 使用 Codex OAuth，同時也想提供原生 `/codex` 聊天控制時，這是有效的。`openclaw doctor` 會對這種組合發出警告，讓你確認這是有意為之；它不會重寫該設定。
<Note>
GPT-5.5 可透過直接 OpenAI Platform API 金鑰存取和訂閱/OAuth 路由使用。使用 `openai/gpt-5.5` 取得直接 `OPENAI_API_KEY` 流量，使用 `openai-codex/gpt-5.5` 透過 PI 取得 Codex OAuth，或使用 `openai/gpt-5.5` 搭配 `agentRuntime.id: "codex"` 取得原生 Codex 應用程式伺服器控制框架。
GPT-5.5 可透過直接 OpenAI Platform API 金鑰存取，以及訂閱/OAuth 路由使用。直接 `OPENAI_API_KEY` 流量請使用 `openai/gpt-5.5`，透過 PI 的 Codex OAuth 請使用 `openai-codex/gpt-5.5`，若要使用原生 Codex 應用程式伺服器執行架構，請使用帶有 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
</Note>
<Note>
啟用 OpenAI plugin，或選擇 `openai-codex/*` 模型，並不會啟用隨附的 Codex 應用程式伺服器 plugin。OpenClaw 只會在你明確以 `agentRuntime.id: "codex"` 選擇原生 Codex 控制框架，或使用舊版 `codex/*` 模型參照時，啟用該 plugin。
如果隨附的 `codex` plugin 已啟用，但 `openai-codex/*` 仍透過 PI 解析，`openclaw doctor` 會發出警告並保持路由不變。
啟用 OpenAI Plugin，或選擇 `openai-codex/*` 模型，並不會啟用內建 Codex 應用程式伺服器 Plugin。OpenClaw 只會在你使用 `agentRuntime.id: "codex"` 明確選擇原生 Codex 執行架構，或使用舊版 `codex/*` 模型參照時，才會啟用該 Plugin。
如果內建 `codex` Plugin 已啟用，但 `openai-codex/*` 仍透過 PI 解析，`openclaw doctor` 會發出警告並保持路由不變。
</Note>
## OpenClaw 功能涵蓋範圍
| OpenAI 能力 | OpenClaw 介面 | 狀態 |
| ------------------------ | ---------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供者 | 支援 |
| Codex 訂閱模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 支援 |
| Codex 應用程式伺服器控制框架 | 使用 `agentRuntime.id: codex` 的 `openai/<model>` | 支援 |
| 伺服器端網頁搜尋 | 原生 OpenAI Responses 工具 | 支援，當網頁搜尋已啟用且未釘選提供者時 |
| 圖片 | `image_generate` | 支援 |
| 影片 | `video_generate` | 支援 |
| 文字轉語音 | `messages.tts.provider: "openai"` / `tts` | 支援 |
| 批次語音轉文字 | `tools.media.audio` / 媒體理解 | 支援 |
| 串流語音轉文字 | Voice Call `streaming.provider: "openai"` | 支援 |
| 即時語音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 支援 |
| 嵌入 | 記憶嵌入提供者 | 支援 |
| OpenAI 能力 | OpenClaw 介面 | 狀態 |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供者 | 是 |
| Codex 訂閱模型 | 搭配 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex 應用程式伺服器執行架構 | 搭配 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 伺服器端網頁搜尋 | 原生 OpenAI Responses 工具 | 是，當網頁搜尋已啟用且未固定提供者時 |
| 圖像 | `image_generate` | 是 |
| 影片 | `video_generate` | 是 |
| 文字轉語音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批次語音轉文字 | `tools.media.audio` / 媒體理解 | 是 |
| 串流語音轉文字 | Voice Call `streaming.provider: "openai"` | 是 |
| 即時語音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
| 嵌入 | 記憶體嵌入提供者 | 是 |
## 記憶嵌入
## 記憶體嵌入
OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_search` 建立索引和查詢嵌入：
OpenClaw 可使用 OpenAI，或與 OpenAI 相容的嵌入端點，為 `memory_search` 建立索引與查詢嵌入：
```json5
{
@ -93,21 +93,21 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
}
```
對於需要非對稱嵌入標籤的 OpenAI 相容端點，請在 `memorySearch` 底下設定 `queryInputType` 和 `documentInputType`。OpenClaw 會將它們作為提供者特定的 `input_type` 請求欄位轉送：查詢嵌入使用 `queryInputType`；已索引的記憶片段和批次索引使用 `documentInputType`。完整範例請參閱[記憶設定參考](/zh-TW/reference/memory-config#provider-specific-config)。
對於需要非對稱嵌入標籤的 OpenAI 相容端點，請在 `memorySearch` 下設定 `queryInputType` 與 `documentInputType`。OpenClaw 會將它們作為提供者特定的 `input_type` 請求欄位轉送：查詢嵌入使用 `queryInputType`；已建立索引的記憶體片段與批次索引使用 `documentInputType`。完整範例請參閱[記憶體設定參考](/zh-TW/reference/memory-config#provider-specific-config)。
## 開始使用
選擇偏好的驗證方法，並依照設定步驟操作。
選擇你偏好的驗證方法，並依照設定步驟操作。
<Tabs>
<Tab title="API 金鑰（OpenAI Platform）">
**最適合：** 直接 API 存取和依用量計費。
**最適合：** 直接 API 存取與依用量計費。
<Steps>
<Step title="取得你的 API 金鑰">
從 [OpenAI Platform 儀表板](https://platform.openai.com/api-keys) 建立或複製 API 金鑰。
從 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 建立或複製 API 金鑰。
</Step>
<Step title="執行初始設定">
<Step title="執行導覽設定">
```bash
openclaw onboard --auth-choice openai-api-key
```
@ -127,14 +127,14 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
### 路由摘要
| 模型參照 | 執行階段設定 | 路由 | 驗證 |
| ---------------------- | -------------------------------- | -------------------------- | ---------------- |
| `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 應用程式伺服器控制框架 | Codex 應用程式伺服器 |
| 模型參照 | 執行階段設定 | 路由 | 驗證 |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 應用程式伺服器執行架構 | Codex 應用程式伺服器 |
<Note>
除非你明確強制使用 Codex 應用程式伺服器控制框架，否則 `openai/*` 是直接 OpenAI API 金鑰路由。使用 `openai-codex/*` 透過預設 PI 執行器取得 Codex OAuth，或使用 `openai/gpt-5.5` 搭配 `agentRuntime.id: "codex"` 進行原生 Codex 應用程式伺服器執行。
`openai/*` 是直接 OpenAI API 金鑰路由，除非你明確強制使用 Codex 應用程式伺服器執行架構。若要透過預設 PI 執行器使用 Codex OAuth，請使用 `openai-codex/*`；若要使用原生 Codex 應用程式伺服器執行，請使用搭配 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
</Note>
### 設定範例
@ -147,13 +147,13 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
```
<Warning>
OpenClaw 不會公開 `openai/gpt-5.3-codex-spark`。即時 OpenAI API 請求會拒絕該模型，目前的 Codex 型錄也不會公開它。
OpenClaw 不會公開 `openai/gpt-5.3-codex-spark`。即時 OpenAI API 請求會拒絕該模型，目前的 Codex 目錄也未公開它。
</Warning>
</Tab>
<Tab title="Codex 訂閱">
**最適合：** 使用你的 ChatGPT/Codex 訂閱，而不是獨立 API 金鑰。Codex 雲端需要 ChatGPT 登入。
**最適合：** 使用你的 ChatGPT/Codex 訂閱，而不是另外使用 API 金鑰。Codex 雲端需要 ChatGPT 登入。
<Steps>
<Step title="執行 Codex OAuth">
@ -167,7 +167,7 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
openclaw models auth login --provider openai-codex
```
對於無介面或不方便使用回呼的設定，加入 `--device-code`，即可改用 ChatGPT 裝置碼流程登入，而不是 localhost 瀏覽器回呼：
對於無頭或不適合回呼的設定，請加入 `--device-code`，改用 ChatGPT 裝置碼流程登入，而不是 localhost 瀏覽器回呼：
```bash
openclaw models auth login --provider openai-codex --device-code
@ -189,18 +189,15 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
| 模型參照 | 執行階段設定 | 路由 | 驗證 |
|-----------|----------------|-------|------|
| `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | 透過 PI 使用 ChatGPT/Codex OAuth | Codex 登入 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍為 PI，除非某個 plugin 明確宣告 `openai-codex` | Codex 登入 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 應用程式伺服器控制框架 | Codex 應用程式伺服器驗證 |
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 透過 PI 使用 ChatGPT/Codex OAuth | Codex 登入 |
| `openai-codex/gpt-5.4-mini` | 省略 / `runtime: "pi"` | 透過 PI 使用 ChatGPT/Codex OAuth | Codex 登入 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍為 PI，除非有 Plugin 明確宣告 `openai-codex` | Codex 登入 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 應用程式伺服器執行架構 | Codex 應用程式伺服器驗證 |
<Note>
驗證/設定檔指令請繼續使用 `openai-codex` 提供者 ID。`openai-codex/*` 模型前綴也是 Codex OAuth 的明確 PI 路由。它不會選擇或自動啟用隨附的 Codex 應用程式伺服器控制框架。
驗證/設定檔命令請繼續使用 `openai-codex` 提供者 ID。`openai-codex/*` 模型前綴也是 Codex OAuth 的明確 PI 路由。它不會選擇或自動啟用內建 Codex 應用程式伺服器執行架構。
</Note>
<Warning>
`openai-codex/gpt-5.4-mini` 不是支援的 Codex OAuth 路由。請搭配 OpenAI API 金鑰使用 `openai/gpt-5.4-mini`，或搭配 Codex OAuth 使用 `openai-codex/gpt-5.5`。
</Warning>
### 設定範例
```json5
@ -210,33 +207,36 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
```
<Note>
初始設定不再從 `~/.codex` 匯入 OAuth 資料。請使用瀏覽器 OAuth（預設）或上方的裝置碼流程登入；OpenClaw 會在自己的代理驗證儲存區中管理產生的憑證。
導覽設定不再從 `~/.codex` 匯入 OAuth 資料。請使用瀏覽器 OAuth（預設）或上方的裝置碼流程登入；OpenClaw 會在自己的代理驗證儲存區中管理產生的憑證。
</Note>
### 狀態指示器
聊天中的 `/status` 會顯示目前工作階段啟用的模型執行階段。
預設 PI harness 會顯示為 `Runtime: OpenClaw Pi Default`。選取隨附的 Codex app-server harness 時，`/status` 會顯示
`Runtime: OpenAI Codex`。現有工作階段會保留其記錄的 harness id，因此在變更 `agentRuntime` 後，若希望 `/status` 反映新的 PI/Codex 選擇，請使用
聊天 `/status` 會顯示目前工作階段作用中的模型執行階段。
預設 PI 執行框架會顯示為 `Runtime: OpenClaw Pi Default`。選取
內建 Codex app-server 執行框架時，`/status` 會顯示
`Runtime: OpenAI Codex`。現有工作階段會保留其記錄的執行框架 id，因此如果你希望
`/status` 反映新的 PI/Codex 選擇，請在變更 `agentRuntime` 後使用
`/new` 或 `/reset`。
### Doctor 警告
如果啟用隨附的 `codex` Plugin，同時選取此分頁的
`openai-codex/*` 路由，`openclaw doctor` 會警告模型仍透過 PI 解析。當這是預期的訂閱驗證路由時，請保持設定不變。只有在你需要原生 Codex
app-server 執行時，才切換至 `openai/<model>` 加上
如果在選取此分頁的
`openai-codex/*` 路由時啟用了內建的 `codex` Plugin，`openclaw doctor` 會警告模型
仍然透過 PI 解析。當這是預期的訂閱驗證路由時，請保持設定不變。只有在你想要原生 Codex
app-server 執行時，才切換到 `openai/<model>` 加上
`agentRuntime.id: "codex"`。
### 上下文視窗上限
### Context 視窗上限
OpenClaw 會將模型中繼資料和執行階段上下文上限視為不同值。
OpenClaw 將模型中繼資料和執行階段 context 上限視為分開的值。
對於透過 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
- 原生 `contextWindow`：`1000000`
- 預設執行階段 `contextTokens` 上限：`272000`
較小的預設上限在實務上有更好的延遲與品質特性。可用 `contextTokens` 覆寫：
較小的預設上限在實務上具有更好的延遲和品質特性。使用 `contextTokens` 覆寫它：
```json5
{
@ -251,12 +251,14 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
```
<Note>
使用 `contextWindow` 宣告原生模型中繼資料。使用 `contextTokens` 限制執行階段上下文預算。
使用 `contextWindow` 宣告原生模型中繼資料。使用 `contextTokens` 限制執行階段 context 預算。
</Note>
### 目錄復原
當上游 Codex 目錄中繼資料存在時，OpenClaw 會將它用於 `gpt-5.5`。如果在帳戶已驗證時，線上 Codex 探索遺漏 `openai-codex/gpt-5.5` 列，OpenClaw 會合成該 OAuth 模型列，讓 cron、子代理程式和已設定的預設模型執行不會因
當上游 Codex 目錄中繼資料存在時，OpenClaw 會將其用於 `gpt-5.5`。如果即時 Codex 探索在
帳號已通過驗證時省略了 `openai-codex/gpt-5.5` 列，OpenClaw 會合成該 OAuth 模型列，讓
cron、子代理程式和已設定的預設模型執行不會因
`Unknown model` 而失敗。
</Tab>
@ -264,32 +266,37 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
## 原生 Codex app-server 驗證
原生 Codex app-server harness 使用 `openai/*` 模型參照加上
`agentRuntime.id: "codex"`，但其驗證仍以帳戶為基礎。OpenClaw 會依下列順序選取驗證：
原生 Codex app-server 執行框架使用 `openai/*` 模型參照加上
`agentRuntime.id: "codex"`，但其驗證仍然以帳號為基礎。OpenClaw
會依此順序選取驗證：
1. 綁定至代理程式的明確 OpenClaw `openai-codex` 驗證設定檔。
2. app-server 的既有帳戶，例如本機 Codex CLI ChatGPT 登入。
3. 僅限本機 stdio app-server 啟動，當 app-server 回報沒有帳戶且仍需要
OpenAI 驗證時，使用 `CODEX_API_KEY`，接著使用
2. app-server 的現有帳號，例如本機 Codex CLI ChatGPT 登入。
3. 僅適用於本機 stdio app-server 啟動時，當 app-server 回報沒有帳號但仍需要
OpenAI 驗證，使用 `CODEX_API_KEY`，接著使用
`OPENAI_API_KEY`。
這表示本機 ChatGPT/Codex 訂閱登入不會只因 gateway 程序也有供直接 OpenAI 模型或嵌入使用的 `OPENAI_API_KEY` 而被取代。環境 API key 後援僅是本機 stdio 無帳戶路徑；它不會傳送到 WebSocket app-server 連線。選取訂閱樣式的 Codex 設定檔時，OpenClaw 也會讓 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
不進入產生的 stdio app-server 子程序，並透過 app-server login RPC 傳送所選認證。
這表示本機 ChatGPT/Codex 訂閱登入不會只因 gateway 行程同時具有用於直接 OpenAI 模型
或嵌入的 `OPENAI_API_KEY` 而被取代。環境變數 API 金鑰後援僅限本機 stdio 無帳號路徑；它
不會傳送到 WebSocket app-server 連線。選取訂閱樣式的 Codex
設定檔時，OpenClaw 也會將 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
排除在產生的 stdio app-server 子行程之外，並透過 app-server 登入 RPC 傳送選取的認證。
## 圖片生成
隨附的 `openai` Plugin 會透過 `image_generate` 工具註冊圖片生成。
它透過相同的 `openai/gpt-image-2` 模型參照，同時支援 OpenAI API key 圖片生成與 Codex OAuth 圖片生成。
內建的 `openai` Plugin 會透過 `image_generate` 工具註冊圖片生成。
它透過相同的 `openai/gpt-image-2` 模型參照，同時支援 OpenAI API 金鑰圖片生成和 Codex OAuth 圖片
生成。
| 能力 | OpenAI API key | Codex OAuth |
| 能力 | OpenAI API 金鑰 | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| 模型參照 | `openai/gpt-image-2` | `openai/gpt-image-2` |
| 驗證 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登入 |
| 傳輸 | OpenAI Images API | Codex Responses 後端 |
| 每次請求最多圖片數 | 4 | 4 |
| 編輯模式 | 已啟用（最多 5 張參考圖片） | 已啟用（最多 5 張參考圖片） |
| 尺寸覆寫 | 支援，包含 2K/4K 尺寸 | 支援，包含 2K/4K 尺寸 |
| 長寬比 / 解析度 | 不轉送至 OpenAI Images API | 安全時會對應到支援的尺寸 |
| 每次要求的最大圖片數 | 4 | 4 |
| 編輯模式 | 已啟用（最多 5 張參考圖片） | 已啟用（最多 5 張參考圖片） |
| 尺寸覆寫 | 支援，包括 2K/4K 尺寸 | 支援，包括 2K/4K 尺寸 |
| 長寬比 / 解析度 | 不轉送至 OpenAI Images API | 在安全時對應到支援的尺寸 |
```json5
{
@ -302,19 +309,24 @@ OpenClaw 可使用 OpenAI，或 OpenAI 相容的嵌入端點，為 `memory_searc
```
<Note>
請參閱[圖片生成](/zh-TW/tools/image-generation)，了解共用工具參數、提供者選擇和容錯移轉行為。
請參閱 [圖片生成](/zh-TW/tools/image-generation)，了解共用工具參數、供應商選取和容錯移轉行為。
</Note>
`gpt-image-2` 是 OpenAI 文字轉圖片生成和圖片編輯的預設值。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作為明確的模型覆寫使用。請使用 `openai/gpt-image-1.5` 取得透明背景
PNG/WebP 輸出；目前的 `gpt-image-2` API 會拒絕
`gpt-image-2` 是 OpenAI 文字轉圖片生成和圖片
編輯的預設值。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作為
明確模型覆寫使用。使用 `openai/gpt-image-1.5` 輸出透明背景
PNG/WebP；目前的 `gpt-image-2` API 會拒絕
`background: "transparent"`。
對於透明背景請求，代理程式應呼叫 `image_generate`，並使用
對於透明背景要求，代理程式應呼叫 `image_generate`，並使用
`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及
`background: "transparent"`；較舊的 `openai.background` 提供者選項仍會被接受。OpenClaw 也會保護公開 OpenAI 和
OpenAI Codex OAuth 路由，將預設 `openai/gpt-image-2` 透明請求重寫為 `gpt-image-1.5`；Azure 和自訂 OpenAI 相容端點會保留其已設定的部署/模型名稱。
`background: "transparent"`；較舊的 `openai.background` 供應商選項
仍會被接受。OpenClaw 也會保護公開 OpenAI 和
OpenAI Codex OAuth 路由，方法是將預設 `openai/gpt-image-2` 透明
要求改寫為 `gpt-image-1.5`；Azure 和自訂 OpenAI 相容端點會保留
其設定的部署/模型名稱。
相同設定也會暴露給無頭 CLI 執行：
相同設定也會公開給無頭 CLI 執行使用：
```bash
openclaw infer image generate \
@ -325,14 +337,20 @@ openclaw infer image generate \
--json
```
從輸入檔案開始時，請搭配
從輸入檔案開始時，請對
`openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 旗標。
`--openai-background` 仍可作為 OpenAI 專用別名使用。
對於 Codex OAuth 安裝，請保留相同的 `openai/gpt-image-2` 參照。設定
`openai-codex` OAuth 設定檔時，OpenClaw 會解析該儲存的 OAuth 存取權杖，並透過 Codex Responses 後端傳送圖片請求。它不會先嘗試 `OPENAI_API_KEY`，也不會針對該請求靜默後援到 API key。當你想改用直接 OpenAI Images API 路由時，請明確設定 `models.providers.openai`，搭配 API key、自訂基底 URL 或 Azure 端點。
對於 Codex OAuth 安裝，保留相同的 `openai/gpt-image-2` 參照。設定
`openai-codex` OAuth 設定檔時，OpenClaw 會解析該已儲存的 OAuth
存取權杖，並透過 Codex Responses 後端傳送圖片要求。它
不會先嘗試 `OPENAI_API_KEY`，也不會針對該
要求默默後援到 API 金鑰。當你想要改用直接 OpenAI Images API
路由時，請明確設定 `models.providers.openai`，並提供 API 金鑰、
自訂基底 URL 或 Azure 端點。
如果該自訂圖片端點位於受信任的 LAN/私人位址，也請設定
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此選擇加入設定，OpenClaw 會持續封鎖私人/內部 OpenAI 相容圖片端點。
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；OpenClaw 會持續封鎖
私人/內部 OpenAI 相容圖片端點，除非存在此選擇加入設定。
生成：
@ -354,15 +372,15 @@ openclaw infer image generate \
## 影片生成
隨附的 `openai` Plugin 會透過 `video_generate` 工具註冊影片生成。
內建的 `openai` Plugin 會透過 `video_generate` 工具註冊影片生成。
| 能力 | 值 |
| ------------ | --------------------------------------------------------------------------------- |
| 預設模型 | `openai/sora-2` |
| 模式 | 文字轉影片、圖片轉影片、單一影片編輯 |
| 參考輸入 | 1 張圖片或 1 部影片 |
| 尺寸覆寫 | 支援 |
| 其他覆寫 | `aspectRatio`、`resolution`、`audio`、`watermark` 會被忽略並顯示工具警告 |
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 預設模型 | `openai/sora-2` |
| 模式 | 文字轉影片、圖片轉影片、單一影片編輯 |
| 參考輸入 | 1 張圖片或 1 部影片 |
| 尺寸覆寫 | 支援 |
| 其他覆寫 | `aspectRatio`、`resolution`、`audio`、`watermark` 會被忽略並產生工具警告 |
```json5
{
@ -375,22 +393,22 @@ openclaw infer image generate \
```
<Note>
請參閱[影片生成](/zh-TW/tools/video-generation)，了解共用工具參數、提供者選擇和容錯移轉行為。
請參閱 [影片生成](/zh-TW/tools/video-generation)，了解共用工具參數、供應商選取和容錯移轉行為。
</Note>
## GPT-5 提示貢獻
OpenClaw 會為跨提供者的 GPT-5 系列執行加入共用 GPT-5 提示貢獻。它依模型 id 套用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他相容的 GPT-5 參照會收到相同覆蓋。較舊的 GPT-4.x 模型不會。
OpenClaw 會為跨供應商的 GPT-5 系列執行加入共用 GPT-5 提示貢獻。它依模型 id 套用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他相容 GPT-5 參照會收到相同的覆蓋層。較舊的 GPT-4.x 模型不會。
隨附的原生 Codex harness 會透過 Codex app-server 開發者指令使用相同的 GPT-5 行為與 Heartbeat 覆蓋，因此透過 `agentRuntime.id: "codex"` 強制執行的 `openai/gpt-5.x` 工作階段，即使 Codex 擁有其餘 harness 提示，也會保留相同的跟進與主動 Heartbeat 指引。
內建的原生 Codex 執行框架會透過 Codex app-server 開發者指示使用相同的 GPT-5 行為和 heartbeat 覆蓋層，因此即使 Codex 擁有執行框架提示的其餘部分，強制透過 `agentRuntime.id: "codex"` 執行的 `openai/gpt-5.x` 工作階段仍會保留相同的執行到底和主動 heartbeat 指引。
GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形狀、完成檢查和驗證加入帶標籤的行為契約。通道專屬回覆與靜默訊息行為會保留在共用 OpenClaw 系統提示與輸出傳遞政策中。對於相符模型，GPT-5 指引一律啟用。友善互動風格層是獨立且可設定的。
GPT-5 貢獻會加入已標記的行為契約，涵蓋 persona 持久性、執行安全、工具紀律、輸出形狀、完成檢查和驗證。特定通道的回覆和靜默訊息行為會保留在共用 OpenClaw 系統提示和輸出傳遞政策中。GPT-5 指引會一律對符合的模型啟用。友善互動樣式層是分開且可設定的。
| 值 | 效果 |
| ---------------------- | -------------------------- |
| `"friendly"`（預設） | 啟用友善互動風格層 |
| `"on"` | `"friendly"` 的別名 |
| `"off"` | 僅停用友善風格層 |
| 值 | 效果 |
| ---------------------- | ---------------------------- |
| `"friendly"`（預設） | 啟用友善互動樣式層 |
| `"on"` | `"friendly"` 的別名 |
| `"off"` | 僅停用友善樣式層 |
<Tabs>
<Tab title="設定">
@ -414,30 +432,30 @@ GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形
</Tabs>
<Tip>
值在執行階段不區分大小寫，因此 `"Off"` 和 `"off"` 都會停用友善風格層。
值在執行階段不區分大小寫，因此 `"Off"` 和 `"off"` 都會停用友善樣式層。
</Tip>
<Note>
當未設定共用的 `agents.defaults.promptOverlays.gpt5.personality` 設定時，仍會讀取舊版 `plugins.entries.openai.config.personality` 作為相容性後援。
當共用 `agents.defaults.promptOverlays.gpt5.personality` 設定未設定時，仍會讀取舊版 `plugins.entries.openai.config.personality` 作為相容性後援。
</Note>
## 語音與語音辨識
## 語音和語音辨識
<AccordionGroup>
<Accordion title="語音合成 (TTS)">
隨附的 `openai` Plugin 會為 `messages.tts` 介面註冊語音合成。
<Accordion title="語音合成（TTS）">
內建的 `openai` Plugin 會為 `messages.tts` 表面註冊語音合成。
| 設定 | 設定路徑 | 預設值 |
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 語音 | `messages.tts.providers.openai.voice` | `coral` |
| 聲音 | `messages.tts.providers.openai.voice` | `coral` |
| 速度 | `messages.tts.providers.openai.speed` |（未設定）|
| 指令 | `messages.tts.providers.openai.instructions` |（未設定，僅限 `gpt-4o-mini-tts`）|
| 格式 | `messages.tts.providers.openai.responseFormat` | 語音記事使用 `opus`，檔案使用 `mp3` |
| API key | `messages.tts.providers.openai.apiKey` | 後援至 `OPENAI_API_KEY` |
| 指示 | `messages.tts.providers.openai.instructions` |（未設定，僅 `gpt-4o-mini-tts`）|
| 格式 | `messages.tts.providers.openai.responseFormat` | 語音筆記使用 `opus`，檔案使用 `mp3` |
| API 金鑰 | `messages.tts.providers.openai.apiKey` | 後援到 `OPENAI_API_KEY` |
| 基底 URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用語音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用聲音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
```json5
{
@ -458,14 +476,15 @@ GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形
</Accordion>
<Accordion title="語音轉文字">
隨附的 `openai` Plugin 會透過
OpenClaw 的媒體理解轉錄介面註冊批次語音轉文字。
內建的 `openai` Plugin 會透過
OpenClaw 的媒體理解轉錄表面註冊批次語音轉文字。
- 預設模型：`gpt-4o-transcribe`
- 端點：OpenAI REST `/v1/audio/transcriptions`
- 輸入路徑：multipart 音訊檔案上傳
- 由 OpenClaw 在任何輸入音訊轉錄使用
`tools.media.audio` 的地方支援，包括 Discord 語音頻道片段和通道音訊附件
- 在 OpenClaw 中，任何入站音訊轉錄使用
`tools.media.audio` 的地方都支援，包括 Discord 語音頻道片段和通道
音訊附件
若要強制對傳入音訊轉錄使用 OpenAI：
@ -487,12 +506,12 @@ GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形
}
```
語言與提示提示會在由共用音訊媒體設定或逐次呼叫的轉錄請求提供時轉送至 OpenAI。
提供語言與提示提示時，會從共用音訊媒體設定或逐次呼叫的轉錄請求轉送至 OpenAI。
</Accordion>
<Accordion title="即時轉錄">
內建的 `openai` Plugin 會為 Voice Call Plugin 註冊即時轉錄。
內建的 `openai` Plugin 會為語音通話 Plugin 註冊即時轉錄。
| 設定 | 設定路徑 | 預設值 |
|---------|------------|---------|
@ -501,16 +520,16 @@ GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形
| 提示 | `...openai.prompt` | （未設定） |
| 靜音持續時間 | `...openai.silenceDurationMs` | `800` |
| VAD 閾值 | `...openai.vadThreshold` | `0.5` |
| API 金鑰 | `...openai.apiKey` | 回退至 `OPENAI_API_KEY` |
| API 金鑰 | `...openai.apiKey` | 退回使用 `OPENAI_API_KEY` |
<Note>
使用 WebSocket 連線至 `wss://api.openai.com/v1/realtime`，搭配 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音訊。此串流供應器用於 Voice Call 的即時轉錄路徑；Discord 語音目前會錄製短片段，並改用批次 `tools.media.audio` 轉錄路徑。
使用 WebSocket 連線至 `wss://api.openai.com/v1/realtime`，並採用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音訊。這個串流提供者用於語音通話的即時轉錄路徑；Discord 語音目前會錄製短片段，並改用批次 `tools.media.audio` 轉錄路徑。
</Note>
</Accordion>
<Accordion title="即時語音">
內建的 `openai` Plugin 會為 Voice Call Plugin 註冊即時語音。
內建的 `openai` Plugin 會為語音通話 Plugin 註冊即時語音。
| 設定 | 設定路徑 | 預設值 |
|---------|------------|---------|
@ -519,19 +538,14 @@ GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形
| 溫度 | `...openai.temperature` | `0.8` |
| VAD 閾值 | `...openai.vadThreshold` | `0.5` |
| 靜音持續時間 | `...openai.silenceDurationMs` | `500` |
| API 金鑰 | `...openai.apiKey` | 回退至 `OPENAI_API_KEY` |
| API 金鑰 | `...openai.apiKey` | 退回使用 `OPENAI_API_KEY` |
<Note>
透過 `azureEndpoint` 和 `azureDeployment` 設定鍵支援後端即時橋接的 Azure OpenAI。支援雙向工具呼叫。使用 G.711 u-law 音訊格式。
透過 `azureEndpoint` 與 `azureDeployment` 設定鍵支援 Azure OpenAI，用於後端即時橋接。支援雙向工具呼叫。使用 G.711 u-law 音訊格式。
</Note>
<Note>
Control UI Talk 會使用 OpenAI 瀏覽器即時工作階段，搭配 Gateway 簽發的
暫時性用戶端密鑰，並對 OpenAI Realtime API 進行直接的瀏覽器 WebRTC SDP 交換。維護者即時驗證可使用
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`；
OpenAI 端會在 Node 中簽發用戶端密鑰，使用假麥克風媒體產生瀏覽器 SDP offer，
將其傳送至 OpenAI，並套用 SDP answer
而不記錄密鑰。
Control UI Talk 使用 OpenAI 瀏覽器即時工作階段，搭配 Gateway 簽發的暫時用戶端密鑰，並由瀏覽器直接與 OpenAI Realtime API 進行 WebRTC SDP 交換。維護者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 進行即時驗證；OpenAI 端會在 Node 中簽發用戶端密鑰、使用假麥克風媒體產生瀏覽器 SDP offer、將它送出至 OpenAI，並套用 SDP answer，而不記錄密鑰。
</Note>
</Accordion>
@ -539,30 +553,21 @@ GPT-5 貢獻會為人格持續性、執行安全性、工具紀律、輸出形
## Azure OpenAI 端點
內建的 `openai` 供應器可以透過覆寫基底 URL，將影像
生成目標指向 Azure OpenAI 資源。在影像生成路徑上，OpenClaw
會偵測 `models.providers.openai.baseUrl` 上的 Azure 主機名稱，並自動切換至
Azure 的請求形狀。
內建的 `openai` 提供者可透過覆寫基底 URL，將影像生成導向 Azure OpenAI 資源。在影像生成路徑上，OpenClaw 會偵測 `models.providers.openai.baseUrl` 上的 Azure 主機名稱，並自動切換至 Azure 的請求格式。
<Note>
即時語音使用獨立的設定路徑
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
且不受 `models.providers.openai.baseUrl` 影響。請參閱 [語音與語音](#voice-and-speech) 下的 **即時
語音** 手風琴區塊以了解其 Azure
設定。
即時語音使用獨立的設定路徑（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影響。其 Azure 設定請參閱 [語音與語音合成](#voice-and-speech) 底下的 **即時語音** 摺疊區塊。
</Note>
在以下情況使用 Azure OpenAI：
在下列情況使用 Azure OpenAI：
- 你已有 Azure OpenAI 訂閱、配額或企業協議
- 你已經有 Azure OpenAI 訂閱、配額或企業合約
- 你需要 Azure 提供的區域資料駐留或合規控制
- 你想讓流量保留在既有的 Azure 租用戶內
- 你想將流量保留在既有的 Azure 租用戶內
### 設定
若要透過內建的 `openai` 供應器使用 Azure 影像生成，請將
`models.providers.openai.baseUrl` 指向你的 Azure 資源，並將 `apiKey` 設為
Azure OpenAI 金鑰（而非 OpenAI Platform 金鑰）：
若要透過內建的 `openai` 提供者使用 Azure 影像生成，請將 `models.providers.openai.baseUrl` 指向你的 Azure 資源，並將 `apiKey` 設為 Azure OpenAI 金鑰（不是 OpenAI Platform 金鑰）：
```json5
{
@ -577,103 +582,79 @@ Azure OpenAI 金鑰（而非 OpenAI Platform 金鑰）：
}
```
OpenClaw 會針對 Azure 影像生成
路由識別這些 Azure 主機後綴：
OpenClaw 會針對 Azure 影像生成路由辨識以下 Azure 主機尾碼：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
對於已識別 Azure 主機上的影像生成請求，OpenClaw 會：
在已辨識的 Azure 主機上進行影像生成請求時，OpenClaw 會：
- 傳送 `api-key` 標頭，而不是 `Authorization: Bearer`
- 使用部署範圍路徑（`/openai/deployments/{deployment}/...`）
- 在每個請求後附加 `?api-version=...`
- 對 Azure 影像生成呼叫使用 600 秒的預設請求逾時。
- 在每個請求附加 `?api-version=...`
- 對 Azure 影像生成呼叫使用 600 秒預設請求逾時。
逐次呼叫的 `timeoutMs` 值仍會覆寫此預設值。
其他基底 URL（公開 OpenAI、OpenAI 相容代理）會保留標準的
OpenAI 影像請求形狀。
其他基底 URL（公開 OpenAI、OpenAI 相容代理）會保留標準 OpenAI 影像請求格式。
<Note>
`openai` 供應器影像生成路徑的 Azure 路由需要
OpenClaw 2026.4.22 或更新版本。較早版本會將任何自訂
`openai.baseUrl` 視為公開 OpenAI 端點，並且會在 Azure
影像部署上失敗。
`openai` 提供者影像生成路徑的 Azure 路由需要 OpenClaw 2026.4.22 或更新版本。較早版本會將任何自訂 `openai.baseUrl` 視為公開 OpenAI 端點，並且在連至 Azure 影像部署時失敗。
</Note>
### API 版本
設定 `AZURE_OPENAI_API_VERSION` 以釘選 Azure 影像生成路徑的特定 Azure 預覽版或 GA 版本：
設定 `AZURE_OPENAI_API_VERSION`，即可為 Azure 影像生成路徑固定特定 Azure preview 或 GA 版本：
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
當此變數未設定時，預設值為 `2024-12-01-preview`。
未設定變數時，預設值為 `2024-12-01-preview`。
### 模型名稱即部署名稱
### 模型名稱就是部署名稱
Azure OpenAI 會將模型繫結至部署。對於透過內建 `openai` 供應器
路由的 Azure 影像生成請求，OpenClaw 中的 `model` 欄位
必須是你在 Azure 入口網站中設定的 **Azure 部署名稱**，而不是
公開 OpenAI 模型 ID。
Azure OpenAI 會將模型繫結至部署。對於透過內建 `openai` 提供者路由的 Azure 影像生成請求，OpenClaw 中的 `model` 欄位必須是你在 Azure 入口網站中設定的 **Azure 部署名稱**，而不是公開 OpenAI 模型 ID。
如果你建立名為 `gpt-image-2-prod` 且提供 `gpt-image-2` 的部署：
如果你建立名為 `gpt-image-2-prod`、提供 `gpt-image-2` 的部署：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
```
相同的部署名稱規則也適用於透過
內建 `openai` 供應器路由的影像生成呼叫。
相同的部署名稱規則也適用於透過內建 `openai` 提供者路由的影像生成呼叫。
### 區域可用性
Azure 影像生成目前僅在部分區域
可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
`uaenorth`）。建立
部署前，請檢查 Microsoft 目前的區域清單，並確認你的區域提供特定模型。
Azure 影像生成目前僅在部分區域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。建立部署前，請查看 Microsoft 目前的區域清單，並確認你的區域提供該特定模型。
### 參數差異
Azure OpenAI 和公開 OpenAI 不一定接受相同的影像參數。
Azure 可能會拒絕公開 OpenAI 允許的選項（例如
`gpt-image-2` 上的某些 `background` 值），或只在特定模型
版本上公開這些選項。這些差異來自 Azure 與底層模型，而非
OpenClaw。如果 Azure 請求因驗證錯誤而失敗，請在
Azure 入口網站中檢查你的特定部署與 API 版本支援的
參數集。
Azure OpenAI 與公開 OpenAI 不一定接受相同的影像參數。Azure 可能會拒絕公開 OpenAI 允許的選項（例如 `gpt-image-2` 上的某些 `background` 值），或僅在特定模型版本上公開這些選項。這些差異來自 Azure 與底層模型，而不是 OpenClaw。如果 Azure 請求因驗證錯誤而失敗，請在 Azure 入口網站中檢查你的特定部署與 API 版本支援的參數集。
<Note>
Azure OpenAI 使用原生傳輸和相容行為，但不會接收
OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configuration) 下的 **原生與 OpenAI 相容
路由** 手風琴區塊。
Azure OpenAI 使用原生傳輸與相容行為，但不會接收 OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configuration) 底下的 **原生與 OpenAI 相容路由** 摺疊區塊。
對於 Azure 上的聊天或 Responses 流量（超出影像生成），請使用
上線流程或專用的 Azure 供應器設定 — 單獨的 `openai.baseUrl`
不會套用 Azure API/驗證形狀。另有
`azure-openai-responses/*` 供應器；請參閱
下方的伺服器端 Compaction 手風琴區塊。
對於 Azure 上的聊天或 Responses 流量（影像生成以外），請使用導覽設定流程或專用的 Azure 提供者設定；僅設定 `openai.baseUrl` 不會套用 Azure API/驗證格式。另有獨立的 `azure-openai-responses/*` 提供者；請參閱下方的伺服器端 Compaction 摺疊區塊。
</Note>
## 進階設定
<AccordionGroup>
<Accordion title="傳輸（WebSocket 與 SSE）">
OpenClaw 對 `openai/*` 和 `openai-codex/*` 都使用 WebSocket 優先，並以 SSE 回退（`"auto"`）。
OpenClaw 對 `openai/*` 與 `openai-codex/*` 都採用 WebSocket 優先，並以 SSE 作為後備（`"auto"`）。
在 `"auto"` 模式中，OpenClaw 會：
- 在回退至 SSE 前重試一次早期 WebSocket 失敗
- 失敗後，將 WebSocket 標記為降級約 60 秒，並在冷卻期間使用 SSE
- 附加穩定的工作階段與回合身分標頭，以支援重試與重新連線
- 在退回 SSE 前，重試一次早期 WebSocket 失敗
- 發生失敗後，將 WebSocket 標記為降級約 60 秒，並在冷卻期間使用 SSE
- 為重試與重新連線附加穩定的工作階段與回合身分標頭
- 在傳輸變體之間正規化用量計數器（`input_tokens` / `prompt_tokens`）
| 值 | 行為 |
|-------|----------|
| `"auto"`（預設） | WebSocket 優先，SSE 回退 |
| `"sse"` | 僅強制使用 SSE |
| `"websocket"` | 僅強制使用 WebSocket |
| `"auto"`（預設） | WebSocket 優先，SSE 後備 |
| `"sse"` | 強制僅使用 SSE |
| `"websocket"` | 強制僅使用 WebSocket |
```json5
{
@ -698,8 +679,8 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
</Accordion>
<Accordion title="WebSocket 暖機">
OpenClaw 預設為 `openai/*` 和 `openai-codex/*` 啟用 WebSocket 暖機，以降低第一回合延遲。
<Accordion title="WebSocket 預熱">
OpenClaw 預設會為 `openai/*` 與 `openai-codex/*` 啟用 WebSocket 預熱，以降低第一回合延遲。
```json5
// Disable warm-up
@ -719,12 +700,12 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
</Accordion>
<Accordion title="快速模式">
OpenClaw 為 `openai/*` 和 `openai-codex/*` 公開共用的快速模式切換：
OpenClaw 為 `openai/*` 與 `openai-codex/*` 提供共用的快速模式切換：
- **聊天/UI：** `/fast status|on|off`
- **設定：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
啟用時，OpenClaw 會將快速模式對應至 OpenAI 優先處理（`service_tier = "priority"`）。既有的 `service_tier` 值會保留，且快速模式不會重寫 `reasoning` 或 `text.verbosity`。
啟用後，OpenClaw 會將快速模式對應至 OpenAI 優先處理（`service_tier = "priority"`）。既有的 `service_tier` 值會保留，且快速模式不會改寫 `reasoning` 或 `text.verbosity`。
```json5
{
@ -745,7 +726,7 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
</Accordion>
<Accordion title="優先處理（service_tier）">
OpenAI 的 API 透過 `service_tier` 公開優先處理。在 OpenClaw 中為每個模型設定：
OpenAI 的 API 透過 `service_tier` 提供優先處理。在 OpenClaw 中可逐模型設定：
```json5
{
@ -762,7 +743,7 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
支援的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 只會轉送至原生 OpenAI 端點（`api.openai.com`）和原生 Codex 端點（`chatgpt.com/backend-api`）。如果你透過代理路由任一供應器，OpenClaw 會讓 `service_tier` 保持不變。
`serviceTier` 只會轉送至原生 OpenAI 端點（`api.openai.com`）與原生 Codex 端點（`chatgpt.com/backend-api`）。如果你透過代理路由任一提供者，OpenClaw 會讓 `service_tier` 保持原樣。
</Warning>
</Accordion>
@ -772,9 +753,9 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
- 強制 `store: true`（除非模型相容性設定 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 預設 `compact_threshold`：`contextWindow` 的 70%（或在不可用時為 `80000`）
- 預設 `compact_threshold`：`contextWindow` 的 70%（無法取得時為 `80000`）
這適用於內建 Pi harness 路徑，以及嵌入式執行使用的 OpenAI 供應器 hook。原生 Codex 應用伺服器 harness 會透過 Codex 管理自己的上下文，並使用 `agents.defaults.agentRuntime.id` 另行設定。
這適用於內建 Pi harness 路徑，以及嵌入式執行使用的 OpenAI 提供者 hook。原生 Codex app-server harness 會透過 Codex 管理自己的上下文，並以 `agents.defaults.agentRuntime.id` 另外設定。
<Tabs>
<Tab title="明確啟用">
@ -794,7 +775,7 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
}
```
</Tab>
<Tab title="自訂臨界值">
<Tab title="自訂閾值">
```json5
{
agents: {
@ -830,13 +811,13 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
</Tabs>
<Note>
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍會強制使用 `store: true`，除非 compat 設定 `supportsStore: false`。
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍會強制使用 `store: true`，除非相容層設定了 `supportsStore: false`。
</Note>
</Accordion>
<Accordion title="嚴格代理式 GPT 模式">
對於在 `openai/*` 上執行的 GPT-5 系列，OpenClaw 可以使用更嚴格的嵌入式執行合約：
對於在 `openai/*` 上執行的 GPT-5 系列，OpenClaw 可以使用更嚴格的嵌入式執行契約：
```json5
{
@ -848,34 +829,34 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
}
```
使用 `strict-agentic` 時，OpenClaw：
- 當有可用的工具動作時，不再將只有計畫的回合視為成功進展
- 使用立即行動導引重試該回合
- 針對實質工作自動啟用 `update_plan`
- 如果模型持續規劃而不行動，會顯示明確的受阻狀態
使用 `strict-agentic` 時，OpenClaw 會：
- 當可使用工具動作時，不再將只有計畫的回合視為成功進展
- 使用立即執行的引導重試該回合
- 對實質工作自動啟用 `update_plan`
- 如果模型持續只規劃而不執行，會顯示明確的受阻狀態
<Note>
僅限 OpenAI 和 Codex GPT-5 系列執行。其他供應商和較舊的模型系列會保留預設行為。
僅限 OpenAI 和 Codex GPT-5 系列執行。其他提供者和較舊的模型系列會保留預設行為。
</Note>
</Accordion>
<Accordion title="原生與 OpenAI 相容路由">
OpenClaw 會以不同於通用 OpenAI 相容 `/v1` 代理的方式處理直接的 OpenAI、Codex 和 Azure OpenAI 端點：
<Accordion title="原生路由與 OpenAI 相容路由">
OpenClaw 會以不同方式處理直接的 OpenAI、Codex 和 Azure OpenAI 端點，以及一般的 OpenAI 相容 `/v1` 代理：
**原生路由**（`openai/*`、Azure OpenAI）：
- 只針對支援 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 對於拒絕 `reasoning.effort: "none"` 的模型或代理，省略停用的推理
- 僅對支援 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 對於會拒絕 `reasoning.effort: "none"` 的模型或代理，省略已停用的推理設定
- 預設將工具結構描述設為嚴格模式
- 只在已驗證的原生主機上附加隱藏的歸因標頭
- 保留僅適用於 OpenAI 的請求塑形（`service_tier`、`store`、reasoning-compat、提示快取提示）
- 保留僅限 OpenAI 的請求塑形（`service_tier`、`store`、推理相容、提示快取提示）
**代理/相容路由：**
- 使用較寬鬆的相容行為
- 從非原生 `openai-completions` payload 中移除 Completions `store`
- 接受進階 `params.extra_body`/`params.extraBody` 直通 JSON，供 OpenAI 相容的 Completions 代理使用
- 接受 `params.chat_template_kwargs`，供 vLLM 等 OpenAI 相容的 Completions 代理使用
- 不強制使用嚴格工具結構描述或僅限原生的標頭
- 從非原生 `openai-completions` 酬載中移除 Completions `store`
- 接受進階的 `params.extra_body`/`params.extraBody` 透傳 JSON，用於 OpenAI 相容的 Completions 代理
- 接受 `params.chat_template_kwargs`，用於 vLLM 等 OpenAI 相容的 Completions 代理
- 不會強制使用嚴格工具結構描述或僅限原生的標頭
Azure OpenAI 使用原生傳輸和相容行為，但不會收到隱藏的歸因標頭。
@ -886,13 +867,13 @@ OpenClaw 的隱藏歸因標頭 — 請參閱 [進階設定](#advanced-configurat
<CardGroup cols={2}>
<Card title="模型選擇" href="/zh-TW/concepts/model-providers" icon="layers">
選擇供應商、模型參照和容錯移轉行為。
選擇提供者、模型參照和容錯移轉行為。
</Card>
<Card title="圖片生成" href="/zh-TW/tools/image-generation" icon="image">
共用圖片工具參數和供應商選擇。
共用圖片工具參數和提供者選擇。
</Card>
<Card title="影片生成" href="/zh-TW/tools/video-generation" icon="video">
共用影片工具參數和供應商選擇。
共用影片工具參數和提供者選擇。
</Card>
<Card title="OAuth 和驗證" href="/zh-TW/gateway/authentication" icon="key">
驗證詳細資訊和憑證重用規則。

314
docs/zh-TW/reference/memory-config.md
View File

@ -1,52 +1,52 @@
---
read_when:
- 您想設定記憶搜尋提供者或嵌入模型
- 您想設定 QMD 後端
- 你想要微調混合搜尋、MMR 或時間衰減
- 您想要啟用多模態記憶索引
- 您想要設定記憶搜尋提供者或嵌入模型
- 您想要設定 QMD 後端
- 您想調整混合搜尋、MMR 或時間衰減
- 你想啟用多模態記憶索引
sidebarTitle: Memory config
summary: 記憶搜尋、嵌入提供者、QMD、混合搜尋和多模態索引的所有設定選項
summary: 記憶搜尋、嵌入提供者、QMD、混合搜尋與多模態索引的所有設定選項
title: 記憶設定參考
x-i18n:
generated_at: "2026-04-30T03:37:01Z"
generated_at: "2026-04-30T16:29:50Z"
model: gpt-5.5
provider: openai
source_hash: fbb21d407f7ec9ef76e68c268138892b12568137735b723579703e535d34b195
source_hash: 58b75751a19afb883fd7646cf5f71859f95bac468b2bfd8cc79db12ae892f70f
source_path: reference/memory-config.md
workflow: 16
---
此頁列出 OpenClaw 記憶搜尋的所有設定選項。如需概念概覽，請參閱：
此頁列出 OpenClaw 記憶體搜尋的每個設定旋鈕。如需概念概覽，請參閱：
<CardGroup cols={2}>
<Card title="記憶概覽" href="/zh-TW/concepts/memory">
記憶的運作方式。
<Card title="Memory overview" href="/zh-TW/concepts/memory">
記憶體如何運作。
</Card>
<Card title="內建引擎" href="/zh-TW/concepts/memory-builtin">
<Card title="Builtin engine" href="/zh-TW/concepts/memory-builtin">
預設 SQLite 後端。
</Card>
<Card title="QMD 引擎" href="/zh-TW/concepts/memory-qmd">
<Card title="QMD engine" href="/zh-TW/concepts/memory-qmd">
本地優先的 sidecar。
</Card>
<Card title="記憶搜尋" href="/zh-TW/concepts/memory-search">
<Card title="Memory search" href="/zh-TW/concepts/memory-search">
搜尋管線與調校。
</Card>
<Card title="Active memory" href="/zh-TW/concepts/active-memory">
互動式工作階段的記憶子代理。
互動式工作階段的記憶體子代理程式。
</Card>
</CardGroup>
除非另有註明，所有記憶搜尋設定都位於 `openclaw.json` 的 `agents.defaults.memorySearch` 之下。
除非另有說明，所有記憶體搜尋設定都位於 `openclaw.json` 的 `agents.defaults.memorySearch` 底下。
<Note>
如果你正在尋找 **active memory** 功能切換與子代理設定，它位於 `plugins.entries.active-memory` 之下，而不是 `memorySearch`。
如果你要找的是 **Active Memory** 功能切換與子代理程式設定，它位於 `plugins.entries.active-memory` 底下，而不是 `memorySearch`。
Active memory 使用雙閘門模型：
Active Memory 使用雙閘門模型：
1. Plugin 必須啟用並鎖定目前的代理 ID
1. Plugin 必須已啟用，且目標為目前的代理程式 ID
2. 請求必須是符合資格的互動式持久聊天工作階段
請參閱 [Active Memory](/zh-TW/concepts/active-memory)，了解啟用模型、Plugin 擁有的設定、轉錄保存，以及安全推出模式。
請參閱 [Active Memory](/zh-TW/concepts/active-memory)，了解啟用模型、Plugin 擁有的設定、逐字稿持久化，以及安全推出模式。
</Note>
---
@ -55,39 +55,39 @@ Active memory 使用雙閘門模型：
| 鍵 | 類型 | 預設值 | 說明 |
| ---------- | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | 自動偵測 | 嵌入介面卡 ID，例如 `bedrock`、`deepinfra`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai` 或 `voyage`；也可以是已設定的 `models.providers.<id>`，其 `api` 指向其中一個介面卡 |
| `provider` | `string` | 自動偵測 | 嵌入轉接器 ID，例如 `bedrock`、`deepinfra`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai` 或 `voyage`；也可以是已設定的 `models.providers.<id>`，其 `api` 指向其中一個轉接器 |
| `model` | `string` | 提供者預設值 | 嵌入模型名稱 |
| `fallback` | `string` | `"none"` | 主要項目失敗時使用的備援介面卡 ID |
| `enabled` | `boolean` | `true` | 啟用或停用記憶搜尋 |
| `fallback` | `string` | `"none"` | 主要提供者失敗時使用的備援轉接器 ID |
| `enabled` | `boolean` | `true` | 啟用或停用記憶體搜尋 |
### 自動偵測順序
當未設定 `provider` 時，OpenClaw 會選擇第一個可用項目：
未設定 `provider` 時，OpenClaw 會選擇第一個可用項目：
<Steps>
<Step title="local">
如果已設定 `memorySearch.local.modelPath` 且檔案存在，則選取。
如果已設定 `memorySearch.local.modelPath` 且檔案存在，則會選取。
</Step>
<Step title="github-copilot">
如果可解析 GitHub Copilot 權杖（環境變數或驗證設定檔），則選取。
如果可解析 GitHub Copilot 權杖（環境變數或驗證設定檔），則會選取。
</Step>
<Step title="openai">
如果可解析 OpenAI 金鑰，則選取。
如果可解析 OpenAI 金鑰，則會選取。
</Step>
<Step title="gemini">
如果可解析 Gemini 金鑰，則選取。
如果可解析 Gemini 金鑰，則會選取。
</Step>
<Step title="voyage">
如果可解析 Voyage 金鑰，則選取。
如果可解析 Voyage 金鑰，則會選取。
</Step>
<Step title="mistral">
如果可解析 Mistral 金鑰，則選取。
如果可解析 Mistral 金鑰，則會選取。
</Step>
<Step title="deepinfra">
如果可解析 DeepInfra 金鑰，則選取。
如果可解析 DeepInfra 金鑰，則會選取。
</Step>
<Step title="bedrock">
如果 AWS SDK 憑證鏈可解析（執行個體角色、存取金鑰、設定檔、SSO、Web 身分或共用設定），則選取。
如果 AWS SDK 憑證鏈可解析（執行個體角色、存取金鑰、設定檔、SSO、Web 身分或共用設定），則會選取。
</Step>
</Steps>
@ -95,7 +95,7 @@ Active memory 使用雙閘門模型：
### 自訂提供者 ID
`memorySearch.provider` 可以指向自訂的 `models.providers.<id>` 項目。OpenClaw 會解析該提供者的 `api` 擁有者作為嵌入介面卡，同時保留自訂提供者 ID，用於端點、驗證與模型前綴處理。這可讓多 GPU 或多主機設定將記憶嵌入專用於特定本地端點：
`memorySearch.provider` 可以指向自訂的 `models.providers.<id>` 項目。OpenClaw 會解析該提供者的 `api` 擁有者作為嵌入轉接器，同時保留自訂提供者 ID 以處理端點、驗證與模型前綴。這可讓多 GPU 或多主機設定將記憶體嵌入專門指派給特定本機端點：
```json5
{
@ -131,7 +131,7 @@ Active memory 使用雙閘門模型：
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | 透過裝置登入的驗證設定檔 |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY`（佔位符） | -- |
| Ollama | `OLLAMA_API_KEY`（預留位置） | -- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
@ -143,7 +143,7 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
## 遠端端點設定
用於自訂 OpenAI 相容端點或覆寫提供者預設值：
針對自訂 OpenAI 相容端點或覆寫提供者預設值：
<ParamField path="remote.baseUrl" type="string">
自訂 API 基底 URL。
@ -174,28 +174,28 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
---
## 提供者特定設定
## 提供者專屬設定
<AccordionGroup>
<Accordion title="Gemini">
| 鍵 | 類型 | 預設值 | 說明 |
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
| `model` | `string` | `gemini-embedding-001` | 也支援 `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | 用於 Embedding 2：768、1536 或 3072 |
| `outputDimensionality` | `number` | `3072` | 針對 Embedding 2：768、1536 或 3072 |
<Warning>
變更模型或 `outputDimensionality` 會觸發自動完整重新索引。
</Warning>
</Accordion>
<Accordion title="OpenAI 相容輸入類型">
OpenAI 相容嵌入端點可選擇使用提供者特定的 `input_type` 請求欄位。這對於需要為查詢與文件嵌入使用不同標籤的非對稱嵌入模型很有用。
<Accordion title="OpenAI-compatible input types">
OpenAI 相容的嵌入端點可以選擇加入提供者專屬的 `input_type` 請求欄位。這對需要針對查詢與文件嵌入使用不同標籤的非對稱嵌入模型很有用。
| 鍵 | 類型 | 預設值 | 說明 |
| ------------------- | -------- | ------- | ------------------------------------------------------- |
| `inputType` | `string` | 未設定 | 查詢與文件嵌入共用的 `input_type` |
| `queryInputType` | `string` | 未設定 | 查詢時的 `input_type`；覆寫 `inputType` |
| `documentInputType` | `string` | 未設定 | 索引/文件 `input_type`；覆寫 `inputType` |
| `documentInputType` | `string` | 未設定 | 索引/文件的 `input_type`；覆寫 `inputType` |
```json5
{
@ -216,11 +216,11 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
}
```
變更這些值會影響提供者批次索引的嵌入快取識別；當上游模型對標籤採取不同處理時，應接著重新索引記憶。
變更這些值會影響提供者批次索引的嵌入快取身分；如果上游模型會以不同方式處理標籤，之後應重新索引記憶體。
</Accordion>
<Accordion title="Bedrock">
Bedrock 使用 AWS SDK 預設憑證鏈，不需要 API 金鑰。如果 OpenClaw 在 EC2 上執行，且具備啟用 Bedrock 的執行個體角色，只需設定提供者與模型：
Bedrock 使用 AWS SDK 預設憑證鏈，不需要 API 金鑰。如果 OpenClaw 在具有 Bedrock 啟用執行個體角色的 EC2 上執行，只要設定提供者與模型即可：
```json5
{
@ -238,26 +238,26 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
| 鍵 | 類型 | 預設值 | 說明 |
| ---------------------- | -------- | ------------------------------ | ------------------------------- |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任何 Bedrock 嵌入模型 ID |
| `outputDimensionality` | `number` | 模型預設值 | 用於 Titan V2：256、512 或 1024 |
| `outputDimensionality` | `number` | 模型預設值 | 針對 Titan V2：256、512 或 1024 |
**支援的模型**（包含系列偵測與維度預設值）：
| 模型 ID | 提供者 | 預設維度 | 可設定維度 |
| ------------------------------------------ | ---------- | ------------ | -------------------- |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256、512、1024 |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256、384、1024、3072 |
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
帶有吞吐量後綴的變體（例如 `amazon.titan-embed-text-v1:2:8k`）會繼承基礎模型的設定。
具有輸送量後綴的變體（例如 `amazon.titan-embed-text-v1:2:8k`）會繼承基礎模型的設定。
**驗證：** Bedrock 驗證使用標準 AWS SDK 憑證解析順序：
**驗證：**Bedrock 驗證使用標準 AWS SDK 憑證解析順序：
1. 環境變數（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`）
2. SSO 權杖快取
@ -267,7 +267,7 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
區域會從 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock` 提供者 `baseUrl` 解析，或預設為 `us-east-1`。
**IAM 權限：** IAM 角色或使用者需要：
**IAM 權限：**IAM 角色或使用者需要：
```json
{
@ -277,30 +277,30 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
}
```
若採用最低權限，請將 `InvokeModel` 範圍限制於特定模型：
若要使用最低權限，請將 `InvokeModel` 範圍限制為特定模型：
```
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
```
</Accordion>
<Accordion title="本機 (GGUF + node-llama-cpp)">
| 鍵 | 類型 | 預設值 | 說明 |
| --------------------- | ------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local.modelPath` | `string` | 自動下載 | GGUF 模型檔案的路徑 |
| `local.modelCacheDir` | `string` | node-llama-cpp 預設值 | 已下載模型的快取目錄 |
| `local.contextSize` | `number \| "auto"` | `4096` | 嵌入內容的上下文視窗大小。4096 可涵蓋一般區塊（128–512 個 token），同時限制非權重 VRAM。在資源受限的主機上可降低至 1024–2048。`"auto"` 會使用模型訓練時的最大值，不建議用於 8B+ 模型（Qwen3-Embedding-8B：40 960 個 token → 約 32 GB VRAM，相較於 4096 時約 8.8 GB）。 |
<Accordion title="本機（GGUF + node-llama-cpp）">
| 鍵 | 類型 | 預設值 | 說明 |
| --------------------- | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `local.modelPath` | `string` | 自動下載 | GGUF 模型檔案的路徑 |
| `local.modelCacheDir` | `string` | node-llama-cpp 預設值 | 下載模型的快取目錄 |
| `local.contextSize` | `number \| "auto"` | `4096` | 嵌入內容的脈絡視窗大小。4096 可涵蓋一般區塊（128–512 個權杖），同時限制非權重 VRAM。受限主機上可降低到 1024–2048。`"auto"` 會使用模型訓練時的最大值，不建議用於 8B+ 模型（Qwen3-Embedding-8B：40,960 個權杖 → 約 32 GB VRAM，相較於 4096 時約 8.8 GB）。 |
預設模型：`embeddinggemma-300m-qat-Q8_0.gguf`（約 0.6 GB，自動下載）。需要原生建置：先執行 `pnpm approve-builds`，再執行 `pnpm rebuild node-llama-cpp`。
預設模型：`embeddinggemma-300m-qat-Q8_0.gguf`（約 0.6 GB，自動下載）。封裝安裝在設定 `provider: "local"` 時，會透過受管理的 Plugin 執行階段相依套件修復原生 `node-llama-cpp` 執行階段。原始碼簽出仍需要原生建置核准：先執行 `pnpm approve-builds`，再執行 `pnpm rebuild node-llama-cpp`。
使用獨立 CLI 來驗證 Gateway 使用的同一個提供者路徑：
使用獨立 CLI 驗證 Gateway 使用的同一個提供者路徑：
```bash
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
```
如果 `provider` 是 `auto`，只有在 `local.modelPath` 指向現有本機檔案時，才會選取 `local`。`hf:` 與 HTTP(S) 模型參照仍可透過 `provider: "local"` 明確使用，但在模型可於磁碟上使用之前，它們不會讓 `auto` 選取本機。
如果 `provider` 是 `auto`，只有在 `local.modelPath` 指向現有本機檔案時，才會選取 `local`。`hf:` 和 HTTP(S) 模型參照仍可搭配 `provider: "local"` 明確使用，但在模型可於磁碟上取得之前，它們不會讓 `auto` 選取本機。
</Accordion>
</AccordionGroup>
@ -310,36 +310,36 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
<ParamField path="sync.embeddingBatchTimeoutSeconds" type="number">
覆寫記憶索引期間內嵌嵌入批次的逾時時間。
未設定時會使用提供者預設值：本機/自行託管提供者（例如 `local`、`ollama` 和 `lmstudio`）為 600 秒，託管提供者為 120 秒。當本機受 CPU 限制的嵌入批次運作正常但速度較慢時，請增加此值。
未設定時會使用提供者預設值：本機/自託管提供者（例如 `local`、`ollama` 和 `lmstudio`）為 600 秒，託管提供者為 120 秒。當本機 CPU 受限的嵌入批次正常但速度較慢時，請增加此值。
</ParamField>
---
## 混合搜尋設定
全部位於 `memorySearch.query.hybrid` 下：
全部位於 `memorySearch.query.hybrid` 之下：
| 鍵 | 類型 | 預設值 | 說明 |
| --------------------- | --------- | ------- | ---------------------------------- |
| `enabled` | `boolean` | `true` | 啟用混合 BM25 + 向量搜尋 |
| `vectorWeight` | `number` | `0.7` | 向量分數的權重（0-1） |
| `textWeight` | `number` | `0.3` | BM25 分數的權重（0-1） |
| `candidateMultiplier` | `number` | `4` | 候選池大小倍數 |
| 鍵 | 類型 | 預設值 | 說明 |
| --------------------- | --------- | ------ | -------------------------- |
| `enabled` | `boolean` | `true` | 啟用混合 BM25 + 向量搜尋 |
| `vectorWeight` | `number` | `0.7` | 向量分數權重（0-1） |
| `textWeight` | `number` | `0.3` | BM25 分數權重（0-1） |
| `candidateMultiplier` | `number` | `4` | 候選池大小倍率 |
<Tabs>
<Tab title="MMR（多樣性）">
| 鍵 | 類型 | 預設值 | 說明 |
| ------------- | --------- | ------- | ------------------------------------ |
| 鍵 | 類型 | 預設值 | 說明 |
| ------------- | --------- | ------- | -------------------------------- |
| `mmr.enabled` | `boolean` | `false` | 啟用 MMR 重新排序 |
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多樣性，1 = 最大相關性 |
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多樣性，1 = 最大相關性 |
</Tab>
<Tab title="時間衰減（新近度）">
| 鍵 | 類型 | 預設值 | 說明 |
| ---------------------------- | --------- | ------- | ------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | 啟用新近度加權 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 分數每 N 天減半 |
<Tab title="時間衰減（近期性）">
| 鍵 | 類型 | 預設值 | 說明 |
| ---------------------------- | --------- | ------ | ------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | 啟用近期性提升 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 每 N 天分數減半 |
長青檔案（`MEMORY.md`、`memory/` 中未標日期的檔案）永遠不會衰減。
常青檔案（`MEMORY.md`、`memory/` 中未標日期的檔案）永不衰減。
</Tab>
</Tabs>
@ -369,9 +369,9 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
## 其他記憶路徑
| 鍵 | 類型 | 說明 |
| ------------ | ---------- | ---------------------------------------- |
| `extraPaths` | `string[]` | 要建立索引的其他目錄或檔案 |
| 鍵 | 類型 | 說明 |
| ------------ | ---------- | ---------------------------- |
| `extraPaths` | `string[]` | 要建立索引的其他目錄或檔案 |
```json5
{
@ -385,144 +385,144 @@ Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
}
```
路徑可以是絕對路徑，也可以是相對於工作區的路徑。系統會遞迴掃描目錄中的 `.md` 檔案。符號連結處理取決於作用中的後端：內建引擎會忽略符號連結，而 QMD 則遵循底層 QMD 掃描器行為。
路徑可以是絕對路徑或相對於工作區的路徑。目錄會以遞迴方式掃描 `.md` 檔案。符號連結處理方式取決於使用中的後端：內建引擎會忽略符號連結，而 QMD 會遵循底層 QMD 掃描器行為。
對於以代理程式為範圍的跨代理程式記錄搜尋，請使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。這些額外集合遵循相同的 `{ path, name, pattern? }` 形狀，但會依代理程式合併，並且在路徑指向目前工作區之外時，可以保留明確的共用名稱。如果相同的已解析路徑同時出現在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 會保留第一個項目並略過重複項目。
若要進行代理範圍的跨代理逐字稿搜尋，請使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。這些額外集合遵循相同的 `{ path, name, pattern? }` 形狀，但會依每個代理合併，且當路徑指向目前工作區之外時，可以保留明確的共用名稱。如果相同的解析後路徑同時出現在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 會保留第一個項目並略過重複項目。
---
## 多模態記憶（Gemini）
使用 Gemini Embedding 2 將圖片與音訊連同 Markdown 一起建立索引：
使用 Gemini Embedding 2 將圖片和音訊與 Markdown 一起建立索引：
| 鍵 | 類型 | 預設值 | 說明 |
| 鍵 | 類型 | 預設值 | 說明 |
| ------------------------- | ---------- | ---------- | -------------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | 啟用多模態索引 |
| `multimodal.enabled` | `boolean` | `false` | 啟用多模態索引 |
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引的最大檔案大小 |
| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引的最大檔案大小 |
<Note>
僅適用於 `extraPaths` 中的檔案。預設記憶根目錄仍然僅限 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必須是 `"none"`。
僅適用於 `extraPaths` 中的檔案。預設記憶根目錄仍只限 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必須為 `"none"`。
</Note>
支援的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`（影像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音訊）。
支援格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`（圖片）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音訊）。
---
## 嵌入快取
| 鍵 | 類型 | 預設值 | 描述 |
| 鍵 | 類型 | 預設值 | 說明 |
| ------------------ | --------- | ------- | ---------------------------- |
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中快取區塊嵌入 |
| `cache.maxEntries` | `number` | `50000` | 最大快取嵌入數 |
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中快取區塊嵌入 |
| `cache.maxEntries` | `number` | `50000` | 最大快取嵌入數量 |
避免在重新索引或逐字稿更新期間重新嵌入未變更的文字。
防止在重新建立索引或逐字稿更新期間，對未變更的文字重新建立嵌入。
---
## 批次索引
| 鍵 | 類型 | 預設值 | 描述 |
| ----------------------------- | --------- | ------ | ------------------ |
| `remote.nonBatchConcurrency` | `number` | `4` | 平行內嵌嵌入 |
| `remote.batch.enabled` | `boolean` | `false` | 啟用批次嵌入 API |
| `remote.batch.concurrency` | `number` | `2` | 平行批次作業 |
| `remote.batch.wait` | `boolean` | `true` | 等待批次完成 |
| `remote.batch.pollIntervalMs` | `number` | -- | 輪詢間隔 |
| `remote.batch.timeoutMinutes` | `number` | -- | 批次逾時 |
| 鍵 | 類型 | 預設值 | 說明 |
| ----------------------------- | --------- | ------- | ---------------- |
| `remote.nonBatchConcurrency` | `number` | `4` | 平行內嵌嵌入 |
| `remote.batch.enabled` | `boolean` | `false` | 啟用批次嵌入 API |
| `remote.batch.concurrency` | `number` | `2` | 平行批次工作 |
| `remote.batch.wait` | `boolean` | `true` | 等待批次完成 |
| `remote.batch.pollIntervalMs` | `number` | -- | 輪詢間隔 |
| `remote.batch.timeoutMinutes` | `number` | -- | 批次逾時 |
適用於 `openai`、`gemini` 和 `voyage`。對於大型回填，OpenAI 批次通常最快且成本最低。
可用於 `openai`、`gemini` 和 `voyage`。OpenAI 批次通常是大型回填最快且最便宜的選項。
`remote.nonBatchConcurrency` 控制本機/自託管提供者使用的內嵌嵌入呼叫，以及提供者批次 API 未啟用時託管提供者使用的內嵌嵌入呼叫。Ollama 的非批次索引預設為 `1`，以避免讓較小的本機主機負載過重；在較大的機器上可設定較高的值。
`remote.nonBatchConcurrency` 控制本機/自託管提供者，以及未啟用提供者批次 API 時託管提供者所使用的內嵌嵌入呼叫。Ollama 對非批次索引預設為 `1`，以避免壓垮較小的本機主機；在較大型機器上可設定更高的值。
這與 `sync.embeddingBatchTimeoutSeconds` 分開，後者控制內嵌嵌入呼叫的逾時。
這與 `sync.embeddingBatchTimeoutSeconds` 分開，後者控制內嵌嵌入呼叫的逾時時間。
---
## 工作階段記憶搜尋（實驗性）
索引工作階段逐字稿，並透過 `memory_search` 顯示：
建立工作階段逐字稿索引，並透過 `memory_search` 顯示：
| 鍵 | 類型 | 預設值 | 描述 |
| ----------------------------- | ---------- | ------------ | ---------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | 啟用工作階段索引 |
| 鍵 | 類型 | 預設值 | 說明 |
| ----------------------------- | ---------- | ------------ | ------------------------------ |
| `experimental.sessionMemory` | `boolean` | `false` | 啟用工作階段索引 |
| `sources` | `string[]` | `["memory"]` | 加入 `"sessions"` 以包含逐字稿 |
| `sync.sessions.deltaBytes` | `number` | `100000` | 重新索引的位元組閾值 |
| `sync.sessions.deltaMessages` | `number` | `50` | 重新索引的訊息閾值 |
| `sync.sessions.deltaBytes` | `number` | `100000` | 重新索引的位元組閾值 |
| `sync.sessions.deltaMessages` | `number` | `50` | 重新索引的訊息閾值 |
<Warning>
工作階段索引為選用，且會非同步執行。結果可能稍微過時。工作階段記錄位於磁碟上，因此請將檔案系統存取視為信任邊界。
工作階段索引為選擇加入，並以非同步方式執行。結果可能稍微過時。工作階段記錄位於磁碟上，因此請將檔案系統存取視為信任邊界。
</Warning>
---
## SQLite 向量加速（sqlite-vec）
| 鍵 | 類型 | 預設值 | 描述 |
| 鍵 | 類型 | 預設值 | 說明 |
| ---------------------------- | --------- | ------ | ---------------------------- |
| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 進行向量查詢 |
| `store.vector.extensionPath` | `string` | 隨附 | 覆寫 sqlite-vec 路徑 |
當 sqlite-vec 無法使用時，OpenClaw 會自動退回使用程序內餘弦相似度。
當 sqlite-vec 無法使用時，OpenClaw 會自動退回到程序內餘弦相似度。
---
## 索引儲存
| 鍵 | 類型 | 預設值 | 描述 |
| --------------------- | -------- | ------------------------------------- | -------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支援 `{agentId}` 權杖） |
| 鍵 | 類型 | 預設值 | 說明 |
| --------------------- | -------- | ------------------------------------- | ------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支援 `{agentId}` 權杖） |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer（`unicode61` 或 `trigram`） |
---
## QMD 後端設定
設定 `memory.backend = "qmd"` 以啟用。所有 QMD 設定都位於 `memory.qmd` 下：
設定 `memory.backend = "qmd"` 以啟用。所有 QMD 設定位於 `memory.qmd` 之下：
| 鍵 | 類型 | 預設值 | 描述 |
| ------------------------ | --------- | -------- | ---------------------------------------------------------------------------------- |
| `command` | `string` | `qmd` | QMD 可執行檔路徑；當服務 `PATH` 與你的 shell 不同時，請設定絕對路徑 |
| `searchMode` | `string` | `search` | 搜尋命令：`search`、`vsearch`、`query` |
| `includeDefaultMemory` | `boolean` | `true` | 自動索引 `MEMORY.md` + `memory/**/*.md` |
| 鍵 | 類型 | 預設值 | 說明 |
| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- |
| `command` | `string` | `qmd` | QMD 可執行檔路徑；當服務的 `PATH` 與你的 shell 不同時，請設定絕對路徑 |
| `searchMode` | `string` | `search` | 搜尋命令：`search`、`vsearch`、`query` |
| `includeDefaultMemory` | `boolean` | `true` | 自動索引 `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | 額外路徑：`{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | 索引工作階段逐字稿 |
| `sessions.retentionDays` | `number` | -- | 逐字稿保留 |
| `sessions.exportDir` | `string` | -- | 匯出目錄 |
| `sessions.enabled` | `boolean` | `false` | 索引工作階段逐字稿 |
| `sessions.retentionDays` | `number` | -- | 逐字稿保留期間 |
| `sessions.exportDir` | `string` | -- | 匯出目錄 |
`searchMode: "search"` 僅使用詞彙/BM25。OpenClaw 不會針對該模式執行語意向量就緒探測或 QMD 嵌入維護，包括在 `memory status --deep` 期間；`vsearch` 和 `query` 仍然需要 QMD 向量就緒狀態與嵌入。
`searchMode: "search"` 僅使用詞彙/BM25。OpenClaw 不會為該模式執行語意向量就緒探測或 QMD 嵌入維護，包括在 `memory status --deep` 期間；`vsearch` 和 `query` 仍然需要 QMD 向量就緒狀態與嵌入。
OpenClaw 偏好目前的 QMD collection 與 MCP 查詢形狀，但會在需要時嘗試相容的 collection pattern 旗標和較舊的 MCP tool 名稱，以維持較舊 QMD 版本可用。當 QMD 宣告支援多個 collection filters 時，同來源 collections 會以單一 QMD process 搜尋；較舊的 QMD build 則保留逐 collection 的相容路徑。同來源表示 durable memory collections 會分在同一組，而 session transcript collections 仍會保留為獨立群組，因此 source diversification 仍同時具備兩種輸入。
OpenClaw 偏好目前的 QMD 集合與 MCP 查詢形狀，但會在需要時嘗試相容的集合模式旗標與較舊的 MCP 工具名稱，以維持較舊 QMD 版本可用。當 QMD 宣告支援多個集合篩選器時，會使用一個 QMD 程序搜尋同來源集合；較舊的 QMD 建置會保留逐集合相容路徑。同來源表示持久記憶集合會分組在一起，而工作階段逐字稿集合會保留為獨立群組，因此來源多樣化仍同時具備兩種輸入。
<Note>
QMD model overrides 保留在 QMD 端，而不是 OpenClaw config。如果你需要全域覆寫 QMD 的 models，請在 Gateway runtime environment 中設定環境變數，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
QMD 模型覆寫保留在 QMD 端，而不是 OpenClaw 設定。如果你需要全域覆寫 QMD 的模型，請在 Gateway 執行階段環境中設定環境變數，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
</Note>
<AccordionGroup>
<Accordion title="更新排程">
| Key | Type | Default | Description |
| 鍵 | 類型 | 預設值 | 說明 |
| ------------------------- | --------- | ------- | ------------------------------------- |
| `update.interval` | `string` | `5m` | 重新整理間隔 |
| `update.debounceMs` | `number` | `15000` | 對檔案變更進行 debounce |
| `update.onBoot` | `boolean` | `true` | 在 long-lived QMD manager 開啟時重新整理；也會管控選擇啟用的 startup refresh |
| `update.startup` | `string` | `off` | 選用的 gateway-start refresh：`off`、`idle` 或 `immediate` |
| `update.startupDelayMs` | `number` | `120000` | 執行 `startup: "idle"` refresh 前的延遲 |
| `update.waitForBootSync` | `boolean` | `false` | 阻擋 manager 開啟，直到其初始重新整理完成 |
| `update.embedInterval` | `string` | -- | 獨立的 embed cadence |
| `update.commandTimeoutMs` | `number` | -- | QMD commands 的逾時 |
| `update.updateTimeoutMs` | `number` | -- | QMD update operations 的逾時 |
| `update.embedTimeoutMs` | `number` | -- | QMD embed operations 的逾時 |
| `update.debounceMs` | `number` | `15000` | 檔案變更防彈跳 |
| `update.onBoot` | `boolean` | `true` | 當長駐 QMD 管理器開啟時重新整理；也會控管選擇啟用的啟動重新整理 |
| `update.startup` | `string` | `off` | 選用的 Gateway 啟動重新整理：`off`、`idle` 或 `immediate` |
| `update.startupDelayMs` | `number` | `120000` | 執行 `startup: "idle"` 重新整理前的延遲 |
| `update.waitForBootSync` | `boolean` | `false` | 阻擋管理器開啟，直到其初始重新整理完成 |
| `update.embedInterval` | `string` | -- | 獨立的嵌入節奏 |
| `update.commandTimeoutMs` | `number` | -- | QMD 命令的逾時 |
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作的逾時 |
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作的逾時 |
</Accordion>
<Accordion title="限制">
| Key | Type | Default | Description |
| 鍵 | 類型 | 預設值 | 說明 |
| ------------------------- | -------- | ------- | -------------------------- |
| `limits.maxResults` | `number` | `6` | 搜尋結果上限 |
| `limits.maxSnippetChars` | `number` | -- | 限制 snippet 長度 |
| `limits.maxSnippetChars` | `number` | -- | 限制片段長度 |
| `limits.maxInjectedChars` | `number` | -- | 限制注入字元總數 |
| `limits.timeoutMs` | `number` | `4000` | 搜尋逾時 |
</Accordion>
<Accordion title="範圍">
控制哪些 sessions 可以接收 QMD 搜尋結果。Schema 與 [`session.sendPolicy`](/zh-TW/gateway/config-agents#session) 相同：
控制哪些工作階段可以接收 QMD 搜尋結果。結構描述與 [`session.sendPolicy`](/zh-TW/gateway/config-agents#session) 相同：
```json5
{
@ -537,24 +537,24 @@ QMD model overrides 保留在 QMD 端，而不是 OpenClaw config。如果你需
}
```
隨附的預設值允許 direct 和 channel sessions，同時仍拒絕 groups。
隨附的預設值允許直接與頻道工作階段，同時仍拒絕群組。
預設為僅 DM。`match.keyPrefix` 會比對標準化後的 session key；`match.rawKeyPrefix` 會比對包含 `agent:<id>:` 的 raw key。
預設值僅限 DM。`match.keyPrefix` 會比對正規化後的工作階段鍵；`match.rawKeyPrefix` 會比對包含 `agent:<id>:` 的原始鍵。
</Accordion>
<Accordion title="引用">
`memory.citations` 適用於所有 backends：
`memory.citations` 適用於所有後端：
| Value | Behavior |
| 值 | 行為 |
| ---------------- | --------------------------------------------------- |
| `auto`（預設） | 在 snippets 中包含 `Source: <path#line>` footer |
| `on` | 一律包含 footer |
| `off` | 省略 footer（path 仍會在內部傳給 agent） |
| `auto`（預設） | 在片段中包含 `Source: <path#line>` 頁尾 |
| `on` | 一律包含頁尾 |
| `off` | 省略頁尾（路徑仍會在內部傳遞給代理） |
</Accordion>
</AccordionGroup>
QMD boot refreshes 會在 Gateway startup 期間使用一次性的 subprocess 路徑。當 memory search 開啟以供互動使用時，long-lived QMD manager 仍負責一般的 file watcher 與 interval timers。
QMD 開機重新整理會在 Gateway 啟動期間使用一次性子程序路徑。當記憶搜尋開啟供互動使用時，長駐 QMD 管理器仍負責一般檔案監看器與間隔計時器。
### 完整 QMD 範例
@ -581,19 +581,19 @@ QMD boot refreshes 會在 Gateway startup 期間使用一次性的 subprocess
## Dreaming
Dreaming 設定於 `plugins.entries.memory-core.config.dreaming`，而不是 `agents.defaults.memorySearch`。
Dreaming 設定在 `plugins.entries.memory-core.config.dreaming` 下，而不是 `agents.defaults.memorySearch` 下。
Dreaming 會作為單一排程 sweep 執行，並將內部 light/deep/REM phases 作為實作細節使用。
Dreaming 會作為一個排程掃描執行，並將內部的 light/deep/REM 階段作為實作細節使用。
概念行為與 slash commands，請參閱 [Dreaming](/zh-TW/concepts/dreaming)。
關於概念行為與斜線命令，請參閱 [Dreaming](/zh-TW/concepts/dreaming)。
### 使用者設定
| Key | Type | Default | Description |
| 鍵 | 類型 | 預設值 | 說明 |
| ----------- | --------- | ------------- | ------------------------------------------------- |
| `enabled` | `boolean` | `false` | 完全啟用或停用 dreaming |
| `frequency` | `string` | `0 3 * * *` | 完整 dreaming sweep 的選用 cron cadence |
| `model` | `string` | default model | 選用的 Dream Diary subagent model override |
| `enabled` | `boolean` | `false` | 完全啟用或停用 Dreaming |
| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 掃描的選用 cron 節奏 |
| `model` | `string` | 預設模型 | 選用的 Dream Diary 子代理模型覆寫 |
### 範例
@ -621,14 +621,14 @@ Dreaming 會作為單一排程 sweep 執行，並將內部 light/deep/REM phases
<Note>
- Dreaming 會將機器狀態寫入 `memory/.dreams/`。
- Dreaming 會將人類可讀的敘事輸出寫入 `DREAMS.md`（或現有的 `dreams.md`）。
- `dreaming.model` 會使用現有的 plugin subagent trust gate；請先設定 `plugins.entries.memory-core.subagent.allowModelOverride: true` 再啟用。
- 當設定的 model 無法使用時，Dream Diary 會使用 session default model 重試一次。Trust 或 allowlist 失敗會被記錄，且不會靜默重試。
- light/deep/REM phase policy 與 thresholds 是內部行為，不是面向使用者的 config。
- Dreaming 會將人類可讀的敘事輸出寫入 `DREAMS.md`（或既有的 `dreams.md`）。
- `dreaming.model` 使用既有的 Plugin 子代理信任閘門；請先設定 `plugins.entries.memory-core.subagent.allowModelOverride: true` 再啟用它。
- 當設定的模型無法使用時，Dream Diary 會使用工作階段預設模型重試一次。信任或允許清單失敗會被記錄，且不會靜默重試。
- light/deep/REM 階段政策與閾值是內部行為，不是使用者可見的設定。
</Note>
## 相關內容
## 相關
- [設定參考](/zh-TW/gateway/configuration-reference)
- [記憶概觀](/zh-TW/concepts/memory)

339
docs/zh-TW/reference/session-management-compaction.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你需要偵錯工作階段 ID、逐字稿 JSONL 或 sessions.json 欄位
- 你正在變更自動 Compaction 行為，或新增「Compaction 前」維護作業
- 您想實作記憶清除或靜默系統回合
summary: 深入探討：工作階段儲存區 + 對話記錄、生命週期與 (自動)Compaction 內部機制
title: 工作階段管理深入解析
- 你需要偵錯工作階段 ID、transcript JSONL 或 sessions.json 欄位
- 你正在變更自動 Compaction 行為，或新增「預先 Compaction」清理作業
- 你想實作記憶清除或靜默系統回合
summary: 深入解析：工作階段儲存區 + 對話記錄、生命週期與（自動）Compaction 內部機制
title: 工作階段管理深入探討
x-i18n:
generated_at: "2026-04-30T03:37:34Z"
generated_at: "2026-04-30T16:30:12Z"
model: gpt-5.5
provider: openai
source_hash: 1e9785723ebf9b5411440a8f3b2885a50d659f669811ba749c431a2b3aeed700
source_hash: 5a6a7031cebd90d27784a32a0d0378ea9959249389d209f0745395f90b8a0df9
source_path: reference/session-management-compaction.md
workflow: 16
---
@ -18,85 +18,85 @@ OpenClaw 會在以下領域端對端管理工作階段：
- **工作階段路由**（傳入訊息如何對應到 `sessionKey`）
- **工作階段儲存區**（`sessions.json`）及其追蹤內容
- **逐字稿持久化**（`*.jsonl`）及其結構
- **逐字稿衛生處理**（執行前的提供者特定修正）
- **上下文限制**（上下文視窗與已追蹤權杖）
- **Compaction**（手動與自動 Compaction）以及在哪裡掛接 Compaction 前工作
- **靜默維護**（不應產生使用者可見輸出的記憶體寫入）
- **轉錄稿持久化**（`*.jsonl`）及其結構
- **轉錄稿衛生處理**（執行前的供應商特定修正）
- **上下文限制**（上下文視窗與追蹤的權杖）
- **Compaction**（手動與自動 Compaction）以及在哪裡掛接 Compaction 前作業
- **靜默內務處理**（不應產生使用者可見輸出的記憶體寫入）
如果你想先看較高階的概覽，請從這裡開始：
如果你想先閱讀較高層次的概觀，請從這裡開始：
- [工作階段管理](/zh-TW/concepts/session)
- [Compaction](/zh-TW/concepts/compaction)
- [記憶體概覽](/zh-TW/concepts/memory)
- [記憶體概觀](/zh-TW/concepts/memory)
- [記憶體搜尋](/zh-TW/concepts/memory-search)
- [工作階段修剪](/zh-TW/concepts/session-pruning)
- [逐字稿衛生處理](/zh-TW/reference/transcript-hygiene)
- [轉錄稿衛生處理](/zh-TW/reference/transcript-hygiene)
---
## 真實來源：Gateway
OpenClaw 的設計以單一擁有工作階段狀態的 **Gateway 程序**為核心。
OpenClaw 圍繞單一擁有工作階段狀態的 **Gateway 程序**設計。
- UI（macOS 應用程式、網頁控制 UI、TUI）應查詢 Gateway 以取得工作階段清單和權杖計數。
- 在遠端模式中，工作階段檔案位於遠端主機；「檢查本機 Mac 檔案」不會反映 Gateway 正在使用的內容。
- 使用者介面（macOS 應用程式、網頁控制介面、TUI）應向 Gateway 查詢工作階段清單與權杖計數。
- 在遠端模式中，工作階段檔案位於遠端主機；「檢查你的本機 Mac 檔案」不會反映 Gateway 實際使用的內容。
---
## 兩個持久化層
OpenClaw 會在兩個層中持久化工作階段：
OpenClaw 會在兩層中持久化工作階段：
1. **工作階段儲存區（`sessions.json`）**
- 鍵/值對應：`sessionKey -> SessionEntry`
- 鍵值對應：`sessionKey -> SessionEntry`
- 小型、可變、可安全編輯（或刪除項目）
- 追蹤工作階段中繼資料（目前工作階段 ID、最後活動、切換設定、權杖計數器等）
- 追蹤工作階段中繼資料（目前工作階段 ID、最後活動時間、切換項、權杖計數器等）
2. **逐字稿（`<sessionId>.jsonl`）**
- 具樹狀結構的僅附加逐字稿（項目有 `id` + `parentId`）
2. **轉錄稿（`<sessionId>.jsonl`）**
- 具有樹狀結構的僅附加轉錄稿（項目具有 `id` + `parentId`）
- 儲存實際對話 + 工具呼叫 + Compaction 摘要
- 用於為未來回合重建模型上下文
- 一旦作用中逐字稿超過檢查點大小上限，就會略過大型 Compaction 前除錯檢查點，避免再產生第二份巨大的 `.checkpoint.*.jsonl` 複本。
- 用於在未來回合重建模型上下文
- 一旦作用中轉錄稿超過檢查點大小上限，就會略過大型 Compaction 前除錯檢查點，避免再建立第二份巨大的 `.checkpoint.*.jsonl` 複本。
---
## 磁碟位置
每個代理在 Gateway 主機上：
在 Gateway 主機上，依代理程式區分：
- 儲存區：`~/.openclaw/agents/<agentId>/sessions/sessions.json`
- 逐字稿：`~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- 轉錄稿：`~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- Telegram 主題工作階段：`.../<sessionId>-topic-<threadId>.jsonl`
OpenClaw 會透過 `src/config/sessions.ts` 解析這些位置。
OpenClaw 透過 `src/config/sessions.ts` 解析這些路徑。
---
## 儲存區維護和磁碟控制
## 儲存區維護與磁碟控制
工作階段持久化針對 `sessions.json`、逐字稿成品和軌跡旁支檔案提供自動維護控制（`session.maintenance`）：
工作階段持久化具備自動維護控制（`session.maintenance`），適用於 `sessions.json`、轉錄稿成品與軌跡附屬檔：
- `mode`：`warn`（預設）或 `enforce`
- `pruneAfter`：過期項目年齡截止值（預設 `30d`）
- `maxEntries`：`sessions.json` 中的項目上限（預設 `500`）
- `resetArchiveRetention`：`*.reset.<timestamp>` 逐字稿封存的保留期（預設：與 `pruneAfter` 相同；`false` 會停用清理）
- `maxDiskBytes`：可選的工作階段目錄預算
- `highWaterBytes`：清理後的可選目標（預設為 `maxDiskBytes` 的 `80%`）
- `pruneAfter`：陳舊項目年齡截點（預設 `30d`）
- `maxEntries`：限制 `sessions.json` 中的項目數（預設 `500`）
- `resetArchiveRetention`：`*.reset.<timestamp>` 轉錄稿封存的保留時間（預設：與 `pruneAfter` 相同；`false` 會停用清理）
- `maxDiskBytes`：選用的工作階段目錄預算
- `highWaterBytes`：清理後的選用目標（預設為 `maxDiskBytes` 的 `80%`）
一般 Gateway 寫入會針對生產規模上限批次處理 `maxEntries` 清理，因此儲存區可能會短暫超過已設定的上限，直到下一次高水位清理將其重寫回上限內。`openclaw sessions cleanup --enforce` 仍會立即套用已設定的上限。
一般 Gateway 寫入會針對生產規模上限批次處理 `maxEntries` 清理，因此在下一次高水位清理將儲存區重新寫回上限之前，儲存區可能會短暫超過設定的上限。`openclaw sessions cleanup --enforce` 仍會立即套用已設定的上限。
OpenClaw 不再於 Gateway 寫入期間建立自動 `sessions.json.bak.*` 輪替備份。舊版 `session.maintenance.rotateBytes` 鍵會被忽略，且 `openclaw doctor --fix` 會將其從較舊設定中移除。
OpenClaw 不再於 Gateway 寫入期間自動建立 `sessions.json.bak.*` 輪替備份。舊版 `session.maintenance.rotateBytes` 鍵會被忽略，`openclaw doctor --fix` 會將其從較舊設定中移除。
磁碟預算清理的執行順序（`mode: "enforce"`）：
1. 先移除最舊的已封存、孤立逐字稿或孤立軌跡成品。
2. 如果仍高於目標，逐出最舊的工作階段項目及其逐字稿/軌跡檔案。
3. 持續處理直到用量等於或低於 `highWaterBytes`。
1. 先移除最舊的封存、孤立轉錄稿或孤立軌跡成品。
2. 如果仍高於目標，淘汰最舊的工作階段項目及其轉錄稿/軌跡檔案。
3. 持續進行直到用量等於或低於 `highWaterBytes`。
在 `mode: "warn"` 中，OpenClaw 會報告可能的逐出項目，但不會變更儲存區/檔案。
在 `mode: "warn"` 中，OpenClaw 會回報可能的淘汰項目，但不會變更儲存區/檔案。
隨需執行維護：
視需要執行維護：
```bash
openclaw sessions cleanup --dry-run
@ -107,44 +107,44 @@ openclaw sessions cleanup --enforce
## Cron 工作階段與執行記錄
隔離的 Cron 執行也會建立工作階段項目/逐字稿，且有專用的保留控制：
隔離的 Cron 執行也會建立工作階段項目/轉錄稿，並且有專用的保留控制：
- `cron.sessionRetention`（預設 `24h`）會從工作階段儲存區修剪舊的隔離 Cron 執行工作階段（`false` 會停用）。
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 會修剪 `~/.openclaw/cron/runs/<jobId>.jsonl` 檔案（預設：`2_000_000` 位元組和 `2000` 行）。
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 會修剪 `~/.openclaw/cron/runs/<jobId>.jsonl` 檔案（預設：`2_000_000` 位元組與 `2000` 行）。
當 Cron 強制建立新的隔離執行工作階段時，它會在寫入新列之前清理前一個 `cron:<jobId>` 工作階段項目。它會帶入安全偏好設定，例如思考/快速/詳細設定、標籤，以及使用者明確選取的模型/驗證覆寫。它會捨棄環境對話上下文，例如頻道/群組路由、傳送或佇列原則、提權、來源和 ACP 執行階段繫結，因此新的隔離執行無法從舊執行繼承過期的傳遞或執行階段權限。
當 Cron 強制建立新的隔離執行工作階段時，會在寫入新列之前清理先前的 `cron:<jobId>` 工作階段項目。它會帶入安全的偏好設定，例如思考/快速/詳細設定、標籤，以及使用者明確選取的模型/驗證覆寫。它會捨棄環境對話上下文，例如頻道/群組路由、傳送或佇列策略、提權、來源，以及 ACP 執行階段繫結，讓全新的隔離執行不會從較舊執行繼承過期的傳遞或執行階段權限。
---
## 工作階段鍵（`sessionKey`）
`sessionKey` 會識別你位於_哪個對話桶_（路由 + 隔離）。
`sessionKey` 會識別你所在的_對話容器_（路由 + 隔離）。
常見模式：
- 主要/直接聊天（每個代理）：`agent:<agentId>:<mainKey>`（預設 `main`）
- 主要/直接聊天（依代理程式）：`agent:<agentId>:<mainKey>`（預設 `main`）
- 群組：`agent:<agentId>:<channel>:group:<id>`
- 房間/頻道（Discord/Slack）：`agent:<agentId>:<channel>:channel:<id>` 或 `...:room:<id>`
- Cron：`cron:<job.id>`
- Webhook：`hook:<uuid>`（除非被覆寫）
標準規則記錄在 [/concepts/session](/zh-TW/concepts/session)。
標準規則記錄於 [/concepts/session](/zh-TW/concepts/session)。
---
## 工作階段 ID（`sessionId`）
每個 `sessionKey` 都指向目前的 `sessionId`（會延續對話的逐字稿檔案）。
每個 `sessionKey` 都指向目前的 `sessionId`（延續對話的轉錄稿檔案）。
經驗法則：
- **重設**（`/new`、`/reset`）會為該 `sessionKey` 建立新的 `sessionId`。
- **每日重設**（預設為 Gateway 主機本機時間上午 4:00）會在跨過重設邊界後的下一則訊息建立新的 `sessionId`。
- **閒置到期**（`session.reset.idleMinutes` 或舊版 `session.idleMinutes`）會在閒置視窗後有訊息抵達時建立新的 `sessionId`。同時設定每日與閒置時，先到期者生效。
- **系統事件**（Heartbeat、Cron 喚醒、執行通知、Gateway 簿記）可能會變更工作階段列，但不會延長每日/閒置重設的新鮮度。重設輪替會在建立新提示前捨棄前一個工作階段的佇列中系統事件通知。
- **執行緒父項分叉保護**（`session.parentForkMaxTokens`，預設 `100000`）會在父工作階段已經過大時略過父逐字稿分叉；新執行緒會重新開始。設定為 `0` 可停用。
- **每日重設**（預設為 Gateway 主機本地時間上午 4:00）會在越過重設邊界後的下一則訊息建立新的 `sessionId`。
- **閒置到期**（`session.reset.idleMinutes` 或舊版 `session.idleMinutes`）會在閒置視窗後有訊息抵達時建立新的 `sessionId`。當每日與閒置兩者皆已設定時，以先到期者為準。
- **系統事件**（Heartbeat、Cron 喚醒、exec 通知、Gateway 簿記）可能會變更工作階段列，但不會延長每日/閒置重設的新鮮度。重設輪替會在建立全新提示前，捨棄上一個工作階段的已佇列系統事件通知。
- **執行緒父項分叉防護**（`session.parentForkMaxTokens`，預設 `100000`）會在父工作階段已經過大時略過父轉錄稿分叉；新執行緒會全新開始。設為 `0` 可停用。
實作細節：決策發生在 `src/auto-reply/reply/session.ts` 的 `initSessionState()`。
實作細節：決策發生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()`。
---
@ -154,107 +154,118 @@ openclaw sessions cleanup --enforce
主要欄位（非完整清單）：
- `sessionId`：目前逐字稿 ID（除非設定了 `sessionFile`，否則檔名會由此衍生）
- `sessionStartedAt`：目前 `sessionId` 的開始時間戳；每日重設新鮮度使用此欄位。舊版列可能會從 JSONL 工作階段標頭衍生它。
- `lastInteractionAt`：最後一次真實使用者/頻道互動時間戳；閒置重設新鮮度使用此欄位，因此 Heartbeat、Cron 和執行事件不會讓工作階段保持存活。沒有此欄位的舊版列會退回使用復原的工作階段開始時間作為閒置新鮮度。
- `updatedAt`：最後一次儲存區列變更時間戳，用於清單、修剪和簿記。它不是每日/閒置重設新鮮度的權威依據。
- `sessionFile`：可選的明確逐字稿路徑覆寫
- `chatType`：`direct | group | room`（協助 UI 和傳送原則）
- `provider`、`subject`、`room`、`space`、`displayName`：群組/頻道標籤的中繼資料
- 切換設定：
- `sessionId`：目前轉錄稿 ID（除非已設定 `sessionFile`，否則檔名會由此衍生）
- `sessionStartedAt`：目前 `sessionId` 的開始時間戳；每日重設新鮮度會使用此值。舊版列可能會從 JSONL 工作階段標頭衍生此值。
- `lastInteractionAt`：最後一次真實使用者/頻道互動時間戳；閒置重設新鮮度會使用此值，因此 Heartbeat、Cron 與 exec 事件不會讓工作階段保持存活。沒有此欄位的舊版列會退回使用復原出的工作階段開始時間作為閒置新鮮度。
- `updatedAt`：最後一次儲存區列變更時間戳，用於列出、修剪與簿記。它不是每日/閒置重設新鮮度的依據。
- `sessionFile`：選用的明確轉錄稿路徑覆寫
- `chatType`：`direct | group | room`（協助使用者介面與傳送策略）
- `provider`、`subject`、`room`、`space`、`displayName`：群組/頻道標籤中繼資料
- 切換項：
- `thinkingLevel`、`verboseLevel`、`reasoningLevel`、`elevatedLevel`
- `sendPolicy`（每個工作階段的覆寫）
- `sendPolicy`（每工作階段覆寫）
- 模型選擇：
- `providerOverride`、`modelOverride`、`authProfileOverride`
- 權杖計數器（盡力而為 / 依提供者而定）：
- 權杖計數器（最佳努力 / 依供應商而定）：
- `inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`
- `compactionCount`：此工作階段鍵完成自動 Compaction 的次數
- `memoryFlushAt`：最後一次 Compaction 前記憶體排清的時間戳
- `memoryFlushCompactionCount`：最後一次排清執行時的 Compaction 計數
- `memoryFlushAt`：上一次 Compaction 前記憶體排清的時間戳
- `memoryFlushCompactionCount`：上一次排清執行時的 Compaction 計數
儲存區可以安全編輯，但 Gateway 才是權威：它可能會在工作階段執行時重寫或重新補水項目。
---
## 逐字稿結構（`*.jsonl`）
## 轉錄稿結構（`*.jsonl`）
逐字稿由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。
轉錄稿由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。
檔案是 JSONL：
- 第一行：工作階段標頭（`type: "session"`，包含 `id`、`cwd`、`timestamp`、可選的 `parentSession`）
- 接著：帶有 `id` + `parentId` 的工作階段項目（樹狀）
- 第一行：工作階段標頭（`type: "session"`，包含 `id`、`cwd`、`timestamp`、選用的 `parentSession`）
- 接著：具有 `id` + `parentId` 的工作階段項目（樹狀）
值得注意的項目型別：
- `message`：使用者/助理/工具結果訊息
- `custom_message`：由擴充注入且_會_進入模型上下文的訊息（可在 UI 中隱藏）
- `custom`：_不會_進入模型上下文的擴充狀態
- `compaction`：持久化的 Compaction 摘要，帶有 `firstKeptEntryId` 和 `tokensBefore`
- `message`：使用者/助理/toolResult 訊息
- `custom_message`：擴充功能注入、_會_進入模型上下文的訊息（可從使用者介面隱藏）
- `custom`：_不會_進入模型上下文的擴充功能狀態
- `compaction`：持久化的 Compaction 摘要，包含 `firstKeptEntryId` 與 `tokensBefore`
- `branch_summary`：瀏覽樹狀分支時持久化的摘要
OpenClaw 有意**不會**「修正」逐字稿；Gateway 會使用 `SessionManager` 讀寫它們。
OpenClaw 刻意**不會**「修正」轉錄稿；Gateway 使用 `SessionManager` 讀寫它們。
---
## 上下文視窗與已追蹤權杖
## 上下文視窗與追蹤的權杖
有兩個不同概念很重要：
1. **模型上下文視窗**：每個模型的硬性上限（模型可見的權杖）
2. **工作階段儲存區計數器**：寫入 `sessions.json` 的滾動統計（用於 /status 和儀表板）
2. **工作階段儲存區計數器**：寫入 `sessions.json` 的滾動統計（用於 /status 與儀表板）
如果你正在調整限制：
- 上下文視窗來自模型目錄（且可透過設定覆寫）。
- 儲存區中的 `contextTokens` 是執行階段估算/報告值；不要把它視為嚴格保證。
- 儲存區中的 `contextTokens` 是執行階段估算/回報值；不要把它視為嚴格保證。
更多資訊請參閱 [/token-use](/zh-TW/reference/token-use)。
更多資訊請見 [/token-use](/zh-TW/reference/token-use)。
---
## Compaction：它是什麼
Compaction 會將較舊對話摘要成逐字稿中持久化的 `compaction` 項目，並保留近期訊息不變。
Compaction 會將較舊對話摘要成轉錄稿中持久化的 `compaction` 項目，並保留近期訊息不變。
Compaction 後，未來回合會看到：
Compaction 之後，未來回合會看到：
- Compaction 摘要
- `firstKeptEntryId` 之後的訊息
Compaction 是**持久的**（不同於工作階段修剪）。請參閱 [/concepts/session-pruning](/zh-TW/concepts/session-pruning)。
Compaction 是**持久化**的（不同於工作階段修剪）。請見 [/concepts/session-pruning](/zh-TW/concepts/session-pruning)。
## Compaction 區塊邊界和工具配對
## Compaction 區塊邊界與工具配對
當 OpenClaw 將長逐字稿拆分成 Compaction 區塊時，它會讓助理工具呼叫與其相符的 `toolResult` 項目保持配對。
當 OpenClaw 將長轉錄稿拆分成 Compaction 區塊時，會讓助理工具呼叫與其對應的 `toolResult` 項目保持配對。
- 如果權杖占比拆分落在工具呼叫與其結果之間，OpenClaw 會將邊界移到助理工具呼叫訊息，而不是分開該配對。
- 如果尾端工具結果區塊原本會讓區塊超過目標，OpenClaw 會保留該待處理工具區塊，並保持未摘要尾端完整。
- 已中止/錯誤的工具呼叫區塊不會讓待處理拆分保持開啟。
- 如果依權杖占比的切分點落在工具呼叫與其結果之間，OpenClaw 會將邊界移到助理工具呼叫訊息，而不是拆開這一對。
- 如果尾端工具結果區塊原本會讓區塊超過目標，OpenClaw 會保留該待處理工具區塊，並保持未摘要的尾端不變。
- 已中止/錯誤的工具呼叫區塊不會讓待處理切分保持開啟。
---
## 自動 Compaction 發生時機（Pi 執行階段）
## 自動 Compaction 何時發生（Pi 執行階段）
在嵌入式 Pi 代理中，自動 Compaction 會在兩種情況觸發：
在嵌入式 Pi 代理程式中，自動 Compaction 會在兩種情況下觸發：
1. **溢位復原**：模型回傳上下文溢位錯誤
（`request_too_large`、`context length exceeded`、`input exceeds the maximum
1. **溢位復原**：模型傳回上下文溢位錯誤（`request_too_large`、`context length exceeded`、`input exceeds the maximum
number of tokens`、`input token count exceeds the maximum number of input
tokens`、`input is too long for the model`、`ollama error: context length
exceeded`，以及類似的提供者形式變體）→ compact → retry。
2. **閾值維護**：在成功回合後，當：
exceeded`，以及類似供應商形式的變體）→ compact → retry。
2. **閾值維護**：成功完成一回合後，當：
`contextTokens > contextWindow - reserveTokens`
其中：
- `contextWindow` 是模型的上下文視窗
- `reserveTokens` 是為提示 + 下一次模型輸出保留的餘裕
- `reserveTokens` 是為提示 + 下一次模型輸出預留的餘裕
這些是 Pi 執行階段語意（OpenClaw 會消耗事件，但由 Pi 決定何時 Compaction）。
這些是 Pi 執行階段語意（OpenClaw 會消費事件，但由 Pi 決定何時進行 Compaction）。
當設定了 `agents.defaults.compaction.maxActiveTranscriptBytes` 且作用中逐字稿檔案達到該大小時，OpenClaw 也可以在開啟下一次執行前觸發預檢本機 Compaction。這是針對本機重新開啟成本的檔案大小保護，而不是原始封存：OpenClaw 仍會執行一般語意 Compaction，且它需要 `truncateAfterCompaction`，讓已 Compaction 的摘要可成為新的後繼逐字稿。
當 `agents.defaults.compaction.maxActiveTranscriptBytes` 已設定，且作用中轉錄稿檔案達到該大小時，OpenClaw 也可以在開啟下一次執行前觸發預檢本機 Compaction。這是針對本機重新開啟成本的檔案大小防護，而不是原始封存：OpenClaw 仍會執行一般語意 Compaction，並且它需要 `truncateAfterCompaction`，讓壓縮摘要能成為新的後繼轉錄稿。
針對嵌入式 Pi 執行，`agents.defaults.compaction.midTurnPrecheck.enabled: true`
會加入一個可選用的工具迴圈防護機制。在附加工具結果後、下一次
模型呼叫前，OpenClaw 會使用與回合開始時相同的預檢預算邏輯來估算
提示壓力。如果內容已無法容納，該防護機制不會在 Pi 的 `transformContext`
hook 內執行 compact。它會發出結構化的回合中預檢訊號、停止目前的提示提交，
並讓外層執行迴圈使用既有的復原路徑：在足夠時截斷過大的工具結果，
或觸發已設定的 Compaction 模式並重試。此選項預設停用，並可搭配
`default` 與 `safeguard` 兩種 Compaction 模式使用，包括由 provider 支援的
safeguard Compaction。
這與 `maxActiveTranscriptBytes` 無關：位元組大小防護會在回合開始前執行，
而回合中預檢則是在新的工具結果被附加後，於嵌入式 Pi 工具迴圈中稍後執行。
---
@ -272,25 +283,28 @@ Pi 的 Compaction 設定位於 Pi 設定中：
}
```
OpenClaw 也會對嵌入式執行強制套用安全下限：
OpenClaw 也會針對嵌入式執行強制套用安全下限：
- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 會將其提高。
- 預設下限是 `20000` 個 token。
- 設定 `agents.defaults.compaction.reserveTokensFloor: 0` 可停用此下限。
- 如果它已經更高，OpenClaw 會保持不變。
- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 會將它調高。
- 預設下限是 `20000` tokens。
- 設定 `agents.defaults.compaction.reserveTokensFloor: 0` 可停用下限。
- 如果它已經更高，OpenClaw 會維持不變。
- 手動 `/compact` 會遵循明確的 `agents.defaults.compaction.keepRecentTokens`
並保留 Pi 的近期尾端切點。若沒有明確的保留預算，
手動 Compaction 仍會是硬性檢查點，重建後的上下文會從
並保留 Pi 的近期尾端切點。若未明確設定保留預算，
手動 Compaction 仍會是硬檢查點，且重建後的內容會從
新摘要開始。
- 設定 `agents.defaults.compaction.midTurnPrecheck.enabled: true`，可在新的工具結果後、
下一次模型呼叫前執行可選用的工具迴圈預檢。這只是一個觸發條件；
摘要產生仍會使用已設定的 Compaction 路徑。它與 `maxActiveTranscriptBytes`
無關，後者是回合開始時的作用中逐字稿位元組大小防護。
- 將 `agents.defaults.compaction.maxActiveTranscriptBytes` 設為位元組值或
字串，例如 `"20mb"`，即可在作用中的逐字稿變大時於回合前執行本機 Compaction。
這個防護只有在也啟用
`truncateAfterCompaction` 時才會生效。保持未設定或設為 `0` 即可
停用。
- 啟用 `agents.defaults.compaction.truncateAfterCompaction` 時，
OpenClaw 會在 Compaction 後將作用中的逐字稿輪替為壓縮後的後續 JSONL。
舊的完整逐字稿會保留封存，並從
Compaction 檢查點連結，而不是就地重寫。
例如 `"20mb"` 的字串，可在作用中逐字稿變大時，於回合開始前執行本機
Compaction。此防護僅在 `truncateAfterCompaction` 也啟用時才會作用。
保持未設定或設為 `0` 即可停用。
- 當 `agents.defaults.compaction.truncateAfterCompaction` 啟用時，
OpenClaw 會在 Compaction 後，將作用中逐字稿輪替到 compact 後的後續 JSONL。
舊的完整逐字稿會保留封存，並從 Compaction 檢查點連結，
而不是在原處被重寫。
原因：在 Compaction 變得不可避免之前，為多回合「內務處理」（例如記憶寫入）保留足夠餘裕。
@ -299,20 +313,20 @@ OpenClaw 也會對嵌入式執行強制套用安全下限：
---
## 可插拔的 Compaction 提供者
## 可插拔的 Compaction provider
Plugin 可以透過 Plugin API 上的 `registerCompactionProvider()` 註冊 Compaction 提供者。當 `agents.defaults.compaction.provider` 設為已註冊的提供者 ID 時，防護擴充會將摘要委派給該提供者，而不是使用內建的 `summarizeInStages` 管線。
Plugin 可透過 Plugin API 上的 `registerCompactionProvider()` 註冊 Compaction provider。當 `agents.defaults.compaction.provider` 設為已註冊的 provider id 時，safeguard Plugin 會將摘要委派給該 provider，而不是使用內建的 `summarizeInStages` pipeline。
- `provider`：已註冊 Compaction 提供者 Plugin 的 ID。保持未設定即可使用預設 LLM 摘要。
- 設定 `provider` 會強制 `mode: "safeguard"`。
- 提供者會收到與內建路徑相同的 Compaction 指示與識別碼保留政策。
- 防護在提供者輸出後仍會保留近期回合與分割回合的後綴上下文。
- 內建防護摘要會使用新訊息重新萃取既有摘要，
而不是逐字保留完整的先前摘要。
- 防護模式預設會啟用摘要品質稽核；設定
`qualityGuard.enabled: false` 可略過輸出格式錯誤時重試的行為。
- 如果提供者失敗或傳回空結果，OpenClaw 會自動退回使用內建 LLM 摘要。
- Abort/timeout 訊號會被重新擲出（不會被吞掉），以尊重呼叫端取消。
- `provider`：已註冊 Compaction provider Plugin 的 id。保持未設定則使用預設 LLM 摘要。
- 設定 `provider` 會強制使用 `mode: "safeguard"`。
- provider 會收到與內建路徑相同的 Compaction 指示和識別碼保留政策。
- safeguard 在 provider 輸出後，仍會保留近期回合與分割回合的尾端內容。
- 內建 safeguard 摘要會用新訊息重新萃取先前摘要，
而不是逐字保留完整的前一份摘要。
- safeguard 模式預設啟用摘要品質稽核；設定
`qualityGuard.enabled: false` 可略過輸出格式不正確時重試的行為。
- 如果 provider 失敗或回傳空結果，OpenClaw 會自動退回使用內建 LLM 摘要。
- 中止／逾時訊號會重新拋出（不會被吞掉），以尊重呼叫端取消。
來源：`src/plugins/compaction-provider.ts`、`src/agents/pi-hooks/compaction-safeguard.ts`。
@ -331,74 +345,73 @@ Plugin 可以透過 Plugin API 上的 `registerCompactionProvider()` 註冊 Comp
## 靜默內務處理（`NO_REPLY`）
OpenClaw 支援用於背景工作的「靜默」回合，使用者不應看到中間輸出。
OpenClaw 支援背景工作使用的「靜默」回合，使用者不應看到中間輸出。
慣例：
- 助理會以精確的靜默 token `NO_REPLY` /
`no_reply` 開始輸出，以表示「不要向使用者送出回覆」。
- OpenClaw 會在遞送層移除/抑制這段內容。
- 精確靜默 token 抑制不區分大小寫，因此當整個承載內容只有靜默 token 時，
`NO_REPLY` 和 `no_reply` 都算。
- 這只適用於真正背景/不遞送的回合；它不是一般可執行使用者請求的捷徑。
- assistant 以精確的靜默 token `NO_REPLY` /
`no_reply` 開始其輸出，表示「不要將回覆傳遞給使用者」。
- OpenClaw 會在傳遞層剝除／抑制它。
- 精確靜默 token 抑制不區分大小寫，因此當整個 payload 只有靜默 token 時，
`NO_REPLY` 與 `no_reply` 都會算數。
- 這僅適用於真正的背景／不傳遞回合；它不是一般可執行使用者請求的捷徑。
自 `2026.1.10` 起，當
部分區塊以 `NO_REPLY` 開頭時，OpenClaw 也會抑制**草稿/輸入中串流**，
因此靜默操作不會在回合中途外洩部分輸出。
自 `2026.1.10` 起，當部分 chunk 以 `NO_REPLY` 開頭時，OpenClaw 也會抑制
**草稿／輸入中串流**，因此靜默操作不會在回合中洩漏部分輸出。
---
## Compaction 前「記憶清空」（已實作）
## Compaction 前「記憶 flush」（已實作）
目標：在自動 Compaction 發生前，執行一個靜默的代理式回合，將持久
狀態寫入磁碟（例如代理工作區中的 `memory/YYYY-MM-DD.md`），讓 Compaction 無法
抹除關鍵上下文。
目標：在自動 Compaction 發生前，執行一個靜默 agentic 回合，將持久狀態
寫入磁碟（例如 agent 工作區中的 `memory/YYYY-MM-DD.md`），讓 Compaction 不會
抹除關鍵內容。
OpenClaw 使用**預先閾值清空**方法：
OpenClaw 使用 **預閾值 flush** 方法：
1. 監控工作階段上下文用量。
2. 當它跨過「軟性閾值」（低於 Pi 的 Compaction 閾值）時，向代理執行靜默的
1. 監控工作階段內容使用量。
2. 當它跨過「軟閾值」（低於 Pi 的 Compaction 閾值）時，對 agent 執行靜默的
「立即寫入記憶」指令。
3. 使用精確的靜默 token `NO_REPLY` / `no_reply`，讓使用者
看不到任何內容。
3. 使用精確的靜默 token `NO_REPLY` / `no_reply`，讓使用者不會看到
任何內容。
設定（`agents.defaults.compaction.memoryFlush`）：
- `enabled`（預設：`true`）
- `model`（可選的精確提供者/模型覆寫，用於清空回合，例如 `ollama/qwen3:8b`）
- `model`（可選的精確 provider/model flush 回合覆寫，例如 `ollama/qwen3:8b`）
- `softThresholdTokens`（預設：`4000`）
- `prompt`（清空回合的使用者訊息）
- `systemPrompt`（附加到清空回合的額外系統提示）
- `prompt`（flush 回合的使用者訊息）
- `systemPrompt`（為 flush 回合附加的額外系統提示）
注意：
- 預設提示/系統提示包含 `NO_REPLY` 提示，以抑制
遞送。
- 設定 `model` 時，清空回合會使用該模型，而不繼承
作用中工作階段的後備鏈，因此僅限本機的內務處理不會靜默地
退回使用付費對話模型。
- 每個 Compaction 週期只會執行一次清空（追蹤於 `sessions.json`）。
- 清空只會針對嵌入式 Pi 工作階段執行（CLI 後端會略過）。
- 當工作階段工作區是唯讀時（`workspaceAccess: "ro"` 或 `"none"`），會略過清空。
- 請參閱 [Memory](/zh-TW/concepts/memory) 了解工作區檔案配置與寫入模式。
- 預設提示／系統提示包含 `NO_REPLY` 提示，以抑制
傳遞。
- 設定 `model` 時，flush 回合會使用該模型，而不繼承
作用中工作階段的 fallback 鏈，因此僅限本機的內務處理不會靜默地
fallback 到付費對話模型。
- 每個 Compaction 週期只會執行一次 flush（在 `sessions.json` 中追蹤）。
- flush 僅會針對嵌入式 Pi 工作階段執行（CLI 後端會略過）。
- 當工作階段工作區為唯讀時（`workspaceAccess: "ro"` 或 `"none"`），會略過 flush。
- 請參閱 [記憶](/zh-TW/concepts/memory) 了解工作區檔案配置與寫入模式。
Pi 也會在擴充 API 中公開 `session_before_compact` hook，但 OpenClaw 的
清空邏輯目前位於 Gateway 端。
Pi 也在 Plugin API 中公開了 `session_before_compact` hook，但 OpenClaw 的
flush 邏輯目前位於 Gateway 端。
---
## 疑難排解檢查清單
- 工作階段金鑰錯誤？從 [/concepts/session](/zh-TW/concepts/session) 開始，並確認 `/status` 中的 `sessionKey`。
- 儲存區與逐字稿不相符？從 `openclaw status` 確認 Gateway 主機與儲存區路徑。
- Compaction 垃圾訊息過多？檢查：
- 模型上下文視窗（太小）
- 工作階段 key 錯誤？從 [/concepts/session](/zh-TW/concepts/session) 開始，並確認 `/status` 中的 `sessionKey`。
- 儲存區與逐字稿不一致？從 `openclaw status` 確認 Gateway 主機與儲存區路徑。
- Compaction 過於頻繁？檢查：
- 模型內容視窗（太小）
- Compaction 設定（`reserveTokens` 對模型視窗而言過高，可能導致更早 Compaction）
- 工具結果膨脹：啟用/調整工作階段修剪
- 靜默回合外洩？確認回覆以 `NO_REPLY` 開頭（不區分大小寫的精確 token），並且你使用的建置包含串流抑制修正。
- 工具結果膨脹：啟用／調整工作階段修剪
- 靜默回合外洩？確認回覆以 `NO_REPLY` 開頭（不區分大小寫的精確 token），且你使用的 build 包含串流抑制修正。
## 相關
- [工作階段管理](/zh-TW/concepts/session)
- [工作階段修剪](/zh-TW/concepts/session-pruning)
- [上下文引擎](/zh-TW/concepts/context-engine)
- [內容引擎](/zh-TW/concepts/context-engine)

178
docs/zh-TW/tools/index.md
View File

@ -1,26 +1,25 @@
---
read_when:
- 您想了解 OpenClaw 提供哪些工具
- 你需要設定、允許或拒絕工具
- 你正在內建工具、Skills 與 Plugin 之間做選擇
summary: OpenClaw 工具與 Plugin 概覽：代理程式能做什麼，以及如何擴充它
- 您需要設定、允許或拒絕工具
- 你正在內建工具、Skills 和 Plugin 之間做出選擇
summary: OpenClaw 工具與 Plugin 概覽：代理程式可以做什麼，以及如何擴充它
title: 工具與 Plugin
x-i18n:
generated_at: "2026-04-30T03:45:49Z"
generated_at: "2026-04-30T16:30:14Z"
model: gpt-5.5
provider: openai
source_hash: 62cde740188c224af03b4425c7f6dfca9a12f95603066db5925724fc6a07dcf0
source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb
source_path: tools/index.md
workflow: 16
---
代理在產生文字以外所做的一切，都透過**工具**完成。
工具讓代理能讀取檔案、執行命令、瀏覽網頁、傳送
訊息，並與裝置互動。
OpenClaw 的代理除了產生文字之外，所有動作都透過**工具**完成。
工具讓代理能夠讀取檔案、執行命令、瀏覽網頁、傳送訊息，以及與裝置互動。
## 工具、Skills 與 Plugin
## 工具、Skills 和 Plugin
OpenClaw 有三個協同運作的層次：
OpenClaw 有三個彼此協作的層次：
<Steps>
<Step title="工具是代理呼叫的項目">
@ -32,90 +31,90 @@ OpenClaw 有三個協同運作的層次：
</Step>
<Step title="Skills 教導代理何時以及如何使用">
skill 是注入系統提示中的 markdown 檔案（`SKILL.md`）。
<Step title="Skills 教導代理何時以及如何操作">
skill 是注入系統提示的 markdown 檔案（`SKILL.md`）。
Skills 會提供代理有效使用工具所需的脈絡、限制與逐步指引。
Skills 可以位於你的工作區、共享資料夾中，或隨 Plugin 一起提供。
Skills 可以位於你的工作區、共用資料夾中，或隨 Plugin 一起提供。
[Skills 參考](/zh-TW/tools/skills) | [建立 Skills](/zh-TW/tools/creating-skills)
</Step>
<Step title="Plugin 將所有內容封裝在一起">
<Step title="Plugin 將所有項目封裝在一起">
Plugin 是可以註冊任意能力組合的套件：
頻道、模型供應商、工具、Skills、語音、即時轉錄、
即時語音、媒體理解、圖像生成、影片生成、
網頁擷取、網頁搜尋等。有些 Plugin 是**核心**（隨 OpenClaw
提供），其他則是**外部**（由社群發布在 npm 上）。
頻道、模型提供者、工具、Skills、語音、即時轉錄、
即時語音、媒體理解、影像生成、影片生成、
網頁擷取、網頁搜尋等等。有些 Plugin 是**核心**（隨
OpenClaw 提供），其他則是**外部**（由社群發布在 npm 上）。
[安裝並設定 Plugin](/zh-TW/tools/plugin) | [建置你自己的 Plugin](/zh-TW/plugins/building-plugins)
[安裝和設定 Plugin](/zh-TW/tools/plugin) | [建置你自己的 Plugin](/zh-TW/plugins/building-plugins)
</Step>
</Steps>
## 內建工具
這些工具隨 OpenClaw 提供，不需安裝任何 Plugin 即可使用：
這些工具隨 OpenClaw 提供，不需要安裝任何 Plugin 即可使用：
| 工具 | 功能 | 頁面 |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | 執行 shell 命令、管理背景程序 | [Exec](/zh-TW/tools/exec), [Exec 核准](/zh-TW/tools/exec-approvals) |
| `code_execution` | 執行沙盒化遠端 Python 分析 | [程式碼執行](/zh-TW/tools/code-execution) |
| `browser` | 控制 Chromium 瀏覽器（導覽、點擊、截圖） | [瀏覽器](/zh-TW/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜尋網頁、搜尋 X 貼文、擷取頁面內容 | [網頁](/zh-TW/tools/web), [網頁擷取](/zh-TW/tools/web-fetch) |
| `exec` / `process` | 執行 shell 命令、管理背景程序 | [Exec](/zh-TW/tools/exec), [Exec Approvals](/zh-TW/tools/exec-approvals) |
| `code_execution` | 執行沙盒化遠端 Python 分析 | [Code Execution](/zh-TW/tools/code-execution) |
| `browser` | 控制 Chromium 瀏覽器（導覽、點擊、螢幕截圖） | [Browser](/zh-TW/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜尋網頁、搜尋 X 貼文、擷取頁面內容 | [Web](/zh-TW/tools/web), [Web Fetch](/zh-TW/tools/web-fetch) |
| `read` / `write` / `edit` | 工作區中的檔案 I/O | |
| `apply_patch` | 多區塊檔案修補 | [套用修補](/zh-TW/tools/apply-patch) |
| `message` | 跨所有頻道傳送訊息 | [代理傳送](/zh-TW/tools/agent-send) |
| `canvas` | 驅動 Node Canvas（present、eval、snapshot） | |
| `nodes` | 探索並指定已配對裝置 | |
| `apply_patch` | 多區塊檔案修補 | [Apply Patch](/zh-TW/tools/apply-patch) |
| `message` | 跨所有頻道傳送訊息 | [Agent Send](/zh-TW/tools/agent-send) |
| `canvas` | 驅動 node Canvas（present、eval、snapshot） | |
| `nodes` | 探索並指定已配對裝置 | |
| `cron` / `gateway` | 管理排程工作；檢查、修補、重新啟動或更新 Gateway | |
| `image` / `image_generate` | 分析或生成圖像 | [圖像生成](/zh-TW/tools/image-generation) |
| `music_generate` | 生成音樂曲目 | [音樂生成](/zh-TW/tools/music-generation) |
| `video_generate` | 生成影片 | [影片生成](/zh-TW/tools/video-generation) |
| `tts` | 一次性文字轉語音轉換 | [TTS](/zh-TW/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 工作階段管理、狀態與子代理編排 | [子代理](/zh-TW/tools/subagents) |
| `session_status` | 輕量的 `/status` 風格讀回與工作階段模型覆寫 | [工作階段工具](/zh-TW/concepts/session-tool) |
| `image` / `image_generate` | 分析或生成影像 | [Image Generation](/zh-TW/tools/image-generation) |
| `music_generate` | 生成音樂曲目 | [Music Generation](/zh-TW/tools/music-generation) |
| `video_generate` | 生成影片 | [Video Generation](/zh-TW/tools/video-generation) |
| `tts` | 一次性文字轉語音轉換 | [TTS](/zh-TW/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 工作階段管理、狀態與子代理編排 | [Sub-agents](/zh-TW/tools/subagents) |
| `session_status` | 輕量級 `/status` 風格回讀與工作階段模型覆寫 | [Session Tools](/zh-TW/concepts/session-tool) |
處理圖像時，使用 `image` 進行分析，使用 `image_generate` 進行生成或編輯。如果你指定 `openai/*`、`google/*`、`fal/*` 或其他非預設圖像供應商，請先設定該供應商的驗證/API 金鑰。
影像工作請使用 `image` 進行分析，使用 `image_generate` 進行生成或編輯。如果你指定 `openai/*`、`google/*`、`fal/*` 或其他非預設影像提供者，請先設定該提供者的 auth/API key。
處理音樂時，使用 `music_generate`。如果你指定 `google/*`、`minimax/*` 或其他非預設音樂供應商，請先設定該供應商的驗證/API 金鑰。
音樂工作請使用 `music_generate`。如果你指定 `google/*`、`minimax/*` 或其他非預設音樂提供者，請先設定該提供者的 auth/API key。
處理影片時，使用 `video_generate`。如果你指定 `qwen/*` 或其他非預設影片供應商，請先設定該供應商的驗證/API 金鑰。
影片工作請使用 `video_generate`。如果你指定 `qwen/*` 或其他非預設影片提供者，請先設定該提供者的 auth/API key。
對於工作流程驅動的音訊生成，當 ComfyUI 等 Plugin 註冊
`music_generate` 時，請使用它。這與文字轉語音的 `tts` 是分開的。
對於工作流程驅動的音訊生成，當 ComfyUI 之類的 Plugin 註冊
`music_generate` 時請使用它。這與文字轉語音的 `tts` 分開。
`session_status` 是 sessions 群組中的輕量狀態/讀回工具。
它會回答目前工作階段中 `/status` 風格的問題，並可
`session_status` 是工作階段群組中的輕量級狀態/回讀工具。
它會回答關於目前工作階段的 `/status` 風格問題，並且可以
選擇性設定每個工作階段的模型覆寫；`model=default` 會清除該
覆寫。與 `/status` 一樣，它可以從最新逐字稿用量項目回填稀疏的 token/快取計數器，以及
作用中執行階段模型標籤。
覆寫。與 `/status` 類似，它可以從最新 transcript usage 項目
回填稀疏的 token/cache 計數器，以及作用中執行階段模型標籤。
`gateway` 是 Gateway 操作的僅限擁有者執行階段工具：
`gateway` 是僅限擁有者使用的 Gateway 作業執行階段工具：
- `config.schema.lookup` 用於編輯前的一個路徑範圍設定子樹
- `config.get` 用於目前設定快照 + 雜湊
- `config.patch` 用於部分設定更新並重新啟動
- `config.apply` 僅用於完整設定取代
- `config.schema.lookup` 用於在編輯前查詢一個以路徑為範圍的設定子樹
- `config.get` 用於目前設定快照 + hash
- `config.patch` 用於帶有重新啟動的部分設定更新
- `config.apply` 僅用於完整設定替換
- `update.run` 用於明確自我更新 + 重新啟動
對於部分變更，優先使用 `config.schema.lookup`，再使用 `config.patch`。只有在你有意取代整個設定時，才使用
部分變更請優先使用 `config.schema.lookup`，然後使用 `config.patch`。只有在你有意替換整個設定時，才使用
`config.apply`。
如需更廣泛的設定文件，請閱讀[設定](/zh-TW/gateway/configuration)與
如需更完整的設定文件，請閱讀[設定](/zh-TW/gateway/configuration)與
[設定參考](/zh-TW/gateway/configuration-reference)。
此工具也會拒絕變更 `tools.exec.ask` 或 `tools.exec.security`；
舊版 `tools.bash.*` 別名會正規化為相同受保護的 exec 路徑。
舊版 `tools.bash.*` 別名會正規化為相同的受保護 exec 路徑。
### Plugin 提供的工具
Plugin 可以註冊額外工具。一些範例：
- [差異](/zh-TW/tools/diffs) — 差異檢視器與轉譯器
- [LLM 任務](/zh-TW/tools/llm-task) — 用於結構化輸出的僅 JSON LLM 步驟
- [Lobster](/zh-TW/tools/lobster) — 具可恢復核准的型別化工作流程執行階段
- [音樂生成](/zh-TW/tools/music-generation) — 由工作流程支援供應商共用的 `music_generate` 工具
- [Diffs](/zh-TW/tools/diffs) — 差異檢視器與轉譯器
- [LLM Task](/zh-TW/tools/llm-task) — 用於結構化輸出的僅 JSON LLM 步驟
- [Lobster](/zh-TW/tools/lobster) — 具備可恢復核准的型別化工作流程執行階段
- [Music Generation](/zh-TW/tools/music-generation) — 具備工作流程後端提供者的共用 `music_generate` 工具
- [OpenProse](/zh-TW/prose) — markdown 優先的工作流程編排
- [Tokenjuice](/zh-TW/tools/tokenjuice) — 壓縮嘈雜的 `exec` 與 `bash` 工具結果
- [Tokenjuice](/zh-TW/tools/tokenjuice) — 壓縮雜訊較多的 `exec` 與 `bash` 工具結果
## 工具設定
@ -133,44 +132,48 @@ Plugin 可以註冊額外工具。一些範例：
}
```
當明確允許清單解析不到任何可呼叫工具時，OpenClaw 會以關閉狀態失敗。
例如，`tools.allow: ["query_db"]` 只有在已載入的 Plugin 確實
註冊 `query_db` 時才會運作。如果沒有內建、Plugin 或捆綁的 MCP 工具符合
允許清單，執行會在模型呼叫前停止，而不是繼續成為
當明確 allowlist 解析後沒有任何可呼叫工具時，OpenClaw 會封閉失敗。
例如，`tools.allow: ["query_db"]` 只有在已載入的 Plugin 實際
註冊 `query_db` 時才會運作。如果沒有內建工具、Plugin 或 bundled MCP 工具
符合 allowlist，執行會在模型呼叫前停止，而不是繼續成為
可能幻覺出工具結果的純文字執行。
### 工具設定檔
`tools.profile` 會先設定基礎允許清單，再套用 `allow`/`deny`。
`tools.profile` 會在套用 `allow`/`deny` 前設定基礎 allowlist。
每個代理覆寫：`agents.list[].tools.profile`。
| 設定檔 | 包含內容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 較廣泛命令/控制存取的無限制基準；與未設定 `tools.profile` 相同 |
| `full` | 用於更廣泛命令/控制存取的非受限基準；等同於未設定 `tools.profile` |
| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`music_generate`、`video_generate` |
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
| `minimal` | 僅 `session_status` |
| `minimal` | 僅 `session_status` |
<Note>
`tools.profile: "messaging"` 對於以頻道為重點的
代理有意保持狹窄。它排除了更廣泛的命令/控制工具，例如檔案系統、執行階段、
瀏覽器、canvas、nodes、Cron 與 Gateway 控制。使用 `tools.profile: "full"`
作為較廣泛命令/控制存取的無限制基準，然後在需要時使用
`tools.allow` / `tools.deny` 修剪存取權。
`tools.profile: "messaging"` 對於以頻道為主的
代理刻意保持狹窄。它不包含較廣泛的命令/控制工具，例如檔案系統、執行階段、
瀏覽器、canvas、nodes、cron 與 Gateway 控制。使用 `tools.profile: "full"`
作為較廣泛命令/控制存取的非受限基準，然後在需要時透過
`tools.allow` / `tools.deny` 修剪
存取權。
</Note>
`coding` 包含輕量網頁工具（`web_search`、`web_fetch`、`x_search`），
但不包含完整的瀏覽器控制工具。瀏覽器自動化可以驅動真實
工作階段與已登入的設定檔，因此請透過
`coding` 包含輕量級網頁工具（`web_search`、`web_fetch`、`x_search`），
但不包含完整的瀏覽器控制工具。瀏覽器自動化可以驅動真實的
工作階段與已登入設定檔，因此請使用
`tools.alsoAllow: ["browser"]` 或每個代理的
`agents.list[].tools.alsoAllow: ["browser"]` 明確加入它。
`coding` 與 `messaging` 設定檔也允許已設定的捆綁 MCP 工具，
Plugin 金鑰為 `bundle-mcp`。當你希望
設定檔保留其一般內建項目、但隱藏所有已設定 MCP 工具時，請加入 `tools.deny: ["bundle-mcp"]`。
`minimal` 設定檔不包含捆綁 MCP 工具。
<Note>
在限制性設定檔（`messaging`、`minimal`）下設定 `tools.exec` 或 `tools.fs`，不會隱含擴大該設定檔的 allowlist。當你希望限制性設定檔使用那些已設定區段時，請新增明確的 `tools.alsoAllow` 項目（例如 exec 使用 `["exec", "process"]`，或 fs 使用 `["read", "write", "edit"]`）。當設定區段存在但沒有相符的 `alsoAllow` 授權時，OpenClaw 會記錄啟動警告。
</Note>
範例（預設為最廣泛的工具介面）：
`coding` 與 `messaging` 設定檔也允許設定在 Plugin key `bundle-mcp` 下的 bundled MCP 工具。
當你希望設定檔保留其一般內建工具，但隱藏所有已設定的 MCP 工具時，加入 `tools.deny: ["bundle-mcp"]`。
`minimal` 設定檔不包含 bundled MCP 工具。
範例（預設使用最廣泛的工具表面）：
```json5
{
@ -182,7 +185,7 @@ Plugin 金鑰為 `bundle-mcp`。當你希望
### 工具群組
在允許/拒絕清單中使用 `group:*` 簡寫：
在 allow/deny 清單中使用 `group:*` 簡寫：
| 群組 | 工具 |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
@ -197,20 +200,21 @@ Plugin 金鑰為 `bundle-mcp`。當你希望
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image, image_generate, music_generate, video_generate, tts |
| `group:openclaw` | 所有內建 OpenClaw 工具（不含 Plugin 工具） |
| `group:openclaw` | 所有內建 OpenClaw 工具（不包含 Plugin 工具） |
`sessions_history` 會傳回有界且經安全篩選的回憶檢視。它會從助理文字中移除
思考標籤、`<relevant-memories>` 架構、純文字工具呼叫 XML
承載內容（包括 `<tool_call>...</tool_call>`、
`sessions_history` 會回傳有界且經安全篩選的回憶檢視。它會從助理文字中移除
思考標籤、`<relevant-memories>` 鷹架、純文字工具呼叫 XML
酬載（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>`，以及截斷的工具呼叫區塊）、
降級的工具呼叫架構、洩漏的 ASCII／全形模型控制
權杖，以及格式錯誤的 MiniMax 工具呼叫 XML，然後套用
遮蔽／截斷，以及可能的超大列預留位置，而不是充當原始逐字記錄傾印。
`<function_calls>...</function_calls>`，以及被截斷的工具呼叫區塊）、
降級的工具呼叫鷹架、外洩的 ASCII／全形模型控制
權杖，以及格式錯誤的 MiniMax 工具呼叫 XML，接著套用
遮罩／截斷，並可能使用過大列預留位置，而不是當作
原始對話記錄傾印。
### 供應商專屬限制
### 提供者專屬限制
使用 `tools.byProvider` 針對特定供應商限制工具，而不
使用 `tools.byProvider` 可限制特定提供者的工具，而不需
變更全域預設值：
```json5

363
docs/zh-TW/tools/subagents.md
View File

@ -1,45 +1,40 @@
---
read_when:
- 你想透過代理程式進行背景或並行工作
- 您正在變更 sessions_spawn 或子代理工具政策
- 你正在實作或疑難排解執行緒繫結的子代理工作階段
- 你想透過代理程式進行背景或平行工作
- 你正在變更 sessions_spawn 或子代理工具政策
- 你正在實作或疑難排解對話串綁定的子代理工作階段
sidebarTitle: Sub-agents
summary: 啟動隔離的背景代理程式執行作業，並將結果回報到請求者的聊天室
summary: 啟動隔離的背景代理程式執行，並將結果回報至請求者聊天
title: 子代理
x-i18n:
generated_at: "2026-04-30T03:48:07Z"
generated_at: "2026-04-30T16:30:18Z"
model: gpt-5.5
provider: openai
source_hash: 84386ea706873cf9f2ea03261f916c8fb01304999f2d9fa86e037e734a62bf7e
source_hash: c7c46d2c6d9ddac23653dcbfaf20df0ff5be9619035a1b115a3b49fd48fd8280
source_path: tools/subagents.md
workflow: 16
---
子代理是在現有代理執行中產生的背景代理執行。
它們會在自己的工作階段（`agent:<agentId>:subagent:<uuid>`）中執行，
完成時會將結果**公告**回請求者聊天通道。
每個子代理執行都會被追蹤為一個
[背景工作](/zh-TW/automation/tasks)。
它們會在自己的工作階段（`agent:<agentId>:subagent:<uuid>`）中執行，並在完成時將結果**公告**回請求者的聊天
頻道。每次子代理執行都會被追蹤為
[背景任務](/zh-TW/automation/tasks)。
主要目標：
- 平行化「研究 / 長時間工作 / 慢速工具」工作，而不阻塞主要執行。
- 預設保持子代理隔離（工作階段分離 + 可選的沙箱）。
- 平行處理「研究／長時間任務／慢速工具」工作，而不阻塞主執行。
- 預設隔離子代理（工作階段分離 + 選用沙盒）。
- 讓工具介面難以誤用：子代理預設**不會**取得工作階段工具。
- 支援可設定的巢狀深度，以便使用編排器模式。
- 支援可設定的巢狀深度，以用於協調器模式。
<Note>
**成本注意事項：**每個子代理預設都有自己的內容脈絡和 token 用量。
對於繁重或重複性的工作，請為子代理設定較便宜的模型，
並讓主要代理使用品質較高的模型。可透過
`agents.defaults.subagents.model` 或每個代理的覆寫設定進行設定。
當子代理確實需要請求者目前的逐字稿時，代理可以在那次產生中要求
`context: "fork"`。
**成本注意事項：**預設情況下，每個子代理都有自己的上下文與 token 用量。對於繁重或重複性的任務，請為子代理設定較便宜的模型，並讓主代理使用較高品質的模型。可透過 `agents.defaults.subagents.model` 或每個代理的覆寫設定進行設定。當子代理確實需要請求者目前的逐字稿時，代理可在該次產生中要求 `context: "fork"`。
</Note>
## 斜線命令
使用 `/subagents` 檢查或控制**目前工作階段**的子代理執行：
使用 `/subagents` 檢查或控制**目前
工作階段**的子代理執行：
```text
/subagents list
@ -51,13 +46,12 @@ x-i18n:
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
```
`/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 id、
逐字稿路徑、清理）。使用 `sessions_history` 可取得有界且經安全篩選的回憶檢視；當你需要原始完整逐字稿時，請檢查磁碟上的逐字稿路徑。
`/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 id、逐字稿路徑、清理）。使用 `sessions_history` 取得有界且經安全篩選的回顧檢視；當你需要原始完整逐字稿時，請檢查磁碟上的逐字稿路徑。
### 討論串繫結控制
### 執行緒繫結控制
這些命令適用於支援持久討論串繫結的通道。
請參閱下方的[支援討論串的通道](#thread-supporting-channels)。
這些命令適用於支援持久執行緒繫結的頻道。
請參閱下方的[支援執行緒的頻道](#thread-supporting-channels)。
```text
/focus <subagent-label|session-key|session-id|session-label>
@ -69,76 +63,75 @@ x-i18n:
### 產生行為
`/subagents spawn` 會以使用者命令啟動背景子代理（不是內部轉送），並在執行完成時，將一則最終完成更新傳送回請求者聊天。
`/subagents spawn` 會以使用者命令（而非內部轉送）的形式啟動背景子代理，並在執行完成時將一則最終完成更新傳送回請求者聊天。
<AccordionGroup>
<Accordion title="非阻塞、推送式完成">
- 產生命令是非阻塞的；它會立即傳回執行 id。
- 完成時，子代理會向請求者聊天通道公告摘要/結果訊息。
- 完成採用推送式。產生後，請**不要**在迴圈中輪詢 `/subagents list`、`sessions_list` 或 `sessions_history` 只是為了等待它完成；只在需要除錯或介入時按需檢查狀態。
- 完成時，OpenClaw 會盡力關閉該子代理工作階段開啟並被追蹤的瀏覽器分頁/程序，然後公告清理流程才會繼續。
- 產生命令是非阻塞的；它會立即傳回一個執行 id。
- 完成時，子代理會將摘要／結果訊息公告回請求者聊天頻道。
- 完成是推送式的。產生後，請**不要**為了等待它完成而在迴圈中輪詢 `/subagents list`、`sessions_list` 或 `sessions_history`；僅在偵錯或介入時按需檢查狀態。
- 完成時，在公告清理流程繼續之前，OpenClaw 會盡力關閉該子代理工作階段開啟並受追蹤的瀏覽器分頁／程序。
</Accordion>
<Accordion title="手動產生的交付韌性">
- OpenClaw 會先嘗試使用穩定的冪等性金鑰進行直接 `agent` 交付。
- 如果直接交付失敗，會退回使用佇列路由。
- 如果佇列路由仍不可用，公告會以短暫的指數退避重試，然後才最終放棄。
- 完成交付會保留已解析的請求者路由：可用時，以討論串繫結或對話繫結的完成路由為準；如果完成來源只提供通道，OpenClaw 會從請求者工作階段已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）補上缺少的目標/帳號，因此直接交付仍可運作。
<Accordion title="手動產生的傳遞韌性">
- OpenClaw 會先嘗試使用穩定的冪等鍵進行直接 `agent` 傳遞。
- 如果直接傳遞失敗，會退回到佇列路由。
- 如果佇列路由仍不可用，公告會在最終放棄前以短暫的指數退避重試。
- 完成傳遞會保留已解析的請求者路由：當執行緒繫結或對話繫結的完成路由可用時會優先使用；如果完成來源只提供頻道，OpenClaw 會從請求者工作階段已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）補齊缺少的目標／帳戶，讓直接傳遞仍可運作。
</Accordion>
<Accordion title="完成交接中繼資料">
對請求者工作階段的完成交接是執行階段產生的內部內容脈絡（不是使用者撰寫的文字），並包含：
傳給請求者工作階段的完成交接是執行階段產生的內部上下文（不是使用者撰寫的文字），並包含：
- `Result` — 最新可見的 `assistant` 回覆文字，否則為經清理的最新工具/toolResult 文字。終止且失敗的執行不會重複使用擷取到的回覆文字。
- `Result` — 最新可見的 `assistant` 回覆文字，否則為經清理的最新工具／toolResult 文字。終止且失敗的執行不會重用擷取到的回覆文字。
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。
- 精簡的執行階段/token 統計資料。
- 一項交付指示，要求請求者代理以一般助理語氣重寫（而不是轉發原始內部中繼資料）。
- 精簡的執行階段／token 統計資料。
- 一則傳遞指示，要求請求者代理以一般助理語氣改寫（而不是轉發原始內部中繼資料）。
</Accordion>
<Accordion title="模式與 ACP 執行階段">
- `--model` 和 `--thinking` 會覆寫該特定執行的預設值。
- 使用 `info`/`log` 在完成後檢查詳細資料與輸出。
- `/subagents spawn` 是一次性模式（`mode: "run"`）。若要使用持久的討論串繫結工作階段，請使用 `sessions_spawn` 搭配 `thread: true` 和 `mode: "session"`。
- 對於 ACP harness 工作階段（Claude Code、Gemini CLI、OpenCode，或明確指定的 Codex ACP/acpx），當工具宣告支援該執行階段時，請使用 `sessions_spawn` 搭配 `runtime: "acp"`。除錯完成或代理對代理迴圈時，請參閱 [ACP 交付模型](/zh-TW/tools/acp-agents#delivery-model)。啟用 `codex` Plugin 時，除非使用者明確要求 ACP/acpx，否則 Codex 聊天/討論串控制應優先使用 `/codex ...`，而不是 ACP。
- OpenClaw 會隱藏 `runtime: "acp"`，直到 ACP 已啟用、請求者未被沙箱化，且已載入像 `acpx` 這樣的後端 Plugin。`runtime: "acp"` 需要外部 ACP harness id，或包含 `runtime.type="acp"` 的 `agents.list[]` 項目；對於來自 `agents_list` 的一般 OpenClaw 設定代理，請使用預設子代理執行階段。
- `/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 時，除非使用者明確要求 ACP/acpx，否則 Codex 聊天／執行緒控制應優先使用 `/codex ...` 而不是 ACP。
- OpenClaw 會隱藏 `runtime: "acp"`，直到 ACP 已啟用、請求者未被沙盒化，且已載入後端 plugin（例如 `acpx`）。`runtime: "acp"` 預期使用外部 ACP 控制架構 id，或 `runtime.type="acp"` 的 `agents.list[]` 項目；對於來自 `agents_list` 的一般 OpenClaw 設定代理，請使用預設的子代理執行階段。
</Accordion>
</AccordionGroup>
## 內容脈絡模式
## 上下文模式
原生子代理會以隔離狀態啟動，除非呼叫者明確要求分支目前逐字稿。
原生子代理會以隔離狀態啟動，除非呼叫者明確要求 fork
目前逐字稿。
| 模式 | 使用時機 | 行為 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | 全新研究、獨立實作、慢速工具工作，或任何可在工作文字中清楚交代的事項 | 建立乾淨的子逐字稿。這是預設值，可降低 token 用量。 |
| `fork` | 依賴目前對話、先前工具結果，或請求者逐字稿中既有細微指示的工作 | 在子代理啟動前，將請求者逐字稿分支到子工作階段中。 |
| `isolated` | 全新研究、獨立實作、慢速工具工作，或任何可在任務文字中簡要說明的內容 | 建立乾淨的子逐字稿。這是預設值，並能降低 token 使用量。 |
| `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`
確認有效工具清單。
不會；若代理應委派工作，請加入 `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]`，或使用 `tools.profile: "coding"`。
頻道／群組、提供者、沙盒，以及每個代理的允許／拒絕政策仍可在設定檔階段後移除該工具。請在同一
工作階段中使用 `/tools` 確認有效工具清單。
**預設值：**
- **模型：**除非你設定 `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`（無逾時）。
- **執行逾時：**如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 會在有設定時使用 `agents.defaults.subagents.runTimeoutSeconds`；否則會退回到 `0`（無逾時）。
### 工具參數
<ParamField path="task" type="string" required>
子代理的工作描述。
子代理的任務說明。
</ParamField>
<ParamField path="label" type="string">
選用的人類可讀標籤。
@ -147,55 +140,55 @@ x-i18n:
在 `subagents.allowAgents` 允許時，於另一個代理 id 下產生。
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
`acp` 僅用於外部 ACP harness（`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[]` 項目。
</ParamField>
<ParamField path="resumeSessionId" type="string">
僅限 ACP。當 `runtime: "acp"` 時，恢復現有 ACP harness 工作階段；原生子代理產生會忽略此項。
僅限 ACP。當 `runtime: "acp"` 時恢復現有 ACP 控制架構工作階段；對原生子代理產生會被忽略。
</ParamField>
<ParamField path="streamTo" type='"parent"'>
僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流到父工作階段；原生子代理產生請省略此項。
僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流到父工作階段；原生子代理產生時請省略。
</ParamField>
<ParamField path="model" type="string">
覆寫子代理模型。無效值會被略過，且子代理會在預設模型上執行，並在工具結果中顯示警告。
覆寫子代理模型。無效值會被略過，子代理會在預設模型上執行，並在工具結果中顯示警告。
</ParamField>
<ParamField path="thinking" type="string">
覆寫子代理執行的 thinking 層級。
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
已設定時預設為 `agents.defaults.subagents.runTimeoutSeconds`，否則為 `0`。設定後，子代理執行會在 N 秒後中止。
有設定時預設為 `agents.defaults.subagents.runTimeoutSeconds`，否則為 `0`。設定後，子代理執行會在 N 秒後中止。
</ParamField>
<ParamField path="thread" type="boolean" default="false">
當為 `true` 時，要求為此子代理工作階段進行通道討論串繫結。
當為 `true` 時，要求為此子代理工作階段進行頻道執行緒繫結。
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
如果 `thread: true` 且省略 `mode`，預設會變成 `session`。`mode: "session"` 需要 `thread: true`。
如果 `thread: true` 且省略 `mode`，預設會變為 `session`。`mode: "session"` 需要 `thread: true`。
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
`"delete"` 會在公告後立即封存（仍會透過重新命名保留逐字稿）。
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
`require` 會拒絕產生，除非目標子執行階段已被沙箱化。
`require` 會拒絕產生，除非目標子執行階段已被沙盒化。
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
`fork` 會將請求者目前逐字稿分支到子工作階段。僅限原生子代理。只有在子代理需要目前逐字稿時才使用 `fork`。
`fork` 會將請求者目前的逐字稿分支到子工作階段。僅限原生子代理。只有在子代理需要目前逐字稿時才使用 `fork`。
</ParamField>
<Warning>
`sessions_spawn` **不**接受通道交付參數（`target`、
`channel`、`to`、`threadId`、`replyTo`、`transport`）。若要交付，請從產生的執行使用
`sessions_spawn` **不**接受頻道傳遞參數（`target`、
`channel`、`to`、`threadId`、`replyTo`、`transport`）。若要傳遞，請從產生的執行使用
`message`/`sessions_send`。
</Warning>
## 討論串繫結工作階段
## 執行緒繫結工作階段
當通道已啟用討論串繫結時，子代理可以持續繫結到討論串，
讓該討論串中的後續使用者訊息持續路由到同一個子代理工作階段。
當頻道已啟用執行緒繫結時，子代理可以保持繫結到執行緒，讓該執行緒中的後續使用者訊息持續路由到同一個子代理工作階段。
### 支援討論串的通道
### 支援執行緒的頻道
**Discord** 目前是唯一支援的通道。它支援持久的討論串繫結子代理工作階段（`sessions_spawn` 搭配
`thread: true`）、手動討論串控制（`/focus`、`/unfocus`、`/agents`、
`/session idle`、`/session max-age`），以及配接器鍵
**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` 和
@ -205,16 +198,16 @@ x-i18n:
<Steps>
<Step title="產生">
`sessions_spawn` 搭配 `thread: true`（以及選用的 `mode: "session"`）。
`sessions_spawn` 搭配 `thread: true`（並可選擇搭配 `mode: "session"`）。
</Step>
<Step title="繫結">
OpenClaw 會在作用中的通道中建立或繫結討論串到該工作階段目標。
OpenClaw 會在作用中頻道中建立或繫結一個執行緒到該工作階段目標。
</Step>
<Step title="路由後續訊息">
該討論串中的回覆和後續訊息會路由到繫結的工作階段。
該執行緒中的回覆與後續訊息會路由到已繫結的工作階段。
</Step>
<Step title="檢查逾時">
使用 `/session idle` 檢查/更新非活動自動取消聚焦，並使用
使用 `/session idle` 檢查／更新閒置自動取消焦點，並使用
`/session max-age` 控制硬性上限。
</Step>
<Step title="分離">
@ -224,55 +217,55 @@ x-i18n:
### 手動控制
| 命令 | 效果 |
| 指令 | 效果 |
| ------------------ | --------------------------------------------------------------------- |
| `/focus <target>` | 將目前對話串（或建立一個）繫結到子代理/工作階段目標 |
| `/unfocus` | 移除目前已繫結對話串的繫結 |
| `/focus <target>` | 將目前執行緒（或建立一個執行緒）繫結到子代理/工作階段目標 |
| `/unfocus` | 移除目前已繫結執行緒的繫結 |
| `/agents` | 列出作用中的執行和繫結狀態（`thread:<id>` 或 `unbound`） |
| `/session idle` | 檢查/更新閒置自動取消聚焦（僅限已聚焦且已繫結的對話串） |
| `/session max-age` | 檢查/更新硬性上限（僅限已聚焦且已繫結的對話串） |
| `/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/tools/slash-commands)以取得目前的轉接器詳細資訊。
### 允許清單
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
可透過明確 `agentId` 作為目標的代理 ID 清單（`["*"]` 允許任何代理）。預設值：僅限請求者代理。如果你設定清單，且仍希望請求者使用 `agentId` 產生自己，請將請求者 ID 加入清單。
可透過明確 `agentId` 指定為目標的代理 ID 清單（`["*"]` 允許任何代理）。預設值：僅限請求者代理。如果你設定清單，但仍希望請求者能以 `agentId` 產生自己，請將請求者 ID 加入清單。
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
當請求者代理未設定自己的 `subagents.allowAgents` 時使用的預設目標代理允許清單。
</ParamField>
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選取設定檔）。每個代理覆寫：`agents.list[].subagents.requireAgentId`。
封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔）。個別代理覆寫：`agents.list[].subagents.requireAgentId`。
</ParamField>
如果請求者工作階段受到沙盒限制，`sessions_spawn` 會拒絕將在無沙盒狀態下執行的目標。
如果請求者工作階段受沙箱限制，`sessions_spawn` 會拒絕將在非沙箱環境中執行的目標。
### 探索
使用 `agents_list` 查看目前允許用於 `sessions_spawn` 的代理 ID。回應會包含每個列出代理的有效模型和嵌入式執行階段中繼資料，讓呼叫者可以區分 PI、Codex 應用程式伺服器，以及其他已設定的原生執行階段。
使用 `agents_list` 查看目前允許用於 `sessions_spawn` 的代理 ID。回應包含每個列出代理的有效模型與內嵌執行階段中繼資料，讓呼叫者能區分 PI、Codex app-server 和其他已設定的原生執行階段。
### 自動封存
- 子代理工作階段會在 `agents.defaults.subagents.archiveAfterMinutes` 之後自動封存（預設為 `60`）。
- 子代理工作階段會在 `agents.defaults.subagents.archiveAfterMinutes` 後自動封存（預設 `60`）。
- 封存使用 `sessions.delete`，並將逐字稿重新命名為 `*.deleted.<timestamp>`（同一資料夾）。
- `cleanup: "delete"` 會在宣告後立即封存（仍會透過重新命名保留逐字稿）。
- 自動封存是盡力而為；如果 gateway 重新啟動，待處理計時器會遺失。
- `cleanup: "delete"` 會在宣布後立即封存（仍透過重新命名保留逐字稿）。
- 自動封存採盡力而為；如果 Gateway 重新啟動，待執行的計時器會遺失。
- `runTimeoutSeconds` **不會** 自動封存；它只會停止執行。工作階段會保留到自動封存為止。
- 自動封存同樣適用於深度 1 和深度 2 工作階段。
- 瀏覽器清理與封存清理彼此獨立：受追蹤的瀏覽器分頁/程序會在執行完成時盡力關閉，即使逐字稿/工作階段記錄仍保留。
- 自動封存同樣適用於深度 1 與深度 2 工作階段。
- 瀏覽器清理與封存清理是分開的：追蹤的瀏覽器分頁/程序會在執行完成時盡力關閉，即使逐字稿/工作階段記錄仍被保留。
## 巢狀子代理
預設情況下，子代理無法產生自己的子代理
（`maxSpawnDepth: 1`）。設定 `maxSpawnDepth: 2` 可啟用一層
巢狀結構，也就是 **協調器模式**：主要 → 協調器子代理 →
巢狀結構 — **協調器模式**：主要 → 協調器子代理 →
工作者子子代理。
```json5
@ -292,99 +285,111 @@ x-i18n:
### 深度層級
| 深度 | 工作階段鍵形狀 | 角色 | 可以產生嗎？ |
| 深度 | 工作階段鍵形狀 | 角色 | 可產生？ |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | 主要代理 | 一律可以 |
| 1 | `agent:<id>:subagent:<uuid>` | 子代理（允許深度 2 時為協調器） | 僅當 `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 子子代理（葉節點工作者） | 永不 |
| 1 | `agent:<id>:subagent:<uuid>` | 子代理（允許深度 2 時為協調器） | 僅當 `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 子子代理（葉節點工作者） | 永不 |
### 宣告鏈
### 宣布鏈
結果會沿鏈往上回傳：
結果會沿鏈向上回傳：
1. 深度 2 工作者完成 → 向其父項（深度 1 協調器）宣告。
2. 深度 1 協調器接收宣告、彙整結果、完成 → 向主要代理宣告。
3. 主要代理接收宣告並交付給使用者。
1. 深度 2 工作者完成 → 向其父層（深度 1 協調器）宣布。
2. 深度 1 協調器收到宣布、彙整結果並完成 → 向主要代理宣布。
3. 主要代理收到宣布並傳遞給使用者。
每個層級只會看到其直接子項的宣告。
每一層只會看到其直接子層的宣布。
<Note>
**操作指引：** 子工作只啟動一次，然後等待完成事件，而不是圍繞 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` 睡眠命令建立輪詢迴圈。
`sessions_list` 和 `/subagents list` 會讓子工作階段關係聚焦於即時工作，作用中的子項會維持附加，已結束的子項會在短暫的近期視窗內保持可見，而陳舊且僅存在於儲存區的子連結會在其新鮮度視窗後被忽略。這可防止舊的 `spawnedBy` /
`parentSessionKey` 中繼資料在重新啟動後復活幽靈子項。如果子項完成事件在你已送出最終答案後才抵達，正確的後續回應是精確的靜默權杖
**操作指引：** 啟動子工作一次，然後等待完成
事件，而不是圍繞 `sessions_list`、
`sessions_history`、`/subagents list` 或 `exec` sleep 指令建立輪詢迴圈。
`sessions_list` 和 `/subagents list` 會讓子工作階段關係
聚焦於即時工作 — 即時子層會保持附加，已結束子層會在短暫的近期視窗內
保持可見，而過時的僅存放區子層連結會在其新鮮度視窗後
被忽略。這可防止舊的 `spawnedBy` /
`parentSessionKey` 中繼資料在重新啟動後復活幽靈子層。
如果你已送出最終答案後才收到子層完成事件，正確的後續回應是精確的靜默權杖
`NO_REPLY` / `no_reply`。
</Note>
### 依深度的工具政策
- 角色和控制範圍會在產生時寫入工作階段中繼資料。這可避免扁平或已還原的工作階段鍵意外重新取得協調器權限。
- **深度 1（協調器，當 `maxSpawnDepth >= 2` 時）：** 取得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子項。其他工作階段/系統工具仍會被拒絕。
- 角色與控制範圍會在產生時寫入工作階段中繼資料。這可避免扁平或還原的工作階段鍵意外重新取得協調器權限。
- **深度 1（協調器，當 `maxSpawnDepth >= 2` 時）：** 取得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子層。其他工作階段/系統工具仍會被拒絕。
- **深度 1（葉節點，當 `maxSpawnDepth == 1` 時）：** 沒有工作階段工具（目前預設行為）。
- **深度 2（葉節點工作者）：** 沒有工作階段工具，`sessions_spawn` 在深度 2 一律被拒絕。無法再產生更多子項。
- **深度 2（葉節點工作者）：** 沒有工作階段工具 — `sessions_spawn` 在深度 2 一律被拒絕。無法再產生更多子層。
### 每個代理的產生限制
### 個別代理產生限制
每個代理工作階段（任何深度）同一時間最多可有 `maxChildrenPerAgent`
（預設 `5`）個作用中子項。這可防止單一協調器失控擴散。
每個代理工作階段（任何深度）一次最多可有 `maxChildrenPerAgent`
（預設 `5`）個作用中子層。這可防止單一協調器失控展開。
### 串級停止
### 級聯停止
停止深度 1 協調器會自動停止其所有深度 2 子項：
停止深度 1 協調器會自動停止其所有深度 2
子層：
- 主要聊天中的 `/stop` 會停止所有深度 1 代理，並串級停止其深度 2 子項。
- `/subagents kill <id>` 會停止特定子代理，並串級停止其子項。
- `/subagents kill all` 會停止請求者的所有子代理並串級停止。
- 主要聊天中的 `/stop` 會停止所有深度 1 代理，並級聯至其深度 2 子層。
- `/subagents kill <id>` 會停止特定子代理，並級聯至其子層。
- `/subagents kill all` 會停止請求者的所有子代理，並級聯。
## 驗證
子代理驗證依 **代理 ID** 解析，而不是依工作階段類型：
- 子代理工作階段鍵為 `agent:<agentId>:subagent:<uuid>`。
- 驗證儲存區會從該代理的 `agentDir` 載入。
- 主要代理的驗證設定檔會作為 **後援** 合併；發生衝突時，代理設定檔會覆寫主要設定檔。
- 驗證存放區會從該代理的 `agentDir` 載入。
- 主要代理的驗證設定檔會作為**備援**合併；衝突時代理設定檔會覆寫主要設定檔。
合併是加成式，因此主要設定檔一律可作為後援使用。尚不支援每個代理完全隔離的驗證。
合併是加成式的，因此主要設定檔永遠可作為備援使用。
尚不支援每個代理完全隔離的驗證。
## 宣告
## 宣布
子代理會透過宣告步驟回報：
子代理會透過宣布步驟回報：
- 宣告步驟在子代理工作階段內執行（不是請求者工作階段）。
- 如果子代理精確回覆 `ANNOUNCE_SKIP`，就不會張貼任何內容。
- 如果最新的助理文字是精確的靜默權杖 `NO_REPLY` / `no_reply`，即使先前已有可見進度，也會抑制宣告輸出。
- 宣布步驟在子代理工作階段內執行（不是請求者工作階段）。
- 如果子代理精確回覆 `ANNOUNCE_SKIP`，則不會張貼任何內容。
- 如果最新助理文字是精確的靜默權杖 `NO_REPLY` / `no_reply`，即使先前已有可見進度，宣布輸出也會被抑制。
交付取決於請求者深度：
傳遞取決於請求者深度：
- 最上層請求者工作階段會使用後續 `agent` 呼叫並進行外部交付（`deliver=true`）。
- 巢狀請求者子代理工作階段會接收內部後續注入（`deliver=false`），讓協調器可以在工作階段內彙整子項結果。
- 頂層請求者工作階段會使用帶有外部傳遞的後續 `agent` 呼叫（`deliver=true`）。
- 巢狀請求者子代理工作階段會收到內部後續注入（`deliver=false`），讓協調器能在工作階段內彙整子層結果。
- 如果巢狀請求者子代理工作階段已不存在，OpenClaw 會在可用時退回到該工作階段的請求者。
對於最上層請求者工作階段，完成模式直接交付會先解析任何已繫結的對話/對話串路由和 hook 覆寫，然後從請求者工作階段儲存的路由填入缺少的頻道目標欄位。這可讓完成訊息留在正確的聊天/主題中，即使完成來源只識別了頻道。
對於頂層請求者工作階段，完成模式的直接傳遞會先解析任何已繫結的對話/執行緒路由與掛鉤覆寫，然後從請求者工作階段儲存的路由補齊缺少的通道目標欄位。
這可讓完成結果留在正確的聊天/主題中，即使完成來源只識別通道。
建置巢狀完成發現時，子項完成彙總會限定於目前請求者執行，避免先前執行的陳舊子項輸出洩漏到目前宣告中。當頻道配接器可用時，宣告回覆會保留對話串/主題路由。
建立巢狀完成發現項目時，子層完成彙總會限定在目前請求者執行範圍內，防止過時的先前執行子層輸出洩漏到目前宣布中。當通道轉接器上有執行緒/主題路由時，宣布回覆會保留該路由。
### 宣告內容
### 宣布內容
宣告內容會正規化為穩定的內部事件區塊：
宣布內容會正規化為穩定的內部事件區塊：
| 欄位 | 來源 |
| 欄位 | 來源 |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| 來源 | `subagent` 或 `cron` |
| 工作階段 ID | 子工作階段鍵/ID |
| 類型 | 宣告類型 + 任務標籤 |
| 狀態 | 衍生自執行階段結果（`success`、`error`、`timeout` 或 `unknown`），**不是** 從模型文字推斷 |
| 結果內容 | 最新可見的助理文字，否則為已清理的最新工具/toolResult 文字 |
| 後續 | 描述何時回覆與何時保持靜默的指示 |
| 來源 | `subagent` 或 `cron` |
| 工作階段 ID | 子工作階段鍵/ID |
| 類型 | 宣布類型 + 任務標籤 |
| 狀態 | 從執行階段結果衍生（`success`、`error`、`timeout` 或 `unknown`）— **不是** 從模型文字推斷 |
| 結果內容 | 最新可見助理文字，否則為已清理的最新工具/toolResult 文字 |
| 後續 | 描述何時回覆或保持靜默的指示 |
終止的失敗執行會回報失敗狀態，而不重播擷取到的回覆文字。逾時時，如果子項只完成了工具呼叫，宣告可將該歷史壓縮成簡短的部分進度摘要，而不是重播原始工具輸出。
終止且失敗的執行會回報失敗狀態，而不重播擷取的
回覆文字。逾時時，如果子層只完成到工具呼叫，宣布
可將該歷史壓縮成簡短的部分進度摘要，而不是
重播原始工具輸出。
### 統計行
宣告承載資料會在結尾包含統計行（即使已換行包裹）：
宣布承載會在結尾包含統計行（即使被包裝）：
- 執行時間（例如 `runtime 5m12s`）。
- 權杖使用量（輸入/輸出/總計）。
- 設定模型定價時的估計成本（`models.providers.*.models[].cost`）。
- 當已設定模型定價時的估計成本（`models.providers.*.models[].cost`）。
- `sessionKey`、`sessionId` 和逐字稿路徑，讓主要代理可透過 `sessions_history` 擷取歷史，或檢查磁碟上的檔案。
內部中繼資料僅供協調使用；面向使用者的回覆應以一般助理語氣重寫。
@ -393,27 +398,30 @@ x-i18n:
`sessions_history` 是較安全的協調路徑：
- 助理回憶會先正規化：移除 thinking 標籤；移除 `<relevant-memories>` / `<relevant_memories>` 鷹架；移除純文字工具呼叫 XML 承載區塊（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`），包括從未乾淨關閉的截斷承載；移除降級的工具呼叫/結果鷹架和歷史內容標記；移除外洩的模型控制權杖（`<|assistant|>`、其他 ASCII `<|...|>`、全形 `<｜...｜>`）；移除格式錯誤的 MiniMax 工具呼叫 XML。
- 助理回憶會先正規化：移除思考標籤；移除 `<relevant-memories>` / `<relevant_memories>` 鷹架；移除純文字工具呼叫 XML 承載區塊（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`），包括從未乾淨關閉的截斷承載；移除降級的工具呼叫/結果鷹架與歷史內容標記；移除洩漏的模型控制權杖（`<|assistant|>`、其他 ASCII `<|...|>`、全形 `<｜...｜>`）；移除格式錯誤的 MiniMax 工具呼叫 XML。
- 憑證/類權杖文字會被遮蔽。
- 長區塊可以被截斷。
- 長區塊可能會被截斷。
- 非常大的歷史可以捨棄較舊列，或以 `[sessions_history omitted: message too large]` 取代過大的列。
- 當你需要完整逐位元組一致的逐字稿時，原始磁碟逐字稿檢查是後援方式。
- 需要完整逐位元組逐字稿時，原始磁碟逐字稿檢查是備援方式。
## 工具政策
子代理會先使用與父項或目標代理相同的設定檔和工具政策管線。之後，OpenClaw 會套用子代理限制層。
子代理會先使用與父層或目標代理相同的設定檔與工具政策管線。
之後，OpenClaw 會套用子代理限制層。
若沒有具限制性的 `tools.profile`，子代理會取得 **除了工作階段工具** 和系統工具以外的所有工具：
若沒有限制性的 `tools.profile`，子代理會取得**除了工作階段工具**與系統工具以外的所有工具：
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
`sessions_history` 在此處仍是有界且已清理的回憶檢視，並非原始逐字稿傾印。
`sessions_history` 在這裡也仍是有界且已清理的回憶檢視 —
它不是原始逐字稿傾印。
當 `maxSpawnDepth >= 2` 時，深度 1 協調器子代理還會額外接收 `sessions_spawn`、`subagents`、`sessions_list` 和
`sessions_history`，以便管理其子項。
當 `maxSpawnDepth >= 2` 時，深度 1 協調器子代理會額外
接收 `sessions_spawn`、`subagents`、`sessions_list` 和
`sessions_history`，以便管理其子層。
### 透過設定覆寫
@ -439,12 +447,7 @@ x-i18n:
}
```
`tools.subagents.tools.allow` 是最終的僅允許篩選器。它可以縮小
已解析的工具集，但無法**加回**被 `tools.profile` 移除的工具。
例如，`tools.profile: "coding"` 包含
`web_search`/`web_fetch`，但不包含 `browser` 工具。若要讓
coding 設定檔的子代理使用 browser 自動化，請在
profile 階段加入 browser：
`tools.subagents.tools.allow` 是最終的僅允許篩選器。它可以縮小已解析的工具集，但無法**加回**已被 `tools.profile` 移除的工具。例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，但不包含 `browser` 工具。若要讓使用 coding 設定檔的子代理使用瀏覽器自動化，請在設定檔階段加入 browser：
```json5
{
@ -455,7 +458,7 @@ profile 階段加入 browser：
}
```
當只有單一代理應取得 browser 自動化時，請使用個別代理的 `agents.list[].tools.alsoAllow: ["browser"]`。
當只有一個代理應取得瀏覽器自動化時，請使用個別代理的 `agents.list[].tools.alsoAllow: ["browser"]`。
## 並行
@ -464,47 +467,37 @@ profile 階段加入 browser：
- **通道名稱：** `subagent`
- **並行數：** `agents.defaults.subagents.maxConcurrent`（預設 `8`）
## 存活狀態與復原
## 存活性與復原
OpenClaw 不會將缺少 `endedAt` 視為
子代理仍存活的永久證明。早於過期執行時間窗口的未結束執行，
在 `/subagents list`、狀態摘要、
後代完成門檻，以及各工作階段並行檢查中，將不再計為作用中/待處理。
OpenClaw 不會將缺少 `endedAt` 視為子代理仍然存活的永久證明。超過過期執行視窗且尚未結束的執行，會停止在 `/subagents list`、狀態摘要、後代完成門檻，以及個別工作階段並行檢查中計為作用中/待處理。
Gateway 重新啟動後，過期且未結束的已還原執行會被修剪，除非
其子工作階段標記為 `abortedLastRun: true`。這些
由重新啟動中止的子工作階段仍可透過子代理
孤立復原流程復原；該流程會先傳送合成的繼續訊息，
再清除已中止標記。
Gateway 重新啟動後，過期且未結束的已還原執行會被修剪，除非其子工作階段標示為 `abortedLastRun: true`。這些因重新啟動而中止的子工作階段仍可透過子代理孤兒復原流程復原；該流程會先傳送合成的恢復訊息，再清除中止標記。
自動重新啟動復原會以每個子工作階段為界限。如果同一個子代理子項在快速重新卡住視窗內反覆被接受進行孤兒復原，OpenClaw 會在該工作階段上持久化復原墓碑，並在後續重新啟動時停止自動恢復它。執行 `openclaw tasks maintenance --apply` 來調和任務記錄，或執行 `openclaw doctor --fix` 來清除已加墓碑工作階段上的過期中止復原旗標。
<Note>
如果子代理產生失敗並出現 Gateway `PAIRING_REQUIRED` /
`scope-upgrade`，請在編輯配對狀態前檢查 RPC 呼叫端。
內部 `sessions_spawn` 協調應以
`client.id: "gateway-client"` 搭配 `client.mode: "backend"` 透過直接
loopback 共享權杖/密碼驗證連線；該路徑不依賴
CLI 的已配對裝置 scope 基準。遠端呼叫端、明確的
`deviceIdentity`、明確的裝置權杖路徑，以及瀏覽器/Node 用戶端
仍需一般裝置核准才能升級 scope。
如果子代理產生失敗並顯示 Gateway `PAIRING_REQUIRED` /
`scope-upgrade`，請先檢查 RPC 呼叫端，再編輯配對狀態。
內部 `sessions_spawn` 協調應以 `client.id: "gateway-client"` 搭配 `client.mode: "backend"`，透過直接 loopback 共用權杖/密碼驗證連線；該路徑不依賴 CLI 的已配對裝置範圍基準。遠端呼叫端、明確的 `deviceIdentity`、明確的裝置權杖路徑，以及瀏覽器/node 用戶端，仍需要一般裝置核准才能進行範圍升級。
</Note>
## 停止
- 在請求者聊天中傳送 `/stop` 會中止請求者工作階段，並停止從中產生的任何作用中子代理執行，且會連鎖至巢狀子項。
- `/subagents kill <id>` 會停止指定子代理，並連鎖至其子項。
- 在請求者聊天中傳送 `/stop` 會中止請求者工作階段，並停止由其產生的任何作用中子代理執行，且會串連到巢狀子項。
- `/subagents kill <id>` 會停止特定子代理，並串連到其子項。
## 限制
- 子代理公告是**盡力而為**。如果 Gateway 重新啟動，待處理的「announce back」工作會遺失。
- 子代理仍共用相同的 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`）。
- 子代理公告是**盡力而為**。如果 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`）。
## 相關
- [ACP 代理](/zh-TW/tools/acp-agents)
- [代理傳送](/zh-TW/tools/agent-send)
- [背景工作](/zh-TW/automation/tasks)
- [背景任務](/zh-TW/automation/tasks)
- [多代理沙箱工具](/zh-TW/tools/multi-agent-sandbox-tools)

155
docs/zh-TW/tools/thinking.md
View File

@ -1,139 +1,140 @@
---
read_when:
- 調整思考、快速模式或詳細指令的解析或預設值
summary: /think、/fast、/verbose、/trace 的指令語法，以及推理可見性
summary: 用於 /think、/fast、/verbose、/trace 與推理可見性的指令語法
title: 思考層級
x-i18n:
generated_at: "2026-04-30T03:47:53Z"
generated_at: "2026-04-30T16:30:54Z"
model: gpt-5.5
provider: openai
source_hash: e9fabead8d2f58fc5bce3bf8b281ad9d52da2cd02ba2777bc1597359537b7705
source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7
source_path: tools/thinking.md
workflow: 16
---
## 功能說明
- 任何傳入本文中的內嵌指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
- 任何傳入本文中的行內指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
- 層級（別名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal →「think」
- low →「think hard」
- medium →「think harder」
- high →「ultrathink」（最大預算）
- xhigh →「ultrathink+」（GPT-5.2+ 和 Codex 模型，加上 Anthropic Claude Opus 4.7 effort）
- adaptive → 由提供者管理的自適應思考（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 動態思考）
- 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 預設值仍由提供者擁有。
- 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 路徑。
- 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.<provider>.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` 增量。
- 思考選單與選擇器由提供者設定檔驅動。提供者 Plugin 會宣告所選模型的確切層級集合，包括二元 `on` 這類標籤。
- `adaptive`、`xhigh` 和 `max` 只會針對支援它們的提供者/模型設定檔顯示。不支援層級的輸入指令會被拒絕，並回覆該模型的有效選項。
- 既有儲存的不支援層級會依提供者設定檔排名重新對應。在非自適應模型上，`adaptive` 會回退到 `medium`，而 `xhigh` 和 `max` 會回退到所選模型支援的最大非 off 層級。
- 未設定明確思考層級時，Anthropic Claude 4.6 模型預設為 `adaptive`。
- Anthropic Claude Opus 4.7 不預設使用自適應思考。除非你明確設定思考層級，否則其 API effort 預設值仍由提供者擁有。
- Anthropic Claude Opus 4.7 會將 `/think xhigh` 對應到自適應思考加上 `output_config.effort: "xhigh"`，因為 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 設定。
- Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到相同的提供者自有最大 effort 路徑。
- DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，較低的非 off 層級則對應到 `high`。
- 具備思考能力的 Ollama 模型公開 `/think low|medium|high|max`；`max` 會對應到原生 `think: "high"`，因為 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字串。
- OpenAI GPT 模型會透過模型特定的 Responses API effort 支援來對應 `/think`。只有目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用推理的 payload，而不是傳送不支援的值。
- 自訂 OpenAI 相容目錄項目可以透過設定 `models.providers.<provider>.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。
- 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`）。
1. 訊息上的行內指令（只套用於該訊息）。
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["<provider>/<model>"].params.fastMode`
5. 備援：`off`
3. 個別代理預設值（`agents.list[].fastModeDefault`）
4. 個別模型設定：`agents.defaults.models["<provider>/<model>"].params.fastMode`
5. 回退：`off`
- 對於 `openai/*`，快速模式會在支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI 優先處理。
- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 會在兩種驗證路徑之間保留一個共用的 `/fast` 切換。
- 對於 `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 代理基底 URL 略過 Anthropic 服務層級注入。
- `/status` 只會在啟用快速模式時顯示 `Fast`。
- 同時設定時，明確的 Anthropic `serviceTier` / `service_tier` 模型參數會覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理 base URL 略過 Anthropic 服務層級注入。
- `/status` 只有在啟用快速模式時才會顯示 `Fast`。
## 詳細指令（/verbose 或 /v）
- 層級：`on`（最小）| `full` | `off`（預設）。
- 只有指令的訊息會切換工作階段詳細記錄，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示而不變更狀態。
- `/verbose off` 會儲存明確的工作階段覆寫；可透過 Sessions UI 選擇 `inherit` 來清除。
- 內嵌指令只影響該訊息；其他情況會套用工作階段/全域預設值。
- 傳送沒有引數的 `/verbose`（或 `/verbose:`）即可查看目前詳細層級。
- 詳細模式開啟時，會發出結構化工具結果的代理（Pi、其他 JSON 代理）會將每次工具呼叫作為自己的僅中繼資料訊息送回，可用時前綴為 `<emoji> <tool-name>: <arg>`（路徑/命令）。這些工具摘要會在每個工具啟動後立即傳送（獨立氣泡），而不是作為串流增量。
- 工具失敗摘要在一般模式中仍可見，但原始錯誤詳細資料後綴會隱藏，除非詳細層級為 `on` 或 `full`。
- 當詳細層級為 `full` 時，工具輸出也會在完成後轉送（獨立氣泡，截斷至安全長度）。如果你在執行期間切換 `/verbose on|full|off`，後續工具氣泡會遵守新設定。
- 僅含指令的訊息會切換工作階段詳細模式，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。
- `/verbose off` 會儲存明確的工作階段覆寫；可在 Sessions UI 中選擇 `inherit` 來清除。
- 行內指令只影響該訊息；否則會套用工作階段/全域預設值。
- 傳送不帶引數的 `/verbose`（或 `/verbose:`）即可查看目前詳細層級。
- 啟用詳細模式時，會發出結構化工具結果的代理（Pi、其他 JSON 代理）會將每次工具呼叫作為自己的僅中繼資料訊息傳回，可用時前綴為 `<emoji> <tool-name>: <arg>`（路徑/指令）。這些工具摘要會在每個工具開始時立即傳送（分開的氣泡），而不是作為串流 delta。
- 工具失敗摘要在一般模式中仍會顯示，但原始錯誤詳細資料後綴會隱藏，除非詳細模式為 `on` 或 `full`。
- 當詳細模式為 `full` 時，工具輸出也會在完成後轉送（分開的氣泡，截斷到安全長度）。如果你在執行期間切換 `/verbose on|full|off`，後續工具氣泡會遵循新設定。
## 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`）。
格式錯誤的本機模型推理標籤會以保守方式處理。封閉的 `<think>...</think>` 區塊會在一般回覆中維持隱藏，已可見文字之後未封閉的推理也會隱藏。如果回覆完全包在單一未封閉的開頭標籤中，且否則會以空文字傳遞，OpenClaw 會移除格式錯誤的開頭標籤並傳遞剩餘文字。
格式不正確的本機模型推理標籤會保守處理。封閉的 `<think>...</think>` 區塊會在一般回覆中維持隱藏，已可見文字後未封閉的推理也會隱藏。如果回覆完整包在單一未封閉開啟標籤中，且原本會作為空文字傳送，OpenClaw 會移除格式不正確的開啟標籤並傳送剩餘文字。
## 相關
## 相關內容
- 提權模式文件位於 [提權模式](/zh-TW/tools/elevated)。
- Elevated mode 文件位於 [Elevated mode](/zh-TW/tools/elevated)。
## Heartbeat
## Heartbeats
- Heartbeat 探測本文是已設定的 Heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的內嵌指令會照常套用（但請避免從 Heartbeat 變更工作階段預設值）。
- Heartbeat 傳遞預設只傳送最終 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 傳遞預設只傳送最終 payload。若也要傳送獨立的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或個別代理的 `agents.list[].heartbeat.includeReasoning: true`。
## 網頁聊天 UI
- 網頁聊天思考選擇器會在頁面載入時，從傳入工作階段儲存區/設定映照工作階段已儲存的層級。
- 選擇另一個層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，也不是一次性的 `thinkingOnce` 覆寫。
- 第一個選項一律是 `Default (<resolved level>)`，其中解析後的預設值來自作用中工作階段模型的提供者思考設定檔，加上 `/status` 和 `session_status` 使用的相同備援邏輯。
- 選擇器使用 Gateway 工作階段列/預設值傳回的 `thinkingLevels`，並保留 `thinkingOptions` 作為舊版標籤清單。瀏覽器 UI 不會保留自己的提供者正規表示式清單；Plugin 擁有模型特定的層級集合。
- `/think:<level>` 仍可運作，並會更新相同儲存的工作階段層級，因此聊天指令和選擇器會保持同步。
- 第一個選項一律是 `Default (<resolved level>)`，其中解析後的預設值來自作用中工作階段模型的提供者思考設定檔，加上 `/status` 與 `session_status` 使用的相同回退邏輯。
- 選擇器使用 Gateway 工作階段列/預設值回傳的 `thinkingLevels`，並將 `thinkingOptions` 保留為舊版標籤清單。瀏覽器 UI 不會保留自己的提供者 regex 清單；模型特定層級集合由 Plugin 擁有。
- `/think:<level>` 仍可運作並更新相同的已儲存工作階段層級，因此聊天指令與選擇器會保持同步。
## 提供者設定檔
- 提供者 Plugin 可以公開 `resolveThinkingProfile(ctx)`，以定義模型支援的層級和預設值。
- 代理 Claude 模型的提供者 Plugin 應重用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 目錄和代理目錄保持一致。
- 每個設定檔層級都有一個已儲存的標準 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），並且可以包含顯示用的 `label`。二元提供者使用 `{ id: "low", label: "on" }`。
- 需要驗證明確思考覆寫的工具 Plugin 應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它們不應維護自己的提供者/模型層級清單。
- 可存取已設定自訂模型中繼資料的工具 Plugin 可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 的選用設定反映在 Plugin 端驗證中。
- 已發布的舊版掛鉤（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）會保留為相容性轉接器，但新的自訂層級集合應使用 `resolveThinkingProfile`。
- Gateway 列和預設值會公開 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證所使用的相同設定檔 id 和標籤。
- 提供者 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 與標籤。