修復 OpenClaw 模型故障轉移與認證錯誤

想像一下，你正在執行一個關鍵任務，結果 API 突然因為達到速率限制（rate limit）或是服務端不穩定而掛掉，這真的會讓人抓狂。這就是為什麼我們需要 Failover（容錯移轉）機制，讓你的系統在遇到問題時能自動切換到備援方案，確保服務不中斷。

這篇文章會幫你理解 OpenClaw 的 Failover 運作邏輯，並解決常見的認證錯誤。

容錯移轉（Failover）是如何運作的？

Failover 分成兩個階段進行：

1. Auth profile rotation：在同一個 provider 內輪替不同的認證設定檔。
2. Model fallback：切換到 agents.defaults.model.fallbacks 中定義的下一個模型。

系統會對失敗的 profile 應用冷卻時間（指數退避），所以即使某個 provider 暫時故障或被限流，OpenClaw 依然能保持回應。

---

「No credentials found for profile ‘anthropic:default’」是什麼意思？

這代表系統嘗試使用 ID 為 anthropic:default 的 auth profile，但在預期的 auth store（認證儲存區）中找不到對應的憑證。

---

針對「No credentials found for profile anthropic:default」的修復檢查清單

1. 確認 auth profiles 的存放位置：

   • 目前路徑：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
   • 舊版路徑：~/.openclaw/agent/*（可透過 openclaw doctor 進行遷移）

2. 確認你的環境變數有被 Gateway 讀取

   • 如果你在 shell 設定了 ANTHROPIC_API_KEY 但透過 systemd 或 launchd 執行 Gateway，它可能無法繼承該變數。
   • 請將變數放入 ~/.openclaw/.env 或啟用 env.shellEnv 設定。

3. 確保你編輯的是正確的 agent

   • 在多 agent 的設定下，系統中可能存在多個 auth-profiles.json 檔案。

4. 檢查模型與認證狀態

   openclaw models status

---

針對「No credentials found for profile anthropic」的修復檢查清單

這代表該次執行被鎖定（pinned）在某個 Anthropic auth profile，但 Gateway 找不到它。

使用 setup-token：

claude setup-token
openclaw models auth setup-token --provider anthropic

如果你想改用 API key：

• 在 gateway host 上的 ~/.openclaw/.env 檔案中加入 ANTHROPIC_API_KEY。
• 清除任何鎖定的順序：

  openclaw models auth order clear --provider anthropic

確認你在 gateway host 上執行指令

• 在遠端模式下，auth profiles 是儲存在 gateway 機器上，而不是你的筆電。

---

為什麼它也嘗試了 Google Gemini 並且失敗了？

如果你的模型配置將 Google Gemini 列為 fallback（或者你切換到了 Gemini 的簡寫模式），OpenClaw 就會在模型回退期間嘗試呼叫它。如果你還沒設定好 Google 的憑證，就會看到 No API key found for provider "google"。

修復方法： 你可以選擇提供 Google 認證，或者從 agents.defaults.model.fallbacks 中移除 Google 模型。

下一步

• 了解如何使用 openclaw doctor 診斷問題
• 設定多個 Auth Profiles 以提高穩定性

如果你在設定過程中遇到任何困難，可以隨時詢問我們的 AI Setup Assistant。