feat: Redis Lock 跨平台相容性與管理議題

[jlin53882]

背景

PR #662 實現了 Redis distributed lock 用於解決高並發寫入的 lock contention 問題。

相關連結

• PR feat: Redis distributed lock for high concurrency #662: feat: Redis distributed lock for high concurrency #662
• Issue [BUG] auto-recall timeout 在首次啟動或多進程 session 時容易發生 #643: [BUG] auto-recall timeout 在首次啟動或多進程 session 時容易發生 #643
• Issue Solution: Redis Distributed Lock for High Concurrency (extends #643) #659: Solution: Redis Distributed Lock for High Concurrency (extends #643) #659

Redis Lock 使用情境

用戶類型	需要的 lock	需要 Redis？
單一 Agent	原本的 file lock 就夠了	❌ 不需要
多個 Agent 同時寫入	需要分散式 lock	✅ 需要

跨平台相容性

平台	Redis 安裝方式
Windows	MSI 安裝（MSOpenTech 版本）
Mac	brew install redis
Linux	apt/yum/dnf

雲端選項（免自管）

• Redis Cloud（免費方案）
• Upstash
• Redis Enterprise Cloud

設計考量

目前實作（Graceful Fallback）

優先嘗試 Redis lock，Redis 不可用時，回傳 no-op lock（程式照常跑）。

情境	行為	優點	缺點
有 Redis	用 Redis lock	真正解決高並發	需要安裝
無 Redis	no-op lock	不阻塞程式	失去 lock 保護

替代方案：Failover 到 File Lock

Redis 不可用時，用原本的 file lock，保有 lock 保護，只是效能較差。

建議

1. 單一 Agent 用戶：不需要 Redis，原本就能用
2. 多個 Agent 同時寫入：需要 Redis（本地或雲端）
3. 文件說明：需要清楚說明什麼情況需要 Redis

待確認

• 是否要改成 failover 到 file lock（保有正確性）？
• 文件是否要說明使用情境？
• 要記錄到 README 嗎？

[jlin53882]

修正：標題中的「多實例/多機器」應該是「多個 Agent 同時寫入」才對。

使用情境（修正版）

用戶類型	情境	需要 Redis？
單一 Agent	單獨使用	❌ 不需要
多個 Agent 同時寫入	同時有多個 OpenClaw Agent 寫入 memory	✅ 需要

[jlin53882]

Windows Redis 安裝參考

https://ithelp.ithome.com.tw/m/articles/10249583

[jlin53882]

更新：已修改 Failover 行為

變更內容

PR #662 已更新：當 Redis 不可用時，改為 fallback 到 file lock（而非 no-op）。

` ypescript
// 修改前（no-op）
return async () => {}; // No-op release

// 修改後（file lock fallback）
return this.createFileLock(key, ttl); // 使用 file lock
`

修正後的行為

情境	行為	優點
有 Redis	用 Redis lock	真正解決高並發
無 Redis	用 file lock	保有 lock 保護

優點

1. 保有 lock 保護機制（不會資料競爭）
2. 不需要 Redis 也能正常運作
3. 單機單 Agent 用戶不受影響

[jlin53882]

更新：Redis Lock 已整合完成

Issue #643 解決方案

PR #662 已將 Redis lock 整合到 store.ts。

不再需要設定額外選項，只要有 Redis server 運行，就會自動使用 Redis lock。

使用方式

1. 確保 Redis 運行：localhost:6379
2. 自動使用 Redis lock：所有寫入操作會優先使用 Redis
3. 無 Redis 時 fallback：自動使用 file lock

相關連結

• PR feat: Redis distributed lock for high concurrency #662: feat: Redis distributed lock for high concurrency #662
• Issue [BUG] auto-recall timeout 在首次啟動或多進程 session 時容易發生 #643: [BUG] auto-recall timeout 在首次啟動或多進程 session 時容易發生 #643

[jlin53882]

Update: 單一實例不需要 Redis

對於單一 OpenClaw 實例用戶：

• Issue feat: batch write to reduce lock contention from auto-capture (extends Issue #643) #665 的 �ulkStore() 使用 file lock，不需要 Redis
• 只有多實例才需要 Redis lock

建議

用戶類型	建議
單一實例	不需要 Redis，使用 file lock + bulkStore
多實例	需要 Redis lock（PR #662）