疑難排解

這是深入操作手冊。請先從 /help/troubleshooting 開始，依照快速分流流程處理。

命令執行順序

依下列順序執行：

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

健康狀態的訊號：

• openclaw gateway status 顯示 Runtime: running、Connectivity probe: ok，以及一行 Capability: ...。
• openclaw doctor 未回報會阻礙運作的設定或服務問題。
• openclaw channels status --probe 顯示每個帳號的即時傳輸狀態，並在支援時顯示 works 或 audit ok。

更新後

更新完成，但閘道未運作、頻道為空，或模型呼叫因 401 而失敗時使用。

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

檢查：

• openclaw status／openclaw status --all 中的 Update restart。待處理或失敗的交接會包含接下來要執行的命令。
• Channels 下方出現 plugin load failed: dependency tree corrupted; run openclaw doctor --fix：頻道設定仍然存在，但外掛註冊在頻道載入前失敗。
• 重新驗證後出現供應商 401：openclaw doctor --fix 會檢查是否存在過時的個別代理程式 OAuth 驗證陰影副本，並移除舊副本，讓所有代理程式都能解析目前的共用設定檔。

安裝分歧與較新設定防護

更新後閘道服務意外停止，或日誌顯示某個 openclaw 二進位檔比最後寫入 openclaw.json 的版本舊時使用。

OpenClaw 會使用 meta.lastTouchedVersion 標記設定寫入版本。唯讀命令可以檢查由較新版 OpenClaw 寫入的設定，但使用較舊二進位檔執行時，程序與服務異動會被拒絕。遭封鎖的動作包括：啟動／停止／重新啟動／解除安裝閘道服務、強制重新安裝服務、以服務模式啟動閘道，以及使用 gateway --force 清理連接埠。

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

復原後的通訊協定不相符

降級或復原後，日誌持續顯示 protocol mismatch 時使用。較舊的閘道仍在執行，但較新的本機用戶端程序仍持續使用舊閘道無法處理的通訊協定範圍重新連線。

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

檢查：

• 閘道日誌中的 protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>。
• openclaw gateway status --deep 中的 Established clients:，或 openclaw doctor --deep 中的 Gateway clients：連線至閘道連接埠的作用中 TCP 用戶端；作業系統允許時，還會包含 PID 與命令列。
• 命令列指向你已復原之較新版 OpenClaw 安裝或包裝程式的用戶端程序。

修正方式：

1. 停止或重新啟動 gateway status --deep 顯示的過時 OpenClaw 用戶端程序。
2. 重新啟動內嵌 OpenClaw 的應用程式或包裝程式：本機儀表板、編輯器、應用程式伺服器輔助程式，或長時間執行 openclaw logs --follow 的 shell。
3. 重新執行 openclaw gateway status --deep 或 openclaw doctor --deep，並確認過時的用戶端 PID 已消失。

不要讓較舊的閘道接受較新且不相容的通訊協定。通訊協定版本提升用於保護線路合約；復原作業應處理程序與版本清理問題。

Skills 符號連結因路徑逸出而遭略過

日誌包含以下內容時使用：

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

每個 Skills 根目錄都是一個包含範圍邊界。當 ~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills 或 ~/.openclaw/skills 下的符號連結，其實際目標解析至該根目錄之外時，除非明確信任該目標，否則會略過此連結。

檢查連結：

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

如果該目標是刻意設定的，請同時設定直接的 Skills 根目錄與允許的符號連結目標：

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

接著啟動新工作階段，或等待 Skills 監看程式重新整理。如果執行中的程序早於這次設定變更，請重新啟動閘道。

請勿使用 ~、/ 或整個同步專案資料夾等過於寬泛的目標。將 allowSymlinkTargets 限定於包含受信任 SKILL.md 目錄的實際 Skills 根目錄。

如果 Skills 工作坊套用功能也應透過這些受信任的符號連結工作區 Skills 路徑寫入，請啟用 skills.workshop.allowSymlinkTargetWrites。若為唯讀的共用 Skills 根目錄，請保持停用。

相關內容：

• Skills 設定
• 設定範例

Anthropic 429：長上下文需要額外用量

日誌／錯誤包含以下內容時使用：HTTP 429: rate_limit_error: Extra usage is required for long context requests。

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

檢查：

• 選取的 Anthropic 模型是支援正式版 1M 上下文的 Claude 4.x 模型（Opus 4.6/4.7/4.8、Sonnet 4.6），或模型設定仍包含舊版 params.context1m: true。
• 目前的 Anthropic 認證資訊不具備使用長上下文的資格。
• 請求僅在需要使用 1M 上下文路徑的長工作階段／模型執行中失敗。

修正選項：

相關內容：

• Anthropic
• 權杖用量與成本
• 為什麼我會收到 Anthropic 的 HTTP 429？

上游 403 封鎖回應

上游 LLM 供應商傳回一般 403（例如 Your request was blocked）時使用。

不要假設這一定是 OpenClaw 設定問題。此回應可能來自 OpenAI 相容端點前方的上游安全層，例如 CDN、WAF、機器人管理規則或反向代理。

openclaw statusopenclaw gateway statusopenclaw logs --follow

檢查：

• 同一供應商下的多個模型以相同方式失敗。
• 傳回 HTML 或一般安全性文字，而非正常的供應商 API 錯誤。
• 同一請求時間的供應商端安全性事件。
• 極小型直接 curl 探測成功，但一般 SDK 格式的請求失敗。

當證據指向 WAF／CDN 封鎖時，請先修正供應商端的篩選。優先針對 OpenClaw 使用的 API 路徑設定範圍明確的允許或略過規則，並避免停用整個網站的防護。

相關內容：

• OpenAI 相容端點
• 供應商設定
• 日誌

本機 OpenAI 相容後端通過直接探測，但代理程式執行失敗

適用情況：

• curl ... /v1/models 可正常運作。
• 極小型直接 /v1/chat/completions 呼叫可正常運作。
• OpenClaw 模型執行僅在一般代理程式回合失敗。

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

檢查：

• 極小型直接呼叫成功，但 OpenClaw 僅在較大的提示詞上執行失敗。
• 即使直接 /v1/chat/completions 使用相同的裸模型 ID 可正常運作，仍出現 model_not_found 或 404 錯誤。
• 後端錯誤指出 messages[].content 預期為字串。
• 使用 OpenAI 相容本機後端時，間歇出現 incomplete turn detected ... stopReason=stop payloads=0 警告。
• 僅在提示詞權杖數較大或使用完整代理程式執行階段提示詞時出現的後端當機。

相關內容：

• 設定
• 本機模型
• OpenAI 相容端點

沒有回覆

如果頻道已啟動但沒有任何回覆，請先檢查路由與政策，再重新連線任何項目。

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

檢查：

• 私訊傳送者是否有待處理的配對。
• 群組提及閘門控制（requireMention、mentionPatterns）。
• 頻道／群組允許清單不相符。

常見特徵：

• drop guild message (mention required → 群組訊息會被忽略，直到提及為止。
• pairing request → 傳送者需要核准。
• blocked / allowlist → 傳送者／頻道已被政策篩除。

相關內容：

• 頻道疑難排解
• 群組
• 配對

儀表板控制介面連線能力

當儀表板／控制介面無法連線時，請驗證 URL、驗證模式及安全內容環境的假設。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

檢查：

• 探測 URL 與儀表板 URL 是否正確。
• 用戶端與閘道之間的驗證模式／權杖是否不相符。
• 在需要裝置身分時使用了 HTTP。

如果更新後本機瀏覽器無法連線至 127.0.0.1:18789，請先復原本機閘道服務，並確認其正在提供儀表板：

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

如果 curl 傳回 OpenClaw HTML，表示閘道運作正常，其餘問題可能是瀏覽器快取、舊的深層連結或過期的分頁狀態。請直接開啟 http://127.0.0.1:18789，再從儀表板進行導覽。如果重新啟動後服務未持續執行，請執行 openclaw gateway start，然後重新檢查 openclaw gateway status。

驗證詳細代碼速查表

使用失敗 connect 回應中的 error.details.code 來選擇下一個動作：

裝置驗證 v2 移轉檢查：

openclaw --versionopenclaw doctoropenclaw gateway status

如果記錄顯示 nonce／簽章錯誤，請更新連線中的用戶端並進行驗證：

如果 openclaw devices rotate / revoke / remove 意外遭到拒絕：

• 已配對裝置的權杖工作階段只能管理自己的裝置，除非呼叫端也擁有 operator.admin。
• openclaw devices rotate --scope ... 只能要求呼叫端工作階段已擁有的操作者範圍。

相關內容：

• 設定（閘道驗證模式）
• 控制介面
• 裝置
• 遠端存取
• 受信任 Proxy 驗證

閘道服務未執行

適用於服務已安裝，但處理程序無法持續執行的情況。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # 同時掃描系統層級服務

檢查：

• Runtime: stopped 及結束提示。
• 服務設定不相符（Config (cli) 與 Config (service)）。
• 連接埠／監聽器衝突。
• 使用 --deep 時發現額外安裝的 launchd/systemd/schtasks。
• Other gateway-like services detected (best effort) 清理提示。

相關內容：

• 背景執行與處理程序工具
• 設定
• Doctor

macOS 閘道無聲地停止回應，觸碰儀表板後又恢復

適用於 macOS 主機上的頻道（Telegram、WhatsApp 等）一次沉寂數分鐘至數小時，而當你開啟控制介面、透過 SSH 登入或以其他方式與主機互動時，閘道似乎立刻恢復的情況。openclaw status 通常不會顯示明顯症狀，因為等你查看時，閘道已再次恢復運作。

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

檢查：

• ~/.openclaw/logs/stability/ 中有一個或多個 *-uncaught_exception.json 組合包，其中 error.code 設為暫時性網路錯誤碼，例如 ENETDOWN、ENETUNREACH、EHOSTUNREACH 或 ECONNREFUSED。
• pmset -g log 中出現類似 Entering Sleep state due to 'Maintenance Sleep' 或 en0 driver is slow (msg: WillChangeState to 0) 的行，且時間與當機時間戳記一致。Power Nap／維護睡眠會短暫讓 Wi-Fi 驅動程式進入狀態 0；任何剛好在該時段發出的對外 connect() 都可能因 ENETDOWN 而失敗，即使主機在其他時間具有完整的網路連線能力。
• launchctl print 輸出顯示 state = not running，並有多次近期的 runs 與結束代碼，尤其是當機與下次啟動之間的間隔約為一小時，而非數秒時。macOS launchd 在短時間內多次當機後，會套用未公開的重新衍生保護機制；這可能導致它停止遵循 KeepAlive=true，直到互動式登入、控制面板連線或 launchctl kickstart 等外部觸發重新啟用該機制。

常見特徵：

• 穩定性組合包中的 error.code 為 ENETDOWN 或同類錯誤碼，且呼叫堆疊指向 Node net 的 lookupAndConnect／Socket.connect。OpenClaw 2026.5.26 及更新版本會將這些錯誤分類為無害的暫時性網路錯誤，因此不再傳播至頂層未捕捉處理常式；如果你使用較舊的版本，請先升級。
• 長時間沒有活動，卻在你連線至控制介面或透過 SSH 登入主機時立即恢復：重新啟用 launchd 重新衍生機制的是使用者可見的活動，而不是控制面板對閘道執行了任何操作。
• runs 計數在一天內持續增加，但 ~/Library/Logs/openclaw/gateway.log 中沒有對應的 received SIG*; shutting down 行：正常關閉會記錄訊號；暫時性當機則不會。

處理方式：

1. 如果你執行的是 2026.5.26 之前的版本，請升級閘道。升級後，未來的 ENETDOWN 錯誤會記錄為警告，而不會終止程序。

2. 對於用作全天候伺服器的 Mac mini／桌上型主機，請減少維護睡眠活動：

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   這會顯著減少、但無法完全消除底層驅動程式的狀態波動。無論這些旗標如何設定，系統仍可能為了 TCP keepalive 與 mDNS 維護而執行部分維護睡眠。

3. 新增存活監看程式，以便未來短時間內多次當機並被 launchd 暫停重新啟動時，能夠迅速偵測：

   # 適用於每 5 分鐘執行一次的排程或 LaunchAgent，並可感知 launchd 的存活檢查範例state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   重點是透過外部操作重新啟用重新衍生機制；macOS 在短時間內多次當機後，僅設定 KeepAlive=true 並不足夠。

相關內容：

• macOS 平台注意事項
• 記錄
• Doctor

存在重複閘道／節點 LaunchAgent 時的 macOS launchd 監督程式迴圈

當 macOS 安裝項目每隔幾秒便持續重新啟動、openclaw 健康檢查在正常與無法使用之間反覆變動，且即使服務看似正在執行， 頻道分派仍然停滯時，請使用此方法。

此問題曾出現在較舊的安裝中，當時 ai.openclaw.gateway 與 ai.openclaw.node LaunchAgent 同時啟用，且兩者都注入了 OPENCLAW_LAUNCHD_LABEL。在此狀態下，OpenClaw 可能偵測到 launchd 監督、嘗試將重新啟動交還給 launchd，結果不是維持單一穩定的閘道程序， 而是陷入快速的 EADDRINUSE／重新衍生迴圈。

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

請檢查：

• 在 30 秒取樣期間出現多個閘道 PID，而非一個穩定的 程序。
• gateway.log 中出現 EADDRINUSE、another gateway instance is already listening，或重複的 重新啟動／交接行。
• 在應該只執行一個受管理閘道服務的主機上， ~/Library/LaunchAgents/ai.openclaw.gateway.plist 與 ~/Library/LaunchAgents/ai.openclaw.node.plist 同時載入。

處理方式：

1. 如果此主機應該只執行閘道服務，請透過 OpenClaw 移除受管理的節點 服務。如果你目前依賴節點服務提供遠端節點功能，請略過此步驟； 解除安裝會停止此主機上的那些功能：

   openclaw node uninstall

2. 安裝持續生效的閘道包裝程式，在啟動 OpenClaw 前清除繼承的 launchd 標記。請使用支援的 --wrapper 選項；不要編輯 ~/.openclaw/service-env/ 下產生的檔案，因為重新安裝服務、 更新及 Doctor 修復都會重新產生該檔案：

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install 會在強制重新安裝、更新及 Doctor 修復後，仍保留包裝程式路徑。

3. 驗證閘道保持穩定且確實提供 RPC，而不只是監聽連線：

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   PID 取樣應顯示一個穩定的程序，而非持續輪替的一組 PID，且傳入頻道分派應恢復運作。

4. 升級到已修正底層雙 LaunchAgent 迴圈的版本後， 請移除因應措施，並重新安裝一般的受管理服務：

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

相關內容：

• macOS 平台注意事項
• Doctor
• 閘道命令列介面

閘道在高記憶體用量期間結束

當閘道在負載下消失、監督程式回報類似 OOM 的重新啟動，或記錄中提到 critical memory pressure bundle written 時使用。

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

請檢查：

• 最新穩定性組合包中的 Reason: diagnostic.memory.pressure.critical。
• 包含 critical/rss_threshold、critical/heap_threshold 或 critical/rss_growth 的 Memory pressure:。
• 接近堆積限制的 V8 heap: 值。
• Largest session files: 項目，例如 agents/<agent>/sessions/<session>.jsonl 或 sessions/<session>.jsonl。
• 當閘道在容器或記憶體受限的服務內執行時，檢查 Linux cgroup 記憶體計數器。

常見特徵：

• critical memory pressure bundle written 在重新啟動前不久出現 → OpenClaw 已擷取 OOM 前的穩定性組合包。請使用 openclaw gateway stability --bundle latest 檢查。
• memory pressure: level=critical ... memoryPressureSnapshot=disabled 出現在閘道記錄中 → OpenClaw 偵測到嚴重記憶體壓力，但 OOM 前穩定性快照已關閉。
• Largest session files: 指向非常大的已遮蔽逐字稿路徑 → 請減少保留的工作階段歷程、檢查工作階段成長情況，或在重新啟動前將舊逐字稿移出作用中儲存區。
• V8 heap: 已用位元組數接近堆積限制 → 請降低提示／工作階段壓力、減少並行工作，或僅在確認該工作負載符合預期後才提高 Node 堆積限制。
• Memory pressure: critical/rss_growth → 記憶體在單一取樣時段內快速增加。請檢查最新記錄中是否有大型匯入、失控的工具輸出、重複重試，或一批排入佇列的代理程式工作。
• 記錄中出現嚴重記憶體壓力，但不存在組合包 → 這是預設行為。請設定 diagnostics.memoryPressureSnapshot: true，以便未來發生嚴重記憶體壓力事件時擷取 OOM 前穩定性組合包。

穩定性組合包不含承載內容。它包含運作相關的記憶體證據與已遮蔽的相對檔案路徑，但不含訊息文字、網路鉤子本文、認證資訊、權杖、Cookie 或原始工作階段 ID。提交錯誤報告時，請附加診斷匯出，而不要複製原始記錄。

相關內容：

• 閘道健康狀態
• 診斷匯出
• 工作階段

閘道拒絕無效設定

當閘道啟動因 Invalid config 而失敗，或熱重新載入記錄顯示已略過無效編輯時使用。

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

請檢查：

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• 作用中設定旁帶有時間戳記的 openclaw.json.rejected.* 檔案。
• 如果 doctor --fix 修復了損壞的直接編輯，則會有帶時間戳記的 openclaw.json.clobbered.* 檔案。
• OpenClaw 會為每個設定路徑保留最新的 32 個 .clobbered.* 檔案，並輪替較舊的檔案。

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

相關內容：

• 設定
• 設定：熱重新載入
• 設定：嚴格驗證
• Doctor

閘道探測警告

當 openclaw gateway probe 能連線到某個目標，但仍印出警告區塊時使用。

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

檢查：

• JSON 輸出中的 warnings[].code 和 primaryTargetId。
• 警告是否與 SSH 備援、多個閘道、缺少範圍或無法解析的驗證參照有關。

常見特徵：

• SSH tunnel failed to start; falling back to direct probes. → SSH 設定失敗，但命令仍嘗試直接探測已設定的目標／迴路目標。
• multiple reachable gateway identities detected → 有不同的閘道回應，或 OpenClaw 無法證明可連線的目標是同一個閘道。即使傳輸連接埠不同，連至同一閘道的 SSH 通道、Proxy URL 或已設定的遠端 URL 仍視為具有多種傳輸方式的單一閘道。
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → 連線成功，但詳細 RPC 受範圍限制；請配對裝置身分，或使用具有 operator.read 的認證資訊。
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → 連線成功，但完整的診斷 RPC 集合逾時或失敗。請將此情況視為可連線但診斷功能降級的閘道；比較 --json 輸出中的 connect.ok 和 connect.rpcOk。
• Capability: pairing-pending 或 gateway closed (1008): pairing required → 閘道已回應，但此用戶端仍需完成配對／核准，才能取得一般操作員存取權。
• 未解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文字 → 此命令路徑無法取得失敗目標所需的驗證資料。

相關內容：

• 閘道
• 同一主機上的多個閘道
• 遠端存取

頻道已連線，但訊息未流通

如果頻道狀態顯示已連線，但訊息完全無法流通，請著重檢查政策、權限及頻道特定的傳遞規則。

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

檢查：

• 私訊政策（pairing、allowlist、open、disabled）。
• 群組允許清單與提及要求。
• 缺少的頻道 API 權限／範圍。

常見特徵：

• mention required → 訊息因群組提及政策而被忽略。
• pairing／等待核准的追蹤記錄 → 傳送者尚未獲得核准。
• missing_scope、not_in_channel、Forbidden、401/403 → 頻道驗證／權限問題。

相關內容：

• 頻道疑難排解
• Discord
• Telegram
• WhatsApp

排程與心跳偵測傳遞

如果排程或心跳偵測未執行或未傳遞，請先確認排程器狀態，再檢查傳遞目標。

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

檢查：

• 排程已啟用，且存在下一次喚醒時間。
• 工作執行歷史狀態（ok、skipped、error）。
• 心跳偵測略過原因（quiet-hours、requests-in-flight、cron-in-progress、lanes-busy、alerts-disabled、empty-heartbeat-file、no-tasks-due）。

相關內容：

• 心跳偵測
• 排程工作
• 排程工作：疑難排解

節點已配對，但工具失敗

如果節點已配對但工具失敗，請分別確認前景狀態、權限及核准狀態。

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

檢查：

• 節點已上線，且具有預期功能。
• 相機／麥克風／位置／螢幕的作業系統權限授予狀態。
• 執行核准與允許清單狀態。

常見特徵：

• NODE_BACKGROUND_UNAVAILABLE → 節點應用程式必須位於前景。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少作業系統權限。
• SYSTEM_RUN_DENIED: approval required → 執行核准等待中。
• SYSTEM_RUN_DENIED: allowlist miss → 命令遭允許清單封鎖。

相關內容：

• 執行核准
• 節點疑難排解
• 節點

瀏覽器工具失敗

當瀏覽器工具動作失敗，但閘道本身運作正常時使用。

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

檢查：

• 是否已設定 plugins.allow 且包含 browser。
• 瀏覽器執行檔路徑是否有效。
• CDP 設定檔是否可連線。
• existing-session / user 設定檔是否可使用本機 Chrome。

相關內容：

• 瀏覽器（由 OpenClaw 管理）
• 瀏覽器疑難排解

如果升級後某項功能突然損壞

大多數升級後的損壞，都是設定漂移或目前開始強制執行更嚴格的預設值所造成。

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

如果檢查後服務設定與執行階段仍不一致，請從相同的設定檔／狀態目錄重新安裝服務中繼資料：

openclaw gateway install --forceopenclaw gateway restart

相關內容：

• 驗證
• 背景執行與程序工具
• 節點配對

相關內容

• 診斷工具
• 常見問題
• 閘道操作手冊