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 03:51:34 +00:00
parent 0db6c7cde4
commit 282f46f264
481 changed files with 122613 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
docs/.i18n/zh-TW.tm.jsonl Normal file
View File

44
docs/zh-TW/.i18n/README.md Normal file
View File

@ -0,0 +1,44 @@
---
x-i18n:
generated_at: "2026-04-30T02:44:12Z"
model: gpt-5.5
provider: openai
source_hash: 6e1cf417b0c04d001bc494fbe03ac2fcb66866f759e21646dbfd1a9c3a968bff
source_path: .i18n/README.md
workflow: 16
---
# OpenClaw 文件 i18n 資產
此資料夾存放來源文件儲存庫的翻譯設定。
產生的語系頁面和即時語系翻譯記憶現在位於發布儲存庫（`openclaw/docs`，本機同層 checkout `~/Projects/openclaw-docs`）。
## 檔案
- `glossary.<lang>.json` — 偏好的術語對應（用於提示指引）。
- `<lang>.tm.jsonl` — 以工作流程 + 模型 + 文字雜湊為索引鍵的翻譯記憶（快取）。在此儲存庫中，語系 TM 檔案會隨需產生。
## 詞彙表格式
`glossary.<lang>.json` 是項目陣列：
```json
{
"source": "troubleshooting",
"target": "故障排除",
"ignore_case": true,
"whole_word": false
}
```
欄位：
- `source`：偏好使用的英文（或來源）片語。
- `target`：偏好的翻譯輸出。
## 備註
- 詞彙表項目會作為**提示指引**傳遞給模型（不進行確定性重寫）。
- `scripts/docs-i18n` 仍負責翻譯產生。
- 來源儲存庫會將英文文件同步至發布儲存庫；語系產生會在該處依語系於推送、排程和 release dispatch 時執行。

38
docs/zh-TW/AGENTS.md Normal file
View File

@ -0,0 +1,38 @@
---
x-i18n:
generated_at: "2026-04-30T02:44:12Z"
model: gpt-5.5
provider: openai
source_hash: 8b046833f9a15dc61894ab9e808a09a9fb055ef7ada5c3d4893fbe5f70dec126
source_path: AGENTS.md
workflow: 16
---
# 文件指南
此目錄負責文件撰寫、Mintlify 連結規則，以及文件 i18n 政策。
## Mintlify 規則
- 文件託管於 Mintlify (`https://docs.openclaw.ai`)。
- `docs/**/*.md` 中的內部文件連結必須保持根相對路徑，且不得有 `.md` 或 `.mdx` 後綴（範例：`[Config](/gateway/configuration)`）。
- 區段交叉參照應在根相對路徑上使用錨點（範例：`[Hooks](/gateway/configuration-reference#hooks)`）。
- 文件標題應避免使用長破折號和撇號，因為 Mintlify 的錨點產生在這些字元上很脆弱。
- README 和其他由 GitHub 轉譯的文件應保留絕對文件 URL，讓連結在 Mintlify 之外也能運作。
- 文件內容必須保持通用：不得包含個人裝置名稱、主機名稱或本機路徑；請使用像 `user@gateway-host` 這樣的佔位符。
## 文件內容規則
- 對於文件、UI 文案和選擇器清單，除非該區段明確描述執行階段順序或自動偵測順序，否則服務/提供者應依字母順序排列。
- 保持隨附 Plugin 命名與根目錄 `AGENTS.md` 中 repo 全域的 Plugin 術語規則一致。
## 文件 i18n
- 此 repo 不維護外語文件。產生的發布輸出位於獨立的 `openclaw/docs` repo（本機通常複製為 `../openclaw-docs`）。
- 不要在此處的 `docs/<locale>/**` 下新增或編輯在地化文件。
- 將此 repo 中的英文文件與詞彙表檔案視為事實來源。
- 流程：在此處更新英文文件，視需要更新 `docs/.i18n/glossary.<locale>.json`，然後讓發布 repo 同步與 `scripts/docs-i18n` 在 `openclaw/docs` 中執行。
- 重新執行 `scripts/docs-i18n` 之前，請為任何必須保持英文或使用固定翻譯的新技術術語、頁面標題或短導覽標籤新增詞彙表項目。
- `pnpm docs:check-i18n-glossary` 是用於檢查已變更英文文件標題與短內部文件標籤的防護。
- 翻譯記憶位於發布 repo 中產生的 `docs/.i18n/*.tm.jsonl` 檔案。
- 請參閱 `docs/.i18n/README.md`。

116
docs/zh-TW/auth-credential-semantics.md Normal file
View File

@ -0,0 +1,116 @@
---
read_when:
- 處理身分驗證設定檔解析或憑證路由
- 偵錯模型身分驗證失敗或設定檔順序
summary: 身分驗證設定檔的標準憑證適用條件與解析語意
title: 驗證憑證語意
x-i18n:
generated_at: "2026-04-30T02:44:44Z"
model: gpt-5.5
provider: openai
source_hash: 0525a71d3f08b7aa95e2f06acc6c23d87cd92d6b5fe4fc050ecf2b7caff84b3f
source_path: auth-credential-semantics.md
workflow: 16
---
本文件定義下列各處使用的標準認證資料資格與解析語意：
- `resolveAuthProfileOrder`
- `resolveApiKeyForProfile`
- `models status --probe`
- `doctor-auth`
目標是讓選擇時與執行階段行為保持一致。
## 穩定的探測原因代碼
- `ok`
- `excluded_by_auth_order`
- `missing_credential`
- `invalid_expires`
- `expired`
- `unresolved_ref`
- `no_model`
## 權杖認證資料
權杖認證資料（`type: "token"`）支援內嵌 `token` 和/或 `tokenRef`。
### 資格規則
1. 當 `token` 和 `tokenRef` 兩者皆不存在時，權杖設定檔不符合資格。
2. `expires` 是選用項。
3. 如果存在 `expires`，它必須是大於 `0` 的有限數字。
4. 如果 `expires` 無效（`NaN`、`0`、負數、非有限值或型別錯誤），設定檔不符合資格，原因為 `invalid_expires`。
5. 如果 `expires` 是過去時間，設定檔不符合資格，原因為 `expired`。
6. `tokenRef` 不會略過 `expires` 驗證。
### 解析規則
1. 解析器對 `expires` 的語意與資格語意相符。
2. 對符合資格的設定檔，權杖內容可從內嵌值或 `tokenRef` 解析。
3. 無法解析的參照會在 `models status --probe` 輸出中產生 `unresolved_ref`。
## 代理程式複本可攜性
代理程式驗證繼承採用讀穿模式。當代理程式沒有本機設定檔時，
它可在執行階段從預設/主要代理程式儲存區解析設定檔，而不需將
秘密內容複製到自己的 `auth-profiles.json`。
明確複製流程（例如 `openclaw agents add`）會使用此可攜性政策：
- `api_key` 設定檔可攜，除非 `copyToAgents: false`。
- `token` 設定檔可攜，除非 `copyToAgents: false`。
- `oauth` 設定檔預設不可攜，因為重新整理權杖可能是
單次使用或對輪替敏感。
- 由提供者擁有的 OAuth 流程只有在已知可安全跨代理程式
複製重新整理內容時，才能以 `copyToAgents: true` 選擇加入。
不可攜設定檔仍可透過讀穿繼承使用，除非目標代理程式
另外登入並建立自己的本機設定檔。
## 明確驗證順序篩選
- 當為某個提供者設定 `auth.order.<provider>` 或驗證儲存區順序覆寫時，
`models status --probe` 只會探測仍保留在該提供者已解析驗證順序中的
設定檔 ID。
- 該提供者的已儲存設定檔若從明確順序中省略，
之後不會被靜默嘗試。探測輸出會以
`reasonCode: excluded_by_auth_order` 回報，詳細資訊為
`Excluded by auth.order for this provider.`
## 探測目標解析
- 探測目標可以來自驗證設定檔、環境認證資料或
`models.json`。
- 如果提供者具有認證資料，但 OpenClaw 無法為其解析可探測的模型
候選項，`models status --probe` 會回報 `status: no_model`，並帶有
`reasonCode: no_model`。
## 外部 CLI 認證資料探索
- 由外部 CLI 擁有的僅執行階段認證資料，只會在
提供者、執行階段或驗證設定檔屬於目前操作範圍時探索，或在
該外部來源的已儲存本機設定檔已存在時探索。
- 唯讀/狀態路徑會傳入 `allowKeychainPrompt: false`；它們只使用檔案支援的
外部 CLI 認證資料，且不會讀取或重用 macOS Keychain 結果。
## OAuth SecretRef 政策防護
- SecretRef 輸入僅適用於靜態認證資料。
- 如果設定檔認證資料是 `type: "oauth"`，則該設定檔認證資料內容不支援 SecretRef 物件。
- 如果 `auth.profiles.<id>.mode` 是 `"oauth"`，則會拒絕該設定檔使用由 SecretRef 支援的 `keyRef`/`tokenRef` 輸入。
- 違規會在啟動/重新載入驗證解析路徑中造成硬性失敗。
## 舊版相容訊息
為了維持腳本相容性，探測錯誤會讓第一行保持不變：
`Auth profile credentials are missing or expired.`
後續行可加入適合閱讀的詳細資訊與穩定原因代碼。
## 相關
- [秘密管理](/zh-TW/gateway/secrets)
- [驗證儲存](/zh-TW/concepts/oauth)

18
docs/zh-TW/automation/auth-monitoring.md Normal file
View File

@ -0,0 +1,18 @@
---
summary: 重新導向至 /gateway/authentication
title: 身分驗證監控
x-i18n:
generated_at: "2026-04-30T02:44:25Z"
model: gpt-5.5
provider: openai
source_hash: d0bb68c2881911afc634aaba017444a5a8356f4cc519f0a2b5e415ff9ad739f3
source_path: automation/auth-monitoring.md
workflow: 16
---
身份驗證監控位於 [身份驗證](/zh-TW/gateway/authentication) 下。
## 相關內容
- [自動化疑難排解](/zh-TW/automation/cron-jobs)
- [掛鉤](/zh-TW/automation/hooks)

19
docs/zh-TW/automation/clawflow.md Normal file
View File

@ -0,0 +1,19 @@
---
summary: 重新導向至任務流程
title: ClawFlow
x-i18n:
generated_at: "2026-04-30T02:44:25Z"
model: gpt-5.5
provider: openai
source_hash: dec1ddc0e784b4ad49d0f5e5a8e332032e40281b81fe27de99363178ff8d3272
source_path: automation/clawflow.md
workflow: 16
---
ClawFlow 已重新命名為 [任務流程](/zh-TW/automation/taskflow)。
## 相關
- [任務流程](/zh-TW/automation/taskflow)
- [常設指令](/zh-TW/automation/standing-orders)
- [掛鉤](/zh-TW/automation/hooks)

489
docs/zh-TW/automation/cron-jobs.md Normal file
View File

@ -0,0 +1,489 @@
---
read_when:
- 排程背景作業或喚醒
- 將外部觸發器（Webhook、Gmail）接入 OpenClaw
- 為排程任務決定使用 Heartbeat 還是 Cron
sidebarTitle: Scheduled tasks
summary: Gateway 排程器的排程作業、Webhook 和 Gmail PubSub 觸發器
title: 排程任務
x-i18n:
generated_at: "2026-04-30T02:44:43Z"
model: gpt-5.5
provider: openai
source_hash: 021e623bdea786178e0948e9905360c897c26d31fdf866e9af8cfc9538968d60
source_path: automation/cron-jobs.md
workflow: 16
---
Cron 是 Gateway 的內建排程器。它會持久化作業、在正確時間喚醒代理，並可將輸出送回聊天頻道或 Webhook 端點。
## 快速開始
<Steps>
<Step title="新增一次性提醒">
```bash
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: check the cron docs draft" \
--wake now \
--delete-after-run
```
</Step>
<Step title="檢查你的作業">
```bash
openclaw cron list
openclaw cron show <job-id>
```
</Step>
<Step title="查看執行歷程">
```bash
openclaw cron runs --id <job-id>
```
</Step>
</Steps>
## Cron 的運作方式
- Cron 在 **Gateway** 程序內執行（不是在模型內）。
- 作業定義會持久化在 `~/.openclaw/cron/jobs.json`，因此重新啟動不會遺失排程。
- 執行階段狀態會持久化在旁邊的 `~/.openclaw/cron/jobs-state.json`。如果你在 git 中追蹤 cron 定義，請追蹤 `jobs.json`，並將 `jobs-state.json` 加入 gitignore。
- 分離後，較舊的 OpenClaw 版本可以讀取 `jobs.json`，但可能會將作業視為全新，因為執行階段欄位現在位於 `jobs-state.json`。
- 當 Gateway 正在執行或已停止時編輯 `jobs.json`，OpenClaw 會比較已變更的排程欄位與待執行的執行階段時段中繼資料，並清除過期的 `nextRunAtMs` 值。單純格式化或只變更鍵順序的重寫，會保留待執行時段。
- 所有 cron 執行都會建立[背景任務](/zh-TW/automation/tasks)記錄。
- Gateway 啟動時，逾期的隔離代理回合作業會被重新排程到頻道連線視窗之外，而不是立即重播，因此 Discord/Telegram 啟動與原生命令設定在重新啟動後仍能保持回應。
- 一次性作業（`--at`）預設會在成功後自動刪除。
- 隔離 cron 執行完成時，會盡力關閉其 `cron:<jobId>` 工作階段追蹤的瀏覽器分頁/程序，因此分離的瀏覽器自動化不會留下孤立程序。
- 隔離 cron 執行也會防止過期的確認回覆。如果第一個結果只是暫時狀態更新（`on it`、`pulling everything together` 及類似提示），且沒有後代子代理執行仍負責最終答案，OpenClaw 會在交付前重新提示一次以取得實際結果。
- 隔離 cron 執行會優先使用嵌入式執行中的結構化執行拒絕中繼資料，然後退回到已知的最終摘要/輸出標記，例如 `SYSTEM_RUN_DENIED` 和 `INVALID_REQUEST`，因此被封鎖的命令不會被回報為成功執行。
- 隔離 cron 執行也會將執行層級的代理失敗視為作業錯誤，即使沒有產生回覆酬載也是如此，因此模型/供應商失敗會增加錯誤計數並觸發失敗通知，而不是將作業清除為成功。
- 當隔離代理回合作業達到 `timeoutSeconds` 時，cron 會中止底層代理執行，並給它一小段清理視窗。如果執行未能排空，Gateway 擁有的清理會在 cron 記錄逾時前強制清除該執行的工作階段所有權，因此佇列中的聊天工作不會被留在過期的處理工作階段後面。
<a id="maintenance"></a>
<Note>
cron 的任務協調先由執行階段擁有，其次才由持久歷史支援：只要 cron 執行階段仍將該作業追蹤為執行中，即使仍存在舊的子工作階段列，作用中的 cron 任務也會保持即時狀態。一旦執行階段停止擁有該作業且 5 分鐘寬限期到期，維護檢查就會查詢持久化執行記錄與作業狀態，以尋找相符的 `cron:<jobId>:<startedAt>` 執行。如果該持久歷史顯示終止結果，任務帳本會據此完成；否則 Gateway 擁有的維護可以將任務標記為 `lost`。離線 CLI 稽核可以從持久歷史復原，但不會將它自己的空白處理程序內作用中作業集合視為 Gateway 擁有的 cron 執行已消失的證明。
</Note>
## 排程類型
| 類型 | CLI 旗標 | 說明 |
| ------- | --------- | ------------------------------------------------------- |
| `at` | `--at` | 一次性時間戳記（ISO 8601 或像 `20m` 這樣的相對時間） |
| `every` | `--every` | 固定間隔 |
| `cron` | `--cron` | 5 欄位或 6 欄位 cron 運算式，可搭配選用的 `--tz` |
沒有時區的時間戳記會被視為 UTC。若要依本地牆鐘時間排程，請加上 `--tz America/New_York`。
整點重複運算式會自動錯開最多 5 分鐘，以降低負載尖峰。使用 `--exact` 強制精準時間，或使用 `--stagger 30s` 指定明確視窗。
### 日期與星期使用 OR 邏輯
Cron 運算式由 [croner](https://github.com/Hexagon/croner) 解析。當日期與星期欄位都不是萬用字元時，croner 會在**任一**欄位符合時匹配，而不是兩者都符合。這是標準 Vixie cron 行為。
```
# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual: "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1
```
這會每月觸發約 5 到 6 次，而不是每月 0 到 1 次。OpenClaw 在此使用 Croner 的預設 OR 行為。若要要求兩個條件都成立，請使用 Croner 的 `+` 星期修飾符（`0 9 15 * +1`），或在其中一個欄位上排程，並在作業的提示或命令中保護另一個條件。
## 執行樣式
| 樣式 | `--session` 值 | 執行位置 | 最適合 |
| --------------- | ------------------- | ------------------------ | ------------------------------- |
| 主工作階段 | `main` | 下一個 Heartbeat 回合 | 提醒、系統事件 |
| 隔離 | `isolated` | 專用 `cron:<jobId>` | 報告、背景雜務 |
| 目前工作階段 | `current` | 建立時繫結 | 具情境感知的重複工作 |
| 自訂工作階段 | `session:custom-id` | 持久化命名工作階段 | 以歷史為基礎的工作流程 |
<AccordionGroup>
<Accordion title="主工作階段、隔離與自訂">
**主工作階段**作業會將系統事件加入佇列，並可選擇喚醒 Heartbeat（`--wake now` 或 `--wake next-heartbeat`）。這些系統事件不會延長目標工作階段的每日/閒置重設新鮮度。**隔離**作業會以全新工作階段執行專用代理回合。**自訂工作階段**（`session:xxx`）會跨執行持久化情境，啟用像每日站會這類以先前摘要為基礎的工作流程。
</Accordion>
<Accordion title="隔離作業中「全新工作階段」的含義">
對隔離作業而言，「全新工作階段」表示每次執行都有新的逐字稿/工作階段 ID。OpenClaw 可以攜帶安全偏好，例如思考/快速/詳細設定、標籤，以及明確由使用者選擇的模型/驗證覆寫，但不會從較舊的 cron 列繼承環境對話情境：頻道/群組路由、傳送或佇列政策、提升權限、來源，或 ACP 執行階段繫結。當重複作業應刻意以同一個對話情境為基礎時，請使用 `current` 或 `session:<id>`。
</Accordion>
<Accordion title="執行階段清理">
對隔離作業而言，執行階段拆除現在包含該 cron 工作階段的盡力瀏覽器清理。清理失敗會被忽略，因此實際 cron 結果仍會優先。
隔離 cron 執行也會透過共用的執行階段清理路徑，處置為該作業建立的任何內建 MCP 執行階段執行個體。這符合主工作階段與自訂工作階段 MCP 用戶端的拆除方式，因此隔離 cron 作業不會在多次執行之間洩漏 stdio 子程序或長時間存在的 MCP 連線。
</Accordion>
<Accordion title="子代理與 Discord 交付">
當隔離 cron 執行協調子代理時，交付也會優先使用最終後代輸出，而不是過期的父層暫時文字。如果後代仍在執行，OpenClaw 會抑制該部分父層更新，而不是公告它。
對於純文字 Discord 公告目標，OpenClaw 只會傳送一次標準最終助理文字，而不是同時重播串流/中間文字酬載與最終答案。媒體與結構化 Discord 酬載仍會作為個別酬載交付，因此附件和元件不會被丟棄。
</Accordion>
</AccordionGroup>
### 隔離作業的酬載選項
<ParamField path="--message" type="string" required>
提示文字（隔離作業必填）。
</ParamField>
<ParamField path="--model" type="string">
模型覆寫；使用為該作業選取的允許模型。
</ParamField>
<ParamField path="--thinking" type="string">
思考層級覆寫。
</ParamField>
<ParamField path="--light-context" type="boolean">
跳過工作區啟動檔案注入。
</ParamField>
<ParamField path="--tools" type="string">
限制作業可使用的工具，例如 `--tools exec,read`。
</ParamField>
`--model` 會使用選取的允許模型作為該作業的主要模型。這與聊天工作階段的 `/model` 覆寫不同：當作業主要模型失敗時，已設定的備援鏈仍會套用。如果要求的模型不被允許或無法解析，cron 會以明確的驗證錯誤使執行失敗，而不是靜默退回到作業的代理/預設模型選擇。
Cron 作業也可以攜帶酬載層級的 `fallbacks`。存在時，該清單會取代作業的已設定備援鏈。當你想要嚴格的 cron 執行、只嘗試所選模型時，請在作業酬載/API 中使用 `fallbacks: []`。如果作業有 `--model`，但沒有酬載或已設定的備援，OpenClaw 會傳遞明確的空白備援覆寫，因此代理主要模型不會被附加為隱藏的額外重試目標。
隔離作業的模型選擇優先順序如下：
1. Gmail hook 模型覆寫（當執行來自 Gmail 且該覆寫被允許時）
2. 每個作業酬載的 `model`
3. 使用者選取且已儲存的 cron 工作階段模型覆寫
4. 代理/預設模型選擇
快速模式也會遵循解析出的即時選擇。如果選取的模型設定有 `params.fastMode`，隔離 cron 預設會使用它。已儲存的工作階段 `fastMode` 覆寫仍會在任一方向上優先於設定。
如果隔離執行遇到即時模型切換交接，cron 會使用切換後的供應商/模型重試，並在重試前為作用中執行持久化該即時選擇。當切換也攜帶新的驗證設定檔時，cron 也會為作用中執行持久化該驗證設定檔覆寫。重試有界限：初始嘗試加上 2 次切換重試後，cron 會中止，而不是永遠迴圈。
在隔離 cron 執行進入代理執行器前，OpenClaw 會檢查已設定 `api: "ollama"` 和 `api: "openai-completions"` 供應商的可到達本地供應商端點，其 `baseUrl` 為回送、私有網路或 `.local`。如果該端點停機，執行會被記錄為 `skipped`，並附上清楚的供應商/模型錯誤，而不是開始模型呼叫。端點結果會快取 5 分鐘，因此使用同一個停機本地 Ollama、vLLM、SGLang 或 LM Studio 伺服器的許多到期作業，會共用一次小型探測，而不是造成請求風暴。跳過的供應商預檢執行不會增加執行錯誤退避；當你想要重複跳過通知時，請啟用 `failureAlert.includeSkipped`。
## 交付與輸出
| 模式 | 發生的事 |
| ---------- | ------------------------------------------------------------------- |
| `announce` | 如果代理未傳送，則以備援方式將最終文字交付給目標 |
| `webhook` | 將完成事件酬載 POST 到 URL |
| `none` | 沒有執行器備援交付 |
使用 `--announce --channel telegram --to "-1001234567890"` 進行頻道傳遞。對於 Telegram 論壇主題，使用 `-1001234567890:topic:123`；直接 RPC/設定呼叫端也可以將 `delivery.threadId` 以字串或數字傳入。Slack/Discord/Mattermost 目標應使用明確前綴（`channel:<id>`、`user:<id>`）。Matrix 房間 ID 區分大小寫；請使用確切房間 ID 或 Matrix 提供的 `room:!room:server` 形式。
對於隔離作業，聊天傳遞是共享的。如果有聊天路由可用，即使作業使用 `--no-deliver`，代理也可以使用 `message` 工具。如果代理傳送到已設定/目前的目標，OpenClaw 會略過備援公告。否則，`announce`、`webhook` 與 `none` 只控制執行器在代理回合後如何處理最終回覆。
當代理從作用中的聊天建立隔離提醒時，OpenClaw 會儲存保留的即時傳遞目標，用於備援公告路由。內部工作階段鍵可能是小寫；當目前聊天情境可用時，提供者傳遞目標不會從這些鍵重建。
失敗通知會走獨立的目的地路徑：
- `cron.failureDestination` 設定失敗通知的全域預設值。
- `job.delivery.failureDestination` 會針對每個作業覆寫該值。
- 如果兩者都未設定，且作業已經透過 `announce` 傳遞，失敗通知現在會退回到該主要公告目標。
- 除非主要傳遞模式是 `webhook`，否則 `delivery.failureDestination` 只支援 `sessionTarget="isolated"` 作業。
- `failureAlert.includeSkipped: true` 會讓作業或全域 cron 警示政策納入重複的略過執行警示。略過的執行會保留獨立的連續略過計數器，因此不會影響執行錯誤退避。
## CLI 範例
<Tabs>
<Tab title="一次性提醒">
```bash
openclaw cron add \
--name "Calendar check" \
--at "20m" \
--session main \
--system-event "Next heartbeat: check calendar." \
--wake now
```
</Tab>
<Tab title="重複隔離作業">
```bash
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize overnight updates." \
--announce \
--channel slack \
--to "channel:C1234567890"
```
</Tab>
<Tab title="模型與思考覆寫">
```bash
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 1" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Weekly deep analysis of project progress." \
--model "opus" \
--thinking high \
--announce
```
</Tab>
</Tabs>
## Webhook
Gateway 可以公開 HTTP Webhook 端點供外部觸發。在設定中啟用：
```json5
{
hooks: {
enabled: true,
token: "shared-secret",
path: "/hooks",
},
}
```
### 驗證
每個請求都必須透過標頭包含 hook 權杖：
- `Authorization: Bearer <token>`（建議）
- `x-openclaw-token: <token>`
查詢字串權杖會被拒絕。
<AccordionGroup>
<Accordion title="POST /hooks/wake">
為主要工作階段排入系統事件：
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"text":"New email received","mode":"now"}'
```
<ParamField path="text" type="string" required>
事件描述。
</ParamField>
<ParamField path="mode" type="string" default="now">
`now` 或 `next-heartbeat`。
</ParamField>
</Accordion>
<Accordion title="POST /hooks/agent">
執行隔離代理回合：
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
```
欄位：`message`（必填）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`fallbacks`、`thinking`、`timeoutSeconds`。
</Accordion>
<Accordion title="對應 hook（POST /hooks/<name>）">
自訂 hook 名稱會透過設定中的 `hooks.mappings` 解析。對應可以使用範本或程式碼轉換，將任意酬載轉換成 `wake` 或 `agent` 動作。
</Accordion>
</AccordionGroup>
<Warning>
將 hook 端點限制在 loopback、tailnet 或受信任的反向代理後方。
- 使用專用 hook 權杖；不要重複使用 Gateway 驗證權杖。
- 將 `hooks.path` 保持在專用子路徑；`/` 會被拒絕。
- 設定 `hooks.allowedAgentIds` 以限制明確的 `agentId` 路由。
- 除非你需要呼叫端選擇工作階段，否則請保持 `hooks.allowRequestSessionKey=false`。
- 如果啟用 `hooks.allowRequestSessionKey`，也請設定 `hooks.allowedSessionKeyPrefixes` 以限制允許的工作階段鍵形狀。
- Hook 酬載預設會以安全邊界包裝。
</Warning>
## Gmail PubSub 整合
透過 Google PubSub 將 Gmail 收件匣觸發器接到 OpenClaw。
<Note>
**先決條件：** `gcloud` CLI、`gog`（gogcli）、已啟用的 OpenClaw hook、用於公開 HTTPS 端點的 Tailscale。
</Note>
### 精靈設定（建議）
```bash
openclaw webhooks gmail setup --account openclaw@gmail.com
```
這會寫入 `hooks.gmail` 設定、啟用 Gmail 預設集，並使用 Tailscale Funnel 作為推送端點。
### Gateway 自動啟動
當 `hooks.enabled=true` 且已設定 `hooks.gmail.account` 時，Gateway 會在啟動時啟動 `gog gmail watch serve`，並自動續訂 watch。設定 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可選擇退出。
### 手動一次性設定
<Steps>
<Step title="選取 GCP 專案">
選取擁有 `gog` 所使用 OAuth 用戶端的 GCP 專案：
```bash
gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
```
</Step>
<Step title="建立主題並授予 Gmail 推送存取權">
```bash
gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
--member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
--role=roles/pubsub.publisher
```
</Step>
<Step title="啟動 watch">
```bash
gog gmail watch start \
--account openclaw@gmail.com \
--label INBOX \
--topic projects/<project-id>/topics/gog-gmail-watch
```
</Step>
</Steps>
### Gmail 模型覆寫
```json5
{
hooks: {
gmail: {
model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
thinking: "off",
},
},
}
```
## 管理作業
```bash
# List all jobs
openclaw cron list
# Show one job, including resolved delivery route
openclaw cron show <jobId>
# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
# Force run a job now
openclaw cron run <jobId>
# Run only if due
openclaw cron run <jobId> --due
# View run history
openclaw cron runs --id <jobId> --limit 50
# Delete a job
openclaw cron remove <jobId>
# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
<Note>
模型覆寫注意事項：
- `openclaw cron add|edit --model ...` 會變更作業選取的模型。
- 如果允許該模型，該確切的提供者/模型會送達隔離代理執行。
- 如果不允許或無法解析，cron 會以明確的驗證錯誤讓該次執行失敗。
- 已設定的備援鏈仍會套用，因為 cron `--model` 是作業主要模型，而不是工作階段 `/model` 覆寫。
- 酬載 `fallbacks` 會取代該作業已設定的備援；`fallbacks: []` 會停用備援，並讓執行變成嚴格模式。
- 沒有明確或已設定備援清單的純 `--model`，不會靜默接續到代理主要模型作為額外重試目標。
</Note>
## 設定
```json5
{
cron: {
enabled: true,
store: "~/.openclaw/cron/jobs.json",
maxConcurrentRuns: 1,
retry: {
maxAttempts: 3,
backoffMs: [60000, 120000, 300000],
retryOn: ["rate_limit", "overloaded", "network", "server_error"],
},
webhookToken: "replace-with-dedicated-webhook-token",
sessionRetention: "24h",
runLog: { maxBytes: "2mb", keepLines: 2000 },
},
}
```
`maxConcurrentRuns` 會限制排程 cron 分派與隔離代理回合執行。隔離 cron 代理回合會在內部使用佇列的專用 `cron-nested` 執行通道，因此提高此值可讓獨立的 cron LLM 執行並行推進，而不只是啟動其外層 cron 包裝器。共享的非 cron `nested` 通道不會因為此設定而加寬。
執行階段狀態 sidecar 會從 `cron.store` 推導：像 `~/clawd/cron/jobs.json` 這樣的 `.json` 儲存會使用 `~/clawd/cron/jobs-state.json`，而沒有 `.json` 後綴的儲存路徑會附加 `-state.json`。
如果你手動編輯 `jobs.json`，請不要將 `jobs-state.json` 納入原始碼控制。OpenClaw 會使用該 sidecar 保存待處理槽位、作用中標記、上次執行中繼資料，以及告知排程器外部編輯過的作業何時需要新的 `nextRunAtMs` 的排程身分。
停用 cron：`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`。
<AccordionGroup>
<Accordion title="重試行為">
**一次性重試**：暫時性錯誤（速率限制、過載、網路、伺服器錯誤）最多重試 3 次，並使用指數退避。永久錯誤會立即停用。
**重複重試**：重試之間使用指數退避（30 秒到 60 分鐘）。下一次成功執行後會重設退避。
</Accordion>
<Accordion title="維護">
`cron.sessionRetention`（預設 `24h`）會修剪隔離執行工作階段項目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 會自動修剪執行記錄檔。
</Accordion>
</AccordionGroup>
## 疑難排解
### 命令階梯
```bash
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor
```
<AccordionGroup>
<Accordion title="Cron 未觸發">
- 檢查 `cron.enabled` 與 `OPENCLAW_SKIP_CRON` 環境變數。
- 確認 Gateway 正在持續執行。
- 對於 `cron` 排程，驗證時區（`--tz`）與主機時區。
- 執行輸出中的 `reason: not-due` 表示手動執行是以 `openclaw cron run <jobId> --due` 檢查，且作業尚未到期。
</Accordion>
<Accordion title="Cron 已觸發但沒有傳遞">
- 傳遞模式 `none` 表示不預期有執行器備援傳送。當聊天路由可用時，代理仍可使用 `message` 工具直接傳送。
- 傳遞目標缺失/無效（`channel`/`to`）表示已略過外送。
- 對於 Matrix，複製或舊版作業若有小寫的 `delivery.to` 房間 ID，可能會失敗，因為 Matrix 房間 ID 區分大小寫。請將作業編輯為 Matrix 提供的確切 `!room:server` 或 `room:!room:server` 值。
- 頻道驗證錯誤（`unauthorized`、`Forbidden`）表示傳遞已被憑證封鎖。
- 如果隔離執行只回傳靜默權杖（`NO_REPLY` / `no_reply`），OpenClaw 會抑制直接外送傳遞，也會抑制備援佇列摘要路徑，因此不會有任何內容傳回聊天。
- 如果代理應自行傳訊給使用者，請檢查作業是否有可用路由（`channel: "last"` 搭配先前聊天，或明確的頻道/目標）。
</Accordion>
<Accordion title="Cron 或 Heartbeat 似乎防止 /new-style 輪替">
- 每日與閒置重設的新鮮度不是依據 `updatedAt`；請參閱[工作階段管理](/zh-TW/concepts/session#session-lifecycle)。
- Cron 喚醒、Heartbeat 執行、exec 通知，以及 Gateway 簿記可能會為了路由/狀態而更新工作階段資料列，但它們不會延長 `sessionStartedAt` 或 `lastInteractionAt`。
- 對於在這些欄位存在之前建立的舊版資料列，若檔案仍可用，OpenClaw 可以從逐行 JSONL 轉錄稿的工作階段標頭復原 `sessionStartedAt`。沒有 `lastInteractionAt` 的舊版閒置資料列會使用該復原的開始時間作為其閒置基準。
</Accordion>
<Accordion title="時區注意事項">
- 未使用 `--tz` 的 Cron 會使用 Gateway 主機時區。
- 未指定時區的 `at` 排程會被視為 UTC。
- Heartbeat `activeHours` 會使用已設定的時區解析。
</Accordion>
</AccordionGroup>
## 相關
- [自動化與任務](/zh-TW/automation) — 所有自動化機制一覽
- [背景任務](/zh-TW/automation/tasks) — Cron 執行的任務台帳
- [Heartbeat](/zh-TW/gateway/heartbeat) — 定期的主工作階段回合
- [時區](/zh-TW/concepts/timezone) — 時區設定

18
docs/zh-TW/automation/cron-vs-heartbeat.md Normal file
View File

@ -0,0 +1,18 @@
---
summary: 重新導向至 /automation
title: Cron 與 Heartbeat
x-i18n:
generated_at: "2026-04-30T02:44:28Z"
model: gpt-5.5
provider: openai
source_hash: 4a4951f926f9050a9bd33b338cf4cd1869d73b9c3e7222349ea8265b959f41b4
source_path: automation/cron-vs-heartbeat.md
workflow: 16
---
Cron 與 Heartbeat 的決策指南位於 [自動化與任務](/zh-TW/automation) 下。
## 相關內容
- [排程任務](/zh-TW/automation/cron-jobs)
- [背景任務](/zh-TW/automation/tasks)

18
docs/zh-TW/automation/gmail-pubsub.md Normal file
View File

@ -0,0 +1,18 @@
---
summary: 重新導向至 /automation/cron-jobs
title: Gmail 發布/訂閱
x-i18n:
generated_at: "2026-04-30T02:44:41Z"
model: gpt-5.5
provider: openai
source_hash: 4462fb58fa73ac3eb3d8d2994760b96424dcad3f1543e8ff10222936f6c54caf
source_path: automation/gmail-pubsub.md
workflow: 16
---
此頁面已移至 [排程任務](/zh-TW/automation/cron-jobs#gmail-pubsub-integration)。請參閱 [排程任務](/zh-TW/automation/cron-jobs#gmail-pubsub-integration) 以取得 Gmail PubSub 文件。
## 相關
- [Webhook](/zh-TW/automation/cron-jobs)
- [自動化疑難排解](/zh-TW/automation/cron-jobs)

332
docs/zh-TW/automation/hooks.md Normal file
View File

@ -0,0 +1,332 @@
---
read_when:
- 你需要針對 /new、/reset、/stop 和代理程式生命週期事件的事件驅動自動化
- 你想要建置、安裝或偵錯鉤子
summary: 掛鉤：用於命令與生命週期事件的事件驅動自動化
title: 鉤子
x-i18n:
generated_at: "2026-04-30T02:44:59Z"
model: gpt-5.5
provider: openai
source_hash: a6c567ab79fbff8228d174816e9fb4613f0544ea15a99b5917190a4066af0f57
source_path: automation/hooks.md
workflow: 16
---
掛鉤是在 Gateway 內部發生事件時執行的小型腳本。它們可以從目錄中探索，並可使用 `openclaw hooks` 檢視。只有在你啟用掛鉤，或設定至少一個掛鉤項目、掛鉤套件、舊版處理常式或額外掛鉤目錄後，Gateway 才會載入內部掛鉤。
OpenClaw 中有兩種掛鉤：
- **內部掛鉤**（本頁）：在代理事件觸發時於 Gateway 內執行，例如 `/new`、`/reset`、`/stop` 或生命週期事件。
- **Webhooks**：外部 HTTP 端點，可讓其他系統觸發 OpenClaw 中的工作。請參閱 [Webhooks](/zh-TW/automation/cron-jobs#webhooks)。
掛鉤也可以封裝在 plugins 內。`openclaw hooks list` 會顯示獨立掛鉤與 plugin 管理的掛鉤。
## 快速開始
```bash
# List available hooks
openclaw hooks list
# Enable a hook
openclaw hooks enable session-memory
# Check hook status
openclaw hooks check
# Get detailed information
openclaw hooks info session-memory
```
## 事件類型
| 事件 | 觸發時機 |
| ------------------------ | ---------------------------------------------------------- |
| `command:new` | 發出 `/new` 命令 |
| `command:reset` | 發出 `/reset` 命令 |
| `command:stop` | 發出 `/stop` 命令 |
| `command` | 任何命令事件（一般監聽器） |
| `session:compact:before` | Compaction 摘要歷程記錄之前 |
| `session:compact:after` | Compaction 完成之後 |
| `session:patch` | 工作階段屬性被修改時 |
| `agent:bootstrap` | 注入工作區啟動程序檔案之前 |
| `gateway:startup` | 頻道啟動且掛鉤載入之後 |
| `gateway:shutdown` | Gateway 關閉開始時 |
| `gateway:pre-restart` | 預期的 Gateway 重新啟動之前 |
| `message:received` | 來自任何頻道的傳入訊息 |
| `message:transcribed` | 音訊轉錄完成之後 |
| `message:preprocessed` | 媒體與連結前處理完成或略過之後 |
| `message:sent` | 傳出訊息已送達 |
## 撰寫掛鉤
### 掛鉤結構
每個掛鉤都是一個包含兩個檔案的目錄：
```
my-hook/
├── HOOK.md # Metadata + documentation
└── handler.ts # Handler implementation
```
### HOOK.md 格式
```markdown
---
name: my-hook
description: "Short description of what this hook does"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
Detailed documentation goes here.
```
**中繼資料欄位**（`metadata.openclaw`）：
| 欄位 | 說明 |
| ---------- | ---------------------------------------------------- |
| `emoji` | CLI 顯示用表情符號 |
| `events` | 要監聽的事件陣列 |
| `export` | 要使用的具名匯出（預設為 `"default"`） |
| `os` | 必要平台（例如 `["darwin", "linux"]`） |
| `requires` | 必要的 `bins`、`anyBins`、`env` 或 `config` 路徑 |
| `always` | 略過資格檢查（布林值） |
| `install` | 安裝方法 |
### 處理常式實作
```typescript
const handler = async (event) => {
if (event.type !== "command" || event.action !== "new") {
return;
}
console.log(`[my-hook] New command triggered`);
// Your logic here
// Optionally send message to user
event.messages.push("Hook executed!");
};
export default handler;
```
每個事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（推入即可傳送給使用者）以及 `context`（事件專屬資料）。代理與工具 plugin 掛鉤內容也可以包含 `trace`，這是一個唯讀、相容 W3C 的診斷追蹤內容，plugins 可將其傳入結構化記錄，以便進行 OTEL 關聯。
### 事件內容重點
**命令事件**（`command:new`、`command:reset`）：`context.sessionEntry`、`context.previousSessionEntry`、`context.commandSource`、`context.workspaceDir`、`context.cfg`。
**訊息事件**（`message:received`）：`context.from`、`context.content`、`context.channelId`、`context.metadata`（供應商專屬資料，包含 `senderId`、`senderName`、`guildId`）。
**訊息事件**（`message:sent`）：`context.to`、`context.content`、`context.success`、`context.channelId`。
**訊息事件**（`message:transcribed`）：`context.transcript`、`context.from`、`context.channelId`、`context.mediaPath`。
**訊息事件**（`message:preprocessed`）：`context.bodyForAgent`（最終強化後的本文）、`context.from`、`context.channelId`。
**啟動程序事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可變陣列）、`context.agentId`。
**工作階段修補事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（僅變更的欄位）、`context.cfg`。只有具權限的用戶端可以觸發修補事件。
**Compaction 事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 會新增 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。
`command:stop` 會觀察使用者發出 `/stop`；它是取消/命令生命週期，不是代理完成閘門。需要檢查自然最終答案並要求代理再執行一次的 plugins，應改用型別化 plugin 掛鉤 `before_agent_finalize`。請參閱 [Plugin 掛鉤](/zh-TW/plugins/hooks)。
**Gateway 生命週期事件**：`gateway:shutdown` 包含 `reason` 與 `restartExpectedMs`，並在 Gateway 關閉開始時觸發。`gateway:pre-restart` 包含相同內容，但只會在關閉屬於預期重新啟動的一部分，且提供有限的 `restartExpectedMs` 值時觸發。關閉期間，每個生命週期掛鉤的等待都是盡力而為且有界限，因此即使處理常式停滯，關閉仍會繼續。
## 掛鉤探索
掛鉤會從這些目錄探索，順序為覆寫優先順序由低到高：
1. **內建掛鉤**：隨 OpenClaw 發佈
2. **Plugin 掛鉤**：封裝在已安裝 plugins 內的掛鉤
3. **受管理掛鉤**：`~/.openclaw/hooks/`（使用者安裝，跨工作區共用）。來自 `hooks.internal.load.extraDirs` 的額外目錄共用此優先順序。
4. **工作區掛鉤**：`<workspace>/hooks/`（每個代理專屬，預設停用，直到明確啟用）
工作區掛鉤可以新增掛鉤名稱，但無法覆寫同名的內建、受管理或 plugin 提供的掛鉤。
Gateway 會在內部掛鉤完成設定之前，於啟動時略過內部掛鉤探索。使用 `openclaw hooks enable <name>` 啟用內建或受管理掛鉤、安裝掛鉤套件，或設定 `hooks.internal.enabled=true` 以選擇啟用。當你啟用一個具名掛鉤時，Gateway 只會載入該掛鉤的處理常式；`hooks.internal.enabled=true`、額外掛鉤目錄與舊版處理常式會選擇進行廣泛探索。
### 掛鉤套件
掛鉤套件是透過 `package.json` 中的 `openclaw.hooks` 匯出掛鉤的 npm 套件。使用以下命令安裝：
```bash
openclaw plugins install <path-or-spec>
```
Npm 規格僅限登錄檔（套件名稱 + 選用的精確版本或 dist-tag）。Git/URL/file 規格與 semver 範圍會被拒絕。
## 內建掛鉤
| 掛鉤 | 事件 | 功能 |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | 將工作階段內容儲存到 `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | 從 glob 模式注入額外啟動程序檔案 |
| command-logger | `command` | 將所有命令記錄到 `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | Gateway 啟動時執行 `BOOT.md` |
啟用任何內建掛鉤：
```bash
openclaw hooks enable <hook-name>
```
<a id="session-memory"></a>
### session-memory 詳細資訊
擷取最後 15 則使用者/助理訊息，透過 LLM 產生描述性檔名 slug，並使用主機本機日期儲存到 `<workspace>/memory/YYYY-MM-DD-slug.md`。需要設定 `workspace.dir`。
<a id="bootstrap-extra-files"></a>
### bootstrap-extra-files 設定
```json
{
"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
}
}
}
}
}
```
路徑會相對於工作區解析。只會載入可辨識的啟動程序基礎檔名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。
<a id="command-logger"></a>
### command-logger 詳細資訊
將每個斜線命令記錄到 `~/.openclaw/logs/commands.log`。
<a id="boot-md"></a>
### boot-md 詳細資訊
Gateway 啟動時，從作用中工作區執行 `BOOT.md`。
## Plugin 掛鉤
Plugins 可以透過 Plugin SDK 註冊型別化掛鉤以進行更深入整合：攔截工具呼叫、修改提示、控制訊息流程，以及更多功能。當你需要 `before_tool_call`、`before_agent_reply`、`before_install` 或其他程序內生命週期掛鉤時，請使用 plugin 掛鉤。
如需完整的 plugin 掛鉤參考，請參閱 [Plugin 掛鉤](/zh-TW/plugins/hooks)。
## 設定
```json
{
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": { "enabled": true },
"command-logger": { "enabled": false }
}
}
}
}
```
每個掛鉤的環境變數：
```json
{
"hooks": {
"internal": {
"entries": {
"my-hook": {
"enabled": true,
"env": { "MY_CUSTOM_VAR": "value" }
}
}
}
}
}
```
額外掛鉤目錄：
```json
{
"hooks": {
"internal": {
"load": {
"extraDirs": ["/path/to/more/hooks"]
}
}
}
}
```
<Note>
舊版 `hooks.internal.handlers` 陣列設定格式仍支援向後相容性，但新掛鉤應使用以探索為基礎的系統。
</Note>
## CLI 參考
```bash
# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list
# Show detailed info about a hook
openclaw hooks info <hook-name>
# Show eligibility summary
openclaw hooks check
# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>
```
## 最佳實務
- **保持處理常式快速。** 掛鉤會在命令處理期間執行。對耗時工作使用 `void processInBackground(event)` 進行啟動後即不等待。
- **優雅處理錯誤。** 將有風險的操作包在 try/catch 中；不要拋出錯誤，讓其他處理常式可以執行。
- **及早篩選事件。** 如果事件類型/動作不相關，立即傳回。
- **使用特定事件鍵。** 偏好 `"events": ["command:new"]`，而非 `"events": ["command"]`，以降低額外負擔。
## 疑難排解
### 未探索到掛鉤
```bash
# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts
# List all discovered hooks
openclaw hooks list
```
### 掛鉤不符合資格
```bash
openclaw hooks info my-hook
```
檢查是否缺少二進位檔（PATH）、環境變數、設定值或作業系統相容性。
### 掛鉤未執行
1. 確認掛鉤已啟用：`openclaw hooks list`
2. 重新啟動你的 gateway 程序，讓掛鉤重新載入。
3. 檢查 Gateway 記錄：`./scripts/clawlog.sh | grep hook`
## 相關
- [CLI 參考：鉤子](/zh-TW/cli/hooks)
- [Webhook](/zh-TW/automation/cron-jobs#webhooks)
- [Plugin 鉤子](/zh-TW/plugins/hooks) — 行程內 Plugin 生命週期鉤子
- [設定](/zh-TW/gateway/configuration-reference#hooks)

132
docs/zh-TW/automation/index.md Normal file
View File

@ -0,0 +1,132 @@
---
read_when:
- 決定如何使用 OpenClaw 自動化工作
- 在 Heartbeat、Cron、承諾事項、掛鉤與常設指令之間做選擇
- 尋找合適的自動化入口點
summary: 自動化機制概覽：任務、Cron、掛鉤、常設指令，以及 TaskFlow
title: 自動化與任務
x-i18n:
generated_at: "2026-04-30T02:45:11Z"
model: gpt-5.5
provider: openai
source_hash: a2465c39f21db8bcb98f980a2c4b2c03018dddd5f43de59d8bf6ce0d6e97d9ef
source_path: automation/index.md
workflow: 16
---
OpenClaw 會透過任務、排程工作、推斷承諾、事件 Hook 與常設指令在背景執行工作。本頁協助你選擇合適的機制，並了解它們如何彼此配合。
## 快速決策指南
```mermaid
flowchart TD
START([你需要什麼？]) --> Q1{排程工作？}
START --> Q2{追蹤分離的工作？}
START --> Q3{編排多步驟流程？}
START --> Q4{回應生命週期事件？}
START --> Q5{給代理持續性指令？}
START --> Q6{記住自然的後續事項？}
Q1 -->|是| Q1a{精確時間或彈性時間？}
Q1a -->|精確| CRON["排程任務 (Cron)"]
Q1a -->|彈性| HEARTBEAT[Heartbeat]
Q2 -->|是| TASKS[背景任務]
Q3 -->|是| FLOW[Task Flow]
Q4 -->|是| HOOKS[Hooks]
Q5 -->|是| SO[常設命令]
Q6 -->|是| COMMITMENTS[推斷承諾]
```
| 使用案例 | 建議 | 原因 |
| --------------------------------------- | ---------------------- | ------------------------------------------------ |
| 每天上午 9 點準時傳送報告 | 排程任務 (Cron) | 精確時間、隔離執行 |
| 20 分鐘後提醒我 | 排程任務 (Cron) | 具有精準時間的一次性任務 (`--at`) |
| 執行每週深度分析 | 排程任務 (Cron) | 獨立任務，可使用不同模型 |
| 每 30 分鐘檢查收件匣 | Heartbeat | 與其他檢查批次處理，具備情境感知 |
| 監控日曆中的即將到來事件 | Heartbeat | 很自然適合週期性覺察 |
| 在提到的面試後追蹤確認 | 推斷承諾 | 類似記憶的後續追蹤，沒有精確提醒請求 |
| 根據使用者情境進行溫和關懷確認 | 推斷承諾 | 限定於同一代理與頻道 |
| 檢查子代理或 ACP 執行狀態 | 背景任務 | 任務帳本會追蹤所有分離的工作 |
| 稽核執行了什麼以及何時執行 | 背景任務 | `openclaw tasks list` 與 `openclaw tasks audit` |
| 多步驟研究後彙整摘要 | Task Flow | 具備修訂追蹤的持久編排 |
| 在工作階段重設時執行腳本 | Hooks | 事件驅動，會在生命週期事件觸發 |
| 在每次工具呼叫時執行程式碼 | Plugin hooks | 程序內 Hook 可攔截工具呼叫 |
| 回覆前一律檢查合規性 | 常設命令 | 自動注入每個工作階段 |
### 排程任務 (Cron) 與 Heartbeat
| 面向 | 排程任務 (Cron) | Heartbeat |
| --------------- | ----------------------------------- | ------------------------------------- |
| 時間 | 精確（cron 表達式、一次性） | 近似（預設每 30 分鐘） |
| 工作階段情境 | 全新（隔離）或共享 | 完整主工作階段情境 |
| 任務紀錄 | 一律建立 | 從不建立 |
| 交付 | 頻道、Webhook 或靜默 | 在主工作階段內內嵌 |
| 最適合 | 報告、提醒、背景工作 | 收件匣檢查、日曆、通知 |
需要精確時間或隔離執行時，請使用排程任務 (Cron)。當工作受益於完整工作階段情境，而且近似時間即可時，請使用 Heartbeat。
## 核心概念
### 排程任務 (cron)
Cron 是 Gateway 內建的精確時間排程器。它會持久保存工作、在正確時間喚醒代理，並可將輸出交付到聊天頻道或 Webhook 端點。支援一次性提醒、週期性表達式與傳入 Webhook 觸發器。
請參閱[排程任務](/zh-TW/automation/cron-jobs)。
### 任務
背景任務帳本會追蹤所有分離的工作：ACP 執行、子代理產生、隔離的 cron 執行與 CLI 操作。任務是紀錄，不是排程器。使用 `openclaw tasks list` 與 `openclaw tasks audit` 來檢查它們。
請參閱[背景任務](/zh-TW/automation/tasks)。
### 推斷承諾
承諾是選擇加入、短期存在的後續追蹤記憶。OpenClaw 會從一般對話中推斷它們，將其限定於同一代理與頻道，並透過 Heartbeat 交付到期的確認。使用者明確請求的精確提醒仍屬於 cron。
請參閱[推斷承諾](/zh-TW/concepts/commitments)。
### Task Flow
Task Flow 是位於背景任務之上的流程編排基底。它會管理持久的多步驟流程，支援受管理與鏡像同步模式、修訂追蹤，以及用於檢查的 `openclaw tasks flow list|show|cancel`。
請參閱 [Task Flow](/zh-TW/automation/taskflow)。
### 常設命令
常設命令會授予代理針對已定義程式的永久操作權限。它們存放於工作區檔案中（通常是 `AGENTS.md`），並會注入每個工作階段。可搭配 cron 執行時間型強制要求。
請參閱[常設命令](/zh-TW/automation/standing-orders)。
### Hooks
內部 Hook 是由代理生命週期事件（`/new`、`/reset`、`/stop`）、工作階段 Compaction、Gateway 啟動與訊息流程觸發的事件驅動腳本。它們會從目錄中自動探索，並可使用 `openclaw hooks` 管理。若要進行程序內工具呼叫攔截，請使用 [Plugin hooks](/zh-TW/plugins/hooks)。
請參閱 [Hooks](/zh-TW/automation/hooks)。
### Heartbeat
Heartbeat 是週期性的主工作階段回合（預設每 30 分鐘）。它會在一個具備完整工作階段情境的代理回合中批次處理多項檢查（收件匣、日曆、通知）。Heartbeat 回合不會建立任務紀錄，也不會延長每日/閒置工作階段重設的新鮮度。可使用 `HEARTBEAT.md` 放置簡短檢查清單，或在你希望於 Heartbeat 本身內執行僅限到期的週期性檢查時使用 `tasks:` 區塊。空的 Heartbeat 檔案會以 `empty-heartbeat-file` 略過；僅限到期任務模式會以 `no-tasks-due` 略過。Heartbeat 會在 cron 工作處於作用中或已排入佇列時延後，而 `heartbeat.skipWhenBusy` 也可在子代理或巢狀通道忙碌時延後它們。
請參閱 [Heartbeat](/zh-TW/gateway/heartbeat)。
## 它們如何一起運作
- **Cron** 處理精確排程（每日報告、每週回顧）與一次性提醒。所有 cron 執行都會建立任務紀錄。
- **Heartbeat** 每 30 分鐘在一個批次回合中處理例行監控（收件匣、日曆、通知）。
- **Hooks** 使用自訂腳本回應特定事件（工作階段重設、Compaction、訊息流程）。Plugin hooks 涵蓋工具呼叫。
- **常設命令** 為代理提供持續性情境與權限邊界。
- **Task Flow** 在個別任務之上協調多步驟流程。
- **任務** 會自動追蹤所有分離的工作，讓你能檢查與稽核。
## 相關
- [排程任務](/zh-TW/automation/cron-jobs) — 精確排程與一次性提醒
- [推斷承諾](/zh-TW/concepts/commitments) — 類似記憶的後續追蹤確認
- [背景任務](/zh-TW/automation/tasks) — 所有分離工作的任務帳本
- [Task Flow](/zh-TW/automation/taskflow) — 持久的多步驟流程編排
- [Hooks](/zh-TW/automation/hooks) — 事件驅動的生命週期腳本
- [Plugin hooks](/zh-TW/plugins/hooks) — 程序內工具、提示、訊息與生命週期 Hook
- [常設命令](/zh-TW/automation/standing-orders) — 持續性代理指令
- [Heartbeat](/zh-TW/gateway/heartbeat) — 週期性主工作階段回合
- [設定參考](/zh-TW/gateway/configuration-reference) — 所有設定鍵

19
docs/zh-TW/automation/poll.md Normal file
View File

@ -0,0 +1,19 @@
---
summary: 重新導向至 /cli/message
title: 投票
x-i18n:
generated_at: "2026-04-30T02:44:53Z"
model: gpt-5.5
provider: openai
source_hash: a277212ed680b7aeb9153d003bc084d2d0c918dc53f2f469c72f7fe5a881cfae
source_path: automation/poll.md
workflow: 16
---
此頁面已移至 [訊息工具](/zh-TW/cli/message)。請參閱 [訊息工具](/zh-TW/cli/message) 以取得輪詢文件。
## 相關內容
- [Webhook](/zh-TW/automation/cron-jobs)
- [排程任務](/zh-TW/automation/cron-jobs)
- [背景任務](/zh-TW/automation/tasks)

257
docs/zh-TW/automation/standing-orders.md Normal file
View File

@ -0,0 +1,257 @@
---
read_when:
- 設定無需針對每項任務提示即可執行的自主代理工作流程
- 定義代理可以獨立執行的事項，以及需要人工核准的事項
- 使用清楚的邊界與升級規則來建構多程式代理程式
summary: 定義自主代理程式的永久操作權限
title: 常設指令
x-i18n:
generated_at: "2026-04-30T02:45:15Z"
model: gpt-5.5
provider: openai
source_hash: ff895378cbd53f7e8058137389037ab40201ce2cdfb34c135f480dfef775919b
source_path: automation/standing-orders.md
workflow: 16
---
常設指令會授予你的代理程式針對定義好方案的**永久操作權限**。你不必每次都提供個別任務指示，而是定義具備明確範圍、觸發條件與升級規則的方案，代理程式會在這些邊界內自主執行。
這就像是每週五告訴你的助理「寄送週報」，與授予常設權限之間的差異：「週報由你負責。每週五彙整、寄出，只有在看起來有問題時才升級處理。」
## 為什麼需要常設指令
**沒有常設指令時：**
- 你必須為每個任務提示代理程式
- 代理程式會在請求之間閒置
- 例行工作會被忘記或延誤
- 你會變成瓶頸
**有常設指令時：**
- 代理程式會在定義好的邊界內自主執行
- 例行工作會按時發生，無需提示
- 你只需介入例外與核准事項
- 代理程式能有效利用閒置時間
## 運作方式
常設指令定義在你的[代理程式工作區](/zh-TW/concepts/agent-workspace)檔案中。建議做法是直接放在 `AGENTS.md` 中（每個工作階段會自動注入），讓代理程式永遠能在脈絡中取得它們。對於較大型的設定，你也可以把它們放在像 `standing-orders.md` 這樣的專用檔案中，並從 `AGENTS.md` 參照它。
每個方案都會指定：
1. **範圍** — 代理程式被授權執行的事項
2. **觸發條件** — 何時執行（排程、事件或條件）
3. **核准關卡** — 採取行動前哪些事項需要人工簽核
4. **升級規則** — 何時停止並請求協助
代理程式會透過工作區啟動檔案在每個工作階段載入這些指示（完整的自動注入檔案清單請見[代理程式工作區](/zh-TW/concepts/agent-workspace)），並結合[Cron 工作](/zh-TW/automation/cron-jobs)執行，以便進行以時間為基礎的強制執行。
<Tip>
把常設指令放在 `AGENTS.md` 中，以確保每個工作階段都會載入。工作區啟動程序會自動注入 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` 與 `MEMORY.md`，但不會注入子目錄中的任意檔案。
</Tip>
## 常設指令的結構
```markdown
## Program: Weekly Status Report
**Authority:** Compile data, generate report, deliver to stakeholders
**Trigger:** Every Friday at 4 PM (enforced via cron job)
**Approval gate:** None for standard reports. Flag anomalies for human review.
**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm)
### Execution steps
1. Pull metrics from configured sources
2. Compare to prior week and targets
3. Generate report in Reports/weekly/YYYY-MM-DD.md
4. Deliver summary via configured channel
5. Log completion to Agent/Logs/
### What NOT to do
- Do not send reports to external parties
- Do not modify source data
- Do not skip delivery if metrics look bad — report accurately
```
## 常設指令加上 Cron 工作
常設指令定義代理程式被授權執行的**事項**。[Cron 工作](/zh-TW/automation/cron-jobs)定義它發生的**時間**。兩者會一起運作：
```
Standing Order: "You own the daily inbox triage"
↓
Cron Job (8 AM daily): "Execute inbox triage per standing orders"
↓
Agent: Reads standing orders → executes steps → reports results
```
Cron 工作提示應該參照常設指令，而不是重複其內容：
```bash
openclaw cron add \
--name daily-inbox-triage \
--cron "0 8 * * 1-5" \
--tz America/New_York \
--timeout-seconds 300 \
--announce \
--channel bluebubbles \
--to "+1XXXXXXXXXX" \
--message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns."
```
## 範例
### 範例 1：內容與社群媒體（每週週期）
```markdown
## Program: Content & Social Media
**Authority:** Draft content, schedule posts, compile engagement reports
**Approval gate:** All posts require owner review for first 30 days, then standing approval
**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief)
### Weekly cycle
- **Monday:** Review platform metrics and audience engagement
- **Tuesday–Thursday:** Draft social posts, create blog content
- **Friday:** Compile weekly marketing brief → deliver to owner
### Content rules
- Voice must match the brand (see SOUL.md or brand voice guide)
- Never identify as AI in public-facing content
- Include metrics when available
- Focus on value to audience, not self-promotion
```
### 範例 2：財務作業（事件觸發）
```markdown
## Program: Financial Processing
**Authority:** Process transaction data, generate reports, send summaries
**Approval gate:** None for analysis. Recommendations require owner approval.
**Trigger:** New data file detected OR scheduled monthly cycle
### When new data arrives
1. Detect new file in designated input directory
2. Parse and categorize all transactions
3. Compare against budget targets
4. Flag: unusual items, threshold breaches, new recurring charges
5. Generate report in designated output directory
6. Deliver summary to owner via configured channel
### Escalation rules
- Single item > $500: immediate alert
- Category > budget by 20%: flag in report
- Unrecognizable transaction: ask owner for categorization
- Failed processing after 2 retries: report failure, do not guess
```
### 範例 3：監控與警示（連續）
```markdown
## Program: System Monitoring
**Authority:** Check system health, restart services, send alerts
**Approval gate:** Restart services automatically. Escalate if restart fails twice.
**Trigger:** Every heartbeat cycle
### Checks
- Service health endpoints responding
- Disk space above threshold
- Pending tasks not stale (>24 hours)
- Delivery channels operational
### Response matrix
| Condition | Action | Escalate? |
| ---------------- | ------------------------ | ------------------------ |
| Service down | Restart automatically | Only if restart fails 2x |
| Disk space < 10% | Alert owner | Yes |
| Stale task > 24h | Remind owner | No |
| Channel offline | Log and retry next cycle | If offline > 2 hours |
```
## 執行、驗證、回報模式
常設指令搭配嚴格的執行紀律時效果最好。常設指令中的每個任務都應遵循這個循環：
1. **執行** — 完成實際工作（不要只是確認收到指示）
2. **驗證** — 確認結果正確（檔案存在、訊息已送達、資料已解析）
3. **回報** — 告訴擁有者已完成哪些事項，以及已驗證哪些事項
```markdown
### Execution rules
- Every task follows Execute-Verify-Report. No exceptions.
- "I'll do that" is not execution. Do it, then report.
- "Done" without verification is not acceptable. Prove it.
- If execution fails: retry once with adjusted approach.
- If still fails: report failure with diagnosis. Never silently fail.
- Never retry indefinitely — 3 attempts max, then escalate.
```
這個模式能避免最常見的代理程式失敗模式：確認任務但沒有完成它。
## 多方案架構
對於管理多個關注領域的代理程式，請將常設指令組織成邊界清楚的獨立方案：
```markdown
## Program 1: [Domain A] (Weekly)
...
## Program 2: [Domain B] (Monthly + On-Demand)
...
## Program 3: [Domain C] (As-Needed)
...
## Escalation Rules (All Programs)
- [Common escalation criteria]
- [Approval gates that apply across programs]
```
每個方案都應具備：
- 自己的**觸發節奏**（每週、每月、事件驅動、連續）
- 自己的**核准關卡**（有些方案需要比其他方案更多監督）
- 清楚的**邊界**（代理程式應知道一個方案在哪裡結束，另一個方案在哪裡開始）
## 最佳實務
### 應該做
- 從狹窄權限開始，隨著信任建立再擴大
- 為高風險動作定義明確的核准關卡
- 包含「不該做什麼」區段，邊界和權限一樣重要
- 結合 Cron 工作，以可靠地執行以時間為基礎的任務
- 每週檢閱代理程式日誌，確認常設指令有被遵循
- 隨著需求演進更新常設指令；它們是持續變動的文件
### 避免
- 第一天就授予廣泛權限（「做你認為最好的事」）
- 省略升級規則；每個方案都需要「何時停止並詢問」條款
- 假設代理程式會記得口頭指示；把所有內容都放進檔案
- 在單一方案中混合不同關注領域；為不同領域分開建立方案
- 忘記用 Cron 工作強制執行；沒有觸發條件的常設指令會變成建議
## 相關
- [自動化與任務](/zh-TW/automation)：所有自動化機制一覽。
- [Cron 工作](/zh-TW/automation/cron-jobs)：常設指令的排程強制執行。
- [Hook](/zh-TW/automation/hooks)：用於代理程式生命週期事件的事件驅動指令碼。
- [Webhook](/zh-TW/automation/cron-jobs#webhooks)：傳入的 HTTP 事件觸發條件。
- [代理程式工作區](/zh-TW/concepts/agent-workspace)：常設指令所在的位置，包括完整的自動注入啟動檔案清單（`AGENTS.md`、`SOUL.md` 等）。

162
docs/zh-TW/automation/taskflow.md Normal file
View File

@ -0,0 +1,162 @@
---
read_when:
- 你想了解 Task Flow 與背景任務之間的關係
- 你會在發行說明或文件中遇到 TaskFlow 或 OpenClaw 任務流程
- 你想要檢視或管理持久化的流程狀態
summary: 位於背景任務之上的 TaskFlow 流程編排層
title: 任務流程
x-i18n:
generated_at: "2026-04-30T02:45:23Z"
model: gpt-5.5
provider: openai
source_hash: 2ab261dea0ec3beb10b53c641bd188288cada5345aef6ddbbc8071d37eb57bdc
source_path: automation/taskflow.md
workflow: 16
---
TaskFlow 是位於[背景任務](/zh-TW/automation/tasks)之上的流程編排基底。它會管理具有自身狀態、修訂追蹤與同步語義的持久多步驟流程，而個別任務仍是分離工作的單位。
## 何時使用 TaskFlow
當工作橫跨多個循序或分支步驟，且需要在 gateway 重新啟動後仍能持久追蹤進度時，請使用 TaskFlow。對於單一背景作業，普通的[任務](/zh-TW/automation/tasks)就已足夠。
| 情境 | 使用方式 |
| ------------------------------------- | -------------------- |
| 單一背景工作 | 普通任務 |
| 多步驟管線（A 接著 B 接著 C） | TaskFlow（受管理） |
| 觀察外部建立的任務 | TaskFlow（鏡像） |
| 一次性提醒 | Cron 工作 |
## 可靠的排程工作流程模式
對於市場情報簡報等週期性工作流程，請將排程、編排與可靠性檢查視為不同層次：
1. 使用[排程任務](/zh-TW/automation/cron-jobs)處理時機。
2. 當工作流程應該基於先前脈絡延續時，使用持久 cron 工作階段。
3. 使用 [Lobster](/zh-TW/tools/lobster) 處理確定性步驟、核准關卡與續接權杖。
4. 使用 TaskFlow 在子任務、等待、重試與 gateway 重新啟動之間追蹤多步驟執行。
範例 cron 形狀：
```bash
openclaw cron add \
--name "Market intelligence brief" \
--cron "0 7 * * 1-5" \
--tz "America/New_York" \
--session session:market-intel \
--message "Run the market-intel Lobster workflow. Verify source freshness before summarizing." \
--announce \
--channel slack \
--to "channel:C1234567890"
```
當週期性工作流程需要刻意保留的歷史、前次執行摘要或常駐脈絡時，請使用 `session:<id>` 而不是 `isolated`。當每次執行都應該從全新狀態開始，且所有必要狀態都已在工作流程中明確指定時，請使用 `isolated`。
在工作流程內，請將可靠性檢查放在 LLM 摘要步驟之前：
```yaml
name: market-intel-brief
steps:
- id: preflight
command: market-intel check --json
- id: collect
command: market-intel collect --json
stdin: $preflight.json
- id: summarize
command: market-intel summarize --json
stdin: $collect.json
- id: approve
command: market-intel deliver --preview
stdin: $summarize.json
approval: required
- id: deliver
command: market-intel deliver --execute
stdin: $summarize.json
condition: $approve.approved
```
建議的預檢檢查：
- 瀏覽器可用性與設定檔選擇，例如受管理狀態使用 `openclaw`，需要已登入的 Chrome 工作階段時使用 `user`。請參閱[瀏覽器](/zh-TW/tools/browser)。
- 每個來源的 API 認證與配額。
- 必要端點的網路可連線性。
- 已為 agent 啟用必要工具，例如 `lobster`、`browser` 與 `llm-task`。
- 已為 cron 設定失敗目的地，讓預檢失敗可見。請參閱[排程任務](/zh-TW/automation/cron-jobs#delivery-and-output)。
每個收集項目的建議資料來源欄位：
```json
{
"sourceUrl": "https://example.com/report",
"retrievedAt": "2026-04-24T12:00:00Z",
"asOf": "2026-04-24",
"title": "Example report",
"content": "..."
}
```
讓工作流程在摘要前拒絕或標記過期項目。LLM 步驟應該只接收結構化 JSON，並應要求它在輸出中保留 `sourceUrl`、`retrievedAt` 與 `asOf`。當你需要在工作流程內使用經 schema 驗證的模型步驟時，請使用 [LLM Task](/zh-TW/tools/llm-task)。
對於可重複使用的團隊或社群工作流程，請將 CLI、`.lobster` 檔案與任何設定說明封裝為 skill 或 plugin，並透過 [ClawHub](/zh-TW/tools/clawhub) 發布。除非 plugin API 缺少必要的通用能力，否則請將工作流程特定的防護規則保留在該套件中。
## 同步模式
### 受管理模式
TaskFlow 端到端擁有生命週期。它會建立任務作為流程步驟、驅動它們完成，並自動推進流程狀態。
範例：每週報告流程會 (1) 收集資料、(2) 產生報告，並 (3) 傳送報告。TaskFlow 會將每個步驟建立為背景任務，等待完成，然後移至下一個步驟。
```
Flow: weekly-report
Step 1: gather-data → task created → succeeded
Step 2: generate-report → task created → succeeded
Step 3: deliver → task created → running
```
### 鏡像模式
TaskFlow 會觀察外部建立的任務，並在不取得任務建立所有權的情況下讓流程狀態保持同步。當任務來自 cron 工作、CLI 命令或其他來源，而你想要以流程形式統一檢視其進度時，這很有用。
範例：三個獨立的 cron 工作共同構成一個「早晨營運」例行流程。鏡像流程會追蹤它們的整體進度，而不控制它們何時或如何執行。
## 持久狀態與修訂追蹤
每個流程都會保留自身狀態並追蹤修訂，讓進度能在 gateway 重新啟動後延續。當多個來源嘗試同時推進同一個流程時，修訂追蹤可啟用衝突偵測。
流程登錄使用 SQLite，並搭配有界限的預寫日誌維護，包括
定期與關閉時的檢查點，因此長時間執行的 gateway 不會保留
無界限的 `registry.sqlite-wal` 附屬檔案。
## 取消行為
`openclaw tasks flow cancel` 會在流程上設定黏著的取消意圖。流程內的作用中任務會被取消，且不會啟動新的步驟。取消意圖會在重新啟動後持續存在，因此即使 gateway 在所有子任務終止前重新啟動，已取消的流程仍會保持取消狀態。
## CLI 命令
```bash
# List active and recent flows
openclaw tasks flow list
# Show details for a specific flow
openclaw tasks flow show <lookup>
# Cancel a running flow and its active tasks
openclaw tasks flow cancel <lookup>
```
| 命令 | 說明 |
| --------------------------------- | -------------------------------------------- |
| `openclaw tasks flow list` | 顯示受追蹤流程的狀態與同步模式 |
| `openclaw tasks flow show <id>` | 依流程 ID 或查找鍵檢查單一流程 |
| `openclaw tasks flow cancel <id>` | 取消執行中的流程及其作用中任務 |
## 流程與任務的關係
流程會協調任務，而不是取代任務。單一流程在其生命週期內可能驅動多個背景任務。使用 `openclaw tasks` 檢查個別任務記錄，並使用 `openclaw tasks flow` 檢查編排流程。
## 相關
- [背景任務](/zh-TW/automation/tasks) — 流程所協調的分離工作帳本
- [CLI：任務](/zh-TW/cli/tasks) — `openclaw tasks flow` 的 CLI 命令參考
- [自動化概覽](/zh-TW/automation) — 所有自動化機制一覽
- [Cron 工作](/zh-TW/automation/cron-jobs) — 可能提供資料給流程的排程工作

375
docs/zh-TW/automation/tasks.md Normal file
View File

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

19
docs/zh-TW/automation/troubleshooting.md Normal file
View File

@ -0,0 +1,19 @@
---
summary: 重新導向至 /automation/cron-jobs
title: 自動化疑難排解
x-i18n:
generated_at: "2026-04-30T02:45:16Z"
model: gpt-5.5
provider: openai
source_hash: e7784858f6d2594a1d6019435b2a5a1647e12f5de6329198db9539e325f73737
source_path: automation/troubleshooting.md
workflow: 16
---
此頁面已移至[排程任務](/zh-TW/automation/cron-jobs#troubleshooting)。請參閱[排程任務](/zh-TW/automation/cron-jobs#troubleshooting)以取得疑難排解文件。
## 相關
- [掛鉤](/zh-TW/automation/hooks)
- [背景任務](/zh-TW/automation/tasks)
- [Gateway 疑難排解](/zh-TW/gateway/troubleshooting)

19
docs/zh-TW/automation/webhook.md Normal file
View File

@ -0,0 +1,19 @@
---
summary: 重新導向至 /automation/cron-jobs
title: Webhook
x-i18n:
generated_at: "2026-04-30T02:45:20Z"
model: gpt-5.5
provider: openai
source_hash: b0241fc7232c73d1f595f18fdf1a2d65475c6a82e3068b0aefb4f95f41712086
source_path: automation/webhook.md
workflow: 16
---
此頁面已移至 [排程任務](/zh-TW/automation/cron-jobs#webhooks)。請參閱 [排程任務](/zh-TW/automation/cron-jobs#webhooks) 以取得 Webhook 文件。
## 相關
- [輪詢](/zh-TW/cli/message)
- [Gmail PubSub](/zh-TW/automation/cron-jobs)
- [掛鉤](/zh-TW/automation/hooks)

114
docs/zh-TW/brave-search.md Normal file
View File

@ -0,0 +1,114 @@
---
read_when:
- 您想使用 Brave Search 進行 web_search
- 你需要 BRAVE_API_KEY 或方案詳細資訊
summary: web_search 的 Brave Search API 設定
title: Brave 搜尋（舊版路徑）
x-i18n:
generated_at: "2026-04-30T02:45:48Z"
model: gpt-5.5
provider: openai
source_hash: e2769da4db2ff5b94217c09b13ef5ee4106ba108a828db2a99892a4a15d7b517
source_path: brave-search.md
workflow: 16
---
# Brave Search API
OpenClaw 支援 Brave Search API 作為 `web_search` 提供者。
## 取得 API 金鑰
1. 在 [https://brave.com/search/api/](https://brave.com/search/api/) 建立 Brave Search API 帳戶
2. 在儀表板中，選擇 **Search** 方案並產生 API 金鑰。
3. 將金鑰儲存在設定中，或在 Gateway 環境中設定 `BRAVE_API_KEY`。
## 設定範例
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
mode: "web", // or "llm-context"
},
},
},
},
},
tools: {
web: {
search: {
provider: "brave",
maxResults: 5,
timeoutSeconds: 30,
},
},
},
}
```
Brave 專屬的搜尋設定現在位於 `plugins.entries.brave.config.webSearch.*` 下。
舊版 `tools.web.search.apiKey` 仍會透過相容性 shim 載入，但它不再是標準設定路徑。
`webSearch.mode` 控制 Brave 傳輸模式：
- `web`（預設）：一般 Brave 網頁搜尋，包含標題、URL 和摘要
- `llm-context`：Brave LLM Context API，包含預先擷取的文字區塊和用於依據佐證的來源
## 工具參數
| 參數 | 說明 |
| ------------- | ------------------------------------------------------------------- |
| `query` | 搜尋查詢（必要） |
| `count` | 要傳回的結果數量（1-10，預設：5） |
| `country` | 2 字母 ISO 國家代碼（例如 "US"、"DE"） |
| `language` | 搜尋結果的 ISO 639-1 語言代碼（例如 "en"、"de"、"fr"） |
| `search_lang` | Brave 搜尋語言代碼（例如 `en`、`en-gb`、`zh-hans`） |
| `ui_lang` | UI 元素的 ISO 語言代碼 |
| `freshness` | 時間篩選器：`day`（24 小時）、`week`、`month` 或 `year` |
| `date_after` | 只包含此日期之後發布的結果（YYYY-MM-DD） |
| `date_before` | 只包含此日期之前發布的結果（YYYY-MM-DD） |
**範例：**
```javascript
// Country and language-specific search
await web_search({
query: "renewable energy",
country: "DE",
language: "de",
});
// Recent results (past week)
await web_search({
query: "AI news",
freshness: "week",
});
// Date range search
await web_search({
query: "AI developments",
date_after: "2024-01-01",
date_before: "2024-06-30",
});
```
## 注意事項
- OpenClaw 使用 Brave **Search** 方案。如果你有舊版訂閱（例如原本每月 2,000 次查詢的 Free 方案），它仍然有效，但不包含 LLM Context 或更高速率限制等較新功能。
- 每個 Brave 方案都包含**每月 \$5 免費額度**（會續期）。Search 方案每 1,000 次請求收費 \$5，因此該額度可涵蓋每月 1,000 次查詢。請在 Brave 儀表板中設定使用量限制，以避免產生非預期費用。請參閱 [Brave API 入口網站](https://brave.com/search/api/)了解目前方案。
- Search 方案包含 LLM Context 端點和 AI 推論權限。儲存結果以訓練或微調模型需要具備明確儲存權限的方案。請參閱 Brave [服務條款](https://api-dashboard.search.brave.com/terms-of-service)。
- `llm-context` 模式會傳回有依據佐證的來源項目，而不是一般網頁搜尋摘要格式。
- `llm-context` 模式不支援 `ui_lang`、`freshness`、`date_after` 或 `date_before`。
- `ui_lang` 必須包含像 `en-US` 這樣的區域子標籤。
- 結果預設會快取 15 分鐘（可透過 `cacheTtlMinutes` 設定）。
請參閱 [Web 工具](/zh-TW/tools/web)了解完整的 web_search 設定。
## 相關
- [Brave 搜尋](/zh-TW/tools/brave-search)

645
docs/zh-TW/channels/bluebubbles.md Normal file
View File

@ -0,0 +1,645 @@
---
read_when:
- 設定 BlueBubbles 頻道
- Webhook 配對疑難排解
- 在 macOS 上設定 iMessage
sidebarTitle: BlueBubbles
summary: 透過 BlueBubbles macOS 伺服器使用 iMessage（REST 傳送/接收、輸入狀態、回應、配對、進階動作）。
title: BlueBubbles
x-i18n:
generated_at: "2026-04-30T02:46:00Z"
model: gpt-5.5
provider: openai
source_hash: 7a77b248ed86eb4114f8b7f1fc6bd4cea004d65095a0439a4a8c814bc180082c
source_path: channels/bluebubbles.md
workflow: 16
---
狀態：透過 HTTP 與 BlueBubbles macOS 伺服器通訊的內建 Plugin。由於相較於舊版 imsg 頻道，它具備更完整的 API 且設定更簡單，因此**建議用於 iMessage 整合**。
<Note>
目前的 OpenClaw 版本已內建 BlueBubbles，因此一般封裝建置不需要另外執行 `openclaw plugins install` 步驟。
</Note>
## 概觀
- 透過 BlueBubbles 輔助 App（[bluebubbles.app](https://bluebubbles.app)）在 macOS 上執行。
- 建議／已測試：macOS Sequoia (15)。macOS Tahoe (26) 可運作；目前 Tahoe 上的編輯功能無法使用，而群組圖示更新可能回報成功但未同步。
- OpenClaw 透過其 REST API（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）與它通訊。
- 傳入訊息透過 Webhook 抵達；傳出回覆、輸入中指示、已讀回條與 tapback 都是 REST 呼叫。
- 附件與貼圖會作為傳入媒體擷取（可行時也會提供給代理）。
- 合成 MP3 或 CAF 音訊的自動 TTS 回覆會以 iMessage 語音備忘錄氣泡傳送，而不是一般檔案附件。
- 配對／允許清單的運作方式與其他頻道相同（`/channels/pairing` 等），搭配 `channels.bluebubbles.allowFrom` 與配對碼使用。
- 回應會像 Slack/Telegram 一樣以系統事件呈現，讓代理可在回覆前「提及」它們。
- 進階功能：編輯、取消傳送、回覆串接、訊息效果、群組管理。
## 快速開始
<Steps>
<Step title="安裝 BlueBubbles">
在你的 Mac 上安裝 BlueBubbles 伺服器（依照 [bluebubbles.app/install](https://bluebubbles.app/install) 的指示）。
</Step>
<Step title="啟用 Web API">
在 BlueBubbles 設定中啟用 Web API 並設定密碼。
</Step>
<Step title="設定 OpenClaw">
執行 `openclaw onboard` 並選取 BlueBubbles，或手動設定：
```json5
{
channels: {
bluebubbles: {
enabled: true,
serverUrl: "http://192.168.1.100:1234",
password: "example-password",
webhookPath: "/bluebubbles-webhook",
},
},
}
```
</Step>
<Step title="將 Webhook 指向 Gateway">
將 BlueBubbles Webhook 指向你的 Gateway（範例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
</Step>
<Step title="啟動 Gateway">
啟動 Gateway；它會註冊 Webhook 處理常式並開始配對。
</Step>
</Steps>
<Warning>
**安全性**
- 一律設定 Webhook 密碼。
- Webhook 驗證一律為必要。除非 BlueBubbles Webhook 要求包含符合 `channels.bluebubbles.password` 的密碼／guid（例如 `?password=<password>` 或 `x-password`），否則 OpenClaw 會拒絕該要求，不論 loopback／代理拓撲為何。
- 密碼驗證會在讀取／解析完整 Webhook 本文之前檢查。
</Warning>
## 讓 Messages.app 保持運作（VM／無頭設定）
某些 macOS VM／常開設定可能會使 Messages.app 進入「閒置」狀態（傳入事件停止，直到 App 被開啟／切到前景）。簡單的替代方案是使用 AppleScript + LaunchAgent **每 5 分鐘戳一下 Messages**。
<Steps>
<Step title="儲存 AppleScript">
將此儲存為 `~/Scripts/poke-messages.scpt`：
```applescript
try
tell application "Messages"
if not running then
launch
end if
-- Touch the scripting interface to keep the process responsive.
set _chatCount to (count of chats)
end tell
on error
-- Ignore transient failures (first-run prompts, locked session, etc).
end try
```
</Step>
<Step title="安裝 LaunchAgent">
將此儲存為 `~/Library/LaunchAgents/com.user.poke-messages.plist`：
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.poke-messages</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>-lc</string>
<string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>300</integer>
<key>StandardOutPath</key>
<string>/tmp/poke-messages.log</string>
<key>StandardErrorPath</key>
<string>/tmp/poke-messages.err</string>
</dict>
</plist>
```
這會**每 300 秒**並在**登入時**執行。第一次執行可能會觸發 macOS **Automation** 提示（`osascript` → Messages）。請在執行 LaunchAgent 的同一個使用者工作階段中核准。
</Step>
<Step title="載入它">
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
```
</Step>
</Steps>
## 上線設定
BlueBubbles 可在互動式上線設定中使用：
```
openclaw onboard
```
精靈會提示輸入：
<ParamField path="伺服器 URL" type="string" required>
BlueBubbles 伺服器位址（例如 `http://192.168.1.100:1234`）。
</ParamField>
<ParamField path="密碼" type="string" required>
來自 BlueBubbles Server 設定的 API 密碼。
</ParamField>
<ParamField path="Webhook 路徑" type="string" default="/bluebubbles-webhook">
Webhook 端點路徑。
</ParamField>
<ParamField path="DM 政策" type="string">
`pairing`、`allowlist`、`open` 或 `disabled`。
</ParamField>
<ParamField path="允許清單" type="string[]">
電話號碼、電子郵件或聊天目標。
</ParamField>
你也可以透過 CLI 新增 BlueBubbles：
```
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
## 存取控制（DM + 群組）
<Tabs>
<Tab title="DM">
- 預設：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知寄件者會收到配對碼；在核准前訊息會被忽略（代碼會在 1 小時後過期）。
- 透過以下方式核准：
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- 配對是預設的權杖交換。詳細資訊：[配對](/zh-TW/channels/pairing)
</Tab>
<Tab title="群組">
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled`（預設：`allowlist`）。
- 設定 `allowlist` 時，`channels.bluebubbles.groupAllowFrom` 控制誰可以在群組中觸發。
</Tab>
</Tabs>
### 聯絡人名稱補充（macOS，選用）
BlueBubbles 群組 Webhook 通常只包含原始參與者位址。如果你希望 `GroupMembers` 內容改為顯示本機聯絡人名稱，可以在 macOS 上選擇啟用本機 Contacts 補充：
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` 啟用查詢。預設：`false`。
- 查詢只會在群組存取、命令授權與提及閘控允許訊息通過後執行。
- 只會補充未命名的電話參與者。
- 找不到本機符合項目時，原始電話號碼會保留作為後備。
```json5
{
channels: {
bluebubbles: {
enrichGroupParticipantsFromContacts: true,
},
},
}
```
### 提及閘控（群組）
BlueBubbles 支援群組聊天的提及閘控，與 iMessage/WhatsApp 行為一致：
- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）偵測提及。
- 對群組啟用 `requireMention` 時，代理只會在被提及時回應。
- 來自已授權寄件者的控制命令會略過提及閘控。
每群組設定：
```json5
{
channels: {
bluebubbles: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // default for all groups
"iMessage;-;chat123": { requireMention: false }, // override for specific group
},
},
},
}
```
### 命令閘控
- 控制命令（例如 `/config`、`/model`）需要授權。
- 使用 `allowFrom` 與 `groupAllowFrom` 判定命令授權。
- 已授權寄件者即使未在群組中提及，也可以執行控制命令。
### 每群組系統提示
`channels.bluebubbles.groups.*` 下的每個項目都接受選用的 `systemPrompt` 字串。該值會在處理該群組訊息的每一輪中注入代理的系統提示，因此你可以設定每群組的人格或行為規則，而不必編輯代理提示：
```json5
{
channels: {
bluebubbles: {
groups: {
"iMessage;-;chat123": {
systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
},
},
},
},
}
```
鍵會符合 BlueBubbles 為該群組回報的 `chatGuid` / `chatIdentifier` / 數字 `chatId`，而 `"*"` 萬用字元項目會為沒有精確符合項目的每個群組提供預設值（與 `requireMention` 和每群組工具政策使用相同模式）。精確符合一律優先於萬用字元。DM 會忽略此欄位；請改用代理層級或帳號層級的提示自訂。
#### 實作範例：串接回覆與 tapback 回應（Private API）
啟用 BlueBubbles Private API 後，傳入訊息會附帶短訊息 ID（例如 `[[reply_to:5]]`），且代理可以呼叫 `action=reply` 以串接到特定訊息，或呼叫 `action=react` 放置 tapback。每群組 `systemPrompt` 是讓代理選擇正確工具的可靠方式：
```json5
{
channels: {
bluebubbles: {
groups: {
"iMessage;+;chat-family": {
systemPrompt: [
"When replying in this group, always call action=reply with the",
"[[reply_to:N]] messageId from context so your response threads",
"under the triggering message. Never send a new unlinked message.",
"",
"For short acknowledgements ('ok', 'got it', 'on it'), use",
"action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓)",
"instead of sending a text reply.",
].join(" "),
},
},
},
},
}
```
Tapback 回應和串接回覆都需要 BlueBubbles Private API；請參閱[進階動作](#advanced-actions)與[訊息 ID](#message-ids-short-vs-full)以了解底層機制。
## ACP 對話繫結
BlueBubbles 聊天可以在不變更傳輸層的情況下轉換為持久 ACP 工作區。
快速操作流程：
- 在 DM 或允許的群組聊天中執行 `/acp spawn codex --bind here`。
- 同一個 BlueBubbles 對話中的後續訊息會路由到產生的 ACP 工作階段。
- `/new` 和 `/reset` 會就地重設同一個已繫結的 ACP 工作階段。
- `/acp close` 會關閉 ACP 工作階段並移除繫結。
也支援透過頂層 `bindings[]` 項目設定持久繫結，其中包含 `type: "acp"` 與 `match.channel: "bluebubbles"`。
`match.peer.id` 可以使用任何支援的 BlueBubbles 目標形式：
- 正規化 DM 控點，例如 `+15555550123` 或 `user@example.com`
- `chat_id:<id>`
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
對於穩定的群組繫結，建議使用 `chat_id:*` 或 `chat_identifier:*`。
範例：
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: { agent: "codex", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "bluebubbles",
accountId: "default",
peer: { kind: "dm", id: "+15555550123" },
},
acp: { label: "codex-imessage" },
},
],
}
```
請參閱 [ACP Agents](/zh-TW/tools/acp-agents) 以了解共用的 ACP 繫結行為。
## 輸入中 + 已讀回條
- **輸入中指示器**：會在回覆生成前與生成期間自動傳送。
- **已讀回條**：由 `channels.bluebubbles.sendReadReceipts` 控制（預設值：`true`）。
- **輸入中指示器**：OpenClaw 會傳送開始輸入事件；BlueBubbles 會在傳送或逾時時自動清除輸入狀態（透過 DELETE 手動停止並不可靠）。
```json5
{
channels: {
bluebubbles: {
sendReadReceipts: false, // disable read receipts
},
},
}
```
## 進階動作
BlueBubbles 在設定中啟用後支援進階訊息動作：
```json5
{
channels: {
bluebubbles: {
actions: {
reactions: true, // tapbacks (default: true)
edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
unsend: true, // unsend messages (macOS 13+)
reply: true, // reply threading by message GUID
sendWithEffect: true, // message effects (slam, loud, etc.)
renameGroup: true, // rename group chats
setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
addParticipant: true, // add participants to groups
removeParticipant: true, // remove participants from groups
leaveGroup: true, // leave group chats
sendAttachment: true, // send attachments/media
},
},
},
}
```
<AccordionGroup>
<Accordion title="可用動作">
- **react**：新增/移除 tapback 反應（`messageId`、`emoji`、`remove`）。iMessage 的原生 tapback 集合是 `love`、`like`、`dislike`、`laugh`、`emphasize` 和 `question`。當代理選擇該集合之外的 emoji（例如 `👀`）時，反應工具會退回使用 `love`，讓 tapback 仍能顯示，而不是讓整個請求失敗。已設定的確認反應仍會嚴格驗證，並在未知值上報錯。
- **edit**：編輯已傳送的訊息（`messageId`、`text`）。
- **unsend**：收回訊息（`messageId`）。
- **reply**：回覆特定訊息（`messageId`、`text`、`to`）。
- **sendWithEffect**：使用 iMessage 效果傳送（`text`、`to`、`effectId`）。
- **renameGroup**：重新命名群組聊天（`chatGuid`、`displayName`）。
- **setGroupIcon**：設定群組聊天的圖示/照片（`chatGuid`、`media`）— 在 macOS 26 Tahoe 上不穩定（API 可能回傳成功，但圖示不會同步）。
- **addParticipant**：將某人加入群組（`chatGuid`、`address`）。
- **removeParticipant**：將某人從群組移除（`chatGuid`、`address`）。
- **leaveGroup**：離開群組聊天（`chatGuid`）。
- **upload-file**：傳送媒體/檔案（`to`、`buffer`、`filename`、`asVoice`）。
- 語音備忘錄：設定 `asVoice: true`，並使用 **MP3** 或 **CAF** 音訊，以 iMessage 語音訊息傳送。BlueBubbles 會在傳送語音備忘錄時將 MP3 → CAF。
- 舊版別名：`sendAttachment` 仍可使用，但 `upload-file` 是標準動作名稱。
</Accordion>
</AccordionGroup>
### 訊息 ID（短 ID 與完整 ID）
OpenClaw 可能會顯示_短_訊息 ID（例如 `1`、`2`）以節省 Token。
- `MessageSid` / `ReplyToId` 可以是短 ID。
- `MessageSidFull` / `ReplyToIdFull` 包含提供者的完整 ID。
- 短 ID 儲存在記憶體中；它們可能會在重新啟動或快取淘汰後過期。
- 動作接受短或完整 `messageId`，但如果短 ID 已無法取得，將會報錯。
對於持久的自動化與儲存，請使用完整 ID：
- 範本：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
- 情境：傳入酬載中的 `MessageSidFull` / `ReplyToIdFull`
範本變數請參閱[設定](/zh-TW/gateway/configuration)。
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
## 合併分段傳送的 DM（指令 + URL 在同一次組合中）
當使用者在 iMessage 中同時輸入指令和 URL，例如 `Dump https://example.com/article`，Apple 會將傳送拆成**兩個獨立的 Webhook 投遞**：
1. 一則文字訊息（`"Dump"`）。
2. 一個 URL 預覽氣泡（`"https://..."`），並以附件形式包含 OG 預覽圖片。
在多數設定中，兩個 Webhook 約相隔 0.8-2.0 秒抵達 OpenClaw。若沒有合併，代理會在第 1 回合只收到指令並回覆（通常是「把 URL 傳給我」），然後只在第 2 回合看到 URL，此時指令情境已經遺失。
`channels.bluebubbles.coalesceSameSenderDms` 會選擇讓 DM 將連續的同一寄件者 Webhook 合併成單一代理回合。群組聊天會繼續按每則訊息作為鍵，以保留多使用者回合結構。
<Tabs>
<Tab title="何時啟用">
在以下情況啟用：
- 你提供預期一則訊息中有 `command + payload` 的 Skills（dump、paste、save、queue 等）。
- 你的使用者會在指令旁貼上 URL、圖片或長內容。
- 你可以接受增加的 DM 回合延遲（見下方）。
在以下情況保持停用：
- 你需要單字 DM 觸發的最低指令延遲。
- 你的所有流程都是沒有後續酬載的一次性指令。
</Tab>
<Tab title="啟用">
```json5
{
channels: {
bluebubbles: {
coalesceSameSenderDms: true, // opt in (default: false)
},
},
}
```
啟用此旗標且未明確設定 `messages.inbound.byChannel.bluebubbles` 時，防抖視窗會加寬到 **2500 ms**（未合併時的預設值為 500 ms）。較寬的視窗是必要的，因為 Apple 的分段傳送節奏為 0.8-2.0 秒，無法放入較短的預設值。
若要自行調整視窗：
```json5
{
messages: {
inbound: {
byChannel: {
// 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
// or under memory pressure (observed gap can stretch past 2 s then).
bluebubbles: 2500,
},
},
},
}
```
</Tab>
<Tab title="取捨">
- **DM 控制指令會增加延遲。** 啟用此旗標後，DM 控制指令訊息（例如 `Dump`、`Save` 等）現在會等待最多到防抖視窗結束再派送，以防酬載 Webhook 即將到來。群組聊天指令會保持立即派送。
- **合併輸出有界限** — 合併文字上限為 4000 字元，並帶有明確的 `…[truncated]` 標記；附件上限為 20；來源項目上限為 10（超過後保留第一個加最新的項目）。每個來源 `messageId` 仍會進入傳入去重，因此稍後 MessagePoller 重新播放任何個別事件時，都會被辨識為重複。
- **選擇加入，按頻道設定。** 其他頻道（Telegram、WhatsApp、Slack、…）不受影響。
</Tab>
</Tabs>
### 場景與代理看到的內容
| 使用者組合內容 | Apple 投遞 | 關閉旗標（預設） | 開啟旗標 + 2500 ms 視窗 |
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `Dump https://example.com`（一次傳送） | 約相隔 1 秒的 2 個 Webhook | 兩個代理回合：只有 "Dump"，接著是 URL | 一個回合：合併文字 `Dump https://example.com` |
| `Save this 📎image.jpg caption`（附件 + 文字） | 2 個 Webhook | 兩個回合 | 一個回合：文字 + 圖片 |
| `/status`（獨立指令） | 1 個 Webhook | 立即派送 | **等待最多到視窗結束，然後派送** |
| 單獨貼上的 URL | 1 個 Webhook | 立即派送 | 立即派送（桶中只有一個項目） |
| 文字 + URL 以兩則刻意分開的訊息傳送，相隔數分鐘 | 視窗外的 2 個 Webhook | 兩個回合 | 兩個回合（視窗在兩者之間到期） |
| 快速大量湧入（視窗內 >10 則小型 DM） | N 個 Webhook | N 個回合 | 一個回合，有界限的輸出（套用第一個 + 最新、文字/附件上限） |
### 分段傳送合併疑難排解
如果旗標已開啟，但分段傳送仍以兩個回合抵達，請檢查每一層：
<AccordionGroup>
<Accordion title="設定確實已載入">
```
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
```
然後執行 `openclaw gateway restart` — 此旗標會在建立防抖器註冊表時讀取。
</Accordion>
<Accordion title="防抖視窗對你的設定足夠寬">
查看 `~/Library/Logs/bluebubbles-server/main.log` 下的 BlueBubbles 伺服器日誌：
```
grep -E "Dispatching event to webhook" main.log | tail -20
```
測量 `"Dump"` 風格文字派送與後續 `"https://..."; Attachments:` 派送之間的間隔。將 `messages.inbound.byChannel.bluebubbles` 提高到能從容涵蓋該間隔的值。
</Accordion>
<Accordion title="工作階段 JSONL 時間戳 ≠ Webhook 抵達">
工作階段事件時間戳（`~/.openclaw/agents/<id>/sessions/*.jsonl`）反映 Gateway 將訊息交給代理的時間，**不是** Webhook 抵達的時間。標記為 `[Queued messages while agent was busy]` 的已佇列第二則訊息，表示第二個 Webhook 抵達時第一回合仍在執行，合併桶已經清空。請根據 BB 伺服器日誌調整視窗，而不是工作階段日誌。
</Accordion>
<Accordion title="記憶體壓力拖慢回覆派送">
在較小的機器（8 GB）上，代理回合可能會花很久，導致合併桶在回覆完成前清空，而 URL 會以已佇列的第二回合進入。檢查 `memory_pressure` 和 `ps -o rss -p $(pgrep openclaw-gateway)`；如果 Gateway 超過約 500 MB RSS 且壓縮器正在作用，請關閉其他高負載程序或改用更大的主機。
</Accordion>
<Accordion title="引用回覆傳送是不同路徑">
如果使用者點選 `Dump` 作為既有 URL 氣泡的**回覆**（iMessage 在 Dump 氣泡上顯示「1 Reply」徽章），URL 會位於 `replyToBody`，而不是第二個 Webhook 中。合併不適用 — 那是 Skills/提示詞問題，不是防抖器問題。
</Accordion>
</AccordionGroup>
## 區塊串流
控制回覆要以單一訊息傳送，或以區塊串流傳送：
```json5
{
channels: {
bluebubbles: {
blockStreaming: true, // enable block streaming (off by default)
},
},
}
```
## 媒體 + 限制
- 傳入附件會下載並儲存在媒體快取中。
- 透過 `channels.bluebubbles.mediaMaxMb` 設定傳入與傳出媒體的媒體上限（預設值：8 MB）。
- 傳出文字會依 `channels.bluebubbles.textChunkLimit` 分段（預設值：4000 字元）。
## 設定參考
完整設定：[設定](/zh-TW/gateway/configuration)
<AccordionGroup>
<Accordion title="連線與 Webhook">
- `channels.bluebubbles.enabled`：啟用/停用頻道。
- `channels.bluebubbles.serverUrl`：BlueBubbles REST API 基礎 URL。
- `channels.bluebubbles.password`：API 密碼。
- `channels.bluebubbles.webhookPath`：Webhook 端點路徑（預設值：`/bluebubbles-webhook`）。
</Accordion>
<Accordion title="存取政策">
- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（預設值：`pairing`）。
- `channels.bluebubbles.allowFrom`：DM 允許清單（帳號、電子郵件、E.164 號碼、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（預設值：`allowlist`）。
- `channels.bluebubbles.groupAllowFrom`：群組寄件者允許清單。
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`：在 macOS 上，通過門檻檢查後，可選擇從本機「聯絡人」補充未命名群組參與者。預設值：`false`。
- `channels.bluebubbles.groups`：每個群組的設定（`requireMention` 等）。
</Accordion>
<Accordion title="傳遞與分塊">
- `channels.bluebubbles.sendReadReceipts`: 傳送已讀回條（預設：`true`）。
- `channels.bluebubbles.blockStreaming`: 啟用區塊串流（預設：`false`；串流回覆需要此項）。
- `channels.bluebubbles.textChunkLimit`: 外送分塊大小，以字元數計（預設：4000）。
- `channels.bluebubbles.sendTimeoutMs`: 透過 `/api/v1/message/text` 傳送外送文字時，每個請求的逾時時間，以毫秒計（預設：30000）。在 macOS 26 設定中，如果 Private API iMessage 傳送可能在 iMessage framework 內停滯 60 秒以上，請提高此值；例如 `45000` 或 `60000`。探測、聊天查找、反應、編輯和健康檢查目前仍保留較短的 10 秒預設值；後續計畫將涵蓋範圍擴大到反應和編輯。每個帳號覆寫：`channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`。
- `channels.bluebubbles.chunkMode`: `length`（預設）只會在超過 `textChunkLimit` 時分割；`newline` 會先依空白行（段落邊界）分割，再按長度分塊。
</Accordion>
<Accordion title="媒體與歷史記錄">
- `channels.bluebubbles.mediaMaxMb`: 傳入/傳出媒體上限，以 MB 計（預設：8）。
- `channels.bluebubbles.mediaLocalRoots`: 明確允許用於傳出本機媒體路徑的絕對本機目錄允許清單。除非已設定此項，否則預設拒絕傳送本機路徑。每個帳號覆寫：`channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
- `channels.bluebubbles.coalesceSameSenderDms`: 將連續的同一寄件者 DM Webhook 合併成一次代理回合，讓 Apple 的文字+URL 分割傳送以單一訊息抵達（預設：`false`）。請參閱[合併分割傳送的 DM](#coalescing-split-send-dms-command--url-in-one-composition)，了解情境、視窗調整與取捨。啟用時若未明確設定 `messages.inbound.byChannel.bluebubbles`，會將預設傳入防抖視窗從 500 ms 擴大到 2500 ms。
- `channels.bluebubbles.historyLimit`: 內容脈絡的群組訊息數上限（0 會停用）。
- `channels.bluebubbles.dmHistoryLimit`: DM 歷史記錄限制。
</Accordion>
<Accordion title="動作與帳號">
- `channels.bluebubbles.actions`: 啟用/停用特定動作。
- `channels.bluebubbles.accounts`: 多帳號設定。
</Accordion>
</AccordionGroup>
相關全域選項：
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
- `messages.responsePrefix`。
## 定址 / 傳遞目標
建議使用 `chat_guid` 進行穩定路由：
- `chat_guid:iMessage;-;+15555550123`（群組建議使用）
- `chat_id:123`
- `chat_identifier:...`
- 直接 handle：`+15555550123`、`user@example.com`
- 如果直接 handle 沒有既有的 DM 聊天，OpenClaw 會透過 `POST /api/v1/chat/new` 建立一個。這需要啟用 BlueBubbles Private API。
### iMessage 與 SMS 路由
當同一個 handle 在 Mac 上同時有 iMessage 和 SMS 聊天時（例如某個電話號碼已註冊 iMessage，但也曾收到綠色氣泡備援），OpenClaw 會優先使用 iMessage 聊天，且絕不會默默降級為 SMS。若要強制使用 SMS 聊天，請使用明確的 `sms:` 目標前綴（例如 `sms:+15555550123`）。沒有相符 iMessage 聊天的 handle 仍會透過 BlueBubbles 回報的任何聊天傳送。
## 安全性
- Webhook 請求會透過比較 `guid`/`password` 查詢參數或標頭與 `channels.bluebubbles.password` 來驗證。
- 請將 API 密碼和 Webhook 端點保密（視同憑證處理）。
- BlueBubbles Webhook 驗證沒有 localhost 繞過。如果你代理 Webhook 流量，請在請求端到端保留 BlueBubbles 密碼。此處的 `gateway.trustedProxies` 不會取代 `channels.bluebubbles.password`。請參閱 [Gateway 安全性](/zh-TW/gateway/security#reverse-proxy-configuration)。
- 如果要將 BlueBubbles 伺服器暴露到 LAN 外，請啟用 HTTPS + 防火牆規則。
## 疑難排解
- 如果輸入/已讀事件停止運作，請檢查 BlueBubbles Webhook 記錄，並確認 Gateway 路徑符合 `channels.bluebubbles.webhookPath`。
- 配對代碼會在一小時後過期；請使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
- 反應需要 BlueBubbles Private API（`POST /api/v1/message/react`）；請確認伺服器版本有公開它。
- 編輯/取消傳送需要 macOS 13+ 和相容的 BlueBubbles 伺服器版本。在 macOS 26（Tahoe）上，由於 Private API 變更，編輯目前無法使用。
- 群組圖示更新在 macOS 26（Tahoe）上可能不穩定：API 可能回傳成功，但新圖示不會同步。
- OpenClaw 會根據 BlueBubbles 伺服器的 macOS 版本自動隱藏已知無法運作的動作。如果在 macOS 26（Tahoe）上仍看到編輯，請使用 `channels.bluebubbles.actions.edit=false` 手動停用它。
- 已啟用 `coalesceSameSenderDms`，但分割傳送（例如 `Dump` + URL）仍以兩個回合抵達：請參閱[分割傳送合併疑難排解](#split-send-coalescing-troubleshooting)檢查清單 — 常見原因包括防抖視窗太短、將工作階段記錄時間戳誤讀為 Webhook 抵達時間，或回覆引用傳送（其使用 `replyToBody`，而不是第二個 Webhook）。
- 如需狀態/健康資訊：`openclaw status --all` 或 `openclaw status --deep`。
如需一般頻道工作流程參考，請參閱[頻道](/zh-TW/channels)和 [Plugin](/zh-TW/tools/plugin) 指南。
## 相關
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [頻道概觀](/zh-TW/channels) — 所有支援的頻道
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

477
docs/zh-TW/channels/broadcast-groups.md Normal file
View File

@ -0,0 +1,477 @@
---
read_when:
- 設定廣播群組
- 偵錯 WhatsApp 中的多代理回覆
sidebarTitle: Broadcast groups
status: experimental
summary: 將 WhatsApp 訊息廣播給多個代理程式
title: 廣播群組
x-i18n:
generated_at: "2026-04-30T02:45:59Z"
model: gpt-5.5
provider: openai
source_hash: b0de4ccc85bf79e2ceb1dddd60db067309b15b7f876c92e7d591ff0b4b4315ec
source_path: channels/broadcast-groups.md
workflow: 16
---
<Note>
**狀態：** 實驗性。已於 2026.1.9 新增。
</Note>
## 概覽
廣播群組可讓多個代理同時處理並回應同一則訊息。這讓你能建立專門化的代理團隊，在單一 WhatsApp 群組或私訊中協同工作，而且全都使用同一個電話號碼。
目前範圍：**僅限 WhatsApp**（網頁通道）。
廣播群組會在通道允許清單與群組啟用規則之後評估。在 WhatsApp 群組中，這表示當 OpenClaw 通常會回覆時就會發生廣播（例如：提及時，取決於你的群組設定）。
## 使用案例
<AccordionGroup>
<Accordion title="1. Specialized agent teams">
部署多個具備原子化、聚焦職責的代理：
```
Group: "Development Team"
Agents:
- CodeReviewer (reviews code snippets)
- DocumentationBot (generates docs)
- SecurityAuditor (checks for vulnerabilities)
- TestGenerator (suggests test cases)
```
每個代理都會處理同一則訊息，並提供其專門觀點。
</Accordion>
<Accordion title="2. Multi-language support">
```
Group: "International Support"
Agents:
- Agent_EN (responds in English)
- Agent_DE (responds in German)
- Agent_ES (responds in Spanish)
```
</Accordion>
<Accordion title="3. Quality assurance workflows">
```
Group: "Customer Support"
Agents:
- SupportAgent (provides answer)
- QAAgent (reviews quality, only responds if issues found)
```
</Accordion>
<Accordion title="4. Task automation">
```
Group: "Project Management"
Agents:
- TaskTracker (updates task database)
- TimeLogger (logs time spent)
- ReportGenerator (creates summaries)
```
</Accordion>
</AccordionGroup>
## 設定
### 基本設定
新增頂層 `broadcast` 區段（與 `bindings` 並列）。鍵是 WhatsApp 對等端 ID：
- 群組聊天：群組 JID（例如 `120363403215116621@g.us`）
- 私訊：E.164 電話號碼（例如 `+15551234567`）
```json
{
"broadcast": {
"120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
}
}
```
**結果：** 當 OpenClaw 會在此聊天中回覆時，它會執行全部三個代理。
### 處理策略
控制代理如何處理訊息：
<Tabs>
<Tab title="parallel (default)">
所有代理同時處理：
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
</Tab>
<Tab title="sequential">
代理依序處理（一個代理會等待前一個完成）：
```json
{
"broadcast": {
"strategy": "sequential",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
</Tab>
</Tabs>
### 完整範例
```json
{
"agents": {
"list": [
{
"id": "code-reviewer",
"name": "Code Reviewer",
"workspace": "/path/to/code-reviewer",
"sandbox": { "mode": "all" }
},
{
"id": "security-auditor",
"name": "Security Auditor",
"workspace": "/path/to/security-auditor",
"sandbox": { "mode": "all" }
},
{
"id": "docs-generator",
"name": "Documentation Generator",
"workspace": "/path/to/docs-generator",
"sandbox": { "mode": "all" }
}
]
},
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
"120363424282127706@g.us": ["support-en", "support-de"],
"+15555550123": ["assistant", "logger"]
}
}
```
## 運作方式
### 訊息流程
<Steps>
<Step title="Incoming message arrives">
WhatsApp 群組或私訊訊息抵達。
</Step>
<Step title="Broadcast check">
系統檢查對等端 ID 是否在 `broadcast` 中。
</Step>
<Step title="If in broadcast list">
- 所有列出的代理都會處理該訊息。
- 每個代理都有自己的工作階段鍵與隔離的情境。
- 代理會平行處理（預設）或依序處理。
</Step>
<Step title="If not in broadcast list">
套用一般路由（第一個相符的繫結）。
</Step>
</Steps>
<Note>
廣播群組不會繞過通道允許清單或群組啟用規則（提及／命令等）。它們只會在訊息符合處理資格時，變更_哪些代理會執行_。
</Note>
### 工作階段隔離
廣播群組中的每個代理都會維持完全獨立的：
- **工作階段鍵**（`agent:alfred:whatsapp:group:120363...` 相對於 `agent:baerbel:whatsapp:group:120363...`）
- **對話歷史**（代理看不到其他代理的訊息）
- **工作區**（如有設定，則使用獨立沙箱）
- **工具存取權**（不同的允許／拒絕清單）
- **記憶／情境**（獨立的 IDENTITY.md、SOUL.md 等）
- **群組情境緩衝區**（用於情境的近期群組訊息）會依對等端共享，因此所有廣播代理在觸發時都會看到相同情境
這讓每個代理都能擁有：
- 不同個性
- 不同工具存取權（例如唯讀與可讀寫）
- 不同模型（例如 opus 與 sonnet）
- 安裝不同 Skills
### 範例：隔離的工作階段
在群組 `120363403215116621@g.us` 中，代理為 `["alfred", "baerbel"]`：
<Tabs>
<Tab title="Alfred's context">
```
Session: agent:alfred:whatsapp:group:120363403215116621@g.us
History: [user message, alfred's previous responses]
Workspace: /Users/user/openclaw-alfred/
Tools: read, write, exec
```
</Tab>
<Tab title="Bärbel's context">
```
Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
History: [user message, baerbel's previous responses]
Workspace: /Users/user/openclaw-baerbel/
Tools: read only
```
</Tab>
</Tabs>
## 最佳實務
<AccordionGroup>
<Accordion title="1. Keep agents focused">
以單一、明確的職責設計每個代理：
```json
{
"broadcast": {
"DEV_GROUP": ["formatter", "linter", "tester"]
}
}
```
✅ **良好：** 每個代理都有一項工作。❌ **不佳：** 一個通用的「dev-helper」代理。
</Accordion>
<Accordion title="2. Use descriptive names">
讓每個代理的用途清楚明瞭：
```json
{
"agents": {
"security-scanner": { "name": "Security Scanner" },
"code-formatter": { "name": "Code Formatter" },
"test-generator": { "name": "Test Generator" }
}
}
```
</Accordion>
<Accordion title="3. Configure different tool access">
只提供代理所需的工具：
```json
{
"agents": {
"reviewer": {
"tools": { "allow": ["read", "exec"] } // Read-only
},
"fixer": {
"tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
}
}
}
```
</Accordion>
<Accordion title="4. Monitor performance">
使用多個代理時，請考慮：
- 使用 `"strategy": "parallel"`（預設）以提高速度
- 將廣播群組限制為 5 到 10 個代理
- 為較簡單的代理使用較快的模型
</Accordion>
<Accordion title="5. Handle failures gracefully">
代理會獨立失敗。一個代理的錯誤不會阻擋其他代理：
```
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Result: Agent A and C respond, Agent B logs error
```
</Accordion>
</AccordionGroup>
## 相容性
### 提供者
廣播群組目前可搭配：
- ✅ WhatsApp（已實作）
- 🚧 Telegram（規劃中）
- 🚧 Discord（規劃中）
- 🚧 Slack（規劃中）
### 路由
廣播群組可與現有路由並用：
```json
{
"bindings": [
{
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
"agentId": "alfred"
}
],
"broadcast": {
"GROUP_B": ["agent1", "agent2"]
}
}
```
- `GROUP_A`：只有 alfred 回應（一般路由）。
- `GROUP_B`：agent1 和 agent2 都會回應（廣播）。
<Note>
**優先順序：** `broadcast` 優先於 `bindings`。
</Note>
## 疑難排解
<AccordionGroup>
<Accordion title="Agents not responding">
**檢查：**
1. 代理 ID 存在於 `agents.list`。
2. 對等端 ID 格式正確（例如 `120363403215116621@g.us`）。
3. 代理不在拒絕清單中。
**偵錯：**
```bash
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
```
</Accordion>
<Accordion title="Only one agent responding">
**原因：** 對等端 ID 可能在 `bindings` 中，但不在 `broadcast` 中。
**修正：** 新增到廣播設定，或從繫結中移除。
</Accordion>
<Accordion title="Performance issues">
如果多個代理導致速度緩慢：
- 減少每個群組的代理數量。
- 使用較輕量的模型（使用 sonnet 而非 opus）。
- 檢查沙箱啟動時間。
</Accordion>
</AccordionGroup>
## 範例
<AccordionGroup>
<Accordion title="Example 1: Code review team">
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": [
"code-formatter",
"security-scanner",
"test-coverage",
"docs-checker"
]
},
"agents": {
"list": [
{
"id": "code-formatter",
"workspace": "~/agents/formatter",
"tools": { "allow": ["read", "write"] }
},
{
"id": "security-scanner",
"workspace": "~/agents/security",
"tools": { "allow": ["read", "exec"] }
},
{
"id": "test-coverage",
"workspace": "~/agents/testing",
"tools": { "allow": ["read", "exec"] }
},
{ "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
]
}
}
```
**使用者傳送：** 程式碼片段。
**回應：**
- code-formatter：「已修正縮排並加入型別提示」
- security-scanner：「⚠️ 第 12 行有 SQL injection 弱點」
- test-coverage：「覆蓋率為 45%，缺少錯誤案例的測試」
- docs-checker：「函式 `process_data` 缺少 docstring」
</Accordion>
<Accordion title="Example 2: Multi-language support">
```json
{
"broadcast": {
"strategy": "sequential",
"+15555550123": ["detect-language", "translator-en", "translator-de"]
},
"agents": {
"list": [
{ "id": "detect-language", "workspace": "~/agents/lang-detect" },
{ "id": "translator-en", "workspace": "~/agents/translate-en" },
{ "id": "translator-de", "workspace": "~/agents/translate-de" }
]
}
}
```
</Accordion>
</AccordionGroup>
## API 參考
### 設定綱要
```typescript
interface OpenClawConfig {
broadcast?: {
strategy?: "parallel" | "sequential";
[peerId: string]: string[];
};
}
```
### 欄位
<ParamField path="strategy" type='"parallel" | "sequential"' default='"parallel"'>
如何處理代理。`parallel` 會同時執行所有代理；`sequential` 會依陣列順序執行它們。
</ParamField>
<ParamField path="[peerId]" type="string[]">
WhatsApp 群組 JID、E.164 號碼，或其他對等端 ID。值是應處理訊息的代理 ID 陣列。
</ParamField>
## 限制
1. **代理上限：** 沒有硬性限制，但 10 個以上的代理可能會較慢。
2. **共享情境：** 代理看不到彼此的回應（這是刻意設計）。
3. **訊息排序：** 平行回應可能以任何順序抵達。
4. **速率限制：** 所有代理都會計入 WhatsApp 速率限制。
## 未來增強
規劃中的功能：
- [ ] 共享情境模式（代理可看到彼此的回應）
- [ ] 代理協調（代理可彼此發送訊號）
- [ ] 動態代理選擇（根據訊息內容選擇代理）
- [ ] 代理優先順序（某些代理會先於其他代理回應）
## 相關內容
- [通道路由](/zh-TW/channels/channel-routing)
- [群組](/zh-TW/channels/groups)
- [多代理沙箱工具](/zh-TW/tools/multi-agent-sandbox-tools)
- [配對](/zh-TW/channels/pairing)
- [工作階段管理](/zh-TW/concepts/session)

157
docs/zh-TW/channels/channel-routing.md Normal file
View File

@ -0,0 +1,157 @@
---
read_when:
- 變更頻道路由或收件匣行為
summary: 每個通道（WhatsApp、Telegram、Discord、Slack）的路由規則和共用上下文
title: 通道路由
x-i18n:
generated_at: "2026-04-30T02:46:00Z"
model: gpt-5.5
provider: openai
source_hash: c43347048fcfd137cc3a0b2cfdc4cf36426fdcf9645f2d1a05ce9cf49688cf0d
source_path: channels/channel-routing.md
workflow: 16
---
# 頻道與路由
OpenClaw 會將回覆路由**回訊息來源的頻道**。模型不會選擇頻道；路由是確定性的，並由主機設定控制。
## 關鍵術語
- **頻道**：`telegram`、`whatsapp`、`discord`、`irc`、`googlechat`、`slack`、`signal`、`imessage`、`line`，以及 Plugin 頻道。`webchat` 是內部 WebChat UI 頻道，不是可設定的對外頻道。
- **AccountId**：每個頻道的帳號實例（支援時）。
- 選用的頻道預設帳號：`channels.<channel>.defaultAccount` 會選擇
當對外路徑未指定 `accountId` 時使用哪個帳號。
- 在多帳號設定中，當設定了兩個以上帳號時，請設定明確的預設值（`defaultAccount` 或 `accounts.default`）。若未設定，後援路由可能會選擇第一個正規化的帳號 ID。
- **AgentId**：隔離的工作區 + 工作階段儲存區（「大腦」）。
- **SessionKey**：用於儲存脈絡並控制並行性的桶鍵。
## 工作階段鍵形狀（範例）
直接訊息預設會折疊到代理的 **main** 工作階段：
- `agent:<agentId>:<mainKey>`（預設：`agent:main:main`）
即使直接訊息對話歷史與 main 共用，沙盒與工具政策仍會針對外部 DM 使用衍生的每帳號直接聊天執行階段鍵，
因此來自頻道的訊息不會被視為本機 main 工作階段執行。
群組與頻道會依頻道維持隔離：
- 群組：`agent:<agentId>:<channel>:group:<id>`
- 頻道/聊天室：`agent:<agentId>:<channel>:channel:<id>`
執行緒：
- Slack/Discord 執行緒會將 `:thread:<threadId>` 附加到基礎鍵。
- Telegram 論壇主題會在群組鍵中嵌入 `:topic:<topicId>`。
範例：
- `agent:main:telegram:group:-1001234567890:topic:42`
- `agent:main:discord:channel:123456:thread:987654`
## Main DM 路由釘選
當 `session.dmScope` 為 `main` 時，直接訊息可能會共用一個 main 工作階段。
為了防止工作階段的 `lastRoute` 被非擁有者 DM 覆寫，
當下列條件全部成立時，OpenClaw 會從 `allowFrom` 推斷釘選擁有者：
- `allowFrom` 恰好有一個非萬用字元項目。
- 該項目可正規化為該頻道的具體寄件者 ID。
- 傳入的 DM 寄件者不符合該釘選擁有者。
在這種不相符的情況下，OpenClaw 仍會記錄傳入工作階段中繼資料，但會
略過更新 main 工作階段的 `lastRoute`。
## 受保護的傳入記錄
當受保護路徑不得建立新的 OpenClaw 工作階段時，頻道 Plugin 可將傳入工作階段記錄標示為 `createIfMissing: false`。
在此模式下，OpenClaw 可能會更新既有工作階段的中繼資料與 `lastRoute`，但不會
只因為觀察到訊息就建立僅含路由的工作階段項目。
## 路由規則（如何選擇代理）
路由會為每則傳入訊息選擇**一個代理**：
1. **精確對等方符合**（含 `peer.kind` + `peer.id` 的 `bindings`）。
2. **父對等方符合**（執行緒繼承）。
3. **Guild + 角色符合**（Discord），透過 `guildId` + `roles`。
4. **Guild 符合**（Discord），透過 `guildId`。
5. **團隊符合**（Slack），透過 `teamId`。
6. **帳號符合**（頻道上的 `accountId`）。
7. **頻道符合**（該頻道上的任何帳號，`accountId: "*"`）。
8. **預設代理**（`agents.list[].default`，否則第一個清單項目，後援為 `main`）。
當綁定包含多個符合欄位（`peer`、`guildId`、`teamId`、`roles`）時，**所有提供的欄位都必須符合**，該綁定才會套用。
符合的代理會決定要使用哪個工作區與工作階段儲存區。
## 廣播群組（執行多個代理）
廣播群組可讓你針對同一個對等方**執行多個代理**，條件是 **OpenClaw 通常會回覆**（例如：在 WhatsApp 群組中，通過提及/啟用閘門之後）。
設定：
```json5
{
broadcast: {
strategy: "parallel",
"120363403215116621@g.us": ["alfred", "baerbel"],
"+15555550123": ["support", "logger"],
},
}
```
請參閱：[廣播群組](/zh-TW/channels/broadcast-groups)。
## 設定概覽
- `agents.list`：具名代理定義（工作區、模型等）。
- `bindings`：將傳入頻道/帳號/對等方對應到代理。
範例：
```json5
{
agents: {
list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
},
bindings: [
{ match: { channel: "slack", teamId: "T123" }, agentId: "support" },
{ match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
],
}
```
## 工作階段儲存
工作階段儲存區位於狀態目錄下（預設為 `~/.openclaw`）：
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- JSONL 逐字稿會與儲存區並列存放
你可以透過 `session.store` 與 `{agentId}` 模板化覆寫儲存區路徑。
Gateway 與 ACP 工作階段探索也會掃描預設 `agents/` 根目錄下，以及模板化 `session.store` 根目錄下的磁碟支援代理儲存區。探索到的
儲存區必須維持在該解析後的代理根目錄內，並使用一般的
`sessions.json` 檔案。符號連結與根目錄外路徑會被忽略。
## WebChat 行為
WebChat 會附加到**選取的代理**，並預設使用該代理的 main
工作階段。因此，WebChat 可讓你在同一處查看該代理的跨頻道脈絡。
## 回覆脈絡
傳入回覆會包含：
- 可用時包含 `ReplyToId`、`ReplyToBody` 與 `ReplyToSender`。
- 引用脈絡會作為 `[Replying to ...]` 區塊附加到 `Body`。
這在各頻道之間保持一致。
## 相關
- [群組](/zh-TW/channels/groups)
- [廣播群組](/zh-TW/channels/broadcast-groups)
- [配對](/zh-TW/channels/pairing)

1267
docs/zh-TW/channels/discord.md Normal file
View File

File diff suppressed because it is too large Load Diff

485
docs/zh-TW/channels/feishu.md Normal file
View File

@ -0,0 +1,485 @@
---
read_when:
- 你想要連接 Feishu/Lark 機器人
- 你正在設定 Feishu 頻道
summary: Feishu 機器人概觀、功能和設定
title: 飛書
x-i18n:
generated_at: "2026-04-30T02:46:17Z"
model: gpt-5.5
provider: openai
source_hash: 37de7cbb12821f119ca1a06fcdb8e80a07752e1cbfc462344d24750fbf13147a
source_path: channels/feishu.md
workflow: 16
---
# Feishu / Lark
Feishu/Lark 是一站式協作平台，團隊可以在其中聊天、共享文件、管理行事曆，並共同完成工作。
**狀態：** 已可用於生產環境的機器人私訊與群組聊天。WebSocket 是預設模式；Webhook 模式為選用。
---
## 快速開始
<Note>
需要 OpenClaw 2026.4.25 或以上版本。執行 `openclaw --version` 檢查版本。使用 `openclaw update` 升級。
</Note>
<Steps>
<Step title="執行頻道設定精靈">
```bash
openclaw channels login --channel feishu
```
使用你的 Feishu/Lark 行動 App 掃描 QR code，以自動建立 Feishu/Lark 機器人。
</Step>
<Step title="設定完成後，重新啟動 gateway 以套用變更">
```bash
openclaw gateway restart
```
</Step>
</Steps>
---
## 存取控制
### 私訊
設定 `dmPolicy` 來控制誰可以私訊機器人：
- `"pairing"` — 未知使用者會收到配對碼；透過 CLI 核准
- `"allowlist"` — 只有列在 `allowFrom` 中的使用者可以聊天（預設：僅限機器人擁有者）
- `"open"` — 只有在 `allowFrom` 包含 `"*"` 時才允許公開私訊；若有較嚴格的項目，只有相符的使用者可以聊天
- `"disabled"` — 停用所有私訊
**核准配對請求：**
```bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
```
### 群組聊天
**群組政策** (`channels.feishu.groupPolicy`)：
| 值 | 行為 |
| ------------- | -------------------------------------------------------------------------------------------- |
| `"open"` | 回應群組中的所有訊息 |
| `"allowlist"` | 只回應 `groupAllowFrom` 中的群組，或明確設定於 `groups.<chat_id>` 下的群組 |
| `"disabled"` | 停用所有群組訊息；明確的 `groups.<chat_id>` 項目不會覆寫此設定 |
預設值：`allowlist`
**提及要求** (`channels.feishu.requireMention`)：
- `true` — 需要 @mention（預設）
- `false` — 不需 @mention 即可回應
- 每個群組覆寫：`channels.feishu.groups.<chat_id>.requireMention`
- 僅廣播用途的 `@all` 和 `@_all` 不會被視為機器人提及。同時提及 `@all` 與直接提及機器人的訊息，仍會算作機器人提及。
---
## 群組設定範例
### 允許所有群組，不需要 @mention
```json5
{
channels: {
feishu: {
groupPolicy: "open",
},
},
}
```
### 允許所有群組，但仍需要 @mention
```json5
{
channels: {
feishu: {
groupPolicy: "open",
requireMention: true,
},
},
}
```
### 僅允許特定群組
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
// Group IDs look like: oc_xxx
groupAllowFrom: ["oc_xxx", "oc_yyy"],
},
},
}
```
在 `allowlist` 模式中，你也可以加入明確的 `groups.<chat_id>` 項目來允許某個群組。明確項目不會覆寫 `groupPolicy: "disabled"`。`groups.*` 下的萬用字元預設值會設定相符的群組，但它們本身不會准入群組。
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
groups: {
oc_xxx: {
requireMention: false,
},
},
},
},
}
```
### 限制群組內的傳送者
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
groupAllowFrom: ["oc_xxx"],
groups: {
oc_xxx: {
// User open_ids look like: ou_xxx
allowFrom: ["ou_user1", "ou_user2"],
},
},
},
},
}
```
---
<a id="get-groupuser-ids"></a>
## 取得群組/使用者 ID
### 群組 ID（`chat_id`，格式：`oc_xxx`）
在 Feishu/Lark 中開啟群組，點擊右上角的選單圖示，然後前往 **設定**。群組 ID (`chat_id`) 會列在設定頁面上。
![取得群組 ID](/images/feishu-get-group-id.png)
### 使用者 ID（`open_id`，格式：`ou_xxx`）
啟動 Gateway，傳送私訊給機器人，然後檢查日誌：
```bash
openclaw logs --follow
```
在日誌輸出中尋找 `open_id`。你也可以檢查待處理的配對請求：
```bash
openclaw pairing list feishu
```
---
## 常用命令
| 命令 | 說明 |
| --------- | -------------------- |
| `/status` | 顯示機器人狀態 |
| `/reset` | 重設目前工作階段 |
| `/model` | 顯示或切換 AI 模型 |
<Note>
Feishu/Lark 不支援原生斜線命令選單，因此請將這些命令作為純文字訊息傳送。
</Note>
---
## 疑難排解
### 機器人在群組聊天中沒有回應
1. 確認機器人已加入群組
2. 確認你已 @mention 機器人（預設需要）
3. 確認 `groupPolicy` 不是 `"disabled"`
4. 檢查日誌：`openclaw logs --follow`
### 機器人沒有收到訊息
1. 確認機器人已在 Feishu Open Platform / Lark Developer 發布並核准
2. 確認事件訂閱包含 `im.message.receive_v1`
3. 確認已選取 **持久連線**（WebSocket）
4. 確認已授予所有必要的權限範圍
5. 確認 Gateway 正在執行：`openclaw gateway status`
6. 檢查日誌：`openclaw logs --follow`
### App Secret 外洩
1. 在 Feishu Open Platform / Lark Developer 中重設 App Secret
2. 更新你的設定中的值
3. 重新啟動 Gateway：`openclaw gateway restart`
---
## 進階設定
### 多個帳戶
```json5
{
channels: {
feishu: {
defaultAccount: "main",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
name: "Primary bot",
tts: {
providers: {
openai: { voice: "shimmer" },
},
},
},
backup: {
appId: "cli_yyy",
appSecret: "yyy",
name: "Backup bot",
enabled: false,
},
},
},
},
}
```
`defaultAccount` 控制在輸出 API 未指定 `accountId` 時使用哪個帳戶。
`accounts.<id>.tts` 使用與 `messages.tts` 相同的形狀，並會深度合併到
全域 TTS 設定之上，因此多機器人的 Feishu 設定可以在全域保留共用提供者
憑證，同時只按帳戶覆寫語音、模型、persona 或自動模式。
### 訊息限制
- `textChunkLimit` — 輸出文字區塊大小（預設：`2000` 字元）
- `mediaMaxMb` — 媒體上傳/下載限制（預設：`30` MB）
### 串流
Feishu/Lark 支援透過互動式卡片提供串流回覆。啟用後，機器人會在產生文字時即時更新卡片。
```json5
{
channels: {
feishu: {
streaming: true, // enable streaming card output (default: true)
blockStreaming: true, // enable block-level streaming (default: true)
},
},
}
```
設定 `streaming: false` 可將完整回覆作為單一訊息傳送。
### 配額最佳化
使用兩個選用旗標減少 Feishu/Lark API 呼叫次數：
- `typingIndicator`（預設 `true`）：設定為 `false` 可略過打字反應呼叫
- `resolveSenderNames`（預設 `true`）：設定為 `false` 可略過傳送者個人資料查詢
```json5
{
channels: {
feishu: {
typingIndicator: false,
resolveSenderNames: false,
},
},
}
```
### ACP 工作階段
Feishu/Lark 支援 ACP 用於私訊與群組 thread 訊息。Feishu/Lark ACP 由文字命令驅動，沒有原生斜線命令選單，因此請直接在對話中使用 `/acp ...` 訊息。
#### 持久 ACP 繫結
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: {
agent: "codex",
backend: "acpx",
mode: "persistent",
cwd: "/workspace/openclaw",
},
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "direct", id: "ou_1234567890" },
},
},
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
},
acp: { label: "codex-feishu-topic" },
},
],
}
```
#### 從聊天產生 ACP
在 Feishu/Lark 私訊或 thread 中：
```text
/acp spawn codex --thread here
```
`--thread here` 適用於私訊與 Feishu/Lark thread 訊息。繫結對話中的後續訊息會直接路由到該 ACP 工作階段。
### 多代理路由
使用 `bindings` 將 Feishu/Lark 私訊或群組路由到不同代理。
```json5
{
agents: {
list: [
{ id: "main" },
{ id: "agent-a", workspace: "/home/user/agent-a" },
{ id: "agent-b", workspace: "/home/user/agent-b" },
],
},
bindings: [
{
agentId: "agent-a",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_xxx" },
},
},
{
agentId: "agent-b",
match: {
channel: "feishu",
peer: { kind: "group", id: "oc_zzz" },
},
},
],
}
```
路由欄位：
- `match.channel`：`"feishu"`
- `match.peer.kind`：`"direct"`（私訊）或 `"group"`（群組聊天）
- `match.peer.id`：使用者 Open ID（`ou_xxx`）或群組 ID（`oc_xxx`）
請參閱[取得群組/使用者 ID](#get-groupuser-ids) 以取得查詢提示。
---
## 設定參考
完整設定：[Gateway 設定](/zh-TW/gateway/configuration)
| Setting | Description | Default |
| ------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------- |
| `channels.feishu.enabled` | 啟用/停用通道 | `true` |
| `channels.feishu.domain` | API 網域（`feishu` 或 `lark`） | `feishu` |
| `channels.feishu.connectionMode` | 事件傳輸（`websocket` 或 `webhook`） | `websocket` |
| `channels.feishu.defaultAccount` | 出站路由的預設帳戶 | `default` |
| `channels.feishu.verificationToken` | Webhook 模式必填 | — |
| `channels.feishu.encryptKey` | Webhook 模式必填 | — |
| `channels.feishu.webhookPath` | Webhook 路由路徑 | `/feishu/events` |
| `channels.feishu.webhookHost` | Webhook 綁定主機 | `127.0.0.1` |
| `channels.feishu.webhookPort` | Webhook 綁定連接埠 | `3000` |
| `channels.feishu.accounts.<id>.appId` | App ID | — |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
| `channels.feishu.accounts.<id>.domain` | 每個帳戶的網域覆寫 | `feishu` |
| `channels.feishu.accounts.<id>.tts` | 每個帳戶的 TTS 覆寫 | `messages.tts` |
| `channels.feishu.dmPolicy` | DM 政策 | `allowlist` |
| `channels.feishu.allowFrom` | DM 允許清單（open_id 清單） | [BotOwnerId] |
| `channels.feishu.groupPolicy` | 群組政策 | `allowlist` |
| `channels.feishu.groupAllowFrom` | 群組允許清單 | — |
| `channels.feishu.requireMention` | 群組中需要 @提及 | `true` |
| `channels.feishu.groups.<chat_id>.requireMention` | 每個群組的 @提及覆寫；明確 ID 也會在允許清單模式中允許該群組 | 繼承 |
| `channels.feishu.groups.<chat_id>.enabled` | 啟用/停用特定群組 | `true` |
| `channels.feishu.textChunkLimit` | 訊息分塊大小 | `2000` |
| `channels.feishu.mediaMaxMb` | 媒體大小限制 | `30` |
| `channels.feishu.streaming` | 串流卡片輸出 | `true` |
| `channels.feishu.blockStreaming` | 區塊層級串流 | `true` |
| `channels.feishu.typingIndicator` | 傳送輸入中反應 | `true` |
| `channels.feishu.resolveSenderNames` | 解析傳送者顯示名稱 | `true` |
---
## 支援的訊息類型
### 接收
- ✅ 文字
- ✅ 富文字（貼文）
- ✅ 圖片
- ✅ 檔案
- ✅ 音訊
- ✅ 影片/媒體
- ✅ 貼圖
傳入的 Feishu/Lark 音訊訊息會正規化為媒體預留位置，而不是原始 `file_key` JSON。設定 `tools.media.audio` 時，OpenClaw 會下載語音備註資源，並在代理程式回合前執行共用音訊轉錄，因此代理程式會收到語音轉錄稿。如果 Feishu 直接在音訊承載中包含轉錄文字，則會使用該文字而不再進行另一次 ASR 呼叫。若沒有音訊轉錄提供者，代理程式仍會收到 `<media:audio>` 預留位置加上已儲存的附件，而不是原始 Feishu 資源承載。
### 傳送
- ✅ 文字
- ✅ 圖片
- ✅ 檔案
- ✅ 音訊
- ✅ 影片/媒體
- ✅ 互動式卡片（包含串流更新）
- ⚠️ 富文字（貼文樣式格式；不支援完整的 Feishu/Lark 撰寫功能）
原生 Feishu/Lark 音訊泡泡會使用 Feishu `audio` 訊息類型，並需要 Ogg/Opus 上傳媒體（`file_type: "opus"`）。既有的 `.opus` 和 `.ogg` 媒體會直接作為原生音訊傳送。只有在回覆要求語音傳送（`audioAsVoice` / 訊息工具 `asVoice`，包含 TTS 語音備註回覆）時，MP3/WAV/M4A 和其他可能的音訊格式才會使用 `ffmpeg` 轉碼為 48kHz Ogg/Opus。一般 MP3 附件會保留為一般檔案。如果缺少 `ffmpeg` 或轉換失敗，OpenClaw 會退回為檔案附件並記錄原因。
### 討論串與回覆
- ✅ 行內回覆
- ✅ 討論串回覆
- ✅ 回覆討論串訊息時，媒體回覆會保留討論串感知
對於 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 主題群組會使用事件 `thread_id`（`omt_*`）作為標準主題工作階段鍵。OpenClaw 轉成討論串的一般群組回覆會繼續使用回覆根訊息 ID（`om_*`），因此第一回合與後續回合會保留在同一個工作階段中。
---
## 相關
- [通道總覽](/zh-TW/channels) — 所有支援的通道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及門檻
- [通道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

275
docs/zh-TW/channels/googlechat.md Normal file
View File

@ -0,0 +1,275 @@
---
read_when:
- 正在開發 Google Chat 通道功能
summary: Google Chat 應用程式支援狀態、功能與設定
title: Google Chat
x-i18n:
generated_at: "2026-04-30T02:46:20Z"
model: gpt-5.5
provider: openai
source_hash: eacc27c89fd563abab6214912687e0f15c80c7d3e652e9159bf8b43190b0886a
source_path: channels/googlechat.md
workflow: 16
---
Status：已可透過 Google Chat API Webhook（僅 HTTP）用於 DM + space。
## 快速設定（初學者）
1. 建立 Google Cloud 專案並啟用 **Google Chat API**。
- 前往：[Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- 如果尚未啟用 API，請啟用它。
2. 建立 **Service Account**：
- 按 **Create Credentials** > **Service Account**。
- 依喜好命名（例如 `openclaw-chat`）。
- 權限留空（按 **Continue**）。
- 可存取的主體留空（按 **Done**）。
3. 建立並下載 **JSON Key**：
- 在 Service Account 清單中，點選你剛建立的那一個。
- 前往 **Keys** 分頁。
- 點選 **Add Key** > **Create new key**。
- 選取 **JSON** 並按 **Create**。
4. 將下載的 JSON 檔案儲存在你的 Gateway 主機上（例如 `~/.openclaw/googlechat-service-account.json`）。
5. 在 [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中建立 Google Chat 應用程式：
- 填寫 **Application info**：
- **App name**：（例如 `OpenClaw`）
- **Avatar URL**：（例如 `https://openclaw.ai/logo.png`）
- **Description**：（例如 `Personal AI Assistant`）
- 啟用 **Interactive features**。
- 在 **Functionality** 下，勾選 **Join spaces and group conversations**。
- 在 **Connection settings** 下，選取 **HTTP endpoint URL**。
- 在 **Triggers** 下，選取 **Use a common HTTP endpoint URL for all triggers**，並將其設為你的 Gateway 公開 URL，後面接 `/googlechat`。
- _提示：執行 `openclaw status` 以尋找你的 Gateway 公開 URL。_
- 在 **Visibility** 下，勾選 **Make this Chat app available to specific people and groups in `<Your Domain>`**。
- 在文字方塊中輸入你的電子郵件地址（例如 `user@example.com`）。
- 點選底部的 **Save**。
6. **啟用應用程式狀態**：
- 儲存後，**重新整理頁面**。
- 尋找 **App status** 區段（儲存後通常在頁面上方或下方附近）。
- 將狀態變更為 **Live - available to users**。
- 再次點選 **Save**。
7. 使用 Service Account 路徑 + Webhook audience 設定 OpenClaw：
- Env：`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
- 或 config：`channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。
8. 設定 Webhook audience 類型 + 值（需符合你的 Chat 應用程式設定）。
9. 啟動 Gateway。Google Chat 會將 POST 傳送到你的 Webhook 路徑。
## 新增到 Google Chat
Gateway 執行中且你的電子郵件已新增至可見性清單後：
1. 前往 [Google Chat](https://chat.google.com/)。
2. 點選 **Direct Messages** 旁的 **+**（加號）圖示。
3. 在搜尋列（你通常新增使用者的位置）中，輸入你在 Google Cloud Console 中設定的 **App name**。
- **注意**：機器人不會出現在「Marketplace」瀏覽清單中，因為它是私人應用程式。你必須依名稱搜尋它。
4. 從結果中選取你的機器人。
5. 點選 **Add** 或 **Chat** 以開始 1:1 對話。
6. 傳送「Hello」以觸發助理！
## 公開 URL（僅 Webhook）
Google Chat Webhook 需要公開 HTTPS 端點。為了安全性，**只將 `/googlechat` 路徑暴露到網際網路**。請將 OpenClaw 儀表板與其他敏感端點保留在你的私人網路上。
### 選項 A：Tailscale Funnel（建議）
使用 Tailscale Serve 提供私人儀表板，並使用 Funnel 提供公開 Webhook 路徑。這會讓 `/` 保持私有，同時只暴露 `/googlechat`。
1. **檢查你的 Gateway 綁定到哪個位址：**
```bash
ss -tlnp | grep 18789
```
注意 IP 位址（例如 `127.0.0.1`、`0.0.0.0`，或你的 Tailscale IP，例如 `100.x.x.x`）。
2. **只將儀表板暴露給 tailnet（連接埠 8443）：**
```bash
# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789
# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789
```
3. **只公開暴露 Webhook 路徑：**
```bash
# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
```
4. **授權 Node 以取得 Funnel 存取權：**
如果出現提示，請造訪輸出中顯示的授權 URL，以在你的 tailnet policy 中為此 Node 啟用 Funnel。
5. **驗證設定：**
```bash
tailscale serve status
tailscale funnel status
```
你的公開 Webhook URL 會是：
`https://<node-name>.<tailnet>.ts.net/googlechat`
你的私人儀表板會維持僅限 tailnet：
`https://<node-name>.<tailnet>.ts.net:8443/`
在 Google Chat 應用程式設定中使用公開 URL（不含 `:8443`）。
> 注意：此設定會在重新開機後保留。若要稍後移除它，請執行 `tailscale funnel reset` 和 `tailscale serve reset`。
### 選項 B：反向 Proxy（Caddy）
如果你使用像 Caddy 這樣的反向 Proxy，只 Proxy 特定路徑：
```caddy
your-domain.com {
reverse_proxy /googlechat* localhost:18789
}
```
使用此 config 時，任何對 `your-domain.com/` 的請求都會被忽略或傳回 404，而 `your-domain.com/googlechat` 會安全地路由到 OpenClaw。
### 選項 C：Cloudflare Tunnel
設定你的 tunnel ingress 規則，只路由 Webhook 路徑：
- **Path**：`/googlechat` -> `http://localhost:18789/googlechat`
- **Default Rule**：HTTP 404（Not Found）
## 運作方式
1. Google Chat 會將 Webhook POST 傳送到 Gateway。每個請求都包含 `Authorization: Bearer <token>` 標頭。
- OpenClaw 會在讀取/剖析完整 Webhook body 之前，先在標頭存在時驗證 bearer auth。
- 支援在 body 中攜帶 `authorizationEventObject.systemIdToken` 的 Google Workspace Add-on 請求，並使用更嚴格的 pre-auth body budget。
2. OpenClaw 會依設定的 `audienceType` + `audience` 驗證 token：
- `audienceType: "app-url"` → audience 是你的 HTTPS Webhook URL。
- `audienceType: "project-number"` → audience 是 Cloud 專案編號。
3. 訊息會依 space 路由：
- DM 使用 session key `agent:<agentId>:googlechat:direct:<spaceId>`。
- Space 使用 session key `agent:<agentId>:googlechat:group:<spaceId>`。
4. DM 存取預設使用 pairing。未知傳送者會收到 pairing code；使用下列指令核准：
- `openclaw pairing approve googlechat <code>`
5. 群組 space 預設需要 @-mention。如果提及偵測需要應用程式的使用者名稱，請使用 `botUser`。
## 目標
使用這些識別碼進行傳送與 allowlist：
- 直接訊息：`users/<userId>`（建議）。
- 原始電子郵件 `name@example.com` 是可變的，且只有在 `channels.googlechat.dangerouslyAllowNameMatching: true` 時才用於直接 allowlist 比對。
- 已棄用：`users/<email>` 會被視為使用者 ID，而不是電子郵件 allowlist。
- Space：`spaces/<spaceId>`。
## Config 重點
```json5
{
channels: {
googlechat: {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
// or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
botUser: "users/1234567890", // optional; helps mention detection
dm: {
policy: "pairing",
allowFrom: ["users/1234567890"],
},
groupPolicy: "allowlist",
groups: {
"spaces/AAAA": {
allow: true,
requireMention: true,
users: ["users/1234567890"],
systemPrompt: "Short answers only.",
},
},
actions: { reactions: true },
typingIndicator: "message",
mediaMaxMb: 20,
},
},
}
```
注意：
- Service Account 認證也可以用 `serviceAccount`（JSON 字串）內嵌傳入。
- 也支援 `serviceAccountRef`（env/file SecretRef），包含 `channels.googlechat.accounts.<id>.serviceAccountRef` 下的個別 account ref。
- 如果未設定 `webhookPath`，預設 Webhook 路徑是 `/googlechat`。
- `dangerouslyAllowNameMatching` 會重新啟用 allowlist 的可變電子郵件主體比對（緊急相容模式）。
- 啟用 `actions.reactions` 時，可透過 `reactions` 工具與 `channels action` 使用 reaction。
- 訊息 action 會公開 `send` 以傳送文字，以及 `upload-file` 以明確傳送附件。`upload-file` 接受 `media` / `filePath` / `path`，以及可選的 `message`、`filename` 和 thread target。
- `typingIndicator` 支援 `none`、`message`（預設）和 `reaction`（reaction 需要使用者 OAuth）。
- 附件會透過 Chat API 下載，並儲存在 media pipeline 中（大小受 `mediaMaxMb` 限制）。
Secrets 參照詳細資訊：[Secrets Management](/zh-TW/gateway/secrets)。
## 疑難排解
### 405 Method Not Allowed
如果 Google Cloud Logs Explorer 顯示如下錯誤：
```
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
```
這表示尚未註冊 Webhook handler。常見原因：
1. **尚未設定 channel**：你的 config 中缺少 `channels.googlechat` 區段。使用下列指令驗證：
```bash
openclaw config get channels.googlechat
```
如果傳回「Config path not found」，請新增設定（見 [Config 重點](#config-highlights)）。
2. **Plugin 未啟用**：檢查 Plugin 狀態：
```bash
openclaw plugins list | grep googlechat
```
如果顯示「disabled」，請將 `plugins.entries.googlechat.enabled: true` 新增到你的 config。
3. **Gateway 未重新啟動**：新增 config 後，重新啟動 Gateway：
```bash
openclaw gateway restart
```
確認 channel 正在執行：
```bash
openclaw channels status
# Should show: Google Chat default: enabled, configured, ...
```
### 其他問題
- 檢查 `openclaw channels status --probe` 是否有 auth 錯誤或缺少 audience config。
- 如果沒有收到訊息，請確認 Chat 應用程式的 Webhook URL + 事件訂閱。
- 如果 mention gating 阻擋回覆，請將 `botUser` 設為應用程式的使用者資源名稱，並驗證 `requireMention`。
- 傳送測試訊息時使用 `openclaw logs --follow`，查看請求是否抵達 Gateway。
相關文件：
- [Gateway configuration](/zh-TW/gateway/configuration)
- [Security](/zh-TW/gateway/security)
- [Reactions](/zh-TW/tools/reactions)
## 相關
- [Channels Overview](/zh-TW/channels) — 所有支援的 channel
- [Pairing](/zh-TW/channels/pairing) — DM 驗證與 pairing 流程
- [Groups](/zh-TW/channels/groups) — 群組聊天行為與 mention gating
- [Channel Routing](/zh-TW/channels/channel-routing) — 訊息的 session 路由
- [Security](/zh-TW/gateway/security) — 存取模型與強化

97
docs/zh-TW/channels/group-messages.md Normal file
View File

@ -0,0 +1,97 @@
---
read_when:
- 變更群組訊息規則或提及
summary: WhatsApp 群組訊息處理的行為與設定（mentionPatterns 會跨各介面共用）
title: 群組訊息
x-i18n:
generated_at: "2026-04-30T02:46:41Z"
model: gpt-5.5
provider: openai
source_hash: eb7713f83b3bf309336c4b09add17835b13facb17a5a1e3db48c25d892988ee4
source_path: channels/group-messages.md
workflow: 16
---
目標：讓 Clawd 待在 WhatsApp 群組中，只在被 ping 時喚醒，並將該討論串與個人 DM 工作階段分開。
<Note>
`agents.list[].groupChat.mentionPatterns` 也會由 Telegram、Discord、Slack 和 iMessage 使用。本文件聚焦於 WhatsApp 專屬行為。對於多代理設定，請為每個代理設定 `agents.list[].groupChat.mentionPatterns`，或使用 `messages.groupChat.mentionPatterns` 作為全域後援。
</Note>
## 目前實作（2025-12-03）
- 啟用模式：`mention`（預設）或 `always`。`mention` 需要 ping（透過 `mentionedJids` 的真實 WhatsApp @提及、安全的 regex 模式，或文字中任何位置的機器人 E.164）。`always` 會在每則訊息喚醒代理，但只有在能提供有意義價值時才應回覆；否則會回傳精確的靜默權杖 `NO_REPLY` / `no_reply`。預設值可在設定（`channels.whatsapp.groups`）中設定，並可透過 `/activation` 針對每個群組覆寫。設定 `channels.whatsapp.groups` 時，它也會作為群組允許清單（包含 `"*"` 以允許全部）。
- 群組政策：`channels.whatsapp.groupPolicy` 控制是否接受群組訊息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（後援：明確的 `channels.whatsapp.allowFrom`）。預設為 `allowlist`（在你加入寄件者前會封鎖）。
- 每群組工作階段：工作階段鍵看起來像 `agent:<agentId>:whatsapp:group:<jid>`，因此像 `/verbose on`、`/trace on` 或 `/think high` 這類命令（以獨立訊息傳送）會限定於該群組；個人 DM 狀態不受影響。群組討論串會略過 Heartbeat。
- 脈絡注入：**僅待處理**的群組訊息（預設 50 則）若_未_觸發執行，會加上 `[Chat messages since your last reply - for context]` 前綴，觸發行則放在 `[Current message - respond to this]` 之下。已在工作階段中的訊息不會重新注入。
- 寄件者呈現：每個群組批次現在都會以 `[from: Sender Name (+E164)]` 結尾，讓 Pi 知道誰正在說話。
- 臨時／僅檢視一次：我們會先展開這些訊息再擷取文字／提及，因此其中的 ping 仍會觸發。
- 群組系統提示：在群組工作階段的第一輪（以及每次 `/activation` 變更模式時），我們會向系統提示注入一段簡短說明，例如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` 如果無法取得中繼資料，我們仍會告知代理這是群組聊天。
## 設定範例（WhatsApp）
將 `groupChat` 區塊加入 `~/.openclaw/openclaw.json`，如此即使 WhatsApp 從文字本文中移除視覺上的 `@`，顯示名稱 ping 仍可運作：
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
},
},
},
agents: {
list: [
{
id: "main",
groupChat: {
historyLimit: 50,
mentionPatterns: ["@?openclaw", "\\+?15555550123"],
},
},
],
},
}
```
注意事項：
- regex 不區分大小寫，並使用與其他設定 regex 介面相同的 safe-regex 防護措施；無效模式和不安全的巢狀重複會被忽略。
- 當有人點選聯絡人時，WhatsApp 仍會透過 `mentionedJids` 傳送標準提及，因此很少需要號碼後援，但它是有用的安全網。
### 啟用命令（僅限擁有者）
使用群組聊天命令：
- `/activation mention`
- `/activation always`
只有擁有者號碼（來自 `channels.whatsapp.allowFrom`，或未設定時為機器人自己的 E.164）可以變更此設定。在群組中以獨立訊息傳送 `/status`，即可查看目前的啟用模式。
## 使用方式
1. 將你的 WhatsApp 帳號（執行 OpenClaw 的那個）加入群組。
2. 說 `@openclaw …`（或包含該號碼）。除非你設定 `groupPolicy: "open"`，否則只有允許清單中的寄件者可以觸發它。
3. 代理提示會包含最近的群組脈絡，加上尾隨的 `[from: …]` 標記，讓它能對正確的人回應。
4. 工作階段層級指令（`/verbose on`、`/trace on`、`/think high`、`/new` 或 `/reset`、`/compact`）只會套用到該群組的工作階段；請將它們作為獨立訊息傳送，讓它們能被註冊。你的個人 DM 工作階段會保持獨立。
## 測試／驗證
- 手動煙霧測試：
- 在群組中傳送 `@openclaw` ping，並確認回覆引用了寄件者名稱。
- 傳送第二次 ping，並確認歷史區塊已包含其中，且在下一輪被清除。
- 檢查 Gateway 記錄（使用 `--verbose` 執行），查看顯示 `from: <groupJid>` 和 `[from: …]` 後綴的 `inbound web message` 項目。
## 已知考量
- 群組會刻意略過 Heartbeat，以避免吵雜的廣播。
- 回音抑制使用合併後的批次字串；如果你傳送兩次相同文字且沒有提及，只有第一次會收到回覆。
- 工作階段儲存項目會在工作階段儲存中顯示為 `agent:<agentId>:whatsapp:group:<jid>`（預設為 `~/.openclaw/agents/<agentId>/sessions/sessions.json`）；缺少項目只代表該群組尚未觸發執行。
- 群組中的輸入指示器遵循 `agents.defaults.typingMode`。當可見回覆使用預設的僅訊息工具模式時，預設會立即開始輸入，因此即使沒有發佈自動最終回覆，群組成員也能看到代理正在工作。明確的輸入模式設定仍會優先。
## 相關
- [群組](/zh-TW/channels/groups)
- [通道路由](/zh-TW/channels/channel-routing)
- [廣播群組](/zh-TW/channels/broadcast-groups)

496
docs/zh-TW/channels/groups.md Normal file
View File

@ -0,0 +1,496 @@
---
read_when:
- 變更群組聊天行為或提及閘控
sidebarTitle: Groups
summary: 跨各介面的群組聊天行為 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: 群組
x-i18n:
generated_at: "2026-04-30T02:46:45Z"
model: gpt-5.5
provider: openai
source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998
source_path: channels/groups.md
workflow: 16
---
OpenClaw 在各個介面上一致地處理群組聊天：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
## 初學者簡介（2 分鐘）
OpenClaw「存在」於你自己的訊息帳號中。沒有獨立的 WhatsApp bot 使用者。如果**你**在某個群組中，OpenClaw 就能看見該群組並在其中回應。
預設行為：
- 群組受到限制（`groupPolicy: "allowlist"`）。
- 除非你明確停用提及閘控，否則回覆需要提及。
- 群組/頻道中的一般最終回覆預設為私人。可見的聊天室輸出會使用 `message` 工具。
換句話說：允許清單中的傳送者可以透過提及 OpenClaw 來觸發它。
<Note>
**TL;DR**
- **私訊存取**由 `*.allowFrom` 控制。
- **群組存取**由 `*.groupPolicy` + 允許清單（`*.groups`、`*.groupAllowFrom`）控制。
- **回覆觸發**由提及閘控（`requireMention`、`/activation`）控制。
</Note>
快速流程（群組訊息會發生什麼）：
```
groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
## 可見回覆
對於群組/頻道聊天室，OpenClaw 預設為 `messages.groupChat.visibleReplies: "message_tool"`。
這表示 agent 仍會處理該回合，並可更新記憶/session 狀態，但它的一般最終答案不會自動貼回聊天室。若要可見地發言，agent 會使用 `message(action=send)`。
對於直接聊天和任何其他來源回合，使用 `messages.visibleReplies: "message_tool"` 可在全域套用相同的僅工具可見回覆行為。`messages.groupChat.visibleReplies` 仍是群組/頻道聊天室更具體的覆寫設定。
這取代了舊模式，也就是強迫模型在多數潛伏模式回合中回答 `NO_REPLY`。在僅工具模式中，沒有任何可見動作只代表沒有呼叫 message 工具。
agent 在僅工具模式下工作時仍會傳送輸入指示器。這些回合的預設群組輸入模式會從「message」升級為「instant」，因為在 agent 決定是否呼叫 message 工具之前，可能永遠不會有一般 assistant 訊息文字。明確的輸入模式設定仍會優先。
若要恢復群組/頻道聊天室的舊版自動最終回覆：
```json5
{
messages: {
groupChat: {
visibleReplies: "automatic",
},
},
}
```
若要要求每個來源聊天的可見輸出都透過 message 工具：
```json5
{
messages: {
visibleReplies: "message_tool",
},
}
```
原生 slash commands（Discord、Telegram，以及其他支援原生命令的介面）會繞過 `visibleReplies: "message_tool"`，並一律可見回覆，讓頻道原生命令 UI 取得預期回應。這只適用於已驗證的原生命令回合；文字輸入的 `/...` 命令和一般聊天回合仍會遵循已設定的群組預設值。
## 脈絡可見性與允許清單
群組安全涉及兩種不同控制：
- **觸發授權**：誰可以觸發 agent（`groupPolicy`、`groups`、`groupAllowFrom`、頻道專屬允許清單）。
- **脈絡可見性**：哪些補充脈絡會注入模型（回覆文字、引文、討論串歷史、轉寄中繼資料）。
預設情況下，OpenClaw 會優先維持一般聊天行為，並大多保留接收到的脈絡。這表示允許清單主要決定誰可以觸發動作，而不是每個引用或歷史片段的通用遮蔽邊界。
<AccordionGroup>
<Accordion title="目前行為依頻道而異">
- 某些頻道已在特定路徑中對補充脈絡套用以傳送者為基礎的篩選（例如 Slack 討論串種子、Matrix 回覆/討論串查詢）。
- 其他頻道仍會照接收內容傳遞引用/回覆/轉寄脈絡。
</Accordion>
<Accordion title="強化方向（已規劃）">
- `contextVisibility: "all"`（預設）保留目前照接收內容處理的行為。
- `contextVisibility: "allowlist"` 會將補充脈絡篩選為允許清單中的傳送者。
- `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一個明確的引用/回覆例外。
在此強化模型於各頻道一致實作之前，預期不同介面會有差異。
</Accordion>
</AccordionGroup>
![群組訊息流程](/images/groups-flow.svg)
如果你想要...
| 目標 | 要設定的內容 |
| -------------------------------------------- | ---------------------------------------------------------- |
| 允許所有群組，但只在 @提及時回覆 | `groups: { "*": { requireMention: true } }` |
| 停用所有群組回覆 | `groupPolicy: "disabled"` |
| 只允許特定群組 | `groups: { "<group-id>": { ... } }`（沒有 `"*"` 鍵） |
| 只有你可以在群組中觸發 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
## Session 鍵
- 群組 session 使用 `agent:<agentId>:<channel>:group:<id>` session 鍵（聊天室/頻道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 論壇主題會在群組 ID 加上 `:topic:<threadId>`，因此每個主題都有自己的 session。
- 直接聊天使用主要 session（或在設定時使用每位傳送者各自的 session）。
- 群組 session 會略過 Heartbeat。
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## 模式：個人私訊 + 公開群組（單一 agent）
可以，若你的「個人」流量是**私訊**，而你的「公開」流量是**群組**，這個做法很適合。
原因：在單一 agent 模式中，私訊通常落在**主要** session 鍵（`agent:main:main`），而群組一律使用**非主要** session 鍵（`agent:main:<channel>:group:<id>`）。如果你使用 `mode: "non-main"` 啟用 sandboxing，這些群組 session 會在設定的 sandbox 後端中執行，而你的主要私訊 session 會留在主機上。如果你沒有選擇後端，Docker 是預設後端。
這會給你一個 agent「大腦」（共享工作區 + 記憶），但有兩種執行姿態：
- **私訊**：完整工具（主機）
- **群組**：sandbox + 受限工具
<Note>
如果你需要真正分離的工作區/persona（「個人」和「公開」絕不能混在一起），請使用第二個 agent + 繫結。請參閱[多 Agent 路由](/zh-TW/concepts/multi-agent)。
</Note>
<Tabs>
<Tab title="私訊在主機上，群組在 sandbox 中">
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // groups/channels are non-main -> sandboxed
scope: "session", // strongest isolation (one container per group/channel)
workspaceAccess: "none",
},
},
},
tools: {
sandbox: {
tools: {
// If allow is non-empty, everything else is blocked (deny still wins).
allow: ["group:messaging", "group:sessions"],
deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
},
},
},
}
```
</Tab>
<Tab title="群組只看得到允許清單中的資料夾">
想要「群組只能看到資料夾 X」，而不是「沒有主機存取權」？保留 `workspaceAccess: "none"`，並只將允許清單中的路徑掛載到 sandbox：
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
scope: "session",
workspaceAccess: "none",
docker: {
binds: [
// hostPath:containerPath:mode
"/home/user/FriendsShared:/data:ro",
],
},
},
},
},
}
```
</Tab>
</Tabs>
相關：
- 設定鍵與預設值：[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)
## 顯示標籤
- UI 標籤在可用時使用 `displayName`，格式為 `<channel>:<token>`。
- `#room` 保留給聊天室/頻道；群組聊天使用 `g-<slug>`（小寫、空格 -> `-`、保留 `#@+._-`）。
## 群組政策
控制每個頻道如何處理群組/聊天室訊息：
```json5
{
channels: {
whatsapp: {
groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
groupAllowFrom: ["+15551234567"],
},
telegram: {
groupPolicy: "disabled",
groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
},
signal: {
groupPolicy: "disabled",
groupAllowFrom: ["+15551234567"],
},
imessage: {
groupPolicy: "disabled",
groupAllowFrom: ["chat_id:123"],
},
msteams: {
groupPolicy: "disabled",
groupAllowFrom: ["user@org.com"],
},
discord: {
groupPolicy: "allowlist",
guilds: {
GUILD_ID: { channels: { help: { allow: true } } },
},
},
slack: {
groupPolicy: "allowlist",
channels: { "#general": { allow: true } },
},
matrix: {
groupPolicy: "allowlist",
groupAllowFrom: ["@owner:example.org"],
groups: {
"!roomId:example.org": { enabled: true },
"#alias:example.org": { enabled: true },
},
},
},
}
```
| 政策 | 行為 |
| ------------- | ------------------------------------------------------------ |
| `"open"` | 群組會繞過允許清單；提及閘控仍會套用。 |
| `"disabled"` | 完全封鎖所有群組訊息。 |
| `"allowlist"` | 只允許符合已設定允許清單的群組/聊天室。 |
<AccordionGroup>
<Accordion title="各頻道注意事項">
- `groupPolicy` 與提及閘控是分開的（後者需要 @提及）。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（備援：明確的 `allowFrom`）。
- 私訊配對核准（`*-allowFrom` 儲存項目）只適用於私訊存取；群組傳送者授權仍明確使用群組允許清單。
- 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"`）；前綴不區分大小寫。
- 預設為 `groupPolicy: "allowlist"`；如果你的群組允許清單是空的，群組訊息會被封鎖。
- 執行階段安全性：當 provider 區塊完全缺失（沒有 `channels.<provider>`）時，群組政策會退回失敗關閉模式（通常是 `allowlist`），而不是繼承 `channels.defaults.groupPolicy`。
</Accordion>
</AccordionGroup>
快速心智模型（群組訊息的評估順序）：
<Steps>
<Step title="groupPolicy">
`groupPolicy`（open/disabled/allowlist）。
</Step>
<Step title="群組允許清單">
群組允許清單（`*.groups`、`*.groupAllowFrom`、頻道專屬允許清單）。
</Step>
<Step title="提及閘控">
提及閘控（`requireMention`、`/activation`）。
</Step>
</Steps>
## 提及閘控（預設）
群組訊息需要提及，除非依群組覆寫。預設值位於每個子系統的 `*.groups."*"` 下。
回覆機器人訊息在頻道支援回覆中繼資料時，會算作隱含提及。引用機器人訊息在公開引用中繼資料的頻道上，也可以算作隱含提及。目前內建案例包含 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 與 ZaloUser。
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
"123@g.us": { requireMention: false },
},
},
telegram: {
groups: {
"*": { requireMention: true },
"123456789": { requireMention: false },
},
},
imessage: {
groups: {
"*": { requireMention: true },
"123": { requireMention: false },
},
},
},
agents: {
list: [
{
id: "main",
groupChat: {
mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
historyLimit: 50,
},
},
],
},
}
```
<AccordionGroup>
<Accordion title="Mention gating notes">
- `mentionPatterns` 是不區分大小寫的安全 regex 模式；無效模式與不安全的巢狀重複形式會被忽略。
- 提供明確提及的介面仍會通過；模式是備援。
- 每代理覆寫：`agents.list[].groupChat.mentionPatterns`（在多個代理共用群組時很有用）。
- 提及門檻只會在可偵測提及時強制執行（已設定原生提及或 `mentionPatterns`）。
- 群組聊天提示詞上下文會在每一輪攜帶已解析的靜默回覆指令；工作區檔案不應重複 `NO_REPLY` 機制。
- 允許靜默回覆的群組，會將乾淨的空白或僅推理模型輪次視為靜默，等同於 `NO_REPLY`。直接聊天只有在明確允許直接靜默回覆時才會相同；否則空白回覆仍會保留為失敗的代理輪次。
- Discord 預設值位於 `channels.discord.guilds."*"`（可依 guild/channel 覆寫）。
- 群組歷史上下文會跨頻道一致包裝，且為 **pending-only**（因提及門檻而略過的訊息）；使用 `messages.groupChat.historyLimit` 作為全域預設值，並使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）進行覆寫。設為 `0` 可停用。
</Accordion>
</AccordionGroup>
## 群組/頻道工具限制（選用）
某些頻道設定支援限制 **特定群組/聊天室/頻道內** 可用的工具。
- `tools`：允許/拒絕整個群組的工具。
- `toolsBySender`：群組內依傳送者覆寫。使用明確的鍵前綴：`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>` 與 `"*"` 萬用字元。舊版未加前綴的鍵仍會接受，且只會以 `id:` 比對。
解析順序（最具體者優先）：
<Steps>
<Step title="Group toolsBySender">
群組/頻道 `toolsBySender` 比對。
</Step>
<Step title="Group tools">
群組/頻道 `tools`。
</Step>
<Step title="Default toolsBySender">
預設 (`"*"`) `toolsBySender` 比對。
</Step>
<Step title="Default tools">
預設 (`"*"`) `tools`。
</Step>
</Steps>
範例（Telegram）：
```json5
{
channels: {
telegram: {
groups: {
"*": { tools: { deny: ["exec"] } },
"-1001234567890": {
tools: { deny: ["exec", "read", "write"] },
toolsBySender: {
"id:123456789": { alsoAllow: ["exec"] },
},
},
},
},
},
}
```
<Note>
群組/頻道工具限制會在全域/代理工具政策之外另行套用（拒絕仍然優先）。某些頻道會針對聊天室/頻道使用不同的巢狀結構（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
</Note>
## 群組允許清單
設定 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 時，鍵會作為群組允許清單。使用 `"*"` 可允許所有群組，同時仍設定預設提及行為。
<Warning>
常見混淆：DM 配對核准不等同於群組授權。對於支援 DM 配對的頻道，配對儲存區只會解鎖 DM。群組命令仍需要來自設定允許清單（例如 `groupAllowFrom`）或該頻道已記載設定備援的明確群組傳送者授權。
</Warning>
常見意圖（複製/貼上）：
<Tabs>
<Tab title="Disable all group replies">
```json5
{
channels: { whatsapp: { groupPolicy: "disabled" } },
}
```
</Tab>
<Tab title="Allow only specific groups (WhatsApp)">
```json5
{
channels: {
whatsapp: {
groups: {
"123@g.us": { requireMention: true },
"456@g.us": { requireMention: false },
},
},
},
}
```
</Tab>
<Tab title="Allow all groups but require mention">
```json5
{
channels: {
whatsapp: {
groups: { "*": { requireMention: true } },
},
},
}
```
</Tab>
<Tab title="Owner-only triggers (WhatsApp)">
```json5
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
groups: { "*": { requireMention: true } },
},
},
}
```
</Tab>
</Tabs>
## 啟用（僅限擁有者）
群組擁有者可以切換每個群組的啟用狀態：
- `/activation mention`
- `/activation always`
擁有者由 `channels.whatsapp.allowFrom` 判定（未設定時則使用機器人自己的 E.164）。請將命令作為獨立訊息傳送。其他介面目前會忽略 `/activation`。
## 上下文字段
群組傳入 payload 會設定：
- `ChatType=group`
- `GroupSubject`（若已知）
- `GroupMembers`（若已知）
- `WasMentioned`（提及門檻結果）
- Telegram 論壇主題也會包含 `MessageThreadId` 與 `IsForum`。
頻道特定注意事項：
- BlueBubbles 可以選擇在填入 `GroupMembers` 前，先從本機「聯絡人」資料庫補充未命名的 macOS 群組參與者。這預設關閉，且只會在正常群組門檻通過後執行。
代理系統提示詞會在新群組工作階段的第一輪包含群組介紹。它會提醒模型像人類一樣回應、避免 Markdown 表格、盡量減少空白行並遵循一般聊天間距，以及避免輸入字面 `\n` 序列。頻道來源的群組名稱與參與者標籤會呈現為 fenced 不受信任中繼資料，而不是內嵌系統指令。
## iMessage 細節
- 路由或加入允許清單時，優先使用 `chat_id:<id>`。
- 列出聊天：`imsg chats --limit 20`。
- 群組回覆一律傳回相同的 `chat_id`。
## WhatsApp 系統提示詞
請參閱 [WhatsApp](/zh-TW/channels/whatsapp#system-prompts)，了解權威的 WhatsApp 系統提示詞規則，包括群組與直接提示詞解析、萬用字元行為，以及帳號覆寫語意。
## WhatsApp 細節
請參閱 [群組訊息](/zh-TW/channels/group-messages)，了解 WhatsApp 專屬行為（歷史注入、提及處理細節）。
## 相關
- [廣播群組](/zh-TW/channels/broadcast-groups)
- [頻道路由](/zh-TW/channels/channel-routing)
- [群組訊息](/zh-TW/channels/group-messages)
- [配對](/zh-TW/channels/pairing)

434
docs/zh-TW/channels/imessage.md Normal file
View File

@ -0,0 +1,434 @@
---
read_when:
- 設定 iMessage 支援
- 偵錯 iMessage 傳送/接收
summary: 透過 imsg（stdio 上的 JSON-RPC）提供舊版 iMessage 支援。新的設定應使用 BlueBubbles。
title: iMessage
x-i18n:
generated_at: "2026-04-30T02:46:43Z"
model: gpt-5.5
provider: openai
source_hash: 60eeb3553a6511d56b8177ca4eafbedfed2d0852ac64c230c250911cd18ce17e
source_path: channels/imessage.md
workflow: 16
---
<Warning>
若要進行新的 iMessage 部署，請使用 <a href="/zh-TW/channels/bluebubbles">BlueBubbles</a>。
`imsg` 整合屬於舊版功能，可能會在未來版本中移除。
</Warning>
狀態：舊版外部 CLI 整合。Gateway 會啟動 `imsg rpc`，並透過 stdio 上的 JSON-RPC 通訊（沒有獨立的守護程式/連接埠）。
<CardGroup cols={3}>
<Card title="BlueBubbles (recommended)" icon="message-circle" href="/zh-TW/channels/bluebubbles">
新設定建議使用的 iMessage 路徑。
</Card>
<Card title="Pairing" icon="link" href="/zh-TW/channels/pairing">
iMessage 私訊預設使用配對模式。
</Card>
<Card title="Configuration reference" icon="settings" href="/zh-TW/gateway/config-channels#imessage">
完整的 iMessage 欄位參考。
</Card>
</CardGroup>
## 快速設定
<Tabs>
<Tab title="Local Mac (fast path)">
<Steps>
<Step title="Install and verify imsg">
```bash
brew install steipete/tap/imsg
imsg rpc --help
```
</Step>
<Step title="Configure OpenClaw">
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "/usr/local/bin/imsg",
dbPath: "/Users/user/Library/Messages/chat.db",
},
},
}
```
</Step>
<Step title="Start gateway">
```bash
openclaw gateway
```
</Step>
<Step title="Approve first DM pairing (default dmPolicy)">
```bash
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
```
配對請求會在 1 小時後過期。
</Step>
</Steps>
</Tab>
<Tab title="Remote Mac over SSH">
OpenClaw 只需要與 stdio 相容的 `cliPath`，因此你可以將 `cliPath` 指向一個 wrapper script，由它透過 SSH 連到遠端 Mac 並執行 `imsg`。
```bash
#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"
```
啟用附件時的建議設定：
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "user@gateway-host", // used for SCP attachment fetches
includeAttachments: true,
// Optional: override allowed attachment roots.
// Defaults include /Users/*/Library/Messages/Attachments
attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
},
},
}
```
如果未設定 `remoteHost`，OpenClaw 會嘗試透過剖析 SSH wrapper script 自動偵測。
`remoteHost` 必須是 `host` 或 `user@host`（不可有空格或 SSH 選項）。
OpenClaw 對 SCP 使用嚴格的主機金鑰檢查，因此轉送主機金鑰必須已存在於 `~/.ssh/known_hosts`。
附件路徑會根據允許的根目錄（`attachmentRoots` / `remoteAttachmentRoots`）進行驗證。
</Tab>
</Tabs>
## 需求與權限（macOS）
- Messages 必須已在執行 `imsg` 的 Mac 上登入。
- 執行 OpenClaw/`imsg` 的程序環境需要完整磁碟存取權（Messages 資料庫存取）。
- 需要自動化權限，才能透過 Messages.app 傳送訊息。
<Tip>
權限是依程序環境授予。如果 gateway 以無頭模式執行（LaunchAgent/SSH），請在同一環境中執行一次互動式命令以觸發提示：
```bash
imsg chats --limit 1
# or
imsg send <handle> "test"
```
</Tip>
## 存取控制與路由
<Tabs>
<Tab title="DM policy">
`channels.imessage.dmPolicy` 控制直接訊息：
- `pairing`（預設）
- `allowlist`
- `open`（需要 `allowFrom` 包含 `"*"`）
- `disabled`
Allowlist 欄位：`channels.imessage.allowFrom`。
Allowlist 項目可以是 handle 或聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。
</Tab>
<Tab title="Group policy + mentions">
`channels.imessage.groupPolicy` 控制群組處理：
- `allowlist`（已設定時的預設值）
- `open`
- `disabled`
群組傳送者 allowlist：`channels.imessage.groupAllowFrom`。
執行階段後援：如果未設定 `groupAllowFrom`，iMessage 群組傳送者檢查會在可用時退回使用 `allowFrom`。
執行階段注意事項：如果完全缺少 `channels.imessage`，執行階段會退回到 `groupPolicy="allowlist"` 並記錄警告（即使已設定 `channels.defaults.groupPolicy`）。
群組的提及 gating：
- iMessage 沒有原生提及 metadata
- 提及偵測使用 regex patterns（`agents.list[].groupChat.mentionPatterns`，後援為 `messages.groupChat.mentionPatterns`）
- 未設定 patterns 時，無法強制執行提及 gating
來自授權傳送者的控制命令可以在群組中略過提及 gating。
</Tab>
<Tab title="Sessions and deterministic replies">
- 私訊使用直接路由；群組使用群組路由。
- 使用預設 `session.dmScope=main` 時，iMessage 私訊會收斂到 agent main session。
- 群組 session 會隔離（`agent:<agentId>:imessage:group:<chat_id>`）。
- 回覆會使用來源 channel/target metadata 路由回 iMessage。
類群組 thread 行為：
某些多參與者 iMessage threads 可能會以 `is_group=false` 抵達。
如果該 `chat_id` 明確設定於 `channels.imessage.groups` 下，OpenClaw 會將其視為群組流量（群組 gating + 群組 session 隔離）。
</Tab>
</Tabs>
## ACP 對話繫結
舊版 iMessage 聊天也可以繫結到 ACP sessions。
快速操作流程：
- 在私訊或允許的群組聊天內執行 `/acp spawn codex --bind here`。
- 之後同一個 iMessage 對話中的訊息會路由到產生的 ACP session。
- `/new` 和 `/reset` 會就地重設同一個已繫結的 ACP session。
- `/acp close` 會關閉 ACP session 並移除繫結。
已設定的持久繫結可透過最上層 `bindings[]` 項目支援，其中 `type: "acp"` 且 `match.channel: "imessage"`。
`match.peer.id` 可以使用：
- 標準化的私訊 handle，例如 `+15555550123` 或 `user@example.com`
- `chat_id:<id>`（建議用於穩定的群組繫結）
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
範例：
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: { agent: "codex", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "imessage",
accountId: "default",
peer: { kind: "group", id: "chat_id:123" },
},
acp: { label: "codex-group" },
},
],
}
```
請參閱 [ACP Agents](/zh-TW/tools/acp-agents) 了解共用的 ACP 繫結行為。
## 部署模式
<AccordionGroup>
<Accordion title="Dedicated bot macOS user (separate iMessage identity)">
使用專用 Apple ID 和 macOS 使用者，讓 bot 流量與你的個人 Messages profile 隔離。
典型流程：
1. 建立/登入專用 macOS 使用者。
2. 在該使用者中使用 bot Apple ID 登入 Messages。
3. 在該使用者中安裝 `imsg`。
4. 建立 SSH wrapper，讓 OpenClaw 可以在該使用者環境中執行 `imsg`。
5. 將 `channels.imessage.accounts.<id>.cliPath` 和 `.dbPath` 指向該使用者 profile。
第一次執行可能需要在該 bot 使用者 session 中進行 GUI 核准（自動化 + 完整磁碟存取）。
</Accordion>
<Accordion title="Remote Mac over Tailscale (example)">
常見拓撲：
- gateway 在 Linux/VM 上執行
- iMessage + `imsg` 在你 tailnet 中的一台 Mac 上執行
- `cliPath` wrapper 使用 SSH 執行 `imsg`
- `remoteHost` 啟用 SCP 附件擷取
範例：
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
includeAttachments: true,
dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}
```
```bash
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
```
使用 SSH 金鑰，讓 SSH 和 SCP 都能非互動執行。
請先確保主機金鑰已受信任（例如 `ssh bot@mac-mini.tailnet-1234.ts.net`），讓 `known_hosts` 已填入。
</Accordion>
<Accordion title="Multi-account pattern">
iMessage 支援 `channels.imessage.accounts` 下的逐帳號設定。
每個帳號都可以覆寫 `cliPath`、`dbPath`、`allowFrom`、`groupPolicy`、`mediaMaxMb`、history settings，以及附件根目錄 allowlists 等欄位。
</Accordion>
</AccordionGroup>
## 媒體、分塊與遞送目標
<AccordionGroup>
<Accordion title="Attachments and media">
- 傳入附件擷取是選用的：`channels.imessage.includeAttachments`
- 設定 `remoteHost` 時，可以透過 SCP 擷取遠端附件路徑
- 附件路徑必須符合允許的根目錄：
- `channels.imessage.attachmentRoots`（本機）
- `channels.imessage.remoteAttachmentRoots`（遠端 SCP 模式）
- 預設根目錄 pattern：`/Users/*/Library/Messages/Attachments`
- SCP 使用嚴格的主機金鑰檢查（`StrictHostKeyChecking=yes`）
- 傳出媒體大小使用 `channels.imessage.mediaMaxMb`（預設 16 MB）
</Accordion>
<Accordion title="Outbound chunking">
- 文字分塊限制：`channels.imessage.textChunkLimit`（預設 4000）
- 分塊模式：`channels.imessage.chunkMode`
- `length`（預設）
- `newline`（段落優先切分）
</Accordion>
<Accordion title="Addressing formats">
建議的明確目標：
- `chat_id:123`（建議用於穩定路由）
- `chat_guid:...`
- `chat_identifier:...`
也支援 handle 目標：
- `imessage:+1555...`
- `sms:+1555...`
- `user@example.com`
```bash
imsg chats --limit 20
```
</Accordion>
</AccordionGroup>
## 設定寫入
iMessage 預設允許 channel 發起的設定寫入（適用於 `commands.config: true` 時的 `/config set|unset`）。
停用：
```json5
{
channels: {
imessage: {
configWrites: false,
},
},
}
```
## 疑難排解
<AccordionGroup>
<Accordion title="imsg not found or RPC unsupported">
驗證 binary 與 RPC 支援：
```bash
imsg rpc --help
openclaw channels status --probe
```
如果 probe 回報 RPC 不受支援，請更新 `imsg`。
</Accordion>
<Accordion title="DMs are ignored">
檢查：
- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- 配對核准（`openclaw pairing list imessage`）
</Accordion>
<Accordion title="Group messages are ignored">
檢查：
- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` allowlist 行為
- 提及 pattern 設定（`agents.list[].groupChat.mentionPatterns`）
</Accordion>
<Accordion title="Remote attachments fail">
檢查：
- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- 來自 gateway host 的 SSH/SCP 金鑰驗證
- gateway host 上的 `~/.ssh/known_hosts` 中存在主機金鑰
- 執行 Messages 的 Mac 上的遠端路徑可讀性
</Accordion>
<Accordion title="macOS permission prompts were missed">
在同一使用者/session 環境中的互動式 GUI terminal 重新執行並核准提示：
```bash
imsg chats --limit 1
imsg send <handle> "test"
```
確認完整磁碟存取 + 自動化已授予執行 OpenClaw/`imsg` 的程序環境。
</Accordion>
</AccordionGroup>
## 設定參考指標
- [設定參考 - iMessage](/zh-TW/gateway/config-channels#imessage)
- [Gateway 設定](/zh-TW/gateway/configuration)
- [配對](/zh-TW/channels/pairing)
- [BlueBubbles](/zh-TW/channels/bluebubbles)
## 相關
- [Channels Overview](/zh-TW/channels) — 所有支援的 channels
- [配對](/zh-TW/channels/pairing) — 私訊驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及 gating
- [Channel Routing](/zh-TW/channels/channel-routing) — 訊息的 session 路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化措施

65
docs/zh-TW/channels/index.md Normal file
View File

@ -0,0 +1,65 @@
---
read_when:
- 你想要為 OpenClaw 選擇聊天頻道
- 需要快速概覽支援的訊息平台
summary: OpenClaw 可連接的訊息平台
title: 聊天頻道
x-i18n:
generated_at: "2026-04-30T02:46:58Z"
model: gpt-5.5
provider: openai
source_hash: b58a1f1a0500419015985500a301d9f8ee4fa3a67b11e30561cabe2dc57b5049
source_path: channels/index.md
workflow: 16
---
OpenClaw 可以在你已經使用的任何聊天 App 上與你交談。每個頻道都透過 Gateway 連線。
所有地方都支援文字；媒體與反應則依頻道而異。
## 傳送注意事項
- 包含 Markdown 圖片語法的 Telegram 回覆，例如 `![alt](url)`，
會在可行時於最終傳出路徑上轉換為媒體回覆。
- Slack 多人私訊會以群組聊天的方式路由，因此群組政策、提及
行為與群組工作階段規則會套用到 MPIM 對話。
- WhatsApp 設定是按需安裝：新手導引可以在
Baileys 執行階段相依套件完成部署前顯示設定流程，而 Gateway 只會在頻道實際啟用時載入 WhatsApp
執行階段。
## 支援的頻道
- [BlueBubbles](/zh-TW/channels/bluebubbles) — **建議用於 iMessage**；使用 BlueBubbles macOS 伺服器 REST API，完整支援功能（內建 Plugin；編輯、收回、效果、反應、群組管理 — 編輯目前在 macOS 26 Tahoe 上故障）。
- [Discord](/zh-TW/channels/discord) — Discord Bot API + Gateway；支援伺服器、頻道與私訊。
- [Feishu](/zh-TW/channels/feishu) — 透過 WebSocket 使用 Feishu/Lark 機器人（內建 Plugin）。
- [Google Chat](/zh-TW/channels/googlechat) — 透過 HTTP Webhook 使用 Google Chat API App。
- [iMessage（舊版）](/zh-TW/channels/imessage) — 透過 imsg CLI 的舊版 macOS 整合（已棄用，新設定請使用 BlueBubbles）。
- [IRC](/zh-TW/channels/irc) — 傳統 IRC 伺服器；支援頻道與私訊，並提供配對／允許清單控制。
- [LINE](/zh-TW/channels/line) — LINE Messaging API 機器人（內建 Plugin）。
- [Matrix](/zh-TW/channels/matrix) — Matrix 協定（內建 Plugin）。
- [Mattermost](/zh-TW/channels/mattermost) — Bot API + WebSocket；頻道、群組、私訊（內建 Plugin）。
- [Microsoft Teams](/zh-TW/channels/msteams) — Bot Framework；企業支援（內建 Plugin）。
- [Nextcloud Talk](/zh-TW/channels/nextcloud-talk) — 透過 Nextcloud Talk 的自架聊天（內建 Plugin）。
- [Nostr](/zh-TW/channels/nostr) — 透過 NIP-04 的去中心化私訊（內建 Plugin）。
- [QQ Bot](/zh-TW/channels/qqbot) — QQ Bot API；私人聊天、群組聊天與豐富媒體（內建 Plugin）。
- [Signal](/zh-TW/channels/signal) — signal-cli；注重隱私。
- [Slack](/zh-TW/channels/slack) — Bolt SDK；工作區 App。
- [Synology Chat](/zh-TW/channels/synology-chat) — 透過傳出與傳入 Webhook 使用 Synology NAS Chat（內建 Plugin）。
- [Telegram](/zh-TW/channels/telegram) — 透過 grammY 使用 Bot API；支援群組。
- [Tlon](/zh-TW/channels/tlon) — 以 Urbit 為基礎的 Messenger（內建 Plugin）。
- [Twitch](/zh-TW/channels/twitch) — 透過 IRC 連線的 Twitch 聊天（內建 Plugin）。
- [Voice Call](/zh-TW/plugins/voice-call) — 透過 Plivo 或 Twilio 的電話通訊（Plugin，需另行安裝）。
- [WebChat](/zh-TW/web/webchat) — 透過 WebSocket 的 Gateway WebChat UI。
- [WeChat](/zh-TW/channels/wechat) — 透過 QR 登入的 Tencent iLink Bot Plugin；僅支援私人聊天（外部 Plugin）。
- [WhatsApp](/zh-TW/channels/whatsapp) — 最受歡迎；使用 Baileys，並需要 QR 配對。
- [Yuanbao](/zh-TW/channels/yuanbao) — Tencent Yuanbao 機器人（外部 Plugin）。
- [Zalo](/zh-TW/channels/zalo) — Zalo Bot API；越南熱門 Messenger（內建 Plugin）。
- [Zalo Personal](/zh-TW/channels/zalouser) — 透過 QR 登入的 Zalo 個人帳號（內建 Plugin）。
## 注意事項
- 頻道可以同時執行；設定多個頻道後，OpenClaw 會依聊天進行路由。
- 最快的設定通常是 **Telegram**（簡單的機器人權杖）。WhatsApp 需要 QR 配對，並且會在磁碟上儲存更多狀態。
- 群組行為因頻道而異；請參閱[群組](/zh-TW/channels/groups)。
- 為了安全，會強制執行私訊配對與允許清單；請參閱[安全性](/zh-TW/gateway/security)。
- 疑難排解：[頻道疑難排解](/zh-TW/channels/troubleshooting)。
- 模型提供者另有文件說明；請參閱[模型提供者](/zh-TW/providers/models)。

259
docs/zh-TW/channels/irc.md Normal file
View File

@ -0,0 +1,259 @@
---
read_when:
- 您想要將 OpenClaw 連接到 IRC 頻道或私訊
- 您正在設定 IRC 允許清單、群組政策或提及閘控
summary: IRC Plugin 設定、存取控制與疑難排解
title: IRC
x-i18n:
generated_at: "2026-04-30T02:47:15Z"
model: gpt-5.5
provider: openai
source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69
source_path: channels/irc.md
workflow: 16
---
使用 IRC 可讓 OpenClaw 進入傳統頻道（`#room`）和私訊。
IRC 以隨附的 Plugin 提供，但設定位於主要設定檔的 `channels.irc` 下。
## 快速開始
1. 在 `~/.openclaw/openclaw.json` 啟用 IRC 設定。
2. 至少設定：
```json5
{
channels: {
irc: {
enabled: true,
host: "irc.example.com",
port: 6697,
tls: true,
nick: "openclaw-bot",
channels: ["#openclaw"],
},
},
}
```
建議使用私人 IRC 伺服器進行機器人協調。如果你刻意使用公開 IRC 網路，常見選擇包括 Libera.Chat、OFTC 和 Snoonet。避免將可預測的公開頻道用於機器人或群集後端通道流量。
3. 啟動/重新啟動 Gateway：
```bash
openclaw gateway run
```
## 安全性預設值
- `channels.irc.dmPolicy` 預設為 `"pairing"`。
- `channels.irc.groupPolicy` 預設為 `"allowlist"`。
- 使用 `groupPolicy="allowlist"` 時，請設定 `channels.irc.groups` 來定義允許的頻道。
- 除非你刻意接受純文字傳輸，否則請使用 TLS（`channels.irc.tls=true`）。
## 存取控制
IRC 頻道有兩個獨立的「關卡」：
1. **頻道存取**（`groupPolicy` + `groups`）：機器人是否會接受來自某個頻道的訊息。
2. **傳送者存取**（`groupAllowFrom` / 每頻道 `groups["#channel"].allowFrom`）：誰可以在該頻道內觸發機器人。
設定鍵：
- 私訊允許清單（私訊傳送者存取）：`channels.irc.allowFrom`
- 群組傳送者允許清單（頻道傳送者存取）：`channels.irc.groupAllowFrom`
- 每頻道控制（頻道 + 傳送者 + 提及規則）：`channels.irc.groups["#channel"]`
- `channels.irc.groupPolicy="open"` 允許未設定的頻道（**預設仍受提及限制**）
允許清單項目應使用穩定的傳送者身分（`nick!user@host`）。
裸暱稱比對是可變的，只有在 `channels.irc.dangerouslyAllowNameMatching: true` 時才會啟用。
### 常見陷阱：`allowFrom` 用於私訊，不是頻道
如果你看到如下記錄：
- `irc: drop group sender alice!ident@host (policy=allowlist)`
……這表示該傳送者未被允許傳送**群組/頻道**訊息。可用以下任一方式修正：
- 設定 `channels.irc.groupAllowFrom`（套用於所有頻道的全域設定），或
- 設定每頻道傳送者允許清單：`channels.irc.groups["#channel"].allowFrom`
範例（允許 `#tuirc-dev` 中任何人與機器人對話）：
```json5
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#tuirc-dev": { allowFrom: ["*"] },
},
},
},
}
```
## 回覆觸發（提及）
即使頻道已被允許（透過 `groupPolicy` + `groups`）且傳送者已被允許，OpenClaw 在群組情境中預設仍會採用**提及限制**。
這表示你可能會看到類似 `drop channel … (missing-mention)` 的記錄，除非訊息包含符合機器人的提及模式。
若要讓機器人在 IRC 頻道中**不需要提及即可回覆**，請停用該頻道的提及限制：
```json5
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#tuirc-dev": {
requireMention: false,
allowFrom: ["*"],
},
},
},
},
}
```
或者，若要允許**所有** IRC 頻道（不使用每頻道允許清單），且仍可不需提及就回覆：
```json5
{
channels: {
irc: {
groupPolicy: "open",
groups: {
"*": { requireMention: false, allowFrom: ["*"] },
},
},
},
}
```
## 安全性注意事項（建議用於公開頻道）
如果你在公開頻道中允許 `allowFrom: ["*"]`，任何人都可以提示機器人。
若要降低風險，請限制該頻道可用的工具。
### 頻道內所有人使用相同工具
```json5
{
channels: {
irc: {
groups: {
"#tuirc-dev": {
allowFrom: ["*"],
tools: {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
},
},
},
},
}
```
### 依傳送者使用不同工具（擁有者取得更多權限）
使用 `toolsBySender`，對 `"*"` 套用較嚴格的政策，對你的暱稱套用較寬鬆的政策：
```json5
{
channels: {
irc: {
groups: {
"#tuirc-dev": {
allowFrom: ["*"],
toolsBySender: {
"*": {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
"id:eigen": {
deny: ["gateway", "nodes", "cron"],
},
},
},
},
},
},
}
```
注意事項：
- `toolsBySender` 鍵應對 IRC 傳送者身分值使用 `id:`：
`id:eigen`，或使用 `id:eigen!~eigen@174.127.248.171` 進行更強的比對。
- 舊版未加前綴的鍵仍會被接受，並且只會以 `id:` 進行比對。
- 第一個相符的傳送者政策會生效；`"*"` 是萬用字元後備項目。
若要深入了解群組存取與提及限制（以及它們如何互動），請參閱：[/channels/groups](/zh-TW/channels/groups)。
## NickServ
若要在連線後向 NickServ 識別身分：
```json5
{
channels: {
irc: {
nickserv: {
enabled: true,
service: "NickServ",
password: "your-nickserv-password",
},
},
},
}
```
連線時可選的一次性註冊：
```json5
{
channels: {
irc: {
nickserv: {
register: true,
registerEmail: "bot@example.com",
},
},
},
}
```
暱稱註冊完成後，請停用 `register`，以避免重複嘗試 REGISTER。
## 環境變數
預設帳號支援：
- `IRC_HOST`
- `IRC_PORT`
- `IRC_TLS`
- `IRC_NICK`
- `IRC_USERNAME`
- `IRC_REALNAME`
- `IRC_PASSWORD`
- `IRC_CHANNELS`（逗號分隔）
- `IRC_NICKSERV_PASSWORD`
- `IRC_NICKSERV_REGISTER_EMAIL`
`IRC_HOST` 不能從工作區 `.env` 設定；請參閱[工作區 `.env` 檔案](/zh-TW/gateway/security)。
## 疑難排解
- 如果機器人已連線但從不在頻道中回覆，請確認 `channels.irc.groups` **以及**提及限制是否正在丟棄訊息（`missing-mention`）。如果你希望它不需要 ping 就回覆，請為該頻道設定 `requireMention:false`。
- 如果登入失敗，請確認暱稱可用性和伺服器密碼。
- 如果自訂網路上的 TLS 失敗，請確認主機/連接埠和憑證設定。
## 相關內容
- [頻道概覽](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — 私訊驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及限制
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化措施

235
docs/zh-TW/channels/line.md Normal file
View File

@ -0,0 +1,235 @@
---
read_when:
- 您想要將 OpenClaw 連接到 LINE
- 你需要設定 LINE Webhook 與憑證
- 你想要 LINE 專用的訊息選項
summary: LINE Messaging API Plugin 的設定、組態與使用方式
title: 行
x-i18n:
generated_at: "2026-04-30T02:47:38Z"
model: gpt-5.5
provider: openai
source_hash: e9f06d882f1e8d2a758e50459fadefd77796a68c28f63bef5790eb1b540c17d1
source_path: channels/line.md
workflow: 16
---
LINE 透過 LINE Messaging API 連接到 OpenClaw。此 Plugin 會在 Gateway 上作為 Webhook
接收器執行，並使用你的通道存取權杖 + 通道密鑰進行驗證。
狀態：內建 Plugin。支援直接訊息、群組聊天、媒體、位置、Flex
訊息、範本訊息與快速回覆。不支援回應與討論串。
## 內建 Plugin
LINE 在目前的 OpenClaw 版本中作為內建 Plugin 隨附，因此一般
封裝建置不需要另行安裝。
如果你使用的是較舊的建置，或排除 LINE 的自訂安裝，請在 npm 套件發布後安裝
目前的 npm 套件：
```bash
openclaw plugins install @openclaw/line
```
如果 npm 回報 OpenClaw 擁有的套件已淘汰或不存在，請使用
目前封裝的 OpenClaw 建置或本機 checkout，直到 npm 套件發布流程
趕上。
本機 checkout（從 git repo 執行時）：
```bash
openclaw plugins install ./path/to/local/line-plugin
```
## 設定
1. 建立 LINE Developers 帳號並開啟 Console：
[https://developers.line.biz/console/](https://developers.line.biz/console/)
2. 建立（或選取）Provider，並新增 **Messaging API** 通道。
3. 從通道設定複製 **Channel access token** 與 **Channel secret**。
4. 在 Messaging API 設定中啟用 **Use webhook**。
5. 將 Webhook URL 設為你的 Gateway 端點（必須使用 HTTPS）：
```
https://gateway-host/line/webhook
```
Gateway 會回應 LINE 的 Webhook 驗證（GET）與傳入事件（POST）。
如果你需要自訂路徑，請設定 `channels.line.webhookPath` 或
`channels.line.accounts.<id>.webhookPath`，並相應更新 URL。
安全性注意事項：
- LINE 簽章驗證取決於請求本文（對原始本文做 HMAC），因此 OpenClaw 會在驗證前套用嚴格的預驗證本文大小限制與逾時。
- OpenClaw 會從已驗證的原始請求位元組處理 Webhook 事件。為了簽章完整性安全，會忽略上游中介軟體轉換過的 `req.body` 值。
## 設定
最小設定：
```json5
{
channels: {
line: {
enabled: true,
channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
channelSecret: "LINE_CHANNEL_SECRET",
dmPolicy: "pairing",
},
},
}
```
環境變數（僅限預設帳號）：
- `LINE_CHANNEL_ACCESS_TOKEN`
- `LINE_CHANNEL_SECRET`
權杖/密鑰檔案：
```json5
{
channels: {
line: {
tokenFile: "/path/to/line-token.txt",
secretFile: "/path/to/line-secret.txt",
},
},
}
```
`tokenFile` 與 `secretFile` 必須指向一般檔案。符號連結會被拒絕。
多個帳號：
```json5
{
channels: {
line: {
accounts: {
marketing: {
channelAccessToken: "...",
channelSecret: "...",
webhookPath: "/line/marketing",
},
},
},
},
}
```
## 存取控制
直接訊息預設使用配對。未知傳送者會取得配對代碼，且其
訊息會被忽略，直到獲得核准。
```bash
openclaw pairing list line
openclaw pairing approve line <CODE>
```
允許清單與政策：
- `channels.line.dmPolicy`：`pairing | allowlist | open | disabled`
- `channels.line.allowFrom`：允許傳送 DM 的 LINE 使用者 ID
- `channels.line.groupPolicy`：`allowlist | open | disabled`
- `channels.line.groupAllowFrom`：允許在群組中傳送訊息的 LINE 使用者 ID
- 個別群組覆寫：`channels.line.groups.<groupId>.allowFrom`
- 執行階段注意事項：如果 `channels.line` 完全不存在，執行階段會在群組檢查時回退到 `groupPolicy="allowlist"`（即使已設定 `channels.defaults.groupPolicy`）。
LINE ID 區分大小寫。有效 ID 如下：
- 使用者：`U` + 32 個十六進位字元
- 群組：`C` + 32 個十六進位字元
- 聊天室：`R` + 32 個十六進位字元
## 訊息行為
- 文字會以 5000 個字元為一段進行分段。
- Markdown 格式會被移除；程式碼區塊與表格會在可行時轉換成 Flex
卡片。
- 串流回應會被緩衝；Agent 工作期間，LINE 會收到完整分段並顯示載入
動畫。
- 媒體下載受 `channels.line.mediaMaxMb` 限制（預設 10）。
- 傳入媒體會先儲存在 `~/.openclaw/media/inbound/` 下，再傳給
Agent，與其他內建通道 Plugin 使用的共用媒體儲存區一致。
## 通道資料（豐富訊息）
使用 `channelData.line` 傳送快速回覆、位置、Flex 卡片或範本
訊息。
```json5
{
text: "Here you go",
channelData: {
line: {
quickReplies: ["Status", "Help"],
location: {
title: "Office",
address: "123 Main St",
latitude: 35.681236,
longitude: 139.767125,
},
flexMessage: {
altText: "Status card",
contents: {
/* Flex payload */
},
},
templateMessage: {
type: "confirm",
text: "Proceed?",
confirmLabel: "Yes",
confirmData: "yes",
cancelLabel: "No",
cancelData: "no",
},
},
},
}
```
LINE Plugin 也隨附 `/card` 命令，可用於 Flex 訊息預設：
```
/card info "Welcome" "Thanks for joining!"
```
## ACP 支援
LINE 支援 ACP（Agent Communication Protocol）對話繫結：
- `/acp spawn <agent> --bind here` 會將目前 LINE 聊天繫結到 ACP 工作階段，而不建立子討論串。
- 已設定的 ACP 繫結與作用中的對話繫結 ACP 工作階段，在 LINE 上的運作方式與其他對話通道相同。
詳情請參閱 [ACP Agent](/zh-TW/tools/acp-agents)。
## 傳出媒體
LINE Plugin 支援透過 Agent 訊息工具傳送圖片、影片與音訊檔案。媒體會透過 LINE 專用的傳遞路徑送出，並具備適當的預覽與追蹤處理：
- **圖片**：作為 LINE 圖片訊息傳送，並自動產生預覽。
- **影片**：傳送時明確處理預覽與內容類型。
- **音訊**：作為 LINE 音訊訊息傳送。
傳出媒體 URL 必須是公開 HTTPS URL。OpenClaw 會先驗證目標主機名稱，再將 URL 交給 LINE，並拒絕 loopback、link-local 與私人網路目標。
當 LINE 專用路徑不可用時，一般媒體傳送會回退到既有的僅圖片路由。
## 疑難排解
- **Webhook 驗證失敗：** 確認 Webhook URL 使用 HTTPS，且
`channelSecret` 與 LINE console 相符。
- **沒有傳入事件：** 確認 Webhook 路徑符合 `channels.line.webhookPath`，
且 LINE 能連線到 Gateway。
- **媒體下載錯誤：** 如果媒體超過預設限制，請提高 `channels.line.mediaMaxMb`。
## 相關
- [通道概觀](/zh-TW/channels) — 所有支援的通道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及門檻
- [通道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

78
docs/zh-TW/channels/location.md Normal file
View File

@ -0,0 +1,78 @@
---
read_when:
- 新增或修改頻道位置解析
- 在代理提示詞或工具中使用位置情境欄位
summary: 傳入頻道位置解析（Telegram/WhatsApp/Matrix）和上下文欄位
title: 通道位置解析
x-i18n:
generated_at: "2026-04-30T02:47:31Z"
model: gpt-5.5
provider: openai
source_hash: 19c10a55e30c70a7af5d041f9a25c0a2783e3191403e7c0cedfbe7dd8f1a77c1
source_path: channels/location.md
workflow: 16
---
OpenClaw 會將聊天頻道分享的位置正規化為：
- 附加到傳入本文的簡短座標文字，以及
- 自動回覆情境承載中的結構化欄位。頻道提供的標籤、地址和說明/留言會透過共用的不受信任中繼資料 JSON 區塊轉譯到提示中，而不是內嵌在使用者本文裡。
目前支援：
- **Telegram**（位置圖釘 + 場所 + 即時位置）
- **WhatsApp**（locationMessage + liveLocationMessage）
- **Matrix**（含有 `geo_uri` 的 `m.location`）
## 文字格式
位置會轉譯為不含括號的友善行：
- 圖釘：
- `📍 48.858844, 2.294351 ±12m`
- 具名地點：
- `📍 48.858844, 2.294351 ±12m`
- 即時分享：
- `🛰 Live location: 48.858844, 2.294351 ±12m`
如果頻道包含標籤、地址或說明/留言，會保留在情境承載中，並以加上圍欄的不受信任 JSON 顯示在提示中：
````text
Location (untrusted metadata):
```json
{
"latitude": 48.858844,
"longitude": 2.294351,
"name": "Eiffel Tower",
"address": "Champ de Mars, Paris",
"caption": "Meet here"
}
```
````
## 情境欄位
當存在位置時，這些欄位會加入 `ctx`：
- `LocationLat`（數字）
- `LocationLon`（數字）
- `LocationAccuracy`（數字，公尺；選用）
- `LocationName`（字串；選用）
- `LocationAddress`（字串；選用）
- `LocationSource`（`pin | place | live`）
- `LocationIsLive`（布林值）
- `LocationCaption`（字串；選用）
提示轉譯器會將 `LocationName`、`LocationAddress` 和 `LocationCaption` 視為不受信任的中繼資料，並透過與其他頻道情境相同的有界 JSON 路徑將它們序列化。
## 頻道附註
- **Telegram**：場所會對應到 `LocationName/LocationAddress`；即時位置使用 `live_period`。
- **WhatsApp**：`locationMessage.comment` 和 `liveLocationMessage.caption` 會填入 `LocationCaption`。
- **Matrix**：`geo_uri` 會剖析為圖釘位置；高度會被忽略，且 `LocationIsLive` 一律為 false。
## 相關
- [位置命令（節點）](/zh-TW/nodes/location-command)
- [相機擷取](/zh-TW/nodes/camera)
- [媒體理解](/zh-TW/nodes/media-understanding)

380
docs/zh-TW/channels/matrix-migration.md Normal file
View File

@ -0,0 +1,380 @@
---
read_when:
- 升級現有的 Matrix 安裝
- 遷移加密的 Matrix 歷史記錄與裝置狀態
summary: OpenClaw 如何就地升級舊版 Matrix Plugin，包括加密狀態復原限制與手動復原步驟。
title: Matrix 遷移
x-i18n:
generated_at: "2026-04-30T02:47:39Z"
model: gpt-5.5
provider: openai
source_hash: fff409eef1b7da7be4b63d8459a62b8365a04adf989f271a2f2c4aef46e90716
source_path: channels/matrix-migration.md
workflow: 16
---
從先前公開的 `matrix` Plugin 升級到目前實作。
對大多數使用者而言，升級會就地完成：
- Plugin 保持為 `@openclaw/matrix`
- 通道保持為 `matrix`
- 你的設定保持在 `channels.matrix` 下
- 快取的憑證保持在 `~/.openclaw/credentials/matrix/` 下
- 執行階段狀態保持在 `~/.openclaw/matrix/` 下
你不需要重新命名設定鍵，也不需要以新名稱重新安裝 Plugin。
## 遷移會自動做什麼
當 Gateway 啟動時，以及當你執行 [`openclaw doctor --fix`](/zh-TW/gateway/doctor) 時，OpenClaw 會嘗試自動修復舊的 Matrix 狀態。
在任何可操作的 Matrix 遷移步驟變更磁碟狀態之前，OpenClaw 會建立或重用一個聚焦的復原快照。
當你使用 `openclaw update` 時，確切觸發方式取決於 OpenClaw 的安裝方式：
- 原始碼安裝會在更新流程期間執行 `openclaw doctor --fix`，然後預設重新啟動 Gateway
- 套件管理器安裝會更新套件、執行一次非互動式 doctor 檢查，然後依賴預設 Gateway 重新啟動，讓啟動流程完成 Matrix 遷移
- 如果你使用 `openclaw update --no-restart`，由啟動支援的 Matrix 遷移會延後到你稍後執行 `openclaw doctor --fix` 並重新啟動 Gateway 時
自動遷移涵蓋：
- 在 `~/Backups/openclaw-migrations/` 下建立或重用遷移前快照
- 重用你快取的 Matrix 憑證
- 保持相同的帳號選擇和 `channels.matrix` 設定
- 將最舊的扁平 Matrix 同步儲存移到目前以帳號為範圍的位置
- 當可以安全解析目標帳號時，將最舊的扁平 Matrix 加密儲存移到目前以帳號為範圍的位置
- 當舊 rust 加密儲存中本機存在先前儲存的 Matrix 房間金鑰備份解密金鑰時，擷取該金鑰
- 當存取權杖稍後變更時，為相同的 Matrix 帳號、homeserver 和使用者重用最完整的既有權杖雜湊儲存根目錄
- 當 Matrix 存取權杖已變更但帳號/裝置身分保持相同時，掃描相鄰的權杖雜湊儲存根目錄以尋找待處理的加密狀態還原中繼資料
- 在下一次 Matrix 啟動時，將已備份的房間金鑰還原到新的加密儲存中
快照詳細資訊：
- OpenClaw 會在快照成功後，將標記檔寫入 `~/.openclaw/matrix/migration-snapshot.json`，讓稍後的啟動和修復檢查可以重用同一個封存檔。
- 這些自動 Matrix 遷移快照只會備份設定 + 狀態（`includeWorkspace: false`）。
- 如果 Matrix 只有警告型遷移狀態，例如因為 `userId` 或 `accessToken` 仍缺失，OpenClaw 還不會建立快照，因為沒有可操作的 Matrix 變更。
- 如果快照步驟失敗，OpenClaw 會略過該次執行的 Matrix 遷移，而不是在沒有復原點的情況下變更狀態。
關於多帳號升級：
- 最舊的扁平 Matrix 儲存（`~/.openclaw/matrix/bot-storage.json` 和 `~/.openclaw/matrix/crypto/`）來自單一儲存版面，因此 OpenClaw 只能將它遷移到一個已解析的 Matrix 帳號目標
- 已經以帳號為範圍的舊版 Matrix 儲存會依每個已設定的 Matrix 帳號偵測並準備
## 遷移無法自動做什麼
先前公開的 Matrix Plugin **不會**自動建立 Matrix 房間金鑰備份。它會保存本機加密狀態並請求裝置驗證，但不保證你的房間金鑰已備份到 homeserver。
這表示某些加密安裝只能部分遷移。
OpenClaw 無法自動復原：
- 從未備份的僅本機房間金鑰
- 目標 Matrix 帳號尚無法解析時的加密狀態，因為 `homeserver`、`userId` 或 `accessToken` 仍不可用
- 當設定了多個 Matrix 帳號但未設定 `channels.matrix.defaultAccount` 時，無法自動遷移一個共用的扁平 Matrix 儲存
- 釘選到 repo 路徑而非標準 Matrix 套件的自訂 Plugin 路徑安裝
- 當舊儲存有已備份金鑰但未在本機保留解密金鑰時，無法取得缺失的復原金鑰
目前警告範圍：
- 自訂 Matrix Plugin 路徑安裝會同時由 Gateway 啟動和 `openclaw doctor` 顯示
如果你的舊安裝有從未備份的僅本機加密歷史紀錄，升級後某些較舊的加密訊息可能仍無法讀取。
## 建議升級流程
1. 正常更新 OpenClaw 和 Matrix Plugin。
偏好使用不帶 `--no-restart` 的普通 `openclaw update`，讓啟動流程可以立即完成 Matrix 遷移。
2. 執行：
```bash
openclaw doctor --fix
```
如果 Matrix 有可操作的遷移工作，doctor 會先建立或重用遷移前快照，並印出封存檔路徑。
3. 啟動或重新啟動 Gateway。
4. 檢查目前驗證和備份狀態：
```bash
openclaw matrix verify status
openclaw matrix verify backup status
```
5. 將你正在修復的 Matrix 帳號復原金鑰放入帳號專用環境變數。對單一預設帳號而言，`MATRIX_RECOVERY_KEY` 即可。對多個帳號，請為每個帳號使用一個變數，例如 `MATRIX_RECOVERY_KEY_ASSISTANT`，並在命令中加入 `--account assistant`。
6. 如果 OpenClaw 告訴你需要復原金鑰，請針對相符帳號執行命令：
```bash
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant
```
7. 如果此裝置仍未驗證，請針對相符帳號執行命令：
```bash
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify device --recovery-key-stdin --account assistant
```
如果復原金鑰已接受且備份可用，但 `Cross-signing verified`
仍為 `no`，請從另一個 Matrix 用戶端完成自我驗證：
```bash
openclaw matrix verify self
```
在另一個 Matrix 用戶端中接受請求，比對表情符號或十進位數字，
並且只有在相符時輸入 `yes`。此命令只有在
`Cross-signing verified` 變為 `yes` 之後才會成功結束。
8. 如果你有意放棄無法復原的舊歷史紀錄，並想為未來訊息建立全新的備份基準，請執行：
```bash
openclaw matrix verify backup reset --yes
```
9. 如果尚未存在伺服器端金鑰備份，請建立一個以供未來復原：
```bash
openclaw matrix verify bootstrap
```
## 加密遷移如何運作
加密遷移是兩階段流程：
1. 如果加密遷移可操作，啟動流程或 `openclaw doctor --fix` 會建立或重用遷移前快照。
2. 啟動流程或 `openclaw doctor --fix` 會透過啟用中的 Matrix Plugin 安裝檢查舊 Matrix 加密儲存。
3. 如果找到備份解密金鑰，OpenClaw 會將它寫入新的復原金鑰流程，並將房間金鑰還原標記為待處理。
4. 在下一次 Matrix 啟動時，OpenClaw 會自動將已備份的房間金鑰還原到新的加密儲存中。
如果舊儲存回報有從未備份的房間金鑰，OpenClaw 會發出警告，而不是假裝復原成功。
## 常見訊息及其含義
### 升級與偵測訊息
`Matrix plugin upgraded in place.`
- 含義：偵測到舊的磁碟 Matrix 狀態，並已遷移到目前版面。
- 要做什麼：除非同一輸出也包含警告，否則不需要做任何事。
`Matrix migration snapshot created before applying Matrix upgrades.`
- 含義：OpenClaw 在變更 Matrix 狀態之前建立了復原封存檔。
- 要做什麼：保留印出的封存檔路徑，直到你確認遷移成功。
`Matrix migration snapshot reused before applying Matrix upgrades.`
- 含義：OpenClaw 找到既有的 Matrix 遷移快照標記，並重用該封存檔，而不是建立重複備份。
- 要做什麼：保留印出的封存檔路徑，直到你確認遷移成功。
`Legacy Matrix state detected at ... but channels.matrix is not configured yet.`
- 含義：舊的 Matrix 狀態存在，但 OpenClaw 無法將它對應到目前 Matrix 帳號，因為 Matrix 尚未設定。
- 要做什麼：設定 `channels.matrix`，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).`
- 含義：OpenClaw 找到舊狀態，但仍無法判定確切的目前帳號/裝置根目錄。
- 要做什麼：使用可運作的 Matrix 登入啟動 Gateway 一次，或在快取憑證存在後重新執行 `openclaw doctor --fix`。
`Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.`
- 含義：OpenClaw 找到一個共用的扁平 Matrix 儲存，但拒絕猜測哪個具名 Matrix 帳號應該接收它。
- 要做什麼：將 `channels.matrix.defaultAccount` 設為預期帳號，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`Matrix legacy sync store not migrated because the target already exists (...)`
- 含義：新的以帳號為範圍的位置已經有同步或加密儲存，因此 OpenClaw 沒有自動覆寫它。
- 要做什麼：在手動移除或移動衝突目標之前，確認目前帳號是正確帳號。
`Failed migrating Matrix legacy sync store (...)` 或 `Failed migrating Matrix legacy crypto store (...)`
- 含義：OpenClaw 嘗試移動舊 Matrix 狀態，但檔案系統操作失敗。
- 要做什麼：檢查檔案系統權限和磁碟狀態，然後重新執行 `openclaw doctor --fix`。
`Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.`
- 含義：OpenClaw 找到舊的加密 Matrix 儲存，但沒有目前 Matrix 設定可附加到它。
- 要做什麼：設定 `channels.matrix`，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).`
- 含義：加密儲存存在，但 OpenClaw 無法安全判定它屬於哪個目前帳號/裝置。
- 要做什麼：使用可運作的 Matrix 登入啟動 Gateway 一次，或在快取憑證可用後重新執行 `openclaw doctor --fix`。
`Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.`
- 含義：OpenClaw 找到一個共用的扁平舊版加密儲存，但拒絕猜測哪個具名 Matrix 帳號應該接收它。
- 要做什麼：將 `channels.matrix.defaultAccount` 設為預期帳號，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.`
- 含義：OpenClaw 偵測到舊 Matrix 狀態，但遷移仍因缺少身分或憑證資料而受阻。
- 要做什麼：完成 Matrix 登入或設定配置，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @openclaw/matrix so OpenClaw can inspect the old rust crypto store before upgrading.`
- 意義：OpenClaw 找到舊的加密 Matrix 狀態，但無法從 Matrix Plugin 載入通常會檢查該儲存區的輔助進入點。
- 處理方式：重新安裝或修復 Matrix Plugin（`openclaw plugins install @openclaw/matrix`，或針對 repo checkout 使用 `openclaw plugins install ./path/to/local/matrix-plugin`），然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
- 如果 npm 回報 OpenClaw 擁有的 Matrix 套件已棄用，請使用目前封裝版 OpenClaw 建置中隨附的
Plugin，或使用本機 checkout 路徑，直到發布較新的 npm 套件為止。
`Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.`
- 意義：OpenClaw 找到的輔助檔案路徑會跳出 Plugin 根目錄，或未通過 Plugin 邊界檢查，因此拒絕匯入它。
- 處理方式：從受信任的路徑重新安裝 Matrix Plugin，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`- Failed creating a Matrix migration snapshot before repair: ...`
`- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".`
- 意義：OpenClaw 拒絕修改 Matrix 狀態，因為它無法先建立復原快照。
- 處理方式：解決備份錯誤，然後重新執行 `openclaw doctor --fix` 或重新啟動 Gateway。
`Failed migrating legacy Matrix client storage: ...`
- 意義：Matrix 用戶端側備援流程找到舊的扁平儲存區，但移動失敗。OpenClaw 現在會中止該備援流程，而不是在沒有提示的情況下以全新儲存區啟動。
- 處理方式：檢查檔案系統權限或衝突，保留舊狀態不變，並在修正錯誤後重試。
`Matrix is installed from a custom path: ...`
- 意義：Matrix 已釘選為路徑安裝，因此主線更新不會自動以 repo 的標準 Matrix 套件取代它。
- 處理方式：當你想回到預設 Matrix Plugin 時，使用 `openclaw plugins install @openclaw/matrix` 重新安裝。
- 如果 npm 回報 OpenClaw 擁有的 Matrix 套件已棄用，請使用目前封裝版 OpenClaw 建置中隨附的
Plugin，直到發布較新的 npm 套件為止。
### 加密狀態復原訊息
`matrix: restored X/Y room key(s) from legacy encrypted-state backup`
- 意義：已備份的房間金鑰已成功還原到新的加密儲存區。
- 處理方式：通常不需要做任何事。
`matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically`
- 意義：部分舊房間金鑰只存在舊的本機儲存區，且從未上傳到 Matrix 備份。
- 處理方式：除非你能從另一個已驗證的用戶端手動復原那些金鑰，否則應預期部分舊的加密歷史記錄仍無法使用。
`Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "openclaw matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.`
- 意義：備份存在，但 OpenClaw 無法自動復原復原金鑰。
- 處理方式：執行 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`。
`Failed inspecting legacy Matrix encrypted state for account "..." (...): ...`
- 意義：OpenClaw 找到舊的加密儲存區，但無法以足夠安全的方式檢查它以準備復原。
- 處理方式：重新執行 `openclaw doctor --fix`。如果重複發生，請保留舊狀態目錄不變，並使用另一個已驗證的 Matrix 用戶端加上 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin` 進行復原。
`Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.`
- 意義：OpenClaw 偵測到備份金鑰衝突，並拒絕自動覆寫目前的 recovery-key 檔案。
- 處理方式：在重試任何還原命令之前，先確認哪個復原金鑰才是正確的。
`Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.`
- 意義：這是舊儲存格式的硬性限制。
- 處理方式：已備份的金鑰仍可還原，但僅存在本機的加密歷史記錄可能仍無法使用。
`matrix: failed restoring room keys from legacy encrypted-state backup: ...`
- 意義：新的 Plugin 嘗試還原，但 Matrix 回傳錯誤。
- 處理方式：執行 `openclaw matrix verify backup status`，必要時再使用 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin` 重試。
### 手動復原訊息
`Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.`
- 意義：OpenClaw 知道你應該有備份金鑰，但它目前未在此裝置上啟用。
- 處理方式：執行 `openclaw matrix verify backup restore`，或必要時設定 `MATRIX_RECOVERY_KEY` 並執行 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`。
`Store a recovery key with 'openclaw matrix verify device --recovery-key-stdin', then run 'openclaw matrix verify backup restore'.`
- 意義：此裝置目前沒有儲存復原金鑰。
- 處理方式：設定 `MATRIX_RECOVERY_KEY`，執行 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`，然後還原備份。
`Backup key mismatch on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin' with the matching recovery key.`
- 意義：已儲存的金鑰與作用中的 Matrix 備份不相符。
- 處理方式：將 `MATRIX_RECOVERY_KEY` 設為正確的金鑰，並執行 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`。
如果你接受失去無法復原的舊加密歷史記錄，也可以改用
`openclaw matrix verify backup reset --yes` 重設目前的備份基準。當已儲存的備份秘密損壞時，該重設也可能重新建立秘密儲存區，讓新的備份金鑰在重新啟動後能正確載入。
`Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin'.`
- 意義：備份存在，但此裝置尚未充分信任交叉簽署鏈。
- 處理方式：設定 `MATRIX_RECOVERY_KEY` 並執行 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`。
`Matrix recovery key is required`
- 意義：你嘗試執行需要復原金鑰的復原步驟，但未提供復原金鑰。
- 處理方式：使用 `--recovery-key-stdin` 重新執行命令，例如 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`。
`Invalid Matrix recovery key: ...`
- 意義：提供的金鑰無法解析，或不符合預期格式。
- 處理方式：使用你的 Matrix 用戶端或 recovery-key 檔案中的確切復原金鑰重試。
`Matrix recovery key was applied, but this device still lacks full Matrix identity trust.`
- 意義：OpenClaw 可以套用復原金鑰，但 Matrix 仍尚未為此裝置
建立完整的交叉簽署身分信任。請檢查命令輸出中的 `Recovery key accepted`、`Backup usable`、
`Cross-signing verified` 和 `Device verified by owner`。
- 處理方式：執行 `openclaw matrix verify self`，在另一個
Matrix 用戶端接受請求，比對 SAS，並且只有在相符時輸入 `yes`。該
命令會等待完整的 Matrix 身分信任後才回報成功。只有在你有意
取代目前的交叉簽署身分時，才使用
`printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing`。
`Matrix key backup is not active on this device after loading from secret storage.`
- 意義：秘密儲存區未在此裝置上產生活動的備份工作階段。
- 處理方式：先驗證裝置，然後使用 `openclaw matrix verify backup status` 重新檢查。
`Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device --recovery-key-stdin' first.`
- 意義：此裝置在完成裝置驗證前，無法從秘密儲存區還原。
- 處理方式：先執行 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`。
### 自訂 Plugin 安裝訊息
`Matrix is installed from a custom path that no longer exists: ...`
- 意義：你的 Plugin 安裝記錄指向一個已不存在的本機路徑。
- 處理方式：使用 `openclaw plugins install @openclaw/matrix` 重新安裝；如果你是從 repo checkout 執行，則使用 `openclaw plugins install ./path/to/local/matrix-plugin`。
- 如果 npm 回報 OpenClaw 擁有的 Matrix 套件已棄用，請使用目前封裝版 OpenClaw 建置中隨附的
Plugin，或使用本機 checkout 路徑，直到發布較新的 npm 套件為止。
## 如果加密歷史記錄仍未恢復
依序執行以下檢查：
```bash
openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose
```
如果備份成功還原，但某些舊房間仍缺少歷史記錄，那些遺失的金鑰很可能從未由先前的 Plugin 備份。
## 如果你想讓未來訊息從頭開始
如果你接受失去無法復原的舊加密歷史記錄，並且只想為往後建立乾淨的備份基準，請依序執行以下命令：
```bash
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
如果裝置在此之後仍未驗證，請從你的 Matrix 用戶端完成驗證：比對 SAS 表情符號或十進位代碼，並確認它們相符。
## 相關
- [Matrix](/zh-TW/channels/matrix)：頻道設定與設定。
- [Matrix 推送規則](/zh-TW/channels/matrix-push-rules)：通知路由。
- [Doctor](/zh-TW/gateway/doctor)：健康檢查與自動遷移觸發器。
- [遷移指南](/zh-TW/install/migrating)：所有遷移路徑（機器搬移、跨系統匯入）。
- [Plugin](/zh-TW/tools/plugin)：Plugin 安裝與註冊。

157
docs/zh-TW/channels/matrix-push-rules.md Normal file
View File

@ -0,0 +1,157 @@
---
read_when:
- 為自行託管的 Synapse 或 Tuwunel 設定 Matrix 靜默串流
- 使用者希望只在區塊完成時收到通知，而不是每次預覽編輯時都收到通知
summary: 用於靜默完成預覽編輯的逐收件者 Matrix 推送規則
title: 用於靜音預覽的 Matrix 推播規則
x-i18n:
generated_at: "2026-04-30T02:47:44Z"
model: gpt-5.5
provider: openai
source_hash: e2f037a50a85b350163c74cf6b9cce335ecaaa5cccc762124122ad6d0321a1fa
source_path: channels/matrix-push-rules.md
workflow: 16
---
當 `channels.matrix.streaming` 為 `"quiet"` 時，OpenClaw 會就地編輯單一預覽事件，並以自訂內容旗標標記最終編輯。只有當每位使用者的推送規則符合該旗標時，Matrix 用戶端才會在最終編輯時通知。此頁面適用於自行託管 Matrix，並想為每個接收者帳號安裝該規則的維運人員。
如果你只想使用標準的 Matrix 通知行為，請使用 `streaming: "partial"` 或關閉串流。請參閱 [Matrix 頻道設定](/zh-TW/channels/matrix#streaming-previews)。
## 先決條件
- 接收者使用者 = 應該收到通知的人
- 機器人使用者 = 傳送回覆的 OpenClaw Matrix 帳號
- 下方 API 呼叫請使用接收者使用者的存取權杖
- 在推送規則中將 `sender` 比對為機器人使用者的完整 MXID
- 接收者帳號必須已經有可運作的推送器 — 靜默預覽規則只有在一般 Matrix 推送傳遞健全時才會運作
## 步驟
<Steps>
<Step title="設定靜默預覽">
```json5
{
channels: {
matrix: {
streaming: "quiet",
},
},
}
```
</Step>
<Step title="取得接收者的存取權杖">
盡可能重用現有用戶端工作階段權杖。若要核發新的權杖：
```bash
curl -sS -X POST \
"https://matrix.example.org/_matrix/client/v3/login" \
-H "Content-Type: application/json" \
--data '{
"type": "m.login.password",
"identifier": { "type": "m.id.user", "user": "@alice:example.org" },
"password": "REDACTED"
}'
```
</Step>
<Step title="確認推送器存在">
```bash
curl -sS \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
"https://matrix.example.org/_matrix/client/v3/pushers"
```
如果沒有傳回任何推送器，請先修正此帳號的一般 Matrix 推送傳遞，再繼續。
</Step>
<Step title="安裝覆寫推送規則">
OpenClaw 會以 `content["com.openclaw.finalized_preview"] = true` 標記已最終化的純文字預覽編輯。安裝一條規則，比對該標記以及作為傳送者的機器人 MXID：
```bash
curl -sS -X PUT \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"conditions": [
{ "kind": "event_match", "key": "type", "pattern": "m.room.message" },
{
"kind": "event_property_is",
"key": "content.m\\.relates_to.rel_type",
"value": "m.replace"
},
{
"kind": "event_property_is",
"key": "content.com\\.openclaw\\.finalized_preview",
"value": true
},
{ "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
],
"actions": [
"notify",
{ "set_tweak": "sound", "value": "default" },
{ "set_tweak": "highlight", "value": false }
]
}'
```
執行前請替換：
- `https://matrix.example.org`：你的家伺服器基底 URL
- `$USER_ACCESS_TOKEN`：接收者使用者的存取權杖
- `openclaw-finalized-preview-botname`：每個機器人、每個接收者都唯一的規則 ID（模式：`openclaw-finalized-preview-<botname>`）
- `@bot:example.org`：你的 OpenClaw 機器人 MXID，不是接收者的
</Step>
<Step title="驗證">
```bash
curl -sS \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
```
接著測試串流回覆。在靜默模式中，房間會顯示靜默草稿預覽，並在區塊或回合完成時通知一次。
</Step>
</Steps>
若稍後要移除規則，請使用接收者的權杖對同一個規則 URL 執行 `DELETE`。
## 多機器人注意事項
推送規則以 `ruleId` 作為鍵：對同一個 ID 重新執行 `PUT` 會更新單一規則。若有多個 OpenClaw 機器人要通知同一個接收者，請為每個機器人建立一條規則，並使用不同的傳送者比對。
新的使用者定義 `override` 規則會插入在預設抑制規則之前，因此不需要額外的排序參數。此規則只會影響可就地最終化的純文字預覽編輯；媒體後備與過期預覽後備會使用一般 Matrix 傳遞。
## 家伺服器注意事項
<AccordionGroup>
<Accordion title="Synapse">
不需要特殊的 `homeserver.yaml` 變更。如果一般 Matrix 通知已經能送達此使用者，上方的接收者權杖加上 `pushrules` 呼叫就是主要設定步驟。
如果你在反向代理或工作節點後方執行 Synapse，請確認 `/_matrix/client/.../pushrules/` 能正確到達 Synapse。推送傳遞由主程序或 `synapse.app.pusher`／已設定的推送工作節點處理 — 請確認它們都正常運作。
此規則使用 `event_property_is` 推送規則條件（MSC3758，推送規則 v1.10），Synapse 於 2023 年加入此條件。較舊的 Synapse 版本會接受 `PUT pushrules/...` 呼叫，但會默默永遠無法比對條件 — 若最終化預覽編輯沒有送出通知，請升級 Synapse。
</Accordion>
<Accordion title="Tuwunel">
流程與 Synapse 相同；最終化預覽標記不需要 Tuwunel 專屬設定。
如果使用者在另一台裝置上處於活動狀態時通知消失，請檢查是否已啟用 `suppress_push_when_active`。Tuwunel 於 1.4.2（2025 年 9 月）加入此選項，且它可以在一台裝置處於活動狀態時刻意抑制傳送到其他裝置的推送。
</Accordion>
</AccordionGroup>
## 相關
- [Matrix 頻道設定](/zh-TW/channels/matrix)
- [串流概念](/zh-TW/concepts/streaming)

926
docs/zh-TW/channels/matrix.md Normal file
View File

@ -0,0 +1,926 @@
---
read_when:
- 在 OpenClaw 中設定 Matrix
- 設定 Matrix E2EE 與驗證
summary: Matrix 支援狀態、設定與組態範例
title: Matrix
x-i18n:
generated_at: "2026-04-30T02:47:50Z"
model: gpt-5.5
provider: openai
source_hash: 261b0eaae452cff7bb9ddf8dc67ddda45fb27b6468e95450b19207348d0b577a
source_path: channels/matrix.md
workflow: 16
---
Matrix 是 OpenClaw 隨附的頻道 Plugin。
它使用官方的 `matrix-js-sdk`，並支援 DM、房間、執行緒、媒體、反應、投票、位置和 E2EE。
## 隨附 Plugin
目前封裝的 OpenClaw 發行版本內建 Matrix Plugin。你不需要安裝任何東西；設定 `channels.matrix.*`（請參閱[設定](#setup)）就會啟用它。
對於較舊的建置版本，或排除 Matrix 的自訂安裝，請在發布後安裝目前的 npm
套件：
```bash
openclaw plugins install @openclaw/matrix
```
如果 npm 回報 OpenClaw 擁有的套件已被棄用，請使用目前封裝的
OpenClaw 建置版本或本機 checkout，直到較新的 npm 套件發布為止。
從本機 checkout：
```bash
openclaw plugins install ./path/to/local/matrix-plugin
```
`plugins install` 會註冊並啟用 Plugin，因此不需要另外執行 `openclaw plugins enable matrix` 步驟。不過在你設定下方的頻道之前，Plugin 仍然不會執行任何動作。請參閱 [Plugins](/zh-TW/tools/plugin) 了解一般 Plugin 行為與安裝規則。
## 設定
1. 在你的 homeserver 上建立 Matrix 帳號。
2. 使用 `homeserver` + `accessToken`，或 `homeserver` + `userId` + `password` 設定 `channels.matrix`。
3. 重新啟動 Gateway。
4. 與 bot 開始 DM，或邀請它加入房間（請參閱 [auto-join](#auto-join) — 只有在 `autoJoin` 允許時，新邀請才會進入）。
### 互動式設定
```bash
openclaw channels add
openclaw configure --section channels
```
精靈會詢問：homeserver URL、驗證方法（存取權杖或密碼）、使用者 ID（僅限密碼驗證）、選用的裝置名稱、是否啟用 E2EE，以及是否設定房間存取與 auto-join。
如果相符的 `MATRIX_*` 環境變數已存在，且所選帳號沒有已儲存的驗證資訊，精靈會提供環境變數捷徑。若要在儲存 allowlist 前解析房間名稱，請執行 `openclaw channels resolve --channel matrix "Project Room"`。啟用 E2EE 時，精靈會寫入設定，並執行與 [`openclaw matrix encryption setup`](#encryption-and-verification) 相同的 bootstrap。
### 最小設定
以權杖為基礎：
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
dm: { policy: "pairing" },
},
},
}
```
以密碼為基礎（首次登入後會快取權杖）：
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
userId: "@bot:example.org",
password: "replace-me", // pragma: allowlist secret
deviceName: "OpenClaw Gateway",
},
},
}
```
### Auto-join
`channels.matrix.autoJoin` 預設為 `off`。使用預設值時，bot 不會因新邀請而出現在新的房間或 DM 中，直到你手動加入為止。
OpenClaw 無法在邀請時判斷受邀房間是 DM 還是群組，因此所有邀請（包括 DM 形式的邀請）都會先經過 `autoJoin`。`dm.policy` 只會在之後套用，也就是 bot 已加入且房間已分類之後。
<Warning>
設定 `autoJoin: "allowlist"` 加上 `autoJoinAllowlist`，可限制 bot 接受哪些邀請；或設定 `autoJoin: "always"` 以接受所有邀請。
`autoJoinAllowlist` 只接受穩定目標：`!roomId:server`、`#alias:server` 或 `*`。純房間名稱會被拒絕；alias 項目會根據 homeserver 解析，而不是根據受邀房間宣稱的狀態解析。
</Warning>
```json5
{
channels: {
matrix: {
autoJoin: "allowlist",
autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
groups: {
"!ops:example.org": { requireMention: true },
},
},
},
}
```
若要接受所有邀請，請使用 `autoJoin: "always"`。
### Allowlist 目標格式
DM 和房間 allowlist 最好填入穩定 ID：
- DM（`dm.allowFrom`、`groupAllowFrom`、`groups.<room>.users`）：使用 `@user:server`。只有在 homeserver 目錄剛好回傳一個相符項目時，才會解析顯示名稱。
- 房間（`groups`、`autoJoinAllowlist`）：使用 `!room:server` 或 `#alias:server`。名稱會盡力根據已加入的房間解析；未解析的項目會在執行階段被忽略。
### 帳號 ID 正規化
精靈會將友善名稱轉換成正規化的帳號 ID。例如，`Ops Bot` 會變成 `ops-bot`。標點符號會在 scoped 環境變數名稱中逸出，避免兩個帳號衝突：`-` → `_X2D_`，因此 `ops-prod` 會對應到 `MATRIX_OPS_X2D_PROD_*`。
### 快取的憑證
Matrix 會將快取的憑證儲存在 `~/.openclaw/credentials/matrix/` 下：
- 預設帳號：`credentials.json`
- 命名帳號：`credentials-<account>.json`
當快取憑證存在於該處時，即使設定檔中沒有存取權杖，OpenClaw 也會將 Matrix 視為已設定 — 這涵蓋設定流程、`openclaw doctor` 和頻道狀態探測。
### 環境變數
在等效的設定鍵未設定時使用。預設帳號使用未加前綴的名稱；命名帳號會在尾碼前插入帳號 ID。
| 預設帳號 | 命名帳號（`<ID>` 是正規化的帳號 ID） |
| --------------------- | --------------------------------------------------- |
| `MATRIX_HOMESERVER` | `MATRIX_<ID>_HOMESERVER` |
| `MATRIX_ACCESS_TOKEN` | `MATRIX_<ID>_ACCESS_TOKEN` |
| `MATRIX_USER_ID` | `MATRIX_<ID>_USER_ID` |
| `MATRIX_PASSWORD` | `MATRIX_<ID>_PASSWORD` |
| `MATRIX_DEVICE_ID` | `MATRIX_<ID>_DEVICE_ID` |
| `MATRIX_DEVICE_NAME` | `MATRIX_<ID>_DEVICE_NAME` |
| `MATRIX_RECOVERY_KEY` | `MATRIX_<ID>_RECOVERY_KEY` |
對於帳號 `ops`，名稱會變成 `MATRIX_OPS_HOMESERVER`、`MATRIX_OPS_ACCESS_TOKEN`，依此類推。recovery-key 環境變數會由具備 recovery 感知能力的 CLI 流程（`verify backup restore`、`verify device`、`verify bootstrap`）讀取，前提是你透過 `--recovery-key-stdin` 將金鑰 pipe 進去。
`MATRIX_HOMESERVER` 不能從 workspace `.env` 設定；請參閱 [Workspace `.env` 檔案](/zh-TW/gateway/security)。
## 設定範例
包含 DM pairing、房間 allowlist 和 E2EE 的實用基準：
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: {
policy: "pairing",
sessionScope: "per-room",
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": { requireMention: true },
},
autoJoin: "allowlist",
autoJoinAllowlist: ["!roomid:example.org"],
threadReplies: "inbound",
replyToMode: "off",
streaming: "partial",
},
},
}
```
## 串流預覽
Matrix 回覆串流是選擇性啟用的。`streaming` 控制 OpenClaw 如何傳遞進行中的 assistant 回覆；`blockStreaming` 控制每個已完成的區塊是否保留為自己的 Matrix 訊息。
```json5
{
channels: {
matrix: {
streaming: "partial",
},
},
}
```
若要保留即時答案預覽，但隱藏暫時性的工具/進度列，請使用物件
形式：
```json5
{
channels: {
matrix: {
streaming: {
mode: "partial",
preview: {
toolProgress: false,
},
},
},
},
}
```
| `streaming` | 行為 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"off"`（預設） | 等待完整回覆，然後傳送一次。`true` ↔ `"partial"`，`false` ↔ `"off"`。 |
| `"partial"` | 在模型寫入目前區塊時，就地編輯一則一般文字訊息。標準 Matrix 用戶端可能會在第一次預覽時通知，而不是在最終編輯時通知。 |
| `"quiet"` | 與 `"partial"` 相同，但訊息是非通知 notice。只有當每位使用者的 push rule 符合最終編輯時，收件人才會收到通知（如下所述）。 |
`blockStreaming` 獨立於 `streaming`：
| `streaming` | `blockStreaming: true` | `blockStreaming: false`（預設） |
| ----------------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
| `"partial"` / `"quiet"` | 目前區塊的即時草稿，已完成的區塊保留為訊息 | 目前區塊的即時草稿，並就地完成 |
| `"off"` | 每個完成區塊一則會通知的 Matrix 訊息 | 完整回覆一則會通知的 Matrix 訊息 |
注意事項：
- 如果預覽超過 Matrix 的單一事件大小限制，OpenClaw 會停止預覽串流，並退回只傳遞最終內容。
- 媒體回覆一律正常傳送附件。如果過期預覽無法再安全重用，OpenClaw 會在傳送最終媒體回覆前將其 redact。
- Matrix 預覽串流啟用時，預設會啟用工具進度預覽更新。設定 `streaming.preview.toolProgress: false` 可保留答案文字的預覽編輯，但讓工具進度走一般傳遞路徑。
- 預覽編輯會耗費額外的 Matrix API 呼叫。如果你想要最保守的 rate-limit profile，請保留 `streaming: "off"`。
## 核准 metadata
Matrix 原生核准提示是一般 `m.room.message` 事件，其 OpenClaw 專用自訂事件內容位於 `com.openclaw.approval` 下。Matrix 允許自訂事件內容鍵，因此標準用戶端仍會顯示文字 body，而支援 OpenClaw 的用戶端可以讀取結構化的核准 ID、類型、狀態、可用決策，以及 exec/Plugin 詳細資料。
當核准提示過長，無法放入單一 Matrix 事件時，OpenClaw 會將可見文字分成多個 chunk，並只將 `com.openclaw.approval` 附加到第一個 chunk。允許/拒絕決策的反應會綁定到該第一個事件，因此長提示會和單一事件提示保持相同的核准目標。
### 自行託管的 quiet 最終預覽 push rule
`streaming: "quiet"` 只會在區塊或 turn 完成後通知收件人 — 每位使用者的 push rule 必須符合最終預覽標記。請參閱 [quiet 預覽的 Matrix push rule](/zh-TW/channels/matrix-push-rules) 取得完整流程（收件人權杖、pusher 檢查、規則安裝、每個 homeserver 的注意事項）。
## Bot 對 bot 房間
預設情況下，來自其他已設定 OpenClaw Matrix 帳號的 Matrix 訊息會被忽略。
當你有意需要 inter-agent Matrix 流量時，請使用 `allowBots`：
```json5
{
channels: {
matrix: {
allowBots: "mentions", // true | "mentions"
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
},
},
}
```
- `allowBots: true` 會接受來自其他已設定 Matrix bot 帳號、且位於允許房間與 DM 中的訊息。
- `allowBots: "mentions"` 只會在那些訊息於房間中明顯提及此 bot 時接受。DM 仍然允許。
- `groups.<room>.allowBots` 會覆寫單一房間的帳號層級設定。
- OpenClaw 仍會忽略來自相同 Matrix 使用者 ID 的訊息，以避免自我回覆迴圈。
- Matrix 在此不公開原生 bot 旗標；OpenClaw 將「bot-authored」視為「由此 OpenClaw Gateway 上另一個已設定的 Matrix 帳號傳送」。
在共享房間中啟用 bot 對 bot 流量時，請使用嚴格的房間 allowlist 和提及要求。
## 加密與驗證
在加密（E2EE）聊天室中，對外送出的圖片事件會使用 `thumbnail_file`，因此圖片預覽會與完整附件一併加密。未加密的聊天室仍使用一般的 `thumbnail_url`。不需要任何設定 — Plugin 會自動偵測 E2EE 狀態。
所有 `openclaw matrix` 命令都接受 `--verbose`（完整診斷）、`--json`（機器可讀輸出）以及 `--account <id>`（多帳號設定）。預設輸出簡潔，內部 SDK 記錄會保持安靜。下列範例顯示標準形式；視需要加入旗標。
### 啟用加密
```bash
openclaw matrix encryption setup
```
啟動密鑰儲存與交叉簽署，必要時建立聊天室金鑰備份，然後列印狀態與後續步驟。實用旗標：
- `--recovery-key <key>` 在啟動前套用復原金鑰（建議使用下方文件說明的 stdin 形式）
- `--force-reset-cross-signing` 捨棄目前的交叉簽署身分並建立新的身分（僅在有意為之時使用）
對於新帳號，請在建立時啟用 E2EE：
```bash
openclaw matrix account add \
--homeserver https://matrix.example.org \
--access-token syt_xxx \
--enable-e2ee
```
`--encryption` 是 `--enable-e2ee` 的別名。
等效的手動設定：
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: { policy: "pairing" },
},
},
}
```
### 狀態與信任訊號
```bash
openclaw matrix verify status
openclaw matrix verify status --include-recovery-key --json
```
`verify status` 會報告三個獨立的信任訊號（`--verbose` 會顯示全部）：
- `Locally trusted`：僅受此用戶端信任
- `Cross-signing verified`：SDK 回報已透過交叉簽署驗證
- `Signed by owner`：由你自己的自我簽署金鑰簽署（僅供診斷）
只有當 `Cross-signing verified` 為 `yes` 時，`Verified by owner` 才會變成 `yes`。僅有本機信任或擁有者簽章並不足夠。
`--allow-degraded-local-state` 會在不先準備 Matrix 帳號的情況下回傳盡力而為的診斷；適合用於離線或部分設定完成的探測。
### 使用復原金鑰驗證此裝置
復原金鑰屬於敏感資訊 — 請透過 stdin 傳入，而不要放在命令列上。設定 `MATRIX_RECOVERY_KEY`（或對具名帳號使用 `MATRIX_<ID>_RECOVERY_KEY`）：
```bash
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
```
此命令會回報三種狀態：
- `Recovery key accepted`：Matrix 已接受此金鑰用於密鑰儲存或裝置信任。
- `Backup usable`：可以使用受信任的復原材料載入聊天室金鑰備份。
- `Device verified by owner`：此裝置具有完整的 Matrix 交叉簽署身分信任。
當完整身分信任尚未完成時，即使復原金鑰已解鎖備份材料，也會以非零狀態結束。在這種情況下，請從另一個 Matrix 用戶端完成自我驗證：
```bash
openclaw matrix verify self
```
`verify self` 會等到 `Cross-signing verified: yes` 後才成功結束。使用 `--timeout-ms <ms>` 調整等待時間。
也接受字面金鑰形式 `openclaw matrix verify device "<recovery-key>"`，但金鑰會留在你的 shell 歷史記錄中。
### 啟動或修復交叉簽署
```bash
openclaw matrix verify bootstrap
```
`verify bootstrap` 是加密帳號的修復與設定命令。依序會：
- 啟動密鑰儲存，並在可能時重用既有復原金鑰
- 啟動交叉簽署並上傳遺漏的公開金鑰
- 標記並交叉簽署目前裝置
- 如果尚未存在，建立伺服器端聊天室金鑰備份
如果 homeserver 需要 UIA 才能上傳交叉簽署金鑰，OpenClaw 會先嘗試不使用驗證，接著嘗試 `m.login.dummy`，再嘗試 `m.login.password`（需要 `channels.matrix.password`）。
實用旗標：
- `--recovery-key-stdin`（搭配 `printf '%s\n' "$MATRIX_RECOVERY_KEY" | …`）或 `--recovery-key <key>`
- `--force-reset-cross-signing` 用於捨棄目前的交叉簽署身分（僅限有意為之）
### 聊天室金鑰備份
```bash
openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
```
`backup status` 會顯示是否存在伺服器端備份，以及此裝置是否能解密該備份。`backup restore` 會將已備份的聊天室金鑰匯入本機加密儲存；如果復原金鑰已在磁碟上，可以省略 `--recovery-key-stdin`。
若要以全新基準取代損壞的備份（接受遺失無法復原的舊歷史記錄；如果目前備份密鑰無法載入，也可以重新建立密鑰儲存）：
```bash
openclaw matrix verify backup reset --yes
```
只有在你有意讓先前的復原金鑰無法再解鎖新的備份基準時，才加入 `--rotate-recovery-key`。
### 列出、請求與回應驗證
```bash
openclaw matrix verify list
```
列出所選帳號的待處理驗證請求。
```bash
openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF
```
從此 OpenClaw 帳號送出驗證請求。`--own-user` 會請求自我驗證（你在同一使用者的另一個 Matrix 用戶端中接受提示）；`--user-id`/`--device-id`/`--room-id` 會指定其他人。`--own-user` 不能與其他指定目標的旗標合併使用。
對於較底層的生命週期處理 — 通常是在旁路追蹤另一個用戶端傳入的請求時 — 這些命令會作用於特定請求 `<id>`（由 `verify list` 和 `verify request` 列印）：
| 命令 | 用途 |
| ------------------------------------------ | ----------------------------------------------------------- |
| `openclaw matrix verify accept <id>` | 接受傳入請求 |
| `openclaw matrix verify start <id>` | 啟動 SAS 流程 |
| `openclaw matrix verify sas <id>` | 列印 SAS 表情符號或十進位數字 |
| `openclaw matrix verify confirm-sas <id>` | 確認 SAS 與另一個用戶端顯示的內容相符 |
| `openclaw matrix verify mismatch-sas <id>` | 當表情符號或十進位數字不相符時拒絕 SAS |
| `openclaw matrix verify cancel <id>` | 取消；接受選用的 `--reason <text>` 與 `--code <matrix-code>` |
當驗證錨定到特定直接訊息聊天室時，`accept`、`start`、`sas`、`confirm-sas`、`mismatch-sas` 和 `cancel` 全都接受 `--user-id` 與 `--room-id` 作為 DM 後續提示。
### 多帳號注意事項
若沒有 `--account <id>`，Matrix CLI 命令會使用隱含的預設帳號。如果你有多個具名帳號且尚未設定 `channels.matrix.defaultAccount`，它們會拒絕猜測並要求你選擇。當具名帳號停用或無法使用 E2EE 時，錯誤會指出該帳號的設定鍵，例如 `channels.matrix.accounts.assistant.encryption`。
<AccordionGroup>
<Accordion title="啟動行為">
使用 `encryption: true` 時，`startupVerification` 預設為 `"if-unverified"`。啟動時，未驗證裝置會在另一個 Matrix 用戶端中請求自我驗證，並略過重複請求與套用冷卻時間（預設 24 小時）。使用 `startupVerificationCooldownHours` 調整，或使用 `startupVerification: "off"` 停用。
啟動時也會執行保守的加密啟動程序，重用目前的密鑰儲存與交叉簽署身分。如果啟動狀態損壞，OpenClaw 會即使沒有 `channels.matrix.password` 也嘗試受保護的修復；如果 homeserver 需要密碼 UIA，啟動會記錄警告並保持非致命狀態。已由擁有者簽署的裝置會保留。
請參閱 [Matrix 遷移](/zh-TW/channels/matrix-migration) 了解完整升級流程。
</Accordion>
<Accordion title="驗證通知">
Matrix 會將驗證生命週期通知以 `m.notice` 訊息發布到嚴格 DM 驗證聊天室中：請求、就緒（含「以表情符號驗證」指引）、開始/完成，以及可用時的 SAS（表情符號/十進位）詳細資訊。
來自另一個 Matrix 用戶端的傳入請求會被追蹤並自動接受。對於自我驗證，OpenClaw 會自動啟動 SAS 流程，並在表情符號驗證可用後確認自身這一側 — 你仍需要在 Matrix 用戶端中比較並確認「它們相符」。
驗證系統通知不會轉送到代理聊天管線。
</Accordion>
<Accordion title="已刪除或無效的 Matrix 裝置">
如果 `verify status` 顯示目前裝置不再列於 homeserver 上，請建立新的 OpenClaw Matrix 裝置。對於密碼登入：
```bash
openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--user-id '@assistant:example.org' \
--password '<password>' \
--device-name OpenClaw-Gateway
```
對於權杖驗證，請在你的 Matrix 用戶端或管理 UI 中建立新的存取權杖，然後更新 OpenClaw：
```bash
openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--access-token '<token>'
```
將 `assistant` 替換為失敗命令中的帳號 ID，或省略 `--account` 以使用預設帳號。
</Accordion>
<Accordion title="裝置維護">
舊的 OpenClaw 管理裝置可能會累積。列出並修剪：
```bash
openclaw matrix devices list
openclaw matrix devices prune-stale
```
</Accordion>
<Accordion title="加密儲存">
Matrix E2EE 使用官方 `matrix-js-sdk` Rust 加密路徑，並以 `fake-indexeddb` 作為 IndexedDB shim。加密狀態會持久化到 `crypto-idb-snapshot.json`（限制性檔案權限）。
加密的執行階段狀態位於 `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` 底下，並包含同步儲存、加密儲存、復原金鑰、IDB 快照、執行緒綁定與啟動驗證狀態。當權杖變更但帳號身分維持相同時，OpenClaw 會重用最佳的既有根目錄，因此先前狀態仍保持可見。
</Accordion>
</AccordionGroup>
## 個人檔案管理
更新所選帳號的 Matrix 自我個人檔案：
```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```
你可以在一次呼叫中同時傳入兩個選項。Matrix 可直接接受 `mxc://` 頭像 URL；當你傳入 `http://` 或 `https://` 時，OpenClaw 會先上傳檔案，並將解析後的 `mxc://` URL 儲存到 `channels.matrix.avatarUrl`（或每帳號覆寫值）。
## 執行緒
Matrix 支援原生 Matrix 執行緒，可用於自動回覆與訊息工具傳送。兩個獨立旋鈕控制行為：
### 工作階段路由（`sessionScope`）
`dm.sessionScope` 決定 Matrix DM 聊天室如何對應到 OpenClaw 工作階段：
- `"per-user"`（預設）：與同一個已路由對等方的所有 DM 聊天室共用一個工作階段。
- `"per-room"`：即使對等方相同，每個 Matrix DM 聊天室也會取得自己的工作階段鍵。
明確對話綁定一律優先於 `sessionScope`，因此已綁定的聊天室與執行緒會保留其選定的目標工作階段。
### 回覆執行緒（`threadReplies`）
`threadReplies` 決定 bot 發布回覆的位置：
- `"off"`：回覆為頂層訊息。傳入的執行緒訊息會留在父工作階段。
- `"inbound"`：只有當傳入訊息已在該執行緒中時，才在執行緒內回覆。
- `"always"`：在以觸發訊息為根的執行緒內回覆；該對話會從第一次觸發起，透過相符的執行緒範圍工作階段路由。
`dm.threadReplies` 僅對 DM 覆寫此設定 — 例如，保持聊天室執行緒隔離，同時讓 DM 維持扁平。
### 執行緒繼承與斜線命令
- 傳入的對話串訊息會包含對話串根訊息，作為額外的 agent 脈絡。
- 訊息工具傳送在目標為同一個房間（或同一個 DM 使用者目標）時，會自動繼承目前的 Matrix 對話串，除非明確提供 `threadId`。
- DM 使用者目標重用只有在目前工作階段中繼資料證明是同一個 Matrix 帳號上的同一個 DM 對象時才會啟用；否則 OpenClaw 會退回一般的使用者範圍路由。
- `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及繫結對話串的 `/acp spawn` 都可在 Matrix 房間和 DM 中使用。
- 當 `threadBindings.spawnSubagentSessions: true` 時，頂層 `/focus` 會建立新的 Matrix 對話串，並將其繫結到目標工作階段。
- 在現有 Matrix 對話串內執行 `/focus` 或 `/acp spawn --thread here`，會就地繫結該對話串。
當 OpenClaw 偵測到 Matrix DM 房間與同一個共享工作階段上的另一個 DM 房間衝突時，會在該房間張貼一次性的 `m.notice`，指向 `/focus` 逃生路徑並建議變更 `dm.sessionScope`。此通知只會在啟用對話串繫結時出現。
## ACP 對話繫結
Matrix 房間、DM 和現有 Matrix 對話串都可以轉換成持久的 ACP 工作區，而不改變聊天介面。
快速操作流程：
- 在你想持續使用的 Matrix DM、房間或現有對話串內執行 `/acp spawn codex --bind here`。
- 在頂層 Matrix DM 或房間中，目前的 DM/房間會保留為聊天介面，未來訊息會路由到新產生的 ACP 工作階段。
- 在現有 Matrix 對話串內，`--bind here` 會就地繫結目前的對話串。
- `/new` 和 `/reset` 會就地重設同一個已繫結的 ACP 工作階段。
- `/acp close` 會關閉 ACP 工作階段並移除繫結。
注意事項：
- `--bind here` 不會建立子 Matrix 對話串。
- `threadBindings.spawnAcpSessions` 只有在 `/acp spawn --thread auto|here` 時才需要，此時 OpenClaw 需要建立或繫結子 Matrix 對話串。
### 對話串繫結設定
Matrix 會從 `session.threadBindings` 繼承全域預設值，也支援各通道覆寫：
- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSubagentSessions`
- `threadBindings.spawnAcpSessions`
Matrix 繫結對話串的 spawn 旗標採選擇啟用：
- 設定 `threadBindings.spawnSubagentSessions: true`，允許頂層 `/focus` 建立並繫結新的 Matrix 對話串。
- 設定 `threadBindings.spawnAcpSessions: true`，允許 `/acp spawn --thread auto|here` 將 ACP 工作階段繫結到 Matrix 對話串。
## 回應
Matrix 支援傳出回應、傳入回應通知和確認回應。
傳出回應工具由 `channels.matrix.actions.reactions` 控制：
- `react` 會將回應新增到 Matrix 事件。
- `reactions` 會列出 Matrix 事件目前的回應摘要。
- `emoji=""` 會移除該事件上 bot 自己的回應。
- `remove: true` 只會從 bot 移除指定的 emoji 回應。
**解析順序**（第一個已定義的值優先）：
| 設定 | 順序 |
| ----------------------- | -------------------------------------------------------------------------------- |
| `ackReaction` | 每帳號 → 通道 → `messages.ackReaction` → agent 身分 emoji 後備 |
| `ackReactionScope` | 每帳號 → 通道 → `messages.ackReactionScope` → 預設 `"group-mentions"` |
| `reactionNotifications` | 每帳號 → 通道 → 預設 `"own"` |
`reactionNotifications: "own"` 會在新增的 `m.reaction` 事件以 bot 撰寫的 Matrix 訊息為目標時轉送；`"off"` 會停用回應系統事件。回應移除不會合成為系統事件，因為 Matrix 會將其呈現為刪訂，而不是獨立的 `m.reaction` 移除。
## 歷史脈絡
- `channels.matrix.historyLimit` 控制當 Matrix 房間訊息觸發 agent 時，會有多少最近的房間訊息作為 `InboundHistory` 包含進來。會退回 `messages.groupChat.historyLimit`；如果兩者都未設定，實際預設值為 `0`。設定為 `0` 可停用。
- Matrix 房間歷史只限房間。DM 會繼續使用一般工作階段歷史。
- Matrix 房間歷史只包含待處理內容：OpenClaw 會緩衝尚未觸發回覆的房間訊息，然後在提及或其他觸發到達時快照該視窗。
- 目前的觸發訊息不會包含在 `InboundHistory` 中；它會留在該回合的主要傳入本文中。
- 同一個 Matrix 事件的重試會重用原始歷史快照，而不是向前漂移到較新的房間訊息。
## 脈絡可見性
Matrix 支援共享的 `contextVisibility` 控制，用於補充房間脈絡，例如擷取的回覆文字、對話串根和待處理歷史。
- `contextVisibility: "all"` 是預設值。補充脈絡會按收到的內容保留。
- `contextVisibility: "allowlist"` 會將補充脈絡篩選為主動房間/使用者允許清單檢查所允許的傳送者。
- `contextVisibility: "allowlist_quote"` 的行為類似 `allowlist`，但仍會保留一則明確引用的回覆。
此設定影響補充脈絡可見性，不影響傳入訊息本身是否可以觸發回覆。
觸發授權仍來自 `groupPolicy`、`groups`、`groupAllowFrom` 和 DM 政策設定。
## DM 和房間政策
```json5
{
channels: {
matrix: {
dm: {
policy: "allowlist",
allowFrom: ["@admin:example.org"],
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": { requireMention: true },
},
},
},
}
```
若要完全靜音 DM，同時保持房間可用，請設定 `dm.enabled: false`：
```json5
{
channels: {
matrix: {
dm: { enabled: false },
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
},
},
}
```
請參閱[群組](/zh-TW/channels/groups)，了解提及閘控和允許清單行為。
Matrix DM 的配對範例：
```bash
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
如果未核准的 Matrix 使用者在核准前持續傳訊息給你，OpenClaw 會重用同一個待處理配對碼，並可能在短暫冷卻後傳送提醒回覆，而不是鑄造新的代碼。
請參閱[配對](/zh-TW/channels/pairing)，了解共享的 DM 配對流程和儲存配置。
## 直接房間修復
如果直接訊息狀態不同步，OpenClaw 可能會留下過時的 `m.direct` 對應，指向舊的單人房間，而不是即時 DM。檢查某個對象目前的對應：
```bash
openclaw matrix direct inspect --user-id @alice:example.org
```
修復它：
```bash
openclaw matrix direct repair --user-id @alice:example.org
```
兩個命令都接受 `--account <id>`，可用於多帳號設定。修復流程：
- 偏好已在 `m.direct` 中對應的嚴格 1:1 DM
- 退回目前已加入、與該使用者的任何嚴格 1:1 DM
- 如果沒有健康的 DM，則建立新的直接房間並重寫 `m.direct`
它不會自動刪除舊房間。它會選擇健康的 DM 並更新對應，讓未來的 Matrix 傳送、驗證通知和其他直接訊息流程都以正確房間為目標。
## Exec 核准
Matrix 可以作為原生核准用戶端。在 `channels.matrix.execApprovals` 下設定（或使用 `channels.matrix.accounts.<account>.execApprovals` 作為每帳號覆寫）：
- `enabled`：透過 Matrix 原生提示傳遞核准。未設定或為 `"auto"` 時，只要至少可解析一位核准者，Matrix 就會自動啟用。設定 `false` 可明確停用。
- `approvers`：允許核准 exec 要求的 Matrix 使用者 ID（`@owner:example.org`）。選用 — 會退回 `channels.matrix.dm.allowFrom`。
- `target`：提示送達位置。`"dm"`（預設）會傳送到核准者 DM；`"channel"` 會傳送到來源 Matrix 房間或 DM；`"both"` 會傳送到兩者。
- `agentFilter` / `sessionFilter`：選用允許清單，指定哪些 agent/工作階段會觸發 Matrix 傳遞。
不同核准種類的授權略有差異：
- **Exec 核准**使用 `execApprovals.approvers`，並退回 `dm.allowFrom`。
- **Plugin 核准**只透過 `dm.allowFrom` 授權。
兩種核准都共用 Matrix 回應捷徑和訊息更新。核准者會在主要核准訊息上看到回應捷徑：
- `✅` 允許一次
- `❌` 拒絕
- `♾️` 永遠允許（當有效 exec 政策允許時）
後備斜線命令：`/approve <id> allow-once`、`/approve <id> allow-always`、`/approve <id> deny`。
只有已解析的核准者可以核准或拒絕。Exec 核准的通道傳遞會包含命令文字 — 只有在受信任的房間中才啟用 `channel` 或 `both`。
相關：[Exec 核准](/zh-TW/tools/exec-approvals)。
## 斜線命令
斜線命令（`/new`、`/reset`、`/model`、`/focus`、`/unfocus`、`/agents`、`/session`、`/acp`、`/approve` 等）可直接在 DM 中使用。在房間中，OpenClaw 也會辨識以 bot 自己的 Matrix 提及作為前綴的命令，因此 `@bot:server /new` 會觸發命令路徑，而不需要自訂提及 regex。這讓 bot 能回應 Element 和類似用戶端在使用者於輸入命令前以 Tab 補全 bot 時送出的房間風格 `@mention /command` 貼文。
授權規則仍適用：命令傳送者必須符合與一般訊息相同的 DM 或房間允許清單/擁有者政策。
## 多帳號
```json5
{
channels: {
matrix: {
enabled: true,
defaultAccount: "assistant",
dm: { policy: "pairing" },
accounts: {
assistant: {
homeserver: "https://matrix.example.org",
accessToken: "syt_assistant_xxx",
encryption: true,
},
alerts: {
homeserver: "https://matrix.example.org",
accessToken: "syt_alerts_xxx",
dm: {
policy: "allowlist",
allowFrom: ["@ops:example.org"],
threadReplies: "off",
},
},
},
},
},
}
```
**繼承：**
- 頂層 `channels.matrix` 值會作為具名帳號的預設值，除非帳號覆寫它們。
- 使用 `groups.<room>.account` 將繼承的房間項目限定到特定帳號。沒有 `account` 的項目會在帳號之間共享；當預設帳號設定於頂層時，`account: "default"` 仍然可用。
**預設帳號選擇：**
- 設定 `defaultAccount` 以選擇隱式路由、探測和 CLI 命令偏好的具名帳號。
- 如果你有多個帳號，且其中一個字面名稱為 `default`，即使未設定 `defaultAccount`，OpenClaw 也會隱式使用它。
- 如果你有多個具名帳號且未選擇預設帳號，CLI 命令會拒絕猜測 — 請設定 `defaultAccount` 或傳入 `--account <id>`。
- 只有在頂層 `channels.matrix.*` 區塊的驗證完整（`homeserver` + `accessToken`，或 `homeserver` + `userId` + `password`）時，才會被視為隱式 `default` 帳號。只要快取認證涵蓋驗證，具名帳號仍可從 `homeserver` + `userId` 探索。
**升級：**
- 當 OpenClaw 在修復或設定期間將單帳號設定升級為多帳號時，如果已有具名帳號或 `defaultAccount` 已指向某個帳號，它會保留現有具名帳號。只有 Matrix 驗證/啟動鍵會移入升級後的帳號；共享傳遞政策鍵會保留在頂層。
請參閱[設定參考](/zh-TW/gateway/config-channels#multi-account-all-channels)，了解共享的多帳號模式。
## 私有/LAN homeserver
預設情況下，OpenClaw 會封鎖私有/內部 Matrix homeserver 以防護 SSRF，除非你
明確針對每個帳號選擇啟用。
如果你的 homeserver 在 localhost、LAN/Tailscale IP 或內部主機名稱上執行，請為該 Matrix 帳號啟用
`network.dangerouslyAllowPrivateNetwork`：
```json5
{
channels: {
matrix: {
homeserver: "http://matrix-synapse:8008",
network: {
dangerouslyAllowPrivateNetwork: true,
},
accessToken: "syt_internal_xxx",
},
},
}
```
CLI 設定範例：
```bash
openclaw matrix account add \
--account ops \
--homeserver http://matrix-synapse:8008 \
--allow-private-network \
--access-token syt_ops_xxx
```
此選擇加入設定只允許受信任的私人/內部目標。公開的明文 homeserver，例如
`http://matrix.example.org:8008` 仍會被封鎖。請盡可能優先使用 `https://`。
## 代理 Matrix 流量
如果你的 Matrix 部署需要明確的對外 HTTP(S) Proxy，請設定 `channels.matrix.proxy`：
```json5
{
channels: {
matrix: {
homeserver: "https://matrix.example.org",
accessToken: "syt_bot_xxx",
proxy: "http://127.0.0.1:7890",
},
},
}
```
具名帳號可以使用 `channels.matrix.accounts.<id>.proxy` 覆寫頂層預設值。
OpenClaw 會對執行階段 Matrix 流量與帳號狀態探測使用相同的 Proxy 設定。
## 目標解析
凡是 OpenClaw 要求你提供房間或使用者目標的位置，Matrix 都接受下列目標格式：
- 使用者：`@user:server`、`user:@user:server` 或 `matrix:user:@user:server`
- 房間：`!room:server`、`room:!room:server` 或 `matrix:room:!room:server`
- 別名：`#alias:server`、`channel:#alias:server` 或 `matrix:channel:#alias:server`
Matrix 房間 ID 區分大小寫。設定明確的傳遞目標、Cron 作業、繫結或允許清單時，
請使用 Matrix 中完全相同大小寫的房間 ID。OpenClaw 會將內部工作階段金鑰正規化後儲存，
因此這些小寫金鑰並不是 Matrix 傳遞 ID 的可靠來源。
即時目錄查詢會使用已登入的 Matrix 帳號：
- 使用者查詢會查詢該 homeserver 上的 Matrix 使用者目錄。
- 房間查詢會直接接受明確的房間 ID 與別名，然後退回搜尋該帳號已加入的房間名稱。
- 已加入房間的名稱查詢是盡力而為。如果房間名稱無法解析為 ID 或別名，執行階段允許清單解析會忽略它。
## 設定參考
允許清單樣式欄位（`groupAllowFrom`、`dm.allowFrom`、`groups.<room>.users`）接受完整的 Matrix 使用者 ID（最安全）。精確目錄相符項目會在啟動時解析，並在監視器執行期間允許清單變更時重新解析；無法解析的項目會在執行階段被忽略。基於同樣原因，房間允許清單優先使用房間 ID 或別名。
### 帳號與連線
- `enabled`：啟用或停用此頻道。
- `name`：帳號的選用顯示標籤。
- `defaultAccount`：設定多個 Matrix 帳號時偏好的帳號 ID。
- `accounts`：具名的逐帳號覆寫。頂層 `channels.matrix` 值會作為預設值繼承。
- `homeserver`：homeserver URL，例如 `https://matrix.example.org`。
- `network.dangerouslyAllowPrivateNetwork`：允許此帳號連線到 `localhost`、LAN/Tailscale IP 或內部主機名稱。
- `proxy`：Matrix 流量的選用 HTTP(S) Proxy URL。支援逐帳號覆寫。
- `userId`：完整的 Matrix 使用者 ID（`@bot:example.org`）。
- `accessToken`：Token 型驗證的存取 Token。支援跨 env/file/exec 提供者使用明文與 SecretRef 值（[密鑰管理](/zh-TW/gateway/secrets)）。
- `password`：密碼型登入使用的密碼。支援明文與 SecretRef 值。
- `deviceId`：明確的 Matrix 裝置 ID。
- `deviceName`：密碼登入時使用的裝置顯示名稱。
- `avatarUrl`：用於個人檔案同步與 `profile set` 更新的已儲存自身頭像 URL。
- `initialSyncLimit`：啟動同步期間擷取的事件數量上限。
### 加密
- `encryption`：啟用 E2EE。預設：`false`。
- `startupVerification`：`"if-unverified"`（E2EE 開啟時的預設值）或 `"off"`。當此裝置尚未驗證時，在啟動時自動要求自我驗證。
- `startupVerificationCooldownHours`：下一次自動啟動要求前的冷卻時間。預設：`24`。
### 存取與政策
- `groupPolicy`：`"open"`、`"allowlist"` 或 `"disabled"`。預設：`"allowlist"`。
- `groupAllowFrom`：房間流量的使用者 ID 允許清單。
- `dm.enabled`：為 `false` 時，忽略所有 DM。預設：`true`。
- `dm.policy`：`"pairing"`（預設）、`"allowlist"`、`"open"` 或 `"disabled"`。在 bot 已加入且將房間分類為 DM 後套用；不影響邀請處理。
- `dm.allowFrom`：DM 流量的使用者 ID 允許清單。
- `dm.sessionScope`：`"per-user"`（預設）或 `"per-room"`。
- `dm.threadReplies`：僅限 DM 的回覆執行緒覆寫（`"off"`、`"inbound"`、`"always"`）。
- `allowBots`：接受來自其他已設定 Matrix bot 帳號的訊息（`true` 或 `"mentions"`）。
- `allowlistOnly`：為 `true` 時，強制所有作用中的 DM 政策（除了 `"disabled"`）與 `"open"` 群組政策改為 `"allowlist"`。不會變更 `"disabled"` 政策。
- `autoJoin`：`"always"`、`"allowlist"` 或 `"off"`。預設：`"off"`。套用於每個 Matrix 邀請，包括 DM 樣式邀請。
- `autoJoinAllowlist`：當 `autoJoin` 為 `"allowlist"` 時允許的房間/別名。別名項目會依據 homeserver 解析，而不是依據受邀房間宣稱的狀態。
- `contextVisibility`：補充內容脈絡可見性（預設 `"all"`、`"allowlist"`、`"allowlist_quote"`）。
### 回覆行為
- `replyToMode`：`"off"`、`"first"`、`"all"` 或 `"batched"`。
- `threadReplies`：`"off"`、`"inbound"` 或 `"always"`。
- `threadBindings`：執行緒繫結工作階段路由與生命週期的逐頻道覆寫。
- `streaming`：`"off"`（預設）、`"partial"`、`"quiet"`，或物件形式 `{ mode, preview: { toolProgress } }`。`true` ↔ `"partial"`，`false` ↔ `"off"`。
- `blockStreaming`：為 `true` 時，已完成的助理區塊會保留為獨立的進度訊息。
- `markdown`：輸出文字的選用 Markdown 算繪設定。
- `responsePrefix`：附加到輸出回覆前方的選用字串。
- `textChunkLimit`：當 `chunkMode: "length"` 時，以字元計算的輸出分塊大小。預設：`4000`。
- `chunkMode`：`"length"`（預設，依字元數分割）或 `"newline"`（在行邊界分割）。
- `historyLimit`：當房間訊息觸發 agent 時，作為 `InboundHistory` 包含的近期房間訊息數量。退回使用 `messages.groupChat.historyLimit`；有效預設值為 `0`（停用）。
- `mediaMaxMb`：輸出傳送與輸入處理的媒體大小上限，單位為 MB。
### 回應設定
- `ackReaction`：此頻道/帳號的 ack 回應覆寫。
- `ackReactionScope`：範圍覆寫（預設 `"group-mentions"`、`"group-all"`、`"direct"`、`"all"`、`"none"`、`"off"`）。
- `reactionNotifications`：輸入回應通知模式（預設 `"own"`、`"off"`）。
### 工具與逐房間覆寫
- `actions`：逐動作工具控管（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。
- `groups`：逐房間政策對應。解析後，工作階段識別會使用穩定的房間 ID。（`rooms` 是舊版別名。）
- `groups.<room>.account`：將一個繼承的房間項目限制到特定帳號。
- `groups.<room>.allowBots`：頻道層級設定的逐房間覆寫（`true` 或 `"mentions"`）。
- `groups.<room>.users`：逐房間傳送者允許清單。
- `groups.<room>.tools`：逐房間工具允許/拒絕覆寫。
- `groups.<room>.autoReply`：逐房間提及控管覆寫。`true` 會停用該房間的提及要求；`false` 會強制重新啟用。
- `groups.<room>.skills`：逐房間 skill 篩選器。
- `groups.<room>.systemPrompt`：逐房間系統提示片段。
### Exec 核准設定
- `execApprovals.enabled`：透過 Matrix 原生提示傳遞 exec 核准。
- `execApprovals.approvers`：允許核准的 Matrix 使用者 ID。退回使用 `dm.allowFrom`。
- `execApprovals.target`：`"dm"`（預設）、`"channel"` 或 `"both"`。
- `execApprovals.agentFilter` / `execApprovals.sessionFilter`：傳遞用的選用 agent/工作階段允許清單。
## 相關
- [頻道概觀](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及控管
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

550
docs/zh-TW/channels/mattermost.md Normal file
View File

@ -0,0 +1,550 @@
---
read_when:
- 設定 Mattermost
- 偵錯 Mattermost 路由
sidebarTitle: Mattermost
summary: Mattermost 機器人設定與 OpenClaw 設定
title: Mattermost
x-i18n:
generated_at: "2026-04-30T02:47:59Z"
model: gpt-5.5
provider: openai
source_hash: 1926a1d7347ff35ed60f8d5c3e0b26a064863ada213ad0e171776af5a84d8475
source_path: channels/mattermost.md
workflow: 16
---
狀態：隨附 Plugin（bot token + WebSocket 事件）。支援頻道、群組和 DM。Mattermost 是可自行託管的團隊訊息平台；產品詳細資料與下載請參閱官方網站 [mattermost.com](https://mattermost.com)。
## 隨附 Plugin
<Note>
Mattermost 在目前的 OpenClaw 發行版本中以隨附 Plugin 提供，因此一般封裝組建不需要另外安裝。
</Note>
如果你使用的是較舊的組建，或是排除 Mattermost 的自訂安裝，請在發布後安裝目前的 npm 套件：
<Tabs>
<Tab title="npm registry">
```bash
openclaw plugins install @openclaw/mattermost
```
</Tab>
<Tab title="本機 checkout">
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
```
</Tab>
</Tabs>
如果 npm 回報 OpenClaw 擁有的套件已棄用，請使用目前封裝的
OpenClaw 組建，或在較新的 npm 套件發布前使用本機 checkout 路徑。
詳細資料：[Plugins](/zh-TW/tools/plugin)
## 快速設定
<Steps>
<Step title="確認 Plugin 可用">
目前封裝的 OpenClaw 發行版本已經內建它。較舊或自訂安裝可以使用上述命令手動新增。
</Step>
<Step title="建立 Mattermost bot">
建立 Mattermost bot 帳號並複製 **bot token**。
</Step>
<Step title="複製基底 URL">
複製 Mattermost **基底 URL**（例如 `https://chat.example.com`）。
</Step>
<Step title="設定 OpenClaw 並啟動 Gateway">
最小設定：
```json5
{
channels: {
mattermost: {
enabled: true,
botToken: "mm-token",
baseUrl: "https://chat.example.com",
dmPolicy: "pairing",
},
},
}
```
</Step>
</Steps>
## 原生 slash commands
原生 slash commands 需要選擇啟用。啟用後，OpenClaw 會透過 Mattermost API 註冊 `oc_*` slash commands，並在 Gateway HTTP 伺服器上接收 callback POST。
```json5
{
channels: {
mattermost: {
commands: {
native: true,
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
// Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
},
},
}
```
<AccordionGroup>
<Accordion title="行為注意事項">
- `native: "auto"` 對 Mattermost 預設為停用。設定 `native: true` 以啟用。
- 如果省略 `callbackUrl`，OpenClaw 會從 Gateway 主機/連接埠 + `callbackPath` 推導出一個。
- 對於多帳號設定，`commands` 可以設定在最上層，或設定在 `channels.mattermost.accounts.<id>.commands` 底下（帳號值會覆寫最上層欄位）。
- 命令 callback 會使用 OpenClaw 註冊 `oc_*` 命令時 Mattermost 傳回的每個命令 token 進行驗證。
- 當註冊失敗、啟動不完整，或 callback token 與任何已註冊命令不相符時，slash callback 會以安全失敗方式拒絕。
</Accordion>
<Accordion title="可連線性需求">
callback 端點必須能由 Mattermost 伺服器連線到。
- 除非 Mattermost 與 OpenClaw 在同一主機/網路命名空間中執行，否則不要將 `callbackUrl` 設為 `localhost`。
- 除非該 URL 會將 `/api/channels/mattermost/command` 反向代理到 OpenClaw，否則不要將 `callbackUrl` 設為你的 Mattermost 基底 URL。
- 快速檢查方式是 `curl https://<gateway-host>/api/channels/mattermost/command`；GET 應該從 OpenClaw 傳回 `405 Method Not Allowed`，而不是 `404`。
</Accordion>
<Accordion title="Mattermost 輸出 allowlist">
如果你的 callback 目標是私有/tailnet/內部位址，請設定 Mattermost `ServiceSettings.AllowedUntrustedInternalConnections` 以包含 callback 主機/網域。
使用主機/網域項目，而不是完整 URL。
- 正確：`gateway.tailnet-name.ts.net`
- 錯誤：`https://gateway.tailnet-name.ts.net`
</Accordion>
</AccordionGroup>
## 環境變數（預設帳號）
如果你偏好使用 env vars，請在 Gateway 主機上設定這些項目：
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
<Note>
Env vars 只套用至**預設**帳號（`default`）。其他帳號必須使用設定值。
`MATTERMOST_URL` 無法從 workspace `.env` 設定；請參閱 [Workspace `.env` 檔案](/zh-TW/gateway/security)。
</Note>
## 聊天模式
Mattermost 會自動回應 DM。頻道行為由 `chatmode` 控制：
<Tabs>
<Tab title="oncall（預設）">
只在頻道中被 @提及 時回應。
</Tab>
<Tab title="onmessage">
回應每則頻道訊息。
</Tab>
<Tab title="onchar">
當訊息以觸發前綴開頭時回應。
</Tab>
</Tabs>
設定範例：
```json5
{
channels: {
mattermost: {
chatmode: "onchar",
oncharPrefixes: [">", "!"],
},
},
}
```
注意事項：
- `onchar` 仍會回應明確的 @提及。
- `channels.mattermost.requireMention` 會為舊版設定保留支援，但建議使用 `chatmode`。
## 執行緒與工作階段
使用 `channels.mattermost.replyToMode` 控制頻道與群組回覆要留在主要頻道，或是在觸發貼文下方開始執行緒。
- `off`（預設）：只有在傳入貼文已經位於執行緒中時，才在執行緒中回覆。
- `first`：對於最上層頻道/群組貼文，在該貼文下方開始執行緒，並將對話路由到執行緒範圍的工作階段。
- `all`：目前對 Mattermost 與 `first` 行為相同。
- 直接訊息會忽略此設定並保持非執行緒。
設定範例：
```json5
{
channels: {
mattermost: {
replyToMode: "all",
},
},
}
```
注意事項：
- 執行緒範圍的工作階段會使用觸發貼文 ID 作為執行緒根。
- `first` 和 `all` 目前等效，因為一旦 Mattermost 有執行緒根，後續片段與媒體會繼續留在同一個執行緒中。
## 存取控制（DM）
- 預設：`channels.mattermost.dmPolicy = "pairing"`（未知傳送者會取得 pairing code）。
- 透過以下方式核准：
- `openclaw pairing list mattermost`
- `openclaw pairing approve mattermost <CODE>`
- 公開 DM：`channels.mattermost.dmPolicy="open"` 加上 `channels.mattermost.allowFrom=["*"]`。
## 頻道（群組）
- 預設：`channels.mattermost.groupPolicy = "allowlist"`（需提及）。
- 使用 `channels.mattermost.groupAllowFrom` 將傳送者加入 allowlist（建議使用使用者 ID）。
- 每個頻道的提及覆寫位於 `channels.mattermost.groups.<channelId>.requireMention` 底下，或以 `channels.mattermost.groups["*"].requireMention` 作為預設值。
- `@username` 比對是可變的，且只在 `channels.mattermost.dangerouslyAllowNameMatching: true` 時啟用。
- 開放頻道：`channels.mattermost.groupPolicy="open"`（需提及）。
- 執行階段注意事項：如果完全缺少 `channels.mattermost`，執行階段會針對群組檢查退回使用 `groupPolicy="allowlist"`（即使已設定 `channels.defaults.groupPolicy`）。
範例：
```json5
{
channels: {
mattermost: {
groupPolicy: "open",
groups: {
"*": { requireMention: true },
"team-channel-id": { requireMention: false },
},
},
},
}
```
## 對外傳遞的目標
搭配 `openclaw message send` 或 cron/webhooks 使用這些目標格式：
- `channel:<id>` 表示頻道
- `user:<id>` 表示 DM
- `@username` 表示 DM（透過 Mattermost API 解析）
<Warning>
裸露的不透明 ID（例如 `64ifufp...`）在 Mattermost 中是**不明確的**（使用者 ID 與頻道 ID）。
OpenClaw 會以**使用者優先**方式解析它們：
- 如果該 ID 作為使用者存在（`GET /api/v4/users/<id>` 成功），OpenClaw 會透過 `/api/v4/channels/direct` 解析直接頻道後傳送 **DM**。
- 否則該 ID 會被視為**頻道 ID**。
如果你需要確定性行為，請一律使用明確前綴（`user:<id>` / `channel:<id>`）。
</Warning>
## DM 頻道重試
當 OpenClaw 傳送到 Mattermost DM 目標且需要先解析直接頻道時，預設會重試暫時性的直接頻道建立失敗。
使用 `channels.mattermost.dmChannelRetry` 為 Mattermost Plugin 全域調整該行為，或使用 `channels.mattermost.accounts.<id>.dmChannelRetry` 為單一帳號調整。
```json5
{
channels: {
mattermost: {
dmChannelRetry: {
maxRetries: 3,
initialDelayMs: 1000,
maxDelayMs: 10000,
timeoutMs: 30000,
},
},
},
}
```
注意事項：
- 這只套用至 DM 頻道建立（`/api/v4/channels/direct`），不套用至每個 Mattermost API 呼叫。
- 重試會套用至暫時性失敗，例如速率限制、5xx 回應，以及網路或逾時錯誤。
- 除了 `429` 以外的 4xx 用戶端錯誤會被視為永久錯誤，不會重試。
## 預覽串流
Mattermost 會將思考、工具活動和部分回覆文字串流到單一**草稿預覽貼文**，並在最終答案可安全傳送時就地完成。預覽會更新同一個貼文 ID，而不是用每個片段訊息洗版頻道。媒體/錯誤最終內容會取消待處理的預覽編輯，並使用正常傳遞，而不是送出一次性的預覽貼文。
透過 `channels.mattermost.streaming` 啟用：
```json5
{
channels: {
mattermost: {
streaming: "partial", // off | partial | block | progress
},
},
}
```
<AccordionGroup>
<Accordion title="串流模式">
- `partial` 是一般選擇：一篇預覽貼文會隨著回覆增加而被編輯，接著以完整答案完成。
- `block` 會在預覽貼文中使用附加式草稿片段。
- `progress` 會在產生期間顯示狀態預覽，並只在完成時發布最終答案。
- `off` 會停用預覽串流。
</Accordion>
<Accordion title="串流行為注意事項">
- 如果串流無法就地完成（例如貼文在串流中途被刪除），OpenClaw 會退回傳送新的最終貼文，確保回覆不會遺失。
- 純推理 payload 會從頻道貼文中隱藏，包括以 `> Reasoning:` blockquote 到達的文字。設定 `/reasoning on` 可在其他介面看到思考；Mattermost 最終貼文只保留答案。
- 請參閱[串流](/zh-TW/concepts/streaming#preview-streaming-modes)了解頻道對應矩陣。
</Accordion>
</AccordionGroup>
## 回應（訊息工具）
- 使用 `message action=react` 並搭配 `channel=mattermost`。
- `messageId` 是 Mattermost 貼文 ID。
- `emoji` 接受像 `thumbsup` 或 `:+1:` 這類名稱（冒號可選）。
- 設定 `remove=true`（boolean）以移除回應。
- 新增/移除回應事件會作為系統事件轉送至已路由的代理工作階段。
範例：
```
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true
```
設定：
- `channels.mattermost.actions.reactions`：啟用/停用回應動作（預設為 true）。
- 每帳號覆寫：`channels.mattermost.accounts.<id>.actions.reactions`。
## 互動式按鈕（訊息工具）
傳送含可點擊按鈕的訊息。使用者點擊按鈕時，代理會收到選項並可以回應。
將 `inlineButtons` 新增到頻道 capabilities 以啟用按鈕：
```json5
{
channels: {
mattermost: {
capabilities: ["inlineButtons"],
},
},
}
```
使用 `message action=send` 並搭配 `buttons` 參數。按鈕是 2D 陣列（按鈕列）：
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
```
按鈕欄位：
<ParamField path="text" type="string" required>
顯示標籤。
</ParamField>
<ParamField path="callback_data" type="string" required>
點擊時傳回的值（用作動作 ID）。
</ParamField>
<ParamField path="style" type='"default" | "primary" | "danger"'>
按鈕樣式。
</ParamField>
當使用者點擊按鈕時：
<Steps>
<Step title="按鈕已替換為確認訊息">
所有按鈕都會替換為一行確認訊息（例如「✓ **Yes** selected by @user」）。
</Step>
<Step title="代理收到選擇">
代理會以傳入訊息的形式收到該選擇並回應。
</Step>
</Steps>
<AccordionGroup>
<Accordion title="實作備註">
- 按鈕回呼使用 HMAC-SHA256 驗證（自動執行，無需設定）。
- Mattermost 會從其 API 回應中移除回呼資料（安全功能），因此點擊後會移除所有按鈕 — 無法只移除部分按鈕。
- 包含連字號或底線的動作 ID 會自動清理（Mattermost 路由限制）。
</Accordion>
<Accordion title="設定與可達性">
- `channels.mattermost.capabilities`：能力字串陣列。新增 `"inlineButtons"` 可在代理系統提示中啟用按鈕工具說明。
- `channels.mattermost.interactions.callbackBaseUrl`：按鈕回呼的選用外部基礎 URL（例如 `https://gateway.example.com`）。當 Mattermost 無法直接透過 Gateway 的繫結主機連到 Gateway 時使用。
- 在多帳戶設定中，你也可以在 `channels.mattermost.accounts.<id>.interactions.callbackBaseUrl` 下設定相同欄位。
- 如果省略 `interactions.callbackBaseUrl`，OpenClaw 會從 `gateway.customBindHost` + `gateway.port` 推導回呼 URL，然後退回到 `http://localhost:<port>`。
- 可達性規則：按鈕回呼 URL 必須能從 Mattermost 伺服器連到。`localhost` 只有在 Mattermost 和 OpenClaw 執行於同一主機／網路命名空間時才有效。
- 如果你的回呼目標是私有／tailnet／內部目標，請將其主機／網域加入 Mattermost `ServiceSettings.AllowedUntrustedInternalConnections`。
</Accordion>
</AccordionGroup>
### 直接 API 整合（外部指令碼）
外部指令碼和 Webhook 可以透過 Mattermost REST API 直接發佈按鈕，而不必透過代理的 `message` 工具。可行時請使用 Plugin 中的 `buildButtonAttachments()`；如果要發佈原始 JSON，請遵循這些規則：
**承載結構：**
```json5
{
channel_id: "<channelId>",
message: "Choose an option:",
props: {
attachments: [
{
actions: [
{
id: "mybutton01", // alphanumeric only — see below
type: "button", // required, or clicks are silently ignored
name: "Approve", // display label
style: "primary", // optional: "default", "primary", "danger"
integration: {
url: "https://gateway.example.com/mattermost/interactions/default",
context: {
action_id: "mybutton01", // must match button id (for name lookup)
action: "approve",
// ... any custom fields ...
_token: "<hmac>", // see HMAC section below
},
},
},
],
},
],
},
}
```
<Warning>
**關鍵規則**
1. 附件放在 `props.attachments`，不要放在頂層 `attachments`（會被靜默忽略）。
2. 每個動作都需要 `type: "button"` — 沒有它，點擊會被靜默吞掉。
3. 每個動作都需要 `id` 欄位 — Mattermost 會忽略沒有 ID 的動作。
4. 動作 `id` 必須**只能是英數字元**（`[a-zA-Z0-9]`）。連字號和底線會破壞 Mattermost 的伺服器端動作路由（回傳 404）。使用前請移除它們。
5. `context.action_id` 必須符合按鈕的 `id`，這樣確認訊息才會顯示按鈕名稱（例如「Approve」），而不是原始 ID。
6. `context.action_id` 是必要欄位 — 沒有它，互動處理器會回傳 400。
</Warning>
**HMAC 權杖產生**
Gateway 會使用 HMAC-SHA256 驗證按鈕點擊。外部指令碼必須產生符合 Gateway 驗證邏輯的權杖：
<Steps>
<Step title="從機器人權杖推導密鑰">
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
</Step>
<Step title="建構內容物件">
使用 `_token` **以外**的所有欄位建構內容物件。
</Step>
<Step title="使用排序鍵序列化">
使用**排序鍵**且**不含空格**進行序列化（Gateway 使用含排序鍵的 `JSON.stringify`，會產生緊湊輸出）。
</Step>
<Step title="簽署承載">
`HMAC-SHA256(key=secret, data=serializedContext)`
</Step>
<Step title="加入權杖">
將產生的十六進位摘要作為 `_token` 加入內容中。
</Step>
</Steps>
Python 範例：
```python
import hmac, hashlib, json
secret = hmac.new(
b"openclaw-mattermost-interactions",
bot_token.encode(), hashlib.sha256
).hexdigest()
ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
context = {**ctx, "_token": token}
```
<AccordionGroup>
<Accordion title="常見 HMAC 陷阱">
- Python 的 `json.dumps` 預設會加入空格（`{"key": "val"}`）。使用 `separators=(",", ":")` 以符合 JavaScript 的緊湊輸出（`{"key":"val"}`）。
- 一律簽署**所有**內容欄位（扣除 `_token`）。Gateway 會移除 `_token`，然後簽署剩下的所有內容。只簽署子集會導致靜默驗證失敗。
- 使用 `sort_keys=True` — Gateway 會在簽署前排序鍵，而且 Mattermost 儲存承載時可能會重新排序內容欄位。
- 從機器人權杖推導密鑰（確定性），不要使用隨機位元組。建立按鈕的程序與驗證按鈕的 Gateway 必須使用相同密鑰。
</Accordion>
</AccordionGroup>
## 目錄配接器
Mattermost Plugin 包含一個目錄配接器，可透過 Mattermost API 解析頻道和使用者名稱。這會在 `openclaw message send` 與 Cron／Webhook 傳遞中啟用 `#channel-name` 和 `@username` 目標。
無需設定 — 配接器會使用帳戶設定中的機器人權杖。
## 多帳戶
Mattermost 支援在 `channels.mattermost.accounts` 下設定多個帳戶：
```json5
{
channels: {
mattermost: {
accounts: {
default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
},
},
},
}
```
## 疑難排解
<AccordionGroup>
<Accordion title="頻道中沒有回覆">
確認機器人在頻道中並提及它（oncall）、使用觸發前綴（onchar），或設定 `chatmode: "onmessage"`。
</Accordion>
<Accordion title="驗證或多帳戶錯誤">
- 檢查機器人權杖、基礎 URL，以及帳戶是否已啟用。
- 多帳戶問題：環境變數只會套用到 `default` 帳戶。
</Accordion>
<Accordion title="原生斜線命令失敗">
- `Unauthorized: invalid command token.`：OpenClaw 未接受回呼權杖。典型原因：
- 斜線命令註冊在啟動時失敗，或只完成一部分
- 回呼打到錯誤的 Gateway／帳戶
- Mattermost 仍有舊命令指向先前的回呼目標
- Gateway 重新啟動後未重新啟用斜線命令
- 如果原生斜線命令停止運作，請檢查記錄中是否有 `mattermost: failed to register slash commands` 或 `mattermost: native slash commands enabled but no commands could be registered`。
- 如果省略 `callbackUrl`，且記錄警告回呼解析為 `http://127.0.0.1:18789/...`，該 URL 可能只有在 Mattermost 與 OpenClaw 執行於同一主機／網路命名空間時才能連到。請改為設定明確可從外部連到的 `commands.callbackUrl`。
</Accordion>
<Accordion title="按鈕問題">
- 按鈕顯示為白色方塊：代理可能正在傳送格式錯誤的按鈕資料。檢查每個按鈕是否同時具有 `text` 和 `callback_data` 欄位。
- 按鈕有呈現但點擊沒有反應：確認 Mattermost 伺服器設定中的 `AllowedUntrustedInternalConnections` 包含 `127.0.0.1 localhost`，且 ServiceSettings 中的 `EnablePostActionIntegration` 為 `true`。
- 按鈕點擊後回傳 404：按鈕 `id` 可能包含連字號或底線。Mattermost 的動作路由器會因非英數 ID 而失效。只能使用 `[a-zA-Z0-9]`。
- Gateway 記錄 `invalid _token`：HMAC 不相符。檢查你是否簽署所有內容欄位（不是子集）、使用排序鍵，並使用緊湊 JSON（沒有空格）。請參閱上方 HMAC 區段。
- Gateway 記錄 `missing _token in context`：`_token` 欄位不在按鈕內容中。請確保建構整合承載時已包含它。
- 確認訊息顯示原始 ID 而不是按鈕名稱：`context.action_id` 與按鈕的 `id` 不相符。將兩者設定為相同的清理後值。
- 代理不知道按鈕：將 `capabilities: ["inlineButtons"]` 加入 Mattermost 頻道設定。
</Accordion>
</AccordionGroup>
## 相關
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [頻道概覽](/zh-TW/channels) — 所有支援的頻道
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及門檻
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

1028
docs/zh-TW/channels/msteams.md Normal file
View File

File diff suppressed because it is too large Load Diff

182
docs/zh-TW/channels/nextcloud-talk.md Normal file
View File

@ -0,0 +1,182 @@
---
read_when:
- 開發 Nextcloud Talk 頻道功能
summary: Nextcloud Talk 支援狀態、功能與設定
title: Nextcloud Talk
x-i18n:
generated_at: "2026-04-30T02:48:12Z"
model: gpt-5.5
provider: openai
source_hash: fcbe8a65adfddc95d2b4944af88f9982e23a1676752efec2bbf40cfc4dd846d2
source_path: channels/nextcloud-talk.md
workflow: 16
---
Status: 內建 Plugin（Webhook 機器人）。支援直接訊息、聊天室、回應，以及 Markdown 訊息。
## 內建 Plugin
Nextcloud Talk 在目前的 OpenClaw 版本中以內建 Plugin 提供，因此
一般封裝建置不需要另行安裝。
如果你使用的是較舊的建置，或是排除 Nextcloud Talk 的自訂安裝，
請在有目前版本套件發布時安裝目前的 npm 套件：
透過 CLI 安裝（npm registry，有目前套件時）：
```bash
openclaw plugins install @openclaw/nextcloud-talk
```
如果 npm 回報 OpenClaw 擁有的套件已棄用，請使用目前的封裝
OpenClaw 建置，或在較新的 npm 套件發布前使用本機 checkout 路徑。
本機 checkout（從 git repo 執行時）：
```bash
openclaw plugins install ./path/to/local/nextcloud-talk-plugin
```
詳細資訊：[Plugin](/zh-TW/tools/plugin)
## 快速設定（初學者）
1. 確認 Nextcloud Talk Plugin 可用。
- 目前的封裝 OpenClaw 版本已內建它。
- 較舊或自訂安裝可以使用上述指令手動加入。
2. 在你的 Nextcloud 伺服器上建立機器人：
```bash
./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
```
3. 在目標聊天室設定中啟用機器人。
4. 設定 OpenClaw：
- 設定：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
- 或 env：`NEXTCLOUD_TALK_BOT_SECRET`（僅預設帳號）
CLI 設定：
```bash
openclaw channels add --channel nextcloud-talk \
--url https://cloud.example.com \
--token "<shared-secret>"
```
等效的明確欄位：
```bash
openclaw channels add --channel nextcloud-talk \
--base-url https://cloud.example.com \
--secret "<shared-secret>"
```
檔案支援的 secret：
```bash
openclaw channels add --channel nextcloud-talk \
--base-url https://cloud.example.com \
--secret-file /path/to/nextcloud-talk-secret
```
5. 重新啟動 Gateway（或完成設定）。
最小設定：
```json5
{
channels: {
"nextcloud-talk": {
enabled: true,
baseUrl: "https://cloud.example.com",
botSecret: "shared-secret",
dmPolicy: "pairing",
},
},
}
```
## 注意事項
- 機器人無法主動發起 DM。使用者必須先傳訊息給機器人。
- Webhook URL 必須可由 Gateway 存取；如果位於代理後方，請設定 `webhookPublicUrl`。
- 機器人 API 不支援媒體上傳；媒體會以 URL 傳送。
- Webhook payload 不會區分 DM 與聊天室；設定 `apiUser` + `apiPassword` 可啟用聊天室類型查詢（否則 DM 會被視為聊天室）。
## 存取控制（DM）
- 預設：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知傳送者會取得配對碼。
- 透過下列方式核准：
- `openclaw pairing list nextcloud-talk`
- `openclaw pairing approve nextcloud-talk <CODE>`
- 公開 DM：`channels.nextcloud-talk.dmPolicy="open"` 加上 `channels.nextcloud-talk.allowFrom=["*"]`。
- `allowFrom` 只會比對 Nextcloud 使用者 ID；顯示名稱會被忽略。
## 聊天室（群組）
- 預設：`channels.nextcloud-talk.groupPolicy = "allowlist"`（提及閘控）。
- 使用 `channels.nextcloud-talk.rooms` 將聊天室加入允許清單：
```json5
{
channels: {
"nextcloud-talk": {
rooms: {
"room-token": { requireMention: true },
},
},
},
}
```
- 若要不允許任何聊天室，請保持允許清單為空，或設定 `channels.nextcloud-talk.groupPolicy="disabled"`。
## 功能
| 功能 | 狀態 |
| --------------- | ------------- |
| 直接訊息 | 支援 |
| 聊天室 | 支援 |
| 對話串 | 不支援 |
| 媒體 | 僅限 URL |
| 回應 | 支援 |
| 原生指令 | 不支援 |
## 設定參考（Nextcloud Talk）
完整設定：[設定](/zh-TW/gateway/configuration)
Provider 選項：
- `channels.nextcloud-talk.enabled`：啟用/停用 channel 啟動。
- `channels.nextcloud-talk.baseUrl`：Nextcloud 執行個體 URL。
- `channels.nextcloud-talk.botSecret`：機器人 shared secret。
- `channels.nextcloud-talk.botSecretFile`：一般檔案 secret 路徑。symlink 會被拒絕。
- `channels.nextcloud-talk.apiUser`：用於聊天室查詢的 API 使用者（DM 偵測）。
- `channels.nextcloud-talk.apiPassword`：用於聊天室查詢的 API/app 密碼。
- `channels.nextcloud-talk.apiPasswordFile`：API 密碼檔案路徑。
- `channels.nextcloud-talk.webhookPort`：Webhook listener 連接埠（預設：8788）。
- `channels.nextcloud-talk.webhookHost`：Webhook host（預設：0.0.0.0）。
- `channels.nextcloud-talk.webhookPath`：Webhook path（預設：/nextcloud-talk-webhook）。
- `channels.nextcloud-talk.webhookPublicUrl`：外部可存取的 Webhook URL。
- `channels.nextcloud-talk.dmPolicy`：`pairing | allowlist | open | disabled`。
- `channels.nextcloud-talk.allowFrom`：DM 允許清單（使用者 ID）。`open` 需要 `"*"`。
- `channels.nextcloud-talk.groupPolicy`：`allowlist | open | disabled`。
- `channels.nextcloud-talk.groupAllowFrom`：群組允許清單（使用者 ID）。
- `channels.nextcloud-talk.rooms`：各聊天室設定與允許清單。
- `channels.nextcloud-talk.historyLimit`：群組歷史記錄限制（0 會停用）。
- `channels.nextcloud-talk.dmHistoryLimit`：DM 歷史記錄限制（0 會停用）。
- `channels.nextcloud-talk.dms`：各 DM 覆寫（historyLimit）。
- `channels.nextcloud-talk.textChunkLimit`：輸出文字區塊大小（字元）。
- `channels.nextcloud-talk.chunkMode`：`length`（預設）或 `newline`，在依長度分塊前先依空白行（段落邊界）分割。
- `channels.nextcloud-talk.blockStreaming`：停用此 channel 的區塊串流。
- `channels.nextcloud-talk.blockStreamingCoalesce`：區塊串流合併調校。
- `channels.nextcloud-talk.mediaMaxMb`：傳入媒體上限（MB）。
## 相關
- [Channels 概覽](/zh-TW/channels) — 所有支援的 channels
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [Channel 路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

260
docs/zh-TW/channels/nostr.md Normal file
View File

@ -0,0 +1,260 @@
---
read_when:
- 你想讓 OpenClaw 透過 Nostr 接收私訊
- 你正在設定去中心化訊息傳遞
summary: 透過 NIP-04 加密訊息的 Nostr 私訊通道
title: Nostr
x-i18n:
generated_at: "2026-04-30T02:48:23Z"
model: gpt-5.5
provider: openai
source_hash: 545d68077c9fe81d5fa5a17262d37e3688185a1fb12d67b8b1053b27b96c3c7f
source_path: channels/nostr.md
workflow: 16
---
**狀態：** 選用隨附 Plugin（設定前預設停用）。
Nostr 是用於社群網路的去中心化通訊協定。此頻道讓 OpenClaw 能透過 NIP-04 接收並回覆加密直接訊息（DM）。
## 隨附 Plugin
目前的 OpenClaw 版本將 Nostr 作為隨附 Plugin 發佈，因此一般封裝建置
不需要另外安裝。
### 較舊/自訂安裝
- Onboarding (`openclaw onboard`) 和 `openclaw channels add` 仍會從共用頻道目錄
顯示 Nostr。
- 如果你的建置排除了隨附的 Nostr，請在目前的 npm 套件發佈後安裝。
```bash
openclaw plugins install @openclaw/nostr
```
如果 npm 回報 OpenClaw 擁有的套件已棄用，請使用目前封裝的
OpenClaw 建置，或在較新的 npm 套件發佈前使用本機 checkout。
使用本機 checkout（開發工作流程）：
```bash
openclaw plugins install --link <path-to-local-nostr-plugin>
```
安裝或啟用 Plugin 後重新啟動 Gateway。
### 非互動式設定
```bash
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
```
使用 `--use-env` 將 `NOSTR_PRIVATE_KEY` 保留在環境中，而不是將金鑰儲存在設定裡。
## 快速設定
1. 產生 Nostr 金鑰組（如有需要）：
```bash
# Using nak
nak key generate
```
2. 加入設定：
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
},
},
}
```
3. 匯出金鑰：
```bash
export NOSTR_PRIVATE_KEY="nsec1..."
```
4. 重新啟動 Gateway。
## 設定參考
| 鍵 | 類型 | 預設值 | 說明 |
| ------------ | -------- | ------------------------------------------- | ------------------------------------- |
| `privateKey` | string | 必填 | `nsec` 或十六進位格式的私密金鑰 |
| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URL（WebSocket） |
| `dmPolicy` | string | `pairing` | DM 存取政策 |
| `allowFrom` | string[] | `[]` | 允許的傳送者 pubkey |
| `enabled` | boolean | `true` | 啟用/停用頻道 |
| `name` | string | - | 顯示名稱 |
| `profile` | object | - | NIP-01 個人檔案中繼資料 |
## 個人檔案中繼資料
個人檔案資料會作為 NIP-01 `kind:0` 事件發佈。你可以從 Control UI（Channels -> Nostr -> Profile）管理，或直接在設定中指定。
範例：
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
profile: {
name: "openclaw",
displayName: "OpenClaw",
about: "Personal assistant DM bot",
picture: "https://example.com/avatar.png",
banner: "https://example.com/banner.png",
website: "https://example.com",
nip05: "openclaw@example.com",
lud16: "openclaw@example.com",
},
},
},
}
```
注意事項：
- 個人檔案 URL 必須使用 `https://`。
- 從 relay 匯入會合併欄位並保留本機覆寫。
## 存取控制
### DM 政策
- **pairing**（預設）：未知傳送者會收到配對碼。
- **allowlist**：只有 `allowFrom` 中的 pubkey 可以傳送 DM。
- **open**：公開傳入 DM（需要 `allowFrom: ["*"]`）。
- **disabled**：忽略傳入 DM。
強制執行注意事項：
- 傳入事件簽章會在傳送者政策和 NIP-04 解密前驗證，因此偽造事件會提早遭到拒絕。
- 配對回覆會在不處理原始 DM 內文的情況下送出。
- 傳入 DM 會受到速率限制，過大的 payload 會在解密前被丟棄。
### 允許清單範例
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
dmPolicy: "allowlist",
allowFrom: ["npub1abc...", "npub1xyz..."],
},
},
}
```
## 金鑰格式
接受的格式：
- **私密金鑰：** `nsec...` 或 64 字元十六進位
- **Pubkeys (`allowFrom`)：** `npub...` 或十六進位
## Relays
預設值：`relay.damus.io` 和 `nos.lol`。
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"],
},
},
}
```
提示：
- 使用 2-3 個 relay 以提供備援。
- 避免使用太多 relay（延遲、重複）。
- 付費 relay 可以提升可靠性。
- 本機 relay 適合測試（`ws://localhost:7777`）。
## 通訊協定支援
| NIP | 狀態 | 說明 |
| ------ | ------ | --------------------------------- |
| NIP-01 | 已支援 | 基本事件格式 + 個人檔案中繼資料 |
| NIP-04 | 已支援 | 加密 DM（`kind:4`） |
| NIP-17 | 已規劃 | 禮物包裝 DM |
| NIP-44 | 已規劃 | 版本化加密 |
## 測試
### 本機 relay
```bash
# Start strfry
docker run -p 7777:7777 ghcr.io/hoytech/strfry
```
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
relays: ["ws://localhost:7777"],
},
},
}
```
### 手動測試
1. 從記錄中記下 bot pubkey（npub）。
2. 開啟 Nostr 用戶端（Damus、Amethyst 等）。
3. 對 bot pubkey 傳送 DM。
4. 驗證回應。
## 疑難排解
### 未收到訊息
- 驗證私密金鑰有效。
- 確認 relay URL 可連線，且使用 `wss://`（本機則使用 `ws://`）。
- 確認 `enabled` 不是 `false`。
- 檢查 Gateway 記錄中的 relay 連線錯誤。
### 未傳送回應
- 檢查 relay 是否接受寫入。
- 驗證對外連線能力。
- 留意 relay 速率限制。
### 重複回應
- 使用多個 relay 時屬於預期情況。
- 訊息會依事件 ID 去重；只有第一次傳遞會觸發回應。
## 安全性
- 絕不要提交私密金鑰。
- 使用環境變數儲存金鑰。
- 對正式環境 bot，請考慮使用 `allowlist`。
- 簽章會在傳送者政策前驗證，且傳送者政策會在解密前強制執行，因此偽造事件會提早遭到拒絕，未知傳送者也無法強制執行完整的密碼學工作。
## 限制（MVP）
- 僅支援直接訊息（不支援群組聊天）。
- 不支援媒體附件。
- 僅支援 NIP-04（已規劃 NIP-17 gift-wrap）。
## 相關
- [頻道概覽](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及門檻
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

179
docs/zh-TW/channels/pairing.md Normal file
View File

@ -0,0 +1,179 @@
---
read_when:
- 設定私訊存取控制
- 配對新的 iOS/Android 節点
- 檢視 OpenClaw 安全態勢
summary: 配對概覽：核准誰可以私訊你 + 哪些節點可以加入
title: 配對
x-i18n:
generated_at: "2026-04-30T02:48:36Z"
model: gpt-5.5
provider: openai
source_hash: cfdcaf831aedb122ea85200518b8dc1c6f42eff365444dee6c4b740050b1ce26
source_path: channels/pairing.md
workflow: 16
---
「配對」是 OpenClaw 明確的存取核准步驟。
它用於兩個地方：
1. **DM 配對**（誰被允許與機器人交談）
2. **Node 配對**（哪些裝置/Node 被允許加入 Gateway 網路）
安全性脈絡：[安全性](/zh-TW/gateway/security)
## 1) DM 配對（傳入聊天存取）
當某個頻道設定為 DM 政策 `pairing` 時，未知寄件者會取得一組短代碼，而且在你核准前，其訊息**不會被處理**。
預設 DM 政策記錄於：[安全性](/zh-TW/gateway/security)
只有在有效的 DM 允許清單包含 `"*"` 時，`dmPolicy: "open"` 才是公開的。
設定與驗證公開開放設定時需要這個萬用字元。若既有狀態包含
`open` 以及具體的 `allowFrom` 項目，執行階段仍只允許
那些寄件者，而配對儲存區核准不會擴大 `open` 存取權。
配對代碼：
- 8 個字元、大寫、不含易混淆字元（`0O1I`）。
- **1 小時後過期**。機器人只會在建立新請求時傳送配對訊息（約每位寄件者每小時一次）。
- 待處理的 DM 配對請求預設上限為**每個頻道 3 個**；額外請求會被忽略，直到其中一個過期或被核准。
### 核准寄件者
```bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```
如果尚未設定命令擁有者，核准 DM 配對代碼也會將
`commands.ownerAllowFrom` 啟動設定為已核准的寄件者，例如 `telegram:123456789`。
這會讓首次設定具備一位明確擁有者，可用於特權命令與 exec
核准提示。在擁有者存在後，後續配對核准只會授予 DM
存取權；它們不會新增更多擁有者。
支援的頻道：`bluebubbles`、`discord`、`feishu`、`googlechat`、`imessage`、`irc`、`line`、`matrix`、`mattermost`、`msteams`、`nextcloud-talk`、`nostr`、`openclaw-weixin`、`signal`、`slack`、`synology-chat`、`telegram`、`twitch`、`whatsapp`、`zalo`、`zalouser`。
### 狀態存放位置
存放於 `~/.openclaw/credentials/`：
- 待處理請求：`<channel>-pairing.json`
- 已核准允許清單儲存區：
- 預設帳號：`<channel>-allowFrom.json`
- 非預設帳號：`<channel>-<accountId>-allowFrom.json`
帳號範圍行為：
- 非預設帳號只會讀寫其範圍限定的允許清單檔案。
- 預設帳號使用頻道範圍、未限定範圍的允許清單檔案。
請將這些視為敏感資料（它們控管對你的助理的存取權）。
<Note>
配對允許清單儲存區用於 DM 存取。群組授權是分開的。
核准 DM 配對代碼不會自動允許該寄件者執行群組
命令或在群組中控制機器人。第一位擁有者啟動設定是
`commands.ownerAllowFrom` 中的獨立設定狀態，而群組聊天傳遞仍遵循
頻道的群組允許清單（例如 `groupAllowFrom`、`groups`，或依頻道而定的個別群組
或個別主題覆寫）。
</Note>
## 2) Node 裝置配對（iOS/Android/macOS/無頭 Node）
Node 會以具備 `role: node` 的**裝置**身分連線至 Gateway。Gateway
會建立必須核准的裝置配對請求。
### 透過 Telegram 配對（建議用於 iOS）
如果你使用 `device-pair` Plugin，可以完全透過 Telegram 完成首次裝置配對：
1. 在 Telegram 中傳訊息給你的機器人：`/pair`
2. 機器人會回覆兩則訊息：一則指示訊息，以及另一則獨立的**設定代碼**訊息（在 Telegram 中易於複製/貼上）。
3. 在手機上開啟 OpenClaw iOS app → Settings → Gateway。
4. 貼上設定代碼並連線。
5. 回到 Telegram：`/pair pending`（檢閱請求 ID、角色與範圍），然後核准。
設定代碼是 base64 編碼的 JSON 承載，其中包含：
- `url`：Gateway WebSocket URL（`ws://...` 或 `wss://...`）
- `bootstrapToken`：短效、單一裝置的啟動權杖，用於初始配對交握
該啟動權杖帶有內建的配對啟動設定檔：
- 主要交接的 `node` 權杖維持 `scopes: []`
- 任何交接的 `operator` 權杖都會限制在啟動允許清單內：
`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`
- 啟動範圍檢查以角色作為前綴，而不是單一扁平範圍池：
operator 範圍項目只會滿足 operator 請求，且非 operator 角色
仍必須在其自身角色前綴下請求範圍
- 後續權杖輪換/撤銷仍同時受限於裝置已核准的
角色合約，以及呼叫者工作階段的 operator 範圍
在設定代碼有效期間，請像密碼一樣看待它。
### 核准 Node 裝置
```bash
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
```
如果同一裝置以不同驗證詳細資料重試（例如不同的
角色/範圍/公開金鑰），先前的待處理請求會被取代，並建立新的
`requestId`。
<Note>
已配對的裝置不會被靜默授予更廣的存取權。如果它重新連線並要求更多範圍或更廣的角色，OpenClaw 會保持既有核准不變，並建立新的待處理升級請求。在核准前，請使用 `openclaw devices list` 比較目前已核准的存取權與新請求的存取權。
</Note>
### 選用的受信任 CIDR Node 自動核准
裝置配對預設仍為手動。對於嚴格控管的 Node 網路，
你可以使用明確 CIDR 或精確 IP 選擇加入首次 Node 自動核准：
```json5
{
gateway: {
nodes: {
pairing: {
autoApproveCidrs: ["192.168.1.0/24"],
},
},
},
}
```
這只適用於沒有請求
範圍的全新 `role: node` 配對請求。Operator、瀏覽器、Control UI 與 WebChat 用戶端仍需要手動
核准。角色、範圍、中繼資料與公開金鑰變更仍需要手動
核准。
### Node 配對狀態儲存
存放於 `~/.openclaw/devices/`：
- `pending.json`（短效；待處理請求會過期）
- `paired.json`（已配對裝置 + 權杖）
### 注意事項
- 舊版 `node.pair.*` API（CLI：`openclaw nodes pending|approve|reject|remove|rename`）是
獨立、由 Gateway 擁有的配對儲存區。WS Node 仍需要裝置配對。
- 配對記錄是已核准角色的持久真實來源。作用中的
裝置權杖仍受限於該已核准角色集合；位於已核准角色之外的零散權杖項目
不會建立新的存取權。
## 相關文件
- 安全性模型 + 提示注入：[安全性](/zh-TW/gateway/security)
- 安全更新（執行 doctor）：[更新](/zh-TW/install/updating)
- 頻道設定：
- Telegram：[Telegram](/zh-TW/channels/telegram)
- WhatsApp：[WhatsApp](/zh-TW/channels/whatsapp)
- Signal：[Signal](/zh-TW/channels/signal)
- BlueBubbles（iMessage）：[BlueBubbles](/zh-TW/channels/bluebubbles)
- iMessage（舊版）：[iMessage](/zh-TW/channels/imessage)
- Discord：[Discord](/zh-TW/channels/discord)
- Slack：[Slack](/zh-TW/channels/slack)

93
docs/zh-TW/channels/qa-channel.md Normal file
View File

@ -0,0 +1,93 @@
---
read_when:
- 您正在將合成 QA 傳輸接入本機或 CI 測試執行
- 你需要隨附的 qa-channel 設定介面
- 你正在反覆改進端對端品質保證自動化
summary: 用於決定性 OpenClaw QA 情境的合成 Slack 級頻道 Plugin
title: QA 頻道
x-i18n:
generated_at: "2026-04-30T02:48:54Z"
model: gpt-5.5
provider: openai
source_hash: e1de1f52da1a14c845cf2a536ddc6f36ab52ed6364f68d9ece32ce272e2a2f96
source_path: channels/qa-channel.md
workflow: 16
---
`qa-channel` 是一個隨附的合成訊息傳輸，用於自動化 OpenClaw QA。它不是生產用通道，而是用來演練實際傳輸所使用的相同通道 Plugin 邊界，同時保持狀態具備確定性且可完整檢查。
## 功能
- Slack 類型目標語法：
- `dm:<user>`
- `channel:<room>`
- `thread:<room>/<thread>`
- 以 HTTP 支援的合成匯流排，用於注入傳入訊息、擷取傳出逐字稿、建立討論串、反應、編輯、刪除，以及搜尋/讀取動作。
- 主機端自我檢查執行器，會將 Markdown 報告寫入 `.artifacts/qa-e2e/`。
## 設定
```json
{
"channels": {
"qa-channel": {
"baseUrl": "http://127.0.0.1:43123",
"botUserId": "openclaw",
"botDisplayName": "OpenClaw QA",
"allowFrom": ["*"],
"pollTimeoutMs": 1000
}
}
}
```
帳號鍵：
- `enabled` — 此帳號的主開關。
- `name` — 選用的顯示標籤。
- `baseUrl` — 合成匯流排 URL。
- `botUserId` — 目標語法中使用的 Matrix 樣式機器人使用者 ID。
- `botDisplayName` — 傳出訊息的顯示名稱。
- `pollTimeoutMs` — 長輪詢等待時間窗。介於 100 到 30000 之間的整數。
- `allowFrom` — 寄件者允許清單（使用者 ID 或 `"*"`）。
- `defaultTo` — 未提供目標時的後備目標。
- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` — 依動作設定的工具門控。
頂層的多帳號鍵：
- `accounts` — 以帳號 ID 作為鍵的具名逐帳號覆寫記錄。
- `defaultAccount` — 設定多個帳號時偏好的帳號 ID。
## 執行器
主機端自我檢查（在 `.artifacts/qa-e2e/` 下寫入 Markdown 報告）：
```bash
pnpm qa:e2e
```
這會透過 `qa-lab` 路由，啟動儲存庫內的 QA 匯流排，啟動隨附的 `qa-channel` 執行階段切片，並執行具確定性的自我檢查。
完整的儲存庫支援情境套件：
```bash
pnpm openclaw qa suite
```
針對 QA Gateway lane 平行執行情境。情境、設定檔與供應商模式請參閱 [QA 概觀](/zh-TW/concepts/qa-e2e-automation)。
Docker 支援的 QA 站台（Gateway + QA Lab 除錯器 UI 位於同一個堆疊中）：
```bash
pnpm qa:lab:up
```
建置 QA 站台，啟動 Docker 支援的 Gateway + QA Lab 堆疊，並列印 QA Lab URL。接著你可以挑選情境、選擇模型 lane、啟動個別執行，並即時觀看結果。QA Lab 除錯器與已出貨的 Control UI bundle 是分開的。
## 相關
- [QA 概觀](/zh-TW/concepts/qa-e2e-automation) — 整體堆疊、傳輸配接器、情境撰寫
- [Matrix QA](/zh-TW/concepts/qa-matrix) — 驅動真實通道的範例即時傳輸執行器
- [配對](/zh-TW/channels/pairing)
- [群組](/zh-TW/channels/groups)
- [通道概觀](/zh-TW/channels)

276
docs/zh-TW/channels/qqbot.md Normal file
View File

@ -0,0 +1,276 @@
---
read_when:
- 您想要將 OpenClaw 連接到 QQ
- 你需要設定 QQ Bot 憑證
- 你想要 QQ Bot 群組或私聊支援
summary: QQ Bot 設定、組態與使用方式
title: QQ 機器人
x-i18n:
generated_at: "2026-04-30T02:49:04Z"
model: gpt-5.5
provider: openai
source_hash: aefece6b05bb16d5c4f588bf7af4fd710b5f98aab0dbed8221490c46bf3f379c
source_path: channels/qqbot.md
workflow: 16
---
QQ Bot 透過官方 QQ Bot API（WebSocket gateway）連接到 OpenClaw。此 Plugin 支援 C2C 私聊、群組 @訊息，以及頻道訊息，並支援豐富媒體（圖片、語音、影片、檔案）。
狀態：內建 Plugin。支援私訊、群組聊天、頻道和媒體。不支援反應和討論串。
## 內建 Plugin
目前的 OpenClaw 版本內建 QQ Bot，因此一般封裝建置不需要額外執行 `openclaw plugins install` 步驟。
## 設定
1. 前往 [QQ Open Platform](https://q.qq.com/)，並用手機 QQ 掃描 QR code 以註冊 / 登入。
2. 點擊 **Create Bot** 建立新的 QQ bot。
3. 在 bot 的設定頁面找到 **AppID** 和 **AppSecret**，並複製它們。
> AppSecret 不會以明文儲存，如果你未儲存就離開頁面，
> 就必須重新產生新的 AppSecret。
4. 加入 channel：
```bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"
```
5. 重新啟動 Gateway。
互動式設定路徑：
```bash
openclaw channels add
openclaw configure --section channels
```
## 設定
最小設定：
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecret: "YOUR_APP_SECRET",
},
},
}
```
預設帳號環境變數：
- `QQBOT_APP_ID`
- `QQBOT_CLIENT_SECRET`
以檔案提供的 AppSecret：
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecretFile: "/path/to/qqbot-secret.txt",
},
},
}
```
注意事項：
- 環境變數 fallback 只適用於預設 QQ Bot 帳號。
- `openclaw channels add --channel qqbot --token-file ...` 只提供
AppSecret；AppID 必須已在 config 或 `QQBOT_APP_ID` 中設定。
- `clientSecret` 也接受 SecretRef 輸入，而不只是明文字串。
### 多帳號設定
在單一 OpenClaw 實例下執行多個 QQ bot：
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "111111111",
clientSecret: "secret-of-bot-1",
accounts: {
bot2: {
enabled: true,
appId: "222222222",
clientSecret: "secret-of-bot-2",
},
},
},
},
}
```
每個帳號會啟動自己的 WebSocket 連線，並維護獨立的 token 快取（以 `appId` 隔離）。
透過 CLI 加入第二個 bot：
```bash
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
```
### 群組聊天
QQ Bot 群組聊天支援使用 QQ 群組 OpenID，而不是顯示名稱。將 bot 加入群組，然後提及它，或設定群組讓它不需提及即可執行。
```json5
{
channels: {
qqbot: {
groupPolicy: "allowlist",
groupAllowFrom: ["member_openid"],
groups: {
"*": {
requireMention: true,
historyLimit: 50,
toolPolicy: "restricted",
},
GROUP_OPENID: {
name: "Release room",
requireMention: false,
ignoreOtherMentions: true,
historyLimit: 20,
prompt: "Keep replies short and operational.",
},
},
},
},
}
```
`groups["*"]` 會設定每個群組的預設值，而具體的
`groups.GROUP_OPENID` 項目會覆寫單一群組的這些預設值。群組設定包含：
- `requireMention`：bot 回覆前需要 @mention。預設值：`true`。
- `ignoreOtherMentions`：丟棄提及其他人但未提及 bot 的訊息。
- `historyLimit`：保留最近未提及 bot 的群組訊息，作為下一次被提及回合的情境。設為 `0` 可停用。
- `toolPolicy`：群組範圍工具的 `full`、`restricted` 或 `none`。
- `name`：用於日誌和群組情境的友善標籤。
- `prompt`：附加到 agent 情境的個別群組行為提示。
啟用模式為 `mention` 和 `always`。`requireMention: true` 對應到
`mention`；`requireMention: false` 對應到 `always`。若存在工作階段層級的啟用覆寫，則其優先於 config。
入站佇列以 peer 為單位。群組 peer 具有較大的佇列上限，佇列已滿時會讓人類訊息排在 bot 撰寫的聊天內容之前，並將一般群組訊息的突發串流合併成一個具署名的回合。斜線命令仍會逐一執行。
### 語音（STT / TTS）
STT 和 TTS 支援具有優先 fallback 的雙層設定：
| 設定 | Plugin 專屬 | Framework fallback |
| ------- | -------------------------------------------------------- | ----------------------------- |
| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` |
| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts` | `messages.tts` |
```json5
{
channels: {
qqbot: {
stt: {
provider: "your-provider",
model: "your-stt-model",
},
tts: {
provider: "your-provider",
model: "your-tts-model",
voice: "your-voice",
},
accounts: {
qq-main: {
tts: {
providers: {
openai: { voice: "shimmer" },
},
},
},
},
},
},
}
```
在任一項上設定 `enabled: false` 可停用。
帳號層級的 TTS 覆寫使用與 `messages.tts` 相同的形狀，並會深度合併到 channel/global TTS config 之上。
入站 QQ 語音附件會以音訊媒體中繼資料的形式公開給 agent，同時讓原始語音檔案不進入通用的 `MediaPaths`。當 TTS 已設定時，`[[audio_as_voice]]` 純文字回覆會合成 TTS 並傳送原生 QQ 語音訊息。
出站音訊上傳 / 轉碼行為也可使用
`channels.qqbot.audioFormatPolicy` 調整：
- `sttDirectFormats`
- `uploadDirectFormats`
- `transcodeEnabled`
## 目標格式
| 格式 | 說明 |
| -------------------------- | ------------------ |
| `qqbot:c2c:OPENID` | 私聊（C2C） |
| `qqbot:group:GROUP_OPENID` | 群組聊天 |
| `qqbot:channel:CHANNEL_ID` | 頻道 |
> 每個 bot 都有自己的使用者 OpenID 集合。Bot A 收到的 OpenID **不能**
> 用來透過 Bot B 傳送訊息。
## 斜線命令
在 AI 佇列前攔截的內建命令：
| 命令 | 說明 |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `/bot-ping` | 延遲測試 |
| `/bot-version` | 顯示 OpenClaw framework 版本 |
| `/bot-help` | 列出所有命令 |
| `/bot-upgrade` | 顯示 QQBot 升級指南連結 |
| `/bot-logs` | 將最近的 gateway 日誌匯出為檔案 |
| `/bot-approve` | 透過原生流程核准待處理的 QQ Bot 動作（例如確認 C2C 或群組上傳）。 |
在任何命令後加上 `?` 可查看用法說明（例如 `/bot-upgrade ?`）。
## 引擎架構
QQ Bot 以 Plugin 內自包含引擎的形式提供：
- 每個帳號都擁有以 `appId` 作為索引鍵的隔離資源堆疊（WebSocket 連線、API client、token 快取、媒體儲存根目錄）。帳號絕不共享入站 / 出站狀態。
- 多帳號 logger 會以擁有帳號標記日誌行，因此在同一個 gateway 下執行多個 bot 時，診斷資訊仍可分開檢視。
- 入站、出站和 gateway bridge 路徑共用 `~/.openclaw/media` 下的單一媒體 payload 根目錄，因此上傳、下載和轉碼快取會落在同一個受保護目錄下，而不是分散在各子系統樹狀結構中。
- 豐富媒體傳送會透過單一 `sendMedia` 路徑送往 C2C 和群組目標。超過大檔案閾值的本機檔案和緩衝區會使用 QQ 的分塊上傳 endpoint，而較小的 payload 則使用一次性媒體 API。
- 認證可作為標準 OpenClaw 認證快照的一部分備份和還原；引擎會在還原時重新附加每個帳號的資源堆疊，不需要新的 QR-code 配對。
## QR-code onboarding
除了手動貼上 `AppID:AppSecret`，引擎也支援用於將 QQ Bot 連結到 OpenClaw 的 QR-code onboarding 流程：
1. 執行 QQ Bot 設定路徑（例如 `openclaw channels add --channel qqbot`），並在提示時選擇 QR-code 流程。
2. 使用綁定目標 QQ Bot 的手機 app 掃描產生的 QR code。
3. 在手機上核准配對。OpenClaw 會將回傳的認證保存到正確帳號範圍下的 `credentials/`。
由 bot 本身產生的核准提示（例如 QQ Bot API 公開的「允許此動作？」流程）會呈現為原生 OpenClaw 提示，你可以用 `/bot-approve` 接受，而不必透過原始 QQ client 回覆。
## 疑難排解
- **Bot 回覆「gone to Mars」：** 認證未設定或 Gateway 未啟動。
- **沒有入站訊息：** 驗證 `appId` 和 `clientSecret` 是否正確，且
bot 已在 QQ Open Platform 上啟用。
- **重複自我回覆：** OpenClaw 會將 QQ 出站 ref index 記錄為
bot 撰寫，並忽略目前 `msgIdx` 符合同一 bot 帳號的入站事件。這會防止平台回音迴圈，同時仍允許使用者引用或回覆先前的 bot 訊息。
- **使用 `--token-file` 設定後仍顯示未設定：** `--token-file` 只會設定
AppSecret。你仍需要在 config 或 `QQBOT_APP_ID` 中設定 `appId`。
- **主動訊息未送達：** 如果使用者近期未互動，QQ 可能會攔截 bot 主動發起的訊息。
- **語音未轉錄：** 確認 STT 已設定，且 provider 可連線。
## 相關
- [配對](/zh-TW/channels/pairing)
- [群組](/zh-TW/channels/groups)
- [Channel 疑難排解](/zh-TW/channels/troubleshooting)

345
docs/zh-TW/channels/signal.md Normal file
View File

@ -0,0 +1,345 @@
---
read_when:
- 設定 Signal 支援
- Signal 傳送/接收偵錯
summary: 透過 signal-cli (JSON-RPC + SSE) 支援 Signal、設定路徑與號碼模型
title: Signal
x-i18n:
generated_at: "2026-04-30T02:48:59Z"
model: gpt-5.5
provider: openai
source_hash: d450454550a86cbf0e2b7231bb149f78275a756517db1f20d7a07e3d298febee
source_path: channels/signal.md
workflow: 16
---
狀態：外部 CLI 整合。Gateway 透過 HTTP JSON-RPC + SSE 與 `signal-cli` 通訊。
## 先決條件
- 你的伺服器上已安裝 OpenClaw（以下 Linux 流程已在 Ubuntu 24 測試）。
- Gateway 執行所在主機上可使用 `signal-cli`。
- 可接收一則驗證簡訊的電話號碼（用於簡訊註冊路徑）。
- 註冊期間可透過瀏覽器存取 Signal captcha（`signalcaptchas.org`）。
## 快速設定（初學者）
1. 為機器人使用**獨立的 Signal 號碼**（建議）。
2. 安裝 `signal-cli`（如果使用 JVM 建置版本，需安裝 Java）。
3. 選擇一種設定路徑：
- **路徑 A（QR 連結）：** `signal-cli link -n "OpenClaw"`，然後使用 Signal 掃描。
- **路徑 B（簡訊註冊）：** 使用 captcha + 簡訊驗證註冊專用號碼。
4. 設定 OpenClaw 並重新啟動 Gateway。
5. 傳送第一則私訊並核准配對（`openclaw pairing approve signal <CODE>`）。
最小設定：
```json5
{
channels: {
signal: {
enabled: true,
account: "+15551234567",
cliPath: "signal-cli",
dmPolicy: "pairing",
allowFrom: ["+15557654321"],
},
},
}
```
欄位參考：
| 欄位 | 說明 |
| ----------- | ------------------------------------------------- |
| `account` | E.164 格式的機器人電話號碼（`+15551234567`） |
| `cliPath` | `signal-cli` 的路徑（若在 `PATH` 上則為 `signal-cli`） |
| `dmPolicy` | 私訊存取政策（建議使用 `pairing`） |
| `allowFrom` | 允許傳送私訊的電話號碼或 `uuid:<id>` 值 |
## 它是什麼
- 透過 `signal-cli` 的 Signal 頻道（不是內嵌 libsignal）。
- 決定性路由：回覆一律回到 Signal。
- 私訊共用 agent 的主要工作階段；群組則隔離（`agent:<agentId>:signal:group:<groupId>`）。
## 設定寫入
預設情況下，Signal 允許寫入由 `/config set|unset` 觸發的設定更新（需要 `commands.config: true`）。
使用以下設定停用：
```json5
{
channels: { signal: { configWrites: false } },
}
```
## 號碼模型（重要）
- Gateway 會連線到一個 **Signal 裝置**（`signal-cli` 帳號）。
- 如果你在**自己的個人 Signal 帳號**上執行機器人，它會忽略你自己的訊息（迴圈保護）。
- 若要「我傳訊息給機器人，然後它回覆」，請使用**獨立的機器人號碼**。
## 設定路徑 A：連結現有 Signal 帳號（QR）
1. 安裝 `signal-cli`（JVM 或原生建置版本）。
2. 連結機器人帳號：
- `signal-cli link -n "OpenClaw"`，然後在 Signal 中掃描 QR。
3. 設定 Signal 並啟動 Gateway。
範例：
```json5
{
channels: {
signal: {
enabled: true,
account: "+15551234567",
cliPath: "signal-cli",
dmPolicy: "pairing",
allowFrom: ["+15557654321"],
},
},
}
```
多帳號支援：使用 `channels.signal.accounts` 搭配每個帳號的設定與選用的 `name`。共享模式請參閱 [`gateway/configuration`](/zh-TW/gateway/config-channels#multi-account-all-channels)。
## 設定路徑 B：註冊專用機器人號碼（簡訊，Linux）
當你想使用專用機器人號碼，而不是連結現有 Signal 應用程式帳號時，請使用此方式。
1. 取得可接收簡訊的號碼（或固定電話的語音驗證）。
- 使用專用機器人號碼，以避免帳號/工作階段衝突。
2. 在 Gateway 主機上安裝 `signal-cli`：
```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version
```
如果你使用 JVM 建置版本（`signal-cli-${VERSION}.tar.gz`），請先安裝 JRE 25+。
請保持 `signal-cli` 更新；上游說明指出，舊版本可能會因 Signal 伺服器 API 變更而故障。
3. 註冊並驗證號碼：
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register
```
如果需要 captcha：
1. 開啟 `https://signalcaptchas.org/registration/generate.html`。
2. 完成 captcha，從「Open Signal」複製 `signalcaptcha://...` 連結目標。
3. 盡可能從與瀏覽器工作階段相同的外部 IP 執行。
4. 立即再次執行註冊（captcha token 很快會過期）：
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
4. 設定 OpenClaw、重新啟動 Gateway、驗證頻道：
```bash
# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service
# Then verify:
openclaw doctor
openclaw channels status --probe
```
5. 配對你的私訊傳送者：
- 傳送任何訊息到機器人號碼。
- 在伺服器上核准代碼：`openclaw pairing approve signal <PAIRING_CODE>`。
- 將機器人號碼儲存為手機聯絡人，以避免顯示「未知聯絡人」。
<Warning>
使用 `signal-cli` 註冊電話號碼帳號，可能會讓該號碼的主要 Signal 應用程式工作階段失效。建議使用專用機器人號碼，或者如果你需要保留現有手機應用程式設定，請使用 QR 連結模式。
</Warning>
上游參考：
- `signal-cli` README：`https://github.com/AsamK/signal-cli`
- Captcha 流程：`https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha`
- 連結流程：`https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)`
## 外部 daemon 模式（httpUrl）
如果你想自行管理 `signal-cli`（JVM 冷啟動較慢、容器初始化，或共用 CPU），請另外執行 daemon，並讓 OpenClaw 指向它：
```json5
{
channels: {
signal: {
httpUrl: "http://127.0.0.1:8080",
autoStart: false,
},
},
}
```
這會略過 OpenClaw 內部的自動生成程序與啟動等待。若自動生成時啟動較慢，請設定 `channels.signal.startupTimeoutMs`。
## 存取控制（私訊 + 群組）
私訊：
- 預設：`channels.signal.dmPolicy = "pairing"`。
- 未知傳送者會收到配對代碼；訊息會在核准前被忽略（代碼 1 小時後過期）。
- 透過以下方式核准：
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
- 配對是 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`）。
## 運作方式（行為）
- `signal-cli` 以 daemon 形式執行；Gateway 透過 SSE 讀取事件。
- 傳入訊息會正規化為共享頻道 envelope。
- 回覆一律路由回相同號碼或群組。
## 媒體 + 限制
- 傳出文字會切分到 `channels.signal.textChunkLimit`（預設 4000）。
- 選用換行切分：設定 `channels.signal.chunkMode="newline"`，先依空白行（段落邊界）切分，再依長度切分。
- 支援附件（從 `signal-cli` 擷取 base64）。
- 當缺少 `contentType` 時，語音備忘附件會使用 `signal-cli` 檔名作為 MIME 後備，因此音訊轉錄仍可分類 AAC 語音備忘。
- 預設媒體上限：`channels.signal.mediaMaxMb`（預設 8）。
- 使用 `channels.signal.ignoreAttachments` 跳過下載媒體。
- 群組歷史情境使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），並回退到 `messages.groupChat.historyLimit`。設定為 `0` 可停用（預設 50）。
## 輸入中 + 已讀回條
- **輸入指示器**：OpenClaw 透過 `signal-cli sendTyping` 傳送輸入訊號，並在回覆執行期間持續刷新。
- **已讀回條**：當 `channels.signal.sendReadReceipts` 為 true 時，OpenClaw 會為允許的私訊轉發已讀回條。
- Signal-cli 不會公開群組的已讀回條。
## 反應（訊息工具）
- 使用 `message action=react` 搭配 `channel=signal`。
- 目標：傳送者 E.164 或 UUID（使用配對輸出中的 `uuid:<id>`；裸 UUID 也可）。
- `messageId` 是你要反應的訊息的 Signal 時間戳。
- 群組反應需要 `targetAuthor` 或 `targetAuthorUuid`。
範例：
```
message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅
```
設定：
- `channels.signal.actions.reactions`：啟用/停用反應動作（預設 true）。
- `channels.signal.reactionLevel`：`off | ack | minimal | extensive`。
- `off`/`ack` 會停用 agent 反應（訊息工具 `react` 會出錯）。
- `minimal`/`extensive` 會啟用 agent 反應並設定指引層級。
- 每個帳號的覆寫：`channels.signal.accounts.<id>.actions.reactions`、`channels.signal.accounts.<id>.reactionLevel`。
## 傳送目標（CLI/Cron）
- 私訊：`signal:+15551234567`（或純 E.164）。
- UUID 私訊：`uuid:<id>`（或裸 UUID）。
- 群組：`signal:group:<groupId>`。
- 使用者名稱：`username:<name>`（如果你的 Signal 帳號支援）。
## 疑難排解
先執行此階梯：
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
必要時再確認私訊配對狀態：
```bash
openclaw pairing list signal
```
常見失敗：
- Daemon 可連線但沒有回覆：確認帳號/daemon 設定（`httpUrl`、`account`）與接收模式。
- 私訊被忽略：傳送者正在等待配對核准。
- 群組訊息被忽略：群組傳送者/提及閘控阻擋了傳送。
- 編輯後出現設定驗證錯誤：執行 `openclaw doctor --fix`。
- 診斷中缺少 Signal：確認 `channels.signal.enabled: true`。
額外檢查：
```bash
openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20
```
分流流程：[/channels/troubleshooting](/zh-TW/channels/troubleshooting)。
## 安全性注意事項
- `signal-cli` 會將帳號金鑰儲存在本機（通常是 `~/.local/share/signal-cli/data/`）。
- 伺服器遷移或重建前，請備份 Signal 帳號狀態。
- 除非你明確想要更廣泛的私訊存取，否則請保留 `channels.signal.dmPolicy: "pairing"`。
- 簡訊驗證只在註冊或復原流程需要，但失去對號碼/帳號的控制可能會讓重新註冊變得複雜。
## 設定參考（Signal）
完整設定：[設定](/zh-TW/gateway/configuration)
提供者選項：
- `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）。
相關全域選項：
- `agents.list[].groupChat.mentionPatterns`（Signal 不支援原生提及）。
- `messages.groupChat.mentionPatterns`（全域後援）。
- `messages.responsePrefix`。
## 相關
- [頻道總覽](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

1040
docs/zh-TW/channels/slack.md Normal file
View File

File diff suppressed because it is too large Load Diff

189
docs/zh-TW/channels/synology-chat.md Normal file
View File

@ -0,0 +1,189 @@
---
read_when:
- 設定 Synology Chat 與 OpenClaw 搭配使用
- 偵錯 Synology Chat Webhook 路由
summary: Synology Chat Webhook 設定與 OpenClaw 配置
title: Synology Chat
x-i18n:
generated_at: "2026-04-30T02:49:19Z"
model: gpt-5.5
provider: openai
source_hash: c3d6d7a56bd15d29de38c6ae29ae496b491c2e75df5e0a0a15410b0fbdc55a00
source_path: channels/synology-chat.md
workflow: 16
---
狀態：使用 Synology Chat Webhook 的隨附 Plugin 直接訊息頻道。
此 Plugin 接受來自 Synology Chat outgoing Webhook 的傳入訊息，並透過 Synology Chat incoming Webhook 傳送回覆。
## 隨附 Plugin
Synology Chat 在目前的 OpenClaw 版本中以隨附 Plugin 形式提供，因此一般封裝建置不需要另外安裝。
如果你使用的是較舊的建置，或是不包含 Synology Chat 的自訂安裝，請手動安裝：
從本機 checkout 安裝：
```bash
openclaw plugins install ./path/to/local/synology-chat-plugin
```
詳細資訊：[Plugins](/zh-TW/tools/plugin)
## 快速設定
1. 確認 Synology Chat Plugin 可用。
- 目前封裝的 OpenClaw 版本已經隨附它。
- 較舊或自訂安裝可以使用上方指令，從原始碼 checkout 手動加入。
- `openclaw onboard` 現在會在與 `openclaw channels add` 相同的頻道設定清單中顯示 Synology Chat。
- 非互動式設定：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. 在 Synology Chat integrations 中：
- 建立 incoming Webhook 並複製其 URL。
- 使用你的秘密 token 建立 outgoing Webhook。
3. 將 outgoing Webhook URL 指向你的 OpenClaw Gateway：
- 預設為 `https://gateway-host/webhook/synology`。
- 或使用你的自訂 `channels.synology-chat.webhookPath`。
4. 在 OpenClaw 中完成設定。
- 引導式：`openclaw onboard`
- 直接：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
5. 重新啟動 Gateway，並向 Synology Chat bot 傳送 DM。
Webhook 驗證詳細資訊：
- OpenClaw 會先從 `body.token` 接受 outgoing Webhook token，接著是
`?token=...`，再來是 headers。
- 接受的 header 形式：
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- 空白或缺少的 token 會安全失敗。
最小設定：
```json5
{
channels: {
"synology-chat": {
enabled: true,
token: "synology-outgoing-token",
incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
webhookPath: "/webhook/synology",
dmPolicy: "allowlist",
allowedUserIds: ["123456"],
rateLimitPerMinute: 30,
allowInsecureSsl: false,
},
},
}
```
## 環境變數
對於預設帳號，你可以使用環境變數：
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
- `SYNOLOGY_NAS_HOST`
- `SYNOLOGY_ALLOWED_USER_IDS`（以逗號分隔）
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
設定值會覆寫環境變數。
`SYNOLOGY_CHAT_INCOMING_URL` 無法從工作區 `.env` 設定；請參閱[工作區 `.env` 檔案](/zh-TW/gateway/security)。
## DM 政策與存取控制
- `dmPolicy: "allowlist"` 是建議的預設值。
- `allowedUserIds` 接受 Synology 使用者 ID 的清單（或以逗號分隔的字串）。
- 在 `allowlist` 模式中，空的 `allowedUserIds` 清單會視為設定錯誤，Webhook 路由將不會啟動（若要允許全部，請使用 `dmPolicy: "open"` 搭配 `allowedUserIds: ["*"]`）。
- `dmPolicy: "open"` 只有在 `allowedUserIds` 包含 `"*"` 時才允許公開 DM；如果是限制性項目，只有相符的使用者可以聊天。
- `dmPolicy: "disabled"` 會封鎖 DM。
- 回覆收件者繫結預設維持在穩定的數字 `user_id`。`channels.synology-chat.dangerouslyAllowNameMatching: true` 是破窗相容模式，會重新啟用可變更的使用者名稱/暱稱查找以進行回覆傳送。
- 配對核准可搭配：
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
## 對外傳送
使用數字 Synology Chat 使用者 ID 作為目標。
範例：
```bash
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
```
支援透過 URL 型檔案傳送媒體。
對外檔案 URL 必須使用 `http` 或 `https`，而且私有或其他遭封鎖的網路目標會在 OpenClaw 將 URL 轉送至 NAS Webhook 前被拒絕。
## 多帳號
`channels.synology-chat.accounts` 下支援多個 Synology Chat 帳號。
每個帳號都可以覆寫 token、incoming URL、Webhook path、DM 政策與限制。
直接訊息工作階段會依帳號與使用者隔離，因此兩個不同 Synology 帳號上的相同數字 `user_id`
不會共用 transcript 狀態。
請為每個啟用的帳號提供不同的 `webhookPath`。OpenClaw 現在會拒絕重複的完全相同路徑，
並拒絕啟動在多帳號設定中只繼承共用 Webhook path 的具名帳號。
如果你刻意需要具名帳號的舊版繼承行為，請在該帳號或 `channels.synology-chat` 上設定
`dangerouslyAllowInheritedWebhookPath: true`，但重複的完全相同路徑仍會安全失敗並遭拒絕。請優先使用明確的各帳號路徑。
```json5
{
channels: {
"synology-chat": {
enabled: true,
accounts: {
default: {
token: "token-a",
incomingUrl: "https://nas-a.example.com/...token=...",
},
alerts: {
token: "token-b",
incomingUrl: "https://nas-b.example.com/...token=...",
webhookPath: "/webhook/synology-alerts",
dmPolicy: "allowlist",
allowedUserIds: ["987654"],
},
},
},
},
}
```
## 安全性注意事項
- 請保護 `token` 秘密，若外洩請輪換它。
- 除非你明確信任自簽的本機 NAS 憑證，否則請保持 `allowInsecureSsl: false`。
- 傳入 Webhook 請求會經過 token 驗證，並依傳送者套用速率限制。
- 無效 token 檢查使用固定時間秘密比較，並會安全失敗。
- 生產環境建議使用 `dmPolicy: "allowlist"`。
- 除非你明確需要舊版以使用者名稱為基礎的回覆傳送，否則請保持 `dangerouslyAllowNameMatching` 關閉。
- 除非你明確接受多帳號設定中的共用路徑路由風險，否則請保持 `dangerouslyAllowInheritedWebhookPath` 關閉。
## 疑難排解
- `Missing required fields (token, user_id, text)`：
- outgoing Webhook payload 缺少其中一個必填欄位
- 如果 Synology 在 headers 中傳送 token，請確認 Gateway/proxy 保留這些 headers
- `Invalid token`：
- outgoing Webhook secret 與 `channels.synology-chat.token` 不相符
- 請求打到錯誤的帳號/Webhook path
- reverse proxy 在請求到達 OpenClaw 前移除了 token header
- `Rate limit exceeded`：
- 來自同一來源的過多無效 token 嘗試可能會暫時鎖定該來源
- 已驗證的傳送者也有另一個依使用者套用的訊息速率限制
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].`：
- 已啟用 `dmPolicy="allowlist"`，但尚未設定任何使用者
- `User not authorized`：
- 傳送者的數字 `user_id` 不在 `allowedUserIds` 中
## 相關
- [頻道概覽](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

989
docs/zh-TW/channels/telegram.md Normal file
View File

@ -0,0 +1,989 @@
---
read_when:
- 開發 Telegram 功能或 Webhook
summary: Telegram 機器人支援狀態、功能與設定
title: Telegram
x-i18n:
generated_at: "2026-04-30T02:49:17Z"
model: gpt-5.5
provider: openai
source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7
source_path: channels/telegram.md
workflow: 16
---
Production-ready for bot DMs and groups via grammY. Long polling is the default mode; webhook mode is optional.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/zh-TW/channels/pairing">
Default DM policy for Telegram is pairing.
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/zh-TW/channels/troubleshooting">
Cross-channel diagnostics and repair playbooks.
</Card>
<Card title="Gateway configuration" icon="settings" href="/zh-TW/gateway/configuration">
Full channel config patterns and examples.
</Card>
</CardGroup>
## Quick setup
<Steps>
<Step title="Create the bot token in BotFather">
Open Telegram and chat with **@BotFather** (confirm the handle is exactly `@BotFather`).
Run `/newbot`, follow prompts, and save the token.
</Step>
<Step title="Configure token and DM policy">
```json5
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
groups: { "*": { requireMention: true } },
},
},
}
```
Env fallback: `TELEGRAM_BOT_TOKEN=...` (default account only).
Telegram does **not** use `openclaw channels login telegram`; configure token in config/env, then start gateway.
</Step>
<Step title="Start gateway and approve first DM">
```bash
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```
Pairing codes expire after 1 hour.
</Step>
<Step title="Add the bot to a group">
Add the bot to your group, then set `channels.telegram.groups` and `groupPolicy` to match your access model.
</Step>
</Steps>
<Note>
Token resolution order is account-aware. In practice, config values win over env fallback, and `TELEGRAM_BOT_TOKEN` only applies to the default account.
</Note>
## Telegram side settings
<AccordionGroup>
<Accordion title="Privacy mode and group visibility">
Telegram bots default to **Privacy Mode**, which limits what group messages they receive.
If the bot must see all group messages, either:
- disable privacy mode via `/setprivacy`, or
- make the bot a group admin.
When toggling privacy mode, remove + re-add the bot in each group so Telegram applies the change.
</Accordion>
<Accordion title="Group permissions">
Admin status is controlled in Telegram group settings.
Admin bots receive all group messages, which is useful for always-on group behavior.
</Accordion>
<Accordion title="Helpful BotFather toggles">
- `/setjoingroups` to allow/deny group adds
- `/setprivacy` for group visibility behavior
</Accordion>
</AccordionGroup>
## Access control and activation
<Tabs>
<Tab title="DM policy">
`channels.telegram.dmPolicy` controls direct message access:
- `pairing` (default)
- `allowlist` (requires at least one sender ID in `allowFrom`)
- `open` (requires `allowFrom` to include `"*"`)
- `disabled`
`dmPolicy: "open"` with `allowFrom: ["*"]` lets any Telegram account that finds or guesses the bot username command the bot. Use it only for intentionally public bots with tightly restricted tools; one-owner bots should use `allowlist` with numeric user IDs.
`channels.telegram.allowFrom` accepts numeric Telegram user IDs. `telegram:` / `tg:` prefixes are accepted and normalized.
In multi-account configs, a restrictive top-level `channels.telegram.allowFrom` is treated as a safety boundary: account-level `allowFrom: ["*"]` entries do not make that account public unless the effective account allowlist still contains an explicit wildcard after merging.
`dmPolicy: "allowlist"` with empty `allowFrom` blocks all DMs and is rejected by config validation.
Setup asks for numeric user IDs only.
If you upgraded and your config contains `@username` allowlist entries, run `openclaw doctor --fix` to resolve them (best-effort; requires a Telegram bot token).
If you previously relied on pairing-store allowlist files, `openclaw doctor --fix` can recover entries into `channels.telegram.allowFrom` in allowlist flows (for example when `dmPolicy: "allowlist"` has no explicit IDs yet).
For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs to keep access policy durable in config (instead of depending on previous pairing approvals).
Common confusion: DM pairing approval does not mean "this sender is authorized everywhere".
Pairing grants DM access. If no command owner exists yet, the first approved pairing also sets `commands.ownerAllowFrom` so owner-only commands and exec approvals have an explicit operator account.
Group sender authorization still comes from explicit config allowlists.
If you want "I am authorized once and both DMs and group commands work", put your numeric Telegram user ID in `channels.telegram.allowFrom`; for owner-only commands, make sure `commands.ownerAllowFrom` contains `telegram:<your user id>`.
### Finding your Telegram user ID
Safer (no third-party bot):
1. DM your bot.
2. Run `openclaw logs --follow`.
3. Read `from.id`.
Official Bot API method:
```bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
Third-party method (less private): `@userinfobot` or `@getidsbot`.
</Tab>
<Tab title="Group policy and allowlists">
Two controls apply together:
1. **Which groups are allowed** (`channels.telegram.groups`)
- no `groups` config:
- with `groupPolicy: "open"`: any group can pass group-ID checks
- with `groupPolicy: "allowlist"` (default): groups are blocked until you add `groups` entries (or `"*"`)
- `groups` configured: acts as allowlist (explicit IDs or `"*"`)
2. **Which senders are allowed in groups** (`channels.telegram.groupPolicy`)
- `open`
- `allowlist` (default)
- `disabled`
`groupAllowFrom` is used for group sender filtering. If not set, Telegram falls back to `allowFrom`.
`groupAllowFrom` entries should be numeric Telegram user IDs (`telegram:` / `tg:` prefixes are normalized).
Do not put Telegram group or supergroup chat IDs in `groupAllowFrom`. Negative chat IDs belong under `channels.telegram.groups`.
Non-numeric entries are ignored for sender authorization.
Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals.
Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`.
If `groupAllowFrom` is unset, Telegram falls back to config `allowFrom`, not the pairing store.
Practical pattern for one-owner bots: set your user ID in `channels.telegram.allowFrom`, leave `groupAllowFrom` unset, and allow the target groups under `channels.telegram.groups`.
Runtime note: if `channels.telegram` is completely missing, runtime defaults to fail-closed `groupPolicy="allowlist"` unless `channels.defaults.groupPolicy` is explicitly set.
Example: allow any member in one specific group:
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": {
groupPolicy: "open",
requireMention: false,
},
},
},
},
}
```
Example: allow only specific users inside one specific group:
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": {
requireMention: true,
allowFrom: ["8734062810", "745123456"],
},
},
},
},
}
```
<Warning>
Common mistake: `groupAllowFrom` is not a Telegram group allowlist.
- Put negative Telegram group or supergroup chat IDs like `-1001234567890` under `channels.telegram.groups`.
- Put Telegram user IDs like `8734062810` under `groupAllowFrom` when you want to limit which people inside an allowed group can trigger the bot.
- Use `groupAllowFrom: ["*"]` only when you want any member of an allowed group to be able to talk to the bot.
</Warning>
</Tab>
<Tab title="Mention behavior">
Group replies require mention by default.
Mention can come from:
- native `@botusername` mention, or
- mention patterns in:
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
Session-level command toggles:
- `/activation always`
- `/activation mention`
These update session state only. Use config for persistence.
Persistent config example:
```json5
{
channels: {
telegram: {
groups: {
"*": { requireMention: false },
},
},
},
}
```
Getting the group chat ID:
- forward a group message to `@userinfobot` / `@getidsbot`
- or read `chat.id` from `openclaw logs --follow`
- or inspect Bot API `getUpdates`
</Tab>
</Tabs>
## Runtime behavior
- Telegram is owned by the gateway process.
- Routing is deterministic: Telegram inbound replies back to Telegram (the model does not pick channels).
- Inbound messages normalize into the shared channel envelope with reply metadata and media placeholders.
- Group sessions are isolated by group ID. Forum topics append `:topic:<threadId>` to keep topics isolated.
- DM messages can carry `message_thread_id`; OpenClaw routes them with thread-aware session keys and preserves thread ID for replies.
- Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses `agents.defaults.maxConcurrent`.
- Long polling is guarded inside each gateway process so only one active poller can use a bot token at a time. If you still see `getUpdates` 409 conflicts, another OpenClaw gateway, script, or external poller is likely using the same token.
- Long-polling watchdog restarts trigger after 120 seconds without completed `getUpdates` liveness by default. Increase `channels.telegram.pollingStallThresholdMs` only if your deployment still sees false polling-stall restarts during long-running work. The value is in milliseconds and is allowed from `30000` to `600000`; per-account overrides are supported.
- Telegram Bot API has no read-receipt support (`sendReadReceipts` does not apply).
## Feature reference
<AccordionGroup>
<Accordion title="Live stream preview (message edits)">
OpenClaw can stream partial replies in real time:
- direct chats: preview message + `editMessageText`
- groups/topics: preview message + `editMessageText`
Requirement:
- `channels.telegram.streaming` is `off | partial | block | progress` (default: `partial`)
- `progress` maps to `partial` on Telegram (compat with cross-channel naming)
- `streaming.preview.toolProgress` controls whether tool/progress updates reuse the same edited preview message (default: `true` when preview streaming is active)
- legacy `channels.telegram.streamMode` and boolean `streaming` values are detected; run `openclaw doctor --fix` to migrate them to `channels.telegram.streaming.mode`
Tool-progress preview updates are the short "Working..." lines shown while tools run, for example command execution, file reads, planning updates, or patch summaries. Telegram keeps these enabled by default to match released OpenClaw behavior from `v2026.4.22` and later. To keep the edited preview for answer text but hide tool-progress lines, set:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "partial",
"preview": {
"toolProgress": false
}
}
}
}
}
```
Use `streaming.mode: "off"` only when you want final-only delivery: Telegram preview edits are disabled and generic tool/progress chatter is suppressed instead of being sent as standalone "Working..." messages. Approval prompts, media payloads, and errors still route through normal final delivery. Use `streaming.preview.toolProgress: false` when you only want to keep answer preview edits while hiding the tool-progress status lines.
For text-only replies:
- 簡短的私訊/群組/主題預覽：OpenClaw 會保留相同的預覽訊息，並在原處執行最終編輯
- 超過約一分鐘的預覽：OpenClaw 會將完成的回覆作為新的最終訊息送出，然後清理預覽，因此 Telegram 可見的時間戳會反映完成時間，而不是預覽建立時間
對於複雜回覆（例如媒體 payload），OpenClaw 會退回一般最終傳遞，然後清理預覽訊息。
預覽串流與區塊串流是分開的。當 Telegram 明確啟用區塊串流時，OpenClaw 會略過預覽串流，以避免雙重串流。
如果原生草稿傳輸不可用/遭拒，OpenClaw 會自動退回 `sendMessage` + `editMessageText`。
僅限 Telegram 的 reasoning 串流：
- `/reasoning stream` 會在生成時將 reasoning 傳送到即時預覽
- 最終答案會在不含 reasoning 文字的情況下送出
</Accordion>
<Accordion title="格式化與 HTML 退回">
對外文字使用 Telegram `parse_mode: "HTML"`。
- 類似 Markdown 的文字會轉譯為 Telegram 安全的 HTML。
- 原始模型 HTML 會被逸出，以減少 Telegram 解析失敗。
- 如果 Telegram 拒絕已解析的 HTML，OpenClaw 會以純文字重試。
連結預覽預設啟用，可透過 `channels.telegram.linkPreview: false` 停用。
</Accordion>
<Accordion title="原生命令與自訂命令">
Telegram 命令選單註冊會在啟動時透過 `setMyCommands` 處理。
原生命令預設值：
- `commands.native: "auto"` 會為 Telegram 啟用原生命令
新增自訂命令選單項目：
```json5
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Git backup" },
{ command: "generate", description: "Create an image" },
],
},
},
}
```
規則：
- 名稱會正規化（移除開頭的 `/`、轉為小寫）
- 有效模式：`a-z`、`0-9`、`_`，長度 `1..32`
- 自訂命令不能覆寫原生命令
- 衝突/重複項目會被略過並記錄
注意：
- 自訂命令只是選單項目；它們不會自動實作行為
- plugin/skill 命令即使未顯示在 Telegram 選單中，輸入時仍可運作
如果停用原生命令，內建命令會被移除。Custom/plugin 命令若已設定，仍可能註冊。
常見設定失敗：
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 選單在修剪後仍然超出限制；請減少 plugin/skill/custom 命令，或停用 `channels.telegram.commands.native`。
- 當直接使用 Bot API curl 命令可運作，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 因 `404: Not Found` 失敗時，可能表示 `channels.telegram.apiRoot` 被設定為完整的 `/bot<TOKEN>` 端點。`apiRoot` 必須只包含 Bot API 根路徑，而 `openclaw doctor --fix` 會移除意外尾隨的 `/bot<TOKEN>`。
- `getMe returned 401` 表示 Telegram 拒絕已設定的 bot token。請使用目前的 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 會在輪詢前停止，因此這不會被回報為 Webhook 清理失敗。
- `setMyCommands failed` 搭配網路/fetch 錯誤，通常表示對 `api.telegram.org` 的對外 DNS/HTTPS 被封鎖。
### 裝置配對命令（`device-pair` plugin）
安裝 `device-pair` plugin 時：
1. `/pair` 產生設定程式碼
2. 將程式碼貼到 iOS app
3. `/pair pending` 列出待處理請求（包含角色/scopes）
4. 核准請求：
- `/pair approve <requestId>` 用於明確核准
- `/pair approve` 用於只有一個待處理請求時
- `/pair approve latest` 用於最近一筆
設定程式碼帶有短效 bootstrap token。內建 bootstrap 交接會將主要 node token 維持在 `scopes: []`；任何已交接的 operator token 都會限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap scope 檢查會加上角色前綴，因此該 operator allowlist 只滿足 operator 請求；非 operator 角色仍需要其自身角色前綴下的 scopes。
如果裝置以變更後的驗證詳細資料重試（例如角色/scopes/公開金鑰），先前的待處理請求會被取代，新請求會使用不同的 `requestId`。核准前請重新執行 `/pair pending`。
更多詳細資訊：[配對](/zh-TW/channels/pairing#pair-via-telegram-recommended-for-ios)。
</Accordion>
<Accordion title="行內按鈕">
設定行內鍵盤範圍：
```json5
{
channels: {
telegram: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
}
```
每個帳號覆寫：
```json5
{
channels: {
telegram: {
accounts: {
main: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
},
},
}
```
範圍：
- `off`
- `dm`
- `group`
- `all`
- `allowlist`（預設）
舊版 `capabilities: ["inlineButtons"]` 會對應到 `inlineButtons: "all"`。
訊息動作範例：
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
message: "Choose an option:",
buttons: [
[
{ text: "Yes", callback_data: "yes" },
{ text: "No", callback_data: "no" },
],
[{ text: "Cancel", callback_data: "cancel" }],
],
}
```
Callback 點擊會作為文字傳給 agent：
`callback_data: <value>`
</Accordion>
<Accordion title="供 agent 與自動化使用的 Telegram 訊息動作">
Telegram 工具動作包含：
- `sendMessage`（`to`、`content`、選用 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
- `react`（`chatId`、`messageId`、`emoji`）
- `deleteMessage`（`chatId`、`messageId`）
- `editMessage`（`chatId`、`messageId`、`content`）
- `createForumTopic`（`chatId`、`name`、選用 `iconColor`、`iconCustomEmojiId`）
頻道訊息動作提供符合人體工學的別名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
Gate 控制：
- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker`（預設：停用）
注意：`edit` 和 `topic-create` 目前預設啟用，且沒有個別的 `channels.telegram.actions.*` 切換。
Runtime 傳送會使用作用中的 config/secrets 快照（啟動/重新載入），因此動作路徑不會在每次傳送時執行臨時 SecretRef 重新解析。
反應移除語意：[/tools/reactions](/zh-TW/tools/reactions)
</Accordion>
<Accordion title="回覆 threading 標籤">
Telegram 支援在生成輸出中使用明確的回覆 threading 標籤：
- `[[reply_to_current]]` 回覆觸發訊息
- `[[reply_to:<id>]]` 回覆特定 Telegram 訊息 ID
`channels.telegram.replyToMode` 控制處理方式：
- `off`（預設）
- `first`
- `all`
啟用回覆 threading 且原始 Telegram 文字或 caption 可用時，OpenClaw 會自動包含原生 Telegram 引言摘錄。Telegram 將原生引言文字限制為 1024 個 UTF-16 code units，因此較長訊息會從開頭開始引用，若 Telegram 拒絕引言，則退回純回覆。
注意：`off` 會停用隱含回覆 threading。明確的 `[[reply_to_*]]` 標籤仍會被遵循。
</Accordion>
<Accordion title="論壇主題與 thread 行為">
論壇 supergroups：
- 主題 session keys 會附加 `:topic:<threadId>`
- 回覆與 typing 會以主題 thread 為目標
- 主題 config 路徑：
`channels.telegram.groups.<chatId>.topics.<threadId>`
一般主題（`threadId=1`）特殊情況：
- 訊息傳送會省略 `message_thread_id`（Telegram 會拒絕 `sendMessage(...thread_id=1)`）
- typing 動作仍會包含 `message_thread_id`
主題繼承：主題項目會繼承群組設定，除非已覆寫（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
`agentId` 只屬於主題，不會從群組預設值繼承。
**每個主題的 agent 路由**：每個主題都可以透過在主題 config 中設定 `agentId` 路由到不同的 agent。這讓每個主題都有自己的隔離工作區、記憶體和 session。範例：
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": {
topics: {
"1": { agentId: "main" }, // General topic → main agent
"3": { agentId: "zu" }, // Dev topic → zu agent
"5": { agentId: "coder" } // Code review → coder agent
}
}
}
}
}
}
```
接著每個主題都有自己的 session key：`agent:zu:telegram:group:-1001234567890:topic:3`
**持久 ACP 主題綁定**：論壇主題可透過頂層 typed ACP bindings（`bindings[]` 搭配 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及類似 `-1001234567890:topic:42` 的主題限定 id）釘選 ACP harness sessions。目前範圍限於 groups/supergroups 中的論壇主題。請參閱 [ACP Agents](/zh-TW/tools/acp-agents)。
**從聊天室產生 thread-bound ACP**：`/acp spawn <agent> --thread here|auto` 會將目前主題綁定到新的 ACP session；後續訊息會直接路由至該處。OpenClaw 會將 spawn 確認釘選在主題內。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
Template context 會公開 `MessageThreadId` 和 `IsForum`。帶有 `message_thread_id` 的私訊聊天室會保留私訊路由，但使用 thread-aware session keys。
</Accordion>
<Accordion title="音訊、影片與貼圖">
### 音訊訊息
Telegram 會區分語音備忘 vs 音訊檔案。
- 預設：音訊檔案行為
- 在 agent 回覆中加入標籤 `[[audio_as_voice]]` 以強制作為語音備忘傳送
- 內送語音備忘逐字稿會在 agent context 中被標示為機器生成、
不受信任的文字；提及偵測仍會使用原始
逐字稿，因此受提及 gate 控制的語音訊息仍可運作。
訊息動作範例：
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
media: "https://example.com/voice.ogg",
asVoice: true,
}
```
### 影片訊息
Telegram 會區分影片檔案 vs 影片備忘。
訊息動作範例：
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
media: "https://example.com/video.mp4",
asVideoNote: true,
}
```
影片備忘不支援 caption；提供的訊息文字會另行傳送。
### 貼圖
內送貼圖處理：
- 靜態 WEBP：下載並處理（placeholder `<media:sticker>`）
- 動畫 TGS：略過
- 影片 WEBM：略過
貼圖 context 欄位：
- `Sticker.emoji`
- `Sticker.setName`
- `Sticker.fileId`
- `Sticker.fileUniqueId`
- `Sticker.cachedDescription`
貼圖快取檔案：
- `~/.openclaw/telegram/sticker-cache.json`
貼圖會被描述一次（可行時）並快取，以減少重複的視覺呼叫。
啟用貼圖動作：
```json5
{
channels: {
telegram: {
actions: {
sticker: true,
},
},
},
}
```
傳送貼圖動作：
```json5
{
action: "sticker",
channel: "telegram",
to: "123456789",
fileId: "CAACAgIAAxkBAAI...",
}
```
搜尋快取的貼圖：
```json5
{
action: "sticker-search",
channel: "telegram",
query: "cat waving",
limit: 5,
}
```
</Accordion>
<Accordion title="反應通知">
Telegram 反應會以 `message_reaction` updates 抵達（與訊息 payloads 分開）。
啟用後，OpenClaw 會將如下系統事件排入佇列：
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
Config:
- `channels.telegram.reactionNotifications`: `off | own | all`（預設：`own`）
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（預設：`minimal`）
備註：
- `own` 表示僅限使用者對機器人傳送訊息的反應（透過已傳送訊息快取盡力處理）。
- 反應事件仍會遵守 Telegram 存取控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授權的傳送者會被丟棄。
- Telegram 不會在反應更新中提供對話串 ID。
- 非論壇群組會路由到群組聊天工作階段
- 論壇群組會路由到群組的一般主題工作階段（`:topic:1`），而不是確切的原始主題
輪詢/Webhook 的 `allowed_updates` 會自動包含 `message_reaction`。
</Accordion>
<Accordion title="Ack 反應">
`ackReaction` 會在 OpenClaw 處理傳入訊息時傳送確認表情符號。
解析順序：
- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- agent 身分表情符號後援（`agents.list[].identity.emoji`，否則為「👀」）
備註：
- Telegram 預期使用 unicode 表情符號（例如「👀」）。
- 使用 `""` 可停用某個頻道或帳號的反應。
</Accordion>
<Accordion title="來自 Telegram 事件和命令的設定寫入">
頻道設定寫入預設啟用（`configWrites !== false`）。
Telegram 觸發的寫入包含：
- 群組遷移事件（`migrate_to_chat_id`），用於更新 `channels.telegram.groups`
- `/config set` 和 `/config unset`（需要啟用命令）
停用：
```json5
{
channels: {
telegram: {
configWrites: false,
},
},
}
```
</Accordion>
<Accordion title="長輪詢與 Webhook">
預設為長輪詢。若要使用 Webhook 模式，請設定 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可選擇設定 `webhookPath`、`webhookHost`、`webhookPort`（預設為 `/telegram-webhook`、`127.0.0.1`、`8787`）。
本機監聽器會繫結到 `127.0.0.1:8787`。若要使用公開入口，請在本機連接埠前方放置反向代理，或有意地設定 `webhookHost: "0.0.0.0"`。
Webhook 模式會先驗證請求防護、Telegram 密鑰權杖和 JSON 本文，才向 Telegram 回傳 `200`。
OpenClaw 接著會透過與長輪詢相同的每聊天/每主題機器人通道非同步處理更新，因此緩慢的 agent 回合不會卡住 Telegram 的傳遞 ACK。
</Accordion>
<Accordion title="限制、重試與 CLI 目標">
- `channels.telegram.textChunkLimit` 預設為 4000。
- `channels.telegram.chunkMode="newline"` 會在依長度分割前優先使用段落邊界（空白行）。
- `channels.telegram.mediaMaxMb`（預設 100）會限制傳入和傳出的 Telegram 媒體大小。
- `channels.telegram.timeoutSeconds` 會覆寫 Telegram API 用戶端逾時（若未設定，則套用 grammY 預設值）。
- `channels.telegram.pollingStallThresholdMs` 預設為 `120000`；只有在輪詢停滯重新啟動出現誤判時，才在 `30000` 到 `600000` 之間調整。
- 群組上下文歷史記錄使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（預設 50）；`0` 會停用。
- 回覆/引用/轉寄的補充上下文目前會依收到的內容傳遞。
- Telegram 允許清單主要管控誰可以觸發 agent，而不是完整的補充上下文遮蔽邊界。
- 私訊歷史記錄控制：
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- `channels.telegram.retry` 設定會套用到 Telegram 傳送輔助工具（CLI/工具/動作），用於可復原的傳出 API 錯誤。傳入最終回覆傳遞也會針對 Telegram 預連線失敗使用有界限的安全傳送重試，但不會重試可能造成可見訊息重複的不明確傳送後網路封包。
CLI 傳送目標可以是數值聊天 ID 或使用者名稱：
```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
```
Telegram 投票使用 `openclaw message poll`，並支援論壇主題：
```bash
openclaw message poll --channel telegram --target 123456789 \
--poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
--poll-duration-seconds 300 --poll-public
```
僅限 Telegram 的投票旗標：
- `--poll-duration-seconds`（5-600）
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` 用於論壇主題（或使用 `:topic:` 目標）
Telegram 傳送也支援：
- 當 `channels.telegram.capabilities.inlineButtons` 允許時，搭配 `buttons` 區塊的 `--presentation` 可用於行內鍵盤
- `--pin` 或 `--delivery '{"pin":true}'` 可在機器人能於該聊天中釘選時要求釘選傳遞
- `--force-document` 會將傳出圖片和 GIF 作為文件傳送，而不是使用壓縮相片或動畫媒體上傳
動作管控：
- `channels.telegram.actions.sendMessage=false` 會停用傳出的 Telegram 訊息，包括投票
- `channels.telegram.actions.poll=false` 會停用 Telegram 投票建立，同時保留一般傳送啟用
</Accordion>
<Accordion title="Telegram 中的執行核准">
Telegram 支援在核准者私訊中進行執行核准，也可以選擇在原始聊天或主題中發布提示。核准者必須是數值 Telegram 使用者 ID。
設定路徑：
- `channels.telegram.execApprovals.enabled`（至少可解析一位核准者時會自動啟用）
- `channels.telegram.execApprovals.approvers`（後援為 `commands.ownerAllowFrom` 中的數值擁有者 ID）
- `channels.telegram.execApprovals.target`: `dm`（預設）| `channel` | `both`
- `agentFilter`, `sessionFilter`
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制誰可以和機器人對話，以及機器人將一般回覆傳送到哪裡。它們不會讓某人成為執行核准者。當尚未存在命令擁有者時，第一個核准的私訊配對會啟動 `commands.ownerAllowFrom`，因此單一擁有者設定仍可運作，而不必在 `execApprovals.approvers` 下重複 ID。
頻道傳遞會在聊天中顯示命令文字；只有在受信任的群組/主題中才啟用 `channel` 或 `both`。當提示出現在論壇主題中時，OpenClaw 會為核准提示和後續訊息保留該主題。執行核准預設會在 30 分鐘後過期。
行內核准按鈕也需要 `channels.telegram.capabilities.inlineButtons` 允許目標介面（`dm`、`group` 或 `all`）。以 `plugin:` 為前綴的核准 ID 會透過 Plugin 核准解析；其他 ID 會先透過執行核准解析。
請參閱[執行核准](/zh-TW/tools/exec-approvals)。
</Accordion>
</AccordionGroup>
## 錯誤回覆控制
當 agent 遇到傳遞或提供者錯誤時，Telegram 可以回覆錯誤文字，或隱藏錯誤。這個行為由兩個設定鍵控制：
| 鍵 | 值 | 預設值 | 說明 |
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 會向聊天傳送友善的錯誤訊息。`silent` 會完全隱藏錯誤回覆。 |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 對同一聊天傳送錯誤回覆之間的最短時間。可防止中斷期間出現錯誤垃圾訊息。 |
支援每帳號、每群組和每主題覆寫（繼承方式與其他 Telegram 設定鍵相同）。
```json5
{
channels: {
telegram: {
errorPolicy: "reply",
errorCooldownMs: 120000,
groups: {
"-1001234567890": {
errorPolicy: "silent", // suppress errors in this group
},
},
},
},
}
```
## 疑難排解
<AccordionGroup>
<Accordion title="機器人未回應非提及群組訊息">
- 如果 `requireMention=false`，Telegram 隱私模式必須允許完整可見性。
- BotFather：`/setprivacy` -> Disable
- 然後移除機器人並重新加入群組
- 當設定預期未提及的群組訊息時，`openclaw channels status` 會發出警告。
- `openclaw channels status --probe` 可以檢查明確的數值群組 ID；萬用字元 `"*"` 無法探測成員資格。
- 快速工作階段測試：`/activation always`。
</Accordion>
<Accordion title="機器人完全看不到群組訊息">
- 當 `channels.telegram.groups` 存在時，群組必須列在其中（或包含 `"*"`）
- 驗證機器人在群組中的成員資格
- 檢閱記錄：使用 `openclaw logs --follow` 查看略過原因
</Accordion>
<Accordion title="命令只能部分運作或完全無法運作">
- 授權你的傳送者身分（配對和/或數值 `allowFrom`）
- 即使群組政策是 `open`，命令授權仍會套用
- `setMyCommands failed` 且出現 `BOT_COMMANDS_TOO_MUCH` 表示原生命令選單有太多項目；請減少 Plugin/skill/自訂命令，或停用原生選單
- `deleteMyCommands` / `setMyCommands` 啟動呼叫有界限，且在請求逾時時會透過 Telegram 的傳輸後援重試一次。持續性的網路/擷取錯誤通常表示對 `api.telegram.org` 的 DNS/HTTPS 可達性問題
</Accordion>
<Accordion title="啟動回報未授權權杖">
- `getMe returned 401` 是已設定機器人權杖的 Telegram 驗證失敗。
- 在 BotFather 中重新複製或重新產生機器人權杖，然後更新預設帳號的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
- 啟動期間的 `deleteWebhook 401 Unauthorized` 也是驗證失敗；將其視為「不存在 Webhook」只會把同一個錯誤權杖失敗延後到後續 API 呼叫。
- 如果 `deleteWebhook` 在輪詢啟動期間因暫時性網路錯誤而失敗，OpenClaw 會檢查 `getWebhookInfo`；當 Telegram 回報空的 Webhook URL 時，輪詢會繼續，因為清理已經滿足。
</Accordion>
<Accordion title="輪詢或網路不穩定">
- Node 22+ + 自訂 fetch/proxy 可能會在 AbortSignal 型別不相符時觸發立即中止行為。
- 有些主機會先將 `api.telegram.org` 解析為 IPv6；損壞的 IPv6 對外連線可能導致間歇性的 Telegram API 失敗。
- 如果日誌包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 現在會將這些作為可復原的網路錯誤重試。
- 如果日誌包含 `Polling stall detected`，OpenClaw 預設會在 120 秒內沒有完成長輪詢活性後，重新啟動輪詢並重建 Telegram 傳輸。
- `openclaw channels status --probe` 和 `openclaw doctor` 會在執行中的輪詢帳戶於啟動寬限期後尚未完成 `getUpdates`、執行中的 webhook 帳戶於啟動寬限期後尚未完成 `setWebhook`，或最後一次成功的輪詢傳輸活動已過舊時發出警告。
- 只有在長時間執行的 `getUpdates` 呼叫正常，但你的主機仍回報錯誤的輪詢停滯重新啟動時，才增加 `channels.telegram.pollingStallThresholdMs`。持續停滯通常表示主機與 `api.telegram.org` 之間存在 proxy、DNS、IPv6 或 TLS 對外連線問題。
- Telegram 也會遵循 Bot API 傳輸的程序 proxy 環境變數，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 以及它們的小寫變體。`NO_PROXY` / `no_proxy` 仍可繞過 `api.telegram.org`。
- 如果服務環境透過 `OPENCLAW_PROXY_URL` 設定了 OpenClaw 受管 proxy，且沒有標準 proxy 環境變數，Telegram 也會將該 URL 用於 Bot API 傳輸。
- 在直接對外連線/TLS 不穩定的 VPS 主機上，請透過 `channels.telegram.proxy` 路由 Telegram API 呼叫：
```yaml
channels:
telegram:
proxy: socks5://<user>:<password>@proxy-host:1080
```
- Node 22+ 預設為 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
- 如果你的主機是 WSL2，或明確以僅 IPv4 行為運作得更好，請強制指定位址族選擇：
```yaml
channels:
telegram:
network:
autoSelectFamily: false
```
- RFC 2544 基準測試範圍的答案（`198.18.0.0/15`）預設已允許
用於 Telegram 媒體下載。如果受信任的 fake-IP 或
透明 proxy 在媒體下載期間將 `api.telegram.org` 重寫為其他
私有/內部/特殊用途位址，你可以選擇啟用僅限 Telegram 的繞過：
```yaml
channels:
telegram:
network:
dangerouslyAllowPrivateNetwork: true
```
- 同樣的選擇啟用可在每個帳戶層級透過
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 使用。
- 如果你的 proxy 將 Telegram 媒體主機解析為 `198.18.x.x`，請先保持
危險旗標關閉。Telegram 媒體預設已允許 RFC 2544
基準測試範圍。
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 會削弱 Telegram
媒體 SSRF 防護。僅在受信任、由操作者控制的 proxy
環境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它們
會合成 RFC 2544 基準測試
範圍之外的私有或特殊用途答案。一般公開網際網路 Telegram 存取請保持關閉。
</Warning>
- 環境覆寫（暫時）：
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- 驗證 DNS 答案：
```bash
dig +short api.telegram.org A
dig +short api.telegram.org AAAA
```
</Accordion>
</AccordionGroup>
更多協助：[Channel 疑難排解](/zh-TW/channels/troubleshooting)。
## 設定參考
主要參考：[設定參考 - Telegram](/zh-TW/gateway/config-channels#telegram)。
<Accordion title="高資訊量 Telegram 欄位">
- 啟動/驗證：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必須指向一般檔案；符號連結會被拒絕）
- 存取控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、頂層 `bindings[]`（`type: "acp"`）
- exec 核准：`execApprovals`、`accounts.*.execApprovals`
- 指令/選單：`commands.native`、`commands.nativeSkills`、`customCommands`
- 執行緒/回覆：`replyToMode`
- 串流：`streaming`（預覽）、`streaming.preview.toolProgress`、`blockStreaming`
- 格式化/傳遞：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
- 媒體/網路：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
- 自訂 API 根目錄：`apiRoot`（僅 Bot API 根目錄；不要包含 `/bot<TOKEN>`）
- Webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
- 動作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- 回應：`reactionNotifications`、`reactionLevel`
- 錯誤：`errorPolicy`、`errorCooldownMs`
- 寫入/歷史記錄：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
</Accordion>
<Note>
多帳戶優先順序：設定兩個或更多帳戶 ID 時，請設定 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），以明確指定預設路由。否則 OpenClaw 會退回到第一個正規化的帳戶 ID，且 `openclaw doctor` 會發出警告。命名帳戶會繼承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不會繼承 `accounts.default.*` 值。
</Note>
## 相關
<CardGroup cols={2}>
<Card title="配對" icon="link" href="/zh-TW/channels/pairing">
將 Telegram 使用者與 Gateway 配對。
</Card>
<Card title="群組" icon="users" href="/zh-TW/channels/groups">
群組與主題允許清單行為。
</Card>
<Card title="Channel 路由" icon="route" href="/zh-TW/channels/channel-routing">
將傳入訊息路由到代理。
</Card>
<Card title="安全性" icon="shield" href="/zh-TW/gateway/security">
威脅模型與強化。
</Card>
<Card title="多代理路由" icon="sitemap" href="/zh-TW/concepts/multi-agent">
將群組與主題對應到代理。
</Card>
<Card title="疑難排解" icon="wrench" href="/zh-TW/channels/troubleshooting">
跨 Channel 診斷。
</Card>
</CardGroup>

298
docs/zh-TW/channels/tlon.md Normal file
View File

@ -0,0 +1,298 @@
---
read_when:
- 正在開發 Tlon/Urbit 頻道功能
summary: Tlon/Urbit 支援狀態、功能與設定
title: Tlon
x-i18n:
generated_at: "2026-04-30T02:49:23Z"
model: gpt-5.5
provider: openai
source_hash: bec632f946796a0ea4bceb5ad26f1ff1825c4304bf7252e9d2fd4d3889d36b52
source_path: channels/tlon.md
workflow: 16
---
Tlon 是建構於 Urbit 之上的去中心化通訊軟體。OpenClaw 會連線到你的 Urbit ship，並可
回應私訊和群組聊天室訊息。群組回覆預設需要 @ 提及，且可
透過允許清單進一步限制。
狀態：隨附 Plugin。支援私訊、群組提及、討論串回覆、富文字格式，以及
圖片上傳。尚不支援反應和投票。
## 隨附 Plugin
Tlon 在目前的 OpenClaw 版本中作為隨附 Plugin 提供，因此一般封裝
建置不需要另外安裝。
如果你使用的是較舊的建置，或排除 Tlon 的自訂安裝，請在發布
目前的 npm 套件後安裝它：
透過 CLI 安裝（npm registry，在目前套件存在時）：
```bash
openclaw plugins install @openclaw/tlon
```
如果 npm 回報 OpenClaw 擁有的套件已淘汰，請使用目前封裝的
OpenClaw 建置，或在較新的 npm 套件發布前使用本機 checkout 路徑。
本機 checkout（從 git repo 執行時）：
```bash
openclaw plugins install ./path/to/local/tlon-plugin
```
詳細資訊：[Plugins](/zh-TW/tools/plugin)
## 設定
1. 確認 Tlon Plugin 可用。
- 目前封裝的 OpenClaw 版本已隨附它。
- 較舊/自訂安裝可使用上述命令手動加入。
2. 取得你的 ship URL 和登入代碼。
3. 設定 `channels.tlon`。
4. 重新啟動 Gateway。
5. 私訊機器人，或在群組頻道中提及它。
最小設定（單一帳號）：
```json5
{
channels: {
tlon: {
enabled: true,
ship: "~sampel-palnet",
url: "https://your-ship-host",
code: "lidlut-tabwed-pillex-ridrup",
ownerShip: "~your-main-ship", // recommended: your ship, always allowed
},
},
}
```
## 私有/LAN ships
OpenClaw 預設會封鎖私有/內部主機名稱和 IP 範圍，以提供 SSRF 防護。
如果你的 ship 在私有網路上執行（localhost、LAN IP 或內部主機名稱），
你必須明確選擇啟用：
```json5
{
channels: {
tlon: {
url: "http://localhost:8080",
allowPrivateNetwork: true,
},
},
}
```
這適用於下列 URL：
- `http://localhost:8080`
- `http://192.168.x.x:8080`
- `http://my-ship.local:8080`
⚠️ 只有在你信任本機網路時才啟用此設定。此設定會停用
對你的 ship URL 發出請求時的 SSRF 防護。
## 群組頻道
預設啟用自動探索。你也可以手動固定頻道：
```json5
{
channels: {
tlon: {
groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
},
},
}
```
停用自動探索：
```json5
{
channels: {
tlon: {
autoDiscoverChannels: false,
},
},
}
```
## 存取控制
私訊允許清單（空白 = 不允許私訊，使用 `ownerShip` 進行核准流程）：
```json5
{
channels: {
tlon: {
dmAllowlist: ["~zod", "~nec"],
},
},
}
```
群組授權（預設受限制）：
```json5
{
channels: {
tlon: {
defaultAuthorizedShips: ["~zod"],
authorization: {
channelRules: {
"chat/~host-ship/general": {
mode: "restricted",
allowedShips: ["~zod", "~nec"],
},
"chat/~host-ship/announcements": {
mode: "open",
},
},
},
},
},
}
```
## 擁有者與核准系統
設定擁有者 ship，在未授權使用者嘗試互動時接收核准請求：
```json5
{
channels: {
tlon: {
ownerShip: "~your-main-ship",
},
},
}
```
擁有者 ship 會**自動在所有地方獲得授權**——私訊邀請會自動接受，
頻道訊息也一律允許。你不需要將擁有者加入 `dmAllowlist` 或
`defaultAuthorizedShips`。
設定後，擁有者會收到下列私訊通知：
- 來自不在允許清單中 ship 的私訊請求
- 未經授權頻道中的提及
- 群組邀請請求
## 自動接受設定
自動接受私訊邀請（適用於 dmAllowlist 中的 ships）：
```json5
{
channels: {
tlon: {
autoAcceptDmInvites: true,
},
},
}
```
自動接受群組邀請：
```json5
{
channels: {
tlon: {
autoAcceptGroupInvites: true,
},
},
}
```
## 傳遞目標（CLI/Cron）
搭配 `openclaw message send` 或 Cron 傳遞使用這些目標：
- 私訊：`~sampel-palnet` 或 `dm/~sampel-palnet`
- 群組：`chat/~host-ship/channel` 或 `group:~host-ship/channel`
## 隨附 Skills
Tlon Plugin 包含隨附的 Skills（[`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)），
可提供 Tlon 操作的 CLI 存取：
- **聯絡人**：取得/更新個人檔案、列出聯絡人
- **頻道**：列出、建立、張貼訊息、擷取歷程
- **群組**：列出、建立、管理成員
- **私訊**：傳送訊息、對訊息加入反應
- **反應**：對貼文和私訊新增/移除 emoji 反應
- **設定**：透過 slash commands 管理 Plugin 權限
安裝 Plugin 後，該 Skills 會自動可用。
## 功能
| 功能 | 狀態 |
| --------------- | --------------------------------------- |
| 直接訊息 | ✅ 支援 |
| 群組/頻道 | ✅ 支援（預設需要提及） |
| 討論串 | ✅ 支援（在討論串中自動回覆） |
| 富文字 | ✅ Markdown 會轉換為 Tlon 格式 |
| 圖片 | ✅ 上傳到 Tlon 儲存空間 |
| 反應 | ✅ 透過[隨附 Skills](#bundled-skill) |
| 投票 | ❌ 尚不支援 |
| 原生命令 | ✅ 支援（預設僅擁有者） |
## 疑難排解
先執行這個階梯：
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
```
常見失敗：
- **私訊被忽略**：寄件者不在 `dmAllowlist` 中，且未設定 `ownerShip` 以供核准流程使用。
- **群組訊息被忽略**：頻道未被探索到，或寄件者未獲授權。
- **連線錯誤**：檢查 ship URL 是否可連線；對本機 ships 啟用 `allowPrivateNetwork`。
- **驗證錯誤**：確認登入代碼是目前有效的（代碼會輪替）。
## 設定參考
完整設定：[設定](/zh-TW/gateway/configuration)
提供者選項：
- `channels.tlon.enabled`：啟用/停用頻道啟動。
- `channels.tlon.ship`：機器人的 Urbit ship 名稱（例如 `~sampel-palnet`）。
- `channels.tlon.url`：ship URL（例如 `https://sampel-palnet.tlon.network`）。
- `channels.tlon.code`：ship 登入代碼。
- `channels.tlon.allowPrivateNetwork`：允許 localhost/LAN URL（SSRF 繞過）。
- `channels.tlon.ownerShip`：核准系統的擁有者 ship（一律獲授權）。
- `channels.tlon.dmAllowlist`：允許私訊的 ships（空白 = 無）。
- `channels.tlon.autoAcceptDmInvites`：自動接受來自允許清單中 ships 的私訊。
- `channels.tlon.autoAcceptGroupInvites`：自動接受所有群組邀請。
- `channels.tlon.autoDiscoverChannels`：自動探索群組頻道（預設：true）。
- `channels.tlon.groupChannels`：手動固定的頻道 nests。
- `channels.tlon.defaultAuthorizedShips`：對所有頻道都獲授權的 ships。
- `channels.tlon.authorization.channelRules`：每個頻道的驗證規則。
- `channels.tlon.showModelSignature`：在訊息後附加模型名稱。
## 備註
- 群組回覆需要提及（例如 `~your-bot-ship`）才會回應。
- 討論串回覆：如果傳入訊息位於討論串中，OpenClaw 會在討論串內回覆。
- 富文字：Markdown 格式（粗體、斜體、程式碼、標題、清單）會轉換為 Tlon 的原生格式。
- 圖片：URL 會上傳到 Tlon 儲存空間，並嵌入為圖片區塊。
## 相關
- [頻道概觀](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — 私訊驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天室行為與提及閘控
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的 session 路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化措施

148
docs/zh-TW/channels/troubleshooting.md Normal file
View File

@ -0,0 +1,148 @@
---
read_when:
- 通道傳輸顯示已連線，但回覆失敗
- 深入查閱提供者文件前，需要頻道特定檢查
summary: 快速通道層級疑難排解，包含各通道的失敗特徵與修復方式
title: 通道疑難排解
x-i18n:
generated_at: "2026-04-30T02:50:00Z"
model: gpt-5.5
provider: openai
source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee
source_path: channels/troubleshooting.md
workflow: 16
---
當通道已連線但行為不正確時，請使用此頁面。
## 命令階梯
先依序執行這些命令：
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
健康基準：
- `Runtime: running`
- `Connectivity probe: ok`
- `Capability: read-only`、`write-capable` 或 `admin-capable`
- 通道探測顯示傳輸已連線，且在支援的情況下顯示 `works` 或 `audit ok`
## WhatsApp
### WhatsApp 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 已連線但沒有私人訊息回覆 | `openclaw pairing list whatsapp` | 核准寄件者，或切換私人訊息政策/允許清單。 |
| 群組訊息被忽略 | 檢查設定中的 `requireMention` + 提及模式 | 提及機器人，或放寬該群組的提及政策。 |
| QR 登入因 408 而逾時 | 檢查 Gateway 的 `HTTPS_PROXY` / `HTTP_PROXY` 環境變數 | 設定可連線的 Proxy；僅將 `NO_PROXY` 用於略過連線。 |
| 隨機斷線/重新登入迴圈 | `openclaw channels status --probe` + 日誌 | 即使目前已連線，最近重新連線也會被標記；監看日誌、重新啟動 Gateway，若持續不穩再重新連結。 |
完整疑難排解：[WhatsApp 疑難排解](/zh-TW/channels/whatsapp#troubleshooting)
## Telegram
### Telegram 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| ------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `/start` 但沒有可用的回覆流程 | `openclaw pairing list telegram` | 核准配對或變更私人訊息政策。 |
| 機器人在線上但群組保持沉默 | 驗證提及要求與機器人隱私模式 | 停用隱私模式以允許群組可見，或提及機器人。 |
| 傳送因網路錯誤而失敗 | 檢查日誌中的 Telegram API 呼叫失敗 | 修正到 `api.telegram.org` 的 DNS/IPv6/Proxy 路由。 |
| 啟動回報 `getMe returned 401` | 檢查設定的 Token 來源 | 重新複製或重新產生 BotFather Token，並更新 `botToken`、`tokenFile` 或預設帳號的 `TELEGRAM_BOT_TOKEN`。 |
| 輪詢停滯或重新連線緩慢 | 使用 `openclaw logs --follow` 檢查輪詢診斷 | 升級；若重新啟動是誤判，請調整 `pollingStallThresholdMs`。持續停滯仍表示 Proxy/DNS/IPv6 有問題。 |
| 啟動時 `setMyCommands` 被拒絕 | 檢查日誌中的 `BOT_COMMANDS_TOO_MUCH` | 減少 Plugin/skill/自訂 Telegram 命令，或停用原生選單。 |
| 升級後允許清單封鎖了你 | `openclaw security audit` 和設定允許清單 | 執行 `openclaw doctor --fix`，或將 `@username` 替換為數字寄件者 ID。 |
完整疑難排解：[Telegram 疑難排解](/zh-TW/channels/telegram#troubleshooting)
## Discord
### Discord 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| ------------------------------- | ----------------------------------- | ---------------------------------------------------------- |
| 機器人在線上但沒有伺服器回覆 | `openclaw channels status --probe` | 允許伺服器/頻道，並驗證訊息內容 Intent。 |
| 群組訊息被忽略 | 檢查日誌中的提及閘控丟棄 | 提及機器人，或設定伺服器/頻道 `requireMention: false`。 |
| 私人訊息回覆遺失 | `openclaw pairing list discord` | 核准私人訊息配對或調整私人訊息政策。 |
完整疑難排解：[Discord 疑難排解](/zh-TW/channels/discord#troubleshooting)
## Slack
### Slack 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket mode 已連線但沒有回應 | `openclaw channels status --probe` | 驗證 App Token + Bot Token 和必要 Scope；在 SecretRef 支援的設定中留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
| 私人訊息被封鎖 | `openclaw pairing list slack` | 核准配對或放寬私人訊息政策。 |
| 頻道訊息被忽略 | 檢查 `groupPolicy` 和頻道允許清單 | 允許該頻道，或將政策切換為 `open`。 |
完整疑難排解：[Slack 疑難排解](/zh-TW/channels/slack#troubleshooting)
## iMessage 和 BlueBubbles
### iMessage 和 BlueBubbles 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| -------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| 沒有傳入事件 | 驗證 Webhook/伺服器可達性與 App 權限 | 修正 Webhook URL 或 BlueBubbles 伺服器狀態。 |
| 在 macOS 上可傳送但無法接收 | 檢查 macOS 對 Messages 自動化的隱私權限 | 重新授予 TCC 權限並重新啟動通道程序。 |
| 私人訊息寄件者被封鎖 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 核准配對或更新允許清單。 |
完整疑難排解：
- [iMessage 疑難排解](/zh-TW/channels/imessage#troubleshooting)
- [BlueBubbles 疑難排解](/zh-TW/channels/bluebubbles#troubleshooting)
## Signal
### Signal 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| ------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
| Daemon 可達但機器人沉默 | `openclaw channels status --probe` | 驗證 `signal-cli` Daemon URL/帳號和接收模式。 |
| 私人訊息被封鎖 | `openclaw pairing list signal` | 核准寄件者或調整私人訊息政策。 |
| 群組回覆未觸發 | 檢查群組允許清單和提及模式 | 新增寄件者/群組或放寬閘控。 |
完整疑難排解：[Signal 疑難排解](/zh-TW/channels/signal#troubleshooting)
## QQ Bot
### QQ Bot 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| 機器人回覆「gone to Mars」 | 驗證設定中的 `appId` 和 `clientSecret` | 設定憑證或重新啟動 Gateway。 |
| 沒有傳入訊息 | `openclaw channels status --probe` | 在 QQ Open Platform 上驗證憑證。 |
| 語音未被轉錄 | 檢查 STT 提供者設定 | 設定 `channels.qqbot.stt` 或 `tools.media.audio`。 |
| 主動訊息未送達 | 檢查 QQ 平台互動要求 | 若近期沒有互動，QQ 可能會封鎖機器人主動發起的訊息。 |
完整疑難排解：[QQ Bot 疑難排解](/zh-TW/channels/qqbot#troubleshooting)
## Matrix
### Matrix 失敗特徵
| 症狀 | 最快檢查 | 修正 |
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| 已登入但忽略房間訊息 | `openclaw channels status --probe` | 檢查 `groupPolicy`、房間允許清單與提及閘控。 |
| 私人訊息未處理 | `openclaw pairing list matrix` | 核准寄件者或調整私人訊息政策。 |
| 加密房間失敗 | `openclaw matrix verify status` | 重新驗證裝置，然後檢查 `openclaw matrix verify backup status`。 |
| 備份還原擱置/損壞 | `openclaw matrix verify backup status` | 執行 `openclaw matrix verify backup restore`，或使用復原金鑰重新執行。 |
| 交叉簽署/啟動流程看起來不正確 | `openclaw matrix verify bootstrap` | 一次修復祕密儲存、交叉簽署與備份狀態。 |
完整設定與配置：[Matrix](/zh-TW/channels/matrix)
## 相關
- [配對](/zh-TW/channels/pairing)
- [通道路由](/zh-TW/channels/channel-routing)
- [Gateway 疑難排解](/zh-TW/gateway/troubleshooting)

439
docs/zh-TW/channels/twitch.md Normal file
View File

@ -0,0 +1,439 @@
---
read_when:
- 設定 OpenClaw 的 Twitch 聊天整合
sidebarTitle: Twitch
summary: Twitch 聊天機器人組態與設定
title: Twitch
x-i18n:
generated_at: "2026-04-30T02:49:56Z"
model: gpt-5.5
provider: openai
source_hash: 897079687a243c9c2ce2be63167e59f4413bbd89735fb79f03928547023bd787
source_path: channels/twitch.md
workflow: 16
---
透過 IRC 連線支援 Twitch 聊天。OpenClaw 會以 Twitch 使用者（機器人帳號）身分連線，以在頻道中接收與傳送訊息。
## 內建 Plugin
<Note>
Twitch 在目前的 OpenClaw 發行版本中以內建 Plugin 提供，因此一般封裝建置不需要另外安裝。
</Note>
如果你使用的是較舊的建置，或是不包含 Twitch 的自訂安裝，請在新版 npm 套件發布後安裝：
<Tabs>
<Tab title="npm registry">
```bash
openclaw plugins install @openclaw/twitch
```
</Tab>
<Tab title="本機 checkout">
```bash
openclaw plugins install ./path/to/local/twitch-plugin
```
</Tab>
</Tabs>
如果 npm 回報 OpenClaw 擁有的套件已棄用，請使用目前封裝好的
OpenClaw 建置，或使用本機 checkout 路徑，直到更新的 npm 套件
發布為止。
詳細資訊：[Plugins](/zh-TW/tools/plugin)
## 快速設定（初學者）
<Steps>
<Step title="確認 Plugin 可用">
目前封裝好的 OpenClaw 發行版本已經內建它。較舊或自訂安裝可使用上方命令手動加入。
</Step>
<Step title="建立 Twitch 機器人帳號">
為機器人建立專用的 Twitch 帳號（或使用現有帳號）。
</Step>
<Step title="產生憑證">
使用 [Twitch Token Generator](https://twitchtokengenerator.com/)：
- 選取 **Bot Token**
- 確認已選取 `chat:read` 和 `chat:write` scopes
- 複製 **Client ID** 和 **Access Token**
</Step>
<Step title="找出你的 Twitch 使用者 ID">
使用 [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) 將使用者名稱轉換為 Twitch 使用者 ID。
</Step>
<Step title="設定權杖">
- Env：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（僅預設帳號）
- 或 config：`channels.twitch.accessToken`
如果兩者都設定，config 優先（env fallback 僅適用於預設帳號）。
</Step>
<Step title="啟動 Gateway">
使用已設定的 channel 啟動 Gateway。
</Step>
</Steps>
<Warning>
加入存取控制（`allowFrom` 或 `allowedRoles`），以防止未授權使用者觸發機器人。`requireMention` 預設為 `true`。
</Warning>
最小設定：
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw", // Bot's Twitch account
accessToken: "oauth:abc123...", // OAuth Access Token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
clientId: "xyz789...", // Client ID from Token Generator
channel: "vevisk", // Which Twitch channel's chat to join (required)
allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
},
},
}
```
## 它是什麼
- 由 Gateway 擁有的 Twitch channel。
- 決定性路由：回覆一律回到 Twitch。
- 每個帳號都對應到隔離的 session key `agent:<agentId>:twitch:<accountName>`。
- `username` 是機器人的帳號（用於驗證身分），`channel` 是要加入的聊天室。
## 設定（詳細）
### 產生憑證
使用 [Twitch Token Generator](https://twitchtokengenerator.com/)：
- 選取 **Bot Token**
- 確認已選取 `chat:read` 和 `chat:write` scopes
- 複製 **Client ID** 和 **Access Token**
<Note>
不需要手動註冊應用程式。權杖會在數小時後過期。
</Note>
### 設定機器人
<Tabs>
<Tab title="Env var（僅預設帳號）">
```bash
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
```
</Tab>
<Tab title="Config">
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
},
}
```
</Tab>
</Tabs>
如果 env 和 config 都已設定，config 優先。
### 存取控制（建議）
```json5
{
channels: {
twitch: {
allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
},
},
}
```
偏好使用 `allowFrom` 作為嚴格允許清單。如果你想使用以角色為基礎的存取，請改用 `allowedRoles`。
**可用角色：** `"moderator"`、`"owner"`、`"vip"`、`"subscriber"`、`"all"`。
<Note>
**為什麼使用使用者 ID？** 使用者名稱可以變更，可能導致冒名。使用者 ID 是永久的。
找出你的 Twitch 使用者 ID：[https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)（將你的 Twitch 使用者名稱轉換為 ID）
</Note>
## 權杖重新整理（選用）
來自 [Twitch Token Generator](https://twitchtokengenerator.com/) 的權杖無法自動重新整理；過期時請重新產生。
若要自動重新整理權杖，請在 [Twitch Developer Console](https://dev.twitch.tv/console) 建立你自己的 Twitch 應用程式，並加入 config：
```json5
{
channels: {
twitch: {
clientSecret: "your_client_secret",
refreshToken: "your_refresh_token",
},
},
}
```
機器人會在過期前自動重新整理權杖，並記錄重新整理事件。
## 多帳號支援
使用 `channels.twitch.accounts` 搭配每個帳號各自的權杖。共享模式請參閱[設定](/zh-TW/gateway/configuration)。
範例（一個機器人帳號在兩個頻道中）：
```json5
{
channels: {
twitch: {
accounts: {
channel1: {
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
channel2: {
username: "openclaw",
accessToken: "oauth:def456...",
clientId: "uvw012...",
channel: "secondchannel",
},
},
},
},
}
```
<Note>
每個帳號都需要自己的權杖（每個頻道一個權杖）。
</Note>
## 存取控制
<Tabs>
<Tab title="使用者 ID 允許清單（最安全）">
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789", "987654321"],
},
},
},
},
}
```
</Tab>
<Tab title="以角色為基礎">
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator", "vip"],
},
},
},
},
}
```
`allowFrom` 是嚴格允許清單。設定後，只允許這些使用者 ID。如果你想使用以角色為基礎的存取，請不要設定 `allowFrom`，並改為設定 `allowedRoles`。
</Tab>
<Tab title="停用 @mention 要求">
預設情況下，`requireMention` 為 `true`。若要停用並回應所有訊息：
```json5
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}
```
</Tab>
</Tabs>
## 疑難排解
首先，執行診斷命令：
```bash
openclaw doctor
openclaw channels status --probe
```
<AccordionGroup>
<Accordion title="機器人沒有回應訊息">
- **檢查存取控制：** 確保你的使用者 ID 位於 `allowFrom` 中，或暫時移除 `allowFrom` 並設定 `allowedRoles: ["all"]` 進行測試。
- **檢查機器人是否在該頻道中：** 機器人必須加入 `channel` 中指定的頻道。
</Accordion>
<Accordion title="權杖問題">
「連線失敗」或驗證錯誤：
- 確認 `accessToken` 是 OAuth access token 值（通常以 `oauth:` 前綴開頭）
- 檢查權杖具有 `chat:read` 和 `chat:write` scopes
- 如果使用權杖重新整理，請確認已設定 `clientSecret` 和 `refreshToken`
</Accordion>
<Accordion title="權杖重新整理無法運作">
檢查記錄中的重新整理事件：
```
Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)
```
如果你看到「token refresh disabled (no refresh token)」：
- 確保已提供 `clientSecret`
- 確保已提供 `refreshToken`
</Accordion>
</AccordionGroup>
## Config
### 帳號 config
<ParamField path="username" type="string">
機器人使用者名稱。
</ParamField>
<ParamField path="accessToken" type="string">
具有 `chat:read` 和 `chat:write` 的 OAuth access token。
</ParamField>
<ParamField path="clientId" type="string">
Twitch Client ID（來自 Token Generator 或你的應用程式）。
</ParamField>
<ParamField path="channel" type="string" required>
要加入的頻道。
</ParamField>
<ParamField path="enabled" type="boolean" default="true">
啟用此帳號。
</ParamField>
<ParamField path="clientSecret" type="string">
選用：用於自動重新整理權杖。
</ParamField>
<ParamField path="refreshToken" type="string">
選用：用於自動重新整理權杖。
</ParamField>
<ParamField path="expiresIn" type="number">
權杖到期秒數。
</ParamField>
<ParamField path="obtainmentTimestamp" type="number">
權杖取得時間戳記。
</ParamField>
<ParamField path="allowFrom" type="string[]">
使用者 ID 允許清單。
</ParamField>
<ParamField path="allowedRoles" type='Array<"moderator" | "owner" | "vip" | "subscriber" | "all">'>
以角色為基礎的存取控制。
</ParamField>
<ParamField path="requireMention" type="boolean" default="true">
要求 @mention。
</ParamField>
### Provider 選項
- `channels.twitch.enabled` - 啟用/停用 channel 啟動
- `channels.twitch.username` - 機器人使用者名稱（簡化的單帳號 config）
- `channels.twitch.accessToken` - OAuth access token（簡化的單帳號 config）
- `channels.twitch.clientId` - Twitch Client ID（簡化的單帳號 config）
- `channels.twitch.channel` - 要加入的頻道（簡化的單帳號 config）
- `channels.twitch.accounts.<accountName>` - 多帳號 config（以上所有帳號欄位）
完整範例：
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
clientSecret: "secret123...",
refreshToken: "refresh456...",
allowFrom: ["123456789"],
allowedRoles: ["moderator", "vip"],
accounts: {
default: {
username: "mybot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "your_channel",
enabled: true,
clientSecret: "secret123...",
refreshToken: "refresh456...",
expiresIn: 14400,
obtainmentTimestamp: 1706092800000,
allowFrom: ["123456789", "987654321"],
allowedRoles: ["moderator"],
},
},
},
},
}
```
## 工具動作
agent 可以使用動作呼叫 `twitch`：
- `send` - 傳送訊息到頻道
範例：
```json5
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}
```
## 安全性與營運
- **將權杖視同密碼** — 絕不要將權杖提交到 git。
- **使用自動權杖重新整理** 以支援長時間執行的機器人。
- **使用使用者 ID 允許清單** 而不是使用者名稱來做存取控制。
- **監控記錄** 以查看權杖重新整理事件和連線狀態。
- **最小化權杖 scopes** — 只要求 `chat:read` 和 `chat:write`。
- **如果卡住**：確認沒有其他程序佔用 session 後，重新啟動 Gateway。
## 限制
- 每則訊息 **500 個字元**（會在單字邊界自動分塊）。
- Markdown 會在分塊前移除。
- 沒有速率限制（使用 Twitch 內建的速率限制）。
## 相關
- [Channel 路由](/zh-TW/channels/channel-routing) — 訊息的 session 路由
- [Channels 概觀](/zh-TW/channels) — 所有支援的 channels
- [群組](/zh-TW/channels/groups) — 群組聊天行為與 mention 閘控
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

155
docs/zh-TW/channels/wechat.md Normal file
View File

@ -0,0 +1,155 @@
---
read_when:
- 您想要將 OpenClaw 連接到 WeChat 或 Weixin
- 您正在安裝或排解 openclaw-weixin 頻道 Plugin 的問題
- 你需要了解外部頻道 Plugin 如何與 Gateway 並行執行
summary: 透過外部 openclaw-weixin Plugin 設定 WeChat 通道
title: WeChat
x-i18n:
generated_at: "2026-04-30T02:50:18Z"
model: gpt-5.5
provider: openai
source_hash: ea7c815a364c2ae087041bf6de5b4182334c67377e18b9bedfa0f9d949afc09c
source_path: channels/wechat.md
workflow: 16
---
OpenClaw 透過 Tencent 的外部
`@tencent-weixin/openclaw-weixin` 頻道 Plugin 連接 WeChat。
狀態：外部 Plugin。支援直接聊天與媒體。目前 Plugin 能力中繼資料未宣告支援群組聊天。
## 命名
- **WeChat** 是這些文件中面向使用者的名稱。
- **Weixin** 是 Tencent 套件與 Plugin id 使用的名稱。
- `openclaw-weixin` 是 OpenClaw 頻道 id。
- `@tencent-weixin/openclaw-weixin` 是 npm 套件。
在 CLI 指令與設定路徑中使用 `openclaw-weixin`。
## 運作方式
WeChat 程式碼不在 OpenClaw 核心 repo 中。OpenClaw 提供通用頻道 Plugin 合約，而外部 Plugin 提供 WeChat 專用 runtime：
1. `openclaw plugins install` 安裝 `@tencent-weixin/openclaw-weixin`。
2. Gateway 探索 Plugin manifest 並載入 Plugin entrypoint。
3. Plugin 註冊頻道 id `openclaw-weixin`。
4. `openclaw channels login --channel openclaw-weixin` 啟動 QR 登入。
5. Plugin 將帳號憑證儲存在 OpenClaw 狀態目錄下。
6. Gateway 啟動時，Plugin 會為每個已設定帳號啟動其 Weixin 監控器。
7. 傳入的 WeChat 訊息會透過頻道合約標準化、路由到選取的 OpenClaw agent，並透過 Plugin 輸出路徑送回。
這種分離很重要：OpenClaw 核心應保持頻道無關。WeChat 登入、Tencent iLink API 呼叫、媒體上傳/下載、context tokens，以及帳號監控都由外部 Plugin 擁有。
## 安裝
快速安裝：
```bash
npx -y @tencent-weixin/openclaw-weixin-cli install
```
手動安裝：
```bash
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true
```
安裝後重新啟動 Gateway：
```bash
openclaw gateway restart
```
## 登入
在執行 Gateway 的同一台機器上執行 QR 登入：
```bash
openclaw channels login --channel openclaw-weixin
```
使用手機上的 WeChat 掃描 QR code 並確認登入。成功掃描後，Plugin 會在本機儲存帳號 token。
若要新增另一個 WeChat 帳號，請再次執行相同的登入指令。若有多個帳號，請依帳號、頻道與傳送者隔離直接訊息工作階段：
```bash
openclaw config set session.dmScope per-account-channel-peer
```
## 存取控制
直接訊息會使用頻道 Plugin 的一般 OpenClaw pairing 與 allowlist 模型。
核准新的傳送者：
```bash
openclaw pairing list openclaw-weixin
openclaw pairing approve openclaw-weixin <CODE>
```
完整的存取控制模型請參閱 [Pairing](/zh-TW/channels/pairing)。
## 相容性
Plugin 會在啟動時檢查主機的 OpenClaw 版本。
| Plugin 線 | OpenClaw 版本 | npm tag |
| ----------- | ----------------------- | -------- |
| `2.x` | `>=2026.3.22` | `latest` |
| `1.x` | `>=2026.1.0 <2026.3.22` | `legacy` |
如果 Plugin 回報你的 OpenClaw 版本太舊，請更新 OpenClaw，或安裝舊版 Plugin 線：
```bash
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
```
## Sidecar process
WeChat Plugin 在監控 Tencent iLink API 時，可以在 Gateway 旁執行輔助工作。在 issue #68451 中，該輔助路徑暴露了 OpenClaw 通用過時 Gateway 清理中的一個錯誤：子行程可能會嘗試清理父 Gateway 行程，導致在 systemd 等 process manager 下出現重新啟動迴圈。
目前 OpenClaw 啟動清理會排除目前行程及其祖先，因此頻道輔助程式不得終止啟動它的 Gateway。此修正是通用的；它不是核心中的 WeChat 專用路徑。
## 疑難排解
檢查安裝與狀態：
```bash
openclaw plugins list
openclaw channels status --probe
openclaw --version
```
如果頻道顯示已安裝但沒有連線，請確認 Plugin 已啟用並重新啟動：
```bash
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart
```
如果啟用 WeChat 後 Gateway 反覆重新啟動，請同時更新 OpenClaw 與 Plugin：
```bash
npm view @tencent-weixin/openclaw-weixin version
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
openclaw gateway restart
```
暫時停用：
```bash
openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart
```
## 相關文件
- 頻道概覽：[Chat Channels](/zh-TW/channels)
- Pairing：[Pairing](/zh-TW/channels/pairing)
- 頻道路由：[Channel Routing](/zh-TW/channels/channel-routing)
- Plugin 架構：[Plugin Architecture](/zh-TW/plugins/architecture)
- 頻道 Plugin SDK：[Channel Plugin SDK](/zh-TW/plugins/sdk-channel-plugins)
- 外部套件：[@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin)

681
docs/zh-TW/channels/whatsapp.md Normal file
View File

@ -0,0 +1,681 @@
---
read_when:
- 處理 WhatsApp/網頁通道行為或收件匣路由
summary: WhatsApp 通道支援、存取控制、傳遞行為與維運
title: WhatsApp
x-i18n:
generated_at: "2026-04-30T02:50:06Z"
model: gpt-5.5
provider: openai
source_hash: 5d0268e068de0001a11a6ed87fe70df8e685d1dcc87c8142ee5b3c77d7a727f3
source_path: channels/whatsapp.md
workflow: 16
---
狀態：可透過 WhatsApp Web (Baileys) 用於生產環境。Gateway 擁有已連結的工作階段。
## 安裝（隨需）
- Onboarding (`openclaw onboard`) 和 `openclaw channels add --channel whatsapp`
會在你第一次選取 WhatsApp Plugin 時提示安裝。
- 當 Plugin 尚未存在時，`openclaw channels login --channel whatsapp` 也會提供安裝流程。
- 開發通道 + git checkout：預設使用本機 Plugin 路徑。
- Stable/Beta：當目前套件已發布時，使用 npm 套件 `@openclaw/whatsapp`。
手動安裝仍可使用：
```bash
openclaw plugins install @openclaw/whatsapp
```
如果 npm 回報 OpenClaw 擁有的套件已棄用或缺失，請使用目前已封裝的 OpenClaw 建置，或使用本機 checkout，直到 npm 套件發布列車跟上為止。
<CardGroup cols={3}>
<Card title="配對" icon="link" href="/zh-TW/channels/pairing">
預設 DM 政策會對未知傳送者使用配對。
</Card>
<Card title="通道疑難排解" icon="wrench" href="/zh-TW/channels/troubleshooting">
跨通道診斷與修復操作手冊。
</Card>
<Card title="Gateway 設定" icon="settings" href="/zh-TW/gateway/configuration">
完整的通道設定模式與範例。
</Card>
</CardGroup>
## 快速設定
<Steps>
<Step title="設定 WhatsApp 存取政策">
```json5
{
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
```
</Step>
<Step title="連結 WhatsApp（QR）">
```bash
openclaw channels login --channel whatsapp
```
針對特定帳號：
```bash
openclaw channels login --channel whatsapp --account work
```
若要在登入前附加既有/自訂 WhatsApp Web 驗證目錄：
```bash
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work
```
</Step>
<Step title="啟動 gateway">
```bash
openclaw gateway
```
</Step>
<Step title="核准第一個配對要求（若使用配對模式）">
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
配對要求會在 1 小時後過期。每個通道最多保留 3 個待處理要求。
</Step>
</Steps>
<Note>
OpenClaw 建議在可行時使用獨立號碼執行 WhatsApp。（通道中繼資料與設定流程已針對該設定最佳化，但也支援個人號碼設定。）
</Note>
## 部署模式
<AccordionGroup>
<Accordion title="專用號碼（建議）">
這是最乾淨的操作模式：
- 為 OpenClaw 使用獨立的 WhatsApp 身分
- 更清楚的 DM allowlist 與路由邊界
- 較低的自我聊天混淆機率
最小政策模式：
```json5
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
```
</Accordion>
<Accordion title="個人號碼備援">
Onboarding 支援個人號碼模式，並寫入適合自我聊天的基準設定：
- `dmPolicy: "allowlist"`
- `allowFrom` 包含你的個人號碼
- `selfChatMode: true`
在執行階段，自我聊天保護會依據已連結的自身號碼與 `allowFrom` 判定。
</Accordion>
<Accordion title="僅限 WhatsApp Web 的通道範圍">
在目前的 OpenClaw 通道架構中，訊息平台通道以 WhatsApp Web (`Baileys`) 為基礎。
內建聊天通道登錄中沒有獨立的 Twilio WhatsApp 訊息通道。
</Accordion>
</AccordionGroup>
## 執行階段模型
- Gateway 擁有 WhatsApp socket 與重新連線迴圈。
- 重新連線 watchdog 使用 WhatsApp Web 傳輸活動，而不只是傳入應用程式訊息量，因此安靜的已連結裝置工作階段不會只因最近沒人傳訊息就重新啟動。若傳輸 frame 持續抵達但 watchdog 視窗內沒有處理任何應用程式訊息，較長的應用程式靜默上限仍會強制重新連線；對於最近活躍工作階段的暫時性重新連線，該應用程式靜默檢查會在第一個復原視窗使用一般訊息逾時。
- Baileys socket 時序明確位於 `web.whatsapp.*` 下：`keepAliveIntervalMs` 控制 WhatsApp Web 應用程式 ping，`connectTimeoutMs` 控制開啟握手逾時，而 `defaultQueryTimeoutMs` 控制 Baileys 查詢逾時。
- 對外傳送需要目標帳號有作用中的 WhatsApp listener。
- 狀態與廣播聊天會被忽略（`@status`、`@broadcast`）。
- 重新連線 watchdog 追蹤 WhatsApp Web 傳輸活動，而不只是傳入應用程式訊息量：安靜的已連結裝置工作階段會在傳輸 frame 持續時保持連線，但傳輸停滯會在較晚的遠端斷線路徑之前就強制重新連線。
- 直接聊天使用 DM 工作階段規則（`session.dmScope`；預設 `main` 會將 DM 收合至代理程式主工作階段）。
- 群組工作階段是隔離的（`agent:<agentId>:whatsapp:group:<jid>`）。
- WhatsApp Web 傳輸會遵循 gateway 主機上的標準 proxy 環境變數（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小寫變體）。請優先使用主機層級 proxy 設定，而非通道特定的 WhatsApp proxy 設定。
- 啟用 `messages.removeAckAfterReply` 時，OpenClaw 會在可見回覆送達後清除 WhatsApp ack reaction。
## Plugin hook 與隱私
WhatsApp 傳入訊息可能包含個人訊息內容、電話號碼、群組識別碼、傳送者名稱，以及工作階段關聯欄位。因此，除非你明確選擇加入，否則 WhatsApp 不會將傳入的 `message_received` hook payload 廣播給 Plugin：
```json5
{
channels: {
whatsapp: {
pluginHooks: {
messageReceived: true,
},
},
},
}
```
你可以將選擇加入範圍限定到單一帳號：
```json5
{
channels: {
whatsapp: {
accounts: {
work: {
pluginHooks: {
messageReceived: true,
},
},
},
},
},
}
```
只應對你信任可接收傳入 WhatsApp 訊息內容與識別碼的 Plugin 啟用此功能。
## 存取控制與啟用
<Tabs>
<Tab title="DM 政策">
`channels.whatsapp.dmPolicy` 控制直接聊天存取：
- `pairing`（預設）
- `allowlist`
- `open`（需要 `allowFrom` 包含 `"*"`）
- `disabled`
`allowFrom` 接受 E.164 風格號碼（內部會正規化）。
多帳號覆寫：`channels.whatsapp.accounts.<id>.dmPolicy`（以及 `allowFrom`）會優先於該帳號的通道層級預設值。
執行階段行為詳細資訊：
- 配對會保存在通道 allow-store 中，並與設定的 `allowFrom` 合併
- 若未設定 allowlist，預設允許已連結的自身號碼
- OpenClaw 永遠不會自動配對對外 `fromMe` DM（你從已連結裝置傳送給自己的訊息）
</Tab>
<Tab title="群組政策 + allowlist">
群組存取有兩層：
1. **群組成員 allowlist** (`channels.whatsapp.groups`)
- 若省略 `groups`，所有群組都符合資格
- 若存在 `groups`，它會作為群組 allowlist（允許 `"*"`）
2. **群組傳送者政策** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
- `open`：略過傳送者 allowlist
- `allowlist`：傳送者必須符合 `groupAllowFrom`（或 `*`）
- `disabled`：封鎖所有群組傳入
傳送者 allowlist 備援：
- 若未設定 `groupAllowFrom`，執行階段會在可用時退回使用 `allowFrom`
- 傳送者 allowlist 會在 mention/reply 啟用前評估
注意：如果完全沒有 `channels.whatsapp` 區塊，即使已設定 `channels.defaults.groupPolicy`，執行階段群組政策備援仍會是 `allowlist`（並記錄 warning log）。
</Tab>
<Tab title="Mention + /activation">
群組回覆預設需要 mention。
Mention 偵測包含：
- 對機器人身分的明確 WhatsApp mention
- 已設定的 mention regex pattern（`agents.list[].groupChat.mentionPatterns`，備援為 `messages.groupChat.mentionPatterns`）
- 已授權群組訊息的傳入語音筆記 transcript
- 隱含的回覆給機器人偵測（回覆傳送者符合機器人身分）
安全性注意事項：
- 引用/回覆只滿足 mention gating；它**不會**授予傳送者授權
- 使用 `groupPolicy: "allowlist"` 時，即使非 allowlist 傳送者回覆 allowlist 使用者的訊息，仍會被封鎖
工作階段層級啟用命令：
- `/activation mention`
- `/activation always`
`activation` 會更新工作階段狀態（不是全域設定）。它受 owner gating 控制。
</Tab>
</Tabs>
## 個人號碼與自我聊天行為
當已連結的自身號碼也出現在 `allowFrom` 中時，WhatsApp 自我聊天防護會啟用：
- 跳過自我聊天回合的讀取回條
- 忽略 mention-JID 自動觸發行為，否則它會 ping 你自己
- 如果未設定 `messages.responsePrefix`，自我聊天回覆預設為 `[{identity.name}]` 或 `[openclaw]`
## 訊息正規化與上下文
<AccordionGroup>
<Accordion title="傳入 envelope + 回覆上下文">
傳入 WhatsApp 訊息會包裝在共享的傳入 envelope 中。
如果存在引用回覆，會以下列形式附加上下文：
```text
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
```
可用時也會填入回覆中繼資料欄位（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、傳送者 JID/E.164）。
</Accordion>
<Accordion title="媒體 placeholder 與位置/聯絡人擷取">
純媒體傳入訊息會使用下列 placeholder 正規化：
- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`
已授權群組語音筆記會在 mention gating 前轉錄，前提是本文只有 `<media:audio>`，因此在語音筆記中說出機器人 mention 可觸發回覆。如果 transcript 仍未 mention 機器人，transcript 會保留在待處理群組歷史中，而不是保留原始 placeholder。
位置本文使用簡短座標文字。位置標籤/註解與聯絡人/vCard 詳細資料會呈現為 fenced 的不受信任中繼資料，而不是 inline prompt text。
</Accordion>
<Accordion title="待處理群組歷史注入">
對於群組，未處理訊息可被緩衝，並在機器人最後被觸發時作為上下文注入。
- 預設限制：`50`
- 設定：`channels.whatsapp.historyLimit`
- 備援：`messages.groupChat.historyLimit`
- `0` 會停用
注入標記：
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
</Accordion>
<Accordion title="讀取回條">
已接受的傳入 WhatsApp 訊息預設會啟用讀取回條。
全域停用：
```json5
{
channels: {
whatsapp: {
sendReadReceipts: false,
},
},
}
```
每帳號覆寫：
```json5
{
channels: {
whatsapp: {
accounts: {
work: {
sendReadReceipts: false,
},
},
},
},
}
```
即使全域啟用，自我聊天回合也會跳過讀取回條。
</Accordion>
</AccordionGroup>
## 傳遞、分段與媒體
<AccordionGroup>
<Accordion title="文字分段">
- 預設分段限制：`channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- `newline` 模式偏好段落邊界（空白行），然後退回到長度安全的分段
</Accordion>
<Accordion title="外送媒體行為">
- 支援圖片、影片、音訊（PTT 語音訊息）和文件 payload
- 音訊媒體會透過 Baileys `audio` payload 並帶有 `ptt: true` 傳送，因此 WhatsApp 用戶端會將其呈現為按住說話語音訊息
- 回覆 payload 會保留 `audioAsVoice`；即使 provider 傳回 MP3 或 WebM，WhatsApp 的 TTS 語音訊息輸出仍會走這條 PTT 路徑
- 原生 Ogg/Opus 音訊會以 `audio/ogg; codecs=opus` 傳送，以相容語音訊息
- 非 Ogg 音訊，包括 Microsoft Edge TTS 的 MP3/WebM 輸出，會先用 `ffmpeg` 轉碼為 48 kHz 單聲道 Ogg/Opus，再透過 PTT 傳遞
- `/tts latest` 會將最新的助理回覆作為一則語音訊息傳送，並防止同一則回覆重複傳送；`/tts chat on|off|default` 控制目前 WhatsApp 聊天的自動 TTS
- 透過影片傳送時使用 `gifPlayback: true` 支援動態 GIF 播放
- 傳送多媒體回覆 payload 時，caption 會套用到第一個媒體項目；但 PTT 語音訊息會先傳送音訊，再另外傳送可見文字，因為 WhatsApp 用戶端無法一致呈現語音訊息 caption
- 媒體來源可以是 HTTP(S)、`file://` 或本機路徑
</Accordion>
<Accordion title="媒體大小限制與 fallback 行為">
- 傳入媒體儲存上限：`channels.whatsapp.mediaMaxMb`（預設 `50`）
- 傳出媒體傳送上限：`channels.whatsapp.mediaMaxMb`（預設 `50`）
- 每個帳號的覆寫使用 `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- 圖片會自動最佳化（調整大小/品質掃描）以符合限制
- 媒體傳送失敗時，第一項 fallback 會傳送文字警告，而不是默默丟棄回應
</Accordion>
</AccordionGroup>
## 回覆引用
WhatsApp 支援原生回覆引用，傳出回覆會明顯引用傳入訊息。使用 `channels.whatsapp.replyToMode` 控制。
| 值 | 行為 |
| ----------- | --------------------------------------------------------------------- |
| `"off"` | 永不引用；作為一般訊息傳送 |
| `"first"` | 只引用第一個傳出回覆片段 |
| `"all"` | 引用每個傳出回覆片段 |
| `"batched"` | 引用佇列中的批次回覆，但立即回覆不引用 |
預設為 `"off"`。每個帳號的覆寫使用 `channels.whatsapp.accounts.<id>.replyToMode`。
```json5
{
channels: {
whatsapp: {
replyToMode: "first",
},
},
}
```
## 反應層級
`channels.whatsapp.reactionLevel` 控制 agent 在 WhatsApp 上使用 emoji reactions 的範圍：
| 層級 | Ack reactions | Agent 發起的 reactions | 說明 |
| ------------- | ------------- | ---------------------- | ------------------------------------------------ |
| `"off"` | 否 | 否 | 完全不使用 reactions |
| `"ack"` | 是 | 否 | 僅 Ack reactions（回覆前收件確認） |
| `"minimal"` | 是 | 是（保守） | Ack + agent reactions，採用保守指引 |
| `"extensive"` | 是 | 是（鼓勵） | Ack + agent reactions，採用鼓勵指引 |
預設：`"minimal"`。
每個帳號的覆寫使用 `channels.whatsapp.accounts.<id>.reactionLevel`。
```json5
{
channels: {
whatsapp: {
reactionLevel: "ack",
},
},
}
```
## 確認 reactions
WhatsApp 支援透過 `channels.whatsapp.ackReaction` 在收到傳入訊息時立即送出 ack reactions。
Ack reactions 受 `reactionLevel` 控制；當 `reactionLevel` 為 `"off"` 時會被抑制。
```json5
{
channels: {
whatsapp: {
ackReaction: {
emoji: "👀",
direct: true,
group: "mentions", // always | mentions | never
},
},
},
}
```
行為備註：
- 在傳入訊息被接受後立即傳送（回覆前）
- 失敗會記錄，但不會阻擋正常回覆傳遞
- 群組模式 `mentions` 會在提及觸發的回合中反應；群組啟用 `always` 會作為此檢查的旁路
- WhatsApp 使用 `channels.whatsapp.ackReaction`（此處不使用舊版 `messages.ackReaction`）
## 多帳號與憑證
<AccordionGroup>
<Accordion title="帳號選擇與預設值">
- 帳號 id 來自 `channels.whatsapp.accounts`
- 預設帳號選擇：若存在則使用 `default`，否則使用第一個已設定的帳號 id（排序後）
- 帳號 id 會在內部正規化以供查找
</Accordion>
<Accordion title="憑證路徑與舊版相容性">
- 目前的驗證路徑：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- 備份檔案：`creds.json.bak`
- `~/.openclaw/credentials/` 中的舊版預設驗證仍會被辨識/遷移，用於預設帳號流程
</Accordion>
<Accordion title="登出行為">
`openclaw channels logout --channel whatsapp [--account <id>]` 會清除該帳號的 WhatsApp 驗證狀態。
在舊版驗證目錄中，會保留 `oauth.json`，並移除 Baileys 驗證檔案。
</Accordion>
</AccordionGroup>
## 工具、動作與設定寫入
- Agent 工具支援包含 WhatsApp reaction 動作（`react`）。
- 動作閘門：
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
- 頻道發起的設定寫入預設為啟用（可透過 `channels.whatsapp.configWrites=false` 停用）。
## 疑難排解
<AccordionGroup>
<Accordion title="未連結（需要 QR）">
症狀：頻道狀態回報未連結。
修正：
```bash
openclaw channels login --channel whatsapp
openclaw channels status
```
</Accordion>
<Accordion title="已連結但已斷線 / 重新連線迴圈">
症狀：已連結的帳號反覆斷線或嘗試重新連線。
安靜的帳號可以在一般訊息逾時後仍保持連線；當 WhatsApp Web 傳輸活動停止、socket 關閉，或應用程式層級活動靜默超過較長安全視窗時，watchdog 會重新啟動。
如果記錄顯示重複的 `status=408 Request Time-out Connection was lost`，請調整 `web.whatsapp` 下的 Baileys socket 時序。先將 `keepAliveIntervalMs` 縮短到低於網路的閒置逾時，並在慢速或高遺失率連線上增加 `connectTimeoutMs`：
```json5
{
web: {
whatsapp: {
keepAliveIntervalMs: 15000,
connectTimeoutMs: 60000,
defaultQueryTimeoutMs: 60000,
},
},
}
```
修正：
```bash
openclaw doctor
openclaw logs --follow
```
如有需要，請用 `channels login` 重新連結。
</Accordion>
<Accordion title="在 proxy 後方 QR 登入逾時">
症狀：`openclaw channels login --channel whatsapp` 在顯示可用的 QR code 前失敗，並出現 `status=408 Request Time-out` 或 TLS socket 斷線。
WhatsApp Web 登入使用 Gateway 主機的標準 proxy 環境（`HTTPS_PROXY`、`HTTP_PROXY`、小寫變體和 `NO_PROXY`）。確認 Gateway 程序繼承 proxy env，且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。
</Accordion>
<Accordion title="傳送時沒有作用中的 listener">
當目標帳號沒有作用中的 Gateway listener 時，傳出傳送會快速失敗。
確認 Gateway 正在執行，且帳號已連結。
</Accordion>
<Accordion title="回覆出現在 transcript 中，但沒有出現在 WhatsApp">
Transcript 列會記錄 agent 產生的內容。WhatsApp 傳遞會另行檢查：OpenClaw 只有在 Baileys 對至少一個可見文字或媒體傳送傳回傳出訊息 id 後，才會將自動回覆視為已傳送。
Ack reactions 是獨立的回覆前收件確認。成功的 reaction 不代表後續文字或媒體回覆已被 WhatsApp 接受。
檢查 Gateway 記錄中是否有 `auto-reply delivery failed` 或 `auto-reply was not accepted by WhatsApp provider`。
</Accordion>
<Accordion title="群組訊息意外被忽略">
請依下列順序檢查：
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- `groups` allowlist entries
- 提及閘門（`requireMention` + 提及 patterns）
- `openclaw.json`（JSON5）中的重複鍵：後面的項目會覆寫前面的項目，因此每個 scope 只保留一個 `groupPolicy`
</Accordion>
<Accordion title="Bun runtime 警告">
WhatsApp Gateway runtime 應使用 Node。Bun 被標記為不相容於穩定的 WhatsApp/Telegram Gateway 操作。
</Accordion>
</AccordionGroup>
## 系統 prompts
WhatsApp 透過 `groups` 和 `direct` maps 支援 Telegram 風格的群組與直接聊天系統 prompts。
群組訊息的解析階層：
有效的 `groups` map 會先被決定：如果帳號定義自己的 `groups`，它會完全取代根層級的 `groups` map（沒有 deep merge）。Prompt 查找接著會在產生的單一 map 上執行：
1. **群組專屬系統 prompt**（`groups["<groupId>"].systemPrompt`）：當特定群組項目存在於 map 中，**且**其 `systemPrompt` 鍵已定義時使用。如果 `systemPrompt` 是空字串（`""`），wildcard 會被抑制，且不套用任何系統 prompt。
2. **群組 wildcard 系統 prompt**（`groups["*"].systemPrompt`）：當特定群組項目完全不存在於 map 中，或項目存在但未定義 `systemPrompt` 鍵時使用。
直接訊息的解析階層：
有效的 `direct` map 會先被決定：如果帳號定義自己的 `direct`，它會完全取代根層級的 `direct` map（沒有 deep merge）。Prompt 查找接著會在產生的單一 map 上執行：
1. **直接對象專屬系統 prompt**（`direct["<peerId>"].systemPrompt`）：當特定對象項目存在於 map 中，**且**其 `systemPrompt` 鍵已定義時使用。如果 `systemPrompt` 是空字串（`""`），wildcard 會被抑制，且不套用任何系統 prompt。
2. **直接對象 wildcard 系統 prompt**（`direct["*"].systemPrompt`）：當特定對象項目完全不存在於 map 中，或項目存在但未定義 `systemPrompt` 鍵時使用。
<Note>
`dms` 仍是每個 DM 輕量歷史覆寫 bucket（`dms.<id>.historyLimit`）。Prompt 覆寫位於 `direct` 下。
</Note>
**與 Telegram 多帳號行為的差異：** 在 Telegram 中，多帳號設定會刻意對所有帳號抑制根層級 `groups`，即使帳號沒有定義自己的 `groups` 也一樣，以防 bot 接收不屬於它的群組訊息。WhatsApp 不會套用此防護：根層級 `groups` 和根層級 `direct` 一律會由未定義帳號層級覆寫的帳號繼承，無論設定了多少帳號。在多帳號 WhatsApp 設定中，如果你想要每個帳號各自的群組或直接 prompts，請在每個帳號下明確定義完整 map，而不是依賴根層級預設值。
重要行為：
- `channels.whatsapp.groups` 同時是每個群組的設定映射，也是聊天層級的群組允許清單。在根層級或帳號作用域中，`groups["*"]` 都表示該作用域「允許所有群組」。
- 只有在你已經希望該作用域允許所有群組時，才加入通配群組 `systemPrompt`。如果你仍然只希望固定的一組群組 ID 符合資格，請不要使用 `groups["*"]` 作為提示預設值。請改為在每個明確列入允許清單的群組項目上重複該提示。
- 群組准入與寄件者授權是分開的檢查。`groups["*"]` 會擴大可進入群組處理的群組集合，但它本身不會授權這些群組中的每個寄件者。寄件者存取仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 分別控制。
- `channels.whatsapp.direct` 對 DM 沒有相同的副作用。`direct["*"]` 只會在 DM 已由 `dmPolicy` 加上 `allowFrom` 或配對儲存規則准入後，提供預設的直接聊天設定。
範例：
```json5
{
channels: {
whatsapp: {
groups: {
// Use only if all groups should be admitted at the root scope.
// Applies to all accounts that do not define their own groups map.
"*": { systemPrompt: "Default prompt for all groups." },
},
direct: {
// Applies to all accounts that do not define their own direct map.
"*": { systemPrompt: "Default prompt for all direct chats." },
},
accounts: {
work: {
groups: {
// This account defines its own groups, so root groups are fully
// replaced. To keep a wildcard, define "*" explicitly here too.
"120363406415684625@g.us": {
requireMention: false,
systemPrompt: "Focus on project management.",
},
// Use only if all groups should be admitted in this account.
"*": { systemPrompt: "Default prompt for work groups." },
},
direct: {
// This account defines its own direct map, so root direct entries are
// fully replaced. To keep a wildcard, define "*" explicitly here too.
"+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
"*": { systemPrompt: "Default prompt for work direct chats." },
},
},
},
},
},
}
```
## 設定參考指標
主要參考：
- [設定參考 - WhatsApp](/zh-TW/gateway/config-channels#whatsapp)
高訊號 WhatsApp 欄位：
- 存取：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
- 傳遞：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel`
- 多帳號：`accounts.<id>.enabled`、`accounts.<id>.authDir`、帳號層級覆寫
- 操作：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`、`web.whatsapp.*`
- 工作階段行為：`session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms.<id>.historyLimit`
- 提示：`groups.<id>.systemPrompt`、`groups["*"].systemPrompt`、`direct.<id>.systemPrompt`、`direct["*"].systemPrompt`
## 相關
- [配對](/zh-TW/channels/pairing)
- [群組](/zh-TW/channels/groups)
- [安全性](/zh-TW/gateway/security)
- [Channel 路由](/zh-TW/channels/channel-routing)
- [多代理路由](/zh-TW/concepts/multi-agent)
- [疑難排解](/zh-TW/channels/troubleshooting)

425
docs/zh-TW/channels/yuanbao.md Normal file
View File

@ -0,0 +1,425 @@
---
read_when:
- 你想要連接 Yuanbao 機器人
- 您正在設定 Yuanbao 頻道
summary: Yuanbao 機器人概覽、功能與設定
title: 元寶
x-i18n:
generated_at: "2026-04-30T02:50:19Z"
model: gpt-5.5
provider: openai
source_hash: d82b6d275ae8aa4cc5e62321772c5ba2b5044c6058be0d2e5215cdb1488118e9
source_path: channels/yuanbao.md
workflow: 16
---
# Yuanbao
Tencent Yuanbao 是 Tencent 的 AI 助理平台。OpenClaw 頻道 Plugin
透過 WebSocket 將 Yuanbao 機器人連接到 OpenClaw，讓它們可以透過私訊和群組聊天
與使用者互動。
**狀態：** 可用於生產環境，支援機器人私訊與群組聊天。WebSocket 是唯一支援的連線模式。
---
## 快速開始
> **需要 OpenClaw 2026.4.10 或以上版本。** 執行 `openclaw --version` 檢查。使用 `openclaw update` 升級。
<Steps>
<Step title="使用你的憑證新增 Yuanbao 頻道">
```bash
openclaw channels add --channel yuanbao --token "appKey:appSecret"
```
`--token` 值使用以冒號分隔的 `appKey:appSecret` 格式。你可以在 Yuanbao 應用程式的應用設定中建立機器人來取得這些資訊。
</Step>
<Step title="設定完成後，重新啟動 Gateway 以套用變更">
```bash
openclaw gateway restart
```
</Step>
</Steps>
### 互動式設定（替代方式）
你也可以使用互動式精靈：
```bash
openclaw channels login --channel yuanbao
```
依照提示輸入你的 App ID 和 App Secret。
---
## 存取控制
### 私訊
設定 `dmPolicy` 以控制誰可以私訊機器人：
- `"pairing"` — 未知使用者會收到配對碼；透過 CLI 核准
- `"allowlist"` — 只有列於 `allowFrom` 的使用者可以聊天
- `"open"` — 允許所有使用者（預設）
- `"disabled"` — 停用所有私訊
**核准配對請求：**
```bash
openclaw pairing list yuanbao
openclaw pairing approve yuanbao <CODE>
```
### 群組聊天
**提及要求** (`channels.yuanbao.requireMention`)：
- `true` — 需要 @提及（預設）
- `false` — 不需要 @提及即可回應
在群組聊天中回覆機器人的訊息會被視為隱含提及。
---
## 設定範例
### 使用開放私訊政策的基本設定
```json5
{
channels: {
yuanbao: {
appKey: "your_app_key",
appSecret: "your_app_secret",
dm: {
policy: "open",
},
},
},
}
```
### 將私訊限制為特定使用者
```json5
{
channels: {
yuanbao: {
appKey: "your_app_key",
appSecret: "your_app_secret",
dm: {
policy: "allowlist",
allowFrom: ["user_id_1", "user_id_2"],
},
},
},
}
```
### 停用群組中的 @提及要求
```json5
{
channels: {
yuanbao: {
requireMention: false,
},
},
}
```
### 最佳化外送訊息傳遞
```json5
{
channels: {
yuanbao: {
// 立即傳送每個片段，不進行緩衝
outboundQueueStrategy: "immediate",
},
},
}
```
### 調整合併文字策略
```json5
{
channels: {
yuanbao: {
outboundQueueStrategy: "merge-text",
minChars: 2800, // 緩衝直到達到此字元數
maxChars: 3000, // 超過此限制時強制分割
idleMs: 5000, // 閒置逾時後自動清空緩衝（毫秒）
},
},
}
```
---
## 常用命令
| 命令 | 說明 |
| ---------- | ---------------- |
| `/help` | 顯示可用命令 |
| `/status` | 顯示機器人狀態 |
| `/new` | 開始新工作階段 |
| `/stop` | 停止目前執行 |
| `/restart` | 重新啟動 OpenClaw |
| `/compact` | 壓縮工作階段內容 |
> Yuanbao 支援原生斜線命令選單。命令會在 Gateway 啟動時自動同步到平台。
---
## 疑難排解
### 機器人在群組聊天中沒有回應
1. 確認機器人已加入群組
2. 確認你有 @提及機器人（預設為必要）
3. 檢查記錄：`openclaw logs --follow`
### 機器人沒有接收訊息
1. 確認機器人已在 Yuanbao 應用程式中建立並核准
2. 確認 `appKey` 和 `appSecret` 已正確設定
3. 確認 Gateway 正在執行：`openclaw gateway status`
4. 檢查記錄：`openclaw logs --follow`
### 機器人傳送空白或備援回覆
1. 檢查 AI 模型是否回傳有效內容
2. 預設備援回覆是："暫時無法解答，你可以換個問題問問我哦"
3. 透過 `channels.yuanbao.fallbackReply` 自訂
### App Secret 洩漏
1. 在 YuanBao APP 中重設 App Secret
2. 更新你的設定中的值
3. 重新啟動 Gateway：`openclaw gateway restart`
---
## 進階設定
### 多個帳號
```json5
{
channels: {
yuanbao: {
defaultAccount: "main",
accounts: {
main: {
appKey: "key_xxx",
appSecret: "secret_xxx",
name: "Primary bot",
},
backup: {
appKey: "key_yyy",
appSecret: "secret_yyy",
name: "Backup bot",
enabled: false,
},
},
},
},
}
```
`defaultAccount` 控制當外送 API 未指定 `accountId` 時使用哪個帳號。
### 訊息限制
- `maxChars` — 單則訊息最大字元數（預設：`3000` 個字元）
- `mediaMaxMb` — 媒體上傳／下載限制（預設：`20` MB）
- `overflowPolicy` — 訊息超過限制時的行為：`"split"`（預設）或 `"stop"`
### 串流
Yuanbao 支援區塊層級串流輸出。啟用後，機器人會在產生文字時分段傳送。
```json5
{
channels: {
yuanbao: {
disableBlockStreaming: false, // 已啟用區塊串流（預設）
},
},
}
```
設定 `disableBlockStreaming: true` 以在單則訊息中傳送完整回覆。
### 群組聊天歷史內容
控制在群組聊天的 AI 內容中包含多少則歷史訊息：
```json5
{
channels: {
yuanbao: {
historyLimit: 100, // 預設：100，設為 0 可停用
},
},
}
```
### 回覆目標模式
控制機器人在群組聊天中回覆時如何引用訊息：
```json5
{
channels: {
yuanbao: {
replyToMode: "first", // "off" | "first" | "all"（預設："first"）
},
},
}
```
| 值 | 行為 |
| --------- | ---------------------------------- |
| `"off"` | 不引用回覆 |
| `"first"` | 每則傳入訊息只引用第一個回覆（預設） |
| `"all"` | 引用每個回覆 |
### Markdown 提示注入
預設情況下，機器人會在系統提示中注入指示，防止 AI 模型將整個回覆包在 markdown 程式碼區塊中。
```json5
{
channels: {
yuanbao: {
markdownHintEnabled: true, // 預設：true
},
},
}
```
### 偵錯模式
針對特定機器人 ID 啟用未清理的記錄輸出：
```json5
{
channels: {
yuanbao: {
debugBotIds: ["bot_user_id_1", "bot_user_id_2"],
},
},
}
```
### 多代理路由
使用 `bindings` 將 Yuanbao 私訊或群組路由到不同代理。
```json5
{
agents: {
list: [
{ id: "main" },
{ id: "agent-a", workspace: "/home/user/agent-a" },
{ id: "agent-b", workspace: "/home/user/agent-b" },
],
},
bindings: [
{
agentId: "agent-a",
match: {
channel: "yuanbao",
peer: { kind: "direct", id: "user_xxx" },
},
},
{
agentId: "agent-b",
match: {
channel: "yuanbao",
peer: { kind: "group", id: "group_zzz" },
},
},
],
}
```
路由欄位：
- `match.channel`: `"yuanbao"`
- `match.peer.kind`: `"direct"`（私訊）或 `"group"`（群組聊天）
- `match.peer.id`: 使用者 ID 或群組代碼
---
## 設定參考
完整設定：[Gateway 設定](/zh-TW/gateway/configuration)
| 設定 | 說明 | 預設 |
| ------------------------------------------ | ----------------------------------------- | -------------------------------------- |
| `channels.yuanbao.enabled` | 啟用／停用頻道 | `true` |
| `channels.yuanbao.defaultAccount` | 外送路由的預設帳號 | `default` |
| `channels.yuanbao.accounts.<id>.appKey` | App Key（用於簽署和產生票證） | — |
| `channels.yuanbao.accounts.<id>.appSecret` | App Secret（用於簽署） | — |
| `channels.yuanbao.accounts.<id>.token` | 預先簽署的權杖（略過自動票證簽署） | — |
| `channels.yuanbao.accounts.<id>.name` | 帳號顯示名稱 | — |
| `channels.yuanbao.accounts.<id>.enabled` | 啟用／停用特定帳號 | `true` |
| `channels.yuanbao.dm.policy` | 私訊政策 | `open` |
| `channels.yuanbao.dm.allowFrom` | 私訊允許清單（使用者 ID 清單） | — |
| `channels.yuanbao.requireMention` | 在群組中要求 @提及 | `true` |
| `channels.yuanbao.overflowPolicy` | 長訊息處理（`split` 或 `stop`） | `split` |
| `channels.yuanbao.replyToMode` | 群組回覆目標策略（`off`、`first`、`all`） | `first` |
| `channels.yuanbao.outboundQueueStrategy` | 外送策略（`merge-text` 或 `immediate`） | `merge-text` |
| `channels.yuanbao.minChars` | 合併文字：觸發傳送的最小字元數 | `2800` |
| `channels.yuanbao.maxChars` | 合併文字：每則訊息的最大字元數 | `3000` |
| `channels.yuanbao.idleMs` | 合併文字：自動清空緩衝前的閒置逾時（毫秒） | `5000` |
| `channels.yuanbao.mediaMaxMb` | 媒體大小限制（MB） | `20` |
| `channels.yuanbao.historyLimit` | 群組聊天歷史內容項目 | `100` |
| `channels.yuanbao.disableBlockStreaming` | 停用區塊層級串流輸出 | `false` |
| `channels.yuanbao.fallbackReply` | AI 未回傳內容時的備援回覆 | `暫時無法解答，你可以換個問題問問我哦` |
| `channels.yuanbao.markdownHintEnabled` | 注入 markdown 防包覆指示 | `true` |
| `channels.yuanbao.debugBotIds` | 偵錯允許清單機器人 ID（未清理記錄） | `[]` |
---
## 支援的訊息類型
### 接收
- ✅ 文字
- ✅ 圖片
- ✅ 檔案
- ✅ 音訊／語音
- ✅ 影片
- ✅ 貼圖／自訂表情符號
- ✅ 自訂元素（連結卡片等）
### 傳送
- ✅ 文字（支援 markdown）
- ✅ 圖片
- ✅ 檔案
- ✅ 音訊
- ✅ 影片
- ✅ 貼圖
### 對話串與回覆
- ✅ 引用回覆（可透過 `replyToMode` 設定）
- ❌ 對話串回覆（平台不支援）
---
## 相關
- [頻道概覽](/zh-TW/channels) — 所有支援的頻道
- [配對](/zh-TW/channels/pairing) — 私訊驗證和配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為和提及閘控
- [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型和強化

262
docs/zh-TW/channels/zalo.md Normal file
View File

@ -0,0 +1,262 @@
---
read_when:
- 處理 Zalo 功能或 Webhook
summary: Zalo 機器人支援狀態、功能與設定
title: Zalo
x-i18n:
generated_at: "2026-04-30T02:50:42Z"
model: gpt-5.5
provider: openai
source_hash: e79a4a27accc7f460bd3ae9c01e8f5f80e21a285af5d89b94bb9c89244a4438f
source_path: channels/zalo.md
workflow: 16
---
狀態：實驗性。支援 DM。下方的[功能](#capabilities)章節反映目前 Marketplace Bot 的行為。
## 內建 Plugin
Zalo 會以內建 Plugin 隨目前 OpenClaw 版本提供，因此一般封裝版本
不需要另外安裝。
如果你使用的是較舊版本，或自訂安裝排除了 Zalo，請在 npm 套件發布後安裝
目前版本的 npm 套件：
- 透過 CLI 安裝：`openclaw plugins install @openclaw/zalo`
- 或從原始碼 checkout 安裝：`openclaw plugins install ./path/to/local/zalo-plugin`
- 詳細資訊：[Plugins](/zh-TW/tools/plugin)
如果 npm 回報 OpenClaw 擁有的套件已被標記為 deprecated，請使用目前封裝的
OpenClaw 版本，或在較新的 npm 套件發布前使用本機 checkout 路徑。
## 快速設定（初學者）
1. 確認 Zalo Plugin 可用。
- 目前封裝的 OpenClaw 版本已經內建它。
- 較舊或自訂安裝可使用上方指令手動加入。
2. 設定權杖：
- Env：`ZALO_BOT_TOKEN=...`
- 或設定：`channels.zalo.accounts.default.botToken: "..."`。
3. 重新啟動 Gateway（或完成設定）。
4. DM 存取預設使用配對；第一次聯絡時核准配對碼。
最小設定：
```json5
{
channels: {
zalo: {
enabled: true,
accounts: {
default: {
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
},
},
}
```
## 這是什麼
Zalo 是一款以越南為主的通訊應用程式；它的 Bot API 讓 Gateway 能為 1:1 對話執行 Bot。
當你希望確定性地路由回 Zalo 來處理支援或通知時，它很適合使用。
此頁面反映目前 OpenClaw 對 **Zalo Bot Creator / Marketplace Bot** 的行為。
**Zalo Official Account (OA) Bot** 是不同的 Zalo 產品介面，行為可能不同。
- 由 Gateway 擁有的 Zalo Bot API 頻道。
- 確定性路由：回覆會回到 Zalo；模型不會選擇頻道。
- DM 共用代理程式的主要工作階段。
- 下方的[功能](#capabilities)章節顯示目前 Marketplace Bot 的支援情況。
## 設定（快速路徑）
### 1) 建立 Bot 權杖（Zalo Bot Platform）
1. 前往 [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) 並登入。
2. 建立新的 Bot 並設定其選項。
3. 複製完整 Bot 權杖（通常是 `numeric_id:secret`）。對於 Marketplace Bot，可用的執行階段權杖可能會在建立後出現在 Bot 的歡迎訊息中。
### 2) 設定權杖（env 或設定）
範例：
```json5
{
channels: {
zalo: {
enabled: true,
accounts: {
default: {
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
},
},
}
```
如果你之後移至支援群組的 Zalo Bot 介面，可以明確加入群組專屬設定，例如 `groupPolicy` 和 `groupAllowFrom`。關於目前 Marketplace Bot 的行為，請參閱[功能](#capabilities)。
Env 選項：`ZALO_BOT_TOKEN=...`（僅適用於預設帳號）。
多帳號支援：使用 `channels.zalo.accounts`，並為每個帳號設定權杖與選用的 `name`。
3. 重新啟動 Gateway。Zalo 會在解析到權杖（env 或設定）時啟動。
4. DM 存取預設為配對。Bot 首次被聯絡時請核准代碼。
## 運作方式（行為）
- 傳入訊息會被正規化為含媒體佔位符的共用頻道信封。
- 回覆一律路由回相同的 Zalo 聊天。
- 預設使用長輪詢；Webhook 模式可透過 `channels.zalo.webhookUrl` 使用。
## 限制
- 傳出文字會分塊為 2000 個字元（Zalo API 限制）。
- 媒體下載/上傳受 `channels.zalo.mediaMaxMb` 限制（預設 5）。
- 串流預設會被封鎖，因為 2000 字元限制讓串流用途較低。
## 存取控制（DM）
### DM 存取
- 預設：`channels.zalo.dmPolicy = "pairing"`。未知寄件者會收到配對碼；在核准前訊息會被忽略（代碼會在 1 小時後過期）。
- 透過以下方式核准：
- `openclaw pairing list zalo`
- `openclaw pairing approve zalo <CODE>`
- 配對是預設的權杖交換方式。詳細資訊：[Pairing](/zh-TW/channels/pairing)
- `channels.zalo.allowFrom` 接受數字使用者 ID（沒有可用的使用者名稱查詢）。
## 存取控制（群組）
對於 **Zalo Bot Creator / Marketplace Bot**，實務上群組支援不可用，因為 Bot 完全無法被加入群組。
這表示下列群組相關設定鍵存在於 schema 中，但 Marketplace Bot 無法使用：
- `channels.zalo.groupPolicy` 控制群組傳入處理：`open | allowlist | disabled`。
- `channels.zalo.groupAllowFrom` 限制哪些寄件者 ID 可在群組中觸發 Bot。
- 如果未設定 `groupAllowFrom`，Zalo 會回退到 `allowFrom` 進行寄件者檢查。
- 執行階段注意事項：如果完全缺少 `channels.zalo`，執行階段仍會為安全起見回退到 `groupPolicy="allowlist"`。
群組政策值（當你的 Bot 介面可使用群組存取時）如下：
- `groupPolicy: "disabled"` — 封鎖所有群組訊息。
- `groupPolicy: "open"` — 允許任何群組成員（由提及觸發）。
- `groupPolicy: "allowlist"` — 預設失敗關閉；只接受允許的寄件者。
如果你使用不同的 Zalo Bot 產品介面，並且已驗證群組行為可正常運作，請另外記錄，而不是假設它符合 Marketplace Bot 流程。
## 長輪詢 vs Webhook
- 預設：長輪詢（不需要公開 URL）。
- Webhook 模式：設定 `channels.zalo.webhookUrl` 和 `channels.zalo.webhookSecret`。
- Webhook 密鑰必須為 8-256 個字元。
- Webhook URL 必須使用 HTTPS。
- Zalo 會以 `X-Bot-Api-Secret-Token` 標頭傳送事件以供驗證。
- Gateway HTTP 會在 `channels.zalo.webhookPath` 處理 Webhook 請求（預設為 Webhook URL 路徑）。
- 請求必須使用 `Content-Type: application/json`（或 `+json` 媒體類型）。
- 重複事件（`event_name + message_id`）會在短暫的重放視窗中被忽略。
- 突發流量會依路徑/來源進行速率限制，且可能回傳 HTTP 429。
**注意：** 根據 Zalo API 文件，getUpdates（輪詢）與 Webhook 彼此互斥。
## 支援的訊息類型
如需快速支援概覽，請參閱[功能](#capabilities)。下方說明會在行為需要額外脈絡時補充細節。
- **文字訊息**：完整支援，並會以 2000 個字元分塊。
- **文字中的純 URL**：行為如同一般文字輸入。
- **連結預覽 / 豐富連結卡片**：請參閱[功能](#capabilities)中的 Marketplace Bot 狀態；它們未能可靠觸發回覆。
- **圖片訊息**：請參閱[功能](#capabilities)中的 Marketplace Bot 狀態；傳入圖片處理不可靠（顯示輸入指示器但沒有最終回覆）。
- **貼圖**：請參閱[功能](#capabilities)中的 Marketplace Bot 狀態。
- **語音訊息 / 音訊檔案 / 影片 / 一般檔案附件**：請參閱[功能](#capabilities)中的 Marketplace Bot 狀態。
- **不支援的類型**：會記錄（例如來自受保護使用者的訊息）。
## 功能
此表摘要目前 OpenClaw 中 **Zalo Bot Creator / Marketplace Bot** 的行為。
| 功能 | 狀態 |
| --------------------------- | --------------------------------------- |
| 直接訊息 | ✅ 支援 |
| 群組 | ❌ Marketplace Bot 不可用 |
| 媒體（傳入圖片） | ⚠️ 有限 / 請在你的環境中驗證 |
| 媒體（傳出圖片） | ⚠️ 尚未針對 Marketplace Bot 重新測試 |
| 文字中的純 URL | ✅ 支援 |
| 連結預覽 | ⚠️ Marketplace Bot 不可靠 |
| 回應 | ❌ 不支援 |
| 貼圖 | ⚠️ Marketplace Bot 沒有代理程式回覆 |
| 語音訊息 / 音訊 / 影片 | ⚠️ Marketplace Bot 沒有代理程式回覆 |
| 檔案附件 | ⚠️ Marketplace Bot 沒有代理程式回覆 |
| 執行緒 | ❌ 不支援 |
| 投票 | ❌ 不支援 |
| 原生命令 | ❌ 不支援 |
| 串流 | ⚠️ 已封鎖（2000 字元限制） |
## 傳送目標（CLI/Cron）
- 使用聊天 ID 作為目標。
- 範例：`openclaw message send --channel zalo --target 123456789 --message "hi"`。
## 疑難排解
**Bot 沒有回應：**
- 檢查權杖是否有效：`openclaw channels status --probe`
- 確認寄件者已核准（配對或 allowFrom）
- 檢查 Gateway 記錄：`openclaw logs --follow`
**Webhook 未收到事件：**
- 確認 Webhook URL 使用 HTTPS
- 驗證密鑰權杖為 8-256 個字元
- 確認 Gateway HTTP 端點可在設定的路徑上連線
- 檢查 getUpdates 輪詢未在執行（兩者彼此互斥）
## 設定參考（Zalo）
完整設定：[Configuration](/zh-TW/gateway/configuration)
扁平的頂層鍵（`channels.zalo.botToken`、`channels.zalo.dmPolicy` 及類似鍵）是舊版單帳號縮寫。新設定建議使用 `channels.zalo.accounts.<id>.*`。這兩種形式仍在此文件中記錄，因為它們存在於 schema 中。
提供者選項：
- `channels.zalo.enabled`：啟用/停用頻道啟動。
- `channels.zalo.botToken`：來自 Zalo Bot Platform 的 Bot 權杖。
- `channels.zalo.tokenFile`：從一般檔案路徑讀取權杖。符號連結會被拒絕。
- `channels.zalo.dmPolicy`：`pairing | allowlist | open | disabled`（預設：pairing）。
- `channels.zalo.allowFrom`：DM 允許清單（使用者 ID）。`open` 需要 `"*"`。精靈會要求輸入數字 ID。
- `channels.zalo.groupPolicy`：`open | allowlist | disabled`（預設：allowlist）。存在於設定中；關於目前 Marketplace Bot 的行為，請參閱[功能](#capabilities)與[存取控制（群組）](#access-control-groups)。
- `channels.zalo.groupAllowFrom`：群組寄件者允許清單（使用者 ID）。未設定時會回退到 `allowFrom`。
- `channels.zalo.mediaMaxMb`：傳入/傳出媒體上限（MB，預設 5）。
- `channels.zalo.webhookUrl`：啟用 Webhook 模式（需要 HTTPS）。
- `channels.zalo.webhookSecret`：Webhook 密鑰（8-256 個字元）。
- `channels.zalo.webhookPath`：Gateway HTTP 伺服器上的 Webhook 路徑。
- `channels.zalo.proxy`：API 請求的代理 URL。
多帳號選項：
- `channels.zalo.accounts.<id>.botToken`：每個帳號的權杖。
- `channels.zalo.accounts.<id>.tokenFile`：每個帳號的一般權杖檔案。符號連結會被拒絕。
- `channels.zalo.accounts.<id>.name`：顯示名稱。
- `channels.zalo.accounts.<id>.enabled`：啟用/停用帳號。
- `channels.zalo.accounts.<id>.dmPolicy`：每個帳號的 DM 政策。
- `channels.zalo.accounts.<id>.allowFrom`：每個帳號的允許清單。
- `channels.zalo.accounts.<id>.groupPolicy`：每個帳號的群組政策。存在於設定中；關於目前 Marketplace Bot 的行為，請參閱[功能](#capabilities)與[存取控制（群組）](#access-control-groups)。
- `channels.zalo.accounts.<id>.groupAllowFrom`：每個帳號的群組寄件者允許清單。
- `channels.zalo.accounts.<id>.webhookUrl`：每個帳號的 Webhook URL。
- `channels.zalo.accounts.<id>.webhookSecret`：每個帳號的 Webhook 密鑰。
- `channels.zalo.accounts.<id>.webhookPath`：每個帳號的 Webhook 路徑。
- `channels.zalo.accounts.<id>.proxy`：每個帳號的代理 URL。
## 相關
- [Channels Overview](/zh-TW/channels) — 所有支援的頻道
- [Pairing](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [Groups](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [Channel Routing](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [Security](/zh-TW/gateway/security) — 存取模型與強化

207
docs/zh-TW/channels/zalouser.md Normal file
View File

@ -0,0 +1,207 @@
---
read_when:
- 為 OpenClaw 設定 Zalo Personal
- 偵錯 Zalo Personal 登入或訊息流程
summary: 透過原生 zca-js（QR 登入）提供 Zalo 個人帳號支援、功能與設定
title: Zalo 個人版
x-i18n:
generated_at: "2026-04-30T02:50:51Z"
model: gpt-5.5
provider: openai
source_hash: 581a427f7fa37b0fa204f6b813c767eaa7af1f577baf2ac6ea3a31bf23ca6a49
source_path: channels/zalouser.md
workflow: 16
---
狀態：實驗性。此整合透過 OpenClaw 內的原生 `zca-js` 自動化一個**個人 Zalo 帳號**。
<Warning>
這是非官方整合，可能導致帳號遭停權或封鎖。請自行承擔使用風險。
</Warning>
## 內建 Plugin
Zalo Personal 在目前的 OpenClaw 發行版本中作為內建 Plugin 隨附，因此一般
封裝建置不需要另外安裝。
如果你使用的是較舊的建置，或是不包含 Zalo Personal 的自訂安裝，
請在有發布時安裝目前的 npm 套件：
- 透過 CLI 安裝：`openclaw plugins install @openclaw/zalouser`
- 或從原始碼 checkout 安裝：`openclaw plugins install ./path/to/local/zalouser-plugin`
- 詳細資訊：[Plugins](/zh-TW/tools/plugin)
如果 npm 回報 OpenClaw 擁有的套件已棄用，請使用目前封裝的
OpenClaw 建置，或使用本機 checkout 路徑，直到較新的 npm 套件
發布為止。
不需要外部 `zca`/`openzca` CLI 二進位檔。
## 快速設定（初學者）
1. 確認 Zalo Personal Plugin 可用。
- 目前封裝的 OpenClaw 發行版本已內建。
- 較舊/自訂安裝可使用上述命令手動加入。
2. 登入（QR，在 Gateway 機器上）：
- `openclaw channels login --channel zalouser`
- 使用 Zalo 行動應用程式掃描 QR code。
3. 啟用通道：
```json5
{
channels: {
zalouser: {
enabled: true,
dmPolicy: "pairing",
},
},
}
```
4. 重新啟動 Gateway（或完成設定）。
5. DM 存取預設使用配對；首次聯絡時核准配對碼。
## 它是什麼
- 完全透過 `zca-js` 在程序內執行。
- 使用原生事件監聽器接收傳入訊息。
- 直接透過 JS API 傳送回覆（文字/媒體/連結）。
- 專為無法使用 Zalo Bot API 的「個人帳號」使用情境設計。
## 命名
通道 id 是 `zalouser`，以明確表示這會自動化一個**個人 Zalo 使用者帳號**（非官方）。我們保留 `zalo` 給未來可能的官方 Zalo API 整合。
## 尋找 ID（目錄）
使用目錄 CLI 探索對象/群組及其 ID：
```bash
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"
```
## 限制
- 傳出文字會分段為約 2000 個字元（Zalo 用戶端限制）。
- 預設封鎖串流。
## 存取控制（DM）
`channels.zalouser.dmPolicy` 支援：`pairing | allowlist | open | disabled`（預設：`pairing`）。
`channels.zalouser.allowFrom` 接受使用者 ID 或名稱。設定期間，名稱會使用 Plugin 的程序內聯絡人查找解析為 ID。
透過以下命令核准：
- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser <code>`
## 群組存取（選用）
- 預設：`channels.zalouser.groupPolicy = "open"`（允許群組）。未設定時，使用 `channels.defaults.groupPolicy` 覆寫預設值。
- 使用以下設定限制為允許清單：
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups`（key 應為穩定的群組 ID；啟動時會在可能情況下將名稱解析為 ID）
- `channels.zalouser.groupAllowFrom`（控制允許群組中的哪些傳送者可以觸發 bot）
- 封鎖所有群組：`channels.zalouser.groupPolicy = "disabled"`。
- 設定精靈可以提示輸入群組允許清單。
- 啟動時，OpenClaw 會將允許清單中的群組/使用者名稱解析為 ID，並記錄對應關係。
- 群組允許清單比對預設僅使用 ID。除非啟用 `channels.zalouser.dangerouslyAllowNameMatching: true`，否則未解析的名稱會在驗證時被忽略。
- `channels.zalouser.dangerouslyAllowNameMatching: true` 是一種緊急相容模式，會重新啟用可變的群組名稱比對。
- 如果未設定 `groupAllowFrom`，執行階段會退回使用 `allowFrom` 進行群組傳送者檢查。
- 傳送者檢查同時套用於一般群組訊息和控制命令（例如 `/new`）。
範例：
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groupAllowFrom: ["1471383327500481391"],
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
### 群組提及閘控
- `channels.zalouser.groups.<group>.requireMention` 控制群組回覆是否需要提及。
- 解析順序：精確群組 id/名稱 -> 正規化群組 slug -> `*` -> 預設（`true`）。
- 這同時套用於允許清單群組和開放群組模式。
- 引用 bot 訊息會算作群組啟用的隱含提及。
- 已授權的控制命令（例如 `/new`）可以略過提及閘控。
- 當群組訊息因需要提及而被略過時，OpenClaw 會將它儲存為待處理群組歷史，並在下一則已處理的群組訊息中包含它。
- 群組歷史限制預設為 `messages.groupChat.historyLimit`（備援 `50`）。你可以使用 `channels.zalouser.historyLimit` 依帳號覆寫。
範例：
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"*": { allow: true, requireMention: true },
"Work Chat": { allow: true, requireMention: false },
},
},
},
}
```
## 多帳號
帳號會對應到 OpenClaw 狀態中的 `zalouser` 設定檔。範例：
```json5
{
channels: {
zalouser: {
enabled: true,
defaultAccount: "default",
accounts: {
work: { enabled: true, profile: "work" },
},
},
},
}
```
## 輸入狀態、反應與送達確認
- OpenClaw 會在送出回覆前傳送輸入中事件（盡力而為）。
- 訊息反應動作 `react` 在通道動作中支援 `zalouser`。
- 使用 `remove: true` 從訊息移除特定反應 emoji。
- 反應語意：[Reactions](/zh-TW/tools/reactions)
- 對於包含事件中繼資料的傳入訊息，OpenClaw 會傳送已送達 + 已讀確認（盡力而為）。
## 疑難排解
**登入無法保留：**
- `openclaw channels status --probe`
- 重新登入：`openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
**允許清單/群組名稱未解析：**
- 在 `allowFrom`/`groupAllowFrom`/`groups` 中使用數字 ID，或使用精確的朋友/群組名稱。
**從舊的 CLI 架構設定升級：**
- 移除任何舊的外部 `zca` 程序假設。
- 通道現在完全在 OpenClaw 中執行，不需要外部 CLI 二進位檔。
## 相關
- [通道概覽](/zh-TW/channels) — 所有支援的通道
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [通道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化

367
docs/zh-TW/ci.md Normal file
View File

File diff suppressed because one or more lines are too long

295
docs/zh-TW/cli/acp.md Normal file
View File

@ -0,0 +1,295 @@
---
read_when:
- 設定以 ACP 為基礎的 IDE 整合
- 偵錯 ACP 工作階段到 Gateway 的路由
summary: 執行 ACP 橋接器以支援 IDE 整合
title: ACP
x-i18n:
generated_at: "2026-04-30T02:50:59Z"
model: gpt-5.5
provider: openai
source_hash: 88b4d5de9e8e7464fd929ace0471af7d85afc94789c0c45a1f4a00d39b7871e1
source_path: cli/acp.md
workflow: 16
---
執行與 OpenClaw Gateway 通訊的 [代理程式用戶端通訊協定 (ACP)](https://agentclientprotocol.com/) 橋接器。
此命令會透過 stdio 為 IDE 使用 ACP，並透過 WebSocket 將提示轉送至 Gateway。它會讓 ACP 工作階段對應到 Gateway 工作階段金鑰。
`openclaw acp` 是由 Gateway 支援的 ACP 橋接器，不是完整的 ACP 原生編輯器執行階段。它專注於工作階段路由、提示傳遞，以及基本串流更新。
如果你想讓外部 MCP 用戶端直接與 OpenClaw 頻道對話通訊，而不是代管 ACP harness 工作階段，請改用 [`openclaw mcp serve`](/zh-TW/cli/mcp)。
## 這不是什麼
此頁面經常與 ACP harness 工作階段混淆。
`openclaw acp` 表示：
- OpenClaw 會作為 ACP 伺服器
- IDE 或 ACP 用戶端會連線到 OpenClaw
- OpenClaw 會將該工作轉送到 Gateway 工作階段
這不同於 [ACP 代理程式](/zh-TW/tools/acp-agents)，在後者中，OpenClaw 會透過 `acpx` 執行外部 harness，例如 Codex 或 Claude Code。
快速規則：
- 編輯器/用戶端想要以 ACP 與 OpenClaw 通訊：使用 `openclaw acp`
- OpenClaw 應以 ACP harness 啟動 Codex/Claude/Gemini：使用 `/acp spawn` 和 [ACP 代理程式](/zh-TW/tools/acp-agents)
## 相容性矩陣
| ACP 範圍 | 狀態 | 備註 |
| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initialize`, `newSession`, `prompt`, `cancel` | 已實作 | 透過 stdio 到 Gateway chat/send + abort 的核心橋接流程。 |
| `listSessions`, 斜線命令 | 已實作 | 工作階段清單會對照 Gateway 工作階段狀態運作；命令會透過 `available_commands_update` 公告。 |
| `loadSession` | 部分支援 | 會將 ACP 工作階段重新繫結到 Gateway 工作階段金鑰，並重放已儲存的使用者/助理文字歷史紀錄。工具/系統歷史紀錄尚未重建。 |
| 提示內容（`text`、內嵌 `resource`、圖片） | 部分支援 | 文字/資源會扁平化為聊天輸入；圖片會變成 Gateway 附件。 |
| 工作階段模式 | 部分支援 | 支援 `session/set_mode`，且橋接器會公開初始的 Gateway 支援工作階段控制項，用於思考層級、工具詳細程度、推理、用量明細，以及提升權限動作。更廣泛的 ACP 原生模式/設定介面仍不在範圍內。 |
| 工作階段資訊與用量更新 | 部分支援 | 橋接器會從快取的 Gateway 工作階段快照發出 `session_info_update` 和盡力而為的 `usage_update` 通知。用量為近似值，且只有在 Gateway 將 Token 總量標記為最新時才會傳送。 |
| 工具串流 | 部分支援 | 當 Gateway 工具引數/結果公開相關資訊時，`tool_call` / `tool_call_update` 事件會包含原始 I/O、文字內容，以及盡力而為的檔案位置。內嵌終端機和更豐富的差異原生輸出仍未公開。 |
| 每個工作階段的 MCP 伺服器（`mcpServers`） | 不支援 | 橋接模式會拒絕每個工作階段的 MCP 伺服器請求。請改在 OpenClaw gateway 或代理程式上設定 MCP。 |
| 用戶端檔案系統方法（`fs/read_text_file`, `fs/write_text_file`） | 不支援 | 橋接器不會呼叫 ACP 用戶端檔案系統方法。 |
| 用戶端終端機方法（`terminal/*`） | 不支援 | 橋接器不會建立 ACP 用戶端終端機，也不會透過工具呼叫串流終端機 ID。 |
| 工作階段計畫 / 思考串流 | 不支援 | 橋接器目前會發出輸出文字與工具狀態，而不是 ACP 計畫或思考更新。 |
## 已知限制
- `loadSession` 會重放已儲存的使用者與助理文字歷史紀錄，但不會重建歷史工具呼叫、系統通知，或更豐富的 ACP 原生事件類型。
- 如果多個 ACP 用戶端共用同一個 Gateway 工作階段金鑰，事件與取消路由會是盡力而為，而不是嚴格依用戶端隔離。當你需要乾淨的編輯器本機回合時，請偏好預設隔離的 `acp:<uuid>` 工作階段。
- Gateway 停止狀態會轉譯為 ACP 停止原因，但該對應的表達能力不如完整的 ACP 原生執行階段。
- 初始工作階段控制項目前會公開一組聚焦的 Gateway 旋鈕：思考層級、工具詳細程度、推理、用量明細，以及提升權限動作。模型選擇與 exec 主機控制尚未公開為 ACP 設定選項。
- `session_info_update` 和 `usage_update` 來自 Gateway 工作階段快照，而不是即時 ACP 原生執行階段計量。用量為近似值，不包含成本資料，且只有在 Gateway 將總 Token 資料標記為最新時才會發出。
- 工具跟隨資料是盡力而為。橋接器可以公開出現在已知工具引數/結果中的檔案路徑，但尚未發出 ACP 終端機或結構化檔案差異。
## 用法
```bash
openclaw acp
# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>
# Remote Gateway (token from file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Attach to an existing session key
openclaw acp --session agent:main:main
# Attach by label (must already exist)
openclaw acp --session-label "support inbox"
# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session
```
## ACP 用戶端（偵錯）
使用內建 ACP 用戶端，在沒有 IDE 的情況下對橋接器做基本檢查。
它會產生 ACP 橋接器，並讓你以互動方式輸入提示。
```bash
openclaw acp client
# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
```
權限模型（用戶端偵錯模式）：
- 自動核准以允許清單為基礎，且只適用於受信任的核心工具 ID。
- `read` 自動核准的範圍限於目前工作目錄（設定時為 `--cwd`）。
- ACP 只會自動核准狹窄的唯讀類別：作用中 cwd 底下的範圍限定 `read` 呼叫，以及唯讀搜尋工具（`search`、`web_search`、`memory_search`）。未知/非核心工具、超出範圍的讀取、可執行工具、控制平面工具、變更型工具，以及互動流程一律需要明確的提示核准。
- 伺服器提供的 `toolCall.kind` 會被視為不受信任的中繼資料（不是授權來源）。
- 此 ACP 橋接器政策獨立於 ACPX harness 權限。如果你透過 `acpx` 後端執行 OpenClaw，`plugins.entries.acpx.config.permissionMode=approve-all` 是該 harness 工作階段的緊急「yolo」開關。
## 如何使用
當 IDE（或其他用戶端）使用代理程式用戶端通訊協定，而你想讓它驅動 OpenClaw Gateway 工作階段時，請使用 ACP。
1. 確認 Gateway 正在執行（本機或遠端）。
2. 設定 Gateway 目標（設定或旗標）。
3. 將你的 IDE 指向透過 stdio 執行 `openclaw acp`。
範例設定（持久化）：
```bash
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
```
直接執行範例（不寫入設定）：
```bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
```
## 選擇代理程式
ACP 不會直接挑選代理程式。它會依 Gateway 工作階段金鑰路由。
使用代理程式範圍的工作階段金鑰來指定特定代理程式：
```bash
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
```
每個 ACP 工作階段會對應到單一 Gateway 工作階段金鑰。一個代理程式可以有許多工作階段；除非你覆寫金鑰或標籤，否則 ACP 預設會使用隔離的 `acp:<uuid>` 工作階段。
橋接模式不支援每個工作階段的 `mcpServers`。如果 ACP 用戶端在 `newSession` 或 `loadSession` 期間傳送它們，橋接器會回傳清楚的錯誤，而不是默默忽略。
如果你想讓 ACPX 支援的工作階段看見 OpenClaw Plugin 工具，或所選內建工具（例如 `cron`），請啟用 Gateway 端 ACPX MCP 橋接器，而不是嘗試傳遞每個工作階段的 `mcpServers`。請參閱 [ACP 代理程式](/zh-TW/tools/acp-agents-setup#plugin-tools-mcp-bridge) 和 [OpenClaw 工具 MCP 橋接器](/zh-TW/tools/acp-agents-setup#openclaw-tools-mcp-bridge)。
## 從 `acpx` 使用（Codex、Claude、其他 ACP 用戶端）
如果你想讓 Codex 或 Claude Code 這類程式碼代理程式透過 ACP 與你的 OpenClaw bot 通訊，請使用 `acpx` 及其內建的 `openclaw` 目標。
典型流程：
1. 執行 Gateway，並確認 ACP 橋接器能連到它。
2. 將 `acpx openclaw` 指向 `openclaw acp`。
3. 指定你想讓程式碼代理程式使用的 OpenClaw 工作階段金鑰。
範例：
```bash
# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."
# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
"Ask my OpenClaw work agent for recent context relevant to this repo."
```
如果你想讓 `acpx openclaw` 每次都指定特定 Gateway 和工作階段金鑰，請在 `~/.acpx/config.json` 中覆寫 `openclaw` 代理程式命令：
```json
{
"agents": {
"openclaw": {
"command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
}
}
}
```
對於 repo 本機的 OpenClaw checkout，請使用直接 CLI 進入點，而不是 dev runner，讓 ACP 串流保持乾淨。例如：
```bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
```
這是讓 Codex、Claude Code 或其他支援 ACP 的用戶端從 OpenClaw 代理程式擷取情境資訊，而不需要擷取終端機內容的最簡單方式。
## Zed 編輯器設定
在 `~/.config/zed/settings.json` 中新增自訂 ACP 代理程式（或使用 Zed 的設定 UI）：
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": ["acp"],
"env": {}
}
}
}
```
若要指定特定 Gateway 或代理：
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": [
"acp",
"--url",
"wss://gateway-host:18789",
"--token",
"<token>",
"--session",
"agent:design:main"
],
"env": {}
}
}
}
```
在 Zed 中，開啟代理面板並選取「OpenClaw ACP」以啟動對話串。
## 工作階段對應
預設情況下，ACP 工作階段會取得具有 `acp:` 前綴的隔離 Gateway 工作階段金鑰。
若要重複使用已知工作階段，請傳入工作階段金鑰或標籤：
- `--session <key>`：使用特定 Gateway 工作階段金鑰。
- `--session-label <label>`：依標籤解析現有工作階段。
- `--reset-session`：為該金鑰鑄造新的工作階段 ID（相同金鑰，新的記錄文字）。
如果你的 ACP 用戶端支援中繼資料，可以依工作階段覆寫：
```json
{
"_meta": {
"sessionKey": "agent:main:main",
"sessionLabel": "support inbox",
"resetSession": true
}
}
```
在 [/concepts/session](/zh-TW/concepts/session) 深入了解工作階段金鑰。
## 選項
- `--url <url>`：Gateway WebSocket URL（設定時預設為 gateway.remote.url）。
- `--token <token>`：Gateway 驗證權杖。
- `--token-file <path>`：從檔案讀取 Gateway 驗證權杖。
- `--password <password>`：Gateway 驗證密碼。
- `--password-file <path>`：從檔案讀取 Gateway 驗證密碼。
- `--session <key>`：預設工作階段金鑰。
- `--session-label <label>`：要解析的預設工作階段標籤。
- `--require-existing`：如果工作階段金鑰/標籤不存在則失敗。
- `--reset-session`：首次使用前重設工作階段金鑰。
- `--no-prefix-cwd`：不要在提示前加上工作目錄。
- `--provenance <off|meta|meta+receipt>`：包含 ACP 來源中繼資料或收據。
- `--verbose, -v`：將詳細記錄輸出到 stderr。
安全性注意事項：
- `--token` 和 `--password` 在某些系統上可能會顯示於本機處理程序清單中。
- 優先使用 `--token-file`/`--password-file` 或環境變數（`OPENCLAW_GATEWAY_TOKEN`、`OPENCLAW_GATEWAY_PASSWORD`）。
- Gateway 驗證解析會遵循其他 Gateway 用戶端使用的共用合約：
- 本機模式：env（`OPENCLAW_GATEWAY_*`）-> `gateway.auth.*` -> 僅在未設定 `gateway.auth.*` 時才回退到 `gateway.remote.*`（已設定但未解析的本機 SecretRefs 會封閉失敗）
- 遠端模式：`gateway.remote.*` 搭配 env/config 回退，依遠端優先順序規則處理
- `--url` 是覆寫安全的，且不會重複使用隱含的 config/env 憑證；請傳入明確的 `--token`/`--password`（或檔案變體）
- ACP 執行階段後端子處理程序會接收 `OPENCLAW_SHELL=acp`，可用於特定情境的 shell/profile 規則。
- `openclaw acp client` 會在產生的橋接處理程序上設定 `OPENCLAW_SHELL=acp-client`。
### `acp client` 選項
- `--cwd <dir>`：ACP 工作階段的工作目錄。
- `--server <command>`：ACP 伺服器命令（預設：`openclaw`）。
- `--server-args <args...>`：傳遞給 ACP 伺服器的額外引數。
- `--server-verbose`：在 ACP 伺服器上啟用詳細記錄。
- `--verbose, -v`：詳細用戶端記錄。
## 相關內容
- [CLI 參考](/zh-TW/cli)
- [ACP 代理](/zh-TW/tools/acp-agents)

76
docs/zh-TW/cli/agent.md Normal file
View File

@ -0,0 +1,76 @@
---
read_when:
- 你想要從指令碼執行一個代理程式回合（可選擇傳送回覆）
summary: '`openclaw agent` 的 CLI 參考（透過 Gateway 傳送一次代理程式回合）'
title: 代理
x-i18n:
generated_at: "2026-04-30T02:51:09Z"
model: gpt-5.5
provider: openai
source_hash: b77668949040933c5281f2f183e48cc2593d09252470483b9ae38dcffd13d071
source_path: cli/agent.md
workflow: 16
---
# `openclaw agent`
透過 Gateway 執行代理的一輪作業（使用 `--local` 可改用嵌入式）。
使用 `--agent <id>` 可直接指定已設定的代理。
至少傳入一個工作階段選擇器：
- `--to <dest>`
- `--session-id <id>`
- `--agent <id>`
相關：
- 代理傳送工具：[代理傳送](/zh-TW/tools/agent-send)
## 選項
- `-m, --message <text>`：必要的訊息內容
- `-t, --to <dest>`：用來衍生工作階段金鑰的收件者
- `--session-id <id>`：明確的工作階段 ID
- `--agent <id>`：代理 ID；覆寫路由繫結
- `--model <id>`：此執行的模型覆寫（`provider/model` 或模型 ID）
- `--thinking <level>`：代理思考層級（`off`、`minimal`、`low`、`medium`、`high`，以及提供者支援的自訂層級，例如 `xhigh`、`adaptive` 或 `max`）
- `--verbose <on|off>`：保留此工作階段的詳細程度
- `--channel <channel>`：傳遞通道；省略時使用主要工作階段通道
- `--reply-to <target>`：傳遞目標覆寫
- `--reply-channel <channel>`：傳遞通道覆寫
- `--reply-account <id>`：傳遞帳號覆寫
- `--local`：直接執行嵌入式代理（在 Plugin 登錄檔預載之後）
- `--deliver`：將回覆送回選取的通道/目標
- `--timeout <seconds>`：覆寫代理逾時時間（預設為 600 或設定值）
- `--json`：輸出 JSON
## 範例
```bash
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local
```
## 注意事項
- 當 Gateway 請求失敗時，Gateway 模式會退回使用嵌入式代理。使用 `--local` 可一開始就強制使用嵌入式執行。
- `--local` 仍會先預載 Plugin 登錄檔，因此 Plugin 提供的提供者、工具與通道在嵌入式執行期間仍可使用。
- `--local` 與嵌入式備援執行會被視為一次性執行。為該本機程序開啟的內建 MCP 回送資源與暖 Claude stdio 工作階段，會在回覆後被停用，因此腳本化呼叫不會讓本機子程序持續存活。
- Gateway 支援的執行會將 Gateway 擁有的 MCP 回送資源保留在執行中的 Gateway 程序下；較舊的用戶端可能仍會傳送歷史清理旗標，但 Gateway 會將其視為相容性無操作並接受。
- `--channel`、`--reply-channel` 和 `--reply-account` 會影響回覆傳遞，而不是工作階段路由。
- `--json` 會保留 stdout 供 JSON 回應使用。Gateway、Plugin 與嵌入式備援診斷會路由到 stderr，因此腳本可以直接剖析 stdout。
- 嵌入式備援 JSON 包含 `meta.transport: "embedded"` 和 `meta.fallbackFrom: "gateway"`，讓腳本可區分備援執行與 Gateway 執行。
- 如果 Gateway 接受代理執行，但 CLI 等待最終回覆逾時，嵌入式備援會使用新的明確 `gateway-fallback-*` 工作階段/執行 ID，並回報 `meta.fallbackReason: "gateway_timeout"` 加上備援工作階段欄位。這可避免與 Gateway 擁有的逐字稿鎖競爭，或無聲地取代原始路由對話工作階段。
- 當此命令觸發 `models.json` 重新產生時，SecretRef 管理的提供者憑證會以非機密標記保存（例如環境變數名稱、`secretref-env:ENV_VAR_NAME` 或 `secretref-managed`），而不是解析後的純文字機密。
- 標記寫入以來源為權威：OpenClaw 會保存來自作用中來源設定快照的標記，而不是來自解析後執行階段機密值的標記。
## 相關
- [CLI 參考](/zh-TW/cli)
- [代理執行階段](/zh-TW/concepts/agent)

238
docs/zh-TW/cli/agents.md Normal file
View File

@ -0,0 +1,238 @@
---
read_when:
- 你需要多個隔離的代理（工作區 + 路由 + 身分驗證）
summary: '`openclaw agents` 的 CLI 參考文件（list/add/delete/bindings/bind/unbind/set identity）'
title: 代理
x-i18n:
generated_at: "2026-04-30T02:51:13Z"
model: gpt-5.5
provider: openai
source_hash: 46742a890a57cb1035a053f14fe574044e4a3d7dcc04812cd11c633bd808819b
source_path: cli/agents.md
workflow: 16
---
# `openclaw agents`
管理隔離的代理（工作區 + 驗證 + 路由）。
相關：
- [多代理路由](/zh-TW/concepts/multi-agent)
- [代理工作區](/zh-TW/concepts/agent-workspace)
- [Skills 設定](/zh-TW/tools/skills-config)：Skills 可見性設定。
## 範例
```bash
openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work
```
## 路由綁定
使用路由綁定，將傳入的頻道流量固定到特定代理。
如果你也想讓每個代理有不同的可見 Skills，請在 `openclaw.json` 中設定 `agents.defaults.skills` 和 `agents.list[].skills`。請參閱 [Skills 設定](/zh-TW/tools/skills-config)和[設定參考](/zh-TW/gateway/config-agents#agents-defaults-skills)。
列出綁定：
```bash
openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json
```
新增綁定：
```bash
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
```
如果省略 `accountId`（`--bind <channel>`），OpenClaw 會在可用時從頻道預設值和 Plugin 設定 Hook 解析它。
如果對 `bind` 或 `unbind` 省略 `--agent`，OpenClaw 會以目前的預設代理作為目標。
### 綁定範圍行為
- 沒有 `accountId` 的綁定只會符合頻道的預設帳號。
- `accountId: "*"` 是整個頻道的備援（所有帳號），且比明確帳號綁定更不精確。
- 如果同一個代理已有符合的頻道綁定且沒有 `accountId`，而你稍後使用明確或已解析的 `accountId` 綁定，OpenClaw 會就地升級該現有綁定，而不是新增重複項目。
範例：
```bash
# initial channel-only binding
openclaw agents bind --agent work --bind telegram
# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:ops
```
升級後，該綁定的路由範圍會限定為 `telegram:ops`。如果你也想要預設帳號路由，請明確新增它（例如 `--bind telegram:default`）。
移除綁定：
```bash
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all
```
`unbind` 接受 `--all` 或一個以上的 `--bind` 值，但不能兩者同時使用。
## 命令介面
### `agents`
執行沒有子命令的 `openclaw agents` 等同於 `openclaw agents list`。
### `agents list`
選項：
- `--json`
- `--bindings`：包含完整路由規則，而不只每個代理的計數/摘要
### `agents add [name]`
選項：
- `--workspace <dir>`
- `--model <id>`
- `--agent-dir <dir>`
- `--bind <channel[:accountId]>`（可重複）
- `--non-interactive`
- `--json`
注意事項：
- 傳入任何明確的新增旗標會將命令切換到非互動路徑。
- 非互動模式同時需要代理名稱和 `--workspace`。
- `main` 是保留字，不能作為新的代理 ID。
- 在互動模式中，驗證植入只會複製可攜式靜態設定檔
（預設為 `api_key` 和靜態 `token`）。OAuth 重新整理權杖設定檔仍然
只能透過從實際 `main` 代理儲存區的讀取穿透繼承來使用。
如果設定的預設代理不是 `main`，請為新代理的 OAuth
設定檔分別登入。
### `agents bindings`
選項：
- `--agent <id>`
- `--json`
### `agents bind`
選項：
- `--agent <id>`（預設為目前的預設代理）
- `--bind <channel[:accountId]>`（可重複）
- `--json`
### `agents unbind`
選項：
- `--agent <id>`（預設為目前的預設代理）
- `--bind <channel[:accountId]>`（可重複）
- `--all`
- `--json`
### `agents delete <id>`
選項：
- `--force`
- `--json`
注意事項：
- `main` 無法刪除。
- 沒有 `--force` 時，需要互動式確認。
- 工作區、代理狀態和工作階段逐字記錄目錄會移到垃圾桶，而不是永久刪除。
- 如果另一個代理的工作區是相同路徑、位於此工作區內，或包含此工作區，
工作區會保留，且 `--json` 會回報 `workspaceRetained`、
`workspaceRetainedReason` 和 `workspaceSharedWith`。
## 身分檔案
每個代理工作區可以在工作區根目錄包含 `IDENTITY.md`：
- 範例路徑：`~/.openclaw/workspace/IDENTITY.md`
- `set-identity --from-identity` 會從工作區根目錄（或明確的 `--identity-file`）讀取
頭像路徑會相對於工作區根目錄解析。
## 設定身分
`set-identity` 會將欄位寫入 `agents.list[].identity`：
- `name`
- `theme`
- `emoji`
- `avatar`（工作區相對路徑、http(s) URL 或資料 URI）
選項：
- `--agent <id>`
- `--workspace <dir>`
- `--identity-file <path>`
- `--from-identity`
- `--name <name>`
- `--theme <theme>`
- `--emoji <emoji>`
- `--avatar <value>`
- `--json`
注意事項：
- 可以使用 `--agent` 或 `--workspace` 選取目標代理。
- 如果你依賴 `--workspace`，且多個代理共用該工作區，命令會失敗並要求你傳入 `--agent`。
- 未提供明確身分欄位時，命令會從 `IDENTITY.md` 讀取身分資料。
從 `IDENTITY.md` 載入：
```bash
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
```
明確覆寫欄位：
```bash
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
```
設定範例：
```json5
{
agents: {
list: [
{
id: "main",
identity: {
name: "OpenClaw",
theme: "space lobster",
emoji: "🦞",
avatar: "avatars/openclaw.png",
},
},
],
},
}
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [多代理路由](/zh-TW/concepts/multi-agent)
- [代理工作區](/zh-TW/concepts/agent-workspace)

197
docs/zh-TW/cli/approvals.md Normal file
View File

@ -0,0 +1,197 @@
---
read_when:
- 您想要從 CLI 編輯執行核准
- 您需要在 Gateway 或 Node 主機上管理允許清單
summary: 適用於 `openclaw approvals` 和 `openclaw exec-policy` 的 CLI 參考
title: 核准
x-i18n:
generated_at: "2026-04-30T02:51:29Z"
model: gpt-5.5
provider: openai
source_hash: 7403f0e35616db5baf3d1564c8c405b3883fc3e5032da9c6a19a32dba8c5fb7d
source_path: cli/approvals.md
workflow: 16
---
# `openclaw approvals`
管理 **本機主機**、**Gateway 主機** 或 **Node 主機** 的 exec 核准。
預設情況下，指令會以磁碟上的本機核准檔案為目標。使用 `--gateway` 以 Gateway 為目標，或使用 `--node` 以特定 Node 為目標。
別名：`openclaw exec-approvals`
相關：
- Exec 核准：[Exec 核准](/zh-TW/tools/exec-approvals)
- Node：[Node](/zh-TW/nodes)
## `openclaw exec-policy`
`openclaw exec-policy` 是一個本機便利指令，可一步保持要求的
`tools.exec.*` 設定與本機主機核准檔案一致。
在你想要執行以下操作時使用它：
- 檢查本機要求的政策、主機核准檔案，以及有效合併結果
- 套用本機預設集，例如 YOLO 或全部拒絕
- 同步本機 `tools.exec.*` 與本機 `~/.openclaw/exec-approvals.json`
範例：
```bash
openclaw exec-policy show
openclaw exec-policy show --json
openclaw exec-policy preset yolo
openclaw exec-policy preset cautious --json
openclaw exec-policy set --host gateway --security full --ask off --ask-fallback full
```
輸出模式：
- 無 `--json`：列印人類可讀的表格檢視
- `--json`：列印機器可讀的結構化輸出
目前範圍：
- `exec-policy` **僅限本機**
- 它會一起更新本機設定檔與本機核准檔案
- 它**不會**將政策推送到 Gateway 主機或 Node 主機
- 此指令會拒絕 `--host node`，因為 Node exec 核准會在執行階段從 Node 擷取，而且必須改由以 Node 為目標的核准指令管理
- `openclaw exec-policy show` 會將 `host=node` 範圍標示為執行階段由 Node 管理，而不是從本機核准檔案推導有效政策
如果你需要直接編輯遠端主機核准，請繼續使用 `openclaw approvals set --gateway`
或 `openclaw approvals set --node <id|name|ip>`。
## 常用指令
```bash
openclaw approvals get
openclaw approvals get --node <id|name|ip>
openclaw approvals get --gateway
```
`openclaw approvals get` 現在會顯示本機、Gateway 與 Node 目標的有效 exec 政策：
- 要求的 `tools.exec` 政策
- 主機核准檔案政策
- 套用優先順序規則後的有效結果
優先順序是刻意設計的：
- 主機核准檔案是可強制執行的事實來源
- 要求的 `tools.exec` 政策可以縮小或擴大意圖，但有效結果仍然由主機規則推導
- `--node` 會將 Node 主機核准檔案與 Gateway `tools.exec` 政策結合，因為兩者在執行階段仍然適用
- 如果 Gateway 設定無法使用，CLI 會退回使用 Node 核准快照，並註明無法計算最終執行階段政策
## 從檔案取代核准
```bash
openclaw approvals set --file ./exec-approvals.json
openclaw approvals set --stdin <<'EOF'
{ version: 1, defaults: { security: "full", ask: "off" } }
EOF
openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
openclaw approvals set --gateway --file ./exec-approvals.json
```
`set` 接受 JSON5，不只接受嚴格 JSON。請使用 `--file` 或 `--stdin` 其中之一，不要同時使用兩者。
##「永不提示」/ YOLO 範例
對於不應因 exec 核准而停止的主機，請將主機核准預設值設為 `full` + `off`：
```bash
openclaw approvals set --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
Node 變體：
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
這只會變更**主機核准檔案**。若要讓要求的 OpenClaw 政策保持一致，另請設定：
```bash
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
```
此範例中為何使用 `tools.exec.host=gateway`：
- `host=auto` 仍然表示「可用時使用沙盒，否則使用 Gateway」。
- YOLO 關乎核准，而不是路由。
- 如果即使已設定沙盒仍想要使用主機 exec，請使用 `gateway` 或 `/exec host=gateway` 明確指定主機選擇。
這符合目前的主機預設 YOLO 行為。如果你想要核准，請收緊它。
本機捷徑：
```bash
openclaw exec-policy preset yolo
```
該本機捷徑會同時更新要求的本機 `tools.exec.*` 設定與
本機核准預設值。其意圖等同於上方的手動兩步驟
設定，但僅適用於本機。
## 允許清單輔助工具
```bash
openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
openclaw approvals allowlist remove "~/Projects/**/bin/rg"
```
## 常用選項
`get`、`set` 與 `allowlist add|remove` 全都支援：
- `--node <id|name|ip>`
- `--gateway`
- 共用 Node RPC 選項：`--url`、`--token`、`--timeout`、`--json`
目標指定注意事項：
- 沒有目標旗標表示使用磁碟上的本機核准檔案
- `--gateway` 以 Gateway 主機核准檔案為目標
- `--node` 在解析 ID、名稱、IP 或 ID 前綴後，以一個 Node 主機為目標
`allowlist add|remove` 也支援：
- `--agent <id>`（預設為 `*`）
## 注意事項
- `--node` 使用與 `openclaw nodes` 相同的解析器（ID、名稱、IP 或 ID 前綴）。
- `--agent` 預設為 `"*"`，會套用至所有代理。
- Node 主機必須通告 `system.execApprovals.get/set`（macOS app 或 headless Node 主機）。
- 核准檔案會依每個主機儲存在 `~/.openclaw/exec-approvals.json`。
## 相關
- [CLI 參考](/zh-TW/cli)
- [Exec 核准](/zh-TW/tools/exec-approvals)

92
docs/zh-TW/cli/backup.md Normal file
View File

@ -0,0 +1,92 @@
---
read_when:
- 您想要一個用於本機 OpenClaw 狀態的一流備份封存檔
- 你想在重設或解除安裝前預覽會包含哪些路徑
summary: '`openclaw backup` 的 CLI 參考 (建立本機備份封存檔)'
title: 備份
x-i18n:
generated_at: "2026-04-30T02:51:38Z"
model: gpt-5.5
provider: openai
source_hash: 5c16f953bb32a1613181448f0e4c6ba8777383bce95bddc856dc7e1c3afe8550
source_path: cli/backup.md
workflow: 16
---
# `openclaw backup`
建立 OpenClaw 狀態、設定、授權設定檔、頻道/供應者憑證、工作階段，以及選擇性工作區的本機備份封存檔。
```bash
openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
```
## 注意事項
- 封存檔包含一個 `manifest.json` 檔案，其中含有解析後的來源路徑與封存檔配置。
- 預設輸出是在目前工作目錄中建立具時間戳記的 `.tar.gz` 封存檔。
- 如果目前工作目錄位於已備份的來源樹內，OpenClaw 會改用你的家目錄作為預設封存檔位置。
- 永遠不會覆寫既有封存檔。
- 來源狀態/工作區樹內的輸出路徑會被拒絕，以避免自我包含。
- `openclaw backup verify <archive>` 會驗證封存檔只包含一個根資訊清單、拒絕穿越式封存檔路徑，並檢查資訊清單宣告的每個承載內容都存在於 tarball 中。
- `openclaw backup create --verify` 會在寫入封存檔後立即執行該驗證。
- `openclaw backup create --only-config` 只會備份作用中的 JSON 設定檔。
## 會備份哪些內容
`openclaw backup create` 會從你的本機 OpenClaw 安裝規劃備份來源：
- OpenClaw 本機狀態解析器回傳的狀態目錄，通常是 `~/.openclaw`
- 作用中的設定檔路徑
- 當解析後的 `credentials/` 目錄存在於狀態目錄之外時
- 從目前設定中探索到的工作區目錄，除非你傳入 `--no-include-workspace`
模型授權設定檔已經是狀態目錄的一部分，位於
`agents/<agentId>/agent/auth-profiles.json` 下，因此通常會由狀態備份項目涵蓋。
如果你使用 `--only-config`，OpenClaw 會略過狀態、憑證目錄與工作區探索，只封存作用中的設定檔路徑。
OpenClaw 會在建立封存檔前將路徑正規化。如果設定、憑證目錄或工作區已位於狀態目錄內，它們不會被重複成個別的頂層備份來源。缺少的路徑會被略過。
封存檔承載內容會儲存那些來源樹中的檔案內容，而內嵌的 `manifest.json` 會記錄解析後的絕對來源路徑，以及每個資產使用的封存檔配置。
狀態目錄 `extensions/` 樹下已安裝的 Plugin 原始碼與資訊清單檔案會被包含，但其巢狀 `node_modules/` 相依性樹會被略過。這些相依性是可重建的安裝成品；還原封存檔後，當還原的 Plugin 回報缺少相依性時，請使用 `openclaw plugins update <id>`，或使用 `openclaw plugins install <spec> --force` 重新安裝 Plugin。
## 無效設定行為
`openclaw backup` 會刻意略過一般設定預檢，讓它仍能在復原期間提供協助。由於工作區探索取決於有效設定，現在當設定檔存在但無效，且工作區備份仍啟用時，`openclaw backup create` 會快速失敗。
如果你在這種情況下仍想要部分備份，請重新執行：
```bash
openclaw backup create --no-include-workspace
```
這會將狀態、設定與外部憑證目錄保留在範圍內，同時完全略過工作區探索。
如果你只需要設定檔本身的副本，`--only-config` 在設定格式錯誤時也能運作，因為它不依賴解析設定來進行工作區探索。
## 大小與效能
OpenClaw 不會強制內建的最大備份大小或單檔大小限制。
實務限制來自本機機器與目的地檔案系統：
- 暫存封存檔寫入加上最終封存檔所需的可用空間
- 走訪大型工作區樹並將其壓縮成 `.tar.gz` 所需的時間
- 如果你使用 `openclaw backup create --verify` 或執行 `openclaw backup verify`，重新掃描封存檔所需的時間
- 目的地路徑的檔案系統行為。OpenClaw 偏好採用不覆寫的硬連結發布步驟，並在不支援硬連結時退回到獨占複製
大型工作區通常是封存檔大小的主要因素。如果你想要較小或較快的備份，請使用 `--no-include-workspace`。
若要取得最小的封存檔，請使用 `--only-config`。
## 相關
- [CLI 參考](/zh-TW/cli)

270
docs/zh-TW/cli/browser.md Normal file
View File

@ -0,0 +1,270 @@
---
read_when:
- 你使用 `openclaw browser`，並想要常見任務的範例
- 你想透過 Node 主機控制在另一台機器上執行的瀏覽器
- 你想透過 Chrome MCP 連接到本機已登入的 Chrome
summary: '`openclaw browser` 的 CLI 參考（生命週期、設定檔、分頁、動作、狀態和偵錯）'
title: 瀏覽器
x-i18n:
generated_at: "2026-04-30T02:51:51Z"
model: gpt-5.5
provider: openai
source_hash: c7b5112c61e8289ab6a02bc30c9aefe640c053271f82197c0ee810b4a5efa580
source_path: cli/browser.md
workflow: 16
---
# `openclaw browser`
管理 OpenClaw 的瀏覽器控制介面，並執行瀏覽器動作（生命週期、設定檔、分頁、快照、螢幕截圖、導覽、輸入、狀態模擬與除錯）。
相關：
- 瀏覽器工具 + API：[瀏覽器工具](/zh-TW/tools/browser)
## 常用旗標
- `--url <gatewayWsUrl>`：Gateway WebSocket URL（預設為設定值）。
- `--token <token>`：Gateway 權杖（如果需要）。
- `--timeout <ms>`：請求逾時（ms）。
- `--expect-final`：等待最終 Gateway 回應。
- `--browser-profile <name>`：選擇瀏覽器設定檔（預設來自設定）。
- `--json`：機器可讀輸出（支援時）。
## 快速開始（本機）
```bash
openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
代理可以使用 `browser({ action: "doctor" })` 執行相同的就緒檢查。
## 快速疑難排解
如果 `start` 失敗並出現 `not reachable after start`，請先排查 CDP 就緒狀態。如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失敗，表示瀏覽器控制平面正常，失敗通常是導覽 SSRF 政策造成的。
最小序列：
```bash
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
```
詳細指引：[瀏覽器疑難排解](/zh-TW/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
## 生命週期
```bash
openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile
```
注意：
- `doctor --deep` 會新增即時快照探測。當基本 CDP 就緒狀態為綠燈，但你想證明目前分頁可被檢查時，這很有用。
- 對於 `attachOnly` 和遠端 CDP 設定檔，即使 OpenClaw 並未自行啟動瀏覽器程序，`openclaw browser stop` 也會關閉作用中的控制工作階段，並清除暫時的模擬覆寫。
- 對於本機受管理設定檔，`openclaw browser stop` 會停止產生的瀏覽器程序。
- `openclaw browser start --headless` 只套用於該次啟動請求，且只在 OpenClaw 啟動本機受管理瀏覽器時套用。它不會重寫 `browser.headless` 或設定檔設定，對已在執行的瀏覽器也不會有任何作用。
- 在沒有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主機上，除非 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless=false` 或 `browser.profiles.<name>.headless=false` 明確要求可見瀏覽器，否則本機受管理設定檔會自動以無頭模式執行。
## 如果命令不存在
如果 `openclaw browser` 是未知命令，請檢查 `~/.openclaw/openclaw.json` 中的 `plugins.allow`。
當 `plugins.allow` 存在時，除非設定已經有根層級 `browser` 區塊，否則請明確列出內建瀏覽器 Plugin：
```json5
{
plugins: {
allow: ["telegram", "browser"],
},
}
```
明確的根層級 `browser` 區塊，例如 `browser.enabled=true` 或 `browser.profiles.<name>`，也會在限制性的 Plugin 允許清單下啟用內建瀏覽器 Plugin。
相關：[瀏覽器工具](/zh-TW/tools/browser#missing-browser-command-or-tool)
## 設定檔
設定檔是具名的瀏覽器路由設定。實務上：
- `openclaw`：啟動或附加到專用的 OpenClaw 受管理 Chrome 執行個體（隔離的使用者資料目錄）。
- `user`：透過 Chrome DevTools MCP 控制你現有的已登入 Chrome 工作階段。
- 自訂 CDP 設定檔：指向本機或遠端 CDP 端點。
```bash
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
```
使用特定設定檔：
```bash
openclaw browser --browser-profile work tabs
```
## 分頁
```bash
openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw browser close t1
```
`tabs` 會先回傳 `suggestedTargetId`，接著是穩定的 `tabId`（例如 `t1`）、選用標籤，以及原始 `targetId`。代理應將 `suggestedTargetId` 傳回 `focus`、`close`、快照和動作。你可以使用 `open --label`、`tab new --label` 或 `tab label` 指派標籤；標籤、分頁 ID、原始目標 ID，以及唯一的目標 ID 前綴都可接受。當 Chromium 在導覽或表單送出期間替換底層原始目標時，如果 OpenClaw 能證明匹配，它會將穩定的 `tabId`/標籤保留在替換後的分頁上。原始目標 ID 仍然易變；請優先使用 `suggestedTargetId`。
## 快照 / 螢幕截圖 / 動作
快照：
```bash
openclaw browser snapshot
openclaw browser snapshot --urls
```
螢幕截圖：
```bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw browser screenshot --labels
```
注意：
- `--full-page` 僅適用於頁面擷取；不能與 `--ref` 或 `--element` 搭配使用。
- `existing-session` / `user` 設定檔支援頁面螢幕截圖，以及來自快照輸出的 `--ref` 螢幕截圖，但不支援 CSS `--element` 螢幕截圖。
- `--labels` 會在螢幕截圖上疊加目前快照參照。
- `snapshot --urls` 會將探索到的連結目的地附加到 AI 快照，讓代理可以選擇直接導覽目標，而不是只根據連結文字猜測。
導覽/點擊/輸入（以參照為基礎的 UI 自動化）：
```bash
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
```
當 OpenClaw 能證明替換分頁時，動作回應會在動作觸發的頁面替換後回傳目前的原始 `targetId`。腳本仍應儲存並傳遞 `suggestedTargetId`/標籤，以支援長時間執行的工作流程。
檔案 + 對話框輔助工具：
```bash
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
```
受管理 Chrome 設定檔會將一般點擊觸發的下載儲存到 OpenClaw 下載目錄（預設為 `/tmp/openclaw/downloads`，或設定的暫存根目錄）。當代理需要等待特定檔案並回傳其路徑時，請使用 `waitfordownload` 或 `download`；這些明確的等待器會擁有下一個下載。
## 狀態與儲存
視窗大小 + 模擬：
```bash
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
```
Cookie + 儲存：
```bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear
```
## 除錯
```bash
openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip
```
## 透過 MCP 使用現有 Chrome
使用內建的 `user` 設定檔，或建立你自己的 `existing-session` 設定檔：
```bash
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser --browser-profile chrome-live tabs
```
此路徑僅適用於主機。對於 Docker、無頭伺服器、Browserless 或其他遠端設定，請改用 CDP 設定檔。
目前 existing-session 限制：
- 由快照驅動的動作使用參照，而不是 CSS 選擇器
- 當呼叫端省略 `timeoutMs` 時，`browser.actionTimeoutMs` 會將支援的 `act` 請求預設為 60000 ms；每次呼叫的 `timeoutMs` 仍會優先。
- `click` 僅限左鍵點擊
- `type` 不支援 `slowly=true`
- `press` 不支援 `delayMs`
- `hover`、`scrollintoview`、`drag`、`select`、`fill` 和 `evaluate` 會拒絕每次呼叫的逾時覆寫
- `select` 僅支援一個值
- 不支援 `wait --load networkidle`
- 檔案上傳需要 `--ref` / `--input-ref`，不支援 CSS `--element`，且目前一次支援一個檔案
- 對話框掛鉤不支援 `--timeout`
- 螢幕截圖支援頁面擷取和 `--ref`，但不支援 CSS `--element`
- `responsebody`、下載攔截、PDF 匯出和批次動作仍需要受管理瀏覽器或原始 CDP 設定檔
## 遠端瀏覽器控制（Node 主機代理）
如果 Gateway 與瀏覽器在不同機器上執行，請在有 Chrome/Brave/Edge/Chromium 的機器上執行 **Node 主機**。Gateway 會將瀏覽器動作代理到該 Node（不需要獨立的瀏覽器控制伺服器）。
使用 `gateway.nodes.browser.mode` 控制自動路由，並在有多個 Node 連線時使用 `gateway.nodes.browser.node` 固定到特定 Node。
安全性 + 遠端設定：[瀏覽器工具](/zh-TW/tools/browser)、[遠端存取](/zh-TW/gateway/remote)、[Tailscale](/zh-TW/gateway/tailscale)、[安全性](/zh-TW/gateway/security)
## 相關
- [CLI 參考](/zh-TW/cli)
- [瀏覽器](/zh-TW/tools/browser)

146
docs/zh-TW/cli/channels.md Normal file
View File

@ -0,0 +1,146 @@
---
read_when:
- 你想要新增/移除頻道帳號（WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix）
- 你想檢查通道狀態或追蹤通道日誌
summary: CLI 參考資料：`openclaw channels`（帳戶、狀態、登入/登出、日誌）
title: 通道
x-i18n:
generated_at: "2026-04-30T02:51:52Z"
model: gpt-5.5
provider: openai
source_hash: 6fc3c5983114c17e0e7284450aa161b658312c05864db65e09d6d764e357cd1f
source_path: cli/channels.md
workflow: 16
---
# `openclaw channels`
管理 Gateway 上的聊天頻道帳號及其執行階段狀態。
相關文件：
- 頻道指南：[頻道](/zh-TW/channels)
- Gateway 設定：[設定](/zh-TW/gateway/configuration)
## 常用指令
```bash
openclaw channels list
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## 狀態 / 能力 / 解析 / 日誌
- `channels status`：`--probe`、`--timeout <ms>`、`--json`
- `channels capabilities`：`--channel <name>`、`--account <id>`（僅能與 `--channel` 搭配使用）、`--target <dest>`、`--timeout <ms>`、`--json`
- `channels resolve`：`<entries...>`、`--channel <name>`、`--account <id>`、`--kind <auto|user|group>`、`--json`
- `channels logs`：`--channel <name|all>`、`--lines <n>`、`--json`
`channels status --probe` 是即時路徑：在可連線的 Gateway 上，它會針對每個帳號執行
`probeAccount` 與選用的 `auditAccount` 檢查，因此輸出可包含傳輸
狀態以及探測結果，例如 `works`、`probe failed`、`audit ok` 或 `audit failed`。
如果無法連線到 Gateway，`channels status` 會回退為僅根據設定產生的摘要，
而不是即時探測輸出。
## 新增 / 移除帳號
```bash
openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels remove --channel telegram --delete
```
<Tip>
`openclaw channels add --help` 會顯示各頻道的旗標（權杖、私密金鑰、應用程式權杖、signal-cli 路徑等）。
</Tip>
常見的非互動式新增介面包括：
- bot-token 頻道：`--token`、`--bot-token`、`--app-token`、`--token-file`
- Signal/iMessage 傳輸欄位：`--signal-number`、`--cli-path`、`--http-url`、`--http-host`、`--http-port`、`--db-path`、`--service`、`--region`
- Google Chat 欄位：`--webhook-path`、`--webhook-url`、`--audience-type`、`--audience`
- Matrix 欄位：`--homeserver`、`--user-id`、`--access-token`、`--password`、`--device-name`、`--initial-sync-limit`
- Nostr 欄位：`--private-key`、`--relay-urls`
- Tlon 欄位：`--ship`、`--url`、`--code`、`--group-channels`、`--dm-allowlist`、`--auto-discover-channels`
- `--use-env` 用於支援此功能的預設帳號環境變數後援驗證
如果在以旗標驅動的新增指令期間需要安裝頻道 Plugin，OpenClaw 會使用該頻道的預設安裝來源，而不會開啟互動式 Plugin 安裝提示。
當你在沒有旗標的情況下執行 `openclaw channels add` 時，互動式精靈可提示：
- 每個所選頻道的帳號 ID
- 這些帳號的選用顯示名稱
- `Bind configured channel accounts to agents now?`
如果你確認立即綁定，精靈會詢問哪個 agent 應擁有每個已設定的頻道帳號，並寫入以帳號為範圍的路由繫結。
你也可以稍後使用 `openclaw agents bindings`、`openclaw agents bind` 和 `openclaw agents unbind` 管理相同的路由規則（請參閱 [agents](/zh-TW/cli/agents)）。
當你將非預設帳號新增到仍使用單一帳號頂層設定的頻道時，OpenClaw 會先將以帳號為範圍的頂層值提升到該頻道的帳號對應表，再寫入新帳號。多數頻道會將這些值放入 `channels.<channel>.accounts.default`，但內建頻道可以改為保留現有相符的已提升帳號。Matrix 是目前的範例：如果已存在一個具名帳號，或 `defaultAccount` 指向現有具名帳號，提升程序會保留該帳號，而不是建立新的 `accounts.default`。
路由行為保持一致：
- 現有的僅頻道繫結（沒有 `accountId`）會繼續符合預設帳號。
- `channels add` 不會在非互動模式中自動建立或重寫繫結。
- 互動式設定可選擇性地新增以帳號為範圍的繫結。
如果你的設定已處於混合狀態（存在具名帳號且仍設定頂層單一帳號值），請執行 `openclaw doctor --fix`，將以帳號為範圍的值移到該頻道所選的已提升帳號。多數頻道會提升到 `accounts.default`；Matrix 則可改為保留現有具名/預設目標。
## 登入與登出（互動式）
```bash
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
```
- `channels login` 支援 `--verbose`。
- 當只設定了一個支援登入的目標時，`channels login` 和 `logout` 可以推斷頻道。
- 從 Gateway 主機上的終端機執行 `channels login`。Agent `exec` 會阻擋此互動式登入流程；若有可用的頻道原生 agent 登入工具，例如 `whatsapp_login`，應從聊天中使用。
## 疑難排解
- 執行 `openclaw status --deep` 進行廣泛探測。
- 使用 `openclaw doctor` 取得引導式修復。
- `openclaw channels list` 印出 `Claude: HTTP 403 ... user:profile` → 用量快照需要 `user:profile` 範圍。請使用 `--no-usage`，或提供 claude.ai 工作階段金鑰（`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`），或透過 Claude CLI 重新驗證。
- 當無法連線到 Gateway 時，`openclaw channels status` 會回退為僅根據設定產生的摘要。如果支援的頻道認證是透過 SecretRef 設定，但在目前指令路徑中不可用，它會將該帳號回報為已設定並附上降級備註，而不是顯示為未設定。
## 能力探測
擷取提供者能力提示（可用時包含 intents/scopes）以及靜態功能支援：
```bash
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
```
備註：
- `--channel` 是選用的；省略它即可列出每個頻道（包括 extensions）。
- `--account` 僅在搭配 `--channel` 時有效。
- `--target` 接受 `channel:<id>` 或原始數字頻道 ID，且僅適用於 Discord。
- 探測會依提供者而異：Discord intents + 選用頻道權限；Slack bot + 使用者範圍；Telegram bot 旗標 + Webhook；Signal daemon 版本；Microsoft Teams 應用程式權杖 + Graph 角色/範圍（在已知處標註）。沒有探測的頻道會回報 `Probe: unavailable`。
## 將名稱解析為 ID
使用提供者目錄將頻道/使用者名稱解析為 ID：
```bash
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"
```
備註：
- 使用 `--kind user|group|auto` 強制指定目標類型。
- 當多個項目共用相同名稱時，解析會優先選擇作用中的相符項目。
- `channels resolve` 是唯讀的。如果所選帳號是透過 SecretRef 設定，但該認證在目前指令路徑中不可用，指令會傳回附有備註的降級未解析結果，而不是中止整個執行。
## 相關
- [CLI 參考](/zh-TW/cli)
- [頻道概觀](/zh-TW/channels)

32
docs/zh-TW/cli/clawbot.md Normal file
View File

@ -0,0 +1,32 @@
---
read_when:
- 您維護使用 `openclaw clawbot ...` 的舊版指令碼
- 你需要遷移到目前指令的指南
summary: '`openclaw clawbot` 的 CLI 參考（舊版別名命名空間）'
title: Clawbot
x-i18n:
generated_at: "2026-04-30T02:51:55Z"
model: gpt-5.5
provider: openai
source_hash: 4ca7f189071d170a94ec3eda276a3ba1202ccdee43c610f214b65bda8375d300
source_path: cli/clawbot.md
workflow: 16
---
# `openclaw clawbot`
為了向後相容性而保留的舊版別名命名空間。
目前支援的別名：
- `openclaw clawbot qr`（與 [`openclaw qr`](/zh-TW/cli/qr) 行為相同）
## 遷移
請直接優先使用現代的頂層命令：
- `openclaw clawbot qr` -> `openclaw qr`
## 相關
- [CLI 參考](/zh-TW/cli)

95
docs/zh-TW/cli/commitments.md Normal file
View File

@ -0,0 +1,95 @@
---
read_when:
- 您想檢視推斷出的後續承諾
- 你想要關閉待處理的簽到
- 你正在稽核 Heartbeat 可能傳遞的內容
summary: '`openclaw commitments` 的 CLI 參考（檢查並關閉推斷出的後續追蹤事項）'
title: '`openclaw commitments`'
x-i18n:
generated_at: "2026-04-30T02:52:13Z"
model: gpt-5.5
provider: openai
source_hash: 37d5e5dca25cf649a5069360aa4e41fcc33d042dea99f643b98c07189c58f21c
source_path: cli/commitments.md
workflow: 16
---
列出並管理推斷出的後續承諾。
承諾是選用、短期存在的後續記憶，從對話情境建立。概念指南請參閱[推斷承諾](/zh-TW/concepts/commitments)。
未指定子命令時，`openclaw commitments` 會列出待處理的承諾。
## 用法
```bash
openclaw commitments [--all] [--agent <id>] [--status <status>] [--json]
openclaw commitments list [--all] [--agent <id>] [--status <status>] [--json]
openclaw commitments dismiss <id...> [--json]
```
## 選項
- `--all`：顯示所有狀態，而不只顯示待處理的承諾。
- `--agent <id>`：篩選至一個代理程式 ID。
- `--status <status>`：依狀態篩選。值：`pending`、`sent`、
`dismissed`、`snoozed` 或 `expired`。
- `--json`：輸出機器可讀的 JSON。
## 範例
列出待處理的承諾：
```bash
openclaw commitments
```
列出每個已儲存的承諾：
```bash
openclaw commitments --all
```
篩選至一個代理程式：
```bash
openclaw commitments --agent main
```
尋找已延後的承諾：
```bash
openclaw commitments --status snoozed
```
關閉一或多個承諾：
```bash
openclaw commitments dismiss cm_abc123 cm_def456
```
匯出為 JSON：
```bash
openclaw commitments --all --json
```
## 輸出
文字輸出包含：
- 承諾 ID
- 狀態
- 種類
- 最早到期時間
- 範圍
- 建議的確認文字
JSON 輸出也包含承諾儲存區路徑和完整的已儲存記錄。
## 相關
- [推斷承諾](/zh-TW/concepts/commitments)
- [記憶概觀](/zh-TW/concepts/memory)
- [Heartbeat](/zh-TW/gateway/heartbeat)
- [排程工作](/zh-TW/automation/cron-jobs)

46
docs/zh-TW/cli/completion.md Normal file
View File

@ -0,0 +1,46 @@
---
read_when:
- 你想要 zsh/bash/fish/PowerShell 的殼層自動補全功能
- 你需要將補全指令碼快取在 OpenClaw 狀態下
summary: CLI 參考：`openclaw completion`（產生／安裝 shell 自動補全腳本）
title: 完成
x-i18n:
generated_at: "2026-04-30T02:52:17Z"
model: gpt-5.5
provider: openai
source_hash: 9d064723b97f09105154197e4ef35b98ccb61e4b775f3fd990b18958f751f713
source_path: cli/completion.md
workflow: 16
---
# `openclaw completion`
產生 shell 補全指令碼，並可選擇安裝到你的 shell 設定檔。
## 使用方式
```bash
openclaw completion
openclaw completion --shell zsh
openclaw completion --install
openclaw completion --shell fish --install
openclaw completion --write-state
openclaw completion --shell bash --write-state
```
## 選項
- `-s, --shell <shell>`：shell 目標（`zsh`、`bash`、`powershell`、`fish`；預設：`zsh`）
- `-i, --install`：透過在你的 shell 設定檔加入 source 行來安裝補全
- `--write-state`：將補全指令碼寫入 `$OPENCLAW_STATE_DIR/completions`，不輸出到標準輸出
- `-y, --yes`：略過安裝確認提示
## 注意事項
- `--install` 會將一個小型的「OpenClaw 補全」區塊寫入你的 shell 設定檔，並指向快取的指令碼。
- 若未使用 `--install` 或 `--write-state`，此命令會將指令碼輸出到標準輸出。
- 補全產生會預先載入命令樹，因此會包含巢狀子命令。
## 相關
- [CLI 參考](/zh-TW/cli)

507
docs/zh-TW/cli/config.md Normal file
View File

@ -0,0 +1,507 @@
---
read_when:
- 您想要以非互動方式讀取或編輯設定
sidebarTitle: Config
summary: '`openclaw config` 的 CLI 參考 (get/set/patch/unset/file/schema/validate)'
title: 設定
x-i18n:
generated_at: "2026-04-30T02:52:12Z"
model: gpt-5.5
provider: openai
source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d
source_path: cli/config.md
workflow: 16
---
設定輔助工具可用於在 `openclaw.json` 中進行非互動式編輯：依路徑 get/set/patch/unset/file/schema/validate 值，並印出作用中的設定檔。未帶子命令執行時，會開啟設定精靈（等同於 `openclaw configure`）。
## 根選項
<ParamField path="--section <section>" type="string">
當你未帶子命令執行 `openclaw config` 時，可重複使用的引導式設定區段篩選器。
</ParamField>
支援的引導區段：`workspace`、`model`、`web`、`gateway`、`daemon`、`channels`、`plugins`、`skills`、`health`。
## 範例
```bash
openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json
```
### `config schema`
將為 `openclaw.json` 產生的 JSON schema 以 JSON 格式列印到 stdout。
<AccordionGroup>
<Accordion title="包含內容">
- 目前的根設定 schema，外加供編輯器工具使用的根 `$schema` 字串欄位。
- Control UI 使用的欄位 `title` 與 `description` 文件中繼資料。
- 巢狀物件、萬用字元（`*`）與陣列項目（`[]`）節點在存在相符欄位文件時，會繼承相同的 `title` / `description` 中繼資料。
- `anyOf` / `oneOf` / `allOf` 分支在存在相符欄位文件時，也會繼承相同的文件中繼資料。
- 當 runtime manifests 可載入時，會盡力提供即時 Plugin + 頻道 schema 中繼資料。
- 即使目前設定無效，也會提供乾淨的備用 schema。
</Accordion>
<Accordion title="相關 runtime RPC">
`config.schema.lookup` 會回傳一個正規化設定路徑，並附上淺層 schema 節點（`title`、`description`、`type`、`enum`、`const`、常見邊界）、相符的 UI 提示中繼資料，以及直接子項摘要。可用於 Control UI 或自訂用戶端中的路徑範圍下鑽。
</Accordion>
</AccordionGroup>
```bash
openclaw config schema
```
當你想用其他工具檢查或驗證它時，可將它管線輸出到檔案：
```bash
openclaw config schema > openclaw.schema.json
```
### 路徑
路徑使用點號或方括號表示法：
```bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
```
使用 agent 清單索引來指定特定 agent：
```bash
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
```
## 值
值會在可能時解析為 JSON5；否則會視為字串。使用 `--strict-json` 要求 JSON5 解析。`--json` 仍支援作為舊版別名。
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
```
`config get <path> --json` 會將原始值以 JSON 印出，而不是終端機格式化文字。
<Note>
物件指定預設會取代目標路徑。常用來保存使用者新增項目的受保護 map/list 路徑，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 與 `auth.profiles`，若取代會移除既有項目，除非你傳入 `--replace`，否則會拒絕。
</Note>
新增項目到這些 map 時使用 `--merge`：
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
```
只有當你刻意想讓提供的值成為完整目標值時，才使用 `--replace`。
## `config set` 模式
`openclaw config set` 支援四種指定樣式：
<Tabs>
<Tab title="值模式">
```bash
openclaw config set <path> <value>
```
</Tab>
<Tab title="SecretRef 建構器模式">
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN
```
</Tab>
<Tab title="提供者建構器模式">
提供者建構器模式只以 `secrets.providers.<alias>` 路徑為目標：
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-timeout-ms 5000
```
</Tab>
<Tab title="批次模式">
```bash
openclaw config set --batch-json '[
{
"path": "secrets.providers.default",
"provider": { "source": "env" }
},
{
"path": "channels.discord.token",
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
}
]'
```
```bash
openclaw config set --batch-file ./config-set.batch.json --dry-run
```
</Tab>
</Tabs>
<Warning>
SecretRef 指定在不支援的 runtime 可變更介面上會被拒絕（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord thread-binding webhook token，以及 WhatsApp creds JSON）。請參閱 [SecretRef 憑證介面](/zh-TW/reference/secretref-credential-surface)。
</Warning>
批次解析一律使用批次 payload（`--batch-json`/`--batch-file`）作為真實來源。`--strict-json` / `--json` 不會改變批次解析行為。
## `config patch`
當你想貼上或管線輸入設定形狀的 patch，而不是執行許多依路徑的 `config set` 命令時，請使用 `config patch`。輸入是 JSON5 物件。物件會遞迴合併，陣列與純量值會取代目標值，而 `null` 會刪除目標路徑。
```bash
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5
```
你也可以透過 stdin 管線輸入 patch，這對遠端設定指令碼很有用：
```bash
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
```
patch 範例：
```json5
{
channels: {
slack: {
enabled: true,
mode: "socket",
botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
groupPolicy: "open",
requireMention: false,
},
discord: {
enabled: true,
token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
dmPolicy: "disabled",
dm: { enabled: false },
groupPolicy: "allowlist",
},
},
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
models: {
"openai/gpt-5.5": { params: { fastMode: true } },
},
},
},
}
```
當某個物件或陣列必須完全成為所提供的值，而不是被遞迴 patch 時，請使用 `--replace-path <path>`：
```bash
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
```
`--dry-run` 會執行 schema 與 SecretRef 可解析性檢查，但不寫入。Dry-run 期間預設會略過 exec-backed SecretRef；當你刻意想讓 dry-run 執行提供者命令時，請加入 `--allow-exec`。
SecretRef 與提供者仍都支援 JSON 路徑/值模式：
```bash
openclaw config set channels.discord.token \
'{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
--strict-json
openclaw config set secrets.providers.vaultfile \
'{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
--strict-json
```
## 提供者建構器旗標
提供者建構器目標必須使用 `secrets.providers.<alias>` 作為路徑。
<AccordionGroup>
<Accordion title="通用旗標">
- `--provider-source <env|file|exec>`
- `--provider-timeout-ms <ms>`（`file`、`exec`）
</Accordion>
<Accordion title="Env 提供者（--provider-source env）">
- `--provider-allowlist <ENV_VAR>`（可重複）
</Accordion>
<Accordion title="File 提供者（--provider-source file）">
- `--provider-path <path>`（必要）
- `--provider-mode <singleValue|json>`
- `--provider-max-bytes <bytes>`
- `--provider-allow-insecure-path`
</Accordion>
<Accordion title="Exec 提供者（--provider-source exec）">
- `--provider-command <path>`（必要）
- `--provider-arg <arg>`（可重複）
- `--provider-no-output-timeout-ms <ms>`
- `--provider-max-output-bytes <bytes>`
- `--provider-json-only`
- `--provider-env <KEY=VALUE>`（可重複）
- `--provider-pass-env <ENV_VAR>`（可重複）
- `--provider-trusted-dir <path>`（可重複）
- `--provider-allow-insecure-path`
- `--provider-allow-symlink-command`
</Accordion>
</AccordionGroup>
強化的 exec 提供者範例：
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-json-only \
--provider-pass-env VAULT_TOKEN \
--provider-trusted-dir /usr/local/bin \
--provider-timeout-ms 5000
```
## Dry run
使用 `--dry-run` 驗證變更而不寫入 `openclaw.json`。
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run \
--json
openclaw config set channels.discord.token \
--ref-provider vault \
--ref-source exec \
--ref-id discord/token \
--dry-run \
--allow-exec
```
<AccordionGroup>
<Accordion title="Dry-run 行為">
- 建構器模式：對變更的 ref/provider 執行 SecretRef 可解析性檢查。
- JSON 模式（`--strict-json`、`--json` 或批次模式）：執行 schema 驗證與 SecretRef 可解析性檢查。
- 政策驗證也會針對已知不支援的 SecretRef 目標介面執行。
- 政策檢查會評估完整的變更後設定，因此父物件寫入（例如將 `hooks` 設為物件）無法繞過不支援介面驗證。
- Dry-run 期間預設會略過 Exec SecretRef 檢查，以避免命令副作用。
- 搭配 `--dry-run` 使用 `--allow-exec`，即可選擇加入 exec SecretRef 檢查（這可能會執行提供者命令）。
- `--allow-exec` 僅適用於 dry-run，若未搭配 `--dry-run` 使用會報錯。
</Accordion>
<Accordion title="--dry-run --json 欄位">
`--dry-run --json` 會印出機器可讀報告：
- `ok`：dry-run 是否通過
- `operations`：已評估的指定數量
- `checks`：schema/可解析性檢查是否執行
- `checks.resolvabilityComplete`：可解析性檢查是否執行完成（略過 exec refs 時為 false）
- `refsChecked`：dry-run 期間實際解析的 refs 數量
- `skippedExecRefs`：因未設定 `--allow-exec` 而略過的 exec refs 數量
- `errors`：`ok=false` 時的結構化 schema/可解析性失敗
</Accordion>
</AccordionGroup>
### JSON 輸出形狀
```json5
{
ok: boolean,
operations: number,
configPath: string,
inputModes: ["value" | "json" | "builder", ...],
checks: {
schema: boolean,
resolvability: boolean,
resolvabilityComplete: boolean,
},
refsChecked: number,
skippedExecRefs: number,
errors?: [
{
kind: "schema" | "resolvability",
message: string,
ref?: string, // present for resolvability errors
},
],
}
```
<Tabs>
<Tab title="Success example">
```json
{
"ok": true,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0
}
```
</Tab>
<Tab title="Failure example">
```json
{
"ok": false,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0,
"errors": [
{
"kind": "resolvability",
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
"ref": "env:default:MISSING_TEST_SECRET"
}
]
}
```
</Tab>
</Tabs>
<AccordionGroup>
<Accordion title="If dry-run fails">
- `config schema validation failed`：變更後的設定形狀無效；請修正路徑/值或提供者/ref 物件形狀。
- `Config policy validation failed: unsupported SecretRef usage`：將該認證移回純文字/字串輸入，並只在支援的表面使用 SecretRefs。
- `SecretRef assignment(s) could not be resolved`：目前無法解析參照的提供者/ref（缺少環境變數、檔案指標無效、exec 提供者失敗，或提供者/來源不相符）。
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 已略過 exec refs；如果需要 exec 可解析性驗證，請搭配 `--allow-exec` 重新執行。
- 對於批次模式，請修正失敗項目，並在寫入前重新執行 `--dry-run`。
</Accordion>
</AccordionGroup>
## 寫入安全性
`openclaw config set` 和其他 OpenClaw 擁有的設定寫入器，會先驗證完整的變更後設定，才將其提交到磁碟。如果新的 payload 未通過 schema 驗證，或看起來像是破壞性的覆寫，作用中的設定會保持不變，而被拒絕的 payload 會儲存在旁邊，檔名為 `openclaw.json.rejected.*`。
<Warning>
作用中的設定路徑必須是一般檔案。不支援對符號連結的 `openclaw.json` 配置進行寫入；請改用 `OPENCLAW_CONFIG_PATH` 直接指向真實檔案。
</Warning>
小幅編輯建議使用 CLI 寫入：
```bash
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate
```
如果寫入被拒絕，請檢查已儲存的 payload，並修正完整的設定形狀：
```bash
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
```
仍然允許直接用編輯器寫入，但執行中的 Gateway 會在驗證通過前將其視為不受信任。無效的直接編輯可在啟動或熱重新載入期間，從最後已知良好的備份還原。請參閱 [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#gateway-restored-last-known-good-config)。
整檔還原僅保留給全域損壞的設定，例如解析錯誤、根層級 schema 失敗、舊版遷移失敗，或同時發生 Plugin 與根層級失敗。如果驗證只在 `plugins.entries.<id>...` 底下失敗，OpenClaw 會保留作用中的 `openclaw.json`，並回報 Plugin 本地問題，而不是還原 `.last-good`。這可防止 Plugin schema 變更或 `minHostVersion` 偏差回滾不相關的使用者設定，例如模型、提供者、驗證設定檔、頻道、Gateway 暴露、工具、記憶體、瀏覽器或 cron 設定。
## 子命令
- `config file`：列印作用中的設定檔路徑（從 `OPENCLAW_CONFIG_PATH` 或預設位置解析）。該路徑應指向一般檔案，而不是符號連結。
編輯後重新啟動 gateway。
## 驗證
在不啟動 gateway 的情況下，依作用中 schema 驗證目前設定。
```bash
openclaw config validate
openclaw config validate --json
```
`openclaw config validate` 通過後，你可以使用本機 TUI，讓嵌入式 agent 在你從同一個終端機驗證每項變更時，比對作用中設定與文件：
<Note>
如果驗證已經失敗，請從 `openclaw configure` 或 `openclaw doctor --fix` 開始。`openclaw chat` 不會繞過無效設定防護。
</Note>
```bash
openclaw chat
```
然後在 TUI 內：
```text
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
```
典型修復迴圈：
<Steps>
<Step title="Compare with docs">
請 agent 將你的目前設定與相關文件頁面比對，並建議最小修正。
</Step>
<Step title="Apply targeted edits">
使用 `openclaw config set` 或 `openclaw configure` 套用目標明確的編輯。
</Step>
<Step title="Re-validate">
每次變更後，重新執行 `openclaw config validate`。
</Step>
<Step title="Doctor for runtime issues">
如果驗證通過但執行階段仍不健康，請執行 `openclaw doctor` 或 `openclaw doctor --fix` 取得遷移與修復協助。
</Step>
</Steps>
## 相關
- [CLI 參考](/zh-TW/cli)
- [設定](/zh-TW/gateway/configuration)

79
docs/zh-TW/cli/configure.md Normal file
View File

@ -0,0 +1,79 @@
---
read_when:
- 您想以互動方式調整憑證、裝置或代理預設值
summary: '`openclaw configure` 的 CLI 參考資料（互動式設定提示）'
title: 設定
x-i18n:
generated_at: "2026-04-30T02:52:22Z"
model: gpt-5.5
provider: openai
source_hash: 1bde13a139c299879ff13a85c17afdd55dce7ad758418266854428b059d8a05e
source_path: cli/configure.md
workflow: 16
---
# `openclaw configure`
用於設定憑證、裝置與代理預設值的互動式提示。
<Note>
**模型**區段包含 `agents.defaults.models` 允許清單的多選項目（會顯示在 `/model` 和模型選擇器中的內容）。依供應商範圍設定的選項，會將所選模型合併到既有允許清單，而不是取代設定中已存在的其他無關供應商。從 configure 重新執行供應商驗證時，會保留現有的 `agents.defaults.model.primary`。當你刻意想變更預設模型時，請使用 `openclaw models auth login --provider <id> --set-default` 或 `openclaw models set <model>`。
</Note>
當 configure 從供應商驗證選項開始時，預設模型與允許清單選擇器會自動優先使用該供應商。對於 Volcengine 和 BytePlus 等成對供應商，相同的偏好也會符合其編碼方案變體（`volcengine-plan/*`、`byteplus-plan/*`）。如果偏好的供應商篩選器會產生空清單，configure 會改用未篩選的目錄，而不是顯示空白選擇器。
<Tip>
不帶子命令的 `openclaw config` 會開啟相同的精靈。使用 `openclaw config get|set|unset` 進行非互動式編輯。
</Tip>
對於網頁搜尋，`openclaw configure --section web` 可讓你選擇供應商
並設定其憑證。有些供應商也會顯示供應商專屬的
後續提示：
- **Grok** 可以使用相同的 `XAI_API_KEY` 提供選用的 `x_search` 設定，並
讓你選擇 `x_search` 模型。
- **Kimi** 可以詢問 Moonshot API 區域（`api.moonshot.ai` 與
`api.moonshot.cn`）以及預設的 Kimi 網頁搜尋模型。
相關：
- Gateway 設定參考：[Configuration](/zh-TW/gateway/configuration)
- Config CLI：[Config](/zh-TW/cli/config)
## 選項
- `--section <section>`：可重複的區段篩選器
可用區段：
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
注意事項：
- 選擇 Gateway 執行位置一律會更新 `gateway.mode`。如果這就是你需要的全部內容，可以選擇「繼續」而不選其他區段。
- 以頻道為導向的服務（Slack/Discord/Matrix/Microsoft Teams）會在設定期間提示輸入頻道/聊天室允許清單。你可以輸入名稱或 ID；精靈會在可行情況下將名稱解析為 ID。
- 如果你執行 daemon 安裝步驟，權杖驗證需要權杖，且 `gateway.auth.token` 由 SecretRef 管理，configure 會驗證 SecretRef，但不會將解析後的明文權杖值保存到 supervisor 服務環境中繼資料。
- 如果權杖驗證需要權杖，而設定的權杖 SecretRef 無法解析，configure 會阻止 daemon 安裝，並提供可執行的修復指引。
- 如果已同時設定 `gateway.auth.token` 和 `gateway.auth.password`，且未設定 `gateway.auth.mode`，configure 會阻止 daemon 安裝，直到明確設定模式為止。
## 範例
```bash
openclaw configure
openclaw configure --section web
openclaw configure --section model --section channels
openclaw configure --section gateway --section daemon
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [Configuration](/zh-TW/gateway/configuration)

278
docs/zh-TW/cli/crestodian.md Normal file
View File

@ -0,0 +1,278 @@
---
read_when:
- 你執行 openclaw 時未指定命令，並想了解 Crestodian
- 你需要一種在沒有設定檔時也安全的方式來檢查或修復 OpenClaw
- 你正在設計或啟用訊息通道救援模式
summary: Crestodian 的 CLI 參考與安全模型，無需設定也安全的設定與修復輔助工具
title: Crestodian
x-i18n:
generated_at: "2026-04-30T02:52:40Z"
model: gpt-5.5
provider: openai
source_hash: e09331a5303120e9044ae147426ad17caeed35f092b316506ca8e4e3a1c55157
source_path: cli/crestodian.md
workflow: 16
---
# `openclaw crestodian`
Crestodian 是 OpenClaw 的本機設定、修復與組態輔助工具。它設計成在一般 agent 路徑損壞時仍可觸及。
不帶命令執行 `openclaw` 會在互動式終端機中啟動 Crestodian。執行 `openclaw crestodian` 則會明確啟動同一個輔助工具。
## Crestodian 顯示的內容
啟動時，互動式 Crestodian 會開啟與 `openclaw tui` 相同的 TUI shell，並使用 Crestodian 聊天後端。聊天記錄會以簡短問候開始：
- 何時啟動 Crestodian
- Crestodian 實際使用的模型或確定性規劃器路徑
- 組態有效性與預設 agent
- 來自首次啟動探測的 Gateway 可達性
- Crestodian 可採取的下一個除錯動作
它不會傾印秘密，也不會為了啟動而載入 Plugin CLI 命令。TUI 仍提供一般的標頭、聊天記錄、狀態列、頁尾、自動完成與編輯器控制。
使用 `status` 取得詳細清單，其中包含組態路徑、文件/原始碼路徑、本機 CLI 探測、API 金鑰存在狀態、agents、模型與 Gateway 詳細資料。
Crestodian 使用與一般 agents 相同的 OpenClaw 參考探索。在 Git checkout 中，它會指向本機 `docs/` 與本機原始碼樹。在 npm package 安裝中，它會使用隨附的 package 文件並連結至 [https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)，並明確指引在文件不足時檢閱原始碼。
## 範例
```bash
openclaw
openclaw crestodian
openclaw crestodian --json
openclaw crestodian --message "models"
openclaw crestodian --message "validate config"
openclaw crestodian --message "setup workspace ~/Projects/work model openai/gpt-5.5" --yes
openclaw crestodian --message "set default model openai/gpt-5.5" --yes
openclaw onboard --modern
```
在 Crestodian TUI 內：
```text
status
health
doctor
doctor fix
validate config
setup
setup workspace ~/Projects/work model openai/gpt-5.5
config set gateway.port 19001
config set-ref gateway.auth.token env OPENCLAW_GATEWAY_TOKEN
gateway status
restart gateway
agents
create agent work workspace ~/Projects/work
models
set default model openai/gpt-5.5
talk to work agent
talk to agent for ~/Projects/work
audit
quit
```
## 安全啟動
Crestodian 的啟動路徑刻意保持精簡。它可以在下列情況下執行：
- 缺少 `openclaw.json`
- `openclaw.json` 無效
- Gateway 已關閉
- Plugin 命令註冊無法使用
- 尚未設定任何 agent
`openclaw --help` 與 `openclaw --version` 仍使用一般快速路徑。非互動式 `openclaw` 會以簡短訊息結束，而不是列印根 help，因為無命令產品是 Crestodian。
## 操作與核准
Crestodian 使用具型別的操作，而不是臨時編輯組態。
唯讀操作可以立即執行：
- 顯示概覽
- 列出 agents
- 顯示模型/後端狀態
- 執行狀態或健康檢查
- 檢查 Gateway 可達性
- 執行 doctor 但不進行互動式修復
- 驗證組態
- 顯示稽核記錄路徑
持久性操作在互動式模式中需要對話式核准，除非你為直接命令傳入 `--yes`：
- 寫入組態
- 執行 `config set`
- 透過 `config set-ref` 設定支援的 SecretRef 值
- 執行設定/入門 bootstrap
- 變更預設模型
- 啟動、停止或重新啟動 Gateway
- 建立 agents
- 執行會重寫組態或狀態的 doctor 修復
已套用的寫入會記錄於：
```text
~/.openclaw/audit/crestodian.jsonl
```
探索不會被稽核。只有已套用的操作與寫入會被記錄。
`openclaw onboard --modern` 會以現代入門預覽啟動 Crestodian。純 `openclaw onboard` 仍會執行傳統入門流程。
## 設定 bootstrap
`setup` 是聊天優先的入門 bootstrap。它只會透過具型別的組態操作寫入，並且會先要求核准。
```text
setup
setup workspace ~/Projects/work
setup workspace ~/Projects/work model openai/gpt-5.5
```
未設定模型時，setup 會依照以下順序選擇第一個可用的後端，並告訴你它選擇了什麼：
- 既有明確模型，如果已設定
- `OPENAI_API_KEY` -> `openai/gpt-5.5`
- `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-7`
- Claude Code CLI -> `claude-cli/claude-opus-4-7`
- Codex CLI -> `codex-cli/gpt-5.5`
如果都無法使用，setup 仍會寫入預設工作區，並讓模型保持未設定。安裝或登入 Codex/Claude Code，或公開 `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`，然後再次執行 setup。
## 模型輔助規劃器
Crestodian 一律以確定性模式啟動。對於確定性解析器無法理解的模糊命令，本機 Crestodian 可透過 OpenClaw 的一般執行階段路徑進行一次有界規劃器回合。它會先使用已設定的 OpenClaw 模型。如果尚無可用的已設定模型，它可以 fallback 到機器上已存在的本機執行階段：
- Claude Code CLI: `claude-cli/claude-opus-4-7`
- Codex app-server harness: `openai/gpt-5.5` with `agentRuntime.id: "codex"`
- Codex CLI: `codex-cli/gpt-5.5`
模型輔助規劃器無法直接變更組態。它必須將請求轉譯為 Crestodian 的其中一個具型別命令，然後套用一般核准與稽核規則。Crestodian 會在執行任何動作前，列印它使用的模型與解讀出的命令。無組態 fallback 規劃器回合是暫時性的、在執行階段支援時會停用工具，並使用暫時工作區/session。
訊息通道救援模式不使用模型輔助規劃器。遠端救援保持確定性，因此損壞或遭入侵的一般 agent 路徑無法被用作組態編輯器。
## 切換至 agent
使用自然語言選擇器離開 Crestodian 並開啟一般 TUI：
```text
talk to agent
talk to work agent
switch to main agent
```
`openclaw tui`、`openclaw chat` 與 `openclaw terminal` 仍會直接開啟一般 agent TUI。它們不會啟動 Crestodian。
切換到一般 TUI 後，使用 `/crestodian` 返回 Crestodian。你可以包含後續請求：
```text
/crestodian
/crestodian restart gateway
```
TUI 內的 agent 切換會留下麵包屑，指出 `/crestodian` 可用。
## 訊息救援模式
訊息救援模式是 Crestodian 的訊息通道進入點。它適用於你的正常 agent 已停止運作，但 WhatsApp 等受信任通道仍可接收命令的情況。
支援的文字命令：
- `/crestodian <request>`
操作員流程：
```text
You, in a trusted owner DM: /crestodian status
OpenClaw: Crestodian rescue mode. Gateway reachable: no. Config valid: no.
You: /crestodian restart gateway
OpenClaw: Plan: restart the Gateway. Reply /crestodian yes to apply.
You: /crestodian yes
OpenClaw: Applied. Audit entry written.
```
也可以從本機提示或救援模式佇列建立 agent：
```text
create agent work workspace ~/Projects/work model openai/gpt-5.5
/crestodian create agent work workspace ~/Projects/work
```
遠端救援模式是管理介面。它必須被視為遠端組態修復，而不是一般聊天。
遠端救援的安全合約：
- 沙箱化啟用時停用。如果 agent/session 已被沙箱化，Crestodian 必須拒絕遠端救援，並說明需要本機 CLI 修復。
- 預設有效狀態是 `auto`：只在受信任的 YOLO 操作中允許遠端救援，此時執行階段已具有未沙箱化的本機權限。
- 要求明確的 owner 身分。救援不得接受萬用字元寄件者規則、開放群組政策、未驗證的 webhooks 或匿名通道。
- 預設僅限 owner DM。群組/通道救援需要明確 opt-in。
- 遠端救援無法開啟本機 TUI，也無法切換到互動式 agent session。使用本機 `openclaw` 進行 agent handoff。
- 即使在救援模式中，持久性寫入仍需要核准。
- 稽核每個已套用的救援操作。訊息通道救援會記錄通道、帳號、寄件者與來源位址中繼資料。會變更組態的操作也會記錄變更前後的組態雜湊。
- 絕不回顯秘密。SecretRef 檢查應回報可用性，而不是值。
- 如果 Gateway 存活，優先使用 Gateway 具型別操作。如果 Gateway 已停止，則只使用不依賴一般 agent 迴圈的最小本機修復介面。
組態形狀：
```jsonc
{
"crestodian": {
"rescue": {
"enabled": "auto",
"ownerDmOnly": true,
},
},
}
```
`enabled` 應接受：
- `"auto"`：預設。只在有效執行階段為 YOLO 且沙箱化關閉時允許。
- `false`：永不允許訊息通道救援。
- `true`：當 owner/通道檢查通過時明確允許救援。這仍不得繞過沙箱化拒絕。
預設 `"auto"` YOLO 姿態是：
- sandbox mode 解析為 `off`
- `tools.exec.security` 解析為 `full`
- `tools.exec.ask` 解析為 `off`
遠端救援由 Docker lane 覆蓋：
```bash
pnpm test:docker:crestodian-rescue
```
無組態本機規劃器 fallback 由下列項目覆蓋：
```bash
pnpm test:docker:crestodian-planner
```
Opt-in 即時通道命令介面 smoke 會檢查 `/crestodian status`，以及透過救援處理器的持久性核准 roundtrip：
```bash
pnpm test:live:crestodian-rescue-channel
```
透過 Crestodian 進行全新的無組態設定由下列項目覆蓋：
```bash
pnpm test:docker:crestodian-first-run
```
該 lane 會從空狀態目錄開始，將裸 `openclaw` 路由至 Crestodian，設定預設模型、建立額外 agent、透過 Plugin enablement 加 token SecretRef 設定 Discord、驗證組態，並檢查稽核記錄。QA Lab 也有一個 repo-backed scenario，用於相同的 Ring 0 流程：
```bash
pnpm openclaw qa suite --scenario crestodian-ring-zero-setup
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [Doctor](/zh-TW/cli/doctor)
- [TUI](/zh-TW/cli/tui)
- [Sandbox](/zh-TW/cli/sandbox)
- [安全性](/zh-TW/cli/security)

246
docs/zh-TW/cli/cron.md Normal file
View File

@ -0,0 +1,246 @@
---
read_when:
- 你想要排程工作和喚醒
- 您正在偵錯 Cron 執行與日誌
summary: '`openclaw cron` 的 CLI 參考（排程並執行背景作業）'
title: Cron
x-i18n:
generated_at: "2026-04-30T02:52:47Z"
model: gpt-5.5
provider: openai
source_hash: 658498b09e0f0997d0f05dcdbdbd8822284d747df932f1c51e86f97b94cd81a7
source_path: cli/cron.md
workflow: 16
---
# `openclaw cron`
管理 Gateway 排程器的 Cron 工作。
<Tip>
執行 `openclaw cron --help` 查看完整命令介面。概念指南請參閱 [Cron 工作](/zh-TW/automation/cron-jobs)。
</Tip>
## 工作階段
`--session` 接受 `main`、`isolated`、`current` 或 `session:<id>`。
<AccordionGroup>
<Accordion title="工作階段鍵">
- `main` 繫結到代理程式的主要工作階段。
- `isolated` 會為每次執行建立新的轉錄記錄與工作階段 ID。
- `current` 會繫結到建立時的作用中工作階段。
- `session:<id>` 會固定到明確的持久工作階段鍵。
</Accordion>
<Accordion title="隔離工作階段語意">
隔離執行會重設環境對話脈絡。通道與群組路由、傳送/佇列政策、提權、來源，以及 ACP 執行階段繫結都會為新的執行重設。安全偏好設定與使用者明確選取的模型或驗證覆寫可以跨執行保留。
</Accordion>
</AccordionGroup>
## 傳遞
`openclaw cron list` 和 `openclaw cron show <job-id>` 會預覽解析後的傳遞路由。對於 `channel: "last"`，預覽會顯示路由是從主要或目前工作階段解析而來，或會以關閉方式失敗。
<Note>
隔離的 `cron add` 工作預設使用 `--announce` 傳遞。使用 `--no-deliver` 可讓輸出維持內部。`--deliver` 仍作為 `--announce` 的已棄用別名保留。
</Note>
### 傳遞擁有權
隔離 Cron 聊天傳遞由代理程式與執行器共同處理：
- 當聊天路由可用時，代理程式可以使用 `message` 工具直接傳送。
- `announce` 只有在代理程式未直接傳送到解析後目標時，才會後備傳遞最終回覆。
- `webhook` 會將完成的承載內容發布到 URL。
- `none` 會停用執行器後備傳遞。
`--announce` 是最終回覆的執行器後備傳遞。`--no-deliver` 會停用該後備，但當聊天路由可用時，不會移除代理程式的 `message` 工具。
從作用中聊天建立的提醒會保留即時聊天傳遞目標，以供後備公告傳遞使用。內部工作階段鍵可能是小寫；不要將它們作為區分大小寫的提供者 ID 的真實來源，例如 Matrix 房間 ID。
### 失敗傳遞
失敗通知會依此順序解析：
1. 工作上的 `delivery.failureDestination`。
2. 全域 `cron.failureDestination`。
3. 工作的主要公告目標（未設定明確失敗目的地時）。
<Note>
主要工作階段工作只有在主要傳遞模式為 `webhook` 時，才可以使用 `delivery.failureDestination`。隔離工作在所有模式中都接受它。
</Note>
注意：隔離 Cron 執行會將執行層級的代理程式失敗視為工作錯誤，即使沒有產生回覆承載內容也一樣，因此模型/提供者失敗仍會增加錯誤計數器並觸發失敗通知。
## 排程
### 一次性工作
`--at <datetime>` 會排程一次性執行。沒有偏移量的日期時間會視為 UTC，除非你也傳入 `--tz <iana>`，它會以指定時區解讀牆鐘時間。
<Note>
一次性工作預設在成功後刪除。使用 `--keep-after-run` 可保留它們。
</Note>
### 週期性工作
週期性工作在連續錯誤後使用指數重試退避：30 秒、1 分鐘、5 分鐘、15 分鐘、60 分鐘。排程會在下一次成功執行後恢復正常。
略過的執行會與執行錯誤分開追蹤。它們不會影響重試退避，但 `openclaw cron edit <job-id> --failure-alert-include-skipped` 可以選擇讓失敗警示包含重複的略過執行通知。
對於以本機設定模型提供者為目標的隔離工作，Cron 會在啟動代理程式回合前執行輕量提供者預檢。Loopback、私人網路和 `.local` `api: "ollama"` 提供者會在 `/api/tags` 探測；本機 OpenAI 相容提供者（例如 vLLM、SGLang 和 LM Studio）會在 `/models` 探測。如果端點無法連線，該執行會記錄為 `skipped`，並在之後的排程重試；符合的失效端點會快取 5 分鐘，以避免許多工作持續重擊同一本機伺服器。
注意：Cron 工作定義存放在 `jobs.json`，而待處理的執行階段狀態存放在 `jobs-state.json`。如果 `jobs.json` 從外部被編輯，Gateway 會重新載入已變更的排程並清除過期的待處理時段；僅格式化的重寫不會清除待處理時段。
### 手動執行
`openclaw cron run` 會在手動執行排入佇列後立即返回。成功回應會包含 `{ ok: true, enqueued: true, runId }`。使用 `openclaw cron runs --id <job-id>` 追蹤最終結果。
<Note>
`openclaw cron run <job-id>` 預設會強制執行。使用 `--due` 可保留較舊的「只有到期時才執行」行為。
</Note>
## 模型
`cron add|edit --model <ref>` 會為工作選取允許的模型。
<Warning>
如果模型不被允許或無法解析，Cron 會以明確的驗證錯誤讓執行失敗，而不是退回到工作的代理程式或預設模型選擇。
</Warning>
Cron `--model` 是**工作主要模型**，不是聊天工作階段的 `/model` 覆寫。這表示：
- 當選取的工作模型失敗時，設定的模型後備仍會套用。
- 存在時，每個工作的承載 `fallbacks` 會取代設定的後備清單。
- 空的每工作後備清單（工作承載/API 中的 `fallbacks: []`）會使 Cron 執行變得嚴格。
- 當工作有 `--model` 但未設定後備清單時，OpenClaw 會傳入明確的空後備覆寫，因此代理程式主要模型不會作為隱藏重試目標附加。
### 隔離 Cron 模型優先順序
隔離 Cron 依此順序解析作用中模型：
1. Gmail-hook 覆寫。
2. 每工作 `--model`。
3. 已儲存的 Cron 工作階段模型覆寫（當使用者已選取一個時）。
4. 代理程式或預設模型選擇。
### 快速模式
隔離 Cron 快速模式會遵循解析後的即時模型選擇。模型設定 `params.fastMode` 預設會套用，但已儲存的工作階段 `fastMode` 覆寫仍優先於設定。
### 即時模型切換重試
如果隔離執行擲出 `LiveSessionModelSwitchError`，Cron 會在重試前，為作用中執行保留已切換的提供者與模型（以及存在時的已切換驗證設定檔覆寫）。外層重試迴圈在初次嘗試後限制為兩次切換重試，然後中止而不是永久迴圈。
## 執行輸出與拒絕
### 過期確認抑制
隔離 Cron 回合會抑制過期的僅確認回覆。如果第一個結果只是中間狀態更新，且沒有後代子代理程式執行負責最終答案，Cron 會在傳遞前重新提示一次以取得真正結果。
### 靜默權杖抑制
如果隔離 Cron 執行只返回靜默權杖（`NO_REPLY` 或 `no_reply`），Cron 會同時抑制直接對外傳遞與後備佇列摘要路徑，因此不會有任何內容發布回聊天。
### 結構化拒絕
隔離 Cron 執行會優先使用嵌入式執行中的結構化執行拒絕中繼資料，然後退回到最終輸出中的已知拒絕標記，例如 `SYSTEM_RUN_DENIED`、`INVALID_REQUEST` 和核准繫結拒絕片語。
`cron list` 和執行歷史會顯示拒絕原因，而不是將被封鎖的命令報告為 `ok`。
## 保留
保留與修剪由設定控制：
- `cron.sessionRetention`（預設 `24h`）會修剪已完成的隔離執行工作階段。
- `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 會修剪 `~/.openclaw/cron/runs/<jobId>.jsonl`。
## 遷移較舊的工作
<Note>
如果你有目前傳遞與儲存格式之前的 Cron 工作，請執行 `openclaw doctor --fix`。Doctor 會正規化舊版 Cron 欄位（`jobId`、`schedule.cron`、頂層傳遞欄位，包括舊版 `threadId`、承載 `provider` 傳遞別名），並在已設定 `cron.webhook` 時，將簡單的 `notify: true` Webhook 後備工作遷移為明確的 Webhook 傳遞。
</Note>
## 常見編輯
更新傳遞設定而不變更訊息：
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
```
停用隔離工作的傳遞：
```bash
openclaw cron edit <job-id> --no-deliver
```
為隔離工作啟用輕量啟動脈絡：
```bash
openclaw cron edit <job-id> --light-context
```
公告到特定通道：
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
公告到 Telegram 論壇主題：
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
```
建立具有輕量啟動脈絡的隔離工作：
```bash
openclaw cron add \
--name "Lightweight morning brief" \
--cron "0 7 * * *" \
--session isolated \
--message "Summarize overnight updates." \
--light-context \
--no-deliver
```
`--light-context` 只適用於隔離代理程式回合工作。對於 Cron 執行，輕量模式會讓啟動脈絡保持空白，而不是注入完整工作區啟動集。
## 常見管理命令
手動執行與檢查：
```bash
openclaw cron list
openclaw cron show <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50
```
`cron runs` 項目包含傳遞診斷，提供預期的 Cron 目標、解析後目標、訊息工具傳送、後備使用情況，以及已傳遞狀態。
代理程式與工作階段重新指向：
```bash
openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
```
傳遞微調：
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [排程任務](/zh-TW/automation/cron-jobs)

70
docs/zh-TW/cli/daemon.md Normal file
View File

@ -0,0 +1,70 @@
---
read_when:
- 你仍在 scripts 中使用 `openclaw daemon ...`
- 你需要服務生命週期指令（install/start/stop/restart/status）
summary: '`openclaw daemon` 的 CLI 參考（Gateway 服務管理的舊版別名）'
title: 常駐程式
x-i18n:
generated_at: "2026-04-30T02:52:48Z"
model: gpt-5.5
provider: openai
source_hash: 51839f7cbc180cc0c43caa2d7e83cc2add7cbca40665f83f64e6ce9dde8574dd
source_path: cli/daemon.md
workflow: 16
---
# `openclaw daemon`
Gateway 服務管理命令的舊版別名。
`openclaw daemon ...` 對應到與 `openclaw gateway ...` 服務命令相同的服務控制介面。
## 用法
```bash
openclaw daemon status
openclaw daemon install
openclaw daemon start
openclaw daemon stop
openclaw daemon restart
openclaw daemon uninstall
```
## 子命令
- `status`：顯示服務安裝狀態並探測 Gateway 健康狀態
- `install`：安裝服務（`launchd`/`systemd`/`schtasks`）
- `uninstall`：移除服務
- `start`：啟動服務
- `stop`：停止服務
- `restart`：重新啟動服務
## 常用選項
- `status`：`--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json`
- `install`：`--port`、`--runtime <node|bun>`、`--token`、`--force`、`--json`
- 生命週期（`uninstall|start|stop|restart`）：`--json`
注意事項：
- `status` 會在可能時解析已設定的 auth SecretRefs，以用於探測驗證。
- 如果此命令路徑中所需的 auth SecretRef 未解析，當探測連線能力/驗證失敗時，`daemon status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析祕密來源。
- 如果探測成功，未解析的 auth-ref 警告會被抑制，以避免誤判。
- `status --deep` 會加入盡力而為的系統層級服務掃描。當它找到其他類似 gateway 的服務時，人類可讀輸出會列印清理提示，並警告每台機器一個 gateway 仍是一般建議。
- 在 Linux systemd 安裝中，`status` 權杖漂移檢查會同時包含 `Environment=` 和 `EnvironmentFile=` 單元來源。
- 漂移檢查會使用合併後的執行階段環境解析 `gateway.auth.token` SecretRefs（先用服務命令環境，再退回程序環境）。
- 如果權杖驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或模式未設定且密碼可勝出、沒有權杖候選可勝出），權杖漂移檢查會略過設定權杖解析。
- 當權杖驗證需要權杖且 `gateway.auth.token` 由 SecretRef 管理時，`install` 會驗證 SecretRef 可解析，但不會將解析後的權杖持久化到服務環境中繼資料。
- 如果權杖驗證需要權杖，而已設定的權杖 SecretRef 未解析，安裝會以關閉方式失敗。
- 如果同時設定了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，安裝會被封鎖，直到明確設定模式。
- 在 macOS 上，`install` 會讓 LaunchAgent plists 僅限擁有者存取，並透過僅限擁有者存取的檔案和 wrapper 載入受管理的服務環境值，而不是將 API 金鑰或 auth-profile 環境參照序列化到 `EnvironmentVariables`。
- 如果你刻意在同一台主機上執行多個 gateways，請隔離連接埠、設定/狀態和工作區；請參閱 [/gateway#multiple-gateways-same-host](/zh-TW/gateway#multiple-gateways-same-host)。
## 建議
請使用 [`openclaw gateway`](/zh-TW/cli/gateway) 查看目前的文件與範例。
## 相關
- [CLI 參考](/zh-TW/cli)
- [Gateway runbook](/zh-TW/gateway)

36
docs/zh-TW/cli/dashboard.md Normal file
View File

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

181
docs/zh-TW/cli/devices.md Normal file
View File

@ -0,0 +1,181 @@
---
read_when:
- 你正在核准裝置配對請求
- 你需要輪替或撤銷裝置權杖
summary: '`openclaw devices` 的 CLI 參考（裝置配對 + 權杖輪替/撤銷）'
title: 裝置
x-i18n:
generated_at: "2026-04-30T02:52:57Z"
model: gpt-5.5
provider: openai
source_hash: df105135a12ec733e45a67792e8447628f1538fc2536a008d615d46d1eaff5c8
source_path: cli/devices.md
workflow: 16
---
# `openclaw devices`
管理裝置配對請求和裝置範圍的權杖。
## 命令
### `openclaw devices list`
列出待處理的配對請求和已配對的裝置。
```
openclaw devices list
openclaw devices list --json
```
待處理請求的輸出會在裝置目前已核准的存取權旁邊顯示請求的存取權，前提是該裝置已經配對。這會讓範圍/角色升級明確可見，而不是看起來像配對遺失了。
### `openclaw devices remove <deviceId>`
移除一個已配對的裝置項目。
當你使用已配對裝置權杖進行身分驗證時，非管理員呼叫者只能移除**自己的**裝置項目。移除其他裝置需要 `operator.admin`。
```
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json
```
### `openclaw devices clear --yes [--pending]`
大量清除已配對的裝置。
```
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json
```
### `openclaw devices approve [requestId] [--latest]`
依精確的 `requestId` 核准待處理的裝置配對請求。如果省略 `requestId` 或傳入 `--latest`，OpenClaw 只會列印選取的待處理請求後結束；請先確認詳細資料，再使用精確的請求 ID 重新執行核准。
<Note>
如果裝置以變更後的驗證詳細資料（角色、範圍或公開金鑰）重試配對，OpenClaw 會取代先前的待處理項目，並發出新的 `requestId`。請在核准前立即執行 `openclaw devices list`，以使用目前的 ID。
</Note>
如果裝置已經配對，並要求更廣的範圍或更廣的角色，OpenClaw 會保留現有核准，並建立新的待處理升級請求。請查看 `openclaw devices list` 中的 `Requested` 與 `Approved` 欄位，或使用 `openclaw devices approve --latest` 在核准前預覽精確的升級內容。
如果 Gateway 明確設定了 `gateway.nodes.pairing.autoApproveCidrs`，來自相符用戶端 IP 的首次 `role: node` 請求可以在出現在此清單之前獲得核准。該原則預設停用，且永遠不適用於操作者/瀏覽器用戶端或升級請求。
```
openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest
```
### `openclaw devices reject <requestId>`
拒絕待處理的裝置配對請求。
```
openclaw devices reject <requestId>
```
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
輪替特定角色的裝置權杖（可選擇更新範圍）。
目標角色必須已存在於該裝置已核准的配對合約中；輪替不能鑄造新的未核准角色。
如果你省略 `--scope`，之後使用已儲存輪替權杖重新連線時，會重用該權杖快取的已核准範圍。如果你傳入明確的 `--scope` 值，這些值會成為未來快取權杖重新連線所儲存的範圍集合。
非管理員的已配對裝置呼叫者只能輪替**自己的**裝置權杖。
目標權杖範圍集合必須維持在呼叫者工作階段自己的操作者範圍內；輪替不能鑄造或保留比呼叫者已擁有者更廣的操作者權杖。
```
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
```
以 JSON 傳回輪替中繼資料。如果呼叫者在使用該裝置權杖進行身分驗證時輪替自己的權杖，回應也會包含替換權杖，讓用戶端可在重新連線前保存它。共享/管理員輪替不會回傳承載權杖。
### `openclaw devices revoke --device <id> --role <role>`
撤銷特定角色的裝置權杖。
非管理員的已配對裝置呼叫者只能撤銷**自己的**裝置權杖。
撤銷其他裝置的權杖需要 `operator.admin`。
目標權杖範圍集合也必須符合呼叫者工作階段自己的操作者範圍；僅配對的呼叫者不能撤銷管理員/寫入操作者權杖。
```
openclaw devices revoke --device <deviceId> --role node
```
以 JSON 傳回撤銷結果。
## 常用選項
- `--url <url>`：Gateway WebSocket URL（設定時預設為 `gateway.remote.url`）。
- `--token <token>`：Gateway 權杖（如有需要）。
- `--password <password>`：Gateway 密碼（密碼驗證）。
- `--timeout <ms>`：RPC 逾時。
- `--json`：JSON 輸出（建議用於指令碼）。
<Warning>
當你設定 `--url` 時，CLI 不會回退到設定或環境認證。請明確傳入 `--token` 或 `--password`。缺少明確認證會導致錯誤。
</Warning>
## 備註
- 權杖輪替會傳回新的權杖（敏感資訊）。請將它視為機密。
- 這些命令需要 `operator.pairing`（或 `operator.admin`）範圍。
- `gateway.nodes.pairing.autoApproveCidrs` 是一項選用的 Gateway 原則，僅適用於新的節點裝置配對；它不會變更 CLI 核准權限。
- 權杖輪替和撤銷會維持在該裝置已核准的配對角色集合，以及已核准的範圍基準內。游離的快取權杖項目不會授予權杖管理目標。
- 對於已配對裝置權杖工作階段，跨裝置管理僅限管理員：
`remove`、`rotate` 和 `revoke` 僅限自身操作，除非呼叫者擁有
`operator.admin`。
- 權杖變更也受呼叫者範圍限制：僅配對工作階段不能
輪替或撤銷目前帶有 `operator.admin` 或
`operator.write` 的權杖。
- `devices clear` 會刻意以 `--yes` 作為門檻。
- 如果配對範圍在 local loopback 上無法使用（且未傳入明確的 `--url`），list/approve 可以使用本機配對後援。
- `devices approve` 在鑄造權杖前需要明確的請求 ID；省略 `requestId` 或傳入 `--latest` 只會預覽最新的待處理請求。
## 權杖漂移復原檢查清單
當 Control UI 或其他用戶端持續因 `AUTH_TOKEN_MISMATCH` 或 `AUTH_DEVICE_TOKEN_MISMATCH` 失敗時，請使用此清單。
1. 確認目前的 Gateway 權杖來源：
```bash
openclaw config get gateway.auth.token
```
2. 列出已配對裝置並識別受影響的裝置 ID：
```bash
openclaw devices list
```
3. 輪替受影響裝置的操作者權杖：
```bash
openclaw devices rotate --device <deviceId> --role operator
```
4. 如果輪替仍不足，移除過期配對並重新核准：
```bash
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
```
5. 使用目前的共享權杖/密碼重試用戶端連線。
備註：
- 一般重新連線的驗證優先順序是明確共享權杖/密碼優先，接著是明確的 `deviceToken`，再來是已儲存的裝置權杖，最後是啟動權杖。
- 受信任的 `AUTH_TOKEN_MISMATCH` 復原可以在一次有界重試中，暫時同時傳送共享權杖和已儲存的裝置權杖。
相關：
- [儀表板驗證疑難排解](/zh-TW/web/dashboard#if-you-see-unauthorized-1008)
- [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#dashboard-control-ui-connectivity)
## 相關
- [CLI 參考](/zh-TW/cli)
- [節點](/zh-TW/nodes)

74
docs/zh-TW/cli/directory.md Normal file
View File

@ -0,0 +1,74 @@
---
read_when:
- 你想查詢某個通道的聯絡人/群組/自身 ID
- 你正在開發通道目錄配接器
summary: '`openclaw directory` 的 CLI 參考（self、peers、groups）'
title: 目錄
x-i18n:
generated_at: "2026-04-30T02:53:04Z"
model: gpt-5.5
provider: openai
source_hash: f63ed92469738501ae1f8f08aec3edf01d1f0f46008571ed38ccd9c77e5ba15e
source_path: cli/directory.md
workflow: 16
---
# `openclaw directory`
支援目錄查詢的通道查詢（聯絡人/對等方、群組，以及「me」）。
## 常用旗標
- `--channel <name>`：通道 ID/別名（設定多個通道時為必要；只設定一個通道時自動使用）
- `--account <id>`：帳號 ID（預設：通道預設值）
- `--json`：輸出 JSON
## 注意事項
- `directory` 用於協助你找出可貼到其他命令中的 ID（特別是 `openclaw message send --target ...`）。
- 對許多通道而言，結果是由設定支援（允許清單/已設定的群組），而不是即時提供者目錄。
- 預設輸出是以 Tab 分隔的 `id`（有時也包含 `name`）；編寫指令碼時請使用 `--json`。
## 搭配 `message send` 使用結果
```bash
openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
```
## ID 格式（依通道）
- WhatsApp：`+15551234567`（DM）、`1234567890-1234567890@g.us`（群組）
- Telegram：`@username` 或數字聊天 ID；群組為數字 ID
- Slack：`user:U…` 和 `channel:C…`
- Discord：`user:<id>` 和 `channel:<id>`
- Matrix（Plugin）：`user:@user:server`、`room:!roomId:server`，或 `#alias:server`
- Microsoft Teams（Plugin）：`user:<id>` 和 `conversation:<id>`
- Zalo（Plugin）：使用者 ID（Bot API）
- Zalo Personal / `zalouser`（Plugin）：來自 `zca` 的對話串 ID（DM/群組）（`me`、`friend list`、`group list`）
## 自己（"me"）
```bash
openclaw directory self --channel zalouser
```
## 對等方（聯絡人/使用者）
```bash
openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50
```
## 群組
```bash
openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>
```
## 相關
- [CLI 參考](/zh-TW/cli)

60
docs/zh-TW/cli/dns.md Normal file
View File

@ -0,0 +1,60 @@
---
read_when:
- 你想要透過 Tailscale + CoreDNS 進行廣域探索（DNS-SD）
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: '`openclaw dns` 的 CLI 參考（廣域探索輔助工具）'
title: DNS
x-i18n:
generated_at: "2026-04-30T02:53:21Z"
model: gpt-5.5
provider: openai
source_hash: 99dcf7c8c76833784a2b712b02f9e40c6c0548c37c9743a89b9d650fe503d385
source_path: cli/dns.md
workflow: 16
---
# `openclaw dns`
用於廣域探索的 DNS 輔助工具（Tailscale + CoreDNS）。目前專注於 macOS + Homebrew CoreDNS。
相關：
- Gateway 探索：[探索](/zh-TW/gateway/discovery)
- 廣域探索設定：[設定](/zh-TW/gateway/configuration)
## 設定
```bash
openclaw dns setup
openclaw dns setup --domain openclaw.internal
openclaw dns setup --apply
```
## `dns setup`
規劃或套用 CoreDNS 設定，以進行單播 DNS-SD 探索。
選項：
- `--domain <domain>`：廣域探索網域（例如 `openclaw.internal`）
- `--apply`：安裝或更新 CoreDNS 設定並重新啟動服務（需要 sudo；僅限 macOS）
顯示內容：
- 已解析的探索網域
- 區域檔案路徑
- 目前的 tailnet IP
- 建議的 `openclaw.json` 探索設定
- 要設定的 Tailscale 分割 DNS 名稱伺服器/網域值
注意事項：
- 若不使用 `--apply`，此命令只作為規劃輔助工具，並會列印建議設定。
- 如果省略 `--domain`，OpenClaw 會使用設定中的 `discovery.wideArea.domain`。
- `--apply` 目前僅支援 macOS，並且需要 Homebrew CoreDNS。
- `--apply` 會在需要時啟動區域檔案，確保 CoreDNS 匯入段落存在，並重新啟動 `coredns` brew 服務。
## 相關
- [CLI 參考](/zh-TW/cli)
- [探索](/zh-TW/gateway/discovery)

39
docs/zh-TW/cli/docs.md Normal file
View File

@ -0,0 +1,39 @@
---
read_when:
- 你想要從終端機搜尋即時 OpenClaw 文件
summary: '`openclaw docs` 的 CLI 參考（搜尋即時文件索引）'
title: 文件
x-i18n:
generated_at: "2026-04-30T02:53:29Z"
model: gpt-5.5
provider: openai
source_hash: 0d208f5b9a3576ce0597abca600df109db054d20068359a9f2070ac30b1a8f69
source_path: cli/docs.md
workflow: 16
---
# `openclaw docs`
搜尋即時文件索引。
引數：
- `[query...]`：要傳送至即時文件索引的搜尋詞彙
範例：
```bash
openclaw docs
openclaw docs browser existing-session
openclaw docs sandbox allowHostControl
openclaw docs gateway token secretref
```
備註：
- 未提供查詢時，`openclaw docs` 會開啟即時文件搜尋入口。
- 多字詞查詢會作為單一搜尋要求傳遞。
## 相關內容
- [CLI 參考](/zh-TW/cli)

82
docs/zh-TW/cli/doctor.md Normal file
View File

@ -0,0 +1,82 @@
---
read_when:
- 你遇到連線/驗證問題，並想要取得引導式修復
- 你已更新並想要進行合理性檢查
summary: '`openclaw doctor` 的 CLI 參考（健康檢查 + 引導式修復）'
title: 診斷
x-i18n:
generated_at: "2026-04-30T02:53:37Z"
model: gpt-5.5
provider: openai
source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c
source_path: cli/doctor.md
workflow: 16
---
# `openclaw doctor`
Gateway 與通道的健康檢查 + 快速修復。
相關：
- 疑難排解：[疑難排解](/zh-TW/gateway/troubleshooting)
- 安全稽核：[安全性](/zh-TW/gateway/security)
## 範例
```bash
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token
```
## 選項
- `--no-workspace-suggestions`：停用工作區記憶體/搜尋建議
- `--yes`：不提示即接受預設值
- `--repair`：不提示即套用建議的修復
- `--fix`：`--repair` 的別名
- `--force`：套用積極修復，包括在需要時覆寫自訂服務設定
- `--non-interactive`：不顯示提示執行；僅進行安全遷移
- `--generate-gateway-token`：產生並設定 Gateway token
- `--deep`：掃描系統服務中的額外 Gateway 安裝
注意事項：
- 互動式提示（例如 keychain/OAuth 修復）只會在 stdin 是 TTY 且**未**設定 `--non-interactive` 時執行。無頭執行（cron、Telegram、沒有終端機）會略過提示。
- 效能：非互動式 `doctor` 執行會略過急切 Plugin 載入，讓無頭健康檢查保持快速。互動式工作階段在檢查需要 Plugin 貢獻時，仍會完整載入 Plugin。
- `--fix`（`--repair` 的別名）會將備份寫入 `~/.openclaw/openclaw.json.bak`，並移除未知設定鍵，同時列出每項移除項目。
- 狀態完整性檢查現在會偵測 sessions 目錄中的孤立 transcript 檔案。將其封存為 `.deleted.<timestamp>` 需要互動式確認；`--fix`、`--yes` 和無頭執行會將其保留在原位。
- Doctor 也會掃描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的舊版 cron job 形狀，並可在 scheduler 必須於執行階段自動正規化之前就地重寫。
- Doctor 會修復缺少的內建 Plugin 執行階段依賴項，而不寫入已封裝的全域安裝。對於 root 擁有的 npm 安裝或加固的 systemd unit，請將 `OPENCLAW_PLUGIN_STAGE_DIR` 設為可寫入目錄，例如 `/var/lib/openclaw/plugin-runtime-deps`；它也可以是路徑清單，例如 `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`，其中較前面的根目錄是唯讀查找層，最後一個根目錄是修復目標。
- Doctor 會透過從 `plugins.allow`/`plugins.entries` 移除遺失的 Plugin ID，以及在 Plugin 探索健康時移除相符的懸空通道設定、Heartbeat 目標和通道模型覆寫，來修復過期的 Plugin 設定。
- Doctor 會隔離無效的 Plugin 設定，方法是停用受影響的 `plugins.entries.<id>` 項目，並移除其無效的 `config` payload。Gateway 啟動時已經只會略過該壞掉的 Plugin，因此其他 Plugin 與通道可以繼續執行。
- 當另一個 supervisor 擁有 Gateway 生命週期時，請設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍會回報 Gateway/服務健康狀態並套用非服務修復，但會略過服務安裝/啟動/重新啟動/bootstrap 和舊版服務清理。
- 在 Linux 上，doctor 會忽略非使用中的額外類 Gateway systemd unit，且在修復期間不會為正在執行的 systemd Gateway 服務重寫 command/entrypoint metadata。當你有意替換作用中的 launcher 時，請先停止服務，或使用 `openclaw gateway install --force`。
- Doctor 會將舊版扁平 Talk 設定（`talk.voiceId`、`talk.modelId` 及相關項目）自動遷移至 `talk.provider` + `talk.providers.<provider>`。
- 重複執行 `doctor --fix` 時，如果唯一差異是物件鍵順序，將不再回報/套用 Talk 正規化。
- Doctor 包含記憶體搜尋就緒狀態檢查，並可在缺少 embedding credentials 時建議 `openclaw configure --section model`。
- Doctor 會在未設定命令擁有者時發出警告。命令擁有者是允許執行僅限擁有者命令並核准危險動作的人類操作者帳號。DM pairing 只允許某人與 bot 對話；如果你在 first-owner bootstrap 存在前核准過寄件者，請明確設定 `commands.ownerAllowFrom`。
- 如果已啟用 sandbox mode 但 Docker 不可用，doctor 會回報高訊號警告並提供修復方式（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理，且在目前命令路徑中不可用，doctor 會回報唯讀警告，且不會寫入明文 fallback credentials。
- 如果通道 SecretRef 檢查在修復路徑中失敗，doctor 會繼續並回報警告，而不是提前結束。
- Telegram `allowFrom` 使用者名稱自動解析（`doctor --fix`）需要目前命令路徑中有可解析的 Telegram token。如果 token 檢查不可用，doctor 會回報警告，並在該次執行略過自動解析。
## macOS：`launchctl` env 覆寫
如果你先前執行過 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），該值會覆寫你的設定檔，並可能導致持續的「未授權」錯誤。
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [Gateway doctor](/zh-TW/gateway/doctor)

30
docs/zh-TW/cli/flows.md Normal file
View File

@ -0,0 +1,30 @@
---
read_when:
- 你會在較舊的文件或版本資訊中遇到 openclaw 流程
summary: 重新導向：flow 命令位於 `openclaw tasks flow`
title: 流程（重新導向）
x-i18n:
generated_at: "2026-04-30T02:53:37Z"
model: gpt-5.5
provider: openai
source_hash: c818ebd740a395fdbb4d68be21a29b524b45c7348c39efd4cf6eab125c86d44c
source_path: cli/flows.md
workflow: 16
---
# `openclaw tasks flow`
流程命令是 `openclaw tasks` 的子命令，不是獨立的 `flows` 命令。
```bash
openclaw tasks flow list [--json]
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
完整文件請參閱 [TaskFlow](/zh-TW/automation/taskflow) 和 [tasks CLI 參考](/zh-TW/cli/tasks)。
## 相關
- [CLI 參考](/zh-TW/cli)
- [自動化](/zh-TW/automation)

548
docs/zh-TW/cli/gateway.md Normal file
View File

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

48
docs/zh-TW/cli/health.md Normal file
View File

@ -0,0 +1,48 @@
---
read_when:
- 您想快速檢查執行中 Gateway 的健康狀態
summary: '`openclaw health` 的 CLI 參考（透過 RPC 取得 Gateway 健康狀態快照）'
title: 健康狀態
x-i18n:
generated_at: "2026-04-30T02:53:44Z"
model: gpt-5.5
provider: openai
source_hash: bf5f5b9c3ec5c08090134764966d2657241ed0ebbd28a9dc7fafde0b8c7216d6
source_path: cli/health.md
workflow: 16
---
# `openclaw health`
從執行中的 Gateway 擷取健康狀態。
選項：
- `--json`：機器可讀輸出
- `--timeout <ms>`：連線逾時時間，以毫秒為單位（預設 `10000`）
- `--verbose`：詳細記錄
- `--debug`：`--verbose` 的別名
範例：
```bash
openclaw health
openclaw health --json
openclaw health --timeout 2500
openclaw health --verbose
openclaw health --debug
```
注意事項：
- 預設的 `openclaw health` 會向執行中的 Gateway 要求其健康狀態快照。當
Gateway 已有新鮮的快取快照時，它可以回傳該快取酬載，並在背景
重新整理。
- `--verbose` 會強制執行即時探測、列印 Gateway 連線詳細資訊，並展開
所有已設定帳戶和代理的可讀輸出。
- 設定多個代理時，輸出會包含每個代理的工作階段儲存區。
## 相關
- [CLI 參考](/zh-TW/cli)
- [Gateway 健康狀態](/zh-TW/gateway/health)

350
docs/zh-TW/cli/hooks.md Normal file
View File

@ -0,0 +1,350 @@
---
read_when:
- 您想管理代理程式掛鉤
- 您想檢查掛鉤可用性，或啟用工作區掛鉤
summary: '`openclaw hooks` 的 CLI 參考（代理程式鉤子）'
title: 掛鉤
x-i18n:
generated_at: "2026-04-30T02:53:56Z"
model: gpt-5.5
provider: openai
source_hash: 63ab6b014923dd4776767a6a0333129b85f51d008c63bb9fbdff06228d4c2f4b
source_path: cli/hooks.md
workflow: 16
---
# `openclaw hooks`
管理代理鉤子（用於 `/new`、`/reset` 和 Gateway 啟動等命令的事件驅動自動化）。
在沒有子命令的情況下執行 `openclaw hooks`，等同於 `openclaw hooks list`。
相關：
- 鉤子：[鉤子](/zh-TW/automation/hooks)
- Plugin 鉤子：[Plugin 鉤子](/zh-TW/plugins/hooks)
## 列出所有鉤子
```bash
openclaw hooks list
```
列出從工作區、受管理、額外和內建目錄中探索到的所有鉤子。
Gateway 啟動時不會載入內部鉤子處理器，直到至少設定了一個內部鉤子。
**選項：**
- `--eligible`：只顯示合格的鉤子（符合需求）
- `--json`：以 JSON 輸出
- `-v, --verbose`：顯示包含缺少需求的詳細資訊
**範例輸出：**
```
Hooks (4/4 ready)
Ready:
🚀 boot-md ✓ - Run BOOT.md on gateway startup
📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
📝 command-logger ✓ - Log all command events to a centralized audit file
💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued
```
**範例（詳細）：**
```bash
openclaw hooks list --verbose
```
顯示不合格鉤子缺少的需求。
**範例（JSON）：**
```bash
openclaw hooks list --json
```
傳回供程式使用的結構化 JSON。
## 取得鉤子資訊
```bash
openclaw hooks info <name>
```
顯示特定鉤子的詳細資訊。
**引數：**
- `<name>`：鉤子名稱或鉤子鍵（例如 `session-memory`）
**選項：**
- `--json`：以 JSON 輸出
**範例：**
```bash
openclaw hooks info session-memory
```
**輸出：**
```
💾 session-memory ✓ Ready
Save session context to memory when /new or /reset command is issued
Details:
Source: openclaw-bundled
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
Events: command:new, command:reset
Requirements:
Config: ✓ workspace.dir
```
## 檢查鉤子合格性
```bash
openclaw hooks check
```
顯示鉤子合格狀態摘要（就緒與未就緒的數量）。
**選項：**
- `--json`：以 JSON 輸出
**範例輸出：**
```
Hooks Status
Total hooks: 4
Ready: 4
Not ready: 0
```
## 啟用鉤子
```bash
openclaw hooks enable <name>
```
透過將特定鉤子新增至你的設定（預設為 `~/.openclaw/openclaw.json`）來啟用它。
**注意：** 工作區鉤子預設為停用，直到在這裡或設定中啟用為止。由 plugins 管理的鉤子會在 `openclaw hooks list` 中顯示 `plugin:<id>`，且無法在這裡啟用/停用。請改為啟用/停用該 plugin。
**引數：**
- `<name>`：鉤子名稱（例如 `session-memory`）
**範例：**
```bash
openclaw hooks enable session-memory
```
**輸出：**
```
✓ Enabled hook: 💾 session-memory
```
**它會執行的動作：**
- 檢查鉤子是否存在且合格
- 在你的設定中更新 `hooks.internal.entries.<name>.enabled = true`
- 將設定儲存至磁碟
如果鉤子來自 `<workspace>/hooks/`，則必須先完成此選擇啟用步驟，
Gateway 才會載入它。
**啟用後：**
- 重新啟動 gateway，讓鉤子重新載入（在 macOS 上重新啟動選單列應用程式，或在開發環境中重新啟動你的 gateway 程序）。
## 停用鉤子
```bash
openclaw hooks disable <name>
```
透過更新你的設定來停用特定鉤子。
**引數：**
- `<name>`：鉤子名稱（例如 `command-logger`）
**範例：**
```bash
openclaw hooks disable command-logger
```
**輸出：**
```
⏸ Disabled hook: 📝 command-logger
```
**停用後：**
- 重新啟動 gateway，讓鉤子重新載入
## 注意事項
- `openclaw hooks list --json`、`info --json` 和 `check --json` 會將結構化 JSON 直接寫入 stdout。
- Plugin 管理的鉤子無法在這裡啟用或停用；請改為啟用或停用其所屬的 plugin。
## 安裝鉤子套件
```bash
openclaw plugins install <package> # ClawHub first, then npm
openclaw plugins install npm:<package> # npm only
openclaw plugins install <package> --pin # pin version
openclaw plugins install <path> # local path
```
透過統一的 plugins 安裝器安裝鉤子套件。
`openclaw hooks install` 仍可作為相容性別名使用，但它會列印
棄用警告並轉送至 `openclaw plugins install`。
Npm 規格為**僅限 registry**（套件名稱 + 選用的**精確版本**或
**dist-tag**）。Git/URL/file 規格與 semver 範圍會被拒絕。基於安全考量，即使你的
shell 有全域 npm 安裝設定，依賴項安裝也會在專案本機以 `--ignore-scripts` 執行。
裸規格和 `@latest` 會維持在穩定軌道。如果 npm 將其中任一項解析為
預先發布版本，OpenClaw 會停止並要求你使用預先發布標籤（例如 `@beta`/`@rc`）或精確的預先發布版本明確選擇加入。
**它會執行的動作：**
- 將鉤子套件複製到 `~/.openclaw/hooks/<id>`
- 在 `hooks.internal.entries.*` 中啟用已安裝的鉤子
- 在 `hooks.internal.installs` 下記錄安裝
**選項：**
- `-l, --link`：連結本機目錄而非複製（將其新增至 `hooks.internal.load.extraDirs`）
- `--pin`：將 npm 安裝記錄為 `hooks.internal.installs` 中精確解析的 `name@version`
**支援的封存檔：** `.zip`、`.tgz`、`.tar.gz`、`.tar`
**範例：**
```bash
# Local directory
openclaw plugins install ./my-hook-pack
# Local archive
openclaw plugins install ./my-hook-pack.zip
# NPM package
openclaw plugins install @openclaw/my-hook-pack
# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack
```
連結的鉤子套件會被視為來自操作員設定目錄的受管理鉤子，
而不是工作區鉤子。
## 更新鉤子套件
```bash
openclaw plugins update <id>
openclaw plugins update --all
```
透過統一的 plugins 更新器更新受追蹤、基於 npm 的鉤子套件。
`openclaw hooks update` 仍可作為相容性別名使用，但它會列印
棄用警告並轉送至 `openclaw plugins update`。
**選項：**
- `--all`：更新所有受追蹤的鉤子套件
- `--dry-run`：顯示會變更的內容但不寫入
當已儲存的完整性雜湊存在且擷取的成品雜湊發生變更時，
OpenClaw 會列印警告並在繼續前要求確認。在 CI/非互動式執行中，請使用
全域 `--yes` 來略過提示。
## 內建鉤子
### session-memory
在你發出 `/new` 或 `/reset` 時，將工作階段情境儲存到記憶體。
**啟用：**
```bash
openclaw hooks enable session-memory
```
**輸出：** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
**另請參閱：** [session-memory 文件](/zh-TW/automation/hooks#session-memory)
### bootstrap-extra-files
在 `agent:bootstrap` 期間注入額外的 bootstrap 檔案（例如 monorepo 本機的 `AGENTS.md` / `TOOLS.md`）。
**啟用：**
```bash
openclaw hooks enable bootstrap-extra-files
```
**另請參閱：** [bootstrap-extra-files 文件](/zh-TW/automation/hooks#bootstrap-extra-files)
### command-logger
將所有命令事件記錄到集中式稽核檔案。
**啟用：**
```bash
openclaw hooks enable command-logger
```
**輸出：** `~/.openclaw/logs/commands.log`
**檢視日誌：**
```bash
# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log
# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .
# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
```
**另請參閱：** [command-logger 文件](/zh-TW/automation/hooks#command-logger)
### boot-md
在 gateway 啟動時（在 channels 啟動後）執行 `BOOT.md`。
**事件**：`gateway:startup`
**啟用**：
```bash
openclaw hooks enable boot-md
```
**另請參閱：** [boot-md 文件](/zh-TW/automation/hooks#boot-md)
## 相關
- [CLI 參考](/zh-TW/cli)
- [自動化鉤子](/zh-TW/automation/hooks)

381
docs/zh-TW/cli/index.md Normal file
View File

@ -0,0 +1,381 @@
---
read_when:
- 尋找合適的 `openclaw` 子命令
- 查閱全域旗標或輸出樣式規則
summary: OpenClaw CLI 索引：命令清單、全域旗標，以及各命令頁面的連結
title: CLI 參考
x-i18n:
generated_at: "2026-04-30T02:53:53Z"
model: gpt-5.5
provider: openai
source_hash: 522e0f156b919946756de6b933bb0a08374507401bf8639312daf52781927f33
source_path: cli/index.md
workflow: 16
---
`openclaw` 是主要的 CLI 進入點。每個核心命令都有專屬的參考頁面，或與其別名對應的命令一併記錄；此索引列出命令、全域旗標，以及套用於整個 CLI 的輸出樣式規則。
## 命令頁面
| 區域 | 命令 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 設定與入門 | [`crestodian`](/zh-TW/cli/crestodian) · [`setup`](/zh-TW/cli/setup) · [`onboard`](/zh-TW/cli/onboard) · [`configure`](/zh-TW/cli/configure) · [`config`](/zh-TW/cli/config) · [`completion`](/zh-TW/cli/completion) · [`doctor`](/zh-TW/cli/doctor) · [`dashboard`](/zh-TW/cli/dashboard) |
| 重設與解除安裝 | [`backup`](/zh-TW/cli/backup) · [`reset`](/zh-TW/cli/reset) · [`uninstall`](/zh-TW/cli/uninstall) · [`update`](/zh-TW/cli/update) |
| 訊息與代理 | [`message`](/zh-TW/cli/message) · [`agent`](/zh-TW/cli/agent) · [`agents`](/zh-TW/cli/agents) · [`acp`](/zh-TW/cli/acp) · [`mcp`](/zh-TW/cli/mcp) |
| 健康狀態與工作階段 | [`status`](/zh-TW/cli/status) · [`health`](/zh-TW/cli/health) · [`sessions`](/zh-TW/cli/sessions) |
| Gateway 與日誌 | [`gateway`](/zh-TW/cli/gateway) · [`logs`](/zh-TW/cli/logs) · [`system`](/zh-TW/cli/system) |
| 模型與推論 | [`models`](/zh-TW/cli/models) · [`infer`](/zh-TW/cli/infer) · `capability`（[`infer`](/zh-TW/cli/infer) 的別名）· [`memory`](/zh-TW/cli/memory) · [`commitments`](/zh-TW/cli/commitments) · [`wiki`](/zh-TW/cli/wiki) |
| 網路與節點 | [`directory`](/zh-TW/cli/directory) · [`nodes`](/zh-TW/cli/nodes) · [`devices`](/zh-TW/cli/devices) · [`node`](/zh-TW/cli/node) |
| 執行階段與沙箱 | [`approvals`](/zh-TW/cli/approvals) · `exec-policy`（請參閱 [`approvals`](/zh-TW/cli/approvals)）· [`sandbox`](/zh-TW/cli/sandbox) · [`tui`](/zh-TW/cli/tui) · `chat`/`terminal`（[`tui --local`](/zh-TW/cli/tui) 的別名）· [`browser`](/zh-TW/cli/browser) |
| 自動化 | [`cron`](/zh-TW/cli/cron) · [`tasks`](/zh-TW/cli/tasks) · [`hooks`](/zh-TW/cli/hooks) · [`webhooks`](/zh-TW/cli/webhooks) |
| 探索與文件 | [`dns`](/zh-TW/cli/dns) · [`docs`](/zh-TW/cli/docs) |
| 配對與通道 | [`pairing`](/zh-TW/cli/pairing) · [`qr`](/zh-TW/cli/qr) · [`channels`](/zh-TW/cli/channels) |
| 安全性與 Plugin | [`security`](/zh-TW/cli/security) · [`secrets`](/zh-TW/cli/secrets) · [`skills`](/zh-TW/cli/skills) · [`plugins`](/zh-TW/cli/plugins) · [`proxy`](/zh-TW/cli/proxy) |
| 舊版別名 | [`daemon`](/zh-TW/cli/daemon)（Gateway 服務）· [`clawbot`](/zh-TW/cli/clawbot)（命名空間） |
| Plugin（選用） | [`voicecall`](/zh-TW/cli/voicecall)（若已安裝） |
## 全域旗標
| 旗標 | 用途 |
| ----------------------- | --------------------------------------------------------------------- |
| `--dev` | 將狀態隔離在 `~/.openclaw-dev` 下，並轉移預設連接埠 |
| `--profile <name>` | 將狀態隔離在 `~/.openclaw-<name>` 下 |
| `--container <name>` | 以具名容器作為執行目標 |
| `--no-color` | 停用 ANSI 色彩（也會遵循 `NO_COLOR=1`） |
| `--update` | [`openclaw update`](/zh-TW/cli/update) 的簡寫（僅限原始碼安裝） |
| `-V`, `--version`, `-v` | 列印版本並結束 |
## 輸出模式
- ANSI 色彩與進度指示器只會在 TTY 工作階段中呈現。
- 支援時，OSC-8 超連結會呈現為可點擊連結；否則 CLI 會退回純文字 URL。
- `--json`（以及支援處的 `--plain`）會停用樣式，以產生乾淨輸出。
- 長時間執行的命令會顯示進度指示器（支援時使用 OSC 9;4）。
調色盤的唯一真實來源：`src/terminal/palette.ts`。
## 命令樹
<Accordion title="完整命令樹">
```
openclaw [--dev] [--profile <name>] <command>
crestodian
setup
onboard
configure
config
get
set
unset
file
schema
validate
completion
doctor
dashboard
backup
create
verify
security
audit
secrets
reload
audit
configure
apply
reset
uninstall
update
wizard
status
channels
list
status
capabilities
resolve
logs
add
remove
login
logout
directory
self
peers list
groups list|members
skills
search
install
update
list
info
check
plugins
list
inspect
install
uninstall
update
enable
disable
doctor
marketplace list
memory
status
index
search
commitments
list
dismiss
wiki
status
doctor
init
ingest
compile
lint
search
get
apply
bridge import
unsafe-local import
obsidian status|search|open|command|daily
message
send
broadcast
poll
react
reactions
read
edit
delete
pin
unpin
pins
permissions
search
thread create|list|reply
emoji list|upload
sticker send|upload
role info|add|remove
channel info|list
member info
voice status
event list|create
timeout
kick
ban
agent
agents
list
add
delete
bindings
bind
unbind
set-identity
acp
mcp
serve
list
show
set
unset
status
health
sessions
cleanup
tasks
list
audit
maintenance
show
notify
cancel
flow list|show|cancel
gateway
call
usage-cost
health
status
probe
discover
install
uninstall
start
stop
restart
run
daemon
status
install
uninstall
start
stop
restart
logs
system
event
heartbeat last|enable|disable
presence
models
list
status
set
set-image
aliases list|add|remove
fallbacks list|add|remove|clear
image-fallbacks list|add|remove|clear
scan
infer (alias: capability)
list
inspect
model run|list|inspect|providers|auth login|logout|status
image generate|edit|describe|describe-many|providers
audio transcribe|providers
tts convert|voices|providers|status|enable|disable|set-provider
video generate|describe|providers
web search|fetch|providers
embedding create|providers
auth add|login|login-github-copilot|setup-token|paste-token
auth order get|set|clear
sandbox
list
recreate
explain
cron
status
list
add
edit
rm
enable
disable
runs
run
nodes
status
describe
list
pending
approve
reject
rename
invoke
notify
push
canvas snapshot|present|hide|navigate|eval
canvas a2ui push|reset
camera list|snap|clip
screen record
location get
devices
list
remove
clear
approve
reject
rotate
revoke
node
run
status
install
uninstall
stop
restart
approvals
get
set
allowlist add|remove
exec-policy
show
preset
set
browser
status
start
stop
reset-profile
tabs
open
focus
close
profiles
create-profile
delete-profile
screenshot
snapshot
navigate
resize
click
type
press
hover
drag
select
upload
fill
dialog
wait
evaluate
console
pdf
hooks
list
info
check
enable
disable
install
update
webhooks
gmail setup|run
proxy
start
run
coverage
sessions
query
blob
purge
pairing
list
approve
qr
clawbot
qr
docs
dns
setup
tui
chat (alias: tui --local)
terminal (alias: tui --local)
```
Plugin 可以新增其他頂層命令（例如 `openclaw voicecall`）。
</Accordion>
## 聊天斜線命令
聊天訊息支援 `/...` 命令。請參閱[斜線命令](/zh-TW/tools/slash-commands)。
重點：
- `/status` — 快速診斷。
- `/trace` — 工作階段範圍的 Plugin 追蹤/偵錯列。
- `/config` — 持久化的設定變更。
- `/debug` — 僅限執行階段的設定覆寫（記憶體，而非磁碟；需要 `commands.debug: true`）。
## 使用量追蹤
當 OAuth/API 憑證可用時，`openclaw status --usage` 與 Control UI 會顯示供應商使用量/配額。資料直接來自供應商使用量端點，並正規化為 `X% left`。目前有使用量視窗的供應商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi 與 z.ai。
詳情請參閱[使用量追蹤](/zh-TW/concepts/usage-tracking)。
## 相關
- [斜線命令](/zh-TW/tools/slash-commands)
- [設定](/zh-TW/gateway/configuration)
- [環境](/zh-TW/help/environment)

361
docs/zh-TW/cli/infer.md Normal file
View File

@ -0,0 +1,361 @@
---
read_when:
- 新增或修改 `openclaw infer` 命令
- 設計穩定的無介面能力自動化
summary: 推論優先的 CLI，用於供應商支援的模型、影像、音訊、文字轉語音、影片、網頁和嵌入工作流程
title: 推論 CLI
x-i18n:
generated_at: "2026-04-30T02:54:09Z"
model: gpt-5.5
provider: openai
source_hash: 8a154cf11a09f6c60117740f42937da3a0e6942931dde6eee6d902fb6e0ba461
source_path: cli/infer.md
workflow: 16
---
`openclaw infer` 是供提供者支援之推論工作流程使用的標準無頭介面。
它刻意公開功能系列，而不是原始 Gateway RPC 名稱，也不是原始代理程式工具 ID。
## 將 infer 轉換為 Skills
將此內容複製並貼給代理程式：
```text
Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.
```
良好的 infer 型 Skills 應該：
- 將常見使用者意圖對應到正確的 infer 子命令
- 為其涵蓋的工作流程包含幾個標準 infer 範例
- 在範例和建議中優先使用 `openclaw infer ...`
- 避免在 Skills 內容中重新記錄整個 infer 介面
典型的 infer 聚焦 Skills 涵蓋範圍：
- `openclaw infer model run`
- `openclaw infer image generate`
- `openclaw infer audio transcribe`
- `openclaw infer tts convert`
- `openclaw infer web search`
- `openclaw infer embedding create`
## 為何使用 infer
`openclaw infer` 為 OpenClaw 內由提供者支援的推論任務提供一致的 CLI。
優點：
- 使用 OpenClaw 中已設定的提供者和模型，而不是為每個後端接線一次性的包裝器。
- 將模型、影像、音訊轉錄、TTS、影片、網頁和嵌入工作流程集中在一個命令樹下。
- 為指令碼、自動化和代理程式驅動的工作流程使用穩定的 `--json` 輸出形狀。
- 當任務本質上是「執行推論」時，優先使用第一方 OpenClaw 介面。
- 大多數 infer 命令使用一般本機路徑，不需要 Gateway。
對於端對端提供者檢查，當較低層級的
提供者測試通過後，優先使用 `openclaw infer ...`。它會在提出提供者請求前，演練已發布的 CLI、設定載入、
預設代理程式解析、內建 Plugin 啟用、執行階段相依性修復，
以及共用功能執行階段。
## 命令樹
```text
openclaw infer
list
inspect
model
run
list
inspect
providers
auth login
auth logout
auth status
image
generate
edit
describe
describe-many
providers
audio
transcribe
providers
tts
convert
voices
providers
status
enable
disable
set-provider
video
generate
describe
providers
web
search
fetch
providers
embedding
create
providers
```
## 常見任務
此表將常見推論任務對應到相應的 infer 命令。
| 任務 | 命令 | 備註 |
| ---------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| 執行文字/模型提示 | `openclaw infer model run --prompt "..." --json` | 預設使用一般本機路徑 |
| 對影像執行模型提示 | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | 對多個影像輸入重複使用 `--file` |
| 產生影像 | `openclaw infer image generate --prompt "..." --json` | 從現有檔案開始時使用 `image edit` |
| 描述影像檔案 | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` 必須是支援影像的 `<provider/model>` |
| 轉錄音訊 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必須是 `<provider/model>` |
| 合成語音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 以 Gateway 為導向 |
| 產生影片 | `openclaw infer video generate --prompt "..." --json` | 支援例如 `--resolution` 的提供者提示 |
| 描述影片檔案 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必須是 `<provider/model>` |
| 搜尋網頁 | `openclaw infer web search --query "..." --json` | |
| 擷取網頁 | `openclaw infer web fetch --url https://example.com --json` | |
| 建立嵌入 | `openclaw infer embedding create --text "..." --json` | |
## 行為
- `openclaw infer ...` 是這些工作流程的主要 CLI 介面。
- 當輸出會由另一個命令或指令碼使用時，請使用 `--json`。
- 需要特定後端時，請使用 `--provider` 或 `--model provider/model`。
- 對於 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必須使用 `<provider/model>` 形式。
- 對於 `image describe`，明確的 `--model` 會直接執行該提供者/模型。模型必須在模型目錄或提供者設定中具備影像能力。`codex/<model>` 會執行有界限的 Codex 應用程式伺服器影像理解回合；`openai-codex/<model>` 使用 OpenAI Codex OAuth 提供者路徑。
- 無狀態執行命令預設為本機。
- Gateway 管理的狀態命令預設為 Gateway。
- 一般本機路徑不需要 Gateway 正在執行。
- 本機 `model run` 是精簡的一次性提供者補全。它會解析已設定的代理程式模型和驗證，但不會啟動聊天代理程式回合、載入工具，或開啟內建 MCP 伺服器。
- `model run --file` 接受影像檔案、偵測其 MIME 類型，並將它們連同提供的提示傳送至所選模型。對多張影像重複使用 `--file`。
- `model run --file` 會拒絕非影像輸入。音訊檔案請使用 `infer audio transcribe`，影片檔案請使用 `infer video describe`。
- `model run --gateway` 會演練 Gateway 路由、已儲存的驗證、提供者選擇，以及嵌入式執行階段，但仍會以原始模型探測方式執行：它會傳送提供的提示和任何影像附件，不含先前的工作階段逐字稿、bootstrap/AGENTS 上下文、上下文引擎組裝、工具或內建 MCP 伺服器。
- `model run --gateway --model <provider/model>` 需要可信任的操作者 Gateway 認證，因為該請求要求 Gateway 執行一次性的提供者/模型覆寫。
## 模型
使用 `model` 進行由提供者支援的文字推論，以及模型/提供者檢查。
```bash
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --json
openclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --json
openclaw infer model providers --json
openclaw infer model inspect --name gpt-5.5 --json
```
使用完整 `<provider/model>` 參照來對特定提供者進行煙霧測試，而不需
啟動 Gateway 或載入完整代理程式工具介面：
```bash
openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model cerebras/zai-glm-4.7 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model groq/llama-3.1-8b-instant --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model openai/gpt-4.1 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json
```
備註：
- 本機 `model run` 是提供者/模型/驗證健康狀態最窄的 CLI 煙霧測試，因為它只會將提供的提示傳送給所選模型。
- 本機 `model run --file` 保持該精簡路徑，並將影像內容直接附加到單一使用者訊息。當 PNG、JPEG 和 WebP 等常見影像檔案的 MIME 類型被偵測為 `image/*` 時即可運作；不支援或無法辨識的檔案會在呼叫提供者前失敗。
- 當你想直接測試所選多模態文字模型時，`model run --file` 最適合。當你想使用 OpenClaw 的影像理解提供者選擇和預設影像模型路由時，請使用 `infer image describe`。
- 所選模型必須支援影像輸入；純文字模型可能會在提供者層拒絕該請求。
- `model run --prompt` 必須包含非空白文字；空提示會在呼叫本機提供者或 Gateway 前被拒絕。
- 當提供者沒有傳回文字輸出時，本機 `model run` 會以非零狀態結束，因此無法連線的本機提供者和空補全不會看起來像成功的探測。
- 當你需要測試 Gateway 路由、代理程式執行階段設定，或 Gateway 管理的提供者狀態，同時保持模型輸入為原始內容時，請使用 `model run --gateway`。當你想要完整的代理程式上下文、工具、記憶體和工作階段逐字稿時，請使用 `openclaw agent` 或聊天介面。
- `model auth login`、`model auth logout` 和 `model auth status` 管理已儲存的提供者驗證狀態。
## 影像
使用 `image` 進行產生、編輯和描述。
```bash
openclaw infer image generate --prompt "friendly lobster illustration" --json
openclaw infer image generate --prompt "cinematic product photo of headphones" --json
openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json
openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json
openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json
openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json
openclaw infer image describe --file ./photo.jpg --json
openclaw infer image describe --file ./receipt.jpg --prompt "Extract the merchant, date, and total" --json
openclaw infer image describe-many --file ./before.png --file ./after.png --prompt "Compare the screenshots and list visible UI changes" --json
openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --prompt "Describe the image in one sentence" --timeout-ms 300000 --json
```
備註：
- 從現有輸入檔案開始時，請使用 `image edit`。
- 對於支援參考影像編輯幾何提示的
提供者/模型，請搭配 `image edit` 使用 `--size`、`--aspect-ratio` 或 `--resolution`。
- 使用 `--output-format png --background transparent` 搭配
`--model openai/gpt-image-1.5` 以取得透明背景的 OpenAI PNG 輸出；
`--openai-background` 仍可作為 OpenAI 專用別名使用。未宣告背景支援的提供者
會將該提示回報為已忽略的覆寫。
- 使用 `image providers --json` 驗證哪些內建影像提供者
可被發現、已設定、已選取，以及每個提供者公開哪些產生/編輯能力。
- 使用 `image generate --model <provider/model> --json` 作為影像產生變更最窄的即時
CLI 煙霧測試。範例：
```bash
openclaw infer image providers --json
openclaw infer image generate \
--model google/gemini-3.1-flash-image-preview \
--prompt "Minimal flat test image: one blue square on a white background, no text." \
--output ./openclaw-infer-image-smoke.png \
--json
```
JSON 回應會回報 `ok`、`provider`、`model`、`attempts`，以及已寫入的
輸出路徑。設定 `--output` 時，最終副檔名可能會依照
提供者回傳的 MIME 類型。
- 對於 `image describe` 和 `image describe-many`，使用 `--prompt` 為視覺模型提供特定任務指示，例如 OCR、比較、UI 檢查或精簡字幕。
- 搭配緩慢的本機視覺模型或冷啟動的 Ollama 使用 `--timeout-ms`。
- 對於 `image describe`，`--model` 必須是具備影像能力的 `<provider/model>`。
- 對於本機 Ollama 視覺模型，請先拉取模型，並將 `OLLAMA_API_KEY` 設為任何佔位值，例如 `ollama-local`。請參閱 [Ollama](/zh-TW/providers/ollama#vision-and-image-description)。
## 音訊
使用 `audio` 進行檔案轉錄。
```bash
openclaw infer audio transcribe --file ./memo.m4a --json
openclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --json
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json
```
注意事項：
- `audio transcribe` 用於檔案轉錄，而非即時工作階段管理。
- `--model` 必須是 `<provider/model>`。
## TTS
使用 `tts` 進行語音合成與 TTS 提供者狀態查詢。
```bash
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
openclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --json
openclaw infer tts providers --json
openclaw infer tts status --json
```
注意事項：
- `tts status` 預設使用 Gateway，因為它反映由 Gateway 管理的 TTS 狀態。
- 使用 `tts providers`、`tts voices` 和 `tts set-provider` 來檢查並設定 TTS 行為。
## 影片
使用 `video` 進行生成與描述。
```bash
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
openclaw infer video generate --prompt "slow drone shot over a forest lake" --resolution 768P --duration 6 --json
openclaw infer video describe --file ./clip.mp4 --json
openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --json
```
注意事項：
- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，並將它們轉送至影片生成執行階段。
- `--model` 對於 `video describe` 必須是 `<provider/model>`。
## Web
使用 `web` 進行搜尋與擷取工作流程。
```bash
openclaw infer web search --query "OpenClaw docs" --json
openclaw infer web search --query "OpenClaw infer web providers" --json
openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json
openclaw infer web providers --json
```
注意事項：
- 使用 `web providers` 來檢查可用、已設定及已選取的提供者。
## 嵌入
使用 `embedding` 進行向量建立與嵌入提供者檢查。
```bash
openclaw infer embedding create --text "friendly lobster" --json
openclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --json
openclaw infer embedding providers --json
```
## JSON 輸出
`infer` 命令會將 JSON 輸出正規化到共用封套下：
```json
{
"ok": true,
"capability": "image.generate",
"transport": "local",
"provider": "openai",
"model": "gpt-image-2",
"attempts": [],
"outputs": []
}
```
頂層欄位是穩定的：
- `ok`
- `capability`
- `transport`
- `provider`
- `model`
- `attempts`
- `outputs`
- `error`
對於生成媒體命令，`outputs` 包含 OpenClaw 寫入的檔案。請使用
該陣列中的 `path`、`mimeType`、`size` 以及任何媒體專屬尺寸
進行自動化，而不是剖析人類可讀的 stdout。
## 常見陷阱
```bash
# Bad
openclaw infer media image generate --prompt "friendly lobster"
# Good
openclaw infer image generate --prompt "friendly lobster"
```
```bash
# Bad
openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json
# Good
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json
```
## 注意事項
- `openclaw capability ...` 是 `openclaw infer ...` 的別名。
## 相關
- [CLI 參考](/zh-TW/cli)
- [模型](/zh-TW/concepts/models)

71
docs/zh-TW/cli/logs.md Normal file
View File

@ -0,0 +1,71 @@
---
read_when:
- 你需要遠端追蹤 Gateway 日誌（不使用 SSH）
- 你需要供工具使用的 JSON 記錄行
summary: CLI 參考：`openclaw logs`（透過 RPC 追蹤 Gateway 日誌）
title: 日誌
x-i18n:
generated_at: "2026-04-30T02:54:11Z"
model: gpt-5.5
provider: openai
source_hash: 0f9268fefa4d0e54297fd12c5cef30a1465bd735ae6a36292c279a438285f2b8
source_path: cli/logs.md
workflow: 16
---
# `openclaw logs`
透過 RPC 即時追蹤 Gateway 檔案日誌（可在遠端模式使用）。
相關：
- 日誌記錄概觀：[日誌記錄](/zh-TW/logging)
- Gateway CLI：[gateway](/zh-TW/cli/gateway)
## 選項
- `--limit <n>`：要傳回的日誌行數上限（預設 `200`）
- `--max-bytes <n>`：要從日誌檔案讀取的位元組數上限（預設 `250000`）
- `--follow`：追蹤日誌串流
- `--interval <ms>`：追蹤時的輪詢間隔（預設 `1000`）
- `--json`：輸出以行分隔的 JSON 事件
- `--plain`：不含樣式格式的純文字輸出
- `--no-color`：停用 ANSI 色彩
- `--local-time`：以你的本機時區呈現時間戳記
## 共用 Gateway RPC 選項
`openclaw logs` 也接受標準的 Gateway 用戶端旗標：
- `--url <url>`：Gateway WebSocket URL
- `--token <token>`：Gateway token
- `--timeout <ms>`：逾時時間，以毫秒為單位（預設 `30000`）
- `--expect-final`：當 Gateway 呼叫由代理支援時，等待最終回應
當你傳入 `--url` 時，CLI 不會自動套用設定或環境憑證。如果目標 Gateway 需要驗證，請明確包含 `--token`。
## 範例
```bash
openclaw logs
openclaw logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --limit 500
openclaw logs --local-time
openclaw logs --follow --local-time
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
```
## 注意事項
- 使用 `--local-time` 以你的本機時區呈現時間戳記。
- 如果隱含的 local loopback Gateway 要求配對、在連線期間關閉，或在 `logs.tail` 回應前逾時，`openclaw logs` 會自動退回到已設定的 Gateway 檔案日誌。明確的 `--url` 目標不會使用這個退回機制。
## 相關
- [CLI 參考](/zh-TW/cli)
- [Gateway 日誌記錄](/zh-TW/gateway/logging)

525
docs/zh-TW/cli/mcp.md Normal file
View File

@ -0,0 +1,525 @@
---
read_when:
- 將 Codex、Claude Code 或其他 MCP 用戶端連接到 OpenClaw 支援的頻道
- 正在執行 `openclaw mcp serve`
- 管理 OpenClaw 儲存的 MCP 伺服器定義
sidebarTitle: MCP
summary: 透過 MCP 公開 OpenClaw 頻道對話，並管理已儲存的 MCP 伺服器定義
title: MCP
x-i18n:
generated_at: "2026-04-30T02:54:22Z"
model: gpt-5.5
provider: openai
source_hash: d66ec20b81ab3894c7202ee1c1c6666bd9cdeffc8d48a280b1f298bb358887ef
source_path: cli/mcp.md
workflow: 16
---
`openclaw mcp` 有兩項工作：
- 使用 `openclaw mcp serve` 將 OpenClaw 作為 MCP 伺服器執行
- 使用 `list`、`show`、`set` 和 `unset` 管理 OpenClaw 擁有的外送 MCP 伺服器定義
換句話說：
- `serve` 是 OpenClaw 作為 MCP 伺服器運作
- `list` / `show` / `set` / `unset` 是 OpenClaw 作為 MCP 用戶端側登錄檔運作，供其執行階段稍後可能取用的其他 MCP 伺服器使用
當 OpenClaw 應自行託管編碼工具組工作階段，並透過 ACP 路由該執行階段時，請使用 [`openclaw acp`](/zh-TW/cli/acp)。
## OpenClaw 作為 MCP 伺服器
這是 `openclaw mcp serve` 路徑。
### 何時使用 `serve`
在下列情況使用 `openclaw mcp serve`：
- Codex、Claude Code 或其他 MCP 用戶端應直接與 OpenClaw 支援的頻道對話溝通
- 你已經有本機或遠端 OpenClaw Gateway，且其中有已路由的工作階段
- 你想要一個可跨 OpenClaw 頻道後端運作的 MCP 伺服器，而不是執行各頻道各自的橋接器
當 OpenClaw 應自行託管編碼執行階段，並將代理程式工作階段保留在 OpenClaw 內時，請改用 [`openclaw acp`](/zh-TW/cli/acp)。
### 運作方式
`openclaw mcp serve` 會啟動 stdio MCP 伺服器。MCP 用戶端擁有該程序。只要用戶端保持 stdio 工作階段開啟，橋接器就會透過 WebSocket 連線至本機或遠端 OpenClaw Gateway，並透過 MCP 暴露已路由的頻道對話。
<Steps>
<Step title="用戶端產生橋接器">
MCP 用戶端會產生 `openclaw mcp serve`。
</Step>
<Step title="橋接器連線至 Gateway">
橋接器會透過 WebSocket 連線至 OpenClaw Gateway。
</Step>
<Step title="工作階段成為 MCP 對話">
已路由的工作階段會成為 MCP 對話與逐字稿/歷史工具。
</Step>
<Step title="即時事件佇列">
橋接器連線期間，即時事件會在記憶體中排入佇列。
</Step>
<Step title="選用 Claude 推送">
如果啟用 Claude 頻道模式，同一個工作階段也可以接收 Claude 專用推送通知。
</Step>
</Steps>
<AccordionGroup>
<Accordion title="重要行為">
- 即時佇列狀態會在橋接器連線時開始
- 較舊的逐字稿歷史會透過 `messages_read` 讀取
- Claude 推送通知只會在 MCP 工作階段存活期間存在
- 當用戶端中斷連線時，橋接器會結束，且即時佇列會消失
- `openclaw agent` 和 `openclaw infer model run` 等一次性代理程式進入點會在回覆完成時淘汰其開啟的任何內建 MCP 執行階段，因此重複的腳本化執行不會累積 stdio MCP 子程序
- 由 OpenClaw 啟動的 stdio MCP 伺服器（內建或使用者設定）會在關閉時以程序樹形式拆除，因此伺服器啟動的子程序不會在父 stdio 用戶端結束後存活
- 刪除或重設工作階段會透過共用執行階段清理路徑處置該工作階段的 MCP 用戶端，因此不會有綁定至已移除工作階段的殘留 stdio 連線
</Accordion>
</AccordionGroup>
### 選擇用戶端模式
以兩種不同方式使用相同橋接器：
<Tabs>
<Tab title="通用 MCP 用戶端">
僅標準 MCP 工具。使用 `conversations_list`、`messages_read`、`events_poll`、`events_wait`、`messages_send` 和核准工具。
</Tab>
<Tab title="Claude Code">
標準 MCP 工具加上 Claude 專用頻道配接器。啟用 `--claude-channel-mode on`，或保留預設值 `auto`。
</Tab>
</Tabs>
<Note>
目前，`auto` 的行為與 `on` 相同。尚未有用戶端能力偵測。
</Note>
### `serve` 暴露的內容
橋接器會使用現有 Gateway 工作階段路由中繼資料來暴露頻道支援的對話。當 OpenClaw 已有含已知路由的工作階段狀態時，對話就會出現，例如：
- `channel`
- 接收者或目的地中繼資料
- 選用 `accountId`
- 選用 `threadId`
這讓 MCP 用戶端能在一處：
- 列出最近已路由的對話
- 讀取最近的逐字稿歷史
- 等待新的入站事件
- 透過相同路由傳送回覆
- 查看橋接器連線期間到達的核准要求
### 用法
<Tabs>
<Tab title="本機 Gateway">
```bash
openclaw mcp serve
```
</Tab>
<Tab title="遠端 Gateway（權杖）">
```bash
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
```
</Tab>
<Tab title="遠端 Gateway（密碼）">
```bash
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
```
</Tab>
<Tab title="詳細 / Claude 關閉">
```bash
openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off
```
</Tab>
</Tabs>
### 橋接工具
目前橋接器會暴露這些 MCP 工具：
<AccordionGroup>
<Accordion title="conversations_list">
列出最近已有 Gateway 工作階段狀態中路由中繼資料的工作階段支援對話。
實用篩選器：
- `limit`
- `search`
- `channel`
- `includeDerivedTitles`
- `includeLastMessage`
</Accordion>
<Accordion title="conversation_get">
依 `session_key` 傳回一個對話。
</Accordion>
<Accordion title="messages_read">
讀取一個工作階段支援對話的最近逐字稿訊息。
</Accordion>
<Accordion title="attachments_fetch">
從一則逐字稿訊息擷取非文字訊息內容區塊。這是逐字稿內容上的中繼資料檢視，不是獨立的持久附件 blob 儲存庫。
</Accordion>
<Accordion title="events_poll">
讀取自數值游標以來已排入佇列的即時事件。
</Accordion>
<Accordion title="events_wait">
長輪詢直到下一個相符的已排入佇列事件到達，或逾時到期。
當通用 MCP 用戶端需要接近即時的傳遞，但沒有 Claude 專用推送通訊協定時，請使用此工具。
</Accordion>
<Accordion title="messages_send">
透過工作階段上已記錄的相同路由傳回文字。
目前行為：
- 需要現有對話路由
- 使用工作階段的頻道、接收者、帳號 ID 和討論串 ID
- 僅傳送文字
</Accordion>
<Accordion title="permissions_list_open">
列出橋接器自連線至 Gateway 以來觀察到的待處理 exec/Plugin 核准要求。
</Accordion>
<Accordion title="permissions_respond">
使用以下其中一項解決一個待處理 exec/Plugin 核准要求：
- `allow-once`
- `allow-always`
- `deny`
</Accordion>
</AccordionGroup>
### 事件模型
橋接器在連線期間會保留記憶體內事件佇列。
目前事件類型：
- `message`
- `exec_approval_requested`
- `exec_approval_resolved`
- `plugin_approval_requested`
- `plugin_approval_resolved`
- `claude_permission_request`
<Warning>
- 佇列僅限即時；它會在 MCP 橋接器啟動時開始
- `events_poll` 和 `events_wait` 本身不會重播較舊的 Gateway 歷史
- 持久待處理記錄應使用 `messages_read` 讀取
</Warning>
### Claude 頻道通知
橋接器也可以暴露 Claude 專用頻道通知。這是 OpenClaw 中對應 Claude Code 頻道配接器的功能：標準 MCP 工具仍然可用，但即時入站訊息也可以作為 Claude 專用 MCP 通知到達。
<Tabs>
<Tab title="off">
`--claude-channel-mode off`：僅標準 MCP 工具。
</Tab>
<Tab title="on">
`--claude-channel-mode on`：啟用 Claude 頻道通知。
</Tab>
<Tab title="auto（預設）">
`--claude-channel-mode auto`：目前預設值；橋接器行為與 `on` 相同。
</Tab>
</Tabs>
啟用 Claude 頻道模式時，伺服器會宣告 Claude 實驗性能力，並可發出：
- `notifications/claude/channel`
- `notifications/claude/channel/permission`
目前橋接器行為：
- 入站 `user` 逐字稿訊息會轉送為 `notifications/claude/channel`
- 透過 MCP 接收的 Claude 權限要求會在記憶體中追蹤
- 如果連結的對話稍後傳送 `yes abcde` 或 `no abcde`，橋接器會將其轉換為 `notifications/claude/channel/permission`
- 這些通知僅限即時工作階段；如果 MCP 用戶端中斷連線，就沒有推送目標
這是刻意為特定用戶端設計。通用 MCP 用戶端應依賴標準輪詢工具。
### MCP 用戶端設定
stdio 用戶端設定範例：
```json
{
"mcpServers": {
"openclaw": {
"command": "openclaw",
"args": [
"mcp",
"serve",
"--url",
"wss://gateway-host:18789",
"--token-file",
"/path/to/gateway.token"
]
}
}
}
```
對大多數通用 MCP 用戶端，請從標準工具介面開始，並忽略 Claude 模式。只有在用戶端實際理解 Claude 專用通知方法時，才開啟 Claude 模式。
### 選項
`openclaw mcp serve` 支援：
<ParamField path="--url" type="string">
Gateway WebSocket URL。
</ParamField>
<ParamField path="--token" type="string">
Gateway 權杖。
</ParamField>
<ParamField path="--token-file" type="string">
從檔案讀取權杖。
</ParamField>
<ParamField path="--password" type="string">
Gateway 密碼。
</ParamField>
<ParamField path="--password-file" type="string">
從檔案讀取密碼。
</ParamField>
<ParamField path="--claude-channel-mode" type='"auto" | "on" | "off"'>
Claude 通知模式。
</ParamField>
<ParamField path="-v, --verbose" type="boolean">
stderr 上的詳細記錄。
</ParamField>
<Tip>
可行時，偏好使用 `--token-file` 或 `--password-file`，而不是行內祕密。
</Tip>
### 安全性與信任邊界
橋接器不會自行發明路由。它只會暴露 Gateway 已知如何路由的對話。
這表示：
- 傳送者允許清單、配對和頻道層級信任仍屬於底層 OpenClaw 頻道設定
- `messages_send` 只能透過現有已儲存路由回覆
- 核准狀態僅對目前橋接器工作階段即時/記憶體內有效
- 橋接器驗證應使用你會信任任何其他遠端 Gateway 用戶端的相同 Gateway 權杖或密碼控制
如果某個對話未出現在 `conversations_list` 中，通常原因不是 MCP 設定，而是底層 Gateway 工作階段中的路由中繼資料缺失或不完整。
### 測試
OpenClaw 隨附此橋接器的確定性 Docker smoke：
```bash
pnpm test:docker:mcp-channels
```
該 smoke 會：
- 啟動已植入資料的 Gateway 容器
- 啟動第二個容器，並產生 `openclaw mcp serve`
- 驗證對話探索、逐字稿讀取、附件中繼資料讀取、即時事件佇列行為，以及外送傳送路由
- 透過真實 stdio MCP 橋接器驗證 Claude 風格的頻道與權限通知
這是在不將真實 Telegram、Discord 或 iMessage 帳號接入測試執行的情況下，證明橋接器可運作的最快方式。
如需更廣泛的測試背景，請參閱 [測試](/zh-TW/help/testing)。
### 疑難排解
<AccordionGroup>
<Accordion title="未傳回任何對話">
通常表示 Gateway 工作階段尚不可路由。確認底層工作階段已儲存頻道/供應者、接收者，以及選用帳號/討論串路由中繼資料。
</Accordion>
<Accordion title="events_poll 或 events_wait 遺漏較舊訊息">
預期行為。即時佇列會在橋接器連線時開始。使用 `messages_read` 讀取較舊的逐字稿歷史。
</Accordion>
<Accordion title="Claude 通知未顯示">
檢查以下所有項目：
- 用戶端保持 stdio MCP 工作階段開啟
- `--claude-channel-mode` 為 `on` 或 `auto`
- 用戶端實際理解 Claude 專用通知方法
- 入站訊息發生在橋接器連線之後
</Accordion>
<Accordion title="核准缺失">
`permissions_list_open` 只會顯示橋接器連線期間觀察到的核准要求。它不是持久核准歷史 API。
</Accordion>
</AccordionGroup>
## OpenClaw 作為 MCP 用戶端登錄檔
這是 `openclaw mcp list`、`show`、`set` 和 `unset` 路徑。
這些命令不會透過 MCP 公開 OpenClaw。它們會管理 OpenClaw 設定中 `mcp.servers` 底下由 OpenClaw 擁有的 MCP 伺服器定義。
這些已儲存的定義用於 OpenClaw 稍後啟動或設定的執行階段，例如嵌入式 Pi 和其他執行階段轉接器。OpenClaw 會集中儲存這些定義，讓那些執行階段不需要維護自己的重複 MCP 伺服器清單。
<AccordionGroup>
<Accordion title="重要行為">
- 這些命令只會讀取或寫入 OpenClaw 設定
- 它們不會連線到目標 MCP 伺服器
- 它們不會驗證命令、URL 或遠端傳輸目前是否可連線
- 執行階段轉接器會在執行時決定它們實際支援哪些傳輸形狀
- 嵌入式 Pi 會在一般 `coding` 和 `messaging` 工具設定檔中公開已設定的 MCP 工具；`minimal` 仍會隱藏它們，而 `tools.deny: ["bundle-mcp"]` 會明確停用它們
- 工作階段範圍的 bundled MCP 執行階段會在閒置 `mcp.sessionIdleTtlMs` 毫秒後被清理（預設 10 分鐘；設為 `0` 可停用），而一次性的嵌入式執行會在執行結束時清理它們
</Accordion>
</AccordionGroup>
執行階段轉接器可能會將這個共用登錄正規化為其下游用戶端預期的形狀。例如，嵌入式 Pi 會直接使用 OpenClaw `transport` 值，而 Claude Code 和 Gemini 會接收 CLI 原生的 `type` 值，例如 `http`、`sse` 或 `stdio`。
### 已儲存的 MCP 伺服器定義
OpenClaw 也會在設定中儲存輕量級 MCP 伺服器登錄，供需要由 OpenClaw 管理 MCP 定義的介面使用。
命令：
- `openclaw mcp list`
- `openclaw mcp show [name]`
- `openclaw mcp set <name> <json>`
- `openclaw mcp unset <name>`
注意事項：
- `list` 會排序伺服器名稱。
- 未指定名稱的 `show` 會印出完整設定的 MCP 伺服器物件。
- `set` 需要在命令列上提供一個 JSON 物件值。
- 對 Streamable HTTP MCP 伺服器使用 `transport: "streamable-http"`。`openclaw mcp set` 也會將 CLI 原生的 `type: "http"` 正規化為相同的標準設定形狀，以維持相容性。
- 如果具名伺服器不存在，`unset` 會失敗。
範例：
```bash
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp unset context7
```
設定形狀範例：
```json
{
"mcp": {
"servers": {
"context7": {
"command": "uvx",
"args": ["context7-mcp"]
},
"docs": {
"url": "https://mcp.example.com",
"transport": "streamable-http"
}
}
}
}
```
### Stdio 傳輸
啟動本機子程序，並透過 stdin/stdout 通訊。
| 欄位 | 說明 |
| -------------------------- | ---------------------------- |
| `command` | 要產生的可執行檔（必要） |
| `args` | 命令列引數陣列 |
| `env` | 額外環境變數 |
| `cwd` / `workingDirectory` | 程序的工作目錄 |
<Warning>
**Stdio env 安全篩選器**
OpenClaw 會拒絕可在第一個 RPC 之前改變 stdio MCP 伺服器啟動方式的直譯器啟動 env 鍵，即使它們出現在伺服器的 `env` 區塊中也一樣。封鎖的鍵包含 `NODE_OPTIONS`、`PYTHONSTARTUP`、`PYTHONPATH`、`PERL5OPT`、`RUBYOPT`、`SHELLOPTS`、`PS4` 以及類似的執行階段控制變數。啟動時會以設定錯誤拒絕這些鍵，因此它們無法注入隱含前置內容、替換直譯器，或針對 stdio 程序啟用偵錯器。一般憑證、Proxy 和伺服器專用 env 變數（`GITHUB_TOKEN`、`HTTP_PROXY`、自訂 `*_API_KEY` 等）不受影響。
如果你的 MCP 伺服器確實需要其中一個被封鎖的變數，請在 gateway 主機程序上設定它，而不是放在 stdio 伺服器的 `env` 底下。
</Warning>
### SSE / HTTP 傳輸
透過 HTTP Server-Sent Events 連線到遠端 MCP 伺服器。
| 欄位 | 說明 |
| --------------------- | ---------------------------------------------- |
| `url` | 遠端伺服器的 HTTP 或 HTTPS URL（必要） |
| `headers` | 選用的 HTTP 標頭鍵值對應（例如驗證 token） |
| `connectionTimeoutMs` | 每個伺服器的連線逾時時間，以 ms 為單位（選用） |
範例：
```json
{
"mcp": {
"servers": {
"remote-tools": {
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
`url`（userinfo）和 `headers` 中的敏感值會在記錄和狀態輸出中遮蔽。
### Streamable HTTP 傳輸
`streamable-http` 是 `sse` 和 `stdio` 之外的另一個傳輸選項。它使用 HTTP 串流與遠端 MCP 伺服器進行雙向通訊。
| 欄位 | 說明 |
| --------------------- | ------------------------------------------------------------------------------------ |
| `url` | 遠端伺服器的 HTTP 或 HTTPS URL（必要） |
| `transport` | 設為 `"streamable-http"` 以選取此傳輸；省略時，OpenClaw 會使用 `sse` |
| `headers` | 選用的 HTTP 標頭鍵值對應（例如驗證 token） |
| `connectionTimeoutMs` | 每個伺服器的連線逾時時間，以 ms 為單位（選用） |
OpenClaw 設定會使用 `transport: "streamable-http"` 作為標準拼法。透過 `openclaw mcp set` 儲存時會接受 CLI 原生的 MCP `type: "http"` 值，且現有設定會由 `openclaw doctor --fix` 修復，但 `transport` 才是嵌入式 Pi 直接使用的值。
範例：
```json
{
"mcp": {
"servers": {
"streaming-tools": {
"url": "https://mcp.example.com/stream",
"transport": "streamable-http",
"connectionTimeoutMs": 10000,
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
<Note>
這些命令只管理已儲存的設定。它們不會啟動頻道橋接器、開啟即時 MCP 用戶端工作階段，或證明目標伺服器可連線。
</Note>
## 目前限制
本頁記錄的是目前已發布的橋接器。
目前限制：
- 對話探索取決於既有的 Gateway 工作階段路由中繼資料
- 除了 Claude 專用轉接器之外，沒有通用推送協定
- 尚無訊息編輯或反應工具
- HTTP/SSE/streamable-http 傳輸會連線到單一遠端伺服器；尚無多工上游
- `permissions_list_open` 只包含橋接器連線期間觀察到的核准
## 相關
- [CLI 參考](/zh-TW/cli)
- [Plugin](/zh-TW/cli/plugins)

188
docs/zh-TW/cli/memory.md Normal file
View File

@ -0,0 +1,188 @@
---
read_when:
- 你想要索引或搜尋語意記憶
- 你正在偵錯記憶體可用性或索引建立
- 您想要將已召回的短期記憶提升為 `MEMORY.md`
summary: '`openclaw memory` 的 CLI 參考（status/index/search/promote/promote-explain/rem-harness）'
title: 記憶
x-i18n:
generated_at: "2026-04-30T02:54:38Z"
model: gpt-5.5
provider: openai
source_hash: 53301e82d4ebe72b161b3a58078e7b75b9e499bc55cbceec5032c7e410619bd4
source_path: cli/memory.md
workflow: 16
---
# `openclaw memory`
管理語意記憶索引與搜尋。
由 Active Memory Plugin 提供（預設：`memory-core`；設定 `plugins.slots.memory = "none"` 可停用）。
相關：
- 記憶概念：[Memory](/zh-TW/concepts/memory)
- 記憶 wiki：[Memory Wiki](/zh-TW/plugins/memory-wiki)
- Wiki CLI：[wiki](/zh-TW/cli/wiki)
- Plugins：[Plugins](/zh-TW/tools/plugin)
## 範例
```bash
openclaw memory status
openclaw memory status --deep
openclaw memory status --fix
openclaw memory index --force
openclaw memory search "meeting notes"
openclaw memory search --query "deployment" --max-results 20
openclaw memory promote --limit 10 --min-score 0.75
openclaw memory promote --apply
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
openclaw memory rem-harness
openclaw memory rem-harness --json
openclaw memory status --json
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose
```
## 選項
`memory status` 和 `memory index`：
- `--agent <id>`：限定於單一代理程式。若未指定，這些命令會針對每個已設定的代理程式執行；如果未設定代理程式清單，則會退回使用預設代理程式。
- `--verbose`：在探測與索引期間輸出詳細記錄。
`memory status`：
- `--deep`：探測向量 + embedding 可用性。一般的 `memory status` 會保持快速，且不會執行即時 embedding ping。QMD 詞彙 `searchMode: "search"` 即使搭配 `--deep`，也會略過語意向量探測與 embedding 維護。
- `--index`：如果儲存區是髒的，則執行重新索引（意味著 `--deep`）。
- `--fix`：修復過期的回憶鎖定並正規化提升中繼資料。
- `--json`：列印 JSON 輸出。
如果 `memory status` 顯示 `Dreaming status: blocked`，代表受管理的 dreaming cron 已啟用，但驅動它的 Heartbeat 未針對預設代理程式觸發。請參閱 [Dreaming 永遠不會執行](/zh-TW/concepts/dreaming#dreaming-never-runs-status-shows-blocked)，了解兩個常見原因。
`memory index`：
- `--force`：強制完整重新索引。
`memory search`：
- 查詢輸入：傳入位置參數 `[query]` 或 `--query <text>`。
- 如果兩者皆提供，會以 `--query` 為準。
- 如果兩者皆未提供，命令會以錯誤結束。
- `--agent <id>`：限定於單一代理程式（預設：預設代理程式）。
- `--max-results <n>`：限制傳回的結果數量。
- `--min-score <n>`：篩除低分相符項目。
- `--json`：列印 JSON 結果。
`memory promote`：
預覽並套用短期記憶提升。
```bash
openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
```
- `--apply` -- 將提升寫入 `MEMORY.md`（預設：僅預覽）。
- `--limit <n>` -- 限制顯示的候選項目數量。
- `--include-promoted` -- 包含先前週期中已提升的項目。
完整選項：
- 使用加權提升訊號（`frequency`、`relevance`、`query diversity`、`recency`、`consolidation`、`conceptual richness`）對來自 `memory/YYYY-MM-DD.md` 的短期候選項目排序。
- 使用來自記憶回憶與每日擷取流程的短期訊號，加上 light/REM 階段強化訊號。
- 啟用 Dreaming 時，`memory-core` 會自動管理一個在背景執行完整掃描（`light -> REM -> deep`）的 cron 工作（不需要手動 `openclaw cron add`）。
- `--agent <id>`：限定於單一代理程式（預設：預設代理程式）。
- `--limit <n>`：要傳回/套用的最大候選項目數。
- `--min-score <n>`：最低加權提升分數。
- `--min-recall-count <n>`：候選項目所需的最低回憶次數。
- `--min-unique-queries <n>`：候選項目所需的最低相異查詢數。
- `--apply`：將選取的候選項目附加到 `MEMORY.md`，並標記為已提升。
- `--include-promoted`：在輸出中包含已提升的候選項目。
- `--json`：列印 JSON 輸出。
`memory promote-explain`：
說明特定提升候選項目及其分數明細。
```bash
openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]
```
- `<selector>`：要查找的候選鍵、路徑片段或片段內容。
- `--agent <id>`：限定於單一代理程式（預設：預設代理程式）。
- `--include-promoted`：包含已提升的候選項目。
- `--json`：列印 JSON 輸出。
`memory rem-harness`：
預覽 REM 反思、候選真相與深層提升輸出，不寫入任何內容。
```bash
openclaw memory rem-harness [--agent <id>] [--include-promoted] [--json]
```
- `--agent <id>`：限定於單一代理程式（預設：預設代理程式）。
- `--include-promoted`：包含已提升的深層候選項目。
- `--json`：列印 JSON 輸出。
## Dreaming
Dreaming 是背景記憶整合系統，包含三個協作
階段：**light**（排序/暫存短期素材）、**deep**（將耐久
事實提升到 `MEMORY.md`），以及 **REM**（反思並浮現主題）。
- 使用 `plugins.entries.memory-core.config.dreaming.enabled: true` 啟用。
- 透過聊天中的 `/dreaming on|off` 切換（或用 `/dreaming status` 檢查）。
- Dreaming 會依一個受管理的掃描排程（`dreaming.frequency`）執行，並依序執行階段：light、REM、deep。
- 只有 deep 階段會將耐久記憶寫入 `MEMORY.md`。
- 人類可讀的階段輸出與日記項目會寫入 `DREAMS.md`（或既有的 `dreams.md`），並可選擇在 `memory/dreaming/<phase>/YYYY-MM-DD.md` 寫入各階段報告。
- 排序使用加權訊號：回憶頻率、擷取相關性、查詢多樣性、時間近因、跨日整合，以及衍生概念豐富度。
- 提升會在寫入 `MEMORY.md` 前重新讀取即時每日筆記，因此已編輯或刪除的短期片段不會從過期的回憶儲存區快照被提升。
- 排程與手動 `memory promote` 執行會共用相同的 deep 階段預設值，除非你傳入 CLI 閾值覆寫。
- 自動執行會展開到所有已設定的記憶工作區。
預設排程：
- **掃描節奏**：`dreaming.frequency = 0 3 * * *`
- **Deep 閾值**：`minScore=0.8`、`minRecallCount=3`、`minUniqueQueries=3`、`recencyHalfLifeDays=14`、`maxAgeDays=30`
範例：
```json
{
"plugins": {
"entries": {
"memory-core": {
"config": {
"dreaming": {
"enabled": true
}
}
}
}
}
}
```
注意事項：
- `memory index --verbose` 會列印各階段細節（供應者、模型、來源、批次活動）。
- `memory status` 會包含任何透過 `memorySearch.extraPaths` 設定的額外路徑。
- 如果實際啟用的 Active Memory 遠端 API 金鑰欄位設定為 SecretRefs，命令會從作用中的 Gateway 快照解析這些值。如果 Gateway 不可用，命令會快速失敗。
- Gateway 版本偏差注意事項：此命令路徑需要支援 `secrets.resolve` 的 Gateway；較舊的 Gateway 會傳回未知方法錯誤。
- 使用 `dreaming.frequency` 調整排程掃描節奏。Deep 提升政策除此之外屬於內部機制；需要一次性手動覆寫時，請在 `memory promote` 使用 CLI 旗標。
- `memory rem-harness --path <file-or-dir> --grounded` 會從歷史每日筆記預覽有根據的 `What Happened`、`Reflections` 和 `Possible Lasting Updates`，不寫入任何內容。
- `memory rem-backfill --path <file-or-dir>` 會將可逆的有根據日記項目寫入 `DREAMS.md`，供 UI 檢閱。
- `memory rem-backfill --path <file-or-dir> --stage-short-term` 也會將有根據的耐久候選項目植入即時短期提升儲存區，讓正常 deep 階段可以對它們排序。
- `memory rem-backfill --rollback` 會移除先前寫入的有根據日記項目，而 `memory rem-backfill --rollback-short-term` 會移除先前暫存的有根據短期候選項目。
- 請參閱 [Dreaming](/zh-TW/concepts/dreaming)，取得完整階段說明與設定參考。
## 相關
- [CLI 參考](/zh-TW/cli)
- [記憶概覽](/zh-TW/concepts/memory)

311
docs/zh-TW/cli/message.md Normal file
View File

@ -0,0 +1,311 @@
---
read_when:
- 新增或修改訊息 CLI 動作
- 變更出站通道行為
summary: CLI 參考：`openclaw message`（傳送 + 頻道動作）
title: 訊息
x-i18n:
generated_at: "2026-04-30T02:54:27Z"
model: gpt-5.5
provider: openai
source_hash: 43f14b3815d89c92a7503e620e2424f41a3f6b92e20e089504017305b19bace4
source_path: cli/message.md
workflow: 16
---
# `openclaw message`
用於傳送訊息與頻道動作的單一對外命令
（Discord/Google Chat/iMessage/Matrix/Mattermost（Plugin）/Microsoft Teams/Signal/Slack/Telegram/WhatsApp）。
## 使用方式
```
openclaw message <subcommand> [flags]
```
頻道選擇：
- 如果設定了多個頻道，則必須提供 `--channel`。
- 如果只設定了一個頻道，該頻道會成為預設值。
- 值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost 需要 Plugin）
- 當存在 `--channel` 或帶有頻道前綴的目標時，`openclaw message` 會將所選頻道解析為其所屬的 Plugin；否則會載入已設定的頻道 Plugin 以推斷預設頻道。
目標格式（`--target`）：
- WhatsApp：E.164 或群組 JID
- Telegram：聊天 ID 或 `@username`
- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；原始數字 ID 會被視為頻道）
- Google Chat：`spaces/<spaceId>` 或 `users/<userId>`
- Slack：`channel:<id>` 或 `user:<id>`（接受原始頻道 ID）
- Mattermost（Plugin）：`channel:<id>`、`user:<id>` 或 `@username`（裸 ID 會被視為頻道）
- Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>`，或 `username:<name>`/`u:<name>`
- iMessage：控制代碼、`chat_id:<id>`、`chat_guid:<guid>` 或 `chat_identifier:<id>`
- Matrix：`@user:server`、`!room:server` 或 `#alias:server`
- Microsoft Teams：對話 ID（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
名稱查找：
- 對於支援的提供者（Discord/Slack/等），像 `Help` 或 `#help` 這樣的頻道名稱會透過目錄快取解析。
- 快取未命中時，如果提供者支援，OpenClaw 會嘗試即時目錄查找。
## 常用旗標
- `--channel <name>`
- `--account <id>`
- `--target <dest>`（傳送/輪詢/讀取等的目標頻道或使用者）
- `--targets <name>`（可重複；僅廣播）
- `--json`
- `--dry-run`
- `--verbose`
## SecretRef 行為
- `openclaw message` 會在執行所選動作前解析支援頻道的 SecretRefs。
- 可行時，解析範圍會限定在作用中的動作目標：
- 設定 `--channel` 時（或從像 `discord:...` 這樣的前綴目標推斷時）以頻道為範圍
- 設定 `--account` 時以帳號為範圍（頻道全域 + 所選帳號表面）
- 省略 `--account` 時，OpenClaw 不會強制使用 `default` 帳號 SecretRef 範圍
- 不相關頻道上未解析的 SecretRefs 不會阻擋目標訊息動作。
- 如果所選頻道/帳號 SecretRef 未解析，該命令會對該動作以關閉方式失敗。
## 動作
### 核心
- `send`
- 頻道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（Plugin）/Signal/iMessage/Matrix/Microsoft Teams
- 必要：`--target`，以及 `--message`、`--media` 或 `--presentation`
- 可選：`--media`、`--presentation`、`--delivery`、`--pin`、`--reply-to`、`--thread-id`、`--gif-playback`、`--force-document`、`--silent`
- 共用呈現承載：`--presentation` 傳送語意區塊（`text`、`context`、`divider`、`buttons`、`select`），核心會透過所選頻道宣告的能力進行呈現。請參閱[訊息呈現](/zh-TW/plugins/message-presentation)。
- 通用傳遞偏好設定：`--delivery` 接受像 `{ "pin": true }` 這樣的傳遞提示；在頻道支援時，`--pin` 是釘選傳遞的簡寫。
- 僅 Telegram：`--force-document`（將圖片與 GIF 作為文件傳送，以避免 Telegram 壓縮）
- 僅 Telegram：`--thread-id`（論壇主題 ID）
- 僅 Slack：`--thread-id`（討論串時間戳；`--reply-to` 使用同一欄位）
- Telegram + Discord：`--silent`
- 僅 WhatsApp：`--gif-playback`
- `poll`
- 頻道：WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
- 必要：`--target`、`--poll-question`、`--poll-option`（可重複）
- 可選：`--poll-multi`
- 僅 Discord：`--poll-duration-hours`、`--silent`、`--message`
- 僅 Telegram：`--poll-duration-seconds`（5-600）、`--silent`、`--poll-anonymous` / `--poll-public`、`--thread-id`
- `react`
- 頻道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
- 必要：`--message-id`、`--target`
- 可選：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
- 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 以在支援處清除自己的反應；請參閱 /tools/reactions）
- 僅 WhatsApp：`--participant`、`--from-me`
- Signal 群組反應：需要 `--target-author` 或 `--target-author-uuid`
- `reactions`
- 頻道：Discord/Google Chat/Slack/Matrix
- 必要：`--message-id`、`--target`
- 可選：`--limit`
- `read`
- 頻道：Discord/Slack/Matrix
- 必要：`--target`
- 可選：`--limit`、`--before`、`--after`
- 僅 Discord：`--around`
- `edit`
- 頻道：Discord/Slack/Matrix
- 必要：`--message-id`、`--message`、`--target`
- `delete`
- 頻道：Discord/Slack/Telegram/Matrix
- 必要：`--message-id`、`--target`
- `pin` / `unpin`
- 頻道：Discord/Slack/Matrix
- 必要：`--message-id`、`--target`
- `pins`（列表）
- 頻道：Discord/Slack/Matrix
- 必要：`--target`
- `permissions`
- 頻道：Discord/Matrix
- 必要：`--target`
- 僅 Matrix：在 Matrix 加密已啟用且驗證動作被允許時可用
- `search`
- 頻道：Discord
- 必要：`--guild-id`、`--query`
- 可選：`--channel-id`、`--channel-ids`（可重複）、`--author-id`、`--author-ids`（可重複）、`--limit`
### 討論串
- `thread create`
- 頻道：Discord
- 必要：`--thread-name`、`--target`（頻道 ID）
- 可選：`--message-id`、`--message`、`--auto-archive-min`
- `thread list`
- 頻道：Discord
- 必要：`--guild-id`
- 可選：`--channel-id`、`--include-archived`、`--before`、`--limit`
- `thread reply`
- 頻道：Discord
- 必要：`--target`（討論串 ID）、`--message`
- 可選：`--media`、`--reply-to`
### 表情符號
- `emoji list`
- Discord：`--guild-id`
- Slack：沒有額外旗標
- `emoji upload`
- 頻道：Discord
- 必要：`--guild-id`、`--emoji-name`、`--media`
- 可選：`--role-ids`（可重複）
### 貼圖
- `sticker send`
- 頻道：Discord
- 必要：`--target`、`--sticker-id`（可重複）
- 可選：`--message`
- `sticker upload`
- 頻道：Discord
- 必要：`--guild-id`、`--sticker-name`、`--sticker-desc`、`--sticker-tags`、`--media`
### 角色 / 頻道 / 成員 / 語音
- `role info`（Discord）：`--guild-id`
- `role add` / `role remove`（Discord）：`--guild-id`、`--user-id`、`--role-id`
- `channel info`（Discord）：`--target`
- `channel list`（Discord）：`--guild-id`
- `member info`（Discord/Slack）：`--user-id`（Discord 另加 `--guild-id`）
- `voice status`（Discord）：`--guild-id`、`--user-id`
### 事件
- `event list`（Discord）：`--guild-id`
- `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time`
- 可選：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
### 審核（Discord）
- `timeout`：`--guild-id`、`--user-id`（可選 `--duration-min` 或 `--until`；兩者皆省略可清除逾時）
- `kick`：`--guild-id`、`--user-id`（+ `--reason`）
- `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
- `timeout` 也支援 `--reason`
### 廣播
- `broadcast`
- 頻道：任何已設定頻道；使用 `--channel all` 以目標所有提供者
- 必要：`--targets <target...>`
- 可選：`--message`、`--media`、`--dry-run`
## 範例
傳送 Discord 回覆：
```
openclaw message send --channel discord \
--target channel:123 --message "hi" --reply-to 456
```
傳送帶有語意按鈕的訊息：
```
openclaw message send --channel discord \
--target channel:123 --message "Choose:" \
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
```
核心會根據頻道能力，將相同的 `presentation` 承載呈現為 Discord 元件、Slack 區塊、Telegram 內嵌按鈕、Mattermost props，或 Teams/Feishu 卡片。請參閱[訊息呈現](/zh-TW/plugins/message-presentation)以了解完整合約與後援規則。
傳送更豐富的呈現承載：
```bash
openclaw message send --channel googlechat --target spaces/AAA... \
--message "Choose:" \
--presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Choose a path"},{"type":"buttons","buttons":[{"label":"Approve","value":"approve"},{"label":"Decline","value":"decline"}]}]}'
```
建立 Discord 投票：
```
openclaw message poll --channel discord \
--target channel:123 \
--poll-question "Snack?" \
--poll-option Pizza --poll-option Sushi \
--poll-multi --poll-duration-hours 48
```
建立 Telegram 投票（2 分鐘後自動關閉）：
```
openclaw message poll --channel telegram \
--target @mychat \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi \
--poll-duration-seconds 120 --silent
```
傳送 Teams 主動訊息：
```
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 --message "hi"
```
建立 Teams 投票：
```
openclaw message poll --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi
```
在 Slack 中反應：
```
openclaw message react --channel slack \
--target C123 --message-id 456 --emoji "✅"
```
在 Signal 群組中反應：
```
openclaw message react --channel signal \
--target signal:group:abc123 --message-id 1737630212345 \
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
```
透過通用呈現傳送 Telegram 內嵌按鈕：
```
openclaw message send --channel telegram --target @mychat --message "Choose:" \
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
```
透過通用呈現傳送 Teams 卡片：
```bash
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--presentation '{"title":"Status update","blocks":[{"type":"text","text":"Build completed"}]}'
```
將 Telegram 圖片作為文件傳送以避免壓縮：
```bash
openclaw message send --channel telegram --target @mychat \
--media ./diagram.png --force-document
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [Agent 傳送](/zh-TW/tools/agent-send)

177
docs/zh-TW/cli/migrate.md Normal file
View File

@ -0,0 +1,177 @@
---
read_when:
- 你想從 Hermes 或其他代理系統遷移到 OpenClaw
- 你正在新增由 Plugin 擁有的遷移提供者
summary: '`openclaw migrate` 的 CLI 參考（從另一個代理系統匯入狀態）'
title: 遷移
x-i18n:
generated_at: "2026-04-30T02:54:47Z"
model: gpt-5.5
provider: openai
source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e
source_path: cli/migrate.md
workflow: 16
---
# `openclaw migrate`
透過 Plugin 所擁有的遷移提供者，從另一個代理系統匯入狀態。內建提供者涵蓋 [Claude](/zh-TW/install/migrating-claude) 和 [Hermes](/zh-TW/install/migrating-hermes)；第三方插件可以註冊其他提供者。
<Tip>
如需面向使用者的逐步說明，請參閱[從 Claude 遷移](/zh-TW/install/migrating-claude)和[從 Hermes 遷移](/zh-TW/install/migrating-hermes)。[遷移中心](/zh-TW/install/migrating)列出所有路徑。
</Tip>
## 命令
```bash
openclaw migrate list
openclaw migrate claude --dry-run
openclaw migrate hermes --dry-run
openclaw migrate hermes
openclaw migrate apply claude --yes
openclaw migrate apply hermes --yes
openclaw migrate apply hermes --include-secrets --yes
openclaw onboard --flow import
openclaw onboard --import-from claude --import-source ~/.claude
openclaw onboard --import-from hermes --import-source ~/.hermes
```
<ParamField path="<provider>" type="string">
已註冊遷移提供者的名稱，例如 `hermes`。執行 `openclaw migrate list` 以查看已安裝的提供者。
</ParamField>
<ParamField path="--dry-run" type="boolean">
建立計畫後結束，不變更狀態。
</ParamField>
<ParamField path="--from <path>" type="string">
覆寫來源狀態目錄。Hermes 預設為 `~/.hermes`。
</ParamField>
<ParamField path="--include-secrets" type="boolean">
匯入支援的憑證。預設為關閉。
</ParamField>
<ParamField path="--overwrite" type="boolean">
當計畫回報衝突時，允許套用取代現有目標。
</ParamField>
<ParamField path="--yes" type="boolean">
略過確認提示。在非互動模式中必填。
</ParamField>
<ParamField path="--no-backup" type="boolean">
略過套用前備份。當本機 OpenClaw 狀態存在時，需要搭配 `--force`。
</ParamField>
<ParamField path="--force" type="boolean">
當套用原本會拒絕略過備份時，必須與 `--no-backup` 一起使用。
</ParamField>
<ParamField path="--json" type="boolean">
以 JSON 列印計畫或套用結果。使用 `--json` 且未使用 `--yes` 時，套用會列印計畫且不變更狀態。
</ParamField>
## 安全模型
`openclaw migrate` 以預覽優先。
<AccordionGroup>
<Accordion title="Preview before apply">
在任何變更發生前，提供者會傳回逐項列出的計畫，其中包含衝突、略過的項目和敏感項目。JSON 計畫、套用輸出和遷移報告會遮蔽巢狀且看似祕密的鍵，例如 API 金鑰、權杖、授權標頭、Cookie 和密碼。
`openclaw migrate apply <provider>` 會先預覽計畫，並在變更狀態前提示，除非已設定 `--yes`。在非互動模式中，套用需要 `--yes`。
</Accordion>
<Accordion title="Backups">
套用會在套用遷移前建立並驗證 OpenClaw 備份。如果尚未存在本機 OpenClaw 狀態，則會略過備份步驟，遷移可以繼續。若要在狀態存在時略過備份，請同時傳入 `--no-backup` 和 `--force`。
</Accordion>
<Accordion title="Conflicts">
當計畫有衝突時，套用會拒絕繼續。請檢閱計畫，若有意取代現有目標，再使用 `--overwrite` 重新執行。提供者仍可在遷移報告目錄中，為被覆寫的檔案寫入項目層級備份。
</Accordion>
<Accordion title="Secrets">
預設永遠不會匯入祕密。使用 `--include-secrets` 匯入支援的憑證。
</Accordion>
</AccordionGroup>
## Claude 提供者
內建 Claude 提供者預設會偵測 `~/.claude` 的 Claude Code 狀態。使用 `--from <path>` 匯入特定 Claude Code 主目錄或專案根目錄。
<Tip>
如需面向使用者的逐步說明，請參閱[從 Claude 遷移](/zh-TW/install/migrating-claude)。
</Tip>
### Claude 會匯入什麼
- 將專案 `CLAUDE.md` 和 `.claude/CLAUDE.md` 匯入 OpenClaw 代理工作區。
- 將使用者的 `~/.claude/CLAUDE.md` 附加到工作區 `USER.md`。
- 從專案 `.mcp.json`、Claude Code `~/.claude.json` 和 Claude Desktop `claude_desktop_config.json` 匯入 MCP 伺服器定義。
- 包含 `SKILL.md` 的 Claude skill 目錄。
- 將 Claude 命令 Markdown 檔案轉換為僅能手動叫用的 OpenClaw skills。
### 封存和手動檢閱狀態
Claude 掛鉤、權限、環境預設值、本機記憶、路徑範圍規則、子代理、快取、計畫和專案歷史會保留在遷移報告中，或回報為手動檢閱項目。OpenClaw 不會自動執行掛鉤、複製廣泛允許清單，或匯入 OAuth/Desktop 憑證狀態。
## Hermes 提供者
內建 Hermes 提供者預設會偵測 `~/.hermes` 的狀態。當 Hermes 位於其他位置時，請使用 `--from <path>`。
### Hermes 會匯入什麼
- 從 `config.yaml` 匯入預設模型設定。
- 從 `providers` 和 `custom_providers` 匯入已設定的模型提供者和自訂 OpenAI 相容端點。
- 從 `mcp_servers` 或 `mcp.servers` 匯入 MCP 伺服器定義。
- 將 `SOUL.md` 和 `AGENTS.md` 匯入 OpenClaw 代理工作區。
- 將 `memories/MEMORY.md` 和 `memories/USER.md` 附加到工作區記憶檔案。
- OpenClaw 檔案記憶的記憶設定預設值，以及外部記憶提供者（例如 Honcho）的封存或手動檢閱項目。
- `skills/<name>/` 底下包含 `SKILL.md` 檔案的 Skills。
- 從 `skills.config` 匯入每個 skill 的設定值。
- 從 `.env` 匯入支援的 API 金鑰，僅在使用 `--include-secrets` 時。
### 支援的 `.env` 鍵
`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENROUTER_API_KEY`、`GOOGLE_API_KEY`、`GEMINI_API_KEY`、`GROQ_API_KEY`、`XAI_API_KEY`、`MISTRAL_API_KEY`、`DEEPSEEK_API_KEY`。
### 僅封存狀態
OpenClaw 無法安全解讀的 Hermes 狀態會複製到遷移報告以供手動檢閱，但不會載入即時 OpenClaw 設定或憑證。這會保留不透明或不安全的狀態，而不假裝 OpenClaw 可以自動執行或信任它：
- `plugins/`
- `sessions/`
- `logs/`
- `cron/`
- `mcp-tokens/`
- `auth.json`
- `state.db`
### 套用之後
```bash
openclaw doctor
```
## Plugin 合約
遷移來源是插件。插件會在 `openclaw.plugin.json` 中宣告其提供者 ID：
```json
{
"contracts": {
"migrationProviders": ["hermes"]
}
}
```
執行階段中，Plugin 會呼叫 `api.registerMigrationProvider(...)`。提供者會實作 `detect`、`plan` 和 `apply`。核心負責 CLI 編排、備份政策、提示、JSON 輸出和衝突預檢。核心會將已檢閱的計畫傳入 `apply(ctx, plan)`，而提供者只有在為了相容性且該引數不存在時，才可以重建計畫。
提供者插件可以使用 `openclaw/plugin-sdk/migration` 來建構項目和彙總計數，並使用 `openclaw/plugin-sdk/migration-runtime` 來進行可感知衝突的檔案複製、僅封存的報告複製、快取設定執行階段包裝器，以及遷移報告。
## Onboarding 整合
當提供者偵測到已知來源時，Onboarding 可以提供遷移。`openclaw onboard --flow import` 和 `openclaw setup --wizard --import-from hermes` 都使用相同的插件遷移提供者，並且仍會在套用前顯示預覽。
<Note>
Onboarding 匯入需要全新的 OpenClaw 設定。如果你已經有本機狀態，請先重設設定、憑證、工作階段和工作區。對於現有設定，備份加覆寫或合併匯入功能受功能旗標控管。
</Note>
## 相關
- [從 Hermes 遷移](/zh-TW/install/migrating-hermes)：面向使用者的逐步說明。
- [從 Claude 遷移](/zh-TW/install/migrating-claude)：面向使用者的逐步說明。
- [遷移](/zh-TW/install/migrating)：將 OpenClaw 移至新機器。
- [Doctor](/zh-TW/gateway/doctor)：套用遷移後的健康檢查。
- [插件](/zh-TW/tools/plugin)：插件安裝和註冊。

203
docs/zh-TW/cli/models.md Normal file
View File

@ -0,0 +1,203 @@
---
read_when:
- 您想要變更預設模型或檢視提供者驗證狀態
- 您想掃描可用的模型/供應商並除錯身分驗證設定檔
summary: '`openclaw models` 的 CLI 參考（status/list/set/scan、別名、備援機制、身分驗證）'
title: 模型
x-i18n:
generated_at: "2026-04-30T02:54:49Z"
model: gpt-5.5
provider: openai
source_hash: 95e2361989b583f7f52947dad1faaaba44dc6a5f58719cc2e83c13fce7c33adc
source_path: cli/models.md
workflow: 16
---
# `openclaw models`
模型探索、掃描與設定（預設模型、備援、驗證設定檔）。
相關：
- 供應商 + 模型：[模型](/zh-TW/providers/models)
- 模型選擇概念 + `/models` 斜線指令：[模型概念](/zh-TW/concepts/models)
- 供應商驗證設定：[開始使用](/zh-TW/start/getting-started)
## 常用指令
```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` 會顯示解析後的預設值/備援，以及驗證概覽。
當供應商使用量快照可用時，OAuth/API 金鑰狀態區段會包含
供應商使用時段與配額快照。
目前的使用時段供應商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI
Codex、MiniMax、Xiaomi 和 z.ai。使用量驗證在可用時會來自供應商專屬掛鉤；
否則 OpenClaw 會退回使用來自驗證設定檔、環境或設定中相符的 OAuth/API 金鑰
憑證。
在 `--json` 輸出中，`auth.providers` 是感知環境/設定/儲存區的供應商
概覽，而 `auth.oauth` 只代表驗證儲存區設定檔健康狀態。
加入 `--probe` 可對每個已設定的供應商設定檔執行即時驗證探測。
探測是真實請求（可能會消耗權杖並觸發速率限制）。
使用 `--agent <id>` 檢查已設定代理程式的模型/驗證狀態。省略時，
此指令會使用已設定的預設代理程式，除非已設定
`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`。
探測列可能來自驗證設定檔、環境憑證或 `models.json`。
備註：
- `models set <model-or-alias>` 接受 `provider/model` 或別名。
- `models list` 是唯讀的：它會讀取設定、驗證設定檔、現有目錄
狀態，以及供應商擁有的目錄列，但不會重寫
`models.json`。
- `Auth` 欄位是供應商層級且唯讀。它會根據本機
驗證設定檔中繼資料、環境標記、已設定的供應商金鑰、本機供應商
標記、AWS Bedrock 環境/設定檔標記，以及 Plugin 合成驗證中繼資料計算；
它不會載入供應商執行階段、讀取鑰匙圈祕密、呼叫供應商
API，或證明精確的逐模型執行就緒狀態。
- `models list --all --provider <id>` 可包含來自 Plugin 資訊清單或隨附供應商目錄中繼資料的供應商擁有靜態目錄
列，即使你尚未向該供應商完成驗證。這些列在設定相符驗證之前仍會顯示為
不可用。
- 廣泛的 `models list --all` 會將資訊清單目錄列合併到登錄列之上，
而不載入供應商執行階段補充掛鉤。供應商篩選的資訊清單
快速路徑只使用標記為 `static` 的供應商；標記為 `refreshable` 的供應商
保持以登錄/快取為基礎，並附加資訊清單列作為補充，而
標記為 `runtime` 的供應商則保持使用登錄/執行階段探索。
- `models list` 會將原生模型中繼資料與執行階段上限分開。在表格
輸出中，當有效執行階段上限不同於原生內容視窗時，`Ctx` 會顯示
`contextTokens/contextWindow`；當供應商公開該上限時，JSON 列會包含 `contextTokens`。
- `models list --provider <id>` 會依供應商 ID 篩選，例如 `moonshot` 或
`openai-codex`。它不接受互動式供應商
選擇器中的顯示標籤，例如 `Moonshot AI`。
- 模型參照會透過分割**第一個** `/` 來解析。如果模型 ID 包含 `/`（OpenRouter 風格），請包含供應商前綴（範例：`openrouter/moonshotai/kimi-k2`）。
- 如果你省略供應商，OpenClaw 會先將輸入解析為別名，接著
解析為該精確模型 ID 的唯一已設定供應商相符項，最後才
退回至已設定的預設供應商並顯示淘汰警告。
如果該供應商不再公開已設定的預設模型，OpenClaw
會退回到第一個已設定的供應商/模型，而不是顯示
過時的已移除供應商預設值。
- `models status` 可能會在驗證輸出中，針對非祕密佔位符顯示 `marker(<value>)`（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是將其遮罩為祕密。
### 模型掃描
`models scan` 會讀取 OpenRouter 的公開 `:free` 目錄，並為
備援用途排序候選項。目錄本身是公開的，因此僅中繼資料掃描不需要
OpenRouter 金鑰。
預設情況下，OpenClaw 會嘗試透過即時模型呼叫探測工具與圖片支援。
如果未設定 OpenRouter 金鑰，此指令會退回至僅中繼資料
輸出，並說明 `:free` 模型仍需要 `OPENROUTER_API_KEY` 才能進行
探測與推論。
選項：
- `--no-probe`（僅中繼資料；不查詢設定/祕密）
- `--min-params <b>`
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>`（目錄請求與每次探測逾時）
- `--concurrency <n>`
- `--yes`
- `--no-input`
- `--set-default`
- `--set-image`
- `--json`
`--set-default` 和 `--set-image` 需要即時探測；僅中繼資料掃描
結果只供參考，不會套用至設定。
### 模型狀態
選項：
- `--json`
- `--plain`
- `--check`（結束碼 1=已過期/缺少，2=即將過期）
- `--probe`（即時探測已設定的驗證設定檔）
- `--probe-provider <name>`（探測單一供應商）
- `--probe-profile <id>`（重複或以逗號分隔的設定檔 ID）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>`（已設定的代理程式 ID；覆寫 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）
`--json` 會保留 stdout 供 JSON 承載使用。驗證設定檔、供應商，
以及啟動診斷會路由到 stderr，讓指令碼可以將 stdout 直接管線傳送
到 `jq` 等工具。
探測狀態分類：
- `ok`
- `auth`
- `rate_limit`
- `billing`
- `timeout`
- `format`
- `unknown`
- `no_model`
可預期的探測詳細資料/原因碼案例：
- `excluded_by_auth_order`：已存在儲存的設定檔，但明確的
`auth.order.<provider>` 省略了它，因此探測會回報此排除，而不是
嘗試它。
- `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`：
設定檔存在，但不符合資格/無法解析。
- `no_model`：供應商驗證存在，但 OpenClaw 無法為該供應商解析可探測的
模型候選項。
## 別名 + 備援
```bash
openclaw models aliases list
openclaw models fallbacks list
```
## 驗證設定檔
```bash
openclaw models auth add
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` 是互動式驗證輔助工具。它可以啟動供應商驗證
流程（OAuth/API 金鑰），或根據你選擇的
供應商，引導你手動貼上權杖。
`models auth login` 會執行供應商 Plugin 的驗證流程（OAuth/API 金鑰）。使用
`openclaw plugins list` 查看已安裝哪些供應商。
使用 `openclaw models auth --agent <id> <subcommand>` 可將驗證結果寫入
特定已設定的代理程式儲存區。父層 `--agent` 旗標會由
`add`、`login`、`setup-token`、`paste-token` 和 `login-github-copilot` 遵循。
範例：
```bash
openclaw models auth login --provider openai-codex --set-default
```
備註：
- `setup-token` 和 `paste-token` 仍是供公開權杖驗證方法的供應商使用的通用權杖指令。
- `setup-token` 需要互動式 TTY，並會執行供應商的權杖驗證
方法（當該供應商公開 `setup-token` 方法時，預設使用該方法）。
- `paste-token` 接受在其他地方產生或來自自動化的權杖字串。
- `paste-token` 需要 `--provider`，會提示輸入權杖值，並將
它寫入預設設定檔 ID `<provider>:manual`，除非你傳入
`--profile-id`。
- `paste-token --expires-in <duration>` 會根據相對持續時間（例如 `365d` 或 `12h`）儲存絕對權杖到期時間。
- Anthropic 備註：Anthropic 人員告訴我們，OpenClaw 風格的 Claude CLI 使用方式已再次被允許，因此除非 Anthropic 發布新政策，OpenClaw 會將 Claude CLI 重用與 `claude -p` 使用視為此整合已核准的方式。
- Anthropic `setup-token` / `paste-token` 仍可作為受支援的 OpenClaw 權杖路徑使用，但 OpenClaw 現在會優先使用 Claude CLI 重用與可用時的 `claude -p`。
## 相關
- [CLI 參考](/zh-TW/cli)
- [模型選擇](/zh-TW/concepts/model-providers)
- [模型故障轉移](/zh-TW/concepts/model-failover)

162
docs/zh-TW/cli/node.md Normal file
View File

@ -0,0 +1,162 @@
---
read_when:
- 執行無頭式 Node 主機
- 配對用於 system.run 的非 macOS 節點
summary: '`openclaw node` 的 CLI 參考（無頭節點主機）'
title: Node
x-i18n:
generated_at: "2026-04-30T02:54:54Z"
model: gpt-5.5
provider: openai
source_hash: 40f623b163a3c3bcd2d3ff218c5e62a4acba45f7e3f16694d8da62a004b77706
source_path: cli/node.md
workflow: 16
---
# `openclaw node`
執行一個連線到 Gateway WebSocket，並在這台機器上公開
`system.run` / `system.which` 的 **無頭 Node 主機**。
## 為什麼使用 Node 主機？
當你想讓代理在網路中的**其他機器上執行命令**，但不想在那裡安裝完整的 macOS companion app 時，請使用 Node 主機。
常見使用情境：
- 在遠端 Linux/Windows 機器上執行命令（建置伺服器、實驗室機器、NAS）。
- 讓 exec 在 gateway 上保持**沙箱化**，但將已核准的執行委派給其他主機。
- 為自動化或 CI 節點提供輕量、無頭的執行目標。
執行仍受 **exec 核准**與 Node 主機上的逐代理允許清單保護，因此你可以讓命令存取維持在明確且限定的範圍內。
## 瀏覽器代理（零設定）
如果 Node 上未停用 `browser.enabled`，Node 主機會自動宣告瀏覽器代理。這可讓代理在該 Node 上使用瀏覽器自動化，而不需要額外設定。
預設情況下，代理會公開該 Node 的一般瀏覽器設定檔介面。如果你設定了 `nodeHost.browserProxy.allowProfiles`，代理會變成限制模式：未列入允許清單的設定檔目標會被拒絕，且持久設定檔的建立/刪除路由會透過代理被封鎖。
如有需要，可在 Node 上停用：
```json5
{
nodeHost: {
browserProxy: {
enabled: false,
},
},
}
```
## 執行（前景）
```bash
openclaw node run --host <gateway-host> --port 18789
```
選項：
- `--host <host>`：Gateway WebSocket 主機（預設：`127.0.0.1`）
- `--port <port>`：Gateway WebSocket 連接埠（預設：`18789`）
- `--tls`：對 gateway 連線使用 TLS
- `--tls-fingerprint <sha256>`：預期的 TLS 憑證指紋（sha256）
- `--node-id <id>`：覆寫 node id（清除 pairing token）
- `--display-name <name>`：覆寫 Node 顯示名稱
## Node 主機的 Gateway 驗證
`openclaw node run` 和 `openclaw node install` 會從 config/env 解析 gateway 驗證（Node 命令沒有 `--token`/`--password` 旗標）：
- 會先檢查 `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`。
- 接著使用本機設定後援：`gateway.auth.token` / `gateway.auth.password`。
- 在本機模式中，Node 主機刻意不繼承 `gateway.remote.token` / `gateway.remote.password`。
- 如果 `gateway.auth.token` / `gateway.auth.password` 透過 SecretRef 明確設定但無法解析，Node 驗證解析會關閉失敗（不以遠端後援遮蔽）。
- 在 `gateway.mode=remote` 中，遠端用戶端欄位（`gateway.remote.token` / `gateway.remote.password`）也會依遠端優先順序規則納入資格。
- Node 主機驗證解析只採用 `OPENCLAW_GATEWAY_*` 環境變數。
對於連線到受信任私人網路中非 loopback `ws://` Gateway 的 Node，請設定 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`。若未設定，Node 啟動會關閉失敗，並要求你使用 `wss://`、SSH 通道或 Tailscale。
這是程序環境的選擇加入項，不是 `openclaw.json` 設定鍵。
當 `openclaw node install` 的安裝命令環境中存在此項時，會將它持久化到受監督的 Node 服務中。
## 服務（背景）
將無頭 Node 主機安裝為使用者服務。
```bash
openclaw node install --host <gateway-host> --port 18789
```
選項：
- `--host <host>`：Gateway WebSocket 主機（預設：`127.0.0.1`）
- `--port <port>`：Gateway WebSocket 連接埠（預設：`18789`）
- `--tls`：對 gateway 連線使用 TLS
- `--tls-fingerprint <sha256>`：預期的 TLS 憑證指紋（sha256）
- `--node-id <id>`：覆寫 node id（清除 pairing token）
- `--display-name <name>`：覆寫 Node 顯示名稱
- `--runtime <runtime>`：服務執行階段（`node` 或 `bun`）
- `--force`：如果已安裝，重新安裝/覆寫
管理服務：
```bash
openclaw node status
openclaw node start
openclaw node stop
openclaw node restart
openclaw node uninstall
```
使用 `openclaw node run` 以前景方式執行 Node 主機（無服務）。
服務命令接受 `--json`，以產生機器可讀輸出。
Node 主機會在程序內重試 Gateway 重新啟動與網路關閉。如果 Gateway 回報終端 token/password/bootstrap 驗證暫停，Node 主機會記錄關閉詳細資訊並以非零狀態結束，讓 launchd/systemd 可以用新的設定與憑證重新啟動它。需要 pairing 的暫停會保留在前景流程中，讓待處理請求可以被核准。
## Pairing
第一次連線會在 Gateway 上建立待處理的裝置 pairing 請求（`role: node`）。
透過以下方式核准：
```bash
openclaw devices list
openclaw devices approve <requestId>
```
在嚴格控管的 Node 網路中，Gateway 操作者可以明確選擇加入，從受信任 CIDR 自動核准首次 Node pairing：
```json5
{
gateway: {
nodes: {
pairing: {
autoApproveCidrs: ["192.168.1.0/24"],
},
},
},
}
```
此功能預設停用。它只套用於沒有要求 scopes 的全新 `role: node` pairing。操作者/瀏覽器用戶端、Control UI、WebChat，以及 role、scope、metadata 或 public-key 升級仍需要手動核准。
如果 Node 使用變更後的驗證詳細資訊（role/scopes/public key）重試 pairing，先前的待處理請求會被取代，並建立新的 `requestId`。
核准前請再次執行 `openclaw devices list`。
Node 主機會將其 node id、token、顯示名稱與 gateway 連線資訊儲存在
`~/.openclaw/node.json`。
## Exec 核准
`system.run` 受本機 exec 核准控管：
- `~/.openclaw/exec-approvals.json`
- [Exec 核准](/zh-TW/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>`（從 Gateway 編輯）
對於已核准的非同步 Node exec，OpenClaw 會在提示前準備標準的 `systemRunPlan`。
後續已核准的 `system.run` 轉送會重用該已儲存的計畫，因此在核准請求建立後對 command/cwd/session 欄位的編輯會被拒絕，而不是改變 Node 執行的內容。
## 相關
- [CLI 參考](/zh-TW/cli)
- [Nodes](/zh-TW/nodes)

81
docs/zh-TW/cli/nodes.md Normal file
View File

@ -0,0 +1,81 @@
---
read_when:
- 你正在管理配對的節點（攝影機、螢幕、畫布）
- 你需要核准請求或叫用 Node 命令
summary: '`openclaw nodes` 的 CLI 參考（狀態、配對、叫用、相機/畫布/螢幕）'
title: Node
x-i18n:
generated_at: "2026-04-30T02:55:31Z"
model: gpt-5.5
provider: openai
source_hash: 3229db91d7e64b0d37bee29bd51895d90796f5fd33b67e3d900fd8bda2b6e7e9
source_path: cli/nodes.md
workflow: 16
---
# `openclaw nodes`
管理已配對節點（裝置）並呼叫節點功能。
相關：
- 節點概觀：[節點](/zh-TW/nodes)
- 相機：[相機節點](/zh-TW/nodes/camera)
- 影像：[影像節點](/zh-TW/nodes/images)
常用選項：
- `--url`, `--token`, `--timeout`, `--json`
## 常用命令
```bash
openclaw nodes list
openclaw nodes list --connected
openclaw nodes list --last-connected 24h
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name <displayName>
openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
```
`nodes list` 會列印待處理/已配對表格。已配對列包含最近一次連線距今時間（上次連線）。
使用 `--connected` 只顯示目前已連線的節點。使用 `--last-connected <duration>` 可
篩選在一段時間內曾連線的節點（例如 `24h`、`7d`）。
使用 `nodes remove --node <id|name|ip>` 可刪除過時且由 Gateway 擁有的節點配對記錄。
核准注意事項：
- `openclaw nodes pending` 只需要配對權限範圍。
- `gateway.nodes.pairing.autoApproveCidrs` 只能針對明確信任、首次 `role: node` 裝置配對
跳過待處理步驟。它預設為關閉，且不會核准升級。
- `openclaw nodes approve <requestId>` 會從待處理請求繼承額外的權限範圍要求：
- 無命令請求：僅配對
- 非 exec 節點命令：配對 + 寫入
- `system.run` / `system.run.prepare` / `system.which`：配對 + 管理員
## 呼叫
```bash
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
```
呼叫旗標：
- `--params <json>`：JSON 物件字串（預設 `{}`）。
- `--invoke-timeout <ms>`：節點呼叫逾時（預設 `15000`）。
- `--idempotency-key <key>`：選用的等冪鍵。
- `system.run` 和 `system.run.prepare` 在此處會被封鎖；請使用帶有 `host=node` 的 `exec` 工具進行 shell 執行。
若要在節點上執行 shell，請使用帶有 `host=node` 的 `exec` 工具，而不是 `openclaw nodes run`。
`nodes` CLI 現在專注於功能：透過 `nodes invoke` 進行直接 RPC，以及配對、相機、
螢幕、位置、canvas 和通知。
## 相關
- [CLI 參考](/zh-TW/cli)
- [節點](/zh-TW/nodes)

225
docs/zh-TW/cli/onboard.md Normal file
View File

@ -0,0 +1,225 @@
---
read_when:
- 您想要 Gateway、工作區、身分驗證、通道和 Skills 的引導式設定
summary: '`openclaw onboard` 的 CLI 參考資料（互動式新手引導）'
title: 入門
x-i18n:
generated_at: "2026-04-30T02:55:18Z"
model: gpt-5.5
provider: openai
source_hash: 583310458b2e2bc8ddc1513112c960520d972716be0c33e4177d0db30e896504
source_path: cli/onboard.md
workflow: 16
---
# `openclaw onboard`
用於本機或遠端 Gateway 設定的互動式導覽。
## 相關指南
<CardGroup cols={2}>
<Card title="CLI 導覽中心" href="/zh-TW/start/wizard" icon="rocket">
互動式 CLI 流程逐步說明。
</Card>
<Card title="導覽概覽" href="/zh-TW/start/onboarding-overview" icon="map">
OpenClaw 導覽如何銜接運作。
</Card>
<Card title="CLI 設定參考" href="/zh-TW/start/wizard-cli-reference" icon="book">
輸出、內部機制，以及每個步驟的行為。
</Card>
<Card title="CLI 自動化" href="/zh-TW/start/wizard-cli-automation" icon="terminal">
非互動式旗標與腳本化設定。
</Card>
<Card title="macOS app 導覽" href="/zh-TW/start/onboarding" icon="apple">
macOS 選單列 app 的導覽流程。
</Card>
</CardGroup>
## 範例
```bash
openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
`--flow import` 會使用 Hermes 等由 Plugin 擁有的遷移提供者。它只會針對全新的 OpenClaw 設定執行；如果已存在設定、憑證、工作階段，或工作區記憶/身分檔案，請先重設或選擇全新設定再匯入。
`--modern` 會啟動 Crestodian 對話式導覽預覽。若未使用
`--modern`，`openclaw onboard` 會保留傳統導覽流程。
對於純文字私有網路 `ws://` 目標（僅限受信任網路），請在導覽程序環境中設定
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`。
此用戶端傳輸的緊急例外設定沒有對應的 `openclaw.json` 項目。
非互動式自訂提供者：
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai \
--custom-image-input
```
在非互動式模式中，`--custom-api-key` 是選用的。若省略，導覽會檢查 `CUSTOM_API_KEY`。
OpenClaw 會自動將常見的視覺模型 ID 標記為支援圖片。對於未知的自訂視覺 ID，請傳入 `--custom-image-input`；或傳入 `--custom-text-input` 以強制使用純文字中繼資料。
LM Studio 在非互動式模式中也支援提供者專屬金鑰旗標：
```bash
openclaw onboard --non-interactive \
--auth-choice lmstudio \
--custom-base-url "http://localhost:1234/v1" \
--custom-model-id "qwen/qwen3.5-9b" \
--lmstudio-api-key "$LM_API_TOKEN" \
--accept-risk
```
非互動式 Ollama：
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
`--custom-base-url` 預設為 `http://127.0.0.1:11434`。`--custom-model-id` 是選用的；若省略，導覽會使用 Ollama 建議的預設值。像 `kimi-k2.5:cloud` 這類雲端模型 ID 也可在此使用。
將提供者金鑰儲存為參照，而非純文字：
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
使用 `--secret-input-mode ref` 時，導覽會寫入由環境支援的參照，而非純文字金鑰值。
對於由 auth-profile 支援的提供者，這會寫入 `keyRef` 項目；對於自訂提供者，這會將 `models.providers.<id>.apiKey` 寫成環境參照（例如 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`）。
非互動式 `ref` 模式合約：
- 在導覽程序環境中設定提供者環境變數（例如 `OPENAI_API_KEY`）。
- 除非也已設定該環境變數，否則不要傳入行內金鑰旗標（例如 `--openai-api-key`）。
- 如果傳入行內金鑰旗標但缺少必要的環境變數，導覽會快速失敗並提供指引。
非互動式模式中的 Gateway 權杖選項：
- `--gateway-auth token --gateway-token <token>` 會儲存純文字權杖。
- `--gateway-auth token --gateway-token-ref-env <name>` 會將 `gateway.auth.token` 儲存為環境 SecretRef。
- `--gateway-token` 和 `--gateway-token-ref-env` 互斥。
- `--gateway-token-ref-env` 要求導覽程序環境中存在非空的環境變數。
- 使用 `--install-daemon` 時，若權杖驗證需要權杖，由 SecretRef 管理的 Gateway 權杖會被驗證，但不會以解析後的純文字形式保存到 supervisor 服務環境中繼資料。
- 使用 `--install-daemon` 時，若權杖模式需要權杖，且已設定的權杖 SecretRef 無法解析，導覽會關閉式失敗並提供修復指引。
- 使用 `--install-daemon` 時，若同時設定了 `gateway.auth.token` 和 `gateway.auth.password`，且未設定 `gateway.auth.mode`，導覽會阻止安裝，直到明確設定模式。
- 本機導覽會將 `gateway.mode="local"` 寫入設定。如果後續設定檔缺少 `gateway.mode`，請將其視為設定損壞或未完成的手動編輯，而不是有效的本機模式捷徑。
- `--allow-unconfigured` 是獨立的 Gateway 執行階段逃生口。它不表示導覽可以省略 `gateway.mode`。
範例：
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
非互動式本機 Gateway 健康狀態：
- 除非傳入 `--skip-health`，否則導覽會等待可連線的本機 Gateway，然後才成功結束。
- `--install-daemon` 會先啟動受管理的 Gateway 安裝路徑。若未使用它，則必須已有本機 Gateway 在執行，例如 `openclaw gateway run`。
- 如果在自動化中只想寫入設定/工作區/bootstrap，請使用 `--skip-health`。
- 如果自行管理工作區檔案，請傳入 `--skip-bootstrap` 以設定 `agents.defaults.skipBootstrap: true`，並略過建立 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 和 `BOOTSTRAP.md`。
- 在原生 Windows 上，`--install-daemon` 會先嘗試 Scheduled Tasks；如果建立工作遭拒，則退回為每位使用者的 Startup 資料夾登入項目。
使用參照模式時的互動式導覽行為：
- 出現提示時選擇 **使用秘密參照**。
- 然後選擇以下其中之一：
- 環境變數
- 已設定的秘密提供者（`file` 或 `exec`）
- 導覽會在儲存參照前執行快速預檢驗證。
- 如果驗證失敗，導覽會顯示錯誤並讓你重試。
### 非互動式 Z.AI 端點選擇
<Note>
`--auth-choice zai-api-key` 會自動偵測最適合你金鑰的 Z.AI 端點（偏好使用搭配 `zai/glm-5.1` 的通用 API）。如果你明確想使用 GLM Coding Plan 端點，請選擇 `zai-coding-global` 或 `zai-coding-cn`。
</Note>
```bash
# Promptless endpoint selection
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# Other Z.AI endpoint choices:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
```
非互動式 Mistral 範例：
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
## 流程備註
<AccordionGroup>
<Accordion title="流程類型">
- `quickstart`：最少提示，自動產生 Gateway 權杖。
- `manual`：完整提示連接埠、繫結與驗證（`advanced` 的別名）。
- `import`：執行偵測到的遷移提供者，預覽計畫，然後在確認後套用。
</Accordion>
<Accordion title="提供者預先篩選">
當驗證選項暗示偏好的提供者時，導覽會將預設模型與允許清單選擇器預先篩選到該提供者。對於 Volcengine 和 BytePlus，這也會符合 coding-plan 變體（`volcengine-plan/*`、`byteplus-plan/*`）。
如果偏好提供者篩選尚未產生任何已載入模型，導覽會退回未篩選的目錄，而不是讓選擇器留空。
</Accordion>
<Accordion title="網頁搜尋後續提示">
某些網頁搜尋提供者會觸發提供者專屬的後續提示：
- **Grok** 可以使用相同的 `XAI_API_KEY` 和 `x_search` 模型選項，提供選用的 `x_search` 設定。
- **Kimi** 可以詢問 Moonshot API 區域（`api.moonshot.ai` 或 `api.moonshot.cn`）以及預設 Kimi 網頁搜尋模型。
</Accordion>
<Accordion title="其他行為">
- 本機導覽 DM 範圍行為：[CLI 設定參考](/zh-TW/start/wizard-cli-reference#outputs-and-internals)。
- 最快開始第一次聊天：`openclaw dashboard`（Control UI，無需設定頻道）。
- 自訂提供者：連接任何與 OpenAI 或 Anthropic 相容的端點，包括未列出的託管提供者。使用 Unknown 可自動偵測。
- 如果偵測到 Hermes 狀態，導覽會提供遷移流程。使用 [遷移](/zh-TW/cli/migrate) 取得 dry-run 計畫、覆寫模式、報告，以及精確對應。
</Accordion>
</AccordionGroup>
## 常見後續命令
```bash
openclaw configure
openclaw agents add <name>
```
<Note>
`--json` 不代表非互動式模式。腳本請使用 `--non-interactive`。
</Note>

84
docs/zh-TW/cli/pairing.md Normal file
View File

@ -0,0 +1,84 @@
---
read_when:
- 你正在使用配對模式私訊，且需要核准傳送者
summary: CLI 參考：`openclaw pairing`（核准/列出配對請求）
title: 配對
x-i18n:
generated_at: "2026-04-30T02:55:25Z"
model: gpt-5.5
provider: openai
source_hash: bffc70a8c08e298f42c8fbc2238fce06993572e72f333e87ad18dea3cf33fab5
source_path: cli/pairing.md
workflow: 16
---
# `openclaw pairing`
核准或檢視 DM 配對請求（適用於支援配對的通道）。
相關：
- 配對流程：[配對](/zh-TW/channels/pairing)
## 命令
```bash
openclaw pairing list telegram
openclaw pairing list --channel telegram --account work
openclaw pairing list telegram --json
openclaw pairing approve <code>
openclaw pairing approve telegram <code>
openclaw pairing approve --channel telegram --account work <code> --notify
```
## `pairing list`
列出某個通道的待處理配對請求。
選項：
- `[channel]`：位置式通道 ID
- `--channel <channel>`：明確的通道 ID
- `--account <accountId>`：多帳號通道的帳號 ID
- `--json`：機器可讀輸出
注意事項：
- 如果已設定多個支援配對的通道，你必須以位置參數或 `--channel` 提供通道。
- 只要通道 ID 有效，也允許使用擴充通道。
## `pairing approve`
核准待處理的配對碼，並允許該傳送者。
用法：
- `openclaw pairing approve <channel> <code>`
- `openclaw pairing approve --channel <channel> <code>`
- 已設定的支援配對通道剛好只有一個時，使用 `openclaw pairing approve <code>`
選項：
- `--channel <channel>`：明確的通道 ID
- `--account <accountId>`：多帳號通道的帳號 ID
- `--notify`：在同一通道傳送確認訊息給請求者
擁有者啟動設定：
- 如果你核准配對碼時 `commands.ownerAllowFrom` 是空的，OpenClaw 也會將核准的傳送者記錄為命令擁有者，使用通道作用域項目，例如 `telegram:123456789`。
- 這只會啟動設定第一位擁有者。後續配對核准不會取代或擴充 `commands.ownerAllowFrom`。
- 命令擁有者是允許執行僅限擁有者命令，以及核准危險動作（例如 `/diagnostics`、`/export-trajectory`、`/config` 和 exec 核准）的人類操作員帳號。
## 注意事項
- 通道輸入：以位置參數傳入（`pairing list telegram`），或使用 `--channel <channel>`。
- `pairing list` 支援針對多帳號通道使用 `--account <accountId>`。
- `pairing approve` 支援 `--account <accountId>` 和 `--notify`。
- 如果已設定的支援配對通道只有一個，則允許使用 `pairing approve <code>`。
- 如果你在此啟動設定存在之前已核准某位傳送者，請執行 `openclaw doctor`；當未設定命令擁有者時，它會發出警告，並顯示用來修正的 `openclaw config set commands.ownerAllowFrom ...` 命令。
## 相關
- [CLI 參考](/zh-TW/cli)
- [通道配對](/zh-TW/channels/pairing)

378
docs/zh-TW/cli/plugins.md Normal file
View File

@ -0,0 +1,378 @@
---
read_when:
- 你想安裝或管理 Gateway Plugin 或相容套件包
- 你想要偵錯 Plugin 載入失敗
sidebarTitle: Plugins
summary: '`openclaw plugins` 的 CLI 參考（list、install、marketplace、uninstall、enable/disable、deps、doctor）'
title: Plugins
x-i18n:
generated_at: "2026-04-30T02:55:49Z"
model: gpt-5.5
provider: openai
source_hash: c1ba79bccbbb74e3403188afc2dffc06e4215d433e2b23ed998b1fb09419601b
source_path: cli/plugins.md
workflow: 16
---
管理 Gateway Plugin、hook pack 與相容的 bundle。
<CardGroup cols={2}>
<Card title="Plugin 系統" href="/zh-TW/tools/plugin">
安裝、啟用和疑難排解 Plugin 的使用者指南。
</Card>
<Card title="Plugin bundle" href="/zh-TW/plugins/bundles">
Bundle 相容性模型。
</Card>
<Card title="Plugin manifest" href="/zh-TW/plugins/manifest">
Manifest 欄位與設定 schema。
</Card>
<Card title="安全性" href="/zh-TW/gateway/security">
Plugin 安裝的安全強化。
</Card>
</CardGroup>
## 命令
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins deps
openclaw plugins deps --repair
openclaw plugins deps --prune
openclaw plugins deps --json
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
若要調查緩慢的安裝、檢查、解除安裝或 registry 重新整理，請使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 執行命令。Trace 會將階段計時寫入 stderr，並保持 JSON 輸出可解析。請參閱[偵錯](/zh-TW/help/debugging#plugin-lifecycle-trace)。
<Note>
Bundled Plugin 會隨 OpenClaw 出貨。有些預設啟用（例如 bundled model provider、bundled speech provider，以及 bundled browser Plugin）；其他則需要 `plugins enable`。
原生 OpenClaw Plugin 必須隨附 `openclaw.plugin.json`，並包含內嵌 JSON Schema（`configSchema`，即使為空也需要）。相容 bundle 則改用自己的 bundle manifest。
`plugins list` 會顯示 `Format: openclaw` 或 `Format: bundle`。Verbose list/info 輸出也會顯示 bundle 子類型（`codex`、`claude` 或 `cursor`）以及偵測到的 bundle 能力。
</Note>
### 安裝
```bash
openclaw plugins install <package> # ClawHub first, then npm
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install <package> --force # overwrite existing install
openclaw plugins install <package> --pin # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # local path
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
<Warning>
裸 package 名稱會先對 ClawHub 檢查，然後才是 npm。請像執行程式碼一樣看待 Plugin 安裝。建議使用固定版本。
</Warning>
<Note>
ClawHub 是多數 Plugin 的主要發佈與探索介面。Npm 仍是受支援的備援與直接安裝路徑。在遷移到 ClawHub 期間，OpenClaw 仍會在 npm 上發佈一些 OpenClaw 擁有的 `@openclaw/*` Plugin package；這些 package 版本可能會落後於 Plugin release train 之間的 bundled source。如果 npm 將 OpenClaw 擁有的 Plugin package 回報為 deprecated，該已發佈版本就是舊的外部 artifact；請使用目前 OpenClaw 隨附的 Plugin，或使用 local checkout，直到更新的 npm package 發佈為止。
</Note>
<AccordionGroup>
<Accordion title="設定 include 與無效設定復原">
如果你的 `plugins` 區段由單一檔案 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會寫入該 included 檔案，並保持 `openclaw.json` 不變。Root include、include 陣列，以及帶有 sibling override 的 include 會失敗關閉，而不是攤平成設定。支援的形狀請參閱[設定 include](/zh-TW/gateway/configuration)。
如果安裝期間設定無效，`plugins install` 通常會失敗關閉，並提示你先執行 `openclaw doctor --fix`。Gateway 啟動期間，單一 Plugin 的無效設定會隔離到該 Plugin，讓其他 channel 和 Plugin 可以繼續執行；`openclaw doctor --fix` 可以隔離無效的 Plugin 項目。唯一有文件記載的安裝時例外，是一條狹窄的 bundled Plugin 復原路徑，僅適用於明確 opt in `openclaw.install.allowInvalidConfigRecovery` 的 Plugin。
</Accordion>
<Accordion title="--force 與重新安裝 vs 更新">
`--force` 會重用現有安裝目標，並就地覆寫已安裝的 Plugin 或 hook pack。當你有意從新的本機路徑、archive、ClawHub package 或 npm artifact 重新安裝相同 id 時使用它。對於已追蹤 npm Plugin 的例行升級，建議使用 `openclaw plugins update <id-or-npm-spec>`。
如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並指向 `plugins update <id-or-npm-spec>` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時，指向 `plugins install <package> --force`。
</Accordion>
<Accordion title="--pin 範圍">
`--pin` 只適用於 npm 安裝。它不支援與 `--marketplace` 搭配使用，因為 marketplace 安裝會持久化 marketplace source metadata，而不是 npm spec。
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 是針對內建危險程式碼掃描器誤判的 break-glass 選項。它允許在內建掃描器回報 `critical` finding 時繼續安裝，但它**不會**繞過 Plugin `before_install` hook policy block，也**不會**繞過掃描失敗。
這個 CLI flag 適用於 Plugin install/update flow。Gateway 支援的 skill dependency install 會使用對應的 `dangerouslyForceUnsafeInstall` request override，而 `openclaw skills install` 仍是獨立的 ClawHub skill download/install flow。
如果你發佈在 ClawHub 上的 Plugin 被 registry scan 封鎖，請使用 [ClawHub](/zh-TW/tools/clawhub) 中的 publisher steps。
</Accordion>
<Accordion title="Hook pack 與 npm spec">
`plugins install` 也是安裝在 `package.json` 中公開 `openclaw.hooks` 的 hook pack 的介面。請使用 `openclaw hooks` 進行篩選後的 hook 可見性與個別 hook 啟用，而不是 package 安裝。
Npm spec 是**僅限 registry**（package 名稱 + 選用的**精確版本**或 **dist-tag**）。Git/URL/file spec 與 semver range 會被拒絕。即使你的 shell 有全域 npm install 設定，dependency install 也會以 project-local 方式搭配 `--ignore-scripts` 執行，以確保安全。
當你想略過 ClawHub lookup 並直接從 npm 安裝時，請使用 `npm:<package>`。裸 package spec 仍會優先使用 ClawHub，只有在 ClawHub 沒有該 package 或版本時才會 fallback 到 npm。
裸 spec 與 `@latest` 會留在 stable track。如果 npm 將其中任一解析為 prerelease，OpenClaw 會停止並要求你使用 prerelease tag（例如 `@beta`/`@rc`）或精確 prerelease 版本（例如 `@1.2.3-beta.4`）明確 opt in。
如果裸 install spec 符合 bundled Plugin id（例如 `diffs`），OpenClaw 會直接安裝 bundled Plugin。若要安裝同名的 npm package，請使用明確 scoped spec（例如 `@scope/diffs`）。
</Accordion>
<Accordion title="Archive">
支援的 archive：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin archive 必須在解壓後的 Plugin root 包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的 archive 會在 OpenClaw 寫入安裝記錄前被拒絕。
也支援 Claude marketplace 安裝。
</Accordion>
</AccordionGroup>
ClawHub 安裝使用明確的 `clawhub:<package>` locator：
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw 現在也會對裸 npm-safe Plugin spec 優先使用 ClawHub。只有在 ClawHub 沒有該 package 或版本時，它才會 fallback 到 npm：
```bash
openclaw plugins install openclaw-codex-app-server
```
使用 `npm:` 強制僅以 npm 解析，例如當 ClawHub 無法連線，或你知道該 package 只存在於 npm 時：
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw 會從 ClawHub 下載 package archive，檢查宣告的 Plugin API / 最低 gateway 相容性，然後透過一般 archive 路徑安裝。記錄下來的安裝會保留其 ClawHub source metadata，以便日後更新。
未指定版本的 ClawHub 安裝會保留未指定版本的 recorded spec，讓 `openclaw plugins update` 可以跟隨較新的 ClawHub release；明確版本或 tag selector（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）會保持固定在該 selector。
#### Marketplace 簡寫
當 marketplace 名稱存在於 Claude 位於 `~/.claude/plugins/known_marketplaces.json` 的本機 registry cache 時，請使用 `plugin@marketplace` 簡寫：
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
當你想明確傳入 marketplace source 時，請使用 `--marketplace`：
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="Marketplace source">
- 來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude known-marketplace 名稱
- 本機 marketplace root 或 `marketplace.json` 路徑
- GitHub repo 簡寫，例如 `owner/repo`
- GitHub repo URL，例如 `https://github.com/owner/repo`
- git URL
</Tab>
<Tab title="遠端 marketplace 規則">
對於從 GitHub 或 git 載入的遠端 marketplace，Plugin 項目必須保持在 cloned marketplace repo 內。OpenClaw 接受來自該 repo 的相對路徑 source，並拒絕來自 remote manifest 的 HTTP(S)、絕對路徑、git、GitHub，以及其他非路徑 Plugin source。
</Tab>
</Tabs>
對於本機路徑和 archive，OpenClaw 會自動偵測：
- 原生 OpenClaw Plugin（`openclaw.plugin.json`）
- Codex 相容 bundle（`.codex-plugin/plugin.json`）
- Claude 相容 bundle（`.claude-plugin/plugin.json` 或預設 Claude component layout）
- Cursor 相容 bundle（`.cursor-plugin/plugin.json`）
<Note>
相容 bundle 會安裝到一般 Plugin root，並參與相同的 list/info/enable/disable flow。目前支援 bundle skill、Claude command-skill、Claude `settings.json` 預設值、Claude `.lsp.json` / manifest 宣告的 `lspServers` 預設值、Cursor command-skill，以及相容 Codex hook 目錄；其他偵測到的 bundle 能力會顯示在 diagnostics/info 中，但尚未接入 runtime execution。
</Note>
### 列出
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
```
<ParamField path="--enabled" type="boolean">
僅顯示已啟用的 Plugin。
</ParamField>
<ParamField path="--verbose" type="boolean">
從表格檢視切換為每個 Plugin 的詳細行，包含 source/origin/version/activation metadata。
</ParamField>
<ParamField path="--json" type="boolean">
機器可讀 inventory 與 registry diagnostics。
</ParamField>
<Note>
`plugins list` 會先讀取已持久化的本機 Plugin 登錄檔；如果登錄檔遺失或無效，才會使用僅由資訊清單衍生的後援資料。它適合用來檢查某個 Plugin 是否已安裝、已啟用，並且對冷啟動規劃可見，但它不是針對已在執行中的 Gateway 程序的即時執行階段探測。變更 Plugin 程式碼、啟用狀態、掛鉤政策或 `plugins.load.paths` 後，請重新啟動提供該通道服務的 Gateway，然後才期待新的 `register(api)` 程式碼或掛鉤執行。對於遠端/容器部署，請確認你重新啟動的是實際的 `openclaw gateway run` 子程序，而不只是包裝程序。
</Note>
對於封裝 Docker 映像檔內的內建 Plugin 工作，請將 Plugin
原始碼目錄繫結掛載到對應的封裝原始碼路徑上，例如
`/app/extensions/synology-chat`。OpenClaw 會先於 `/app/dist/extensions/synology-chat` 探索該已掛載的原始碼
覆蓋層；單純複製的原始碼
目錄仍不會生效，因此一般封裝安裝仍會使用已編譯的 dist。
對於執行階段掛鉤偵錯：
- `openclaw plugins inspect <id> --json` 會顯示已註冊的掛鉤，以及來自模組載入檢查階段的診斷資訊。
- `openclaw gateway status --deep --require-rpc` 會確認可連線的 Gateway、服務/程序提示、設定路徑與 RPC 健康狀態。
- 非內建對話掛鉤 (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) 需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
使用 `--link` 可避免複製本機目錄（會加入到 `plugins.load.paths`）：
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` 不支援與 `--link` 搭配使用，因為連結式安裝會重用原始碼路徑，而不是覆寫受管理的安裝目標。
在 npm 安裝時使用 `--pin`，可將解析後的精確規格 (`name@version`) 儲存在受管理的 Plugin 索引中，同時保留預設的非釘選行為。
</Note>
### Plugin 索引
Plugin 安裝中繼資料是由機器管理的狀態，不是使用者設定。安裝與更新會將它寫入作用中 OpenClaw 狀態目錄底下的 `plugins/installs.json`。其頂層 `installRecords` 對應表是安裝中繼資料的持久來源，包括損壞或遺失 Plugin 資訊清單的記錄。`plugins` 陣列是由資訊清單衍生的冷登錄快取。該檔案包含請勿編輯警告，並由 `openclaw plugins update`、解除安裝、診斷與冷 Plugin 登錄檔使用。
當 OpenClaw 在設定中看到已出貨的舊版 `plugins.installs` 記錄時，會將它們移入 Plugin 索引並移除設定鍵；如果任一寫入失敗，設定記錄會被保留，確保安裝中繼資料不會遺失。
### 執行階段相依項
```bash
openclaw plugins deps
openclaw plugins deps --repair
openclaw plugins deps --prune
openclaw plugins deps --json
```
`plugins deps` 會檢查 OpenClaw 所擁有內建 Plugin 的封裝執行階段相依項階段。它不是第三方 npm 或 ClawHub Plugin 的安裝/更新路徑。
當封裝安裝在 Gateway 啟動或 `plugins doctor` 期間回報缺少內建執行階段相依項時，請使用 `--repair`。修復只會安裝缺少的已啟用內建 Plugin 相依項，並停用生命週期指令碼。使用 `--prune` 可移除舊版封裝版面配置留下的過期未知外部執行階段相依項根目錄。
### 解除安裝
```bash
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 會從 `plugins.entries`、持久化 Plugin 索引、Plugin 允許/拒絕清單項目，以及適用時的連結式 `plugins.load.paths` 項目中移除 Plugin 記錄。除非設定 `--keep-files`，否則解除安裝也會移除追蹤到的受管理安裝目錄，前提是它位於 OpenClaw 的 Plugin extensions 根目錄內。對於 active memory Plugin，記憶體槽位會重設為 `memory-core`。
<Note>
`--keep-config` 支援作為 `--keep-files` 的已棄用別名。
</Note>
### 更新
```bash
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
更新會套用到受管理 Plugin 索引中已追蹤的 Plugin 安裝，以及 `hooks.internal.installs` 中已追蹤的掛鉤套件安裝。
<AccordionGroup>
<Accordion title="解析 Plugin ID 與 npm 規格">
當你傳入 Plugin ID 時，OpenClaw 會重用該 Plugin 已記錄的安裝規格。這表示先前儲存的 dist-tag，例如 `@beta`，以及精確釘選版本，會在之後的 `update <id>` 執行中繼續使用。
對於 npm 安裝，你也可以傳入帶有 dist-tag 或精確版本的明確 npm 套件規格。OpenClaw 會將該套件名稱解析回已追蹤的 Plugin 記錄，更新該已安裝的 Plugin，並記錄新的 npm 規格供未來依 ID 更新時使用。
傳入不含版本或標籤的 npm 套件名稱，也會解析回已追蹤的 Plugin 記錄。當某個 Plugin 已釘選到精確版本，而你想將它移回登錄檔的預設發行線時，請使用此方式。
</Accordion>
<Accordion title="版本檢查與完整性漂移">
在即時 npm 更新之前，OpenClaw 會根據 npm 登錄檔中繼資料檢查已安裝的套件版本。如果已安裝版本與已記錄成品身分已經符合解析後的目標，更新會略過，不會下載、重新安裝或重寫 `openclaw.json`。
當已儲存的完整性雜湊存在，且擷取到的成品雜湊發生變化時，OpenClaw 會將其視為 npm 成品漂移。互動式 `openclaw plugins update` 命令會列印預期與實際雜湊，並在繼續前要求確認。非互動式更新輔助程式會以關閉失敗處理，除非呼叫者提供明確的續行情境政策。
</Accordion>
<Accordion title="更新時使用 --dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 也可用於 `plugins update`，作為 Plugin 更新期間內建危險程式碼掃描誤判的緊急覆寫。它仍不會繞過 Plugin `before_install` 政策封鎖或掃描失敗封鎖，而且只適用於 Plugin 更新，不適用於掛鉤套件更新。
</Accordion>
</AccordionGroup>
### 檢查
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
針對單一 Plugin 的深度內省。顯示身分、載入狀態、來源、已註冊能力、掛鉤、工具、命令、服務、Gateway 方法、HTTP 路由、政策旗標、診斷、安裝中繼資料、套件能力，以及任何偵測到的 MCP 或 LSP 伺服器支援。
每個 Plugin 都會依照它在執行階段實際註冊的內容分類：
- **plain-capability** — 一種能力類型（例如僅提供者的 Plugin）
- **hybrid-capability** — 多種能力類型（例如文字 + 語音 + 圖片）
- **hook-only** — 僅有掛鉤，沒有能力或介面
- **non-capability** — 工具/命令/服務，但沒有能力
如需能力模型的更多資訊，請參閱 [Plugin 形態](/zh-TW/plugins/architecture#plugin-shapes)。
<Note>
`--json` 旗標會輸出適合指令碼與稽核使用的機器可讀報告。`inspect --all` 會呈現整體表格，包含形態、能力種類、相容性通知、套件能力與掛鉤摘要欄位。`info` 是 `inspect` 的別名。
</Note>
### Doctor
```bash
openclaw plugins doctor
```
`doctor` 會回報 Plugin 載入錯誤、資訊清單/探索診斷，以及相容性通知。當一切正常時，會列印 `No plugin issues detected.`
對於缺少 `register`/`activate` 匯出等模組形態失敗，請用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新執行，以在診斷輸出中包含精簡的匯出形態摘要。
### 登錄檔
```bash
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json
```
本機 Plugin 登錄檔是 OpenClaw 對已安裝 Plugin 身分、啟用狀態、來源中繼資料與貢獻所有權的持久化冷讀模型。一般啟動、提供者擁有者查找、通道設定分類與 Plugin 清查，都可以在不匯入 Plugin 執行階段模組的情況下讀取它。
使用 `plugins registry` 檢查持久化登錄檔是否存在、目前有效或過期。使用 `--refresh` 可從持久化 Plugin 索引、設定政策與資訊清單/套件中繼資料重新建置它。這是修復路徑，不是執行階段啟用路徑。
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已棄用的緊急相容性開關，用於登錄檔讀取失敗。請優先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；env 後援僅供遷移推出期間的緊急啟動復原使用。
</Warning>
### Marketplace
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Marketplace list 接受本機 Marketplace 路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub 儲存庫 URL，或 git URL。`--json` 會列印解析後的來源標籤，以及已剖析的 Marketplace 資訊清單與 Plugin 項目。
## 相關
- [建置 Plugin](/zh-TW/plugins/building-plugins)
- [CLI 參考](/zh-TW/cli)
- [社群 Plugin](/zh-TW/plugins/community)

54
docs/zh-TW/cli/proxy.md Normal file
View File

@ -0,0 +1,54 @@
---
read_when:
- 您需要在本機擷取 OpenClaw 傳輸流量以進行偵錯
- 您想要檢查除錯代理工作階段、二進位大型物件，或內建查詢預設集
summary: '`openclaw proxy` 的 CLI 參考，這是本機偵錯代理與擷取檢查器'
title: 代理
x-i18n:
generated_at: "2026-04-30T02:55:47Z"
model: gpt-5.5
provider: openai
source_hash: 7af5c596fb36f67e3fcffaff14dcbb4eabbcff0b95174ac6058a097ec9fd715f
source_path: cli/proxy.md
workflow: 16
---
# `openclaw proxy`
執行本機明確式除錯代理，並檢查擷取的流量。
這是用於傳輸層級調查的除錯命令。它可以啟動本機代理、在啟用擷取的情況下執行子命令、列出擷取工作階段、查詢常見流量模式、讀取擷取的 blob，以及清除本機擷取資料。
## 命令
```bash
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
openclaw proxy blob --id <blobId>
openclaw proxy purge
```
## 查詢預設集
`openclaw proxy query --preset <name>` 接受：
- `double-sends`
- `retry-storms`
- `cache-busting`
- `ws-duplicate-frames`
- `missing-ack`
- `error-bursts`
## 備註
- `start` 預設為 `127.0.0.1`，除非已設定 `--host`。
- `run` 會啟動本機除錯代理，然後執行 `--` 之後的命令。
- 擷取內容是本機除錯資料；完成後請使用 `openclaw proxy purge`。
## 相關
- [CLI 參考](/zh-TW/cli)
- [受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)

64
docs/zh-TW/cli/qr.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- 您想快速將行動 Node 應用程式與 Gateway 配對
- 你需要 setup-code 輸出以進行遠端／手動分享
summary: '`openclaw qr` 的 CLI 參考（產生行動裝置配對 QR 碼 + 設定碼）'
title: QR 碼
x-i18n:
generated_at: "2026-04-30T02:55:52Z"
model: gpt-5.5
provider: openai
source_hash: 05e25f5cf4116adcd0630b148b6799e90304058c51c998293ebbed995f0a0533
source_path: cli/qr.md
workflow: 16
---
# `openclaw qr`
從目前的 Gateway 設定產生行動裝置配對 QR 和設定碼。
## 用法
```bash
openclaw qr
openclaw qr --setup-code-only
openclaw qr --json
openclaw qr --remote
openclaw qr --url wss://gateway.example/ws
```
## 選項
- `--remote`：偏好使用 `gateway.remote.url`；如果未設定，`gateway.tailscale.mode=serve|funnel` 仍可提供遠端公開 URL
- `--url <url>`：覆寫酬載中使用的 Gateway URL
- `--public-url <url>`：覆寫酬載中使用的公開 URL
- `--token <token>`：覆寫 bootstrap 流程用來驗證的 Gateway 權杖
- `--password <password>`：覆寫 bootstrap 流程用來驗證的 Gateway 密碼
- `--setup-code-only`：只列印設定碼
- `--no-ascii`：略過 ASCII QR 算繪
- `--json`：輸出 JSON（`setupCode`、`gatewayUrl`、`auth`、`urlSource`）
## 注意事項
- `--token` 和 `--password` 互斥。
- 設定碼本身現在帶有不透明、短效的 `bootstrapToken`，而不是共用的 Gateway 權杖/密碼。
- 在內建的節點/操作員 bootstrap 流程中，主要節點權杖仍會以 `scopes: []` 落地。
- 如果 bootstrap 交接也簽發操作員權杖，它會持續受限於 bootstrap 允許清單：`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`。
- Bootstrap 範圍檢查具有角色前綴。該操作員允許清單只滿足操作員請求；非操作員角色仍需要其自身角色前綴下的範圍。
- 行動裝置配對會對 Tailscale/公開 `ws://` Gateway URL 採取失敗關閉。私人 LAN `ws://` 仍受支援，但 Tailscale/公開行動裝置路由應使用 Tailscale Serve/Funnel 或 `wss://` Gateway URL。
- 使用 `--remote` 時，OpenClaw 需要 `gateway.remote.url` 或
`gateway.tailscale.mode=serve|funnel`。
- 使用 `--remote` 時，如果實際作用中的遠端憑證設定為 SecretRefs，且你未傳入 `--token` 或 `--password`，此命令會從作用中的 Gateway 快照解析它們。如果 Gateway 無法使用，此命令會快速失敗。
- 未使用 `--remote` 時，若未傳入 CLI 驗證覆寫，會解析本機 Gateway 驗證 SecretRefs：
- 當權杖驗證可以勝出時（明確的 `gateway.auth.mode="token"` 或沒有密碼來源勝出的推斷模式），會解析 `gateway.auth.token`。
- 當密碼驗證可以勝出時（明確的 `gateway.auth.mode="password"` 或沒有來自 auth/env 的勝出權杖的推斷模式），會解析 `gateway.auth.password`。
- 如果同時設定了 `gateway.auth.token` 和 `gateway.auth.password`（包含 SecretRefs），且未設定 `gateway.auth.mode`，設定碼解析會失敗，直到明確設定模式為止。
- Gateway 版本偏差注意事項：此命令路徑需要支援 `secrets.resolve` 的 Gateway；較舊的 Gateway 會傳回未知方法錯誤。
- 掃描後，使用以下命令核准裝置配對：
- `openclaw devices list`
- `openclaw devices approve <requestId>`
## 相關
- [CLI 參考](/zh-TW/cli)
- [配對](/zh-TW/cli/pairing)

46
docs/zh-TW/cli/reset.md Normal file
View File

@ -0,0 +1,46 @@
---
read_when:
- 您想在保留已安裝的 CLI 的同時清除本機狀態
- 你想要模擬執行以查看會移除哪些內容
summary: '`openclaw reset` 的 CLI 參考（重設本機狀態/設定）'
title: 重設
x-i18n:
generated_at: "2026-04-30T02:55:49Z"
model: gpt-5.5
provider: openai
source_hash: e4a4aba32fb44905d079bf2a22e582a3affbe9809eac9af237ce3e48da72b42c
source_path: cli/reset.md
workflow: 16
---
# `openclaw reset`
重設本機設定/狀態（保留已安裝的 CLI）。
選項：
- `--scope <scope>`：`config`、`config+creds+sessions` 或 `full`
- `--yes`：略過確認提示
- `--non-interactive`：停用提示；需要 `--scope` 和 `--yes`
- `--dry-run`：印出動作而不移除檔案
範例：
```bash
openclaw backup create
openclaw reset
openclaw reset --dry-run
openclaw reset --scope config --yes --non-interactive
openclaw reset --scope config+creds+sessions --yes --non-interactive
openclaw reset --scope full --yes --non-interactive
```
備註：
- 如果你想在移除本機狀態前取得可還原的快照，請先執行 `openclaw backup create`。
- 如果省略 `--scope`，`openclaw reset` 會使用互動式提示來選擇要移除的項目。
- `--non-interactive` 只有在同時設定 `--scope` 和 `--yes` 時才有效。
## 相關
- [CLI 參考](/zh-TW/cli)

204
docs/zh-TW/cli/sandbox.md Normal file
View File

@ -0,0 +1,204 @@
---
read_when: You are managing sandbox runtimes or debugging sandbox/tool-policy behavior.
status: active
summary: 管理沙盒執行環境並檢查實際生效的沙盒政策
title: 沙盒 CLI
x-i18n:
generated_at: "2026-04-30T02:55:54Z"
model: gpt-5.5
provider: openai
source_hash: 65520040611ccf0cfc28b28f0caf2ed1c7d3b32de06eec7884131042bba4a01e
source_path: cli/sandbox.md
workflow: 16
---
管理用於隔離代理程式執行的沙盒執行環境。
## 概覽
OpenClaw 可以在隔離的沙盒執行環境中執行代理程式，以提升安全性。`sandbox` 命令可協助你在更新或設定變更後檢查並重新建立這些執行環境。
目前通常是指：
- Docker 沙盒容器
- 當 `agents.defaults.sandbox.backend = "ssh"` 時的 SSH 沙盒執行環境
- 當 `agents.defaults.sandbox.backend = "openshell"` 時的 OpenShell 沙盒執行環境
對於 `ssh` 和 OpenShell `remote`，重新建立比 Docker 更重要：
- 初始種子建立後，遠端工作區就是權威來源
- `openclaw sandbox recreate` 會刪除所選範圍的權威遠端工作區
- 下次使用時會從目前的本機工作區再次建立種子
## 命令
### `openclaw sandbox explain`
檢查**有效的**沙盒模式／範圍／工作區存取、沙盒工具政策，以及提升權限閘門（含修正用設定鍵路徑）。
```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```
### `openclaw sandbox list`
列出所有沙盒執行環境及其狀態和設定。
```bash
openclaw sandbox list
openclaw sandbox list --browser # List only browser containers
openclaw sandbox list --json # JSON output
```
**輸出包含：**
- 執行環境名稱和狀態
- 後端（`docker`、`openshell` 等）
- 設定標籤，以及它是否符合目前設定
- 年齡（自建立以來的時間）
- 閒置時間（自上次使用以來的時間）
- 關聯的工作階段／代理程式
### `openclaw sandbox recreate`
移除沙盒執行環境，以強制使用更新後的設定重新建立。
```bash
openclaw sandbox recreate --all # Recreate all containers
openclaw sandbox recreate --session main # Specific session
openclaw sandbox recreate --agent mybot # Specific agent
openclaw sandbox recreate --browser # Only browser containers
openclaw sandbox recreate --all --force # Skip confirmation
```
**選項：**
- `--all`：重新建立所有沙盒容器
- `--session <key>`：重新建立特定工作階段的容器
- `--agent <id>`：重新建立特定代理程式的容器
- `--browser`：只重新建立瀏覽器容器
- `--force`：略過確認提示
<Note>
執行環境會在代理程式下次使用時自動重新建立。
</Note>
## 使用情境
### 更新 Docker 映像後
```bash
# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
# Recreate containers
openclaw sandbox recreate --all
```
### 變更沙盒設定後
```bash
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
# Recreate to apply new config
openclaw sandbox recreate --all
```
### 變更 SSH 目標或 SSH 驗證資料後
```bash
# Edit config:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
openclaw sandbox recreate --all
```
對於核心 `ssh` 後端，重新建立會刪除 SSH 目標上每個範圍的遠端工作區根目錄。下一次執行會從本機工作區再次建立種子。
### 變更 OpenShell 來源、政策或模式後
```bash
# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy
openclaw sandbox recreate --all
```
對於 OpenShell `remote` 模式，重新建立會刪除該範圍的權威遠端工作區。下一次執行會從本機工作區再次建立種子。
### 變更 setupCommand 後
```bash
openclaw sandbox recreate --all
# or just one agent:
openclaw sandbox recreate --agent family
```
### 僅針對特定代理程式
```bash
# Update only one agent's containers
openclaw sandbox recreate --agent alfred
```
## 為什麼需要這個功能
當你更新沙盒設定時：
- 現有執行環境會繼續以舊設定執行。
- 執行環境只會在閒置 24 小時後被清除。
- 經常使用的代理程式會讓舊執行環境無限期維持存活。
使用 `openclaw sandbox recreate` 強制移除舊執行環境。下次需要時，它們會使用目前設定自動重新建立。
<Tip>
建議使用 `openclaw sandbox recreate`，而不是手動執行特定後端的清理。它會使用 Gateway 的執行環境登錄檔，並避免在範圍或工作階段鍵變更時發生不一致。
</Tip>
## 設定
沙盒設定位於 `~/.openclaw/openclaw.json` 的 `agents.defaults.sandbox` 底下（每個代理程式的覆寫設定放在 `agents.list[].sandbox`）：
```jsonc
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"backend": "docker", // docker, ssh, openshell
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... more Docker options
},
"prune": {
"idleHours": 24, // Auto-prune after 24h idle
"maxAgeDays": 7, // Auto-prune after 7 days
},
},
},
},
}
```
## 相關
- [CLI 參考](/zh-TW/cli)
- [沙盒化](/zh-TW/gateway/sandboxing)
- [代理程式工作區](/zh-TW/concepts/agent-workspace)
- [Doctor](/zh-TW/gateway/doctor)：檢查沙盒設定。

209
docs/zh-TW/cli/secrets.md Normal file
View File

@ -0,0 +1,209 @@
---
read_when:
- 在執行階段重新解析秘密參照
- 稽核明文殘留與未解決的參照
- 設定 SecretRefs 並套用單向清理變更
summary: '`openclaw secrets` 的 CLI 參考（reload、audit、configure、apply）'
title: 機密資訊
x-i18n:
generated_at: "2026-04-30T02:56:24Z"
model: gpt-5.5
provider: openai
source_hash: 6fe1933ca6a9f2a24fbbe20fa3b83bf8f6493ea6c94061e135b4e1b48c33d62c
source_path: cli/secrets.md
workflow: 16
---
# `openclaw secrets`
使用 `openclaw secrets` 管理 SecretRef，並保持作用中的執行階段快照健康。
命令角色：
- `reload`：Gateway RPC（`secrets.reload`），會重新解析 ref，且僅在完全成功時替換執行階段快照（不寫入設定）。
- `audit`：唯讀掃描設定、驗證、產生的模型儲存區和舊版殘留，檢查明文、未解析的 ref，以及優先順序漂移（除非設定 `--allow-exec`，否則會略過 exec ref）。
- `configure`：用於提供者設定、目標對應和預檢的互動式規劃器（需要 TTY）。
- `apply`：執行已儲存的計畫（`--dry-run` 僅用於驗證；dry-run 預設會略過 exec 檢查，而寫入模式會拒絕包含 exec 的計畫，除非設定 `--allow-exec`），然後清除目標明文殘留。
建議的操作員循環：
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload
```
如果你的計畫包含 `exec` SecretRef/提供者，請在 dry-run 和寫入 apply 命令中都傳入 `--allow-exec`。
CI/閘門的結束代碼注意事項：
- `audit --check` 發現問題時會傳回 `1`。
- 未解析的 ref 會傳回 `2`。
相關：
- 秘密指南：[Secrets Management](/zh-TW/gateway/secrets)
- 憑證介面：[SecretRef Credential Surface](/zh-TW/reference/secretref-credential-surface)
- 安全性指南：[Security](/zh-TW/gateway/security)
## 重新載入執行階段快照
重新解析秘密 ref，並以原子方式替換執行階段快照。
```bash
openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
```
注意事項：
- 使用 Gateway RPC 方法 `secrets.reload`。
- 如果解析失敗，Gateway 會保留最後已知正常的快照並傳回錯誤（不會部分啟用）。
- JSON 回應包含 `warningCount`。
選項：
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--json`
## 稽核
掃描 OpenClaw 狀態以檢查：
- 明文秘密儲存
- 未解析的 ref
- 優先順序漂移（`auth-profiles.json` 憑證遮蔽 `openclaw.json` ref）
- 產生的 `agents/*/agent/models.json` 殘留（提供者 `apiKey` 值和敏感提供者標頭）
- 舊版殘留（舊版驗證儲存項目、OAuth 提醒）
標頭殘留注意事項：
- 敏感提供者標頭偵測是以名稱啟發式為基礎（常見驗證/憑證標頭名稱，以及像 `authorization`、`x-api-key`、`token`、`secret`、`password` 和 `credential` 這類片段）。
```bash
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec
```
結束行為：
- `--check` 發現問題時會以非零代碼結束。
- 未解析的 ref 會以較高優先級的非零代碼結束。
報告形狀重點：
- `status`：`clean | findings | unresolved`
- `resolution`：`refsChecked`、`skippedExecRefs`、`resolvabilityComplete`
- `summary`：`plaintextCount`、`unresolvedRefCount`、`shadowedRefCount`、`legacyResidueCount`
- 發現代碼：
- `PLAINTEXT_FOUND`
- `REF_UNRESOLVED`
- `REF_SHADOWED`
- `LEGACY_RESIDUE`
## 設定（互動式輔助工具）
以互動方式建置提供者和 SecretRef 變更、執行預檢，並可選擇套用：
```bash
openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json
```
流程：
- 先設定提供者（對 `secrets.providers` 別名進行 `add/edit/remove`）。
- 再對應憑證（選取欄位並指派 `{source, provider, id}` ref）。
- 最後執行預檢並可選擇套用。
旗標：
- `--providers-only`：只設定 `secrets.providers`，略過憑證對應。
- `--skip-provider-setup`：略過提供者設定，並將憑證對應到現有提供者。
- `--agent <id>`：將 `auth-profiles.json` 目標探索和寫入限定到一個代理程式儲存區。
- `--allow-exec`：允許在預檢/apply 期間執行 exec SecretRef 檢查（可能會執行提供者命令）。
注意事項：
- 需要互動式 TTY。
- 你不能將 `--providers-only` 與 `--skip-provider-setup` 組合使用。
- `configure` 會以 `openclaw.json` 中帶有秘密的欄位為目標，並包含所選代理程式範圍的 `auth-profiles.json`。
- `configure` 支援直接在選取器流程中建立新的 `auth-profiles.json` 對應。
- 標準支援介面：[SecretRef Credential Surface](/zh-TW/reference/secretref-credential-surface)。
- 它會在套用前執行預檢解析。
- 如果預檢/apply 包含 exec ref，請在兩個步驟都保持設定 `--allow-exec`。
- 產生的計畫預設啟用清除選項（`scrubEnv`、`scrubAuthProfilesForProviderTargets`、`scrubLegacyAuthJson` 全部啟用）。
- apply 路徑對已清除的明文值是單向的。
- 若未使用 `--apply`，CLI 仍會在預檢後提示 `Apply this plan now?`。
- 使用 `--apply`（且沒有 `--yes`）時，CLI 會提示額外的不可逆確認。
- `--json` 會列印計畫和預檢報告，但命令仍需要互動式 TTY。
exec 提供者安全性注意事項：
- Homebrew 安裝通常會在 `/opt/homebrew/bin/*` 下公開符號連結的二進位檔。
- 僅在受信任套件管理器路徑需要時，才設定 `allowSymlinkCommand: true`，並搭配 `trustedDirs`（例如 `["/opt/homebrew"]`）。
- 在 Windows 上，如果無法對提供者路徑進行 ACL 驗證，OpenClaw 會採取失敗關閉。僅對受信任路徑，在該提供者上設定 `allowInsecurePath: true` 以略過路徑安全性檢查。
## 套用已儲存的計畫
套用或預檢先前產生的計畫：
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
```
exec 行為：
- `--dry-run` 會驗證預檢而不寫入檔案。
- dry-run 預設會略過 exec SecretRef 檢查。
- 寫入模式會拒絕包含 exec SecretRef/提供者的計畫，除非設定 `--allow-exec`。
- 使用 `--allow-exec` 在任一模式中選擇加入 exec 提供者檢查/執行。
計畫合約詳細資訊（允許的目標路徑、驗證規則和失敗語意）：
- [Secrets Apply Plan Contract](/zh-TW/gateway/secrets-plan-contract)
`apply` 可能更新的內容：
- `openclaw.json`（SecretRef 目標 + 提供者 upsert/delete）
- `auth-profiles.json`（提供者目標清除）
- 舊版 `auth.json` 殘留
- `~/.openclaw/.env` 中已遷移其值的已知秘密鍵
## 為什麼沒有復原備份
`secrets apply` 刻意不寫入包含舊明文值的復原備份。
安全性來自嚴格預檢，以及失敗時盡力進行記憶體內還原的近似原子套用。
## 範例
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```
如果 `audit --check` 仍回報明文發現項目，請更新剩餘回報的目標路徑並重新執行稽核。
## 相關
- [CLI reference](/zh-TW/cli)
- [Secrets management](/zh-TW/gateway/secrets)

96
docs/zh-TW/cli/security.md Normal file
View File

@ -0,0 +1,96 @@
---
read_when:
- 你想要對設定/狀態執行快速安全稽核
- 你想要套用安全的「修復」建議（權限、收緊預設值）
summary: '`openclaw security` 的 CLI 參考（稽核並修正常見的安全性陷阱）'
title: 安全性
x-i18n:
generated_at: "2026-04-30T02:56:21Z"
model: gpt-5.5
provider: openai
source_hash: b4c15f2111cac2492aa331e5217dd18de169c8b6440f103e3009e059a06d81f6
source_path: cli/security.md
workflow: 16
---
# `openclaw security`
安全工具（稽核 + 選用修正）。
相關：
- 安全指南：[安全](/zh-TW/gateway/security)
## 稽核
```bash
openclaw security audit
openclaw security audit --deep
openclaw security audit --deep --password <password>
openclaw security audit --deep --token <token>
openclaw security audit --fix
openclaw security audit --json
```
當多個 DM 傳送者共用主要工作階段時，稽核會發出警告，並建議使用**安全 DM 模式**：共享收件匣使用 `session.dmScope="per-channel-peer"`（多帳號通道則使用 `per-account-channel-peer`）。
這是為了強化協作式/共享收件匣。由互不信任或具對抗性的操作者共用單一 Gateway 並非建議的設定；請使用個別 Gateway（或個別 OS 使用者/主機）分隔信任邊界。
當設定顯示可能有共享使用者入口時（例如開放 DM/群組政策、已設定的群組目標，或萬用字元傳送者規則），它也會發出 `security.trust_model.multi_user_heuristic`，並提醒你 OpenClaw 預設是個人助理信任模型。
對於刻意的共享使用者設定，稽核指引是將所有工作階段沙盒化、將檔案系統存取限制在工作區範圍內，並讓個人/私人身分或憑證遠離該執行環境。
當小型模型（`<=300B`）在未沙盒化且啟用 Web/瀏覽器工具的情況下使用時，它也會發出警告。
對於 Webhook 入口，當 `hooks.token` 重複使用 Gateway 權杖、`hooks.token` 過短、`hooks.path="/"`、`hooks.defaultSessionKey` 未設定、`hooks.allowedAgentIds` 不受限制、啟用請求 `sessionKey` 覆寫，以及在未設定 `hooks.allowedSessionKeyPrefixes` 的情況下啟用覆寫時，它會發出警告。
當沙盒 Docker 設定已設定但沙盒模式關閉、`gateway.nodes.denyCommands` 使用無效的類模式/未知項目（僅精確比對節點命令名稱，不做 shell 文字過濾）、`gateway.nodes.allowCommands` 明確啟用危險節點命令、全域 `tools.profile="minimal"` 被代理工具設定檔覆寫、開放群組在沒有沙盒/工作區防護的情況下暴露執行環境/檔案系統工具，以及已安裝的 Plugin 工具可能在寬鬆工具政策下可被存取時，它也會發出警告。
它也會標記 `gateway.allowRealIpFallback=true`（若代理設定錯誤，會有標頭偽造風險）和 `discovery.mdns.mode="full"`（透過 mDNS TXT 記錄洩漏中繼資料）。
當沙盒瀏覽器使用 Docker `bridge` 網路但未設定 `sandbox.browser.cdpSourceRange` 時，它也會發出警告。
它也會標記危險的沙盒 Docker 網路模式（包括 `host` 和 `container:*` 命名空間加入）。
當既有的沙盒瀏覽器 Docker 容器缺少/過期的雜湊標籤時（例如遷移前容器缺少 `openclaw.browserConfigEpoch`），它也會發出警告，並建議執行 `openclaw sandbox recreate --browser --all`。
當 npm 型 Plugin/鉤子安裝記錄未釘選、缺少完整性中繼資料，或與目前已安裝套件版本偏離時，它也會發出警告。
當通道允許清單依賴可變的名稱/電子郵件/標籤，而不是穩定 ID 時（Discord、Slack、Google Chat、Microsoft Teams、Mattermost、IRC 範圍，視適用情況而定），它會發出警告。
當 `gateway.auth.mode="none"` 讓 Gateway HTTP API 在沒有共享密鑰的情況下可被存取時（`/tools/invoke` 加上任何已啟用的 `/v1/*` 端點），它會發出警告。
以 `dangerous`/`dangerously` 為前綴的設定是明確的緊急操作者覆寫；啟用其中一項本身並不構成安全漏洞報告。
如需完整的危險參數清單，請參閱[安全](/zh-TW/gateway/security)中的「不安全或危險旗標摘要」章節。
SecretRef 行為：
- `security audit` 會以唯讀模式解析其目標路徑中支援的 SecretRefs。
- 如果目前命令路徑中無法使用某個 SecretRef，稽核會繼續並回報 `secretDiagnostics`（而不是當機）。
- `--token` 和 `--password` 只會覆寫該次命令叫用的深度探測驗證；它們不會重寫設定或 SecretRef 對應。
## JSON 輸出
使用 `--json` 進行 CI/政策檢查：
```bash
openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
```
如果合併使用 `--fix` 和 `--json`，輸出會同時包含修正動作和最終報告：
```bash
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
```
## `--fix` 會變更什麼
`--fix` 會套用安全且決定性的修復：
- 將常見的 `groupPolicy="open"` 翻轉為 `groupPolicy="allowlist"`（包含受支援通道中的帳號變體）
- 當 WhatsApp 群組政策翻轉為 `allowlist` 時，若儲存的 `allowFrom` 檔案存在且設定尚未定義 `allowFrom`，則從該檔案植入 `groupAllowFrom`
- 將 `logging.redactSensitive` 從 `"off"` 設為 `"tools"`
- 收緊狀態/設定和常見敏感檔案的權限
(`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session
`*.jsonl`)
- 也會收緊從 `openclaw.json` 參照的設定 include 檔案
- 在 POSIX 主機上使用 `chmod`，並在 Windows 上使用 `icacls` 重設
`--fix` **不會**：
- 輪替權杖/密碼/API 金鑰
- 停用工具（`gateway`、`cron`、`exec` 等）
- 變更 Gateway 繫結/驗證/網路暴露選擇
- 移除或重寫 Plugin/Skills
## 相關
- [CLI 參考](/zh-TW/cli)
- [安全稽核](/zh-TW/gateway/security)

130
docs/zh-TW/cli/sessions.md Normal file
View File

@ -0,0 +1,130 @@
---
read_when:
- 您想列出已儲存的工作階段並查看近期活動
summary: CLI 參考：`openclaw sessions`（列出已儲存的工作階段 + 使用方式）
title: 工作階段
x-i18n:
generated_at: "2026-04-30T02:56:13Z"
model: gpt-5.5
provider: openai
source_hash: 9fea2014f538b00a27fa0078391a421843052333c5bcfc8100fced515eed0004
source_path: cli/sessions.md
workflow: 16
---
# `openclaw sessions`
列出已儲存的對話工作階段。
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --verbose
openclaw sessions --json
```
範圍選擇：
- 預設：已設定的預設代理程式儲存區
- `--verbose`：詳細記錄
- `--agent <id>`：一個已設定的代理程式儲存區
- `--all-agents`：彙總所有已設定的代理程式儲存區
- `--store <path>`：明確的儲存區路徑（不能與 `--agent` 或 `--all-agents` 搭配使用）
為已儲存的工作階段匯出軌跡套件：
```bash
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
這是 `/export-trajectory` 斜線命令在擁有者核准 exec 請求後使用的命令路徑。輸出目錄一律會在所選工作區底下的 `.openclaw/trajectory-exports/` 內解析。
`openclaw sessions --all-agents` 會讀取已設定的代理程式儲存區。Gateway 和 ACP 工作階段探索範圍更廣：它們也會包含在預設 `agents/` 根目錄或範本化 `session.store` 根目錄下找到的僅磁碟儲存區。這些探索到的儲存區必須解析為代理程式根目錄內的一般 `sessions.json` 檔案；符號連結與根目錄外路徑會被略過。
JSON 範例：
`openclaw sessions --all-agents --json`：
```json
{
"path": null,
"stores": [
{ "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
{ "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
],
"allAgents": true,
"count": 2,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
{ "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
]
}
```
## 清理維護
立即執行維護（而不是等待下一個寫入週期）：
```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --agent work --dry-run
openclaw sessions cleanup --all-agents --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
openclaw sessions cleanup --json
```
`openclaw sessions cleanup` 會使用設定中的 `session.maintenance` 設定：
- 範圍注意事項：`openclaw sessions cleanup` 會維護工作階段儲存區、逐字稿與軌跡伴隨檔。它不會修剪 Cron 執行記錄（`cron/runs/<jobId>.jsonl`），這些記錄由 [Cron 設定](/zh-TW/automation/cron-jobs#configuration) 中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，並在 [Cron 維護](/zh-TW/automation/cron-jobs#maintenance) 中說明。
- `--dry-run`：預覽在不寫入的情況下會修剪/限制多少項目。
- 在文字模式中，dry-run 會列印每個工作階段的動作表（`Action`、`Key`、`Age`、`Model`、`Flags`），讓你查看哪些會保留、哪些會移除。
- `--enforce`：即使 `session.maintenance.mode` 是 `warn`，也套用維護。
- `--fix-missing`：移除逐字稿檔案遺失的項目，即使它們通常尚未因存留時間/數量而淘汰。
- `--active-key <key>`：保護特定作用中鍵不受磁碟預算逐出。
- `--agent <id>`：為一個已設定的代理程式儲存區執行清理。
- `--all-agents`：為所有已設定的代理程式儲存區執行清理。
- `--store <path>`：針對特定 `sessions.json` 檔案執行。
- `--json`：列印 JSON 摘要。搭配 `--all-agents` 時，輸出會包含每個儲存區的一份摘要。
`openclaw sessions cleanup --all-agents --dry-run --json`：
```json
{
"allAgents": true,
"mode": "warn",
"dryRun": true,
"stores": [
{
"agentId": "main",
"storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
"beforeCount": 120,
"afterCount": 80,
"pruned": 40,
"capped": 0
},
{
"agentId": "work",
"storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
"beforeCount": 18,
"afterCount": 18,
"pruned": 0,
"capped": 0
}
]
}
```
相關：
- 工作階段設定：[設定參考](/zh-TW/gateway/config-agents#session)
## 相關
- [CLI 參考](/zh-TW/cli)
- [工作階段管理](/zh-TW/concepts/session)

62
docs/zh-TW/cli/setup.md Normal file
View File

@ -0,0 +1,62 @@
---
read_when:
- 你正在進行首次執行設定，但未使用完整的 CLI 入門導引
- 你想要設定預設工作區路徑
summary: '`openclaw setup` 的 CLI 參考（初始化設定 + 工作區）'
title: 設定
x-i18n:
generated_at: "2026-04-30T02:56:32Z"
model: gpt-5.5
provider: openai
source_hash: 68e5c07a6b1769420c2125677f3eda9bd4841c938b4fc62583c5bed2a2596250
source_path: cli/setup.md
workflow: 16
---
# `openclaw setup`
初始化 `~/.openclaw/openclaw.json` 與代理工作區。
相關：
- 開始使用：[開始使用](/zh-TW/start/getting-started)
- CLI 入門導覽：[入門導覽（CLI）](/zh-TW/start/wizard)
## 範例
```bash
openclaw setup
openclaw setup --workspace ~/.openclaw/workspace
openclaw setup --wizard
openclaw setup --wizard --import-from hermes --import-source ~/.hermes
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
```
## 選項
- `--workspace <dir>`：代理工作區目錄（儲存為 `agents.defaults.workspace`）
- `--wizard`：執行入門導覽
- `--non-interactive`：不顯示提示並執行入門導覽
- `--mode <local|remote>`：入門導覽模式
- `--import-from <provider>`：入門導覽期間要執行的遷移提供者
- `--import-source <path>`：`--import-from` 的來源代理主目錄
- `--import-secrets`：在入門導覽遷移期間匯入支援的秘密
- `--remote-url <url>`：遠端 Gateway WebSocket URL
- `--remote-token <token>`：遠端 Gateway 權杖
若要透過 setup 執行入門導覽：
```bash
openclaw setup --wizard
```
注意事項：
- 單純執行 `openclaw setup` 會初始化設定與工作區，而不會執行完整的入門導覽流程。
- 當任何入門導覽旗標存在時，會自動執行入門導覽（`--wizard`、`--non-interactive`、`--mode`、`--import-from`、`--import-source`、`--import-secrets`、`--remote-url`、`--remote-token`）。
- 如果偵測到 Hermes 狀態，互動式入門導覽可以自動提供遷移。匯入入門導覽需要全新設定；若要在入門導覽之外進行試跑計畫、備份與覆寫模式，請使用[遷移](/zh-TW/cli/migrate)。
## 相關
- [CLI 參考](/zh-TW/cli)
- [安裝概觀](/zh-TW/install)

Some files were not shown because too many files have changed in this diff Show More