凭据

不要把秘密放进工作区、本仓库或提交。Crystal Code 从不把秘密写入项目树。

持久 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} 适合密钥已经在另一个仅所有者文件里。

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

示例和可能被共享的文件里把值留空。真正的秘密只放在本地 credentials.json。

找不到密钥时，进程打印一条英文错误并以状态 1 退出。它不打印秘密。