2026 年 OpenClaw 首次 onboard 後仍異常：credentials、環境變數與模型供應商切換的最小閉環與分層排障手冊
onboard 把入門腳本跑通，不代表已達到可上線的穩定度：實際執行閘道的 Unix 使用者能否讀到同一個 ~/.openclaw/credentials/、systemd 的 EnvironmentFile 是否在守護行程啟動前就注入，以及模型 ID 前綴與目前選定的供應商是否一致，往往決定「CLI 可以 chat、閘道內卻 401／429」這種典型分叉。本文與《官方快速排障階梯》互補：該文先鎖定 RPC 與探測，本文鎖定憑證與供應商層；讀完若還要對齊連線與版本，請續看《pairing 斷開》《split brain》《Docker Compose 憑證與環境》。
目錄（TOC）
1. 三類分叉：HOME 漂移、空 credentials、供應商字串
HOME 漂移：你在終端機以使用者甲完成 onboard，寫入的是甲的家目錄；但 launchctl 或 systemd 卻以使用者乙啟動閘道，於是對甲而言 credentials 路徑存在，對乙卻是空的或根本不同路徑。這類問題在筆電多帳號、或 CI 與本機混用時特別常見。
空目錄誤判：~/.openclaw/credentials 資料夾存在，但裡面沒有任何金鑰檔案；doctor 有時只給較弱的提示，真正爆錯會拖到模型呼叫階段才以 401 呈現，讓人誤以為是「模型壞掉」而不是「沒載到金鑰」。
供應商前綴不一致：設定檔裡的模型字串與 openclaw models status 實際路由到的供應商不同，日誌會出現 provider mismatch 或類似簽章。此時若只改模型名稱而不改 credentials 檔名或環境變數前綴，會陷入「改 A 壞 B」的循環。
實務上先確認誰在跑閘道與環境變數與 JSON 誰覆蓋誰，再處理 429／通道無回覆時請讀《通道在線卻無回覆》。
- 先釐清執行閘道的 Unix 使用者，再談檔案權限與掛載。
- 再對齊環境變數與 JSON 設定的優先序與載入時機。
- 最後才拆429、節流與外掛雙開關，必要時回到官方階梯補
gateway probe。
2. 決策矩陣：API Key、OAuth、多供應商並存
下列矩陣協助決定該動檔案、環境變數或 OAuth；請維持單一真相來源，避免多處 API Key 互相矛盾造成「手動正常、服務讀舊值」。
| 維度 | API Key 檔案落盤 | OAuth／訂閱橋接 | 多供應商輪替 |
|---|---|---|---|
| 金鑰落點 | credentials 目錄＋chmod 600 | 權杖刷新與回呼 URL | 分檔或分環境變數前綴 |
| 守護行程友善度 | EnvironmentFile 明列路徑 | 刷新 job 須同一使用者 | 路由表要單一真相 |
| 排障順序 | 先 ls 再 doctor | 先 OAuth 日誌再模型 | 先 models status 再 channels |
3. How-to：onboard 後七步最小閉環
# 1) 確認閘道行程使用者與 HOME
ps aux | grep -i openclaw
echo "$HOME"
ls -la ~/.openclaw/credentials/- 把 User= 與 plist／unit 裡的 WorkingDirectory 寫進變更紀錄，避免口頭轉述遺漏。
- 對 credentials 檔案套用最小權限，並確認沒有被誤加入版本庫。
- 以同一個 shell 工作階段依序執行
openclaw status與openclaw gateway status，避免 PATH 或別名造成漂移。 - 變更環境變數後務必完整重啟閘道；部分環境下熱重載不會刷新已開啟的金鑰控制代碼。
- 切換供應商時只改最小差異：模型字串、路由區塊、credentials 檔名三處要一起對齊。
- 執行
openclaw doctor並保存已脫敏的輸出，方便事後稽核。 - 憑證層確認後，再依《官方階梯》補
gateway probe與channels探測收據。
# 2) systemd 示意：明確注入 OPENCLAW 家目錄
Environment=OPENCLAW_HOME=/home/oc/.openclaw4. 分層排障與日誌裡該搜尋的關鍵字
固定順序：openclaw status → openclaw gateway status → openclaw doctor → 日誌搜 401、403、429、credential、provider。RPC 健康卻無回覆時回到《通道在線卻無回覆》拆外掛雙開關。
split brain：gateway status --deep 若顯示 CLI 與服務 binary 路徑不一致，先修 PATH；which openclaw 與 unit 不同則先對齊《安裝途徑對照》再談 credentials。
5. 可引用資料：時間軸與工單欄位
工單建議附：執行使用者、credentials 檔名列表（可打碼）、doctor 摘要、模型字串一行、上次完整重啟時間；有 tarball／diff 請附雜湊。Docker 環境註明 uid 與卷映射，見 Docker Compose 文。
6. FAQ
問：Docker 裡 credentials 要怎麼掛載？答：請見《Docker Compose 憑證與環境》關於卷的 uid 對應與環境變數注入。
問：可以跳過 doctor 嗎？答：不建議；它會聚合多數低階錯誤，跳過往往只是把問題往後推。
7. 總結與遠端 Mac 託管收束
憑證層排通後，閘道才能在可重現環境穩定呼叫模型與通道。若要把全天候閘道與可稽核目錄做成預設，見 SFTPMAC 遠端 Mac。官方階梯與本文垂直互補，憑證未對齊前勿過度解讀 429。
多使用者 HOME 與筆電休眠仍可能造成「診斷正確卻抖動」，請把觀測時間窗寫進工單。