疑難排解

這是深入操作手冊。請先從 /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。待處理或失敗的交接會包含下一個要執行的命令。
• 頻道下方的 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 殼層。
3. 重新執行 openclaw gateway status --deep 或 openclaw doctor --deep，並確認過時的用戶端 PID 已消失。

不要讓較舊的閘道接受不相容的較新通訊協定。通訊協定版本提升是為了保護線上傳輸契約；回復舊版後的復原屬於程序／版本清理問題。

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

適用於記錄包含以下內容的情況：

略過位於設定根目錄之外的逸出 Skill 路徑：... reason=symlink-escape

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

檢查連結：

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

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

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

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

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

如果 Skill Workshop 的套用作業也應寫入這些受信任、以符號連結連接的工作區 Skill 路徑，請啟用 skills.workshop.allowSymlinkTargetWrites。對唯讀的共用 Skill 根目錄，請維持停用。

相關內容：

• 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
• Token 使用量與費用
• 為什麼會收到 Anthropic 的 HTTP 429？

上游 403 封鎖回應

適用於上游 LLM 提供者回傳一般性 403（例如 Your request was blocked）的情況。

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

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 執行僅在較大的提示詞上失敗。
• 即使直接使用相同的裸模型 ID 執行 /v1/chat/completions 可正常運作，仍出現 model_not_found 或 404 錯誤。
• 後端錯誤指出 messages[].content 預期收到字串。
• 使用 OpenAI 相容本機後端時，間歇性出現 incomplete turn detected ... stopReason=stop payloads=0 警告。
• 僅在提示詞 Token 數較多或使用完整代理程式執行階段提示詞時，才發生後端當機。

相關內容：

• 設定
• 本機模型
• 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 等）一次沉寂數分鐘至數小時，且你一開啟 Control UI、透過 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／Maintenance Sleep 會短暫將 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 及更新版本會將這些情況分類為無害的暫時性網路錯誤，因此不再傳播至頂層未捕捉處理常式；若你使用較舊版本，請先升級。
• 長時間沉寂後，在你連線至 Control UI 或透過 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 而停滯的密集當機能迅速被偵測到：

   # launchd 感知的存活檢查範例，適合用於每 5 分鐘執行的排程或 LaunchAgentstate=$(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

macOS launchd 監督程式因重複的閘道／節點 LaunchAgent 而進入迴圈

用於 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，而非單一穩定 處理程序。
• EADDRINUSE、another gateway instance is already listening，或 gateway.log 中反覆出現的重新啟動／交接行。
• 在應該只執行一個受管理閘道服務的主機上， ~/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。
• Memory pressure:，以及 critical/rss_threshold、critical/heap_threshold 或 critical/rss_growth。
• 接近堆積限制的 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 出現在閘道記錄中 → OpenClaw 偵測到嚴重記憶體壓力，並記錄可用的處理程序內記憶體資訊。
• Largest session files: 指向非常大的已遮蔽逐字稿路徑 → 請減少保留的工作階段歷程記錄、檢查工作階段增長情況，或在重新啟動前將舊逐字稿移出作用中儲存區。
• V8 heap: 已用位元組接近堆積限制 → 請先降低提示／工作階段壓力或減少並行工作。對於受管理服務，請檢查 openclaw gateway status 中的 Gateway heap:；如果顯示 not set，請使用 openclaw gateway install --force 重新產生舊服務中繼資料。系統會刻意忽略環境殼層的 NODE_OPTIONS。僅在確認持續工作負載，並預留足夠的原生記憶體餘裕後，才使用明確的監督程式層級堆積覆寫。
• Memory pressure: critical/rss_growth → 記憶體在單一取樣時段內快速增長。請檢查最新記錄是否有大型匯入、失控的工具輸出、反覆重試或一批排入佇列的代理程式工作。
• 記錄中出現嚴重記憶體壓力，但不存在套件 → 事件發生後請擷取 openclaw gateway diagnostics export，以取得可用的操作證據。

穩定性套件不含承載資料。它包含操作記憶體證據及已遮蔽的相對檔案路徑，不包含訊息文字、網路鉤子本文、認證資訊、權杖、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）。

相關內容：

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

節點已配對，但工具失敗

若節點已配對但工具失敗，請分別排查前景狀態、權限及核准狀態。

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

相關內容：

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

相關內容

• Doctor
• 常見問題
• 閘道操作手冊