OpenClaw 驗證憑證設定指南：解析與除錯規則

處理 Auth 憑證常常讓人抓狂，有時候本地端跑得好好的，部署後卻因為 Token 過期或設定不對直接掛掉。為了讓你開發更順手，我們統一了憑證的處理邏輯，確保你在不同工具間看到的結果都是一致的。

這份文件定義了在以下工具中使用的標準憑證資格與解析語義：

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

目標是讓選擇時與執行時的行為保持一致。

穩定狀態碼 (Stable Reason Codes)

• ok
• missing_credential
• invalid_expires
• expired
• unresolved_ref

Token 憑證 (Token Credentials)

Token 憑證 (type: "token") 支援內聯的 token 以及 tokenRef（或兩者同時存在）。

資格規則 (Eligibility rules)

1. 當 token 與 tokenRef 同時缺失時，該 Token Profile 為無效。
2. expires 是選填項。
3. 如果有提供 expires，它必須是一個大於 0 的有限數字。
4. 如果 expires 無效（例如 NaN、0、負數、非有限數值或類型錯誤），該 Profile 會被標記為 invalid_expires 且不具備資格。
5. 如果 expires 的時間點已過去，該 Profile 會被標記為 expired 且不具備資格。
6. 使用 tokenRef 並不會跳過 expires 的驗證。

解析規則 (Resolution rules)

1. 解析器的語義在 expires 方面與資格規則一致。
2. 對於符合資格的 Profile，Token 內容可以從內聯數值或 tokenRef 中解析出來。
3. 無法解析的引用（Refs）會在 models status --probe 的輸出中產生 unresolved_ref。

OAuth SecretRef 策略防護 (OAuth SecretRef Policy Guard)

• SecretRef 輸入僅適用於靜態憑證。
• 如果 Profile 憑證是 type: "oauth"，則該 Profile 的憑證內容不支援 SecretRef 物件。
• 如果 auth.profiles.<id>.mode 設定為 "oauth"，系統會拒絕該 Profile 使用基於 SecretRef 的 keyRef 或 tokenRef 輸入。
• 違反此規則將導致啟動或重新載入 Auth 解析路徑時發生硬錯誤（Hard failures）。

相容舊版的訊息 (Legacy-Compatible Messaging)

為了確保腳本相容性，Probe 錯誤會保留第一行內容不變：

Auth profile credentials are missing or expired.

後續行數可能會加入對人類更友好的詳細資訊以及穩定的狀態碼。

想要快速完成設定嗎？試試我們的 AI Setup Assistant。

下一步

• 了解如何配置 Auth Profile
• 使用 models status 進行除錯
• 查看 API 認證最佳實踐
• 管理你的 Gateway 憑證