OpenClaw WORKSPACE_GOVERNANCE

OpenClaw agent 即時回應指令。沒有治理：寫入在讀取前發生，版本問題靠訓練資料作答，出錯後無記錄可查。 WORKSPACE_GOVERNANCE 補上原廠設定欠缺的治理層：寫入前需有計劃及讀取佐證，每次變更產生可追溯的 run report，cron 和 heartbeat 執行中治理規則同樣有效。

English Version

OpenClaw 版本相容性： 針對 OpenClaw v2026.3.7+ 最佳化（完整支援 prependSystemContext 常駐錨點、sessionId 閘門隔離、trigger 偵測）。可向下相容舊版本——治理 hook 仍會觸發，但無條件觸發的系統提示錨點需要 v2026.3.7+ 才能生效。

ClawHub 安裝頁：

• https://clawhub.ai/Adamchanadam/openclaw-workspace-governance-installer

🎬 影片介紹

2 分鐘概覽。

▶️ 觀看：Discipline Master for OpenClaw（Workspace Governance Plugin）

📋 Release Notes 最新 3 版重點報告板

| 版本 | 發佈時間（UTC） | 關鍵變更 | 對使用者的直接影響 | | --- | --- | --- | --- | | v0.2.9 | 2026-03-21 | 治理流程圖修正：PNG 圖表改為 SVG 版本；Brain Docs 閘門邏輯圖從「建議×2 然後封鎖」修正為正確的三步序列（第1次 = 軟封鎖並顯示 PLAN+READ 提醒，第2次 = 放行，第3次起 = 硬封鎖）。SVG 檔案現已包含於 npm 套件中。另補充 2 個回歸測試（C217–C218，共 216→218）。 | 流程圖現已準確反映 v0.2.8 風險分層閘門行為。SVG 格式在任何解析度下均清晰。圖片現可在 npm 套件頁面正常顯示。 | | v0.2.8 | 2026-03-20 | RC-1/RC-3 閘門修復 + 反饋循環完整性：cronIntentUser 改為只看當前回合（不再受舊對話記錄污染）；第一次高風險寫入顯示 PLAN+READ 提醒（軟攔截），第二次放行，第三次起硬攔截。gov_brain_audit 新增 GUARDS_NOT_IN_READ_GATE 規則（medium 嚴重度）：_control/ACTIVE_GUARDS.md 存在時，run report 的 FILES_READ 必須包含它。AGENTS_CORE_v1 明確要求寫入前讀取 _control/ACTIVE_GUARDS.md 及 _control/LESSONS.md。5 個新回歸測試（C212–C216，共 211→216）。 | 治理寫入保護不再被舊對話記錄誤觸。首次高風險寫入改為顯示可見的計劃+讀取提醒。gov_brain_audit 主動偵測跳過 ACTIVE_GUARDS.md 讀取的 governance 任務。執行 /gov_migrate 後，所有用戶的 AGENTS.md 自動獲得更新後的 READ GATE 規則。 | | v0.2.7 | 2026-03-17 | 靜默回合媒體消息污染修復：quietTurnFirstTime 改為只注入被動背景指令——不再與用戶當前任務競爭。新增媒體回合偵測：session 首條消息為圖片／影片／音訊時，靜默回合推遲至下一個非媒體回合觸發。防止治理指令污染感知任務結果。2 個新回歸測試（C210–C211，共 209→211）。 | 以媒體消息開始的 session 不再將治理指令混入媒體描述。這是 agent 層修復，與渠道無關——WhatsApp、Telegram、TUI、Web 等均受惠。 |

來源：GitHub Releases（Adamchanadam/OpenClaw-WORKSPACE-GOVERNANCE）

🆙 v0.2.0 升級一圖覽

為何今次升級重要——一圖說清楚。

升級原因：逃逸漏洞問題 + v0.2.0 修復方案

升級方法：相容矩陣 + 三步執行指令

🎯 Hero

每天用 OpenClaw，最大風險是操作漂移：難以快速知道改了什麼、下一步跑什麼、升級是否安全。WORKSPACE_GOVERNANCE 把這種不確定性變成可重覆的流程。

Install | Quick Start

💡 Why This Matters

沒有治理：

1. 還未核實就先改檔——錯誤在被發現前已擴散。
2. plugin 更新後，不知道下一步跑什麼、更新是否完整。
3. 出事後，無記錄可查改了什麼、怎麼回退。
4. 交接時，接手人不知道哪些做過、哪些通過了、哪些待處理。

裝了這個 plugin：

1. 寫入走 PLAN→READ→CHANGE→QC→PERSIST。
2. /gov_setup quick 一步跑完 check、install/upgrade、migrate、audit。
3. 平台設定改動含備份、驗證與回退。
4. 每次變更有 run report，交接和 audit 有依據可查。

✅ 功能成熟度（不誤導聲明）

GA：

1. /gov_help — 一次列出全部指令與建議入口
2. /gov_setup quick|check|install|upgrade — 一步完成治理部署、升級或驗證
3. /gov_migrate — install 或 upgrade 後，將工作區行為對齊最新治理規則
4. /gov_audit — 驗證 12 項完整性核對，在宣稱完成前捕捉漂移
5. /gov_uninstall quick|check|uninstall — 安全清理，含備份與回復證據
6. /gov_openclaw_json — 安全編輯平台設定（openclaw.json），含備份、驗證與回退
7. /gov_brain_audit — 預覽優先、批准後套用、可回退的 Brain Docs 品質修補
8. /gov_boot_audit — 掃描重覆問題並生成升級提案（只讀診斷）

Experimental（實驗性）：

1. /gov_apply <NN> — 以人工明確批准的方式套用單一 BOOT 升級提案（僅限受控測試，已納入自動化回歸驗證）。
2. 套用後，務必以 /gov_migrate 與 /gov_audit 收尾。

✅ 已驗證場景

自動化回歸測試套件，覆蓋完整操作員生命周期，每次發佈前均通過驗收：

| 場景 | 驗收內容 | |---|---| | 工作區安裝與升級 | 全新安裝、從舊版升級、版本偵測、已是最新版時自動略過 | | 內容保護 | 現有 Brain Docs、openclaw.json 及自訂規則在安裝／升級期間受到保護 | | 遷移準確性 | 所有治理規則與標記正確套用；衝突與部分狀態均能偵測並回報 | | 審核完整性 | 所有 12 項完整性核對均執行；漂移、缺失標記及設定不符均能捕捉 | | 安全設定編輯 | openclaw.json 編輯流程：備份 → 驗證 → 套用 → 確認；無效編輯拒絕並回退 | | Brain Docs 保護 | 對 Brain Docs（AGENTS.md、SOUL.md 等）的高風險寫入，寫前提示警告；可按需回退 | | 故障恢復 | 設定損毀、備份失敗、遷移中斷均設有容錯處理機制 | | 完整操作員生命周期 | 端到端：安裝 → 遷移 → 審核 → 編輯 → 重新審核 → 卸載並留存清理證據 |

🖼️ Visual Walkthrough（ref_doc）

🚀 60-Second Start

最快入口（建議）

在 OpenClaw TUI 直接輸入：

/gov_setup quick

/gov_setup quick 會自動跑： check -> (install|upgrade|skip) -> migrate -> audit 若中途受阻，會直接告知下一步指令。

共用 Allowlist 快速修復

只在出現 Error: not in allowlist 時使用。

openclaw config get plugins.allow
openclaw configure
# 在 plugins.allow 追加 openclaw-workspace-governance，並保留所有原有 trusted IDs。
openclaw plugins enable openclaw-workspace-governance
openclaw gateway restart

編輯 allowlist 陣列時，請保留你原有的 trusted IDs。

新裝路徑（可直接照抄）

1. 主機終端先執行：

openclaw plugins install @adamchanadam/openclaw-workspace-governance@latest
openclaw gateway restart

2. 信任模型檢查（必要）： 部分 OpenClaw 版本在 install 時，不會自動把新 plugin 加入 plugins.allow。 如果 openclaw plugins info openclaw-workspace-governance 顯示 Error: not in allowlist，請先執行上面的「共用 Allowlist 快速修復」。
3. OpenClaw TUI 對話中執行：

/gov_setup quick

4. 若回覆顯示信任清單未就緒（例如出現 plugins.allow is empty，或提示要先對齊 openclaw.json），執行：

/gov_openclaw_json
/gov_setup quick

已安裝升級路徑（可直接照抄）

1. 主機終端先執行：

openclaw plugins update openclaw-workspace-governance
openclaw gateway restart

2. 若 plugin 顯示 Error: not in allowlist，請先執行上面的「共用 Allowlist 快速修復」。
3. OpenClaw TUI 對話中執行：

/gov_setup quick

4. 若回覆顯示信任清單未就緒，執行：

/gov_openclaw_json
/gov_setup quick

正式清理卸載路徑（可直接照抄）

不要先刪 plugin 套件，請先做 workspace 清理。

1. 先確保 plugin 已允許且可載入（否則 /gov_uninstall 無法執行）：

openclaw plugins info openclaw-workspace-governance

若顯示 Error: not in allowlist，先執行上面的「共用 Allowlist 快速修復」。 2. 在 OpenClaw TUI 對話中執行：

/gov_uninstall quick
# 如需嚴格驗證可再跑：
/gov_uninstall check

預期結果：

• quick：PASS 或 CLEAN
• 如有再跑 check：應為 CLEAN

3. 然後再移除 plugin 套件：

openclaw plugins disable openclaw-workspace-governance
openclaw plugins uninstall openclaw-workspace-governance
openclaw gateway restart

卸載 runner 會先備份到 archive/_gov_uninstall_backup_<ts>/...，並寫出 run report：_runs/gov_uninstall_<ts>.md。 如存在 Brain Docs autofix 備份（archive/_brain_docs_autofix_<ts>/...），/gov_uninstall 會輸出並執行對應回復策略（含證據欄位）。

若你已經先卸載 plugin 套件：

1. 先重裝 plugin（令 /gov_uninstall 可用）
2. 跑 /gov_uninstall check -> /gov_uninstall uninstall -> /gov_uninstall check
3. 需要時再停用/卸載 plugin 套件

🧭 Command Chooser（指令選擇器）

| 目標 | 先執行 | 再執行 | 說明 | | --- | --- | --- | --- | | 列出全部治理指令 | /gov_help | 再選 quick 或手動流程 | 不用先讀文檔，直接看指令列表 | | 一鍵完成治理部署/升級/稽核 | /gov_setup quick | 若 blocked 才跟下一步指示 | 自動串 check/install-or-upgrade/migrate/audit | | 改動前先確認正確路徑（手動） | /gov_setup check | 依回覆下一步執行 | 輸出明確下一步，避免走錯 install/upgrade 分支 | | 首次部署治理到工作區 | /gov_setup install | /gov_migrate -> /gov_audit | 部署治理套件檔，再由 migration 補齊缺失的 _control 基線檔 | | 升級既有治理工作區 | /gov_setup upgrade | /gov_migrate -> /gov_audit | 同步治理檔版本與策略，變更後完成驗證 | | 一鍵清理 workspace 治理殘留 | /gov_uninstall quick | 可選再跑 /gov_uninstall check | 完成清理，保留備份/回復證據 | | 先清除平台信任警告再進治理流程 | /gov_openclaw_json | /gov_setup check | 先修信任問題，避免 setup 流程因此失敗 | | 安全修改 OpenClaw 平台控制面 | /gov_openclaw_json | /gov_audit | openclaw.json 的備份/驗證/回退流程 | | 低風險優化 Brain Docs 品質 | /gov_brain_audit | 批准 findings -> /gov_audit | 檢出高風險語句，批准後套用，可回退 | | 重複被治理閘門封鎖時清除所有閘門 | /gov_brain_audit force-accept | 繼續你的任務 | 被閘門封鎖時清除所有閘門，留稽核記錄 | | 掃描重覆問題並取得升級提案 | /gov_boot_audit | 審閱提案 -> /gov_apply <NN>（Experimental） | 只讀掃描，生成編號提案供審閱後決定是否套用 | | 套用單一 BOOT 提案項目（Experimental） | /gov_apply <NN> | /gov_migrate -> /gov_audit | 只執行單一人手批准項目，受控 UAT 用途 |

🧠 核心能力：/gov_brain_audit 如何優化 Brain Docs 效能

/gov_brain_audit 不只是文字檢查，還讓 Brain Docs 更一致、可驗證、較少自我矛盾。

效果：

1. 剔除「先行動後核實」語句，減低寫入失穩風險。
2. 剔除「無證據過度肯定」語句，減少假完成回覆。
3. 對齊 Brain Docs 與 run-report 的證據要求。
4. 以最小改動修補，保留原有 persona 方向。

重要說明： F001、F003 等是當次 preview 產生的動態 finding ID。 它們只是示例，不是固定代碼。請以最新 preview 輸出的 IDs 為準。

執行模式：

/gov_brain_audit
/gov_brain_audit APPROVE: <PASTE_IDS_FROM_PREVIEW>
/gov_brain_audit ROLLBACK

⚙️ 治理如何處理你的請求

治理如何分類請求：

1. 提問與規劃——不改檔案。 策略、說明、規劃：AI 只給建議，不動檔案。

2. 需要可驗證的回答——不改檔案。 版本、狀態、日期：AI 先查官方來源再作答。

3. 改動檔案——完整治理。 寫入、更新、儲存：AI 走 PLAN→READ→CHANGE→QC→PERSIST，寫出 run report。需要時以 /gov_migrate 與 /gov_audit 收尾。

治理流程總覽

⚡ Runtime Gate 行為（透明公開）

Runtime gate 運作方式：

寫入保護流程

| 步驟 | 發生什麼 | 用戶動作 | |------|----------|---------| | 一般寫入（skills/、projects/、代碼） | 透明 — 寫入正常執行（治理內部記錄，不會有任何提示） | 無需操作，寫入直接完成 | | 高風險寫入（治理基礎設施、Brain Docs）第 1-2 次 | 透明 — 寫入正常執行（內部記錄） | 無需操作——AI 在下一輪自動收到輔導回饋 | | 高風險寫入第 3 次以上無證據 | 硬封鎖 — 寫入被攔截 | AI 自動收到輔導回饋；你也可以說：「請包含你的計劃和已讀檔案」 | | 同一閘門連續封鎖 3 次以上 | 逃生提示自動出現在封鎖訊息中 | 使用 /gov_brain_audit force-accept 清除所有閘門（含稽核記錄） | | 執行 /gov_setup、/gov_migrate、/gov_audit 之後 | 建議性提示（非硬封鎖） | 可選擇性執行 /gov_brain_audit 做健康檢查預覽 |

風險分類

| 風險層級 | 目標 | Runtime 行為 | |---------|------|-------------| | 高風險 | Brain Docs（AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md、MEMORY.md、HEARTBEAT.md）、openclaw.json、_control/*、prompts/governance/* | 第 1-2 次透明（AI 下一輪收到輔導），第 3 次起硬封鎖 | | 一般 | 其他所有檔案（skills/、projects/、_runs/、原始碼、設定、文檔等） | 永遠透明（不會硬封鎖，治理內部記錄） |

所有寫入（無論風險層級）在內部都遵循完整的 Mode C 治理流程：PLAN→READ→CHANGE→QC→PERSIST。風險層級只決定 runtime gate 是否能硬封鎖寫入嘗試。

逃生艙

同一閘門被封鎖 3 次以上且無法繼續：

/gov_brain_audit force-accept

清除當前 session 的所有治理閘門。稽核記錄寫入 _runs/。治理保護降低，請謹慎。

治理指令自動繞過

治理寫入指令（/gov_setup install、/gov_migrate、/gov_apply 等）自動繞過寫入閘門 8 分鐘。執行治理指令時無需提供 PLAN/READ 證據。

系統指令讀寫分離

Cron 及 heartbeat 指令依讀/寫意圖分類：

| 指令 | 分類 | Mode C | |------|------|--------| | openclaw cron list/ls/show/status/run/runs | 唯讀 | 繞過（無治理閘門） | | openclaw cron add/update/remove/delete/pause/resume | 寫入 | 必須 — PLAN→READ→CHANGE→QC→PERSIST | | openclaw cron（裸指令，無子命令） | 唯讀 | 繞過 | | openclaw gateway heartbeat 配置變更 | 寫入 | 必須 |

修改排程任務前，請先閱讀官方文檔：https://docs.openclaw.ai/automation/cron-jobs 修改心跳配置前，請先閱讀官方文檔：https://docs.openclaw.ai/gateway/heartbeat

Brain Audit 時序

• 每輪重置：兩次指令間隔超過 30 秒時，blockedWrites 計數器重置
• 建議性回饋：無證據寫入後，AI 在下一輪收到輔導指引——無需用戶操作

Scanner 容錯度

如果治理掃描器因格式差異而拒絕 LLM 生成的 run reports，可在 openclaw.json 中設定 scannerTolerance：

| 設定值 | 行為 | |--------|------| | strict | 僅接受精確機器格式（如 files_read:） | | tolerant（預設） | 接受 markdown 標題、項目符號、格式變體 | | lenient | 模糊關鍵字匹配，適用於較低能力的 LLM |

影響範圍：/gov_audit、/gov_brain_audit preview、/gov_boot_audit scan。

🔒 安全預設

1. /gov_* 指令只在你明確請求時啟動，不會自行執行。
2. 寫入保護閘門始終活躍，但對日常操作完全透明——一般使用中不會出現任何提示或封鎖。
3. 原有 OpenClaw 工作方式不受影響。

❓ FAQ（新手決策導向，10 題）

1. 不用 slash——第一句最安全怎樣講：

請先在此工作區做 governance readiness check（只讀），然後只告訴我下一步要跑什麼。

Slash 備援：/gov_setup quick

2. 跑完 openclaw onboard / openclaw configure 後 governance 好像被擋：

我剛執行了官方 OpenClaw 初始化/設定指令。請重新檢查 governance readiness，若有需要請對齊 openclaw.json 的信任 allowlist，然後告訴我精確下一步。

Slash 備援：

/gov_openclaw_json
/gov_setup quick

3. Plugin 已安裝但工作區仍未見治理檔案：

請檢查這個 workspace 的 governance 狀態，安全部署缺少的治理檔案，最後執行 audit。

Slash 備援：

/gov_setup check
/gov_setup install
/gov_migrate
/gov_audit

4. Plugin 已更新但行為仍像舊版：

請在此工作區執行 governance 升級流程：check、upgrade、migrate、最後 audit。

Slash 備援：

/gov_setup check
/gov_setup upgrade
/gov_migrate
/gov_audit

5. 出現 Blocked by WORKSPACE_GOVERNANCE runtime gate...——是不是故障？ 不是。一般寫入（skills、projects、代碼）不會硬封鎖。硬封鎖只針對高風險目標（Brain Docs、_control/、治理 prompts、openclaw.json）。要 AI 帶上計劃和已讀檔案：

請包含你的計劃和已讀檔案，然後繼續。

被封鎖 3 次以上且無法繼續：

/gov_brain_audit force-accept

官方 openclaw ... 系統指令預設允許，不應被此 runtime gate 誤擋。

6. 只想改 openclaw.json，不動 workspace 文檔：

請只修改 OpenClaw 控制面設定（openclaw.json），要有備份與驗證，完成後回報結果。

Slash 備援：

/gov_openclaw_json
/gov_audit

7. Slash 觸發不穩定——可以全程用自然語言嗎： 可以：

請用 gov_setup 的 check 模式，回覆 status 與 next action。

或：

請在此 workspace 跑完整 governance upgrade flow，並逐步回報每一步結果。

8. 用自然語言指派 coding 任務——如何減少 governance 封鎖： 直接描述任務。AI 在內部遵循治理，不需要特別操作。例如：

請按需要建立/更新檔案。

9. 優化 Brain Docs，不只是改字面：

請先以 gov_brain_audit 做 preview，列出高風險 findings 與原因；未經我批准不可套用 patch。

批准與回退： <PASTE_IDS_FROM_PREVIEW> 代表「貼上你當次 preview 的 finding IDs」（例如 F002,F005）。

/gov_brain_audit APPROVE: <PASTE_IDS_FROM_PREVIEW>
/gov_brain_audit ROLLBACK

10. 自然語言任務完成後標準化交接：

請用 governance 收尾此任務：如有需要先 migrate，再做 audit，最後輸出可交接的證據摘要。

📚 Deep Docs Links

1. Operations 手冊（EN）: WORKSPACE_GOVERNANCE_README.en.md
2. Positioning 與價值定位（EN）: VALUE_POSITIONING_AND_FACTORY_GAP.en.md
3. Operations 手冊（繁中）: WORKSPACE_GOVERNANCE_README.md
4. Positioning 與價值定位（繁中）: VALUE_POSITIONING_AND_FACTORY_GAP.md

官方參考：

1. https://docs.openclaw.ai/tools/skills
2. https://docs.openclaw.ai/tools/clawhub
3. https://docs.openclaw.ai/plugins
4. https://docs.openclaw.ai/cli/plugins
5. https://docs.openclaw.ai/cli/skills
6. https://github.com/openclaw/openclaw/releases