Migrations - OpenClaw 設定變更管理

README.md

Migrations — OpenClaw 設定變更管理

用時間戳排序的 patch 檔，逐筆記錄並套用 OpenClaw 的設定變更（格式仿 Supabase migration）。

---

🚦 三條鐵則（動手前先確認）

1. 路徑只用相對路徑 migrations/ 開頭 — 新版本擋掉 ~/.openclaw 目錄，絕對路徑會執行失敗。
2. 一定先 --dry-run — 驗證過才能真的 apply。
3. apply 與 restart 都要先得到主人同意 — 不可自己直接套用或重啟。

---

✅ 標準流程

# 0. 先確認在 workspace 根目錄，相對路徑才會對
cd ~/.openclaw/workspace

# 1. 建立 migration 檔（命名見下方規則）
#    migrations/YYYYMMDDHHmmss_描述.json5

# 2. Dry-run 驗證（必做）
openclaw config patch --file migrations/YYYYMMDDHHmmss_描述.json5 --dry-run

# 3. 【先問主人同意】才 apply
openclaw config patch --file migrations/YYYYMMDDHHmmss_描述.json5

# 4. 【先問主人同意】才重啟
openclaw gateway restart --safe

---

📝 命名規則

YYYYMMDDHHmmss_簡短描述.json5

• 例：20260525010000_disable-session-auto-reset.json5
• 時間戳排序、不會撞號。

📄 檔案格式

// Migration: 標題
// 原因: 為什麼要改
// 日期: YYYY-MM-DD
// 影響: 改了會怎樣
{
  "要改的設定": "值"
}

---

📌 路徑為什麼要相對（鐵則 1 的原理）

這資料夾真實位置是 ~/.openclaw/workspace/migrations/，但新版本無法存取 ~/.openclaw， 所以指令裡的檔案路徑一律從 migrations/ 開頭，且要在 workspace 根目錄下執行。

	範例
✅ 對	migrations/20260525010000_xxx.json5
❌ 錯	~/.openclaw/workspace/migrations/20260525010000_xxx.json5
❌ 錯	/home/ubuntu/.openclaw/workspace/migrations/...

TOOLS.md

OpenClaw 設定變更流程（Migration）

• 何時用：任何要持久變更 OpenClaw 行為／設定的時候，都走這條。常見情境：
  • 調整 heartbeat 間隔、session 設定（如關掉 auto-reset）
  • 開關 plugin、改 gateway 或排程行為
  • 主人說「改某個設定」「把 XX 關掉／打開」而那是 ~/.openclaw/openclaw.json 裡的項目
  • → 凡是想動 openclaw.json，一律用 migration 流程，不要手動編輯
• 功能: 透過 migration patch 檔變更 ~/.openclaw/openclaw.json
• 流程：建檔 → dry-run → 主人確認 → apply → 主人確認 → 重啟
• 重啟指令：openclaw gateway restart --safe
• 詳細規則（路徑寫法、命名、相對路徑注意）：見 ~/.openclaw/workspace/migrations/README.md
• ❗ 套用和重啟都要先確認主人
• ❗ 不要手動修改 ~/.openclaw/openclaw.json 檔案，一定要用 migration 流程