发车前检查：把 .env 挡在编码智能体上下文外

Agent 快速起步ZH2026-10-30

密钥为什么会掉进编码智能体的上下文

编码智能体的工作方式，是把仓库文件、终端输出和工具返回值整段读进上下文，再交给模型处理。只要 .env 文件留在工作目录里，它就可能被一次普通的“读取全部配置”操作整份带走。

真正的麻烦不在于智能体读了文件，而在于这些内容会随请求一起发往模型服务端。请求日志、会话回放、错误报告都可能留下副本；上下文本身还会被压缩、被整理成摘要，摘要里同样可能保留密钥片段。一旦密钥进了上下文，再想从历史记录里彻底抹掉，基本做不到。

还有几条容易被忽略的旁路：智能体跑测试时打印的调试输出、被无意加入版本控制的配置文件、脚本里写死的接口地址，以及工具返回的完整响应体。更麻烦的是提示词注入，仓库里任何一段第三方代码都可能诱导智能体把环境变量打印出来，于是密钥再次回到上下文里，甚至出现在给你看的总结中。

先明确一点：密钥泄漏的后果往往不是立刻被利用，而是长期躺在某处日志里等待被翻出来。所以判断标准不是“这次会不会出事”，而是“密钥有没有机会进入上下文”。

四种密钥管理做法并排比较

把常见做法摆在一起，差异就很明显。下面四条路线按隔离程度从低到高排列。

直接把 .env 放在仓库目录：上手最快，也最省事，但智能体默认拥有读取权限，密钥会随文件内容进入上下文，属于风险最高的一种。
把密钥写进提示词或智能体配置：等于主动复制多份密钥，配置文件本身又会被后续会话反复读到，这种做法应当直接排除。
把 .env 移出仓库，进程启动时注入环境变量：智能体看不到文件内容，只在运行时拿到需要的变量，是可落地的默认方案。
用系统钥匙串或密钥管理器，配合短期令牌按需取用：隔离最彻底，适合多人协作和高权限凭据，代价是多一层取用与轮换流程。

并排看完可以这样判断：凡是让密钥以文件形式待在智能体可达目录里的做法，都要换掉；凡是让密钥以字符串形式出现在提示词里的做法，一律不做。剩下两条路线里，环境变量注入的改动成本最低，适合绝大多数单人或小团队仓库；密钥管理器则更适合已经有运维体系、需要审计和定期轮换的场景。

改动成本也要算进去。有人担心移出 .env 会让本地开发变复杂，其实多数项目只需要在启动脚本里读一次环境变量，或者在 shell 配置里导出一次即可。相比事后清理泄漏密钥、逐个作废重发的返工，这点成本可以忽略。

接口密钥在代理链路上的落点

无论选哪种落地方案，密钥最终都要落到调用模型的那一层。SwiftRelay 是一个按 token 计费的模型中转服务，覆盖 Claude、GPT、Gemini、DeepSeek、Kimi、GLM、Qwen、Grok 等模型，可用于 Claude Code、Codex、Gemini CLI，以及任何兼容 OpenAI 的 SDK。

接入只需要一组接口密钥。Claude Code 和 Gemini CLI 直接填接口地址 https://api.fastapirelay.com，OpenAI 系的 SDK 在后面补上 /v1。新账户会拿到一小笔赠金，邀请朋友还能获得其充值金额的 14%。

实践上建议分层存放：只让中转密钥进环境变量，项目自己的数据库口令、第三方令牌继续留在各自的密钥管理器里。这样即使某次会话的上下文被完整导出，泄漏面也只覆盖一个可以随时作废重发的中转密钥，而不是整套系统凭据。

另外建议给不同环境各开一份密钥，本地调试、持续集成、线上服务分开使用。哪一份出问题，就只轮换哪一份，排查范围会小很多。

绿灯前的逐项检查

动手改配置之前，先把下面几项过一遍。

确认 .env 没有被版本控制跟踪，仓库历史里也没有提交过真实密钥。
把 .env 移到仓库之外，或者放进智能体明确不读的目录。
在智能体的忽略规则里显式排除配置文件、日志目录和密钥目录。
检查提示词、智能体配置和脚本里有没有写死的密钥字符串。
为不同用途申请不同密钥，中转密钥单独一份，方便单独作废。
限制工具调用的权限范围，只放行本次任务真正需要的能力。
明确要求智能体不要在输出里复述任何环境变量的取值。
跑一次会话回放，检查上下文里是否出现过密钥片段。
把这些规则写进仓库里的贡献说明，让后来的人不必重新踩坑。

这一轮做完，上下文里剩下的应该只有代码、报错和你的意图描述。任何一段凭空出现的凭据，都说明前面还有漏网的地方，回到上面的对照表再查一遍。