← Blog

使用 macOS Keychain 管理 API Key

在本地开发中,把 API Key 直接写进 .env 或代码里并不安全。macOS 自带的 security 命令行工具可以直接与系统钥匙串(Keychain)交互,把密钥加密保存,避免明文暴露在配置文件中。

存储密钥

security add-generic-password -s "agents" -a "OPENAI_API_KEY" -w "sk-proj-xxxxxxxxxx"
  • -s(Service):服务或命名空间,例如项目名 agents;
  • -a(Account):密钥标识,例如 OPENAI_API_KEY;
  • -w(Password):实际要保存的密钥值。

如果直接把 API Key 写在命令里,它可能会被记录到终端 shell 历史中。更安全的做法是省略 -w 后面的值:

security add-generic-password -s "myapp" -a "OPENAI_API_KEY" -w

执行后,security 会以隐藏输入的方式提示你输入或粘贴密钥,这样密钥就不会留在命令历史中。

读取密钥

要从钥匙串中读回密钥,可以使用 find-generic-password:

security find-generic-password -s "myapp" -a "OPENAI_API_KEY" -w

末尾的 -w 让命令只输出原始的密钥值,而不是完整的元数据信息。

自动加载为环境变量

如果希望本地脚本或开发服务器自动获得这个密钥,可以把读取命令写入 shell 配置文件,例如 ~/.zshrc。

export OPENAI_API_KEY=$(security find-generic-password -s "myapp" -a "OPENAI_API_KEY" -w)

删除条目

security 工具不允许直接用 add-generic-password 覆盖已有条目。如果 API Key 轮换或变更,需要先删除旧条目,再重新添加。

security delete-generic-password -s "myapp" -a "OPENAI_API_KEY"