認證憑證語義

本文件定義以下各處使用的標準憑證資格與解析語意：

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

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

# 穩定的探測原因代碼

• ok
• excluded_by_auth_order
• missing_credential
• invalid_expires
• expired
• unresolved_ref
• no_model

# 權杖憑證

權杖憑證（type: "token"）支援內嵌 token 和/或 tokenRef。

# 資格規則

1. 當 token 和 tokenRef 都不存在時，權杖設定檔不符合資格。
2. expires 是選用項。
3. 如果有 expires，它必須是大於 0 的有限數字。
4. 如果 expires 無效（NaN、0、負數、非有限值或型別錯誤），設定檔不符合資格，原因為 invalid_expires。
5. 如果 expires 是過去時間，設定檔不符合資格，原因為 expired。
6. tokenRef 不會略過 expires 驗證。

# 解析規則

1. 解析器對 expires 的語意會符合資格語意。
2. 對於符合資格的設定檔，權杖材料可從內嵌值或 tokenRef 解析。
3. 無法解析的參照會在 models status --probe 輸出中產生 unresolved_ref。

# Agent 複製可攜性

Agent 驗證繼承是透過讀取穿透運作。當 Agent 沒有本機設定檔時，它 可以在執行階段從預設/主要 Agent 儲存解析設定檔，而無需 將秘密材料複製到自己的 auth-profiles.json。

明確複製流程（例如 openclaw agents add）使用此可攜性政策：

• 除非 copyToAgents: false，否則 api_key 設定檔可攜。
• 除非 copyToAgents: false，否則 token 設定檔可攜。
• oauth 設定檔預設不可攜，因為重新整理權杖可能是 單次使用或對輪替敏感。
• 提供者擁有的 OAuth 流程僅可在已知跨 Agent 複製 重新整理材料是安全的情況下，以 copyToAgents: true 選擇加入。

不可攜的設定檔仍可透過讀取穿透繼承使用，除非 目標 Agent 分別登入並建立自己的本機設定檔。

# 僅設定的驗證路由

具有 mode: "aws-sdk" 的 auth.profiles 項目是路由中繼資料，而非儲存的 憑證。當目標提供者使用 models.providers.<id>.auth: "aws-sdk" 或內建 Amazon Bedrock 預設 AWS SDK 路由時，這些項目有效。即使 auth-profiles.json 中沒有相符項目， 這些設定檔 ID 也可以出現在 auth.order 和工作階段 覆寫中。

不要將 type: "aws-sdk" 寫入 auth-profiles.json。如果舊版安裝 有這類標記，openclaw doctor --fix 會將它移至 auth.profiles，並 從憑證儲存中移除該標記。

# 明確驗證順序篩選

• 當某個提供者設定了 auth.order.<provider> 或驗證儲存順序覆寫時， models status --probe 只會探測仍保留在該提供者 已解析驗證順序中的設定檔 ID。
• 該提供者的已儲存設定檔若從明確順序中省略， 之後不會被默默嘗試。探測輸出會以 reasonCode: excluded_by_auth_order 和詳細資訊 Excluded by auth.order for this provider. 回報它。

# 探測目標解析

• 探測目標可以來自驗證設定檔、環境憑證或 models.json。
• 如果提供者有憑證，但 OpenClaw 無法為其解析可探測模型 候選項，models status --probe 會以 reasonCode: no_model 回報 status: no_model。

# 外部 CLI 憑證探索

• 外部 CLI 擁有的僅執行階段憑證，只會在 提供者、執行階段或驗證設定檔位於目前操作範圍內時， 或者該外部來源已有已儲存本機設定檔時才會被探索。
• 驗證儲存呼叫端應選擇明確的外部 CLI 探索模式： none 用於僅持久化/Plugin 驗證，existing 用於重新整理已 儲存的外部 CLI 設定檔，或 scoped 用於具體提供者/設定檔集合。
• 唯讀/狀態路徑會傳遞 allowKeychainPrompt: false；它們只使用以檔案為後端的 外部 CLI 憑證，且不會讀取或重用 macOS Keychain 結果。

# OAuth SecretRef 政策防護

• SecretRef 輸入僅適用於靜態憑證。
• 如果設定檔憑證是 type: "oauth"，該設定檔憑證材料不支援 SecretRef 物件。
• 如果 auth.profiles.<id>.mode 是 "oauth"，則會拒絕該設定檔中由 SecretRef 支援的 keyRef/tokenRef 輸入。
• 違規會在啟動/重新載入驗證解析路徑中造成硬性失敗。

# 舊版相容訊息

為了指令碼相容性，探測錯誤會保留第一行不變：

Auth profile credentials are missing or expired.

後續行可加入易懂的詳細資訊與穩定原因代碼。

# 相關

• 秘密管理
• 驗證儲存