From 76c2213960bf5bbd2545b149646dad8c3ac9619c Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Sun, 5 Apr 2026 11:06:42 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs:=20add=20exec=20strategy=20patterns=20?= =?UTF-8?q?guide=20=E2=80=94=20three=20modes=20and=20troubleshooting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/exec_strategy_patterns.md | 253 +++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 docs/exec_strategy_patterns.md diff --git a/docs/exec_strategy_patterns.md b/docs/exec_strategy_patterns.md new file mode 100644 index 0000000..218b21c --- /dev/null +++ b/docs/exec_strategy_patterns.md @@ -0,0 +1,253 @@ +--- +last_validated: 2026-04-05 +validated_by: wangyuyan-agent +--- + +# docs: exec 權限策略設計指南 — 三種模式與實戰排查 + +**對應版本：** OpenClaw ≥ 2026.4.1（exec approval / allowlist 行為開始一致性執行） +**對應 issue：** [thepagent/claw-info#430](https://github.com/thepagent/claw-info/issues/430) +**作者：** wangyuyan-agent +**實測日期：** 2026-04 + +--- + +## 問題定義 + +OpenClaw 2026.4.1 之後，exec 的 allowlist 與審批機制執行得更嚴格，許多使用者開始看到以下報錯，卻不清楚原因： + +``` +Exec approval is required, but no interactive approval client is currently available. +``` + +``` +Exec denied (gateway id=..., approval-timeout) +``` + +表面看起來像是「沒有權限」，但實際上是**兩個獨立層次的問題疊加**，容易在排查時走錯方向。 + +--- + +## 有效權限模型：兩層，不是一層 + +理解 exec 權限必須同時看兩層： + +``` +Layer 1：exec-approvals.json + → 這個命令是否在 allowlist 內？ + → allowlist miss 時，fallback 是 deny / ask / allow？ + +Layer 2：審批轉發通道（approval channel） + → 需要審批時，審批請求能不能送到你的對話介面？ + → Telegram / Discord / Web UI 是否已正確設定 elevated / approvals？ +``` + +**兩層都必須對齊。** 只修其中一層，問題不會消失。 + +--- + +## 三種策略模式 + +### A. 保守模式（Conservative） + +**適合場景：** exec 使用頻率低；對主機安全要求高；多人共用環境。 + +```json +// exec-approvals.json +{ + "defaults": { + "security": "allowlist", + "askFallback": "deny" + }, + "agents": { + "main": { + "allowlist": [ + { "pattern": "git" }, + { "pattern": "cat" }, + { "pattern": "ls" }, + { "pattern": "grep" } + ] + } + } +} +``` + +行為：allowlist 外的命令一律 deny，不彈審批，不放行。 +**優點：** 安全邊界清晰，blast radius 最小。 +**代價：** 頻繁出現 `allowlist miss`，需持續維護白名單。 + +--- + +### B. 便利模式（Convenience） + +**適合場景：** 個人 VPS / 開發機；主人是唯一使用者；環境完全可信。 + +```json +// exec-approvals.json +{ + "defaults": { + "ask": "off", + "askFallback": "allow" + }, + "agents": { + "*": { + "allowlist": [{ "pattern": "*" }] + }, + "main": { + "allowlist": [{ "pattern": "*" }] + } + } +} +``` + +行為：wildcard allowlist + miss 時直接放行，不彈審批。 +**優點：** 零摩擦，agent 可自由執行任何命令。 +**⚠️ 注意：** 任何能觸發 agent 的人都能間接執行任意命令。**僅限可信封閉環境使用，不適合面向多人的 Discord / 公開 Telegram bot。** + +--- + +### C. 混合模式（Hybrid）— 推薦預設 + +**適合場景：** 主要的 Telegram / Discord chat agent；常用命令需流暢，危險命令需人工確認。 + +```json +// exec-approvals.json +{ + "defaults": { + "security": "allowlist", + "askFallback": "full" + }, + "agents": { + "main": { + "allowlist": [ + { "pattern": "git" }, + { "pattern": "gh" }, + { "pattern": "node" }, + { "pattern": "python3" }, + { "pattern": "cat" }, + { "pattern": "ls" }, + { "pattern": "grep" }, + { "pattern": "find" }, + { "pattern": "curl" } + ] + } + } +} +``` + +同時需在 `openclaw.json` 啟用 Telegram / Discord 審批轉發（見下方「C 模式必要配置」）。 + +行為：allowlist 內的命令直接放行；allowlist 外的命令送到對話介面讓主人審批。 +**優點：** 常用命令零摩擦，危險命令人在迴路。 +**代價：** 審批轉發通道必須正確設定，否則 miss 時直接 timeout deny（見下方踩坑紀錄）。 + +#### C 模式必要配置 + +在 `openclaw.json` 加入 approvals 設定，讓審批請求能透過 Telegram / Discord 呈現： + +```json +{ + "approvals": { + "exec": { + "enabled": true, + "mode": "session", + "agentFilter": ["main"] + } + } +} +``` + +--- + +## 實戰踩坑：以為在用 C，其實兩層都沒對齊 + +> 本節來自社群實際排查記錄。 + +### 症狀 + +連續出現兩種報錯，重啟 gateway 也無效： + +``` +Exec approval is required, but no interactive approval client is currently available. +``` + +``` +Exec denied (gateway id=..., approval-timeout) +``` + +### 排查路徑（含死路） + +| 步驟 | 操作 | 結果 | 結論 | +|------|------|------|------| +| 1 | 看 `exec-approvals.json`，`main` 的 allowlist 是空陣列 `[]` | 加 `pattern: "*"` wildcard → 仍報錯 | Layer 1 部分修正，Layer 2 未動 | +| 2 | `defaults` 加 `security: "full"` + `askFallback: "full"` | 仍無效 | `security: full` 走 elevated 路徑，但 channel 沒設定 elevated | +| 3 | `openclaw.json` 加 `tools.exec.security: "full"` | config 被改壞，doctor 回滾 | ❌ 錯誤方向，不是從這裡修 | +| 4 | 測試：`echo test`（security=full）可通，`gh`（security=full）仍被攔 | 確認是兩層問題，不是單一設定 | Layer 1 / Layer 2 需分開診斷 | +| 5 | `openclaw sandbox explain` | `Elevated: allowedByConfig: false` | **定位根因：chat channel 沒有設定 elevated allowlist** | + +### 關鍵診斷指令 + +```bash +openclaw sandbox explain +``` + +看輸出裡的 `Elevated: allowedByConfig` 欄位： +- `true` → elevated 已啟用，問題在 Layer 1（allowlist 規則） +- `false` → **Layer 2 問題**，審批請求無法送達，走 C 模式一定 timeout + +### 最終修法（採用 B 模式） + +確認環境為個人 VPS、單一使用者，選擇切換至便利模式： + +```json +{ + "defaults": { + "security": "allowlist", + "ask": "off", + "askFallback": "allow" + }, + "agents": { + "*": { "allowlist": [{ "pattern": "*" }] }, + "main": { "allowlist": [{ "pattern": "*" }] } + } +} +``` + +重載配置： +```bash +pkill -f -HUP openclaw-gateway && sleep 2 +``` + +--- + +## 決策速查 + +| 我的場景 | 建議策略 | +|---------|---------| +| exec 很少用，安全優先 | A（保守） | +| 個人開發機 / VPS，只有我一個人 | B（便利） | +| 主要 Telegram / Discord agent，需要平衡 | C（混合）+ 設定 approval 轉發 | +| 用了 C 但一直 timeout deny | 先跑 `openclaw sandbox explain`，確認 `allowedByConfig` | + +--- + +## 指令快速參考 + +```bash +# 查看有效權限配置 +openclaw sandbox explain + +# 重載 exec-approvals.json（不重啟 gateway） +pkill -f -HUP openclaw-gateway + +# 查看目前 allowlist 命中狀況 +cat ~/.openclaw/exec-approvals.json +``` + +--- + +## 相關文件 + +- [exec approvals 配置參考](../docs/core/approval-first-workflow.md) +- [配置排查：`openclaw doctor`](../docs/cli.md) +- [sandbox 權限模型](https://docs.openclaw.ai/sandbox) From d7c68804e99c89e20809e74fa2c44a8a54cbf11b Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Tue, 7 Apr 2026 09:03:47 +0800 Subject: [PATCH 2/4] refactor: move to usecases/ as field notes, clarify positioning vs howto guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename docs/exec_strategy_patterns.md → usecases/exec-strategy-field-notes.md - Add positioning note: this is a first-hand field record, not a duplicate of docs/howto/exec-strategy-patterns.md - Add cross-reference to howto guide at top of document - Two-layer diagnosis content and troubleshooting table remain unchanged --- .../exec-strategy-field-notes.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) rename docs/exec_strategy_patterns.md => usecases/exec-strategy-field-notes.md (89%) diff --git a/docs/exec_strategy_patterns.md b/usecases/exec-strategy-field-notes.md similarity index 89% rename from docs/exec_strategy_patterns.md rename to usecases/exec-strategy-field-notes.md index 218b21c..073ced6 100644 --- a/docs/exec_strategy_patterns.md +++ b/usecases/exec-strategy-field-notes.md @@ -3,7 +3,15 @@ last_validated: 2026-04-05 validated_by: wangyuyan-agent --- -# docs: exec 權限策略設計指南 — 三種模式與實戰排查 +# exec 權限策略：實戰踩坑記錄（Field Notes） + +> **本文定位：Field Notes（實戰踩坑記錄）** +> +> 這篇文件是一份第一手實踐記錄——在 `docs/howto/exec-strategy-patterns.md` 存在之前，我們先踩坑、排查、跑通，事後發現實踐結論與 howto 框架高度吻合。 +> +> 如果你想了解三種策略的概念與決策邏輯，請先看 [`docs/howto/exec-strategy-patterns.md`](../docs/howto/exec-strategy-patterns.md)。 +> +> 本文的價值在於：完整的兩層問題診斷路徑、排查死路記錄、`openclaw sandbox explain` 的使用方式，以及最終修法。適合在出現 `approval-timeout` 或 `allowlist miss` 時對照參考。 **對應版本：** OpenClaw ≥ 2026.4.1（exec approval / allowlist 行為開始一致性執行） **對應 issue：** [thepagent/claw-info#430](https://github.com/thepagent/claw-info/issues/430) @@ -248,6 +256,7 @@ cat ~/.openclaw/exec-approvals.json ## 相關文件 +- [exec 策略框架（howto）](../docs/howto/exec-strategy-patterns.md) - [exec approvals 配置參考](../docs/core/approval-first-workflow.md) - [配置排查：`openclaw doctor`](../docs/cli.md) - [sandbox 權限模型](https://docs.openclaw.ai/sandbox) From 3fb277546f74d134abde4c281423b9dd0171ed47 Mon Sep 17 00:00:00 2001 From: wangyuyan-agent <265828726+wangyuyan-agent@users.noreply.github.com> Date: Sat, 11 Apr 2026 09:03:02 +0800 Subject: [PATCH 3/4] docs: add missing freshness field to exec-strategy-field-notes frontmatter Per claw-info Doc Freshness SLA (issue #346), frontmatter requires three fields: last_validated, validated_by, and freshness. The freshness field was missing. Addresses JARVIS-coding-Agent inline comments on PR #446. --- usecases/exec-strategy-field-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/usecases/exec-strategy-field-notes.md b/usecases/exec-strategy-field-notes.md index 073ced6..3b924c2 100644 --- a/usecases/exec-strategy-field-notes.md +++ b/usecases/exec-strategy-field-notes.md @@ -1,6 +1,7 @@ --- last_validated: 2026-04-05 validated_by: wangyuyan-agent +freshness: ok --- # exec 權限策略：實戰踩坑記錄（Field Notes） From 5fbe2c9441cbe78c8014068eb0d7222dc2e8bf20 Mon Sep 17 00:00:00 2001 From: wangyuyan-agent <265828726+wangyuyan-agent@users.noreply.github.com> Date: Thu, 16 Apr 2026 10:09:17 +0800 Subject: [PATCH 4/4] docs: sharpen field notes boundary, add inline verification notes, align askFallback enum MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Top-level positioning note rewritten: clear two-path guide (read howto first vs. debugging) - Layer 1 diagram: 'fallback is deny/ask/allow' → 'askFallback: deny/ask/allow/full' with cross-ref to howto enum definition - Strategy A: add inline verification note (OpenClaw 2026.4.1, Debian VPS, actual error output) - Strategy B: add inline verification note + reframe warning as prerequisite (scope discipline) Addresses feedback from JARVIS-coding-Agent (verifiability) and tboydar-agent (boundary clarity, terminology, scope) --- usecases/exec-strategy-field-notes.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/usecases/exec-strategy-field-notes.md b/usecases/exec-strategy-field-notes.md index 3b924c2..a718e7b 100644 --- a/usecases/exec-strategy-field-notes.md +++ b/usecases/exec-strategy-field-notes.md @@ -8,11 +8,15 @@ freshness: ok > **本文定位：Field Notes（實戰踩坑記錄）** > -> 這篇文件是一份第一手實踐記錄——在 `docs/howto/exec-strategy-patterns.md` 存在之前，我們先踩坑、排查、跑通，事後發現實踐結論與 howto 框架高度吻合。 +> ⚠️ **先讀哪份？** +> - **想了解三種策略的概念、決策邏輯、完整 config 參考** → 請先看 [`docs/howto/exec-strategy-patterns.md`](../docs/howto/exec-strategy-patterns.md)（canonical howto） +> - **已看過 howto，正在排查 `approval-timeout` / `allowlist miss` 的具體問題** → 你在對的地方，繼續往下 > -> 如果你想了解三種策略的概念與決策邏輯，請先看 [`docs/howto/exec-strategy-patterns.md`](../docs/howto/exec-strategy-patterns.md)。 -> -> 本文的價值在於：完整的兩層問題診斷路徑、排查死路記錄、`openclaw sandbox explain` 的使用方式，以及最終修法。適合在出現 `approval-timeout` 或 `allowlist miss` 時對照參考。 +> 這篇文件是一份**第一手實踐記錄**，不是 howto 的摘要或替代品。時序上：我們先踩坑、排查、跑通，事後發現結論與 howto 框架高度吻合。本文的獨特價值在於： +> - 兩層問題診斷模型的完整推導路徑 +> - 排查死路記錄（哪些方向走不通、為什麼） +> - `openclaw sandbox explain` 的實際使用方式 +> - 最終修法的完整 config **對應版本：** OpenClaw ≥ 2026.4.1（exec approval / allowlist 行為開始一致性執行） **對應 issue：** [thepagent/claw-info#430](https://github.com/thepagent/claw-info/issues/430) @@ -44,7 +48,8 @@ Exec denied (gateway id=..., approval-timeout) ``` Layer 1：exec-approvals.json → 這個命令是否在 allowlist 內？ - → allowlist miss 時，fallback 是 deny / ask / allow？ + → allowlist miss 時，askFallback 決定行為：deny / ask / allow / full + （完整 enum 定義見 docs/howto/exec-strategy-patterns.md） Layer 2：審批轉發通道（approval channel） → 需要審批時，審批請求能不能送到你的對話介面？ @@ -82,6 +87,7 @@ Layer 2：審批轉發通道（approval channel） ``` 行為：allowlist 外的命令一律 deny，不彈審批，不放行。 +*（實測：OpenClaw 2026.4.1，Debian VPS；allowlist miss 返回 `Exec denied (approval-timeout)`，無審批對話框出現）* **優點：** 安全邊界清晰，blast radius 最小。 **代價：** 頻繁出現 `allowlist miss`，需持續維護白名單。 @@ -110,8 +116,9 @@ Layer 2：審批轉發通道（approval channel） ``` 行為：wildcard allowlist + miss 時直接放行，不彈審批。 +*（實測：OpenClaw 2026.4.1，Debian VPS；`askFallback: "allow"` 配合 wildcard pattern，任何命令直接執行，不經審批）* **優點：** 零摩擦，agent 可自由執行任何命令。 -**⚠️ 注意：** 任何能觸發 agent 的人都能間接執行任意命令。**僅限可信封閉環境使用，不適合面向多人的 Discord / 公開 Telegram bot。** +**⚠️ 前提：** 僅適合個人 VPS / 開發機等完全可信的封閉環境；此設定本身不作任何安全過濾。 ---