From 22c44dfdcf166dfbad21036bc5b8d77a8610127a Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Thu, 12 Mar 2026 21:42:21 +0800 Subject: [PATCH 1/5] usecases: approval-first workflow for personal OpenClaw agents --- usecases/approval-first-workflow.md | 226 ++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 usecases/approval-first-workflow.md diff --git a/usecases/approval-first-workflow.md b/usecases/approval-first-workflow.md new file mode 100644 index 0000000..e14f4eb --- /dev/null +++ b/usecases/approval-first-workflow.md @@ -0,0 +1,226 @@ +# Approval-First Workflow：個人 Agent 的審批優先設計 + +> 讓 agent 自主讀、分析、起草，但在任何改變狀態的操作前先取得人類許可。 + +--- + +## TL;DR + +- **核心原則**：read freely, change only with approval +- **問題根源**：agent 太自主 → 做了難回頭的事；太被動 → 每步都問，用起來痛苦 +- **解法**：在 `AGENTS.md` 明確劃定邊界，state-changing 操作插審批閘門 +- **執行工具**：`openfeedback`——自動化腳本暫停、發 Telegram 請示、exit code 決定繼續或中止 +- **關鍵設計**：審批訊息要帶足夠的上下文，不是「繼續？」而是「做什麼、影響什麼、有沒有退路」 + +--- + +## 兩個失敗極端 + +``` +太自主 太被動 + │ │ + ▼ ▼ +agent 自行 push commit agent 每次讀檔案 +agent 自行發 Telegram 訊息 都要問「可以嗎？」 +agent 自行刪改 memory 檔案 + │ │ + ▼ ▼ +出錯難撤銷 體驗極差，棄用 +``` + +approval-first 是中間路徑：agent 在安全範圍內自主運作，在邊界處停下來問。 + +--- + +## 邊界劃定：哪些可以自主，哪些需要審批 + +### ✅ 無需審批（read-only / 低風險） + +- 讀取本地檔案、workspace 內容 +- 分析、摘要、翻譯、起草文字 +- 搜尋網路、查詢文件 +- 讀取 GitHub issues / PR（不寫入） +- 查看 calendar、通知（不回覆） + +### 🔐 需要審批（state-changing） + +| 類別 | 操作範例 | +|------|---------| +| 檔案系統 | 新增 / 修改 / 刪除檔案，寫入 memory | +| Shell 指令 | 任何有副作用的指令（deploy、rm、push）| +| Git / GitHub | commit、push、開 PR、留 issue 留言 | +| 外部訊息 | 發 Telegram / Email / 任何對外發送 | +| 排程 | 新增 / 修改 cron 任務 | +| 設定 / 憑證 | 改 config、secrets、API keys | + +--- + +## 在 AGENTS.md 中表達這個 Policy + +在 `AGENTS.md` 的 Safety 區塊加入明確邊界： + +```markdown +## Safety + +**可自主執行：** +- 讀取檔案、搜尋、分析、起草 + +**必須先取得許可：** +- 任何寫入操作（檔案、memory、git） +- 任何對外發送（訊息、API 呼叫） +- 任何排程變更 + +遇到邊界操作：暫停、說明意圖、等待確認後再執行。 +``` + +--- + +## 執行層：接入 openfeedback + +[openfeedback](https://github.com/antx-code/openfeedback) 是一個 CLI 工具，讓自動化腳本在執行前發 Telegram 審批請求，根據 exit code 決定繼續（0）或中止（1）。 + +### 工作流程 + +``` +agent / 自動化腳本 + │ + │ 抵達 state-changing 操作 + ▼ +┌───────────────────────────────┐ +│ openfeedback "操作說明" │ +│ → 發 Telegram 審批訊息 │ +│ → 等待回應（預設 60 秒） │ +└──────────┬────────────────────┘ + │ + ┌──────┴──────┐ + ▼ ▼ + 核准 拒絕 / 超時 + exit 0 exit 1 + │ │ + ▼ ▼ +繼續執行 中止操作 +``` + +### 在 cron payload 中使用 + +```bash +# cron isolated session 的執行腳本片段 +# 分析完成後，準備寫入 memory——先審批 + +openfeedback "Agent 準備更新 memory/2026-03-10.md +內容：今日市場分析摘要（約 500 字） +影響：覆蓋既有當日記錄 +是否核准？" && \ + write_memory_file +``` + +### 在 coding agent 流程中使用 + +```bash +# agent 完成實作後，準備開 PR + +openfeedback "Coding agent 準備開 PR +標題：${PR_TITLE} +分支：${BRANCH} +變更：${CHANGED_FILES} 個檔案 +Repo：${REPO} +是否核准？" && \ + gh pr create --title "${PR_TITLE}" --body "${PR_BODY}" +``` + +### 審批訊息的關鍵原則 + +``` +# ❌ 沒用——不知道在問什麼 +openfeedback "繼續？" + +# ✅ 有用——做什麼、影響什麼、有無退路 +openfeedback "準備 git push origin main +包含 3 個 commit，最後一個是 feat: 新增付款流程 +此操作 push 後需另開 PR 才能撤銷 +是否核准？" +``` + +### 設定要點 + +```toml +# ~/.config/openfeedback/config.toml +bot_token = "" +chat_id = +trusted_user_ids = [] # 只允許你自己審批 +default_timeout = 60 # 超時視為拒絕（安全預設） +``` + +詳細安裝請見 [openfeedback README](https://github.com/antx-code/openfeedback)。 + +--- + +## 在 cron payload 中表達 approval-first + +isolated session 不繼承 `AGENTS.md`，必須在 payload 裡顯式說明邊界： + +``` +你是一個財務分析 agent。 + +可自主執行： +- 讀取 workspace 內的 market-data/ 檔案 +- 分析數據、生成摘要 + +需要審批（使用 openfeedback）： +- 寫入任何檔案 +- 發送任何外部訊息 + +完成分析後，用 openfeedback 請示是否將摘要寫入 memory/today.md。 +``` + +--- + +## 取捨設計 + +| 場景 | 建議策略 | +|------|---------| +| 完全自動化的低風險任務（純讀取、分析） | 無需審批，讓 agent 自主跑 | +| 有寫入但影響可逆（如更新 memory） | 審批一次，批准後自動執行 | +| 高風險不可逆（push、deploy、發訊息） | 每次都審批，不設豁免 | +| 批次操作（10 個檔案逐一確認） | 審批整個計劃，不逐項問 | +| 無人值守 cron（深夜跑） | 純讀取任務不插審批；寫入任務改在有人值守時段執行 | + +--- + +## Anti-patterns + +**在無人值守 cron 裡插審批** + +深夜的 cron 任務要寫入 memory，發了 Telegram 沒人看——60 秒後超時、任務中止、隔天才發現。解法：分離任務，純分析放無人值守，需審批的操作排在清醒時段。 + +**審批粒度太細** + +agent 每寫一行都問一次，體驗比沒有 agent 更差。審批應該在「計劃」層級，不是「操作」層級。 + +**AGENTS.md 寫了邊界但 cron payload 沒寫** + +isolated session 不讀 AGENTS.md。邊界 policy 必須在 payload 裡重複說明。 + +--- + +## Troubleshooting + +**症狀**：openfeedback 發出訊息但沒有收到 +- 確認 bot 已對話過（先對 bot 發 `/start`） +- 確認 `chat_id` 正確 + +**症狀**：cron 任務因審批超時而中止 +- 檢查任務是否在無人值守時段執行 +- 調整 `--timeout` 或改在有人值守時段排程 + +**症狀**：agent 跳過審批直接執行 +- isolated session 的 payload 沒有說明邊界——補上 approval-first 指示 + +--- + +## 相關連結 + +- `docs/cron.md`：OpenClaw Cron 系統 +- `usecases/cron-automated-workflows.md`：自動化工作流設計 +- `usecases/context-overflow-prevention.md`：agent session 防護 +- Issue #297：本文件的提案來源 From 7132b491b04a922a59daccbd0694c9171484af86 Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Thu, 12 Mar 2026 21:42:21 +0800 Subject: [PATCH 2/5] =?UTF-8?q?fix:=20=E4=BF=AE=E6=AD=A3=E5=81=87=E6=8C=87?= =?UTF-8?q?=E4=BB=A4=E3=80=81=E7=A7=BB=E9=99=A4=E6=87=B8=E7=A9=BA=E5=BC=95?= =?UTF-8?q?=E7=94=A8=E3=80=81=E5=90=88=E4=BD=B5=E9=87=8D=E8=A4=87=20cron?= =?UTF-8?q?=20payload=20=E7=AB=A0=E7=AF=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- usecases/approval-first-workflow.md | 43 +++++++++++------------------ 1 file changed, 16 insertions(+), 27 deletions(-) diff --git a/usecases/approval-first-workflow.md b/usecases/approval-first-workflow.md index e14f4eb..ba38766 100644 --- a/usecases/approval-first-workflow.md +++ b/usecases/approval-first-workflow.md @@ -103,15 +103,25 @@ agent / 自動化腳本 ### 在 cron payload 中使用 -```bash -# cron isolated session 的執行腳本片段 -# 分析完成後，準備寫入 memory——先審批 +isolated session 不繼承 `AGENTS.md`，必須在 payload 裡顯式說明邊界，再搭配 openfeedback 作為執行閘門： + +``` +# cron payload 範例（財務分析 agent） +你是一個財務分析 agent。 + +可自主執行： +- 讀取 workspace 內的 market-data/ 檔案 +- 分析數據、生成摘要 -openfeedback "Agent 準備更新 memory/2026-03-10.md +需要審批（使用 openfeedback）： +- 寫入任何檔案 +- 發送任何外部訊息 + +完成分析後，執行以下指令請示是否寫入 memory： +openfeedback "Agent 準備更新 memory/today.md 內容：今日市場分析摘要（約 500 字） 影響：覆蓋既有當日記錄 -是否核准？" && \ - write_memory_file +是否核准？" && echo "${SUMMARY}" >> memory/today.md ``` ### 在 coding agent 流程中使用 @@ -155,26 +165,6 @@ default_timeout = 60 # 超時視為拒絕（安全預設） --- -## 在 cron payload 中表達 approval-first - -isolated session 不繼承 `AGENTS.md`，必須在 payload 裡顯式說明邊界： - -``` -你是一個財務分析 agent。 - -可自主執行： -- 讀取 workspace 內的 market-data/ 檔案 -- 分析數據、生成摘要 - -需要審批（使用 openfeedback）： -- 寫入任何檔案 -- 發送任何外部訊息 - -完成分析後，用 openfeedback 請示是否將摘要寫入 memory/today.md。 -``` - ---- - ## 取捨設計 | 場景 | 建議策略 | @@ -222,5 +212,4 @@ isolated session 不讀 AGENTS.md。邊界 policy 必須在 payload 裡重複說 - `docs/cron.md`：OpenClaw Cron 系統 - `usecases/cron-automated-workflows.md`：自動化工作流設計 -- `usecases/context-overflow-prevention.md`：agent session 防護 - Issue #297：本文件的提案來源 From 84df4e9a03161ef89f3be294d547dc4e86a94e1b Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Thu, 12 Mar 2026 21:42:21 +0800 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20=E8=A3=9C=E5=85=85=20openfeedback?= =?UTF-8?q?=20timeout=20=E9=85=8D=E7=BD=AE=E8=AA=AA=E6=98=8E=EF=BC=88?= =?UTF-8?q?=E6=9C=AC=E5=9C=B0=E7=89=88=20vs=20upstream=20=E5=8D=80?= =?UTF-8?q?=E5=88=86=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- usecases/approval-first-workflow.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/usecases/approval-first-workflow.md b/usecases/approval-first-workflow.md index ba38766..332ce2d 100644 --- a/usecases/approval-first-workflow.md +++ b/usecases/approval-first-workflow.md @@ -161,6 +161,18 @@ trusted_user_ids = [] # 只允許你自己審批 default_timeout = 60 # 超時視為拒絕（安全預設） ``` +> **Timeout 配置說明** +> +> `default_timeout` 是本地自訂版本的配置項。若使用 upstream 版本（`cargo install --git ...`），目前主審批流程的 timeout 無法透過 config 直接設定，建議在腳本層控制： +> +> ```bash +> # 對不可逆操作，透過 --timeout 延長等待時間（若 CLI 支援） +> # 或將任務排在有人值守時段，避免因超時導致中止 +> openfeedback --timeout 300 "準備 git push origin main ..." +> ``` +> +> v0.2.0 新增的 `reject_feedback_timeout` 是「拒絕後等待理由」的時間窗，與主審批 timeout 是不同的配置。 + 詳細安裝請見 [openfeedback README](https://github.com/antx-code/openfeedback)。 --- From 2c889ced5e43c079b69b89946d97b0340577a052 Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Fri, 13 Mar 2026 07:46:51 +0800 Subject: [PATCH 4/5] =?UTF-8?q?refactor:=20=E9=87=8D=E6=A7=8B=E7=82=BA=20H?= =?UTF-8?q?ITL=20=E6=A9=9F=E5=88=B6=E8=AA=AA=E6=98=8E=20+=20openfeedback?= =?UTF-8?q?=20=E7=A4=BA=E4=BE=8B=EF=BC=8C=E4=BF=AE=E6=AD=A3=E6=8C=87?= =?UTF-8?q?=E4=BB=A4=E6=A0=BC=E5=BC=8F=EF=BC=8C=E7=B2=BE=E7=B0=A1=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E7=B4=B0=E7=AF=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- usecases/approval-first-workflow.md | 112 +++++++++++++--------------- 1 file changed, 53 insertions(+), 59 deletions(-) diff --git a/usecases/approval-first-workflow.md b/usecases/approval-first-workflow.md index 332ce2d..257b610 100644 --- a/usecases/approval-first-workflow.md +++ b/usecases/approval-first-workflow.md @@ -1,4 +1,4 @@ -# Approval-First Workflow：個人 Agent 的審批優先設計 +# Approval-First Workflow — Human-in-the-Loop 審批閘門設計 > 讓 agent 自主讀、分析、起草，但在任何改變狀態的操作前先取得人類許可。 @@ -9,11 +9,40 @@ - **核心原則**：read freely, change only with approval - **問題根源**：agent 太自主 → 做了難回頭的事；太被動 → 每步都問，用起來痛苦 - **解法**：在 `AGENTS.md` 明確劃定邊界，state-changing 操作插審批閘門 -- **執行工具**：`openfeedback`——自動化腳本暫停、發 Telegram 請示、exit code 決定繼續或中止 +- **執行層**：需要一個「暫停 → 請示 → 繼續/中止」的閘門機制；本文以 `openfeedback` 為例示範落地方式 - **關鍵設計**：審批訊息要帶足夠的上下文，不是「繼續？」而是「做什麼、影響什麼、有沒有退路」 --- +## 什麼是 Human-in-the-Loop + +Human-in-the-Loop（HITL）是一種設計模式：在自動化流程的關鍵節點，主動插入人類判斷，而不是讓系統一路跑到底。 + +``` +全自動 Human-in-the-Loop 全手動 + │ │ │ + ▼ ▼ ▼ +agent 自主決定 agent 自主跑安全操作 每步都問人 +不中斷執行 在邊界處暫停等人確認 效率極低 + │ │ │ + ▼ ▼ ▼ +出錯難撤銷 效率與安全兼顧 棄用 +``` + +對 AI Agent 來說，HITL 解決的核心矛盾是： + +- **自主性帶來效率**，但也帶來「做了難回頭的事」的風險 +- **人類監督帶來安全**，但介入太細會讓 agent 失去價值 + +HITL 的答案是：**讓 agent 在安全邊界內全速跑，只在邊界處停下來問一次。** + +三個核心要素： +1. **明確的邊界**：哪些操作可自主，哪些需審批——寫死在 AGENTS.md 或 payload 裡 +2. **可見的閘門**：邊界操作前發出審批請求，帶足夠上下文（做什麼、影響什麼、有無退路） +3. **清晰的語義**：批准 → 繼續執行；拒絕/超時 → 中止，不做任何假設 + +--- + ## 兩個失敗極端 ``` @@ -75,9 +104,14 @@ approval-first 是中間路徑：agent 在安全範圍內自主運作，在邊 --- -## 執行層：接入 openfeedback +## 執行層示例：以 openfeedback 為例 + +審批閘門的實作方式不只一種，核心需求是： +1. 操作前發送可見的審批請求 +2. 等待人類回應 +3. 根據回應決定繼續（exit 0）或中止（exit 1） -[openfeedback](https://github.com/antx-code/openfeedback) 是一個 CLI 工具，讓自動化腳本在執行前發 Telegram 審批請求，根據 exit code 決定繼續（0）或中止（1）。 +以下以 [openfeedback](https://github.com/antx-code/openfeedback) CLI 為例示範一種落地方式。你也可以用自定義腳本、webhook、或其他具備相同語義的工具替代。 ### 工作流程 @@ -87,7 +121,8 @@ agent / 自動化腳本 │ 抵達 state-changing 操作 ▼ ┌───────────────────────────────┐ -│ openfeedback "操作說明" │ +│ openfeedback send --title │ +│ "操作說明" │ │ → 發 Telegram 審批訊息 │ │ → 等待回應（預設 60 秒） │ └──────────┬────────────────────┘ @@ -101,57 +136,28 @@ agent / 自動化腳本 繼續執行 中止操作 ``` -### 在 cron payload 中使用 - -isolated session 不繼承 `AGENTS.md`，必須在 payload 裡顯式說明邊界，再搭配 openfeedback 作為執行閘門： - -``` -# cron payload 範例（財務分析 agent） -你是一個財務分析 agent。 - -可自主執行： -- 讀取 workspace 內的 market-data/ 檔案 -- 分析數據、生成摘要 - -需要審批（使用 openfeedback）： -- 寫入任何檔案 -- 發送任何外部訊息 - -完成分析後，執行以下指令請示是否寫入 memory： -openfeedback "Agent 準備更新 memory/today.md -內容：今日市場分析摘要（約 500 字） -影響：覆蓋既有當日記錄 -是否核准？" && echo "${SUMMARY}" >> memory/today.md -``` - -### 在 coding agent 流程中使用 +### 最小可用範例 ```bash -# agent 完成實作後，準備開 PR - -openfeedback "Coding agent 準備開 PR -標題：${PR_TITLE} -分支：${BRANCH} -變更：${CHANGED_FILES} 個檔案 -Repo：${REPO} -是否核准？" && \ - gh pr create --title "${PR_TITLE}" --body "${PR_BODY}" +openfeedback send \ + --title "準備 git push origin main" \ + --body "包含 3 個 commit，最後一個是 feat: 新增付款流程。push 後需另開 PR 才能撤銷。" \ + && git push origin main ``` ### 審批訊息的關鍵原則 -``` +```bash # ❌ 沒用——不知道在問什麼 -openfeedback "繼續？" +openfeedback send --title "繼續？" # ✅ 有用——做什麼、影響什麼、有無退路 -openfeedback "準備 git push origin main -包含 3 個 commit，最後一個是 feat: 新增付款流程 -此操作 push 後需另開 PR 才能撤銷 -是否核准？" +openfeedback send \ + --title "準備 git push origin main" \ + --body "包含 3 個 commit，最後一個是 feat: 新增付款流程。此操作 push 後需另開 PR 才能撤銷。" ``` -### 設定要點 +### 基本設定 ```toml # ~/.config/openfeedback/config.toml @@ -161,18 +167,6 @@ trusted_user_ids = [] # 只允許你自己審批 default_timeout = 60 # 超時視為拒絕（安全預設） ``` -> **Timeout 配置說明** -> -> `default_timeout` 是本地自訂版本的配置項。若使用 upstream 版本（`cargo install --git ...`），目前主審批流程的 timeout 無法透過 config 直接設定，建議在腳本層控制： -> -> ```bash -> # 對不可逆操作，透過 --timeout 延長等待時間（若 CLI 支援） -> # 或將任務排在有人值守時段，避免因超時導致中止 -> openfeedback --timeout 300 "準備 git push origin main ..." -> ``` -> -> v0.2.0 新增的 `reject_feedback_timeout` 是「拒絕後等待理由」的時間窗，與主審批 timeout 是不同的配置。 - 詳細安裝請見 [openfeedback README](https://github.com/antx-code/openfeedback)。 --- @@ -207,13 +201,13 @@ isolated session 不讀 AGENTS.md。邊界 policy 必須在 payload 裡重複說 ## Troubleshooting -**症狀**：openfeedback 發出訊息但沒有收到 +**症狀**：審批請求發出但沒有收到 - 確認 bot 已對話過（先對 bot 發 `/start`） - 確認 `chat_id` 正確 **症狀**：cron 任務因審批超時而中止 - 檢查任務是否在無人值守時段執行 -- 調整 `--timeout` 或改在有人值守時段排程 +- 將需審批的操作改排在有人值守時段 **症狀**：agent 跳過審批直接執行 - isolated session 的 payload 沒有說明邊界——補上 approval-first 指示 From a81953fbe2accd500c4131458fb9f8d5f5ebf442 Mon Sep 17 00:00:00 2001 From: wangyuyan-agent Date: Sat, 14 Mar 2026 22:16:50 +0800 Subject: [PATCH 5/5] =?UTF-8?q?fix:=20=E5=8A=A0=E5=BC=B7=20isolated=20sess?= =?UTF-8?q?ion=20AGENTS.md=20=E9=99=B7=E9=98=B1=E8=A6=96=E8=A6=BA=E6=8F=90?= =?UTF-8?q?=E7=A4=BA=EF=BC=88blockquote=20+=20=E5=8A=A0=E7=B2=97=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- usecases/approval-first-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usecases/approval-first-workflow.md b/usecases/approval-first-workflow.md index 257b610..6367e25 100644 --- a/usecases/approval-first-workflow.md +++ b/usecases/approval-first-workflow.md @@ -195,7 +195,7 @@ agent 每寫一行都問一次，體驗比沒有 agent 更差。審批應該在 **AGENTS.md 寫了邊界但 cron payload 沒寫** -isolated session 不讀 AGENTS.md。邊界 policy 必須在 payload 裡重複說明。 +> ⚠️ **isolated session 不讀 `AGENTS.md`。邊界 policy 必須在 payload 裡顯式重複說明。** 忘記這一點，審批閘門在 isolated session 裡形同虛設。 ---