OpenClaw Gateway 死鎖：為什麼指令執行剛好 10 分鐘後才失敗？完整修復指南
你是否遇過這種情況？在 OpenClaw 正在處理某個任務（Agent turn 進行中）時，你想要查詢一下現在有哪些 Session 在執行，於是輸入 openclaw sessions --json 或 /cron list。然後你就開始等，等了 5 分鐘、8 分鐘……剛好 10 分鐘後，指令失敗並輸出錯誤訊息。這不是巧合，這是 OpenClaw 的 Gateway 死鎖 Bug（Issue #18470）。
為什麼剛好是 10 分鐘？不是 5 分鐘也不是 15 分鐘？
這個「剛好 10 分鐘」不是隨機的，它直接揭示了 Bug 的根源。OpenClaw 的 Gateway 在執行內部指令（如 sessions、cron list）時，使用了一個嵌入式執行器（embedded runner），這個執行器有一個固定的10 分鐘硬性超時（timeout）。
死鎖的技術原因
OpenClaw 的 Gateway 使用一把「資源鎖」來管理 Agent 的執行狀態。問題在於：
Agent 開始執行 LLM 任務（Agent turn 開始）→ Gateway 鎖定資源鎖
你在任務進行中輸入 sessions --json → 這個指令嘗試取得資源鎖
資源鎖被 Agent 持有 → sessions 指令無法取得鎖 → 開始無限等待
等了 600 秒（10 分鐘）後，嵌入式執行器的硬性超時觸發 → 指令失敗
哪些指令會觸發 Gateway 死鎖？
以下指令在 Agent 正在執行任務時呼叫，都可能導致 10 分鐘死鎖：
🔴 高風險指令（幾乎必定死鎖）
- • openclaw sessions --json
- • openclaw sessions list
- • /cron list
- • /cron status
🟠 中等風險指令（不穩定）
- • openclaw gateway status
- • openclaw status --deep
- • /subagents（查看子 Agent）
- • openclaw doctor（診斷時）
確認是否遇到 Gateway 死鎖
執行以下步驟確認：
# 搜尋日誌中的超時記錄
grep -i "timeout\|deadlock\|10 minutes\|600" ~/.openclaw/logs/openclaw.log | tail -20
# 查看 Gateway 程序目前是否持有鎖
ps aux | grep openclaw
# 如果有多個 openclaw 相關程序在執行，可能有殭屍程序導致鎖未釋放
⚠️ 注意：死鎖的副作用
Gateway 死鎖不只是讓你的指令失敗。在某些情況下，10 分鐘的等待期間，OpenClaw 的 retry 邏輯會不斷重試，每次重試都消耗 API Token，最終可能導致你的 Token 配額被大量浪費（有用戶回報一次死鎖消耗了超過 50,000 Token）。
立即解決：強制解除死鎖
如果你已經進入死鎖狀態（指令卡住了），最快的解除方法是重啟 Gateway 並清除鎖：
# 方法一：等待目前的 Agent 任務自然完成
# （如果任務快結束，可以稍等）
# 方法二：強制重啟 Gateway（立即解除所有鎖）
openclaw gateway restart
# 注意：重啟 Gateway 會中斷目前正在執行的 Agent 任務！
# 方法三：如果 gateway restart 本身也卡住
# 找到並殺死 openclaw gateway 程序
ps aux | grep "openclaw-gateway\|openclaw gateway"
kill -9 [PID] # 強制結束程序
# 然後重新啟動
openclaw gateway start
預防死鎖：改變使用習慣
避免 Gateway 死鎖的最有效方法，是改變你查詢系統狀態的時機：
✅ 正確做法：在 Agent 空閒時查詢
等待 Agent 完成當前任務（你收到回覆後）再執行 sessions 或 cron 查詢。Agent 空閒時，Gateway 不持有鎖，查詢指令可以立即執行。
# 等 Agent 回覆你後，再執行以下查詢
openclaw sessions list
/cron list
❌ 避免：在任務進行中查詢系統狀態
不要在傳送指令給 Agent 後，立即打開另一個終端機執行 sessions 或 cron list。等第一個任務完成後再做。
進階設定：縮短死鎖超時時間
OpenClaw 的 10 分鐘超時是硬寫在程式碼中的。在官方修復之前，有一個社群提供的 workaround：透過環境變數設定更短的超時時間，讓死鎖更快失敗，減少浪費的 Token：
# 在啟動 Gateway 前設定環境變數（縮短到 60 秒）
export OPENCLAW_EMBEDDED_RUN_TIMEOUT=60
# 重啟 Gateway
openclaw gateway restart
# 設定為永久生效（加入 ~/.bashrc 或 ~/.zshrc）
echo 'export OPENCLAW_EMBEDDED_RUN_TIMEOUT=60' >> ~/.zshrc
source ~/.zshrc
💡 為什麼設定 60 秒而不是更短？
60 秒是一個平衡點——足夠讓合法的長時間任務完成，同時又比原來的 10 分鐘短很多。設得太短（如 10 秒）可能導致正常的任務也被強制中斷。
特殊情況：gateway restart 指令本身也會超時
這裡有一個特別有趣的 Bug-in-Bug 情況：openclaw gateway restart 這個指令本身在某些情況下也會觸發超時問題（Issue #32933）。
🔍 什麼情況下 gateway restart 會超時？
當你透過 exec 工具（讓 Agent 自動執行指令）呼叫 openclaw gateway restart 時，問題出現了：
- • gateway restart 需要 10-15 秒才能完成
- • exec 工具的內建等待時間不夠長
- • Gateway 實際上重啟成功了，但 exec 工具等不到確認就超時了
- • 導致 Agent 認為重啟失敗，產生錯誤訊息並觸發重試
# 如果讓 Agent 自動重啟 Gateway，請在 soul.md 中加入等待指示：
# After running 'openclaw gateway restart', wait at least 20 seconds
# before checking the gateway status. The restart takes 10-15 seconds
# and the exec tool may timeout before confirmation is received.
# 手動重啟時不受此影響，直接執行即可
openclaw gateway restart
# 等 15 秒後再執行
sleep 15
openclaw gateway status
官方修復進展
Gateway Deadlock：Internal Commands Hang During Active Agent Turn
狀態：Open。計畫修復方向是將內部查詢指令改為非阻塞模式，避免爭奪同一把資源鎖。
Gateway Restart Command Loses Result in Exec Tool
狀態：Open。計畫修復方向是讓 exec 工具在呼叫 gateway restart 時使用非同步模式，不等待確認回覆。
常見問題 Q&A
Q：Gateway 死鎖期間，正在進行的 Agent 任務會怎樣？
A：如果你只是查詢指令（sessions/cron）卡住，正在進行的 Agent 主任務不受影響，它會繼續執行。死鎖只影響你發起的那個查詢指令。但如果你強制重啟 Gateway 來解除死鎖，那麼主任務就會被中斷。
Q：為什麼 OpenClaw 不把查詢指令設計成非阻塞的？
A：這是一個架構設計問題。OpenClaw 的 Gateway 使用了一個單執行緒的資源管理模型，確保同一時間只有一個操作在修改 Session 狀態。這保證了資料一致性，但代價是查詢也需要排隊等待。官方正在研究如何引入讀寫分離鎖來解決這個問題。
Q：如何知道 Gateway 死鎖已經解除？
A：在重啟 Gateway 後，執行 openclaw gateway status。如果快速回傳結果（不再等待），代表死鎖已解除。也可以執行一個簡單的指令（如 /status）確認 Agent 能正常回應。
深入分析：Gateway 死鎖的常見觸發情境
理解死鎖的觸發路徑，有助於你在日常使用中有意識地避免它：
🎯 情境一：好奇心觸發死鎖
讓 OpenClaw 執行長任務，然後好奇地執行 openclaw sessions --json 查看進度。這是最常見的觸發方式。
✅ 正確做法：等 OpenClaw 主動匯報進度（在任務指令中要求它每完成一定量就通知你），而不是主動查詢。
🎯 情境二：監控腳本觸發死鎖
你寫了每 5 分鐘執行 openclaw sessions --json 的監控腳本。若某次執行恰好在 Agent 處理任務時觸發，整個腳本就被卡死 10 分鐘。
✅ 正確做法：在腳本中設定比死鎖更短的超時（如 30 秒），超時後優雅退出。
🎯 情境三：Skill 自身觸發死鎖
某個 Skill 在執行中呼叫了 openclaw sessions，且這個 Skill 被 Agent turn 中呼叫，形成死鎖。
✅ 正確做法：審查 Skill 程式碼，避免在 Skill 中呼叫 sessions 或 cron 等系統管理指令。
#!/bin/bash
# 安全的 OpenClaw 狀態監控腳本
# 設定最多等待 30 秒（避免卡死 10 分鐘）
STATUS=$(timeout 30 openclaw gateway status 2>&1)
if [ $? -eq 124 ]; then
echo "⚠️ Gateway 查詢超時，可能有死鎖，跳過"
exit 1
fi
echo "✅ Gateway: $STATUS"
網路不穩如何加重死鎖問題？
你可能注意到：在網路不穩定的環境中，Gateway 死鎖的頻率更高。這有幾個原因：
⏱️ 任務時間拉長
網路慢 → Agent 等待 API 回應時間更長 → Agent turn 持續更久 → 鎖被持有的時間更長 → 你更容易在等待期間「手癢」執行查詢指令。
🔄 重試增加鎖爭用
API 請求超時 → 系統自動重試 → 每次重試都需要重新取得鎖 → 鎖的爭用次數增加 → 死鎖機率上升。
VPN07 - 縮短Agent任務時間，降低死鎖機率
1000Mbps千兆頻寬 · API請求秒速完成 · Gateway鎖釋放更快
Gateway 死鎖的根本原因是鎖被持有太久。VPN07 的 1000Mbps 千兆頻寬讓 Agent 與 Claude API 的每次通訊都能快速完成，大幅縮短每個 Agent turn 的持續時間，也就縮短了鎖被持有的時間，間接降低死鎖觸發機率。全球 70+ 節點，十年穩定運營，月費 $1.5，30 天退款保證。