環境變數

行程環境選擇資料目錄，並可以提供 API 金鑰。它不替換 config.json 或 providers.json。

變數	含義
CRYSTAL_HOME	資料目錄，代替 ~/.crystal
<PROVIDER>_API_KEY	提供商名稱的預設金鑰變數
apiKeyEnvironment	可選的 providers.json 欄位，替換預設變數名
CRYSTAL_API_KEY	提供商需要金鑰且更早的變數都未設定時的共用回退
XDG_CONFIG_HOME	OpenCode 指令和技能回退的設定根。未設定時使用 ~/.config
PATH	由 bash 繼承。主機不會編造路徑

不要在命令列上傳遞秘密。它們會出現在行程清單中。

資料目錄

CrystalHome.Resolve 按此順序選擇根目錄：

1. 顯式根參數，當呼叫方傳入一個時。
2. CRYSTAL_HOME，當它已設定且不是空白時。該值經過 Path.GetFullPath，且不被修剪。
3. <user profile>/.crystal。

如果使用者設定檔目錄不可用，且前兩項都不適用，啟動擲出 The user profile directory is not available.

EnsureCreated 建立根目錄以及 sessions、logs、plugins 和 tools。其他已知檔案（config.json、providers.json、credentials.json 以及其餘檔案）在擁有它們的功能首次寫入時建立。

API 金鑰

對一個提供商，CredentialStore 按此順序解析金鑰，並在第一個非空白值處停止：

1. 該提供商上 apiKeyEnvironment 命名的環境變數（該欄位已設定時）。否則是 <NAME>_API_KEY，其中 NAME 是提供商名稱的大寫形式，連字號變為底線。deepseek 是 DEEPSEEK_API_KEY。my-provider 是 MY_PROVIDER_API_KEY。
2. 再次是派生的 <NAME>_API_KEY，當 apiKeyEnvironment 命名了別的名稱時。自訂名稱不會隱藏派生名稱。
3. CRYSTAL_API_KEY，僅當提供商需要 API 金鑰時。
4. providers.json 中的提供商 apiKey 欄位（已設定時）。
5. 資料目錄下 credentials.json 的鍵 <provider>.apiKey。

從環境讀取的值會被修剪。空或空白變數會被跳過，不視為已存在的金鑰。

requiresApiKey 對 ollama 協定預設為 false，對其他每個協定為 true。提供商不需要金鑰且上面沒有產生金鑰時，解析以空金鑰成功。它確實需要金鑰且每個來源都未命中時，啟動報告提供商名稱、providers.json 的 apiKey 形式、環境變數名稱和憑證檔案路徑。所選提供商沒有金鑰時，/model 讓目前模型保持不變。

apiKey 形式

上面的環境來源為空之前，不讀取 apiKey 欄位。接受三種形式：

形式	行為
字面文字	修剪後用作金鑰
{env:NAME}	讀取 NAME。缺失或空白時失敗，訊息為 Environment variable NAME is not set.
{file:path}	讀取整個檔案並修剪。~ 和 ~/... 展開為使用者設定檔。相對路徑位於資料目錄下，不是工作區。缺失檔案：API key file not found: <path>. 空檔案：API key file is empty: <path>.

{env:NAME} 獨立於 <PROVIDER>_API_KEY。秘密已經位於另一個變數時使用它。

從產品儲存金鑰會寫入 credentials.json，並在 Unix 上將檔案模式設為僅擁有者讀寫。儲存路徑不會把金鑰匯出到環境中。

XDG_CONFIG_HOME

指令發現和技能發現共用一條規則。如果 XDG_CONFIG_HOME 已設定且不是空白，該目錄就是設定根。否則根是 <user profile>/.config。

指令隨後在 Crystal 資料目錄中的檔案之後，尋找 <config>/opencode/AGENTS.md 作為全域回退。技能把 <config>/opencode 作為一個 OpenCode 相容的掃描根。工作區下的專案檔案不使用此變數。見提示與指令和技能。