在多代理（Multi-Agent）架構的日常維運中，最容易讓工程師捏把冷汗的狀況之一，就是打開終端機，卻發現 status summary、JSON 輸出或 TUI（文字使用者介面）上，顯示的 provider 或是模型名稱跟原本預期的完全不一樣。
明明專案裡設定好要跑某個輕量測試模型，畫面上卻大喇喇地寫著另一個全域（Global）模型。這時候，很多人會直覺認為「完蛋了，路由走錯地方了！」然後急忙跑去修改正式環境的設定檔。
但先等一下！在 OpenClaw 的多代理環境裡，畫面顯示錯模型，並不代表底層 API 的請求真的送錯了。問題往往只發生在別名解析器（Alias Resolver）把 Agent 區域（Local）的設定，誤解成了全域別名。先把「顯示錯誤」和「實際路由錯誤」分開來看，才不會在除錯時愈弄愈糟。
本篇目錄
動手改設定前，先建立最小重現沙盒
遇到這種設定疑似跑掉的狀況，第一步絕對不是直接去動 production 的設定，而是先在本地端切出一個「最小重現（Minimal Reproduction）」的測試沙盒。
你可以準備兩個 Agent，刻意讓它們使用同名的 alias，但各自指向不同的測試模型。為了避免跟真實的機密環境混淆，名稱請使用不含真實 provider 或金鑰的假資料（Fixture），例如：
- agent-a：將別名指向
local-alpha - agent-b：將別名指向
local-beta - 全域對照組：另外保留一個 global alias 作為全域的比對基準。
在只改變這個變數的情況下，依序把 status summary、JSON 輸出與 TUI 畫面擷取下來，並且同步記下後台真正送出請求所使用的模型。這份對照表，就是我們接下來抓出 Bug 的關鍵。
用三個測試 Fixture，精準抓出 Alias 衝突點
有了乾淨的測試環境後，我們可以透過以下三個階段，定位出 Alias 是在哪個解析環節被蓋掉的：
1. 只有 Agent-local Alias
先不要設定任何同名的 global alias，只在單一的 agent 內宣告別名。如果這時候 status 能正確顯示 local-alpha，代表 agent scope 的基礎運作是沒問題的。如果連在這個最單純的狀態下，畫面都已經跑出空值或其他模型名稱，請優先去查該版本的 resolver 解析邏輯，別先把問題怪到模型 API 身上。
2. Agent-local 與 Global 同名衝突
接著，建立一個同名的 global alias，讓 agent-a 的 local 設定與全域值「打架」。這是整個排查中最重要的一步：如果系統底層的實際請求仍舊抓到了 local-alpha，但終端機的 summary 卻顯示 global-model，那答案就很明顯了——這純粹是「狀態解析的顯示層」出包，而不是路由送錯。
除錯小提醒： 檢查 Log 輸出時，請務必同時保留 agent ID、alias 原值、解析後的 provider 名稱，以及實際的 request fixture。如果只看畫面最後面那欄 summary，很容易就會被誤導。
3. 明確清除 (Explicit Clear) 後重載
最後一個測試，是明確清除 agent-local alias 的設定並重新載入。預期的結果應該要乖乖退回到 global alias，而且 status、JSON、TUI 三個地方的顯示必須完全一致。這個動作可以幫我們排除「舊設定還卡在記憶體」或是「設定檔合併順序寫錯」所造成的假象。記得每次測試都要開全新的 session，避免快取混入干擾。
修正設定後，怎樣的驗證才算過關？
當團隊針對 alias resolver 發布了修正版本後，請務必拿著上面那三個 fixture 重新跑一次。一份及格的驗證表至少要確認以下幾點：
- Agent-only alias：是否能正確保留在 agent scope 內？
- 同名 Global alias 出現時：顯示層是否還能堅持顯示 local 的值，沒被全域設定強行蓋掉？
- Explicit clear 後：是否能正確退回（fallback）到 global 值？
- 一致性：實際發出的 request 路由是否與畫面顯示完全一致？
如果在驗收時發現「只有 status summary 錯，但 request 路由是對的」，請把它記為顯示層的回歸錯誤（Regression），別急著發布路由異常的重大警報；唯有兩邊都錯時，才需要往下深挖設定載入與 fallback 機制。
給維運團隊的 5 步除錯節奏
第一線維運人員如果遇到類似狀況，建議照著這 5 步節奏處理：
- 保存現場：把當下的軟體版本、agent scope 與三種輸出的原始畫面先備份起來。
- 最小重現：用不含敏感資料的 fixture 進行本地重現。
- 交叉比對：核對 status 顯示與實際的 request，分清是顯示問題還是路由問題。
- 升級驗證：套用修正版後，在同一個環境重跑一次測試。
- 納入驗收：把這些 fixture 寫進未來的改版驗收表裡，特別把「同名 local/global alias」列為必考題。
用這套邏輯來除錯，不僅能避免在慌亂中改壞正式環境的設定，也能讓多代理架構的運作更透明穩定。
常見問題 (FAQ)
不一定。這正是我們強調要「交叉比對」的原因。Status、JSON 或 TUI 看到的結果，是經過解析器轉化過的；很多時候只是顯示層抓錯了 Scope，但底層 API 呼叫的路由依舊是正確的。
因為在多代理環境中，Local（區域）與 Global（全域）都有可能提供設定的候選值。如果系統在解析時，沒有嚴格保護 agent scope 的優先權，顯示層就很可能會選到全域值，把區域設定給覆蓋掉。
強烈建議不要第一時間去動 production 的全域設定，這很可能會波及到其他正常運作的 Agent。請先用前面提到的三個 fixture 找出真正的問題點，再針對修正版進行驗證。