环境变量

进程环境选择数据目录，并可以提供 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：提供商名大写，连字符变成下划线。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。不需要密钥且上面没有找到时，解析以空密钥成功。需要密钥且每个来源都未命中时，启动报告提供商名、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 兼容的扫描根。工作区下的项目文件不使用此变量。见提示与指令和技能。