憑證

不要把秘密放在工作區、本儲存庫或提交內容中。CrystalCode 從不把秘密寫入專案樹。

把持久 API 金鑰存在 ~/.crystal/credentials.json 中，按提供商名稱作為鍵。值是純文字。作業系統允許時，該檔案以僅擁有者權限建立。子行程不繼承此檔案。互動式安裝使用它。

行程環境變數覆寫該檔案。為單次啟動或向該行程注入金鑰的 CI 執行器設定一個。寫入 shell 啟動檔案的金鑰會被登入 shell 載入，包括產品為模型呼叫的命令啟動的登入 shell，而這些檔案常常可被擁有者以外的使用者讀取。

活動提供商的解析順序：

1. 行程環境（見下文）
2. 有效提供商定義上的 apiKey
3. ~/.crystal/credentials.json，按提供商名稱作為鍵

有效定義是 providers.json 中的提供商項目。該檔案不存在時，它是舊版 config.json.providers 欄位下的項目。providers.json 存在時，舊欄位不用於目錄或此次金鑰查找。見設定。

環境變數名稱，按順序：

1. 同一份定義上的 apiKeyEnvironment（已設定時）
2. 從提供商名稱派生的 <PROVIDER>_API_KEY（連字號變為底線；例如 DEEPSEEK_API_KEY、OPENAI_API_KEY、OPENROUTER_API_KEY）
3. CRYSTAL_API_KEY（共用回退）

提供商特定的變數優先於 CRYSTAL_API_KEY。

該定義上的 apiKey 可以是：

形式	含義
{env:NAME}	讀取命名的行程環境變數
{file:path}	讀取檔案（相對於 ~/.crystal，或絕對路徑；展開 ~）
字面字串	按原樣使用（共用檔案中應避免）

把秘密留在 providers.json 之外。留在本機的金鑰屬於 credentials.json。{env:NAME} 適合已經匯出該變數的啟動或 CI 作業。{file:path} 適合已經位於另一個僅擁有者檔案中的金鑰。

credentials.json 的形狀：

{
  "deepseek": {
    "apiKey": ""
  }
}

範例和任何可能被共用的檔案中，把值留空。把真正的秘密放在本機 credentials.json 中。

如果找不到金鑰，行程印出一條英文錯誤並以狀態 1 結束。它不印出秘密。