# 疑難排解

判斷問題出在啟動設定、CLI，還是模型供應商。

## 檢查預計使用的啟動設定

從命令面板執行 **Show Agent Launch**，並選擇工作位置。報告會顯示每個 CLI 在該位置目前的啟動方式：執行檔、目錄、參數與環境變數名稱。私密的值會隱藏。

報告描述的是以目前設定進行的下一次啟動，而不是已在執行的 Agent。如果請求成功，供應商的用量記錄可以協助確認是哪個帳號處理的。

## 依症狀查找

| 問題 | 檢查重點 |
| --- | --- |
| 找不到設定檔 | 依序選擇 Open Settings，再在 Facade: Home 底下選擇 Edit in facade.json。如果遠端視窗以 JSON 形式開啟設定，這個命令會直接開啟 facade.json。 |
| New Agent 中少了某個項目 | 檢查項目的名稱與 `type`，並確認沒有被 `enabled: false` 停用。無效的項目會列在 Unavailable 底下並附上原因。 |
| 找不到執行檔 | 在專案實際執行的位置安裝 CLI，或在 `command` 中填寫完整路徑。OpenCode 請使用第 2 版（`@opencode/cli`）。 |
| 環境變數參照找不到 | Agent 啟動前，編輯器主機必須具備該變數。在既有終端機中匯出變數，不會更新主機環境。 |
| 參數與 Facade 管理的選項衝突 | 從 `args` 中移除該選項，改用 `model`、`effort` 或最上層的 `yolo` 欄位。 |
| 驗證失敗或模型無法使用 | 檢查供應商的金鑰、端點、區域、模型 ID 與帳號權限。 |
| Codex 供應商沒有回應 | 確認其端點支援 Responses API。 |
| Agent 找不到另一個 Agent | 檢查兩者的專案是否透過同一個 Facade home 連接，且存取設定允許通訊。 |
| 自訂程式收不到訊息 | 直接在它的終端機輸入。自訂項目不會收到 Facade 的訊息或工具。 |
| 儲存的設定沒有套用到執行中的 Agent | 啟動新的 Agent。若想保留對話，請先結束 Agent，再用 Resume Agent 以新設定重新啟動。 |

SSH 設定請見[在遠端機器上執行 Agent](https://facadecode.com/zh-tw/docs/remote-ssh/)。手機連線錯誤請見[從手機繼續工作](https://facadecode.com/zh-tw/docs/remote-control/)。

## 回報問題

請附上你做過的嘗試、完整的錯誤訊息、作業系統、編輯器與擴充套件版本、CLI 版本，以及所選的項目。情況允許的話，也請提供相關設定，但請移除金鑰與私密值。

[開啟 GitHub issue ↗](https://github.com/y5ez3g/facadecode/issues)